claude-dev-env 2.4.0 → 2.7.0

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

@@ -1,44 +1,53 @@
----
-paths:
-  - "**/*.py"
-  - "**/*.md"
----
-
-# Docstring Prose Matches Implementation
-
-**When this applies:** Any Write or Edit to a public function, method, class, or module whose docstring prose makes an enumerable claim about behavior — a list of inputs the code handles, the conditions it treats as a match, the cases it skips, or the order of its steps. It applies equally to a skill's companion `SKILL.md` (or any sibling `.md`) that describes a producer the skill's `scripts/` carry out: a doc sentence that claims a produced artifact's ordering or content is the prose this rule governs, and it tracks the producer function's own docstring and body.
-
-## Rule
-
-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.
-
-When the body changes the set of behaviors it applies, the same edit updates the prose enumeration. The two move together in one commit.
-
-## Write-time checks
-
-Read the body and the docstring side by side. Apply each check that matches the prose:
-
-- **Unions / match sources** — every member of a "what counts" union appears in the prose.
-- **Suppressors / skip lists** — every early-return suppressor appears in the prose.
-- **Step order** — named order matches call order; branch-guarded corrective steps are named too.
-- **Shared fallbacks** — every condition that reaches a fallback call is named.
-- **Predicate breadth** — the body accepts only the inputs the prose names.
-- **Exclusion axis** — an exclusion clause keys on the same axis the body classifies on.
-- **Companion docs** — a `SKILL.md` (or sibling) order/content claim matches the producer body.
-- **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.
-
-## 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`
-
-## Division of labor
-
-| Surface | Role |
-|---|---|
-| **This rule** | Always-on write-time policy and the compact checklist above. |
-| Category O rubric | Single thick source for the full standard (on demand). |
-| Category O prompt | Audit template; points at the rubric for judgment. |
+---
+paths:
+  - "**/*.py"
+  - "**/*.md"
+---
+
+# Docstring Prose Matches Implementation
+
+**When this applies:** Any Write or Edit to a public function, method, class, or module whose docstring prose makes an enumerable claim about behavior — a list of inputs the code handles, the conditions it treats as a match, the cases it skips, or the order of its steps. It applies equally to a skill's companion `SKILL.md` (or any sibling `.md`) that describes a producer the skill's `scripts/` carry out: a doc sentence that claims a produced artifact's ordering or content is the prose this rule governs, and it tracks the producer function's own docstring and body.
+
+## Rule
+
+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.
+
+When the body changes the set of behaviors it applies, the same edit updates the prose enumeration. The two move together in one commit.
+
+## Write-time checks
+
+Read the body and the docstring side by side. Apply each check that matches the prose:
+
+- **Unions / match sources** — every member of a "what counts" union appears in the prose.
+- **Suppressors / skip lists** — every early-return suppressor appears in the prose.
+- **Step order** — named order matches call order; branch-guarded corrective steps are named too.
+- **Shared fallbacks** — every condition that reaches a fallback call is named.
+- **Predicate breadth** — the body accepts only the inputs the prose names.
+- **Exclusion axis** — an exclusion clause keys on the same axis the body classifies on.
+- **Companion docs** — a `SKILL.md` (or sibling) order/content claim matches the producer body.
+- **Gate-outcome status flags** — an outcome routed to a blocker (`blocker = ...; break`) reads as blocked everywhere, never as a bypass.
+- **Returns / Raises / Note claims** — each free-form claim matches the body.
+
+Many deterministic shapes of this drift have Write/Edit gates in `~/.claude/hooks/blocking/code_rules_docstrings.py` (and the JS/`.mjs` slices in `code_rules_imports_logging.py`). Free-form rest is judgment.
+
+## 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:
+
+`~/.claude/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md`
+
+## Division of labor
+
+| Surface | Role |
+|---|---|
+| **This rule** | Always-on write-time policy and the compact checklist above. |
+| Category O rubric | Single thick source for the full standard (on demand). |
+| Category O prompt | Audit template; points at the rubric for judgment. |

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.

package/rules/git-workflow.md

@@ -40,3 +40,29 @@ User-level rule: applies to **every** git repo that uses GitHub with `gh` (no ex
 | `*.plan.md` | Temporary planning files |
 | `SESSION_STATE.md` | Local session state |
 | `*.png *.jpg *.jpeg *.gif *.webp *.avif *.svg *.ico` | Images go to external storage, not GitHub |
+
+An image a PR needs as visual evidence is not an exception to that row. Upload it to the repository's durable `artifacts` release with `python3 ~/.claude/scripts/gh_artifact_upload.py <file> <owner/repo>` and embed the permanent URL in the proof comment. The image lives on GitHub without entering the repository tree.
+
+## Responding to review feedback
+
+**When this applies:** GitHub PR review feedback on a branch you are fixing.
+
+1. Fetch every reviewer comment before making any fix.
+2. Create a TodoWrite checklist with one item per comment.
+3. Fix systematically, marking each todo complete.
+4. Reply to each comment inline.
+5. Create one review-fix commit. Do not squash it with the original.
+
+Repair only reported findings, then re-verify after every repair.
+
+## See also
+
+| Rule | Covers |
+|---|---|
+| [`gh-cli-conventions.md`](gh-cli-conventions.md) | `--body-file` for post bodies; `--paginate --slurp` for list reads |
+| [`proof-of-work-pr-comments.md`](proof-of-work-pr-comments.md) | The five-part proof comment every PR carries before leaving draft |
+| [`re-stage-before-commit.md`](re-stage-before-commit.md) | Staging session edits so a commit does not drop them |
+| [`verified-commit-gate-skip.md`](verified-commit-gate-skip.md) | Optional code-verifier review guidance |
+| [`durable-post-artifacts.md`](durable-post-artifacts.md) | Keeping volatile scratch paths out of a post body |
+| [`destructive-commands.md`](destructive-commands.md) | Allowed removal forms; destructive literals in commit and post bodies |
+| [`code-standards.md`](code-standards.md) | The code standards a PR's diff is reviewed against |

package/rules/hedging-claims.md

@@ -0,0 +1,9 @@
+# Hedging Claims
+
+State a claim with the evidence that backs it, or name the claim unverified. A hedge word stands in for evidence you did not gather.
+
+`hedging_language_blocker` (Stop hook, hosted by `stop_dispatcher`) blocks a response carrying one — `likely`, `probably`, `presumably`, `perhaps`, `possibly`, `seemingly`, `apparently`, `arguably`, `supposedly`, `ostensibly`, `conceivably`, `plausibly`, `unlikely`, `probable`, and the phrases `might be`, `could be`, `seems to be`, `appears to be`, `in all likelihood`, `more likely than not`, `it's possible that`.
+
+Deleting the hedge word and keeping the claim does not clear the block. Gather the source, run the probe, or ask the user through `AskUserQuestion` — then re-output the whole revised response.
+
+Sibling rules: [`research-mode.md`](research-mode.md) names what counts as a citation; [`verify-runtime-state.md`](verify-runtime-state.md) names the live probe a runtime verdict rests on.

package/rules/long-horizon-autonomy.md

@@ -37,7 +37,3 @@ Terse shorthand between tool calls is fine — that is you thinking. The final m
 ## Keep going on context
 
 A remaining-context or token count is not a reason to stop. Do not pause, summarize, or float a fresh session on account of context limits; keep working. When the user must see content word-for-word (a partial deliverable, a direct answer to a mid-run question), surface it through the channel the harness gives for that, not by ending the turn.
-
-## Why
-
-A capable model under-delivers on long runs for predictable reasons: it overplans when it could act, stops on a promise, blocks on subagents, skips its own verification, fabricates progress, buries the result in working shorthand, or quits early over a context count. Each section above removes one of those failure modes so the run finishes.

package/rules/measurement-denominators.md

@@ -0,0 +1,48 @@
+---
+paths:
+  - "**/*.md"
+  - "**/*.py"
+---
+
+# Measurement Denominators
+
+**When this applies:** Any Write or Edit that states a count, rate, or coverage figure in a docstring or a `.md` file.
+
+## Rule
+
+Every count names what it scanned. "Read 10 of 10 changed files" states the scan and the whole set it was drawn from. "Swept the files" states neither, and a reader takes it as full coverage of a scan that touched a fraction.
+
+Three parts travel with each figure. The report author writes part 1 for every figure and part 2 when the figure is a rate; the consumer runs part 3:
+
+1. **A count carries its denominator.** Name both numbers: files read of files changed, rounds fired of rounds available, tests reached of tests collected, entries compared of entries present.
+2. **A rate needs two runs and a stated denominator.** One run yields a count. Written down as a rate — "fires 40% of the time" — it claims a spread across runs that one run cannot back. Report the count and the run that produced it until a second run exists; once it does, the rate stays counts across runs — "failed twice across 5 runs on this branch" — never a percentage.
+3. **The consumer cross-checks the count against the scope its denominator names.** A sweep reporting 3 files read of 10 changed fails coverage: its verdict reaches 3 of the 10 files its own denominator names. A sweep reporting 3 of 3 security-sensitive files states its own scope and covers all of it, so it passes. That comparison settles the sweep before anyone reads its result.
+
+A number written into a docstring or a doc carries its denominator beside it. A number written there as a rate carries its run count too.
+
+## Shapes
+
+| Bare figure | With its denominator |
+|---|---|
+| swept the files | read 10 of 10 changed files |
+| all tests pass | 412 of 412 collected tests pass, 0 skipped |
+| the hook catches this | the hook denies 6 of 6 recorded shapes |
+| fails about 40% of the time | failed twice across 5 runs on this branch |
+| most entries match | 88 of 90 entries match |
+
+## Cross-check at the consumer
+
+A sweep reports "read 3 files". The change under review touches 10 files. The arithmetic reads: the sweep covered 3 of 10, so its clean verdict covers 3 of 10. The gap is the finding — send the sweep back for the other 7, and hold the verdict until the two numbers meet.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| `falsify-before-green.md` | A check's green counts once the check was shown red |
+| `anti-corollary-tests.md` | Each test carries information; no corollary matrices; no suite that only matches the dead default |
+| `docstring-prose-matches-implementation.md` | A docstring enumeration covers every behavior the body applies |
+| `measurement-denominators.md` | Every count names what it scanned; a rate needs two runs |
+
+## Enforcement
+
+This rule binds as prose discipline: a reviewer applies it to the counts a PR's prose and docstrings state, and to the counts a report claims. No hook backs it, because weighing a figure's denominator against the scope it covers needs meaning a regex cannot read.

package/rules/nas-ssh-invocation.md

@@ -1,11 +1,29 @@
-# NAS SSH Invocation Policy
+# Running Commands on the NAS
 
-Reach the NAS through the Windows `System32/OpenSSH` binary with `-o BatchMode=yes` on every `ssh`, `scp`, or `sftp` command:
+Reach the NAS through the `nas_ssh_key.py` runner, never through `ssh`, `scp` or `sftp`:
 
 ```
-"/c/Windows/System32/OpenSSH/ssh.exe" -o BatchMode=yes -o ConnectTimeout=10 -p 22 operator@nas.example.local "<cmd>"
+python <runner-path> <command-script.sh> <private-key-path>
 ```
 
-Git Bash's MSYS `ssh` falls back to an interactive password prompt that hangs an unattended session; the `System32/OpenSSH` binary authenticates the key without a prompt, and `-o BatchMode=yes` turns an auth failure into a loud non-zero exit. `nas_ssh_binary_enforcer.py` (PreToolUse on Bash) enforces this: it denies a bare ssh-family word aimed at the NAS, and denies the full binary when `-o BatchMode=yes` is absent.
+The first argument is a **path to a file** holding a bash script, not a command string. Write that
+file with the Write tool. The whole script runs in one shell, so variables, `cd` and `source` carry
+from line to line.
 
-Host, user, and port config, the `scp`/`sftp` forms, and the full rationale: `@~/.claude/docs/nas-ssh-invocation.md`.
+The runner ships with the automation project it serves; read its path from that project's own
+reference. Use the ops key under `~/.claude/keys` — keys under `~/.ssh` either carry a passphrase,
+which cannot be answered unattended, or belong to other hosts.
+
+The runner loads the key with paramiko and signs in the same process. The command-line clients check
+the key file's permissions first and refuse it, and Git Bash's `ssh` then falls back to a password
+prompt that hangs an unattended run. `nas_ssh_binary_enforcer.py` (PreToolUse on Bash) denies a bare
+ssh-family word aimed at the NAS, and denies the full `System32/OpenSSH` binary when
+`-o BatchMode=yes` is missing.
+
+Host, ssh port and ssh user are constants inside the runner and are also under the `nas` key in
+`~/.claude/local-identity.json`. Keep all three out of anything committed or posted.
+
+To copy a file, write it inside the script with a quoted heredoc rather than reaching for `scp`.
+
+The `/tmp` size limit, how to tell a real break from a platform-only one, and a failure-to-cause
+table: `@~/.claude/docs/nas-ssh-invocation.md`.

package/rules/parallel-tools.md

@@ -18,6 +18,6 @@ When multiple tool calls have no dependencies between them, make all independent
 - Use real parameter values only. Do not guess or use placeholders to force parallelism.
 - If you are unsure whether calls are independent, run them sequentially.
 
-## Why
+## The one surface that serializes
 
-Explicit reinforcement of parallel calling boosts compliance to near 100%. Sequential calls for independent operations waste time and round-trips for the user.
+Harness tool calls — Read, Grep, Glob, and the rest — carry no shared cost and parallelize freely. A large shell filesystem walk does not: parallel full-tree searches contend for the shell and can lock the host, so issue those one at a time. See [`filesystem-search.md`](filesystem-search.md).

package/rules/plain-illustrative-docstrings.md

@@ -48,7 +48,7 @@ cannot tell which name states the truth. Rename the callee to a neutral form
 the two names agree on at every call site.
 ```
 
-The live version of this docstring sits on `check_polarity_name_contradiction` in `packages/claude-dev-env/hooks/blocking/code_rules_naming_collection.py`.
+The live version of this docstring sits on `check_polarity_name_contradiction` in `~/.claude/hooks/blocking/code_rules_naming_collection.py`.
 
 A short narrative with no diagram is fine when a couple of plain sentences carry the whole picture. The diagram earns its place once the explanation grows past what two or three lines hold — the moment a wall of prose starts to form.
 
@@ -86,10 +86,6 @@ one — and you're debugging blind.
 
 Two surfaces carry this standard:
 
-- **Hook (the run-on backstop).** `check_docstring_runon_sentence` in `packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py` flags the one mechanical mark of a wall: a single narrative sentence that is both over the word limit and joined by an em-dash or a semicolon. A hook cannot judge whether prose paints a picture, so it catches only this structural mark. It reads the narrative through a shared partition that sets aside any `::` literal block and any doctest, so a diagram's own arrows and dashes never count against the sentence.
+- **Hook (the run-on backstop).** `check_docstring_runon_sentence` in `~/.claude/hooks/blocking/code_rules_docstrings.py` flags the one mechanical mark of a wall: a single narrative sentence that is both over the word limit and joined by an em-dash or a semicolon. A hook cannot judge whether prose paints a picture, so it catches only this structural mark. It reads the narrative through a shared partition that sets aside any `::` literal block and any doctest, so a diagram's own arrows and dashes never count against the sentence.
 - **Hook (the prose-wall backstop).** `check_docstring_prose_wall_without_illustration` in the same module flags a narrative that runs more than six prose lines with no diagram block. It marks the wall so the writer shows the behavior with a `::` example or a doctest and trims the prose to a few short lines. It cannot judge whether the diagram illustrates well; that stays with the audit lane.
-- **Audit (the judgment lane).** Category O sub-bucket O9 in `packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` carries the illustrative-and-brief judgment the hook cannot. The audit teammate reads each changed docstring's narrative and asks whether a general developer follows it on the first read.
-
-## Why
-
-A docstring earns its place by saving the reader a trip into the body. A wall of stacked machinery nouns costs more to read than the code it describes, so the reader skips it and the docstring becomes dead weight. Prose that paints a concrete scene — the moment, the input, the outcome — lets a reader reason about the code without reading it. Naming this standard makes the wall a finding at write time and at audit, rather than a slow defect a reader meets months later.
+- **Audit (the judgment lane).** Category O sub-bucket O9 in `~/.claude/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` carries the illustrative-and-brief judgment the hook cannot. The audit teammate reads each changed docstring's narrative and asks whether a general developer follows it on the first read.

package/rules/plain-language.md

@@ -4,4 +4,6 @@ All prose a person reads (chat, `AskUserQuestion`, docs, PR/issue bodies, commit
 
 The `plain_language_blocker` PreToolUse hook (AskUserQuestion + `.md` Write/Edit/MultiEdit) blocks a heavy word and names the everyday swap; code fences, inline code, blockquotes, URLs, and file paths are skipped.
 
+[`eli11-replies`](eli11-replies.md) governs reply length and shape; this rule governs word choice.
+
 A project can keep its own domain words out of the check with a `.claude/plain-language-allow.json` file: a JSON array of terms. An exact, case-insensitive, whole-word match on any term passes. The hook reads this file only from inside the project tree, up to the repository root, so each project's allowlist stays with its own code.

package/rules/proof-of-work-pr-comments.md

@@ -20,7 +20,3 @@ The `pr_description_enforcer` hook enforces the standard at two points:
 - **On `gh pr ready`:** the hook reads the PR's comments and blocks readying while no comment passes the audit. `gh pr ready --undo` returns a PR to draft and is never blocked.
 
 A `gh` failure (network, auth, missing executable) never blocks — the gate fails open on tooling problems, and the comment audit skips bodies it cannot read.
-
-## Why
-
-A PR body says what changed; the proof comment shows that it worked. Real command output, measured numbers, and a rendered image let a reviewer check the claim in seconds, with no need to re-run the work. Stating the gaps keeps the proof honest: the reviewer knows exactly what still rests on trust and where that is covered. Gating draft-to-ready makes the comment land before review starts, on every machine, whatever the session's habits.

package/rules/re-stage-before-commit.md

@@ -4,6 +4,8 @@ Stage the files you edited this session right before you commit them. A plain `g
 
 `session_edit_stage_gate` (PreToolUse on Bash `git commit`) denies a commit that would drop tracked session edits and names the fix: `git add <paths>`, `git commit -a`, or a `# partial-commit` marker.
 
+Staging covers tracked files you edited. Do not commit untracked files unless the user explicitly instructs it — an untracked file in the working tree is outside the change until they say otherwise.
+
 ## Escapes the denial does not restate
 
 - **A pathspec** — `git commit -- <paths>` or `git commit <paths>` commits only the named paths on purpose and steps the gate aside.

package/rules/research-mode.md

@@ -19,5 +19,15 @@ If you generate a claim and cannot find a supporting source, retract it. Do not
 ## 3. Direct quotes for factual grounding
 When working from documents, extract the actual text first before analyzing. Ground your response in word-for-word quotes, not paraphrased summaries. Reference the quote when making your point.
 
+## How citations appear in a chat reply
+
+The grounding requirement above never relaxes: state no claim you cannot source. What changes with the channel is how much of the source you print. A chat reply carries the source in compact form — a linked source name, or a `file:line` reference. Word-for-word quotes and full citation lists belong in artifacts, PR bodies, and issue bodies, or in a reply when the user asks for them.
+
 ## Exceptions
 Creative thinking, brainstorming, and novel ideas don't require citation. You can synthesize across sources to reach new conclusions, but the inputs must be grounded.
+
+## Sibling rules
+
+- [`explore-thoroughly.md`](explore-thoroughly.md) — grounds an implementation plan in the codebase, as this rule grounds a factual claim in a source.
+- [`verify-runtime-state.md`](verify-runtime-state.md) — a runtime verdict needs a live probe from this session, not a citation.
+- [`hedging-claims.md`](hedging-claims.md) — the Stop hook that catches an unverified claim wearing a hedge word.

package/rules/shell-invocation.md

@@ -0,0 +1,21 @@
+# Shell Invocation
+
+Two constraints govern every shell command an agent issues: which shell runs it, and what the command string may contain.
+
+## Use pwsh
+
+Every Bash-tool shell command on Windows uses `pwsh`: `pwsh -NoProfile -File '<script>.ps1' <args>` for scripts, `pwsh -NoProfile -Command "..."` (or a literal `@'...'@` here-string) for inline work, or the built-in `PowerShell` tool for pure-PowerShell workflows (it supports `run_in_background`). Never wrap a script path in `-Command "& '...'"` — `-File` keeps `permissions.allow` matching. The `&` call operator is fine for invoking an executable at a path (`& '<venv>\Scripts\python.exe' script.py`).
+
+The mandate covers the shell a command runs through, not every executable a command names. A direct interpreter invocation another rule documents — the paramiko NAS helper in [`nas-ssh-invocation.md`](nas-ssh-invocation.md), a `python` call on a repo script — conforms as written.
+
+Keep `powershell`, `powershell.exe`, `cmd /c`, and `bash -c` out of the `settings.json` permission rules. `Audit-ShellPolicy.ps1` reports those forms and `Migrate-ShellPolicy.ps1` rewrites them to `pwsh`. Both ship in the claude-dev-env repo at `packages/claude-dev-env/scripts/` and run on demand, not as a live gate.
+
+## No shell substitution
+
+No `$(...)`, unescaped backticks, or `<(...)` / `>(...)` process substitution in Bash tool commands. The allowlist matcher reads the raw command string, so a substitution wrapper forces a permission prompt even when every inner segment is auto-allowed. Split into separate tool calls, or use flag forms like `git -C "<path>" rev-parse HEAD`. Arithmetic `$((...))` passes: it spawns no subshell.
+
+When a script file's literal body needs `$(...)`, author it with the Write tool, not a Bash heredoc.
+
+## Enforcement
+
+`shell_substitution_blocker.py` (PreToolUse on Bash, hosted by `bash_pre_tool_use_dispatcher`) denies a command carrying a live substitution and returns the split-into-two-calls rewrite. Single-quoted runs are stripped before the scan, and a backtick preceded by an odd number of backslashes is escaped, so an inert mention passes.

package/rules/testing.md

@@ -18,3 +18,7 @@ paths:
 
 If a component renders field X, the mock must have field X with a valid value.
 Incomplete mocks make it impossible to distinguish "broken code" from "missing data".
+
+## Tests Exercise Real Behavior
+
+Tests exercise real behavior, real data, and production code paths. A test that asserts on a stand-in for the production path proves the stand-in works.

package/rules/verified-commit-gate-skip.md

@@ -1,28 +1,4 @@
-# Verified-Commit-Gate Skip Marker
+# Optional Verifier Review
 
-**When this applies:** A `git commit` or `git push` through the Bash tool is blocked by the `verified_commit_gate` hook.
-
-## The marker
-
-Appending the comment `# verify-skip` as a trailing shell comment to the Bash command exempts that single commit or push from the gate. The hook (`hooks/blocking/verified_commit_gate.py`, marker constant `VERIFICATION_BYPASS_MARKER`) recognizes the marker only when its leading `#` sits at a word boundary and outside every quoted region — a genuine comment, not a data-only mention inside a quoted commit message or `gh` body — and lets the command run without a minted verdict.
-
-## When the marker is allowed
-
-Use it only when both hold:
-
-1. The gate is blocking the command, and
-2. The branch surface content is the same code a `code-verifier` already passed clean — nothing effectively changed since that clean verdict.
-
-That situation arises when the verdict fails to cover the current surface even though the code is the same: a clean verdict that never minted (the verifier's fenced block ran in a resumed turn, so the SubagentStop minter never fired), a surface hash perturbed by index-only staging churn, or a concurrent worktree write that was fully reverted back to the verified content. Before using the marker, confirm the match yourself: the test suite the verifier ran still passes, and the diff holds no content beyond what the clean verdict covered.
-
-## When the marker is not allowed
-
-Every other case runs the verification: spawn the `code-verifier` agent and let the SubagentStop hook mint the verdict. In particular, never use the marker to:
-
-- Skip a branch's first verification.
-- Commit or push after any real code change since the last clean verdict — one changed line means a fresh verification.
-- Work around a verifier that reported findings; findings get repaired and re-verified.
-
-## One command, one exemption
-
-The marker exempts only the command that carries it. The next commit or push on the branch faces the gate again, so a follow-up change still verifies before it lands.
+Code-verifier review is an optional workflow selected by the task owner.
+Commit and push operations use the checks selected for the task.

package/rules/verify-before-asking.md

@@ -47,3 +47,8 @@ Reserve user questions for:
 
 **Wrong:** "Is there a Prisma schema in this project?"
 **Right:** Glob for `schema.prisma` and check.
+
+## Parent rules
+
+- [`ask-user-question-required.md`](ask-user-question-required.md) — once a question genuinely belongs to the user, this rule routes it through `AskUserQuestion`.
+- [`verify-runtime-state.md`](verify-runtime-state.md) — the same duty applied to a verdict: gather the live probe before you conclude, not just before you ask.