baldart 3.18.1 → 3.21.1

package/src/commands/doctor.js

@@ -212,8 +212,47 @@ async function detectState(cwd, opts = {}) {
     state.overlays = countOverlays(cwd);
     state.overlaysDrifted = overlayDrift(cwd, state.frameworkVersion);
 
-    state.editGateRegistered = false;
-    try { state.editGateRegistered = Hooks.isRegistered(cwd); } catch (_) {}
+    state.hooksStatus = { malformed: false, hooks: [] };
+    state.hooksMissing = [];
+    state.hooksDrifted = [];
+    state.hooksLegacy = [];
+    try {
+      const status = Hooks.getStatus(cwd);
+      state.hooksStatus = status;
+      if (!status.malformed) {
+        state.hooksMissing  = status.hooks.filter((h) => !h.registered).map((h) => h.id);
+        state.hooksDrifted  = status.hooks.filter((h) => h.registered && h.drift && !h.legacy).map((h) => h.id);
+        state.hooksLegacy   = status.hooks.filter((h) => h.legacy).map((h) => h.id);
+      }
+    } catch (_) {}
+
+    // ---- Agent symlink integrity (since v3.20.0) -----------------------
+    // Source of truth for the BALDART agent list is the framework filesystem
+    // directory itself (`.framework/framework/.claude/agents/*.md`). For each
+    // name, the consumer must have a working `.claude/agents/<name>.md`
+    // (symlink to the framework copy, possibly merged with an overlay).
+    // A missing or broken symlink would otherwise be detected at runtime by
+    // `agent-discovery-gate.js`, blocking Agent calls. This probe lets the
+    // doctor heal it offline before the user hits the gate.
+    state.agentSymlinksBroken = [];
+    try {
+      if (state.frameworkPresent) {
+        const frameworkAgentsDir = path.join(cwd, '.framework', 'framework', '.claude', 'agents');
+        const consumerAgentsDir = path.join(cwd, '.claude', 'agents');
+        if (fs.existsSync(frameworkAgentsDir)) {
+          const baldartAgents = fs.readdirSync(frameworkAgentsDir)
+            .filter((f) => f.endsWith('.md') && f !== 'REGISTRY.md')
+            .map((f) => f.replace(/\.md$/, ''));
+          for (const name of baldartAgents) {
+            try {
+              fs.statSync(path.join(consumerAgentsDir, `${name}.md`));
+            } catch (_) {
+              state.agentSymlinksBroken.push(name);
+            }
+          }
+        }
+      }
+    } catch (_) { /* never block doctor on probe */ }
 
     // `.framework/` is a git subtree — gitignore matching it breaks every
     // future `git add` under that path (the failure mode that hit v3.13.0
@@ -410,15 +449,75 @@ function planActions(state) {
     // Non-blocking — keep looking for other actions to run in the same pass.
   }
 
-  if (state.editGateRegistered === false) {
+  // BALDART hooks (multi-hook registry since v3.18.0).
+  // Three buckets, three actions: missing → propose; legacy → propose
+  // (silent migration to current id); drifted → require interactive prompt.
+  if ((state.hooksMissing && state.hooksMissing.length > 0)
+      || (state.hooksLegacy && state.hooksLegacy.length > 0)) {
+    const ids = [...(state.hooksMissing || []), ...(state.hooksLegacy || [])];
     actions.push({
-      key: 'register-edit-gate',
-      label: 'Register framework-edit-gate hook (.claude/settings.json)',
-      why: 'Prevents project-specific tokens (Neo-Brutalism, merchant, …) from being written to .framework/ accidentally. Standard in v3.3.0+; missing on installs predating that version.',
+      key: 'register-hooks',
+      label: `Register/migrate BALDART hook(s) in .claude/settings.json (${ids.join(', ')})`,
+      why: 'BALDART hooks are missing or registered under a pre-v3.18 layout. They run on PreToolUse/Stop/SessionStart to gate edits and feed the auto-learning loop. Re-registration is idempotent and never overwrites user-customized commands without asking.',
       autoOk: true,
       run: async () => {
-        const res = require('../utils/hooks').register();
-        UI.success(`Hook registered: ${res.status} (${res.path})`);
+        const Hooks = require('../utils/hooks');
+        const res = await Hooks.registerAll(process.cwd(), {
+          onDrift: Hooks.createDriftPrompt(UI, { autoYes: state.autoMode }),
+        });
+        if (res.malformed) {
+          UI.warning('.claude/settings.json is malformed; fix it manually then re-run `npx baldart doctor`.');
+          return;
+        }
+        for (const r of res.results) {
+          if (r.status === 'created') UI.success(`Registered hook \`${r.id}\``);
+          else if (r.status === 'legacy-migrated') UI.success(`Migrated legacy hook to \`${r.id}\` (previous: ${r.previousCommand})`);
+        }
+      },
+    });
+  }
+  if (state.hooksDrifted && state.hooksDrifted.length > 0) {
+    actions.push({
+      key: 'reconcile-hooks-drift',
+      label: `Reconcile drifted BALDART hook(s) (${state.hooksDrifted.join(', ')})`,
+      why: 'These hooks are registered but their command differs from the BALDART default. This is typically a sign of a manual customization or a stale framework version on disk. Reconciliation prompts you per hook (Keep / Replace / Show diff).',
+      autoOk: false, // drift reconciliation is the kind of decision --auto must NOT make
+      run: async () => {
+        const Hooks = require('../utils/hooks');
+        const res = await Hooks.registerAll(process.cwd(), {
+          onDrift: Hooks.createDriftPrompt(UI), // always interactive here
+        });
+        for (const r of res.results) {
+          if (r.status === 'drift-replaced') UI.success(`Replaced \`${r.id}\` (was: ${r.previousCommand})`);
+          else if (r.status === 'drift-kept') UI.info(`Kept \`${r.id}\` as-is.`);
+        }
+      },
+    });
+  }
+
+  // Agent symlink integrity (since v3.20.0). Re-runs the agent merge loop to
+  // recreate any missing per-agent symlink. Calls `SymlinkUtils.mergeAgents`
+  // directly rather than dispatching to `update` — we want only the symlink
+  // pass, not a full update (which would also pull, merge overlays, register
+  // hooks, and verify config drift).
+  if (state.agentSymlinksBroken && state.agentSymlinksBroken.length > 0) {
+    actions.push({
+      key: 'repair-agent-symlinks',
+      label: `Repair ${state.agentSymlinksBroken.length} broken agent symlink(s)`,
+      why: `BALDART expects these agents to be reachable via .claude/agents/<name>.md but the symlinks are missing or broken: ${state.agentSymlinksBroken.join(', ')}. Without these, the agent-discovery-gate PreToolUse hook will deny Agent calls targeting these names.`,
+      autoOk: true,
+      run: async () => {
+        const SymlinkUtils = require('../utils/symlinks');
+        // Re-read the config here (not stashed on state) to pick up
+        // `tools.enabled`. Falls back to ['claude'] if absent/malformed.
+        const cfg = loadConfig(process.cwd());
+        const enabledTools = (cfg && !cfg.__malformed
+          && cfg.tools && Array.isArray(cfg.tools.enabled))
+          ? cfg.tools.enabled
+          : ['claude'];
+        const symlinks = new SymlinkUtils();
+        symlinks.mergeAgents({ tools: enabledTools });
+        UI.success(`Re-merged agent symlinks for tools: ${enabledTools.join(', ')}`);
       },
     });
   }
@@ -616,11 +715,36 @@ function renderDiagnostic(state) {
       console.log(`   • ${o.name} targets v${o.target}, installed v${o.installed}`));
   }
 
-  console.log(statusLine(
-    'Edit gate',
-    state.editGateRegistered ? 'registered' : 'NOT registered (.claude/settings.json)',
-    state.editGateRegistered ? 'ok' : 'warn'
-  ));
+  {
+    const total = state.hooksStatus && state.hooksStatus.hooks ? state.hooksStatus.hooks.length : 0;
+    const missing = state.hooksMissing ? state.hooksMissing.length : 0;
+    const drifted = state.hooksDrifted ? state.hooksDrifted.length : 0;
+    const legacy  = state.hooksLegacy  ? state.hooksLegacy.length  : 0;
+    const registered = total - missing;
+    let summary;
+    let status;
+    if (state.hooksStatus && state.hooksStatus.malformed) {
+      summary = '.claude/settings.json is malformed';
+      status = 'warn';
+    } else if (missing === 0 && drifted === 0 && legacy === 0) {
+      summary = `${registered}/${total} registered`;
+      status = 'ok';
+    } else {
+      const parts = [`${registered}/${total} registered`];
+      if (missing) parts.push(`${missing} missing`);
+      if (drifted) parts.push(`${drifted} drifted`);
+      if (legacy)  parts.push(`${legacy} pre-v3.18`);
+      summary = parts.join(', ');
+      status = 'warn';
+    }
+    console.log(statusLine('BALDART hooks', summary, status));
+    if (state.hooksMissing && state.hooksMissing.length)
+      console.log(`   • missing:   ${state.hooksMissing.join(', ')}`);
+    if (state.hooksDrifted && state.hooksDrifted.length)
+      console.log(`   • drifted:   ${state.hooksDrifted.join(', ')}`);
+    if (state.hooksLegacy && state.hooksLegacy.length)
+      console.log(`   • pre-v3.18: ${state.hooksLegacy.join(', ')}`);
+  }
 
   if (state.frameworkIgnored && state.frameworkIgnored.ignored) {
     console.log(statusLine(
@@ -663,6 +787,7 @@ async function doctor(opts = {}) {
   const offline = !!opts.offline;
 
   const state = await detectState(cwd, { offline });
+  state.autoMode = auto;
   renderDiagnostic(state);
 
   const actions = planActions(state);

package/src/commands/overlay.js

@@ -0,0 +1,381 @@
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const UI = require('../utils/ui');
+const { mergeOverlay, computeBaseFileSha } = require('../utils/overlay-merger');
+
+const FRAMEWORK_DIR = '.framework';
+const FRAMEWORK_PAYLOAD = path.join(FRAMEWORK_DIR, 'framework');
+const OVERLAYS_DIR = path.join('.baldart', 'overlays');
+
+const KINDS = ['skill', 'agent', 'command'];
+
+function frameworkRoot(cwd) {
+  return path.join(cwd, FRAMEWORK_DIR);
+}
+
+function ensureConsumer(cwd) {
+  if (!fs.existsSync(frameworkRoot(cwd))) {
+    UI.error('Not a BALDART consumer repo — `.framework/` not found.');
+    UI.info('Run `npx baldart` to install the framework first.');
+    process.exit(1);
+  }
+}
+
+function readFrameworkVersion(cwd) {
+  try {
+    return fs.readFileSync(path.join(cwd, FRAMEWORK_DIR, 'VERSION'), 'utf8').trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+function baseFilePathFor(cwd, kind, name) {
+  if (kind === 'skill') {
+    return path.join(cwd, FRAMEWORK_PAYLOAD, '.claude', 'skills', name, 'SKILL.md');
+  }
+  return path.join(cwd, FRAMEWORK_PAYLOAD, '.claude', `${kind}s`, `${name}.md`);
+}
+
+function overlayPathFor(cwd, kind, name) {
+  if (kind === 'skill') return path.join(cwd, OVERLAYS_DIR, `${name}.md`);
+  return path.join(cwd, OVERLAYS_DIR, `${kind}s`, `${name}.md`);
+}
+
+function parseTarget(target) {
+  // Accept "agents/coder", "commands/codexreview", "skill/bug", or bare name
+  // (skill assumed). Always normalise to { kind: 'agent'|'command'|'skill', name }.
+  if (!target || typeof target !== 'string') return null;
+  if (target.includes('/')) {
+    const [head, ...rest] = target.split('/');
+    const name = rest.join('/');
+    if (!name) return null;
+    if (head === 'skill' || head === 'skills') return { kind: 'skill', name };
+    if (head === 'agent' || head === 'agents') return { kind: 'agent', name };
+    if (head === 'command' || head === 'commands') return { kind: 'command', name };
+    return null;
+  }
+  return { kind: 'skill', name: target };
+}
+
+function parseFrontmatter(content) {
+  const m = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return { fm: {}, found: false };
+  try {
+    const fm = yaml.load(m[1]) || {};
+    // Coerce `base_file_sha` to string — a 12-char hex SHA may be all digits,
+    // which YAML would otherwise parse as a number (0 → falsy → false drift).
+    if (fm.base_file_sha != null) fm.base_file_sha = String(fm.base_file_sha);
+    return { fm, found: true };
+  } catch (_) {
+    return { fm: {}, found: true, malformed: true };
+  }
+}
+
+function scaffoldBody(kind, name) {
+  if (kind === 'skill') {
+    return [
+      '',
+      `> Skill overlays are concatenated to the base SKILL.md at runtime by the Claude`,
+      `> agent. The merger does NOT parse [OVERRIDE]/[APPEND]/[PREPEND] markers here —`,
+      `> they are textual conventions for the agent. Use \`mode: override\` in`,
+      `> frontmatter to replace the base skill entirely.`,
+      '',
+      `## [APPEND] Project-specific guidance`,
+      '',
+      `<!-- Add the rules / vocabulary / opinions that apply to THIS project. -->`,
+      '',
+    ].join('\n');
+  }
+  return [
+    '',
+    `> Section markers (parsed by overlay-merger.js):`,
+    `>   ## [OVERRIDE] <H2> — replace base section verbatim`,
+    `>   ## [APPEND]   <H2> — add overlay content after base section`,
+    `>   ## [PREPEND]  <H2> — add overlay content before base section`,
+    `>   ## <H2>            — appended as a new section at the end`,
+    '',
+    `## [APPEND] <heading from base ${kind} "${name}">`,
+    '',
+    `<!-- Replace the heading above with one that exists in the base file. -->`,
+    '',
+  ].join('\n');
+}
+
+function buildFrontmatter({ kind, name, frameworkVersion, baseSha, mode }) {
+  const lines = ['---'];
+  lines.push(`base_${kind}: ${name}`);
+  lines.push(`base_${kind}_version: ${frameworkVersion || 'unknown'}`);
+  // Quote the SHA — a 12-char hex string can be all digits, which YAML would
+  // otherwise parse as a number (0 → falsy → false-negative in drift check).
+  if (baseSha) lines.push(`base_file_sha: "${baseSha}"`);
+  lines.push(`mode: ${mode || 'extend'}`);
+  lines.push('---');
+  return lines.join('\n') + '\n';
+}
+
+// ─── scaffold ──────────────────────────────────────────────────────────────
+
+async function scaffold(target, options = {}) {
+  const cwd = process.cwd();
+  ensureConsumer(cwd);
+
+  const parsed = parseTarget(target);
+  if (!parsed) {
+    UI.error('Invalid target. Use: skill/<name>, agents/<name>, or commands/<name>.');
+    UI.info('Example: npx baldart overlay scaffold agents/coder');
+    process.exit(1);
+  }
+  const { kind, name } = parsed;
+
+  const baseAbs = baseFilePathFor(cwd, kind, name);
+  if (!fs.existsSync(baseAbs)) {
+    UI.error(`Base ${kind} "${name}" not found at ${path.relative(cwd, baseAbs)}.`);
+    UI.info(`Run \`ls ${path.relative(cwd, path.dirname(baseAbs))}\` to list available ${kind}s.`);
+    process.exit(1);
+  }
+
+  const overlayAbs = overlayPathFor(cwd, kind, name);
+  const overlayRel = path.relative(cwd, overlayAbs);
+
+  if (fs.existsSync(overlayAbs)) {
+    UI.warning(`Overlay already exists: ${overlayRel}`);
+    UI.info('Run `npx baldart overlay drift ' + overlayRel + '` to check it, or edit it directly to extend.');
+    process.exit(0);
+  }
+
+  fs.mkdirSync(path.dirname(overlayAbs), { recursive: true });
+
+  const baseContent = fs.readFileSync(baseAbs, 'utf8');
+  const baseSha = computeBaseFileSha(baseContent);
+  const fwVersion = readFrameworkVersion(cwd);
+  const mode = (options.mode || 'extend').trim();
+  if (!['extend', 'override'].includes(mode)) {
+    UI.error(`Invalid --mode "${mode}". Use "extend" or "override".`);
+    process.exit(1);
+  }
+
+  const content =
+    buildFrontmatter({ kind, name, frameworkVersion: fwVersion, baseSha, mode }) +
+    scaffoldBody(kind, name);
+
+  fs.writeFileSync(overlayAbs, content);
+  UI.success(`Created ${overlayRel}`);
+  UI.info(`Base file: ${path.relative(cwd, baseAbs)}`);
+  UI.info(`Targets framework v${fwVersion || 'unknown'} (base_file_sha=${baseSha}).`);
+  UI.newline();
+  UI.list([
+    `Edit ${overlayRel} to add your customisations.`,
+    `Validate the merge with: npx baldart overlay validate ${overlayRel}`,
+    kind === 'skill'
+      ? `Run any /-command that uses this skill to see the overlay applied at runtime.`
+      : `Apply with: npx baldart update (regenerates .claude/${kind}s/${name}.md from base + overlay).`,
+  ]);
+}
+
+// ─── validate ──────────────────────────────────────────────────────────────
+
+function deriveTargetFromOverlayPath(cwd, overlayPath) {
+  const abs = path.isAbsolute(overlayPath) ? overlayPath : path.join(cwd, overlayPath);
+  const root = path.join(cwd, OVERLAYS_DIR);
+  const rel = path.relative(root, abs);
+  if (rel.startsWith('..')) return null;
+  const parts = rel.split(path.sep);
+  if (parts.length === 1) {
+    return { kind: 'skill', name: parts[0].replace(/\.md$/, ''), abs };
+  }
+  if (parts.length === 2) {
+    const sub = parts[0];
+    if (sub === 'agents') return { kind: 'agent', name: parts[1].replace(/\.md$/, ''), abs };
+    if (sub === 'commands') return { kind: 'command', name: parts[1].replace(/\.md$/, ''), abs };
+  }
+  return null;
+}
+
+async function validate(overlayPath) {
+  const cwd = process.cwd();
+  ensureConsumer(cwd);
+
+  if (!overlayPath) {
+    UI.error('Usage: npx baldart overlay validate <path>');
+    UI.info('Example: npx baldart overlay validate .baldart/overlays/agents/coder.md');
+    process.exit(1);
+  }
+
+  const t = deriveTargetFromOverlayPath(cwd, overlayPath);
+  if (!t) {
+    UI.error(`Path is not under ${OVERLAYS_DIR}/ or has unexpected shape: ${overlayPath}`);
+    process.exit(1);
+  }
+  if (!fs.existsSync(t.abs)) {
+    UI.error(`Overlay file not found: ${path.relative(cwd, t.abs)}`);
+    process.exit(1);
+  }
+
+  const overlayContent = fs.readFileSync(t.abs, 'utf8');
+  const { fm, found, malformed } = parseFrontmatter(overlayContent);
+  if (!found) {
+    UI.error('Overlay has no YAML frontmatter.');
+    process.exit(1);
+  }
+  if (malformed) {
+    UI.error('Overlay frontmatter is not valid YAML.');
+    process.exit(1);
+  }
+  const expectedKindField = `base_${t.kind}`;
+  if (fm[expectedKindField] !== t.name) {
+    UI.error(`Frontmatter mismatch: expected ${expectedKindField}: ${t.name} (got ${fm[expectedKindField] || 'missing'}).`);
+    process.exit(1);
+  }
+
+  const baseAbs = baseFilePathFor(cwd, t.kind, t.name);
+  if (!fs.existsSync(baseAbs)) {
+    UI.error(`Base ${t.kind} "${t.name}" not found at ${path.relative(cwd, baseAbs)}.`);
+    process.exit(1);
+  }
+
+  if (t.kind === 'skill') {
+    UI.success(`Overlay valid (skill, concat model).`);
+    UI.info(`Targets v${fm.base_skill_version || 'unknown'}, mode=${fm.mode || 'extend'}.`);
+    if (fm.base_file_sha) {
+      const currentSha = computeBaseFileSha(fs.readFileSync(baseAbs, 'utf8'));
+      if (currentSha !== fm.base_file_sha) {
+        UI.warning(`Base file changed since overlay was authored (sha ${fm.base_file_sha} → ${currentSha}). Review for drift.`);
+      } else {
+        UI.success('Base file unchanged since overlay was authored.');
+      }
+    } else {
+      UI.info('No base_file_sha in frontmatter — drift check by version only.');
+    }
+    return;
+  }
+
+  // Agent/command — dry-run the merger.
+  const baseContent = fs.readFileSync(baseAbs, 'utf8');
+  const fwVersion = readFrameworkVersion(cwd);
+  let result;
+  try {
+    result = mergeOverlay({
+      kind: t.kind,
+      name: t.name,
+      baseContent,
+      overlayContent,
+      frameworkVersion: fwVersion
+    });
+  } catch (err) {
+    UI.error(`Merger threw: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (result.warnings && result.warnings.length) {
+    result.warnings.forEach((w) => UI.warning(w));
+  }
+  UI.success(`Overlay valid (${t.kind}, marker model).`);
+  UI.info(`Targets v${result.baseVersionTargeted}, mode=${result.overlayMode}.`);
+  UI.info(`Generated output: ${result.generated.split('\n').length} lines.`);
+  if (fm.base_file_sha) {
+    const currentSha = computeBaseFileSha(baseContent);
+    if (currentSha !== fm.base_file_sha) {
+      UI.warning(`Base file changed since overlay was authored (sha ${fm.base_file_sha} → ${currentSha}). Review for drift.`);
+    } else {
+      UI.success('Base file unchanged since overlay was authored.');
+    }
+  }
+}
+
+// ─── drift ─────────────────────────────────────────────────────────────────
+
+function collectOverlays(cwd) {
+  const root = path.join(cwd, OVERLAYS_DIR);
+  if (!fs.existsSync(root)) return [];
+  const out = [];
+  const pushFrom = (sub, kind) => {
+    const dir = sub ? path.join(root, sub) : root;
+    if (!fs.existsSync(dir)) return;
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.md')) continue;
+      if (f.endsWith('.example.md')) continue;
+      if (sub === '' && (f === 'README.md')) continue;
+      out.push({ kind, name: f.replace(/\.md$/, ''), abs: path.join(dir, f), rel: path.join(OVERLAYS_DIR, sub || '', f) });
+    }
+  };
+  pushFrom('', 'skill');
+  pushFrom('agents', 'agent');
+  pushFrom('commands', 'command');
+  return out;
+}
+
+async function drift(target, options = {}) {
+  const cwd = process.cwd();
+  ensureConsumer(cwd);
+
+  const fwVersion = readFrameworkVersion(cwd);
+  const all = !!options.all || !target;
+  const targets = [];
+  if (all) {
+    targets.push(...collectOverlays(cwd));
+  } else {
+    const t = deriveTargetFromOverlayPath(cwd, target);
+    if (!t) {
+      UI.error(`Path is not under ${OVERLAYS_DIR}/ or has unexpected shape: ${target}`);
+      process.exit(1);
+    }
+    if (!fs.existsSync(t.abs)) {
+      UI.error(`Overlay not found: ${path.relative(cwd, t.abs)}`);
+      process.exit(1);
+    }
+    targets.push({ kind: t.kind, name: t.name, abs: t.abs, rel: path.relative(cwd, t.abs) });
+  }
+
+  if (targets.length === 0) {
+    UI.info('No overlays authored.');
+    return;
+  }
+
+  let drifted = 0;
+  let unknown = 0;
+  let clean = 0;
+  for (const t of targets) {
+    const content = fs.readFileSync(t.abs, 'utf8');
+    const { fm } = parseFrontmatter(content);
+    const versionField = `base_${t.kind}_version`;
+    const overlayVersion = fm[versionField];
+    const baseAbs = baseFilePathFor(cwd, t.kind, t.name);
+    const baseExists = fs.existsSync(baseAbs);
+
+    if (!baseExists) {
+      UI.error(`${t.rel}: base ${t.kind} "${t.name}" no longer exists in framework.`);
+      drifted++;
+      continue;
+    }
+
+    const baseSha = computeBaseFileSha(fs.readFileSync(baseAbs, 'utf8'));
+    let shaDrift = null;
+    if (fm.base_file_sha) {
+      shaDrift = fm.base_file_sha !== baseSha;
+    }
+    const versionDrift = overlayVersion && fwVersion && overlayVersion !== fwVersion;
+
+    if (shaDrift === true) {
+      UI.warning(`${t.rel}: base file changed since overlay was authored (sha ${fm.base_file_sha} → ${baseSha}).`);
+      drifted++;
+    } else if (shaDrift === false) {
+      UI.success(`${t.rel}: clean (sha matches base v${fwVersion}).`);
+      clean++;
+    } else if (versionDrift) {
+      UI.warning(`${t.rel}: targets v${overlayVersion}, installed v${fwVersion} — review (no base_file_sha to confirm).`);
+      unknown++;
+    } else if (overlayVersion) {
+      UI.info(`${t.rel}: targets v${overlayVersion} (no base_file_sha — drift unknown).`);
+      unknown++;
+    } else {
+      UI.warning(`${t.rel}: no base_${t.kind}_version in frontmatter.`);
+      unknown++;
+    }
+  }
+
+  UI.newline();
+  UI.info(`Summary: ${clean} clean, ${drifted} drifted, ${unknown} unknown — of ${targets.length} overlay(s).`);
+}
+
+module.exports = { scaffold, validate, drift };

package/src/commands/update.js

@@ -400,13 +400,25 @@ async function update(options = {}) {
       UI.warning(`Routines wizard skipped: ${err.message}`);
     }
 
-    // Framework-edit-gate hook (since v3.3.0) — backfill for consumers
-    // installed before v3.3.0 didn't have this hook. We register it on every
-    // update (idempotent — no-op if already present).
+    // BALDART hooks (multi-hook registry since v3.18.0) — backfill for
+    // consumers that predate any of the hooks shipped in the current
+    // framework version. Idempotent: no-op when every hook is already in
+    // place. Drift on an existing entry triggers an interactive prompt
+    // (Keep / Replace / Show diff); on --auto / -y the default is 'keep'.
     try {
-      const res = Hooks.register();
-      if (res.status === 'created' || res.status === 'updated') {
-        UI.success('Registered framework-edit-gate hook in .claude/settings.json (v3.3.0+ default).');
+      const res = await Hooks.registerAll(process.cwd(), {
+        onDrift: Hooks.createDriftPrompt(UI, { autoYes }),
+      });
+      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 (v3.18.0+ default).`);
+          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.`);
+          // 'already' is silent on update to avoid noise
+        }
       }
     } catch (err) {
       UI.warning(`Hook registration skipped: ${err.message}`);