claude-dev-env 1.73.0 → 1.75.0

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/lifecycle/config_change_guard.py

@@ -4,6 +4,13 @@ from datetime import datetime
 import json
 import os
 import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 
 AUDIT_LOG = os.path.expanduser("~/.claude/cache/config-change-audit.log")
 # pragma: no-tdd-gate
@@ -68,6 +75,11 @@ def guard_hook_injection(file_path: str) -> None:
             "decision": "block",
             "reason": block_reason,
         }
+        log_hook_block(
+            calling_hook_name="config_change_guard.py",
+            hook_event="ConfigChange",
+            block_reason=block_reason,
+        )
         print(json.dumps(block_payload))
         return
 

package/hooks/lifecycle/test_config_change_guard.py

@@ -109,3 +109,26 @@ def test_non_user_settings_source_produces_no_output(tmp_path: Path) -> None:
     assert hook_run.returncode == 0
     assert hook_run.stderr.strip() == ""
     assert hook_run.stdout.strip() == ""
+
+
+def test_block_logs_config_change_event(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    known_count_file = tmp_path / "known-hook-count.txt"
+    known_count_file.write_text("2")
+    settings_path = _make_settings_with_hook_count(5, tmp_path)
+
+    hook_run = _run_hook(
+        source="user_settings",
+        file_path=settings_path,
+        extra_env={
+            "KNOWN_HOOK_COUNT_FILE": str(known_count_file),
+            "HOME": str(fake_home),
+            "USERPROFILE": str(fake_home),
+        },
+    )
+
+    assert hook_run.returncode == 0
+    log_path = fake_home / ".claude" / "logs" / "hook-blocks.log"
+    logged_record = json.loads(log_path.read_text(encoding="utf-8").splitlines()[-1])
+    assert logged_record["event"] == "ConfigChange"

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/hook_format_validator.py

@@ -7,7 +7,13 @@ Blocks if hooks use simple 'python3 ~/.claude/...' instead of the exec(open(...)
 import json
 import re
 import sys
+from pathlib import Path
 
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 
 SIMPLE_PATTERN = re.compile(
     r'python3?\s+~/\.claude/hooks/'
@@ -56,6 +62,13 @@ def main() -> None:
                 "permissionDecisionReason": message
             }
         }
+        log_hook_block(
+            calling_hook_name="hook_format_validator.py",
+            hook_event="PreToolUse",
+            block_reason=message,
+            tool_name=tool_name,
+            offending_input_preview=file_path,
+        )
         print(json.dumps(result))
         sys.exit(0)
 

package/hooks/validation/mypy_validator.py

@@ -35,6 +35,7 @@ if _hooks_directory not in sys.path:
 
 from mypy_integration import find_pyproject_with_mypy_config  # noqa: E402
 
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.mypy_validator_cache_constants import (  # noqa: E402
     CACHE_FILE_ENCODING,
     CONTENT_HASH_CACHE_PASSING_EXIT_CODE,
@@ -293,6 +294,28 @@ def build_mypy_command(relative_file_path: str, mypy_config_file: Path | None) -
     ]
 
 
+def project_relative_path(target_file: str, project_root: str) -> str:
+    """Return *target_file* relative to *project_root*, or its absolute path.
+
+    On Windows ``os.path.relpath`` raises ``ValueError`` when the two paths sit
+    on different mounts (for example a ``Y:`` drive file against a project root
+    that resolved to its backing UNC share), so no relative path can span them.
+    The absolute target path is then handed to mypy unchanged, which accepts it.
+
+    Args:
+        target_file: The absolute path of the file to type-check.
+        project_root: The directory mypy runs from.
+
+    Returns:
+        The path relative to *project_root* when one exists, otherwise the
+        absolute path of *target_file*.
+    """
+    try:
+        return os.path.relpath(target_file, project_root)
+    except ValueError:
+        return os.path.abspath(target_file)
+
+
 def run_mypy(target_file: str, project_root: str) -> tuple[int, str]:
     """Run mypy on one file from the project root and return its result.
 
@@ -325,7 +348,7 @@ def run_mypy(target_file: str, project_root: str) -> tuple[int, str]:
     Returns:
         The mypy exit code paired with its combined stdout and stderr text.
     """
-    relative_file_path = os.path.relpath(target_file, project_root)
+    relative_file_path = project_relative_path(target_file, project_root)
     mypy_config_file = discover_mypy_config(Path(target_file))
 
     content_hash = _composite_content_hash(target_file, mypy_config_file)
@@ -457,6 +480,12 @@ def main() -> None:
     error_summary = format_error_summary(all_error_lines)
     send_block_notification(error_summary)
     block_response = build_block_response(error_summary)
+    log_hook_block(
+        calling_hook_name="mypy_validator.py",
+        hook_event="PostToolUse",
+        block_reason=f"[MYPY] Type errors: {error_summary}",
+        offending_input_preview=target_file_path,
+    )
     print(json.dumps(block_response))
     sys.exit(0)
 

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_hook_format_validator.py

@@ -0,0 +1,64 @@
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+HOOK_PATH = Path(__file__).parent / "hook_format_validator.py"
+
+
+def _run_hook(
+    payload: dict[str, object],
+    extra_env: dict[str, str] | None = None,
+) -> subprocess.CompletedProcess[str]:
+    env = {**os.environ, **(extra_env or {})}
+    return subprocess.run(
+        [sys.executable, str(HOOK_PATH)],
+        input=json.dumps(payload),
+        text=True,
+        capture_output=True,
+        check=False,
+        env=env,
+    )
+
+
+def test_simple_pattern_blocks_with_deny_payload(tmp_path: Path) -> None:
+    settings_path = tmp_path / ".claude" / "settings.json"
+    payload = {
+        "tool_name": "Edit",
+        "tool_input": {
+            "file_path": str(settings_path),
+            "new_string": "python3 ~/.claude/hooks/blocking/my-hook.py",
+        },
+    }
+
+    hook_run = _run_hook(payload)
+
+    assert hook_run.returncode == 0
+    deny_payload = json.loads(hook_run.stdout)
+    hook_specific_output = deny_payload["hookSpecificOutput"]
+    assert hook_specific_output["hookEventName"] == "PreToolUse"
+    assert hook_specific_output["permissionDecision"] == "deny"
+
+
+def test_block_logs_pre_tool_use_event(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    settings_path = tmp_path / ".claude" / "settings.json"
+    payload = {
+        "tool_name": "Edit",
+        "tool_input": {
+            "file_path": str(settings_path),
+            "new_string": "python3 ~/.claude/hooks/blocking/my-hook.py",
+        },
+    }
+
+    hook_run = _run_hook(
+        payload,
+        extra_env={"HOME": str(fake_home), "USERPROFILE": str(fake_home)},
+    )
+
+    assert hook_run.returncode == 0
+    log_path = fake_home / ".claude" / "logs" / "hook-blocks.log"
+    logged_record = json.loads(log_path.read_text(encoding="utf-8").splitlines()[-1])
+    assert logged_record["event"] == "PreToolUse"

package/hooks/validation/test_mypy_validator.py

@@ -15,6 +15,8 @@ the cache directory redirected to a temporary directory.
 """
 
 import importlib.util
+import os
+import sys
 from pathlib import Path
 from types import ModuleType
 
@@ -92,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)
@@ -275,3 +277,23 @@ def test_content_hash_skip_invalidated_when_mypy_config_tightens(
     )
     assert tightened_exit_code != 0
     assert ": error:" in tightened_output
+
+
+def test_project_relative_path_within_root_returns_relative() -> None:
+    validator = _load_validator()
+    project_root = os.path.join("base", "project")
+    target_file = os.path.join(project_root, "package", "module.py")
+    assert validator.project_relative_path(target_file, project_root) == os.path.join(
+        "package", "module.py"
+    )
+
+
+def test_project_relative_path_across_mounts_falls_back_to_absolute() -> None:
+    if sys.platform != "win32":
+        pytest.skip("cross-mount relpath ValueError only occurs on Windows")
+    validator = _load_validator()
+    target_file = "Y:\\repository\\package\\module.py"
+    project_root = "C:\\other\\root"
+    assert validator.project_relative_path(target_file, project_root) == os.path.abspath(
+        target_file
+    )

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.73.0",
+    "version": "1.75.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/CLAUDE.md

@@ -28,6 +28,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `no-historical-clutter.md` | Documentation describes current state only; no historical or transitional language |
 | `no-inline-destructive-literals.md` | No destructive-command literals in Bash tool command strings, even as data |
 | `orphan-css-class.md` | Every `class="..."` attribute in Python-generated markup has a matching selector in the `<style>` block |
+| `package-inventory-stale-entry.md` | A new production code file added to a directory carries an entry in that directory's `README.md`/`CLAUDE.md` file inventory |
 | `parallel-tools.md` | Make all independent tool calls in a single response |
 | `plain-language.md` | Everyday words, short active sentences, lead with the answer |
 | `prompt-workflow-context-controls.md` | Keep prompt-workflow instruction layers small and stable; load heavy skills on demand |

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

@@ -6,7 +6,7 @@
 
 When a docstring enumerates the behaviors a body applies, the enumeration covers every behavior the body applies. A reader trusts the list to be complete: an item the code applies but the prose omits is a silent gap that misleads every future reader and reviewer.
 
-The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Three more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. `check_docstring_no_consumer_claim` covers a producer docstring asserting that no consumer reads its output yet (`producer-only artifact`, `no submission-run consumer reads it yet`) — a transitional claim that drifts the moment a reader lands and contradicts any companion `SKILL.md` that documents the consumer; this is the deterministic slice of the O8 companion-doc producer/consumer drift below. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and module-level responsibility paragraphs — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the four gated slices.
+The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Four more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. `check_docstring_no_consumer_claim` covers a producer docstring asserting that no consumer reads its output yet (`producer-only artifact`, `no submission-run consumer reads it yet`) — a transitional claim that drifts the moment a reader lands and contradicts any companion `SKILL.md` that documents the consumer; this is the deterministic slice of the O8 companion-doc producer/consumer drift below. `check_docstring_returns_plural_cardinality` covers a `Returns:` clause that names a dict-key prefix family with a plural noun (`the sheen stops`) while the returned dict literal holds exactly one key in that family (`sheen_mid`) — the drift where a single-key family carries a plural noun, so the prose claims a cardinality of two or more that the dict does not hold. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and module-level responsibility paragraphs — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the five gated slices.
 
 ## What to check before you write the docstring
 
@@ -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.
+- **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.
 - **Companion-doc ordering and content claims.** A `SKILL.md` (or sibling `.md`) sentence that names a produced artifact and claims its order (`sorted`, `alphabetical`, `in sorted order`) or its content (`the at-risk names`, `just the current set`) matches the producer function's docstring and body for that same artifact. A producer that builds the artifact by merging stored names with new names and appending — preserving file order, not re-sorting the union — leaves a doc that still says `sorted` drifted on both counts: the order claim is wrong, and the content claim hides the merged-in prior entries. When the producer's ordering or union changes, the same change updates the companion doc. The two move together in one commit, even when the producer edit does not touch the `.md` file.

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

@@ -0,0 +1,24 @@
+# New Production File Absent From Its Package Inventory
+
+**When this applies:** Any Write that creates a new production code file (`.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`) in a directory whose sibling `README.md` or `CLAUDE.md` already names two or more of the directory's files in backticks.
+
+## Rule
+
+A package directory that documents its own files in a `README.md` Layout table or a `CLAUDE.md` "Key files" list keeps that inventory in step with the directory. A new production file the inventory does not name leaves the inventory and the directory disagreeing on the package's file set: a reader who trusts the inventory to map the directory misses the new file.
+
+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.
+
+## 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:
+
+1. Skips a target that is not a production code file (`.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`), an exempt basename (`__init__.py`, `conftest.py`, `setup.py`, `_path_setup.py`), a test file (`test_*.py`, `*_test.py`, `*.spec.*`, `*.test.*`), or a file directly inside a `config/` or `tests/` directory.
+2. Reads each `README.md` and `CLAUDE.md` present in the target's own directory and collects every bare filename they name in backticks. A backticked token holding a path contributes its final segment, so `pipeline/seam_continuity.py` in an inventory counts as naming `seam_continuity.py`. A multi-word command-example span — one carrying whitespace or shell punctuation (`:`, `$`, `<`, `>`), such as `parent:node_modules package.json` or `python <file>.py` — names no literal file and is dropped.
+3. Filters the named basenames to those that exist as a file in the target's own directory — the inventory's own sibling files — and treats the directory as carrying a maintained inventory only when two or more such sibling files are named. A directory with no inventory, one whose `README.md` mentions a single file in passing, or one whose inventory prose names only files living in other directories (so no named basename is an on-disk sibling) is out of scope.
+4. Blocks the write when the new file's basename appears in no present inventory. An unreadable or oversized inventory document is skipped, so a missing inventory never blocks a write.
+
+The check fires on Write only — editing an existing file adds no new inventory entry — and stays quiet for a directory with no inventory document, an inventory naming too few siblings to be a maintained list, an exempt or test file, and a file the inventory already names.
+
+## Why this is a hook, not a lint pass
+
+A package inventory that omits a file reads as a complete map of the directory while leaving one file off it. A reader trusting the inventory to list the package misses the new file, and the gap survives review because the inventory still looks complete. Catching it as the new file is written keeps the inventory and the directory in step. This is the counterpart to `claude-md-orphan-file.md`, which catches the reverse drift: an inventory entry naming a file the directory does not hold.

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/autoconverge/SKILL.md

@@ -261,7 +261,27 @@ agents never inline a destructive-command literal (`rm -rf`, `git reset --hard`,
 `dd`) into a Bash command — the `destructive_command_blocker` hook matches those
 patterns as raw text, and a confirmation prompt no human can answer would stall
 the run. Agents verify destructive-blocker behavior through the committed test
-suite (`python -m pytest`) and keep scratch work in ephemeral temp dirs.
+suite (`python -m pytest`) and keep scratch work in the OS temp dir. The preamble
+describes the narrowest rm auto-allow path — a standalone Bash call whose target
+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 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
+variables `TEMP`, `TMP`, `TMPDIR`, and `CLAUDE_JOB_DIR` to the OS temp root, so
+under that declared ephemeral cwd a bare `$CLAUDE_JOB_DIR/tmp/<name>` target and a
+relative target after a `cd` are auto-allowed. Even so, for any cleanup whose path
+is variable-built or whose teardown spans multiple steps, agents author a Python
+helper file and run it as `python <file>.py` — keeping every destructive literal
+out of a Bash command string entirely and independent of which auto-allow path
+matches.
 
 - **Converge:** `parallel([Bugbot lens, code-review lens, bug-audit lens])` on
   the current HEAD, full `origin/main...HEAD` diff. Dedup findings; one

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/);