claude-dev-env 2.8.0 → 2.10.0

package/hooks/blocking/state_description_blocker.py

@@ -20,6 +20,9 @@ if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
 from blocking.code_rules_shared import is_ephemeral_path  # noqa: E402
+from blocking.config.prose_style_enforcement_constants import (  # noqa: E402
+    prose_style_enforcement_enabled_in_environment,
+)
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin  # noqa: E402
 from hooks_constants.state_description_blocker_constants import (  # noqa: E402
@@ -278,7 +281,8 @@ def evaluate(payload_by_key: dict[str, object]) -> str | None:
 
     Applies the same tool-name gate, file-extension gate, content selection, and
     pattern scan the standalone hook applies. Returns the deny-reason text when a
-    historical phrase is found, or None to allow.
+    historical phrase is found, or None to allow. Opinionated prose enforcement
+    is default-off via ``prose_style_enforcement_enabled_in_environment()``.
 
     Args:
         payload_by_key: The PreToolUse payload with tool_name and tool_input.
@@ -287,6 +291,8 @@ def evaluate(payload_by_key: dict[str, object]) -> str | None:
         The permissionDecisionReason text when the write is denied, or None when
         the write is allowed.
     """
+    if not prose_style_enforcement_enabled_in_environment():
+        return None
     raw_tool_name = payload_by_key.get("tool_name", "")
     tool_name = raw_tool_name if isinstance(raw_tool_name, str) else ""
     if tool_name not in ("Write", "Edit"):

package/hooks/blocking/tdd_enforcer.py

@@ -17,6 +17,7 @@ try:
         if each_bootstrap_directory not in sys.path:
             sys.path.insert(0, each_bootstrap_directory)
     from code_rules_shared import (
+        is_agent_home_tooling,
         is_ephemeral_script_path,
         is_under_session_scratchpad,
     )
@@ -40,6 +41,11 @@ def _is_session_scratchpad_write(file_path: str, input_data: dict) -> bool:
     return is_under_session_scratchpad(file_path, input_data)
 
 
+def _is_agent_home_tooling_write(file_path: str) -> bool:
+    """A coding agent's own home-directory tooling is outside the TDD gate."""
+    return is_agent_home_tooling(file_path)
+
+
 production_extensions = path_classification.production_extensions
 skip_extensions = path_classification.skip_extensions
 _is_inside_dotclaude_segment = path_classification._is_inside_dotclaude_segment
@@ -69,6 +75,8 @@ def _resolve_payload(input_data: dict) -> tuple[str, dict, str]:
 def _is_silently_skipped(file_path: str, extension: str, path: Path) -> bool:
     if _is_inside_dotclaude_segment(file_path) or is_ephemeral_script_path(file_path):
         return True
+    if _is_agent_home_tooling_write(file_path):
+        return True
     if extension in skip_extensions():
         return True
     if extension not in production_extensions():

package/hooks/blocking/test__path_setup.py

@@ -37,3 +37,31 @@ def test_importing_path_setup_puts_the_hooks_directory_on_sys_path() -> None:
     )
     assert completed.returncode == 0, completed.stderr
     assert completed.stdout.strip() == "ok"
+
+
+def test_importing_path_setup_puts_the_blocking_directory_on_sys_path() -> None:
+    """A module reached through the package finds its own directory on sys.path.
+
+    ``code_rules_shared`` imports both ``hooks_constants`` (a hooks-directory
+    package) and its blocking-directory siblings, so the bootstrap must place
+    both roots. Only the hooks directory is on PYTHONPATH here, so the blocking
+    entry can only come from the bootstrap itself.
+    """
+    driver = (
+        "import sys\n"
+        "from blocking import _path_setup\n"
+        "from pathlib import Path\n"
+        "blocking_dir = str(Path(_path_setup.__file__).resolve().parent)\n"
+        "assert blocking_dir in sys.path, blocking_dir\n"
+        "print('ok')\n"
+    )
+    subprocess_environment = {**os.environ, "PYTHONPATH": str(_HOOKS_DIR)}
+    completed = subprocess.run(
+        [sys.executable, "-c", driver],
+        check=False,
+        capture_output=True,
+        text=True,
+        env=subprocess_environment,
+    )
+    assert completed.returncode == 0, completed.stderr
+    assert completed.stdout.strip() == "ok"

package/hooks/blocking/test_code_rules_enforcer_agent_home_tooling.py

@@ -0,0 +1,99 @@
+"""Agent-home tooling exemption tests for the classifier and the enforcer.
+
+A coding agent installs its own helper scripts under a dot-directory in the
+user's home — ``~/.grok/runs/`` sits beside the already-exempt
+``~/.claude/hooks/``. That tree is vendored tooling rather than project code,
+so the repository code rules do not govern it::
+
+    /home/example/.grok/runs/worktree-health/health.py  -> exempt
+    C:/dev/my-project/src/grokking.py               -> governed
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from blocking import _path_setup  # noqa: F401  (pins this checkout ahead of sibling worktrees)
+from blocking.code_rules_shared import is_agent_home_tooling, is_ephemeral_path
+
+_ENFORCER_SCRIPT = Path(__file__).resolve().parent / "code_rules_enforcer.py"
+
+_VIOLATING_PRODUCTION_SOURCE = "def process_data(payload: str) -> None:\n    print(payload)\n"
+
+
+def _check_as(candidate_source: str, target_path: str) -> subprocess.CompletedProcess[str]:
+    """Run the enforcer's pre-check on a candidate judged as another path.
+
+    Args:
+        candidate_source: Python source written to the candidate file.
+        target_path: Destination path the candidate is judged as.
+
+    Returns:
+        The completed process carrying stdout, stderr, and the exit code.
+    """
+    with tempfile.TemporaryDirectory() as scratch:
+        candidate = Path(scratch) / "candidate.py"
+        candidate.write_text(candidate_source, encoding="utf-8")
+        return subprocess.run(
+            [sys.executable, str(_ENFORCER_SCRIPT), "--check", str(candidate), "--as", target_path],
+            input="",
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+
+
+def test_posix_agent_home_path_is_agent_tooling() -> None:
+    assert is_agent_home_tooling("/home/example/.grok/runs/worktree-health/health.py")
+
+
+def test_windows_agent_home_path_is_agent_tooling() -> None:
+    assert is_agent_home_tooling(r"C:\Users\example\.grok\runs\worktree-health\health.py")
+
+
+def test_any_depth_under_the_agent_home_is_agent_tooling() -> None:
+    assert is_agent_home_tooling("/home/example/.grok/hooks/force_worktree.py")
+
+
+def test_ordinary_project_code_is_not_agent_tooling() -> None:
+    assert not is_agent_home_tooling("/dev/my-project/src/service.py")
+
+
+def test_a_filename_spelled_like_the_agent_is_not_agent_tooling() -> None:
+    assert not is_agent_home_tooling("/dev/my-project/src/grokking.py")
+
+
+def test_a_directory_without_the_leading_dot_is_not_agent_tooling() -> None:
+    assert not is_agent_home_tooling("/dev/my-project/grok/runner.py")
+
+
+def test_an_empty_path_is_not_agent_tooling() -> None:
+    assert not is_agent_home_tooling("")
+
+
+def test_agent_home_path_is_exempt_from_the_repository_gates() -> None:
+    assert is_ephemeral_path("/home/example/.grok/runs/worktree-health/health.py")
+
+
+def test_project_code_is_not_exempt_from_the_repository_gates() -> None:
+    assert not is_ephemeral_path("/dev/my-project/src/service.py")
+
+
+def test_enforcer_allows_violating_source_under_the_agent_home() -> None:
+    target = os.path.join("/home/example", ".grok", "runs", "worktree-health", "health.py")
+
+    completed = _check_as(_VIOLATING_PRODUCTION_SOURCE, target)
+
+    assert completed.returncode == 0, completed.stdout + completed.stderr
+
+
+def test_enforcer_still_flags_the_same_source_in_a_project_path() -> None:
+    target = os.path.join("/dev/my-project", "src", "service.py")
+
+    completed = _check_as(_VIOLATING_PRODUCTION_SOURCE, target)
+
+    assert completed.returncode != 0

package/hooks/blocking/test_code_rules_enforcer_docstring_args_span_scope.py

@@ -1,13 +1,15 @@
-"""Tests for check_docstring_args_single_line_scope_vs_span — Category O6 drift.
-
-A docstring Args: entry that scopes a finding to one named line ("only when its
-block-anchor line is among the changed lines") while the body builds a range()
-span and routes it through a span-intersection scoper claims a narrower scope
-than the code applies. The body blocks when ANY line of the span is among the
-changed lines, so an edit touching a non-anchor line of the span still blocks —
-contradicting the single-line Args sentence. This is the deterministic slice of
-Category O6 (free-form docstring-vs-implementation drift) for an Args entry whose
-single-line scope claim disagrees with a span-intersection body.
+"""Span-scope tests for docstring checks.
+
+Covers two surfaces:
+
+1. ``check_docstring_args_single_line_scope_vs_span`` (Category O6) — an Args
+   entry that claims single-line (block-anchor) scope while the body builds a
+   multi-line span and routes it through span intersection.
+
+2. Changed-span grading for ``check_docstring_runon_sentence`` and
+   ``check_docstring_prose_wall_without_illustration`` (issue #237) — far-away
+   no-op grandfathering, introduced-violation blocking, and
+   ``defer_scope_to_caller`` pass-through.
 """
 
 from __future__ import annotations
@@ -201,3 +203,223 @@ def test_hook_infrastructure_is_not_exempt() -> None:
     assert (
         len(check_docstring_args_single_line_scope_vs_span(content, HOOK_INFRASTRUCTURE_PATH)) == 1
     )
+
+# ---------------------------------------------------------------------------
+# Changed-span grading for the two whole-file docstring checks (issue #237 / P-41)
+# check_docstring_runon_sentence and check_docstring_prose_wall_without_illustration
+# ---------------------------------------------------------------------------
+
+
+def check_docstring_runon_sentence(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    return code_rules_enforcer.check_docstring_runon_sentence(
+        content, file_path, all_changed_lines, defer_scope_to_caller
+    )
+
+
+def check_docstring_prose_wall_without_illustration(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    return code_rules_enforcer.check_docstring_prose_wall_without_illustration(
+        content, file_path, all_changed_lines, defer_scope_to_caller
+    )
+
+
+_CLEAN_HELPER_TAIL = (
+    "\n"
+    "def clean_helper() -> str:\n"
+    '    """Return a short status token for the board.\n'
+    "\n"
+    "    Each call names one vessel and its final port.\n"
+    '    """\n'
+    '    return "ok"\n'
+)
+
+
+def _module_with_far_away_runon_and_clean_helper() -> str:
+    return (
+        '"""Owns the SIGINT install/restore/installability check, the atexit terminal-record\n'
+        "registration, and the interrupted-run finalizer — the non-promoter-specific\n"
+        "machinery that brackets a run so the JSONL artifact always carries a terminal\n"
+        "record and an in-flight theme record on interrupt.\n"
+        '"""\n'
+        + _CLEAN_HELPER_TAIL
+    )
+
+
+def _module_with_far_away_prose_wall_and_clean_helper() -> str:
+    return (
+        '"""Assemble the nightly voyage tally from the harbor scans.\n'
+        "\n"
+        "A scan names one vessel and where it dropped anchor.\n"
+        "The tally walks the scans in arrival order and keeps that order.\n"
+        "A calm voyage ends well for every vessel it carried.\n"
+        "A halted voyage marks the vessel it was near when the storm arrived.\n"
+        "A wrecked voyage marks the vessel that sank and stops the walk there.\n"
+        "The tally groups the vessels by their final port for the harbor.\n"
+        "The harbor reads the tally and sees every arrival at a glance.\n"
+        '"""\n'
+        + _CLEAN_HELPER_TAIL
+    )
+
+
+def test_runon_far_away_no_op_is_grandfathered() -> None:
+    content = _module_with_far_away_runon_and_clean_helper()
+    clean_helper_line = content.splitlines().index("def clean_helper() -> str:") + 1
+    all_changed_lines = set(range(clean_helper_line, clean_helper_line + 6))
+    unscoped = check_docstring_runon_sentence(content, PRODUCTION_FILE_PATH)
+    assert any("run-on" in each for each in unscoped), (
+        f"control: unscoped must still see the far-away run-on, got {unscoped!r}"
+    )
+    scoped = check_docstring_runon_sentence(
+        content, PRODUCTION_FILE_PATH, all_changed_lines=all_changed_lines
+    )
+    assert scoped == [], (
+        f"far-away run-on must be grandfathered on a clean-helper edit, got {scoped!r}"
+    )
+
+
+def test_runon_introduced_violation_blocks() -> None:
+    content = _module_with_far_away_runon_and_clean_helper()
+    unscoped = check_docstring_runon_sentence(content, PRODUCTION_FILE_PATH)
+    assert any("run-on" in each for each in unscoped)
+    scoped = check_docstring_runon_sentence(
+        content, PRODUCTION_FILE_PATH, all_changed_lines={1}
+    )
+    assert any("run-on" in each for each in scoped), (
+        f"introduced/touched run-on must block, got {scoped!r}"
+    )
+
+
+def test_prose_wall_far_away_no_op_is_grandfathered() -> None:
+    content = _module_with_far_away_prose_wall_and_clean_helper()
+    clean_helper_line = content.splitlines().index("def clean_helper() -> str:") + 1
+    all_changed_lines = set(range(clean_helper_line, clean_helper_line + 6))
+    unscoped = check_docstring_prose_wall_without_illustration(
+        content, PRODUCTION_FILE_PATH
+    )
+    assert any("worked example" in each for each in unscoped), (
+        f"control: unscoped must still see the far-away wall, got {unscoped!r}"
+    )
+    scoped = check_docstring_prose_wall_without_illustration(
+        content, PRODUCTION_FILE_PATH, all_changed_lines=all_changed_lines
+    )
+    assert scoped == [], (
+        f"far-away wall must be grandfathered on a clean-helper edit, got {scoped!r}"
+    )
+
+
+def test_prose_wall_introduced_violation_blocks() -> None:
+    content = _module_with_far_away_prose_wall_and_clean_helper()
+    unscoped = check_docstring_prose_wall_without_illustration(
+        content, PRODUCTION_FILE_PATH
+    )
+    assert any("worked example" in each for each in unscoped)
+    scoped = check_docstring_prose_wall_without_illustration(
+        content, PRODUCTION_FILE_PATH, all_changed_lines={1}
+    )
+    assert any("worked example" in each for each in scoped), (
+        f"introduced/touched wall must block, got {scoped!r}"
+    )
+
+
+def test_runon_defer_scope_returns_all_violations() -> None:
+    content = _module_with_far_away_runon_and_clean_helper()
+    deferred = check_docstring_runon_sentence(
+        content,
+        PRODUCTION_FILE_PATH,
+        all_changed_lines={999},
+        defer_scope_to_caller=True,
+    )
+    assert any("run-on" in each for each in deferred)
+
+
+def _function_with_runon_docstring() -> str:
+    return (
+        "def clean_helper() -> str:\n"
+        '    """Owns the SIGINT install/restore/installability check, the atexit terminal-record\n'
+        "    registration, and the interrupted-run finalizer — the non-promoter-specific\n"
+        "    machinery that brackets a run so the JSONL artifact always carries a terminal\n"
+        "    record and an in-flight theme record on interrupt.\n"
+        '    """\n'
+        '    return "ok"\n'
+    )
+
+
+def test_runon_docstring_body_edit_blocks_without_def_line() -> None:
+    content = _function_with_runon_docstring()
+    unscoped = check_docstring_runon_sentence(content, PRODUCTION_FILE_PATH)
+    assert any("run-on" in each for each in unscoped), (
+        f"control: unscoped must see the function run-on, got {unscoped!r}"
+    )
+    docstring_body_lines = {2, 3, 4, 5}
+    scoped = check_docstring_runon_sentence(
+        content, PRODUCTION_FILE_PATH, all_changed_lines=docstring_body_lines
+    )
+    assert any("run-on" in each for each in scoped), (
+        f"docstring-body edit must block even when the def line is untouched, got {scoped!r}"
+    )
+
+
+def test_runon_post_docstring_body_edit_is_grandfathered() -> None:
+    content = _function_with_runon_docstring()
+    return_line = content.splitlines().index('    return "ok"') + 1
+    scoped = check_docstring_runon_sentence(
+        content, PRODUCTION_FILE_PATH, all_changed_lines={return_line}
+    )
+    assert scoped == [], (
+        f"post-docstring body edit must grandfather the pre-existing run-on, got {scoped!r}"
+    )
+
+
+def _function_with_prose_wall_docstring() -> str:
+    return (
+        "def clean_helper() -> str:\n"
+        '    """Assemble the nightly voyage tally from the harbor scans.\n'
+        "\n"
+        "    A scan names one vessel and where it dropped anchor.\n"
+        "    The tally walks the scans in arrival order and keeps that order.\n"
+        "    A calm voyage ends well for every vessel it carried.\n"
+        "    A halted voyage marks the vessel it was near when the storm arrived.\n"
+        "    A wrecked voyage marks the vessel that sank and stops the walk there.\n"
+        "    The tally groups the vessels by their final port for the harbor.\n"
+        "    The harbor reads the tally and sees every arrival at a glance.\n"
+        '    """\n'
+        '    return "ok"\n'
+    )
+
+
+def test_prose_wall_docstring_body_edit_blocks_without_def_line() -> None:
+    content = _function_with_prose_wall_docstring()
+    unscoped = check_docstring_prose_wall_without_illustration(
+        content, PRODUCTION_FILE_PATH
+    )
+    assert any("worked example" in each for each in unscoped), (
+        f"control: unscoped must see the function wall, got {unscoped!r}"
+    )
+    docstring_body_lines = set(range(2, 12))
+    scoped = check_docstring_prose_wall_without_illustration(
+        content, PRODUCTION_FILE_PATH, all_changed_lines=docstring_body_lines
+    )
+    assert any("worked example" in each for each in scoped), (
+        f"docstring-body edit must block even when the def line is untouched, got {scoped!r}"
+    )
+
+
+def test_prose_wall_defer_scope_returns_all_violations() -> None:
+    content = _module_with_far_away_prose_wall_and_clean_helper()
+    deferred = check_docstring_prose_wall_without_illustration(
+        content,
+        PRODUCTION_FILE_PATH,
+        all_changed_lines={999},
+        defer_scope_to_caller=True,
+    )
+    assert any("worked example" in each for each in deferred)
+

package/hooks/blocking/test_code_rules_enforcer_ephemeral.py

@@ -186,7 +186,7 @@ def test_should_return_false_for_pytest_tmp_path_when_job_dir_elsewhere(
     temp directory was an ephemeral source: pytest tmp_path fixtures live
     under tempfile.gettempdir(), so the enforcer's own test targets must not
     classify as ephemeral. CLAUDE_JOB_DIR points elsewhere (its scratch dir
-    lives under .claude-ev/jobs, not %TEMP%).
+    lives under .claude-profile-c/jobs, not %TEMP%).
     """
     monkeypatch.delenv("CLAUDE_CODE_RULES_DISABLE_EPHEMERAL_EXEMPT", raising=False)
     monkeypatch.setenv("CLAUDE_JOB_DIR", str(tmp_path / "elsewhere"))

package/hooks/blocking/test_code_rules_enforcer_join_separator_magic.py

@@ -65,3 +65,44 @@ def test_should_report_join_separator_line_number() -> None:
     assert any("Line 2" in each_issue for each_issue in issues), (
         f"Expected line 2 reported, got: {issues}"
     )
+
+
+def test_should_grandfather_unchanged_join_separator_in_wide_edit() -> None:
+    prior_fragment = (
+        "def render(all_paths: list) -> str:\n"
+        "    return ', '.join(str(each_path) for each_path in all_paths)\n"
+    )
+    proposed_fragment = (
+        "def render(all_paths: list) -> str:\n"
+        "    # keep the join separator the same\n"
+        "    return ', '.join(str(each_path) for each_path in all_paths)\n"
+    )
+    issues = code_rules_enforcer.validate_content(
+        proposed_fragment,
+        PRODUCTION_FILE_PATH,
+        prior_fragment,
+    )
+    join_issues = [each for each in issues if "join" in each]
+    assert join_issues == [], (
+        f"unchanged enclosed join separator must be grandfathered, got: {join_issues}"
+    )
+
+
+def test_should_block_new_join_separator_in_wide_edit() -> None:
+    prior_fragment = (
+        "def render(all_paths: list) -> str:\n"
+        "    return JOIN_DELIMITER.join(all_paths)\n"
+    )
+    proposed_fragment = (
+        "def render(all_paths: list) -> str:\n"
+        "    return ', '.join(all_paths)\n"
+    )
+    issues = code_rules_enforcer.validate_content(
+        proposed_fragment,
+        PRODUCTION_FILE_PATH,
+        prior_fragment,
+    )
+    join_issues = [each for each in issues if "join" in each]
+    assert any("Line 2" in each_issue for each_issue in join_issues), (
+        f"introduced join separator must block at its new location, got: {join_issues}"
+    )

package/hooks/blocking/test_code_rules_enforcer_string_magic.py

@@ -232,3 +232,101 @@ def test_should_still_flag_literal_in_nested_function_body() -> None:
     assert len(issues) == 1, (
         f"Inner literal must be flagged exactly once (no duplicate from outer walk), got: {issues}"
     )
+
+
+def test_should_grandfather_unchanged_string_magic_in_wide_edit() -> None:
+    prior_fragment = (
+        "import os\n"
+        "\n"
+        "def fetch_secret() -> str:\n"
+        "    return os.environ['STRIPE_SECRET']\n"
+    )
+    proposed_fragment = (
+        "import os\n"
+        "\n"
+        "def fetch_secret() -> str:\n"
+        "    # wide edit that leaves the magic string in place\n"
+        "    return os.environ['STRIPE_SECRET']\n"
+    )
+    issues = code_rules_enforcer.validate_content(
+        proposed_fragment,
+        PRODUCTION_FILE_PATH,
+        prior_fragment,
+    )
+    magic_issues = [each for each in issues if "STRIPE_SECRET" in each]
+    assert magic_issues == [], (
+        f"unchanged enclosed string magic must be grandfathered, got: {magic_issues}"
+    )
+
+
+def test_should_block_new_string_magic_in_wide_edit() -> None:
+    prior_fragment = (
+        "import os\n"
+        "\n"
+        "def fetch_secret() -> str:\n"
+        "    return os.environ.get('missing', '')\n"
+    )
+    proposed_fragment = (
+        "import os\n"
+        "\n"
+        "def fetch_secret() -> str:\n"
+        "    return os.environ['STRIPE_SECRET']\n"
+    )
+    issues = code_rules_enforcer.validate_content(
+        proposed_fragment,
+        PRODUCTION_FILE_PATH,
+        prior_fragment,
+    )
+    magic_issues = [each for each in issues if "STRIPE_SECRET" in each]
+    assert any("Line " in each_issue for each_issue in magic_issues), (
+        f"introduced string magic must block with a line locator, got: {magic_issues}"
+    )
+    assert any("STRIPE_SECRET" in each_issue for each_issue in magic_issues)
+
+
+def test_should_block_second_identical_string_magic_per_occurrence() -> None:
+    prior_fragment = (
+        "import os\n"
+        "\n"
+        "def fetch_secret() -> str:\n"
+        "    return os.environ['STRIPE_SECRET']\n"
+    )
+    proposed_fragment = (
+        "import os\n"
+        "\n"
+        "def fetch_secret() -> str:\n"
+        "    return os.environ['STRIPE_SECRET']\n"
+        "\n"
+        "def fetch_backup() -> str:\n"
+        "    return os.environ['STRIPE_SECRET']\n"
+    )
+    issues = code_rules_enforcer.validate_content(
+        proposed_fragment,
+        PRODUCTION_FILE_PATH,
+        prior_fragment,
+    )
+    magic_issues = [each for each in issues if "STRIPE_SECRET" in each]
+    assert len(magic_issues) == 1, (
+        f"exactly one new identical magic must block (per-occurrence), got: {magic_issues}"
+    )
+    assert any("Line 7" in each_issue for each_issue in magic_issues), (
+        f"second occurrence must keep proposed-fragment line, got: {magic_issues}"
+    )
+
+
+def test_should_surface_magic_when_gate_defers_scope_with_head_as_old() -> None:
+    source = (
+        "def compute() -> int:\n"
+        "    old_number = 9999\n"
+        "    return old_number\n"
+    )
+    issues = code_rules_enforcer.validate_content(
+        source,
+        PRODUCTION_FILE_PATH,
+        source,
+        defer_scope_to_caller=True,
+    )
+    assert any("9999" in each_issue for each_issue in issues), (
+        f"gate path must still surface whole-file magic when old_content equals content, "
+        f"got: {issues}"
+    )