claude-dev-env 2.18.0 → 2.20.0

package/hooks/blocking/test_code_rules_enforcer_precheck_forecast.py

@@ -2,12 +2,10 @@
 
 from __future__ import annotations
 
-import io
 import json
 import subprocess
 import sys
 from pathlib import Path
-from types import SimpleNamespace
 
 _BLOCKING_DIRECTORY = str(Path(__file__).resolve().parent)
 _HOOKS_DIRECTORY = str(Path(__file__).resolve().parent.parent)
@@ -20,11 +18,10 @@ from code_rules_enforcer import (  # noqa: E402
     main,
     validate_content,
 )
-
-code_rules_enforcer = SimpleNamespace(
-    main=main,
-    sys=sys,
-    validate_content=validate_content,
+from code_rules_enforcer_test_support import (  # noqa: E402
+    run_enforcer_cli,
+    run_precheck,
+    run_serialized_payload_entrypoint,
 )
 
 _ENFORCER_SCRIPT_PATH = Path(__file__).resolve().parent / "code_rules_enforcer.py"
@@ -57,13 +54,7 @@ def _run_enforcer_cli(
     Returns:
         The completed process carrying stdout, stderr, and the exit code.
     """
-    return subprocess.run(
-        [sys.executable, str(_ENFORCER_SCRIPT_PATH), *all_cli_arguments],
-        input="",
-        capture_output=True,
-        text=True,
-        check=False,
-    )
+    return run_enforcer_cli(_ENFORCER_SCRIPT_PATH, all_cli_arguments, None)
 
 
 def _run_precheck(
@@ -80,28 +71,15 @@ def _run_precheck(
     Returns:
         The completed process carrying the pre-check stdout, stderr, and exit code.
     """
-    return _run_enforcer_cli(["--check", candidate_path, "--as", target_path])
+    return run_precheck(Path(candidate_path), target_path, None)
 
 
 def _run_main_with_edit_payload(
     file_path: str,
     old_string: str,
     new_string: str,
-    monkeypatch: object,
-    capsys: object,
 ) -> str:
-    """Drive ``main()`` through its stdin entry point for an Edit and return stdout.
-
-    Args:
-        file_path: The on-disk path the Edit targets.
-        old_string: The Edit's ``old_string`` fragment.
-        new_string: The Edit's ``new_string`` fragment.
-        monkeypatch: The pytest fixture used to redirect ``sys.stdin``.
-        capsys: The pytest fixture used to capture the deny payload on stdout.
-
-    Returns:
-        The captured stdout, which holds the deny payload when violations fire.
-    """
+    """Drive ``main()`` through its stdin entry point for an Edit."""
     edit_payload = json.dumps(
         {
             "tool_name": "Edit",
@@ -112,13 +90,8 @@ def _run_main_with_edit_payload(
             },
         }
     )
-    getattr(monkeypatch, "setattr")(code_rules_enforcer.sys, "stdin", io.StringIO(edit_payload))
-    try:
-        code_rules_enforcer.main([])
-    except SystemExit:
-        pass
-    captured = getattr(capsys, "readouterr")()
-    return captured.out
+    captured_stdout, _exit_code = run_serialized_payload_entrypoint(main, edit_payload)
+    return captured_stdout
 
 
 def test_precheck_stream_parameter_carries_no_banned_noun() -> None:
@@ -130,9 +103,7 @@ def test_precheck_stream_parameter_carries_no_banned_noun() -> None:
     banned-noun check fires. Scanning the enforcer source at a production path
     proves the introduced stream parameter is free of that violation."""
     enforcer_source = _ENFORCER_SCRIPT_PATH.read_text(encoding="utf-8")
-    issues = code_rules_enforcer.validate_content(
-        enforcer_source, "/project/src/code_rules_enforcer.py"
-    )
+    issues = validate_content(enforcer_source, "/project/src/code_rules_enforcer.py")
     banned_noun_issues = [
         each_issue
         for each_issue in issues
@@ -234,8 +205,6 @@ def test_precheck_missing_candidate_errors_on_stderr_without_traceback(
 
 def test_edit_deny_reason_includes_forecast_and_precheck_hint(
     tmp_path_factory: object,
-    monkeypatch: object,
-    capsys: object,
 ) -> None:
     """An Edit whose new_string introduces a violation on a file that already
     contains a separate violation elsewhere blocks on the fragment violation and
@@ -244,9 +213,7 @@ def test_edit_deny_reason_includes_forecast_and_precheck_hint(
     production_directory = getattr(tmp_path_factory, "mktemp")("production_pkg")
     untouched_print_violation = _UNTOUCHED_PRINT_VIOLATION_SOURCE
     clean_before = _CLEAN_FRAGMENT_BEFORE
-    introduces_banned_noun_after = (
-        "def short_helper() -> int:\n    output = 0\n    return output\n"
-    )
+    introduces_banned_noun_after = "def short_helper() -> int:\n    output = 0\n    return output\n"
     on_disk_before = untouched_print_violation + "\n" + clean_before
     source_file = production_directory / "production_module.py"
     source_file.write_text(on_disk_before, encoding="utf-8")
@@ -254,8 +221,6 @@ def test_edit_deny_reason_includes_forecast_and_precheck_hint(
         str(source_file),
         clean_before,
         introduces_banned_noun_after,
-        monkeypatch,
-        capsys,
     )
     deny_payload = json.loads(stdout)
     reason = deny_payload["hookSpecificOutput"]["permissionDecisionReason"]
@@ -263,9 +228,7 @@ def test_edit_deny_reason_includes_forecast_and_precheck_hint(
     assert "output" in blocking_section, (
         f"fragment-introduced banned-noun must block, got reason: {reason!r}"
     )
-    assert forecast_section != "", (
-        f"forecast section must be present, got reason: {reason!r}"
-    )
+    assert forecast_section != "", f"forecast section must be present, got reason: {reason!r}"
     assert "Library print()" in forecast_section, (
         f"forecast must name the untouched print violation, got reason: {reason!r}"
     )
@@ -274,8 +237,6 @@ def test_edit_deny_reason_includes_forecast_and_precheck_hint(
 
 def test_edit_clean_fragment_on_dirty_file_produces_no_deny_payload(
     tmp_path_factory: object,
-    monkeypatch: object,
-    capsys: object,
 ) -> None:
     """A clean Edit fragment on a file that is dirty elsewhere must not block —
     the forecast never converts a clean-fragment edit into a deny."""
@@ -290,8 +251,6 @@ def test_edit_clean_fragment_on_dirty_file_produces_no_deny_payload(
         str(source_file),
         clean_before,
         clean_after,
-        monkeypatch,
-        capsys,
     )
     assert stdout == "", (
         f"a clean fragment on a dirty file must not produce a deny payload, got stdout: {stdout!r}"
@@ -300,8 +259,6 @@ def test_edit_clean_fragment_on_dirty_file_produces_no_deny_payload(
 
 def test_every_deny_reason_carries_the_precheck_hint(
     tmp_path_factory: object,
-    monkeypatch: object,
-    capsys: object,
 ) -> None:
     """A deny with no forecast still appends the pre-check hint to the reason."""
     production_directory = getattr(tmp_path_factory, "mktemp")("production_pkg")
@@ -313,8 +270,6 @@ def test_every_deny_reason_carries_the_precheck_hint(
         str(source_file),
         clean_before,
         introduces_violation_after,
-        monkeypatch,
-        capsys,
     )
     deny_payload = json.loads(stdout)
     reason = deny_payload["hookSpecificOutput"]["permissionDecisionReason"]
@@ -333,8 +288,6 @@ def test_every_deny_reason_carries_the_precheck_hint(
 
 def test_forecast_skipped_when_edit_prior_is_unreconstructable(
     tmp_path_factory: object,
-    monkeypatch: object,
-    capsys: object,
 ) -> None:
     """An Edit whose old_string is absent from the file has no reliable prior to
     diff against, so the full-file forecast must not run: a pre-existing inline
@@ -350,8 +303,6 @@ def test_forecast_skipped_when_edit_prior_is_unreconstructable(
         str(source_file),
         absent_old,
         introduces_print_new,
-        monkeypatch,
-        capsys,
     )
     deny_payload = json.loads(stdout)
     reason = deny_payload["hookSpecificOutput"]["permissionDecisionReason"]
@@ -363,8 +314,6 @@ def test_forecast_skipped_when_edit_prior_is_unreconstructable(
 
 def test_forecast_omits_the_fragment_introduced_violation(
     tmp_path_factory: object,
-    monkeypatch: object,
-    capsys: object,
 ) -> None:
     """An Edit that introduces the file's only print() blocks on it without the
     forecast re-listing that same violation under its full-file line number."""
@@ -378,8 +327,6 @@ def test_forecast_omits_the_fragment_introduced_violation(
         str(source_file),
         _CLEAN_FRAGMENT_BEFORE,
         introduces_print_after,
-        monkeypatch,
-        capsys,
     )
     deny_payload = json.loads(stdout)
     reason = deny_payload["hookSpecificOutput"]["permissionDecisionReason"]
@@ -454,9 +401,7 @@ def test_precheck_strips_candidate_byte_order_mark_before_validation(
     staging_directory = getattr(tmp_path_factory, "mktemp")("staging")
     production_directory = getattr(tmp_path_factory, "mktemp")("production_pkg")
     candidate_file = staging_directory / "candidate.py"
-    candidate_file.write_text(
-        "\ufeff" + _VIOLATING_PRODUCTION_SOURCE, encoding="utf-8"
-    )
+    candidate_file.write_text("\ufeff" + _VIOLATING_PRODUCTION_SOURCE, encoding="utf-8")
     target_path = str(production_directory / "production_module.py")
     completed = _run_precheck(str(candidate_file), target_path)
     assert completed.returncode == 1, (
@@ -478,9 +423,7 @@ def test_precheck_strips_every_leading_byte_order_mark_before_validation(
     staging_directory = getattr(tmp_path_factory, "mktemp")("staging")
     production_directory = getattr(tmp_path_factory, "mktemp")("production_pkg")
     candidate_file = staging_directory / "candidate.py"
-    candidate_file.write_text(
-        "\ufeff\ufeff" + _VIOLATING_PRODUCTION_SOURCE, encoding="utf-8"
-    )
+    candidate_file.write_text("\ufeff\ufeff" + _VIOLATING_PRODUCTION_SOURCE, encoding="utf-8")
     target_path = str(production_directory / "production_module.py")
     completed = _run_precheck(str(candidate_file), target_path)
     assert completed.returncode == 1, (

package/hooks/blocking/test_code_rules_enforcer_scratchpad.py

@@ -1,7 +1,6 @@
 """Tests for the session-scratchpad exemption wired into code_rules_enforcer.main."""
 
 import importlib.util
-import io
 import json
 import os
 import sys
@@ -11,6 +10,13 @@ from types import ModuleType
 
 import pytest
 
+_HOOKS_DIRECTORY = str(Path(__file__).resolve().parent.parent)
+if _HOOKS_DIRECTORY not in sys.path:
+    sys.path.insert(0, _HOOKS_DIRECTORY)
+from blocking import _path_setup  # noqa: F401
+
+from code_rules_enforcer_test_support import run_serialized_payload_entrypoint
+
 ENFORCER_PATH = Path(__file__).parent / "code_rules_enforcer.py"
 FIXED_USER_ID = 6070
 WORKING_DIRECTORY = "/home/user/project"
@@ -55,19 +61,11 @@ def _write_payload(target: Path) -> dict[str, object]:
     }
 
 
-def _run_main(
-    monkeypatch: pytest.MonkeyPatch, payload: dict[str, object]
-) -> tuple[int | None, str]:
-    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps(payload)))
-    captured_stdout = io.StringIO()
-    monkeypatch.setattr(sys, "stdout", captured_stdout)
-    exit_code: int | None = None
-    try:
-        _ENFORCER.main([])
-    except SystemExit as raised_exit:
-        raw_code = raised_exit.code
-        exit_code = raw_code if isinstance(raw_code, int) else None
-    return exit_code, captured_stdout.getvalue()
+def _run_main(payload_by_key: dict[str, object]) -> tuple[int | None, str]:
+    captured_stdout, exit_code = run_serialized_payload_entrypoint(
+        _ENFORCER.main, json.dumps(payload_by_key)
+    )
+    return exit_code, captured_stdout
 
 
 def _decision_from(stdout_text: str) -> str | None:
@@ -84,7 +82,7 @@ def test_scratchpad_write_is_exempt_from_code_rules(
     monkeypatch.setenv("CLAUDE_CODE_RULES_DISABLE_EPHEMERAL_EXEMPT", "1")
     throwaway_script = scratchpad_directory / "one_off_probe.py"
 
-    exit_code, stdout_text = _run_main(monkeypatch, _write_payload(throwaway_script))
+    exit_code, stdout_text = _run_main(_write_payload(throwaway_script))
 
     assert exit_code == 0
     assert _decision_from(stdout_text) != "deny"
@@ -99,7 +97,7 @@ def test_identical_non_scratchpad_write_is_still_blocked(
     outside_directory.mkdir(parents=True)
     production_module = outside_directory / "one_off_probe.py"
 
-    exit_code, stdout_text = _run_main(monkeypatch, _write_payload(production_module))
+    exit_code, stdout_text = _run_main(_write_payload(production_module))
 
     assert exit_code == 0
     assert _decision_from(stdout_text) == "deny"

package/hooks/blocking/test_code_rules_enforcer_split_entry_2.py

@@ -2,12 +2,13 @@
 
 from __future__ import annotations
 
-import io
 import json
 import sys
 from pathlib import Path
 from types import SimpleNamespace
 
+import pytest
+
 _BLOCKING_DIRECTORY = str(Path(__file__).resolve().parent)
 _HOOKS_DIRECTORY = str(Path(__file__).resolve().parent.parent)
 if _BLOCKING_DIRECTORY not in sys.path:
@@ -23,6 +24,9 @@ from code_rules_enforcer import (  # noqa: E402
     prior_and_post_edit_content,
     validate_content,
 )
+from code_rules_enforcer_test_support import (  # noqa: E402
+    run_serialized_payload_entrypoint,
+)
 
 code_rules_enforcer = SimpleNamespace(
     FUNCTION_LENGTH_BLOCKING_THRESHOLD=FUNCTION_LENGTH_BLOCKING_THRESHOLD,
@@ -35,9 +39,7 @@ code_rules_enforcer = SimpleNamespace(
 
 def _oversized_function_source(name: str) -> str:
     body_line_count = code_rules_enforcer.FUNCTION_LENGTH_BLOCKING_THRESHOLD - 1
-    body_lines = [
-        f"    bound_{each_index} = {each_index}" for each_index in range(body_line_count)
-    ]
+    body_lines = [f"    bound_{each_index} = {each_index}" for each_index in range(body_line_count)]
     return f"def {name}() -> None:\n" + "\n".join(body_lines) + "\n"
 
 
@@ -45,21 +47,8 @@ def _run_main_with_edit_payload(
     file_path: str,
     old_string: str,
     new_string: str,
-    monkeypatch: object,
-    capsys: object,
 ) -> str:
-    """Drive ``main()`` through its stdin entry point for an Edit and return stdout.
-
-    Args:
-        file_path: The on-disk path the Edit targets.
-        old_string: The Edit's ``old_string`` fragment.
-        new_string: The Edit's ``new_string`` fragment.
-        monkeypatch: The pytest fixture used to redirect ``sys.stdin``.
-        capsys: The pytest fixture used to capture the deny payload on stdout.
-
-    Returns:
-        The captured stdout, which holds the deny payload when violations fire.
-    """
+    """Drive ``main()`` through its stdin entry point for an Edit."""
     edit_payload = json.dumps(
         {
             "tool_name": "Edit",
@@ -70,13 +59,10 @@ def _run_main_with_edit_payload(
             },
         }
     )
-    getattr(monkeypatch, "setattr")(code_rules_enforcer.sys, "stdin", io.StringIO(edit_payload))
-    try:
-        code_rules_enforcer.main([])
-    except SystemExit:
-        pass
-    captured = getattr(capsys, "readouterr")()
-    return captured.out
+    captured_stdout, _exit_code = run_serialized_payload_entrypoint(
+        code_rules_enforcer.main, edit_payload
+    )
+    return captured_stdout
 
 
 def test_banned_noun_word_keeps_in_scope_binding_among_untouched_ones() -> None:
@@ -85,8 +71,7 @@ def test_banned_noun_word_keeps_in_scope_binding_among_untouched_ones() -> None:
     binding while leaving the untouched bindings out of scope."""
     leading_count = 5
     leading_bindings = "".join(
-        f"LEADING_{each_index}_RESULT_PATH = {each_index}\n"
-        for each_index in range(leading_count)
+        f"LEADING_{each_index}_RESULT_PATH = {each_index}\n" for each_index in range(leading_count)
     )
     target_before = "PLACEHOLDER_NAME = 0\n"
     target_after = "INTRODUCED_RESULT_PATH = 0\n"
@@ -99,9 +84,9 @@ def test_banned_noun_word_keeps_in_scope_binding_among_untouched_ones() -> None:
         full_file_content=post_edit_full_file,
         prior_full_file_content=prior_full_file,
     )
-    assert any(
-        "INTRODUCED_RESULT_PATH" in each_issue for each_issue in issues
-    ), f"in-scope banned-noun past the cap window must still block, got: {issues!r}"
+    assert any("INTRODUCED_RESULT_PATH" in each_issue for each_issue in issues), (
+        f"in-scope banned-noun past the cap window must still block, got: {issues!r}"
+    )
 
 
 def test_banned_noun_edit_drops_untouched_out_of_scope_binding() -> None:
@@ -122,9 +107,9 @@ def test_banned_noun_edit_drops_untouched_out_of_scope_binding() -> None:
         full_file_content=post_edit_full_file,
         prior_full_file_content=prior_full_file,
     )
-    assert not any(
-        "RESULT_PATH" in each_issue for each_issue in issues
-    ), f"untouched banned-noun bindings must stay out of scope, got: {issues!r}"
+    assert not any("RESULT_PATH" in each_issue for each_issue in issues), (
+        f"untouched banned-noun bindings must stay out of scope, got: {issues!r}"
+    )
 
 
 def test_banned_noun_edit_keeps_touched_binding_in_scope() -> None:
@@ -144,9 +129,9 @@ def test_banned_noun_edit_keeps_touched_binding_in_scope() -> None:
         full_file_content=post_edit_full_file,
         prior_full_file_content=prior_full_file,
     )
-    assert any(
-        "INTRODUCED_RESULT_PATH" in each_issue for each_issue in issues
-    ), f"introduced banned-noun binding must block, got: {issues!r}"
+    assert any("INTRODUCED_RESULT_PATH" in each_issue for each_issue in issues), (
+        f"introduced banned-noun binding must block, got: {issues!r}"
+    )
 
 
 def test_banned_noun_edit_does_not_reflag_param_when_unrelated_body_line_changes() -> None:
@@ -171,9 +156,9 @@ def test_banned_noun_edit_does_not_reflag_param_when_unrelated_body_line_changes
         full_file_content=post_edit_full_file,
         prior_full_file_content=prior_full_file,
     )
-    assert not any(
-        "canned_results" in each_issue for each_issue in issues
-    ), f"pre-existing param must not re-flag on unrelated body edit, got: {issues!r}"
+    assert not any("canned_results" in each_issue for each_issue in issues), (
+        f"pre-existing param must not re-flag on unrelated body edit, got: {issues!r}"
+    )
 
 
 def test_unreadable_prior_yields_no_prior_and_no_reconstruction() -> None:
@@ -191,13 +176,13 @@ def test_unreadable_prior_yields_no_prior_and_no_reconstruction() -> None:
 
 
 def test_edit_with_missing_old_string_runs_whole_file_against_on_disk_content(
-    tmp_path_factory: object, monkeypatch: object, capsys: object,
+    tmp_path_factory: pytest.TempPathFactory,
 ) -> None:
     """When an Edit's old_string is absent from the file, ``prior_and_post_edit_content``
     yields ``(None, None)``; ``main()`` must analyze the real on-disk file whole-file
     rather than the new_string fragment, so an oversized function elsewhere in the
     file is still reported with its true line numbers."""
-    production_directory = getattr(tmp_path_factory, "mktemp")("production_pkg")
+    production_directory = tmp_path_factory.mktemp("production_pkg")
     untouched_long_function = _oversized_function_source("untouched_long")
     short_helper = "def short_helper() -> int:\n    return 1\n"
     on_disk_content = untouched_long_function + "\n" + short_helper
@@ -206,7 +191,9 @@ def test_edit_with_missing_old_string_runs_whole_file_against_on_disk_content(
     absent_fragment_old = "def absent_function() -> int:\n    return 0\n"
     short_fragment_new = "def absent_function() -> int:\n    return 2\n"
     stdout = _run_main_with_edit_payload(
-        str(source_file), absent_fragment_old, short_fragment_new, monkeypatch, capsys,
+        str(source_file),
+        absent_fragment_old,
+        short_fragment_new,
     )
     assert "untouched_long" in stdout, (
         "an unreconstructable Edit must fall back to whole-file on-disk analysis, "
@@ -215,13 +202,13 @@ def test_edit_with_missing_old_string_runs_whole_file_against_on_disk_content(
 
 
 def test_edit_with_unreadable_file_does_not_analyze_fragment_as_whole_file(
-    tmp_path_factory: object, monkeypatch: object, capsys: object,
+    tmp_path_factory: pytest.TempPathFactory,
 ) -> None:
     """When the on-disk file cannot be read, no well-defined post-edit content
     exists; ``main()`` must exit cleanly rather than analyze the new_string
     fragment as if it were the whole file, so the fragment's own function-length
     violation does not surface as a deny payload."""
-    production_directory = getattr(tmp_path_factory, "mktemp")("production_pkg")
+    production_directory = tmp_path_factory.mktemp("production_pkg")
     missing_path = str(production_directory / "never_created.py")
     oversized_fragment_old = "def grows() -> int:\n    return 0\n"
     oversized_fragment_new = _oversized_function_source("grows")
@@ -229,8 +216,6 @@ def test_edit_with_unreadable_file_does_not_analyze_fragment_as_whole_file(
         missing_path,
         oversized_fragment_old,
         oversized_fragment_new,
-        monkeypatch,
-        capsys,
     )
     assert stdout == "", (
         "an unreadable Edit target has no well-defined whole-file content, so the "

package/hooks/blocking/test_code_rules_enforcer_stage.py

@@ -0,0 +1,192 @@
+"""Test stage ownership for the code-rules enforcer entrypoint."""
+
+from __future__ import annotations
+
+import io
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_BLOCKING_DIRECTORY = str(Path(__file__).resolve().parent)
+_HOOKS_DIRECTORY = str(Path(__file__).resolve().parent.parent)
+_PR_LOOP_SCRIPTS_DIRECTORY = str(
+    Path(__file__).resolve().parents[2] / "_shared" / "pr-loop" / "scripts"
+)
+if _BLOCKING_DIRECTORY not in sys.path:
+    sys.path.insert(0, _BLOCKING_DIRECTORY)
+if _HOOKS_DIRECTORY not in sys.path:
+    sys.path.insert(0, _HOOKS_DIRECTORY)
+if _PR_LOOP_SCRIPTS_DIRECTORY not in sys.path:
+    sys.path.insert(0, _PR_LOOP_SCRIPTS_DIRECTORY)
+
+from code_rules_enforcer import (  # noqa: E402
+    _fragment_or_deferred_check,
+    main,
+    validate_content,
+)
+from code_rules_gate_parts import gate_running  # noqa: E402
+from code_rules_gate_parts.tests._repo_test_helpers import (  # noqa: E402
+    init_repository,
+    write_commit_and_stage_change,
+)
+
+
+PRODUCTION_FILE_PATH = "packages/app/services.py"
+ENFORCER_SCRIPT_PATH = Path(__file__).with_name("code_rules_enforcer.py")
+
+
+def _write_payload(file_path: str, source: str) -> str:
+    return json.dumps(
+        {
+            "tool_name": "Write",
+            "tool_input": {"file_path": file_path, "content": source},
+        }
+    )
+
+
+def _run_write_stage(
+    file_path: str,
+    source: str,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> str:
+    payload = _write_payload(file_path, source)
+    monkeypatch.setattr(sys, "stdin", io.StringIO(payload))
+    try:
+        main([])
+    except SystemExit:
+        pass
+    return capsys.readouterr().out
+def _run_precheck_stage(candidate_path: Path, target_path: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [
+            sys.executable,
+            str(ENFORCER_SCRIPT_PATH),
+            "--check",
+            str(candidate_path),
+            "--as",
+            target_path,
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+def test_edit_stage_baselines_the_new_fragment_against_the_old_fragment() -> None:
+    all_seen_contents: list[str] = []
+
+    def record_check(content: str, file_path: str) -> list[str]:
+        all_seen_contents.append(content)
+        if "introduced" in content:
+            return [f"finding in {file_path}"]
+        return []
+
+    all_issues = _fragment_or_deferred_check(
+        record_check,
+        "existing fragment",
+        "introduced fragment",
+        PRODUCTION_FILE_PATH,
+        defer_scope_to_caller=False,
+    )
+
+    assert all_seen_contents == ["introduced fragment", "existing fragment"]
+    assert all_issues == [f"finding in {PRODUCTION_FILE_PATH}"]
+
+
+def test_commit_stage_owns_scope_and_scans_the_complete_candidate_once() -> None:
+    all_seen_contents: list[str] = []
+
+    def record_check(content: str, file_path: str) -> list[str]:
+        all_seen_contents.append(content)
+        return [f"finding in {file_path}"]
+
+    all_issues = _fragment_or_deferred_check(
+        record_check,
+        "HEAD content",
+        "staged candidate",
+        PRODUCTION_FILE_PATH,
+        defer_scope_to_caller=True,
+    )
+
+    assert all_seen_contents == ["staged candidate"]
+    assert all_issues == [f"finding in {PRODUCTION_FILE_PATH}"]
+
+
+def test_write_stage_runs_the_real_entrypoint_and_reports_a_deny_payload(
+    tmp_path_factory: pytest.TempPathFactory,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    staging_directory = tmp_path_factory.mktemp("stage")
+    target_path = str(staging_directory / "service.py")
+    source = "def process_data() -> None:\n    print('payload')\n"
+
+    captured_stdout = _run_write_stage(target_path, source, monkeypatch, capsys)
+
+    deny_payload = json.loads(captured_stdout)
+    deny_reason = deny_payload["hookSpecificOutput"]["permissionDecisionReason"]
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert "process_data" in deny_reason
+
+
+def test_write_stage_allows_a_clean_candidate_through_the_real_entrypoint(
+    tmp_path_factory: pytest.TempPathFactory,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    staging_directory = tmp_path_factory.mktemp("stage")
+    target_path = str(staging_directory / "service.py")
+    source = "def calculate_total() -> int:\n    return 0\n"
+
+    captured_stdout = _run_write_stage(target_path, source, monkeypatch, capsys)
+
+    assert captured_stdout == ""
+
+
+def test_precheck_stage_runs_the_cli_and_uses_the_declared_target_path(
+    tmp_path_factory: pytest.TempPathFactory,
+) -> None:
+    staging_directory = tmp_path_factory.mktemp("stage")
+    candidate_path = staging_directory / "candidate.py"
+    candidate_path.write_text(
+        "def process_data() -> None:\n    print('payload')\n",
+        encoding="utf-8",
+    )
+    target_path = str(staging_directory / "service.py")
+
+    completed_process = _run_precheck_stage(candidate_path, target_path)
+
+    assert completed_process.returncode == 1
+    assert "process_data" in completed_process.stdout
+def test_gate_caller_scans_staged_content_with_commit_stage_scope(
+    tmp_path: Path,
+) -> None:
+    repository_root = tmp_path / "repository"
+    repository_root.mkdir()
+    init_repository(repository_root)
+    committed_source = "def calculate_total() -> int:\n    return 0\n"
+    staged_source = (
+        "def calculate_total() -> int:\n"
+        "    total = 9999\n"
+        "    return total\n"
+    )
+    file_path = write_commit_and_stage_change(
+        repository_root,
+        "service.py",
+        committed_source,
+        staged_source,
+    )
+
+    all_partitioned_violations = gate_running._scoped_violations_for_file(
+        validate_content=validate_content,
+        resolved_path=file_path,
+        repository_root=repository_root,
+        all_added_lines_for_file={2, 3},
+        should_read_staged_content=True,
+    )
+
+    assert all_partitioned_violations is not None
+    all_blocking_violations, _all_advisory_violations = all_partitioned_violations
+    assert any("9999" in each_issue for each_issue in all_blocking_violations)