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

.prettierignore

@@ -45,6 +45,14 @@ docs/branch-review-ledger.md
 # row shape, ids, the next-id marker and the merge attribute far more strictly than
 # Prettier's alignment ever did.
 docs/outstanding-issues.md
+# Generated by `scripts/generate-branch-review-index.mjs` from
+# docs/branch-review-records/. Same reason as the two ledgers above: Prettier
+# column-pads markdown tables, so one long cell would repad all 576 rows and turn
+# a one-record append into a whole-file diff. The generator emits single-space
+# padding so appending a record stays a one-line diff. Structure is not lost —
+# tests/branch-review-index.test.ts gates the generator's escaping, ordering and
+# per-record coverage far more strictly than Prettier's alignment would.
+docs/branch-review-index.md
 # Verbatim user-provided prompt inputs retained for cloud review.
 docs/prompts/codex-cloud-review/
 # Generated by `scripts/generate-outstanding-issues-snapshot.mjs` from

PR_POLICY_BODY.md

@@ -1,48 +1,50 @@
 ## Summary
 
-This PR completes three non-RAG UI maintenance items across the developer area and search/UI components:
-
-1. **Developer Hub Phase 2 Tidy-ups (Dev Hub Handoff §6.5)**:
-   - **`PanelSection` Server Component**: Exported a shared Server Component `PanelSection` in `src/components/developer-area/hub/panel-primitives.tsx` (pure Server Component, zero client imports or `"use client"`).
-   - **Page Migrations**: Migrated all 17 repetitive `<section aria-labelledby="...">` blocks across 5 developer mockup pages:
-     - `src/app/mockups/development/documentation/page.tsx`
-     - `src/app/mockups/development/ledger/page.tsx`
-     - `src/app/mockups/development/review-state/page.tsx`
-     - `src/app/mockups/development/routes/page.tsx`
-     - `src/app/mockups/development/test-health/page.tsx`
-   - **Documentation Section Counts Cleanup**: Cleaned `DocumentationSection.sections` to `{ name: string }[]` in `src/lib/developer-area/repo-awareness-types.ts` and `scripts/generate-repo-awareness-snapshot.ts` so snapshot metadata and reader consumption stay 1:1.
-   - **Prettierignore Sync**: Added `data/repo-awareness-snapshot.json` to `.prettierignore` mirroring `data/outstanding-issues-snapshot.json`.
-
-2. **Search CLS Layout Reserve Verification (`#308` / `#JVYQEM`)**:
-   - Verified settled height reserve tokens and layout constraints at composer adoption boundary (160px for tablet / 88px for desktop).
-   - Verified zero reserve when search is `hidden` or unmounted, avoiding interference with phone bottom-dock.
-
-3. **Form Control Design Token Modernization (`#321`)**:
-   - Audited form controls across `src/components/document-viewer/` and verified design token alignment (`aria-disabled`, `ignoreUnavailableActivation`, focus rings).
+- 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
 
-- [x] `npm run check:repo-awareness-snapshot`: Passed (188 pages, 429 docs, 2609 reviews)
-- [x] `npm run check:design-system-contract`: Passed (1006 production files checked)
-- [x] `npm run check:design-system-adoption`: Passed (54 components, 96 roots)
-- [x] `npm run check:design-sync-contract`: Passed (54 components, 7 guidelines)
-- [x] `tsc -p tsconfig.typecheck.json --noEmit`: Passed (0 errors)
-- [x] `npm run ensure` + `/api/local-project-id`: Passed (HTTP 200 `Clinical KB` at `http://localhost:4131`)
-- [x] Probed all 5 migrated mockup routes live: all returned HTTP 200
-- [x] Vitest suites: **127 / 127 tests passed** across 9 test files (`developer-hub-panels`, `developer-documentation-page`, `developer-routes-page`, `developer-ledger-page`, `repo-awareness-gate`, `repo-awareness-generator`, `repo-awareness-snapshot`, `search-route-ownership`, `document-image-filmstrip`)
-- UI verification not run: production UI journeys already green on this head in CI (`Production UI critical` / `Production UI (1–3)` SUCCESS); local `verify:ui` not re-run for this body-only policy fix.
-- Verification not run: `verify:release` — not a release/handoff confidence claim; provider-backed gate not authorized for this PR-policy body fix.
+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.
+
+- [x] `npm run check:ledger-write-discipline` — `Ledger write discipline passed for c0ee4ddd5fdd..HEAD.`
+- [x] `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.`
+- [x] `npm run check:outstanding-issues` — `[snapshot] in step with data/outstanding-issues-snapshot.json (70 open, 0 pending)`
+- [x] `npm run check:repo-awareness-snapshot` — `[repo-awareness] in step with data/repo-awareness-snapshot.json (204 pages, 578 documents, 2663 reviews)`
+- [x] `npm run docs:check-links` — `docs link check passed: 5412 repo path references resolve.`
+- [x] `npm run docs:check-scripts` — `docs script-ref check passed: 1222 npm-run reference(s) resolve to real scripts.`
+- [x] `npm run docs:check-inventory` — `Docs inventory current: 285 script files, 289 npm scripts.`
+- [x] `npm run ledger:index:check` — `[ledger:index] docs/branch-review-index.md is current.`
+- [x] `npm run format:check` — `All matched files use Prettier code style!`
+- [x] `npm run typecheck` — exit 0, `[gate-receipts] recorded a pass for "typecheck:internal" (6025 input files).`
+- [x] `npx eslint scripts/generate-branch-review-index.mjs tests/branch-review-index.test.ts` — exit 0, no output.
+- [x] `npx vitest run tests/branch-review-index.test.ts` — `Test Files  1 passed (1)`, `Tests  22 passed (22)`
+- [x] 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; developer mockup refactor and generated snapshot shape only; no production clinical path change.
-- Rollback: Revert the branch commits.
+- 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: no retrieval behaviour change — developer-area mockups and repo-awareness snapshot metadata only; no rag/retrieval/ranking surfaces touched.
+- 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 is a developer-hub mockup refactor + snapshot metadata cleanup; no clinical pipeline/RAG/privacy change.
+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.
 
 - [x] Source-backed claims still require linked source verification before clinical use
 - [x] No patient-identifiable document workflow was introduced or expanded without explicit governance approval
@@ -52,21 +54,16 @@ This is a developer-hub mockup refactor + snapshot metadata cleanup; no clinical
 - [x] Source metadata, review status, and outdated/unknown-source behavior remain conservative
 - [x] Deployment classification/TGA SaMD impact was checked when clinical decision-support behavior changed
 
-<!-- CURSOR_SUMMARY -->
+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.
 
-> [!NOTE]
-> **Low Risk**
-> Refactor of dev-only mockup UI and generated snapshot shape with matching tests; no production auth, API, or payment paths touched.
->
-> **Overview**
-> Introduces a shared **Server Component** `PanelSection` in `panel-primitives.tsx` and replaces repeated `<section aria-labelledby>` + heading markup across the five developer mockup panels (documentation, ledger, review-state, routes, test-health). Section headings, `h2`/`h3` levels, optional `data-testid`, and default spacing stay consistent without adding a client boundary.
->
-> **Repo-awareness documentation metadata** no longer stores per-section `documents` / `uncatalogued` counts in the snapshot: `DocumentationSection.sections` is now `{ name }[]`, `buildDocumentationSection` only emits section names, and the committed `data/repo-awareness-snapshot.json` is regenerated. The documentation page still shows counts via `documentsBySection`, which groups live document rows.
->
-> Adds `data/repo-awareness-snapshot.json` to **`.prettierignore`** (same rationale as the outstanding-issues snapshot) so generator formatting and `check:repo-awareness-snapshot` stay aligned.
->
-> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 0c052c08df58974aa059fc52a4987e62afe0be10. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
 
-<!-- /CURSOR_SUMMARY -->
+https://claude.ai/code/session_01AxPVZhAvzE2YupMiDz8sqF

data/repo-awareness-snapshot.json

@@ -1,8 +1,8 @@
 {
   "version": "repo-awareness-snapshot-v2",
   "captured_revision": {
-    "sha": "cdfb3fdda5533c126e76fecaf4e0352a6757249f",
-    "committed_at": "2026-09-02T11:12:52+00:00"
+    "sha": "a683a5a6af3d400574bb8ef55e199e0c8665c60f",
+    "committed_at": "2026-09-02T11:35:41+00:00"
   },
   "routes": {
     "modes": [
@@ -1850,6 +1850,16 @@
         "section": "root",
         "catalogued": true
       },
+      {
+        "path": "docs/branch-review-archival-policy.md",
+        "section": "root",
+        "catalogued": true
+      },
+      {
+        "path": "docs/branch-review-index.md",
+        "section": "root",
+        "catalogued": true
+      },
       {
         "path": "docs/branch-review-ledger.md",
         "section": "root",
@@ -4437,8 +4447,8 @@
       }
     ],
     "counts": {
-      "documents": 580,
-      "catalogued": 111,
+      "documents": 582,
+      "catalogued": 113,
       "uncatalogued": 469,
       "sections": 21
     }