claude-dev-env 1.74.0 → 1.76.0

package/hooks/hooks_constants/pre_tool_use_dispatcher_constants.py

@@ -15,6 +15,7 @@ __all__ = [
     "HOOK_EVENT_NAME",
     "BLOCKING_CRASH_EXIT_CODE",
     "EXIT_CODE_TWO_DENY_REASON",
+    "BLOCKING_CRASH_DENY_REASON",
     "WRITE_TOOL_NAME",
     "EDIT_TOOL_NAME",
     "MULTI_EDIT_TOOL_NAME",
@@ -31,6 +32,7 @@ ALLOW_DECISION = "allow"
 HOOK_EVENT_NAME = "PreToolUse"
 BLOCKING_CRASH_EXIT_CODE = 2
 EXIT_CODE_TWO_DENY_REASON = "[dispatcher] hook denied via exit code 2 — write blocked"
+BLOCKING_CRASH_DENY_REASON = "[dispatcher] hook crash in blocking hook — write blocked for safety"
 
 WRITE_TOOL_NAME = "Write"
 EDIT_TOOL_NAME = "Edit"
@@ -59,8 +61,8 @@ class HostedHookEntry:
         native_module_name: The importable module name whose evaluate function
             the dispatcher calls in-process for this hook, or None when the hook
             runs via runpy under __main__. The named module exposes a function
-            named NATIVE_EVALUATE_FUNCTION_NAME taking the payload dict and
-            returning a deny-reason string or None.
+            named `evaluate` taking the payload dict and returning a deny-reason
+            string or None.
     """
 
     script_relative_path: str
@@ -94,6 +96,10 @@ ALL_HOSTED_HOOK_ENTRIES: tuple[HostedHookEntry, ...] = (
         script_relative_path="blocking/windows_rmtree_blocker.py",
         applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
     ),
+    HostedHookEntry(
+        script_relative_path="blocking/duplicate_rmtree_helper_blocker.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
     HostedHookEntry(
         script_relative_path="blocking/state_description_blocker.py",
         applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,

package/hooks/hooks_constants/test_post_tool_use_dispatcher_constants.py

@@ -0,0 +1,43 @@
+"""Tests for the PostToolUse dispatcher constants module."""
+
+import pathlib
+import sys
+
+_HOOKS_ROOT = pathlib.Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+_VALIDATION_DIR = _HOOKS_ROOT / "validation"
+if str(_VALIDATION_DIR) not in sys.path:
+    sys.path.insert(0, str(_VALIDATION_DIR))
+
+from post_tool_use_dispatcher import (
+    PostHostedHookResult,
+    aggregate_post_hosted_hook_results,
+)
+
+from hooks_constants.post_tool_use_dispatcher_constants import (
+    BLOCKING_CRASH_DENY_REASON,
+)
+
+
+def test_blocking_hook_crash_block_reason_surfaces_the_constant() -> None:
+    crash_result = PostHostedHookResult(
+        captured_stdout="",
+        did_crash=True,
+        is_blocking=True,
+    )
+    decision = aggregate_post_hosted_hook_results([crash_result])
+    assert decision.should_block
+    assert BLOCKING_CRASH_DENY_REASON in decision.all_block_reasons
+
+
+def test_non_blocking_hook_crash_does_not_surface_the_constant() -> None:
+    crash_result = PostHostedHookResult(
+        captured_stdout="",
+        did_crash=True,
+        is_blocking=False,
+    )
+    decision = aggregate_post_hosted_hook_results([crash_result])
+    assert not decision.should_block
+    assert BLOCKING_CRASH_DENY_REASON not in decision.all_block_reasons

package/hooks/hooks_constants/test_pre_tool_use_dispatcher_constants.py

@@ -0,0 +1,99 @@
+"""Tests for the PreToolUse dispatcher hosted-hook roster."""
+
+import importlib
+import pathlib
+import sys
+
+_HOOKS_ROOT = pathlib.Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+_BLOCKING_DIR = _HOOKS_ROOT / "blocking"
+if str(_BLOCKING_DIR) not in sys.path:
+    sys.path.insert(0, str(_BLOCKING_DIR))
+
+from hooks_constants.pre_tool_use_dispatcher_constants import (
+    ALL_HOSTED_HOOK_ENTRIES,
+    ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    BLOCKING_CRASH_DENY_REASON,
+    EDIT_TOOL_NAME,
+    WRITE_TOOL_NAME,
+)
+from pre_tool_use_dispatcher import (
+    HostedHookResult,
+    aggregate_hosted_hook_results,
+)
+
+
+def _entry_for(script_relative_path: str):
+    matching_entries = [
+        each_entry
+        for each_entry in ALL_HOSTED_HOOK_ENTRIES
+        if each_entry.script_relative_path == script_relative_path
+    ]
+    return matching_entries[0] if matching_entries else None
+
+
+def test_roster_includes_duplicate_rmtree_helper_blocker_script_path() -> None:
+    all_registered_script_paths = [
+        each_entry.script_relative_path for each_entry in ALL_HOSTED_HOOK_ENTRIES
+    ]
+    assert "blocking/duplicate_rmtree_helper_blocker.py" in all_registered_script_paths, (
+        "duplicate_rmtree_helper_blocker must be hosted by the dispatcher so a local "
+        "re-definition of the Windows-safe rmtree helper trio is blocked at Write time"
+    )
+
+
+def test_duplicate_rmtree_helper_blocker_applies_to_write_and_edit() -> None:
+    entry = _entry_for("blocking/duplicate_rmtree_helper_blocker.py")
+    assert entry is not None
+    assert WRITE_TOOL_NAME in entry.applicable_tool_names
+    assert EDIT_TOOL_NAME in entry.applicable_tool_names
+
+
+def test_duplicate_rmtree_helper_blocker_is_blocking() -> None:
+    entry = _entry_for("blocking/duplicate_rmtree_helper_blocker.py")
+    assert entry is not None
+    assert entry.is_blocking is True
+
+
+def test_duplicate_rmtree_helper_blocker_runs_via_runpy() -> None:
+    entry = _entry_for("blocking/duplicate_rmtree_helper_blocker.py")
+    assert entry is not None
+    assert entry.native_module_name is None
+
+
+def test_windows_rmtree_blocker_still_registered() -> None:
+    entry = _entry_for("blocking/windows_rmtree_blocker.py")
+    assert entry is not None
+    assert entry.applicable_tool_names == ALL_WRITE_AND_EDIT_TOOL_NAMES
+
+
+def test_blocking_hook_crash_deny_reason_surfaces_the_constant() -> None:
+    crash_result = HostedHookResult(
+        exit_code=0,
+        captured_stdout="",
+        did_crash=True,
+        is_blocking=True,
+    )
+    decision = aggregate_hosted_hook_results([crash_result])
+    assert decision.should_deny
+    assert BLOCKING_CRASH_DENY_REASON in decision.all_deny_reasons
+
+
+def test_every_native_module_exposes_a_callable_evaluate() -> None:
+    nativized_entries = [
+        each_entry
+        for each_entry in ALL_HOSTED_HOOK_ENTRIES
+        if each_entry.native_module_name is not None
+    ]
+    assert nativized_entries, (
+        "the roster must carry at least one nativized hook for this test to lock the contract"
+    )
+    for each_entry in nativized_entries:
+        native_module = importlib.import_module(each_entry.native_module_name)
+        evaluate_function = getattr(native_module, "evaluate", None)
+        assert callable(evaluate_function), (
+            f"{each_entry.native_module_name} must expose a callable named evaluate, "
+            "matching the native_module_name docstring contract"
+        )

package/hooks/hooks_constants/test_text_stripping.py

@@ -0,0 +1,39 @@
+"""Tests for the shared strip_code_and_quotes helper."""
+
+import pathlib
+import sys
+
+_HOOKS_ROOT = pathlib.Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+from hooks_constants.text_stripping import strip_code_and_quotes
+
+
+def test_removes_fenced_code_block() -> None:
+    text = "before\n```python\nshould I run this?\n```\nafter"
+    stripped = strip_code_and_quotes(text)
+    assert "should I run this?" not in stripped
+    assert "before" in stripped
+    assert "after" in stripped
+
+
+def test_removes_inline_code_span() -> None:
+    text = "the function `would you like` is named oddly"
+    stripped = strip_code_and_quotes(text)
+    assert "would you like" not in stripped
+    assert "the function" in stripped
+    assert "is named oddly" in stripped
+
+
+def test_removes_leading_blockquote_lines() -> None:
+    text = "real line\n> should I proceed?\nfinal line"
+    stripped = strip_code_and_quotes(text)
+    assert "should I proceed?" not in stripped
+    assert "real line" in stripped
+    assert "final line" in stripped
+
+
+def test_leaves_plain_prose_unchanged() -> None:
+    text = "This sentence carries no code or quotes."
+    assert strip_code_and_quotes(text) == text

package/hooks/hooks_constants/text_stripping.py

@@ -0,0 +1,36 @@
+"""Shared text-stripping helper for the Stop-hook prose blockers.
+
+Several Stop hooks judge the prose of an assistant message and must ignore
+fenced code blocks, inline code spans, and leading blockquotes so a phrase that
+appears only inside code or a quote never trips the detector. The stripping
+logic is identical across those blockers, so it lives here once and is imported
+from each.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = [
+    "strip_code_and_quotes",
+]
+
+CODE_BLOCK_PATTERN = re.compile(r"```[\s\S]*?```", re.MULTILINE)
+INLINE_CODE_PATTERN = re.compile(r"`[^`]+`")
+QUOTED_BLOCK_PATTERN = re.compile(r"^>.*$", re.MULTILINE)
+
+
+def strip_code_and_quotes(text: str) -> str:
+    """Remove fenced code blocks, inline code, and blockquotes from prose.
+
+    Args:
+        text: The raw assistant message to clean of code and quoted lines.
+
+    Returns:
+        The text with every fenced code block, inline code span, and leading
+        blockquote line removed, so only the prose a reader sees remains.
+    """
+    text = CODE_BLOCK_PATTERN.sub("", text)
+    text = INLINE_CODE_PATTERN.sub("", text)
+    text = QUOTED_BLOCK_PATTERN.sub("", text)
+    return text

package/hooks/validation/CLAUDE.md

@@ -9,6 +9,7 @@ PostToolUse hooks that validate code quality after Claude writes or edits a file
 | `mypy_validator.py` | PostToolUse (Write/Edit on `.py` files) | Runs mypy on the written file and blocks (via PostToolUse block decision) when type errors are found — catches missing attributes, wrong signatures, type mismatches, and import errors |
 | `hook_format_validator.py` | PostToolUse | Validates that a hook script's output JSON matches the expected Claude Code hook-output schema |
 | `test_mypy_validator.py` | — | Tests for `mypy_validator.py` |
+| `test_hook_format_validator.py` | — | Tests for `hook_format_validator.py` |
 
 ## Conventions
 

package/hooks/validation/post_tool_use_dispatcher.py

@@ -33,6 +33,7 @@ if _hooks_directory not in sys.path:
 from hooks_constants.post_tool_use_dispatcher_constants import (  # noqa: E402
     ALL_POST_HOSTED_HOOK_ENTRIES,
     BLOCK_DECISION,
+    BLOCKING_CRASH_DENY_REASON,
     DECISION_KEY,
     EMPTY_REASON_BLOCK_FALLBACK,
     HOOK_EVENT_NAME,
@@ -197,7 +198,6 @@ def aggregate_post_hosted_hook_results(
         A PostDispatcherDecision with the aggregated allow-or-block signal,
         all block reasons, and all non-block stdout.
     """
-    blocking_crash_reason = "[dispatcher] hook crash in blocking hook — write blocked for safety"
     all_block_reasons: list[str] = []
     all_non_block_stdout: list[str] = []
 
@@ -206,7 +206,7 @@ def aggregate_post_hosted_hook_results(
         if is_block:
             all_block_reasons.append(block_reason if block_reason else EMPTY_REASON_BLOCK_FALLBACK)
         elif each_result.did_crash and each_result.is_blocking:
-            all_block_reasons.append(blocking_crash_reason)
+            all_block_reasons.append(BLOCKING_CRASH_DENY_REASON)
         else:
             non_block_text = each_result.captured_stdout.strip()
             if non_block_text:

package/hooks/validation/test_mypy_validator.py

@@ -94,7 +94,7 @@ def test_build_mypy_command_includes_config_file_when_present(tmp_path: Path) ->
     assert command[-1] == "package/module.py"
 
 
-def test_build_mypy_command_omits_config_file_when_absent(tmp_path: Path) -> None:
+def test_build_mypy_command_omits_config_file_when_absent() -> None:
     validator = _load_validator()
 
     command = validator.build_mypy_command("package/module.py", None)

package/hooks/validation/test_post_tool_use_dispatcher.py

@@ -39,6 +39,7 @@ from hooks_constants.doc_gist_auto_publish_constants import (  # noqa: E402, I00
 from hooks_constants.post_tool_use_dispatcher_constants import (  # noqa: E402, I001
     ALL_POST_HOSTED_HOOK_ENTRIES,
     BLOCK_DECISION,
+    BLOCKING_CRASH_DENY_REASON,
     EMPTY_REASON_BLOCK_FALLBACK,
     PLUGIN_ROOT_PLACEHOLDER,
     PostHostedHookEntry,
@@ -608,3 +609,8 @@ def test_blocking_hook_crash_surfaces_a_block() -> None:
         "The block reason from a blocking hook crash must reference the dispatcher.\n"
         f"Got: {aggregated_decision.all_block_reasons[0]!r}"
     )
+    assert BLOCKING_CRASH_DENY_REASON in aggregated_decision.all_block_reasons, (
+        "The block reason from a blocking hook crash must be the "
+        "BLOCKING_CRASH_DENY_REASON constant.\n"
+        f"Got: {aggregated_decision.all_block_reasons!r}"
+    )

package/hooks/workflow/auto_formatter.py

@@ -79,11 +79,14 @@ def has_prettier_config(file_path: str) -> bool:
 def budgeted_python_format_seconds() -> int:
     """Return the wall-clock budget for the two-subprocess happy path.
 
-    The Python branch breaks out of each loop the moment a command runs, so
-    the common case spends one fix subprocess plus one format subprocess. This
-    is a budget for that assumed path, not a guaranteed upper bound: when a
-    command is missing or times out the loops fall through to the next entry,
-    so a degraded run can spend more than this budget.
+    The fix loop breaks on the first command that runs — whether it returns zero
+    or non-zero — or on a timeout, and continues to the next command only when a
+    command is missing (FileNotFoundError). The format loop breaks only on a
+    returncode of zero or on a timeout, and continues on a non-zero return or a
+    missing command. The common case spends one fix subprocess plus one format
+    subprocess. This is a budget for that assumed path, not a guaranteed upper
+    bound: when commands are missing or time out the loops can spend more than
+    this budget.
     """
     fix_phase_seconds = PYTHON_FORMAT_TIMEOUT_SECONDS
     format_phase_seconds = PYTHON_FORMAT_TIMEOUT_SECONDS

package/hooks/workflow/test_auto_formatter.py

@@ -105,6 +105,39 @@ class TestRuffFixOnNewFiles:
         assert completed_hook.returncode == 0
         assert "import os" in edited_file.read_text(encoding="utf-8")
 
+    def should_leave_tracked_python_file_arriving_through_write_untouched(
+        self, git_repository: Path
+    ) -> None:
+        tracked_file = git_repository / "tracked.py"
+        tracked_file.write_text(UNUSED_IMPORT_SOURCE, encoding="utf-8")
+        subprocess.run(
+            ["git", "add", "tracked.py"],
+            cwd=git_repository,
+            capture_output=True,
+            check=True,
+        )
+
+        completed_hook = _run_hook("Write", tracked_file)
+
+        assert completed_hook.returncode == 0
+        assert "import os" in tracked_file.read_text(encoding="utf-8")
+
+
+def test_tracked_write_leaves_unused_import_in_place(git_repository: Path) -> None:
+    tracked_file = git_repository / "tracked_module.py"
+    tracked_file.write_text(UNUSED_IMPORT_SOURCE, encoding="utf-8")
+    subprocess.run(
+        ["git", "add", "tracked_module.py"],
+        cwd=git_repository,
+        capture_output=True,
+        check=True,
+    )
+
+    completed_hook = _run_hook("Write", tracked_file)
+
+    assert completed_hook.returncode == 0
+    assert "import os" in tracked_file.read_text(encoding="utf-8")
+
 
 def _load_auto_formatter_module() -> object:
     module_spec = importlib.util.spec_from_file_location("auto_formatter", HOOK_SCRIPT_PATH)

package/package.json

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

package/rules/claude-md-orphan-file.md

@@ -1,24 +1,23 @@
 # Orphan File Reference in a Per-Directory CLAUDE.md
 
-**When this applies:** Any Write, Edit, or MultiEdit to a file named `CLAUDE.md` that lists files in a markdown table whose first column names each file in backticks.
+**When this applies:** Any Write, Edit, or MultiEdit to a file named `CLAUDE.md` that lists files in a markdown table whose first column names each file in backticks, or that shows run commands invoking those files inside fenced code blocks.
 
 ## Rule
 
-Every bare filename a per-directory `CLAUDE.md` table names in its first column points at a file that exists in the directory subtree the `CLAUDE.md` describes. A first-column cell naming a file that exists nowhere in that subtree points a reader at something that is not there: the listing claims a file the directory does not hold.
+Every bare filename a per-directory `CLAUDE.md` names points at a file that exists in the directory subtree the `CLAUDE.md` describes — both the filenames its table cells list and the scripts its fenced run commands invoke (`python script.py`). A table cell or a run command naming a file that exists nowhere in that subtree points a reader at something that is not there: the doc claims a file the directory does not hold.
 
-When you add a table row, the file it names already exists in this directory or a subdirectory of it. When you remove a file, drop the row that named it.
+When you add a table row or a run command, the file it names already exists in this directory or a subdirectory of it. When you remove a file, drop the row and the run command that named it.
 
 ## What the gate checks
 
 The `claude_md_orphan_file_blocker.py` hook runs on every Write, Edit, and MultiEdit whose target basename is `CLAUDE.md`. It:
 
 1. Reads the content the tool would leave on disk. For a Write that is the full `content`. For an Edit or MultiEdit it reconstructs the post-edit file — the existing on-disk file with the replacements applied — and also notes which orphans the file already held before the edit, 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` fragment(s) instead.
-2. Skips any line inside a fenced code block (between a ``` or `~~~` fence pair), since an example table there is documentation, not a live listing.
-3. Takes the first column of each remaining markdown table row and keeps the cells that name a bare filename: wrapped in backticks, no path separator, not a slash-command, and ending in a known file extension (`.py`, `.md`, `.json`, `.mjs`, `.js`, `.ts`, `.ps1`, `.cmd`, `.ahk`, `.yml`, `.yaml`, `.sh`, `.txt`, `.cfg`, `.toml`, `.ini`).
-4. Blocks the write when a named file exists nowhere under the scan root — the `CLAUDE.md` directory's parent, which covers the directory, its subdirectories, and its siblings. A filesystem error that halts the whole subtree walk fails open (the write proceeds), so an unreadable tree never blocks a write.
+2. Collects two kinds of referenced filename. Table cells: the first column of each markdown table row **outside** a fenced code block, keeping cells that name a bare filename wrapped in backticks, no path separator, not a slash-command, ending in a known file extension (`.py`, `.md`, `.json`, `.mjs`, `.js`, `.ts`, `.ps1`, `.cmd`, `.ahk`, `.yml`, `.yaml`, `.sh`, `.txt`, `.cfg`, `.toml`, `.ini`). Run commands: each line **inside** a fenced code block (between a ``` or `~~~` fence pair) that invokes an interpreter (`python`, `python.exe`, `python3`, `node`, `pwsh`, `powershell`, `bash`, `sh`, `ruby`, `perl`) on a script, taking that script's basename when it ends in `.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`, `.rb`, or `.pl`. A fenced *table row* is an example, not a live listing, so it contributes no table-cell filename; a fenced *run command* is the contract a reader runs, so its script filename is checked.
+3. Blocks the write when a referenced filename — from a table cell or a fenced run command — exists nowhere under the scan root — the `CLAUDE.md` directory's parent, which covers the directory, its subdirectories, and its siblings. A filesystem error that halts the whole subtree walk fails open (the write proceeds), so an unreadable tree never blocks a write.
 
-The check stays quiet for a target that is not a `CLAUDE.md`, for a table cell that holds a path, a subdirectory ending in `/`, or a slash-command, for a table row inside a fenced code block, and for a table whose content names an explicit relative-path source (a `../` token), since that table documents files that sit outside the subtree by design.
+The check stays quiet for a target that is not a `CLAUDE.md`, for a table cell that holds a path, a subdirectory ending in `/`, or a slash-command, for a table row inside a fenced code block, for an inline `python x.py` mention outside a fence (prose, not a runnable contract), and for a table whose content names an explicit relative-path source (a `../` token), since that table documents files that sit outside the subtree by design.
 
 ## Why this is a hook, not a lint pass
 
-A table row that names an absent file reads as a contract: a reader trusts the listing to map the directory. A wrong row sends the reader looking for a file that is not there and erodes trust in every other row. Catching it as each row is written keeps the table and the directory in step.
+A table row or a run command that names an absent file reads as a contract: a reader trusts the listing to map the directory and trusts the shown command to run. A wrong row sends the reader looking for a file that is not there; a stale run command fails the moment the reader runs it. Both erode trust in every other entry. Catching them as each line is written keeps the doc and the directory in step.

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

@@ -16,6 +16,7 @@ Read the body and the docstring side by side:
 - **Suppressor / skip lists.** A body with several early returns that suppress the check names each suppressor in the prose.
 - **Shared fallback routes.** A summary that scopes a fallback call to one condition names every condition that reaches that call. When the body routes to the same fallback from two or more early-return guards (`if a is None: fallback(); return` and `if random() < p: fallback(); return`), the prose enumerates both guards. The `check_docstring_fallback_branch_coverage` gate blocks the single-condition form of this drift at Write/Edit time.
 - **Step order.** A docstring that says `A then B then C` matches the call order in the body. A step enumeration that names the body's linear steps also names every corrective step the body guards inside an `if`/`elif` branch (`if not await cancel_and_reinitiate_update(...): return`). The `check_docstring_step_enumeration_dispatch_coverage` gate blocks the branch-guarded-dispatch form of this drift — a step-enumeration docstring that omits a two-or-more-token dispatch step the body guards inside a branch — at Write/Edit time.
+- **JS/`.mjs` resume-task enumerations.** A `spawn<Role>Agent` JSDoc that enumerates its sibling `resume<Role>Agent`'s resume tasks in a parenthetical `resume (repair-verify, hardening-verify)` list names every `task === '<name>'` branch the resume body dispatches on. The `check_js_resume_task_enumeration_coverage` gate blocks the JavaScript form of this drift — a spawn JSDoc whose resume enumeration omits a dispatched task — at Write/Edit time. This is the `.mjs` slice of the same Category O6 standard the Python gates carry; the Python AST docstring gates never inspect JavaScript source.
 - **Returns-clause cardinality.** A `Returns:` clause that names a dict-key prefix family with a plural noun (`the sheen stops`) matches the count of keys in that family in the returned dict literal. When the dict holds one key in the family (`sheen_mid`), the noun is singular (`the sheen stop`); a plural noun there claims two or more entries the dict does not hold. The `check_docstring_returns_plural_cardinality` gate blocks the single-key-with-plural-noun form of this drift at Write/Edit time.
 - **Predicate breadth.** A boolean helper whose prose promises a narrow check accepts only the inputs the prose names — no broader input class the name and prose do not mention.
 - **Exclusion-clause distinguisher.** A docstring sentence that says a named category of input "are not" / "is not" the thing the function flags (`plain logging, screenshot, or method-on-local calls inside a branch are not dispatch steps`) keys the exclusion to the same axis the body's classification keys on. When the body decides on one axis (a call sits in an `If.test` guard versus a plain statement) but the prose excludes on a different axis (the call's receiver shape — a method on a local), the exclusion clause names a category the body still flags: a guarded method-on-local call is flagged even though the prose lists method-on-local calls as excluded. Read the body's actual branch condition, then state the exclusion on that same axis (`plain (unguarded) calls inside a branch body are not dispatch steps`), so every member the prose excludes is a member the body also excludes.

package/rules/package-inventory-stale-entry.md

@@ -8,6 +8,14 @@ A package directory that documents its own files in a `README.md` Layout table o
 
 When you create a new production file in such a directory, add an entry naming it — a row in the `README.md` table, a bullet in the `CLAUDE.md` list — in the same change. The entry names the file in backticks and says what it does.
 
+## Companion: keep the Purpose/scope sentence in step with the new responsibility
+
+The file-list entry is the deterministic slice the gate enforces. A package inventory also carries a free-prose scope sentence — a `## Purpose` paragraph in a `CLAUDE.md`, a one-line summary the parent directory's inventory gives each subdirectory — that names the responsibilities the package's modules cover. When the new module adds a responsibility the scope sentence omits, the same change broadens that sentence to name it, and updates the parent inventory's one-line summary of this subdirectory to match.
+
+Take a `files/` package whose `Purpose` reads "Holds helpers for downloading files over HTTP and extracting zip archives" and whose parent summary reads "file download, extraction, and path config helpers". Once a `force_remove.py` module that removes a directory tree sits beside the download helpers, both sentences name a narrower responsibility set than the directory holds. The required file-list bullet alone leaves that gap open. Broaden the `Purpose` sentence to name directory removal, and broaden the parent summary to match, in the same change that adds the module and its bullet.
+
+This scope-sentence slice is free prose: a hook cannot derive a module's responsibility from its filename, so the gate leaves it to judgment. It is the judgment companion to the file-list entry the gate enforces, and it belongs in the same change. This is the `category-o-docstring-vs-impl-drift` (O8) orphaned-doc-claim shape applied to a package inventory: a behavior change orphans a scope claim the prose still makes.
+
 ## What the gate checks
 
 The `package_inventory_stale_blocker.py` hook runs on every Write whose target is a new file (a path not yet on disk). It:

package/rules/windows-filesystem-safe.md

@@ -5,3 +5,5 @@ Never call `shutil.rmtree` with `ignore_errors=True` — Windows `ReadOnly` file
 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)`).
 
 The `windows_rmtree_blocker.py` PreToolUse hook (Write/Edit/Bash) blocks the unsafe rmtree pattern and returns the full `force_rmtree` safe-pattern code.
+
+Define the safe handler trio (`_strip_read_only_and_retry`, `_force_remove_tree` / `force_rmtree`, and the `inspect.signature` onexc/onerror guard) once in a shared Windows-filesystem utility module, and import it from every call site. A second local copy drifts from the first — a fix lands in one and the other keeps the bug (CODE_RULES.md section 3, Reuse before create). The `duplicate_rmtree_helper_blocker.py` PreToolUse hook (Write/Edit) blocks a local re-definition of any trio member outside the shared home and points the writer at the import. This complements the same-directory `check_duplicate_function_body_across_files` gate, which a copy between two distant packages slips past.

package/skills/anthropic-plan/CLAUDE.md

@@ -2,7 +2,7 @@
 
 **Trigger:** `/anthropic-plan`, `/plan`, "plan this first", "think before coding", "make a plan", "scope this out", "don't code yet", and non-trivial requests that need source-grounded design before build work.
 
-Creates a repo-local plan packet under `docs/plans/<slug>/` by running the `plan-packet.mjs` workflow. The packet holds context, spec, implementation steps, validation, and a handoff prompt for the build agent. The skill stops before any production code changes.
+Creates a repo-local plan packet under `docs/plans/<slug>/` by running the `plan-packet.mjs` workflow. The skill first drafts a short starting plan and gets the user's approval in plan mode (`EnterPlanMode` / `ExitPlanMode`); on approval it runs the workflow. The packet holds context, spec, implementation steps, validation, and a handoff prompt for the build agent. The skill stops before any production code changes.
 
 ## Subdirectories
 

package/skills/anthropic-plan/SKILL.md

@@ -5,9 +5,20 @@ description: Workflow-backed implementation planning that creates a deep repo-lo
 
 # Anthropic Plan
 
-Create a source-grounded plan packet through the Claude Code Workflow runtime. The output is a repo-local `docs/plans/<slug>/` folder with context, spec, implementation, validation, and handoff docs. Stop before implementation.
+Create a source-grounded plan packet through the Claude Code Workflow runtime. First draft a short starting plan and get it approved in plan mode; then the workflow builds the full repo-local `docs/plans/<slug>/` packet — context, spec, implementation, validation, and handoff docs. Stop before implementation.
 
-## Isolate first
+## Plan first (plan mode)
+
+Before any worktree or workflow, build a short starting plan in plan mode and get the user's approval. This is a cheap gate: it confirms the direction before the workflow spends tokens building the full packet.
+
+1. Enter plan mode with `EnterPlanMode` if the session is not already in it.
+2. Read the handful of files closest to the request — the entry points, the modules the change touches, the tests that cover them — enough to ground the approach in real source.
+3. Write a short plan: the goal in a sentence or two, the approach, the files the build will touch, and the main risks or open choices. Use `AskUserQuestion` for any product choice that local context cannot settle.
+4. Call `ExitPlanMode` to hand the plan to the user for approval.
+
+On approval, fold the approved scope and direction into the `task` payload at launch, then continue with the steps below. If the user revises the plan, fold the changes in and present it again. Do not isolate a worktree or launch the workflow until the starting plan is approved.
+
+## Isolate the session
 
 The workflow's background subagents write the packet into the working tree. A background session that has not isolated into a worktree cannot write a shared checkout — the background-isolation guard rejects the write. So put the session in a worktree before launching the workflow:
 
@@ -27,6 +38,8 @@ Workflow({
 })
 ```
 
+The `task` string carries the user request together with the approved starting plan, so the packet reflects the direction the user signed off on.
+
 If the Workflow tool is unavailable, say `anthropic-plan requires the Workflow tool; aborting` and stop.
 
 ## Self-healing writes

package/skills/autoconverge/SKILL.md

@@ -266,9 +266,12 @@ describes the narrowest rm auto-allow path — a standalone Bash call whose targ
 resolves inside the ephemeral namespace (`/tmp`, `/temp`, the OS temp root, or the
 run worktree) — and a compound path that accepts an rm joined with benign
 reporting segments when every rm target is an absolute ephemeral path. Both of
-those paths fail closed on `$(...)` substitution, backtick subshells, and any `$`
-in the target — including `$CLAUDE_JOB_DIR` — so neither resolves an environment
-variable. A third, broad path matches only when the command itself declares an
+those paths fail closed on `$(...)` substitution and backtick subshells. The
+compound path also fails closed on any `$` in the target — including
+`$CLAUDE_JOB_DIR`. The standalone path declines a `$`-bearing target only when
+the literal path is not already under an ephemeral root, so it does not by
+itself stop a `$VAR` that expands inside an ephemeral root. A third, broad path
+matches only when the command itself declares an
 ephemeral working directory (it `cd`s into one, or runs under one): that
 cwd-scoped path resolves the target against the declared cwd, fails closed on
 `$(...)`, backticks, and unknown variables, and resolves the known temporary

package/skills/autoconverge/reference/stop-conditions.md

@@ -31,6 +31,13 @@ skill still runs teardown (revoke permissions, final report).
   cannot confirm the PR left draft state (`gh pr ready` errored, or the draft
   re-query still reports true). The workflow does not report `converged: true`;
   the run ends with a `blocker` naming the failed ready transition.
+- **Clean-audit post blocked** — every review lens is clean on HEAD, but the
+  CLEAN bugteam review cannot be posted (the `post_audit_thread.py` post is
+  denied, errors, or its agent dies). The convergence gate's bugteam-review
+  check can never pass without that CLEAN review, so the run stops rather than
+  re-converge to the iteration cap. The `blocker` names the post failure and the
+  HEAD. Unblock by allowing `post_audit_thread.py` with a Bash permission rule,
+  or post the CLEAN review by hand, then re-run.
 
 ## Not a blocker (the run continues)
 

package/skills/autoconverge/workflow/converge.clean-audit.test.mjs

@@ -40,8 +40,9 @@ test('cleanAuditBlocker falls back to a no-result reason when the post agent die
   assert.match(message, /the post agent returned no result/);
 });
 
-test('postCleanAudit returns the CLEAN_AUDIT_SCHEMA result rather than an unused transcript', () => {
-  const body = functionBody('postCleanAudit');
+test('the post-clean-audit task in resumeGeneralUtilityAgent returns the CLEAN_AUDIT_SCHEMA result rather than an unused transcript', () => {
+  const body = functionBody('resumeGeneralUtilityAgent');
+  assert.match(body, /task === 'post-clean-audit'/);
   assert.match(body, /schema: CLEAN_AUDIT_SCHEMA/);
   assert.doesNotMatch(body, /agent transcript \(unused\)/);
 });
@@ -58,7 +59,7 @@ test('the standards-only call site breaks with a clean-audit blocker when the po
     convergeSource.indexOf('if (isStandardsOnlyRound(findings)) {'),
     convergeSource.indexOf('if (findings.length > 0) {'),
   );
-  assert.match(branch, /const auditResult = await postCleanAudit\(head\)/);
+  assert.match(branch, /resumeGeneralUtilityAgent\(.*'post-clean-audit'/);
   assert.match(branch, /if \(!auditResult\?\.posted\)/);
   assert.match(branch, /blocker = cleanAuditBlocker\(head, auditResult\)/);
   assert.match(branch, /\bbreak\b/);
@@ -69,7 +70,7 @@ test('the all-clean call site breaks with a clean-audit blocker when the post do
     convergeSource.indexOf('all lenses clean on'),
     convergeSource.indexOf("if (phase === 'COPILOT') {"),
   );
-  assert.match(branch, /const auditResult = await postCleanAudit\(head\)/);
+  assert.match(branch, /resumeGeneralUtilityAgent\(.*'post-clean-audit'/);
   assert.match(branch, /if \(!auditResult\?\.posted\)/);
   assert.match(branch, /blocker = cleanAuditBlocker\(head, auditResult\)/);
   assert.match(branch, /\bbreak\b/);