baldart 3.15.0 → 3.16.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.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.16.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/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/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/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.16.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"