claude-dev-env 1.72.0 → 1.74.0

package/hooks/blocking/write_existing_file_blocker.py

@@ -8,6 +8,13 @@ Exemptions: Jupyter notebooks (.ipynb) and files in ~/.claude/hooks/ (standalone
 import json
 import os
 import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 
 JUPYTER_EXTENSION = ".ipynb"
 HOOKS_DIRECTORY = os.path.normpath(os.path.expanduser("~/.claude/hooks"))
@@ -48,13 +55,21 @@ def main() -> None:
     if not os.path.exists(target_file_path):
         sys.exit(0)
 
+    deny_reason = f"BLOCKED: Write on existing file {target_file_path}. Use Edit tool instead."
     denial = {
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",
             "permissionDecision": "deny",
-            "permissionDecisionReason": f"BLOCKED: Write on existing file {target_file_path}. Use Edit tool instead.",
+            "permissionDecisionReason": deny_reason,
         }
     }
+    log_hook_block(
+        calling_hook_name="write_existing_file_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=deny_reason,
+        tool_name="Write",
+        offending_input_preview=target_file_path,
+    )
     print(json.dumps(denial))
     sys.exit(0)
 

package/hooks/hooks.json

@@ -5,60 +5,10 @@
       {
         "matcher": "Write|Edit",
         "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/write_existing_file_blocker.py",
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/sensitive_file_protector.py",
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/validation/hook_format_validator.py",
-            "timeout": 15
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/code_rules_enforcer.py",
-            "timeout": 30
-          },
           {
             "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
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/tdd_enforcer.py",
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/windows_rmtree_blocker.py",
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/state_description_blocker.py",
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/subprocess_budget_completeness.py",
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/hook_prose_detector_consistency.py",
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/verified_commit_message_accuracy_blocker.py",
-            "timeout": 10
           }
         ]
       },
@@ -67,23 +17,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/workflow_substitution_slot_blocker.py",
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/claude_md_orphan_file_blocker.py",
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/open_questions_in_plans_blocker.py",
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/plain_language_blocker.py",
-            "timeout": 10
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pre_tool_use_dispatcher.py",
+            "timeout": 60
           }
         ]
       },
@@ -199,6 +134,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pr_converge_bugteam_enforcer.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/code_verifier_spawn_preflight_gate.py",
+            "timeout": 30
           }
         ]
       },
@@ -221,6 +161,16 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "SendUserFile",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/send_user_file_open_locally_blocker.py",
+            "timeout": 10
+          }
+        ]
       }
     ],
     "SessionStart": [
@@ -324,18 +274,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/validation/mypy_validator.py",
-            "timeout": 30
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/workflow/auto_formatter.py",
-            "timeout": 30
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/workflow/doc_gist_auto_publish.py ${CLAUDE_PLUGIN_ROOT}",
-            "timeout": 60
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/validation/post_tool_use_dispatcher.py",
+            "timeout": 180
           }
         ]
       },

package/hooks/hooks_constants/CLAUDE.md

@@ -14,13 +14,15 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `claude_md_orphan_file_blocker_constants.py` | Table patterns, file extensions, scan budget, and block-message text for the CLAUDE.md orphan-file blocker |
 | `code_rules_enforcer_constants.py` | File-extension sets, test-path patterns, advisory line thresholds, boolean-name prefixes |
 | `code_rules_path_utils_constants.py` | Path-matching helpers used by the code-rules check modules |
+| `code_verifier_spawn_preflight_gate_constants.py` | Subagent type, merge-tree command flags, timeouts, and deny-message text for the code-verifier spawn pre-flight gate |
 | `convergence_branch_constants.py` | Branch and worktree naming patterns for the convergence gate |
 | `dead_argparse_argument_constants.py` | Patterns for detecting unused argparse arguments |
-| `dead_config_field_constants.py` | Patterns for detecting unused dataclass config fields |
+| `dead_config_field_constants.py` | Patterns for detecting unused `*Config` / `*Selectors` dataclass fields |
 | `dead_dataclass_field_constants.py` | Patterns for detecting unused dataclass fields |
 | `dead_module_constant_constants.py` | Patterns for detecting unexported `UPPER_SNAKE` constants in `*_constants.py` modules |
 | `destructive_command_segment_constants.py` | The list of destructive shell command patterns the blocker matches |
 | `doc_gist_auto_publish_constants.py` | Sentinel marker and URL patterns for the doc-gist auto-publish hook |
+| `docstring_rule_gate_count_blocker_constants.py` | Target rule basename, spelled-out-number lookup, count-clause and `check_*` validator patterns, and block-message text for the docstring-rule gate-count staleness blocker |
 | `duplicate_function_body_constants.py` | Hashing and comparison config for the duplicate-body check |
 | `dynamic_stderr_handler.py` | `DynamicStderrHandler` — a logging handler that resolves `sys.stderr` at emit time (for testability) |
 | `gh_pr_author_swap_constants.py` | Constants for the PR-author swap enforcement hooks |
@@ -31,8 +33,10 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `inline_tuple_string_magic_constants.py` | Patterns for detecting magic strings in inline tuple literals |
 | `md_to_html_blocker_constants.py` | Path exemptions and trigger patterns for the markdown-to-html blocker |
 | `messages.py` | Short user-facing notice strings shown when a Stop hook redirects agent behavior |
+| `multi_edit_reconstruction.py` | `apply_edits()` / `edits_for_tool()` — shared helpers that reconstruct the post-edit content of an Edit or MultiEdit, imported by the blockers that judge post-edit content |
 | `open_questions_in_plans_blocker_constants.py` | Patterns for detecting unresolved open questions in plan documents |
 | `orphan_css_class_constants.py` | Scan radius and selector patterns for the orphan-CSS-class check |
+| `package_inventory_stale_blocker_constants.py` | Inventory document names, production code extensions, backtick token pattern, smallest inventory size, exempt names, scan budget, and block-message text for the package-inventory stale-entry blocker |
 | `path_rewriter_constants.py` | Path rewriting patterns for the Everything-search path rewriter |
 | `plain_language_blocker_constants.py` | The list of heavy words and their everyday replacements |
 | `pr_converge_bugteam_enforcer_constants.py` | State keys and timing config for the bugteam-parallel enforcer |
@@ -41,6 +45,8 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `pre_tool_use_stdin.py` | `read_hook_input_dictionary_from_stdin()` — shared stdin parser for PreToolUse hooks |
 | `precommit_code_rules_gate_constants.py` | Scope argument and exit-code constants for the precommit gate |
 | `project_paths_reader.py` | Loads `~/.claude/project-paths.json` — the per-user project-path registry |
+| `pytest_testpaths_orphan_blocker_constants.py` | Marker filename, section and key names, test-file pattern, search budget, and block-message text for the pytest unregistered-test-directory blocker |
+| `send_user_file_open_locally_blocker_constants.py` | Tool name, proactive status, and the block message for the open-locally attach blocker |
 | `session_env_cleanup_constants.py` | Stale-age threshold and directory names for the session-env cleanup hook |
 | `session_handoff_blocker_constants.py` | Trigger phrases for the session-handoff blocker |
 | `setup_project_paths_constants.py` | Encoding policy, BOM marker, and registry meta-key used across multiple hooks |

package/hooks/hooks_constants/blocking_check_limits.py

@@ -30,8 +30,61 @@ DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT: int = 3
 MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES: int = 3
 DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT: int = 2
 MAX_DOCSTRING_NO_CONSUMER_CLAIM_ISSUES: int = 3
+MAX_DOCSTRING_UNGUARDED_PAYLOAD_CLAIM_ISSUES: int = 3
 MAX_STALE_TEST_NAME_TARGET_ISSUES: int = 3
 STALE_TEST_NAME_MINIMUM_SHARED_TOKEN_COUNT: int = 2
+MAX_MODULE_DOCSTRING_CHECK_ROSTER_ISSUES: int = 5
+MINIMUM_PUBLIC_CHECKS_FOR_MODULE_DOCSTRING_ROSTER: int = 2
+MAX_DOCSTRING_TUPLE_ENUMERATION_ISSUES: int = 5
+MINIMUM_TUPLE_MEMBERS_FOR_DOCSTRING_ENUMERATION: int = 2
+MAX_DOCSTRING_STEP_DISPATCH_ISSUES: int = 5
+MINIMUM_NAMED_LINEAR_STEPS_FOR_DISPATCH_CHECK: int = 2
+MINIMUM_TOKENS_FOR_DISPATCH_CALLEE: int = 2
+MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES: int = 3
+MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES: int = 5
+SINGLE_DICT_KEY_COUNT_FOR_PLURAL_CARDINALITY_DRIFT: int = 1
+ALL_NAMING_CONVENTION_DESCRIPTOR_TOKENS: frozenset[str] = frozenset(
+    {
+        "UPPER_SNAKE_CASE",
+        "SCREAMING_SNAKE_CASE",
+        "UPPER_CASE",
+        "SNAKE_CASE",
+        "CAMEL_CASE",
+        "PASCAL_CASE",
+        "KEBAB_CASE",
+        "TITLE_CASE",
+    }
+)
+ALL_DOCSTRING_NON_CONSTANT_REFERENCE_MARKERS: frozenset[str] = frozenset(
+    {
+        "rule",
+        "rules",
+        "doc",
+        "docs",
+        "document",
+        "file",
+        "env",
+        "environment",
+        "variable",
+        "set",
+        "reads",
+        "read",
+        "per",
+        "follows",
+        "following",
+        "see",
+    }
+)
+ALL_DOCSTRING_FILE_REFERENCE_SUFFIXES: tuple[str, ...] = (
+    ".md",
+    ".py",
+    ".txt",
+    ".json",
+)
+DOCSTRING_REFERENCE_MARKER_WINDOW: int = 2
+ALL_GENERIC_CHECK_NAME_TOKENS: frozenset[str] = frozenset(
+    {"check", "checks", "test", "tests", "in", "for", "and", "the"}
+)
 
 ALL_DOCSTRING_NO_CONSUMER_CLAIM_PHRASES: tuple[str, ...] = (
     "no consumer reads",
@@ -44,6 +97,27 @@ ALL_DOCSTRING_NO_CONSUMER_CLAIM_PHRASES: tuple[str, ...] = (
     "not yet read by any consumer",
 )
 
+ALL_DOCSTRING_GUARDED_FAILURE_CLAIM_PHRASES: tuple[str, ...] = (
+    "malformed payload resolves to none",
+    "malformed payload returns none",
+    "malformed response resolves to none",
+    "malformed response returns none",
+    "bad payload resolves to none",
+    "invalid payload resolves to none",
+    "malformed payload yields none",
+)
+
+MAX_DOCSTRING_INLINE_LITERAL_CLAIM_ISSUES: int = 3
+ALL_DOCSTRING_NO_INLINE_LITERAL_CLAIM_PHRASES: tuple[str, ...] = (
+    "no literals appear inline",
+    "no literal appears inline",
+    "no literals inline",
+    "no inline literals",
+    "no string literals appear inline",
+    "without any inline literals",
+    "no hardcoded literals remain",
+)
+
 ALL_DOCSTRING_EXCLUSIVE_SCOPE_PHRASES: tuple[str, ...] = (
     "only when",
     "only if",

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -17,6 +17,10 @@ ALL_JAVASCRIPT_EXTENSIONS = {".js", ".ts", ".tsx", ".jsx"}
 ALL_CODE_EXTENSIONS = ALL_PYTHON_EXTENSIONS | ALL_JAVASCRIPT_EXTENSIONS
 
 ALL_TEST_PATH_PATTERNS = {"test_", "_test.", ".test.", ".spec.", "/tests/", "\\tests\\", "/tests.py", "\\tests.py"}
+STRICT_TEST_FILE_BASENAME_PATTERN: re.Pattern[str] = re.compile(
+    r"^(test_.*|.*_test|.*\.test|.*\.spec)\.[^.]+$|^conftest\.py$"
+)
+ALL_STRICT_TEST_DIRECTORY_SEGMENTS: tuple[str, ...] = ("/tests/",)
 ALL_ROOT_ANCHORED_EPHEMERAL_DIRECTORIES: tuple[str, str] = ("/tmp", "/temp")
 CLAUDE_JOB_DIR_ENVIRONMENT_VARIABLE_NAME: str = "CLAUDE_JOB_DIR"
 CLAUDE_JOB_DIR_SCRATCH_SUBDIRECTORY: str = "tmp"
@@ -38,6 +42,11 @@ UPPER_SNAKE_CONSTANT_PATTERN = re.compile(r"^[A-Z][A-Z0-9_]*$")
 ALL_MUST_CHECK_RETURN_FUNCTION_NAMES: frozenset[str] = frozenset({"find_and_click", "write_outcome"})
 
 DOCSTRING_ARG_ENTRY_PATTERN: re.Pattern[str] = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)\s*[:(]")
+DOCSTRING_PLURAL_FAMILY_STOP_PATTERN: re.Pattern[str] = re.compile(
+    r"\bthe\s+([a-z][a-z]+)\s+stops\b"
+)
+INLINE_CODE_TOKEN_PATTERN: re.Pattern[str] = re.compile(r"``?(\.?[A-Za-z_][A-Za-z0-9_.]*)``?")
+IDENTIFIER_SHAPED_TUPLE_MEMBER_PATTERN: re.Pattern[str] = re.compile(r"^\.?[A-Za-z_][A-Za-z0-9_]*$")
 ALL_DOCSTRING_ARGS_SECTION_HEADERS: tuple[str, ...] = ("Args:", "Arguments:")
 ALL_DOCSTRING_TERMINATING_SECTION_HEADERS: frozenset[str] = frozenset({
     "Returns:",

package/hooks/hooks_constants/code_verifier_spawn_preflight_gate_constants.py

@@ -0,0 +1,45 @@
+"""Configuration constants for the code_verifier_spawn_preflight_gate hook.
+
+The gate denies an ``Agent`` spawn whose ``subagent_type`` is ``code-verifier``
+when the branch carries a merge conflict against its base ref or a CODE_RULES
+violation on a line added in the uncommitted working tree. It runs two
+pre-flight checks before the expensive verification spawn and addresses its
+deny reason to the spawning agent so that agent fixes the named issues and
+re-spawns. Every literal the hook body reads lives here; the hook imports
+``AGENT_TOOL_NAME`` from ``pr_converge_bugteam_enforcer_constants`` rather than
+redefining it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+CODE_VERIFIER_SUBAGENT_TYPE: str = "code-verifier"
+
+ALL_MERGE_TREE_COMMAND_FLAGS: tuple[str, ...] = (
+    "merge-tree",
+    "--write-tree",
+    "--name-only",
+)
+MERGE_TREE_CONFLICT_EXIT_CODE: int = 1
+MERGE_TREE_CLEAN_EXIT_CODE: int = 0
+MERGE_TREE_TIMEOUT_SECONDS: int = 30
+
+ALL_NAME_ONLY_WORKTREE_DIFF_FLAGS: tuple[str, ...] = (
+    "-c",
+    "core.quotePath=false",
+    "diff",
+    "--name-only",
+    "--no-renames",
+)
+ALL_UNIFIED_ZERO_DIFF_FLAGS: tuple[str, ...] = ("diff", "--unified=0")
+
+DENY_REASON_LEAD: str = (
+    "BLOCKED [code-verifier-spawn-preflight]: an Agent spawn with subagent_type "
+    "code-verifier is blocked because the branch is not in a committable state. "
+    "Fix these, then re-spawn the code-verifier:"
+)
+MERGE_CONFLICT_SECTION_HEADER: str = "Merge conflicts vs {base_ref}:"
+CODE_RULES_SECTION_HEADER: str = "CODE_RULES violations on changed lines:"
+
+GATE_SCRIPTS_RELATIVE_PATH: Path = Path("_shared") / "pr-loop" / "scripts"

package/hooks/hooks_constants/dead_config_field_constants.py

@@ -16,18 +16,18 @@ from hooks_constants.dead_module_constant_constants import (
     PYTHON_SOURCE_SUFFIX,
 )
 
-CONFIG_CLASS_NAME_SUFFIX: str = "Config"
+ALL_CONFIG_CLASS_NAME_SUFFIXES: tuple[str, ...] = ("Config", "Selectors")
 DATACLASSES_MODULE_NAME: str = "dataclasses"
 MAX_DEAD_CONFIG_FIELD_ISSUES: int = 25
 DEAD_CONFIG_FIELD_GUIDANCE: str = (
-    "config dataclass field is defined but read by no production module in the"
-    " enclosing package tree - remove the dead field, or read it where the value"
-    " is needed (CODE_RULES §9.8)"
+    "config or selectors dataclass field is defined but read by no production"
+    " module in the enclosing package tree - remove the dead field, or read it"
+    " where the value is needed (CODE_RULES §9.8)"
 )
 
 __all__ = [
+    "ALL_CONFIG_CLASS_NAME_SUFFIXES",
     "ALL_REFLECTIVE_FIELD_CONSUMER_NAMES",
-    "CONFIG_CLASS_NAME_SUFFIX",
     "CONFIG_DIRECTORY_SEGMENT",
     "DATACLASSES_MODULE_NAME",
     "DEAD_CONFIG_FIELD_GUIDANCE",

package/hooks/hooks_constants/docstring_rule_gate_count_blocker_constants.py

@@ -0,0 +1,90 @@
+"""Constants for the docstring-rule gate-count staleness blocker.
+
+The rule file ``docstring-prose-matches-implementation.md`` enumerates the
+``check_docstring_*`` gate validators that cover deterministic slices of docstring
+prose, both as a spelled-out count ("Three more gate validators", "four gated
+slices") and as a backticked list of the validator names. When a new gate
+validator is registered but the count word is left unchanged, the rule's stated
+count drifts from the validators it actually names — the same companion-doc drift
+the rule itself governs. This module holds the target rule basename, the
+spelled-out-number lookup, the code-fence pattern that marks lines to skip, the
+patterns that find the "<count> more gate validators" and "<count> gated slices"
+count clauses and the backticked ``check_*`` validator names, the args-gate name,
+the issue budget, and the block-message text the hook emits.
+"""
+
+import re
+
+__all__ = [
+    "TARGET_RULE_BASENAME",
+    "ALL_NUMBER_WORDS_BY_VALUE",
+    "CODE_FENCE_PATTERN",
+    "FREE_FORM_GATE_COUNT_PATTERN",
+    "TOTAL_GATED_SLICE_COUNT_PATTERN",
+    "GATE_VALIDATOR_NAME_PATTERN",
+    "ARGS_GATE_VALIDATOR_NAME",
+    "MAX_GATE_COUNT_ISSUES",
+    "GATE_COUNT_MESSAGE_TEMPLATE",
+    "GATE_COUNT_SYSTEM_MESSAGE",
+    "GATE_COUNT_ADDITIONAL_CONTEXT",
+]
+
+TARGET_RULE_BASENAME: str = "docstring-prose-matches-implementation.md"
+
+ALL_NUMBER_WORDS_BY_VALUE: dict[str, int] = {
+    "zero": 0,
+    "one": 1,
+    "two": 2,
+    "three": 3,
+    "four": 4,
+    "five": 5,
+    "six": 6,
+    "seven": 7,
+    "eight": 8,
+    "nine": 9,
+    "ten": 10,
+}
+
+CODE_FENCE_PATTERN: re.Pattern[str] = re.compile(r"^\s*(?:```|~~~)")
+
+FREE_FORM_GATE_COUNT_PATTERN: re.Pattern[str] = re.compile(
+    r"\b([A-Za-z]+)\s+more\s+gate\s+validators\b",
+    re.IGNORECASE,
+)
+
+TOTAL_GATED_SLICE_COUNT_PATTERN: re.Pattern[str] = re.compile(
+    r"\b([A-Za-z]+)\s+gated\s+slices\b",
+    re.IGNORECASE,
+)
+
+GATE_VALIDATOR_NAME_PATTERN: re.Pattern[str] = re.compile(r"`(check_[A-Za-z0-9_]+)`")
+
+ARGS_GATE_VALIDATOR_NAME: str = "check_docstring_args_match_signature"
+
+MAX_GATE_COUNT_ISSUES: int = 4
+
+GATE_COUNT_MESSAGE_TEMPLATE: str = (
+    "{rule_basename} states '{stated_phrase}' ({stated_count}) but names "
+    "{named_count} distinct free-form gate validator(s) ({named_validators}). The "
+    "rule's spelled-out gate count drifts from the validators it enumerates — the "
+    "companion-doc-vs-implementation drift this rule governs. Update the count "
+    "word to {named_count} and the '... gated slices' total to {total_count} in "
+    "this same change, and name every gate validator the prose counts."
+)
+
+GATE_COUNT_SYSTEM_MESSAGE: str = (
+    "Gate-validator count in docstring-prose-matches-implementation.md drifted "
+    "from the validators it names - update the count word in this same change"
+)
+
+GATE_COUNT_ADDITIONAL_CONTEXT: str = (
+    "The rule docstring-prose-matches-implementation.md states a spelled-out "
+    "count of free-form docstring gate validators ('Four more gate validators') "
+    "and a total ('five gated slices'), then names each validator in backticks "
+    "(`check_docstring_fallback_branch_coverage`, ...). When a new "
+    "`check_docstring_*` gate is added, name it in the prose and bump both count "
+    "words: the 'N more gate validators' count equals the number of distinct "
+    "free-form validators named after it, and the 'M gated slices' total equals "
+    "that count plus one for check_docstring_args_match_signature. Keep the count "
+    "words and the named-validator list in step in the same change."
+)

package/hooks/hooks_constants/hook_block_logger.py

@@ -0,0 +1,59 @@
+"""Shared fail-safe logger for hook block events.
+
+Every blocking hook calls log_hook_block at the moment it decides to block,
+so the user has a single log showing what tripped and why.
+"""
+
+import datetime
+import json
+from pathlib import Path
+
+_HOOK_BLOCKS_LOG_RELATIVE_PATH = ".claude/logs/hook-blocks.log"
+_MAX_PREVIEW_LENGTH = 500
+
+
+def log_hook_block(
+    calling_hook_name: str,
+    hook_event: str,
+    block_reason: str,
+    tool_name: str | None = None,
+    offending_input_preview: str | None = None,
+) -> None:
+    """Append one JSON record to the hook-blocks log for a block decision.
+
+    Creates the logs directory if absent. Skips logging when the home directory
+    cannot be resolved, and silently swallows all IO errors otherwise, so a
+    logging failure never changes a hook's decision.
+
+    Args:
+        calling_hook_name: The script basename of the hook that is blocking.
+        hook_event: The hook event type, e.g. ``PreToolUse`` or ``Stop``.
+        block_reason: The human-readable reason the hook is blocking.
+        tool_name: The Claude tool name when available, e.g. ``Bash``.
+        offending_input_preview: A short excerpt of the input that triggered
+            the block; truncated to 500 characters before writing.
+    """
+    try:
+        home_directory = Path.home()
+    except RuntimeError:
+        return
+
+    try:
+        log_path = home_directory / _HOOK_BLOCKS_LOG_RELATIVE_PATH
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+
+        log_record: dict[str, str] = {
+            "timestamp": datetime.datetime.now().isoformat(),
+            "hook": calling_hook_name,
+            "event": hook_event,
+            "reason": block_reason,
+        }
+        if tool_name is not None:
+            log_record["tool"] = tool_name
+        if offending_input_preview is not None:
+            log_record["preview"] = offending_input_preview[:_MAX_PREVIEW_LENGTH]
+
+        with log_path.open("a", encoding="utf-8") as log_file:
+            log_file.write(json.dumps(log_record) + "\n")
+    except OSError:
+        pass

package/hooks/hooks_constants/multi_edit_reconstruction.py

@@ -0,0 +1,56 @@
+"""Shared helpers that reconstruct the post-edit content of an Edit or MultiEdit.
+
+Several PreToolUse blockers judge the content a write would leave on disk rather
+than the raw payload fragment, so an edit on a line the blocker watches still
+participates even when an untouched line elsewhere supplies the context. Both the
+edit-replacement applier and the edit-list extractor are identical across those
+blockers, so they live here once and are imported from each.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "apply_edits",
+    "edits_for_tool",
+]
+
+
+def apply_edits(existing_content: str, all_edits: list[dict]) -> str:
+    """Return *existing_content* with each Edit/MultiEdit replacement applied in order.
+
+    Args:
+        existing_content: The current on-disk file content.
+        all_edits: The Edit payload (as a single-element list) or MultiEdit
+            ``edits`` list, each a mapping with an ``old_string`` and a
+            ``new_string``.
+
+    Returns:
+        The content after replacing the first occurrence of each edit's
+        ``old_string`` with its ``new_string``, in list order.
+    """
+    edited_content = existing_content
+    for each_edit in all_edits:
+        if not isinstance(each_edit, dict):
+            continue
+        old_string = each_edit.get("old_string", "")
+        new_string = each_edit.get("new_string", "")
+        if isinstance(old_string, str) and isinstance(new_string, str) and old_string:
+            edited_content = edited_content.replace(old_string, new_string, 1)
+    return edited_content
+
+
+def edits_for_tool(tool_name: str, tool_input: dict) -> list[dict]:
+    """Return the edit mappings an Edit or MultiEdit payload carries.
+
+    Args:
+        tool_name: The intercepted tool — ``Edit`` or ``MultiEdit``.
+        tool_input: The tool's input payload.
+
+    Returns:
+        A single-element list holding the Edit payload, or the MultiEdit
+        ``edits`` list when it is present as a list; an empty list otherwise.
+    """
+    if tool_name == "Edit":
+        return [tool_input]
+    all_edits = tool_input.get("edits", [])
+    return all_edits if isinstance(all_edits, list) else []

package/hooks/hooks_constants/mypy_validator_cache_constants.py

@@ -0,0 +1,36 @@
+"""Cache paths and tunables for the mypy_validator per-session caches.
+
+The validator keeps two per-session caches so a Write/Edit burst under one
+project root does not repeat work whose result has not changed: a config-walk
+cache keyed by the target file's directory, and a content-hash cache keyed by
+target file.
+Both live as JSON files under the per-session hook-state cache directory the
+live tree already uses for hook state. A cold or missing cache simply does the
+work, so these paths are safe to miss.
+"""
+
+from __future__ import annotations
+
+import os
+
+__all__ = [
+    "HOOK_STATE_CACHE_DIRECTORY",
+    "MYPY_CONFIG_CACHE_FILENAME",
+    "MYPY_CONTENT_HASH_CACHE_FILENAME",
+    "SESSION_ID_ENVIRONMENT_VARIABLE",
+    "UNKNOWN_SESSION_IDENTIFIER",
+    "CONTENT_HASH_CACHE_PASSING_EXIT_CODE",
+    "CACHE_FILE_ENCODING",
+]
+
+HOOK_STATE_CACHE_DIRECTORY = os.path.join(os.path.expanduser("~"), ".claude", "cache")
+
+MYPY_CONFIG_CACHE_FILENAME = "mypy-validator-config-cache.json"
+MYPY_CONTENT_HASH_CACHE_FILENAME = "mypy-validator-content-hash-cache.json"
+
+SESSION_ID_ENVIRONMENT_VARIABLE = "CLAUDE_CODE_SESSION_ID"
+UNKNOWN_SESSION_IDENTIFIER = "unknown-session"
+
+CONTENT_HASH_CACHE_PASSING_EXIT_CODE = 0
+
+CACHE_FILE_ENCODING = "utf-8"