baldart 4.16.1 → 4.16.2

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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).
 
+## [4.16.2] - 2026-06-06
+
+**`baldart update` non si blocca più all'infinito su un edit `.framework/` ormai assorbito a monte.** Un edit locale a un file framework (es. `agents/ui-expert.md`) committato con un subject che *non* contiene la parola "baldart" sfuggiva alla classificazione `chore-wrapper` (rumore) e veniva marcato `custom-overlay-able`. Quel commit resta per sempre ancestor di `HEAD` ma mai di `FETCH_HEAD`, quindi `git log FETCH_HEAD..HEAD -- .framework` lo ripesca a **ogni rilascio successivo** — e il flusso seamless si fermava sul gate `divergence-capture-incomplete` perché l'overlay (additivo) non riproduceva byte-a-byte il file `.framework`, anche quando il contenuto era già identico all'upstream e la personalizzazione viveva correttamente nell'overlay. Risultato: lo stesso commit "fantasma" rifaceva muro a ogni `update`, senza via d'uscita via overlay (riconciliare un overlay additivo non può mai far passare il round-trip stretto). **PATCH** (bugfix del detector di divergenza + reset-safety degli overlay additivi; nessun cambio di capability, nessuna chiave `baldart.config.yml`).
+
+> **Why.** Il check di fedeltà capture+verify pretendeva `merge(base_upstream, overlay) == file_.framework`. Per un overlay `extend` (additivo) questo è **strutturalmente falso** quando `.framework` è pristine-upstream: il merge aggiunge sezioni, il file no → "stale" eterno. E il classifier non distingueva un edit *vivo* (da preservare) da uno *assorbito* (contenuto già a monte → un re-sync non perde nulla). Due correzioni complementari chiudono la classe di falso positivo per tutti i consumer.
+
+### Fixed
+
+- **`src/utils/git.js` — categoria `absorbed` nel classifier di divergenza.** `classifyDivergence` ora demota a rumore (`absorbed`) ogni commit `custom-*` i cui file `.framework/` toccati sono **byte-identici all'upstream (`FETCH_HEAD`)** — confronto di blob-SHA, prefisso `.framework/` strippato per mappare il path upstream; conservativo (file fuori da `.framework/`, mancante a monte, o SHA diverso → resta drift reale). `aggregateDivergenceClass` include `absorbed` tra le `noiseCategories`, così un edit ormai assorbito non spinge più la classe verso `overlay-able`/`mixed`: la batch torna `all-noise` → auto-resolve pulito.
+- **`src/utils/overlay-capture.js` — reset-safety per overlay additivi (`captureAndVerify`).** Quando esiste già un overlay agent/command, il file `.framework` viene riconosciuto come **reset-safe** (nessun edit inline da perdere) se è pristine: (a) byte-identico alla base upstream verso cui si farebbe reset, **oppure** (b) corrisponde alla base con cui l'overlay è stato autorato (`base_file_sha` in frontmatter) — pristine anche dopo che l'upstream è andato avanti. In quel caso è `captured` (non più `stale`), invece di pretendere il round-trip stretto che un overlay additivo non può mai soddisfare. Il caso *genuinamente* stale (edit inline reale che l'overlay non riproduce) resta correttamente un blocker.
+- **Test.** `classify-divergence.test.js`: 3 fixture per `absorbed` (da solo / con merge plumbing → `all-noise`; con overlay-able genuino → `overlay-able`). `overlay-capture.test.js`: 2 fixture per la reset-safety (overlay additivo + `.framework` == base → `captured`; upstream spostato ma `.framework` pristine vs `base_file_sha` → `captured`).
+
 ## [4.16.1] - 2026-06-05
 
 **Review di allineamento `new` ↔ `new2`: 9 fix di fedeltà sui workflow `new2`/`new2-resolve` emersi da una review adversariale a 3 reviewer paralleli.** La v4.16.0 ha introdotto `new2` come variante workflow-hosted di `/new`; una review di allineamento (gate-coverage · child-workflow wiring · control-flow) ha refutato l'implementazione su difetti reali — di semantica/allineamento, non di esecuzione (il wiring tra i 3 workflow era contract-fedele). **PATCH** (bugfix di allineamento del nuovo `new2`, nessun cambio di capability, nessuna chiave `baldart.config.yml`).

package/VERSION

@@ -1 +1 @@
-4.16.1
+4.16.2

package/package.json

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

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

@@ -100,6 +100,27 @@ const AGGREGATE_FIXTURES = [
     ],
     expected: 'all-noise',
   },
+  {
+    name: 'absorbed commit alone → all-noise (content now == upstream)',
+    commits: [{ category: 'absorbed' }],
+    expected: 'all-noise',
+  },
+  {
+    name: 'absorbed + plumbing merge → all-noise (absorbed is noise)',
+    commits: [
+      { category: 'absorbed' },
+      { category: 'subtree-merge' },
+    ],
+    expected: 'all-noise',
+  },
+  {
+    name: 'absorbed + genuine overlay-able → overlay-able (absorbed excluded)',
+    commits: [
+      { category: 'absorbed' },
+      { category: 'custom-overlay-able' },
+    ],
+    expected: 'overlay-able',
+  },
 ];
 
 const PATH_FIXTURES = [

package/src/utils/__tests__/overlay-capture.test.js

@@ -20,6 +20,7 @@ const {
   buildOverlayBody, verifyCapture, kindNameFromPath, toRepoPath, captureAndVerify,
 } = require('../overlay-capture');
 const { buildFrontmatter } = require('../../commands/overlay');
+const { computeBaseFileSha } = require('../overlay-merger');
 
 const BASE = `---
 name: ui-expert
@@ -198,6 +199,55 @@ test('captureAndVerify: STALE existing agent overlay (does not reproduce edit)
   }
 });
 
+test('captureAndVerify: ADDITIVE overlay + pristine .framework (== base) → captured, not stale (Fix B)', async () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'baldart-capt-'));
+  try {
+    const fwRel = '.framework/framework/.claude/agents/ui-expert.md';
+    const fwAbs = path.join(tmp, fwRel);
+    fs.mkdirSync(path.dirname(fwAbs), { recursive: true });
+    // `.framework` is pristine upstream base — the customization lives ONLY in
+    // an additive (append-a-new-section) overlay, so reset+reapply loses
+    // nothing. The strict round-trip would call this "stale" (merge=base+append
+    // ≠ base); Fix B recognizes the pristine file as reset-safe → captured.
+    fs.writeFileSync(fwAbs, BASE);
+    const overlayAbs = path.join(tmp, '.baldart/overlays/agents/ui-expert.md');
+    fs.mkdirSync(path.dirname(overlayAbs), { recursive: true });
+    fs.writeFileSync(overlayAbs, overlayFor('\n## Mayo Stack Locks\nCSS Modules only.\n'));
+
+    const git = { git: { raw: async (a) => (a[0] === 'show' ? BASE : '') } };
+    const res = await captureAndVerify({ cwd: tmp, git, files: [fwRel], frameworkVersion: '4.16.1' });
+    assert.deepStrictEqual(res.blockers, []);
+    assert.deepStrictEqual(res.captured, ['.baldart/overlays/agents/ui-expert.md']);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('captureAndVerify: upstream moved but .framework pristine wrt overlay base_file_sha → captured (Fix B)', async () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'baldart-capt-'));
+  try {
+    const fwRel = '.framework/framework/.claude/agents/ui-expert.md';
+    const OLD = BASE;                                                   // base the overlay was authored against
+    const NEW = BASE.replace('You are a UI expert.', 'You are a UI expert (upstream v2).'); // upstream moved on
+    const fwAbs = path.join(tmp, fwRel);
+    fs.mkdirSync(path.dirname(fwAbs), { recursive: true });
+    fs.writeFileSync(fwAbs, OLD);                                       // .framework still pristine-at-OLD (no inline edit)
+    const overlayAbs = path.join(tmp, '.baldart/overlays/agents/ui-expert.md');
+    fs.mkdirSync(path.dirname(overlayAbs), { recursive: true });
+    const overlay = buildFrontmatter({
+      kind: 'agent', name: 'ui-expert', frameworkVersion: '4.16.1', baseSha: computeBaseFileSha(OLD), mode: 'extend',
+    }) + '\n## Mayo Locks\nCSS Modules only.\n';
+    fs.writeFileSync(overlayAbs, overlay);
+
+    const git = { git: { raw: async (a) => (a[0] === 'show' ? NEW : '') } }; // FETCH_HEAD base = NEW (differs from .framework)
+    const res = await captureAndVerify({ cwd: tmp, git, files: [fwRel], frameworkVersion: '4.16.1' });
+    assert.deepStrictEqual(res.blockers, []);
+    assert.deepStrictEqual(res.captured, ['.baldart/overlays/agents/ui-expert.md']);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
 test('captureAndVerify: unmappable overlay-able path (nested agent) → blocker, never silently dropped', async () => {
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'baldart-capt-'));
   try {

package/src/utils/git.js

@@ -209,12 +209,16 @@ class GitUtils {
   //   - subtree-merge:  `git subtree pull --squash` merge commits
   //   - subtree-squash: the squash payload commits themselves
   //   - chore-wrapper:  CLI-generated [CHORE]/chore(baldart): commits
+  //   - absorbed:       a would-be custom commit whose touched .framework/ files
+  //                     are now byte-identical to upstream (FETCH_HEAD) — the edit
+  //                     has been absorbed into upstream (or reset away), so a
+  //                     re-sync loses nothing. Pure history, not 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)
   //
   // Aggregate `class`:
-  //   - all-noise:    every commit is subtree-* / chore-wrapper → auto-resolve
+  //   - all-noise:    every commit is subtree-* / chore-wrapper / absorbed → auto-resolve
   //   - overlay-able: every non-noise commit is overlay-able → suggest /overlay
   //   - real-custom:  every non-noise commit is custom-other → prompt 3-way
   //   - mixed:        non-noise commits span both → prompt 3-way
@@ -293,6 +297,30 @@ class GitUtils {
     });
   }
 
+  // True when EVERY touched `.framework/` file's content at HEAD is already
+  // byte-identical to the upstream (FETCH_HEAD) blob — i.e. the commit's edit
+  // has been fully absorbed into upstream (or reset away) and a re-sync would
+  // lose nothing. Compares blob SHAs (cheap, exact). The subtree prefix
+  // `.framework/` is stripped to reach the upstream path (FETCH_HEAD has no
+  // `.framework/` prefix). Conservative: any file outside `.framework/`, missing
+  // upstream, or whose SHA differs → not absorbed (real drift, keep flagging).
+  async isAbsorbedAgainstUpstream(touched) {
+    if (!touched || !touched.length) return false;
+    const prefix = `${FRAMEWORK_DIR}/`;
+    for (const p of touched) {
+      if (!p.startsWith(prefix)) return false;
+      const upstreamPath = p.slice(prefix.length);
+      let headSha;
+      let upSha;
+      try { headSha = (await this.git.raw(['rev-parse', `HEAD:${p}`])).trim(); }
+      catch (_) { return false; }
+      try { upSha = (await this.git.raw(['rev-parse', `FETCH_HEAD:${upstreamPath}`])).trim(); }
+      catch (_) { return false; }
+      if (!headSha || headSha !== upSha) return false;
+    }
+    return true;
+  }
+
   async classifyDivergence() {
     // Inspect aheadScoped commits — those not on FETCH_HEAD that touch .framework/.
     const commits = [];
@@ -334,6 +362,15 @@ class GitUtils {
           } catch (_) { /* leave empty → custom-other */ }
           category = this.classifyCommitByPaths(touched);
         }
+        // A would-be custom commit whose touched files are now identical to
+        // upstream is absorbed history, not live drift — demote it to noise so
+        // a long-resolved local edit (e.g. one whose content later landed in or
+        // matched upstream) stops re-triggering the divergence gate on every
+        // release. Only runs for custom-* (where `touched` is populated).
+        if ((category === 'custom-overlay-able' || category === 'custom-other')
+            && await this.isAbsorbedAgainstUpstream(touched)) {
+          category = 'absorbed';
+        }
         const overlayCovered = category === 'custom-overlay-able'
           ? this.overlayCoversTouched(touched)
           : false;
@@ -353,7 +390,7 @@ class GitUtils {
   // (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 noiseCategories = new Set(['subtree-merge', 'subtree-squash', 'chore-wrapper', 'absorbed']);
     const nonNoise = commits.filter((c) => !noiseCategories.has(c.category));
     if (nonNoise.length === 0) return 'all-noise';
     const hasOverlayable = nonNoise.some((c) => c.category === 'custom-overlay-able');

package/src/utils/overlay-capture.js

@@ -181,6 +181,26 @@ async function captureAndVerify({ cwd, git, files, frameworkVersion }) {
       let overlayContent;
       try { overlayContent = fs.readFileSync(overlayAbs, 'utf8'); }
       catch (_) { blockers.push({ file, reason: 'existing overlay unreadable' }); continue; }
+
+      // Reset-safety shortcut: when the `.framework/` file carries NO inline
+      // edit to lose, a reset+re-apply preserves everything (the customization
+      // lives in the overlay and is re-applied). Two pristine signals:
+      //   (a) it is byte-identical to the upstream base we'd reset to, or
+      //   (b) it matches the base the overlay was authored against
+      //       (`base_file_sha`) — pristine even after upstream moved on.
+      // This is what makes an ADDITIVE (extend) overlay survive: the strict
+      // round-trip below would otherwise demand merge(base, overlay) == file,
+      // which never holds when the overlay only appends — flagging a perfectly
+      // healthy overlay as "stale" on every release.
+      const overlayBaseSha = (/^\s*base_file_sha\s*:\s*"?([a-f0-9]+)"?/m.exec(overlayContent) || [])[1];
+      const editedPristine =
+        norm(editedContent) === norm(baseContent)
+        || (overlayBaseSha && computeBaseFileSha(editedContent) === overlayBaseSha);
+      if (editedPristine) {
+        captured.push(overlayRel);
+        continue;
+      }
+
       if (verifyCapture({ kind: kn.kind, name: kn.name, baseContent, overlayContent, editedContent, frameworkVersion })) {
         captured.push(overlayRel);
       } else {