claude-dev-env 2.13.0 → 2.14.0

package/_shared/process-tree/CLAUDE.md

@@ -1,41 +1 @@
-# _shared/process-tree
-
-One home for ending a spawned process together with every descendant it
-started. Callers that capture a CLI's output import it so a grandchild can
-never outlive the run and hold the capture pipe open.
-
-## Consumers
-
-| Caller | Use |
-|---|---|
-| `scripts/grok_headless_runner.py` | Kills a timed-out worker's tree between drain attempts |
-| `skills/codex-review/scripts/run_codex_review.py` | Kills the review tree on timeout, then drains |
-| `skills/codex-review/scripts/codex_usage_probe.py` | Tears the app-server tree down after the rate-limits exchange |
-
-A skill script reaches this home the way the bugteam scripts reach
-`_shared/pr-loop/scripts`: it puts the directory on `sys.path` and imports by
-module name. `bin/install.mjs` copies `_shared` and `scripts` together, and
-every install group that carries a consumer carries `_shared`, so the import
-resolves in the repository and under `~/.claude` alike.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `scripts/process_tree_kill.py` | `terminate_process_tree` (poll, platform tree kill, re-poll, `Popen.kill()` fallback), `kill_process_tree_by_identifier`, and `should_start_new_session` for the matching `Popen` flag |
-| `scripts/test_process_tree_kill.py` | Behavioral tests for every public entry point here, each platform branch, each failure the helper swallows, and the `Popen.kill()` fallback |
-| `scripts/config/process_tree_scripts_constants/process_tree_kill_constants.py` | The taskkill command, its `/T`, `/F`, and `/PID` flags, and the bound on the kill command |
-| `scripts/pyproject.toml` | mypy configuration; `check.ps1` runs it under the `mypy-process-tree` label |
-
-## Platform guard
-
-Both the branch selector and the POSIX helper compare `sys.platform` against
-the literal `"win32"`. That literal is what mypy narrows on: behind a named
-constant, `os.getpgid`, `os.killpg`, and `signal.SIGKILL` fail type checking on
-Windows.
-
-## Pairing rule
-
-`os.killpg` signals a whole process group, so a child sharing the caller's
-group takes the caller down with it. Every `Popen` whose tree this module ends
-passes `start_new_session=should_start_new_session()`.
+@AGENTS.md

package/agents/AGENTS.md

@@ -0,0 +1,31 @@
+# agents
+
+Agent definition files installed into `~/.claude/agents/` by `bin/install.mjs`. Each `.md` file defines a named subagent: its description (shown in the Claude Code UI), allowed tools, and behavioral instructions.
+
+## Agent files
+
+| File | Agent name | Role |
+|---|---|---|
+| `caveman.md` | Caveman Agent | Terse voice and smallest-possible artifacts; questions premise before building |
+| `clasp-deployment-orchestrator.md` | Clasp Deployment Orchestrator | Creates and deploys Google Apps Script projects with multiple files |
+| `clean-coder.md` | Clean Coder | Primary code-writing agent; links the review contract, CODE_RULES, and enforcer; task-local discovery and gate-clean first writes |
+| `code-advisor.md` | Code Advisor | Single-executor mid-run advisor (PLAN/CORRECTION/STOP as final text); distinct from session-advisor |
+| `code-quality-agent.md` | Code Quality Agent | Multi-file code quality review across an entire diff or set of files |
+| `deep-research.md` | Deep Research | Citation-grounded research with web search |
+| `docs-agent.md` | Docs Agent | Documentation authoring and maintenance |
+| `git-commit-crafter.md` | Git Commit Crafter | Stages changes, writes conventional commit messages, creates commits |
+| `issue-tracker.md` | Issue Tracker | Primary handler for one GitHub issue action per spawn; loads the issue-tracker skill (plain-brief); returns issue numbers and URLs |
+| `plan-packet-validator.md` | Plan Packet Validator | Fresh-context validator for workflow-generated plan packets under `docs/plans/` |
+| `pr-description-writer.md` | PR Description Writer | Drafts PR descriptions and comments from the current diff using the canonical description and comment guides |
+| `session-advisor.md` | Session Advisor | Standing multi-consumer reviewer; SendMessage only; returns endorse/correction/plan/stop |
+| `skill-writer-agent.md` | Skill Writer Agent | Authors SKILL.md and companion files to skill-builder conventions; caller-agnostic authoring specialist |
+
+## Format
+
+Each file uses YAML frontmatter (`name`, `description`, `tools`, optional `color`) followed by a Markdown body with the agent's behavioral instructions. The `description` field appears in the Claude Code agent picker. An agent definition carries no `model` key — the caller supplies the model on each spawn.
+
+## Adding an agent
+
+1. Create a new `.md` file in this directory with valid frontmatter.
+2. Run `bin/install.mjs` to copy it to `~/.claude/agents/`.
+3. Restart Claude Code to pick up the new agent.

package/agents/CLAUDE.md

@@ -1,31 +1 @@
-# agents
-
-Agent definition files installed into `~/.claude/agents/` by `bin/install.mjs`. Each `.md` file defines a named subagent: its description (shown in the Claude Code UI), allowed tools, and behavioral instructions.
-
-## Agent files
-
-| File | Agent name | Role |
-|---|---|---|
-| `caveman.md` | Caveman Agent | Terse voice and smallest-possible artifacts; questions premise before building |
-| `clasp-deployment-orchestrator.md` | Clasp Deployment Orchestrator | Creates and deploys Google Apps Script projects with multiple files |
-| `clean-coder.md` | Clean Coder | Primary code-writing agent; links AGENTS.md / CODE_RULES / enforcer; task-local discovery and gate-clean first writes |
-| `code-advisor.md` | Code Advisor | Single-executor mid-run advisor (PLAN/CORRECTION/STOP as final text); distinct from session-advisor |
-| `code-quality-agent.md` | Code Quality Agent | Multi-file code quality review across an entire diff or set of files |
-| `deep-research.md` | Deep Research | Citation-grounded research with web search |
-| `docs-agent.md` | Docs Agent | Documentation authoring and maintenance |
-| `git-commit-crafter.md` | Git Commit Crafter | Stages changes, writes conventional commit messages, creates commits |
-| `issue-tracker.md` | Issue Tracker | Primary handler for one GitHub issue action per spawn; loads the issue-tracker skill (plain-brief); returns issue numbers and URLs |
-| `plan-packet-validator.md` | Plan Packet Validator | Fresh-context validator for workflow-generated plan packets under `docs/plans/` |
-| `pr-description-writer.md` | PR Description Writer | Drafts PR descriptions and comments from the current diff using the canonical description and comment guides |
-| `session-advisor.md` | Session Advisor | Standing multi-consumer reviewer; SendMessage only; returns endorse/correction/plan/stop |
-| `skill-writer-agent.md` | Skill Writer Agent | Authors SKILL.md and companion files to skill-builder conventions; caller-agnostic authoring specialist |
-
-## Format
-
-Each file uses YAML frontmatter (`name`, `description`, `tools`, optional `color`) followed by a Markdown body with the agent's behavioral instructions. The `description` field appears in the Claude Code agent picker. An agent definition carries no `model` key — the caller supplies the model on each spawn.
-
-## Adding an agent
-
-1. Create a new `.md` file in this directory with valid frontmatter.
-2. Run `bin/install.mjs` to copy it to `~/.claude/agents/`.
-3. Restart Claude Code to pick up the new agent.
+@AGENTS.md

package/agents/clean-coder.md

@@ -1,15 +1,15 @@
 ---
 name: clean-coder
-description: "Use PROACTIVELY for ALL code generation — features, fixes, refactors, hooks, automation, and any task that produces code. Links repo-root AGENTS.md and the CODE_RULES / enforcer / rules map; task-local discovery; high-signal gotchas so write gates pass on the first attempt."
+description: "Use PROACTIVELY for ALL code generation — features, fixes, refactors, hooks, automation, and any task that produces code. Links the project review contract and the CODE_RULES / enforcer / rules map; task-local discovery; high-signal gotchas so write gates pass on the first attempt."
 tools: Read, Write, Edit, Bash, Grep, Glob, Task, Skill, SendMessage
 color: green
 ---
 
 # Clean Coder — Zero-Defect Code Generation
 
-You are the definitive code-writing agent. You produce code so clean that reviewers find nothing. **Canonical policy is repository-root `AGENTS.md` when present.** `../docs/CODE_RULES.md` is its compact projection; `../hooks/blocking/code_rules_enforcer.py` is hand-maintained write-time enforcement. Do not restate those rules with divergent wording — link them.
+You are the definitive code-writing agent. You produce code so clean that reviewers find nothing. **Use the repository's checked-in review contract when present.** `../docs/CODE_RULES.md` is its compact projection; `../hooks/blocking/code_rules_enforcer.py` is hand-maintained write-time enforcement. Link these references and keep their wording authoritative.
 
-**Announce at start:** "Using clean-coder agent — AGENTS.md / CODE_RULES via canonical refs."
+**Announce at start:** "Using clean-coder agent — review contract / CODE_RULES via canonical refs."
 
 ## First Action (MANDATORY)
 
@@ -39,7 +39,7 @@ Paths are relative to this agent file (`agents/`).
 
 | Concern | Canonical source |
 |---|---|
-| Full review criteria | Repo-root `AGENTS.md` (when the target repo has one) |
+| Full review criteria | Project review contract (when the target repo provides one) |
 | Compact generation checklist | `../docs/CODE_RULES.md` |
 | Write-time gates | `../hooks/blocking/code_rules_enforcer.py` |
 | Policy surface map | `../rules/code-standards.md` |
@@ -47,7 +47,7 @@ Paths are relative to this agent file (`agents/`).
 | Windows rmtree / mkdir | `../rules/windows-filesystem-safe.md` |
 | `gh` body files | `../rules/gh-cli-conventions.md` |
 | Plain illustrative docstrings | `../rules/plain-illustrative-docstrings.md` |
-| TDD / right-size | `AGENTS.md` Tests + Design; `CODE_RULES.md` §7–§8 |
+| TDD / right-size | Review contract Tests + Design; `CODE_RULES.md` §7–§8 |
 
 Type-ignore rule (AGENTS Types): a `# type: ignore` needs a second trailing `#` justification of at least five characters. Prefer a real type when available.
 
@@ -88,7 +88,7 @@ def fetch_with_retries(url: str) -> str:
 ## Scope, TDD, and outcomes
 
 - **Scope:** only lines the task needs. Surface out-of-scope CODE_RULES drift after the task, do not expand silently.
-- **TDD:** when tests are in scope, red → green → refactor (`AGENTS.md` Tests / `CODE_RULES` §8).
+- **TDD:** when tests are in scope, red → green → refactor (review contract Tests / `CODE_RULES` §8).
 - **Outcome:** code that passes `/check` and the write gates on the first write; self-documenting names; paired tests for new production paths.
 
 ## When to use this agent

package/agents/test_agent_frontmatter.py

@@ -79,7 +79,7 @@ import pytest
 import yaml
 
 ACCEPTED_FRONTMATTER_KEYS = frozenset({"name", "description", "tools", "color"})
-EXEMPT_MARKDOWN_FILENAME = "CLAUDE.md"
+INSTRUCTION_ALIAS_FILENAMES = frozenset({"AGENTS.md", "CLAUDE.md"})
 FRONTMATTER_FENCE_LINE = "---"
 MATERIALIZER_MODULE_NAME = "codex_compat_materializer"
 MATERIALIZER_MODULE_PATH = (
@@ -113,20 +113,20 @@ def _extract_frontmatter_block(markdown_text: str) -> str | None:
 
 @cache
 def _agent_definition_candidate_paths() -> tuple[Path, ...]:
-    """Return every markdown file in this directory that must be a definition.
+    """Return every markdown file in this directory that is an agent definition.
 
     This is the floor the parametrized checks are measured against: each of
     these files is expected to yield a frontmatter block, so one that does not
     is a broken definition rather than a file to pass over.
 
     Returns:
-        Every `*.md` path in this directory except the exempt one, sorted.
+        Every agent-definition `*.md` path in this directory, sorted.
     """
     agents_directory = Path(__file__).parent
     return tuple(
         each_markdown_file
         for each_markdown_file in sorted(agents_directory.glob("*.md"))
-        if each_markdown_file.name != EXEMPT_MARKDOWN_FILENAME
+        if each_markdown_file.name not in INSTRUCTION_ALIAS_FILENAMES
     )
 
 

package/audit-rubrics/AGENTS.md

@@ -0,0 +1,43 @@
+# audit-rubrics
+
+Audit rubrics for the PR-loop code-review suite. The rubrics define the 17 bug categories (A–Q), their sub-bucket decompositions, and the prompt templates agents use during an audit pass. Installed into `~/.claude/audit-rubrics/` by `bin/install.mjs`.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `audit-categories.json` | Machine-readable A-Q schema: id, title, slug, and sub-bucket id/axis pairs; single source for rubric and prompt skeleton parity |
+| `source-material-section-types.md` | Lookup table for how to chunk an artifact into sections for an audit prompt; covers code PRs, docs, SQL schemas, config files, and more |
+
+## Subdirectories
+
+| Entry | Description |
+|---|---|
+| `category_rubrics/` | One `.md` per category (A–Q): defines what the category audits, example findings, and a sub-bucket decomposition table |
+| `prompts/` | One `.md` per category: the ready-to-use audit prompt template an agent inlines the artifact into |
+
+## Categories
+
+| ID | Name |
+|---|---|
+| A | API contract verification |
+| B | Selector engine compatibility |
+| C | Resource cleanup |
+| D | Scoping and ordering |
+| E | Dead code |
+| F | Silent failures |
+| G | Bounds and overflow |
+| H | Security boundaries |
+| I | Concurrency |
+| J | Code-rules compliance |
+| K | Codebase conflicts |
+| L | Behavior equivalence |
+| M | Producer-consumer cardinality |
+| N | Test name / scenario verifier |
+| O | Docstring vs implementation drift |
+| P | Name vs behavior contract |
+| Q | Cross-surface claim consistency |
+
+## Breaking-change rule
+
+Adding a sub-bucket to a category rubric requires updating `audit-categories.json` and the matching prompt template in `prompts/` in the same commit, then running `audit_category_schema.py --validate`. Skills that reference category IDs (`bugteam`, `findbugs`) rely on stable sub-bucket IDs (A1, A2, … Q-n). Worked examples stay in the rubric markdown only; they are outside the schema.

package/audit-rubrics/CLAUDE.md

@@ -1,43 +1 @@
-# audit-rubrics
-
-Audit rubrics for the PR-loop code-review suite. The rubrics define the 17 bug categories (A–Q), their sub-bucket decompositions, and the prompt templates agents use during an audit pass. Installed into `~/.claude/audit-rubrics/` by `bin/install.mjs`.
-
-## Key file
-
-| File | Purpose |
-|---|---|
-| `audit-categories.json` | Machine-readable A-Q schema: id, title, slug, and sub-bucket id/axis pairs; single source for rubric and prompt skeleton parity |
-| `source-material-section-types.md` | Lookup table for how to chunk an artifact into sections for an audit prompt; covers code PRs, docs, SQL schemas, config files, and more |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `category_rubrics/` | One `.md` per category (A–Q): defines what the category audits, example findings, and a sub-bucket decomposition table |
-| `prompts/` | One `.md` per category: the ready-to-use audit prompt template an agent inlines the artifact into |
-
-## Categories
-
-| ID | Name |
-|---|---|
-| A | API contract verification |
-| B | Selector engine compatibility |
-| C | Resource cleanup |
-| D | Scoping and ordering |
-| E | Dead code |
-| F | Silent failures |
-| G | Bounds and overflow |
-| H | Security boundaries |
-| I | Concurrency |
-| J | Code-rules compliance |
-| K | Codebase conflicts |
-| L | Behavior equivalence |
-| M | Producer-consumer cardinality |
-| N | Test name / scenario verifier |
-| O | Docstring vs implementation drift |
-| P | Name vs behavior contract |
-| Q | Cross-surface claim consistency |
-
-## Breaking-change rule
-
-Adding a sub-bucket to a category rubric requires updating `audit-categories.json` and the matching prompt template in `prompts/` in the same commit, then running `audit_category_schema.py --validate`. Skills that reference category IDs (`bugteam`, `findbugs`) rely on stable sub-bucket IDs (A1, A2, … Q-n). Worked examples stay in the rubric markdown only; they are outside the schema.
+@AGENTS.md

package/audit-rubrics/category_rubrics/AGENTS.md

@@ -0,0 +1,37 @@
+# audit-rubrics/category_rubrics
+
+One rubric file per audit category (A–Q). Each file defines what the category covers, gives concrete examples of findings, and provides the sub-bucket decomposition an audit agent uses to structure its pass.
+
+## Files
+
+| File | Category |
+|---|---|
+| `category-a-api-contracts.md` | A — API contract verification |
+| `category-b-selector-engine-compat.md` | B — Selector engine compatibility |
+| `category-c-resource-cleanup.md` | C — Resource cleanup |
+| `category-d-scoping-and-ordering.md` | D — Scoping and ordering |
+| `category-e-dead-code.md` | E — Dead code |
+| `category-f-silent-failures.md` | F — Silent failures |
+| `category-g-bounds-and-overflow.md` | G — Bounds and overflow |
+| `category-h-security-boundaries.md` | H — Security boundaries |
+| `category-i-concurrency.md` | I — Concurrency |
+| `category-j-code-rules-compliance.md` | J — Code-rules compliance |
+| `category-k-codebase-conflicts.md` | K — Codebase conflicts |
+| `category-l-behavior-equivalence.md` | L — Behavior equivalence |
+| `category-m-producer-consumer-cardinality.md` | M — Producer-consumer cardinality |
+| `category-n-test-name-scenario-verifier.md` | N — Test name / scenario verifier |
+| `category-o-docstring-vs-impl-drift.md` | O — Docstring vs implementation drift |
+| `category-p-name-vs-behavior-contract.md` | P — Name vs behavior contract |
+| `category-q-cross-surface-claims.md` | Q — Cross-surface claim consistency |
+
+## Rubric structure
+
+Each file has:
+- A plain-language description of what the category audits
+- Concrete finding examples
+- A companion-reference pointer to `../source-material-section-types.md`
+- A sub-bucket decomposition table with stable IDs (A1, A2, …) and the concrete checks each bucket requires
+
+## Relationship to prompts/
+
+`category_rubrics/` is the human-readable reference. `prompts/` holds the agent-ready prompt templates that inline the same sub-bucket list in a structured prompt format. Keep both in sync when sub-buckets change.

package/audit-rubrics/category_rubrics/CLAUDE.md

@@ -1,37 +1 @@
-# audit-rubrics/category_rubrics
-
-One rubric file per audit category (A–Q). Each file defines what the category covers, gives concrete examples of findings, and provides the sub-bucket decomposition an audit agent uses to structure its pass.
-
-## Files
-
-| File | Category |
-|---|---|
-| `category-a-api-contracts.md` | A — API contract verification |
-| `category-b-selector-engine-compat.md` | B — Selector engine compatibility |
-| `category-c-resource-cleanup.md` | C — Resource cleanup |
-| `category-d-scoping-and-ordering.md` | D — Scoping and ordering |
-| `category-e-dead-code.md` | E — Dead code |
-| `category-f-silent-failures.md` | F — Silent failures |
-| `category-g-bounds-and-overflow.md` | G — Bounds and overflow |
-| `category-h-security-boundaries.md` | H — Security boundaries |
-| `category-i-concurrency.md` | I — Concurrency |
-| `category-j-code-rules-compliance.md` | J — Code-rules compliance |
-| `category-k-codebase-conflicts.md` | K — Codebase conflicts |
-| `category-l-behavior-equivalence.md` | L — Behavior equivalence |
-| `category-m-producer-consumer-cardinality.md` | M — Producer-consumer cardinality |
-| `category-n-test-name-scenario-verifier.md` | N — Test name / scenario verifier |
-| `category-o-docstring-vs-impl-drift.md` | O — Docstring vs implementation drift |
-| `category-p-name-vs-behavior-contract.md` | P — Name vs behavior contract |
-| `category-q-cross-surface-claims.md` | Q — Cross-surface claim consistency |
-
-## Rubric structure
-
-Each file has:
-- A plain-language description of what the category audits
-- Concrete finding examples
-- A companion-reference pointer to `../source-material-section-types.md`
-- A sub-bucket decomposition table with stable IDs (A1, A2, …) and the concrete checks each bucket requires
-
-## Relationship to prompts/
-
-`category_rubrics/` is the human-readable reference. `prompts/` holds the agent-ready prompt templates that inline the same sub-bucket list in a structured prompt format. Keep both in sync when sub-buckets change.
+@AGENTS.md

package/audit-rubrics/prompts/AGENTS.md

@@ -0,0 +1,37 @@
+# audit-rubrics/prompts
+
+Agent-ready audit prompt templates, one per category (A–Q). An agent inlines the artifact under review into the `[INLINE THE FULL ARTIFACT HERE]` placeholder and runs the prompt as-is.
+
+## Files
+
+| File | Category |
+|---|---|
+| `category-a-api-contracts.md` | A — API contract verification |
+| `category-b-selector-engine-compat.md` | B — Selector engine compatibility |
+| `category-c-resource-cleanup.md` | C — Resource cleanup |
+| `category-d-scoping-and-ordering.md` | D — Scoping and ordering |
+| `category-e-dead-code.md` | E — Dead code |
+| `category-f-silent-failures.md` | F — Silent failures |
+| `category-g-bounds-and-overflow.md` | G — Bounds and overflow |
+| `category-h-security-boundaries.md` | H — Security boundaries |
+| `category-i-concurrency.md` | I — Concurrency |
+| `category-j-code-rules-compliance.md` | J — Code-rules compliance |
+| `category-k-codebase-conflicts.md` | K — Codebase conflicts |
+| `category-l-behavior-equivalence.md` | L — Behavior equivalence |
+| `category-m-producer-consumer-cardinality.md` | M — Producer-consumer cardinality |
+| `category-n-test-name-scenario-verifier.md` | N — Test name / scenario verifier |
+| `category-o-docstring-vs-impl-drift.md` | O — Docstring vs implementation drift |
+| `category-p-name-vs-behavior-contract.md` | P — Name vs behavior contract |
+| `category-q-cross-surface-claims.md` | Q — Cross-surface claim consistency |
+
+## Prompt structure
+
+Each template:
+- Scopes the audit to one category only (skip the others)
+- Lists all sub-buckets from the matching `category_rubrics/` file
+- Requires each sub-bucket to produce at least one Shape A finding OR one Shape B proof-of-absence with three or more adversarial probes
+- Uses `find` as the finding ID prefix (single-pass audits) rather than `loop<N>-<K>`
+
+## Relationship to category_rubrics/
+
+`prompts/` is the executable form; `category_rubrics/` is the reference form. When a sub-bucket decomposition changes in a rubric, update the matching prompt in the same commit.

package/audit-rubrics/prompts/CLAUDE.md

@@ -1,37 +1 @@
-# audit-rubrics/prompts
-
-Agent-ready audit prompt templates, one per category (A–Q). An agent inlines the artifact under review into the `[INLINE THE FULL ARTIFACT HERE]` placeholder and runs the prompt as-is.
-
-## Files
-
-| File | Category |
-|---|---|
-| `category-a-api-contracts.md` | A — API contract verification |
-| `category-b-selector-engine-compat.md` | B — Selector engine compatibility |
-| `category-c-resource-cleanup.md` | C — Resource cleanup |
-| `category-d-scoping-and-ordering.md` | D — Scoping and ordering |
-| `category-e-dead-code.md` | E — Dead code |
-| `category-f-silent-failures.md` | F — Silent failures |
-| `category-g-bounds-and-overflow.md` | G — Bounds and overflow |
-| `category-h-security-boundaries.md` | H — Security boundaries |
-| `category-i-concurrency.md` | I — Concurrency |
-| `category-j-code-rules-compliance.md` | J — Code-rules compliance |
-| `category-k-codebase-conflicts.md` | K — Codebase conflicts |
-| `category-l-behavior-equivalence.md` | L — Behavior equivalence |
-| `category-m-producer-consumer-cardinality.md` | M — Producer-consumer cardinality |
-| `category-n-test-name-scenario-verifier.md` | N — Test name / scenario verifier |
-| `category-o-docstring-vs-impl-drift.md` | O — Docstring vs implementation drift |
-| `category-p-name-vs-behavior-contract.md` | P — Name vs behavior contract |
-| `category-q-cross-surface-claims.md` | Q — Cross-surface claim consistency |
-
-## Prompt structure
-
-Each template:
-- Scopes the audit to one category only (skip the others)
-- Lists all sub-buckets from the matching `category_rubrics/` file
-- Requires each sub-bucket to produce at least one Shape A finding OR one Shape B proof-of-absence with three or more adversarial probes
-- Uses `find` as the finding ID prefix (single-pass audits) rather than `loop<N>-<K>`
-
-## Relationship to category_rubrics/
-
-`prompts/` is the executable form; `category_rubrics/` is the reference form. When a sub-bucket decomposition changes in a rubric, update the matching prompt in the same commit.
+@AGENTS.md

package/bin/AGENTS.md

@@ -0,0 +1,112 @@
+# bin
+
+The installer and its companion modules. Running `npx claude-dev-env` (or `node bin/install.mjs`) copies package files into the managed root (`~/.claude/` by default; `CLAUDE_CONFIG_DIR` or `--target` selects another), merges hook entries into that root's `settings.json`, installs Git hooks, and writes `~/.mypy.ini` under the process home.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `install.mjs` | Main installer: builds a read-only plan via `install-plan.mjs`, then runs mutations inside `install-transaction.mjs` recovery (copy content directories, merge hooks, install skills, prune, git hooks, mypy.ini); routes `CLAUDE_HOME`, the manifest path, and `~/.mypy.ini` through `resolve-install-root.mjs`; resolves single or multi-profile targets before mutation and writes one ownership manifest per target |
+| `resolve-install-root.mjs` | Pure install-root resolver: precedence `--target` > `CLAUDE_CONFIG_DIR` > `~/.claude`, separator-boundary containment, and the declared external allowlist for `~/.mypy.ini` |
+| `select-install-targets.mjs` | Pure target selection for main-default, explicit `--target`, and `--profile`/`--profiles`; rejects ambiguous or duplicate targets; builds per-target manifest records with `targetIdentity` and `managedRoot` |
+| `install-plan.mjs` | Read-only install and uninstall plans: install preflight (managed root, source conflicts, Python, settings when hooks install) and uninstall preflight (settings JSON before removal, removable vs skipped manifest records), freezes plans E2/F execute |
+| `install-transaction.mjs` | Install, update, and uninstall transaction journal: captures prior settings, manifest, managed files, and `core.hooksPath`, restores them on failure, and supports fault injection phases for recovery tests |
+| `install.transaction.test.mjs` | Unit and sandbox installer tests for snapshot/restore and fault phases (`after_file_staging`, `after_settings_write`, `after_git_config`, `after_manifest_write`) |
+| `install.uninstall-transaction.test.mjs` | Uninstall plan preflight and recovery: malformed/non-object settings fail before removal, each fault phase restores files/settings/manifest/`core.hooksPath`, retry succeeds, selected-root containment |
+| `install.profile-root.test.mjs` | Contract tests for the install-root resolver: precedence, containment boundary, external allowlist, and the install.mjs import smoke check |
+| `install-constants.mjs` | The named values `install.mjs` reads: `SKIPPED_SOURCE_ENTRY_NAMES` and `SKIPPED_SOURCE_FILE_EXTENSIONS` for the build artifacts the source walk leaves behind, `RUN_BACKUP_DIRECTORY_NAME_PATTERN` for the timestamp shape a run backup directory carries, `MANAGED_SKILLS_DIRECTORY_NAME` and `MANAGED_HOOKS_DIRECTORY_NAME` for the directory name each of those trees carries in a package source and under `~/.claude` — read by the copy loops, the hooks.json reads, the git-hook shims, the mypy configuration, and the prunes alike — `SETTINGS_FILE_NAME` for the settings file the merge, the retired-hook prune, and the uninstall purge share, and `MYPY_INI_FILE_NAME` for the home-directory file `install_mypy_ini.mjs` writes (also imported by `resolve-install-root.mjs`) |
+| `ever-shipped-skills.mjs` | Static `EVER_SHIPPED_SKILL_NAMES` set of every top-level skill directory name the package has shipped; the installer subtracts the current skill set from it to prune retired skills left under `~/.claude/skills` |
+| `expand_home_directory_tokens.mjs` | Expands residual `$HOME` / `${HOME}` / `~/` tokens in settings.json hook and statusLine commands to absolute home paths at install time (literal-safe for homes that contain `$`) |
+| `git_hooks_installer.mjs` | Installs or updates the `pre-commit`, `pre-push`, and `post-commit` Git hooks in the user's git config; writes hook scripts that delegate to the installed Python hooks |
+| `install_mypy_ini.mjs` | Writes `~/.mypy.ini` with settings that make mypy find the hooks package and enforce strict type checking |
+| `install.test.mjs` | Unit tests for `install.mjs` — covers conflict detection, interpreter detection, settings merging, the settings shapes the installer never wrote — those every hook walk hands back untouched, and the shipped-event value the merge replaces with a warning — the source-artifact skip in `collectFiles`, the case-only rename decision and the `copyTree` copy that acts on it, the retired-hook diff and settings prune, the stale-file prune: the manifest diff, path-key case folding, emptied-parent cleanup, and the warn-and-keep paths, and backup retention: the sweep a moved-content run drives, the empty root a run whose moves failed gives up, and the populated root retention keeps |
+| `install.profiles.test.mjs` | Profile target-selection and per-target ownership manifest contract tests (main-default, multi-profile, ambiguity/duplicate rejection, help text) |
+| `install.plan.test.mjs` | Read-only plan and preflight tests: zero-write plan construction, source-conflict and missing-Python fail-closed, settings check only when hooks install, tolerant broken-manifest, invalid managed root, mutation-kind list for E2 |
+| `install.prune.test.mjs` | End-to-end prune tests that run the real installer against a sandbox `HOME` — retired-skill, retired-hook, and stale-file moves into one timestamped backup, the settings entry a retired hook loses, the top-level paths every root's diff leaves alone, the manifest record a failed move keeps, the full-install and resolved-dependency gates, backup retention, and the uninstall: the `~/.mypy.ini` removal, the containment guard, and nested-directory cleanup |
+| `git_hooks_installer.test.mjs` | Tests for `git_hooks_installer.mjs` |
+| `install_mypy_ini.test.mjs` | Tests for `install_mypy_ini.mjs` |
+
+## Source build artifacts
+
+`collectFiles` walks the package source and skips the artifacts a contributor's tooling writes beside it: the entry names `__pycache__`, `.ruff_cache`, `.pytest_cache`, `.mypy_cache`, `node_modules`, `.DS_Store`, and any file ending `.pyc` or `.pyo`. A skipped directory takes everything under it out of the walk. The `files` negations in `package.json` (`!**/__pycache__/**`, `!**/*.py[cod]`, the cache directories, `!**/*.log`, `!**/*.egg-info/**`) keep the same artifacts out of the published tarball, and `.npmignore` carries those patterns for tooling that reads it — keep the two in step. An `npx` install reads a clean tree; the walk covers a local `node bin/install.mjs` run against a working tree that holds the artifacts.
+
+The skip and the cleanup of artifacts an earlier install copied are one code path. A `.pyc` a prior manifest records under any managed root sits outside the set the walk returns, so the next full install reads it as stale, moves it into that run's backup root, and drops it from the manifest the run writes.
+
+## Copying a file whose name changed letter case
+
+`copyTree` renames a destination entry that differs from the shipped file name only in letter case to the shipped name, then copies. On a case-insensitive volume `copyFileSync` writes its bytes through whichever entry the filesystem resolves the path to, so a package shipping `README.md` over an installed `Readme.md` would fill the installed entry and leave the earlier spelling standing. The rename runs first because `renameSync` inside one directory is atomic: a run interrupted between the rename and the copy leaves the file present under the shipped name holding the earlier content, which the next install overwrites.
+
+The decision reads the destination directory's entry names, cached one listing per directory for the whole copy run. On a case-sensitive volume the two names are two files, so the rename is skipped and each name keeps its own content. `caseOnlyRenameSourceName(shippedName, existingNames, options)` holds the decision, and `options.isCaseInsensitive` carries the platform answer as a value so a test drives either branch on a host of either kind.
+
+## Retired-skill prune
+
+The full-install prune renames a retired skill directory into a timestamped backup rather than deleting it. Each pruned directory is renamed to `~/.claude/.claude-dev-env-pruned/<timestamp>/skills/<skill-name>/`, a backup root outside `~/.claude/skills` so a backed-up directory is never re-discovered as a skill. The `skills/` segment mirrors `~/.claude`, matching the layout the stale-file prune writes, so one recovery point reads as a copy of the tree it came from. One run shares one timestamped root, so a run leaves one recovery point. A rename that fails leaves the directory in place with a logged warning and never falls back to deletion, so a prune failure costs at most a cosmetic leftover.
+
+Matching is by directory name alone, so a user-authored directory whose name collides with a retired skill is backed up as if it were that skill. A directory is pruned when the prior install's manifest recorded it or the ever-shipped set names it, and the current install did not just write it. A name absent from all three of those sets, together with `~/.claude/skills/_shared`, is left in place. Recovery of a wrongly-matched directory runs until the next pruning install, which keeps its own backup and retires the rest.
+
+## Stale-file prune
+
+A full install also moves aside a file under a managed root that the run leaves unwritten. `copyTree` adds and overwrites but never removes, so every root the installer writes carries the same drift, and the prune covers all of them: `rules`, `docs`, `commands`, `agents`, `system-prompts`, `scripts`, `_shared`, `audit-rubrics`, `skills`, and `hooks` — the names in `MANAGED_TOP_LEVEL_DIRECTORY_NAMES`.
+
+Nothing moves unless a prior install recorded it. That single rule is what makes covering ten roots as safe as covering one: the installer reads the file list from `~/.claude/.claude-dev-env-manifest.json`, subtracts every file the run copied across all source roots, and moves what remains.
+
+The prune runs once per root, each call confined to its own root. Per-root iteration gives the containment guard and the emptied-parent walk the root that owns each file, and it settles `_shared`: `~/.claude/_shared` and `~/.claude/skills/_shared` are distinct absolute paths, so the `_shared` call and the `skills` call each see their own files and no path enters two diffs. Each root's content lands under `~/.claude/.claude-dev-env-pruned/<timestamp>/<root-name>/<relative>`, so the backup mirrors `~/.claude`. Every prune in a run shares that one timestamped root. A recorded path under no managed root — `~/.claude/CLAUDE.md`, `settings.json`, the manifest itself, and the `~/.mypy.ini` that sits in the home directory beside `~/.claude` — reaches no root's diff and stays where it is. The install summary reports the skills root's own count on the `skills:` line and the sum across roots on its own line.
+
+The manifest diff limits the move to files the installer itself wrote. Runtime-generated content — a Python `__pycache__` entry, a ruff cache, a log — and any file a user authored under a managed root stay in place, because no install recorded them. Path comparison ignores letter case on Windows and macOS, so a package shipping `README.md` over an installed `Readme.md` keeps the bytes the run just wrote. A directory or a link standing where the manifest records a file is skipped with a warning, so the mover never renames a whole tree and never follows a link out of `~/.claude`. A directory emptied by a move is removed, walking up to the root the file sat under. A move that fails logs a warning and leaves the file in place, so a prune failure costs at most a stale file. The installer records each such path in the fresh manifest when the file is still on disk, so the file stays inside the next full install's diff and gets another attempt.
+
+A missing or unreadable manifest, or one carrying no file list, holds the stale-file prune for that run: with no record of what an install wrote, the run has nothing to diff against.
+
+A run writes both manifest keys — the file list and the skill-name list — wholesale from what it just installed only when the prunes ran that run and read the prior record all the way through, so the next diff reads as "the package stopped shipping this". Every other run unions what it wrote onto the prior lists: a scoped `--only` install, a full install holding its prunes behind an unresolved dependency group, and a run whose prune step ends early with a logged warning. The union keeps every entry a later prune needs to spot a stale file or a retired skill, and keeps `--uninstall` able to name the whole tree. The prune itself bounds the lists: a stale path leaves the record on the first full install that moves it aside.
+
+## Retired-hook entries in settings.json
+
+A hook script under `~/.claude/hooks` carries a second reference: the `settings.json` entry that runs it. A full install removes that entry in the same run that moves the script aside, and removes it first — a `settings.json` naming a script that has left the hooks directory makes every session start invoke a missing file.
+
+The retired set comes from the manifest diff alone: the hook files a prior install recorded that this run leaves unwritten, each taken relative to `~/.claude/hooks`. A script the run still writes stays out of the set, and a path no install of ours recorded never enters it, so a user-authored hook is out of reach of the prune. Each command is matched on the anchored `/.claude/hooks/<relative>` tail the merge uses to tell this installer's entries from a user's, so a command whose path is a retired tail plus a suffix (`retired_gate.py.bak`) names another file and stays.
+
+The walk covers every event type the settings file holds rather than the ones the current `hooks.json` names, so an entry under an event type the package stopped shipping is reached too. A matcher group left empty is dropped, and an event type left empty goes with it. The file is written once, and only when an entry left it, so a run that retires no hook leaves `settings.json` byte-identical.
+
+Every settings walk recognizes the shapes the installer writes and steps around the rest, so a hand-edited or third-party `settings.json` carries an install through rather than ending it. A matcher group carrying no `hooks` array and a hook entry whose `command` is not a string survive every walk untouched. An event type whose value is not an array of groups survives this prune and the uninstall purge; the merge replaces that value with the group list it ships for that event type, warning with the event type named so the user can recover the value from their own history. An event type the package ships no groups for keeps whatever value the file holds.
+
+## Backup retention
+
+A run that moves content into `~/.claude/.claude-dev-env-pruned/<timestamp>/` then retires the other run backups, so the directory holds the one recovery point closest to what sits on disk. The retired-skill prune and the stale-file prune each report how many moves succeeded, and their sum is the signal the sweep answers to. The sweep removes a direct child whose name matches the installer's timestamp shape (`2026-07-25T18-04-11-923Z`), which leaves anything else under the pruned-backup directory in place, along with the directory itself. A removal that fails logs a warning and the sweep carries on, so retention never ends an install. The install output names the count when the sweep removes anything.
+
+A run that moves nothing sweeps nothing, so every recovery point the user holds stays where it is. `moveIntoRunBackup` creates the directories leading to a backup path before it renames, so a run whose every move fails — the antivirus scanner or open editor case — leaves that timestamped root standing empty. Retention clears it with `rmdirSync` alone, depth first, so a directory holding anything survives every step.
+
+## Uninstall
+
+`--uninstall` builds a read-only uninstall plan, captures a recovery snapshot, then removes each file the plan lists.
+
+Settings JSON is validated before any removal. A malformed or non-object `settings.json` fails closed with the managed files still on disk. Each manifest record passes a containment guard: the path resolves under `~/.claude`, or it names the `~/.mypy.ini` the install writes in the home directory. Every other record is skipped with a warning and counted. Skipping keeps one malformed record — hand-edited, or written by an installer that ran against a different home — from stranding the user with a half-removed install. The purge removes every legitimate record, clears the manifest, and reports the skipped count.
+
+The uninstall runs inside the same snapshot/restore journal as install: prior settings, manifest, managed files, and `core.hooksPath` restore when a later phase fails, so a retry starts from a complete ownership record. The journal is discarded only after a successful commit.
+
+Removing a file leaves its directory a candidate for cleanup. Once the file loop ends, the purge walks up from each such directory to the managed top-level directory the file sits under (`MANAGED_TOP_LEVEL_DIRECTORY_NAMES`), removing each directory it finds empty. That reaches a nested tree such as `skills/<name>/scripts/`. A record under no managed root gets no walk, so `~/.claude` itself is never a stop root and a directory the installer never wrote stays. A separate pass drops each managed top-level directory the purge empties.
+
+## Prune gates
+
+Every prune runs behind the same two gates: a full install, and every declared dependency group resolved. When any dependency group fails to resolve, all of them are skipped for the whole run with a logged notice naming the unresolved group. An unresolved dependency contributes no skills to the installed set, so a live skill that a dependency package supplies would look retired and its files would look stale; holding every prune until each dependency resolves keeps that skill's files in place and keeps their manifest records, so a run with every dependency resolved can still prune them.
+
+## Key exports from install.mjs
+
+| Export | Description |
+|---|---|
+| `CONTENT_DIRECTORIES` | Array of package subdirectory names copied verbatim to `~/.claude/` |
+| `MANAGED_TOP_LEVEL_DIRECTORY_NAMES` | The content directories plus `skills` and `hooks`; the stale-file prune walks it to give each root its own diff, and the uninstall purge reads it to find the root a recorded file belongs to |
+| `collectFiles(directory)` | Lists every file under a source directory, skipping the build-artifact names and extensions in `install-constants.mjs` |
+| `pythonCandidatesForPlatform(platform)` | Returns ordered Python interpreter candidates to probe; `py -3` first on Windows to avoid Microsoft Store alias issues |
+| `isWindowsStorePythonStub(path)` | Returns true when the path resolves to the non-spawnable WindowsApps stub |
+| `interpreterCommandFromPath(path)` | Formats an absolute interpreter path as a settings.json hook command prefix |
+| `collectPackageSourceConflicts(dir)` | Returns any unmerged git conflicts in the package source; installer aborts when any exist |
+| `pruneStaleInstalledFiles(priorFiles, currentFiles, destinationRoot, backupRoot, options)` | Moves each manifest-recorded file under the destination root that the run leaves unwritten into the run's backup root; returns `{ prunedCount, failedPaths }`. `options.isCaseInsensitive` drives path-key case folding, defaulting to this host's filesystem; `options.managedHomeDirectory` sets the home the containment guard tests against, defaulting to `~/.claude` |
+| `copyTree(sourceBase, destBase, options)` | Copies every file under a source directory, renaming a destination entry that differs from the shipped name only in letter case to the shipped name first; returns `{ created, updated, paths }`. `options.isCaseInsensitive` drives that rename, defaulting to this host's filesystem |
+| `caseOnlyRenameSourceName(shippedName, existingNames, options)` | Returns the existing directory entry a shipped file name would overwrite through a case-only spelling difference, or null; `options.isCaseInsensitive` defaults to this host's filesystem |
+| `retiredManagedHookRelativePaths(priorFiles, currentFiles, hooksRoot)` | Returns the hook script paths a prior install recorded under the hooks root that this run leaves unwritten, each relative to that root |
+| `pruneRetiredHookEntriesFromSettings(settingsPath, retiredPaths)` | Removes each settings.json entry running a retired managed hook script, writing the file only when an entry left it; returns the removed count |
+| `retainNewestRunBackupOnly(runBackupRoot, didRunMoveContent)` | Retires every run backup sitting beside the run's own when `didRunMoveContent` holds; clears the run's empty root with `rmdirSync` when it does not |
+| `comparisonKeyForPath(path, options)` | Builds the key two paths are compared through: resolved, forward-slashed, and lowercased when `options.isCaseInsensitive` holds — which defaults to true on Windows and macOS |
+
+## Install groups
+
+`install.mjs` defines install groups (`core`, `journal`) plus any dependency groups discovered from `package.json` `dependencies`. The `core` group installs skills, all hooks, and the content directories. `journal` installs only its skill set.