claude-dev-env 2.12.0 → 2.14.0

package/AGENTS.md

@@ -0,0 +1,61 @@
+# Development Assistant
+
+## Communication
+
+Reply shape and length: follow `~/.claude/rules/eli11-replies.md`. Word choice: follow `~/.claude/rules/plain-language.md`. Progress and finals: follow `~/.claude/rules/opus5-communication-contract.md` (`opus5-communication-contract-v1`). State claims affirmatively.
+
+## Security
+
+Collect credentials through secure UI only; never request secrets in chat.
+
+A runtime value that is itself private — a host, an SSH user or port, an owner scope, an account ID — lives in git-ignored local configuration with a committed placeholder in its place. Source files never carry the real value.
+
+## Advisors
+
+| Path | Holds |
+|---|---|
+| `~/.claude/docs/references/advisor-tool.md` | When to call a stronger reviewer, hard rule before first write, how to treat advice |
+| `/team-advisor` skill | Standing warm advisor bind (map: `docs/references/team-advisor-skill.md`) |
+| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, model floor, lifecycle |
+
+Use `/team-advisor` under the rules in `advisor-tool.md` for every advisor consultation.
+
+## Files and workspaces
+
+Put all work in an isolated worktree under the repo's `.claude/worktrees/`.
+
+Default to Edit for existing files; reach for Write only when the path is genuinely new.
+
+## Code and tests
+
+Tests must exercise real behavior, real data, and production paths.
+
+Keep changes within scope. Prefer durable systemic fixes for reusable behavior.
+
+Do not rewrite entire files or rename public parameters without need.
+
+## Reviews
+
+Verify every sub-agent file list, count, description, and finding against the repository and diff.
+
+Do not commit untracked files unless explicitly instructed.
+
+## Package communication contract
+
+Use `opus5-communication-contract-v1` for package communication.
+
+## Delegation
+
+Request precise file-and-line answers from research subagents.
+
+## Task tracking
+
+Track multi-step work with the `task-build` skill.
+
+## Repository rule
+
+Before changing skill, rule, or hook installation in the claude-dev-env repo, read `docs/references/skill-install-system.md`.
+
+## Definitions
+
+Warm agent: active within the past 59 minutes.

package/CLAUDE.md

@@ -1,57 +1 @@
-# Development Assistant
-
-## Communication
-
-Reply shape and length: follow `~/.claude/rules/eli11-replies.md`. Word choice: follow `~/.claude/rules/plain-language.md`. Progress and finals: follow `~/.claude/rules/opus5-communication-contract.md` (`opus5-communication-contract-v1`). State claims affirmatively.
-
-## Security
-
-Collect credentials through secure UI only; never request secrets in chat.
-
-A runtime value that is itself private — a host, an SSH user or port, an owner scope, an account ID — lives in git-ignored local configuration with a committed placeholder in its place. Source files never carry the real value.
-
-## Advisors
-
-| Path | Holds |
-|---|---|
-| `~/.claude/docs/references/advisor-tool.md` | When to call a stronger reviewer, hard rule before first write, how to treat advice |
-| `/team-advisor` skill | Standing warm advisor bind (map: `docs/references/team-advisor-skill.md`) |
-| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, model floor, lifecycle |
-
-Use `/team-advisor` under the rules in `advisor-tool.md` for every advisor consultation.
-
-## Files and workspaces
-
-Put all work in an isolated worktree under the repo's `.claude/worktrees/`.
-
-Default to Edit for existing files; reach for Write only when the path is genuinely new.
-
-## Code and tests
-
-Tests must exercise real behavior, real data, and production paths.
-
-Keep changes within scope. Prefer durable systemic fixes for reusable behavior.
-
-Do not rewrite entire files or rename public parameters without need.
-
-## Reviews
-
-Verify every sub-agent file list, count, description, and finding against the repository and diff.
-
-Do not commit untracked files unless explicitly instructed.
-
-## Delegation
-
-Request precise file-and-line answers from research subagents.
-
-## Task tracking
-
-Track multi-step work with the `task-build` skill.
-
-## Repository rule
-
-Before changing skill, rule, or hook installation in the claude-dev-env repo, read `docs/references/skill-install-system.md`.
-
-## Definitions
-
-Warm agent: active within the past 59 minutes.
+@AGENTS.md

package/_shared/AGENTS.md

@@ -0,0 +1,15 @@
+# _shared
+
+Cross-cutting runtime assets shared by multiple skills. The PR-loop skills (`bugteam`, `pr-converge`, `findbugs`, `fixbugs`) are one such cluster; other clusters live here too. Files here are installed into `~/.claude/_shared/` by `bin/install.mjs` alongside the skill directories that import them.
+
+## Contents
+
+| Entry | Description |
+|---|---|
+| `pr-loop/` | Docs, scripts, and constants for the PR-loop workflow suite |
+| `advisor/` | Warm-advisor spawn-and-consult protocol for `team-advisor` and `orchestrator` |
+| `process-tree/` | One process-tree kill helper for every script that captures a spawned CLI's output |
+
+## Install path
+
+`bin/install.mjs` copies this entire directory tree verbatim to `~/.claude/_shared/`. Skills reference files here by relative path from their own skill root (e.g. `../../_shared/pr-loop/audit-contract.md`).

package/_shared/CLAUDE.md

@@ -1,15 +1 @@
-# _shared
-
-Cross-cutting runtime assets shared by multiple skills. The PR-loop skills (`bugteam`, `pr-converge`, `findbugs`, `fixbugs`) are one such cluster; other clusters live here too. Files here are installed into `~/.claude/_shared/` by `bin/install.mjs` alongside the skill directories that import them.
-
-## Contents
-
-| Entry | Description |
-|---|---|
-| `pr-loop/` | Docs, scripts, and constants for the PR-loop workflow suite |
-| `advisor/` | Warm-advisor spawn-and-consult protocol for `team-advisor` and `orchestrator` |
-| `process-tree/` | One process-tree kill helper for every script that captures a spawned CLI's output |
-
-## Install path
-
-`bin/install.mjs` copies this entire directory tree verbatim to `~/.claude/_shared/`. Skills reference files here by relative path from their own skill root (e.g. `../../_shared/pr-loop/audit-contract.md`).
+@AGENTS.md

package/_shared/advisor/AGENTS.md

@@ -0,0 +1,22 @@
+# _shared/advisor
+
+Warm-advisor bind-and-consult protocol shared by `team-advisor`, `orchestrator`, `orchestrator-refresh`, and every executor subagent `orchestrator` routes work to. Changes here affect all of these simultaneously — treat this as a breaking-change surface.
+
+Host profile (Claude vs third-party) is detected first; Claude walks the multi-tier Agent spawn ladder (CLI chain as fallback), a third-party host binds a max-tier Claude advisor through the CLI Claude-chain (fail closed when the chain cannot serve) with a separate executor paste block.
+
+## Key documents
+
+| File | Purpose |
+|---|---|
+| `advisor-protocol.md` | Router with a moment-keyed read map: host profiles first, model floor, warm-up and consult standing rules, lifecycle ownership, Advisor-block assembly rule, and the shared CLI Claude-chain — each with a stub pointing at its `reference/` detail file |
+
+## Subdirectory
+
+| Entry | Description |
+|---|---|
+| `scripts/` | `model_tier_run_validator.py` (spawn-walk log checks, including optional Sol), `codex_sol_advisor.py` (read-only Sol xhigh bind and resume), `tier_model_ids.py` (Claude aliases, Codex model ids, and host detection), and `advisor_scripts_constants` under `scripts/config/` (ladder, bind tokens, aliases, host profiles, and SendMessage wait bound) |
+| `reference/` | Progressive-disclosure detail behind protocol stub sections: `warm-up.md`, `third-party-bind.md`, `sol-rung.md`, `consult-format.md`, `advisor-block.md`, `lifecycle.md`, `cli-chain.md`, and `spawn-walk-log.md` |
+
+## Breaking-change rule
+
+A change to host detection, the model-floor rule, the charter template, either host's Advisor block, or lifecycle ownership in `advisor-protocol.md` requires updating every consuming skill (`team-advisor`, `orchestrator`, `orchestrator-refresh`) in the same commit.

package/_shared/advisor/CLAUDE.md

@@ -1,22 +1 @@
-# _shared/advisor
-
-Warm-advisor bind-and-consult protocol shared by `team-advisor`, `orchestrator`, `orchestrator-refresh`, and every executor subagent `orchestrator` routes work to. Changes here affect all of these simultaneously — treat this as a breaking-change surface.
-
-Host profile (Claude vs third-party) is detected first; Claude walks the multi-tier Agent spawn ladder (CLI chain as fallback), a third-party host binds a max-tier Claude advisor through the CLI Claude-chain (fail closed when the chain cannot serve) with a separate executor paste block.
-
-## Key documents
-
-| File | Purpose |
-|---|---|
-| `advisor-protocol.md` | Router with a moment-keyed read map: host profiles first, model floor, warm-up and consult standing rules, lifecycle ownership, Advisor-block assembly rule, and the shared CLI Claude-chain — each with a stub pointing at its `reference/` detail file |
-
-## Subdirectory
-
-| Entry | Description |
-|---|---|
-| `scripts/` | `model_tier_run_validator.py` (spawn-walk log checks, including optional Sol), `codex_sol_advisor.py` (read-only Sol xhigh bind and resume), `tier_model_ids.py` (Claude aliases, Codex model ids, and host detection), and `advisor_scripts_constants` under `scripts/config/` (ladder, bind tokens, aliases, host profiles, and SendMessage wait bound) |
-| `reference/` | Progressive-disclosure detail behind protocol stub sections: `warm-up.md`, `third-party-bind.md`, `sol-rung.md`, `consult-format.md`, `advisor-block.md`, `lifecycle.md`, `cli-chain.md`, and `spawn-walk-log.md` |
-
-## Breaking-change rule
-
-A change to host detection, the model-floor rule, the charter template, either host's Advisor block, or lifecycle ownership in `advisor-protocol.md` requires updating every consuming skill (`team-advisor`, `orchestrator`, `orchestrator-refresh`) in the same commit.
+@AGENTS.md

package/_shared/pr-loop/AGENTS.md

@@ -0,0 +1,27 @@
+# _shared/pr-loop
+
+Runtime documents and scripts shared by every PR-loop skill. Changes here affect `bugteam`, `pr-converge`, `clean-room audit`, and `pr-fix-protocol` simultaneously — treat this as a breaking-change surface.
+
+## Key documents
+
+| File | Purpose |
+|---|---|
+| `audit-contract.md` | Canonical finding schema (Shape A / Shape B) and loop contract; defines the JSON shapes every audit skill must emit |
+| `audit-reply-template.md` | Canonical reply skeleton Claude posts to each unresolved review thread; single source of truth for reply structure |
+| `post-audit-thread-contract.md` | Single source of truth for the `post_audit_thread.py` invocation string, exit-code table, and per-caller policy (bugteam exit 2 = hard blocker; autoconverge clean-audit failed post = recorded bypass) |
+| `fix-protocol.md` | Ordered sequence a fix lens follows: read, capture SHA, TDD, apply, validate, self-audit, commit, push, reply + resolve |
+| `gh-payloads.md` | How to build GitHub review and reply payloads via MCP tools; describes the one-review-per-loop pattern |
+| `state-schema.md` | Fields each PR-loop workflow tracks across iterations; documents common fields and per-skill extensions |
+| `code-rules-gate.md` | Reference for the CODE_RULES pre-commit gate check; describes what the gate blocks and when it runs |
+| `precatch-rubric.md` | Shared pre-catch lane checklist — deterministic sweep, doc-vs-code parity, test-assertion completeness, PR-description parity, adversarial audit — that autoconverge's lenses and pr-converge's CODE_REVIEW step read on demand |
+| `worker-spawn.md` | Worker-spawn tier protocol and Claude-only slash-step host routing: three tiers, CLI/API inputs, JSON result shape, host detection, code-review modes via `detect_host_profile` + `invoke_code_review`, leader-socket rule, cloud setup; documents `scripts/resolve_worker_spawn.py` |
+
+## Subdirectory
+
+| Entry | Description |
+|---|---|
+| `scripts/` | Python scripts and constants consumed at runtime by the PR-loop skills |
+
+## Breaking-change rule
+
+Any shape change in `audit-contract.md` or `audit-reply-template.md` requires updating every consuming skill in the same commit.

package/_shared/pr-loop/CLAUDE.md

@@ -1,27 +1 @@
-# _shared/pr-loop
-
-Runtime documents and scripts shared by every PR-loop skill. Changes here affect `bugteam`, `pr-converge`, `clean-room audit`, and `pr-fix-protocol` simultaneously — treat this as a breaking-change surface.
-
-## Key documents
-
-| File | Purpose |
-|---|---|
-| `audit-contract.md` | Canonical finding schema (Shape A / Shape B) and loop contract; defines the JSON shapes every audit skill must emit |
-| `audit-reply-template.md` | Canonical reply skeleton Claude posts to each unresolved review thread; single source of truth for reply structure |
-| `post-audit-thread-contract.md` | Single source of truth for the `post_audit_thread.py` invocation string, exit-code table, and per-caller policy (bugteam exit 2 = hard blocker; autoconverge clean-audit failed post = recorded bypass) |
-| `fix-protocol.md` | Ordered sequence a fix lens follows: read, capture SHA, TDD, apply, validate, self-audit, commit, push, reply + resolve |
-| `gh-payloads.md` | How to build GitHub review and reply payloads via MCP tools; describes the one-review-per-loop pattern |
-| `state-schema.md` | Fields each PR-loop workflow tracks across iterations; documents common fields and per-skill extensions |
-| `code-rules-gate.md` | Reference for the CODE_RULES pre-commit gate check; describes what the gate blocks and when it runs |
-| `precatch-rubric.md` | Shared pre-catch lane checklist — deterministic sweep, doc-vs-code parity, test-assertion completeness, PR-description parity, adversarial audit — that autoconverge's lenses and pr-converge's CODE_REVIEW step read on demand |
-| `worker-spawn.md` | Worker-spawn tier protocol and Claude-only slash-step host routing: three tiers, CLI/API inputs, JSON result shape, host detection, code-review modes via `detect_host_profile` + `invoke_code_review`, leader-socket rule, cloud setup; documents `scripts/resolve_worker_spawn.py` |
-
-## Subdirectory
-
-| Entry | Description |
-|---|---|
-| `scripts/` | Python scripts and constants consumed at runtime by the PR-loop skills |
-
-## Breaking-change rule
-
-Any shape change in `audit-contract.md` or `audit-reply-template.md` requires updating every consuming skill in the same commit.
+@AGENTS.md

package/_shared/pr-loop/scripts/AGENTS.md

@@ -0,0 +1,35 @@
+# _shared/pr-loop/scripts
+
+Python scripts invoked at runtime by the PR-loop skills. Each script is a standalone CLI entry point; `pr_loop_shared_constants/` holds the named constants they import.
+
+## Key scripts
+
+| File | Purpose |
+|---|---|
+| `preflight.py` | Pre-flight check run before each audit loop tick: verifies hooks path, finds test files, runs pytest, checks for `BUGTEAM_PREFLIGHT_SKIP` opt-out |
+| `preflight_self_heal.py` | Clears stale `core.hooksPath` overrides that Git seeds into fresh worktree local config; called from `preflight.py` |
+| `post_audit_thread.py` | Posts an audit review (APPROVE / REQUEST_CHANGES) to a draft PR via the GitHub reviews API; reads the body skeleton from `audit-reply-template.md` at runtime |
+| `grant_project_claude_permissions.py` | Writes idempotent allow-rules and `additionalDirectories` entries into `~/.claude/settings.json` so subagents can edit the project's `.claude/` tree without prompting |
+| `revoke_project_claude_permissions.py` | Removes the allow-rules and entries that `grant_project_claude_permissions.py` wrote; safe to run when no prior grant exists |
+| `stale_worktree_rule_sweep.py` | Drops allow/deny rules pointing at deleted `~/.claude/worktrees/<repo>/<worktree>` directories and deduplicates the rule arrays; run by the grant and revoke flows before they write |
+| `code_rules_gate.py` | Pre-commit gate that runs `code_rules_enforcer` checks on staged Python files before a fix commit lands, and the terminology sweep over the staged diff |
+| `terminology_sweep.py` | Flags a prose term that near-misses an identifier introduced on added code lines of a unified diff (shared leading word, divergent tail) |
+| `reviews_disabled.py` | Shared helper for the reviewer opt-out and opt-in gates; parses `CLAUDE_REVIEWS_DISABLED` tokens `bugteam`, `bugbot`, `copilot`, and `codex`, plus `CLAUDE_REVIEWS_ENABLED` for opt-in. `bugbot`, `bugteam`, and `codex` are off by default and each runs only when `CLAUDE_REVIEWS_ENABLED` lists it; `copilot` runs by default and stops only when `CLAUDE_REVIEWS_DISABLED` lists it |
+| `copilot_quota.py` | Copilot premium-request quota pre-check: resolves a configured GitHub account, reads its remaining `premium_interactions` quota via `gh api copilot_internal/user`, and exits 0 (run Copilot) or non-zero (skip: out of quota, API down, or no account configured) |
+| `reviewer_availability.py` | Unified reviewer-availability entry point for Copilot and Bugbot: reuses `copilot_quota.py` and `reviews_disabled.py` and exits 0 when the named `--reviewer` may be spawned, non-zero when it is opted out or (for Copilot) out of quota |
+| `fix_hookspath.py` | Repairs a malformed `core.hooksPath` global git config entry |
+| `_claude_permissions_common.py` | Internal helpers shared by the grant/revoke scripts: atomic settings.json writes, list mutation, path helpers |
+
+## Subdirectories
+
+| Entry | Description |
+|---|---|
+| `code_rules_gate_parts/` | The decomposed modules `code_rules_gate.py` wires together: enforcer loading, git file sets, blob readers, added-line maps, violation scoping, wrapper plumb-through, gate running, staged-test running, and argument parsing |
+| `pr_loop_shared_constants/` | Named constants used by the scripts above |
+| `tests/` | pytest suite for all scripts in this directory |
+
+## Running tests
+
+```bash
+python -m pytest packages/claude-dev-env/_shared/pr-loop/scripts/tests/
+```

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

@@ -1,35 +1 @@
-# _shared/pr-loop/scripts
-
-Python scripts invoked at runtime by the PR-loop skills. Each script is a standalone CLI entry point; `pr_loop_shared_constants/` holds the named constants they import.
-
-## Key scripts
-
-| File | Purpose |
-|---|---|
-| `preflight.py` | Pre-flight check run before each audit loop tick: verifies hooks path, finds test files, runs pytest, checks for `BUGTEAM_PREFLIGHT_SKIP` opt-out |
-| `preflight_self_heal.py` | Clears stale `core.hooksPath` overrides that Git seeds into fresh worktree local config; called from `preflight.py` |
-| `post_audit_thread.py` | Posts an audit review (APPROVE / REQUEST_CHANGES) to a draft PR via the GitHub reviews API; reads the body skeleton from `audit-reply-template.md` at runtime |
-| `grant_project_claude_permissions.py` | Writes idempotent allow-rules and `additionalDirectories` entries into `~/.claude/settings.json` so subagents can edit the project's `.claude/` tree without prompting |
-| `revoke_project_claude_permissions.py` | Removes the allow-rules and entries that `grant_project_claude_permissions.py` wrote; safe to run when no prior grant exists |
-| `stale_worktree_rule_sweep.py` | Drops allow/deny rules pointing at deleted `~/.claude/worktrees/<repo>/<worktree>` directories and deduplicates the rule arrays; run by the grant and revoke flows before they write |
-| `code_rules_gate.py` | Pre-commit gate that runs `code_rules_enforcer` checks on staged Python files before a fix commit lands, and the terminology sweep over the staged diff |
-| `terminology_sweep.py` | Flags a prose term that near-misses an identifier introduced on added code lines of a unified diff (shared leading word, divergent tail) |
-| `reviews_disabled.py` | Shared helper for the reviewer opt-out and opt-in gates; parses `CLAUDE_REVIEWS_DISABLED` tokens `bugteam`, `bugbot`, `copilot`, and `codex`, plus `CLAUDE_REVIEWS_ENABLED` for opt-in. `bugbot`, `bugteam`, and `codex` are off by default and each runs only when `CLAUDE_REVIEWS_ENABLED` lists it; `copilot` runs by default and stops only when `CLAUDE_REVIEWS_DISABLED` lists it |
-| `copilot_quota.py` | Copilot premium-request quota pre-check: resolves a configured GitHub account, reads its remaining `premium_interactions` quota via `gh api copilot_internal/user`, and exits 0 (run Copilot) or non-zero (skip: out of quota, API down, or no account configured) |
-| `reviewer_availability.py` | Unified reviewer-availability entry point for Copilot and Bugbot: reuses `copilot_quota.py` and `reviews_disabled.py` and exits 0 when the named `--reviewer` may be spawned, non-zero when it is opted out or (for Copilot) out of quota |
-| `fix_hookspath.py` | Repairs a malformed `core.hooksPath` global git config entry |
-| `_claude_permissions_common.py` | Internal helpers shared by the grant/revoke scripts: atomic settings.json writes, list mutation, path helpers |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `code_rules_gate_parts/` | The decomposed modules `code_rules_gate.py` wires together: enforcer loading, git file sets, blob readers, added-line maps, violation scoping, wrapper plumb-through, gate running, staged-test running, and argument parsing |
-| `pr_loop_shared_constants/` | Named constants used by the scripts above |
-| `tests/` | pytest suite for all scripts in this directory |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/_shared/pr-loop/scripts/tests/
-```
+@AGENTS.md

package/_shared/pr-loop/scripts/code_rules_gate.py

@@ -116,9 +116,8 @@ def _report_partitioned_violations(
 ) -> int:
     """Print the violation sections and return the gate exit code.
 
-    Importers outside this directory (the code-verifier spawn-preflight hook)
-    call this surface with the partition spread across positional arguments,
-    so this wrapper keeps that calling shape and folds the pieces into the
+    External callers pass the partition across positional arguments, so this
+    wrapper keeps that calling shape and folds the pieces into the
     ``PartitionedViolations`` tuple the gate-running module consumes.
 
     Args:

package/_shared/pr-loop/scripts/code_rules_gate_parts/AGENTS.md

@@ -0,0 +1,42 @@
+# code_rules_gate_parts
+
+The modules `code_rules_gate.py` wires together to run the code-rules gate. Each
+module owns one concern; the entry script imports them and re-exports their
+surface for the test suite.
+
+## Modules
+
+| File | Purpose |
+|---|---|
+| `enforcer_loading.py` | Locates and loads `code_rules_enforcer.validate_content` from disk with the hooks directory on `sys.path` |
+| `git_file_sets.py` | Resolves the diff, staged, and untracked file sets from git, plus prefix filtering and staged line-span helpers |
+| `git_blob_readers.py` | Reads the committed and staged content of one file, and probes staged-index presence |
+| `added_line_maps.py` | Maps each changed file to the line numbers the current diff added, resolving renames and new files |
+| `violation_scoping.py` | Recovers a violation's line span from the enforcer message and partitions violations into blocking versus advisory |
+| `wrapper_plumb_check.py` | Flags a public wrapper that drops a same-file delegate's optional keyword arguments; holds the code-path and test-path classifiers |
+| `gate_running.py` | Validates the eligible file set, reports the inspected-file count, and prints the partitioned violation report |
+| `staged_test_running.py` | Runs one staged-test group, grouped by its owning pytest config and by top-level directory when no config owns it, in command-line-length-safe pytest batches, optionally writing a JUnit XML report per batch |
+| `staged_test_regression.py` | Discovers the staged test files, runs every group, and blocks only on a failure the staged change introduces — a group that fails is re-run against the HEAD baseline (a throwaway detached checkout made with `git worktree add --detach` under the OS temp root, deleted with `git worktree remove --force`) and only a failure absent there blocks |
+| `baseline_import_isolation.py` | Points the baseline run's imports at the baseline worktree — rebases every repository import root onto the front of its `PYTHONPATH` — and installs the pytest plugin that reports which modules the run loaded out of the user's own tree, so a route that survives the rebase is measured and the baseline discarded |
+| `gate_arguments.py` | Parses the gate's command-line arguments |
+| `__init__.py` | Package marker |
+
+## Staged-test grouping boundaries
+
+The top-level fallback in `staged_test_running.py` fires only in a repository
+whose root holds no pytest config, and it splits top-level neighbors alone:
+
+- Config-less packages that sit deeper under one shared top-level directory, such as `pkgs/alpha` and `pkgs/beta`, share that directory's single pytest session, so a module name they both expose still shadows.
+- A `conftest.py` at the repository root stays unloaded for those groups, because each session works from the top-level directory and the root file falls outside the tree pytest treats as its root.
+
+## Subdirectory
+
+| Entry | Description |
+|---|---|
+| `tests/` | pytest suite with one test module per module above, plus `_repo_test_helpers.py` (shared real-git-repository builders) |
+
+## Running tests
+
+```bash
+python -m pytest packages/claude-dev-env/_shared/pr-loop/scripts/code_rules_gate_parts/tests/
+```

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

@@ -1,42 +1 @@
-# code_rules_gate_parts
-
-The modules `code_rules_gate.py` wires together to run the code-rules gate. Each
-module owns one concern; the entry script imports them and re-exports their
-surface for the test suite.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `enforcer_loading.py` | Locates and loads `code_rules_enforcer.validate_content` from disk with the hooks directory on `sys.path` |
-| `git_file_sets.py` | Resolves the diff, staged, and untracked file sets from git, plus prefix filtering and staged line-span helpers |
-| `git_blob_readers.py` | Reads the committed and staged content of one file, and probes staged-index presence |
-| `added_line_maps.py` | Maps each changed file to the line numbers the current diff added, resolving renames and new files |
-| `violation_scoping.py` | Recovers a violation's line span from the enforcer message and partitions violations into blocking versus advisory |
-| `wrapper_plumb_check.py` | Flags a public wrapper that drops a same-file delegate's optional keyword arguments; holds the code-path and test-path classifiers |
-| `gate_running.py` | Validates the eligible file set, reports the inspected-file count, and prints the partitioned violation report |
-| `staged_test_running.py` | Runs one staged-test group, grouped by its owning pytest config and by top-level directory when no config owns it, in command-line-length-safe pytest batches, optionally writing a JUnit XML report per batch |
-| `staged_test_regression.py` | Discovers the staged test files, runs every group, and blocks only on a failure the staged change introduces — a group that fails is re-run against the HEAD baseline (a throwaway detached checkout made with `git worktree add --detach` under the OS temp root, deleted with `git worktree remove --force`) and only a failure absent there blocks |
-| `baseline_import_isolation.py` | Points the baseline run's imports at the baseline worktree — rebases every repository import root onto the front of its `PYTHONPATH` — and installs the pytest plugin that reports which modules the run loaded out of the user's own tree, so a route that survives the rebase is measured and the baseline discarded |
-| `gate_arguments.py` | Parses the gate's command-line arguments |
-| `__init__.py` | Package marker |
-
-## Staged-test grouping boundaries
-
-The top-level fallback in `staged_test_running.py` fires only in a repository
-whose root holds no pytest config, and it splits top-level neighbors alone:
-
-- Config-less packages that sit deeper under one shared top-level directory, such as `pkgs/alpha` and `pkgs/beta`, share that directory's single pytest session, so a module name they both expose still shadows.
-- A `conftest.py` at the repository root stays unloaded for those groups, because each session works from the top-level directory and the root file falls outside the tree pytest treats as its root.
-
-## Subdirectory
-
-| Entry | Description |
-|---|---|
-| `tests/` | pytest suite with one test module per module above, plus `_repo_test_helpers.py` (shared real-git-repository builders) |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/_shared/pr-loop/scripts/code_rules_gate_parts/tests/
-```
+@AGENTS.md

package/_shared/pr-loop/scripts/pr_loop_shared_constants/AGENTS.md

@@ -0,0 +1,26 @@
+# pr_loop_shared_constants
+
+Named constants for every script in `_shared/pr-loop/scripts/`. Each module owns the constants for one script; the module name mirrors the script name with a `_constants` suffix.
+
+## Modules
+
+| File | Constants for |
+|---|---|
+| `claude_permissions_constants.py` | `grant_project_claude_permissions.py` and `revoke_project_claude_permissions.py` — permission rule strings and settings.json keys |
+| `claude_settings_keys_constants.py` | Top-level `~/.claude/settings.json` key names used across the permission helpers |
+| `stale_worktree_rule_sweep_constants.py` | `stale_worktree_rule_sweep.py` — the worktrees subdirectory name, the worktree path segment count, the rule-string delimiters, the `.claude` home path marker, and `get_claude_worktrees_root` |
+| `code_rules_gate_constants.py` | `code_rules_gate.py` — file extensions, git diff subcommands, test filename patterns |
+| `inline_duplicate_body_span_constants.py` | `code_rules_gate.py` — regex and capture-group indices for the same-file inline-duplicate message, which carries both the helper and the enclosing span the gate reconstructs the union from |
+| `fix_hookspath_constants.py` | `fix_hookspath.py` — verification suffix and related strings |
+| `post_audit_thread_constants.py` | `post_audit_thread.py` — HTTP status codes, retry counts, GitHub API paths |
+| `preflight_constants.py` | `preflight.py` — env-var names, git subcommands, pytest exit codes, test discovery patterns |
+| `preflight_self_heal_constants.py` | `preflight_self_heal.py` — git config keys and local-scope detection strings |
+| `reviews_disabled_constants.py` | `reviews_disabled.py` — `CLAUDE_REVIEWS_DISABLED` and `CLAUDE_REVIEWS_ENABLED` env-var names and token taxonomy |
+| `copilot_quota_constants.py` | `copilot_quota.py` — `COPILOT_QUOTA_ACCOUNT` env-var name, `copilot_internal/user` API path, the `premium_interactions` gating field names, the four skip/run exit codes, and the default `.env` path |
+| `terminology_sweep_constants.py` | `terminology_sweep.py` — identifier and prose-token regexes, diff-parsing prefixes, code-file extensions, test-file detection patterns, and the finding-message template |
+| `reviewer_availability_constants.py` | `reviewer_availability.py` — the available/down exit codes for the unified reviewer-availability pre-check |
+| `__init__.py` | Empty package marker |
+
+## Convention
+
+Every constant is `UPPER_SNAKE_CASE` with an explicit type annotation. No magic literals appear in the consuming scripts — all values live here. Test coverage for each module lives in `tests/test_<module_name>.py`.

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

@@ -1,26 +1 @@
-# pr_loop_shared_constants
-
-Named constants for every script in `_shared/pr-loop/scripts/`. Each module owns the constants for one script; the module name mirrors the script name with a `_constants` suffix.
-
-## Modules
-
-| File | Constants for |
-|---|---|
-| `claude_permissions_constants.py` | `grant_project_claude_permissions.py` and `revoke_project_claude_permissions.py` — permission rule strings and settings.json keys |
-| `claude_settings_keys_constants.py` | Top-level `~/.claude/settings.json` key names used across the permission helpers |
-| `stale_worktree_rule_sweep_constants.py` | `stale_worktree_rule_sweep.py` — the worktrees subdirectory name, the worktree path segment count, the rule-string delimiters, the `.claude` home path marker, and `get_claude_worktrees_root` |
-| `code_rules_gate_constants.py` | `code_rules_gate.py` — file extensions, git diff subcommands, test filename patterns |
-| `inline_duplicate_body_span_constants.py` | `code_rules_gate.py` — regex and capture-group indices for the same-file inline-duplicate message, which carries both the helper and the enclosing span the gate reconstructs the union from |
-| `fix_hookspath_constants.py` | `fix_hookspath.py` — verification suffix and related strings |
-| `post_audit_thread_constants.py` | `post_audit_thread.py` — HTTP status codes, retry counts, GitHub API paths |
-| `preflight_constants.py` | `preflight.py` — env-var names, git subcommands, pytest exit codes, test discovery patterns |
-| `preflight_self_heal_constants.py` | `preflight_self_heal.py` — git config keys and local-scope detection strings |
-| `reviews_disabled_constants.py` | `reviews_disabled.py` — `CLAUDE_REVIEWS_DISABLED` and `CLAUDE_REVIEWS_ENABLED` env-var names and token taxonomy |
-| `copilot_quota_constants.py` | `copilot_quota.py` — `COPILOT_QUOTA_ACCOUNT` env-var name, `copilot_internal/user` API path, the `premium_interactions` gating field names, the four skip/run exit codes, and the default `.env` path |
-| `terminology_sweep_constants.py` | `terminology_sweep.py` — identifier and prose-token regexes, diff-parsing prefixes, code-file extensions, test-file detection patterns, and the finding-message template |
-| `reviewer_availability_constants.py` | `reviewer_availability.py` — the available/down exit codes for the unified reviewer-availability pre-check |
-| `__init__.py` | Empty package marker |
-
-## Convention
-
-Every constant is `UPPER_SNAKE_CASE` with an explicit type annotation. No magic literals appear in the consuming scripts — all values live here. Test coverage for each module lives in `tests/test_<module_name>.py`.
+@AGENTS.md

package/_shared/pr-loop/scripts/test_code_rules_gate.py

@@ -250,29 +250,3 @@ def _gate_import_names_in_source(module_source: str) -> set[str]:
         for each_line in import_block.splitlines()
         if each_line.strip() and not each_line.strip().startswith("#")
     }
-
-
-def test_entry_exposes_every_symbol_the_preflight_hook_imports() -> None:
-    """The gate entry re-exports the whole surface the spawn-preflight hook uses.
-
-    The code-verifier spawn-preflight hook imports gate helpers by name at
-    runtime; a name the entry drops breaks that hook's import and silently
-    turns its deny paths into allows.
-    """
-    hook_path = (
-        Path(__file__).resolve().parents[3]
-        / "hooks"
-        / "blocking"
-        / "code_verifier_spawn_preflight_gate.py"
-    )
-    hook_imported_names = _gate_import_names_in_source(
-        hook_path.read_text(encoding="utf-8")
-    )
-
-    assert hook_imported_names, "hook no longer imports from code_rules_gate"
-    missing_names = sorted(
-        each_name
-        for each_name in hook_imported_names
-        if not hasattr(gate_module, each_name)
-    )
-    assert not missing_names, f"gate entry drops hook imports: {missing_names}"

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

@@ -0,0 +1,44 @@
+# _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/
+```

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