claude-dev-env 2.13.0 → 2.14.0

package/rules/CLAUDE.md

@@ -1,61 +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 |
-| `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/`).
+@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/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,62 +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 |
-| `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/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

package/scripts/sync_to_cursor/AGENTS.md

@@ -0,0 +1,23 @@
+# sync_to_cursor
+
+Python package that syncs Claude rules and docs to Cursor `.mdc` files. Entry point is `packages/claude-dev-env/scripts/sync_to_cursor.py`; this package holds the implementation modules.
+
+## Modules
+
+| File | Purpose |
+|---|---|
+| `engine.py` | Main sync logic: loads the manifest, builds rule mappings, hashes sources, writes `.mdc` files, and updates the manifest |
+| `rules.py` | Builds `RuleMapping` objects from Claude rule markdown files; applies transforms to fit Cursor's `.mdc` format |
+| `canonical_docs.py` | Checks and syncs canonical documentation files (`CODE_RULES.md`, `TEST_QUALITY.md`) to the Cursor rules directory |
+| `paths.py` | Resolves the Claude and Cursor layout paths; respects the `LLM_SETTINGS_ROOT` env var for non-home layouts |
+| `hashing.py` | SHA-256 helpers that detect whether source files changed since the last sync run |
+| `config.py` | Package-level constants: `GENERATOR_VERSION`, `CANONICAL_DOC_FILES`, `MAX_RULE_BODY_LINES` |
+| `__init__.py` | Empty package marker |
+
+## Layout resolution
+
+`paths.py` reads `LLM_SETTINGS_ROOT` from the environment. When set, it uses that path as the base for both `.claude/` and `.cursor/`. When unset, it falls back to `Path.home()`.
+
+## Tests
+
+Tests live in `packages/claude-dev-env/scripts/tests/test_sync_to_cursor.py`.

package/scripts/sync_to_cursor/CLAUDE.md

@@ -1,23 +1 @@
-# sync_to_cursor
-
-Python package that syncs Claude rules and docs to Cursor `.mdc` files. Entry point is `packages/claude-dev-env/scripts/sync_to_cursor.py`; this package holds the implementation modules.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `engine.py` | Main sync logic: loads the manifest, builds rule mappings, hashes sources, writes `.mdc` files, and updates the manifest |
-| `rules.py` | Builds `RuleMapping` objects from Claude rule markdown files; applies transforms to fit Cursor's `.mdc` format |
-| `canonical_docs.py` | Checks and syncs canonical documentation files (`CODE_RULES.md`, `TEST_QUALITY.md`) to the Cursor rules directory |
-| `paths.py` | Resolves the Claude and Cursor layout paths; respects the `LLM_SETTINGS_ROOT` env var for non-home layouts |
-| `hashing.py` | SHA-256 helpers that detect whether source files changed since the last sync run |
-| `config.py` | Package-level constants: `GENERATOR_VERSION`, `CANONICAL_DOC_FILES`, `MAX_RULE_BODY_LINES` |
-| `__init__.py` | Empty package marker |
-
-## Layout resolution
-
-`paths.py` reads `LLM_SETTINGS_ROOT` from the environment. When set, it uses that path as the base for both `.claude/` and `.cursor/`. When unset, it falls back to `Path.home()`.
-
-## Tests
-
-Tests live in `packages/claude-dev-env/scripts/tests/test_sync_to_cursor.py`.
+@AGENTS.md

package/scripts/test_validate_instruction_pairs.py

@@ -0,0 +1,90 @@
+import subprocess
+from pathlib import Path
+
+from validate_instruction_pairs import validate_repository
+
+
+def initialize_repository(repository_root: Path) -> None:
+    subprocess.run(["git", "init", "--quiet"], cwd=repository_root, check=True)
+    subprocess.run(
+        ["git", "config", "user.email", "tests@example.com"],
+        cwd=repository_root,
+        check=True,
+    )
+    subprocess.run(
+        ["git", "config", "user.name", "Instruction tests"],
+        cwd=repository_root,
+        check=True,
+    )
+
+
+def stage_instruction_files(repository_root: Path) -> None:
+    subprocess.run(["git", "add", "AGENTS.md", "CLAUDE.md"], cwd=repository_root, check=True)
+
+
+def test_exact_import_passes(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    (tmp_path / "AGENTS.md").write_bytes(b"# Canonical guidance\n")
+    (tmp_path / "CLAUDE.md").write_bytes(b"@AGENTS.md\n")
+    stage_instruction_files(tmp_path)
+
+    assert validate_repository(tmp_path) == []
+
+
+def test_claude_context_fails_exact_import_check(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    (tmp_path / "AGENTS.md").write_bytes(b"# Canonical guidance\n")
+    (tmp_path / "CLAUDE.md").write_bytes(b"@AGENTS.md\n\nExtra context\n")
+    stage_instruction_files(tmp_path)
+
+    all_errors = validate_repository(tmp_path)
+
+    assert any("exactly import" in each_error for each_error in all_errors)
+
+
+def test_nearest_ancestor_import_passes(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    nested_directory = tmp_path / ".claude"
+    nested_directory.mkdir()
+    (tmp_path / "AGENTS.md").write_bytes(b"# Canonical guidance\n")
+    (nested_directory / "CLAUDE.md").write_bytes(b"@../AGENTS.md\n")
+    subprocess.run(["git", "add", "AGENTS.md", ".claude/CLAUDE.md"], cwd=tmp_path, check=True)
+
+    assert validate_repository(tmp_path) == []
+
+
+def test_crlf_import_fails_line_ending_check(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    (tmp_path / "AGENTS.md").write_bytes(b"# Canonical guidance\n")
+    (tmp_path / "CLAUDE.md").write_bytes(b"@AGENTS.md\r\n")
+    stage_instruction_files(tmp_path)
+
+    all_errors = validate_repository(tmp_path)
+
+    assert any("exactly import" in each_error for each_error in all_errors)
+
+
+def test_executable_import_fails_git_mode_check(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    (tmp_path / "AGENTS.md").write_bytes(b"# Canonical guidance\n")
+    (tmp_path / "CLAUDE.md").write_bytes(b"@AGENTS.md\n")
+    stage_instruction_files(tmp_path)
+    subprocess.run(
+        ["git", "update-index", "--chmod=+x", "CLAUDE.md"],
+        cwd=tmp_path,
+        check=True,
+    )
+
+    all_errors = validate_repository(tmp_path)
+
+    assert any("Git mode 100644" in each_error for each_error in all_errors)
+
+
+def test_untracked_import_fails_tracking_check(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    (tmp_path / "AGENTS.md").write_bytes(b"# Canonical guidance\n")
+    (tmp_path / "CLAUDE.md").write_bytes(b"@AGENTS.md\n")
+
+    all_errors = validate_repository(tmp_path)
+
+    assert any("Git mode 100644" in each_error for each_error in all_errors)

package/scripts/test_verify_installable_package.py

@@ -31,6 +31,7 @@ def test_load_manifest_lists_hooks_and_claude_md() -> None:
     all_root_files = mod.required_root_file_names(manifest)
     assert "hooks" in all_directories
     assert "output-styles" in all_directories
+    assert "AGENTS.md" in all_root_files
     assert "CLAUDE.md" in all_root_files
     assert MANIFEST_FILENAME in all_root_files
 
@@ -58,10 +59,12 @@ def test_surface_appears_in_tarball_members_for_directory_children() -> None:
     all_members = frozenset(
         {
             f"{TARBALL_PACKAGE_PREFIX}hooks/hooks.json",
+            f"{TARBALL_PACKAGE_PREFIX}AGENTS.md",
             f"{TARBALL_PACKAGE_PREFIX}CLAUDE.md",
         }
     )
     assert mod.surface_appears_in_tarball_members("hooks", all_members)
+    assert mod.surface_appears_in_tarball_members("AGENTS.md", all_members)
     assert mod.surface_appears_in_tarball_members("CLAUDE.md", all_members)
     assert not mod.surface_appears_in_tarball_members("missing-dir", all_members)
 
@@ -69,11 +72,12 @@ def test_surface_appears_in_tarball_members_for_directory_children() -> None:
 def test_missing_manifest_surfaces_in_tarball_reports_absent_root_file() -> None:
     manifest = {
         "directories": ["hooks"],
-        "root_files": ["CLAUDE.md", "codex-capability-map.json"],
+        "root_files": ["AGENTS.md", "CLAUDE.md", "codex-capability-map.json"],
     }
     all_members = frozenset(
         {
             f"{TARBALL_PACKAGE_PREFIX}hooks/hooks.json",
+            f"{TARBALL_PACKAGE_PREFIX}AGENTS.md",
             f"{TARBALL_PACKAGE_PREFIX}CLAUDE.md",
         }
     )

package/scripts/tests/AGENTS.md

@@ -0,0 +1,33 @@
+# scripts/tests
+
+pytest suite for the Python scripts and Pester suite for the PowerShell scripts in `scripts/`.
+
+## Test files
+
+| File | Covers |
+|---|---|
+| `test_setup_project_paths.py` | `setup_project_paths.py` — discovery, filtering, and `project-paths.json` writing |
+| `test_setup_project_paths_config.py` | Configuration constants used by `setup_project_paths.py` |
+| `test_sweep_empty_dirs.py` | `sweep_empty_dirs.py` — age check, one-shot mode, and continuous-watch behavior |
+| `test_sync_to_cursor.py` | `sync_to_cursor/` package — mapping, hashing, manifest, and path resolution |
+| `test_grok_worker_constants.py` | `grok_worker_constants.py` — the accepted batch worker-key set stays in step with the worker key constants, and the unknown-key message names both its placeholders |
+
+## PowerShell test files
+
+| File | Covers |
+|---|---|
+| `Get-SessionAccount.Tests.ps1` | `Get-SessionAccount.ps1` — noise filtering, profile-storage email recovery, CLI-vs-desktop account resolution, and output formatting |
+
+## Running
+
+Python scripts (pytest):
+
+```bash
+python -m pytest packages/claude-dev-env/scripts/tests/
+```
+
+PowerShell scripts (Pester 5+, `*.Tests.ps1`):
+
+```powershell
+Invoke-Pester -Path packages/claude-dev-env/scripts/tests/
+```

package/scripts/tests/CLAUDE.md

@@ -1,33 +1 @@
-# scripts/tests
-
-pytest suite for the Python scripts and Pester suite for the PowerShell scripts in `scripts/`.
-
-## Test files
-
-| File | Covers |
-|---|---|
-| `test_setup_project_paths.py` | `setup_project_paths.py` — discovery, filtering, and `project-paths.json` writing |
-| `test_setup_project_paths_config.py` | Configuration constants used by `setup_project_paths.py` |
-| `test_sweep_empty_dirs.py` | `sweep_empty_dirs.py` — age check, one-shot mode, and continuous-watch behavior |
-| `test_sync_to_cursor.py` | `sync_to_cursor/` package — mapping, hashing, manifest, and path resolution |
-| `test_grok_worker_constants.py` | `grok_worker_constants.py` — the accepted batch worker-key set stays in step with the worker key constants, and the unknown-key message names both its placeholders |
-
-## PowerShell test files
-
-| File | Covers |
-|---|---|
-| `Get-SessionAccount.Tests.ps1` | `Get-SessionAccount.ps1` — noise filtering, profile-storage email recovery, CLI-vs-desktop account resolution, and output formatting |
-
-## Running
-
-Python scripts (pytest):
-
-```bash
-python -m pytest packages/claude-dev-env/scripts/tests/
-```
-
-PowerShell scripts (Pester 5+, `*.Tests.ps1`):
-
-```powershell
-Invoke-Pester -Path packages/claude-dev-env/scripts/tests/
-```
+@AGENTS.md

package/scripts/tests/test_codex_compat_materializer.py

@@ -77,6 +77,42 @@ def test_discover_agents_returns_sorted_parsed_agents(tmp_path: Path) -> None:
     assert [agent.name for agent in agents] == ["Alpha", "Zulu"]
 
 
+def test_discover_agents_skips_instruction_aliases_and_keeps_real_agents(
+    tmp_path: Path,
+) -> None:
+    source = tmp_path / "source"
+    source.mkdir()
+    (source / "real-agent.md").write_text(
+        "---\nname: Real Agent\ndescription: real\n---\n",
+        encoding="utf-8",
+    )
+    (source / "CLAUDE.md").write_text("# Guidance\n", encoding="utf-8")
+    try:
+        (source / "AGENTS.md").symlink_to("CLAUDE.md")
+    except OSError as error:
+        pytest.skip(f"symlinks unavailable: {error}")
+
+    agents = materializer.discover_agents(MaterializerConfig(source, tmp_path / "target"))
+
+    assert [agent.name for agent in agents] == ["Real Agent"]
+
+
+def test_discover_agents_rejects_non_alias_reparse_points(tmp_path: Path) -> None:
+    source = tmp_path / "source"
+    source.mkdir()
+    (source / "real-agent.md").write_text(
+        "---\nname: Real Agent\ndescription: real\n---\n",
+        encoding="utf-8",
+    )
+    try:
+        (source / "linked-agent.md").symlink_to("real-agent.md")
+    except OSError as error:
+        pytest.skip(f"symlinks unavailable: {error}")
+
+    with pytest.raises(MaterializerError, match="source reparse point is not allowed"):
+        materializer.discover_agents(MaterializerConfig(source, tmp_path / "target"))
+
+
 def test_content_to_bytes_preserves_bytes_and_encodes_text() -> None:
     assert content_to_bytes(b"payload") == b"payload"
     assert content_to_bytes("payload") == b"payload"
@@ -662,4 +698,3 @@ def test_frontmatter_rejects_non_string_name() -> None:
             "---\nname: 1\ndescription: y\n---\n",
             "bad.md",
         )
-