claude-dev-env 1.30.1 → 1.32.0

package/hooks/session/session_env_cleanup.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""SessionStart hook — clean the Claude Code session-env directory on Windows.
+
+Claude Code's Bash tool sets up a per-session sandbox at
+``~/.claude/session-env/<session_id>/``. The mkdir call appears non-recursive,
+so once the directory exists, later Bash invocations in the same session can
+throw ``EEXIST`` and abort. PowerShell tool calls are unaffected.
+
+This hook removes the current session's pre-existing directory at start and
+prunes sibling entries whose mtime is older than the stale-age threshold so
+the parent directory does not grow without bound.
+
+Tracking: https://github.com/anthropics/claude-code/issues — Windows-only
+mkdir bug separate from the EEXIST fixes in v2.1.70-v2.1.72.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import stat
+import sys
+import time
+from pathlib import Path
+from typing import Callable
+
+
+def _insert_hooks_tree_for_imports() -> None:
+    hooks_tree = Path(__file__).resolve().parent.parent
+    hooks_tree_string = str(hooks_tree)
+    if hooks_tree_string not in sys.path:
+        sys.path.insert(0, hooks_tree_string)
+
+
+_insert_hooks_tree_for_imports()
+
+from config.session_env_cleanup_constants import (
+    RMTREE_ONEXC_PYTHON_VERSION,
+    SESSION_ENV_DIRECTORY,
+    SESSION_ID_PATTERN,
+    STALE_AGE_SECONDS,
+    WINDOWS_PLATFORM_TAG,
+)
+
+
+def _strip_read_only_and_retry(
+    removal_function: Callable[[str], None],
+    target_path: str,
+    *_unused_exception_info: object,
+) -> None:
+    try:
+        os.chmod(target_path, stat.S_IWRITE)
+        removal_function(target_path)
+    except OSError:
+        pass
+
+
+def _force_rmtree(target_path: str) -> None:
+    rmtree_onexc_python_version = RMTREE_ONEXC_PYTHON_VERSION
+    try:
+        if sys.version_info >= rmtree_onexc_python_version:
+            shutil.rmtree(target_path, onexc=_strip_read_only_and_retry)
+        else:
+            shutil.rmtree(target_path, onerror=_strip_read_only_and_retry)
+    except OSError:
+        pass
+
+
+def prune_session_env(
+    session_env_directory: str,
+    session_id: str,
+    stale_age_seconds: float,
+) -> None:
+    """Remove the current session's directory and prune stale siblings."""
+    if session_id:
+        current_session_path = os.path.join(session_env_directory, session_id)
+        if os.path.isdir(current_session_path):
+            _force_rmtree(current_session_path)
+    if not os.path.isdir(session_env_directory):
+        return
+    stale_cutoff_seconds = time.time() - stale_age_seconds
+    try:
+        all_entry_names = os.listdir(session_env_directory)
+    except OSError:
+        return
+    for each_entry_name in all_entry_names:
+        entry_path = os.path.join(session_env_directory, each_entry_name)
+        try:
+            entry_mtime_seconds = os.path.getmtime(entry_path)
+        except OSError:
+            continue
+        if entry_mtime_seconds >= stale_cutoff_seconds:
+            continue
+        _force_rmtree(entry_path)
+
+
+def _read_session_id_from_stdin() -> str:
+    session_id_pattern = SESSION_ID_PATTERN
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return ""
+    if not isinstance(payload, dict):
+        return ""
+    raw_session_id = payload.get("session_id")
+    if not isinstance(raw_session_id, str):
+        return ""
+    if not session_id_pattern.match(raw_session_id):
+        return ""
+    return raw_session_id
+
+
+def main() -> None:
+    windows_platform_tag = WINDOWS_PLATFORM_TAG
+    if sys.platform != windows_platform_tag:
+        return
+    session_env_directory = SESSION_ENV_DIRECTORY
+    stale_age_seconds = STALE_AGE_SECONDS
+    session_id = _read_session_id_from_stdin()
+    prune_session_env(
+        session_env_directory=session_env_directory,
+        session_id=session_id,
+        stale_age_seconds=stale_age_seconds,
+    )
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session/test_session_env_cleanup.py

@@ -0,0 +1,278 @@
+"""Tests for session_env_cleanup — SessionStart hook for Bash EEXIST workaround."""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import stat
+import sys
+import time
+from pathlib import Path
+from unittest.mock import patch
+
+_SESSION_DIR = Path(__file__).resolve().parent
+_HOOKS_ROOT = _SESSION_DIR.parent
+for each_sys_path_entry in (str(_SESSION_DIR), str(_HOOKS_ROOT)):
+    if each_sys_path_entry not in sys.path:
+        sys.path.insert(0, each_sys_path_entry)
+
+import session_env_cleanup as cleanup
+
+SECONDS_PER_DAY = 24 * 60 * 60
+SEVEN_DAYS_IN_SECONDS = 7 * SECONDS_PER_DAY
+
+
+def _set_mtime_days_ago(target_path: Path, days_ago: float) -> None:
+    target_mtime_seconds = time.time() - (days_ago * SECONDS_PER_DAY)
+    os.utime(target_path, (target_mtime_seconds, target_mtime_seconds))
+
+
+class TestRemovesCurrentSessionDirectory:
+    def test_removes_directory_matching_session_id(self, tmp_path: Path) -> None:
+        current_session_id = "abc-123"
+        current_session_directory = tmp_path / current_session_id
+        current_session_directory.mkdir()
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id=current_session_id,
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert not current_session_directory.exists()
+
+    def test_removes_current_session_directory_with_contents(
+        self, tmp_path: Path
+    ) -> None:
+        current_session_id = "abc-123"
+        current_session_directory = tmp_path / current_session_id
+        current_session_directory.mkdir()
+        (current_session_directory / "leftover.txt").write_text("data")
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id=current_session_id,
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert not current_session_directory.exists()
+
+    def test_no_current_session_removal_when_session_id_empty(
+        self, tmp_path: Path
+    ) -> None:
+        sibling_directory = tmp_path / "some-other-session"
+        sibling_directory.mkdir()
+        _set_mtime_days_ago(sibling_directory, days_ago=0)
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id="",
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert sibling_directory.exists()
+
+
+class TestPrunesStaleEntries:
+    def test_removes_entry_older_than_threshold(self, tmp_path: Path) -> None:
+        stale_directory = tmp_path / "old-session"
+        stale_directory.mkdir()
+        _set_mtime_days_ago(stale_directory, days_ago=10)
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id="",
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert not stale_directory.exists()
+
+    def test_keeps_entry_within_threshold(self, tmp_path: Path) -> None:
+        fresh_directory = tmp_path / "fresh-session"
+        fresh_directory.mkdir()
+        _set_mtime_days_ago(fresh_directory, days_ago=2)
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id="",
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert fresh_directory.exists()
+
+    def test_removes_stale_directory_with_contents(self, tmp_path: Path) -> None:
+        stale_directory = tmp_path / "stale-with-content"
+        stale_directory.mkdir()
+        (stale_directory / "leftover.txt").write_text("old data")
+        _set_mtime_days_ago(stale_directory, days_ago=14)
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id="",
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert not stale_directory.exists()
+
+    def test_keeps_fresh_when_pruning_among_mixed_ages(self, tmp_path: Path) -> None:
+        fresh_directory = tmp_path / "fresh-keep"
+        stale_directory = tmp_path / "stale-remove"
+        fresh_directory.mkdir()
+        stale_directory.mkdir()
+        _set_mtime_days_ago(fresh_directory, days_ago=1)
+        _set_mtime_days_ago(stale_directory, days_ago=30)
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id="",
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert fresh_directory.exists()
+        assert not stale_directory.exists()
+
+
+class TestRemovesReadOnlyDirectories:
+    def test_removes_session_directory_with_read_only_contents(
+        self, tmp_path: Path
+    ) -> None:
+        current_session_id = "readonly-session"
+        current_session_directory = tmp_path / current_session_id
+        current_session_directory.mkdir()
+        leftover_file = current_session_directory / "leftover.txt"
+        leftover_file.write_text("data")
+        leftover_file.chmod(stat.S_IREAD)
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id=current_session_id,
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert not current_session_directory.exists()
+
+    def test_prunes_stale_directory_with_read_only_contents(
+        self, tmp_path: Path
+    ) -> None:
+        stale_directory = tmp_path / "stale-readonly"
+        stale_directory.mkdir()
+        stale_file = stale_directory / "old.txt"
+        stale_file.write_text("old data")
+        stale_file.chmod(stat.S_IREAD)
+        _set_mtime_days_ago(stale_directory, days_ago=14)
+        cleanup.prune_session_env(
+            session_env_directory=str(tmp_path),
+            session_id="",
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert not stale_directory.exists()
+
+
+class TestParentDirectoryMissing:
+    def test_returns_silently_when_parent_missing(self, tmp_path: Path) -> None:
+        absent_path = tmp_path / "does-not-exist"
+        cleanup.prune_session_env(
+            session_env_directory=str(absent_path),
+            session_id="abc-123",
+            stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+        )
+        assert not absent_path.exists()
+
+
+class TestMainReadsSessionIdFromStdin:
+    def test_main_invokes_prune_with_stdin_session_id(self, tmp_path: Path) -> None:
+        captured_call = {}
+
+        def fake_prune(
+            session_env_directory: str,
+            session_id: str,
+            stale_age_seconds: float,
+        ) -> None:
+            captured_call["session_id"] = session_id
+
+        stdin_payload = io.StringIO(json.dumps({"session_id": "session-from-stdin"}))
+        with (
+            patch.object(cleanup, "prune_session_env", side_effect=fake_prune),
+            patch("sys.stdin", stdin_payload),
+        ):
+            cleanup.main()
+        assert captured_call["session_id"] == "session-from-stdin"
+
+    def test_main_passes_empty_session_id_when_stdin_invalid(self) -> None:
+        captured_call = {}
+
+        def fake_prune(
+            session_env_directory: str,
+            session_id: str,
+            stale_age_seconds: float,
+        ) -> None:
+            captured_call["session_id"] = session_id
+
+        stdin_payload = io.StringIO("not json at all")
+        with (
+            patch.object(cleanup, "prune_session_env", side_effect=fake_prune),
+            patch("sys.stdin", stdin_payload),
+        ):
+            cleanup.main()
+        assert captured_call["session_id"] == ""
+
+    def test_main_rejects_session_id_with_path_separator(self) -> None:
+        captured_call = {}
+
+        def fake_prune(
+            session_env_directory: str,
+            session_id: str,
+            stale_age_seconds: float,
+        ) -> None:
+            captured_call["session_id"] = session_id
+
+        stdin_payload = io.StringIO(json.dumps({"session_id": "../../../etc/passwd"}))
+        with (
+            patch.object(cleanup, "prune_session_env", side_effect=fake_prune),
+            patch("sys.stdin", stdin_payload),
+            patch.object(cleanup.sys, "platform", "win32"),
+        ):
+            cleanup.main()
+        assert captured_call["session_id"] == ""
+
+    def test_main_rejects_absolute_windows_path_session_id(self) -> None:
+        captured_call = {}
+
+        def fake_prune(
+            session_env_directory: str,
+            session_id: str,
+            stale_age_seconds: float,
+        ) -> None:
+            captured_call["session_id"] = session_id
+
+        stdin_payload = io.StringIO(json.dumps({"session_id": "C:\\Windows\\Temp"}))
+        with (
+            patch.object(cleanup, "prune_session_env", side_effect=fake_prune),
+            patch("sys.stdin", stdin_payload),
+            patch.object(cleanup.sys, "platform", "win32"),
+        ):
+            cleanup.main()
+        assert captured_call["session_id"] == ""
+
+
+class TestMainPlatformGuard:
+    def test_main_no_ops_on_non_windows(self) -> None:
+        captured_call = {"called": False}
+
+        def fake_prune(
+            session_env_directory: str,
+            session_id: str,
+            stale_age_seconds: float,
+        ) -> None:
+            captured_call["called"] = True
+
+        stdin_payload = io.StringIO(json.dumps({"session_id": "abc-123"}))
+        with (
+            patch.object(cleanup, "prune_session_env", side_effect=fake_prune),
+            patch("sys.stdin", stdin_payload),
+            patch.object(cleanup.sys, "platform", "linux"),
+        ):
+            cleanup.main()
+        assert captured_call["called"] is False
+
+
+class TestPruneHandlesListdirFailure:
+    def test_prune_returns_silently_when_listdir_raises(self, tmp_path: Path) -> None:
+        existing_session_directory = tmp_path / "still-there"
+        existing_session_directory.mkdir()
+
+        def raise_oserror(path: str) -> list[str]:
+            raise OSError("simulated listdir failure")
+
+        with patch("os.listdir", side_effect=raise_oserror):
+            cleanup.prune_session_env(
+                session_env_directory=str(tmp_path),
+                session_id="",
+                stale_age_seconds=SEVEN_DAYS_IN_SECONDS,
+            )
+        assert existing_session_directory.exists()

package/package.json

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

package/rules/ask-user-question-required.md

@@ -0,0 +1,44 @@
+# AskUserQuestion Required
+
+**When this applies:** Any time you would ask the user a question during discovery, scoping, or implementation planning — after the `verify-before-asking` decision checklist confirms the question genuinely belongs to the user.
+
+## Rule
+
+Route every user-directed question through the `AskUserQuestion` tool. Embedded plain-text questions in the final paragraph of an assistant message are blocked by a Stop hook, and the response must be re-output with the ask moved into an `AskUserQuestion` tool call.
+
+## Detection Criteria
+
+The `question_to_user_enforcer` Stop hook inspects the last non-empty paragraph of the response after stripping fenced code blocks, inline code (backticks), and blockquoted lines (`> …`). The response is blocked when either signal is present:
+
+- The final paragraph's last sentence ends with a question mark.
+- The final paragraph contains any of these preamble phrases (case-insensitive, word-boundary matched): `would you like`, `should I`, `do you want`, `which would you prefer`, `let me know if`, `let me know which`, `let me know whether`, `please confirm`, `please let me know`, `want me to`.
+
+## Acceptable Plain-Text Question Patterns
+
+These remain allowed and do not trigger the hook:
+
+- **Rhetorical questions answered in the same paragraph.** `"What happens if the queue is empty? The handler short-circuits cleanly."` The question frames its own answer; the reader never has to respond.
+- **Questions inside code, diffs, or documentation excerpts.** Code fences, inline backticks, and `>` blockquotes are stripped before detection. Quoting a GitHub issue title, a user's prior message, or a log line inside a blockquote is fine.
+- **Middle-paragraph questions when the closing paragraph is declarative.** Only the final paragraph is scanned.
+
+## AskUserQuestion Structure
+
+When a question is genuinely for the user, call the tool with:
+
+- A concise `question` string stating what is needed.
+- A `header` of twelve characters or fewer summarizing the decision.
+- Two to four `options`, each with a short `label` the user can pick. An "Other" free-text fallback is already provided by the UI; do not add one manually.
+- `multiSelect: false` unless the user can genuinely combine choices.
+
+## Why
+
+- **Structured options reduce re-reading friction.** The user sees labeled choices directly rather than scanning prose for the ask.
+- **Transcript clarity.** Tool-use entries are easy to locate in the JSONL transcript; prose questions disappear into the response text.
+- **Reduced drift.** Claude's next turn cannot move past an unanswered structured question; prose questions can be silently bypassed.
+
+## Enforcement
+
+- Hook: `packages/claude-dev-env/hooks/blocking/question_to_user_enforcer.py`, registered on the `Stop` matcher in `packages/claude-dev-env/hooks/hooks.json`.
+- Loop prevention: the hook honors Claude Code's `stop_hook_active` flag and does not re-block on retry.
+- User-facing notice: `USER_FACING_ASKUSERQUESTION_NOTICE` in `packages/claude-dev-env/hooks/config/messages.py`.
+- Related rule: `packages/claude-dev-env/rules/verify-before-asking.md` gates whether the question belongs to the user in the first place.

package/rules/windows-filesystem-safe.md

@@ -0,0 +1,93 @@
+# Windows Filesystem Safety
+
+**When this applies:** Any code that recursively deletes directory trees, or that creates directories on Windows where the path may already exist with a `ReadOnly` attribute set.
+
+## Rule 1 — Never use `shutil.rmtree(..., ignore_errors=True)`
+
+`shutil.rmtree` on Windows raises `PermissionError` when it encounters a file carrying the `ReadOnly` attribute (`FILE_ATTRIBUTE_READONLY`). Linux never hits this case because `unlink` on Linux only requires write on the parent directory, not on the file itself. With `ignore_errors=True` the failure is swallowed and the tree stays on disk — cleanup *looks* successful but pruned nothing.
+
+Tests run inside `pytest`'s `tmp_path` do not exercise the regression path because tmp directories do not carry the attribute. The only place this surfaces is real Windows checkouts (notably git working trees, where `.git/objects/pack/` files are read-only by design).
+
+### Tell-tale sign
+
+`rmtree`-based cleanup that "succeeds" against a real Windows directory but the count of removed entries is zero.
+
+### Safe pattern (inline `force_rmtree`)
+
+Replace `ignore_errors=True` with an `onexc`/`onerror` handler that strips the attribute and retries the same syscall:
+
+```python
+import os
+import shutil
+import stat
+import sys
+
+
+def _strip_read_only_and_retry(removal_function, target_path, *_exc_info):
+    try:
+        os.chmod(target_path, stat.S_IWRITE)
+        removal_function(target_path)
+    except OSError:
+        pass
+
+
+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}
+    )
+    try:
+        shutil.rmtree(target_path, **handler_kw)
+    except OSError:
+        pass
+```
+
+Two things to know about the handler:
+
+- `*_exc_info` collapses the signature difference. `onerror` passes `(type, value, traceback)`; `onexc` (Python 3.12+) passes a single exception. The variadic absorbs both.
+- `removal_function` is whichever syscall `rmtree` was attempting when it failed — `os.unlink` for files, `os.rmdir` for directories. Re-calling it after `chmod` finishes the work that originally failed.
+
+### One-liner safe pattern (when shell context demands it)
+
+If a skill or runbook genuinely needs a one-line shell invocation, the equivalent without `ignore_errors=True` is:
+
+```bash
+python -c "import os, shutil, stat, sys; \
+def _h(f, p, *_): os.chmod(p, stat.S_IWRITE); f(p); \
+shutil.rmtree(r'<path>', **({'onexc': _h} if sys.version_info >= (3, 12) else {'onerror': _h}))"
+```
+
+Prefer the multi-line `force_rmtree` helper — the one-liner is hard to read and easy to mis-quote.
+
+## Rule 2 — `mkdirSync` without `{ recursive: true }` on possibly-existing paths
+
+Windows directories can also carry the `ReadOnly` attribute (e.g. anything Claude Code creates under `~/.claude/teams/<name>/`, `~/.claude/session-env/<id>/`). The attribute does not break `shutil.rmtree` directly — it breaks Node's `fs.mkdirSync` when called *without* `{ recursive: true }` on a path that already exists.
+
+### Safe pattern
+
+```javascript
+import { mkdirSync } from 'node:fs';
+
+mkdirSync(targetPath, { recursive: true });
+```
+
+`recursive: true` makes `mkdirSync` idempotent — it succeeds whether the directory exists or not, and skips the attribute check on the existing path.
+
+### When you cannot use `{ recursive: true }`
+
+If the call must be non-recursive for reasons specific to that code path (the existing `bin/git_hooks_installer.mjs` uses `recursive: false` deliberately to assert non-existence), strip the attribute first:
+
+```powershell
+(Get-Item $path -Force).Attributes = "Directory"
+```
+
+```python
+os.chmod(path, stat.S_IWRITE)
+```
+
+…and only then call the non-recursive `mkdir`.
+
+## Enforcement
+
+A `PreToolUse` hook (`windows_rmtree_blocker.py`) blocks any `Write`, `Edit`, or `Bash` invocation whose payload contains `shutil.rmtree(..., ignore_errors=True)` and returns this rule's safe pattern as the corrective message.

package/scripts/config/test_spec_implementer_prompt.py

@@ -21,10 +21,6 @@ def _load_config_module():
 groq_bugteam_config = _load_config_module()
 
 
-def test_spec_implementer_prompt_exists():
-    assert hasattr(groq_bugteam_config, "SPEC_IMPLEMENTER_SYSTEM_PROMPT")
-
-
 def test_spec_implementer_prompt_is_non_empty_string():
     prompt_text = groq_bugteam_config.SPEC_IMPLEMENTER_SYSTEM_PROMPT
     assert isinstance(prompt_text, str)

package/scripts/test_groq_bugteam_spec.py

@@ -36,14 +36,6 @@ def _load_spec_module():
 groq_bugteam_spec = _load_spec_module()
 
 
-def test_apply_fix_from_spec_is_callable():
-    assert callable(groq_bugteam_spec.apply_fix_from_spec)
-
-
-def test_run_spec_mode_main_is_callable():
-    assert callable(groq_bugteam_spec.run_spec_mode_main)
-
-
 def test_is_spec_mode_invocation_detects_flag_value_pair():
     assert groq_bugteam_spec.is_spec_mode_invocation(["--mode", "spec"]) is True
     assert groq_bugteam_spec.is_spec_mode_invocation(["--mode", "pipeline"]) is False

package/skills/bugteam/SKILL.md

@@ -65,6 +65,14 @@ python "${CLAUDE_SKILL_DIR}/scripts/bugteam_preflight.py"
 
 Non-zero → fix before grant. `BUGTEAM_PREFLIGHT_SKIP=1` emergency only. `--pre-commit` if `.pre-commit-config.yaml` exists.
 
+**Auto-remediation for `core.hooksPath`:** when preflight fails with stderr containing `core.hooksPath` (the message starts with `bugteam_preflight: core.hooksPath is`, or `Git-side CODE_RULES enforcement is not active`), Claude must auto-invoke the fix script — do not fall through to `AskUserQuestion`, do not punt to the user, do not ask for confirmation:
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/bugteam_fix_hookspath.py"
+```
+
+The fix script removes any non-canonical local-scope override on the active repository, sets the global `core.hooksPath` to `~/.claude/hooks/git-hooks` if missing or wrong, and re-runs `bugteam_preflight.py`. Its exit code becomes the preflight outcome. Exit 0 → continue to Step 0. Non-zero only when the canonical hooks directory is missing (run `npx claude-dev-env .` first) or `git config --global` writes are blocked. Other preflight failures (pytest, pre-commit) still require manual fixes — the auto-remediation only applies to the `core.hooksPath` failure mode.
+
 ## The Process
 
 ### Progress checklist
@@ -283,7 +291,13 @@ Pass finding comment URLs/ids from `loop_comment_index` in XML. Replies: `Fixed
 
 2. `TeamDelete()`
 
-3. `python -c "import shutil; shutil.rmtree(r'<team_temp_dir>', ignore_errors=True)"`
+3. Windows-safe teardown — `ignore_errors=True` silently swallows ReadOnly-attribute failures on Windows (see `~/.claude/rules/windows-filesystem-safe.md`). Use the inline `force_rmtree` helper:
+
+   ```bash
+   python -c "import os, shutil, stat, sys; \
+   h = lambda f, p, *_: (os.chmod(p, stat.S_IWRITE), f(p)); \
+   shutil.rmtree(r'<team_temp_dir>', **({'onexc': h} if sys.version_info >= (3, 12) else {'onerror': h}))"
+   ```
 
 ### Step 4.5: PR description
 

package/skills/bugteam/SKILL_EVALS.md

@@ -124,7 +124,7 @@ The harness does not yet exist; this document defines its contract.
 | 17 | `Read(".bugteam-loop-2.outcomes.xml")` — zero findings | `SKILL.md` § AUDIT action |
 | 18 | `SendMessage(to="bugfind", message={type: "shutdown_request", reason: "audit loop 2 complete; zero findings"})` | `SKILL.md` § AUDIT action (**Shutdown** fallback) |
 | 19 | `TeamDelete()` | `SKILL.md` § Step 4 |
-| 20 | `Bash("python -c \"import shutil; shutil.rmtree(r'<team_temp_dir>', ignore_errors=True)\"")` | `SKILL.md` § Step 4 |
+| 20 | `Bash("python -c \"import os, shutil, stat, sys; h = lambda f, p, *_: (os.chmod(p, stat.S_IWRITE), f(p)); shutil.rmtree(r'<team_temp_dir>', **({'onexc': h} if sys.version_info >= (3, 12) else {'onerror': h}))\"")` | `SKILL.md` § Step 4 (Windows-safe teardown) |
 | 21 | `Bash("gh pr diff 42 -R ... > .bugteam-final.diff")` | `SKILL.md` § Step 4.5 step 1 |
 | 22 | `Bash("gh pr view 42 -R ... --json body --jq .body > .bugteam-original-body.md")` | `SKILL.md` § Step 4.5 step 2 |
 | 23 | `Agent(subagent_type="pr-description-writer", description=..., prompt=<brief>)` | `SKILL.md` § Step 4.5 |

package/skills/bugteam/reference/teardown-publish-permissions.md

@@ -24,7 +24,7 @@ When the cycle exits (any reason), run these steps in order from **this** sessio
 
 2. **Clean up the team** with `TeamDelete()` (no arguments — reads `<team_name>` from session context). Maps to “clean up the team” in the docs; quote: [`../sources.md`](../sources.md).
 
-3. **Delete the per-team temp directory** using the Python one-liner in `SKILL.md` with the same literal `<team_temp_dir>` from Step 2. `shutil.rmtree(..., ignore_errors=True)` is portable across Windows and Unix.
+3. **Delete the per-team temp directory** using the Python one-liner in `SKILL.md` with the same literal `<team_temp_dir>` from Step 2. The one-liner uses an `onexc`/`onerror` handler that strips the Windows ReadOnly attribute and retries the failing syscall — `ignore_errors=True` is unsafe on Windows because it silently swallows ReadOnly-attribute failures (see `~/.claude/rules/windows-filesystem-safe.md`).
 
 ## Step 4.5 — Finalize the PR description (mandatory)
 

package/skills/bugteam/scripts/README.md

@@ -5,6 +5,7 @@ Scripts in this directory are **executed** by the lead or teammates. They are no
 | Script | Purpose |
 |--------|---------|
 | `bugteam_preflight.py` | Run pytest (when configured) and optional `pre-commit` before `/bugteam`. |
+| `bugteam_fix_hookspath.py` | Auto-remediate a stale local `core.hooksPath` override, set canonical global value, re-run `bugteam_preflight.py`. Invoked by Claude when preflight reports a `core.hooksPath` failure. |
 | `bugteam_code_rules_gate.py` | Run `validate_content` from `code-rules-enforcer.py` on PR-scoped files (`git diff` vs merge-base). Exit `1` if any mandatory rule fails. Invoked **before each audit**; the fixer clears it before the auditor runs. |
 | `grant_project_claude_permissions.py` | Idempotent grant of Edit/Write/Read on `cwd/.claude/**` into `~/.claude/settings.json`. |
 | `revoke_project_claude_permissions.py` | Removes the matching grant entries from `~/.claude/settings.json`. |
@@ -24,6 +25,22 @@ python "${CLAUDE_SKILL_DIR}/scripts/bugteam_preflight.py"
 - Pytest exit code `5` (no tests collected) is treated as success.
 - Add `--pre-commit` to run `pre-commit run --all-files` when `.pre-commit-config.yaml` exists.
 
+## `bugteam_fix_hookspath.py`
+
+From the repository root:
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/bugteam_fix_hookspath.py"
+```
+
+- Removes any local-scope `core.hooksPath` value that does not end in `hooks/git-hooks`.
+- Sets `git config --global core.hooksPath ~/.claude/hooks/git-hooks` when the global value is unset or non-canonical.
+- Refuses to run (exit non-zero) when `~/.claude/hooks/git-hooks` does not exist on disk — install via `npx claude-dev-env .` first.
+- Idempotent: a second invocation is a clean no-op.
+- Re-runs `bugteam_preflight.py --no-pytest` and propagates its exit code.
+
+The bugteam SKILL invokes this automatically when preflight stderr indicates a `core.hooksPath` failure, so Claude does not surface the error to the user.
+
 ## `bugteam_code_rules_gate.py`
 
 From the repository root (same merge-base rules as the PR head vs base — default `--base origin/main`):