claude-dev-env 2.1.0 → 2.2.1

package/skills/_shared/pr-loop/scripts/test_select_converge_pacer.py

@@ -0,0 +1,207 @@
+"""Tests for select_converge_pacer — host tool surface → pacer mapping."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+import select_converge_pacer as pacer_module  # noqa: E402
+from skills_pr_loop_constants.pacer_constants import (  # noqa: E402
+    CLI_HAS_SCHEDULE_WAKEUP_FLAG,
+    CLI_HAS_WORKFLOW_FLAG,
+    CLI_SKILL_FLAG,
+    ENTRY_SKILL_AUTOCONVERGE,
+    ENTRY_SKILL_PR_CONVERGE,
+    EXIT_SUCCESS,
+    EXIT_USAGE_ERROR,
+    PACER_PORTABLE,
+    PACER_SCHEDULE_WAKEUP,
+    PACER_WORKFLOW,
+    RESULT_KEY_ENTRY_SKILL,
+    RESULT_KEY_HAS_SCHEDULE_WAKEUP,
+    RESULT_KEY_HAS_WORKFLOW,
+    RESULT_KEY_PACER,
+)
+
+SCRIPT_PATH = _SCRIPTS_DIR / "select_converge_pacer.py"
+
+
+def test_autoconverge_with_workflow_selects_workflow() -> None:
+    selection = pacer_module.select_converge_pacer(
+        entry_skill=ENTRY_SKILL_AUTOCONVERGE,
+        has_workflow=True,
+        has_schedule_wakeup=False,
+    )
+    assert selection.pacer == PACER_WORKFLOW
+    assert selection.entry_skill == ENTRY_SKILL_AUTOCONVERGE
+
+
+def test_autoconverge_without_workflow_selects_portable() -> None:
+    selection = pacer_module.select_converge_pacer(
+        entry_skill=ENTRY_SKILL_AUTOCONVERGE,
+        has_workflow=False,
+        has_schedule_wakeup=True,
+    )
+    assert selection.pacer == PACER_PORTABLE
+
+
+def test_pr_converge_with_schedule_wakeup_selects_schedule_wakeup() -> None:
+    selection = pacer_module.select_converge_pacer(
+        entry_skill=ENTRY_SKILL_PR_CONVERGE,
+        has_workflow=False,
+        has_schedule_wakeup=True,
+    )
+    assert selection.pacer == PACER_SCHEDULE_WAKEUP
+    assert selection.entry_skill == ENTRY_SKILL_PR_CONVERGE
+
+
+def test_pr_converge_without_schedule_wakeup_selects_portable() -> None:
+    selection = pacer_module.select_converge_pacer(
+        entry_skill=ENTRY_SKILL_PR_CONVERGE,
+        has_workflow=True,
+        has_schedule_wakeup=False,
+    )
+    assert selection.pacer == PACER_PORTABLE
+
+
+def test_third_party_surface_selects_portable_for_both_entries() -> None:
+    for each_skill in (ENTRY_SKILL_AUTOCONVERGE, ENTRY_SKILL_PR_CONVERGE):
+        selection = pacer_module.select_converge_pacer(
+            entry_skill=each_skill,
+            has_workflow=False,
+            has_schedule_wakeup=False,
+        )
+        assert selection.pacer == PACER_PORTABLE, each_skill
+
+
+def test_unknown_entry_skill_raises() -> None:
+    with pytest.raises(ValueError, match="entry skill must be one of"):
+        pacer_module.select_converge_pacer(
+            entry_skill="bugteam",
+            has_workflow=False,
+            has_schedule_wakeup=False,
+        )
+
+
+def test_parse_bool_flag_accepts_common_tokens() -> None:
+    assert pacer_module.parse_bool_flag("1") is True
+    assert pacer_module.parse_bool_flag("true") is True
+    assert pacer_module.parse_bool_flag("YES") is True
+    assert pacer_module.parse_bool_flag("0") is False
+    assert pacer_module.parse_bool_flag("false") is False
+    assert pacer_module.parse_bool_flag("OFF") is False
+
+
+def test_parse_bool_flag_rejects_unknown_token() -> None:
+    with pytest.raises(ValueError, match="boolean token"):
+        pacer_module.parse_bool_flag("maybe")
+
+
+def test_selection_as_json_dict_uses_stable_keys() -> None:
+    selection = pacer_module.select_converge_pacer(
+        entry_skill=ENTRY_SKILL_PR_CONVERGE,
+        has_workflow=False,
+        has_schedule_wakeup=False,
+    )
+    payload = pacer_module.selection_as_json_dict(selection)
+    assert payload[RESULT_KEY_PACER] == PACER_PORTABLE
+    assert payload[RESULT_KEY_ENTRY_SKILL] == ENTRY_SKILL_PR_CONVERGE
+    assert payload[RESULT_KEY_HAS_WORKFLOW] is False
+    assert payload[RESULT_KEY_HAS_SCHEDULE_WAKEUP] is False
+
+
+def test_cli_prints_json_and_exits_zero() -> None:
+    completed = subprocess.run(
+        [
+            sys.executable,
+            str(SCRIPT_PATH),
+            "--skill",
+            ENTRY_SKILL_AUTOCONVERGE,
+            "--has-workflow",
+            "0",
+            "--has-schedule-wakeup",
+            "0",
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    assert completed.returncode == EXIT_SUCCESS, completed.stderr
+    payload = json.loads(completed.stdout)
+    assert payload[RESULT_KEY_PACER] == PACER_PORTABLE
+    assert payload[RESULT_KEY_ENTRY_SKILL] == ENTRY_SKILL_AUTOCONVERGE
+
+
+def test_cli_rejects_bad_bool_with_usage_exit() -> None:
+    completed = subprocess.run(
+        [
+            sys.executable,
+            str(SCRIPT_PATH),
+            "--skill",
+            ENTRY_SKILL_PR_CONVERGE,
+            "--has-workflow",
+            "nope",
+            "--has-schedule-wakeup",
+            "0",
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    assert completed.returncode == EXIT_USAGE_ERROR
+    assert "boolean token" in completed.stderr
+
+
+def test_main_returns_usage_error_on_value_error(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def raise_value_error(**_kwargs: object) -> object:
+        raise ValueError("entry skill must be one of")
+
+    monkeypatch.setattr(
+        pacer_module, "select_converge_pacer", raise_value_error
+    )
+    exit_code = pacer_module.main(
+        [
+            "--skill",
+            ENTRY_SKILL_PR_CONVERGE,
+            "--has-workflow",
+            "0",
+            "--has-schedule-wakeup",
+            "0",
+        ]
+    )
+    assert exit_code == EXIT_USAGE_ERROR
+
+
+def test_build_argument_parser_requires_skill_and_host_flags() -> None:
+    parser = pacer_module.build_argument_parser()
+    all_option_strings = {
+        each_option
+        for each_action in parser._actions
+        for each_option in each_action.option_strings
+    }
+    assert CLI_SKILL_FLAG in all_option_strings
+    assert CLI_HAS_WORKFLOW_FLAG in all_option_strings
+    assert CLI_HAS_SCHEDULE_WAKEUP_FLAG in all_option_strings
+    parsed_namespace = parser.parse_args(
+        [
+            CLI_SKILL_FLAG,
+            ENTRY_SKILL_AUTOCONVERGE,
+            CLI_HAS_WORKFLOW_FLAG,
+            "1",
+            CLI_HAS_SCHEDULE_WAKEUP_FLAG,
+            "0",
+        ]
+    )
+    assert parsed_namespace.skill == ENTRY_SKILL_AUTOCONVERGE
+    assert parsed_namespace.has_workflow == "1"
+    assert parsed_namespace.has_schedule_wakeup == "0"

package/skills/autoconverge/CLAUDE.md

@@ -2,7 +2,7 @@
 
 **Trigger:** `/autoconverge`, "autoconverge this PR", "converge this PR in one run", "run the converge workflow", "drive the PR to ready autonomously".
 
-Drives one draft PR to convergence in a single autonomous workflow run. Each round runs a deterministic static sweep first, then a code-review pass, a bug-audit (with its adversarial second pass), and a self-review parity pass in parallel on the same HEAD, deduplicates findings, applies every fix in one commit, and re-verifies. Once the internal lenses are clean, Cursor Bugbot, Copilot, and Codex run as terminal confirmation gates, and the run marks the PR ready on convergence. State lives in the workflow journal; no `ScheduleWakeup` ticks.
+Drives one draft PR to convergence in one autonomous run. On `pacer=workflow`, each round runs a deterministic static sweep first, then a code-review pass, a bug-audit (with its adversarial second pass), and a self-review parity pass in parallel on the same HEAD, deduplicates findings, applies every fix in one commit, and re-verifies; state lives in the workflow journal. On `pacer=portable`, the continuous driver in `_shared/pr-loop/portable-driver.md` runs the shared pr-converge phase machine with the same helpers and `check_convergence.py` ready definition. Once the internal passes are clean, Cursor Bugbot, Copilot, and Codex run as terminal confirmation gates, and the run marks the PR ready on convergence.
 
 ## Subdirectories
 
@@ -15,7 +15,7 @@ Drives one draft PR to convergence in a single autonomous workflow run. Each rou
 
 | File | Role |
 |---|---|
-| `SKILL.md` | Full entry-point protocol: pre-flight steps, worktree setup, `Workflow` call, budget-aware round boundaries, teardown, and the per-round convergence loop summary. |
+| `SKILL.md` | Full entry-point protocol: pacer selection, pre-flight steps, worktree setup, Workflow or portable path, budget-aware boundaries, teardown, and the convergence loop summary. |
 | `workflow/converge.mjs` | Main convergence workflow. Runs a static sweep then the internal lenses each round, applies fixes, runs Bugbot, Copilot, and Codex as terminal gates, checks convergence, and marks the PR ready. |
 | `workflow/aggregate_runs.py` | Merges every autoconverge journal for a PR into one deduped journal. |
 | `workflow/convergence_summary.py` | Builds the convergence-summary agent prompt over the merged findings. |
@@ -31,4 +31,6 @@ Drives one draft PR to convergence in a single autonomous workflow run. Each rou
 
 ## Entry point
 
-Requires the `Workflow` tool. The `SKILL.md` body specifies the exact pre-flight sequence and `Workflow` call.
+Selects `workflow` or `portable` via `select_converge_pacer.py`. Missing
+`Workflow` selects portable and continues — it does not abort. The `SKILL.md`
+body specifies the pre-flight sequence and each pacer's run path.

package/skills/autoconverge/SKILL.md

@@ -1,48 +1,66 @@
 ---
 name: autoconverge
 description: >-
-  Drives one draft PR to convergence in one autonomous run: static sweep, then
-  code review, bug audit, and self-review on one HEAD, fixes in one commit, then
-  Bugbot, Copilot, and Codex as terminal gates before ready. Use when the user
-  says '/autoconverge', 'autoconverge this PR', 'converge this PR in one run',
-  'run the converge workflow', or 'drive the PR to ready autonomously'.
+  Drives one draft PR to convergence in one autonomous run with a host-selected
+  pacer. On workflow: three parallel lenses (code-review, bug-audit, self-review)
+  and one-commit fixes via converge.mjs. On portable: pr-converge continuous ticks
+  via portable-driver.md. Bugbot, Copilot, and Codex as terminal confirmation
+  gates before ready. Use when the user says '/autoconverge', 'autoconverge this
+  PR', 'converge this PR in one run', 'run the converge workflow', or 'drive the
+  PR to ready autonomously'.
 ---
 
 # Autoconverge
 
 One launch drives the whole loop to convergence. The `/autoconverge` skill
-resolves PR scope, enters a worktree, grants project permissions, then hands
-the loop to the **`converge.mjs` workflow**, which runs every round and every
-reviewer wait inside one background pass — no ticks, no `ScheduleWakeup`, no
-state file. State lives in the workflow's own variables; resume is handled by
-the workflow journal.
+scans the tool list, selects a **pacer** (Workflow or portable), then resolves
+PR scope, enters a worktree, grants project permissions, and drives the shared
+converge product to ready (or a named blocker).
 
-`pr-converge` paces the same four-reviewer loop across `ScheduleWakeup` ticks;
-autoconverge runs it as a deterministic workflow. The two skills share the same
-helper scripts and the same convergence gate.
+| Pacer | Host surface | How the loop runs |
+|---|---|---|
+| `workflow` | Tool list includes `Workflow` | `converge.mjs` background pass; state in the workflow journal |
+| `portable` | `Workflow` absent | Continuous in-session ticks per [`../_shared/pr-loop/portable-driver.md`](../_shared/pr-loop/portable-driver.md); same helpers and `check_convergence.py` ready definition |
+
+`pr-converge` selects `schedule_wakeup` or `portable` the same way. Both
+entry skills share the helper scripts and the convergence gate.
 
 ## Run scope: one PR or several
 
 Decide the scope from how many PRs the user named, then follow that path:
 
-1. **One PR** → the single-PR run described below (`workflow/converge.mjs`): one
-   worktree, one workflow launch, one teardown.
-2. **Several PRs** → the [Multiple PRs](reference/multi-pr.md) run
-   (`workflow/converge_multi.mjs`): one worktree per PR and a single workflow
-   launch that drives every PR's converge run in parallel, then one teardown per
-   PR.
+1. **One PR** → the single-PR run described below: one worktree, one pacer
+   launch (`converge.mjs` on `pacer=workflow`, portable continuous ticks on
+   `pacer=portable`), one teardown.
+2. **Several PRs** → the [Multiple PRs](reference/multi-pr.md) run: on
+   `pacer=workflow`, `workflow/converge_multi.mjs` drives every PR in parallel;
+   on `pacer=portable`, run the portable driver once per PR (serial or host
+   fan-out), then one teardown per PR.
 
-The single-PR sections (Requirements, Pre-flight, Run the workflow, Teardown)
-each describe one converge run. The multi-PR reference reuses them once per PR
-and adds only what fanning out needs: a per-PR worktree and a per-PR teardown
-loop.
+The single-PR sections (Requirements, Pre-flight, Run the workflow or portable
+driver, Teardown) each describe one converge run. The multi-PR reference reuses
+them once per PR and adds only what fanning out needs: a per-PR worktree and a
+per-PR teardown loop.
 
 ## Requirements
 
-Scan the tool list at the top of this conversation for the literal string
-`Workflow`. If it is absent, report `autoconverge requires the Workflow tool;
-aborting` and stop. The workflow also needs the `gh` CLI authenticated for the
-PR's owner.
+Scan the tool list for `Workflow` and `ScheduleWakeup`, then select the pacer:
+
+```
+python "$HOME/.claude/skills/_shared/pr-loop/scripts/select_converge_pacer.py" \
+  --skill autoconverge \
+  --has-workflow <0|1> \
+  --has-schedule-wakeup <0|1>
+```
+
+- `pacer=workflow` — continue with Pre-flight and **Run the workflow** below.
+- `pacer=portable` — continue with Pre-flight (portable worktree rules when
+  `EnterWorktree` is absent), then the continuous driver in
+  [`../_shared/pr-loop/portable-driver.md`](../_shared/pr-loop/portable-driver.md).
+  **Do not abort** because the Workflow tool is missing.
+
+Transport still needs authenticated GitHub access for the PR's owner (`gh` or
+`pr-loop-cloud-transport`).
 
 ## Review-lens boundary
 
@@ -65,11 +83,30 @@ orchestrating session's own steps, and the script's agent-prompt text carries
 
 ## Pre-flight (main session)
 
-1. **Enter a worktree.** Call `EnterWorktree` with no arguments before any
-   `gh`, `git`, file read, or edit. `gh`/`git` Bash calls do not auto-isolate,
-   so this is mandatory. If it fails, report and stop. A bare `EnterWorktree`
-   branches from `origin/main`; step 2 positions the worktree on the PR's head
-   ref, which the workflow needs.
+0. **Build the task list (step 1 of every run).** After Copilot quota / down
+   flags and Codex required/down are known, run only:
+
+   ```
+   python "$HOME/.claude/skills/_shared/pr-loop/scripts/build_converge_task_list.py" \
+     --bugbot-down <0|1> --copilot-down <0|1> \
+     --codex-down <0|1> --codex-required <0|1>
+   ```
+
+   Register every `tasks[]` entry on the session task list. **Final task** is
+   always `all_runnable_reviews_clean_same_head` (`done_when` in the JSON).
+   The run is complete only when that final task is completed — all runnable
+   code reviews CLEAN on the same HEAD. Do not invent tasks in prose. On
+   `pacer=portable`, `open-run` returns the same list; still register it as
+   step 1 before driving reviews.
+
+1. **Enter a worktree.** When `EnterWorktree` is in the tool list, call it with
+   no arguments before any `gh`, `git`, file read, or edit. `gh`/`git` Bash
+   calls do not auto-isolate, so isolation is mandatory. If it fails, report
+   and stop. A bare `EnterWorktree` branches from `origin/main`; step 2
+   positions the worktree on the PR's head ref. When `EnterWorktree` is
+   absent, isolate with git worktree machinery per
+   [`../_shared/pr-loop/portable-driver.md`](../_shared/pr-loop/portable-driver.md)
+   § Isolation and worktree, then continue step 2.
 
 2. **Resolve PR scope.** When the user passed a PR URL or number, parse owner,
    repo, and number from it. Otherwise read the current branch's PR:
@@ -78,14 +115,15 @@ orchestrating session's own steps, and the script's agent-prompt text carries
    ready, mark it draft first (`gh pr ready <n> --repo <o>/<r> --undo`) so the
    loop owns the ready transition.
 
-   **Position the worktree on the PR branch.** The workflow reviews
+   **Position the worktree on the PR branch.** The run reviews
    `git diff origin/main...HEAD` against this worktree's local `HEAD` and pushes
    each fix to the PR branch, so the worktree sits on the PR's head ref at the PR
-   HEAD before the workflow launches. A worktree fresh off `origin/main` has
+   HEAD before the loop starts. A worktree fresh off `origin/main` has
    `HEAD == origin/main`, shows an empty diff, and reports a false convergence
    with zero findings. When a local worktree already tracks the PR branch, enter
-   that one by passing its path to `EnterWorktree`; otherwise put the entered
-   worktree on the branch with `gh pr checkout <number> --repo <owner>/<repo>`
+   that one (pass its path to `EnterWorktree` when that tool exists; otherwise
+   `cd` into it). Otherwise put the checkout on the branch with
+   `gh pr checkout <number> --repo <owner>/<repo>`
    (or `git fetch origin <headRefName>` then `git switch <headRefName>`). Confirm
    before launching: `git rev-parse --abbrev-ref HEAD` equals the PR's head ref
    and local `HEAD` equals the PR head SHA.
@@ -93,27 +131,32 @@ orchestrating session's own steps, and the script's agent-prompt text carries
 3. **Verify the worktree is the PR's repo (strict pre-flight).** Run
    `python "$HOME/.claude/skills/_shared/pr-loop/scripts/preflight_worktree.py" --owner <owner> --repo <repo> --mode strict`.
    It confirms the working directory is a checkout of the PR's own repo and
-   that `git worktree` machinery is healthy, so `EnterWorktree` can create and
-   enter the branch worktree. A non-zero exit prints a `PREFLIGHT_OUTCOME` line
-   and an `ABORT` line: report that line and stop. Autoconverge runs inside the
-   PR's own repo, so a working directory rooted in a different repo (for
-   example, `claude-dev-env` while the PR lives in `llm-settings`) or in no
-   git checkout at all cannot continue.
+   that `git worktree` machinery is healthy. A non-zero exit prints a
+   `PREFLIGHT_OUTCOME` line and an `ABORT` line: report that line and stop.
+   Autoconverge runs inside the PR's own repo, so a working directory rooted in
+   a different repo (for example, `claude-dev-env` while the PR lives in
+   `llm-settings`) or in no git checkout at all cannot continue.
 
 4. **Grant project permissions.** Apply the `pr-loop-lifecycle` skill's Open
    section (`../pr-loop-lifecycle/SKILL.md`) — the grant command
    (`grant_project_claude_permissions.py`) and the auto-mode `AskUserQuestion`
    escalation for a blocked grant both live there.
 
-5. **Copilot quota pre-check.** Before the `Workflow` call, apply the
+5. **Copilot quota pre-check.** Before the pacer starts the loop, apply the
    `reviewer-gates` skill's Copilot quota gate (`../reviewer-gates/SKILL.md`)
-   once. Exit 0 maps to `copilotDisabled: false` in the Workflow call; any
-   non-zero exit maps to `copilotDisabled: true`, and the workflow then skips
-   the Copilot gate with no agent spawned.
+   once. Exit 0 maps to `copilotDisabled: false` / `copilot_down=false`; any
+   non-zero exit maps to `copilotDisabled: true` / `copilot_down=true`, and the
+   run skips the Copilot gate with no agent spawned.
+
+6. **Branch on pacer.** When `pacer=portable`, follow
+   [`../_shared/pr-loop/portable-driver.md`](../_shared/pr-loop/portable-driver.md)
+   § Continuous tick loop and § Autoconverge entry on portable pacer, then
+   skip **Run the workflow** (no Workflow tool). When `pacer=workflow`,
+   continue with **Run the workflow**.
 
 ## Run the workflow
 
-Call the `Workflow` tool against the colocated script:
+(`pacer=workflow` only.) Call the `Workflow` tool against the colocated script:
 
 ```
 Workflow({
@@ -160,26 +203,89 @@ skips a reviewer that is down or out of quota without re-probing. This list is t
 
 ## Copilot findings — tier, verify, then route
 
-The Copilot gate tiers each finding (self-healing vs code-concern), verifies
-each code concern with an executed check against the flagged HEAD, and returns a
-confirmed / refuted / inconclusive verdict — full semantics and the `userReview`
-return contract in
-[`reference/copilot-findings.md`](reference/copilot-findings.md). Only
-inconclusive findings return `blocker: "user-review"`; the orchestrating session
-handles that hold in Teardown via 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.
+
+The wait for a human belongs to the orchestrating session. On a
+`blocker: "user-review"` return, run the
+[`copilot-finding-triage`](../copilot-finding-triage/SKILL.md) skill for the ntfy
+page only (the per-finding summary and evidence note plus the `reviewUrl`
+Copilot review link), then hold for the user's response by pacer. On
+`pacer=portable`, override triage's hold step — ntfy plus the portable hold
+below; do not follow triage's `ScheduleWakeup` / `send_later` path.
+
+- **`pacer=workflow`** — triage hold: 45-minute `ScheduleWakeup` (or
+  `send_later` when that is the host arm).
+- **`pacer=portable`** — portable hold only: in-session poll or handoff per
+  [`../_shared/pr-loop/portable-driver.md`](../_shared/pr-loop/portable-driver.md);
+  never `ScheduleWakeup` or `send_later`.
+
+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.
 
 ## Budget stop
 
-`converge.mjs` paces itself against the workflow `budget` API and stops at a
-round boundary when a full round does not fit —
-[`reference/stop-conditions.md`](reference/stop-conditions.md) § Budget stop
-gives the rule. On a `blocker: "budget"` return, write the durable handoff with
-the run id and the `Workflow({scriptPath, resumeFromRunId})` resume command
-before stopping, so a fresh session resumes the paced run without the stopped
-session's transcript.
+Branch the stop and resume path on the selected pacer. Full rule:
+[`reference/stop-conditions.md`](reference/stop-conditions.md) § Budget stop.
+
+- **`pacer=workflow`** — `converge.mjs` paces against the workflow `budget` API
+  and stops at a round boundary when a full round does not fit. On a
+  `blocker: "budget"` return, write the durable handoff with the run id and the
+  `Workflow({scriptPath, resumeFromRunId})` resume command before stopping, so a
+  fresh session resumes the paced run without the stopped session's transcript.
+- **`pacer=portable`** — stop at a tick boundary when the session cannot cover a
+  full clean tick; write the durable handoff and resume with
+  `/autoconverge <PR URL>` (see
+  [`../_shared/pr-loop/portable-driver.md`](../_shared/pr-loop/portable-driver.md)).
+  Do not instruct a Workflow resume on the portable path.
+
+## Teardown
+
+### `pacer=portable`
+
+Skip Workflow-only report steps that need a workflow run id (journal merge,
+HTML closing report, Artifact publish). Run `pr-loop-lifecycle` Close
+(description rewrite when converged, working-tree clean, permission revoke)
+and print the final report block using tick/`check_convergence` outcomes.
+User-review holds use the portable in-session poll (or handoff) from
+[`../_shared/pr-loop/portable-driver.md`](../_shared/pr-loop/portable-driver.md)
+— not `ScheduleWakeup`. Resume command: `/autoconverge <PR URL>`.
 
-## Teardown (on workflow completion)
+### `pacer=workflow` (on workflow completion)
 
 Teardown runs as an ordered checkpoint list. After each checkpoint finishes,
 re-write the durable handoff with `--phase teardown`, the run id, and the
@@ -201,15 +307,18 @@ On teardown entry, when `~/.claude/runtime/pr-loop/bugteam-pr-<N>/handoff.json`
 exists, read its `completed_steps` and skip any checkpoint the list already
 names, so a resumed run performs only the checkpoints left.
 
-On a `blocker: "user-review"` return, the workflow held one or more code-concern
-findings that stayed inconclusive after the executed-check verification stage.
-Run the [`copilot-finding-triage`](../copilot-finding-triage/SKILL.md) gate before
+On a `blocker: "user-review"` return under `pacer=workflow`, the workflow held
+one or more code-concern findings that stayed inconclusive after the
+executed-check verification stage. Run the
+[`copilot-finding-triage`](../copilot-finding-triage/SKILL.md) gate before
 teardown: send the ntfy alert with the per-finding summary and evidence note and
-the `userReview.reviewUrl` link, then hold with a 45-minute `ScheduleWakeup`. Act
-on the user's direction when it arrives inside the window; when the window closes
-with no response, fall through to normal teardown and report the
-`userReview.findings` un-reviewed. The PR stays a draft in this path — the
-workflow marked nothing ready.
+the `userReview.reviewUrl` link, then hold with a 45-minute `ScheduleWakeup` (or
+`send_later` when that is the host arm). Act on the user's direction when it
+arrives inside the window; when the window closes with no response, fall through
+to normal teardown and report the `userReview.findings` un-reviewed. The PR
+stays a draft in this path — the workflow marked nothing ready. Under
+`pacer=portable`, use the portable teardown hold above (ntfy plus in-session
+poll or handoff; never `ScheduleWakeup`).
 
 Before the checkpoints, when the workflow returned a non-null `copilotNote`
 (the Copilot gate was bypassed), query the PR's reviews once more for a
@@ -277,8 +386,10 @@ When the user names several PRs, run the multi-PR path in
 [`reference/multi-pr.md`](reference/multi-pr.md): one worktree per PR
 (`git worktree add` on each head ref, strict pre-flight per worktree, one
 permission grant per repository, one Copilot quota check for the whole run),
-then a single `workflow/converge_multi.mjs` launch with one entry per PR, then
-the single-PR teardown once per `results` entry and a one-line-per-PR summary.
+then launch by pacer — `pacer=workflow`: one `workflow/converge_multi.mjs`
+call with one entry per PR; `pacer=portable`: portable driver once per PR
+(serial or host fan-out) — then single-PR teardown once per PR and a
+one-line-per-PR summary.
 
 ## Self-closing loop: converge the deferred PRs
 
@@ -294,6 +405,7 @@ also carries the Conventional-Commit title rule each hardening PR must meet.
 ## Folder map
 
 - `SKILL.md` — this hub.
+- [`../_shared/pr-loop/portable-driver.md`](../_shared/pr-loop/portable-driver.md) — portable pacer when `Workflow` is absent.
 - `workflow/converge.mjs` — the convergence workflow script.
 - `workflow/converge_multi.mjs` — the multi-PR fan-out driver: one `converge.mjs` child run per PR in parallel, each pinned to its PR worktree via `repoPath`.
 - `workflow/aggregate_runs.py` — merges every autoconverge journal for a PR into one journal and returns its deduped findings, fix summaries, round count, and final SHA.
@@ -301,7 +413,6 @@ also carries the Conventional-Commit title rule each hardening PR must meet.
 - `workflow/render_report.py` — builds the closing convergence insights HTML report, taking the summary from `--summary-file`.
 - `workflow/autoconverge_report_constants/` — named constants for the report builder and the summary prompt.
 - `reference/convergence.md` — the whole loop: reuse pass, round shape, terminal gates, model tiers, ready definition.
-- `reference/copilot-findings.md` — the Copilot gate tiering, per-finding verification, and the `userReview` return contract.
 - `reference/stop-conditions.md` — every way the run ends short of ready, including the budget stop.
 - `reference/gotchas.md` — hard-won failure lessons.
 - `reference/closing-report.md` — the closing HTML report: 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