claude-dev-env 2.0.1 → 2.1.0

package/rules/agent-spawn-protocol.md

@@ -1,47 +1,9 @@
 # Agent Spawn Protocol (Mandatory)
 
-**When this applies:** Before any Agent or Task tool invocation (Explore, implementation, research, or team subagents).
+Before any Agent or Task tool spawn (Explore, implementation, research, or team subagents):
 
-<agent_spawn_protocol>
+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.
 
-## Before spawning ANY agent — no exceptions
-
-Every Agent and Task tool call must follow this protocol. This includes Explore agents, research agents, execution agents, and team members.
-
-### Step 1: Context sufficiency check
-
-Before writing any agent prompt, verify you can answer all of these:
-- [ ] What specific files, directories, or areas of the codebase are involved?
-- [ ] What constraints apply? (patterns to follow, things NOT to change, boundaries)
-- [ ] What does success look like? (expected output, acceptance criteria)
-- [ ] Is the task unambiguous enough to delegate?
-
-If ANY answer is "I don't know" -- investigate first (read files, search code) or ask the user. Do NOT spawn with incomplete context.
-
-### Step 2: Craft the prompt with /prompt-generator
-
-Run the `/prompt-generator` skill to produce a structured prompt. Feed it:
-- The task description and goal
-- Target files/directories discovered in Step 1
-- Constraints and boundaries
-- Expected output format
-- Acceptance criteria
-
-The skill will ask 1-3 clarifying questions if information is missing -- this is the built-in context verification.
-
-Use the skill's output as the agent's `prompt` parameter.
-
-### Step 3: Spawn the agent
-
-Pass the structured prompt from Step 2 to the Agent/Task tool.
-
-</agent_spawn_protocol>
-
-## Why
-
-Agents receiving vague prompts waste tokens exploring in circles, produce code that misses constraints, and require expensive rework. A 30-second investment in prompt quality via /prompt-generator saves 5-minute agent failures. This applies equally to Explore agents (which waste context on unfocused searches) and execution agents (which write wrong code).
-
-## Relationship to other rules
-
-- **conservative-action.md** gates acting when ambiguous. This extends that: do not delegate when the task is ambiguous—investigate or ask the user first.
-- Project-specific rules or `~/.claude/CLAUDE.md` may define *whether* to use subagents or teams; this rule governs *how* to craft prompts when you do delegate.
+Full step detail, rationale, and relationship to other rules: `@~/.claude/docs/agent-spawn-protocol.md`.

package/rules/code-standards.md

@@ -3,39 +3,4 @@
 > **MANDATORY REFERENCE:** CODE_RULES.md - Load for ALL code generation.
 > This is the single source of truth for code standards. Non-negotiable.
 
-**Key principles (see CODE_RULES.md for complete reference):**
-- Self-documenting code (no comments)
-- Centralized configuration (one source of truth)
-- Reuse constants (search before creating)
-- No magic values (everything named)
-- No abbreviations (full words)
-- Complete type hints
-- TDD (test first)
-
-## Function Parameters - Required vs Optional
-
-**Use required parameters when no valid use case exists for optional.**
-**Remove unused parameters.**
-
-## Encapsulation - Logic Belongs in Models
-
-**NEVER scatter construction logic in calling code.**
-
-Path/URL building, formatting, transformations -> Put in model methods.
-If you find yourself building the same string pattern in multiple places, it belongs in the model.
-
-## Document Temporary Code
-
-**Scaffolding/placeholder code MUST have TODO comments.**
-
-When code exists only to enable testing before full implementation:
-- Add `// TODO: Replace with...` explaining what will replace it
-- Explain WHY it's temporary, not just WHAT it does
-
-## Naming Reflects Behavior
-
-**Name components after what they ARE, not abstract concepts.**
-
-If it overlays the viewport -> "Overlay" not "Screen"
-If it validates input -> "Validator" not "Handler"
-Names should describe observable behavior or visual appearance.
+`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.

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

@@ -5,25 +5,6 @@ paths:
 
 # Env-Var Summary Table Names a Code File That Reads the Variable
 
-**When this applies:** Any Write, Edit, or MultiEdit to a markdown (`.md`) file that carries an environment-variable summary table — a markdown table whose rows pair a `` `VARIABLE` `` name with the `` `code/file.py` `` that reads it.
+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.
 
-## Rule
-
-Every row in an env-var summary table names a code file whose source references the variable. A row pairs an UPPER_SNAKE variable with a code-file path, written as `` | `GOOGLE_APPLICATION_CREDENTIALS` | `auth/google_auth.py` | ... | ``, and the named file reads that variable. When the file exists yet its source never mentions the variable name, the row is stale: the table points a reader at a consumer relationship the code does not have, so a reader trusts the doc to behavior the code dropped.
-
-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. The doc and the code move together in one commit.
-
-## What the gate checks
-
-The `env_var_table_code_drift_blocker.py` hook runs on every Write, Edit, and MultiEdit whose target is a `.md` file. It:
-
-1. Reads the content the tool would leave on disk, skipping lines inside a fenced code block.
-2. Collects each table row whose first cell names an UPPER_SNAKE variable and whose later cell names a code file with a recognized extension (`.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`).
-3. Resolves the named code file under the repository root (the nearest `.git`-bearing ancestor of the markdown file) and reads its source.
-4. Blocks the write when the file resolves yet its source never references the variable name. For an Edit, drift the file already held on an untouched row is excluded, so only drift the edit introduces is reported.
-
-The check stays quiet for a row whose code file resolves nowhere under the repository root (it cannot prove the drift), a row whose second cell holds no code-file path, and a table row inside a fenced code block.
-
-## Why this is a hook, not a lint pass
-
-An env-var table that names a file whose source skips the variable reads as a correct map of which code consumes which setting, while pointing one row at behavior the code dropped. A reader trusting the row chases a setting the file ignores, and the gap survives review because the table still looks complete. Catching it as the doc is written keeps the table and the code in step.
+`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/hook-prose-matches-detector.md

@@ -4,23 +4,12 @@ paths: **/hooks/**/*.py
 
 # Hook Prose Matches Its Detector
 
-**When this applies:** Any Write or Edit to a hook module (`.py` under `hooks/`) or its `*_constants.py` companion.
+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 enforcement:** `hook-prose-detector-consistency` (PreToolUse on Write|Edit) blocks a hook whose user-facing prose claims a trigger its detector never fires on. See `hooks.json` for registration.
+`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.
 
-## Rule
+## Judgment
 
-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. An author reads the corrective message to learn what they did wrong; an author reads the docstring to learn what the hook guards. When either claims a trigger the detector cannot fire on, both audiences are misled: an author whose only token is that shape never sees the block, and an author who does see the block is told the wrong cause.
+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 blocker case
-
-A path-shape blocker detects a per-iteration token only when the token sits next to a path separator (its detection regex keys off a `[\\/]`-style character class). Such a hook must not claim it blocks an "output-key segment": a quoted structured-output key alone, with no looped path, is never flagged. The `*_constants.py` companion holds the corrective message and not the detector, so the phrase "output-key segment" describing a blocked trigger is itself the violation there, regardless of which file holds the regex.
-
-| Prohibited claim | Why it overstates | Correct phrasing |
-|---|---|---|
-| "appears as a path or output-key segment" | the detector keys off a path separator only | "appears as a per-iteration path segment" |
-| docstring: "blocks a bare token like `cand_i`" | a bare prose token next to no separator is not flagged | "blocks a per-iteration path like `${work}\cand_i\plate.svg`" |
-
-## The test
-
-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/nas-ssh-invocation.md

@@ -1,23 +1,11 @@
 # NAS SSH Invocation Policy
 
-**When this applies:** Any `ssh`, `scp`, or `sftp` command against the NAS.
-
-## Rule
-
-Reach the NAS through the Windows OpenSSH binary with batch mode on. Git Bash's MSYS `ssh` reads `~/.ssh/id_ed25519` as world-readable through its ACL mapping, rejects the key as bad permissions, offers no key, and falls back to an interactive password prompt. In an unattended session no one answers that prompt, so the session hangs. The `System32/OpenSSH` binary authenticates the same key without a prompt.
-
-Use this form for every NAS ssh command:
+Reach the NAS through the Windows `System32/OpenSSH` binary with `-o BatchMode=yes` on every `ssh`, `scp`, or `sftp` command:
 
 ```
 "/c/Windows/System32/OpenSSH/ssh.exe" -o BatchMode=yes -o ConnectTimeout=10 -p 22 operator@nas.example.local "<cmd>"
 ```
 
-`scp` and `sftp` take the matching `System32/OpenSSH` binary, `-o BatchMode=yes`, and the same port (`-P` for `scp`).
-
-The host, ssh user, and port come from the `CLAUDE_NAS_*` environment variables or `~/.claude/local-identity.json`; the committed examples show placeholders (`nas.example.local`, `operator`, `22`).
-
-`-o BatchMode=yes` is required, not optional: it turns a key-authentication failure into a loud non-zero exit rather than a silent password prompt, so an auth regression surfaces as an error you can read.
-
-## Enforcement
+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.
 
-`nas_ssh_binary_enforcer.py` (PreToolUse on Bash) denies a bare `ssh`/`scp`/`sftp` command word aimed at the NAS host and points at the full-binary form. It also denies the full `System32/OpenSSH` binary to that host when the command omits `-o BatchMode=yes`. Commands to any other host, and commands that mention the address without an ssh-family command word, pass.
+Host, user, and port config, the `scp`/`sftp` forms, and the full rationale: `@~/.claude/docs/nas-ssh-invocation.md`.

package/rules/no-historical-clutter.md

@@ -11,58 +11,16 @@ paths:
 
 # No Historical Clutter in Documentation or Comments
 
-**When this applies:** Any Write or Edit to files containing comments or documentation.
+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.
 
-**Hook enforcement:** `state-description-blocker` (PreToolUse on Write|Edit) blocks historical/comparative language automatically. See `hooks.json` for registration.
+`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.
 
-Coverage spans `.md` prose, code comments, and Python module/class/function docstrings; a phrase wrapped in double quotes or backticks inside a docstring counts as a mention and is skipped.
+## What stays allowed
 
-## Rule
-
-Never reference removed implementations, old defaults, prior behaviors, or how something `"used to be"` when updating documentation. The current state is all that matters.
-
-A module or function docstring carries the same describe-current-state-only contract as a `.md` file.
-
-## Examples of prohibited patterns
-
-### In documentation (.md files)
-
-| Pattern | Why it's clutter |
-|---------|-----------------|
-| `` `"instead of 30"` `` in a pagination rule | The old default `no longer` exists in code; the rule reader doesn't need to know what it was |
-| `` `"previously this used X"` `` | If X is gone, it's noise |
-| `` `"before this rule, we did Y"` `` | The rule exists now; the before-state is irrelevant |
-| `` `"migrated from Z to W"` `` | If Z is fully removed, the migration story is git history, not documentation |
-| `` `"the old implementation did A"` `` | If A is gone, the reader gains nothing from knowing it existed |
-| `` `"originally"` `` / `` `"used to be"` `` | Same — dead context |
-
-### In code comments
-
-| Pattern | Good replacement |
-|---------|-----------------|
-| `# Uses X instead of Y` | `# Uses X` |
-| `# Previously configured via Z` | `# Configured via Z` |
-| `# Now uses the new API client` | `# Uses the new API client` |
-| `# No longer supports legacy mode` | `# Supports modern mode only` |
-| `// Switched to async processing` | `// Processes asynchronously` |
-| `# Replaced by the cache layer` | `# Cache layer handles reads` |
-
-### Hook-detected patterns
-
-The `state-description-blocker` hook (PreToolUse on Write\|Edit) enforces these patterns automatically:
-
-`instead of`, `previously`, `now uses/does/handles/supports/names/includes`, `was previously`, `were previously`, `was formerly`, `was added`, `used to`, `no longer`, `has/have been updated/changed`, `replaced by`, `replaces`, `superseded by`, `supersedes`, `changed from`, `changes from`, `switched from/to`, `migrated from/to`, `moved to/into`, `extracted as`, `updated to`, `originally`, `as of`
-
-## What IS allowed
-
-- Comparisons to *currently existing* alternatives (e.g., "use `--paginate --slurp | jq`, not `--jq` alone")
-- Rationale that explains *why* a pattern is wrong in terms of present behavior (e.g., "`--jq` runs per-page, so cross-page operations produce wrong results")
-- References to external sources for defects that still exist (e.g., gh CLI #10459)
+- 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 documentation, ask: **"If someone reads this a year from now, with no knowledge of what came before, does every sentence still make sense and add value?"** If a sentence only adds value to someone who knew the old state, delete it.
-
-## Why
-
-Historical references clog context windows and force readers to mentally filter "what was" from "what is." The git log is the authoritative record of what changed and why. Documentation describes the current contract.
+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,11 +1,9 @@
 # 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/review-comment 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.
+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:
 
-- Commit messages and PR/issue/review-comment 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 `destructive_command_blocker` (or any hook) behavior, run the committed test suite (`python -m pytest <test_file>`), which passes the command strings as in-language data, not as a shell command — never an inline `python -c` harness.
+- 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.
-
-The `destructive_command_blocker` hook is the enforcement surface; this rule is how to keep a non-executing mention from tripping it.

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

@@ -10,41 +10,16 @@ paths:
 
 # New Production File Absent From Its Package Inventory
 
-**When this applies:** Any Write that creates a new production code file (`.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`) in a directory whose sibling `README.md` or `CLAUDE.md` already names two or more of the directory's files in backticks, in a directory whose own `SKILL.md` names two or more of the directory's files, or in a skill's `scripts/` subdirectory whose parent `SKILL.md` Layout table already names two or more of those scripts.
+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.
 
-## Rule
+`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.
 
-A package directory that documents its own files in a `README.md` Layout table or a `CLAUDE.md` "Key files" list keeps that inventory in step with the directory. A skill package does the same in its `SKILL.md` Layout table, which sits at the skill root and maps the `scripts/` subdirectory by naming each script with its `scripts/<name>` path. A new production file the inventory does not name leaves the inventory and the directory disagreeing on the package's file set: a reader who trusts the inventory to map the directory misses the new file.
+## Judgment the gate cannot derive
 
-When you create a new production file in such a directory, add an entry naming it — a row in the `README.md` or `SKILL.md` table, a bullet in the `CLAUDE.md` list — in the same change. The entry names the file in backticks and says what it does.
+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:
 
-## Companion: keep the Purpose/scope sentence in step with the new responsibility
+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.
 
-The file-list entry is the deterministic slice the gate enforces. A package inventory also carries a free-prose scope sentence — a `## Purpose` paragraph in a `CLAUDE.md`, a one-line summary the parent directory's inventory gives each subdirectory — that names the responsibilities the package's modules cover. When the new module adds a responsibility the scope sentence omits, the same change broadens that sentence to name it, and updates the parent inventory's one-line summary of this subdirectory to match.
+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.
 
-Take a `files/` package whose `Purpose` reads "Holds helpers for downloading files over HTTP and extracting zip archives" and whose parent summary reads "file download, extraction, and path config helpers". Once a `force_remove.py` module that removes a directory tree sits beside the download helpers, both sentences name a narrower responsibility set than the directory holds. The required file-list bullet alone leaves that gap open. Broaden the `Purpose` sentence to name directory removal, and broaden the parent summary to match, in the same change that adds the module and its bullet.
-
-This scope-sentence slice is free prose: a hook cannot derive a module's responsibility from its filename, so the gate leaves it to judgment. It is the judgment companion to the file-list entry the gate enforces, and it belongs in the same change. This is the `category-o-docstring-vs-impl-drift` (O8) orphaned-doc-claim shape applied to a package inventory: a behavior change orphans a scope claim the prose still makes.
-
-## Companion: keep a per-file description in step with the file it describes
-
-The per-file entry a `CLAUDE.md` "Key files" list or a `README.md` Layout table gives each file carries more than the backticked filename the gate checks for. The clause after the file name — the em-dash description — is itself a free-prose scope claim about what the file holds. When the file gains a responsibility the description omits — a new public function, a new constant — the same change broadens the description clause to name it. The gate's file-list check passes the moment the file name appears once; it never reads the description clause, so a stale description beside a present file name stays invisible to the gate.
-
-A constants module is the common shape of this drift. A file whose name ends `_constants.py`, or any `.py` directly inside a `config/` directory, holds a set of module-level constants, and a sibling inventory describes that file by listing the set — `` `stp_constants.py` — the STP archive member constants: the Properties.xml member name, the workspace prefix every asset reference carries, and the source-form nine-patch filename suffix ``. When the file gains a module-level constant the list omits, three claims drift together: the list itself, the scope label that heads it (`the STP archive member constants`), and the package `## Purpose` sentence when that sentence describes the file's contents. The constant's other home — the module docstring of the constants file — and the sibling inventory's description of that file cover the same set, so the clause that lands in the docstring lands in the inventory description in the same change.
-
-This slice sits outside the gate. The gate fires on a Write that creates a new file, and it skips a file directly inside a `config/` directory, so an Edit that adds a constant to an existing `config/` constants module matches neither path. Like the Purpose/scope companion above, it is free prose a hook cannot derive from a file name, so it stays judgment here and a Category O8 finding at audit: a behavior change orphans a description claim the inventory still makes.
-
-## What the gate checks
-
-The `package_inventory_stale_blocker.py` hook runs on every Write whose target is a new file (a path not yet on disk). It:
-
-1. Skips a target that is not a production code file (`.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`), an exempt basename (`__init__.py`, `conftest.py`, `setup.py`, `_path_setup.py`), a test file (`test_*.py`, `*_test.py`, `*.spec.*`, `*.test.*`), or a file directly inside a `config/` or `tests/` directory.
-2. Reads each `README.md`, `CLAUDE.md`, and `SKILL.md` present in the target's own directory and, when the target sits in a `scripts/` subdirectory, the parent directory's `SKILL.md`, and collects every bare filename they name in backticks. A backticked token holding a path contributes its final segment, so `pipeline/seam_continuity.py` in an inventory counts as naming `seam_continuity.py` and `scripts/stp_selection.py` in a parent `SKILL.md` Layout table counts as naming `stp_selection.py`. A multi-word command-example span — one carrying whitespace or shell punctuation (`:`, `$`, `<`, `>`), such as `parent:node_modules package.json` or `python <file>.py` — names no literal file and is dropped.
-3. Filters the named basenames to those that exist as a file in the target's own directory — the inventory's own sibling files — and treats the directory as carrying a maintained inventory only when two or more such sibling files are named. A directory with no inventory, one whose `README.md` mentions a single file in passing, or one whose inventory prose names only files living in other directories (so no named basename is an on-disk sibling) is out of scope.
-4. Blocks the write when the new file's basename appears in no present inventory. An unreadable or oversized inventory document is skipped, so a missing inventory never blocks a write.
-
-The check fires on Write only — editing an existing file adds no new inventory entry — and stays quiet for a directory with no inventory document, an inventory naming too few siblings to be a maintained list, an exempt or test file, and a file the inventory already names.
-
-## Why this is a hook, not a lint pass
-
-A package inventory that omits a file reads as a complete map of the directory while leaving one file off it. A reader trusting the inventory to list the package misses the new file, and the gap survives review because the inventory still looks complete. Catching it as the new file is written keeps the inventory and the directory in step. This is the counterpart to `claude-md-orphan-file.md`, which catches the reverse drift: an inventory entry naming a file the directory does not hold.
+This is the `category-o-docstring-vs-impl-drift` (O8) orphaned-doc-claim shape applied to a package inventory.

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

@@ -1,31 +1,14 @@
 # Re-Stage Session Edits Before Commit
 
-**When this applies:** Any `git commit` run through the Bash tool in a git repository.
+Stage the files you edited this session right before you commit them. A plain `git commit` records only the staged snapshot; a tracked file this session changed but left unstaged stays behind in the working tree.
 
-## Rule
+`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.
 
-Stage the files you edited this session right before you commit them. A file this session changed but left unstaged is dropped by a plain `git commit` — the commit records the staged snapshot and the edit stays behind in the working tree.
+## Escapes the denial does not restate
 
-The `session_edit_stage_gate` hook holds you to this. It reads the per-session tracker that records every file the session edited, checks which of those files are tracked yet still unstaged at commit time, and denies the commit when any are left out. The denial names each file and gives the exact fix: `git add <paths>`, `git commit -a`, or a `# partial-commit` marker.
-
-## What the gate allows
-
-The gate steps aside for a commit that skips staged files on purpose:
-
-- **`-a` / `--all`** — the commit already takes every tracked change, so nothing is dropped.
-- **A pathspec** — `git commit -- <paths>` or `git commit <paths>` commits only the named paths on purpose.
-- **A preceding `git add` / `git stage`** — `git add <paths> && git commit …` stages the files in its own segment before the commit runs, so they are staged by the time the commit records the index.
-- **`# partial-commit`** — add this marker to the command to commit the staged set on purpose and leave the rest.
+- **A pathspec** — `git commit -- <paths>` or `git commit <paths>` commits only the named paths on purpose and steps the gate aside.
+- **A preceding `git add` / `git stage`** — `git add <paths> && git commit …` stages the files in its own segment before the commit runs.
 
 A `--amend` does not step the gate aside: an amend records the staged snapshot too, so an unstaged session edit is dropped the same way a plain commit drops it.
 
-A missing tracker file or any git failure allows the commit, so the gate never blocks on a tooling problem.
-
-## Companion hooks
-
-- `session_file_edit_tracker` (PostToolUse) records the resolved absolute path of each Write, Edit, and MultiEdit into the per-session tracker file.
-- `session_edit_tracker_cleanup` (SessionStart, SessionEnd) deletes the running session's own tracker file: at a fresh SessionStart so a new session begins with an empty record, and at SessionEnd so a clean exit leaves nothing behind. A tracker is read only by the session that wrote it, so a file a crashed session leaves behind is inert and no peer session touches it.
-
-## Why
-
-A stale git index is a quiet failure: the commit succeeds, the branch looks right, and one file you meant to include never lands. Catching it at commit time keeps the staged set and the session's edits in step.
+`session_file_edit_tracker` (PostToolUse) records each Write/Edit/MultiEdit path; `session_edit_tracker_cleanup` (SessionStart, SessionEnd) clears the session's tracker.

package/rules/shell-invocation-policy.md

@@ -2,4 +2,4 @@
 
 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`).
 
-`powershell`, `powershell.exe`, `cmd /c`, and `bash -c` are blocked by `permissions.deny` and the `pwsh_enforcer.py` PreToolUse hook, which returns the corrective pattern. Audit and migration scripts (`Audit-ShellPolicy.ps1`, `Migrate-ShellPolicy.ps1`) live in `packages/claude-dev-env/scripts/`.
+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/vault-context.md

@@ -1,7 +1,7 @@
 # Obsidian Vault Context
 
-An Obsidian vault stores session reports (`sessions/`), decisions (`decisions/`), and research (`Research/`) across projects. Resolve its location via the obsidian MCP tools — `mcp__obsidian__search_notes` (supports `searchFrontmatter: true`), `mcp__obsidian__read_note`, `mcp__obsidian__read_multiple_notes` — never assume an OS path.
+An Obsidian vault holds session reports (`sessions/`), decisions (`decisions/`), and research (`Research/`) across projects, reached through the obsidian MCP tools.
 
-IMPORTANT: Before substantive project work, search the vault for prior sessions and decisions for the current project — by `project` frontmatter first, then keywords ("blocked", "superseded", "decision", "gotcha"). Also search when touching a component with known history or when a task might repeat or reverse a prior decision.
+Before substantive project work, search the vault for prior sessions and decisions on the current project through the `recall` skill — by `project` frontmatter first, then by keyword. Search again when touching a component with known history, or when a task might repeat or reverse a prior decision.
 
-Session logging runs through `/session-log` (same full flow for short and long sessions); offer it at the end of substantive sessions. Reports include `vault_context_retrieved: true|false` and `session_id` (from `CLAUDE_CODE_SESSION_ID`; literal `unknown` when unset) in frontmatter, and every session log ends with a `/rename [Project] - [Primary Outcome]` command — mandatory output, never optional.
+At the end of a substantive session, offer the `session-log` skill; it owns the report format, the `vault_context_retrieved` and `session_id` frontmatter, and the closing `/rename` hand-off.

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

@@ -0,0 +1,28 @@
+# Verified-Commit-Gate Skip Marker
+
+**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.

package/rules/workers-done-before-complete.md

@@ -1,33 +1,5 @@
 # Workers Done Before Complete
 
-**When this applies:** Before marking any task `completed` when the task spawned workers — subagents, workflow agents, or background shells.
+Before marking a task `completed` that spawned workers — subagents, workflow agents, or background shells — confirm both: every worker has finished, and each worker's result is merged into run state (`state.json`, `pr-converge-state.json`, the task list, or whatever record the task keeps). A worker still running, or one whose output never landed in run state, keeps the task `in_progress`: list the live workers, report any dead or hung one as a finding rather than dropping it in silence, and schedule a wakeup so the run picks the workers back up before the task closes.
 
-## Rule
-
-A task reaches `completed` only when two things hold: every worker it spawned has finished, and each worker's result is merged into run state — `state.json`, `pr-converge-state.json`, the task list, or whatever record the task keeps. A worker that still runs, or one that finished but whose output never landed in run state, leaves the task open.
-
-List the live workers before you mark the task complete. When a worker is dead or hung, that is a finding to record and report, not a result to drop in silence. A step that waits on workers ends its turn `in_progress` with a wakeup scheduled, so the run picks the workers back up rather than closing the task without them.
-
-## Checklist before marking complete
-
-| Check | Action |
-|---|---|
-| Are any spawned workers still running? | List them; if yes, stay `in_progress` and schedule a wakeup. |
-| Did every finished worker return a result? | Read each result; a dead or hung worker is a finding to report. |
-| Is each result merged into run state? | Write it to `state.json` / the task list before closing. |
-| Does the task's own goal now hold? | Confirm against the merged state, not a worker's self-report. |
-
-Mark `completed` only when every row passes.
-
-## Examples
-
-**Wrong:** Marking the audit task complete while two bugteam workers still run in the background.
-**Right:** List the workers, see two still running, keep the task `in_progress`, and schedule a wakeup to collect them.
-
-**Wrong:** A worker crashes; the task closes as complete because the other workers finished.
-**Right:** Record the crashed worker as a finding, report it, and hold the task open until its work is covered.
-
-## Relationship to other rules
-
-- **`long-horizon-autonomy`** covers acting on what you have and not ending a turn on a promise. This rule names the specific completion gate: workers finished and their results merged.
-- **`skills/pr-converge/reference/state-schema.md`** defines the run-state records this rule requires a worker's result to land in before the task closes.
+Checklist, examples, and run-state detail: `@~/.claude/docs/worker-completion-gate.md`.

package/scripts/claude_chain_runner.py

@@ -19,6 +19,12 @@ A usage-limited primary falls over to the second binary::
     primary claude     -> exit 1, "usage limit reached"  (falls over)
     fallback claude-ev -> exit 0                          (served)
 
+When stdin is piped (not a TTY), the runner reads it once and forwards the
+same text to every chain attempt so a piped ``-p`` charter body reaches each
+binary in the walk::
+
+    cat charter.md | python claude_chain_runner.py -- -p --strict-mcp-config
+
 Import ``run_claude`` for the outcome object, or run the module as a CLI::
 
     python claude_chain_runner.py [--timeout-seconds N] -- <claude args...>
@@ -27,11 +33,13 @@ Import ``run_claude`` for the outcome object, or run the module as a CLI::
 from __future__ import annotations
 
 import argparse
+import io
 import json
 import subprocess
 import sys
 from dataclasses import dataclass
 from pathlib import Path
+from typing import TextIO
 
 from dev_env_scripts_constants.claude_chain_constants import (
     ALL_USAGE_LIMIT_SIGNATURES,
@@ -48,6 +56,7 @@ from dev_env_scripts_constants.claude_chain_constants import (
     CLAUDE_HOME_SUBDIRECTORY,
     CLI_ARGUMENTS_SEPARATOR,
     CLI_TIMEOUT_FLAG,
+    CODEC_ERROR_STRATEGY,
     CONFIG_CHAIN_EMPTY_REASON,
     CONFIG_CHAIN_KEY,
     CONFIG_CHAIN_NOT_LIST_REASON,
@@ -283,7 +292,10 @@ def _classify_completion(
 
 
 def run_claude(
-    all_claude_arguments: list[str], *, timeout_seconds: int
+    all_claude_arguments: list[str],
+    *,
+    timeout_seconds: int,
+    stdin_text: str | None = None,
 ) -> ChainInvocationOutcome:
     """Run *all_claude_arguments* through the configured fallback chain.
 
@@ -291,12 +303,16 @@ def run_claude(
     exit whose output carries a usage-limit signature) falls over to the next
     binary. A missing fallback binary is skipped and the walk continues. A
     timeout, a missing primary binary, or a non-zero exit without a usage-limit
-    signature stops the walk and returns that outcome unchanged.
+    signature stops the walk and returns that outcome unchanged. When
+    *stdin_text* is set, that same text is supplied as stdin on every chain
+    attempt.
 
     Args:
         all_claude_arguments: Arguments passed after the binary name, such as
             ``["-p", prompt, "--strict-mcp-config"]``.
         timeout_seconds: Timeout applied to each binary invocation.
+        stdin_text: Optional UTF-8 text forwarded as stdin to every binary.
+            ``None`` leaves the subprocess without a piped stdin body.
 
     Returns:
         The outcome of the walk, naming the serving binary and the full
@@ -315,8 +331,11 @@ def run_claude(
                 _build_invocation(each_entry, all_claude_arguments),
                 capture_output=True,
                 text=True,
+                encoding=UTF8_ENCODING,
+                errors=CODEC_ERROR_STRATEGY,
                 timeout=timeout_seconds,
                 check=False,
+                input=stdin_text,
             )
         except subprocess.TimeoutExpired as timeout_error:
             all_attempts.append(
@@ -368,6 +387,12 @@ def _exhausted_message(all_attempts: tuple[ChainAttempt, ...]) -> str:
     return CHAIN_EXHAUSTED_MESSAGE_TEMPLATE.format(attempt_summary=attempt_summary)
 
 
+def _read_piped_stdin_text() -> str | None:
+    if sys.stdin.isatty():
+        return None
+    return sys.stdin.read()
+
+
 def main(all_command_arguments: list[str]) -> int:
     """Walk the chain for CLI arguments and return the process exit code.
 
@@ -381,9 +406,12 @@ def main(all_command_arguments: list[str]) -> int:
     parser = _build_argument_parser()
     parsed_arguments = parser.parse_args(all_command_arguments)
     all_claude_arguments = _strip_leading_separator(parsed_arguments.passthrough)
+    maybe_stdin_text = _read_piped_stdin_text()
     try:
         chain_outcome = run_claude(
-            all_claude_arguments, timeout_seconds=parsed_arguments.timeout_seconds
+            all_claude_arguments,
+            timeout_seconds=parsed_arguments.timeout_seconds,
+            stdin_text=maybe_stdin_text,
         )
     except ChainConfigurationError as configuration_error:
         print(str(configuration_error), file=sys.stderr)
@@ -396,5 +424,13 @@ def main(all_command_arguments: list[str]) -> int:
     return chain_outcome.returncode
 
 
+def _reconfigure_stream_to_utf8(stream: TextIO) -> None:
+    """Reconfigure *stream* to emit UTF-8, replacing any unmappable character."""
+    if isinstance(stream, io.TextIOWrapper):
+        stream.reconfigure(encoding=UTF8_ENCODING, errors=CODEC_ERROR_STRATEGY)
+
+
 if __name__ == "__main__":
+    _reconfigure_stream_to_utf8(sys.stdout)
+    _reconfigure_stream_to_utf8(sys.stderr)
     sys.exit(main(sys.argv[1:]))

package/scripts/dev_env_scripts_constants/claude_chain_constants.py

@@ -9,6 +9,9 @@ from __future__ import annotations
 UTF8_ENCODING: str = "utf-8"
 """Encoding used to read the chain configuration file."""
 
+CODEC_ERROR_STRATEGY: str = "replace"
+"""Codec error handler that maps any unencodable or undecodable value to a marker."""
+
 CLAUDE_HOME_SUBDIRECTORY: str = ".claude"
 """Per-user directory under the home directory that holds the chain config."""