claude-dev-env 2.1.0 → 2.2.0

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

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""Select the converge pacer for a skill and host tool surface.
+
+Pacer values::
+
+    workflow         — Claude Workflow tool (autoconverge native)
+    schedule_wakeup  — Claude ScheduleWakeup ticks (pr-converge native)
+    portable         — continuous in-session driver (third-party hosts)
+
+Rules::
+
+    autoconverge + Workflow present      -> workflow
+    autoconverge + Workflow absent       -> portable
+    pr-converge  + ScheduleWakeup present -> schedule_wakeup
+    pr-converge  + ScheduleWakeup absent  -> portable
+
+Import ``select_converge_pacer`` or run as a CLI::
+
+    python select_converge_pacer.py --skill <pr-converge|autoconverge> \\
+        --has-workflow <0|1> --has-schedule-wakeup <0|1>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict, dataclass
+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 skills_pr_loop_constants.pacer_constants import (  # noqa: E402
+    ALL_ENTRY_SKILLS,
+    ALL_FALSY_FLAG_TOKENS,
+    ALL_TRUTHY_FLAG_TOKENS,
+    CLI_HAS_SCHEDULE_WAKEUP_FLAG,
+    CLI_HAS_WORKFLOW_FLAG,
+    CLI_SKILL_FLAG,
+    ENTRY_SKILL_AUTOCONVERGE,
+    ENTRY_SKILL_JOIN_SEPARATOR,
+    EXIT_SUCCESS,
+    EXIT_USAGE_ERROR,
+    INVALID_BOOL_FLAG_ERROR,
+    PACER_PORTABLE,
+    PACER_SCHEDULE_WAKEUP,
+    PACER_WORKFLOW,
+    RESULT_KEY_ENTRY_SKILL,
+    RESULT_KEY_HAS_SCHEDULE_WAKEUP,
+    RESULT_KEY_HAS_WORKFLOW,
+    RESULT_KEY_PACER,
+    UNKNOWN_ENTRY_SKILL_ERROR,
+)
+
+
+@dataclass(frozen=True)
+class ConvergePacerSelection:
+    """Result of pacer selection for one skill invocation."""
+
+    pacer: str
+    entry_skill: str
+    has_workflow: bool
+    has_schedule_wakeup: bool
+
+
+def parse_bool_flag(flag_token: str) -> bool:
+    """Parse a CLI boolean token into a bool.
+
+    Args:
+        flag_token: Token from ``--has-workflow`` or ``--has-schedule-wakeup``.
+
+    Returns:
+        True for truthy tokens, False for falsy tokens.
+
+    Raises:
+        ValueError: When the token is not a known boolean form.
+    """
+    normalized_token = flag_token.strip().lower()
+    if normalized_token in ALL_TRUTHY_FLAG_TOKENS:
+        return True
+    if normalized_token in ALL_FALSY_FLAG_TOKENS:
+        return False
+    raise ValueError(INVALID_BOOL_FLAG_ERROR.format(got=flag_token))
+
+
+def select_converge_pacer(
+    *,
+    entry_skill: str,
+    has_workflow: bool,
+    has_schedule_wakeup: bool,
+) -> ConvergePacerSelection:
+    """Return the pacer the named entry skill must use on this host.
+
+    Args:
+        entry_skill: ``pr-converge`` or ``autoconverge``.
+        has_workflow: True when the host tool list includes ``Workflow``.
+        has_schedule_wakeup: True when the host tool list includes
+            ``ScheduleWakeup``.
+
+    Returns:
+        A ``ConvergePacerSelection`` with the chosen ``pacer`` name.
+
+    Raises:
+        ValueError: When ``entry_skill`` is not a known converge entry.
+    """
+    normalized_skill = entry_skill.strip().lower()
+    if normalized_skill not in ALL_ENTRY_SKILLS:
+        raise ValueError(
+            UNKNOWN_ENTRY_SKILL_ERROR.format(
+                allowed=ENTRY_SKILL_JOIN_SEPARATOR.join(ALL_ENTRY_SKILLS),
+                got=entry_skill,
+            )
+        )
+
+    if normalized_skill == ENTRY_SKILL_AUTOCONVERGE:
+        selected_pacer = PACER_WORKFLOW if has_workflow else PACER_PORTABLE
+    else:
+        selected_pacer = (
+            PACER_SCHEDULE_WAKEUP if has_schedule_wakeup else PACER_PORTABLE
+        )
+
+    return ConvergePacerSelection(
+        pacer=selected_pacer,
+        entry_skill=normalized_skill,
+        has_workflow=has_workflow,
+        has_schedule_wakeup=has_schedule_wakeup,
+    )
+
+
+def selection_as_json_dict(
+    selection: ConvergePacerSelection,
+) -> dict[str, str | bool]:
+    """Serialize a selection for JSON stdout.
+
+    Args:
+        selection: Pacer selection to serialize.
+
+    Returns:
+        Dict with stable result keys for CLI and tests.
+    """
+    selection_by_field = asdict(selection)
+    return {
+        RESULT_KEY_PACER: selection_by_field["pacer"],
+        RESULT_KEY_ENTRY_SKILL: selection_by_field["entry_skill"],
+        RESULT_KEY_HAS_WORKFLOW: selection_by_field["has_workflow"],
+        RESULT_KEY_HAS_SCHEDULE_WAKEUP: selection_by_field[
+            "has_schedule_wakeup"
+        ],
+    }
+
+
+def build_argument_parser() -> argparse.ArgumentParser:
+    """Build the CLI parser for pacer selection.
+
+    Returns:
+        Configured argument parser.
+    """
+    parser = argparse.ArgumentParser(
+        description=(
+            "Select workflow, schedule_wakeup, or portable pacer for a "
+            "converge entry skill."
+        )
+    )
+    parser.add_argument(
+        CLI_SKILL_FLAG,
+        required=True,
+        choices=list(ALL_ENTRY_SKILLS),
+        help="Entry skill invoking converge.",
+    )
+    parser.add_argument(
+        CLI_HAS_WORKFLOW_FLAG,
+        required=True,
+        help="1/true when the host tool list includes Workflow.",
+    )
+    parser.add_argument(
+        CLI_HAS_SCHEDULE_WAKEUP_FLAG,
+        required=True,
+        help="1/true when the host tool list includes ScheduleWakeup.",
+    )
+    return parser
+
+
+def main(all_argv: list[str]) -> int:
+    """CLI entry: print one JSON selection line on stdout.
+
+    Args:
+        all_argv: Argument vector (without the program name).
+
+    Returns:
+        Process exit code (0 success, 2 usage/validation error).
+    """
+    parser = build_argument_parser()
+    parsed_arguments = parser.parse_args(all_argv)
+    try:
+        has_workflow = parse_bool_flag(parsed_arguments.has_workflow)
+        has_schedule_wakeup = parse_bool_flag(
+            parsed_arguments.has_schedule_wakeup
+        )
+        selection = select_converge_pacer(
+            entry_skill=parsed_arguments.skill,
+            has_workflow=has_workflow,
+            has_schedule_wakeup=has_schedule_wakeup,
+        )
+    except ValueError as validation_error:
+        print(str(validation_error), file=sys.stderr)
+        return EXIT_USAGE_ERROR
+
+    print(json.dumps(selection_as_json_dict(selection), sort_keys=True))
+    return EXIT_SUCCESS
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

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

@@ -10,6 +10,9 @@ Python package of named constants for the `pr-loop` shared scripts. All constant
 | `path_resolver_constants.py` | Path template strings and format constants: workspace directory naming, worktree directory name, diff patch filename pattern, outcome XML filename patterns, fix status values, audit constraint texts, audit category entries, fix execution steps, and fix constraint texts. |
 | `preflight_constants.py` | Constants used by `preflight_worktree.py` for exit codes and output marker strings. |
 | `handoff_constants.py` | Filename, path-segment, and template constants for the durable handoff writer. |
+| `pacer_constants.py` | Entry-skill names, pacer tokens, CLI flags, and result keys for `select_converge_pacer.py`. |
+| `portable_driver_constants.py` | Phase names, next-action tokens, wait delays, blockers, CLI flags, and result keys for `portable_converge_driver.py`. |
+| `converge_task_list_constants.py` | Task ids, kinds, and CLI flags for `build_converge_task_list.py`. |
 
 ## Usage
 

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/converge_task_list_constants.py

@@ -0,0 +1,56 @@
+"""Constants for the scripted converge task-list builder.
+
+``build_converge_task_list.py`` is the only place that decides which review
+gates appear on a run. Skill prose must not invent a different list.
+"""
+
+from __future__ import annotations
+
+TASK_ID_CODE_REVIEW: str = "code_review"
+TASK_ID_BUGTEAM: str = "bugteam"
+TASK_ID_BUGBOT: str = "bugbot"
+TASK_ID_COPILOT: str = "copilot"
+TASK_ID_CODEX: str = "codex"
+TASK_ID_ALL_CLEAN_SAME_HEAD: str = "all_runnable_reviews_clean_same_head"
+
+TASK_KIND_REVIEW: str = "review"
+TASK_KIND_FINAL: str = "final"
+
+TASK_TITLE_CODE_REVIEW: str = "CODE_REVIEW clean (invoke_code_review / high)"
+TASK_TITLE_BUGTEAM: str = "BUGTEAM clean (full origin/main...HEAD audit)"
+TASK_TITLE_BUGBOT: str = "BUGBOT clean on same HEAD (or down/skip)"
+TASK_TITLE_COPILOT: str = "COPILOT clean on same HEAD (or down/skip)"
+TASK_TITLE_CODEX: str = "CODEX clean on same HEAD (when required)"
+TASK_TITLE_ALL_CLEAN_SAME_HEAD: str = (
+    "All runnable code reviews CLEAN on the same HEAD"
+)
+
+RESULT_KEY_TASKS: str = "tasks"
+RESULT_KEY_FINAL_TASK_ID: str = "final_task_id"
+RESULT_KEY_RUNNABLE_REVIEW_IDS: str = "runnable_review_ids"
+RESULT_KEY_SKIPPED_REVIEW_IDS: str = "skipped_review_ids"
+RESULT_KEY_DONE_WHEN: str = "done_when"
+
+TASK_FIELD_ID: str = "id"
+TASK_FIELD_TITLE: str = "title"
+TASK_FIELD_KIND: str = "kind"
+TASK_FIELD_IS_RUNNABLE: str = "is_runnable"
+TASK_FIELD_SKIP_REASON: str = "skip_reason"
+
+SKIP_REASON_BUGBOT_DOWN: str = "bugbot_down"
+SKIP_REASON_COPILOT_DOWN: str = "copilot_down"
+SKIP_REASON_CODEX_DOWN: str = "codex_down"
+SKIP_REASON_CODEX_NOT_REQUIRED: str = "codex_not_required"
+
+CLI_BUGBOT_DOWN_FLAG: str = "--bugbot-down"
+CLI_COPILOT_DOWN_FLAG: str = "--copilot-down"
+CLI_CODEX_DOWN_FLAG: str = "--codex-down"
+CLI_CODEX_REQUIRED_FLAG: str = "--codex-required"
+
+DONE_WHEN_TEXT: str = (
+    "Every task with is_runnable true and kind review is clean at one shared "
+    "HEAD; final task all_runnable_reviews_clean_same_head is completed."
+)
+
+EXIT_SUCCESS: int = 0
+EXIT_USAGE_ERROR: int = 2

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/pacer_constants.py

@@ -0,0 +1,47 @@
+"""Named constants for converge pacer selection.
+
+Consumed by ``select_converge_pacer.py``. Pacer names are the only values the
+skill hubs and the portable driver accept.
+"""
+
+from __future__ import annotations
+
+ENTRY_SKILL_PR_CONVERGE: str = "pr-converge"
+ENTRY_SKILL_AUTOCONVERGE: str = "autoconverge"
+ALL_ENTRY_SKILLS: tuple[str, ...] = (
+    ENTRY_SKILL_PR_CONVERGE,
+    ENTRY_SKILL_AUTOCONVERGE,
+)
+
+PACER_WORKFLOW: str = "workflow"
+PACER_SCHEDULE_WAKEUP: str = "schedule_wakeup"
+PACER_PORTABLE: str = "portable"
+
+CLI_SKILL_FLAG: str = "--skill"
+CLI_HAS_WORKFLOW_FLAG: str = "--has-workflow"
+CLI_HAS_SCHEDULE_WAKEUP_FLAG: str = "--has-schedule-wakeup"
+
+RESULT_KEY_PACER: str = "pacer"
+RESULT_KEY_ENTRY_SKILL: str = "entry_skill"
+RESULT_KEY_HAS_WORKFLOW: str = "has_workflow"
+RESULT_KEY_HAS_SCHEDULE_WAKEUP: str = "has_schedule_wakeup"
+
+ALL_TRUTHY_FLAG_TOKENS: frozenset[str] = frozenset(
+    {"1", "true", "yes", "on", "y", "t"}
+)
+ALL_FALSY_FLAG_TOKENS: frozenset[str] = frozenset(
+    {"0", "false", "no", "off", "n", "f"}
+)
+
+ENTRY_SKILL_JOIN_SEPARATOR: str = ", "
+
+UNKNOWN_ENTRY_SKILL_ERROR: str = (
+    "entry skill must be one of {allowed}; got {got!r}"
+)
+INVALID_BOOL_FLAG_ERROR: str = (
+    "flag value must be a boolean token (0/1, true/false, yes/no, on/off); "
+    "got {got!r}"
+)
+
+EXIT_SUCCESS: int = 0
+EXIT_USAGE_ERROR: int = 2

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/portable_driver_constants.py

@@ -0,0 +1,181 @@
+"""Constants for the scripted portable converge driver.
+
+Deterministic control for third-party pacers lives in
+``portable_converge_driver.py``. These names are the only phase, next-action,
+and delay tokens that driver emits.
+"""
+
+from __future__ import annotations
+
+PHASE_CODE_REVIEW: str = "CODE_REVIEW"
+PHASE_BUGTEAM: str = "BUGTEAM"
+PHASE_BUGBOT: str = "BUGBOT"
+PHASE_COPILOT_WAIT: str = "COPILOT_WAIT"
+PHASE_READY: str = "READY"
+PHASE_BLOCKED: str = "BLOCKED"
+ALL_PHASES: tuple[str, ...] = (
+    PHASE_CODE_REVIEW,
+    PHASE_BUGTEAM,
+    PHASE_BUGBOT,
+    PHASE_COPILOT_WAIT,
+    PHASE_READY,
+    PHASE_BLOCKED,
+)
+
+NEXT_RUN_CODE_REVIEW: str = "run_code_review"
+NEXT_APPLY_FIXES: str = "apply_fixes_and_push"
+NEXT_RUN_BUGTEAM: str = "run_bugteam"
+NEXT_RUN_BUGBOT_GATE: str = "run_bugbot_gate"
+NEXT_RUN_CODEX: str = "run_codex_review"
+NEXT_REQUEST_COPILOT: str = "request_copilot_review"
+NEXT_POLL_WAIT: str = "poll_wait"
+NEXT_CHECK_READY: str = "check_ready"
+NEXT_MARK_READY: str = "mark_ready"
+NEXT_TEARDOWN: str = "teardown"
+NEXT_STOP_BLOCKED: str = "stop_blocked"
+ALL_NEXT_ACTIONS: tuple[str, ...] = (
+    NEXT_RUN_CODE_REVIEW,
+    NEXT_APPLY_FIXES,
+    NEXT_RUN_BUGTEAM,
+    NEXT_RUN_BUGBOT_GATE,
+    NEXT_RUN_CODEX,
+    NEXT_REQUEST_COPILOT,
+    NEXT_POLL_WAIT,
+    NEXT_CHECK_READY,
+    NEXT_MARK_READY,
+    NEXT_TEARDOWN,
+    NEXT_STOP_BLOCKED,
+)
+
+DEFAULT_WAIT_SECONDS: int = 360
+BUGBOT_INLINE_LAG_WAIT_SECONDS: int = 90
+INLINE_LAG_STREAK_CAP: int = 3
+COPILOT_WAIT_HARD_CAP: int = 3
+BUGBOT_ABSENT_WAIT_HARD_CAP: int = 3
+
+STATE_FILENAME: str = "pr-converge-state.json"
+STATE_JSON_INDENT: int = 2
+STATE_STAGING_SUFFIX: str = ".tmp"
+ALL_GIT_REV_PARSE_HEAD_ARGV: tuple[str, ...] = ("git", "rev-parse", "HEAD")
+PREFLIGHT_WORKTREE_SCRIPT_NAME: str = "preflight_worktree.py"
+CLI_DESCRIPTION: str = "portable_converge_driver phase machine"
+SERVED_COMMAND_IN_SESSION: str = "in_session"
+
+RESULT_KEY_STATUS: str = "status"
+RESULT_KEY_PHASE: str = "phase"
+RESULT_KEY_NEXT: str = "next"
+RESULT_KEY_STATE_FILE: str = "state_file"
+RESULT_KEY_CURRENT_HEAD: str = "current_head"
+RESULT_KEY_TICK_COUNT: str = "tick_count"
+RESULT_KEY_WAIT_SECONDS: str = "wait_seconds"
+RESULT_KEY_BLOCKER: str = "blocker"
+RESULT_KEY_COMMANDS: str = "commands"
+RESULT_KEY_PACER: str = "pacer"
+RESULT_KEY_ENTRY_SKILL: str = "entry_skill"
+RESULT_KEY_OWNER: str = "owner"
+RESULT_KEY_REPO: str = "repo"
+RESULT_KEY_PR_NUMBER: str = "pr_number"
+RESULT_KEY_MESSAGE: str = "message"
+RESULT_KEY_COPILOT_DOWN: str = "copilot_down"
+RESULT_KEY_BUGBOT_DOWN: str = "bugbot_down"
+RESULT_KEY_CODEX_DOWN: str = "codex_down"
+
+STATUS_OK: str = "ok"
+STATUS_ERROR: str = "error"
+
+BLOCKER_COPILOT_WAIT_CAP: str = "copilot_wait_cap"
+BLOCKER_BUGBOT_WAIT_CAP: str = "bugbot_wait_cap"
+BLOCKER_INLINE_LAG_CAP: str = "inline_lag_cap"
+BLOCKER_REVIEW_FAILED: str = "code_review_failed"
+BLOCKER_PREFLIGHT: str = "preflight_failed"
+BLOCKER_NOT_PORTABLE: str = "pacer_not_portable"
+
+CLI_STATE_DIR_FLAG: str = "--state-dir"
+CLI_STATE_FILE_FLAG: str = "--state-file"
+CLI_OWNER_FLAG: str = "--owner"
+CLI_REPO_FLAG: str = "--repo"
+CLI_PR_NUMBER_FLAG: str = "--pr-number"
+CLI_CWD_FLAG: str = "--cwd"
+CLI_SESSION_MODEL_FLAG: str = "--session-model"
+CLI_RETURNCODE_FLAG: str = "--returncode"
+CLI_DIRTY_TREE_FLAG: str = "--dirty-tree"
+CLI_SERVED_COMMAND_FLAG: str = "--served-command"
+CLI_PUSHED_FLAG: str = "--pushed"
+CLI_CONVERGED_FLAG: str = "--converged"
+CLI_CLASSIFICATION_FLAG: str = "--classification"
+CLI_REVIEW_SURFACED_FLAG: str = "--review-surfaced"
+CLI_INLINE_LAG_FLAG: str = "--inline-lag"
+CLI_BUGBOT_DOWN_FLAG: str = "--bugbot-down"
+CLI_COPILOT_DOWN_FLAG: str = "--copilot-down"
+CLI_CODEX_DOWN_FLAG: str = "--codex-down"
+CLI_CODEX_REQUIRED_FLAG: str = "--codex-required"
+CLI_CODEX_CLEAN_AT_FLAG: str = "--codex-clean-at"
+CLI_CURRENT_HEAD_FLAG: str = "--current-head"
+CLI_CHECK_CONVERGENCE_EXIT_FLAG: str = "--check-exit"
+
+CLASSIFICATION_CLEAN: str = "clean"
+CLASSIFICATION_DIRTY: str = "dirty"
+CLASSIFICATION_ABSENT: str = "absent"
+CLASSIFICATION_DOWN: str = "down"
+ALL_CLASSIFICATIONS: tuple[str, ...] = (
+    CLASSIFICATION_CLEAN,
+    CLASSIFICATION_DIRTY,
+    CLASSIFICATION_ABSENT,
+    CLASSIFICATION_DOWN,
+)
+ALL_COPILOT_CLASSIFICATIONS: tuple[str, ...] = (
+    CLASSIFICATION_CLEAN,
+    CLASSIFICATION_DIRTY,
+    CLASSIFICATION_ABSENT,
+    CLASSIFICATION_DOWN,
+)
+ALL_CODEX_CLASSIFICATIONS: tuple[str, ...] = (
+    CLASSIFICATION_CLEAN,
+    CLASSIFICATION_DIRTY,
+    CLASSIFICATION_DOWN,
+)
+
+STATE_KEY_PENDING_NEXT: str = "pending_next"
+STATE_KEY_PENDING_WAIT_SECONDS: str = "pending_wait_seconds"
+STATE_KEY_CODEX_DOWN: str = "codex_down"
+STATE_KEY_CODEX_REQUIRED: str = "codex_required"
+STATE_KEY_CODEX_CLEAN_AT: str = "codex_clean_at"
+STATE_KEY_SESSION_MODEL: str = "session_model"
+STATE_KEY_CWD: str = "cwd"
+
+MARK_READY_GH_BINARY: str = "gh"
+MARK_READY_PR_TOKEN: str = "pr"
+MARK_READY_SUBCOMMAND: str = "ready"
+MARK_READY_REPO_FLAG: str = "--repo"
+
+CHECK_CONVERGENCE_OWNER_FLAG: str = "--owner"
+CHECK_CONVERGENCE_REPO_FLAG: str = "--repo"
+CHECK_CONVERGENCE_PR_NUMBER_FLAG: str = "--pr-number"
+CHECK_CONVERGENCE_COPILOT_DOWN_FLAG: str = "--copilot-down"
+CHECK_CONVERGENCE_BUGBOT_DOWN_FLAG: str = "--bugbot-down"
+CHECK_CONVERGENCE_CODEX_DOWN_FLAG: str = "--codex-down"
+CHECK_CONVERGENCE_CODEX_CLEAN_AT_FLAG: str = "--codex-clean-at"
+
+COMMAND_OPEN_RUN: str = "open-run"
+COMMAND_AFTER_CODE_REVIEW: str = "after-code-review"
+COMMAND_AFTER_BUGTEAM: str = "after-bugteam"
+COMMAND_AFTER_BUGBOT: str = "after-bugbot"
+COMMAND_AFTER_COPILOT_WAIT: str = "after-copilot-wait"
+COMMAND_AFTER_CODEX: str = "after-codex"
+COMMAND_AFTER_READY_CHECK: str = "after-ready-check"
+COMMAND_SHOW_STATE: str = "show-state"
+
+DEFAULT_SESSION_MODEL: str = "third-party"
+
+INVOKE_CODE_REVIEW_RELATIVE_PATH: str = ".claude/scripts/invoke_code_review.py"
+CHECK_CONVERGENCE_RELATIVE_PATH: str = (
+    ".claude/skills/pr-converge/scripts/check_convergence.py"
+)
+
+CODEX_REVIEW_SKILL_DIRNAME: str = "codex-review"
+CODEX_REVIEW_SCRIPTS_DIRNAME: str = "scripts"
+PORTABLE_SCRIPTS_TO_SKILLS_PARENT_HOPS: int = 3
+
+EXIT_SUCCESS: int = 0
+EXIT_USAGE_ERROR: int = 2
+EXIT_CONTRACT_ERROR: int = 1

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

@@ -0,0 +1,140 @@
+"""Tests for build_converge_task_list — runnable gates and final CLEAN task."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+import build_converge_task_list as task_list_module  # noqa: E402
+from skills_pr_loop_constants.converge_task_list_constants import (  # noqa: E402
+    EXIT_SUCCESS,
+    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_NOT_REQUIRED,
+    SKIP_REASON_COPILOT_DOWN,
+    TASK_FIELD_ID,
+    TASK_FIELD_IS_RUNNABLE,
+    TASK_FIELD_KIND,
+    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,
+)
+
+SCRIPT_PATH = _SCRIPTS_DIR / "build_converge_task_list.py"
+
+
+def test_default_flags_code_review_and_bugteam_runnable_final_last() -> None:
+    payload = task_list_module.build_converge_task_list(
+        is_bugbot_down=False,
+        is_copilot_down=False,
+        is_codex_down=False,
+        is_codex_required=False,
+    )
+    all_tasks = payload[RESULT_KEY_TASKS]
+    assert isinstance(all_tasks, list)
+    assert all_tasks[0][TASK_FIELD_ID] == TASK_ID_CODE_REVIEW
+    assert all_tasks[1][TASK_FIELD_ID] == TASK_ID_BUGTEAM
+    assert all_tasks[-1][TASK_FIELD_ID] == TASK_ID_ALL_CLEAN_SAME_HEAD
+    assert all_tasks[-1][TASK_FIELD_KIND] == TASK_KIND_FINAL
+    assert payload[RESULT_KEY_FINAL_TASK_ID] == TASK_ID_ALL_CLEAN_SAME_HEAD
+    assert TASK_ID_CODE_REVIEW in payload[RESULT_KEY_RUNNABLE_REVIEW_IDS]
+    assert TASK_ID_BUGTEAM in payload[RESULT_KEY_RUNNABLE_REVIEW_IDS]
+    assert TASK_ID_BUGBOT in payload[RESULT_KEY_RUNNABLE_REVIEW_IDS]
+    assert TASK_ID_COPILOT in payload[RESULT_KEY_RUNNABLE_REVIEW_IDS]
+    assert TASK_ID_CODEX in payload[RESULT_KEY_SKIPPED_REVIEW_IDS]
+
+
+def test_down_flags_skip_external_reviews() -> None:
+    payload = task_list_module.build_converge_task_list(
+        is_bugbot_down=True,
+        is_copilot_down=True,
+        is_codex_down=True,
+        is_codex_required=True,
+    )
+    all_tasks = payload[RESULT_KEY_TASKS]
+    assert isinstance(all_tasks, list)
+    all_tasks_by_id = {
+        each_task[TASK_FIELD_ID]: each_task for each_task in all_tasks
+    }
+    assert all_tasks_by_id[TASK_ID_BUGBOT][TASK_FIELD_IS_RUNNABLE] is False
+    assert all_tasks_by_id[TASK_ID_COPILOT][TASK_FIELD_IS_RUNNABLE] is False
+    assert all_tasks_by_id[TASK_ID_CODEX][TASK_FIELD_IS_RUNNABLE] is False
+    assert payload[RESULT_KEY_RUNNABLE_REVIEW_IDS] == [
+        TASK_ID_CODE_REVIEW,
+        TASK_ID_BUGTEAM,
+    ]
+    assert SKIP_REASON_BUGBOT_DOWN in str(all_tasks_by_id[TASK_ID_BUGBOT])
+    assert SKIP_REASON_COPILOT_DOWN in str(all_tasks_by_id[TASK_ID_COPILOT])
+
+
+def test_codex_required_is_runnable() -> None:
+    payload = task_list_module.build_converge_task_list(
+        is_bugbot_down=True,
+        is_copilot_down=True,
+        is_codex_down=False,
+        is_codex_required=True,
+    )
+    assert TASK_ID_CODEX in payload[RESULT_KEY_RUNNABLE_REVIEW_IDS]
+    assert SKIP_REASON_CODEX_NOT_REQUIRED not in str(payload)
+
+
+def test_final_task_always_last_and_runnable() -> None:
+    payload = task_list_module.build_converge_task_list(
+        is_bugbot_down=True,
+        is_copilot_down=False,
+        is_codex_down=False,
+        is_codex_required=True,
+    )
+    all_tasks = payload[RESULT_KEY_TASKS]
+    assert isinstance(all_tasks, list)
+    final_task = all_tasks[-1]
+    assert final_task[TASK_FIELD_ID] == TASK_ID_ALL_CLEAN_SAME_HEAD
+    assert final_task[TASK_FIELD_IS_RUNNABLE] is True
+    assert final_task[TASK_FIELD_KIND] == TASK_KIND_FINAL
+    assert payload[RESULT_KEY_DONE_WHEN]
+
+
+def test_cli_prints_json() -> None:
+    completed = subprocess.run(
+        [
+            sys.executable,
+            str(SCRIPT_PATH),
+            "--bugbot-down",
+            "1",
+            "--copilot-down",
+            "0",
+            "--codex-required",
+            "0",
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    assert completed.returncode == EXIT_SUCCESS, completed.stderr
+    payload = json.loads(completed.stdout)
+    assert payload[RESULT_KEY_FINAL_TASK_ID] == TASK_ID_ALL_CLEAN_SAME_HEAD
+    assert TASK_ID_BUGBOT in payload[RESULT_KEY_SKIPPED_REVIEW_IDS]
+    assert any(
+        each_task[TASK_FIELD_KIND] == TASK_KIND_REVIEW
+        for each_task in payload[RESULT_KEY_TASKS]
+    )
+
+
+def test_main_returns_usage_on_bad_bool() -> None:
+    exit_code = task_list_module.main(["--bugbot-down", "maybe"])
+    assert exit_code == task_list_module.EXIT_USAGE_ERROR