baldart 3.25.0 → 3.26.0

package/CHANGELOG.md

@@ -5,6 +5,59 @@ 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`.

package/VERSION

@@ -1 +1 @@
-3.25.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/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

package/package.json

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

package/src/commands/doctor.js

@@ -117,15 +117,22 @@ function overlayDrift(cwd, frameworkVersion) {
 }
 
 async function describeRemote(git, repo, offline) {
-  // Best-effort remote drift detection. Returns { ahead, behind, fetched }.
-  if (offline) return { fetched: false };
-  try { await git.fetch(repo); }
-  catch (_) { return { fetched: false }; }
-  try {
-    const out = await git.git.raw(['rev-list', '--left-right', '--count', 'HEAD...FETCH_HEAD']);
-    const [ahead, behind] = out.trim().split('\t').map(Number);
-    return { ahead, behind, fetched: true };
-  } catch (_) { return { fetched: false }; }
+  // SSOT (v3.25.0+): version-compare authority + diagnostic counts.
+  // The legacy { ahead, behind, fetched } shape is preserved for downstream
+  // callers that read it; the new authoritative fields are `isAligned`,
+  // `installedVersion`, `remoteVersion`.
+  if (offline) return { fetched: false, isAligned: false, installedVersion: 'unknown', remoteVersion: 'unknown', aheadScoped: 0 };
+  const status = await git.getUpdateStatus(repo);
+  return {
+    fetched: status.fetched,
+    ahead: status.commitCount.ahead,
+    behind: status.commitCount.behind,
+    isAligned: status.isAligned,
+    installedVersion: status.installedVersion,
+    remoteVersion: status.remoteVersion,
+    aheadScoped: status.aheadScoped,
+    hasFetchHead: status.hasFetchHead,
+  };
 }
 
 async function localFrameworkChanges(git) {
@@ -137,11 +144,12 @@ async function localFrameworkChanges(git) {
   } catch (_) { return 0; }
 }
 
-async function commitsAheadOfRemote(git) {
-  try {
-    const out = await git.git.raw(['rev-list', '--count', 'FETCH_HEAD..HEAD', '--', FRAMEWORK_DIR]);
-    return Number(out.trim()) || 0;
-  } catch (_) { return 0; }
+async function commitsAheadOfRemote(git, remote) {
+  // Pre-v3.25.0 this re-ran the git query; now we read from the SSOT
+  // result populated by describeRemote(). Kept as a helper for readability
+  // in detectState().
+  if (remote && typeof remote.aheadScoped === 'number') return remote.aheadScoped;
+  return 0;
 }
 
 async function detectState(cwd, opts = {}) {
@@ -206,7 +214,7 @@ async function detectState(cwd, opts = {}) {
     }
 
     state.remote = await describeRemote(git, ledger.framework_repo || REPO_DEFAULT, !!opts.offline);
-    state.commitsAhead = await commitsAheadOfRemote(git);
+    state.commitsAhead = await commitsAheadOfRemote(git, state.remote);
     state.workingTreeDirty = await localFrameworkChanges(git);
 
     state.overlays = countOverlays(cwd);
@@ -577,14 +585,24 @@ function planActions(state) {
     });
   }
 
-  const remoteAhead = state.remote.fetched && state.remote.behind > 0;
-  const hasLocalWork = state.workingTreeDirty > 0 || state.commitsAhead > 0;
+  // v3.25.0+: drift detection is authoritative via VERSION compare (isAligned).
+  // The HEAD...FETCH_HEAD commit count is subtree-merge noise and never reaches
+  // 0, so we MUST NOT use it as the "needs update" signal.
+  const remoteAhead = state.remote.fetched && state.remote.isAligned === false;
+  // Local work detection: working-tree dirty is real; commitsAhead (aheadScoped)
+  // includes subtree-merge noise — only count it when NOT aligned (i.e. there's
+  // a real divergence to investigate). C2 adds classifier to filter noise.
+  const hasLocalWork = state.workingTreeDirty > 0 ||
+    (state.commitsAhead > 0 && state.remote.fetched && state.remote.isAligned === false);
 
   if (remoteAhead) {
+    const fromTo = (state.remote.installedVersion && state.remote.remoteVersion)
+      ? `v${state.remote.installedVersion} → v${state.remote.remoteVersion}`
+      : 'update available';
     actions.push({
       key: 'update',
-      label: `Pull ${state.remote.behind} commit(s) from upstream`,
-      why: 'Remote framework is ahead of your local copy. Updating first keeps your contributions on a fresh base.',
+      label: `Update framework (${fromTo})`,
+      why: 'Remote framework version differs from local. Updating first keeps your contributions on a fresh base.',
       autoOk: true, // update has its own internal "Proceed?" prompt + pre-flight stash
       run: () => require('./update')(),
     });
@@ -596,7 +614,7 @@ function planActions(state) {
       label: 'Push local framework improvements upstream',
       why: state.workingTreeDirty
         ? `${state.workingTreeDirty} uncommitted file(s) in .framework/ — commit them through \`baldart push\`.`
-        : `${state.commitsAhead} commit(s) on .framework/ not yet pushed.`,
+        : `${state.commitsAhead} commit(s) on .framework/ not yet pushed (may include subtree-merge noise; \`baldart push\` will classify).`,
       autoOk: false, // push writes to remote and asks for version classification — keep explicit intent
       run: () => require('./push')(),
     });
@@ -685,25 +703,39 @@ function renderDiagnostic(state) {
   }
 
   if (state.remote.fetched) {
-    const behind = state.remote.behind || 0;
-    console.log(statusLine(
-      'Remote',
-      behind > 0 ? `${behind} commit(s) ahead — update available` : 'up to date',
-      behind > 0 ? 'warn' : 'ok'
-    ));
+    // v3.25.0+: messaging based on isAligned (version-compare), not on
+    // commit count which is structurally noisy on subtree pulls.
+    if (state.remote.isAligned) {
+      console.log(statusLine(
+        'Remote',
+        `v${state.remote.remoteVersion} (aligned)`,
+        'ok'
+      ));
+    } else if (state.remote.remoteVersion && state.remote.remoteVersion !== 'unknown') {
+      console.log(statusLine(
+        'Remote',
+        `v${state.remote.remoteVersion} — update available (installed v${state.remote.installedVersion})`,
+        'warn'
+      ));
+    } else {
+      console.log(statusLine('Remote', 'upstream VERSION unreadable', 'warn'));
+    }
   } else {
     console.log(statusLine('Remote', 'offline / not fetched', 'warn'));
   }
 
-  console.log(statusLine(
-    'Local changes',
-    state.workingTreeDirty > 0
-      ? `${state.workingTreeDirty} file(s) in .framework/`
-      : state.commitsAhead > 0
-        ? `${state.commitsAhead} unpushed commit(s)`
-        : 'clean',
-    (state.workingTreeDirty + state.commitsAhead) > 0 ? 'warn' : 'ok'
-  ));
+  // Local changes: working-tree dirty is real signal. Commit count is shown
+  // ONLY if not aligned (otherwise it's subtree-merge noise — see Fix 2 for
+  // the classifier that further filters this).
+  const showCommitsAhead = state.commitsAhead > 0 &&
+    state.remote.fetched && state.remote.isAligned === false;
+  const localStatusText = state.workingTreeDirty > 0
+    ? `${state.workingTreeDirty} file(s) in .framework/`
+    : showCommitsAhead
+      ? `${state.commitsAhead} unpushed commit(s)`
+      : 'clean';
+  const localSeverity = (state.workingTreeDirty > 0 || showCommitsAhead) ? 'warn' : 'ok';
+  console.log(statusLine('Local changes', localStatusText, localSeverity));
 
   console.log(statusLine(
     'Overlays',