baldart 5.0.1 → 5.2.0

package/CHANGELOG.md

@@ -5,6 +5,163 @@ 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.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
+`senior-researcher` agent is restructured to the v5.0 authoring contract with
+**research profiles**, every report lands in a consumer-owned, indexed
+**research library**, and the **source matrix** that routes each research
+nature to the right sources is versioned and grows project after project.
+Design refined by an adversarial refutation pass (13 findings integrated —
+ID-race BLOCKER, /prd poll determinism, lifecycle circularity, opt-out
+resurrection, auto-commit scoping).
+
+- **NEW protocol module `framework/agents/research-protocol.md`** (`SECTION=`
+  dispatch): `profiles` (`PROFILE=<decision|deep|compare|regulatory>` output
+  contracts; absent → `deep` = legacy semantics; deep's dzhng-style iterative
+  loop + STORM perspectives + CoVe citation spot-check are opt-in via
+  `DEPTH=<1..3>`, default 1 = today's cost), `library` (layout, tag-rich report
+  frontmatter as source of truth, INDEX.md as regenerable view, `RES-<date>-
+  <slug>` ids — no max+1 race, archive-not-delete), `reuse` (pre-flight
+  `FULL_REUSE`/`DELTA`/`NEW` + per-category TTLs + anti-false-reuse guard +
+  the always-write-a-file polling contract), `sources` (matrix schema,
+  SOURCES.md → framework-template resolution — the default matrix lives in ONE
+  file, and the `SOURCE_MATRIX_CANDIDATE` growth loop emitting a ready-to-paste
+  maintainer prompt).
+- **`senior-researcher` v2.0.0** (agents CHANGELOG + heading map): description
+  4-examples → 2 lines; `version:`/`effort:` frontmatter; `model: sonnet` KEPT
+  and the REGISTRY model-tier row corrected (it claimed "always opus",
+  contradicting the frontmatter since day one); NEW Profile Dispatch / Research
+  Library (total delivery-path chain: prompt → library → `paths.docs_dir`) /
+  Source Matrix sections; Operating Protocol cites incl. `SECTION=
+  injection-guard` — the agent reads more untrusted web content than any other
+  and previously had NO injection guard; FIRST MESSAGE TEMPLATE scoped to
+  interactive direct invocation.
+- **NEW skill `/research` (42nd)**: THIN interactive orchestrator — scoping
+  (max 3 questions) → profile+nature routing → library reuse check BEFORE
+  paying for research → `senior-researcher` launch (parallel fan-out on
+  Claude; sequential by-name on Codex per `runtime-portability-protocol.md`)
+  → filing + INDEX ownership → matrix growth loop (apply locally to
+  `SOURCES.md` `## Local additions` and/or print the upstream BALDART prompt).
+  Ships per-profile report templates (`assets/`) + deterministic
+  `scripts/rebuild-research-index.mjs` (INDEX regenerated from frontmatter).
+- **NEW config key `paths.research_dir`** (default `docs/research`, proposed on
+  FIRST encounter only — an explicitly emptied key is a respected opt-out,
+  never re-proposed, never resurrected). Schema-change propagation:
+  template + `configure` (detect probe + prompt + post-write library creation)
+  + `update` (new-key detector already covers `paths.*`; post-pull seed
+  backfill into an EXISTING dir only; auto-commit scoped to UNTRACKED seeds —
+  never sweeps a consumer-edited SOURCES.md/INDEX.md) + `doctor`
+  (`create-research-dir` / `backfill-research-seeds` autoOk actions — seeds are
+  generic, unlike the i18n registry; `research-sources-advisory` when the
+  framework matrix version moves ahead, never overwrites) +
+  `PROJECT-CONFIGURATION.md` (§ 4.2.2 lifecycle + opt-out) + this CHANGELOG.
+  New shared helper `src/utils/research-library.js` (idempotent, silent,
+  returns `created[]`).
+- **Versioned source matrix**: `framework/templates/research-sources.template.md`
+  (`matrix_version: 1.0.0` + sibling `research-sources.CHANGELOG.md`) seeds the
+  consumer-owned `SOURCES.md`; 5-nature default matrix (scientific / dev /
+  regulatory / ux / market × primary / secondary / avoid / notes). Growth loop:
+  agent emits run-evidence-only candidates + the copy-paste BALDART prompt.
+- **`/prd` 1.4.0**: Step 2.5 spawns with `PROFILE=decision`
+  (`PROFILE=regulatory` on signal S2) — resolving the two-conflicting-SSOTs
+  bug where the prompt asked for a light per-topic format while the agent's
+  contract mandated the full §0–§11 report; /prd now PRE-ALLOCATES the output
+  path (library when configured, legacy `prd_dir` fallback otherwise) and the
+  agent always writes a file there (`FULL_REUSE` → pointer stub) so the
+  10-minute exit-check poll stays deterministic. Discovery-phase background
+  launch updated in the same change (parallel location). `hybrid-ml-architect`
+  deliberately NOT touched (vertical, on-request) — protected by the defaults.
+- Inventories: 42 skills / 33 domain modules (README count was already stale
+  at 28); REGISTRY Agent Map + decision tree + model-tier rows updated.
+- OSS recon (inspiration only, zero dependencies adopted): GPT Researcher
+  (planner/executor, local-first hybrid research), dzhng/deep-research
+  (breadth/depth loop), STORM (multi-perspective questioning),
+  open_deep_research (scoping phase), Karpathy markdown-first KB (INDEX as the
+  single map, archive-not-delete).
+- Codex parity: **portable** — skill = same SKILL.md bundle (two symlinks),
+  agent = transpiled `.codex/agents/*.toml` from the same markdown, module +
+  templates = plain markdown; the only Claude-only mechanic (parallel
+  subagent fan-out in `/research`) has an explicit sequential-by-name Codex
+  branch citing `runtime-portability-protocol.md`.
+
 ## [5.0.1] - 2026-07-03
 
 **Adversarial-verification fixes on the 5.0.0 wave.** A full release verification

package/README.md

@@ -83,7 +83,7 @@ No additional activation steps needed — once installed, Claude Code (and Codex
 ### Core Protocol
 
 - **AGENTS.md**: Mandatory coordination rules (MUST/SHOULD/OPTIONAL)
-- **agents/**: 28 domain modules (architecture, workflows, testing, security, card-schema, i18n-protocol, return-contract-protocol, runtime-portability-protocol, component-manifest-schema, etc.)
+- **agents/**: 33 domain modules (architecture, workflows, testing, security, card-schema, i18n-protocol, return-contract-protocol, runtime-portability-protocol, component-manifest-schema, research-protocol, etc.)
 - **Routing**: If you touch X, read Y - minimize context loading
 
 ### AI Agents (32 specialized agents)
@@ -213,7 +213,7 @@ 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 (41 portable skills)
+### Skills (42 portable skills)
 
 Skills live under `.claude/skills/` and are auto-discovered by Claude Code. Every
 skill is **versioned** (`version:` in frontmatter) and ships a per-skill
@@ -222,16 +222,16 @@ 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)
+- **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`
 - **Integration**: `kie-ai`, `remotion-best-practices`
 - **Framework**: `baldart-push` (upstream contribution), `baldart-update` (v3.21.0 — agent-driven framework update), `overlay` (v3.19.0 — guided overlay author)
 
 ### 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.0.1
+5.2.0

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

@@ -7,6 +7,96 @@ 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
+monolith is implicitly `1.x`. Every normative rule survives — inline as a
+1-line binding rule, in the new `agents/research-protocol.md` (SECTION=
+profiles|library|reuse|sources), or in `agent-operating-protocol.md`.
+
+- `version:`/`effort:` frontmatter added; `description` trimmed to 2 lines
+  (the 4 inline examples — ~450 words — were paid by the ORCHESTRATOR's
+  context every session).
+- **`model: sonnet` KEPT** (maintainer decision); the REGISTRY model-tier row
+  is corrected (it claimed "opus — always opus", contradicting the frontmatter
+  since the initial commit) — override to opus stays at the orchestrator's
+  discretion for `PROFILE=deep`.
+- NEW `## Profile Dispatch`: `PROFILE=<decision|deep|compare|regulatory>`
+  spawn token per `research-protocol.md SECTION=profiles`; absent → `deep`
+  (legacy semantics). The deep iterative loop is opt-in via `DEPTH=<1..3>`
+  (default 1 = today's cost) so legacy no-token spawns are unaffected.
+- NEW `## Research Library`: reuse pre-flight (`REUSE: FULL_REUSE|DELTA|NEW`,
+  anti-false-reuse guard), total delivery-path resolution (prompt path →
+  `${paths.research_dir}` → `${paths.docs_dir}`), frontmatter-as-source-of-
+  truth filing.
+- NEW `## Source Matrix`: SOURCES.md resolution + `SOURCE_MATRIX_CANDIDATE`
+  growth-loop block (run-local evidence only).
+- NEW `## Operating Protocol` cites: `SECTION=injection-guard` (this agent
+  reads more untrusted web content than any other — it previously had NO
+  injection guard), `SECTION=tool-budget` (saturation stop), `SECTION=memory`.
+- Return Contract updated: + `REUSE:` line; on an orchestrator-preallocated
+  path a file is ALWAYS written (FULL_REUSE → pointer stub) so file-exists
+  polling never times out.
+- FIRST MESSAGE TEMPLATE scoped to interactive direct invocation only
+  (`BACKGROUND_RUN=true` OR any orchestrator `PROFILE=` token skips it).
+
+**Heading map (old → new) for consumer overlays**:
+
+| Old H2 (pre-5.1) | Now |
+|---|---|
+| `## CRITICAL CONSTRAINT: AI-READABLE + LIMITED CONTEXT` | constraints folded into `## AUDIENCE` + `## OUTPUT — PROFILE=deep` (AI-readable block) |
+| `## OUTPUT (DELIVERABLE)` | `## OUTPUT — PROFILE=deep (§0–§11, VERBATIM contract)` |
+| `## NON-NEGOTIABLE QUALITY BAR` | same name, `(every profile)` suffix; evidence labels + insufficient-evidence rules folded in |
+| `## WORKFLOW (MANDATORY — FOLLOW IN ORDER)` | same name — steps renumbered 1–8 (new step 2 = library pre-flight) |
+| `## SEARCH LOG (REQUIRED IN §11 APPENDIX)` | `## SEARCH LOG (deep profile, §11)` |
+| `## EVIDENCE STRENGTH LABELS` / `## WHAT TO DO WHEN EVIDENCE IS INSUFFICIENT` | folded into `## NON-NEGOTIABLE QUALITY BAR (every profile)` |
+| `## UPDATE AGENT MEMORY` + `# Persistent Agent Memory` boilerplate tail | compressed under `# Persistent Agent Memory` + module `SECTION=memory` |
+
 ## [coder v2.0.1] · [doc-reviewer v2.0.1] · [qa-sentinel v2.0.1] — 2026-07-03 (framework v5.0.1)
 
 Adversarial-verification fixes on the 3-layer restructuring (no H2 moved — overlays unaffected):

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 |
@@ -40,7 +40,7 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 | **prd-card-writer** | Product | Generate atomic backlog cards from approved PRD; `MODE: apply-findings` = fresh-context applier of audit findings to card YAML (spawned by /prd Step 6.9, sonnet override) | Card YAML, traceability, parallel groups | Yes | Backlog writing, dependency analysis |
 | **onboarding-architect-lead** | Product | Design/improve user onboarding experiences | Activation flows, experiments | No | Onboarding research, metrics |
 | **website-orchestrator** | Product | Coordinate multi-agent website development | Project orchestration | No | Phase management, quality gates |
-| **senior-researcher** | Research | Comprehensive research on technical topics | Evidence-based analysis | Yes | Web search, citations |
+| **senior-researcher** | Research | Evidence-based research reports; pass `PROFILE=<decision\|deep\|compare\|regulatory>` (agents/research-protocol.md); reports land in the research library (paths.research_dir) with a reuse pre-flight | Evidence-based analysis, research library | Yes | Web search, citations, library reuse |
 | **marketing-conversion-strategist** | Marketing | Create high-converting copy and messaging | Positioning, CTAs, copy | No | Business interview, copywriting |
 | **seo-analytics-strategist** | Marketing | Define SEO strategy, metadata, analytics | GA4/GTM, schema markup | No | Keyword research, event planning |
 | **api-perf-cost-auditor** | DevOps | Analyze APIs for performance/cost bottlenecks | Backend optimization, scaling | No | Bottleneck detection, cost analysis |
@@ -127,7 +127,7 @@ Visual assets needed?                  --> visual-designer
 Animation specs?                       --> motion-expert
 ML/ranking/recommendation?             --> hybrid-ml-architect
 Gamification/retention?                --> hyper-gamification-designer
-Research a technical topic?            --> senior-researcher
+Research a technical topic?            --> senior-researcher (pass PROFILE=; interactive channel: /research skill)
 Marketing copy/positioning?            --> marketing-conversion-strategist
 SEO/analytics planning?                --> seo-analytics-strategist
 API performance audit?                 --> api-perf-cost-auditor
@@ -208,7 +208,7 @@ Use this table when spawning agents via the `Task` tool. The `model` field in ea
 | **prd-card-writer** | opus | — (always opus, effort: high) | Card precision requires deep reasoning for 20+ fields, traceability, parallel groups |
 | **ui-expert** | opus | — (always opus) | Design quality requires highest capability |
 | **hybrid-ml-architect** | opus | — (always opus) | ML architecture is complex by nature |
-| **senior-researcher** | opus | — (always opus) | Research depth requires strongest model |
+| **senior-researcher** | sonnet | opus at orchestrator's discretion for `PROFILE=deep` surveys | Web-native retrieval + synthesis — sonnet is sufficient and fast; depth comes from the profile loop (`DEPTH=`), not the model |
 
 **Rules**: Never use haiku for any **named specialist agent** in the matrix above. Opus for code writing and creative/complex work. Sonnet for analysis, review, and documentation. `qa-sentinel` stays on sonnet even though it is a mechanical gate runner — its failure interpretation and SCOPED-vs-FULL tiering benefit from sonnet.
 

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):