docs(ledger): add a generated index and archival policy for branch-review records

[BigSimmo]

Summary

• Add docs/branch-review-index.md, a generated, human-readable index of the 577 immutable records in docs/branch-review-records/. Every filename there is a raw SHA-256 content address, so the directory cannot be navigated by hand, and the hash-filename to review-row join existed in no static artifact: scripts/generate-repo-awareness-snapshot.ts reads each record's path in readReviewRecordRows and then discards it in buildReviewStateSection, emitting only the six cells. The index supplies that missing join.
• Add scripts/generate-branch-review-index.mjs (npm run ledger:index, refreshed by npm run docs:update) plus tests/branch-review-index.test.ts. The generator reuses the existing corpus reader — listLedgerRecordPaths and parseLedgerRows from scripts/branch-review-ledger.mjs — rather than adding a third parser, which matters because four records carry escaped pipes that a naive split on the pipe character would mis-parse.
• Add docs/branch-review-archival-policy.md, recording what may and may not be done to the append-only corpus with the enforcing code quoted at file and line, so the constraint is not re-derived by the next session.
• Register both documents in docs/README.md, extend docs/branch-review-records/README.md with pointers, add the index to GENERATED_CATALOGS in scripts/check-stale-docs.mjs and to .prettierignore, and refresh the generated docs/scripts-index.md and data/repo-awareness-snapshot.json.

Deliberately not a gate. Records are appended at roughly 26 a day (576 records spanning only 2026-08-12 to 2026-09-02, 570 of them in August). A byte-equality drift check on a file derived from that corpus would turn main red after nearly every merge and would conflict between concurrent pull requests. This is not a new judgement: scripts/check-repo-awareness-snapshot.ts:22-41 already excludes review_state from COMPARED_CONTENT_KEYS for exactly this reason. So nothing is added to verify:cheap:internal, CI, verify-pr-local.mjs, or the pre-commit hook; ledger:index:check is advisory; and npm run ledger:lookup remains authoritative for "has this ref been reviewed?". The index states its own possible staleness in its header.

Scope note — no archival. The task also asked whether records could be archived. They cannot, and the policy document records why with the code quoted. Editing a row is blocked (check-branch-review-ledger.mjs:379-381 recomputes the filename as the sha256 of the row); compacting rows into one file is blocked (:374-377); deletion is forbidden by docs/codex-review-protocol.md:65 and caught by nothing. Moving records into subdirectories is the dangerous one: the only reader is a non-recursive readdirSync filtered to *.record.md (branch-review-ledger.mjs:172-180), so a nested record disappears from ledger:lookup, from check:branch-review-ledger, and from the repo-awareness snapshot while every gate still passes green. No gate was weakened, exempted, or bypassed.

One incidental gain: because the index links every record relatively, npm run docs:check-links now resolves 578 more references than before, which makes it the first — partial — enforcement of the never-delete-a-record rule. It only catches deletions of records the index already lists, and the policy document says so rather than overstating it.

Verification

Local gates were selected to match the change (documentation, a new offline generator, and generated-document machinery) rather than running a broad gate that covers no plausible failure path here. All output quoted below is verbatim.

• npm run check:ledger-write-discipline — Ledger write discipline passed for c0ee4ddd5fdd..HEAD.
• npm run check:branch-review-ledger — Branch review ledger guard passed: 880 live table records + 1206 archived + 577 immutable (880 under the 2026-07-29 machine-readable contract), immutable review writes, six cells each, no conflict markers, mojibake, heading records, or duplicates.
• npm run check:outstanding-issues — [snapshot] in step with data/outstanding-issues-snapshot.json (70 open, 0 pending)
• npm run check:repo-awareness-snapshot — [repo-awareness] in step with data/repo-awareness-snapshot.json (204 pages, 578 documents, 2663 reviews)
• npm run docs:check-links — docs link check passed: 5412 repo path references resolve.
• npm run docs:check-scripts — docs script-ref check passed: 1222 npm-run reference(s) resolve to real scripts.
• npm run docs:check-inventory — Docs inventory current: 285 script files, 289 npm scripts.
• npm run ledger:index:check — [ledger:index] docs/branch-review-index.md is current.
• npm run format:check — All matched files use Prettier code style!
• npm run typecheck — exit 0, [gate-receipts] recorded a pass for "typecheck:internal" (6025 input files).
• npx eslint scripts/generate-branch-review-index.mjs tests/branch-review-index.test.ts — exit 0, no output.
• npx vitest run tests/branch-review-index.test.ts — Test Files 1 passed (1), Tests 22 passed (22)
• Regression sweep over every existing test this diff could disturb, plus both workflow-contract suites — npx vitest run tests/branch-review-index.test.ts tests/ci-cache-safety.test.ts tests/browser-test-plan.test.ts tests/docs-inventory.test.ts tests/repo-hygiene.test.ts tests/site-map.test.ts tests/repo-awareness-generator.test.ts — Test Files 7 passed (7), Tests 245 passed (245)

Verification not run: npm run verify:pr-local, npm run verify:ui and npm run verify:release were deliberately skipped. The focused gates above cover this diff's plausible failure paths, no UI, routing, styling or browser behaviour changed, and no release confidence is claimed. CI remains the authoritative merge gate.

No provider-backed gate was run. Nothing touching OpenAI, Supabase, live CI, or any paid API was executed.

Two defects were found and fixed during verification rather than being left for CI: a stray NUL byte embedded in the generator's supersession-key separator, which made grep treat the source file as binary, replaced with its escape sequence; and a TypeScript error in the test fixture, whose spread through a Record<string, string> cast erased the hash property.

Risk and rollout

• Risk: Low, and additive. The generator only ever writes docs/branch-review-index.md — it contains a single writeFileSync and no rename or unlink call, and it never modifies anything under docs/branch-review-records/. Nothing was added to any verification gate, so no existing gate changes behaviour. The one edit to an existing script is a single new entry in the advisory GENERATED_CATALOGS list in scripts/check-stale-docs.mjs.
• Rollback: Revert the single commit. Nothing reads the index, so no consumer breaks.
• Provider or production effects: None.
• RAG impact: none. No file under src/lib/rag/, no retrieval RPC, no ranking surface, no golden fixture, and no eval harness file is touched by this diff.

Clinical Governance Preflight

This diff is documentation and offline tooling. It is classified clinical-risk solely because it regenerates data/outstanding-issues-snapshot.json and data/repo-awareness-snapshot.json, which the path classifier treats as clinical data exports. Both regenerations are mechanical output of committed generators, required because this change adds two documents; no clinical content, answer path, or access rule is touched. Each item below is confirmed against the actual diff, not assumed.

• Source-backed claims still require linked source verification before clinical use
• No patient-identifiable document workflow was introduced or expanded without explicit governance approval
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy)
• Service-role keys and private document access remain server-only
• Demo/synthetic content remains clearly separated from real clinical sources
• Source metadata, review status, and outdated/unknown-source behavior remain conservative
• Deployment classification/TGA SaMD impact was checked when clinical decision-support behavior changed

Evidence for the above: no file under src/, worker/, supabase/, or src/lib/rag/ is in this diff; the Supabase integration bot confirmed on this PR that it detected no changes in the supabase directory; Gitleaks and GitGuardian both passed; and no clinical decision-support behaviour changed, so the TGA SaMD classification is unaffected.

Notes

The policy check reports one advisory warning that is accurate and not worth splitting the PR over: operational-risk and clinical-risk paths are bundled, because package.json (two new npm scripts) and the regenerated data/ snapshots must land in the same commit as the generator they describe. Splitting them would leave either the snapshot stale or the scripts unregistered, and each half would fail its own gate.

The index is 644 lines and about 172 KB, roughly 0.6% of the documentation tree — a real but small cost, stated plainly in the policy document alongside the growth figures rather than glossed over. The archival-policy document's size measurements are quoted with the measuring method (du -sh versus du -sh --apparent-size differ by about 6 MB across thousands of small files), so a later reader does not "correct" one figure into the other.

A repo audit of the diff found no defects; its residual observations — the size-measurement ambiguity and a missing curated entry in docs/scripts-index.md — were both fixed before the first push.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AxPVZhAvzE2YupMiDz8sqF

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: b5e298fc-8915-4327-a40d-86cc87307267

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_fc614172-b2e7-4e41-90ca-11269a7646a8)

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-02T06:02:32.152772Z	ab50826	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

CI triage

CI failed on this PR. Automated classification of the 2 failed job(s):

• Unit coverage — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.
• PR required — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.

Compared with main CI run #14836 (success).

Classification is evidence routing, not permission to ignore a failure. Exact quarantined Playwright identities remain governed by the flake ledger.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_966c9a4b-c2dc-4aaf-a2ae-da39f9602358)

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_edbed845-c7f2-4d39-84f2-19cbc4ada9c0)

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_e2c790be-bff9-4429-b2de-05ef833da896)

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_3867d838-6a62-42f0-8e15-870bb4deeabb)