BigSimmo · BigSimmo · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026
@@ -5,7 +5,7 @@ description: Review the current Database diff, branch, or explicitly approved PR
 
 # Review
 
-1. Read `docs/codex-review-protocol.md` and `docs/branch-review-ledger.md` when present.
+1. Read `docs/codex-review-protocol.md`, and check prior reviews with `npm run ledger:lookup -- <ref> --scope "<scope>"` rather than reading the ledger table directly.
 2. Resolve the local target SHA and check whether the same scope was already reviewed.
 3. Inspect changed behavior and realistic failure paths; prioritize reproducible P0-P2 findings.
 4. Cite exact files and lines, trigger, impact, and the smallest proof or fix.

@@ -11,7 +11,7 @@ Use this agent when a change touches source governance, citations, answer verifi
 
 ## Repository Review Protocol
 
-Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and record completed branch/PR reviews with `npm run ledger:append` (check `npm run ledger:lookup` first; never hand-edit the ledger).
 
 ## Scope
 

@@ -11,7 +11,7 @@ Use this agent when a change touches dashboard components, the shared search com
 
 ## Repository Review Protocol
 
-Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and record completed branch/PR reviews with `npm run ledger:append` (check `npm run ledger:lookup` first; never hand-edit the ledger).
 
 ## Scope
 

@@ -11,7 +11,7 @@ Use this agent when a change touches the ingestion pipeline, the OCR worker, chu
 
 ## Repository Review Protocol
 
-Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and record completed branch/PR reviews with `npm run ledger:append` (check `npm run ledger:lookup` first; never hand-edit the ledger).
 
 ## Scope
 

@@ -11,7 +11,7 @@ Use this agent when a pull request's CI or required checks are failing and the g
 
 ## Repository Review Protocol
 
-Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, and record completed branch/PR reviews with `npm run ledger:append` (check `npm run ledger:lookup` first; never hand-edit the ledger).
 
 ## Provider / GitHub boundary (hard rule)
 

@@ -11,7 +11,7 @@ Use this agent when a change touches retrieval, ranking, context selection, answ
 
 ## Repository Review Protocol
 
-Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and record completed branch/PR reviews with `npm run ledger:append` (check `npm run ledger:lookup` first; never hand-edit the ledger).
 
 ## Scope
 

@@ -11,7 +11,7 @@ Use this agent when auditing workspace layout, folder structure, imports, and de
 
 ## Repository Review Protocol
 
-Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and record completed branch/PR reviews with `npm run ledger:append` (check `npm run ledger:lookup` first; never hand-edit the ledger).
 
 ## Provider boundary
 

@@ -11,7 +11,7 @@ Use this agent when a change touches database migrations, schema, RLS, RPCs/SECU
 
 ## Repository Review Protocol
 
-Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and record completed branch/PR reviews with `npm run ledger:append` (check `npm run ledger:lookup` first; never hand-edit the ledger).
 
 ## Scope
 

@@ -37,8 +37,9 @@ force-push, or discard work.
 6. **Open a PR** with `gh pr create --base main`, body ending with the Claude Code
    attribution line. Enabling squash-auto-merge (`gh pr merge --squash --auto`) is the
    repo norm but requires explicit user confirmation before enabling; the PR lands on green.
-7. **Record** the review in `docs/branch-review-ledger.md` (Date | Branch/ref | Reviewed
-   HEAD | Scope | Outcome | Checks).
+7. **Record** the review with `npm run ledger:append`, passing `--ref <branch>`, `--head`
+   (the full 40-character SHA), `--scope`, `--outcome`, and `--checks`. Do not hand-write
+   the row into `docs/branch-review-ledger.md`.
 
 ## Requires explicit confirmation (do not do automatically)
 

@@ -40,8 +40,9 @@ requirement that applies to mutating provider operations (merging, closing PRs,
    only after confirming the content diff is empty. For squash-merged branches, `-d` will
    refuse (no ancestry merge) even though the content landed, so `-D` is required once
    the empty diff confirms the work is fully landed. Do not force-delete before verification.
-5. **Update the ledger** (`docs/branch-review-ledger.md`) and any relevant memory note with
-   the merged HEAD SHA and outcome.
+5. **Update the ledger** with `npm run ledger:append`, passing `--ref <branch>`, `--head`
+   (the merged squash commit's full 40-character SHA, not an abbreviation),
+   `--scope prlanded`, `--outcome`, and `--checks`, plus any relevant memory note.
 
 ## Notes
 

@@ -59,10 +59,9 @@ Never, even during a sweep:
 - Draft with `WIP` or "do not merge" in the title, or a `hold` label → skip. Plain drafts are
   processed the same as ready PRs.
 - Fork-hosted head → no pushes; run diagnosis and thread replies only.
-- Ledger throttle: resolve the head SHA; if `docs/branch-review-ledger.md` already has a
-  completed sweep-scope row for this PR at this exact HEAD, and current checks are green, and
-  there are no unresolved threads, and the branch is not behind `main` → skip, citing the prior
-  row in one line.
+- Ledger throttle: `npm run ledger:lookup -- <branch> --head <sha> --scope "Run PR sweep"`. On
+  `ALREADY REVIEWED`, and current checks are green, and there are no unresolved threads, and the
+  branch is not behind `main` → skip, citing the prior row in one line.
 
 ### Step 1 — snapshot "before"
 
@@ -160,12 +159,19 @@ branch/ref recorded during setup.
 
 ## Ledger recording
 
-Append one row per PR touched to `docs/branch-review-ledger.md` (the file is prettier-ignored,
-so long rows are fine):
+Append one record per PR touched. Never hand-write the markdown row — use the helper, which
+stamps the date, resolves the HEAD, escapes prose pipes, and writes UTF-8:
 
-`| <date> | <branch> (PR #<n>) | <post-sweep HEAD SHA> | Run PR sweep: CI fix + threads + drift | <before → after: failing checks fixed, N threads resolved / M left open (reasons), merged origin/main (conflicts resolved: files / none / skipped: files), or skip reason> | <exact gates run with results; explicit "no provider-backed checks run"> |`
+```bash
+npm run ledger:append -- --ref "<branch> (PR #<n>)" --head <post-sweep full 40-char HEAD SHA> \
+  --scope "Run PR sweep: CI fix + threads + drift" \
+  --outcome "<before → after: failing checks fixed, N threads resolved / M left open (reasons), merged origin/main (conflicts resolved: files / none / skipped: files), or skip reason>" \
+  --checks "<exact gates run with results; explicit 'no provider-backed checks run'>"
+```
 
-Per-PR rows only — no extra sweep-total row — so ledger throttling lookups stay per-branch.
+The HEAD must be the full SHA — `pending pushed head` and 8-character abbreviations are
+unmatchable, so the next sweep re-reviews the same PR. Per-PR records only — no extra sweep-total
+record — so ledger throttling lookups stay per-branch.
 
 ## Final report format
 

@@ -20,6 +20,6 @@ When invoked:
 7. Respect provider confirmation boundaries: no live Supabase/OpenAI/eval spend without separate explicit authorization for that provider action. A Run PR sweep never authorizes provider-backed gates.
 8. Require explicit user authorization before commits, pushes, hosted-CI reruns, replies, or thread resolution. The Run PR shortcut supplies authorization only for the GitHub actions enumerated in `AGENTS.md`. Do not edit PR titles/bodies during Run PR sweeps unless the user explicitly asks. Re-check CI until mergeable + green + comments triaged.
 9. Never merge into `main`, force-push, close the PR, enable auto-merge, or delete branches unless the user explicitly asks.
-10. Follow `docs/codex-review-protocol.md` and append a `docs/branch-review-ledger.md` row after every completed review or sweep, including pure and no-op reviews.
+10. Follow `docs/codex-review-protocol.md` and record every completed review or sweep — including pure and no-op reviews — with `npm run ledger:append`.
 
 Report before/after: merge state, CI, threads fixed vs left open, commits pushed, and any remaining human decision.
@@ -121,10 +121,9 @@ Use `docs/codex-review-protocol.md` as the shared review protocol for every repo
 
 Before reviewing a branch or PR:
 
-- Check `docs/branch-review-ledger.md` if it exists.
-- Resolve the target with `git rev-parse <branch-or-ref>`.
-- If the same branch/ref and HEAD SHA were already reviewed for the same scope, summarize the prior ledger outcome and skip the repeat review unless the user explicitly requests a fresh pass.
-- If the target HEAD changed, review only the changed scope and update the ledger after the review.
+- Run `npm run ledger:lookup -- <branch-or-ref> --scope "<scope>"`. It resolves the HEAD, matches the abbreviated SHAs older records used, and prints an explicit verdict. Do not read `docs/branch-review-ledger.md` by eye — it is over a thousand rows, and eyeballing it is how repeat reviews slipped through.
+- On `ALREADY REVIEWED`, summarize the prior ledger outcome and skip the repeat review unless the user explicitly requests a fresh pass.
+- On `NOT REVIEWED at this HEAD`, review only the changed scope and append a record after the review.
 
 Before reviewing multiple branches:
 
@@ -143,7 +142,7 @@ Review routing:
 - `branch-cleanup`: Use only when the prompt explicitly asks for branch cleanup/hygiene or branch deletion candidates. Apply `docs/branch-cleanup-guide.md` and the review ledger before inspecting branch diffs.
 - `pr-ci-fix`: Confirmation-required for this repo. GitHub/GitLab API calls, PR comments, CI reruns, commits, and pushes require explicit user approval and must respect the upload/handoff rules. Exception: an explicit `Run PR` sweep carries this approval (see "## Run PR shortcut").
 
-When a branch or PR review completes, append the reviewed branch/ref, HEAD SHA, date, scope, outcome, and checks to `docs/branch-review-ledger.md`. The ledger is append-only: never edit or delete an existing record; append a correction or superseding record instead. Its `merge=union` attribute preserves concurrent appends, and `npm run check:branch-review-ledger` blocks conflict markers, exact duplicate records, or loss of that merge protection.
+When a branch or PR review completes, record it with `npm run ledger:append -- --ref <x> --head <full-40-char-sha> --scope <s> --outcome <o> --checks <c>`. Never hand-write the markdown row: hand-written rows produced the mojibake, wrong-width, and duplicate records that the 2026-07-28 hygiene pass had to repair, and `see PR head` or abbreviated HEADs make a record unmatchable so the review runs again. The ledger is append-only: never edit or delete an existing record; append a correction or superseding record (`--supersede`) instead. Its `merge=union` attribute preserves concurrent appends, and `npm run check:branch-review-ledger` blocks conflict markers, duplicate records, mojibake, wrong-width or heading-style records, unresolvable HEADs, or loss of that merge protection.
 
 <!-- END:codex-review-throttling -->
 

@@ -69,7 +69,7 @@ npm run docs:check-links
 - [codex-review-protocol.md](codex-review-protocol.md) — shared review protocol for all review skills
 - [codex-prompt-playbook.md](codex-prompt-playbook.md) — copy/paste prompts for common repo work
 - [branch-cleanup-guide.md](branch-cleanup-guide.md) — branch hygiene workflow
-- [branch-review-ledger.md](branch-review-ledger.md) — reviewed branch/SHA ledger (append after reviews)
+- [branch-review-ledger.md](branch-review-ledger.md) — reviewed branch/SHA ledger; read it with `npm run ledger:lookup`, write it with `npm run ledger:append` (never by hand)
 
 ## Plans and workstreams (living)
 

@@ -45,16 +45,13 @@ does not replace the fetch/approval and per-branch content proof below.
    git worktree list --porcelain
    ```
 
-5. Filter candidates through the review ledger before inspecting branch diffs. Follow the lookup procedure in `docs/branch-review-ledger.md` and require all three fields to match before skipping:
+5. Filter candidates through the review ledger before inspecting branch diffs:
 
-   ```powershell
-   $branch = "BRANCH_NAME"
-   $head = git rev-parse $branch
-   Get-Content docs\branch-review-ledger.md |
-     Select-String -Pattern "\|\s*$branch\s*\|\s*$head\s*\|\s*branch-cleanup\s*\|"
+   ```bash
+   npm run ledger:lookup -- BRANCH_NAME --scope branch-cleanup
    ```
 
-   Skip the branch only when a ledger row matches the same branch/ref, reviewed HEAD, and `branch-cleanup` scope together. A branch-name-only match is not enough. Re-review when the HEAD changed or the user explicitly asks for a fresh pass.
+   The lookup resolves the HEAD itself and matches the abbreviated SHAs that older records used, which a literal regex on the full SHA silently missed. Skip the branch only on an `ALREADY REVIEWED` verdict — that requires the same branch/ref, reviewed HEAD, and an exact `branch-cleanup` scope together; a branch-name-only match is not enough, and a `branch-cleanup-deletion-pending` row must not match. Re-review when the HEAD changed or the user explicitly asks for a fresh pass. `npm run sweep:branch-ledger` applies this filter across every remote branch in one pass.
 
 6. For each remaining candidate branch, check whether it has patch content not on `main`:
 
@@ -75,7 +72,7 @@ credentials.
 2. Resolve each candidate's HEAD and skip unchanged completed reviews recorded in `docs/branch-review-ledger.md`.
 3. For each remaining candidate branch, confirm patch-unique commits and file diffs against `main`.
 4. Port, commit, or explicitly reject useful patch content before deleting any branch ref.
-5. Record completed cleanup reviews in `docs/branch-review-ledger.md`.
+5. Record completed cleanup reviews with `npm run ledger:append -- --ref <branch> --head <full-sha> --scope branch-cleanup --outcome <o> --checks <c>`. The scope cell must be exactly `branch-cleanup` for a later sweep to treat it as complete; `branch-cleanup-deletion-pending` deliberately does not count.
 6. Remove detached worktrees only when clean, unneeded, and absent from active `git worktree list` output.
 
 ## Final Verification