From 7499e5559e06d2a139a7bb4db236c072d2c2c753 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 22 Sep 2026 00:21:27 +1000 Subject: [PATCH] build(docs): gate docs/prds against session-bound writing A PRD states a decision, a requirement, a constraint or evidence. Those survive the code moving underneath them. A line number, a progress report or a dated status claim does not: it is true on the day it is written and silently wrong a month later, while still reading as authoritative. prdlint rejects five shapes: file:line citations (including a document citing its own line numbers), dated status claims, progress reports on the work being designed, phase-completion narration, and records of how a finding was produced. Each finding names the file, line, rule and fix. The rules target decay, not subject matter. A PRD may describe a phased plan, name a dependency that exists, and carry its own Status and Date header fields; what it may not do is assert the state of the tree on the day it was written. Fenced blocks are skipped, since a listing may specify a line reference as its literal content. Wired into task check next to docs:check. A sweep alone would not stop the class recurring. --- Taskfile.yml | 15 ++++++ docs/prds/RULES.md | 5 ++ tools/prdlint/lint.go | 89 +++++++++++++++++++++++++++++++ tools/prdlint/lint_test.go | 105 +++++++++++++++++++++++++++++++++++++ tools/prdlint/main.go | 101 +++++++++++++++++++++++++++++++++++ 5 files changed, 315 insertions(+) create mode 100644 tools/prdlint/lint.go create mode 100644 tools/prdlint/lint_test.go create mode 100644 tools/prdlint/main.go diff --git a/Taskfile.yml b/Taskfile.yml index a53dafe58..341b76820 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -67,6 +67,20 @@ tasks: cmds: - go -C tools run -mod=readonly ./docsgen check --repo-root .. + docs:prds: + desc: Reject session-bound writing in docs/prds + summary: | + A PRD states a decision, a requirement, a constraint or evidence. Those + survive the code moving underneath them. A line number, a progress + report or a dated status claim does not: it is true on the day it is + written and silently wrong a month later, while still reading as + authoritative. The tracker records progress; the PRD records the design. + + Each finding names the file, the line, the rule and the fix. There is no + --fix: the replacement is a judgement about what the sentence was for. + cmds: + - go -C tools run -mod=readonly ./prdlint --repo-root .. + vet: desc: Run go vet cmds: @@ -367,6 +381,7 @@ tasks: - task: proto:lint - task: proto:check - task: docs:check + - task: docs:prds - task: vet - task: lint - task: build diff --git a/docs/prds/RULES.md b/docs/prds/RULES.md index 3a7ef87d2..2190bc6d7 100644 --- a/docs/prds/RULES.md +++ b/docs/prds/RULES.md @@ -26,6 +26,11 @@ These rules apply to every file in `docs/prds/`. findings; do not copy their prose. - Before requesting approval, review every sentence for complexity, repetition, and unsupported scope. +- Write nothing whose truth expires. No `file.go:123` citations (cite the file + and the symbol), no progress reports on the work being designed, no dated + status claims, and no record of how a finding was produced. A phased plan is + durable design; which phase is finished is not. `task docs:prds` enforces + this. - Every PRD carries one of three statuses. `Draft` until the maintainer explicitly approves it, `Approved` once they have and while the work is being built, `Finalised` when the work is complete. A finalised PRD does not change; diff --git a/tools/prdlint/lint.go b/tools/prdlint/lint.go new file mode 100644 index 000000000..63b68cfba --- /dev/null +++ b/tools/prdlint/lint.go @@ -0,0 +1,89 @@ +package main + +import ( + "fmt" + "regexp" + "strings" +) + +// Finding is one rule violation, addressed the way an editor reads it. +type Finding struct { + File string + Line int + Rule string + Text string +} + +func (f Finding) String() string { + return fmt.Sprintf("%s:%d: %s: %s", f.File, f.Line, f.Rule, strings.TrimSpace(f.Text)) +} + +// rule is one forbidden shape. Each rejects writing whose truth expires while +// the sentence around it still reads as current. +type rule struct { + name string + pattern *regexp.Regexp + remedy string +} + +// 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. +var rules = []rule{ + { + name: "line-citation", + pattern: regexp.MustCompile(`\.(go|md|ya?ml|toml|proto|ts|js|sql):\d+|\blines? \d+(-\d+)?\b`), + remedy: "cite the file and the symbol, not the line. Line numbers move on the next edit above them and the stale citation still reads as authoritative. This covers a document citing its own line numbers.", + }, + { + name: "dated-status", + pattern: regexp.MustCompile(`(?i)\b(status|resolved|settled|decided|agreed|approved|shipped|landed|complete|completed|done|wired|verified|corrected|confirmed)\b[^.\n]{0,30}\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.", + }, + { + name: "progress-claim", + pattern: regexp.MustCompile(`(?i)\b(not yet|already|now|currently|today)\s+(wired|built|implemented|shipped|landed|complete)\b|\bis (now|already) \w+ed\b|\bready to (implement|design|build)\b|\bas of (today|this writing)\b`), + remedy: "state the design, not its build state. \"X is not yet wired\" is true for one week and misleading afterwards. Naming a dependency that exists is evidence and stays; reporting progress on the work this document designs does not.", + }, + { + name: "phase-progress", + pattern: regexp.MustCompile(`(?i)\bphases?\s+\d[^.\n]{0,40}\b(complete|completed|done|shipped|landed|in progress|underway|remaining)\b|\b(complete|completed|done|shipped|landed|in progress)\b[^.\n]{0,20}\bphases?\s+\d`), + remedy: "a phased plan is durable design; which phase is finished is not. Name the phases, not their state.", + }, + { + name: "session-artefact", + pattern: regexp.MustCompile(`(?i)\b(crew investigation|investigation pass|not committed|caught in review|this session|at time of writing|in this session)\b`), + remedy: "how the finding was produced is not design. State what is true and the evidence for it.", + }, +} + +// codeFence tracks fenced blocks so a rule never fires on quoted sample output +// or a code listing, where a line number or a status string may be the literal +// content being specified. +var codeFence = regexp.MustCompile("^\\s*```") + +// headerField matches the leading metadata block's own fields. A PRD records +// its own status and date there by design (RULES.md gives three statuses), so +// those lines are the one place a date and a status belong. +var headerField = regexp.MustCompile(`^\*\*(Status|Date|Parent|Blocked on|Supersedes|Superseded by):\*\*`) + +// Lint reports every rule violation in one document. +func Lint(name, content string) []Finding { + var findings []Finding + inFence := false + for i, line := range strings.Split(content, "\n") { + if codeFence.MatchString(line) { + inFence = !inFence + continue + } + if inFence || headerField.MatchString(line) { + continue + } + for _, r := range rules { + if r.pattern.MatchString(line) { + findings = append(findings, Finding{File: name, Line: i + 1, Rule: r.name, Text: line}) + } + } + } + return findings +} diff --git a/tools/prdlint/lint_test.go b/tools/prdlint/lint_test.go new file mode 100644 index 000000000..dfbe6fbf8 --- /dev/null +++ b/tools/prdlint/lint_test.go @@ -0,0 +1,105 @@ +package main + +import "testing" + +// TestLintRejectsSessionBoundWriting covers each rule's triggering shape and a +// nearby sentence it must not fire on, so a pattern tightened later cannot +// quietly stop catching the thing it exists for. +func TestLintRejectsSessionBoundWriting(t *testing.T) { + for _, tc := range []struct { + name string + doc string + rule string + }{ + { + name: "line citation", + doc: "The pin happens in `internal/daemon/daemon.go:1485`.", + rule: "line-citation", + }, + { + name: "markdown line citation", + doc: "The rule is stated in `event-sources-and-reactions.md:61-63`.", + rule: "line-citation", + }, + { + name: "self-referential line range", + doc: "See this document's Dedup section, lines 155-159.", + rule: "line-citation", + }, + { + name: "dated status heading", + doc: "**Status 2026-09-05: resolved** per the decision below.", + rule: "dated-status", + }, + { + name: "dated verification", + doc: "Verified directly, 2026-09-03: the interface has no send method.", + rule: "dated-status", + }, + { + name: "dated settlement", + doc: "### The two decisions (settled 2026-09-19, decided by position)", + rule: "dated-status", + }, + { + name: "progress claim", + doc: "The coordinator is not yet wired into production task intake.", + rule: "progress-claim", + }, + { + name: "readiness claim", + doc: "Forge is ready to implement once the ledger lands.", + rule: "progress-claim", + }, + { + name: "phase progress", + doc: "Phase 2 is complete and Phase 3 starts next.", + rule: "phase-progress", + }, + { + name: "session artefact", + doc: "Grounded by a crew investigation pass.", + rule: "session-artefact", + }, + } { + t.Run(tc.name, func(t *testing.T) { + findings := Lint("x.md", tc.doc) + if len(findings) == 0 { + t.Fatalf("Lint(%q) found nothing, want %s", tc.doc, tc.rule) + } + if findings[0].Rule != tc.rule { + t.Fatalf("rule = %q, want %q", findings[0].Rule, tc.rule) + } + }) + } +} + +// TestLintAcceptsDurableWriting: the rules target decay, not subject matter. A +// PRD may name a file, describe a phased plan, and carry its own status header. +func TestLintAcceptsDurableWriting(t *testing.T) { + for _, tc := range []struct{ name, doc string }{ + {"file without a line", "The pin happens in `internal/daemon/daemon.go`, in `Daemon.resolveWorkflowID`."}, + {"phases as design", "Phase 1 extracts the State Store. Phase 2 extracts the Gateway."}, + {"status header field", "**Status:** Draft"}, + {"date header field", "**Date:** 2026-09-03"}, + {"blocked-on header field", "**Blocked on:** `archie-core-t2db.24`"}, + {"a decision that names a date format", "Timestamps are stored as 2026-09-03 in the ledger."}, + {"bead id as a pointer", "Resolves `archie-core-t2db.19`; supersedes the earlier shape."}, + {"a dependency that exists is evidence", "`channels.Channel` already exists, so the position reuses it."}, + } { + t.Run(tc.name, func(t *testing.T) { + if findings := Lint("x.md", tc.doc); len(findings) != 0 { + t.Fatalf("Lint(%q) = %v, want no findings", tc.doc, findings) + } + }) + } +} + +// TestLintSkipsFencedBlocks: a code listing may legitimately contain a line +// reference or a status string as the content being specified. +func TestLintSkipsFencedBlocks(t *testing.T) { + doc := "Before.\n\n```\ninternal/daemon/daemon.go:1485\n```\n\nAfter." + if findings := Lint("x.md", doc); len(findings) != 0 { + t.Fatalf("Lint = %v, want no findings inside a fence", findings) + } +} diff --git a/tools/prdlint/main.go b/tools/prdlint/main.go new file mode 100644 index 000000000..c5141da11 --- /dev/null +++ b/tools/prdlint/main.go @@ -0,0 +1,101 @@ +// Command prdlint rejects session-bound writing in docs/prds. +// +// A PRD states a decision, a requirement, a constraint, or evidence +// (docs/prds/RULES.md). Those survive the code moving underneath them. A line +// number, a progress report, or a dated status claim does not: it is true on +// the day it is written and silently wrong a month later, while still reading +// as authoritative. The tracker records progress; the PRD records the design. +package main + +import ( + "errors" + "flag" + "fmt" + "io" + "io/fs" + "os" + "path/filepath" + "sort" + "strings" +) + +// defaultDir is the directory prdlint governs, relative to the repository root. +const defaultDir = "docs/prds" + +func main() { + flags := flag.NewFlagSet("prdlint", flag.ContinueOnError) + flags.SetOutput(io.Discard) + repoRoot := flags.String("repo-root", "..", "path to the Archie repository root") + dir := flags.String("dir", defaultDir, "directory to lint, relative to the repository root") + if err := flags.Parse(os.Args[1:]); err != nil { + fmt.Fprintf(os.Stderr, "prdlint: %v\n", err) + os.Exit(2) + } + if extra := flags.Args(); len(extra) > 0 { + fmt.Fprintf(os.Stderr, "prdlint: unexpected argument %q\n", extra[0]) + os.Exit(2) + } + + findings, err := lintDir(filepath.Join(*repoRoot, *dir)) + if err != nil { + fmt.Fprintf(os.Stderr, "prdlint: %v\n", err) + os.Exit(2) + } + if len(findings) == 0 { + fmt.Printf("prdlint: %s carries no session-bound writing\n", *dir) + return + } + for _, f := range findings { + fmt.Fprintln(os.Stderr, f.String()) + } + fmt.Fprintf(os.Stderr, "\nprdlint: %d finding(s). A PRD outlives the code it describes:\n%s\n", + len(findings), strings.Join(remedies(findings), "\n")) + os.Exit(1) +} + +// lintDir lints every Markdown file in dir, skipping RULES.md: it is the rule +// text itself and quotes the shapes the rules forbid. +func lintDir(dir string) ([]Finding, error) { + entries, err := os.ReadDir(dir) + if errors.Is(err, fs.ErrNotExist) { + return nil, fmt.Errorf("%s does not exist", dir) + } + if err != nil { + return nil, err + } + + var findings []Finding + names := make([]string, 0, len(entries)) + for _, e := range entries { + if e.IsDir() || filepath.Ext(e.Name()) != ".md" || e.Name() == "RULES.md" { + continue + } + names = append(names, e.Name()) + } + sort.Strings(names) + + for _, name := range names { + data, err := os.ReadFile(filepath.Join(dir, name)) + if err != nil { + return nil, err + } + findings = append(findings, Lint(name, string(data))...) + } + return findings, nil +} + +// remedies renders each triggered rule's fix once, in rule order, so the +// output ends with instructions rather than repeating them per finding. +func remedies(findings []Finding) []string { + seen := map[string]bool{} + var out []string + for _, r := range rules { + for _, f := range findings { + if f.Rule == r.name && !seen[r.name] { + seen[r.name] = true + out = append(out, " "+r.name+": "+r.remedy) + } + } + } + return out +}