baldart 4.22.1 → 4.23.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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).

package/VERSION

@@ -1 +1 @@
-4.22.1
+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/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/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.1",
+  "version": "4.23.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"