bdeshiandClaude Opus 5
ec6e9838f0
docs/content-model.md opens with "Engine specification". It is also where the rule lives that a leading underscore makes a file unaddressable — and the human who owns this site did not know that rule, because nothing in this repository is addressed to an author. Twelve documents named docs/ while being exclusively about building the parser is a signpost pointing at the wrong room. Naming the directory for its audience makes the gap visible instead of hiding it. docs/ is now reserved and deliberately absent: an empty docs/ is an honest statement that end-user documentation does not exist, where docs/ full of parser specs was a claim that it did. HARNESS.md stays at the root. Root holds the three entry points — README.md for a human, CLAUDE.md for an agent, HARNESS.md for whoever maintains the machine — and harness/README.md is the map of the directory, so moving the guide inside would have collided with it for nothing. Mechanical and wide: 100 path references across 24 files. Every verify.sh gate that names a doc by path, the directory lists the dangling-path and ADR-number gates scan, surface.sh's output target, the Makefile, CLAUDE.md's read order, the skill, four commands, and two Go package comments. A first pass with a shell loop silently edited only four files and the rest still said docs/; the fix was to write the file list out and check the remaining count was zero rather than trust the loop's exit status. No rule, threshold, gate or obligation moved — this is a rename, and the gates demonstrated it twice: they stayed green on the new paths, and the ADR-number gate caught ADR-0082 before the entry existed. Deferred, both on the human's call: the end-user documentation site itself, which wants its own decision about where it lives and whether its claims are gated; and moving examples/ under docs/, since demo-site is a live site root that verify.sh, the coverage test and make demo all point at, and moving it would couple a rename to a design nobody has made. 31 files, +146/-106. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2.4 KiB
2.4 KiB
description
| description |
|---|
| Reconcile the docs against the actual code and report drift |
Reconcile documentation with reality. The code is the truth; the docs are the suspects.
- Inventory the actual Go files, their line counts, and the non-stdlib dependencies in
go.mod. - Compare against
harness/state.md: inventory rows, counters, latent items. Recount the counters from the code — number of render transforms, routing cases, views, output formats, extensions — rather than trusting the recorded numbers. - Check
harness/architecture.mdSTATUS lines: has a primitive become real, or is one described as live when it is not built? - Check
harness/content-model.mdagainst what the parser actually accepts. It describes today's behaviour and carries no markers, so every sentence in it is a claim to test. Frontmatter fields the code reads but the doc omits are drift; fields the doc promises but the code ignores are worse drift. Worst, and the kind that has actually shipped: a subcommand, flag or gate the doc describes in the present tense that no code dispatches. The frontmatter table is the exception — it is the accepted format, andstate.mdnames which of its keys the parser lifts. - Check
scripts/allowed-deps.txtagainstgo.mod. - Look for facts stated in two docs. Delete one, link to the other.
- Run
./scripts/verify.sh --listand check every doc sentence claiming a gate against it. A doc that says "verify.shfails on X" where no such gate exists is the most damaging drift there is: it reads as enforcement and is decoration. - Check the reverse too — a gate in the list that no doc explains. Either document it or delete it.
- Follow every cross-doc citation of a section ("see
roadmap.mdGovernors", "CLAUDE.md§6") and confirm the heading exists. Whole sections have gone missing while another doc still cited them.
Scope: the docs listed above and nothing else. Do not open ideas/ or reference/ —
they describe proposals and facts, never the state of the code, so they cannot be drifted against
it. verify.sh already checks their indexes mechanically.
Then:
- Fix the docs. Doc-only diff; no code changes in this pass, no matter what you find.
- Anything in the code that contradicts an ADR: report it, do not silently document it as correct. A drifted invariant is a bug, not a new decision.
- Report drift found, drift fixed, and anything that needs a human decision.