claude-dev-env 2.0.2 → 2.2.0

package/skills/autoconverge/reference/CLAUDE.md

@@ -7,6 +7,7 @@ Reference documentation for the `autoconverge` skill. The `converge.mjs` workflo
 | File | Role |
 |---|---|
 | `convergence.md` | Round shape: the static sweep, the three parallel internal lenses (code-review, bug-audit, self-review), deduplication, the fix commit step, the terminal Bugbot, Copilot, and Codex gates, and the definition of a clean convergence. |
+| `copilot-findings.md` | The Copilot gate tiering, per-finding verification, and the `userReview` return contract. |
 | `stop-conditions.md` | Every condition that ends the run short of ready: budget cap, iteration cap, blocker exit, static-sweep stall, Bugbot, Copilot, and Codex bypass. |
 | `gotchas.md` | Hard-won lessons from failed runs: PR title validation, conflicting PRs, worktree branch lock, resumed sessions rerooting, and minter issues. |
 | `closing-report.md` | The closing HTML convergence report the teardown step builds and publishes: data source, build steps, publishing. |

package/skills/autoconverge/reference/convergence.md

@@ -66,11 +66,11 @@ confirmation gates that are expected to return zero.
    - **Code-review lens** — a correctness-focused review pass (`code-quality-agent`),
      report-only workflow agent — see runCodeReviewLens in workflow/converge.mjs for its configuration.
      The built-in `/code-review` command is a separate surface outside this
-     workflow path. Autoconverge runs only where the Workflow tool exists (the
-     skill hub Requirements sentence `autoconverge requires the Workflow tool`).
-     Harness portability of that command is a pr-converge concern: pr-converge's
-     CODE_REVIEW phase runs Claude Code's built-in `/code-review high --fix`
-     ([`../../pr-converge/reference/per-tick.md`](../../pr-converge/reference/per-tick.md)).
+     workflow path. On `pacer=workflow`, this lens runs inside `converge.mjs`.
+     On `pacer=portable`, the continuous driver uses the pr-converge CODE_REVIEW
+     phase through `invoke_code_review.py` instead of `runCodeReviewLens`
+     ([`../../_shared/pr-loop/portable-driver.md`](../../_shared/pr-loop/portable-driver.md);
+     [`../../pr-converge/reference/per-tick.md`](../../pr-converge/reference/per-tick.md)).
    - **Bug-audit lens** — the bug-audit (`code-quality-agent`) applying the
      shared A–P rubric from `_shared/pr-loop/audit-contract.md`, then its
      adversarial second pass, and the doc-parity, test-assertion, and

package/skills/autoconverge/reference/copilot-findings.md

@@ -0,0 +1,51 @@
+# Copilot findings — tier, verify, then route
+
+How the autoconverge Copilot gate handles each finding. The hub
+([`../SKILL.md`](../SKILL.md)) points here; the orchestrating session's
+user-review hold runs the [`copilot-finding-triage`](../../copilot-finding-triage/SKILL.md)
+skill.
+
+The Copilot gate tiers each finding: a **self-healing** finding (style, type
+hints, imports, formatting, magic-value extraction, test-only or doc-vs-code
+fixes — nothing that changes observable runtime behavior) flows into the fix
+round with no user notification. A **code-concern** finding (logic, security,
+data handling, error-handling semantics, concurrency — the tier whenever in
+doubt) goes to a verification stage before any routing.
+
+Each code-concern finding gets its own verifier agent, all in parallel, inside
+the workflow. A verdict is conclusive only when an actual check ran: the verifier
+executes a command against the flagged HEAD — running the code path with crafted
+inputs, forcing the claimed error condition, or running a purpose-built test —
+and captures its output. The verdict carries
+`{ verdict, checkCommand, checkOutput, evidence }`; a conclusive verdict with an
+empty `checkCommand` or `checkOutput` downgrades to inconclusive.
+
+- **confirmed** — the check reproduces the defect. The finding becomes
+  self-healing: it joins the fix round carrying its repro, and the fix re-runs
+  that same check, adds a regression test where the suite covers the surface,
+  lands in one commit, pushes, and replies on the thread with the fix SHA and the
+  before/after output. No page.
+- **refuted** — the check shows the code already behaves correctly in the exact
+  scenario the finding claims is broken. The workflow replies on the thread with
+  the command and output, resolves it, and counts it clean. No page.
+- **inconclusive** — everything else, and the verifier's default: no runnable
+  check exists, the check is infeasible here, the results are ambiguous, or the
+  fix needs a product decision. Any doubt sorts here. Only inconclusive findings
+  page the user.
+
+A round whose code concerns all confirm or refute never returns
+`blocker: "user-review"`. On one or more inconclusive findings, the workflow
+stops with `converged: false`, `blocker: "user-review"`, and a `userReview`
+field carrying
+`{ reviewUrl, findings: [{ file, line, severity, tier, title, evidence }] }` —
+`evidence` is the verifier's one-line note stating what check was attempted and
+why it was not decisive.
+
+A background workflow cannot hold for a human, so the wait belongs to the
+orchestrating session. On a `blocker: "user-review"` return, run the
+[`copilot-finding-triage`](../../copilot-finding-triage/SKILL.md) skill: send the
+ntfy notification (the per-finding summary and evidence note plus the `reviewUrl`
+Copilot review link), then hold with a 45-minute `ScheduleWakeup` for the user's
+response. When the user answers within the window, follow their direction. When
+the window closes with no response, run normal teardown and report the
+inconclusive findings un-reviewed.

package/skills/autoconverge/reference/multi-pr.md

@@ -42,7 +42,27 @@ each PR its own checkout with `git worktree add`. For each PR the user named:
    non-zero exit sets `copilotDisabled: true` on every entry, so each child skips
    the Copilot gate with no agent spawned.
 
-## Launch the multi-PR workflow
+## Launch
+
+Select the pacer once for the multi-PR run (same helper as single-PR):
+
+```
+python "$HOME/.claude/skills/_shared/pr-loop/scripts/select_converge_pacer.py" \
+  --skill autoconverge \
+  --has-workflow <0|1> \
+  --has-schedule-wakeup <0|1>
+```
+
+### `pacer=portable`
+
+Do **not** call `Workflow`. For each PR worktree from pre-flight, run the
+continuous portable driver in
+[`../../_shared/pr-loop/portable-driver.md`](../../_shared/pr-loop/portable-driver.md)
+(serial, or host fan-out when the host can isolate workers). One teardown per
+PR after that PR reaches ready or a named blocker. Shared Copilot quota and
+permission grants from multi-PR pre-flight still apply once.
+
+### `pacer=workflow`
 
 Call the `Workflow` tool against the fan-out script, passing the absolute path of
 `converge.mjs` and one entry per PR:
@@ -74,7 +94,18 @@ Each record's `deferredPrs` is that PR's own list of draft hardening PRs, and
 `allDeferredPrs` is every record's `deferredPrs` flattened into one list. The
 top-level `converged` is true only when every PR converged.
 
-## Multi-PR teardown (on workflow completion)
+## Multi-PR teardown
+
+### `pacer=portable`
+
+For each PR worktree, run the single-PR **Teardown → pacer=portable** path in
+[`SKILL.md`](../SKILL.md) (`pr-loop-lifecycle` Close, no Workflow journal
+report). Write one durable handoff per PR with that PR's `--pr-number` and
+resume command `/autoconverge <PR URL>`. Revoke project permissions once per
+repository after every PR's close. Print one summary line per PR as
+`#<prNumber>: <converged | blocked> — rounds <N>, final <finalSha>[, blocker <blocker>]`.
+
+### `pacer=workflow` (on workflow completion)
 
 Run the single-PR Teardown in [`SKILL.md`](../SKILL.md) once per entry in
 `results`, using that PR's `owner`, `repo`, `prNumber`, and `finalSha`, and its

package/skills/autoconverge/reference/stop-conditions.md

@@ -6,14 +6,17 @@ skill still runs teardown (revoke permissions, final report).
 
 ## Blockers (end the run short of ready)
 
-- **Budget stop** — the workflow's `budget` API is the pacing signal: when a
-  usage target is set, `converge.mjs` checks `budget.remaining()` before each
-  round and stops at the round boundary when one full round (three parallel
-  lenses + one fix commit + re-verify) does not fit. The run returns
-  `blocker: "budget"` with the run id; resume with
+- **Budget stop** — on `pacer=workflow`, the workflow's `budget` API is the
+  pacing signal: when a usage target is set, `converge.mjs` checks
+  `budget.remaining()` before each round and stops at the round boundary when
+  one full round (three parallel lenses + one fix commit + re-verify) does not
+  fit. The run returns `blocker: "budget"` with the run id; resume with
   `Workflow({scriptPath, resumeFromRunId})` — completed rounds replay from the
   journal. The workflow never starts a round the budget cannot finish: a
-  half-run round records nothing resumable and replays dirty.
+  half-run round records nothing resumable and replays dirty. On
+  `pacer=portable`, stop at a tick boundary when the session cannot cover a
+  full clean tick; write handoff and resume with `/autoconverge <PR URL>`
+  ([`../../_shared/pr-loop/portable-driver.md`](../../_shared/pr-loop/portable-driver.md)).
 - **Iteration cap** — 20 loop iterations pass without a full convergence-check
   pass. The iteration counter increments on every pass through any phase, so a
   convergence-check gate that no round can clear (for example a `mergeable_state`

package/skills/autoconverge/test_portable_pacer_gate.py

@@ -0,0 +1,54 @@
+"""Contract checks: autoconverge selects a portable pacer when Workflow is absent."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parent
+SKILL_MARKDOWN_PATH = SKILL_ROOT / "SKILL.md"
+MULTI_PR_MARKDOWN_PATH = SKILL_ROOT / "reference" / "multi-pr.md"
+PORTABLE_DRIVER_PATH = (
+    SKILL_ROOT.parent / "_shared" / "pr-loop" / "portable-driver.md"
+)
+
+SELECT_CONVERGE_PACER_SCRIPT = "select_converge_pacer.py"
+PACER_PORTABLE_TOKEN = "pacer=portable"
+PACER_WORKFLOW_TOKEN = "pacer=workflow"
+ABORT_ONLY_PHRASE = "autoconverge requires the Workflow tool"
+PORTABLE_DRIVER_DOC = "portable-driver.md"
+PORTABLE_DRIVER_LINK_PATTERN = re.compile(
+    r"\((?P<relative>(?:\.\./)+_shared/pr-loop/portable-driver\.md)\)"
+)
+
+
+def test_skill_selects_pacer_and_forbids_abort_only_workflow() -> None:
+    skill_text = SKILL_MARKDOWN_PATH.read_text(encoding="utf-8")
+    assert SELECT_CONVERGE_PACER_SCRIPT in skill_text
+    assert PACER_PORTABLE_TOKEN in skill_text
+    assert PACER_WORKFLOW_TOKEN in skill_text
+    assert PORTABLE_DRIVER_DOC in skill_text
+    assert ABORT_ONLY_PHRASE not in skill_text
+
+
+def test_skill_portable_driver_links_resolve_on_disk() -> None:
+    skill_text = SKILL_MARKDOWN_PATH.read_text(encoding="utf-8")
+    all_relative_links = PORTABLE_DRIVER_LINK_PATTERN.findall(skill_text)
+    assert all_relative_links, "SKILL.md must link portable-driver.md"
+    for each_relative_link in all_relative_links:
+        resolved_path = (SKILL_MARKDOWN_PATH.parent / each_relative_link).resolve()
+        assert resolved_path.is_file(), (
+            f"portable-driver link must resolve on disk: "
+            f"{each_relative_link} -> {resolved_path}"
+        )
+        assert resolved_path == PORTABLE_DRIVER_PATH.resolve()
+
+
+def test_multi_pr_documents_portable_launch_and_teardown() -> None:
+    multi_pr_text = MULTI_PR_MARKDOWN_PATH.read_text(encoding="utf-8")
+    assert PACER_PORTABLE_TOKEN in multi_pr_text
+    assert "Do **not** call `Workflow`" in multi_pr_text or (
+        "Do not call `Workflow`" in multi_pr_text
+    )
+    assert "pacer=portable" in multi_pr_text
+    assert PORTABLE_DRIVER_DOC in multi_pr_text

package/skills/closeout/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: closeout
 description: >-
-  Harvests session obstacles into GitHub issues backed by quoted evidence at
-  session end, validates each draft with the user, dedupes against open and
-  closed issues, routes each to its repo, files children then a parent
-  checklist, and prints a computed cloud handoff prompt. Triggers: /closeout,
-  close out this session, close out the session, file the session obstacles,
-  session closeout, harvest session obstacles, end-of-session issue filing.
-  Near-miss: not session-log, which journals the session to the vault; closeout
-  files GitHub issues and prints a handoff prompt, and writes no session
-  journal.
+  Harvests session obstacles into GitHub issues backed by quoted evidence:
+  validates each draft with the user, dedupes against open and closed issues,
+  files children under a parent checklist, and prints a cloud handoff prompt.
+  Triggers: /closeout, close out this session, close out the session, file the
+  session obstacles, session closeout, harvest session obstacles, end-of-session
+  issue filing. Not session-log (vault journal) — closeout files issues and
+  writes no journal.
 ---
 
 # Closeout

package/skills/copilot-finding-triage/SKILL.md

@@ -1,13 +1,11 @@
 ---
 name: copilot-finding-triage
 description: >-
-  Sorts each Copilot gate finding from a converge run into one of two tiers, then
-  verifies each code concern with an executed check before routing it: a
-  self-healing finding is auto-fixed, pushed, and counted toward convergence with
-  no user page; a confirmed or refuted code concern is handled by the run with its
-  check evidence; only a code concern the check leaves inconclusive pages the user
-  over ntfy and holds the run behind a 45-minute gate. Triggers: 'copilot finding
-  triage', 'user review gate', 'tier copilot findings', 'triage the copilot gate'.
+  Tiers each Copilot gate finding from a converge run, verifies each code concern
+  with an executed check, then routes it — auto-fix a self-healing finding,
+  resolve a refuted one, page the user only for an inconclusive one. Triggers:
+  'copilot finding triage', 'user review gate', 'tier copilot findings', 'triage
+  the copilot gate'.
 ---
 
 # Copilot Finding Triage
@@ -117,9 +115,21 @@ counts as approval.
 
 ### Step 2 — Hold and wait
 
-Arm `ScheduleWakeup` for a 45-minute deadline. Where `ScheduleWakeup` is absent,
-use `send_later`. The clock starts when the page reaches the user, which is the
-moment the script exits zero.
+Branch the hold on the caller's pacer (or on whether a durable wake surface is
+present when the caller has not selected a pacer):
+
+- **Native pacer** (`pacer=schedule_wakeup`, `pacer=workflow`, or
+  `ScheduleWakeup` present): arm `ScheduleWakeup` for a 45-minute deadline.
+  Where `ScheduleWakeup` is absent on that native path, use `send_later`.
+- **Portable pacer** (`pacer=portable`, or no durable wake): do not call
+  `ScheduleWakeup` or `send_later`. Hold with an in-session deadline poll, or
+  write handoff and stop, per
+  [`../_shared/pr-loop/portable-driver.md`](../_shared/pr-loop/portable-driver.md).
+  Callers may override this step after the ntfy page and apply their own
+  portable hold.
+
+The clock starts when the page reaches the user, which is the moment the script
+exits zero.
 
 - If the user answers, follow their direction.
 - If the deadline passes with no answer, run the caller's normal teardown and
@@ -143,7 +153,7 @@ its fix re-runs that same check and posts the before/after output on the thread.
       evidence note.
 - [ ] The page carries the PR name, the per-finding summary, and the review URL.
 - [ ] `scripts/notify_ntfy.py` exited zero before the 45-minute clock started.
-- [ ] The wakeup is armed for 45 minutes from a delivered page.
+- [ ] The hold is armed from a delivered page (45-minute `ScheduleWakeup` / `send_later` on native pacer; portable in-session poll or handoff on `pacer=portable`).
 - [ ] A failed page kept the gate open rather than approving the round.
 
 ## Files

package/skills/copilot-review/CLAUDE.md

@@ -6,11 +6,12 @@ Spawns a background subagent that polls the GitHub Copilot reviewer on the curre
 
 The main session gathers PR context (number, HEAD SHA, owner/repo, branch), spawns a self-terminating background subagent with a fully filled-in prompt, and returns control at once. The subagent loops on a 6-minute `ScheduleWakeup` cadence: fetch Copilot's latest review, TDD-fix any inline findings, push a commit, reply inline, resolve each addressed thread, re-request review. It stops on convergence, a persistent blocker, `TaskStop`, three consecutive ticks with no Copilot review at the current HEAD, or after 20 ticks.
 
-## Key file
+## Key files
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Four-step orchestration (opt-out check, gather PR context, spawn subagent, report to user), the verbatim subagent prompt template with all placeholders, fix protocol, stop conditions, and ground rules (one commit per tick, honor hooks, preserve draft state, use `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix). |
+| `SKILL.md` | Four-step orchestration (opt-out check, gather PR context, spawn subagent, report to user), fix protocol, stop conditions, and ground rules (one commit per tick, honor hooks, preserve draft state, use `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix). |
+| `templates/subagent-prompt.md` | The background watcher prompt Step 3 passes to the subagent word for word, with placeholders for PR number, owner, repo, branch, and HEAD SHA. |
 
 ## Environment opt-out
 

package/skills/copilot-review/SKILL.md

@@ -1,155 +1,119 @@
----
-name: copilot-review
-description: >-
-  Spawns a background subagent that babysits the GitHub Copilot reviewer on the
-  current PR: each tick it fixes unaddressed findings against HEAD, re-requests
-  review, and exits on convergence. Triggers: '/copilot-review', 'watch
-  copilot', 'babysit copilot review', '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.
-
-## Transport check (before any GitHub step)
-
-Run `command -v gh`; when it succeeds, run `gh auth status`; once the PR scope is resolved, run `gh api repos/<owner>/<repo> --jq .permissions.push` and take `true` as the pass. When any check fails, run the `pr-loop-cloud-transport` skill first, route every `gh` operation in this skill through its substitution matrix, and carry the same routing into the subagent prompt so the spawned watcher inherits it.
-
-## 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 0: Opt-out check
-
-Before any other work, run:
-
-```bash
-python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer copilot
-```
-
-Exit 0 — Copilot reviews are disabled: respond with the literal line
-`/copilot-review is disabled via CLAUDE_REVIEWS_DISABLED.` and stop — do not
-spawn the subagent, do not call the Copilot reviewer API, do not run any
-other step of this skill. Exit 1 — continue. Gate semantics live in the
-`reviewer-gates` skill ([../reviewer-gates/SKILL.md](../reviewer-gates/SKILL.md)).
-
-### Step 1: Gather PR context
-
-From the current repo:
-
-```bash
-# MCP: pull_request_read(method="get") returns {number, url, head.sha, base.ref, head.ref, isDraft}
-```
-
-Capture `number`, `head.sha`, 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: `pull_request_read(method="get", pullNumber=[NUMBER], owner="[OWNER]", repo="[REPO]")` and extract `.head.sha`.
-> 2. Fetch latest Copilot review via `pull_request_read(method="get_reviews", pullNumber=[NUMBER], owner="[OWNER]", repo="[REPO]")`.
->    Capture `commit_id`, `state`, `submitted_at`, `id`.
-> 3. Decide the branch:
->    - **No review exists:** increment `no_review_count` (see escalation rule below), re-request (step 4), schedule next wakeup, return.
->    - **Latest review's `commit_id` != current HEAD:** increment `no_review_count`, re-request (step 4), schedule next wakeup, return.
->    - **Latest review's `commit_id` == current HEAD with unresolved inline findings:** reset `no_review_count` to 0, TDD-fix them, push, reply inline on each thread, resolve each addressed 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.
->
->    **Escalation rule:** `no_review_count` starts at 0, counts consecutive ticks where no Copilot review exists at the current HEAD, and resets to 0 on every push and every review sighted at HEAD. When it reaches 3, Copilot is not delivering reviews — report the stall to the parent with the count and the last request timestamp, then terminate without scheduling another wakeup.
-> 4. Re-request Copilot via `request_copilot_review(owner="[OWNER]", repo="[REPO]", pullNumber=[NUMBER])`.
->    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.
-> 5. Schedule the next wakeup with `ScheduleWakeup`:
->    - `delaySeconds: 360`
->    - `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 `$HOME/.claude/skills/pr-fix-protocol/SKILL.md` and apply it — it carries the shared fix sequence, the reply-and-resolve unit, and the unresolved-thread sweep.
-> - 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.
-> - 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 via `add_reply_to_pull_request_comment(owner="[OWNER]", repo="[REPO]", pullNumber=[NUMBER], body="...", commentId=<comment_id>)`, referencing the new commit SHA; then resolve each addressed thread via `pull_request_review_write(method="resolve_thread", pullNumber=[NUMBER], owner="[OWNER]", repo="[REPO]", threadId="<PRRT id>")`, harvesting the `PRRT_…` id from `pull_request_read(method="get_review_comments", ...)`. Reply first, then resolve — atomic per thread, per the protocol.
->
-> 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.
-> - `no_review_count` reaches 3 (escalation rule above): report the stall and terminate.
->
-> **Safety cap:** after 20 ticks without convergence, stop and report. This is the total-tick runaway guard, distinct from the 3-consecutive-no-review escalation; 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, resolves 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>
+---
+name: copilot-review
+description: >-
+  Spawns a background subagent that babysits the GitHub Copilot reviewer on the
+  current PR: each tick it fixes unaddressed findings against HEAD, re-requests
+  review, and exits on convergence. Triggers: '/copilot-review', 'watch
+  copilot', 'babysit copilot review', '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.
+
+## Transport check (before any GitHub step)
+
+Run `command -v gh`; when it succeeds, run `gh auth status`; once the PR scope is resolved, run `gh api repos/<owner>/<repo> --jq .permissions.push` and take `true` as the pass. When any check fails, run the `pr-loop-cloud-transport` skill first, route every `gh` operation in this skill through its substitution matrix, and carry the same routing into the subagent prompt so the spawned watcher inherits it.
+
+## 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 0: Opt-out check
+
+Before any other work, run:
+
+```bash
+python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer copilot
+```
+
+Exit 0 — Copilot reviews are disabled: respond with the literal line
+`/copilot-review is disabled via CLAUDE_REVIEWS_DISABLED.` and stop — do not
+spawn the subagent, do not call the Copilot reviewer API, do not run any
+other step of this skill. Exit 1 — continue. Gate semantics live in the
+`reviewer-gates` skill ([../reviewer-gates/SKILL.md](../reviewer-gates/SKILL.md)).
+
+### Step 1: Gather PR context
+
+From the current repo:
+
+```bash
+# MCP: pull_request_read(method="get") returns {number, url, head.sha, base.ref, head.ref, isDraft}
+```
+
+Capture `number`, `head.sha`, 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 the prompt in
+[`templates/subagent-prompt.md`](templates/subagent-prompt.md) to the subagent
+word for word, filling in the bracketed values ([NUMBER], [OWNER], [REPO],
+[BRANCH], [HEAD_SHA]) from Step 1. It carries the per-tick work, the escalation
+rule (three consecutive no-review ticks), the fix protocol, the stop conditions,
+and the 20-tick safety cap.
+
+### 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, resolves 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>