@lh8ppl/claude-memory-kit 0.1.0 → 0.1.2

package/src/reindex.mjs

@@ -1,134 +1,134 @@
-// Granular-archive pointer-index writer (Task 8, refactored in
-// cleanup-layer-2-cross-module-drift). Single public boundary:
-// reindex(opts) → result. See design §2.3.
-//
-// Uses shared modules: tier-paths (path resolution), frontmatter (js-yaml
-// parse). See CLAUDE.md "Shared modules" rule.
-
-import {
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  writeFileSync,
-} from 'node:fs';
-import { join } from 'node:path';
-import { VALID_TIERS, resolveTierRoot, resolveFactDir } from './tier-paths.mjs';
-import { parse } from './frontmatter.mjs';
-
-const INDEX_SIZE_WARN_BYTES = 25 * 1024;
-const HOOK_MAX_LEN = 80;
-
-const TIER_LABEL = {
-  P: 'project tier',
-  L: 'local tier',
-  U: 'user tier',
-};
-
-function extractHook(body) {
-  for (const raw of body.split('\n')) {
-    const line = raw.trim();
-    if (!line) continue;
-    if (line.startsWith('#')) continue;
-    if (line.length > HOOK_MAX_LEN) {
-      return line.slice(0, HOOK_MAX_LEN).trimEnd() + '...';
-    }
-    return line;
-  }
-  return '';
-}
-
-function formatIndexLine({ id, type, title, filename, hook }) {
-  const head = `- (${id}) [${type}] [${title}](${filename})`;
-  return hook ? `${head} — ${hook}` : head;
-}
-
-function listFactFiles(factDir) {
-  if (!existsSync(factDir)) return [];
-  const out = [];
-  for (const entry of readdirSync(factDir, { withFileTypes: true })) {
-    if (!entry.isFile()) continue;
-    if (!entry.name.endsWith('.md')) continue;
-    if (entry.name === 'INDEX.md') continue;
-    out.push(entry.name);
-  }
-  return out.sort();
-}
-
-export function reindex(opts = {}) {
-  const { tier, projectRoot, userDir, warn } = opts;
-  if (!tier || !VALID_TIERS.has(tier)) {
-    throw new Error(
-      `reindex: invalid tier ${JSON.stringify(tier)}. Must be 'U', 'P', or 'L'.`,
-    );
-  }
-  const emit = warn ?? ((msg) => process.stderr.write(msg + '\n'));
-  const warnings = [];
-  function pushWarning(msg) {
-    warnings.push(msg);
-    emit(msg);
-  }
-
-  const tierRoot = resolveTierRoot({ tier, projectRoot, userDir });
-  const factDir = resolveFactDir(tier, tierRoot);
-  mkdirSync(factDir, { recursive: true });
-
-  const entries = [];
-  for (const filename of listFactFiles(factDir)) {
-    const path = join(factDir, filename);
-    let text;
-    try {
-      text = readFileSync(path, 'utf8');
-    } catch (e) {
-      pushWarning(`reindex: failed to read ${filename}: ${e.message}`);
-      continue;
-    }
-    const { frontmatter, body, parseError } = parse(text);
-    if (!frontmatter) {
-      pushWarning(
-        `reindex: ${filename} skipped — ${parseError ?? 'no YAML frontmatter'}`,
-      );
-      continue;
-    }
-    if (!frontmatter.id || !frontmatter.type || !frontmatter.title) {
-      pushWarning(
-        `reindex: ${filename} skipped — missing required frontmatter field(s) (id/type/title)`,
-      );
-      continue;
-    }
-    if (frontmatter.deleted_at) continue;
-    entries.push({
-      id: frontmatter.id,
-      type: frontmatter.type,
-      title: frontmatter.title,
-      filename,
-      hook: extractHook(body),
-    });
-  }
-
-  entries.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
-
-  const header = `# Granular memory index — ${TIER_LABEL[tier]}\n\n## Files\n`;
-  const bodyLines = entries.map(formatIndexLine).join('\n');
-  const content = entries.length
-    ? `${header}\n${bodyLines}\n`
-    : `${header}\n`;
-
-  const indexPath = join(factDir, 'INDEX.md');
-  writeFileSync(indexPath, content, 'utf8');
-
-  const bytes = Buffer.byteLength(content, 'utf8');
-  if (bytes > INDEX_SIZE_WARN_BYTES) {
-    pushWarning(
-      `reindex: ${indexPath} is ${(bytes / 1024).toFixed(1)} KB (>25 KB); consider consolidation`,
-    );
-  }
-
-  return {
-    tier,
-    indexPath,
-    factCount: entries.length,
-    bytes,
-    warnings,
-  };
-}
+// Granular-archive pointer-index writer (Task 8, refactored in
+// cleanup-layer-2-cross-module-drift). Single public boundary:
+// reindex(opts) → result. See design §2.3.
+//
+// Uses shared modules: tier-paths (path resolution), frontmatter (js-yaml
+// parse). See CLAUDE.md "Shared modules" rule.
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { VALID_TIERS, resolveTierRoot, resolveFactDir } from './tier-paths.mjs';
+import { parse } from './frontmatter.mjs';
+
+const INDEX_SIZE_WARN_BYTES = 25 * 1024;
+const HOOK_MAX_LEN = 80;
+
+const TIER_LABEL = {
+  P: 'project tier',
+  L: 'local tier',
+  U: 'user tier',
+};
+
+function extractHook(body) {
+  for (const raw of body.split('\n')) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (line.startsWith('#')) continue;
+    if (line.length > HOOK_MAX_LEN) {
+      return line.slice(0, HOOK_MAX_LEN).trimEnd() + '...';
+    }
+    return line;
+  }
+  return '';
+}
+
+function formatIndexLine({ id, type, title, filename, hook }) {
+  const head = `- (${id}) [${type}] [${title}](${filename})`;
+  return hook ? `${head} — ${hook}` : head;
+}
+
+function listFactFiles(factDir) {
+  if (!existsSync(factDir)) return [];
+  const out = [];
+  for (const entry of readdirSync(factDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith('.md')) continue;
+    if (entry.name === 'INDEX.md') continue;
+    out.push(entry.name);
+  }
+  return out.sort();
+}
+
+export function reindex(opts = {}) {
+  const { tier, projectRoot, userDir, warn } = opts;
+  if (!tier || !VALID_TIERS.has(tier)) {
+    throw new Error(
+      `reindex: invalid tier ${JSON.stringify(tier)}. Must be 'U', 'P', or 'L'.`,
+    );
+  }
+  const emit = warn ?? ((msg) => process.stderr.write(msg + '\n'));
+  const warnings = [];
+  function pushWarning(msg) {
+    warnings.push(msg);
+    emit(msg);
+  }
+
+  const tierRoot = resolveTierRoot({ tier, projectRoot, userDir });
+  const factDir = resolveFactDir(tier, tierRoot);
+  mkdirSync(factDir, { recursive: true });
+
+  const entries = [];
+  for (const filename of listFactFiles(factDir)) {
+    const path = join(factDir, filename);
+    let text;
+    try {
+      text = readFileSync(path, 'utf8');
+    } catch (e) {
+      pushWarning(`reindex: failed to read ${filename}: ${e.message}`);
+      continue;
+    }
+    const { frontmatter, body, parseError } = parse(text);
+    if (!frontmatter) {
+      pushWarning(
+        `reindex: ${filename} skipped — ${parseError ?? 'no YAML frontmatter'}`,
+      );
+      continue;
+    }
+    if (!frontmatter.id || !frontmatter.type || !frontmatter.title) {
+      pushWarning(
+        `reindex: ${filename} skipped — missing required frontmatter field(s) (id/type/title)`,
+      );
+      continue;
+    }
+    if (frontmatter.deleted_at) continue;
+    entries.push({
+      id: frontmatter.id,
+      type: frontmatter.type,
+      title: frontmatter.title,
+      filename,
+      hook: extractHook(body),
+    });
+  }
+
+  entries.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+  const header = `# Granular memory index — ${TIER_LABEL[tier]}\n\n## Files\n`;
+  const bodyLines = entries.map(formatIndexLine).join('\n');
+  const content = entries.length
+    ? `${header}\n${bodyLines}\n`
+    : `${header}\n`;
+
+  const indexPath = join(factDir, 'INDEX.md');
+  writeFileSync(indexPath, content, 'utf8');
+
+  const bytes = Buffer.byteLength(content, 'utf8');
+  if (bytes > INDEX_SIZE_WARN_BYTES) {
+    pushWarning(
+      `reindex: ${indexPath} is ${(bytes / 1024).toFixed(1)} KB (>25 KB); consider consolidation`,
+    );
+  }
+
+  return {
+    tier,
+    indexPath,
+    factCount: entries.length,
+    bytes,
+    warnings,
+  };
+}

package/src/repair.mjs

@@ -16,14 +16,10 @@
 // Per design §14 + tasks.md 39 (39.1–39.3).
 
 import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
   statSync,
   unlinkSync,
-  writeFileSync,
 } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import {
   appendAuditEntry,
   nowIso,
@@ -31,104 +27,38 @@ import {
 } from './audit-log.mjs';
 import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
 import { detectStaleLocks } from './lock-discipline.mjs';
+import { writeKitHooks } from './settings-hooks.mjs';
 
 const DEFAULT_STALE_LOCK_MS = 60 * 60 * 1000; // 1 hour
 const SETTINGS_REL = ['.claude', 'settings.json'];
 
-// I1 fix (Task 39 skill-review 2026-05-28): the canonical hooks block
-// is embedded INLINE as a JS constant instead of being read from
-// plugin/hooks/hooks.json. Rationale: packages/cli/package.json `files`
-// lists ['bin/', 'src/', 'README.md'] — the plugin/ tree is OUTSIDE the
-// published @lh8ppl/claude-memory-kit tarball. Reading from plugin/ works
-// in-repo (where __dirname resolves up to the repo root) but breaks
-// post-`npm install -g` where plugin/ doesn't exist.
+// Task 49 (2026-05-29): the canonical hooks block + the read-merge-write
+// logic moved to settings-hooks.mjs (single source of truth, shared with
+// install.mjs). It also switched from the PLUGIN form (`bash
+// "${CLAUDE_PLUGIN_ROOT}/bin/<name>"`, 6 events incl. Setup) to the
+// npm-route form (PATH-resolved bare bin names, 5 events) so that
+// `cmk repair --hooks` produces hooks that work with NO plugin loaded —
+// matching `cmk install`'s new posture as a complete entry point. The
+// full decision trail (incl. why Setup/cmk-version-check is dropped and
+// where the plugin form still lives) is documented in settings-hooks.mjs.
 //
-// Same Task-33-B1 class of bug: cron-emission paths were also broken
-// post-npm-install-g until they embedded absolute paths at registration
-// time. The embed-the-canonical-constant pattern is the durable fix.
-//
-// Source of truth: keep this in sync with plugin/hooks/hooks.json. A
-// future validator (scripts/validate-hooks-block-sync.mjs) would catch
-// drift automatically; v0.1.x candidate.
-const KIT_HOOKS_BLOCK = Object.freeze({
-  Setup: [{ hooks: [{ type: 'command', command: 'bash "${CLAUDE_PLUGIN_ROOT}/bin/cmk-version-check"', timeout: 30 }] }],
-  SessionStart: [{ hooks: [{ type: 'command', command: 'bash "${CLAUDE_PLUGIN_ROOT}/bin/cmk-inject-context"', timeout: 30 }] }],
-  UserPromptSubmit: [{ hooks: [{ type: 'command', command: 'bash "${CLAUDE_PLUGIN_ROOT}/bin/cmk-capture-prompt"', timeout: 10 }] }],
-  PostToolUse: [{ matcher: 'Write|Edit|MultiEdit', hooks: [{ type: 'command', command: 'bash "${CLAUDE_PLUGIN_ROOT}/bin/cmk-observe-edit"', async: true, timeout: 120 }] }],
-  Stop: [{ hooks: [{ type: 'command', command: 'bash "${CLAUDE_PLUGIN_ROOT}/bin/cmk-capture-turn"', timeout: 30 }] }],
-  SessionEnd: [{ hooks: [{ type: 'command', command: 'bash "${CLAUDE_PLUGIN_ROOT}/bin/cmk-compress-session"', timeout: 60 }] }],
-});
+// Pre-Task-49 history (kept for the trail): the block was previously
+// embedded inline here as a fix for the I1 finding (Task 39 skill-review,
+// 2026-05-28) — reading from plugin/hooks/hooks.json broke post-npm-install-g
+// because the plugin/ tree is outside the published tarball. The inline
+// constant fixed that; Task 49 then extracted it to the shared module.
 
 /**
  * Repair `<projectRoot>/.claude/settings.json` by merging in the kit's
- * canonical hooks block. Preserves any other top-level keys + non-kit
- * hook entries (e.g., the user's own PreToolUse hooks under different
- * matchers).
+ * canonical hooks block (via the shared writeKitHooks boundary).
+ * Preserves any other top-level keys + non-kit hook entries.
  */
 function repairHooks({ projectRoot, ts }) {
-  // I1 fix: use the inlined KIT_HOOKS_BLOCK constant; no file read,
-  // no npm-install-g brittleness.
-  const kitHooks = KIT_HOOKS_BLOCK;
-
   const settingsPath = join(projectRoot, ...SETTINGS_REL);
-  let settings = {};
-  if (existsSync(settingsPath)) {
-    try {
-      settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
-    } catch (err) {
-      return {
-        kind: 'hooks',
-        changed: false,
-        error: `${settingsPath} parse error: ${err?.message ?? err}`,
-      };
-    }
-  }
-
-  const before = JSON.stringify(settings);
-  if (!settings.hooks || typeof settings.hooks !== 'object') {
-    settings.hooks = {};
-  }
-
-  // Merge each event array: replace the kit's hook entries (matched by
-  // command substring) with the canonical version; keep any user-added
-  // entries that don't reference the kit.
-  const KIT_COMMAND_TOKENS = [
-    'cmk-version-check',
-    'cmk-inject-context',
-    'cmk-capture-prompt',
-    'cmk-observe-edit',
-    'cmk-capture-turn',
-    'cmk-compress-session',
-  ];
-  const isKitEntry = (entry) => {
-    if (!entry || typeof entry !== 'object') return false;
-    // Entry shape varies: {command} or {hooks: [{command}]}.
-    const collectCommands = (e) => {
-      const cmds = [];
-      if (typeof e.command === 'string') cmds.push(e.command);
-      if (Array.isArray(e.hooks)) {
-        for (const h of e.hooks) if (typeof h.command === 'string') cmds.push(h.command);
-      }
-      return cmds;
-    };
-    const cmds = collectCommands(entry);
-    return cmds.some((c) => KIT_COMMAND_TOKENS.some((t) => c.includes(t)));
-  };
-
-  for (const [eventName, kitEntries] of Object.entries(kitHooks)) {
-    const existing = Array.isArray(settings.hooks[eventName])
-      ? settings.hooks[eventName]
-      : [];
-    const userEntries = existing.filter((e) => !isKitEntry(e));
-    settings.hooks[eventName] = [...userEntries, ...kitEntries];
-  }
-
-  const after = JSON.stringify(settings);
-  const changed = before !== after;
+  const r = writeKitHooks(settingsPath);
 
-  if (changed) {
-    mkdirSync(dirname(settingsPath), { recursive: true });
-    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+  if (r.error) {
+    return { kind: 'hooks', changed: false, error: r.error };
   }
 
   // I3 fix (Task 39 skill-review 2026-05-28): emit a Door-4 audit
@@ -141,8 +71,8 @@ function repairHooks({ projectRoot, ts }) {
       action: 'repair',
       tier: 'P',
       id: 'P-RPHKAPLD', // synthetic stable id for hooks-repair events (base32 alphabet)
-      reasonCode: changed ? REASON_CODES.REPAIR_HOOKS_APPLIED : REASON_CODES.REPAIR_HOOKS_NOOP,
-      extra: { settingsPath, events: Object.keys(kitHooks) },
+      reasonCode: r.changed ? REASON_CODES.REPAIR_HOOKS_APPLIED : REASON_CODES.REPAIR_HOOKS_NOOP,
+      extra: { settingsPath: r.settingsPath, events: r.events },
     });
   } catch {
     // best-effort — never block repair on audit-log failure
@@ -150,9 +80,9 @@ function repairHooks({ projectRoot, ts }) {
 
   return {
     kind: 'hooks',
-    changed,
-    settingsPath,
-    events: Object.keys(kitHooks),
+    changed: r.changed,
+    settingsPath: r.settingsPath,
+    events: r.events,
   };
 }
 

package/src/sanitize.mjs

@@ -0,0 +1,39 @@
+// sanitize.mjs — privacy sanitizers applied before durable writes to a
+// committed/shared tier. Sibling to poison-guard.mjs, but where Poison_Guard
+// REJECTS a write (secrets/poison), these REWRITE it (privacy abstraction).
+//
+// Write-path fix #1 (the self-test privacy leak): a durable fact written to a
+// committed project tier carried the local username inside an absolute
+// interpreter path (C:\Users\<you>\...\python.exe), shipping it to git and
+// making the fact non-portable. sanitizeHomePaths abstracts the home-dir
+// prefix to `~` — killing the username leak AND making the fact portable
+// across machines — while preserving everything after the home dir.
+//
+// Applied to P (committed) and U (cross-project) tier writes. NOT to L
+// (local, gitignored) — machine-specific absolute paths are the whole point
+// of the local tier, so they stay verbatim there.
+
+// Each pattern matches an absolute home-directory prefix up to (but not
+// including) the next path separator / whitespace / quote, so the remainder
+// of the path is preserved. Username char class excludes separators, spaces,
+// quotes, and shell/redirect metacharacters.
+const USER = "[^\\\\/\\s\"'`<>|]+";
+// Case-INSENSITIVE: Windows + macOS filesystems are case-insensitive, so a
+// fact may carry `c:\users\you\…` or `/users/you`; the `i` flag keeps the
+// privacy abstraction from being bypassed by lowercasing.
+const HOME_PATH_PATTERNS = [
+  new RegExp(`[A-Za-z]:[\\\\/]Users[\\\\/]${USER}`, 'gi'), // Windows C:\Users\name (either slash)
+  new RegExp(`/Users/${USER}`, 'gi'), // macOS /Users/name
+  new RegExp(`/home/${USER}`, 'gi'), // Linux /home/name
+];
+
+/**
+ * Abstract absolute home-directory prefixes to `~`. Returns non-string input
+ * unchanged (callers may pass undefined for optional fields).
+ */
+export function sanitizeHomePaths(text) {
+  if (typeof text !== 'string') return text;
+  let out = text;
+  for (const re of HOME_PATH_PATTERNS) out = out.replace(re, '~');
+  return out;
+}

package/src/settings-hooks.mjs

@@ -0,0 +1,186 @@
+// settings-hooks.mjs — the canonical npm-route hooks block + the
+// read-merge-write logic that wires it into a project's
+// <projectRoot>/.claude/settings.json. (Task 49, T-037.)
+//
+// SINGLE SOURCE OF TRUTH for the npm-route hook wiring. Both
+// `cmk install` (install.mjs — the complete npm entry point) and
+// `cmk repair --hooks` (repair.mjs) import from here. Before Task 49
+// the block lived inline in repair.mjs as `KIT_HOOKS_BLOCK`; it was
+// extracted + de-plugin-ified here so install can share it.
+//
+// ─────────────────────────────────────────────────────────────────────
+// Command form: SHELL form (no `args`), bare bin name. WHY (verified
+// against Anthropic's hooks docs, https://code.claude.com/docs/en/hooks,
+// 2026-05-29):
+//
+//   - Hook commands with `args` present run in EXEC form (no shell). On
+//     Windows, exec form requires `command` to resolve to a REAL
+//     executable (.exe) — the docs explicitly warn that the `.cmd`/`.ps1`
+//     shims npm installs for `bin` entries "cannot be spawned without a
+//     shell". So exec form + a bare `cmk-inject-context` would FAIL on
+//     Windows.
+//   - Hook commands WITHOUT `args` run in SHELL form: `sh -c "<command>"`
+//     on macOS/Linux, Git Bash (or PowerShell) on Windows. The shell
+//     resolves the bare name on PATH — picking up npm's global shim on
+//     every OS. So we deliberately OMIT `args` and emit a bare bin name.
+//
+// This is why the block below has no `args` and a bare command string.
+// `npm install -g @lh8ppl/claude-memory-kit` puts these 5 bins on PATH
+// (declared in packages/cli/package.json `bin`); the hook commands then
+// resolve the same way `cmk` itself does.
+//
+// ─────────────────────────────────────────────────────────────────────
+// Decision trail (CLAUDE.md "Decision-trail preservation"):
+//
+//   **Original block (pre-2026-05-29, repair.mjs)**: the PLUGIN form,
+//   `bash "${CLAUDE_PLUGIN_ROOT}/bin/<name>"`, 6 events incl. Setup →
+//   cmk-version-check. That form is correct ONLY when the plugin is
+//   loaded (CLAUDE_PLUGIN_ROOT is set + bash is present). It still lives
+//   in plugin/hooks/hooks.json for the PLUGIN route (Route B), unchanged.
+//
+//   **Task 49 (2026-05-29)**: the npm route (Route A) needs hooks that
+//   work with NO plugin loaded. This block is that form. It drops the
+//   Setup → cmk-version-check hook: version-check is a not-yet-implemented
+//   bash stub (no node bin ships for it — see tasks.md 49.1, which lists
+//   exactly the 5 functional hooks), and `Setup` is not in Anthropic's
+//   documented common-events set. Porting version-check to a node bin is
+//   a v0.1.x item if a real Setup-time check is wanted. The 5 functional
+//   hooks below are the complete auto-memory loop.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname } from 'node:path';
+
+/**
+ * Canonical npm-route hooks block. Shell form (no `args`), PATH-resolved
+ * bare bin names. Keep in sync with packages/cli/package.json `bin` and
+ * (modulo command form) plugin/hooks/hooks.json.
+ */
+export const KIT_HOOKS_BLOCK = Object.freeze({
+  SessionStart: [{ hooks: [{ type: 'command', command: 'cmk-inject-context', timeout: 30 }] }],
+  UserPromptSubmit: [{ hooks: [{ type: 'command', command: 'cmk-capture-prompt', timeout: 10 }] }],
+  PostToolUse: [{ matcher: 'Write|Edit|MultiEdit', hooks: [{ type: 'command', command: 'cmk-observe-edit', async: true, timeout: 120 }] }],
+  Stop: [{ hooks: [{ type: 'command', command: 'cmk-capture-turn', timeout: 30 }] }],
+  SessionEnd: [{ hooks: [{ type: 'command', command: 'cmk-compress-session', timeout: 60 }] }],
+});
+
+/**
+ * Substrings that identify a kit-owned hook entry, so re-runs replace the
+ * kit's entries in place while preserving the user's own hooks. Covers
+ * BOTH command forms (npm-route bare names AND the plugin-route
+ * `${CLAUDE_PLUGIN_ROOT}/bin/<name>` form) so a project that previously
+ * had plugin-form kit hooks gets them cleanly upgraded to npm-form rather
+ * than duplicated.
+ */
+export const KIT_COMMAND_TOKENS = Object.freeze([
+  'cmk-version-check',
+  'cmk-inject-context',
+  'cmk-capture-prompt',
+  'cmk-observe-edit',
+  'cmk-capture-turn',
+  'cmk-compress-session',
+]);
+
+/** True if a hooks-array entry references any kit bin. */
+function isKitEntry(entry) {
+  if (!entry || typeof entry !== 'object') return false;
+  const cmds = [];
+  if (typeof entry.command === 'string') cmds.push(entry.command);
+  if (Array.isArray(entry.hooks)) {
+    for (const h of entry.hooks) if (typeof h.command === 'string') cmds.push(h.command);
+  }
+  return cmds.some((c) => KIT_COMMAND_TOKENS.some((t) => c.includes(t)));
+}
+
+/**
+ * Read-merge-write the canonical kit hooks block into the settings.json
+ * at `settingsPath`. Idempotent. Preserves any non-kit top-level keys and
+ * any non-kit hook entries under the same events.
+ *
+ * Public boundary (install.mjs + repair.mjs depend on this shape):
+ *   writeKitHooks(settingsPath) → {
+ *     changed: boolean,            // did the file content change?
+ *     settingsPath: string,
+ *     events: string[],            // kit events written
+ *     error?: string,             // present iff the existing file was unparseable
+ *   }
+ *
+ * On a JSON parse error of an existing settings.json, returns
+ * {changed:false, error} WITHOUT overwriting — never clobber a file the
+ * user may have hand-broken; surface it so they can fix it.
+ */
+export function writeKitHooks(settingsPath) {
+  const events = Object.keys(KIT_HOOKS_BLOCK);
+
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    } catch (err) {
+      return {
+        changed: false,
+        settingsPath,
+        events,
+        error: `${settingsPath} parse error: ${err?.message ?? err}`,
+      };
+    }
+  }
+
+  const before = JSON.stringify(settings);
+  if (!settings.hooks || typeof settings.hooks !== 'object') {
+    settings.hooks = {};
+  }
+
+  // Walk the UNION of existing events + kit events. For each event, strip
+  // any kit-owned entries (matched by KIT_COMMAND_TOKENS), preserving the
+  // user's own entries; then re-add the canonical kit entries for events
+  // the kit manages. Walking existing events too (not just the 5 kit
+  // events) is what PRUNES a stale plugin-form hook the kit no longer
+  // emits — e.g. a leftover `Setup → cmk-version-check` written by a
+  // pre-0.1.1 `cmk repair --hooks`: it's a kit entry under an event NOT in
+  // KIT_HOOKS_BLOCK, so it gets removed rather than left to fail on the
+  // npm route (no ${CLAUDE_PLUGIN_ROOT}, no bash).
+  const allEvents = new Set([
+    ...Object.keys(settings.hooks),
+    ...Object.keys(KIT_HOOKS_BLOCK),
+  ]);
+  for (const eventName of allEvents) {
+    const existing = Array.isArray(settings.hooks[eventName])
+      ? settings.hooks[eventName]
+      : [];
+    const isKitEvent = Object.prototype.hasOwnProperty.call(KIT_HOOKS_BLOCK, eventName);
+    const hadKitEntry = existing.some(isKitEntry);
+    // Leave purely-user events untouched (don't even rewrite an empty
+    // array the user authored) — only manage events the kit owns OR that
+    // currently carry a stale kit entry to prune.
+    if (!isKitEvent && !hadKitEntry) continue;
+    const userEntries = existing.filter((e) => !isKitEntry(e));
+    // Deep-clone the kit entries before inserting: KIT_HOOKS_BLOCK is only
+    // shallow-frozen, so inserting its nested objects by reference would let
+    // a later mutation of `settings` leak back into the shared constant.
+    const kitEntries = isKitEvent ? structuredClone(KIT_HOOKS_BLOCK[eventName]) : [];
+    const next = [...userEntries, ...kitEntries];
+    if (next.length > 0) {
+      settings.hooks[eventName] = next;
+    } else {
+      // Event held only kit entries the kit no longer emits (e.g. a stale
+      // plugin-form Setup → cmk-version-check): drop the now-empty array
+      // instead of leaving `"Setup": []` behind.
+      delete settings.hooks[eventName];
+    }
+  }
+
+  const after = JSON.stringify(settings);
+  const changed = before !== after;
+
+  if (changed) {
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+  }
+
+  return { changed, settingsPath, events };
+}