baldart 3.16.0 → 3.17.1

package/CHANGELOG.md

@@ -5,6 +5,45 @@ 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).
 
+## [3.17.1] - 2026-05-23
+
+CLI quality-of-life patch shaken loose by a hands-on consumer update simulation (mayo, 3.13.0 → 3.16.0). Four real bugs surfaced when actually driving `baldart update` end-to-end from a scripted context. Two were show-stoppers for any non-interactive use (CI, AI-driven, headless update agent), one was cosmetic but ugly, one was a stale stub that lied to the user. All four are fixed; nothing in this release changes framework payload behaviour for end-users running BALDART interactively in a TTY.
+
+### Fixed
+
+- **`baldart update` gains `--yes`/`-y` and `--auto-stash` flags** in [bin/baldart.js](bin/baldart.js) and [src/commands/update.js](src/commands/update.js). Until now, every `UI.confirm` and the `UI.select` arrow-key stash prompt blocked indefinitely on a non-TTY stdin (inquirer's pattern detection mis-handles re-rendered prompts when fed via pipe or `expect`). Both flags route through a single internal `confirm()` wrapper that short-circuits to the prompt's default when `--yes` is set; `--auto-stash` is the narrower variant for users who want manual control over confirms but auto-stash on dirty trees. `--yes` implies `--auto-stash` and additionally passes `--non-interactive` down to the `baldart configure` sub-invocation triggered by the schema-drift detector, plus switches symlink reconcile from `mode: 'prompt'` to `mode: 'force'` (the conflict-resolution prompts inside `SymlinkUtils` would otherwise reintroduce blocking I/O even with `--yes`).
+- **`baldart status` actually checks the framework against the upstream tip** in [src/commands/status.js](src/commands/status.js). Previously the "Update Status" section was a hard-coded `UI.success('Up to date')` stub regardless of the installed version — a 4-versions-stale consumer was told everything was fine. The fix calls `git.fetch('antbald/BALDART')` + `git.getRemoteVersion(...)` (already exported by `src/utils/git.js`), compares semver with a tiny inline `cmpSemver` helper, and renders one of four outcomes: update available (`X → Y`), local ahead of remote (unreleased commit, common during BALDART self-development), up to date, or "Cannot check (offline?)" on fetch failure. The SUMMARY box now carries the update line too, so it's visible without scrolling past the per-section output.
+- **`baldart --version` and `baldart --help` exit cleanly** in [bin/baldart.js](bin/baldart.js). Commander 9 throws a `CommanderError` with `exitCode: 0` from these flags as its internal flow-control mechanism; the previous `bin/baldart.js` had no try/catch around `program.parse(process.argv)`, so the throw escaped to Node and printed a 12-line `CommanderError: 3.17.0` stack trace right after the version itself. Now wrapped in try/catch that recognises the three known sentinel codes (`commander.version`, `commander.help`, `commander.helpDisplayed`) and exits 0 silently; real errors keep the previous behaviour (log message + non-zero exit).
+- **CLI version is read from the `VERSION` file, not `package.json`** in [bin/baldart.js](bin/baldart.js). `package.json.version` is only synced at publish time via `npm run sync-version` (see `scripts/sync-version`), so in dev / local-source / pre-publish contexts it lagged the actual `VERSION` file — `node bin/baldart.js --version` was printing `3.14.1` while VERSION was `3.17.0`. A new `resolveVersion()` reads `VERSION` at module load with `package.json.version` as fallback. Published `baldart@<x.y.z>` on npm is unaffected (the workflow still runs `sync-version` first, so both files agree in published artefacts).
+
+### Notes
+
+- **No framework payload changes** — all four fixes are inside `bin/` and `src/`. Skills, agents, templates, hooks, routines, docs are untouched. The next `baldart update` for consumers picks up the new flags and the working status check without any change to the framework files they install.
+- **Not a v3.18.0 because no new capability shipped** — this is purely "what should already have worked". The new flags are additive (zero-config end-users in a TTY see no change) and the status fix is replacing a stub with the real check it was always supposed to be.
+- **Bug #4 from the mayo simulation (schema-drift detector skipped with `--no-commit`) was a false positive** — the drift detector at lines 462–503 runs before `postUpdateAutoCommit` (line 506), so `--no-commit` doesn't reach it. Verified by reading the call sequence, no code change needed.
+- **Verification** (manual, no test suite): (1) `node bin/baldart.js --version` prints `3.17.1` and exits 0 silently; (2) `node bin/baldart.js update --help` shows the three options (`--no-commit`, `--yes/-y`, `--auto-stash`); (3) in a stale consumer repo, `baldart status` reports "Update available" with the version diff; (4) `baldart update --yes` on a dirty consumer auto-stashes, pulls, reconciles symlinks in force mode, runs `configure --non-interactive`, and exits 0 with no blocking prompts.
+
+## [3.17.0] - 2026-05-23
+
+The `/prd` skill gains a third option in the design phase. Until v3.16.0, when a user reached Step 3 without having provided mockups (`mockups.status: none`), the only path forward was internal generation via the `ui-design` skill (3 HTML options → iteration → save). With Claude Design now offering a design-system-sync'd visual generator, users who prefer iterating in that surface had to abandon the PRD flow halfway, work externally, and then re-enter as if they'd had mockups from the start. This release adds **Step 3.0 — Mockup Source Decision**: when `mockups.status: none` AND UI impact ≠ N/A, the skill explicitly asks "internal generation or handoff to Claude Design?". The handoff branch generates a context-rich prompt (discovery + brand voice + design-system tokens + screens in scope + stack target) ready to paste, then STOPs. On user re-entry with local paths, it re-uses the existing Step 1.6 Mockup Intake verbatim — copy → analyze → populate state — and Step 3 falls naturally into Hybrid mode. Zero code paths downstream of the bivio are new; the entire feature is a decision point + a prompt generator on top of pre-existing infrastructure.
+
+### Added — PRD Step 3.0 Mockup Source Decision
+
+- **§ Step 3.0 in [framework/.claude/skills/prd/references/ui-design-phase.md](framework/.claude/skills/prd/references/ui-design-phase.md)** before the precondition decision tree. Activates only when `mockups.status: none` AND UI impact ≠ N/A. Poses the binary question (Internal `ui-design` vs Handoff Claude Design) with explicit STOP gate — silence or ambiguity re-asks rather than defaulting silently. Branch A sets `mockups.source: internal` and falls through unchanged. Branch B collects context from state file + `baldart.config.yml` + `.baldart/overlays/prd.md` + `${paths.design_system}/INDEX.md` + `tokens-reference.md` (when `features.has_design_system: true`), renders the handoff prompt template, presents it inside a fenced code-block with copy-paste instructions, persists `mockups.status: pending_external` + `mockups.source: claude-design` + `mockups.handoff_prompt_path` in the state file (prompt saved to `${paths.prd_dir}/<slug>/handoff/claude-design-prompt.md` for session-restart survival), and STOPs.
+- **Re-entry handler in same file**. When the user returns with local paths after handoff, the skill invokes the existing Step 1.6 Mockup Intake procedure verbatim (no code duplication) — copy into `mockups/` with collision-safe rename, run Mockup analysis schema, populate `## UI Design`. Then flips `mockups.status` from `pending_external` to `provided` or `partial` based on coverage of `screens_in_scope[]`, keeps `mockups.source: claude-design` as audit trail, and falls through to the precondition decision tree which routes to Hybrid mode unchanged.
+- **Precondition decision tree extended** with two new rows: `mockups.status: pending_external` ⇒ STOP (handoff in flight); `mockups.status: none` AND user picked Branch A ⇒ Full (preserves backwards-compatible default). The existing `provided` / `partial` ⇒ Hybrid and UI = N/A ⇒ Skip rows are unchanged.
+- **New template asset [framework/.claude/skills/prd/assets/claude-design-handoff-prompt.template.md](framework/.claude/skills/prd/assets/claude-design-handoff-prompt.template.md)**. Seven-section structure populated at runtime: (1) feature objective, (2) user flow + personas, (3) screens in scope with required states + primary actions + data shown, (4) brand & voice (conditional on overlay), (5) design system constraints with tokens excerpt + registered primitives + numeric tables from `framework/agents/design-system-protocol.md` (conditional on `features.has_design_system: true`), (6) stack target + output format preference derived from `stack.framework`, (7) deliverable spec (PNG exports per state + code/Figma + inline notes on new components / token deviations / layout decisions). Generic and project-agnostic — all project-specific content is injected as placeholders.
+- **Hard Rule 16 note in [framework/.claude/skills/prd/SKILL.md](framework/.claude/skills/prd/SKILL.md)** added to the existing Mockup Intake rule. Codifies that a NO answer at intake routes through Step 3.0 (not directly to Full mode), with cross-reference to the ui-design-phase section. The rule itself remains unchanged for backwards compatibility — Step 3.0 is purely additive.
+
+### Notes
+
+- **No new `baldart.config.yml` keys** — the schema-change propagation rule does not apply to this release. The bivio is runtime-only per the user's preference (zero persistent flag); no template/configure/update/doctor updates needed. All context for the handoff prompt is read from existing config keys (`paths.*`, `stack.*`, `features.has_design_system`).
+- **Backwards compatibility.** PRDs in flight on v3.16.x finish on v3.16.x semantics. New PRD sessions started on v3.17.0+ see Step 3.0 only when they actually reach Step 3 with `mockups.status: none` — the default (Branch A) preserves the v3.16.x behavior exactly. Existing PRDs that already provided mockups never enter Step 3.0.
+- **`ui-design` skill is unchanged** — Step 3.0 sits in front of it, doesn't modify it. The Full pipeline (3a → 3d) is reached identically when the user picks Branch A or when no mockup-related state exists at all. The `ui-expert` agent and `huashu-design`/`frontend-design` skills are equally untouched.
+- **`mockup_analysis` schema is unchanged** — the new `pending_external` value of `mockups.status` is purely transitional and is overwritten by `provided` / `partial` on user re-entry, so existing PRD templates and state files keep validating without migration.
+- **Files modified outside the Step 3.0 scope** (`card-template.yml`, `backlog-phase.md`, `validation-phase.md`, `prd-card-writer.md`, `framework/.claude/skills/new/SKILL.md`) are the v3.16.0 in-flight release (agent routing + UI specialist briefing — see entry below) and are NOT part of v3.17.0. v3.16.0 should be tagged and pushed before v3.17.0 in the release sequence.
+- **Verification is manual** (no test suite). Dogfood scenarios: (1) `/prd` with mockups provided at intake → never enters Step 3.0, Hybrid mode as today (regression check); (2) `/prd` without mockups, answer "A" at Step 3.0 → Full mode runs identically to v3.16.x; (3) `/prd` without mockups, answer "B" → prompt rendered with discovery + tokens + screens + stack, saved to `handoff/`, state shows `pending_external`, skill STOPs; (4) simulate re-entry with a PNG path → file copied to `mockups/`, status flips to `provided`, Step 3 enters Hybrid mode invoking `ui-design` only for uncovered screens; (5) `features.has_design_system: false` → § 5 of the rendered prompt is omitted entirely; (6) no overlay present → § 4 brand voice omitted.
+
 ## [3.16.0] - 2026-05-23
 
 The `/new` orchestrator becomes specialist-aware: it now reads `owner_agent` from each card YAML and dispatches the right implementation agent — `coder` for backend/logic, `ui-expert` for UI cards, with `plan`/`visual-designer`/`motion-expert` reserved as stubs that fall back to `coder` with a WARN. UI cards (`owner_agent: ui-expert`) receive a dedicated mission briefing that enforces the registry-first BLOCKING cascade (read `${paths.design_system}/INDEX.md` + `tokens-reference.md` + per-component specs BEFORE coding), the implementation-only constraint (no mockup redesign — STOP and ask on registry conflicts), and the Post-Intervention Coherence Check (reconcile INDEX + components + tokens in the same commit). The PRD side enforces the contract end-to-end: `owner_agent` is now a mandatory enum on every child card, UI cards have UI-only scope (logic moves to a sibling `coder` card), and the validation phase blocks commit on enum violations + warns on mixed-scope UI cards.

package/VERSION

@@ -1 +1 @@
-3.16.0
+3.17.1

package/bin/baldart.js

@@ -2,9 +2,27 @@
 
 const { Command } = require('commander');
 const chalk = require('chalk');
+const fs = require('fs');
+const path = require('path');
 const packageJson = require('../package.json');
 const updateNotifier = require('../src/utils/update-notifier');
 
+// Source of truth for the running version is the VERSION file at the repo
+// root. package.json.version is only synced at publish time (see scripts/
+// sync-version), so in dev / local-source / pre-publish contexts it lags.
+// Reading VERSION here keeps `baldart --version` honest in every scenario.
+function resolveVersion() {
+  try {
+    const versionFile = path.join(__dirname, '..', 'VERSION');
+    const fromFile = fs.readFileSync(versionFile, 'utf8').trim();
+    if (fromFile) return fromFile;
+  } catch (_) { /* fall through */ }
+  // Fall back to package.json (already required above). Avoids the TDZ trap
+  // of self-referencing `CLI_VERSION` before its initialiser runs.
+  return packageJson.version;
+}
+const CLI_VERSION = resolveVersion();
+
 // CLI self-update notifier (v3.13.0+). Best-effort; non-blocking; suppressed
 // in CI / non-TTY / via BALDART_NO_UPDATE_CHECK=1 / when --offline is passed.
 // Prints a one-shot hint at the top of the run if a newer npm version was
@@ -14,7 +32,7 @@ const updateNotifier = require('../src/utils/update-notifier');
 const rawArgsForNotifier = process.argv.slice(2);
 const offlineForNotifier = rawArgsForNotifier.includes('--offline');
 updateNotifier.announceAndRefresh({
-  currentVersion: packageJson.version,
+  currentVersion: CLI_VERSION,
   offline: offlineForNotifier,
 });
 
@@ -23,7 +41,7 @@ const program = new Command();
 program
   .name('baldart')
   .description('Claude Agent Framework - AI agent coordination for software projects')
-  .version(packageJson.version);
+  .version(CLI_VERSION);
 
 program
   .command('add [repo]')
@@ -38,6 +56,8 @@ program
   .command('update')
   .description('Update the framework to the latest version')
   .option('--no-commit', 'Skip the post-update auto-commit prompt')
+  .option('-y, --yes', 'Auto-confirm all prompts (CI / scripting). Implies --auto-stash.')
+  .option('--auto-stash', 'When the working tree is dirty, stash automatically instead of prompting.')
   .action(async (options) => {
     const updateCommand = require('../src/commands/update');
     await updateCommand(options);
@@ -153,5 +173,16 @@ if (isDoctorShortcut) {
     process.exit(1);
   });
 } else {
-  program.parse(process.argv);
+  try {
+    program.parse(process.argv);
+  } catch (err) {
+    // Commander throws CommanderError(exitCode: 0) for --version / --help.
+    // That's a normal exit, not a crash — swallow the throw and exit cleanly.
+    if (err && err.code === 'commander.version') process.exit(0);
+    if (err && err.code === 'commander.help') process.exit(0);
+    if (err && err.code === 'commander.helpDisplayed') process.exit(0);
+    // Real error: log and exit non-zero like before.
+    console.error(err && err.message ? err.message : err);
+    process.exit(err && Number.isInteger(err.exitCode) ? err.exitCode : 1);
+  }
 }

package/framework/.claude/skills/prd/SKILL.md

@@ -101,6 +101,13 @@ message. You ask questions, wait for answers, and iterate.
     (`mockup_analysis.screens[].gaps[]`) DEVONO diventare domande mirate in Discovery o
     essere esplicitamente waivate.
 
+    **Nota — handoff esterno post-intake.** Se l'utente risponde NO al mockup intake, lo
+    Step 3.0 in UI Design gli chiederà se vuole generare i mockup internamente (workflow
+    `ui-design`) o fare handoff a **Claude Design**. Nel ramo handoff la skill genera un
+    prompt context-rich pronto da incollare, fa STOP, e al rientro con i path locali
+    riusa esattamente questa stessa procedura di Step 1.6 → Step 3 entra in Hybrid mode.
+    Vedi [ui-design-phase.md](references/ui-design-phase.md) § "Step 3.0 — Mockup Source Decision".
+
 ---
 
 ## TEMPLATES

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

@@ -0,0 +1,116 @@
+# 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
+
+{{#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}}
+
+{{#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. **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 -->

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

@@ -1,15 +1,97 @@
 # UI Design Phase (Step 3)
 
+## Step 3.0 — Mockup Source Decision (only when `mockups.status: none`)
+
+When the state file shows `mockups.status: none` AND UI impact ≠ N/A, the user
+has not provided any mockup at intake. Before falling into the **Full** pipeline,
+offer them an explicit choice — generate internally or hand off to **Claude
+Design** (Anthropic's design product, design-system-sync'd) — so they don't have
+to abandon the PRD flow halfway.
+
+Skip this step entirely when `mockups.status` ∈ {`provided`, `partial`,
+`pending_external`} (already decided) or when UI impact = N/A (no design work).
+
+### The question (single STOP)
+
+Ask the user, verbatim:
+
+> Non hai fornito mockup all'intake. Come preferisci produrli per questa feature?
+> **(A) Internamente** — genero io 3 opzioni HTML (workflow `ui-design`), iteriamo qui.
+> **(B) Handoff a Claude Design** — ti preparo un prompt context-rich da incollare in Claude Design; quando hai i mockup tornami con i path locali.
+
+**STOP.** Wait for an explicit `A` / `B` answer. Silence or ambiguity ⇒ ask
+again (do NOT default silently).
+
+### Branch A — Internal generation
+
+Set `mockups.source: internal` in the state file, then fall through to the
+**Precondition decision tree** below — the `none` row routes to Full mode
+unchanged. No other side-effect of Step 3.0.
+
+### Branch B — Claude Design handoff
+
+1. **Collect context from the state file + config + overlays:**
+   - `feature_title`, `feature_objective_one_sentence` from `## Feature Description`.
+   - `user_flow_summary`, `primary_personas` from `## Discovery Log` (dimensions 1 + 2).
+   - `screens_in_scope[]` from `## UI Design` (derive from User Stories + ISA touchpoints if not yet populated — same logic as Hybrid mode § "Build the per-screen routing table").
+   - `brand_voice` from `.baldart/overlays/prd.md` if present (skip section otherwise).
+   - When `features.has_design_system: true`: read `${paths.design_system}/INDEX.md` (primitive list) + `${paths.design_system}/tokens-reference.md` (tokens excerpt). When `false`: omit § 5 of the prompt entirely.
+   - `stack.framework`, `stack.charting`, `stack.animation` from `baldart.config.yml`.
+   - `output_format_preference` derived from `stack.framework` (Next/Remix → React+Tailwind; vanilla → HTML/CSS; otherwise ask the user).
+   - Numeric token tables (type scale, spacing, radius, contrast, motion durations) from `framework/agents/design-system-protocol.md` — cite verbatim.
+
+2. **Render the prompt** by populating
+   [../assets/claude-design-handoff-prompt.template.md](../assets/claude-design-handoff-prompt.template.md)
+   with the collected context. Strip empty conditional sections.
+
+3. **Present the rendered prompt** to the user inside a fenced markdown
+   code-block, prefixed with this instruction (verbatim):
+
+   > Incolla il prompt qui sotto in Claude Design. Quando hai i mockup pronti,
+   > tornami con i **path locali** dei file (PNG, HTML, TSX, o link Figma) e
+   > riprendo da qui — copio i file nella cartella del PRD, li analizzo come
+   > al solito (Step 1.6 Mockup Intake), e Step 3 entra in Hybrid mode.
+
+4. **Update state file** before stopping:
+   - `mockups.status: pending_external`
+   - `mockups.source: claude-design`
+   - `mockups.handoff_prompt_path: ${paths.prd_dir}/<slug>/handoff/claude-design-prompt.md` (save the rendered prompt to disk so it survives session restarts).
+   - `step_3_mode: pending_external_handoff` (transitional — overwritten when user returns).
+
+5. **STOP.** Wait for the user to return with local paths.
+
+### Re-entry from handoff (user returns with paths)
+
+When the user comes back with one or more local paths after the handoff:
+
+1. Invoke **Step 1.6 — Mockup Intake** verbatim
+   ([SKILL.md](../SKILL.md) § Hard Rule 16,
+   [discovery-phase.md](discovery-phase.md) § "Mockup analysis schema"):
+   - Copy local files into `${paths.prd_dir}/<slug>/mockups/` with collision-safe
+     rename.
+   - Run the full Mockup analysis schema (screens, user_flow, components,
+     states_visible, copy_excerpts, gaps, design_system_alignment).
+   - Populate `## UI Design` in the state file.
+2. Flip `mockups.status` from `pending_external` to `provided` or `partial`
+   based on coverage of `screens_in_scope[]`. Keep `mockups.source: claude-design`
+   as audit trail.
+3. Fall through to the **Precondition decision tree** below — the `provided` /
+   `partial` row routes to **Hybrid mode** unchanged.
+
+---
+
 ## Precondition decision tree
 
 Read `mockups.status` and `screens_in_scope[]` from the state file `## UI Design`
-section (populated by Step 1.6) plus the UI impact dimension from the discovery
-checklist. Pick exactly one branch:
+section (populated by Step 1.6 and/or Step 3.0 re-entry) plus the UI impact
+dimension from the discovery checklist. Pick exactly one branch:
 
 | Condition | Branch | Action |
 |-----------|--------|--------|
 | UI impact = N/A | **Skip totale** | Mark task 2 `completed` ("Skipped — no UI"). `step_3_mode: skipped`. Proceed to PRD Writing Phase. |
-| `mockups.status: none` AND UI impact ≠ N/A | **Full** | Run the standard pipeline 3a → 3b → 3c → 3d as before. `step_3_mode: full`. |
+| `mockups.status: none` AND UI impact ≠ N/A | **3.0 Decision** | Run Step 3.0 above first. Branch A ⇒ fall through to **Full**; Branch B ⇒ STOP, then re-enter. |
+| `mockups.status: pending_external` | **STOP** | User is in handoff with Claude Design. Do not advance until paths arrive (see § "Re-entry from handoff"). |
+| `mockups.status: none` AND user picked Branch A in Step 3.0 | **Full** | Run the standard pipeline 3a → 3b → 3c → 3d as before. `step_3_mode: full`. |
 | `mockups.status` ∈ {`provided`, `partial`} AND UI impact ≠ N/A | **Hybrid** | Per-screen routing (see § Hybrid mode below). `step_3_mode: hybrid` (or `skipped` if every screen is covered AND no `mockup_analysis.design_system_alignment.violations`). |
 
 Mark task 2 as `in_progress` for the Full and Hybrid branches.

package/package.json

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

package/src/commands/status.js

@@ -4,6 +4,19 @@ const UI = require('../utils/ui');
 const fs = require('fs');
 const path = require('path');
 
+// Lightweight semver compare. Returns positive if a > b, negative if a < b,
+// zero if equal. Treats malformed input as 0 — degrade open rather than throw.
+function cmpSemver(a, b) {
+  if (!a || !b) return 0;
+  const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
 async function status() {
   const git = new GitUtils();
   const symlinks = new SymlinkUtils();
@@ -94,24 +107,43 @@ async function status() {
       }
     }
 
-    // Check for pending updates
+    // Check for pending updates (since v3.17.1 — was a no-op stub before).
     UI.newline();
     UI.section('Update Status');
 
+    let updateAvailable = false;
+    let remoteVersion = null;
     try {
       await git.fetch('antbald/BALDART');
-      UI.info('Checking for updates...');
-      // Simplified - would need more sophisticated version comparison
-      UI.success('Up to date (check with: baldart update)');
+      remoteVersion = await git.getRemoteVersion('antbald/BALDART', 'main');
+      if (!remoteVersion || remoteVersion === 'unknown') {
+        UI.warning('Could not read remote VERSION — check `baldart update` manually.');
+      } else if (cmpSemver(remoteVersion, version) > 0) {
+        updateAvailable = true;
+        UI.warning(`Update available: ${version} → ${remoteVersion}. Run: baldart update`);
+      } else if (cmpSemver(remoteVersion, version) < 0) {
+        UI.info(`Local v${version} is ahead of remote v${remoteVersion} (likely an unreleased commit).`);
+      } else {
+        UI.success(`Up to date (v${version})`);
+      }
     } catch (error) {
       UI.warning('Cannot check for updates (offline?)');
     }
 
     // Summary
     UI.newline();
+    let updateLine;
+    if (updateAvailable && remoteVersion) {
+      updateLine = `Update: ${version} → ${remoteVersion} available`;
+    } else if (remoteVersion && remoteVersion !== 'unknown') {
+      updateLine = `Update: up to date`;
+    } else {
+      updateLine = `Update: unknown (could not reach remote)`;
+    }
     UI.box('SUMMARY', [
       `Version: ${version}`,
       `Installation: ${symlinkValid ? 'Valid' : 'Issues detected'}`,
+      updateLine,
       '',
       'Commands available:',
       '  • baldart update  - Update framework',

package/src/commands/update.js

@@ -81,7 +81,10 @@ async function postUpdateAutoCommit(git, newVersion, options) {
   if (userOwned.length > 0) {
     UI.warning(`${userOwned.length} other dirty path(s) will be left untouched (not BALDART-managed).`);
   }
-  const ok = await UI.confirm(`Commit them as \`chore(baldart): post-update reconcile to v${newVersion}\`?`, true);
+  const autoYes = options && options.yes === true;
+  const ok = autoYes
+    ? true
+    : await UI.confirm(`Commit them as \`chore(baldart): post-update reconcile to v${newVersion}\`?`, true);
   if (!ok) {
     UI.info('Auto-commit declined. Your worktree keeps the changes for manual review.');
     return;
@@ -110,6 +113,13 @@ async function update(options = {}) {
   const symlinks = new SymlinkUtils();
   const repo = 'antbald/BALDART'; // Default repo
 
+  // Non-interactive flags (since v3.17.1). `--yes` implies `--auto-stash`.
+  // When `yes` is set, every UI.confirm/UI.select downstream short-circuits
+  // to its default — the same value an unattended user would have produced.
+  const autoYes = options.yes === true;
+  const autoStash = autoYes || options.autoStash === true;
+  const confirm = async (msg, def = true) => (autoYes ? def : UI.confirm(msg, def));
+
   try {
     // Step 1: Verify installation
     UI.header('STEP 1/5: Verify Installation');
@@ -194,14 +204,14 @@ async function update(options = {}) {
     const diff = await git.diffWithRemote();
     if (diff) {
       UI.info('Changes detected. Review recommended.');
-      const showDiff = await UI.confirm('Show detailed diff?', false);
+      const showDiff = await confirm('Show detailed diff?', false);
 
       if (showDiff) {
         console.log(diff);
       }
     }
 
-    const proceedUpdate = await UI.confirm('Proceed with update?', true);
+    const proceedUpdate = await confirm('Proceed with update?', true);
     if (!proceedUpdate) {
       UI.info('Update cancelled');
       process.exit(0);
@@ -225,10 +235,16 @@ async function update(options = {}) {
       UI.list(unique.slice(0, 8), 'yellow');
       if (unique.length > 8) UI.info(`…and ${unique.length - 8} more.`);
 
-      const action = await UI.select('How would you like to proceed?', [
-        { name: 'Auto-stash now and re-apply after the update (recommended)', value: 'stash' },
-        { name: 'Abort — I want to commit or stash manually first', value: 'abort' }
-      ]);
+      let action;
+      if (autoStash) {
+        UI.info('Auto-stashing dirty paths (--yes / --auto-stash).');
+        action = 'stash';
+      } else {
+        action = await UI.select('How would you like to proceed?', [
+          { name: 'Auto-stash now and re-apply after the update (recommended)', value: 'stash' },
+          { name: 'Abort — I want to commit or stash manually first', value: 'abort' }
+        ]);
+      }
       if (action === 'abort') {
         UI.info('Aborted. Commit or `git stash -u`, then re-run `npx baldart update`.');
         process.exit(0);
@@ -361,9 +377,12 @@ async function update(options = {}) {
         'Convert legacy .claude/skills/ bulk symlink (v2.0.x) into the new per-item layout.',
         `Merge framework skills into per-tool skill dirs (${enabledTools.join(', ')}) without touching your personal skills.`
       ]);
-      const recreate = await UI.confirm('Reconcile symlinks now?', true);
+      const recreate = await confirm('Reconcile symlinks now?', true);
       if (recreate) {
-        await symlinks.createAllSymlinks({ mode: 'prompt', tools: enabledTools });
+        // In auto-yes mode pass 'force' instead of 'prompt' so per-conflict
+        // prompts inside SymlinkUtils don't reintroduce blocking I/O.
+        const mode = autoYes ? 'force' : 'prompt';
+        await symlinks.createAllSymlinks({ mode, tools: enabledTools });
       }
     } else {
       // Re-run the per-item merges for every enabled tool so newly-shipped
@@ -403,10 +422,10 @@ async function update(options = {}) {
       if (!fs.existsSync(configPath)) {
         UI.newline();
         UI.warning('No baldart.config.yml in this project — skills installed by this framework version require it.');
-        const runConfigure = await UI.confirm('Run `baldart configure` now?', true);
+        const runConfigure = await confirm('Run `baldart configure` now?', true);
         if (runConfigure) {
           const configureCmd = require('./configure');
-          await configureCmd();
+          await configureCmd(autoYes ? { nonInteractive: true } : undefined);
         }
       } else {
         // Schema migration: backfill `tools.enabled` for configs created
@@ -425,7 +444,7 @@ async function update(options = {}) {
           UI.warning('Pre-v3.7.0 config detected — `tools.enabled` is missing.');
           UI.info(`From v3.7.0, BALDART can install framework skills for multiple AI tools (Claude Code, OpenAI Codex CLI, …) from the same source.`);
           UI.info(`Autodetected on this machine: ${suggested.join(', ')}`);
-          const ok = await UI.confirm(`Backfill \`tools.enabled: [${suggested.join(', ')}]\` into baldart.config.yml?`, true);
+          const ok = await confirm(`Backfill \`tools.enabled: [${suggested.join(', ')}]\` into baldart.config.yml?`, true);
           if (ok) {
             cur.tools = cur.tools || {};
             cur.tools.enabled = suggested;
@@ -470,10 +489,10 @@ async function update(options = {}) {
               UI.warning(`New config keys in this version: ${allMissing.join(', ')}.`);
               // Auto-offer configure so the user actually answers, instead of
               // silently falling back to template defaults on first use.
-              const runConfigure = await UI.confirm('Run `baldart configure` now to populate them? (existing values are preserved)', true);
+              const runConfigure = await confirm('Run `baldart configure` now to populate them? (existing values are preserved)', true);
               if (runConfigure) {
                 const configureCmd = require('./configure');
-                await configureCmd();
+                await configureCmd(autoYes ? { nonInteractive: true } : undefined);
               } else {
                 UI.info('Skipped. Skills will prompt for the missing keys on first use.');
               }