claude-dev-env 1.92.0 → 1.93.0

package/skills/pr-converge/reference/per-tick.md

@@ -48,8 +48,8 @@ Capture `number`, `head.sha` (= `current_head`), owner/repo, branch.
 ## Step 1.5: Resolve the PR worktree (cwd routing)
 
 The **PR worktree** is the local working tree of the PR's repo on its head
-branch. Every local operation this tick runs there: the CODE_REVIEW
-`/code-review --fix`, every `clean-coder` fix spawn, and every commit and
+branch. Every local operation this tick runs there: the CODE_REVIEW static sweep
+and `/code-review high --fix`, every `clean-coder` fix spawn, and every commit and
 push. `/code-review` and `git` both act on the repo of the current working
 directory, so the working directory must be the PR worktree before any local
 work begins. Re-resolve it every tick — a rebase or a fresh HEAD can move the
@@ -90,7 +90,7 @@ outcome (no git work tree, or no readable origin) exits non-zero. Route on the
 
 - **`PREFLIGHT_OUTCOME=different_repo`** (the session is rooted in another repo
   — for example, the PR lives in `llm-settings` while the session runs from
-  `claude-code-config`): route the working directory into a checkout of the
+  `claude-dev-env`): route the working directory into a checkout of the
   PR's repo. This is routine and automatic — never pause, and never raise it as
   a fork (see [ground-rules.md](ground-rules.md)). `EnterWorktree` is scoped to
   the session's own repo and cannot re-root into the PR's repo.
@@ -150,75 +150,28 @@ outcome (no git work tree, or no readable origin) exits non-zero. Route on the
 
 ## Step 2: Branch on `phase`
 
-### `phase == BUGBOT`
-
-**Opt-out gate (runs first, before any fetch or trigger).**
-`python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer bugbot`
-
-- Exit 0 (`CLAUDE_REVIEWS_DISABLED` lists `bugbot`) → set `bugbot_down = true`,
-  `phase = CODE_REVIEW`, continue CODE_REVIEW in the same tick; skip steps a–c below.
-- Exit 1 → proceed to step a.
-
-Because `bugbot_down` resets on every push, this gate re-runs on every
-BUGBOT entry and keeps Cursor Bugbot skipped for the entire run.
-
-a. Fetch Cursor Bugbot reviews newest-first, walk back until first clean:
-
-   ```
-pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get_reviews")
-   → filter `.user.login` for cursor/bugbot, sort by `.submitted_at` descending
-   ```
-
-   Track dirty entries (review body contains `BUGBOT_REVIEW` markers with finding content); Fix protocol reads them back later this tick.
-
-   Iterate from index 0 (most recent) toward older:
-
-   - Dirty review → append JSON line with `{review_id, commit_id,
-     submitted_at, body}`.
-   - Stop at first clean. Older reviews presumed addressed at that
-     checkpoint.
-   - Index 0 clean → `$dirty_reviews_path` stays empty.
-
-Capture `commit_id`, `submitted_at`, body, `classification` of index-0
-review for decisions below. When branch routes to **Fix protocol**, address
-**every** entry in `$dirty_reviews_path` — not just index 0.
-
-b. Fetch ALL unresolved inline comment threads on the PR:
-
-   ```
-pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get_review_comments")
-   → filter threads where `is_resolved == false`
-   ```
-
-   Per-thread handling lives in the `pr-fix-protocol` skill's
-   unresolved-thread sweep (`../../pr-fix-protocol/SKILL.md`).
-
-c. Decide (four branches; match first whose predicate holds):
-   - **No bugbot review yet, OR latest review's `commit_id` ≠
-     `current_head`:** Re-trigger bugbot (Step 3), set `bugbot_clean_at =
-     null`, reset `inline_lag_streak = 0`, schedule next wakeup, return.
-   - **`commit_id == current_head` AND zero unaddressed inline AND review
-     body clean:** Set `bugbot_clean_at = current_head`, reset
-     `inline_lag_streak = 0`, `phase = CODE_REVIEW`. Continue CODE_REVIEW
-     in same tick — back-to-back convergence requires code-review then
-     bugteam on same HEAD before next wakeup.
-   - **`commit_id == current_head` with unaddressed inline findings:**
-     Apply the `pr-fix-protocol` skill (`../../pr-fix-protocol/SKILL.md`).
-     Reset `inline_lag_streak = 0`. With `state.json`: the clean-coder
-     teammate executes it, writes `state.json`, goes idle; Step 3 on new
-     HEAD runs after via orchestrator-spawned follow-up agent (§Fix result
-     → general-purpose). No `state.json` (single-PR): the lead executes it
-     → Step 3 in same tick. Schedule next wakeup, return.
+The internal passes drive the code to clean first. CODE_REVIEW is the entry phase
+each tick; BUGTEAM follows; the terminal Bugbot gate confirms; then the
+convergence gates and the terminal Copilot gate run. Every fix push re-enters at
+CODE_REVIEW.
 
 ### `phase == CODE_REVIEW`
 
-Local correctness/quality pass between BUGBOT clean and BUGTEAM. Enters
-after BUGBOT reports clean on `current_head` (or `bugbot_down == true`).
-Runs Claude Code's built-in `/code-review --fix` on the full
-`origin/main...HEAD` diff; it produces no GitHub review artifact, so there
-are no code-review threads to resolve.
-
-a. Run Claude Code's built-in `/code-review --fix` on the FULL
+The entry phase of every convergence tick, re-entered after any fix push. It runs
+a deterministic static sweep, then Claude Code's built-in `/code-review high
+--fix` on the full `origin/main...HEAD` diff; `/code-review` produces no GitHub
+review artifact, so there are no code-review threads to resolve.
+
+a. **Static sweep — runs first, before `/code-review`.** Run the deterministic
+   gates over the full `origin/main...HEAD` changed files:
+   `python "$HOME/.claude/_shared/pr-loop/scripts/code_rules_gate.py" --base origin/main`,
+   `ruff`, `mypy`, and stem-matched `pytest`. On any failure, apply the
+   `pr-fix-protocol` skill (`../../pr-fix-protocol/SKILL.md`), commit and push,
+   reset `bugbot_clean_at = null` and `code_review_clean_at = null`, stay
+   `phase = CODE_REVIEW`, and re-run the sweep. When the sweep is clean, run
+   `/code-review` below.
+
+b. Run Claude Code's built-in `/code-review high --fix` on the FULL
    `origin/main...HEAD` diff — every file the PR touches — via the
    [local diff review](https://code.claude.com/docs/en/code-review#review-a-diff-locally).
    It reviews the diff and applies its findings to the working tree.
@@ -229,26 +182,25 @@ a. Run Claude Code's built-in `/code-review --fix` on the FULL
    `current_head` — with no uncommitted edits. When the session is rooted in a
    different repo than the PR, the `cd` from Step 1.5 supplies this; the
    persisted working directory is what `/code-review` audits. Then invoke
-   `/code-review --fix` with no path arguments so it audits the whole branch
+   `/code-review high --fix` with no path arguments so it audits the whole branch
    diff against `origin/main`. Do not delta-scope to commits added since the
    prior clean SHA, do not scope to a single file, do not scope to bugbot's
    flagged paths. A partial-scope round does not count and cannot set
-   `code_review_clean_at`. Pass no effort argument, so the review uses
-   the session's current effort.
+   `code_review_clean_at`. Invoke `/code-review high --fix` so the pre-catch pass
+   gets broad coverage regardless of the session's current effort.
 
-b. Decide (two branches; match first whose predicate holds):
+c. Decide (two branches; match first whose predicate holds):
 
    - **`/code-review` applied fixes (working tree changed):** Commit the
      applied fixes in one commit → push, following the `pr-fix-protocol`
      skill's commit and push steps (`../../pr-fix-protocol/SKILL.md`). Reset
-     `bugbot_clean_at = null` AND `code_review_clean_at = null`. Re-trigger
-     bugbot (Step 3) so the new HEAD enters the queue. Set `phase = BUGBOT`,
-     schedule next wakeup, return. A code-review fix push requires a full
-     back-to-back-clean cycle on the new HEAD.
+     `bugbot_clean_at = null` AND `code_review_clean_at = null`. Stay
+     `phase = CODE_REVIEW`, schedule next wakeup, return. Every fix push
+     re-enters the internal passes on the new HEAD.
    - **Clean (no changes applied):** Set
      `code_review_clean_at = current_head`, `phase = BUGTEAM`. Continue
-     BUGTEAM in same tick — back-to-back convergence requires bugbot,
-     code-review, and bugteam all clean on the same HEAD.
+     BUGTEAM in same tick — back-to-back convergence requires code-review and
+     bugteam clean on the same HEAD before the terminal gates run.
 
 ### `phase == BUGTEAM`
 
@@ -300,27 +252,94 @@ c. Inspect bugteam outcome. Reports `convergence (zero findings)` or list
 of unfixed findings with file:line.
 
 d. Decide based on post-bugteam state — order matters. Check
-pushed-during-bugteam FIRST so convergence report against stale HEAD
+pushed-during-bugteam FIRST so a convergence report against a stale HEAD
 never falsely terminates:
    - **Audit pushed this tick (`bugbot_clean_at` reset in step b):**
-     Re-trigger bugbot same tick (Step 3) so new HEAD enters queue, `phase
-     = BUGBOT`, schedule next wakeup, return.
-   - **Convergence AND `bugbot_clean_at == current_head` (no push):**
-     Back-to-back clean — necessary, not sufficient. Run **[convergence-gates.md](convergence-gates.md)** to clear all six gates: Copilot findings,
-     Claude reviewer, mergeability, post-convergence Copilot request,
-     thread resolution. Only when all six gates pass mark PR ready and
-     **omit loop pacing** per **Convergence** of active pacing workflow.
-   - **Convergence BUT `bugbot_clean_at != current_head` (no push):**
-     `phase = BUGBOT`, schedule next wakeup, return.
+     Reset `code_review_clean_at = null`, `phase = CODE_REVIEW`, schedule next
+     wakeup, return. Every fix push re-enters the internal passes on the new
+     HEAD.
+   - **Convergence AND no push:** the internal passes are clean on
+     `current_head`. `phase = BUGBOT` — route into the terminal Bugbot gate,
+     which confirms and then runs the convergence gates. Continue BUGBOT in the
+     same tick.
    - **Findings without committed fixes:** apply the `pr-fix-protocol`
-     skill (`../../pr-fix-protocol/SKILL.md`).
-     `phase = BUGBOT`, schedule next wakeup, return.
+     skill (`../../pr-fix-protocol/SKILL.md`). Reset `code_review_clean_at =
+     null`, `phase = CODE_REVIEW`, schedule next wakeup, return.
+
+### `phase == BUGBOT` (terminal gate)
+
+The terminal external confirmation gate. BUGTEAM routes here once the internal
+passes are clean; Bugbot confirms the HEAD, then the convergence gates run.
+
+**Availability gate (runs first, before any fetch or trigger).**
+`python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer bugbot`
+
+- Exit 0 (Bugbot disabled for this run — the default, unless
+  `CLAUDE_REVIEWS_ENABLED` lists `bugbot`) → set `bugbot_down = true`, advance to
+  the [convergence gates](convergence-gates.md) in the same tick with the Bugbot
+  gate bypassed; skip steps a–c below.
+- Exit 1 (`CLAUDE_REVIEWS_ENABLED` lists `bugbot` and `CLAUDE_REVIEWS_DISABLED`
+  does not) → go to step a.
+
+Because `bugbot_down` resets on every push, this gate re-runs on every
+BUGBOT entry. Cursor Bugbot is off by default and runs only when
+`CLAUDE_REVIEWS_ENABLED` lists `bugbot`; a `bugbot` token in
+`CLAUDE_REVIEWS_DISABLED` keeps it off even then.
+
+a. Fetch Cursor Bugbot reviews newest-first, walk back until first clean:
+
+   ```
+pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get_reviews")
+   → filter `.user.login` for cursor/bugbot, sort by `.submitted_at` descending
+   ```
+
+   Track dirty entries (review body has `BUGBOT_REVIEW` markers with finding content); Fix protocol reads them back later this tick.
+
+   Iterate from index 0 (most recent) toward older:
+
+   - Dirty review → append JSON line with `{review_id, commit_id,
+     submitted_at, body}`.
+   - Stop at first clean. Older reviews presumed addressed at that
+     checkpoint.
+   - Index 0 clean → `$dirty_reviews_path` stays empty.
+
+Capture `commit_id`, `submitted_at`, body, `classification` of index-0
+review for decisions below. When branch routes to **Fix protocol**, address
+**every** entry in `$dirty_reviews_path` — not just index 0.
+
+b. Fetch ALL unresolved inline comment threads on the PR:
+
+   ```
+pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get_review_comments")
+   → filter threads where `is_resolved == false`
+   ```
+
+   Per-thread handling lives in the `pr-fix-protocol` skill's
+   unresolved-thread sweep (`../../pr-fix-protocol/SKILL.md`).
+
+c. Decide (four branches; match first whose predicate holds):
+   - **No bugbot review yet, OR latest review's `commit_id` ≠
+     `current_head`:** Re-trigger bugbot (Step 3), set `bugbot_clean_at =
+     null`, reset `inline_lag_streak = 0`, schedule next wakeup, return to the
+     Bugbot gate next tick.
+   - **`commit_id == current_head` AND zero unaddressed inline AND review
+     body clean:** Set `bugbot_clean_at = current_head`, reset
+     `inline_lag_streak = 0`, advance to the [convergence
+     gates](convergence-gates.md) in the same tick.
+   - **`commit_id == current_head` with unaddressed inline findings:**
+     Apply the `pr-fix-protocol` skill (`../../pr-fix-protocol/SKILL.md`).
+     Reset `inline_lag_streak = 0`, `bugbot_clean_at = null`,
+     `code_review_clean_at = null`, `phase = CODE_REVIEW`. With `state.json`:
+     the clean-coder teammate executes the fix, writes `state.json`, goes idle;
+     the next tick re-enters CODE_REVIEW on the new HEAD. No `state.json`
+     (single-PR): the lead executes it, stays `phase = CODE_REVIEW`. Schedule
+     next wakeup, return.
 
 ### `phase == COPILOT_WAIT`
 
-Post-convergence Copilot re-check. Enters after gate (d) requests Copilot
-review. Do **not** run bugteam here — that only happens after BUGBOT clean
-on this HEAD.
+Post-convergence Copilot re-check. Enters after the convergence gates request a
+Copilot review. Do **not** run bugteam here — the internal code-review and
+bugteam passes already converged before this terminal gate.
 
 a. Fetch latest Copilot review at `current_head` plus unaddressed inline
    comments:
@@ -343,9 +362,10 @@ b. Decide (three branches; match first whose predicate holds):
      at `current_head`:** Apply the `pr-fix-protocol` skill
      (`../../pr-fix-protocol/SKILL.md`) — it covers body-only findings with
      no inline threads. Reset
-     `bugbot_clean_at = null` AND `copilot_clean_at = null`. **Set
-     `phase = BUGBOT`** (NOT COPILOT_WAIT) — every fix push requires a full
-     back-to-back-clean cycle on the new HEAD. Schedule next wakeup, return.
+     `bugbot_clean_at = null`, `code_review_clean_at = null`, AND
+     `copilot_clean_at = null`. **Set `phase = CODE_REVIEW`** (NOT
+     COPILOT_WAIT) — every fix push re-enters the internal passes on the new
+     HEAD. Schedule next wakeup, return.
    - **No Copilot review at `current_head` yet:** Increment
      `copilot_wait_count` (init 0 on COPILOT_WAIT entry; reset to 0 on
      every push and on every successful Copilot review). `>= 3` → hard
@@ -353,25 +373,27 @@ b. Decide (three branches; match first whose predicate holds):
      schedule next wakeup (360s), return.
 
 **Non-negotiable:** After any Copilot fix push, `phase` MUST route to
-`BUGBOT`. Never cycle COPILOT_WAIT → fix → COPILOT_WAIT. The
-back-to-back-clean guarantee (bugbot ∧ bugteam both clean on same HEAD
-before gates re-open) only holds when every fix commit re-enters through
-BUGBOT.
+`CODE_REVIEW`. Never cycle COPILOT_WAIT → fix → COPILOT_WAIT. The
+back-to-back-clean guarantee (the internal code-review and bugteam passes both
+clean on the same HEAD before the terminal gates re-open) only holds when every
+fix commit re-enters through CODE_REVIEW.
 
 ## Step 3: Re-trigger bugbot
 
-- [ ] **Opt-out gate.** Enforced at BUGBOT entry (see `### phase == BUGBOT`).
-  When `CLAUDE_REVIEWS_DISABLED` lists `bugbot`, the entry gate sets
-  `bugbot_down = true` and routes to BUGTEAM before any trigger flow runs,
-  so the flow below is skipped.
+- [ ] **Availability gate.** Enforced at BUGBOT entry (see `### phase == BUGBOT`).
+  When Bugbot is disabled for the run — the default unless
+  `CLAUDE_REVIEWS_ENABLED` lists `bugbot`, and always when
+  `CLAUDE_REVIEWS_DISABLED` lists `bugbot` — the entry gate sets
+  `bugbot_down = true` and advances to the convergence gates before any trigger
+  flow runs, so the flow below is skipped.
 - [ ] Apply the `reviewer-gates` skill's Bugbot flow
   (`../../reviewer-gates/SKILL.md` § Gate 3) against `current_head` — the
   silent-pass pre-check, the already-queued check, the trigger comment, and
   the acknowledge check, with their rationale. Map its outcomes:
-- [ ] Silent pass → set `bugbot_clean_at = current_head`, `phase = CODE_REVIEW`, continue CODE_REVIEW same tick
+- [ ] Silent pass → set `bugbot_clean_at = current_head`, advance to the [convergence gates](convergence-gates.md) same tick
 - [ ] Already queued → skip posting, wait for completion, advance to Step 4
 - [ ] Trigger acknowledged (`bugbot_acknowledged_at` recorded) → advance to Step 4
-- [ ] Bugbot down → set `bugbot_down = true`, `phase = CODE_REVIEW`, continue CODE_REVIEW same tick
+- [ ] Bugbot down → set `bugbot_down = true`, advance to the [convergence gates](convergence-gates.md) same tick
 
 ## Step 4: Loop pacing
 

package/skills/pr-converge/reference/state-schema.md

@@ -10,7 +10,9 @@ live ONLY in the single-PR `$CLAUDE_JOB_DIR/pr-converge-state.json` file
 (see those field entries below for details).
 
 - `phase`: `BUGBOT`, `CODE_REVIEW`, `BUGTEAM`, or `COPILOT_WAIT`. Start
-  `BUGBOT` on first tick.
+  `CODE_REVIEW` on first tick. `BUGBOT` is the terminal external-confirmation
+  phase reached after BUGTEAM converges; the internal `CODE_REVIEW` and
+  `BUGTEAM` passes drive the code to clean before it runs.
 - `bugbot_clean_at`: HEAD SHA where bugbot last reported clean, or `null`.
   Reset to `null` on every push.
 - `code_review_clean_at`: HEAD SHA where the `/code-review` pass last
@@ -37,16 +39,19 @@ live ONLY in the single-PR `$CLAUDE_JOB_DIR/pr-converge-state.json` file
   body shows findings against `current_head` but inline API returns zero
   matching. Reset to `0` on any other branch outcome.
 - `bugbot_down`: boolean, init `false`. Set `true` when bugbot fails to
-  acknowledge a trigger comment; forces phase to BUGTEAM. Also set `true`
-  at every BUGBOT-phase entry when `CLAUDE_REVIEWS_DISABLED` lists the
-  `bugbot` token (env opt-out via the BUGBOT entry gate in `per-tick.md`),
-  which routes straight to BUGTEAM before any bugbot fetch or trigger. Also
-  set `true` when an acknowledged trigger has been outstanding more than 30
-  minutes with no surfaced review at `current_head` (per Step 2 BUGBOT (c)
-  30-minute budget — see `per-tick.md`). Reset to `false` on every push;
-  the entry gate re-applies the env opt-out on the next BUGBOT entry.
+  acknowledge a trigger comment; the convergence gates then run with the Bugbot
+  gate bypassed. Also set `true` at the terminal BUGBOT-phase entry whenever the
+  availability gate reports Bugbot disabled for the run — the default unless
+  `CLAUDE_REVIEWS_ENABLED` lists the `bugbot` token, and always when
+  `CLAUDE_REVIEWS_DISABLED` lists it (the BUGBOT entry gate in `per-tick.md`),
+  which advances to the convergence gates before any bugbot fetch or trigger.
+  Also set `true` when an acknowledged trigger has been outstanding more than 30
+  minutes with no surfaced review at `current_head` (per the terminal BUGBOT gate
+  30-minute budget — see `per-tick.md`). Reset to `false` on every push; the
+  entry gate re-applies the availability check on the next BUGBOT entry.
   Once set, remains `true` until the next push; if bugbot stays down
-  across ticks, the flag persists and BUGTEAM continues.
+  across ticks, the flag persists and the convergence gates keep the Bugbot gate
+  bypassed.
 - `bugbot_acknowledged_at`: ISO 8601 timestamp string or `null`. Records
   the wall-clock moment Cursor Bugbot acknowledged the most recent
   `bugbot run` trigger comment (i.e. the trigger comment carries an

package/skills/pr-converge/scripts/check_convergence.py

@@ -747,15 +747,16 @@ def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
 
 
 def _resolve_bugbot_down(bugbot_down_flag: bool) -> bool:
-    """Combine the explicit flag with the CLAUDE_REVIEWS_DISABLED env opt-out.
+    """Combine the explicit flag with the env availability gate for Bugbot.
 
     Args:
         bugbot_down_flag: Value of the ``--bugbot-down`` CLI flag.
 
     Returns:
-        True when the flag is set OR ``CLAUDE_REVIEWS_DISABLED`` lists the
-        ``bugbot`` token, so the env opt-out bypasses the bugbot gates even
-        when the caller omits the flag.
+        True when the flag is set, or when Bugbot is disabled for the run:
+        off by default unless ``CLAUDE_REVIEWS_ENABLED`` lists ``bugbot``, and
+        always when ``CLAUDE_REVIEWS_DISABLED`` lists ``bugbot``. The env gate
+        bypasses the bugbot gates even when the caller omits the flag.
     """
     return bugbot_down_flag or is_bugbot_disabled_via_env()
 

package/skills/pr-converge/scripts/test_check_convergence.py

@@ -231,17 +231,19 @@ def should_resolve_bugbot_down_true_when_env_disables_bugbot(
     assert check_convergence._resolve_bugbot_down(False) is True
 
 
-def should_resolve_bugbot_down_false_when_flag_unset_and_env_empty(
+def should_resolve_bugbot_down_true_when_flag_unset_and_env_empty(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
-    assert check_convergence._resolve_bugbot_down(False) is False
+    monkeypatch.delenv("CLAUDE_REVIEWS_ENABLED", raising=False)
+    assert check_convergence._resolve_bugbot_down(False) is True
 
 
-def should_resolve_bugbot_down_false_when_env_disables_only_bugteam(
+def should_resolve_bugbot_down_false_when_enabled_lists_bugbot(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugteam")
+    monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
+    monkeypatch.setenv("CLAUDE_REVIEWS_ENABLED", "bugbot")
     assert check_convergence._resolve_bugbot_down(False) is False
 
 

package/skills/pr-fix-protocol/SKILL.md

@@ -2,14 +2,9 @@
 name: pr-fix-protocol
 description: >-
   Applies reviewer findings to a PR as verified fixes and drives unresolved
-  review threads to zero: executor choice (clean-coder spawn or multi-PR
-  teammate with a worktree-path handoff), the shared 13-step fix sequence
-  (TDD, one commit, fast-forward push), an atomic reply-and-resolve per
-  thread, the unresolved-thread sweep hard gate (is_resolved == false is the
-  only filter), and post-push state resets. Invoked by PR-loop orchestrators
-  (pr-converge, autoconverge, bugteam, qbug, copilot-review) whenever a
-  reviewer reports findings or unresolved threads exist; not for ad-hoc "fix
-  this bug" requests outside a PR review loop.
+  review threads to zero. Invoked by PR-loop orchestrators (pr-converge,
+  autoconverge, bugteam, qbug, copilot-review) when a reviewer reports
+  findings; not for ad-hoc 'fix this bug' requests outside a PR loop.
 ---
 
 # PR Fix Protocol

package/skills/pr-loop-cloud-transport/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: pr-loop-cloud-transport
+description: Runs any PR-loop skill in a Claude Code session whose gh CLI cannot act on the PR — the binary is absent, gh auth status fails, or the active login cannot act on the PR's owner. A six-step transport workflow loads the GitHub MCP schemas, fixes origin/HEAD before pushes, keys review rules to the live MCP identity, routes every GitHub operation through the gh-to-MCP substitution matrix, reads Copilot status from what lands on the PR, and self-checks the posts the gh-text hooks cannot gate. Use at run start when pr-converge, autoconverge, bugteam, qbug, findbugs, fixbugs, monitor-open-prs, or copilot-review runs in a cloud session, when `command -v gh` or `gh auth status` fails, or when an MCP tool call fails with InputValidationError.
+---
+
+# PR-loop cloud transport
+
+One workflow that makes a cloud session able to run the PR-loop skill family. A cloud session ships no `gh` binary and cannot fetch one, so every `gh` step in a PR-loop skill routes through the GitHub MCP tools; this skill is the setup and routing contract for that substitution. The same routing serves a session whose `gh` is present but unauthenticated, or authenticated as an account that cannot act on the PR's owner — a binary that cannot act on the PR is as unusable as a binary that is not there. The evidence base is `docs/references/cloud-pr-loop-compatibility.md` in the source repo — every rule here traces to a live probe, the operation inventory recorded there, or the auth rule the calling skills state.
+
+## Decide the transport first
+
+Three checks, in order; the first failure routes to the cloud transport:
+
+1. `command -v gh` — the binary exists.
+2. `gh auth status` — an active authenticated account exists; a non-zero exit fails the check.
+3. Once the PR scope is resolved (owner and repo known): `gh api repos/<owner>/<repo> --jq .permissions.push` must print `true`. The `permissions` object in that response reports the authenticated account's own rights on the repo, `push` included (live probe: the Section 7 appendix row in the runbook), so one command proves the binary, the auth, and the account's write access together. An error, a 404, or `false` fails the check.
+
+- **All three pass** → local session. Stop here; follow the calling skill's own steps unchanged.
+- **Any check fails** → cloud transport. Run the workflow below, then follow the calling skill's steps with every `gh` operation swapped for its cloud path.
+
+A read-scoped account passes checks 1 and 2 and fails check 3 — the PR-loop skills push fix commits, so `push: false` means the local path stalls at its first push while the MCP transport carries the run.
+
+## Cloud transport workflow
+
+Copy this checklist and check off items as you complete them:
+
+```
+Cloud transport setup:
+- [ ] Step 1: Load MCP schemas (once per session)
+- [ ] Step 2: Fix origin/HEAD in every repo root
+- [ ] Step 3: Read the MCP identity and key the review rules to it
+- [ ] Step 4: Route every GitHub operation through the substitution matrix
+- [ ] Step 5: Read Copilot status from what lands on the PR
+- [ ] Step 6: Self-check the posts the quiet hooks would have gated
+```
+
+**Step 1: Load MCP schemas (once per session)**
+
+MCP tool schemas are deferred: a call before its schema loads fails with `InputValidationError`. Run exactly:
+
+```
+ToolSearch "select:mcp__github__pull_request_read,mcp__github__pull_request_review_write,mcp__github__add_comment_to_pending_review,mcp__github__add_reply_to_pull_request_comment,mcp__github__add_issue_comment,mcp__github__request_copilot_review,mcp__github__update_pull_request,mcp__github__create_pull_request,mcp__github__issue_write,mcp__github__search_pull_requests,mcp__github__get_me,mcp__github__actions_list,mcp__github__actions_get,mcp__github__get_job_logs,mcp__Claude_Code_Remote__add_repo"
+```
+
+Every name carries its full `mcp__` prefix — a bare name matches nothing and loads no schema. The list mixes servers on purpose: the `mcp__github__*` tools plus `mcp__Claude_Code_Remote__add_repo` for cross-repo checkout.
+
+Verify: call `mcp__github__get_me`. A returned login confirms the load; an `InputValidationError` means a schema is missing — re-run the load with the failing tool named, then verify again.
+
+**Step 2: Fix origin/HEAD in every repo root**
+
+Cloud clones do not set `origin/HEAD`, and the global pre-push hook resolves its base ref from it, so every `git push` fails with `fatal: Not a valid object name origin/HEAD` until the ref exists. For each repo root the run touches:
+
+```
+git -C <repo-root> remote set-head origin -a
+```
+
+Feedback loop: a push that fails with the `origin/HEAD` message means this step has not run in that repo — run it there and push again. Never route around the hook with `--no-verify`.
+
+**Step 3: Read the MCP identity and key the review rules to it**
+
+Call `mcp__github__get_me` and record the login. Key every identity rule to that live login, not to a fixed account name:
+
+- On a PR the MCP login authored, post `COMMENT` reviews only — GitHub blocks `APPROVE` and `REQUEST_CHANGES` on one's own PR. On a PR another account authored, any review type works.
+- Leave `BUGTEAM_REVIEWER_ACCOUNT` unset and skip every account-swap step; the swap path has no cloud form.
+- A second identity rides raw REST: a body posted with `GH_TOKEN` lands as the `claude[bot]` GitHub App. Self-PR checks and bot filters account for the split.
+
+Full identity rules, the REST fallback scope, and the two-identity model: see [reference/identity-and-hooks.md](reference/identity-and-hooks.md).
+
+**Step 4: Route every GitHub operation through the substitution matrix**
+
+Every `gh` operation in the calling skill has one cloud path. The full operation-by-operation table: see [reference/substitution-matrix.md](reference/substitution-matrix.md). The rules that carry the most weight:
+
+- Read review threads with `mcp__github__pull_request_read(method="get_review_comments")` and resolve them with `mcp__github__pull_request_review_write(method="resolve_thread", threadId="PRRT_...")`. Custom GraphQL is pinned to a served set, so hand-written `gh api graphql` queries have no cloud path.
+- Reply to an inline comment with `mcp__github__add_reply_to_pull_request_comment` using the numeric id from the comment's `discussion_r` anchor.
+- Always pass `perPage` on `mcp__github__search_pull_requests` — an unpaginated owner-wide search overflows the tool-result limit.
+- Helper scripts that spawn `gh` subprocesses fail in cloud; run their steps through the matrix and keep their decision rules.
+
+**Step 5: Read Copilot status from what lands on the PR**
+
+Skip the `gh api copilot_internal/user` quota read; treat Copilot quota as unknown. Call `mcp__github__request_copilot_review` — its silent completion confirms nothing either way. Status comes from the PR afterward:
+
+- A Copilot review on the HEAD, clean or with findings, means Copilot is up.
+- An out-of-usage notice on the HEAD, or no review within the caller's poll budget, means Copilot is down — bypass the gate and say plainly in the run report that the status is an environment limit.
+
+**Step 6: Self-check the posts the quiet hooks would have gated**
+
+The `gh`-text hooks read risk from literal `gh ...` command text, and an MCP post carries none, so those checks go quiet in cloud. Before each MCP post, check by hand:
+
+- No volatile scratch path in a post body (job dirs, temp roots, worktrees).
+- A proof-of-work comment carries all five parts the proof standard names.
+- A PR title follows Conventional Commits.
+- Markdown bodies go through the structured `body` parameter so backticks show as formatting.
+
+The commit and push gates still fire on cloud Bash git commands — follow them normally. The full hook roster and which side of the split each hook sits on: see [reference/identity-and-hooks.md](reference/identity-and-hooks.md).
+
+## Layout
+
+| File | Role |
+|---|---|
+| `SKILL.md` | This workflow: the transport decision, the six setup and routing steps, and the progress checklist |
+| `reference/substitution-matrix.md` | The gh-to-MCP operation substitution matrix, pagination rules, and the REST fallback scope |
+| `reference/identity-and-hooks.md` | The two-identity model, self-PR review rules, and the hook-coverage split in cloud sessions |

package/skills/pr-loop-cloud-transport/reference/identity-and-hooks.md

@@ -0,0 +1,40 @@
+# Identity model and hook coverage in cloud sessions
+
+The identity rules a PR-loop run keys its reviews to, and the split between hooks that still gate a cloud run and hooks that go quiet on the MCP path. Every rule traces to a live probe recorded in `docs/references/cloud-pr-loop-compatibility.md` in the source repo.
+
+## Contents
+
+- The two-identity model
+- Self-PR review rules
+- Hooks that still gate a cloud run
+- Hooks that go quiet on the MCP path
+
+## The two-identity model
+
+Two identities run side by side in a cloud session:
+
+- **The MCP identity.** Every `mcp__github__*` tool acts as the user the `mcp__github__get_me` login names. Read it at run start and key every identity rule to that live login, not to a fixed account name.
+- **The REST identity.** A body posted over raw REST with `GH_TOKEN` lands as the `claude[bot]` GitHub App (`author_association` NONE), with a server-appended `Generated by Claude Code` footer. `GET /user` still answers with the MCP user login.
+
+Author-keyed logic accounts for the split: a self-PR check keys on the login that opened the PR, and a bot filter treats `claude[bot]` as the session's own REST author.
+
+## Self-PR review rules
+
+- On a PR the MCP login authored, post `COMMENT` reviews. GitHub blocks `APPROVE` and `REQUEST_CHANGES` on one's own PR.
+- On a PR another account authored, a review of any type from the MCP login works — including the APPROVE that a CLEAN bugteam audit posts.
+- Leave `BUGTEAM_REVIEWER_ACCOUNT` unset. The account-swap path (`gh auth switch`, the swap helpers) has no cloud form.
+
+## Hooks that still gate a cloud run
+
+The commit and push gates read git commands, which a cloud run still issues through Bash, so they fire normally and the run follows them: `verified_commit_gate`, `session_edit_stage_gate`, `block_main_commit`, `precommit_code_rules_gate`, `test_preflight_check`, and the pre-push base-ref check that needs `origin/HEAD` set (SKILL.md Step 2).
+
+## Hooks that go quiet on the MCP path
+
+The `gh`-text hooks read risk from literal `gh ...` command text: `pr_description_enforcer`, `gh_body_arg_blocker`, `conventional_pr_title_gate`, `gh_pr_author_enforcer`, the `gh` branch of `volatile_path_in_post_blocker`, and the `gh pr ready` branch of `convergence_gate_blocker`. An MCP post carries no `gh` text, so these checks see nothing to gate while the settings matchers name only the local tool prefix. The run covers the gap by hand before each MCP post — the Step 6 self-check in SKILL.md:
+
+- No volatile scratch path in a post body (job dirs, temp roots, worktrees).
+- A proof-of-work comment carries all five parts the proof standard names.
+- A PR title follows Conventional Commits.
+- Markdown bodies go through the structured `body` parameter so backticks show as formatting.
+
+`gh_pr_author_enforcer` shells to `gh`, catches the missing-binary error, and does nothing in cloud — it fails open by design.

package/skills/pr-loop-cloud-transport/reference/substitution-matrix.md

@@ -0,0 +1,48 @@
+# gh-to-MCP operation substitution matrix
+
+Route every `gh` operation a PR-loop skill names through its cloud path. Load the MCP schemas first (SKILL.md Step 1) — a call before its schema loads fails with `InputValidationError`. Every row traces to a live probe or the operation inventory recorded in `docs/references/cloud-pr-loop-compatibility.md` in the source repo.
+
+## Contents
+
+- The operation matrix
+- Pagination rules
+- The REST fallback and its scope
+
+## The operation matrix
+
+| Operation | Local mechanism | Cloud path |
+|---|---|---|
+| Read PR / mergeability / draft state | `gh pr view`, `gh api pulls/N` | `mcp__github__pull_request_read(method="get")` |
+| PR diff / files / commits / checks | `gh pr diff`, `gh api ...` | `mcp__github__pull_request_read(method="get_diff"/"get_files"/"get_commits"/"get_check_runs")` |
+| List reviews / review threads | `gh api --paginate --slurp \| jq` | `mcp__github__pull_request_read(method="get_reviews"/"get_review_comments")` |
+| Post / update / close issue | `gh issue create/edit/close` | `mcp__github__issue_write(method="create"/"update")`; close an issue with `method="update", state="closed"` |
+| Post issue or PR comment | `gh issue comment`, `gh pr comment` | `mcp__github__add_issue_comment` |
+| Post review with inline comments | `gh api pulls/N/reviews` POST | `mcp__github__pull_request_review_write(method="create")` → `mcp__github__add_comment_to_pending_review` per finding → `mcp__github__pull_request_review_write(method="submit_pending", event="COMMENT")` |
+| Reply to a review comment | `gh api pulls/N/comments/ID/replies` | `mcp__github__add_reply_to_pull_request_comment` (numeric `discussion_r` id) |
+| Resolve / unresolve a thread | `gh api graphql resolveReviewThread` | `mcp__github__pull_request_review_write(method="resolve_thread"/"unresolve_thread", threadId="PRRT_...")` |
+| Request the Copilot reviewer | `gh api POST pulls/N/requested_reviewers` | `mcp__github__request_copilot_review`. The call completes with no output and no in-band confirmation either way; confirm by a Copilot review landing on the PR. |
+| Mark ready / send to draft | `gh pr ready`, `gh pr ready --undo` | `mcp__github__update_pull_request(draft=false / draft=true)`, with a read-back confirming the draft state each way |
+| Create a PR | `gh pr create --draft` | `mcp__github__create_pull_request(draft=true)` |
+| Edit a PR body or title | `gh pr edit` | `mcp__github__update_pull_request(body=..., title=...)` |
+| Cross-repo PR search | `gh search prs --owner X --state open` | `mcp__github__search_pull_requests(query="user:X is:open", perPage=30)` |
+| Check runs on a SHA | `gh api commits/SHA/check-runs` | `mcp__github__pull_request_read(method="get_check_runs")`, or REST for owners the app connection covers |
+| CI logs | `gh run view --log` | `mcp__github__actions_list` / `mcp__github__actions_get` / `mcp__github__get_job_logs` |
+| Clone another repo | `gh repo clone` | `git clone https://github.com/owner/repo` (session-scoped), or `mcp__Claude_Code_Remote__add_repo` first |
+| Copilot quota | `gh api copilot_internal/user` | None. Treat quota as unknown; call `mcp__github__request_copilot_review`, then read `copilot_down` from what lands on the PR (SKILL.md Step 5). |
+| Second reviewer identity | `gh auth switch`, `BUGTEAM_REVIEWER_ACCOUNT` | None. One MCP identity — the `mcp__github__get_me` login. `COMMENT` reviews on own PRs work; `APPROVE`/`REQUEST_CHANGES` on own PRs are blocked by GitHub. |
+
+## Pagination rules
+
+- `mcp__github__pull_request_read(method="get_reviews")` paginates with `page` + `perPage`.
+- `mcp__github__pull_request_read(method="get_review_comments")` paginates with `perPage` + an `after` cursor.
+- Always pass `perPage` on `mcp__github__search_pull_requests`: an unpaginated owner-wide search overflows the tool-result limit.
+
+## The REST fallback and its scope
+
+Raw REST through the agent proxy works only for owners the Claude GitHub App connection covers; a repo outside that coverage answers 403. The client shape:
+
+```
+curl -H "Authorization: Bearer $GH_TOKEN" --cacert /root/.ccr/ca-bundle.crt https://api.github.com/repos/<owner>/<repo>/...
+```
+
+GraphQL through the proxy is pinned to a served set of PR-review operations, so a hand-written `gh api graphql` query has no cloud path — read review threads through `mcp__github__pull_request_read(method="get_review_comments")` and resolve them through `mcp__github__pull_request_review_write(method="resolve_thread", ...)`.