claude-dev-env 2.12.0 → 2.14.0

package/scripts/validate_instruction_pairs.py

@@ -0,0 +1,183 @@
+"""Validate exact Claude instruction imports and regular Git file modes."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import stat
+import subprocess
+from pathlib import Path
+
+git_directory_name = ".git"
+git_listing_commands = (
+    (("git", "ls-files", "--stage", "-z"), True),
+    (("git", "ls-files", "--others", "--exclude-standard", "-z"), False),
+)
+ascii_encoding_name = "ascii"
+utf8_encoding_name = "utf-8"
+regular_git_file_mode = "100644"
+canonical_instruction_names = frozenset(("AGENTS.md", "CLAUDE.md"))
+logger = logging.getLogger(__name__)
+
+
+def _read_git_paths_and_modes(
+    repository_root: Path,
+) -> tuple[set[Path], dict[Path, set[str]]]:
+    all_git_paths: set[Path] = set()
+    modes_by_path: dict[Path, set[str]] = {}
+    for each_command, each_has_git_mode in git_listing_commands:
+        completed_process = subprocess.run(
+            each_command,
+            cwd=repository_root,
+            capture_output=True,
+            check=True,
+        )
+        for each_record in completed_process.stdout.split(b"\0"):
+            if not each_record:
+                continue
+            if each_has_git_mode:
+                each_header, each_path_bytes = each_record.split(b"\t", 1)
+                each_mode = each_header.split(b" ", 1)[0].decode(ascii_encoding_name)
+                each_path = repository_root / Path(os.fsdecode(each_path_bytes))
+                modes_by_path.setdefault(each_path, set()).add(each_mode)
+            else:
+                each_path = repository_root / Path(os.fsdecode(each_record))
+            all_git_paths.add(each_path)
+    return all_git_paths, modes_by_path
+
+
+def _discover_named_files(
+    repository_root: Path,
+    all_git_paths: set[Path],
+    expected_name: str,
+) -> list[Path]:
+    all_candidate_paths = set(all_git_paths)
+    all_candidate_paths.update(repository_root.rglob("*"))
+    return sorted(
+        each_path
+        for each_path in all_candidate_paths
+        if git_directory_name not in each_path.parts
+        and each_path.name.casefold() == expected_name.casefold()
+    )
+
+
+def _find_nearest_agents_path(
+    claude_path: Path,
+    repository_root: Path,
+    agents_by_directory: dict[Path, Path],
+) -> Path | None:
+    each_directory = claude_path.parent
+    while True:
+        each_agents_path = agents_by_directory.get(each_directory)
+        if each_agents_path is not None:
+            return each_agents_path
+        if each_directory == repository_root:
+            return None
+        each_directory = each_directory.parent
+
+
+def _relative_import_path(claude_path: Path, agents_path: Path) -> str:
+    return Path(os.path.relpath(agents_path, claude_path.parent)).as_posix()
+
+
+def _expected_import_text(claude_path: Path, agents_path: Path) -> bytes:
+    return f"@{_relative_import_path(claude_path, agents_path)}\n".encode(
+        utf8_encoding_name
+    )
+
+
+def _is_regular_file(each_path: Path) -> bool:
+    try:
+        return stat.S_ISREG(each_path.lstat().st_mode)
+    except FileNotFoundError:
+        return False
+
+
+def validate_repository(repository_root: Path) -> list[str]:
+    """Validate instruction filenames, modes, and exact Claude imports.
+
+    Args:
+        repository_root: Repository directory containing the Git metadata.
+
+    Returns:
+        Human-readable validation errors, with an empty list for a valid tree.
+    """
+    repository_root = repository_root.resolve()
+    all_errors: list[str] = []
+    all_git_paths, modes_by_path = _read_git_paths_and_modes(repository_root)
+    all_agents_paths = _discover_named_files(
+        repository_root, all_git_paths, "AGENTS.md"
+    )
+    all_claude_paths = _discover_named_files(
+        repository_root, all_git_paths, "CLAUDE.md"
+    )
+    agents_by_directory = {
+        each_path.parent: each_path
+        for each_path in all_agents_paths
+        if each_path.name == "AGENTS.md"
+    }
+
+    for each_instruction_path in (*all_agents_paths, *all_claude_paths):
+        relative_path = each_instruction_path.relative_to(repository_root)
+        tracked_modes = modes_by_path.get(each_instruction_path, set())
+        if each_instruction_path.name not in canonical_instruction_names:
+            all_errors.append(f"Use the canonical filename: {relative_path}")
+        if not _is_regular_file(each_instruction_path):
+            all_errors.append(f"Use a regular file: {relative_path}")
+        if tracked_modes != {regular_git_file_mode}:
+            all_errors.append(
+                f"Commit the instruction file with Git mode 100644: {relative_path}"
+            )
+
+    for each_claude_path in all_claude_paths:
+        relative_claude_path = each_claude_path.relative_to(repository_root)
+        each_agents_path = _find_nearest_agents_path(
+            each_claude_path, repository_root, agents_by_directory
+        )
+        if each_agents_path is None:
+            all_errors.append(f"Add the nearest governing AGENTS.md: {relative_claude_path}")
+            continue
+        if not _is_regular_file(each_claude_path):
+            continue
+        expected_bytes = _expected_import_text(each_claude_path, each_agents_path)
+        actual_bytes = each_claude_path.read_bytes()
+        if actual_bytes != expected_bytes:
+            relative_import_path = _relative_import_path(
+                each_claude_path, each_agents_path
+            )
+            relative_agents_path = each_agents_path.relative_to(repository_root)
+            all_errors.append(
+                f"Make {relative_claude_path} exactly import "
+                f"@{relative_import_path} for {relative_agents_path}"
+            )
+
+    return all_errors
+
+
+def _parse_arguments() -> argparse.Namespace:
+    argument_parser = argparse.ArgumentParser(
+        description="Validate exact CLAUDE.md imports and regular AGENTS.md files."
+    )
+    argument_parser.add_argument(
+        "--repository-root",
+        type=Path,
+        default=Path.cwd(),
+        help="Repository root containing the .git directory.",
+    )
+    return argument_parser.parse_args()
+
+
+def _main() -> int:
+    parsed_arguments = _parse_arguments()
+    repository_root = parsed_arguments.repository_root.resolve()
+    all_errors = validate_repository(repository_root)
+    if all_errors:
+        for each_error in all_errors:
+            logger.error("%s", each_error)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main())

package/settings.json

@@ -1,10 +1 @@
-{
-  "permissions": {
-    "deny": [
-      "Edit($HOME/.claude/verification/**)",
-      "Write($HOME/.claude/code-review-stamps/**)",
-      "Edit($HOME/.claude/code-review-stamps/**)",
-      "MultiEdit($HOME/.claude/code-review-stamps/**)"
-    ]
-  }
-}
+{}

package/skills/AGENTS.md

@@ -0,0 +1,72 @@
+# Skills Directory
+
+Each skill is a self-contained folder Claude Code loads on demand. At startup, only the skill's `name` and `description` metadata load. The full `SKILL.md` body and any support files load only when a skill becomes relevant to the conversation.
+
+## Skill folder convention
+
+| Item | Role |
+|---|---|
+| `SKILL.md` | Required entry point. YAML frontmatter with `name` and `description` (the trigger). Body holds the skill's full instructions. |
+| `scripts/` | Python helper scripts the skill invokes at runtime. |
+| `workflow/` | `.mjs` workflow scripts run via the `Workflow` tool. |
+| `templates/` | Template files the skill or workflow renders at build time. |
+| `reference/` | Reference docs the skill cites or the workflow reads. |
+| `*_constants/` | Python package of named constants imported by `scripts/`. |
+
+Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/bin/install.mjs`. See `docs/references/skill-install-system.md` for the install pipeline.
+
+## Shared support code
+
+**`skills/_shared/`** — skill-local PR-loop helpers plus `@` stubs that name
+canonical homes under **`@~/.claude/_shared/`** (advisor protocol, PR-loop
+contracts, runtime scripts). Map: `skills/_shared/CLAUDE.md`. End-of-run gotchas: `skills/_shared/end-of-run-gotcha-recommendations.md`.
+
+## Skill groups
+
+**Planning and implementation**
+- `anthropic-plan` — creates a source-grounded plan packet before any code changes
+- `orchestrator` — turns the session into the orchestrator: it spawns executor subagents to do the code edits and test runs; hard decisions go to a shared advisor (Claude warm `session-advisor` via SendMessage; a third-party host: max-tier Claude via CLI Claude-chain)
+- `orchestrator-refresh` — sub-skill fired by the `/orchestrator` loop to re-assert the host-matched shared-advisor discipline mid-run (Claude SendMessage; a third-party host's Claude CLI chain, no Agent-tool advisor spawn)
+- `team-advisor` — binds one advisor at the strongest reachable tier (Claude warm agent; a third-party host: max-tier Claude via CLI Claude-chain, fail closed when unreachable); consult cadence and weight live in `docs/references/advisor-tool.md`
+- `grokify` — builds a paste-ready Grok Build handoff with a Claude advisor charter
+- `grok-spawn` — orchestrator playbook for fleets of headless grok CLI workers (preflight, batch spec, `spawn_grok_batch.py`)
+
+**PR review and convergence**
+- `autoconverge` — autonomous single-run workflow that drives a PR to ready
+- `pr-converge` — paced convergence loop across `ScheduleWakeup` ticks
+- `bugteam` — open-loop audit-fix until convergence
+- `copilot-review` — requests and polls a GitHub Copilot review
+- `copilot-finding-triage` — tiers each Copilot gate finding, verifies each code concern with an executed check, then routes it (auto-fix a confirmed defect, resolve a refuted one, page the user only for an inconclusive one)
+- `reviewer-gates` — availability gates for external reviewers (opt-out parse, Copilot quota, Bugbot trigger/detect)
+- `pr-fix-protocol` — applies reviewer findings as verified fixes and drives unresolved review threads to zero
+- `pr-loop-lifecycle` — opens and closes a PR-loop run (grant, teardown, PR description, revoke, report)
+- `pr-loop-cloud-transport` — six-step transport workflow that lets any PR-loop skill run in a session whose `gh` CLI is absent or cannot act on the PR (MCP schema load, origin/HEAD fix, identity rules, the gh-to-MCP substitution matrix, the Copilot status rule, and the post self-check)
+
+**Code review guides (Google eng-practices, adapted for an AI reviewer)**
+- `small-cl` — the Small CLs guide; refs: handling reviewer comments
+- `comments` — writing review comments and handling reviewer comments; refs: the review standard, pushback, respectful code reviews
+- `reviews` — the reviewer guide: standard, what to look for, navigating a CL, speed, pushback; refs: CL descriptions, review comments, emergencies, style guides, the two guide indexes
+- `descriptions` — writing good CL descriptions
+- `emergencies` — what counts as an emergency change; refs: what to look for, speed
+- Focused pull request guidance: [`small-cl/SKILL.md`](small-cl/SKILL.md)
+
+**Research and discovery**
+- `recall` — retrieves facts from memory files
+- `remember` — saves a decision, gotcha, or architectural choice to the Obsidian vault
+- `everything-search` — file-system search via the Everything `es.exe` CLI
+- `beat-sheet` — reformats a reply as short single-line beats
+- `show` — creates and reviews inline visual explanations: diagrams, interactive widgets, mockups, charts, and illustrations
+
+**Session and workflow management**
+- `session-log` — logs a session report to the Obsidian vault
+- `session-tidy` — tidies the session folder
+- `task-build` — gathers open tasks
+- `issue-tracker` — one consistent way to create, update in place, and close GitHub issues for a work-stream: one epic parent with native sub-issues, dedup-first, marker-delimited body sections edited in place, and an epic checklist mirroring the children
+- `closeout` — session-end entry that harvests obstacles into issue-candidate records and delegates filing to the `issue-tracker` agent (skill fallback), keeping the user-validation gate on each draft
+- `privacy-hygiene` — full-repo personal-data and secret sweep plus remediation guide
+- `update` — updates the dev-env package
+- `fresh-branch` — creates a clean branch off main
+- `rebase` — rebases onto main
+- `usage-pause` — waits out the 5-hour usage window in ScheduleWakeup stages that keep agent contexts warm; probes the OAuth usage endpoint or takes a manual reset override
+- `skill-builder` — complete skill-building lifecycle
+- `auditing-claude-config` — audits a Claude Code setup for context-budget waste and produces a migration table with savings

package/skills/CLAUDE.md

@@ -1,64 +1 @@
-# Skills Directory
-
-Each skill is a self-contained folder Claude Code loads on demand. At startup, only the skill's `name` and `description` metadata load. The full `SKILL.md` body and any support files load only when a skill becomes relevant to the conversation.
-
-## Skill folder convention
-
-| Item | Role |
-|---|---|
-| `SKILL.md` | Required entry point. YAML frontmatter with `name` and `description` (the trigger). Body holds the skill's full instructions. |
-| `scripts/` | Python helper scripts the skill invokes at runtime. |
-| `workflow/` | `.mjs` workflow scripts run via the `Workflow` tool. |
-| `templates/` | Template files the skill or workflow renders at build time. |
-| `reference/` | Reference docs the skill cites or the workflow reads. |
-| `*_constants/` | Python package of named constants imported by `scripts/`. |
-
-Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/bin/install.mjs`. See `docs/references/skill-install-system.md` for the install pipeline.
-
-## Shared support code
-
-**`skills/_shared/`** — skill-local PR-loop helpers plus `@` stubs that name
-canonical homes under **`@~/.claude/_shared/`** (advisor protocol, PR-loop
-contracts, runtime scripts). Map: `skills/_shared/CLAUDE.md`. End-of-run gotchas: `skills/_shared/end-of-run-gotcha-recommendations.md`.
-
-## Skill groups
-
-**Planning and implementation**
-- `anthropic-plan` — creates a source-grounded plan packet before any code changes
-- `orchestrator` — turns the session into the orchestrator: it spawns executor subagents to do the code edits and test runs; hard decisions go to a shared advisor (Claude warm `session-advisor` via SendMessage; a third-party host: max-tier Claude via CLI Claude-chain)
-- `orchestrator-refresh` — sub-skill fired by the `/orchestrator` loop to re-assert the host-matched shared-advisor discipline mid-run (Claude SendMessage; a third-party host's Claude CLI chain, no Agent-tool advisor spawn)
-- `team-advisor` — binds one advisor at the strongest reachable tier (Claude warm agent; a third-party host: max-tier Claude via CLI Claude-chain, fail closed when unreachable); consult cadence and weight live in `docs/references/advisor-tool.md`
-- `grokify` — builds a paste-ready Grok Build handoff with a Claude advisor charter
-- `grok-spawn` — orchestrator playbook for fleets of headless grok CLI workers (preflight, batch spec, `spawn_grok_batch.py`)
-
-**PR review and convergence**
-- `autoconverge` — autonomous single-run workflow that drives a PR to ready
-- `pr-converge` — paced convergence loop across `ScheduleWakeup` ticks
-- `bugteam` — open-loop audit-fix until convergence
-- `copilot-review` — requests and polls a GitHub Copilot review
-- `copilot-finding-triage` — tiers each Copilot gate finding, verifies each code concern with an executed check, then routes it (auto-fix a confirmed defect, resolve a refuted one, page the user only for an inconclusive one)
-- `reviewer-gates` — availability gates for external reviewers (opt-out parse, Copilot quota, Bugbot trigger/detect)
-- `pr-fix-protocol` — applies reviewer findings as verified fixes and drives unresolved review threads to zero
-- `pr-loop-lifecycle` — opens and closes a PR-loop run (grant, teardown, PR description, revoke, report)
-- `pr-loop-cloud-transport` — six-step transport workflow that lets any PR-loop skill run in a session whose `gh` CLI is absent or cannot act on the PR (MCP schema load, origin/HEAD fix, identity rules, the gh-to-MCP substitution matrix, the Copilot status rule, and the post self-check)
-
-**Research and discovery**
-- `recall` — retrieves facts from memory files
-- `remember` — saves a decision, gotcha, or architectural choice to the Obsidian vault
-- `everything-search` — file-system search via the Everything `es.exe` CLI
-- `beat-sheet` — reformats a reply as short single-line beats
-- `show` — creates and reviews inline visual explanations: diagrams, interactive widgets, mockups, charts, and illustrations
-
-**Session and workflow management**
-- `session-log` — logs a session report to the Obsidian vault
-- `session-tidy` — tidies the session folder
-- `task-build` — gathers open tasks
-- `issue-tracker` — one consistent way to create, update in place, and close GitHub issues for a work-stream: one epic parent with native sub-issues, dedup-first, marker-delimited body sections edited in place, and an epic checklist mirroring the children
-- `closeout` — session-end entry that harvests obstacles into issue-candidate records and delegates filing to the `issue-tracker` agent (skill fallback), keeping the user-validation gate on each draft
-- `privacy-hygiene` — full-repo personal-data and secret sweep plus remediation guide
-- `update` — updates the dev-env package
-- `fresh-branch` — creates a clean branch off main
-- `rebase` — rebases onto main
-- `usage-pause` — waits out the 5-hour usage window in ScheduleWakeup stages that keep agent contexts warm; probes the OAuth usage endpoint or takes a manual reset override
-- `skill-builder` — complete skill-building lifecycle
-- `auditing-claude-config` — audits a Claude Code setup for context-budget waste and produces a migration table with savings
+@AGENTS.md

package/skills/_shared/AGENTS.md

@@ -0,0 +1,44 @@
+# skills/_shared
+
+**Map** for skill-install shared assets. Open a stub, then load the `@` target.
+
+## Two homes
+
+| Home | Path | Holds |
+|---|---|---|
+| **Skills shared** | `~/.claude/skills/_shared/` | Converge helpers, end-of-run gotcha ref, and `@` stubs |
+| **Top-level shared** | `~/.claude/_shared/` | Advisor protocol, PR-loop contracts, runtime scripts |
+
+
+## Reference docs (this tree)
+
+| File | Role |
+|---|---|
+| **`end-of-run-gotcha-recommendations.md`** | End-of-run pasteable gotcha protocol for every skill |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| **`advisor/`** | Stubs → `@~/.claude/_shared/advisor/` |
+| **`pr-loop/`** | Local converge helpers + stubs → `@~/.claude/_shared/pr-loop/` |
+
+## Canonical-path stubs
+
+| Stub here | Load |
+|---|---|
+| `advisor/advisor-protocol.md` | `@~/.claude/_shared/advisor/advisor-protocol.md` |
+| `advisor/CLAUDE.md` | `@~/.claude/_shared/advisor/CLAUDE.md` |
+| `advisor/scripts/README.md` | `@~/.claude/_shared/advisor/scripts/` |
+| `pr-loop/audit-contract.md` | `@~/.claude/_shared/pr-loop/audit-contract.md` |
+| `pr-loop/audit-reply-template.md` | `@~/.claude/_shared/pr-loop/audit-reply-template.md` |
+| `pr-loop/code-rules-gate.md` | `@~/.claude/_shared/pr-loop/code-rules-gate.md` |
+| `pr-loop/fix-protocol.md` | `@~/.claude/_shared/pr-loop/fix-protocol.md` |
+| `pr-loop/gh-payloads.md` | `@~/.claude/_shared/pr-loop/gh-payloads.md` |
+| `pr-loop/post-audit-thread-contract.md` | `@~/.claude/_shared/pr-loop/post-audit-thread-contract.md` |
+| `pr-loop/precatch-rubric.md` | `@~/.claude/_shared/pr-loop/precatch-rubric.md` |
+| `pr-loop/state-schema.md` | `@~/.claude/_shared/pr-loop/state-schema.md` |
+| `pr-loop/worker-spawn.md` | `@~/.claude/_shared/pr-loop/worker-spawn.md` |
+| `pr-loop/scripts/RUNTIME_SCRIPTS.md` | `@~/.claude/_shared/pr-loop/scripts/` |
+
+Install via `packages/claude-dev-env/bin/install.mjs`.

package/skills/_shared/CLAUDE.md

@@ -1,44 +1 @@
-# skills/_shared
-
-**Map** for skill-install shared assets. Open a stub, then load the `@` target.
-
-## Two homes
-
-| Home | Path | Holds |
-|---|---|---|
-| **Skills shared** | `~/.claude/skills/_shared/` | Converge helpers, end-of-run gotcha ref, and `@` stubs |
-| **Top-level shared** | `~/.claude/_shared/` | Advisor protocol, PR-loop contracts, runtime scripts |
-
-
-## Reference docs (this tree)
-
-| File | Role |
-|---|---|
-| **`end-of-run-gotcha-recommendations.md`** | End-of-run pasteable gotcha protocol for every skill |
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| **`advisor/`** | Stubs → `@~/.claude/_shared/advisor/` |
-| **`pr-loop/`** | Local converge helpers + stubs → `@~/.claude/_shared/pr-loop/` |
-
-## Canonical-path stubs
-
-| Stub here | Load |
-|---|---|
-| `advisor/advisor-protocol.md` | `@~/.claude/_shared/advisor/advisor-protocol.md` |
-| `advisor/CLAUDE.md` | `@~/.claude/_shared/advisor/CLAUDE.md` |
-| `advisor/scripts/README.md` | `@~/.claude/_shared/advisor/scripts/` |
-| `pr-loop/audit-contract.md` | `@~/.claude/_shared/pr-loop/audit-contract.md` |
-| `pr-loop/audit-reply-template.md` | `@~/.claude/_shared/pr-loop/audit-reply-template.md` |
-| `pr-loop/code-rules-gate.md` | `@~/.claude/_shared/pr-loop/code-rules-gate.md` |
-| `pr-loop/fix-protocol.md` | `@~/.claude/_shared/pr-loop/fix-protocol.md` |
-| `pr-loop/gh-payloads.md` | `@~/.claude/_shared/pr-loop/gh-payloads.md` |
-| `pr-loop/post-audit-thread-contract.md` | `@~/.claude/_shared/pr-loop/post-audit-thread-contract.md` |
-| `pr-loop/precatch-rubric.md` | `@~/.claude/_shared/pr-loop/precatch-rubric.md` |
-| `pr-loop/state-schema.md` | `@~/.claude/_shared/pr-loop/state-schema.md` |
-| `pr-loop/worker-spawn.md` | `@~/.claude/_shared/pr-loop/worker-spawn.md` |
-| `pr-loop/scripts/RUNTIME_SCRIPTS.md` | `@~/.claude/_shared/pr-loop/scripts/` |
-
-Install via `packages/claude-dev-env/bin/install.mjs`.
+@AGENTS.md

package/skills/_shared/advisor/AGENTS.md

@@ -0,0 +1,9 @@
+# Advisor
+
+**Canonical home:**
+
+@~/.claude/_shared/advisor/CLAUDE.md
+
+@~/.claude/_shared/advisor/advisor-protocol.md
+
+Scripts: `~/.claude/_shared/advisor/scripts/` (`model_tier_run_validator.py`, `codex_sol_advisor.py`, `tier_model_ids.py`, constants under `scripts/config/`).

package/skills/_shared/advisor/CLAUDE.md

@@ -1,9 +1 @@
-# Advisor
-
-**Canonical home:**
-
-@~/.claude/_shared/advisor/CLAUDE.md
-
-@~/.claude/_shared/advisor/advisor-protocol.md
-
-Scripts: `~/.claude/_shared/advisor/scripts/` (`model_tier_run_validator.py`, `codex_sol_advisor.py`, `tier_model_ids.py`, constants under `scripts/config/`).
+@AGENTS.md

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

@@ -0,0 +1,50 @@
+# pr-loop
+
+Shared infrastructure for the PR audit-fix loop used by `bugteam`,
+`pr-converge`, and `autoconverge`. Provides the XML prompt template, Python
+runtime scripts, the portable converge driver protocol, and named constants
+those skills invoke during each loop tick.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `prompts/` | XML agent prompt templates. |
+| `scripts/` | Python scripts for loop state management, prompt building, outcome recording, path resolution, pacer selection, and preflight checks. |
+
+## Canonical-path stubs (`~/.claude/_shared/pr-loop/`)
+
+Open a stub, then load the `@` target:
+
+| Stub here | Load |
+|---|---|
+| `audit-contract.md` | `@~/.claude/_shared/pr-loop/audit-contract.md` |
+| `audit-reply-template.md` | `@~/.claude/_shared/pr-loop/audit-reply-template.md` |
+| `code-rules-gate.md` | `@~/.claude/_shared/pr-loop/code-rules-gate.md` |
+| `fix-protocol.md` | `@~/.claude/_shared/pr-loop/fix-protocol.md` |
+| `gh-payloads.md` | `@~/.claude/_shared/pr-loop/gh-payloads.md` |
+| `post-audit-thread-contract.md` | `@~/.claude/_shared/pr-loop/post-audit-thread-contract.md` |
+| `precatch-rubric.md` | `@~/.claude/_shared/pr-loop/precatch-rubric.md` |
+| `state-schema.md` | `@~/.claude/_shared/pr-loop/state-schema.md` |
+| `worker-spawn.md` | `@~/.claude/_shared/pr-loop/worker-spawn.md` |
+| `scripts/RUNTIME_SCRIPTS.md` | `@~/.claude/_shared/pr-loop/scripts/` |
+
+## Key files (live in this tree)
+
+| File | Role |
+|---|---|
+| `portable-driver.md` | Continuous in-session pacer when Workflow / ScheduleWakeup are absent. |
+| `prompts/pr-consistency-audit.xml` | Structured prompt artifact for the cross-file consistency audit agent. |
+| `scripts/select_converge_pacer.py` | Maps entry skill + host tool flags to `workflow`, `schedule_wakeup`, or `portable`. |
+| `scripts/build_audit_prompt.py` | Assembles the audit agent prompt from loop state and the constants module. |
+| `scripts/build_fix_prompt.py` | Assembles the fix agent prompt from loop state and findings. |
+| `scripts/init_loop_state.py` | Initializes the per-PR loop state JSON file. |
+| `scripts/write_audit_outcomes.py` | Writes the per-loop audit outcome XML into the workspace. |
+| `scripts/write_fix_outcomes.py` | Writes the per-loop fix outcome XML into the workspace. |
+| `scripts/preflight_worktree.py` | Verifies the working directory is a healthy worktree for the target PR's repo. |
+| `scripts/teardown_worktrees.py` | Removes loop worktrees on clean exit. |
+| `scripts/write_handoff.py` | Writes durable resume-handoff files under `~/.claude/runtime/pr-loop/<run-name>/` at each converge checkpoint. |
+| `scripts/_path_resolver.py` | Resolves workspace and worktree paths from PR metadata. |
+| `scripts/_cli_utils.py` | Shared CLI argument parsing helpers. |
+| `scripts/_xml_utils.py` | XML serialization helpers. |
+| `scripts/skills_pr_loop_constants/` | Named constants package imported by the scripts above. |

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

@@ -1,50 +1 @@
-# pr-loop
-
-Shared infrastructure for the PR audit-fix loop used by `bugteam`,
-`pr-converge`, and `autoconverge`. Provides the XML prompt template, Python
-runtime scripts, the portable converge driver protocol, and named constants
-those skills invoke during each loop tick.
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `prompts/` | XML agent prompt templates. |
-| `scripts/` | Python scripts for loop state management, prompt building, outcome recording, path resolution, pacer selection, and preflight checks. |
-
-## Canonical-path stubs (`~/.claude/_shared/pr-loop/`)
-
-Open a stub, then load the `@` target:
-
-| Stub here | Load |
-|---|---|
-| `audit-contract.md` | `@~/.claude/_shared/pr-loop/audit-contract.md` |
-| `audit-reply-template.md` | `@~/.claude/_shared/pr-loop/audit-reply-template.md` |
-| `code-rules-gate.md` | `@~/.claude/_shared/pr-loop/code-rules-gate.md` |
-| `fix-protocol.md` | `@~/.claude/_shared/pr-loop/fix-protocol.md` |
-| `gh-payloads.md` | `@~/.claude/_shared/pr-loop/gh-payloads.md` |
-| `post-audit-thread-contract.md` | `@~/.claude/_shared/pr-loop/post-audit-thread-contract.md` |
-| `precatch-rubric.md` | `@~/.claude/_shared/pr-loop/precatch-rubric.md` |
-| `state-schema.md` | `@~/.claude/_shared/pr-loop/state-schema.md` |
-| `worker-spawn.md` | `@~/.claude/_shared/pr-loop/worker-spawn.md` |
-| `scripts/RUNTIME_SCRIPTS.md` | `@~/.claude/_shared/pr-loop/scripts/` |
-
-## Key files (live in this tree)
-
-| File | Role |
-|---|---|
-| `portable-driver.md` | Continuous in-session pacer when Workflow / ScheduleWakeup are absent. |
-| `prompts/pr-consistency-audit.xml` | Structured prompt artifact for the cross-file consistency audit agent. |
-| `scripts/select_converge_pacer.py` | Maps entry skill + host tool flags to `workflow`, `schedule_wakeup`, or `portable`. |
-| `scripts/build_audit_prompt.py` | Assembles the audit agent prompt from loop state and the constants module. |
-| `scripts/build_fix_prompt.py` | Assembles the fix agent prompt from loop state and findings. |
-| `scripts/init_loop_state.py` | Initializes the per-PR loop state JSON file. |
-| `scripts/write_audit_outcomes.py` | Writes the per-loop audit outcome XML into the workspace. |
-| `scripts/write_fix_outcomes.py` | Writes the per-loop fix outcome XML into the workspace. |
-| `scripts/preflight_worktree.py` | Verifies the working directory is a healthy worktree for the target PR's repo. |
-| `scripts/teardown_worktrees.py` | Removes loop worktrees on clean exit. |
-| `scripts/write_handoff.py` | Writes durable resume-handoff files under `~/.claude/runtime/pr-loop/<run-name>/` at each converge checkpoint. |
-| `scripts/_path_resolver.py` | Resolves workspace and worktree paths from PR metadata. |
-| `scripts/_cli_utils.py` | Shared CLI argument parsing helpers. |
-| `scripts/_xml_utils.py` | XML serialization helpers. |
-| `scripts/skills_pr_loop_constants/` | Named constants package imported by the scripts above. |
+@AGENTS.md

package/skills/_shared/pr-loop/prompts/AGENTS.md

@@ -0,0 +1,9 @@
+# prompts
+
+XML agent prompt templates for the PR audit-fix loop.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `pr-consistency-audit.xml` | Structured prompt artifact for the cross-file consistency audit agent. Defines the agent role, scope anchors, a ten-rule detection workflow, and output format. `bugteam` and `pr-converge` both inject this prompt when running the consistency audit step. |

package/skills/_shared/pr-loop/prompts/CLAUDE.md

@@ -1,9 +1 @@
-# prompts
-
-XML agent prompt templates for the PR audit-fix loop.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `pr-consistency-audit.xml` | Structured prompt artifact for the cross-file consistency audit agent. Defines the agent role, scope anchors, a ten-rule detection workflow, and output format. `bugteam` and `pr-converge` both inject this prompt when running the consistency audit step. |
+@AGENTS.md

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

@@ -0,0 +1,35 @@
+# scripts
+
+Python scripts that run the PR audit-fix loop at runtime. Both `bugteam` and `pr-converge` invoke these scripts during each loop tick.
+
+## Two script homes
+
+| Home | Path |
+|---|---|
+| **Skill-local** (this folder) | Converge helpers: `build_*_prompt.py`, `init_loop_state.py`, `portable_converge_driver.py`, … |
+| **Runtime** (top-level shared) | Gate / preflight / review helpers — see `RUNTIME_SCRIPTS.md` → `@~/.claude/_shared/pr-loop/scripts/` |
+
+## Key files (skill-local)
+
+| File | Role |
+|---|---|
+| `audit_category_schema.py` | Loads the A-Q schema JSON, exports category entries, validates rubric/prompt projections, renders deterministic skeletons. |
+| `build_audit_prompt.py` | Assembles the audit agent prompt from loop state and category constants. |
+| `build_fix_prompt.py` | Assembles the fix agent prompt from loop state and findings XML. |
+| `init_loop_state.py` | Initializes the per-PR `loop-state.json` file in the workspace directory. |
+| `write_audit_outcomes.py` | Writes per-loop audit outcome XML into the workspace. |
+| `write_fix_outcomes.py` | Writes per-loop fix outcome XML into the workspace. |
+| `preflight_worktree.py` | Verifies the working directory is a healthy git worktree for the target PR's repo. Supports `--mode strict` to abort when the repo does not match. |
+| `teardown_worktrees.py` | Removes per-PR worktrees after a clean loop exit. |
+| `write_handoff.py` | Writes durable resume-handoff files under the run's `~/.claude/runtime/pr-loop` directory at each converge checkpoint. |
+| `select_converge_pacer.py` | Selects `workflow`, `schedule_wakeup`, or `portable` for pr-converge / autoconverge from host tool flags. |
+| `build_converge_task_list.py` | Step-1 task list: runnable review gates + final all_runnable_reviews_clean_same_head. |
+| `portable_converge_driver.py` | portable_converge_driver phase machine: open-run and post-step transitions emit JSON next/commands only. |
+| `_path_resolver.py` | Resolves workspace and worktree paths from PR owner, repo, and number. |
+| `_cli_utils.py` | Shared CLI argument parsing helpers (argparse wrappers). |
+| `_xml_utils.py` | XML serialization helpers for outcome files. |
+| `skills_pr_loop_constants/` | Named constants package imported by the scripts above. |
+
+## Tests
+
+Each script has a paired test file (`test_build_audit_prompt.py`, `test_build_fix_prompt.py`, etc.) in this directory. Run with `python -m pytest` from the repo root.

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

@@ -1,35 +1 @@
-# scripts
-
-Python scripts that run the PR audit-fix loop at runtime. Both `bugteam` and `pr-converge` invoke these scripts during each loop tick.
-
-## Two script homes
-
-| Home | Path |
-|---|---|
-| **Skill-local** (this folder) | Converge helpers: `build_*_prompt.py`, `init_loop_state.py`, `portable_converge_driver.py`, … |
-| **Runtime** (top-level shared) | Gate / preflight / review helpers — see `RUNTIME_SCRIPTS.md` → `@~/.claude/_shared/pr-loop/scripts/` |
-
-## Key files (skill-local)
-
-| File | Role |
-|---|---|
-| `audit_category_schema.py` | Loads the A-Q schema JSON, exports category entries, validates rubric/prompt projections, renders deterministic skeletons. |
-| `build_audit_prompt.py` | Assembles the audit agent prompt from loop state and category constants. |
-| `build_fix_prompt.py` | Assembles the fix agent prompt from loop state and findings XML. |
-| `init_loop_state.py` | Initializes the per-PR `loop-state.json` file in the workspace directory. |
-| `write_audit_outcomes.py` | Writes per-loop audit outcome XML into the workspace. |
-| `write_fix_outcomes.py` | Writes per-loop fix outcome XML into the workspace. |
-| `preflight_worktree.py` | Verifies the working directory is a healthy git worktree for the target PR's repo. Supports `--mode strict` to abort when the repo does not match. |
-| `teardown_worktrees.py` | Removes per-PR worktrees after a clean loop exit. |
-| `write_handoff.py` | Writes durable resume-handoff files under the run's `~/.claude/runtime/pr-loop` directory at each converge checkpoint. |
-| `select_converge_pacer.py` | Selects `workflow`, `schedule_wakeup`, or `portable` for pr-converge / autoconverge from host tool flags. |
-| `build_converge_task_list.py` | Step-1 task list: runnable review gates + final all_runnable_reviews_clean_same_head. |
-| `portable_converge_driver.py` | portable_converge_driver phase machine: open-run and post-step transitions emit JSON next/commands only. |
-| `_path_resolver.py` | Resolves workspace and worktree paths from PR owner, repo, and number. |
-| `_cli_utils.py` | Shared CLI argument parsing helpers (argparse wrappers). |
-| `_xml_utils.py` | XML serialization helpers for outcome files. |
-| `skills_pr_loop_constants/` | Named constants package imported by the scripts above. |
-
-## Tests
-
-Each script has a paired test file (`test_build_audit_prompt.py`, `test_build_fix_prompt.py`, etc.) in this directory. Run with `python -m pytest` from the repo root.
+@AGENTS.md