baldart 4.22.1 → 4.24.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.24.0] - 2026-06-10
+
+**Atomic backlog-ID allocator — no FEAT/BUG collisions across parallel worktrees.** When several `/prd` (or `/new`/`new2` follow-up) sessions run in parallel on sibling worktrees, each branched from the same trunk, the old `max(^id: FEAT-) + 1` scan made them all land on the **same next integer**: the other session's card was in flight on an unmerged sibling branch, invisible to both the local backlog and the trunk merge-base — so two epics both became `FEAT-0024` and conflicted at rebase/merge. The `git fetch` + merge-base scan only ever covered *already-merged* IDs, never in-flight ones. A new allocator anchors a lock + per-prefix high-water mark in `$MAIN/.worktrees/` (the shared coordination point every worktree already reaches via `git rev-parse --git-common-dir`, gitignored like `registry.json`), so a reservation is atomic across every worktree **on the same machine**. The high-water mark bumped under the lock is the correctness anchor; `max()` against the real backlog + sibling-worktree backlogs + reservations log + trunk merge-base makes it **self-healing**. **MINOR** (additive capability on the `worktree-manager` skill; opt-in — callers fall back to the inline merge-base scan + `[ID-RACE-RISK]` note when the script is absent, so older installs and cross-machine cloud agents are unaffected. **No `baldart.config.yml` key** — the allocator reuses `paths.backlog_dir` + the gitignored `.worktrees/` convention, so the schema-change propagation rule does not apply).
+
+### Added
+
+- **`framework/.claude/skills/worktree-manager/scripts/allocate-id.sh`** — prefix-parametric (`FEAT`/`BUG`/`UI`/`DOC`/`PERF`/…) atomic ID allocator. `reserve <PREFIX> <slug>` prints the next free integer zero-padded to 4 digits; `release <worktree-path>` prunes a finished worktree's reservations. Cross-process mutex via atomic `mkdir` (stale-stolen after 30s via the lock dir's own mtime — a directory, not a git ref, so it never touches the shared `refs/stash` that `git stash` in worktrees is forbidden over). The slow `git fetch` runs **before** the lock, keeping the critical section local-FS-only (sub-second). Reads `paths.backlog_dir` + `git.trunk_branch` from `baldart.config.yml` and resolves `$MAIN` at runtime — no hardcoded project facts (passes the framework-edit-gate). Same-machine scope; the trunk merge-base scan is the best-effort cross-machine guard.
+
+### Changed
+
+- **`framework/.claude/skills/worktree-manager/SKILL.md`** — new section **"ID Allocation"** documenting the allocator, the shared `.id-alloc.lock/` / `.id-hwm-<PREFIX>` / `id-reservations.jsonl` files, the same-machine scope + opt-in fallback contract, and the gap-tolerant monotonic-counter design. `release` is wired into the cleanup paths of `/mw` (step 7), `mw-docs` (step 6), and `/cw` (step 4).
+- **`framework/.claude/agents/prd-card-writer.md`** — § "FEAT-XXXX numbering" + Pre-Generation Checklist item 1 now reserve the integer via the allocator (primary path), with the trunk fetch + merge-base scan + `[ID-RACE-RISK]` note as the documented fallback when the script is absent. Applies to any prefix the writer mints.
+- **`framework/.claude/agents/prd.md`** — § 4.1 NAMING CONVENTIONS prefers the allocator (any prefix) over the plain backlog scan, with the same documented fallback.
+
+## [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.24.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/prd-card-writer.md

@@ -300,18 +300,36 @@ applies even when N=1.
 
 ### FEAT-XXXX numbering
 
-- Pick the next free `FEAT-XXXX` integer (Grep `^id: FEAT-` in `${paths.backlog_dir}/`, find max,
-  add 1). **Reserve the entire integer for this epic** — do NOT reuse the integer
-  for unrelated cards even if it has fewer than ~99 children.
-- **Scan the canonical backlog, not just the worktree branch.** The worktree
-  branched from the trunk may not contain IDs committed on sibling branches not
-  yet merged. Before computing max, run
-  `git fetch <git.trunk_branch>` and grep `${paths.backlog_dir}/` on the merge-base of the
-  trunk (`git grep '^id: FEAT-' $(git merge-base HEAD <git.trunk_branch>)` plus
-  the local worktree) so concurrent PRD sessions don't both land on the same
-  "next free" integer. If a `git fetch` is not possible (offline), state the
-  reservation is best-effort against the local view and surface a
-  `[ID-RACE-RISK]` note so the caller can re-verify before commit.
+- Pick the next free `FEAT-XXXX` integer. **Reserve the entire integer for this
+  epic** — do NOT reuse the integer for unrelated cards even if it has fewer than
+  ~99 children.
+- **Use the atomic allocator when present (primary path).** Plain `max + 1` is
+  unsafe under parallelism: concurrent PRD sessions on sibling worktrees, all
+  branched from the same trunk, see the same max (the other session's card is in
+  flight on an unmerged branch) and both pick the same integer → merge conflict.
+  The `worktree-manager` allocator reserves the integer atomically across every
+  worktree on this machine (lock + shared high-water mark under `.worktrees/`):
+
+  ```bash
+  # $MAIN is the main repo root: dirname of `git rev-parse --git-common-dir`.
+  ALLOC="$MAIN/.claude/skills/worktree-manager/scripts/allocate-id.sh"
+  if [ -x "$ALLOC" ]; then
+    N="$("$ALLOC" reserve FEAT "<slug>")"   # e.g. prints 0024
+    # → the reserved epic id is FEAT-$N. The integer is now claimed; a parallel
+    #   session calling reserve will get FEAT-$((N+1)).
+  fi
+  ```
+
+  State the reserved integer in your response.
+- **Fallback when the allocator is absent** (older install, no script): degrade to
+  the canonical-backlog scan — `git fetch <git.trunk_branch>`, then
+  `max` over `git grep '^id: FEAT-' $(git merge-base HEAD <git.trunk_branch>)`
+  plus the local worktree backlog. This still misses in-flight sibling-worktree
+  IDs, so surface a `[ID-RACE-RISK]` note so the caller can re-verify before
+  commit. If `git fetch` is impossible (offline), say the reservation is
+  best-effort against the local view.
+- The same procedure applies to any other prefix you mint (`BUG`, `UI`, `DOC`,
+  `PERF`): `reserve <PREFIX> <slug>` — the allocator is prefix-parametric.
 
 ### FORBIDDEN PATTERNS — agent MUST refuse to generate
 
@@ -350,10 +368,12 @@ Mirror their structure when generating new epic+child sets.
 
 Before writing the first YAML file, confirm and report to the caller:
 
-1. **Reserved FEAT-XXXX integer**: Grep `^id: FEAT-` in `${paths.backlog_dir}/`, find max,
-   pick max+1, per the concurrency-safe procedure in § "FEAT-XXXX numbering"
-   (fetch trunk + merge-base scan to avoid duplicate IDs across parallel
-   sessions). State the chosen integer in your response.
+1. **Reserved FEAT-XXXX integer**: reserve it via the atomic allocator
+   (`allocate-id.sh reserve FEAT <slug>`), per § "FEAT-XXXX numbering" — this is
+   the concurrency-safe path that prevents duplicate IDs across parallel sessions
+   on sibling worktrees. If the allocator is absent, fall back to the trunk
+   fetch + merge-base scan with an `[ID-RACE-RISK]` note. State the chosen
+   integer in your response.
 2. **Drafted epic + N children list**: list the planned filenames
    (`FEAT-XXXX-00-<slug>-epic.yml`, `FEAT-XXXX-01-<sub-slug>.yml`, ...) BEFORE
    writing them. This is a contract — the actual files MUST match the list.

package/framework/.claude/agents/prd.md

@@ -498,7 +498,20 @@ Create protocol-compliant backlog cards for every actionable step. Cards MUST fo
 
 #### 4.1 — NAMING CONVENTIONS
 
-Before creating cards, scan `${paths.backlog_dir}/*.yml` to determine the next available number. File naming rules:
+Before creating cards, reserve the next number for the chosen prefix. **Prefer the
+atomic allocator** — a plain `${paths.backlog_dir}/*.yml` scan collides under
+parallelism (concurrent sessions on sibling worktrees both pick the same "next"
+integer and conflict at merge):
+
+```bash
+# $MAIN = dirname of `git rev-parse --git-common-dir` (shared across worktrees).
+ALLOC="$MAIN/.claude/skills/worktree-manager/scripts/allocate-id.sh"
+[ -x "$ALLOC" ] && N="$("$ALLOC" reserve FEAT <slug>")   # also BUG | UI | DOC | PERF
+```
+
+If the allocator is absent (older install), fall back to scanning
+`${paths.backlog_dir}/*.yml` for the max and add 1, noting `[ID-RACE-RISK]`. See
+`worktree-manager` § "ID Allocation" for the mechanism. File naming rules:
 
 | Prefix | When to use | Example |
 |--------|-------------|---------|

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/.claude/skills/worktree-manager/SKILL.md

@@ -292,7 +292,9 @@ git -C "$WORKTREE_PATH" rebase "origin/$TRUNK"
 # 5. Sync local trunk ref — reuse /mw "Common" block: ff-only pull when main
 #    repo HEAD is already $TRUNK; otherwise just fetch.
 
-# 6. Remove the registry entry for this worktree.
+# 6. Remove the registry entry for this worktree, then release its backlog-ID
+#    reservations (best-effort, high-water mark untouched):
+#    .claude/skills/worktree-manager/scripts/allocate-id.sh release "$WORKTREE_PATH" 2>/dev/null || true
 ```
 
 **Forbidden in docs merge**: pre-merge `npm run build`, `npx eslint`, `npx tsc`, `npm run test`, post-merge `npm run build`. The whole point of docs mode is that these gates are inapplicable.
@@ -356,6 +358,57 @@ Create the file if it doesn't exist. Update it on every `/nw`, `/mw`, `/cw` oper
 
 ---
 
+## ID Allocation — atomic backlog-ID reservation across parallel worktrees
+
+When several PRD / card sessions run in parallel on sibling worktrees, each
+branched from the same trunk, a plain `max(^id: PREFIX-) + 1` scan makes them all
+land on the **same next integer**: the other session's card is in flight on an
+unmerged sibling branch, invisible to both the local backlog and the trunk
+merge-base. They collide at rebase/merge time.
+
+`scripts/allocate-id.sh` closes that race **on the same machine**. Every worktree
+shares one main repo root (resolved from `git rev-parse --git-common-dir`), and
+`.worktrees/` lives there and is gitignored — so it is the natural shared
+coordination point, exactly like `registry.json`. The allocator anchors a lock
+and a per-prefix high-water-mark there:
+
+```bash
+# Reserve the next free integer for a prefix (FEAT, BUG, UI, DOC, PERF, …).
+# Prints the integer zero-padded to 4 digits on stdout; diagnostics on stderr.
+.claude/skills/worktree-manager/scripts/allocate-id.sh reserve FEAT <slug>
+
+# Release a finished worktree's reservations (best-effort prune; never blocks).
+.claude/skills/worktree-manager/scripts/allocate-id.sh release <worktree-path>
+```
+
+Shared files, all under `$MAIN/.worktrees/` (already gitignored):
+- `.id-alloc.lock/` — cross-process mutex (atomic `mkdir`, stale-stolen after 30s
+  via the dir's own mtime; it is a directory, NOT a git ref, so it does not touch
+  the shared `refs/stash` that `git stash` in worktrees is forbidden over).
+- `.id-hwm-<PREFIX>` — monotonic high-water mark per prefix. **This is the
+  correctness anchor**: bumped under the lock, never decremented.
+- `id-reservations.jsonl` — append-only `{prefix,id,worktree,slug,ts}` log for
+  observability + `release` pruning. NOT load-bearing for correctness.
+
+Inside the lock, `reserve` takes `NEXT = max(high-water file, local backlog, every
+sibling worktree's backlog from registry.json, reservations log, trunk
+merge-base) + 1`. The `max()` against the real backlog makes it **self-healing**:
+if `.id-hwm-*` is ever lost or a card was created bypassing the allocator, the
+next reservation still skips occupied numbers. Abandoned reservations leave
+**gaps**, which is fine — backlog IDs need not be contiguous, and "reserve the
+whole integer, never reuse" is already the rule.
+
+**Scope: same machine only.** The shared file cannot reach separate cloud agents;
+the trunk merge-base scan inside `reserve` is the best-effort cross-machine guard.
+Callers (`prd-card-writer`, the `prd` agent) invoke `reserve` when the script is
+present and **fall back to their inline merge-base scan + `[ID-RACE-RISK]` note**
+when it is absent (older installs) — the allocator is additive, never required.
+
+`release` is wired into the cleanup path of `/mw`, `mw-docs`, and `/cw` (see those
+steps) so a merged/cleaned worktree's reservations are pruned.
+
+---
+
 ## /nw — New Worktree
 
 Supports three modes:
@@ -1077,6 +1130,13 @@ git worktree prune
 
 Remove the entry from `.worktrees/registry.json`.
 
+Also release this worktree's backlog-ID reservations (best-effort; the high-water
+mark stays untouched so numbering remains monotonic):
+
+```bash
+.claude/skills/worktree-manager/scripts/allocate-id.sh release "$WORKTREE_PATH" 2>/dev/null || true
+```
+
 ### 8. Report
 
 ```
@@ -1184,7 +1244,12 @@ git worktree prune
 
 ### 4. Update registry
 
-Remove cleaned entries from `.worktrees/registry.json`.
+Remove cleaned entries from `.worktrees/registry.json`. For each removed
+worktree, also release its backlog-ID reservations (best-effort):
+
+```bash
+.claude/skills/worktree-manager/scripts/allocate-id.sh release "<removed-worktree-path>" 2>/dev/null || true
+```
 
 ### 5. Report
 

package/framework/.claude/skills/worktree-manager/scripts/allocate-id.sh

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+#
+# allocate-id.sh — atomic, cross-worktree backlog-ID allocator (same machine).
+#
+# Problem it solves: several PRD/card sessions running in parallel on sibling
+# worktrees all branch from the same trunk, so each computes the same
+# "max(^id: PREFIX-) + 1" and they collide at rebase/merge time. A plain
+# backlog scan cannot see IDs that are still in flight on an unmerged sibling
+# worktree branch.
+#
+# Mechanism: every worktree shares the same main repo root (resolved from
+# `git rev-parse --git-common-dir`), and `.worktrees/` lives there and is
+# gitignored. We anchor a lock + a per-prefix high-water-mark file there, so a
+# reservation is atomic across every worktree on this machine. The high-water
+# bumped under the lock is the correctness mechanism; the max() against the real
+# backlog makes it self-healing if the counter file is ever lost or bypassed.
+#
+# Scope: SAME MACHINE only (a shared local file). Cross-machine (separate cloud
+# agents) is not covered here — the caller keeps the merge-base scan as a
+# best-effort cross-machine guard and surfaces an [ID-RACE-RISK] note.
+#
+# Usage:
+#   allocate-id.sh reserve <PREFIX> <slug>     # prints the reserved integer, zero-padded to 4
+#   allocate-id.sh release <worktree-path>     # prunes that worktree's reservations (best-effort)
+#
+# Exit non-zero on hard failure (not a git repo, lock unobtainable) so the
+# caller can fall back to its inline scan. All diagnostics go to stderr; stdout
+# carries ONLY the allocated number on success.
+
+set -u
+
+LOCK_STALE_SECONDS=30
+LOCK_MAX_TRIES=150   # ~30s at 0.2s/try
+
+err() { printf '%s\n' "$*" >&2; }
+
+# --- Resolve the shared main repo root from any worktree -------------------
+resolve_main() {
+  local common
+  common="$(git rev-parse --git-common-dir 2>/dev/null)" || return 1
+  case "$common" in
+    /*) ;;                          # already absolute
+    *)  common="$(pwd)/$common" ;;  # relative (we're in the main repo) → absolutise
+  esac
+  (cd "$common/.." 2>/dev/null && pwd) || return 1
+}
+
+# --- Read a paths.* / git.* scalar from baldart.config.yml -----------------
+config_scalar() {
+  # $1 = top-level block (paths|git), $2 = key
+  local block="$1" key="$2" cfg="$MAIN/baldart.config.yml"
+  [ -f "$cfg" ] || return 0
+  grep -A60 "^${block}:" "$cfg" 2>/dev/null \
+    | grep -m1 "[[:space:]]*${key}:" \
+    | sed -E "s/.*${key}:[[:space:]]*\"?([^\"#]*)\"?.*/\1/" \
+    | sed -E 's/[[:space:]]+$//'
+}
+
+# --- Highest integer for PREFIX across one or more directories -------------
+scan_dirs_max() {
+  local prefix="$1"; shift
+  local max="$1"; shift     # starting floor
+  local d line n
+  for d in "$@"; do
+    [ -d "$d" ] || continue
+    while IFS= read -r line; do
+      [ -n "$line" ] || continue
+      n="$(printf '%s' "$line" | sed -E "s/^id:[[:space:]]*${prefix}-0*([0-9]+).*/\1/")"
+      case "$n" in ''|*[!0-9]*) continue ;; esac
+      [ "$n" -gt "$max" ] && max="$n"
+    done <<EOF
+$(grep -rhoE "^id:[[:space:]]*${prefix}-[0-9]+" "$d"/*.yml 2>/dev/null)
+EOF
+  done
+  printf '%s' "$max"
+}
+
+# --- Lock helpers (mkdir is atomic on POSIX; portable, no flock) -----------
+# Staleness uses the lock directory's own mtime (set atomically by mkdir, and
+# refreshed when the holder writes pid) — NOT a ts file that may not be written
+# yet, which would race a just-created lock into an instant false steal. The
+# critical section is local-FS only (the slow `git fetch` runs before the lock),
+# so the stale threshold is never tripped by a legitimate holder.
+file_mtime() { stat -f %m "$1" 2>/dev/null || stat -c %Y "$1" 2>/dev/null || echo 0; }
+acquire_lock() {
+  local tries=0 now m age
+  mkdir -p "$WT_DIR" 2>/dev/null || true
+  while ! mkdir "$LOCKDIR" 2>/dev/null; do
+    if [ -d "$LOCKDIR" ]; then
+      now="$(date +%s)"; m="$(file_mtime "$LOCKDIR")"
+      case "$m" in ''|*[!0-9]*) m=0 ;; esac
+      age=$(( now - m ))
+      if [ "$m" -gt 0 ] && [ "$age" -gt "$LOCK_STALE_SECONDS" ]; then
+        err "WARN: stealing stale id-alloc lock (age ${age}s)"; rm -rf "$LOCKDIR" 2>/dev/null; continue
+      fi
+    fi
+    tries=$(( tries + 1 ))
+    [ "$tries" -gt "$LOCK_MAX_TRIES" ] && { err "ERROR: could not acquire id-alloc lock"; return 1; }
+    sleep 0.2
+  done
+  printf '%s\n' "$$" > "$LOCKDIR/pid" 2>/dev/null || true
+}
+release_lock() { rm -rf "$LOCKDIR" 2>/dev/null || true; }
+
+# ===========================================================================
+CMD="${1:-}"
+MAIN="$(resolve_main)" || { err "ERROR: not inside a git repository"; exit 1; }
+WT_DIR="$MAIN/.worktrees"
+LOCKDIR="$WT_DIR/.id-alloc.lock"
+RESV="$WT_DIR/id-reservations.jsonl"
+REG="$WT_DIR/registry.json"
+
+case "$CMD" in
+  reserve)
+    PREFIX="${2:-}"; SLUG="${3:-}"
+    [ -n "$PREFIX" ] || { err "usage: allocate-id.sh reserve <PREFIX> <slug>"; exit 2; }
+    case "$PREFIX" in *[!A-Z]*|'') err "ERROR: PREFIX must be uppercase letters (e.g. FEAT, BUG)"; exit 2 ;; esac
+
+    BACKLOG_DIR="$(config_scalar paths backlog_dir)"; [ -n "$BACKLOG_DIR" ] || BACKLOG_DIR="backlog"
+    TRUNK="$(config_scalar git trunk_branch)"
+    WT="$(git rev-parse --show-toplevel 2>/dev/null || echo "$MAIN")"
+    HWM="$WT_DIR/.id-hwm-$PREFIX"
+
+    # Refresh the remote trunk ref BEFORE taking the lock — it's the only slow
+    # (network) step; keeping it out of the critical section means a holder can
+    # never be stale-stolen mid-allocation.
+    [ -n "$TRUNK" ] && git fetch origin "$TRUNK" --quiet 2>/dev/null || true
+
+    acquire_lock || exit 1
+    trap release_lock EXIT
+
+    # 1) Floor = stored high-water mark (correctness anchor).
+    max=0
+    if [ -f "$HWM" ]; then
+      max="$(tr -cd '0-9' < "$HWM" 2>/dev/null)"; case "$max" in ''|*[!0-9]*) max=0 ;; esac
+    fi
+
+    # 2) Local worktree backlog + every sibling worktree's backlog (in flight).
+    dirs="$MAIN/$BACKLOG_DIR"
+    [ "$WT" != "$MAIN" ] && dirs="$dirs $WT/$BACKLOG_DIR"
+    if [ -f "$REG" ]; then
+      while IFS= read -r p; do
+        [ -n "$p" ] && dirs="$dirs $p/$BACKLOG_DIR"
+      done <<EOF
+$(grep -oE '"path"[[:space:]]*:[[:space:]]*"[^"]*"' "$REG" 2>/dev/null | sed -E 's/.*"([^"]*)"$/\1/')
+EOF
+    fi
+    # shellcheck disable=SC2086
+    max="$(scan_dirs_max "$PREFIX" "$max" $dirs)"
+
+    # 3) Reservations log (covers a wiped HWM with reservations still in flight).
+    if [ -f "$RESV" ]; then
+      while IFS= read -r n; do
+        n="$(printf '%s' "$n" | sed -E "s/.*\"${PREFIX}-0*([0-9]+).*/\1/")"
+        case "$n" in ''|*[!0-9]*) continue ;; esac
+        [ "$n" -gt "$max" ] && max="$n"
+      done <<EOF
+$(grep -oE "\"id\":\"${PREFIX}-[0-9]+" "$RESV" 2>/dev/null)
+EOF
+    fi
+
+    # 4) Best-effort cross-machine guard: merge-base of trunk (already-merged IDs).
+    #    The fetch already ran before the lock; this is a local object-store read.
+    if [ -n "$TRUNK" ]; then
+      MB="$(git merge-base HEAD "origin/$TRUNK" 2>/dev/null || git merge-base HEAD "$TRUNK" 2>/dev/null || true)"
+      if [ -n "$MB" ]; then
+        while IFS= read -r n; do
+          n="$(printf '%s' "$n" | sed -E "s/^id:[[:space:]]*${PREFIX}-0*([0-9]+).*/\1/")"
+          case "$n" in ''|*[!0-9]*) continue ;; esac
+          [ "$n" -gt "$max" ] && max="$n"
+        done <<EOF
+$(git grep -hoE "^id:[[:space:]]*${PREFIX}-[0-9]+" "$MB" -- "$BACKLOG_DIR/*.yml" 2>/dev/null)
+EOF
+      fi
+    fi
+
+    NEXT=$(( max + 1 ))
+    printf '%s\n' "$NEXT" > "$HWM" 2>/dev/null || true
+    printf '{"prefix":"%s","id":"%s-%04d","worktree":"%s","slug":"%s","ts":"%s"}\n' \
+      "$PREFIX" "$PREFIX" "$NEXT" "$WT" "$SLUG" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$RESV" 2>/dev/null || true
+
+    release_lock; trap - EXIT
+    printf '%04d\n' "$NEXT"
+    ;;
+
+  release)
+    WT="${2:-}"
+    [ -n "$WT" ] || { err "usage: allocate-id.sh release <worktree-path>"; exit 2; }
+    [ -f "$RESV" ] || exit 0
+    acquire_lock || exit 0   # best-effort prune; never block cleanup
+    trap release_lock EXIT
+    # grep -v exit code: 0 = some lines kept, 1 = none kept (all pruned → empty
+    # file is the correct result), >=2 = real error (keep the original).
+    grep -vF "\"worktree\":\"$WT\"" "$RESV" > "$RESV.tmp" 2>/dev/null
+    if [ "$?" -le 1 ]; then
+      mv "$RESV.tmp" "$RESV" 2>/dev/null || rm -f "$RESV.tmp" 2>/dev/null
+    else
+      rm -f "$RESV.tmp" 2>/dev/null
+    fi
+    release_lock; trap - EXIT
+    ;;
+
+  *)
+    err "usage: allocate-id.sh {reserve <PREFIX> <slug> | release <worktree-path>}"
+    exit 2
+    ;;
+esac

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