Audit — Bible content vs a rollback window
A rollback creates the failure mode Codex named at handoff: "commit present, effect absent." git log still reports every rolled-back version as landed, but the files at HEAD say otherwise. Any Bible page that describes a feature added in the rollback window is now potentially stale — the reader would look for a capability that isn't actually running.
This runbook is the method for finding + fixing that class of stale content. It was first run against the 2026-07-23 rollback (window v0.6.930–v0.6.951, 22 versions, see Three Sessions § the rollback) and returned clean.
The method
Six steps. Every one reads from the repo, not from any session's report.
1. Get the exact rollback delta
# Commits ROLLED BACK (in pre-rollback branch, not on HEAD)
git log --oneline origin/pre-rollback-vX.Y.ZZZ --not HEAD
# Commits ADDED AFTER rollback (on HEAD, not in pre-rollback branch)
git log --oneline HEAD --not origin/pre-rollback-vX.Y.ZZZ
If both return empty, the rollback used restore: bring the tree forward commits rather than git revert, so every rolled-back commit is still an ancestor of HEAD. Fall through to a content diff instead:
git diff --name-only origin/pre-rollback-vX.Y.ZZZ HEAD -- migrations/
git diff --name-only origin/pre-rollback-vX.Y.ZZZ HEAD -- src/
2. Enumerate the rolled-back-and-not-re-landed set
Read the pre-rollback branch commit log for the affected version range. Identify:
- Re-lands: post-rollback commits whose subject contains "re-land" or references a pre-rollback SHA.
- Still gone: pre-rollback versions with no re-land at HEAD.
Only the still gone set can produce stale Bible content.
3. Extract the feature claims from each still-gone commit
For each version in the still-gone set:
git show <sha> --stat
git log -1 --format="%h %s%n%b" <sha>
Note the class of change (schema · endpoint · UI text · shared surface · doctrine). A UI-text change or an internal refactor rarely produces Bible-side stale content; a schema, endpoint, or shared-surface change often does.
4. Grep the Bible for each claim
For every candidate claim, grep docs/ for the surface it would appear on:
grep -rniE "<pattern>" docs/ --include="*.md" --include="*.mdx"
Patterns to try, from the still-gone commit subjects:
- Distinctive phrases from the commit body ("flat sortable Purchase Cart", "one click, no preview")
- Endpoint names, migration numbers, class names, permission names introduced in the rolled-back commit
- The tab that owned the change, if the commit touches a module page
5. For every hit, verify the feature at HEAD
Never trust the Bible's claim on face; check the code:
# Schema
grep -n "<column|table>" migrations/*.sql
# Endpoint
grep -n "<route>" src/modules/<tab>/api.ts
# Class / helper
grep -n "<name>" src/modules/<tab>/*.ts src/core/*.ts
# Served behaviour
curl -s https://<worker>/api/build-info
curl -s https://<worker>/<endpoint>
Layer discipline: a grep proves a string is in a file, a curl proves the server sent bytes, reading a handler proves what the code says — none of these prove what the user sees. State which layer your evidence comes from, then ask whether your claim is about that layer.
6. Correct or leave
- Feature verified still true at HEAD — no action.
- Feature verified rolled back — correct the Bible page: either remove the stale claim, or reword to describe the current state, or add a superseded note if the historical framing has value.
- Uncertain — err toward correction. A wrong doc is worse than a gap.
Every correction commits with a message naming the version SHA on both sides and the layer of evidence.
The result of the 2026-07-23 run
22 versions in the window; 3 re-landed; 19 still-gone at HEAD.
Bible claims checked against the 19-commit still-gone set:
| Bible claim (source) | Rolled back? | Still true at HEAD? | Verified via |
|---|---|---|---|
| Serial hard-block + manager override on all 4 sale paths (sales.md) | No — v0.6.934 rolled back the retirement of the hard block | ✅ serialGuardError at api.ts:325, called on /create, /from-estimate, /deposit, /exchange | grep -nE "serialGuardError" src/modules/sales/api.ts |
.kb-link doctrine (no-inline-editing.md) | No | ✅ present in core/ui.ts | grep -c "\.kb-link" src/core/ui.ts = 1 |
| Payment types 11-tile grid (settings.md, mig 056) | No | ✅ 9 pos_tender_* columns present | grep -nE "pos_tender_" migrations/056_payment_tender_grid.sql |
| Layaway toggle (settings.md, mig 057) | No | ✅ pos_layaway_enabled column present | Read migrations/057_layaway_tile_flag.sql |
inventory_units table + Stock Card entry (inventory.md, mig 054) | No | ✅ table + Stock Card entry present | Read migrations/054_inventory_units.sql + grep "Units" src/modules/inventory/client.ts |
| Refund invariant + mixed-sign fix (sales.md, v0.7.410/.411/.414) | No — pre-rollback window | ✅ code at HEAD matches | Read src/modules/sales/api.ts refund handler |
| Refund tender-mismatch manager override (sales.md) | No | ✅ present | Read refund handler |
openReceiptPrompt + always-auto-print localStorage (receipt-engine.md) | Partially — v0.6.951 rolled back the "no longer one-way door" refinement | ✅ RECEIPT_AUTOPRINT_KEY still at src/index.ts:4214–4526. Bible prose is neutral on the one-way-door question | grep -nE "RECEIPT_AUTOPRINT_KEY|Always auto-print" src/index.ts |
| Serial pill wording ("green S/N" / "red Serial required", sales.md) | No — v0.6.935–.937 rolled back later pill-wording refinements | ✅ original v0.7.390 wording is what's at HEAD | Read src/modules/sales/client.ts |
Version-notes popup (core/versionmodal.ts) | Partially — v0.6.945 "serves both readers" rolled back then re-landed as v0.6.959 | ✅ present; Bible describes in neutral terms | Read src/core/versionmodal.ts |
Purchases kbPrint routing | Yes — v0.6.946 rolled back (Three-Sessions audit table shows refs 2 → 0) | N/A — Bible never claimed it | Bible grep returned no hits |
| Flat sortable Purchase Cart | Yes — v0.6.938/.940 rolled back | N/A — Bible never claimed it | Bible grep returned no hits |
| "What's New pop-up speaks shop" plain-language framing | Yes — v0.6.939 rolled back | N/A — Bible never claimed it | Bible grep returned no hits |
No corrections shipped. The Bible was already accurate at HEAD.
Why it came out clean
Two reasons, both worth naming so the next run doesn't get lucky when it should have gotten skill:
- The rollback window was mostly refinement work — pill wording, print-routing plumbing, cart-shape experiments — sitting on top of features documented earlier in more stable form. Rolling back the refinements left the earlier Bible claims still true.
- Prior sync work had already absorbed Codex's handoff proactively — Three Sessions published with the verified rollback audit, the changelog page updated to
v0.6.954with the branch-preservation admonition. That commit did the version-line + open-issues correction before this audit ran, which meant the audit only had to re-verify rather than discover.
What did NOT get audited
- Bible claims about features not shipped (Rentals module page, most eComm, most Trades write-path) — they don't exist to be stale.
- ADR history + slice history — dated citations at their layer per Tom's "do not retro-edit historical references" rule, 2026-07-22.
- The 22 rolled-back commits themselves — the audit checks whether the Bible describes them, not whether they should be re-landed. The latter is Tom's ruling.
When to re-run this
- After any rollback that removes more than a handful of versions.
- Before publishing a new major version note (e.g. an eventual v0.7 / v1.0 milestone), so the milestone's "what's live" claim is code-verified rather than note-derived.
- On demand from Tom.
The whole thing runs in an hour or two on the current Bible size (137 pages). Cost is bounded; discipline is what makes it useful.
See also
- Three Sessions — the handoff that named the rollback and the 22-version window
- The Doctrine — the "read the repository, not the messages" rule this runbook implements
- Changelog — the version-line doctrine + branch-preservation admonition