claude-dev-env 1.28.0 → 1.29.0

package/skills/bugteam/reference/audit-contract.md

@@ -0,0 +1,159 @@
+# Audit contract
+
+Shared output schema and audit-loop contract used by `/bugteam`, `/qbug`, `/findbugs`, and `/fixbugs`. Changing a shape here is a breaking change for every consuming skill.
+
+## Contents
+
+- Finding schema (Shape A, Shape B)
+- Adversarial second pass
+- Haiku secondary auditor
+- Post-fix self-audit
+- Persistence (loop-N-audit.json, loop-N-diagnostics.json)
+
+## Finding schema
+
+Each finding an audit produces MUST be one of exactly two shapes.
+
+### Shape A — structured finding
+
+```json
+{
+  "id": "loop<N>-<K>",
+  "file": "path/relative/to/repo/root.py",
+  "line": 123,
+  "category": "A | B | C | D | E | F | G | H | I | J",
+  "severity": "P0 | P1 | P2",
+  "excerpt": "verbatim code snippet from the offending line(s)",
+  "failure_mode": "one sentence describing what goes wrong and when",
+  "evidence_files": ["additional/files/opened.py"]
+}
+```
+
+`id` is `loop<N>-<K>` where `N` is the loop counter (1-based) and `K` is the 1-based index within the loop. For `/findbugs` which runs once, use `find<K>`.
+
+### Shape B — structured proof-of-absence
+
+Used when an audit investigates a category and does NOT find a bug. Bare "verified clean" claims are REJECTED because they hide shallow reading.
+
+```json
+{
+  "category": "A | B | C | D | E | F | G | H | I | J",
+  "files_opened": ["file1.py", "file2.py"],
+  "lines_quoted": [
+    {"file": "file1.py", "line": 88, "text": "verbatim line content"}
+  ],
+  "adversarial_probes": [
+    "what failure mode was tested for and how it was ruled out"
+  ]
+}
+```
+
+Every category an audit touches MUST have either at least one Shape A finding OR at least one Shape B proof-of-absence entry. A category with neither is a protocol violation.
+
+### Example — Shape A
+
+```json
+{
+  "id": "loop1-1",
+  "file": "scripts/db/neon.py",
+  "line": 43,
+  "category": "C",
+  "severity": "P1",
+  "excerpt": "load_dotenv(env_path, override=False)",
+  "failure_mode": "Called on every connect() — repeats file I/O per connection in scripts that open multiple short-lived connections.",
+  "evidence_files": ["scripts/db/neon.py", "scripts/update_new_releases.py"]
+}
+```
+
+### Example — Shape B
+
+```json
+{
+  "category": "H",
+  "files_opened": ["scripts/db/neon.py", "scripts/db/config.py"],
+  "lines_quoted": [
+    {"file": "scripts/db/neon.py", "line": 30, "text": "dsn = os.environ.get(\"DATABASE_URL\")"}
+  ],
+  "adversarial_probes": [
+    "Checked whether DATABASE_URL is interpolated into a shell — it is passed to psycopg.connect() directly with no shell involvement.",
+    "Checked whether the env path is user-controlled — it is derived from a fixed Y: drive constant, not user input."
+  ]
+}
+```
+
+## Adversarial second pass
+
+After the primary finding list is complete, every audit runs a second pass against itself with the prompt:
+
+> Assume your first pass missed at least 3 P1 bugs. Where are they?
+
+The audit must either produce new Shape A findings citing new file:line references not present in the first pass, or cite explicit Shape B adversarial-probe entries for each category it re-examined. An adversarial pass that returns "nothing new, confident first pass was complete" is REJECTED — produce evidence or findings, not confidence.
+
+## Haiku secondary auditor
+
+For single-subagent skills (`/qbug`, `/findbugs`) the LEAD spawns two `Agent()` calls in one message:
+
+- **Primary** — `subagent_type=clean-coder`, `model=sonnet` (for qbug cycle) or `subagent_type=code-quality-agent`, `model=sonnet` (for findbugs clean-room).
+- **Secondary (Haiku)** — `subagent_type=code-quality-agent`, `model=haiku`, same self-contained clean-room prompt shape used by `/findbugs`.
+
+Both audit the same diff. The secondary returns findings to the LEAD only — never posted to the PR.
+
+Merge rules:
+
+- **De-dup key**: `(file, line, category)`.
+- **Severity conflict**: max wins (P0 > P1 > P2).
+- **Unique-to-Haiku findings**: added to the primary set with Haiku's severity and source annotation.
+- **Unique-to-primary findings**: kept as-is.
+- **Zero Haiku findings**: primary set trusted; proceed.
+- **Malformed or non-parseable Haiku output**: lead trusts the primary set, logs the event in `loop-<N>-diagnostics.json` under `haiku_findings` as `[{"parse_error": "<message>"}]`.
+
+For multi-subagent skills (`/bugteam`) the parallel-auditors pattern in [`audit-and-teammates.md`](audit-and-teammates.md) already provides cross-model coverage via the three variant teammates.
+
+## Post-fix self-audit
+
+Audit-and-fix skills (`/qbug`, `/bugteam`) MUST re-audit modified files between `py_compile` and `git add`. This catches fix-induced regressions in the same loop that introduced them rather than on loop N+1.
+
+Sequence:
+
+1. Capture pre-fix file contents for every file this FIX will touch.
+2. Apply edits.
+3. Run `py_compile` (or language-equivalent) on each modified file.
+4. Compute `fix_diff` against pre-fix contents for the modified set.
+5. Run `bugteam_code_rules_gate.py` with explicit paths for every modified file.
+6. Spawn a scoped audit of `fix_diff` with full A–J rigor, Shape A/B contract, adversarial pass, AND Haiku secondary in parallel (paranoid mode on post-fix).
+7. Any new findings become same-loop fix-targets. Internal iteration count increments by one.
+8. After 3 internal iterations with fresh findings each time, exit `stuck: post-fix audit not converging`.
+9. Only when `gate_findings` empty AND `post_fix_findings` empty: `git add`, commit, push.
+
+`converged` exit condition: `primary_audit_clean AND post_fix_audit_clean` for the committing loop.
+
+## Persistence
+
+Every audit loop writes two JSON files under the skill's scoped temp directory (resolved via `tempfile.gettempdir()`):
+
+### `loop-<N>-audit.json`
+
+```json
+{
+  "findings": [],
+  "proof_of_absence": [],
+  "source": "primary | haiku | adversarial | merged"
+}
+```
+
+### `loop-<N>-diagnostics.json`
+
+```json
+{
+  "loop": 1,
+  "gate_findings": [],
+  "primary_findings": [],
+  "adversarial_findings": [],
+  "haiku_findings": [],
+  "post_fix_findings": [],
+  "merged": [],
+  "deduped": []
+}
+```
+
+All eight keys MUST be present. Missing keys break convergence debugging.

package/skills/bugteam/reference/team-setup.md

@@ -35,8 +35,8 @@ This session is the **team lead**. Create the team with `TeamCreate` using the e
 - **Per-team temp directory (resolved once, reused everywhere):** After `team_name` is captured, resolve a portable absolute path with a Claude-side lookup using Python’s `tempfile.gettempdir()`, which honors `TMPDIR`, `TEMP`, and `TMP` in the platform-correct order and falls back to `C:\Users\<user>\AppData\Local\Temp` on Windows or `/tmp` on Unix: `Path(tempfile.gettempdir()) / team_name` (requires `import tempfile`). The `team_name` value already carries the `bugteam-` prefix; keep it as-is here. Let `tempfile.gettempdir()` perform the lookup; use its result directly. Capture the resolved absolute path as `<team_temp_dir>` and pass that literal path to every shell command that follows. Claude performs all temp-root resolution so every shell (bash, cmd.exe, PowerShell) receives the same literal absolute value.
 
 - **Roles defined up front (spawned per loop, not at team creation):**
-  - `bugfind` — teammate role `code-quality-agent`, model sonnet
-  - `bugfix` — teammate role `clean-coder`, model sonnet
+  - `bugfind` — teammate role `code-quality-agent`, model opus (Opus 4.7 at default xhigh effort)
+  - `bugfix` — teammate role `clean-coder`, model opus (Opus 4.7 at default xhigh effort)
 
 - **Display mode:** inherit the user’s default (`teammateMode` in `~/.claude.json`); do not override.
 

package/skills/bugteam/scripts/bugteam_preflight.py

@@ -7,6 +7,69 @@ import sys
 from pathlib import Path
 
 
+def verify_git_hooks_path(repository_root: Path | None = None) -> int:
+    """Check that core.hooksPath resolves to the claude-dev-env git-hooks directory.
+
+    When *repository_root* is provided, queries the effective config for that
+    repository (``git -C <root> config --get``), which detects repo-level
+    overrides such as Husky or lefthook. Falls back to the current working
+    directory's effective config when *repository_root* is None.
+
+    Returns zero when the configured path ends with the expected hooks suffix.
+    Returns non-zero and prints a correction message when unset or pointing elsewhere.
+    """
+    expected_hooks_path_suffix = "hooks/git-hooks"
+    enforcement_absent_message = (
+        "Git-side CODE_RULES enforcement is not active on this host.\n"
+        "Run: npx claude-dev-env .\n"
+        "Or set core.hooksPath at any scope, e.g.:\n"
+        "  git config --global core.hooksPath ~/.claude/hooks/git-hooks"
+    )
+    git_command: list[str] = ["git"]
+    if repository_root is not None:
+        git_command.extend(["-C", str(repository_root)])
+    git_command.extend(["config", "--get", "core.hooksPath"])
+    try:
+        query_result = subprocess.run(
+            git_command,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+    except FileNotFoundError:
+        print(
+            "bugteam_preflight: git is not installed or not available on PATH.\n"
+            f"{enforcement_absent_message}",
+            file=sys.stderr,
+        )
+        return 1
+    except OSError as os_error:
+        print(
+            f"bugteam_preflight: failed to run git: {os_error}\n"
+            f"{enforcement_absent_message}",
+            file=sys.stderr,
+        )
+        return 1
+    if query_result.returncode != 0:
+        print(
+            f"bugteam_preflight: {enforcement_absent_message}",
+            file=sys.stderr,
+        )
+        return 1
+    configured_path = query_result.stdout.strip().replace("\\", "/").rstrip("/")
+    if not configured_path.endswith(expected_hooks_path_suffix):
+        print(
+            f"bugteam_preflight: core.hooksPath is '{configured_path}' — "
+            f"expected path ending in '{expected_hooks_path_suffix}'.\n"
+            f"{enforcement_absent_message}",
+            file=sys.stderr,
+        )
+        return 1
+    return 0
+
+
 def find_repository_root(start: Path) -> Path:
     resolved = start.resolve()
     candidates = [resolved, *resolved.parents]
@@ -109,6 +172,9 @@ def main(argv: list[str] | None = None) -> int:
         if arguments.repo_root is not None
         else find_repository_root(start)
     )
+    hooks_path_exit_code = verify_git_hooks_path(repository_root)
+    if hooks_path_exit_code != 0:
+        return hooks_path_exit_code
     if not arguments.no_pytest and has_pytest_configuration(repository_root):
         if not has_discoverable_tests(repository_root):
             print(

package/skills/bugteam/scripts/test_bugteam_preflight.py

@@ -0,0 +1,189 @@
+"""Tests for bugteam_preflight git hooks path verification.
+
+Covers:
+- core.hooksPath unset: exits non-zero with correction message
+- core.hooksPath pointing to the correct claude hooks dir: exits zero
+- core.hooksPath pointing elsewhere (husky override): exits non-zero
+- core.hooksPath with trailing slash: must still pass after normalization
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import subprocess
+from pathlib import Path
+from types import ModuleType
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+def _load_preflight_module() -> ModuleType:
+    module_path = Path(__file__).parent / "bugteam_preflight.py"
+    spec = importlib.util.spec_from_file_location("bugteam_preflight", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+bugteam_preflight = _load_preflight_module()
+
+
+def _make_completed_process(
+    stdout: str, returncode: int
+) -> subprocess.CompletedProcess:
+    process = MagicMock(spec=subprocess.CompletedProcess)
+    process.stdout = stdout
+    process.returncode = returncode
+    return process
+
+
+def test_should_exit_nonzero_when_core_hooks_path_unset(capsys: pytest.CaptureFixture[str]) -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process("", returncode=1)
+        exit_code = bugteam_preflight.verify_git_hooks_path()
+    assert exit_code != 0
+    captured = capsys.readouterr()
+    assert "core.hooksPath" in captured.err
+    assert "npx claude-dev-env" in captured.err or "git config" in captured.err
+
+
+def test_should_exit_zero_when_core_hooks_path_points_to_claude_hooks(tmp_path: Path) -> None:
+    claude_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
+    claude_hooks_path.mkdir(parents=True)
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            str(claude_hooks_path) + "\n", returncode=0
+        )
+        exit_code = bugteam_preflight.verify_git_hooks_path()
+    assert exit_code == 0
+
+
+def test_should_exit_nonzero_when_core_hooks_path_points_elsewhere(capsys: pytest.CaptureFixture[str]) -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            "/some/other/path/.husky\n", returncode=0
+        )
+        exit_code = bugteam_preflight.verify_git_hooks_path()
+    assert exit_code != 0
+    captured = capsys.readouterr()
+    assert "core.hooksPath" in captured.err
+
+
+def test_should_include_correction_commands_in_error_message(capsys: pytest.CaptureFixture[str]) -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process("", returncode=1)
+        bugteam_preflight.verify_git_hooks_path()
+    captured = capsys.readouterr()
+    assert (
+        "npx claude-dev-env" in captured.err
+        or "git config --global core.hooksPath" in captured.err
+    )
+
+
+def test_main_should_exit_nonzero_when_hooks_path_unset() -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process("", returncode=1)
+        exit_code = bugteam_preflight.main(["--no-pytest"])
+    assert exit_code != 0
+
+
+def test_main_should_continue_when_hooks_path_valid(tmp_path: Path) -> None:
+    claude_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
+    claude_hooks_path.mkdir(parents=True)
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            str(claude_hooks_path) + "\n", returncode=0
+        )
+        exit_code = bugteam_preflight.main(["--no-pytest"])
+    assert exit_code == 0
+
+
+def test_should_accept_hooks_path_with_trailing_slash() -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            "/home/user/.claude/hooks/git-hooks/\n", returncode=0
+        )
+        exit_code = bugteam_preflight.verify_git_hooks_path()
+    assert exit_code == 0, (
+        "hooksPath with trailing slash must pass verification after normalization"
+    )
+
+
+def test_should_exit_zero_when_hooks_path_set_at_repo_scope(tmp_path: Path) -> None:
+    claude_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
+    claude_hooks_path.mkdir(parents=True)
+    repo_root = tmp_path / "my-repo"
+    repo_root.mkdir()
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            str(claude_hooks_path) + "\n", returncode=0
+        )
+        exit_code = bugteam_preflight.verify_git_hooks_path(repo_root)
+    assert exit_code == 0, (
+        "verify_git_hooks_path must accept a valid path returned by effective "
+        "config query (not restricted to --global scope)"
+    )
+    called_command = mock_run.call_args[0][0]
+    assert "--global" not in called_command, (
+        "verify_git_hooks_path must query effective config, not --global only"
+    )
+    assert "-C" in called_command, (
+        "verify_git_hooks_path must use git -C <repo_root> for repo-effective config"
+    )
+    dash_c_index = called_command.index("-C")
+    assert called_command[dash_c_index + 1] == str(repo_root), (
+        "git -C must receive the resolved repository root path"
+    )
+
+
+def test_should_accept_hooks_path_with_backslash_and_trailing_slash() -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            "C:\\Users\\user\\.claude\\hooks\\git-hooks\\\n", returncode=0
+        )
+        exit_code = bugteam_preflight.verify_git_hooks_path()
+    assert exit_code == 0, (
+        "Windows hooksPath with trailing backslash must pass after normalization"
+    )
+
+
+def test_should_exit_nonzero_when_git_executable_not_found(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Preflight must not crash with a traceback when git is missing from PATH."""
+    with patch("subprocess.run", side_effect=FileNotFoundError()):
+        exit_code = bugteam_preflight.verify_git_hooks_path()
+    assert exit_code != 0, (
+        "FileNotFoundError from subprocess.run must produce a non-zero exit, "
+        "not a propagated traceback"
+    )
+    captured = capsys.readouterr()
+    assert "git" in captured.err.lower(), (
+        "Error message must mention git so the user knows what is missing"
+    )
+    assert (
+        "npx claude-dev-env" in captured.err
+        or "git config --global core.hooksPath" in captured.err
+    ), "Error message must include the enforcement-absent remediation hints"
+
+
+def test_should_exit_nonzero_when_subprocess_run_raises_os_error(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Preflight must surface a clean error for other OS-level git launch failures."""
+    with patch("subprocess.run", side_effect=OSError("permission denied")):
+        exit_code = bugteam_preflight.verify_git_hooks_path()
+    assert exit_code != 0, (
+        "OSError from subprocess.run must produce a non-zero exit, "
+        "not a propagated traceback"
+    )
+    captured = capsys.readouterr()
+    assert "bugteam_preflight" in captured.err, (
+        "Error message must be prefixed with the preflight tool name for context"
+    )
+    assert "permission denied" in captured.err, (
+        "Error message must include the underlying OSError detail for diagnosis"
+    )

package/skills/copilot-review/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: copilot-review
+description: >-
+  Spawns a background subagent that babysits the GitHub Copilot reviewer on the
+  current PR. The subagent self-paces at ~5 minutes per tick, fetches the
+  latest copilot-pull-request-reviewer[bot] review, fixes unaddressed inline
+  findings against current HEAD (new commit, push, inline replies), and
+  re-requests review via the documented requested_reviewers API. The subagent
+  terminates on convergence (clean review against HEAD) and reports back.
+  Triggers: '/copilot-review', 'watch copilot', 'babysit copilot review',
+  'loop copilot reviews', 're-request copilot', 'keep re-requesting copilot'.
+---
+
+# Copilot Review
+
+Delegates Copilot babysitting to a background subagent so the main session stays free. The subagent loops internally and closes itself on convergence.
+
+## When this skill applies
+
+The user is on a PR branch, wants Copilot (the GitHub Copilot reviewer bot) to keep re-reviewing after each push, and wants findings auto-addressed between ticks — but does not want the main conversation consumed by polling.
+
+## The Process
+
+### Step 1: Gather PR context
+
+From the current repo:
+
+```bash
+gh pr view --json number,url,headRefOid,baseRefName,headRefName,isDraft
+```
+
+Capture `number`, `headRefOid`, owner/repo (from `url`), and branch name. Pass these to the subagent so it does not rediscover them.
+
+### Step 2: Spawn the background subagent
+
+Invoke the `Agent` tool with:
+
+- `subagent_type: "general-purpose"`
+- `run_in_background: true`
+- `description: "Copilot review loop for PR #<N>"`
+- `prompt`: the full instructions in **Step 3 (Subagent prompt template)**, with placeholders filled in from Step 1.
+
+Record the returned agent ID. Report to the user in one or two lines:
+
+- The subagent is running in the background.
+- It self-terminates on convergence.
+- To stop it early, the user says "stop the copilot loop" and you call `TaskStop <agent_id>`.
+- The main session stays free; completion arrives as a notification.
+
+Let the subagent own the cadence. The skill's job in the main session ends once the subagent is spawned and reported.
+
+### Step 3: Subagent prompt template
+
+Pass this verbatim to the subagent (substituting the bracketed values):
+
+> You are babysitting the GitHub Copilot reviewer on PR **#[NUMBER]** at **[OWNER]/[REPO]** (branch `[BRANCH]`, current HEAD `[HEAD_SHA]`). Your job: keep the loop running until Copilot returns a clean review against the current HEAD, then stop.
+>
+> **Per-tick work** (do this now, then on each wakeup):
+>
+> 1. Resolve current HEAD: `gh api repos/[OWNER]/[REPO]/pulls/[NUMBER] --jq '.head.sha'`.
+> 2. Fetch latest Copilot review:
+>    ```bash
+>    gh api repos/[OWNER]/[REPO]/pulls/[NUMBER]/reviews \
+>      --jq '[.[] | select(.user.login=="copilot-pull-request-reviewer[bot]")] | sort_by(.submitted_at) | last'
+>    ```
+>    Capture `commit_id`, `state`, `submitted_at`, `id`.
+> 3. Decide the branch:
+>    - **No review exists:** re-request (step 4), schedule next wakeup, return.
+>    - **Latest review's `commit_id` != current HEAD:** re-request (step 4), schedule next wakeup, return.
+>    - **Latest review's `commit_id` == current HEAD with unresolved inline findings:** TDD-fix them, push, reply inline on each thread, re-request (step 4), schedule next wakeup, return.
+>    - **Latest review's `commit_id` == current HEAD and clean:** report convergence to the parent with a one-sentence summary and terminate. The loop is done; skip the ScheduleWakeup call.
+> 4. Re-request Copilot. The reviewer ID **must** be `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix — empirically verified: `Copilot`, `copilot`, and `github-copilot` all return `requested_reviewers: []` with no error, silently no-op.
+>    ```bash
+>    gh api -X POST repos/[OWNER]/[REPO]/pulls/[NUMBER]/requested_reviewers \
+>      -f 'reviewers[]=copilot-pull-request-reviewer[bot]'
+>    ```
+> 5. Schedule the next wakeup with `ScheduleWakeup`:
+>    - `delaySeconds: 300`
+>    - `reason`: one short sentence on what you are waiting for.
+>    - `prompt`: the literal sentinel `<<autonomous-loop-dynamic>>` so the next firing re-enters these instructions.
+>
+> **Fix protocol** (step 3, third branch):
+>
+> - Read each referenced file:line.
+> - Write a failing test first when the finding has behavior to test. For pure doc or comment nits that have no behavior, go straight to the fix.
+> - Implement the fix.
+> - Stage the fix and create one new commit on the existing branch: `git add <files> && git commit -m "fix(review): ..."`.
+> - Push the new commit: `git push origin [BRANCH]`.
+> - Reply inline on each comment thread with `gh api -X POST repos/[OWNER]/[REPO]/pulls/[NUMBER]/comments` using `in_reply_to` set to the comment id, referencing the new commit SHA.
+>
+> When a pre-push, pre-commit, or other hook rejects the change, solve it. Read the hook's error message, diagnose the root cause in the code or test, and fix that. Then rerun the commit or push. Hooks exist to catch real problems; treat each rejection as new evidence to act on.
+>
+> **Stop conditions:**
+>
+> - Convergence (clean review against HEAD): report one-sentence summary to parent and terminate.
+> - Blocker you have exhausted fix attempts on (API auth failure persists, CI regression whose root cause falls outside this PR, a hook you have investigated and cannot resolve in one commit): report the specific blocker and its diagnosis to the parent, then terminate without scheduling another wakeup.
+> - Parent sends `TaskStop`: terminate immediately.
+>
+> **Safety cap:** after 20 ticks without convergence, stop and report. That many rounds means something structural is wrong with the loop.
+
+### Step 4: Report back to the user
+
+After spawning, tell the user in one or two lines: subagent ID, PR URL, that it will notify on convergence or blocker. Nothing else.
+
+## Stopping the subagent
+
+- Convergence → subagent stops itself.
+- Blocker → subagent reports and stops.
+- User says stop → `TaskStop <agent_id>`.
+- User asks what loops are running → `TaskList`.
+
+## Ground rules (for the subagent)
+
+- **Append commits.** Each tick adds one new commit on the existing branch with `git commit` and `git push origin [BRANCH]`.
+- **Honor pre-push and pre-commit hooks.** When a hook rejects the change, read its output, fix the underlying issue (the failing test, the missing constant, the broken import), and retry. Solve, do not punt.
+- **Respect the PR's current state.** Whatever draft-vs-ready state the PR has when the loop starts is the state the subagent preserves. The user decides when to flip it.
+- **One fix commit per tick.** Batch all of the current tick's findings into a single commit; the next tick handles the next review round.
+- **Use `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix for the reviewer ID.** That exact spelling is load-bearing — it is the only form the API accepts.
+
+## Examples
+
+<example>
+User: `/copilot-review`
+Claude: [reads PR context, spawns background subagent with the Step 3 template, reports "subagent X watching PR #123; will notify on convergence"]
+</example>
+
+<example>
+User: "babysit copilot on this PR until it's clean"
+Claude: [same as above]
+</example>
+
+<example>
+Subagent tick fires, latest Copilot review is against an older commit.
+Subagent: [re-requests review, schedules next wakeup, returns]
+</example>
+
+<example>
+Subagent tick fires, Copilot has 2 unaddressed inline findings on HEAD.
+Subagent: [TDD-fixes both, one commit, pushes, replies inline on both threads, re-requests review, schedules next wakeup]
+</example>
+
+<example>
+Subagent tick fires, latest review is clean against HEAD.
+Subagent: [reports convergence to parent, terminates — no further wakeups]
+</example>

package/skills/findbugs/SKILL.md

@@ -47,12 +47,12 @@ The audit's authoritative scope is this single diff file. Do not inject extra fi
 
 ### Step 3: Spawn the code-quality-agent — clean room
 
-Call the Agent tool with:
+Call the Agent tool twice in a single message (primary + Haiku secondary per the audit contract's Haiku secondary section):
 
-- `subagent_type: code-quality-agent`
-- `model: sonnet`
-- `description: "PR bug audit"`
-- `run_in_background: false` — the user invoked `/findbugs` to get a result on this turn
+- Primary: `subagent_type: code-quality-agent`, `model: sonnet`, `description: "PR bug audit"`, `run_in_background: false`
+- Secondary: `subagent_type: code-quality-agent`, `model: haiku`, `description: "PR bug audit (secondary)"`, `run_in_background: false`
+
+After both return, merge per the contract's Haiku secondary section (de-dup key, max-wins severity, malformed-output fallback) before reporting to the user.
 
 **The agent prompt must be self-contained and context-free.** Specifically:
 
@@ -98,25 +98,17 @@ The XML prompt skeleton:
 </constraints>
 
 <output_format>
-  P0 = will not run / data corruption
-  P1 = regression or silent failure
-  P2 = dead code, minor smell
-
-  ## Summary
-  Total: N (P0=N, P1=N, P2=N)
-
-  ## Findings
-  ### [P_] short title
-  File: file/path:line
-  Category: A-J
-  Issue: 2-3 sentence description with concrete trace
-  Evidence: code excerpt or grep result
+  Follow the shared audit contract at ../bugteam/reference/audit-contract.md:
 
-  ## Verified clean
-  Per category investigated, name the evidence and the conclusion.
+  - Severity: P0 = will not run / data corruption; P1 = regression or silent
+    failure; P2 = dead code, minor smell.
+  - Per category, produce either Shape A (structured finding) or Shape B
+    (proof-of-absence). Bare "verified clean" labels are REJECTED.
+  - Run the contract's adversarial second pass after the primary list.
 
-  ## Open questions
-  Anything ambiguous from the diff alone.
+  Preamble: `Total: N (P0=N, P1=N, P2=N)`. Emit findings and proof-of-absence
+  entries in the JSON shapes defined by the contract. Include an "Open
+  questions" section for items the diff alone cannot resolve.
 </output_format>
 ```