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.
This commit is contained in:
sam committed 2026-09-22 00:21:27 +10:00
1 parent 921cd1d559
commit 7499e5559e
5 files changed
+315

No files matched your search

+15
View File
@@ -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
+5
View File
@@ -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;
+89
View File
@@ -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
}
+105
View File
@@ -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)
}
}
+101
View File
@@ -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
}