claude-dev-env 1.72.0 → 1.73.0

package/hooks/blocking/test_shared_stdin_adoption.py

@@ -0,0 +1,166 @@
+"""Same-decision tests for hooks converted to the shared stdin parser.
+
+Each converted hook reads its PreToolUse payload through
+``hooks_constants.pre_tool_use_stdin.read_hook_input_dictionary_from_stdin``
+rather than a hand-rolled ``json.load(sys.stdin)`` plus ``isinstance(dict)``
+guard. The shared parser fails open on empty stdin, malformed JSON, and a
+non-object JSON root by returning ``None``; the hand-rolled form these hooks
+carried failed open on the same three cases by exiting zero. These tests drive
+each real hook script through its production ``__main__`` stdin path over a
+corpus that pins those fail-soft edges plus a representative allow payload, so a
+conversion that changes any decision is caught.
+
+The deterministic deny payloads for the two Write/Edit blockers whose triggers
+need no filesystem or state setup (``md_to_html_blocker``,
+``open_questions_in_plans_blocker``) are exercised here too; each remaining
+hook's full deny coverage stays in its own suite, which also drives the real
+``main()`` and so re-proves the decision after the parser swap.
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_BLOCKING_DIRECTORY = Path(__file__).resolve().parent
+
+ALL_CONVERTED_HOOK_FILENAMES = (
+    "md_to_html_blocker.py",
+    "open_questions_in_plans_blocker.py",
+    "claude_md_orphan_file_blocker.py",
+    "pr_converge_bugteam_enforcer.py",
+    "verdict_directory_write_blocker.py",
+)
+
+EMPTY_STDIN_PAYLOAD = ""
+WHITESPACE_STDIN_PAYLOAD = "   \n\t  "
+MALFORMED_JSON_PAYLOAD = "{not valid json"
+NON_OBJECT_JSON_ARRAY_PAYLOAD = "[1, 2, 3]"
+NON_OBJECT_JSON_SCALAR_PAYLOAD = "42"
+
+ALL_FAIL_SOFT_PAYLOADS = (
+    EMPTY_STDIN_PAYLOAD,
+    WHITESPACE_STDIN_PAYLOAD,
+    MALFORMED_JSON_PAYLOAD,
+    NON_OBJECT_JSON_ARRAY_PAYLOAD,
+    NON_OBJECT_JSON_SCALAR_PAYLOAD,
+)
+
+
+def _run_hook_script(hook_filename: str, stdin_text: str) -> subprocess.CompletedProcess:
+    hook_script_path = _BLOCKING_DIRECTORY / hook_filename
+    return subprocess.run(
+        [sys.executable, str(hook_script_path)],
+        input=stdin_text,
+        capture_output=True,
+        text=True,
+        check=False,
+        cwd=str(Path.home()),
+    )
+
+
+def _decision_from_stdout(completed: subprocess.CompletedProcess) -> str | None:
+    if not completed.stdout.strip():
+        return None
+    parsed_output = json.loads(completed.stdout)
+    return parsed_output["hookSpecificOutput"]["permissionDecision"]
+
+
+@pytest.mark.parametrize("hook_filename", ALL_CONVERTED_HOOK_FILENAMES)
+@pytest.mark.parametrize("stdin_text", ALL_FAIL_SOFT_PAYLOADS)
+def test_fail_soft_payload_exits_zero_with_no_decision(hook_filename: str, stdin_text: str) -> None:
+    completed = _run_hook_script(hook_filename, stdin_text)
+    assert completed.returncode == 0, (
+        f"{hook_filename} must exit zero on fail-soft stdin; "
+        f"got code {completed.returncode}, stderr {completed.stderr!r}"
+    )
+    assert _decision_from_stdout(completed) is None, (
+        f"{hook_filename} must emit no decision on fail-soft stdin; got stdout {completed.stdout!r}"
+    )
+
+
+def test_md_to_html_blocker_still_denies_relative_markdown_write() -> None:
+    payload = json.dumps(
+        {
+            "tool_name": "Write",
+            "tool_input": {"file_path": "notes/topic.md", "content": "# Topic"},
+        }
+    )
+    completed = _run_hook_script("md_to_html_blocker.py", payload)
+    assert completed.returncode == 0
+    assert _decision_from_stdout(completed) == "deny"
+
+
+def test_md_to_html_blocker_still_allows_non_markdown_write() -> None:
+    payload = json.dumps(
+        {
+            "tool_name": "Write",
+            "tool_input": {"file_path": "notes/topic.txt", "content": "plain"},
+        }
+    )
+    completed = _run_hook_script("md_to_html_blocker.py", payload)
+    assert completed.returncode == 0
+    assert _decision_from_stdout(completed) is None
+
+
+def test_open_questions_blocker_still_denies_plan_with_open_questions(
+    tmp_path: Path,
+) -> None:
+    plan_directory = tmp_path / "docs" / "plans"
+    plan_directory.mkdir(parents=True)
+    plan_path = plan_directory / "feature.md"
+    plan_body = "# Feature Plan\n\n## Open Questions\n\n- What endpoint do we call?\n"
+    payload = json.dumps(
+        {
+            "tool_name": "Write",
+            "tool_input": {"file_path": str(plan_path), "content": plan_body},
+        }
+    )
+    completed = _run_hook_script("open_questions_in_plans_blocker.py", payload)
+    assert completed.returncode == 0
+    assert _decision_from_stdout(completed) == "deny"
+
+
+def test_open_questions_blocker_still_allows_plan_without_open_questions(
+    tmp_path: Path,
+) -> None:
+    plan_directory = tmp_path / "docs" / "plans"
+    plan_directory.mkdir(parents=True)
+    plan_path = plan_directory / "feature.md"
+    plan_body = "# Feature Plan\n\n## Approach\n\nBuild the thing.\n"
+    payload = json.dumps(
+        {
+            "tool_name": "Write",
+            "tool_input": {"file_path": str(plan_path), "content": plan_body},
+        }
+    )
+    completed = _run_hook_script("open_questions_in_plans_blocker.py", payload)
+    assert completed.returncode == 0
+    assert _decision_from_stdout(completed) is None
+
+
+def test_converted_hooks_allow_unrelated_tool_name() -> None:
+    payload = json.dumps({"tool_name": "Bash", "tool_input": {"command": "ls"}})
+    for each_hook_filename in ALL_CONVERTED_HOOK_FILENAMES:
+        completed = _run_hook_script(each_hook_filename, payload)
+        assert completed.returncode == 0, (
+            f"{each_hook_filename} must exit zero on an unrelated tool; stderr {completed.stderr!r}"
+        )
+
+
+def test_every_converted_hook_imports_shared_parser() -> None:
+    for each_hook_filename in ALL_CONVERTED_HOOK_FILENAMES:
+        hook_source = (_BLOCKING_DIRECTORY / each_hook_filename).read_text(encoding="utf-8")
+        assert "read_hook_input_dictionary_from_stdin" in hook_source, (
+            f"{each_hook_filename} must read stdin through the shared parser"
+        )
+        assert "json.load(sys.stdin)" not in hook_source, (
+            f"{each_hook_filename} must not hand-roll json.load(sys.stdin)"
+        )
+
+
+def test_blocking_directory_is_resolvable() -> None:
+    assert os.path.isdir(_BLOCKING_DIRECTORY)

package/hooks/blocking/verdict_directory_write_blocker.py

@@ -37,7 +37,11 @@ blocking_directory = str(Path(__file__).resolve().parent)
 if blocking_directory not in sys.path:
     sys.path.insert(0, blocking_directory)
 
-from config.verified_commit_constants import (
+hooks_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_directory not in sys.path:
+    sys.path.insert(0, hooks_directory)
+
+from config.verified_commit_constants import (  # noqa: E402
     ALL_GATED_TOOL_NAMES,
     ALL_VERDICT_PATH_SEGMENT_BODIES,
     ALL_VERDICT_PATH_SEGMENT_NAMES,
@@ -61,11 +65,11 @@ from config.verified_commit_constants import (
     NON_REDIRECT_FILE_WRITE_PRIMITIVE_PATTERN,
     PATH_OBFUSCATION_PRIMITIVE_PATTERN,
     RELATIVE_VERDICT_DIRECTORY_PATTERN,
+    VERDICT_DIRECTORY_CHANGE_TARGET_PATTERN,
     VERDICT_DIRECTORY_GUARD_MESSAGE,
     VERDICT_DIRECTORY_NAME,
     VERDICT_DIRECTORY_NAME_SEPARATOR_PATTERN,
     VERDICT_DIRECTORY_PATH_BOUNDARY_PATTERN,
-    VERDICT_DIRECTORY_CHANGE_TARGET_PATTERN,
     VERDICT_DIRECTORY_TARGET_BOUNDARY_PATTERN,
     VERDICT_FILE_RELATIVE_REFERENCE_PATTERN,
     VERDICT_PATH_GLUE_PATTERN,
@@ -74,6 +78,10 @@ from config.verified_commit_constants import (
     WRITE_CALL_REGION_PATTERN,
 )
 
+from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
+    read_hook_input_dictionary_from_stdin,
+)
+
 
 def _directory_change_verbs_pattern() -> str:
     """Build the alternation of directory-change verbs for a change matcher.
@@ -650,11 +658,8 @@ def decision_for_payload(pretooluse_payload: dict) -> dict | None:
 
 def main() -> None:
     """Read the PreToolUse payload and deny verdict-directory shell access."""
-    try:
-        pretooluse_payload = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        return
-    if not isinstance(pretooluse_payload, dict):
+    pretooluse_payload = read_hook_input_dictionary_from_stdin()
+    if pretooluse_payload is None:
         return
     deny_decision = decision_for_payload(pretooluse_payload)
     if deny_decision is None:

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
           }
         ]
       },
@@ -324,18 +264,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,9 +14,10 @@ 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 |
@@ -41,6 +42,7 @@ 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 |
 | `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

@@ -32,6 +32,56 @@ DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT: int = 2
 MAX_DOCSTRING_NO_CONSUMER_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
+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 +94,17 @@ ALL_DOCSTRING_NO_CONSUMER_CLAIM_PHRASES: tuple[str, ...] = (
     "not yet read by any consumer",
 )
 
+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,8 @@ 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*[:(]")
+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/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"

package/hooks/hooks_constants/post_tool_use_dispatcher_constants.py

@@ -0,0 +1,69 @@
+"""Constants for the PostToolUse dispatcher that hosts the after-write hooks.
+
+Holds the ordered hosted-hook list with each hook's extra command-line
+arguments and blocking flag, the PostToolUse block-decision string and key,
+and the hook-event name. The dispatcher imports these; no literals appear
+inline in the dispatcher script.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+__all__ = [
+    "BLOCK_DECISION",
+    "DECISION_KEY",
+    "REASON_KEY",
+    "HOOK_EVENT_NAME",
+    "EMPTY_REASON_BLOCK_FALLBACK",
+    "PLUGIN_ROOT_PLACEHOLDER",
+    "PostHostedHookEntry",
+    "ALL_POST_HOSTED_HOOK_ENTRIES",
+]
+
+BLOCK_DECISION = "block"
+DECISION_KEY = "decision"
+REASON_KEY = "reason"
+HOOK_EVENT_NAME = "PostToolUse"
+EMPTY_REASON_BLOCK_FALLBACK = "[dispatcher] hook blocked with no reason — write blocked"
+
+PLUGIN_ROOT_PLACEHOLDER = "${CLAUDE_PLUGIN_ROOT}"
+
+
+@dataclass(frozen=True)
+class PostHostedHookEntry:
+    """A single hosted PostToolUse hook with its run-time arguments and flags.
+
+    Attributes:
+        script_relative_path: Hook path relative to the hooks/ directory.
+        extra_argument_relative_paths: Command-line arguments the live entry
+            passes after the script path, each a path relative to the plugin
+            root (the hooks/ parent). The dispatcher resolves each to an
+            absolute path and exposes them as the hook's argv tail, so a hook
+            that reads sys.argv[1] resolves the same path the live entry gives
+            it. An empty tuple means the live entry passes no extra arguments.
+        is_blocking: True when this hook can emit a block decision and a crash
+            should surface a blocking signal; False when the hook only performs
+            a side effect and never blocks.
+    """
+
+    script_relative_path: str
+    extra_argument_relative_paths: tuple[str, ...] = field(default_factory=tuple)
+    is_blocking: bool = field(default=False)
+
+
+ALL_POST_HOSTED_HOOK_ENTRIES: tuple[PostHostedHookEntry, ...] = (
+    PostHostedHookEntry(
+        script_relative_path="validation/mypy_validator.py",
+        is_blocking=True,
+    ),
+    PostHostedHookEntry(
+        script_relative_path="workflow/auto_formatter.py",
+        is_blocking=False,
+    ),
+    PostHostedHookEntry(
+        script_relative_path="workflow/doc_gist_auto_publish.py",
+        extra_argument_relative_paths=(PLUGIN_ROOT_PLACEHOLDER,),
+        is_blocking=False,
+    ),
+)