baldart 4.82.0 → 4.84.0

package/CHANGELOG.md

@@ -5,6 +5,58 @@ 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/`.
+
+Each skeleton mixes three tiers: **STATIC** (universal SOTA prose, shipped verbatim) · **`{{ slot }}`** (project facts filled *deterministically* at write-time from `baldart.config.yml` + `package.json`/README probes — concrete values, so Codex/Cursor/Aider read real commands, never raw `${…}`) · **`[OVERLAY]`** (project opinions authored in `.baldart/overlays/{AGENTS,CLAUDE}.md`, merged via the existing OVERRIDE/APPEND/PREPEND engine). This split follows the 2026 research consensus (short hand-authored skeleton + project depth in the overlay; auto-generating a whole file with an LLM measurably reduces agent task success).
+
+**`AGENTS.md` is the cross-tool SSOT** (read natively by Claude Code + Codex + others). **`CLAUDE.md` is a thin Claude-native stub** that deliberately does **not** import `AGENTS.md` (Claude Code loads both automatically → an `@AGENTS.md` would double-load the protocol) — it holds only Claude-only mechanics (Plan Mode / `AskUserQuestion` / Task tool / output-style / hooks). The writer (`src/utils/root-primitives.js`) reuses `overlay-merger.js` and the same `baldart-generated` marker, so the `framework-edit-gate` already blocks direct edits to the generated files (edit the overlay).
+
+**Existing hand-written files are adopted zero-loss:** a consumer's hand-authored `AGENTS.md`/`CLAUDE.md` (no marker) is preserved **verbatim** into `.baldart/overlays/<name>.md`, then the root is regenerated as skeleton + overlay. Adoption is **interactive-gated** — in autonomous/CI mode a hand-written file is never mutated (the writer emits a blocker and skips it). Wired into `add` (post-configure), `update` (aligned + post-pull paths, idempotent + byte-stable), `doctor` (`regenerate-root-primitives` / `adopt-root-primitives` actions), and `migrate` (legacy symlink → generated file). Each skeleton carries its own `primitive_version` + a sibling `*.CHANGELOG.md` kept out of the generated file.
+
+**MINOR** — additive capability. **No new `baldart.config.yml` key** (slots resolve from existing config + repo probes) → the schema-change propagation rule does NOT apply. Degrades safely: missing commands omit rows, non-multimodal/Codex consumers ignore `CLAUDE.md`, autonomous runs never mutate hand-written files. Authoritative design: [`framework/docs/ROOT-PRIMITIVES.md`](framework/docs/ROOT-PRIMITIVES.md).
+
+### Added
+
+- **`framework/templates/primitives/AGENTS.md` + `CLAUDE.md`** — the versioned SOTA skeletons (STATIC + `{{slot}}` + `[OVERLAY]` hook), each with a `primitive_version` banner.
+- **`framework/templates/primitives/AGENTS.CHANGELOG.md` + `CLAUDE.CHANGELOG.md`** — internal per-primitive changelogs (kept out of the generated file).
+- **`src/utils/root-primitives.js`** — the writer: slot resolver + minimal zero-dep template engine (`{{ }}` / `{{#flag}}` / `{{> partial}}`) + overlay merge + `baldart-generated` marker + state machine (generated / symlink / handwritten / absent) + `rootPrimitiveStatus()` for doctor.
+- **`framework/docs/ROOT-PRIMITIVES.md`** — consumer-facing design/lifecycle/adoption doc.
+
+### Changed
+
+- **`src/utils/symlinks.js`** — `createBulkSymlinks()` no longer symlinks `AGENTS.md`; `createAllSymlinks()` calls the new `writeRootPrimitives()`; `verifySymlinks()` no longer expects `AGENTS.md` to be a symlink.
+- **`src/commands/add.js`** — writes root primitives after `configure` populates the config (final concrete values).
+- **`src/commands/update.js`** — regenerates root primitives on both the aligned-install and post-pull paths (`reconcileRootPrimitives`); adds `CLAUDE.md` to `BALDART_MANAGED_PATTERNS`.
+- **`src/commands/doctor.js`** — detects stale/adoptable root primitives and offers `regenerate-root-primitives` / `adopt-root-primitives`.
+- **`src/commands/migrate.js`** — converts a legacy `AGENTS.md` symlink into the generated file (Step 2b), idempotent.
+- **`README.md`** — install description + repo-tree updated (AGENTS.md/CLAUDE.md generated, not symlinked).
+
+### Removed
+
+- **`framework/AGENTS.md`** — the old bulk-symlink source; its STATIC content now lives in `framework/templates/primitives/AGENTS.md` (single SSOT).
+
 ## [4.82.0] - 2026-07-01
 
 **Mockup→code extracted into a dedicated self-verifying skill `/ui-implement` + skills are now versioned.** The mockup→code fidelity knowledge (v4.73→v4.78) was **inlined inside `/new`**: the "Design Reference" briefing (image/HTML/code-src branching), the design-source declaration + Step 7b grounding, and the Phase 2.6 `/e2e-review` invocation. This release **externalizes** it into one specialized, self-verifying skill and, separately, introduces **per-skill versioning + a canonical structure** across all skills.

package/README.md

@@ -66,7 +66,8 @@ npx baldart status
 ### What `add` (first install) does
 
 - Downloads the framework via Git subtree into `.framework/`
-- Creates symlinks for auto-updateable files (AGENTS.md, agents/)
+- Creates a symlink for the cross-tool `agents/` reference dir
+- Generates the root-file primitives `AGENTS.md` (cross-tool SSOT) + `CLAUDE.md` (Claude entry) from versioned skeletons — filling project facts from `baldart.config.yml` and merging `.baldart/overlays/{AGENTS,CLAUDE}.md`
 - Per-item-merges framework agents/commands/skills into `.claude/` (real directories where your own files coexist)
 - Detects Codex on the machine and mirrors skills into `.agents/skills/` if found
 - Copies customizable templates (hooks, UI guidelines, backlog cards)
@@ -365,7 +366,8 @@ npx baldart routines disable wiki-review   # remove the schedule
 ```
 your-project/
 ├── .framework/              # Framework source (via Git subtree)
-├── AGENTS.md               # Symlink → .framework/AGENTS.md
+├── AGENTS.md               # Generated from skeleton + config + overlay (cross-tool SSOT)
+├── CLAUDE.md               # Generated Claude Code entry (Claude-native mechanics)
 ├── agents/                  # Symlink → .framework/agents/
 ├── .claude/
 │   ├── agents/             # Symlink → .framework/.claude/agents/

package/VERSION

@@ -1 +1 @@
-4.82.0
+4.84.0

package/framework/.claude/hooks/agent-discovery-gate.js

@@ -15,8 +15,10 @@
  *            as BROKEN in some scenarios (files ignored at session start)
  *
  * This hook covers the filesystem-detectable subset of the problem
- * (missing/broken symlinks). The model-side defense (the MUST rule in
- * `framework/AGENTS.md`) covers the rest. The two are inseparable:
+ * (missing/broken symlinks). The model-side defense (the MUST rule in the
+ * generated root `AGENTS.md`, shipped from
+ * `framework/templates/primitives/AGENTS.md`) covers the rest. The two are
+ * inseparable:
  * without the MUST rule, a `permissionDecision: deny` from this hook
  * would likely be worked around by the model trying a different
  * `subagent_type` — the very failure mode this hook exists to prevent.

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/framework/docs/ROOT-PRIMITIVES.md

@@ -0,0 +1,98 @@
+# Root-file primitives — `AGENTS.md` + `CLAUDE.md`
+
+Since **v4.83.0** BALDART ships **versioned skeletons** for the two most important
+files in any AI-assisted repo and generates concrete, project-specific versions of
+them on every install/update.
+
+- **`AGENTS.md`** — the **cross-tool single source of truth** (read natively by Claude
+  Code, Codex, Cursor, Aider, …). Holds the coordination protocol: MUST rules, git
+  workflow, gates, execution modes, routing.
+- **`CLAUDE.md`** — a **thin Claude-native stub**. Claude Code loads *both* files
+  automatically, so `CLAUDE.md` does **not** import `AGENTS.md` (that would double-load
+  the protocol into context). It carries only the Claude-only mechanics: Plan Mode
+  (`EnterPlanMode`/`ExitPlanMode`), `AskUserQuestion` discipline, the Task-tool subagent
+  roster, output-style, hooks.
+
+Before v4.83.0, `AGENTS.md` was a bulk symlink into the framework payload (not
+customizable without losing auto-update) and `CLAUDE.md` was not shipped at all.
+
+## Three tiers
+
+Each skeleton mixes exactly three kinds of content:
+
+| Tier | What | Who authors it |
+|---|---|---|
+| **STATIC** | universal SOTA prose, identical for every project | the shipped primitive (versioned) |
+| **`{{ slot }}`** | project facts, filled deterministically at write-time | the writer (`src/utils/root-primitives.js`) — pure substitution, never LLM invention |
+| **`[OVERLAY]`** | project opinions / war-stories / KPIs / design rules | the repo owner, in `.baldart/overlays/{AGENTS,CLAUDE}.md` |
+
+This split follows the 2026 research consensus: a shipped skeleton stays **short and
+hand-authored**; project depth lives in the overlay (auto-generating a whole
+`AGENTS.md`/`CLAUDE.md` with an LLM measurably *reduces* agent task success).
+
+## Slot resolution (deterministic)
+
+The writer resolves every slot from `baldart.config.yml` + repo probes — no new config
+key was introduced:
+
+| Slot | Source |
+|---|---|
+| `identity.name` | `identity.brand_name` → `package.json` name → dir basename |
+| `identity.description` | README first paragraph → `package.json` description → visible `<!-- TODO -->` |
+| `stack.summary` | composed from `stack.framework` + `database` + `auth_provider` + `testing.e2e` + `toolchain.installed_tools` |
+| `stack.node` | `package.json` `engines.node` → `.nvmrc` |
+| Commands table | `toolchain.commands.*` → `package.json` scripts (rows with no source are omitted) |
+| Repo map | non-empty `paths.*` + a derived source root |
+| `git.trunk_branch` | `git.trunk_branch` |
+| feature gates | `features.has_backlog` / `has_adrs` / `has_i18n` / `has_design_system` |
+
+## Overlay
+
+`.baldart/overlays/AGENTS.md` (and `…/CLAUDE.md`) use the **same** merge engine as agent
+and command overlays (`overlay-merger.js`):
+
+- `## [OVERRIDE] <section>` — replace a section from the skeleton.
+- `## [APPEND] <section>` — append to a section.
+- `## [PREPEND] <section>` — prepend to a section.
+- a plain `## <heading>` — add a new section at the end.
+
+Author overlays with `/overlay` or by hand. The generated root file carries a
+`baldart-generated` marker and the `framework-edit-gate` hook blocks direct edits to it —
+edit the overlay, not the file.
+
+## Lifecycle
+
+- **`baldart add`** — after `configure` populates `baldart.config.yml`, the writer
+  generates both files with concrete values.
+- **`baldart update`** — regenerates on both the aligned-install and post-pull paths.
+  **Byte-stable**: unchanged inputs produce no diff.
+- **`baldart doctor`** — flags `regenerate-root-primitives` when a file is missing, still
+  a legacy symlink, or drifted (skeleton / overlay / config change), and
+  `adopt-root-primitives` for a handwritten file.
+- **`baldart migrate`** — converts a legacy `AGENTS.md` symlink into the generated file.
+
+## Adoption (existing hand-written files — zero loss)
+
+If a consumer already has a hand-authored `AGENTS.md` or `CLAUDE.md` (no
+`baldart-generated` marker), the writer **adopts** it: the entire file is preserved
+verbatim into `.baldart/overlays/<name>.md`, and the root is regenerated as skeleton +
+overlay (so nothing is lost). You are told to review and re-file — much of a rich
+`CLAUDE.md` typically belongs in the **AGENTS.md** overlay (cross-tool), not CLAUDE.md.
+
+**Adoption is interactive-gated.** In autonomous/CI mode (`CI` / `BALDART_AUTONOMOUS` /
+no TTY) a hand-written file is **never mutated**: the writer emits a blocker and skips it,
+so a routine unattended update never silently transforms your file.
+
+## Versioning
+
+Each skeleton carries a `primitive_version` (SemVer, its own line of evolution,
+independent of the framework `VERSION`) in its banner, plus a sibling
+`framework/templates/primitives/<NAME>.CHANGELOG.md` kept **out** of the generated file
+so version history never costs context. Bump `primitive_version` + add a changelog entry
+whenever a skeleton changes.
+
+## Files
+
+- `framework/templates/primitives/AGENTS.md` · `CLAUDE.md` — the skeletons.
+- `framework/templates/primitives/AGENTS.CHANGELOG.md` · `CLAUDE.CHANGELOG.md` — internal changelogs.
+- `src/utils/root-primitives.js` — the writer (resolve → template → merge → marker → write) + `rootPrimitiveStatus` (doctor).

package/framework/templates/primitives/AGENTS.CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog — AGENTS.md primitive
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+Questo è il changelog INTERNO dello skeleton spedito (`primitive_version`), separato dal
+file `AGENTS.md` generato nel consumer e indipendente dal `VERSION` del framework.
+
+## 1.0.0 — 2026-07-01
+
+- Primo skeleton SOTA cross-tool (framework v4.83.0). Sostituisce il bulk symlink di
+  `AGENTS.md` con un real-file **generato**: contenuto STATIC universale + slot `{{ }}`
+  riempiti a write-time da `baldart.config.yml` (identity/stack/paths/commands/git) +
+  hook `[OVERLAY]` per `.baldart/overlays/AGENTS.md`.
+- Struttura: Commands (partial, comandi concreti) · Repo Map (partial) · Non-negotiables
+  (universal + feature-gated) · Git Workflow · Workflow Gates · Execution Modes ·
+  Priority & Conflict · Routing.
+- Le meccaniche solo-Claude (EnterPlanMode/AskUserQuestion/Task) NON stanno qui: vivono
+  nello stub `CLAUDE.md`. La ricchezza project-specific (war-story/KPI/regole design) va
+  in overlay, non nello skeleton (best practice 2026: skeleton corto, no auto-generazione).

package/framework/templates/primitives/AGENTS.md

@@ -0,0 +1,111 @@
+<!-- baldart-primitive: name=AGENTS primitive_version=1.0.0
+     This is the SHIPPED SKELETON. The writer (src/utils/root-primitives.js) strips
+     this banner, resolves every {{ slot }} / {{> partial }} / {{#flag}} from
+     baldart.config.yml (+ package.json/README), merges .baldart/overlays/AGENTS.md,
+     stamps a baldart-generated marker, and writes the result to the repo root.
+     Tiers: STATIC (verbatim) · {{slot}} (config fill) · [OVERLAY] (project opinions).
+     Edit the OVERLAY, never the generated root AGENTS.md. -->
+# {{ identity.name }} — Agent Protocol (AGENTS.md)
+
+{{ identity.description }}
+Stack: {{ stack.summary }}.{{ stack.node_suffix }}
+
+Mandatory coordination rules for all agents (Claude / Codex / humans). Read by every
+AI tool that supports AGENTS.md. If context is limited, follow **MUST** rules and
+**Routing** first. Claude Code additionally loads `CLAUDE.md`, which adds Claude-native
+mechanics — this file remains the single source of truth for the protocol.
+
+{{> commands_section }}
+## Repo Map
+
+{{> repo_map }}
+
+## Non-negotiables (MUST)
+
+**Universal (every project):**
+- MUST treat `AGENTS.md` as authoritative for agent rules.
+- MUST understand the codebase before planning/implementing — invoke `codebase-architect`
+  (Claude Code: Task tool `subagent_type: codebase-architect`; Codex: the custom agent by
+  name at `.codex/agents/codebase-architect.toml`). Only if NEITHER mechanism exists,
+  degrade explicitly to inline retrieval (code-graph → LSP → Grep) and SAY SO.
+- MUST NOT silently substitute a different agent when an invocation returns empty / times
+  out / is denied — STOP, report verbatim, and wait. Never auto-route to a generic agent.
+- MUST NOT work on files another agent has claimed; parallel work only on independent areas.
+- MUST do a clarity analysis before fixing anything labeled `bug` — no blind guessing.
+- MUST mark missing info UNKNOWN and ask; if blocked, set `BLOCKED` with the blocker.
+- MUST NOT make forbidden assumptions: provider/auth swap, DB-schema change without a
+  data-model update, new external dependency without docs, API-contract change without an
+  API-reference update.
+- MUST keep docs and code in sync — a code change without the matching doc update is invalid.
+- MUST use commit format `{{ git.commit_format }}`; small, traceable commits.
+- MUST NOT commit with failing lint/type checks. Full build only before opening a PR.
+- MUST pre-sync (`git fetch`, clean status, confirm branch, `--ff-only`) and NEVER push
+  directly to `{{ git.trunk_branch }}` — all changes reach it via PR.
+- MUST get owner approval before force-push/reset or deleting an UNMERGED branch (create a
+  `backup/<YYYYMMDD>-<reason>` tag first). Deleting an already-merged branch is routine.
+- MUST run the testing gates before DONE (see § Workflow Gates).
+
+**Feature-gated (active only when the flag is `true` in `baldart.config.yml`):**
+{{#has_backlog}}
+- Backlog: pick one card (TODO/READY), set `IN_PROGRESS`, assign yourself, branch-per-card
+  (`{{ git.feature_prefix }}/<CARD-ID>-slug`), keep status current, document before merge.
+{{/has_backlog}}
+{{#has_adrs}}
+- ADRs: write complete records (Context / Decision / Rationale / Alternatives / Consequences,
+  no TODO placeholders) for architectural decisions.
+{{/has_adrs}}
+{{#has_i18n}}
+- i18n: NO hardcoded user-facing strings; every label via `t()` + a key in
+  `{{ i18n.registry }}`. Enforced by the anti-hardcoded lint gate.
+{{/has_i18n}}
+{{#has_design_system}}
+- Design system: the BLOCKING read cascade applies before any UI work — read the registry
+  `INDEX.md` → the per-component spec → the token SSOT (see § Routing).
+{{/has_design_system}}
+{{#has_project_status}}
+- Status doc: update its Active Code Context before work; keep it < 200 lines; archive
+  entries older than 7 days to `work-history.md`.
+{{/has_project_status}}
+
+## Git Workflow
+
+Branch naming: `{{ git.feature_prefix }}/<CARD-ID>-slug` (local), `codex/…` or `claude/…`
+(cloud agents), `hotfix/<ID>-slug` (production fixes). Branches are created by the
+orchestrator (`/nw`, `/new`) or the user — **never by the `coder` agent** (it implements on
+the branch it was spawned on). Stage explicit filenames only; never bundle unrelated changes.
+
+## Workflow Gates
+
+**Pre-commit (fast, every commit):** lint · type check{{#has_i18n}} · the i18n anti-hardcoded
+gate{{/has_i18n}} · markdown-lint on changed `.md`. Fix all errors before `git add`. Do NOT
+run a full build every commit.
+
+**Pre-PR (once, before opening a PR):** full build (must pass) · unit tests (if they exist) ·
+E2E for critical-flow changes.
+
+## Execution Modes
+
+| Mode | Branch | Validation |
+|---|---|---|
+| `local` | `{{ git.feature_prefix }}/<CARD-ID>-slug` → PR to `{{ git.trunk_branch }}` | manual run mandatory |
+| `cloud` | `codex/…` or `claude/…` → PR to `{{ git.trunk_branch }}` | CI-first; local advisory |
+| `hotfix` | `hotfix/<BUG-ID>-slug` | owner approval |
+
+## Priority & Conflict
+
+Priority: `AGENTS.md` → `agents/index.md` → domain references → ADRs → `archive/`.
+On conflict: stop → read both → decide which is newer → update the other → record the
+decision in an ADR + the backlog card.
+
+## Routing
+
+- Docs routing (touch X → read/update Y): `agents/index.md`.
+- Agent invocation routing: `.claude/agents/REGISTRY.md` (SSOT). Update it when adding agents.
+- Domain protocols load on demand from `agents/*.md` (architecture, testing, security,
+  design-system-protocol, i18n-protocol, …) — never load them all at once.
+
+<!-- OVERLAY: project-specific rules live in `.baldart/overlays/AGENTS.md` and are merged
+     below this line. Use `## [APPEND] <section>` to extend a section above, `## [OVERRIDE]
+     <section>` to replace one, or a plain `## <heading>` to add a new section. Typical
+     content: design-system rules · DB/migration discipline · NFR/KPI targets · security
+     specifics · project war-stories & ADR pointers · custom commands. -->

package/framework/templates/primitives/CLAUDE.CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog — CLAUDE.md primitive
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+Changelog INTERNO dello stub spedito (`primitive_version`), separato dal `CLAUDE.md`
+generato nel consumer e indipendente dal `VERSION` del framework.
+
+## 1.0.0 — 2026-07-01
+
+- Primo stub Claude-native (framework v4.83.0). BALDART inizia a spedire `CLAUDE.md`.
+- Deliberatamente **non** importa `AGENTS.md` (Claude Code carica entrambi i file
+  nativamente → un `@AGENTS.md` raddoppierebbe il protocollo in contesto). Contiene solo:
+  Plan Mode (EnterPlanMode/plan-auditor/doc-reviewer/ExitPlanMode), User Interaction
+  (AskUserQuestion = stop-and-wait), Subagents & tooling (Task tool, output-style, hooks).
+- Hook `[OVERLAY]` per `.baldart/overlays/CLAUDE.md`; le regole cross-tool vanno
+  nell'overlay di AGENTS.md, non qui.