baldart 3.24.0 → 3.26.0

package/CHANGELOG.md

@@ -5,6 +5,105 @@ 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.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`.
+
+### Added — Phase 0: Workspace Hygiene Pre-flight (BLOCKING)
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)**: nuova `## Phase 0` prima di `## Pre-flight (once)`. Su `$MAIN`: `fetch origin`, dirty-tree gate (`git status --porcelain` → `AskUserQuestion` con opzioni `[stash auto] / [commit ora] / [procedi senza stash] / [abort]`), divergence gate (`rev-list --left-right --count` → `AskUserQuestion` per ahead/behind/diverged). Stash ref salvato nel tracker sotto `## Workspace Snapshot` per il restore di Phase 6c. Anti-bypass guard finale che rifiuta di proseguire senza `## Phase 0: PASS` nel tracker. Auto Mode NON override.
+
+### Added — Phase 6c: Workspace Hygiene Post-merge (BLOCKING)
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)**: nuova `### Phase 6c` dopo Phase 6b. Parse del marker `[SYNC-DEFERRED]` emesso da `/mw`, clean-tree assertion, divergence assertion (cattura il pattern FEAT-0006 orphan commit con `AskUserQuestion` opzioni `[push adesso] / [cherry-pick] / [reset --hard con conferma esplicita] / [halt]`), restore dello stash di Phase 0 (con `AskUserQuestion` su conflict, mai silent drop). Anti-bypass guard come in Phase 0.
+
+### Added — Team-mode Step D rewrite (FEAT-0006 anti-regression)
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)** righe ~1988: nuovo Step D con clausola di apertura esplicita ("La lean Step D è ora FORBIDDEN") + sub-step MANDATORY per-card propagati identici al sequential mode:
+  - **D.3a** — Phase 2.5b AC-Closure Gate per-card (sequenziale), bloccante.
+  - **D.3b** — Phase 2.55 Simplify per-card (diff per-card per attribuibilità).
+  - **D.3c** — Phase 2.6 E2E-Review per-card (honora il Gate table esistente — skip backend-only/docs/chore con motivazione documentata, mai con "time budget").
+  - **D.4a** — Phase 3 Doc Review per-card (oltre al D.2 combined).
+- **Coverage assertion** end-of-group MANDATORY: prima di Step E, il tracker deve contenere per OGNI card le entry `AC Closure Ledger`, `simplify`, `e2e-review`, `doc-review`, `qa`, `codex-review`. Entry mancante → ritorno alla sub-step mancante. Documentare "skipped per time budget" è violazione esplicita.
+
+### Added — Top-of-file rigidity clause + tracker header
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)**: nuovo blockquote `> **NO PHASE SKIP FOR PERCEIVED TIME, EVER (BLOCKING)**` subito sotto SCOPE CLOSURE DISCIPLINE. Enumera esplicitamente le phrase forbidden (`time budget`, `context budget`, `context pressure as override`, `for time`, `to save tokens`, `to save iterations`). Self-correction trigger: se il modello produce una di queste phrase nel proprio output, deve fermarsi e routare via `AskUserQuestion`.
+- **Tracker template** (~riga 50): HTML comment header che sopravvive alle compaction e ricorda la regola dopo ogni context recovery.
+
+### Changed — `coder` agent completion report (semantica binaria)
+
+- **[framework/.claude/agents/coder.md](framework/.claude/agents/coder.md)**: card-level `status:` enum ridotto a `done | failed` (era `done | partial | failed`). Per-requirement e per-AC `status:` ridotto a `done | not_implemented` (era `done | partial | blocked`). Le legacy values `partial`/`blocked` erano usate come canali di silent deferral. Aggiunta a `Forbidden Actions`: "Don't defer acceptance criteria" + "Don't invent skip reasons". Retro-compatibile: coder che emettono ancora `partial` faranno triggerare il gate Phase 2.5b invece di passare in silenzio.
+
+### Changed — `framework/agents/workflows.md` Scope Closure Discipline
+
+- Nuovo `### Coder authority (no defer)` in coda alla sezione: chiarisce che coder e orchestratori L0/L1 relay-ano i signal nel gate, non li aggregano/filtrano. Citable da skill e agent.
+
+### Changed — `/mw` `[SYNC-DEFERRED]` structured marker
+
+- **[framework/.claude/skills/worktree-manager/SKILL.md](framework/.claude/skills/worktree-manager/SKILL.md)** righe ~835–855: quando `$MAIN` HEAD ≠ develop, oltre al `fetch` esistente emette ora `[SYNC-DEFERRED] main repo HEAD=<branch>, ...` su stdout. `/mw` standalone preserva l'isolamento terminale (no auto-checkout); orchestratori upstream (Phase 6c di `/new`) parsano il marker e routano la riconciliazione via user gate.
+
+### Why MINOR (not MAJOR)
+
+Tutte le fasi MANDATORY esistevano già — vengono solo propagate (team-mode Step D) e rese non-bypassabili. Le nuove Phase 0/6c sono additive bloccanti, non rimuovono né rinominano capability. La semantica del `completion-report` cambia ma è retro-compatibile: coder pre-3.25 che emettono `partial`/`blocked` triggerano il gate invece di passare silently, e il gate ora esiste in team-mode. Per la decision tree in MAINTAINING.md "Tightened existing MANDATORY gates without removing capabilities → MINOR". L'incident FEAT-0006 era un fallimento di propagazione, non di design — la fix riallinea l'implementazione all'intent originale di v3.24.0.
+
+### Why no schema-change propagation
+
+Modifiche testuali a 4 file framework. Zero chiavi nuove in `baldart.config.yml`, zero modifiche CLI (`src/commands/*`), zero hook nuovi, zero adapter, zero template. Considerato e scartato `policy.strict_phase_gating: true`: sarebbe 5 punti di propagazione (template + configure + update + skill + CHANGELOG) per zero beneficio tunable dall'utente — gli overlay `.baldart/overlays/new.md` restano la via per personalizzazioni progettuali. Verifica: `grep -r "policy.strict_phase_gating\|features.strict_phase_gating" framework/ src/` deve restituire vuoto.
+
 ## [3.24.0] - 2026-05-27
 
 Nuovo gate **AC-Closure** (Phase 2.5b) in `/new` + regola **Scope Closure Discipline** in `framework/agents/workflows.md`. Risolve il pattern ricorrente in cui l'orchestratore — sotto pressione di context-window o complessità inattesa — defer-iva unilateralmente acceptance criteria numerate marcandole `deferred` negli `implementation_notes` YAML con razionalizzazione post-hoc ("ApproveSheet già copre il confirm"). Caso reale che ha innescato la fix: sessione `/new` su FEAT-0005 (2026-05-27) dove 5 AC su 22 sono state silenziosamente deferite con razionalizzazione poi rivelata falsa alla verifica funzionale. Le decisioni di deferral sono ora **sempre routate all'utente via `AskUserQuestion`** una-per-AC.

package/VERSION

@@ -1 +1 @@
-3.24.0
+3.26.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/agents/coder.md

@@ -250,21 +250,22 @@ Do NOT wait until the end to verify your work. After each sub-task that changes
 
 ```completion-report
 card: <CARD-ID>
+status: done | failed
 files_modified: [src/path/a.ts, src/path/b.ts]
 files_created: [src/path/new.ts]
 tsc_clean: true | false
 requirements:
   - id: 1
     text: "[verbatim requirement text from card]"
-    status: done | partial | blocked
+    status: done | not_implemented
     evidence: "src/path/to/file.ts:LINE_NUMBER"
-    notes: "[if partial or blocked: explain why; otherwise omit]"
+    notes: "[if not_implemented: state factually what is missing; do NOT propose deferral or rationalization]"
   - id: 2
     [repeat for each requirement]
 acceptance_criteria:
   - id: 1
     text: "[verbatim criterion text from card]"
-    status: done | partial | blocked
+    status: done | not_implemented
     evidence: "src/path/to/file.ts:LINE_NUMBER"
 components_reused: [ComponentName from src/path]
 components_created: [NewComponent in src/path]
@@ -282,8 +283,10 @@ scope_boundaries_respected: true | false
 ```
 
 Rules for the report:
+- `status` at card level is **binary**: `done` (all requirements and acceptance criteria are `done`) or `failed` (anything else, including a single `not_implemented` row). There is no `partial`. The orchestrator's AC-Closure Gate decides what happens with `failed` cards — your job is to report state truthfully.
+- Per-requirement and per-AC `status` is **binary**: `done` or `not_implemented`. The legacy values `partial` and `blocked` are removed — they were used as silent deferral channels and the gate now intercepts them at the orchestrator. Report what is in the diff and what is not. Do not propose a verdict.
 - `evidence` MUST be a real file path and line number you actually wrote/modified — do NOT fabricate.
-- If a requirement is `partial` or `blocked`, the notes field is required.
+- If a requirement or AC is `not_implemented`, the `notes` field is required and MUST describe factually what is missing (e.g. "no LCP measurement wired in `app/orders/page.tsx`"). It MUST NOT contain phrases like "deferred to follow-up", "covered by X", "out of scope", "redundant with Y", "time budget", "context pressure" — those are deferral verdicts and only the user issues verdicts via the gate.
 - List every requirement and acceptance criterion from the card — do not skip any.
 - `files_modified` and `files_created` MUST list every file you touched — downstream reviewers use this as their scope boundary.
 - `tsc_clean` MUST reflect the actual result of your last `npx tsc --noEmit` run.
@@ -312,6 +315,8 @@ Use judgment on review depth, but do not bypass repo-required QA gates.
 - Don't add dependencies without documenting them.
 - Don't force push without owner approval.
 - Don't invent alternative git workflows or testing gates.
+- **Don't defer acceptance criteria.** Deferral is a user decision routed through the orchestrator's AC-Closure Gate (`AskUserQuestion`, one question per AC). You report `done` or `not_implemented`; the gate decides whether `not_implemented` becomes an approved deferral, a fix-loop, or a halt. Do NOT mark an AC as `partial`, `blocked`, `deferred`, `out of scope`, `redundant with X`, `covered by Y`, or any equivalent — those values do not exist for you.
+- **Don't invent skip reasons.** Phrases like `time budget`, `context budget`, `context pressure as override`, `not in scope of this card`, `optional`, or any constraint not enumerated in the card YAML or in a phase's documented Gate table are forbidden. If you genuinely cannot make progress after 3 self-heal attempts, set the card-level `status: failed`, leave per-requirement statuses honest, and stop. The orchestrator handles the rest.
 - **NEVER create, checkout, or switch a git branch autonomously.** See the Hard Rule at the top of this file. No `git checkout -b`, no `git switch -c`, no `git branch`, no `git worktree add`. The `git_strategy` field is descriptive context, NOT authorization. Only an explicit literal instruction in the task prompt ("create branch X", "checkout Y") authorizes branch operations. When in doubt: stay on the current branch and report back in the completion report.
 
 Keep it simple. Write good code. Ask if unsure.

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,14 +304,18 @@ 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. **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
+6. **Stash-pop status**: clean / conflicts present (with file list).
+7. **Suggested next step**: if schema drift residual or other non-update
    doctor checks fired, suggest `npx baldart` (smart doctor).
 
 ## Failure modes