baldart 3.25.0 → 3.26.0

package/src/commands/update.js

@@ -3,6 +3,7 @@ const SymlinkUtils = require('../utils/symlinks');
 const UI = require('../utils/ui');
 const State = require('../utils/state');
 const Hooks = require('../utils/hooks');
+const UpdateNotifier = require('../utils/update-notifier');
 
 function readEnabledTools(cwd = process.cwd()) {
   try {
@@ -108,6 +109,239 @@ async function postUpdateAutoCommit(git, newVersion, options) {
   }
 }
 
+// --reset nuclear option (v3.26.0+).
+//
+// When the standard update keeps failing due to subtree divergence the user
+// doesn't want to investigate, --reset wipes .framework/ and reinstalls
+// cleanly. The user keeps every customization that lives OUTSIDE .framework/:
+//
+//   - baldart.config.yml          (real file, root of consumer)
+//   - .baldart/                   (whole dir: overlays/, state.json, ...)
+//   - .claude/settings.json
+//   - .claude/{agents,skills,commands}/<*.md>  ONLY if NOT a symlink into
+//                                              .framework/ (those are
+//                                              regenerated by `add`)
+//
+// Safety:
+//   - Refuses if the working tree is dirty (commit/stash first).
+//   - Refuses --yes unless --i-know is ALSO passed: --reset rm -rf's
+//     untracked & .gitignored files inside .framework/ that the user
+//     might not realize exist.
+//   - Always creates a backup tag before deleting anything.
+async function runReset(git, options, autoYes) {
+  const fs = require('fs');
+  const path = require('path');
+  const { spawnSync } = require('child_process');
+
+  UI.newline();
+  UI.header('BALDART RESET (NUCLEAR OPTION)');
+  UI.warning('This will rm -rf .framework/ and reinstall from upstream.');
+  UI.info('What is preserved (NEVER touched):');
+  UI.list([
+    'baldart.config.yml',
+    '.baldart/ (overlays, state.json, skill-conflicts.json, …)',
+    '.claude/settings.json',
+    '.claude/{agents,skills,commands}/*.md authored by you (non-framework symlinks)',
+  ], 'cyan');
+
+  // Safety gate #1: working tree MUST be clean.
+  const clean = await git.hasCleanWorkingTree();
+  if (!clean) {
+    UI.error('Working tree is dirty. Commit or `git stash -u` first, then re-run.');
+    UI.info('Reset cannot run with pending changes — too easy to lose work.');
+    process.exit(1);
+  }
+
+  // Safety gate #2: any untracked / ignored files inside .framework/?
+  let untrackedInsideFramework = '';
+  try {
+    untrackedInsideFramework = await git.git.raw([
+      'ls-files', '--others', '--ignored', '--exclude-standard', '--', '.framework/'
+    ]).catch(() => '');
+    // Some git versions return non-zero when --ignored has no matches; treat as empty.
+    if (typeof untrackedInsideFramework !== 'string') untrackedInsideFramework = '';
+  } catch (_) { untrackedInsideFramework = ''; }
+  const ignoredLines = untrackedInsideFramework.split('\n').filter((l) => l.trim());
+
+  if (ignoredLines.length) {
+    UI.newline();
+    UI.warning(`${ignoredLines.length} untracked / ignored file(s) inside .framework/ will be DELETED:`);
+    UI.list(ignoredLines.slice(0, 10), 'yellow');
+    if (ignoredLines.length > 10) UI.info(`…and ${ignoredLines.length - 10} more.`);
+    if (autoYes && options.iKnow !== true) {
+      UI.error('--reset --yes refuses to delete untracked/ignored files without --i-know.');
+      UI.info('Run: npx baldart update --reset --yes --i-know');
+      process.exit(1);
+    }
+    if (!autoYes) {
+      const ok = await UI.confirm('Proceed and DELETE these files permanently?', false);
+      if (!ok) { UI.info('Reset aborted.'); process.exit(0); }
+    }
+  }
+
+  // Safety gate #3: backup tag before doing anything destructive.
+  const backupTag = await git.createBackupTag();
+  UI.success(`Backup tag created: ${backupTag}`);
+
+  // Snapshot user-owned files OUTSIDE .framework/ for restore-after-add.
+  // All these live OUTSIDE .framework/ so `rm -rf .framework/` doesn't touch
+  // them — but we record what was present so a post-install sanity check can
+  // confirm nothing got clobbered by the fresh install flow.
+  const preserved = {
+    baldartConfig: fs.existsSync('baldart.config.yml'),
+    baldartDir: fs.existsSync('.baldart'),
+    claudeSettings: fs.existsSync(path.join('.claude', 'settings.json')),
+    customAgents: snapshotCustomEntries('.claude/agents'),
+    customSkills: snapshotCustomEntries('.claude/skills'),
+    customCommands: snapshotCustomEntries('.claude/commands'),
+  };
+  UI.info(`Preserved snapshot: config=${preserved.baldartConfig}, .baldart=${preserved.baldartDir}, settings.json=${preserved.claudeSettings}, custom files: ${preserved.customAgents.length + preserved.customSkills.length + preserved.customCommands.length}`);
+
+  // Wipe .framework/. The `git rm` first ensures git's index reflects the
+  // deletion (otherwise a stray subtree commit might recreate refs); then
+  // rm -rf removes any untracked leftovers.
+  UI.newline();
+  UI.info('Removing .framework/…');
+  try {
+    spawnSync('git', ['rm', '-rf', '--ignore-unmatch', '.framework'], { stdio: 'pipe' });
+  } catch (_) { /* fall through to rm -rf */ }
+  try {
+    fs.rmSync('.framework', { recursive: true, force: true });
+  } catch (err) {
+    UI.error(`Could not remove .framework/: ${err.message}`);
+    UI.info(`Rollback with: git reset --hard ${backupTag}`);
+    process.exit(1);
+  }
+  UI.success('.framework/ removed.');
+
+  // Commit the deletion so `subtree add` has a clean tree to land on.
+  try {
+    await git.git.add(['-A']);
+    const idx = await git.git.status();
+    if (idx.staged.length || idx.modified.length || idx.deleted.length) {
+      await git.git.commit(`chore(baldart): reset .framework/ (pre-reinstall, backup ${backupTag})`);
+      UI.success('Committed reset.');
+    }
+  } catch (err) {
+    UI.warning(`Could not commit reset (${err.message}). Continuing — subtree add may still succeed.`);
+  }
+
+  // Hand off to `add` for the fresh install. `add` will:
+  //   - `git subtree add --squash` → fresh subtree, no divergence history.
+  //   - Reconcile symlinks (custom files preserved by existing collision logic).
+  //   - Run configure if missing baldart.config.yml (we preserved it, so skip).
+  //   - Register hooks (will see existing settings.json, idempotent).
+  UI.newline();
+  UI.info('Re-installing framework via `baldart add`…');
+  const addCmd = require('./add');
+  await addCmd({ yes: true });
+
+  // Post-restore sanity check — confirm nothing user-owned got clobbered.
+  const stillPresent = {
+    baldartConfig: fs.existsSync('baldart.config.yml'),
+    baldartDir: fs.existsSync('.baldart'),
+    claudeSettings: fs.existsSync(path.join('.claude', 'settings.json')),
+  };
+  const lost = Object.entries(stillPresent).filter(([k, v]) => preserved[k] && !v).map(([k]) => k);
+  if (lost.length) {
+    UI.error(`Reset DROPPED user-owned files: ${lost.join(', ')}.`);
+    UI.info(`Rollback IMMEDIATELY: git reset --hard ${backupTag}`);
+    process.exit(1);
+  }
+
+  UI.header('✓ RESET COMPLETE');
+  UI.box('RESET RESULT', [
+    `Framework: fresh install (${await git.getFrameworkVersion()})`,
+    `Backup tag: ${backupTag}`,
+    `Rollback if needed: git reset --hard ${backupTag}`,
+    '',
+    'All user-owned files preserved.',
+  ]);
+  process.exit(0);
+}
+
+function snapshotCustomEntries(dir) {
+  const fs = require('fs');
+  const path = require('path');
+  if (!fs.existsSync(dir)) return [];
+  try {
+    return fs.readdirSync(dir)
+      .filter((name) => {
+        // Symlinks pointing into .framework/ are framework-owned (will be
+        // recreated by `add`). Real files / dirs are user-authored.
+        try {
+          const lst = fs.lstatSync(path.join(dir, name));
+          if (!lst.isSymbolicLink()) return true;
+          const target = fs.readlinkSync(path.join(dir, name));
+          return !target.includes('.framework/');
+        } catch (_) { return false; }
+      });
+  } catch (_) { return []; }
+}
+
+// CLI self-upgrade auto-relaunch (v3.25.0+).
+// When the globally-installed `baldart` CLI is older than the latest on npm,
+// transparently re-invoke `npx baldart@latest update <flags>` so the user
+// gets the fix without having to remember `npm i -g baldart@latest`. The
+// child inherits stdio (preserves prompts), and BALDART_RELAUNCHED=1 in env
+// is a loop guard: if npm cache somehow serves an older version, the child
+// sees the flag and skips its own relaunch check.
+async function maybeRelaunchUnderLatest(options) {
+  if (process.env.BALDART_RELAUNCHED === '1') return false;
+  if (process.env.BALDART_NO_RELAUNCH === '1') return false;
+
+  const cliVersion = require('../../package.json').version;
+  let info = UpdateNotifier.hint({ currentVersion: cliVersion });
+  if (!info) {
+    // No cached hint — force a refresh so a brand-new `baldart update`
+    // invocation can still benefit. Best-effort, network-bounded.
+    try {
+      await UpdateNotifier.refresh({ currentVersion: cliVersion, timeoutMs: 3000, force: true });
+      info = UpdateNotifier.hint({ currentVersion: cliVersion });
+    } catch (_) { /* offline / blocked — fall through */ }
+  }
+  if (!info) return false;
+
+  const autoYes = options.yes === true;
+  let proceed = autoYes;
+  if (!autoYes) {
+    UI.newline();
+    UI.warning(`The installed CLI is older than npm latest: v${cliVersion} → v${info.latest}.`);
+    const choice = await UI.select('How would you like to proceed?', [
+      { name: `Auto-relaunch via npx baldart@${info.latest} (recommended)`, value: 'relaunch' },
+      { name: 'Proceed with the current CLI (you may hit fixed bugs)', value: 'current' },
+      { name: 'Abort and upgrade manually (`npm i -g baldart@latest`)', value: 'abort' },
+    ]);
+    if (choice === 'abort') {
+      UI.info(`Run: npm i -g baldart@latest && npx baldart update${options.yes ? ' --yes' : ''}`);
+      process.exit(0);
+    }
+    proceed = (choice === 'relaunch');
+  }
+  if (!proceed) return false;
+
+  // Reconstruct the original argv flags for the child.
+  const flags = [];
+  if (options.yes === true) flags.push('--yes');
+  if (options.autoStash === true && options.yes !== true) flags.push('--auto-stash');
+  if (options.commit === false) flags.push('--no-commit');
+  if (options.reset === true) flags.push('--reset');
+  if (options.iKnow === true) flags.push('--i-know');
+
+  const spawn = require('child_process').spawnSync;
+  UI.info(`Auto-relaunching via npx baldart@${info.latest}…`);
+  const res = spawn('npx', ['-y', `baldart@${info.latest}`, 'update', ...flags], {
+    stdio: 'inherit',
+    env: { ...process.env, BALDART_RELAUNCHED: '1' },
+    timeout: 600000, // mirror the longest legitimate flow downstream
+  });
+  if (res.error || res.status === null) {
+    UI.warning(`Auto-relaunch failed (${res.error ? res.error.message : 'no exit'}). Falling back to current CLI.`);
+    return false;
+  }
+  process.exit(res.status || 0);
+}
+
 async function update(options = {}) {
   const git = new GitUtils();
   const symlinks = new SymlinkUtils();
@@ -137,6 +371,21 @@ async function update(options = {}) {
       process.exit(1);
     }
 
+    // v3.26.0+ NUCLEAR OPTION: --reset rips out .framework/ and reinstalls
+    // fresh, preserving everything user-owned that lives OUTSIDE .framework/.
+    // Branches the flow entirely — never proceeds to the standard subtree
+    // pull path.
+    if (options.reset === true) {
+      await runReset(git, options, autoYes);
+      return; // runReset exits the process on success
+    }
+
+    // v3.25.0+: CLI self-upgrade — if a newer baldart is on npm, transparently
+    // relaunch under `npx baldart@latest` so the user always runs the fixed
+    // code path. Loop guard via BALDART_RELAUNCHED env. No-op when already on
+    // latest or when the user opts out / network is down.
+    await maybeRelaunchUnderLatest(options);
+
     const currentVersion = await git.getFrameworkVersion();
     UI.success(`Current version: ${currentVersion}`);
 
@@ -168,8 +417,12 @@ async function update(options = {}) {
 
     const spinner = UI.spinner('Connecting to repository...').start();
 
+    // SSOT (v3.25.0+): one query gives version compare + commit counts +
+    // divergence class. Replaces hasChangesToPush() (which checked the wrong
+    // remote AND wrong direction — see git.js history for context).
+    let status;
     try {
-      await git.fetch(repo);
+      status = await git.getUpdateStatus(repo);
       spinner.succeed('Connected to repository');
     } catch (error) {
       spinner.fail();
@@ -187,16 +440,74 @@ async function update(options = {}) {
       process.exit(1);
     }
 
-    // Compare versions (simplified - in real scenario would fetch VERSION from remote)
-    UI.info('Checking for updates...');
+    if (!status.fetched || !status.hasFetchHead) {
+      UI.error('Could not fetch upstream — try again with network access.');
+      process.exit(1);
+    }
 
-    const hasChanges = await git.hasChangesToPush();
-    if (!hasChanges) {
-      UI.success('Already up to date!');
+    // VERSION-compare authority. Subtree-merge commit count is noise; never
+    // use behind > 0 as the up-to-date signal (root cause of v3.24.x bug).
+    if (status.isAligned) {
+      UI.success(`Already up to date! (v${status.installedVersion})`);
       process.exit(0);
     }
 
-    UI.warning('Updates available!');
+    UI.warning(`Update available: v${status.installedVersion} → v${status.remoteVersion}`);
+
+    // Divergence handling: when consumer has commits on .framework/ that
+    // aren't upstream, classify before deciding. all-noise = subtree
+    // plumbing autogenerated → auto-resolve. overlay-able = user-customised
+    // a framework file → suggest /overlay. real-custom = prompt 3-way.
+    if (status.hasDivergence) {
+      UI.newline();
+      if (status.divergenceClass === 'all-noise') {
+        UI.info(`Detected ${status.divergenceCommits.length} subtree-merge / chore commit(s) (git plumbing noise — no real content drift). Auto-resolving…`);
+      } else if (status.divergenceClass === 'overlay-able') {
+        UI.warning('Detected custom edits to framework files inside `.framework/.claude/{agents,skills,commands}/`.');
+        UI.info('These are better expressed as overlays under `.baldart/overlays/` — they survive updates without divergence.');
+        for (const c of status.divergenceCommits.filter((c) => c.category === 'custom-overlay-able')) {
+          UI.info(`  • ${c.sha.slice(0, 7)} — ${c.subject}`);
+        }
+        if (autoYes) {
+          UI.error('Refusing to overwrite custom edits in --yes mode. Re-run without --yes to choose.');
+          UI.info('Recommended: use the `/overlay` skill to migrate these edits, then re-run update.');
+          process.exit(1);
+        }
+        const choice = await UI.select('How would you like to proceed?', [
+          { name: 'Migrate to overlay and pull anyway (recommended — overlay wins)', value: 'overlay' },
+          { name: 'Keep the custom commits (subtree pull may conflict)', value: 'keep' },
+          { name: 'Abort', value: 'abort' },
+        ]);
+        if (choice === 'abort') { UI.info('Update cancelled.'); process.exit(0); }
+        if (choice === 'overlay') {
+          UI.info('Run `/overlay` from Claude Code to migrate the custom edits, then re-run `npx baldart update`.');
+          process.exit(0);
+        }
+        // 'keep' → fall through, subtree pull will attempt merge
+      } else if (status.divergenceClass === 'real-custom' || status.divergenceClass === 'mixed') {
+        UI.warning(`Detected ${status.divergenceCommits.filter((c) => c.category === 'custom-other').length} custom commit(s) on .framework/ that are NOT auto-classifiable as overlays.`);
+        for (const c of status.divergenceCommits.filter((c) => !['subtree-merge', 'subtree-squash', 'chore-wrapper'].includes(c.category))) {
+          UI.info(`  • ${c.sha.slice(0, 7)} [${c.category}] — ${c.subject}`);
+        }
+        if (autoYes) {
+          UI.error('Refusing to pull over custom commits in --yes mode. Re-run without --yes to choose.');
+          process.exit(1);
+        }
+        const choice = await UI.select('How would you like to proceed?', [
+          { name: 'Push these commits upstream first (recommended — `/baldart-push`)', value: 'push' },
+          { name: 'Pull anyway (will create a merge commit — possible conflicts)', value: 'pull' },
+          { name: 'Abort', value: 'abort' },
+        ]);
+        if (choice === 'abort') { UI.info('Update cancelled.'); process.exit(0); }
+        if (choice === 'push') {
+          UI.info('Run `/baldart-push` from Claude Code (or `npx baldart push`) to contribute upstream, then re-run update.');
+          process.exit(0);
+        }
+        // 'pull' → fall through
+      }
+      // 'unknown' → conservative: continue silently, the subtree pull will
+      // surface any real conflict.
+    }
 
     // Step 3: Show changes preview
     UI.header('STEP 3/5: Preview Changes');
@@ -412,13 +723,23 @@ async function update(options = {}) {
       if (res.malformed) {
         UI.warning('.claude/settings.json is malformed; skipped hook registration. Run `npx baldart doctor` after fixing it.');
       } else {
-        for (const r of res.results) {
-          if (r.status === 'created') UI.success(`Registered hook \`${r.id}\` in .claude/settings.json (v3.18.0+ default).`);
-          else if (r.status === 'legacy-migrated') UI.success(`Migrated legacy hook to \`${r.id}\` (previous: ${r.previousCommand})`);
-          else if (r.status === 'drift-replaced') UI.success(`Replaced drifted hook \`${r.id}\` (was: ${r.previousCommand})`);
-          else if (r.status === 'drift-kept') UI.info(`Kept user-customized hook \`${r.id}\` as-is.`);
-          // 'already' is silent on update to avoid noise
+        // Aggregate output for missing-backfill (the common case after a major
+        // bump) to keep the noise floor low. Drift events stay per-line since
+        // they represent user-visible decisions.
+        const created = res.results.filter((r) => r.status === 'created').map((r) => r.id);
+        const legacy = res.results.filter((r) => r.status === 'legacy-migrated');
+        const drifts = res.results.filter((r) => r.status === 'drift-replaced' || r.status === 'drift-kept');
+        if (created.length === 1) {
+          UI.success(`Registered hook \`${created[0]}\` in .claude/settings.json.`);
+        } else if (created.length > 1) {
+          UI.success(`Auto-registered ${created.length} missing hook(s): ${created.join(', ')}.`);
+        }
+        for (const r of legacy) UI.success(`Migrated legacy hook to \`${r.id}\` (previous: ${r.previousCommand})`);
+        for (const r of drifts) {
+          if (r.status === 'drift-replaced') UI.success(`Replaced drifted hook \`${r.id}\` (was: ${r.previousCommand})`);
+          else UI.info(`Kept user-customized hook \`${r.id}\` as-is.`);
         }
+        // 'already' is silent on update to avoid noise
       }
     } catch (err) {
       UI.warning(`Hook registration skipped: ${err.message}`);

package/src/commands/version.js

@@ -11,28 +11,23 @@ function fmtDate(iso) {
   try { return iso.slice(0, 10); } catch (_) { return iso; }
 }
 
-async function describeDrift(git) {
-  // Returns { ahead, behind, uncommittedFiles, hasFetchHead } or null on failure.
+async function describeDrift(git, status) {
+  // Uncommitted local edits to .framework/ (working tree, NOT commits)
+  let uncommittedFiles = 0;
   try {
-    let hasFetchHead = false;
-    try {
-      const out = await git.git.raw(['rev-list', '--left-right', '--count', 'HEAD...FETCH_HEAD']);
-      const [a, b] = out.trim().split('\t').map(Number);
-      hasFetchHead = !Number.isNaN(a) && !Number.isNaN(b);
-      var ahead = a, behind = b;
-    } catch (_) { /* no FETCH_HEAD — needs fetch first */ }
+    const dirty = await git.git.raw(['diff', '--name-only', 'HEAD', '--', FRAMEWORK_DIR]);
+    uncommittedFiles = dirty.trim() ? dirty.trim().split('\n').length : 0;
+  } catch (_) { /* repo without HEAD yet */ }
 
-    // Uncommitted local edits to .framework/
-    let uncommittedFiles = 0;
-    try {
-      const dirty = await git.git.raw(['diff', '--name-only', 'HEAD', '--', FRAMEWORK_DIR]);
-      uncommittedFiles = dirty.trim() ? dirty.trim().split('\n').length : 0;
-    } catch (_) { /* repo without HEAD yet */ }
-
-    return { ahead, behind, uncommittedFiles, hasFetchHead };
-  } catch (_) {
-    return null;
-  }
+  return {
+    isAligned: status.isAligned,
+    installedVersion: status.installedVersion,
+    remoteVersion: status.remoteVersion,
+    behind: status.commitCount.behind,
+    ahead: status.commitCount.ahead,
+    uncommittedFiles,
+    hasFetchHead: status.hasFetchHead,
+  };
 }
 
 async function version(opts = {}) {
@@ -50,29 +45,42 @@ async function version(opts = {}) {
     const state = State.load();
     const cliVersion = require('../../package.json').version;
     const cliUpdate = UpdateNotifier.hint({ currentVersion: cliVersion });
+    const verbose = opts.verbose === true;
 
-    // Optionally fetch upstream to compute drift (default: yes).
-    const offline = opts.offline === true;
-    if (!offline) {
-      try {
-        await git.fetch(state.framework_repo || REPO_DEFAULT);
-      } catch (_) { /* offline — drift report falls back */ }
+    // SSOT (v3.25.0+): one query, version-compare authority.
+    const repo = state.framework_repo || REPO_DEFAULT;
+    let status;
+    if (opts.offline === true) {
+      status = {
+        installedVersion: frameworkVersion,
+        remoteVersion: 'unknown',
+        isAligned: false,
+        commitCount: { behind: 0, ahead: 0, note: '' },
+        aheadScoped: 0, hasDivergence: false, hasFetchHead: false, fetched: false,
+      };
+    } else {
+      status = await git.getUpdateStatus(repo);
     }
-    const drift = await describeDrift(git);
+    const drift = await describeDrift(git, status);
 
-    UI.newline();
-    UI.box('BALDART VERSION', [
+    // Messaging based on `isAligned` (not commit count, which is subtree noise).
+    let remoteLine;
+    if (!drift.hasFetchHead) {
+      remoteLine = 'Remote:      (offline / not fetched)';
+    } else if (drift.isAligned) {
+      remoteLine = `Remote:      v${drift.remoteVersion} (aligned)`;
+    } else if (drift.remoteVersion !== 'unknown') {
+      remoteLine = `Remote:      v${drift.remoteVersion} (installed v${drift.installedVersion} — \`npx baldart update\`)`;
+    } else {
+      remoteLine = 'Remote:      (upstream VERSION unreadable)';
+    }
+
+    const lines = [
       `Installed:   v${frameworkVersion}    ${state.install_date ? `(since ${fmtDate(state.install_date)})` : ''}`.trim(),
-      drift && drift.hasFetchHead
-        ? (drift.behind > 0
-            ? `Remote:      ${drift.behind} commit(s) ahead — pull with \`npx baldart update\``
-            : 'Remote:      up to date')
-        : 'Remote:      (offline / not fetched)',
-      drift
-        ? (drift.uncommittedFiles > 0
-            ? `Local:       v${frameworkVersion} + ${drift.uncommittedFiles} uncommitted file(s) in .framework/`
-            : `Local:       v${frameworkVersion} (clean)`)
-        : '',
+      remoteLine,
+      drift.uncommittedFiles > 0
+        ? `Local:       v${frameworkVersion} + ${drift.uncommittedFiles} uncommitted file(s) in .framework/`
+        : `Local:       v${frameworkVersion} (clean)`,
       '',
       `Last update: ${fmtDate(state.last_update_date)}`,
       `Last push:   v${state.last_pushed_version || '—'}    ${state.last_push_date ? `(${fmtDate(state.last_push_date)})` : ''}`.trim(),
@@ -80,8 +88,19 @@ async function version(opts = {}) {
       cliUpdate
         ? `CLI:         v${cliVersion} → v${cliUpdate.latest} available (npm i -g baldart@latest)`
         : `CLI:         v${cliVersion}`,
-      `Repository:  https://github.com/${state.framework_repo || REPO_DEFAULT}`,
-    ].filter((l) => l !== ''));
+      `Repository:  https://github.com/${repo}`,
+    ];
+
+    if (verbose && drift.hasFetchHead) {
+      lines.push('');
+      lines.push('Diagnostics (subtree commit history — includes auto-generated merges):');
+      lines.push(`  commits ahead:  ${drift.ahead}`);
+      lines.push(`  commits behind: ${drift.behind}`);
+      lines.push('  (these counts grow with every `git subtree pull --squash`; ignore unless investigating)');
+    }
+
+    UI.newline();
+    UI.box('BALDART VERSION', lines.filter((l) => l !== ''));
     UI.newline();
   } catch (error) {
     UI.error(`Failed to get version: ${error.message}`);

package/src/utils/__tests__/classify-divergence.test.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * Fixture-driven test for classifyDivergence pattern matching.
+ *
+ * Run: node src/utils/__tests__/classify-divergence.test.js
+ * Exits 0 on success, 1 on any mismatch (CI-friendly).
+ *
+ * Fixtures cover the exact commit subjects observed during the
+ * `mayo` consumer debug (v3.25.0 release). Adversarial-review enforced.
+ */
+const GitUtils = require('../git');
+const g = new GitUtils();
+
+const SUBJECT_FIXTURES = [
+  // ─── subtree-merge (branch-agnostic) ─────────────────────────────────
+  { subject: "Merge commit 'abc123' into develop", expected: 'subtree-merge' },
+  { subject: "Merge commit 'abc123' into main", expected: 'subtree-merge' },
+  { subject: "Merge commit 'deadbeef' into feature/x", expected: 'subtree-merge' },
+  { subject: "Merge branch 'feature-x' into main", expected: 'subtree-merge' },
+
+  // ─── subtree-squash ──────────────────────────────────────────────────
+  { subject: "Squashed '.framework/' changes from abc..def", expected: 'subtree-squash' },
+  { subject: "Squashed '.framework/' content from 1234..5678", expected: 'subtree-squash' },
+
+  // ─── chore-wrapper (real commits from mayo) ──────────────────────────
+  { subject: '[CHORE] reconcile baldart state ledger v3.22.1 -> v3.25.0', expected: 'chore-wrapper' },
+  { subject: '[CHORE] register baldart agent-discovery hooks', expected: 'chore-wrapper' },
+  { subject: 'chore(baldart): post-update reconcile to v3.25.0', expected: 'chore-wrapper' },
+  { subject: 'chore: bump baldart version', expected: 'chore-wrapper' },
+  { subject: '[CHORE] baldart update → v3.12.0', expected: 'chore-wrapper' },
+
+  // ─── non-matches (should return null → fall through to path classifier) ──
+  { subject: 'feat: add new login screen', expected: null },
+  { subject: 'fix: ui-expert agent for mayo design system', expected: null },
+  { subject: 'docs: update README', expected: null },
+
+  // ─── adversarial false-positive guards ───────────────────────────────
+  // "Merge pull request" is NOT a subtree merge — must NOT match
+  { subject: 'Merge pull request #42 from feature/x', expected: null },
+  // "Squashed" without `.framework/` path — NOT subtree-squash
+  { subject: "Squashed 'docs/' content from abc..def", expected: null },
+  // Chore without 'baldart' keyword — NOT chore-wrapper
+  { subject: 'chore: update dependencies', expected: null },
+];
+
+const PATH_FIXTURES = [
+  {
+    name: 'all touched in .framework/.claude/agents → overlay-able',
+    touched: ['.framework/framework/.claude/agents/ui-expert.md'],
+    expected: 'custom-overlay-able',
+  },
+  {
+    name: 'all touched in .framework/.claude/skills → overlay-able',
+    touched: [
+      '.framework/framework/.claude/skills/ui-design/SKILL.md',
+      '.framework/framework/.claude/skills/ui-design/scripts/foo.sh',
+    ],
+    expected: 'custom-overlay-able',
+  },
+  {
+    name: 'mixed agents + skills → still overlay-able',
+    touched: [
+      '.framework/framework/.claude/agents/ui-expert.md',
+      '.framework/framework/.claude/commands/check.md',
+    ],
+    expected: 'custom-overlay-able',
+  },
+  {
+    name: 'touches .framework/src → custom-other',
+    touched: ['.framework/src/utils/git.js'],
+    expected: 'custom-other',
+  },
+  {
+    name: 'mix overlay-able + src → custom-other',
+    touched: [
+      '.framework/framework/.claude/agents/ui-expert.md',
+      '.framework/src/utils/git.js',
+    ],
+    expected: 'custom-other',
+  },
+  {
+    name: 'empty paths → custom-other (conservative default)',
+    touched: [],
+    expected: 'custom-other',
+  },
+  {
+    name: 'touches CHANGELOG → custom-other',
+    touched: ['.framework/CHANGELOG.md'],
+    expected: 'custom-other',
+  },
+];
+
+let pass = 0, fail = 0;
+
+console.log('─── Subject classifier ───');
+for (const f of SUBJECT_FIXTURES) {
+  const actual = g.classifyCommitSubject(f.subject);
+  if (actual === f.expected) {
+    pass++;
+    console.log(`  ✓ "${f.subject}" → ${actual}`);
+  } else {
+    fail++;
+    console.log(`  ✗ "${f.subject}" → ${actual} (expected ${f.expected})`);
+  }
+}
+
+console.log('\n─── Path classifier ───');
+for (const f of PATH_FIXTURES) {
+  const actual = g.classifyCommitByPaths(f.touched);
+  if (actual === f.expected) {
+    pass++;
+    console.log(`  ✓ ${f.name} → ${actual}`);
+  } else {
+    fail++;
+    console.log(`  ✗ ${f.name} → ${actual} (expected ${f.expected})`);
+  }
+}
+
+console.log(`\nResult: ${pass} pass, ${fail} fail`);
+process.exit(fail > 0 ? 1 : 0);