claude-dev-env 2.13.0 → 2.14.1

package/_shared/pr-loop/scripts/tests/CLAUDE.md

@@ -1,44 +1 @@
-# _shared/pr-loop/scripts/tests
-
-pytest suite for the scripts and constants in `_shared/pr-loop/scripts/`. Each test file covers one script or one constants module.
-
-## Test files
-
-| File | Covers |
-|---|---|
-| `test__claude_permissions_common.py` | Internal helpers in `_claude_permissions_common.py` (legacy underscore prefix) |
-| `test_claude_permissions_common.py` | Public API of `_claude_permissions_common.py` |
-| `test_claude_permissions_constants.py` | `pr_loop_shared_constants/claude_permissions_constants.py` |
-| `test_claude_settings_keys_constants.py` | `pr_loop_shared_constants/claude_settings_keys_constants.py` |
-| `test_code_rules_gate.py` | `code_rules_gate.py` gate logic |
-| `test_terminology_sweep.py` | `terminology_sweep.py` near-miss detection and exit codes |
-| `test_code_rules_gate_constants.py` | `pr_loop_shared_constants/code_rules_gate_constants.py` |
-| `test_fix_hookspath.py` | `fix_hookspath.py` repair logic |
-| `test_fix_hookspath_constants.py` | `pr_loop_shared_constants/fix_hookspath_constants.py` |
-| `test_grant_project_claude_permissions.py` | `grant_project_claude_permissions.py` end-to-end |
-| `test_post_audit_thread.py` | `post_audit_thread.py` review-posting flow |
-| `test_post_audit_thread_constants.py` | `pr_loop_shared_constants/post_audit_thread_constants.py` |
-| `test_preflight.py` | `preflight.py` pre-flight checks |
-| `test_preflight_constants.py` | `pr_loop_shared_constants/preflight_constants.py` |
-| `test_preflight_self_heal.py` | `preflight_self_heal.py` hooks-path repair |
-| `test_reviews_disabled.py` | `reviews_disabled.py` opt-out gate parsing |
-| `test_copilot_quota.py` | `copilot_quota.py` end-to-end: account resolution, premium-quota classification, exit codes, and skip logging |
-| `test_copilot_quota_constants.py` | `pr_loop_shared_constants/copilot_quota_constants.py` |
-| `test_reviewer_availability.py` | `reviewer_availability.py` end-to-end: Copilot and Bugbot availability, opt-out via `CLAUDE_REVIEWS_DISABLED`, and every Copilot quota outcome |
-| `test_reviewer_availability_constants.py` | `pr_loop_shared_constants/reviewer_availability_constants.py` |
-| `test_revoke_project_claude_permissions.py` | `revoke_project_claude_permissions.py` end-to-end |
-| `test_stale_worktree_rule_sweep.py` | `stale_worktree_rule_sweep.py` sweep and deduplication end-to-end |
-| `test_stale_worktree_rule_sweep_constants.py` | `pr_loop_shared_constants/stale_worktree_rule_sweep_constants.py` worktrees-root resolution and rule-format readers |
-| `test_agent_config_carveout.py` | Agent-config deny-rule carve-out logic |
-| `conftest.py` | Shared pytest fixtures |
-
-## Fixtures
-
-`fixtures/copilot_internal_user_example.json` — a captured `gh api
-copilot_internal/user` response driving `test_copilot_quota.py`.
-
-## Running
-
-```bash
-python -m pytest packages/claude-dev-env/_shared/pr-loop/scripts/tests/
-```
+@AGENTS.md

package/_shared/process-tree/AGENTS.md

@@ -0,0 +1,41 @@
+# _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()`.

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,26 @@
+# 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 |
+|---|---|---|
+| `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-quality-agent.md` | Code Quality Agent | Multi-file code quality review across an entire diff or set of files |
+| `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

@@ -42,8 +42,8 @@ non-empty string, and a `name` equal to its file stem — a mapping that loads
 but binds `description` to nothing, or names an agent the file does not,
 registers a subagent the caller cannot spawn::
 
-    ok:   docs-agent.md  -> name: docs-agent
-    flag: docs-agent.md  -> name: doc-manager   <- wrong spawn id
+    ok:   clean-coder.md  -> name: clean-coder
+    flag: clean-coder.md  -> name: doc-manager   <- wrong spawn id
     flag: description:                          <- loads as None, loader needs text
 
 Every check above is parametrized over the definitions that yield a
@@ -52,8 +52,8 @@ and leave the suite green while unreadable. The block is what the fence lines
 delimit, so the file that opens no fence or never closes one is exactly the
 broken file these checks exist to catch::
 
-    ok:   docs-agent.md  -> ---  name/description  ---   <- block found
-    flag: docs-agent.md  -> ---  name/description        <- no closing fence,
+    ok:   clean-coder.md  -> ---  name/description  ---   <- block found
+    flag: clean-coder.md  -> ---  name/description        <- no closing fence,
                                                             silently uncovered
 
 `test_every_agent_definition_yields_a_frontmatter_block` holds that floor: it
@@ -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
     )
 
 
@@ -218,8 +218,8 @@ def _agent_name_problem(parsed_frontmatter: object, expected_name: str) -> str |
     A subagent registers under the name in its frontmatter, so a name that is
     not the file stem is spawned by an id no caller uses::
 
-        docs-agent.md -> name: docs-agent   -> ok:   None
-        docs-agent.md -> name: doc-manager  -> flag: wrong spawn id
+        clean-coder.md -> name: clean-coder   -> ok:   None
+        clean-coder.md -> name: doc-manager  -> flag: wrong spawn id
 
     Args:
         parsed_frontmatter: Value `yaml.safe_load` produced for the block.
@@ -289,7 +289,7 @@ def test_agent_frontmatter_loads_as_a_yaml_mapping(
 @pytest.mark.parametrize(
     "agent_file_name",
     (
-        "docs-agent.md",
+        "clean-coder.md",
         "issue-tracker.md",
         "skill-writer-agent.md",
     ),

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