claude-dev-env 7.4.0 → 7.5.0

package/hooks/hooks_constants/pii_prevention_constants.py

@@ -18,9 +18,7 @@ from hooks_constants.pre_tool_use_dispatcher_constants import (  # noqa: F401
 BASH_TOOL_NAME: str = "Bash"
 POWERSHELL_TOOL_NAME: str = "PowerShell"
 
-ALL_SHELL_TOOL_NAMES: frozenset[str] = frozenset(
-    {BASH_TOOL_NAME, POWERSHELL_TOOL_NAME}
-)
+ALL_SHELL_TOOL_NAMES: frozenset[str] = frozenset({BASH_TOOL_NAME, POWERSHELL_TOOL_NAME})
 
 ALL_GIT_BINARY_BASENAMES: frozenset[str] = frozenset({"git", "git.exe"})
 GIT_COMMIT_SUBCOMMAND: str = "commit"
@@ -29,12 +27,8 @@ ALL_VALUE_TAKING_GIT_OPTIONS: frozenset[str] = frozenset(
     {GIT_WORKING_DIRECTORY_OPTION, "-c", "--git-dir", "--work-tree", "--namespace"}
 )
 GIT_OPTION_WITH_VALUE_STEP: int = 2
-ALL_SHELL_COMMAND_SEPARATOR_TOKENS: frozenset[str] = frozenset(
-    {"&&", "||", ";", "|", "&"}
-)
-ALL_SHELL_KEYWORD_TOKENS: frozenset[str] = frozenset(
-    {"then", "do", "else", "elif"}
-)
+ALL_SHELL_COMMAND_SEPARATOR_TOKENS: frozenset[str] = frozenset({"&&", "||", ";", "|", "&"})
+ALL_SHELL_KEYWORD_TOKENS: frozenset[str] = frozenset({"then", "do", "else", "elif"})
 ALL_COMMAND_WRAPPER_TOKENS: frozenset[str] = frozenset(
     {
         "sudo",
@@ -85,9 +79,7 @@ SINGLE_DASH_OPTION_PREFIX: str = "-"
 DOUBLE_DASH_OPTION_PREFIX: str = "--"
 ALL_SHELL_QUOTE_CHARACTERS: frozenset[str] = frozenset({'"', "'"})
 ALL_COMMAND_BOUNDARY_NEWLINE_CHARACTERS: frozenset[str] = frozenset({"\n", "\r"})
-ENVIRONMENT_ASSIGNMENT_PATTERN: re.Pattern[str] = re.compile(
-    r"^[A-Za-z_][A-Za-z0-9_]*="
-)
+ENVIRONMENT_ASSIGNMENT_PATTERN: re.Pattern[str] = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
 LINE_CONTINUATION_PATTERN: re.Pattern[str] = re.compile(r"\\\r?\n")
 POWERSHELL_LINE_CONTINUATION_PATTERN: re.Pattern[str] = re.compile(r"`\r?\n")
 
@@ -223,9 +215,7 @@ CATEGORY_HOME_PATH: str = "home-path"
 CATEGORY_PRIVATE_IP: str = "private-ip"
 CATEGORY_SECRET: str = "secret"
 
-ALL_REDACTED_PREVIEW_CATEGORIES: frozenset[str] = frozenset(
-    {CATEGORY_EMAIL, CATEGORY_SECRET}
-)
+ALL_REDACTED_PREVIEW_CATEGORIES: frozenset[str] = frozenset({CATEGORY_EMAIL, CATEGORY_SECRET})
 REDACTED_PREVIEW_PREFIX_LENGTH: int = 4
 REDACTED_PREVIEW_SUFFIX_LENGTH: int = 4
 REDACTED_PREVIEW_REVEALED_LENGTH: int = (
@@ -238,9 +228,7 @@ MINIMUM_LENGTH_FOR_PARTIAL_REDACTION: int = (
     REDACTED_PREVIEW_REVEALED_LENGTH + REDACTED_PREVIEW_MINIMUM_HIDDEN_LENGTH
 )
 
-EMAIL_PATTERN: re.Pattern[str] = re.compile(
-    r"(?i)\b([A-Z0-9._%+\-]+@[A-Z0-9.\-]+\.[A-Z]{2,})\b"
-)
+EMAIL_PATTERN: re.Pattern[str] = re.compile(r"(?i)\b([A-Z0-9._%+\-]+@[A-Z0-9.\-]+\.[A-Z]{2,})\b")
 
 IPV4_PATTERN: re.Pattern[str] = re.compile(
     r"\b((?:25[0-5]|2[0-4]\d|1?\d?\d)\."
@@ -249,13 +237,9 @@ IPV4_PATTERN: re.Pattern[str] = re.compile(
     r"(?:25[0-5]|2[0-4]\d|1?\d?\d))\b"
 )
 
-GITHUB_TOKEN_PATTERN: re.Pattern[str] = re.compile(
-    r"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b"
-)
+GITHUB_TOKEN_PATTERN: re.Pattern[str] = re.compile(r"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b")
 
-GITHUB_FINE_GRAINED_TOKEN_PATTERN: re.Pattern[str] = re.compile(
-    r"\bgithub_pat_[A-Za-z0-9_]{20,}\b"
-)
+GITHUB_FINE_GRAINED_TOKEN_PATTERN: re.Pattern[str] = re.compile(r"\bgithub_pat_[A-Za-z0-9_]{20,}\b")
 
 AWS_ACCESS_KEY_PATTERN: re.Pattern[str] = re.compile(r"\bAKIA[0-9A-Z]{16}\b")
 
@@ -264,8 +248,9 @@ PEM_PRIVATE_KEY_HEADER_PATTERN: re.Pattern[str] = re.compile(
 )
 
 HOME_PATH_PATTERN: re.Pattern[str] = HARDCODED_USER_PATH_PATTERN
+INTERPOLATED_HOME_USERNAME_PATTERN: re.Pattern[str] = re.compile(r"^\{[A-Za-z_][A-Za-z0-9_]*\}$")
 
-ALL_HOME_DIRECTORY_PATH_MARKERS: tuple[str, ...] = ("/users/", "/home/")
+HOME_USERNAME_MARKER_PATTERN: re.Pattern[str] = re.compile(r"[\\/]+(?:users|home)[\\/]+", re.I)
 
 ALL_SECRET_PATTERNS: tuple[re.Pattern[str], ...] = (
     GITHUB_TOKEN_PATTERN,

package/hooks/hooks_constants/post_tool_use_context.py

@@ -0,0 +1,34 @@
+"""Shared stdout emitter for PostToolUse hooks that add context."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from hooks_constants.bash_post_call_dispatcher_constants import (
+    ADDITIONAL_CONTEXT_KEY,
+    HOOK_EVENT_NAME_KEY,
+    HOOK_SPECIFIC_OUTPUT_KEY,
+    POST_TOOL_USE_HOOK_EVENT_NAME,
+)
+
+
+def write_post_tool_use_context_to_stdout(context_text: str) -> None:
+    """Write one PostToolUse additionalContext payload to stdout.
+
+    A hosted hook writes its note here and the Bash PostToolUse dispatcher
+    reads it back, joins it with the other hooks' notes, and writes the joined
+    text here in turn. Both ends of that hop share this one payload shape
+    rather than each carrying a copy of it.
+
+    Args:
+        context_text: The advisory text the dispatcher forwards.
+    """
+    payload = {
+        HOOK_SPECIFIC_OUTPUT_KEY: {
+            HOOK_EVENT_NAME_KEY: POST_TOOL_USE_HOOK_EVENT_NAME,
+            ADDITIONAL_CONTEXT_KEY: context_text,
+        }
+    }
+    sys.stdout.write(json.dumps(payload))
+    sys.stdout.flush()

package/hooks/hooks_constants/pr_done_reminder_constants.py

@@ -19,7 +19,6 @@ __all__ = [
     "ALL_GH_PR_VIEW_ARGUMENTS",
     "GH_PR_VIEW_TIMEOUT_SECONDS",
     "NO_PULL_REQUEST_MARKER",
-    "EXIT_CODE_ERROR_PREFIX",
     "DONE_LABEL_NAME",
     "MERGEABLE_CLEAN_VALUE",
     "MERGEABLE_CONFLICTING_VALUE",
@@ -59,7 +58,6 @@ ALL_GH_PR_VIEW_ARGUMENTS: tuple[str, ...] = (
 )
 GH_PR_VIEW_TIMEOUT_SECONDS: int = 20
 NO_PULL_REQUEST_MARKER: str = "no pull requests found"
-EXIT_CODE_ERROR_PREFIX: str = "Error: Exit code "
 
 DONE_LABEL_NAME: str = "done"
 

package/hooks/hooks_constants/pre_tool_use_allow_output.py

@@ -0,0 +1,48 @@
+"""Shared stdout emitter for PreToolUse hooks that allow a rewritten tool input."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from hooks_constants.bash_pre_tool_use_dispatcher_constants import (
+    ALLOW_DECISION,
+    HOOK_EVENT_NAME,
+)
+
+__all__ = [
+    "HOOK_SPECIFIC_OUTPUT_KEY",
+    "HOOK_EVENT_NAME_KEY",
+    "PERMISSION_DECISION_KEY",
+    "UPDATED_INPUT_KEY",
+    "write_pre_tool_use_allow_to_stdout",
+]
+
+HOOK_SPECIFIC_OUTPUT_KEY: str = "hookSpecificOutput"
+HOOK_EVENT_NAME_KEY: str = "hookEventName"
+PERMISSION_DECISION_KEY: str = "permissionDecision"
+UPDATED_INPUT_KEY: str = "updatedInput"
+
+
+def write_pre_tool_use_allow_to_stdout(
+    all_updated_tool_input_fields: dict[str, object],
+) -> None:
+    """Write one PreToolUse allow payload carrying a rewritten tool input.
+
+    A rewriter writes its replacement input here and the Bash PreToolUse
+    dispatcher reads it back, carrying the updatedInput through to the harness.
+    Both ends of that hop share this one payload shape rather than each holding
+    a copy of it.
+
+    Args:
+        all_updated_tool_input_fields: The full tool_input the tool call should run with.
+    """
+    payload = {
+        HOOK_SPECIFIC_OUTPUT_KEY: {
+            HOOK_EVENT_NAME_KEY: HOOK_EVENT_NAME,
+            PERMISSION_DECISION_KEY: ALLOW_DECISION,
+            UPDATED_INPUT_KEY: all_updated_tool_input_fields,
+        }
+    }
+    sys.stdout.write(json.dumps(payload))
+    sys.stdout.flush()

package/hooks/hooks_constants/test_bash_post_call_dispatcher_constants.py

@@ -7,22 +7,29 @@ from hooks_constants.bash_post_call_dispatcher_constants import (
 from hooks_constants.bash_pre_tool_use_dispatcher_constants import BASH_TOOL_NAME
 
 
-def test_roster_runs_the_recorder_then_the_pr_done_reminder() -> None:
+def test_roster_runs_the_recorder_then_the_pr_reminder_then_the_msys_advisor() -> None:
     all_script_paths = [
         each_entry.script_relative_path for each_entry in ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES
     ]
     assert all_script_paths == [
         "observability/test_failure_recorder.py",
         "advisory/pr_done_reminder.py",
+        "advisory/msys_path_conversion_advisor.py",
     ]
 
 
 def test_pr_done_reminder_also_serves_the_powershell_tool() -> None:
-    reminder_entry = ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES[-1]
+    reminder_entry = ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES[1]
     assert reminder_entry.script_relative_path == "advisory/pr_done_reminder.py"
     assert "PowerShell" in reminder_entry.applicable_tool_names
 
 
+def test_msys_advisor_serves_the_bash_tool_only() -> None:
+    advisor_entry = ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES[-1]
+    assert advisor_entry.script_relative_path == "advisory/msys_path_conversion_advisor.py"
+    assert advisor_entry.applicable_tool_names == frozenset({"Bash"})
+
+
 def test_context_forwarding_keys_match_the_hook_output_contract() -> None:
     assert constants.POST_TOOL_USE_HOOK_EVENT_NAME == "PostToolUse"
     assert constants.HOOK_SPECIFIC_OUTPUT_KEY == "hookSpecificOutput"

package/hooks/hooks_constants/test_bash_pre_tool_use_dispatcher_constants.py

@@ -7,7 +7,14 @@ ALL_CONSTANT_BINDINGS = run_path(
     str(Path(__file__).with_name("bash_pre_tool_use_dispatcher_constants.py"))
 )
 ALL_BASH_HOSTED_HOOK_ENTRIES = ALL_CONSTANT_BINDINGS["ALL_BASH_HOSTED_HOOK_ENTRIES"]
+ALL_BASH_ONLY_TOOL_NAMES = ALL_CONSTANT_BINDINGS["ALL_BASH_ONLY_TOOL_NAMES"]
+BashHostedHookEntry = ALL_CONSTANT_BINDINGS["BashHostedHookEntry"]
 
 
-def test_roster_has_no_blocking_hooks() -> None:
-    assert ALL_BASH_HOSTED_HOOK_ENTRIES == ()
+def test_roster_hosts_only_the_msys_rewriter_and_no_blocking_hook() -> None:
+    assert ALL_BASH_HOSTED_HOOK_ENTRIES == (
+        BashHostedHookEntry(
+            script_relative_path="blocking/msys_rev_path_rewriter.py",
+            applicable_tool_names=ALL_BASH_ONLY_TOOL_NAMES,
+        ),
+    )

package/hooks/hooks_constants/test_failure_recorder_constants.py

@@ -1,7 +1,7 @@
 """Constants for the failing-test-run PostToolUse recorder hook.
 
 Holds the cheap substring check the hook runs before any shell parsing, the
-harness's own exit-code error prefix, the chaining and redirection operator
+chaining and redirection operator
 tokens that keep the recognizer to one unchained command, the pytest program
 and Python interpreter basenames, and the flag-token marker the path
 extractor uses to skip an option rather than an existing test file argument.
@@ -20,7 +20,6 @@ import re
 BASH_TOOL_NAME = "Bash"
 
 ALL_PYTEST_MENTION_SUBSTRINGS: tuple[str, ...] = ("pytest", "py.test")
-EXIT_CODE_ERROR_PREFIX: str = "Error: Exit code "
 OPTION_TOKEN_PREFIX: str = "-"
 NODE_ID_FILE_PATH_SEPARATOR: str = "::"
 ALL_CHAINING_OPERATOR_SUBSTRINGS: tuple[str, ...] = ("&&", "||", ";", "|", "\n")

package/hooks/hooks_constants/test_post_tool_use_context.py

@@ -0,0 +1,22 @@
+"""Tests for the shared PostToolUse context emitter."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from hooks_constants.post_tool_use_context import write_post_tool_use_context_to_stdout
+
+
+def test_should_write_the_post_tool_use_payload_carrying_the_context_text(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    write_post_tool_use_context_to_stdout("=== PR DONE CHECKLIST ===")
+
+    assert json.loads(capsys.readouterr().out) == {
+        "hookSpecificOutput": {
+            "hookEventName": "PostToolUse",
+            "additionalContext": "=== PR DONE CHECKLIST ===",
+        }
+    }

package/hooks/hooks_constants/test_pre_tool_use_allow_output.py

@@ -0,0 +1,27 @@
+"""Tests for the shared PreToolUse allow-with-rewrite stdout emitter."""
+
+from __future__ import annotations
+
+import json
+from io import StringIO
+from unittest.mock import patch
+
+from hooks_constants.pre_tool_use_allow_output import write_pre_tool_use_allow_to_stdout
+
+
+def _emitted_payload(updated_tool_input: dict[str, object]) -> dict[str, object]:
+    """Return the parsed payload the emitter wrote for one updated tool input."""
+    captured_stdout = StringIO()
+    with patch("sys.stdout", captured_stdout):
+        write_pre_tool_use_allow_to_stdout(updated_tool_input)
+    return json.loads(captured_stdout.getvalue())
+
+
+def test_emitter_writes_an_allow_decision_carrying_the_updated_input() -> None:
+    assert _emitted_payload({"command": "git status", "description": "check"}) == {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
+            "updatedInput": {"command": "git status", "description": "check"},
+        }
+    }

package/hooks/observability/test_failure_recorder.py

@@ -101,6 +101,9 @@ try:
     for each_bootstrap_directory in (_hooks_root_directory, _blocking_directory):
         if each_bootstrap_directory not in sys.path:
             sys.path.insert(0, each_bootstrap_directory)
+    from hooks_constants.bash_post_call_dispatcher_constants import (
+        EXIT_CODE_ERROR_PREFIX,
+    )
     from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
     from hooks_constants.test_failure_recorder_constants import (
         ALL_CHAINING_OPERATOR_SUBSTRINGS,
@@ -108,7 +111,6 @@ try:
         ALL_PYTEST_PROGRAM_BASENAMES,
         ALL_REDIRECTION_TOKENS,
         BASH_TOOL_NAME,
-        EXIT_CODE_ERROR_PREFIX,
         MODULE_RUN_FLAG,
         NODE_ID_FILE_PATH_SEPARATOR,
         OPTION_TOKEN_PREFIX,

package/package.json

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

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

@@ -2,13 +2,13 @@
 
 Route every user-directed question through the `AskUserQuestion` tool — never a plain-text question in a response's final paragraph. Structure: concise `question`, `header` of 12 chars or fewer, 2-4 options (the UI adds the "Other" fallback), `multiSelect` only when choices genuinely combine.
 
-The `question_to_user_enforcer` Stop hook blocks a response whose final paragraph (after stripping code fences, inline code, and blockquotes) ends in a question mark or contains ask-phrases ("would you like", "should I", "let me know if", ...). Rhetorical questions answered in the same paragraph, and questions inside code or blockquotes, pass. `verify-before-asking` gates whether the question belongs to the user at all.
+No hook checks this. Read your own final paragraph before you send it. A paragraph that ends in a question mark, or that carries an ask-phrase such as "would you like", "should I", or "let me know if", belongs in an `AskUserQuestion` call instead. A rhetorical question answered in the same paragraph is fine, and so is a question inside code or a blockquote. `verify-before-asking` settles whether the question belongs to the user at all.
 
 ## The question block stays lean
 
 `AskUserQuestion` renders as one plain unformatted text block. Detail — plans, counts, tradeoffs, background — goes in chat text before the call. The block itself carries a lean question and short choices. When a choice needs formatting, an inline visualizer tool carries it.
 
-The `ask_user_question_shape_blocker` PreToolUse hook denies an `AskUserQuestion` call whose `question` text or whose `description` under any of the `options` carries chat detail:
+No hook denies an over-full block, so keep an `AskUserQuestion` call inside these caps yourself. They apply to the `question` text and to the `description` under any of the `options`:
 
 | What the block carries | Cap |
 |---|---|
@@ -28,4 +28,4 @@ Structure is read at block level on the raw text: a marker counts when it opens
 
 An inline code span — a path, a flag, a command the reader needs verbatim — weighs one word against either word cap on both fields, so a question naming `--dry-run` and a choice naming `C:\dev\gate.py` both pass. A span sits inside a line, so it never opens one with a marker.
 
-A sentence closes on `.`, `!`, or `?` followed by a capitalized word or by the end of the text. A word is any whitespace-separated token carrying a letter or a digit. The denial names each cap the block broke and sends the detail back to chat text.
+A sentence closes on `.`, `!`, or `?` followed by a capitalized word or by the end of the text. A word is any whitespace-separated token carrying a letter or a digit. When a block breaks a cap, move that detail back into chat text before the call.

package/rules/code-standards.md

@@ -2,7 +2,7 @@
 
 > **Canonical review contract:** [`CODE_RULES.md`](../docs/CODE_RULES.md) — the human and AI review contract for code quality, loaded on demand.
 > **Checked-in pointer:** [`.cursor/BUGBOT.md`](../../../.cursor/BUGBOT.md) — the file Cursor BugBot reads; it points at `CODE_RULES.md`.
-> **Production enforcement:** `hooks/blocking/code_rules_enforcer.py` — hand-maintained Write/Edit gates; each mechanical rule carries a synchronization test.
+> **Production enforcement.** The staged policy lint runs `hooks/blocking/code_rules_enforcer.py` over each changed file. No write-time hook runs it. Use `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit, and CI runs the same lint against the merge base. Each mechanical rule carries a synchronization test.
 
 ## Policy surface map
 
@@ -10,7 +10,8 @@
 |---|---|---|
 | Contract | `docs/CODE_RULES.md` | Full review criteria for PR agents, loaded on demand |
 | Pointer | `.cursor/BUGBOT.md` | Checked-in file Cursor BugBot reads; points at `CODE_RULES.md` |
-| Enforcer | `hooks/blocking/code_rules_enforcer.py` | Hand-maintained blockers; not generated from the docs |
+| Enforcer | `hooks/blocking/code_rules_enforcer.py` | Hand-maintained checks the staged policy lint runs; not generated from the docs |
+| Lint | `scripts/cde_lint.py` | Runs the enforcer and the other policy rules over staged or changed files |
 | Session rules | `rules/*.md` | Runtime session policy (questions, tasks, shell) |
 
 Load `CODE_RULES.md` when reviewing a PR, resolving a policy conflict, or generating code. Prefer linking this ref over restating rules.

package/rules/confirm-implementation-forks.md

@@ -6,4 +6,6 @@ How to ask: plain language, one option per path with its tradeoff in the descrip
 
 Not a fork (just proceed): trivially reversible internal-only choices, anything the codebase / stated goal / an existing rule already determines (see `verify-before-asking`), or a single viable path.
 
+Naming a gap in chat is not surfacing a fork. Saying "no production path calls this yet" or "that is a follow-up" describes the fork; it does not ask it. Shipping code that nothing calls is a fork, because the alternative — wire the caller, or hold the change — changes the deliverable. Route it through `AskUserQuestion` before the merge, not into the closing summary after it.
+
 When an option you offered names a repair and the answer leaves it undone, write it down before the turn moves on: a todo entry, a `spawn_task` chip, or a filed issue. An answer of "no preference" settles which path you take now. It leaves the repair you found still waiting.

package/rules/destructive-commands.md

@@ -1,41 +1,41 @@
 # Destructive Commands in Bash
 
-The `destructive_command_blocker` PreToolUse hook watches every Bash-tool command and matches destructive patterns (`rm -rf`, `git reset --hard`, `dd`, `mkfs`, `chmod -R`, fork bombs) as raw text, with no quote-awareness. Anything it cannot prove safe falls through to a confirmation prompt. In a background or auto-mode run no human can answer that prompt, so the call stalls.
+No hook watches Bash commands for destructive patterns. What you face is the harness permission prompt. The harness raises it from the session permission mode and the permission rules in effect on your host. In a background or auto-mode run no human can answer that prompt, so the call stalls.
 
-Two consequences follow: use an allowed removal form, and keep a destructive literal out of the command string even when it rides only as data.
+Two consequences follow. Use an allowed removal form, and keep a destructive literal out of the command string even when it rides only as data.
 
-## Removal forms that never prompt
+## Removal forms to prefer
 
-- **Scratch and probe files** — the PowerShell tool: `Remove-Item -Recurse -Force -Confirm:$false <absolute path>`. The hook watches only the Bash tool, so a PowerShell removal never reaches it.
-- **Worktrees** — `git worktree remove --force <path>`. This matches no destructive pattern.
-- **Tracked files** — `git rm <path>`, which records the deletion in the index.
-- **Bash `rm` when unavoidable** — one standalone `rm`, absolute literal paths, no chaining, no globs, every target inside the ephemeral namespace below.
+- **Scratch and probe files.** Use the PowerShell tool with `Remove-Item -Recurse -Force -Confirm:$false <absolute path>`.
+- **Worktrees.** Use `git worktree remove --force <path>`.
+- **Tracked files.** Use `git rm <path>`, which records the deletion in the index.
+- **Bash `rm` when unavoidable.** Write one standalone `rm` with absolute literal paths, no chaining, and no globs. Keep every target inside the ephemeral namespace below.
 
-## The ephemeral namespace the hook auto-allows
+## The ephemeral namespace
 
-An `rm` is auto-allowed when it is a single invocation and every target resolves inside one of:
+Keep a Bash `rm` to targets that resolve inside one of these:
 
-- The OS temporary root (`tempfile.gettempdir()`).
+- The OS temporary root.
 - A path rooted at `/tmp` or `/temp`, drive-letter tolerant.
 - A path holding a `/worktrees/` or `/worktree/` segment, or a directory git reports inside a worktree admin directory.
 - `~/.claude`.
 
-A bare ephemeral root (`/tmp`, the OS temp root itself, a bare directory named `worktrees` or `worktree`) is refused, so a single stray argument cannot wipe the whole namespace.
+Never pass a bare ephemeral root, such as `/tmp`, the OS temp root itself, or a bare directory named `worktrees` or `worktree`. A single stray argument then wipes the whole namespace.
 
-Four environment variables resolve inside a target token: `TEMP`, `TMP`, `TMPDIR`, and `CLAUDE_JOB_DIR`. Any other variable, a `$(...)` or backtick expansion, or a brace glob makes the target unresolvable and the command prompts. A `$CLAUDE_JOB_DIR` path is auto-allowed only when it resolves into the namespace above — the variable is readable, not a blanket pass. Set `CLAUDE_DESTRUCTIVE_DISABLE_EPHEMERAL_AUTO_ALLOW` to a truthy value to turn the whole auto-allow off.
+Write each target as a literal path. A variable, a `$(...)` or backtick expansion, or a brace glob hides what the command will delete from the reader and from the permission matcher.
 
-A file left in the OS temp directory or under `$CLAUDE_JOB_DIR` is cleaned by the harness and needs no explicit removal — see the exception clause in [`cleanup-temp-files.md`](cleanup-temp-files.md).
+A file left in the OS temp directory or under `$CLAUDE_JOB_DIR` is cleaned by the harness and needs no explicit removal. See the exception clause in [`cleanup-temp-files.md`](cleanup-temp-files.md).
 
 ## Keep destructive literals out of the command string
 
-A destructive literal carried only as data — a commit message, a PR or issue body, an echoed string, a `python -c` / `node -e` / `awk` argument, a heredoc — trips the same raw-text match even though the shell never executes it.
+The permission matcher reads the raw command string. A destructive literal carried only as data still sits in that string, so it can push the command out of an allowed shape and into a prompt even though the shell never executes it. This covers a commit message, a PR or issue body, an echoed string, a `python -c` or `node -e` or `awk` argument, and a heredoc.
 
-- Bodies that describe destructive-command behavior go in a file passed by path: `git commit -F <file>`, `gh … --body-file <file>` (see [`gh-cli-conventions.md`](gh-cli-conventions.md)). Never `git commit -m` or `gh … -b`.
-- To exercise or verify the blocker, or any hook, run the committed test suite (`python -m pytest <test_file>`), which passes the command strings as in-language data. Never an inline `python -c` harness.
+- Bodies that describe destructive-command behavior go in a file passed by path, such as `git commit -F <file>` or `gh … --body-file <file>`. See [`gh-cli-conventions.md`](gh-cli-conventions.md). Never `git commit -m` or `gh … -b`.
+- To exercise or verify a hook, run the committed test suite with `python -m pytest <test_file>`, which passes the command strings as in-language data. Never an inline `python -c` harness.
 
 ## Every subagent prompt carries the rule
 
-A prompt-delivered directive reaches only the agent that gets it. An agent that spawns its own workers — review lenses, fix agents, verifiers — copies this line into every subagent prompt it issues, so a grandchild cleaning up its own probe file uses an allowed form:
+A prompt-delivered directive reaches only the agent that gets it. An agent that spawns its own workers, such as review lenses, fix agents, or verifiers, copies this line into every subagent prompt it issues. A grandchild cleaning up its own probe file then uses an allowed form:
 
 > Never use bash rm in any form. Delete scratch/probe files with the PowerShell tool (Remove-Item -Recurse -Force -Confirm:$false <absolute path>), or leave them in the OS temp dir; remove worktrees only via git worktree remove --force.
 
@@ -43,5 +43,5 @@ Prefer that a child leaves its scratch files for the parent to remove at teardow
 
 ## Sibling rules
 
-- [`cleanup-temp-files.md`](cleanup-temp-files.md) — which scratch files a task removes, and which it leaves.
-- [`windows-filesystem-safe.md`](windows-filesystem-safe.md) — the safe `rmtree` / `force_rmtree` patterns for read-only Windows files.
+- [`cleanup-temp-files.md`](cleanup-temp-files.md) names which scratch files a task removes, and which it leaves.
+- [`windows-filesystem-safe.md`](windows-filesystem-safe.md) holds the safe `rmtree` and `force_rmtree` patterns for read-only Windows files.

package/rules/doc-inventory-integrity.md

@@ -11,13 +11,13 @@ paths:
 
 # Documentation Inventory Integrity
 
-A doc that inventories code is a contract: a reader trusts the listing to map the directory, trusts a shown command to run, and trusts a table row to name the file that reads the variable. Three hooks hold the three inventory shapes in step with the code.
+A doc that inventories code is a contract: a reader trusts the listing to map the directory, trusts a shown command to run, and trusts a table row to name the file that reads the variable. Three repository checks hold the three inventory shapes in step with the code. No write-time hook runs them. Run `python packages/claude-dev-env/scripts/repository_policy.py` before you commit, and CI runs the same command.
 
 ## 1. A per-directory `CLAUDE.md` names files that exist
 
 Every bare filename a per-directory `CLAUDE.md` names points at a file in the subtree that `CLAUDE.md` describes — both the filenames its table cells list and the scripts its fenced run commands invoke (`python script.py`). Add the row and the run command in the change that adds the file; drop both in the change that removes it.
 
-`claude_md_orphan_file_blocker.py` (PreToolUse on Write|Edit|MultiEdit of any `CLAUDE.md`) reads the content the tool would leave on disk. For an Edit or MultiEdit it reconstructs the post-edit file and notes which orphans the file already held, so a pre-existing orphan on an untouched line is excluded and only an orphan the edit introduces is reported; when the existing file cannot be read it scans the raw `new_string` fragments instead.
+`repository_checks/claude_md.py` scans every tracked `CLAUDE.md` in the committed tree and reports each orphan it holds, loading its detection logic from `claude_md_orphan_file_blocker.py`. It reads committed files rather than a pending write, so it reports a pre-existing orphan alongside a new one.
 
 It collects two kinds of reference:
 
@@ -32,7 +32,7 @@ The check stays quiet for a target that is not a `CLAUDE.md`, for a cell holding
 
 A package directory that documents its own files in a `README.md` Layout table, a `CLAUDE.md` "Key files" list, or a skill `SKILL.md` Layout table keeps that inventory in step with the directory. A new production file in such a directory gets its entry — a table row or a list bullet naming the file in backticks and saying what it does — in the same change.
 
-`package_inventory_stale_blocker.py` (PreToolUse on Write) blocks a new production file whose basename appears in no present inventory and names the fix. A skill `SKILL.md` Layout table that maps `scripts/` counts as the inventory for files in that subdirectory.
+`repository_checks/package_inventory.py` scans the committed tree and reports a production file whose basename appears in no present inventory, loading its detection logic from `package_inventory_stale_blocker.py`. It names the fix. A skill `SKILL.md` Layout table that maps `scripts/` counts as the inventory for files in that subdirectory.
 
 Two free-prose slices stay with judgment and belong in the same change:
 
@@ -45,4 +45,4 @@ This is the `category-o-docstring-vs-impl-drift` (O8) orphaned-doc-claim shape a
 
 Every row in an env-var summary table pairs an UPPER_SNAKE variable with a code-file path that reads it — written as `` | `GOOGLE_APPLICATION_CREDENTIALS` | `auth/google_auth.py` | … | ``. When a code change removes the last read of a variable from a file, the same change drops or corrects the row naming that file.
 
-`env_var_table_code_drift_blocker.py` (PreToolUse on Write|Edit|MultiEdit of `.md`) blocks a row whose named code file exists yet never references the variable, and names the fix. For an Edit, drift a file already held on an untouched row is excluded; a row whose code file resolves nowhere stays quiet, since the hook cannot prove the drift.
+`repository_checks/env_var_documentation.py` scans tracked `.md` files and reports a row whose named code file exists yet never references the variable, loading its detection logic from `env_var_table_code_drift_blocker.py`. It names the fix. A row whose code file resolves nowhere stays quiet, since the check cannot prove the drift.

package/rules/docstring-prose-matches-implementation.md

@@ -28,13 +28,13 @@ Read the body and the docstring side by side. Apply each check that matches the
 - **Gate-outcome status flags** — an outcome routed to a blocker (`blocker = ...; break`) reads as blocked everywhere, never as a bypass.
 - **Returns / Raises / Note claims** — each free-form claim matches the body.
 
-Many deterministic shapes of this drift have Write/Edit gates in `~/.claude/hooks/blocking/code_rules_docstrings.py` (and the JS/`.mjs` slices in `code_rules_imports_logging.py`). Free-form rest is judgment.
+Many deterministic shapes of this drift are checked in `code_rules_docstrings.py` (and the JS and `.mjs` slices in `code_rules_imports_logging.py`). The staged policy lint reaches both through `code_rules_enforcer.py`, and no write-time hook runs them. Run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. Free-form rest is judgment.
 
 ## Hook prose matches its detector
 
 A hook module is the sharpest case of the same rule: its docstring lead narrative and its `CORRECTIVE_MESSAGE` describe exactly the shapes the detector flags, and claim no broader trigger surface than the regex enforces.
 
-`hook_prose_detector_consistency` (PreToolUse on Write|Edit|MultiEdit of hook modules and their `*_constants.py` companions) blocks prose that claims a trigger the detector never fires on, and names the fix.
+The staged policy lint carries this as its `hook-prose-consistency` rule, covering hook modules and their `*_constants.py` companions. It reports prose that claims a trigger the detector never fires on, and names the fix. No write-time hook runs it, so run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit.
 
 After writing a hook, ask: would a token matching every word of this message actually trip the detector? When the message names a shape the regex skips, rewrite the message to name only what the regex catches. The path-shape case is the common overstatement — a detector that keys off a path separator must not claim it blocks an "output-key segment". The corrective message spells the rewrite.
 

package/rules/failure-blast-radius.md

@@ -64,9 +64,11 @@ The report then presents each candidate to the owner for a durable-fix decision,
 
 ## Enforcement
 
-`code_rules_blast_radius.py` (PreToolUse on Write and Edit, hosted by `code_rules_enforcer.py`) requires each raised type written directly inside a loop body to end in `RunFatal` or `ItemBlocked`. The lexical check covers raises written directly in loop bodies. Shared helpers carry multiple caller contexts, so their callers classify the boundary.
+`code_rules_blast_radius.py` runs inside `code_rules_enforcer.py`, which the staged policy lint applies to each changed file under its `code-rules` rule. No write-time hook runs it, so run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base.
 
-Findings use baseline content for each edit. A raise present on disk remains accepted during the edit; the gate evaluates newly written raises.
+The check requires each raised type written directly inside a loop body to end in `RunFatal` or `ItemBlocked`. The lexical check covers raises written directly in loop bodies. Shared helpers carry multiple caller contexts, so their callers classify the boundary.
+
+Findings compare each changed file against its baseline. A raise already present in the baseline stays accepted, so the check reports only newly written raises.
 
 ## Excerpt for repository-instruction sessions
 

package/rules/filesystem-search.md

@@ -47,5 +47,5 @@ Issue one shell search at a time when the walk is large. Parallel full-tree sear
 
 ## Search controls
 
-- `unscoped_search_blocker` (PreToolUse on Bash and PowerShell, hosted by `bash_pre_tool_use_dispatcher`) denies a walk from an unscoped root and returns the scoped alternative.
+- No hook denies a walk from an unscoped root. `unscoped_search_blocker` went with the blocking policy hooks in `0f21faf8e`, which left the Bash PreToolUse roster empty. The scope invariant above is guidance a reader follows.
 - For Everything searches that use a project name, run `python "${CLAUDE_SKILL_DIR}/scripts/everything_search.py" <project-name> <search arguments>`. An exact project name becomes its path from `~/.claude/project-paths.json`. The command then starts `es.exe` without a shell. `scripts/setup_project_paths.py` writes the registry.

package/rules/git-workflow.md

@@ -50,6 +50,40 @@ untouched.
    - Before push: `gh pr ready --undo`
    - After review approved: `gh pr ready`
 
+## Run the required checks locally before the first push
+
+Read the branch ruleset for the required check contexts before you push a branch,
+or any level of a stack: `gh api repos/<owner>/<repo>/rules/branches/<trunk>`.
+Then run that exact gate command locally against that level's own base, on every
+level. A required check that never fired is invisible debt at every level, and it
+surfaces only after the whole stack is pushed, when the repair costs a second pass
+over every branch.
+
+A checks listing that reports nothing on the branch is a finding, not a neutral
+state. Find out whether the workflow's event filters exclude the branch, or whether
+the check simply never ran, before you treat that branch as clean.
+
+## Each stack level stands on its own
+
+A symbol belongs at the level that first **uses** it, not the level that first
+mentions it. A bottom pull request that declares the imports its descendants will
+need fails the linter on unused imports. A test helper that calls a function three
+levels above it fails on an undefined name. Both defects stay invisible while you
+read the finished tip, and both are obvious the moment you check one level alone.
+
+Prove each level before you push it: import the modules that level changes, and run
+the required linter against that level's own base. To repair a level, rebuild its
+import header as the union of what that level references, let the linter's
+autofix strip the rest, and move a premature helper up to the level that defines
+what it calls.
+
+## A force-push that moves content obliges a description refresh
+
+Force-with-lease protects the ref. It protects nobody's understanding of what the
+branch now holds. When a rewrite moves content between levels of a stack, or
+otherwise changes what a branch contains, refresh that pull request's description
+through the `pr-description-writer` agent before you ask anyone to read or merge it.
+
 ## Never commit working documents or images
 
 **NEVER commit these files to the repo:**

package/rules/long-horizon-autonomy.md

@@ -18,6 +18,8 @@ Before you end any turn, read your last paragraph. If it is a plan, an analysis,
 
 In an autonomous pipeline the user cannot answer mid-task. For reversible actions that follow from the original request, act without asking; save any follow-up offers for after the task is done.
 
+Authority the task already granted stays granted. A later preference about tone, brevity, or reply format changes how you report, never what you are allowed to do. Re-asking for permission the task already gave hands the work back to the user, who then does it by hand.
+
 ## Delegate and keep working
 
 Hand independent subtasks to subagents and keep working while they run; let them run in the background rather than block until each one returns. Reuse a long-lived subagent across related subtasks so its context carries forward and saves repeated reads. Step in when a subagent drifts off track or is missing context.

package/rules/nas-ssh-invocation.md

@@ -16,9 +16,9 @@ which cannot be answered unattended, or belong to other hosts.
 
 The runner loads the key with paramiko and signs in the same process. The command-line clients check
 the key file's permissions first and refuse it, and Git Bash's `ssh` then falls back to a password
-prompt that hangs an unattended run. `nas_ssh_binary_enforcer.py` (PreToolUse on Bash) denies a bare
-ssh-family word aimed at the NAS, and denies the full `System32/OpenSSH` binary when
-`-o BatchMode=yes` is missing.
+prompt that hangs an unattended run. No hook denies an ssh-family word aimed at the NAS, so keep to
+the runner yourself. When the `System32/OpenSSH` binary is unavoidable, pass `-o BatchMode=yes` so it
+fails fast on a refused key.
 
 Host, ssh port and ssh user are constants inside the runner and are also under the `nas` key in
 `~/.claude/local-identity.json`. Keep all three out of anything committed or posted.