baldart 3.28.3 → 3.29.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.29.0] - 2026-05-29
+
+Closes a two-part process gap in `npx baldart update` reported from a non-TTY agent context on a shared consumer repo: (1) plumbing/collaboration merge commits were mislabeled `custom-other`, downgrading an otherwise overlay-able divergence set into `mixed`; (2) an automated agent had **no** non-destructive path to complete an update when the consumer carried local `.framework/` commits — `--yes` refused, the interactive prompt needed a TTY, and `--reset` is gated on a clean working tree. **No new `baldart.config.yml` keys** — `--on-divergence` is a CLI flag, not a config flag, so the schema-propagation rule does not apply.
+
+### Fixed — divergence classifier no longer poisoned by merge commits
+
+- **[src/utils/git.js](src/utils/git.js)** `classifyDivergence()`: merge commits are now detected **structurally by parent count** (`%P` in the `git log` format → `parents.length >= 2`) instead of relying solely on the brittle subject regex `^Merge … into <branch>$`. That regex missed real `git subtree pull --squash` merges that present as a bare `Merge commit '<sha>'` (git omits the `into <branch>` suffix when the merge lands on `master`) and shared-repo collaboration merges shaped like `Merge branch 'x' of <url> into <branch>` / `Merge remote-tracking branch '…'`. Such merges fell through to the path classifier, which returns `custom-other` for the empty diff-tree of a merge — collapsing an `overlay-able` set into `mixed` and hiding the overlay-migration option. Merges are now labeled `subtree-merge` (noise) and excluded before the aggregate decision.
+- **[src/utils/git.js](src/utils/git.js)**: aggregation extracted to a pure, unit-testable static `GitUtils.aggregateDivergenceClass(commits)`. Each divergence commit record now also carries `parents` and `touched` (the latter reused by the new overlay-scaffold flow below).
+- **[src/utils/__tests__/classify-divergence.test.js](src/utils/__tests__/classify-divergence.test.js)**: +9 fixtures — bare-merge / `of <url>` / remote-tracking subjects (documenting the regex blind spot now covered by parent count) and an `aggregateDivergenceClass` suite asserting `overlay-able + plumbing-merge → overlay-able` (not `mixed`).
+
+### Added — `--on-divergence` non-interactive escape hatch for agents / CI
+
+- **[src/commands/update.js](src/commands/update.js)** + **[bin/baldart.js](bin/baldart.js)**: `npx baldart update --on-divergence <strategy>` resolves a divergent update without a TTY:
+  - `scaffold-overlays` → auto-creates overlay skeleton(s) for the overlay-able framework files touched by the divergent commits (reusing `overlay.scaffoldFile`), then stops so the edits can be filled in and the update re-run. For `mixed`, scaffolds the overlay-able subset and refuses to pull while `custom-other` commits remain (would be destructive).
+  - `pull` → keeps the commits and lets the subtree pull create a merge (non-destructive; conflicts are surfaced, never auto-resolved). Works for `overlay-able`, `mixed`, and `real-custom`.
+  - `abort` → explicit no-op.
+- Bare `--yes` on a divergent class still refuses (nothing destructive by accident) but now prints the exact flag to re-run with instead of dead-ending.
+
+### Changed — interactive `overlay` choice now actually scaffolds
+
+- **[src/commands/update.js](src/commands/update.js)**: the interactive "migrate to overlay" option previously printed *"run `/overlay` then re-run"* and exited (a no-op). It now scaffolds the overlay skeleton(s) in-place via `overlay.scaffoldFile` and points the user to `/overlay` for guided filling.
+- **[src/commands/overlay.js](src/commands/overlay.js)**: extracted a non-exiting `scaffoldFile(cwd, target, options)` (returns a structured result) from the `process.exit`-driven `scaffold()` CLI wrapper, so it can be called in a loop from `update` without a single missing/existing overlay terminating the run. Exported alongside `parseTarget`.
+
+### Changed — `/baldart-update` skill narration synced
+
+- **[framework/.claude/skills/baldart-update/SKILL.md](framework/.claude/skills/baldart-update/SKILL.md)**: documents the parent-count merge detection and the new `--on-divergence` strategies; corrects the stale "real user-custom commits ABORT in --yes mode" claim.
+
 ## [3.28.3] - 2026-05-28
 
 Release B of the 3-release plan on `/new` fix-application authority. Closes two inline-apply violation patterns observed in real `/new` runs (doc fixes applied by the orchestrator instead of delegated to coder; Codex HIGH security findings written inline) and shuts the structural loophole in `SKILL.md`'s sub-agent failure protocol that was being used to bypass delegation even when no agent had crashed. Telemetry from v3.28.2 will measure the effectiveness of these changes; Release C (conditional threshold rule) waits for that data.

package/VERSION

@@ -1 +1 @@
-3.28.3
+3.29.0

package/bin/baldart.js

@@ -72,6 +72,7 @@ program
   .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).')
+  .option('--on-divergence <strategy>', 'Non-interactive resolution when the consumer has local commits on .framework/ (for agents / CI): "scaffold-overlays" (auto-create overlay skeletons, then stop), "pull" (keep commits + merge — non-destructive), or "abort".')
   .action(async (options) => {
     const updateCommand = require('../src/commands/update');
     await updateCommand(options);

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

@@ -139,7 +139,7 @@ post-flight assert:
 - **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`.
+- **Subtree-merge / chore divergence commits**: classified by the CLI (merges detected by parent count, so plumbing/collaboration merges never poison the class); auto-resolved silently when `all-noise`, prompts for `overlay-able` / `real-custom` / `mixed` — or resolve non-interactively with `--on-divergence scaffold-overlays|pull|abort`.
 - **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
@@ -272,10 +272,21 @@ Do NOT pass `--auto-stash` (redundant with `--yes`).
   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).
+  local commits that are just `git subtree pull` plumbing, ordinary
+  collaboration merges (detected by parent count, not just subject), or
+  CLI-generated `[CHORE]` commits, the CLI auto-resolves silently. Real
+  user-custom commits do NOT auto-resolve under bare `--yes` — but an agent
+  is no longer dead-ended: pass `--on-divergence` to resolve non-interactively
+  (since v3.29.0):
+  - `--on-divergence scaffold-overlays` → auto-creates overlay skeleton(s)
+    for the overlay-able commits, then stops so the edits can be filled in
+    (then re-run update). Use this when the divergence is `overlay-able`.
+  - `--on-divergence pull` → keeps the commits and lets the subtree pull
+    create a merge (non-destructive; resolve any conflicts that surface).
+    Works for `overlay-able`, `mixed`, and `real-custom`.
+  - `--on-divergence abort` → explicit no-op.
+  Bare `--yes` without a strategy still refuses (and now prints exactly which
+  flag to re-run with), so nothing destructive happens by accident.
 - **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`.

package/package.json

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

package/src/commands/overlay.js

@@ -116,60 +116,86 @@ function buildFrontmatter({ kind, name, frameworkVersion, baseSha, mode }) {
 
 // ─── scaffold ──────────────────────────────────────────────────────────────
 
-async function scaffold(target, options = {}) {
-  const cwd = process.cwd();
-  ensureConsumer(cwd);
-
+// Pure scaffolder — performs the filesystem work and returns a structured
+// result WITHOUT printing or calling process.exit. The interactive `scaffold`
+// wrapper renders the result; `update --on-divergence scaffold-overlays` calls
+// this in a loop (so one already-existing or missing overlay can't terminate
+// the whole update). Keeping the path/frontmatter logic here honours the
+// "CLI is the source of truth, never re-implement" rule.
+function scaffoldFile(cwd, target, options = {}) {
   const parsed = parseTarget(target);
-  if (!parsed) {
-    UI.error('Invalid target. Use: skill/<name>, agents/<name>, or commands/<name>.');
-    UI.info('Example: npx baldart overlay scaffold agents/coder');
-    process.exit(1);
-  }
+  if (!parsed) return { ok: false, reason: 'invalid-target', target };
   const { kind, name } = parsed;
 
   const baseAbs = baseFilePathFor(cwd, kind, name);
   if (!fs.existsSync(baseAbs)) {
-    UI.error(`Base ${kind} "${name}" not found at ${path.relative(cwd, baseAbs)}.`);
-    UI.info(`Run \`ls ${path.relative(cwd, path.dirname(baseAbs))}\` to list available ${kind}s.`);
-    process.exit(1);
+    return { ok: false, reason: 'base-missing', kind, name, baseRel: path.relative(cwd, baseAbs) };
   }
 
   const overlayAbs = overlayPathFor(cwd, kind, name);
   const overlayRel = path.relative(cwd, overlayAbs);
-
   if (fs.existsSync(overlayAbs)) {
-    UI.warning(`Overlay already exists: ${overlayRel}`);
-    UI.info('Run `npx baldart overlay drift ' + overlayRel + '` to check it, or edit it directly to extend.');
-    process.exit(0);
+    return { ok: false, reason: 'exists', kind, name, overlayRel };
   }
 
-  fs.mkdirSync(path.dirname(overlayAbs), { recursive: true });
-
-  const baseContent = fs.readFileSync(baseAbs, 'utf8');
-  const baseSha = computeBaseFileSha(baseContent);
-  const fwVersion = readFrameworkVersion(cwd);
   const mode = (options.mode || 'extend').trim();
   if (!['extend', 'override'].includes(mode)) {
-    UI.error(`Invalid --mode "${mode}". Use "extend" or "override".`);
-    process.exit(1);
+    return { ok: false, reason: 'bad-mode', mode };
   }
 
+  fs.mkdirSync(path.dirname(overlayAbs), { recursive: true });
+  const baseContent = fs.readFileSync(baseAbs, 'utf8');
+  const baseSha = computeBaseFileSha(baseContent);
+  const fwVersion = readFrameworkVersion(cwd);
   const content =
     buildFrontmatter({ kind, name, frameworkVersion: fwVersion, baseSha, mode }) +
     scaffoldBody(kind, name);
-
   fs.writeFileSync(overlayAbs, content);
-  UI.success(`Created ${overlayRel}`);
-  UI.info(`Base file: ${path.relative(cwd, baseAbs)}`);
-  UI.info(`Targets framework v${fwVersion || 'unknown'} (base_file_sha=${baseSha}).`);
+
+  return {
+    ok: true, reason: 'created', kind, name, overlayRel,
+    baseRel: path.relative(cwd, baseAbs), fwVersion, baseSha,
+  };
+}
+
+async function scaffold(target, options = {}) {
+  const cwd = process.cwd();
+  ensureConsumer(cwd);
+
+  const res = scaffoldFile(cwd, target, options);
+  if (!res.ok) {
+    if (res.reason === 'invalid-target') {
+      UI.error('Invalid target. Use: skill/<name>, agents/<name>, or commands/<name>.');
+      UI.info('Example: npx baldart overlay scaffold agents/coder');
+      process.exit(1);
+    }
+    if (res.reason === 'base-missing') {
+      UI.error(`Base ${res.kind} "${res.name}" not found at ${res.baseRel}.`);
+      UI.info(`Run \`ls ${path.dirname(res.baseRel)}\` to list available ${res.kind}s.`);
+      process.exit(1);
+    }
+    if (res.reason === 'exists') {
+      UI.warning(`Overlay already exists: ${res.overlayRel}`);
+      UI.info('Run `npx baldart overlay drift ' + res.overlayRel + '` to check it, or edit it directly to extend.');
+      process.exit(0);
+    }
+    if (res.reason === 'bad-mode') {
+      UI.error(`Invalid --mode "${res.mode}". Use "extend" or "override".`);
+      process.exit(1);
+    }
+    process.exit(1);
+  }
+
+  UI.success(`Created ${res.overlayRel}`);
+  UI.info(`Base file: ${res.baseRel}`);
+  UI.info(`Targets framework v${res.fwVersion || 'unknown'} (base_file_sha=${res.baseSha}).`);
   UI.newline();
   UI.list([
-    `Edit ${overlayRel} to add your customisations.`,
-    `Validate the merge with: npx baldart overlay validate ${overlayRel}`,
-    kind === 'skill'
+    `Edit ${res.overlayRel} to add your customisations.`,
+    `Validate the merge with: npx baldart overlay validate ${res.overlayRel}`,
+    res.kind === 'skill'
       ? `Run any /-command that uses this skill to see the overlay applied at runtime.`
-      : `Apply with: npx baldart update (regenerates .claude/${kind}s/${name}.md from base + overlay).`,
+      : `Apply with: npx baldart update (regenerates .claude/${res.kind}s/${res.name}.md from base + overlay).`,
   ]);
 }
 
@@ -378,4 +404,4 @@ async function drift(target, options = {}) {
   UI.info(`Summary: ${clean} clean, ${drifted} drifted, ${unknown} unknown — of ${targets.length} overlay(s).`);
 }
 
-module.exports = { scaffold, validate, drift };
+module.exports = { scaffold, scaffoldFile, validate, drift, parseTarget };

package/src/commands/update.js

@@ -20,6 +20,68 @@ function readEnabledTools(cwd = process.cwd()) {
   return ['claude'];
 }
 
+// Allowed values for `--on-divergence` — the non-interactive escape hatch that
+// lets an agent / CI complete (or deliberately stop) an update when the
+// consumer has local commits on `.framework/`. Without it a non-TTY caller has
+// no non-destructive path: `--yes` refuses, the interactive prompt needs a TTY,
+// and `--reset` is gated on a clean working tree (see Finding 2 in the
+// agent-overlay feedback that prompted this).
+const DIVERGENCE_STRATEGIES = ['abort', 'pull', 'scaffold-overlays'];
+
+// Map a touched framework path to an `overlay scaffold` target string.
+//   .framework/framework/.claude/agents/coder.md     → 'agents/coder'
+//   .framework/framework/.claude/commands/check.md    → 'commands/check'
+//   .framework/framework/.claude/skills/bug/SKILL.md  → 'skill/bug'
+// Returns null for anything that isn't an overlay-able framework primitive.
+function frameworkPathToOverlayTarget(p) {
+  const m = /(?:^|\/)\.framework\/framework\/\.claude\/(agents|commands|skills)\/(.+)$/.exec(p);
+  if (!m) return null;
+  const [, dir, rest] = m;
+  if (dir === 'skills') {
+    const name = rest.split('/')[0];
+    return name ? `skill/${name}` : null;
+  }
+  const name = rest.replace(/\.md$/, '');
+  if (!name || name.includes('/')) return null;
+  return `${dir}/${name}`;
+}
+
+// Scaffold overlay skeletons for every overlay-able framework file touched by
+// the given commits. Reuses overlay.scaffoldFile (the CLI is the source of
+// truth — we never re-implement frontmatter/path logic here). Idempotent:
+// existing overlays are left untouched.
+function scaffoldOverlaysForCommits(commits) {
+  const overlay = require('./overlay');
+  const cwd = process.cwd();
+  const targets = new Set();
+  for (const c of commits) {
+    for (const p of (c.touched || [])) {
+      const t = frameworkPathToOverlayTarget(p);
+      if (t) targets.add(t);
+    }
+  }
+  const created = [];
+  const skipped = [];
+  if (targets.size === 0) {
+    UI.warning('Could not derive any overlay target from the divergent commits.');
+    UI.info('They may touch files outside `.claude/{agents,skills,commands}/`. Use `/baldart-push` or `--on-divergence pull`.');
+    return { created, skipped };
+  }
+  for (const t of [...targets].sort()) {
+    const r = overlay.scaffoldFile(cwd, t);
+    if (r.ok) {
+      created.push(r.overlayRel);
+      UI.success(`Scaffolded overlay: ${r.overlayRel}  (base: ${r.baseRel})`);
+    } else if (r.reason === 'exists') {
+      skipped.push(r.overlayRel);
+      UI.info(`Overlay already exists, left as-is: ${r.overlayRel}`);
+    } else {
+      UI.warning(`Could not scaffold ${t}: ${r.reason}${r.baseRel ? ` (${r.baseRel})` : ''}`);
+    }
+  }
+  return { created, skipped };
+}
+
 // Path prefixes BALDART itself writes during install/update. Anything outside
 // these patterns is treated as user-owned and never auto-staged.
 const BALDART_MANAGED_PATTERNS = [
@@ -359,6 +421,14 @@ async function update(options = {}) {
   const autoStash = autoYes || options.autoStash === true;
   const confirm = async (msg, def = true) => (autoYes ? def : UI.confirm(msg, def));
 
+  // Non-interactive divergence strategy (since v3.29.0). Validated up-front so
+  // a typo fails fast instead of mid-flow after the network fetch.
+  const divStrategy = options.onDivergence;
+  if (divStrategy !== undefined && !DIVERGENCE_STRATEGIES.includes(divStrategy)) {
+    UI.error(`Invalid --on-divergence "${divStrategy}". Use one of: ${DIVERGENCE_STRATEGIES.join(', ')}.`);
+    process.exit(1);
+  }
+
   try {
     // Step 1: Verify installation
     UI.header('STEP 1/5: Verify Installation');
@@ -470,45 +540,107 @@ async function update(options = {}) {
       } 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')) {
+        const overlayCommits = status.divergenceCommits.filter((c) => c.category === 'custom-overlay-able');
+        for (const c of overlayCommits) {
           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`.');
+
+        // Non-interactive resolution (agents / CI) via --on-divergence.
+        if (divStrategy === 'scaffold-overlays') {
+          UI.newline();
+          scaffoldOverlaysForCommits(overlayCommits);
+          UI.newline();
+          UI.info('Next steps:');
+          UI.list([
+            'Fill in the overlay skeleton(s) above to capture your customisations (the base file shows what you changed).',
+            'Then complete the update with `npx baldart update --reset --yes --i-know` — this discards the now-redundant `.framework/` edits and reinstalls clean; your `.baldart/overlays/` are preserved and re-applied.',
+            'Alternatively, push the edits upstream with `/baldart-push` if they are generic improvements.',
+          ], 'cyan');
           process.exit(0);
         }
-        // 'keep' → fall through, subtree pull will attempt merge
+        if (divStrategy === 'abort') { UI.info('Update cancelled (--on-divergence abort).'); process.exit(0); }
+        if (divStrategy === 'pull') {
+          UI.info('Keeping the custom commits (--on-divergence pull). The subtree pull will attempt a merge.');
+          // fall through
+        } else if (autoYes) {
+          // --yes without an explicit strategy: never silently overwrite. Tell
+          // the (likely non-TTY) caller exactly which flag completes the update.
+          UI.error('Custom edits present — refusing to resolve them unattended under --yes.');
+          UI.info('Re-run with one of:');
+          UI.list([
+            '--on-divergence scaffold-overlays  → auto-create overlay skeleton(s), then stop so you can fill them',
+            '--on-divergence pull               → keep the commits and merge the update (non-destructive)',
+            '--reset --yes --i-know             → discard .framework/ edits and reinstall clean (destructive)',
+          ], 'cyan');
+          process.exit(1);
+        } else {
+          const choice = await UI.select('How would you like to proceed?', [
+            { name: 'Scaffold overlay skeleton(s) now (recommended — then fill them in & re-run)', 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.newline();
+            scaffoldOverlaysForCommits(overlayCommits);
+            UI.newline();
+            UI.info('Next steps:');
+            UI.list([
+              'Edit the overlay skeleton(s) above to capture your customisations (`/overlay` from Claude Code gives a guided flow).',
+              'Then complete the update with `npx baldart update --reset` — discards the redundant `.framework/` edits, reinstalls clean, re-applies your overlays.',
+            ], 'cyan');
+            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.');
+        const overlayCommits = status.divergenceCommits.filter((c) => c.category === 'custom-overlay-able');
+
+        // Non-interactive resolution (agents / CI) via --on-divergence.
+        if (divStrategy === 'scaffold-overlays') {
+          if (overlayCommits.length === 0) {
+            UI.error('No overlay-able commits to scaffold — every custom commit touches non-overlayable paths (src/, CHANGELOG, …).');
+            UI.info('Use `/baldart-push` to contribute them upstream, or `--on-divergence pull` to merge.');
+            process.exit(1);
+          }
+          UI.newline();
+          scaffoldOverlaysForCommits(overlayCommits);
+          UI.newline();
+          UI.warning('Scaffolded overlays for the overlay-able commits, but custom-other commit(s) remain — NOT pulling (would be destructive to those edits).');
+          UI.info('Resolve the remaining commits (push upstream with `/baldart-push`, or revert), then re-run `npx baldart update`.');
           process.exit(0);
         }
-        // 'pull' → fall through
+        if (divStrategy === 'abort') { UI.info('Update cancelled (--on-divergence abort).'); process.exit(0); }
+        if (divStrategy === 'pull') {
+          UI.info('Pulling over the custom commits (--on-divergence pull). A merge commit will be created — resolve any conflicts that surface.');
+          // fall through
+        } else if (autoYes) {
+          UI.error('Custom commits present — refusing to pull over them unattended under --yes.');
+          UI.info('Re-run with one of:');
+          UI.list([
+            '--on-divergence pull               → create a merge commit over your edits (non-destructive)',
+            '--on-divergence scaffold-overlays  → scaffold overlays for the overlay-able subset (custom-other still needs handling)',
+            '--on-divergence abort              → do nothing',
+          ], 'cyan');
+          UI.info('Best practice: contribute generic improvements upstream first with `/baldart-push`.');
+          process.exit(1);
+        } else {
+          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.

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

@@ -41,6 +41,65 @@ const SUBJECT_FIXTURES = [
   { subject: "Squashed 'docs/' content from abc..def", expected: null },
   // Chore without 'baldart' keyword — NOT chore-wrapper
   { subject: 'chore: update dependencies', expected: null },
+
+  // ─── subject-regex BLIND SPOTS (now covered by parent-count detection) ──
+  // git omits the "into <branch>" suffix when the merge lands on `master`,
+  // so a real subtree-pull merge can present as a bare "Merge commit 'x'".
+  // The subject classifier returns null here; classifyDivergence() then
+  // relabels it `subtree-merge` because the commit has 2+ parents. We assert
+  // the subject classifier's null so the gap (and why parents matter) is
+  // documented and regression-locked.
+  { subject: "Merge commit 'abc123'", expected: null },
+  // Shared-repo collaboration merge — the " of <url>" segment breaks the
+  // narrow `Merge branch 'x' into <branch>$` shape. Also null → parent count.
+  { subject: "Merge branch 'develop' of github.com:org/repo into develop", expected: null },
+  { subject: "Merge remote-tracking branch 'origin/main'", expected: null },
+];
+
+// aggregateDivergenceClass(commits) — pure reduction of per-commit categories
+// to the divergence class. The headline Finding-1 case: a single overlay-able
+// commit alongside a plumbing merge must stay `overlay-able`, NOT collapse to
+// `mixed`, because the merge is excluded as noise before the decision.
+const AGGREGATE_FIXTURES = [
+  {
+    name: 'overlay-able commit + plumbing merge → overlay-able (not mixed)',
+    commits: [
+      { category: 'custom-overlay-able' },
+      { category: 'subtree-merge' },
+    ],
+    expected: 'overlay-able',
+  },
+  {
+    name: 'overlay-able + subtree-squash + chore-wrapper → overlay-able',
+    commits: [
+      { category: 'custom-overlay-able' },
+      { category: 'subtree-squash' },
+      { category: 'chore-wrapper' },
+    ],
+    expected: 'overlay-able',
+  },
+  {
+    name: 'overlay-able + custom-other → mixed (genuine mix preserved)',
+    commits: [
+      { category: 'custom-overlay-able' },
+      { category: 'custom-other' },
+    ],
+    expected: 'mixed',
+  },
+  {
+    name: 'only custom-other → real-custom',
+    commits: [{ category: 'custom-other' }, { category: 'subtree-merge' }],
+    expected: 'real-custom',
+  },
+  {
+    name: 'only noise → all-noise',
+    commits: [
+      { category: 'subtree-merge' },
+      { category: 'subtree-squash' },
+      { category: 'chore-wrapper' },
+    ],
+    expected: 'all-noise',
+  },
 ];
 
 const PATH_FIXTURES = [
@@ -116,5 +175,17 @@ for (const f of PATH_FIXTURES) {
   }
 }
 
+console.log('\n─── Aggregate class ───');
+for (const f of AGGREGATE_FIXTURES) {
+  const actual = GitUtils.aggregateDivergenceClass(f.commits);
+  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);

package/src/utils/git.js

@@ -263,43 +263,64 @@ class GitUtils {
       const raw = await this.git.raw([
         'log',
         'FETCH_HEAD..HEAD',
-        '--pretty=format:%H%x00%s',
+        '--pretty=format:%H%x00%P%x00%s',
         '--',
         FRAMEWORK_DIR
       ]);
       for (const line of raw.split('\n')) {
         if (!line.trim()) continue;
-        const [sha, ...rest] = line.split('');
+        const [sha, parentStr, ...rest] = line.split('');
         const subject = rest.join('');
+        const parents = (parentStr || '').trim().split(/\s+/).filter(Boolean);
+        const isMerge = parents.length >= 2;
         let category = this.classifyCommitSubject(subject);
+        let touched;
+        if (!category && isMerge) {
+          // A merge commit is git plumbing, never a user customization. The
+          // real content (if any) lives in the merged commits, which appear
+          // in this range on their own when they aren't already upstream.
+          // `git subtree pull --squash` merges vary in subject across git
+          // versions and default-branch name ("Merge commit 'x'" with no
+          // "into <branch>" suffix when landing on `master`; "Merge branch
+          // 'x' of <url> into <branch>" on shared repos), so the subject
+          // regex alone is brittle. Detect merges structurally by parent
+          // count and treat them as noise — otherwise a single plumbing
+          // merge poisons an otherwise overlay-able set into `mixed`.
+          category = 'subtree-merge';
+        }
         if (!category) {
           // Need file list to disambiguate custom-overlay-able vs custom-other.
-          let touched = [];
+          touched = [];
           try {
             const filesRaw = await this.git.raw(['diff-tree', '--no-commit-id', '--name-only', '-r', sha]);
             touched = filesRaw.split('\n').filter((l) => l.trim());
           } catch (_) { /* leave empty → custom-other */ }
           category = this.classifyCommitByPaths(touched);
         }
-        commits.push({ sha, subject, category });
+        commits.push({ sha, subject, category, parents, touched: touched || [] });
       }
     } catch (_) {
       return { class: 'unknown', commits: [] };
     }
 
     if (commits.length === 0) return { class: 'all-noise', commits: [] };
+    return { class: GitUtils.aggregateDivergenceClass(commits), commits };
+  }
 
+  // Pure aggregation of per-commit categories into the divergence class.
+  // Extracted as a static method so it can be unit-tested without a live repo
+  // (see src/utils/__tests__/classify-divergence.test.js). Noise categories
+  // (subtree plumbing + CLI chore wrappers + merge commits) are excluded
+  // BEFORE deciding overlay-able vs mixed, so plumbing never downgrades the UX.
+  static aggregateDivergenceClass(commits) {
     const noiseCategories = new Set(['subtree-merge', 'subtree-squash', 'chore-wrapper']);
     const nonNoise = commits.filter((c) => !noiseCategories.has(c.category));
-    if (nonNoise.length === 0) return { class: 'all-noise', commits };
-
+    if (nonNoise.length === 0) return 'all-noise';
     const hasOverlayable = nonNoise.some((c) => c.category === 'custom-overlay-able');
     const hasOther = nonNoise.some((c) => c.category === 'custom-other');
-    let aggregate = 'real-custom';
-    if (hasOverlayable && !hasOther) aggregate = 'overlay-able';
-    else if (hasOverlayable && hasOther) aggregate = 'mixed';
-
-    return { class: aggregate, commits };
+    if (hasOverlayable && !hasOther) return 'overlay-able';
+    if (hasOverlayable && hasOther) return 'mixed';
+    return 'real-custom';
   }
 
   async getUpdateStatus(repo, branch = 'main') {