claude-dev-env 2.1.0 → 2.2.1

package/hooks/validators/test_run_all_validators_pretooluse.py

@@ -8,12 +8,19 @@ when that content violates a validator, rather than grading the whole branch.
 import json
 import subprocess
 import sys
+from collections import Counter
 from pathlib import Path
 from unittest.mock import patch
 
 import pytest
 
-from .run_all_validators import main, run_validators_entrypoint_subprocess
+from .run_all_validators import (
+    ValidatorResult,
+    _scope_new_and_preexisting,
+    _violation_line_number,
+    main,
+    run_validators_entrypoint_subprocess,
+)
 
 CLEAN_PYTHON_SOURCE = (
     "def add_two_numbers(first_number: int, second_number: int) -> int:\n"
@@ -26,7 +33,9 @@ VIOLATING_PYTHON_SOURCE = (
 
 
 def run_gate(payload: dict[str, object]) -> "subprocess.CompletedProcess[str]":
-    return run_validators_entrypoint_subprocess(["--pre-tool-use"], stdin_text=json.dumps(payload))
+    return run_validators_entrypoint_subprocess(
+        ["--pre-tool-use"], stdin_text=json.dumps(payload)
+    )
 
 
 class TestPreToolUseGate:
@@ -73,7 +82,9 @@ class TestPreToolUseGate:
         assert completed.returncode == 0, completed.stderr
         assert "deny" not in completed.stdout
 
-    def test_edit_validates_reconstructed_post_edit_content(self, tmp_path: Path) -> None:
+    def test_edit_validates_reconstructed_post_edit_content(
+        self, tmp_path: Path
+    ) -> None:
         target_file = tmp_path / "calculate.py"
         target_file.write_text(CLEAN_PYTHON_SOURCE, encoding="utf-8")
         completed = run_gate(
@@ -116,3 +127,212 @@ class TestCliModeRegression:
         captured = capsys.readouterr()
         assert exit_code == 1
         assert "PRE-PUSH VALIDATOR RESULTS" in captured.out
+
+
+def _over_long_function_source(function_name: str) -> str:
+    """Return a syntactically clean function whose only defect is exceeding 30 lines."""
+    body_lines = "".join("    running_total = running_total + 1\n" for _ in range(35))
+    return (
+        f"def {function_name}(running_total: int) -> int:\n"
+        f"{body_lines}"
+        "    return running_total\n"
+    )
+
+
+CLEAN_MARKER_FUNCTION = "def clean_marker() -> int:\n    return 1\n"
+CLEAN_MARKER_EDITED = (
+    "def clean_marker() -> int:\n    computed_value = 1\n    return computed_value\n"
+)
+MAGIC_VALUE_MARKER_FUNCTION = "def clean_marker() -> int:\n    return 199\n"
+PRE_EXISTING_VIOLATION_SOURCE = (
+    _over_long_function_source("over_long_function") + "\n" + CLEAN_MARKER_FUNCTION
+)
+MAGIC_VALUE_FUNCTION_SOURCE = "def compute_total() -> int:\n    return 199\n"
+RUFF_DIRTY_FUNCTION_SOURCE = (
+    "def compute_total() -> int:\n    unused_intermediate = 1\n    return 1\n"
+)
+
+
+class TestBaselineScopedGate:
+    def test_clean_edit_to_violating_file_is_allowed_with_warning(
+        self, tmp_path: Path
+    ) -> None:
+        target_file = tmp_path / "legacy_module.py"
+        target_file.write_text(PRE_EXISTING_VIOLATION_SOURCE, encoding="utf-8")
+        completed = run_gate(
+            {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "old_string": CLEAN_MARKER_FUNCTION,
+                    "new_string": CLEAN_MARKER_EDITED,
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' not in completed.stdout
+        assert "Code Quality" in completed.stderr
+
+    def test_edit_introducing_new_violation_denies_naming_only_the_new_one(
+        self, tmp_path: Path
+    ) -> None:
+        target_file = tmp_path / "legacy_module.py"
+        target_file.write_text(PRE_EXISTING_VIOLATION_SOURCE, encoding="utf-8")
+        completed = run_gate(
+            {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "old_string": CLEAN_MARKER_FUNCTION,
+                    "new_string": MAGIC_VALUE_MARKER_FUNCTION,
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' in completed.stdout
+        assert "Magic Values" in completed.stdout
+        assert "Code Quality" not in completed.stdout
+
+    def test_new_violation_in_clean_file_denies(self, tmp_path: Path) -> None:
+        target_file = tmp_path / "clean_module.py"
+        target_file.write_text(CLEAN_MARKER_FUNCTION, encoding="utf-8")
+        completed = run_gate(
+            {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "old_string": "    return 1\n",
+                    "new_string": "    return 199\n",
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' in completed.stdout
+        assert "Magic Values" in completed.stdout
+
+    def test_clean_edit_to_clean_file_is_allowed(self, tmp_path: Path) -> None:
+        target_file = tmp_path / "clean_module.py"
+        target_file.write_text(CLEAN_MARKER_FUNCTION, encoding="utf-8")
+        completed = run_gate(
+            {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "old_string": "    return 1\n",
+                    "new_string": "    computed_value = 1\n    return computed_value\n",
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert "deny" not in completed.stdout
+
+    def test_growing_a_function_with_existing_length_violation_is_allowed_with_warning(
+        self, tmp_path: Path
+    ) -> None:
+        target_file = tmp_path / "legacy_module.py"
+        target_file.write_text(
+            _over_long_function_source("over_long_function"), encoding="utf-8"
+        )
+        completed = run_gate(
+            {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "old_string": "    return running_total\n",
+                    "new_string": (
+                        "    running_total = running_total + 1\n"
+                        "    running_total = running_total + 1\n"
+                        "    return running_total\n"
+                    ),
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' not in completed.stdout
+        assert "Code Quality" in completed.stderr
+
+    def test_new_same_validator_violation_in_dirty_function_denies(
+        self, tmp_path: Path
+    ) -> None:
+        target_file = tmp_path / "legacy_module.py"
+        target_file.write_text(MAGIC_VALUE_FUNCTION_SOURCE, encoding="utf-8")
+        completed = run_gate(
+            {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "old_string": "    return 199\n",
+                    "new_string": "    threshold = 42\n    return 199 + threshold\n",
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' in completed.stdout
+        assert "Magic Values" in completed.stdout
+
+    def test_new_module_scope_ruff_violation_with_dirty_function_denies(
+        self, tmp_path: Path
+    ) -> None:
+        target_file = tmp_path / "legacy_module.py"
+        target_file.write_text(RUFF_DIRTY_FUNCTION_SOURCE, encoding="utf-8")
+        completed = run_gate(
+            {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "old_string": "def compute_total",
+                    "new_string": "import os\n\n\ndef compute_total",
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' in completed.stdout
+        assert "F401" in completed.stdout
+        assert "F841" not in completed.stdout
+
+
+class TestScopeNewAndPreexisting:
+    def test_failed_result_without_located_lines_is_treated_as_new(self) -> None:
+        summary_only_result = ValidatorResult(
+            name="Ruff", checks="37", passed=False, output="Found 1 error."
+        )
+
+        new_results, preexisting_results = _scope_new_and_preexisting(
+            [summary_only_result], "import os\n", Counter()
+        )
+
+        assert [each_result.name for each_result in new_results] == ["Ruff"]
+        assert preexisting_results == []
+
+
+class TestViolationLineNumber:
+    def test_ruff_line_col_prefix_returns_line_not_column(self) -> None:
+        ruff_shaped_line = "/pkg/legacy_module.py:37:5: F401 `os` imported but unused"
+
+        assert _violation_line_number(ruff_shaped_line) == 37
+
+    def test_windows_drive_prefix_returns_line(self) -> None:
+        windows_shaped_line = r"C:\repo\tmp\legacy_module.py:37:5: F401 unused import"
+
+        assert _violation_line_number(windows_shaped_line) == 37
+
+    def test_check_module_line_prefix_returns_line(self) -> None:
+        check_module_line = "/pkg/legacy_module.py:37: magic number 199"
+
+        assert _violation_line_number(check_module_line) == 37
+
+    def test_summary_line_without_location_returns_zero(self) -> None:
+        assert _violation_line_number("Found 3 errors.") == 0
+
+    def test_code_frame_line_quoting_colon_digits_returns_zero(self) -> None:
+        frame_line = '4 | message = "err:37: bad"'
+
+        assert _violation_line_number(frame_line) == 0
+
+    def test_code_frame_source_line_returns_zero(self) -> None:
+        assert _violation_line_number("17 | import os") == 0
+
+    def test_path_with_spaces_returns_line(self) -> None:
+        spaced_path_line = "/tmp/my dir/legacy module.py:37: magic number 199"
+
+        assert _violation_line_number(spaced_path_line) == 37

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.1.0",
+    "version": "2.2.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/CLAUDE.md

@@ -16,6 +16,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. A rule withou
 | `ask-user-question-required.md` | Every user-directed question goes through the `AskUserQuestion` tool — no plain-text questions |
 | `bdd.md` | BDD discovery-driven development workflow and Example Mapping reference |
 | `claude-md-orphan-file.md` | Every backticked bare filename in a per-directory `CLAUDE.md` table's first column names a file in that directory's subtree |
+| `cleanup-command-forms.md` | Never use bash `rm` to clean up; use the PowerShell `Remove-Item` and `git worktree remove --force` forms the `destructive_command_blocker` hook never prompts on, and carry the rule into every subagent prompt |
 | `cleanup-temp-files.md` | Remove temporary files created during a task when the task is complete |
 | `code-reviews.md` | Mandatory protocol for responding to GitHub PR review feedback |
 | `code-standards.md` | Pointer to `CODE_RULES.md` as the single source of truth |

package/rules/cleanup-command-forms.md

@@ -0,0 +1,23 @@
+# Cleanup Command Forms
+
+Never use bash `rm` in any form to clean up. The `destructive_command_blocker` hook watches every Bash-tool command and matches `rm -rf` (and the rest of the destructive patterns) as raw text. It allows an `rm` without a prompt only for a narrow set of shapes it can prove safe: an `rm` whose every target is an absolute path under the OS temp root, `/tmp`, `/temp`, or a worktrees directory — standalone, or in a chain whose other segments are plain reporting commands such as `echo` or `cat`; an `rm` run from an ephemeral working directory; and an `rm` whose every target sits inside `~/.claude`. It falls through to a permission prompt on anything outside that set: a `$`, `$(...)`, or backtick expansion whose value it cannot resolve, a target it cannot place in a safe directory, a glob basename, or a string-executing wrapper (`bash -c 'rm -rf …'`). In a background or auto-mode run no human can answer that prompt, so the call stalls.
+
+Remove files with these forms, which the hook never prompts on:
+
+- **Scratch and probe files:** the PowerShell tool — `Remove-Item -Recurse -Force -Confirm:$false <absolute path>`. The hook watches only the Bash tool, so a PowerShell removal never reaches it. A file left in the OS temp dir or `$CLAUDE_JOB_DIR/tmp` is ephemeral and needs no explicit removal.
+- **Worktrees:** `git worktree remove --force <path>`. This matches no destructive pattern.
+- **When bash `rm` is unavoidable:** one standalone `rm` command, an absolute literal path under the OS temp root or a worktrees directory, no chaining, no variables, no globs. The hook auto-allows this shape without a prompt.
+
+## Every subagent prompt carries the rule
+
+A prompt-delivered directive reaches only the agent that gets it. An agent that spawns its own workers — review lenses, fix agents, verifiers — copies this line into every subagent prompt it issues, so a grandchild cleaning up its own probe file uses an allowed form:
+
+> Never use bash rm in any form. Delete scratch/probe files with the PowerShell tool (Remove-Item -Recurse -Force -Confirm:$false <absolute path>), or leave them in the OS temp dir; remove worktrees only via git worktree remove --force.
+
+Prefer that a child leaves its scratch files in place for the parent to remove at teardown with `Remove-Item`.
+
+## Sibling rules
+
+- [`no-inline-destructive-literals`](no-inline-destructive-literals.md) — keep a destructive literal out of the Bash command string even when it rides only as data.
+- [`cleanup-temp-files`](cleanup-temp-files.md) — remove the scratch files a task created once the task is done.
+- [`windows-filesystem-safe`](windows-filesystem-safe.md) — the safe `rmtree` / `force_rmtree` patterns for read-only Windows files.

package/scripts/check.ps1

@@ -1,23 +1,25 @@
 #!/usr/bin/env pwsh
 <#
 .SYNOPSIS
-    One-shot quality gate for the hooks package — runs ruff, mypy, and the
+    One-shot quality gate — runs ruff, hooks mypy, pr-loop mypy, and the
     blocking pytest suite from a single entry point.
 
 .DESCRIPTION
     Resolves paths relative to $PSScriptRoot so the script works from any CWD
     and from both the worktree (packages/claude-dev-env/scripts/check.ps1)
     and the installed runtime (~/.claude/scripts/check.ps1, after install.mjs
-    propagates this file). Each tool runs sequentially; the first non-zero
-    exit code is preserved as the script's exit code so CI/pre-commit can
-    short-circuit on the first failure.
+    propagates this file). Tools: ruff over hooks/, mypy over hooks blocking
+    and validators, mypy-pr-loop over _shared/pr-loop/scripts production
+    modules, and optional pytest over the blocking enforcer suite. Each tool
+    runs sequentially; the first non-zero exit code is preserved as the
+    script's exit code so CI/pre-commit can short-circuit on the first failure.
 
 .PARAMETER SkipTests
     Skip the pytest run. Useful during local iteration when you want only the
     static-analysis gates.
 
 .PARAMETER SkipMypy
-    Skip the mypy run.
+    Skip both mypy runs (hooks mypy and mypy-pr-loop).
 
 .PARAMETER SkipRuff
     Skip the ruff run.
@@ -25,7 +27,7 @@
 .OUTPUTS
     Per-tool status lines on stdout. Final summary line:
         CHECK: OK
-        CHECK: FAILED tools=ruff,mypy,pytest
+        CHECK: FAILED tools=ruff,mypy,mypy-pr-loop,pytest
 #>
 [CmdletBinding()]
 param(
@@ -38,6 +40,7 @@ $ErrorActionPreference = 'Stop'
 
 $hooksRoot = Resolve-Path (Join-Path $PSScriptRoot '..' 'hooks')
 $blockingRoot = Join-Path $hooksRoot 'blocking'
+$prLoopScriptsRoot = Resolve-Path (Join-Path $PSScriptRoot '..' '_shared' 'pr-loop' 'scripts')
 
 $failedTools = @()
 $firstNonZeroExitCode = 0
@@ -82,6 +85,29 @@ if (-not $SkipMypy) {
             Pop-Location
         }
     }
+
+    Invoke-Tool -Label 'mypy-pr-loop' -Action {
+        Push-Location $prLoopScriptsRoot
+        try {
+            mypy --config-file (Join-Path $prLoopScriptsRoot 'pyproject.toml') `
+                _claude_permissions_common.py `
+                code_rules_gate.py `
+                copilot_quota.py `
+                fix_hookspath.py `
+                grant_project_claude_permissions.py `
+                post_audit_thread.py `
+                preflight_self_heal.py `
+                preflight.py `
+                reviewer_availability.py `
+                reviews_disabled.py `
+                revoke_project_claude_permissions.py `
+                terminology_sweep.py `
+                code_rules_gate_parts `
+                pr_loop_shared_constants
+        } finally {
+            Pop-Location
+        }
+    }
 }
 
 if (-not $SkipTests) {

package/skills/_shared/pr-loop/CLAUDE.md

@@ -1,28 +1,33 @@
 # pr-loop
 
-Shared infrastructure for the PR audit-fix loop used by `bugteam` and `pr-converge`. Provides the XML prompt template, Python runtime scripts, and named constants that both skills invoke during each loop tick.
+Shared infrastructure for the PR audit-fix loop used by `bugteam`,
+`pr-converge`, and `autoconverge`. Provides the XML prompt template, Python
+runtime scripts, the portable converge driver protocol, and named constants
+those skills invoke during each loop tick.
 
 ## Subdirectories
 
 | Directory | Role |
 |---|---|
 | `prompts/` | XML agent prompt templates. |
-| `scripts/` | Python scripts for loop state management, prompt building, outcome recording, path resolution, and preflight checks. |
+| `scripts/` | Python scripts for loop state management, prompt building, outcome recording, path resolution, pacer selection, and preflight checks. |
 
 ## Key files
 
 | File | Role |
 |---|---|
+| `portable-driver.md` | Continuous in-session pacer when Workflow / ScheduleWakeup are absent. |
 | `prompts/pr-consistency-audit.xml` | Structured prompt artifact for the cross-file consistency audit agent. |
-| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/build_audit_prompt.py` | Assembles the audit agent prompt from loop state and the constants module. |
-| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/build_fix_prompt.py` | Assembles the fix agent prompt from loop state and findings. |
-| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/init_loop_state.py` | Initializes the per-PR loop state JSON file. |
-| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/write_audit_outcomes.py` | Writes the per-loop audit outcome XML into the workspace. |
-| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/write_fix_outcomes.py` | Writes the per-loop fix outcome XML into the workspace. |
-| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/preflight_worktree.py` | Verifies the working directory is a healthy worktree for the target PR's repo. |
-| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/teardown_worktrees.py` | Removes loop worktrees on clean exit. |
-| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/write_handoff.py` | Writes durable resume-handoff files under `~/.claude/runtime/pr-loop/<run-name>/` at each converge checkpoint. |
-| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/_path_resolver.py` | Resolves workspace and worktree paths from PR metadata. |
-| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/_cli_utils.py` | Shared CLI argument parsing helpers. |
-| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/_xml_utils.py` | XML serialization helpers. |
+| `scripts/select_converge_pacer.py` | Maps entry skill + host tool flags to `workflow`, `schedule_wakeup`, or `portable`. |
+| `scripts/build_audit_prompt.py` | Assembles the audit agent prompt from loop state and the constants module. |
+| `scripts/build_fix_prompt.py` | Assembles the fix agent prompt from loop state and findings. |
+| `scripts/init_loop_state.py` | Initializes the per-PR loop state JSON file. |
+| `scripts/write_audit_outcomes.py` | Writes the per-loop audit outcome XML into the workspace. |
+| `scripts/write_fix_outcomes.py` | Writes the per-loop fix outcome XML into the workspace. |
+| `scripts/preflight_worktree.py` | Verifies the working directory is a healthy worktree for the target PR's repo. |
+| `scripts/teardown_worktrees.py` | Removes loop worktrees on clean exit. |
+| `scripts/write_handoff.py` | Writes durable resume-handoff files under `~/.claude/runtime/pr-loop/<run-name>/` at each converge checkpoint. |
+| `scripts/_path_resolver.py` | Resolves workspace and worktree paths from PR metadata. |
+| `scripts/_cli_utils.py` | Shared CLI argument parsing helpers. |
+| `scripts/_xml_utils.py` | XML serialization helpers. |
 | `scripts/skills_pr_loop_constants/` | Named constants package imported by the scripts above. |

package/skills/_shared/pr-loop/portable-driver.md

@@ -0,0 +1,150 @@
+# Portable converge driver
+
+**Rule: deterministic control is script-only.** Phase transitions, wait delays,
+clean stamps, ready decisions, task lists, and “what next” never live as prose
+for the agent to invent. The agent runs scripts, reads JSON, and only performs
+judgment steps the JSON names.
+
+## Step 1 — task list (every autoconverge / portable run)
+
+```
+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 id is
+always** `all_runnable_reviews_clean_same_head`. The run is complete only when
+that final task is completed: every runnable code review is CLEAN on one
+shared HEAD. Do not invent tasks in prose.
+
+`open-run` embeds the same list (`tasks`, `runnable_review_ids`,
+`final_task_id`, `done_when`).
+
+## Pacer selection
+
+```
+python "$HOME/.claude/skills/_shared/pr-loop/scripts/select_converge_pacer.py" \
+  --skill <pr-converge|autoconverge> \
+  --has-workflow <0|1> \
+  --has-schedule-wakeup <0|1>
+```
+
+When `pacer` is not `portable`, use the skill’s native Workflow or
+ScheduleWakeup path. When `pacer=portable`, use the control script below.
+
+## Isolation and worktree
+
+1. When the tool list includes `EnterWorktree`, call it (same contract as the
+   Claude-host skills).
+2. When `EnterWorktree` is absent, isolate with git worktree machinery:
+   - Prefer an existing worktree already on the PR head ref under
+     `.claude/worktrees/` (or another dedicated worktree path).
+   - Otherwise `git fetch origin <headRefName>` and
+     `git worktree add <path> <headRefName>` (or `gh pr checkout <N>` into a
+     dedicated directory), then `cd` into that checkout.
+3. Confirm the working directory is the PR’s own repo on the PR head SHA:
+   `python "$HOME/.claude/skills/_shared/pr-loop/scripts/preflight_worktree.py" --owner <O> --repo <R> --mode strict`.
+   Non-zero exit → report the `ABORT` line and stop.
+4. Cross-repo routing follows pr-converge Step 1.5: every local review and edit
+   runs with cwd set to the **PR worktree**.
+
+`open-run` runs the same strict preflight before seeding state.
+
+## Control script
+
+```
+python "$HOME/.claude/skills/_shared/pr-loop/scripts/portable_converge_driver.py" <command> ...
+```
+
+Stdout JSON: `status`, `next`, `phase`, `state_file`, optional `commands`,
+`wait_seconds`, `blocker`, and on `open-run` the task-list fields. Exit `0` =
+ok; `1` = contract failure; `2` = usage error.
+
+| Command | Deterministic effect |
+|---|---|
+| `open-run` | Require `portable`; preflight; seed state + task list; when `--codex-down` is off, set `codex_required` from CLI force-on or the weekly usage probe (same rule as `check_convergence`); next=`run_code_review` |
+| `after-code-review` | From returncode / dirty_tree / served_command |
+| `after-bugteam` | From pushed / converged |
+| `after-bugbot` | From classification / inline lag |
+| `after-codex` | From classification clean / dirty / down |
+| `after-copilot-wait` | From review surfaced / wait cap |
+| `after-ready-check` | From check_convergence exit |
+| `show-state` | Echo state; rehydrate `commands` / `wait_seconds` for pending next |
+
+## Continuous tick loop
+
+After transport check, PR scope, isolation, permission grant, and the once-per-run
+Copilot quota pre-check:
+
+1. Seed or restore state via `open-run` or `show-state` (and handoff
+   `state-copy.json` when resuming).
+2. Run the driver command for the current step; read JSON `next` / `commands` /
+   `wait_seconds`.
+3. On non-terminal `next`:
+   - Write state and handoff when the after-* payload says so.
+   - If `next` is `poll_wait`, sleep `wait_seconds` only, then re-poll and call
+     the matching after-*.
+   - If `next` is immediate work, continue in the same turn without sleeping.
+4. On `mark_ready` / `stop_blocked` / named stop: run lifecycle Close, print the
+   entry skill’s exit block, omit further pacing.
+5. External reviewers remain skippable the same way as Claude-host runs when
+   opted out or down. Push and head-change reset push-invalidated markers
+   (`*_clean_at`, `merge_state_status`, `bugbot_down`, `codex_down`).
+
+## Agent loop (judgment only)
+
+1. Run the driver command for the current step.
+2. If JSON `commands` is non-empty, run that argv (scripted helper).
+3. Map JSON `next` to the single judgment action; report back via the matching
+   `after-*` command.
+4. Mark session tasks complete only when the scripted stamps say so; complete
+   the final task only when every runnable review is clean on the same HEAD.
+
+| `next` | Agent does | Report with |
+|---|---|---|
+| `run_code_review` | Run `commands` | `after-code-review` |
+| `apply_fixes_and_push` | Fix protocol; commit; push | re-review then `after-code-review` |
+| `run_bugteam` | resolve_worker_spawn / bugteam body | `after-bugteam` |
+| `run_bugbot_gate` | Bugbot helper scripts | `after-bugbot` |
+| `run_codex_review` | Run Codex review step | `after-codex` |
+| `request_copilot_review` | Request Copilot | `after-copilot-wait` |
+| `poll_wait` | Sleep `wait_seconds` only | re-poll then after-* |
+| `check_ready` | Run `commands` (check_convergence) | `after-ready-check` |
+| `mark_ready` | Run `commands` (`gh pr ready`) | teardown |
+| `stop_blocked` | Teardown; print blocker | stop |
+
+## Autoconverge entry on portable pacer
+
+When `/autoconverge` selects `pacer=portable`:
+
+- Complete autoconverge pre-flight (scope, draft ownership, strict worktree,
+  grant, Copilot quota).
+- Drive the continuous tick loop above (scripted phase machine) until ready
+  or a documented blocker.
+- Skip `Workflow({ scriptPath: converge.mjs })` — that path requires the
+  Workflow tool.
+- Teardown uses the lifecycle Close path; the Workflow-only closing HTML
+  journal report is optional and skipped when no workflow run id exists.
+- Resume command on handoff: `/autoconverge <PR URL>`.
+
+When `/autoconverge` selects `pacer=workflow`, follow the skill’s Workflow
+sections unchanged.
+
+## Helpers (scripted)
+
+| Concern | Script |
+|---|---|
+| Task list | `build_converge_task_list.py` |
+| Pacer | `select_converge_pacer.py` |
+| Worktree | `preflight_worktree.py` |
+| Code review | `$HOME/.claude/scripts/invoke_code_review.py` |
+| Workers | `$HOME/.claude/scripts/resolve_worker_spawn.py` |
+| Ready | `pr-converge/scripts/check_convergence.py` |
+| Handoff | `write_handoff.py` |
+
+## Fail closed
+
+Never abort solely because Workflow or ScheduleWakeup is missing once
+pacer=`portable`. Fail closed on contract failures only: auth, worktree,
+unresolvable gates, and wait caps.

package/skills/_shared/pr-loop/scripts/CLAUDE.md

@@ -14,6 +14,9 @@ Python scripts that run the PR audit-fix loop at runtime. Both `bugteam` and `pr
 | `preflight_worktree.py` | Verifies the working directory is a healthy git worktree for the target PR's repo. Supports `--mode strict` to abort when the repo does not match. |
 | `teardown_worktrees.py` | Removes per-PR worktrees after a clean loop exit. |
 | `write_handoff.py` | Writes durable resume-handoff files under the run's `~/.claude/runtime/pr-loop` directory at each converge checkpoint. |
+| `select_converge_pacer.py` | Selects `workflow`, `schedule_wakeup`, or `portable` for pr-converge / autoconverge from host tool flags. |
+| `build_converge_task_list.py` | Step-1 task list: runnable review gates + final all_runnable_reviews_clean_same_head. |
+| `portable_converge_driver.py` | portable_converge_driver phase machine: open-run and post-step transitions emit JSON next/commands only. |
 | `_path_resolver.py` | Resolves workspace and worktree paths from PR owner, repo, and number. |
 | `_cli_utils.py` | Shared CLI argument parsing helpers (argparse wrappers). |
 | `_xml_utils.py` | XML serialization helpers for outcome files. |