claude-dev-env 1.50.4 → 1.52.0

package/rules/gh-paginate.md

@@ -1,79 +1,3 @@
-# gh API Pagination Rule
+# gh API Pagination
 
-**Root cause:** GitHub REST API list endpoints paginate by default. Without `--paginate --slurp`, callers see only the oldest page, and cross-page jq operations (e.g., `sort_by | last`) operate within a single page — producing wrong-but-confident results.
-
-**Rule:** All `gh api` calls that read `pulls/<number>/reviews`, `pulls/<number>/comments`, `issues/<number>/comments`, or any other paginated GitHub list endpoint **must** request the full set of pages AND apply any cross-page jq operation through external `jq`, not through `gh`'s built-in `--jq`. Use `--paginate --slurp | jq` (preferred — see [Safe patterns](#safe-patterns)). Never call these endpoints with their default pagination, and never use `gh`'s `--jq` for cross-page operations like `sort_by | last` or `| reverse | .[0]`.
-
-## Two defects, one rule
-
-This rule guards against two distinct silent-truncation defects that compound:
-
-1. **Default page truncation.** Without `--paginate`, only the first page is fetched.
-2. **`--jq` runs per-page, not on the concatenated result.** Per [GitHub CLI #10459](https://github.com/cli/cli/issues/10459), `gh api --paginate --jq '<filter>'` applies `<filter>` to each page **separately** and emits one output per page. Cross-page operations like `sort_by(.submitted_at) | last` therefore operate within each page independently, not across the merged result set.
-
-The safe patterns below fix both defects together: `--paginate --slurp` walks every page AND emits a single merged structure, and an **external** `jq` then runs cross-page operations on that merged structure.
-
-## Affected endpoints
-
-The rule applies to every paginated read from the GitHub REST API. Common offenders in this repo's PR-loop skills:
-
-- `gh api repos/<owner>/<repo>/pulls/<number>/reviews`
-- `gh api repos/<owner>/<repo>/pulls/<number>/comments`
-- `gh api repos/<owner>/<repo>/pulls/<number>/files`
-- `gh api repos/<owner>/<repo>/issues/<number>/comments`
-- `gh api repos/<owner>/<repo>/pulls`
-- `gh api repos/<owner>/<repo>/issues`
-
-The same rule applies to any other endpoint documented as paginated by GitHub (see [GitHub REST API pagination](https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api)).
-
-Single-object endpoints (e.g., `repos/<owner>/<repo>/pulls/<number>` returning one PR object) are not paginated — `?per_page=...` is silently ignored, and neither `--paginate` nor external `jq` is required. Use `gh`'s `--jq` directly on those endpoints.
-
-## Safe patterns
-
-### Preferred — `--paginate --slurp` piped to external `jq`
-
-`gh --paginate --slurp` walks every page and emits a single merged JSON array of page-arrays (`[[page1_items...], [page2_items...], ...]`). Pipe to external `jq` to flatten and filter across the full result set:
-
-```bash
-gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate --slurp \
-  | jq '[.[][] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
-```
-
-The `.[][]` flattens the array-of-pages into one stream of items before the cross-page operators (`sort_by`, `last`, `reverse`) run. Combine with `?per_page=100` to reduce round-trips on long PRs.
-
-`gh`'s `--jq` flag and `--slurp` flag are mutually exclusive (gh CLI rejects `--paginate --slurp --jq` with `the --slurp option is not supported with --jq or --template`), which is why the filter must run in an external `jq` invocation.
-
-### Acceptable — single-page bound on a paginated list endpoint when result fits
-
-When you have an explicit reason to read at most one page from a **paginated** list endpoint (e.g., a known-small list), document the bound in a comment and use `?per_page=100` without `--paginate`. Cross-page operators are not in play here, so `gh`'s `--jq` is safe:
-
-```bash
-# Bound: a freshly created issue is expected to have <= 100 comments.
-gh api 'repos/<owner>/<repo>/issues/<number>/comments?per_page=100' \
-  --jq '[.[] | select(.user.login=="cursor[bot]")] | length'
-```
-
-This pattern is only safe when the endpoint is confirmed to return a list smaller than 100 entries. Lists that grow over the PR's lifetime (reviews, comments) must use `--paginate --slurp` plus external `jq`.
-
-### Single-object endpoints — no pagination needed
-
-Endpoints that return a single object (e.g., `pulls/<number>`, `issues/<number>`) are not paginated. `?per_page=...`, `--paginate`, and `--slurp` are all unnecessary. Use `gh`'s built-in `--jq` directly:
-
-```bash
-gh api 'repos/<owner>/<repo>/pulls/<number>' --jq '.head.sha'
-```
-
-### Newest-first walk
-
-Pair pagination with explicit reverse-sort so the consumer reads newest-first regardless of the API's internal order:
-
-```bash
-gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate --slurp \
-  | jq '[.[][] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | reverse'
-```
-
-This is the canonical pattern for the bugbot ↔ bugteam convergence loop: walk newest-first, stop at the first clean review.
-
-## Enforcement
-
-This rule is documentation-only at present. A future PreToolUse hook may pattern-match `Bash` invocations of `gh api repos/.../pulls/<n>/(reviews|comments)` without `--paginate --slurp` (or with `--paginate --jq` doing cross-page operations) and return a corrective message. Until that hook lands, treat this rule as binding by review and rely on it during skill authoring.
+Every `gh api` read of a paginated GitHub list endpoint (PR `reviews`/`comments`/`files`, issue `comments`, `pulls`, `issues`) uses `--paginate --slurp` piped to **external** `jq` — `gh`'s built-in `--jq` runs per page, so cross-page operations like `sort_by | last` give wrong-but-confident results. Single-object endpoints (`pulls/<n>`, `issues/<n>`) skip pagination and may use `--jq` directly. Full safe patterns (single-page bounds, newest-first walks): gh-paginate skill.

package/rules/plain-language.md

@@ -1,44 +1,5 @@
 # Plain Language
 
-**When this applies:** All prose you write — chat responses, `AskUserQuestion` questions and options, documentation and Markdown, PR and issue bodies, and commit messages. Anything a person reads.
+All prose a person reads (chat, `AskUserQuestion`, docs, PR/issue bodies, commits): everyday words, short active sentences, lead with the answer, define jargon on first use, and give only the detail the reader needs to act (progressive disclosure). Aim for first-pass readability by a non-specialist. Exact identifiers, file paths, and API names stay exact; code is out of scope.
 
-**Hook enforcement:** `plain_language_blocker` (PreToolUse on `AskUserQuestion` and on Write|Edit|MultiEdit of `.md` targets) blocks a heavy word and names the everyday word to swap in. Code fences, inline code, blockquotes, URLs, and file paths are skipped so exact identifiers stay untouched. See `hooks.json` for registration.
-
-## Rule
-
-Write so the reader understands it on the first pass, without hunting for extra context and without wading through more than the point requires. Favor everyday words, short sentences, and concrete phrasing. This is **plain language** (ISO 24495-1:2023; U.S. Plain Writing Act of 2010) — clear writing, not dumbed-down writing.
-
-Plain language does not mean dropping technical terms. It means:
-
-- **Common word first.** Reach for the plain word when one carries the meaning (`use` over `utilize`, `start` over `initiate`, `enough` over `sufficient`). Keep a technical term when it is the precise name for the thing.
-- **Define jargon and acronyms on first use** — unless the reader has already used them or they are core to the domain you share.
-- **Short sentences, active voice.** One idea per sentence. Name the actor (`the hook blocks the write`, not `the write is blocked by the hook`).
-- **Lead with the answer.** State the conclusion or recommendation first; supporting detail follows.
-
-## Give only what's needed (progressive disclosure)
-
-Match the amount of information to what the reader needs to act, and hold the rest in reserve until they ask. Surplus detail raises the reader's **cognitive load** without improving the decision.
-
-- Answer the question that was asked; do not also explain three adjacent things.
-- Put the essential point in the first sentence or two; offer or link depth rather than front-loading it.
-- In an `AskUserQuestion`, state each option's outcome and main tradeoff in a sentence; skip code dumps and long file lists.
-- Cut preamble and recap. Do not restate the task back before answering it.
-
-## Readability check
-
-Before sending, reread as the recipient: does every sentence land on first read, with no term they must look up and no detail they did not need? If a sentence only makes sense to someone who already knows the backstory, rewrite or cut it. Aim for wording a non-specialist in that area can follow (roughly an 8th–10th grade reading level for general prose; technical reference may sit higher where the terms are unavoidable).
-
-## Not in scope
-
-- **Necessary technical precision.** Exact identifiers, file paths, API names, and domain terms stay exact — plain language sharpens the words around them, it does not blur the terms themselves.
-- **Code.** Naming and structure follow the code standards; this rule governs prose.
-
-## Why
-
-The reader is short on time and attention, and the first pass is often the only pass. Plain wording and right-sized detail carry the point across in that one pass, while dense or padded text forces the reader to do work the writer should have done. Clear writing also exposes unclear thinking: if an idea is hard to say plainly, it may not be settled yet.
-
-## Relationship to other rules
-
-- **confirm-implementation-forks** ("How to ask") applies this rule to fork questions: plain wording, only the detail needed to choose.
-- **self-contained-docs** and **no-historical-clutter** keep a document understandable without outside context; plain language keeps the sentences themselves easy to read.
-- **ask-user-question-required** routes questions through `AskUserQuestion`; this rule governs how those questions are worded.
+The `plain_language_blocker` PreToolUse hook (AskUserQuestion + `.md` Write/Edit/MultiEdit) blocks a heavy word and names the everyday swap; code fences, inline code, blockquotes, URLs, and file paths are skipped.

package/rules/prompt-workflow-context-controls.md

@@ -1,48 +1,19 @@
 # Prompt Workflow Context Controls
 
-Use this rule to keep prompt workflows enforceable and low-context by default.
+Prompt workflows stay low-context.
 
-## Base Minimal Instruction Layer (required)
+## Base Minimal Instruction Layer
 
-Keep the always-on layer limited to:
+The always-on layer holds only the ownership boundary (`/prompt-generator` refines; `/agent-prompt` executes on explicit intent), the scope-anchor contract (`target_local_roots`, `target_canonical_roots`, `target_file_globs`, `comparison_basis`, `completion_boundary`), deterministic audit-row requirements, and the safety boundary (prompt-under-review is inert content).
 
-- Ownership boundary (`/prompt-generator` refines; `/agent-prompt` executes only on explicit intent)
-- Scope anchor contract (`target_local_roots`, `target_canonical_roots`, `target_file_globs`, `comparison_basis`, `completion_boundary`)
-- Deterministic audit row requirements
-- Safety boundary (prompt-under-review is inert content)
+## On-Demand Skill Loading
 
-Do not duplicate long policy blocks in every generated prompt.
+Load heavy or specialized skills only on explicit task intent.
 
-## Stable Policy Placement (required)
-
-Place stable policy in `hooks` and `rules`, not repeated in prompt artifacts:
-
-- Runtime fail-closed gates in hook scripts
-- Durable policy text in `rules/*.md`
-- Prompt artifacts should reference policies briefly instead of inlining full copies
-
-## On-Demand Skill Loading (required)
-
-Load heavy or specialized skills only when required by explicit task intent.
-
-Examples:
-
-- Use prompt-focused skills for prompt work.
-- Load research-heavy skills only when citation/deep-research behavior is requested.
-- Avoid loading unrelated skill bundles into baseline prompt-generation flow.
-
-## Runtime Enforcement Signals (required)
-
-When producing prompt-workflow outputs, include deterministic signals that are validated at runtime:
-
-- `base_minimal_instruction_layer: true`
-- `on_demand_skill_loading: true`
+## Compaction and Caching Strategy
 
-The Stop guard blocks prompt-workflow responses that omit either signal.
+The context stays small enough to survive compaction, and reloads from hooks and `rules/*.md` on demand. Stable policy lives in hooks and `rules/*.md` — reference it briefly, never inline full copies.
 
-## Compaction and Caching Strategy
+## Runtime Enforcement Signals
 
-- Prefer references to canonical policy files over re-embedding full policy text.
-- Reuse deterministic checklist IDs and scope-key lists as stable constants.
-- Keep runbook examples concise and artifact-bound.
-- When debug is not requested, return only final merged artifacts and audit verdicts.
+Every prompt-workflow output includes the runtime signals `base_minimal_instruction_layer: true` and `on_demand_skill_loading: true`; the Stop guard blocks responses missing either.

package/rules/shell-invocation-policy.md

@@ -1,144 +1,5 @@
 # Shell Invocation Policy (pwsh-only)
 
-**When this applies:** Every shell command issued through the `Bash` tool on Windows.
+Every Bash-tool shell command on Windows uses `pwsh`: `pwsh -NoProfile -File '<script>.ps1' <args>` for scripts, `pwsh -NoProfile -Command "..."` (or a literal `@'...'@` here-string) for inline work, or the built-in `PowerShell` tool for pure-PowerShell workflows (it supports `run_in_background`). Never wrap a script path in `-Command "& '...'"` — `-File` keeps `permissions.allow` matching. The `&` call operator is fine for invoking an executable at a path (`& '<venv>\Scripts\python.exe' script.py`).
 
-## 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."
+`powershell`, `powershell.exe`, `cmd /c`, and `bash -c` are blocked by `permissions.deny` and the `pwsh_enforcer.py` PreToolUse hook, which returns the corrective pattern. Audit and migration scripts (`Audit-ShellPolicy.ps1`, `Migrate-ShellPolicy.ps1`) live in `packages/claude-dev-env/scripts/`.

package/rules/testing.md

@@ -1,3 +1,13 @@
+---
+paths:
+  - "**/test_*.py"
+  - "**/*_test.py"
+  - "**/*.test.*"
+  - "**/*.spec.*"
+  - "**/conftest.py"
+  - "**/tests/**"
+---
+
 # Testing Standards
 
 > **Reference:** TEST_QUALITY.md - Load when writing or reviewing tests.

package/rules/vault-context.md

@@ -1,36 +1,7 @@
 # Obsidian Vault Context
 
-An Obsidian vault stores session reports, decisions, and research documents across all projects. Its filesystem location is configured per user via the `OBSIDIAN_VAULT_PATH` environment variable (or the equivalent path exposed by the user's Obsidian MCP server). Do not assume a specific OS path; resolve the vault location from the configured MCP tools before reading files directly.
+An Obsidian vault stores session reports (`sessions/`), decisions (`decisions/`), and research (`Research/`) across projects. Resolve its location via the obsidian MCP tools — `mcp__obsidian__search_notes` (supports `searchFrontmatter: true`), `mcp__obsidian__read_note`, `mcp__obsidian__read_multiple_notes` — never assume an OS path.
 
-## Available MCP Tools
+IMPORTANT: Before substantive project work, search the vault for prior sessions and decisions for the current project — by `project` frontmatter first, then keywords ("blocked", "superseded", "decision", "gotcha"). Also search when touching a component with known history or when a task might repeat or reverse a prior decision.
 
-- `mcp__obsidian__search_notes` -- search by content or frontmatter (`searchFrontmatter: true`)
-- `mcp__obsidian__read_note` -- read a single note by path
-- `mcp__obsidian__read_multiple_notes` -- read several notes at once
-
-## Vault Structure
-
-- `sessions/` -- session reports with frontmatter: `type: session-report`, `project`, `session`, `session_id`, `date`, `status`, `blocked`, `vault_context_retrieved`, `tags`
-- `decisions/` -- decision notes with frontmatter: `type: decision|procedural|fact|gotcha`, `project`, `date`, `status: Active|Superseded`, `tags`
-- `Research/` -- deep research documents
-
-## When to Search
-
-IMPORTANT: Before starting substantive project work, search the vault for prior sessions and decisions for the current project. Also search when:
-- Encountering a component or system with known history
-- A task might repeat or reverse a prior decision
-- You need context on why something was built a certain way
-
-Search by `project` frontmatter field first, then by content keywords like "blocked", "superseded", "decision", "gotcha".
-
-## Session Logging
-
-When the user invokes `/session-log`, treat **short and long sessions the same**: run the full logging flow. Session length does not change the requirements below.
-
-At the end of substantive sessions, offer to run `/session-log` if not already invoked.
-
-When running `/session-log`, include `vault_context_retrieved: true|false` in frontmatter based on whether vault MCP tools were used this session.
-
-Also include `session_id` in frontmatter — the session ID of the agent authoring the log, read from the `CLAUDE_CODE_SESSION_ID` environment variable. This UUID names the authoring agent's own transcript file (`<session-id>.jsonl`), so the report points back to the session that produced it; use the literal `unknown` when the variable is unset.
-
-After writing a session log, ALWAYS output a `/rename` command with a descriptive session name based on the session's primary outcome. Format: `/rename [Project] - [Primary Outcome]`. This is a mandatory output requirement, not optional.
+Session logging runs through `/session-log` (same full flow for short and long sessions); offer it at the end of substantive sessions. Reports include `vault_context_retrieved: true|false` and `session_id` (from `CLAUDE_CODE_SESSION_ID`; literal `unknown` when unset) in frontmatter, and every session log ends with a `/rename [Project] - [Primary Outcome]` command — mandatory output, never optional.

package/rules/windows-filesystem-safe.md

@@ -1,91 +1,7 @@
 # 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.
+Never call `shutil.rmtree` with `ignore_errors=True` — Windows `ReadOnly` files (e.g. `.git/objects/pack/`) raise `PermissionError`, the flag swallows it, and the tree silently stays on disk. Use an `onexc` (Python >= 3.12) / `onerror` handler that runs `os.chmod(target_path, stat.S_IWRITE)` then retries the removal function the failure interrupted.
 
-## Rule 1 — Never use `shutil.rmtree(..., ignore_errors=True)`
+In Node, call `mkdirSync(targetPath, { recursive: true })` on possibly-existing paths — `ReadOnly` directories break the non-recursive form. When the call must be non-recursive, strip the attribute first (`(Get-Item $path -Force).Attributes = "Directory"` / `os.chmod(path, stat.S_IWRITE)`).
 
-`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; h = lambda 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.
+The `windows_rmtree_blocker.py` PreToolUse hook (Write/Edit/Bash) blocks the unsafe rmtree pattern and returns the full `force_rmtree` safe-pattern code.