Make the written record the gate on retiring a mockup, and retire seven

[BigSimmo]

Summary

The mockup surface reached ~430 files and ~98,000 lines, and the filenames advertise repeated superseded generations of one screen. This adds a policy and a gate that make the written record load-bearing, then retires only what that policy clears on evidence — seven mockups, 4,235 lines across 14 deleted files, not the far larger number the filenames imply.

• docs/mockup-retirement-policy.md — three tiers decided by evidence of a consumer rather than by path, a six-point evidence bar drawn from the 2026-08-27 Favourites retirement (the only one this repo has performed), who decides, and where a retired mockup goes.
• scripts/check-mockup-retirement.mjs / npm run check:mockups — wired into verify:cheap and CI. Enforces index completeness and accuracy, and in --diff auto mode refuses a deletion that is unrecorded, under a developer-gated prefix, or still referenced by any survivor. Fails closed, and never clears a candidate.
• mockups/README.md — gains a ## Retired mockups table, and is corrected in five places the survey refuted.
• Seven retirements across the document-navigation, document-phone-chrome and answer families.
• AGENTS.md / CLAUDE.md — the mockup gate-exemption list corrected to match the code, in both directions.
• Three /issues inbox requests for findings deliberately not fixed here.

Why this is much smaller than it looks

A prior pass (PR #2423) already triaged this surface and declined most of it in writing. Six agents re-examined all 20 design-scratch families against production code and git history, and found the reason:

In this repo a mockup and the production change it justifies are usually added in the same commit. search-heading arrived with the search-band rewrite, universal-search-command with universal-search-command-surface.tsx, sidebar-live with ClinicalSidebar and use-sidebar-pins.ts, all nine document mockups with document-viewer/section-nav.tsx. A mockup here is normally a provenance artifact attached to a shipped commit, not a stale draft.

Two further traps the policy encodes:

• Filename supersession is systematically backwards. answer-chat-perfected-v2 imports answer-chat-perfected; so does answer-loading-redesign. Dictionary rounds 2 and 3 both import round 1. The privacy study imports the privacy winner. In at least five families, deleting "the older generation" breaks the newer one.
• A third of the surface is not design scratch. /mockups/development, /mockups/caring-contacts, /mockups/care-plan and /mockups/ward-flow are live in production behind DeveloperAreaGate and linked from Settings. 82 of their modules have no "mockup" in the name, so every glob in the repo misses them.

What was retired, and against which winner

Document navigation and document phone chrome. The README said "no recorded winner", so all nine were kept. One commit disproves it: 6230c4db (#1311) added every draft and the production implementation together, which is why the dates looked undifferentiated. document-navigation-perfected is the shipped design on exact code identity — production section-nav.tsx carries a weighted segment track (style={{ flexGrow: section.weight }}) and a pending spinner, and a grep across all drafts returns those in perfected and in no other. Rule 22 of docs/search-chrome-behaviour.md, added by that same commit, names a "weighted position track".

Retired: document-navigation-pane, document-navigation-final-review, document-phone-title, document-phone-title-refined, document-phone-fused-directions.

Answer. Three of six shipped and stay. answer-evidence-popups is the five-tab Evidence sheet #2362 explicitly replaced, naming it as one of "four mental models for one question"; none of its distinctive components survives in production. answer-home-proposal never shipped — its subtitle copy is absent from ui-copy.ts, and the badge removal it argued for landed independently in #1512 hours before its own PR merged.

Kept deliberately: answer-chat-perfected is a shared base two newer files import; answer-chat-redesign is the three-way comparison the winner was chosen from, cited by the answer handover and by answer-chat-perfected-mockups.tsx; document-navigation-contract is superseded as a build but is the origin of rule 22.

Adversarial review — two candidates withdrawn

Two fresh agents reviewed before push: one asked to argue every candidate was still alive, one frontend-ui-reviewer on the full diff. Both found real defects.

The "still alive" reviewer found two survivors, and both were restored:

• document-navigation-final — production section-nav.tsx:143 renders its heading as <div className="flex items-baseline justify-between px-0.5 pb-2">. That exact string exists in two files repo-wide: production, and this draft at line 278. perfected does not have it. Production is a hybrid, so by the sweep's own standard of exact code identity this was partly adopted, not superseded.
• document-phone-zero-chrome — returned UNCERTAIN, the condition it was admitted under. Its "zero new chrome" contract is live, but the kept document-navigation-contract carries the same thesis verbatim and both landed in one squash, so authorship cannot be established.

The UI reviewer found two of my own doc corrections were wrong, both verified with picomatch before changing anything:

• CodeRabbit is not exempt. .coderabbit.yaml's !mockups/** is root-anchored and excludes only the repo-root notes directory — not src/app/mockups/** or *-mockups.tsx. With the capped allowance in #CCZ4HB, believing otherwise could have cost real review coverage.
• knip is not blind to this surface. Its ignore is a basename filter, so *-mockups.tsx is exempt but the route page.tsx files and */mockups/** subtrees are not. What suppresses findings is check:knip omitting unused-file analysis repo-wide — not a mockup carve-out.

It also found the gate advertised enforcement it was not performing (nothing ever passed --diff), that the gate missed relative imports, dynamic imports, CSS composes and route-path literals, and that the sweep had consequently left four dead pathname === "/mockups/<slug>" branches in mockups-layout-client.tsx that the gate passed clean. All fixed, with tests.

Verification

• npm run check:mockups — self-test passed; 72 mockup route(s) indexed, 14 recorded as retired; 13 deleted mockup file(s), each recorded and unreferenced
• npm run test — Test Files 947 passed (947), Tests 12098 passed | 4 skipped (12102)
• npm run lint and npm run typecheck — both clean; the gate arbiter returned RUN for each (container scope never defers), so neither was deferred
• npm run check:gate-manifest — all 38 verify:cheap gates are enforced in CI ... and the 35 static gates are documented consistently
• npm run sitemap:check, docs:check-links (4742 repo path references resolve), check:outstanding-issues, check:ledger-write-discipline — all pass
• npx prettier --check on every changed file — All matched files use Prettier code style!
• Bundle measured on two cold builds (rm -rf .next first, BUILD_ID mtime checked against the clock each time): mockups 611.6 KiB gzip, 160 chunks, 133 routes, −0.3% against the committed baseline. Against the last recorded clean measurement (2026-09-01, /issues #QSHHGK: 645.1 KiB / 165 chunks / 138 routes) that is −33.5 KiB and −5 exclusive chunks. Production is 1738.3 KiB / +5.0%, unchanged by this work and already tracked as #QSHHGK.

npm run check:dead-code-candidate -- --diff origin/main REFUSES this diff, and I am not reporting it as green. 64 of 201 candidates refuse. Every refusal is a bare-symbol-name collision on a file-local or framework-convention identifier — sections, activeIndex, documentTitle, Canvas, and metadata, which exists in roughly 150 route files — because that gate matches names repo-wide and whole-file deletion surfaces every module-local const. Run per exported symbol instead, every named component export comes back CLEAR and the only export-level refusals are the seven metadata declarations. The adversarial reviewer independently re-ran it, read every distinct refusal reason, and pulled the pinning file for the two that could plausibly have been real (SourcePreviewPopover, pinned by a test importing the production module; Composer, pinned by a synthetic fixture string) — both collisions. No threshold and no refusal-list entry was changed. One correction to an earlier commit message: that per-symbol run covered 24 declarations I extracted myself, not 17 candidates the gate emitted; the gate emits none for default exports.

• UI verification not run: the only non-mockup source change is mockups-layout-client.tsx, which is the /mockups route-group shell and 404s in production. Chromium mockup journeys run in the advisory chromium-mockups lane, not the required one.
• Not run: any provider-backed gate (eval:*, verify:release, check:supabase-project, test:live). None applies.

Risk and rollout

• Risk: Low — every deletion is design scratch that 404s in production, and the two non-deletion code changes are confined to the /mockups shell. The residual risk is a wrong supersession call — mitigated by requiring exact code identity, by the adversarial review that withdrew two candidates, and by git history remaining the archive.
• Rollback: git revert either commit independently. The policy commit contains no deletions, so it can stand alone if the sweep is reverted.
• Provider or production effects: None
• RAG impact: none — no ranking, retrieval, selection, or eval surface is touched. src/lib/rag/rag-eval-cases.ts and src/lib/eval-document-matching.ts were identified during the survey as mockup-exclusive by route reachability while being imported by nine scripts and seven tests; the policy classifies them Tier C explicitly so they can never become cleanup candidates.

Clinical Governance Preflight

• 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

No clinical behaviour changes in this PR. The preflight is completed because the diff touches paths the policy classifies as clinical-risk, not because clinical output moved.

Notes

Three findings are filed as /issues inbox requests rather than fixed here, because each belongs to someone else or to another change:

1. The calculators mockup still serves clinical directives production deleted for safety. PR fix(calculators): enforce clinical safety and evidence governance #2491 (2026-09-01) cut src/components/calculators/calculator-pathways.ts from 296 lines to 65 on clinical-safety grounds; the mockup copy still carries all of it — 15 matches for ECT|admission|discharge|refer|prescrib|commence|titrat against 0 in production, including "Initiate pharmacotherapy; consider psychiatry referral" and "Assess psychotic features and ECT indications". This is not a patient-facing exposure: /mockups/calculators-* is not in DEVELOPER_GATED_PATH_PREFIXES, so it 404s in production. It is visible in dev and preview. The calculators tree is interconnected and can only come out as one unit, and the fix is a call for whoever owns fix(calculators): enforce clinical safety and evidence governance #2491.
2. Retiring answer-evidence-popups removed the repo's only source-text heading-hierarchy contract, added by Fix typography audit issues #1294 for a regression that had already recurred once. The ~375 DOM-level heading assertions elsewhere never render a mockup gallery page. Deleting the test was correct — it readFileSync'd its own subject — but the gap is real.
3. Two pieces of dead wiring beside this surface: src/components/clinical-dashboard/source-preview-popover.tsx has zero importers anywhere in src/, and src/proxy.ts:49 redirects /mockups/document-search-command, a route that no longer exists.

Separately fixed here because it caused the original mis-triage: docs/answer-page-redesign-handover.md still said "design settled, not built" after the design shipped across five PRs, and had been edited twice after the build began without the status changing.

About 15 files (~10,000 lines) across therapy-navigation, universal-search, settings-search, the nine Tools layouts and the warning studies came back genuinely undecided. Per the policy, "parallel draft, no recorded winner" is a legitimate stable resting state rather than a backlog item. They stay, correctly labelled, and the new check stops the index drifting away from the tree again.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_015UPvNZYvyuDxc1o7xfTGCS

---

Generated by Claude Code

---

Note

Low Risk
Changes are confined to dev-gated mockup routes and repo gates/docs; production patient flows are untouched, with residual risk limited to an incorrect retirement if the evidence bar were wrong (mitigated by the new check and recorded successors).

Overview
Introduces a written-record gate for mockup cleanup and uses it to retire seven design-scratch routes (~4k+ lines), not a broad filename-based sweep.

Policy and enforcement: docs/mockup-retirement-policy.md defines tiers (design scratch vs developer-gated live prototypes vs fixtures), a six-point evidence bar, and npm run check:mockups (scripts/check-mockup-retirement.mjs). The check enforces mockups/README.md completeness, retired-table accuracy, and --diff auto rules (no unrecorded deletes, no Tier B removals, import/CSS/route-literal references). It is added to verify:cheap and CI when docs/static-heavy paths change; gate docs now count 37 static checks in verify:cheap.

Sweep: Removes seven mockups (answer-evidence-popups, answer-home-proposal, document-navigation pane/final-review, three document-phone variants) plus their component modules; updates mockups/README.md with a ## Retired mockups table and corrects several families (answer, document nav, calculators, tools). mockups-layout-client.tsx drops chrome-suppression branches for retired paths.

Docs/hygiene: Corrects mockup exemption claims (CodeRabbit, knip, ESLint carve-outs); links the policy from docs/README.md and wiring docs; marks answer redesign handover as shipped; ignores docs/branch-review-records/ in Prettier so content-addressed ledger rows are not reformatted away; refreshes sitemap and repo-awareness snapshot counts (197 pages, 130 mockup routes).

^{Reviewed by Cursor Bugbot for commit fce054c. Configure here.}

[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: 1a1ba21b-32f4-472e-9e63-5b2926c1133b

---

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 ↗︎.

[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:03:45.749527Z	8a184b5	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.

[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_917e3d96-8940-4431-bd20-d8c92f082116)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8a184b5aec

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

CI triage

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

• Production UI (3) — 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 #15071 (failure).

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_af3515d9-ddca-48f5-82cb-8bf810a530e7)

[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_f3d5a43b-182d-49c6-bcbb-6b692d43ab5b)

[BigSimmo]

Re-verified at eafbca91, and two corrections to the body above

main advanced 25 commits while the review threads were being worked, so the branch was merged forward twice and everything was re-run against the merged tree. Two numbers in the PR description are stale as a result, and one of them matters.

Corrections

• The description says 13 deleted mockup file(s). It is 14. That is not drift — it is the direct effect of the third Codex fix in 0a45136e: dropping the filename filter from deletedMockupFiles brought tests/answer-evidence-popups-heading-contract.test.ts into the scan, which the old naming filter had excluded. The description was written before that fix.
• The unit-suite line (947 files / 12098 tests) predates both merges. Current: 948 files, 12,181 passed, 1 skipped, 0 failed.

Merge conflicts resolved

The first merge conflicted on three files, all generated — data/outstanding-issues-snapshot.json, data/repo-awareness-snapshot.json, docs/scripts-index.md. Resolved by taking main and re-running npm run docs:update, which also adopts c0ee4dd's fix for that recurring collision (/issues #Y090R5). The second merge, onto 969cc7f8, was clean — confirmed with git merge-tree --write-tree before merging rather than after.

Gates re-run on the merged tree

• npm run verify:pr-local — 31 gates completed, failed: (none), not reached: (none). It escalated to heavy scope and ran the full production build, lint, typecheck, the whole unit suite, docs:check-links, check:gate-manifest, check:pr-policy, and both offline RAG harnesses.
• npm run check:mockups — self-test passed; 72 mockup route(s) indexed, 14 recorded as retired; 14 deleted mockup file(s), each recorded and unreferenced.
• npm run docs:check-inventory — 285 script files, 288 npm scripts, current after the merge. This gate had already gone stale twice on this branch as main added scripts, so it was re-checked rather than assumed.
• Both snapshot gates and sitemap:check — in step.
• npx prettier --check on every changed file — clean.

Unchanged from the description: no provider-backed gate was run, and check:dead-code-candidate still refuses this diff on bare-symbol-name collisions, which is reported there in full rather than presented as green. No threshold and no refusal-list entry was touched.

All three Codex review threads are answered and resolved. Each reply states the reproduction before the fix, because each finding was reproduced first.

---

Generated by Claude Code

[BigSimmo]

Advisory UI is failing, and it is not this PR's — with the reproduction

Failing check: Advisory UI (chromium-mockups lane) on eafbca91. One test of 130: tests/ui-tools-search-mode-mockup.spec.ts:122 — "matches the exact displayed tool title after normalising punctuation". 127 passed, 2 skipped. It also failed on the previous head, c4c0a5d1.

Locator: locator('[data-testid="tools-search-mode-mockup"]:visible').getByText('1 tool', { exact: true })
Expected: visible — element(s) not found

Why it is not this PR's

Every file in that test's dependency chain is byte-identical to origin/main on this branch — git diff origin/main...HEAD returns nothing for src/lib/tools-catalog.ts, src/lib/smart-search-intent.ts, src/components/tools/tools-search-results-page.tsx, src/components/tools-page-mockups/**, src/app/mockups/tools-search-mode/**, or the spec itself. This PR's entire src/ footprint is seven deleted mockup routes, six deleted mockup components, and mockups-layout-client.tsx.

That last file is the only one that could plausibly reach a Tools route, so it is worth being explicit rather than waving it off: the change removes three pathname predicates that matched /mockups/document-navigation-pane, /mockups/document-phone-* and /mockups/answer-home-proposal, and drops their negations from two !isA && !isB && … chains. For a /mockups/tools-search-mode pathname every one of those predicates was already false, so every negation was already true and both chains evaluate identically before and after. The 127 passing tests in the same lane — including four others in this very file that load the same route through the same shell — corroborate that.

The actual cause, reproduced offline

ToolsSearchModeMockup is a seven-line wrapper around the production ToolsSearchResultsPage, so this test asserts production catalogue-search behaviour. The page counts results with rankToolRecords(query, undefined, smartExpansions, …). Running that exact call on this tree:

query: "Risk & Safety"   naturalLanguage: false
count: 3
 - risk-safety    | Risk & Safety  | score 26 | title,keywords,description
 - safety-plan    | Safety plan    | score 13 | title,keywords,description
 - differentials  | Differentials  | score  5 | keywords,description

The catalogue returns 3, and the test asserts 1. That is a pure function over tools-catalog.ts, which this branch does not touch — so the assertion is false on main too, and no re-run can change it. I am not spending the one permitted re-run on a deterministic arithmetic failure.

The behaviour changed on main under #2508 "add native Smart catalogue matching" (2026-09-01) and #2510 "Add governed clinical Sources catalogue" (2026-09-02) — both landed after this test was last green. Safety plan matches on its safety keyword and Differentials on its risk keyword, so a two-word query that used to isolate one title now pulls in two neighbours.

It does not show up on any other open PR because Advisory UI only runs when a PR touches mockup scope, and this is currently the only such PR. That is why it looks like this PR's failure and is not.

Proposed patch — deliberately not applied here

The test's stated purpose is punctuation normalisation (Risk & Safety typed against the displayed title); the result count was incidental scaffolding, and it is the scaffolding that broke. The minimal fix is to assert what the test is actually about:

   test("matches the exact displayed tool title after normalising punctuation", async ({ page }) => {
     const mockup = await gotoMockup(page, 1440);
     await page.locator('[data-testid="global-search-input"]:visible').fill("Risk & Safety");

-    await expect(mockup.getByText("1 tool", { exact: true })).toBeVisible();
     await expect(mockup.getByRole("heading", { level: 2, name: "Risk & Safety" }).first()).toBeVisible();
+    await expect(mockup.getByRole("article").first()).toContainText("Risk & Safety");
   });

That keeps the punctuation contract and the exact-title-ranks-first contract, and stops pinning a count that catalogue growth will keep invalidating.

I have not applied it, and I am not going to from here. Whether an exact title match should collapse to one result is a product decision about catalogue search, not a test-hygiene question — and if the answer is "yes", the fix belongs in the ranker, which is a search-ranking surface that must not be edited inside a mockup-retirement PR. Either way it belongs to whoever owns #2508 and #2510. Widening this PR to reach it would be exactly the scope creep the policy in this PR exists to prevent.

Advisory UI is not aggregated by pr-required, so this does not block the required set.

---

Generated by Claude Code

[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_a7964f18-b9f8-4e5e-9013-6e20915f9072)

[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_4bff095f-a570-4871-93b6-3cf53ca84ac8)