claude-dev-env 2.4.0 → 2.7.0

package/hooks/validators/test_run_all_validators_pretooluse.py

@@ -8,6 +8,7 @@ when that content violates a validator, rather than grading the whole branch.
 import json
 import subprocess
 import sys
+import tempfile
 from collections import Counter
 from pathlib import Path
 from unittest.mock import patch
@@ -16,12 +17,21 @@ import pytest
 
 from .run_all_validators import (
     ValidatorResult,
+    _escapes_temporary_root,
+    _hooks_subprocess_working_directory_and_environment,
     _scope_new_and_preexisting,
+    _temporary_path_preserving_directory_signal,
     _violation_line_number,
     main,
     run_validators_entrypoint_subprocess,
 )
 
+CONFIG_DIR_TARGET_PATH = (
+    "CDP Automations/os_update_workflow/config/submission_constants.py"
+)
+PARENT_TRAVERSAL_TARGET_PATH = "../../escape_target.py"
+RELATIVE_CONFIG_TARGET_PATH = "config/x.py"
+
 CLEAN_PYTHON_SOURCE = (
     "def add_two_numbers(first_number: int, second_number: int) -> int:\n"
     "    return first_number + second_number\n"
@@ -85,7 +95,9 @@ class TestPreToolUseGate:
     def test_edit_validates_reconstructed_post_edit_content(
         self, tmp_path: Path
     ) -> None:
-        target_file = tmp_path / "calculate.py"
+        target_directory = tmp_path / "neutral_edit_target"
+        target_directory.mkdir(exist_ok=True)
+        target_file = target_directory / "calculate.py"
         target_file.write_text(CLEAN_PYTHON_SOURCE, encoding="utf-8")
         completed = run_gate(
             {
@@ -107,6 +119,152 @@ class TestPreToolUseGate:
         assert completed.returncode == 0, completed.stderr
         assert "deny" not in completed.stdout
 
+    def test_write_to_config_dir_path_is_not_denied(self) -> None:
+        completed = run_gate(
+            {
+                "tool_name": "Write",
+                "tool_input": {
+                    "file_path": CONFIG_DIR_TARGET_PATH,
+                    "content": VIOLATING_PYTHON_SOURCE,
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert "deny" not in completed.stdout
+
+    def test_write_relative_config_path_not_denied_when_cwd_under_system_temp(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        system_temp_root = Path(tempfile.gettempdir()).resolve()
+        monkeypatch.setenv("TEMP", str(system_temp_root))
+        monkeypatch.setenv("TMP", str(system_temp_root))
+        monkeypatch.setenv("TMPDIR", str(system_temp_root))
+        with tempfile.TemporaryDirectory(
+            dir=str(system_temp_root), prefix="gate_cwd_"
+        ) as temporary_root_string:
+            temporary_cwd = Path(temporary_root_string) / "gate_cwd"
+            temporary_cwd.mkdir()
+
+            def working_directory_under_system_temp() -> tuple[str, dict[str, str]]:
+                _working_directory, environment = (
+                    _hooks_subprocess_working_directory_and_environment()
+                )
+                return str(temporary_cwd), environment
+
+            with patch(
+                "validators.run_all_validators._hooks_subprocess_working_directory_and_environment",
+                side_effect=working_directory_under_system_temp,
+            ):
+                completed = run_gate(
+                    {
+                        "tool_name": "Write",
+                        "tool_input": {
+                            "file_path": RELATIVE_CONFIG_TARGET_PATH,
+                            "content": VIOLATING_PYTHON_SOURCE,
+                        },
+                    }
+                )
+        assert completed.returncode == 0, completed.stderr
+        assert "deny" not in completed.stdout
+
+    def test_write_to_parent_traversal_path_still_validates(self) -> None:
+        completed = run_gate(
+            {
+                "tool_name": "Write",
+                "tool_input": {
+                    "file_path": PARENT_TRAVERSAL_TARGET_PATH,
+                    "content": VIOLATING_PYTHON_SOURCE,
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' in completed.stdout
+        assert "Magic Values" in completed.stdout
+
+
+class TestTemporaryPathPreservingDirectorySignal:
+    def test_strips_parent_traversal_segments(self, tmp_path: Path) -> None:
+        assert _escapes_temporary_root("..") is True
+        staged_path = _temporary_path_preserving_directory_signal(
+            tmp_path, PARENT_TRAVERSAL_TARGET_PATH
+        )
+        assert staged_path == tmp_path / "escape_target.py"
+        assert staged_path.resolve().is_relative_to(tmp_path.resolve())
+
+    def test_keeps_config_directory_segment(self, tmp_path: Path) -> None:
+        staged_path = _temporary_path_preserving_directory_signal(
+            tmp_path, CONFIG_DIR_TARGET_PATH
+        )
+        assert staged_path.name == "submission_constants.py"
+        assert "config" in staged_path.parts
+        assert staged_path == tmp_path / "config" / "submission_constants.py"
+
+    def test_drops_leading_anchor(self, tmp_path: Path) -> None:
+        absolute_target = tmp_path / "config" / "submission_constants.py"
+        staging_root = tmp_path / "staging_root"
+        staging_root.mkdir()
+        staged_path = _temporary_path_preserving_directory_signal(
+            staging_root, str(absolute_target)
+        )
+        relative_parts = staged_path.relative_to(staging_root).parts
+        assert relative_parts == ("config", "submission_constants.py")
+        assert absolute_target.anchor not in relative_parts
+        assert staged_path.resolve().is_relative_to(staging_root.resolve())
+
+    def test_path_without_exemption_directory_stages_flat_basename(
+        self, tmp_path: Path
+    ) -> None:
+        pytest_shaped_target = (
+            tmp_path / "test_edit_introducing_new_viol0" / "legacy_module.py"
+        )
+        pytest_shaped_target.parent.mkdir(parents=True, exist_ok=True)
+        pytest_shaped_target.write_text(CLEAN_MARKER_FUNCTION, encoding="utf-8")
+        staging_root = tmp_path / "staging_root"
+        staging_root.mkdir()
+        staged_path = _temporary_path_preserving_directory_signal(
+            staging_root, str(pytest_shaped_target)
+        )
+        assert staged_path == staging_root / "legacy_module.py"
+
+    def test_relative_config_path_preserves_config_under_system_temp_cwd(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        system_temp_root = Path(tempfile.gettempdir()).resolve()
+        monkeypatch.setenv("TEMP", str(system_temp_root))
+        monkeypatch.setenv("TMP", str(system_temp_root))
+        monkeypatch.setenv("TMPDIR", str(system_temp_root))
+        with tempfile.TemporaryDirectory(
+            dir=str(system_temp_root), prefix="staging_cwd_"
+        ) as temporary_root_string:
+            temporary_root = Path(temporary_root_string)
+            previous_cwd = Path.cwd()
+            try:
+                monkeypatch.chdir(temporary_root)
+                staging_root = temporary_root / "staging_root"
+                staging_root.mkdir()
+                staged_path = _temporary_path_preserving_directory_signal(
+                    staging_root, RELATIVE_CONFIG_TARGET_PATH
+                )
+                assert staged_path == staging_root / "config" / "x.py"
+                assert "config" in staged_path.parts
+                assert staged_path.name == "x.py"
+            finally:
+                monkeypatch.chdir(previous_cwd)
+
+    def test_escapes_temporary_root_rejects_absolute_and_parent_parts(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        sandbox_temp_root = tmp_path / "system_temp"
+        sandbox_temp_root.mkdir()
+        monkeypatch.setenv("TEMP", str(sandbox_temp_root))
+        monkeypatch.setenv("TMP", str(sandbox_temp_root))
+        monkeypatch.setenv("TMPDIR", str(sandbox_temp_root))
+        assert _escapes_temporary_root("..") is True
+        assert _escapes_temporary_root("scripts") is False
+        assert _escapes_temporary_root("config") is False
+        absolute_part = str(Path(tempfile.gettempdir()).resolve().anchor) or "/"
+        assert _escapes_temporary_root(absolute_part) is True
+
 
 class TestCliModeRegression:
     def test_cli_mode_reports_violations_and_exits_one(

package/package.json

@@ -1,10 +1,11 @@
 {
     "name": "claude-dev-env",
-    "version": "2.4.0",
+    "version": "2.7.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
-        "claude-dev-env": "bin/install.mjs"
+        "claude-dev-env": "bin/install.mjs",
+        "codex-compat": "bin/codex-compat.mjs"
     },
     "scripts": {
         "test": "node --test \"bin/*.test.mjs\" \"skills/**/*.test.mjs\""
@@ -19,9 +20,18 @@
         "hooks/",
         "system-prompts/",
         "scripts/",
+        "codex-capability-map.json",
         "_shared/",
         "audit-rubrics/",
-        "CLAUDE.md"
+        "CLAUDE.md",
+        "!**/__pycache__/**",
+        "!**/*.py[cod]",
+        "!**/.pytest_cache/**",
+        "!**/.mypy_cache/**",
+        "!**/.ruff_cache/**",
+        "!**/*.log",
+        "!**/debug-*.log",
+        "!**/*.egg-info/**"
     ],
     "keywords": [
         "claude-code",

package/rules/CLAUDE.md

@@ -11,35 +11,33 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. A rule withou
 
 | File | Rule |
 |---|---|
-| `agent-spawn-protocol.md` | Protocol for spawning subagents: context sufficiency check, prompt generation via `/prompt-generator`, then spawn |
+| `agent-spawn-protocol.md` | Check context sufficiency before a spawn and ask subagents for file-and-line answers; `/prompt-generator` is recommended for a complex or user-facing spawn |
 | `anti-corollary-tests.md` | Tests must carry information: no corollary matrices over canonical reductions, no suite that only matches a dead-implementation default, stated mutation in the audit lane |
 | `ask-user-question-required.md` | Every user-directed question goes through the `AskUserQuestion` tool — no plain-text questions |
 | `bdd.md` | BDD discovery-driven development workflow and Example Mapping reference |
-| `claude-md-orphan-file.md` | Every backticked bare filename in a per-directory `CLAUDE.md` table's first column names a file in that directory's subtree |
-| `cleanup-command-forms.md` | Never use bash `rm` to clean up; use the PowerShell `Remove-Item` and `git worktree remove --force` forms the `destructive_command_blocker` hook never prompts on, and carry the rule into every subagent prompt |
 | `cleanup-temp-files.md` | Remove temporary files created during a task when the task is complete |
-| `code-reviews.md` | Mandatory protocol for responding to GitHub PR review feedback |
-| `code-standards.md` | Pointer to `CODE_RULES.md` as the single source of truth |
+| `code-standards.md` | Pointer to `CODE_RULES.md` as the single source of truth, including §8 (TDD) and §7 (right-sizing); BDD is the outer process and TDD the inner loop |
 | `confirm-implementation-forks.md` | Stop and ask when two or more workable implementation paths change the deliverable |
 | `conservative-action.md` | Research and recommend when intent is ambiguous; act only on explicit request |
 | `context7.md` | Use Context7 MCP to fetch current library docs; always prefer live docs over built-in knowledge |
+| `destructive-commands.md` | Allowed removal forms and the ephemeral namespace the `destructive_command_blocker` auto-allows; keep destructive literals out of a Bash command string even as data |
+| `doc-inventory-integrity.md` | Three inventory shapes stay in step with the code: a per-directory `CLAUDE.md` file list, a package `README`/`SKILL.md` inventory, and an env-var summary table |
+| `doc-prose-cuts.md` | Four sentence shapes to cut from prose: exclusion claims, justification sentences, conversation references, and time references |
 | `docstring-prose-matches-implementation.md` | Prose enumerations in docstrings cover every behavior the body applies |
 | `durable-post-artifacts.md` | GitHub post bodies never reference volatile scratch paths; text embeds inline and binary artifacts upload to the `artifacts` release with the permanent URL linked |
+| `eli11-replies.md` | Every chat reply the user reads follows one shape: action first, detail last, few words; `plain-language.md` governs word choice, this rule governs reply length and shape |
 | `explore-thoroughly.md` | Read relevant files and map existing patterns before proposing a change |
+| `falsify-before-green.md` | A check's green counts as evidence only after that same check ran red on a named break, with a passing control beside it |
 | `file-global-constants.md` | File-global constants need at least two same-file references; otherwise move value to `config/` |
-| `gh-body-file.md` | Use `--body-file` with a temp file for all `gh` commands carrying markdown body content |
-| `gh-paginate.md` | Use `--paginate --slurp` piped to external `jq` for paginated GitHub API list endpoints |
-| `git-workflow.md` | PR workflow: always create as draft, one commit per review stage, never commit working docs or images |
-| `hook-prose-matches-detector.md` | Hook prose descriptions match what the hook actually detects |
+| `filesystem-search.md` | Every filesystem search names a scope; `es.exe`, `Glob`, `Grep`, and `Read` are equally sanctioned, and the `unscoped_search_blocker` denies a walk from a root |
+| `gh-cli-conventions.md` | `--body-file` for every `gh` body; `--paginate --slurp` piped to external `jq` for every paginated list read |
+| `git-workflow.md` | PR workflow: always create as draft, one commit per review stage, never commit working docs or images; carries the review-response protocol and a See-also block for its seven siblings |
+| `hedging-claims.md` | State the evidence or name the claim unverified; the `hedging_language_blocker` Stop hook sends a hedged response back for a re-check |
 | `long-horizon-autonomy.md` | Autonomous-run behaviors: act on what you have, do not end on a promise, delegate and keep working |
-| `nas-ssh-invocation.md` | Reach the NAS through the `System32/OpenSSH` binary with `-o BatchMode=yes`; bare `ssh`/`scp`/`sftp` stalls on an interactive password prompt |
-| `no-cross-skill-duplicate-helpers.md` | No duplicating shared helpers across skills; use `_shared/` |
-| `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 |
-| `no-justification-noise.md` | Markdown states facts a reader can act on; cut a present-tense sentence that only justifies a stated choice or restates a gain the reader already works out from the behavior or from a rule enforced elsewhere |
-| `env-var-table-code-drift.md` | Every env-var summary table row in a `.md` file names a code file whose source references the variable |
+| `measurement-denominators.md` | Every reported count names what it scanned and carries its denominator; a rate needs two runs; the consumer cross-checks the count against the scope its denominator names |
+| `nas-ssh-invocation.md` | Reach the NAS through the paramiko-backed `nas_ssh_key.py` runner, which signs in-process; every ssh-family client reads the key through file permissions, refuses it, and stalls an unattended run on a password prompt |
+| `no-cross-skill-duplicate-helpers.md` | Within one skill a duplicated helper is blocked; across two skill folders a small self-contained copy is a sanctioned isolation tradeoff that draws a non-blocking advisory naming the source skill |
 | `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 |
 | `paired-test-coverage.md` | A public function omitted by a module's established paired test suite must get a behavioral test |
 | `parallel-tools.md` | Make all independent tool calls in a single response |
 | `plain-illustrative-docstrings.md` | Public docstring narrative reads plainly and shows behavior with a diagram block (a `::` example or a doctest), painting a concrete scene a general developer follows on first read; a run-on backstop hook, a prose-wall backstop hook, and Category O9 audit enforce it |
@@ -48,13 +46,10 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. A rule withou
 | `proof-of-work-pr-comments.md` | Every PR carries one five-part proof-of-work comment before it leaves draft; the `pr_description_enforcer` hook audits proof-shaped comments and gates `gh pr ready` |
 | `re-stage-before-commit.md` | Stage the files edited this session before `git commit`; the session edit stage gate denies a commit that leaves a tracked session edit unstaged, with `-a`, a pathspec, a preceding `git add`, and `# partial-commit` as escapes |
 | `research-mode.md` | Three anti-hallucination constraints: say "I don't know", verify with citations, quote for factual grounding |
-| `right-sized-engineering.md` | Simple over clever; functions over classes; concrete over abstract |
-| `self-contained-docs.md` | Every document is fully self-contained; no references to the conversation that produced it |
-| `shell-invocation-policy.md` | All Windows shell commands use `pwsh`; `Audit-ShellPolicy.ps1` reports the non-`pwsh` forms in the `settings.json` permission rules and `Migrate-ShellPolicy.ps1` rewrites them to `pwsh`, both run on demand, not as a live gate |
-| `tdd.md` | Test-driven development: red → green → refactor, no production code before a failing test |
+| `shell-invocation.md` | Windows shell commands run through `pwsh`; no `$(...)`, backtick, or process substitution in a Bash tool command |
 | `testing.md` | Test quality and infrastructure standards |
 | `vault-context.md` | Search Obsidian vault for prior sessions and decisions before substantive project work |
-| `verified-commit-gate-skip.md` | The `# verify-skip` marker on a blocked commit/push is allowed only when the branch surface is the same code a code-verifier already passed clean; any real change since that verdict runs a fresh verification |
+| `verified-commit-gate-skip.md` | Code-verifier review is optional; commits and pushes use the checks selected for the task |
 | `verify-before-asking.md` | Answer questions by inspecting files or running tools before asking; recalled facts expire until re-checked this session |
 | `verify-runtime-state.md` | A "component is fine / not at fault" verdict rests on a live probe this session, never code reading or prior-session memory |
 | `windows-filesystem-safe.md` | Use safe `rmtree` patterns on Windows; `mkdirSync` with `recursive: true` on possibly-existing paths |
@@ -63,4 +58,4 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. A rule withou
 
 ## Hook enforcement
 
-Rules marked with ⚡ in `packages/claude-dev-env/docs/CODE_RULES.md` are backed by a blocking hook in `hooks/blocking/`. Rules without a hook are judgment-based and enforced via audit rubrics (`audit-rubrics/`).
+Rules marked with ⚡ in `~/.claude/docs/CODE_RULES.md` are backed by a blocking hook in `hooks/blocking/`. Rules without a hook are judgment-based and enforced via audit rubrics (`audit-rubrics/`).

package/rules/agent-spawn-protocol.md

@@ -1,9 +1,9 @@
-# Agent Spawn Protocol (Mandatory)
+# Agent Spawn Guidance
 
-Before any Agent or Task tool spawn (Explore, implementation, research, or team subagents):
+Before any Agent or Task tool spawn, check context sufficiency: you can name the files involved, the constraints, and what success looks like, and the task is unambiguous. When you cannot, investigate or ask the user first — a spawn with incomplete context returns work you throw away.
 
-1. **Check context sufficiency** — you can name the files involved, the constraints, and what success looks like, and the task is unambiguous. When you cannot, investigate or ask the user first; do not spawn with incomplete context.
-2. **Craft the prompt with `/prompt-generator`** — feed it the goal, the target files from step 1, the constraints, the output format, and the acceptance criteria; use its output as the agent's `prompt`.
-3. **Spawn** with that structured prompt.
+Ask each research subagent for precise file-and-line answers. A finding that names a path and a line number is one a reader can check.
 
-Full step detail, rationale, and relationship to other rules: `@~/.claude/docs/agent-spawn-protocol.md`.
+`/prompt-generator` is recommended for a complex spawn, or one whose output the user reads directly: feed it the goal, the target files, the constraints, the output format, and the acceptance criteria, then use its output as the agent's `prompt`. Inside a scoped autonomous run, an inline structured prompt you write yourself is fine.
+
+Full step detail and the relationship to other rules: `@~/.claude/docs/agent-spawn-protocol.md`.

package/rules/anti-corollary-tests.md

@@ -59,7 +59,7 @@ A structural hook is the wrong tool here. "Is this a corollary?" and "would this
 
 | Rule | Role |
 |---|---|
-| `tdd.md` | Write a failing test before production code |
+| `code-standards.md` | Points at CODE_RULES §8: write a failing test before production code |
 | `testing.md` | Mocks and test infrastructure standards |
 | `paired-test-coverage.md` | Every public function in an established suite gets a behavioral test |
 | `anti-corollary-tests.md` | Each test carries information; no corollary matrices; no suite that only matches the dead default |

package/rules/bdd.md

@@ -13,7 +13,7 @@
 1. **Deliberate Discovery** — Reduce uncertainty before code; surface what you do not know (Smart & Molak §5.4).
 2. **Illustrate** — Explore goals, constraints, and concrete examples in chat; "given … when … then …" style outcomes.
 3. **Formulate** — Express behavior as narrow **"should …"** specifications the user can approve.
-4. **Automate** — Failing specification first, then minimum code to pass; refactor only for a concrete smell.
+4. **Automate** — Build each formulated behavior through the TDD inner loop: CODE_RULES §8, red-green-refactor, canonical as stated in [`code-standards.md`](code-standards.md).
 
 Conversation is the essential practice: if discovery is skipped, structured formats do not rescue the workflow (Minimal BDD).
 

package/rules/cleanup-temp-files.md

@@ -15,13 +15,19 @@ Source: [Anthropic — Reduce file creation in agentic coding](https://platform.
 - Leave the working directory cleaner than you found it.
 - If a file was created at the user's explicit request (not as a byproduct of your process), leave it in place.
 
+## Exceptions to the removal duty
+
+Three kinds of file are already ephemeral and need no explicit removal:
+
+- A file under the OS temporary root.
+- A file under `$CLAUDE_JOB_DIR`, which the harness clears with the job.
+- A child agent's scratch file, which the parent removes at teardown.
+
+Use an allowed removal form for everything else: [`destructive-commands.md`](destructive-commands.md) names them.
+
 ## What counts as temporary
 
 - Scripts written to test a hypothesis or run a one-off check
 - Debug output files, log dumps, or intermediate data exports
 - Helper files created to work around tool limitations
 - Any file the user did not ask for and would not expect to find after the task
-
-## Why
-
-Temporary files accumulate across sessions and clutter the project root. Latest models sometimes use files as scratchpads during iteration, and these leftovers confuse both the user and future sessions if not cleaned up.

package/rules/code-standards.md

@@ -4,3 +4,10 @@
 > This is the single source of truth for code standards. Non-negotiable.
 
 `CODE_RULES.md` (`~/.claude/docs/CODE_RULES.md`) is the compact reference for every standard: self-documenting names, centralized configuration, constant reuse, no magic literals, full words, complete type hints, required-vs-optional parameters, construction logic in the model, temporary-code `TODO:` markers, behavior-first component names, and TDD.
+
+Two standards live there in full and nowhere else:
+
+- **TDD** — CODE_RULES §8 is canonical: red, green, refactor, with no production code before a failing test.
+- **Right-sized engineering** — CODE_RULES §7 is canonical: functions over classes, concrete over abstract, an abstraction added at the commit that introduces its second concrete implementation.
+
+BDD is the outer process and TDD is the inner loop: [`bdd.md`](bdd.md) discovers and formulates the behavior a feature needs, then each formulated behavior is built through the CODE_RULES §8 red-green-refactor cycle.

package/rules/conservative-action.md

@@ -14,8 +14,4 @@ Proceed with edits, file modifications, or implementations only when the user ex
 - If the user describes a problem, investigate and recommend. Do not jump to implementation.
 - If the user says "do it", "go ahead", "make the change", or similarly explicit language, proceed with action.
 - Once the user has explicitly asked and you have what you need, act — do not re-open settled facts or decisions, and do not re-survey options you will not pursue. This rule governs the ambiguous case; the clear case belongs to `long-horizon-autonomy`.
-- When in doubt, ask: "Would you like me to make this change, or just show you the approach?"
-
-## Why
-
-Acting prematurely wastes effort and round-trips when the user wanted a different approach. Exploring first produces better outcomes than committing early. This is especially important with models that have a strong action bias.
+- When in doubt, put the decision to the user through `AskUserQuestion` with two options: show the approach first, or make the change now.

package/rules/context7.md

@@ -1,7 +1,3 @@
----
-alwaysApply: true
----
-
 When working with libraries, frameworks, or APIs — use Context7 MCP to fetch current documentation instead of relying on training data. This includes setup questions, code generation, API references, and anything involving specific packages.
 
 ## Steps

package/rules/destructive-commands.md

@@ -0,0 +1,47 @@
+# 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.
+
+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
+
+- **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.
+
+## The ephemeral namespace the hook auto-allows
+
+An `rm` is auto-allowed when it is a single invocation and every target resolves inside one of:
+
+- The OS temporary root (`tempfile.gettempdir()`).
+- 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.
+
+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.
+
+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.
+
+- 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.
+
+## 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:
+
+> 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.
+
+Prefer that a child leaves its scratch files for the parent to remove at teardown.
+
+## 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.

package/rules/doc-inventory-integrity.md

@@ -0,0 +1,48 @@
+---
+paths:
+  - "**/*.md"
+  - "**/*.py"
+  - "**/*.mjs"
+  - "**/*.js"
+  - "**/*.ts"
+  - "**/*.ps1"
+  - "**/*.sh"
+---
+
+# 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.
+
+## 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.
+
+It collects two kinds of reference:
+
+- **Table cells** — the first column of each markdown table row **outside** a fenced code block, keeping cells that name a bare filename in backticks, with no path separator, not a slash-command, ending in a known 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 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 and contributes nothing; a fenced *run command* is a contract the reader runs and is checked. The write is blocked when a collected filename exists nowhere under the scan root — the `CLAUDE.md` directory's parent, covering the directory, its subdirectories, and its siblings. A filesystem error that halts the subtree walk fails open.
+
+The check stays quiet for a target that is not a `CLAUDE.md`, for a cell holding a path, a subdirectory ending in `/`, or a slash-command, for a table row inside a fence, for an inline `python x.py` mention outside a fence, and for a table naming an explicit relative-path source (a `../` token), which documents files outside the subtree by design.
+
+## 2. A package inventory names each new production file
+
+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.
+
+Two free-prose slices stay with judgment and belong in the same change:
+
+1. **Purpose / scope sentence.** When the new module adds a responsibility the package `## Purpose` (or the parent inventory's one-line summary of the subdirectory) omits, broaden that sentence to name it. A hook cannot derive a module's responsibility from its filename.
+2. **Per-file description clause.** When a file gains a responsibility the inventory's em-dash description omits — a new public function, a new module-level constant — broaden the clause to name it. The gate checks only that the basename appears once and never reads the description. Constants modules (`*_constants.py`, or any `.py` directly inside `config/`) are the common shape: the clause that lands in the module docstring lands in the inventory description in the same change. The gate fires on Write of a new file and skips files directly inside `config/`, so an Edit adding a constant to an existing config module matches neither path.
+
+This is the `category-o-docstring-vs-impl-drift` (O8) orphaned-doc-claim shape applied to a package inventory.
+
+## 3. An env-var table row names a file that reads the variable
+
+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.

package/rules/doc-prose-cuts.md

@@ -0,0 +1,58 @@
+# Documentation Prose Cuts
+
+Prose a reader acts on states settled facts, decisions, and behavior directly. Four sentence shapes carry no fact the reader can act on. Cut each on sight, in `.md` files, in code comments, and in docstrings alike.
+
+A detail earns its place by mattering now, or by being timeless enough to matter for future work. Everything else is noise.
+
+## The four cut shapes
+
+### 1. Exclusion claims — state the claim itself
+
+Establishing a claim by naming what it is not, or by walking rejected candidates to reach the answer. Replace with the claim and the evidence behind it.
+
+> This is not Option A from the original framing.
+
+Cut it. Write what the approach is.
+
+### 2. Justification sentences — state the fact, drop the payoff
+
+A sentence whose only job is to say why a stated choice is good, or to restate a gain the reader already works out from the behavior around it or from a rule enforced elsewhere.
+
+> The lenses point at this file and read it when they run; they do not carry its text in their spawn prompts, so the checklist stays out of the per-round token budget.
+
+Keep the first clause. Cut the tail — the reader reaches it alone.
+
+For each sentence, ask: **does it state a fact the reader can act on that they could not already work out from the behavior around it?** If no, cut it.
+
+A rule's one-line reason stated in present behavior stays — `--jq` runs per page, so cross-page sorts give wrong results — because that reason names a fact the reader needs to pick the right call. A tradeoff or constraint the reader weighs before choosing a path stays too.
+
+### 3. Conversation references — write for a reader who saw nothing
+
+Every document stands alone. A reader with zero prior context understands every statement without the conversation that produced it.
+
+| Shape | Example | Fix |
+|---|---|---|
+| Options discussed in chat | "This is not Option A from the original framing" | State the decision on its own terms |
+| "As discussed" / "as we decided" | "As discussed, we'll use embeddings" | "Sref matching uses sentence-transformer embeddings" |
+| Pronouns pointing at chat | "This addresses the concerns raised earlier" | Name the concerns inline, or cut |
+| Relative framing on unseen alternatives | "Instead of the three options considered" | State the chosen approach directly |
+| Session sequencing | "After Round 3 we decided…" | State the decision as a fact |
+
+Obsidian session logs are the exception — they are conversation-scoped on purpose.
+
+### 4. Time references — describe current state only
+
+Never reference removed implementations, old defaults, prior behaviors, or earlier contracts. A module or function docstring carries the same current-state-only contract as a `.md` file.
+
+Comparisons to alternatives that still exist stay allowed ("use `--paginate --slurp | jq`, not `--jq` alone"), as do references to external defects that still exist (gh CLI #10459).
+
+After writing, ask: read a year from now by someone who knew no earlier state, does every sentence still make sense? If a sentence only helps someone who knew an earlier state, cut it.
+
+## Enforcement
+
+- **Write-time.** `state_description_blocker` (PreToolUse on Write|Edit) blocks historical and comparative phrases in `.md` prose, code comments, and Python docstrings. A phrase wrapped in double quotes or backticks inside a docstring counts as a mention and is skipped. The denial names the matched phrases and shows a rewrite.
+- **AI review.** The claude-dev-env repository's root `AGENTS.md`, the AI-review fan-out source, names the other three shapes as findings an agent applies to the `.md` lines a PR changes. No hook backs them: telling a justification sentence from a load-bearing one needs meaning a regex cannot read.
+
+## Sibling rule
+
+[`plain-language.md`](plain-language.md) governs word choice — heavy words swapped for everyday ones. This rule governs which sentences survive at all.