Claude Opus 5andbdeshi
7f9ac3c412
The verified-against sha could only ever be wrong. A commit cannot name itself,
so the line had to be written after the commit it described, which forced a
trailing `state:` commit every time — against conventions.md, which has always
said code, test, state.md row and ADR belong in one commit. Folding those
trailing commits away then left the sha naming a commit that no longer existed.
backup/pre-fold shows the pattern, and 8905686 is the commit that had to name
the survivor afterwards.
Git already knows when each file last changed. The gate now compares the last
commit touching docs/state.md against the last touching a .go file, and the
line is gone. Same intent, nothing to maintain, and no rewrite can invalidate it.
Also records two commit rules the human stated this session: state.md never gets
a commit of its own, and a minor change asked for just after a commit is amended
into it while it is unpushed rather than accumulating as noise.
2.1 KiB
2.1 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
docs/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
docs/architecture.mdSTATUS lines: has a primitive become real, or is one described as live when it is not built? - Check
docs/content-model.md[spec]versus[live]markers against what the parser actually accepts. Frontmatter fields the code reads but the doc omits are drift; fields the doc promises but the code ignores are worse drift. - 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.