baldart 4.22.0 → 4.23.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.23.0] - 2026-06-09
+
+**Functional Traceability Gate — no orphan UI affordances from mockups.** Handed-off mockups (Claude Design / Figma / the internal generators) routinely add interactive-looking chrome — buttons, icons, menu entries — that no requirement backed. Implementing a mockup **1:1 for fidelity** materialised that chrome into real markup + dead handlers + unused icon imports, and the cruft propagated forever. A new **unconditional** gate (independent of `features.has_design_system`) now requires every interactive or iconographic artifact to trace to a function before it becomes code: each artifact is classified **backed** (implement) / **decorative** (static-render, `aria-hidden`) / **orphan** (drop or escalate — never silent). The oracle is the PRD **UI Element Inventory `function_ref`** allowlist → card AC → orphan. Enforced at three boundaries: PRD mockup-intake (orphans become BLOCKING Discovery items), `ui-expert` implementation-time (BLOCKING pre-work), and `code-reviewer` / `/design-review` per-merge (`UI_ORPHAN_AFFORDANCE` HIGH finding). The `visual-fidelity-verifier` gains a `resolved_orphans` carve-out so a deliberately-dropped orphan is *expected-absent*, not a `component-missing` false positive. **MINOR** (additive discipline across existing UI surfaces; no new agent/skill/command and **no `baldart.config.yml` key** — the gate is registry-independent and reads its allowlist from the PRD inventory, so the schema-change propagation rule does not apply).
+
+### Added
+
+- **`framework/agents/design-system-protocol.md`** — new SSOT section **"Functional Traceability Gate (BLOCKING — unconditional)"**: the rule, the oracle hierarchy (UI Element Inventory `function_ref` → card AC → orphan), the backed/decorative/orphan classification + outcome matrix, the drop-or-escalate contract for orphans, where it runs (design / implementation / review), and the canonical `UI_ORPHAN_AFFORDANCE` finding code. The Gating section gains an explicit carve-out: this is the one part of the module **not** gated on `features.has_design_system`.
+
+### Changed
+
+- **`framework/.claude/agents/ui-expert.md`** — BLOCKING step `0b` (Functional Traceability Gate) added to "When Designing New Interfaces"; check `3b` added to "When Reviewing UI Code"; new red-flag category **Functional traceability (`UI_ORPHAN_AFFORDANCE`)**.
+- **`framework/.claude/agents/code-reviewer.md`** — new section **"Functional Traceability (MANDATORY for UI work — unconditional)"**: live affordances tracing to nothing are `UI_ORPHAN_AFFORDANCE` HIGH findings that block merge; positioned as the per-merge net behind `ui-expert`'s implementation-time gate.
+- **`framework/.claude/agents/visual-fidelity-verifier.md`** — input contract gains optional `resolved_orphans[]`; `component-missing` / `interactive-state-missing` carve-out so a dropped/decorative orphan is expected-absent rather than a fidelity finding.
+- **`framework/.claude/skills/e2e-review/SKILL.md`** — populates `resolved_orphans` in the verifier payload from the card's UI Element Inventory (`function_ref: decorative` or gate-resolved drops).
+- **`framework/.claude/skills/prd/references/discovery-phase.md`** — mockup-intake `mockup_analysis.screens[]` schema gains an `affordances[]` block (`label` / `traces_to` / `classification`); new **Affordance discipline (Functional Traceability)** making every `orphan` a BLOCKING Discovery item resolved via Scope Expansion / `/prd-add` / downgrade / drop.
+- **`framework/.claude/skills/prd/references/ui-design-phase.md`** — Step 3d gates (Full + Hybrid) now require every interactive/iconographic inventory row to carry a `function_ref` with no unresolved `orphan`.
+- **`framework/.claude/skills/prd/assets/claude-design-handoff-prompt.template.md`** — § 3 gains a functional-traceability constraint (only ship controls tied to a listed function; mark decorative explicitly); § 7 gains a per-element traceability map + orphan-to-decide list requirement.
+- **`framework/.claude/skills/ui-design/references/inventory.md`** — UI Element Inventory table gains a **Function ref** column + the rule binding it to the gate.
+- **`framework/.claude/commands/design-review.md`** — new step 6 (Functional Traceability check) emitting `UI_ORPHAN_AFFORDANCE` HIGH→major findings.
+
+## [4.22.1] - 2026-06-09
+
+**Epic-parent closure at end of `/new` + `/new2`.** When the last child of an epic is implemented, the epic/parent card now gets marked `DONE` automatically instead of being left stuck at `TODO`. The Phase 6b post-merge reconciliation gate only ever touched the **batch cards** (the children); the epic/parent card (`group.is_epic: true`) is excluded from the batch by the epic guard, so it never got reconciled — final-review only *reported* "all children done" without writing the epic's own status. **PATCH** (strengthens the existing Phase 6b reconciliation gate; no new agent/skill/command/config key — `/new2` inherits it because its merge agent follows `merge-cleanup.md` as SSOT).
+
+### Changed
+
+- **`framework/.claude/skills/new/references/merge-cleanup.md`** — Phase 6b gains **step 5e (Epic-parent closure)**: for each distinct `group.parent` of the batch (plus any epic card in the batch itself), if **every** child is `DONE` (checked across the whole backlog, not just the batch subset), force-update the epic card to `status: DONE` + `completed_date` + note, folded into the same reconciliation commit. Leaves the epic untouched if any child is still open. The step-6 tracker block now records `Epics closed: …`.
+- **`framework/.claude/skills/new/references/final-review.md`** — the "all cards in the epic are DONE" Next-Steps message now states the epic card itself is marked `DONE` (by Phase 6b step 5e), with a note that a still-`TODO` epic under all-DONE children is a Phase 6b failure to flag.
+- **`framework/.claude/workflows/new2.js`** — the merge agent's deterministic policies gain an explicit **EPIC CLOSURE** rule (all-children-DONE gate, distinct from the F-029 forced-DONE prohibition since the epic is a tracker), `MERGE_SCHEMA` gains `epicsClosed[]`, and a new `epic-closure` ledger entry records which epics were closed.
+
 ## [4.22.0] - 2026-06-09
 
 **`/prd` Obsidian back-reference.** When a PRD is kicked off from an Obsidian note (the documental starting point), the same note now receives, at the end of the run, an idempotent snippet indexing how the feature was developed and where it landed — PRD path, epic + card IDs, branch, merge commit/PR, and the PRD's Canonical Sources — so the user can later query the note ("come è stata sviluppata la feature X, dov'è finita"). **MINOR** (additive capability on the `prd` skill; no new `baldart.config.yml` key — the note path is runtime-detected and state-persisted, so the schema-change propagation rule does not apply).

package/VERSION

@@ -1 +1 @@
-4.22.0
+4.23.0

package/framework/.claude/agents/code-reviewer.md

@@ -90,6 +90,28 @@ When `features.has_design_system: false`, the registry reads are skipped but
 the review still flags hardcoded values and inconsistencies against
 `${paths.ui_guidelines}`, and recommends `/design-system-init` in the report.
 
+## Functional Traceability (MANDATORY for UI work — unconditional)
+
+Independent of `features.has_design_system`. For any diff that introduces UI
+affordances, enforce the gate defined in
+[`design-system-protocol.md`](../../agents/design-system-protocol.md)
+§ "Functional Traceability Gate":
+
+1. For every interactive or iconographic artifact added by the diff (button,
+   link, menu item, tab, toggle, input, icon, badge, status dot), verify it
+   traces to a function — a PRD UI Element Inventory `function_ref`, a card AC,
+   or a real handler/endpoint reached by the code.
+2. A live affordance that traces to nothing is a **`UI_ORPHAN_AFFORDANCE`** HIGH
+   finding: dead/stub `onClick`, button with no effect, unused icon import kept
+   only to mirror a mockup, menu entry routing nowhere. It ships dead code and
+   breaks the minimalism contract — block merge.
+3. The fix is always one of: wire the real behaviour (requires an AC — flag for
+   `/prd-add` or a follow-up card), render it static/`aria-hidden` decorative,
+   or drop it. "Leave it, it matches the mockup" is never acceptable.
+
+This is the per-merge net behind `ui-expert`'s own implementation-time gate; if
+it trips here, the upstream gate was skipped — flag that alongside the finding.
+
 ## Scope Boundary (MUST — read first)
 
 Your review scope is STRICTLY limited to **changed files only**.

package/framework/.claude/agents/ui-expert.md

@@ -255,6 +255,13 @@ project context layer at invocation time:
    AND tokens-reference (no hardcoded hex/shadow/radius when
    `has_design_system: true`)
 3. Evaluate minimalism: unnecessary controls, button placement, cognitive load
+3b. **Functional Traceability check** (unconditional) — for every interactive /
+   iconographic artifact in the diff, verify it traces to a function (inventory
+   `function_ref`, an AC, or a real handler/endpoint). A live affordance that
+   does nothing (dead `onClick`, unused icon import, button with no effect) is a
+   `UI_ORPHAN_AFFORDANCE` HIGH finding per
+   [`design-system-protocol.md`](../../agents/design-system-protocol.md)
+   § "Functional Traceability Gate".
 4. **Small screen audit**: verify touch targets (44x44px min), layout at 320px, text scaling to 200%
 5. Check brand theming: color application, CSS variable usage
 6. Verify separation of concerns: presentation vs. logic boundaries
@@ -275,6 +282,16 @@ project context layer at invocation time:
 ### When Designing New Interfaces
 0. **BLOCKING pre-work** — execute the registry-first cascade above
    (`design-system-protocol.md`).
+0b. **BLOCKING — Functional Traceability Gate** (runs regardless of
+   `has_design_system`). When implementing from a mockup (your own or one handed
+   off from `/prd` / Claude Design / Figma), build the list of interactive +
+   iconographic artifacts and classify each against the oracle (PRD UI Element
+   Inventory `function_ref` → card AC → orphan) per
+   [`design-system-protocol.md`](../../agents/design-system-protocol.md)
+   § "Functional Traceability Gate". Resolve every orphan **before** writing
+   code — drop it, render it static-only (no stub handler, no dead icon import),
+   or escalate via `AskUserQuestion` (one per orphan). Never implement an
+   unrequested affordance "to stay 1:1 with the mockup".
 1. **Component Discovery cascade** — for every visual element the task
    introduces or touches, walk: `${paths.design_system}/INDEX.md` →
    `${paths.components_primitives}/*` → external catalog (shadcn / 21st.dev /
@@ -377,6 +394,16 @@ Use the Task tool to launch the `motion-expert` agent with a clear brief:
 - Controls that serve edge cases but clutter the main flow
 - Inconsistent terminology in UI labels
 
+### Functional traceability (`UI_ORPHAN_AFFORDANCE`)
+- An interactive artifact (button, link, menu item, toggle, tab) wired to a
+  dead/empty/stub handler — it looks actionable but does nothing
+- An icon import kept solely to mirror the mockup, with no semantic or
+  functional role (should be dropped or `aria-hidden` decorative)
+- A mockup affordance implemented 1:1 with no backing AC / inventory
+  `function_ref` — implement only what traces to a function; drop or
+  static-render the rest (see `design-system-protocol.md`
+  § "Functional Traceability Gate")
+
 ### Architecture & separation of concerns
 - Business logic embedded in component render functions
 - Hardcoded colors instead of theme variables in branded pages

package/framework/.claude/agents/visual-fidelity-verifier.md

@@ -64,13 +64,25 @@ The orchestrator (`/e2e-review`) invokes you with this JSON payload:
     "components_in_scope": ["Button","Card"]      // present for compliance-only
   },
   "tolerance": "strict" | "balanced" | "lenient",
-  "fix_hints_enabled": true
+  "fix_hints_enabled": true,
+  "resolved_orphans": [                              // optional — Functional Traceability Gate
+    "Export CSV button", "bell icon"                 // mockup affordances deliberately dropped or
+  ]                                                  // downgraded to decorative; absence is EXPECTED
 }
 ```
 
 If `mockup_source.level == "skip"`, return immediately with
 `{ "status": "skipped", "reason": "no_mockup_available", "findings": [] }`.
 
+**`resolved_orphans` carve-out (Functional Traceability Gate).** The mockup is a
+fidelity target, not a requirements oracle: it may contain interactive chrome that
+no requirement backed, which the implementer correctly **dropped or rendered
+static**. Any element matching an entry in `resolved_orphans` that is absent (or
+inert) in the rendered output is **EXPECTED — never a `component-missing` or
+`interactive-state-missing` finding**. Treat the list as authoritative over the
+raw mockup. See `framework/agents/design-system-protocol.md` § "Functional
+Traceability Gate".
+
 ## Severity Taxonomy (CANONICAL — cite verbatim)
 
 This taxonomy is the SSOT consumed by `/e2e-review` and `/design-review`. Do
@@ -83,7 +95,7 @@ not invent new severity levels. Do not move categories across tiers.
 | `layout-break` | Flexbox/grid container collapsed, elements stacked when designed side-by-side, vertical rhythm broken |
 | `element-order` | DOM/visual order differs from mockup (Button placed before Title when designed after) |
 | `responsiveness-break` | Breakpoint missing — desktop layout served on 320–375px viewport, horizontal scroll on mobile |
-| `component-missing` | Designed component absent from rendered output (e.g. mockup has a CTA card, screen does not) |
+| `component-missing` | Designed component absent from rendered output (e.g. mockup has a CTA card, screen does not). **Exception:** an element listed in `resolved_orphans` is expected-absent — do NOT flag it. |
 | `component-duplicated` | Same primitive rendered twice when designed once (e.g. accidental React key collision) |
 | `unreachable-action` | Primary CTA off-screen / behind fixed overlay / unreachable by thumb on mobile |
 

package/framework/.claude/commands/design-review.md

@@ -117,6 +117,7 @@ When the user invokes `/design-review`, do the following (in both modes — only
 5. **Design-System Conformance section** — primitives reused, primitives reinvented (HIGH→major), tokens bypassed (HIGH→major), spec drift (MEDIUM→minor), new primitives proposed.
    - **Mode A**: include as a top-level section in the Markdown report per `agents/design-review.md` § Report Template.
    - **Mode B**: emit as `findings[]` entries with the appropriate categories from the taxonomy above, and populate `ds_drift_codes[]` with the deduplicated set.
+6. **Functional Traceability check** (unconditional — independent of `has_design_system`) — flag every interactive or iconographic affordance on the route that traces to no function (dead/stub handler, button with no effect, unused icon, menu entry routing nowhere) as a `UI_ORPHAN_AFFORDANCE` HIGH→major finding, per `framework/agents/design-system-protocol.md` § "Functional Traceability Gate". The fix is wire-it / static-render / drop — never "matches the mockup".
 
 ## Mode-detection contract (avoid silent misdetection)
 

package/framework/.claude/skills/e2e-review/SKILL.md

@@ -351,9 +351,16 @@ For each `route` in `plan.routes[]`:
        "implementation_screenshot_path": ".baldart/e2e-review/FEAT-XXXX/screenshots/merchant-dashboard.png",
        "mockup_source": { ... },
        "tolerance": "<from config>",
-       "fix_hints_enabled": true
+       "fix_hints_enabled": true,
+       "resolved_orphans": [ "<mockup affordances dropped / downgraded to decorative>" ]
      }
    ```
+   Populate `resolved_orphans` from the card's UI Element Inventory: any
+   interactive/iconographic row whose `function_ref` is `decorative` or that was
+   resolved as dropped by the Functional Traceability Gate. This prevents the
+   verifier from flagging a deliberately-removed orphan affordance as
+   `component-missing`. Omit the field (or pass `[]`) when the inventory has no
+   resolved orphans.
 3. **Parse the agent's JSON response** strictly. If the response is malformed
    or contains prose outside the JSON, log
    `verifier_protocol_violation` in `gaps[]` and treat the route's findings

package/framework/.claude/skills/new/references/final-review.md

@@ -303,10 +303,16 @@ deterministic script outside this orchestrator's context window.
    ```
    ## Prossimi Passi
 
-   Tutte le card dell'epic **FEAT-XXXX** sono state completate.
+   Tutte le card dell'epic **FEAT-XXXX** sono state completate, e la card epic stessa è
+   stata marcata `DONE` (chiusura automatica in Phase 6b, step 5e).
    Pronto per il deploy: `/deploy` o `git push origin <trunk branch>` (il `git.trunk_branch` configurato)
    ```
 
+   > Nota: la chiusura della card epic è eseguita dal gate Phase 6b (epic-parent closure),
+   > non da questo step di reporting — qui la si riporta soltanto. Se l'epic risultasse
+   > ancora `TODO`/`IN_PROGRESS` mentre tutti i figli sono `DONE`, è un fallimento di
+   > Phase 6b step 5e da segnalare in `## Issues & Flags`.
+
 5. **Proceed to Phase 7** (production readiness checklist).
 
 ---

package/framework/.claude/skills/new/references/merge-cleanup.md

@@ -74,12 +74,39 @@ The most common failure mode is leaving cards IN_PROGRESS after merge. This crea
       - If doc-freshness requires ssot-registry.md → update its `last_verified_from_code` date, stage it, and retry.
       - If COMMIT_LOCK → re-run step 5a and retry.
       - Do NOT retry more than 2 times. Log the failure and move on.
+5e. **Epic-parent closure (MANDATORY — the epic card is NOT in the batch)**: the batch
+   implements children; the epic/parent card (`group.is_epic: true`, id usually ending
+   `-00` / filename `*-epic.yml` / `review_profile: skip`) is never implemented and is
+   excluded from the per-card loop in step 2 — so it stays at its old status (almost
+   always `TODO`) even when its **last** child just went DONE. Close it here, deterministically:
+
+   For each **distinct parent epic** referenced by the batch — the set of `group.parent`
+   values across the batch cards, PLUS any card in the batch that is itself an epic
+   (`group.is_epic: true`) — do:
+   a. Read the epic parent card `${paths.backlog_dir}/<EPIC-ID>.yml`. If `status: DONE`
+      already → skip (idempotent).
+   b. Check that **every** child is DONE (not just the batch's subset — children
+      implemented in earlier sessions count too):
+      ```bash
+      # Lists children of <EPIC-ID> that are NOT yet DONE. Empty output ⇒ all DONE.
+      grep -l "parent: <EPIC-ID>" ${paths.backlog_dir}/*.yml | xargs grep -L "status: DONE"
+      ```
+   c. **Only if** that command prints nothing (all children DONE) → force-update the epic
+      parent: set `status: DONE`, add `completed_date: <today>`, add note
+      `"Marked DONE by epic-closure gate (Phase 6b) — all children DONE"`. Stage it and
+      **fold into the SAME reconciliation commit** as step 5 (or, if step 5 didn't run
+      because all children were already DONE, make a dedicated
+      `[BATCH] Close epic <EPIC-ID> — all children DONE` commit, honoring the same
+      COMMIT_LOCK / doc-freshness precautions as step 5a–5d).
+   d. **If any child is still open** → leave the epic untouched: it is genuinely still in
+      progress, and step-4b's "Card rimanenti nell'epic" table already reports the gap.
 6. **Update tracker** with reconciliation results:
    ```
    ## Phase 6b — Status Reconciliation
    Cards checked: N
    Already DONE: M
    Force-updated to DONE: K [list card IDs]
+   Epics closed: J [list epic IDs] (or "none — children still open" / "n/a — no epic in batch")
    Reconciliation commit: <hash> (or "not needed")
    ```
 7. **HALT condition**: if a card cannot be updated (e.g., file read error, YAML parse error), log it in `## Issues & Flags` and continue with the remaining cards. Report the failure in the final summary.

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

@@ -34,6 +34,15 @@
 
 ## 3. Schermate in scope
 
+> **Vincolo di tracciabilità funzionale.** Inserisci SOLO controlli (bottoni,
+> icone-azione, voci di menu, tab, toggle) legati a una funzione elencata qui
+> sotto. Non aggiungere chrome interattivo "per completezza visiva": ogni
+> affordance senza funzione diventa codice morto in implementazione. Se proponi
+> un elemento interattivo non presente nelle azioni primarie, segnalalo in
+> consegna come *proposta da validare*, non come requisito. Gli elementi
+> puramente decorativi (icone di sezione, marchi) marcali esplicitamente come
+> **decorativi**.
+
 {{#each screens_in_scope}}
 ### {{this.name}}
 
@@ -108,7 +117,14 @@ Per ogni schermata elencata in § 3:
 
 1. **PNG export** ad alta risoluzione (≥ 2x) di OGNI stato richiesto (es. `lista-ordini__empty.png`, `lista-ordini__populated.png`).
 2. {{output_format_preference_block}}  <!-- "Codice HTML/CSS in un file unico" | "Codice React (.tsx) con import Tailwind" | "Link Figma alla frame" -->
-3. **Note inline** su:
+3. **Mappa di tracciabilità** — per OGNI elemento interattivo o iconografico
+   della schermata, una riga: `elemento → funzione che lo motiva` (l'azione
+   primaria / il dato di § 3 che serve), oppure marcalo **decorativo** se non ha
+   comportamento. Qualunque elemento che non riesci a tracciare a una funzione,
+   elencalo separatamente come *orphan da decidere* — così posso scegliere se
+   dargli una funzione, renderlo decorativo o rimuoverlo, invece di
+   implementarlo a vuoto.
+4. **Note inline** su:
    - Componenti nuovi (non presenti nel registry sopra) che hai introdotto e perché.
    - Token deviation: qualunque colore/spacing/radius fuori dalla palette sopra, con motivazione.
    - Decisioni di layout non ovvie (es. priority sort, hierarchy visiva, density).

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

@@ -1095,6 +1095,10 @@ 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>
+      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]
       copy_excerpts:
         - <verbatim text visible in the mockup, max ~10 strings per screen>
@@ -1122,3 +1126,25 @@ mockup_analysis:
 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.
+
+**Affordance discipline (Functional Traceability):** classify every interactive
+or iconographic artifact the mockup shows. The mockup is a fidelity target, not
+a requirements oracle — handed-off designs (Claude Design / Figma) routinely add
+buttons, icons, and menu entries no requirement asked for, and implementing them
+1:1 ships dead code. So:
+- `backed` — the artifact serves a user story / AC already in scope. Record
+  `traces_to`.
+- `decorative` — legitimately present but carries no behaviour (section icon,
+  brand mark). It will render static/`aria-hidden` at implementation, never as a
+  live control.
+- `orphan` — interactive-looking but traces to nothing in scope. Each orphan is
+  a **BLOCKING Discovery item**: ask the user (one per turn, like a gap) whether
+  it should (a) gain a real function → routes through the Scope Expansion Check /
+  `/prd-add`, (b) be downgraded to decorative, or (c) be dropped from the design.
+  Never carry an unresolved `orphan` past Discovery — it would silently become
+  dead UI. Record the resolution in the Discovery Log.
+
+This classification is the seed of the UI Element Inventory `function_ref`
+column (Step 3d) — the allowlist `ui-expert` and `code-reviewer` enforce at
+implementation/review via the Functional Traceability Gate
+(`framework/agents/design-system-protocol.md`).

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

@@ -157,7 +157,10 @@ This prevents designing new components when 450+ reusable ones already exist.
   **STOP.** Wait for user to choose.
 - **After Step 3c:** explicit user approval ("confermo", "va bene", "ok").
 - **After Step 3d:** `${paths.prd_dir}/<slug>/design.html` exists (inside `$WORKTREE_PATH`) AND `## UI Element Inventory`
-  is populated in the state file with at least 3 elements.
+  is populated in the state file with at least 3 elements, AND every interactive
+  or iconographic row carries a `function_ref` (an US/AC/endpoint or `decorative`) —
+  no unresolved `orphan` (Functional Traceability Gate, see
+  `framework/agents/design-system-protocol.md`).
 - **After Step 3e (BLOCKING when `features.has_design_system: true`):** ui-design Step H
   (Post-Intervention Coherence Check) must complete with no unresolved `DS_INDEX_DRIFT` /
   `DS_COMPONENT_STALE` / `DS_TOKENS_DRIFT` findings (or every finding explicitly waived
@@ -252,7 +255,9 @@ to the design system, approve, and inventory. Generate ONLY the screens not cove
   `design_system_alignment.violations[]` is either resolved (token/component
   swapped in the inventory) or explicitly waived by the user (logged as such).
 - **After 3d:** UI Element Inventory populated with at least one row per screen in
-  `screens_in_scope[]`. `design.html_path` set OR `mockup-only` flag recorded.
+  `screens_in_scope[]`, every interactive/iconographic row carrying a `function_ref`
+  (no unresolved `orphan` — Functional Traceability Gate).
+  `design.html_path` set OR `mockup-only` flag recorded.
 - **After 3e — Registry Coherence (BLOCKING when `features.has_design_system: true`):**
   ui-design Step H (Post-Intervention Coherence Check) must complete with no
   unresolved `DS_INDEX_DRIFT` / `DS_COMPONENT_STALE` / `DS_TOKENS_DRIFT` findings

package/framework/.claude/skills/ui-design/references/inventory.md

@@ -24,10 +24,10 @@ Aggiungi al state file del PRD sotto `## UI Element Inventory`:
 
 Source: ${paths.prd_dir}/<slug>/design.html (option <X>, approved <date>)
 
-| # | Element | Type | Purpose | Inputs/Outputs | Behavior |
-|---|---------|------|---------|----------------|----------|
-| 1 | <name>  | page / section / component / modal / form / button / endpoint | <what it does> | <fields, props, API params> | <interactions, states, validation> |
-| 2 | ...     | ...  | ...     | ...            | ...      |
+| # | Element | Type | Purpose | Inputs/Outputs | Behavior | Function ref |
+|---|---------|------|---------|----------------|----------|--------------|
+| 1 | <name>  | page / section / component / modal / form / button / endpoint | <what it does> | <fields, props, API params> | <interactions, states, validation> | <US-id / AC-id / endpoint — or `decorative`> |
+| 2 | ...     | ...  | ...     | ...            | ...      | ...          |
 
 ### New components to create
 - <ComponentName> — <purpose> (NOT existing in codebase)
@@ -45,6 +45,16 @@ Source: ${paths.prd_dir}/<slug>/design.html (option <X>, approved <date>)
 - Sii specifico: "Save button that calls POST /api/v1/foo/bar" non "a button" (cita l'endpoint reale).
 - Includi error states, loading states, e empty states visibili nel design.
 - Distingui chiaramente tra componenti da creare e componenti da riusare.
+- **Function ref (Functional Traceability):** ogni riga interattiva o iconografica
+  DEVE citare la funzione che la giustifica — uno US-id, un AC-id, o l'endpoint
+  reale che invoca. Un elemento puramente visivo si marca `decorative` (verrà reso
+  statico/`aria-hidden`, mai come controllo vivo). Se un artefatto del design non
+  traccia a nulla ed è interattivo (un **orphan**), NON inventargli uno scopo:
+  era un orphan già emerso nell'intake del mockup (Discovery) e va risolto lì
+  (funzione reale via `/prd-add`, downgrade a `decorative`, o rimozione dal design)
+  prima di scrivere l'inventario. Questa colonna è l'allowlist che `ui-expert` e
+  `code-reviewer` fanno rispettare con il Functional Traceability Gate
+  (`framework/agents/design-system-protocol.md`).
 
 ## Cosa NON includere
 

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

@@ -163,6 +163,7 @@ const MERGE_SCHEMA = {
     mergeTs: { type: 'string' },
     reconciliation: { type: 'string' },
     forcedDone: { type: 'array', items: { type: 'string' }, description: 'MUST be empty — false-DONE is forbidden (F-029)' },
+    epicsClosed: { type: 'array', items: { type: 'string' }, description: 'Epic/parent cards marked DONE by Phase 6b step 5e (all children DONE) — NOT a forcedDone violation' },
     uncommittedLeft: { type: 'boolean', description: 'true if dirty code was left (NOT committed) + reported (F-030)' },
     note: { type: 'string' },
   },
@@ -634,6 +635,7 @@ if (!committed.length) {
         `• G24 → auto-merge via merge_strategy.\n` +
         `• F-030 HARD RULE: NEVER \`git add\`/commit code that did not pass the per-card gates. If the worktree is dirty with uncommitted code → DO NOT commit it; leave it, set uncommittedLeft:true, and report. NO "safety commit". Security/migration code is NEVER swept in.\n` +
         `• F-029 HARD RULE: Phase 6b reconciliation marks a card DONE ONLY if it has a real commit in ${TRUNK}..HEAD AND its gates are green. NEVER force a non-implemented card to DONE. Return forcedDone:[] (must be empty).\n` +
+        `• EPIC CLOSURE (Phase 6b step 5e): the epic/parent card (group.is_epic:true) is NOT in the batch and stays TODO unless closed here. For each distinct group.parent of the batch cards (and any epic card in the batch itself): if EVERY child of that epic — \`grep -l "parent: <EPIC-ID>" backlog/*.yml | xargs grep -L "status: DONE"\` prints nothing — set the epic card status:DONE + completed_date + note "epic-closure gate — all children DONE" and fold into the reconciliation commit. If any child is still open → leave the epic untouched. This is NOT a forcedDone violation (the epic is a tracker, gated on all-children-DONE, not on its own commit). Return epicsClosed:[<EPIC-IDs marked DONE>].\n` +
         `• G19 sync-deferred → HEAD==${TRUNK} ff-pull, else leave+report. G20 → leave+report. G21 post-batch dirty → partition-ignore framework artifacts; leave the rest + report (do NOT commit). G22 divergence → behind: ff-pull; ahead/both: leave+report; NEVER reset --hard/force-push. G23 stash restore conflict → leave intact + report.\n\n` +
         `Return: { merged, mergeCommit, mergeTs, reconciliation, forcedDone:[], uncommittedLeft, note }`,
       { label: 'merge', phase: 'Merge', agentType: 'general-purpose', schema: MERGE_SCHEMA }
@@ -641,6 +643,7 @@ if (!committed.length) {
   } catch (e) { if (e && e.transientExhausted) noteDegraded('outage'); mergeResult = null }
   if (mergeResult && (mergeResult.forcedDone || []).length) { noteDegraded('false_done'); ledger(firstCard, 'F029-guard', 'VIOLATION', `forcedDone: ${mergeResult.forcedDone.join(' ')}`) }
   if (mergeResult && mergeResult.uncommittedLeft) ledger(firstCard, 'F030-guard', 'LEFT-UNCOMMITTED', 'dirty code left (not swept) + reported')
+  if (mergeResult && (mergeResult.epicsClosed || []).length) ledger(firstCard, 'epic-closure', 'CLOSED', `epics marked DONE (all children DONE): ${mergeResult.epicsClosed.join(' ')}`)
   ledger(firstCard, 'G24-merge', (mergeResult && mergeResult.merged) ? 'MERGED' : 'INCOMPLETE', (mergeResult && (mergeResult.mergeCommit || mergeResult.note)) || '')
   if (mergeResult && mergeResult.reconciliation) ledger(firstCard, 'G19-23-reconcile', 'AUTO', mergeResult.reconciliation)
 }

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

@@ -36,6 +36,12 @@ in step 1 below are SKIPPED — agents/skills still respect
 When the flag is `true`, the registry reads are **BLOCKING**: skipping them is
 a protocol violation and the agent must refuse to proceed.
 
+**One exception — the Functional Traceability Gate is unconditional.** The
+gate defined in § "Functional Traceability Gate" below is the only part of this
+module that is **not** gated on `features.has_design_system`. It concerns
+*function provenance* (does each artifact in a mockup do something?), not the
+visual registry, so it applies to every UI surface — design-system or not.
+
 To bootstrap a registry on a project that does not yet have one, invoke the
 `design-system-init` skill (`/design-system-init`).
 
@@ -259,6 +265,86 @@ agent has two choices:
 Never silently introduce a new component that overlaps with an existing
 registry primitive — that is the exact failure mode this protocol prevents.
 
+## Functional Traceability Gate (BLOCKING — unconditional)
+
+A mockup is a fidelity target, **not** a requirements oracle. Design tools
+(Claude Design, Figma, the `ui-design`/`frontend-design` generators) routinely
+add interactive-looking chrome — buttons, icons, menu entries, toggles, badges —
+that no requirement asked for. Implementing a mockup **1:1 for fidelity**
+materialises that chrome into real markup + dead handlers + unused icon imports,
+and the cruft then propagates forever. This gate stops it at the boundary where
+the leak happens: **before** any artifact becomes code.
+
+**Gating: unconditional.** Unlike the registry cascade above, this gate runs on
+every UI surface regardless of `features.has_design_system`. It is about whether
+each artifact *does something*, not about tokens or the registry.
+
+### The rule
+
+> No interactive or iconographic artifact is implemented unless it traces to a
+> function. Orphans are resolved — never implemented "to stay faithful to the
+> mockup".
+
+"Interactive or iconographic artifact" = any element a user could plausibly
+expect to act on or read as a signal: buttons, links, menu items, tabs,
+toggles, inputs, icons, badges, status dots, action affordances. Pure layout
+and decorative-by-construction visuals (spacers, dividers, background art,
+hero illustrations) are out of scope — they carry no implied behaviour.
+
+### The oracle (where "a function" comes from), in order
+
+1. **PRD UI Element Inventory** — the `function_ref` column (added by `/prd`
+   Step 3d / the `ui-design` inventory). When present, this is the authoritative
+   allowlist: each row names the AC / user story / handler / endpoint it serves,
+   or is explicitly marked `decorative`.
+2. **Backlog card spec / acceptance criteria** — when no inventory row exists,
+   the artifact must map to an AC or an explicit behaviour in the card.
+3. **Neither** — the artifact is an **orphan**. Do not guess a purpose for it.
+
+### Classification + outcome (per artifact)
+
+| Classification | Definition | Outcome |
+|---|---|---|
+| **Backed** | Traces to an inventory `function_ref`, an AC, or a real handler/endpoint | **Implement** — wire the real behaviour |
+| **Decorative** | Legitimately present but carries no behaviour (e.g. a section icon, a brand mark) | **Static-only** — render it inert: no `onClick`, no stub handler, no route, no disabled-button placeholder. If it imports an icon purely for decoration, keep it minimal and labelled `aria-hidden` |
+| **Orphan** | Interactive-looking, traces to nothing, not deliberately decorative | **Drop or escalate** — see below |
+
+For every **orphan**, never decide silently (consistent with the framework's
+`always-ask, never-assume` and "no silent AC deferral" contracts):
+
+- **Drop** when the artifact is clearly unrequested chrome and removing it does
+  not change any in-scope flow — the default for obvious leftover decoration
+  rendered as a button.
+- **Escalate** (one `AskUserQuestion` per orphan, or a single grouped report
+  when run inside an autonomous workflow) when it is plausible the artifact
+  *should* have a function that was simply never specified — i.e. dropping it
+  might silently discard intended scope. The three offered resolutions are:
+  *implement (needs an AC → routes to `/prd-add` or a follow-up card)*,
+  *static-only*, or *drop*.
+
+### Where it runs
+
+1. **Design / generation time** (`ui-design`, `frontend-design`, `ui-expert`
+   designing) — when producing a mockup, do not invent interactive chrome with
+   no backing requirement; mark genuinely decorative elements as such in the
+   inventory so the downstream gate is deterministic, not a guess.
+2. **Implementation time** (`ui-expert` implementing) — **BLOCKING pre-work**:
+   build the artifact list from the mockup, classify each row against the oracle,
+   and resolve every orphan (drop / static-only / escalate) **before** writing
+   code. Implementing an orphan as a live affordance is the exact failure mode
+   this gate prevents.
+3. **Review time** (`code-reviewer`, `/design-review`) — verify the shipped diff
+   introduces no live affordance that traces to nothing. Each one is a
+   `UI_ORPHAN_AFFORDANCE` HIGH finding (dead handler / unused icon import / button
+   with no effect).
+
+### Finding code
+
+`UI_ORPHAN_AFFORDANCE` — an interactive or iconographic artifact that was
+implemented (or is about to be) without a traceable function. HIGH severity:
+it ships dead code and erodes the minimalism contract. The fix is always one of
+the three outcomes above, never "leave it, it matches the mockup".
+
 ## Post-Intervention Coherence Check (BLOCKING completion gate)
 
 The BLOCKING pre-work above enforces *reads* before any UI change. This
@@ -351,6 +437,18 @@ The following files reference this module instead of duplicating its rules:
 - `framework/.claude/commands/design-review.md`
 - `framework/agents/design-review.md`
 
+Additional consumers of the **Functional Traceability Gate** specifically
+(unconditional, registry-independent):
+
+- `framework/.claude/agents/visual-fidelity-verifier.md` (`resolved_orphans`
+  carve-out — a dropped orphan is expected-absent, not `component-missing`)
+- `framework/.claude/skills/e2e-review/SKILL.md` (passes `resolved_orphans`)
+- `framework/.claude/skills/prd/references/discovery-phase.md` (mockup-intake
+  affordance classification — the oracle's origin)
+- `framework/.claude/skills/prd/references/ui-design-phase.md` +
+  `framework/.claude/skills/ui-design/references/inventory.md` (the
+  `function_ref` allowlist the gate enforces)
+
 When changing the BLOCKING cascade, change it here — not in the consumers.
 
 ## See also

package/package.json

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