baldart 5.1.0 → 5.2.1

package/CHANGELOG.md

@@ -5,6 +5,121 @@ 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).
 
+## [5.2.1] - 2026-07-03
+
+**`/mw` local-trunk sync robustness.** The worktree merge's local-trunk sync
+(step 4c "Common", both `pr` and `local-push` strategies) failed to
+fast-forward on the majority of real checkouts, needlessly leaving
+`SYNC-DEFERRED` / `SYNC-NEEDS-DECISION`. Two targeted fixes, kept single-sourced
+across the executed SSOT (`framework/.claude/skills/worktree-manager/scripts/merge-worktree.sh`)
+and the prose (`worktree-manager/SKILL.md` step 4c) — **without `git stash`**,
+which stays forbidden here because `refs/stash` is shared across all worktrees
+via `git.commondir` (the FEAT-0522 incident): a stash from the main checkout can
+pop into the wrong worktree, and two parallel `/mw` runs race on the shared
+stash list.
+
+- **Fix 1 — safe ref-advance when main is on another branch.** Previously, if
+  the main repo's HEAD was not on `$TRUNK`, sync did a fetch-only and always
+  emitted `SYNC-DEFERRED`, never advancing the local `$TRUNK` ref. Now it
+  fast-forwards `refs/heads/$TRUNK` via a ref-only, ff-only fetch
+  (`git fetch origin $TRUNK:$TRUNK`) that **never touches any working tree** and
+  never checks out — turning a large class of deferrals into a clean sync
+  (`sync_marker: none`). If `$TRUNK` is checked out in another worktree, git
+  refuses and it falls back to fetch-only + defer.
+- **Fix 2 — accurate ff-fail disambiguation.** When the ff failed with a
+  tracked-clean tree and no owned/foreign dirt, the code fell to a misleading
+  "clean (diverged?)" marker (the dirty scan uses `--untracked-files=no`, so an
+  untracked-file collision was invisible to it). Now it disambiguates via
+  `merge-base --is-ancestor` between a **genuine branch divergence** (needs a
+  rebase/merge decision) and an **untracked-file collision** (the blocking files
+  are enumerated), emitting the correct actionable marker.
+
+Behaviour is strictly safer: cases #2 (foreign uncommitted work) and #3 (real
+divergence) still defer to ONE explicit user gate — never auto-committed, never
+stashed — which is the correct behaviour on a shared checkout.
+
+**Codex parity: portable.** The change is pure git plumbing inside the
+dual-runtime `merge-worktree.sh` (executed identically under Claude and Codex)
+plus its prose twin; no runtime-specific mechanic, no config key. The
+schema-change propagation rule does not apply (no `baldart.config.yml` key).
+
+## [5.2.0] - 2026-07-03
+
+**The local design studio.** `/ui-design` is refounded from the root as the
+top-of-the-line skill for designing, prototyping and restyling UI locally —
+the internal twin of the Claude Design handoff — absorbing design
+intelligence distilled from three state-of-the-art open repos
+([impeccable](https://github.com/pbakaus/impeccable) Apache-2.0,
+[taste-skill](https://github.com/Leonxlnx/taste-skill) MIT,
+[open-design](https://github.com/nexu-io/open-design) Apache-2.0, attributed
+in each derived reference). The superseded `frontend-design` /
+`ui-ux-pro-max` / `huashu-design` dependencies are cut, and the skill-routing
+failure ("agents pick frontend-design for UI work") is fixed at every layer.
+
+- **`ui-design` v2.0.0** (public step contract A–H and the `/prd` 3a–3e
+  mapping UNCHANGED):
+  - NEW **Step C.0 — Design Read & Direction Lock** (`references/design-brief.md`):
+    register (brand/product), regime (in-context/exploration), dials
+    VARIANCE/MOTION/DENSITY, two-altitude slop test, color-commitment axis,
+    dark/light scene sentence, anti-references, ONE-question ambiguity rule,
+    cross-run rotation check.
+  - NEW **`references/design-directions.md`** (12-direction aesthetic menu +
+    font/palette reflex-reject lists: LILA rule, premium-consumer beige ban,
+    serif discipline), **`references/craft-standards.md`** (always-on craft;
+    numeric ranges cite `design-system-protocol.md` § Reference Tables; the
+    **canonical new home of Performance Gates/CWV 2026 + Modern CSS + Form
+    quality**, migrated from frontend-design), **`references/anti-slop.md`**
+    (the Tells catalog — absolute bans, count-bounded rations, copy tells;
+    every ban with a declared-override path).
+  - NEW **`scripts/craft-check.mjs`** — deterministic anti-slop/craft gate
+    (~22 rules, zero-dep, `--json`, `--strict-palette`); generator self-check
+    + Step D Gate 0; identical on Claude and Codex.
+  - **Step D rewritten as dual-lens**: Gate 0 craft-check (fail-fast, hidden
+    from lenses) → Lens A **`ui-quality-critic`** (true evaluator diversity —
+    different agent definition than the generator; rubric SSOT unchanged) →
+    Lens B fresh `ui-expert` conformance (B1–B5, evidence-cited scoring,
+    worst-sustained-band, no grade inflation). Honest **degraded mode** on
+    non-multimodal runtimes (mandatory `⚠️ DEGRADED` banner).
+  - Generation is **token-first** (project tokens embedded in `:root` so the
+    mockup speaks the project token language, mirroring the Claude Design
+    channel) and **`data-region`-annotated** (surgical iteration +
+    deterministic inventory join into `component_bindings`).
+- **`frontend-design` v2.0.0 — retired to a ROUTER**: the body reroutes
+  deterministically (design → `/ui-design`, approved mockup →
+  `/ui-implement`, direct in-code UI → `ui-expert`, motion →
+  `/motion-design`); the broad legacy triggers are KEPT on purpose as a
+  honeypot so reflexive mis-routing gets corrected instead of landing on
+  stale guidance. Consumer overlays with aesthetic mandates should port to
+  `.baldart/overlays/ui-design.md`.
+- **Routing fix at every layer**: `ui-design` description rewritten to claim
+  design/restyle/prototype triggers (IT+EN) with an explicit NOT-list;
+  `agents/index.md` gains a DESIGN-DECISION routing rule;
+  `agents/skills-mapping.md` UI section + decision tree rewritten
+  (`ui-ux-pro-max` marked superseded, never route to it).
+- **Agents**: `ui-quality-critic` v1.1.0 (gating extended: invoked by
+  `/e2e-review` Phase 4b OR `/ui-design` Step D — never ad-hoc; mockup
+  payload flavor documented); `ui-expert` v2.1.0 (CWV pointer re-targeted to
+  `craft-standards.md`; Linked Skills drop `frontend-design`/`ui-ux-pro-max`,
+  `ui-design` references become the standalone design-intelligence library);
+  `coder` v2.0.2 + `remotion-animator-orchestrator` v1.0.1 (pointer
+  re-targets). REGISTRY rows updated.
+- **Docs**: `design-system-protocol.md` consumer lists updated
+  (`frontend-design` → `ui-implement` where apt), `PROJECT-CONFIGURATION.md`,
+  `configure.js` design-system hint, README + CLAUDE.md conventions;
+  `e2e-review` 1.3.1 / `design-system-init` 1.0.1 / `gamification-design`
+  1.0.1 pointer fixes.
+- **Fix (`update`) riding in this release**: `isAbsorbedAgainstUpstream` now
+  scopes the absorbed-commit divergence check to the `.framework/framework/`
+  payload only (`GitUtils.absorbablePayloadSubset`) — mixed commits and
+  subtree bookkeeping no longer mis-flag net-zero divergence as blocking
+  `custom-other` (repro: mayo v5.0.1→v5.1.0 update).
+- **No new `baldart.config.yml` key** (rides on `features.has_design_system`
+  + existing keys) — the schema-change propagation rule does NOT apply.
+- **Codex parity: portable** — same SKILL.md bundles (two symlinks), zero-dep
+  script, spawn/decision-gate bindings cited from
+  `runtime-portability-protocol.md`, and the visual lenses degrade honestly
+  (banner) instead of silently on non-multimodal runtimes.
+
 ## [5.1.0] - 2026-07-03
 
 **The research layer.** Research becomes a first-class, reusable asset: the

package/README.md

@@ -222,7 +222,7 @@ Bundled skills:
 
 - **Workflow**: `new`, `new2` (v4.16.0 — EXPERIMENTAL workflow-hosted `/new`, Claude-only, for A/B testing context economy), `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), `graphify-bootstrap` (v4.21.0 — code knowledge graph), `graph-align` (v4.21.0 — doc↔graph alignment), `toolchain-bootstrap` (v4.41.0 — curated dev toolchain), `e2e-review` (v3.18.0)
-- **Design**: `frontend-design`, `ui-design`, `ui-implement` (v4.82.0 — implement an approved mockup end-to-end + self-verify fidelity; the mockup→code playbook SSOT, delegated from `/new`), `motion-design`, `gamification-design`, `design-system-init` (v3.11.0 — bulk registry bootstrap/upgrade), `ds-new` (v4.69.0 — single-element guided creation: one component or token, reuse-first → optional scaffold → document + register + govern + verify; the on-the-fly twin of `design-system-init`), `ds-edit` (v4.70.0 — deliberate edit of one existing element: resync / extend-variant / breaking / re-govern; regenerates the spec preserving agentic fields + prose, same canonical template), `ds-render` (v4.76.0 — render primitives in isolation to PNG via Storybook+Playwright), `design-sync` (v4.76.0 — mirror the registry to its Claude Design satellite), `ds-handoff` (v4.79.0 — field-level 1:1 Claude Design handoff brief: grounds every screen's fields in the real data schemas + coverage-gates before emitting; the SSOT for the Claude Design prompt, delegated from `/prd`)
+- **Design**: `ui-design` (v2.0.0, framework v5.2.0 — the **local design studio**: Design Read & direction lock, 12-direction menu, deterministic anti-slop craft gate `craft-check.mjs`, dual-lens evaluation with `ui-quality-critic`; the internal twin of the Claude Design handoff), `frontend-design` (retired to a router since v5.2.0 — reroutes to `ui-design` / `ui-implement` / `ui-expert`), `ui-implement` (v4.82.0 — implement an approved mockup end-to-end + self-verify fidelity; the mockup→code playbook SSOT, delegated from `/new`), `motion-design`, `gamification-design`, `design-system-init` (v3.11.0 — bulk registry bootstrap/upgrade), `ds-new` (v4.69.0 — single-element guided creation: one component or token, reuse-first → optional scaffold → document + register + govern + verify; the on-the-fly twin of `design-system-init`), `ds-edit` (v4.70.0 — deliberate edit of one existing element: resync / extend-variant / breaking / re-govern; regenerates the spec preserving agentic fields + prose, same canonical template), `ds-render` (v4.76.0 — render primitives in isolation to PNG via Storybook+Playwright), `design-sync` (v4.76.0 — mirror the registry to its Claude Design satellite), `ds-handoff` (v4.79.0 — field-level 1:1 Claude Design handoff brief: grounds every screen's fields in the real data schemas + coverage-gates before emitting; the SSOT for the Claude Design prompt, delegated from `/prd`)
 - **Product**: `seo-audit`, `copywriting`, `api-design-principles`
 - **Knowledge**: `doc-writing-for-rag`, `capture` (LLM wiki overlay), `research` (v5.1.0 — routed research over the reusable research library: profile + source-matrix routing, reuse pre-flight, `senior-researcher` fan-out, matrix growth loop)
 - **Internationalization**: `i18n` (v4.52.0 — audit the context registry + context-aware translation into native locale files), `i18n-adopt` (v4.52.0 — one-shot migration that externalizes all hardcoded strings on an existing codebase); both gated on `features.has_i18n`
@@ -231,7 +231,7 @@ Bundled skills:
 
 ### 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.
+When `features.has_design_system: true`, every UI-touching agent/skill/command (`ui-expert`, `ui-design`, `ui-implement`, `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.
 
 **Closed-Set Selection Policy (v4.68.0).** The registry has a token layer and a component layer, but until now nothing asserted the *boundary* of a category — so an agent designing from a mockup could write a third "header" when two canonical ones already cover every case, and the duplicate was only caught (reactively) at review. The closed-set policy adds the missing third layer: each component spec declares the presentational **role** it is canonical for (`canonical_for: [page-header@depth-0]`) and whether that role family is **closed** (`selection_closed`), aggregated into a generated `INDEX.md` § "Selection Policy". A closed family means *introducing a new canonical member is a governance decision, not an implementation act*. Three layers enforce it: (1) **`/prd` Component Reconciliation** — a human-in-the-loop *match-before-generate* gate that binds each mockup region to an existing component (or a governed NEW one) and asks *"this becomes the standard?"* only on genuine ambiguity, persisting the decision into the card's `component_bindings`; (2) **`baldart ds-gate`** — a deterministic, zero-false-positive build-time gate that BLOCKS (`DS_CLOSED_SET_VIOLATION`) any change adding a new canonical in a closed family (wired into `qa-sentinel` / `/new` / `code-reviewer`, the design-system analogue of the i18n gate); (3) the existing review + weekly `ds-drift` safety net. Rides on `features.has_design_system` — no new config key; `/design-system-init --upgrade` derives the closed sets from your existing `must_rules`. This closes a gap no 2026 design-to-code vendor hard-gates (Figma Code Connect, Storybook MCP, shadcn are all advisory).
 
@@ -245,7 +245,7 @@ Tuning lives under `features.e2e_review` in `baldart.config.yml`: `fidelity_tole
 
 ### 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).
+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` / `ui-implement` (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)
 

package/VERSION

@@ -1 +1 @@
-5.1.0
+5.2.1

package/framework/.claude/agents/CHANGELOG.md

@@ -7,6 +7,51 @@ per-item agent merge, the doctor probes, and the discovery hooks — like
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · per-agent SemVer.
 
+## [ui-expert v2.1.0] — 2026-07-03 (framework v5.2.0)
+
+The `/ui-design` v2.0.0 studio refactor. No H2 moved; edits are within
+`## Red Flags` (one pointer) and `## Linked Skills`.
+
+- CWV full-reference pointer re-targeted: `frontend-design` § Performance
+  Gates → `ui-design/references/craft-standards.md` § Performance Gates (the
+  new canonical home after the frontend-design router demotion).
+- `## Linked Skills`: `frontend-design` and `ui-ux-pro-max` entries REMOVED
+  (both superseded); the `ui-design` entry now also names its references
+  (`craft-standards` / `anti-slop` / `design-directions`) as the agent's
+  standalone design-intelligence library — Read directly, no skill
+  invocation, replacing `ui-ux-pro-max` for palettes/pairings/directions.
+
+## [ui-quality-critic v1.1.0] — 2026-07-03 (framework v5.2.0)
+
+Second consumer: `/ui-design` Step D (mockup quality lens). `version:`
+frontmatter added (pre-5.2 body is implicitly 1.0.x). No H2 moved.
+
+- Gating reworded from "features.has_e2e_review, exists only for /e2e-review"
+  to **gated-by-invocation**: spawned by `/e2e-review` Phase 4b (that lane
+  still gated on `features.has_e2e_review`) OR `/ui-design` Step D (no
+  feature gate) — never ad-hoc. Rationale: the rubric judges any rendered UI
+  screenshot; binding it to the e2e harness was an artifact of its birth
+  context, and `/ui-design` needs a *different agent definition* than its
+  generator to break same-definition self-review (v4.61.0 discipline).
+- Input Contract: documented the mockup payload flavor
+  (`route: "mockup:<slug>/option-<x>"`); no-source prohibition explicitly
+  covers the mockup HTML.
+- description updated (2 lines kept).
+
+## [remotion-animator-orchestrator v1.0.1] — 2026-07-03 (framework v5.2.0)
+
+- Component-build delegation re-targeted: `frontend-design` (retired to a
+  router) → `ui-expert` in the Asset Generation phase, the boundary list, and
+  the parallel-invocation example. `version:` frontmatter added.
+
+## [coder v2.0.2] — 2026-07-03 (framework v5.2.0)
+
+- `## Linked Skills`: `frontend-design` entry replaced with a
+  references-only pointer to `ui-design/references/craft-standards.md`
+  (Performance Gates/CWV, form quality, modern CSS) for UI-adjacent markup in
+  mixed cards — with the explicit reminder that full UI work routes to
+  `ui-expert` per `AGENTS.md` § delegation.
+
 ## [senior-researcher v2.0.0] — 2026-07-03 (framework v5.1.0)
 
 The research-layer restructuring (profiles + library + source matrix). Pre-5.1

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

@@ -28,10 +28,10 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 | **merge-conflict-resolver** | DevOps | Resolve the final-merge **code** conflicts OFF the orchestrator context. Auto-spawned by `/new` Phase 6 (and standalone `/mw`) ONLY when the deterministic `scripts/merge-worktree.sh` pauses with `status:code_conflict` — the script already resolved every additive doc/registry/JSONL conflict; this agent adjudicates the irreducible code/test hunks then lets the script land. Runs in a fresh isolated context so the conflict churn never re-enters the bloated end-of-batch orchestrator. Never spawned ad-hoc. | Additive-vs-semantic hunk judgment (semantic → STOP), `merge-worktree.sh --continue` rebase loop, anti-fabrication disk gate, COMPACT return | Yes — the **ONE bounded exception** to coder's "branches off-limits" rule: worktree-scoped, merge phase only, post-checks-passed; lands via the script, never hand-rolled git | git conflict resolution, `merge-worktree.sh --continue` |
 | **hybrid-ml-architect** | ML | Design/implement ML systems end-to-end | Recommender, ranking, embeddings | Yes | Model design, evaluation, monitoring |
 | **i18n-translator** | Localization | Translate user-facing labels into the maintained target languages (invoked by `/i18n` + the `i18n-align` routine). Gated on `features.has_i18n`. | Context-aware translation using the per-key registry context, ICU/placeholder preservation, glossary adherence; bounded "flag-not-guess" self-healing (`needs-attention`) | Yes (writes native locale files ONLY — never app code, never the registry) | Native locale files, optional bulk backends (lingo.dev/languine) |
-| **ui-expert** | Design | Design, implement, 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 | Yes (generates UI / HTML mockups in `ui-design` Step C; a separate fresh instance acts as design-quality evaluator in Step D) | ui-ux-pro-max, Playwright |
+| **ui-expert** | Design | Design, implement, 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 | Yes (generates UI / HTML mockups in `ui-design` Step C.1; a separate fresh instance acts as the Step D conformance lens — design quality is judged by `ui-quality-critic`) | ui-design references (design-directions / craft-standards / anti-slop), Playwright |
 | **visual-fidelity-verifier** | Design | Compare an implemented UI route against its mockup (or design-system spec) and return a severity-tagged JSON report. Auto-invoked by `/e2e-review` skill (Phase 4) — never spawned ad-hoc. Stateless. Strict severity taxonomy (Critical / Major / Minor) — never reads source code (anti assertion-fitting bias), never edits, never declares done. Emits `data-state-mismatch` when the render is in the wrong data state. | Visual diff, severity taxonomy, design-system compliance check via registry cascade | No | Vision (multimodal), Read (screenshots + registry only), Playwright screenshots passed in by orchestrator |
 | **markup-fidelity-verifier** | Design | **Route-INDEPENDENT structural twin** of `visual-fidelity-verifier`: compare the implementation's code structure against the mockup expressed as code (`links.design` HTML or `links.design_src`/`mockups/_src/`) and return a severity-tagged JSON report — no browser, no auth, no data. Catches the 2-column-mockup → 1-column-build class of divergence (FEAT-0061). Auto-invoked by `/e2e-review` (Phase 2.7) — never spawned ad-hoc. Stateless. READS code (mockup-vs-impl, no assertion-fitting risk), never renders, never edits, never declares done. Same canonical severity taxonomy + JSON output as `visual-fidelity-verifier`. Fixes route to `ui-expert`. | Code-structural diff (DOM tree-edit-distance analogue), layout/grid/order/token-bypass, design-to-code fidelity | No | Read (mockup markup + implementation source) |
-| **ui-quality-critic** | Design | Judge the **intrinsic design quality** of an implemented UI screenshot against a scientific 10-dimension rubric (hierarchy, typographic & spacing rhythm, color/contrast, density, composition, states, motion, polish, brand) and return a severity-tagged JSON report + per-dimension scores. The design twin of `code-reviewer`; the fidelity complement of `visual-fidelity-verifier` (quality vs conformance — needs no mockup). Auto-invoked by `/e2e-review` (Phase 4b) — never spawned ad-hoc. Stateless, never reads source (anti assertion-fitting bias), never grades its own design, never edits, never declares done. Fixes route to `ui-expert`. Return Contract: JSON (already COMPACT). | Design-quality critique, rubric scoring, calibration anchors per dimension | No | Vision (multimodal), Read (screenshots + registry/guidelines only) |
+| **ui-quality-critic** | Design | Judge the **intrinsic design quality** of a UI screenshot (implemented route or mockup option) against a scientific 10-dimension rubric (hierarchy, typographic & spacing rhythm, color/contrast, density, composition, states, motion, polish, brand) and return a severity-tagged JSON report + per-dimension scores. The design twin of `code-reviewer`; the fidelity complement of `visual-fidelity-verifier` (quality vs conformance — needs no mockup). Invoked by `/e2e-review` (Phase 4b) and `/ui-design` (Step D quality lens) — never spawned ad-hoc. Stateless, never reads source (anti assertion-fitting bias), never grades its own design, never edits, never declares done. Fixes route to `ui-expert`. Return Contract: JSON (already COMPACT). | Design-quality critique, rubric scoring, calibration anchors per dimension | No | Vision (multimodal), Read (screenshots + registry/guidelines only) |
 | **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/coder.md

@@ -4,7 +4,7 @@ description: "Write, modify, or refactor production code. For features, bugs, an
 model: opus
 effort: high
 color: red
-version: 2.0.1
+version: 2.0.2
 ---
 
 > **YOLO MODE**: All agents spawned via the Task tool MUST use `mode: "bypassPermissions"`. No exceptions.
@@ -221,8 +221,8 @@ You MUST use these skills when applicable:
 
 ### `vercel-react-best-practices`
 React performance patterns (any React stack, Next.js included). When: writing React components, optimizing renders, async data, bundle size. Skill not installed (non-React stack / no plugin) → skip silently.
-### `frontend-design`
-Production-grade frontend code with high design quality. When: building new UI components or complex layouts.
+### `ui-design` (references only — not the skill workflow)
+Craft reference for presentational code you cannot delegate: Read `ui-design/references/craft-standards.md` (Performance Gates/CWV 2026, form quality, modern CSS). When: a mixed card touches UI-adjacent markup. Full UI work still routes to `ui-expert` per `AGENTS.md` § delegation — never build UI yourself. (The `frontend-design` skill is retired to a router since framework v5.2.0.)
 {{#deploy_vercel}}
 ### `vercel:deploy`
 Deploying to Vercel. When: the user requests deployment.

package/framework/.claude/agents/remotion-animator-orchestrator.md

@@ -6,6 +6,7 @@ aliases:
 description: "Orchestrator for creating stunning Remotion animations with custom visual assets. Use when: creating animated videos, motion graphics, promotional videos, explainers, or any Remotion project requiring custom illustrations."
 model: sonnet
 color: magenta
+version: 1.0.1
 ---
 
 You are the Remotion Animator Orchestrator, an expert in creating stunning animated videos by coordinating visual asset creation with programmatic animation implementation. You specialize in orchestrating multiple specialized agents to produce cohesive, visually distinctive video content.
@@ -35,7 +36,7 @@ You control the execution order for animation projects:
 3. **Asset Generation Phase** → Coordinate visual agents:
    - `ui-expert` → Design direction, typography, color systems
    - `visual-designer` → Illustrations, icons, backgrounds via image generation API
-   - `frontend-design` → Animated React components, SVG illustrations as code
+   - `ui-expert` → Animated React components, SVG illustrations as code (craft reference: `ui-design/references/craft-standards.md`)
 4. **Implementation Phase** → Build Remotion compositions following `remotion-best-practices`
 5. **Refinement Phase** → Polish timing, transitions, visual coherence
 
@@ -51,7 +52,7 @@ You control the execution order for animation projects:
 **You DO NOT:**
 - Generate illustrations yourself (delegate to `visual-designer`)
 - Design UI layouts (delegate to `ui-expert` for direction)
-- Create complex React components from scratch (delegate to `frontend-design`)
+- Create complex React components from scratch (delegate to `ui-expert`)
 - Skip the discovery phase - always understand requirements first
 
 ## Required Inputs
@@ -99,7 +100,7 @@ Animation intent:
 Invoke simultaneously:
 ├── visual-designer: Hero illustration
 ├── visual-designer: Background set
-└── frontend-design: Animated logo component
+└── ui-expert: Animated logo component
 ```
 
 **Sequential** (when there are dependencies):

package/framework/.claude/agents/ui-expert.md

@@ -3,7 +3,7 @@ name: ui-expert
 description: "Design and review UI/UX for your project. For new components, pages, or design reviews."
 model: opus
 color: purple
-version: 2.0.0
+version: 2.1.0
 ---
 
 You are a UI/UX expert specializing in design systems, mobile-first responsive design, and conversion-focused interfaces.
@@ -121,7 +121,7 @@ Surfaces with AI-generated output: streaming tokens append without re-layout (`m
 
 ## Performance Gates (BLOCKING for any production-facing surface)
 
-UI decisions causing CWV regressions are HIGH findings — not "polish later". Full reference (CWV 2026 thresholds, LCP image pattern, INP fixes, CLS budget, modern CSS): the `frontend-design` skill § Performance Gates — load it when building/reviewing production surfaces. **Immediate red flags**: LCP image `loading="lazy"` or client-rendered post-hydration · media without `width`/`height` or `aspect-ratio` · web font without `font-display` strategy or metric-compatible fallback · skeleton dimensions ≠ real content · late-injected UI pushing content down instead of reserving space · input handler recomputing synchronously per keystroke (debounce to one frame) · `setInterval` polling (use stale-while-revalidate).
+UI decisions causing CWV regressions are HIGH findings — not "polish later". Full reference (CWV 2026 thresholds, LCP image pattern, INP fixes, CLS budget, modern CSS): the `ui-design` skill's `references/craft-standards.md` § Performance Gates — load it when building/reviewing production surfaces. **Immediate red flags**: LCP image `loading="lazy"` or client-rendered post-hydration · media without `width`/`height` or `aspect-ratio` · web font without `font-display` strategy or metric-compatible fallback · skeleton dimensions ≠ real content · late-injected UI pushing content down instead of reserving space · input handler recomputing synchronously per keystroke (debounce to one frame) · `setInterval` polling (use stale-while-revalidate).
 
 ## Project Terminology (Use Exactly)
 
@@ -188,17 +188,11 @@ Direct and authoritative but constructive: state violations with specific guidel
 
 You MUST use these skills when applicable:
 
-### `frontend-design`
-Production-grade component/page generation AND the canonical **Performance Gates** reference (CWV 2026 thresholds, LCP pattern, INP fixes, CLS budget, modern CSS). When: building/reviewing any production surface; citing a CWV threshold or modern-CSS pattern verbatim.
+### `ui-design`
+The local design studio: structured design exploration with a locked Design Read, deterministic craft gate, and separated generator/evaluator verification. When: designing a new page/component end-to-end, from `/prd` Step 3, or on "3 options" requests. Its references are ALSO your standalone design-intelligence library — Read them directly (no skill invocation needed) when building without an existing direction: `references/craft-standards.md` (always-on craft + the canonical **Performance Gates**/CWV + modern CSS + form quality), `references/anti-slop.md` (the Tells catalog — binding on everything you produce), `references/design-directions.md` (aesthetic directions, font/palette pools + reflex-reject lists — replaces the retired `ui-ux-pro-max`).
 
 ### `motion-design`
 Easing curves, duration budgets, stagger, spring parameters, reduced-motion strategy, View Transitions specifics (reference tables in `reference/timing-easing-tables.md`). When: any animation/micro-interaction decision — cite the tables, never invent curves or durations.
 
-### `ui-design`
-Structured design exploration with generator/evaluator separation, sprint contracts, Playwright visual verification. When: designing a new page/component end-to-end, from `/prd` Step 3, or on "3 options" requests.
-
-### `ui-ux-pro-max`
-Design styles, palettes, font pairings, component pattern catalog. When: selecting palettes/pairings without an existing project direction.
-
 ### `webapp-testing` / `playwright-skill`
 Visual verification at multiple viewports (320/375/768/1280px), focus-order capture, accessibility snapshots, screenshot regression. When: a UI change is implemented and needs confirmation across breakpoints, keyboard navigation, reduced-motion/high-contrast/dark mode.

package/framework/.claude/agents/ui-quality-critic.md

@@ -1,8 +1,9 @@
 ---
 name: ui-quality-critic
-description: "Judge the intrinsic design quality of an implemented UI screenshot against a scientific rubric (hierarchy, rhythm, balance, polish) and return a severity-tagged JSON report with per-dimension scores. Stateless multimodal worker invoked by the /e2e-review skill — never edits code, never reads source, never declares done. Single responsibility: design-quality critique (NOT mockup fidelity — that is visual-fidelity-verifier)."
+description: "Judge the intrinsic design quality of a UI screenshot (implemented route, or a mockup option) against a scientific rubric (hierarchy, rhythm, balance, polish) and return a severity-tagged JSON report with per-dimension scores. Stateless multimodal worker invoked by the /e2e-review skill (Phase 4b) and the /ui-design skill (Step D quality lens) — never ad-hoc; never edits code, never reads source, never declares done. Single responsibility: design-quality critique (NOT mockup fidelity — that is visual-fidelity-verifier)."
 model: opus
 color: purple
+version: 1.1.0
 ---
 
 You are the **UI Quality Critic**. You exist for one purpose: look at a rendered
@@ -20,8 +21,11 @@ still be poor design. That gap is your job.
 
 You are stateless. You do not iterate. You do not fix. You report what you see
 against the rubric, with a structured severity tag and an actionable fix hint
-per finding. The orchestrating skill (`/e2e-review`) runs the bounded
-critic→fix loop and decides what to do with your output.
+per finding. The orchestrating skill (`/e2e-review` on implemented routes,
+`/ui-design` on mockup options) runs the bounded critic→fix loop and decides
+what to do with your output. Whether the screenshot renders shipped code or a
+throwaway HTML mockup changes nothing about your job: good design is good
+design.
 
 ## Project Context
 
@@ -30,10 +34,13 @@ critic→fix loop and decides what to do with your output.
 `identity.audience_segments`, `features.has_design_system`,
 `features.e2e_review.fidelity_tolerance`.
 
-**Gated by features:** `features.has_e2e_review`. The agent refuses to run when
-`false` — it exists only to support the `/e2e-review` skill. The quality
-critique itself does **not** require a mockup and does **not** require a design
-system: when `features.has_design_system: false` it judges against
+**Gated by invocation, not ad-hoc:** you run only when spawned by an
+orchestrating skill — `/e2e-review` Phase 4b (gated on
+`features.has_e2e_review`; refuse that lane when `false`) or `/ui-design`
+Step D (mockup quality lens — no feature gate; a design run needs no e2e
+harness). Never spawned ad-hoc. The quality critique itself does **not**
+require a mockup and does **not** require a design system: when
+`features.has_design_system: false` it judges against
 `${paths.ui_guidelines}` + the universal rubric below; when `true` it
 additionally grounds numeric thresholds in the registry.
 
@@ -66,7 +73,8 @@ assume project-specific defaults. See `framework/agents/project-context.md` § 3
 
 ## Input Contract
 
-The orchestrator (`/e2e-review`) invokes you with this JSON payload:
+The orchestrator (`/e2e-review`, or `/ui-design` with the mockup flavor
+below) invokes you with this JSON payload:
 
 ```json
 {
@@ -96,6 +104,13 @@ aesthetic, `identity.design_philosophy`). These tell you *which* row of each
 reference table the project chose, so your critique judges against the project's
 own discipline, not a generic ideal.
 
+**Mockup flavor (`/ui-design` Step D):** identical payload with
+`card_id: "mockup:<slug>"`, `route: "mockup:<slug>/option-<x>"`, and
+`implementation_screenshot_path` pointing at the rendered mockup capture
+(`states_screenshots` may carry the 375px mobile capture). Judge it exactly
+like an implemented screen; the no-source prohibition applies unchanged (the
+mockup HTML is source — do not read it).
+
 ## The Quality Rubric (CANONICAL — 10 dimensions)
 
 This rubric is defined in
@@ -261,9 +276,10 @@ suppressing severity to match the mode is a protocol violation.
   separation is the entire point (the generator must not grade itself).
 - You are not `code-reviewer`. That agent reviews source for bugs and registry
   compliance. You never read source.
-- You are not the orchestrator. `/e2e-review` aggregates your findings, runs the
-  bounded self-heal loop (routing your `source: "design-quality"` findings to
-  `ui-expert`), and produces the final pass / block decision.
+- You are not the orchestrator. `/e2e-review` (or `/ui-design`) aggregates your
+  findings, runs the bounded self-heal/iteration loop (routing your
+  `source: "design-quality"` findings to `ui-expert`), and produces the final
+  pass / block decision.
 
 ## Linked Protocols
 

package/framework/.claude/skills/design-system-init/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.0.1 — 2026-07-03
+
+- Lista consumer del registry aggiornata: `frontend-design` → `ui-implement`
+  (`frontend-design` ritirata a router, framework v5.2.0).
+
 ## 1.0.0 — 2026-07-01
 
 - Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/design-system-init/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: design-system-init
 effort: medium
-version: 1.0.0
+version: 1.0.1
 description: >
   Bootstrap OR upgrade a component registry / design system. GREENFIELD: scaffolds
   ${paths.design_system}/INDEX.md (a thin generated router), a DTCG
@@ -25,7 +25,7 @@ description: >
 Scaffold the component registry that the registry-first protocol
 (`framework/agents/design-system-protocol.md`) treats as BLOCKING for every
 UI task. Without a registry, the BLOCKING reads in `ui-design`,
-`frontend-design`, `ui-expert`, and `/design-review` are inert — they have
+`ui-implement`, `ui-expert`, and `/design-review` are inert — they have
 nothing to read. This skill creates the missing pieces from the codebase's
 current state so the discipline can kick in immediately.
 

package/framework/.claude/skills/e2e-review/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.3.1 — 2026-07-03
+
+- Boundary pointer: "Not a design generator" ora punta solo a `ui-design`
+  (`frontend-design` ritirata a router, framework v5.2.0).
+
 ## 1.3.0 — 2026-07-02
 
 - **Analysis-profile contract (framework v4.94.0)**: the two `codebase-architect` reverse-dependency lookups (routes importing a changed component; primitives used by a route in compliance-only mode) pass `PROFILE=impact` per `framework/agents/analysis-profiles.md`.

package/framework/.claude/skills/e2e-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: e2e-review
 effort: medium
-version: 1.3.0
+version: 1.3.1
 description: >
   Deterministic, BLOCKING end-to-end review run after a feature is implemented.
   Combines functional E2E (Playwright spec written by `coder`, executed via
@@ -1049,7 +1049,7 @@ and starts from Phase 3 (skipping plan extraction and mockup cascade).
 ## What This Skill Is NOT
 
 - **Not a code reviewer** — that is `/codexreview` + `code-reviewer`.
-- **Not a design generator** — that is `ui-design` / `frontend-design`.
+- **Not a design generator** — that is `ui-design`.
 - **Not a mockup creator** — when no mockup exists, the skill degrades to
   compliance-only or skip; it does not invent one.
 - **Not a unit-test runner** — that is `qa-sentinel`.

package/framework/.claude/skills/frontend-design/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 2.0.0 — 2026-07-03
+
+- **BREAKING — retired to a ROUTER** (framework v5.2.0). The generator body
+  (Design Thinking, Frontend Aesthetics, MANDATORY pre-work cascade,
+  Performance Gates/CWV, Modern CSS, Form quality, huashu-design pointer) is
+  removed; the design intelligence is superseded by `ui-design` v2.0.0
+  (`references/craft-standards.md` is the new canonical home of Performance
+  Gates + Modern CSS + Form quality). The description keeps its historical
+  broad triggers ON PURPOSE: agents that reflexively route "build/style any
+  web UI" here get deterministically rerouted — `/ui-design` (design work),
+  `/ui-implement` (approved mockup → code), `ui-expert` (direct in-code UI),
+  `/motion-design` (motion). Consumer overlays with aesthetic mandates should
+  port to `.baldart/overlays/ui-design.md`.
+- Codex parity: portable (same SKILL.md bundle, no runtime-specific
+  constructs).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.
+
 ## 1.0.0 — 2026-07-01
 
 - Baseline: versioning per-skill introdotto al framework v4.82.0.