Repository navigation
feat(registry): refuse a push with a stale FEATURES.md - #675
Merged
Merged
Conversation
docs/FEATURES.md is a generated projection whose inputs include tests/test-*.sh and docs/specs/SPEC-*.md, because the Specs and Tests columns are token greps. An author adding a test file has no reason to think about a docs projection, so the drift lands, the suite pin goes red on master, and every later merge commit inherits it until someone regenerates by hand. hooks/ship-gate.sh gains an arm that fires when a push edits an input and leaves docs/FEATURES.md untouched. It calls the registry's own check verb, which tests/test-meta.sh now also uses for its freshness pin, so the gate and the suite share one definition of fresh. The regeneration costs about 20 seconds, so a push that carries the regenerated file skips it; whether that regeneration was correct is what CI pins. Escape hatch DWARVES_KIT_SKIP_REGISTRY_FRESHNESS=1. run-all --changed needed no new selection rule: test-meta.sh already carries the always marker that forces it onto every diff. Spec: docs/specs/SPEC-294-registry-freshness-guard.md
The Codex trust command pins ship-gate.sh by content hash, so editing the hook makes tests/test-codex-hooks.sh red until the pin follows.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
docs/FEATURES.mdis a generated projection oflib/registry/feature-registry.sh. Its inputs are the whole feature surface, includingtests/test-*.shanddocs/specs/SPEC-*.md, because the Specs and Tests columns are token greps.That pair is the trap. Adding a test file moves rows for every feature the file names, and an author adding a test has no reason to think about a docs projection. PR #663 added
tests/test-gitattributes-union.sh, which moved the/kit:docsrow's Tests column. Nobody regenerated.tests/test-meta.shwent red on master and every PR merge commit inherited that red until PR #665 regenerated by hand.The pin caught the drift on the wrong side of the push.
What changed
hooks/ship-gate.shgains an arm beside the existing doc-projection arm. It fires when a kit-repo push edits a FEATURES.md input and leavesdocs/FEATURES.mduntouched, callsfeature-registry.sh check, and exits 2 with the regenerate command when the projection has drifted.tests/test-meta.shnow pins freshness through that samecheckverb instead of rebuilding the regenerate-and-diff by hand, so the gate and the suite cannot disagree about what fresh means.The short-circuit. The regeneration costs about 20 seconds. A push that also carries
docs/FEATURES.mdskips it: an author who regenerated is not the failure mode, and whether they regenerated correctly is what CI pins. The expensive path runs only on the shape of the incident.Scope. Kit repo only, by file existence. Escape hatch
DWARVES_KIT_SKIP_REGISTRY_FRESHNESS=1, registered inlib/config/module-registry.md.No
run-all --changedrule was needed. The goal's pause-if clause fired:tests/test-meta.shalready carries the# always:marker that forces it onto every diff. Evidence is in the proof.Also repins the Codex trust command's content hash for
ship-gate.sh, whichtests/test-codex-hooks.shasserts and which any edit to that hook invalidates.Verification
bash tests/test-registry-freshness-guard.shbash tests/test-meta.shbash tests/test-config-registry.shbash tests/test-codex-hooks.shbash tests/run-all.sh --changedNegative control through
lib/gate/negctl.sh, verdict PASS: neutering the arm's input pattern turns the new suite red and restoring it turns it green.Spec:
docs/specs/SPEC-294-registry-freshness-guard.mdProof:
docs/verification/registry-freshness-guard.mdBoard: ID-905