@dalzoubi/dev-agents-sync 2.0.16 → 2.0.18

package/README.md

@@ -99,6 +99,44 @@ Show lockfile status:
 npx --yes @dalzoubi/dev-agents-sync@1 status
 ```
 
+## Steering and hooks
+
+For the `claude` target, `init` and `update` set up two extra pieces of project memory and automation.
+
+### Steering scaffold (consumer-owned)
+
+The CLI seeds a blank steering scaffold under `.claude/steering/` — `decisions.md`, `glossary.md`, and `architecture.md` — on first run. These files are **consumer-owned**: they carry no managed-by marker, are never tracked in the lockfile, and are **never overwritten** once they exist. Agents read all three at session start and append to them; the toolkit only seeds the blank files once. Editing them is expected.
+
+### Hook scripts (managed)
+
+`init` and `update` install three hook scripts into `.claude/hooks/` as marker-managed, lockfile-tracked, executable files:
+
+| Script | Claude Code event | Purpose |
+|---|---|---|
+| `steering-injector.sh` | `SessionStart` | Surfaces steering context at the start of a session. |
+| `managed-file-guard.sh` | `PostToolUse` | Guards managed files against unexpected edits. |
+| `uncommitted-check.sh` | `Stop` | Flags uncommitted work when a session ends. |
+
+Hook scripts use the shell-comment marker form `# managed-by: dev-agents-sync vX.Y.Z`. Like other managed files, the CLI overwrites them on `update` and `check` reports drift (exit 1) if one is deleted or locally modified.
+
+### settings.json auto-wiring
+
+By default, `init` and `update` also register the three hooks in `.claude/settings.json` so Claude Code runs them. The merge is:
+
+- **Additive** — every existing setting and every consumer-authored hook is preserved untouched.
+- **Idempotent** — running `update` twice produces no duplicate entries.
+- **Tagged** — each injected entry is marked as CLI-managed so it can be identified and removed later without disturbing consumer-authored hooks.
+
+> **Carve-out.** `settings.json` is a consumer-owned configuration file, **not** a marker-managed file. The CLI never replaces it wholesale; it only merges in its own tagged hook registrations and otherwise leaves the file alone. If `settings.json` contains malformed JSON, `update` fails loud with the stable code `ESETTINGS_PARSE` and leaves the file byte-identical — it will never half-write or clobber an unparseable file.
+
+To install the hook scripts but skip the `settings.json` merge entirely, pass `--no-hooks-wiring`:
+
+```bash
+npx --yes @dalzoubi/dev-agents-sync@1 update --no-hooks-wiring
+```
+
+With `--no-hooks-wiring`, the hook scripts are still installed under `.claude/hooks/`, but `settings.json` is neither created nor modified — wire the hooks yourself if you want them active.
+
 ## Agents
 
 Syncing installs six agents that form a spec-driven workflow:
@@ -137,6 +175,7 @@ and build if relevant) and summarizes what changed. It does not push or open a P
 - `--range ^1` selects the content version range. The default is `^1`.
 - `--dry-run` prints the planned changes without writing files.
 - `--force` allows overwriting unmanaged file collisions.
+- `--no-hooks-wiring` installs the hook scripts but skips the `.claude/settings.json` merge — see [Steering and hooks](#steering-and-hooks).
 - `--token <token>` passes a GitHub token directly.
 
 ## Safety

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dalzoubi/dev-agents-sync",
-  "version": "2.0.16",
+  "version": "2.0.18",
   "type": "module",
   "description": "CLI that syncs managed dev-agent prompts into consumer repos (.claude/ and/or .cursor/).",
   "license": "UNLICENSED",

package/src/cli.mjs

@@ -109,6 +109,7 @@ async function main() {
     range: typeof flags.range === 'string' ? flags.range : undefined,
     force: Boolean(flags.force),
     dryRun: Boolean(flags['dry-run']),
+    noHooksWiring: Boolean(flags['no-hooks-wiring']),
   };
 
   try {

package/src/commands/init.mjs

@@ -16,6 +16,9 @@ import { resolveRange } from '../range.mjs';
 import { resolveConsumerPath, writeManagedFile, normalizeFileMap } from '../writer.mjs';
 import { hasMarker, hasMarkerOnFirstLine } from '../marker.mjs';
 import { injectClaudeMd } from '../claudeMd.mjs';
+import { seedSteering, steeringSummary } from '../steering.mjs';
+import { mergeHookSettings } from '../settings.mjs';
+import { collectHookPaths, hookScriptsForInstalled } from '../hooks.mjs';
 
 const _require = createRequire(import.meta.url);
 const CLI_VERSION = _require('../../package.json').version;
@@ -84,6 +87,7 @@ export async function runInit(consumerCwd, opts = {}) {
     token,
     fetcher,
     availableTags,
+    noHooksWiring = false,
     source = DEFAULT_SOURCE,
     repo = 'dalzoubi/dev-agents',
   } = opts;
@@ -135,6 +139,11 @@ export async function runInit(consumerCwd, opts = {}) {
       ? injectClaudeMd(claudeMdPath, CLI_VERSION, routingContent, { dryRun: true })
       : null;
 
+    // Steering seed plan (claude target only). seed-if-absent; writes nothing in dry-run.
+    const steering = claudeTargetActive
+      ? seedSteering(consumerCwd, { dryRun: true })
+      : null;
+
     return {
       dryRun: true,
       resolvedVersion,
@@ -142,6 +151,7 @@ export async function runInit(consumerCwd, opts = {}) {
       plannedWrites: plannedWrites.map(({ relKey, absPath }) => ({ relKey, absPath })),
       files: plannedWrites.map(({ relKey }) => relKey),
       claudeMd: claudeMdResult,
+      steering,
     };
   }
 
@@ -179,11 +189,33 @@ export async function runInit(consumerCwd, opts = {}) {
     injectClaudeMd(claudeMdPath, CLI_VERSION, routingContent);
   }
 
+  // Seed the consumer-owned steering scaffold (claude target only). Seed-if-absent:
+  // never overwrites edited steering, never recorded in the lockfile (it is unmanaged
+  // by design). Fails loud with ESTEER_WRITE on a write error.
+  let steering = null;
+  if (claudeTargetActive) {
+    steering = seedSteering(consumerCwd);
+    process.stderr.write(`info: dev-agents-sync: ${steeringSummary(steering)}\n`);
+  }
+
+  // Wire the installed hook scripts into .claude/settings.json (claude target
+  // only), unless the consumer opted out with --no-hooks-wiring. The merge is
+  // additive + idempotent and fails loud (ESETTINGS_PARSE) on a malformed file.
+  const installedHookKeys = plannedWrites.map(({ relKey }) => relKey);
+  const hookPaths = collectHookPaths(installedHookKeys);
+  if (claudeTargetActive && !noHooksWiring) {
+    const hookSpec = hookScriptsForInstalled(installedHookKeys);
+    if (hookSpec.length > 0) {
+      mergeHookSettings(consumerCwd, hookSpec);
+    }
+  }
+
   writeLockfile(consumerCwd, {
     source,
     range,
     resolvedVersion,
     targets: [...resolvedTargets].sort(),
+    ...(hookPaths.length > 0 ? { hooks: hookPaths } : {}),
     lastUpdated: new Date().toISOString(),
   });
 
@@ -192,5 +224,7 @@ export async function runInit(consumerCwd, opts = {}) {
     targets: [...resolvedTargets].sort(),
     plannedWrites: plannedWrites.map(({ relKey, absPath }) => ({ relKey, absPath })),
     files: plannedWrites.map(({ relKey }) => relKey),
+    hooks: hookPaths,
+    steering,
   };
 }

package/src/commands/update.mjs

@@ -14,6 +14,9 @@ import { resolveRange } from '../range.mjs';
 import { resolveConsumerPath, writeManagedFile, normalizeFileMap } from '../writer.mjs';
 import { hasMarker, hasMarkerOnFirstLine } from '../marker.mjs';
 import { injectClaudeMd } from '../claudeMd.mjs';
+import { seedSteering, steeringSummary } from '../steering.mjs';
+import { mergeHookSettings, DEFAULT_HOOK_SCRIPTS } from '../settings.mjs';
+import { collectHookPaths, hookScriptsForInstalled } from '../hooks.mjs';
 
 const _require = createRequire(import.meta.url);
 const CLI_VERSION = _require('../../package.json').version;
@@ -31,7 +34,15 @@ function filterFileMapByTargets(fileMap, targets) {
 }
 
 export async function runUpdate(consumerCwd, opts = {}) {
-  const { force = false, dryRun = false, token, fetcher, availableTags, repo = 'dalzoubi/dev-agents' } = opts;
+  const {
+    force = false,
+    dryRun = false,
+    token,
+    fetcher,
+    availableTags,
+    noHooksWiring = false,
+    repo = 'dalzoubi/dev-agents',
+  } = opts;
 
   if (typeof fetcher !== 'function') {
     const err = new Error('runUpdate requires an injected fetcher');
@@ -48,11 +59,40 @@ export async function runUpdate(consumerCwd, opts = {}) {
 
   const targetVersion = resolveRange(availableTags, lock.range);
 
+  // Seed the consumer-owned steering scaffold (claude target only), seed-if-absent,
+  // BEFORE the up-to-date short-circuit so existing consumers adopt steering on any
+  // `update` — not only when a version bump is available. Never overwrites edited
+  // steering; never recorded in the lockfile (unmanaged by design); respects --dry-run.
+  const claudeTargetActive = lock.targets.includes('claude');
+  let steering = null;
+  if (claudeTargetActive) {
+    steering = seedSteering(consumerCwd, { dryRun });
+    if (!dryRun) {
+      process.stderr.write(`info: dev-agents-sync: ${steeringSummary(steering)}\n`);
+    }
+  }
+
   if (targetVersion === lock.resolvedVersion) {
+    // Up to date — but mirror the STEERING precedent above: a consumer already
+    // pinned to the latest version who never had hooks wired must still get the
+    // settings merge so adoption isn't gated on a version bump. We do NOT fetch
+    // here (the short-circuit's whole point is to avoid a fetch); instead we wire
+    // only the hook scripts that already exist on disk. The merge is additive +
+    // idempotent, so running twice == once. --dry-run still writes nothing.
+    if (claudeTargetActive && !noHooksWiring && !dryRun) {
+      const hookSpec = DEFAULT_HOOK_SCRIPTS.filter((h) =>
+        existsSync(path.join(consumerCwd, h.command)),
+      );
+      if (hookSpec.length > 0) {
+        mergeHookSettings(consumerCwd, hookSpec);
+      }
+    }
+
     return {
       upToDate: true,
       resolvedVersion: lock.resolvedVersion,
       message: `already up to date at v${lock.resolvedVersion}`,
+      steering,
     };
   }
 
@@ -68,7 +108,6 @@ export async function runUpdate(consumerCwd, opts = {}) {
   }
 
   // Auto-route content for CLAUDE.md injection (claude target only).
-  const claudeTargetActive = lock.targets.includes('claude');
   const routingContent = claudeTargetActive
     ? (normalized['claude/skills/auto-route.md'] ?? null)
     : null;
@@ -86,6 +125,7 @@ export async function runUpdate(consumerCwd, opts = {}) {
       previousVersion: lock.resolvedVersion,
       files: plannedWrites.map(({ relKey }) => relKey),
       claudeMd: claudeMdResult,
+      steering,
     };
   }
 
@@ -122,11 +162,30 @@ export async function runUpdate(consumerCwd, opts = {}) {
     injectClaudeMd(claudeMdPath, CLI_VERSION, routingContent);
   }
 
+  // Wire installed hook scripts into .claude/settings.json (claude target only),
+  // unless --no-hooks-wiring. Additive + idempotent; fails loud (ESETTINGS_PARSE)
+  // on a malformed settings.json, leaving it byte-identical.
+  const installedHookKeys = plannedWrites.map(({ relKey }) => relKey);
+  const hookPaths = collectHookPaths(installedHookKeys);
+  if (claudeTargetActive && !noHooksWiring) {
+    const hookSpec = hookScriptsForInstalled(installedHookKeys);
+    if (hookSpec.length > 0) {
+      mergeHookSettings(consumerCwd, hookSpec);
+    }
+  }
+
   writeLockfile(consumerCwd, {
     source: lock.source,
     range: lock.range,
     resolvedVersion: targetVersion,
     targets: lock.targets,
+    // Carry forward installed hooks (additive §8). Falls back to any hooks the
+    // pre-existing lockfile already recorded when this update shipped none.
+    ...(hookPaths.length > 0
+      ? { hooks: hookPaths }
+      : Array.isArray(lock.hooks)
+        ? { hooks: lock.hooks }
+        : {}),
     lastUpdated: new Date().toISOString(),
   });
 
@@ -134,5 +193,7 @@ export async function runUpdate(consumerCwd, opts = {}) {
     resolvedVersion: targetVersion,
     previousVersion: lock.resolvedVersion,
     files: plannedWrites.map(({ relKey }) => relKey),
+    hooks: hookPaths,
+    steering,
   };
 }

package/src/hooks.mjs

@@ -0,0 +1,47 @@
+/**
+ * Hook install helpers shared by `init` and `update`.
+ *
+ * Hook scripts ride the normal managed-file install path (they arrive in the
+ * fetched FileMap under `claude/hooks/*.sh` and are written by writeManagedFile,
+ * which also sets the exec bit). These helpers derive, from the set of files
+ * that were actually planned/installed, (a) the consumer-relative hook paths to
+ * record in the lockfile and (b) the settings.json registration spec — so the
+ * CLI only wires hooks that genuinely shipped in the resolved version.
+ */
+
+import { DEFAULT_HOOK_SCRIPTS } from './settings.mjs';
+
+/** True for a FileMap key that is a managed hook script (claude/hooks/*.sh). */
+function isHookKey(relKey) {
+  const norm = relKey.replace(/\\/g, '/');
+  return /^claude\/hooks\/.+\.sh$/.test(norm);
+}
+
+/**
+ * Maps a `claude/hooks/foo.sh` FileMap key to its consumer-relative path
+ * `.claude/hooks/foo.sh` (the form recorded in the lockfile and used as the
+ * settings.json command).
+ */
+function toConsumerHookPath(relKey) {
+  const norm = relKey.replace(/\\/g, '/');
+  return norm.replace(/^claude\//, '.claude/');
+}
+
+/**
+ * Returns the sorted list of consumer-relative hook script paths present in the
+ * given FileMap keys. Used to record installed hooks in the lockfile.
+ */
+export function collectHookPaths(relKeys) {
+  const paths = relKeys.filter(isHookKey).map(toConsumerHookPath);
+  return [...new Set(paths)].sort();
+}
+
+/**
+ * Returns the settings.json hook registration spec restricted to the hook
+ * scripts that were actually installed (present in `relKeys`). Each registration
+ * is taken from DEFAULT_HOOK_SCRIPTS so the event/matcher stay authoritative.
+ */
+export function hookScriptsForInstalled(relKeys) {
+  const installed = new Set(collectHookPaths(relKeys));
+  return DEFAULT_HOOK_SCRIPTS.filter((h) => installed.has(h.command));
+}

package/src/lockfile.mjs

@@ -19,12 +19,18 @@ export const SCHEMA_URL =
 const VALID_TARGETS = new Set(['claude', 'cursor', 'copilot', 'codex']);
 
 // Field order is load-bearing for determinism.
+//
+// `hooks` is an ADDITIVE, OPTIONAL field (§8): it records the relative paths of
+// the managed hook scripts installed under .claude/hooks/. Pre-hooks lockfiles
+// omit it entirely and still parse/validate — it is never a required field, so
+// the upgrade is non-breaking and needs no migration prompt.
 const FIELD_ORDER = [
   '$schema',
   'source',
   'range',
   'resolvedVersion',
   'targets',
+  'hooks',
   'lastUpdated',
 ];
 
@@ -71,6 +77,13 @@ export function validateLockfile(lock) {
       );
     }
   }
+  // `hooks` is optional (additive §8). When present it must be a string array;
+  // its absence is valid and must never be treated as an error (back-compat).
+  if (lock.hooks !== undefined) {
+    if (!Array.isArray(lock.hooks) || lock.hooks.some((h) => typeof h !== 'string')) {
+      throw new LockfileError('invalid lockfile: `hooks` must be an array of strings when present');
+    }
+  }
   return true;
 }
 
@@ -89,6 +102,11 @@ export function serializeLockfile(lock) {
     if (lock[key] === undefined) continue;
     if (key === 'targets') {
       out.targets = [...lock.targets].sort();
+    } else if (key === 'hooks') {
+      // Optional additive field; only emit when present. Sorted for determinism.
+      if (Array.isArray(lock.hooks)) {
+        out.hooks = [...lock.hooks].sort();
+      }
     } else {
       out[key] = lock[key];
     }
@@ -108,6 +126,8 @@ export function writeLockfile(consumerCwd, lock, _options) {
     range: lock.range,
     resolvedVersion: lock.resolvedVersion,
     targets: lock.targets,
+    // Additive optional field — only carried forward when supplied.
+    ...(Array.isArray(lock.hooks) ? { hooks: lock.hooks } : {}),
     lastUpdated: lock.lastUpdated,
   };
   validateLockfile(normalized);

package/src/settings.mjs

@@ -0,0 +1,268 @@
+/**
+ * Claude `settings.json` hook auto-wiring.
+ *
+ * `init`/`update` install the three managed hook scripts into `.claude/hooks/`
+ * via the normal managed-file path. This module performs the genuinely-new step:
+ * an ADDITIVE, IDEMPOTENT merge of the corresponding hook registrations into the
+ * consumer's `.claude/settings.json`.
+ *
+ * Invariants enforced here:
+ *   - Additive: every existing setting and every consumer-authored hook is
+ *     preserved untouched. We only append our own registrations.
+ *   - Idempotent (§9): a second merge adds no duplicates. Identity is the
+ *     installed command path, so re-running is a no-op.
+ *   - Tagged (§4): each injected hook entry carries `HOOK_TAG: true` so it is
+ *     identifiable and removable later (update/uninstall) without touching
+ *     consumer-authored entries. Consumer entries never receive the tag.
+ *   - Fail loud (§5/§12): a malformed `settings.json` surfaces a stable
+ *     `ESETTINGS_PARSE` code and the file is left byte-identical (no partial
+ *     write). We never half-write.
+ *   - Deterministic (§9): stable 2-space JSON + trailing newline, no timestamps.
+ *   - --dry-run writes nothing.
+ *   - Privacy (§11): no tokens are ever read or written here.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Property injected onto every CLI-managed hook entry so it can be identified
+ * and removed without disturbing consumer-authored entries. The value is the
+ * literal property NAME (the tests look for it in the serialized settings and
+ * assert it is absent on consumer entries).
+ */
+export const HOOK_TAG = 'managedBy:dev-agents-sync';
+
+export class SettingsParseError extends Error {
+  constructor(message, { cause } = {}) {
+    super(message);
+    this.name = 'SettingsParseError';
+    this.code = 'ESETTINGS_PARSE';
+    this.exitCode = 1;
+    if (cause) this.cause = cause;
+  }
+}
+
+function settingsPathFor(consumerCwd) {
+  return path.join(consumerCwd, '.claude', 'settings.json');
+}
+
+/** True if `value` is a plain (non-array, non-null) object. */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Fail-loud validation of the INTERNAL shape of a settings `hooks` field before
+ * any merge or removal touches it (§5/§12). `readSettings` already guarantees
+ * the top-level value is a plain object; this guards the sub-tree so a
+ * wrong-shape `hooks` (e.g. a string or array) is never silently spread into an
+ * index-keyed object, and a wrong-shape event value (e.g. a non-array) is never
+ * silently discarded. On any violation we throw SettingsParseError so NO write
+ * happens and the consumer file is left byte-identical.
+ *
+ * Accepts an absent `hooks` (undefined). Otherwise `hooks` must be a plain
+ * object and every `hooks[event]` must be an array (or absent/undefined).
+ */
+function assertHooksShape(hooks, absPath) {
+  if (hooks === undefined) return;
+  if (!isPlainObject(hooks)) {
+    throw new SettingsParseError(
+      `ESETTINGS_PARSE: "hooks" in ${absPath} must be a JSON object — fix or remove it, then re-run`,
+    );
+  }
+  for (const [event, entries] of Object.entries(hooks)) {
+    if (entries === undefined) continue;
+    if (!Array.isArray(entries)) {
+      throw new SettingsParseError(
+        `ESETTINGS_PARSE: "hooks.${event}" in ${absPath} must be a JSON array — fix or remove it, then re-run`,
+      );
+    }
+  }
+}
+
+/**
+ * Reads and parses the consumer's settings.json.
+ * Returns {} when the file is absent. Throws SettingsParseError on malformed JSON.
+ */
+function readSettings(absPath) {
+  if (!existsSync(absPath)) return {};
+  const raw = readFileSync(absPath, 'utf8');
+  if (raw.trim().length === 0) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new SettingsParseError(
+        `ESETTINGS_PARSE: ${absPath} is not a JSON object — fix or remove it, then re-run`,
+      );
+    }
+    return parsed;
+  } catch (err) {
+    if (err instanceof SettingsParseError) throw err;
+    throw new SettingsParseError(
+      `ESETTINGS_PARSE: could not parse ${absPath} as JSON — fix the file or remove it, then re-run`,
+      { cause: err },
+    );
+  }
+}
+
+/** True if `event` already has a CLI-managed entry whose command targets `command`. */
+function hasManagedCommand(eventEntries, command) {
+  if (!Array.isArray(eventEntries)) return false;
+  for (const entry of eventEntries) {
+    if (!entry || entry[HOOK_TAG] !== true) continue;
+    const hookList = Array.isArray(entry.hooks) ? entry.hooks : [];
+    for (const h of hookList) {
+      if (h && typeof h.command === 'string' && h.command === command) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Builds the managed hook entry for one registration. The HOOK_TAG property
+ * marks it as CLI-owned.
+ */
+function buildManagedEntry({ matcher, command }) {
+  return {
+    [HOOK_TAG]: true,
+    matcher,
+    hooks: [{ type: 'command', command }],
+  };
+}
+
+/**
+ * Computes the merged settings object additively. Pure — does not touch disk.
+ * Returns { settings, changed }. Fails loud (ESETTINGS_PARSE) if the consumer's
+ * `hooks` sub-tree has the wrong internal shape, BEFORE any merge — so no write
+ * happens and the file stays byte-identical.
+ */
+function computeMerge(current, hookScripts, absPath) {
+  // Validate the internal shape of the consumer's hooks before merging so a
+  // wrong-shape value is never silently corrupted or discarded (§5/§12).
+  assertHooksShape(current.hooks, absPath);
+
+  // Shallow clone so we never mutate the caller's object; hooks is the only
+  // sub-tree we touch and we clone it per-event below before appending.
+  const next = { ...current };
+  const hooks = { ...(next.hooks ?? {}) };
+  let changed = false;
+
+  for (const { event, matcher, command } of hookScripts) {
+    const existing = Array.isArray(hooks[event]) ? hooks[event] : [];
+    if (hasManagedCommand(existing, command)) {
+      // Already wired — idempotent no-op for this registration.
+      hooks[event] = existing;
+      continue;
+    }
+    hooks[event] = [...existing, buildManagedEntry({ matcher, command })];
+    changed = true;
+  }
+
+  if (changed) {
+    next.hooks = hooks;
+  }
+  return { settings: next, changed };
+}
+
+/**
+ * Idempotent, additive merge of the given hook registrations into the
+ * consumer's `.claude/settings.json`.
+ *
+ * @param {string} consumerCwd
+ * @param {{ event: string, matcher: string, command: string }[]} hookScripts
+ * @param {{ dryRun?: boolean }} [opts]
+ * @returns {{ merged: boolean, dryRun: boolean, settingsPath: string }}
+ * @throws {SettingsParseError} with .code === 'ESETTINGS_PARSE' on malformed settings.json
+ */
+export function mergeHookSettings(consumerCwd, hookScripts, opts = {}) {
+  const { dryRun = false } = opts;
+  const absPath = settingsPathFor(consumerCwd);
+
+  // Parse first — a malformed file fails loud BEFORE any write so the consumer's
+  // file is never clobbered (§5/§12).
+  const current = readSettings(absPath);
+  const { settings, changed } = computeMerge(current, hookScripts, absPath);
+
+  if (dryRun) {
+    return { merged: changed, dryRun: true, settingsPath: absPath };
+  }
+
+  if (!changed) {
+    // Nothing to do — leave the file byte-identical (idempotent §9).
+    return { merged: false, dryRun: false, settingsPath: absPath };
+  }
+
+  mkdirSync(path.dirname(absPath), { recursive: true });
+  writeFileSync(absPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+  return { merged: true, dryRun: false, settingsPath: absPath };
+}
+
+/**
+ * Removes all CLI-managed hook entries (those carrying HOOK_TAG) from the
+ * consumer's settings.json, leaving consumer-authored entries untouched. Used by
+ * uninstall flows. Returns { removed, dryRun } and writes nothing in dry-run.
+ *
+ * @param {string} consumerCwd
+ * @param {{ dryRun?: boolean }} [opts]
+ */
+export function removeHookSettings(consumerCwd, opts = {}) {
+  const { dryRun = false } = opts;
+  const absPath = settingsPathFor(consumerCwd);
+
+  if (!existsSync(absPath)) {
+    return { removed: false, dryRun, settingsPath: absPath };
+  }
+
+  const current = readSettings(absPath);
+  // Same fail-loud posture as the merge path: a wrong-shape `hooks` sub-tree
+  // surfaces ESETTINGS_PARSE and leaves the file byte-identical (§5/§12) rather
+  // than crashing or silently mangling it.
+  assertHooksShape(current.hooks, absPath);
+  const hooks = current.hooks ?? {};
+  let changed = false;
+  const nextHooks = {};
+
+  for (const [event, entries] of Object.entries(hooks)) {
+    if (!Array.isArray(entries)) {
+      nextHooks[event] = entries;
+      continue;
+    }
+    const kept = entries.filter((entry) => !(entry && entry[HOOK_TAG] === true));
+    if (kept.length !== entries.length) changed = true;
+    if (kept.length > 0) {
+      nextHooks[event] = kept;
+    } else {
+      // Drop the now-empty event bucket so we don't leave dangling keys.
+      changed = changed || entries.length > 0;
+    }
+  }
+
+  if (!changed) {
+    return { removed: false, dryRun, settingsPath: absPath };
+  }
+
+  const next = { ...current };
+  if (Object.keys(nextHooks).length > 0) {
+    next.hooks = nextHooks;
+  } else {
+    delete next.hooks;
+  }
+
+  if (dryRun) {
+    return { removed: true, dryRun: true, settingsPath: absPath };
+  }
+
+  writeFileSync(absPath, JSON.stringify(next, null, 2) + '\n', 'utf8');
+  return { removed: true, dryRun: false, settingsPath: absPath };
+}
+
+/**
+ * The default hook registration spec — maps each installed hook script to its
+ * Claude Code event. Kept here so init/update share one source of truth.
+ */
+export const DEFAULT_HOOK_SCRIPTS = [
+  { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
+  { event: 'PostToolUse', matcher: '.*', command: '.claude/hooks/managed-file-guard.sh' },
+  { event: 'Stop', matcher: '.*', command: '.claude/hooks/uncommitted-check.sh' },
+];