claude-dev-env 2.4.0 → 2.7.0

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

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

package/rules/cleanup-command-forms.md

@@ -1,23 +0,0 @@
-# Cleanup Command Forms
-
-Never use bash `rm` in any form to clean up. The `destructive_command_blocker` hook watches every Bash-tool command and matches `rm -rf` (and the rest of the destructive patterns) as raw text. It allows an `rm` without a prompt only for a narrow set of shapes it can prove safe: an `rm` whose every target is an absolute path under the OS temp root, `/tmp`, `/temp`, or a worktrees directory — standalone, or in a chain whose other segments are plain reporting commands such as `echo` or `cat`; an `rm` run from an ephemeral working directory; and an `rm` whose every target sits inside `~/.claude`. It falls through to a permission prompt on anything outside that set: a `$`, `$(...)`, or backtick expansion whose value it cannot resolve, a target it cannot place in a safe directory, a glob basename, or a string-executing wrapper (`bash -c 'rm -rf …'`). In a background or auto-mode run no human can answer that prompt, so the call stalls.
-
-Remove files with these forms, which the hook never prompts on:
-
-- **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. A file left in the OS temp dir or `$CLAUDE_JOB_DIR/tmp` is ephemeral and needs no explicit removal.
-- **Worktrees:** `git worktree remove --force <path>`. This matches no destructive pattern.
-- **When bash `rm` is unavoidable:** one standalone `rm` command, an absolute literal path under the OS temp root or a worktrees directory, no chaining, no variables, no globs. The hook auto-allows this shape without a prompt.
-
-## 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 in place for the parent to remove at teardown with `Remove-Item`.
-
-## Sibling rules
-
-- [`no-inline-destructive-literals`](no-inline-destructive-literals.md) — keep a destructive literal out of the Bash command string even when it rides only as data.
-- [`cleanup-temp-files`](cleanup-temp-files.md) — remove the scratch files a task created once the task is done.
-- [`windows-filesystem-safe`](windows-filesystem-safe.md) — the safe `rmtree` / `force_rmtree` patterns for read-only Windows files.

package/rules/code-reviews.md

@@ -1,11 +0,0 @@
-# Responding to Code Reviews
-
-**When this applies:** GitHub PR review feedback on a branch you are fixing.
-
-**MANDATORY PROTOCOL:**
-
-1. Fetch ALL reviewer comments BEFORE any fixes
-2. Create TodoWrite checklist - One item per comment
-3. Fix systematically - Mark each todo complete
-4. Reply to EACH comment inline
-5. Create ONE review fix commit - DO NOT squash with original

package/rules/env-var-table-code-drift.md

@@ -1,10 +0,0 @@
----
-paths:
-  - "**/*.md"
----
-
-# Env-Var Summary Table Names a Code 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 table row that names 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 (the hook cannot prove the drift).

package/rules/gh-body-file.md

@@ -1,5 +0,0 @@
-# gh --body-file Rule
-
-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 literal `\``. Write the temp file BOM-free: `[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) blocks `--body <arg>` and returns the corrective message.

package/rules/gh-paginate.md

@@ -1,3 +0,0 @@
-# gh API Pagination
-
-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` — `gh`'s built-in `--jq` runs per page, so cross-page operations like `sort_by | last` give wrong-but-confident results. 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.

package/rules/hook-prose-matches-detector.md

@@ -1,15 +0,0 @@
----
-paths: **/hooks/**/*.py
----
-
-# Hook Prose Matches Its Detector
-
-A hook's docstring lead narrative and its `CORRECTIVE_MESSAGE` describe exactly the shapes the detector flags — no broader trigger surface than the regex enforces.
-
-`hook_prose_detector_consistency` (PreToolUse on Write|Edit of hook modules and `*_constants.py` companions) blocks prose that claims a trigger the detector never fires on, and names the fix.
-
-## Judgment
-
-After writing a hook, ask: would a token that matches 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.

package/rules/no-historical-clutter.md

@@ -1,26 +0,0 @@
----
-paths:
-  - "**/*.md"
-  - "**/*.py"
-  - "**/*.mjs"
-  - "**/*.js"
-  - "**/*.ts"
-  - "**/*.ps1"
-  - "**/*.sh"
----
-
-# No Historical Clutter in Documentation or Comments
-
-Never reference removed implementations, old defaults, prior behaviors, or earlier contracts when updating documentation or comments. The current state is all that matters. A module or function docstring carries the same describe-current-state-only contract as a `.md` file.
-
-`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 example.
-
-## What stays allowed
-
-- Comparisons to alternatives that still exist (for example, "use `--paginate --slurp | jq`, not `--jq` alone")
-- Rationale that explains why a pattern is wrong in terms of present behavior (for example, "`--jq` runs per-page, so cross-page operations produce wrong results")
-- References to external sources for defects that still exist (for example, gh CLI #10459)
-
-## The test
-
-After writing, ask: if someone reads this a year from now with no knowledge of earlier states, does every sentence still make sense and add value? If a sentence only helps someone who knew an earlier state, delete it.

package/rules/no-inline-destructive-literals.md

@@ -1,9 +0,0 @@
-# No Inline Destructive-Command Literals in Bash
-
-The `destructive_command_blocker` PreToolUse hook matches destructive patterns (`rm -rf`, `git reset --hard`, `dd`, `mkfs`, `chmod -R`, fork bombs) as raw text anywhere in a Bash-tool command, with no quote-awareness — so a destructive literal carried only as data (a commit message, a PR/issue body, an echoed string, a `python -c` / `node -e` / `awk` argument, a heredoc) trips the confirmation prompt even though the shell never executes it. In a background or auto-mode run no human can answer that prompt, so the call stalls.
-
-Keep destructive literals out of the Bash command string:
-
-- Bodies that describe destructive-command behavior go in a file passed by path — `git commit -F <file>`, `gh ... --body-file <file>` (see [`gh-body-file`](gh-body-file.md)) — never `git commit -m` / `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.
-- Genuine cleanup targets the OS temp dir or `$CLAUDE_JOB_DIR/tmp` (auto-allowed as ephemeral), never a repository or worktree path.

package/rules/no-justification-noise.md

@@ -1,61 +0,0 @@
----
-paths:
-  - "**/*.md"
----
-
-# No Justification Noise in Documentation
-
-**When this applies:** Any Write or Edit to a `.md` file.
-
-## Rule
-
-Markdown states what the system is and does, in facts a reader can act on. Cut any sentence whose only job is to say why a choice is good, or to restate a gain the reader already works out from the stated behavior or from a rule a hook or another file enforces. A sentence like that carries no new fact — it repeats one the reader already holds, so it earns no space.
-
-## The test
-
-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 or from a rule enforced elsewhere?** If no, cut the sentence.
-
-## Two shapes to catch
-
-### Pure noise — cut the whole sentence
-
-A sentence whose only job is to point out a result that follows from a fact the doc already states.
-
-> Autoconverge's bug-audit and self-review lenses and pr-converge's CODE_REVIEW step 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.
-
-The doc already states the lenses read the file. The "so it stays out of the token budget" tail is a result the reader works out alone, so it carries nothing. Cut the sentence.
-
-### Load-bearing first, noise after — keep the fact, cut the rest
-
-A sentence that states a real fact, trailed by prose that only re-argues it or restates its payoff.
-
-> The pre-catch stage drives the code to clean against these five lanes before any external reviewer sees it. External reviewers (Cursor Bugbot, GitHub Copilot) are terminal confirmation gates that run only after every lane below is clean, and they are expected to return zero findings.
-
-Keep the first sentence — it states what the stage does. Cut the second: "run only after every lane below is clean" repeats the first sentence's claim, and "expected to return zero findings" is a hoped-for result, not a fact the reader acts on.
-
-## What stays
-
-- A fact the reader acts on: an input a piece of code takes, an order a producer emits, a path a script writes.
-- A rule's one-line reason stated in terms of present behavior — `--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 a constraint the reader weighs before choosing a path.
-
-## Sibling rules
-
-This rule sits beside three others; each cuts a different kind of dead prose.
-
-| Rule | Cuts |
-|---|---|
-| `no-historical-clutter.md` | references to old state (`previously`, `migrated from`) |
-| `self-contained-docs.md` | references to the chat that produced the doc |
-| `plain-language.md` | heavy words with an everyday swap |
-| `no-justification-noise.md` | a present-tense sentence that only justifies or restates a fact the reader already holds |
-
-`no-historical-clutter.md` keeps a rule's reason when the reason names present behavior; this rule keeps the same reason for the same test. The two agree: a reason that names a fact the reader acts on stays, and a sentence that only re-argues a stated fact goes.
-
-## Enforcement
-
-The AI review lane carries this rule: `AGENTS.md` names it as a finding an agent applies to the `.md` lines a PR changes. No hook backs it, because telling a justification sentence from a load-bearing one needs meaning a regex cannot read.
-
-## Why
-
-A sentence that repeats a fact the reader already holds costs reading time and pays back nothing.

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

@@ -1,25 +0,0 @@
----
-paths:
-  - "**/*.py"
-  - "**/*.mjs"
-  - "**/*.js"
-  - "**/*.ts"
-  - "**/*.ps1"
-  - "**/*.sh"
----
-
-# New Production File Absent From Its Package Inventory
-
-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. When you create a new production file in such a directory, add an entry naming it — a row in the table or a bullet in the list — in the same change. The entry names the file in backticks and says what it does.
-
-`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.
-
-## Judgment the gate cannot derive
-
-The file-list entry is the slice the gate checks by name. 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 this 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 description clause to name it. The gate only checks that the basename appears once; it never reads the description. Constants modules (`*_constants.py`, or any `.py` directly inside `config/`) are the common shape: the constant's other home is the module docstring, so the clause that lands in the 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 that adds 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.

package/rules/right-sized-engineering.md

@@ -1,28 +0,0 @@
-# Right-Sized Engineering
-
-**Build it right, but build it simple.** Good engineering principles at the appropriate scale.
-
-## Always Do
-- Extract constants and configuration (no hardcoding)
-- Create reusable functions (no copy-paste)
-- Use proper error handling
-- Follow DRY from the start
-- Single responsibility per function
-
-## Never Do (Solo Scale)
-- Abstract base classes for single implementations
-- Dependency injection frameworks
-- Complex patterns (CQRS, microservices)
-- Multiple inheritance hierarchies
-- Over-abstracted interfaces
-
-## Complexity Budget
-
-**State BEFORE implementation:** Files (target 1-2, max 3), Lines (~50-300), Checkpoints ("Is this MINIMUM?", "Fewer files?", "Functions vs classes?")
-
-## YAGNI for API Surface
-
-**Don't expose optional parameters until they're actually used.**
-
-If a value will always be a constant for now, use the constant internally.
-Only add the parameter when callers actually need to vary it.

package/rules/self-contained-docs.md

@@ -1,17 +0,0 @@
-# Self-Contained Documentation
-
-**When this applies:** All generated artifacts — gists, decision docs, PR descriptions, issue bodies, plans, SKILL.md content. Exception: Obsidian session logs (intentionally conversation-scoped).
-
-## Rule
-
-Every document must be fully self-contained. A reader with zero prior context must understand every statement without needing access to the conversation that produced it.
-
-## Patterns to Catch and Replace
-
-| Pattern | Example | Fix |
-|---|---|---|
-| References to options/choices discussed in conversation | "This is not Option A from the original framing" | Delete the sentence, or restate the decision on its own terms |
-| "As discussed" / "as we decided" / "from the prior session" | "As discussed, we'll use embeddings" | "Sref matching uses sentence-transformer embeddings" |
-| Pronouns pointing to conversation context | "This approach addresses the concerns raised earlier" | State what the concerns were inline, or delete |
-| Relative framing ("instead of X") where X was only discussed verbally | "Instead of the three options considered" | State the chosen approach directly without referencing alternatives the reader can't see |
-| Session-specific sequencing | "After Round 3 we decided..." | State the decision as a fact |

package/rules/shell-invocation-policy.md

@@ -1,5 +0,0 @@
-# Shell Invocation Policy (pwsh-only)
-
-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`).
-
-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 in `packages/claude-dev-env/scripts/` and run on demand, not as a live gate.

package/rules/tdd.md

@@ -1,7 +0,0 @@
-# TDD Process: Red-Green-Refactor
-
-**TEST-DRIVEN DEVELOPMENT IS NON-NEGOTIABLE.** Every single line of production code must be written in response to a failing test. No exceptions.
-
-1. **Red**: Write failing test. NO PRODUCTION CODE.
-2. **Green**: MINIMUM code to pass. Resist urge for more.
-3. **Refactor**: Assess improvements. Only if valuable.

package/skills/closeout/reference/issue-body-templates.md

@@ -1,108 +0,0 @@
-# Issue body templates
-
-Body shapes for the parent tracking issue and its child issues, plus a worked example. Every body is self-contained: a reader with zero session context understands it. Every body carries a quoted line of evidence captured this session. Write each body to a temp file and pass it with `gh issue create --body-file <path>`.
-
-## Contents
-
-- [Child issue body](#child-issue-body)
-- [Parent tracking issue body](#parent-tracking-issue-body)
-- [Worked example — child](#worked-example--child)
-- [Worked example — parent](#worked-example--parent)
-- [Body rules](#body-rules)
-
-## Child issue body
-
-One obstacle per child. Fill every section:
-
-```markdown
-## What happened
-
-<One sentence: the failure mode, in plain terms.>
-
-## Evidence
-
-<The verbatim line captured this session — error text, command, or log line — in a fenced block.>
-
-```
-<exact quoted text>
-```
-
-## Where
-
-<The file, hook, gate, or tool the evidence names. Path relative to the repo root.>
-
-## Impact
-
-<What the obstacle cost: work blocked, count of times hit, workaround forced.>
-
-## Proposed fix
-
-<The specific change. Name the failure mode and the condition, not "improve error handling".>
-```
-
-## Parent tracking issue body
-
-The parent gathers the children. Its body is a checklist, one line per child created:
-
-```markdown
-## Session closeout — <short session label>
-
-Obstacles this session, filed as child issues:
-
-- [ ] owner/repo#<N> — <child title>
-- [ ] owner/repo#<N> — <child title>
-- [ ] owner/repo#<N> — <child title>
-
-## Handoff
-
-A cloud handoff prompt for these issues was printed in the closing session. It carries the safety boundaries, base branch, per-package verification commands, and the dependency order among the children.
-```
-
-## Worked example — child
-
-```markdown
-## What happened
-
-The code_rules_enforcer hook blocked a valid list literal in a test file, where test files are exempt from the magic-value gate.
-
-## Evidence
-
-```
-BLOCKED: [MAGIC_VALUE] Inline list literal [200, 404, 500] in a function body -- extract to a named constant in config/.
-```
-
-## Where
-
-packages/claude-dev-env/hooks/blocking/code_rules_enforcer.py — the inline-collection check.
-
-## Impact
-
-Hit 3 times in one session on three test files. Forced a workaround: moving each literal to a module constant the test did not need.
-
-## Proposed fix
-
-Extend the test-file exemption that already covers the magic-value gate to also cover the inline-collection check, so list and set literals in test bodies pass.
-```
-
-## Worked example — parent
-
-```markdown
-## Session closeout — hook exemptions for test files
-
-Obstacles this session, filed as child issues:
-
-- [ ] jl-cmd/claude-dev-env#101 — inline-collection gate fires in exempt test files
-- [ ] jl-cmd/claude-dev-env#102 — boolean-naming gate flags a fixture variable
-
-## Handoff
-
-A cloud handoff prompt for these issues was printed in the closing session. It carries the safety boundaries, base branch, per-package verification commands, and the dependency order among the children.
-```
-
-## Body rules
-
-- **Quoted evidence is required.** No child ships without a fenced block holding a line captured this session.
-- **No volatile paths.** No temp dirs, worktrees, `$CLAUDE_JOB_DIR`, `.claude-editor/jobs`, or `.claude/worktrees` paths in any body. Paste text inline; for a binary artifact, upload it to a durable release and link that URL.
-- **No chat references.** Drop "as discussed" and "the choice we picked". State each fact on its own.
-- **Specific over vague.** "The gate fires on `[200, 404, 500]` in a test body" beats "the gate is too strict".
-- **PII stripped.** Run the PII pass (see the PII redaction checklist) over every body before it reaches the confirmation gate.