claude-dev-env 2.5.0 → 2.7.0

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,14 +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 |
-| `state-what-is.md` | Assert claims, decisions, and actions directly; replace exclusion (naming what a claim is not) and elimination (walking rejected candidates) with the claim or answer itself |
-| `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 |
@@ -64,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.

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

@@ -28,13 +28,21 @@ Read the body and the docstring side by side. Apply each check that matches the
 - **Gate-outcome status flags** — an outcome routed to a blocker (`blocker = ...; break`) reads as blocked everywhere, never as a bypass.
 - **Returns / Raises / Note claims** — each free-form claim matches the body.
 
-Many deterministic shapes of this drift have Write/Edit gates in `packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py` (and the JS/`.mjs` slices in `code_rules_imports_logging.py`). Free-form rest is judgment.
+Many deterministic shapes of this drift have Write/Edit gates in `~/.claude/hooks/blocking/code_rules_docstrings.py` (and the JS/`.mjs` slices in `code_rules_imports_logging.py`). Free-form rest is judgment.
+
+## Hook prose matches its detector
+
+A hook module is the sharpest case of the same rule: its docstring lead narrative and its `CORRECTIVE_MESSAGE` describe exactly the shapes the detector flags, and claim no broader trigger surface than the regex enforces.
+
+`hook_prose_detector_consistency` (PreToolUse on Write|Edit of hook modules and their `*_constants.py` companions) blocks prose that claims a trigger the detector never fires on, and names the fix.
+
+After writing a hook, ask: would a token matching every word of this message actually trip the detector? When the message names a shape the regex skips, rewrite the message to name only what the regex catches. The path-shape case is the common overstatement — a detector that keys off a path separator must not claim it blocks an "output-key segment". The corrective message spells the rewrite.
 
 ## Full standard
 
 The full Category O judgment standard — sub-buckets O1–O9, the complete write-time gate inventory, free-form checklists, and worked examples — lives in:
 
-`packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md`
+`~/.claude/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md`
 
 ## Division of labor
 

package/rules/durable-post-artifacts.md

@@ -36,7 +36,3 @@ With neither anchor the text names the directory rather than something inside it
 ## Enforcement
 
 The `volatile_path_in_post_blocker` PreToolUse hook reads the body of each `gh` post command and each GitHub MCP post call, scans it for these markers, and blocks the post when it finds one. For a `--body-file`, the hook reads the file and scans its contents, so writing the body to a temp file and passing it with `--body-file` stays allowed — what the hook rejects is a volatile path inside the text that gets posted.
-
-## Why
-
-A comment that cites an artifact under a job's tmp directory reads fine the moment it is posted and breaks a few minutes later, once the job is cleaned. Embedding text inline and linking binary artifacts to a durable release keeps every post readable for as long as it exists.

package/rules/eli11-replies.md

@@ -0,0 +1,31 @@
+# ELI11 Replies
+
+**Users read about 20% of your words, and 79% of them scan.** Write every reply so the bold words alone tell the whole story.
+
+## Four skim mechanics
+
+1. **Bold keyword first** — open every line and bullet with its load-bearing words in bold. Eyes land on the first words of a line, then fall down the left edge — the [F-pattern](https://www.nngroup.com/articles/f-shaped-pattern-reading-web-content-discovered/).
+2. **One idea per line** — a second idea in the same line is invisible to a skimmer.
+3. **Conclusion first** — the outcome goes in sentence one. Detail sits below it, or gets cut.
+4. **Half the words** — write it, halve it, halve it again. Cap a reply at about 120 words.
+
+**Measured gains** ([NN/g eyetracking](https://www.nngroup.com/articles/how-users-read-on-the-web/)): concise +58%, scannable layout +47%, both together +124%.
+
+## Reply shape
+
+1. **Action first** — when the user must act, open with "Do N things" and numbered click-by-click steps, one short line each.
+2. **Outcome first** — when nothing is needed, open with the outcome in one sentence.
+3. **Findings** — at most 3 short bullets.
+4. **Detail** — only when the user asks.
+
+## Rules
+
+- **One command per block** — a command the user runs goes in its own `bash`-tagged fenced block, so the Run button appears. That tag gives the user a Run button; [`shell-invocation-policy`](shell-invocation-policy.md) stays in charge of the agent's own Bash-tool calls, which run pwsh-only.
+- **One line per status** — each background-work update gets a single line.
+- **Cut findings first** — when a reply runs long, drop findings and keep the action steps.
+- **Skim test** — reading only the bold words tells the whole story.
+
+## Relationship to other rules
+
+- **[`plain-language`](plain-language.md)** owns word choice; this rule owns reply length and shape.
+- **`AskUserQuestion`** carries every question to the user, in the same short style.

package/rules/explore-thoroughly.md

@@ -17,11 +17,11 @@ Note: This deliberately chooses exploration depth over the "commit and execute q
 - New feature or cross-cutting change: read broadly across the codebase to understand how similar things are done.
 - Architectural decision: explore the full landscape before recommending a direction.
 
+## Inside an autonomous run
+
+The depth budget shrinks once the evidence is in hand. When you can already name the files, the constraints, and what success looks like, further reading buys nothing — act. Re-reading a file to re-derive a fact the run already settled is the shape to cut. See [`long-horizon-autonomy.md`](long-horizon-autonomy.md).
+
 ## Relationship to other rules
 
 - **conservative-action.md** gates *whether* to act. This rule governs *how deeply* to investigate.
 - **research-mode.md** ensures factual claims are grounded. This rule ensures implementation plans are grounded in the actual codebase.
-
-## Why
-
-Premature commitment leads to wasted effort when the chosen approach conflicts with existing patterns or misses important context. Thorough exploration surfaces constraints early and produces better-informed solutions.

package/rules/falsify-before-green.md

@@ -0,0 +1,68 @@
+---
+paths:
+  - "**/test_*.py"
+  - "**/*_test.py"
+  - "**/*.test.*"
+  - "**/*.spec.*"
+  - "**/conftest.py"
+  - "**/tests/**"
+  - "**/scripts/**"
+---
+
+# Falsify Before Green
+
+**When this applies:** Any new test, probe, concurrency harness, sweep, mutation check, or measurement script, before its green counts as evidence.
+
+## Rule
+
+A check's green counts as evidence only after that same check ran red on a deliberate break, with a paired control that passes beside it. The break is named: a mutation applied to the code, a stubbed-out target, or a trip input built to fire the check.
+
+A green with no shown red is an unmeasured result, not a pass. Apply the break, watch the check fail, then trust the green. A check that stays green under its own break reads nothing about the code, and its number carries no weight.
+
+## The four shapes this stops
+
+### 1. A probe whose trigger condition never fires
+
+The probe reports zero because it measured zero events, not because the code is clean. Its counter sits at its start value for the whole run.
+
+**Break to apply:** feed it one input that must trip it. A probe still at zero on that input measures nothing.
+
+### 2. A sweep that reads a subset of the files it claims to cover
+
+The sweep compares against the wrong base, walks a slice of the tree, and reports its finding count over the full set.
+
+**Break to apply:** plant one violation in a file the sweep's coverage claim names. A sweep that misses the plant walks a smaller file set than the one it reports.
+
+### 3. A mutation that survives
+
+The test meant to kill the mutation never reaches the mutated code — a mock stands in for the call, a guard returns early, or the test drives a neighboring branch.
+
+**Break to apply:** hold the mutation in place and run the test. A green test names a line nothing covers.
+
+### 4. An assertion that counts an artifact the harness seeded
+
+The harness writes the row, file, or event the assertion counts, so the assertion tracks the harness rather than the code under test.
+
+**Break to apply:** stub the production writer to a no-op. A green assertion counts the seed.
+
+## What a shown-red record holds
+
+| Part | What it names |
+|---|---|
+| The break | The mutation, stub, or trip input applied, named by file and line or by the exact input text |
+| The red | The failing output the check printed under that break |
+| The control | The case that passes beside the red, run on the same command |
+
+All three land together. A record carrying the red alone shows a check that fails on everything; a record carrying the control alone shows a check that passes on everything.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| `anti-corollary-tests.md` | Each test carries information; the stated mutation names one code change and how many tests it kills |
+| `verify-runtime-state.md` | A runtime verdict rests on a live probe from this session |
+| `measurement-denominators.md` | Every count names what it scanned; a rate needs two runs |
+
+## Enforcement
+
+This rule binds as prose discipline: a reviewer reads the shown-red record beside each new check a PR adds. No hook backs it, because a green that measured the code and a green that measured nothing look the same to a regex — the difference sits in what the check reached at run time.

package/rules/file-global-constants.md

@@ -4,7 +4,7 @@ paths: **/*.py
 
 # File-Global Constants
 
-This rule extends the `constants-location` rule defined in `~/.claude/docs/CODE_RULES.md` — see the ⚡ HOOK-ENFORCED RULES table, Constants location row.
+This rule extends the `constants-location` rule defined in `~/.claude/docs/CODE_RULES.md` — see the ⚡ HOOK-ENFORCED RULES section, the "UPPER_SNAKE constants only in `config/`" clause.
 
 **file_global_constants_use_count:** A file-global constant is a module-level named constant declared at the top of a file (for example, an `UPPER_SNAKE_CASE` value assigned at module scope). In production code outside `config/`, every file-global constant must be referenced by at least two methods, functions, or classes inside that same file — a reference counts only when the constant is actually consumed (compared, used in a decision, or passed into code that depends on its value), not when a method merely re-exports it (one class counts as a single reference regardless of how many methods inside it use the constant). Module-level usages outside any function, method, or class body also count as a reference. A default parameter value counts as one reference from the enclosing function. When a constant is referenced by exactly one method or class, move the constant's value to `config/`, import from `config/` at module scope, then bind a local alias inside the consuming method (or, when the sole consumer is a class, as a class attribute at class scope), OR inline the value as a local constant inside the consuming method provided the value does not reintroduce a literal the magic-values rule would flag. When the sole reference is a module-level expression (for example, `ALL_ITEMS = build_registry(BATCH_SIZE)` at module scope), move the value to `config/` and reference the imported name directly at module scope; no local alias is needed.
 

package/rules/filesystem-search.md

@@ -0,0 +1,51 @@
+# Filesystem Search
+
+**When this applies:** Any search for files by name, path, extension, size, or date — through `es.exe`, a shell `find`, a recursive `Get-ChildItem` / `gci` / `dir` / `ls -R`, or the harness Grep and Glob tools.
+
+## The scope invariant
+
+Every filesystem search names a scope. A scope is a project, worktree, or package directory under the work in progress, or a filter that narrows the walk: an `ext:` filter, a `dm:` date filter, a `size:` filter, or a name pattern.
+
+A search that starts at the filesystem root, a drive root, bare home, or a network share is out of bounds. Narrow it to what you need.
+
+## Choosing a tool
+
+Three tools are equally sanctioned; pick by what you know:
+
+| You know | Use |
+|---|---|
+| The exact path | `Read` — no search at all |
+| A name, extension, or date, on Windows | `es.exe` with a path scope |
+| A name or path pattern | The harness `Glob` tool |
+| Text inside files | The harness `Grep` tool |
+
+When `es.exe` fails or returns nothing, fall back to `Glob` or `Grep` without pausing, and report the outage so the reader knows the index was unavailable. Ask the user only after all three tools fail.
+
+`skills/everything-search/SKILL.md` holds the full `es.exe` operator reference: `ext:`, `dm:`, `size:`, wildcards, OR/AND/NOT, output flags, and the junction and drive-mapping note.
+
+## Allowed and denied shapes
+
+| Allowed | Example |
+|---|---|
+| Cwd-relative | `find . -iname '*.py'` |
+| Project path | `find packages/claude-dev-env -name code_rules_gate.py` |
+| Git Bash scoped path | `find /c/Users/<you>/repo -iname SKILL.md` |
+| Recursive listing under a project | `Get-ChildItem -Path .\src -Recurse` |
+| Scoped Windows index search | `es.exe path:C:\dev\repo ext:py gate` |
+
+| Denied | Example |
+|---|---|
+| Filesystem root | `find / -iname code_rules_gate.py` |
+| Git Bash drive root | `find /c -name '*.py'` |
+| Windows drive root | `find C:\ -name foo` / `Get-ChildItem C:\ -Recurse` |
+| Bare home | `find ~ -name README.md` / `find $HOME -type f` |
+| Network share root | `find //server/share -name x` — a path under the share (`//server/share/project/src`) is allowed |
+
+## Shell batching
+
+Issue one shell search at a time when the walk is large. Parallel full-tree searches contend for the shell and can lock the host. Harness `Grep` and `Glob` calls carry no such cost and run in parallel freely — see [`parallel-tools.md`](parallel-tools.md).
+
+## Enforcement
+
+- `unscoped_search_blocker` (PreToolUse on Bash and PowerShell, hosted by `bash_pre_tool_use_dispatcher`) denies a walk from an unscoped root and returns the scoped alternative.
+- `es_exe_path_rewriter` (PreToolUse on Bash) substitutes `{project-name}` placeholders and bare registry keys in an `es.exe` command with their quoted absolute paths, read from `~/.claude/project-paths.json`. It allows and rewrites; it never blocks, and a machine with no registry file passes the command through unchanged. `scripts/setup_project_paths.py` writes the registry.

package/rules/gh-cli-conventions.md

@@ -0,0 +1,27 @@
+# gh CLI Conventions
+
+Two call shapes the `gh` CLI gets wrong by default.
+
+## Body content goes in a file
+
+Every `gh` command carrying markdown body content (`gh pr create/edit/comment/review`, `gh issue create/edit/comment`) uses `--body-file <path>` with a temp file — never a `--body` / `-b` string, where backticks land on GitHub as a literal `` \` ``. Write the temp file BOM-free:
+
+```powershell
+[IO.File]::WriteAllText($bodyPath, $body, [Text.UTF8Encoding]::new($false))
+```
+
+MCP GitHub tools take `body` as a structured parameter and are unaffected.
+
+`gh_body_arg_blocker.py` (PreToolUse on Bash, hosted by `bash_pre_tool_use_dispatcher`) blocks `--body <arg>` and returns the corrective message.
+
+## Paginated reads slurp before they filter
+
+Every `gh api` read of a paginated GitHub list endpoint (PR `reviews` / `comments` / `files`, issue `comments`, `pulls`, `issues`) uses `--paginate --slurp` piped to **external** `jq`. The built-in `--jq` runs per page, so a cross-page operation like `sort_by | last` gives a wrong-but-confident result.
+
+Single-object endpoints (`pulls/<n>`, `issues/<n>`) skip pagination and may use `--jq` directly. For a newest-first walk, sort the slurped array and take the last element; for single-page bounds, cap with a `per_page` query parameter.
+
+## Sibling rules
+
+- [`destructive-commands.md`](destructive-commands.md) — why a body describing `rm -rf` must travel by file path.
+- [`durable-post-artifacts.md`](durable-post-artifacts.md) — what a post body may reference.
+- [`proof-of-work-pr-comments.md`](proof-of-work-pr-comments.md) — what the proof comment must contain.