claude-dev-env 2.30.1 → 2.31.0

package/hooks/validators/run_all_validators.py

@@ -24,6 +24,7 @@ from .config.directory_exemption_constants import (
     ALL_DIRECTORY_EXEMPTION_SEGMENT_NAMES,
     ALL_DIRECTORY_EXEMPTION_SUBSTRING_PATTERNS,
 )
+from .fast_save_validators import FastSaveCheckOutcome, run_fast_save_validators
 from .health_check import get_system_health, get_validator_version, print_health_report
 from .mypy_integration import check_mypy_available, run_mypy_check
 from .system_temporary_roots import enclosing_system_temporary_root
@@ -42,6 +43,35 @@ hooks_dir = VALIDATORS_DIR.parent
 package_name = VALIDATORS_DIR.name
 
 
+def _gate_entry_for_fast_save_check(
+    check_outcome: FastSaveCheckOutcome,
+) -> "ValidatorResult":
+    """Wrap one in-process check's finding into the gate's shared reporting type."""
+    return ValidatorResult(
+        name=check_outcome.display_name,
+        checks=check_outcome.checks,
+        passed=check_outcome.is_clean,
+        output=check_outcome.violation_report,
+    )
+
+
+def _run_fast_save_checks(files: List[Path]) -> List["ValidatorResult"]:
+    """Run the save-path roster in-process and wrap each finding for the gate.
+
+    Args:
+        files: The files under validation -- one reconstructed file in gate mode.
+
+    Returns:
+        One ValidatorResult per in-process save-path check. Ruff and Mypy are
+        not part of this roster; the caller adds Ruff separately and never
+        adds Mypy on the save path.
+    """
+    return [
+        _gate_entry_for_fast_save_check(each_outcome)
+        for each_outcome in run_fast_save_validators(files)
+    ]
+
+
 def _windows_non_unc_working_directory_string(
     candidate_directory_strings: list[str | None],
 ) -> str:
@@ -731,38 +761,6 @@ def reconstruct_proposed_content(
     return apply_edits(existing_content, edits_for_tool(tool_name, dict(tool_input)))
 
 
-def run_file_scoped_validators(
-    all_files: List[Path], config_source_path: Optional[Path] = None
-) -> List[ValidatorResult]:
-    """Run every file-scoped validator against *all_files*.
-
-    Excludes the branch-scoped File Structure and Git validators.
-
-    Args:
-        all_files: The files under validation — one reconstructed file in gate mode.
-        config_source_path: Original path ruff and mypy resolve their config from.
-
-    Returns:
-        One ValidatorResult per file-scoped validator, in run order.
-    """
-    return [
-        run_python_style_checks(all_files),
-        run_test_safety_checks(all_files),
-        run_react_checks(all_files),
-        run_ruff_checks(all_files, config_source_path),
-        run_mypy_checks(all_files, config_source_path),
-        run_abbreviation_checks(all_files),
-        run_pr_reference_checks(all_files),
-        run_magic_value_checks(all_files),
-        run_useless_test_checks(all_files),
-        run_security_checks(all_files),
-        run_code_quality_checks(all_files),
-        run_python_antipattern_checks(all_files),
-        run_todo_checks(all_files),
-        run_type_safety_checks(all_files),
-    ]
-
-
 def _escapes_temporary_root(path_part: str) -> bool:
     """Return True when a path part would climb out of or re-anchor the temp root.
 
@@ -919,18 +917,20 @@ def validate_proposed_file(
     Writes the content to a temporary file that preserves the exemption-relevant
     directory tail and basename so directory-based exemptions, suffix-based
     filtering, and test-name-based filtering match the real path, then runs the
-    file-scoped validators against it. Ruff and mypy resolve their config by
-    walking up from the config source path, so the staged copy is graded under
-    the project config the real path sits in rather than the temp directory's.
+    save-path checks in-process against it, plus Ruff. Ruff resolves its config
+    by walking up from the config source path, so the staged copy is graded
+    under the project config the real path sits in rather than the temp
+    directory's.
 
     Args:
         file_path: The destination path the write or edit targets.
         proposed_content: The reconstructed post-edit content of that file.
-        config_source_path: Path ruff and mypy resolve their config from;
-            defaults to *file_path* when the caller passes nothing.
+        config_source_path: Path Ruff resolves its config from; defaults to
+            *file_path* when the caller passes nothing.
 
     Returns:
-        One ValidatorResult per file-scoped validator.
+        One ValidatorResult per save-path check, plus Ruff. Mypy never runs
+        here; CLI/full mode is the only caller that still runs it.
     """
     with tempfile.TemporaryDirectory() as temporary_directory:
         temporary_file = _temporary_path_preserving_directory_signal(
@@ -942,9 +942,10 @@ def validate_proposed_file(
             if config_source_path is not None
             else Path(file_path)
         )
-        return run_file_scoped_validators(
-            [temporary_file], config_source_path=resolved_config_source_path
-        )
+        return [
+            *_run_fast_save_checks([temporary_file]),
+            run_ruff_checks([temporary_file], resolved_config_source_path),
+        ]
 
 
 def _validator_summaries(results: List[ValidatorResult]) -> str:

package/hooks/validators/test_abbreviation_checks.py

@@ -74,3 +74,23 @@ class TestSingleLetterVariables:
         tree = ast.parse(ALLOWED_LOOP_COUNTERS)
         violations = check_single_letter_variables(tree, "test.py")
         assert violations == []
+
+    def test_underscore_allowed_alongside_disallowed_single_letter(self) -> None:
+        """``_`` and the loop counters share one allow-list; every other letter fails.
+
+        config/abbreviation_checks_constants.py pins the allow-list's exact
+        membership; this test pins that check_single_letter_variables reads
+        that same list correctly for a mixed allowed/disallowed source.
+        """
+        source = '''
+def process(matrix):
+    for i in range(10):
+        for j in range(10):
+            for k in range(10):
+                _ = matrix[i][j][k]
+                q = matrix[i][j][k]
+'''
+        tree = ast.parse(source)
+        violations = check_single_letter_variables(tree, "test.py")
+        assert len(violations) == 1
+        assert "q" in violations[0].message

package/hooks/validators/test_fast_save_validators.py

@@ -0,0 +1,172 @@
+"""Tests for fast_save_validators.py -- the in-process save-path validator roster."""
+
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from .fast_save_validators import run_fast_save_validators
+from .magic_value_checks import validate_file as read_magic_literal_violations
+from .react_checks import check_no_class_components
+from .test_safety_checks import check_no_skip_decorators
+from .todo_checks import validate_file as read_todo_violations
+
+MAGIC_LITERAL_SOURCE = "def compute_total(unit_price: int) -> int:\n    return unit_price * 199\n"
+_UNTRACKED_TODO_MARKER = "#" + " TODO"
+TODO_SOURCE = f"{_UNTRACKED_TODO_MARKER}: revisit this\ndef clean() -> None:\n    return None\n"
+REACT_CLASS_COMPONENT_SOURCE = "class Widget extends Component {\n  render() { return null; }\n}\n"
+TEST_SKIP_DECORATOR_SOURCE = (
+    "import pytest\n\n\n@pytest.mark.skip\ndef test_something() -> None:\n    pass\n"
+)
+
+_ALL_EXPECTED_FAST_SAVE_VALIDATOR_NAMES = frozenset(
+    {
+        "Python Style",
+        "Abbreviations",
+        "Magic Values",
+        "TODO Tracking",
+        "Security",
+        "Code Quality",
+        "Python Anti-patterns",
+        "Type Safety",
+        "Test Safety",
+        "Useless Tests",
+        "React",
+        "PR References",
+    }
+)
+
+
+def test_run_fast_save_validators_covers_every_non_mypy_non_ruff_check(
+    tmp_path: Path,
+) -> None:
+    target_file = tmp_path / "legacy_module.py"
+    target_file.write_text(MAGIC_LITERAL_SOURCE, encoding="utf-8")
+
+    all_outcomes = run_fast_save_validators([target_file])
+
+    assert {each_outcome.display_name for each_outcome in all_outcomes} == (
+        _ALL_EXPECTED_FAST_SAVE_VALIDATOR_NAMES
+    )
+
+
+def test_run_fast_save_validators_excludes_mypy_and_ruff(tmp_path: Path) -> None:
+    target_file = tmp_path / "legacy_module.py"
+    target_file.write_text(MAGIC_LITERAL_SOURCE, encoding="utf-8")
+
+    all_outcomes = run_fast_save_validators([target_file])
+
+    assert all(each_outcome.display_name != "Mypy" for each_outcome in all_outcomes)
+    assert all(each_outcome.display_name != "Ruff" for each_outcome in all_outcomes)
+
+
+def test_run_fast_save_validators_spawns_no_subprocess(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    target_file = tmp_path / "legacy_module.py"
+    target_file.write_text(MAGIC_LITERAL_SOURCE, encoding="utf-8")
+
+    def _fail_if_called(*args: object, **kwargs: object) -> None:
+        raise AssertionError("run_fast_save_validators must not spawn a subprocess")
+
+    monkeypatch.setattr("subprocess.run", _fail_if_called)
+
+    run_fast_save_validators([target_file])
+
+
+def test_magic_values_outcome_matches_direct_validate_file_call(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # A directory with no "test_"-patterned segment: magic_value_checks exempts
+    # any path under one, which pytest's own tmp_path always carries (tmp_path
+    # names itself "test_<function name><N>"). tmp_path's own parent carries no
+    # such segment. Routing TMPDIR there through monkeypatch, and also passing
+    # it as TemporaryDirectory's own ``dir``, keeps the probe from depending on
+    # whatever the real process environment happens to hold.
+    isolated_root = tmp_path.parent
+    monkeypatch.setenv("TMPDIR", str(isolated_root))
+    with tempfile.TemporaryDirectory(
+        dir=str(isolated_root), prefix="fast_save_probe_"
+    ) as workspace_name:
+        target_file = Path(workspace_name) / "legacy_module.py"
+        target_file.write_text(MAGIC_LITERAL_SOURCE, encoding="utf-8")
+        expected_lines = [
+            str(each) for each in read_magic_literal_violations(target_file)
+        ]
+        assert expected_lines != []
+
+        all_outcomes = run_fast_save_validators([target_file])
+
+    magic_values_outcome = next(
+        each for each in all_outcomes if each.display_name == "Magic Values"
+    )
+    assert magic_values_outcome.violation_report == "\n".join(expected_lines)
+
+
+def test_todo_outcome_matches_direct_validate_file_call(tmp_path: Path) -> None:
+    target_file = tmp_path / "legacy_module.py"
+    target_file.write_text(TODO_SOURCE, encoding="utf-8")
+    expected_lines = [str(each) for each in read_todo_violations(target_file)]
+    assert expected_lines != []
+
+    all_outcomes = run_fast_save_validators([target_file])
+
+    todo_outcome = next(each for each in all_outcomes if each.display_name == "TODO Tracking")
+    assert todo_outcome.violation_report == "\n".join(expected_lines)
+
+
+def test_abbreviations_outcome_reports_clean_for_a_clean_file(tmp_path: Path) -> None:
+    target_file = tmp_path / "legacy_module.py"
+    target_file.write_text(
+        "def add_two_numbers(first: int, second: int) -> int:\n    return first + second\n",
+        encoding="utf-8",
+    )
+
+    all_outcomes = run_fast_save_validators([target_file])
+
+    abbreviations_outcome = next(
+        each for each in all_outcomes if each.display_name == "Abbreviations"
+    )
+    assert abbreviations_outcome.is_clean is True
+
+
+def test_react_outcome_matches_direct_check_function_call(tmp_path: Path) -> None:
+    target_file = tmp_path / "widget.tsx"
+    target_file.write_text(REACT_CLASS_COMPONENT_SOURCE, encoding="utf-8")
+    expected_violations = check_no_class_components([str(target_file)])
+    expected_lines = [f"{each.file}:{each.line}: {each.message}" for each in expected_violations]
+    assert expected_lines != []
+
+    all_outcomes = run_fast_save_validators([target_file])
+
+    react_outcome = next(each for each in all_outcomes if each.display_name == "React")
+    assert react_outcome.violation_report == "\n".join(expected_lines)
+
+
+def test_test_safety_outcome_matches_direct_check_function_calls(
+    tmp_path: Path,
+) -> None:
+    target_file = tmp_path / "test_something.py"
+    target_file.write_text(TEST_SKIP_DECORATOR_SOURCE, encoding="utf-8")
+    code = target_file.read_text(encoding="utf-8")
+    expected_violations = check_no_skip_decorators(code, str(target_file))
+    expected_lines = [str(each) for each in expected_violations]
+    assert expected_lines != []
+
+    all_outcomes = run_fast_save_validators([target_file])
+
+    test_safety_outcome = next(each for each in all_outcomes if each.display_name == "Test Safety")
+    assert test_safety_outcome.violation_report == "\n".join(expected_lines)
+
+
+def test_no_matching_files_reports_configured_message(tmp_path: Path) -> None:
+    target_file = tmp_path / "widget.tsx"
+    target_file.write_text("export const Widget = () => null;\n", encoding="utf-8")
+
+    all_outcomes = run_fast_save_validators([target_file])
+
+    abbreviations_outcome = next(
+        each for each in all_outcomes if each.display_name == "Abbreviations"
+    )
+    assert abbreviations_outcome.is_clean is True
+    assert abbreviations_outcome.violation_report == "No Python files to check"

package/hooks/validators/test_python_style_checks.py

@@ -197,6 +197,15 @@ class TestImportsAtTop:
         assert len(violations) == 1
         assert "inside function" in violations[0].message.lower()
 
+    def test_sys_path_bootstrap_guard_does_not_fail(self) -> None:
+        """The mandated sys.path dedup-guard idiom should not fail (see test_python_style_import_bootstrap.py)."""
+        tree = ast.parse(
+            "import sys\n_hooks_dir = str(__file__)\n"
+            "if _hooks_dir not in sys.path:\n    sys.path.insert(0, _hooks_dir)\n"
+            "from hooks_constants.something import NAME  # noqa: E402\n"
+        )
+        assert check_imports_at_top(tree, "test.py") == []
+
 
 class TestNoEmptyLineAfterDecorators:
     """Test decorator spacing validation."""

package/hooks/validators/test_python_style_checks_import_order.py

@@ -0,0 +1,81 @@
+"""Tests for the sys.path bootstrap-guard idiom in the import-order check.
+
+Split from ``test_python_style_checks.py`` to stay under its line cap,
+matching the existing ``test_python_style_checks_decorator_gap.py`` split.
+"""
+
+import ast
+from pathlib import Path
+
+from .python_style_checks import check_imports_at_top
+
+SYS_PATH_BOOTSTRAP_GUARD_IMPORTS = """import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.something import NAME  # noqa: E402
+"""
+
+TWO_SYS_PATH_BOOTSTRAP_GUARD_BLOCKS = """import sys
+from pathlib import Path
+
+_first_dir = str(Path(__file__).resolve().parent)
+if _first_dir not in sys.path:
+    sys.path.insert(0, _first_dir)
+
+from hooks_constants.first import FIRST_NAME  # noqa: E402
+
+_second_dir = str(Path(__file__).resolve().parent.parent)
+if _second_dir not in sys.path:
+    sys.path.insert(0, _second_dir)
+
+from hooks_constants.second import SECOND_NAME  # noqa: E402
+"""
+
+UNGUARDED_SYS_PATH_INSERT_THEN_IMPORT = """import sys
+
+sys.path.insert(0, "/some/hooks/dir")
+
+import os
+"""
+
+
+class TestSysPathBootstrapGuardImportOrder:
+    """Tests pinning the sys.path bootstrap-guard exemption in import ordering."""
+
+    def test_sys_path_bootstrap_guard_passes(self) -> None:
+        """The mandated dedup-guard idiom must not flag its own import."""
+        tree = ast.parse(SYS_PATH_BOOTSTRAP_GUARD_IMPORTS)
+        violations = check_imports_at_top(tree, "test.py")
+        assert violations == []
+
+    def test_two_sys_path_bootstrap_guard_blocks_pass(self) -> None:
+        """Two separate bootstrap-guard blocks in one file both pass."""
+        tree = ast.parse(TWO_SYS_PATH_BOOTSTRAP_GUARD_BLOCKS)
+        violations = check_imports_at_top(tree, "test.py")
+        assert violations == []
+
+    def test_unguarded_sys_path_insert_still_fails(self) -> None:
+        """A bare sys.path.insert with no membership guard still counts as ordinary code.
+
+        Only the guarded idiom `check_sys_path_insert_deduplication_guard`
+        mandates is exempt. An unguarded insert is itself a violation of that
+        same guard, so an import after it stays flagged rather than rewarding
+        the shape the other gate penalizes.
+        """
+        tree = ast.parse(UNGUARDED_SYS_PATH_INSERT_THEN_IMPORT)
+        violations = check_imports_at_top(tree, "test.py")
+        assert len(violations) == 1
+        assert violations[0].line == 5
+
+    def test_code_rules_enforcer_bootstrap_produces_no_findings(self) -> None:
+        """The enforcer's own real bootstrap block goes from 29 findings to 0."""
+        enforcer_path = (
+            Path(__file__).resolve().parent.parent / "blocking" / "code_rules_enforcer.py"
+        )
+        tree = ast.parse(enforcer_path.read_text(encoding="utf-8"))
+        violations = check_imports_at_top(tree, str(enforcer_path))
+        assert violations == []

package/hooks/validators/test_python_style_helpers.py

@@ -6,11 +6,18 @@ from .python_style_helpers import (
     blank_line_for_source,
     function_start_line,
     gap_is_blank_only,
+    is_docstring_statement,
+    is_import_statement,
     iter_function_definitions,
     real_newline_lines,
     top_level_functions,
 )
 
+
+def _first_statement(source: str) -> ast.stmt:
+    """Return the first top-level statement of *source*."""
+    return ast.parse(source).body[0]
+
 TWO_FUNCTIONS = """def foo() -> None:
     pass
 
@@ -123,3 +130,31 @@ class TestBlankLineForSource:
     def test_crlf_source_returns_crlf(self) -> None:
         """CRLF source yields a CRLF blank line."""
         assert blank_line_for_source(CRLF_SOURCE) == "\r\n"
+
+
+class TestIsImportStatement:
+    """Tests pinning which statements the import-order scan treats as imports."""
+
+    def test_import_statement_is_recognized(self) -> None:
+        """A plain `import` statement is recognized."""
+        assert is_import_statement(_first_statement("import os\n")) is True
+
+    def test_from_import_statement_is_recognized(self) -> None:
+        """A `from ... import ...` statement is recognized."""
+        assert is_import_statement(_first_statement("from os import path\n")) is True
+
+    def test_assignment_is_not_an_import_statement(self) -> None:
+        """An assignment is not treated as an import."""
+        assert is_import_statement(_first_statement("X = 1\n")) is False
+
+
+class TestIsDocstringStatement:
+    """Tests pinning which statements the import-order scan treats as docstrings."""
+
+    def test_leading_string_literal_is_a_docstring(self) -> None:
+        """A bare string-literal expression statement is a docstring."""
+        assert is_docstring_statement(_first_statement('"""A module docstring."""\n')) is True
+
+    def test_assignment_is_not_a_docstring(self) -> None:
+        """An assignment is not a docstring, even with a string value."""
+        assert is_docstring_statement(_first_statement('X = "not a docstring"\n')) is False

package/hooks/validators/test_python_style_import_bootstrap.py

@@ -0,0 +1,69 @@
+"""Tests for the sys.path bootstrap-guard idiom recognizer."""
+
+import ast
+
+from .python_style_import_bootstrap import is_sys_path_bootstrap_prelude
+
+
+def _module_body(source: str) -> list[ast.stmt]:
+    """Return the top-level statements of *source* for use as a pending run."""
+    return ast.parse(source).body
+
+
+class TestIsSysPathBootstrapPrelude:
+    """Tests pinning which statement runs qualify as the bootstrap prelude."""
+
+    def test_empty_run_is_not_a_prelude(self) -> None:
+        """An empty run carries no guard, so it is not the bootstrap idiom."""
+        assert is_sys_path_bootstrap_prelude([]) is False
+
+    def test_guard_alone_is_a_prelude(self) -> None:
+        """A bare guarded insert, with no preceding assignment, still counts."""
+        body = _module_body(
+            'if "/some/dir" not in sys.path:\n    sys.path.insert(0, "/some/dir")\n'
+        )
+        assert is_sys_path_bootstrap_prelude(body) is True
+
+    def test_assignment_feeding_guard_is_a_prelude(self) -> None:
+        """The mandated `path = ...` plus guarded insert pair passes."""
+        body = _module_body(
+            "_hooks_dir = str(Path(__file__).resolve().parent)\n"
+            "if _hooks_dir not in sys.path:\n"
+            "    sys.path.insert(0, _hooks_dir)\n"
+        )
+        assert is_sys_path_bootstrap_prelude(body) is True
+
+    def test_unrelated_trailing_constant_stays_a_prelude(self) -> None:
+        """A plain constant sitting alongside a real guard does not break it.
+
+        Mirrors code_rules_enforcer.py's own bootstrap block, which tucks an
+        unrelated `_codex_apply_patch_tool_name = "apply_patch"` constant
+        right after its guarded sys.path.insert calls.
+        """
+        body = _module_body(
+            "_hooks_dir = str(Path(__file__).resolve().parent)\n"
+            "if _hooks_dir not in sys.path:\n"
+            "    sys.path.insert(0, _hooks_dir)\n"
+            '_codex_apply_patch_tool_name = "apply_patch"\n'
+        )
+        assert is_sys_path_bootstrap_prelude(body) is True
+
+    def test_plain_assignments_with_no_guard_are_not_a_prelude(self) -> None:
+        """Assignments alone, with no guard anywhere, are ordinary code."""
+        body = _module_body("MY_CONSTANT = 42\n")
+        assert is_sys_path_bootstrap_prelude(body) is False
+
+    def test_unguarded_insert_is_not_a_prelude(self) -> None:
+        """A bare sys.path.insert with no membership guard is ordinary code."""
+        body = _module_body('sys.path.insert(0, "/some/dir")\n')
+        assert is_sys_path_bootstrap_prelude(body) is False
+
+    def test_guard_alongside_a_function_def_is_not_a_prelude(self) -> None:
+        """A real statement (a function def) in the run still counts as ordinary code."""
+        body = _module_body(
+            'if "/some/dir" not in sys.path:\n'
+            '    sys.path.insert(0, "/some/dir")\n'
+            "def foo() -> None:\n"
+            "    pass\n"
+        )
+        assert is_sys_path_bootstrap_prelude(body) is False

package/hooks/validators/test_run_all_validators.py

@@ -31,6 +31,10 @@ _ASSERT_FALSE_SOURCE = (
     "    assert False, observed_total\n"
 )
 PRINT_PRODUCTION_CONTENT = 'def run() -> None:\n    print("x")\n'
+CLEAN_PROBE_SOURCE = (
+    "def add_two_numbers(first_number: int, second_number: int) -> int:\n"
+    "    return first_number + second_number\n"
+)
 ALL_PYTHON_TEST_EXEMPT_PATHS = [
     "pkg/test_helpers/worker.py",
     "pkg/conftest.py",
@@ -66,6 +70,48 @@ def test_validate_proposed_file_threads_ruff_config_from_original_path() -> None
     assert "B011" in ruff_output
 
 
+def test_validate_proposed_file_never_probes_mypy_availability() -> None:
+    """The save-path gate drops Mypy entirely; it must not even probe for it.
+
+    Mypy runs 500-1800ms cold, the largest single item on the save path by a
+    wide margin (see hooks/validators/hook_timing_harness.py). CLI/full mode
+    keeps probing it; only the save-path gate skips the probe.
+    """
+    with patch("validators.run_all_validators.check_mypy_available") as mock_check_mypy:
+        validate_proposed_file(
+            str(_VALIDATORS_DIRECTORY / "probe_target.py"), CLEAN_PROBE_SOURCE
+        )
+
+    mock_check_mypy.assert_not_called()
+
+
+def test_validate_proposed_file_never_spawns_a_validator_subprocess() -> None:
+    """The save-path gate must not spawn a ``python -m validators.<module>`` per check.
+
+    Twelve validator subprocesses cost roughly 600ms in interpreter startup
+    and import alone (see hook_timing_harness.py), for checks that measure in
+    single digits once running. CLI/full mode keeps spawning one process per
+    validator; only the save-path gate runs them in-process instead.
+    """
+    with patch("validators.run_all_validators.invoke_validator_module") as mock_invoke:
+        validate_proposed_file(
+            str(_VALIDATORS_DIRECTORY / "probe_target.py"), CLEAN_PROBE_SOURCE
+        )
+
+    mock_invoke.assert_not_called()
+
+
+def test_validate_proposed_file_still_finds_a_fast_path_violation() -> None:
+    """Dropping mypy and the per-validator subprocess must not blind the gate."""
+    all_results = validate_proposed_file(
+        str(_VALIDATORS_DIRECTORY / "probe_target.py"), PRINT_PRODUCTION_CONTENT
+    )
+
+    failed_names = {each_result.name for each_result in all_results if not each_result.passed}
+    assert failed_names, "expected at least one failing fast-path check"
+    assert "Mypy" not in failed_names
+
+
 def _validators_deny_print(file_path: str) -> bool:
     all_results = validate_proposed_file(file_path, PRINT_PRODUCTION_CONTENT)
     return any(not each_result.passed for each_result in all_results)

package/hooks/validators/test_run_all_validators_pretooluse.py

@@ -26,6 +26,8 @@ from .run_all_validators import (
     run_validators_entrypoint_subprocess,
 )
 
+pytestmark = pytest.mark.usefixtures("ephemeral_exempt_off")
+
 CONFIG_DIR_TARGET_PATH = (
     "CDP Automations/os_update_workflow/config/submission_constants.py"
 )

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.30.1",
+    "version": "2.31.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/docstring-prose-matches-implementation.md

@@ -34,7 +34,7 @@ Many deterministic shapes of this drift have Write/Edit gates in `~/.claude/hook
 
 A hook module is the sharpest case of the same rule: its docstring lead narrative and its `CORRECTIVE_MESSAGE` describe exactly the shapes the detector flags, and claim no broader trigger surface than the regex enforces.
 
-`hook_prose_detector_consistency` (PreToolUse on Write|Edit of hook modules and their `*_constants.py` companions) blocks prose that claims a trigger the detector never fires on, and names the fix.
+`hook_prose_detector_consistency` (PreToolUse on Write|Edit|MultiEdit of hook modules and their `*_constants.py` companions) blocks prose that claims a trigger the detector never fires on, and names the fix.
 
 After writing a hook, ask: would a token matching every word of this message actually trip the detector? When the message names a shape the regex skips, rewrite the message to name only what the regex catches. The path-shape case is the common overstatement — a detector that keys off a path separator must not claim it blocks an "output-key segment". The corrective message spells the rewrite.
 

package/rules/git-workflow.md

@@ -17,6 +17,8 @@ User-level rule: applies to **every** git repo that uses GitHub with `gh` (no ex
 
 **ALWAYS create PRs as DRAFT:** Use `gh pr create --draft` for ALL PRs
 
+**The pr-description-writer agent writes the body:** Spawn the `pr-description-writer` agent (Agent tool, `subagent_type` `pr-description-writer`), then publish what it returns with `--body-file`. `pr_description_writer_gate.py` (PreToolUse on Bash and PowerShell, hosted by `bash_pre_tool_use_dispatcher`) denies a `gh pr create` when the session records no such spawn. A trailing `# pr-description-skip` comment on the command opts out for a body you write yourself.
+
 ## Git Golden Rules (NON-NEGOTIABLE)
 
 1. **DRAFT BEFORE PUSH**: When pushing ANYTHING to a PR, it MUST be in draft state first

package/rules/testing.md

@@ -22,3 +22,7 @@ Incomplete mocks make it impossible to distinguish "broken code" from "missing d
 ## Tests Exercise Real Behavior
 
 Tests exercise real behavior, real data, and production code paths. A test that asserts on a stand-in for the production path proves the stand-in works.
+
+## The File-Level TDD Gate Reads Content
+
+`tdd_enforcer.py` records each candidate test's content hash at every sighting and compares that hash on the next write. A first sighting requires content that differs from HEAD.