baldart 4.83.0 → 4.85.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.85.0] - 2026-07-01
+
+**Root-file primitives gain universal delegation + quality rules (primitive `1.1.0`).** The v4.83.0 skeletons pointed to `.claude/agents/REGISTRY.md` for agent routing but never stated the single highest-frequency rule in the always-loaded file: *which agent writes what*. The `AGENTS.md` primitive (the cross-tool SSOT Codex also reads) now carries a **MUST**: plan-and-delegate, never write substantial code inline — **code / logic / tests → `coder`**, **UI → `ui-expert`** (dual-tool: Claude Task `subagent_type` / Codex custom agent by name; every other agent routes via `REGISTRY.md`). The `CLAUDE.md` stub's Plan Mode names both agents to match (was `coder` only).
+
+Alongside it, the **universal, stack-agnostic** subset of rules a mature project accumulates — previously discoverable only after a project authored them by hand — is promoted into the skeleton: a **security-hygiene MUST** (no hardcoded secrets, no exposed stack traces, no PII in logs, validate/parse external inputs), a **Quality bar (SHOULD)** (bound/paginate list queries — no unbounded/N+1 — + Core Web Vitals for web UIs + baseline accessibility), and explicit **worktree isolation** in the Git Workflow (new branch → `/nw`; never `git switch`/`checkout -b`/`branch` on the shared main checkout). **Deliberately NOT promoted** (they stay project overlay, and would trip the contamination scanner): exact KPI numbers, database/ORM specifics, CSS-framework choices, and project-specific git rituals.
+
+**MINOR** — enriches the shipped skeleton's protocol content; no new `baldart.config.yml` key, no layout/CLI change. Consumers pick it up on the next `npx baldart update` (the writer regenerates `AGENTS.md`/`CLAUDE.md`, byte-stable on everything else). `primitive_version` 1.0.0 → 1.1.0.
+
+### Changed
+
+- **`framework/templates/primitives/AGENTS.md`** — added the implementation-delegation MUST (`coder`/`ui-expert`), the security-hygiene MUST, a `## Quality bar (SHOULD)` section (performance + accessibility), and worktree isolation in Git Workflow. `primitive_version` → 1.1.0.
+- **`framework/templates/primitives/CLAUDE.md`** — Plan Mode delegation now names `coder` (code) + `ui-expert` (UI) + `doc-reviewer` (docs). `primitive_version` → 1.1.0.
+- **`framework/templates/primitives/AGENTS.CHANGELOG.md` + `CLAUDE.CHANGELOG.md`** — `1.1.0` entries.
+
+## [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.85.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/framework/templates/primitives/AGENTS.CHANGELOG.md

@@ -4,6 +4,23 @@ Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://sem
 Questo è il changelog INTERNO dello skeleton spedito (`primitive_version`), separato dal
 file `AGENTS.md` generato nel consumer e indipendente dal `VERSION` del framework.
 
+## 1.1.0 — 2026-07-01
+
+- **Implementation-delegation MUST**: plan-and-delegate, never write substantial code
+  inline — **code/logic/tests → `coder`**, **UI → `ui-expert`** (dual-tool: Claude Task
+  `subagent_type` / Codex by-name); other agents route via `.claude/agents/REGISTRY.md`.
+  Now in the cross-tool SSOT so Codex sees it too (was only weakly in the CLAUDE.md stub).
+- **Universal security hygiene MUST**: no hardcoded secrets, no exposed stack traces, no
+  PII in logs, validate/parse external inputs at the boundary.
+- **Quality bar (SHOULD)**: stack-agnostic performance discipline (no unbounded/N+1 list
+  reads, Core Web Vitals) + baseline accessibility. Project-specific KPI numbers stay in
+  the overlay.
+- **Git Workflow**: explicit worktree isolation — new branch → `/nw`; orchestrator never
+  runs `git switch`/`checkout -b`/`branch` on the shared main checkout.
+- Distilled the UNIVERSAL subset of common project rules; stack-specific specifics
+  (database/ORM & migration policies, CSS-framework choices, exact KPI numbers, git
+  rituals) remain overlay content, never baked into the shipped skeleton.
+
 ## 1.0.0 — 2026-07-01
 
 - Primo skeleton SOTA cross-tool (framework v4.83.0). Sostituisce il bulk symlink di

package/framework/templates/primitives/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- baldart-primitive: name=AGENTS primitive_version=1.0.0
+<!-- baldart-primitive: name=AGENTS primitive_version=1.1.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,
@@ -28,6 +28,12 @@ mechanics — this file remains the single source of truth for the protocol.
   (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 delegate implementation to the domain agent — plan and delegate, do NOT write
+  substantial code inline: **code / logic / tests → `coder`**; **UI (components, pages,
+  styling, visual output) → `ui-expert`**. Same dual-tool invocation as `codebase-architect`
+  (Claude Code: Task tool `subagent_type`; Codex: custom agent by name). Every other agent
+  (code-reviewer, doc-reviewer, qa-sentinel, security-reviewer, …) routes via
+  `.claude/agents/REGISTRY.md`.
 - 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.
@@ -43,6 +49,8 @@ mechanics — this file remains the single source of truth for the protocol.
   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 NOT hardcode secrets / tokens / API keys (env vars only), expose internal stack
+  traces in responses, or log PII. Validate & parse every external / user input at the boundary.
 - MUST run the testing gates before DONE (see § Workflow Gates).
 
 **Feature-gated (active only when the flag is `true` in `baldart.config.yml`):**
@@ -72,7 +80,9 @@ mechanics — this file remains the single source of truth for the protocol.
 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.
+the branch it was spawned on). For a NEW branch, prefer a git **worktree** (`/nw`): the
+orchestrator MUST NOT run `git switch` / `checkout -b` / `branch` on the shared main
+checkout (other sessions share it). Stage explicit filenames only; never bundle unrelated changes.
 
 ## Workflow Gates
 
@@ -83,6 +93,14 @@ 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.
 
+## Quality bar (SHOULD)
+
+- SHOULD respect performance budgets — avoid unbounded or N+1 data access on list paths
+  (bound + paginate queries, index hot lookups), and for web UIs keep Core Web Vitals
+  healthy (LCP / INP / CLS). Project-specific numeric targets live in the overlay.
+- SHOULD meet baseline accessibility for interactive UI — keyboard navigation, sufficient
+  contrast, labelled inputs, alt text on informative images.
+
 ## Execution Modes
 
 | Mode | Branch | Validation |

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

@@ -4,6 +4,12 @@ Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://sem
 Changelog INTERNO dello stub spedito (`primitive_version`), separato dal `CLAUDE.md`
 generato nel consumer e indipendente dal `VERSION` del framework.
 
+## 1.1.0 — 2026-07-01
+
+- Plan Mode delegation now names **both** domain agents — **code → `coder`**, **UI →
+  `ui-expert`** (was `coder` only) — plus `doc-reviewer` for full docs/SSOT. Mirrors the
+  new cross-tool delegation MUST in the AGENTS.md primitive.
+
 ## 1.0.0 — 2026-07-01
 
 - Primo stub Claude-native (framework v4.83.0). BALDART inizia a spedire `CLAUDE.md`.

package/framework/templates/primitives/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- baldart-primitive: name=CLAUDE primitive_version=1.0.0
+<!-- baldart-primitive: name=CLAUDE primitive_version=1.1.0
      SHIPPED SKELETON. The writer strips this banner, resolves {{ slot }}/{{#flag}} from
      baldart.config.yml, merges .baldart/overlays/CLAUDE.md, stamps a baldart-generated
      marker, and writes the result to the repo root.
@@ -19,8 +19,9 @@ SSOT, not restated here. Below are the **Claude-native mechanics only**.
 - Invoke `codebase-architect` before writing the plan — never plan blind.
 - Launch `plan-auditor` + `doc-reviewer` in parallel to review the plan, incorporate their
   feedback, and state inside the plan that the review gate was honored, BEFORE `ExitPlanMode`.
-- Wait for explicit user approval, then delegate implementation to the `coder` agent (via the
-  Task tool). The `coder` writes code + minimal doc stubs only.
+- Wait for explicit user approval, then delegate implementation to the domain agent via the
+  Task tool — **code / logic / tests → `coder`**, **UI → `ui-expert`**. Each writes code +
+  minimal doc stubs only; full docs / SSOT sync go to `doc-reviewer`.
 
 ## User Interaction (Claude-native, ABSOLUTE)
 

package/package.json

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