From aa16021add5841402bae8313f5b60a710ccaf75e Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 22 Sep 2026 01:07:05 +1000 Subject: [PATCH] fix(prdlint): close three gaps that let a nested document through The playbook engine PRD passed the guard while carrying a whole second PRD inside a list item. Three separate blind spots, each with a test: A second **Status:** field was invisible twice over. lintStatus returned on the first status it found, and its pattern was anchored at ^, so an indented one inside a list item was never read. It now checks every status line and reports a second one as what it is: a nested document that belongs in its own file. dated-status matched verb-then-date only, so "(2026-08-22, decided)" and "surveyed 2026-09-03" read as clean. It matches either order now, plus the words that turn a date into provenance for a finding rather than a fact. Rules were line-scoped, so a citation broken across a line wrap was two innocent lines: "...Dedup section, lines" then "155-159, the rule". Each rule now also tests the line joined to its successor, reporting the line the match starts on. --- tools/prdlint/lint.go | 40 ++++++++++++++++++++++++++++++-------- tools/prdlint/lint_test.go | 26 +++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 8 deletions(-) diff --git a/tools/prdlint/lint.go b/tools/prdlint/lint.go index eca88ef7f..4abd07340 100644 --- a/tools/prdlint/lint.go +++ b/tools/prdlint/lint.go @@ -26,6 +26,10 @@ type rule struct { remedy string } +// datedVerbs are the words that turn a date into a status claim. A date on +// its own is provenance; a date next to one of these is a progress report. +const datedVerbs = `(status|resolved|settled|decided|agreed|approved|supersedes|superseded|withdrawn|shipped|landed|complete|completed|done|wired|verified|corrected|confirmed)` + // rules is the closed set. Each pattern targets a shape that decays, never a // topic: a PRD may discuss phases, dates and shipped work, and says so without // asserting the state of the tree on the day it was written. @@ -37,7 +41,7 @@ var rules = []rule{ }, { name: "dated-status", - pattern: regexp.MustCompile(`(?i)\b(status|resolved|settled|decided|agreed|approved|supersedes|superseded|withdrawn|shipped|landed|complete|completed|done|wired|verified|corrected|confirmed)\b[^.\n]{0,30}\b20\d\d-\d\d-\d\d\b`), + pattern: regexp.MustCompile(`(?i)\b` + datedVerbs + `\b[^.\n]{0,30}\b20\d\d-\d\d-\d\d\b|\b20\d\d-\d\d-\d\d\b[^.\n]{0,30}\b` + datedVerbs + `\b|\b(surveyed|queried|measured|checked|reviewed|correction|per [A-Z]\w+)\b[^.\n]{0,20}\b20\d\d-\d\d-\d\d\b`), remedy: "drop the date and the state. A PRD says what the design is; the tracker and git history say when it happened.", }, { @@ -79,8 +83,10 @@ var codeFence = regexp.MustCompile("^\\s*```") // 2026-09-22" smuggle a dated status into the one line the rules did not read. var exemptHeader = regexp.MustCompile(`^\*\*Date:\*\*\s*20\d\d-\d\d-\d\d\s*$|^\*\*Status:\*\*\s*(Draft|Approved|Finalised)\s*$`) -// statusField matches the document's own status line, whatever it holds. -var statusField = regexp.MustCompile(`^\*\*Status:\*\*\s*(.*)$`) +// statusField matches a status line anywhere in the document, indented or +// not. The indent matters: a whole second PRD nested inside a list item +// carried its own indented status, and an anchored pattern never saw it. +var statusField = regexp.MustCompile(`^\s*\*\*Status:\*\*\s*(.*)$`) // statuses is the closed set from RULES.md. A status outside it is how a // progress report gets into the one field the rules cannot read: "Implemented @@ -102,7 +108,8 @@ func LintDocument(name, content string) []Finding { func Lint(name, content string) []Finding { var findings []Finding inFence := false - for i, line := range strings.Split(content, "\n") { + lines := strings.Split(content, "\n") + for i, line := range lines { if codeFence.MatchString(line) { inFence = !inFence continue @@ -113,6 +120,13 @@ func Lint(name, content string) []Finding { for _, r := range rules { if r.pattern.MatchString(line) { findings = append(findings, Finding{File: name, Line: i + 1, Rule: r.name, Text: line}) + continue + } + // Prose wraps, so a citation can straddle a line break ("...lines" + // / "155-159, ..."). Re-test the pair, reporting the line the + // match starts on. + if i+1 < len(lines) && !inFence && r.pattern.MatchString(line+" "+strings.TrimSpace(lines[i+1])) { + findings = append(findings, Finding{File: name, Line: i + 1, Rule: r.name, Text: line + " " + strings.TrimSpace(lines[i+1])}) } } } @@ -122,15 +136,25 @@ func Lint(name, content string) []Finding { // lintStatus checks the one status line RULES.md requires, since a missing or // free-text status is not a line-level violation any pattern above would see. func lintStatus(name, content string) []Finding { + var findings []Finding + var seen int for i, line := range strings.Split(content, "\n") { m := statusField.FindStringSubmatch(line) if m == nil { continue } - if statuses[strings.TrimSpace(m[1])] { - return nil + seen++ + switch { + case seen > 1: + // One document, one status. A second one means a second document + // has been pasted inside this one, which is the real defect. + findings = append(findings, Finding{File: name, Line: i + 1, Rule: "status", Text: "second **Status:** field; a nested document belongs in its own file"}) + case !statuses[strings.TrimSpace(m[1])]: + findings = append(findings, Finding{File: name, Line: i + 1, Rule: "status", Text: line}) } - return []Finding{{File: name, Line: i + 1, Rule: "status", Text: line}} } - return []Finding{{File: name, Line: 1, Rule: "status", Text: "no **Status:** field"}} + if seen == 0 { + return []Finding{{File: name, Line: 1, Rule: "status", Text: "no **Status:** field"}} + } + return findings } diff --git a/tools/prdlint/lint_test.go b/tools/prdlint/lint_test.go index 9dac19b45..ef781c389 100644 --- a/tools/prdlint/lint_test.go +++ b/tools/prdlint/lint_test.go @@ -36,6 +36,16 @@ func TestLintRejectsSessionBoundWriting(t *testing.T) { doc: "Verified directly, 2026-09-03: the interface has no send method.", rule: "dated-status", }, + { + name: "date before the verb", + doc: "`event-sources-and-reactions.md` (2026-08-22, decided) ruled that", + rule: "dated-status", + }, + { + name: "dated survey", + doc: "### Candidate comparison (surveyed 2026-09-03, pkg.go.dev)", + rule: "dated-status", + }, { name: "dated settlement", doc: "### The two decisions (settled 2026-09-19, decided by position)", @@ -114,6 +124,7 @@ func TestLintRequiresACanonicalStatus(t *testing.T) { {"free text", "# T\n\n**Status:** Implemented (wiring landed)\n", true}, {"status with a changelog", "# T\n\n**Status:** Ratified (rev. 2e). Rev. 2e adds a lookup\n", true}, {"missing entirely", "# T\n\nBody.\n", true}, + {"a nested document's indented status", "# T\n\n**Status:** Draft\n\n1. Item\n\n **Status:** Draft\n", true}, } { t.Run(tc.name, func(t *testing.T) { var got bool @@ -129,6 +140,21 @@ func TestLintRequiresACanonicalStatus(t *testing.T) { } } +// TestLintCatchesACitationSplitAcrossALineBreak: prose wraps, and a +// line-scoped rule saw "lines" and "155-159" as two innocent lines. +func TestLintCatchesACitationSplitAcrossALineBreak(t *testing.T) { + doc := "never swallowed as a log line (this document's Dedup section, lines\n155-159, the drop-and-report rule)." + var got bool + for _, f := range Lint("x.md", doc) { + if f.Rule == "line-citation" { + got = true + } + } + if !got { + t.Fatal("no line-citation finding for a citation split across a line break") + } +} + // TestLintSkipsFencedBlocks: a code listing may legitimately contain a line // reference or a status string as the content being specified. func TestLintSkipsFencedBlocks(t *testing.T) {