diff --git a/docs/branch-review-ledger.md b/docs/branch-review-ledger.md index 2007d1c9b6..3dfa10c3b9 100644 --- a/docs/branch-review-ledger.md +++ b/docs/branch-review-ledger.md @@ -749,3 +749,5 @@ Records before 2026-07-28 were written by hand and had drifted: 146 lines carrie | 2026-08-08 | claude/differentials-inpage-navigation-h2u8fq (PR #1715) | f0b27ec857a70130d1616ddc1ccae1c9952c697b | heavy review-and-fix PR #1715 differentials in-page navigation | merge-blocker cleared (origin/main sync); no P0/P1 findings; phone-chrome + verify:pr-local green on f0b27ec8 | merge-tree clean post-sync; verify:phone-chrome lock-parity+runtime PASS, contracts 119 passed, changed-browser ui-tools passed, focused-browser 7 passed (19.4s); verify:pr-local Test Files 523 passed (523), Tests 5547 passed \| 4 skipped (5551); lint+typecheck+build+rag fixtures green; 0 unresolved review threads | | 2026-08-08 | claude/ds-doc-corrections | b4051d21f38755f7d37dbc2b49994f689af801b5 | M1 stranded doc corrections, final reviewed head (adds the review-response commit: COMPONENTS.md section 4 integration-vs-adoption split and the re-measured ui-primitives row) | merged to main as 8cffad59a. Supersedes the 534405600 record, which was accurate at that head but predates the review pass. Three findings, all valid and all fixed: Codex caught four future-dated 2026-08-09 records (corrected to the 2026-08-08 authoring date by f3a91c67c, verified none remain); CodeRabbit caught 'Select/choice controls remain separate adoption work', wrong on both axes since select.tsx consumes FormField and Select has 2 production importers while SearchField has zero; CodeRabbit caught a stale '27 adopted', and re-measuring that row also corrected 686 to 698 lines and 200 to 157 production importers of ui-primitives (200 was close to the 202 mockup-inclusive figure) | prettier --check . pass whole-tree; check:outstanding-issues pass (274 rows, unique ids, no ids deleted from base); adoption figures read from the generated adoption-manifest.json; docs-only diff so no unit, lint, typecheck or browser gate applies to it | | 2026-08-08 | claude/ds-tap-and-linkaction | 6916c80526603514d91bd29d224959dd420af59c | M5 LinkAction tone refusal plus re-measured corrections to outstanding-issues #270, #118 and #269 — final reviewed head, adds the tone?: never fix, its type-contract test and both regenerated manifests | PR #1720, superseding the 824c1b74a record. Codex found the Omit form still accepted tone through a spread; verified with a focused tsc probe before changing anything (Omit accepted the spread with no diagnostic, tone?: never rejected it with TS2345), because excess-property checking only fires on object literals. Fixed with tone?: never plus a type-level contract test that stops compiling if the prop widens back. CodeRabbit's future-dated finding fixed in ff307cc5b. CodeRabbit's ledger-scope finding does not apply: that row records a different ref and head and was accurate as written, but a superseding row for the final #1719 head was appended anyway since its scope grew after the review pass | tsc -p tsconfig.typecheck.json --noEmit exit 0 zero diagnostics; lint exit 0; check:design-system-contract exit 0 (676 production files, legacy shadow aliases 228 confirming the #262 re-measure, adoption 53 components 55 roots, design-sync 53 components and 7 guidelines); check-icon-scale.mjs --strict exit 0; vitest threads pool 3 files 164 tests passed; check:outstanding-issues pass; check:branch-review-ledger pass; prettier --check . pass whole-tree; main merged in with merge-tree proven clean first and an id-set proof over both merge parents showing 274 ids each side, none lost, none invented | +| 2026-08-08 | claude/ds-close-276 (PR #1724) | 75c89993f3ea23b70a250f605b21437b4ea9aac8 | PR #1724 review-and-fix | fixed Codex P2 wrong #118 Lighthouse cause (150 overwrite vs 151 pin); dispositioned CodeRabbit #276 archive claim as false (issues:done move); merge-tree clean; required CI was green on prior tip 8ae8c48f; no Bugbot findings | check:outstanding-issues pass; prettier --check docs/outstanding-issues.md pass; no provider-backed checks | +| 2026-08-08 | claude/ds-close-276 (PR #1724) | 4baa9a1b42fa05731a6f983b3e0d0ebbd37f5271 | PR #1724 review-and-fix | synced origin/main (#1725 conflict on outstanding-issues resolved by preferring main queue then re-applying #276 done + corrected #118 diagnosis); Codex P2 fixed; CodeRabbit #276 archive claim dispositioned false; merge-tree clean after sync | check:outstanding-issues pass; prettier --check docs/outstanding-issues.md pass; merge-tree clean vs origin/main; no provider-backed checks | diff --git a/docs/outstanding-issues.md b/docs/outstanding-issues.md index 2bd799438b..ee74c46733 100644 --- a/docs/outstanding-issues.md +++ b/docs/outstanding-issues.md @@ -163,7 +163,6 @@ removed after current-main verification; it is not missing recommended work. | 110 | `#255` | A2 | High — Cloud/browser gates | Next environment image update | 2–4 hours | Align Cloud Playwright browser builds with lockfile pin; document CI delegation until then. **Stop:** do not force mismatched Chromium revisions. | | 111 | `#256` | A2 | High — mode section nav | Next information-page / mode-nav pass | 2–4 hours | Declared information-page section sets whose target ids nothing renders — verify each set against the rendered DOM per route; render anchors or delete the set. **Stop:** do not audit by grepping for `id=` alone (sectionId props exist). | | 112 | `#257` | Optional | High — formulation/specifiers flake | Standing until second reproduction | 15–30 min | Single unreproduced ui-formulation flake when run with ui-specifiers — record a second sighting only; do not quarantine until three on the same SHA. **Stop:** do not weaken assertions. | -| 113 | `#276` | Optional | High — design-system links | Next LinkAction tone follow-up | 30–60 min | LinkAction accepts `tone` via `BaseProps` but never reads it, so `tone="inherit"` is silently ignored while sibling links honour tone. Decide honour vs refuse on `LinkActionProps`; refusing is probably right for a forward-action link. **Gate:** `npm run check:design-system-contract` plus the Links block in `tests/ui-v2-components.dom.test.tsx`. **Stop:** do not bundle with unrelated link policy work (#263 follow-on rows). | @@ -212,7 +211,7 @@ removed after current-main verification; it is not missing recommended work. | #101 | P3 | rec | Canary-gated retrieval parallelisation candidates | **Outcome:** independent retrieval stages stop running serially, proven by a live canary pair. Candidates: metadata/memory/visual hydration triples repeated on four branches (`rag.ts:2460,2493,2521` and three more) while `rag.ts:2751-2804` already parallelises three RPCs in one `Promise.all`, so the omission is inconsistency rather than intent; the nested `await`-in-loop scope enumeration (`search-scope.ts:202,328`); typeahead results never cached (`rag.ts:2698-2711`); universal-search coalescing (`/api/search` has it, `/api/search/universal` does not). Each changes candidate assembly, truncation, or what the next keystroke returns, so each needs 36/36 retrieval plus recall 1.0 and zero per-case rr regressions. Distinct from #001 (semantic rerank). Resolved #075 and #083 are the precedents for why these are gated rather than free. **Stop:** needs the #098 harness and explicit canary approval first. | `docs/audit/latency-audit-2026-07-28.md` L2-1/L2-2/L2-8/L1-5 | 2026-07-29 | | #102 | P3 | task | Apply the additive `documents` index debt (operator) | **Outcome:** bare-column `ILIKE` and the paged status scan on `documents` are index-served on hosted. `documents_title_trgm_idx` indexes a CONCATENATED expression, so the bare-column predicates in `api/documents/route.ts:193` and `rag-candidate-sources.ts:477` (RAG path) cannot use it and fall back to scanning; `search-scope.ts:271-277` sorts per page against the single-column `documents_status_idx`. **Runbook prepared 2026-07-29 — NOT applied, item stays open:** three `CREATE INDEX CONCURRENTLY` statements authored and reviewed in `docs/operator-apply-performance-latency-remediation.md` — additive, though **the "recall is byte-identical" claim was RETRACTED on 2026-07-29 review**: `fetchDocumentTitleAliasRows` (`rag-candidate-sources.ts:482`) applies `.limit(12)` with no `ORDER BY`, so a new index can change which title-alias documents feed candidate assembly. Only the documents-list use stays ordering-safe; `(status,id)` is canary-gated too — see runbook, and making that `.limit(12)` deterministic first does **not** lift the gate — an unordered `LIMIT` has no stable selection to preserve, so imposing an order can pick a different twelve and is itself an ordering behaviour change on a retrieval surface, which AGENTS.md requires a canary pair for. Sequencing the ordering fix first is worthwhile (unordered `LIMIT` on a retrieval input is latent nondeterminism regardless) but yields two canary-gated changes, not one (PR #1377 review). **Deliberately NO migration file:** an additive-index migration without a synchronized `schema.sql` mirror and regenerated drift manifest is exactly what closed PR #1312, and the mirror cannot come first because `required_indexes` in `search_schema_health()` (`schema.sql:3178`) runs against live. **Next (operator):** **author the migration first** — `supabase/migrations/` is the source of truth and `schema.sql` only a mirror, so hand-run operator SQL never reaches staging, disaster-recovery replay, or a local `supabase db reset`, and a `required_indexes` registration would fail there (PR #1377 review); follow the `20260717170000_registry_projection_cleanup.sql` idempotent pattern. **That migration must also carry the health-function change** — `required_indexes` lives inside `search_schema_health()`, which is redefined by `create or replace function` in eleven migrations (copy `20260705180000_reconcile_search_health_indexes.sql:62`); editing `schema.sql:3177` alone moves only the mirror and leaves the indexes unmonitored on hosted (PR #1377 review). Then apply concurrently, confirm `indisvalid`, mirror both the index statements and the identical function body into `schema.sql`, run `npm run drift:manifest` (Docker), and deploy the migration LAST — in that order, in one change. Expect `check:drift` to report them as unexpected between steps 1 and 2. **Rollback is three deployed phases, not the reverse of one:** retract `required_indexes` via its own `create or replace function` migration and deploy → drop concurrently live → only then deploy the `schema.sql` removal plus an idempotent forward `drop index if exists` migration, because Supabase wraps migrations in a transaction and a plain `DROP INDEX` there takes the lock the concurrent procedure exists to avoid (PR #1377 review). | `docs/audit/latency-audit-2026-07-28.md` L2-3/L2-5; `docs/operator-apply-performance-latency-remediation.md` | 2026-07-29 | | #117 | P2 | rec | Therapy Compass catalogue payload is the mobile LCP outlier | **Outcome:** `/therapy-compass` mobile LCP lands near the other mobile routes instead of double them. **Measured 2026-07-30** by the new pre-merge Lighthouse budget: mobile LCP 5229 ms, TBT 612 ms, CLS 0.142, against 2123-2460 ms on every other mobile route and 826 ms on desktop — so it is client-side work under mobile CPU/network throttling, not server latency. **Cause before this PR:** `useTherapyData` fetched `public/therapy-compass-data/therapies-index.json` (the thin browse index; 205 records) for the home/search/pathways screens, so the download plus JSON parse sat on the critical path before content painted. **Current split:** home now fetches `public/therapy-compass-data/therapies-home.211dab554c4ec62d.json` (136,288 bytes raw), pathways use the thin browse index, and search loads the full prose corpus (#1471). 90% of the index weight is long-form clinical prose — indications 159 KB (26%), contraindicationsOrCautions 139 KB (23%), bestUsedFor 73 KB (12%), clinicalSummary 67 KB (11%), patientPopulation 59 KB (10%), targetSymptoms 48 KB (8%) — while name, slug, category, tags and setting together are 54 KB (7%). **Remaining decision for search/pathways: rendered on the card, matched by search, or neither.** `therapy-card.tsx` references five of those prose fields and the same index feeds the search screen, so stripping fields could silently change clinical display or search recall. **Next:** settle that per-field question, then either pre-truncate prose that only feeds card display, or move search matching server-side / load prose on first keystroke. **Gate:** `check:therapy-data-index` plus the therapy Playwright journeys; re-measure with `npm run verify:lighthouse`. **Stop:** do not drop a field from the catalogue payload without confirming no card renders it and no search path matches on it. Same class as #013 (route-chunk / catalogue JSON weight), different route and now measured. | session 2026-07-30 Lighthouse budget first run; PR #1404; PR #1489 | 2026-07-30 | -| #118 | P2 | task | Adopt the visual and Lighthouse baselines so the two new gates actually gate | **Outcome:** `visual-baseline` and `lighthouse-budget` stop reporting and start blocking. **Detail:** PR #1404 added both as `continue-on-error` jobs outside `pr-required`, deliberately. `tests/ui-visual-baseline.spec.ts` has no committed baselines, so all six targets (dashboard-shell, dashboard-shell-phone, search-results-band, search-results-band-phone, document-viewer, therapy-compass-home) fail with a missing-snapshot error by design; the job uploads them on every run (run 30513537912, artifact 8748062487, 31 files). `tests/__screenshots__/` still holds only README.md, re-checked 2026-08-08. `lighthouse-budget.json` ships `enforce: false` with `baseline: null`, so the grader warns rather than grades. **Owner decision 2026-08-08: adopt the baselines, advisory-only first, and promote to required only after they have held across a few runs** — the workflow comment asks for that soak explicitly. **Sequencing constraint recorded the same day:** the owner had design changes merging at the time, and pixel baselines frozen while the look is still moving go red on the next merge, which is the churn the hold exists to avoid. Trigger the ubuntu job once that merge wave has landed, not before. **Next:** (1) trigger `visual-baseline` on a UI PR, download the artifact, review the six PNGs and commit them under the platform-scoped screenshots directory that `playwright.visual.config.ts` names in its `snapshotPathTemplate` — from CI, never a developer machine, because font hinting differs between them; (2) run `npm run check:lighthouse-budget -- --update` against a known-good CI build and flip `enforce`, but not before #117 or the baseline pins a known-slow route; (3) then add each job to `pr-required` and drop `continue-on-error` in the same edit. **Also:** PR #1404 added the first rendered-effect contract for #094, but 37 of the 38 unlayered visual classes still carry exemptions in `tests/helpers/style-contracts.ts` rather than contracts; and `scripts/run-lighthouse-budget.mjs` duplicates about 50 lines of the isolated-server boot in `scripts/run-playwright.mjs`, deferred to avoid destabilising the required UI gate in the same change. **Stop:** do not make a missing baseline skip instead of fail — that is the soft-skip-green pattern `AGENTS.md` forbids. | session 2026-07-30; PR #1404 | 2026-07-30 | +| #118 | P2 | task | Adopt the visual and Lighthouse baselines so the two new gates actually gate | **Outcome:** `visual-baseline` and `lighthouse-budget` stop reporting and start blocking. **Detail:** PR #1404 added both as `continue-on-error` jobs outside `pr-required`, deliberately. `tests/ui-visual-baseline.spec.ts` has no committed baselines, so all six targets (dashboard-shell, dashboard-shell-phone, search-results-band, search-results-band-phone, document-viewer, therapy-compass-home) fail with a missing-snapshot error by design; the job uploads them on every run (run 30513537912, artifact 8748062487, 31 files). `tests/__screenshots__/` still holds only README.md, re-checked 2026-08-08. `lighthouse-budget.json` ships `enforce: false` with `baseline: null`, so the grader warns rather than grades. **Owner decision 2026-08-08: adopt the baselines, advisory-only first, and promote to required only after they have held across a few runs** — the workflow comment asks for that soak explicitly. **Sequencing constraint recorded the same day:** the owner had design changes merging at the time, and pixel baselines frozen while the look is still moving go red on the next merge, which is the churn the hold exists to avoid. Trigger the ubuntu job once that merge wave has landed, not before. **Next:** (1) trigger `visual-baseline` on a UI PR, download the artifact, review the six PNGs and commit them under the platform-scoped screenshots directory that `playwright.visual.config.ts` names in its `snapshotPathTemplate` — from CI, never a developer machine, because font hinting differs between them; (2) run `npm run check:lighthouse-budget -- --update` against a known-good CI build and flip `enforce`, but not before #117 or the baseline pins a known-slow route; (3) then add each job to `pr-required` and drop `continue-on-error` in the same edit. **Also:** PR #1404 added the first rendered-effect contract for #094, but 37 of the 38 unlayered visual classes still carry exemptions in `tests/helpers/style-contracts.ts` rather than contracts; and `scripts/run-lighthouse-budget.mjs` duplicates about 50 lines of the isolated-server boot in `scripts/run-playwright.mjs`, deferred to avoid destabilising the required UI gate in the same change. **Stop:** do not make a missing baseline skip instead of fail — that is the soft-skip-green pattern `AGENTS.md` forbids. **Lighthouse half is currently failing for an unrelated reason, measured 2026-08-08 on PR #1720 (run 31248683948).** **CORRECTION 2026-08-08 (PR #1724 Codex review):** this is NOT a new CI-runner Chromium bump. Commit `4a9d81d` (#1716) already pinned the job to Playwright's Chromium 151, and the pre-#1710 baseline (`4f1bbbb^:lighthouse-budget.json`) already recorded `HeadlessChrome/151`. PR #1710 (`4f1bbbb`) then replaced those baselines with Chromium 150 data, so the advisory refuses to grade 151 measurements against a stale 150 overwrite. Prefer restoring or comparing against the already-known Chromium 151 baseline rather than a blind `--update` that silently re-accepts current numbers. Symptom unchanged: all ten route/strategy pairs report 'baseline measured by a different browser ... refresh with --update' and the job exits 1 with 'Evidence incomplete. Nothing is graded from this run.' That is a refuse-to-grade, NOT a budget breach — the measurements themselves were at or better than baseline, with mobile-root improving from LCP 3930ms to 2304ms. After #1722 the advisory is scoped to `perf_changed` (not every ui/build PR) and a `workflow_dispatch` "Refresh Lighthouse baseline" path exists — still commit only after reviewing the artifact. Refresh from CI artifact provenance only (that run uploaded `lighthouse-budget-31248683948`, artifact id 9019375154) — the script keys on the browser UA, so developer-machine numbers are rejected the same way. | session 2026-07-30; PR #1404 | 2026-07-30 | | #142 | P3 | task | Four loose dated docs need source and migration edits before they can be filed | **Outcome:** every dated point-in-time doc lives in `docs/audit/` or `docs/archive/` as `docs/README.md` requires, not loose at the `docs/` top level. **Detail:** PR #1436 filed the five that were docs-only moves. These four are referenced from outside `docs/`, so relocating them means editing source, tests and migration SQL comments — a different risk class than a docs tidy, and not worth bundling into one: `capacity-review.md` (`scripts/soak-test.ts`), `tenancy-defense-in-depth-review.md` (`src/lib/owner-scope.ts`, `tests/owner-scope-guard.test.ts`, two migrations, `SECURITY.md`, `.claude/agents/clinical-governance-reviewer.md`), `operator-apply-july8-batch.md` (three migrations plus `supabase/schema.sql`), `scale-readiness-review.md` (one migration). Also note `forward-codify-retrieval-rpcs-workorder.md` is indexed as a completed workorder but live is still ahead of the repo on those RPCs, so archiving it would misrepresent open operator work. **Next:** treat as low priority — the docs are correctly indexed and reachable where they are; only file them if a pass is already editing those migrations. Editing applied migration SQL is subject to `npm run check:migration-role`'s immutability pin. | PR #1436; session 2026-07-30 | 2026-07-30 | | #147 | P2 | rec | Mobile CLS breaches four routes, and it reproduces exactly offline | **Outcome:** mobile CLS is under 0.1 on every measured route, or each remaining breach has a recorded reason. **Measured 2026-07-30 with the LOCAL OFFLINE production harness** (`CHROME_PATH=/opt/pw-browsers/chromium npm run verify:lighthouse -- --keep`; Lighthouse 12.8.2, Chromium 141.0.7390.37, demo corpus, inert loopback Supabase). Mobile CLS: `/dsm` 0.363, `/documents/search` 0.220, `/therapy-compass` 0.142, `/` 0.023 — `/forms` did not measure locally (Lighthouse `NO_NAVSTART`, its own "run again" transient), but the live dispatch put it at 0.212. Desktop passes everywhere: 0.016–0.097. **The finding that matters is that these reproduce the live production dispatch EXACTLY.** Against run `30548662649` on `psychiatry.tools`, all four locally measurable mobile routes match to three decimals — 0.023 / 0.142 / 0.220 / 0.363 on both — and the desktop range matches at both endpoints, 0.016–0.097. So CLS on these routes is deterministic layout structure, not network, latency, or production data. Three consequences: (a) the CLS half of `#017` is debuggable and gate-able locally at zero provider cost; (b) `#017`'s recorded blocker "prod server hard-requires Supabase secrets" is stale — `scripts/run-lighthouse-budget.mjs` builds and serves an offline production app precisely to sidestep that, and its earlier note that dev-mode CLS looked "excellent at 0.00–0.04" was measuring DEV, which does not reproduce production; (c) re-dispatching the live workflow to re-measure CLS buys nothing. **LCP does NOT reproduce and must not be read from local runs:** local mobile LCP is 2014–2051 ms against 3639–4716 ms live, because the loopback server has no network latency. The LCP _ranking_ does survive — `/therapy-compass` is the outlier both locally (4978 ms, ~2.4x every other route) and live — which corroborates `#117` rather than replacing it. Mobile TBT, local: `/documents/search` 581 ms, `/dsm` 448, `/therapy-compass` 379, `/` 338. **Ranking by measured contribution, which is what `#017` asked for:** 1. `/dsm` CLS 0.363 (3.6x the threshold, the worst single number anywhere); 2. `/documents/search` 0.220; 3. `/forms` 0.212 (live only); 4. `/therapy-compass` 0.142, and separately the sole LCP outlier via `#117`; 5. `/` 0.023, which passes and needs nothing. **ATTRIBUTED 2026-07-30 — one cause dominates, and it is a self-inflicted round trip.** Driving Chromium directly against the same offline production build (Lighthouse mobile emulation: 412x823, DPR 1.75, 4x CPU throttle) with a `PerformanceObserver` on `layout-shift` reading `entry.sources[].node`: on `/dsm`, `/documents/search`, `/forms` and `/therapy-compass` the entire main content region moves **down 128px and straight back up 128px** within 15-60ms. Both moves score, so the round trip is pure cost with zero net movement. It is **100% of `/documents/search`** (0.110 down + 0.110 up = 0.220) and about 75% of `/dsm`. The shifting element is the `max-sm:pt-[var(--phone-overlay-chrome-h)]` wrapper around `
`, i.e. the phone overlay chrome reserve. **Mechanism, pinned by a MutationObserver timeline on the root style attribute rather than inferred:** the property goes CSS seed -> `200px` -> `72px`, and the decisive line is that the 200px is written when the header stack **already measures 72px** — `t=1552ms reserve=200px stack=72`, corrected to `72px` at `t=1612ms`. So `usePhoneOverlayChromeReserve` (`src/components/clinical-dashboard/use-phone-overlay-chrome-reserve.ts`) publishes a **stale** measurement: its `useLayoutEffect` reads `stack.offsetHeight` while the stack is still transiently 200px, and the write lands after the stack has already collapsed to 72px; its `ResizeObserver` then corrects it. The CSS seed at `globals.css:375` (`calc(max(0.5rem, var(--safe-area-top)) + var(--shell-header-h))` = 72px on a zero-inset profile) is **correct for the settled stack** — the seed is not the problem. **This corrects the mechanism recorded on `#130`** (now archived), which framed the defect as the seed under-reserving by `max(0, 0.5rem - inset)`, i.e. 0px on a notched iPhone and 8px elsewhere. Measured, the CLS driver is not an 8px seed shortfall but a 128px transient over-reserve written by the hook. Do not reopen `#130` on this; it is recorded here. **Control that makes the attribution trustworthy:** `/` never writes the property at all (no overlay stack) and is the one clean route at 0.023. **Variance, stated rather than smoothed over:** `/dsm` measured 0.363 (3 shift entries) and 0.219 (2 entries) on two runs — the round trip is the stable core and the third entry is intermittent. This harness has no network throttling, so `/forms` (0.310 local vs 0.212 live) and `/therapy-compass` (0.240 vs 0.142) run high locally; only `/dsm` 0.363, `/documents/search` 0.220 and `/` 0.023 reproduced the live dispatch exactly, and only those three should be treated as production-equivalent. **Next:** stop the hook publishing a measurement it is about to revise — defer the first publish until the stack has settled, or let the `ResizeObserver` be the only writer and trust the seed until it fires. That is a phone-chrome change, so it is governed by `docs/search-chrome-behaviour.md` and needs `npm run verify:phone-chrome` plus a before/after CLS pair from this harness. **Harness trap worth keeping:** attaching a `MutationObserver` to `document.documentElement` inside a Playwright `addInitScript` throws when the document element does not exist yet, which silently takes the CLS observer down with it and reports a uniform `CLS=0.000` across every route — a false clean bill, not a pass. Guard the attach. **Original next step, now done:** attribute the shifts to elements. Lighthouse's `layout-shift-elements` audit returned **zero items on every route** — the `cumulative-layout-shift` audit carries only `debugdata` — so attribution needs a driven Chromium session with a `PerformanceObserver` on `layout-shift`, reading `entry.sources[].node` and `entry.value`, against the same offline production build. Start with `/dsm`. **Gate — `#118` owns it, and this row supplies a constraint it was missing.** `#118` already tracks flipping `lighthouse-budget.json` to `enforce: true` and says not to do it "before `#117` or the baseline pins a known-slow route". These numbers make that concrete: pinning a baseline today would bake CLS 0.363 on `/dsm` in as the accepted value, so the CLS fixes must land first or the gate ratifies the breach. Separately, no baseline could have been committed from this run anyway — the grader correctly refused it as incomplete evidence because `/forms` produced no report, and that refusal was not overridden. **Reproduction trap:** without `CHROME_PATH`, `chrome-launcher` cannot find a browser in this container and every route fails; the harness reads `CHROME_PATH`/`PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` (`run-lighthouse-budget.mjs:291`) but nothing sets either, even though `PLAYWRIGHT_BROWSERS_PATH` is set. Related to `#121`. Also seen: a truncated `progress` package in the npx cache broke Lighthouse startup entirely; clearing the npx cache entry fixed it. **Stop:** do not re-dispatch the live Web-Vitals workflow to re-measure CLS — it is reproducible offline for free. Do not commit a budget baseline from a run with a failed route. Do not treat local LCP numbers as production LCP. | `#017` live run `30548662649`; local `verify:lighthouse` 2026-07-30; `lighthouse-budget.json` | 2026-07-30 | | #149 | P2 | issue | `check:installed-lock-parity` only compares seven top-level packages, so transitive drift passes | **Outcome:** a session cannot run local gates against a `node_modules` that silently disagrees with the lockfile. **Evidence 2026-07-30:** the `SessionStart` hook reported "node_modules matches the lockfile, skipping install" while `brace-expansion` was installed at **1.1.16** and the lockfile pinned **1.1.18** — the CVE-2026-14257 patch. Every local gate run in that window was weaker than it appeared, including several `verify:cheap` runs reported as green during PR #1430/#1444 work. It surfaced only because `tests/installed-lock-parity.test.ts` asserts the patched behaviour directly (`maxLength` honoured); its failure was initially mistaken for a pre-existing repo defect, since it also failed on clean `main` **in the same stale container**. `npm ci --include=dev` fixed it. **CORRECTION 2026-07-30 (PR #1496 review, Codex):** an earlier version of this row said the parity check lives only in `verify:ui` and proposed adding it to `verify:cheap`. **Both were wrong** — `verify:cheap:internal` already runs `check:installed-lock-parity`, so that follow-up was a no-op, and it ran green throughout the stale window. The real gap is its **scope**: `scripts/check-installed-lock-parity.mjs` compares only seven top-level packages (`criticalInstalledPackages` = next, react, react-dom, eslint, playwright, typescript, vitest), so a stale **transitive** dependency is invisible to it. Proved by faking `node_modules/brace-expansion` back to `1.1.16` against the `1.1.18` lockfile pin: `npm run check:installed-lock-parity` **exits 0**. That also explains why the hook and the gate both reported parity while the tree was stale — neither was looking at the package that drifted. **Next:** broaden the check beyond the seven names — validate the full installed tree against the lockfile, or stamp the install with the lockfile hash and compare that — so transitive drift is caught rather than assumed absent. **Stop:** do not treat a green `check:installed-lock-parity` as proof the install is lockfile-current; today it means seven packages match. **Do not archive on the audit-worktree disposition (checked 2026-07-31):** several `comprehensive-audit-*` worktrees carry an uncommitted row archiving this as “Resolved 2026-07-31 — `check:installed-lock-parity` now validates every concrete package location in `package-lock.json`, including nested transitives”. That fix exists nowhere: not on `main`, not in any of the 42 worktrees, and not in any open PR. `main` still reads `criticalInstalledPackages = ["next", "react", "react-dom", "eslint", "playwright", "typescript", "vitest"]`. The sibling `#103` disposition from the same worktrees WAS verified true and landed in PR #1528; this one was not. **Second, worse instance measured 2026-08-08 — the gap is not only transitive version drift, it is structural completeness.** Two `npm install` runs were killed mid-extraction (a concurrent session ran `npm cache clean`; both exited **127 with an empty log**, no npm error). What survived looked complete: every package directory present at its locked version, and `check:installed-lock-parity` **passed**. But `@testing-library/dom/types/index.d.ts` was **0 bytes** and `@types/node` was **six files short**, missing `web-globals/importmeta.d.ts`. The result was **163 phantom `tsc` errors** — 135 x TS2305 'no exported member screen', plus `ImportMeta.dirname`, `Timeout` and `unref` failures — that read exactly like real code breakage, and `@rolldown/binding-win32-x64-msvc` was absent so Vitest died with `ERR_DLOPEN_FAILED`. A version comparison of any width cannot catch this; the installed files were the right version and simply incomplete. Cheap detection that worked: run the gate against pristine `origin/main` content as well — an identical error count proves the tree innocent and the install guilty. Repair that worked: `rm -rf node_modules` then ONE `npm install `, which reifies the whole tree from the lockfile without touching `package.json` or `package-lock.json`. Worth folding into this row's fix: a completeness check alongside the version comparison — but zero-byte tracked `.d.ts` plus each package's `main`/`types` entry point is NOT enough on its own. The measured miss was `@types/node/web-globals/importmeta.d.ts`, a non-entry file; `@types/node/index.d.ts` stayed present and non-empty, so that shallow check would still pass. Require a completeness method that rejects structurally incomplete installs when arbitrary package files are missing (for example a lockfile/package file inventory, an extract-integrity stamp, or an equivalent that fails closed on a deleted non-entry path), and prove it with a fixture that deletes a non-entry file while leaving entry points intact. | `scripts/check-installed-lock-parity.mjs`; `tests/installed-lock-parity.test.ts`; `package.json` | 2026-07-30 | @@ -314,7 +313,6 @@ removed after current-main verification; it is not missing recommended work. | #273 | P2 | task | The results band's max-[413px] wrap threshold is stale now that Sort and the phone selects are both gone | **Outcome:** the one-line phone results bar extends down to 320px instead of stopping at 414px, so the Filter trigger stops taking an otherwise-empty second row on the most common phone widths. **Detail:** `search-results-header-band.tsx` wraps the band's first line with `max-[413px]:flex-wrap max-[413px]:py-2`, justified in its own comment as "below 414px one line provably cannot hold count + query + sort + filter even with the query fully truncated". Both halves of that premise have since been removed: Sort became `sm`-and-up (PR #1689), and every mode's phone control became a compact trigger rather than a `w-full` select (#247). Measured in a real browser on the differentials band with the wrap class stripped at runtime, `scrollWidth - clientWidth` is **0 at 320, 360, 375, 390 and 402px** — the line fits at every width with room to spare. Left unchanged deliberately: the fix also changes documents, which is the reference layout the user approved, and it is a shared-geometry change with a 320-540px clip sweep asserting against it in `ui-smoke`. **Next:** delete the two `max-[413px]:` utilities, re-run the `ui-smoke` clip sweep and `ui-tools` phone rail assertions, and re-measure band height at 320/360/390 (expect 60px everywhere, versus 89px today below 414). **Stop:** do not raise the threshold instead of deleting it — it is not a narrower window now, it is an empty one. Do not re-measure with Sort mentally re-added; that control is gone below `sm` and is not coming back. | browser measurement 2026-08-07 on claude/search-bar-mobile-layout-buu0io; band comment; #247 | 2026-08-07 | | #274 | P2 | task | Services' Clear quick filters leaves the q param in the URL, so a reload restores the filter | **Outcome:** clearing a services quick filter survives a reload. **Detail:** `services-navigator-page.tsx`'s Clear runs `setLocalQuery({ urlQuery, value: "" })`, which clears local state only; the route still carries `?q=crisis`, so a remount or reload re-derives `activeQuickFilter` and the filter comes back. Raised by CodeRabbit against the phone sheet's `onClearAll` in PR #1706, but the phone path was deliberately wired to the *same* handler the desktop Clear button already used — the behaviour is pre-existing on desktop and was mirrored, not introduced. Fixing it in that PR would have changed a shipped desktop control's semantics under a phone-scoped change, so it was deferred rather than bundled. **Next:** add one clear path that both resets local state and pushes a route without `q` (or with the mode's default query), and point both the desktop Clear and the sheet's `onClearAll` at it; assert the URL after Clear in `ui-tools`. **Stop:** do not fix only the phone path — two Clear buttons that disagree about whether the URL changes is worse than one that is consistently wrong. | CodeRabbit review on PR #1706; services-navigator-page.tsx Clear handler | 2026-08-07 | | #275 | P2 | task | The shared filter trigger carries arbitrary spacing values inherited from DocumentFilterTrigger | **Outcome:** the phone filter trigger expresses its measurements as named tokens rather than bracketed values. **Detail:** `result-filter-control.tsx`'s `ResultFilterTrigger` uses `pr-[0.6875rem]`, `h-[1.0625rem]`/`min-w-[1.0625rem]` for the badge, and the raw breakpoint window `min-[414px]:max-[429px]` for the label. CodeRabbit flagged these against the design-token rule in PR #1706. Every one of them is copied *verbatim* from `DocumentFilterTrigger`, which shipped on main earlier and is the component this one was deliberately lifted from so the two cannot drift — so the finding is real but its scope is both call sites, not the new one. Changing only the copy would reintroduce exactly the drift the extraction removed, and each value carries a measured justification in its own comment (the asymmetric padding answers a stroked glyph against a filled pill; the breakpoint window is the one band that is single-line and short of width). **Next:** tokenise in `@theme` once, then update the trigger — there is now only one implementation, so it is a single edit. Confirm the badge and padding render identically at 393/402/414/430px before and after. **Stop:** do not tokenise the trigger without also retiring the values from the documents original, and do not treat this as licence to change the measurements themselves. | CodeRabbit review on PR #1706; DocumentFilterTrigger on main | 2026-08-07 | -| #276 | P3 | issue | LinkAction accepts a tone prop it never reads | src/components/ui/link.tsx: LinkActionProps = BaseProps & { href: string }, and BaseProps declares tone?: 'accent' \| 'inherit'. LinkAction destructures only { href, children, className }, so a call site can pass tone='inherit' and get the accent styling anyway, with no type error and no DOM leak to notice it by. The three sibling links (TextLink, ExternalTextLink, DownloadLink) all honour tone, so this is an inconsistency inside one module rather than a deliberate omission. Found while closing #263 (Track A4) and left alone because it is a behaviour change to a link's colour on adopted surfaces, not a defect on the #263 list. Next: decide whether LinkAction should honour tone (apply toneClass[tone] like its siblings) or refuse it (drop BaseProps' tone from LinkActionProps so the compiler rejects the call). Refusing is probably right — a forward-action link is always the accent by design — and is the smaller diff. Gate: npm run check:design-system-contract plus the Links block in tests/ui-v2-components.dom.test.tsx. | session 2026-08-07 closing #263 / COMPONENTS section 0.4; commit e674f6e20 | 2026-08-07 | | #277 | P2 | issue | docs/design-system/HANDOVER-2026-08-07.md is cited as provenance by nine ledger rows but is measurably wrong | Outcome: no session scopes design-system work from a document whose figures have already been disproved. Evidence: rows #261, #262, #264, #265, #266, #267, #268, #269 and #270 all carry 'session 2026-08-07 — design-system HANDOVER-2026-08-07 Track A1 handoff (PR #1678)' as their Source, and docs/design-system/README.md links it as 'measured state, the ordered plan'. Measured wrong so far, all corrected into the rows themselves rather than the document: its '229 --shadow-tight aliases' is the seven-token legacyShadowAliases total mislabelled as one token (real figure 100 sites across 55 files, total 228); its adoption figure was 24 unadopted against a measured 23; its claim that visual baselines cannot be generated on Windows is half true and led to the wrong conclusion, since the ubuntu CI job already produces the ones that count; and #270's '22 call sites pair a tap token with a dead numeric height' does not survive re-measurement at all (zero same-variant pairs, 84 cross-variant responsive step-downs that are not dead). The document itself still asserts the originals. Next: cheapest fix is a superseded banner at the top naming the ledger rows as the current source of truth, plus the same in docs/design-system/README.md's link text — not a rewrite, because the corrections already live in the rows and duplicating them re-creates the drift. If the live path should leave docs/design-system/, move the file to docs/archive/ (or the design-system archive) and update inbound links per docs/README.md; do not delete it, because the nine Source citations, the PR/commit record, and the handover's verification/gotcha sections are provenance the ledger is meant to preserve. Stop: do not re-copy its figures into any new plan or handover, do not delete the evidence, and do not silently correct it in place, which would leave the nine Source citations pointing at a document that no longer says what those rows were derived from. | session 2026-08-08 — measured while closing #263 follow-ups across PRs #1719 and #1720 | 2026-08-08 | ## Resolved / archive @@ -473,5 +471,6 @@ Move resolved rows here with the resolution date and a one-line outcome. Keep th | #259 | task | Ledger row for claude/pr-handoff-loop-prevention-54y5zr (PR #1670) is still owed | Resolved 2026-08-07, and not by this session: a Cursor review-and-fix sweep on PR #1670 appended the row for claude/pr-handoff-loop-prevention-54y5zr at dfe2946110e0ff93bd4acc571ae79c26b79a7a85 (scope 'PR #1670 heavy review-and-fix'), and refined the #1649 row's checks cell to name the exact gates after a CodeRabbit finding. The structural observation this row was opened for still holds and is worth keeping: a handoff whose deliverable IS a ledger append cannot append its own row without a second commit to that head cancelling its in-flight CI. What resolved it here was a DIFFERENT session picking the row up in a sweep that was already touching the branch — which is the practical answer to the pattern, and cheaper than either paying for a CI restart or writing the row post-merge against the squash commit. | 2026-08-07 | | #247 | task | Widen the one-line results bar to the six modes that pass a full-width phone select | RESOLVED 2026-08-07. All seven surfaces that shipped a full-width phone select now pass one compact badged trigger and opt into `mobileControlsPlacement="inline"`, so the one-line results bar is universal rather than a documents/therapy-compass exception. Converted: differentials, services, factsheets, prescribing, and the tools launcher (one select each) plus formulation and specifiers (two selects each, in the two-column grid this row named as the hard case). `MobileResultFilterControl` is deleted — no caller remains. The shared idiom lives in `src/components/clinical-dashboard/result-filter-control.tsx`: `ResultFilterTrigger` (lifted verbatim from `DocumentFilterTrigger`, so the control is the same component everywhere) and `ResultFilterSheet`, which renders one `role="radiogroup"` per dimension because these are genuinely one-of-N. Documents keeps its own panel — multi-select facet groups with counts, a find-a-filter field and collapse-by-default are not radios. Desktop is untouched: the ribbon renders `filterControls` from `sm` up and `mobileControls` below it, never both, so every mode keeps its chip row or tab strip on a wide screen. Verified in a real browser at 390px: the differentials band is geometrically identical to the documents band (89px at 390, 60px at 414 and 430). The "Stop" in this row is honoured — `mobileControlsPlacement` still defaults to `row`; nothing relies on that fallback now, and it stays so a mode that forgets the prop degrades to a second row rather than to an unreadable line. Follow-up captured separately: the `max-[413px]:flex-wrap` threshold was measured when Sort still occupied the phone line and is now stale — one line fits with zero overflow at 320/360/375/390/402px. | 2026-08-07 | | #263 | task | DS Track A4: close the 13 open COMPONENTS section 0.4 defect rows | Closed on branch claude/ds-a4-component-defects (commit e674f6e20). Eleven defects fixed across ten registered components: Button ref forwarding (+ a testId prop, because @types/react@19 gives components no data-${string} index signature); Progress indeterminate sweep onto the animate-shimmer theme token; StageList step index clamped to >=1 and announcement moved off the
    onto an sr-only role=status SIBLING (a child
  1. would make a five-stage job announce as 'list, 6 items'); StatusMark DocumentStatus declared in the component with the app row type asserted to conform, not the reverse; PageHeader title column floored at minmax(20ch,1fr) — the pre-existing wrap decided WHERE actions sat, not how wide, so the title still starved; Disclosure collapsed panel print:block (and the docstring's Ctrl-F claim was false); AccessibleTable dense header keeps its full string as title and the expander is now the registered Button; Tabs invalid value no longer empties the tab order (reachability only, no onChange fired to repair caller state); Pagination props clamped, row wraps at 320px, boundary focus handed to the current page, page announced via LiveAnnouncer; Links download type-omitted AND written after the spread, and LinkAction's hover nudge is a composited translate-x because gap is not in Tailwind's transition list so hover:gap-2 never eased; Checkbox/RadioGroup raw size-[1.125rem]/h-[2px] onto size-5/h-0.5 (size-4.5 retired by check:icon-scale). THREE ROWS RE-MEASURED AS STALE and were not work: Checkbox/RadioGroup unsanitised ids (optionId already sanitises) and no group hint/error (fieldset already carries hint/error/describedBy). Button is now genuinely product-adopted by AccessibleTable with a real v2 mount, so it left the reference-only snapshot in tests/design-system-adoption.test.ts. Ratchets fell and none rose: edge conflicts 28->27, legacy shadow aliases 229->228; baseline deliberately NOT lowered — that is A3/A5 work and needs a full debt-baseline regeneration. Evidence executed: check:design-system-contract exit 0 (all three sub-checks); tsc --noEmit exit 0; lint exit 0 at --max-warnings 0; prettier --check . clean; verify:ui 407 passed (14.1m) exit 0; 260+191 unit tests across component suites. npm run verify:pr-local aggregate NOT run — Vitest fork workers unreliable under box load; components run individually. Deliberately OUT of scope and still open: TextField/SearchField/Select (PR 7) and the ui-primitives.tsx module split (PR 12) were never in this task; Disclosure title truncation, StatusMark inline styles/raw geometry, Citation route/source modes, Links implicit new-tab policy, AccessibleTable content-role widths and the Button client boundary remain on their own rows. New finding worth a row: LinkAction accepts tone via BaseProps but never destructures it, so tone is silently ignored (#276). | 2026-08-07 | +| #276 | issue | LinkAction accepts a tone prop it never reads | Refused rather than honoured: LinkActionProps now carries tone?: never, shipped in PR #1720 (5c0504a40). Omit alone was not enough — excess-property checking only fires on object literals, so a spread still type-checked clean and rendered the accent; verified with a focused tsc probe (Omit accepted the spread with no diagnostic, tone?: never rejected it with TS2345). A type-level contract test in tests/ui-v2-components.dom.test.tsx stops compiling if the prop widens back, plus a render assertion that the accent is what ships. | 2026-08-08 |