baldart 3.10.0 → 3.12.0

package/CHANGELOG.md

@@ -5,6 +5,63 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.12.0] - 2026-05-23
+
+BALDART completes the **UI excellence loop**: the `ui-expert` agent is upgraded from a "good but generic" baseline to a world-class UI/UX reviewer/designer, and — crucially — the registry-first discipline gains a **post-intervention coherence gate** so visual coherence is enforced not only when work begins (BLOCKING reads) but also when work ends (BLOCKING completion check). The asymmetry of v3.11.0 (registry read before, no verification after) is closed: every UI change introduced by `ui-expert`, the `ui-design` skill, the `frontend-design` skill, or caught by `code-reviewer` must now reconcile the registry (INDEX + per-component specs + tokens-reference) in the **same change**, never deferring drift to the weekly `ds-drift` routine. This release contains zero schema changes — the cascade reuses `features.has_design_system` + `paths.*` already in place.
+
+### Added
+
+- **`framework/agents/design-system-protocol.md` § "Reference Tables (embed)"** — canonical numeric ranges that every agent/skill must cite verbatim: type scale (6 modular ratios + line-height pairing rule), color contrast targets (WCAG 2.x + APCA Lc as secondary perceived-legibility gate), spacing scale (base-4 vs base-8 with use-case mapping), density tiers (compact/cozy/comfortable/spacious with row-height + padding numbers). Replaces the previous "agents pick their own numbers" failure mode.
+- **`framework/agents/design-system-protocol.md` § "Token Cascade: primitive → semantic → component"** — three-layer token discipline (raw → purpose-named → optional component alias) that makes components theme-agnostic and multi-brand-ready by construction. Documents OKLCH > HSL for palette generation and forbids `filter: invert()`-style dark mode shortcuts.
+- **`framework/agents/design-system-protocol.md` § "Post-Intervention Coherence Check"** — new BLOCKING completion gate (4 verifications + decision matrix + reporting format + relationship with the weekly `ds-drift` routine as safety net). This is the SSOT consumed by `ui-expert`, `ui-design`, and `code-reviewer`.
+- **`framework/.claude/skills/motion-design/reference/accessibility-and-modern-apis.md`** — new reference file covering `prefers-reduced-motion` collapse semantics (0.01ms, not 0 — Safari bug), the View Transitions API (same-doc + shared-element + cross-doc), spring vs cubic-bezier decision matrix, choreography budget (≤ 600ms total), and animations that communicate state and must NOT be collapsed under reduced-motion.
+- **`framework/.claude/skills/frontend-design/SKILL.md` § "Performance Gates (Core Web Vitals 2026)"** — CWV thresholds table (LCP / INP / CLS / TTFB / FCP) with p75 good/poor cuts, canonical LCP image pattern (preload + fetchpriority + AVIF/WebP + explicit dimensions), INP fixes (`scheduler.yield`, debounce-to-frame, off-main-thread parsing), CLS budget (dimensions on every replaced element, font-display strategies, reserved space for late-injected UI).
+- **`framework/.claude/skills/frontend-design/SKILL.md` § "Modern CSS (2025–2026)"** — container queries as default for component-level responsiveness, `:has()` for styling-only state reactions (never business logic), View Transitions API, subgrid, logical properties for free i18n, `color-mix()` for derived states, `@scope`.
+- **`framework/.claude/skills/frontend-design/SKILL.md` § "Form quality (always-on requirements)"** — non-optional form contract (label association, `autocomplete=`, validation on blur, actionable error messages, `aria-invalid` + `aria-describedby`, `inputMode=`, paste normalization, submit-disabled-only-after-failed-attempt).
+- **`framework/.claude/skills/ui-design/SKILL.md` Step H — Registry Coherence Reconciliation** — new BLOCKING completion gate inside the `ui-design` workflow that walks the UI Element Inventory from Step G and reconciles each item with INDEX + per-component spec + tokens-reference before sign-off. Catches drift at design time when it's cheapest to prevent.
+- **`framework/docs/UPGRADE-3.12-UI-COHERENCE.md`** — onboarding doc consumable by Claude in any consumer repo. Step-by-step alignment of an existing project's UI organization with the new discipline: registry presence check, overlay drift audit, token/primitive hardcoding scan, one-shot `ds-drift` baseline, prioritized reconciliation backlog.
+
+### Changed
+
+- **`framework/.claude/agents/ui-expert.md` (massive upgrade — from ~250 to ~500 lines)** — § "Your Expertise" expanded to cite WCAG 2.2 SCs (2.4.11/2.4.12 focus, 2.5.5 target size, 1.3.5 input purpose) + APCA, OKLCH-based palette generation, modern CSS surface (container queries, `:has()`, View Transitions, subgrid, logical properties), motion intent-driven curve selection, Core Web Vitals literacy, AI-era patterns, inclusive design beyond AA, i18n with text-expansion buffers. **New § "UI States Taxonomy"** (8 states explicitly: idle / loading / empty / partial / success / error / offline / optimistic) with loading rules (sub-1s → no indicator, 1–10s → skeleton, > 10s → progress with cancel) and skeleton-must-match-real-dimensions discipline. **New § "Token Cascade Discipline"** (semantic-only consumption, primitive → semantic → component, OKLCH preferred). **New § "Composition over Configuration"** (Radix Slot / `asChild`, controlled+uncontrolled contract). **New § "AI-Era UI Patterns"** (streaming-without-CLS, always-visible stop/regenerate, ARIA live regions, confidence affordance, hallucination guardrails). **New § "Performance Gates"** with UI-level red flags. **Red flag list** expanded from 14 generic items to **60+ categorized findings** (registry & tokens / minimalism / architecture / mobile / a11y / state design / forms / motion / data viz / modern CSS / i18n). **Workflow steps** gain step 10 (Review) and step 12 (Design) — both BLOCKING completion gates that run the Post-Intervention Coherence Check. **Linked Skills** section enabled (was commented out) with explicit "MUST use" routing to `frontend-design`, `motion-design`, `ui-design`, `ui-ux-pro-max`, `webapp-testing` / `playwright-skill`.
+- **`framework/.claude/agents/code-reviewer.md` § "Design System Compliance"** — gains rule 8 (Post-Intervention Coherence Check as BLOCKING merge gate). If the check trips at code-review time, it means the upstream `ui-design`/`ui-expert` checks were skipped — the violation is flagged alongside the drift. Code-reviewer is the third and final gate before the weekly safety net.
+- **`framework/.claude/skills/ui-design/SKILL.md` § "Design Principles (quick reference)"** — gains a BLOCKING bullet point pointing at Step H so the registry-coherence rule is visible even to readers who skim only the quick reference.
+
+### Notes
+
+- **No new `baldart.config.yml` keys.** The post-intervention gate, the upgraded `ui-expert`, the new motion / frontend-design sections, and the `code-reviewer` rule 8 all gate on the existing `features.has_design_system` and read paths already declared in `paths.*`. The schema-change propagation rule is satisfied — this release only adds behaviors, expands an agent, and adds reference content.
+- **Backwards-compatible.** Projects with `has_design_system: false` see no behavioral change for the registry-coherence gate (it short-circuits when the flag is false). Projects with `has_design_system: true` get the gate active immediately on next agent/skill invocation — if their codebase already has drift (silent primitives, missing specs, hardcoded tokens), the agent will surface it as findings on the first UI task post-update rather than fixing it silently. Use the `UPGRADE-3.12-UI-COHERENCE.md` doc to baseline and prioritize the reconciliation.
+- **Three-layer gating design.** Drift detection is now redundant by design: (1) `ui-design`/`ui-expert`/`frontend-design` post-intervention check (per-task) → (2) `code-reviewer` rule 8 (per-merge) → (3) `ds-drift` routine (weekly safety net). The failure of any one layer is caught by the next. The per-task check is the cheapest reconciliation point — the weekly routine should now find very little to report when the upstream gates run correctly.
+- **SSOT discipline preserved.** All numeric reference tables (type scale, contrast, spacing, density, CWV thresholds, motion durations / easings, spring parameters) live in exactly one place. The agent is explicitly instructed to cite from there verbatim and not invent numbers. The four post-intervention conditions are defined once in `design-system-protocol.md` and referenced from `ui-expert`, `ui-design`, and `code-reviewer` rather than restated.
+- **Migration for consumers.** No file the user owns is touched. `baldart update` symlinks the upgraded framework payload; `.baldart/overlays/ui-expert.md` (if present) keeps overriding sections by name as before — but consumers with overlays should run the `UPGRADE-3.12-UI-COHERENCE.md` walkthrough to spot overlay sections that may now conflict with the expanded base (e.g. overlays that previously codified red flags or workflow steps the base now defines authoritatively).
+
+## [3.11.0] - 2026-05-23
+
+BALDART makes the **component registry the SSOT for visual coherence**. Until now, the registry-first discipline (`${paths.design_system}/INDEX.md` + `tokens-reference.md` + `components/<Name>.md`) was BLOCKING only inside the `ui-design` and `frontend-design` skills, while the `ui-expert` agent — the most-used entry point for ad-hoc UI edits — and the `/design-review` command had only a generic "follow the style guide" prompt. This release closes the gap end-to-end (agent + skill + command + onboarding + bootstrap) so every UI change passes through the same inventory and token contract, regardless of which entry point routes the work. A new `/design-system-init` skill scaffolds a registry from the codebase's current state, so projects without one can adopt the discipline with a single command.
+
+### Added
+
+- **`framework/agents/design-system-protocol.md`** — new protocol module that is the textual SSOT of the registry-first cascade (Component Discovery, token contract, Authority Matrix, "primitive missing" decision tree). Referenced from `framework/agents/index.md`. All UI-touching agents/skills/commands cite it instead of duplicating the BLOCKING-reads block. Same pattern as `code-search-protocol.md`.
+- **`framework/.claude/skills/design-system-init/`** — new invokable skill (`/design-system-init`). Inventories primitives via `codebase-architect`, extracts tokens from `${paths.global_styles}` + Tailwind config, scaffolds `INDEX.md` + `tokens-reference.md` + a `components/<Name>.md` per primitive (template under `scripts/component-spec.template.md`), and flips `features.has_design_system: true` + `paths.design_system` in `baldart.config.yml`. Idempotent — refuses to overwrite an existing registry, supports incremental re-runs.
+- **`scripts/component-spec.template.md`** — dense per-component spec template (props, variants, tokens consumed, accessibility, anti-patterns, MUST rules, changelog) used by `design-system-init` and by hand when extending the registry.
+- **Design-system bootstrap hint in `configure`** — when the user opts in to `has_design_system: true` but autodetect found no path on disk, configure now surfaces `/design-system-init` as the next step so the flag doesn't end up pointing at nothing. When the user opts out, a soft pointer to `/design-system-init` is shown for future adoption.
+
+### Changed
+
+- **`framework/.claude/agents/ui-expert.md`** — now follows the registry-first protocol. Gains a Project Context header citing `baldart.config.yml` keys, replaces the lone `ui-guidelines.md` BLOCKING-read with the full cascade (`INDEX.md` + `tokens-reference.md` + per-component specs) gated by `has_design_system`, prepends Component Discovery (registry → source-tree → catalog → create) to both `When Reviewing UI Code` and `When Designing New Interfaces`, and adds red flags for re-implementing existing primitives and hardcoding values that bypass the token contract.
+- **`framework/.claude/commands/design-review.md` + `framework/agents/design-review.md`** — both gain a step 0 BLOCKING when `has_design_system: true` (read `INDEX.md` + `tokens-reference.md` + `components/<Name>.md` for primitives on the route under review). The checklist gains a new top section **Design-System Conformance** (primitives reused, primitives reinvented HIGH, tokens bypassed HIGH, spec drift MEDIUM, new primitives proposed). The agent module ships a Report Template for that section; the command file points the subagent at it.
+- **`framework/.claude/agents/code-reviewer.md`** — the existing § "Design System Compliance (MANDATORY for UI work)" now cites `design-system-protocol.md` as the SSOT, makes the BLOCKING reads conditional on `features.has_design_system: true` (instead of "if the project has a design system"), and adds two explicit HIGH findings: re-implementation of an existing registry primitive, and new primitives introduced without their per-component spec.
+- **`framework/.claude/skills/ui-design/SKILL.md` + `framework/.claude/skills/frontend-design/SKILL.md`** — both gain a one-paragraph header on the Prerequisites section declaring `framework/agents/design-system-protocol.md` as the SSOT when local rules drift. Existing BLOCKING-read content kept verbatim (skills remain readable stand-alone).
+- **`framework/agents/index.md`** — new routing entry: "if you touch ANY visual surface and `features.has_design_system: true` → read `agents/design-system-protocol.md`". `design-system-protocol.md` added to the Modules list.
+- **`src/commands/configure.js`** — after the `has_design_system` prompt, surfaces `/design-system-init` either as the recommended next step (when the user opts in but no path is detected) or as a soft pointer (when the user opts out).
+
+### Notes
+
+- **No new `baldart.config.yml` keys.** The cascade gates on the existing `features.has_design_system` and reads paths already declared in `paths.*`. The schema-change propagation rule (per `feedback_schema_change_propagation`) is therefore satisfied without template/configure/update detector churn — this release only adds behaviors, a skill, and a protocol module.
+- **Backwards-compatible.** Projects with `has_design_system: false` see no behavioral change (the BLOCKING reads in the agent/skill/command are no-ops when the flag is false). Projects with `has_design_system: true` already had the discipline inside `ui-design`/`frontend-design`/`code-reviewer` — this release just propagates it to the remaining surfaces (`ui-expert`, `/design-review`).
+- **Bootstrap path.** Projects that want the discipline but lack a registry now have a single command (`/design-system-init`) that inventories existing primitives, scaffolds the registry from them, and flips the flag — eliminating the chicken-and-egg gap where the BLOCKING reads pointed at files that didn't exist.
+- **SSOT trade-off.** `design-system-protocol.md` is the textual SSOT, but the BLOCKING-reads block is still inlined verbatim in `ui-design/SKILL.md`, `frontend-design/SKILL.md`, `code-reviewer.md`, and `ui-expert.md` (each file gains an SSOT-pointer header instead of being structurally deduplicated). Skills/agents stay readable stand-alone and don't depend on runtime module loading; the cost is that future protocol changes need to touch the consumers as well. Acceptable for v3.11.0 — revisit if the cascade churns frequently.
+
 ## [3.10.0] - 2026-05-23
 
 BALDART grows an **LSP symbol-search layer**. When enabled, `codebase-architect` and the code-exploration skills (`context-primer`, `bug`, `prd`, `new`, `simplify`) prefer LSP `find-references` / `go-to-definition` over Grep for identifier-shaped queries. The filtering happens **before** Claude reads files — a function-name search that previously returned thousands of textual matches now resolves to the actual callsites of the same symbol. Grep remains the fallback for free-text queries and when the LSP layer is unavailable, so existing flows degrade gracefully.

package/README.md

@@ -183,18 +183,26 @@ Skills always-ask when required keys are missing — never silently default.
 never overwrites your file. Full guide:
 [`framework/docs/PROJECT-CONFIGURATION.md`](framework/docs/PROJECT-CONFIGURATION.md).
 
-### Skills (23 portable skills)
+### Skills (24 portable skills)
 
 Skills live under `.claude/skills/` and are auto-discovered by Claude Code.
 Bundled skills:
 
 - **Workflow**: `new`, `prd`, `prd-add`, `bug`, `simplify`, `worktree-manager`, `issue-review`, `context-primer`
 - **Code quality**: `skill-creator`, `find-skills`, `webapp-testing`, `playwright-skill`, `lsp-bootstrap` (v3.10.0)
-- **Design**: `frontend-design`, `ui-design`, `motion-design`, `gamification-design`
+- **Design**: `frontend-design`, `ui-design`, `motion-design`, `gamification-design`, `design-system-init` (v3.11.0)
 - **Product**: `seo-audit`, `copywriting`, `api-design-principles`
 - **Knowledge**: `doc-writing-for-rag`, `capture` (LLM wiki overlay)
 - **Integration**: `kie-ai`, `remotion-best-practices`
 
+### Registry-First UI Protocol (new in v3.11.0)
+
+When `features.has_design_system: true`, every UI-touching agent/skill/command (`ui-expert`, `ui-design`, `frontend-design`, `code-reviewer`, `/design-review`) follows the same BLOCKING cascade: read `${paths.design_system}/INDEX.md` (Authority Matrix), `tokens-reference.md` (token contract), and `components/<Name>.md` for every primitive in scope — BEFORE producing or reviewing any UI. New components must reuse from the registry or ship their per-component spec in the same change. Hardcoded color/shadow/radius/spacing values are HIGH findings. The textual SSOT for the protocol lives in [`framework/agents/design-system-protocol.md`](framework/agents/design-system-protocol.md). Projects without a registry can bootstrap one with `/design-system-init`, which inventories existing primitives, extracts tokens from global styles + Tailwind config, scaffolds the registry, and flips the flag.
+
+### UI Excellence + Post-Intervention Coherence Gate (new in v3.12.0)
+
+The `ui-expert` agent is upgraded from a generic baseline to a world-class UI/UX reviewer/designer — UI States Taxonomy (8 states), Performance Gates (Core Web Vitals 2026 — LCP/INP/CLS), modern CSS surface (container queries, `:has()`, View Transitions, subgrid, logical properties), AI-era patterns (streaming UI, hallucination guardrails), and 60+ categorized red flags. Numeric reference tables (type scale, contrast targets WCAG+APCA, spacing scales, density tiers, motion durations/easings) are SSOT'd in [`framework/agents/design-system-protocol.md`](framework/agents/design-system-protocol.md) so agents cite values verbatim instead of inventing them. Crucially, the registry-first discipline now has a **post-intervention coherence gate**: every UI change introduced by `ui-expert` / `ui-design` / `frontend-design` (and verified by `code-reviewer` at merge) must reconcile `INDEX.md` + `components/<Name>.md` + `tokens-reference.md` **in the same change** — drift can no longer wait for the weekly `ds-drift` routine. Three layers now enforce coherence: per-task → per-merge → weekly safety net. Existing projects align their current graphic organization with the new discipline via [`framework/docs/UPGRADE-3.12-UI-COHERENCE.md`](framework/docs/UPGRADE-3.12-UI-COHERENCE.md) (idempotent walkthrough: baseline scan → prioritized backlog → quick wins → gate verification).
+
 ### LSP Symbol Search Layer (new in v3.10.0)
 
 When `features.has_lsp_layer: true`, `codebase-architect` and the code-exploration skills (`context-primer`, `bug`, `prd`, `new`, `simplify`) prefer LSP `find-references` / `go-to-definition` over Grep for identifier-shaped queries — the filtering happens **before** Claude reads files, so a common function name no longer dumps thousands of textual matches into context. Opt-in at `baldart configure`; BALDART installs the matching language servers (npm devDeps for TypeScript/Python, system commands printed for Go/Rust/Ruby). Grep remains the fallback for free-text queries and degraded states. See [`framework/agents/code-search-protocol.md`](framework/agents/code-search-protocol.md).

package/VERSION

@@ -1 +1 @@
-3.10.0
+3.12.0

package/framework/.claude/agents/REGISTRY.md

@@ -13,11 +13,11 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 | **doc-reviewer** | Architecture | Audit/write docs after feature implementation | Macro feature identification, SSOT sync, linking-protocol resolution, doc debt tracking, gap analysis | Yes | Doc writing, TaskCreate (doc debt), token optimization |
 | **wiki-curator** | Documentation | Maintain the derived LLM wiki overlay under `docs/wiki/` (concept pages, syntheses, dashboards, reading guides) without creating new canonicals. See `agents/llm-wiki-methodology.md`. | Synthesis pages, provenance hygiene, freshness, derived-link checks, auto-learning loop | Yes | `docs/wiki/`, wiki lint, reindex follow-up |
 | **coder** | Code | Write, modify, or refactor production code | Features, bugs, optimizations | Yes | Build tools, testing, Playwright |
-| **code-reviewer** | Code | Review code post-implementation for bugs/quality | Security analysis, code quality | No | Static analysis, security audit |
+| **code-reviewer** | Code | Review code post-implementation for bugs/quality | Security analysis, code quality, registry-first UI compliance (when `features.has_design_system: true`) — flags re-implemented primitives and bypassed tokens as HIGH per `framework/agents/design-system-protocol.md` | No | Static analysis, security audit |
 | **security-reviewer** | Code | Review security-sensitive code, configs, auth, secrets, and infra changes | AppSec audit, threat modeling, hardening guidance | No | Security review, trust-boundary analysis |
 | **qa-sentinel** | QA | **Mechanical gate runner** — lint, typecheck, test suite, build, security audit, markdownlint. Returns PASS/FAIL verdict only. Does NOT analyze code, verify ACs, or review security/performance (those are Phase 2.5 and code-reviewer responsibilities). | Gate execution, verdicts | No (reports failures, coder fixes) | ESLint, tsc, node --test, npm run build, npm audit, markdownlint |
 | **hybrid-ml-architect** | ML | Design/implement ML systems end-to-end | Recommender, ranking, embeddings | Yes | Model design, evaluation, monitoring |
-| **ui-expert** | Design | Design and review UI/UX | Mobile-first, accessibility | No | ui-ux-pro-max, Playwright |
+| **ui-expert** | Design | Design and review UI/UX | Mobile-first, accessibility, registry-first protocol gate (when `features.has_design_system: true`) — BLOCKING reads on `${paths.design_system}/INDEX.md` + `tokens-reference.md` + `components/<Name>.md` per `framework/agents/design-system-protocol.md`, Component Discovery cascade before any design | No | ui-ux-pro-max, Playwright |
 | **visual-designer** | Design | Generate visual assets via Kie.ai | Illustrations, icons, hero images | Yes | Kie.ai API, WebP optimization |
 | **motion-expert** | Design | Design animations and micro-interactions | Transitions, timing, easing | No | Animation specs, a11y fallbacks |
 | **hyper-gamification-designer** | Design | Analyze game features and retention mechanics | Progression, reward loops | No | MDA analysis, economy balance |

package/framework/.claude/agents/code-reviewer.md

@@ -40,17 +40,53 @@ Before applying the review checklist, consult MEMORY for similar prior reviews:
 
 ## Design System Compliance (MANDATORY for UI work)
 
-When reviewing files that touch UI components, styling, or visual output, verify compliance against the Design System SSOT:
-
-1. If the project has a design system, read its index (typically `docs/design-system/INDEX.md` — component index + canonical authority matrix + quick rules MUST) before reviewing UI diffs.
-2. For any component in the diff, cross-check against the per-component spec (typically `docs/design-system/components/<Name>.md`) — variants, states, required props, accessibility contract.
-3. Enforce design-system MUST rules from the project's INDEX as HIGH-confidence findings. Typical rules include:
-   - No hardcoded hex, shadow, or border values — only canonical tokens.
-   - Text/background pairing rules for themed surfaces (project-specific — see the relevant pattern doc).
-   - Overlay/z-index decisions must follow the project's overlay decision tree.
-   - Motion must honor the project's reduced-motion variant rules.
-4. Violations of project-declared design-system MUST rules are HIGH — they block merge.
-5. Skipping this step when the diff includes UI is itself a protocol violation worth flagging.
+When reviewing files that touch UI components, styling, or visual output,
+follow the registry-first protocol defined in
+[`framework/agents/design-system-protocol.md`](../../agents/design-system-protocol.md)
+(SSOT — do not duplicate its rules here, treat any divergence as a bug in
+this file).
+
+Concrete enforcement contract for the review pass:
+
+1. When `features.has_design_system: true`, read `${paths.design_system}/INDEX.md`
+   (component index + Canonical Authority Matrix) before reviewing UI diffs.
+2. For any component in the diff, cross-check against
+   `${paths.design_system}/components/<Name>.md` — variants, states, required
+   props, accessibility contract.
+3. Enforce design-system MUST rules from the project's INDEX as HIGH-confidence
+   findings. Typical rules include:
+   - No hardcoded hex, shadow, radius, spacing literals — only tokens from
+     `${paths.design_system}/tokens-reference.md`.
+   - Text/background pairing rules for themed surfaces (see the relevant
+     pattern doc when `features.multi_tenant_theming: true`).
+   - Overlay/z-index decisions follow the project's overlay decision tree.
+   - Motion honors the project's reduced-motion variant rules.
+4. Re-implementation of an existing registry primitive is a HIGH finding —
+   the diff must reuse the primitive or propose a new variant in the registry.
+5. New primitives introduced without their `components/<Name>.md` spec are a
+   HIGH finding.
+6. Violations of project-declared design-system MUST rules are HIGH — they
+   block merge.
+7. Skipping this step when the diff includes UI is itself a protocol
+   violation worth flagging.
+8. **Post-Intervention Coherence Check (BLOCKING merge gate)** — for any
+   diff that touched a visual surface, verify the four reconciliation
+   conditions defined in [`design-system-protocol.md`](../../agents/design-system-protocol.md)
+   § "Post-Intervention Coherence Check":
+   (a) new primitive ⇒ `components/<Name>.md` spec present in the same diff,
+   (b) modified primitive ⇒ spec updated in the same diff,
+   (c) new/changed token ⇒ `tokens-reference.md` updated in the same diff,
+   (d) silently-existing primitive reused ⇒ INDEX entry added in the same diff.
+   Each failing condition is a HIGH finding with the canonical code
+   (`DS_INDEX_DRIFT` / `DS_COMPONENT_STALE` / `DS_TOKENS_DRIFT`). This is the
+   third and final gate after `ui-design`/`ui-expert`'s own post-intervention
+   check and the weekly `ds-drift` routine; if it trips here at review time,
+   it means the upstream checks were skipped — flag the protocol violation
+   alongside the drift.
+
+When `features.has_design_system: false`, the registry reads are skipped but
+the review still flags hardcoded values and inconsistencies against
+`${paths.ui_guidelines}`, and recommends `/design-system-init` in the report.
 
 ## Scope Boundary (MUST — read first)