@dalzoubi/dev-agents-sync 2.0.25 → 2.0.26

package/tests/rules-injector-registration.test.mjs

@@ -1,27 +1,47 @@
 /**
  * tests/rules-injector-registration.test.mjs
  *
- * Slice S2 — SessionStart rules-injector.sh hook (registration half).
- * Spec: docs/specs/260708-claude-rules-enforcement/
+ * Originally Slice S2 (docs/specs/260708-claude-rules-enforcement/) — proved
+ * that `rules-injector.sh` got wired into a consumer's `.claude/settings.json`
+ * as a managed SessionStart hook.
  *
- * These tests FAIL before the implement agent registers rules-injector.sh as a
- * managed SessionStart hook and PASS after. They are behavior-anchored (§7):
- * each criterion maps to a named test that would fail if the behavior broke.
+ * Slice S1 of docs/specs/260724-opus5-native-overlap/ ("retire-rules-injector-hook")
+ * retires that hook: Claude Code now loads `.claude/rules/*.md` natively as
+ * project instructions, so the hook is redundant, and the CLI gains a
+ * `RETIRED_HOOK_SCRIPTS` prune (see tests/hook-retirement.test.mjs for the
+ * settings.mjs-level merge-then-prune contract). T004 of that spec's tasks.md
+ * requires updating this file "to the retired-hook expectation" so it proves
+ * the OPPOSITE of what it proved before: rules-injector.sh is no longer
+ * registered by DEFAULT_HOOK_SCRIPTS, `init` never wires it for a new
+ * consumer, and `update` PRUNES it from an existing consumer who has it from
+ * before S1 shipped.
+ *
+ * These tests are written RED-first, alongside tests/hook-retirement.test.mjs
+ * and the S1 additions to tests/hooks-build-emission.test.mjs: they FAIL today
+ * because `.agents/hooks/rules-injector.sh` still exists, DEFAULT_HOOK_SCRIPTS
+ * still lists it, and mergeHookSettings has no prune branch yet. They go GREEN
+ * once S1 lands: the canonical hook source is deleted, DEFAULT_HOOK_SCRIPTS
+ * drops the entry, and RETIRED_HOOK_SCRIPTS + the merge-then-prune pass ship.
  *
  * Behavior anchors:
  *
- *  R1. DEFAULT_HOOK_SCRIPTS (packages/dev-agents-sync/src/settings.mjs) includes
- *      a SessionStart entry whose command targets
- *      `.claude/hooks/rules-injector.sh`.
- *  R2. When the fetched FileMap ships `claude/hooks/rules-injector.sh` (as S3's
- *      build.mjs will once the canonical `.agents/hooks/rules-injector.sh`
- *      exists), `runInit` wires a HOOK_TAG-tagged SessionStart registration for
- *      it into the consumer's `.claude/settings.json`, additively alongside the
- *      three pre-existing managed hooks (steering-injector.sh,
- *      managed-file-guard.sh, uncommitted-check.sh).
- *  R3. `runUpdate` does the same on a pre-initialized consumer repo.
- *  R4. Running update twice produces no duplicate rules-injector.sh
- *      registration (idempotent, §9).
+ *  R1. DEFAULT_HOOK_SCRIPTS (packages/dev-agents-sync/src/settings.mjs) no
+ *      longer has an entry targeting `.claude/hooks/rules-injector.sh`; it
+ *      registers exactly the three surviving hooks.
+ *  R2. `runInit` on a fresh consumer never wires a SessionStart registration
+ *      for rules-injector.sh into `.claude/settings.json` — the three
+ *      surviving managed hooks are still wired additively.
+ *  R3. `runUpdate` on a consumer who already has a managed (HOOK_TAG-tagged)
+ *      rules-injector.sh SessionStart entry from before S1 shipped PRUNES
+ *      that entry, without disturbing the three surviving hooks.
+ *  R4. Running update twice against that same pre-S1 consumer leaves the
+ *      registration pruned — it is never reintroduced (idempotent removal,
+ *      §9).
+ *
+ * This file stays a CLI-integration-level check (exercising the real
+ * runInit/runUpdate entry points end to end); it deliberately does not
+ * duplicate tests/hook-retirement.test.mjs's settings.mjs-level unit coverage
+ * of the merge-then-prune mechanism itself (P1-P6, T0 there).
  *
  * Test runner: `node --test packages/dev-agents-sync/tests/rules-injector-registration.test.mjs`
  * No third-party dependencies. All tests use isolated tmp dirs.
@@ -53,6 +73,7 @@ import { DEFAULT_HOOK_SCRIPTS, HOOK_TAG } from '../src/settings.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const FIXTURE_DIR = path.join(__dirname, 'fixtures', 'release-v1.0.0');
+const RETIRED_COMMAND = '.claude/hooks/rules-injector.sh';
 
 function collectFiles(baseDir, currentDir, map, prefix) {
   const entries = readdirSync(currentDir, { withFileTypes: true });
@@ -68,9 +89,11 @@ function collectFiles(baseDir, currentDir, map, prefix) {
 }
 
 /**
- * Builds a fixture FileMap that includes the four managed hook scripts —
- * the three pre-existing ones plus rules-injector.sh (as S3's build.mjs will
- * emit once the canonical `.agents/hooks/rules-injector.sh` source exists).
+ * Builds a fixture FileMap that includes the three surviving managed hook
+ * scripts — matching what S1's build.mjs emits once
+ * `.agents/hooks/rules-injector.sh` is deleted (planHookEmissions directory-
+ * scans `.agents/hooks/`, so a deleted source simply stops appearing here).
+ * rules-injector.sh is deliberately NOT included: a post-S1 fetch never ships it.
  */
 function buildFixtureFileMap() {
   const map = {};
@@ -84,8 +107,6 @@ function buildFixtureFileMap() {
     '#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# PostToolUse hook.\nexit 0\n';
   map['claude/hooks/uncommitted-check.sh'] =
     '#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# Stop hook.\nexit 0\n';
-  map['claude/hooks/rules-injector.sh'] =
-    '#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# SessionStart hook.\nexit 0\n';
   return map;
 }
 
@@ -119,6 +140,55 @@ function setupInitializedRepo(consumerDir, opts = {}) {
   writeFileSync(path.join(agentsDir, 'define.md'), fixtureContent, 'utf8');
 }
 
+/**
+ * Simulates a consumer who ran `update` before S1 shipped: their
+ * settings.json already carries a managed (HOOK_TAG-tagged) SessionStart
+ * registration for rules-injector.sh, wired the normal way (buildManagedEntry
+ * shape in src/settings.mjs).
+ */
+function writePreS1SettingsWithRulesInjector(consumerDir) {
+  const settingsDir = path.join(consumerDir, '.claude');
+  mkdirSync(settingsDir, { recursive: true });
+  const settings = {
+    hooks: {
+      SessionStart: [
+        {
+          [HOOK_TAG]: true,
+          matcher: '.*',
+          hooks: [{ type: 'command', command: RETIRED_COMMAND }],
+        },
+      ],
+    },
+  };
+  writeFileSync(
+    path.join(settingsDir, 'settings.json'),
+    JSON.stringify(settings, null, 2) + '\n',
+    'utf8',
+  );
+}
+
+/**
+ * Captures all output written to process.stderr.write during the execution of
+ * `fn`. Returns the concatenated string.
+ *
+ * Matches the same capture pattern used in first-sync-notice.test.mjs /
+ * root-target.test.mjs.
+ */
+async function captureStderr(fn) {
+  const origWrite = process.stderr.write.bind(process.stderr);
+  let captured = '';
+  process.stderr.write = (chunk) => {
+    captured += typeof chunk === 'string' ? chunk : chunk.toString();
+    return true;
+  };
+  try {
+    await fn();
+  } finally {
+    process.stderr.write = origWrite;
+  }
+  return captured;
+}
+
 /** Collects every hook `command` string registered anywhere in settings.hooks. */
 function allHookCommands(settings) {
   const hooks = settings.hooks ?? {};
@@ -136,34 +206,36 @@ function allHookCommands(settings) {
 }
 
 // ---------------------------------------------------------------------------
-// R1 — DEFAULT_HOOK_SCRIPTS registers rules-injector.sh on SessionStart
+// R1 — DEFAULT_HOOK_SCRIPTS no longer registers rules-injector.sh
 // ---------------------------------------------------------------------------
 
-describe('S2 R1 — DEFAULT_HOOK_SCRIPTS includes rules-injector.sh', () => {
-  it('R1a: DEFAULT_HOOK_SCRIPTS has an entry whose command is .claude/hooks/rules-injector.sh', () => {
-    const entry = DEFAULT_HOOK_SCRIPTS.find(
-      (h) => h.command === '.claude/hooks/rules-injector.sh',
-    );
-    assert.ok(
+describe('S1 R1 — DEFAULT_HOOK_SCRIPTS no longer includes rules-injector.sh (retired)', () => {
+  it('R1a: DEFAULT_HOOK_SCRIPTS has no entry whose command is .claude/hooks/rules-injector.sh', () => {
+    const entry = DEFAULT_HOOK_SCRIPTS.find((h) => h.command === RETIRED_COMMAND);
+    assert.equal(
       entry,
-      `DEFAULT_HOOK_SCRIPTS must register .claude/hooks/rules-injector.sh; ` +
+      undefined,
+      `DEFAULT_HOOK_SCRIPTS must no longer register ${RETIRED_COMMAND} (retired by S1); ` +
         `got commands: ${DEFAULT_HOOK_SCRIPTS.map((h) => h.command).join(', ')}`,
     );
   });
 
-  it('R1b: the rules-injector.sh registration fires on SessionStart', () => {
-    const entry = DEFAULT_HOOK_SCRIPTS.find(
-      (h) => h.command === '.claude/hooks/rules-injector.sh',
-    );
-    assert.ok(entry, 'rules-injector.sh must be registered in DEFAULT_HOOK_SCRIPTS');
-    assert.equal(
-      entry.event,
-      'SessionStart',
-      `rules-injector.sh must be registered on the SessionStart event; got: ${entry?.event}`,
+  it('R1b: DEFAULT_HOOK_SCRIPTS registers exactly the three surviving hooks', () => {
+    const commands = DEFAULT_HOOK_SCRIPTS.map((h) => h.command).sort();
+    const expected = [
+      '.claude/hooks/managed-file-guard.sh',
+      '.claude/hooks/steering-injector.sh',
+      '.claude/hooks/uncommitted-check.sh',
+    ].sort();
+    assert.deepEqual(
+      commands,
+      expected,
+      `DEFAULT_HOOK_SCRIPTS must register exactly the three surviving hooks, no more, no fewer; ` +
+        `got: ${commands.join(', ')}`,
     );
   });
 
-  it('R1c: the three pre-existing managed hooks are still registered (additive, not replaced)', () => {
+  it('R1c: the three pre-existing managed hooks are still registered (retirement is subtractive only, not destructive)', () => {
     const commands = DEFAULT_HOOK_SCRIPTS.map((h) => h.command);
     for (const expected of [
       '.claude/hooks/steering-injector.sh',
@@ -172,17 +244,17 @@ describe('S2 R1 — DEFAULT_HOOK_SCRIPTS includes rules-injector.sh', () => {
     ]) {
       assert.ok(
         commands.includes(expected),
-        `registering rules-injector.sh must not drop the existing ${expected} registration`,
+        `retiring rules-injector.sh must not drop the existing ${expected} registration`,
       );
     }
   });
 });
 
 // ---------------------------------------------------------------------------
-// R2 — init wires a tagged SessionStart registration for rules-injector.sh
+// R2 — init never wires rules-injector.sh into settings.json
 // ---------------------------------------------------------------------------
 
-describe('S2 R2 — init wires rules-injector.sh into settings.json', () => {
+describe('S1 R2 — init does not wire rules-injector.sh into settings.json (retired)', () => {
   let consumerDir;
 
   beforeEach(() => {
@@ -193,7 +265,7 @@ describe('S2 R2 — init wires rules-injector.sh into settings.json', () => {
     rmSync(consumerDir, { recursive: true, force: true });
   });
 
-  it('R2a: init registers a SessionStart entry for rules-injector.sh', async () => {
+  it('R2a: init does not register a SessionStart entry for rules-injector.sh', async () => {
     await runInit(consumerDir, {
       targets: ['claude'],
       fetcher: makeFixtureFetcher(),
@@ -211,34 +283,25 @@ describe('S2 R2 — init wires rules-injector.sh into settings.json', () => {
         e.hooks.some((h) => typeof h.command === 'string' && h.command.includes('rules-injector.sh')),
     );
     assert.ok(
-      found,
-      'settings.json must contain a SessionStart hook entry for rules-injector.sh after init',
+      !found,
+      'settings.json must NOT contain a SessionStart hook entry for rules-injector.sh after init (retired)',
     );
   });
 
-  it('R2b: the injected rules-injector.sh entry carries the HOOK_TAG', async () => {
+  it('R2b: init does not install .claude/hooks/rules-injector.sh on disk', async () => {
     await runInit(consumerDir, {
       targets: ['claude'],
       fetcher: makeFixtureFetcher(),
       availableTags: AVAILABLE_TAGS,
     });
 
-    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
-    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
-    const sessionStart = settings.hooks?.SessionStart ?? [];
-    const taggedEntry = sessionStart.find(
-      (e) =>
-        e[HOOK_TAG] === true &&
-        Array.isArray(e.hooks) &&
-        e.hooks.some((h) => typeof h.command === 'string' && h.command.includes('rules-injector.sh')),
-    );
     assert.ok(
-      taggedEntry,
-      `rules-injector.sh SessionStart entry must carry HOOK_TAG ("${HOOK_TAG}") so it is identifiable as CLI-managed`,
+      !existsSync(path.join(consumerDir, '.claude', 'hooks', 'rules-injector.sh')),
+      'init must not write .claude/hooks/rules-injector.sh — the fetched FileMap no longer ships it (retired)',
     );
   });
 
-  it('R2c: rules-injector.sh registration coexists with the three pre-existing managed hooks', async () => {
+  it('R2c: the three surviving managed hooks are still wired by init (additive behavior unaffected by retirement)', async () => {
     await runInit(consumerDir, {
       targets: ['claude'],
       fetcher: makeFixtureFetcher(),
@@ -249,25 +312,24 @@ describe('S2 R2 — init wires rules-injector.sh into settings.json', () => {
     const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
     const commands = allHookCommands(settings).map((c) => c.command);
 
-    for (const expected of [
-      'steering-injector.sh',
-      'managed-file-guard.sh',
-      'uncommitted-check.sh',
-      'rules-injector.sh',
-    ]) {
+    for (const expected of ['steering-injector.sh', 'managed-file-guard.sh', 'uncommitted-check.sh']) {
       assert.ok(
         commands.some((cmd) => cmd.includes(expected)),
-        `settings.json must register ${expected} alongside the other managed hooks after init`,
+        `settings.json must still register ${expected} after init`,
       );
     }
+    assert.ok(
+      !commands.some((cmd) => cmd.includes('rules-injector.sh')),
+      'settings.json must not register rules-injector.sh after init',
+    );
   });
 });
 
 // ---------------------------------------------------------------------------
-// R3 — update wires rules-injector.sh on a pre-initialized consumer repo
+// R3 — update PRUNES a pre-S1 consumer's existing rules-injector.sh entry
 // ---------------------------------------------------------------------------
 
-describe('S2 R3 — update wires rules-injector.sh into settings.json', () => {
+describe('S1 R3 — update prunes a pre-existing rules-injector.sh registration (migration)', () => {
   let consumerDir;
 
   beforeEach(() => {
@@ -278,8 +340,9 @@ describe('S2 R3 — update wires rules-injector.sh into settings.json', () => {
     rmSync(consumerDir, { recursive: true, force: true });
   });
 
-  it('R3a: update registers a SessionStart entry for rules-injector.sh', async () => {
+  it('R3a: a consumer with a managed rules-injector.sh SessionStart entry from before S1 has it pruned by update', async () => {
     setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+    writePreS1SettingsWithRulesInjector(consumerDir);
 
     await runUpdate(consumerDir, {
       fetcher: makeFixtureFetcher(),
@@ -287,41 +350,47 @@ describe('S2 R3 — update wires rules-injector.sh into settings.json', () => {
     });
 
     const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
-    assert.ok(existsSync(settingsPath), '.claude/settings.json must exist after update');
-
     const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
     const sessionStart = settings.hooks?.SessionStart ?? [];
-    const found = sessionStart.some(
+    const stillPresent = sessionStart.some(
       (e) =>
         Array.isArray(e.hooks) &&
         e.hooks.some((h) => typeof h.command === 'string' && h.command.includes('rules-injector.sh')),
     );
     assert.ok(
-      found,
-      'settings.json must contain a SessionStart hook entry for rules-injector.sh after update',
+      !stillPresent,
+      'update must prune the pre-S1 managed rules-injector.sh SessionStart entry; ' +
+        `got hooks.SessionStart: ${JSON.stringify(sessionStart)}`,
     );
   });
 
-  it('R3b: rules-injector.sh script itself is installed by update', async () => {
+  it('R3b: pruning the retired entry does not disturb the three surviving hooks getting wired', async () => {
     setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+    writePreS1SettingsWithRulesInjector(consumerDir);
 
     await runUpdate(consumerDir, {
       fetcher: makeFixtureFetcher(),
       availableTags: AVAILABLE_TAGS,
     });
 
-    assert.ok(
-      existsSync(path.join(consumerDir, '.claude', 'hooks', 'rules-injector.sh')),
-      'update must write .claude/hooks/rules-injector.sh',
-    );
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    const commands = allHookCommands(settings).map((c) => c.command);
+
+    for (const expected of ['steering-injector.sh', 'managed-file-guard.sh', 'uncommitted-check.sh']) {
+      assert.ok(
+        commands.some((cmd) => cmd.includes(expected)),
+        `settings.json must register ${expected} after update, alongside the rules-injector.sh prune`,
+      );
+    }
   });
 });
 
 // ---------------------------------------------------------------------------
-// R4 — idempotent: running update twice adds no duplicate registration
+// R4 — repeated update never reintroduces the pruned registration
 // ---------------------------------------------------------------------------
 
-describe('S2 R4 — repeated update produces no duplicate rules-injector.sh registration', () => {
+describe('S1 R4 — repeated update leaves the rules-injector.sh registration pruned (idempotent removal)', () => {
   let consumerDir;
 
   beforeEach(() => {
@@ -332,8 +401,9 @@ describe('S2 R4 — repeated update produces no duplicate rules-injector.sh regi
     rmSync(consumerDir, { recursive: true, force: true });
   });
 
-  it('R4: rules-injector.sh command appears at most once after two updates', async () => {
+  it('R4: rules-injector.sh command is absent after two updates starting from a pre-S1 tagged entry', async () => {
     setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+    writePreS1SettingsWithRulesInjector(consumerDir);
 
     const opts = { fetcher: makeFixtureFetcher(), availableTags: AVAILABLE_TAGS };
     await runUpdate(consumerDir, opts);
@@ -344,9 +414,378 @@ describe('S2 R4 — repeated update produces no duplicate rules-injector.sh regi
     const commands = allHookCommands(settings).map((c) => c.command);
     const occurrences = commands.filter((cmd) => cmd.includes('rules-injector.sh')).length;
 
+    assert.equal(
+      occurrences,
+      0,
+      `rules-injector.sh hook command must be absent (pruned, never reintroduced) after two updates ` +
+        `(found: ${occurrences})`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// S1 cycle 2 RED — deliver-validate finding H2 (major).
+//
+// mergeHookSettings returns `prunedRetired`, and all three call sites in
+// update.mjs / init.mjs discard it — nothing is ever printed when a retired
+// hook registration is pruned from a consumer's settings.json. Meanwhile the
+// FILE-orphan prune two blocks below in update.mjs DOES emit an
+// "info: dev-agents-sync: pruned N orphaned managed file(s)" line
+// (update.mjs:269-272) — so the silence on the hook-registration prune is an
+// inconsistency within one function, not house style.
+//
+// Worse: `runUpdate --dry-run` returns at update.mjs:187-202 BEFORE
+// mergeHookSettings is ever called, so the planned prune is never computed
+// or reported at all — while README.md:129's "Self-cleaning" bullet
+// advertises the behavior unconditionally.
+//
+// Intended fix (not yet implemented): `update` (and `init`) report the prune
+// on stderr, in the same "info: dev-agents-sync: ..." style as the existing
+// orphan-prune line, when prunedRetired.length > 0; and `update --dry-run`
+// computes and surfaces the planned prune (result.prunedRetired) instead of
+// skipping the computation.
+// ---------------------------------------------------------------------------
+
+describe('S1 H2 — update reports the retired-hook-registration prune (not silent)', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('H2a: runUpdate emits an info: dev-agents-sync: line naming the retired-hook prune when one occurs', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+    writePreS1SettingsWithRulesInjector(consumerDir);
+
+    const stderr = await captureStderr(() =>
+      runUpdate(consumerDir, { fetcher: makeFixtureFetcher(), availableTags: AVAILABLE_TAGS }),
+    );
+
+    assert.match(
+      stderr,
+      /info: dev-agents-sync:.*(prun|remov)[a-z]*.*(hook|registration|rules-injector)/i,
+      'runUpdate must report the retired-hook-registration prune on stderr, in the same ' +
+        '"info: dev-agents-sync: ..." style as the orphaned-file-prune line (update.mjs:269-272), ' +
+        `not silently discard mergeHookSettings’s prunedRetired result; got stderr:\n${stderr || '(empty)'}`,
+    );
+  });
+
+  it('H2b: update --dry-run computes and surfaces the planned retired-hook prune instead of skipping it', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+    writePreS1SettingsWithRulesInjector(consumerDir);
+
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    const before = readFileSync(settingsPath, 'utf8');
+
+    const result = await runUpdate(consumerDir, {
+      dryRun: true,
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
     assert.ok(
-      occurrences <= 1,
-      `rules-injector.sh hook command must appear at most once after two updates (found: ${occurrences})`,
+      Array.isArray(result.prunedRetired) && result.prunedRetired.includes(RETIRED_COMMAND),
+      '--dry-run must compute and surface the planned retired-hook-registration prune ' +
+        '(result.prunedRetired) rather than returning before mergeHookSettings is ever called ' +
+        `(README.md:129’s "Self-cleaning" bullet must hold under --dry-run too); got: ${JSON.stringify(result)}`,
+    );
+
+    const after = readFileSync(settingsPath, 'utf8');
+    assert.equal(after, before, '--dry-run must never write to settings.json');
+  });
+
+  it('H2c: no prune line is emitted when there is nothing to prune (guards against a spurious message every run)', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+    // settings.json is already fully wired to the three surviving hooks, with
+    // no retired registration anywhere — nothing to prune.
+    const settingsDir = path.join(consumerDir, '.claude');
+    mkdirSync(settingsDir, { recursive: true });
+    writeFileSync(
+      path.join(settingsDir, 'settings.json'),
+      JSON.stringify(
+        {
+          hooks: {
+            SessionStart: [
+              {
+                [HOOK_TAG]: true,
+                matcher: '.*',
+                hooks: [{ type: 'command', command: '.claude/hooks/steering-injector.sh' }],
+              },
+            ],
+            PostToolUse: [
+              {
+                [HOOK_TAG]: true,
+                matcher: '.*',
+                hooks: [{ type: 'command', command: '.claude/hooks/managed-file-guard.sh' }],
+              },
+            ],
+            Stop: [
+              {
+                [HOOK_TAG]: true,
+                matcher: '.*',
+                hooks: [{ type: 'command', command: '.claude/hooks/uncommitted-check.sh' }],
+              },
+            ],
+          },
+        },
+        null,
+        2,
+      ) + '\n',
+      'utf8',
+    );
+
+    const stderr = await captureStderr(() =>
+      runUpdate(consumerDir, { fetcher: makeFixtureFetcher(), availableTags: AVAILABLE_TAGS }),
+    );
+
+    assert.doesNotMatch(
+      stderr,
+      /rules-injector|retired hook|hook registration/i,
+      `no retired-hook-registration prune message must be emitted when nothing was pruned ` +
+        `(guards against a spurious message on every run); got stderr:\n${stderr}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// S1 cycle 3 — closing deferred Minor/Low findings from deliver-validate.
+//
+// M2 (Group A — regression guard): cycle 2 removed the `hookSpec.length > 0`
+// guard from all three settings-wiring call sites (update.mjs:149-154,
+// update.mjs:254-256, init.mjs:206-209) so a consumer with a stale retired
+// registration but NO hook scripts on disk still gets pruned. Validate's exact
+// words: "re-adding the guard at all three sites would leave both suites
+// green" — nothing pinned it before this test. This exercises the
+// up-to-date short-circuit branch specifically, since that is the one branch
+// that derives its hook spec from files present ON DISK (update.mjs:149-151)
+// rather than from the fetched FileMap, so it is the only branch where "no
+// hook scripts on disk" naturally produces an empty spec.
+//
+// M3 (Group A — regression guard): R2a/R2b only assert init never ADDS the
+// retired registration; nothing asserted it REMOVES a pre-existing one.
+// init.mjs:207-208 justifies its unconditional wiring call by claiming init
+// run over an existing .claude/ can meet a pre-retirement settings.json —
+// e.g. a second `init` re-run, or a consumer who lost their lockfile. That
+// claim was unpinned before this test.
+//
+// M1 (Group B — RED): init.mjs:135-155 returns before any hook wiring is
+// computed, so `runInit --dry-run`'s result never carries a `prunedRetired`
+// field at all — update.mjs:196-198 explicitly calls out that under-reporting
+// "a real, intended change to consumer-owned state" as the reason update's
+// dry-run computes it. init's write path is correct (see M3); only its PLAN
+// is incomplete.
+//
+// L5 (Group B — RED): hooks.mjs:69-73 prints `prunedRetired.length`, but
+// settings.mjs:220 dedupes that list with `[...new Set(pruned)]`. So the same
+// retired command registered under TWO event buckets is removed twice but
+// reported as pruning only 1 distinct command.
+// ---------------------------------------------------------------------------
+
+describe('S1 M2 — update prunes a retired registration on the up-to-date short-circuit even with no hook scripts on disk', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('M2: an up-to-date consumer with a pre-S1 tagged rules-injector.sh entry and an empty .claude/hooks/ dir still gets it pruned', async () => {
+    // Pin resolvedVersion to the highest tag AVAILABLE_TAGS/`^1` resolves to
+    // (1.2.0) so update takes the up-to-date short-circuit (update.mjs:140-164)
+    // rather than fetching. That branch filters DEFAULT_HOOK_SCRIPTS down to
+    // commands that `existsSync` on disk BEFORE calling wireHookSettings — with
+    // no hooks installed, that filtered spec is empty. The prune must still run
+    // because it was deliberately made unconditional on the spec's length
+    // (update.mjs:152-154's comment); re-adding a `hookSpec.length > 0` guard
+    // would make this a silent no-op and fail the assertions below.
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.2.0' });
+    writePreS1SettingsWithRulesInjector(consumerDir);
+
+    // No hook scripts on disk anywhere — .claude/hooks/ exists but is empty.
+    mkdirSync(path.join(consumerDir, '.claude', 'hooks'), { recursive: true });
+
+    const result = await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.equal(
+      result.upToDate,
+      true,
+      'this test must exercise the up-to-date short-circuit (update.mjs:140-164); ' +
+        `got: ${JSON.stringify(result)}`,
+    );
+    assert.ok(
+      Array.isArray(result.prunedRetired) && result.prunedRetired.includes(RETIRED_COMMAND),
+      `result.prunedRetired must report "${RETIRED_COMMAND}" pruned even though no hook scripts ` +
+        `are on disk; got: ${JSON.stringify(result.prunedRetired)}`,
+    );
+
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    const sessionStart = settings.hooks?.SessionStart ?? [];
+    const stillPresent = sessionStart.some(
+      (e) => Array.isArray(e.hooks) && e.hooks.some((h) => h.command === RETIRED_COMMAND),
+    );
+    assert.ok(
+      !stillPresent,
+      `the pre-S1 rules-injector.sh entry must be pruned even though no hook scripts are on disk; ` +
+        `got hooks.SessionStart: ${JSON.stringify(sessionStart)}`,
+    );
+  });
+});
+
+describe('S1 M3 — init prunes a pre-existing tagged retired entry (mirrors R3a, but for runInit)', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('M3: runInit prunes a pre-existing managed rules-injector.sh SessionStart entry and reports it in result.prunedRetired', async () => {
+    // Simulates a consumer whose .claude/settings.json already carries a
+    // pre-retirement managed registration (e.g. a lost lockfile, or a second
+    // `init` re-run over an already-hook-wired .claude/) — the scenario
+    // init.mjs:207-208's comment claims is possible but that R2a/R2b never
+    // exercised (those only prove init never ADDS the retired registration).
+    writePreS1SettingsWithRulesInjector(consumerDir);
+
+    const result = await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.ok(
+      Array.isArray(result.prunedRetired) && result.prunedRetired.includes(RETIRED_COMMAND),
+      `runInit's result must report "${RETIRED_COMMAND}" pruned; got: ${JSON.stringify(result.prunedRetired)}`,
+    );
+
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    const sessionStart = settings.hooks?.SessionStart ?? [];
+    const stillPresent = sessionStart.some(
+      (e) => Array.isArray(e.hooks) && e.hooks.some((h) => h.command === RETIRED_COMMAND),
+    );
+    assert.ok(
+      !stillPresent,
+      `init must prune the pre-existing managed rules-injector.sh entry; ` +
+        `got hooks.SessionStart: ${JSON.stringify(sessionStart)}`,
+    );
+  });
+});
+
+describe('S1 M1 — init --dry-run computes and reports the planned retired-hook prune', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('M1: runInit --dry-run over a consumer with a pre-existing tagged retired entry reports the planned prune and writes nothing', async () => {
+    writePreS1SettingsWithRulesInjector(consumerDir);
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    const before = readFileSync(settingsPath, 'utf8');
+
+    const result = await runInit(consumerDir, {
+      dryRun: true,
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.ok(
+      Array.isArray(result.prunedRetired) && result.prunedRetired.includes(RETIRED_COMMAND),
+      'runInit --dry-run must compute and report the planned retired-hook-registration prune ' +
+        `(mirroring update's prunedRetired field name), not skip it because init.mjs:135-155 ` +
+        `returns before any hook wiring is computed; got: ${JSON.stringify(result)}`,
+    );
+
+    const after = readFileSync(settingsPath, 'utf8');
+    assert.equal(after, before, '--dry-run must never write to settings.json');
+  });
+});
+
+describe('S1 L5 — the prune info line counts registrations removed, not distinct commands', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('L5: a retired command registered under two event buckets is reported as 2 registrations pruned, not deduped to 1', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    // The SAME retired command, tagged, registered under TWO different event
+    // buckets — settings.mjs:220 dedupes prunedRetired with
+    // `[...new Set(pruned)]` before hooks.mjs reports its length, so this
+    // removes TWO registrations but (today) is reported as pruning only 1
+    // distinct command.
+    const settingsDir = path.join(consumerDir, '.claude');
+    mkdirSync(settingsDir, { recursive: true });
+    writeFileSync(
+      path.join(settingsDir, 'settings.json'),
+      JSON.stringify(
+        {
+          hooks: {
+            SessionStart: [
+              {
+                [HOOK_TAG]: true,
+                matcher: '.*',
+                hooks: [{ type: 'command', command: RETIRED_COMMAND }],
+              },
+            ],
+            PostToolUse: [
+              {
+                [HOOK_TAG]: true,
+                matcher: '.*',
+                hooks: [{ type: 'command', command: RETIRED_COMMAND }],
+              },
+            ],
+          },
+        },
+        null,
+        2,
+      ) + '\n',
+      'utf8',
+    );
+
+    const stderr = await captureStderr(() =>
+      runUpdate(consumerDir, { fetcher: makeFixtureFetcher(), availableTags: AVAILABLE_TAGS }),
+    );
+
+    // Assert on the emitted MESSAGE (not on settings.mjs's internal array shape)
+    // so a fix is free to report the count however it likes internally, as long
+    // as the number a consumer reads on their terminal is correct.
+    const match = stderr.match(/(\d+)\D{0,40}regist/i);
+    assert.ok(
+      match,
+      `stderr must report a registration count for the prune; got stderr:\n${stderr || '(empty)'}`,
+    );
+    assert.equal(
+      match[1],
+      '2',
+      'the prune info line must report 2 registrations removed (one per event bucket the retired ' +
+        `command was registered under), not the deduped distinct-command count (1); got stderr:\n${stderr}`,
     );
   });
 });