baldart 4.78.2 → 4.79.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.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.79.0

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.

package/framework/.claude/skills/ds-handoff/references/field-extraction.md

@@ -0,0 +1,78 @@
+# Field extraction — locating and reading the real fields
+
+How `ds-handoff` Step 3 grounds the field inventory in the project's actual data
+schemas. This is **retrieval composition + a mapping table**, NOT a new parser.
+The skill ships no Zod/AST extractor (that would be over-scoped and fragile across
+stacks; contrast `design-system-init`'s `extract-one.mjs`, justified only because a
+manifest HEAD must be byte-deterministic — a prose handoff tolerates LLM extraction
+behind the Step 5 coverage gate).
+
+## Retrieval order (each with silent fallback)
+
+Resolve the backing schema/type/form for each entity from Step 2, top to bottom.
+Stop at the first tier that returns the field set; degrade silently down the list.
+
+1. **Code-graph** — when `features.has_code_graph: true`. Use it to find the
+   schema/type/form definition and (bonus) which screens consume it. DELEGATE
+   `framework/agents/code-graph-protocol.md`.
+2. **LSP** — when `features.has_lsp_layer: true`. `go-to-definition` /
+   `find-references` on the entity symbol (e.g. `supplierSchema`) to jump straight
+   to the definition without grepping a common name. DELEGATE
+   `framework/agents/code-search-protocol.md`.
+3. **`codebase-architect`** (Task tool) — the workhorse. Ask it to locate the
+   entity's Zod schema / TS interface / form schema (react-hook-form, Formik, a
+   server action's input) and **return the field facts as structured data** (one
+   row per field with the columns below). Read-only exploration; it does not parse
+   ASTs for you — it reads the source and reports. Honor its return contract
+   (`framework/agents/return-contract-protocol.md`).
+4. **Grep** — last resort / Codex. Patterns: `z.object(`, `interface .*Props`,
+   `type .* = {`, `useForm`, `zodResolver`, `createInsertSchema` (drizzle-zod),
+   the entity name. Read the matched file directly.
+
+**Exclude framework noise** from every tier: `.framework/`, `.baldart/`,
+generated/telemetry files. These never back a product screen.
+
+## Per-field capture (the 9 inventory columns)
+
+For each field, capture exactly what the template's field-inventory table needs.
+Anything you cannot ground in code is the **literal `da definire`** — never a guess.
+
+| Column | Source in code | If ungrounded |
+|---|---|---|
+| **Campo (label)** | Humanize the field name; or the i18n registry source string when `features.has_i18n: true` (`paths.i18n_registry`); or an explicit `label`/JSDoc. | humanized name + note |
+| **Controllo** | The control-type mapping below. | `da definire` |
+| **Required** | `sì` unless `.optional()` / `.nullish()` / `?` / `.partial()`. | `da definire` |
+| **Validazione/Vincoli** | `.min()`/`.max()`/`.length()`/`.regex()`/`.email()`/`.url()`/`.int()`/`.positive()`/refinements. | `—` if none |
+| **Default** | `.default(x)` / a form `defaultValues` entry. | `—` if none |
+| **Opzioni / sorgente enum** | `z.enum([...])` / `z.nativeEnum` literals verbatim; a `z.string()` whose options come from a runtime query → `"query runtime — da definire"`. | `—` / `da definire` |
+| **Helper text** | JSDoc on the field; the i18n `context` for the key; an existing form description. | `da definire` |
+| **Mode** | `editable` by default; `readonly` for server-set / computed fields (see below). | `editable` |
+| **Card/gruppo** | From `mockup_analysis.screens[].layout` when present, else the reconciliation decision (Step 4). | `da definire` |
+
+## Control-type mapping (applied by the agent, not a CLI)
+
+A documented heuristic — apply it, but prefer an explicit signal (an existing
+component binding, a form control already in code) over the heuristic when present.
+
+| Schema / type shape | Control |
+|---|---|
+| `z.enum([...])` / `z.nativeEnum` / union of string literals | `select` (or `radio` for ≤ 3 options / `segmented` per project convention) |
+| `z.boolean()` | `toggle` (or `checkbox`) |
+| `z.string()` short (no/small `.max`) | `text input` |
+| `z.string()` long (`.max` ≥ ~200, or named `notes`/`description`/`body`) | `textarea` |
+| `z.string().email()` | `email input` |
+| `z.string().url()` | `url input` |
+| `z.string()` matching a phone/postal regex | typed input (`phone`/`postal`) |
+| `z.number()` / `z.coerce.number()` | `number input` (or `price`/`percent` per unit) |
+| `z.date()` / `z.string().datetime()` | `date picker` — **readonly** if server-set/computed |
+| `z.array(...)` of a sub-object | repeatable group / multi-row editor |
+| `z.array(z.string())` from a known set | `multi-select` |
+| `z.object(...)` nested | a sub-group / sub-card |
+
+## Readonly detection
+
+Mark a field **readonly** (static text, no editable control) when it is not
+user-authored: server-set timestamps (`created_at`, `updated_at`), derived/computed
+values, IDs, audit fields, anything the schema marks server-generated or that the
+form's `defaultValues` sets but the UI never edits. A field drawn as an input when
+it is in truth readonly is the classic Claude Design hallucination this prevents.

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

@@ -30,35 +30,50 @@ unchanged. No other side-effect of Step 3.0.
 
 ### Branch B — Claude Design handoff
 
-1. **Collect context from the state file + config + overlays:**
-   - `feature_title`, `feature_objective_one_sentence` from `## Feature Description`.
-   - `user_flow_summary`, `primary_personas` from `## Discovery Log` (dimensions 1 + 2).
-   - `screens_in_scope[]` from `## UI Design` (derive from User Stories + ISA touchpoints if not yet populated — same logic as Hybrid mode § "Build the per-screen routing table").
-   - `brand_voice` from `.baldart/overlays/prd.md` if present (skip section otherwise).
-   - When `features.has_design_system: true`: read `${paths.design_system}/INDEX.md` (primitive list) + `${paths.design_system}/tokens-reference.md` (tokens excerpt). When `false`: omit § 5 of the prompt entirely.
-   - `stack.framework`, `stack.charting`, `stack.animation` from `baldart.config.yml`.
-   - `output_format_preference` derived from `stack.framework` (Next/Remix → React+Tailwind; vanilla → HTML/CSS; otherwise ask the user).
-   - Numeric token tables (type scale, spacing, radius, contrast, motion durations) from `framework/agents/design-system-protocol.md` — cite verbatim.
-
-2. **Render the prompt** by populating
-   [../assets/claude-design-handoff-prompt.template.md](../assets/claude-design-handoff-prompt.template.md)
-   with the collected context. Strip empty conditional sections.
-
-3. **Present the rendered prompt** to the user inside a fenced markdown
-   code-block, prefixed with this instruction (verbatim):
+The handoff prompt is owned by the **`ds-handoff` skill** (the single SSOT). `/prd`
+decides to hand off; `/ds-handoff` builds the field-level, 1:1 brief — it grounds
+every screen's fields in the real data schemas and runs a coverage gate **before**
+emitting, so Claude Design does not have to imagine the fields. (This is the same
+delegate-or-else-inline contract as `/prd` → `/ds-new`.)
+
+1. **Delegate to `/ds-handoff`.** Invoke it in *delegated* mode, passing the
+   resolved context so it skips its own screen-resolution prompt:
+   - the state-file path;
+   - `feature_title`, `feature_objective_one_sentence` (from `## Feature Description`);
+   - `user_flow_summary`, `primary_personas` (from `## Discovery Log` dimensions 1 + 2);
+   - `screens_in_scope[]` from `## UI Design` (derive from User Stories + ISA
+     touchpoints if not yet populated — same logic as Hybrid mode § "Build the
+     per-screen routing table");
+   - `mockup_analysis` from `## UI Design` if present (the skill reads its
+     `layout / component_props / states / responsive` as input);
+   - the `features.has_design_system` flag (the skill omits § 5 when `false`).
+
+   `/ds-handoff` runs field extraction + the coverage gate + the mandatory template
+   and returns the **rendered prompt** plus the **`field-inventory.md` path**.
+
+   **Graceful fallback** — if `/ds-handoff` is unavailable (Codex without it linked,
+   or an older install): render a **coarse** brief inline from `screens_in_scope[]`
+   (per-screen: scopo / stati / azioni primarie / dati visualizzati) and the same
+   top-level sections (obiettivo, user flow, brand, design system, stack, cosa
+   restituirmi). State explicitly to the user: *"field-level brief non disponibile →
+   brief coarse"*, so the lost fidelity is visible, not silent.
+
+2. **Present the returned prompt** to the user inside a fenced markdown code-block,
+   prefixed with this instruction (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 — copio i file nella cartella del PRD, li analizzo come
    > al solito (Step 1.6 Mockup Intake), e Step 3 entra in Hybrid mode.
 
-4. **Update state file** before stopping:
+3. **Update state file** before stopping:
    - `mockups.status: pending_external`
    - `mockups.source: claude-design`
    - `mockups.handoff_prompt_path: ${paths.prd_dir}/<slug>/handoff/claude-design-prompt.md` (save the rendered prompt to disk so it survives session restarts).
+   - `mockups.field_inventory_path: ${paths.prd_dir}/<slug>/mockups/field-inventory.md` (the path `/ds-handoff` returned; omit on the coarse fallback).
    - `step_3_mode: pending_external_handoff` (transitional — overwritten when user returns).
 
-5. **STOP.** Wait for the user to return with local paths.
+4. **STOP.** Wait for the user to return with local paths.
 
 ### Re-entry from handoff (user returns with paths)
 

package/framework/agents/skills-mapping.md

@@ -24,6 +24,10 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 > This map references **only skills shipped under `framework/.claude/skills/`**.
 > Confirm a skill exists (its directory is present) before routing to it; never
 > route to a skill name that has no directory.
+>
+> **Gating.** Many skills are gated on a `features.*` flag in `baldart.config.yml`
+> (noted per entry). When the flag is `false` the skill REFUSES — do not route to
+> it; resolve the gate first (e.g. `/design-system-init` for `has_design_system`).
 
 ## Core Development Skills
 
@@ -43,6 +47,19 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - "Nuova funzionalità"
 - "How should I scope..."
 
+### prd-add
+
+**When to use**:
+
+- A new requirement lands on an ACTIVE `/prd` session (change request)
+- "serve anche…", a missing endpoint/sub-feature surfaces mid-discovery
+- Runs ICIAS impact analysis to decide which PRD phases SKIP / PATCH / REDO
+
+**Triggers**:
+
+- "/prd-add"
+- "Aggiungi requisito" / "Serve anche" / "Manca un endpoint"
+
 ### context-primer
 
 **When to use**:
@@ -68,6 +85,20 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - "Implementa le card"
 - "Esegui le card"
 
+### new2
+
+**When to use**:
+
+- EXPERIMENTAL workflow-hosted variant of `/new` (A/B testing context economy)
+- The whole card batch runs in a background dynamic workflow (subagent output never
+  enters the main context); every `/new` gate becomes a deterministic policy
+- **Claude-only** (needs the `Workflow` tool)
+
+**Triggers**:
+
+- "/new2 CARD-IDS"
+- "Implementa le card con workflow"
+
 ### bug
 
 **When to use**:
@@ -82,6 +113,30 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - "Fix [bug]"
 - "Non funziona" / "Why is [X] not working?"
 
+### worktree-manager
+
+**When to use**:
+
+- Parallel coding agents needing fully independent git worktrees
+- Create / merge (→ PR) / list / cleanup isolated workspaces
+- Used programmatically by `/new` for per-card worktree ops
+
+**Triggers**:
+
+- "/nw" (new) · "/mw" (merge) · "/lw" (list) · "/cw" (cleanup)
+- "New worktree" / "Merge worktree"
+
+### issue-review
+
+**When to use**:
+
+- Triage / planning a GitHub issue (summary + priority + plan + tests)
+
+**Triggers**:
+
+- "/issue-review"
+- "Triage this issue" / "Review issue [N]"
+
 ## Code Quality Skills
 
 ### simplify
@@ -136,7 +191,129 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 > standalone invocable BALDART skill. Route UI work through `ui-design` /
 > `ui-expert`, not to `ui-ux-pro-max` directly.
 
-## Testing Skills
+### motion-design
+
+**When to use**:
+
+- Animations, transitions, micro-interactions, loading/page transitions
+- Scroll-triggered effects, choreography, timing/easing decisions
+- Works with CSS / Framer Motion / GSAP / Lottie / Spring
+
+**Triggers**:
+
+- "/motion-design"
+- "Anima…" / "transition" / "micro-interaction"
+
+### gamification-design
+
+**When to use**:
+
+- Points systems, reward loops, progression mechanics, loyalty/retention
+- B2C customer-facing engagement features
+
+**Triggers**:
+
+- "/gamification-design"
+- "Punti / reward / progression / battle pass / loyalty"
+
+## Design System Skills
+
+> All gated on `features.has_design_system: true`. Without a registry, bootstrap
+> first with `/design-system-init`.
+
+### design-system-init
+
+**When to use**:
+
+- GREENFIELD: bootstrap a component registry (INDEX.md + DTCG tokens + per-component specs) and flip `has_design_system`
+- UPGRADE: regenerate machine-readable HEADs / DTCG tokens on an existing prose-only registry
+- SEED: a registry born in Claude Design (design-led)
+
+**Triggers**:
+
+- "/design-system-init"
+- "Crea design system" / "inizializza registro componenti" / "aggiorna le spec"
+- `baldart doctor` nudges (specs missing / prose-only)
+
+### ds-new
+
+**When to use**:
+
+- Create ONE canonical element (a component OR a token) end-to-end: reuse-first → optional scaffold → document + register + govern + verify
+- The on-the-fly twin of the bulk `design-system-init`; callable by `/prd` when reconciliation confirms a NEW component
+
+**Triggers**:
+
+- "/ds-new" · "/ds-new token [id]"
+- "Nuovo componente design system" / "registra una primitive" / "aggiungi un token"
+
+### ds-edit
+
+**When to use**:
+
+- Deliberately edit ONE existing element: resync / extend-variant / breaking / re-govern
+- Regenerates the spec preserving agentic fields + prose
+- NOT for the automatic mechanical doc-resync after a code change (that's already automatic via the `DS_COMPONENT_STALE` gate)
+
+**Triggers**:
+
+- "/ds-edit"
+- "Aggiungi una variante" / "modifica un componente" / "breaking change su un componente"
+
+### ds-render
+
+**When to use**:
+
+- Render design-system primitives in ISOLATION (one component × variant) to a PNG each
+- Feeds isolated QUALITY verification (`/e2e-review` Phase 4b/4c) — never a fidelity diff
+- Rides on a detected Storybook (clean no-op otherwise)
+
+**Triggers**:
+
+- "/ds-render"
+- "Render i componenti" / "screenshot dei primitivi"
+
+### ds-handoff
+
+**When to use**:
+
+- Produce the FIELD-LEVEL, 1:1 Claude Design handoff prompt — every screen's real fields (label / control / required / validation / default / enum / helper / readonly), grounded in the project's data schemas, coverage-gated before emission
+- The single SSOT for the Claude Design prompt; `/prd` Step 3.0 Branch B delegates here
+- Standalone for an ad-hoc orchestrator + `ui-expert` run
+
+**Triggers**:
+
+- "/ds-handoff [screens-or-feature]"
+- "Handoff a Claude Design" / "prompt per Claude Design" / "brief field-level"
+
+### design-sync
+
+**When to use**:
+
+- Mirror the in-repo registry (SSOT) UP to its Claude Design satellite (the code→design half of the closed loop)
+- `publish` / `bootstrap` / `drift` modes; delegates every write to the DesignSync MCP; refuse-on-divergence
+- Claude-only; interactive-auth (`/design-login`); no-op without a bound satellite
+
+**Triggers**:
+
+- "/design-sync"
+- "Pubblica il design system" / "mirror su Claude Design" / "il designer ha cambiato qualcosa"
+
+## Testing & Review Skills
+
+### e2e-review
+
+**When to use**:
+
+- Deterministic BLOCKING end-to-end review after a feature is implemented
+- Functional E2E (Playwright) + visual fidelity diff + design-quality critic, under a severity gate + bounded self-heal
+- Auto-called by `/new` Phase 2.6; invocable manually
+- Gated on `features.has_e2e_review`
+
+**Triggers**:
+
+- "/e2e-review CARD-ID"
+- "Verifica end-to-end" / "review schermate" / "controlla i mockup"
 
 ### playwright-skill
 
@@ -166,7 +343,7 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - Integration testing
 - Server management needed
 
-## Documentation Skills
+## Documentation & Knowledge Skills
 
 ### doc-writing-for-rag
 
@@ -180,6 +357,64 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - "doc per RAG" / "dense documentation"
 - "template endpoint" / "compattare docs"
 
+### capture
+
+**When to use**:
+
+- Distill a cross-document synthesis of the recent conversation into a reusable wiki synthesis page
+- Implements Karpathy's query→wiki file-back loop
+- Gated on `features.has_wiki_overlay`
+
+**Triggers**:
+
+- "/capture"
+- "Salva sintesi" / "distilla conversazione" / "questa conversazione in wiki"
+
+### graph-align
+
+**When to use**:
+
+- On-demand documentation alignment via the Graphify code knowledge graph
+- Surface core code with no doc coverage, stale docs, drift vs the SSOT registry
+- The interactive twin of the nightly `doc-graph-align` routine
+- Gated on `features.has_code_graph`
+
+**Triggers**:
+
+- "/graph-align"
+- "Allinea la documentazione" / "check doc coverage"
+
+## Internationalization Skills
+
+> Gated on `features.has_i18n: true`.
+
+### i18n
+
+**When to use**:
+
+- Audit the i18n context registry against `t()` calls + native locale files (drift codes)
+- Context-aware translation of missing/stale labels via the `i18n-translator` agent
+- The interactive twin of the weekly `i18n-align` routine
+
+**Triggers**:
+
+- "/i18n"
+- "Traduci le label" / "audit i18n" / "allinea le traduzioni"
+
+### i18n-adopt
+
+**When to use**:
+
+- One-shot migration that externalizes ALL hardcoded user-facing strings on an existing codebase (the i18n analogue of `/design-system-init`)
+- Full-auto on a dedicated branch, idempotent + resumable; never auto-merges
+
+**Triggers**:
+
+- "/i18n-adopt"
+- "Migra a i18n" / "adotta i18n" / "externalize all strings"
+
+## Product & Content Skills
+
 ### copywriting
 
 **When to use**:
@@ -193,6 +428,152 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - "Migliora il testo"
 - Landing/marketing content
 
+### seo-audit
+
+**When to use**:
+
+- Audit / diagnose technical + on-page SEO issues on a site
+
+**Triggers**:
+
+- "/seo-audit"
+- "SEO audit" / "why am I not ranking" / "meta tags review"
+
+### api-design-principles
+
+**When to use**:
+
+- Designing a new API, reviewing an API spec, establishing API design standards (REST / GraphQL)
+
+**Triggers**:
+
+- "/api-design-principles"
+- "Design this API" / "review API spec"
+
+## Integration Skills
+
+### kie-ai
+
+**When to use**:
+
+- Generate images / videos / audio via Kie.ai (80+ models), upscaling, background removal, TTS/SFX
+
+**Triggers**:
+
+- "/kie" / "/generate-image" / "/generate-video"
+- "Genera immagine / video", model names ("nano banana", "veo", "kling", "suno"…)
+
+### remotion-best-practices
+
+**When to use**:
+
+- Building video in React with Remotion (best practices guidance)
+
+**Triggers**:
+
+- "Remotion" / "video in React"
+
+## Retrieval & Toolchain Bootstrap Skills
+
+> Install/verify opt-in layers. Each is gated on its `features.*` flag and is
+> idempotent (re-running re-verifies + reports drift).
+
+### lsp-bootstrap
+
+**When to use**:
+
+- Install + verify the LSP symbol-search layer (language servers, `lsp.installed_servers`)
+- After enabling `features.has_lsp_layer`
+
+**Triggers**:
+
+- "/lsp-bootstrap"
+- "Install LSP" / "set up symbol search"
+
+### graphify-bootstrap
+
+**When to use**:
+
+- Install + verify + wire the Graphify code-knowledge-graph layer (CLI, offline graph build, auto-rebuild hook, MCP)
+- After enabling `features.has_code_graph`
+
+**Triggers**:
+
+- "/graphify-bootstrap"
+- "Install graphify" / "set up the code graph"
+
+### toolchain-bootstrap
+
+**When to use**:
+
+- Install + verify + wire the curated dev toolchain (Biome / Vitest / tsc / Lefthook) as devDeps
+- After enabling `features.has_toolchain`
+
+**Triggers**:
+
+- "/toolchain-bootstrap"
+- "Install the toolchain" / "set up biome"
+
+## Framework Maintenance & Meta Skills
+
+### baldart-update
+
+**When to use**:
+
+- Bring the BALDART framework up-to-date in a consumer repo (seamless `npx baldart update --yes`)
+- The skill narrates the CLI; it never re-implements it
+
+**Triggers**:
+
+- "/baldart-update"
+- "Aggiorna baldart" / "update del framework"
+
+### baldart-push
+
+**When to use**:
+
+- Contribute local framework improvements upstream to the BALDART repo
+- Hands off to `npx baldart push` (interactive); never pushes project-specific customizations
+
+**Triggers**:
+
+- "/baldart-push"
+- "Contribuisci al framework" / "push del framework"
+
+### overlay
+
+**When to use**:
+
+- Author `.baldart/overlays/` — the per-project customisation layer for skills / agents / commands
+- Scaffolds + validates + surfaces drift via the CLI; often the answer when the `framework-edit-gate` hook blocked a direct edit
+
+**Triggers**:
+
+- "/overlay"
+- "Customizza skill" / "override agent" / "personalizza comando"
+
+### skill-creator
+
+**When to use**:
+
+- Create a new skill, or modify/optimize/measure an existing one
+
+**Triggers**:
+
+- "/skill-creator"
+- "Crea una skill" / "improve this skill"
+
+### find-skills
+
+**When to use**:
+
+- Discover/install agent skills when a needed capability might already exist as a skill
+
+**Triggers**:
+
+- "/find-skills"
+- "Is there a skill that…" / "how do I do X"
+
 ## Project-Specific Skills
 
 Add your project-specific skills here:
@@ -214,7 +595,8 @@ START: User gives a task
   |
   v
 Is it a new feature needing scope/plan?
-  |-- YES --> /prd (scopes + plans + writes cards)
+  |-- YES --> /prd (scopes + plans + writes cards; UI phase delegates the
+  |           Claude Design prompt to /ds-handoff)
   |           Then /new (implements the cards end-to-end)
   |
   v
@@ -223,11 +605,22 @@ Is it a bug fix?
   |
   v
 Is it UI/visual work?
-  |-- YES --> /ui-design (mockups/options) or frontend-design
+  |-- YES --> /ui-design (mockups/options) or frontend-design;
+  |           motion → /motion-design
   |
   v
-Is it browser testing?
-  |-- YES --> playwright-skill or webapp-testing (E2E via /e2e-review)
+Is it design-system work (a component / token / handoff)?
+  |-- YES --> /ds-new (create) · /ds-edit (change) · /ds-render (isolate) ·
+  |           /ds-handoff (Claude Design prompt) · /design-sync (mirror)
+  |           (bootstrap the registry first with /design-system-init)
+  |
+  v
+Is it internationalization?
+  |-- YES --> /i18n (audit + translate) or /i18n-adopt (one-shot migration)
+  |
+  v
+Is it browser/E2E testing or review?
+  |-- YES --> playwright-skill / webapp-testing / /e2e-review (blocking)
   |
   v
 Is it cleanup/complexity reduction?
@@ -250,7 +643,15 @@ Common skill chains (all skills below are shipped under `.claude/skills/`):
 3. **UI Feature**:
    - /prd → /ui-design → /new → playwright-skill (or /e2e-review for blocking E2E)
 
-4. **Refactoring**:
+4. **UI Feature via Claude Design handoff**:
+   - /prd (Branch B) → /ds-handoff (field-level prompt) → [design in Claude Design]
+     → /prd re-entry (mockup intake) → /new → /e2e-review
+
+5. **Design System**:
+   - /design-system-init (bootstrap) → /ds-new / /ds-edit (evolve) → /ds-render
+     (verify isolated) → /design-sync (mirror to the satellite)
+
+6. **Refactoring**:
    - /simplify (identify + apply cleanups) → /new gates re-run lint/tsc/tests
 
 ## Anti-Patterns
@@ -263,6 +664,7 @@ Common skill chains (all skills below are shipped under `.claude/skills/`):
 - Claim completion before the `/new` review + gate cycle passes
 - Use wrong skill for the task
 - Route to a skill name that has no directory under `.claude/skills/`
+- Route to a feature-gated skill when its `features.*` flag is `false`
 
 **Do**:
 

package/package.json

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

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

@@ -1,137 +0,0 @@
-# Claude Design Handoff Prompt — Template
-
-> Template populated at runtime by **Step 3.0 (Mockup Source Decision)** in
-> [../references/ui-design-phase.md](../references/ui-design-phase.md) when the
-> user picks the **handoff** branch. All `{{placeholders}}` are resolved from the
-> PRD state file (`${paths.prd_dir}/sessions/YYYY-MM-DD-<slug>-state.md`),
-> `baldart.config.yml`, and optional overlays.
->
-> Render rules:
-> - Conditional sections (marked `{{#if …}} … {{/if}}`) are emitted only when the
->   condition is true. Skip the entire section (including its heading) when false.
-> - Lists (marked `{{#each …}}`) render one bullet per item; emit "—" if empty.
-> - The rendered output is presented to the user inside a fenced markdown
->   code-block so they can copy-paste verbatim into Claude Design.
-
----
-
-# 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
-
-> **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}}
-
-- **Scopo**: {{this.purpose}}
-- **Stati richiesti**: {{this.states_required}}  <!-- empty, loading, populated, error, success, ecc. -->
-- **Azioni primarie**: {{this.primary_actions}}
-- **Dati visualizzati**: {{this.data_shown}}
-{{#if this.notes}}
-- **Note**: {{this.notes}}
-{{/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. schermata 3.1 → artboard `s31`). Scaricherò il bundle
-> completo del workspace: questo mi permette di ritrovare esattamente le TUE schermate
-> ed evitare ambiguità con le altre feature.
-
-{{#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. `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. **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).
-
-Quando hai pronto, dimmi i **path locali** dei file (PNG/HTML/TSX) — li importerò in questa sessione PRD per analisi e validazione contro il design system.
-
----
-
-<!-- baldart-handoff: do-not-edit-manually -->
-<!-- Generated from claude-design-handoff-prompt.template.md by /prd Step 3.0 -->