claude-dev-env 1.71.0 → 1.73.0

package/CLAUDE.md

@@ -27,6 +27,14 @@ When making code changes, make sure you are working in the proper worktree path
 
 `Edit` changes existing files; `Write` creates new ones. Default to `Edit` — reach for `Write` only for a genuinely new path. For a true full rewrite, delete the file first, then `Write`.
 
+## Showing Files: Open Them, Don't Print the Path
+
+When I ask you to "show me", "open", "display", "let me see", or "pull up" a file — an image, PDF, HTML page, document, anything — open it on my screen. Launch the viewer so each image window matches the asset's size:
+
+`Start-Process pwsh -WindowStyle Hidden -ArgumentList '-NoProfile','-File',"$HOME\.claude\scripts\Show-Asset.ps1",'<path 1>','<path 2>'`
+
+It sizes each image window to the image (scaled down to fit the screen) and opens non-image files in their default app; pass every path I name. Printing a path or attaching the file is not showing it — do that only when the file truly cannot be opened, and say why.
+
 ## Test Philosophy
 
 When writing tests, always write tests that actually test the behavior of the function against actual, real data and environments.

package/_shared/pr-loop/scripts/code_rules_gate.py

@@ -594,11 +594,11 @@ def check_wrapper_plumb_through(content: str, file_path: str) -> list[str]:
     Args:
         content: File content as a single string for AST parsing.
         file_path: Repository-relative POSIX path of the file (used to
-            skip non-Python code extensions early).
+            skip non-Python code extensions and test files early).
 
     Returns:
-        List of violation strings, one per dropped optional kwarg. Returns
-        an empty list when the file is not Python or has a syntax error.
+        List of violation strings, one per dropped optional kwarg. Empty for
+        a non-Python file, a test file, or a file with a syntax error.
     """
     non_python_code_extensions = ALL_CODE_FILE_EXTENSIONS - {PYTHON_FILE_EXTENSION}
     lowercase_file_path = file_path.lower()
@@ -607,6 +607,8 @@ def check_wrapper_plumb_through(content: str, file_path: str) -> list[str]:
         for each_extension in non_python_code_extensions
     ):
         return []
+    if is_test_path(file_path):
+        return []
     try:
         tree = ast.parse(content)
     except SyntaxError:

package/_shared/pr-loop/scripts/tests/test_code_rules_gate.py

@@ -430,6 +430,45 @@ def test_check_wrapper_plumb_through_still_flags_attribute_call() -> None:
     )
 
 
+def test_check_wrapper_plumb_through_exempts_test_files() -> None:
+    source = (
+        "def _helper(name, *, clean_name=None):\n"
+        "    return (name, clean_name)\n"
+        "\n"
+        "def test_uses_helper():\n"
+        "    return _helper('a', clean_name='b')\n"
+    )
+    shared_issues = gate_module.check_wrapper_plumb_through(source, "pkg/test_thing.py")
+    bugteam_gate = _load_bugteam_gate_module()
+    bugteam_issues = bugteam_gate.check_wrapper_plumb_through(source, "pkg/test_thing.py")
+    assert shared_issues == [], (
+        "a test_* function in a test-file path that calls a module-level helper "
+        "exposing an optional kwarg is not a wrapper; the shared gate must exempt "
+        "test files and emit zero findings"
+    )
+    assert bugteam_issues == [], (
+        "the bugteam gate copy must apply the identical test-file exemption"
+    )
+
+
+def test_check_wrapper_plumb_through_still_flags_non_test_path_with_test_shape() -> None:
+    source = (
+        "def _helper(name, *, clean_name=None):\n"
+        "    return (name, clean_name)\n"
+        "\n"
+        "def test_uses_helper():\n"
+        "    return _helper('a', clean_name='b')\n"
+    )
+    issues = gate_module.check_wrapper_plumb_through(source, "pkg/module.py")
+    assert any(
+        "test_uses_helper" in each_issue and "clean_name" in each_issue
+        for each_issue in issues
+    ), (
+        "the test-file exemption is scoped to test paths only; the same wrapper "
+        "shape on a non-test path must still be flagged"
+    )
+
+
 def test_split_violations_by_scope_accepts_all_added_line_numbers_param_name() -> None:
     blocking_issues, advisory_issues = gate_module.split_violations_by_scope(
         ["Line 5: violation"],

package/agents/clean-coder.md

@@ -264,6 +264,7 @@ Tests document behavior. The hook layer enforces several constraints on test fil
 - **No decorators named `skip*` on test functions.** Tests fail with a clear error rather than skip when a system dependency is missing. The hook fires on any decorator (whether `@skip_if_missing_dependency`, `@unittest.skipIf`, `@pytest.mark.skip`, or any custom variant) whose identifier contains the substring `skip`.
 - **No existence-only tests.** A test whose entire body is `assert callable(x)`, `assert hasattr(module, "name")`, or `assert obj is not None` covers no behavior. Replace with an assertion that exercises the behavior — call the function and assert on its return value or side effect.
 - **No constant-equality tests.** A test whose sole assertion is `assert CACHE_DIR == "cache"` (or any `UPPER_SNAKE == LITERAL` pattern) just verifies the constant has not changed. Delete it or replace with a behavior assertion.
+- **No stale test names after a rename.** When you rename a function the tests exercise, rename the test functions in the same edit. The `check_stale_test_name_target` hook fires on a `test_*` name that embeds a snake_case run the file never imports, defines, or calls while the body calls a same-shape sibling — the signature of a producer rename that updated the bodies but left the test identifiers naming the deleted function.
 - **No tautological assertions.** `assert CONSTANT == CONSTANT` and `assert hasattr(module, "name")` pass regardless of the implementation. Replace with assertions that would fail if the implementation regressed.
 - **Test through the public API.** Do not assert on private state, hook return values, internal class fields, `_protected_field`, `__private_field`, or `component.state.X`. If the test needs visibility the public API does not provide, the public API needs a method, not the test.
 - **For React components**, query in this priority order: `getByRole > getByLabelText > getByText > getByTestId`. Use `userEvent` over `fireEvent` (more realistic). Mock at API boundaries (network calls, external services), not internal hooks or utilities.

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/docs/CODE_RULES.md

@@ -23,7 +23,7 @@ Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.p
 
 `code_rules_enforcer.py` blocks each of these at Write/Edit and explains the specific violation when it fires; exact patterns and exemption lists live in the hook:
 
-no new comments · imports at top · logging format args (`log_*("...", arg)`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`, `/migrations/`, workflow registries `/workflow/` + `_tab.py` + `/states.py` + `/modules.py`, test files) · no hardcoded user home paths · guarded `sys.path.insert` · no unused module-level imports · banned identifiers (`ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`) · banned function prefixes (`handle_`, `process_`, `manage_`, `do_`) · no type escape hatches (`Any` import, `cast()`, inline `Any`) outside boundary files · no bare/broad `except` · no `Any` in signatures or class attributes · no stub bodies (`pass`/`...`/`raise NotImplementedError`) outside abstract/Protocol · TypedDict `_encode_*`/`_decode_*` companions in the same module · no test-mode branching in production (use dependency injection) · no thin wrapper modules · Google-style docstrings on public functions with `Args:` matching the signature · boolean names prefixed `is_`/`has_`/`should_`/`can_`/`was_`/`did_` (assignments AND bool-typed parameters) · must-check returns (`find_and_click`, `write_outcome`) assigned and checked · known pytest fixture parameters in test files annotated with their single documented type (`tmp_path: Path`, `monkeypatch: pytest.MonkeyPatch`, `capsys`, `caplog`, `request`, …) · known pytest fixture parameters a test function declares but never references (drop the unused parameter — pytest still pays its setup cost)
+no new comments · imports at top · logging format args (`log_*("...", arg)`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`, `/migrations/`, workflow registries `/workflow/` + `_tab.py` + `/states.py` + `/modules.py`, test files) · no hardcoded user home paths · guarded `sys.path.insert` · no unused module-level imports · banned identifiers (`ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`) · banned function prefixes (`handle_`, `process_`, `manage_`, `do_`) · no type escape hatches (`Any` import, `cast()`, inline `Any`, a parameter typed bare `object` whose body reads `param.attribute`) outside boundary files · no bare/broad `except` · no `Any` in signatures or class attributes · no stub bodies (`pass`/`...`/`raise NotImplementedError`) outside abstract/Protocol · TypedDict `_encode_*`/`_decode_*` companions in the same module · no test-mode branching in production (use dependency injection) · no thin wrapper modules · Google-style docstrings on public functions with `Args:` matching the signature · boolean names prefixed `is_`/`has_`/`should_`/`can_`/`was_`/`did_` (assignments AND bool-typed parameters) · must-check returns (`find_and_click`, `write_outcome`) assigned and checked · known pytest fixture parameters in test files annotated with their single documented type (`tmp_path: Path`, `monkeypatch: pytest.MonkeyPatch`, `capsys`, `caplog`, `request`, …) · known pytest fixture parameters a test function declares but never references (drop the unused parameter — pytest still pays its setup cost)
 
 Test files are exempt from most checks. The one annotation the test-file exemption does NOT cover is a known pytest builtin fixture parameter: `tmp_path`, `monkeypatch`, `capsys`, `capfd`, `caplog`, `request`, and `tmp_path_factory` each have a single documented injected type, so the gate requires that annotation (`tmp_path: Path`) even inside a test file. The same set of fixtures is also subject to a use check: a pytest-collected test function that declares one of these parameters and never references it in its body fails the gate, because pytest materializes the fixture's setup (the temp directory, the monkeypatch context, the output capture) on every run whether or not the body reads the value — drop the unused parameter. A parameter counts as referenced when its name is read, augmented-assigned, or deleted anywhere in the body, including inside a nested function or comprehension. Only pytest-collectable functions are inspected — those at module top level or defined directly in a class body; a function nested inside another function's body is a local helper pytest never collects, so its fixture-named parameter is exempt. A `@pytest.fixture`-decorated function is exempt from the use check, since injecting one fixture into another purely to order its setup is intentional. Ordinary test parameters stay exempt from both checks. See also the file-global constants use-count rule: [`rules/file-global-constants.md`](../rules/file-global-constants.md).