baldart 4.78.2 → 4.80.0

package/framework/docs/CODEX-AGENTS.md

@@ -0,0 +1,111 @@
+# Codex-native subagents
+
+> **Status:** shipped in v4.80.0. Claude + Codex. No new `baldart.config.yml` key —
+> rides on `tools.enabled` containing `codex`.
+
+## The problem this fixes
+
+BALDART's skills delegate code-understanding, review, and planning to named
+**subagents** (`codebase-architect`, `code-reviewer`, `plan-auditor`, …). For a
+long time those agents were treated as a Claude-only construct: the Codex tool
+adapter declared `supportsSubagents() === false` and `agentsDir() === null`, so
+the 32 agent definitions under `framework/.claude/agents/` were **never installed
+into a Codex tree**.
+
+The result, on Codex: a skill said *"invoke the `codebase-architect` agent"*, the
+agent did not exist, there was no obvious mechanism to spawn it, and the model
+**improvised** — e.g. falling back to a generic "explorer" sub-agent. Not a
+comprehension failure; a missing portability contract.
+
+Meanwhile Codex shipped **custom agents** (subagents). So the fix is not "degrade
+on Codex" — it is "install the agents on Codex, in Codex's own format".
+
+## Why a transpiler, not a symlink
+
+Skills are portable by **symlink** because the on-disk format is identical for
+both tools (`SKILL.md` + frontmatter). One source, two symlinks, zero
+duplication.
+
+A subagent is **not** identical across tools:
+
+| | Claude Code | Codex |
+|---|---|---|
+| Location | `.claude/agents/<name>.md` | `.codex/agents/<name>.toml` |
+| Format | Markdown + YAML frontmatter | TOML |
+| Required fields | `name`, `description` + body | `name`, `description`, `developer_instructions` |
+| Effort knob | `effort: low\|…\|max` | `model_reasoning_effort: low\|medium\|high` |
+| Invocation | Task/Agent tool, `subagent_type` | spawned **by `name`** |
+| Nesting | (orchestrator spawns) | `agents.max_depth: 1` (no deeper nesting) |
+
+Because the format differs, the same `framework/.claude/agents/<name>.md` stays
+the **single source of truth** and BALDART **generates** the `.toml` from it on
+install/update. The generated file is a real file (you cannot symlink a `.md`
+source onto a `.toml` target), carrying a `# baldart-generated:` marker so:
+
+- a later `update` regenerates it safely (idempotent — unchanged source → no rewrite),
+- a user fork (a `.toml` without the marker) is **never clobbered** (recorded as a conflict).
+
+## Field mapping (`.md` → `.toml`)
+
+Implemented in [`src/utils/codex-agent-transpiler.js`](../../src/utils/codex-agent-transpiler.js):
+
+| Claude frontmatter / body | Codex TOML | Notes |
+|---|---|---|
+| `name` | `name` | spawn identity; source of truth |
+| `description` | `description` | collapsed to a single line |
+| markdown body | `developer_instructions` | the agent's system prompt; emitted as a TOML multi-line **literal** (`'''…'''`) so backslashes/quotes survive byte-for-byte (falls back to escaped `"""…"""` only if the body itself contains `'''`) |
+| `effort: low\|medium\|high\|xhigh\|max` | `model_reasoning_effort: low\|medium\|high` | `xhigh`/`max` clamp to `high` |
+| `model: opus\|sonnet\|haiku` | *(omitted)* | no 1:1 Codex model → inherit the parent session model (the safe default) |
+
+Overlays apply **first**: when `.baldart/overlays/agents/<name>.md` exists the
+markdown overlay is merged (the normal `## [OVERRIDE]/[APPEND]/[PREPEND]`
+machinery), then the merged markdown is transpiled — so Codex agents honour
+overlays exactly like Claude agents. The overlay's HTML-comment marker is
+stripped before it can leak into `developer_instructions`.
+
+## How it is wired
+
+The transpile rides on the **existing** per-item merge machinery
+(`SymlinkUtils._mergeBulkDir`) through one new adapter hook:
+
+```js
+// codex.js
+agentsDir() { return '.codex/agents'; }   // was null
+supportsSubagents() { return true; }       // was false
+transpilerFor(kind) {                      // NEW
+  if (kind !== 'agent') return null;
+  const t = require('../codex-agent-transpiler');
+  return { outExt: '.toml', transform: t.mdAgentToToml, isGenerated: t.isGeneratedToml };
+}
+```
+
+When `_mergeBulkDir` sees a non-null `transpilerFor(kind)` it routes that kind
+through `_installTranspiledFile` (generate `.toml`) instead of the symlink /
+overlay path. `claude.transpilerFor()` returns null, so Claude is unchanged
+(agents still symlinked `.md`). `commandsDir`/`workflowsDir`/`outputStylesDir`
+stay null for Codex — slash commands, dynamic workflows, and output styles have
+no Codex equivalent.
+
+Existing Codex consumers pick this up automatically on the next
+`npx baldart update` (which calls `mergeAgents`), and `baldart doctor`'s
+`mergeAgents` backfill covers any drift.
+
+## The authoring contract (for every new agent, from now on)
+
+Any new agent is **auto-portable** — just drop a `.md` under
+`framework/.claude/agents/`. To keep it clean across both tools:
+
+1. **Keep `name` + `description` in the frontmatter.** `name` is the spawn
+   identity on both tools; `description` is how Codex chooses which agent to spawn.
+2. **Put the agent's behaviour in the body** — it becomes `developer_instructions`.
+3. **Set `effort:`** if the agent needs a non-default reasoning tier; it maps to
+   `model_reasoning_effort`.
+4. **Do not rely on a subagent spawning a further subagent.** Codex caps
+   `agents.max_depth` at 1 — consistent with BALDART's own `## Role boundary`
+   ("no Task/Agent tool") convention and the "nested subagents not available"
+   reality on Claude. Orchestration belongs to the skill, not the agent.
+5. **Avoid Claude-only tool references in the body that have no Codex analogue.**
+   Prefer the portable retrieval cascade (code-graph → LSP → Grep → reads).
+
+Nothing else is required — no per-agent Codex file, no registry entry beyond the
+usual `REGISTRY.md` row.

package/package.json

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

package/src/utils/codex-agent-transpiler.js

@@ -0,0 +1,139 @@
+const yaml = require('js-yaml');
+
+/**
+ * Codex agent transpiler — turns a BALDART Claude subagent definition
+ * (`.claude/agents/<name>.md`, YAML frontmatter + markdown body) into a Codex
+ * custom-agent definition (`.codex/agents/<name>.toml`).
+ *
+ * Why a transpiler and not a symlink (the model used for skills): a skill has
+ * the SAME on-disk format for Claude and Codex, so one source file is linked
+ * into two places. A subagent does NOT — Codex custom agents are TOML files
+ * with a different field set, living under a different root (`.codex/agents/`,
+ * not `.agents/skills/`). So the SAME source `.md` is the SSOT and we *generate*
+ * the `.toml` from it on install/update. Edit the `.md`; never hand-edit the
+ * generated `.toml`.
+ *
+ * Field mapping (Claude frontmatter → Codex TOML):
+ *   name        → name                    (source of truth for spawn identity)
+ *   description → description             (single-lined)
+ *   <body>      → developer_instructions  (the agent's system prompt)
+ *   effort      → model_reasoning_effort  (low|medium|high — see mapEffort)
+ *   model       → (OMITTED on purpose)    opus/sonnet/haiku have no 1:1 Codex
+ *                                          model; inheriting the parent session
+ *                                          model is the safe, correct default.
+ *
+ * Codex docs: developers.openai.com/codex/subagents — required fields are
+ * `name`, `description`, `developer_instructions`; optional `model`,
+ * `model_reasoning_effort`, `sandbox_mode`, `nickname_candidates`,
+ * `mcp_servers`, `skills.config`. Agents are spawned by their `name`.
+ */
+
+const TOML_MARKER_PREFIX = '# baldart-generated:';
+
+/**
+ * Map a BALDART effort tier (low|medium|high|xhigh|max — see
+ * framework/agents/effort-protocol.md) onto Codex's `model_reasoning_effort`,
+ * which only accepts low|medium|high. xhigh/max clamp to high (the ceiling).
+ * Returns null when there's nothing to map (omit the key → inherit parent).
+ */
+function mapEffort(effort) {
+  if (!effort) return null;
+  const e = String(effort).trim().toLowerCase();
+  if (e === 'low') return 'low';
+  if (e === 'medium') return 'medium';
+  if (e === 'high' || e === 'xhigh' || e === 'max') return 'high';
+  return null;
+}
+
+/** Split leading YAML frontmatter from the markdown body. */
+function splitFrontmatter(md) {
+  let rest = String(md).replace(/^/, '');
+  const m = rest.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (m) return { frontmatter: m[1], body: rest.slice(m[0].length) };
+  return { frontmatter: '', body: rest };
+}
+
+/**
+ * Strip a leading `<!-- baldart-generated: … -->` HTML-comment marker. Present
+ * only when the source markdown was overlay-merged (the marker sits right after
+ * the frontmatter); it must not leak into developer_instructions.
+ */
+function stripHtmlMarker(body) {
+  return String(body).replace(/^\s*<!--\s*baldart-generated:[\s\S]*?-->\s*\n/, '');
+}
+
+/** Emit a TOML basic (single-line) string with the required escapes. */
+function tomlBasicString(s) {
+  return '"' + String(s)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/[\r\n\t]+/g, ' ')
+    .trim() + '"';
+}
+
+/**
+ * Emit a TOML multi-line string for an arbitrary markdown body.
+ *
+ * Prefer a multi-line LITERAL string (`'''…'''`): it processes no escapes, so
+ * markdown full of backslashes and double-quotes survives byte-for-byte. The
+ * only thing it cannot contain is `'''`, so fall back to a multi-line BASIC
+ * string (`"""…"""`) with escaping when the body has a triple-single-quote.
+ * A leading newline (trimmed by the TOML spec) keeps the body starting exactly
+ * as authored; a trailing newline keeps a body-final quote from abutting the
+ * closing delimiter.
+ */
+function tomlMultiline(s) {
+  const body = String(s).replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  if (!body.includes("'''")) {
+    return "'''\n" + body + "\n'''";
+  }
+  const esc = body.replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"');
+  return '"""\n' + esc + '\n"""';
+}
+
+/**
+ * Transpile one Claude agent `.md` into Codex `.toml` text.
+ * @param {string} markdown - raw `.md` content (frontmatter + body)
+ * @param {{name?: string, frameworkVersion?: string}} [opts]
+ * @returns {string} TOML content (ends with a trailing newline)
+ */
+function mdAgentToToml(markdown, opts = {}) {
+  const { frontmatter, body } = splitFrontmatter(markdown);
+  let meta = {};
+  if (frontmatter) {
+    try { meta = yaml.load(frontmatter) || {}; }
+    catch (_) { meta = {}; }
+  }
+
+  const name = String(meta.name || opts.name || '').trim();
+  if (!name) {
+    throw new Error('codex-agent-transpiler: agent has no `name` (neither frontmatter nor filename provided one)');
+  }
+  const description = String(meta.description || '').replace(/\s+/g, ' ').trim();
+  const instructions = stripHtmlMarker(body).replace(/^\n+/, '').replace(/\n+$/, '\n');
+  const effort = mapEffort(meta.effort);
+
+  const lines = [];
+  lines.push(`${TOML_MARKER_PREFIX} kind=agent name=${name} v=${opts.frameworkVersion || 'unknown'}`);
+  lines.push(`# Transpiled from .claude/agents/${name}.md by BALDART — edit the source, not this file.`);
+  lines.push(`name = ${tomlBasicString(name)}`);
+  if (description) lines.push(`description = ${tomlBasicString(description)}`);
+  if (effort) lines.push(`model_reasoning_effort = ${tomlBasicString(effort)}`);
+  lines.push(`developer_instructions = ${tomlMultiline(instructions)}`);
+
+  return lines.join('\n') + '\n';
+}
+
+/** True when a TOML file was generated by BALDART (safe to overwrite/regenerate). */
+function isGeneratedToml(content) {
+  return typeof content === 'string' && content.includes(TOML_MARKER_PREFIX);
+}
+
+module.exports = {
+  mdAgentToToml,
+  isGeneratedToml,
+  mapEffort,
+  splitFrontmatter,
+  tomlMultiline,
+  TOML_MARKER_PREFIX
+};

package/src/utils/symlinks.js

@@ -425,6 +425,18 @@ class SymlinkUtils {
         const overlayAbs = path.join(this.cwd, overlayRel);
         const hasOverlay = cfg.overlay && fs.existsSync(overlayAbs);
 
+        // Transpile path: when the adapter declares a transpiler for this kind
+        // (e.g. Codex agents → TOML), do NOT symlink the `.md` source — generate
+        // the tool-native file from it (overlay-merged first when present).
+        const transpiler = (typeof adapter.transpilerFor === 'function') ? adapter.transpilerFor(kind) : null;
+        if (transpiler) {
+          this._installTranspiledFile({
+            kind, baseName, fwAbsolute, overlayAbs, hasOverlay,
+            targetRel, transpiler, adapter, frameworkVersion, aggregate
+          });
+          continue;
+        }
+
         // Inspect what currently lives at the link path (if anything).
         let lstat = null;
         try { lstat = fs.lstatSync(linkPath); } catch (_) { /* absent */ }
@@ -525,6 +537,77 @@ class SymlinkUtils {
     });
   }
 
+  /**
+   * Install a transpiled payload for a tool whose on-disk format differs from
+   * the framework source (currently: Codex agents, `.md` → `.toml`).
+   *
+   * The framework `.md` stays the single SSOT; the `.toml` is *generated* (a
+   * real file, never a symlink — you can't symlink a `.md` source to a `.toml`
+   * target). When an overlay exists it is merged FIRST (reusing the markdown
+   * overlay machinery), so Codex agents honour overlays exactly like Claude
+   * agents do, then the merged markdown is transpiled. The output carries a
+   * `# baldart-generated:` marker so a later update can safely regenerate it
+   * and a user fork (no marker) is never clobbered.
+   */
+  _installTranspiledFile({ kind, baseName, fwAbsolute, overlayAbs, hasOverlay, targetRel, transpiler, adapter, frameworkVersion, aggregate }) {
+    const outName = `${baseName}${transpiler.outExt}`;
+    const outPath = path.join(this.cwd, targetRel, outName);
+    const relOut = path.join(targetRel, outName);
+
+    // Effective markdown = overlay-merged when an overlay exists, else the base.
+    const baseContent = fs.readFileSync(fwAbsolute, 'utf8');
+    let effectiveMd = baseContent;
+    if (hasOverlay) {
+      try {
+        const { mergeOverlay } = require('./overlay-merger');
+        const overlayContent = fs.readFileSync(overlayAbs, 'utf8');
+        const merged = mergeOverlay({ kind, name: baseName, baseContent, overlayContent, frameworkVersion });
+        effectiveMd = merged.generated;
+        (merged.warnings || []).forEach((w) => {
+          UI.warning(`[${adapter.label}] ${kind} ${baseName}: ${w}`);
+          aggregate.warnings.push({ tool: adapter.name, kind, name: baseName, warning: w });
+        });
+      } catch (_) { effectiveMd = baseContent; /* fail-safe: transpile the base */ }
+    }
+
+    let outContent;
+    try {
+      outContent = transpiler.transform(effectiveMd, { name: baseName, frameworkVersion });
+    } catch (err) {
+      UI.warning(`[${adapter.label}] ${kind} ${baseName}: transpile failed (${err.message}) — skipped.`);
+      aggregate.warnings.push({ tool: adapter.name, kind, name: baseName, warning: `transpile-failed: ${err.message}` });
+      return;
+    }
+
+    let lstat = null;
+    try { lstat = fs.lstatSync(outPath); } catch (_) { /* absent */ }
+    if (lstat) {
+      if (lstat.isSymbolicLink()) {
+        // Stale symlink from an earlier layout — replace with the generated file.
+        fs.unlinkSync(outPath);
+      } else {
+        const existing = fs.readFileSync(outPath, 'utf8');
+        if (!transpiler.isGenerated(existing)) {
+          UI.warning(`[${adapter.label}] ${kind} ${baseName}: ${relOut} exists without a baldart-generated marker — NOT overwriting (user fork?).`);
+          aggregate.conflicts.push({
+            tool: adapter.name, kind, name: baseName,
+            local_path: relOut, reason: 'manual-edit-no-marker',
+            detected_at: new Date().toISOString()
+          });
+          return;
+        }
+        if (existing === outContent) {
+          aggregate.skipped.push({ tool: adapter.name, kind, name: baseName, reason: 'already-generated' });
+          return;
+        }
+      }
+    }
+
+    fs.writeFileSync(outPath, outContent);
+    UI.success(`[${adapter.label}] ${kind} transpiled: ${relOut}`);
+    aggregate.generated.push({ tool: adapter.name, kind, name: baseName });
+  }
+
   _generateOverlayedFile({ kind, name, fwAbsolute, overlayAbs, linkPath, lstat, frameworkVersion, aggregate, adapter, targetRel }) {
     const { mergeOverlay, isGeneratedFile, computeBaseFileSha, ensureBaseFileShaInOverlay, refreshOverlayVersionPin } = require('./overlay-merger');
     const baseContent = fs.readFileSync(fwAbsolute, 'utf8');
@@ -706,12 +789,16 @@ class SymlinkUtils {
           allValid = false;
         } else {
           const { isGeneratedFile } = require('./overlay-merger');
+          const { isGeneratedToml } = require('./codex-agent-transpiler');
           const entries = fs.readdirSync(full);
           const frameworkOwned = entries.filter((n) => {
             const p = path.join(full, n);
             try {
               if (fs.lstatSync(p).isSymbolicLink()) return true;
-              return isGeneratedFile(fs.readFileSync(p, 'utf8'));
+              // Symlinked (Claude .md) OR transpiled-generated (Codex .toml) OR
+              // overlay-generated (Claude .md with HTML marker).
+              const c = fs.readFileSync(p, 'utf8');
+              return isGeneratedFile(c) || isGeneratedToml(c);
             } catch { return false; }
           });
           if (frameworkOwned.length === 0) {

package/src/utils/tool-adapters/claude.js

@@ -35,6 +35,13 @@ class ClaudeAdapter {
   /** Where this tool reads output-style definitions from (null if unsupported). */
   outputStylesDir() { return '.claude/output-styles'; }
 
+  /**
+   * Per-kind transpiler hook. Claude consumes every payload in its native
+   * on-disk format, so nothing is transpiled — the merge machinery symlinks
+   * the source verbatim. (Codex returns a transpiler for `agent`.)
+   */
+  transpilerFor(/* kind */) { return null; }
+
   /** Whether this tool consumes subagent definitions (`.claude/agents/`). */
   supportsSubagents() { return true; }
 

package/src/utils/tool-adapters/codex.js

@@ -19,9 +19,16 @@ const os = require('os');
  * Codex reads from `.agents/skills/<x>`, and both follow the symlink to
  * the single source under `.framework/framework/.claude/skills/<x>/`.
  *
- * Codex does NOT have an equivalent of Claude subagents (`.claude/agents/`)
- * or slash commands (custom prompts are deprecated in favor of skills).
- * AGENTS.md at the repo root IS read by Codex — same convention as Claude.
+ * Codex DOES have custom agents (since the subagents feature shipped), but in
+ * a different shape than Claude: TOML files under `.codex/agents/` (project) or
+ * `~/.codex/agents/` (personal), with fields name / description /
+ * developer_instructions (+ optional model_reasoning_effort, sandbox_mode, …),
+ * spawned by `name`. Because the format differs from Claude's markdown
+ * subagents, BALDART does not symlink them — it *transpiles* the same `.md`
+ * source into `.toml` via `codex-agent-transpiler` (see `transpilerFor`).
+ * Slash commands have no Codex equivalent (custom prompts are deprecated in
+ * favor of skills). AGENTS.md at the repo root IS read by Codex — same
+ * convention as Claude.
  */
 class CodexAdapter {
   constructor(cwd = process.cwd()) {
@@ -33,13 +40,27 @@ class CodexAdapter {
 
   skillsDir() { return '.agents/skills'; }
 
-  // Codex has no equivalent of Claude subagents or slash commands (custom
-  // prompts are deprecated in favor of skills). Returning null disables the
-  // per-item merge for those kinds — adapters that DO support them return
-  // the target directory string.
-  agentsDir() { return null; }
+  // Codex custom agents live under `.codex/agents/` as TOML files. They are
+  // NOT symlinked from the `.md` source (the format differs) — the merge
+  // machinery routes this kind through `transpilerFor('agent')` to *generate*
+  // a `.toml` from each source `.md`. Slash commands have no Codex equivalent
+  // (custom prompts are deprecated in favor of skills) → null disables that merge.
+  agentsDir() { return '.codex/agents'; }
   commandsDir() { return null; }
 
+  /**
+   * Per-kind transpiler. The merge machinery (`SymlinkUtils._mergeBulkDir`)
+   * calls this for every merge kind; a non-null return means "do NOT symlink
+   * the `.md` source — generate `outExt` content from it via `transform`".
+   * Only `agent` is transpiled (markdown subagent → Codex TOML); every other
+   * kind returns null (and Codex already disables them via a null dirGetter).
+   */
+  transpilerFor(kind) {
+    if (kind !== 'agent') return null;
+    const t = require('../codex-agent-transpiler');
+    return { outExt: '.toml', transform: t.mdAgentToToml, isGenerated: t.isGeneratedToml };
+  }
+
   // Codex has no equivalent of Claude Code dynamic workflows (the JS
   // orchestration runtime is Claude-only). Returning null disables the
   // per-item workflow merge for Codex — the same source workflow scripts are
@@ -51,7 +72,7 @@ class CodexAdapter {
   // Codex — the source style files are simply never linked into a Codex tree.
   outputStylesDir() { return null; }
 
-  supportsSubagents() { return false; }
+  supportsSubagents() { return true; }
   supportsSlashCommands() { return false; }
   supportsHooks() { return false; }
 

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

@@ -1,137 +0,0 @@
-# Claude Design Handoff Prompt — Template
-
-> Template populated at runtime by **Step 3.0 (Mockup Source Decision)** in
-> [../references/ui-design-phase.md](../references/ui-design-phase.md) when the
-> user picks the **handoff** branch. All `{{placeholders}}` are resolved from the
-> PRD state file (`${paths.prd_dir}/sessions/YYYY-MM-DD-<slug>-state.md`),
-> `baldart.config.yml`, and optional overlays.
->
-> Render rules:
-> - Conditional sections (marked `{{#if …}} … {{/if}}`) are emitted only when the
->   condition is true. Skip the entire section (including its heading) when false.
-> - Lists (marked `{{#each …}}`) render one bullet per item; emit "—" if empty.
-> - The rendered output is presented to the user inside a fenced markdown
->   code-block so they can copy-paste verbatim into Claude Design.
-
----
-
-# Feature: {{feature_title}}
-
-## 1. Obiettivo
-
-{{feature_objective_one_sentence}}
-
-## 2. User flow
-
-{{user_flow_summary}}
-
-{{#if primary_personas}}
-**Personas target**:
-{{#each primary_personas}}
-- {{this.name}} — {{this.context}}
-{{/each}}
-{{/if}}
-
-## 3. Schermate in scope
-
-> **Vincolo di tracciabilità funzionale.** Inserisci SOLO controlli (bottoni,
-> icone-azione, voci di menu, tab, toggle) legati a una funzione elencata qui
-> sotto. Non aggiungere chrome interattivo "per completezza visiva": ogni
-> affordance senza funzione diventa codice morto in implementazione. Se proponi
-> un elemento interattivo non presente nelle azioni primarie, segnalalo in
-> consegna come *proposta da validare*, non come requisito. Gli elementi
-> puramente decorativi (icone di sezione, marchi) marcali esplicitamente come
-> **decorativi**.
-
-{{#each screens_in_scope}}
-### {{this.name}}
-
-- **Scopo**: {{this.purpose}}
-- **Stati richiesti**: {{this.states_required}}  <!-- empty, loading, populated, error, success, ecc. -->
-- **Azioni primarie**: {{this.primary_actions}}
-- **Dati visualizzati**: {{this.data_shown}}
-{{#if this.notes}}
-- **Note**: {{this.notes}}
-{{/if}}
-
-{{/each}}
-> **Nota per l'export.** Dai al canvas di questa feature un titolo che contenga il
-> nome feature («{{feature_title}}»), e numera gli artboard in modo coerente con gli
-> ID schermata qui sopra (es. schermata 3.1 → artboard `s31`). Scaricherò il bundle
-> completo del workspace: questo mi permette di ritrovare esattamente le TUE schermate
-> ed evitare ambiguità con le altre feature.
-
-{{#if brand_voice}}
-## 4. Brand & voice
-
-- **Tono**: {{brand_voice.tone}}
-- **Personalità**: {{brand_voice.personality}}
-- **Do**: {{brand_voice.do}}
-- **Don't**: {{brand_voice.dont}}
-{{#if brand_voice.references}}
-- **Riferimenti visivi**: {{brand_voice.references}}
-{{/if}}
-{{/if}}
-
-{{#if has_design_system}}
-## 5. Design system constraints
-
-> Riusa SOLO i token e le primitive elencate. Se devi proporre qualcosa di nuovo,
-> segnalalo esplicitamente nella consegna così posso aggiornare il registro.
-
-### Token chiave
-
-```
-{{design_tokens_excerpt}}
-```
-
-### Primitive da riusare
-
-{{#each registered_primitives}}
-- **{{this.name}}** — {{this.purpose}} ({{this.path}})
-{{/each}}
-
-### Vincoli numerici (da `design-system-protocol.md`)
-
-- Type scale: {{tokens.type_scale}}
-- Spacing scale: {{tokens.spacing_scale}}
-- Radius: {{tokens.radius_scale}}
-- Contrast minimo: {{tokens.contrast_target}} (WCAG AA + APCA Lc ≥ {{tokens.apca_target}})
-- Motion durations: {{tokens.motion_durations}}
-{{/if}}
-
-## 6. Stack target
-
-- **Framework**: {{stack.framework}}
-- **Output preferito**: {{output_format_preference}}  <!-- "HTML/CSS standalone" | "React component (Tailwind)" | "Figma frame" -->
-{{#if stack.charting}}
-- **Charting library**: {{stack.charting}}
-{{/if}}
-{{#if stack.animation}}
-- **Animation library**: {{stack.animation}}
-{{/if}}
-
-## 7. Cosa restituirmi
-
-Per ogni schermata elencata in § 3:
-
-1. **PNG export** ad alta risoluzione (≥ 2x) di OGNI stato richiesto (es. `lista-ordini__empty.png`, `lista-ordini__populated.png`).
-2. {{output_format_preference_block}}  <!-- "Codice HTML/CSS in un file unico" | "Codice React (.tsx) con import Tailwind" | "Link Figma alla frame" -->
-3. **Mappa di tracciabilità** — per OGNI elemento interattivo o iconografico
-   della schermata, una riga: `elemento → funzione che lo motiva` (l'azione
-   primaria / il dato di § 3 che serve), oppure marcalo **decorativo** se non ha
-   comportamento. Qualunque elemento che non riesci a tracciare a una funzione,
-   elencalo separatamente come *orphan da decidere* — così posso scegliere se
-   dargli una funzione, renderlo decorativo o rimuoverlo, invece di
-   implementarlo a vuoto.
-4. **Note inline** su:
-   - Componenti nuovi (non presenti nel registry sopra) che hai introdotto e perché.
-   - Token deviation: qualunque colore/spacing/radius fuori dalla palette sopra, con motivazione.
-   - Decisioni di layout non ovvie (es. priority sort, hierarchy visiva, density).
-
-Quando hai pronto, dimmi i **path locali** dei file (PNG/HTML/TSX) — li importerò in questa sessione PRD per analisi e validazione contro il design system.
-
----
-
-<!-- baldart-handoff: do-not-edit-manually -->
-<!-- Generated from claude-design-handoff-prompt.template.md by /prd Step 3.0 -->