baldart 3.31.0 → 3.33.0

package/CHANGELOG.md

@@ -5,6 +5,59 @@ 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.
+
+### Added — `--json` structured output
+
+- **[src/commands/version.js](src/commands/version.js)**: `--json` emits `{schema:"baldart.version/1", installed, installed_version, remote_version, aligned, offline, fetched, uncommitted_files, commits_ahead/behind, cli_version, cli_latest, cli_update_available, repository, last_update_date, last_pushed_version, last_push_date}` — exactly the facts the human box shows. Framework-not-installed and error paths emit `{installed:false|null, error, …}` so the agent always gets parseable stdout.
+- **[src/commands/update.js](src/commands/update.js)**: `--json` emits a single `{schema:"baldart.update/1", ok, action, …}` result at **every** terminal point through one `emitUpdateJson` chokepoint (all-or-nothing: a missed exit would leave stdout empty). `ok:true` ⟺ the framework is now at the remote version (`action` `updated` / `already-current`); every refusal/failure is `ok:false` with `action` (`divergence-refused`, `divergence-scaffolded`, `aborted`, `failed`, `framework-missing`, `usage-error`), `reason`, and a `next_command` the human can re-run. `--json` **requires `--yes`** (so no prompt can block) and **rejects `--reset`** (the nuclear path stays an interactive human escape hatch).
+- **[src/utils/ui.js](src/utils/ui.js)**: new `UI.setJsonMode(on)` redirects every `console.log` the UI helpers emit to **stderr** (reversible), keeping stdout clean for the JSON. `ora` spinners already write to stderr, so they need no change. The JSON itself is written with `process.stdout.write`, never `console.log`, so it survives the redirect.
+
+### Changed — autonomous `/baldart-update` reads JSON, not prose
+
+- **[framework/.claude/skills/baldart-update/SKILL.md](framework/.claude/skills/baldart-update/SKILL.md)**: Step 0 now **prefers** `version --json` (field reads) and **falls back** to the dual-format text parser when the global CLI predates v3.32.0 (`--json` unknown / non-JSON stdout) — the same "new skill + old global CLI" transition window the text parser already guards. Autonomous mode runs `update --json --yes`, parses the single result object (`ok` / `action` / `installed_after` / `backup_tag` / `next_command`), and keeps the **exit code as the safety backstop**. The post-flight assert cross-checks `installed_after` against on-disk `.framework/VERSION` and the Step 0 `remote_version`. `last_verified` v3.31.0 → v3.32.0; added a **JSON-OUTPUT NOTE** recording that `--json` is a flag, not a config key.
+
+### Fixed — self-relaunch flag forwarding
+
+- **[src/commands/update.js](src/commands/update.js)** `maybeRelaunchUnderLatest`: the stale-CLI self-relaunch now forwards `--json` **and** `--on-divergence <strategy>` to the `npx baldart@latest` child. The latter was a pre-existing latent drop (an agent's non-interactive divergence strategy would silently vanish on relaunch); both are fixed together.
+- **[bin/baldart.js](bin/baldart.js)**: the CLI self-update notifier's stdout `announce` is suppressed under `--json` so it cannot pollute the single JSON object.
+
 ## [3.31.0] - 2026-05-30
 
 Gives `/baldart-update` an **autonomous mode** so agents and scheduled routines can bring the framework up-to-date with **zero human interaction** — closing the gap that the skill, as shipped, was *purely* human-in-the-loop (it replicated every CLI decision point as a chat confirmation, which an unattended agent cannot answer). The new mode is **auto-detected** from a positive automation signal and keeps every one of the CLI's safety gates: it drives `npx baldart update --yes` and **stops hard** (never forces a merge or reset) the moment the CLI refuses on custom divergence or a conflict — exactly the calls a human should own. **No new `baldart.config.yml` keys** — `BALDART_AUTONOMOUS` is a runtime env var, not a config flag, so the schema-propagation rule does not apply.

package/README.md

@@ -456,6 +456,14 @@ Update framework to latest version.
 - Updates via Git subtree
 - Verifies symlinks
 
+**For agents / CI (v3.32.0+):** `npx baldart update --json --yes` emits a single
+machine-readable result object on stdout (`{schema:"baldart.update/1", ok,
+action, installed_after, backup_tag, next_command, …}`) with all human output on
+stderr — no prose to scrape. `ok:true` ⟺ the framework is now at the remote
+version. `--json` requires `--yes` and rejects `--reset`. Pair with
+`--on-divergence pull|scaffold-overlays|abort` for non-interactive divergence
+resolution.
+
 ### `npx baldart` (no args) / `doctor` (v3.2.0+)
 
 Smart diagnostic that detects the install state and proposes the next sensible
@@ -474,7 +482,10 @@ npx baldart doctor     # explicit alias (same behaviour)
 
 Show installed framework version, install date, drift from remote (commits
 ahead/behind), uncommitted-files count in `.framework/`, and last-push info.
-Use `--offline` to skip the upstream fetch when offline.
+Use `--offline` to skip the upstream fetch when offline. Use `--json`
+(v3.32.0+) for a machine-readable object (`schema:"baldart.version/1"`) on
+stdout — agents read `installed_version` / `remote_version` / `aligned`
+instead of scraping the human box.
 
 ### `npx baldart push` / `/baldart-push` (v3.1.0+)
 

package/VERSION

@@ -1 +1 @@
-3.31.0
+3.33.0

package/bin/baldart.js

@@ -43,10 +43,16 @@ const CLI_VERSION = resolveVersion();
 // command on a network call.
 const rawArgsForNotifier = process.argv.slice(2);
 const offlineForNotifier = rawArgsForNotifier.includes('--offline');
-updateNotifier.announceAndRefresh({
-  currentVersion: CLI_VERSION,
-  offline: offlineForNotifier,
-});
+// In --json mode STDOUT must carry exactly one JSON object — the notifier hint
+// would pollute it. Suppress the announce entirely (the refresh is harmless but
+// the announce prints to stdout). (v3.32.0+)
+const jsonForNotifier = rawArgsForNotifier.includes('--json');
+if (!jsonForNotifier) {
+  updateNotifier.announceAndRefresh({
+    currentVersion: CLI_VERSION,
+    offline: offlineForNotifier,
+  });
+}
 
 const program = new Command();
 
@@ -59,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);
@@ -73,6 +80,7 @@ program
   .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".')
+  .option('--json', 'Machine-readable output (agents / CI): emit a single JSON result object on stdout, route all human output to stderr. Requires --yes (non-interactive); rejects --reset.')
   .action(async (options) => {
     const updateCommand = require('../src/commands/update');
     await updateCommand(options);
@@ -90,9 +98,10 @@ program
   .command('version')
   .description('Show installed framework version + drift from remote + last-push info')
   .option('--offline', 'Skip the upstream fetch (no remote drift report)')
+  .option('--json', 'Machine-readable output: emit a single JSON object on stdout, route human output to stderr (for agents / CI).')
   .action(async (options) => {
     const versionCommand = require('../src/commands/version');
-    await versionCommand({ offline: !!options.offline });
+    await versionCommand({ offline: !!options.offline, json: !!options.json });
   });
 
 program

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

@@ -15,7 +15,17 @@ 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.31.0
+last_verified: v3.33.0
+-->
+
+<!--
+JSON-OUTPUT NOTE (v3.32.0)
+`npx baldart version --json` and `npx baldart update --json --yes` emit a single
+machine-readable object on stdout (schemas `baldart.version/1` /
+`baldart.update/1`), with all human output on stderr. The skill PREFERS these
+over regex-scraping prose, but keeps the text parser as a fallback for the
+"new skill + old global CLI" transition window. `--json` is a CLI FLAG, not a
+baldart.config.yml key — the schema-change propagation rule does NOT apply.
 -->
 
 <!--
@@ -116,27 +126,46 @@ touches the user's custom content.**
    global CLI crossing the v3.27.0 payload boundary → STOP and report; do not
    launch).
    - Aligned / already up-to-date → report "already current", exit success.
-2. **Launch directly — no preview/stash confirmation:**
+2. **Launch directly — no preview/stash confirmation. Prefer `--json`
+   (v3.32.0+) so the result is a parseable object, not prose:**
    ```bash
-   npx baldart update --yes
+   npx baldart update --json --yes
    ```
    Use the Bash tool with `timeout: 600000`. `--yes` implies `--auto-stash`,
-   so a dirty tree is handled (stashed + re-applied) without asking.
+   so a dirty tree is handled (stashed + re-applied) without asking. `--json`
+   requires `--yes` (it refuses interactively) and routes all human output to
+   stderr — **stdout carries exactly one JSON object**.
    **Do NOT add `--on-divergence pull` or `--reset`.** Bare `--yes` is the
    safe ceiling: the CLI auto-resolves only mechanical noise and *refuses*
    (exits non-zero) on real custom divergence.
-3. **Interpret the exit code (the whole point of staying safe):**
-   - **Exit 0** → update applied (or already aligned). Go to post-flight.
-   - **Exit non-zero** → the CLI hit a wall it will not cross unattended:
-     custom-overlay-able / real-custom divergence, a subtree-pull conflict, or
-     a stale-CLI halt. **STOP. Do NOT retry with `--on-divergence` or
-     `--reset`.** Report loudly (see below) so the human who reads the routine
-     log knows exactly what needs a hands-on decision. Forcing a merge or a
-     reset unattended is precisely the silent destruction this mode forbids.
+
+   **Fallback:** if the CLI predates v3.32.0 it rejects `--json` (unknown
+   option, non-zero exit, empty/garbled stdout). Re-run without it
+   (`npx baldart update --yes`) and fall back to exit-code + stdout-grep
+   interpretation. Never let a missing `--json` block the update.
+3. **Interpret the result — JSON first, exit code as the safety backstop:**
+   - With `--json`, parse the single stdout object. `ok === true` (action
+     `updated` or `already-current`) → success, go to post-flight using
+     `installed_after` / `backup_tag`. `ok === false` → the CLI refused or
+     failed; read `action` (`divergence-refused`, `divergence-scaffolded`,
+     `failed`, `framework-missing`, `usage-error`), `reason`, and
+     `next_command`. Report them verbatim.
+   - The **exit code is still the contract** regardless of `--json`:
+     - **Exit 0** → update applied (or already aligned). Go to post-flight.
+     - **Exit non-zero** → the CLI hit a wall it will not cross unattended:
+       custom-overlay-able / real-custom divergence, a subtree-pull conflict, or
+       a stale-CLI halt. **STOP. Do NOT retry with `--on-divergence` or
+       `--reset`.** Surface the JSON `reason` + `next_command` (or, in fallback
+       mode, the verbatim stderr) so the human who reads the routine log knows
+       exactly what needs a hands-on decision. Forcing a merge or a reset
+       unattended is precisely the silent destruction this mode forbids.
 4. **Post-flight assert (MANDATORY)** — identical to interactive Step 4:
    `cat .framework/VERSION`, compare to the pre-update version. If the CLI
    exited 0 but VERSION did not change (and stdout is not "Already up to
-   date"), **FAIL LOUD** — do not report success.
+   date"), **FAIL LOUD** — do not report success. With `--json` this is a
+   direct check: the result's `installed_after` MUST equal both
+   `.framework/VERSION` and the Step 0 `remote_version`; any mismatch (e.g.
+   `ok:true` but `installed_after` ≠ on-disk VERSION) is the same FAIL LOUD.
 5. **Report** — emit a structured, log-friendly summary (no questions):
    version delta, backup tag + rollback command, any agent-layout migration
    (v3.27.0+), and — on a non-zero exit — the verbatim CLI stderr plus the
@@ -260,7 +289,36 @@ post-flight assert:
 npx baldart version
 ```
 
-**Parser tollerante** — the output format changed in v3.26.0 (version-compare
+#### Preferred: structured `--json` (v3.32.0+) — NO regex
+
+As of v3.32.0 the CLI emits a machine-readable object — read fields instead
+of scraping prose:
+
+```bash
+npx baldart version --json 2>/dev/null
+# → {"schema":"baldart.version/1","installed":true,"installed_version":"3.32.0",
+#    "remote_version":"3.33.0","aligned":false,"offline":false,"fetched":true,
+#    "uncommitted_files":0,"cli_version":"3.32.0","cli_latest":null,
+#    "cli_update_available":false,"repository":"https://github.com/antbald/BALDART",...}
+```
+
+Decision logic on the JSON:
+- `installed === false` → framework not installed → STOP, instruct `npx baldart add`.
+- `aligned === true` → already up-to-date (`installed_version`). STOP.
+- `aligned === false` AND `remote_version !== "unknown"` → continue (save
+  `installed_version` for the post-flight assert, `remote_version` as target).
+- `offline === true` / `fetched === false` → ask the user how to proceed.
+- Still apply the **CLI version drift gate** below using `cli_version` /
+  `cli_latest` (same semver logic).
+
+**Fallback (BLOCKING for the transition window):** if `version --json` errors
+(non-zero exit, unknown-option message, or stdout that is NOT valid JSON), the
+global CLI predates v3.32.0. Do **not** abort — fall back to the **Parser
+tollerante** below, which scrapes the human-readable output. This is the same
+"new skill + old global CLI" case the dual-format text parser already exists
+for. Never remove the text parser.
+
+**Parser tollerante (fallback)** — the output format changed in v3.26.0 (version-compare
 authority instead of subtree-merge commit count). The skill must accept BOTH
 the new and legacy formats so it works during the transition window where
 the consumer has the new skill but an older global CLI.
@@ -440,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.31.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

@@ -28,6 +28,20 @@ function readEnabledTools(cwd = process.cwd()) {
 // agent-overlay feedback that prompted this).
 const DIVERGENCE_STRATEGIES = ['abort', 'pull', 'scaffold-overlays'];
 
+// Machine-readable result channel (v3.32.0+). When --json is active, STDOUT
+// must carry exactly ONE JSON object and nothing else — UI.setJsonMode() has
+// already redirected every human line to STDERR. Every terminal point in the
+// standard flow routes through `emitUpdateJson` so the contract holds: one
+// object, then exit. `ok: true` means "framework is now at the remote version"
+// (action `updated` or `already-current`); everything else is `ok: false`.
+let JSON_MODE = false;
+function emitUpdateJson(obj, exitCode) {
+  if (JSON_MODE) {
+    process.stdout.write(JSON.stringify({ schema: 'baldart.update/1', ...obj }) + '\n');
+  }
+  process.exit(exitCode);
+}
+
 // 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'
@@ -394,6 +408,10 @@ async function maybeRelaunchUnderLatest(options) {
   if (options.commit === false) flags.push('--no-commit');
   if (options.reset === true) flags.push('--reset');
   if (options.iKnow === true) flags.push('--i-know');
+  // Forward the non-interactive resolution + machine-readable flags too, else
+  // a stale-CLI self-relaunch would silently drop them (v3.32.0+).
+  if (options.onDivergence) flags.push('--on-divergence', options.onDivergence);
+  if (options.json === true) flags.push('--json');
 
   const spawn = require('child_process').spawnSync;
   UI.info(`Auto-relaunching via npx baldart@${info.latest}…`);
@@ -421,10 +439,31 @@ async function update(options = {}) {
   const autoStash = autoYes || options.autoStash === true;
   const confirm = async (msg, def = true) => (autoYes ? def : UI.confirm(msg, def));
 
+  // Machine-readable mode (v3.32.0+). Must be fully non-interactive: --json
+  // requires --yes (so no UI.select/confirm can block) and rejects --reset
+  // (the nuclear path is a deliberate destructive human escape hatch, not an
+  // agent flow — see the autonomous /baldart-update skill, which never resets).
+  JSON_MODE = options.json === true;
+  if (JSON_MODE) {
+    UI.setJsonMode(true);
+    if (options.reset === true) {
+      emitUpdateJson({ ok: false, action: 'usage-error',
+        reason: '--json does not support --reset. Reset is an interactive destructive escape hatch; run it manually.' }, 2);
+    }
+    if (!autoYes) {
+      emitUpdateJson({ ok: false, action: 'usage-error',
+        reason: '--json requires --yes (non-interactive). Re-run: npx baldart update --json --yes [--on-divergence pull|scaffold-overlays]' }, 2);
+    }
+  }
+
   // 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)) {
+    if (JSON_MODE) {
+      emitUpdateJson({ ok: false, action: 'usage-error',
+        reason: `Invalid --on-divergence "${divStrategy}". Use one of: ${DIVERGENCE_STRATEGIES.join(', ')}.` }, 1);
+    }
     UI.error(`Invalid --on-divergence "${divStrategy}". Use one of: ${DIVERGENCE_STRATEGIES.join(', ')}.`);
     process.exit(1);
   }
@@ -443,7 +482,9 @@ async function update(options = {}) {
         'Solution:',
         '  Install first: npx baldart add'
       ]);
-      process.exit(1);
+      emitUpdateJson({ ok: false, action: 'framework-missing',
+        reason: 'Framework directory .framework/ not found.',
+        next_command: 'npx baldart add' }, 1);
     }
 
     // v3.26.0+ NUCLEAR OPTION: --reset rips out .framework/ and reinstalls
@@ -480,7 +521,8 @@ async function update(options = {}) {
           UI.error('.framework/ is STILL ignored after auto-heal — likely a parent-dir .gitignore outside this repo.');
           UI.info(`Source: ${heal.recheck.source}:${heal.recheck.line} (${heal.recheck.pattern})`);
           UI.info('Resolve by removing that rule, then re-run `baldart update`.');
-          process.exit(1);
+          emitUpdateJson({ ok: false, action: 'failed',
+            reason: `.framework/ is still ignored after auto-heal (${heal.recheck.source}:${heal.recheck.line}). Remove that .gitignore rule and re-run.` }, 1);
         }
       }
     } catch (err) {
@@ -512,19 +554,24 @@ async function update(options = {}) {
         '  • Check internet connection',
         '  • Try again later'
       ]);
-      process.exit(1);
+      emitUpdateJson({ ok: false, action: 'connect-failed',
+        reason: 'Cannot connect to repository (network / access).' }, 1);
     }
 
     if (!status.fetched || !status.hasFetchHead) {
       UI.error('Could not fetch upstream — try again with network access.');
-      process.exit(1);
+      emitUpdateJson({ ok: false, action: 'fetch-failed',
+        reason: 'Could not fetch upstream — try again with network access.' }, 1);
     }
 
     // VERSION-compare authority. Subtree-merge commit count is noise; never
     // use behind > 0 as the up-to-date signal (root cause of v3.24.x bug).
     if (status.isAligned) {
       UI.success(`Already up to date! (v${status.installedVersion})`);
-      process.exit(0);
+      emitUpdateJson({ ok: true, action: 'already-current',
+        installed_before: status.installedVersion,
+        installed_after: status.installedVersion,
+        remote_version: status.remoteVersion }, 0);
     }
 
     UI.warning(`Update available: v${status.installedVersion} → v${status.remoteVersion}`);
@@ -545,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();
@@ -556,9 +616,18 @@ async function update(options = {}) {
             '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);
+          emitUpdateJson({ ok: false, action: 'divergence-scaffolded',
+            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);
+        }
+        if (divStrategy === 'abort') {
+          UI.info('Update cancelled (--on-divergence abort).');
+          emitUpdateJson({ ok: false, action: 'aborted',
+            divergence_class: status.divergenceClass,
+            reason: 'Update cancelled (--on-divergence abort).' }, 0);
         }
-        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
@@ -568,11 +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');
-          process.exit(1);
+          emitUpdateJson({ ok: false, action: 'divergence-refused',
+            divergence_class: status.divergenceClass, overlay_already_covered: allCovered,
+            installed_before: status.installedVersion, remote_version: status.remoteVersion,
+            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' },
@@ -605,16 +686,29 @@ async function update(options = {}) {
           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);
+            emitUpdateJson({ ok: false, action: 'divergence-refused',
+              divergence_class: status.divergenceClass,
+              installed_before: status.installedVersion, remote_version: status.remoteVersion,
+              reason: 'No overlay-able commits to scaffold — every custom commit touches non-overlayable paths.',
+              next_command: 'npx baldart update --json --yes --on-divergence pull' }, 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);
+          emitUpdateJson({ ok: false, action: 'divergence-scaffolded',
+            divergence_class: status.divergenceClass,
+            installed_before: status.installedVersion, remote_version: status.remoteVersion,
+            reason: 'Scaffolded overlay-able subset; custom-other commit(s) still need handling before pulling.',
+            next_command: 'npx baldart update --json --yes' }, 0);
+        }
+        if (divStrategy === 'abort') {
+          UI.info('Update cancelled (--on-divergence abort).');
+          emitUpdateJson({ ok: false, action: 'aborted',
+            divergence_class: status.divergenceClass,
+            reason: 'Update cancelled (--on-divergence abort).' }, 0);
         }
-        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
@@ -627,7 +721,11 @@ async function update(options = {}) {
             '--on-divergence abort              → do nothing',
           ], 'cyan');
           UI.info('Best practice: contribute generic improvements upstream first with `/baldart-push`.');
-          process.exit(1);
+          emitUpdateJson({ ok: false, action: 'divergence-refused',
+            divergence_class: status.divergenceClass,
+            installed_before: status.installedVersion, remote_version: status.remoteVersion,
+            reason: 'Custom commits present — refusing to pull over them unattended under --yes.',
+            next_command: 'npx baldart update --json --yes --on-divergence pull' }, 1);
         } else {
           const choice = await UI.select('How would you like to proceed?', [
             { name: 'Push these commits upstream first (recommended — `/baldart-push`)', value: 'push' },
@@ -669,6 +767,7 @@ async function update(options = {}) {
     // "fatal: working tree has modifications. Cannot add." Offer to stash
     // and re-apply after the update, so the user doesn't have to abort mid-flow.
     let stashRef = null;
+    let stashConflict = false; // surfaced in the --json result (v3.32.0+)
     const isClean = await git.hasCleanWorkingTree();
     if (!isClean) {
       UI.newline();
@@ -703,7 +802,8 @@ async function update(options = {}) {
         UI.success(`Stashed working tree as "${stashRef}".`);
       } catch (err) {
         UI.error(`Could not stash: ${err.message}`);
-        process.exit(1);
+        emitUpdateJson({ ok: false, action: 'failed',
+          reason: `Could not stash working tree before update: ${err.message}` }, 1);
       }
     }
 
@@ -756,6 +856,7 @@ async function update(options = {}) {
           await git.git.stash(['pop']);
           UI.success(`Re-applied pre-update stash "${stashRef}".`);
         } catch (err) {
+          stashConflict = true;
           UI.newline();
           UI.warning(`Could not auto-re-apply stash "${stashRef}" — conflicts with the framework update.`);
           UI.box('STASH CONFLICT', [
@@ -1006,7 +1107,15 @@ async function update(options = {}) {
     UI.newline();
     UI.success('Framework updated successfully!');
 
+    emitUpdateJson({ ok: true, action: 'updated',
+      installed_before: currentVersion, installed_after: newVersion,
+      remote_version: status.remoteVersion, backup_tag: backupTag,
+      stash_conflict: stashConflict }, 0);
+
   } catch (error) {
+    if (JSON_MODE) {
+      emitUpdateJson({ ok: false, action: 'failed', reason: error.message }, 1);
+    }
     UI.error(`Update failed: ${error.message}`);
     process.exit(1);
   }

package/src/commands/version.js

@@ -30,12 +30,25 @@ async function describeDrift(git, status) {
   };
 }
 
+// Emit a structured JSON object on stdout (v3.32.0+). Used by agents / CI to
+// avoid scraping the human-readable box with fragile regex. Schema is
+// versioned (`baldart.version/1`) so consumers can detect breaking changes.
+function emitVersionJson(obj) {
+  process.stdout.write(JSON.stringify({ schema: 'baldart.version/1', ...obj }) + '\n');
+}
+
 async function version(opts = {}) {
   const git = new GitUtils();
+  const jsonMode = opts.json === true;
+  if (jsonMode) UI.setJsonMode(true);
 
   try {
     const exists = await git.frameworkExists();
     if (!exists) {
+      if (jsonMode) {
+        emitVersionJson({ installed: false, error: 'framework_not_installed' });
+        process.exit(0);
+      }
       UI.warning('Framework not installed');
       UI.info('Install with: npx baldart add');
       process.exit(0);
@@ -63,6 +76,31 @@ async function version(opts = {}) {
     }
     const drift = await describeDrift(git, status);
 
+    // Machine-readable path (v3.32.0+) — emit the structured object and stop.
+    // Mirrors exactly the facts the human box shows below, so the autonomous
+    // /baldart-update skill can read fields instead of regex-scraping prose.
+    if (jsonMode) {
+      emitVersionJson({
+        installed: true,
+        installed_version: frameworkVersion,
+        remote_version: drift.remoteVersion, // string version, or 'unknown'
+        aligned: drift.isAligned,
+        offline: opts.offline === true || !drift.hasFetchHead,
+        fetched: drift.hasFetchHead,
+        uncommitted_files: drift.uncommittedFiles,
+        commits_ahead: drift.ahead,
+        commits_behind: drift.behind,
+        cli_version: cliVersion,
+        cli_latest: cliUpdate ? cliUpdate.latest : null,
+        cli_update_available: !!cliUpdate,
+        repository: `https://github.com/${repo}`,
+        last_update_date: state.last_update_date || null,
+        last_pushed_version: state.last_pushed_version || null,
+        last_push_date: state.last_push_date || null,
+      });
+      return;
+    }
+
     // Messaging based on `isAligned` (not commit count, which is subtree noise).
     let remoteLine;
     if (!drift.hasFetchHead) {
@@ -103,6 +141,10 @@ async function version(opts = {}) {
     UI.box('BALDART VERSION', lines.filter((l) => l !== ''));
     UI.newline();
   } catch (error) {
+    if (jsonMode) {
+      emitVersionJson({ installed: null, error: 'version_failed', reason: error.message });
+      process.exit(1);
+    }
     UI.error(`Failed to get version: ${error.message}`);
     process.exit(1);
   }

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 });
 

package/src/utils/ui.js

@@ -3,6 +3,22 @@ const ora = require('ora');
 const inquirer = require('inquirer');
 
 class UI {
+  // Machine-readable mode (v3.32.0+). When on, every human-facing line that
+  // these helpers emit via `console.log` is redirected to STDERR, leaving
+  // STDOUT free for a single JSON object the caller (agent / CI) can parse.
+  // The JSON itself MUST be written with `process.stdout.write` directly —
+  // never through `console.log` — so it survives this redirect. Reversible;
+  // `ora` spinners already write to stderr, so they need no special handling.
+  static setJsonMode(on) {
+    if (on && !UI._origLog) {
+      UI._origLog = console.log;
+      console.log = (...args) => process.stderr.write(args.join(' ') + '\n');
+    } else if (!on && UI._origLog) {
+      console.log = UI._origLog;
+      UI._origLog = null;
+    }
+  }
+
   static header(text) {
     console.log('');
     console.log(chalk.cyan('━'.repeat(60)));