claude-dev-env 1.50.4 → 1.51.0

package/CLAUDE.md

@@ -9,8 +9,6 @@ The user delegates execution to you and expects zero manual steps unless strictl
 ## Code Rules
 @~/.claude/docs/CODE_RULES.md
 
-When an edit deletes or rewrites code, delete everything it orphans in the same edit — unused variables, uncalled functions, unpassed parameters, dead branches, unused imports — once Serena's `find_referencing_symbols` (plus a text search for dynamic lookups) confirms they're unreachable from any live entry point, not merely unreferenced; when liveness is uncertain, ask via AskUserQuestion rather than risk deleting live code (CODE_RULES.md §9.8).
-
 ALWAYS call the AskUserQuestion tool if you have a question for the user. Provide content-appropriate default options, with a flag for the recommended one.
 
 ## Timeless Documentation (all `.md` files)
@@ -29,12 +27,6 @@ When making code changes, make sure you are working in the proper worktree path
 
 `Edit` changes existing files; `Write` creates new ones. Default to `Edit` — reach for `Write` only for a genuinely new path. For a true full rewrite, delete the file first, then `Write`.
 
-## File-Global Constants
-
-**file_global_constants_use_count:** Every module-level constant in production code outside `config/` must be referenced by at least two methods, functions, or classes in the same file. One reference → move to `config/` and import as a local alias. Zero references → delete (dead code). Test files are exempt.
-
-Full rule including the decision table, examples, and exemption details: [`packages/claude-dev-env/rules/file-global-constants.md`](rules/file-global-constants.md).
-
 ## Test Philosophy
 
 When writing tests, always write tests that actually test the behavior of the function against actual, real data and environments.

package/_shared/pr-loop/audit-contract.md

@@ -21,7 +21,7 @@ Each finding an audit produces MUST be one of exactly two shapes.
   "id": "loop<N>-<K>",
   "file": "path/relative/to/repo/root.py",
   "line": 123,
-  "category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N",
+  "category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P",
   "severity": "P0 | P1 | P2",
   "excerpt": "verbatim code snippet from the offending line(s)",
   "failure_mode": "one sentence describing what goes wrong and when",
@@ -37,7 +37,7 @@ Used when an audit investigates a category and does NOT find a bug. Bare "verifi
 
 ```json
 {
-  "category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N",
+  "category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P",
   "files_opened": ["file1.py", "file2.py"],
   "lines_quoted": [
     {"file": "file1.py", "line": 88, "text": "verbatim line content"}
@@ -120,7 +120,7 @@ Sequence:
 3. Run `py_compile` (or language-equivalent) on each modified file.
 4. Compute `fix_diff` against pre-fix contents for the modified set.
 5. Run `bugteam_code_rules_gate.py` with explicit paths for every modified file.
-6. Spawn a scoped audit of `fix_diff` with full A–N rigor, Shape A/B contract, adversarial pass, AND Haiku secondary in parallel (paranoid mode on post-fix).
+6. Spawn a scoped audit of `fix_diff` with full A–P rigor, Shape A/B contract, adversarial pass, AND Haiku secondary in parallel (paranoid mode on post-fix).
 7. Read the previous loop's outcome XML (`<worktree_path>/.bugteam-pr<N>-loop<L-1>.outcomes.xml`) and obtain its total finding count. If this is the first loop (L <= 1) or the file does not exist, skip this comparison. Compute the post-fix total: previous total minus bugs fixed in this round plus new violations found in the post-fix audit (step 6). If the post-fix total exceeds the previous total, flag all new findings as same-loop fix-targets and revise. An increase in total findings across loop transitions is a regression.
 8. Any new findings become same-loop fix-targets. Internal iteration count increments by one.
 9. After 3 internal iterations with fresh findings each time, exit `stuck: post-fix audit not converging`.

package/_shared/pr-loop/scripts/pr_loop_shared_constants/preflight_self_heal_constants.py

@@ -0,0 +1,28 @@
+"""Configuration constants for the preflight self-heal helper.
+
+The helper unsets any local-scope ``core.hooksPath`` entry git seeds into a
+new worktree's config so the canonical global setting takes effect without
+preflight surfacing a failure or invoking the auto-remediation script.
+"""
+
+from __future__ import annotations
+
+ALL_GIT_CONFIG_LOCAL_GET_ALL_HOOKS_PATH_ARGUMENTS: tuple[str, ...] = (
+    "config",
+    "--local",
+    "--get-all",
+    "core.hooksPath",
+)
+ALL_GIT_CONFIG_LOCAL_UNSET_ALL_HOOKS_PATH_ARGUMENTS: tuple[str, ...] = (
+    "config",
+    "--local",
+    "--unset-all",
+    "core.hooksPath",
+)
+ALL_GIT_CONFIG_GLOBAL_GET_ALL_HOOKS_PATH_COMMAND: tuple[str, ...] = (
+    "git",
+    "config",
+    "--global",
+    "--get-all",
+    "core.hooksPath",
+)

package/_shared/pr-loop/scripts/preflight.py

@@ -39,6 +39,7 @@ from pr_loop_shared_constants.preflight_constants import (
     PYTHON_FILE_SUFFIX,
     TESTS_DIRECTORY_NAME,
 )
+from preflight_self_heal import silently_clear_stale_local_hooks_path_override  # noqa: E402
 from reviews_disabled import (
     CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
     CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME,
@@ -50,9 +51,17 @@ from reviews_disabled import (
 def verify_git_hooks_path(repository_root: Path | None = None) -> int:
     """Check that core.hooksPath resolves to the claude-dev-env git-hooks directory.
 
-    When *repository_root* is provided, queries the effective config for that
-    repository (``git -C <root> config --get``), which detects repo-level
-    overrides such as Husky or lefthook. Falls back to the current working
+    Silently clears any stale, non-canonical local-scope core.hooksPath
+    override before querying the effective config, so a worktree-seeded local
+    entry cannot shadow a correctly configured global setting. When
+    *repository_root* is provided, queries the effective config for that
+    repository (``git -C <root> config --get``). When a canonical global
+    ``core.hooksPath`` is already configured, the preceding self-heal step
+    clears non-canonical local-scope entries, so repo-level overrides such
+    as Husky or lefthook at local scope are silently removed in favor of
+    the canonical global; when the global is unset or non-canonical, the
+    self-heal stands down and the ``--get`` query still surfaces those
+    overrides through the failure path. Falls back to the current working
     directory's effective config when *repository_root* is None.
 
     Args:
@@ -64,6 +73,9 @@ def verify_git_hooks_path(repository_root: Path | None = None) -> int:
         Non-zero and prints a correction message when unset or pointing elsewhere.
     """
     expected_hooks_path_suffix = HOOKS_PATH_VERIFICATION_SUFFIX
+    silently_clear_stale_local_hooks_path_override(
+        repository_root, expected_hooks_path_suffix
+    )
     enforcement_absent_message = (
         "Git-side CODE_RULES enforcement is not active on this host.\n"
         "Run: npx claude-dev-env .\n"
@@ -75,7 +87,7 @@ def verify_git_hooks_path(repository_root: Path | None = None) -> int:
         git_command.extend(["-C", str(repository_root)])
     git_command.extend(list(ALL_GIT_CONFIG_GET_CORE_HOOKS_PATH_SUBCOMMAND))
     try:
-        query_result = subprocess.run(
+        query_completed_process = subprocess.run(
             git_command,
             capture_output=True,
             text=True,
@@ -97,13 +109,13 @@ def verify_git_hooks_path(repository_root: Path | None = None) -> int:
             file=sys.stderr,
         )
         return 1
-    if query_result.returncode != 0:
+    if query_completed_process.returncode != 0:
         print(
             f"bugteam_preflight: {enforcement_absent_message}",
             file=sys.stderr,
         )
         return 1
-    configured_path = query_result.stdout.strip().replace("\\", "/").rstrip("/")
+    configured_path = query_completed_process.stdout.strip().replace("\\", "/").rstrip("/")
     if not configured_path.endswith(expected_hooks_path_suffix):
         print(
             f"bugteam_preflight: core.hooksPath is '{configured_path}' — "

package/_shared/pr-loop/scripts/preflight_self_heal.py

@@ -0,0 +1,164 @@
+"""Self-heal helper for stale local-scope ``core.hooksPath`` overrides.
+
+Git seeds ``core.hooksPath = <repo>/.git/hooks`` into every new worktree's
+local config. That repo-local entry shadows the correct global setting and
+breaks downstream hook-dependent skills. The helper here is called from both
+:mod:`bugteam_preflight` (skill-local) and :mod:`preflight` (shared) so the
+shadowing entry is cleared the first time preflight runs against a fresh
+worktree, without any caller-visible failure.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+_parent_directory = str(Path(__file__).resolve().parent)
+if _parent_directory not in sys.path:
+    sys.path.insert(0, _parent_directory)
+
+from pr_loop_shared_constants.preflight_self_heal_constants import (  # noqa: E402
+    ALL_GIT_CONFIG_GLOBAL_GET_ALL_HOOKS_PATH_COMMAND,
+    ALL_GIT_CONFIG_LOCAL_GET_ALL_HOOKS_PATH_ARGUMENTS,
+    ALL_GIT_CONFIG_LOCAL_UNSET_ALL_HOOKS_PATH_ARGUMENTS,
+)
+
+
+def _is_canonical_hooks_path_entry(
+    raw_hooks_path_entry: str,
+    expected_hooks_path_suffix: str,
+) -> bool:
+    """Return True when *raw_hooks_path_entry* matches the canonical hooks suffix.
+
+    Args:
+        raw_hooks_path_entry: A core.hooksPath entry as written in git config.
+        expected_hooks_path_suffix: The canonical suffix the caller expects
+            (the bugteam and shared callers each pass their own constant so
+            the helper does not need to know which suffix is in force).
+
+    Returns:
+        True when, after Windows-to-POSIX separator normalization and trailing
+        slash stripping, the entry ends with *expected_hooks_path_suffix*.
+    """
+    return (
+        raw_hooks_path_entry.replace("\\", "/")
+        .rstrip("/")
+        .endswith(expected_hooks_path_suffix)
+    )
+
+
+def _canonical_global_hooks_path_is_set(expected_hooks_path_suffix: str) -> bool:
+    """Return True when ``git config --global core.hooksPath`` has a canonical value.
+
+    Reads the global scope with ``--get-all`` so a multi-valued global key
+    does not produce a git "more than one value" exit code. Any one canonical
+    entry among the global values is enough.
+
+    Args:
+        expected_hooks_path_suffix: The canonical suffix to check against.
+
+    Returns:
+        True when at least one global value normalizes to the canonical
+        suffix; False when git is missing, the read fails, or no global value
+        is canonical.
+    """
+    try:
+        global_read_completed_process = subprocess.run(
+            list(ALL_GIT_CONFIG_GLOBAL_GET_ALL_HOOKS_PATH_COMMAND),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+    except (FileNotFoundError, OSError):
+        return False
+    if global_read_completed_process.returncode != 0:
+        return False
+    all_global_hooks_path_entries = [
+        each_line.strip()
+        for each_line in global_read_completed_process.stdout.splitlines()
+        if each_line.strip()
+    ]
+    return any(
+        _is_canonical_hooks_path_entry(
+            each_global_hooks_path_entry, expected_hooks_path_suffix
+        )
+        for each_global_hooks_path_entry in all_global_hooks_path_entries
+    )
+
+
+def silently_clear_stale_local_hooks_path_override(
+    repository_root: Path | None,
+    expected_hooks_path_suffix: str,
+) -> None:
+    """Remove every stale, non-canonical local-scope core.hooksPath override.
+
+    The unset runs only when BOTH conditions hold: at least one local-scope
+    entry is non-canonical, AND a canonical global setting is already
+    configured. When the global is unset or non-canonical, the helper stands
+    down so the downstream ``core.hooksPath is '<path>'`` diagnostic stays
+    informative and the auto-remediation script can repair the global from a
+    known starting point.
+
+    Silent on every git outcome — read errors, write errors, and process
+    launch errors are all suppressed so an unrelated git failure cannot block
+    preflight. The caller's subsequent ``--get`` verification step surfaces
+    the final config state through the normal failure path, so a real
+    misconfiguration is still reported with the canonical
+    ``core.hooksPath is '<path>'`` diagnostic.
+
+    Args:
+        repository_root: Repository root to operate on; a None argument is a
+            no-op so callers without a resolved root can call unconditionally.
+        expected_hooks_path_suffix: The canonical suffix used to classify
+            entries as canonical or stale.
+    """
+    if repository_root is None:
+        return
+    read_command: list[str] = ["git", "-C", str(repository_root)]
+    read_command.extend(list(ALL_GIT_CONFIG_LOCAL_GET_ALL_HOOKS_PATH_ARGUMENTS))
+    try:
+        read_completed_process = subprocess.run(
+            read_command,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+    except (FileNotFoundError, OSError):
+        return
+    if read_completed_process.returncode != 0:
+        return
+    all_local_hooks_path_entries = [
+        each_line.strip()
+        for each_line in read_completed_process.stdout.splitlines()
+        if each_line.strip()
+    ]
+    if not all_local_hooks_path_entries:
+        return
+    has_non_canonical_local_hooks_path_entry = any(
+        not _is_canonical_hooks_path_entry(
+            each_local_hooks_path_entry, expected_hooks_path_suffix
+        )
+        for each_local_hooks_path_entry in all_local_hooks_path_entries
+    )
+    if not has_non_canonical_local_hooks_path_entry:
+        return
+    if not _canonical_global_hooks_path_is_set(expected_hooks_path_suffix):
+        return
+    unset_command: list[str] = ["git", "-C", str(repository_root)]
+    unset_command.extend(list(ALL_GIT_CONFIG_LOCAL_UNSET_ALL_HOOKS_PATH_ARGUMENTS))
+    try:
+        subprocess.run(
+            unset_command,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+    except (FileNotFoundError, OSError):
+        return

package/_shared/pr-loop/scripts/tests/test_preflight.py

@@ -233,6 +233,44 @@ def test_preflight_uses_shared_hooks_path_suffix_constant() -> None:
     assert exit_code == 0
 
 
+def test_verify_git_hooks_path_invokes_self_heal_before_effective_query(
+    tmp_path: Path,
+) -> None:
+    """Shared verify_git_hooks_path must delegate to self-heal before --get.
+
+    Mirrors the bugteam-side guard so a future refactor that drops the
+    silently_clear_stale_local_hooks_path_override call in the shared
+    preflight would be caught.
+    """
+    canonical_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
+    canonical_hooks_path.mkdir(parents=True)
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            str(canonical_hooks_path) + "\n", returncode=0
+        )
+        preflight.verify_git_hooks_path(tmp_path)
+    all_called_commands = [
+        each_call_args[0][0] for each_call_args in mock_run.call_args_list
+    ]
+    has_self_heal_local_read = any(
+        "--get-all" in each_command for each_command in all_called_commands
+    )
+    has_effective_query = any(
+        "--get" in each_command and "--get-all" not in each_command
+        for each_command in all_called_commands
+    )
+    assert has_self_heal_local_read, (
+        "verify_git_hooks_path must run the --local --get-all read for self-heal"
+    )
+    assert has_effective_query, (
+        "verify_git_hooks_path must still run the effective --get verification"
+    )
+    first_called_command = all_called_commands[0]
+    assert "--get-all" in first_called_command, (
+        "Self-heal must run BEFORE the effective config query, not after"
+    )
+
+
 def test_preflight_skip_uses_shared_env_var_constant(
     capsys: pytest.CaptureFixture[str],
     monkeypatch: pytest.MonkeyPatch,
@@ -428,6 +466,7 @@ def test_main_should_not_double_print_when_git_ls_fails(
         patch.object(preflight, "run_pytest", return_value=0) as mock_pytest,
     ):
         mock_run.side_effect = [
+            mock_hooks_result,
             mock_hooks_result,
             subprocess.CalledProcessError(128, ["git", "ls-files"]),
         ]

package/_shared/pr-loop/scripts/tests/test_preflight_self_heal.py

@@ -0,0 +1,273 @@
+"""Tests for the preflight self-heal helper.
+
+Each test mocks ``subprocess.run`` with an ordered ``side_effect`` list so the
+helper's three potential calls (local read, global read, local unset) are
+distinguishable.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent.parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+import preflight_self_heal
+
+
+CANONICAL_SUFFIX = "hooks/git-hooks"
+
+
+def _make_completed_process(
+    stdout: str, returncode: int
+) -> subprocess.CompletedProcess:
+    process = MagicMock(spec=subprocess.CompletedProcess)
+    process.stdout = stdout
+    process.returncode = returncode
+    return process
+
+
+def _was_called_with_argument(
+    mock_subprocess_run: MagicMock, expected_argument: str
+) -> bool:
+    """Return True when *expected_argument* appears as an element of any call's argv.
+
+    Uses list-membership (Python ``in`` on a list is element-equality), so
+    `"--get"` matches `["git", "config", "--get", ...]` but not
+    `["git", "config", "--get-all", ...]`.
+    """
+    return any(
+        expected_argument in each_call_args[0][0]
+        for each_call_args in mock_subprocess_run.call_args_list
+    )
+
+
+def test_is_canonical_when_suffix_matches() -> None:
+    assert preflight_self_heal._is_canonical_hooks_path_entry(
+        "/home/me/.claude/hooks/git-hooks", CANONICAL_SUFFIX
+    )
+
+
+def test_is_canonical_normalizes_windows_separators_and_trailing_slash() -> None:
+    assert preflight_self_heal._is_canonical_hooks_path_entry(
+        "C:\\Users\\me\\.claude\\hooks\\git-hooks\\", CANONICAL_SUFFIX
+    )
+
+
+def test_is_canonical_rejects_non_matching_suffix() -> None:
+    assert not preflight_self_heal._is_canonical_hooks_path_entry(
+        "/some/other/path/.husky", CANONICAL_SUFFIX
+    )
+
+
+def test_is_canonical_rejects_seeded_git_hooks_path() -> None:
+    assert not preflight_self_heal._is_canonical_hooks_path_entry(
+        "/repo/.git/hooks", CANONICAL_SUFFIX
+    )
+
+
+def test_canonical_global_helper_returns_true_for_canonical_value() -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            "/home/me/.claude/hooks/git-hooks\n", returncode=0
+        )
+        assert preflight_self_heal._canonical_global_hooks_path_is_set(CANONICAL_SUFFIX)
+
+
+def test_canonical_global_helper_returns_false_when_unset() -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process("", returncode=1)
+        assert not preflight_self_heal._canonical_global_hooks_path_is_set(
+            CANONICAL_SUFFIX
+        )
+
+
+def test_canonical_global_helper_returns_false_when_non_canonical() -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            "/some/other/path/.husky\n", returncode=0
+        )
+        assert not preflight_self_heal._canonical_global_hooks_path_is_set(
+            CANONICAL_SUFFIX
+        )
+
+
+def test_canonical_global_helper_normalizes_trailing_whitespace_and_separators() -> (
+    None
+):
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            "  C:\\Users\\me\\.claude\\hooks\\git-hooks  \n", returncode=0
+        )
+        assert preflight_self_heal._canonical_global_hooks_path_is_set(CANONICAL_SUFFIX)
+
+
+def test_canonical_global_helper_returns_true_when_any_multi_value_is_canonical() -> (
+    None
+):
+    multi_global_entries = "/some/other/path/.husky\n/home/me/.claude/hooks/git-hooks\n"
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            multi_global_entries, returncode=0
+        )
+        assert preflight_self_heal._canonical_global_hooks_path_is_set(CANONICAL_SUFFIX)
+
+
+def test_canonical_global_helper_returns_false_when_git_missing() -> None:
+    with patch("subprocess.run", side_effect=FileNotFoundError()):
+        assert not preflight_self_heal._canonical_global_hooks_path_is_set(
+            CANONICAL_SUFFIX
+        )
+
+
+def test_canonical_global_helper_returns_false_when_os_error() -> None:
+    with patch("subprocess.run", side_effect=OSError("permission denied")):
+        assert not preflight_self_heal._canonical_global_hooks_path_is_set(
+            CANONICAL_SUFFIX
+        )
+
+
+def test_silent_clear_is_noop_when_repository_root_is_none() -> None:
+    with patch("subprocess.run") as mock_run:
+        preflight_self_heal.silently_clear_stale_local_hooks_path_override(
+            None, CANONICAL_SUFFIX
+        )
+    assert mock_run.call_count == 0
+
+
+def test_silent_clear_is_noop_when_local_core_hooks_path_unset() -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process("", returncode=1)
+        preflight_self_heal.silently_clear_stale_local_hooks_path_override(
+            Path("."), CANONICAL_SUFFIX
+        )
+    assert mock_run.call_count == 1
+    assert not _was_called_with_argument(mock_run, "--unset-all")
+
+
+def test_silent_clear_is_noop_when_local_value_is_canonical(tmp_path: Path) -> None:
+    canonical_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
+    canonical_hooks_path.mkdir(parents=True)
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            str(canonical_hooks_path) + "\n", returncode=0
+        )
+        preflight_self_heal.silently_clear_stale_local_hooks_path_override(
+            Path("."), CANONICAL_SUFFIX
+        )
+    assert not _was_called_with_argument(mock_run, "--unset-all")
+
+
+def test_silent_clear_unsets_stale_worktree_seeded_local_value(tmp_path: Path) -> None:
+    """Git seeds <repo>/.git/hooks into worktree-local config; preflight must heal it."""
+    seeded_local_path_text = "/repo/.git/hooks"
+    canonical_global_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
+    canonical_global_hooks_path.mkdir(parents=True)
+    with patch("subprocess.run") as mock_run:
+        mock_run.side_effect = [
+            _make_completed_process(seeded_local_path_text + "\n", returncode=0),
+            _make_completed_process(
+                str(canonical_global_hooks_path) + "\n", returncode=0
+            ),
+            _make_completed_process("", returncode=0),
+        ]
+        preflight_self_heal.silently_clear_stale_local_hooks_path_override(
+            Path("/repo"), CANONICAL_SUFFIX
+        )
+    assert _was_called_with_argument(mock_run, "--unset-all")
+    assert _was_called_with_argument(mock_run, "--local")
+
+
+def test_silent_clear_unsets_when_any_local_entry_is_non_canonical(
+    tmp_path: Path,
+) -> None:
+    canonical_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
+    canonical_hooks_path.mkdir(parents=True)
+    mixed_entries_text = f"{canonical_hooks_path}\n/some/other/path/.husky\n"
+    with patch("subprocess.run") as mock_run:
+        mock_run.side_effect = [
+            _make_completed_process(mixed_entries_text, returncode=0),
+            _make_completed_process(str(canonical_hooks_path) + "\n", returncode=0),
+            _make_completed_process("", returncode=0),
+        ]
+        preflight_self_heal.silently_clear_stale_local_hooks_path_override(
+            Path("."), CANONICAL_SUFFIX
+        )
+    assert _was_called_with_argument(mock_run, "--unset-all")
+
+
+def test_silent_clear_stands_down_when_global_is_unset() -> None:
+    seeded_local_path_text = "/repo/.git/hooks"
+    with patch("subprocess.run") as mock_run:
+        mock_run.side_effect = [
+            _make_completed_process(seeded_local_path_text + "\n", returncode=0),
+            _make_completed_process("", returncode=1),
+        ]
+        preflight_self_heal.silently_clear_stale_local_hooks_path_override(
+            Path("/repo"), CANONICAL_SUFFIX
+        )
+    assert not _was_called_with_argument(mock_run, "--unset-all")
+
+
+def test_silent_clear_stands_down_when_global_is_non_canonical() -> None:
+    seeded_local_path_text = "/repo/.git/hooks"
+    non_canonical_global_text = "/some/other/path/.husky"
+    with patch("subprocess.run") as mock_run:
+        mock_run.side_effect = [
+            _make_completed_process(seeded_local_path_text + "\n", returncode=0),
+            _make_completed_process(non_canonical_global_text + "\n", returncode=0),
+        ]
+        preflight_self_heal.silently_clear_stale_local_hooks_path_override(
+            Path("/repo"), CANONICAL_SUFFIX
+        )
+    assert not _was_called_with_argument(mock_run, "--unset-all")
+
+
+def test_silent_clear_swallows_file_not_found_error() -> None:
+    with patch("subprocess.run", side_effect=FileNotFoundError()):
+        preflight_self_heal.silently_clear_stale_local_hooks_path_override(
+            Path("."), CANONICAL_SUFFIX
+        )
+
+
+def test_silent_clear_swallows_os_error() -> None:
+    with patch("subprocess.run", side_effect=OSError("permission denied")):
+        preflight_self_heal.silently_clear_stale_local_hooks_path_override(
+            Path("."), CANONICAL_SUFFIX
+        )
+
+
+def test_silent_clear_swallows_file_not_found_error_on_unset_call(tmp_path: Path) -> None:
+    """A spawn-level FileNotFoundError on the unset-all write must not crash preflight."""
+    seeded_local_path_text = "/repo/.git/hooks"
+    canonical_global_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
+    canonical_global_hooks_path.mkdir(parents=True)
+    with patch("subprocess.run") as mock_run:
+        mock_run.side_effect = [
+            _make_completed_process(seeded_local_path_text + "\n", returncode=0),
+            _make_completed_process(str(canonical_global_hooks_path) + "\n", returncode=0),
+            FileNotFoundError(),
+        ]
+        preflight_self_heal.silently_clear_stale_local_hooks_path_override(
+            Path("/repo"), CANONICAL_SUFFIX
+        )
+
+
+def test_silent_clear_swallows_os_error_on_unset_call(tmp_path: Path) -> None:
+    """A spawn-level OSError on the unset-all write must not crash preflight."""
+    seeded_local_path_text = "/repo/.git/hooks"
+    canonical_global_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
+    canonical_global_hooks_path.mkdir(parents=True)
+    with patch("subprocess.run") as mock_run:
+        mock_run.side_effect = [
+            _make_completed_process(seeded_local_path_text + "\n", returncode=0),
+            _make_completed_process(str(canonical_global_hooks_path) + "\n", returncode=0),
+            OSError("permission denied"),
+        ]
+        preflight_self_heal.silently_clear_stale_local_hooks_path_override(
+            Path("/repo"), CANONICAL_SUFFIX
+        )

package/agents/clean-coder.md

@@ -438,7 +438,7 @@ Docstrings on functions, methods, classes, and modules are encouraged for public
 
 ## Audit Awareness
 
-Code clean-coder writes will be audited later against the A–N bug categories from `code-quality-agent`. The hooks listed in this file enforce the Category J slice at write time, but A–I and K–N surface only in audit. For each category's full rubric, sub-bucket decomposition, and concrete checks, see `../audit-rubrics/category_rubrics/` (relative to this agent file). While generating code, anticipate the full A–N surface so the first write clears every audit category.
+Code clean-coder writes will be audited later against the A–P bug categories from `code-quality-agent`. The hooks listed in this file enforce the Category J slice at write time, but A–I and K–P surface only in audit. For each category's full rubric, sub-bucket decomposition, and concrete checks, see `../audit-rubrics/category_rubrics/` (relative to this agent file). While generating code, anticipate the full A–P surface so the first write clears every audit category.
 
 Three audit lanes deserve particular attention while generating new code: