claude-dev-env 2.12.0 → 2.14.0

package/hooks/git-hooks/test_pre_push.py

@@ -17,8 +17,6 @@ SCRIPT_DIRECTORY = Path(__file__).resolve().parent
 REAL_RUN_GIT_TEXT_COMMAND = pre_push.run_git_text_command
 
 
-CODE_REVIEW_ENFORCEMENT_ENV_VAR: str = "CLAUDE_CODE_REVIEW_ENFORCEMENT"
-ENFORCEMENT_CONSTANTS_MODULE_NAME: str = "config.code_review_enforcement_constants"
 ALL_ZEROS_OBJECT_NAME: str = "0" * 40
 NON_ZERO_LOCAL_SHA: str = "a" * 40
 NON_ZERO_REMOTE_SHA_ONE: str = "1" * 40
@@ -111,7 +109,6 @@ def _write_gate_that_allows_every_push(
     passing_gate_path = tmp_path / "code_rules_gate.py"
     passing_gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
     monkeypatch.setenv("CODE_RULES_GATE_PATH", str(passing_gate_path))
-    _isolate_code_review_gate(tmp_path, monkeypatch)
     monkeypatch.setattr(sys, "stdin", io.StringIO(NEW_BRANCH_PUSH_STDIN))
 
 
@@ -159,11 +156,10 @@ def test_run_git_reference_query_returns_replaced_text_on_locale_invalid_bytes(
     assert resolved_output == expected_replaced_reference
 
 
-def test_unresolvable_merge_base_message_does_not_claim_dangling_origin_head() -> None:
+def test_unresolvable_merge_base_message_describes_pending_validation() -> None:
     skip_message = git_hooks_constants.UNRESOLVABLE_MERGE_BASE_MESSAGE
-    assert "origin/HEAD names a ref" not in skip_message
-    assert "unrelated histories" in skip_message
-    assert "merge-base still could not name a shared commit" in skip_message
+    assert "CODE_RULES validation is pending" in skip_message
+    assert "Restore shared history" in skip_message
 
 
 def test_run_git_text_command_raises_when_git_cannot_launch(
@@ -242,14 +238,14 @@ def resolve_remote_head_reference(monkeypatch: pytest.MonkeyPatch) -> None:
         return GIT_RESOLVED_EXIT_CODE, RESOLVED_COMMIT_OBJECT_NAME
 
     monkeypatch.setattr(pre_push, "run_git_text_command", fake_run_git_text_command)
-
-
-def _isolate_code_review_gate(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.setenv(
-        "CODE_REVIEW_PUSH_GATE_PATH", str(tmp_path / "no_code_review_gate.py")
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        [HOOK_INVOCATION_NAME, git_hooks_constants.DEFAULT_REMOTE_NAME, PUSHED_REMOTE_URL],
     )
 
 
+
 def test_resolve_base_reference_from_stdin_uses_remote_object_when_non_zero() -> None:
     stdin_text = (
         f"refs/heads/feature {NON_ZERO_LOCAL_SHA} refs/heads/feature {NON_ZERO_REMOTE_SHA_ONE}\n"
@@ -295,7 +291,6 @@ def test_main_exits_zero_when_gate_script_missing(
         "CODE_RULES_GATE_PATH",
         str(tmp_path / "does_not_exist.py"),
     )
-    _isolate_code_review_gate(tmp_path, monkeypatch)
     monkeypatch.setattr(sys, "stdin", io.StringIO(""))
 
     exit_code = pre_push.main()
@@ -317,7 +312,6 @@ def test_main_invokes_gate_with_resolved_base_reference(
         encoding="utf-8",
     )
     monkeypatch.setenv("CODE_RULES_GATE_PATH", str(recording_gate_script_path))
-    _isolate_code_review_gate(tmp_path, monkeypatch)
     _isolate_from_default_branch_refs(tmp_path, monkeypatch)
     remote_sha = "9" * 40
     monkeypatch.setattr(
@@ -345,7 +339,6 @@ def test_main_passes_the_pushed_remote_name_to_base_resolution(
     # No default-branch ref so the gate base is the stdin remote object, not a
     # merge-base skip; usable-base resolution then sees the pushed remote name.
     _isolate_repository_and_write_passing_code_rules_gate(tmp_path, monkeypatch)
-    _isolate_code_review_gate(tmp_path, monkeypatch)
     all_recorded_remote_names: list[str] = []
 
     def recording_resolve_usable_base_reference(
@@ -566,7 +559,6 @@ def test_invoke_gate_uses_resolved_path(
     symlink_gate_path.symlink_to(real_gate_path)
     resolved_path = symlink_gate_path.resolve()
     monkeypatch.setenv("CODE_RULES_GATE_PATH", str(symlink_gate_path))
-    _isolate_code_review_gate(tmp_path, monkeypatch)
     _isolate_from_default_branch_refs(tmp_path, monkeypatch)
     monkeypatch.setattr(sys, "stdin", io.StringIO(
         f"refs/heads/feature {NON_ZERO_LOCAL_SHA} refs/heads/feature {NON_ZERO_REMOTE_SHA_ONE}\n"
@@ -684,7 +676,6 @@ def test_main_allows_main_onto_main_push(
     passing_gate_path = tmp_path / "gate.py"
     passing_gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
     monkeypatch.setenv("CODE_RULES_GATE_PATH", str(passing_gate_path))
-    _isolate_code_review_gate(tmp_path, monkeypatch)
     monkeypatch.setattr(
         sys,
         "stdin",
@@ -698,8 +689,6 @@ def test_main_allows_main_onto_main_push(
     assert exit_code == 0
 
 
-CODE_REVIEW_STUB_BLOCK_REASON: str = "CODE_REVIEW_STUB_BLOCK_REASON"
-
 
 def _write_passing_code_rules_gate(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
@@ -725,83 +714,6 @@ def _isolate_repository_and_write_passing_code_rules_gate(
     _write_passing_code_rules_gate(tmp_path, monkeypatch)
 
 
-def _write_code_review_gate_stub(tmp_path: Path, returned_reason_literal: str) -> Path:
-    stub_gate_path = tmp_path / "code_review_push_gate.py"
-    stub_gate_path.write_text(
-        "def deny_reason_for_directory(target_directory):\n"
-        f"    return {returned_reason_literal}\n",
-        encoding="utf-8",
-    )
-    return stub_gate_path
-
-
-def test_main_blocks_when_code_review_gate_returns_reason(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    _isolate_repository_and_write_passing_code_rules_gate(tmp_path, monkeypatch)
-    stub_gate_path = _write_code_review_gate_stub(
-        tmp_path, repr(CODE_REVIEW_STUB_BLOCK_REASON)
-    )
-    monkeypatch.setenv("CODE_REVIEW_PUSH_GATE_PATH", str(stub_gate_path))
-
-    exit_code = pre_push.main()
-
-    assert exit_code == git_hooks_constants.CODE_REVIEW_STAMP_BLOCK_EXIT_CODE
-    captured = capsys.readouterr()
-    assert CODE_REVIEW_STUB_BLOCK_REASON in captured.err
-
-
-def test_main_allows_when_code_review_gate_returns_none(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    _isolate_repository_and_write_passing_code_rules_gate(tmp_path, monkeypatch)
-    stub_gate_path = _write_code_review_gate_stub(tmp_path, "None")
-    monkeypatch.setenv("CODE_REVIEW_PUSH_GATE_PATH", str(stub_gate_path))
-
-    exit_code = pre_push.main()
-
-    assert exit_code == 0
-
-
-def test_main_code_review_check_fails_open_when_gate_module_absent(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    _isolate_repository_and_write_passing_code_rules_gate(tmp_path, monkeypatch)
-    monkeypatch.setenv(
-        "CODE_REVIEW_PUSH_GATE_PATH", str(tmp_path / "does_not_exist.py")
-    )
-
-    exit_code = pre_push.main()
-
-    assert exit_code == 0
-
-
-def test_main_allows_deletion_push_even_when_code_review_gate_would_block(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    passing_gate_path = tmp_path / "code_rules_gate.py"
-    passing_gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
-    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(passing_gate_path))
-    stub_gate_path = _write_code_review_gate_stub(
-        tmp_path, repr(CODE_REVIEW_STUB_BLOCK_REASON)
-    )
-    monkeypatch.setenv("CODE_REVIEW_PUSH_GATE_PATH", str(stub_gate_path))
-    deletion_stdin = (
-        f"refs/heads/feature {ALL_ZEROS_OBJECT_NAME} "
-        f"refs/heads/feature {ALL_ZEROS_OBJECT_NAME}\n"
-    )
-    monkeypatch.setattr(sys, "stdin", io.StringIO(deletion_stdin))
-
-    exit_code = pre_push.main()
-
-    assert exit_code == 0
-
-
 DEFAULT_BRANCH_NAME: str = "main"
 FEATURE_BRANCH_NAME: str = "feature/example"
 UNPROTECTED_DEFAULT_BRANCH_NAME: str = "develop"
@@ -1086,6 +998,46 @@ def test_resolve_default_branch_reference_reads_the_origin_head_symbolic_referen
     assert pre_push.resolve_default_branch_reference() == ORIGIN_DEFAULT_BRANCH_REFERENCE
 
 
+def test_resolve_default_branch_reference_reads_the_requested_remote_head(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    repository, default_branch_tip, _topic_branch_tip = _build_default_branch_repository(
+        tmp_path
+    )
+    upstream_reference = "refs/remotes/upstream/main"
+    upstream_head_reference = "refs/remotes/upstream/HEAD"
+    _run_fixture_git(repository, "update-ref", upstream_reference, default_branch_tip)
+    _run_fixture_git(
+        repository, "symbolic-ref", upstream_head_reference, upstream_reference
+    )
+    monkeypatch.chdir(repository)
+
+    assert pre_push.resolve_default_branch_reference("upstream") == upstream_reference
+
+
+def test_resolve_default_branch_merge_base_uses_requested_remote_trunk_fallback(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    repository, default_branch_tip, topic_branch_tip = _build_default_branch_repository(
+        tmp_path
+    )
+    upstream_trunk_reference = "refs/remotes/upstream/trunk"
+    _run_fixture_git(
+        repository, "update-ref", upstream_trunk_reference, default_branch_tip
+    )
+    monkeypatch.chdir(repository)
+
+    merge_base_object_name = pre_push.resolve_default_branch_merge_base(
+        FEATURE_BRANCH_NAME,
+        topic_branch_tip,
+        "upstream",
+    )
+
+    assert merge_base_object_name == default_branch_tip
+
+
 def test_resolve_default_branch_reference_returns_none_without_remote_tracking_refs(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
@@ -1267,7 +1219,6 @@ def test_main_allows_the_push_when_origin_head_names_an_absent_reference(
         encoding="utf-8",
     )
     monkeypatch.setenv("CODE_RULES_GATE_PATH", str(recording_gate_script_path))
-    _isolate_code_review_gate(tmp_path, monkeypatch)
     monkeypatch.chdir(repository)
     monkeypatch.setattr(
         sys,
@@ -1291,7 +1242,7 @@ def test_main_allows_the_push_when_origin_head_names_an_absent_reference(
     assert recorded_arguments == ["--base", remote_object_name]
 
 
-def test_main_skips_the_gate_when_no_merge_base_resolves(
+def test_main_keeps_the_gate_pending_when_no_merge_base_resolves(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
     capsys: pytest.CaptureFixture[str],
@@ -1307,7 +1258,6 @@ def test_main_skips_the_gate_when_no_merge_base_resolves(
         encoding="utf-8",
     )
     monkeypatch.setenv("CODE_RULES_GATE_PATH", str(recording_gate_script_path))
-    _isolate_code_review_gate(tmp_path, monkeypatch)
     monkeypatch.chdir(repository)
     monkeypatch.setattr(
         sys,
@@ -1324,13 +1274,73 @@ def test_main_skips_the_gate_when_no_merge_base_resolves(
 
     exit_code = pre_push.main()
 
-    assert exit_code == 0
+    assert exit_code == git_hooks_constants.GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE
     assert not recorded_arguments_path.exists(), (
-        "the gate ran on a base the hook could not verify"
+        "the gate remains pending until the hook verifies a usable base"
     )
     assert git_hooks_constants.UNRESOLVABLE_MERGE_BASE_MESSAGE in capsys.readouterr().err
 
 
+def test_main_uses_the_pushed_remote_when_origin_has_unrelated_history(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    repository, default_branch_tip, topic_branch_tip = _build_default_branch_repository(
+        tmp_path
+    )
+    _run_fixture_git(repository, "checkout", "--orphan", "unrelated-origin")
+    _run_fixture_git(repository, "rm", "-rf", ".")
+    unrelated_origin_tip = _commit_file(repository, "unrelated.txt")
+    _run_fixture_git(repository, "checkout", FEATURE_BRANCH_NAME)
+    _run_fixture_git(
+        repository,
+        "update-ref",
+        ORIGIN_DEFAULT_BRANCH_REFERENCE,
+        unrelated_origin_tip,
+    )
+    _set_origin_head(repository, ORIGIN_DEFAULT_BRANCH_REFERENCE)
+    upstream_reference = "refs/remotes/upstream/main"
+    upstream_head_reference = "refs/remotes/upstream/HEAD"
+    _run_fixture_git(repository, "update-ref", upstream_reference, default_branch_tip)
+    _run_fixture_git(
+        repository, "symbolic-ref", upstream_head_reference, upstream_reference
+    )
+    recorded_arguments_path = tmp_path / "upstream_recorded_arguments.txt"
+    recording_gate_script_path = tmp_path / "upstream_recording_gate.py"
+    recording_gate_script_path.write_text(
+        "import pathlib, sys\n"
+        f'pathlib.Path(r"{recorded_arguments_path}").write_text('
+        "'\\n'.join(sys.argv[1:]), encoding='utf-8')\n"
+        "sys.exit(0)\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(recording_gate_script_path))
+    monkeypatch.chdir(repository)
+    monkeypatch.setattr(
+        sys, "argv", [HOOK_INVOCATION_NAME, PUSHED_REMOTE_NAME, PUSHED_REMOTE_URL]
+    )
+    monkeypatch.setattr(
+        sys,
+        "stdin",
+        io.StringIO(
+            _push_stdin_line(
+                FEATURE_BRANCH_NAME,
+                topic_branch_tip,
+                FEATURE_BRANCH_NAME,
+                NON_ZERO_REMOTE_SHA_ONE,
+            )
+        ),
+    )
+
+    exit_code = pre_push.main()
+
+    assert exit_code == 0
+    assert recorded_arguments_path.read_text(encoding="utf-8").splitlines() == [
+        "--base",
+        default_branch_tip,
+    ]
+
+
 def test_main_allows_default_branch_file_the_rebase_replayed_onto(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
@@ -1342,7 +1352,6 @@ def test_main_allows_default_branch_file_the_rebase_replayed_onto(
     )
     _set_origin_head(repository, ORIGIN_DEFAULT_BRANCH_REFERENCE)
     _write_diff_scoped_gate(tmp_path, monkeypatch)
-    _isolate_code_review_gate(tmp_path, monkeypatch)
     monkeypatch.chdir(repository)
     monkeypatch.setattr(
         sys,
@@ -1370,7 +1379,6 @@ def test_main_blocks_violation_the_branch_itself_adds(
     )
     _set_origin_head(repository, ORIGIN_DEFAULT_BRANCH_REFERENCE)
     _write_diff_scoped_gate(tmp_path, monkeypatch)
-    _isolate_code_review_gate(tmp_path, monkeypatch)
     monkeypatch.chdir(repository)
     monkeypatch.setattr(
         sys,
@@ -1407,7 +1415,6 @@ def test_main_uses_remote_object_when_no_default_branch_reference_resolves(
         encoding="utf-8",
     )
     monkeypatch.setenv("CODE_RULES_GATE_PATH", str(recording_gate_script_path))
-    _isolate_code_review_gate(tmp_path, monkeypatch)
     monkeypatch.chdir(repository)
     monkeypatch.setattr(
         sys,
@@ -1446,7 +1453,6 @@ def test_main_uses_remote_object_when_the_default_branch_is_pushed(
     )
     _set_origin_head(repository, ORIGIN_DEFAULT_BRANCH_REFERENCE)
     _write_diff_scoped_gate(tmp_path, monkeypatch)
-    _isolate_code_review_gate(tmp_path, monkeypatch)
     monkeypatch.chdir(repository)
     monkeypatch.setattr(
         sys,
@@ -1481,7 +1487,6 @@ def test_main_uses_merge_base_when_a_default_named_local_branch_updates_a_topic_
     )
     _set_origin_head(repository, ORIGIN_UNPROTECTED_DEFAULT_BRANCH_REFERENCE)
     _write_diff_scoped_gate(tmp_path, monkeypatch)
-    _isolate_code_review_gate(tmp_path, monkeypatch)
     monkeypatch.chdir(repository)
     monkeypatch.setattr(
         sys,
@@ -1517,7 +1522,6 @@ def test_main_uses_remote_object_when_a_renamed_local_branch_updates_the_default
     )
     _set_origin_head(repository, ORIGIN_UNPROTECTED_DEFAULT_BRANCH_REFERENCE)
     _write_diff_scoped_gate(tmp_path, monkeypatch)
-    _isolate_code_review_gate(tmp_path, monkeypatch)
     monkeypatch.chdir(repository)
     monkeypatch.setattr(
         sys,
@@ -1547,7 +1551,6 @@ def test_main_reads_default_branch_tracking_reference_when_origin_head_is_unset(
         branch_file_name=BRANCH_FILE_NAME,
     )
     _write_diff_scoped_gate(tmp_path, monkeypatch)
-    _isolate_code_review_gate(tmp_path, monkeypatch)
     monkeypatch.chdir(repository)
     monkeypatch.setattr(
         sys,
@@ -1575,7 +1578,6 @@ def test_main_skips_a_deletion_line_to_reach_the_branch_update(
     )
     _set_origin_head(repository, ORIGIN_DEFAULT_BRANCH_REFERENCE)
     _write_diff_scoped_gate(tmp_path, monkeypatch)
-    _isolate_code_review_gate(tmp_path, monkeypatch)
     monkeypatch.chdir(repository)
     deletion_line = (
         f"(delete) {ALL_ZEROS_OBJECT_NAME} refs/heads/retired {NON_ZERO_REMOTE_SHA_ONE}\n"
@@ -1594,31 +1596,3 @@ def test_main_skips_a_deletion_line_to_reach_the_branch_update(
     exit_code = pre_push.main()
 
     assert exit_code == 0
-
-
-def test_main_allows_when_code_review_enforcement_flag_is_off(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    """Native pre-push honors the real gate with enforcement off.
-
-    Points at the production push gate (not a reason stub). The gate resolves
-    its flag when its config module first executes, so this test clears the
-    environment variable and evicts that one module if a sibling suite cached
-    it earlier in the same session. The gate then returns no deny reason and
-    the backstop allows the push.
-    """
-    monkeypatch.delenv(CODE_REVIEW_ENFORCEMENT_ENV_VAR, raising=False)
-    monkeypatch.delitem(sys.modules, ENFORCEMENT_CONSTANTS_MODULE_NAME, raising=False)
-    _isolate_repository_and_write_passing_code_rules_gate(tmp_path, monkeypatch)
-    real_gate_path = (
-        Path(__file__).resolve().parent.parent
-        / "blocking"
-        / "code_review_push_gate.py"
-    )
-    assert real_gate_path.is_file()
-    monkeypatch.setenv("CODE_REVIEW_PUSH_GATE_PATH", str(real_gate_path))
-
-    exit_code = pre_push.main()
-
-    assert exit_code == 0

package/hooks/hooks.json

@@ -42,16 +42,6 @@
           }
         ]
       },
-      {
-        "matcher": "mcp__plugin_github_github__create_pull_request",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/code_review_pr_create_gate.py",
-            "timeout": 20
-          }
-        ]
-      },
       {
         "matcher": "mcp__plugin_github_github__.*",
         "hooks": [
@@ -67,24 +57,9 @@
           }
         ]
       },
-      {
-        "matcher": "Agent",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pr_converge_bugteam_enforcer.py",
-            "timeout": 10
-          }
-        ]
-      },
       {
         "matcher": "Agent|Task",
         "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/code_verifier_spawn_preflight_gate.py",
-            "timeout": 30
-          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/fable_spawn_gate.py",
@@ -102,16 +77,6 @@
           }
         ]
       },
-      {
-        "matcher": "Skill",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/lifecycle/pr_converge_bugteam_skill_tracker.py",
-            "timeout": 10
-          }
-        ]
-      },
       {
         "matcher": "AskUserQuestion",
         "hooks": [

package/hooks/hooks_constants/AGENTS.md

@@ -0,0 +1,104 @@
+# hooks/hooks_constants
+
+Shared constant modules imported by hooks throughout the `hooks/` tree. Each file holds the tunables for one hook or one cross-cutting concern, keeping magic values out of the hook scripts themselves.
+
+## Files
+
+| File | What it holds |
+|---|---|
+| `__init__.py` | Package marker (`# pragma: no-tdd-gate`) |
+| `any_type_config.py` | Config for the `Any`-type escape-hatch check |
+| `ask_user_question_shape.py` | Pure AskUserQuestion lean-block shape analyzer: grades question and option-description prose against shared chat-detail markers and sentence/word caps with no hook I/O |
+| `banned_identifiers_constants.py` | The set of banned short identifiers and banned function-name prefixes |
+| `bash_pre_tool_use_dispatcher_constants.py` | Permission outcomes, tool-name sets, and the ordered hosted-hook roster for the Bash PreToolUse dispatcher (also covers PowerShell-shared gates) |
+| `blocking_check_limits.py` | Max issue counts and preview lengths for blocking hooks |
+| `bot_mention_comment_blocker_constants.py` | Patterns for detecting bot @-mentions in PR comments |
+| `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 |
+| `enter_worktree_prefetch_constants.py` | Tool name, origin-remote ref names, and git-command timeouts for the EnterWorktree origin-prefetch hook |
+| `env_var_table_code_drift_constants.py` | Table patterns, env-var-name and code-file recognizers, scan budget, and block-message text for the env-var-table code-drift blocker |
+| `code_rules_path_utils_constants.py` | Path-matching helpers used by the code-rules check modules |
+| `command_dispatch_constants.py` | Command-word regex, command-key access pattern, tokenization pattern, and anchors for the unanchored command-dispatch meta-gate |
+| `conventional_pr_title_gate_constants.py` | Bash tool name, gh executable basenames and pr create/edit subcommand tokens, title/repo flag names, semantic-title-CI workflow markers, the Conventional Commits type list and title pattern, the semantic-pull-request action `types:` input pattern, and block-message text for the conventional-PR-title gate |
+| `dead_argparse_argument_constants.py` | Patterns for detecting unused argparse arguments |
+| `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 |
+| `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 |
+| `duplicate_rmtree_helper_blocker_constants.py` | Sanctioned Windows-safe rmtree helper names, the definition pattern, and the exempt-path set for the duplicate-rmtree-helper blocker |
+| `dynamic_stderr_handler.py` | `DynamicStderrHandler` — a logging handler that resolves `sys.stderr` at emit time (for testability) |
+| `eli11_reply_enforcer_constants.py` | Reply-shape thresholds (bullet cap, lead-line window, per-list-line word cap, overpacked list-line cap), the bullet / numbered-step / table-row / link-target / word patterns, the imperative instruction verbs, and the user-facing notice for the ELI11 reply-shape Stop hook |
+| `fable_spawn_gate_constants.py` | The spawn tool-name set, the fable model alias and the model-id segment split pattern, the `FABLE-SPAWN-AUTHORIZED` authorization token, the advisor-protocol document path, payload field names, the deny message, and the deny `additionalContext` recovery text for the fable-tier spawn gate |
+| `gh_pr_author_swap_constants.py` | Constants for the PR-author swap enforcement hooks |
+| `hardcoded_user_path_constants.py` | Patterns for detecting hardcoded home-directory paths |
+| `harness_scratchpad_constants.py` | Fixed path components (`claude` / `claude-` user-directory name and prefix, `scratchpad` leaf name), the PreToolUse session-id payload key, and the `CLAUDE_CODE_SESSION_ID` environment variable name that the code-rules and TDD gates use to recognize an existing harness session scratchpad directory |
+| `hedging_uncertainty_constants.py` | Sentence-boundary pattern, explicit uncertainty label patterns, hedge-term list separator, and positive corrective block text for OP-07C sentence-scoped hedging |
+| `hook_block_logger.py` | `log_hook_block()` — shared fail-safe logger every blocking hook calls to append a JSON record of each block decision to `~/.claude/logs/hook-blocks.log` |
+| `hook_log_extractor_constants.py` | Neon table name, offset state file path, timeouts, and outcome-type mapping for the hook-log extractor |
+| `hook_prose_detector_consistency_constants.py` | Trigger patterns and corrective messages for the hook-prose consistency checker |
+| `hosted_hook_runner.py` | `run_hook_capturing_output()` — shared runner that runs one dispatcher-hosted hook in-process via runpy and returns its captured stdout and crash flag |
+| `inline_tuple_string_magic_constants.py` | Patterns for detecting magic strings in inline tuple literals |
+| `js_conventions_constants.py` | Banned identifier set, boolean-prefix pattern, and declaration/JSDoc patterns for the JavaScript convention checks |
+| `local_identity.py` | Loader for local machine values: NAS host, ssh user, and ssh port the ssh enforcer guards (`CLAUDE_NAS_*` / `~/.claude/local-identity.json` with placeholder defaults), the PII commit-scan exempt-repo slug set (`CLAUDE_PII_EXEMPT_REPOS` / `pii_exempt_repositories`), and the per-repository allowlisted-values mapping (`pii_allowlisted_values`, keyed by owner/repo slug) read from the git-ignored local file whose path `CLAUDE_LOCAL_IDENTITY_PATH` may point elsewhere; also composes the ssh enforcer's two deny messages that quote the NAS values |
+| `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 |
+| `mypy_integration_constants.py` | Path markers (``.git``, ``.py``, ``pyproject.toml``) for mypy project-root resolution |
+| `mypy_validator_cache_constants.py` | Cache paths and tunables for the mypy_validator per-session caches |
+| `nas_ssh_binary_enforcer_constants.py` | Bash tool name, ssh-family basenames, OpenSSH binary path suffixes, and the batch-mode pattern for the NAS ssh binary enforcer; segment helpers come from `shell_command_segments.py` |
+| `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 |
+| `paired_test_coverage_constants.py` | Test-directory name, stem-test filename affixes, test-file globs, exempt public-function names, scan budget, coverage threshold, and guidance text for the public-function paired-test coverage check |
+| `path_rewriter_constants.py` | Path rewriting patterns for the Everything-search path rewriter |
+| `pii_prevention_constants.py` | Patterns, allowlists, path exemptions, and deny-message text for `pii_prevention_blocker` |
+| `piped_pytest_blocker_constants.py` | Bash tool name, pytest program basenames and the python-interpreter basename pattern, the pipe and segment-reset operator token sets, and the deny message for the piped-pytest blocker; classification that consumes those program and wrapper constants lives in `pytest_invocation.py` |
+| `pytest_invocation.py` | Pure parsed-segment classifier for pytest runs through interpreters, shims, wrappers, and shell string-exec forms; no pipeline deny decision |
+| `plain_language_blocker_constants.py` | The list of heavy words and their everyday replacements |
+| `prose_matcher_precision_constants.py` | Sample floor, keep/narrow precision floors, matcher ids, label decisions, advisory log path, emit caps, and context fingerprint length for OP-07B prose-matcher advisory telemetry |
+| `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 and finds a home-bounded git root for registry checks |
+| `pyproject_config_discovery_constants.py` | Table names (``tool`` key, ``mypy``, ``ruff``) for resolving a validator's config from a pyproject.toml `[tool.<name>]` table |
+| `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 |
+| `python_style_checks_constants.py` | Command-line argument count and blank-line count between top-level functions for the style validator |
+| `ruff_integration_constants.py` | ``NO_COLOR`` / ``FORCE_COLOR`` environment variable names for plain ruff diagnostics |
+| `send_user_file_open_locally_blocker_constants.py` | Tool name, proactive status, and the block message for the open-locally attach blocker |
+| `sensitive_file_protector_constants.py` | Sensitive filename patterns, the committed-template suffixes that earn an exemption, the write/edit tool names, and the deny decision and message template for `sensitive_file_protector` |
+| `session_edit_stage_gate_constants.py` | Tracker filename prefix/suffix, JSON payload key, edit tool name set, session-id sanitize pattern, lock filename suffix and lock-acquire timing, git diff command, commit flag escapes, and deny-message template shared by the session edit stage gate trio |
+| `session_env_cleanup_constants.py` | Stale-age threshold and directory names for the session-env cleanup hook |
+| `session_start_injector.py` | Pure SessionStart context injector: normalize `source` (`startup`/`resume`/`clear`/`compact`), honor enable/timeout, return structured injection results for starter hooks |
+| `session_start_injector_constants.py` | Known SessionStart source values, injection status codes, enable env var, default timeout for the shared injector |
+| `test_session_start_injector.py` | Behavioral tests for every known source, disabled, timeout, and unknown-source paths |
+| `orchestrator_auto_starter_constants.py` | Opt-in env var, enable values, timeout, and SessionStart directive text for the orchestrator auto-starter |
+| `issue_tracker_session_starter_constants.py` | Opt-in env var, enable values, timeout, and SessionStart directive text for the repository-gated issue-tracker starter |
+| `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 |
+| `shell_command_pipeline.py` | Quote-aware shell pipeline parsing: operator-paired segments after line-continuation join, comment strip, heredoc body drop, and parenthesis-group join |
+| `shell_command_segments.py` | Shell tokenization helpers shared by the segment-walking blockers: segment splitting on control operators, a segment's effective leading program, and a token's basename |
+| `shell_substitution_blocker_constants.py` | Tool name, payload keys, the four substitution-detection patterns, the deny decision shape, and the corrective message for the shell-substitution blocker |
+| `stale_comment_reference_blocker_constants.py` | Identifier pattern, comment stopwords, and denial text for the stale-comment-reference blocker |
+| `state_description_blocker_constants.py` | The set of historical/comparative phrases the state-description blocker rejects, plus the docstring-extraction and mention-span patterns for its Python docstring scan |
+| `stop_dispatcher_constants.py` | Ordered hosted-hook roster and Stop block payload field names for the Stop-chain dispatcher |
+| `stuttering_check_config.py` | Config for the stuttering (repeated-phrase) check |
+| `stuttering_import_binding_constants.py` | Import-binding patterns for the stuttering check |
+| `subprocess_budget_completeness_constants.py` | Required argument names for the subprocess-budget completeness check |
+| `sys_path_insert_constants.py` | Patterns for detecting unguarded `sys.path.insert` calls |
+| `task_list_loop_starter_constants.py` | The one-line task-list instruction and the full session-start directive text for the task-list loop starter hook |
+| `test_layout_constants.py` | The named constants for the test-layout write-time checks |
+| `text_stripping.py` | `strip_code_and_quotes()` — shared helper that removes fenced code blocks, inline code, and blockquotes from prose, imported by the Stop-hook prose blockers |
+| `unscoped_search_blocker_constants.py` | Tool names, `find` and listing program basenames, Get-ChildItem option sets, unscoped-root patterns, the flag/value token stride, and the deny message for the unscoped-search blocker |
+| `unused_module_import_constants.py` | Patterns for detecting unused module-level imports |
+| `volatile_path_in_post_blocker_constants.py` | Volatile path markers, affected `gh` post subcommands, MCP body param names, and the corrective message for the volatile-path post blocker |
+| `windows_rmtree_blocker_constants.py` | The unsafe `shutil.rmtree` pattern and the safe replacement pattern |
+| `workflow_substitution_slot_blocker_constants.py` | Per-iteration token patterns for the workflow-slot blocker |
+| `working_style_prompt_constants.py` | The fixed multi-paragraph working-style prompt text for the SessionStart working_style_prompt hook |
+
+## Conventions
+
+- Most files in this package are pure constants modules — no side effects, no I/O.
+- Hooks import from this package with `from hooks_constants.<module> import <CONSTANT>`.
+- Tests for these modules live beside them as `test_<module>.py`. Run with `python -m pytest hooks_constants/test_<name>.py`.
+- `dynamic_stderr_handler.py`, `pre_tool_use_stdin.py`, `multi_edit_reconstruction.py`, `hosted_hook_runner.py`, and `text_stripping.py` are utility modules (not pure constants) but live here because they hold logic shared across hook surfaces.
+- `local_identity.py` is a loader: it reads the environment or `~/.claude/local-identity.json` (its path overridable via `CLAUDE_LOCAL_IDENTITY_PATH`) to resolve private NAS values (with committed placeholder defaults), the PII commit-scan exempt-repo slug set (`CLAUDE_PII_EXEMPT_REPOS` / `pii_exempt_repositories`), and the per-repository allowlisted-values mapping (`pii_allowlisted_values`).