baldart 3.9.0 → 3.12.0

package/CHANGELOG.md

@@ -5,6 +5,99 @@ 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.
+
+The layer is opt-in: at install / update / configure, BALDART asks "Enable LSP symbol-search layer?" and (on yes) detects the project's languages and installs the matching language servers — npm devDeps for TypeScript and Python, system commands printed for Go, Rust, Ruby.
+
+### Added
+
+- **`baldart.config.yml` → `features.has_lsp_layer`** — new boolean (default `false`). Gates the LSP retrieval tier in agents and skills. When `true`, also populates the new `lsp` section with the installed language servers.
+- **`baldart.config.yml` → `lsp.installed_servers` + `lsp.auto_verify`** — new top-level section tracking which language servers are recorded for the project and whether `baldart doctor` should re-verify them on every run.
+- **`framework/agents/code-search-protocol.md`** — new protocol module defining the retrieval hierarchy (RAG hybrid → LSP for symbols → Grep → Git), query-type discrimination, LSP budget (max 3 calls/task), and fallback rules. Referenced from `framework/agents/index.md`.
+- **`framework/.claude/skills/lsp-bootstrap/SKILL.md`** — new invokable skill (`/lsp-bootstrap`) that runs the install + verify flow as a standalone workflow. Refuses to run when `features.has_lsp_layer: false`. Idempotent.
+- **`src/utils/lsp-adapters/`** — new pluggable adapter registry (TypeScript, Python via Pyright, Go via gopls, Rust via rust-analyzer, Ruby via ruby-lsp). Each adapter exposes `detect(cwd)`, `installCommand()`, `verifyCommand()`, and `claudePluginId()`. Same pattern as `src/utils/tool-adapters/`. Add a new language by dropping in a `<lang>.js` file and registering it in `index.js`.
+- **`src/utils/lsp-installer.js`** — high-level installer used by `configure.js` and the `doctor` LSP step. `detectLanguages()` / `recommend()` / `installServers()` / `verifyServers()`. Pure detection has no side effects; install ops respect `--non-interactive`.
+- **`src/commands/configure.js` LSP block** — when the user opts in, autodetects languages, prompts per server, installs npm-mode adapters in-process, prints system-mode install commands, verifies binaries, and persists `lsp.installed_servers`. Re-running configure on an existing project re-detects and updates the list.
+- **`src/commands/doctor.js` LSP step** — new "LSP layer" line in the diagnostic table + a `lsp-fix` action that reinstalls broken servers. Surfaces missing binaries without breaking other doctor flows.
+- **`framework/templates/overlays/agents/codebase-architect.lsp-example.md`** — starter overlay demonstrating how to add project-specific LSP tuning (monorepo quirks, generated-code exclusions, callsite thresholds) on top of the shipped protocol.
+
+### Changed
+
+- **`framework/.claude/agents/codebase-architect.md`** — Investigation Protocol step 3 now points at `agents/code-search-protocol.md` for LSP escalation. Behavior under `features.has_lsp_layer: false` is unchanged.
+- **`framework/.claude/agents/REGISTRY.md`** — `codebase-architect` row gains "LSP symbol resolution (when `features.has_lsp_layer: true`)" as a specialization.
+- **`framework/.claude/skills/context-primer/SKILL.md`** — step 3 of the retrieval loop redirects to the code-search protocol for symbol-shaped queries when the flag is on.
+- **`framework/.claude/skills/bug/SKILL.md`** — Phase 0 step 3 references the protocol; `codebase-architect` now automatically uses LSP for symbol lookups during code-path mapping.
+- **`framework/.claude/skills/simplify/SKILL.md`** — deduplication step 3 uses LSP `find-references` to confirm callsites before recommending consolidation; eliminates false positives from textual name collisions and dead-code candidates.
+- **`framework/.claude/skills/prd/SKILL.md` / `new/SKILL.md`** — one-line note that LSP usage is transitive via `context-primer` / `codebase-architect` when the flag is on.
+- **`framework/templates/baldart.config.template.yml`** — adds `features.has_lsp_layer` and the new `lsp:` block with inline documentation.
+- **`framework/docs/PROJECT-CONFIGURATION.md`** — new § 4.5 row for `has_lsp_layer` and a new § 4.6 documenting the `lsp.*` keys, per-adapter install modes, and the fallback contract.
+
+### Notes
+
+- **Schema-change propagation** (matches the `v3.9.0` pattern): the new key is wired into the template, the configure prompt, the update-detector, the doctor table, the relevant skills, and the changelog.
+- **Backwards-compatible.** Pre-v3.10 consumers running `npx baldart update` see the standard "new config keys" warning (`has_lsp_layer`) and are offered `configure`. Agents and skills behave exactly as before when the flag is absent or `false`.
+- **Fallback contract.** When the layer is enabled but a server is missing, broken, or returns no references for a known symbol, agents silently fall back to Grep. Code search never fails because of LSP issues; `baldart doctor` surfaces the mismatch.
+- **Languages out of scope** (Java, C/C++, PHP, Elixir, …) can be added by dropping a new file under `src/utils/lsp-adapters/`. No core change required.
+
 ## [3.9.0] - 2026-05-22
 
 `worktree-manager` (`/mw`) gains a configurable merge strategy. The previous flow forced every consumer through `gh pr create` + `gh pr merge`; in repos where `develop` is not protected on GitHub, that roundtrip is unnecessary and was observed to stall (PR opened, never merged). The new `git.merge_strategy` key lets each project pick its lane.

package/README.md

@@ -183,18 +183,30 @@ 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 (new in v2.0.0 — 22 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`
-- **Design**: `frontend-design`, `ui-design`, `motion-design`, `gamification-design`
+- **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-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).
+
 ### Commands
 
 - **/new**: Batch orchestrator with QA validation, production readiness checklist, and context recovery (also available as a skill)

package/VERSION

@@ -1 +1 @@
-3.9.0
+3.12.0

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

@@ -8,16 +8,16 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 
 | Agent | Category | When to Use | Specialization | Can Edit Code | Key Tools |
 |-------|----------|-------------|----------------|---------------|-----------|
-| **codebase-architect** | Architecture | **MANDATORY** before planning/implementing changes | Platform analysis, system design, canonical-source resolution via Linking Protocol v1 | No | Code navigation, pattern tracing |
+| **codebase-architect** | Architecture | **MANDATORY** before planning/implementing changes | Platform analysis, system design, canonical-source resolution via Linking Protocol v1, LSP symbol resolution (when `features.has_lsp_layer: true`) | No | Code navigation, pattern tracing, LSP find-references / go-to-definition |
 | **plan-auditor** | Architecture | Review implementation plans before coding begins | Risk assessment, gap detection | Yes | Multi-persona review (eng/security/SRE) |
 | **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)
 

package/framework/.claude/agents/codebase-architect.md

@@ -163,6 +163,14 @@ Before providing any architectural guidance or implementation advice, follow thi
 3. **Targeted grep** (only if RAG was weak/empty): grep for 2-3 specific identifiers
    (function names, file patterns), NOT broad keyword sweeps across the entire codebase.
 
+   **LSP escalation (since v3.10.0):** when `features.has_lsp_layer: true` in
+   `baldart.config.yml` AND the query is a symbol/identifier (function, type, class,
+   variable name), prefer LSP `find-references` / `go-to-definition` over Grep — it
+   filters textual collisions before you read anything. Cap at 3 LSP calls per task,
+   then escalate to direct file reads. Falls back to Grep silently when the LSP tool
+   isn't loaded or returns nothing. See `framework/agents/code-search-protocol.md`
+   for the full hierarchy and query-type discrimination.
+
 4. **Targeted verification** — DO NOT read entire files. Instead:
    - For files **<200 lines**: read in full.
    - For files **200-500 lines**: read the first 50 lines (imports + exports) + the