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:
1 parent
921cd1d559
commit
7499e5559e
5 files changed
+315
No files matched your search
@@ -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
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
Reference in new issue
Block a user