Cursor/cloud agent 1787842840327 vmus2

data/repo-awareness-snapshot.json

@@ -1,8 +1,8 @@
 {
   "version": "repo-awareness-snapshot-v1",
   "captured_revision": {
-    "sha": "59bb01b3e5c6b5c846053d2916d3e780ea38bbb1",
-    "committed_at": "2026-08-27T05:20:05+00:00"
+    "sha": "284454e511a503567e9e984dbc01ae0390c37153",
+    "committed_at": "2026-08-27T18:45:24+08:00"
   },
   "routes": {
     "modes": [
@@ -2386,6 +2386,11 @@
         "section": "design-system",
         "catalogued": true
       },
+      {
+        "path": "docs/design-system/FIX-GUIDE.md",
+        "section": "design-system",
+        "catalogued": true
+      },
       {
         "path": "docs/design-system/GATES.md",
         "section": "design-system",
@@ -2399,7 +2404,7 @@
       {
         "path": "docs/design-system/README.md",
         "section": "design-system",
-        "catalogued": false
+        "catalogued": true
       },
       {
         "path": "docs/design-system/SPEC.md",
@@ -3867,9 +3872,9 @@
       }
     ],
     "counts": {
-      "documents": 480,
-      "catalogued": 106,
-      "uncatalogued": 374,
+      "documents": 481,
+      "catalogued": 108,
+      "uncatalogued": 373,
       "sections": 19
     }
   },

docs/README.md

@@ -30,13 +30,15 @@ npm run docs:check-links
 - [search-results-bar-decisions.md](search-results-bar-decisions.md) — shared results-bar anatomy, why the filter shelf is scoped to two modes, and what is deliberately not done
 - [deployment-architecture.md](deployment-architecture.md) — app/worker/Supabase deployment topology
 - [ingestion-state-machine.md](ingestion-state-machine.md) — ingestion job lifecycle and states
-- [design-system.md](design-system.md) — tokens, primitives, styling conventions
+- [design-system/README.md](design-system/README.md) — front door for the v2 design system (tokens, components, gates)
+- [design-system.md](design-system.md) — live-layer notes during the v1→v2 transition (superseded as spec)
 - [design-system/SPEC.md](design-system/SPEC.md) — the complete v2 design system: roles, rules, rationale (never values)
 - [design-system/TOKENS.md](design-system/TOKENS.md) — reconciled token inventory: every role, winning name, owner, and what it replaces
 - [design-system/COMPONENTS.md](design-system/COMPONENTS.md) — the eight safety-component specifications plus the maturity matrix
 - [design-system/DECISIONS.md](design-system/DECISIONS.md) — conflicts C1–C5 resolved, clinical Q&A record, assumptions, blocked items
 - [design-system/GATES.md](design-system/GATES.md) — every design-system rule paired with its enforcement status
 - [design-system/ADOPTION.md](design-system/ADOPTION.md) — PR 13 registration record: adoption order, per-surface file allowlists, exclusions, pins, proof shots
+- [design-system/FIX-GUIDE.md](design-system/FIX-GUIDE.md) — Hazard 1–2 sweep dispositions (Fixed / Documented / Deferred / Out-of-scope)
 - [comparison-behaviour.md](comparison-behaviour.md) — shared selection, state, responsive, and accessibility contract for comparison surfaces
 - [clinical-chat-ui-component-map.md](clinical-chat-ui-component-map.md) — chat UI component inventory
 - [clinical-badge-system-guide.md](clinical-badge-system-guide.md) — clinical badge semantics

docs/branch-review-records/be0d35ad96adbaa5219303ff8595fd560ba330b3fc03c79f10d2dabdf35b4921.record.md

@@ -0,0 +1 @@
+| 2026-08-27 | ds-hazard-1-2-sweep | 19ee085b1cc952e8c40e893fb2fce99538415259 | design-system hazard 1-2 | P2 SPEC.md:217-218 still requires per-step -lh/-tr against gated deletion; P3 GATES evidence header still not-re-run; no P0/P1 | test:focused --files token,adoption,responsive,reachability: fail-closed exit 2 (tests/** unsafe); run-vitest same files blocked by exclusive coordinator (browser-test-gate-handoff-d5c1db); check:design-system-contract not run; verify:cheap/ui/pr-local and providers skipped |

docs/codebase-index.md

@@ -9,28 +9,28 @@ Structured map for AI agents and onboarding. For live routes, see `docs/site-map
 
 ## Quick start
 
-| Step                              | Command                          |
-| --------------------------------- | -------------------------------- |
-| Confirm Supabase target           | `npm run check:supabase-project` |
-| Start app (project-specific port) | `npm run ensure`                 |
-| Start ingestion worker            | `npm run worker`                 |
-| Cheap verification gate           | `npm run verify:cheap`           |
-| UI verification gate              | `npm run verify:ui`              |
+| Step                              | Command                                                                          |
+| --------------------------------- | -------------------------------------------------------------------------------- |
+| Confirm Supabase target           | `npm run check:supabase-project` (provider-backed — needs explicit confirmation) |
+| Start app (project-specific port) | `npm run ensure`                                                                 |
+| Start ingestion worker            | `npm run worker`                                                                 |
+| Cheap verification gate           | `npm run verify:cheap`                                                           |
+| UI verification gate              | `npm run verify:ui`                                                              |
 
 ---
 
 ## Top-level layout
 
-| Path        | Purpose                                                          |
-| ----------- | ---------------------------------------------------------------- |
-| `src/`      | Next.js App Router UI, API routes, shared lib, components        |
-| `supabase/` | SQL migrations, schema mirror, Edge Functions, CLI config        |
-| `worker/`   | Local ingestion worker (parse, OCR, chunk, embed, DB writes)     |
-| `scripts/`  | CLI ops: reindex, eval, backfill, governance, dev-server helpers |
-| `tests/`    | Vitest unit (`*.test.ts`) + Playwright E2E (`ui-*.spec.ts`)      |
-| `docs/`     | Runbooks, governance, search/RAG plans, generated sitemap        |
-| `public/`   | Static assets (`public/llms.txt`)                                |
-| `.github/`  | CI workflows, PR template (clinical governance preflight)        |
+| Path        | Purpose                                                                                                                                                |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `src/`      | Next.js App Router UI, API routes, shared lib, components                                                                                              |
+| `supabase/` | SQL migrations, schema mirror, Edge Functions, CLI config                                                                                              |
+| `worker/`   | Local ingestion worker (parse, OCR, chunk, embed, DB writes)                                                                                           |
+| `scripts/`  | CLI ops: reindex, eval, backfill, governance, dev-server helpers                                                                                       |
+| `tests/`    | Vitest unit (`*.test.ts`) + Playwright E2E (`ui-*.spec.ts`)                                                                                            |
+| `docs/`     | Runbooks, governance, search/RAG plans, generated sitemap; design-system system of record is [`docs/design-system/README.md`](design-system/README.md) |
+| `public/`   | Static assets (`public/llms.txt`)                                                                                                                      |
+| `.github/`  | CI workflows, PR template (clinical governance preflight)                                                                                              |
 
 Smaller top-level directories that are easy to miss:
 

docs/design-system-contract.md

@@ -25,11 +25,11 @@ npm run check:icon-scale
 - **Tokens Only**: Raw CSS hex codes (e.g. `#007a78`, `#ffffff`), RGB/RGBA, HSL, and un-tokenized Tailwind color classes (e.g. `bg-white`, `text-slate-900`, `border-red-200`) are prohibited in components.
 - **Variable Syntax**: All colors must use CSS custom properties defined in `src/app/globals.css` with semantic purpose:
   - **Brand & Clinical Accent**: `var(--clinical-accent)`, `var(--clinical-accent-hover)`, `var(--clinical-accent-soft)`, `var(--clinical-accent-border)`
-  - **Surfaces & Borders**: `var(--surface)`, `var(--surface-subtle)`, `var(--surface-wash)`, `var(--surface-lux)`, `var(--border)`, `var(--border-subtle)`
-  - **Text Roles**: `var(--text)`, `var(--text-muted)`, `var(--text-heading)`, `var(--text-soft)`
+  - **Surfaces & Borders**: `var(--surface)`, `var(--surface-subtle)`, `var(--surface-wash)`, `var(--surface-lux)`, `var(--border)`, `var(--border-strong)`, `var(--border-lux)`
+  - **Text Roles**: `var(--text)`, `var(--text-muted)`, `var(--text-heading)`. `--text-soft` is decoration (`--decoration-soft`), not a text role.
   - **Status & Safety Triads**: `--success-*`, `--warning-*`, `--danger-*`, `--info-*` (reserved exclusively for clinical/system status).
   - **Focus Ring & Outlines**: `var(--focus)` for all keyboard and visible focus rings.
-- **Raw Color Exemptions**: Strict and enumerated in `RAW_COLOR_EXEMPTIONS` in `scripts/design-system-contract-utils.mjs` (e.g., globals token definitions, brand mark SVG builder, diagnostic visualizations, OpenGraph art, printable patient/factsheet paper).
+- **Raw Color Exemptions**: Strict and enumerated in `RAW_COLOR_EXEMPTIONS` in `scripts/design-system-contract-utils.mjs` (e.g., globals token definitions, brand mark SVG builder, diagnostic visualizations, OpenGraph art, printable patient/factsheet paper). Medication record accent defaults (`#0f766e` in `src/lib/medications.ts` and `src/lib/medication-records.ts`) are a **scoped** exemption for the Postgres `accent` column default only — not a whole-file blank cheque, and not a mapping onto `--clinical-accent`.
 
 ### 2.2 Typography Scale
 
@@ -47,7 +47,7 @@ npm run check:icon-scale
 
 - **Elevation**: Monotonic numeric scale `var(--e0)` through `var(--e4)`. No raw `box-shadow` values.
 - **Edge Ownership**: Prohibits simultaneous `border-*` and `ring-*` styling on the same surface to prevent clipped or competing boundaries.
-- **Motion Durations**: Transitions and animations must use standardized duration tokens (`var(--duration-fast)`, `var(--duration-normal)`) and respect `motion-reduce:`. Layout-property animation (e.g., width, height, padding) is disallowed except for explicitly audited phone-chrome transitions.
+- **Motion Durations**: Transitions and animations must use standardized duration tokens (`var(--duration-fast)`, `var(--duration-base)`) and respect `motion-reduce:`. Layout-property animation (e.g., width, height, padding) is disallowed except for explicitly audited phone-chrome transitions.
 
 ---
 

docs/design-system/ADOPTION.md

@@ -5,7 +5,7 @@ of truth is `adoption-contract.json`; the generated manifest and marked tables i
 must match it exactly.
 
 - **Date:** 12 August 2026
-- **Current state:** 54 visual references are locally registered; all 51 production page routes
+- **Current state:** 55 visual references are locally registered; all 51 production page routes
   are owned across 14 surface families, with 59 route/component roots scanned; every declared
   root uses the v2 shell and has declared proof with no committed visual baseline.
 - **Phase 1 blockers resolved first, in their own commits:** `#207` ungrounded `AnswerState`,

docs/design-system/COMPONENTS.md

@@ -20,7 +20,7 @@ derived from source, `.design-sync/config.json`, previews, direct contract cover
 production imports. It intentionally does not claim dark, forced-colours, 320px, print, remote
 publication, or product adoption without separate evidence.
 
-### 0.1 Registered visual components (54 — local contract; remote status unverified)
+### 0.1 Registered visual components (55 — local contract; remote status unverified)
 
 Every visual export has one source map entry, a source-derived public `*Props` contract (except
 the two zero-prop roots), a reference preview, and a direct static publication test. The generated
@@ -37,7 +37,7 @@ table under **Generated maturity snapshot** is the canonical list and product-im
 
 _Remaining from the original eight in this document:_ `DocumentFrame` is built locally
 (`src/components/ui/document-frame.tsx`, shell-only in `DocumentViewer`) but is not yet among
-the 54 design-sync registered visual exports — registration and full controls remain follow-up.
+the 55 design-sync registered visual exports — registration and full controls remain follow-up.
 
 `OverlayRoot`, `SegmentedControl`, and the PR 6–8 components are built and represented by the
 local publication contract. The generated snapshot records their current product-import counts;
@@ -47,8 +47,9 @@ design-project publication or browser acceptance.
 _P1 reusable (specified in outline only):_ `Menu`/`Popover` · `KeyValue` ·
 `AppliedFilters`/`FilterSheet` · `ResponsiveActionGroup` · `ScrollableStrip`/
 `ScrollAffordance` · `SourceLink` · `Banner` · `CopyButton`/`CopyField` ·
-state family (`ErrorState`, `OfflineState`, `PermissionDeniedState`, `NotFoundState`,
-`UnavailableState`).
+state family (`OfflineState`, `PermissionDeniedState`, `NotFoundState`,
+`UnavailableState`). `ErrorState` is built (`src/components/ui/error-state.tsx`) and
+locally registered — it is not outline-only.
 
 `FilterBar` and `DataTable` are retired names, not future component contracts. Use a
 surface-owned filter pattern or the canonical `AccessibleTable`; do not revive either name.
@@ -86,7 +87,7 @@ print primitives (`PrintHeader`, `PrintFooter`, `CitationFootnote`, `PrintOnly`,
 | Progress/StageList           | all four resolved: `scaleX`, the theme `animate-shimmer` in place of a hardcoded `1.4s`, a step index clamped to ≥1, and an sr-only `role="status"` sibling in place of `aria-live` on the whole `<ol>`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | **done**             |
 | EmptyState                   | static live-off default with explicit polite/assertive opt-in                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | **done** (PR 8)      |
 | AccessibleTable              | semantic caption, `MissingValue` cells, dense headers (clipped header keeps its full string as `title`) and the expander (now the registered `Button`, off the local ring-focus recipe) landed; content-role widths remain                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | PR 6/PR 12 remainder |
-| ui-primitives.tsx            | 698-line module mixing recipes/actions/feedback/clinical — split. Re-measured 2026-08-12: **157** production files import it (202 including mockups), against the 54 registered components' **31** with product imports; this module, not the registry, is what the product actually runs on. Per-primitive breakdown added 2026-08-21: `Button` **12** importers against 157, with **112** production files still holding a raw `<button>`; `Sheet` **26** — the one genuinely adopted primitive. The split is not uniform, and the pattern explains it: `Sheet` owns focus trap, portal and overlay stacking, which a className cannot fake, while `Button`/`Chip`/field shells own visual convention a recipe string approximates. Deciding between "give `Button` behaviour worth importing" and "promote `ui-primitives` to the documented layer" is the actual PR 12 question | PR 12                |
+| ui-primitives.tsx            | 698-line module mixing recipes/actions/feedback/clinical — split. Re-measured 2026-08-12: **157** production files import it (202 including mockups), against the 55 registered components' **31** with product imports; this module, not the registry, is what the product actually runs on. Per-primitive breakdown added 2026-08-21: `Button` **12** importers against 157, with **112** production files still holding a raw `<button>`; `Sheet` **26** — the one genuinely adopted primitive. The split is not uniform, and the pattern explains it: `Sheet` owns focus trap, portal and overlay stacking, which a className cannot fake, while `Button`/`Chip`/field shells own visual convention a recipe string approximates. Deciding between "give `Button` behaviour worth importing" and "promote `ui-primitives` to the documented layer" is the actual PR 12 question | PR 12                |
 
 ---
 

docs/design-system/DECISIONS.md

@@ -147,7 +147,7 @@ source), flagged in SPEC §3 and cheap to veto mode-by-mode.
 
 ## C6 · Publication truth is source-derived; adoption truth is route-complete
 
-**Chose.** The local design-sync registry contains 53 visual exports. Each row is derived from
+**Chose.** The local design-sync registry contains 55 visual exports. Each row is derived from
 one real source file and requires an entry export, an exact TypeScript-checker-derived public
 `*Props` contract (or an explicit zero-prop root), a reference preview, and a direct publication
 test. `OverlayPortal`, `ToastProvider`, `useToast`, `AnswerState`, the answer helpers, and the