@dalzoubi/dev-agents-sync 2.0.25 → 2.0.27

package/README.md

@@ -109,12 +109,11 @@ The CLI seeds a blank steering scaffold under `.claude/steering/` — `decisions
 
 ### Hook scripts (managed)
 
-`init` and `update` install four hook scripts into `.claude/hooks/` as marker-managed, lockfile-tracked, executable files:
+`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. |
-| `rules-injector.sh` | `SessionStart` | Injects the always-on shared rule bodies (`structured-choices`, `tone`) from `.claude/rules/` into every session; fail-safe (skips absent rules, exits 0). |
 | `managed-file-guard.sh` | `PostToolUse` | Guards managed files against unexpected edits. |
 | `uncommitted-check.sh` | `Stop` | Flags uncommitted work when a session ends. |
 
@@ -122,11 +121,12 @@ Hook scripts use the shell-comment marker form `# managed-by: dev-agents-sync vX
 
 ### settings.json auto-wiring
 
-By default, `init` and `update` also register the four hooks in `.claude/settings.json` so Claude Code runs them. The merge is:
+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.
+- **Self-cleaning** — when the toolkit retires a hook, `update` also prunes the CLI-managed registration for it, so no consumer is left with an entry pointing at a script that no longer ships. Only tagged entries are pruned, and only the retired command within them: a consumer-authored entry for the same command is left untouched, and a command you added yourself inside a tagged entry survives alongside. The prune is reported on stderr (`info: dev-agents-sync: pruned N retired hook registration(s)`, counting registrations removed) and is computed — and surfaced in the `--dry-run` result — without writing anything. `rules-injector.sh` is the first retired hook — Claude Code now loads `.claude/rules/*.md` natively, so the hook is redundant.
 
 > **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.
 
@@ -136,7 +136,7 @@ To install the hook scripts but skip the `settings.json` merge entirely, pass `-
 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.
+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. Note that the flag skips the whole merge, **including the self-cleaning de-registration above**: a registration for a retired hook stays in your `settings.json` until you run without the flag or remove it yourself.
 
 ## Agents
 

package/package.json

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

package/src/commands/init.mjs

@@ -17,8 +17,7 @@ import { resolveConsumerPath, writeManagedFile, normalizeFileMap } from '../writ
 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';
+import { collectHookPaths, hookScriptsForInstalled, wireHookSettings } from '../hooks.mjs';
 
 const _require = createRequire(import.meta.url);
 const CLI_VERSION = _require('../../package.json').version;
@@ -134,6 +133,7 @@ export async function runInit(consumerCwd, opts = {}) {
   const claudeMdPath = path.join(consumerCwd, 'CLAUDE.md');
 
   if (dryRun) {
+    const plannedKeys = plannedWrites.map(({ relKey }) => relKey);
     // Run inject in dry-run mode to compute the planned change.
     const claudeMdResult = routingContent
       ? injectClaudeMd(claudeMdPath, CLI_VERSION, routingContent, { dryRun: true })
@@ -144,13 +144,24 @@ export async function runInit(consumerCwd, opts = {}) {
       ? seedSteering(consumerCwd, { dryRun: true })
       : null;
 
+    // Compute the planned settings.json merge too, mirroring update's dry-run
+    // branch: skipping it would under-report a real, intended change to
+    // consumer-owned state — and `init` over an existing .claude/ can meet a
+    // pre-retirement settings.json (same exposure the wiring call below cites).
+    // The merge writes nothing in dry-run, so settings.json stays byte-identical.
+    const plannedPrunedRetired =
+      claudeTargetActive && !noHooksWiring
+        ? wireHookSettings(consumerCwd, hookScriptsForInstalled(plannedKeys), { dryRun: true })
+        : [];
+
     return {
       dryRun: true,
       resolvedVersion,
       targets: resolvedTargets,
       plannedWrites: plannedWrites.map(({ relKey, absPath }) => ({ relKey, absPath })),
-      files: plannedWrites.map(({ relKey }) => relKey),
+      files: plannedKeys,
       claudeMd: claudeMdResult,
+      prunedRetired: plannedPrunedRetired,
       steering,
     };
   }
@@ -203,11 +214,11 @@ export async function runInit(consumerCwd, opts = {}) {
   // additive + idempotent and fails loud (ESETTINGS_PARSE) on a malformed file.
   const installedHookKeys = plannedWrites.map(({ relKey }) => relKey);
   const hookPaths = collectHookPaths(installedHookKeys);
+  let prunedRetired = [];
   if (claudeTargetActive && !noHooksWiring) {
-    const hookSpec = hookScriptsForInstalled(installedHookKeys);
-    if (hookSpec.length > 0) {
-      mergeHookSettings(consumerCwd, hookSpec);
-    }
+    // Unconditional on the spec being non-empty: the prune half needs no spec,
+    // and `init` over an existing .claude/ can meet a pre-retirement settings.json.
+    prunedRetired = wireHookSettings(consumerCwd, hookScriptsForInstalled(installedHookKeys));
   }
 
   writeLockfile(consumerCwd, {
@@ -225,6 +236,7 @@ export async function runInit(consumerCwd, opts = {}) {
     plannedWrites: plannedWrites.map(({ relKey, absPath }) => ({ relKey, absPath })),
     files: plannedWrites.map(({ relKey }) => relKey),
     hooks: hookPaths,
+    prunedRetired,
     steering,
   };
 }

package/src/commands/update.mjs

@@ -15,8 +15,8 @@ import { resolveConsumerPath, writeManagedFile, normalizeFileMap } from '../writ
 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';
+import { DEFAULT_HOOK_SCRIPTS } from '../settings.mjs';
+import { collectHookPaths, hookScriptsForInstalled, wireHookSettings } from '../hooks.mjs';
 
 const _require = createRequire(import.meta.url);
 const CLI_VERSION = _require('../../package.json').version;
@@ -144,19 +144,21 @@ export async function runUpdate(consumerCwd, opts = {}) {
     // 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) {
+    let prunedRetired = [];
+    if (claudeTargetActive && !noHooksWiring) {
       const hookSpec = DEFAULT_HOOK_SCRIPTS.filter((h) =>
         existsSync(path.join(consumerCwd, h.command)),
       );
-      if (hookSpec.length > 0) {
-        mergeHookSettings(consumerCwd, hookSpec);
-      }
+      // Unconditional on hookSpec.length: the prune needs no spec, so a consumer
+      // with no hook scripts on disk still gets retired registrations removed.
+      prunedRetired = wireHookSettings(consumerCwd, hookSpec, { dryRun });
     }
 
     return {
       upToDate: true,
       resolvedVersion: lock.resolvedVersion,
       message: `already up to date at v${lock.resolvedVersion}`,
+      prunedRetired,
       steering,
     };
   }
@@ -185,18 +187,27 @@ export async function runUpdate(consumerCwd, opts = {}) {
   const orphans = computeOrphans(consumerCwd, scopedKeys, lock.targets);
 
   if (dryRun) {
+    const plannedKeys = plannedWrites.map(({ relKey }) => relKey);
     // Compute the planned CLAUDE.md change so callers can inspect it without
     // the result shape silently diverging from the init --dry-run contract.
     const claudeMdResult = routingContent
       ? injectClaudeMd(claudeMdPath, CLI_VERSION, routingContent, { dryRun: true })
       : null;
+    // Compute the planned settings.json merge too — a dry run that skipped it
+    // would under-report a real, intended change to consumer-owned state. The
+    // merge writes nothing in dry-run, so settings.json stays byte-identical.
+    const plannedPrunedRetired =
+      claudeTargetActive && !noHooksWiring
+        ? wireHookSettings(consumerCwd, hookScriptsForInstalled(plannedKeys), { dryRun: true })
+        : [];
     return {
       dryRun: true,
       resolvedVersion: targetVersion,
       previousVersion: lock.resolvedVersion,
-      files: plannedWrites.map(({ relKey }) => relKey),
+      files: plannedKeys,
       claudeMd: claudeMdResult,
       plannedPrune: orphans,
+      prunedRetired: plannedPrunedRetired,
       steering,
     };
   }
@@ -239,11 +250,10 @@ export async function runUpdate(consumerCwd, opts = {}) {
   // on a malformed settings.json, leaving it byte-identical.
   const installedHookKeys = plannedWrites.map(({ relKey }) => relKey);
   const hookPaths = collectHookPaths(installedHookKeys);
+  let prunedRetired = [];
   if (claudeTargetActive && !noHooksWiring) {
-    const hookSpec = hookScriptsForInstalled(installedHookKeys);
-    if (hookSpec.length > 0) {
-      mergeHookSettings(consumerCwd, hookSpec);
-    }
+    // Unconditional on the spec being non-empty: the prune half needs no spec.
+    prunedRetired = wireHookSettings(consumerCwd, hookScriptsForInstalled(installedHookKeys));
   }
 
   // Prune orphans: marker-bearing managed files no longer shipped. Delete in
@@ -293,6 +303,7 @@ export async function runUpdate(consumerCwd, opts = {}) {
     hooks: hookPaths,
     pruned,
     prunedCount: pruned.length,
+    prunedRetired,
     summary: pruneSummary,
     steering,
   };

package/src/hooks.mjs

@@ -9,7 +9,7 @@
  * CLI only wires hooks that genuinely shipped in the resolved version.
  */
 
-import { DEFAULT_HOOK_SCRIPTS } from './settings.mjs';
+import { DEFAULT_HOOK_SCRIPTS, mergeHookSettings } from './settings.mjs';
 
 /** True for a FileMap key that is a managed hook script (claude/hooks/*.sh). */
 function isHookKey(relKey) {
@@ -45,3 +45,40 @@ export function hookScriptsForInstalled(relKeys) {
   const installed = new Set(collectHookPaths(relKeys));
   return DEFAULT_HOOK_SCRIPTS.filter((h) => installed.has(h.command));
 }
+
+/**
+ * Merges `hookScripts` into the consumer's .claude/settings.json and reports any
+ * retired registrations the merge de-registered. Shared by init and update so
+ * all three wiring call sites report identically.
+ *
+ * Called even when `hookScripts` is EMPTY: the prune half of the merge needs no
+ * spec, so a consumer with no hook scripts on disk still gets stale
+ * registrations for retired hooks cleaned up. With nothing to add and nothing to
+ * prune the merge is a no-op that writes nothing — it does not create the file.
+ *
+ * De-registration is a real edit to consumer-owned state, so it is never silent
+ * (§6): it emits the same `info: dev-agents-sync: ...` line as update's
+ * orphaned-file prune. Nothing is printed under --dry-run (planning is not
+ * doing) or when nothing was pruned (no spurious line on every run).
+ *
+ * The line reports `prunedRetiredCount` — REGISTRATIONS removed — not
+ * `prunedRetired.length`, which is the same list deduped by command. One retired
+ * command registered under two event buckets is two registrations gone from the
+ * consumer's file; saying "1" there would under-report the edit we just made.
+ *
+ * @returns {string[]} the DISTINCT retired commands de-registered (or, in
+ *   dry-run, that would be de-registered) by this call. Always an array. Callers
+ *   match on it ("was X pruned?"); the user-facing count stays inside this
+ *   function, which is the toolkit's single reporting site for the prune.
+ */
+export function wireHookSettings(consumerCwd, hookScripts, { dryRun = false } = {}) {
+  const { prunedRetired, prunedRetiredCount } = mergeHookSettings(consumerCwd, hookScripts, {
+    dryRun,
+  });
+  if (!dryRun && prunedRetiredCount > 0) {
+    process.stderr.write(
+      `info: dev-agents-sync: pruned ${prunedRetiredCount} retired hook registration(s)\n`,
+    );
+  }
+  return prunedRetired;
+}

package/src/settings.mjs

@@ -8,7 +8,8 @@
  *
  * Invariants enforced here:
  *   - Additive: every existing setting and every consumer-authored hook is
- *     preserved untouched. We only append our own registrations.
+ *     preserved untouched. We only append our own registrations — and remove
+ *     our own registrations for RETIRED_HOOK_SCRIPTS, never anyone else's.
  *   - 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
@@ -106,17 +107,25 @@ function readSettings(absPath) {
   }
 }
 
+/**
+ * The command strings carried by one CLI-managed settings entry, in order, or []
+ * when the entry is absent, malformed, or consumer-authored.
+ *
+ * The HOOK_TAG check lives here rather than at each call site because EVERY read
+ * path — the idempotence check and the retirement prune alike — must ignore a
+ * consumer-authored entry pointing at the very same command: that is
+ * consumer-owned state and must survive untouched (spec risk 6).
+ */
+function managedCommandsIn(entry) {
+  if (!entry || entry[HOOK_TAG] !== true) return [];
+  const hookList = Array.isArray(entry.hooks) ? entry.hooks : [];
+  return hookList.filter((h) => h && typeof h.command === 'string').map((h) => h.command);
+}
+
 /** 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;
+  return eventEntries.some((entry) => managedCommandsIn(entry).includes(command));
 }
 
 /**
@@ -131,48 +140,174 @@ function buildManagedEntry({ matcher, command }) {
   };
 }
 
+/** True if `command` is on the retired list (exact match, never a prefix/substring). */
+function isRetiredCommand(command) {
+  return RETIRED_HOOK_SCRIPTS.some((h) => h.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.
+ * True for a single `hooks[]` element that invokes a retired command.
+ *
+ * Shared by the two halves of the prune — the one that REPORTS what was removed
+ * (via `retiredCommandsIn`, which applies `isRetiredCommand` to the same
+ * `command`/shape guards `managedCommandsIn` enforces) and the one that DOES the
+ * removing. Those two must agree exactly or the prune would report a command it
+ * left in place, so the predicate is named once rather than spelled out twice.
+ */
+function isRetiredHook(hook) {
+  return Boolean(hook) && typeof hook.command === 'string' && isRetiredCommand(hook.command);
+}
+
+/** The retired commands carried by a single CLI-managed settings entry, or [] if none. */
+function retiredCommandsIn(entry) {
+  return managedCommandsIn(entry).filter(isRetiredCommand);
+}
+
+/**
+ * Removes managed registrations for retired hooks from `hooks` IN PLACE, across
+ * every event bucket.
+ *
+ * Returns two deliberately different views of the same prune:
+ *   - `commands` — the distinct retired commands removed (deduped, first-seen
+ *     order, so the result is deterministic §9). Callers answer "was X
+ *     de-registered?" from this.
+ *   - `count` — how many registrations were actually removed. One command can be
+ *     registered under several event buckets (a pre-retirement CLI, or a
+ *     hand-edit), so this is >= `commands.length`. It is the number a consumer
+ *     must read on their terminal: reporting the deduped length there would
+ *     under-count a real, multi-bucket edit to consumer-owned state (§6).
+ *
+ * Scans all buckets rather than only the ones named in RETIRED_HOOK_SCRIPTS: a
+ * pre-retirement CLI may have registered the command under a different event,
+ * and a stale registration pointing at a script that no longer ships fails
+ * every session with no detection (§5).
+ *
+ * The prune is HOOK-granular, not entry-granular: it filters `entry.hooks` down
+ * to its non-retired commands and drops the entry only once that array empties.
+ * `buildManagedEntry` only ever emits one command per entry, so the CLI cannot
+ * produce a multi-command entry itself — but a multi-command `hooks[]` is
+ * idiomatic Claude Code settings shape, and a consumer hand-adding their own
+ * command into our tagged entry produces exactly that. Dropping the whole entry
+ * would delete their command permanently (nothing managed re-adds it), breaking
+ * the module invariant above — and would equally un-register a still-shipped
+ * managed command sharing the entry, which `appendMissingEntries` has already
+ * seen as present and so will not re-add.
+ *
+ * Entries are REPLACED, never mutated, so the objects and arrays inside the
+ * consumer's parsed settings are never written through.
+ */
+function pruneRetiredEntries(hooks) {
+  const pruned = [];
+  for (const [event, entries] of Object.entries(hooks)) {
+    if (!Array.isArray(entries)) continue;
+    let changed = false;
+    const kept = [];
+    for (const entry of entries) {
+      const retired = retiredCommandsIn(entry);
+      if (retired.length === 0) {
+        // Untagged (consumer-authored) or carrying nothing retired — untouched.
+        kept.push(entry);
+        continue;
+      }
+      pruned.push(...retired);
+      changed = true;
+      // `retired` being non-empty means managedCommandsIn found commands, which
+      // it only does for a tagged entry whose `hooks` is an array — so this is
+      // reachable only when `entry.hooks` is safe to filter.
+      const survivors = entry.hooks.filter((h) => !isRetiredHook(h));
+      // Only drop the entry outright once nothing of it is left.
+      if (survivors.length > 0) kept.push({ ...entry, hooks: survivors });
+    }
+    if (!changed) continue;
+    if (kept.length > 0) {
+      hooks[event] = kept;
+    } else {
+      // Drop the now-empty event bucket so we don't leave a dangling key.
+      delete hooks[event];
+    }
+  }
+  return { commands: [...new Set(pruned)], count: pruned.length };
+}
+
+/**
+ * Appends a managed entry for every registration in `hookScripts` not already
+ * wired, mutating the caller's `hooks` copy IN PLACE, and returns true when at
+ * least one was added.
+ *
+ * Event arrays are REPLACED, never mutated, so the arrays inside the consumer's
+ * parsed settings are never written through.
+ */
+function appendMissingEntries(hooks, hookScripts) {
+  let added = false;
+  for (const { event, matcher, command } of hookScripts) {
+    const existing = Array.isArray(hooks[event]) ? hooks[event] : [];
+    // Already wired — idempotent no-op for this registration (§9).
+    if (hasManagedCommand(existing, command)) continue;
+    hooks[event] = [...existing, buildManagedEntry({ matcher, command })];
+    added = true;
+  }
+  return added;
+}
+
+/**
+ * Assigns `hooks` onto `settings` IN PLACE, dropping the key outright when no
+ * bucket survived, so neither write path can leave a dangling `"hooks": {}`
+ * behind. Both the merge and the removal path empty buckets and so must treat
+ * that end state identically; callers pass a shallow clone they own.
+ */
+function assignHooks(settings, hooks) {
+  if (Object.keys(hooks).length > 0) {
+    settings.hooks = hooks;
+  } else {
+    delete settings.hooks;
+  }
+}
+
+/**
+ * Computes the merged settings object: the additive pass, then a prune of
+ * managed registrations for retired hooks. Pure — does not touch disk.
+ * Returns { settings, changed, prunedRetired, prunedRetiredCount }. Fails loud (ESETTINGS_PARSE) if
+ * the consumer's `hooks` sub-tree has the wrong internal shape, BEFORE any merge
+ * or prune — 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.
+  // Shallow clone so we never mutate the caller's object; `hooks` is the only
+  // sub-tree we touch, and both passes below replace event arrays rather than
+  // writing through to the consumer's own arrays.
   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;
-  }
+  const added = appendMissingEntries(hooks, hookScripts);
+  // Merge-then-prune: retirement is subtractive and runs AFTER the additive
+  // pass, so a command that is both shipped and retired cannot survive by
+  // being re-added in the same run.
+  const { commands: prunedRetired, count: prunedRetiredCount } = pruneRetiredEntries(hooks);
 
-  if (changed) {
-    next.hooks = hooks;
-  }
-  return { settings: next, changed };
+  const changed = added || prunedRetiredCount > 0;
+  if (changed) assignHooks(next, hooks);
+  return { settings: next, changed, prunedRetired, prunedRetiredCount };
 }
 
 /**
- * Idempotent, additive merge of the given hook registrations into the
- * consumer's `.claude/settings.json`.
+ * Idempotent merge of the given hook registrations into the consumer's
+ * `.claude/settings.json`: additive for shipped hooks, then a prune of managed
+ * registrations for retired ones (RETIRED_HOOK_SCRIPTS).
  *
  * @param {string} consumerCwd
  * @param {{ event: string, matcher: string, command: string }[]} hookScripts
  * @param {{ dryRun?: boolean }} [opts]
- * @returns {{ merged: boolean, dryRun: boolean, settingsPath: string }}
+ * @returns {{ merged: boolean, dryRun: boolean, settingsPath: string, prunedRetired: string[], prunedRetiredCount: number }}
+ *   `merged` is true when EITHER the additive pass or the prune changed the
+ *   settings. `prunedRetired` lists the DISTINCT retired commands this call
+ *   removed and is always an array — empty when nothing was pruned — so a caller
+ *   can tell "no retired entries existed" apart from "retirement isn't
+ *   supported". `prunedRetiredCount` is how many registrations were removed to
+ *   get there: >= `prunedRetired.length`, since one command can be registered
+ *   under several event buckets. Report the COUNT to users; match on the LIST.
  * @throws {SettingsParseError} with .code === 'ESETTINGS_PARSE' on malformed settings.json
  */
 export function mergeHookSettings(consumerCwd, hookScripts, opts = {}) {
@@ -182,20 +317,24 @@ export function mergeHookSettings(consumerCwd, hookScripts, opts = {}) {
   // 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);
+  const { settings, changed, prunedRetired, prunedRetiredCount } = computeMerge(
+    current,
+    hookScripts,
+    absPath,
+  );
 
   if (dryRun) {
-    return { merged: changed, dryRun: true, settingsPath: absPath };
+    return { merged: changed, dryRun: true, settingsPath: absPath, prunedRetired, prunedRetiredCount };
   }
 
   if (!changed) {
     // Nothing to do — leave the file byte-identical (idempotent §9).
-    return { merged: false, dryRun: false, settingsPath: absPath };
+    return { merged: false, dryRun: false, settingsPath: absPath, prunedRetired, prunedRetiredCount };
   }
 
   mkdirSync(path.dirname(absPath), { recursive: true });
   writeFileSync(absPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
-  return { merged: true, dryRun: false, settingsPath: absPath };
+  return { merged: true, dryRun: false, settingsPath: absPath, prunedRetired, prunedRetiredCount };
 }
 
 /**
@@ -230,11 +369,10 @@ export function removeHookSettings(consumerCwd, opts = {}) {
     }
     const kept = entries.filter((entry) => !(entry && entry[HOOK_TAG] === true));
     if (kept.length !== entries.length) changed = true;
+    // An emptied bucket is simply not carried over, so we don't leave a dangling
+    // key; `changed` is already true in that case via the length check above.
     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;
     }
   }
 
@@ -243,11 +381,7 @@ export function removeHookSettings(consumerCwd, opts = {}) {
   }
 
   const next = { ...current };
-  if (Object.keys(nextHooks).length > 0) {
-    next.hooks = nextHooks;
-  } else {
-    delete next.hooks;
-  }
+  assignHooks(next, nextHooks);
 
   if (dryRun) {
     return { removed: true, dryRun: true, settingsPath: absPath };
@@ -263,7 +397,30 @@ export function removeHookSettings(consumerCwd, opts = {}) {
  */
 export const DEFAULT_HOOK_SCRIPTS = [
   { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
-  { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/rules-injector.sh' },
   { event: 'PostToolUse', matcher: '.*', command: '.claude/hooks/managed-file-guard.sh' },
   { event: 'Stop', matcher: '.*', command: '.claude/hooks/uncommitted-check.sh' },
 ];
+
+/**
+ * Hook registrations the toolkit once shipped and has since retired.
+ *
+ * On every `init`/`update`, `mergeHookSettings` removes any CLI-managed entry
+ * whose command appears here. Without it, deleting a hook script would leave a
+ * live registration pointing at a file that no longer exists — a per-session
+ * failure with no detection and no recovery path (§5).
+ *
+ * APPEND-ONLY, and deliberately separate from DEFAULT_HOOK_SCRIPTS. A consumer
+ * may upgrade from any older version, so this list has to name every command
+ * the CLI has ever registered and no longer ships — removing an entry once
+ * published would strand that registration in every consumer who had not yet
+ * updated past it. Being additive is also what makes the change §8-compatible:
+ * an older CLI reading newer content simply does not prune rather than erroring.
+ * Reversing a retirement is done by moving the entry back to
+ * DEFAULT_HOOK_SCRIPTS, not by silently dropping it from here.
+ */
+export const RETIRED_HOOK_SCRIPTS = [
+  // Retired by docs/specs/260724-opus5-native-overlap/ (S1): Claude Code loads
+  // `.claude/rules/*.md` natively as project instructions, which is strictly
+  // broader than this hook's fixed injection list.
+  { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/rules-injector.sh' },
+];