baldart 3.9.0 → 3.12.0

package/framework/.claude/skills/prd/SKILL.md

@@ -148,7 +148,9 @@ Before entering the discovery loop, load codebase context using the **context-pr
 2. Invoke the `Skill` tool with `skill: "context-primer"` passing the keywords
    (e.g., `args: "prize scanning scratch card wheel"`).
 3. The context-primer launches `codebase-architect` which searches RAG, docs,
-   backlog, source code, and git history — returning a compact summary.
+   backlog, source code, and git history — returning a compact summary. When
+   `features.has_lsp_layer: true`, the symbol-lookup tier is automatically used
+   for identifier-shaped queries (transitive via `agents/code-search-protocol.md`).
 4. Additionally, use `search_docs` MCP tool (if available) with `mode: "hybrid"` for the feature domain
    to surface related PRDs, ADRs, and specs not covered by context-primer. The
    active retrieval layer is Obsidian-first LightRAG; use Obsidian hits for

package/framework/.claude/skills/simplify/SKILL.md

@@ -39,6 +39,12 @@ For each new piece of code in the diff:
 1. **Start with `${paths.references_dir}/component-registry.md`** — the authoritative inventory of all UI primitives, shared components, hooks, and utility modules. Scan the relevant tables before grepping. Then search for existing utilities and helpers that could replace newly written code in the project's utility roots (e.g. `${paths.components_root}/shared/`, `${paths.components_primitives}/`, and `src/lib/`, `src/hooks/` if they exist), and files adjacent to the changed ones.
 2. **For each new component**, Grep the codebase for components with similar names, similar prop signatures, or similar JSX structure. Check for copy-pasted layout components (`layout.tsx` files with near-identical structure).
 3. **For each new function/hook**, search for functions with similar signatures or logic patterns elsewhere. Check for duplicated page-level patterns (similar data fetching, similar error boundaries, similar loading states).
+   When `features.has_lsp_layer: true`, run LSP `find-references` on each new exported
+   symbol before grepping — it tells you exactly which callsites would need to migrate
+   if you replaced the new code with an existing utility (textual grep over identifier
+   names overcounts because of collisions). See `framework/agents/code-search-protocol.md`.
+   Also use LSP `find-references` on candidate "existing" utilities to confirm they're
+   really in use and not abandoned dead code before recommending them as the canonical version.
 4. **Flag components that wrap the same underlying element** with minor style/prop differences.
 
 Classify each finding as:

package/framework/.claude/skills/ui-design/SKILL.md

@@ -32,6 +32,11 @@ Evaluation is always performed by a separate agent with fresh context.
 
 ## Prerequisites — BLOCKING reads before ANY design work
 
+The registry-first cascade below is the consumer view of the SSOT in
+[`framework/agents/design-system-protocol.md`](../../../agents/design-system-protocol.md).
+When the cascade rules diverge between this file and the protocol module,
+the protocol module wins.
+
 These reads are BLOCKING. Resolve paths from `baldart.config.yml` before opening files. If `features.has_design_system: true`, item 1 is the mandatory entry point and skipping it is a protocol violation.
 
 1. **MANDATORY / BLOCKING when `features.has_design_system: true`** — read `${paths.design_system}/INDEX.md` (the design-system entry point: component index, authority matrix, token contract, any project-specific theming pairing rules and overlay decision tree).
@@ -141,6 +146,43 @@ Read [references/inventory.md](references/inventory.md).
 3. Update state file with chosen option, design decisions, component lists.
 4. Clean up `/tmp/prd-design-<slug>/`.
 
+### Step H — Registry Coherence Reconciliation (BLOCKING completion gate)
+
+When `features.has_design_system: true`, the design is not complete until the
+component registry reflects every primitive the chosen design depends on. Run
+the **Post-Intervention Coherence Check** defined in
+[`framework/agents/design-system-protocol.md`](../../../agents/design-system-protocol.md)
+§ "Post-Intervention Coherence Check".
+
+Concretely, walk the UI Element Inventory from Step G and for each item:
+
+1. **Registry-hit confirmed**: the primitive exists in `${paths.design_system}/INDEX.md`
+   AND its `components/<Name>.md` spec matches the way the design uses it
+   (props, variants, accessibility). If the design uses a variant not yet
+   documented, update the spec inline.
+2. **Source-tree-hit silent primitive**: the primitive exists under
+   `${paths.components_primitives}` but not in `INDEX.md`. Add the INDEX entry
+   inline (full spec or stub `status: needs-review`, see decision matrix in the
+   protocol).
+3. **New primitive proposed by the design**: it has no source implementation
+   AND no spec. Either:
+   - scaffold the spec + INDEX entry now as part of the inventory deliverable, OR
+   - open a follow-up card and **flag the gap explicitly** in the inventory so
+     downstream implementation work cannot proceed without resolution.
+4. **Token additions**: the design introduces a color / spacing / shadow / motion
+   value not present in `${paths.design_system}/tokens-reference.md`. Update the
+   reference inline OR open a follow-up token-addition card before approval.
+
+Surface every finding in the design handoff with the standard codes
+(`DS_INDEX_DRIFT` / `DS_COMPONENT_STALE` / `DS_TOKENS_DRIFT`). Silent
+reconciliation is forbidden — the user must see the drift that was found and
+how it was resolved (inline vs. follow-up card).
+
+This step exists because the design phase is where drift is **cheapest to
+prevent**: catching a duplicate primitive at the mockup stage costs minutes,
+catching it after implementation costs a refactor. The weekly `ds-drift`
+routine is a safety net, not a substitute for this check.
+
 ---
 
 ## Design Principles (quick reference)
@@ -153,6 +195,7 @@ These are enforced — read `${paths.ui_guidelines}` for full spec.
 - **Multi-tenant theming pairing**: when `features.multi_tenant_theming: true`, themed text-token paired with themed bg-token per the project's theming pattern doc
 - **View State Trinity**: loading (skeletons), error (localized message + retry), empty (CTA). The error language follows `identity.language`.
 - **Separation of concerns**: UI / business logic / data layers stay separate
+- **Registry coherence (BLOCKING)**: when `has_design_system: true`, every primitive in the chosen design is reconciled with `INDEX.md` + `components/<Name>.md` + `tokens-reference.md` before sign-off (Step H). New primitive ⇒ new spec same change. Modified primitive ⇒ updated spec same change. Silent reuse of undocumented primitive ⇒ INDEX entry added now
 
 ---
 

package/framework/agents/code-search-protocol.md

@@ -0,0 +1,126 @@
+# Code Search Protocol
+
+## Purpose
+
+Define a deterministic retrieval hierarchy for agents and skills that need to
+find code (identifiers, references, definitions, similar patterns) inside the
+consumer repo. The goal is to filter noise **before** Claude reads files, not
+after — Grep on a common function name returns thousands of textual matches and
+burns context; LSP returns only the references that point to the same symbol.
+
+## Scope
+
+**In**: How agents/skills should choose between RAG, LSP, Grep, and Git when
+searching for code. Fallback rules when a tier is unavailable.
+**Out**: Documentation search (see `agents/llm-wiki-methodology.md`), test
+discovery (see `agents/testing.md`).
+
+## Gating
+
+This protocol is **conditional** on `features.has_lsp_layer: true` in
+`baldart.config.yml`. When the flag is `false` or missing, agents fall back to
+the legacy RAG → Grep → Git flow and skip the LSP tier entirely.
+
+Adapters for installed servers live under `src/utils/lsp-adapters/`; the
+current set of servers BALDART has wired in this project is recorded at
+`lsp.installed_servers` in `baldart.config.yml`.
+
+## Retrieval Hierarchy (in order)
+
+1. **RAG hybrid** — `search_docs(query, mode: "hybrid")` via the doc-rag MCP if
+   available. Best for free-text and conceptual queries ("how does session
+   token storage work").
+2. **LSP symbol search** — when the query is an identifier (function, type,
+   class, variable name) and `features.has_lsp_layer: true`. Use the LSP tool
+   (`ToolSearch("LSP")` in Claude Code) for:
+   - **find references**: every callsite of a symbol across the project.
+   - **go to definition**: the single authoritative declaration.
+   - **type info / hover**: signature, parameters, return type.
+   - **document/workspace symbols**: enumerate top-level symbols.
+3. **Grep** — for textual patterns that aren't symbols (a comment, a magic
+   string, a regex match, a config key, a TODO marker). Also the fallback when
+   LSP is unavailable or returns nothing for a symbol that clearly exists.
+4. **Git log** — `git log --oneline -20 --grep="keyword"` to find when and why
+   code changed. Last resort, but cheap when you suspect a regression.
+
+## Query-type discrimination
+
+Before picking a tier, classify the query:
+
+| Query shape                            | Start with |
+|----------------------------------------|------------|
+| `handleSubmit`, `UserSchema`, `useAuth`| LSP        |
+| `"TODO: encrypt tokens"`               | Grep       |
+| `/api/v1/users` route handler          | Grep then LSP on the handler name |
+| "how is auth wired"                    | RAG hybrid |
+| "when did we change session storage"   | Git log    |
+| Mixed (refactor a function used in 5 places) | RAG → LSP find-references |
+
+## Budget
+
+- **LSP**: up to **3 calls per task** for symbol resolution. If after 3 calls
+  the picture is still unclear, escalate to RAG or read the file directly —
+  don't keep ping-ponging through references.
+- **Grep**: existing project budget (typically 15–25 calls per agent).
+- **RAG / Git**: no hard budget, but verify the verdict (`rag_telemetry.verdict`
+  for RAG) before relying on it.
+
+## Fallback rules
+
+- LSP tool not loaded / plugin missing → silently fall back to Grep with the
+  symbol name. Do **not** prompt the user mid-task — the missing tool is a
+  setup concern surfaced by `baldart doctor`.
+- LSP returns zero references for a symbol you know exists → fall back to
+  Grep; the symbol may live in a file the LSP server hasn't indexed yet (e.g.
+  a path excluded by `tsconfig.json`).
+- LSP times out (>8s) → fall back to Grep for this query, log the symptom in
+  the agent's reasoning so the user can re-run doctor.
+
+## Examples
+
+### Refactor: rename a function used across the repo
+
+1. RAG hybrid: confirm the function is the right one and not a name collision.
+2. LSP find-references on the symbol → exact callsite list (file + line +
+   column).
+3. Read each callsite, propose the rename, apply edits.
+
+Why this beats Grep: a project with both `handleSubmit` in a form component
+and `handleSubmit` in a CLI utility gets two semantically distinct sets from
+LSP, but a single conflated list from Grep.
+
+### Bug: trace where a value originates
+
+1. RAG hybrid on the symptom (free text).
+2. LSP go-to-definition on the suspect variable → authoritative source.
+3. LSP find-references back from the definition → call graph upstream.
+4. Grep only if LSP cannot resolve (e.g. the value passes through a
+   dynamically-typed boundary).
+
+### Cleanup: remove a deprecated helper
+
+1. LSP find-references on the helper. Zero hits → safe to delete.
+2. Non-zero hits → migrate callsites first, then delete.
+
+Skip Grep here: textual matches inside string literals or comments are not
+true callsites and would falsely block the deletion.
+
+## When to skip LSP entirely
+
+- Query is a phrase or comment, not a symbol.
+- The project's `lsp.installed_servers` is empty for the relevant language.
+- You are reading a single small file (under 200 lines) — direct Read is
+  cheaper than a tool call.
+
+## Maintenance
+
+When adding a new language to `src/utils/lsp-adapters/`, no change is required
+here unless the new language has special tooling caveats (e.g. multi-root
+workspaces, monorepos). In that case, append a subsection below.
+
+## See also
+
+- `framework/.claude/skills/lsp-bootstrap/SKILL.md` — install + verify flow.
+- `framework/agents/project-context.md` — always-ask / never-assume contract.
+- `framework/.claude/agents/codebase-architect.md` — primary consumer of this
+  protocol.

package/framework/agents/design-review.md

@@ -9,6 +9,23 @@ Define design review process and UI/UX quality standards.
 **In**: UI review criteria, design consistency, accessibility.
 **Out**: Implementation details (see agents/coding-standards.md).
 
+## Registry-First Pre-Work (BLOCKING when `features.has_design_system: true`)
+
+Before walking the checklist below, execute the cascade defined in
+[`framework/agents/design-system-protocol.md`](design-system-protocol.md):
+
+1. Read `${paths.design_system}/INDEX.md` and extract the Authority Matrix for
+   every primitive present on the route under review.
+2. Read `${paths.design_system}/tokens-reference.md` and use it as the SSOT
+   when judging color / shadow / radius / spacing decisions.
+3. For each component visible in the screenshots/DOM, read the corresponding
+   `${paths.design_system}/components/<Name>.md` spec.
+
+When `features.has_design_system: false`, skip the registry reads and run the
+checklist using `${paths.ui_guidelines}` alone — but flag in the report that
+the absence of a registry is preventing systematic conformance checks, and
+recommend `/design-system-init`.
+
 ## Do
 
 - Review designs before implementation
@@ -24,6 +41,19 @@ Define design review process and UI/UX quality standards.
 
 ## Design Review Checklist
 
+### Design-System Conformance (when `has_design_system: true`)
+
+- [ ] Every primitive in the DOM is listed in `${paths.design_system}/INDEX.md`
+- [ ] No reinvented variant of an existing registry primitive
+- [ ] No hardcoded color / shadow / radius / spacing values that bypass
+      `${paths.design_system}/tokens-reference.md`
+- [ ] Each component matches its `components/<Name>.md` spec (props, variants,
+      a11y hooks)
+- [ ] Authority Matrix respected — no local override of registry-authoritative
+      decisions
+- [ ] New primitives introduced in the change ship with their per-component
+      spec in the same change
+
 ### Visual Design
 
 - [ ] Follows design system/style guide
@@ -170,3 +200,24 @@ Define supported devices:
 - **Approved with minor changes**: Small tweaks needed
 - **Needs revision**: Significant changes required
 - **Rejected**: Fundamental issues, needs redesign
+
+## Report Template
+
+Every `/design-review` report MUST include a top-level section
+**Design-System Conformance** with these subsections (when
+`has_design_system: true`):
+
+- **Primitives reused** — list of `<Name>` taken from
+  `${paths.design_system}/INDEX.md`.
+- **Primitives reinvented** — DOM components that duplicate or overlap with an
+  existing registry primitive. HIGH severity.
+- **Tokens bypassed** — hardcoded values that should have used a token from
+  `tokens-reference.md`. HIGH severity.
+- **Spec drift** — components in the diff that diverge from their
+  `components/<Name>.md`. MEDIUM severity.
+- **New primitives proposed** — components that legitimately need a new
+  registry entry, with a one-line justification.
+
+When `has_design_system: false`, replace the section with:
+> Design-system conformance check skipped — `features.has_design_system: false`.
+> Run `/design-system-init` to enable systematic conformance checks.

package/framework/agents/design-system-protocol.md

@@ -0,0 +1,363 @@
+# Design-System Protocol
+
+## Purpose
+
+Define a deterministic, registry-first discipline for any agent or skill that
+touches a visual surface (component, page, mockup, design review). The goal is
+twofold:
+
+1. **Visual coherence** across the whole product — every UI passes through the
+   same canonical inventory of primitives + tokens, never reinvents one.
+2. **Code economy** — the component registry is interrogated **before**
+   implementation, so existing primitives are reused instead of duplicated.
+
+This is the textual SSOT for the registry-first protocol. Skills (`ui-design`,
+`frontend-design`, `design-system-init`), agents (`ui-expert`, `code-reviewer`),
+and the `/design-review` command all reference this module instead of
+duplicating the BLOCKING-read cascade.
+
+## Scope
+
+**In**: How to discover, reuse, and extend the project component registry
+before producing or reviewing UI. Token contract enforcement. Authority matrix.
+What to do when a primitive is missing.
+
+**Out**: Aesthetic direction (see `${paths.ui_guidelines}` and
+`identity.design_philosophy`), motion specs (see `motion-design` skill),
+illustration assets (see `visual-designer` agent).
+
+## Gating
+
+This protocol is **conditional** on `features.has_design_system: true` in
+`baldart.config.yml`. When the flag is `false` or missing, the registry reads
+in step 1 below are SKIPPED — agents/skills still respect
+`${paths.ui_guidelines}` but do not block on a registry that does not exist.
+
+When the flag is `true`, the registry reads are **BLOCKING**: skipping them is
+a protocol violation and the agent must refuse to proceed.
+
+To bootstrap a registry on a project that does not yet have one, invoke the
+`design-system-init` skill (`/design-system-init`).
+
+## Canonical sources (resolve via `baldart.config.yml`)
+
+- `${paths.design_system}/INDEX.md` — component index + Canonical Authority
+  Matrix + quick MUST rules. Entry point for every UI task.
+- `${paths.design_system}/tokens-reference.md` — human-readable token contract
+  (colors, spacing, shadows, radii, motion). Single source of truth for any
+  value that would otherwise be hardcoded.
+- `${paths.design_system}/components/<Name>.md` — per-component spec (props,
+  variants, accessibility, anti-patterns). One file per primitive.
+- `${paths.design_system}/patterns/*.md` — opt-in pattern docs (theming,
+  overlays, motion choreography, multi-tenant pairing rules).
+- `${paths.ui_guidelines}` — brand voice, typography, philosophy. Always read.
+- `${paths.components_primitives}` / `${paths.components_root}` — source roots
+  where the registry primitives are actually implemented.
+
+## BLOCKING pre-work (when `has_design_system: true`)
+
+Before producing any new UI code, mockup, or design review:
+
+1. **BLOCKING** — read `${paths.design_system}/INDEX.md`. Extract: the
+   component index, the Authority Matrix for the surface you are about to
+   touch, any pattern docs the index points to.
+2. **BLOCKING** — read `${paths.ui_guidelines}` for visual language, typography,
+   accessibility, and brand voice. The `identity.design_philosophy` (when set)
+   is the lens through which these guidelines apply.
+3. **BLOCKING** — read `${paths.design_system}/tokens-reference.md`. Treat it
+   as the SSOT for every color / spacing / shadow / radius / duration value.
+4. **BLOCKING per primitive in scope** — read the relevant
+   `${paths.design_system}/components/<Name>.md`. For every component the task
+   will create, modify, or visually depend on.
+5. **BLOCKING per pattern in scope** — read the relevant
+   `${paths.design_system}/patterns/<topic>.md` (e.g. theming pattern when
+   `features.multi_tenant_theming: true`).
+
+Skipping any of the above when the gating flag is `true` is a protocol
+violation. The correct response to a missing file is to flag it and propose
+adding it via `design-system-init` or a follow-up card — **not** to proceed
+without it.
+
+## Component Discovery Cascade
+
+For every visual element the task introduces or touches, walk the cascade in
+order. Stop at the first match.
+
+1. **Registry hit** — `${paths.design_system}/INDEX.md` lists a primitive that
+   covers the use case. Use the per-component spec to implement.
+2. **Source-tree hit** — a component exists under
+   `${paths.components_primitives}` (or `${paths.components_root}/shared/*`)
+   that is not yet documented in the registry. Use it, then **propose adding
+   it to the registry** as a follow-up — the registry is the canonical
+   inventory and silent primitives create drift.
+3. **External catalog candidate** — no in-repo match but a catalog primitive
+   (shadcn, 21st.dev, Radix UI, etc.) fits the canonical stack. Use it,
+   document it as a new entry in the registry.
+4. **Create from scratch** — only after 1–3 fail. Any newly created primitive
+   MUST be tokens-compliant and must ship with its per-component spec in the
+   same change.
+
+The cascade is identical for design (mockups, HTML prototypes) and for
+implementation (component code).
+
+## Token Contract
+
+When `features.has_design_system: true`, the following are **forbidden** in
+any code or mockup produced under this protocol:
+
+- Hardcoded hex / rgb / hsl color literals (use the color tokens).
+- Hardcoded shadow tuples (use the shadow tokens).
+- Hardcoded border-width / border-radius numeric literals (use the radius and
+  border tokens).
+- Hardcoded spacing numbers outside the spacing scale (use the spacing tokens).
+- Hardcoded motion durations or easings (use the motion tokens, or escalate to
+  the `motion-design` skill).
+
+The exact token consumption mechanism (CSS custom properties, Tailwind theme
+extend, theme provider) is project-specific — defer to
+`${paths.design_system}/tokens-reference.md` and the project's chosen
+mechanism.
+
+## Reference Tables (embed)
+
+These tables are the SSOT for the *numeric ranges* every agent/skill should
+cite verbatim instead of guessing. They complement
+`${paths.design_system}/tokens-reference.md` (which holds the *project-specific*
+values) by providing the canonical menu of options from which a project
+typically derives its tokens.
+
+### Type scale (base 16px)
+
+| Ratio | Name | Use | Example sequence (rounded) |
+|---|---|---|---|
+| 1.125 | Major Second | Dense UI, dashboards | 12 / 14 / 16 / 18 / 20 / 23 / 26 |
+| 1.200 | Minor Third | Default web app | 12 / 14 / 16 / 19 / 23 / 28 / 33 |
+| 1.250 | Major Third | Marketing, landing | 13 / 16 / 20 / 25 / 31 / 39 / 49 |
+| 1.333 | Perfect Fourth | Editorial, blog | 12 / 16 / 21 / 28 / 37 / 50 / 67 |
+| 1.414 | Augmented Fourth | Display-led | 12 / 17 / 24 / 34 / 48 / 67 / 95 |
+| 1.618 | Golden | Hero / poster | 10 / 16 / 26 / 42 / 68 / 110 |
+
+Line-height pairing (inverse to size): 12–14px → 1.5 · 16–18px → 1.5 ·
+20–24px → 1.35 · 28–40px → 1.2 · 48px+ → 1.1. Limit the scale to **6–9
+deliberate steps**. More steps = chaos. Extra hierarchy comes from weight,
+color, and spacing — not from new sizes.
+
+### Color contrast targets (WCAG 2.x + APCA secondary gate)
+
+| Case | WCAG 2.x ratio | APCA Lc | Notes |
+|---|---|---|---|
+| Body text (<18pt regular / <14pt bold) | ≥ 4.5 (AA), ≥ 7 (AAA) | ≥ 75 | Reading-flow text |
+| Large text (≥18pt or ≥14pt bold) | ≥ 3 (AA), ≥ 4.5 (AAA) | ≥ 60 | Headlines, large UI labels |
+| UI components / focus indicator | ≥ 3 | ≥ 45 | Borders, icons, focus rings |
+| Disabled / decorative text | exempt | Lc 30–45 | Still must be distinguishable |
+| Placeholder text | ≥ 4.5 if treated as content | ≥ 60 | Many a11y audits flag low-contrast placeholders |
+
+WCAG 2.x remains the legal requirement. **APCA is the secondary gate**: it
+captures perceived legibility considering weight, polarity, and size, so a
+project that satisfies WCAG can still have specific text-on-background pairs
+that fail APCA — those are real readability bugs.
+
+### Spacing scale (base-4 vs base-8)
+
+| Step | base-4 (px) | base-8 (px) | Typical use |
+|---|---|---|---|
+| 0 | 0 | 0 | reset |
+| 1 | 4 | 8 | icon ↔ label inline |
+| 2 | 8 | 16 | padding-x button sm |
+| 3 | 12 | 24 | padding-x button md, gap between cards |
+| 4 | 16 | 32 | section gap mobile |
+| 5 | 24 | 48 | section gap desktop |
+| 6 | 32 | 64 | hero spacing |
+| 7 | 48 | 96 | landing section |
+| 8 | 64 | 128 | landing hero |
+
+**base-4** preferred for dense product UI (dashboards, IDE-like tools);
+**base-8** preferred for marketing / editorial. **Never mix** the two scales
+in the same product — pick one and derive every token from it. Arbitrary
+values outside the scale (`padding: 13px`) are a token violation.
+
+### Density tiers
+
+| Tier | Row height | Button md padding-y | Table cell padding | Primary use |
+|---|---|---|---|---|
+| Compact | 28–32px | 4–6px | 6–8px | Power user, data tables, IDE-like surfaces |
+| Cozy | 36–40px | 8–10px | 10–12px | Default web app |
+| Comfortable | 44–48px | 12–14px | 14–16px | Mobile primary, consumer surfaces |
+| Spacious | 56–64px | 16–20px | 20–24px | Marketing, onboarding |
+
+**Touch-primary surfaces must use Comfortable or above** (44px = WCAG 2.5.5
+enhanced target). Mixing tiers within the same view is allowed only when the
+information density genuinely demands it (e.g. compact data table inside a
+cozy app shell) — document the exception in the registry.
+
+## Token Cascade: primitive → semantic → component
+
+A mature token system has **three layers**, and components consume only the
+top of the cascade:
+
+1. **Primitive tokens** — raw palette / scale values (`color-blue-500`,
+   `space-4`, `radius-md`). Stable, machine-generated, named by *what they
+   are*. Components must **never reference these directly**.
+2. **Semantic tokens** — purpose-named aliases (`color-action-primary`,
+   `color-surface-elevated`, `color-text-on-action`, `space-section-gap`).
+   Resolve to a primitive in the active theme. Named by *what they mean*.
+   The theming layer (light / dark / high-contrast / multi-brand) swaps
+   semantics → primitives — primitives themselves don't change per theme.
+3. **Component tokens** (optional) — per-component aliases when a primitive
+   appears in many components but a semantic is too generic
+   (`button-bg-primary`, `card-shadow-elevated`). Resolve to a semantic.
+
+**Why it matters**: components written against semantic tokens become
+theme-agnostic and multi-brand-ready by construction. A brand swap touches
+the semantic-layer mapping only, not the component code. Dark mode is a
+semantic-layer concern (different primitive mappings per theme), **never**
+implemented via `filter: invert()` or naïve color flips — that produces
+washed-out brights, inverted shadows, and inverted images.
+
+When the project's `tokens-reference.md` doesn't yet expose a semantic
+layer, propose adding one rather than letting components reach into
+primitives — that drift is the entry door to inconsistent theming.
+
+For palette *generation*, prefer **OKLCH** (or LCH) over HSL: it's
+perceptually uniform, so equal lightness numbers across hues read as equal
+brightness, dark/light variants stay tonally consistent, and palette steps
+land at predictable contrast levels. HSL `lighten()` / `darken()` produces
+visually uneven steps because HSL lightness is not perceptual.
+
+## Authority Matrix
+
+`${paths.design_system}/INDEX.md` declares, for each primitive, who is
+authoritative over which dimension:
+
+- **Visual authority** — colors, spacing, shadows, radii: the registry +
+  tokens-reference. Agents/skills may not deviate.
+- **Behavioral authority** — props, variants, accessibility hooks: the
+  per-component spec.
+- **Composition authority** — how primitives are combined into patterns: the
+  pattern docs.
+
+When a task would violate any of these authorities, the agent must:
+
+1. Stop and surface the conflict.
+2. Propose a registry update (new variant, new token, new pattern) instead of
+   bypassing the authority locally.
+
+## When a primitive is missing
+
+If the cascade reaches step 3 or 4 (no registry hit, no source-tree hit), the
+agent has two choices:
+
+- **Add to the registry** — preferred when the primitive is broadly useful.
+  Create the per-component spec, the implementation under
+  `${paths.components_primitives}/<Name>`, and an INDEX.md entry in the same
+  change.
+- **Local one-off** — only when the use case is genuinely surface-specific
+  (e.g. a marketing-page hero illustration). Even then, prefer composing
+  existing primitives over hand-rolling a new one. Justify the local choice
+  in the change description.
+
+Never silently introduce a new component that overlaps with an existing
+registry primitive — that is the exact failure mode this protocol prevents.
+
+## Post-Intervention Coherence Check (BLOCKING completion gate)
+
+The BLOCKING pre-work above enforces *reads* before any UI change. This
+section enforces *writes* before completion. **No UI task is considered
+complete** when `features.has_design_system: true` until the registry has
+been verified against the change that was just made.
+
+The check runs at end-of-task by the agent that performed the work (`ui-expert`,
+`ui-design`, `frontend-design`, `code-reviewer`). It is **not** delegated to
+the weekly `ds-drift` routine — that routine is a safety net, not the primary
+mechanism. Drift introduced today must be reconciled today, not next Monday.
+
+### What to verify
+
+For each item in the diff that touched a visual surface, run these 4 checks:
+
+1. **New primitive ⇒ new spec**: did the change introduce a component under
+   `${paths.components_primitives}` that has no
+   `${paths.design_system}/components/<Name>.md`? If yes, the spec MUST ship
+   in the same change. Missing spec = `DS_INDEX_DRIFT` finding, task blocked.
+2. **Modified primitive ⇒ updated spec**: did the change alter a primitive's
+   props / variants / accessibility behavior? If yes, the corresponding
+   `components/<Name>.md` MUST be updated to match. Stale spec =
+   `DS_COMPONENT_STALE` finding, task blocked.
+3. **New / changed token ⇒ updated reference**: did the change introduce or
+   modify a token (color, spacing, shadow, radius, motion)? If yes,
+   `${paths.design_system}/tokens-reference.md` MUST reflect it. Stale
+   reference = `DS_TOKENS_DRIFT` finding, task blocked.
+4. **Surfaced silent primitive ⇒ added to INDEX**: during the work, did you
+   reuse a primitive that exists in the source tree but is **not** in
+   `INDEX.md`? If yes, add it to the INDEX in the same change (or open a
+   follow-up card if the registry entry requires design judgement beyond
+   the current scope). Silent primitive = `DS_INDEX_DRIFT` finding.
+
+### Decision matrix
+
+| Situation | Action |
+|---|---|
+| Spec / token update is trivial (variant added, prop renamed, token value tweaked) | Apply inline — same commit as the code change |
+| Spec / token update requires design judgement (new variant semantics, breaking change, accessibility decision) | Open a follow-up card; **document the gap explicitly** in the change description; flag for `code-reviewer` |
+| Reused undocumented primitive that is broadly useful | Add INDEX entry inline; if a full spec needs design work, scaffold a stub spec marked `status: needs-review` |
+| Reused undocumented primitive that is surface-specific | Add INDEX entry with `scope: local` and a 2-line note explaining why no full spec is needed |
+| Introduced a primitive that **duplicates** an existing registry entry | **Stop**. This is the failure mode the cascade exists to prevent. Revert and reuse the existing primitive, or escalate to refactor the existing primitive if the new requirement is legitimately broader |
+
+### Reporting
+
+When any of checks 1–4 trip, the agent must surface them explicitly to the
+user before declaring task done — never silent. The recommended phrasing:
+
+> Registry coherence check: <N> finding(s)
+> - `DS_INDEX_DRIFT`: <Name> created without INDEX entry → resolved inline
+> - `DS_COMPONENT_STALE`: <Name>.md not updated for variant `xyz` → follow-up CARD-NNNN opened
+> - `DS_TOKENS_DRIFT`: `--color-action-secondary` added without tokens-reference entry → resolved inline
+
+This makes drift **visible at the source of introduction**, which is the
+only place it can be cheaply reconciled.
+
+### Interaction with the weekly routine
+
+The `ds-drift` routine (`framework/routines/ds-drift.routine.yml`) still
+runs weekly and catches what slips through (e.g. changes made by tools that
+bypass the agents, or by humans editing directly). But the per-intervention
+check above is **first-line**: if it fires correctly, the weekly routine
+should find very little to report.
+
+## Bootstrap (when no registry exists)
+
+If `features.has_design_system: false`:
+
+- The BLOCKING reads above are skipped.
+- Skills still respect `${paths.ui_guidelines}` and the project's existing
+  components under `${paths.components_primitives}`.
+- Recommend `/design-system-init` to the user when the absence of a registry
+  is creating obvious drift (token hardcoding, duplicate primitives, divergent
+  styling across pages).
+
+The `design-system-init` skill scaffolds `INDEX.md`, `tokens-reference.md`,
+and a `components/<Name>.md` file for every primitive already in the codebase,
+then flips `features.has_design_system: true` in `baldart.config.yml`.
+
+## Consumers of this protocol
+
+The following files reference this module instead of duplicating its rules:
+
+- `framework/.claude/agents/ui-expert.md`
+- `framework/.claude/agents/code-reviewer.md`
+- `framework/.claude/skills/ui-design/SKILL.md`
+- `framework/.claude/skills/frontend-design/SKILL.md`
+- `framework/.claude/skills/design-system-init/SKILL.md`
+- `framework/.claude/commands/design-review.md`
+- `framework/agents/design-review.md`
+
+When changing the BLOCKING cascade, change it here — not in the consumers.
+
+## See also
+
+- `framework/agents/project-context.md` — always-ask / never-assume contract
+  and the `baldart.config.yml` resolution flow.
+- `framework/agents/design-review.md` — design-review workflow and report
+  template (uses this protocol's step 0).
+- `framework/.claude/skills/design-system-init/SKILL.md` — bootstrap a
+  registry on a project that does not yet have one.