baldart 3.28.2 → 3.29.0

package/CHANGELOG.md

@@ -5,6 +5,57 @@ 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).
 
+## [3.29.0] - 2026-05-29
+
+Closes a two-part process gap in `npx baldart update` reported from a non-TTY agent context on a shared consumer repo: (1) plumbing/collaboration merge commits were mislabeled `custom-other`, downgrading an otherwise overlay-able divergence set into `mixed`; (2) an automated agent had **no** non-destructive path to complete an update when the consumer carried local `.framework/` commits — `--yes` refused, the interactive prompt needed a TTY, and `--reset` is gated on a clean working tree. **No new `baldart.config.yml` keys** — `--on-divergence` is a CLI flag, not a config flag, so the schema-propagation rule does not apply.
+
+### Fixed — divergence classifier no longer poisoned by merge commits
+
+- **[src/utils/git.js](src/utils/git.js)** `classifyDivergence()`: merge commits are now detected **structurally by parent count** (`%P` in the `git log` format → `parents.length >= 2`) instead of relying solely on the brittle subject regex `^Merge … into <branch>$`. That regex missed real `git subtree pull --squash` merges that present as a bare `Merge commit '<sha>'` (git omits the `into <branch>` suffix when the merge lands on `master`) and shared-repo collaboration merges shaped like `Merge branch 'x' of <url> into <branch>` / `Merge remote-tracking branch '…'`. Such merges fell through to the path classifier, which returns `custom-other` for the empty diff-tree of a merge — collapsing an `overlay-able` set into `mixed` and hiding the overlay-migration option. Merges are now labeled `subtree-merge` (noise) and excluded before the aggregate decision.
+- **[src/utils/git.js](src/utils/git.js)**: aggregation extracted to a pure, unit-testable static `GitUtils.aggregateDivergenceClass(commits)`. Each divergence commit record now also carries `parents` and `touched` (the latter reused by the new overlay-scaffold flow below).
+- **[src/utils/__tests__/classify-divergence.test.js](src/utils/__tests__/classify-divergence.test.js)**: +9 fixtures — bare-merge / `of <url>` / remote-tracking subjects (documenting the regex blind spot now covered by parent count) and an `aggregateDivergenceClass` suite asserting `overlay-able + plumbing-merge → overlay-able` (not `mixed`).
+
+### Added — `--on-divergence` non-interactive escape hatch for agents / CI
+
+- **[src/commands/update.js](src/commands/update.js)** + **[bin/baldart.js](bin/baldart.js)**: `npx baldart update --on-divergence <strategy>` resolves a divergent update without a TTY:
+  - `scaffold-overlays` → auto-creates overlay skeleton(s) for the overlay-able framework files touched by the divergent commits (reusing `overlay.scaffoldFile`), then stops so the edits can be filled in and the update re-run. For `mixed`, scaffolds the overlay-able subset and refuses to pull while `custom-other` commits remain (would be destructive).
+  - `pull` → keeps the commits and lets the subtree pull create a merge (non-destructive; conflicts are surfaced, never auto-resolved). Works for `overlay-able`, `mixed`, and `real-custom`.
+  - `abort` → explicit no-op.
+- Bare `--yes` on a divergent class still refuses (nothing destructive by accident) but now prints the exact flag to re-run with instead of dead-ending.
+
+### Changed — interactive `overlay` choice now actually scaffolds
+
+- **[src/commands/update.js](src/commands/update.js)**: the interactive "migrate to overlay" option previously printed *"run `/overlay` then re-run"* and exited (a no-op). It now scaffolds the overlay skeleton(s) in-place via `overlay.scaffoldFile` and points the user to `/overlay` for guided filling.
+- **[src/commands/overlay.js](src/commands/overlay.js)**: extracted a non-exiting `scaffoldFile(cwd, target, options)` (returns a structured result) from the `process.exit`-driven `scaffold()` CLI wrapper, so it can be called in a loop from `update` without a single missing/existing overlay terminating the run. Exported alongside `parseTarget`.
+
+### Changed — `/baldart-update` skill narration synced
+
+- **[framework/.claude/skills/baldart-update/SKILL.md](framework/.claude/skills/baldart-update/SKILL.md)**: documents the parent-count merge detection and the new `--on-divergence` strategies; corrects the stale "real user-custom commits ABORT in --yes mode" claim.
+
+## [3.28.3] - 2026-05-28
+
+Release B of the 3-release plan on `/new` fix-application authority. Closes two inline-apply violation patterns observed in real `/new` runs (doc fixes applied by the orchestrator instead of delegated to coder; Codex HIGH security findings written inline) and shuts the structural loophole in `SKILL.md`'s sub-agent failure protocol that was being used to bypass delegation even when no agent had crashed. Telemetry from v3.28.2 will measure the effectiveness of these changes; Release C (conditional threshold rule) waits for that data.
+
+### Added — Domain-Override Domains sub-section
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)**: new sub-section under "Fix Application Log Schema" enumerates tassativamente the domains where inline orchestrator apply is **never** safe, regardless of patch size: `doc` (any `*.md` under references/, prd/, root CHANGELOG, ssot-registry), `security` (Phase 3.7 detector Triggers #2/#3 + SQL RLS policy mutations), `migration` (`supabase/migrations/*.sql` or `${paths.migrations_dir}`). The coder agent's system prompt + project overlay enforces invariants (freshness, tabular formatting, RLS structure) that orchestrator inline edits routinely break. Edge case explicit: mechanical CHANGELOG / ssot-registry append-a-row stays `doc` (uniformity > spawn cost).
+
+### Changed — Phase 3 doc delegation reinforced
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)** Phase 3 step 15: explicit chiosa "Doc fixes are NEVER applied inline by the orchestrator, regardless of size or perceived triviality" added below the existing coder-spawn instruction. The rule already existed (line 1116, pre-v3.28.2: "invoke the coder agent once") but was being bypassed in practice — the chiosa makes the rule non-discretionary.
+
+### Changed — Phase 3.7 coder applies Codex patches verbatim
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)** Phase 3.7 step 4 sub-bullet "spawn coder": coder now receives the report path + list of VERIFIED bugs **plus the patches Codex suggested inline in the report**, and applies them verbatim. The coder does NOT re-do the analysis, does NOT re-grep, does NOT re-read files extensively. Codex has already produced both the diagnosis and the patch; the coder's value-add is the right system prompt (project conventions, naming, testing patterns), not redoing security/correctness review. Saves an estimated 5-10k tokens per Codex-driven coder spawn.
+
+### Changed — Sub-agent failure protocol (loophole closed)
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)** "Sub-agent failure protocol" section: replaced single bullet "attempt the work yourself directly" with a 4-step protocol. (1) log failure with full trace, (2) retry once (transient errors are common), (3) **if domain-override (doc / security / migration) and retry still fails: STOP and AskUserQuestion — never inline-fallback for these domains**, (4) non-override domains may fall back inline but MUST log `applied_by=orchestrator-fallback` for telemetry visibility. Razionale: the pre-v3.28.3 wording was being used as a shortcut to bypass delegation rules even when no agent had crashed; closing that defeats the violation pattern at the structural level.
+
+### Rationale
+
+Release B addresses 4 of the 17 critiques raised in the adversarial review of the original threshold-rule plan (#4-5 domain override definition, #7 Codex re-analysis ridondante, #10 escape valve aperta). The remaining critiques are either addressed by Release A telemetry, deferred to conditional Release C, or accepted as design trade-offs documented in the plan file. **No new `baldart.config.yml` keys** — domain-override is enforced by content/path matching, not by config flag (KISS).
+
 ## [3.28.2] - 2026-05-28
 
 Telemetry-only release. Adds structured logging for fix-application decisions in `/new` Phases 2.55 / 3 / 3.5 / 3.7. **Zero behavior change** — the orchestrator's decisions remain identical to v3.28.1. The goal is to measure, with real data, whether the per-phase delegation rules need to change in a future release.

package/VERSION

@@ -1 +1 @@
-3.28.2
+3.29.0

package/bin/baldart.js

@@ -72,6 +72,7 @@ program
   .option('--auto-stash', 'When the working tree is dirty, stash automatically instead of prompting.')
   .option('--reset', 'Nuclear option: rm -rf .framework/ + fresh install, preserving baldart.config.yml + .baldart/ + custom .claude/{agents,skills,commands}/. Requires clean working tree.')
   .option('--i-know', 'Acknowledges --reset will wipe untracked/ignored files inside .framework/ (required to use --reset --yes).')
+  .option('--on-divergence <strategy>', 'Non-interactive resolution when the consumer has local commits on .framework/ (for agents / CI): "scaffold-overlays" (auto-create overlay skeletons, then stop), "pull" (keep commits + merge — non-destructive), or "abort".')
   .action(async (options) => {
     const updateCommand = require('../src/commands/update');
     await updateCommand(options);

package/framework/.claude/skills/baldart-update/SKILL.md

@@ -139,7 +139,7 @@ post-flight assert:
 - **Hooks drift**: missing hooks auto-registered silently; only command-level drift prompts (and only if interactive).
 - **Schema config drift**: surfaces as a warning post-update; never blocks.
 - **BALDART-managed auto-commit**: `--yes` commits silently with `chore(baldart):` subject.
-- **Subtree-merge / chore divergence commits**: classified by the CLI; auto-resolved silently when `all-noise`, prompts only for `overlay-able` / `real-custom` / `mixed`.
+- **Subtree-merge / chore divergence commits**: classified by the CLI (merges detected by parent count, so plumbing/collaboration merges never poison the class); auto-resolved silently when `all-noise`, prompts for `overlay-able` / `real-custom` / `mixed` — or resolve non-interactively with `--on-divergence scaffold-overlays|pull|abort`.
 - **CLI self-upgrade**: transparent relaunch via `npx baldart@latest` when global CLI is stale.
 
 > **IMPORTANT — do NOT use `git -C .framework fetch`.** `.framework/` is a git
@@ -272,10 +272,21 @@ Do NOT pass `--auto-stash` (redundant with `--yes`).
   files it touched during the reconcile with `chore(baldart): post-update
   reconcile to vX.Y.Z`. User-owned files are never staged.
 - **Subtree-merge / chore divergence commits**: when the consumer has
-  local commits that are just `git subtree pull` plumbing or CLI-generated
-  `[CHORE]` commits, the CLI auto-resolves silently. Real user-custom
-  commits ABORT in `--yes` mode (the user must re-run without `--yes` to
-  choose).
+  local commits that are just `git subtree pull` plumbing, ordinary
+  collaboration merges (detected by parent count, not just subject), or
+  CLI-generated `[CHORE]` commits, the CLI auto-resolves silently. Real
+  user-custom commits do NOT auto-resolve under bare `--yes` — but an agent
+  is no longer dead-ended: pass `--on-divergence` to resolve non-interactively
+  (since v3.29.0):
+  - `--on-divergence scaffold-overlays` → auto-creates overlay skeleton(s)
+    for the overlay-able commits, then stops so the edits can be filled in
+    (then re-run update). Use this when the divergence is `overlay-able`.
+  - `--on-divergence pull` → keeps the commits and lets the subtree pull
+    create a merge (non-destructive; resolve any conflicts that surface).
+    Works for `overlay-able`, `mixed`, and `real-custom`.
+  - `--on-divergence abort` → explicit no-op.
+  Bare `--yes` without a strategy still refuses (and now prints exactly which
+  flag to re-run with), so nothing destructive happens by accident.
 - **CLI self-upgrade**: if the global CLI is older than npm latest, the
   update transparently relaunches itself via `npx baldart@latest update
   --yes`. Loop-guarded by `BALDART_RELAUNCHED=1`.

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

@@ -961,6 +961,22 @@ Every fix-application decision in Phases 2.55 / 3 / 3.5 / 3.7 appends one row to
 
 **Cost**: ~80-120 bytes per row, ~5-15 rows per card. Negligible context impact, large analytical value.
 
+#### Domain-Override Domains (since v3.28.3)
+
+Some fix domains are **never** safe for inline orchestrator apply, regardless of size. The coder agent's system prompt + project overlay enforces invariants (doc freshness, tabular formatting, RLS policy structure, migration ordering) that orchestrator inline edits routinely break. The orchestrator MUST delegate every fix in these domains to `coder`, even when the patch is a one-liner.
+
+Enumerated tassativamente:
+
+| Domain | Match rule |
+|---|---|
+| `doc` | File path matching `*.md` under `${paths.references_dir}`, `${paths.prd_dir}`, project root `CHANGELOG.md`, or any `ssot-registry.md`. |
+| `security` | File path matching the Phase 3.7 detector Triggers #2 (auth/permissions: `src/lib/auth/middleware.ts`, `src/lib/permissions.ts`, anything matching `withAuth`) or #3 (payments: `^src/lib/payments/`, `^src/app/api/v1/billing/`). Also any SQL migration whose content matches `CREATE POLICY|ALTER POLICY|DROP POLICY` (RLS policy mutations). |
+| `migration` | File path matching `supabase/migrations/*.sql` (or `${paths.migrations_dir}/*.sql` if defined in `baldart.config.yml`). |
+
+**Edge case explicit** — a mechanical append-a-row update to `CHANGELOG.md` or `ssot-registry.md` is still classified `doc` and still goes through coder. The uniformity of the rule matters more than the cost of the individual spawn. If telemetry from Release A shows that doc-mechanical-append is a large fraction of doc coder spawns, a sub-domain `doc-mechanical-append` may be carved out in a later release.
+
+Domains NOT listed here remain governed by the per-phase rules of the corresponding phase (e.g. `simplify-*` follows Phase 2.55 inline rule).
+
 ### Phase 2.55 — Simplify (code cleanup before review)
 
 After completeness is verified, clean up the implementation before it reaches reviewers and E2E tests. This phase launches three parallel agents on the card's diff, then applies fixes directly.
@@ -1140,6 +1156,8 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
 14. **Obsidian Corpus Dispatch**: Parse section H from doc-reviewer findings. If `Trigger: YES`, dispatch the `obsidian-sync` agent (`.claude/agents/obsidian-sync.md`) with the listed paths after all fixes are applied (step 16). If `Trigger: NO`, skip. This is non-blocking -- do not wait for obsidian-sync to complete before proceeding.
 15. If doc findings exist, invoke the **coder** agent once to apply **ALL doc fixes in one pass**.
 
+    **Doc fixes are NEVER applied inline by the orchestrator**, regardless of size or perceived triviality (since v3.28.3). `doc` is a domain-override domain — see "Domain-Override Domains" sub-section. A one-line `CHANGELOG.md` append and a 50-line `data-model.md` migration row update both go through coder. The freshness invariants and tabular formatting that the coder's system prompt enforces are routinely broken by orchestrator inline edits; the cost of a coder spawn is the cost of correctness.
+
     **Telemetry** — after the coder returns, append one row per doc finding to `## Fix Application Log`: `3 | doc | est_lines=<n> | decision=coder-batch | applied_by=coder | finding=<1-line>`. If 0 findings, append one row: `3 | doc | est_lines=0 | decision=skipped | applied_by=- | reason=no-findings`.
 16. Run `npm run lint` and `npx tsc --noEmit` to verify nothing broke. If any check fails, apply the self-healing retry loop (up to 3 times, no user prompt).
 17. **Update tracker**: phase = "3-doc-review DONE", log doc findings count, fixes applied.
@@ -1274,7 +1292,7 @@ For EVERY card (no conditional skip):
 
 4. **Apply fix sub-loop** (mirror of Phase 3.5 retry pattern):
    - If 0 BLOCKER and 0 HIGH → log `verdict: PASS — proceeding to Phase 4` in tracker. Done.
-   - If 1+ BLOCKER OR 1+ HIGH → spawn `coder` agent with the report path + list of VERIFIED bugs to fix. After coder fixes, re-invoke `/codexreview <CARD-ID>` to re-validate. Repeat **max 2 times**.
+   - If 1+ BLOCKER OR 1+ HIGH → spawn `coder` agent with the report path + list of VERIFIED bugs **+ the patch(es) suggested by Codex inline in the report**. The coder applies the suggested patches verbatim — **does NOT re-do the analysis, does NOT re-grep, does NOT re-read files extensively** (since v3.28.3). Codex has already produced both the diagnosis and the patch; the coder is here to apply edits with the right system prompt (project conventions, naming, testing patterns), not to redo Codex's work. This saves 5-10k tokens of redundant security/correctness review per spawn. After coder fixes, re-invoke `/codexreview <CARD-ID>` to re-validate. Repeat **max 2 times**.
    - If still BLOCKER/HIGH after 2 retries → log in `## Issues & Flags` and **ask the user** whether to proceed, escalate, or stop. The Phase 4 commit MUST NOT happen until High-Risk Gate verdict is PASS or user explicitly overrides.
    - **Telemetry** — for EVERY codex finding processed (verified BLOCKER, verified HIGH, or false-positive-filtered), append one row to `## Fix Application Log`: `3.7 | codex-<security|correctness|other> | est_lines=<n> | decision=<coder|skipped> | applied_by=<coder|-> | severity=<BLOCKER|HIGH|FALSE-POSITIVE> | retry=<n>`. Classify domain: `security` for findings touching RLS / auth / permissions / payments; `correctness` for logic / data integrity / race conditions; `other` for everything else.
 
@@ -1314,9 +1332,16 @@ The detector (Step A) is bash + grep — guaranteed to run, no LLM skip. The dow
     e. Stage BOTH the updated YAML AND ssot-registry.md, then commit (or as an immediate follow-up commit if Phase 4 commit already happened).
 28. **Update tracker**: move card to `## Completed Cards` with commit hash, summary, flags, **and `card_status: DONE (verified)`**.
 
-### Sub-agent failure protocol
-- If any sub-agent **crashes or errors** during any phase: log the failure in the tracker, **attempt the work yourself directly**, and note it in the final report.
-- Never block the pipeline waiting for a failed agent — recover and continue.
+### Sub-agent failure protocol (since v3.28.3)
+
+If any sub-agent **crashes or errors** during any phase, follow this 4-step protocol. The pre-v3.28.3 wording ("attempt the work yourself directly") was being used as a shortcut to bypass delegation rules even when no agent had crashed — that escape valve is closed.
+
+1. **Log the failure** in the tracker with the full error trace (under `## Issues & Flags`, prefix `[AGENT-CRASH]`).
+2. **Retry the same agent once**. Transient errors (network, rate-limit, race) are common; a single retry resolves most.
+3. **If retry fails AND the fix is in a domain-override domain** (`doc`, `security`, `migration` — see "Domain-Override Domains" sub-section): **STOP the pipeline**, log in `## Issues & Flags`, and invoke `AskUserQuestion` with options (a) skip the finding, (b) hand off to user, (c) escalate to a different agent type. **NEVER** fall through to inline orchestrator apply for these domains. The whole point of delegation here is that the orchestrator does not have the right system prompt — bypassing on crash defeats the rule.
+4. **If retry fails AND the fix is non-domain-override**: orchestrator MAY apply inline, but MUST log a Fix Application Log row with `applied_by=orchestrator-fallback` + `reason=<agent>-crash-retry-failed` so the telemetry surfaces frequency. If this happens often for the same agent, that agent's reliability is the problem, not the protocol.
+
+Never block the pipeline indefinitely — recover and continue per the rules above. AskUserQuestion in step 3 is bounded by normal user response time.
 
 ### Phase 5 — Context Clean & Continue
 29. Archive the card from Active Code Context in `${paths.references_dir}/project-status.md`.

package/package.json

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

package/src/commands/overlay.js

@@ -116,60 +116,86 @@ function buildFrontmatter({ kind, name, frameworkVersion, baseSha, mode }) {
 
 // ─── scaffold ──────────────────────────────────────────────────────────────
 
-async function scaffold(target, options = {}) {
-  const cwd = process.cwd();
-  ensureConsumer(cwd);
-
+// Pure scaffolder — performs the filesystem work and returns a structured
+// result WITHOUT printing or calling process.exit. The interactive `scaffold`
+// wrapper renders the result; `update --on-divergence scaffold-overlays` calls
+// this in a loop (so one already-existing or missing overlay can't terminate
+// the whole update). Keeping the path/frontmatter logic here honours the
+// "CLI is the source of truth, never re-implement" rule.
+function scaffoldFile(cwd, target, options = {}) {
   const parsed = parseTarget(target);
-  if (!parsed) {
-    UI.error('Invalid target. Use: skill/<name>, agents/<name>, or commands/<name>.');
-    UI.info('Example: npx baldart overlay scaffold agents/coder');
-    process.exit(1);
-  }
+  if (!parsed) return { ok: false, reason: 'invalid-target', target };
   const { kind, name } = parsed;
 
   const baseAbs = baseFilePathFor(cwd, kind, name);
   if (!fs.existsSync(baseAbs)) {
-    UI.error(`Base ${kind} "${name}" not found at ${path.relative(cwd, baseAbs)}.`);
-    UI.info(`Run \`ls ${path.relative(cwd, path.dirname(baseAbs))}\` to list available ${kind}s.`);
-    process.exit(1);
+    return { ok: false, reason: 'base-missing', kind, name, baseRel: path.relative(cwd, baseAbs) };
   }
 
   const overlayAbs = overlayPathFor(cwd, kind, name);
   const overlayRel = path.relative(cwd, overlayAbs);
-
   if (fs.existsSync(overlayAbs)) {
-    UI.warning(`Overlay already exists: ${overlayRel}`);
-    UI.info('Run `npx baldart overlay drift ' + overlayRel + '` to check it, or edit it directly to extend.');
-    process.exit(0);
+    return { ok: false, reason: 'exists', kind, name, overlayRel };
   }
 
-  fs.mkdirSync(path.dirname(overlayAbs), { recursive: true });
-
-  const baseContent = fs.readFileSync(baseAbs, 'utf8');
-  const baseSha = computeBaseFileSha(baseContent);
-  const fwVersion = readFrameworkVersion(cwd);
   const mode = (options.mode || 'extend').trim();
   if (!['extend', 'override'].includes(mode)) {
-    UI.error(`Invalid --mode "${mode}". Use "extend" or "override".`);
-    process.exit(1);
+    return { ok: false, reason: 'bad-mode', mode };
   }
 
+  fs.mkdirSync(path.dirname(overlayAbs), { recursive: true });
+  const baseContent = fs.readFileSync(baseAbs, 'utf8');
+  const baseSha = computeBaseFileSha(baseContent);
+  const fwVersion = readFrameworkVersion(cwd);
   const content =
     buildFrontmatter({ kind, name, frameworkVersion: fwVersion, baseSha, mode }) +
     scaffoldBody(kind, name);
-
   fs.writeFileSync(overlayAbs, content);
-  UI.success(`Created ${overlayRel}`);
-  UI.info(`Base file: ${path.relative(cwd, baseAbs)}`);
-  UI.info(`Targets framework v${fwVersion || 'unknown'} (base_file_sha=${baseSha}).`);
+
+  return {
+    ok: true, reason: 'created', kind, name, overlayRel,
+    baseRel: path.relative(cwd, baseAbs), fwVersion, baseSha,
+  };
+}
+
+async function scaffold(target, options = {}) {
+  const cwd = process.cwd();
+  ensureConsumer(cwd);
+
+  const res = scaffoldFile(cwd, target, options);
+  if (!res.ok) {
+    if (res.reason === 'invalid-target') {
+      UI.error('Invalid target. Use: skill/<name>, agents/<name>, or commands/<name>.');
+      UI.info('Example: npx baldart overlay scaffold agents/coder');
+      process.exit(1);
+    }
+    if (res.reason === 'base-missing') {
+      UI.error(`Base ${res.kind} "${res.name}" not found at ${res.baseRel}.`);
+      UI.info(`Run \`ls ${path.dirname(res.baseRel)}\` to list available ${res.kind}s.`);
+      process.exit(1);
+    }
+    if (res.reason === 'exists') {
+      UI.warning(`Overlay already exists: ${res.overlayRel}`);
+      UI.info('Run `npx baldart overlay drift ' + res.overlayRel + '` to check it, or edit it directly to extend.');
+      process.exit(0);
+    }
+    if (res.reason === 'bad-mode') {
+      UI.error(`Invalid --mode "${res.mode}". Use "extend" or "override".`);
+      process.exit(1);
+    }
+    process.exit(1);
+  }
+
+  UI.success(`Created ${res.overlayRel}`);
+  UI.info(`Base file: ${res.baseRel}`);
+  UI.info(`Targets framework v${res.fwVersion || 'unknown'} (base_file_sha=${res.baseSha}).`);
   UI.newline();
   UI.list([
-    `Edit ${overlayRel} to add your customisations.`,
-    `Validate the merge with: npx baldart overlay validate ${overlayRel}`,
-    kind === 'skill'
+    `Edit ${res.overlayRel} to add your customisations.`,
+    `Validate the merge with: npx baldart overlay validate ${res.overlayRel}`,
+    res.kind === 'skill'
       ? `Run any /-command that uses this skill to see the overlay applied at runtime.`
-      : `Apply with: npx baldart update (regenerates .claude/${kind}s/${name}.md from base + overlay).`,
+      : `Apply with: npx baldart update (regenerates .claude/${res.kind}s/${res.name}.md from base + overlay).`,
   ]);
 }
 
@@ -378,4 +404,4 @@ async function drift(target, options = {}) {
   UI.info(`Summary: ${clean} clean, ${drifted} drifted, ${unknown} unknown — of ${targets.length} overlay(s).`);
 }
 
-module.exports = { scaffold, validate, drift };
+module.exports = { scaffold, scaffoldFile, validate, drift, parseTarget };

package/src/commands/update.js

@@ -20,6 +20,68 @@ function readEnabledTools(cwd = process.cwd()) {
   return ['claude'];
 }
 
+// Allowed values for `--on-divergence` — the non-interactive escape hatch that
+// lets an agent / CI complete (or deliberately stop) an update when the
+// consumer has local commits on `.framework/`. Without it a non-TTY caller has
+// no non-destructive path: `--yes` refuses, the interactive prompt needs a TTY,
+// and `--reset` is gated on a clean working tree (see Finding 2 in the
+// agent-overlay feedback that prompted this).
+const DIVERGENCE_STRATEGIES = ['abort', 'pull', 'scaffold-overlays'];
+
+// Map a touched framework path to an `overlay scaffold` target string.
+//   .framework/framework/.claude/agents/coder.md     → 'agents/coder'
+//   .framework/framework/.claude/commands/check.md    → 'commands/check'
+//   .framework/framework/.claude/skills/bug/SKILL.md  → 'skill/bug'
+// Returns null for anything that isn't an overlay-able framework primitive.
+function frameworkPathToOverlayTarget(p) {
+  const m = /(?:^|\/)\.framework\/framework\/\.claude\/(agents|commands|skills)\/(.+)$/.exec(p);
+  if (!m) return null;
+  const [, dir, rest] = m;
+  if (dir === 'skills') {
+    const name = rest.split('/')[0];
+    return name ? `skill/${name}` : null;
+  }
+  const name = rest.replace(/\.md$/, '');
+  if (!name || name.includes('/')) return null;
+  return `${dir}/${name}`;
+}
+
+// Scaffold overlay skeletons for every overlay-able framework file touched by
+// the given commits. Reuses overlay.scaffoldFile (the CLI is the source of
+// truth — we never re-implement frontmatter/path logic here). Idempotent:
+// existing overlays are left untouched.
+function scaffoldOverlaysForCommits(commits) {
+  const overlay = require('./overlay');
+  const cwd = process.cwd();
+  const targets = new Set();
+  for (const c of commits) {
+    for (const p of (c.touched || [])) {
+      const t = frameworkPathToOverlayTarget(p);
+      if (t) targets.add(t);
+    }
+  }
+  const created = [];
+  const skipped = [];
+  if (targets.size === 0) {
+    UI.warning('Could not derive any overlay target from the divergent commits.');
+    UI.info('They may touch files outside `.claude/{agents,skills,commands}/`. Use `/baldart-push` or `--on-divergence pull`.');
+    return { created, skipped };
+  }
+  for (const t of [...targets].sort()) {
+    const r = overlay.scaffoldFile(cwd, t);
+    if (r.ok) {
+      created.push(r.overlayRel);
+      UI.success(`Scaffolded overlay: ${r.overlayRel}  (base: ${r.baseRel})`);
+    } else if (r.reason === 'exists') {
+      skipped.push(r.overlayRel);
+      UI.info(`Overlay already exists, left as-is: ${r.overlayRel}`);
+    } else {
+      UI.warning(`Could not scaffold ${t}: ${r.reason}${r.baseRel ? ` (${r.baseRel})` : ''}`);
+    }
+  }
+  return { created, skipped };
+}
+
 // Path prefixes BALDART itself writes during install/update. Anything outside
 // these patterns is treated as user-owned and never auto-staged.
 const BALDART_MANAGED_PATTERNS = [
@@ -359,6 +421,14 @@ async function update(options = {}) {
   const autoStash = autoYes || options.autoStash === true;
   const confirm = async (msg, def = true) => (autoYes ? def : UI.confirm(msg, def));
 
+  // Non-interactive divergence strategy (since v3.29.0). Validated up-front so
+  // a typo fails fast instead of mid-flow after the network fetch.
+  const divStrategy = options.onDivergence;
+  if (divStrategy !== undefined && !DIVERGENCE_STRATEGIES.includes(divStrategy)) {
+    UI.error(`Invalid --on-divergence "${divStrategy}". Use one of: ${DIVERGENCE_STRATEGIES.join(', ')}.`);
+    process.exit(1);
+  }
+
   try {
     // Step 1: Verify installation
     UI.header('STEP 1/5: Verify Installation');
@@ -470,45 +540,107 @@ async function update(options = {}) {
       } 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.');
-        for (const c of status.divergenceCommits.filter((c) => c.category === 'custom-overlay-able')) {
+        const overlayCommits = status.divergenceCommits.filter((c) => c.category === 'custom-overlay-able');
+        for (const c of overlayCommits) {
           UI.info(`  • ${c.sha.slice(0, 7)} — ${c.subject}`);
         }
-        if (autoYes) {
-          UI.error('Refusing to overwrite custom edits in --yes mode. Re-run without --yes to choose.');
-          UI.info('Recommended: use the `/overlay` skill to migrate these edits, then re-run update.');
-          process.exit(1);
-        }
-        const choice = await UI.select('How would you like to proceed?', [
-          { name: 'Migrate to overlay and pull anyway (recommended — overlay wins)', value: 'overlay' },
-          { name: 'Keep the custom commits (subtree pull may conflict)', value: 'keep' },
-          { name: 'Abort', value: 'abort' },
-        ]);
-        if (choice === 'abort') { UI.info('Update cancelled.'); process.exit(0); }
-        if (choice === 'overlay') {
-          UI.info('Run `/overlay` from Claude Code to migrate the custom edits, then re-run `npx baldart update`.');
+
+        // Non-interactive resolution (agents / CI) via --on-divergence.
+        if (divStrategy === 'scaffold-overlays') {
+          UI.newline();
+          scaffoldOverlaysForCommits(overlayCommits);
+          UI.newline();
+          UI.info('Next steps:');
+          UI.list([
+            'Fill in the overlay skeleton(s) above to capture your customisations (the base file shows what you changed).',
+            'Then complete the update with `npx baldart update --reset --yes --i-know` — this discards the now-redundant `.framework/` edits and reinstalls clean; your `.baldart/overlays/` are preserved and re-applied.',
+            'Alternatively, push the edits upstream with `/baldart-push` if they are generic improvements.',
+          ], 'cyan');
           process.exit(0);
         }
-        // 'keep' → fall through, subtree pull will attempt merge
+        if (divStrategy === 'abort') { UI.info('Update cancelled (--on-divergence abort).'); process.exit(0); }
+        if (divStrategy === 'pull') {
+          UI.info('Keeping the custom commits (--on-divergence pull). The subtree pull will attempt a merge.');
+          // fall through
+        } else if (autoYes) {
+          // --yes without an explicit strategy: never silently overwrite. Tell
+          // the (likely non-TTY) caller exactly which flag completes the update.
+          UI.error('Custom edits present — refusing to resolve them unattended under --yes.');
+          UI.info('Re-run with one of:');
+          UI.list([
+            '--on-divergence scaffold-overlays  → auto-create overlay skeleton(s), then stop so you can fill them',
+            '--on-divergence pull               → keep the commits and merge the update (non-destructive)',
+            '--reset --yes --i-know             → discard .framework/ edits and reinstall clean (destructive)',
+          ], 'cyan');
+          process.exit(1);
+        } else {
+          const choice = await UI.select('How would you like to proceed?', [
+            { name: 'Scaffold overlay skeleton(s) now (recommended — then fill them in & re-run)', value: 'overlay' },
+            { name: 'Keep the custom commits (subtree pull may conflict)', value: 'keep' },
+            { name: 'Abort', value: 'abort' },
+          ]);
+          if (choice === 'abort') { UI.info('Update cancelled.'); process.exit(0); }
+          if (choice === 'overlay') {
+            UI.newline();
+            scaffoldOverlaysForCommits(overlayCommits);
+            UI.newline();
+            UI.info('Next steps:');
+            UI.list([
+              'Edit the overlay skeleton(s) above to capture your customisations (`/overlay` from Claude Code gives a guided flow).',
+              'Then complete the update with `npx baldart update --reset` — discards the redundant `.framework/` edits, reinstalls clean, re-applies your overlays.',
+            ], 'cyan');
+            process.exit(0);
+          }
+          // 'keep' → fall through, subtree pull will attempt merge
+        }
       } 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))) {
           UI.info(`  • ${c.sha.slice(0, 7)} [${c.category}] — ${c.subject}`);
         }
-        if (autoYes) {
-          UI.error('Refusing to pull over custom commits in --yes mode. Re-run without --yes to choose.');
-          process.exit(1);
-        }
-        const choice = await UI.select('How would you like to proceed?', [
-          { name: 'Push these commits upstream first (recommended — `/baldart-push`)', value: 'push' },
-          { name: 'Pull anyway (will create a merge commit — possible conflicts)', value: 'pull' },
-          { name: 'Abort', value: 'abort' },
-        ]);
-        if (choice === 'abort') { UI.info('Update cancelled.'); process.exit(0); }
-        if (choice === 'push') {
-          UI.info('Run `/baldart-push` from Claude Code (or `npx baldart push`) to contribute upstream, then re-run update.');
+        const overlayCommits = status.divergenceCommits.filter((c) => c.category === 'custom-overlay-able');
+
+        // Non-interactive resolution (agents / CI) via --on-divergence.
+        if (divStrategy === 'scaffold-overlays') {
+          if (overlayCommits.length === 0) {
+            UI.error('No overlay-able commits to scaffold — every custom commit touches non-overlayable paths (src/, CHANGELOG, …).');
+            UI.info('Use `/baldart-push` to contribute them upstream, or `--on-divergence pull` to merge.');
+            process.exit(1);
+          }
+          UI.newline();
+          scaffoldOverlaysForCommits(overlayCommits);
+          UI.newline();
+          UI.warning('Scaffolded overlays for the overlay-able commits, but custom-other commit(s) remain — NOT pulling (would be destructive to those edits).');
+          UI.info('Resolve the remaining commits (push upstream with `/baldart-push`, or revert), then re-run `npx baldart update`.');
           process.exit(0);
         }
-        // 'pull' → fall through
+        if (divStrategy === 'abort') { UI.info('Update cancelled (--on-divergence abort).'); process.exit(0); }
+        if (divStrategy === 'pull') {
+          UI.info('Pulling over the custom commits (--on-divergence pull). A merge commit will be created — resolve any conflicts that surface.');
+          // fall through
+        } else if (autoYes) {
+          UI.error('Custom commits present — refusing to pull over them unattended under --yes.');
+          UI.info('Re-run with one of:');
+          UI.list([
+            '--on-divergence pull               → create a merge commit over your edits (non-destructive)',
+            '--on-divergence scaffold-overlays  → scaffold overlays for the overlay-able subset (custom-other still needs handling)',
+            '--on-divergence abort              → do nothing',
+          ], 'cyan');
+          UI.info('Best practice: contribute generic improvements upstream first with `/baldart-push`.');
+          process.exit(1);
+        } else {
+          const choice = await UI.select('How would you like to proceed?', [
+            { name: 'Push these commits upstream first (recommended — `/baldart-push`)', value: 'push' },
+            { name: 'Pull anyway (will create a merge commit — possible conflicts)', value: 'pull' },
+            { name: 'Abort', value: 'abort' },
+          ]);
+          if (choice === 'abort') { UI.info('Update cancelled.'); process.exit(0); }
+          if (choice === 'push') {
+            UI.info('Run `/baldart-push` from Claude Code (or `npx baldart push`) to contribute upstream, then re-run update.');
+            process.exit(0);
+          }
+          // 'pull' → fall through
+        }
       }
       // 'unknown' → conservative: continue silently, the subtree pull will
       // surface any real conflict.

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

@@ -41,6 +41,65 @@ const SUBJECT_FIXTURES = [
   { subject: "Squashed 'docs/' content from abc..def", expected: null },
   // Chore without 'baldart' keyword — NOT chore-wrapper
   { subject: 'chore: update dependencies', expected: null },
+
+  // ─── subject-regex BLIND SPOTS (now covered by parent-count detection) ──
+  // git omits the "into <branch>" suffix when the merge lands on `master`,
+  // so a real subtree-pull merge can present as a bare "Merge commit 'x'".
+  // The subject classifier returns null here; classifyDivergence() then
+  // relabels it `subtree-merge` because the commit has 2+ parents. We assert
+  // the subject classifier's null so the gap (and why parents matter) is
+  // documented and regression-locked.
+  { subject: "Merge commit 'abc123'", expected: null },
+  // Shared-repo collaboration merge — the " of <url>" segment breaks the
+  // narrow `Merge branch 'x' into <branch>$` shape. Also null → parent count.
+  { subject: "Merge branch 'develop' of github.com:org/repo into develop", expected: null },
+  { subject: "Merge remote-tracking branch 'origin/main'", expected: null },
+];
+
+// aggregateDivergenceClass(commits) — pure reduction of per-commit categories
+// to the divergence class. The headline Finding-1 case: a single overlay-able
+// commit alongside a plumbing merge must stay `overlay-able`, NOT collapse to
+// `mixed`, because the merge is excluded as noise before the decision.
+const AGGREGATE_FIXTURES = [
+  {
+    name: 'overlay-able commit + plumbing merge → overlay-able (not mixed)',
+    commits: [
+      { category: 'custom-overlay-able' },
+      { category: 'subtree-merge' },
+    ],
+    expected: 'overlay-able',
+  },
+  {
+    name: 'overlay-able + subtree-squash + chore-wrapper → overlay-able',
+    commits: [
+      { category: 'custom-overlay-able' },
+      { category: 'subtree-squash' },
+      { category: 'chore-wrapper' },
+    ],
+    expected: 'overlay-able',
+  },
+  {
+    name: 'overlay-able + custom-other → mixed (genuine mix preserved)',
+    commits: [
+      { category: 'custom-overlay-able' },
+      { category: 'custom-other' },
+    ],
+    expected: 'mixed',
+  },
+  {
+    name: 'only custom-other → real-custom',
+    commits: [{ category: 'custom-other' }, { category: 'subtree-merge' }],
+    expected: 'real-custom',
+  },
+  {
+    name: 'only noise → all-noise',
+    commits: [
+      { category: 'subtree-merge' },
+      { category: 'subtree-squash' },
+      { category: 'chore-wrapper' },
+    ],
+    expected: 'all-noise',
+  },
 ];
 
 const PATH_FIXTURES = [
@@ -116,5 +175,17 @@ for (const f of PATH_FIXTURES) {
   }
 }
 
+console.log('\n─── Aggregate class ───');
+for (const f of AGGREGATE_FIXTURES) {
+  const actual = GitUtils.aggregateDivergenceClass(f.commits);
+  if (actual === f.expected) {
+    pass++;
+    console.log(`  ✓ ${f.name} → ${actual}`);
+  } else {
+    fail++;
+    console.log(`  ✗ ${f.name} → ${actual} (expected ${f.expected})`);
+  }
+}
+
 console.log(`\nResult: ${pass} pass, ${fail} fail`);
 process.exit(fail > 0 ? 1 : 0);

package/src/utils/git.js

@@ -263,43 +263,64 @@ class GitUtils {
       const raw = await this.git.raw([
         'log',
         'FETCH_HEAD..HEAD',
-        '--pretty=format:%H%x00%s',
+        '--pretty=format:%H%x00%P%x00%s',
         '--',
         FRAMEWORK_DIR
       ]);
       for (const line of raw.split('\n')) {
         if (!line.trim()) continue;
-        const [sha, ...rest] = line.split('');
+        const [sha, parentStr, ...rest] = line.split('');
         const subject = rest.join('');
+        const parents = (parentStr || '').trim().split(/\s+/).filter(Boolean);
+        const isMerge = parents.length >= 2;
         let category = this.classifyCommitSubject(subject);
+        let touched;
+        if (!category && isMerge) {
+          // A merge commit is git plumbing, never a user customization. The
+          // real content (if any) lives in the merged commits, which appear
+          // in this range on their own when they aren't already upstream.
+          // `git subtree pull --squash` merges vary in subject across git
+          // versions and default-branch name ("Merge commit 'x'" with no
+          // "into <branch>" suffix when landing on `master`; "Merge branch
+          // 'x' of <url> into <branch>" on shared repos), so the subject
+          // regex alone is brittle. Detect merges structurally by parent
+          // count and treat them as noise — otherwise a single plumbing
+          // merge poisons an otherwise overlay-able set into `mixed`.
+          category = 'subtree-merge';
+        }
         if (!category) {
           // Need file list to disambiguate custom-overlay-able vs custom-other.
-          let touched = [];
+          touched = [];
           try {
             const filesRaw = await this.git.raw(['diff-tree', '--no-commit-id', '--name-only', '-r', sha]);
             touched = filesRaw.split('\n').filter((l) => l.trim());
           } catch (_) { /* leave empty → custom-other */ }
           category = this.classifyCommitByPaths(touched);
         }
-        commits.push({ sha, subject, category });
+        commits.push({ sha, subject, category, parents, touched: touched || [] });
       }
     } catch (_) {
       return { class: 'unknown', commits: [] };
     }
 
     if (commits.length === 0) return { class: 'all-noise', commits: [] };
+    return { class: GitUtils.aggregateDivergenceClass(commits), commits };
+  }
 
+  // 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
+  // (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 nonNoise = commits.filter((c) => !noiseCategories.has(c.category));
-    if (nonNoise.length === 0) return { class: 'all-noise', commits };
-
+    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');
-    let aggregate = 'real-custom';
-    if (hasOverlayable && !hasOther) aggregate = 'overlay-able';
-    else if (hasOverlayable && hasOther) aggregate = 'mixed';
-
-    return { class: aggregate, commits };
+    if (hasOverlayable && !hasOther) return 'overlay-able';
+    if (hasOverlayable && hasOther) return 'mixed';
+    return 'real-custom';
   }
 
   async getUpdateStatus(repo, branch = 'main') {