baldart 4.72.0 → 4.73.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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.73.0] - 2026-06-25
+
+**Mockup→code fidelity: let the implementer actually SEE the mockup, and carry the intent a flat list loses.** A recurring complaint: a detailed mockup (Claude Design / Figma) is handed to `/prd`, then `/new` ships something that is not 1:1 with the design. The obvious diagnosis — "the PRD's visual mapping is too weak, add a mockup-understanding agent" — was **refuted** by an adversarial pass: the visual data largely already exists (`mockup_analysis` captures affordances + traceability + states + DS violations; `component_bindings` propagates region→component to the implementer), and a parallel machine-readable `design-spec` artifact would be a second SSOT that drifts from the mockup and would feed the verifier a textual proxy instead of the pixels (a bias `visual-fidelity-verifier` explicitly forbids). The **actual driver**: the `/new` UI briefing passes the mockup as a *path* and says "Read the design.html file" — but for a binary PNG/Figma mockup nothing ever instructs the (multimodal) `ui-expert` to **load the image into its context**. The implementer was building from text, never looking at the design.
+
+**MINOR** — adds capability; **no new `baldart.config.yml` key** (rides on the existing `features.has_design_system`), so the schema-change propagation rule does NOT apply. The new `component_bindings[].props` is an **optional** sub-field — legacy cards omit it and the validator (which keys on the `C`-profile top-level field) is unaffected. On a non-multimodal tool (Codex) the image-load instruction degrades to a harmless no-op and the structured fields carry the intent.
+
+### Changed
+
+- **The `/new` UI briefing loads the mockup IMAGE multimodally** (`framework/.claude/skills/new/references/implement.md` § "Design Reference"). The instruction now branches on the file type of `links.design`: an IMAGE (`.png`/`.jpg`/`.jpeg`/`.webp`/`.pdf`, or a `mockups/*.png` canonical path) is **`Read` directly** so it renders into the agent's context (pixels = fidelity target); an `.html` keeps the existing read-as-text behaviour. The briefing also now surfaces `component_bindings[].props`/`variant` (exact variant intent) and the card's responsive ACs (breakpoint behaviour a single-viewport image cannot show) as the structured complement to the image.
+- **`mockup_analysis` schema enriched in-place with the four dimensions a flat affordance list + a single static image lose** (`framework/.claude/skills/prd/references/discovery-phase.md` § "Mockup analysis schema"). Each `screens[]` entry gains four OPTIONAL fields: `layout` (compact nesting sketch — the hierarchy), `component_props` (key props/variant legible per component — the reuse-vs-`reuse-variant` signal), `states` (richer `states_visible` mapping each state→the AC that mandates it; an untraced state is a Discovery gap by the same rule as an untraced affordance), and `responsive` (breakpoint behaviour). "Omit rather than guess" discipline extended to all four.
+- **Component Reconciliation consumes the enrichment and persists it** (`framework/.claude/skills/prd/references/ui-design-phase.md` § "Component Reconciliation"). `REUSE+VARIANT` detection now compares `mockup_analysis.component_props` against the component's spec HEAD (props the spec doesn't cover ⇒ variant), and the persist step carries resolved props into `component_bindings[].props` and lifts `responsive` notes into the UI card's `acceptance_criteria` as testable ACs.
+
+### Added
+
+- **`component_bindings[].props` card sub-field** (`framework/agents/card-schema.md` § `component_bindings`) — the optional resolved props/variant each region must use, the exact-variant intent a static image leaves ambiguous; `ui-expert` implements it verbatim. Sub-field of the existing `C`-profile `component_bindings`, so no validator/matrix change.
+
 ## [4.72.0] - 2026-06-25
 
 **Session-id provenance on PRDs and cards — trace an implementation bug back to the chat history that produced it.** When `/new` ships a card that turns out wrong, there was no link from the card back to *which Claude Code session* planned it (`/prd`) or implemented it (`/new`/`/new2`) — so you couldn't reopen the transcript to see the steps the session took (or skipped). Now every card carries an optional `provenance` block recording the session UUID for each lifecycle stage, and the PRD frontmatter records its authoring session. Resolve the chat history at `~/.claude/projects/*/<session-id>.jsonl` (the UUID is globally unique — no project slug needed). This turns "this feature is broken, why?" into a concrete pointer at the planning/implementation conversation, for improving the framework from real runs.

package/VERSION

@@ -1 +1 @@
-4.72.0
+4.73.0

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

@@ -111,9 +111,32 @@
 
    ### Design Reference (UI cards only — include if card has links.design)
    Design file: [path from card's links.design field]
-   Read the design.html file and use it as the **visual reference** for your
-   implementation (layout, spacing, hierarchy, copy). The design was approved by
-   the user — your implementation MUST match its appearance.
+
+   **Load the mockup into your context — branch on the file type:**
+   - If `links.design` resolves to an IMAGE (`.png` / `.jpg` / `.jpeg` /
+     `.webp` / `.pdf`, or the card points at a `mockups/*.png` canonical path):
+     you are multimodal — **`Read` the mockup image file path directly**. `Read`
+     renders the image visually into your context (the native multimodal
+     mechanism). The mockup's PIXELS are the fidelity target: study layout,
+     spacing, hierarchy, density, color, and the relative position of every
+     region. Do NOT implement from the filename or a textual guess — you MUST
+     actually load and look at the image. (On a non-multimodal tool the `Read`
+     degrades to no-op text; fall back to the structured fields below.)
+   - If `links.design` is an `.html` file: **Read the design.html file** and use
+     it as the visual reference.
+
+   Use it as the **visual reference** for your implementation (layout, spacing,
+   hierarchy, copy). The design was approved by the user — your implementation
+   MUST match its appearance.
+
+   **Structured design intent (when present on the card).** The image shows the
+   static look at one viewport; these fields cover what a single image cannot:
+   - `component_bindings[].props` / `variant` — the exact props/variant each
+     region must use (e.g. `SectionHeader {depth: 0}`, `DataTable {density:
+     comfortable}`). Implement them verbatim; do not eyeball a variant.
+   - the card's responsive acceptance criteria — breakpoint behaviour the
+     single-viewport mockup does not show (e.g. "≤640px: table collapses to
+     card-list"). These are testable ACs, not optional polish.
 
    **The mockup is a visual reference, NOT a license to re-create components.**
    When the card carries `component_bindings` (the `/prd` Component Reconciliation

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

@@ -1122,11 +1122,24 @@ mockup_analysis:
       purpose: <one line — what this screen lets the user do>
       components:
         - <component name from ${paths.design_system}/INDEX.md if matched, else free-form>
+      layout:        # OPTIONAL — compact nesting sketch (the hierarchy a flat list loses)
+        - region: <e.g. "page-header">
+          component: <component or free-form for this region>
+          contains: [<child region/component>, …]   # omit for leaf regions
+      component_props:   # OPTIONAL — key props/variants legible from the mockup, per component
+        - component: <e.g. "SectionHeader">
+          props: {<prop>: <value>}    # e.g. {depth: 0} · {density: comfortable, selectable: true}
       affordances:   # interactive + iconographic artifacts visible in the mockup
         - label: <e.g. "Export CSV button", "bell icon", "Filters tab">
           traces_to: <US-id / AC-id / discovery dimension this artifact serves — or "" if none yet>
           classification: backed | decorative | orphan
       states_visible: [empty, loading, error, success, default]
+      states:        # OPTIONAL — richer form: map each visible state to the AC that mandates it
+        - state: <loading | empty | error | success | default>
+          traces_to: <AC-id — or "" if no AC mandates it yet (a Discovery gap, see below)>
+          representation: <one line, e.g. "skeleton rows ×5", "EmptyState, copy 'Nessun ordine'">
+      responsive:    # OPTIONAL — breakpoint behaviour a single-viewport mockup cannot show
+        - <e.g. "≤640px: DataTable collapses to card-list; header shows back button">
       copy_excerpts:
         - <verbatim text visible in the mockup, max ~10 strings per screen>
       gaps:
@@ -1148,11 +1161,21 @@ mockup_analysis:
 - Omit `copy_excerpts` for screens that have no readable text (icon-only).
 - Omit `states_visible` for screens that show only the default state — do not
   invent states the mockup doesn't show.
+- `layout`, `component_props`, `states`, and `responsive` are OPTIONAL
+  enrichments. Fill them when the mockup makes them legible — they carry exactly
+  the intent a flat affordance list and a single static image lose (nesting
+  hierarchy, the exact component variant, state→AC mapping, breakpoint
+  behaviour). Omit a field rather than guess; never invent a breakpoint,
+  prop, or nesting the mockup doesn't actually show (same rule as `states_visible`).
+  These feed the Component Reconciliation (reuse vs `reuse-variant`) and the
+  `/new` implementer briefing — they are how visual intent survives to code.
 
 **Gap discipline:** every entry in `gaps[]` MUST become either a Discovery question
 or an explicit non-question (recorded in Discovery Log as "skipped — outside
 mockup scope"). Gaps that remain unresolved by the end of Discovery block PRD
-writing in Step 4.
+writing in Step 4. A `states[]` entry with `traces_to: ""` is a gap by the same
+rule — a visible state no AC mandates must be resolved in Discovery (gain an AC,
+or be confirmed cosmetic), exactly like an untraced affordance.
 
 **Affordance discipline (Functional Traceability):** classify every interactive
 or iconographic artifact the mockup shows. The mockup is a fidelity target, not

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

@@ -158,7 +158,10 @@ Before invoking `ui-design`:
    - **REUSE** — an existing component (or a closed-family canonical member) covers
      it. Record the exact component. *No question asked — this is the silent path.*
    - **REUSE+VARIANT** — an existing component covers it but the mockup needs a
-     prop/variant not yet in its spec.
+     prop/variant not yet in its spec. The `mockup_analysis.component_props` for
+     this component is the signal: compare the legible props against the
+     component's spec HEAD — props the spec doesn't cover ⇒ this is a VARIANT,
+     not a plain REUSE.
    - **NEW** — genuinely no match.
 5. **Ask ONLY on ambiguity** (`REUSE+VARIANT` and `NEW` — never on plain REUSE).
    One consolidated `AskUserQuestion` per ambiguous element, in the
@@ -179,7 +182,12 @@ Before invoking `ui-design`:
    - Into each affected card → the `component_bindings` block (see
      `agents/card-schema.md`): `region → component (reuse | new) [+ variant]`. This
      is the authority `ui-expert` implements against (the mockup becomes a visual
-     reference, not a license to re-create).
+     reference, not a license to re-create). **Carry the resolved props** from
+     `mockup_analysis.component_props` into `component_bindings[].props` so the
+     exact-variant intent reaches the implementer (a single static image leaves it
+     ambiguous). Likewise, lift any `mockup_analysis.screens[].responsive` notes
+     into the UI card's `acceptance_criteria` as testable responsive ACs — the
+     mockup cannot show breakpoint behaviour at one viewport.
    - Into the manifest → when the user confirms a new standard / closure, the
      component's `canonical_for` / `use_when` / `selection_closed` are written (via
      `/design-system-init` enrich or `doc-reviewer`), so `baldart ds-gate` enforces
@@ -222,7 +230,7 @@ Pass the resolved inventory to `ui-design`:
 ```
 ### Component Reconciliation (resolved)
 REUSE — bind region → existing component:
-- [region] → [Component] — [path] — [variant if any]
+- [region] → [Component] — [path] — [variant if any] — [props if any]
 
 NEW (governed) — confirmed with user:
 - [region] → [NewComponent] — role: [family@context] — standard: [yes/no] — closed: [yes/no]

package/framework/agents/card-schema.md

@@ -148,6 +148,7 @@ component_bindings:
     action: reuse                     # reuse | reuse-variant | new
     variant: ""                       # when action: reuse-variant
     role: "page-header@depth-0"       # when it maps a Selection-Policy role
+    props: {depth: 0}                 # optional — exact props the region must use (from mockup_props)
   - region: "row actions"
     component: IconButton
     action: reuse
@@ -159,6 +160,14 @@ that finds a `component_bindings` entry MUST honor it over any contrary reading
 the mockup; a UI card that went through `/prd` with `features.has_design_system:
 true` but lacks this field is under-specified (the reconciliation did not run).
 
+`props` is **optional** — the resolved key props/variant the region must use,
+lifted from the mockup analysis `component_props` during reconciliation (e.g.
+`{depth: 0}`, `{density: comfortable}`). It carries the exact-variant intent a
+single static image leaves ambiguous; `ui-expert` implements it verbatim. Omit it
+when the mockup exposes no distinguishing props (the component's defaults apply).
+Breakpoint behaviour the mockup cannot show at a single viewport lives in the
+card's `acceptance_criteria` as testable responsive ACs, not here.
+
 ### `provenance` (session-id traceability — optional, skill-written)
 
 A small block that records **which Claude Code session produced the card**, so a card

package/package.json

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