baldart 5.10.1 → 5.11.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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).
 
+## [5.11.0] - 2026-07-06
+
+**Seamless framework-drift reconciliation in `baldart update` — a trivially-drifted shared framework file no longer dead-ends the whole update.**
+A `mayo` consumer stuck at v5.7.0→v5.9.0 surfaced the failure: five ancient `.framework/` commits (an add-then-revert of the v4.77.0 extractor, a superseded responsive-prose delete, a FEAT-0054-03 gating feature) were all flagged `custom-other` → class `mixed`/`real-custom` → **hard block**. Root cause, proven by diffing HEAD vs upstream file-by-file: of the **14** framework files those commits touched, **13 were already byte-identical to upstream** — only ONE, `design-system-protocol.md`, still diverged, and its *entire* divergence was **2 cosmetic characters** (a `+ ` vs `- ` markdown continuation bullet, a merge artifact). Because `isAbsorbedAgainstUpstream` is **all-or-nothing per commit** (a commit demotes to `absorbed` only when EVERY touched payload file matches upstream), that single 2-char drift in a file all five commits share poisoned the whole set. Five commits blocked by two cosmetic characters, on every release.
+
+The fix encodes BALDART's own contract — **direct `.framework/` edits are blocked by the `framework-edit-gate` and sanctioned customizations live in overlays, so an uncovered residual is drift upstream OWNS** — into three additive classifier/updater pieces (no new agent, no new file):
+
+- **New `liveDriftAgainstUpstream(touched)` + `reconcilable` category** (`src/utils/git.js` `classifyDivergence`). A would-be `custom-other` commit whose SURVIVING drift (`absorbablePayloadSubset` with HEAD≠upstream, computed by cheap blob-SHA compare) is confined to framework-owned files that (a) still exist upstream and (b) are NOT captured by any existing overlay is demoted from `custom-other` to `reconcilable`, carrying the exact file list. Overlay-COVERED drift routes to the capture path (intentional, tracked); net-new/deleted framework files keep flagging as real drift (an overwrite can't cleanly reconcile them).
+- **Revert-pair cancellation** (`GitUtils.cancelRevertPairs`, pure/static). A `Revert "<subject>"` commit and the commit it reverts are a net no-op on the tree — both demote to `absorbed`. Kills the add-then-revert class that re-triggered the gate every release.
+- **Seamless auto-align in `update`** (`src/commands/update.js`). New non-blocking `reconcilable` divergence branch: it lists the framework-owned files that drift, aligns each to its upstream (FETCH_HEAD) blob via the new `reconcileFrameworkDrift` helper and commits ONCE (so the subtree pull has no local hunk to conflict on), then proceeds — with the pre-pull backup tag making it fully recoverable. `git.on_divergence: abort` still lets a cautious consumer opt out; a genuine `custom-other` blocker (net-new/deleted/overlay-covered) still dominates to `mixed`/`real-custom` and stops for `/baldart-push` or `--on-divergence pull`.
+- **`aggregateDivergenceClass`** gains the `reconcilable` class (blockers dominate → `mixed`/`real-custom`; else overlay-able → `overlay-able`; else reconcilable → `reconcilable`; else `all-noise`). `doctor`/`version` need no change (they delegate to `update`, which now self-heals the drift).
+- Tests: `src/utils/__tests__/classify-divergence.test.js` gains 5 `reconcilable` aggregate fixtures + 4 `cancelRevertPairs` fixtures (61 pass, 0 fail). End-to-end validated on a synthetic subtree consumer reproducing the exact cosmetic-drift cascade → class flips from blocking to `reconcilable`, and `reconcileFrameworkDrift` aligns the file byte-for-byte to upstream.
+- **Codex parity: portable** — pure CLI (Node), runtime-agnostic; benefits `[claude]`, `[codex]`, and `[claude, codex]` consumers identically. **No new `baldart.config.yml` key** (rides on the existing `git.on_divergence` policy) → the schema-change propagation rule does NOT apply.
+
 ## [5.10.1] - 2026-07-06
 
 **Per-wave Codex relay backported to the v5.6.0 blocking-foreground pattern — no more bogus TIMEOUT at 83s that kills a live Codex.**

package/VERSION

@@ -1 +1 @@
-5.10.1
+5.11.0

package/package.json

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

package/src/commands/update.js

@@ -118,6 +118,43 @@ function scaffoldOverlaysForCommits(commits) {
   return { created, skipped };
 }
 
+// Seamless framework-drift reconciliation (v5.11.0). Given the exact set of
+// framework-owned payload files whose HEAD content still diverges from upstream
+// (the `reconcilableFiles` computed by classifyDivergence → liveDriftAgainst
+// Upstream), align each to its upstream (FETCH_HEAD) blob and commit ONCE, so
+// the subsequent subtree pull has no local hunk to conflict on. These are files
+// BALDART's own contract says upstream owns (direct `.framework/` edits are
+// blocked by the edit-gate; sanctioned customizations live in overlays), so
+// overwriting them loses nothing tracked — and the pre-pull backup tag makes it
+// recoverable regardless. Returns the list actually rewritten. Non-fatal on a
+// per-file read/write error (skips it → the pull will surface any residue).
+async function reconcileFrameworkDrift(git, files) {
+  const fs = require('fs');
+  const path = require('path');
+  const cwd = process.cwd();
+  const written = [];
+  for (const p of files) {
+    // p is a repo-relative `.framework/<rest>` path; upstream (FETCH_HEAD) has no
+    // `.framework/` prefix. Read the upstream blob and overwrite the working file.
+    const upstreamPath = p.replace(/^\.framework\//, '');
+    try {
+      const blob = await git.git.raw(['show', `FETCH_HEAD:${upstreamPath}`]);
+      fs.writeFileSync(path.join(cwd, p), blob);
+      written.push(p);
+    } catch (_) { /* skip — pull will reconcile or surface it */ }
+  }
+  if (written.length) {
+    try {
+      await git.git.add(written);
+      const st = await git.git.status();
+      if (st.staged.length) {
+        await git.git.commit('chore(baldart): align framework-owned drift to upstream (pre-pull reconcile)');
+      }
+    } catch (_) { /* non-fatal — files remain aligned on disk for the pull */ }
+  }
+  return written;
+}
+
 // Path prefixes BALDART itself writes during install/update. Anything outside
 // these patterns is treated as user-owned and never auto-staged.
 //
@@ -1077,6 +1114,27 @@ async function update(options = {}, unknownArgs = []) {
       }
       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 === 'reconcilable') {
+        // Only framework-owned residual drift, uncovered by any overlay → upstream
+        // owns these files. Align them to upstream BEFORE the pull so the update is
+        // seamless instead of dead-ending. The backup tag (created below) + the
+        // shown file list keep it transparent and recoverable. `--on-divergence
+        // abort` still lets a cautious user opt out.
+        const reconcileFiles = [...new Set(
+          status.divergenceCommits.flatMap((c) => c.reconcilableFiles || [])
+        )].sort();
+        UI.warning(`Detected ${reconcileFiles.length} framework-owned file(s) that drift from upstream but carry no overlay — upstream owns them.`);
+        for (const f of reconcileFiles) UI.info(`  • ${f}`);
+        if (divStrategy === 'abort') {
+          UI.info('Update cancelled (--on-divergence abort). The drift is left untouched.');
+          emitUpdateJson({ ok: false, action: 'aborted',
+            divergence_class: status.divergenceClass, reconcile_files: reconcileFiles,
+            reason: 'Reconcilable framework drift left untouched (--on-divergence abort).' }, 0);
+        }
+        UI.info('Aligning them to upstream (pre-pull reconcile) — nothing tracked is lost; a backup tag is created below…');
+        const written = await reconcileFrameworkDrift(git, reconcileFiles);
+        UI.success(`Aligned ${written.length} framework file(s) to upstream. Proceeding with the update.`);
+        // fall through to the normal preview + pull
       } 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.');
@@ -1131,7 +1189,7 @@ async function update(options = {}, unknownArgs = []) {
         }
       } 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))) {
+        for (const c of status.divergenceCommits.filter((c) => !['subtree-merge', 'subtree-squash', 'chore-wrapper', 'absorbed', 'reconcilable'].includes(c.category))) {
           UI.info(`  • ${c.sha.slice(0, 7)} [${c.category}] — ${c.subject}`);
         }
         const overlayCommits = status.divergenceCommits.filter((c) => c.category === 'custom-overlay-able');

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

@@ -121,6 +121,82 @@ const AGGREGATE_FIXTURES = [
     ],
     expected: 'overlay-able',
   },
+  // ─── reconcilable (v5.11.0): framework-owned drift, no overlay → seamless ──
+  {
+    name: 'reconcilable alone → reconcilable (framework-owned, non-blocking)',
+    commits: [{ category: 'reconcilable' }],
+    expected: 'reconcilable',
+  },
+  {
+    name: 'reconcilable + plumbing noise → reconcilable',
+    commits: [
+      { category: 'reconcilable' },
+      { category: 'subtree-merge' },
+      { category: 'absorbed' },
+    ],
+    expected: 'reconcilable',
+  },
+  {
+    name: 'reconcilable + custom-other → real-custom (blocker dominates)',
+    commits: [
+      { category: 'reconcilable' },
+      { category: 'custom-other' },
+    ],
+    expected: 'real-custom',
+  },
+  {
+    name: 'reconcilable + overlay-able → overlay-able (overlay path wins)',
+    commits: [
+      { category: 'reconcilable' },
+      { category: 'custom-overlay-able' },
+    ],
+    expected: 'overlay-able',
+  },
+  {
+    name: 'reconcilable + overlay-able + custom-other → mixed (blocker + overlay)',
+    commits: [
+      { category: 'reconcilable' },
+      { category: 'custom-overlay-able' },
+      { category: 'custom-other' },
+    ],
+    expected: 'mixed',
+  },
+];
+
+// cancelRevertPairs(commits) — mutating: a `Revert "<subject>"` commit and its
+// target both demote to `absorbed` (net-zero tree effect). Only custom-* are
+// touched; noise categories and unmatched reverts are left as-is.
+const REVERT_PAIR_FIXTURES = [
+  {
+    name: 'add + its Revert → both absorbed',
+    commits: [
+      { subject: '[CHORE] add extractor', category: 'reconcilable' },
+      { subject: 'Revert "[CHORE] add extractor"', category: 'reconcilable' },
+    ],
+    expected: ['absorbed', 'absorbed'],
+  },
+  {
+    name: 'revert with no matching target → left unchanged',
+    commits: [
+      { subject: 'Revert "something not here"', category: 'custom-other' },
+    ],
+    expected: ['custom-other'],
+  },
+  {
+    name: 'target is noise → only the custom revert is demoted',
+    commits: [
+      { subject: 'chore(baldart): x', category: 'chore-wrapper' },
+      { subject: 'Revert "chore(baldart): x"', category: 'custom-other' },
+    ],
+    expected: ['chore-wrapper', 'absorbed'],
+  },
+  {
+    name: 'non-revert commits untouched',
+    commits: [
+      { subject: 'feat: real work', category: 'custom-other' },
+    ],
+    expected: ['custom-other'],
+  },
 ];
 
 const PATH_FIXTURES = [
@@ -247,6 +323,16 @@ for (const f of AGGREGATE_FIXTURES) {
   }
 }
 
+console.log('\n─── Revert-pair cancellation ───');
+for (const f of REVERT_PAIR_FIXTURES) {
+  const commits = f.commits.map((c) => ({ ...c }));
+  GitUtils.cancelRevertPairs(commits);
+  const actual = commits.map((c) => c.category);
+  const ok = actual.length === f.expected.length && actual.every((v, i) => v === f.expected[i]);
+  if (ok) { pass++; console.log(`  ✓ ${f.name} → [${actual.join(', ')}]`); }
+  else { fail++; console.log(`  ✗ ${f.name} → [${actual.join(', ')}] (expected [${f.expected.join(', ')}])`); }
+}
+
 console.log('\n─── Overlay path mapping ───');
 for (const f of OVERLAY_REL_FIXTURES) {
   const actual = GitUtils.overlayRelForFrameworkFile(f.file);

package/src/utils/git.js

@@ -218,13 +218,21 @@ class GitUtils {
   //                     live drift → noise.
   //   - custom-overlay-able: user edited a framework agent/skill/command
   //                          → should migrate to .baldart/overlays/
-  //   - custom-other:   anything else (src/, CHANGELOG, ad-hoc fixes)
+  //   - reconcilable:   a would-be custom-other whose SURVIVING drift is confined
+  //                     to framework-owned payload files that exist upstream and
+  //                     are NOT captured by any overlay → upstream OWNS them;
+  //                     `update` aligns them to upstream then pulls (see
+  //                     liveDriftAgainstUpstream). Non-blocking.
+  //   - custom-other:   anything else that still carries genuine live drift
+  //                     (net-new/deleted framework files, overlay-covered edits)
   //
   // Aggregate `class`:
   //   - all-noise:    every commit is subtree-* / chore-wrapper / absorbed → auto-resolve
   //   - overlay-able: every non-noise commit is overlay-able → suggest /overlay
+  //   - reconcilable: non-noise commits are only framework-owned reconcilable
+  //                   drift → align-to-upstream then pull (seamless, non-blocking)
   //   - real-custom:  every non-noise commit is custom-other → prompt 3-way
-  //   - mixed:        non-noise commits span both → prompt 3-way
+  //   - mixed:        non-noise commits span overlay-able + custom-other → prompt 3-way
   //
   // Default-conservative: any commit whose subject + touched-paths don't
   // match a known pattern is classified `custom-other`, never auto-resolved.
@@ -357,6 +365,32 @@ class GitUtils {
     return true;
   }
 
+  // The subset of a commit's touched `.framework/` payload files whose current
+  // HEAD content STILL diverges from upstream (FETCH_HEAD) — i.e. the surviving
+  // "live drift" the subtree pull would otherwise have to merge. Restricted to
+  // the `absorbablePayloadSubset` (consumer files + subtree bookkeeping
+  // excluded — see there). A file is INCLUDED only when it exists BOTH at HEAD
+  // and upstream and their blob SHAs differ; a file that is net-new locally
+  // (absent upstream) or deleted at HEAD is EXCLUDED here (it cannot be cleanly
+  // reconciled by an overwrite-with-upstream, so it must keep flagging as real
+  // drift). Used to decide the `reconcilable` category. Cheap — compares SHAs.
+  async liveDriftAgainstUpstream(touched) {
+    const prefix = `${FRAMEWORK_DIR}/`;
+    const payload = GitUtils.absorbablePayloadSubset(touched);
+    const drift = [];
+    for (const p of payload) {
+      const upstreamPath = p.slice(prefix.length);
+      let headSha;
+      let upSha;
+      try { headSha = (await this.git.raw(['rev-parse', `HEAD:${p}`])).trim(); }
+      catch (_) { continue; } // deleted at HEAD → not overwrite-reconcilable
+      try { upSha = (await this.git.raw(['rev-parse', `FETCH_HEAD:${upstreamPath}`])).trim(); }
+      catch (_) { continue; } // net-new local (absent upstream) → not reconcilable
+      if (headSha && upSha && headSha !== upSha) drift.push(p);
+    }
+    return drift;
+  }
+
   async classifyDivergence() {
     // Inspect aheadScoped commits — those not on FETCH_HEAD that touch .framework/.
     const commits = [];
@@ -407,19 +441,69 @@ class GitUtils {
             && await this.isAbsorbedAgainstUpstream(touched)) {
           category = 'absorbed';
         }
+        // Seamless framework-drift reconciliation (v5.11.0). A `custom-other`
+        // commit that is NOT fully absorbed but whose SURVIVING drift is confined
+        // to framework-owned payload files that (a) still exist upstream and (b)
+        // are NOT captured by any existing overlay is, by BALDART's own contract,
+        // overwrite-reconcilable: direct `.framework/` edits are blocked by the
+        // `framework-edit-gate` and sanctioned customizations live in overlays, so
+        // an uncovered residual is drift upstream OWNS. Demote it to `reconcilable`
+        // + carry the exact file list so `update` can align those files to upstream
+        // BEFORE the pull instead of dead-ending the whole update. This kills the
+        // cascade where ONE trivially-drifted shared file (e.g. a cosmetic 2-char
+        // diff in `design-system-protocol.md`) poisons every commit that touches it
+        // into `custom-other`. Overlay-COVERED drift routes to the capture path
+        // instead (intentional, tracked); net-new/deleted files keep flagging.
+        let reconcilableFiles = [];
+        if (category === 'custom-other') {
+          const drift = await this.liveDriftAgainstUpstream(touched);
+          const anyCovered = drift.some((p) => {
+            const rel = GitUtils.overlayRelForFrameworkFile(p);
+            return rel ? fs.existsSync(path.join(this.cwd, rel)) : false;
+          });
+          if (drift.length && !anyCovered) {
+            category = 'reconcilable';
+            reconcilableFiles = drift;
+          }
+        }
         const overlayCovered = category === 'custom-overlay-able'
           ? this.overlayCoversTouched(touched)
           : false;
-        commits.push({ sha, subject, category, parents, touched: touched || [], overlayCovered });
+        commits.push({ sha, subject, category, parents, touched: touched || [], overlayCovered, reconcilableFiles });
       }
     } catch (_) {
       return { class: 'unknown', commits: [] };
     }
 
     if (commits.length === 0) return { class: 'all-noise', commits: [] };
+    // Revert-pair cancellation: a `Revert "<subject>"` commit and the commit it
+    // reverts are a net no-op on the tree — neither contributes live drift, so
+    // both are noise. Detect by subject (git's default revert subject) and demote
+    // the pair to `absorbed`. Guards a long-lived add-then-revert of a framework
+    // file from re-triggering the divergence gate on every release.
+    GitUtils.cancelRevertPairs(commits);
     return { class: GitUtils.aggregateDivergenceClass(commits), commits };
   }
 
+  // Pure: demote reverted+revert commit pairs to `absorbed` in place. A default
+  // git revert of "<subject>" produces the subject `Revert "<subject>"`; when
+  // both the revert and its target appear in the divergence range, their net
+  // tree effect is zero. Only demotes commits that are still `custom-*` (never
+  // touches genuine noise categories). Extracted static for unit-testing.
+  static cancelRevertPairs(commits) {
+    const custom = new Set(['custom-overlay-able', 'custom-other', 'reconcilable']);
+    const bySubject = new Map();
+    for (const c of commits) bySubject.set(c.subject, c);
+    for (const c of commits) {
+      const m = /^Revert "(.+)"$/.exec(c.subject || '');
+      if (!m) continue;
+      const target = bySubject.get(m[1]);
+      if (!target) continue;
+      if (custom.has(c.category)) { c.category = 'absorbed'; c.reconcilableFiles = []; }
+      if (custom.has(target.category)) { target.category = 'absorbed'; target.reconcilableFiles = []; }
+    }
+  }
+
   // 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
@@ -431,8 +515,15 @@ class GitUtils {
     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');
-    if (hasOverlayable && !hasOther) return 'overlay-able';
-    if (hasOverlayable && hasOther) return 'mixed';
+    const hasReconcilable = nonNoise.some((c) => c.category === 'reconcilable');
+    // A genuine `custom-other` blocker always dominates — it needs `/baldart-push`
+    // or an explicit `--on-divergence pull` (reconcilable commits ride along and
+    // are handled by the pull). Overlay-able edits route to the capture path.
+    if (hasOther) return hasOverlayable ? 'mixed' : 'real-custom';
+    if (hasOverlayable) return 'overlay-able';
+    // No blockers, no overlay-able: only framework-owned reconcilable drift →
+    // `update` aligns those files to upstream, then pulls. Seamless, non-blocking.
+    if (hasReconcilable) return 'reconcilable';
     return 'real-custom';
   }