baldart 4.88.3 → 4.89.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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).
 
+## [4.89.0] - 2026-07-01
+
+**Mockup-first build routing — a card with a mockup ALWAYS builds via `/ui-implement` → `ui-expert`.** A `/new` post-mortem (mayo FEAT-0064) found two UI cards with a `links.design_src` mockup built by `coder` instead of `ui-expert`, causing layout drift (caught by the v4.78.0 fidelity gate) + three avoidable rework passes + a full `balanced` review (~174M tokens). Root cause: the v4.82.0 `/ui-implement` delegation gate was positioned **inside** `implement.md` step 7's briefing, structurally **subordinate** to the `owner_agent` router (step 6b) — so a card whose `owner_agent` is `coder` (which `prd-card-writer` Rule B correctly assigns to a **mixed UI+logic** card, since `ui-expert` has UI-only scope) resolved `spawn=coder` and the delegation note never fired. `new2.js` was worse: it dispatched `owner_agent` with no delegation gate at all.
+
+**MINOR** — routing behavior change, backwards-compatible (no-mockup cards unchanged; the coarse `ui-expert` inline fallback is preserved for Codex / older installs). **No new `baldart.config.yml` key** (rides on the existing `/ui-implement` + `features.has_design_system`) → the schema-change propagation rule does NOT apply.
+
+### Changed
+
+- **`implement.md` step 6a (NEW — PRIMARY, precedes the `owner_agent` router)**: a card with `links.design` / `links.design_src` has its BUILD routed **mockup-first** to `/ui-implement` (coarse fallback: force `ui-expert` inline + Phase 2.6), *regardless of `owner_agent`*. The epic guard runs first inside 6a. Step 6b (`owner_agent` router) is now explicitly scoped to cards **without** a mockup; the delegation-gate prose is **retired** from step 7's "### Design Reference" (it lives once, at 6a). `owner_agent` still governs review/ownership semantics.
+- **`new2.js`**: `cardGraph` gains `hasMockup`; the deterministic `OWNER_SPAWN` clamp forces `spawn=ui-expert` (ledger `CLAMPED-TO-UI (mockup-first)`) for a mockup card. new2 keeps its **inline** `ui-expert` build this release (full `/ui-implement` off-context delegation remains the documented follow-up).
+- **`/new` SKILL.md § Agent Routing** + **`prd-card-writer.md` Rule A** + **`design-system-protocol.md`** § "Route-Independent Fidelity" — one aligned note each: the build-agent selection is mockup-first; `owner_agent: coder` on a mixed card means coder owns review/logic semantics, never the UI build. Cited from the single SSOT (implement.md step 6a), not duplicated.
+
 ## [4.88.3] - 2026-07-01
 
 **Context-economy trim of the Codex runtime-portability citations.** The top-level RUNTIME PORTABILITY note in `/new` and the HARD-RULES Runtime-portability note in `/prd` (added in v4.88.2's S4/S5 wave) restated content that already lives in `framework/agents/runtime-portability-protocol.md`. Trimmed both to a one-liner (cite, don't restate) — ~406 chars off `/new` SKILL.md and ~363 off `/prd` SKILL.md, i.e. the core each skill drags in context every turn after activation. **No behavior change**: the module citation, the "don't probe `Workflow`/`AskUserQuestion`/the task spine on Codex" rule, and the ADDITIVE guarantee are preserved; RULE 4/11 Codex branches are untouched; the parity guard (`scripts/check-codex-parity.js`) passes. **PATCH.** Skills `new`/`prd` → 1.1.2. No new config key.

package/VERSION

@@ -1 +1 @@
-4.88.3
+4.89.0

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

@@ -156,6 +156,16 @@ that list — not this one — is the source of truth.
 **Epic cards** use `owner_agent: ""` (empty string) because they are
 trackers, not implementation. The dispatcher skips them.
 
+> **Mockup-first build (since v4.89.0) — `owner_agent` does NOT gate the build for a
+> card with a mockup.** When a card carries `links.design` / `links.design_src`, `/new`
+> routes its BUILD **mockup-first** to `/ui-implement` → `ui-expert` at `implement.md`
+> step 6a, *regardless of `owner_agent`*. So a **mixed UI+logic card** correctly keeps
+> `owner_agent: coder` (per Rule B — `ui-expert` cannot OWN logic scope) **and still gets
+> its UI built by `ui-expert`**: `owner_agent: coder` here means coder owns the
+> review/logic ownership semantics, it does NOT send the UI build to coder. Keep setting
+> `owner_agent` per Rules A/B as before — just do not expect it to pick the build agent
+> for a mockup card.
+
 ### Rule A.1 — AC↔ownership consistency (every AC must be satisfiable inside the card)
 
 For EVERY acceptance criterion you write, the file(s) that AC requires editing

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

@@ -427,6 +427,15 @@ orchestrator is hard-killed and never resumed, the `baldart doctor` reaper is th
 
 ## Agent Routing (Phase 2 dispatcher)
 
+> **Mockup-first override (since v4.89.0 — precedes this table).** A card with a
+> mockup (`links.design` / `links.design_src`) does NOT reach the `owner_agent`
+> dispatcher below: its BUILD is routed **mockup-first** at `implement.md` **step 6a**
+> to `/ui-implement` → `ui-expert` (coarse fallback: `ui-expert` inline), *regardless of
+> `owner_agent`*. `owner_agent` still governs review/ownership semantics for that card,
+> but never sends a UI build to `coder`. The table below applies only to cards WITHOUT a
+> mockup. This closes the FEAT-0064 failure (a `owner_agent: coder` mixed card with
+> `links.design_src` built by coder).
+
 Phase 2 reads the card's `owner_agent` field and dispatches to the matching
 specialist. The enum's single source of truth is the **`owner_agent enum` block in
 `framework/.claude/agents/REGISTRY.md`** (applied by `prd-card-writer.md § Agent

package/framework/.claude/skills/new/references/implement.md

@@ -49,7 +49,36 @@
 
 ### Phase 2 — Implement (self-healing, up to 3 retries)
 6. **Update tracker**: phase = "2-implement".
-6b. **Agent dispatch (router)** — read `owner_agent` from the card YAML and resolve the spawn target per the table in § Agent Routing above:
+6a. **Mockup-build delegation gate (PRIMARY — precedes the owner_agent router).** The BUILD agent for a card with a mockup is decided by the **mockup**, NOT by `owner_agent`. This gate is structurally FIRST so a stale/mixed-card `owner_agent: coder` can never send a UI build to `coder` (the FEAT-0064 failure: a card with `links.design_src` built by coder because the delegation note was buried downstream in the step-7 briefing). SSOT: `framework/agents/design-system-protocol.md` § "Route-Independent Fidelity & Coverage Obligation".
+
+   ```
+   # 6a is the FIRST dispatch decision. Epic guard FIRST — an epic is a tracker, never built.
+   If card is an epic (id ends "-00" OR filename ends "-epic.yml" OR review_profile == "skip"
+       with no requirements): SKIP — log "[ROUTER] card <ID> is an epic (tracker) — skipped,
+       not implemented" and move to the next card.
+   If card has links.design OR links.design_src (a mockup exists):
+       IF the /ui-implement skill is available:
+           DELEGATE this card's mockup→code implement + fidelity verify to /ui-implement
+           in programmatic mode (contract: ui-implement/references/integration.md).
+           Consume its COMPACT JSON (status mirrors /e2e-review — review-cycle.md Phase 2.6
+           gating table). SKIP step 6b (owner_agent router), the step-7 coarse briefing,
+           AND Phase 2.6 (the skill already ran /e2e-review). Then resume the per-card
+           review cluster (Phase 2.55 Simplify → Phase 3 doc → 3.5 QA → 3.7 Codex) per the
+           card's review_profile — for a MIXED UI+logic card /new KEEPS that cluster
+           (integration.md § "What /new KEEPS"); it is fidelity-only that the skill owns.
+       ELSE (coarse fallback — Codex without the skill / older install / no skill routing):
+           FORCE spawn = "ui-expert", briefing = "ui-expert" (regardless of owner_agent),
+           and run Phase 2.6 /e2e-review inline as before. The step-7 "### Design Reference"
+           section is the coarse briefing body.
+       Log (tracker): "[ROUTER] card <ID> has a mockup (links.design[_src]) → mockup-first
+           build via /ui-implement (or ui-expert coarse); owner_agent='<raw>' does NOT gate
+           the build".
+       → the build agent for this card is now decided; do NOT fall through to step 6b.
+   Else (no mockup) → fall through to step 6b (owner_agent router).
+   ```
+
+   `owner_agent` is still honored for **review/ownership semantics** (AC-closure ownership, `security-reviewer` relevance, the mixed-card review cluster) — it simply no longer decides the BUILD agent when a mockup is present.
+6b. **Agent dispatch (router — cards WITHOUT a mockup only).** Reached only when step 6a did not fire (the card has no `links.design`/`links.design_src`). 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).
@@ -113,22 +142,13 @@
    Design file: [path from card's links.design field]
    Design source: [path from card's links.design_src field, if present]
 
-   **DELEGATION GATE — mockup→code is owned by `/ui-implement` (since v4.82.0).**
-   When the `/ui-implement` skill is available AND the card has `links.design` /
-   `links.design_src`, the orchestrator DELEGATES this card's mockup→code
-   **implement + fidelity verify** to `/ui-implement` in programmatic mode
-   (contract: `framework/.claude/skills/ui-implement/references/integration.md`).
-   The skill is the SSOT of the input-type build playbook (Claude Design link /
-   finished-code / image / HTML) and folds in Phase 2.6 `/e2e-review`. On delegation: **skip the
-   coarse briefing below AND Phase 2.6 for this card** (the skill already ran the
-   fidelity verify), consume its COMPACT JSON, then resume the normal per-card
-   cluster on the resulting diff (Phase 2.55 Simplify → **skip Phase 2.6** which
-   the skill already ran → Phase 3 doc / 3.5 QA / 3.7 Codex — the skill's scope is
-   **fidelity only**, no review hole). The `ui-expert` registry-first cascade +
-   Post-Intervention Coherence below STILL apply — the skill enforces the same
-   SSOTs. **Coarse inline fallback** (skill unavailable / Codex / older install):
-   use the briefing below + Phase 2.6 as before; the prose here stays the SSOT
-   fallback (delegate-or-else-inline).
+   > **Note:** the mockup→code build decision was made at **step 6a** (Mockup-build
+   > delegation gate). If step 6a delegated to `/ui-implement`, this whole
+   > "### Design Reference" section is NOT reached (the skill owns the build + Phase
+   > 2.6). This section is the **coarse-fallback briefing body** filled by step 6a's
+   > ELSE branch (skill unavailable → `ui-expert` builds inline + Phase 2.6 runs). Its
+   > SSOT is `ui-implement/references/playbook.md` + `ui-expert.md`; do NOT re-add a
+   > delegation gate here — it lives once, at step 6a.
 
    **Coarse fallback — build workflow by input type.** The full SSOT is
    `framework/.claude/skills/ui-implement/references/playbook.md` +

package/framework/.claude/workflows/new2.js

@@ -286,7 +286,7 @@ try {
       g3Bullet +
       `• G4 card-field validation (setup.md 1b/1c, card-schema.md consumer contract): card missing acceptance_criteria/files_likely_touched/scope → EXCLUDE (excluded[] + reason). \`requirements\` is CONDITIONAL, not an auto-exclude: if it is missing BUT acceptance_criteria + scope are both present and non-empty, FAITHFULLY DERIVE it (a concrete restatement/decomposition of the existing AC + scope — faithful, never inventing new scope) and WRITE it back to the card YAML on disk in ${MAIN}/${paths.backlog_dir || 'backlog'} (F-040: main repo, not the worktree copy; the card artifact is NOT a source/doc file, so this is allowed despite the role boundary), logging \`[BACKFILL] <id>: requirements=<N items, AC+scope-derived>\`. Only EXCLUDE for missing requirements when acceptance_criteria OR scope is ALSO empty (a genuinely thin card). Never HALT for one bad card.\n` +
       `• G5 depends-on: a card whose depends_on names a non-DONE card NOT in this batch → EXCLUDE it AND every in-batch card that transitively depends on it.\n` +
-      `• cardGraph (REQUIRED, F-021): for every runnable card return { id, dependsOn:[IN-BATCH deps only], ownerAgent (the card's owner_agent; G25 unknown→'coder'), reviewProfile (the card's review_profile; default 'balanced'), policyDeferredACs, alreadyCommitted, alreadyCommittedSha, isEpic (implement.md §6b epic guard: id ends '-00' OR filename ends '-epic.yml' OR group.is_epic:true OR review_profile 'skip' with no requirements), filesLikelyTouched (verbatim from the YAML) }.\n` +
+      `• cardGraph (REQUIRED, F-021): for every runnable card return { id, dependsOn:[IN-BATCH deps only], ownerAgent (the card's owner_agent; G25 unknown→'coder'), hasMockup (BOOLEAN — true IFF the card has a non-empty links.design OR links.design_src; drives the mockup-first build override — implement.md §6a), reviewProfile (the card's review_profile; default 'balanced'), policyDeferredACs, alreadyCommitted, alreadyCommittedSha, isEpic (implement.md §6b epic guard: id ends '-00' OR filename ends '-epic.yml' OR group.is_epic:true OR review_profile 'skip' with no requirements), filesLikelyTouched (verbatim from the YAML) }.\n` +
       `• B1/F-026 idempotency (per card, AFTER the worktree exists): set alreadyCommitted:true (+ alreadyCommittedSha) IFF ALL hold: (a) a commit referencing the card id exists in ${TRUNK}..HEAD of the worktree; (b) the card's validation_commands re-run GREEN right now; (c) NO open follow-up card for it exists in ${paths.backlog_dir || 'backlog'}. On a FRESH worktree ${TRUNK}..HEAD is empty → all false, zero extra work.\n` +
       `• F-016 AC↔ownership consistency: for each acceptance_criterion, derive the file(s) it requires editing. If those files are NOT a subset of the card's MAY-EDIT/files_likely_touched → add the AC to policyDeferredACs:[{n,text,owningCard|owningFile,reason}] (it will become ONE follow-up, never a resolve). Do the same for any AC whose remedy is an owner-gated infra action (remote db push / deploy / secret / DNS).\n` +
       (migrationApplied
@@ -370,6 +370,16 @@ for (const n of cardGraph) graphById[n.id] = n
 const OWNER_SPAWN = { coder: 'coder', 'ui-expert': 'ui-expert' }
 for (const n of cardGraph) {
   const raw = String(n.ownerAgent || '').trim()
+  // Mockup-first override (implement.md §6a, since v4.89.0): a card with a mockup builds
+  // via ui-expert regardless of owner_agent — closes the FEAT-0064 coder-builds-UI failure.
+  // (new2 keeps the INLINE ui-expert build this release; full /ui-implement off-context
+  // delegation is the documented follow-up — ui-implement/references/integration.md § new2 note.)
+  if (n.hasMockup) {
+    n.ownerAgentRaw = raw
+    n.ownerAgent = 'ui-expert'
+    ledger(n.id, 'router', 'CLAMPED-TO-UI', `mockup-first: links.design[_src] present → spawn=ui-expert (owner_agent='${raw || '(missing)'}' does not gate the build)`)
+    continue
+  }
   const spawn = OWNER_SPAWN[raw.toLowerCase()] || 'coder'
   n.ownerAgentRaw = raw
   n.ownerAgent = spawn

package/framework/agents/design-system-protocol.md

@@ -645,6 +645,15 @@ advisory), plus the mechanical build/lint/tsc gates. The deep `/codexreview` and
 layout) is absorbed by the trio. All fidelity fixes (structural, presentational, quality)
 route to `ui-expert`.
 
+**BUILD-agent selection is mockup-first (since v4.89.0).** For ANY card with a mockup
+(`links.design` / `links.design_src`) — pure-graphics OR **mixed UI+logic** — the build
+agent is decided by the mockup, NOT `owner_agent`: it is routed to `/ui-implement` →
+`ui-expert` **before and independent of** the `owner_agent` router (`/new` `implement.md`
+step 6a; `new2.js` mockup-first clamp). This closes the FEAT-0064 failure where a mixed
+card's `owner_agent: coder` (correct for its logic/review ownership) sent the UI build to
+`coder`. `owner_agent` still governs the review/ownership semantics; it just does not pick
+the build agent when a mockup is present.
+
 ### Gating philosophy (calibration)
 
 Vision-model reliability research (*MLLM as a UI Judge*, 2025) shows multimodal judges are

package/package.json

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