baldart 5.10.1 → 5.11.1

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.1] - 2026-07-07
+
+**`/new` now tears down its idle background subagents at end of run — closes the "Background work is running" leak on terminal exit.**
+A user reported that after every interactive `/new` run, closing the terminal warns `Background work is running` and lists the batch's teammates (`## AUTONOMOUS CARD IMPLEMENTATION — FEAT-00NN`, the `i18n-translator` fill, the doc closer) as if they were still executing. They are not — they **finished**. Root cause: `/new` spawns its coder + closer subagents with `run_in_background: true`, and a background subagent that completes its work does **NOT** terminate — it goes idle ("rests") so the orchestrator could `SendMessage`/resume it (deliberate: the empty-result gate reads their transcripts from disk, and the framework explicitly forbids messaging a rested teammate). Phase 6c's teardown ended the **Codex broker** (a Bash process) + reaped orphan MCP servers, but there was **no `TaskStop` anywhere in the framework** — so the idle teammates stayed alive until Claude Code's `SessionEnd` (whenever the user closes the terminal). Harmless to the committed work (already merged), but noisy and wasteful of session resources.
+
+- **New Phase 6c step 5c** (`framework/.claude/skills/new/references/merge-cleanup.md`) — after the merge and after every teammate's transcript has been consumed, `TaskList` → `TaskStop` the batch's idle teammates, scoped to THIS run only: matched by the `coder-<CARD-ID>` name prefix OR any card ID in the tracker `## Card Queue` (so the match survives a compaction). NEVER stops a task outside the batch signature (the user's unrelated background work in the same session). Best-effort + non-blocking + one log line (`Background subagents teardown: <stopped N | none alive | N/A (Codex) | skipped>`).
+- **Mirror on early exit** (`framework/.claude/skills/new/SKILL.md` § "Terminal hygiene") — the same `TaskList`→`TaskStop` runs when the batch ends before Phase 6c (unrecoverable HALT / killed final-review workflow), exactly as the Codex-broker early teardown already did.
+- **Pointer** in `references/team-mode.md` — the parallel `coder-<CARD-ID>` fan-out is the widest source of the leak; noted that Phase 6c 5c tears them down after merge.
+- **`/new2` is unaffected** — its agents run inside the dynamic-workflow runtime and die with the workflow; only the classic `/new` (Task-tool background subagents) leaked.
+- **Codex parity: N/A** — no observable Agent/Task tool on Codex, team-mode is forced sequential there, and Codex named-agent spawns do not persist as idle background tasks (`framework/agents/runtime-portability-protocol.md`). **No new `baldart.config.yml` key** → the schema-change propagation rule does NOT apply. `/new` skill version → 2.4.1.
+
+## [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.1

package/framework/.claude/skills/new/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 2.4.1 — 2026-07-07
+
+- **Teardown dei subagent in background a fine run (chiude il leak "Background work is running").**
+  I coder + closer di `/new` sono spawnati con `run_in_background: true`; un subagent che finisce il
+  lavoro **non termina** — va in idle ("rests") così l'orchestratore *potrebbe* farne resume. Il
+  teardown di Phase 6c fermava solo il **broker Codex** (processo Bash), mai i subagent → restavano
+  vivi in idle fino al `SessionEnd`, comparendo come "Background work is running" alla chiusura del
+  terminale. Nuovo step **6c.5c** (`references/merge-cleanup.md`): dopo il merge, `TaskList` →
+  `TaskStop` sui soli teammate di QUESTO batch — matchati per `coder-<CARD-ID>` o per card-ID dal
+  tracker `## Card Queue` (sopravvive alla compaction); mai un task fuori dalla firma del batch
+  (lavoro background non correlato dell'utente). Best-effort + non-bloccante + riga di log. Mirror
+  dello stesso teardown nel path di uscita anticipata (`SKILL.md` § "Terminal hygiene"); pointer in
+  `references/team-mode.md` (i coder paralleli sono la fonte principale del leak). `/new2` non è
+  affetto (agent nel runtime del workflow → muoiono col workflow). Codex parity: N/A (nessun
+  Agent/Task tool osservabile; team-mode forzato sequenziale). Nessuna nuova chiave `baldart.config.yml`.
+
 ## 2.4.0 — 2026-07-06
 
 - **Prossime wave per NOME nel messaggio finale.** Il Step F.6 "Prossimi Passi"

package/framework/.claude/skills/new/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: new
 effort: medium
-version: 2.4.0
+version: 2.4.1
 requires_feature: has_backlog
 description: >
   Orchestrate a team of specialized agents to implement one or more backlog cards
@@ -472,6 +472,14 @@ printf '%s' "$TD" | grep -qi "unknown command" \
 This NEVER touches a broker for another worktree or the user's interactive session (different cwd). If the
 orchestrator is hard-killed and never resumed, the `baldart doctor` reaper is the final safety net.
 
+**Also stop THIS batch's idle background subagents on that early exit** (Claude-only, best-effort) — the
+same teardown Phase 6c step 5c runs on the normal close. `/new`'s coder + closer teammates (`run_in_background`)
+go idle rather than terminate, so an early exit leaves them alive and they surface as "Background work is
+running" when the user closes the terminal. `TaskList` → `TaskStop` each task named `coder-<CARD-ID>` or whose
+name/prompt references a card ID from the tracker `## Card Queue`; NEVER stop a task that does not match the
+batch signature (the user's unrelated background work). Any `TaskStop` error / absent tool is fine — never
+gate the exit on it. (Codex: N/A — no observable Task tool.)
+
 ---
 
 

package/framework/.claude/skills/new/references/merge-cleanup.md

@@ -263,6 +263,28 @@ The most common failure mode is leaving cards IN_PROGRESS after merge. This crea
    Never gate the close on these — any error or a "nothing to do" result is fine; capture each one-line
    summary for the log.
 
+5c. **Background subagent teardown — stop THIS batch's idle teammates (Claude-only, NON-BLOCKING)**.
+   `/new` spawns coder + closer subagents with `run_in_background: true` (team-mode coders
+   `coder-<CARD-ID>`, the step-7c `i18n-translator` fill, the doc closer). A background subagent that
+   finishes its work does **NOT** terminate — it goes idle ("rests") so the orchestrator *could*
+   resume it (and the empty-result gate reads its transcript from disk, never via `SendMessage`). By
+   Phase 6c every card is merged and every teammate's transcript has already been consumed, so these
+   idle teammates are pure dead weight — but the broker teardown above only ends the **Codex broker**
+   (a Bash process); it does NOT touch the subagents. Left alone they stay alive until Claude Code's
+   `SessionEnd` (hours away) and surface as **"Background work is running"** the moment the user tries
+   to close the terminal — noise + held session resources, though the committed work is already safe.
+   Stop ONLY the teammates belonging to THIS batch — matched by the batch's card IDs (read from the
+   tracker `## Card Queue`, so the match survives a compaction) or the `coder-` name prefix:
+   - `TaskList` → for each task still `running`/idle whose `name` is `coder-<CARD-ID>` OR whose
+     `name`/prompt references any card ID in `## Card Queue` (e.g. `FEAT-00NN`) → `TaskStop` it.
+   - **NEVER** `TaskStop` a task that does not match the batch signature — the user may have unrelated
+     background work in the same session. When a task's ownership is ambiguous, LEAVE it (a stray idle
+     `/new` teammate is harmless; killing the user's unrelated work is not).
+   Best-effort: a `TaskStop` error / "already stopped" / an absent `TaskList` tool is all fine —
+   capture a one-line count for the log, never gate the close on it. **(Codex path — N/A:** no
+   observable Agent/Task tool, team-mode is forced sequential, and Codex named-agent spawns do not
+   persist as idle background tasks — see `framework/agents/runtime-portability-protocol.md`.)
+
 6. **Log and exit**:
    ```
    ## Phase 6c — Workspace Hygiene Post-merge
@@ -273,6 +295,7 @@ The most common failure mode is leaving cards IN_PROGRESS after merge. This crea
    Phase 0 snapshot restore: <n/a | popped clean | conflict-deferred-to-user>
    Codex broker teardown: <graceful (pid) | signalled N | none | skipped (error)>
    Codex MCP hygiene (reap): <reaped N/M | nothing to reap | skipped (error)>
+   Background subagents teardown: <stopped N | none alive | N/A (Codex) | skipped (error)>
    Completed: <timestamp>
    ```
    If any step ended in HALT, set `Status: HALT` and report — Phase 7 must NOT start with an unclean main repo unless the user explicitly chose `[Lascia così]`.

package/framework/.claude/skills/new/references/team-mode.md

@@ -348,4 +348,6 @@ Before starting group N, verify ALL cards in groups 0..N-1 are status: done. If
 
 After all groups are complete, run the same Final Review, Phase 6 (merge), and Phase 7 (production readiness) as documented above. Since v3.37.0 the Final Review runs a **single FULL `/codexreview` over the entire batch diff** (per the Final-review FULL gate) — no scope reduction — so every team-mode card, including any reviewed at `light` in D.4b, receives a guaranteed full review before merge.
 
+> **The parallel `coder-<CARD-ID>` teammates are torn down at Phase 6c step 5c** (`references/merge-cleanup.md`) — a `run_in_background` coder goes idle rather than terminating, so team mode (the widest fan-out) is the main source of the "Background work is running" idle-teammate leak. The Phase 6c teardown `TaskStop`s them after merge; nothing to do here.
+
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "5.10.1",
+  "version": "5.11.1",
   "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';
   }