claude-dev-env 1.32.0 → 1.34.0

package/hooks/blocking/code_rules_enforcer.py

@@ -60,6 +60,13 @@ NOT_INSIDE_TYPE_CHECKING_BLOCK = -1
 MAX_ISSUES_PER_CHECK = 3
 FILE_GLOBAL_UPPER_SNAKE_PATTERN = re.compile(r"^_?[A-Z][A-Z0-9_]*$")
 
+COLLECTION_TYPE_NAMES: frozenset[str] = frozenset({
+    "list", "tuple", "set", "frozenset", "dict",
+    "Iterable", "Sequence", "Mapping", "MutableMapping", "FrozenSet",
+})
+COLLECTION_BY_NAME_PATTERN: re.Pattern[str] = re.compile(r"^[a-z][a-z0-9]*_by_[a-z][a-z0-9_]*$")
+CLI_FILE_PATH_MARKERS: tuple[str, ...] = ("/scripts/", "\\scripts\\", "_cli.py", "/cli.py", "\\cli.py")
+
 
 def get_file_extension(file_path: str) -> str:
     """Extract lowercase file extension."""
@@ -1933,6 +1940,106 @@ def check_unused_optional_parameters(content: str, file_path: str) -> list[str]:
     return issues
 
 
+def _annotation_names_collection(annotation_node: ast.expr | None) -> bool:
+    if annotation_node is None:
+        return False
+    if isinstance(annotation_node, ast.Name):
+        return annotation_node.id in COLLECTION_TYPE_NAMES
+    if isinstance(annotation_node, ast.Subscript):
+        return _annotation_names_collection(annotation_node.value)
+    if isinstance(annotation_node, ast.Attribute):
+        return annotation_node.attr in COLLECTION_TYPE_NAMES
+    return False
+
+
+def check_collection_prefix(content: str, file_path: str) -> list[str]:
+    if is_test_file(file_path):
+        return []
+    if is_workflow_registry_file(file_path) or is_migration_file(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for node in tree.body:
+        target_name: str | None = None
+        target_line = 0
+        is_collection_value = False
+        if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            target_name = node.target.id
+            target_line = node.lineno
+            is_collection_value = _annotation_names_collection(node.annotation)
+        elif isinstance(node, ast.Assign) and len(node.targets) == 1 and isinstance(node.targets[0], ast.Name):
+            target_name = node.targets[0].id
+            target_line = node.lineno
+            is_collection_value = isinstance(node.value, (ast.Tuple, ast.List, ast.Set, ast.Dict))
+        if target_name is None or not is_collection_value:
+            continue
+        if not UPPER_SNAKE_CONSTANT_PATTERN.match(target_name):
+            continue
+        if target_name.startswith("ALL_") or COLLECTION_BY_NAME_PATTERN.match(target_name.lower()):
+            continue
+        issues.append(
+            f"Line {target_line}: Collection constant {target_name} - prefix with ALL_ (CODE_RULES §5)"
+        )
+        if len(issues) >= MAX_ISSUES_PER_CHECK:
+            break
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for each_arg in _collect_annotated_arguments(node):
+            if not _annotation_names_collection(each_arg.annotation):
+                continue
+            if each_arg.arg in {"self", "cls"}:
+                continue
+            if each_arg.arg.startswith("all_") or COLLECTION_BY_NAME_PATTERN.match(each_arg.arg):
+                continue
+            issues.append(
+                f"Line {each_arg.lineno}: Collection parameter {each_arg.arg} - prefix with all_ (CODE_RULES §5)"
+            )
+            if len(issues) >= MAX_ISSUES_PER_CHECK:
+                return issues
+    return issues
+
+
+def _is_cli_entry_point(file_path: str) -> bool:
+    path_lower = file_path.lower().replace("\\", "/")
+    return any(marker.replace("\\", "/") in path_lower for marker in CLI_FILE_PATH_MARKERS)
+
+
+def check_library_print(content: str, file_path: str) -> list[str]:
+    if is_test_file(file_path) or is_config_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+    if _is_cli_entry_point(file_path):
+        return []
+    if get_file_extension(file_path) not in PYTHON_EXTENSIONS:
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        function_reference = node.func
+        if isinstance(function_reference, ast.Name) and function_reference.id == "print":
+            issues.append(
+                f"Line {node.lineno}: Library print() - route through logger or accept an explicit stream parameter"
+            )
+        elif isinstance(function_reference, ast.Attribute) and function_reference.attr == "write":
+            value_node = function_reference.value
+            if isinstance(value_node, ast.Attribute) and isinstance(value_node.value, ast.Name):
+                if value_node.value.id == "sys" and value_node.attr in {"stdout", "stderr"}:
+                    issues.append(
+                        f"Line {node.lineno}: sys.{value_node.attr}.write - route through logger"
+                    )
+        if len(issues) >= MAX_ISSUES_PER_CHECK:
+            break
+    return issues
+
+
 def validate_content(content: str, file_path: str, old_content: str = "") -> list[str]:
     """Run all applicable validators on content.
 
@@ -1964,6 +2071,8 @@ def validate_content(content: str, file_path: str, old_content: str = "") -> lis
         all_issues.extend(check_existence_check_tests(content, file_path))
         all_issues.extend(check_constant_equality_tests(content, file_path))
         all_issues.extend(check_unused_optional_parameters(content, file_path))
+        all_issues.extend(check_collection_prefix(content, file_path))
+        all_issues.extend(check_library_print(content, file_path))
         check_incomplete_mocks(content, file_path)
         check_duplicated_format_patterns(content, file_path)
 

package/hooks/blocking/test_windows_rmtree_blocker.py

@@ -76,6 +76,12 @@ def test_allows_ignore_errors_false() -> None:
     )
 
 
+def test_blocks_rmtree_with_nested_parens_in_args() -> None:
+    assert payload_contains_unsafe_rmtree(
+        "shutil.rmtree(Path(target).resolve(), ignore_errors=True)"
+    )
+
+
 def test_extract_payload_handles_write_content() -> None:
     extracted = extract_payload_text("Write", {"content": "abc"})
     assert extracted == "abc"
@@ -98,6 +104,7 @@ def test_extract_payload_returns_empty_for_unknown_tool() -> None:
 
 def _run_hook(hook_input: dict) -> tuple[str, int]:
     captured = io.StringIO()
+    exit_code = 0
     sys.stdin = io.StringIO(json.dumps(hook_input))
     try:
         with redirect_stdout(captured):

package/hooks/blocking/windows_rmtree_blocker.py

@@ -16,70 +16,66 @@ import json
 import re
 import sys
 
-_WRITE_EDIT_TOOL_NAMES = {"Write", "Edit"}
-_BASH_TOOL_NAME = "Bash"
-
-_RMTREE_IGNORE_ERRORS_PATTERN = re.compile(
-    r"shutil\s*\.\s*rmtree\s*\([^)]*\bignore_errors\s*=\s*True\b",
-    re.DOTALL,
-)
-
-_CORRECTIVE_MESSAGE = (
-    "BLOCKED [windows-rmtree]: shutil.rmtree(..., ignore_errors=True) silently "
-    "fails on Windows when a file carries the ReadOnly attribute "
-    "(FILE_ATTRIBUTE_READONLY). The PermissionError is swallowed and the tree "
-    "stays on disk -- cleanup looks successful but removes nothing. Linux is "
-    "unaffected because unlink only needs write on the parent directory.\n\n"
-    "Use a Windows-safe handler that strips the attribute and retries the "
-    "syscall:\n\n"
-    "    import os\n"
-    "    import shutil\n"
-    "    import stat\n"
-    "    import sys\n\n"
-    "    def _strip_read_only_and_retry(removal_function, target_path, *_exc_info):\n"
-    "        try:\n"
-    "            os.chmod(target_path, stat.S_IWRITE)\n"
-    "            removal_function(target_path)\n"
-    "        except OSError:\n"
-    "            pass\n\n"
-    "    def force_rmtree(target_path: str) -> None:\n"
-    "        handler_kw = (\n"
-    '            {"onexc": _strip_read_only_and_retry}\n'
-    "            if sys.version_info >= (3, 12)\n"
-    '            else {"onerror": _strip_read_only_and_retry}\n'
-    "        )\n"
-    "        try:\n"
-    "            shutil.rmtree(target_path, **handler_kw)\n"
-    "        except OSError:\n"
-    "            pass\n\n"
-    "Two things to know about the handler:\n"
-    "  - *_exc_info collapses the signature difference. onerror passes "
-    "(type, value, traceback); onexc (Python 3.12+) passes a single exception.\n"
-    "  - removal_function is whichever syscall rmtree was attempting "
-    "(os.unlink for files, os.rmdir for dirs). Re-call it after chmod to finish "
-    "the work that originally failed.\n\n"
-    "See ~/.claude/rules/windows-filesystem-safe.md for full guidance."
-)
-
 
 def payload_contains_unsafe_rmtree(payload_text: str) -> bool:
     if not payload_text:
         return False
-    return bool(_RMTREE_IGNORE_ERRORS_PATTERN.search(payload_text))
+    rmtree_ignore_errors_pattern = re.compile(
+        r"shutil\s*\.\s*rmtree\s*\(.*?\bignore_errors\s*=\s*True\b",
+        re.DOTALL,
+    )
+    return bool(rmtree_ignore_errors_pattern.search(payload_text))
 
 
 def extract_payload_text(tool_name: str, tool_input: dict) -> str:
-    if tool_name in _WRITE_EDIT_TOOL_NAMES:
+    if tool_name in {"Write", "Edit"}:
         return tool_input.get("content", "") or tool_input.get("new_string", "") or ""
-    if tool_name == _BASH_TOOL_NAME:
+    if tool_name == "Bash":
         return tool_input.get("command", "") or ""
     return ""
 
 
 def main() -> None:
+    corrective_message = (
+        "BLOCKED [windows-rmtree]: shutil.rmtree(..., ignore_errors=True) silently "
+        "fails on Windows when a file carries the ReadOnly attribute "
+        "(FILE_ATTRIBUTE_READONLY). The PermissionError is swallowed and the tree "
+        "stays on disk -- cleanup looks successful but removes nothing. Linux is "
+        "unaffected because unlink only needs write on the parent directory.\n\n"
+        "Use a Windows-safe handler that strips the attribute and retries the "
+        "syscall:\n\n"
+        "    import os\n"
+        "    import shutil\n"
+        "    import stat\n"
+        "    import sys\n\n"
+        "    def _strip_read_only_and_retry(removal_function, target_path, *_exc_info):\n"
+        "        try:\n"
+        "            os.chmod(target_path, stat.S_IWRITE)\n"
+        "            removal_function(target_path)\n"
+        "        except OSError:\n"
+        "            pass\n\n"
+        "    def force_rmtree(target_path: str) -> None:\n"
+        "        handler_kw = (\n"
+        '            {"onexc": _strip_read_only_and_retry}\n'
+        "            if sys.version_info >= (3, 12)\n"
+        '            else {"onerror": _strip_read_only_and_retry}\n'
+        "        )\n"
+        "        try:\n"
+        "            shutil.rmtree(target_path, **handler_kw)\n"
+        "        except OSError:\n"
+        "            pass\n\n"
+        "Two things to know about the handler:\n"
+        "  - *_exc_info collapses the signature difference. onerror passes "
+        "(type, value, traceback); onexc (Python 3.12+) passes a single exception.\n"
+        "  - removal_function is whichever syscall rmtree was attempting "
+        "(os.unlink for files, os.rmdir for dirs). Re-call it after chmod to finish "
+        "the work that originally failed.\n\n"
+        "See ~/.claude/rules/windows-filesystem-safe.md for full guidance."
+    )
     try:
         hook_input = json.load(sys.stdin)
     except json.JSONDecodeError:
+        sys.stderr.write("windows_rmtree_blocker: malformed JSON on stdin\n")
         sys.exit(0)
 
     tool_name = hook_input.get("tool_name", "")
@@ -94,7 +90,7 @@ def main() -> None:
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",
             "permissionDecision": "deny",
-            "permissionDecisionReason": _CORRECTIVE_MESSAGE,
+            "permissionDecisionReason": corrective_message,
         }
     }
     print(json.dumps(deny_response))

package/hooks/config/session_env_cleanup_constants.py

@@ -11,7 +11,9 @@ SECONDS_PER_DAY = 24 * 60 * 60
 STALE_AGE_DAYS = 7
 STALE_AGE_SECONDS = STALE_AGE_DAYS * SECONDS_PER_DAY
 
-RMTREE_ONEXC_PYTHON_VERSION = (3, 12)
+ALL_RMTREE_ONEXC_PYTHON_VERSION_PARTS: tuple[int, int] = (3, 12)
+
+SESSION_ID_PAYLOAD_KEY: str = "session_id"
 
 SESSION_ID_PATTERN = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
 

package/hooks/config/test_session_env_cleanup_constants.py

@@ -11,7 +11,7 @@ for each_sys_path_entry in (str(_CONFIG_DIRECTORY), str(_HOOKS_ROOT)):
     if each_sys_path_entry not in sys.path:
         sys.path.insert(0, each_sys_path_entry)
 
-from config.session_env_cleanup_constants import SESSION_ID_PATTERN
+from config.session_env_cleanup_constants import SESSION_ID_PATTERN, SESSION_ID_PAYLOAD_KEY
 
 
 class TestSessionIdPatternAccepts:
@@ -31,6 +31,11 @@ class TestSessionIdPatternAccepts:
         assert matched.group(0) == underscore_input
 
 
+class TestSessionIdPayloadKey:
+    def test_session_id_payload_key_matches_hook_protocol_field(self) -> None:
+        assert SESSION_ID_PAYLOAD_KEY == "session_id"
+
+
 class TestSessionIdPatternRejects:
     def test_rejects_forward_slash(self) -> None:
         assert SESSION_ID_PATTERN.match("etc/passwd") is None

package/hooks/hooks.json

@@ -224,6 +224,18 @@
           }
         ]
       }
+    ],
+    "InstructionsLoaded": [
+      {
+        "matcher": "session_start|nested_traversal|path_glob_match|include|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/observability/instructions_loaded_logger.py",
+            "timeout": 10
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/observability/instructions_loaded_logger.py

@@ -0,0 +1,38 @@
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def main() -> int:
+    log_path = Path.home() / ".claude" / "logs" / "instructions_loaded.jsonl"
+    payload_fields = (
+        "file_path",
+        "load_reason",
+        "memory_type",
+        "trigger_file_path",
+        "parent_file_path",
+        "globs",
+        "session_id",
+    )
+    try:
+        payload = json.load(sys.stdin)
+        record = {"timestamp": datetime.now(timezone.utc).isoformat()}
+        for each_field_name in payload_fields:
+            record[each_field_name] = payload.get(each_field_name)
+    except Exception as exception:
+        record = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "error": str(exception),
+        }
+    try:
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        with log_path.open("a", encoding="utf-8") as log_file:
+            log_file.write(json.dumps(record) + "\n")
+    except OSError:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/observability/test_instructions_loaded_logger.py

@@ -0,0 +1,85 @@
+"""Tests for instructions_loaded_logger observability hook."""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+SCRIPT_PATH = Path(__file__).parent / "instructions_loaded_logger.py"
+
+
+def _run_hook(payload: dict, fake_home: Path) -> subprocess.CompletedProcess[str]:
+    child_environment = os.environ.copy()
+    child_environment["HOME"] = str(fake_home)
+    child_environment["USERPROFILE"] = str(fake_home)
+    return subprocess.run(
+        [sys.executable, str(SCRIPT_PATH)],
+        input=json.dumps(payload),
+        text=True,
+        capture_output=True,
+        check=False,
+        env=child_environment,
+    )
+
+
+def test_should_write_record_with_known_payload_fields_to_jsonl_log() -> None:
+    with tempfile.TemporaryDirectory() as fake_home_string:
+        fake_home = Path(fake_home_string)
+        payload = {
+            "file_path": "/tmp/CLAUDE.md",
+            "load_reason": "session_start",
+            "memory_type": "User",
+            "trigger_file_path": "/tmp/trigger",
+            "parent_file_path": "/tmp/parent",
+            "globs": ["**/*.py"],
+            "session_id": "abc-123",
+        }
+        completed = _run_hook(payload, fake_home)
+        assert completed.returncode == 0, completed.stderr
+        log_path = fake_home / ".claude" / "logs" / "instructions_loaded.jsonl"
+        assert log_path.exists()
+        record = json.loads(log_path.read_text(encoding="utf-8").strip())
+        assert record["file_path"] == "/tmp/CLAUDE.md"
+        assert record["load_reason"] == "session_start"
+        assert record["session_id"] == "abc-123"
+        assert "timestamp" in record
+
+
+def test_should_exit_zero_and_record_error_when_stdin_payload_is_invalid_json() -> None:
+    with tempfile.TemporaryDirectory() as fake_home_string:
+        fake_home = Path(fake_home_string)
+        completed = subprocess.run(
+            [sys.executable, str(SCRIPT_PATH)],
+            input="not json",
+            text=True,
+            capture_output=True,
+            check=False,
+            env={**os.environ, "HOME": str(fake_home), "USERPROFILE": str(fake_home)},
+        )
+        assert completed.returncode == 0, completed.stderr
+        log_path = fake_home / ".claude" / "logs" / "instructions_loaded.jsonl"
+        assert log_path.exists()
+        record = json.loads(log_path.read_text(encoding="utf-8").strip())
+        assert "error" in record
+        assert "timestamp" in record
+
+
+def test_should_exit_zero_when_log_directory_creation_fails() -> None:
+    with tempfile.TemporaryDirectory() as fake_home_string:
+        fake_home = Path(fake_home_string)
+        blocking_file = fake_home / ".claude"
+        blocking_file.write_text("not a directory", encoding="utf-8")
+        payload = {
+            "file_path": "/tmp/CLAUDE.md",
+            "load_reason": "path_glob_match",
+            "memory_type": "User",
+            "trigger_file_path": None,
+            "parent_file_path": None,
+            "globs": None,
+            "session_id": "abc-123",
+        }
+        completed = _run_hook(payload, fake_home)
+        assert completed.returncode == 0, completed.stderr

package/hooks/session/session_env_cleanup.py

@@ -36,9 +36,10 @@ def _insert_hooks_tree_for_imports() -> None:
 _insert_hooks_tree_for_imports()
 
 from config.session_env_cleanup_constants import (
-    RMTREE_ONEXC_PYTHON_VERSION,
+    ALL_RMTREE_ONEXC_PYTHON_VERSION_PARTS,
     SESSION_ENV_DIRECTORY,
     SESSION_ID_PATTERN,
+    SESSION_ID_PAYLOAD_KEY,
     STALE_AGE_SECONDS,
     WINDOWS_PLATFORM_TAG,
 )
@@ -57,7 +58,7 @@ def _strip_read_only_and_retry(
 
 
 def _force_rmtree(target_path: str) -> None:
-    rmtree_onexc_python_version = RMTREE_ONEXC_PYTHON_VERSION
+    rmtree_onexc_python_version = ALL_RMTREE_ONEXC_PYTHON_VERSION_PARTS
     try:
         if sys.version_info >= rmtree_onexc_python_version:
             shutil.rmtree(target_path, onexc=_strip_read_only_and_retry)
@@ -103,10 +104,10 @@ def _read_session_id_from_stdin() -> str:
         return ""
     if not isinstance(payload, dict):
         return ""
-    raw_session_id = payload.get("session_id")
+    raw_session_id = payload.get(SESSION_ID_PAYLOAD_KEY)
     if not isinstance(raw_session_id, str):
         return ""
-    if not session_id_pattern.match(raw_session_id):
+    if not session_id_pattern.fullmatch(raw_session_id):
         return ""
     return raw_session_id
 

package/hooks/session/test_session_env_cleanup.py

@@ -179,6 +179,7 @@ class TestMainReadsSessionIdFromStdin:
         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"] == "session-from-stdin"
@@ -197,6 +198,7 @@ class TestMainReadsSessionIdFromStdin:
         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"] == ""

package/package.json

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

package/rules/code-standards.md

@@ -3,8 +3,6 @@
 > **MANDATORY REFERENCE:** CODE_RULES.md - Load for ALL code generation.
 > This is the single source of truth for code standards. Non-negotiable.
 
-@~/.claude/docs/CODE_RULES.md
-
 **Key principles (see CODE_RULES.md for complete reference):**
 - Self-documenting code (no comments)
 - Centralized configuration (one source of truth)

package/rules/file-global-constants.md

@@ -1,3 +1,7 @@
+---
+paths: **/*.py
+---
+
 # File-Global Constants
 
 This rule extends the `constants-location` rule defined in `~/.claude/docs/CODE_RULES.md` — see the ⚡ HOOK-ENFORCED RULES table, Constants location row.

package/rules/shell-invocation-policy.md

@@ -0,0 +1,144 @@
+# Shell Invocation Policy (pwsh-only)
+
+**When this applies:** Every shell command issued through the `Bash` tool on Windows.
+
+## What to use
+
+### Pattern A — Run a `.ps1` script with named arguments
+
+```
+pwsh -NoProfile -File 'Y:\absolute\path\to\Build-Skyline.ps1' -RunTests -Tag staging
+```
+
+Use this when a `.ps1` script accepts named parameters. The `-File` form exposes the script path as a flat token, so `permissions.allow` rules of the form `Bash(pwsh -NoProfile -File *)` match the invocation directly.
+
+### Pattern B — Run an inline expression
+
+```
+pwsh -NoProfile -Command "Get-Date -Format o"
+```
+
+Use this for one or two lines of work that does not need a script file. Quote the entire `-Command` argument with double quotes; use single quotes inside for embedded strings.
+
+### Pattern C — Multi-line inline script with a here-string
+
+```
+pwsh -NoProfile -Command @'
+$projects = Get-ChildItem -Path 'Y:\Projects\LLM Plugins' -Directory
+$projects | Where-Object Name -Like 'claude*' | Select-Object FullName
+'@
+```
+
+Use this for multi-line logic without a separate `.ps1` file. The `@'...'@` form is literal — variables and backticks inside are not expanded.
+
+### Pattern D — The built-in `PowerShell` tool
+
+Use the `PowerShell` tool directly when the entire workflow is PowerShell and does not pipe through external `Bash`-tool-native commands. The built-in tool already runs PowerShell 7+ from `C:\Program Files\PowerShell\7\pwsh.exe`. It supports `run_in_background` for long-running tasks, which `Bash` invocations of `pwsh` do not.
+
+## Migration mapping (replace left with right)
+
+| Existing pattern | Replacement |
+|---|---|
+| `powershell -Command "X"` | `pwsh -NoProfile -Command "X"` |
+| `powershell.exe -Command "X"` | `pwsh -NoProfile -Command "X"` |
+| `powershell -File path.ps1` | `pwsh -NoProfile -File 'path.ps1'` |
+| `powershell.exe -File path.ps1` | `pwsh -NoProfile -File 'path.ps1'` |
+| `powershell -Command "& 'path.ps1' -A v"` | `pwsh -NoProfile -File 'path.ps1' -A v` |
+| `bash -c "X"` | `pwsh -NoProfile -Command "X"` |
+| `cmd /c X` | `pwsh -NoProfile -Command "X"` |
+| `cmd.exe /c X` | `pwsh -NoProfile -Command "X"` |
+| `Bash(powershell:*)` (settings.json) | `Bash(pwsh:*)` |
+| `Bash(powershell.exe:*)` (settings.json) | `Bash(pwsh:*)` |
+
+## Common operations in pwsh
+
+| Task | pwsh syntax |
+|---|---|
+| List directory names | `Get-ChildItem -Path 'X' -Directory -Name` |
+| Read a whole file | `Get-Content -Path 'X' -Raw` |
+| Write file (UTF-8 no BOM) | `[IO.File]::WriteAllText('X', $content, [Text.UTF8Encoding]::new($false))` |
+| Test a path | `Test-Path 'X'` |
+| Remove a directory | `Remove-Item -Path 'X' -Recurse -Force` |
+| Activate a venv | `& 'Y:\path\.venv\Scripts\Activate.ps1'` |
+| Run venv-Python | `& 'Y:\path\.venv\Scripts\python.exe' script.py` |
+| Set env var (current process) | `$env:NAME = 'value'` |
+| Pipe to ripgrep | `Get-ChildItem | Select-String -Pattern 'X'` |
+| First match in a stream | `Select-Object -First 1` |
+
+The `&` call operator is appropriate for invoking an executable at a path — for example, `& '<venv>\Scripts\python.exe' script.py`. The forbidden form is wrapping a script path inside `pwsh -Command "& 'X' -A v"`, where the call operator is inside a `-Command` payload and breaks `permissions.allow` matching. Use `pwsh -File 'X' -A v` instead for that case.
+
+## External binaries usable from pwsh
+
+Invoke these directly without wrapping:
+
+- `git` — `git status`, `git log --oneline -10`, `git -C 'path' status`
+- `gh` — `gh pr create`, `gh issue list`
+- `python`, `pip` (via venv path: `& '.venv\Scripts\python.exe'`)
+- `node`, `npm`, `npx`
+- `rg` (ripgrep), `fd`, `es.exe` (Everything search)
+- `pytest`, `mypy`, `pyright` (via venv)
+
+## Verification
+
+To confirm pwsh is correctly installed and routed:
+
+```
+pwsh -NoProfile -Command "$PSVersionTable.PSVersion.ToString()"
+```
+
+Expected output: `7.x.x.x` or higher. The verified install at the time of writing this rule is `7.5.5.0` at `C:\Program Files\PowerShell\7\pwsh.exe`.
+
+## Permission allowlist (settings.json `permissions.allow`)
+
+These entries pre-approve canonical pwsh invocations:
+
+```
+Bash(pwsh -NoProfile -File *)
+Bash(pwsh -File *)
+Bash(pwsh -NoProfile -Command *)
+Bash(pwsh -Command *)
+Bash(pwsh:*)
+PowerShell
+```
+
+The `PowerShell` entry auto-approves the built-in tool.
+
+## Permission denylist (settings.json `permissions.deny`)
+
+These entries block legacy shells:
+
+```
+Bash(powershell *)
+Bash(powershell.exe *)
+Bash(powershell:*)
+Bash(powershell.exe:*)
+Bash(bash -c *)
+Bash(bash --login *)
+Bash(bash --rcfile *)
+Bash(bash --init-file *)
+Bash(cmd /c *)
+Bash(cmd.exe /c *)
+```
+
+## Migration scripts
+
+Two scripts ship with this rule, located at `packages/claude-dev-env/scripts/`:
+
+- `Audit-ShellPolicy.ps1` — scans `settings*.json` files under the configured project roots and prints one summary line: `POLICY: OK` or `POLICY: VIOLATIONS=<count> IN=<n> FILES`. Exit code 0 when clean, 1 when violations remain. Use this as a check before merging.
+- `Migrate-ShellPolicy.ps1` — applies the migration mapping to `settings*.json` files in place. Defaults to dry-run; pass `-Apply` to write changes. Prints one summary line: `MIGRATED: <count> rules IN=<n> FILES` or `DRY RUN: would migrate <count> rules IN=<n> FILES`.
+
+Run order: audit → migrate (dry run) → migrate (apply) → audit.
+
+## Enforcement layers
+
+1. **`permissions.allow`** pre-approves the canonical patterns so Claude never gets a prompt for them.
+2. **`permissions.deny`** blocks the legacy patterns at the permission layer.
+3. **`pwsh_enforcer.py`** PreToolUse hook catches edge cases that wildcard syntax misses (compound commands, process wrappers, alternate spellings). Source: `packages/claude-dev-env/hooks/blocking/pwsh_enforcer.py`.
+4. **Migration scripts** keep existing `settings.local.json` files in compliance.
+
+## Precedent
+
+This rule mirrors the convention from [ProteoWizard/pwiz-ai](https://github.com/ProteoWizard/pwiz-ai) `CLAUDE.md`:
+
+> "Always use `pwsh` (PowerShell 7), never `powershell` (5.1). The Bash tool uses Git Bash, which has limited Windows tool access. Route commands through PowerShell when needed."
+> "Never use the `&` call operator — it breaks permissions matching. Use `-File` instead, which supports arguments directly."