claude-dev-env 2.5.0 → 2.7.1

package/rules/git-workflow.md

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

package/rules/hedging-claims.md

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

package/rules/long-horizon-autonomy.md

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

package/rules/measurement-denominators.md

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

package/rules/nas-ssh-invocation.md

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

package/rules/parallel-tools.md

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

package/rules/plain-illustrative-docstrings.md

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

package/rules/plain-language.md

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

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

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

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

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

package/rules/research-mode.md

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

package/rules/shell-invocation.md

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

package/rules/testing.md

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

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

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

package/rules/verify-before-asking.md

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

package/rules/windows-filesystem-safe.md

@@ -14,4 +14,4 @@ In Node, call `mkdirSync(targetPath, { recursive: true })` on possibly-existing
 
 The `windows_rmtree_blocker.py` PreToolUse hook (Write/Edit/Bash) blocks the unsafe rmtree pattern and returns the full `force_rmtree` safe-pattern code.
 
-Define the safe handler trio (`_strip_read_only_and_retry`, `_force_remove_tree` / `force_rmtree`, and the `inspect.signature` onexc/onerror guard) once in a shared Windows-filesystem utility module, and import it from every call site. A second local copy drifts from the first — a fix lands in one and the other keeps the bug (CODE_RULES.md section 3, Reuse before create). The `duplicate_rmtree_helper_blocker.py` PreToolUse hook (Write/Edit) blocks a local re-definition of any trio member outside the shared home and points the writer at the import. This complements the same-directory `check_duplicate_function_body_across_files` gate, which a copy between two distant packages slips past.
+Define the safe handler trio (`_strip_read_only_and_retry`, `_force_remove_tree` / `force_rmtree`, and the `inspect.signature` onexc/onerror guard) once in a shared Windows-filesystem utility module, and import it from every call site. A second local copy drifts from the first — a fix lands in one and the other keeps the bug (CODE_RULES.md, CORE PRINCIPLES — "Reuse before create"). The `duplicate_rmtree_helper_blocker.py` PreToolUse hook (Write/Edit) blocks a local re-definition of any trio member outside the shared home and points the writer at the import. This complements the same-directory `check_duplicate_function_body_across_files` gate, which a copy between two distant packages slips past.

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

@@ -2,4 +2,8 @@
 
 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.
 
+This rule gates a task's status, not your own work. It never says wait before acting: keep working while a worker runs, and hold only the `completed` mark until the worker's result has landed.
+
+Verify every sub-agent file list, count, description, and finding against the repository and the diff before you merge it into run state or repeat it to the user.
+
 Checklist, examples, and run-state detail: `@~/.claude/docs/worker-completion-gate.md`.

package/scripts/CLAUDE.md

@@ -9,13 +9,13 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 | `claude_chain_runner.py` | Runs a `claude` invocation through a usage-ranked fallback chain (`~/.claude/claude-chain.json`): probes weekly remaining once via `claude_chain_usage` / the usage-pause OAuth probe, tries the highest-remaining account first, and falls over to the next ranked binary only on a usage-limit failure; usable as an imported module (`run_claude`) or a CLI. Copy `claude-chain.example.json` to `~/.claude/claude-chain.json` and list your account binaries. Optional per-entry `credentials_path` names that account's OAuth credentials file for the usage probe |
 | `claude_chain_usage.py` | Reports remaining weekly usage for every account in `~/.claude/claude-chain.json` via the usage-pause OAuth probe; prints JSON (`accounts` with `weekly_remaining_percent` or null plus `error`); importable `report_chain_weekly_usage` and `rank_accounts_by_weekly_remaining` (highest remaining first, ties keep config order, unmeasurable last). The chain runner consumes this ranking for try order |
 | `gh_artifact_upload.py` | Uploads a file to a repo's durable `artifacts` prerelease under a timestamped asset name and prints the permanent download URL a GitHub post can link |
-| `grok_headless_runner.py` | Runs one worker as headless `grok`: builds argv, mints a unique leader socket, captures streams, kills on timeout with grace, classifies ok/usage_limit/auth_failure/timeout/error; imported by `spawn_grok_batch.py` |
+| `grok_headless_runner.py` | Runs one worker as headless `grok`: builds argv with no turn cap (the timeout is the only bound), mints a unique leader socket, captures streams, refuses a timeout that is missing, below `MIN_WORKER_TIMEOUT_SECONDS`, or above the `MAXIMUM_WORKER_TIMEOUT_SECONDS` (5400) ceiling, kills the whole process tree on timeout with grace and retries the kill-and-drain round once, classifies ok/usage_limit/auth_failure/timeout/kill_failed/error; exports `require_timeout_within_bounds` so a dispatcher can apply the same bounds without launching; imported by `spawn_grok_batch.py` and `resolve_worker_spawn.py` |
 | `grok_worker_preflight.py` | Soft gate for the headless grok tier: binary on PATH, `grok models` auth, install manifest + role agents, opt-in cached live ping; non-zero exit is fallthrough, not failure |
 | `setup_project_paths.py` | One-time bootstrap: discovers git repos via `es.exe` (Everything) and writes `~/.claude/project-paths.json`; never hardcodes scan roots |
-| `spawn_grok_batch.py` | Launches a fleet of headless grok workers from a JSON batch spec: gates once through the preflight, assembles each prompt from part files, staggers starts, runs each through `grok_headless_runner.py`, and emits one batch summary JSON |
+| `spawn_grok_batch.py` | Launches a fleet of headless grok workers from a JSON batch spec: gates once through the preflight, refuses a spec whose `timeout_seconds` exceeds `MAXIMUM_WORKER_TIMEOUT_SECONDS` (5400) rather than clamping it, assembles each prompt from part files, staggers starts, runs each through `grok_headless_runner.py`, and emits one batch summary JSON |
 | `sweep_empty_dirs.py` | Deletes empty directories older than a configurable age under a given root; runs once (`--once`) or in continuous-watch mode |
 | `sync_to_cursor.py` | Entry point for syncing Claude rules to Cursor `.mdc` files; delegates to the `sync_to_cursor/` package |
-| `resolve_worker_spawn.py` | Dispatches a worker role through grok then claude fallback tiers (preflight, headless grok, `claude_agent_required` handoff, optional claude headless); protocol: [`../_shared/pr-loop/worker-spawn.md`](../_shared/pr-loop/worker-spawn.md) |
+| `resolve_worker_spawn.py` | Dispatches a worker role through grok then claude fallback tiers (preflight, headless grok, `claude_agent_required` handoff, optional claude headless); applies `require_timeout_within_bounds` before the preflight, so an out-of-bounds `--timeout-seconds` prints a `timeout_out_of_bounds` outcome and exits 3 on every tier; protocol: [`../_shared/pr-loop/worker-spawn.md`](../_shared/pr-loop/worker-spawn.md) |
 
 ## PowerShell scripts
 

package/scripts/Migrate-ShellPolicy.ps1

@@ -9,7 +9,7 @@
     settings.local.json, and settings.local.json.template, and rewrites permission
     rule strings that invoke powershell / powershell.exe / bash -c / cmd /c
     into their pwsh equivalents per the migration mapping in
-    rules/shell-invocation-policy.md. Defaults to dry-run; pass -Apply to write
+    rules/shell-invocation.md. Defaults to dry-run; pass -Apply to write
     changes. Prints exactly one summary line.
 
 .PARAMETER Roots

package/scripts/codex_capability_bridge.py

@@ -0,0 +1,171 @@
+"""Translate Claude capability requests into declarative Codex records."""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+class CapabilityArgumentError(ValueError):
+    """Raised when bridge command-line input cannot be translated."""
+
+
+class CapabilityArgumentParser(argparse.ArgumentParser):
+    """Parse bridge arguments while keeping failures inside the JSON contract."""
+
+    def error(self, message: str) -> None:
+        raise CapabilityArgumentError(f"invalid bridge arguments: {message}")
+
+
+def _load_capability_map() -> dict[str, object]:
+    capability_map_path = Path(__file__).resolve().parents[1] / "codex-capability-map.json"
+    with capability_map_path.open(encoding="utf-8") as map_file:
+        return json.load(map_file)
+
+
+def _build_error_record(source_surface: str, message: str) -> dict[str, object]:
+    return {"source": source_surface, "status": "error", "error": message}
+
+
+def _parse_command_arguments() -> argparse.Namespace:
+    argument_parser = CapabilityArgumentParser()
+    argument_parser.add_argument("source_surface")
+    argument_parser.add_argument("payload_json", nargs="?")
+    return argument_parser.parse_args()
+
+
+def _read_payload(payload_json: str) -> object:
+    try:
+        return json.loads(payload_json)
+    except json.JSONDecodeError as payload_error:
+        raise CapabilityArgumentError("payload must be valid JSON") from payload_error
+
+
+def _capability_by_surface() -> dict[str, dict[str, object]]:
+    all_capabilities = _load_capability_map()["capabilities"]
+    capability_by_surface: dict[str, dict[str, object]] = {}
+    for each_capability in all_capabilities:
+        capability_by_surface[each_capability["source"].casefold()] = each_capability
+        for each_alias in each_capability["aliases"]:
+            capability_by_surface[each_alias.casefold()] = each_capability
+    return capability_by_surface
+
+
+def _contains_unsafe_path(all_capability_payload: object) -> bool:
+    path_pattern = re.compile(
+        r"(?:^[A-Za-z]:[\\/]|^\\\\|^/|^~(?:[\\/]|$)|^(?:%[^%]+%|\$\{?[A-Za-z_][A-Za-z0-9_]*\}?)(?:[\\/]|$)|(?:^|[\\/])(?:Users|home|\.ssh|\.codex)(?:[\\/]|$)|(?:^|[\\/])\.\.(?:[\\/]|$))",
+        re.IGNORECASE,
+    )
+    if isinstance(all_capability_payload, str):
+        return bool(path_pattern.search(all_capability_payload))
+    if isinstance(all_capability_payload, dict):
+        return any(_contains_unsafe_path(each_payload_entry) for each_payload_entry in all_capability_payload.values())
+    if isinstance(all_capability_payload, list):
+        return any(_contains_unsafe_path(each_payload_entry) for each_payload_entry in all_capability_payload)
+    return False
+
+
+def _status_by_source() -> dict[str, str]:
+    return {"pending": "pending", "queued": "pending", "in_progress": "in_progress", "in-progress": "in_progress", "active": "in_progress", "completed": "completed", "complete": "completed", "done": "completed"}
+
+
+def _task_plan_entry(all_capability_payload: dict[str, object]) -> dict[str, str] | None:
+    task_name = all_capability_payload.get("subject", all_capability_payload.get("name", all_capability_payload.get("title")))
+    task_status = all_capability_payload.get("status", "pending")
+    status_by_source = _status_by_source()
+    if not isinstance(task_name, str) or not task_name.strip():
+        return None
+    if not isinstance(task_status, str) or task_status.casefold() not in status_by_source:
+        return None
+    return {"step": task_name, "status": status_by_source[task_status.casefold()]}
+
+
+def _has_required_fields(all_capability_payload: dict[str, object], all_required_field_definitions: dict[str, str]) -> bool:
+    status_by_source = _status_by_source()
+    for each_required_field_name, each_required_field_schema in all_required_field_definitions.items():
+        required_field_content = all_capability_payload.get(each_required_field_name)
+        if each_required_field_schema == "string" and (not isinstance(required_field_content, str) or not required_field_content.strip()):
+            return False
+        if each_required_field_schema == "status" and (not isinstance(required_field_content, str) or required_field_content.casefold() not in status_by_source):
+            return False
+    return True
+
+
+def _has_valid_plan(all_capability_payload: dict[str, object]) -> bool:
+    all_task_entries = all_capability_payload.get("plan")
+    return isinstance(all_task_entries, list) and all(isinstance(each_task_entry, dict) and _task_plan_entry(each_task_entry) is not None for each_task_entry in all_task_entries)
+
+
+def translate_capability(source_surface: str, payload: object) -> dict[str, object]:
+    """Translate one capability request into a deterministic declarative record.
+
+    The dispatcher selects a mapped target, rejects unsafe or malformed payloads,
+    conditionally dispatches TaskList plans through ``_has_valid_plan``, and emits
+    manual-review records for unsupported scheduling requests.
+
+    Args:
+        source_surface: Claude capability name or configured alias.
+        payload: JSON-compatible request payload.
+
+    Returns:
+        A declarative translation record that never executes the target action.
+    """
+    capability = _capability_by_surface().get(source_surface.casefold())
+    if capability is None:
+        return {"source": source_surface, "status": "unknown", "error": "unknown source surface"}
+    if _contains_unsafe_path(payload):
+        return {"source": capability["source"], "status": "rejected", "error": "path-bearing payload is not allowed"}
+    if not isinstance(payload, dict):
+        return {"source": capability["source"], "status": "malformed", "error": "payload must be a JSON object"}
+    if capability["status"] == "unsupported":
+        return {"source": capability["source"], "target": None, "status": "unsupported", "manual_review": True, "error": "scheduling is unavailable"}
+    if capability["target"] == "update_plan":
+        if capability["source"] == "TaskList":
+            if not _has_valid_plan(payload):
+                return {"source": capability["source"], "status": "malformed", "error": "TaskList requires a plan of named tasks"}
+            return {"source": capability["source"], "target": capability["target"], "transformation": "snapshot", "payload": {"plan": payload["plan"]}, "manual_review": True, "status": "mapped"}
+        task_plan_entry = _task_plan_entry(payload)
+        if task_plan_entry is None:
+            return {"source": capability["source"], "status": "malformed", "error": "task requires a name and supported status"}
+        operation = "status mutation" if capability["source"] == "TaskUpdate" else "replace-plan-item" if payload.get("operation") == "replace" else "append"
+        return {"source": capability["source"], "target": capability["target"], "transformation": operation, "payload": {"plan": [task_plan_entry]}, "status": "mapped"}
+    all_required_field_definitions = capability.get("required_fields", {})
+    if not isinstance(all_required_field_definitions, dict) or not _has_required_fields(payload, all_required_field_definitions):
+        return {"source": capability["source"], "status": "malformed", "error": "payload is missing required fields"}
+    return {"source": capability["source"], "target": capability["target"], "transformation": capability["transformation"], "payload": payload, "manual_review": capability["manual_review"], "status": "mapped"}
+
+
+def main() -> int:
+    """Dispatch a command-line request and print its JSON translation record.
+
+    The dispatcher reads an optional payload argument or stdin, translates it
+    through the public capability dispatcher, and emits JSON.
+
+    Args:
+        None. Command-line arguments are read from the process argument vector.
+
+    Returns:
+        Zero after the translation record is written.
+    """
+    try:
+        command_arguments = _parse_command_arguments()
+        payload_json = command_arguments.payload_json or sys.stdin.read()
+        capability_payload = _read_payload(payload_json)
+        translated_record = translate_capability(command_arguments.source_surface, capability_payload)
+        all_translation_error_statuses = ("unknown", "rejected", "malformed")
+        if translated_record["status"] in all_translation_error_statuses:
+            print(json.dumps(translated_record, sort_keys=True, separators=(",", ":")))
+            return 2
+        print(json.dumps(translated_record, sort_keys=True, separators=(",", ":")))
+        return 0
+    except CapabilityArgumentError as argument_error:
+        print(json.dumps(_build_error_record("unknown", str(argument_error)), separators=(",", ":")))
+        return 2
+    except (OSError, KeyError, TypeError, json.JSONDecodeError) as configuration_error:
+        print(json.dumps(_build_error_record("unknown", f"bridge configuration error: {configuration_error}"), separators=(",", ":")))
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())