baldart 4.83.0 → 4.84.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.84.0] - 2026-07-01
+
+**`/ds-handoff` decision & preference pass — anticipa le domande di Claude Design invece di rimandargliele.** Il prompt field-level di `ds-handoff` copriva un solo asse (correttezza dei *campi* via field-extraction + coverage gate) e lasciava scoperto il **secondo asse — le decisioni di design aperte + le preferenze di consegna** — che è esattamente ciò su cui Claude Design rimanda le domande all'utente (nel caso reale "Hub fornitore", 6 domande su 6 erano su questo asse, zero sui campi). Una era **auto-inflitta** (il PRD diceva *"da proporre"* e la skill l'ha inoltrata testualmente), un'altra su un fatto **già in mano alla skill** (enum categoria con `color`) mai tradotto in istruzione.
+
+Il fix è **combinato**: (1) un nuovo **Step 5.5 — Decision & preference pass** (`references/decision-pass.md`) che risolve PRIMA di emettere le scelte aperte / formato consegna / scope stati / canvas / varianti — **triggered, non always-on** (stessa filosofia del BLOCK del coverage gate: parte solo se c'è un irrisolto, UNA `AskUserQuestion` consolidata, no-op quando nulla è aperto; per le decisioni aperte offre "decido io" vs "fai proporre N opzioni a Claude Design"); (2) **arricchimento** che pre-compila i fatti rilevabili — nuova **§ 0 "Direttive di consegna & decisioni"** nel template + regola **enum presentazionale** in `field-extraction.md` (metadata `color`/`icon`/`badge`/`label` → render hint automatico, non una domanda). Attivo standalone **e** delegato da `/prd` (Branch B ora inoltra le preferenze già risolte in Discovery → la skill riconcilia e chiede solo il residuo). **DEGRADE** su Codex/no-TTY: bake dei default DICHIARATI in § 0, mai abort.
+
+Resta un *thin orchestrator*, **nessun dual-SSOT** (delivery/placement/varianti non sono in `design-system-protocol.md`). **MINOR** — capability additiva su una skill esistente. **Nessuna nuova chiave `baldart.config.yml`** (rides on `features.has_design_system`) → la schema-change propagation rule NON si applica. Skill versionata `1.0.0 → 1.1.0` (bump `version` + entry nel `CHANGELOG.md` per-skill, stesso edit).
+
+### Added
+
+- **`framework/.claude/skills/ds-handoff/references/decision-pass.md`** — il pre-emit Step 5.5: trigger inventory, `AskUserQuestion` consolidata, DEGRADE bake-defaults, riconciliazione in modalità delegata, false-positive guards.
+
+### Changed
+
+- **`framework/.claude/skills/ds-handoff/SKILL.md`** — nuovo Step 5.5 nel workflow, Step 6 popola anche § 0, Invocation + Inline fallbacks aggiornati; `version: 1.0.0 → 1.1.0`.
+- **`framework/.claude/skills/ds-handoff/assets/claude-design-handoff-prompt.template.md`** — nuova § 0 "Direttive di consegna & decisioni"; § 7 rimanda a § 0 per il formato export.
+- **`framework/.claude/skills/ds-handoff/references/field-extraction.md`** — regola enum presentazionale (render hint automatico) nel mapping + sezione dedicata.
+- **`framework/.claude/skills/prd/references/ui-design-phase.md`** — Branch B inoltra a `/ds-handoff` le preferenze di consegna/decisione già emerse in Discovery.
+- **`framework/.claude/skills/ds-handoff/CHANGELOG.md`** — entry `1.1.0`.
+
 ## [4.83.0] - 2026-07-01
 
 **Versioned root-file primitives — BALDART now generates `AGENTS.md` + `CLAUDE.md` from SOTA skeletons.** Previously `AGENTS.md` was a bulk symlink into the framework payload (not customizable without losing auto-update) and `CLAUDE.md` was not shipped at all. Now both are **generated real files**, produced on every install/update from **versioned skeletons** under `framework/templates/primitives/`.

package/VERSION

@@ -1 +1 @@
-4.83.0
+4.84.0

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

@@ -2,6 +2,26 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.1.0 — 2026-07-01
+
+- **Decision & preference pass (Step 5.5)** — nuovo `references/decision-pass.md`.
+  Chiude l'asse *decisioni* (accanto all'asse *campi* del coverage gate): risolve
+  PRIMA di emettere le scelte di design aperte + preferenze di consegna che Claude
+  Design altrimenti rimanda all'utente come domande (token `da proporre`, formato
+  consegna, scope stati, canvas/placement, appetito varianti). Triggered-not-always-on,
+  UNA `AskUserQuestion` consolidata, no-op quando nulla è aperto; per le decisioni
+  aperte offre "decido io" vs "fai proporre N opzioni a Claude Design".
+- **Template § 0 "Direttive di consegna & decisioni"** — nuova sezione che porta le
+  risposte del pass (placement, formato, stati da consegnare, decisioni aperte,
+  varianti) come direttive esplicite; § 7 ora rimanda a § 0 per il formato export.
+- **Enum presentazionale** — `references/field-extraction.md` rileva metadata di
+  display (`color`/`icon`/`badge`/`label`) sulle opzioni enum ed emette un render
+  hint automatico (es. Categoria con colore → pallino colore per opzione), evitando
+  la domanda "come lo rendo?". Non è un `da definire` né una domanda.
+- **DEGRADE** (Codex / no-TTY): il pass fa bake dei default e li DICHIARA in § 0,
+  mai abort. **Delegated mode**: riconcilia con le preferenze già risolte da `/prd`
+  (Branch B in `ui-design-phase.md` ora le inoltra), chiede solo il residuo.
+
 ## 1.0.0 — 2026-07-01
 
 - Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -1,7 +1,7 @@
 ---
 name: ds-handoff
 effort: medium
-version: 1.0.0
+version: 1.1.0
 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,
@@ -67,7 +67,9 @@ user input. Level→behavior mapping, parsing contract, and precedence caveats:
 `/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).
++ brand + DS flag + any delivery/decision preferences already resolved in Discovery)
+— skip the standalone screen-resolution prompt (Step 1's ask), and reconcile the
+Step 5.5 decision pass against those preferences (ask only the residual).
 
 ## Pre-flight
 
@@ -120,10 +122,23 @@ Each step is a delegation. Read the cited SSOT; do not paraphrase it.
    user-confirmation (present best-effort, ask the user to fill `da definire`);
    never hard-abort.
 
+   This gate closes the **field** axis. The **decision** axis is Step 5.5.
+
+5.5. **Decision & preference pass.** DELEGATE —
+   [references/decision-pass.md](references/decision-pass.md). Resolve the open
+   design choices + delivery/placement preferences that Claude Design would
+   otherwise bounce back as questions (the `da proporre` tokens, delivery format,
+   state scope, canvas, variation appetite). **Triggered, not always-on** — fires
+   only when an item is unresolved; ONE consolidated `AskUserQuestion`; a no-op when
+   nothing is open. **DEGRADE** (Codex / no-TTY): bake defaults and DECLARE them in
+   § 0, never abort. **Delegated mode:** skip whatever `/prd` already resolved. The
+   answers populate the template's § 0.
+
 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
+   with the § 0 delivery/decision directives (from Step 5.5), 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.
@@ -152,8 +167,9 @@ Each step is a delegation. Read the cited SSOT; do not paraphrase it.
 
 - **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.
+  (per `references/field-extraction.md`); the Step 5 gate degrades BLOCK →
+  user-confirmation; the Step 5.5 decision pass degrades to **bake-defaults**
+  declared in § 0 (per `references/decision-pass.md`). 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 +

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

@@ -22,6 +22,23 @@
 
 # Feature: {{feature_title}}
 
+## 0. Direttive di consegna & decisioni
+
+> Queste sono decisioni **già prese** (o esplicitamente delegate a te). Non
+> richiedermele: seguile, oppure — dove indicato "proponi N opzioni" — proponi le
+> alternative con i loro trade-off invece di sceglierne una a caso.
+
+- **Dove collocarlo**: {{delivery.target_canvas}}  <!-- es. "Nuovo canvas «Hub fornitore desktop/tablet», NON dentro il master-detail Fornitori esistente" -->
+- **Formato di consegna**: {{delivery.output_delivery}}  <!-- "1 artboard per stato (PNG ≥2x)" | "prototipo interattivo navigabile" | "entrambi" -->
+- **Stati da consegnare**: {{delivery.states_to_deliver}}  <!-- lista esplicita — consegna ESATTAMENTE questi, non chiedermi di deselezionare -->
+{{#if delivery.open_decisions}}
+- **Decisioni di design aperte**:
+{{#each delivery.open_decisions}}
+  - **{{this.topic}}**: {{this.directive}}  <!-- valore deciso, OPPURE "proponi {{this.n}} opzioni con trade-off" -->
+{{/each}}
+{{/if}}
+- **Varianti**: {{delivery.variations}}  <!-- "nessuna oltre le decisioni sopra" | assi richiesti (es. layout griglia, densità gruppi, posizione action bar) -->
+
 ## 1. Obiettivo
 
 {{feature_objective_one_sentence}}
@@ -172,9 +189,13 @@
 
 ## 7. Cosa restituirmi
 
-Per ogni schermata elencata in § 3:
+Per ogni schermata elencata in § 3, nel **formato di consegna deciso in § 0**
+({{delivery.output_delivery}}):
 
-1. **PNG export** ad alta risoluzione (≥ 2x) di OGNI stato richiesto (es. `dettaglio-fornitore__loading.png`, `dettaglio-fornitore__populated.png`).
+1. **Export** ad alta risoluzione (≥ 2x) di OGNI stato in **§ 0 → Stati da
+   consegnare** (es. `dettaglio-fornitore__loading.png`,
+   `dettaglio-fornitore__populated.png`). Se § 0 chiede un prototipo interattivo,
+   consegna gli stati come schermi navigabili invece che come PNG separati.
 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

package/framework/.claude/skills/ds-handoff/references/decision-pass.md

@@ -0,0 +1,94 @@
+# Decision & preference pass — resolve the open choices BEFORE emitting
+
+`ds-handoff` Step 5.5. Runs **after** the coverage gate (Step 5, which verifies the
+*fields*) and **before** filling the template (Step 6). Where the coverage gate
+closes the *data-correctness* axis, this pass closes the **decision axis**: the open
+design choices, delivery preferences and workspace directives that — if left
+implicit — Claude Design bounces back to the user as questions.
+
+The failure this prevents: a prompt that says *"pattern editing per-sede, da
+proporre"* forces Claude Design to STOP and ask which pattern; a prompt that lists
+states but never says "deliver exactly these" invites a "deselect what you don't
+need" round-trip; an enum with a colour but no render directive gets a "how do I
+show the colour?" question. Every one of those is a decision BALDART can make (or
+frame) up front.
+
+**Same discipline as the coverage gate:** decision-**triggered**, not always-on —
+it fires ONLY when there is an unresolved item; ONE consolidated `AskUserQuestion`;
+never assume a default silently. If nothing is unresolved, this step is a **no-op**
+and you proceed straight to Step 6.
+
+## Trigger inventory — what makes the pass necessary
+
+Scan the reconciled per-screen specs (Step 4 output: regions, actions, states,
+list behaviour) plus the delegated/standalone context. An item is "unresolved" when:
+
+| Item | Unresolved when… | Detection |
+|---|---|---|
+| **Open design decision** | an affordance/layout/pattern is explicitly left open | literal token `da proporre` / `da decidere` / `(… inline/pannello/rotta, da proporre)` / `TBD` / `?` in a region/action/state cell |
+| **Delivery format** | not stated in context | no `output_delivery` in the delegated context / standalone args |
+| **State scope** | states enumerated but not confirmed as the deliverable set | states present but no explicit "deliver these" directive |
+| **Placement / canvas** | the Claude Design workspace target is unknown | no `target_canvas` in context |
+| **Variation appetite** | the user's want for alternatives beyond the open decisions is unknown | not stated in context |
+
+If EVERY row is already resolved (all decided in the source / passed by `/prd`),
+**do not ask** — skip to Step 6.
+
+## The consolidated AskUserQuestion (interactive, human present)
+
+Raise **exactly ONE** `AskUserQuestion` covering only the unresolved rows. Suggested
+questions (drop any that is already resolved; `multiSelect` where noted):
+
+1. **Per each open design decision** — offer two shapes of resolution:
+   - *"Decido io"* → the user picks the concrete option (list the plausible ones:
+     e.g. inline / side-panel / dedicated route). The chosen value goes into §0 as a
+     firm directive.
+   - *"Fai proporre a Claude Design"* → frame it in the prompt as *"proponi N opzioni
+     per X con trade-off"*. This is legitimate — Claude Design is a design tool and
+     proposing is its job; the point is to make the ASK **intentional** in the prompt
+     instead of an accidental blocker.
+2. **Formato di consegna** — `artboard-per-stato (PNG ≥2x)` (default) | `prototipo
+   interattivo navigabile` | both.
+3. **Stati da consegnare** (`multiSelect`) — pre-checked with the full detected list;
+   the user unchecks any out of scope. The confirmed set becomes `states_to_deliver`.
+4. **Placement / canvas** — `nuovo canvas dedicato «<feature>»` (default) | `dentro
+   un canvas esistente` (ask which).
+5. **Varianti oltre le decisioni aperte** — `nessuna` (default) | pick axes (grid
+   layout, densità gruppi, posizione action bar, …).
+
+Only after the user answers do you populate §0 and proceed to Step 6. Consistent with
+always-ask-never-assume and "no silent deferral".
+
+## DEGRADE (graceful — Codex / no-TTY / unattended)
+
+When no interactive prompt is possible (Codex without subagents, no-TTY, an
+autonomous run), do **not** hard-abort and do **not** ask. Instead **bake the
+defaults** and **declare them explicitly** in §0 so the choice is visible, not
+silent:
+
+- Open decisions → framed as *"proponi 2 opzioni per X"* (let CD propose, since we
+  can't ask the user).
+- Delivery → `artboard-per-stato (PNG ≥2x)`.
+- States → deliver the full detected list.
+- Placement → `nuovo canvas dedicato`.
+- Variations → `nessuna`.
+
+The prompt still ships, with an honest §0 the user can review — never an abort.
+
+## Delegated-mode reconciliation (called from /prd)
+
+When invoked from `/prd` Step 3.0 Branch B, the caller may already have resolved some
+of these during Discovery (a delivery preference, a placement, an explicit design
+decision). The passed context is authoritative: **skip every already-resolved row**
+and ask only the residual. Never re-ask what `/prd` already knows. If the context
+resolves everything, the pass is a no-op even in delegated mode.
+
+## False-positive guards (do NOT treat as an open decision)
+
+- **Descriptive prose that isn't a bivio** — a region note like "header con nome e
+  stato" is a spec, not a choice. Only a literal open-choice token (see the trigger
+  table) counts.
+- **Fields** — those are the coverage gate's job (Step 5), not this pass. A `da
+  definire` cell is a *data* gap, not a *decision*; do not surface it here.
+- **Already-decided affordances** — an action with a concrete effect/destination is
+  resolved; don't ask about it.

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

@@ -44,7 +44,7 @@ Anything you cannot ground in code is the **literal `da definire`** — never a
 | **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` |
+| **Opzioni / sorgente enum** | `z.enum([...])` / `z.nativeEnum` literals verbatim; a `z.string()` whose options come from a runtime query → `"query runtime — da definire"`. When the option source carries **presentational metadata**, add the render hint (see below). | `—` / `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` |
@@ -57,6 +57,7 @@ component binding, a form control already in code) over the heuristic when prese
 | Schema / type shape | Control |
 |---|---|
 | `z.enum([...])` / `z.nativeEnum` / union of string literals | `select` (or `radio` for ≤ 3 options / `segmented` per project convention) |
+| enum whose option source carries **presentational metadata** (`color` / `icon` / `badge` / `label`) — a lookup table, a `const` map, a DB category with a colour | `select` **+ a render hint** (see "Presentational enums" below) |
 | `z.boolean()` | `toggle` (or `checkbox`) |
 | `z.string()` short (no/small `.max`) | `text input` |
 | `z.string()` long (`.max` ≥ ~200, or named `notes`/`description`/`body`) | `textarea` |
@@ -69,6 +70,25 @@ component binding, a form control already in code) over the heuristic when prese
 | `z.array(z.string())` from a known set | `multi-select` |
 | `z.object(...)` nested | a sub-group / sub-card |
 
+## Presentational enums (pre-empt the "how do I render it?" question)
+
+When an enum's options are not bare strings but carry **display metadata** — a
+category with a `color`, a status with an `icon`, an option with a human `label`
+distinct from its value — capturing the values alone leaves Claude Design to guess
+*how* to render them, which becomes a round-trip question. Instead, **detect the
+extra fields and emit a render hint** in the Opzioni cell, so the directive is
+explicit:
+
+- Colour per option → `"<EnumName> (name + color) → pallino/badge colore per opzione; colore = .color"`.
+- Icon per option → `"<EnumName> (name + icon) → icona per opzione; icona = .icon"`.
+- Human label ≠ value → give both: `"value → «Label»"` per option.
+
+Ground the metadata the same way as the enum itself (the lookup table / `const` map
+/ schema). If the option list is a runtime query, still note the presentational field
+if the row shape exposes it (`"query runtime — ogni riga ha { name, color }"`). This
+is a documented hint the extraction step fills automatically — it is **not** a `da
+definire` and it is **not** a user question.
+
 ## Readonly detection
 
 Mark a field **readonly** (static text, no editable control) when it is not

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

@@ -46,10 +46,15 @@ delegate-or-else-inline contract as `/prd` → `/ds-new`.)
      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**.
+   - the `features.has_design_system` flag (the skill omits § 5 when `false`);
+   - **any delivery/decision preferences already surfaced in Discovery** (output
+     format, target canvas, a design decision the user already made) — `/ds-handoff`
+     runs a **decision pass** (its Step 5.5) before emitting, and reconciles against
+     what you pass so it asks only the residual, never re-asking the known.
+
+   `/ds-handoff` runs field extraction + the coverage gate + the decision pass + 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[]`

package/package.json

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