claude-dev-env 2.28.1 → 2.30.0

package/hooks/blocking/test_code_rules_validation_phase.py

@@ -0,0 +1,281 @@
+"""Tests for the validate_content edit-lane and full-gate phase split."""
+
+from __future__ import annotations
+
+import contextlib
+import importlib
+import importlib.util
+import inspect
+import re
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+from types import ModuleType
+from unittest.mock import DEFAULT, MagicMock, patch
+
+import pytest
+
+
+def _load_module_from_path(module_name: str, module_path: Path) -> ModuleType:
+    """Load and execute the module found at module_path, under module_name."""
+    specification = importlib.util.spec_from_file_location(module_name, module_path)
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+_BLOCKING_DIRECTORY = Path(__file__).resolve().parent
+_HOOKS_DIRECTORY = _BLOCKING_DIRECTORY.parent
+_PACKAGE_ROOT = _HOOKS_DIRECTORY.parent
+_PR_LOOP_SCRIPTS_DIRECTORY = str(_PACKAGE_ROOT / "_shared" / "pr-loop" / "scripts")
+
+code_rules_enforcer = _load_module_from_path(
+    "code_rules_enforcer", _BLOCKING_DIRECTORY / "code_rules_enforcer.py"
+)
+validation_phase_constants = _load_module_from_path(
+    "validation_phase_constants",
+    _HOOKS_DIRECTORY / "hooks_constants" / "validation_phase_constants.py",
+)
+
+if _PR_LOOP_SCRIPTS_DIRECTORY not in sys.path:
+    sys.path.insert(0, _PR_LOOP_SCRIPTS_DIRECTORY)
+enforcer_loading = importlib.import_module("code_rules_gate_parts.enforcer_loading")
+gate_running = importlib.import_module("code_rules_gate_parts.gate_running")
+repo_test_helpers = importlib.import_module("code_rules_gate_parts.tests._repo_test_helpers")
+
+PRODUCTION_FILE_PATH = "packages/app/services.py"
+SAMPLE_PYTHON_CONTENT = "def add_one(value: int) -> int:\n    return value + 1\n"
+UNKNOWN_PHASE_NAME = "not_a_real_phase"
+HOOK_INFRASTRUCTURE_FILE_PATH = "/repo/packages/claude-dev-env/hooks/blocking/example.py"
+_HOOK_MODULE_DUPLICATE_BODY_SOURCE = (
+    "def compute_shipping_total(order_total: float, tax_rate: float) -> float:\n"
+    "    taxed_total = order_total * (1 + tax_rate)\n"
+    "    rounded_total = round(taxed_total, 2)\n"
+    "    return rounded_total\n"
+)
+
+
+def test_all_validation_phases_holds_exactly_the_two_phases() -> None:
+    assert validation_phase_constants.ALL_VALIDATION_PHASES == {
+        validation_phase_constants.EDIT_LANE_PHASE,
+        validation_phase_constants.FULL_GATE_PHASE,
+    }
+
+
+def test_unknown_phase_raises_value_error_naming_the_rejected_value() -> None:
+    with pytest.raises(ValueError, match=UNKNOWN_PHASE_NAME):
+        code_rules_enforcer.validate_content_for_phase(
+            SAMPLE_PYTHON_CONTENT, PRODUCTION_FILE_PATH, phase=UNKNOWN_PHASE_NAME
+        )
+
+
+def test_validate_content_for_phase_requires_phase_keyword() -> None:
+    with pytest.raises(TypeError):
+        code_rules_enforcer.validate_content_for_phase(SAMPLE_PYTHON_CONTENT, PRODUCTION_FILE_PATH)
+
+
+def _full_gate_only_default_kwargs() -> dict[str, object]:
+    return {
+        each_name: DEFAULT
+        for each_name in validation_phase_constants.ALL_FULL_GATE_ONLY_CHECK_NAMES
+    }
+
+
+def _patched_full_gate_only_checks() -> contextlib.AbstractContextManager[dict[str, MagicMock]]:
+    """Return the patch.multiple context manager for the six full-gate-only checks.
+
+    ::
+
+        mypy's patch.multiple stub only accepts an ``Any | str`` target, so a
+        dynamically loaded ``ModuleType`` target needs a local type: ignore.
+    """
+    return patch.multiple(  # type: ignore[call-overload]  # mypy stub rejects ModuleType targets
+        code_rules_enforcer, **_full_gate_only_default_kwargs()
+    )
+
+
+def _configure_full_gate_only_mock_returns(all_mocks: dict[str, MagicMock]) -> None:
+    for each_name, each_mock in all_mocks.items():
+        each_mock.return_value = None if each_name == "advise_cross_skill_duplicate_helper" else []
+
+
+def test_edit_lane_calls_none_of_the_six_full_gate_only_checks() -> None:
+    with _patched_full_gate_only_checks() as all_mocks:
+        _configure_full_gate_only_mock_returns(all_mocks)
+        code_rules_enforcer.validate_content_for_edit_lane(
+            SAMPLE_PYTHON_CONTENT, PRODUCTION_FILE_PATH
+        )
+        for each_name, each_mock in all_mocks.items():
+            assert each_mock.call_count == 0, f"edit lane must not call {each_name}"
+
+
+def test_full_gate_calls_all_six_full_gate_only_checks() -> None:
+    with _patched_full_gate_only_checks() as all_mocks:
+        _configure_full_gate_only_mock_returns(all_mocks)
+        code_rules_enforcer.validate_content_for_full_gate(
+            SAMPLE_PYTHON_CONTENT, PRODUCTION_FILE_PATH
+        )
+        for each_name, each_mock in all_mocks.items():
+            assert each_mock.call_count >= 1, f"full gate must call {each_name}"
+
+
+def test_both_phases_report_identical_findings_with_the_six_spied_out() -> None:
+    with _patched_full_gate_only_checks() as all_mocks:
+        _configure_full_gate_only_mock_returns(all_mocks)
+        edit_lane_issues = code_rules_enforcer.validate_content_for_edit_lane(
+            SAMPLE_PYTHON_CONTENT, PRODUCTION_FILE_PATH
+        )
+        full_gate_issues = code_rules_enforcer.validate_content_for_full_gate(
+            SAMPLE_PYTHON_CONTENT, PRODUCTION_FILE_PATH
+        )
+    assert edit_lane_issues == full_gate_issues
+
+
+def test_no_caller_should_reach_a_phase_less_validator() -> None:
+    assert not hasattr(code_rules_enforcer, "validate_content"), (
+        "validate_content must not survive as a callable on the enforcer module"
+    )
+    enforcer_source = inspect.getsource(code_rules_enforcer)
+    assert re.search(r"\bvalidate_content\(", enforcer_source) is None, (
+        "no call site in code_rules_enforcer.py may reach a phase-less validator"
+    )
+
+
+def test_precheck_selects_the_full_gate() -> None:
+    precheck_source = inspect.getsource(code_rules_enforcer._run_precheck)
+    assert "validate_content_for_full_gate(" in precheck_source, (
+        "the --check precheck must run the full-gate verdict"
+    )
+
+
+def test_codex_patch_issues_selects_the_edit_lane() -> None:
+    """Pin the apply_patch mutation path to the edit-lane verdict."""
+    codex_patch_issues_source = inspect.getsource(code_rules_enforcer._codex_patch_issues)
+    assert "validate_content_for_edit_lane(" in codex_patch_issues_source, (
+        "the apply_patch branch must run the edit-lane verdict"
+    )
+
+
+def test_forecast_full_file_violations_selects_the_edit_lane() -> None:
+    """Pin the full-file forecast pass to the edit-lane verdict."""
+    forecast_source = inspect.getsource(code_rules_enforcer._forecast_full_file_violations)
+    assert "validate_content_for_edit_lane(" in forecast_source, (
+        "the full-file forecast pass must run the edit-lane verdict"
+    )
+
+
+def test_report_blocking_violations_selects_the_edit_lane() -> None:
+    """Pin the PreToolUse Write and Edit main path to the edit-lane verdict."""
+    report_blocking_violations_source = inspect.getsource(
+        code_rules_enforcer._report_blocking_violations
+    )
+    assert "validate_content_for_edit_lane(" in report_blocking_violations_source, (
+        "the PreToolUse Write and Edit main path must run the edit-lane verdict"
+    )
+
+
+def _write_scoped_service_file_with_a_committed_baseline(repository_root: Path) -> Path:
+    repo_test_helpers.init_repository(repository_root)
+    return repo_test_helpers.write_commit_and_stage_change(
+        repository_root,
+        "service.py",
+        "def read_port() -> int:\n    return 0\n",
+        "def read_port() -> int:\n    port_number = 9999\n    return port_number\n",
+    )
+
+
+def test_hook_infrastructure_edit_lane_skips_the_cross_file_duplicate_check() -> None:
+    with patch.object(
+        code_rules_enforcer, "check_duplicate_function_body_across_files"
+    ) as mock_check_duplicate_across_files:
+        mock_check_duplicate_across_files.return_value = []
+        code_rules_enforcer._hook_infrastructure_blocking_issues(
+            SAMPLE_PYTHON_CONTENT,
+            HOOK_INFRASTRUCTURE_FILE_PATH,
+            phase=validation_phase_constants.EDIT_LANE_PHASE,
+        )
+    assert mock_check_duplicate_across_files.call_count == 0, (
+        "the hook-infrastructure edit lane must not call the cross-file duplicate-body check"
+    )
+
+
+def test_hook_infrastructure_full_gate_calls_the_cross_file_duplicate_check() -> None:
+    with patch.object(
+        code_rules_enforcer, "check_duplicate_function_body_across_files"
+    ) as mock_check_duplicate_across_files:
+        mock_check_duplicate_across_files.return_value = []
+        code_rules_enforcer._hook_infrastructure_blocking_issues(
+            SAMPLE_PYTHON_CONTENT,
+            HOOK_INFRASTRUCTURE_FILE_PATH,
+            phase=validation_phase_constants.FULL_GATE_PHASE,
+        )
+    assert mock_check_duplicate_across_files.call_count == 1, (
+        "the hook-infrastructure full gate must still call the cross-file duplicate-body check"
+    )
+
+
+def _write_duplicate_helper_pair_under_a_non_test_named_tempdir() -> tuple[Path, str]:
+    """Write a hook-infra sibling pair under a ``tempfile.mkdtemp()`` root.
+
+    ``tempfile.mkdtemp()`` names its directory ``tmp<random>``, carrying no
+    ``test_`` segment, unlike pytest's own ``tmp_path`` fixture — whose
+    directory embeds the test's name and so reads as a test path to
+    ``is_test_file``'s full-path substring match, silently exempting every
+    check the caller means to exercise.
+    """
+    base_directory = Path(tempfile.mkdtemp())
+    hook_blocking_directory = base_directory / "packages" / "claude-dev-env" / "hooks" / "blocking"
+    hook_blocking_directory.mkdir(parents=True)
+    (hook_blocking_directory / "shipping_helper.py").write_text(
+        _HOOK_MODULE_DUPLICATE_BODY_SOURCE, encoding="utf-8"
+    )
+    return base_directory, str(hook_blocking_directory / "shipping_target.py")
+
+
+def test_full_gate_still_catches_a_helper_duplicated_across_two_hook_modules() -> None:
+    base_directory, target_path = _write_duplicate_helper_pair_under_a_non_test_named_tempdir()
+    try:
+        full_gate_issues = code_rules_enforcer._hook_infrastructure_blocking_issues(
+            _HOOK_MODULE_DUPLICATE_BODY_SOURCE,
+            target_path,
+            phase=validation_phase_constants.FULL_GATE_PHASE,
+        )
+        edit_lane_issues = code_rules_enforcer._hook_infrastructure_blocking_issues(
+            _HOOK_MODULE_DUPLICATE_BODY_SOURCE,
+            target_path,
+            phase=validation_phase_constants.EDIT_LANE_PHASE,
+        )
+    finally:
+        shutil.rmtree(base_directory, ignore_errors=False)
+
+    assert any("duplicates" in each_issue for each_issue in full_gate_issues), (
+        "the full gate must still catch a helper duplicated across two hook "
+        f"modules, got: {full_gate_issues!r}"
+    )
+    assert not any("duplicates" in each_issue for each_issue in edit_lane_issues), (
+        "the edit lane must not run the cross-file duplicate-body check against "
+        f"hook infrastructure, got: {edit_lane_issues!r}"
+    )
+
+
+def test_gate_running_selects_the_full_gate(tmp_path: Path) -> None:
+    repository_root = tmp_path / "repo"
+    repository_root.mkdir()
+    file_path = _write_scoped_service_file_with_a_committed_baseline(repository_root)
+
+    loaded_validate_content = enforcer_loading.load_validate_content_for_full_gate()
+    assert loaded_validate_content.__name__ == "validate_content_for_full_gate"
+
+    scoped_violations = gate_running._scoped_violations_for_file(
+        validate_content=loaded_validate_content,
+        resolved_path=file_path,
+        repository_root=repository_root,
+        all_added_lines_for_file={2, 3},
+        should_read_staged_content=True,
+    )
+    assert scoped_violations is not None
+    blocking_violations, _advisory_violations = scoped_violations
+    assert any("9999" in each_issue for each_issue in blocking_violations)

package/hooks/blocking/test_fable_spawn_gate.py

@@ -72,7 +72,7 @@ _ADVISOR_LIFECYCLE_TEXT = (_ADVISOR_REFERENCE_DIR / "lifecycle.md").read_text(
 _ADVISOR_WARM_UP_TEXT = (_ADVISOR_REFERENCE_DIR / "warm-up.md").read_text(
     encoding="utf-8"
 )
-_ALL_CONSUMING_SKILL_NAMES = ("team-advisor", "orchestrator", "orchestrator-refresh")
+_ALL_CONSUMING_SKILL_NAMES = ("team-advisor",)
 _ALL_CONSUMING_SKILL_PATHS = tuple(
     _PACKAGE_ROOT / ".agents" / "skills" / each_skill_name / "SKILL.md"
     for each_skill_name in _ALL_CONSUMING_SKILL_NAMES

package/hooks/blocking/test_pre_tool_use_dispatcher.py

@@ -734,16 +734,31 @@ def test_dispatcher_multi_edit_applies_only_group_b() -> None:
     )
 
 
-def test_proceed_after_run_all_validators_removal_allows() -> None:
-    """The PreToolUse dispatcher allows a Python edit that the removed gate would have processed.
-
-    The inline run_all_validators runner was a PostToolUse gate removed in Stage 4;
-    it was never a PreToolUse hook and never hosted by the PreToolUse dispatcher.
-    A Python Write payload that run_all_validators would have flagged (mypy errors, for
-    instance) still produces ALLOW from the PreToolUse dispatcher because the PreToolUse
-    dispatcher covers only its 23 hosted blocking hooks — none of which includes the
-    validators runner.
+def _assert_roster_names_no_run_all_validators_entry() -> None:
+    """Assert no hosted-roster ``script_relative_path`` names run_all_validators."""
+    all_roster_script_paths = {
+        each_entry.script_relative_path for each_entry in ALL_HOSTED_HOOK_ENTRIES
+    }
+    assert not any(
+        "run_all_validators" in each_script_path
+        for each_script_path in all_roster_script_paths
+    ), (
+        "ALL_HOSTED_HOOK_ENTRIES must name no run_all_validators entry, got: "
+        f"{sorted(all_roster_script_paths)}"
+    )
+
+
+def test_run_all_validators_is_not_hosted_by_pre_tool_use_dispatcher() -> None:
+    """The main PreToolUse dispatcher's hosted roster names no run_all_validators entry.
+
+    ``hooks.json`` registers the ``run_all_validators`` runner as its own
+    PreToolUse ``Write|Edit`` command, separate from the main dispatcher. A
+    Python Write payload that ``run_all_validators`` would flag (a type error,
+    for instance) still produces ALLOW from the main dispatcher, because its
+    roster carries no entry for that runner.
     """
+    _assert_roster_names_no_run_all_validators_entry()
+
     python_content_with_type_error = (
         "def add_one(value: int) -> int:\n"
         "    return value + 1\n\n\n"
@@ -754,8 +769,8 @@ def test_proceed_after_run_all_validators_removal_allows() -> None:
     is_deny, _reason = _parse_hook_decision(dispatcher_result)
     assert not is_deny, (
         "PreToolUse dispatcher must allow a Python Write with a type error — "
-        "mypy validation is PostToolUse-only; the removed run_all_validators gate "
-        "was never a PreToolUse hook"
+        "run_all_validators runs as its own separate PreToolUse command, not "
+        "through this dispatcher's roster"
     )
     assert dispatcher_result.returncode == 0, (
         f"Dispatcher must exit 0, got {dispatcher_result.returncode}"

package/hooks/git-hooks/AGENTS.md

@@ -1,32 +1 @@
-# hooks/git-hooks
 
-Native git hooks that run outside the Claude Code lifecycle — invoked directly by git at commit and push time. The installer copies these scripts into the user's shared git-hooks directory (`core.hooksPath`).
-
-## Key files
-
-| File | Git hook | What it does |
-|---|---|---|
-| `pre_commit.py` | `pre-commit` | Runs immediate CODE_RULES and terminology validation over staged changes; exits 1 when any staged file has a blocking violation. CI runs package tests for package Python changes. |
-| `pre_push.py` | `pre-push` | Blocks a push that would land a non-`main` local branch onto remote `main` (or `master`), then runs the CODE_RULES gate. An existing branch's gate base is the merge base with the remote default branch; the gate process still diffs that base against checkout HEAD, so the surface matches the pushed tip only when HEAD is that tip. |
-| `pre_push_base_reference.py` | — | Resolves a usable gate base for `pre_push.py`: reads the pushed remote name from git's arguments, then turns a symbolic default-branch head into a reference that git can resolve |
-| `post_commit.py` | `post-commit` | Runs bookkeeping, then best-effort reminds the agent about its PR |
-| `pull_request_handoff.py` | — | Prints the full PR title and description handoff prompt |
-| `gate_utils.py` | — | Shared helpers: resolves the gate script path, checks that the path is a safe regular file |
-| `test_config.py` | — | Test configuration helpers |
-| `test_gate_utils.py` | — | Tests for `gate_utils.py` |
-| `test_pre_commit.py` | — | Tests for `pre_commit.py` |
-| `test_pre_push.py` | — | Tests for `pre_push.py` |
-| `test_pre_push_base_reference.py` | — | Tests for the gate base resolution in `pre_push.py` |
-| `conftest.py` | — | Puts this directory on `sys.path` and clears cached `config` modules, so each test module imports the hooks at the top of the file |
-
-## Subdirectory
-
-| Directory | Role |
-|---|---|
-| `git_hooks_constants/` | Shared constants imported by the git-hook scripts |
-
-## Conventions
-
-- The installer strips the `_` and `.py` suffix when copying into the live git-hooks path (e.g. `pre_commit.py` becomes `pre-commit`).
-- Constants (exit codes, argument names, error messages) live in `git_hooks_constants/` and are imported at the top of each script.
-- Run tests with `python -m pytest git-hooks/test_<name>.py`.

package/hooks/git-hooks/git_hooks_constants/AGENTS.md

@@ -1,21 +1 @@
-# hooks/git-hooks/git_hooks_constants
 
-Shared constants imported by the git-hook scripts in `git-hooks/`. Centralizes exit codes, argument names, and error messages so every tunable lives in one place.
-
-## Files
-
-| File | Contents |
-|---|---|
-| `__init__.py` | Exports all constants; marks this as a package so `from git_hooks_constants import ...` resolves |
-
-## Key constants (defined in `__init__.py`)
-
-- `GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE` — exit code when the gate script cannot be found or launched
-- `GATE_SCRIPT_NOT_FOUND_MESSAGE` — error message when the gate script path does not exist
-- `INVOKE_GATE_FAILURE_MESSAGE` — error message when the gate subprocess fails to start
-- `STAGED_SCOPE_ARGUMENT` — CLI argument passed to the gate script to scope it to staged changes
-
-## Conventions
-
-- Import with `from git_hooks_constants import <CONSTANT>` from within the `git-hooks/` directory.
-- Add new constants here rather than inline in the hook scripts.

package/hooks/hooks_constants/AGENTS.md

@@ -1,100 +1 @@
-# 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) |
-| `pre_tool_use_dispatcher_constants.py` | Shared Write, Edit, and MultiEdit tool-name set and the ordered hosted-hook roster for the Write/Edit/MultiEdit PreToolUse dispatcher |
-| `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 |
-| `cursor_cli_python_misfire_blocker_constants.py` | Detection patterns and deny message for Cursor launches that mistreat a Python code-rules-gate script |
-| `destructive_command_environment_constants.py` | Environment keys and shared truthy values used by destructive-command hooks |
-| `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) |
-| `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 |
-| `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_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, plus detached-file `--follow-imports=skip` flags, subprocess timeout, and timeout skip message |
-| `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 |
-| `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` | Git-repository-root resolution command and timeout for the `precommit_code_rules_gate` library module |
-| 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 `Invoke-Item` block message for the open-locally attach blocker |
-| `sensitive_file_protector_constants.py` | Sensitive filename patterns, committed-template suffixes that earn an exemption, 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 |
-| `style_reminder_prompt_constants.py` | The style reminder text ("small words. few words. always. forever.") for the style_reminder_prompt hook |
-| `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`).

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -6,6 +6,14 @@ Extracted from code_rules_enforcer.py to satisfy the constants-location rule.
 import re
 import tokenize
 
+from hooks_constants.validation_phase_constants import (  # noqa: F401  re-exported for code_rules_enforcer.py
+    ALL_HOOK_INFRASTRUCTURE_EDIT_LANE_CHECK_NAMES,
+    ALL_VALIDATION_PHASES,
+    EDIT_LANE_PHASE,
+    FULL_GATE_PHASE,
+    UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE,
+)
+
 ALL_PYTHON_TOKENIZE_FAILURE_EXCEPTIONS: tuple[type[BaseException], ...] = (
     tokenize.TokenError,
     IndentationError,

package/hooks/hooks_constants/test_code_rules_enforcer_constants.py

@@ -17,12 +17,17 @@ if str(_HOOKS_ROOT) not in sys.path:
     sys.path.insert(0, str(_HOOKS_ROOT))
 
 from hooks_constants.code_rules_enforcer_constants import (
+    ALL_HOOK_INFRASTRUCTURE_EDIT_LANE_CHECK_NAMES,
+    ALL_VALIDATION_PHASES,
     CONFIG_DIRECTORY_SEGMENT,
     CONSTANTS_MODULE_SUFFIX,
+    EDIT_LANE_PHASE,
+    FULL_GATE_PHASE,
     FUNCTION_WITH_JSDOC_PATTERN,
     JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN,
     RETURN_CALL_OPENING_PARENTHESIS_PATTERN,
     SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN,
+    UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE,
 )
 
 
@@ -98,3 +103,19 @@ def test_schema_property_key_pattern_matches_only_the_options_key() -> None:
 def test_constants_module_suffix_and_config_directory_segment_are_defined() -> None:
     assert CONSTANTS_MODULE_SUFFIX == "_constants.py"
     assert CONFIG_DIRECTORY_SEGMENT == "config"
+
+
+def test_validation_phase_constants_are_reexported_and_render() -> None:
+    assert ALL_VALIDATION_PHASES == {EDIT_LANE_PHASE, FULL_GATE_PHASE}
+    rendered_message = UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE.format(
+        phase="bogus_phase", all_phases=sorted(ALL_VALIDATION_PHASES)
+    )
+    assert "bogus_phase" in rendered_message
+
+
+def test_hook_infrastructure_edit_lane_check_names_are_reexported() -> None:
+    assert ALL_HOOK_INFRASTRUCTURE_EDIT_LANE_CHECK_NAMES == {
+        "check_same_file_inline_duplicate_body",
+        "check_zero_payload_function_alias",
+        "check_unanchored_command_dispatch",
+    }

package/hooks/hooks_constants/validation_phase_constants.py

@@ -0,0 +1,34 @@
+"""Constants for the validate_content edit-lane and full-gate phase split.
+
+The edit lane and the full gate share every check except six that read
+sibling modules from disk. These names identify each phase, name the checks
+the full gate alone runs, name the hook-infrastructure checks the edit lane
+still runs, and template the error for an unrecognized phase.
+"""
+
+EDIT_LANE_PHASE: str = "edit_lane"
+FULL_GATE_PHASE: str = "full_gate"
+ALL_VALIDATION_PHASES: frozenset[str] = frozenset({EDIT_LANE_PHASE, FULL_GATE_PHASE})
+
+ALL_FULL_GATE_ONLY_CHECK_NAMES: frozenset[str] = frozenset(
+    {
+        "check_duplicate_function_body_across_files",
+        "advise_cross_skill_duplicate_helper",
+        "check_public_function_missing_paired_test",
+        "check_test_file_omits_module_public_function",
+        "check_orphan_css_classes",
+        "check_config_duplicate_path_anchor",
+    }
+)
+
+ALL_HOOK_INFRASTRUCTURE_EDIT_LANE_CHECK_NAMES: frozenset[str] = frozenset(
+    {
+        "check_same_file_inline_duplicate_body",
+        "check_zero_payload_function_alias",
+        "check_unanchored_command_dispatch",
+    }
+)
+
+UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE: str = (
+    "unrecognized validation phase {phase!r}; expected one of {all_phases}"
+)

package/hooks/lifecycle/AGENTS.md

@@ -1,18 +1 @@
-# hooks/lifecycle
 
-Hooks that run at session or config-change boundaries rather than on individual tool calls.
-
-## Key files
-
-| File | Event | What it does |
-|---|---|---|
-| `config_change_guard.py` | PostToolUse (Write/Edit on `settings.json`) | Counts hooks in the edited `settings.json` and logs any change to `~/.claude/cache/config-change-audit.log`; alerts when the hook count drops below the last known value |
-| `enter_worktree_origin_prefetch.py` | PreToolUse (EnterWorktree) | Fetches origin's default branch before a worktree creation call, keeping the `refs/remotes/origin/<default-branch>` ref that `fresh` mode reads current; never blocks on fetch failure |
-| `session_end_cleanup.py` | SessionEnd | Purges stale cache entries from `~/.claude/cache/` (entries older than the configured threshold) and old backup files |
-| `test_config_change_guard.py` | — | Tests for `config_change_guard.py` |
-| `test_enter_worktree_origin_prefetch.py` | — | Tests for `enter_worktree_origin_prefetch.py` |
-
-## Conventions
-
-- Constants for these hooks (stale-age threshold, cache directory, known-hook-count file, EnterWorktree prefetch tuning) live in `hooks_constants/session_env_cleanup_constants.py` and `hooks_constants/enter_worktree_prefetch_constants.py`.
-- Tests run with `python -m pytest lifecycle/test_<name>.py`.

package/hooks/observability/AGENTS.md

@@ -1,20 +1 @@
-# hooks/observability
 
-PostToolUse hooks that record agent behavior for later review. These hooks do not block tool calls; they log or annotate them.
-
-## Key files
-
-| File | Event | What it does |
-|---|---|---|
-| `instructions_loaded_logger.py` | PostToolUse (file load events) | Appends a JSONL record to `~/.claude/logs/instructions_loaded.jsonl` each time Claude Code loads a context file (CLAUDE.md, rules, skills), capturing the file path, load reason, memory type, and session ID |
-| `session_file_edit_tracker.py` | PostToolUse (Write/Edit/MultiEdit) | Records the resolved absolute path of each file edited this session into a per-session JSON file under the system temp directory, for the session edit stage gate to read at commit time |
-| `prose_matcher_advisory.py` | Advisory emit from prose matchers | Privacy-safe JSONL candidates (`matcher_id`, surface, context fingerprint, label) plus keep/narrow/drop/advisory classification against the sample floor |
-| `test_instructions_loaded_logger.py` | — | Tests for `instructions_loaded_logger.py` |
-| `test_session_file_edit_tracker.py` | — | Tests for `session_file_edit_tracker.py` |
-| `test_prose_matcher_advisory.py` | — | Tests for advisory emit and precision classification |
-
-## Conventions
-
-- The log file is append-only; the hook creates the parent directory if needed.
-- Errors during logging are caught and written as error records rather than propagated — the hook never blocks the tool call.
-- Tests run with `python -m pytest observability/test_instructions_loaded_logger.py`.