@xenonbyte/req-2-plan 0.4.5 → 0.5.1

package/tools/workflow_cli/agent_shortcuts.py

@@ -7,6 +7,9 @@ Usage:
 from __future__ import annotations
 
 import argparse
+import contextlib
+import io
+import json
 import re
 import shutil
 import shlex
@@ -16,7 +19,8 @@ from pathlib import Path
 
 from tools.workflow_cli.atomic import atomic_write_text
 from tools.workflow_cli.models import RunStatus, WorkId
-from tools.workflow_cli.output import EXIT_CONFLICT
+from tools.workflow_cli.output import EXIT_CONFLICT, is_json_mode
+from tools.workflow_cli.workspace import ensure_workspace_gitignore
 
 ACTIVE_POINTER_FILE = ".workflow-active"
 
@@ -42,10 +46,22 @@ def read_active_pointer(base_path: Path) -> dict | None:
     return data if data else None
 
 
+def _ensure_workspace_gitignore_or_exit(base_path: Path, work_id: str) -> None:
+    try:
+        ensure_workspace_gitignore(base_path)
+    except ValueError as exc:
+        print(
+            "blocked: unsafe_workspace_gitignore\n"
+            f"work_id: {work_id}\n"
+            f"reason: {exc}\n"
+        )
+        sys.exit(EXIT_CONFLICT)
+
+
 def write_active_pointer(base_path: Path, work_id: str, reason: str = "workflow_start") -> None:
     work_id = _validate_work_id(work_id)
+    _ensure_workspace_gitignore_or_exit(base_path, work_id)
     path = _pointer_path(base_path)
-    path.parent.mkdir(parents=True, exist_ok=True)
     run_rel = f".req-to-plan/{work_id}/run.md"
     updated_at = datetime.now(timezone.utc).astimezone().isoformat()
     content = (
@@ -136,19 +152,24 @@ def generate_work_id(
     if base_path is None:
         return base_id
 
-    if not (base_path / ".req-to-plan" / base_id).exists():
+    r2p_dir = base_path / ".req-to-plan"
+
+    def is_reserved(work_id: str) -> bool:
+        return (r2p_dir / work_id).exists() or (r2p_dir / "archive" / work_id).exists()
+
+    if not is_reserved(base_id):
         return base_id
 
     for n in range(2, 100):
         suffix = f"-{n}"
         alt_candidate = candidate[:max_slug_len - len(suffix)].rstrip("-")
         alt = f"{prefix}{alt_candidate}{suffix}"
-        if not (base_path / ".req-to-plan" / alt).exists():
+        if not is_reserved(alt):
             return alt
 
     raise RuntimeError(
         f"Could not generate a unique work ID for {base_id!r} after 98 attempts. "
-        "Clean up old runs in .req-to-plan/ before starting a new one."
+        "Clean up old runs in .req-to-plan/ or .req-to-plan/archive/ before starting a new one."
     )
 
 
@@ -158,7 +179,7 @@ def generate_work_id(
 
 
 def is_terminal(status: RunStatus) -> bool:
-    return status == RunStatus.CLOSED_AT_PLAN_CHECKPOINT
+    return status in (RunStatus.CLOSED_AT_PLAN_CHECKPOINT, RunStatus.ARCHIVED)
 
 
 # ---------------------------------------------------------------------------
@@ -180,6 +201,36 @@ def _shell_join(parts: list[str | Path]) -> str:
     return " ".join(shlex.quote(str(part)) for part in parts)
 
 
+def _extract_cli_output_value(output: str, key: str) -> str | None:
+    stripped = output.strip()
+    if stripped.startswith("{"):
+        try:
+            payload = json.loads(stripped)
+        except json.JSONDecodeError:
+            payload = {}
+        value = payload.get(key)
+        if isinstance(value, str):
+            return value
+
+    prefix = f"{key}:"
+    for line in output.splitlines():
+        line = line.strip()
+        if line.startswith(prefix):
+            return line.partition(":")[2].strip()
+    return None
+
+
+def _json_payload_from_cli_output(output: str) -> dict[str, object]:
+    stripped = output.strip()
+    if not stripped:
+        return {}
+    try:
+        parsed = json.loads(stripped)
+    except json.JSONDecodeError:
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
 def _repo_root() -> Path:
     return Path(__file__).resolve().parents[2]
 
@@ -221,10 +272,15 @@ def _tier_lock_command(base_path: Path, work_id: str, record) -> str:
 
 
 def _prepare_input_file(run_dir: Path, stage: str, suffix: str, seed: str = "") -> Path:
-    path = run_dir / "inputs" / f"{stage}-{suffix}.md"
-    path.parent.mkdir(parents=True, exist_ok=True)
+    inputs_dir = run_dir / "inputs"
+    if inputs_dir.is_symlink():
+        raise ValueError("unsafe_input_file_symlink")
+    inputs_dir.mkdir(parents=True, exist_ok=True)
+    path = inputs_dir / f"{stage}-{suffix}.md"
+    if path.is_symlink():
+        raise ValueError("unsafe_input_file_symlink")
     if not path.exists():
-        path.write_text(seed, encoding="utf-8")
+        atomic_write_text(path, seed)
     return path
 
 
@@ -318,7 +374,9 @@ def _emit_checkpoint_stop(
             f"reason: forced subagent review required (tier modifier: {modifiers})\n"
             "note: you are authorized to spawn a read-only review subagent now; "
             "separate human approval is NOT required for this step\n"
-            "next: have the review subagent audit the stage artifact, write its "
+            "next: have the review subagent audit the stage artifact for spec "
+            "compliance, code/design quality, AND any unresolved ambiguity / "
+            "undecided point (flag hedging that lacks a decision), write its "
             "findings to review_file, then r2p-continue\n"
         )
         return
@@ -435,6 +493,7 @@ def _cmd_start(ns: argparse.Namespace, base_path: Path) -> None:
 
     work_id = generate_work_id(requirement, base_path)
     run_args = _build_run_start_args(work_id, requirement, file_path, getattr(ns, "repo_path", None))
+    _ensure_workspace_gitignore_or_exit(base_path, work_id)
     exit_code = _run_cli(run_args, base_path)
     if exit_code != 0:
         sys.exit(exit_code)
@@ -468,9 +527,25 @@ def _cmd_continue(ns: argparse.Namespace, base_path: Path) -> None:
         s = record.status
         stage = record.current_stage.value
 
+        if s == RunStatus.EXECUTING:
+            ledger = run_path.parent / "execution" / "progress.md"
+            print(
+                "stop: resume_execution\n"
+                f"work_id: {work_id}\n"
+                f"ledger: {ledger}\n"
+                "next: resume the r2p-execute loop from the first unchecked task\n"
+            )
+            sys.exit(0)
+
+        if s == RunStatus.ARCHIVED:
+            print(f"done: archived\nwork_id: {work_id}\n")
+            sys.exit(0)
+
         if s == RunStatus.CLOSED_AT_PLAN_CHECKPOINT:
             print(f"done: run_closed\nwork_id: {work_id}\nplan: 07-plan.md\n"
-                  "next: hand the PLAN to your executor\n")
+                  "next: hand the PLAN to your executor\n"
+                  f"to implement: r2p-execute --work-id {work_id}\n"
+                  f"to archive: r2p-archive --work-id {work_id}\n")
             sys.exit(0)
 
         if s == RunStatus.ACTIVE_STAGE_DRAFT:
@@ -691,16 +766,206 @@ def _cmd_switch(ns: argparse.Namespace, base_path: Path) -> None:
 
 def _cmd_reopen(ns: argparse.Namespace, base_path: Path) -> None:
     from_id = _validate_work_id(ns.from_id)
-    exit_code = _run_cli(
-        [
-            "run-reopen",
-            "--from", from_id,
-            "--stage", ns.stage,
-            "--reason", ns.reason,
-        ],
-        base_path,
-    )
-    sys.exit(exit_code)
+    _ensure_workspace_gitignore_or_exit(base_path, from_id)
+    output = io.StringIO()
+    with contextlib.redirect_stdout(output):
+        exit_code = _run_cli(
+            [
+                "run-reopen",
+                "--from", from_id,
+                "--stage", ns.stage,
+                "--reason", ns.reason,
+            ],
+            base_path,
+        )
+    cli_output = output.getvalue()
+    json_mode = is_json_mode()
+    if cli_output and (exit_code != 0 or not json_mode):
+        print(cli_output, end="" if cli_output.endswith("\n") else "\n")
+    if exit_code != 0:
+        sys.exit(exit_code)
+
+    new_work_id = _extract_cli_output_value(cli_output, "new_work_id")
+    if not new_work_id:
+        print("blocked: reopen_output_missing_new_work_id\n")
+        sys.exit(EXIT_CONFLICT)
+
+    write_active_pointer(base_path, new_work_id, reason="workflow_reopen")
+    selected_run = f".req-to-plan/{new_work_id}/run.md"
+    if json_mode:
+        payload: dict[str, object] = {}
+        stripped = cli_output.strip()
+        if stripped:
+            try:
+                parsed = json.loads(stripped)
+            except json.JSONDecodeError:
+                parsed = {}
+            if isinstance(parsed, dict):
+                payload.update(parsed)
+        payload["selected_work_id"] = new_work_id
+        payload["selected_run"] = selected_run
+        payload["next"] = "r2p-continue"
+        print(json.dumps(payload, indent=2))
+        sys.exit(0)
+
+    print(f"selected_run: {selected_run}\nnext: r2p-continue\n")
+    sys.exit(0)
+
+
+def _cmd_archive(ns: argparse.Namespace, base_path: Path) -> None:
+    work_id = ns.work_id
+    if not work_id:
+        pointer = read_active_pointer(base_path)
+        if not pointer:
+            print("no_selected_run: true\nnext: r2p-archive --work-id <id>\n")
+            sys.exit(1)
+        work_id = pointer["selected_work_id"]
+    work_id = _validate_work_id(work_id)
+    archive_args = ["run-archive", "--work-id", work_id]
+    if getattr(ns, "force", False):
+        archive_args.append("--force")
+    json_mode = is_json_mode()
+    cli_output = ""
+    if json_mode:
+        output = io.StringIO()
+        with contextlib.redirect_stdout(output):
+            exit_code = _run_cli(archive_args, base_path)
+        cli_output = output.getvalue()
+    else:
+        exit_code = _run_cli(archive_args, base_path)
+    if exit_code != 0:
+        if json_mode and cli_output:
+            print(cli_output, end="" if cli_output.endswith("\n") else "\n")
+        sys.exit(exit_code)
+    pointer = read_active_pointer(base_path)
+    if pointer and pointer.get("selected_work_id") == work_id:
+        _pointer_path(base_path).unlink(missing_ok=True)
+    if json_mode:
+        payload = _json_payload_from_cli_output(cli_output)
+        payload.setdefault("work_id", work_id)
+        payload["next"] = "r2p-status --all"
+        print(json.dumps(payload, indent=2))
+        sys.exit(0)
+    print(f"archived: {work_id}\nnext: r2p-status --all\n")
+    sys.exit(0)
+
+
+def _cmd_execute(ns: argparse.Namespace, base_path: Path) -> None:
+    work_id = ns.work_id
+    if not work_id:
+        pointer = read_active_pointer(base_path)
+        if not pointer:
+            print("no_selected_run: true\nnext: r2p-execute --work-id <id>\n")
+            sys.exit(1)
+        work_id = pointer["selected_work_id"]
+    work_id = _validate_work_id(work_id)
+    r2p_dir = base_path / ".req-to-plan"
+    run_dir = r2p_dir / work_id
+    if r2p_dir.is_symlink():
+        print(
+            "blocked: unsafe_workspace_dir_symlink\n"
+            f"work_id: {work_id}\n"
+            f"path: {r2p_dir}\n"
+        )
+        sys.exit(EXIT_CONFLICT)
+    if run_dir.is_symlink():
+        print(
+            "blocked: unsafe_run_dir_symlink\n"
+            f"work_id: {work_id}\n"
+            f"path: {run_dir}\n"
+        )
+        sys.exit(EXIT_CONFLICT)
+    run_path = run_dir / "run.md"
+    if not run_path.exists():
+        print(f"blocked: source_run_not_found\nwork_id: {work_id}\n")
+        sys.exit(7)
+
+    from tools.workflow_cli.state import RunStateManager
+    record = RunStateManager(run_dir).load()
+    plan = run_dir / "07-plan.md"
+    ledger = run_dir / "execution" / "progress.md"
+
+    if record.status == RunStatus.CLOSED_AT_PLAN_CHECKPOINT:
+        _ensure_workspace_gitignore_or_exit(base_path, work_id)
+        json_mode = is_json_mode()
+        cli_output = ""
+        if json_mode:
+            output = io.StringIO()
+            with contextlib.redirect_stdout(output):
+                code = _run_cli(["run-execute-start", "--work-id", work_id], base_path)
+            cli_output = output.getvalue()
+        else:
+            code = _run_cli(["run-execute-start", "--work-id", work_id], base_path)
+        if code != 0:
+            if json_mode and cli_output:
+                print(cli_output, end="" if cli_output.endswith("\n") else "\n")
+            sys.exit(code)
+        write_active_pointer(base_path, work_id, reason="execute_start")
+        next_step = (
+            "drive the r2p-execute skill (subagent-driven SDD loop) to "
+            "implement each PLAN-TASK in place on the current branch, then "
+            f"r2p-archive --work-id {work_id} when done"
+        )
+        if json_mode:
+            payload = _json_payload_from_cli_output(cli_output)
+            run_status = payload.get("status")
+            payload.update(
+                {
+                    "status": "stop",
+                    "reason": "execute_plan",
+                    "work_id": work_id,
+                    "plan": str(plan),
+                    "ledger": str(ledger),
+                    "next": next_step,
+                }
+            )
+            if isinstance(run_status, str):
+                payload["run_status"] = run_status
+            print(json.dumps(payload, indent=2))
+            sys.exit(0)
+        print(
+            "stop: execute_plan\n"
+            f"work_id: {work_id}\n"
+            f"plan: {plan}\n"
+            f"ledger: {ledger}\n"
+            f"next: {next_step}\n"
+        )
+        sys.exit(0)
+
+    if record.status == RunStatus.EXECUTING:
+        _ensure_workspace_gitignore_or_exit(base_path, work_id)
+        write_active_pointer(base_path, work_id, reason="execute_resume")
+        next_step = (
+            "resume the r2p-execute loop from the first unchecked task in "
+            f"the ledger, then r2p-archive --work-id {work_id} when done"
+        )
+        if is_json_mode():
+            print(
+                json.dumps(
+                    {
+                        "status": "stop",
+                        "reason": "resume_execution",
+                        "work_id": work_id,
+                        "run_status": record.status.value,
+                        "plan": str(plan),
+                        "ledger": str(ledger),
+                        "next": next_step,
+                    },
+                    indent=2,
+                )
+            )
+            sys.exit(0)
+        print(
+            "stop: resume_execution\n"
+            f"work_id: {work_id}\n"
+            f"plan: {plan}\n"
+            f"ledger: {ledger}\n"
+            f"next: {next_step}\n"
+        )
+        sys.exit(0)
+
+    print(f"blocked: plan_not_ready\nwork_id: {work_id}\nstatus: {record.status.value}\nnext: r2p-continue\n")
+    sys.exit(EXIT_CONFLICT)
 
 
 def _cmd_gap_open(ns: argparse.Namespace, base_path: Path) -> None:
@@ -789,6 +1054,10 @@ def _build_parser() -> argparse.ArgumentParser:
     p_reopen.add_argument("--stage", required=True)
     p_reopen.add_argument("--reason", required=True)
 
+    p_archive = sub.add_parser("archive")
+    p_archive.add_argument("--work-id", dest="work_id", default=None)
+    p_archive.add_argument("--force", action="store_true")
+
     p_tier_lock = sub.add_parser("tier-lock")
     p_tier_lock.add_argument("--work-id", dest="work_id", required=True)
     p_tier_lock.add_argument("--base", required=True, choices=["light", "standard"])
@@ -807,6 +1076,9 @@ def _build_parser() -> argparse.ArgumentParser:
     p_gap_resolve.add_argument("--route-id", dest="route_id", required=True)
     p_gap_resolve.add_argument("--confirm", action="store_true")
 
+    p_execute = sub.add_parser("execute")
+    p_execute.add_argument("--work-id", dest="work_id", default=None)
+
     return parser
 
 
@@ -827,9 +1099,11 @@ def main(args: list[str] | None = None, base_path: Path | None = None) -> None:
         "status": _cmd_status,
         "switch": _cmd_switch,
         "reopen": _cmd_reopen,
+        "archive": _cmd_archive,
         "tier-lock": _cmd_tier_lock,
         "gap-open": _cmd_gap_open,
         "gap-resolve": _cmd_gap_resolve,
+        "execute": _cmd_execute,
     }
     handlers[ns.subcommand](ns, bp)
     sys.exit(0)

package/tools/workflow_cli/agent_templates/claude/SKILL.md

@@ -18,7 +18,7 @@ Run each via Bash using the scripts in `{{R2P_BIN_DIR}}`:
 | `{{R2P_BIN_DIR}}/r2p-tier-lock --work-id <id> --base <light\|standard> --confirm` | Lock the tier for a run |
 | `{{R2P_BIN_DIR}}/r2p-status [--all]` | Inspect run state (read-only) |
 | `{{R2P_BIN_DIR}}/r2p-switch --work-id <id>` | Switch active run pointer |
-| `{{R2P_BIN_DIR}}/r2p-reopen --from <work-id> --stage <stage> --reason "<text>"` | Reopen a closed run |
+| `{{R2P_BIN_DIR}}/r2p-reopen --from <work-id> --stage <stage> --reason "<text>"` | Reopen a closed or executing run |
 | `{{R2P_BIN_DIR}}/r2p-gap-open --work-id <id> --owner-stage <stage> --required-action "<text>"` | Route an upstream gap back to its owner stage |
 | `{{R2P_BIN_DIR}}/r2p-gap-resolve --work-id <id> --route-id <route-id>` | Resolve an open upstream-gap route after the owner stage re-passes gate-quality |
 
@@ -34,4 +34,5 @@ Run each via Bash using the scripts in `{{R2P_BIN_DIR}}`:
    - Auto-closes: closes the run when the PLAN checkpoint is approved and no open routes remain
    - Does NOT auto-mark artifacts ready and does NOT auto-approve checkpoints — those are human steps
    - Standard-tier DESIGN: record any human technical choice in `## Decision Requests` as a `### DECISION-NNN` block (`Question:`/`Options:`/`Recommended:`/`Status: pending`); pending blocks `gate-quality` until a human selects (`Status: selected` + `Selected:`/`Rationale:`), or write exactly `none` when no decision is needed
+   - At a checkpoint, only approve a DESIGN/SPEC/PLAN artifact that has no unresolved ambiguity or undecided point: resolve it by evidence, or route it (DESIGN: `### DECISION-NNN`; SPEC/PLAN: `r2p-gap-open`) before approving.
 3. When the run closes, hand the approved PLAN at `07-plan.md` directly to your executor — the PLAN is executor-neutral and needs no adaptation step.

package/tools/workflow_cli/agent_templates/claude/commands/r2p-archive.md

@@ -0,0 +1,10 @@
+---
+description: Archive a closed or executing workflow run out of the active workspace
+---
+Run `{{R2P_BIN_DIR}}/r2p-archive` to archive the selected run, or pass a run explicitly.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-archive [--work-id <work-id>]`
+
+The run must be `closed_at_plan_checkpoint` or `executing`. On success, it moves `.req-to-plan/<work-id>` to `.req-to-plan/archive/<work-id>` and clears the active selection for that run.
+
+Use `{{R2P_BIN_DIR}}/r2p-status --all` afterward to inspect remaining active runs.

package/tools/workflow_cli/agent_templates/claude/commands/r2p-continue.md

@@ -10,6 +10,7 @@ Behavior:
 - Stops when human action is required: stage content generation, marking an artifact ready (`stage-ready`), Quality Gate failure or requested changes (repair), human checkpoint approval (`checkpoint-decide`), entry gate failure
 - Stops with `needs_subagent_review` on forced-review runs (a `migration`/`safety`/`cross_project` modifier at `design`/`spec`/`plan`) when the required review file is missing. You are authorized to run a read-only review subagent yourself for this step — no separate human approval is needed
 - Does NOT auto-mark artifacts ready and does NOT auto-approve checkpoints
+- At a checkpoint, only approve a DESIGN/SPEC/PLAN artifact that has no unresolved ambiguity or undecided point: resolve it by evidence, or route it (DESIGN: `### DECISION-NNN`; SPEC/PLAN: `r2p-gap-open`) before approving
 
 Call repeatedly until the output says `stop:` with a message indicating why the run paused. For `needs_content` and `needs_repair`, write the required artifact content into the printed `content_file`, then run the printed `next:` command exactly. For `needs_subagent_review`, run a review subagent to audit the stage artifact, write its findings to the printed `review_file`, then resume with `r2p-continue` (you do not need to ask for approval to spawn the review subagent). For other stops, run the printed `next:` command exactly. If an `alt:` command is shown, use it only when that alternate decision is intended. Resume with `r2p-continue` after completing that step.
 

package/tools/workflow_cli/agent_templates/claude/commands/r2p-execute.md

@@ -0,0 +1,122 @@
+---
+description: Execute a closed run's PLAN in place on the current branch via the subagent-driven SDD loop, then archive
+---
+
+# r2p-execute — SDD Execution Loop
+
+Execute each PLAN-TASK on the **current branch** using a fresh implementer subagent per task, a task-reviewer after each, and a whole-branch review at the end.
+
+**Subagents are a hard prerequisite.** If this platform cannot dispatch subagents, fail explicitly and let the human decide — never silently fall back to sequential execution.
+
+## Precondition Gate
+
+Run `{{R2P_BIN_DIR}}/r2p-execute` and read its stop output. On a `closed_at_plan_checkpoint` run it transitions the run to `executing` (via the `run-execute-start` CLI command) and stops with `execute_plan`; on an already-`executing` run it stops with `resume_execution`; on any other status it stops with `plan_not_ready`.
+
+- If the run status is `closed_at_plan_checkpoint` (first execution): the command transitions it to `executing` and returns the plan path.
+- If the run status is already `executing` (resume after interruption): proceed directly to the plan path.
+- Any other status → `plan_not_ready`. Stop and tell the user.
+
+## In-Place Execution (no branch)
+
+Work directly on the **current branch** — do NOT create a new branch, worktree, or protection boundary.
+
+Before task 1, run `git status --short -- ':!.req-to-plan'` to check the code working tree (excluding `.req-to-plan/` state). If there are uncommitted changes, stop before dispatching Task 1 and ask the user to clean, stash, or commit that work, or to explicitly identify which dirty paths belong to this execution and approve task-only staging. Do not commit unrelated work. `push` and PR creation are out of scope; request them explicitly from the user.
+
+## Pre-flight Plan Review
+
+Before dispatching Task 1, read `07-plan.md` once and scan for:
+- Tasks that contradict each other or the plan's Global Constraints
+- Items the plan mandates that the review rubric would treat as a defect
+
+Batch all findings into one question to the human **before** execution begins. If the scan is clean, proceed without comment.
+If a finding requires PLAN, SPEC, or DESIGN repair, stop and ask the human to reopen from the affected stage rather than patching over it in execution.
+
+## Per-Task Loop
+
+For each PLAN-TASK (in order):
+
+### 1. Extract task inline
+
+Read the task text directly from `07-plan.md`. Note the task's `Skeleton`, `Steps`, `Spec References`, and `Verification` criteria.
+
+### 2. Dispatch a fresh implementer subagent
+
+Provide the subagent with:
+- The task text (from `07-plan.md`)
+- Scene-setting context (project, dependencies, architectural constraints)
+- TDD instructions: follow `Skeleton`/`Steps`; prove `Verification` with evidence
+- A report file path (`execution/task-N-report.md`)
+
+The implementer must:
+1. Implement exactly what the task specifies, following TDD
+2. Satisfy the task's `Verification` criteria and attach evidence (test output, assertions)
+3. Commit the work, staging only files intentionally changed for this PLAN-TASK
+4. Self-review and report back
+
+### 3. Handle implementer status
+
+- **DONE / DONE_WITH_CONCERNS**: proceed to review
+- **NEEDS_CONTEXT**: the implementer needs missing information — provide it and re-dispatch the fresh implementer subagent
+- **BLOCKED**: assess the blocker; provide context, use a more capable model, or break the task into smaller pieces; escalate to the human if the plan itself is wrong
+
+### 4. Ambiguity ladder
+
+The fresh implementer subagent verifies-then-removes ambiguity by evidence and TDD. If it cannot resolve ambiguity:
+- Return `NEEDS_CONTEXT` or `BLOCKED` and escalate to the human — never guess a vague implementation
+- If the ambiguity is an upstream PLAN, SPEC, or DESIGN defect, stop and ask the human to choose an upstream repair path (for example, reopening from the affected stage) rather than patching over it in execution. Do not try to open a gap route from an `executing` run.
+
+### 5. Write diff and dispatch task-reviewer
+
+After the implementer reports DONE:
+1. Record the diff inline: `git diff -U10 <base-commit> HEAD` (no external script needed)
+2. Dispatch a task-reviewer subagent with:
+   - The task text and `Spec References` from `07-plan.md`
+   - The implementer's report
+   - The diff
+   - Global constraints from the plan
+
+The task-reviewer returns two verdicts:
+- **Spec compliance**: checked against `Spec References` + `Verification`
+- **Code quality**: clean, tested, maintainable
+
+### 6. Fix loop
+
+- Dispatch fix subagents for Critical and Important findings
+- Re-dispatch the task-reviewer after each fix wave
+- Only when the task-reviewer is clean (both spec ✅ and quality Approved, and `Verification` satisfied), update the matching `execution/progress.md` checkbox from `- [ ] PLAN-TASK-NNN ...` to `- [x] PLAN-TASK-NNN ...` and append one line:
+  `Task N: complete (commits <base7>..<head7>, review clean)`
+
+## Final Whole-Branch Review
+
+After all tasks complete, dispatch a final whole-branch review subagent:
+- Scope: all commits since the branch started (or since `closed_at_plan_checkpoint`)
+- Include the diff (`git diff -U10 <merge-base> HEAD`)
+- Dispatch fix subagents for any Critical/Important findings before marking done
+- This whole-branch review is the merge gate
+
+## Auto-Archive on Completion
+
+When all tasks are done and the final whole-branch review is clean, call:
+
+```
+{{R2P_BIN_DIR}}/r2p-archive --work-id <work_id from the precondition output>
+```
+
+Archiving is gated: `r2p-archive` refuses unless every PLAN-TASK from the PLAN is checked off (`- [x]`) in the ledger. Add `--force` only to archive an abandoned or superseded run.
+
+Commits are already on the **current branch**. `push` and PR creation still require an explicit user request.
+
+## Durable Progress
+
+Track progress in `execution/progress.md` (not only in todos). On resume, read the ledger and skip tasks already marked complete.
+
+## Error Reference
+
+| Condition | Action |
+|---|---|
+| Status not `closed_at_plan_checkpoint` or `executing` | Stop: `plan_not_ready` |
+| Implementer returns `NEEDS_CONTEXT` | Provide missing context, re-dispatch fresh implementer subagent |
+| Upstream PLAN/SPEC/DESIGN defect found | Stop: ask the human to reopen/repair the upstream stage |
+| Platform lacks subagent capability | Fail explicitly (subagents are a hard prerequisite) |
+
+Use `r2p-status` to inspect progress without making changes.

package/tools/workflow_cli/agent_templates/claude/commands/r2p-reopen.md

@@ -1,7 +1,7 @@
 ---
-description: Reopen a closed workflow run from a specific stage
+description: Reopen a closed or executing workflow run from a specific stage
 ---
-Run `{{R2P_BIN_DIR}}/r2p-reopen` to reopen a run that was closed at the PLAN checkpoint.
+Run `{{R2P_BIN_DIR}}/r2p-reopen` to reopen a run that was closed at the PLAN checkpoint or is already executing. On success, it selects the reopened run as the active run.
 
 Usage: `{{R2P_BIN_DIR}}/r2p-reopen --from <work-id> --stage <stage> --reason "<text>"`
 

package/tools/workflow_cli/agent_templates/codex/skills/r2p-archive/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: r2p-archive
+description: Use when the user asks to run r2p-archive, archive an r2p run, or move a closed or executing r2p workflow run out of the active workspace.
+---
+
+# r2p-archive
+
+Run `{{R2P_BIN_DIR}}/r2p-archive` to archive the selected run, or pass a run explicitly.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-archive [--work-id <work-id>]`
+
+The run must be `closed_at_plan_checkpoint` or `executing`. On success, it moves `.req-to-plan/<work-id>` to `.req-to-plan/archive/<work-id>` and clears the active selection for that run.
+
+Use `{{R2P_BIN_DIR}}/r2p-status --all` afterward to inspect remaining active runs.

package/tools/workflow_cli/agent_templates/codex/skills/r2p-continue/SKILL.md

@@ -9,4 +9,6 @@ Run `{{R2P_BIN_DIR}}/r2p-continue` to resume the currently selected run.
 
 Usage: `{{R2P_BIN_DIR}}/r2p-continue`
 
+At a checkpoint, only approve a DESIGN/SPEC/PLAN artifact that has no unresolved ambiguity or undecided point: resolve it by evidence, or route it (DESIGN: `### DECISION-NNN`; SPEC/PLAN: `r2p-gap-open`) before approving.
+
 Call repeatedly until the run reaches the closed state. For `needs_content` and `needs_repair` stops, write the required artifact content into the printed `content_file`, then run the printed `next:` command exactly. For a `needs_subagent_review` stop (forced-review runs: a `migration`/`safety`/`cross_project` modifier at `design`/`spec`/`plan`), run a read-only review subagent to audit the stage artifact yourself — no separate human approval is needed — write its findings to the printed `review_file`, then resume with `r2p-continue`. For other stops, run the printed `next:` command exactly. If an `alt:` command is shown, use it only when that alternate decision is intended. Use `r2p-status` to inspect progress.