claude-dev-env 2.1.0 → 2.2.0

package/package.json

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

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. |

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

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+"""``build_converge_task_list.py`` — ordered review tasks for a run.
+
+Step 1 of autoconverge / portable pr-converge: call this script. Do not invent
+tasks in prose. The final task is always all runnable code reviews CLEAN on
+the same HEAD.
+
+::
+
+    python build_converge_task_list.py \\
+        [--bugbot-down 0|1] [--copilot-down 0|1] \\
+        [--codex-down 0|1] [--codex-required 0|1]
+
+Stdout JSON::
+
+    {
+      "tasks": [...],
+      "runnable_review_ids": [...],
+      "skipped_review_ids": [...],
+      "final_task_id": "all_runnable_reviews_clean_same_head",
+      "done_when": "..."
+    }
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+_self_dir = Path(__file__).resolve().parent
+if str(_self_dir) not in sys.path:
+    sys.path.insert(0, str(_self_dir))
+
+from select_converge_pacer import parse_bool_flag  # noqa: E402
+from skills_pr_loop_constants.converge_task_list_constants import (  # noqa: E402
+    CLI_BUGBOT_DOWN_FLAG,
+    CLI_CODEX_DOWN_FLAG,
+    CLI_CODEX_REQUIRED_FLAG,
+    CLI_COPILOT_DOWN_FLAG,
+    DONE_WHEN_TEXT,
+    EXIT_SUCCESS,
+    EXIT_USAGE_ERROR,
+    RESULT_KEY_DONE_WHEN,
+    RESULT_KEY_FINAL_TASK_ID,
+    RESULT_KEY_RUNNABLE_REVIEW_IDS,
+    RESULT_KEY_SKIPPED_REVIEW_IDS,
+    RESULT_KEY_TASKS,
+    SKIP_REASON_BUGBOT_DOWN,
+    SKIP_REASON_CODEX_DOWN,
+    SKIP_REASON_CODEX_NOT_REQUIRED,
+    SKIP_REASON_COPILOT_DOWN,
+    TASK_FIELD_ID,
+    TASK_FIELD_IS_RUNNABLE,
+    TASK_FIELD_KIND,
+    TASK_FIELD_SKIP_REASON,
+    TASK_FIELD_TITLE,
+    TASK_ID_ALL_CLEAN_SAME_HEAD,
+    TASK_ID_BUGBOT,
+    TASK_ID_BUGTEAM,
+    TASK_ID_CODE_REVIEW,
+    TASK_ID_CODEX,
+    TASK_ID_COPILOT,
+    TASK_KIND_FINAL,
+    TASK_KIND_REVIEW,
+    TASK_TITLE_ALL_CLEAN_SAME_HEAD,
+    TASK_TITLE_BUGBOT,
+    TASK_TITLE_BUGTEAM,
+    TASK_TITLE_CODE_REVIEW,
+    TASK_TITLE_CODEX,
+    TASK_TITLE_COPILOT,
+)
+
+
+def _review_task(
+    *,
+    task_id: str,
+    title: str,
+    is_runnable: bool,
+    skip_reason: str | None,
+) -> dict[str, object]:
+    task: dict[str, object] = {
+        TASK_FIELD_ID: task_id,
+        TASK_FIELD_TITLE: title,
+        TASK_FIELD_KIND: TASK_KIND_REVIEW,
+        TASK_FIELD_IS_RUNNABLE: is_runnable,
+    }
+    if skip_reason is not None:
+        task[TASK_FIELD_SKIP_REASON] = skip_reason
+    return task
+
+
+def _append_always_runnable_reviews(
+    all_tasks: list[dict[str, object]],
+) -> None:
+    all_tasks.append(
+        _review_task(
+            task_id=TASK_ID_CODE_REVIEW,
+            title=TASK_TITLE_CODE_REVIEW,
+            is_runnable=True,
+            skip_reason=None,
+        )
+    )
+    all_tasks.append(
+        _review_task(
+            task_id=TASK_ID_BUGTEAM,
+            title=TASK_TITLE_BUGTEAM,
+            is_runnable=True,
+            skip_reason=None,
+        )
+    )
+
+
+def _append_bugbot_task(
+    all_tasks: list[dict[str, object]],
+    *,
+    is_bugbot_down: bool,
+) -> None:
+    if is_bugbot_down:
+        all_tasks.append(
+            _review_task(
+                task_id=TASK_ID_BUGBOT,
+                title=TASK_TITLE_BUGBOT,
+                is_runnable=False,
+                skip_reason=SKIP_REASON_BUGBOT_DOWN,
+            )
+        )
+        return
+    all_tasks.append(
+        _review_task(
+            task_id=TASK_ID_BUGBOT,
+            title=TASK_TITLE_BUGBOT,
+            is_runnable=True,
+            skip_reason=None,
+        )
+    )
+
+
+def _append_copilot_task(
+    all_tasks: list[dict[str, object]],
+    *,
+    is_copilot_down: bool,
+) -> None:
+    if is_copilot_down:
+        all_tasks.append(
+            _review_task(
+                task_id=TASK_ID_COPILOT,
+                title=TASK_TITLE_COPILOT,
+                is_runnable=False,
+                skip_reason=SKIP_REASON_COPILOT_DOWN,
+            )
+        )
+        return
+    all_tasks.append(
+        _review_task(
+            task_id=TASK_ID_COPILOT,
+            title=TASK_TITLE_COPILOT,
+            is_runnable=True,
+            skip_reason=None,
+        )
+    )
+
+
+def _append_codex_task(
+    all_tasks: list[dict[str, object]],
+    *,
+    is_codex_down: bool,
+    is_codex_required: bool,
+) -> None:
+    if is_codex_down:
+        all_tasks.append(
+            _review_task(
+                task_id=TASK_ID_CODEX,
+                title=TASK_TITLE_CODEX,
+                is_runnable=False,
+                skip_reason=SKIP_REASON_CODEX_DOWN,
+            )
+        )
+        return
+    if not is_codex_required:
+        all_tasks.append(
+            _review_task(
+                task_id=TASK_ID_CODEX,
+                title=TASK_TITLE_CODEX,
+                is_runnable=False,
+                skip_reason=SKIP_REASON_CODEX_NOT_REQUIRED,
+            )
+        )
+        return
+    all_tasks.append(
+        _review_task(
+            task_id=TASK_ID_CODEX,
+            title=TASK_TITLE_CODEX,
+            is_runnable=True,
+            skip_reason=None,
+        )
+    )
+
+
+def _append_final_task(all_tasks: list[dict[str, object]]) -> None:
+    all_tasks.append(
+        {
+            TASK_FIELD_ID: TASK_ID_ALL_CLEAN_SAME_HEAD,
+            TASK_FIELD_TITLE: TASK_TITLE_ALL_CLEAN_SAME_HEAD,
+            TASK_FIELD_KIND: TASK_KIND_FINAL,
+            TASK_FIELD_IS_RUNNABLE: True,
+        }
+    )
+
+
+def _partition_review_ids(
+    all_tasks: list[dict[str, object]],
+) -> tuple[list[str], list[str]]:
+    all_runnable_review_ids = [
+        str(each_task[TASK_FIELD_ID])
+        for each_task in all_tasks
+        if each_task[TASK_FIELD_KIND] == TASK_KIND_REVIEW
+        and each_task[TASK_FIELD_IS_RUNNABLE] is True
+    ]
+    all_skipped_review_ids = [
+        str(each_task[TASK_FIELD_ID])
+        for each_task in all_tasks
+        if each_task[TASK_FIELD_KIND] == TASK_KIND_REVIEW
+        and each_task[TASK_FIELD_IS_RUNNABLE] is False
+    ]
+    return all_runnable_review_ids, all_skipped_review_ids
+
+
+def build_converge_task_list(
+    *,
+    is_bugbot_down: bool,
+    is_copilot_down: bool,
+    is_codex_down: bool,
+    is_codex_required: bool,
+) -> dict[str, object]:
+    """Return the ordered task list and done criterion for one converge run.
+
+    Args:
+        is_bugbot_down: Skip Bugbot as a runnable review.
+        is_copilot_down: Skip Copilot as a runnable review.
+        is_codex_down: Skip Codex even when usage would require it.
+        is_codex_required: Weekly usage / policy requires a Codex review.
+
+    Returns:
+        JSON-serializable control object with ``tasks`` and ``done_when``.
+    """
+    all_tasks: list[dict[str, object]] = []
+    _append_always_runnable_reviews(all_tasks)
+    _append_bugbot_task(all_tasks, is_bugbot_down=is_bugbot_down)
+    _append_copilot_task(all_tasks, is_copilot_down=is_copilot_down)
+    _append_codex_task(
+        all_tasks,
+        is_codex_down=is_codex_down,
+        is_codex_required=is_codex_required,
+    )
+    _append_final_task(all_tasks)
+    all_runnable_review_ids, all_skipped_review_ids = _partition_review_ids(
+        all_tasks
+    )
+    return {
+        RESULT_KEY_TASKS: all_tasks,
+        RESULT_KEY_RUNNABLE_REVIEW_IDS: all_runnable_review_ids,
+        RESULT_KEY_SKIPPED_REVIEW_IDS: all_skipped_review_ids,
+        RESULT_KEY_FINAL_TASK_ID: TASK_ID_ALL_CLEAN_SAME_HEAD,
+        RESULT_KEY_DONE_WHEN: DONE_WHEN_TEXT,
+    }
+
+
+def build_argument_parser() -> argparse.ArgumentParser:
+    """Build the CLI parser for ``build_converge_task_list``.
+
+    Returns:
+        Configured argument parser.
+    """
+    parser = argparse.ArgumentParser(description="build_converge_task_list")
+    parser.add_argument(CLI_BUGBOT_DOWN_FLAG, default="0")
+    parser.add_argument(CLI_COPILOT_DOWN_FLAG, default="0")
+    parser.add_argument(CLI_CODEX_DOWN_FLAG, default="0")
+    parser.add_argument(CLI_CODEX_REQUIRED_FLAG, default="0")
+    return parser
+
+
+def main(all_argv: list[str]) -> int:
+    """CLI entry: print one task-list JSON object on stdout.
+
+    Args:
+        all_argv: Argument vector without program name.
+
+    Returns:
+        Process exit code.
+    """
+    parser = build_argument_parser()
+    parsed_arguments = parser.parse_args(all_argv)
+    try:
+        task_list_payload = build_converge_task_list(
+            is_bugbot_down=parse_bool_flag(parsed_arguments.bugbot_down),
+            is_copilot_down=parse_bool_flag(parsed_arguments.copilot_down),
+            is_codex_down=parse_bool_flag(parsed_arguments.codex_down),
+            is_codex_required=parse_bool_flag(parsed_arguments.codex_required),
+        )
+    except ValueError as validation_error:
+        print(str(validation_error), file=sys.stderr)
+        return EXIT_USAGE_ERROR
+    print(json.dumps(task_list_payload, sort_keys=True))
+    return EXIT_SUCCESS
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))