claude-dev-env 2.0.0 → 2.0.2

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/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."""
 

package/scripts/test_claude_chain_runner.py

@@ -1,6 +1,7 @@
 """Behavioral tests for the claude fallback-chain runner."""
 
 import json
+import os
 import subprocess
 import sys
 from pathlib import Path
@@ -78,20 +79,32 @@ class _Recorder:
         self.behavior_by_command = behavior_by_command
         self.invocations = []
         self.timeouts = []
+        self.all_keyword_arguments = []
 
     def __call__(self, invocation, **keyword_arguments):
         self.invocations.append(invocation)
         self.timeouts.append(keyword_arguments.get("timeout"))
+        self.all_keyword_arguments.append(keyword_arguments)
         behavior = self.behavior_by_command[invocation[0]]
         if isinstance(behavior, BaseException):
             raise behavior
         return behavior
 
 
+class _TtyStdin:
+    def isatty(self) -> bool:
+        return True
+
+
+def _install_tty_stdin(monkeypatch):
+    monkeypatch.setattr(runner.sys, "stdin", _TtyStdin())
+
+
 def _install(monkeypatch, config_file, behavior_by_command):
     recorder = _Recorder(behavior_by_command)
     monkeypatch.setattr(runner, "chain_config_path", lambda: config_file)
     monkeypatch.setattr(runner, "chain_subprocess_runner", recorder)
+    _install_tty_stdin(monkeypatch)
     return recorder
 
 
@@ -276,6 +289,45 @@ def test_extra_args_are_appended_to_invocation(
     assert recorder.invocations[0] == ["claude", "-p", "hello", "--account", "ev"]
 
 
+def test_run_claude_forwards_stdin_text_to_subprocess(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude")])
+    recorder = _install(monkeypatch, config_file, {"claude": _completed("claude", 0)})
+    runner.run_claude(
+        _PROMPT_ARGUMENTS, timeout_seconds=5, stdin_text="charter body"
+    )
+    assert recorder.all_keyword_arguments[0]["input"] == "charter body"
+
+
+def test_run_claude_passes_none_input_when_stdin_text_omitted(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude")])
+    recorder = _install(monkeypatch, config_file, {"claude": _completed("claude", 0)})
+    runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert recorder.all_keyword_arguments[0].get("input") is None
+
+
+def test_cli_forwards_piped_stdin_to_invocation(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude")])
+    recorder = _install(monkeypatch, config_file, {"claude": _completed("claude", 0)})
+
+    class _PipedStdin:
+        def isatty(self) -> bool:
+            return False
+
+        def read(self) -> str:
+            return "charter body"
+
+    monkeypatch.setattr(runner.sys, "stdin", _PipedStdin())
+    exit_code = runner.main([CLI_ARGUMENTS_SEPARATOR, "-p", "hi"])
+    assert exit_code == 0
+    assert recorder.all_keyword_arguments[0]["input"] == "charter body"
+
+
 def test_signature_matching_is_case_insensitive(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
@@ -362,6 +414,7 @@ def test_cli_missing_config_exits_config_error(
 ) -> None:
     missing_config = tmp_path / CONFIG_FILENAME
     monkeypatch.setattr(runner, "chain_config_path", lambda: missing_config)
+    _install_tty_stdin(monkeypatch)
     exit_code = runner.main([CLI_ARGUMENTS_SEPARATOR, "-p", "hi"])
     captured = capsys.readouterr()
     assert exit_code == CHAIN_CONFIG_ERROR_EXIT_CODE
@@ -470,3 +523,62 @@ def test_chain_config_path_points_at_home_config() -> None:
     config_path = runner.chain_config_path()
     assert config_path.name == CONFIG_FILENAME
     assert CLAUDE_HOME_SUBDIRECTORY in config_path.parts
+
+
+def test_real_subprocess_capture_replaces_undecodable_bytes(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry(sys.executable)])
+    monkeypatch.setattr(runner, "chain_config_path", lambda: config_file)
+    child_code = 'import sys; sys.stdout.buffer.write(b"ok \\x90 end")'
+    chain_result = runner.run_claude(["-c", child_code], timeout_seconds=60)
+    assert chain_result.served_command == sys.executable
+    assert chain_result.returncode == 0
+    assert chain_result.stdout == "ok � end"
+
+
+def test_real_subprocess_capture_preserves_utf8_text(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry(sys.executable)])
+    monkeypatch.setattr(runner, "chain_config_path", lambda: config_file)
+    child_code = 'import sys; sys.stdout.buffer.write("report ✅ done".encode("utf-8"))'
+    chain_result = runner.run_claude(["-c", child_code], timeout_seconds=60)
+    assert chain_result.served_command == sys.executable
+    assert chain_result.returncode == 0
+    assert chain_result.stdout == "report ✅ done"
+
+
+def test_cli_emits_utf8_when_console_encoding_is_legacy(tmp_path: Path) -> None:
+    tmp_home = tmp_path / "home"
+    claude_directory = tmp_home / CLAUDE_HOME_SUBDIRECTORY
+    claude_directory.mkdir(parents=True)
+    config_file = claude_directory / CONFIG_FILENAME
+    config_file.write_text(
+        json.dumps({CONFIG_CHAIN_KEY: [_entry(sys.executable)]}),
+        encoding=UTF8_ENCODING,
+    )
+    runner_script = _SCRIPTS_DIR / "claude_chain_runner.py"
+    child_code = 'import sys; sys.stdout.buffer.write("report ✅".encode("utf-8"))'
+    legacy_console_encoding = "cp1252"
+    child_environment = dict(os.environ)
+    child_environment["USERPROFILE"] = str(tmp_home)
+    child_environment["HOME"] = str(tmp_home)
+    child_environment["PYTHONIOENCODING"] = legacy_console_encoding
+    child_environment.pop("PYTHONUTF8", None)
+    runner_command = [
+        sys.executable,
+        str(runner_script),
+        CLI_ARGUMENTS_SEPARATOR,
+        "-c",
+        child_code,
+    ]
+    completed = subprocess.run(
+        runner_command,
+        capture_output=True,
+        env=child_environment,
+        timeout=60,
+    )
+    assert completed.returncode == 0
+    assert b"Traceback" not in completed.stderr
+    assert "report ✅" in completed.stdout.decode(UTF8_ENCODING)

package/scripts/test_grok_headless_runner.py

@@ -418,7 +418,6 @@ def test_tightened_auth_phrases_still_classify_auth_failure(
         assert outcome.classification == CLASSIFICATION_AUTH_FAILURE, each_stderr
 
 
-def test_dual_match_prefers_auth_failure_over_usage_limit(
 def test_missing_binary_returns_dedicated_error(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:

package/skills/auditing-claude-config/SKILL.md

@@ -31,7 +31,7 @@ These come from the official Claude Code documentation; do not re-derive them.
 | Files in `.claude/rules/` without `paths:` frontmatter load **every** session | "Rules without `paths` frontmatter are loaded unconditionally and apply to all files" |
 | Path-scoped rules load **lazily** when matching files are accessed | "Rules can be scoped to specific files using YAML frontmatter with the `paths` field. These conditional rules only apply when Claude is working with files matching the specified patterns" |
 | Skills preload **metadata only** | "At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed" |
-| `@`-imports inside fenced/inline code blocks do not trigger imports | Empirical (verified in this skill's source session) — referenced files alongside backtick-wrapped `@` paths do not appear in session-start context |
+| `@`-imports inside fenced/inline code blocks do not trigger imports | Empirical (`InstructionsLoaded` hook): a bare `@`-import fires an `include` load event; the same path wrapped in backticks fires none, so the referenced file stays out of session-start context |
 
 ## Audit workflow