claude-dev-env 1.72.0 → 1.73.0

package/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md

@@ -23,9 +23,9 @@ Decomposition is by the **kind of docstring claim** that needs to be cross-check
 | O1 | Module-level responsibility verbs | A module docstring uses verbs (`detects`, `validates`, `enforces`, `recovers`, `parses`, `routes`) — every claimed responsibility is implemented by an exported symbol in the same module. Symbols absent from the module body should not appear as this module's responsibilities. |
 | O2 | Fixture docstring vs sibling-test behavior | An autouse / module-scope fixture docstring asserts an invariant (`readability is disabled`, `network is mocked`, `tmp_path is empty`). No sibling test in the same module explicitly opts out of the invariant. |
 | O3 | Predicate-name and -docstring vs body breadth | A boolean helper's name and docstring promise a narrow predicate. Walk the body's branches: every branch's `return True` path is consistent with the promised name. Bodies that accept inputs broader than the name (`_dir_value_resolves_to_shared_temp` also accepting HOME/TMP env-derived paths) are O3 findings. |
-| O4 | Step-ordering narrative | A docstring describes processing as `A then B then C`. Walk the body and confirm the call order matches. Mismatched order is an O4 finding regardless of whether the final output is the same. |
+| O4 | Step-ordering narrative | A docstring describes processing as `A then B then C`. Walk the body and confirm the call order matches. Mismatched order is an O4 finding regardless of whether the final output is the same. A docstring step enumeration that names the body's linear steps but omits a corrective workflow step the body guards inside an `if`/`elif` branch (`if not await cancel_and_reinitiate_update(...): return`) is also an O4 finding: the reader trusts the step list to be complete and misses the conditional path. The branch-guarded-dispatch shape of this drift — a docstring that names two or more linear-step callees while the body guards a two-or-more-token dispatch callee inside a branch whose name the prose never spells out — is gated deterministically at Write/Edit time by `check_docstring_step_enumeration_dispatch_coverage` (`packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py`), so the audit lane focuses on the step-ordering shapes the gate cannot match (re-ordered steps, plain unguarded steps the prose omits). |
 | O5 | Named-sentinel / filename references | A docstring names a sentinel marker, environment variable, filename, or magic string. Confirm the named token actually exists in the module body or in the repo's naming convention. |
-| O6 | Free-form `Args:`-adjacent claims | A docstring's `Returns:` / `Raises:` / `Note:` / `Example:` sections make claims (`returns shared-temp only`, `raises ValueError on missing key`). Verify each claim against the body. When a docstring enumerates the inputs a body counts (a "field counts as read when ..." list, a list of conditions treated as a match, a list of cases the body skips), list every union member and every suppressor the body applies (`read_names = a | b | c`, each early-return guard) and confirm each appears in the prose enumeration. A union member or suppressor the body applies but the prose omits is an O6 finding. The single-condition shared-fallback shape of this drift — a summary that scopes a fallback call to one condition while the body routes to that same call from two or more early-return guards — is gated deterministically at Write/Edit time by `check_docstring_fallback_branch_coverage`, so the audit lane focuses on the O6 shapes the gate cannot match. A `Returns:` that names the mechanism, tool, or output format the function produces (`instructing a StructuredOutput summary`, `returns a YAML document`, `emits a JSON object`) matches the artifact the body actually builds: a prompt body that asks the agent to "Return strictly a JSON object" while the docstring claims it "instruct[s] a StructuredOutput" summary is an O6 finding, because the named tool appears nowhere in the emitted text. See `../../rules/docstring-prose-matches-implementation.md`. |
+| O6 | Free-form `Args:`-adjacent claims | A docstring's `Returns:` / `Raises:` / `Note:` / `Example:` sections make claims (`returns shared-temp only`, `raises ValueError on missing key`). Verify each claim against the body. When a docstring enumerates the inputs a body counts (a "field counts as read when ..." list, a list of conditions treated as a match, a list of cases the body skips), list every union member and every suppressor the body applies (`read_names = a | b | c`, each early-return guard) and confirm each appears in the prose enumeration. A union member or suppressor the body applies but the prose omits is an O6 finding. When a docstring sentence excludes a named category of input from what the function flags (`X are not dispatch steps`, `Y is not a match`), confirm the axis the prose excludes on is the axis the body's branch condition actually keys on. A body that flags a call when it sits inside an `If.test` guard, paired with prose that excludes by the call's receiver shape (`method-on-local calls inside a branch are not dispatch steps`), is an O6 finding: a guarded method-on-local call is flagged even though the prose lists it as excluded — the exclusion is keyed to the wrong axis. The single-condition shared-fallback shape of this drift — a summary that scopes a fallback call to one condition while the body routes to that same call from two or more early-return guards — is gated deterministically at Write/Edit time by `check_docstring_fallback_branch_coverage`, so the audit lane focuses on the O6 shapes the gate cannot match. A `Returns:` that names the mechanism, tool, or output format the function produces (`instructing a StructuredOutput summary`, `returns a YAML document`, `emits a JSON object`) matches the artifact the body actually builds: a prompt body that asks the agent to "Return strictly a JSON object" while the docstring claims it "instruct[s] a StructuredOutput" summary is an O6 finding, because the named tool appears nowhere in the emitted text. See `../../rules/docstring-prose-matches-implementation.md`. |
 | O7 | Module-doc-vs-split-module after refactor | When a refactor moves a responsibility to a sibling module, the originating module's docstring and the receiving module's docstring both describe the home of that responsibility. A module docstring should describe only the responsibilities it owns. |
 | O8 | Companion-doc ordering/content vs producer | When a PR changes a producer function's ordering or union, read that skill's companion `SKILL.md` and sibling `.md` docs for any sentence naming the same produced artifact (a file path, a JSON key, a named list). A doc sentence that claims the artifact is `sorted` / `alphabetical` / `in sorted order`, or holds `just the at-risk names` / `only the current set`, while the producer merges stored names with new names and appends — preserving file order, not re-sorting the union — is an O8 finding on both counts (wrong order claim, hidden merged-in entries). The finding stands even when the PR diff never touched the `.md` file, because the behavior change orphaned the doc claim. See `../../rules/docstring-prose-matches-implementation.md`. |
 

package/bin/install.mjs

@@ -293,18 +293,59 @@ function backupClaudeHubBeforeOverwrite(destPath, incomingPath) {
     return backupPath;
 }
 
+/**
+ * Hook script paths that were folded into the PreToolUse dispatcher in Stage 1.
+ * These entries no longer appear in hooks.json but must still be recognized as
+ * managed so a reinstall from an older settings shape prunes them and they do
+ * not double-run alongside the dispatcher.
+ */
+export const FOLDED_HOOK_RELATIVE_PATHS = new Set([
+    'blocking/write_existing_file_blocker.py',
+    'blocking/sensitive_file_protector.py',
+    'validation/hook_format_validator.py',
+    'blocking/code_rules_enforcer.py',
+    'blocking/tdd_enforcer.py',
+    'blocking/windows_rmtree_blocker.py',
+    'blocking/state_description_blocker.py',
+    'blocking/subprocess_budget_completeness.py',
+    'blocking/hook_prose_detector_consistency.py',
+    'blocking/verified_commit_message_accuracy_blocker.py',
+    'blocking/workflow_substitution_slot_blocker.py',
+    'blocking/claude_md_orphan_file_blocker.py',
+    'blocking/pytest_testpaths_orphan_blocker.py',
+    'blocking/open_questions_in_plans_blocker.py',
+    'blocking/plain_language_blocker.py',
+]);
+
+/**
+ * Hook script paths that were folded into the PostToolUse dispatcher. These
+ * after-write hooks no longer appear in hooks.json but must still be recognized
+ * as managed so a reinstall from an older settings shape prunes them and they do
+ * not double-run alongside the PostToolUse dispatcher.
+ */
+export const POST_FOLDED_HOOK_RELATIVE_PATHS = new Set([
+    'validation/mypy_validator.py',
+    'workflow/auto_formatter.py',
+    'workflow/doc_gist_auto_publish.py',
+]);
+
 /**
  * Builds the set of hook script paths this installer manages, each relative to
  * the hooks directory (e.g. 'blocking/code_rules_enforcer.py'), parsed from the
  * `${CLAUDE_PLUGIN_ROOT}/hooks/<path>` references in hooks.json. Inline
  * `python3 -c` commands reference the hooks directory without a script tail and
- * contribute nothing.
+ * contribute nothing. Also includes every path from FOLDED_HOOK_RELATIVE_PATHS
+ * and POST_FOLDED_HOOK_RELATIVE_PATHS so a reinstall from an older settings shape
+ * prunes both the PreToolUse and the PostToolUse folded entries.
  *
  * @param {{hooks: object}} hooksConfig Parsed hooks.json.
  * @returns {Set<string>} Forward-slash relative script paths under hooks/.
  */
 export function managedHookScriptRelativePaths(hooksConfig) {
-    const relativePaths = new Set();
+    const relativePaths = new Set([
+        ...FOLDED_HOOK_RELATIVE_PATHS,
+        ...POST_FOLDED_HOOK_RELATIVE_PATHS,
+    ]);
     const scriptReferencePattern = /\$\{CLAUDE_PLUGIN_ROOT\}\/hooks\/(\S+?\.py)/g;
     for (const matcherGroups of Object.values(hooksConfig.hooks)) {
         for (const sourceGroup of matcherGroups) {
@@ -426,12 +467,38 @@ export function commandIsInlineManagedValidatorRunner(normalizedCommand) {
     );
 }
 
+/**
+ * Strips every managed hook (standalone script or inline validators runner) from
+ * all existing matcher groups of one event in a settings object, dropping any
+ * group left empty. Run before the per-group merge so a managed hook that an
+ * upgrade moves to a different matcher group is pruned from its old group rather
+ * than left to double-run. User-authored hooks outside the managed set stay.
+ *
+ * @param {object} settings The parsed settings.json object (mutated in place).
+ * @param {string} eventType The lifecycle event whose groups are pruned.
+ * @param {Set<string>} managedHookRelativePaths Managed script paths under hooks/.
+ * @returns {void}
+ */
+function pruneManagedHooksFromEvent(settings, eventType, managedHookRelativePaths) {
+    const existingGroups = settings.hooks[eventType];
+    if (!existingGroups) return;
+    settings.hooks[eventType] = existingGroups
+        .map(group => ({
+            ...group,
+            hooks: group.hooks.filter(
+                hook => !commandReferencesManagedHook(hook.command, managedHookRelativePaths)
+            ),
+        }))
+        .filter(group => group.hooks.length > 0);
+}
+
 /**
  * Merges the installer's managed hook groups into a settings object in memory,
  * pruning every prior managed hook (standalone script or inline validators
- * runner) from each matcher group before appending the freshly rewritten copies
- * so repeated merges stay idempotent. User-authored hooks in the same group are
- * preserved untouched.
+ * runner) from each event's existing matcher groups before appending the freshly
+ * rewritten copies so repeated merges stay idempotent and a managed hook moved to
+ * a new matcher group does not double-run. User-authored hooks are preserved
+ * untouched.
  *
  * @param {object} settings The parsed settings.json object (mutated in place).
  * @param {{hooks: object}} hooksConfig Parsed hooks.json.
@@ -445,6 +512,7 @@ export function mergeHooksIntoSettings(settings, hooksConfig, pluginRootDir, pyt
     let groupCount = 0;
     for (const [eventType, matcherGroups] of Object.entries(hooksConfig.hooks)) {
         if (!settings.hooks[eventType]) settings.hooks[eventType] = [];
+        pruneManagedHooksFromEvent(settings, eventType, managedHookRelativePaths);
         for (const sourceGroup of matcherGroups) {
             const rewrittenHooks = sourceGroup.hooks.map(hook => {
                 let command = hook.command;

package/bin/install.test.mjs

@@ -1,7 +1,7 @@
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { execFileSync } from 'node:child_process';
-import { mkdtempSync, rmSync, mkdirSync, writeFileSync, symlinkSync } from 'node:fs';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, symlinkSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -9,6 +9,8 @@ import { pathToFileURL } from 'node:url';
 import {
     collectPackageSourceConflicts,
     CONTENT_DIRECTORIES,
+    FOLDED_HOOK_RELATIVE_PATHS,
+    POST_FOLDED_HOOK_RELATIVE_PATHS,
     pythonCandidatesForPlatform,
     isWindowsStorePythonStub,
     interpreterCommandFromPath,
@@ -361,7 +363,9 @@ test('managedHookScriptRelativePaths collects every installed hook script path a
     const relativePaths = managedHookScriptRelativePaths(SAMPLE_HOOKS_CONFIG);
     assert.ok(relativePaths.has('notification/attention_needed_notify.py'));
     assert.ok(relativePaths.has('blocking/hedging_language_blocker.py'));
-    assert.equal([...relativePaths].length, 2);
+    for (const foldedPath of FOLDED_HOOK_RELATIVE_PATHS) {
+        assert.ok(relativePaths.has(foldedPath), `folded hook ${foldedPath} must always be in the managed set`);
+    }
 });
 
 
@@ -566,7 +570,9 @@ test('managedHookScriptRelativePathsFromSourceRoots reads each root hooks.json s
 
         assert.ok(relativePaths.has('notification/attention_needed_notify.py'));
         assert.ok(relativePaths.has('blocking/hedging_language_blocker.py'));
-        assert.equal([...relativePaths].length, 2);
+        for (const foldedPath of FOLDED_HOOK_RELATIVE_PATHS) {
+            assert.ok(relativePaths.has(foldedPath), `folded hook ${foldedPath} must always be in the managed set`);
+        }
     } finally {
         rmSync(sourceRoot, { recursive: true, force: true });
     }
@@ -588,7 +594,9 @@ test('managedHookScriptRelativePathsFromSourceRoots unions managed scripts acros
 
         assert.ok(relativePaths.has('blocking/code_rules_enforcer.py'));
         assert.ok(relativePaths.has('blocking/pwsh_enforcer.py'));
-        assert.equal([...relativePaths].length, 2);
+        for (const foldedPath of FOLDED_HOOK_RELATIVE_PATHS) {
+            assert.ok(relativePaths.has(foldedPath), `folded hook ${foldedPath} must always be in the managed set`);
+        }
     } finally {
         rmSync(builtinRoot, { recursive: true, force: true });
         rmSync(dependencyRoot, { recursive: true, force: true });
@@ -647,3 +655,351 @@ test('purge set sourced from package hooks.json prunes standalone managed script
         rmSync(sourceRoot, { recursive: true, force: true });
     }
 });
+
+
+const DISPATCHER_HOOKS_CONFIG = {
+    hooks: {
+        PreToolUse: [
+            {
+                matcher: 'Write|Edit',
+                hooks: [
+                    {
+                        type: 'command',
+                        command: 'python3 -c "import sys; sys.path.insert(0, r\'${CLAUDE_PLUGIN_ROOT}/hooks\'); from validators.run_all_validators import main; sys.exit(main())"',
+                        timeout: 15,
+                    },
+                ],
+            },
+            {
+                matcher: 'Write|Edit|MultiEdit',
+                hooks: [
+                    {
+                        type: 'command',
+                        command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pre_tool_use_dispatcher.py',
+                        timeout: 60,
+                    },
+                ],
+            },
+        ],
+    },
+};
+
+const OLD_FOLDED_HOOKS_SETTINGS = {
+    hooks: {
+        PreToolUse: [
+            {
+                matcher: 'Write|Edit',
+                hooks: [
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/write_existing_file_blocker.py', timeout: 10 },
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/sensitive_file_protector.py', timeout: 10 },
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/validation/hook_format_validator.py', timeout: 15 },
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/code_rules_enforcer.py', timeout: 30 },
+                    { type: 'command', command: 'py -3 -c "import sys; sys.path.insert(0, r\'C:/Users/x/.claude/hooks\'); from validators.run_all_validators import main; sys.exit(main())"', timeout: 15 },
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/tdd_enforcer.py', timeout: 10 },
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/windows_rmtree_blocker.py', timeout: 10 },
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/state_description_blocker.py', timeout: 10 },
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/subprocess_budget_completeness.py', timeout: 10 },
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/hook_prose_detector_consistency.py', timeout: 10 },
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/verified_commit_message_accuracy_blocker.py', timeout: 10 },
+                ],
+            },
+            {
+                matcher: 'Write|Edit|MultiEdit',
+                hooks: [
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/workflow_substitution_slot_blocker.py', timeout: 10 },
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/claude_md_orphan_file_blocker.py', timeout: 10 },
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/pytest_testpaths_orphan_blocker.py', timeout: 10 },
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/open_questions_in_plans_blocker.py', timeout: 10 },
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/plain_language_blocker.py', timeout: 10 },
+                ],
+            },
+        ],
+    },
+};
+
+
+test('FOLDED_HOOK_RELATIVE_PATHS contains all 15 hooks removed from hooks.json', () => {
+    assert.equal(FOLDED_HOOK_RELATIVE_PATHS.size, 15);
+    assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/write_existing_file_blocker.py'));
+    assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/plain_language_blocker.py'));
+    assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/code_rules_enforcer.py'));
+    assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/pytest_testpaths_orphan_blocker.py'));
+});
+
+
+test('FOLDED_HOOK_RELATIVE_PATHS lists every hook the PreToolUse dispatcher hosts', () => {
+    const dispatcherHostedHooks = [
+        'blocking/write_existing_file_blocker.py',
+        'blocking/sensitive_file_protector.py',
+        'validation/hook_format_validator.py',
+        'blocking/code_rules_enforcer.py',
+        'blocking/tdd_enforcer.py',
+        'blocking/windows_rmtree_blocker.py',
+        'blocking/state_description_blocker.py',
+        'blocking/subprocess_budget_completeness.py',
+        'blocking/hook_prose_detector_consistency.py',
+        'blocking/verified_commit_message_accuracy_blocker.py',
+        'blocking/workflow_substitution_slot_blocker.py',
+        'blocking/claude_md_orphan_file_blocker.py',
+        'blocking/pytest_testpaths_orphan_blocker.py',
+        'blocking/open_questions_in_plans_blocker.py',
+        'blocking/plain_language_blocker.py',
+    ];
+    for (const hostedPath of dispatcherHostedHooks) {
+        assert.ok(
+            FOLDED_HOOK_RELATIVE_PATHS.has(hostedPath),
+            `dispatcher-hosted hook ${hostedPath} must be in FOLDED_HOOK_RELATIVE_PATHS so a reinstall prunes its stale standalone entry and it does not double-run`
+        );
+    }
+    assert.equal(
+        FOLDED_HOOK_RELATIVE_PATHS.size,
+        dispatcherHostedHooks.length,
+        'FOLDED_HOOK_RELATIVE_PATHS must hold exactly the dispatcher-hosted hooks, no more, no fewer'
+    );
+});
+
+
+test('managedHookScriptRelativePaths includes the dispatcher and all folded hooks so old entries are prunable', () => {
+    const relativePaths = managedHookScriptRelativePaths(DISPATCHER_HOOKS_CONFIG);
+    assert.ok(relativePaths.has('blocking/pre_tool_use_dispatcher.py'), 'dispatcher must be in managed set');
+    for (const foldedPath of FOLDED_HOOK_RELATIVE_PATHS) {
+        assert.ok(relativePaths.has(foldedPath), `folded hook ${foldedPath} must be in managed set`);
+    }
+});
+
+
+test('mergeHooksIntoSettings into old folded-hooks settings yields exactly one dispatcher entry and no folded entries', () => {
+    const settings = JSON.parse(JSON.stringify(OLD_FOLDED_HOOKS_SETTINGS));
+    mergeHooksIntoSettings(settings, DISPATCHER_HOOKS_CONFIG, 'C:/Users/x/.claude', 'py -3');
+
+    const allPreToolUseGroups = settings.hooks.PreToolUse || [];
+    const allHookCommands = allPreToolUseGroups.flatMap(group => group.hooks.map(hook => hook.command));
+
+    const allDispatcherCommands = allHookCommands.filter(cmd => cmd.includes('pre_tool_use_dispatcher.py'));
+    assert.equal(allDispatcherCommands.length, 1, 'exactly one dispatcher entry must be present');
+
+    for (const foldedPath of FOLDED_HOOK_RELATIVE_PATHS) {
+        const foldedBasename = foldedPath.split('/').pop();
+        const foldedCommands = allHookCommands.filter(
+            cmd => cmd.includes(foldedBasename) && !cmd.includes('pre_tool_use_dispatcher')
+        );
+        assert.equal(foldedCommands.length, 0, `folded hook ${foldedBasename} must not appear as a separate entry`);
+    }
+});
+
+
+test('mergeHooksIntoSettings into old folded-hooks settings preserves the inline validators runner', () => {
+    const settings = JSON.parse(JSON.stringify(OLD_FOLDED_HOOKS_SETTINGS));
+    mergeHooksIntoSettings(settings, DISPATCHER_HOOKS_CONFIG, 'C:/Users/x/.claude', 'py -3');
+
+    assert.equal(
+        countManagedRunAllValidatorsHooks(settings),
+        1,
+        'exactly one run_all_validators hook must remain in Write|Edit',
+    );
+});
+
+
+test('mergeHooksIntoSettings is idempotent when run twice against an already-updated settings shape', () => {
+    const settings = JSON.parse(JSON.stringify(OLD_FOLDED_HOOKS_SETTINGS));
+    mergeHooksIntoSettings(settings, DISPATCHER_HOOKS_CONFIG, 'C:/Users/x/.claude', 'py -3');
+    mergeHooksIntoSettings(settings, DISPATCHER_HOOKS_CONFIG, 'C:/Users/x/.claude', 'py -3');
+
+    const allPreToolUseGroups = settings.hooks.PreToolUse || [];
+    const allHookCommands = allPreToolUseGroups.flatMap(group => group.hooks.map(hook => hook.command));
+
+    const allDispatcherCommands = allHookCommands.filter(cmd => cmd.includes('pre_tool_use_dispatcher.py'));
+    assert.equal(allDispatcherCommands.length, 1, 'dispatcher must appear exactly once after two merges');
+    assert.equal(countManagedRunAllValidatorsHooks(settings), 1, 'run_all_validators must appear exactly once after two merges');
+});
+
+
+test('shipped hooks.json matches the dispatcher design: dispatchers registered, run_all_validators retained, no folded hook standalone', () => {
+    const shippedHooksConfig = JSON.parse(
+        readFileSync(new URL('../hooks/hooks.json', import.meta.url), 'utf8')
+    );
+
+    const allPreToolUseGroups = shippedHooksConfig.hooks.PreToolUse || [];
+    const allPreCommands = allPreToolUseGroups.flatMap(group => group.hooks.map(hook => hook.command));
+    const preDispatcherCommands = allPreCommands.filter(cmd => cmd.includes('pre_tool_use_dispatcher.py'));
+    assert.equal(preDispatcherCommands.length, 1, 'shipped hooks.json must register the PreToolUse dispatcher exactly once');
+
+    assert.equal(
+        countManagedRunAllValidatorsHooks(shippedHooksConfig),
+        1,
+        'shipped hooks.json must retain the inline run_all_validators runner in Write|Edit',
+    );
+
+    const allPostToolUseGroups = shippedHooksConfig.hooks.PostToolUse || [];
+    const postDispatcherCommands = allPostToolUseGroups
+        .flatMap(group => group.hooks.map(hook => hook.command))
+        .filter(cmd => cmd.includes('post_tool_use_dispatcher.py'));
+    assert.equal(postDispatcherCommands.length, 1, 'shipped hooks.json must register the PostToolUse dispatcher exactly once');
+
+    const writePathCommands = allPreToolUseGroups
+        .filter(group => /Write|Edit|MultiEdit/.test(group.matcher || ''))
+        .flatMap(group => group.hooks.map(hook => hook.command));
+    for (const foldedPath of FOLDED_HOOK_RELATIVE_PATHS) {
+        const foldedBasename = foldedPath.split('/').pop();
+        const standaloneFoldedCommands = writePathCommands.filter(
+            cmd => cmd.includes(foldedBasename) && !cmd.includes('pre_tool_use_dispatcher')
+        );
+        assert.equal(
+            standaloneFoldedCommands.length,
+            0,
+            `folded hook ${foldedBasename} must not ship as a standalone write-path PreToolUse entry`,
+        );
+    }
+});
+
+
+const POST_DISPATCHER_HOOKS_CONFIG = {
+    hooks: {
+        PostToolUse: [
+            {
+                matcher: 'Write|Edit',
+                hooks: [
+                    {
+                        type: 'command',
+                        command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/validation/post_tool_use_dispatcher.py',
+                        timeout: 60,
+                    },
+                ],
+            },
+        ],
+    },
+};
+
+const OLD_POST_FOLDED_HOOKS_SETTINGS = {
+    hooks: {
+        PostToolUse: [
+            {
+                matcher: 'Write|Edit',
+                hooks: [
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/validation/mypy_validator.py', timeout: 30 },
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/workflow/auto_formatter.py', timeout: 30 },
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/workflow/doc_gist_auto_publish.py C:/Users/x/.claude', timeout: 60 },
+                ],
+            },
+        ],
+    },
+};
+
+
+test('POST_FOLDED_HOOK_RELATIVE_PATHS contains the three after-write hooks folded into the PostToolUse dispatcher', () => {
+    assert.equal(POST_FOLDED_HOOK_RELATIVE_PATHS.size, 3);
+    assert.ok(POST_FOLDED_HOOK_RELATIVE_PATHS.has('validation/mypy_validator.py'));
+    assert.ok(POST_FOLDED_HOOK_RELATIVE_PATHS.has('workflow/auto_formatter.py'));
+    assert.ok(POST_FOLDED_HOOK_RELATIVE_PATHS.has('workflow/doc_gist_auto_publish.py'));
+});
+
+
+test('managedHookScriptRelativePaths includes the PostToolUse dispatcher and all post-folded hooks so old entries are prunable', () => {
+    const relativePaths = managedHookScriptRelativePaths(POST_DISPATCHER_HOOKS_CONFIG);
+    assert.ok(relativePaths.has('validation/post_tool_use_dispatcher.py'), 'PostToolUse dispatcher must be in managed set');
+    for (const foldedPath of POST_FOLDED_HOOK_RELATIVE_PATHS) {
+        assert.ok(relativePaths.has(foldedPath), `post-folded hook ${foldedPath} must be in managed set`);
+    }
+});
+
+
+test('mergeHooksIntoSettings into the old three PostToolUse entries yields exactly one post_tool_use_dispatcher entry and none of the three', () => {
+    const settings = JSON.parse(JSON.stringify(OLD_POST_FOLDED_HOOKS_SETTINGS));
+    mergeHooksIntoSettings(settings, POST_DISPATCHER_HOOKS_CONFIG, 'C:/Users/x/.claude', 'py -3');
+
+    const writeEditGroup = settings.hooks.PostToolUse.find(group => group.matcher === 'Write|Edit');
+    const allCommands = writeEditGroup.hooks.map(hook => hook.command);
+
+    const dispatcherCommands = allCommands.filter(cmd => cmd.includes('post_tool_use_dispatcher.py'));
+    assert.equal(dispatcherCommands.length, 1, 'exactly one PostToolUse dispatcher entry must be present');
+
+    for (const foldedPath of POST_FOLDED_HOOK_RELATIVE_PATHS) {
+        const foldedBasename = foldedPath.split('/').pop();
+        const foldedCommands = allCommands.filter(cmd => cmd.includes(foldedBasename));
+        assert.equal(foldedCommands.length, 0, `post-folded hook ${foldedBasename} must not appear as a separate entry`);
+    }
+});
+
+
+test('mergeHooksIntoSettings installs the PostToolUse dispatcher cleanly into an empty settings object', () => {
+    const settings = {};
+    mergeHooksIntoSettings(settings, POST_DISPATCHER_HOOKS_CONFIG, 'C:/Users/x/.claude', 'py -3');
+
+    const writeEditGroup = settings.hooks.PostToolUse.find(group => group.matcher === 'Write|Edit');
+    assert.equal(writeEditGroup.hooks.length, 1);
+    assert.equal(
+        writeEditGroup.hooks[0].command,
+        'py -3 C:/Users/x/.claude/hooks/validation/post_tool_use_dispatcher.py',
+    );
+});
+
+
+test('mergeHooksIntoSettings is idempotent for the PostToolUse dispatcher across two installs', () => {
+    const settings = JSON.parse(JSON.stringify(OLD_POST_FOLDED_HOOKS_SETTINGS));
+    mergeHooksIntoSettings(settings, POST_DISPATCHER_HOOKS_CONFIG, 'C:/Users/x/.claude', 'py -3');
+    mergeHooksIntoSettings(settings, POST_DISPATCHER_HOOKS_CONFIG, 'C:/Users/x/.claude', 'py -3');
+
+    const writeEditGroup = settings.hooks.PostToolUse.find(group => group.matcher === 'Write|Edit');
+    const dispatcherCommands = writeEditGroup.hooks.filter(hook => hook.command.includes('post_tool_use_dispatcher.py'));
+    assert.equal(dispatcherCommands.length, 1, 'PostToolUse dispatcher must appear exactly once after two merges');
+    assert.equal(writeEditGroup.hooks.length, 1);
+});
+
+
+const PRE_DISPATCHER_ONLY_HOOKS_CONFIG = {
+    hooks: {
+        PreToolUse: [
+            {
+                matcher: 'Write|Edit|MultiEdit',
+                hooks: [
+                    {
+                        type: 'command',
+                        command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pre_tool_use_dispatcher.py',
+                        timeout: 60,
+                    },
+                ],
+            },
+        ],
+    },
+};
+
+const SETTINGS_WITH_INLINE_RUNNER = {
+    hooks: {
+        PreToolUse: [
+            {
+                matcher: 'Write|Edit',
+                hooks: [
+                    {
+                        type: 'command',
+                        command: "py -3 -c \"import sys; sys.path.insert(0, r'C:/Users/x/.claude/hooks'); from validators.run_all_validators import main; sys.exit(main())\"",
+                        timeout: 15,
+                    },
+                ],
+            },
+            {
+                matcher: 'Write|Edit|MultiEdit',
+                hooks: [
+                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/pre_tool_use_dispatcher.py', timeout: 60 },
+                ],
+            },
+        ],
+    },
+};
+
+
+test('mergeHooksIntoSettings prunes the inline run_all_validators runner when the new shape no longer ships it', () => {
+    const settings = JSON.parse(JSON.stringify(SETTINGS_WITH_INLINE_RUNNER));
+    mergeHooksIntoSettings(settings, PRE_DISPATCHER_ONLY_HOOKS_CONFIG, 'C:/Users/x/.claude', 'py -3');
+
+    assert.equal(countManagedRunAllValidatorsHooks(settings), 0, 'the inline validators runner must be pruned');
+
+    const writeEditGroup = (settings.hooks.PreToolUse || []).find(group => group.matcher === 'Write|Edit');
+    if (writeEditGroup) {
+        const runnerSurvivors = writeEditGroup.hooks.filter(hook => hook.command.includes('run_all_validators'));
+        assert.equal(runnerSurvivors.length, 0);
+    }
+
+    const dispatcherGroup = settings.hooks.PreToolUse.find(group => group.matcher === 'Write|Edit|MultiEdit');
+    const dispatcherCommands = dispatcherGroup.hooks.filter(hook => hook.command.includes('pre_tool_use_dispatcher.py'));
+    assert.equal(dispatcherCommands.length, 1, 'the PreToolUse dispatcher must remain exactly once');
+});

package/hooks/blocking/CLAUDE.md

@@ -26,7 +26,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `code_rules_comments.py` | No new inline comments; no deletion of existing ones |
 | `code_rules_constants_config.py` | Constants must live in `config/`; file-global constant use-count |
 | `code_rules_dead_argparse_argument.py` | Argparse arguments with no references in the same file |
-| `code_rules_dead_config_field.py` | Dataclass config fields with no live references |
+| `code_rules_dead_config_field.py` | `*Config` / `*Selectors` dataclass fields with no live references |
 | `code_rules_dead_dataclass_field.py` | Dataclass fields with no consuming references |
 | `code_rules_dead_module_constant.py` | `UPPER_SNAKE` constants in `*_constants.py` modules with no importers |
 | `code_rules_docstrings.py` | Google-style docstrings; `Args:` section matches signature; fallback-branch coverage |
@@ -59,6 +59,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `block_main_commit.py` | PreToolUse (Bash) | `git commit`/`git push` directly to `main` |
 | `bot_mention_comment_blocker.py` | PreToolUse (Write/Edit) | PR review comments that @-mention a bot |
 | `claude_md_orphan_file_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | Per-directory `CLAUDE.md` table cells naming a bare filename absent from the directory subtree |
+| `code_verifier_spawn_preflight_gate.py` | PreToolUse (Agent) | Spawning the `code-verifier` subagent when the branch has a merge conflict vs its base or a CODE_RULES violation on a working-tree-added line |
 | `convergence_gate_blocker.py` | PreToolUse (Bash) | Convergence workflow actions on a conflicting PR |
 | `destructive_command_blocker.py` | PreToolUse (Bash/PowerShell) | Shell commands with destructive literals (`rm -rf`, `git reset --hard`, etc.) |
 | `es_exe_path_rewriter.py` | PreToolUse | Rewrites paths referencing `.exe` under the Everything search path |
@@ -74,6 +75,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `pr_converge_bugteam_enforcer.py` | PreToolUse | Enforces that bugteam runs in parallel with bugbot in pr-converge loops |
 | `pr_description_enforcer.py` | PreToolUse (Bash) | `gh pr create`/`edit` without a PR-description-writer-authored body |
 | `precommit_code_rules_gate.py` | PreToolUse (Bash) | Staged changes that fail the CODE_RULES gate at commit time |
+| `pytest_testpaths_orphan_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | New `test_*.py` files created under a directory absent from a package's explicit pytest `testpaths` allowlist |
 | `question_to_user_enforcer.py` | Stop | User-directed questions not routed through `AskUserQuestion` |
 | `sensitive_file_protector.py` | PreToolUse (Write/Edit) | Writes to sensitive credential or config files |
 | `session_handoff_blocker.py` | Stop | Responses suggesting a new session mid-task |

package/hooks/blocking/claude_md_orphan_file_blocker.py

@@ -39,6 +39,9 @@ from hooks_constants.claude_md_orphan_file_blocker_constants import (  # noqa: E
     SEPARATOR_CELL_PATTERN,
     TABLE_ROW_PATTERN,
 )
+from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
+    read_hook_input_dictionary_from_stdin,
+)
 
 
 def is_claude_md_file(file_path: str) -> bool:
@@ -588,12 +591,8 @@ def _emit_hook_result(all_hook_data: dict, output_stream: TextIO) -> None:
 
 def main() -> None:
     """Read the PreToolUse payload from stdin and block an orphan-file CLAUDE.md."""
-    try:
-        input_data = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
-
-    if not isinstance(input_data, dict):
+    input_data = read_hook_input_dictionary_from_stdin()
+    if input_data is None:
         sys.exit(0)
 
     tool_name = input_data.get("tool_name", "")