fix(docs): the rail count drifted to five different answers in one commit - #687
Merged
Conversation
…mmit (#667 follow-up) `guards.check` implements TWENTY rails -- 1-14 and 16-21, rail 15 retired. At v0.13.2 the repository stated that number four different ways at once: guards.py:267 "all twenty rails" correct README.md:227 "the 18 rails" two behind executor.py:4 "eighteen ... rails" two behind executor.py:93 "eighteen rails" two behind executor.py:1558 "eighteen rails" two behind MY OWN SWEEP CAUSED IT. #667 added rail 21 and updated the count by grepping for "nineteen" -- which found `guards.py`, `glossary.md`, the runbook, `launch.md` and `go-live-runbook.md`, and never touched the four places that said "eighteen" or "18" because those had already been stale since rail 19. Fixing the spelling I happened to search for left the ones I did not, and nothing failed. TEST FIRST, and it earned its place immediately: it found FIVE claims where a manual grep had found three, including `executor.py`'s module docstring. The count is DERIVED from the numbered rails in `guards.check` and every English and numeric spelling is searched repository-wide, so rail 22 fails the suite instead of leaving documents wrong for three releases. DATED RECORDS ARE EXCLUDED, and this is a rule rather than a convenience. `docs/research/2026-08-20-quant-lab-note-cross-verification.md` says "eighteen rails" and "four rule families", and BOTH WERE TRUE when a third party's note was verified in August 2026. Updating it would silently rewrite a verification nobody re-ran. `docs/experiments`, `docs/presentations` and `docs/superpowers` are out for the same reason: they are statements about what was true when written. The contiguity assertion is about the SET, not about "sorted, unique, starts at 1". A mutation renumbering rail 21 to 22 passed all three of those -- the count held, the order held, 15 was still absent -- while a silent gap opened at the top. A gap is the shape this drifts in. 4 mutants, 4 killed: README going stale, a docstring going stale, a renumbering that opens a gap, and reuse of the retired 15. Tests: `tests/execution/test_rail_count.py` (2 tests). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NzuKAe2RVrPt9acVAWjRyL
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
1 participant
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.
guards.checkimplements twenty rails — 1–14 and 16–21, rail 15 retired. At v0.13.2 the repository stated that number four different ways at once:guards.py:267README.md:227executor.py:4executor.py:93executor.py:1558My own sweep caused it
#667 added rail 21 and updated the count by grepping for "nineteen". That found
guards.py,glossary.md, the runbook,launch.mdandgo-live-runbook.md— and never touched the four places saying "eighteen" or "18", which had already been stale since rail 19. Fixing the spelling I happened to search for left the ones I didn't, and nothing failed.Test first, and it earned it immediately
Writing
tests/execution/test_rail_count.pybefore the fix found five claims where my manual grep had found three — includingexecutor.py's module docstring, which I'd missed entirely.The count is derived from the numbered rails in
guards.check, and every English and numeric spelling is searched repository-wide. Rail 22 fails the suite instead of leaving documents wrong for three releases.Dated records are excluded, deliberately
docs/research/2026-08-20-quant-lab-note-cross-verification.mdsays "eighteen rails" and "four rule families" — both were true when a third party's note was verified in August 2026. Updating it would silently rewrite a verification nobody re-ran.docs/experiments,docs/presentationsanddocs/superpowersare out for the same reason: they state what was true when written.The contiguity assertion is about the set
Not "sorted, unique, starts at 1". A mutation renumbering rail 21 → 22 passed all three of those — the count held, the order held, 15 was still absent — while a silent gap opened at the top. A gap is the shape this drifts in, so the assertion compares against
1..maxminus the retired 15.Verification
Tests:
tests/execution/test_rail_count.py— 2 tests.4 mutants, 4 killed: README going stale, a docstring going stale, a renumbering that opens a gap, and reuse of the retired rail 15.
Full suite 5249 passed / 3 skipped; ruff and mypy clean.