claude-dev-env 2.0.2 → 2.2.0

package/skills/pr-converge/reference/CLAUDE.md

@@ -6,6 +6,7 @@ Reference documents for the `pr-converge` skill. These files define the per-tick
 
 | File | Purpose |
 |---|---|
+| `progress-checklist.md` | The per-tick eleven-step checklist (Step 0 open → Step 11 report), each step pointing to its spoke file |
 | `per-tick.md` | Step-by-step procedure for one tick (resolve HEAD, run the internal CODE_REVIEW and BUGTEAM phases, then the terminal BUGBOT and COPILOT_WAIT gates, schedule next wakeup) |
 | `convergence-gates.md` | Six gates that must all pass before the PR is marked ready for review |
 | `fix-protocol.md` | pr-converge deltas on the `pr-fix-protocol` skill: multi-PR teammate obligations and the same-tick bugbot re-trigger rule |

package/skills/pr-converge/reference/multi-pr-orchestration.md

@@ -210,7 +210,11 @@ When bugfix (clean-coder) subagent completes after push:
 3. Each PR with new subagent results → spawn next agent per rules, all
    in one parallel message.
 4. Re-read `state.json` if needed for scheduling.
-5. Call `ScheduleWakeup` with appropriate delay.
+5. Advance the pacer: on `pacer=schedule_wakeup`, call `ScheduleWakeup`
+   with the appropriate delay; on `pacer=portable`, continue or poll
+   in-session per
+   [`../../_shared/pr-loop/portable-driver.md`](../../_shared/pr-loop/portable-driver.md)
+   (no `ScheduleWakeup`).
 6. Nothing else.
 
 ## Memory

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

@@ -15,29 +15,38 @@ Use on **draft PR**. Cursor Bugbot and `/bugteam` re-run after each push. Fix
 findings between rounds until back-to-back clean on same `HEAD`, then mark
 PR ready for review.
 
-Run every tick in parent harness session. Pacing lives in
-[`../workflows/schedule-wakeup-loop.md`](../workflows/schedule-wakeup-loop.md) (read before Step 4); see [Pacing
-workflow](#pacing-workflow).
+Run every tick in the parent harness session. Pacing depends on the selected
+pacer from pre-flight (`select_converge_pacer.py`):
+
+- `schedule_wakeup` — [`../workflows/schedule-wakeup-loop.md`](../workflows/schedule-wakeup-loop.md)
+- `portable` — [`../../_shared/pr-loop/portable-driver.md`](../../_shared/pr-loop/portable-driver.md)
+
+See [Pacing workflow](#pacing-workflow).
 
 Every BUGTEAM tick runs **bugteam** — never hand-rolled substitute. Fix
-protocol per [fix-protocol.md](fix-protocol.md). Pacing stays in main session via
-`ScheduleWakeup` (pre-flight aborts when absent).
+protocol per [fix-protocol.md](fix-protocol.md). Pacing stays in the main
+session (native `ScheduleWakeup` or the portable continuous driver).
 
 ## Invocation modes
 
-- **`/pr-converge`** runs one tick, then Step 4 schedules the next via
-  `ScheduleWakeup`. Omit the next wakeup only on convergence or **Stop
-  conditions**.
+- **`/pr-converge` with `pacer=schedule_wakeup`** runs one tick, then Step 4
+  schedules the next via `ScheduleWakeup`. Omit the next wakeup only on
+  convergence or **Stop conditions**.
+- **`/pr-converge` with `pacer=portable`** runs ticks continuously in-session
+  (poll waits at the same delays); write handoff at budget boundaries. See
+  the portable driver.
 
 ## Pacing workflow
 
-Read [`../workflows/schedule-wakeup-loop.md`](../workflows/schedule-wakeup-loop.md)
+When `pacer=schedule_wakeup`, read
+[`../workflows/schedule-wakeup-loop.md`](../workflows/schedule-wakeup-loop.md)
 (installed copy under `$HOME/.claude/skills/pr-converge/workflows/`) before
-Step 4. The pre-flight gate guarantees `ScheduleWakeup` is invokable; the
-workflow file specifies delays, prompts, and convergence cleanup.
+Step 4. When `pacer=portable`, read
+[`../../_shared/pr-loop/portable-driver.md`](../../_shared/pr-loop/portable-driver.md)
+and skip `ScheduleWakeup` calls.
 
 - **`/pr-converge`** (default): loops until convergence. After each tick
-  (unless converged or stopped), run **Step 4**.
+  (unless converged or stopped), run **Step 4** using the selected pacer.
 
 ## Step 1: Resolve current HEAD and PR context
 
@@ -244,8 +253,8 @@ c. Decide (three branches; match first whose predicate holds):
 
    - **Failed review (`returncode != 0`, or chain mode with null
      `served_command`):** The review did not complete a successful serve. Do
-     not set `code_review_clean_at`. Stay `phase = CODE_REVIEW`, schedule next
-     wakeup, return. A failed chain often leaves `dirty_tree` false — that is
+     not set `code_review_clean_at`. Stay `phase = CODE_REVIEW`, apply Step 4 pacer
+     (ScheduleWakeup or portable continue/poll), return. A failed chain often leaves `dirty_tree` false — that is
      not a clean stamp.
    - **Fixes applied (working tree dirty / `dirty_tree` true):** Commit the
      applied fixes in one commit → push, following the shared fix protocol
@@ -253,7 +262,7 @@ c. Decide (three branches; match first whose predicate holds):
      push-invalidated markers per [ground-rules.md](ground-rules.md) /
      [state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
      `bugbot_down`, `bugbot_acknowledged_at`, `codex_down`). Stay
-     `phase = CODE_REVIEW`, schedule next wakeup, return. Every fix push
+     `phase = CODE_REVIEW`, apply Step 4 pacer (ScheduleWakeup or portable continue/poll), return. Every fix push
      re-enters the internal passes on the new HEAD.
    - **Clean (successful serve: `returncode == 0`, chain `served_command`
      non-null when `mode == chain`, and `dirty_tree` false):** Set
@@ -318,7 +327,7 @@ d. Decide based on post-bugteam state — order matters. Check
 pushed-during-bugteam FIRST so a convergence report against a stale HEAD
 never falsely terminates:
    - **Audit pushed this tick (clean-at fields reset in step b):**
-     `phase = CODE_REVIEW`, schedule next wakeup, return. Every fix push
+     `phase = CODE_REVIEW`, apply Step 4 pacer (ScheduleWakeup or portable continue/poll), 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`. Stamp `bugteam_clean_at = current_head`, then
@@ -328,8 +337,8 @@ never falsely terminates:
      ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [fix-protocol.md](fix-protocol.md)). Reset push-invalidated markers
      per [ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md)
      (all `*_clean_at`, `merge_state_status`, `bugbot_down`,
-     `bugbot_acknowledged_at`, `codex_down`), `phase = CODE_REVIEW`, schedule
-     next wakeup, return.
+     `bugbot_acknowledged_at`, `codex_down`), `phase = CODE_REVIEW`, apply Step 4 pacer
+     (ScheduleWakeup or portable continue/poll), return.
 
 ### `phase == BUGBOT` (terminal gate)
 
@@ -386,7 +395,7 @@ pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get_review_
 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
+     null`, reset `inline_lag_streak = 0`, apply Step 4 pacer (ScheduleWakeup or portable continue/poll), 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
@@ -402,7 +411,7 @@ c. Decide (four branches; match first whose predicate holds):
      `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 = CODE_REVIEW`. Apply Step 4 pacer (ScheduleWakeup or portable continue/poll), return.
 
 ### `phase == COPILOT_WAIT`
 
@@ -435,12 +444,12 @@ b. Decide (three branches; match first whose predicate holds):
      (all `*_clean_at`, `merge_state_status`, `bugbot_down`,
      `bugbot_acknowledged_at`, `codex_down`). **Set `phase = CODE_REVIEW`**
      (NOT COPILOT_WAIT) — every fix push re-enters the internal passes on the
-     new HEAD. Schedule next wakeup, return.
+     new HEAD. Apply Step 4 pacer (ScheduleWakeup or portable continue/poll), 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
      blocker per [stop-conditions.md](stop-conditions.md). Otherwise
-     schedule next wakeup (360s), return.
+     apply Step 4 pacer (ScheduleWakeup or portable continue/poll; 360s wait), return.
 
 **Non-negotiable:** After any Copilot fix push, `phase` MUST route to
 `CODE_REVIEW`. Never cycle COPILOT_WAIT → fix → COPILOT_WAIT. The
@@ -508,8 +517,11 @@ base), never an invented commit range.
 
 ## Step 4: Loop pacing
 
-**`ScheduleWakeup` field hints** (prefer [Pacing
-workflow](#pacing-workflow)):
+Apply the pacer selected at pre-flight ([Pacing workflow](#pacing-workflow)).
+
+### `pacer=schedule_wakeup`
+
+**`ScheduleWakeup` field hints:**
 
 - `delaySeconds: 360` after bugbot re-trigger. Exception:
   BUGBOT inline-lag branch uses `delaySeconds: 90` (no re-trigger;
@@ -521,6 +533,21 @@ workflow](#pacing-workflow)):
 **On convergence:** apply **Convergence** section of
 `../workflows/schedule-wakeup-loop.md` (omit wakeups).
 
+### `pacer=portable`
+
+Do **not** call `ScheduleWakeup`. After writing state and handoff:
+
+- **Immediate work next** → continue the next tick in the same turn.
+- **Wait next** (Bugbot queued, COPILOT_WAIT with no review yet) → poll
+  in-session for the same delay (`360` default, `90` on Bugbot inline-lag),
+  then resume the same step. Honor the same hard caps as the ScheduleWakeup
+  path.
+- **Budget too low for a full tick** → stop at the tick boundary; print
+  `/pr-converge <PR URL>` and the persisted phase.
+
+Full portable rules:
+[`../../_shared/pr-loop/portable-driver.md`](../../_shared/pr-loop/portable-driver.md).
+
 ## Bugteam execution
 
 **Second audit** (BUGTEAM phase) is **always** **bugteam** skill: preflight,

package/skills/pr-converge/reference/progress-checklist.md

@@ -0,0 +1,168 @@
+# pr-converge progress checklist
+
+The per-tick step sequence for the pr-converge loop. The hub
+([`../SKILL.md`](../SKILL.md)) points here; run these steps in order, one pass
+per tick.
+
+State variables (`phase`, `bugbot_clean_at`, `code_review_clean_at`,
+`bugteam_clean_at`, `copilot_clean_at`, `merge_state_status`, counters) are
+defined in [`state-schema.md`](state-schema.md). Ground rules
+in [`ground-rules.md`](ground-rules.md).
+
+Each step references its spoke file for full procedural detail — MCP calls,
+script invocations, decision criteria. Every "return to Step N" means the next
+tick starts fresh from that step.
+
+**Hard gate: do not advance from any step while ANY unresolved review
+thread exists on the PR.** Sweep semantics and per-thread handling live in
+the shared fix protocol
+([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md)
+step 12; skill deltas in [`fix-protocol.md`](fix-protocol.md)).
+
+**Full-PR-diff rule: every CODE-REVIEW round (Step 5) and every BUGTEAM
+round (Step 6) covers the FULL `origin/main...HEAD` diff — every file
+the PR touches.** A round that scopes to a subset — only the last commit,
+only files touched since the prior clean SHA, only bugbot-flagged paths,
+or any other delta cut — does not satisfy the gate, and a "clean" verdict
+against a partial diff is not a valid clean. Re-run the round against the
+full diff before recording `code_review_clean_at` or treating the bugteam
+round as converged. This rule holds every tick, every loop, every PR.
+
+- [ ] **Step 0: Open the run**
+      Apply the `pr-loop-lifecycle` skill's Open section
+      (`../../pr-loop-lifecycle/SKILL.md`): permission grant + worktree preflight.
+
+- [ ] **Step 1: Resolve PR scope + PR worktree**
+      Apply Step 1.5 scope resolution in
+      [`per-tick.md`](per-tick.md). Resolve the **PR
+      worktree** — the local checkout every local step this tick targets:
+      the `EnterWorktree` checkout when the PR shares the session's repo,
+      else a checkout of the PR's repo that the working directory routes
+      into via `cd`. Cross-repo routing is automatic, not a fork.
+      See: [`per-tick.md` § Step 1](per-tick.md)
+      and [§ Step 1.5](per-tick.md)
+
+- [ ] **Step 2: Initialize loop state**
+      `phase = CODE_REVIEW`; all counters at zero; `run_name` resolved.
+
+- [ ] **Step 3: Mergeability check**
+      See: [`convergence-gates.md` § (c)](convergence-gates.md)
+
+      ```
+      pull_request_read(method="get") → .mergeable_state, .mergeable
+      ```
+
+      - [ ] mergeable → advance to Step 4
+      - [ ] not mergeable → rebase → force-push → return to Step 1
+
+- [ ] **Step 4: BUGBOT — terminal Bugbot confirmation gate**
+      Step 6 routes here after BUGTEAM converges. Bugbot confirms code the
+      internal passes already drove to clean.
+      See: [`per-tick.md` § BUGBOT terminal gate + Step 3](per-tick.md);
+      availability and trigger via `reviewer-gates`
+      (`../../reviewer-gates/SKILL.md` § Gate 1 / Gate 3).
+
+      - [ ] **disabled / down** → `bugbot_down = true` → Step 7
+      - [ ] **dirty on `current_head`** → apply shared fix protocol
+            ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md);
+            skill deltas in [`fix-protocol.md`](fix-protocol.md))
+            → push → reset push-invalidated markers → `phase = CODE_REVIEW` → Step 5
+      - [ ] **clean on `current_head`** → zero unresolved threads (else fix + resolve first)
+            → `bugbot_clean_at = current_head` → Step 7
+      - [ ] **no review / commit_id mismatch** → `reviewer-gates` Bugbot flow (Gate 3):
+            silent pass → stamp + Step 7; queued/triggered → 360s wakeup → Step 4;
+            down → `bugbot_down = true` → Step 7
+
+- [ ] **Step 5: CODE-REVIEW — static sweep, review, fix, advance**
+      Entry phase every tick; re-entered after any fix push.
+      See: [`per-tick.md` § CODE_REVIEW entry](per-tick.md).
+      Pre-condition: cwd is the Step 1.5 PR worktree on `current_head`.
+      Scope: FULL `origin/main...HEAD` diff every tick (no path args, no delta cut).
+      Review always runs at effort high on model opus through
+      `invoke_code_review.py`. Mode decision inputs: host profile + session
+      model. Call:
+      `python "$HOME/.claude/scripts/invoke_code_review.py" --cwd <PR-worktree>
+      --session-model <alias>`. Chain mode uses that cwd and empty stdin; the
+      chain process never commits and never pushes. JSON stdout carries
+      `mode` (`in_session` | `chain`), `served_command`, `returncode`, and
+      `dirty_tree`. Config/host errors still emit that JSON with non-zero
+      `returncode` (no traceback-only failure).
+
+      - [ ] **Static sweep fails** → apply shared fix protocol → push → reset markers
+            → stay CODE_REVIEW → Step 5
+      - [ ] **`mode == in_session`** (Claude host, session model opus) → run
+            `/code-review high --fix` in-session (no path args)
+      - [ ] **`mode == chain`** (any other host or non-opus session) → helper
+            already ran the headless review; read `returncode`,
+            `served_command`, and `dirty_tree` from JSON
+      - [ ] **failed review** (`returncode != 0`, or chain with null
+            `served_command`) → do not set `code_review_clean_at` → stay
+            CODE_REVIEW → Step 5
+      - [ ] **fixes applied** (`dirty_tree` true / working tree dirty) →
+            commit + push via shared fix protocol → reset markers → stay
+            CODE_REVIEW → Step 5
+      - [ ] **clean** (successful serve: `returncode == 0`, chain
+            `served_command` non-null when chain, and `dirty_tree` false) →
+            zero unresolved threads (else fix + resolve) →
+            `code_review_clean_at = current_head` → `phase = BUGTEAM` → Step 6
+
+- [ ] **Step 6: BUGTEAM — run, decide, fix, reply, resolve**
+      See: [`per-tick.md` § Step 2 BUGTEAM](per-tick.md);
+      [`../../bugteam/SKILL.md`](../../bugteam/SKILL.md).
+      Pre-condition: `code_review_clean_at == current_head`.
+      Mandatory: `Skill({skill: "bugteam", args: "<PR URL>"})` this tick
+      (enforcer-blocked otherwise; `qbug` is not a substitute). Scope: FULL
+      `origin/main...HEAD` diff. Re-resolve HEAD after bugteam.
+
+      - [ ] **bugteam pushed** → verify threads replied + resolved → reset markers
+            → `phase = CODE_REVIEW` → 360s wakeup → Step 5
+      - [ ] **converged, no push** → zero unresolved threads →
+            `bugteam_clean_at = current_head` → `phase = BUGBOT` → Step 4
+      - [ ] **findings without committed fixes** → apply shared fix protocol → push →
+            reset markers → `phase = CODE_REVIEW` → Step 5
+
+- [ ] **Step 7: Convergence gates**
+      Full procedure: [`convergence-gates.md`](convergence-gates.md).
+
+      Pre-condition: Step 6 converged AND (`bugbot_clean_at == current_head` OR
+      `bugbot_down`). The terminal Bugbot gate (Step 4) sets that state just
+      before these gates run. Count unresolved threads before each gate.
+      Every gate records evidence; gate (f) cites evidence from (a)–(e).
+
+      - [ ] **(a) Copilot findings** — fetch Copilot on `current_head`; dirty → fix + return to Step 5; clean → stamp `copilot_clean_at`; absent → continue; when `copilot_down`, skip
+      - [ ] **(b) Claude reviewer** — fetch Claude on `current_head`; dirty → fix + return to Step 5; clean or absent → continue
+      - [ ] **(c) Mergeability** — `mergeable_state == "clean"` and `mergeable == true`; dirty → rebase + return to Step 1; blocked/behind/unknown/unstable → hard blocker
+      - [ ] **(d) Post-convergence Copilot request** — request Copilot when not pending and not `copilot_down`; enter `COPILOT_WAIT` (Step 7a); when `copilot_down`, skip to (e)
+      - [ ] **(e) Thread-resolution** — zero unresolved threads across the PR; else sweep + fix/resolve
+      - [ ] **(f) Mark ready** — run `check_convergence.py`; exit 0 → `update_pull_request(draft=false)` → Step 8; exit 1 → fix path; exit 2 → retry/stop
+
+- [ ] **Step 7a: COPILOT_WAIT — fetch Copilot, decide**
+      See: [`per-tick.md` § Step 2 COPILOT_WAIT](per-tick.md).
+      Skipped entirely when `copilot_down` (gate (d) never enters this phase).
+
+      - [ ] **clean** → `copilot_clean_at = current_head` → Step 7 (re-validate (b), (c), (e), (f))
+      - [ ] **dirty** → apply shared fix protocol
+            ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md);
+            skill deltas in [`fix-protocol.md`](fix-protocol.md))
+            → push → reset markers → `phase = CODE_REVIEW` → Step 5
+      - [ ] **no review yet** → increment `copilot_wait_count` → ≥ 3 hard-blocks;
+            else 360s wakeup → Step 7a next tick
+
+- [ ] **Step 8: Clean working tree**
+      `pr-loop-lifecycle` Close (`../../pr-loop-lifecycle/SKILL.md`).
+      See: [`../../pr-loop-lifecycle/reference/teardown-publish-permissions.md` § Clean working tree](../../pr-loop-lifecycle/reference/teardown-publish-permissions.md)
+
+- [ ] **Step 9: Rewrite PR description**
+      `pr-loop-lifecycle` Close.
+      See: [`../../pr-loop-lifecycle/reference/teardown-publish-permissions.md` § Publish the final PR description](../../pr-loop-lifecycle/reference/teardown-publish-permissions.md)
+
+- [ ] **Step 10: Revoke project permissions (always)**
+      `pr-loop-lifecycle` Close (`../../pr-loop-lifecycle/SKILL.md` § Close).
+
+- [ ] **Step 11: Print final report**
+      Print this block verbatim — no paraphrase, no extra commentary:
+      ```
+      /pr-converge exit: converged
+      Loops: <N>
+      Final commit: <SHA>
+      ```

package/skills/pr-converge/test_portable_pacer_gate.py

@@ -0,0 +1,67 @@
+"""Contract checks: pr-converge selects a portable pacer when ScheduleWakeup 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"
+PER_TICK_MARKDOWN_PATH = SKILL_ROOT / "reference" / "per-tick.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_SCHEDULE_WAKEUP_TOKEN = "pacer=schedule_wakeup"
+ABORT_ONLY_PHRASE = "pr-converge requires ScheduleWakeup; aborting"
+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_schedule_wakeup() -> 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_SCHEDULE_WAKEUP_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_per_tick_documents_both_pacers() -> None:
+    per_tick_text = PER_TICK_MARKDOWN_PATH.read_text(encoding="utf-8")
+    assert "portable" in per_tick_text
+    assert "schedule_wakeup" in per_tick_text or "ScheduleWakeup" in per_tick_text
+    assert PORTABLE_DRIVER_DOC in per_tick_text
+    assert "pacer=portable" in per_tick_text
+    assert "Do **not** call `ScheduleWakeup`" in per_tick_text or (
+        "Do not call `ScheduleWakeup`" in per_tick_text
+    )
+
+
+def test_portable_driver_protocol_exists() -> None:
+    assert PORTABLE_DRIVER_PATH.is_file()
+    portable_text = PORTABLE_DRIVER_PATH.read_text(encoding="utf-8")
+    assert "check_convergence.py" in portable_text
+    assert "invoke_code_review.py" in portable_text
+    assert "resolve_worker_spawn.py" in portable_text
+    assert "build_converge_task_list.py" in portable_text
+    assert "all_runnable_reviews_clean_same_head" in portable_text
+    assert "portable_converge_driver.py" in portable_text
+    assert "Never abort solely because" in portable_text

package/skills/pr-converge/test_step5_host_branch.py

@@ -11,7 +11,7 @@ from pathlib import Path
 
 
 SKILL_ROOT = Path(__file__).resolve().parent
-SKILL_MARKDOWN_PATH = SKILL_ROOT / "SKILL.md"
+PROGRESS_CHECKLIST_MARKDOWN_PATH = SKILL_ROOT / "reference" / "progress-checklist.md"
 PER_TICK_MARKDOWN_PATH = SKILL_ROOT / "reference" / "per-tick.md"
 
 HELPER_SCRIPT_NAME = "invoke_code_review.py"
@@ -45,10 +45,10 @@ def _code_review_section(per_tick_text: str) -> str:
     return per_tick_text[section_start:section_end]
 
 
-def _step_five_checklist(skill_text: str) -> str:
-    step_start = skill_text.index("**Step 5: CODE-REVIEW")
-    step_end = skill_text.index("**Step 6: BUGTEAM", step_start)
-    return skill_text[step_start:step_end]
+def _step_five_checklist(progress_checklist_text: str) -> str:
+    step_start = progress_checklist_text.index("**Step 5: CODE-REVIEW")
+    step_end = progress_checklist_text.index("**Step 6: BUGTEAM", step_start)
+    return progress_checklist_text[step_start:step_end]
 
 
 def test_per_tick_code_review_names_helper_and_mode_inputs() -> None:
@@ -75,7 +75,9 @@ def test_per_tick_code_review_names_helper_and_mode_inputs() -> None:
 
 
 def test_skill_step_five_checklist_names_helper_and_mode_inputs() -> None:
-    step_five_checklist = _step_five_checklist(_read_markdown(SKILL_MARKDOWN_PATH))
+    step_five_checklist = _step_five_checklist(
+        _read_markdown(PROGRESS_CHECKLIST_MARKDOWN_PATH)
+    )
     assert HELPER_SCRIPT_NAME in step_five_checklist
     assert HOST_PROFILE_PHRASE in step_five_checklist
     assert SESSION_MODEL_PHRASE in step_five_checklist

package/skills/pr-converge/workflows/schedule-wakeup-loop.md

@@ -1,8 +1,10 @@
 # ScheduleWakeup loop pacing (pr-converge)
 
-Load this document for converge **loop pacing**. The pre-flight in `SKILL.md`
-guarantees `ScheduleWakeup` is available before any tick runs. Shared bugbot
-/ bugteam / Fix protocol steps stay in the main `SKILL.md`.
+Load this document when pre-flight selects `pacer=schedule_wakeup`. When
+`pacer=portable`, use
+[`../../_shared/pr-loop/portable-driver.md`](../../_shared/pr-loop/portable-driver.md)
+instead. Shared bugbot / bugteam / Fix protocol steps stay in the main
+`SKILL.md`.
 
 ## Calling ScheduleWakeup
 

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Runs any PR-loop skill in a Claude Code session whose gh CLI cannot act on the PR. 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