baldart 3.15.0 → 3.17.0

package/CHANGELOG.md

@@ -5,6 +5,60 @@ 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.17.0] - 2026-05-23
+
+The `/prd` skill gains a third option in the design phase. Until v3.16.0, when a user reached Step 3 without having provided mockups (`mockups.status: none`), the only path forward was internal generation via the `ui-design` skill (3 HTML options → iteration → save). With Claude Design now offering a design-system-sync'd visual generator, users who prefer iterating in that surface had to abandon the PRD flow halfway, work externally, and then re-enter as if they'd had mockups from the start. This release adds **Step 3.0 — Mockup Source Decision**: when `mockups.status: none` AND UI impact ≠ N/A, the skill explicitly asks "internal generation or handoff to Claude Design?". The handoff branch generates a context-rich prompt (discovery + brand voice + design-system tokens + screens in scope + stack target) ready to paste, then STOPs. On user re-entry with local paths, it re-uses the existing Step 1.6 Mockup Intake verbatim — copy → analyze → populate state — and Step 3 falls naturally into Hybrid mode. Zero code paths downstream of the bivio are new; the entire feature is a decision point + a prompt generator on top of pre-existing infrastructure.
+
+### Added — PRD Step 3.0 Mockup Source Decision
+
+- **§ Step 3.0 in [framework/.claude/skills/prd/references/ui-design-phase.md](framework/.claude/skills/prd/references/ui-design-phase.md)** before the precondition decision tree. Activates only when `mockups.status: none` AND UI impact ≠ N/A. Poses the binary question (Internal `ui-design` vs Handoff Claude Design) with explicit STOP gate — silence or ambiguity re-asks rather than defaulting silently. Branch A sets `mockups.source: internal` and falls through unchanged. Branch B collects context from state file + `baldart.config.yml` + `.baldart/overlays/prd.md` + `${paths.design_system}/INDEX.md` + `tokens-reference.md` (when `features.has_design_system: true`), renders the handoff prompt template, presents it inside a fenced code-block with copy-paste instructions, persists `mockups.status: pending_external` + `mockups.source: claude-design` + `mockups.handoff_prompt_path` in the state file (prompt saved to `${paths.prd_dir}/<slug>/handoff/claude-design-prompt.md` for session-restart survival), and STOPs.
+- **Re-entry handler in same file**. When the user returns with local paths after handoff, the skill invokes the existing Step 1.6 Mockup Intake procedure verbatim (no code duplication) — copy into `mockups/` with collision-safe rename, run Mockup analysis schema, populate `## UI Design`. Then flips `mockups.status` from `pending_external` to `provided` or `partial` based on coverage of `screens_in_scope[]`, keeps `mockups.source: claude-design` as audit trail, and falls through to the precondition decision tree which routes to Hybrid mode unchanged.
+- **Precondition decision tree extended** with two new rows: `mockups.status: pending_external` ⇒ STOP (handoff in flight); `mockups.status: none` AND user picked Branch A ⇒ Full (preserves backwards-compatible default). The existing `provided` / `partial` ⇒ Hybrid and UI = N/A ⇒ Skip rows are unchanged.
+- **New template asset [framework/.claude/skills/prd/assets/claude-design-handoff-prompt.template.md](framework/.claude/skills/prd/assets/claude-design-handoff-prompt.template.md)**. Seven-section structure populated at runtime: (1) feature objective, (2) user flow + personas, (3) screens in scope with required states + primary actions + data shown, (4) brand & voice (conditional on overlay), (5) design system constraints with tokens excerpt + registered primitives + numeric tables from `framework/agents/design-system-protocol.md` (conditional on `features.has_design_system: true`), (6) stack target + output format preference derived from `stack.framework`, (7) deliverable spec (PNG exports per state + code/Figma + inline notes on new components / token deviations / layout decisions). Generic and project-agnostic — all project-specific content is injected as placeholders.
+- **Hard Rule 16 note in [framework/.claude/skills/prd/SKILL.md](framework/.claude/skills/prd/SKILL.md)** added to the existing Mockup Intake rule. Codifies that a NO answer at intake routes through Step 3.0 (not directly to Full mode), with cross-reference to the ui-design-phase section. The rule itself remains unchanged for backwards compatibility — Step 3.0 is purely additive.
+
+### Notes
+
+- **No new `baldart.config.yml` keys** — the schema-change propagation rule does not apply to this release. The bivio is runtime-only per the user's preference (zero persistent flag); no template/configure/update/doctor updates needed. All context for the handoff prompt is read from existing config keys (`paths.*`, `stack.*`, `features.has_design_system`).
+- **Backwards compatibility.** PRDs in flight on v3.16.x finish on v3.16.x semantics. New PRD sessions started on v3.17.0+ see Step 3.0 only when they actually reach Step 3 with `mockups.status: none` — the default (Branch A) preserves the v3.16.x behavior exactly. Existing PRDs that already provided mockups never enter Step 3.0.
+- **`ui-design` skill is unchanged** — Step 3.0 sits in front of it, doesn't modify it. The Full pipeline (3a → 3d) is reached identically when the user picks Branch A or when no mockup-related state exists at all. The `ui-expert` agent and `huashu-design`/`frontend-design` skills are equally untouched.
+- **`mockup_analysis` schema is unchanged** — the new `pending_external` value of `mockups.status` is purely transitional and is overwritten by `provided` / `partial` on user re-entry, so existing PRD templates and state files keep validating without migration.
+- **Files modified outside the Step 3.0 scope** (`card-template.yml`, `backlog-phase.md`, `validation-phase.md`, `prd-card-writer.md`, `framework/.claude/skills/new/SKILL.md`) are the v3.16.0 in-flight release (agent routing + UI specialist briefing — see entry below) and are NOT part of v3.17.0. v3.16.0 should be tagged and pushed before v3.17.0 in the release sequence.
+- **Verification is manual** (no test suite). Dogfood scenarios: (1) `/prd` with mockups provided at intake → never enters Step 3.0, Hybrid mode as today (regression check); (2) `/prd` without mockups, answer "A" at Step 3.0 → Full mode runs identically to v3.16.x; (3) `/prd` without mockups, answer "B" → prompt rendered with discovery + tokens + screens + stack, saved to `handoff/`, state shows `pending_external`, skill STOPs; (4) simulate re-entry with a PNG path → file copied to `mockups/`, status flips to `provided`, Step 3 enters Hybrid mode invoking `ui-design` only for uncovered screens; (5) `features.has_design_system: false` → § 5 of the rendered prompt is omitted entirely; (6) no overlay present → § 4 brand voice omitted.
+
+## [3.16.0] - 2026-05-23
+
+The `/new` orchestrator becomes specialist-aware: it now reads `owner_agent` from each card YAML and dispatches the right implementation agent — `coder` for backend/logic, `ui-expert` for UI cards, with `plan`/`visual-designer`/`motion-expert` reserved as stubs that fall back to `coder` with a WARN. UI cards (`owner_agent: ui-expert`) receive a dedicated mission briefing that enforces the registry-first BLOCKING cascade (read `${paths.design_system}/INDEX.md` + `tokens-reference.md` + per-component specs BEFORE coding), the implementation-only constraint (no mockup redesign — STOP and ask on registry conflicts), and the Post-Intervention Coherence Check (reconcile INDEX + components + tokens in the same commit). The PRD side enforces the contract end-to-end: `owner_agent` is now a mandatory enum on every child card, UI cards have UI-only scope (logic moves to a sibling `coder` card), and the validation phase blocks commit on enum violations + warns on mixed-scope UI cards.
+
+Until now, every card from `/new` was spawned to the generic `coder` agent regardless of `owner_agent`, and mockups arrived as a textual "match this reference" hint without triggering the registry/tokens/specs cascade that `ui-expert` mandates. The symptom reported by users: graphical code generated from mockups was "not quite right" — wrong shadows, off-scale font sizes, off-palette colors. Root cause: the right specialist existed and PRD cards declared it (`owner_agent: ui-expert`), but the dispatcher never read the field.
+
+### Added — Agent router + UI specialist briefing
+
+- **§ Agent Routing section in [framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)** between Pre-flight and Per-card pipeline. Documents the `owner_agent` → spawn-target mapping in a single table (coder | ui-expert | plan | visual-designer | motion-expert → resolved agent + briefing variant) with a cross-reference list of the 5 layers that must stay in lockstep (template, prd.md enum, prd-card-writer rule, validation-phase check, REGISTRY.md decision tree).
+- **Step 6b "Agent dispatch (router)" in Phase 2** of [framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md). Reads `card.owner_agent`, resolves the spawn target via a switch with explicit fallbacks: `coder` → coder briefing; `ui-expert` → ui-expert briefing; `plan`/`visual-designer`/`motion-expert` → coder briefing + WARN ("specialized briefing not yet implemented"); empty/`claude`/missing → coder briefing + WARN; unknown value → HALT and ask the user. The resolved spawn + briefing pair is logged in the tracker as the audit trail.
+- **`[UI-ONLY]` mission briefing sections** in Phase 2 step 7 of [framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md). Three new sections inserted between "Design Reference" and "File Permissions", included ONLY when the router resolves `briefing = "ui-expert"`:
+  - **Registry-first BLOCKING pre-work** — reproduces verbatim the cascade defined in [framework/.claude/agents/ui-expert.md](framework/.claude/agents/ui-expert.md) § "Registry-first pre-work (BLOCKING)": read `INDEX.md` + `tokens-reference.md` + `components/<Name>.md` for every primitive in scope, declare which Authority Matrix rows govern the card in the first response. Orchestrator rejects the implementation if the declaration is missing.
+  - **Implementation-only constraint** — explicit DO NOTs: don't redesign the mockup, don't silently adapt registry-conflicting details (STOP + `[DS-DRIFT] mockup-vs-registry` log + ask the user), don't extend scope into business logic / API / state / validation (split-into-sibling-card is upstream PRD concern).
+  - **Post-Intervention Coherence Check** — citation of [framework/agents/design-system-protocol.md](framework/agents/design-system-protocol.md) § "Post-Intervention Coherence Check": reconcile `INDEX.md` (drift code `DS_INDEX_DRIFT`) + `components/<Name>.md` (`DS_COMPONENT_STALE`) + `tokens-reference.md` (`DS_TOKENS_DRIFT`) in the same commit. The completion report MUST include a `design_system_coherence:` block enumerating the artifacts updated.
+- **`[UI-ONLY]` design-system conformance step in Phase 2.5** of [framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md). New row in the Completeness Check verification depth, runs only when `briefing = "ui-expert"` AND `features.has_design_system: true`. Greps changed files for hardcoded design values that bypass the registry (hex colors, `rgb(`, inline `box-shadow:` offsets, raw px/rem `border-radius:`/`font-size:`/spacing); verifies the `design_system_coherence:` block in the completion report; verifies new primitives ship their `components/<Name>.md` spec in the same commit; verifies new tokens land in `tokens-reference.md`. Each gap classified Partial → fix-coder sub-loop.
+
+### Added — PRD-side enforcement (split-scope + mandatory enum)
+
+- **§ MANDATORY Card Rules (Rule A + Rule B)** in [framework/.claude/skills/prd/references/backlog-phase.md](framework/.claude/skills/prd/references/backlog-phase.md). New section between MANDATORY Card Structure and Specialist Audits. **Rule A**: every child card MUST declare `owner_agent` with one of the five enum values; missing/empty/placeholder/non-enum BLOCKS commit. **Rule B**: cards with `owner_agent: ui-expert` MUST be UI-only — components, layout, styling, motion, accessibility — and MUST NOT bundle business logic, API integration, state management, validation logic, or backend changes; mixed steps split into a `ui-expert` card (visual, consumes mocked contract) + a `coder` card (logic, API, state) wired via `depends_on:`/`blocks:`. Ships a canonical Login feature split example (bad: single mixed card; good: `FEAT-XXXX-02` UI + `FEAT-XXXX-01` logic).
+- **§ Agent Specialization Rules in [framework/.claude/agents/prd-card-writer.md](framework/.claude/agents/prd-card-writer.md)** before Card Atomicity Rules. The same Rule A + Rule B formulated from the agent writer's POV (which value to pick per work type, what NOT to bundle, when not to assign `ui-expert` to a tight-knit mixed card). Cross-references the backlog-phase split example for canonical guidance.
+- **§ Step 6 Agent Specialization Audit (new step 0)** in [framework/.claude/skills/prd/references/validation-phase.md](framework/.claude/skills/prd/references/validation-phase.md). Runs FIRST, before the Field Name Audit. Step 0a: `owner_agent` enum check (BLOCKING) — halts the audit on missing/empty/placeholder/non-enum with an actionable message. Step 0b: UI-only scope heuristic (WARN, soft gate) — for each `ui-expert` card, greps `scope.summary` + `requirements` + `acceptance_criteria` for logic markers (`api call`, `endpoint`, `route handler`, `state machine`, `validation logic`, `business rule`, `database`, `migration`, `prisma`, `auth flow`, `token storage`, `webhook`, `cron`) and emits `[UI-SCOPE-WARN]` lines for human review. Intentionally soft: legitimate UI references to mocked contracts ("consumes `useAuth()` mock") don't trip the WARN thanks to the consume/mock/contract-reference exception.
+- **§ Card-template fields updated** in [framework/.claude/skills/prd/assets/card-template.yml](framework/.claude/skills/prd/assets/card-template.yml). The placeholder `owner_agent: claude` is replaced with `owner_agent: <REQUIRED — coder | ui-expert | plan | visual-designer | motion-expert>` so a card left at the placeholder fails validation. A leading comment block documents each enum value (one line each) and a comment under `scope:` reminds the writer of the UI-only constraint for `ui-expert` cards.
+- **§ Epic-template aligned to the tracker-only contract** in [framework/.claude/skills/prd/assets/epic-template.yml](framework/.claude/skills/prd/assets/epic-template.yml). `owner_agent` changes from the legacy `claude` placeholder to `""` (empty string) with an inline comment clarifying that epics are tracker-only — the dispatcher skips them and the validation-phase enum-check exempts them — so the empty value is the correct signal that no specialist is assigned to an epic. Prevents the false-positive of writing a child enum value (e.g. `coder`) on an epic and implying it carries implementation work.
+
+### Notes
+
+- **No new `baldart.config.yml` keys** — the schema-change propagation rule does not apply to this release. The router consumes an existing field (`owner_agent`) already present in the PRD card schema.
+- **Backwards compatibility for cards written before v3.16.0.** The dispatcher accepts `owner_agent: ""` / missing / legacy `claude` value via the WARN-and-fallback-to-coder branch, so existing backlogs keep working — the WARN surfaces the gap on first use without blocking. New PRD sessions on v3.16.0+ produce enum-compliant cards from the start; the validation phase's enum BLOCKER applies only to NEW cards generated under v3.16.0+.
+- **Specialist briefings for `plan` / `visual-designer` / `motion-expert` are stubs** in this release — they fall back to the coder briefing with a WARN. Specialized briefings will follow in future iterations without further schema changes (the router structure is already in place).
+- **`ui-expert` in `/new` is implementation-only by design** — refinement of the mockup remains a PRD-phase responsibility (the `ui-design-phase` skill handles design decisions). If the implementation step finds a mockup-vs-registry conflict, `ui-expert` STOPs and asks the user; it does not auto-adapt the mockup. This boundary is documented in the `[UI-ONLY] Implementation-only constraint` briefing section.
+- **REGISTRY.md decision tree** in [framework/.claude/agents/REGISTRY.md](framework/.claude/agents/REGISTRY.md) gains a header note clarifying that `/new` dispatches by `owner_agent` (not by re-running the decision tree) — the tree remains authoritative for ad-hoc spawns and for `prd-card-writer`'s writing decisions, with a lockstep-with-skill warning to keep the 5 layers in sync.
+- **Verification is manual** (no test suite — `npm test` remains a no-op stub). Dogfood scenarios to run after install: (1) `/new <CARD-ID>` on a card with `owner_agent: coder` → identical behavior to v3.15.x (no regression); (2) `/new <CARD-ID>` on a card with `owner_agent: ui-expert` + valorized `links.design` → `ui-expert` is spawned (not coder), the briefing contains the BLOCKING cascade verbatim, the implementation reads `INDEX.md` + `tokens-reference.md` + `components/<Name>.md` BEFORE coding, the completion report ships the `design_system_coherence:` block, the commit reconciles the three design-system sources; (3) `/new` on a legacy card with `owner_agent: claude` or missing field → fallback to coder + WARN line in tracker; (4) `/prd` on a feature involving login (UI + logic) → produces TWO cards (`UI-LOGIN-*` ui-expert + `LOGIC-LOGIN-*` coder) wired via `depends_on:` rather than one mixed coder card; (5) PRD validation phase on a card with `owner_agent: ""` → enum BLOCKER, commit refused.
+
 ## [3.15.0] - 2026-05-23
 
 Two changes ship together. **(1) PRD becomes mockup-aware** — formal intake of existing mockups between Kickoff and Discovery, with a per-screen decision tree in Step 3 that skips generation for screens already covered. **(2) Framework becomes stack-aware** — four new `stack.*` cardinal scalars (`database`, `auth_provider`, `framework`, `deployment`) drive vocabulary, gate sections, anti-pattern checklists, and deploy commands across `/prd`, `coder`, `api-perf-cost-auditor`, `/new`, `code-reviewer`, `security-reviewer`, `bug`. Project-identity assumptions previously hard-coded (mayo personas, real test credentials, Italian merchant business names) are removed from the framework and now resolved from `identity.audience_segments[]` + `.baldart/overlays/prd.md`. Sanitization sweep removed all PII (phone numbers, real usernames, real passwords, real store names) from the published payload.

package/VERSION

@@ -1 +1 @@
-3.15.0
+3.17.0

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

@@ -37,6 +37,16 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 
 ## Decision Tree
 
+> **Note**: when invoked from the `/new` skill, agent assignment is NOT taken
+> from this tree — `/new` reads `owner_agent` directly from each card YAML
+> (enum: `coder | ui-expert | plan | visual-designer | motion-expert`, set
+> by `prd-card-writer`). This tree is the source for HUMAN routing (when
+> spawning an agent ad-hoc) and for prd-card-writer's WRITING decisions.
+> If you change agent capabilities here, keep the enum in
+> `framework/.claude/agents/prd.md:538` and the router in
+> `framework/.claude/skills/new/SKILL.md` § Agent Routing in lockstep —
+> drift between layers silently mis-routes cards.
+
 ```
 Need to understand existing code?      --> codebase-architect (MANDATORY)
 Have a plan to review?                 --> plan-auditor

package/framework/.claude/agents/prd-card-writer.md

@@ -56,6 +56,69 @@ You produce:
 4. **Scan existing backlog** — `backlog/*.yml` to find the highest `FEAT-XXXX` number. Use Glob to list files, then Grep for `^id:` lines to extract IDs.
 5. **Read existing card conventions** — sample 2-3 recent cards from `backlog/` to match style.
 
+## Agent Specialization Rules (HARD RULE — zero tolerance)
+
+These two rules govern HOW you assign work to specialist agents. They are
+enforced by the validation phase of `/prd` (Step 6) and by the `/new`
+dispatcher — getting them wrong silently routes work to the wrong agent.
+
+### Rule A — Set `owner_agent` on every child card (enum, no default)
+
+Every child card you produce MUST set `owner_agent` to exactly one of:
+
+```
+coder | ui-expert | plan | visual-designer | motion-expert
+```
+
+`claude` is NOT a valid value (it is a legacy placeholder kept only for
+backward compatibility in the dispatcher's fallback). Missing, empty, or
+out-of-enum values fail validation.
+
+**How to choose:**
+
+- `coder` — backend, business logic, state management, data layer, API
+  handlers, scripts, CLI, hooks, anything that writes/reads persistence.
+- `ui-expert` — UI implementation from an existing mockup (`links.design`):
+  components, layout, styling, motion, accessibility, registry-first
+  discipline (reads `${paths.design_system}/INDEX.md` + tokens-reference
+  + per-component specs BEFORE coding, runs Post-Intervention Coherence
+  Check after).
+- `plan` — planning-only deliverables (no code edits): RFC, ADR draft,
+  research synopsis, sequencing doc.
+- `visual-designer` — static visual asset generation (illustrations, icons,
+  hero images) via the visual-designer agent.
+- `motion-expert` — motion specs (timing tables, easing curves,
+  micro-interaction storyboards) — NOT motion code implementation, which
+  is `ui-expert` work.
+
+**Epic cards** use `owner_agent: ""` (empty string) because they are
+trackers, not implementation. The dispatcher skips them.
+
+### Rule B — UI cards (`ui-expert`) have UI-ONLY scope
+
+When you assign `owner_agent: ui-expert` to a card, its scope MUST cover
+ONLY graphical concerns. The card MUST NOT bundle:
+
+- business logic, domain rules, calculation
+- API calls, data fetching, mutations
+- state management beyond local UI state (`useState` for open/closed,
+  hover, focus — fine; global app state, cache invalidation, sync — not)
+- validation LOGIC (rendering validation states is UI work; the rules and
+  side-effects are coder work)
+- backend changes (routes, handlers, DB schema, migrations, indexes)
+
+**If a step requires both UI and logic, you MUST split it into two cards**
+and wire them via `depends_on:` / `blocks:` — a `ui-expert` card that
+consumes a mocked or contract-stable interface, plus a `coder` card that
+owns the logic side. Canonical example: see § "Split example — Login
+feature" in `framework/.claude/skills/prd/references/backlog-phase.md`.
+
+If you cannot reasonably split (e.g. because the UI and logic share <3
+files and one file would be torn between two cards), prefer a single
+`coder` card with UI work as one of its acceptance criteria — do NOT
+assign `ui-expert` to a mixed card. The dispatcher's specialist routing
+breaks down when scope is mixed.
+
 ## Card Atomicity Rules
 
 Cards MUST be as atomic as possible to enable parallel execution:

package/framework/.claude/skills/new/SKILL.md

@@ -225,6 +225,38 @@ Before Phase 3.5, determine the QA profile for each card by reading its YAML met
 
 ---
 
+## Agent Routing (Phase 2 dispatcher)
+
+Phase 2 reads the card's `owner_agent` field and dispatches to the matching
+specialist. The enum is defined by the PRD card writer
+(`framework/.claude/agents/prd.md:538` + `prd-card-writer.md § Agent
+Specialization Rules`) and validated by the PRD validation phase
+(`framework/.claude/skills/prd/references/validation-phase.md` Step 6 → 0).
+
+| `owner_agent` | Dispatcher action in Phase 2 step 7 | Briefing variant |
+|---|---|---|
+| `coder` | Spawn `coder` | Standard coder briefing (default body below) |
+| `ui-expert` | Spawn `ui-expert` | UI briefing — adds BLOCKING registry-first cascade + Post-Intervention Coherence Check (see step 7 § UI branch) |
+| `plan` | Fallback to `coder` + WARN | Standard coder briefing + log `"[ROUTER] plan-only briefing not yet implemented — using coder"` |
+| `visual-designer` | Fallback to `coder` + WARN | Standard coder briefing + same WARN format |
+| `motion-expert` | Fallback to `coder` + WARN | Standard coder briefing + same WARN format |
+| missing / `claude` / unknown | Fallback to `coder` + WARN | Standard coder briefing; for unknown value also log the literal value |
+
+The three `plan` / `visual-designer` / `motion-expert` stubs exist so the
+router never blocks a card; specialized briefings are tracked as a follow-up.
+
+If you change which values are valid here, also update:
+
+- `framework/.claude/agents/prd.md:538` (the canonical enum comment),
+- `framework/.claude/skills/prd/assets/card-template.yml` (the placeholder),
+- `framework/.claude/agents/prd-card-writer.md § Agent Specialization Rules`,
+- `framework/.claude/skills/prd/references/validation-phase.md` Step 6 → 0a,
+- `framework/.claude/agents/REGISTRY.md` decision-tree.
+
+Keep them in lockstep — drift between any two layers silently mis-routes cards.
+
+---
+
 ## Per-card pipeline
 
 For each card, execute these phases in order:
@@ -262,7 +294,28 @@ For each card, execute these phases in order:
 
 ### Phase 2 — Implement (self-healing, up to 3 retries)
 6. **Update tracker**: phase = "2-implement".
-7. Spawn the **coder** agent (or appropriate specialist from `.claude/agents/REGISTRY.md`) using this **standardized mission briefing** — fill in each section from the card YAML, tracker, and codebase-architect findings:
+6b. **Agent dispatch (router)** — read `owner_agent` from the card YAML and resolve the spawn target per the table in § Agent Routing above:
+
+   ```
+   Let raw = card.owner_agent (string, may be missing).
+   Switch on raw:
+     - "coder"           → spawn = "coder",       briefing = "coder"
+     - "ui-expert"       → spawn = "ui-expert",   briefing = "ui-expert"
+     - "plan"            → spawn = "coder",       briefing = "coder"
+                           + log: "[ROUTER] plan-only briefing not yet implemented — using coder"
+     - "visual-designer" → spawn = "coder",       briefing = "coder"
+                           + log: "[ROUTER] visual-designer briefing not yet implemented — using coder"
+     - "motion-expert"   → spawn = "coder",       briefing = "coder"
+                           + log: "[ROUTER] motion-expert briefing not yet implemented — using coder"
+     - "" | missing | "claude"
+                         → spawn = "coder",       briefing = "coder"
+                           + log: "[ROUTER] card <ID> has no valid owner_agent (got '<raw>'); defaulting to coder"
+     - anything else     → HALT. Log: "[ROUTER] card <ID> has unknown owner_agent '<raw>' — not in {coder, ui-expert, plan, visual-designer, motion-expert}. Ask the user how to proceed."
+   ```
+
+   Log the resolved `spawn` and `briefing` in the tracker (1 line: `"router: owner_agent=<raw> → spawn=<agent>, briefing=<variant>"`). This is the audit trail for which specialist actually handled the card.
+
+7. Spawn the **resolved agent** (from step 6b) using this **standardized mission briefing** — fill in each section from the card YAML, tracker, and codebase-architect findings. When `briefing = "ui-expert"`, ALSO include the additional UI sections marked **[UI-ONLY]** below:
 
    ```
    ## MISSION BRIEFING — <CARD-ID>
@@ -294,6 +347,70 @@ For each card, execute these phases in order:
    Read the design.html file and use it as the visual reference for your implementation.
    The design was approved by the user — your implementation MUST match it.
 
+   ### [UI-ONLY] Registry-first BLOCKING pre-work (include ONLY when briefing = "ui-expert")
+   You are spawned as `ui-expert`. Before writing any UI code, you MUST complete
+   the registry-first cascade defined in
+   `framework/.claude/agents/ui-expert.md` § "Authoritative Style Reference —
+   Registry-First Protocol" (the SSOT lives in
+   `framework/agents/design-system-protocol.md`). Reproduce its 5 steps
+   verbatim, do NOT paraphrase or skip:
+
+   1. Read `${paths.design_system}/INDEX.md` (component index + Canonical
+      Authority Matrix).
+   2. Read `${paths.ui_guidelines}` (visual language, typography,
+      accessibility, brand voice).
+   3. Read `${paths.design_system}/tokens-reference.md` (token contract —
+      SSOT for every color / spacing / shadow / radius / motion value).
+   4. For EACH primitive in scope on this card, read
+      `${paths.design_system}/components/<Name>.md`. "In scope" = any
+      component named in the mockup, the requirements, or `files_likely_touched`.
+   5. For EACH pattern in scope, read the relevant
+      `${paths.design_system}/patterns/<topic>.md`.
+
+   State, in your first response, which Authority Matrix rows govern this
+   card, which component specs you read (step 4), and which patterns you
+   read (step 5). Skipping this declaration = the orchestrator will reject
+   the implementation and re-spawn.
+
+   The `features.has_design_system: true` flag in `baldart.config.yml` is
+   the precondition for the full cascade. When `features.has_design_system:
+   false`, only step 2 applies — log the gap, recommend `/design-system-init`
+   if drift is visible, and proceed with coder-level diligence (no cascade
+   enforced).
+
+   ### [UI-ONLY] Implementation-only constraint (include ONLY when briefing = "ui-expert")
+   This `/new` invocation gives you the role of IMPLEMENTER, not designer:
+
+   - DO NOT redesign the mockup. The mockup at `links.design` is the
+     user-approved visual contract for this card.
+   - DO NOT silently adapt a mockup detail that conflicts with the registry
+     (e.g. a custom shadow not in `tokens-reference.md`, a font size off the
+     type scale, a color outside the palette). If you find such a conflict:
+     STOP, log it in the tracker as `[DS-DRIFT] mockup-vs-registry`, and ask
+     the user which side to honor.
+   - DO NOT extend scope into business logic, API calls, state management, or
+     validation rules. Those belong to a sibling `coder` card (see
+     `backlog-phase.md § Rule B`). If a requirement appears to need logic,
+     STOP and ask — do not implement it.
+
+   ### [UI-ONLY] Post-Intervention Coherence Check (include ONLY when briefing = "ui-expert")
+   Before declaring the card done, you MUST reconcile the three design-system
+   sources in the SAME commit as your UI change, per
+   `framework/agents/design-system-protocol.md § Post-Intervention Coherence Check`:
+
+   - `${paths.design_system}/INDEX.md` — add / update entries for any primitive
+     introduced or modified. Drift code: `DS_INDEX_DRIFT`.
+   - `${paths.design_system}/components/<Name>.md` — ship the per-component
+     spec for any new primitive; update the spec when a primitive's API or
+     visual changes. Drift code: `DS_COMPONENT_STALE`.
+   - `${paths.design_system}/tokens-reference.md` — add / update token entries
+     when introducing new semantic tokens. Drift code: `DS_TOKENS_DRIFT`.
+
+   The four conditions defined in `design-system-protocol.md` are the SSOT —
+   reproduce them in your completion report under a `design_system_coherence:`
+   block listing which conditions applied and which artifacts you updated.
+   Omitting the block = the orchestrator treats the card as not done.
+
    ### File Permissions (ENFORCED — no exceptions)
    MAY EDIT — your files for this card:
    [list from ownership map for this card]
@@ -545,6 +662,27 @@ Before triggering any review, you MUST verify that the coder agent implemented *
    If the completion report has `items_skipped` that is not "none", immediately flag those
    items as Missing regardless of the agent's justification.
 
+   - **[UI-ONLY] Design-system conformance** → run ONLY when `briefing = "ui-expert"` from step 6b
+     AND `features.has_design_system: true` in `baldart.config.yml`:
+     - Grep the changed files for hardcoded design values that bypass the registry:
+       hex colors (`#[0-9a-fA-F]{3,8}`), `rgb(`/`rgba(`, `box-shadow:` with inline
+       offsets/blurs, `border-radius:` with px/rem literals, `font-size:` with raw
+       px/rem (outside the type scale), `padding`/`margin` with raw px (outside the
+       spacing scale). Each hit on a NEW or MODIFIED line = Partial — the value
+       should come from a token, not a literal.
+     - Verify the completion report includes the `design_system_coherence:` block
+       required by the UI-ONLY briefing. Missing block = Missing (orchestrator
+       cannot confirm Post-Intervention Coherence Check ran).
+     - For each new primitive declared by the report (or detected via Grep for new
+       components in `${paths.components_primitives}`), verify the matching
+       `${paths.design_system}/components/<Name>.md` spec was created in the same
+       commit. Missing spec = Partial — fix by re-spawning `ui-expert` with the
+       narrow instruction "ship the component spec for <Name> per
+       design-system-protocol.md".
+     - For each token change declared by the report, verify the entry exists in
+       `${paths.design_system}/tokens-reference.md`. Missing entry = Partial.
+     - If `features.has_design_system: false`, log "DS conformance skipped — flag is false" and continue.
+
 5. Classify each item:
    - **Done** — code exists AND satisfies the FULL scope of the requirement (not just partial).
    - **Partial** — some code exists but the criterion is not fully satisfied (e.g., UI renders but no error state, endpoint exists but wrong response shape).

package/framework/.claude/skills/prd/SKILL.md

@@ -101,6 +101,13 @@ message. You ask questions, wait for answers, and iterate.
     (`mockup_analysis.screens[].gaps[]`) DEVONO diventare domande mirate in Discovery o
     essere esplicitamente waivate.
 
+    **Nota — handoff esterno post-intake.** Se l'utente risponde NO al mockup intake, lo
+    Step 3.0 in UI Design gli chiederà se vuole generare i mockup internamente (workflow
+    `ui-design`) o fare handoff a **Claude Design**. Nel ramo handoff la skill genera un
+    prompt context-rich pronto da incollare, fa STOP, e al rientro con i path locali
+    riusa esattamente questa stessa procedura di Step 1.6 → Step 3 entra in Hybrid mode.
+    Vedi [ui-design-phase.md](references/ui-design-phase.md) § "Step 3.0 — Mockup Source Decision".
+
 ---
 
 ## TEMPLATES

package/framework/.claude/skills/prd/assets/card-template.yml

@@ -6,7 +6,16 @@ id: {{FEAT-ID}}
 title: "{{Full descriptive title}}"
 status: TODO
 priority: {{HIGH|MEDIUM|LOW}}
-owner_agent: claude
+
+# owner_agent — REQUIRED, no implicit default. One of:
+#   coder            → backend / logic / state / data layer / scripts
+#   ui-expert        → UI implementation (mockup → code, registry-first); UI-ONLY scope
+#   plan             → planning-only card (no code edits)
+#   visual-designer  → static visual assets (illustrations, icons, hero images)
+#   motion-expert    → animation specs (timing, easing, micro-interactions)
+# The /new orchestrator dispatches by this field (see new/SKILL.md § Agent Routing).
+# Validation phase BLOCKS commit if value is missing or outside this enum.
+owner_agent: <REQUIRED — coder | ui-expert | plan | visual-designer | motion-expert>
 execution_mode: local
 
 group:
@@ -29,6 +38,12 @@ business_rationale: |
   Aiuta gli agenti implementatori a comprendere l'intento strategico.}}
 
 scope:
+  # UI-only constraint (when owner_agent: ui-expert):
+  # The scope MUST cover ONLY graphical concerns — components, layout, styling,
+  # token usage, motion, accessibility. It MUST NOT bundle business logic, API
+  # integration, data fetching, state management, form validation, or backend
+  # changes. If the step involves both UI and logic, split into two cards
+  # (ui-expert + coder) and wire them via `depends_on:` / `blocks:`.
   summary: |
     {{What this card delivers in 2-3 lines.}}
   # Drawn from identity.audience_segments[] in baldart.config.yml.

package/framework/.claude/skills/prd/assets/claude-design-handoff-prompt.template.md

@@ -0,0 +1,116 @@
+# Claude Design Handoff Prompt — Template
+
+> Template populated at runtime by **Step 3.0 (Mockup Source Decision)** in
+> [../references/ui-design-phase.md](../references/ui-design-phase.md) when the
+> user picks the **handoff** branch. All `{{placeholders}}` are resolved from the
+> PRD state file (`${paths.prd_dir}/sessions/YYYY-MM-DD-<slug>-state.md`),
+> `baldart.config.yml`, and optional overlays.
+>
+> Render rules:
+> - Conditional sections (marked `{{#if …}} … {{/if}}`) are emitted only when the
+>   condition is true. Skip the entire section (including its heading) when false.
+> - Lists (marked `{{#each …}}`) render one bullet per item; emit "—" if empty.
+> - The rendered output is presented to the user inside a fenced markdown
+>   code-block so they can copy-paste verbatim into Claude Design.
+
+---
+
+# Feature: {{feature_title}}
+
+## 1. Obiettivo
+
+{{feature_objective_one_sentence}}
+
+## 2. User flow
+
+{{user_flow_summary}}
+
+{{#if primary_personas}}
+**Personas target**:
+{{#each primary_personas}}
+- {{this.name}} — {{this.context}}
+{{/each}}
+{{/if}}
+
+## 3. Schermate in scope
+
+{{#each screens_in_scope}}
+### {{this.name}}
+
+- **Scopo**: {{this.purpose}}
+- **Stati richiesti**: {{this.states_required}}  <!-- empty, loading, populated, error, success, ecc. -->
+- **Azioni primarie**: {{this.primary_actions}}
+- **Dati visualizzati**: {{this.data_shown}}
+{{#if this.notes}}
+- **Note**: {{this.notes}}
+{{/if}}
+
+{{/each}}
+
+{{#if brand_voice}}
+## 4. Brand & voice
+
+- **Tono**: {{brand_voice.tone}}
+- **Personalità**: {{brand_voice.personality}}
+- **Do**: {{brand_voice.do}}
+- **Don't**: {{brand_voice.dont}}
+{{#if brand_voice.references}}
+- **Riferimenti visivi**: {{brand_voice.references}}
+{{/if}}
+{{/if}}
+
+{{#if has_design_system}}
+## 5. Design system constraints
+
+> Riusa SOLO i token e le primitive elencate. Se devi proporre qualcosa di nuovo,
+> segnalalo esplicitamente nella consegna così posso aggiornare il registro.
+
+### Token chiave
+
+```
+{{design_tokens_excerpt}}
+```
+
+### Primitive da riusare
+
+{{#each registered_primitives}}
+- **{{this.name}}** — {{this.purpose}} ({{this.path}})
+{{/each}}
+
+### Vincoli numerici (da `design-system-protocol.md`)
+
+- Type scale: {{tokens.type_scale}}
+- Spacing scale: {{tokens.spacing_scale}}
+- Radius: {{tokens.radius_scale}}
+- Contrast minimo: {{tokens.contrast_target}} (WCAG AA + APCA Lc ≥ {{tokens.apca_target}})
+- Motion durations: {{tokens.motion_durations}}
+{{/if}}
+
+## 6. Stack target
+
+- **Framework**: {{stack.framework}}
+- **Output preferito**: {{output_format_preference}}  <!-- "HTML/CSS standalone" | "React component (Tailwind)" | "Figma frame" -->
+{{#if stack.charting}}
+- **Charting library**: {{stack.charting}}
+{{/if}}
+{{#if stack.animation}}
+- **Animation library**: {{stack.animation}}
+{{/if}}
+
+## 7. Cosa restituirmi
+
+Per ogni schermata elencata in § 3:
+
+1. **PNG export** ad alta risoluzione (≥ 2x) di OGNI stato richiesto (es. `lista-ordini__empty.png`, `lista-ordini__populated.png`).
+2. {{output_format_preference_block}}  <!-- "Codice HTML/CSS in un file unico" | "Codice React (.tsx) con import Tailwind" | "Link Figma alla frame" -->
+3. **Note inline** su:
+   - Componenti nuovi (non presenti nel registry sopra) che hai introdotto e perché.
+   - Token deviation: qualunque colore/spacing/radius fuori dalla palette sopra, con motivazione.
+   - Decisioni di layout non ovvie (es. priority sort, hierarchy visiva, density).
+
+Quando hai pronto, dimmi i **path locali** dei file (PNG/HTML/TSX) — li importerò in questa sessione PRD per analisi e validazione contro il design system.
+
+---
+
+<!-- baldart-handoff: do-not-edit-manually -->
+<!-- Generated from claude-design-handoff-prompt.template.md by /prd Step 3.0 -->

package/framework/.claude/skills/prd/assets/epic-template.yml

@@ -26,7 +26,14 @@ id: {{FEAT-XXXX-00}}
 title: "Epic: {{Feature Name}} — {{short tagline}}"
 status: TODO
 priority: {{HIGH|MEDIUM|LOW}}
-owner_agent: claude
+
+# Epics are tracker-only — no implementation work, no dispatcher routing.
+# The /new orchestrator skips epics (it only operates on child cards) and the
+# PRD validation-phase enum-check skips them too. Keep this as an empty
+# string to signal "no specialist assigned"; do NOT use one of the child
+# enum values (coder | ui-expert | plan | visual-designer | motion-expert)
+# on an epic — that would falsely imply the epic carries implementation work.
+owner_agent: ""
 execution_mode: cloud
 
 # Epic's group.parent is the PRD slug (string), NOT a FEAT-ID.

package/framework/.claude/skills/prd/references/backlog-phase.md

@@ -4,6 +4,87 @@
 
 Mark task 4 as `in_progress`.
 
+## MANDATORY Card Rules (zero tolerance — read first)
+
+These two rules apply to EVERY child card (epics use `owner_agent: ""`). The
+`prd-card-writer` agent enforces them; the skill MUST verify post-generation
+and HALT if violated.
+
+### Rule A — `owner_agent` is mandatory and enum-validated
+
+Every child card MUST declare `owner_agent` with one of the five values:
+
+```
+coder | ui-expert | plan | visual-designer | motion-expert
+```
+
+There is no implicit default and `claude` is NOT a valid value. Cards with
+missing, empty, placeholder, or non-enum values fail Step 6 (validation-phase)
+and BLOCK the commit. The `/new` orchestrator dispatches implementation
+agent by this field (see `framework/.claude/skills/new/SKILL.md` § Agent
+Routing), so a wrong value silently routes the card to the wrong specialist.
+
+### Rule B — UI cards have UI-only scope (no mixed scope)
+
+A card with `owner_agent: ui-expert` MUST be scoped EXCLUSIVELY to graphical
+concerns: components, layout, styling, token usage, motion, accessibility.
+It MUST NOT bundle:
+
+- business logic / domain rules
+- API integration or data fetching
+- state management beyond local UI state
+- form validation logic (rendering validation states is UI; the rules are not)
+- backend changes (routes, handlers, DB schema)
+
+If a feature step involves BOTH UI and logic, the writer MUST split it into:
+
+- one `owner_agent: ui-expert` card — visual implementation, consumes mocked
+  or contract-stable data
+- one `owner_agent: coder` card — logic, API call, state, persistence
+
+The two cards are wired via `depends_on:` / `blocks:`. A common ordering is
+`coder → ui-expert` (contract ready before UI), but the reverse is acceptable
+when the UI card consumes a hand-written mock.
+
+#### Split example — Login feature
+
+**Bad** (single mixed card):
+
+```yaml
+id: FEAT-XXXX-01
+owner_agent: coder
+scope:
+  summary: |
+    Implement the login page: form layout, validation states, call to
+    POST /api/auth/login, token storage, redirect to dashboard.
+```
+
+**Good** (split into UI + logic):
+
+```yaml
+# UI card — visual only, consumes a mocked auth contract
+id: FEAT-XXXX-02
+owner_agent: ui-expert
+depends_on: [FEAT-XXXX-01]
+scope:
+  summary: |
+    Login form layout (email/password fields, primary CTA, link to recovery),
+    visual states (idle / loading / error / success), a11y (focus order,
+    aria-live for inline errors), responsive breakpoints. Consumes the
+    `useAuth()` mock provided by FEAT-XXXX-01.
+```
+
+```yaml
+# Logic card — API call + state + redirect
+id: FEAT-XXXX-01
+owner_agent: coder
+blocks: [FEAT-XXXX-02]
+scope:
+  summary: |
+    POST /api/auth/login handler, token storage in httpOnly cookie, redirect
+    on success, `useAuth()` hook exposing { status, error, signIn }.
+```
+
 ## MANDATORY Card Structure (zero tolerance — read first)
 
 Every PRD generates **1 epic card + N children**, regardless of N. The

package/framework/.claude/skills/prd/references/ui-design-phase.md

@@ -1,15 +1,97 @@
 # UI Design Phase (Step 3)
 
+## Step 3.0 — Mockup Source Decision (only when `mockups.status: none`)
+
+When the state file shows `mockups.status: none` AND UI impact ≠ N/A, the user
+has not provided any mockup at intake. Before falling into the **Full** pipeline,
+offer them an explicit choice — generate internally or hand off to **Claude
+Design** (Anthropic's design product, design-system-sync'd) — so they don't have
+to abandon the PRD flow halfway.
+
+Skip this step entirely when `mockups.status` ∈ {`provided`, `partial`,
+`pending_external`} (already decided) or when UI impact = N/A (no design work).
+
+### The question (single STOP)
+
+Ask the user, verbatim:
+
+> Non hai fornito mockup all'intake. Come preferisci produrli per questa feature?
+> **(A) Internamente** — genero io 3 opzioni HTML (workflow `ui-design`), iteriamo qui.
+> **(B) Handoff a Claude Design** — ti preparo un prompt context-rich da incollare in Claude Design; quando hai i mockup tornami con i path locali.
+
+**STOP.** Wait for an explicit `A` / `B` answer. Silence or ambiguity ⇒ ask
+again (do NOT default silently).
+
+### Branch A — Internal generation
+
+Set `mockups.source: internal` in the state file, then fall through to the
+**Precondition decision tree** below — the `none` row routes to Full mode
+unchanged. No other side-effect of Step 3.0.
+
+### Branch B — Claude Design handoff
+
+1. **Collect context from the state file + config + overlays:**
+   - `feature_title`, `feature_objective_one_sentence` from `## Feature Description`.
+   - `user_flow_summary`, `primary_personas` from `## Discovery Log` (dimensions 1 + 2).
+   - `screens_in_scope[]` from `## UI Design` (derive from User Stories + ISA touchpoints if not yet populated — same logic as Hybrid mode § "Build the per-screen routing table").
+   - `brand_voice` from `.baldart/overlays/prd.md` if present (skip section otherwise).
+   - When `features.has_design_system: true`: read `${paths.design_system}/INDEX.md` (primitive list) + `${paths.design_system}/tokens-reference.md` (tokens excerpt). When `false`: omit § 5 of the prompt entirely.
+   - `stack.framework`, `stack.charting`, `stack.animation` from `baldart.config.yml`.
+   - `output_format_preference` derived from `stack.framework` (Next/Remix → React+Tailwind; vanilla → HTML/CSS; otherwise ask the user).
+   - Numeric token tables (type scale, spacing, radius, contrast, motion durations) from `framework/agents/design-system-protocol.md` — cite verbatim.
+
+2. **Render the prompt** by populating
+   [../assets/claude-design-handoff-prompt.template.md](../assets/claude-design-handoff-prompt.template.md)
+   with the collected context. Strip empty conditional sections.
+
+3. **Present the rendered prompt** to the user inside a fenced markdown
+   code-block, prefixed with this instruction (verbatim):
+
+   > Incolla il prompt qui sotto in Claude Design. Quando hai i mockup pronti,
+   > tornami con i **path locali** dei file (PNG, HTML, TSX, o link Figma) e
+   > riprendo da qui — copio i file nella cartella del PRD, li analizzo come
+   > al solito (Step 1.6 Mockup Intake), e Step 3 entra in Hybrid mode.
+
+4. **Update state file** before stopping:
+   - `mockups.status: pending_external`
+   - `mockups.source: claude-design`
+   - `mockups.handoff_prompt_path: ${paths.prd_dir}/<slug>/handoff/claude-design-prompt.md` (save the rendered prompt to disk so it survives session restarts).
+   - `step_3_mode: pending_external_handoff` (transitional — overwritten when user returns).
+
+5. **STOP.** Wait for the user to return with local paths.
+
+### Re-entry from handoff (user returns with paths)
+
+When the user comes back with one or more local paths after the handoff:
+
+1. Invoke **Step 1.6 — Mockup Intake** verbatim
+   ([SKILL.md](../SKILL.md) § Hard Rule 16,
+   [discovery-phase.md](discovery-phase.md) § "Mockup analysis schema"):
+   - Copy local files into `${paths.prd_dir}/<slug>/mockups/` with collision-safe
+     rename.
+   - Run the full Mockup analysis schema (screens, user_flow, components,
+     states_visible, copy_excerpts, gaps, design_system_alignment).
+   - Populate `## UI Design` in the state file.
+2. Flip `mockups.status` from `pending_external` to `provided` or `partial`
+   based on coverage of `screens_in_scope[]`. Keep `mockups.source: claude-design`
+   as audit trail.
+3. Fall through to the **Precondition decision tree** below — the `provided` /
+   `partial` row routes to **Hybrid mode** unchanged.
+
+---
+
 ## Precondition decision tree
 
 Read `mockups.status` and `screens_in_scope[]` from the state file `## UI Design`
-section (populated by Step 1.6) plus the UI impact dimension from the discovery
-checklist. Pick exactly one branch:
+section (populated by Step 1.6 and/or Step 3.0 re-entry) plus the UI impact
+dimension from the discovery checklist. Pick exactly one branch:
 
 | Condition | Branch | Action |
 |-----------|--------|--------|
 | UI impact = N/A | **Skip totale** | Mark task 2 `completed` ("Skipped — no UI"). `step_3_mode: skipped`. Proceed to PRD Writing Phase. |
-| `mockups.status: none` AND UI impact ≠ N/A | **Full** | Run the standard pipeline 3a → 3b → 3c → 3d as before. `step_3_mode: full`. |
+| `mockups.status: none` AND UI impact ≠ N/A | **3.0 Decision** | Run Step 3.0 above first. Branch A ⇒ fall through to **Full**; Branch B ⇒ STOP, then re-enter. |
+| `mockups.status: pending_external` | **STOP** | User is in handoff with Claude Design. Do not advance until paths arrive (see § "Re-entry from handoff"). |
+| `mockups.status: none` AND user picked Branch A in Step 3.0 | **Full** | Run the standard pipeline 3a → 3b → 3c → 3d as before. `step_3_mode: full`. |
 | `mockups.status` ∈ {`provided`, `partial`} AND UI impact ≠ N/A | **Hybrid** | Per-screen routing (see § Hybrid mode below). `step_3_mode: hybrid` (or `skipped` if every screen is covered AND no `mockup_analysis.design_system_alignment.violations`). |
 
 Mark task 2 as `in_progress` for the Full and Hybrid branches.

package/framework/.claude/skills/prd/references/validation-phase.md

@@ -6,6 +6,26 @@
 
 Mark task 5 as `in_progress`.
 
+0. **Agent Specialization Audit (runs FIRST — blocks if any failure)** — for each generated child card (epics are skipped):
+
+   a. **`owner_agent` enum check (BLOCKING)** — read the `owner_agent` field. It MUST equal one of:
+      ```
+      coder | ui-expert | plan | visual-designer | motion-expert
+      ```
+      Empty string, missing field, `claude`, or any other value = **BLOCKER**.
+      Message to the user: `"Card <ID> has owner_agent: '<value>' — must be one of {coder, ui-expert, plan, visual-designer, motion-expert}. Fix the card YAML before commit."`
+      Halt the audit. No subsequent checks run on a card that fails this gate.
+
+   b. **UI-only scope heuristic (WARN — soft gate, not blocking)** — for each card with `owner_agent: ui-expert`:
+      - Concatenate `scope.summary`, `requirements[]`, and `acceptance_criteria[]` into one lowercase string.
+      - Grep for logic-marker substrings: `api call`, `endpoint`, `route handler`, `state machine`, `validation logic`, `business rule`, `database`, `migration`, `prisma`, `firestore.collection`, `auth flow`, `token storage`, `webhook`, `cron`.
+      - For each marker hit, log a WARN line in the audit output:
+        `"[UI-SCOPE-WARN] Card <ID> (ui-expert) mentions '<marker>' — review whether logic belongs in a sibling coder card. See backlog-phase.md § Rule B."`
+      - The check is intentionally a soft gate: substrings like "API contract per il mock" or "consumes the auth state from `useAuth()`" are legitimate UI references. The WARN exists to prompt human review, not to block.
+      - Exception (no WARN): the marker appears INSIDE a quoted string that explicitly says "consume", "mock", "contract reference", or "exposed by sibling card" — those are UI cards reading an upstream contract, which is expected.
+
+   **Gate**: every card has `owner_agent` in the enum. WARN entries from check (b) are noted in the audit log; user may accept them after review.
+
 1. **Field Name Audit (runs BEFORE audit agents)** — for each generated card:
 
    a. Verify every `data_fields` entry has `ts_verified: true` OR `status: new` with `schema_ref`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.15.0",
+  "version": "3.17.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"