claude-dev-env 2.12.0 → 2.14.0

package/rules/AGENTS.md

@@ -0,0 +1,61 @@
+---
+paths:
+  - "**/rules/**"
+---
+
+# rules
+
+Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. A rule without `paths:` frontmatter loads at the start of every session; a rule with `paths:` frontmatter loads only when the session works with a file its globs match. The `InstructionsLoaded` log records that match as a `path_glob_match` event. Each `.md` file covers one named rule; hook-enforced rules are also backed by a Python hook in `hooks/`.
+
+## Files
+
+| File | Rule |
+|---|---|
+| `agent-spawn-protocol.md` | Check context sufficiency before a spawn and ask subagents for file-and-line answers; `/prompt-generator` is recommended for a complex or user-facing spawn |
+| `anti-corollary-tests.md` | Tests must carry information: no corollary matrices over canonical reductions, no suite that only matches a dead-implementation default, stated mutation in the audit lane |
+| `ask-user-question-required.md` | Every user-directed question goes through the `AskUserQuestion` tool — no plain-text questions |
+| `bdd.md` | BDD discovery-driven development workflow and Example Mapping reference |
+| `claims-as-quotes.md` | On agent reports, hand-offs, review verdicts, and PR or commit prose, a design-gating claim travels with its quoted lines and `path:line` reference; chat keeps research-mode compact citations; a claim without its quote is a lead to check |
+| `cleanup-temp-files.md` | Remove temporary files created during a task when the task is complete |
+| `code-standards.md` | Pointer to `CODE_RULES.md` as the single source of truth, including §8 (TDD) and §7 (right-sizing); BDD is the outer process and TDD the inner loop |
+| `confirm-implementation-forks.md` | Stop and ask when two or more workable implementation paths change the deliverable |
+| `conservative-action.md` | Research and recommend when intent is ambiguous; act only on explicit request |
+| `context7.md` | Use Context7 MCP to fetch current library docs; always prefer live docs over built-in knowledge |
+| `destructive-commands.md` | Allowed removal forms and the ephemeral namespace the `destructive_command_blocker` auto-allows; keep destructive literals out of a Bash command string even as data |
+| `doc-inventory-integrity.md` | Three inventory shapes stay in step with the code: a per-directory `CLAUDE.md` file list, a package `README`/`SKILL.md` inventory, and an env-var summary table |
+| `doc-prose-cuts.md` | Four sentence shapes to cut from prose: exclusion claims, justification sentences, conversation references, and time references |
+| `docstring-prose-matches-implementation.md` | Prose enumerations in docstrings cover every behavior the body applies |
+| `durable-post-artifacts.md` | GitHub post bodies never reference volatile scratch paths; text embeds inline and binary artifacts upload to the `artifacts` release with the permanent URL linked |
+| `eli11-replies.md` | Every chat reply the user reads follows one shape: action first, detail last, few words; `plain-language.md` governs word choice, this rule governs reply length and shape |
+| `explore-thoroughly.md` | Read relevant files and map existing patterns before proposing a change |
+| `falsify-before-green.md` | A check's green counts as evidence only after that same check ran red on a named break, with a passing control beside it |
+| `file-global-constants.md` | File-global constants need at least two same-file references; otherwise move value to `config/` |
+| `filesystem-search.md` | Every filesystem search names a scope; `es.exe`, `Glob`, `Grep`, and `Read` are equally sanctioned, and the `unscoped_search_blocker` denies a walk from a root |
+| `gh-cli-conventions.md` | `--body-file` for every `gh` body; `--paginate --slurp` piped to external `jq` for every paginated list read |
+| `git-workflow.md` | PR workflow: always create as draft, one commit per review stage, never commit working docs or images; carries the review-response protocol and a See-also block for its seven siblings |
+| `hedging-claims.md` | State the evidence or name the claim unverified; the `hedging_language_blocker` Stop hook sends a hedged response back for a re-check |
+| `long-horizon-autonomy.md` | Autonomous-run behaviors: act on what you have, do not end on a promise, delegate and keep working |
+| `measurement-denominators.md` | Every reported count names what it scanned and carries its denominator; a rate needs two runs; the consumer cross-checks the count against the scope its denominator names |
+| `nas-ssh-invocation.md` | Reach the NAS through the paramiko-backed `nas_ssh_key.py` runner, which signs in-process; every ssh-family client reads the key through file permissions, refuses it, and stalls an unattended run on a password prompt |
+| `no-cross-skill-duplicate-helpers.md` | Within one skill a duplicated helper is blocked; across two skill folders a small self-contained copy is a sanctioned isolation tradeoff that draws a non-blocking advisory naming the source skill |
+| `orphan-css-class.md` | Every `class="..."` attribute in Python-generated markup has a matching selector in the `<style>` block |
+| `opus5-communication-contract.md` | Visible concision, one-sentence first progress, important-change-only updates, outcome-first finals, thinking-disabled tool narration (`opus5-communication-contract-v1`) |
+| `paired-test-coverage.md` | A public function omitted by a module's established paired test suite must get a behavioral test |
+| `parallel-tools.md` | Make all independent tool calls in a single response |
+| `plain-illustrative-docstrings.md` | Public docstring narrative reads plainly and shows behavior with a diagram block (a `::` example or a doctest), painting a concrete scene a general developer follows on first read; a run-on backstop hook, a prose-wall backstop hook, and Category O9 audit enforce it |
+| `plain-language.md` | Everyday words, short active sentences, lead with the answer |
+| `prompt-workflow-context-controls.md` | Keep prompt-workflow instruction layers small and stable; load heavy skills on demand |
+| `re-stage-before-commit.md` | Stage the files edited this session before `git commit`; the session edit stage gate denies a commit that leaves a tracked session edit unstaged, with `-a`, a pathspec, a preceding `git add`, and `# partial-commit` as escapes |
+| `research-mode.md` | Three anti-hallucination constraints: say "I don't know", verify with citations, quote for factual grounding |
+| `shell-invocation.md` | Windows shell commands run through `pwsh`; no `$(...)`, backtick, or process substitution in a Bash tool command |
+| `testing.md` | Test quality and infrastructure standards |
+| `vault-context.md` | Search Obsidian vault for prior sessions and decisions before substantive project work |
+| `verify-before-asking.md` | Answer questions by inspecting files or running tools before asking; recalled facts expire until re-checked this session |
+| `verify-runtime-state.md` | A "component is fine / not at fault" verdict rests on a live probe this session, never code reading or prior-session memory |
+| `windows-filesystem-safe.md` | Use safe `rmtree` patterns on Windows; `mkdirSync` with `recursive: true` on possibly-existing paths |
+| `workers-done-before-complete.md` | A task reaches `completed` only when every spawned worker has finished and its results are merged into run state |
+| `workflow-substitution-slots.md` | Per-iteration values in `.workflow.js` templates use angle-bracket slots |
+
+## Hook enforcement
+
+Rules marked with ⚡ in `~/.claude/docs/CODE_RULES.md` are backed by a blocking hook in `hooks/blocking/`. Rules without a hook are judgment-based and enforced via audit rubrics (`audit-rubrics/`).

package/rules/CLAUDE.md

@@ -1,63 +1 @@
----
-paths:
-  - "**/rules/**"
----
-
-# rules
-
-Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. A rule without `paths:` frontmatter loads at the start of every session; a rule with `paths:` frontmatter loads only when the session works with a file its globs match. The `InstructionsLoaded` log records that match as a `path_glob_match` event. Each `.md` file covers one named rule; hook-enforced rules are also backed by a Python hook in `hooks/`.
-
-## Files
-
-| File | Rule |
-|---|---|
-| `agent-spawn-protocol.md` | Check context sufficiency before a spawn and ask subagents for file-and-line answers; `/prompt-generator` is recommended for a complex or user-facing spawn |
-| `anti-corollary-tests.md` | Tests must carry information: no corollary matrices over canonical reductions, no suite that only matches a dead-implementation default, stated mutation in the audit lane |
-| `ask-user-question-required.md` | Every user-directed question goes through the `AskUserQuestion` tool — no plain-text questions |
-| `bdd.md` | BDD discovery-driven development workflow and Example Mapping reference |
-| `claims-as-quotes.md` | On agent reports, hand-offs, review verdicts, and PR or commit prose, a design-gating claim travels with its quoted lines and `path:line` reference; chat keeps research-mode compact citations; a claim without its quote is a lead to check |
-| `cleanup-temp-files.md` | Remove temporary files created during a task when the task is complete |
-| `code-standards.md` | Pointer to `CODE_RULES.md` as the single source of truth, including §8 (TDD) and §7 (right-sizing); BDD is the outer process and TDD the inner loop |
-| `confirm-implementation-forks.md` | Stop and ask when two or more workable implementation paths change the deliverable |
-| `conservative-action.md` | Research and recommend when intent is ambiguous; act only on explicit request |
-| `context7.md` | Use Context7 MCP to fetch current library docs; always prefer live docs over built-in knowledge |
-| `destructive-commands.md` | Allowed removal forms and the ephemeral namespace the `destructive_command_blocker` auto-allows; keep destructive literals out of a Bash command string even as data |
-| `doc-inventory-integrity.md` | Three inventory shapes stay in step with the code: a per-directory `CLAUDE.md` file list, a package `README`/`SKILL.md` inventory, and an env-var summary table |
-| `doc-prose-cuts.md` | Four sentence shapes to cut from prose: exclusion claims, justification sentences, conversation references, and time references |
-| `docstring-prose-matches-implementation.md` | Prose enumerations in docstrings cover every behavior the body applies |
-| `durable-post-artifacts.md` | GitHub post bodies never reference volatile scratch paths; text embeds inline and binary artifacts upload to the `artifacts` release with the permanent URL linked |
-| `eli11-replies.md` | Every chat reply the user reads follows one shape: action first, detail last, few words; `plain-language.md` governs word choice, this rule governs reply length and shape |
-| `explore-thoroughly.md` | Read relevant files and map existing patterns before proposing a change |
-| `falsify-before-green.md` | A check's green counts as evidence only after that same check ran red on a named break, with a passing control beside it |
-| `file-global-constants.md` | File-global constants need at least two same-file references; otherwise move value to `config/` |
-| `filesystem-search.md` | Every filesystem search names a scope; `es.exe`, `Glob`, `Grep`, and `Read` are equally sanctioned, and the `unscoped_search_blocker` denies a walk from a root |
-| `gh-cli-conventions.md` | `--body-file` for every `gh` body; `--paginate --slurp` piped to external `jq` for every paginated list read |
-| `git-workflow.md` | PR workflow: always create as draft, one commit per review stage, never commit working docs or images; carries the review-response protocol and a See-also block for its seven siblings |
-| `hedging-claims.md` | State the evidence or name the claim unverified; the `hedging_language_blocker` Stop hook sends a hedged response back for a re-check |
-| `long-horizon-autonomy.md` | Autonomous-run behaviors: act on what you have, do not end on a promise, delegate and keep working |
-| `measurement-denominators.md` | Every reported count names what it scanned and carries its denominator; a rate needs two runs; the consumer cross-checks the count against the scope its denominator names |
-| `nas-ssh-invocation.md` | Reach the NAS through the paramiko-backed `nas_ssh_key.py` runner, which signs in-process; every ssh-family client reads the key through file permissions, refuses it, and stalls an unattended run on a password prompt |
-| `no-cross-skill-duplicate-helpers.md` | Within one skill a duplicated helper is blocked; across two skill folders a small self-contained copy is a sanctioned isolation tradeoff that draws a non-blocking advisory naming the source skill |
-| `orphan-css-class.md` | Every `class="..."` attribute in Python-generated markup has a matching selector in the `<style>` block |
-| `opus5-communication-contract.md` | Visible concision, one-sentence first progress, important-change-only updates, outcome-first finals, thinking-disabled tool narration (`opus5-communication-contract-v1`) |
-| `paired-test-coverage.md` | A public function omitted by a module's established paired test suite must get a behavioral test |
-| `parallel-tools.md` | Make all independent tool calls in a single response |
-| `plain-illustrative-docstrings.md` | Public docstring narrative reads plainly and shows behavior with a diagram block (a `::` example or a doctest), painting a concrete scene a general developer follows on first read; a run-on backstop hook, a prose-wall backstop hook, and Category O9 audit enforce it |
-| `plain-language.md` | Everyday words, short active sentences, lead with the answer |
-| `prompt-workflow-context-controls.md` | Keep prompt-workflow instruction layers small and stable; load heavy skills on demand |
-| `proof-of-work-pr-comments.md` | Every PR carries one five-part proof-of-work comment before it leaves draft; the `pr_description_enforcer` hook audits proof-shaped comments and gates `gh pr ready` |
-| `re-stage-before-commit.md` | Stage the files edited this session before `git commit`; the session edit stage gate denies a commit that leaves a tracked session edit unstaged, with `-a`, a pathspec, a preceding `git add`, and `# partial-commit` as escapes |
-| `research-mode.md` | Three anti-hallucination constraints: say "I don't know", verify with citations, quote for factual grounding |
-| `shell-invocation.md` | Windows shell commands run through `pwsh`; no `$(...)`, backtick, or process substitution in a Bash tool command |
-| `testing.md` | Test quality and infrastructure standards |
-| `vault-context.md` | Search Obsidian vault for prior sessions and decisions before substantive project work |
-| `verified-commit-gate-skip.md` | Code-verifier review is optional; commits and pushes use the checks selected for the task |
-| `verify-before-asking.md` | Answer questions by inspecting files or running tools before asking; recalled facts expire until re-checked this session |
-| `verify-runtime-state.md` | A "component is fine / not at fault" verdict rests on a live probe this session, never code reading or prior-session memory |
-| `windows-filesystem-safe.md` | Use safe `rmtree` patterns on Windows; `mkdirSync` with `recursive: true` on possibly-existing paths |
-| `workers-done-before-complete.md` | A task reaches `completed` only when every spawned worker has finished and its results are merged into run state |
-| `workflow-substitution-slots.md` | Per-iteration values in `.workflow.js` templates use angle-bracket slots |
-
-## Hook enforcement
-
-Rules marked with ⚡ in `~/.claude/docs/CODE_RULES.md` are backed by a blocking hook in `hooks/blocking/`. Rules without a hook are judgment-based and enforced via audit rubrics (`audit-rubrics/`).
+@AGENTS.md

package/rules/code-standards.md

@@ -1,6 +1,6 @@
 # Code Standards
 
-> **Canonical policy:** repository-root [`AGENTS.md`](../../../AGENTS.md) — the human and AI review contract for code quality.
+> **Checked-in review contract:** [`.cursor/BUGBOT.md`](../../../.cursor/BUGBOT.md) — the human and AI review contract for code quality.
 > **Compact projection:** [`CODE_RULES.md`](../docs/CODE_RULES.md) — validated summary for generation load.
 > **Production enforcement:** `hooks/blocking/code_rules_enforcer.py` — hand-maintained Write/Edit gates; each mechanical rule carries a synchronization test.
 
@@ -8,12 +8,12 @@
 
 | Layer | Path | Role |
 |---|---|---|
-| Canonical | `AGENTS.md` (repo root) | Full review criteria for PR agents; BugBot sync source |
+| Contract | `.cursor/BUGBOT.md` | Full review criteria for PR agents |
 | Projection | `docs/CODE_RULES.md` | Compact always-load reference; must not diverge from AGENTS |
 | Enforcer | `hooks/blocking/code_rules_enforcer.py` | Hand-maintained blockers; not generated from the docs |
 | Session rules | `rules/*.md` | Runtime session policy (questions, tasks, shell) |
 
-Load `AGENTS.md` when reviewing a PR or resolving a policy conflict. Load `CODE_RULES.md` when generating code under the compact checklist. Prefer linking these refs over restating rules.
+Load `.cursor/BUGBOT.md` when reviewing a PR or resolving a policy conflict. Load `CODE_RULES.md` when generating code under the compact checklist. Prefer linking these refs over restating rules.
 
 Two standards live in the canonical policy in full (and in the projection by name):
 
@@ -30,10 +30,6 @@ BDD is the outer process and TDD is the inner loop: [`bdd.md`](bdd.md) discovers
 | Task tracking / worker completion | [`workers-done-before-complete.md`](workers-done-before-complete.md) |
 | Multi-step task list | skill `task-build` (see agents catalog) |
 
-## Synchronization
+## Validation
 
-Mechanical enforcer coverage is checked by `tests/test_agents_policy_parity.py` and the existing `hooks/blocking/test_code_rules_enforcer*.py` suite. BugBot projection drift is checked with:
-
-```
-python .github/scripts/sync_ai_rules.py --check
-```
+Mechanical enforcer coverage is checked by the existing `hooks/blocking/test_code_rules_enforcer*.py` suite.

package/rules/doc-prose-cuts.md

@@ -51,7 +51,7 @@ After writing, ask: read a year from now by someone who knew no earlier state, d
 ## Enforcement
 
 - **Write-time.** `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.
-- **AI review.** The claude-dev-env repository's root `AGENTS.md`, the AI-review fan-out source, names the other three shapes as findings an agent applies to the `.md` lines a PR changes. No hook backs them: telling a justification sentence from a load-bearing one needs meaning a regex cannot read.
+- **AI review.** The claude-dev-env repository's `.cursor/BUGBOT.md` names the other three shapes as findings an agent applies to the `.md` lines a PR changes. Judgment-based review covers these shapes because a regex cannot read sentence meaning.
 
 ## Sibling rule
 

package/rules/gh-cli-conventions.md

@@ -24,4 +24,3 @@ Single-object endpoints (`pulls/<n>`, `issues/<n>`) skip pagination and may use
 
 - [`destructive-commands.md`](destructive-commands.md) — why a body describing `rm -rf` must travel by file path.
 - [`durable-post-artifacts.md`](durable-post-artifacts.md) — what a post body may reference.
-- [`proof-of-work-pr-comments.md`](proof-of-work-pr-comments.md) — what the proof comment must contain.

package/rules/git-workflow.md

@@ -41,7 +41,7 @@ User-level rule: applies to **every** git repo that uses GitHub with `gh` (no ex
 | `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.
+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 PR comment. The image lives on GitHub without entering the repository tree.
 
 ## Responding to review feedback
 
@@ -60,9 +60,7 @@ Repair only reported findings, then re-verify after every repair.
 | 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/scripts/AGENTS.md

@@ -0,0 +1,62 @@
+# scripts
+
+Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each script is a standalone tool a user or hook can invoke directly.
+
+## Scripts
+
+| File | Purpose |
+|---|---|
+| `claude_chain_runner.py` | Runs a `claude` invocation through a fallback chain (`~/.claude/claude-chain.json`) with `--routing-mode usage_ranked` (default: probe weekly remaining once via `claude_chain_usage` / the usage-pause OAuth probe, highest remaining first) or `ordered_account` (config list order; non-usage failures stop as `advisor_blocked`); falls over only on a usage-limit failure; returns `terminal_status` / optional `session_id` on the outcome; 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 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, refuses a spec whose `timeout_seconds` exceeds `MAXIMUM_WORKER_TIMEOUT_SECONDS` (5400) rather than clamping it, assembles each prompt from part files, optionally binds a unique worker advisor per role via the lead-supplied `advisor.launcher` (placeholder default in constants), injects `advisor_session_id`, requires the same session ENDORSE or bounded CORRECTION/PLAN then ENDORSE, classifies bind/verdict/timeout/missing-launcher failures as `advisor_blocked`, 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); 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) |
+| `active_capability_references.py` | Inventories committed skill, agent, and command names and scans package markdown for active slash or backticked capability references; fails ban-listed names outside inert historical/example fences |
+| `verify_installable_package.py` | Verifies the published package: runs real `npm pack`, checks every surface in `installable-surfaces.manifest.json` appears in the tarball, requires each `hooks.json` `.py` command to be git-tracked, and smoke-compiles those scripts (`node --check` on `bin/install.mjs`) |
+
+## PowerShell scripts
+
+| File | Purpose |
+|---|---|
+| `Audit-ShellPolicy.ps1` | Audits Bash tool calls in session transcripts against the `pwsh`-only shell policy |
+| `Migrate-ShellPolicy.ps1` | Applies automated fixes for common shell-policy violations found by the audit script |
+| `Install-SweepEmptyDirs.ps1` | Registers `sweep_empty_dirs.py` as a scheduled task on Windows |
+| `Sync-RepoMain.ps1` | Fast-forwards a main-tracking mirror (`-RepoPath`, required) to its remote main using `merge --ff-only`; refuses a different checkout or a diverged branch, logs each run to `-LogPath`, and exits non-zero so a scheduled-task history row surfaces the problem. `-StashDirty` stashes tracked changes right before the fast-forward under a dated `pre-sync stash` message and leaves the stash in the list |
+| `check.ps1` | Runs the full code-quality check suite |
+| `Get-SessionAccount.ps1` | Reports which Claude account the current session is actually logged into by comparing `~/.claude.json`'s CLI login against a `CLAUDE_USER_DATA_DIR` desktop profile's `lastKnownAccountUuid`, recovering the desktop account's email from profile storage when the two accounts differ |
+| `Capture-PoolHealth.ps1` | Captures Windows memory pool counters, high-handle processes, and kernel pool tags (via `NtQuerySystemInformation` class 22), prints a threshold verdict with a remediation map, and exits non-zero when any alert threshold fires |
+
+## Subdirectories
+
+| Entry | Description |
+|---|---|
+| `ci/` | CI-only adapters; `windows-installer-lifecycle.ps1` runs the Node installer 16-check driver under isolated HOME/USERPROFILE/GIT_CONFIG_GLOBAL and writes bounded evidence |
+| `dev_env_scripts_constants/` | Named constants (`timing.py`, `grok_worker_constants.py`, …) for scripts in this directory, including worker-advisor placeholder launcher/model/effort, four verdict signals, correction cap, and advisor timeout |
+| `profile-isolation-launchers/` | Profile-launcher contract plus MCP activation, Windows shortcut source semantics, and version preflight: profiles manifest, shared-path allowlist, profile resolver, `CLAUDE_CONFIG_DIR` authority, lean/full MCP bundle materialization into profile `mcp.json`, pure CLI/Desktop version-compatibility classifier consumed by launcher preflight, read-only shortcut inventory and preview reconcile under `windows/`. Live launcher execution, provenance pin, live shortcut mutation, and L1 deploy stay residual |
+| `sync_to_cursor/` | Package that builds Cursor `.mdc` files from Claude rules and docs |
+| `tests/` | pytest suite for the Python scripts and Pester (`*.Tests.ps1`) suite for the PowerShell scripts in this directory |
+
+## Running tests
+
+Python scripts (pytest):
+
+```bash
+python -m pytest packages/claude-dev-env/scripts/tests/
+```
+
+Profile-isolation launcher contract (node:test):
+
+```bash
+node --test packages/claude-dev-env/scripts/profile-isolation-launchers/**/*.test.mjs
+```
+
+PowerShell scripts (Pester 5+, `*.Tests.ps1`):
+
+```powershell
+Invoke-Pester -Path packages/claude-dev-env/scripts/tests/
+```

package/scripts/CLAUDE.md

@@ -1,63 +1 @@
-# scripts
-
-Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each script is a standalone tool a user or hook can invoke directly.
-
-## Scripts
-
-| File | Purpose |
-|---|---|
-| `claude_chain_runner.py` | Runs a `claude` invocation through a fallback chain (`~/.claude/claude-chain.json`) with `--routing-mode usage_ranked` (default: probe weekly remaining once via `claude_chain_usage` / the usage-pause OAuth probe, highest remaining first) or `ordered_account` (config list order; non-usage failures stop as `advisor_blocked`); falls over only on a usage-limit failure; returns `terminal_status` / optional `session_id` on the outcome; 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 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, refuses a spec whose `timeout_seconds` exceeds `MAXIMUM_WORKER_TIMEOUT_SECONDS` (5400) rather than clamping it, assembles each prompt from part files, optionally binds a unique worker advisor per role via the lead-supplied `advisor.launcher` (placeholder default in constants), injects `advisor_session_id`, requires the same session ENDORSE or bounded CORRECTION/PLAN then ENDORSE, classifies bind/verdict/timeout/missing-launcher failures as `advisor_blocked`, 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); 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) |
-| `active_capability_references.py` | Inventories committed skill, agent, and command names and scans package markdown for active slash or backticked capability references; fails ban-listed names outside inert historical/example fences |
-| `verify_installable_package.py` | Verifies the published package: runs real `npm pack`, checks every surface in `installable-surfaces.manifest.json` appears in the tarball, requires each `hooks.json` `.py` command to be git-tracked, and smoke-compiles those scripts (`node --check` on `bin/install.mjs`) |
-
-## PowerShell scripts
-
-| File | Purpose |
-|---|---|
-| `Audit-ShellPolicy.ps1` | Audits Bash tool calls in session transcripts against the `pwsh`-only shell policy |
-| `Migrate-ShellPolicy.ps1` | Applies automated fixes for common shell-policy violations found by the audit script |
-| `Install-SweepEmptyDirs.ps1` | Registers `sweep_empty_dirs.py` as a scheduled task on Windows |
-| `Sync-RepoMain.ps1` | Fast-forwards a main-tracking mirror (`-RepoPath`, required) to its remote main using `merge --ff-only`; refuses a different checkout or a diverged branch, logs each run to `-LogPath`, and exits non-zero so a scheduled-task history row surfaces the problem. `-StashDirty` stashes tracked changes right before the fast-forward under a dated `pre-sync stash` message and leaves the stash in the list |
-| `check.ps1` | Runs the full code-quality check suite |
-| `Show-Asset.ps1` | Opens files on screen, sizing each image window to the image's pixel dimensions (scaled to fit the screen); non-image files open in their default application |
-| `Get-SessionAccount.ps1` | Reports which Claude account the current session is actually logged into by comparing `~/.claude.json`'s CLI login against a `CLAUDE_USER_DATA_DIR` desktop profile's `lastKnownAccountUuid`, recovering the desktop account's email from profile storage when the two accounts differ |
-| `Capture-PoolHealth.ps1` | Captures Windows memory pool counters, high-handle processes, and kernel pool tags (via `NtQuerySystemInformation` class 22), prints a threshold verdict with a remediation map, and exits non-zero when any alert threshold fires |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `ci/` | CI-only adapters; `windows-installer-lifecycle.ps1` runs the Node installer 16-check driver under isolated HOME/USERPROFILE/GIT_CONFIG_GLOBAL and writes bounded evidence |
-| `dev_env_scripts_constants/` | Named constants (`timing.py`, `grok_worker_constants.py`, …) for scripts in this directory, including worker-advisor placeholder launcher/model/effort, four verdict signals, correction cap, and advisor timeout |
-| `profile-isolation-launchers/` | Profile-launcher contract plus MCP activation, Windows shortcut source semantics, and version preflight: profiles manifest, shared-path allowlist, profile resolver, `CLAUDE_CONFIG_DIR` authority, lean/full MCP bundle materialization into profile `mcp.json`, pure CLI/Desktop version-compatibility classifier consumed by launcher preflight, read-only shortcut inventory and preview reconcile under `windows/`. Live launcher execution, provenance pin, live shortcut mutation, and L1 deploy stay residual |
-| `sync_to_cursor/` | Package that builds Cursor `.mdc` files from Claude rules and docs |
-| `tests/` | pytest suite for the Python scripts and Pester (`*.Tests.ps1`) suite for the PowerShell scripts in this directory |
-
-## Running tests
-
-Python scripts (pytest):
-
-```bash
-python -m pytest packages/claude-dev-env/scripts/tests/
-```
-
-Profile-isolation launcher contract (node:test):
-
-```bash
-node --test packages/claude-dev-env/scripts/profile-isolation-launchers/**/*.test.mjs
-```
-
-PowerShell scripts (Pester 5+, `*.Tests.ps1`):
-
-```powershell
-Invoke-Pester -Path packages/claude-dev-env/scripts/tests/
-```
+@AGENTS.md

package/scripts/_code_review_test_support.py

@@ -35,7 +35,6 @@ from dev_env_scripts_constants.code_review_constants import (  # noqa: E402
     CLI_SESSION_MODEL_FLAG,
     CODE_REVIEW_MODEL_ALIAS,
     GIT_BINARY,
-    RECORD_STAMP_FLAG,
 )
 from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
     CLI_TIMEOUT_FLAG,
@@ -108,19 +107,6 @@ def write_dirty_tree(working_directory: Path) -> None:
     dirty_file.write_text(DIRTY_FILE_CONTENTS, encoding="utf-8")
 
 
-def run_record_stamp_cli(working_directory: Path, *, effort: str) -> int:
-    return invoker.main(
-        [
-            CWD_FLAG,
-            str(working_directory),
-            CLI_SESSION_MODEL_FLAG,
-            CODE_REVIEW_MODEL_ALIAS,
-            RECORD_STAMP_FLAG,
-            effort,
-        ]
-    )
-
-
 def claude_served(
     *,
     returncode: int = FIXTURE_CHAIN_RETURNCODE,
@@ -327,84 +313,3 @@ def install_seams(
 EFFORT_LOW = "low"
 REJECTED_ULTRA_EFFORT = "ultra"
 SINGLE_PASS_CAP = 1
-MISSING_STORE_FILE_NAME = "code_review_stamp_store_absent.py"
-SURFACE_SOURCE = "def add(left: int, right: int) -> int:\n    return left + right\n"
-SURFACE_CHANGE_SOURCE = (
-    "def add(left: int, right: int) -> int:\n    return left - right\n"
-)
-
-
-def _make_repo_with_change_surface(tmp_path: Path) -> Path:
-    origin_directory = tmp_path / "origin.git"
-    work_directory = tmp_path / "work"
-    _run_git(
-        "init",
-        "--bare",
-        "--initial-branch",
-        PINNED_INITIAL_BRANCH,
-        str(origin_directory),
-    )
-    _initialize_repository(work_directory)
-    (work_directory / "app.py").write_text(SURFACE_SOURCE, encoding="utf-8")
-    _run_git("add", "-A", working_directory=work_directory)
-    _run_git("commit", "-m", "base", working_directory=work_directory)
-    _run_git(
-        "remote",
-        "add",
-        "origin",
-        str(origin_directory),
-        working_directory=work_directory,
-    )
-    _run_git(
-        "push", "-u", "origin", PINNED_INITIAL_BRANCH, working_directory=work_directory
-    )
-    (work_directory / "app.py").write_text(SURFACE_CHANGE_SOURCE, encoding="utf-8")
-    return work_directory
-
-
-def _isolate_home(monkeypatch: pytest.MonkeyPatch, fake_home: Path) -> None:
-    home_text = str(fake_home)
-    monkeypatch.setenv("HOME", home_text)
-    monkeypatch.setenv("USERPROFILE", home_text)
-    monkeypatch.delenv("HOMEDRIVE", raising=False)
-    monkeypatch.delenv("HOMEPATH", raising=False)
-
-
-def prepared_surface_repo(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path:
-    fake_home = tmp_path / "home"
-    fake_home.mkdir()
-    _isolate_home(monkeypatch, fake_home)
-    return _make_repo_with_change_surface(tmp_path)
-
-
-def _chain_clean_outcome() -> invoker.CodeReviewOutcome:
-    return invoker.CodeReviewOutcome(
-        mode=invoker.MODE_CHAIN,
-        served_command=FIXTURE_SERVED_COMMAND,
-        returncode=FIXTURE_CHAIN_RETURNCODE,
-        is_dirty_tree=True,
-    )
-
-
-def stable_clean_review(**_review_keywords: object) -> invoker.CodeReviewOutcome:
-    return _chain_clean_outcome()
-
-
-def surface_changing_review(
-    *, working_directory: Path, **_review_keywords: object
-) -> invoker.CodeReviewOutcome:
-    write_dirty_tree(working_directory)
-    return _chain_clean_outcome()
-
-
-class DriftingReview:
-    def __init__(self) -> None:
-        self.pass_count = 0
-
-    def __call__(
-        self, *, working_directory: Path, **_review_keywords: object
-    ) -> invoker.CodeReviewOutcome:
-        self.pass_count += 1
-        drift_path = working_directory / f"fix_{self.pass_count}.txt"
-        drift_path.write_text(str(self.pass_count), encoding="utf-8")
-        return _chain_clean_outcome()

package/scripts/codex_compat_materializer.py

@@ -26,6 +26,7 @@ manifest_indentation_width = 2
 publish_plan_max_positional_arguments = 3
 publish_plan_failure_injector_position = 2
 frontmatter_unsupported_fields = ("tools", "model", "color")
+instruction_alias_filenames = frozenset({"AGENTS.md", "CLAUDE.md"})
 full_prune_opt_in_flag = "--allow-prune-all"
 unreadable_source_root_message = (
     "source root is missing or is not a directory, so nothing was planned or changed; "
@@ -430,6 +431,9 @@ def discover_agents(config: MaterializerConfig) -> list[ClaudeAgent]:
         raise MaterializerError(f"{reparse_source_root_message}: {config.source_root}")
     all_agents: list[ClaudeAgent] = []
     for each_path in sorted(config.source_root.rglob("*.md"), key=lambda path: path.as_posix().casefold()):
+        if each_path.name in instruction_alias_filenames:
+            _validate_containment(config.source_root, each_path)
+            continue
         if _is_reparse_point(each_path):
             raise MaterializerError(f"source reparse point is not allowed: {each_path}")
         relative_source = each_path.relative_to(config.source_root).as_posix()

package/scripts/dev_env_scripts_constants/AGENTS.md

@@ -0,0 +1,21 @@
+# dev_env_scripts_constants
+
+Named constants for scripts in `scripts/`. Follows the project convention that timeouts, delays, and retries live in `timing.py`.
+
+## Modules
+
+| File | Constants for |
+|---|---|
+| `timing.py` | `sweep_empty_dirs.py` - `DEFAULT_AGE_SECONDS` (smallest age before an empty directory is eligible for removal) and `DEFAULT_POLL_INTERVAL` (seconds between sweep passes in continuous-watch mode); `spawn_grok_batch.py` - `WORKER_STAGGER_SECONDS` (seconds between staggered headless grok worker starts); `invoke_code_review.py` - `DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS` (timeout for one headless `/code-review` chain run) |
+| `gh_artifact_upload_constants.py` | `gh_artifact_upload.py` - the `artifacts` release tag, title, and notes body, the GitHub CLI binary name, the asset-name timestamp format and template, the asset download URL template, the notes-file suffix, and the text encoding |
+| `claude_chain_constants.py` | `claude_chain_runner.py` - the chain config filename and home subdirectory, the usage-limit signature text, the per-binary status labels, routing-mode tokens (`usage_ranked` / `ordered_account`), outcome `terminal_status` values (`served` / `advisor_blocked` / `chain_exhausted` / `timeout`), the default timeout, CLI flag and separator tokens, config JSON keys (including optional `credentials_path`), invalid-shape reason text, config-error and exhausted-chain message templates, and CLI exit codes (including advisor-blocked); `invoke_code_review.py` and `resolve_worker_spawn.py` - the text-codec keyword names and the `collect_forwarded_text_codec` helper that forwards them to the subprocess runner for text-mode capture |
+| `claude_chain_usage_constants.py` | `claude_chain_usage.py` - full weekly percent scale, usage-pause skill path segments, CLI config-path flag, JSON report keys, and probe error message templates |
+| `grok_worker_constants.py` | `grok_worker_preflight.py`, `grok_headless_runner.py`, `spawn_grok_batch.py`, and `resolve_worker_spawn.py` - the `grok` binary name and CLI flags, model and subcommand tokens, leader-socket and scratch-file name parts, auth and usage-limit signature lists, outcome classifications, fallthrough reasons, tool-profile names and prompt headers, worker timeouts (default, plus the floor and the `MAXIMUM_WORKER_TIMEOUT_SECONDS` ceiling that the batch spec parse, the headless runner, and the spawn dispatcher all enforce, each bound carrying one rejection template shared by those sites, plus launch-failure return code and post-kill grace), the process-tree kill attempt limit and kill-failed classification, the preflight ping's single-turn cap, ping-cache keys and TTL, batch-spec and summary JSON keys, worker-advisor placeholder launcher/model/effort tokens, four verdict signals, MAXIMUM_WORKER_ADVISOR_CORRECTIONS, advisor_blocked classification, and advisor_session_id report keys, the prompt-part and report-stream join separators, and the CLI launch-error stderr prefix |
+| `code_review_constants.py` | `invoke_code_review.py` - the `/code-review ultra --fix` prompt, opus model alias, permission-mode flag and value, result mode and JSON keys, session-model CLI flag, git dirty-check tokens, and in-session return markers; finding severity tokens (`blocker` / `high` / `medium` / `low` / `nit`), verification verdict tokens, loop terminal tokens (`clean` / `nits_fixed` / `advisor_blocked`), and pure helpers for retained-finding checks, head recording, terminal resolution, and terminal encoding |
+| `active_capability_constants.py` | `active_capability_references.py` - package skills/agents/commands directory names, skill manifest filename, ban-listed capability names, inert fence languages, slash and backtick extract patterns, fence open/close patterns, banned-reason prefix, UTF-8 encoding, and newline join separator |
+| `verify_installable_package_constants.py` | `verify_installable_package.py` - manifest filename and keys, npm pack / tarball / plugin-root tokens, git and node smoke argv pieces, surface classification labels, exit codes, and CLI status headers |
+| `__init__.py` | Empty package marker |
+
+## Convention
+
+Every constant is `UPPER_SNAKE_CASE` with an explicit type annotation and a docstring. Scripts import from here rather than embedding literal values in their bodies. `code_review_constants.py` also exports pure helpers that resolve review-loop terminals from those tokens.

package/scripts/dev_env_scripts_constants/CLAUDE.md

@@ -1,21 +1 @@
-# dev_env_scripts_constants
-
-Named constants for scripts in `scripts/`. Follows the project convention that timeouts, delays, and retries live in `timing.py`.
-
-## Modules
-
-| File | Constants for |
-|---|---|
-| `timing.py` | `sweep_empty_dirs.py` - `DEFAULT_AGE_SECONDS` (smallest age before an empty directory is eligible for removal) and `DEFAULT_POLL_INTERVAL` (seconds between sweep passes in continuous-watch mode); `spawn_grok_batch.py` - `WORKER_STAGGER_SECONDS` (seconds between staggered headless grok worker starts); `invoke_code_review.py` - `DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS` (timeout for one headless `/code-review` chain run) |
-| `gh_artifact_upload_constants.py` | `gh_artifact_upload.py` - the `artifacts` release tag, title, and notes body, the GitHub CLI binary name, the asset-name timestamp format and template, the asset download URL template, the notes-file suffix, and the text encoding |
-| `claude_chain_constants.py` | `claude_chain_runner.py` - the chain config filename and home subdirectory, the usage-limit signature text, the per-binary status labels, routing-mode tokens (`usage_ranked` / `ordered_account`), outcome `terminal_status` values (`served` / `advisor_blocked` / `chain_exhausted` / `timeout`), the default timeout, CLI flag and separator tokens, config JSON keys (including optional `credentials_path`), invalid-shape reason text, config-error and exhausted-chain message templates, and CLI exit codes (including advisor-blocked); `invoke_code_review.py` and `resolve_worker_spawn.py` - the text-codec keyword names and the `collect_forwarded_text_codec` helper that forwards them to the subprocess runner for text-mode capture |
-| `claude_chain_usage_constants.py` | `claude_chain_usage.py` - full weekly percent scale, usage-pause skill path segments, CLI config-path flag, JSON report keys, and probe error message templates |
-| `grok_worker_constants.py` | `grok_worker_preflight.py`, `grok_headless_runner.py`, `spawn_grok_batch.py`, and `resolve_worker_spawn.py` - the `grok` binary name and CLI flags, model and subcommand tokens, leader-socket and scratch-file name parts, auth and usage-limit signature lists, outcome classifications, fallthrough reasons, tool-profile names and prompt headers, worker timeouts (default, plus the floor and the `MAXIMUM_WORKER_TIMEOUT_SECONDS` ceiling that the batch spec parse, the headless runner, and the spawn dispatcher all enforce, each bound carrying one rejection template shared by those sites, plus launch-failure return code and post-kill grace), the process-tree kill attempt limit and kill-failed classification, the preflight ping's single-turn cap, ping-cache keys and TTL, batch-spec and summary JSON keys, worker-advisor placeholder launcher/model/effort tokens, four verdict signals, MAXIMUM_WORKER_ADVISOR_CORRECTIONS, advisor_blocked classification, and advisor_session_id report keys, the prompt-part and report-stream join separators, and the CLI launch-error stderr prefix |
-| `code_review_constants.py` | `invoke_code_review.py` - the `/code-review ultra --fix` prompt, opus model alias, permission-mode flag and value, result mode and JSON keys, session-model CLI flag, git dirty-check tokens, and in-session return markers; finding severity tokens (`blocker` / `high` / `medium` / `low` / `nit`), verification verdict tokens, loop terminal tokens (`clean` / `nits_fixed` / `advisor_blocked`), and pure helpers for retained-finding checks, head recording, terminal resolution, and terminal encoding |
-| `active_capability_constants.py` | `active_capability_references.py` - package skills/agents/commands directory names, skill manifest filename, ban-listed capability names, inert fence languages, slash and backtick extract patterns, fence open/close patterns, banned-reason prefix, UTF-8 encoding, and newline join separator |
-| `verify_installable_package_constants.py` | `verify_installable_package.py` - manifest filename and keys, npm pack / tarball / plugin-root tokens, git and node smoke argv pieces, surface classification labels, exit codes, and CLI status headers |
-| `__init__.py` | Empty package marker |
-
-## Convention
-
-Every constant is `UPPER_SNAKE_CASE` with an explicit type annotation and a docstring. Scripts import from here rather than embedding literal values in their bodies. `code_review_constants.py` also exports pure helpers that resolve review-loop terminals from those tokens.
+@AGENTS.md