baldart 3.25.0 → 3.27.0

package/CHANGELOG.md

@@ -5,6 +5,101 @@ 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.27.0] - 2026-05-28
+
+Fix critico al meccanismo di overlay-merge degli agent. Sintomo riproducibile osservato in `mayo` durante `/new FEAT-0009 -full` (team mode, claude-opus-4-7): gli agent overlay-merged (`coder`, `ui-expert`, `code-reviewer`, `doc-reviewer`, `qa-sentinel`, `security-reviewer` quando hanno un overlay) **non comparivano nella lista "Available agent types"** del Claude Code session reminder. Sequenza concreta: `codebase-architect` (symlink) parte e completa; i 4 background agent (`coder×2` + `ui-expert×2`) lanciati subito dopo falliscono con `InputValidationError: subagent_type not recognized`; l'orchestratore halta con un AskUserQuestion fuori-protocollo. Repro: `ls -la .claude/agents/` mostra 21 symlink + 6 file regolari (i 6 overlay-merged); CC discoverizza i 21 symlink e omette i 6 file regolari. Confermato su sessioni indipendenti del 2026-05-27 e 2026-05-28 → bug strutturale, non transiente. Workflow `/new` in team mode, `/check`, `/qa`, `/codexreview` e skill `prd` erano **bloccati end-to-end** su qualsiasi consumer con overlay agent.
+
+### Root cause — Claude Code upstream bug #20931
+
+Il session-start discovery scanner di Claude Code che costruisce la registry di `subagent_type` validi **skippa silenziosamente i file regolari** in `.claude/agents/` (solo i symlink vengono caricati). Il bug è già documentato in `framework/.claude/hooks/agent-discovery-gate.js:10-15`:
+
+> #20931 — file-based discovery of `.claude/agents/*.md` is documented as BROKEN in some scenarios (files ignored at session start)
+
+Dalla v3.8.0 in poi BALDART ha generato i file overlay-merged come **file regolari** direttamente in `.claude/agents/<name>.md`, intersecando esattamente la zona di rottura di CC. Tutti gli overlay agent attivi nei consumer sono stati silenziosamente invisibili per ~3 mesi, e il sintomo emergeva solo quando una skill provava ad invocare lo `subagent_type` (es. team-mode `/new`).
+
+Diagnosi precedente erroneamente attribuita a "HTML comment prima del frontmatter rompe il parser YAML" è stata rivista: il riordino del marker post-frontmatter resta una pulizia di formato corretta ma **non era la causa primaria** del sintomo.
+
+### Fixed — Symlink indirection per agent/command overlay-merged (root cause fix)
+
+- **[src/utils/symlinks.js](src/utils/symlinks.js)** `_generateOverlayedFile()`: il content merged ora vive in `.baldart/generated/<kind>s/<name>.md` (file regolare), e `.claude/agents/<name>.md` (o `.claude/commands/<name>.md`) viene creato come **symlink relativo** verso quel file. Claude Code vede il path consumer come un symlink come tutti gli altri e lo discoverizza correttamente. Stesso pattern per Codex (`.agents/skills/`) tramite il tool adapter.
+- **[src/utils/symlinks.js](src/utils/symlinks.js)** `_installPerItemSymlink()`: quando `hasOverlay` viene rimosso e il path consumer è un symlink che punta in `.baldart/generated/`, il CLI relinka al framework base e cancella lo stale generated file. Coerenza forte tra "overlay esiste" e "esiste un generated file".
+- **[src/utils/symlinks.js](src/utils/symlinks.js)**: migrazione automatica del legacy layout. Se il consumer ha un file regolare baldart-generated direttamente in `.claude/agents/<name>.md` (pre-v3.27.0), la prossima `npx baldart update` lo riconosce dal marker, sposta il content in `.baldart/generated/agents/<name>.md` e crea il symlink. Nessun intervento manuale richiesto. User-fork (file regolare senza marker baldart) restano protetti.
+
+### Added — Safety net SessionStart hook
+
+- **[framework/.claude/hooks/agent-discovery-info.sh](framework/.claude/hooks/agent-discovery-info.sh)**: oltre a rilevare gli agent **mancanti** (file assente), il hook ora rileva anche gli agent in **stato degradato** — ovvero file regolari con marker `<!-- baldart-generated: -->` presenti in `.claude/agents/` (pre-v3.27.0 layout). Quando rilevati, emette `additionalContext` esplicito al modello con il nome degli agent affected, la causa (upstream bug #20931) e l'azione richiesta (`npx baldart update`). Difesa-in-profondità: il `mergeAgents` migra automaticamente e questo hook copre l'edge case in cui un consumer non lanci `update` subito dopo l'upgrade.
+
+### Fixed — Formato file generato (cleanup secondario, non root cause)
+
+- **[src/utils/overlay-merger.js](src/utils/overlay-merger.js)**: i file generati hanno il frontmatter YAML su riga 1 e il marker `<!-- baldart-generated: -->` subito dopo il `---` di chiusura (era prima invertito). Allinea il formato alla convenzione standard CommonMark + YAML frontmatter, indipendentemente dal fatto che CC sia o meno strict sul parser.
+- **[src/utils/overlay-merger.js](src/utils/overlay-merger.js)**: nuovo export `isGeneratedFile(content)` posizione-agnostico. `readMarker()` cerca il marker in tutto il file (cap 4KB) per leggere sia file v3.27.0+ sia legacy pre-v3.27.0 (retrocompat fondamentale per la migration).
+- **[framework/.claude/hooks/framework-edit-gate.js](framework/.claude/hooks/framework-edit-gate.js)**: il PreToolUse hook controlla il marker via `head.includes` su slice 5KB, così intercetta edit ai file generati sia che il marker sia su riga 1 (legacy) sia dopo il frontmatter (v3.27.0+).
+
+### Migration path per i consumer
+
+Su un consumer con overlay agent in layout legacy (es. `mayo`):
+
+1. `npx baldart update` rileva la nuova VERSION e lancia `mergeAgents`.
+2. Per ogni file regolare baldart-generated in `.claude/agents/`: marker letto → content spostato in `.baldart/generated/agents/<name>.md` → simlink creato.
+3. `git status` mostra: `.claude/agents/<name>.md` modificato (file → symlink), `.baldart/generated/agents/<name>.md` nuovo. La `_autoCommitFn` del CLI committa con `chore(baldart): post-update reconcile to v3.27.0`.
+4. **Restart della Claude Code session** richiesto perché la registry di `subagent_type` viene letta al session-start.
+5. Verifica: `Available agent types` ora include tutti i nomi (sia symlink che generated-symlink). `/new` in team mode funziona.
+
+Nessuna perdita di overlay: i file in `.baldart/overlays/agents/*.md` sono consumer-owned e non vengono toccati. Lo skill `/baldart-update` cita esplicitamente nel report post-flight gli agent migrati e ricorda di restartare la sessione CC.
+
+## [3.26.0] - 2026-05-27
+
+Fix definitivo del processo `baldart update` dopo che un'esecuzione reale su un consumer (`mayo`) ha esposto un workflow strutturalmente rotto. Sintomi: `update --yes` stampava "Already up to date!" mentre `version`/`doctor` riportavano correttamente "Remote: 51 commit ahead"; CLI globale (v3.18.1) silenzioso vs npm latest (v3.24.0); divergenza subtree (19 commit locali + 51 upstream) mai menzionata; output sporcato da `ExperimentalWarning` di npm a ogni invocazione; skill `/baldart-update` che narrava il workflow rotto senza accorgersene. Root cause: tre superfici (`update`, `version`, `doctor`) implementavano TRE check diversi per la stessa domanda, e nessuna era giusta — `update.js:193` usava `hasChangesToPush()` (commit LOCALI non pushati al CONSUMER's origin, niente a che vedere con BALDART upstream); `version`/`doctor` usavano `HEAD...FETCH_HEAD` full-repo che include sempre subtree-merge noise → falso positivo perenne "52 commit ahead".
+
+### Fixed — Bug "Already up to date" su consumer con update disponibili
+
+- **[src/utils/git.js](src/utils/git.js)** + **[src/commands/update.js](src/commands/update.js)**: nuova `getUpdateStatus(repo, branch)` SSOT basata su **VERSION compare** (`git show FETCH_HEAD:VERSION` vs `.framework/VERSION`), non sul commit count (che è strutturalmente rumoroso sul subtree). `update.js` Step 2 ora usa `status.isAligned` come segnale autoritativo. Eliminata la chiamata a `git.hasChangesToPush()` (rimane per compatibilità di `push.js`).
+
+### Fixed — Falsi positivi "52 commit ahead / 20 unpushed" perenni
+
+- **[src/commands/version.js](src/commands/version.js)** + **[src/commands/doctor.js](src/commands/doctor.js)**: messaging riscritto su `isAligned`. `Remote: v3.26.0 (aligned)` quando OK, `Remote: v3.26.0 — update available (installed v3.22.1)` altrimenti. Il commit count migra dietro `version --verbose` (etichettato "subtree commit history — includes auto-generated merges"). Doctor `Local changes` mostra `unpushed commit(s)` SOLO se non-aligned (altrimenti tutto subtree-noise → riga `clean`).
+
+### Added — Classifier divergenza subtree (Fix 2)
+
+- **[src/utils/git.js](src/utils/git.js)**: nuova `classifyDivergence()` che ispeziona i commit consumer non in upstream e li categorizza branch-agnostic:
+  - `subtree-merge` (`Merge commit '*' into <any-branch>`) → auto-resolve silente.
+  - `subtree-squash` (`Squashed '.framework/' changes from *`) → auto-resolve silente.
+  - `chore-wrapper` (`[CHORE]` / `chore(baldart):` con `baldart` keyword nel subject o scope) → auto-resolve silente.
+  - `custom-overlay-able` (modifiche SOLO a file in `.framework/.claude/{agents,skills,commands}/`) → prompt: "Migra a overlay (raccomandato)".
+  - `custom-other` → prompt 3-way (push first / pull anyway / abort).
+- Aggregate class `all-noise | overlay-able | real-custom | mixed | unknown`. Default conservativo `custom-other` per commit non riconosciuti — mai data loss silente.
+- Test fixture-driven: **[src/utils/__tests__/classify-divergence.test.js](src/utils/__tests__/classify-divergence.test.js)** con 24 fixture inclusi i pattern commit reali osservati nel debug di `mayo` (`[CHORE] reconcile baldart state ledger v3.22.1 -> v3.25.0`, `[CHORE] register baldart agent-discovery hooks`, ecc.).
+
+### Added — CLI self-upgrade auto-relaunch (Fix 4)
+
+- **[src/commands/update.js](src/commands/update.js)** `maybeRelaunchUnderLatest()`: se il CLI globale è dietro npm latest, `update` rilancia trasparentemente `npx baldart@<latest> update <flags>` con `stdio: inherit` (preserva prompt). Loop guard via env `BALDART_RELAUNCHED=1` (impedisce ricorsione se npm cache serve ancora un vecchio). Fallback al CLI corrente se npx fallisce. Opt-out: `BALDART_NO_RELAUNCH=1`. Razionale rispetto a `update-notifier.js`: l'avvertenza "no auto-update globale" si riferisce a `npm i -g` silente; `npx@latest` è per-invocation, esplicito, opt-out → policy intatta.
+
+### Added — `--reset` nuclear option (Fix 5)
+
+- **[bin/baldart.js](bin/baldart.js)** + **[src/commands/update.js](src/commands/update.js)** `runReset()`: `npx baldart update --reset` rimuove `.framework/` e reinstalla pulito, preservando `baldart.config.yml` + `.baldart/` (overlays, state.json) + `.claude/settings.json` + custom agents/skills/commands non-symlink. Safety gate obbligatorio: working tree clean (refusal se dirty), prompt esplicito per file untracked/ignored in `.framework/` (in `--yes` richiede ALSO `--i-know`), backup tag pre-rm. Post-restore sanity check: se un file user-owned è scomparso, refuse + suggest `git reset --hard <backup-tag>`.
+
+### Added — Soppressione `ExperimentalWarning` (Fix 6)
+
+- **[bin/baldart.js](bin/baldart.js)**: `process.env.NODE_NO_WARNINGS = '1'` impostato ALL'INIZIO (prima di ogni `require`). Propagato a tutti i child process spawnati dal CLI (git, npx, ecc.). Verificato su Node 23.3.0: silenzia il warning. Escape hatch: `BALDART_VERBOSE_WARNINGS=1` lo riabilita. **Limite noto**: non silenzia il warning emesso da `npx` PRIMA che il nostro codice carichi — l'unico workaround è `npm i -g baldart` (modalità raccomandata) + invocazione diretta `baldart`.
+
+### Changed — Auto-backfill hook missing senza prompt (Fix 7)
+
+- **[src/commands/update.js](src/commands/update.js)** logging: hook missing aggregati in una singola linea (`Auto-registered N missing hook(s): a, b, c`) invece di una per hook. La logica `Hooks.registerAll` era già corretta (auto-create silenzioso per missing, prompt solo per drift) — il cambio è cosmetico ma riduce noise post-update.
+
+### Changed — Skill `/baldart-update` parser tollerante + post-flight assert (Fix 9)
+
+- **[framework/.claude/skills/baldart-update/SKILL.md](framework/.claude/skills/baldart-update/SKILL.md)**: Step 0 parser tollerante con 5 pattern in ordine (nuovo format `Remote: vX.Y.Z (aligned)`, format intermedio `update available`, legacy `N commit(s) ahead` / `up to date`, offline) — gestisce la finestra di transizione skill v3.26.0 + CLI globale v3.18.1. Se nessun pattern matcha → istruisce `npm i -g baldart@latest`. Eliminato Step 3 (hooks drift — ora auto-backfill in CLI) e Step 4 (auto-commit prompt — sempre yes in `--yes`). Step 6 ora include **post-flight assert obbligatorio**: confronta `.framework/VERSION` pre/post, FAIL LOUD se exit 0 ma VERSION invariata (safety net contro regression del Fix 1).
+
+### Changed — Doctor planner usa version-compare authority
+
+- **[src/commands/doctor.js](src/commands/doctor.js)** `planActions()`: `remoteAhead = state.remote.fetched && state.remote.isAligned === false`. Label dell'action `update` ora `Update framework (vX.Y.Z → vA.B.C)` invece di `Pull N commit(s) from upstream`. Local-work detection sopprime commit count quando aligned.
+
+### Internal
+
+- Nessuna nuova chiave in `baldart.config.yml`. Schema-change propagation rule non applicabile.
+- `getRemoteVersion()` esistente non più consumato — VERSION compare ora dentro `getUpdateStatus()` via `git show FETCH_HEAD:VERSION`. La funzione resta per back-compat (status.js la chiama).
+- `hasChangesToPush()` resta in `git.js` per `push.js` che la usa correttamente (consumer's origin commits to push upstream).
+
 ## [3.25.0] - 2026-05-27
 
 Strict-phase-gating + workspace-hygiene gates per `/new`. Risolve l'incident **FEAT-0006**: epic team-mode (4-layer L0→L1×5→L2×2→L3×2, 10 sub-card) che ha saltato per ogni card le fasi MANDATORY 2.5b (AC-Closure), 2.55 (Simplify), 2.6 (E2E-Review), 3 (Doc-Review), 3.5 (QA-Sentinel), 3.7 (Codexreview) — giustificazione documentata come "time budget", parola **inventata dal modello a runtime**, non esistente nella skill. In aggiunta, AC-IMG-3 "deferred dal coder 09" senza passare dal gate, e main repo lasciato con orphan commit non pushato + local `develop` diverged. Tre root cause radicate: (1) Phase 2.5b non era propagata in team-mode Step D, (2) coder `completion-report` accettava `status: partial`/`blocked` come terminale, (3) zero gate di workspace hygiene su `$MAIN`.

package/VERSION

@@ -1 +1 @@
-3.25.0
+3.27.0

package/bin/baldart.js

@@ -1,5 +1,17 @@
 #!/usr/bin/env node
 
+// Suppress ExperimentalWarning noise from Node/npm internals (v3.25.0+).
+// On Node 22+ npm emits a CommonJS/ESM ExperimentalWarning on every spawn —
+// not actionable for our users, repeated on every invocation, illegible.
+// Setting NODE_NO_WARNINGS in env BEFORE any spawn propagates to all
+// child processes we launch (git, npx, etc). Cannot silence the warning
+// emitted by `npx` itself BEFORE our code loads — for that, the
+// recommended install is `npm i -g baldart` (then `baldart` direct).
+// Escape hatch: BALDART_VERBOSE_WARNINGS=1 keeps them visible.
+if (process.env.BALDART_VERBOSE_WARNINGS !== '1' && !process.env.NODE_NO_WARNINGS) {
+  process.env.NODE_NO_WARNINGS = '1';
+}
+
 const { Command } = require('commander');
 const chalk = require('chalk');
 const fs = require('fs');
@@ -58,6 +70,8 @@ program
   .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.')
+  .option('--reset', 'Nuclear option: rm -rf .framework/ + fresh install, preserving baldart.config.yml + .baldart/ + custom .claude/{agents,skills,commands}/. Requires clean working tree.')
+  .option('--i-know', 'Acknowledges --reset will wipe untracked/ignored files inside .framework/ (required to use --reset --yes).')
   .action(async (options) => {
     const updateCommand = require('../src/commands/update');
     await updateCommand(options);

package/framework/.claude/hooks/agent-discovery-info.sh

@@ -62,9 +62,19 @@ CONSUMER_AGENTS_DIR=".claude/agents"
 
 [ -d "$FRAMEWORK_AGENTS_DIR" ] || exit 0  # consumer not installed — silent.
 
-# --- compute missing set --------------------------------------------------
+# --- compute missing + degraded sets --------------------------------------
+#
+# MISSING — file does not exist (or symlink is broken). agent-discovery-gate
+#           will hard-deny calls to these names.
+# DEGRADED — file exists as a *regular file* with the baldart-generated marker.
+#           Pre-v3.27.0 layout produced these, but Claude Code upstream bug
+#           #20931 skips regular files at session-start discovery, so the
+#           `subagent_type` value is silently unavailable to the orchestrator.
+#           The fix is `npx baldart update` (migrates them to a symlink into
+#           .baldart/generated/<kind>s/).
 
 MISSING=""
+DEGRADED=""
 while IFS= read -r f; do
   [ -z "$f" ] && continue
   name="$(basename "$f" .md)"
@@ -72,16 +82,21 @@ while IFS= read -r f; do
   target="$CONSUMER_AGENTS_DIR/${name}.md"
   # `test -e` returns false for broken symlinks too — exactly what we want.
   if [ ! -e "$target" ]; then
-    if [ -z "$MISSING" ]; then
-      MISSING="$name"
-    else
-      MISSING="$MISSING, $name"
+    if [ -z "$MISSING" ]; then MISSING="$name"; else MISSING="$MISSING, $name"; fi
+    continue
+  fi
+  # File exists. If it's a symlink → CC discovery sees it, healthy.
+  # If it's a regular file with the baldart-generated marker → degraded
+  # state (legacy overlay layout before v3.27.0).
+  if [ ! -L "$target" ] && [ -f "$target" ]; then
+    if head -c 4096 "$target" 2>/dev/null | grep -q "<!-- baldart-generated:" ; then
+      if [ -z "$DEGRADED" ]; then DEGRADED="$name"; else DEGRADED="$DEGRADED, $name"; fi
     fi
   fi
 done < <(find "$FRAMEWORK_AGENTS_DIR" -maxdepth 1 -type f -name '*.md' 2>/dev/null | sort)
 
-# Nothing missing — exit silently. No noise when everything is healthy.
-[ -z "$MISSING" ] && exit 0
+# Nothing to report — exit silently. No noise when everything is healthy.
+[ -z "$MISSING" ] && [ -z "$DEGRADED" ] && exit 0
 
 # --- emit additionalContext ----------------------------------------------
 
@@ -90,7 +105,14 @@ escape_json() {
   printf '%s' "$1" | awk 'BEGIN{ORS=""} {gsub(/\\/,"\\\\"); gsub(/"/,"\\\""); gsub(/\r/,""); gsub(/\n/,"\\n"); print}'
 }
 
-MSG="BALDART expects the following sub-agents to be reachable via the Agent tool in this session, but their backing files are missing from .claude/agents/: ${MISSING}. Calling Agent with one of these subagent_type values will be denied by the agent-discovery-gate PreToolUse hook. Run \`npx baldart doctor\` to repair, then restart this session."
+MSG=""
+if [ -n "$MISSING" ]; then
+  MSG="BALDART expects the following sub-agents to be reachable via the Agent tool in this session, but their backing files are missing from .claude/agents/: ${MISSING}. Calling Agent with one of these subagent_type values will be denied by the agent-discovery-gate PreToolUse hook. Run \`npx baldart doctor\` to repair, then restart this session."
+fi
+if [ -n "$DEGRADED" ]; then
+  DEG_MSG="BALDART detected overlay-merged agents stored in the legacy pre-v3.27.0 layout (regular files in .claude/agents/ with the baldart-generated marker): ${DEGRADED}. Claude Code upstream bug #20931 silently skips regular files at session-start discovery, so calling Agent with one of these subagent_type values will fail with InputValidationError even though the file is on disk. Run \`npx baldart update\` to migrate to the v3.27.0+ symlink-indirection layout (the file is moved to .baldart/generated/<kind>s/<name>.md and .claude/agents/<name>.md becomes a symlink to it), then restart this session."
+  if [ -n "$MSG" ]; then MSG="${MSG} | ${DEG_MSG}"; else MSG="$DEG_MSG"; fi
+fi
 
 cat <<JSON
 {

package/framework/.claude/hooks/framework-edit-gate.js

@@ -163,18 +163,24 @@ function main() {
 
   // v3.8.0+: also block direct edits to BALDART-generated files (agents /
   // commands generated from base + overlay). These live OUTSIDE .framework/
-  // but carry the baldart-generated marker comment as their first line.
-  // The user should edit the overlay, not the generated file, otherwise the
-  // next `baldart update` will overwrite their changes.
+  // but carry the baldart-generated marker comment in their head. Pre-v3.27.0
+  // the marker was on line 1; v3.27.0+ places it after the YAML frontmatter
+  // and the actual file lives in .baldart/generated/<kind>s/<name>.md with a
+  // symlink from .claude/agents/<name>.md. Match both layouts. The structural
+  // regex (requires kind=…name=…overlay_sha=…) avoids false-positives on
+  // framework source files that mention the marker as a string literal
+  // (e.g. this hook itself, agent-discovery-info.sh, overlay-merger.js).
+  const GENERATED_MARKER_RE =
+    /<!-- baldart-generated:[\s\S]{0,400}?kind=\S+[\s\S]{0,400}?name=\S+[\s\S]{0,400}?overlay_sha=\S+/;
   try {
     const fs = require('fs');
     if (fs.existsSync(filePath)) {
-      const head = fs.readFileSync(filePath, 'utf8').slice(0, 200);
-      if (head.startsWith('<!-- baldart-generated:')) {
-        // Allow ONLY if the edit explicitly retains the marker on line 1 —
+      const head = fs.readFileSync(filePath, 'utf8').slice(0, 5000);
+      if (GENERATED_MARKER_RE.test(head)) {
+        // Allow ONLY if the edit explicitly retains the marker —
         // catches accidental overwrites while letting BALDART itself regenerate.
         const newContent = extractNewContent(toolName, input.tool_input) || '';
-        if (!newContent.startsWith('<!-- baldart-generated:')) {
+        if (!GENERATED_MARKER_RE.test(newContent)) {
           const reason =
             `Cannot edit BALDART-generated file (${filePath}).\n` +
             `This file is auto-generated by \`npx baldart update\` from a base ` +

package/framework/.claude/skills/baldart-update/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: baldart-update
-description: "Guidance for updating BALDART framework to the latest version in a consumer repo. Use when the user says /baldart-update, 'aggiorna baldart', 'aggiorna framework', 'update del framework', 'pull baldart latest', or wants to bring the framework up-to-date. Replicates all 5 native CLI decision points (preview diff, working tree stash, hooks drift, schema config drift, BALDART-managed auto-commit) as chat-side confirmations before launching `npx baldart update --yes` via Bash. For non-update drift, defers to `npx baldart` (smart doctor)."
+description: "Guidance for updating BALDART framework to the latest version in a consumer repo. Use when the user says /baldart-update, 'aggiorna baldart', 'aggiorna framework', 'update del framework', 'pull baldart latest', or wants to bring the framework up-to-date. Replicates the native CLI's user-decision points (preview diff, working-tree stash) as chat-side confirmations, lets the CLI auto-resolve mechanical noise (hook backfill, subtree-merge commits, schema migration), and asserts post-flight that .framework/VERSION actually changed. For non-update drift, defers to `npx baldart` (smart doctor)."
 contamination_scan: skip
 ---
 
@@ -12,10 +12,10 @@ pull_request). When any of the numbers below changes against the actual
 sources, a warning is surfaced in the workflow run. The decision whether
 this skill needs an update is left to a human reviewer.
 
-update_js_prompts: 6
+update_js_prompts: 7
 hook_registry_entries: 3
 config_template_top_level_keys: features,git,identity,lsp,paths,stack,tools,version
-last_verified: v3.21.2
+last_verified: v3.26.0
 -->
 
 
@@ -122,15 +122,25 @@ for the protocol.
    how to proceed or aborts. Never silence a decision point because a
    probe failed.
 
-## The 5 decision points the skill replicates
+## Decision points the skill still replicates (v3.26.0+)
+
+Before v3.26.0 this skill chat-replicated five CLI decision points. As of
+v3.26.0 the CLI itself silently auto-resolves three of them (hooks drift,
+schema config drift, BALDART-managed auto-commit) when they don't involve
+real user choices. The skill is now down to two prompts plus a mandatory
+post-flight assert:
 
 | # | Native CLI prompt           | Chat-side replication                                                                                                                                  | Detect via                                                                                                                                                          |
 |---|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| 1 | "Proceed with update?"       | Show "Remote: N commit(s) ahead" + last N commit messages, ask "Procedo?"                                                                              | `npx baldart version` (parse "Remote: …" + "Repository: <url>") → if N > 0, `git fetch <url> main && git log HEAD..FETCH_HEAD --oneline -- .framework/`              |
+| 1 | "Proceed with update?"       | Show "Remote: vX.Y.Z" + (if known) last commit messages, ask "Procedo?"                                                                                 | `npx baldart version` (parse `Remote:` line with tolerant matcher — see Step 0)                                                                                     |
 | 2 | "Stash dirty working tree?"  | List modified files, explain they will go into `baldart-pre-update-<timestamp>`, ask explicit confirmation                                              | `git status --porcelain` in consumer root                                                                                                                            |
-| 3 | Hooks drift prompt           | Compare `.claude/settings.json` entries vs `HOOK_REGISTRY`; if drift, describe what backfill will change                                                | `cat .claude/settings.json` + read `.framework/src/utils/hooks.js` for `HOOK_REGISTRY`                                                                               |
-| 4 | Schema config migration      | Compare `baldart.config.yml` keys vs `.framework/framework/templates/baldart.config.template.yml`; if missing keys, list which + consequence            | semantic diff key-by-key (NOT textual diff)                                                                                                                          |
-| 5 | Auto-commit BALDART-managed  | Classify `git status --porcelain` paths as BALDART-managed vs user-owned by path-prefix, show classification, confirm commit of the managed subset      | path-prefix matching on `.framework/`, `.claude/agents/`, `.claude/skills/`, `.claude/commands/`, `AGENTS.md`, `agents/`                                              |
+
+**Auto-resolved by CLI in v3.26.0+** (no chat replication needed):
+- **Hooks drift**: missing hooks auto-registered silently; only command-level drift prompts (and only if interactive).
+- **Schema config drift**: surfaces as a warning post-update; never blocks.
+- **BALDART-managed auto-commit**: `--yes` commits silently with `chore(baldart):` subject.
+- **Subtree-merge / chore divergence commits**: classified by the CLI; auto-resolved silently when `all-noise`, prompts only for `overlay-able` / `real-custom` / `mixed`.
+- **CLI self-upgrade**: transparent relaunch via `npx baldart@latest` when global CLI is stale.
 
 > **IMPORTANT — do NOT use `git -C .framework fetch`.** `.framework/` is a git
 > subtree, not a separate repo: git commands inside it fall back to the consumer's
@@ -145,19 +155,44 @@ for the protocol.
 ### Step 0 — Pre-flight (read-only)
 
 ```bash
-# One call gives both: installed version, behind count, and the
-# BALDART repo URL. NO git operation inside .framework/ — that
+# One call gives installed version, remote version, alignment status, and
+# the BALDART repo URL. NO git operation inside .framework/ — that
 # directory is a git subtree, not a separate repo.
 npx baldart version
 ```
 
-Parse the output for:
-
-- `Installed: vX.Y.Z` — current framework version in the consumer.
-- `Remote: N commit(s) ahead — pull with …` — number of commits behind upstream. If this line is absent or shows 0, the consumer is up-to-date.
-- `Repository: <url>` — the BALDART git URL (needed in Step 1).
-
-If `Remote:` is absent / shows 0 → tell the user "Already up-to-date — version vX.Y.Z" and STOP. Do not launch the CLI.
+**Parser tollerante** — the output format changed in v3.26.0 (version-compare
+authority instead of subtree-merge commit count). The skill must accept BOTH
+the new and legacy formats so it works during the transition window where
+the consumer has the new skill but an older global CLI.
+
+Match the `Remote:` line in this order (first match wins):
+
+| # | Pattern (regex)                                              | Meaning                                                            |
+|---|--------------------------------------------------------------|--------------------------------------------------------------------|
+| 1 | `Remote:\s+v(\S+)\s+\(aligned\)`                             | NEW — aligned, save `remoteVersion` for post-flight                |
+| 2 | `Remote:\s+v(\S+)\s+(?:—\|--)\s+update available`             | NEW — NOT aligned, save `remoteVersion`                            |
+| 3 | `Remote:\s+(\d+)\s+commit\(s\)\s+ahead`                      | LEGACY — count > 0 means NOT aligned (subtree-merge noise possible)|
+| 4 | `Remote:\s+up to date`                                       | LEGACY — aligned                                                   |
+| 5 | `Remote:\s+\(offline.*\)`                                    | unknown — ASK the user how to proceed                              |
+
+Always also capture:
+- `Installed:\s+v(\S+)` → `installedVersion` (saved for post-flight assert).
+- `CLI:\s+v\S+\s+→\s+v(\S+)\s+available` → if present, tell the user once:
+  "Il CLI globale è vecchio (v<old> → v<new>). L'update lo gestirà
+  auto-relanciando via `npx baldart@latest` — niente da fare."
+
+**Decision after parsing**:
+
+- Patterns 1 or 4 → "Already up-to-date — version v<installedVersion>". STOP.
+  Do not launch the CLI.
+- Patterns 2 or 3 → continue with Step 1 (preview + update).
+- Pattern 5 → ask the user: "Vuoi forzare un fetch e ritentare, o procedere
+  in modalità offline (l'update fallirà nel CLI)?". STOP if unclear.
+- **No pattern matches** → the CLI output format is unknown. Tell the user:
+  "Il CLI installato globalmente non emette un format riconosciuto.
+  Aggiorna il CLI con `npm i -g baldart@latest` e ri-invoca /baldart-update."
+  STOP.
 
 If `.framework/` does not exist, `npx baldart version` will say "framework not installed" — STOP and instruct `npx baldart add`. Do not attempt to recover.
 
@@ -195,73 +230,72 @@ chat, explain:
 If the user refuses → STOP, instruct them to commit or stash manually
 and re-run `/baldart-update`.
 
-### Step 3 — Replicate decision points #3 + #4 (hooks/schema drift)
+### Step 3 — Run the CLI
 
 ```bash
-# Hooks drift detection
-cat .claude/settings.json
-# Compare entries against HOOK_REGISTRY in .framework/src/utils/hooks.js
-# (the skill reads both and reports any expected entry missing
-# or any installed entry with a stale config)
-
-# Schema drift detection
-# Compare top-level keys in baldart.config.yml against
-# .framework/framework/templates/baldart.config.template.yml
-```
-
-For each drift detected, describe what `update.js` would do:
-
-- Hooks drift → "il CLI registrerà le hook mancanti in `settings.json`
-  (entry: `baldart-<hook-name>`). Procedo?"
-- Schema drift → "il CLI segnalerà che mancano le chiavi `X.Y` da
-  `baldart.config.yml` e suggerirà di rilanciare `npx baldart configure`
-  dopo l'update. Procedo (l'update non bloccherà, ma è bene saperlo)?"
-
-If a probe fails (e.g. `settings.json` malformed), ask the user how to
-proceed — never silently assume "no drift".
-
-### Step 4 — Replicate decision point #5 (auto-commit classification)
-
-```bash
-git status --porcelain
+npx baldart update --yes
 ```
 
-Classify each path:
-
-- **BALDART-managed**: starts with `.framework/`, `.claude/agents/`,
-  `.claude/skills/`, `.claude/commands/`, `AGENTS.md`, `agents/`.
-- **User-owned**: everything else.
-
-Show the user the classification:
-
-> *"Dopo il pull, il CLI auto-committa SOLO i file BALDART-managed che
-> risultano modificati dal reconcile (es. symlink ricreati, agent/command
-> generati). I tuoi file user-owned non vengono toccati. Procedo?"*
+**Use the Bash tool with `timeout: 600000`** (10 minutes). Capture stdout
+and stderr — both are needed for Step 4.
 
-If no managed files would be modified, skip the prompt silently.
+Do NOT pass `--auto-stash` (redundant with `--yes`).
 
-### Step 5 — Run the CLI
+**What the CLI auto-resolves without prompting** (since v3.26.0):
+
+- **Hooks drift**: missing hooks are auto-registered silently. Hooks with
+  modified commands stay user-customised (warning surfaced in `--yes` mode,
+  interactive prompt otherwise).
+- **Schema config drift**: new config keys are reported as a warning; the
+  user is told to run `npx baldart configure` later. The update never
+  blocks on schema drift.
+- **BALDART-managed auto-commit**: in `--yes` mode the CLI commits any
+  files it touched during the reconcile with `chore(baldart): post-update
+  reconcile to vX.Y.Z`. User-owned files are never staged.
+- **Subtree-merge / chore divergence commits**: when the consumer has
+  local commits that are just `git subtree pull` plumbing or CLI-generated
+  `[CHORE]` commits, the CLI auto-resolves silently. Real user-custom
+  commits ABORT in `--yes` mode (the user must re-run without `--yes` to
+  choose).
+- **CLI self-upgrade**: if the global CLI is older than npm latest, the
+  update transparently relaunches itself via `npx baldart@latest update
+  --yes`. Loop-guarded by `BALDART_RELAUNCHED=1`.
+
+The skill no longer chat-replicates these decision points — they are
+either silent (no user choice involved) or only triggered by genuine
+user content, in which case the CLI surfaces the prompt directly.
+
+### Step 4 — Post-flight assert + Report
+
+**Post-flight assert (MANDATORY — safety net against silent CLI bugs)**:
 
 ```bash
-npx baldart update --yes
+# Read the new installed version
+cat .framework/VERSION
 ```
 
-**Use the Bash tool with `timeout: 600000`** (10 minutes). Capture stdout
-and stderr — both are needed for Step 6.
-
-Do NOT pass `--auto-stash` (redundant with `--yes`).
+Compare against `installedVersion_before` saved in Step 0:
 
-### Step 6 — Report
+- **If `before === after` AND stdout DOES NOT contain "Already up to date"** →
+  the CLI exited 0 but the framework didn't actually update. **FAIL LOUD**:
+  ```
+  ✗ Update CLI exited 0 but .framework/VERSION did not change.
+    Before: v<before> | After: v<after>
+    This is a CLI bug — please report the full stdout/stderr above.
+    The repo is in an inconsistent state; do NOT continue assuming success.
+  ```
+  Do NOT report success. Do NOT mark the task complete.
+- **If stdout contains "Already up to date" but Step 0 had a `remoteVersion`
+  different from `installedVersion`** → same FAIL LOUD (this is the v3.24.x
+  bug regression check — Fix 1 of v3.26.0 must not regress).
+- Otherwise → success path.
 
-Extract the post-update facts and surface them:
+Then extract the post-update facts and surface them:
 
 ```bash
 # Backup tag (most recent baldart-pre-update-* tag)
 git tag -l 'baldart-pre-update-*' --sort=-creatordate | head -1
 
-# New installed version
-cat .framework/VERSION
-
 # Stash-pop conflicts (if any)
 # Grep stdout/stderr for: CONFLICT, "stash pop failed", "unmerged paths"
 # If matches found, list the conflicted paths:
@@ -270,15 +304,31 @@ git status --porcelain | grep '^UU'
 
 Report to the user, in order:
 
-1. **Version**: `vX.Y.Z → vA.B.C` (delta).
+1. **Version**: `vX.Y.Z → vA.B.C` (delta — both from `cat .framework/VERSION`
+   pre and post).
 2. **Backup tag**: the `baldart-pre-update-<timestamp>` ref, with the
    rollback command: `git reset --hard <tag>` (only if needed).
-3. **Hooks reconciled**: any hook backfilled.
-4. **Schema notes**: any missing key still flagged → suggest
+3. **CLI self-upgrade**: if stdout mentions "Auto-relaunching via npx
+   baldart@…", surface it once so the user knows the CLI bumped too.
+4. **Hooks reconciled**: any hook backfilled (parse "Auto-registered N
+   missing hook(s)" or per-line "Registered hook" from stdout).
+5. **Agent layout migration (v3.27.0+)**: parse stdout for lines matching
+   `agent generated (overlay applied): .claude/agents/<name>.md → ../../.baldart/generated/agents/<name>.md`.
+   Pre-v3.27.0 overlay-merged agents (`coder`, `ui-expert`, `code-reviewer`,
+   `doc-reviewer`, `qa-sentinel`, `security-reviewer` when overlayed) lived
+   as regular files in `.claude/agents/` and were silently invisible to
+   Claude Code session-start discovery (upstream bug #20931). The CLI now
+   stores merged content in `.baldart/generated/<kind>s/<name>.md` and
+   places a symlink at `.claude/agents/<name>.md`. Report the migrated
+   names so the user knows they should restart their CC session for the
+   new layout to take effect on `subagent_type` resolution.
+6. **Schema notes**: any missing key still flagged → suggest
    `npx baldart configure`.
-5. **Stash-pop status**: clean / conflicts present (with file list).
-6. **Suggested next step**: if schema drift residual or other non-update
-   doctor checks fired, suggest `npx baldart` (smart doctor).
+7. **Stash-pop status**: clean / conflicts present (with file list).
+8. **Suggested next step**: if schema drift residual or other non-update
+   doctor checks fired, suggest `npx baldart` (smart doctor). Also remind:
+   if any agent was migrated (step 5), **restart the Claude Code session**
+   so the discovery scanner sees the new symlinks.
 
 ## Failure modes
 

package/package.json

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