compare state.md's currency instead of declaring it
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.
This commit is contained in:
@@ -5,7 +5,7 @@ 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.
|
||||
|
||||
1. Inventory the actual Go files, their line counts, and the non-stdlib dependencies in `go.mod`.
|
||||
2. Compare against `docs/state.md`: inventory rows, counters, latent items, `verified against`.
|
||||
2. 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.
|
||||
3. Check `docs/architecture.md` STATUS lines: has a primitive become real, or is one described
|
||||
|
||||
@@ -120,7 +120,8 @@ not run something, say which and why.
|
||||
Same change, not later. Triggers: `docs/README.md`. Walk the propagation table above — every surface
|
||||
done or explicitly n/a. Minimum:
|
||||
|
||||
- `docs/state.md`: inventory rows, counters, `verified against` line, latent items added/removed.
|
||||
- `docs/state.md`: inventory rows, counters, latent items added/removed — in *this* commit, never a
|
||||
trailing one, which is what `verify.sh` compares (ADR-0057).
|
||||
- `docs/decisions.md`: an ADR if the choice is expensive to reverse. Six lines. First open the doc
|
||||
that owns the topic — if it already carries the rule, amend it there; an ADR restating an
|
||||
existing doc is a duplicate, not a decision.
|
||||
|
||||
Reference in New Issue
Block a user