Split out of #829 (closed by #951), whose ROADMAP row carried this as a "deeper option" with no tracker of its own.
Summary
#951 closed the detection half of #829: TestErrorDisplaySync now guards the canonical E001 diagnostic against all five of its mirrors —
| Mirror |
Guarded |
README.md |
✅ |
docs/index.html |
✅ |
spec/00-introduction.md |
✅ |
AGENTS.md (example --json block) |
✅ (#951) |
scripts/build_site.py (hardcoded example → generates docs/index.md) |
✅ (#951) |
But the example is still hand-duplicated in five places. The tests can only tell you after the fact that a mirror drifted; they cannot stop it drifting. Every future edit to missing_contract_block's description / rationale / fix / spec_ref requires five coordinated hand-edits, and the suite's job is to catch the one you forgot.
The deeper fix
Single-source the example so nothing can drift: generate each mirror's rendered block from the canonical diagnostic (vera/errors.py::missing_contract_block) rather than hand-writing it.
Sketch:
- Render the canonical
E001 once (human-readable block + --json payload) from vera.errors.
- Have
scripts/build_site.py emit its example from that renderer instead of a hardcoded f-string.
- For the Markdown/HTML mirrors (
README.md, docs/index.html, spec/00-introduction.md, AGENTS.md), either inject the rendered block at doc-build time, or keep them hand-written but reduce TestErrorDisplaySync to a single generated-vs-file comparison.
Once a mirror is generated, its TestErrorDisplaySync guard becomes redundant and can be retired; the remaining hand-written mirrors keep theirs.
Why it matters
AGENTS.md's fix field was byte-identical to the canonical text yet unguarded until #951 — a drift there would have passed silently. That is the failure mode this issue removes structurally rather than by test coverage. It is squarely the project's "loud over silent" principle applied to its own documentation.
Notes
Split out of #829 (closed by #951), whose ROADMAP row carried this as a "deeper option" with no tracker of its own.
Summary
#951 closed the detection half of #829:
TestErrorDisplaySyncnow guards the canonicalE001diagnostic against all five of its mirrors —README.mddocs/index.htmlspec/00-introduction.mdAGENTS.md(example--jsonblock)scripts/build_site.py(hardcoded example → generatesdocs/index.md)But the example is still hand-duplicated in five places. The tests can only tell you after the fact that a mirror drifted; they cannot stop it drifting. Every future edit to
missing_contract_block'sdescription/rationale/fix/spec_refrequires five coordinated hand-edits, and the suite's job is to catch the one you forgot.The deeper fix
Single-source the example so nothing can drift: generate each mirror's rendered block from the canonical diagnostic (
vera/errors.py::missing_contract_block) rather than hand-writing it.Sketch:
E001once (human-readable block +--jsonpayload) fromvera.errors.scripts/build_site.pyemit its example from that renderer instead of a hardcoded f-string.README.md,docs/index.html,spec/00-introduction.md,AGENTS.md), either inject the rendered block at doc-build time, or keep them hand-written but reduceTestErrorDisplaySyncto a single generated-vs-file comparison.Once a mirror is generated, its
TestErrorDisplaySyncguard becomes redundant and can be retired; the remaining hand-written mirrors keep theirs.Why it matters
AGENTS.md'sfixfield was byte-identical to the canonical text yet unguarded until #951 — a drift there would have passed silently. That is the failure mode this issue removes structurally rather than by test coverage. It is squarely the project's "loud over silent" principle applied to its own documentation.Notes