baldart 3.10.0 → 3.13.0

package/CHANGELOG.md

@@ -5,6 +5,88 @@ 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.13.0] - 2026-05-23
+
+BALDART closes **two drift visibility gaps in one release**. (1) The CLI binary (installed globally via `npm i -g baldart`) and the framework payload (`.framework/` inside each consumer repo, updated by `baldart update`) drifted silently — users on an old CLI never learned that new flags, new doctor checks, or new adapters had shipped. (2) The framework payload on disk and the `.baldart/state.json` ledger could drift silently when the ledger write failed (the catch in `update.js` was silent until now), when an update flow exited mid-way, or when a manual commit excluded `.baldart/state.json` — `baldart doctor` had no way to detect or fix this. Both gaps are now closed: a **non-invasive CLI self-update notifier** for the first, and **ledger drift detection + self-heal** in the doctor for the second. The unifying theme is "no silent drift" — every layer that can fall out of sync now reports it and offers a one-step fix.
+
+### Added
+
+- **`src/utils/update-notifier.js`** — best-effort CLI self-update check. HTTPS GET to `https://registry.npmjs.org/baldart/latest` with a 1.5s timeout, cached at `~/.baldart/cli-update-check.json` (TTL 24h). Banner is printed from the cache on subsequent invocations (the very first run shows nothing — that is intentional; the check never blocks the command). The background refresh fire-and-forget: its timer is `unref()`'d and the underlying socket dies with the process, so the check can never hold the event loop open. Suppression: `BALDART_NO_UPDATE_CHECK=1`, `CI=true`, `NODE_ENV=test`, non-TTY stdout, or `--offline` on `baldart` / `baldart doctor` / `baldart version`.
+- **Top-of-run banner in `bin/baldart.js`** — when a newer baldart npm package has been detected on a previous run, every command prints a 3-line hint at startup (yellow arrow + bold version, then two gray lines): `↑ baldart X.Y.Z available (you have A.B.C)` + `Update with: npm i -g baldart@latest` + `Suppress with: BALDART_NO_UPDATE_CHECK=1`. Zero-latency (reads cache only); no banner if cache is missing or up-to-date.
+- **`CLI` row in `baldart doctor` diagnostic table** — always shown (independent of git/framework state), surfaces drift inline alongside framework version / config / overlays / hooks so the doctor remains the single pane of glass. Severity `warn` when an update is available, `ok` otherwise.
+- **CLI drift in `baldart version` box** — the existing `CLI: vX.Y.Z` line now appends `→ vA.B.C available (npm i -g baldart@latest)` when a newer version was detected.
+- **`State.reconcileInstalledVersion({ to, reason })` in `src/utils/state.js`** — new ledger reconciliation helper. Idempotent (no-op when `from === to`), audit-trailed (writes a `ledger-reconcile` history entry distinct from real `update` events), and reversible (pure local file write). Used by the doctor's new `reconcile-state-ledger` action and available for direct call from future recovery flows.
+- **Ledger drift detection in `baldart doctor`** — `detectState` now compares `.framework/VERSION` against `.baldart/state.json:installed_version` and surfaces a `stateLedgerDrift` state field when they diverge. The action planner inserts a `reconcile-state-ledger` action (`autoOk: true`, idempotent, no remote effects) that one-shot fixes the drift via `State.reconcileInstalledVersion()`. Drift is non-blocking — it pairs with other proposed actions instead of short-circuiting them.
+
+### Changed
+
+- **`src/commands/update.js`** — replaced the silent `try { State.recordUpdate(...) } catch (_) {}` on the ledger write with a visible warning + actionable next step. When the write fails or returns an unexpected `installed_version`, the user now sees a yellow warning explaining the drift (framework on disk is at vNEW but ledger still records vOLD) and is told to run `baldart doctor` to reconcile. This is the root cause of most "my doctor says I'm on the wrong version" reports — silent catches were hiding write failures (permissions, EBUSY) for weeks. New behavior makes the failure immediately visible and self-healable.
+
+### Notes
+
+- **CLI vs framework — two independent layers.** `npm i -g baldart@latest` updates the binary on disk (this package); `baldart update` updates the *framework payload* inside the consumer repo (the `.framework/` subtree). They are *independent* by design — a consumer may want to update the framework without touching the global CLI (or vice versa). The notifier surfaces drift on the *CLI* layer; the existing `Remote` row in doctor (and the `Remote:` line in `version`) surfaces drift on the *framework* layer. Both layers are now visible at a glance from the same diagnostic surface.
+- **Why not auto-install.** Three reasons we deliberately reject `npx baldart` auto-running `npm i -g`: (1) blast radius — global install impacts *every* project on the user's machine, not just the one they invoked from; (2) permissions — `npm i -g` often needs sudo (without nvm/volta), and a no-args `baldart` cannot trigger sudo prompts silently; (3) reproducibility — `--auto` runs in CI must be deterministic, so auto-updating the CLI mid-run would change behavior unpredictably. The notifier is the right level: visible, dismissible, never invasive.
+- **No new `baldart.config.yml` keys.** The notifier cache lives in `~/.baldart/cli-update-check.json` (per-user, not per-project), so the schema-change propagation rule (per `feedback_schema_change_propagation`) does not apply to this release. Suppression is via environment variable (`BALDART_NO_UPDATE_CHECK=1`) which is intentionally global — disabling the notifier in one project but enabling it in another is not a use case worth modeling.
+- **Backwards-compatible.** Pre-3.13 consumers see the new banner on their next `baldart` run after the npm package upgrades. Consumers that never want the check set `BALDART_NO_UPDATE_CHECK=1` in their shell rc; CI runs are auto-suppressed.
+- **No framework payload changes.** All work is inside `src/` and `bin/` — the framework agents/skills/commands/protocols are unchanged. This is purely a CLI-layer improvement; no consumer files are touched by `baldart update`.
+
+## [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

@@ -156,6 +156,30 @@ last-push info. Use `--offline` to skip the upstream fetch.
 
 State updates happen automatically — no manual bookkeeping required.
 
+### CLI self-update notifier (new in v3.13.0)
+
+The CLI binary (`baldart`, installed globally via `npm i -g baldart`) and the
+framework payload (`.framework/` inside each repo, updated by `baldart update`)
+are two independent layers. Until now the CLI drifted silently — users on an
+old CLI never learned about new flags or new doctor checks.
+
+Now every `baldart` run does a best-effort check against `registry.npmjs.org`
+(cached at `~/.baldart/cli-update-check.json` with a 24h TTL, 1.5s network
+timeout, fire-and-forget). When a newer version is available, a one-shot
+banner appears at the top of the run:
+
+```
+↑ baldart 3.13.0 available (you have 3.12.0)
+  Update with: npm i -g baldart@latest
+  Suppress with: BALDART_NO_UPDATE_CHECK=1
+```
+
+The notifier never installs anything automatically — global installs can
+require sudo and affect every other project on your machine, so the choice
+stays with you. CLI drift also appears inline in `baldart doctor` (new `CLI`
+row) and in `baldart version`. Auto-suppressed in CI, in non-TTY runs, with
+`--offline`, with `NODE_ENV=test`, or via `BALDART_NO_UPDATE_CHECK=1`.
+
 ### Project Configuration (new in v3.0.0)
 
 BALDART skills are **portable across projects**. Instead of hard-coding paths
@@ -183,18 +207,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.13.0

package/bin/baldart.js

@@ -3,6 +3,20 @@
 const { Command } = require('commander');
 const chalk = require('chalk');
 const packageJson = require('../package.json');
+const updateNotifier = require('../src/utils/update-notifier');
+
+// CLI self-update notifier (v3.13.0+). Best-effort; non-blocking; suppressed
+// in CI / non-TTY / via BALDART_NO_UPDATE_CHECK=1 / when --offline is passed.
+// Prints a one-shot hint at the top of the run if a newer npm version was
+// detected on a previous invocation, then kicks off a background refresh.
+// First-ever run shows nothing — that is intentional; we never block the
+// command on a network call.
+const rawArgsForNotifier = process.argv.slice(2);
+const offlineForNotifier = rawArgsForNotifier.includes('--offline');
+updateNotifier.announceAndRefresh({
+  currentVersion: packageJson.version,
+  offline: offlineForNotifier,
+});
 
 const program = new Command();
 

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)