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.
This commit is contained in:
sam committed 2026-09-22 01:07:05 +10:00
1 parent f600eb01aa
commit aa16021add
2 files changed
+58 -8

No files matched your search

+32 -8
View File
@@ -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
}
+26
View File
@@ -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) {