Put the documentation under its own linter — a per‑file line budget that only ratchets down, an index requirement and a real‑path check — which found six of nine plans marked done while carrying unchecked boxes, and fourteen commit‑gating tasks named in no document.
Work carried out: 2025
Situation. The repository governs itself with written instructions — twenty‑five documents covering the quality policy, the design system, accessibility, print, metadata, translation and git. Instructions have a specific decay pattern: they get longer, they drift from the code, they start referring to files that moved, and at some size they stop being read. An unread rule is not a rule.
Task. The documentation needed the same treatment as the code — a linter with limits that fail rather than advise.
Action. Eight policies, each mechanical. A hard ceiling on document length and a softer one that warns. A per‑file line budget that only ever ratchets downward, so a document can shrink and cannot grow back. An index requirement above a threshold, and a section index above a smaller one. A location rule about which document owns which subject. Link validity. Plan honesty — the status a plan claims must match its own checkboxes. A rule that every task gating a commit is named in some document. And a real‑path check, that every directory‑qualified path and every code symbol a document names actually exists. The first run was the argument for the whole exercise: six plans marked done while carrying unchecked boxes, fourteen tasks gating every commit and named in no document at all, three broken links, one orphaned document, and three dead paths across five documents. The budget then refused its own author — writing the summary of this work into the development document pushed it past its limit, which is how a separate document came to exist, which is the policy working exactly as intended.
Result. Twenty‑five documents totalling about 2,568 effective lines, each under a budget that cannot grow, with every path and symbol they name checked against the tree. The uncomfortable finding is the one worth repeating: fourteen checks were gating every single commit while appearing in no document, so the rules the machine enforced and the rules the humans read had already come apart.