baldart 4.78.2 → 4.80.0

package/CHANGELOG.md

@@ -5,6 +5,48 @@ 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.80.0] - 2026-06-29
+
+**Codex-native subagents — the 32 BALDART agents are now installed for Codex, not just Claude.** A portability bug surfaced in the field: a skill running on Codex delegated to `codebase-architect` (*"invoke the codebase-architect agent"*), but the agent did not exist in the Codex tree and there was no obvious mechanism to spawn it, so the model **improvised** a generic explorer sub-agent. Root cause (confirmed against the OpenAI Codex docs, June 2026): the framework treated subagents as Claude-only — the Codex tool adapter declared `supportsSubagents() === false` / `agentsDir() === null`, so the agent definitions under `framework/.claude/agents/` were **never installed into a Codex tree**. But **Codex now has custom agents** (subagents) — they were simply in a different shape than Claude's, and BALDART had not yet mapped them. This release closes that gap.
+
+Because a Codex custom agent is a **different on-disk artifact** than a Claude subagent — a TOML file at `.codex/agents/<name>.toml` with `name` / `description` / `developer_instructions` (+ optional `model_reasoning_effort`), spawned **by name** — the skill-style "one source, two symlinks" model does not apply. Instead the same `framework/.claude/agents/<name>.md` stays the **single SSOT** and BALDART **transpiles** it to `.toml` on install/update (new `src/utils/codex-agent-transpiler.js`): frontmatter `name`/`description` → same, body → `developer_instructions`, `effort` (low|medium|high|xhigh|max) → `model_reasoning_effort` (xhigh/max clamp to high), `model` **omitted on purpose** (opus/sonnet/haiku have no 1:1 Codex model → inherit the parent session). The generated `.toml` is a real file (you cannot symlink `.md` → `.toml`) carrying a `# baldart-generated:` marker, so an `update` regenerates it idempotently and a user fork (no marker) is never clobbered. Overlays apply **first** (the markdown `## [OVERRIDE]/[APPEND]/[PREPEND]` overlay is merged, then transpiled) — Codex agents honour `.baldart/overlays/agents/<name>.md` exactly like Claude. The transpile rides on the **existing** `MERGE_KINDS` machinery via one new adapter hook, `transpilerFor(kind)` (`codex` returns a transpiler for `agent`; `claude` returns null), so nothing else in the merge path changed and Claude is byte-for-byte unaffected. Existing Codex consumers pick it up on the next `npx baldart update`. AGENTS.md's "MUST invoke codebase-architect" + no-silent-fallback rules are now tool-aware (the agent exists on both tools; spawn by name on Codex). Verified end-to-end: all 32 real agents transpile to valid TOML (parsed with `@iarna/toml`), idempotency / source-change-regen / user-fork-protection / overlay-aware-transpile all pass.
+
+**Standing convention** (the user's explicit ask: *every agent from now on is natively Codex-compatible*): any new agent is auto-portable — drop a `.md` under `framework/.claude/agents/`, keep `name`+`description` frontmatter, put behaviour in the body (→ `developer_instructions`), and don't rely on an agent spawning a further agent (Codex `agents.max_depth: 1`, consistent with BALDART's `## Role boundary`). Skills were already Codex-native (identical format). Authoritative design: [`framework/docs/CODEX-AGENTS.md`](framework/docs/CODEX-AGENTS.md).
+
+**MINOR** — additive capability (Codex consumers gain 32 agents; existing Claude installs unchanged). **No new `baldart.config.yml` key** — rides on `tools.enabled` containing `codex`, so the schema-change propagation rule does NOT apply. Slash commands / dynamic workflows / output styles stay Claude-only (`commandsDir`/`workflowsDir`/`outputStylesDir` remain null for Codex — no Codex equivalent).
+
+### Added
+
+- **`src/utils/codex-agent-transpiler.js`** — pure `.md` → `.toml` transpiler (`mdAgentToToml`, `isGeneratedToml`, `mapEffort`). Emits `developer_instructions` as a TOML multi-line **literal** (`'''…'''`) so arbitrary markdown survives byte-for-byte, with an escaped `"""…"""` fallback only when the body itself contains `'''`.
+- **`framework/docs/CODEX-AGENTS.md`** — design + field-mapping table + the per-agent authoring contract.
+
+### Changed
+
+- **`src/utils/tool-adapters/codex.js`** — `agentsDir()` → `.codex/agents` (was null), `supportsSubagents()` → true (was false), new `transpilerFor(kind)` hook returning the TOML transpiler for `agent`. Header comment corrected (Codex DOES have custom agents now).
+- **`src/utils/tool-adapters/claude.js`** — added `transpilerFor()` → null (explicit no-op: Claude consumes every payload in its native format).
+- **`src/utils/symlinks.js`** — `_mergeBulkDir` routes a kind through the new `_installTranspiledFile` (generate tool-native file, overlay-merged first when present) when the adapter declares a transpiler; `verifySymlinks` recognises transpiled `.toml` (via `isGeneratedToml`) as framework-managed alongside symlinks and overlay-generated `.md`.
+- **`framework/AGENTS.md`** — the "MUST invoke `codebase-architect`" and no-silent-substitution rules are now tool-aware: the agent exists on both tools (Claude → Task/`subagent_type`; Codex → spawn by name at `.codex/agents/codebase-architect.toml`); the #56869 specifics stay Claude-scoped, the principle stays universal.
+- **`framework/.claude/agents/REGISTRY.md`** + **`CLAUDE.md`** — document the Codex-native subagent convention + the authoring contract.
+
+## [4.79.0] - 2026-06-29
+
+**New skill `/ds-handoff` — the field-level, 1:1 Claude Design handoff brief.** When `/prd` reached the "hand off to Claude Design" branch, the prompt it produced described each screen only coarsely — *purpose / states / actions / data shown* — and never the exact fields. With no field-level contract, Claude Design **imagines** control types, required-ness, validation, defaults and enum values to cover the gap, so the result is never 1:1. The root cause: BALDART had **no mandatory phase** that enumerated a screen's real fields, and **no coverage gate** verifying them before the prompt was emitted (field discovery was manual discovery-questions). `/ds-handoff` fixes this end-to-end: it (1) identifies each screen's backing data entities, (2) **grounds the field inventory in the project's real schemas** (Zod / TS types / form schemas) by composing existing retrieval (code-graph → LSP → `codebase-architect` → Grep — **no new AST/Zod parser**, an over-scoped fragility the design refused), (3) reconciles fields↔screens (which fields show / are editable / group into which card), (4) runs a **coverage gate** that **BLOCKS** emission in interactive mode when a backed screen's `{control, required}` are unverified — degrading gracefully to user-confirmation when no formal schema exists (portable / Codex), (5) renders the **mandatory field-level template** (a 9-column field-inventory table per screen + actions / states / responsive). It becomes the **single SSOT** for the Claude Design prompt: `/prd` Step 3.0 Branch B now **delegates** to it (graceful inline-coarse fallback when the skill is unavailable), and the old inline `/prd` template is **retired**. Usable standalone via `/ds-handoff <screens-or-feature>` (e.g. an ad-hoc orchestrator + `ui-expert` run). A THIN orchestrator — it **cites** `design-system-protocol.md` (Functional Traceability Gate `backed/decorative/orphan` vocabulary + Reference Tables numbers) and **reads** `discovery-phase.md`'s `mockup_analysis` as input, never duplicating their rules (no dual-SSOT).
+
+**MINOR** — new skill (40 portable skills). **No new `baldart.config.yml` key** — rides on the already-present `features.has_design_system` (BLOCKING gate; REFUSE + suggest `/design-system-init` when `false`) + `features.has_prd_workflow` when delegated, so the schema-change propagation rule does NOT apply. Claude + Codex portable (the gate degrades, subagent steps fall back to Grep). No agent / template / routine outside the skill changed; `discovery-phase.md` (`mockup_analysis`) and `card-schema.md` (`component_bindings`) are deliberately **untouched** (the field layer is a skill-local artifact, not a card/state schema field).
+
+### Added
+
+- **`/ds-handoff`** (`framework/.claude/skills/ds-handoff/`) — `SKILL.md` (thin 8-step orchestrator), `assets/claude-design-handoff-prompt.template.md` (the mandatory field-level template — replaces the retired `/prd` coarse template), `references/field-extraction.md` (retrieval order + control-type mapping table + readonly detection), `references/coverage-gate.md` (BLOCK-vs-degrade logic + the worked "Fornitori" example). Gated on `features.has_design_system`.
+
+### Changed
+
+- **`/prd`** (`framework/.claude/skills/prd/references/ui-design-phase.md`) — Step 3.0 Branch B now **delegates** the Claude Design handoff prompt to `/ds-handoff` (passing the resolved context so it skips its own screen-resolution), presents what it returns, and persists `mockups.field_inventory_path`. Graceful **inline-coarse fallback** (stated explicitly) when `/ds-handoff` is unavailable.
+- **`framework/agents/skills-mapping.md`** — expanded from a curated 11-skill subset to the **full 40-skill routing map** (Design System, Internationalization, Retrieval/Toolchain Bootstrap, Framework Maintenance categories added; per-entry `features.*` gating noted; decision tree + chains updated with the design-system + Claude-Design-handoff flows), so the routing doc the agent reads covers every shipped skill including `ds-handoff`.
+
+### Removed
+
+- **`framework/.claude/skills/prd/assets/claude-design-handoff-prompt.template.md`** — the coarse `/prd` handoff template, superseded by the field-level template in `ds-handoff/assets/` (single SSOT; coarse content survives inline in the Branch B fallback).
+
 ## [4.78.2] - 2026-06-29
 
 **The "visual-verify every `ui-expert` intervention" hard rule was investigated and deliberately NOT built.** The ask sounded obvious — wire an invariant `UI_VISUAL_UNVERIFIED` forcing a visual check after every `ui-expert` implementation. Three adversarial reviewers (distinct lenses) refuted the diagnosis: (1) standalone skills already verify — `/ui-design` has its generator/evaluator Playwright loop, `/ds-new` + `/ds-edit` delegate to `ui-expert`'s own BLOCKING pre-work + `ds-gate` + the coherence report, `/ds-render` feeds `/e2e-review` Phase 4b; (2) the invariant would be redundant with the existing `DS_*` coherence codes + the `coverage-gap` finding, and would fire **constantly** on every Storybook-less project — the gate-with-no-exit structural false-positive the framework explicitly avoids — plus risk the assertion-fitting the verifier trio forbids; (3) the real driver the obvious diagnosis missed: **visual verification is deliberately deferred to where a ground-truth exists** (a composed route / a mockup) — an inert scaffolded primitive has nothing to be judged against, so verifying it *now* judges the void. The single useful residue (a deterministic `PostToolUse` hook would beat prose if one ever wanted to harden `/new`'s own prose-driven Phase 2.6) was logged, not built. So this release ships only the **zero-cost, non-regressive nudge**: a documentation pointer making explicit *where* route-level fidelity lives.

package/README.md

@@ -212,14 +212,14 @@ Skills always-ask when required keys are missing — never silently default.
 never overwrites your file. Full guide:
 [`framework/docs/PROJECT-CONFIGURATION.md`](framework/docs/PROJECT-CONFIGURATION.md).
 
-### Skills (37 portable skills)
+### Skills (40 portable skills)
 
 Skills live under `.claude/skills/` and are auto-discovered by Claude Code.
 Bundled skills:
 
 - **Workflow**: `new`, `new2` (v4.16.0 — EXPERIMENTAL workflow-hosted `/new`, Claude-only, for A/B testing context economy), `prd`, `prd-add`, `bug`, `simplify`, `worktree-manager`, `issue-review`, `context-primer`
 - **Code quality**: `skill-creator`, `find-skills`, `webapp-testing`, `playwright-skill`, `lsp-bootstrap` (v3.10.0), `graphify-bootstrap` (v4.21.0 — code knowledge graph), `graph-align` (v4.21.0 — doc↔graph alignment), `toolchain-bootstrap` (v4.41.0 — curated dev toolchain), `e2e-review` (v3.18.0)
-- **Design**: `frontend-design`, `ui-design`, `motion-design`, `gamification-design`, `design-system-init` (v3.11.0 — bulk registry bootstrap/upgrade), `ds-new` (v4.69.0 — single-element guided creation: one component or token, reuse-first → optional scaffold → document + register + govern + verify; the on-the-fly twin of `design-system-init`), `ds-edit` (v4.70.0 — deliberate edit of one existing element: resync / extend-variant / breaking / re-govern; regenerates the spec preserving agentic fields + prose, same canonical template)
+- **Design**: `frontend-design`, `ui-design`, `motion-design`, `gamification-design`, `design-system-init` (v3.11.0 — bulk registry bootstrap/upgrade), `ds-new` (v4.69.0 — single-element guided creation: one component or token, reuse-first → optional scaffold → document + register + govern + verify; the on-the-fly twin of `design-system-init`), `ds-edit` (v4.70.0 — deliberate edit of one existing element: resync / extend-variant / breaking / re-govern; regenerates the spec preserving agentic fields + prose, same canonical template), `ds-render` (v4.76.0 — render primitives in isolation to PNG via Storybook+Playwright), `design-sync` (v4.76.0 — mirror the registry to its Claude Design satellite), `ds-handoff` (v4.79.0 — field-level 1:1 Claude Design handoff brief: grounds every screen's fields in the real data schemas + coverage-gates before emitting; the SSOT for the Claude Design prompt, delegated from `/prd`)
 - **Product**: `seo-audit`, `copywriting`, `api-design-principles`
 - **Knowledge**: `doc-writing-for-rag`, `capture` (LLM wiki overlay)
 - **Internationalization**: `i18n` (v4.52.0 — audit the context registry + context-aware translation into native locale files), `i18n-adopt` (v4.52.0 — one-shot migration that externalizes all hardcoded strings on an existing codebase); both gated on `features.has_i18n`

package/VERSION

@@ -1 +1 @@
-4.78.2
+4.80.0

package/framework/.claude/agents/REGISTRY.md

@@ -2,7 +2,9 @@
 
 Quick-reference for all custom agents. Use this to route tasks to the right specialist.
 
-**Location**: `.claude/agents/<name>.md` | **Invoke via**: `Task` tool with `subagent_type="<name>"`
+**Location**: `.claude/agents/<name>.md` | **Invoke via**: `Task` tool with `subagent_type="<name>"` (Claude) — or **by name** as a Codex custom agent (Codex)
+
+> **Codex-native (since v4.80.0)**: every agent here is portable to Codex. The same `<name>.md` is **transpiled** to `.codex/agents/<name>.toml` on install/update (`name`/`description` → same, body → `developer_instructions`, `effort` → `model_reasoning_effort`, `model` omitted). Authoring stays single-source: drop a `.md`, it auto-installs for both tools. Keep `name`+`description` frontmatter, put behaviour in the body, and don't rely on an agent spawning a further agent (Codex `agents.max_depth: 1`). Design: [`framework/docs/CODEX-AGENTS.md`](../../docs/CODEX-AGENTS.md).
 
 > **Machine-readable source of truth (since v3.20.0)**: the filesystem directory `framework/.claude/agents/` is authoritative for the list of BALDART agents. The `agent-discovery-gate.js` PreToolUse hook, the `agent-discovery-info.sh` SessionStart hook, and `baldart doctor` enumerate the directory directly (every `<name>.md` except this file is an agent — no manifest JSON is shipped). Adding a new agent means dropping `<name>.md` here; no other touchpoint.
 

package/framework/.claude/skills/ds-handoff/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: ds-handoff
+effort: medium
+description: >
+  Produce a FIELD-LEVEL, 1:1, interaction-complete handoff brief for Claude Design
+  — every screen's real fields (label, control type, required, validation, default,
+  enum source, helper text, editable-vs-readonly), grounded in the project's actual
+  data schemas (Zod / TS types / form schemas) via a coverage gate that BLOCKS prompt
+  emission when a backed screen's fields are unverified. The single SSOT for the
+  Claude Design handoff prompt: `/prd` Step 3.0 Branch B delegates here; usable
+  standalone via `/ds-handoff <screens-or-feature>`. A THIN orchestrator — cites
+  `design-system-protocol.md` (Functional Traceability Gate, Reference Tables) and
+  reads `mockup_analysis` as input, never duplicating their rules; reuses existing
+  retrieval (code-graph / LSP / codebase-architect / Grep) rather than shipping a
+  schema-extractor tool. Use when the user says /ds-handoff, "handoff a Claude
+  Design", "prompt per Claude Design", "brief field-level", "prepara il prompt
+  mockup". Gated on features.has_design_system.
+---
+
+# DS Handoff — field-level Claude Design brief
+
+The fix for the "the prompt describes structure but not the fields, so Claude
+Design imagines" failure. A mockup prompt that lists screens only as
+*purpose / states / actions / data shown* forces the design tool to invent control
+types, required-ness, validation, defaults and enum values. This skill enumerates
+every backing field **from the real code**, reconciles it per screen, **verifies
+coverage before emitting**, and renders the mandatory field-level template.
+
+It is a conductor: each step DELEGATES to an existing module and cross-pointers to
+it. No cascade / schema / traceability rule is re-described here (re-describing it
+is how it drifts from the SSOT).
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `paths.design_system`,
+`paths.components_primitives`, `paths.design_tokens`, `paths.ui_guidelines`,
+`paths.prd_dir`, `stack.framework`, `stack.charting`, `stack.animation`,
+`identity.*`, `features.has_design_system`, `features.has_lsp_layer`,
+`features.has_code_graph`, `features.has_i18n`.
+
+**Writes:** the rendered prompt → `${paths.prd_dir}/<slug>/handoff/claude-design-prompt.md`;
+the optional field inventory → `${paths.prd_dir}/<slug>/mockups/field-inventory.md`.
+Source-read-only otherwise (it never edits app code or the registry).
+
+**Gated by features:** `features.has_design_system` (BLOCKING). When `false`,
+REFUSE and recommend `/design-system-init` (§ 5 of the prompt + the per-region
+component binding need a registry). When delegated from `/prd` it also rides on
+`features.has_prd_workflow`. See `design-system-protocol.md` § Gating.
+
+**Overlay:** loads `.baldart/overlays/ds-handoff.md` if present (brand voice,
+mandated output format, project control conventions).
+
+**On missing/empty keys:** ask the user; do not assume defaults. See
+`framework/agents/project-context.md` § 3.
+
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale reasoning
+depth for this run — detect it once at kickoff and strip the token before consuming
+user input. Level→behavior mapping, parsing contract, and precedence caveats:
+`framework/agents/effort-protocol.md`.
+
+## Invocation
+
+`/ds-handoff <screens-or-feature>` (standalone) · `/ds-handoff` (ask). When called
+by `/prd` Step 3.0 Branch B, the caller passes the resolved context (state-file
+path + feature title/objective/user_flow/personas/screens_in_scope/mockup_analysis
++ brand + DS flag) — skip the standalone screen-resolution prompt (Step 1's ask).
+
+## Pre-flight
+
+- **P0 — gate.** `features.has_design_system: false` → REFUSE + suggest
+  `/design-system-init`. (DELEGATE `design-system-protocol.md` § Gating.)
+- **P1 — mode.** *Delegated* (a `/prd` state-file path was passed) vs *standalone*
+  (`/ds-handoff <args>`). The mode only changes where screens + top-level context
+  come from (Step 1); Steps 2–8 are identical.
+
+---
+
+## Workflow
+
+Each step is a delegation. Read the cited SSOT; do not paraphrase it.
+
+1. **Resolve screens in scope.** *Delegated* → read `screens_in_scope[]` +
+   `mockup_analysis` from the `/prd` state file `## UI Design` (reuse the caller's
+   collection — do NOT re-derive). *Standalone* → derive screens from the arg;
+   on ambiguity, ONE `AskUserQuestion` listing route/page candidates from a
+   `codebase-architect` probe. Never proceed on silence.
+
+2. **Identify backing entities per screen.** Name the entity/entities each screen
+   reads or writes. A screen may legitimately have **zero** entities (pure
+   navigation / dashboard chrome) — that is valid and MUST NOT trip the gate
+   (Step 5).
+
+3. **Locate & extract the real field definitions.** DELEGATE — see
+   [references/field-extraction.md](references/field-extraction.md) for the
+   retrieval order (code-graph → LSP → `codebase-architect` → Grep, each with
+   silent fallback) and the control-type mapping table. Per field capture: label,
+   control, required, validation, default, enum/options source, helper,
+   editable-vs-readonly. The skill ships **no** AST/Zod parser — it composes
+   existing retrieval and applies the documented mapping; anything it cannot ground
+   becomes the literal `da definire`.
+
+4. **Reconcile fields ↔ screens.** Not every field appears on every screen. Per
+   screen decide the shown subset, editable vs readonly, and card grouping —
+   informed by `mockup_analysis.screens[].layout / component_props / states` when
+   present (read as input; owned by `discovery-phase.md`), user intent (standalone),
+   and the entity field set.
+
+5. **Coverage gate (BLOCK vs degrade).** DELEGATE —
+   [references/coverage-gate.md](references/coverage-gate.md). It reuses the
+   `backed / decorative / orphan` vocabulary from `design-system-protocol.md`
+   § Functional Traceability Gate (CITE, never redefine). Field coverage: every
+   screen with ≥1 backing entity must have each shown field present with non-`da
+   definire` `{control, required}`. **BLOCK (interactive):** STOP + ONE consolidated
+   `AskUserQuestion` over the unverified backed screens + unbacked-orphan fields.
+   **DEGRADE:** no formal schema / empty extraction / Codex → downgrade BLOCK to
+   user-confirmation (present best-effort, ask the user to fill `da definire`);
+   never hard-abort.
+
+6. **Fill the mandatory template.** Populate
+   [assets/claude-design-handoff-prompt.template.md](assets/claude-design-handoff-prompt.template.md)
+   with the reconciled per-screen specs + the top-level sections (brand / design
+   system / stack / cosa restituirmi). § 5's numeric constraints are the
+   `{{tokens.*}}` placeholders that **cite** `design-system-protocol.md` § Reference
+   Tables — copy values verbatim from the protocol, never invent numbers. Strip
+   empty conditionals.
+
+7. **Persist the inventory artifact.** Write
+   `${paths.prd_dir}/<slug>/mockups/field-inventory.md` (the reconciled inventory)
+   so it survives restarts and feeds re-entry (`/prd` Step 1.6 Mockup Intake) +
+   downstream `component_bindings` reconciliation. Standalone with no prd-dir
+   convention → present inline + offer to persist.
+
+8. **Emit the prompt.** Present the rendered template inside a fenced markdown
+   code-block, prefixed verbatim:
+
+   > Incolla il prompt qui sotto in Claude Design. Quando hai i mockup pronti,
+   > tornami con i **path locali** dei file (PNG, HTML, TSX, o link Figma) e
+   > riprendo da qui.
+
+   *Delegated* → return the rendered prompt + the `field-inventory.md` path to
+   `/prd`, which owns the state-file mutation (`mockups.handoff_prompt_path`,
+   `mockups.field_inventory_path`, `mockups.status: pending_external`). *Standalone*
+   → save under `${paths.prd_dir}/<slug>/handoff/` and report the paths.
+
+---
+
+## Inline fallbacks (portability + fail-safe)
+
+- **No `Workflow` tool needed** — this skill is prose-orchestrated.
+- **Codex (no subagents):** Step 3's `codebase-architect` degrades to inline Grep
+  (per `references/field-extraction.md`); the gate degrades BLOCK → user-confirmation
+  (Step 5). Runs end-to-end.
+- **No LSP / no code-graph:** silent fallback down the retrieval order. Surface a
+  broken layer via `baldart doctor`, never abort here.
+- **No formal schema in the stack:** the DEGRADE branch — best-effort inventory +
+  user confirmation of every `da definire`. Always-ask-never-assume
+  (`project-context.md` § 3).
+
+## /prd integration
+
+`/prd` Step 3.0 Branch B (`prd/references/ui-design-phase.md`) OWNS the decision to
+hand off to Claude Design; `/ds-handoff` OWNS the prompt. `/prd` invokes this skill
+with the resolved context and presents what it returns. If the skill is unavailable
+(Codex without it linked / an older install), `/prd` falls back to an inline
+**coarse** brief and says so explicitly — the prose stays SSOT, delegate-or-else-inline
+(the same opt-in contract as `/prd` → `/ds-new`).
+
+## See Also
+
+- `framework/agents/design-system-protocol.md` — Functional Traceability Gate
+  (the `backed/decorative/orphan` vocabulary), Reference Tables (the § 5 numbers),
+  the registry cascade this skill's binding column relies on.
+- `framework/.claude/skills/prd/references/discovery-phase.md` — the
+  `mockup_analysis` schema this skill reads as input (NEVER redefines).
+- `framework/.claude/skills/prd/references/ui-design-phase.md` — the `/prd`
+  delegation site (Step 3.0 Branch B) + the re-entry that consumes the artifact.
+- `framework/.claude/skills/ds-new/SKILL.md` / `ds-edit` — when the brief surfaces
+  a genuinely-new component, these create/edit it canonically.
+- `framework/agents/code-search-protocol.md` — the code-graph/LSP/Grep retrieval
+  layer Step 3 composes.

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

@@ -0,0 +1,197 @@
+# Claude Design Handoff Prompt — Field-Level Template
+
+> The MANDATORY template for the Claude Design handoff prompt. Populated by the
+> `ds-handoff` skill ([../SKILL.md](../SKILL.md)) — invoked standalone or
+> delegated from `/prd` Step 3.0 Branch B. This is the **single SSOT** for the
+> prompt shape; the old coarse `/prd` template is retired.
+>
+> All `{{placeholders}}` resolve from the `ds-handoff` field inventory (Steps 1–5),
+> the PRD state file when delegated, `baldart.config.yml`, and optional overlays.
+>
+> Render rules:
+> - Conditional sections (`{{#if …}} … {{/if}}`) are emitted only when true. Skip
+>   the whole section (heading included) when false.
+> - Lists (`{{#each …}}`) render one row/bullet per item; emit "—" if empty.
+> - The rendered output is presented inside a fenced markdown code-block so the
+>   user can copy-paste it verbatim into Claude Design.
+> - **`da definire`** is a real, literal cell value — never a guess. It signals a
+>   fact the field-extraction step could not ground in code; Claude Design must
+>   ask, not invent (always-ask-never-assume).
+
+---
+
+# Feature: {{feature_title}}
+
+## 1. Obiettivo
+
+{{feature_objective_one_sentence}}
+
+## 2. User flow
+
+{{user_flow_summary}}
+
+{{#if primary_personas}}
+**Personas target**:
+{{#each primary_personas}}
+- {{this.name}} — {{this.context}}
+{{/each}}
+{{/if}}
+
+## 3. Schermate in scope — specifica field-level
+
+> **Questo è un contratto 1:1.** Ogni campo, controllo, validazione e opzione
+> qui sotto è **estratto dallo schema dati reale** del progetto. NON inventare,
+> aggiungere o rinominare campi; NON inventare tipi di controllo, validazioni,
+> default o valori di enum. Una cella **`da definire`** = chiedimelo, non
+> indovinarla. Un campo marcato **readonly** è di sola lettura: NON dargli un
+> controllo editabile (input/select/toggle) — rendilo come testo statico.
+>
+> **Vincolo di tracciabilità funzionale.** Inserisci SOLO controlli e affordance
+> (bottoni, icone-azione, voci di menu, tab, toggle) legati a una funzione
+> elencata. Non aggiungere chrome interattivo "per completezza visiva": ogni
+> affordance senza funzione diventa codice morto. Elementi puramente decorativi
+> (icone di sezione, marchi) marcali esplicitamente **decorativi**.
+
+{{#each screens_in_scope}}
+### {{this.name}}
+
+**Identità** — Route: `{{this.route}}`{{#if this.slot_id}} · Artboard: `{{this.slot_id}}`{{/if}}{{#if this.screen_id}} · Screen id: {{this.screen_id}}{{/if}}
+- **Scopo**: {{this.purpose}}
+- **Entità backing**: {{this.backing_entities}}  <!-- es. "Fornitore (supplierSchema)"; "—" se schermata di sola navigazione -->
+
+**Layout (regioni & nesting)**:
+{{#each this.regions}}
+- `{{this.region}}` → **{{this.component}}**{{#if this.props}} ({{this.props}}){{/if}}{{#if this.contains}} → contiene: {{this.contains}}{{/if}}
+{{/each}}
+
+{{#if this.fields}}
+**Field inventory** — ogni riga è un campo reale dello schema:
+
+| Campo (label) | Controllo | Required | Validazione/Vincoli | Default | Opzioni / sorgente enum | Helper text | Mode | Card/gruppo |
+|---|---|---|---|---|---|---|---|---|
+{{#each this.fields}}
+| {{this.label}} | {{this.control}} | {{this.required}} | {{this.validation}} | {{this.default}} | {{this.options}} | {{this.helper}} | {{this.mode}} | {{this.card}} |
+{{/each}}
+{{/if}}
+
+{{#if this.cards}}
+**Raggruppamento in card**:
+{{#each this.cards}}
+- **{{this.title}}**: {{this.fields}}
+{{/each}}
+{{/if}}
+
+{{#if this.actions}}
+**Azioni & interazioni**:
+
+| Azione | Effetto | Destinazione | Abilitata quando | Traccia a |
+|---|---|---|---|---|
+{{#each this.actions}}
+| {{this.action}} | {{this.effect}} | {{this.destination}} | {{this.enabled_when}} | {{this.traces_to}} |
+{{/each}}
+{{/if}}
+
+{{#if this.states}}
+**Stati → rappresentazione**:
+{{#each this.states}}
+- `{{this.state}}` → {{this.representation}}{{#if this.traces_to}} (traccia a {{this.traces_to}}){{/if}}
+{{/each}}
+{{/if}}
+
+{{#if this.list_item}}
+**Dato per-riga / per-card** (lista):
+{{#each this.list_item.fields}}
+- {{this.label}} — {{this.note}}
+{{/each}}
+- Azioni di riga: {{this.list_item.row_actions}}
+- Empty / sort / paginazione: {{this.list_item.list_behavior}}
+{{/if}}
+
+{{#if this.responsive}}
+**Responsive**:
+{{#each this.responsive}}
+- {{this}}
+{{/each}}
+{{/if}}
+
+{{/each}}
+> **Nota per l'export.** Dai al canvas di questa feature un titolo che contenga il
+> nome feature («{{feature_title}}»), e numera gli artboard in modo coerente con
+> gli ID schermata qui sopra (es. screen id 3.1 → artboard `s31`). Scaricherò il
+> bundle completo del workspace per ritrovare esattamente le TUE schermate.
+
+{{#if brand_voice}}
+## 4. Brand & voice
+
+- **Tono**: {{brand_voice.tone}}
+- **Personalità**: {{brand_voice.personality}}
+- **Do**: {{brand_voice.do}}
+- **Don't**: {{brand_voice.dont}}
+{{#if brand_voice.references}}
+- **Riferimenti visivi**: {{brand_voice.references}}
+{{/if}}
+{{/if}}
+
+{{#if has_design_system}}
+## 5. Design system constraints
+
+> Riusa SOLO i token e le primitive elencate. Se devi proporre qualcosa di nuovo,
+> segnalalo esplicitamente nella consegna così posso aggiornare il registro.
+
+### Token chiave
+
+```
+{{design_tokens_excerpt}}
+```
+
+### Primitive da riusare
+
+{{#each registered_primitives}}
+- **{{this.name}}** — {{this.purpose}} ({{this.path}})
+{{/each}}
+
+### Vincoli numerici (da `design-system-protocol.md`)
+
+- Type scale: {{tokens.type_scale}}
+- Spacing scale: {{tokens.spacing_scale}}
+- Radius: {{tokens.radius_scale}}
+- Contrast minimo: {{tokens.contrast_target}} (WCAG AA + APCA Lc ≥ {{tokens.apca_target}})
+- Motion durations: {{tokens.motion_durations}}
+{{/if}}
+
+## 6. Stack target
+
+- **Framework**: {{stack.framework}}
+- **Output preferito**: {{output_format_preference}}  <!-- "HTML/CSS standalone" | "React component (Tailwind)" | "Figma frame" -->
+{{#if stack.charting}}
+- **Charting library**: {{stack.charting}}
+{{/if}}
+{{#if stack.animation}}
+- **Animation library**: {{stack.animation}}
+{{/if}}
+
+## 7. Cosa restituirmi
+
+Per ogni schermata elencata in § 3:
+
+1. **PNG export** ad alta risoluzione (≥ 2x) di OGNI stato richiesto (es. `dettaglio-fornitore__loading.png`, `dettaglio-fornitore__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. **Mappa di tracciabilità campo→funzione** — per OGNI campo della field inventory,
+   conferma che sia presente e col controllo/mode indicati. Se un campo di § 3 manca
+   nel tuo design, **segnalalo, non ometterlo silenziosamente**. Per OGNI elemento
+   interattivo o iconografico, una riga `elemento → funzione che lo motiva`, oppure
+   marcalo **decorativo**. Qualunque elemento non tracciabile elencalo come
+   *orphan da decidere* — così scelgo se dargli funzione, renderlo decorativo o
+   rimuoverlo, invece di implementarlo a vuoto.
+4. **Note inline** su:
+   - Componenti nuovi (non nel registry sopra) introdotti e perché.
+   - Token deviation: qualunque colore/spacing/radius fuori dalla palette sopra, con motivazione.
+   - Decisioni di layout non ovvie (priority sort, hierarchy visiva, density).
+
+Quando hai pronto, dimmi i **path locali** dei file (PNG/HTML/TSX) — li importerò
+in questa sessione per analisi e validazione contro il design system.
+
+---
+
+<!-- baldart-handoff: do-not-edit-manually -->
+<!-- Generated from ds-handoff/assets/claude-design-handoff-prompt.template.md by the ds-handoff skill -->

package/framework/.claude/skills/ds-handoff/references/coverage-gate.md

@@ -0,0 +1,109 @@
+# Coverage gate — verify the fields BEFORE emitting the prompt
+
+`ds-handoff` Step 5. The gate that makes the brief 1:1: it refuses to emit a prompt
+whose backed screens have unverified fields, so Claude Design never has to imagine.
+It reuses the `backed / decorative / orphan` vocabulary from
+`design-system-protocol.md` § Functional Traceability Gate — **CITE it, never
+redefine it**. That gate governs *interactive/iconographic affordances*; this gate
+applies the same discipline one level deeper, to **data fields**.
+
+## What is checked
+
+### Axis 1 — Field coverage (the BLOCK condition)
+
+For every screen with **≥ 1 backing entity** (Step 2): each shown field in its
+inventory must be present with, at minimum, a non-`da definire` **Controllo** and
+**Required**. A backed screen whose inventory is empty, or whose shown fields carry
+`da definire` in `{control, required}`, is **unverified** → a BLOCK condition.
+
+Validation / default / helper / enum-source cells MAY remain `da definire` (they
+degrade gracefully — Claude Design will ask), but `{control, required}` are the
+floor: without them the design tool cannot even place the right widget.
+
+### Axis 2 — Field traceability (advisory + resolve)
+
+Reuse the protocol's classification, applied to fields:
+
+| Class | Definition | Outcome |
+|---|---|---|
+| **Backed** | Field exists in the entity schema AND is placed on a screen | OK — in the inventory |
+| **Decorative** | Static display (a computed value shown read-only, a label) | `mode: readonly`, never blocks |
+| **Orphan — unbacked** | A field in the inventory that traces to NO schema field | Resolve: "da definire o rimuovere" — escalate (see below) |
+| **Orphan — unplaced** | A schema field placed on NO screen in scope | **Advisory** — surface "confermare se fuori scope"; NOT a BLOCK |
+
+## BLOCK vs DEGRADE
+
+**BLOCK (interactive mode, a human is present):** STOP. Do not emit the prompt.
+Surface — never silently — every unverified backed screen and every unbacked-orphan
+field, then raise **ONE consolidated `AskUserQuestion`** (consistent with
+always-ask-never-assume and "no silent deferral"). Offer per item: supply the
+missing fact / mark the field decorative-readonly / drop it. Only after the user
+resolves them do you proceed to Step 6.
+
+**DEGRADE (graceful, never hard-abort):** downgrade BLOCK → user-confirmation when
+- no formal schema exists in the stack (the entity is plain TS objects / untyped), OR
+- field extraction returned empty across all retrieval tiers, OR
+- running under Codex with no subagents / no-TTY.
+
+In DEGRADE: present the best-effort inventory with its `da definire` cells visible,
+and ask the user to fill or confirm them before emission. The prompt still ships —
+with honest `da definire` cells the user has seen — rather than aborting the flow.
+
+## False-positive guards (do NOT block on these)
+
+By construction the gate excludes:
+- **Zero-entity screens** — pure navigation / dashboard chrome / marketing screens
+  have no backing entity and so no field-coverage obligation. Never block them.
+- **Decorative regions** — labels, section icons, computed read-only displays.
+- **Framework noise** — `.framework/`, `.baldart/`, telemetry/generated files are
+  never a backing schema.
+- **Unplaced schema fields** — advisory only (a field legitimately out of this
+  feature's scope is not a defect).
+
+The BLOCK condition is deliberately narrow: *a backed screen whose inventory is
+empty or has unverified `{control, required}`*. Everything else informs, not blocks.
+
+## Worked example — "Fornitori" (suppliers)
+
+Backing schema discovered in Step 3:
+
+```ts
+const supplierSchema = z.object({
+  ragione_sociale: z.string().min(1).max(120),
+  partita_iva:     z.string().regex(/^IT\d{11}$/),
+  email:           z.string().email().optional(),
+  categoria:       z.enum(["materie_prime", "servizi", "logistica"]),
+  pagamento_giorni: z.number().int().min(0).max(120).default(30),
+  attivo:          z.boolean().default(true),
+  note:            z.string().max(500).optional(),
+  created_at:      z.date(),   // server-set
+});
+```
+
+Reconciled inventory for **Dettaglio Fornitore** (`/fornitori/:id`, screen 3.2,
+backing: `Fornitore (supplierSchema)`):
+
+| Campo (label) | Controllo | Req | Validazione/Vincoli | Default | Opzioni / enum | Helper text | Mode | Card |
+|---|---|---|---|---|---|---|---|---|
+| Ragione sociale | text input | sì | 1–120 caratteri | — | — | da definire | editable | Anagrafica |
+| Partita IVA | text input | sì | pattern `IT` + 11 cifre | — | — | "Formato: IT01234567890" (da confermare) | editable | Anagrafica |
+| Email | email input | no | formato email | — | — | da definire | editable | Contatti |
+| Categoria | select | sì | enum | — | materie_prime · servizi · logistica | da definire | editable | Anagrafica |
+| Giorni pagamento | number input | sì | intero 0–120 | 30 | — | "Termini di pagamento" (da confermare) | editable | Condizioni |
+| Attivo | toggle | no | boolean | true | — | da definire | editable | Stato |
+| Note | textarea | no | max 500 caratteri | — | — | da definire | editable | Note |
+| Creato il | testo statico | — | — | — | — | — | readonly | Metadati |
+
+Actions:
+
+| Azione | Effetto | Destinazione | Abilitata quando | Traccia a |
+|---|---|---|---|---|
+| Salva | PATCH /suppliers/:id | resta su dettaglio + toast | form valido & dirty | US-fornitori-edit |
+| Annulla | scarta modifiche | torna a /fornitori | sempre | US-fornitori-edit |
+| Elimina | DELETE /suppliers/:id | torna a /fornitori | fornitore non collegato a ordini | da definire (orphan?) |
+
+Gate verdict on this screen: **PASS the BLOCK floor** — every shown field has a
+grounded `{control, required}`. The `da definire` helper cells and the `Elimina`
+enable-condition/traceability are surfaced (advisory) so the user can resolve them,
+but they do not block emission. `created_at` is correctly `readonly` (testo statico,
+no input) — the exact hallucination the gate prevents.