baldart 4.16.1 → 4.17.0

package/framework/docs/WORKFLOWS.md

@@ -14,8 +14,8 @@ workflows are unavailable behaves exactly as before.
 | Workflow | Used by | What it does |
 | :--- | :--- | :--- |
 | `new-final-review` | `/new` Final Review (Step F.1.5) | Runs the read-only cross-batch review fan-out — architecture baseline + Codex ‖ doc-reviewer ‖ api-perf-cost-auditor ‖ qa-sentinel — then adversarially verifies low-confidence findings and returns them classified. Applies no fixes (the skill owns fix application + user gates). |
-| `new2` (v4.16.0) | `/new2` skill (the whole batch) | **EXPERIMENTAL A/B variant of `/new`.** Hosts the ENTIRE batch orchestration — pre-flight, per-card implement+review pipeline (sequential or team-mode parallel coders), final review (delegates to `new-final-review`), and auto-merge — in the background runtime, so subagent output never enters the main context. Fully autonomous: every `/new` `AskUserQuestion` gate is a deterministic policy; blocking gates / scope-expanding findings route to `new2-resolve`. Agents Read `/new`'s reference modules for semantics, so the script encodes only orchestration shape + gate policy. |
-| `new2-resolve` (v4.16.0) | `new2` (self-healing) | Resolution pass invoked by `new2` for any gate that would otherwise need a human: card fail/blocker, scope-EXPANDING finding, or cross-cutting edge (agent-crash, baseline-fail). Runs targeted fix → judged multi-attempt → adversarial re-verify; its terminal auto-materialises a tracked follow-up card so nothing is silently dropped. Domain-Override aware (doc→doc-reviewer; security/migration never inline-bypassed). |
+| `new2` (v4.17.0) | `/new2` skill (the whole batch) | **EXPERIMENTAL A/B variant of `/new`.** Hosts the ENTIRE batch in the background runtime so subagent output never enters the main context. **v4.17.0 hardening (single-wave):** a **dependency-gated DAG scheduler** runs a card only when all in-batch deps are *committed* (and blocks transitive dependents of a failed dep instead of routing them to resolve); each card uses its **owner_agent** + a **specialized review fan-out** (not general-purpose); the worktree is kept **atomic per card** (rollback-to-HEAD on failure); transient API errors are retried and a sustained **outage degrades cleanly** (`degraded` return + durable resume via the skill); a **run ledger** dedups resolves and records accepted deferrals (no re-routing loop); the **merge is integrity-gated** (never force-DONE, never `git add` unreviewed code, never merge an incomplete/degraded batch); mechanical steps (commit / follow-up) run on **Haiku**; telemetry carries real **cost** (`total_tokens` via `budget.spent()`, `agent_count`, skill-stamped `wall_clock_s`) + `degraded`. Agents Read `/new`'s reference modules for semantics. |
+| `new2-resolve` (v4.17.0) | `new2` (self-healing) | Resolution pass for any gate that would otherwise need a human. **v4.17.0:** a **terminal short-circuit** skips the costly multi-attempt when the problem is impossible-by-definition (`out-of-ownership` verified in JS; other terminal reasons ratified by a judge); a **MANDATORY adversarial judge** cross-checks every `verified` claim — the judge independently greps the files and the workflow verifies they fall inside MAY-EDIT (defeats fabricated success); accepts a **batched `findings` list** (one resolve per fix-area); domain-specialized fixer + judge (doc→doc-reviewer, ui→ui-expert, security→security-reviewer judge, perf→api-perf-cost-auditor judge); incidental out-of-scope findings are surfaced (not dropped); follow-up materialisation is offline-safe (deferred to the skill if no agent can write). |
 
 > **`new2` is an experiment, not a replacement.** It exists to A/B-test the
 > context-economy of workflow-hosting `/new`. `/new` remains the SSOT, the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.16.1",
+  "version": "4.17.0",
   "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 {