baldart 4.16.0 → 4.16.2

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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`).
+
+> **Why.** `new2` deve essere un A/B equo di `/new`: ogni gate va mappato con policy *fedele* alla semantica di `/new` (meno l'AskUserQuestion), e tutti i path/child-workflow vanno cablati. La review ha trovato punti dove la policy deterministica divergeva silenziosamente dalla SSOT o dove un segnale veniva letto ma non agito.
+
+### Fixed
+
+- **`framework/.claude/workflows/new2.js`**:
+  - **Final review `NEEDS_MANUAL_CONFIRMATION` non più ignorato** — il filtro blocker includeva solo `VERIFIED` mentre il commento dichiarava "treat as VERIFIED": ora include anche `NEEDS_MANUAL_CONFIRMATION` (tentato il fix, mai scartato in silenzio → ripristina l'invariante zero-drop di `final-review.md` F.4).
+  - **`status:'fatal'` di `new2-resolve` ora onorato** — `resolve()` setta `batchFatal` e sospende final review + merge, invece di degradarlo a `followup`.
+  - **Phase 7 Production Readiness aggiunta** (post-merge, non-bloccante) — ripristina la full-parity dichiarata (auto-esegue i deploy stack-matched, riporta gli item manuali).
+  - **Card crashata non più persa** — il catch del driver passa da `resolve('agent-crash')` (retry specialista, mai bypass su security/migration) e garantisce un follow-up tracciato (path `agent-crash` prima irraggiungibile).
+  - **G3 cross-card / G5 depends-on rafforzati** — il prompt pre-flight ora *applica* le azioni cross-card (force-sequential/warning in executionMode/groups), non le logga soltanto; G5 garantisce l'esclusione **transitiva** dei dipendenti.
+  - **Minori**: `fileDiffViolation` (E4) ora loggato nel gate ledger; `hasApiDataFiles` non più sempre-true (rimosso il disgiunto che rendeva irraggiungibile lo skip dell'api-perf-auditor); i resolve di `merge-blocker`/`qa-fail` passano `mayEditPaths` (confine ownership sui fix batch-wide).
+- **`framework/.claude/workflows/new2-resolve.js`**: obbligo esplicito di **re-run E2E (Phase 2.6)** quando un fix tocca file UI (app/components/`*.css`/`*.scss`), allineato a `codex-gate.md` step 6.
+
 ## [4.16.0] - 2026-06-05
 
 **Nuova skill sperimentale `new2` + i workflow `new2`/`new2-resolve`: l'INTERA batch di `/new` può girare come un singolo dynamic workflow autonomo in background, per fare A/B testing sul context economy.** `/new` è una skill che gira nel main loop, quindi l'output di ogni subagent (architect, coder, reviewer, Codex, QA, E2E) gonfia il contesto dell'orchestrator — il driver di costo che si sposta d'asse a ogni fix (v4.12→v4.15). I dynamic workflow spostano l'orchestrazione in un runtime **isolato**: i risultati intermedi vivono in variabili di script e nel main loop torna **solo il report finale**. `new2` è la versione workflow-hosted di `/new`, **parallela e additiva** (NON sostituisce `/new`), pensata per misurare il delta di `usage` reale a parità di semantica. **MINOR** (nuova skill + 2 workflow, opt-in, Claude-only; nessun breaking change, nessuna chiave `baldart.config.yml` — il gating è runtime via presenza del tool `Workflow`, come v4.14.0).

package/VERSION

@@ -1 +1 @@
-4.16.0
+4.16.2

package/framework/.claude/workflows/new2-resolve.js

@@ -67,6 +67,7 @@ const brief = [
   `Scope files for re-verify: ${scopeFiles.join(', ') || '(diff)'}`,
   `Domain: ${domain}${protectedDomain ? ' (PROTECTED — security/migration: never inline-bypass; the right specialist MUST apply)' : ''}`,
   `Reference modules (Read for exact semantics): ${REF}/`,
+  `UI re-verify obligation: if your fix touches a UI file (app dir / components / *.css / *.scss), you MUST re-run the Phase 2.6 E2E review (per ${REF}/review-cycle.md) before declaring verified — a code-review/Codex fix can reintroduce visual/functional drift (mirrors codex-gate.md step 6).`,
 ].join('\n')
 
 // The agent that OWNS a fix in this domain (Domain-Override): doc → doc-reviewer.

package/framework/.claude/workflows/new2.js

@@ -7,6 +7,7 @@ export const meta = {
     { title: 'Implement', detail: 'per-card implement+review pipeline; team-mode runs coders in parallel per wave' },
     { title: 'Final', detail: 'cross-batch final review (delegates to new-final-review)' },
     { title: 'Merge', detail: 'auto-merge to trunk via git.merge_strategy + cleanup' },
+    { title: 'Production', detail: 'post-merge production-readiness checklist (Phase 7, non-blocking)' },
   ],
 }
 
@@ -46,6 +47,8 @@ const firstCard = cardIds[0] || 'BATCH'
 const gateLedger = []       // { card, gate, decision, detail }
 const residualFollowups = []// { card, kind, followupCard, reason }
 const perCardResults = []   // structured per-card outcome
+let batchFatal = false      // set when a resolve() returns 'fatal' (unrecoverable)
+let prodReadiness = null    // Phase 7 result (post-merge, non-blocking)
 
 function ledger(card, gate, decision, detail) {
   gateLedger.push({ card, gate, decision, detail: detail || '' })
@@ -120,9 +123,9 @@ const preflight = await agent(
     `DETERMINISTIC GATE POLICIES (NO user prompts):\n` +
     `• G1 dirty-tree (main repo ${MAIN}): partition framework-managed noise exactly as setup.md step 3 ($METRICS=${METRICS}, .baldart/generated|state.json|skill-conflicts.json — NOT overlays/). If genuine user work remains → auto-stash 'baldart-new2-${firstCard}-<ts>' (main checkout, safe) and record the MESSAGE label for restore at merge. Never commit/abort/prompt.\n` +
     `• G2 divergence vs origin/${TRUNK}: behind-only AND HEAD==${TRUNK} → ff-pull; ahead-genuine or diverged → DO NOT push/rebase/reset; proceed (the worktree is isolated) and put a one-line note in workspaceNote. Framework-management commits are auto-ignored (setup.md step 4 reclassification).\n` +
-    `• G3 cross-card grounding (setup.md 3d): run the Codex cross-card check with the provenance skip; on CODEX_NOT_FOUND fall back to code-reviewer; if BOTH unavailable → proceed and set crossCard='CAPABILITY_UNAVAILABLE'. Read the audit file ONLY via the [codex]-stripping filter; return DISTILLED findings.\n` +
+    `• G3 cross-card grounding (setup.md 3d): run the Codex cross-card check with the provenance skip; on CODEX_NOT_FOUND fall back to code-reviewer; if BOTH unavailable → proceed and set crossCard='CAPABILITY_UNAVAILABLE'. Read the audit file ONLY via the [codex]-stripping filter; return DISTILLED findings. CRITICAL — if conflicts are FOUND you MUST APPLY them, not just report: FILE_CONFLICT / ORDER_RISK → force the conflicting cards SEQUENTIAL (encode this in executionMode/groups AND the ownership map); STATE_MUTATION → fold a warning into the affected cards via the ownership map. The returned executionMode/groups MUST already reflect these constraints.\n` +
     `• G4 card-field validation (setup.md 1b/1c): a card missing requirements/acceptance_criteria/files_likely_touched → EXCLUDE it (add to excluded[] with reason); continue with valid cards. Never HALT the batch for one bad card.\n` +
-    `• G5 depends-on (implement.md Phase 1 step 2): if a card's depends_on names a card that is NOT DONE and is NOT in this batch → exclude that card AND its in-batch dependents (excluded[], reason 'depends_on <dep> not DONE'). If the dep IS in this batch, keep it and ensure ordering.\n` +
+    `• G5 depends-on (implement.md Phase 1 step 2): if a card's depends_on names a card that is NOT DONE and is NOT in this batch → exclude that card AND, TRANSITIVELY, every in-batch card that depends on it (excluded[], reason 'depends_on <dep> not DONE'). GUARANTEE: the returned cards[] must contain NO card that transitively depends on an excluded card. If the dep IS in this batch, keep it and order it first.\n` +
     `• Worktree (setup.md step 4): create ONE code worktree off ${TRUNK} (slug from git_strategy.branch or the parent/lead card title), install deps, assign a port, run the baseline (tsc+lint+build). Use the git-authoritative idempotency pre-check (step 4a2). E2: if baseline FAILS, fix-attempt once (the trunk itself may not build); if still failing return baseline:'fail' with baselineLog (the caller treats it as batch-fatal).\n` +
     `• Complexity (setup.md 3c): decide executionMode sequential|team and, for team, the groups [{level,cards}]. Build the file-ownership map; write it to /tmp and return ownershipMapPath.\n` +
     `• Persist per-card architecture baselines you gather to /tmp/arch-baseline-<CARD>.md and return archBaselinePaths (final review reuses them).\n\n` +
@@ -165,6 +168,7 @@ async function resolve(kind, card, evidence, extra) {
     config: cfg,
   }).catch((e) => ({ status: 'followup', reason: 'resolve workflow error: ' + (e && e.message) }))
   const status = (res && res.status) || 'followup'
+  if (status === 'fatal') { batchFatal = true; ledger(card, 'resolve:' + kind, 'FATAL', (res && res.reason) || ''); return status }
   if (status === 'followup' && res && res.followupCard) {
     residualFollowups.push({ card, kind, followupCard: res.followupCard, reason: res.reason || '' })
   }
@@ -172,6 +176,15 @@ async function resolve(kind, card, evidence, extra) {
   return status
 }
 
+// A crashed runCard (E1) routes through new2-resolve(agent-crash) for a specialist
+// retry, then ALWAYS lands as a tracked followup — never a silent drop.
+async function crashFollowup(id, e) {
+  const msg = String(e && e.message)
+  const s = await resolve('agent-crash', id, 'runCard crashed: ' + msg, { mayEditPaths: [], scopeFiles: [] })
+  if (s !== 'followup') residualFollowups.push({ card: id, kind: 'agent-crash', followupCard: '(specialist retry attempted — manual check)', reason: msg })
+  return { card: id, status: 'followup', gates: [{ gate: 'runCard', decision: 'ERROR', detail: msg }], commit: '-', telemetry: {} }
+}
+
 // ───────────────────────────────────────────────────────────────────────────
 // Per-card pipeline — sequences /new Phases 1→4 via agents that Read the modules.
 // Each phase agent returns a structured verdict; this function applies the
@@ -200,6 +213,7 @@ async function runCard(cardId, cardPath, lessons) {
 
   const mayEdit = (impl && impl.mayEditPaths) || []
   const scopeFiles = (impl && impl.scopeFiles) || []
+  if (impl && impl.fileDiffViolation) g('E4-file-diff', 'AUTO-REVERTED', 'coder touched files outside ownership — reverted per implement.md 11b')
 
   // G26 — build gates not converging → self-heal.
   if (impl && impl.buildBlocked) {
@@ -291,13 +305,13 @@ if (preflight.executionMode === 'team' && Array.isArray(preflight.groups) && pre
     const ids = (grp.cards || []).filter((id) => runnableCards.includes(id))
     if (!ids.length) continue
     log(`Team wave level=${grp.level}: ${ids.length} card(s) in parallel.`)
-    const waveResults = await parallel(ids.map((id) => () => runCard(id, pathById[id], lessons).catch((e) => ({ card: id, status: 'followup', gates: [{ gate: 'runCard', decision: 'ERROR', detail: String(e && e.message) }], commit: '-', telemetry: {} }))))
+    const waveResults = await parallel(ids.map((id) => () => runCard(id, pathById[id], lessons).catch((e) => crashFollowup(id, e))))
     for (const r of waveResults.filter(Boolean)) { perCardResults.push(r); if (r.note) lessons.push(`${r.card}: ${r.note}`) }
   }
 } else {
   // Sequential — cards share one worktree and run one at a time.
   for (const id of runnableCards) {
-    const r = await runCard(id, pathById[id], lessons).catch((e) => ({ card: id, status: 'followup', gates: [{ gate: 'runCard', decision: 'ERROR', detail: String(e && e.message) }], commit: '-', telemetry: {} }))
+    const r = await runCard(id, pathById[id], lessons).catch((e) => crashFollowup(id, e))
     perCardResults.push(r)
     if (r && r.note) lessons.push(`${r.card}: ${r.note}`)
   }
@@ -313,12 +327,12 @@ const committed = perCardResults.filter((r) => r.status === 'committed')
 // ───────────────────────────────────────────────────────────────────────────
 phase('Final')
 let finalSummary = null
-let mergeBlocked = false
-if (committed.length) {
+let mergeBlocked = batchFatal
+if (committed.length && !batchFatal) {
   const reviewScopeFiles = dedupe(committed.flatMap((r) => r.scopeFiles || []))
   const archPaths = committed.map((r) => r.archBaselinePath).filter(Boolean)
   const allArch = archPaths.length === committed.length ? archPaths : null
-  const hasApiDataFiles = reviewScopeFiles.some((f) => /api\/|data-model|\.sql$|migrations?\//i.test(f)) || reviewScopeFiles.length > 0
+  const hasApiDataFiles = reviewScopeFiles.some((f) => /api\/|data-model|\.sql$|migrations?\//i.test(f))
 
   const final = await workflow('new-final-review', {
     firstCardId: firstCard,
@@ -334,21 +348,23 @@ if (committed.length) {
   if (final) {
     finalSummary = final.summary || null
     ledger(firstCard, 'final-review', 'DONE', `engine=${final.codexEngine}; verified=${final.summary ? final.summary.verified : '?'}`)
-    // G18 — apply verified BLOCKER/HIGH fixes; unresolved → block merge.
-    const blockers = (final.findings || []).filter((f) => f.classification === 'VERIFIED' && (f.severity === 'BLOCKER' || f.severity === 'HIGH'))
+    // G18 — apply BLOCKER/HIGH fixes; unresolved → block merge. G17: a workflow
+    // cannot ask the user, so NEEDS_MANUAL_CONFIRMATION is treated as VERIFIED
+    // (attempt the fix) — never silently ignored (the count-only path was the bug).
+    const blockers = (final.findings || []).filter((f) => (f.classification === 'VERIFIED' || f.classification === 'NEEDS_MANUAL_CONFIRMATION') && (f.severity === 'BLOCKER' || f.severity === 'HIGH'))
     for (const f of blockers) {
-      const s = await resolve('merge-blocker', f.finding_id || firstCard, `${f.severity} ${f.title}: ${f.evidence}`, { scopeFiles: reviewScopeFiles, domain: f.domain || 'code' })
+      const s = await resolve('merge-blocker', f.finding_id || firstCard, `${f.classification} ${f.severity} ${f.title}: ${f.evidence}`, { mayEditPaths: reviewScopeFiles, scopeFiles: reviewScopeFiles, domain: f.domain || 'code' })
       if (s !== 'resolved') mergeBlocked = true
     }
     if ((final.summary && final.summary.failingGates && final.summary.failingGates.length)) {
-      const s = await resolve('qa-fail', firstCard, `final gates failing: ${final.summary.failingGates.join(', ')}`, { scopeFiles: reviewScopeFiles, domain: 'code' })
+      const s = await resolve('qa-fail', firstCard, `final gates failing: ${final.summary.failingGates.join(', ')}`, { mayEditPaths: reviewScopeFiles, scopeFiles: reviewScopeFiles, domain: 'code' })
       if (s !== 'resolved') mergeBlocked = true
     }
   } else {
     ledger(firstCard, 'final-review', 'SKIPPED', 'workflow returned null')
   }
 } else {
-  ledger(firstCard, 'final-review', 'SKIPPED', 'no committed cards')
+  ledger(firstCard, 'final-review', 'SKIPPED', batchFatal ? 'batch fatal — review/merge halted' : 'no committed cards')
 }
 
 // ───────────────────────────────────────────────────────────────────────────
@@ -372,6 +388,22 @@ if (!committed.length) {
   if (mergeResult && mergeResult.reconciliation) ledger(firstCard, 'G19-23-reconcile', 'AUTO', mergeResult.reconciliation)
 }
 
+// ───────────────────────────────────────────────────────────────────────────
+// Phase Production (Phase 7) — post-merge readiness checklist (non-blocking, full
+// parity with /new). Auto-executes stack-matched deploys; reports the manual items.
+// ───────────────────────────────────────────────────────────────────────────
+phase('Production')
+if (mergeResult && mergeResult.merged) {
+  prodReadiness = await agent(
+    `Run the post-merge Production Readiness checklist per ${REF}/production-readiness.md (Phase 7) over the batch's changed files. Auto-EXECUTE only stack-matched index / access-rule / cron deploys; REPORT (do not execute) env vars, feature flags, DB migrations, third-party secrets, DNS changes. NON-BLOCKING — never fail the batch.\n\n${projectBrief}\nChanged files: ${dedupe(committed.flatMap((r) => r.filesChanged || [])).join(', ') || '(derive from git)'}\n\nReturn: { autoExecuted:[...], manualItems:[...], note }`,
+    { label: 'production-readiness', phase: 'Production', agentType: 'general-purpose',
+      schema: { type: 'object', required: ['manualItems'], additionalProperties: true, properties: { autoExecuted: { type: 'array', items: { type: 'string' } }, manualItems: { type: 'array', items: { type: 'string' } }, note: { type: 'string' } } } }
+  )
+  ledger(firstCard, 'phase7-production', 'DONE', `auto=${((prodReadiness && prodReadiness.autoExecuted) || []).length} manual=${((prodReadiness && prodReadiness.manualItems) || []).length}`)
+} else {
+  ledger(firstCard, 'phase7-production', 'SKIPPED', 'not merged')
+}
+
 // ───────────────────────────────────────────────────────────────────────────
 // Return — assemble the report + Phase-8 telemetry (variant new2).
 // ───────────────────────────────────────────────────────────────────────────
@@ -421,8 +453,14 @@ function buildReport(o) {
   }
   L.push(``, `## Merge`)
   if (mergeResult && mergeResult.merged) L.push(`Merged → ${TRUNK} @ ${mergeResult.mergeCommit || '?'}${mergeResult.reconciliation ? ' · ' + mergeResult.reconciliation : ''}`)
-  else if (mergeBlocked) L.push(`Merge BLOCKED — unresolved final BLOCKER/HIGH. Worktree left intact at ${sharedCtx.worktreePath}.`)
+  else if (mergeBlocked) L.push(`Merge BLOCKED — ${batchFatal ? 'batch fatal (new2-resolve)' : 'unresolved final BLOCKER/HIGH'}. Worktree left intact at ${sharedCtx.worktreePath}.`)
   else L.push(`Not merged (no committed cards or incomplete).`)
+  if (prodReadiness) {
+    const man = prodReadiness.manualItems || []
+    L.push(``, `## Production readiness (Phase 7)`)
+    L.push(`Auto-eseguiti: ${(prodReadiness.autoExecuted || []).length} · Da fare a mano: ${man.length}`)
+    for (const m of man) L.push(`- [ ] ${m}`)
+  }
   if (residualFollowups.length) {
     L.push(``, `## ⚠️ Follow-up auto-creati (residui non risolti autonomamente — nulla perso)`)
     for (const f of residualFollowups) L.push(`- **${f.followupCard}** ← ${f.card} (${f.kind})${f.reason ? ': ' + f.reason : ''}`)

package/package.json

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