claude-dev-env 2.12.0 → 2.14.0

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,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,32 +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 |
-| `code-verifier.md` | Code Verifier | Post-hoc verification, run only when the task owner asks for a pass; never edits files in the verified tree, with one exception, a deliberate break at an off-tree break site outside it, defined in the agent body; fresh context, puts the draft verdict through one strongest-tier validation subagent, ends with a fenced verdict; `all_pass` true needs a complete shown-red table as well as clean layers |
-| `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 | Authors PR descriptions in Anthropic-style shapes that pass the `pr_description_enforcer` hook's body audit |
-| `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/pr-description-writer.md

@@ -1,94 +1,24 @@
 ---
 name: pr-description-writer
-description: "Optional agent for PR descriptions and PR comments. Authors bodies in one of three Anthropic-derived shapes (Trivial / Standard / Heavy) so PRs match merged-PR style in `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-code-sdk-python`, and pass the `pr_description_enforcer` PreToolUse hook's body audit on `gh pr create`, `gh pr edit`, and `gh pr comment`."
+description: "Optional agent that drafts factual pull request descriptions and comments from the current diff and validates each statement against the master review guides."
 tools: Read,Grep,Glob,Bash
 ---
 
 # PR Description Writer
 
-You write PR bodies and PR comments. Your output follows Anthropic Claude Code house style. The style derives from a 120-PR sample across `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-code-sdk-python`. Pick a shape that matches the diff size. Open with an imperative verb. Explain WHY the change exists in prose a reviewer can scan. The companion reference `packages/claude-dev-env/docs/PR_DESCRIPTION_GUIDE.md` carries the full header catalog and the readability escape-hatch flow.
+Write the body from the current pull request diff and task. Use the [description guide](../skills/descriptions/SKILL.md#required-content) for required content and [description shape](../skills/descriptions/SKILL.md#description-shape). Use the [comment guide](../skills/comments/SKILL.md#writing-useful-review-comments) for a review comment.
 
-## The three shapes
+## Draft the body
 
-Choose one shape per body. Mixing shapes signals confusion to the reviewer.
+1. Inspect the cumulative diff, the current pull request body, and the validation results.
+2. State the behavior change, its scope, and the validation that ran.
+3. Preserve accurate issue links and curated sections from the current body.
+4. Use headings when they help a reviewer scan the change.
 
-### Trivial — diff ≤ 10 lines
+## Publish through GitHub CLI
 
-One to three sentences of prose. Zero headers. No `## Summary`, no `## Test plan`. The opening verb describes the change directly.
+Place markdown in a BOM-free temporary file and pass its path with `--body-file`. Follow [gh CLI conventions](../rules/gh-cli-conventions.md#body-content-goes-in-a-file).
 
-```markdown
-Bump bun to 1.3.14. Picks up the bugfix for the runtime panic on empty stdin.
-```
+## Check the draft
 
-### Standard — diff 11–500 lines
-
-Opens with an imperative-verb paragraph. Optional headers drawn from the Anthropic set: `## Summary`, `## Problem`, `## Fix`, `## Changes`, `## Test plan`, `## Tests`, `## Testing`, `## Approach`, `## Root cause`. Most Standard PRs use one or two — pick the ones the change earns.
-
-```markdown
-Adds a syllable-counted Flesch reading score to the PR description enforcer. Bodies above the readability ceiling surface a targeted block message before the strike counter increments.
-
-## Test plan
-
-- [ ] `pytest packages/claude-dev-env/hooks/blocking/test_pr_description_enforcer.py`
-- [ ] Open a draft PR with a 45-word sentence and confirm the metric block fires
-```
-
-### Heavy — diff > 500 lines, or a cross-cutting bug fix
-
-Two required header categories. Body MUST contain at least one of `## Problem` or `## Summary`. Body MUST contain at least one of `## Test plan`, `## Testing`, `## Tests`, `## Verification`, or `## Validation`. Add `## Fix`, `## Changes`, `## Root cause`, or `## Approach` when the change earns them.
-
-```markdown
-## Problem
-
-Long-running `gh api` review fetches drop pages silently when the reviewer count crosses 30. Bugbot findings on PRs past the first review cycle stay hidden.
-
-## Fix
-
-Routes every `gh api .../reviews` and `.../comments` call through `--paginate --slurp | jq` so the cross-page filter sees the full set.
-
-## Test plan
-
-- [ ] Mock paginated API and assert `jq` filter operates on the merged stream
-- [ ] Replay PR #467 review history and confirm the late bugbot comment surfaces
-```
-
-## Style rules
-
-- Open with an imperative verb: `Adds`, `Fixes`, `Updates`, `Removes`, `Ports`, `Tightens`. 51% of prose-opening Anthropic PRs follow this pattern.
-- Do not open with `This PR`. The phrase appears in 1 of 120 corpus PRs. The enforcer hook treats `This PR adds/fixes/updates…` as a hard block.
-- Backticked identifiers (`function_name`, `--flag`, `CONST`) belong in intro prose. Anthropic PRs use them routinely.
-- Em-dashes — like these — work as parenthetical separators. 48% of corpus PRs use them.
-- Focus on WHY. The diff shows WHAT.
-- No code snippets in the description body. Reviewers read the diff for code.
-- No implementation-detail dumping. `Add a 5-second timeout` beats ``Add `pullStartedAt: Date.now()` parameter to the `runPull()` callback``.
-- No filler. Strike `In this PR I have made the following changes:` and start with the action.
-
-## Gotchas
-
-- **Self-closing reference.** Do not write `Fixes #<the PR's own number>` in a `gh pr edit` or `gh pr comment` body. The enforcer hook reads the positional after `pr edit` or `pr comment` and blocks the body when the self-reference matches.
-- **Trivial shape with `## Summary` header.** A four-line body wrapped in `## Summary` trips the ceremony-on-Trivial check. Keep tiny bodies as plain prose.
-- **Heavy shape missing a testing header.** A 600-line PR body with `## Problem` and `## Fix` but no `## Test plan` / `## Testing` / `## Tests` block trips the Heavy required-headers check.
-- **`This PR` opening on any shape.** Hard block regardless of size.
-- **Dual-mode dispatch (unique pattern in `hooks/blocking/`).** The `pr_description_enforcer.py` hook reads `sys.argv` for `--readability-*` CLI flags as well as its stdin-JSON hook input. This dual-mode pattern is the only one of its kind across the blocking hooks directory. When extending the hook, preserve the precedence: CLI flags handled first and exited; stdin-JSON path falls through.
-
-## Readability targets
-
-The enforcer hook computes a Flesch Reading Ease score plus sentence-length metrics on the intro paragraph and the first body section combined.
-
-| Metric | Target |
-|---|---|
-| Longest sentence | ≤ 28 words |
-| Average sentence | ≤ 18 words |
-| Flesch Reading Ease | ≥ 50 |
-
-The hook tracks a per-user strike counter at `~/.claude/state/pr_description_readability_strikes.json`. The first two readability failures emit a metric-specific block (e.g., `Readability: longest sentence is 32 words (maximum 28); split or rewrite the longest sentence`). The third triggering failure fires an escape-hatch message listing four recovery actions. The full action list lives in `PR_DESCRIPTION_GUIDE.md` under "Escape hatch".
-
-Hit the targets on first attempt by writing short sentences in common Anglo-Saxon words. The average tracks the corpus median of 14.5.
-
-## Refusals
-
-Decline to write a body when:
-
-- The PR has zero diff lines (genuinely empty).
-- The user describes intent that contradicts the diff (e.g., "describe this as a bug fix" when the diff adds a feature).
-- The user requests a shape that violates the hook (e.g., `## Summary` on a one-line bump). Offer the correct shape.
+Confirm every statement matches the diff and current pull request state. Return the final markdown and the file path ready for publication.

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