claude-dev-env 2.26.0 → 2.28.0

package/hooks/validators/mypy_integration.py

@@ -1,6 +1,7 @@
 """Mypy integration for static type checking."""
 
 import contextlib
+import logging
 import subprocess
 import sys
 import tempfile
@@ -16,6 +17,7 @@ try:
         ancestor_directories,
         find_pyproject_configuring_tool,
     )
+    from system_temporary_roots import enclosing_system_temporary_root
 except ModuleNotFoundError:
     if _validators_directory not in sys.path:
         sys.path.insert(0, _validators_directory)
@@ -23,10 +25,15 @@ except ModuleNotFoundError:
         ancestor_directories,
         find_pyproject_configuring_tool,
     )
+    from system_temporary_roots import enclosing_system_temporary_root
 
 try:
     from hooks_constants.mypy_integration_constants import (
+        FOLLOW_IMPORTS_FLAG,
+        FOLLOW_IMPORTS_SKIP_VALUE,
         GIT_DIRECTORY_NAME,
+        MYPY_DETACHED_SUBPROCESS_TIMEOUT_SECONDS,
+        MYPY_DETACHED_TIMEOUT_SKIP_MESSAGE,
         PYPROJECT_FILENAME,
         PYTHON_SOURCE_SUFFIX,
     )
@@ -35,12 +42,18 @@ except ModuleNotFoundError:
     if _hooks_directory not in sys.path:
         sys.path.insert(0, _hooks_directory)
     from hooks_constants.mypy_integration_constants import (
+        FOLLOW_IMPORTS_FLAG,
+        FOLLOW_IMPORTS_SKIP_VALUE,
         GIT_DIRECTORY_NAME,
+        MYPY_DETACHED_SUBPROCESS_TIMEOUT_SECONDS,
+        MYPY_DETACHED_TIMEOUT_SKIP_MESSAGE,
         PYPROJECT_FILENAME,
         PYTHON_SOURCE_SUFFIX,
     )
     from hooks_constants.pyproject_config_discovery_constants import MYPY_TOOL_TABLE_NAME
 
+logger = logging.getLogger(__name__)
+
 
 @dataclass
 class MypyResult:
@@ -91,25 +104,33 @@ def find_module_resolution_root(starting_file: Path) -> Path | None:
     directory, so anchoring there binds ``config.*`` to the target file's own
     project and keeps a foreign ``config`` in the caller's directory out of scope.
 
+    The walk does not climb out of the system temp directory. A PreToolUse
+    staging copy lives under ``%TEMP%``, and a ``.git`` in the user home above
+    that temp root is not this file's project.
+
     ::
 
         target_repo/.git + target_repo/tools/x.py -> target_repo
-        /tmp/detached/x.py (no marker up-tree)      -> None
+        /tmp/detached/x.py (home .git above temp) -> None
+        flag: walk past %TEMP% into ~/.git        -> mypy cwd=home, hook timeout
 
     Args:
         starting_file: The file (or directory) the walk begins from.
 
     Returns:
         The nearest ancestor Path that holds ``.git`` or ``pyproject.toml``,
-        or ``None`` when no such ancestor exists.
+        or ``None`` when no such ancestor exists inside the walk limit.
     """
     git_entry_name = GIT_DIRECTORY_NAME
     pyproject_filename = PYPROJECT_FILENAME
+    enclosing_temporary_root = enclosing_system_temporary_root(starting_file)
     for each_candidate_directory in ancestor_directories(starting_file):
         has_git_entry = (each_candidate_directory / git_entry_name).exists()
         has_pyproject = (each_candidate_directory / pyproject_filename).is_file()
         if has_git_entry or has_pyproject:
             return each_candidate_directory
+        if each_candidate_directory == enclosing_temporary_root:
+            return None
     return None
 
 
@@ -123,7 +144,7 @@ def _first_module_resolution_root(all_py_files: list[str]) -> Path | None:
 
 
 @contextlib.contextmanager
-def mypy_working_directory(all_py_files: list[str]) -> Iterator[str]:
+def mypy_working_directory(resolution_root: Path | None) -> Iterator[str]:
     """Yield the working directory mypy resolves first-party imports from.
 
     ::
@@ -136,12 +157,12 @@ def mypy_working_directory(all_py_files: list[str]) -> Iterator[str]:
     no foreign top-level package leaks in.
 
     Args:
-        all_py_files: Absolute or relative paths of the Python files under check.
+        resolution_root: The first rooted target's project root, or ``None``
+            when every target is detached.
 
     Yields:
         A directory path string mypy should use as its working directory.
     """
-    resolution_root = _first_module_resolution_root(all_py_files)
     if resolution_root is not None:
         yield str(resolution_root)
         return
@@ -189,17 +210,55 @@ def _mypy_config_argument(
 def _run_mypy_subprocess(
     all_py_files: list[str], config_source_path: Path | None
 ) -> subprocess.CompletedProcess[str]:
-    """Run mypy over *all_py_files* from each file's own project root."""
+    """Run mypy over *all_py_files* from each file's own project root.
+
+    A detached file (no ``.git`` or ``pyproject.toml`` ancestor) is a PreToolUse
+    staging copy. Following imports there loads site-packages and sibling
+    modules and blows the 30-second hook budget, so that path skips followed
+    imports and bounds the subprocess.
+
+    ::
+
+        ok:   temp/vae_compile.py (no project root) -> --follow-imports skip
+        ok:   repo/tools/serialize_tool.py          -> default follow-imports
+        flag: temp/vae_compile.py follow=normal     -> torch stubs, hook timeout
+    """
+    follow_imports_flag = FOLLOW_IMPORTS_FLAG
+    follow_imports_skip_value = FOLLOW_IMPORTS_SKIP_VALUE
+    detached_timeout_seconds = MYPY_DETACHED_SUBPROCESS_TIMEOUT_SECONDS
+    detached_timeout_skip_message = MYPY_DETACHED_TIMEOUT_SKIP_MESSAGE
     config_argument = _mypy_config_argument(all_py_files, config_source_path)
-    with mypy_working_directory(all_py_files) as working_directory:
-        return subprocess.run(
-            ["mypy", *config_argument, "--ignore-missing-imports", "--no-error-summary"]
-            + all_py_files,
-            check=False,
-            capture_output=True,
-            text=True,
-            cwd=working_directory,
-        )
+    resolution_root = _first_module_resolution_root(all_py_files)
+    is_detached_target = resolution_root is None
+    follow_imports_arguments = (
+        [follow_imports_flag, follow_imports_skip_value] if is_detached_target else []
+    )
+    timeout_seconds = detached_timeout_seconds if is_detached_target else None
+    with mypy_working_directory(resolution_root) as working_directory:
+        try:
+            return subprocess.run(
+                [
+                    "mypy",
+                    *config_argument,
+                    *follow_imports_arguments,
+                    "--ignore-missing-imports",
+                    "--no-error-summary",
+                    *all_py_files,
+                ],
+                check=False,
+                capture_output=True,
+                text=True,
+                cwd=working_directory,
+                timeout=timeout_seconds,
+            )
+        except subprocess.TimeoutExpired:
+            logger.warning(detached_timeout_skip_message)
+            return subprocess.CompletedProcess(
+                args=["mypy"],
+                returncode=0,
+                stdout="",
+                stderr=detached_timeout_skip_message,
+            )
 
 
 def run_mypy_check(
@@ -208,7 +267,9 @@ def run_mypy_check(
     """Run mypy on files, resolving config from *config_source_path* when given.
 
     A given ``config_source_path`` walks ``--config-file`` up from the original
-    target rather than the staged copy's own ancestors.
+    target rather than the staged copy's own ancestors. A detached staging
+    file that hits the subprocess timeout returns passed, same as when mypy
+    is not installed, so the 30-second PreToolUse hook can still return.
     """
     if not all_files:
         return MypyResult(passed=True, output="No files to check", error_count=0)

package/hooks/validators/run_all_validators.py

@@ -23,10 +23,10 @@ from ._path_setup import hooks_directory_on_path  # noqa: F401
 from .config.directory_exemption_constants import (
     ALL_DIRECTORY_EXEMPTION_SEGMENT_NAMES,
     ALL_DIRECTORY_EXEMPTION_SUBSTRING_PATTERNS,
-    ALL_SYSTEM_TEMPORARY_ROOT_ENVIRONMENT_VARIABLE_NAMES,
 )
 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
 from .output_formatter import OutputFormatter, OutputMode, ValidatorResultDict
 from .python_style_checks import fix_file
 from .ruff_integration import check_ruff_available, run_ruff_check
@@ -788,32 +788,6 @@ def _escapes_temporary_root(path_part: str) -> bool:
     return part_as_path.is_absolute() or bool(part_as_path.anchor)
 
 
-def _all_system_temporary_roots() -> tuple[Path, ...]:
-    """Return resolved roots that count as system temporary directories.
-
-    ::
-
-        gettempdir() plus TEMP / TMP / TMPDIR / RUNNER_TEMP when set.
-
-    GitHub Actions puts pytest basetemp under ``RUNNER_TEMP``
-    (``/home/runner/work/_temp``) while ``tempfile.gettempdir()`` is ``/tmp``.
-    Both must count so pytest-shaped ``test_*`` parents disable substring
-    exemption matching during staging.
-    """
-    all_candidate_roots: list[str] = [tempfile.gettempdir()]
-    for each_environment_name in ALL_SYSTEM_TEMPORARY_ROOT_ENVIRONMENT_VARIABLE_NAMES:
-        environment_value = os.environ.get(each_environment_name)
-        if environment_value:
-            all_candidate_roots.append(environment_value)
-    all_resolved_roots: list[Path] = []
-    for each_candidate in all_candidate_roots:
-        try:
-            all_resolved_roots.append(Path(each_candidate).resolve())
-        except OSError:
-            continue
-    return tuple(all_resolved_roots)
-
-
 def _is_absolute_path_under_system_temporary_directory(file_path: str) -> bool:
     """Return True when *file_path* is absolute and resolves under an OS temp root.
 
@@ -840,14 +814,7 @@ def _is_absolute_path_under_system_temporary_directory(file_path: str) -> bool:
     destination_path = Path(file_path)
     if not destination_path.is_absolute():
         return False
-    try:
-        resolved_destination = destination_path.resolve()
-    except OSError:
-        return False
-    return any(
-        resolved_destination.is_relative_to(each_temporary_root)
-        for each_temporary_root in _all_system_temporary_roots()
-    )
+    return enclosing_system_temporary_root(destination_path) is not None
 
 
 def _directory_segment_signals_exemption(

package/hooks/validators/system_temporary_roots.py

@@ -0,0 +1,90 @@
+"""Resolve the system temp root that contains a path, if any.
+
+Staging copies and pytest basetemp live under ``tempfile.gettempdir()`` or
+under ``TEMP`` / ``TMP`` / ``TMPDIR`` / ``RUNNER_TEMP``. A walk that needs to
+stop at that boundary asks here instead of re-coding membership in each caller.
+
+::
+
+    %TEMP%/pytest-123/x.py              -> %TEMP%
+    RUNNER_TEMP/detached/x.py (GHA)     -> RUNNER_TEMP
+    C:/repo/pkg/x.py                    -> None
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from validators.config.directory_exemption_constants import (  # noqa: E402
+    ALL_SYSTEM_TEMPORARY_ROOT_ENVIRONMENT_VARIABLE_NAMES,
+)
+
+
+def all_system_temporary_roots() -> tuple[Path, ...]:
+    """Return resolved roots that count as system temporary directories.
+
+    ::
+
+        gettempdir() plus TEMP / TMP / TMPDIR / RUNNER_TEMP when set.
+
+    GitHub Actions puts pytest basetemp under ``RUNNER_TEMP``
+    (``/home/runner/work/_temp``) while ``tempfile.gettempdir()`` is ``/tmp``.
+    Both count so a staging walk and a path-exemption check agree.
+
+    Returns:
+        Unique resolved directory Paths. Unresolvable candidates are dropped.
+    """
+    all_candidate_roots: list[str] = [tempfile.gettempdir()]
+    for each_environment_name in ALL_SYSTEM_TEMPORARY_ROOT_ENVIRONMENT_VARIABLE_NAMES:
+        environment_value = os.environ.get(each_environment_name)
+        if environment_value:
+            all_candidate_roots.append(environment_value)
+    all_resolved_roots: list[Path] = []
+    all_seen_roots: set[Path] = set()
+    for each_candidate in all_candidate_roots:
+        try:
+            resolved_root = Path(each_candidate).resolve()
+        except OSError:
+            continue
+        if resolved_root in all_seen_roots:
+            continue
+        all_seen_roots.add(resolved_root)
+        all_resolved_roots.append(resolved_root)
+    return tuple(all_resolved_roots)
+
+
+def enclosing_system_temporary_root(starting_file: Path) -> Path | None:
+    """Return the innermost system temp root that contains *starting_file*.
+
+    ::
+
+        %TEMP%/pytest-123/x.py -> %TEMP%
+        C:/repo/pkg/x.py       -> None
+
+    When more than one listed root contains the file, the first ancestor that
+    is already in the root set wins, so a nested ``RUNNER_TEMP`` stops the walk
+    before a broader ``gettempdir()`` ancestor.
+
+    Args:
+        starting_file: The file or directory whose ancestors are bounded.
+
+    Returns:
+        The innermost matching root Path, or ``None`` when no listed root
+        contains *starting_file*.
+    """
+    try:
+        resolved_start = starting_file.resolve()
+    except OSError:
+        return None
+    all_root_set = set(all_system_temporary_roots())
+    for each_candidate_directory in (resolved_start, *resolved_start.parents):
+        if each_candidate_directory in all_root_set:
+            return each_candidate_directory
+    return None

package/hooks/validators/test_directory_exemption_constants.py

@@ -147,7 +147,7 @@ def test_runner_temp_pytest_shaped_path_stages_flat_basename_when_gettempdir_dif
     os_gettemp.mkdir()
     monkeypatch.setenv("RUNNER_TEMP", str(runner_temp_root))
     monkeypatch.setattr(
-        "validators.run_all_validators.tempfile.gettempdir",
+        "validators.system_temporary_roots.tempfile.gettempdir",
         lambda: str(os_gettemp),
     )
     pytest_shaped_target = (

package/hooks/validators/test_mypy_integration.py

@@ -1,10 +1,13 @@
 """Tests for mypy integration module."""
 
+import logging
+import subprocess
 from pathlib import Path
 from unittest.mock import patch
 
 import pytest
 
+from . import mypy_integration as mypy_integration_module
 from .mypy_integration import (
     MypyResult,
     check_mypy_available,
@@ -30,6 +33,63 @@ def _write_config_importer(script_path: Path) -> None:
     )
 
 
+def test_find_module_resolution_root_ignores_git_above_system_temp(
+    tmp_path: Path,
+) -> None:
+    """A temp staging file does not inherit ``.git`` from a parent of ``%TEMP%``.
+
+    ::
+
+        %TEMP%/pytest-.../detached/module.py
+        C:/Users/<you>/.git exists above %TEMP%
+        flag: walk returns the home repo -> mypy cwd=home, torch stubs, 30s timeout
+        ok:   walk stops at the temp root -> None
+    """
+    nested_file = tmp_path / "detached" / "module.py"
+    nested_file.parent.mkdir()
+    nested_file.write_text("sample_number: int = 1\n", encoding="utf-8")
+    assert find_module_resolution_root(nested_file) is None
+
+
+def test_find_module_resolution_root_still_sees_git_inside_temp(tmp_path: Path) -> None:
+    """A repo created inside the temp tree is still a project root."""
+    nested_repo = tmp_path / "inner_repo"
+    nested_file = nested_repo / "pkg" / "module.py"
+    nested_file.parent.mkdir(parents=True)
+    (nested_repo / ".git").mkdir()
+    nested_file.write_text("sample_number: int = 1\n", encoding="utf-8")
+    assert find_module_resolution_root(nested_file) == nested_repo
+
+
+def test_find_module_resolution_root_stops_at_runner_temp_when_gettempdir_differs(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A RUNNER_TEMP staging file does not inherit ``.git`` above that root.
+
+    ::
+
+        RUNNER_TEMP/detached/module.py, gettempdir -> sibling os_gettemp
+        tmp_path/.git sits above RUNNER_TEMP
+        flag: gettempdir-only walk returns tmp_path
+        ok:   walk stops at RUNNER_TEMP -> None
+    """
+    runner_temp_root = tmp_path / "runner_temp"
+    os_gettemp = tmp_path / "os_gettemp"
+    runner_temp_root.mkdir()
+    os_gettemp.mkdir()
+    (tmp_path / ".git").mkdir()
+    monkeypatch.setenv("RUNNER_TEMP", str(runner_temp_root))
+    monkeypatch.setattr(
+        "validators.system_temporary_roots.tempfile.gettempdir",
+        lambda: str(os_gettemp),
+    )
+    nested_file = runner_temp_root / "detached" / "module.py"
+    nested_file.parent.mkdir()
+    nested_file.write_text("sample_number: int = 1\n", encoding="utf-8")
+
+    assert find_module_resolution_root(nested_file) is None
+
+
 def test_find_module_resolution_root_returns_git_marked_ancestor(tmp_path: Path) -> None:
     target_repo = tmp_path / "git_repo"
     nested_directory = target_repo / "src" / "deep"
@@ -165,6 +225,115 @@ def test_run_mypy_check_accepts_relative_path_under_nested_root(
     assert mypy_result.passed, mypy_result.output
 
 
+def test_run_mypy_check_does_not_report_imported_sibling_on_detached_file(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A detached gate file does not inherit type errors from an imported sibling.
+
+    ::
+
+        detached/importer.py -> from sibling import broken_value
+        detached/sibling.py  -> broken_value: int = "not an integer"
+        flag: follow-imports=normal reports sibling.py and fails the gate file
+        ok:   follow-imports=skip grades importer.py only -> passed
+
+    The PreToolUse gate stages one file under a temp directory with no project
+    root. Following imports there loads site-packages (torch stubs) and sibling
+    modules, and the 30s hook budget expires.
+    """
+    if not check_mypy_available():
+        pytest.skip("mypy is not installed")
+
+    detached_directory = tmp_path / "detached_gate_dir"
+    detached_directory.mkdir()
+    (detached_directory / "sibling.py").write_text(
+        "broken_value: int = 'not an integer'\n",
+        encoding="utf-8",
+    )
+    importer_file = detached_directory / "importer.py"
+    importer_file.write_text(
+        "from sibling import broken_value\n\n"
+        "copied_value: int = broken_value\n",
+        encoding="utf-8",
+    )
+
+    monkeypatch.chdir(tmp_path)
+    mypy_result = run_mypy_check([importer_file])
+
+    assert mypy_result.passed, mypy_result.output
+    assert "sibling.py" not in mypy_result.output
+
+
+def test_run_mypy_check_reports_imported_sibling_on_rooted_file(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A rooted file still follows first-party imports and reports sibling errors.
+
+    ::
+
+        rooted_repo/.git + importer.py -> from sibling import broken_value
+        rooted_repo/sibling.py         -> broken_value: int = "not an integer"
+        ok:   follow-imports=normal reports sibling.py -> failed
+        flag: --follow-imports=skip on rooted files hides sibling.py -> passed
+
+    Skip applies only to detached staging copies. Applying it to a repo file
+    would drop first-party type errors the in-repo path must still see.
+    """
+    if not check_mypy_available():
+        pytest.skip("mypy is not installed")
+
+    rooted_repo = tmp_path / "rooted_repo"
+    rooted_repo.mkdir()
+    (rooted_repo / ".git").mkdir()
+    (rooted_repo / "sibling.py").write_text(
+        "broken_value: int = 'not an integer'\n",
+        encoding="utf-8",
+    )
+    importer_file = rooted_repo / "importer.py"
+    importer_file.write_text(
+        "from sibling import broken_value\n\n"
+        "copied_value: int = broken_value\n",
+        encoding="utf-8",
+    )
+
+    monkeypatch.chdir(tmp_path)
+    mypy_result = run_mypy_check([importer_file])
+
+    assert not mypy_result.passed
+    assert "sibling.py" in mypy_result.output
+
+
+def test_run_mypy_check_skips_when_detached_mypy_times_out(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A detached mypy that exceeds its timeout does not fail the file.
+
+    ::
+
+        detached/module.py, subprocess.run raises TimeoutExpired
+        ok:   passed=True and the skip message is in the output
+        flag: TimeoutExpired propagates and the PreToolUse hook dies
+    """
+    detached_file = tmp_path / "detached" / "module.py"
+    detached_file.parent.mkdir()
+    detached_file.write_text("sample_number: int = 1\n", encoding="utf-8")
+
+    monkeypatch.setattr(
+        mypy_integration_module, "check_mypy_available", lambda: True
+    )
+
+    def raise_timeout(*_args: object, **_kwargs: object) -> None:
+        raise subprocess.TimeoutExpired(cmd="mypy", timeout=1)
+
+    monkeypatch.setattr(mypy_integration_module.subprocess, "run", raise_timeout)
+    with caplog.at_level(logging.WARNING):
+        mypy_result = run_mypy_check([detached_file])
+
+    assert mypy_result.passed
+    assert "timed out on a detached file" in mypy_result.output
+    assert "timed out on a detached file" in caplog.text
+
+
 def test_run_mypy_check_applies_config_resolved_from_config_source_path(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:

package/hooks/validators/test_system_temporary_roots.py

@@ -0,0 +1,93 @@
+"""Tests for the shared system-temp root membership helper."""
+
+from pathlib import Path
+
+import pytest
+
+from .system_temporary_roots import (
+    all_system_temporary_roots,
+    enclosing_system_temporary_root,
+)
+
+
+def test_all_system_temporary_roots_includes_runner_temp_when_set(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """RUNNER_TEMP joins gettempdir so GHA basetemp counts as system temp."""
+    runner_temp_root = tmp_path / "runner_temp"
+    os_gettemp = tmp_path / "os_gettemp"
+    runner_temp_root.mkdir()
+    os_gettemp.mkdir()
+    monkeypatch.setenv("RUNNER_TEMP", str(runner_temp_root))
+    monkeypatch.setattr(
+        "validators.system_temporary_roots.tempfile.gettempdir",
+        lambda: str(os_gettemp),
+    )
+
+    all_roots = all_system_temporary_roots()
+
+    assert os_gettemp.resolve() in all_roots
+    assert runner_temp_root.resolve() in all_roots
+
+
+def test_enclosing_system_temporary_root_returns_gettempdir_for_file_under_it(
+    tmp_path: Path,
+) -> None:
+    """A pytest tmp_path file sits under the process temp root."""
+    nested_file = tmp_path / "detached" / "module.py"
+    nested_file.parent.mkdir()
+    nested_file.write_text("sample_number: int = 1\n", encoding="utf-8")
+
+    enclosing_root = enclosing_system_temporary_root(nested_file)
+
+    assert enclosing_root is not None
+    assert nested_file.resolve().is_relative_to(enclosing_root)
+
+
+def test_enclosing_system_temporary_root_uses_runner_temp_when_gettempdir_differs(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """GHA basetemp lives under RUNNER_TEMP while gettempdir is often another root.
+
+    ::
+
+        RUNNER_TEMP/detached/module.py, gettempdir -> sibling os_gettemp
+        ok:   enclosing root is RUNNER_TEMP
+        flag: gettempdir-only helper returns None and the mypy walk climbs out
+    """
+    runner_temp_root = tmp_path / "runner_temp"
+    os_gettemp = tmp_path / "os_gettemp"
+    runner_temp_root.mkdir()
+    os_gettemp.mkdir()
+    monkeypatch.setenv("RUNNER_TEMP", str(runner_temp_root))
+    monkeypatch.setattr(
+        "validators.system_temporary_roots.tempfile.gettempdir",
+        lambda: str(os_gettemp),
+    )
+    nested_file = runner_temp_root / "detached" / "module.py"
+    nested_file.parent.mkdir()
+    nested_file.write_text("sample_number: int = 1\n", encoding="utf-8")
+
+    assert enclosing_system_temporary_root(nested_file) == runner_temp_root.resolve()
+
+
+def test_enclosing_system_temporary_root_returns_none_outside_every_temp_root(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A path outside gettempdir and the temp env vars is not a staging copy."""
+    os_gettemp = tmp_path / "os_gettemp"
+    project_root = tmp_path / "project"
+    os_gettemp.mkdir()
+    project_root.mkdir()
+    monkeypatch.delenv("RUNNER_TEMP", raising=False)
+    monkeypatch.delenv("TEMP", raising=False)
+    monkeypatch.delenv("TMP", raising=False)
+    monkeypatch.delenv("TMPDIR", raising=False)
+    monkeypatch.setattr(
+        "validators.system_temporary_roots.tempfile.gettempdir",
+        lambda: str(os_gettemp),
+    )
+    project_file = project_root / "module.py"
+    project_file.write_text("sample_number: int = 1\n", encoding="utf-8")
+
+    assert enclosing_system_temporary_root(project_file) is None

package/package.json

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