baldart 4.71.0 → 4.73.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.
+
+The enabling fact (verified against a live `env`): the session id IS available at runtime as **`CLAUDE_CODE_SESSION_ID`** — NOT `CLAUDE_SESSION_ID` (which does not exist). The capture discipline matters: the value is read by the **orchestrator** (`/prd`, `/new`, the `new2` skill) in its own context and passed down — never read inside a writer/commit subagent, whose own session id differs (`CLAUDE_CODE_CHILD_SESSION=1`).
+
+**MINOR** — adds a traceability capability; **NOT a `baldart.config.yml` key** (it is a card-schema field + a native env var), so the schema-change propagation rule does NOT apply. The `provenance` field is **optional (`C`)** in every card profile — the validator ignores it and legacy cards never break (verified by running `validate-card-baseline.js` on cards with and without the block). Sub-fields are omitted when the env var is unset; an EPIC card (a tracker) carries `planning_session` only.
+
+### Added
+
+- **`provenance` card field** (`framework/agents/card-schema.md` — the schema SSOT) — `{ planning_session, implementation_session }`, both optional session UUIDs, added to the field-state matrix as `C`/`C`/`C` with a dedicated `§ provenance` section defining ownership-by-lifecycle and the `CLAUDE_CODE_SESSION_ID` resolution rule. Mirrored in the card template (`framework/.claude/skills/prd/assets/card-template.yml`) and a `planning_session` frontmatter line in the PRD template (`framework/.claude/skills/prd/assets/prd-template.md`).
+- **`session_id` on the `/new` telemetry row** (`framework/.claude/skills/new/references/metrics.md`) — `skill-runs.jsonl` records now carry the run's session UUID so the metrics row also resolves to its transcript.
+
+### Changed
+
+- **`/prd` stamps the planning session** — `prd-card-writer` (`framework/.claude/agents/prd-card-writer.md`) sets `provenance.planning_session` from a new `PLANNING_SESSION_ID` field the `/prd` orchestrator passes (captured in the orchestrator's own context, `backlog-phase.md`), and `/prd` writes the same id into the PRD frontmatter (`prd-writing-phase.md`). The writer never reads the env var itself (subagent session ≠ conversation session).
+- **`/new` + `/new2` stamp the implementation session** when a card reaches `status: DONE` — `/new` at `commit.md` Step 28 (`framework/.claude/skills/new/references/commit.md`); `/new2` via a new `sessionId` workflow arg captured by the skill and stamped by `new2.js` at the per-card commit step, the cross-card integration commit, and the skill's post-run deferred-card reconciliation — always merging into the existing `provenance` block, never overwriting `planning_session`.
+
+### Fixed
+
+- **`team-mode.md` used the non-existent `CLAUDE_SESSION_ID`** (`framework/.claude/skills/new/references/team-mode.md`) — the subagent-transcript locator (`ls ~/.claude/projects/*/${CLAUDE_SESSION_ID:-*}/subagents`) always fell through to the wildcard fallback because the variable name was wrong. Corrected to `CLAUDE_CODE_SESSION_ID` so it resolves the live session's `subagents/` dir directly.
+
 ## [4.71.0] - 2026-06-25
 
 **Responsive-awareness in UI review — catch a viewport-scoped edit that regresses the *other* viewport.** When an agent works on one viewport (fix the mobile header, tweak the desktop table), nothing today catches it silently shifting the viewport it was *not* editing. The obvious fix — cloning the i18n ESLint gate into a `responsive-gate` that bans raw `matchMedia`/breakpoint literals — was **refuted** by an adversarial pass: that gate is blind to where responsiveness actually lives (Tailwind `md:` classes, CSS, CSS-in-JS — not `window.matchMedia`), so it is mayo-specific opinion, not a distributable mechanism. The real driver is served by **reactivating machinery that already exists and was inert**: `visual-fidelity-verifier` has had a `responsiveness-break` finding all along, but `/e2e-review` only ever screenshotted **one** viewport (1440px), so it could never fire.

package/VERSION

@@ -1 +1 @@
-4.71.0
+4.73.0

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

@@ -42,6 +42,26 @@ predating v3.22.0): fall back to the consumer root (whatever Bash `pwd`
 returns). Log a `[WORKING-DIR-FALLBACK]` warning in your response so the
 caller can detect it and migrate.
 
+## Session provenance (the caller passes `PLANNING_SESSION_ID`)
+
+When invoked by `/prd` Step 5 the caller ALSO passes a **`PLANNING_SESSION_ID`**
+field — the Claude Code session UUID of the `/prd` run (the orchestrator's
+`$CLAUDE_CODE_SESSION_ID`). On EVERY card you write, set:
+
+```yaml
+provenance:
+  planning_session: "<PLANNING_SESSION_ID>"
+```
+
+This makes a card traceable back to the chat history that authored it
+(`~/.claude/projects/*/<id>.jsonl`). **Do NOT read `CLAUDE_CODE_SESSION_ID`
+yourself** — you run as a subagent, so your own session id differs from the
+`/prd` conversation the user sees; only the value the caller passed is correct.
+If the caller did NOT pass `PLANNING_SESSION_ID` (legacy call site, or the env
+var was unset), **omit the `provenance` block entirely** — never write a
+placeholder. Do NOT set `implementation_session` — `/new`/`/new2` add that when
+the card reaches `status: DONE`.
+
 ---
 
 ## Field Grounding Rule (HARD RULE — zero tolerance)

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

@@ -30,7 +30,7 @@
       3. **Retry cap + escalation** — retry the commit at most **2 times**. If it still fails (e.g. a pre-commit / doc-freshness rule that cannot be satisfied without human input), log the failure in `## Issues & Flags` as `[COMMIT-BLOCKED] <error>` and invoke `AskUserQuestion`: (a) fix the blocking condition manually and let me retry, (b) hand off the worktree intact, (c) abandon this card and continue the batch. Do NOT loop indefinitely and do NOT silently proceed to step 28 with an uncommitted card. **When AUTONOMOUS, apply § AUTONOMOUS RESOLUTION RULE (SKILL.md): category=blocker; recommended=none safe (a hook rejection needs human input) → materialize a follow-up card carrying the blocking condition and leave the worktree intact (NEVER force-commit, NEVER mark the card DONE).**
     - The Claude Code pre-commit hook automatically skips for worktree commits (Husky handles checks natively in the worktree).
 28. **Mark card DONE (MANDATORY — do NOT skip)**:
-    a. Edit the backlog YAML (`${paths.backlog_dir}/<CARD-ID>.yml`): set `status: DONE`, add `completed_date: <today>`.
+    a. Edit the backlog YAML (`${paths.backlog_dir}/<CARD-ID>.yml`): set `status: DONE`, add `completed_date: <today>`, and add `provenance.implementation_session: <SESSION-ID>` (this run's session UUID — get it with `Bash(echo "${CLAUDE_CODE_SESSION_ID:-}")`; if empty, omit the field). Merge into any existing `provenance:` block written by `/prd` — do NOT overwrite `planning_session`. This makes an implementation bug traceable back to the session that produced it (`~/.claude/projects/*/<id>.jsonl`).
     b. Add implementation notes summarizing what was built.
     c. **Update `${paths.references_dir}/ssot-registry.md`** — add/update the entry for this card's feature area. The pre-commit doc-freshness hook BLOCKS commits that touch `${paths.backlog_dir}/` without a corresponding ssot-registry update. Always include ssot-registry.md in the same commit as the backlog YAML.
     d. **Verify the write**: re-read the YAML file and confirm `status: DONE` is present. If not, retry the edit.

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/new/references/metrics.md

@@ -41,10 +41,10 @@ has no blocking consequence the honest label is "monitoring signal".
 3. **Assemble the full JSONL record in memory** (single atomic append — JSONL is append-only, so the row must be COMPLETE before it touches the file). If `STATS=true` (step 6), the `"cost"` key is part of THIS record — do NOT write a baseline row now and rewrite it later (a mid-file rewrite corrupts the JSONL; there is no `sed -i`/`jq` rewrite step in this skill). When `STATS=true`, defer the single append to step 6 after the cost object is computed; when `STATS=false`, append now. The record shape:
 
    ```json
-   {"ts":"<ISO-8601-UTC>","skill":"new","run_id":"batch-<FIRST-CARD-ID>","cards":["FEAT-XXX"],"total_cards":N,"first_attempt_success_rate":0.0,"mean_fix_cycles":0.0,"qa_profiles":{"skip":0,"light":0,"balanced":0,"deep":0},"qa_pass_first_attempt_rate":0.0,"findings_total":0,"findings_verified":0,"actionability_rate":0.0,"severity_p0_pct":0.0,"doc_gaps_found":0,"doc_gaps_fixed":0,"cycle_time_mins":0,"worktree_branch":"","merge_commit":""}
+   {"ts":"<ISO-8601-UTC>","skill":"new","run_id":"batch-<FIRST-CARD-ID>","session_id":"<$CLAUDE_CODE_SESSION_ID, '' if unset>","cards":["FEAT-XXX"],"total_cards":N,"first_attempt_success_rate":0.0,"mean_fix_cycles":0.0,"qa_profiles":{"skip":0,"light":0,"balanced":0,"deep":0},"qa_pass_first_attempt_rate":0.0,"findings_total":0,"findings_verified":0,"actionability_rate":0.0,"severity_p0_pct":0.0,"doc_gaps_found":0,"doc_gaps_fixed":0,"cycle_time_mins":0,"worktree_branch":"","merge_commit":""}
    ```
 
-   Use `date -u +%Y-%m-%dT%H:%M:%SZ` for the timestamp. Append the assembled line ONCE with `echo '<full-record>' >> "$METRICS/skill-runs.jsonl"` via Bash — never append a partial row then mutate it.
+   Use `date -u +%Y-%m-%dT%H:%M:%SZ` for the timestamp. Fill `session_id` with `echo "${CLAUDE_CODE_SESSION_ID:-}"` (this run's session UUID — the same one stamped as `provenance.implementation_session` on each card; `""` if unset) so the telemetry row resolves to the chat transcript at `~/.claude/projects/*/<id>.jsonl`. Append the assembled line ONCE with `echo '<full-record>' >> "$METRICS/skill-runs.jsonl"` via Bash — never append a partial row then mutate it.
 
 4. Copy the batch tracker to archive:
 

package/framework/.claude/skills/new/references/team-mode.md

@@ -153,8 +153,8 @@ For each completed agent:
 - A genuinely legitimate no-op card (its AC turned out already satisfied) is the rare exception: confirm it from the report's per-requirement `evidence` pointing at PRE-EXISTING code, and log it explicitly as `no-op (AC pre-satisfied)` — never assume zero-diff means success.
 **Classify the CAUSE before re-spawning — you MUST read the rested agent's LAST event, never infer the cause from "no report" alone.** A background teammate killed mid-flight dies WITHOUT delivering anything to you, so its failure signature lives ONLY in its on-disk transcript — "no report + no diff" is the SAME observable for a rate-limit death and a genuine empty-result, and they need OPPOSITE remedies. Before choosing one, locate and tail that transcript:
 - Subagent transcripts live at `<session-subagents-dir>/agent-*.jsonl`, each with a sibling `agent-*.meta.json` whose `agentType` equals the teammate label. Resolve the file and read its tail, e.g.:
-  `D="$(ls -dt ~/.claude/projects/*/${CLAUDE_SESSION_ID:-*}/subagents 2>/dev/null | head -1)"; f="$(grep -l '"<teammate-label>"' "$D"/*.meta.json 2>/dev/null | head -1 | sed 's/\.meta\.json$/.jsonl/')"; tail -c 4000 "$f"`
-  (if `$CLAUDE_SESSION_ID` is unset, the most recent `subagents/` dir under this project is the live session's.) If the transcript truly cannot be located, fall back to whatever the `Agent` tool result surfaced — but do NOT default to "genuine empty-result" without having looked. **State the classification you reached + the evidence in your narration** (e.g. "03 last event = `Rate limited` → transient").
+  `D="$(ls -dt ~/.claude/projects/*/${CLAUDE_CODE_SESSION_ID:-*}/subagents 2>/dev/null | head -1)"; f="$(grep -l '"<teammate-label>"' "$D"/*.meta.json 2>/dev/null | head -1 | sed 's/\.meta\.json$/.jsonl/')"; tail -c 4000 "$f"`
+  (if `$CLAUDE_CODE_SESSION_ID` is unset, the most recent `subagents/` dir under this project is the live session's.) If the transcript truly cannot be located, fall back to whatever the `Agent` tool result surfaced — but do NOT default to "genuine empty-result" without having looked. **State the classification you reached + the evidence in your narration** (e.g. "03 last event = `Rate limited` → transient").
 - **Transient infra failure (the common cause of a silent empty rest in a WIDE parallel wave).** The agent's last event is an API error — signatures: `isApiErrorMessage:true`, `Rate limited`, `Server is temporarily limiting requests`, `overload`, `(not your usage limit)` — i.e. the background teammate was **killed mid-flight by API rate-limiting** (it had done real work — reads, a plan — then died), NOT a model fabrication or "decided nothing to do". The runtime does NOT auto-resume a dead teammate, so it rests with no report + no diff. **Re-spawn it, but STAGGERED with backoff — do NOT re-fire several transient-failed agents in the same parallel burst** (that re-saturates the API and kills them again). Space them out (one at a time, or after a brief pause). This still costs a fresh run (the killed agent's reads are lost — the runtime cannot resume it), so **prevention beats recovery**: if a wave repeatedly hits rate limits, NARROW the parallel fan-out width for that wave (spawn fewer coders at once) rather than re-firing the full wave. A transient failure does NOT consume the Step-B genuine-failure budget. **(Workflow twin, since v4.66.0:** inside the `new-card-review` / `new-final-review` dynamic workflows the same transient-vs-terminal discipline is enforced in code — `agentSafe` retries a transient-killed reviewer in-workflow, and a reviewer that stays dead is recorded in `summary.degradedReviewers` rather than silently dropped by `filter(Boolean)`; a dead **qa-sentinel** specifically injects a synthetic `FAIL` gate so the merge is blocked, never passed on UNKNOWN mechanical gates. Same SSOT, two surfaces: this prose for orchestrator-spawned teammates, the workflow JS for in-workflow fan-out.)**
 - **Genuine empty-result / fabrication.** The agent rested CLEANLY (no error in its last event), with no completion report and no diff. THIS is the model-fault case: take the one Step-B re-spawn below (same cap), re-briefing the coder with an explicit "write your ownership files and confirm them on disk before reporting done" mandate. A second empty result → `AskUserQuestion` (skip/abandon) — do not re-spawn a third time. **When AUTONOMOUS, apply § AUTONOMOUS RESOLUTION RULE (SKILL.md): category=blocker; recommended=none safe (a card whose coder produced nothing twice has no implementation) → skip the card AND materialize a follow-up card carrying its spec (NEVER mark it DONE / no-op).** (Classify the cause first — a transient rate-limit death is re-spawned staggered, not counted against this budget.)
 

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

@@ -152,6 +152,7 @@ Workflow({ name: 'new2', args: {
   refModulesBase,     // .claude/skills/new/references (semantic SSOT)
   config,             // the parsed baldart.config.yml (paths.*/stack.*/features.*/git.*)
   ts,                 // ISO timestamp NOW — the workflow has no clock (Date.now() unavailable there)
+  sessionId,          // this run's CLAUDE_CODE_SESSION_ID — stamped as provenance.implementation_session on each DONE card
   migration,          // Step-3.5 manifest: { status:'none'|'applied'|'skipped'|'degraded', modality?, summary?, artifacts?, affects_cards? }
   flags: { stats, effort, full }
 }})
@@ -160,6 +161,12 @@ Workflow({ name: 'new2', args: {
 Record the kickoff time (`ts`) before the call — Step 5 uses it to stamp the
 real wall-clock duration (the workflow cannot read a clock).
 
+Capture `sessionId` the same way, in THIS skill's own context (not a subagent):
+`Bash(echo "${CLAUDE_CODE_SESSION_ID:-}")`. The workflow stamps it as
+`provenance.implementation_session` on each card it marks DONE, so a batch is
+traceable back to the chat history that ran it (`~/.claude/projects/*/<id>.jsonl`).
+If the echo is empty, pass `sessionId: ''` and the workflow omits the field.
+
 The workflow runs the entire batch in the background. **Do not poll it** — it
 returns when the batch is done. It returns:
 
@@ -212,8 +219,10 @@ returns when the batch is done. It returns:
    - **Every class ∈ {`owner-gated`, `not-a-code-defect`, `policy-deferred-ac`}** → the card's own
      code is complete; the residual is an external/infra step. Now that step 1 guaranteed its
      deferral's follow-up exists on disk in the main repo, set the card `status: DONE` +
-     `completed_date` + an implementation_note (`"DONE post-run (new2) — AC deferred to follow-up
-     <id>"`) in `${paths.backlog_dir}/<card>.yml`, and fold all of them into ONE reconciliation
+     `completed_date` + `provenance.implementation_session: <sessionId>` (the same id captured
+     for the workflow args — merge into any existing provenance block, do NOT touch
+     `planning_session`; omit if empty) + an implementation_note (`"DONE post-run (new2) — AC
+     deferred to follow-up <id>"`) in `${paths.backlog_dir}/<card>.yml`, and fold all of them into ONE reconciliation
      commit in the MAIN repo.
    - **ANY class ∈ {`unresolved`, `out-of-ownership`, `outage`} (or missing)** → the card's DoD is
      genuinely NOT met (an AC the workflow tried and failed to implement). Leave it **IN_PROGRESS**

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

@@ -284,3 +284,14 @@ assumptions:
 unknowns: []
 
 notes: []
+
+# --- Provenance (OPTIONAL — SKILL-written, never authored by hand) ---
+# Records which Claude Code session produced this card, so an implementation error
+# is traceable back to the chat history that planned/implemented it.
+# Resolve the transcript at ~/.claude/projects/*/<session-id>.jsonl (UUID is globally unique).
+# planning_session: written by prd-card-writer (value passed in by the /prd orchestrator as
+#   PLANNING_SESSION_ID — the orchestrator's CLAUDE_CODE_SESSION_ID, NOT the writer subagent's).
+# implementation_session: added by /new (commit.md Step 28) or /new2 when status → DONE.
+# Omit a sub-field when its session id is unavailable; an EPIC card has planning_session only.
+provenance:
+  planning_session: "{{CLAUDE_CODE_SESSION_ID of the /prd run — omit if unset}}"

package/framework/.claude/skills/prd/assets/prd-template.md

@@ -5,6 +5,10 @@ canonicality: canonical
 owner: prd
 status: draft
 freshness_status: fresh
+# Session that authored this PRD — resolve the chat history at
+# ~/.claude/projects/*/<id>.jsonl. Value = $CLAUDE_CODE_SESSION_ID of the /prd run.
+# Omit the line if the env var is unset.
+planning_session: {{CLAUDE_CODE_SESSION_ID of the /prd run}}
 ---
 
 # {{Feature Name}} PRD

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

@@ -194,6 +194,10 @@ Agent(
     directory, NOT into the consumer's main repo. See your "Working Directory"
     section for the rule and sanity check.)
 
+    PLANNING_SESSION_ID: <$PLANNING_SESSION_ID>
+    (The /prd run's session UUID — set provenance.planning_session on every card.
+    See your "Session provenance" section. Omit the field if this value is empty.)
+
     PRD path: <$WORKTREE_PATH>/<prd_path>
     State file path: <$WORKTREE_PATH>/<state_file_path>
     Card template: <$WORKTREE_PATH>/.claude/skills/prd/assets/card-template.yml
@@ -223,6 +227,13 @@ in the state file's `## Worktree` section BEFORE invoking the agent. Do NOT
 pass the literal string `$WORKTREE_PATH` — the subagent has no shell context
 to expand it.
 
+The same applies to `<$PLANNING_SESSION_ID>`: BEFORE invoking the agent, the
+`/prd` skill captures its OWN session id with `Bash(echo "${CLAUDE_CODE_SESSION_ID:-}")`
+and substitutes the value (a UUID) into the prompt. The capture MUST run in the
+orchestrator's own context (this skill), NOT inside the writer subagent — a
+subagent's `CLAUDE_CODE_SESSION_ID` is its own, not the `/prd` conversation's.
+If the echo prints empty, pass an empty value and the writer omits the field.
+
 ### What the agent handles
 
 The `prd-card-writer` agent owns the entire card writing pipeline:

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/prd-writing-phase.md

@@ -97,6 +97,11 @@ Mark task 3 as `in_progress`.
    - Include a "Research-Informed Decisions" subsection listing decisions influenced
      by research, with brief rationale and source reference.
 5. Write `${paths.prd_dir}/<slug>/PRD.md` using the template from `assets/prd-template.md`.
+   Fill the frontmatter `planning_session` with this run's session id —
+   `Bash(echo "${CLAUDE_CODE_SESSION_ID:-}")` (run it in this skill's own context,
+   not a subagent). If the echo is empty, drop the `planning_session:` line. This is
+   the same UUID passed to `prd-card-writer` as `PLANNING_SESSION_ID`, so the PRD and
+   its cards share one traceable session pointer.
 
 ### PRD sections checklist
 

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/.claude/workflows/new2.js

@@ -29,6 +29,8 @@ export const meta = {
 //                             affected cards' apply-AC is NOT owner-gated-deferred (F-016 exception).
 //   flags          { stats, effort, full }
 //   ts             string     ISO timestamp injected by the skill (Date.now() is unavailable here)
+//   sessionId      string     this run's CLAUDE_CODE_SESSION_ID (skill-captured) — stamped as
+//                             provenance.implementation_session on each card marked DONE ('' → omit)
 //
 // return (consumed by the skill at Step 5):
 //   { report, perCardResults, gateLedger, residualFollowups, telemetry, degraded, degradationReasons, residuals }
@@ -52,6 +54,12 @@ const METRICS = a.metricsDir || 'docs/metrics'
 const REF = (a.refModulesBase || '.claude/skills/new/references').replace(/\/$/, '')
 const FLAGS = a.flags || {}
 const TS = a.ts || ''
+// Session provenance — stamped on each DONE card so an implementation bug is traceable to the
+// chat history that produced it. '' (env var unset) → the commit agent omits the field.
+const SESSION_ID = a.sessionId || ''
+const provLine = SESSION_ID
+  ? ` Also set provenance.implementation_session: "${SESSION_ID}" (merge into any existing provenance block from /prd — do NOT touch planning_session).`
+  : ''
 // Migration Gate manifest (skill Step 3.5 — front-loaded BEFORE this workflow ran). When
 // status:'applied', the declared schema is LIVE on the active DB, so its apply-AC must NOT be
 // re-classified as an owner-gated policy-deferred AC (F-016) — the downstream cards verify for real.
@@ -775,7 +783,7 @@ async function runCard(cardId, cardPath) {
   // main repo (so a card is never DONE with a silently-dropped requirement — F-029).
   const doneStep = deferredOpen
     ? `(4) DO NOT mark the card DONE: it has an OPEN owner-gated/policy-deferred AC. Keep status IN_PROGRESS and add an implementation_note "deferred — DONE pending follow-up (new2 skill reconciles post-run)". STILL add the ssot-registry row for the committed code.`
-    : `(4) mark the card DONE in its YAML + add the ssot-registry row.`
+    : `(4) mark the card DONE in its YAML + add the ssot-registry row.${provLine}`
   let commitRes
   try {
     commitRes = await agentSafe(
@@ -968,7 +976,7 @@ async function integrateCrossCard() {
   try {
     await agentSafe(
       `Commit the cross-card integration fixes in worktree ${sharedCtx.worktreePath}. MECHANICAL — do NOT modify source beyond what is already changed on disk. Steps:\n` +
-        `(1) \`git status --porcelain\`; (2) stage ONLY dirty files within the batch union ${JSON.stringify(batchUnion)} — NEVER \`git add -A\`, NEVER \`git stash\`; (3) for each fully-freed card YAML [${fullyFreed.join(', ') || '(none)'}] set status to DONE and add implementation_note "cross-card integration: deferred AC resolved with batch-union ownership (new2 v4.30.0)"; (4) commit message \`[integrate] cross-card residual fixes${fullyFreed.length ? ' (' + fullyFreed.join(', ') + ')' : ''}\`; (5) 'nothing to commit' = the resolve already committed (record HEAD).\n` +
+        `(1) \`git status --porcelain\`; (2) stage ONLY dirty files within the batch union ${JSON.stringify(batchUnion)} — NEVER \`git add -A\`, NEVER \`git stash\`; (3) for each fully-freed card YAML [${fullyFreed.join(', ') || '(none)'}] set status to DONE and add implementation_note "cross-card integration: deferred AC resolved with batch-union ownership (new2 v4.30.0)"${SESSION_ID ? ' and set provenance.implementation_session: "' + SESSION_ID + '" (do NOT touch planning_session)' : ''}; (4) commit message \`[integrate] cross-card residual fixes${fullyFreed.length ? ' (' + fullyFreed.join(', ') + ')' : ''}\`; (5) 'nothing to commit' = the resolve already committed (record HEAD).\n` +
         `Return: { committed, commit, filesChanged }`,
       { label: 'integrate:commit', phase: 'Integrate', agentType: 'general-purpose', model: 'haiku',
         schema: { type: 'object', required: ['committed'], additionalProperties: true, properties: { committed: { type: 'boolean' }, commit: { type: 'string' }, filesChanged: { type: 'array', items: { type: 'string' } } } } }

package/framework/agents/card-schema.md

@@ -74,6 +74,7 @@ Legend: **R** = required, present **and non-empty** · **E** = required key, val
 | `db_indexes` | — | C | C | only if it adds a compound query |
 | `test_plan` · `integration_points` · `existing_patterns` · `anti_patterns` · `reuse_analysis` · `input_output_examples` · `error_handling` | C | C | C | populate when applicable (see `prd-card-writer.md` Required Fields) |
 | `assumptions` · `unknowns` · `notes` | C | C | C | |
+| `provenance` | C | C | C | session-id traceability — written by the SKILL, never the user; see § `provenance` below |
 
 ## Consumer contract — HALT / BACK-FILL / WARN
 
@@ -147,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
@@ -158,6 +160,42 @@ 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
+that later turns out wrong is traceable back to the chat history that planned or
+implemented it (read the transcript at `~/.claude/projects/*/<session-id>.jsonl`).
+
+```yaml
+provenance:
+  planning_session: "fd8a0411-8946-45b6-a671-c7f747ca67e6"        # /prd — the session that AUTHORED this card
+  implementation_session: "9c2e17b0-1a3d-4f88-bb20-7e0c4a9d51fe"  # /new|/new2 — the session that took it to status: DONE
+```
+
+Rules:
+- **Optional (`C`)** in every profile — legacy cards lack it and never HALT; the validator
+  ignores it. It is **never** authored by a human; the skills fill it.
+- The value is the canonical session UUID from the env var **`CLAUDE_CODE_SESSION_ID`**
+  (NOT `CLAUDE_SESSION_ID`, which does not exist). Resolve a transcript with
+  `ls ~/.claude/projects/*/<uuid>.jsonl` — the UUID is globally unique, so the project slug
+  is not needed.
+- **Ownership is split by lifecycle**: `prd-card-writer` writes `planning_session` at creation
+  (the value is **passed in by the `/prd` orchestrator** as `PLANNING_SESSION_ID` — never read
+  from inside the writer subagent, whose own session id differs). `/new` (`commit.md` Step 28)
+  and `/new2` (`new2.js` commit step) add `implementation_session` when they set `status: DONE`.
+- An **EPIC** card is a tracker, never implemented → it carries `planning_session` only, never
+  `implementation_session`.
+- Omit any sub-field whose session id is unavailable (env var unset) rather than writing a
+  placeholder.
+
 ## Writer contract
 
 The canonical writer is the `prd-card-writer` agent. It emits the full baseline for the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.71.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"