claude-dev-env 2.19.0 → 2.21.0

package/hooks/workflow/test_auto_formatter.py

@@ -21,18 +21,34 @@ import sys
 import tempfile
 from collections.abc import Generator
 from pathlib import Path
+from types import ModuleType
 
 import pytest
 
 HOOK_SCRIPT_PATH = os.path.join(os.path.dirname(__file__), "auto_formatter.py")
-HOOKS_JSON_PATH = os.path.join(
-    os.path.dirname(os.path.dirname(os.path.dirname(__file__))), "hooks", "hooks.json"
+HOOKS_DIRECTORY_PATH = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+POST_TOOL_USE_DISPATCHER_PATH = os.path.join(
+    HOOKS_DIRECTORY_PATH, "validation", "post_tool_use_dispatcher.py"
 )
+PLUGIN_ROOT_PATH = os.path.dirname(HOOKS_DIRECTORY_PATH)
+HOOKS_JSON_PATH = os.path.join(HOOKS_DIRECTORY_PATH, "hooks.json")
 POST_TOOL_USE_DISPATCHER_COMMAND_FRAGMENT = "validation/post_tool_use_dispatcher.py"
 UNUSED_IMPORT_SOURCE = "import os\n\n\nVALUE = 1\n"
 HOOK_RUN_TIMEOUT_SECONDS = 60
 
 
+def build_fixture_git_environment() -> dict[str, str]:
+    return {
+        each_name: each_value
+        for each_name, each_value in os.environ.items()
+        if not each_name.upper().startswith("GIT_")
+    }
+
+
+def build_dispatcher_payload(tool_name: str, file_path: Path) -> str:
+    return json.dumps({"tool_name": tool_name, "tool_input": {"file_path": str(file_path)}})
+
+
 def _strip_read_only_and_retry(removal_function, target_path, *_exc_info):
     try:
         os.chmod(target_path, stat.S_IWRITE)
@@ -42,13 +58,8 @@ def _strip_read_only_and_retry(removal_function, target_path, *_exc_info):
 
 
 def _force_rmtree(target_path: str) -> None:
-    handler_kw = (
-        {"onexc": _strip_read_only_and_retry}
-        if sys.version_info >= (3, 12)
-        else {"onerror": _strip_read_only_and_retry}
-    )
     with contextlib.suppress(OSError):
-        shutil.rmtree(target_path, **handler_kw)
+        shutil.rmtree(target_path, onexc=_strip_read_only_and_retry)
 
 
 @functools.lru_cache(maxsize=1)
@@ -67,20 +78,40 @@ def _cleanup_sandbox_parent_directory() -> Generator[None]:
 @pytest.fixture
 def git_repository() -> Generator[Path]:
     repository_path = Path(tempfile.mkdtemp(dir=_get_sandbox_parent_directory()))
-    subprocess.run(["git", "init"], cwd=repository_path, capture_output=True, check=True)
+    subprocess.run(
+        ["git", "init"],
+        cwd=repository_path,
+        capture_output=True,
+        check=True,
+        env=build_fixture_git_environment(),
+    )
     yield repository_path
     _force_rmtree(str(repository_path))
 
 
 def _run_hook(tool_name: str, file_path: Path) -> subprocess.CompletedProcess[str]:
-    hook_input = json.dumps({"tool_name": tool_name, "tool_input": {"file_path": str(file_path)}})
     return subprocess.run(
         [sys.executable, HOOK_SCRIPT_PATH],
-        input=hook_input,
+        input=build_dispatcher_payload(tool_name, file_path),
         capture_output=True,
         text=True,
         timeout=HOOK_RUN_TIMEOUT_SECONDS,
         check=False,
+        env=build_fixture_git_environment(),
+    )
+
+
+def _run_post_tool_use_dispatcher(
+    tool_name: str, file_path: Path, environment: dict[str, str]
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, POST_TOOL_USE_DISPATCHER_PATH, PLUGIN_ROOT_PATH],
+        input=build_dispatcher_payload(tool_name, file_path),
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=HOOK_RUN_TIMEOUT_SECONDS,
+        env=environment,
     )
 
 
@@ -115,6 +146,7 @@ class TestRuffFixOnNewFiles:
             cwd=git_repository,
             capture_output=True,
             check=True,
+            env=build_fixture_git_environment(),
         )
 
         completed_hook = _run_hook("Write", tracked_file)
@@ -131,6 +163,7 @@ def test_tracked_write_leaves_unused_import_in_place(git_repository: Path) -> No
         cwd=git_repository,
         capture_output=True,
         check=True,
+        env=build_fixture_git_environment(),
     )
 
     completed_hook = _run_hook("Write", tracked_file)
@@ -139,7 +172,7 @@ def test_tracked_write_leaves_unused_import_in_place(git_repository: Path) -> No
     assert "import os" in tracked_file.read_text(encoding="utf-8")
 
 
-def _load_auto_formatter_module() -> object:
+def _load_auto_formatter_module() -> ModuleType:
     module_spec = importlib.util.spec_from_file_location("auto_formatter", HOOK_SCRIPT_PATH)
     assert module_spec is not None and module_spec.loader is not None
     auto_formatter_module = importlib.util.module_from_spec(module_spec)
@@ -147,6 +180,222 @@ def _load_auto_formatter_module() -> object:
     return auto_formatter_module
 
 
+def test_formatter_eligibility_requires_write_tool_and_untracked_source(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    auto_formatter_module = _load_auto_formatter_module()
+    source_file = tmp_path / "new_module.py"
+    monkeypatch.setattr(auto_formatter_module, "is_untracked_in_git", lambda _: True)
+
+    assert auto_formatter_module.is_formatter_eligible("Write", str(source_file))
+    assert not auto_formatter_module.is_formatter_eligible("Bash", str(source_file))
+
+
+def test_formatter_eligibility_protects_hook_tree(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    auto_formatter_module = _load_auto_formatter_module()
+    hooks_directory = tmp_path / "hooks"
+    protected_file = hooks_directory / "generated.py"
+    monkeypatch.setattr(
+        auto_formatter_module,
+        "HOOKS_DIR",
+        f"{hooks_directory}{os.sep}",
+    )
+
+    assert auto_formatter_module.is_protected_path(str(protected_file))
+
+
+def test_formatter_eligibility_protects_symlinked_hook_tree(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    auto_formatter_module = _load_auto_formatter_module()
+    hooks_directory = tmp_path / "hooks"
+    hooks_directory.mkdir()
+    outside_file = tmp_path / "outside.py"
+    outside_file.write_text(UNUSED_IMPORT_SOURCE, encoding="utf-8")
+    symlinked_file = hooks_directory / "linked.py"
+    try:
+        symlinked_file.symlink_to(outside_file)
+    except (OSError, NotImplementedError):
+        return
+    monkeypatch.setattr(
+        auto_formatter_module,
+        "HOOKS_DIR",
+        f"{hooks_directory}{os.sep}",
+    )
+    monkeypatch.setattr(auto_formatter_module, "is_untracked_in_git", lambda _: True)
+
+    assert auto_formatter_module.is_formatter_eligible("Write", str(symlinked_file)) is False
+
+
+def test_formatter_eligibility_protects_symlink_target_inside_hook_tree(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    auto_formatter_module = _load_auto_formatter_module()
+    hooks_directory = tmp_path / "hooks"
+    hooks_directory.mkdir()
+    protected_file = hooks_directory / "protected.py"
+    protected_file.write_text(UNUSED_IMPORT_SOURCE, encoding="utf-8")
+    symlinked_file = tmp_path / "linked.py"
+    try:
+        symlinked_file.symlink_to(protected_file)
+    except (OSError, NotImplementedError):
+        return
+    monkeypatch.setattr(
+        auto_formatter_module,
+        "HOOKS_DIR",
+        f"{hooks_directory}{os.sep}",
+    )
+    monkeypatch.setattr(auto_formatter_module, "is_untracked_in_git", lambda _: True)
+
+    assert auto_formatter_module.is_formatter_eligible("Write", str(symlinked_file)) is False
+
+
+def test_formatter_diagnostic_stays_on_stderr(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    auto_formatter_module = _load_auto_formatter_module()
+
+    def return_formatter_failure(
+        command: list[str], **_options: object
+    ) -> subprocess.CompletedProcess[str]:
+        return subprocess.CompletedProcess(
+            command,
+            3,
+            "formatter stdout",
+            "formatter stderr",
+        )
+
+    monkeypatch.setattr(subprocess, "run", return_formatter_failure)
+    auto_formatter_module.run_eligible_formatter("broken.py")
+
+    captured_output = capsys.readouterr()
+    assert "formatter stdout" in captured_output.err
+    assert "formatter stderr" in captured_output.err
+    assert captured_output.out == ""
+
+
+def test_prettier_command_uses_windows_npx_and_resolved_file_path(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    auto_formatter_module = _load_auto_formatter_module()
+    candidate_file = tmp_path / "linked_module.js"
+    captured_commands: list[list[str]] = []
+
+    def capture_formatter_command(
+        command: list[str], _file_path: str, _timeout_seconds: int
+    ) -> tuple[subprocess.CompletedProcess[str], bool]:
+        captured_commands.append(command)
+        return subprocess.CompletedProcess(command, 0, "", ""), False
+
+    monkeypatch.setattr(auto_formatter_module, "_run_command", capture_formatter_command)
+
+    auto_formatter_module._run_prettier(str(candidate_file))
+
+    assert captured_commands == [
+        [
+            auto_formatter_module.NPX_EXECUTABLE,
+            "--yes",
+            "prettier",
+            "--write",
+            os.path.realpath(candidate_file),
+        ]
+    ]
+
+
+def test_tracked_write_ignores_redirected_git_dir(
+    git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    tracked_file = git_repository / "redirected_git_dir.py"
+    tracked_file.write_text(UNUSED_IMPORT_SOURCE, encoding="utf-8")
+    subprocess.run(
+        ["git", "add", "redirected_git_dir.py"],
+        cwd=git_repository,
+        capture_output=True,
+        check=True,
+        env=build_fixture_git_environment(),
+    )
+    redirected_repository = tmp_path / "redirected_repository"
+    redirected_repository.mkdir()
+    subprocess.run(
+        ["git", "init"],
+        cwd=redirected_repository,
+        capture_output=True,
+        check=True,
+        env=build_fixture_git_environment(),
+    )
+    monkeypatch.setenv("GIT_DIR", str(redirected_repository / ".git"))
+
+    completed_hook = _run_hook("Write", tracked_file)
+
+    assert completed_hook.returncode == 0
+    assert "import os" in tracked_file.read_text(encoding="utf-8")
+
+
+def test_dispatcher_preserves_redirected_git_dir_until_formatter_hook(
+    git_repository: Path,
+    tmp_path: Path,
+) -> None:
+    tracked_file = git_repository / "dispatcher_redirected_git_dir.py"
+    tracked_file.write_text(UNUSED_IMPORT_SOURCE, encoding="utf-8")
+    subprocess.run(
+        ["git", "add", "dispatcher_redirected_git_dir.py"],
+        cwd=git_repository,
+        capture_output=True,
+        check=True,
+        env=build_fixture_git_environment(),
+    )
+    redirected_repository = tmp_path / "dispatcher_redirected_repository"
+    redirected_repository.mkdir()
+    subprocess.run(
+        ["git", "init"],
+        cwd=redirected_repository,
+        capture_output=True,
+        check=True,
+        env=build_fixture_git_environment(),
+    )
+    dispatcher_environment = os.environ.copy()
+    dispatcher_environment["GIT_DIR"] = str(redirected_repository / ".git")
+
+    completed_dispatcher = _run_post_tool_use_dispatcher(
+        "Write", tracked_file, dispatcher_environment
+    )
+
+    assert completed_dispatcher.returncode == 0
+    assert "import os" in tracked_file.read_text(encoding="utf-8")
+
+
+def test_dispatcher_run_uses_hook_timeout(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    captured_options: dict[str, object] = {}
+
+    def capture_dispatcher_run(
+        command: list[str], **options: object
+    ) -> subprocess.CompletedProcess[str]:
+        captured_options.update(options)
+        return subprocess.CompletedProcess(command, 0, "", "")
+
+    monkeypatch.setattr(subprocess, "run", capture_dispatcher_run)
+
+    _run_post_tool_use_dispatcher("Write", tmp_path / "module.py", {})
+
+    assert captured_options["timeout"] == HOOK_RUN_TIMEOUT_SECONDS
+
+
+def test_python_formatting_preserves_crlf_line_endings(git_repository: Path) -> None:
+    source_file = git_repository / "crlf_module.py"
+    source_file.write_bytes(b"x=1\r\ny  =  2\r\n")
+
+    completed_hook = _run_hook("Write", source_file)
+
+    assert completed_hook.returncode == 0
+    formatted_source = source_file.read_bytes()
+    assert b"\r\n" in formatted_source
+    assert b"\n" not in formatted_source.replace(b"\r\n", b"")
+
+
 def _registered_auto_formatter_timeout() -> int:
     with open(HOOKS_JSON_PATH, encoding="utf-8") as hooks_file:
         hooks_configuration = json.load(hooks_file)

package/hooks/workflow/test_investigation_tracker_reset.py

@@ -0,0 +1,90 @@
+"""Behavior tests for investigation tracker reset."""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+from pathlib import Path
+from unittest import mock
+
+import pytest
+
+
+HOOK_DIRECTORY = Path(__file__).parent
+HOOK_SPEC = importlib.util.spec_from_file_location(
+    "investigation_tracker_reset",
+    HOOK_DIRECTORY / "investigation_tracker_reset.py",
+)
+assert HOOK_SPEC is not None
+assert HOOK_SPEC.loader is not None
+HOOK_MODULE = importlib.util.module_from_spec(HOOK_SPEC)
+HOOK_SPEC.loader.exec_module(HOOK_MODULE)
+
+
+def _run_main(input_text: str) -> int | None:
+    with mock.patch("sys.stdin", io.StringIO(input_text)):
+        try:
+            HOOK_MODULE.main()
+        except SystemExit as system_exit:
+            if system_exit.code not in (None, 0):
+                raise
+            return system_exit.code if isinstance(system_exit.code, int) else None
+    return None
+
+
+@pytest.mark.parametrize("delegation_tool", ["Agent", "Task", "TeamCreate"])
+def test_main_removes_tracker_after_delegation(
+    tmp_path: Path,
+    delegation_tool: str,
+) -> None:
+    tracker_path = tmp_path / "investigation-tracker.json"
+    tracker_path.write_text("{}", encoding="utf-8")
+    HOOK_MODULE.__dict__["TRACKER_STATE_PATH"] = str(tracker_path)
+
+    exit_status = _run_main(json.dumps({"tool_name": delegation_tool}))
+
+    assert exit_status in (None, 0)
+    assert not tracker_path.exists()
+
+
+@pytest.mark.parametrize("unrelated_tool", ["Read", "Bash", "Grep"])
+def test_main_keeps_tracker_for_unrelated_tool(
+    tmp_path: Path,
+    unrelated_tool: str,
+) -> None:
+    tracker_path = tmp_path / "investigation-tracker.json"
+    tracker_path.write_text("{}", encoding="utf-8")
+    HOOK_MODULE.__dict__["TRACKER_STATE_PATH"] = str(tracker_path)
+
+    exit_status = _run_main(json.dumps({"tool_name": unrelated_tool}))
+
+    assert exit_status in (None, 0)
+    assert tracker_path.exists()
+
+
+@pytest.mark.parametrize("invalid_input", ["not json", json.dumps([])])
+def test_main_ignores_invalid_input(
+    tmp_path: Path,
+    invalid_input: str,
+) -> None:
+    tracker_path = tmp_path / "investigation-tracker.json"
+    tracker_path.write_text("{}", encoding="utf-8")
+    HOOK_MODULE.__dict__["TRACKER_STATE_PATH"] = str(tracker_path)
+
+    exit_status = _run_main(invalid_input)
+
+    assert exit_status in (None, 0)
+    assert tracker_path.exists()
+
+
+def test_main_keeps_running_when_tracker_removal_fails(tmp_path: Path) -> None:
+    tracker_path = tmp_path / "investigation-tracker.json"
+    tracker_path.write_text("{}", encoding="utf-8")
+    HOOK_MODULE.__dict__["TRACKER_STATE_PATH"] = str(tracker_path)
+
+    with mock.patch.object(HOOK_MODULE.os, "remove", side_effect=OSError("locked")):
+        exit_status = _run_main(json.dumps({"tool_name": "Agent"}))
+
+    assert exit_status in (None, 0)
+    assert tracker_path.exists()

package/package.json

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

package/rules/failure-blast-radius.md

@@ -0,0 +1,126 @@
+# Failure Blast Radius
+
+**When this applies:** Batch code that processes assets, rows, accounts, messages, or files where one member can fail while the others are fine.
+
+## Rule
+
+A check that raises decides two things at once: that a condition requires action, and what stops because of it. Name the second one.
+
+An exception type ending in `RunFatal` says the whole run stops. An exception type ending in `ItemBlocked` says this one member stops and the batch carries on. Every raise reached through per-member work uses one or the other.
+
+Define `RunFatal` outside the `ItemBlocked` inheritance branch. The per-member boundary routes `ItemBlocked` to parking, while a `RunFatal` escalation passes straight through to the run-level branch.
+
+## What ends a run
+
+Four failures end a run, and they share one property: continuing compromises delivery integrity.
+
+Three of them are declared, and carry a `RunFatal` type:
+
+- The source bytes changed under the run.
+- A provenance or digest comparison failed.
+- Authentication is required.
+
+The fourth is a runtime crash, such as `TypeError` or `AttributeError`. Its runtime type reaches run-level handling because the per-member boundary recognizes the contract's named types.
+
+All remaining failures are member failures. A size mismatch, an optional input error, a path resolution error, or a manifest-field error each stops one member while the batch continues with its other members.
+
+## The boundary
+
+Put the `try`/`except` inside the loop body, around the per-member work:
+
+```python
+for each_member in all_members:
+    try:
+        remaster(each_member)
+    except AssetRunFatal:
+        raise
+    except AssetItemBlocked as failure:
+        park(each_member, failure)
+```
+
+The re-raise comes first, sending an escalation directly through the boundary.
+
+**The boundary recognizes declared types.** A runtime crash inside member work — a `TypeError`, an `AttributeError` — ends the run because its type identifies a code defect. `except Exception` triggers the rule (`CODE_RULES.md` §31).
+
+## Repair, park, and the deliverable
+
+An agent that hits a member failure keeps working the problem. Three things bound how:
+
+- **Repair in place.** The current run preserves every completed member.
+- **Three real attempts, then park.** An attempt is a theory of the cause, acted on. Re-running the same code on the same input counts as one attempt. Three theories cover the obvious cause, the second guess, and the cause revealed by the first two attempts. Judgment selects each theory; the third attempt sets the stopping point. After the third theory fails, park the member with its reason and move to the next. Parked members return after the batch.
+- **The batch always reaches a deliverable.** Complete every member that can complete, produce the packaged artifact, then work the parked list. A run with 34 of 37 members complete and 3 parked records progress and continues to delivery.
+
+## Three alike means one cause
+
+When three or more members park with the same failure signature — same exception type, same `file:line` — one shared defect affects all three members. Route repair to the shared cause.
+
+The run report groups parked members by that signature and names every group of three or more as a suspected shared cause. The raise site provides a reliable grouping key and removes message-text normalization.
+
+## Close the run with every outcome
+
+Every issue the run hit gets one line in the closing report: what failed, and how it ended — repaired, worked around, or parked. Members that finished after a repair belong in that list beside the parked ones. A workaround patched past mid-run is the likeliest real defect in the batch, because the closing report becomes its durable record.
+
+The report then presents each candidate to the owner for a durable-fix decision, names the fixes the run recommends, and waits for the answer. The next run builds the selected fix; the current run completes its deliverable first.
+
+## Enforcement
+
+`code_rules_blast_radius.py` (PreToolUse on Write and Edit, hosted by `code_rules_enforcer.py`) requires each raised type written directly inside a loop body to end in `RunFatal` or `ItemBlocked`. The lexical check covers raises written directly in loop bodies. Shared helpers carry multiple caller contexts, so their callers classify the boundary.
+
+Findings use baseline content for each edit. A raise present on disk remains accepted during the edit; the gate evaluates newly written raises.
+
+## Excerpt for repository-instruction sessions
+
+Codex reads its repository `AGENTS.md`; this excerpt supplies the standalone failure-handling contract.
+
+```
+Failure handling for this run — from rules/failure-blast-radius.md.
+
+Keep solving problems. You own the fix. Each blast radius sets the repair
+scope, and the deliverable remains the run priority.
+
+Repair in place and preserve every completed asset in the current run.
+
+Three real attempts, then park. An attempt is a theory of the cause, acted
+on. Repeated execution of one theory remains one attempt.
+Three theories cover the obvious cause, the second guess, and the cause
+revealed by the first two attempts. Use your judgment to select each theory;
+the third attempt sets the stopping point. After the third theory fails, park
+the asset with its reason and continue. Parked assets return after the batch.
+
+The batch always reaches a deliverable. Finish every asset you can, produce
+the packaged artifact, then work the parked list.
+
+When three or more assets fail the same way, one shared defect affects all
+three assets. Route repair to the shared cause.
+
+Four things end a run outright: the source bytes changed, a provenance or
+digest mismatch, authentication is required, or the code crashed with a
+runtime failure that requires run-level handling. Work every other failure. The
+named-type boundary defines the accepted exception handling; broad `except`
+handling triggers the rule.
+
+When you add a check that raises, name what it stops. End the type in
+RunFatal when the whole run stops, or ItemBlocked when a single asset
+stops. For an asset-level stop, put the handling inside the loop body.
+
+Close the run by reporting what broke and what you did about it. Every issue
+gets one line: what failed, and how it ended — repaired, worked around, or
+parked. Include the ones you solved; a workaround you patched past in attempt
+two is the likeliest real defect in the list, because the closing report becomes
+its durable record.
+Present each candidate for the owner's durable-fix decision, state which fixes
+you recommend and why, and wait for the answer. The next run builds the
+selected durable fix after this run completes its deliverable.
+
+Report as: N of M complete, K parked, and what you are working now.
+Close with: what broke, how each one ended, and which of them deserve a
+durable fix.
+```
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`code-standards.md`](code-standards.md) | `CODE_RULES.md` §9.7 names the boundary that turns a recorded per-member failure into an explicit outcome |
+| [`confirm-implementation-forks.md`](confirm-implementation-forks.md) | A defect correction creates an implementation fork when it routes around parking; surface and decide that fork |
+| [`long-horizon-autonomy.md`](long-horizon-autonomy.md) | A parked member receives an explicit report entry and follow-up |