baldart 3.32.0 → 3.33.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.33.0] - 2026-05-30
+
+Closes a **structural silent-partial-install** failure mode (observed on the `mayo` consumer, 3.28→3.31, still live in 3.32.0; same class as the historic v3.27.1 bug): `add` was **non-atomic** — the hook registration ran *after* optional blocking prompts (git aliases, configure). In a non-TTY context (Claude's Bash tool never has a TTY on stdin) or on any interruption, those `inquirer` prompts throw/hang, so `.framework/` + `state.json` landed on the new version while `Hooks.registerAll` never ran — a half-install that `baldart status` still reported as "Valid". The fix makes install atomic (correctness-critical mutations run **before** every optional prompt), adds a **post-flight hook assert** that refuses to declare success with any active hook missing, and finally exposes `add --yes` so agents/CI can install unattended. Two additive, non-breaking follow-ups ship alongside. **No new `baldart.config.yml` keys** — `--yes` is a CLI flag, so the schema-propagation rule does not apply.
+
+### Fixed — `add` is now atomic + never declares a half-install successful
+
+- **[src/commands/add.js](src/commands/add.js)**: `Hooks.registerAll` is **reordered ahead of** the optional git-aliases and configure prompts. Hook registration determines install correctness and must never sit behind a blocking prompt — if `add` is interrupted at an optional prompt, the hooks are already in place. The drift callback now passes `{ autoYes: nonInteractive }` (parity with `update.js`), so a drifted hook in non-TTY no longer throws.
+- **[src/utils/hooks.js](src/utils/hooks.js)**: new exported `verifyAll(cwd)` — a pure read over `getStatus` returning `{ ok, malformed, missing, path }`. It iterates only the **active** `HOOK_REGISTRY` (commented-out entries like `capture-detect` excluded for free). A malformed `settings.json` counts as a failure (registration was skipped).
+- **[src/commands/add.js](src/commands/add.js)**: **post-flight assert** before the success summary — re-reads `settings.json`, attempts a single best-effort re-registration if anything is missing, then exits non-zero ("Install is NOT complete") if a hook is still absent. Covers `update --reset` too, since that path delegates to `add(undefined, { yes: true })`.
+
+### Added — `add --yes` (non-interactive install for CI / agents)
+
+- **[bin/baldart.js](bin/baldart.js)**: registers `-y, --yes` on the `add` subcommand (the underlying `add(repo, options)` already honored `options.yes`, it was just unreachable from the CLI). With `--yes`, `add` auto-confirms optional prompts and passes `{ nonInteractive: true }` to `configure` so its wizard writes autodetected values without blocking.
+- **[src/commands/add.js](src/commands/add.js)**: `add --yes` on a repo that **already has** `.framework/` now fails fast with a clear pointer to `npx baldart update --reset --yes --i-know` instead of hitting the deliberately-interactive destructive "Remove and reinstall?" prompt (which would throw under non-TTY and surface as a generic failure). Clean installs only; reinstall goes through `--reset`.
+
+### Added — divergence classifier flags overlay-covered edits (`--reset` is safe)
+
+- **[src/utils/git.js](src/utils/git.js)**: `classifyDivergence` now tags each `custom-overlay-able` commit with `overlayCovered` — true when **every** framework file it touches already has a matching overlay in `.baldart/overlays/`. New pure static `overlayRelForFrameworkFile(path)` mirrors the `overlay.js` path conventions (unit-tested).
+- **[src/commands/update.js](src/commands/update.js)**: in the overlay-able divergence branch, when all commits are `overlayCovered` the UI/JSON now recommend `--reset --yes --i-know` as the **safe** resolution (intent already preserved in the overlays) and note that `scaffold-overlays` would create redundant skeletons. New `overlay_already_covered` field in the `--json` output.
+
+### Added — deterministic `overlay drift` via base-sha backfill
+
+- **[src/utils/overlay-merger.js](src/utils/overlay-merger.js)**: new `ensureBaseFileShaInOverlay(overlayPath, baseSha)` — **additive-only, idempotent, fail-safe**: stamps `base_file_sha` into an overlay's frontmatter when absent (never overwrites, never fabricates frontmatter). Called from the merger in **[src/utils/symlinks.js](src/utils/symlinks.js)** `_generateOverlayedFile` at `add`/`update` time, so `baldart overlay drift` becomes deterministic for **every** overlay — not just freshly-scaffolded ones (hand-written / pre-v3.19.0 overlays were "unknown" to drift).
+
+### Tests
+
+- **[scripts/test-add-postflight.sh](scripts/test-add-postflight.sh)**: new — encodes the post-flight **invariant** (a `settings.json` missing an active hook → `verifyAll().ok === false`; the dropped hook in the test is literally `baldart-overlay-telemetry`, the mayo failure). Fails on pre-v3.33.0 code (no `verifyAll`).
+- **[scripts/test-overlay-backfill.sh](scripts/test-overlay-backfill.sh)**: new — backfill is additive, idempotent, never overwrites an existing sha, never fabricates frontmatter, fail-safe.
+- **[src/utils/__tests__/classify-divergence.test.js](src/utils/__tests__/classify-divergence.test.js)**: extended with overlay-path-mapping fixtures (38 assertions, all green).
+
+### Changed — `/baldart-update` skill
+
+- **[framework/.claude/skills/baldart-update/SKILL.md](framework/.claude/skills/baldart-update/SKILL.md)**: post-flight report (step 4) documents the new CLI hook assert in `add`/`--reset`; `last_verified` v3.32.0 → v3.33.0 (`hook_registry_entries`/`update_js_prompts` unchanged).
+
 ## [3.32.0] - 2026-05-30
 
 Makes the CLI **agent-native at the output layer**: `npx baldart version --json` and `npx baldart update --json --yes` now emit a single **machine-readable JSON object** on stdout (schemas `baldart.version/1` / `baldart.update/1`), with every human line routed to stderr. This closes the last fragile seam in the autonomous-update path — the `/baldart-update` skill previously had to **regex-scrape human-readable prose** (the v3.26.0 wording change had already forced a dual-format tolerant parser in Step 0). An agent now reads a field instead of matching a sentence. Borrowed from the [CLI-Anything](https://github.com/HKUDS/CLI-Anything) philosophy (`--json` on every command) — but BALDART is already a headless CLI, so this is a thin, hand-rolled output layer, not a generated wrapper. **No new `baldart.config.yml` keys** — `--json` is a CLI flag, not a config key, so the schema-propagation rule does not apply.

package/VERSION

@@ -1 +1 @@
-3.32.0
+3.33.0

package/bin/baldart.js

@@ -65,6 +65,7 @@ program
   .command('add [repo]')
   .description('Install the framework in your project')
   .option('-b, --branch <branch>', 'Branch to use', 'main')
+  .option('-y, --yes', 'Non-interactive install (CI / agents): auto-confirm all optional prompts and skip the interactive configure wizard. Refuses to reinstall over an existing .framework/ — use `update --reset` for that.')
   .action(async (repo, options) => {
     const addCommand = require('../src/commands/add');
     await addCommand(repo || 'antbald/BALDART', options);

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

@@ -15,7 +15,7 @@ this skill needs an update is left to a human reviewer.
 update_js_prompts: 6
 hook_registry_entries: 4
 config_template_top_level_keys: features,git,identity,lsp,paths,stack,tools,version
-last_verified: v3.32.0
+last_verified: v3.33.0
 -->
 
 <!--
@@ -498,7 +498,15 @@ Report to the user, in order:
 3. **CLI self-upgrade**: if stdout mentions "Auto-relaunching via npx
    baldart@…", surface it once so the user knows the CLI bumped too.
 4. **Hooks reconciled**: any hook backfilled (parse "Auto-registered N
-   missing hook(s)" or per-line "Registered hook" from stdout).
+   missing hook(s)" or per-line "Registered hook" from stdout). Since v3.33.0
+   the CLI also runs a **post-flight hook assert** at the end of `add` (and
+   therefore of `update --reset`, which delegates to `add`): it re-reads
+   `.claude/settings.json` and refuses to declare success — exiting non-zero
+   with "Install is NOT complete" — if any active `HOOK_REGISTRY` entry is
+   missing. So a clean `--reset` can no longer leave a half-install that
+   reports "Valid" (the mayo 3.28→3.31 / v3.27.1 failure class). If you see
+   that error, the repo is in an inconsistent state: run `npx baldart doctor`
+   to repair, do NOT report success.
 5. **Agent layout migration (v3.27.0+)**: parse stdout for lines matching
    `agent generated (overlay applied): .claude/agents/<name>.md → ../../.baldart/generated/agents/<name>.md`.
    Pre-v3.27.0 overlay-merged agents (`coder`, `ui-expert`, `code-reviewer`,

package/package.json

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

package/src/commands/add.js

@@ -44,6 +44,15 @@ async function add(repo, options) {
     const exists = await git.frameworkExists();
     if (exists) {
       UI.warning('Framework already installed!');
+      // A non-interactive `add --yes` must never block on (or auto-confirm) the
+      // destructive "Remove and reinstall?" prompt. Reinstalling is an explicit
+      // user decision routed through `update --reset` (which rm -rf's
+      // `.framework/` itself, so this branch is never reached on that path).
+      // Fail fast with a clear pointer instead of a generic catch below.
+      if (nonInteractive) {
+        UI.error('.framework/ already present — a non-interactive reinstall must go through `npx baldart update --reset --yes --i-know`.');
+        process.exit(1);
+      }
       const shouldReinstall = await UI.confirm(
         'Remove and reinstall? (You will lose customizations)',
         false
@@ -163,6 +172,35 @@ async function add(repo, options) {
     UI.newline();
     symlinks.copyCustomizableFiles();
 
+    // BALDART hooks (multi-hook registry since v3.18.0)
+    // Auto-register every hook in src/utils/hooks.js HOOK_REGISTRY into
+    // .claude/settings.json. Drift on an existing entry triggers an
+    // interactive prompt (Keep / Replace / Show diff), or 'keep' in --yes mode.
+    //
+    // This runs BEFORE the optional prompts below (git aliases, configure) —
+    // hook registration determines the correctness of the install and must
+    // never sit behind a blocking prompt. If `add` is interrupted at an
+    // optional prompt (non-TTY, Ctrl-C), the hooks are already in place.
+    // (Reordered in v3.33.0 to close the silent partial-install gap.)
+    try {
+      const res = await Hooks.registerAll(process.cwd(), {
+        onDrift: Hooks.createDriftPrompt(UI, { autoYes: nonInteractive }),
+      });
+      if (res.malformed) {
+        UI.warning('.claude/settings.json is malformed; skipped hook registration. Run `npx baldart doctor` after fixing it.');
+      } else {
+        for (const r of res.results) {
+          if (r.status === 'created') UI.success(`Registered hook \`${r.id}\` in .claude/settings.json`);
+          else if (r.status === 'legacy-migrated') UI.success(`Migrated legacy hook to \`${r.id}\` (previous: ${r.previousCommand})`);
+          else if (r.status === 'drift-replaced') UI.success(`Replaced drifted hook \`${r.id}\` (was: ${r.previousCommand})`);
+          else if (r.status === 'drift-kept') UI.info(`Kept user-customized hook \`${r.id}\` as-is.`);
+          else if (r.status === 'already') UI.info(`Hook \`${r.id}\` already registered.`);
+        }
+      }
+    } catch (err) {
+      UI.warning(`Hook registration skipped: ${err.message}`);
+    }
+
     // Configure Git aliases
     UI.section('Configuring Git Aliases');
 
@@ -201,29 +239,6 @@ async function add(repo, options) {
       }
     }
 
-    // BALDART hooks (multi-hook registry since v3.18.0)
-    // Auto-register every hook in src/utils/hooks.js HOOK_REGISTRY into
-    // .claude/settings.json. Drift on an existing entry triggers an
-    // interactive prompt (Keep / Replace / Show diff).
-    try {
-      const res = await Hooks.registerAll(process.cwd(), {
-        onDrift: Hooks.createDriftPrompt(UI),
-      });
-      if (res.malformed) {
-        UI.warning('.claude/settings.json is malformed; skipped hook registration. Run `npx baldart doctor` after fixing it.');
-      } else {
-        for (const r of res.results) {
-          if (r.status === 'created') UI.success(`Registered hook \`${r.id}\` in .claude/settings.json`);
-          else if (r.status === 'legacy-migrated') UI.success(`Migrated legacy hook to \`${r.id}\` (previous: ${r.previousCommand})`);
-          else if (r.status === 'drift-replaced') UI.success(`Replaced drifted hook \`${r.id}\` (was: ${r.previousCommand})`);
-          else if (r.status === 'drift-kept') UI.info(`Kept user-customized hook \`${r.id}\` as-is.`);
-          else if (r.status === 'already') UI.info(`Hook \`${r.id}\` already registered.`);
-        }
-      }
-    } catch (err) {
-      UI.warning(`Hook registration skipped: ${err.message}`);
-    }
-
     // Routines wizard (since v2.1.0)
     try {
       const routinesCmd = require('./routines');
@@ -245,7 +260,9 @@ async function add(repo, options) {
     if (runConfigure) {
       try {
         const configureCmd = require('./configure');
-        await configureCmd();
+        // In --yes mode, configure must write autodetected values without
+        // prompting — otherwise its inquirer prompts block in non-TTY.
+        await configureCmd(nonInteractive ? { nonInteractive: true } : undefined);
       } catch (err) {
         UI.warning(`Configure step failed: ${err.message}`);
         UI.info('Run `npx baldart configure` later to complete setup.');
@@ -254,6 +271,31 @@ async function add(repo, options) {
       UI.info('Skipped. Run `npx baldart configure` before invoking skills.');
     }
 
+    // Post-flight assert — never declare success with missing hooks.
+    // Re-reads .claude/settings.json and confirms every active hook in
+    // HOOK_REGISTRY is present. Guards against the silent partial-install
+    // class (v3.27.1 / mayo 3.28→3.31). Covers `update --reset` too, since
+    // that path delegates to add(undefined, { yes: true }).
+    let verify = Hooks.verifyAll(process.cwd());
+    if (!verify.ok && !verify.malformed) {
+      // A single best-effort re-registration before failing hard.
+      try {
+        await Hooks.registerAll(process.cwd(), {
+          onDrift: Hooks.createDriftPrompt(UI, { autoYes: nonInteractive }),
+        });
+      } catch (_) { /* fall through to the assert below */ }
+      verify = Hooks.verifyAll(process.cwd());
+    }
+    if (!verify.ok) {
+      UI.error(
+        verify.malformed
+          ? '.claude/settings.json is malformed — cannot verify hooks. Install is NOT complete.'
+          : `Hooks missing after install: ${verify.missing.join(', ')}. Install is NOT complete.`
+      );
+      UI.info('Run `npx baldart doctor` to repair, then re-check `npx baldart status`.');
+      process.exit(1);
+    }
+
     // Success summary
     UI.header('✓ INSTALLATION COMPLETE');
 

package/src/commands/update.js

@@ -592,6 +592,19 @@ async function update(options = {}) {
           UI.info(`  • ${c.sha.slice(0, 7)} — ${c.subject}`);
         }
 
+        // If every overlay-able commit only touches files that ALREADY have a
+        // matching overlay in `.baldart/overlays/`, the divergent edit's intent
+        // is already preserved — `--reset` is safe and `scaffold-overlays`
+        // would only create redundant skeletons. Surface that so the user/agent
+        // picks the cheap, correct resolution. (v3.33.0)
+        const allCovered = overlayCommits.length > 0
+          && overlayCommits.every((c) => c.overlayCovered === true);
+        if (allCovered) {
+          UI.newline();
+          UI.success('These edits are already preserved in `.baldart/overlays/` — `--reset` is safe (your overlays are re-applied); scaffolding new overlays would be redundant.');
+          UI.info('Fast path: `npx baldart update --reset --yes --i-know`.');
+        }
+
         // Non-interactive resolution (agents / CI) via --on-divergence.
         if (divStrategy === 'scaffold-overlays') {
           UI.newline();
@@ -604,7 +617,7 @@ async function update(options = {}) {
             'Alternatively, push the edits upstream with `/baldart-push` if they are generic improvements.',
           ], 'cyan');
           emitUpdateJson({ ok: false, action: 'divergence-scaffolded',
-            divergence_class: status.divergenceClass,
+            divergence_class: status.divergenceClass, overlay_already_covered: allCovered,
             installed_before: status.installedVersion, remote_version: status.remoteVersion,
             reason: 'Scaffolded overlay skeleton(s); fill them in, then re-run.',
             next_command: 'npx baldart update --reset --yes --i-know' }, 0);
@@ -624,15 +637,23 @@ async function update(options = {}) {
           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',
+            allCovered
+              ? '--reset --yes --i-know             → SAFE here: these edits are already in `.baldart/overlays/` (recommended)'
+              : '--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)',
+            allCovered
+              ? '--on-divergence scaffold-overlays  → would create redundant skeletons (edits already covered)'
+              : '--reset --yes --i-know             → discard .framework/ edits and reinstall clean (destructive)',
           ], 'cyan');
           emitUpdateJson({ ok: false, action: 'divergence-refused',
-            divergence_class: status.divergenceClass,
+            divergence_class: status.divergenceClass, overlay_already_covered: allCovered,
             installed_before: status.installedVersion, remote_version: status.remoteVersion,
-            reason: 'Custom edits present — refusing to resolve them unattended under --yes.',
-            next_command: 'npx baldart update --json --yes --on-divergence scaffold-overlays' }, 1);
+            reason: allCovered
+              ? 'Custom edits present but already preserved in .baldart/overlays/ — `--reset --yes --i-know` is the safe resolution.'
+              : 'Custom edits present — refusing to resolve them unattended under --yes.',
+            next_command: allCovered
+              ? 'npx baldart update --reset --yes --i-know'
+              : 'npx baldart update --json --yes --on-divergence scaffold-overlays' }, 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' },

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

@@ -149,6 +149,45 @@ const PATH_FIXTURES = [
   },
 ];
 
+// overlayRelForFrameworkFile(p) — pure mapping of a touched .framework/ payload
+// file to the consumer overlay path that would preserve a customization of it.
+// Mirrors src/commands/overlay.js conventions (overlayPath). null when no
+// overlay maps to the file. Used by overlayCoversTouched() to flag commits
+// whose intent is already preserved (→ `--reset` safe, scaffold redundant).
+const path = require('path');
+const OVERLAY_REL_FIXTURES = [
+  {
+    name: 'skill SKILL.md → flat overlay',
+    file: '.framework/framework/.claude/skills/ui-design/SKILL.md',
+    expected: path.join('.baldart', 'overlays', 'ui-design.md'),
+  },
+  {
+    name: 'skill nested script → same flat overlay',
+    file: '.framework/framework/.claude/skills/ui-design/scripts/foo.sh',
+    expected: path.join('.baldart', 'overlays', 'ui-design.md'),
+  },
+  {
+    name: 'agent .md → agents/ overlay',
+    file: '.framework/framework/.claude/agents/ui-expert.md',
+    expected: path.join('.baldart', 'overlays', 'agents', 'ui-expert.md'),
+  },
+  {
+    name: 'command .md → commands/ overlay',
+    file: '.framework/framework/.claude/commands/check.md',
+    expected: path.join('.baldart', 'overlays', 'commands', 'check.md'),
+  },
+  {
+    name: 'src file → null (no overlay maps)',
+    file: '.framework/src/utils/git.js',
+    expected: null,
+  },
+  {
+    name: 'nested agent path → null (agents are flat .md)',
+    file: '.framework/framework/.claude/agents/sub/x.md',
+    expected: null,
+  },
+];
+
 let pass = 0, fail = 0;
 
 console.log('─── Subject classifier ───');
@@ -187,5 +226,48 @@ for (const f of AGGREGATE_FIXTURES) {
   }
 }
 
+console.log('\n─── Overlay path mapping ───');
+for (const f of OVERLAY_REL_FIXTURES) {
+  const actual = GitUtils.overlayRelForFrameworkFile(f.file);
+  if (actual === f.expected) {
+    pass++;
+    console.log(`  ✓ ${f.name} → ${actual}`);
+  } else {
+    fail++;
+    console.log(`  ✗ ${f.name} → ${actual} (expected ${f.expected})`);
+  }
+}
+
+// overlayCoversTouched(touched) — fs-backed: true only when EVERY touched file
+// maps to an EXISTING overlay. This is the `overlayCovered` field that flows
+// (via classifyDivergence → getUpdateStatus.divergenceCommits, a direct
+// pass-through) into update.js's "reset is safe" branch. Lock the fs semantics.
+console.log('\n─── overlayCoversTouched (fs-backed) ───');
+{
+  const fsMod = require('fs');
+  const os = require('os');
+  const tmp = fsMod.mkdtempSync(path.join(os.tmpdir(), 'baldart-ovl-'));
+  fsMod.mkdirSync(path.join(tmp, '.baldart', 'overlays', 'agents'), { recursive: true });
+  fsMod.writeFileSync(path.join(tmp, '.baldart', 'overlays', 'agents', 'coder.md'), '---\n---\n');
+  const g2 = new GitUtils(tmp);
+  const cases = [
+    { name: 'touched file has an existing overlay → covered',
+      touched: ['.framework/framework/.claude/agents/coder.md'], expected: true },
+    { name: 'touched file has NO overlay → not covered',
+      touched: ['.framework/framework/.claude/agents/ui-expert.md'], expected: false },
+    { name: 'one covered + one uncovered → not covered (every)',
+      touched: ['.framework/framework/.claude/agents/coder.md',
+                '.framework/framework/.claude/agents/ui-expert.md'], expected: false },
+    { name: 'empty touched → not covered',
+      touched: [], expected: false },
+  ];
+  for (const c of cases) {
+    const actual = g2.overlayCoversTouched(c.touched);
+    if (actual === c.expected) { pass++; console.log(`  ✓ ${c.name} → ${actual}`); }
+    else { fail++; console.log(`  ✗ ${c.name} → ${actual} (expected ${c.expected})`); }
+  }
+  fsMod.rmSync(tmp, { recursive: true, force: true });
+}
+
 console.log(`\nResult: ${pass} pass, ${fail} fail`);
 process.exit(fail > 0 ? 1 : 0);

package/src/utils/git.js

@@ -256,6 +256,47 @@ class GitUtils {
     return allOverlayable ? 'custom-overlay-able' : 'custom-other';
   }
 
+  // Maps a touched `.framework/` payload file to the consumer overlay path that
+  // would preserve a customization of it, or null when no overlay maps to it.
+  // Mirrors the conventions in src/commands/overlay.js (overlayPath):
+  //   .framework/framework/.claude/skills/<name>/...   → .baldart/overlays/<name>.md
+  //   .framework/framework/.claude/agents/<name>.md    → .baldart/overlays/agents/<name>.md
+  //   .framework/framework/.claude/commands/<name>.md  → .baldart/overlays/commands/<name>.md
+  // Pure (no fs) so it stays unit-testable.
+  static overlayRelForFrameworkFile(p) {
+    const prefix = '.framework/framework/.claude/';
+    if (!p.startsWith(prefix)) return null;
+    const rest = p.slice(prefix.length);
+    const slash = rest.indexOf('/');
+    if (slash < 0) return null;
+    const dir = rest.slice(0, slash);
+    if (dir === 'skills') {
+      const name = rest.slice(slash + 1).split('/')[0];
+      if (!name) return null;
+      return path.join('.baldart', 'overlays', `${name}.md`);
+    }
+    if (dir === 'agents' || dir === 'commands') {
+      const file = rest.slice(slash + 1);
+      if (!file || file.includes('/')) return null; // flat <name>.md files only
+      const name = file.replace(/\.md$/, '');
+      if (!name) return null;
+      return path.join('.baldart', 'overlays', dir, `${name}.md`);
+    }
+    return null;
+  }
+
+  // True when EVERY overlay-able file touched by the commit already has an
+  // existing overlay in `.baldart/overlays/` — i.e. the divergent edit's intent
+  // is already preserved, so `--reset` is safe and `scaffold-overlays` would
+  // only create redundant skeletons.
+  overlayCoversTouched(touched) {
+    if (!touched || !touched.length) return false;
+    return touched.every((p) => {
+      const rel = GitUtils.overlayRelForFrameworkFile(p);
+      return rel ? fs.existsSync(path.join(this.cwd, rel)) : false;
+    });
+  }
+
   async classifyDivergence() {
     // Inspect aheadScoped commits — those not on FETCH_HEAD that touch .framework/.
     const commits = [];
@@ -297,7 +338,10 @@ class GitUtils {
           } catch (_) { /* leave empty → custom-other */ }
           category = this.classifyCommitByPaths(touched);
         }
-        commits.push({ sha, subject, category, parents, touched: touched || [] });
+        const overlayCovered = category === 'custom-overlay-able'
+          ? this.overlayCoversTouched(touched)
+          : false;
+        commits.push({ sha, subject, category, parents, touched: touched || [], overlayCovered });
       }
     } catch (_) {
       return { class: 'unknown', commits: [] };

package/src/utils/hooks.js

@@ -384,6 +384,38 @@ function unregisterAll(cwd = process.cwd()) {
   return { malformed: false, path: settingsPath, results };
 }
 
+// ---------------------------------------------------------------------------
+// Verify — post-flight assertion that every active hook is registered
+// ---------------------------------------------------------------------------
+
+/**
+ * Confirms that every active hook in HOOK_REGISTRY is present in
+ * `.claude/settings.json`. Pure read (delegates to `getStatus`). Designed as
+ * the post-flight gate for `add` / `update --reset`: the install must never
+ * declare success while a hook is missing (the silent partial-install class,
+ * v3.27.1 / mayo 3.28→3.31). Commented-out registry entries (e.g.
+ * capture-detect) are excluded for free — `getStatus` only iterates the array.
+ *
+ * A malformed settings.json counts as a failure: registration was skipped, so
+ * the hooks are not verifiably present.
+ *
+ * @param {string} [cwd]
+ * @returns {{ ok: boolean, malformed: boolean, missing: string[], path: string }}
+ */
+function verifyAll(cwd = process.cwd()) {
+  const status = getStatus(cwd);
+  if (status.malformed) {
+    return {
+      ok: false,
+      malformed: true,
+      missing: HOOK_REGISTRY.map((d) => d.id),
+      path: status.path,
+    };
+  }
+  const missing = status.hooks.filter((h) => !h.registered).map((h) => h.id);
+  return { ok: missing.length === 0, malformed: false, missing, path: status.path };
+}
+
 // ---------------------------------------------------------------------------
 // Drift prompt helper (interactive Keep / Replace / Show diff)
 // ---------------------------------------------------------------------------
@@ -434,6 +466,7 @@ module.exports = {
   HOOK_REGISTRY,
   SETTINGS_FILE,
   getStatus,
+  verifyAll,
   registerAll,
   unregisterAll,
   createDriftPrompt,

package/src/utils/overlay-merger.js

@@ -1,4 +1,5 @@
 const crypto = require('crypto');
+const fs = require('fs');
 const yaml = require('js-yaml');
 
 /**
@@ -41,6 +42,45 @@ function computeBaseFileSha(content) {
   return shortSha(content);
 }
 
+/**
+ * Idempotently backfill `base_file_sha` into an overlay file's frontmatter so
+ * `baldart overlay drift` is deterministic for EVERY overlay — not only those
+ * freshly scaffolded by `overlay scaffold` (which already writes it). Overlays
+ * authored by hand or by pre-v3.19.0 versions are otherwise "unknown" to drift
+ * (overlay.js drift § no base_file_sha). The merger knows the base file, so it
+ * stamps the sha here at `add`/`update` time.
+ *
+ * Contract: ADDITIVE-ONLY. Never overwrites an existing `base_file_sha`. Only
+ * touches a file that already has a leading YAML frontmatter block — never
+ * fabricates frontmatter on a file that lacks it. Fail-safe: any I/O error is
+ * swallowed (returns `changed:false`) so a backfill can never block a merge.
+ *
+ * @param {string} overlayPath absolute path to `.baldart/overlays/<…>.md`
+ * @param {string} baseSha     12-char hex from computeBaseFileSha(baseContent)
+ * @returns {{ changed: boolean, reason: string }}
+ */
+function ensureBaseFileShaInOverlay(overlayPath, baseSha) {
+  if (!baseSha) return { changed: false, reason: 'no-base-sha' };
+  let content;
+  try { content = fs.readFileSync(overlayPath, 'utf8'); }
+  catch (_) { return { changed: false, reason: 'unreadable' }; }
+  // Leading frontmatter block only (optionally after a BOM / blank lines).
+  const m = content.match(/^(\uFEFF?\s*)---\n([\s\S]*?)\n---(\r?\n|$)/);
+  if (!m) return { changed: false, reason: 'no-frontmatter' };
+  const fmBody = m[2];
+  if (/^\s*base_file_sha\s*:/m.test(fmBody)) {
+    return { changed: false, reason: 'already-present' };
+  }
+  // Quote the value — a 12-char hex can be all digits, which YAML would
+  // otherwise parse as a number (matches overlay.js buildFrontmatter).
+  const newFmBody = `${fmBody.replace(/\n+$/, '')}\nbase_file_sha: "${baseSha}"`;
+  const replaced = `${m[1]}---\n${newFmBody}\n---${m[3]}`;
+  const updated = content.slice(0, m.index) + replaced + content.slice(m.index + m[0].length);
+  try { fs.writeFileSync(overlayPath, updated, 'utf8'); }
+  catch (_) { return { changed: false, reason: 'unwritable' }; }
+  return { changed: true, reason: 'backfilled' };
+}
+
 function buildMarker({ kind, name, baseVersion, baseSha, overlaySha }) {
   const baseShaField = baseSha ? ` base_sha=${baseSha}` : '';
   return `${MARKER_PREFIX} kind=${kind} name=${name} base_version=${baseVersion}${baseShaField} overlay_sha=${overlaySha}
@@ -239,5 +279,6 @@ module.exports = {
   parseMarkdown,
   shortSha,
   computeBaseFileSha,
+  ensureBaseFileShaInOverlay,
   MARKER_PREFIX
 };

package/src/utils/symlinks.js

@@ -484,8 +484,17 @@ class SymlinkUtils {
   }
 
   _generateOverlayedFile({ kind, name, fwAbsolute, overlayAbs, linkPath, lstat, frameworkVersion, aggregate, adapter, targetRel }) {
-    const { mergeOverlay, readMarker, isGeneratedFile } = require('./overlay-merger');
+    const { mergeOverlay, isGeneratedFile, computeBaseFileSha, ensureBaseFileShaInOverlay } = require('./overlay-merger');
     const baseContent = fs.readFileSync(fwAbsolute, 'utf8');
+    // Backfill base_file_sha into the overlay frontmatter so `overlay drift` is
+    // deterministic for EVERY overlay, not just freshly-scaffolded ones
+    // (additive-only, never overwrites). Done BEFORE reading overlayContent so
+    // the marker's overlay_sha already reflects it — no one-time regen churn.
+    // (v3.33.0)
+    try {
+      const bf = ensureBaseFileShaInOverlay(overlayAbs, computeBaseFileSha(baseContent));
+      if (bf.changed) UI.info(`[${adapter.label}] ${kind} ${name}: backfilled base_file_sha into overlay frontmatter.`);
+    } catch (_) { /* non-fatal — never block a merge on backfill */ }
     const overlayContent = fs.readFileSync(overlayAbs, 'utf8');
     const merged = mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersion });