@xenonbyte/req-2-plan 0.4.5 → 0.5.1

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

@@ -0,0 +1,123 @@
+---
+name: r2p-execute
+description: Execute a closed run's PLAN in place on the current branch via the subagent-driven SDD loop, then archive. Use when the user asks to run r2p-execute, execute the plan, start execution of the r2p run, or implement the PLAN tasks.
+---
+
+# 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 — one interrupt, not one per discovery. If the scan is clean, proceed without comment. The task-reviewer loop catches conflicts that only emerge from implementation.
+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`
+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`)
+- This whole-branch review is the merge gate
+- Dispatch fix subagents for any Critical/Important findings before marking done
+
+## 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/codex/skills/r2p-reopen/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: r2p-reopen
-description: Reopen a closed requirement-to-PLAN workflow run from a specific stage. Use when the user asks to run r2p-reopen or reopen an r2p run because an upstream stage needs repair.
+description: Reopen a closed or executing requirement-to-PLAN workflow run from a specific stage. Use when the user asks to run r2p-reopen or reopen an r2p run because an upstream stage needs repair.
 ---
 
 # r2p-reopen
 
-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/gemini/commands/r2p-archive.toml

@@ -0,0 +1,4 @@
+name = "r2p-archive"
+description = "Archive a closed or executing workflow run out of the active workspace"
+command = "{{R2P_BIN_DIR}}/r2p-archive"
+version = "{{R2P_VERSION}}"

package/tools/workflow_cli/agent_templates/gemini/commands/r2p-continue.toml

@@ -1,4 +1,4 @@
 name = "r2p-continue"
-description = "Continue the active requirement-to-PLAN workflow run"
+description = "Continue the active requirement-to-PLAN workflow run. At checkpoints, only approve DESIGN/SPEC/PLAN artifacts with no unresolved ambiguity or undecided point."
 command = "{{R2P_BIN_DIR}}/r2p-continue"
 version = "{{R2P_VERSION}}"

package/tools/workflow_cli/agent_templates/gemini/commands/r2p-execute.toml

@@ -0,0 +1,4 @@
+name = "r2p-execute"
+description = "Execute a closed run's PLAN in place on the current branch via the subagent-driven SDD loop, then archive. Implements each PLAN-TASK with a fresh implementer subagent + task review; subagents are required."
+command = "{{R2P_BIN_DIR}}/r2p-execute"
+version = "{{R2P_VERSION}}"

package/tools/workflow_cli/agent_templates/gemini/commands/r2p-reopen.toml

@@ -1,4 +1,4 @@
 name = "r2p-reopen"
-description = "Reopen a closed workflow run from a specific stage"
+description = "Reopen a closed or executing workflow run from a specific stage and select the reopened run"
 command = "{{R2P_BIN_DIR}}/r2p-reopen"
 version = "{{R2P_VERSION}}"

package/tools/workflow_cli/atomic.py

@@ -7,7 +7,12 @@ from pathlib import Path
 
 
 def atomic_write_text(path: Path, content: str, *, encoding: str = "utf-8") -> None:
-    """Write text via a unique sibling temp file, then atomically replace path."""
+    """Write text via a unique sibling temp file, then atomically replace path.
+
+    Guarantees atomic-replace semantics (a reader sees either the old or the new
+    file, never a truncated one). It does NOT fsync — durability across power
+    loss / crash is a deliberate non-goal for this CLI.
+    """
     tmp_path, fd = _open_unique_sibling_tmp(path)
     try:
         with os.fdopen(fd, "w", encoding=encoding) as tmp:

package/tools/workflow_cli/cli.py

@@ -42,7 +42,12 @@ from tools.workflow_cli.artifact import (
     get_artifact_version,
     update_artifact_status,
 )
-from tools.workflow_cli.gates import check_entry_gate, check_quality_gate, check_forced_subagent_review
+from tools.workflow_cli.gates import (
+    check_entry_gate,
+    check_quality_gate,
+    check_forced_subagent_review,
+    check_execution_complete,
+)
 from tools.workflow_cli.output import (
     format_success,
     format_error,
@@ -56,6 +61,9 @@ from tools.workflow_cli.output import (
     EXIT_NOT_FOUND,
 )
 from tools.workflow_cli.tier import estimate_tier, scan_keywords
+from tools.workflow_cli.workspace import ensure_workspace_gitignore, commit_requirement_dir
+from tools.workflow_cli.atomic import atomic_write_text
+from tools.workflow_cli.markdown import plan_task_anchors, strip_readonly_sections
 
 
 # ---------------------------------------------------------------------------
@@ -70,8 +78,13 @@ def _get_run_dir(work_id: str, base_path: Path | None = None) -> Path:
 
 
 def _load_run(work_id: str, base_path: Path | None = None):
-    """Load RunRecord; exit with EXIT_NOT_FOUND if not found."""
-    run_dir = _get_run_dir(work_id, base_path)
+    """Load RunRecord; exit with EXIT_NOT_FOUND if not found.
+
+    Rejects a symlinked workspace or run directory up front (EXIT_CONFLICT) so
+    no command — read-only or mutating — ever follows `.req-to-plan` or
+    `.req-to-plan/<id>` out of the workspace.
+    """
+    run_dir = _reject_symlinked_run_paths(work_id, base_path)
     mgr = RunStateManager(run_dir)
     try:
         return mgr.load(), mgr, run_dir
@@ -90,6 +103,32 @@ def _validate_work_id(raw: str) -> WorkId:
         print_and_exit(format_error(str(e), exit_code=EXIT_CLI_ERR), EXIT_CLI_ERR)
 
 
+def _ensure_workspace_gitignore_or_exit(base_path: Path) -> None:
+    try:
+        ensure_workspace_gitignore(base_path)
+    except ValueError as e:
+        print_and_exit(format_error(str(e), exit_code=EXIT_CONFLICT), EXIT_CONFLICT)
+
+
+def _reject_symlink_or_exit(path: Path, message: str) -> None:
+    if path.is_symlink():
+        print_and_exit(format_error(message, exit_code=EXIT_CONFLICT), EXIT_CONFLICT)
+
+
+def _reject_symlinked_run_paths(work_id, base_path: Path | None) -> Path:
+    """Reject a symlinked workspace or run directory, then return the run dir.
+
+    Guards `.req-to-plan` and `.req-to-plan/<id>` up front (EXIT_CONFLICT) so no
+    command — read-only or mutating — ever follows either out of the workspace.
+    Call before any filesystem mutation that targets the run dir.
+    """
+    root = base_path or Path.cwd()
+    _reject_symlink_or_exit(root / ".req-to-plan", "unsafe_workspace_dir_symlink")
+    run_dir = _get_run_dir(work_id, base_path)
+    _reject_symlink_or_exit(run_dir, f"Run directory is a symlink: {run_dir}")
+    return run_dir
+
+
 def _validate_repo_path(raw: str) -> Path:
     """Return a repo path only when it is an existing directory."""
     repo_path = Path(raw)
@@ -195,7 +234,7 @@ def _cmd_run_start(args):
             EXIT_CLI_ERR,
         )
     repo_path = _validate_repo_path(args.repo_path) if args.repo_path else None
-    run_dir = _get_run_dir(work_id, args.base_path)
+    run_dir = _reject_symlinked_run_paths(work_id, args.base_path)
     mgr = RunStateManager(run_dir)
 
     run_dir_occupied = False
@@ -371,6 +410,8 @@ def _cmd_run_close(args):
             ),
             EXIT_CONFLICT,
         )
+    base = args.base_path or Path.cwd()
+    _ensure_workspace_gitignore_or_exit(base)
     try:
         record = update_run_status(record, RunStatus.CLOSED_AT_PLAN_CHECKPOINT)
     except ValueError as e:
@@ -378,6 +419,13 @@ def _cmd_run_close(args):
     record.current_stage = Stage.CLOSED
     update_resume_context(record, last_operation="close_at_plan_checkpoint")
     mgr.save(record)
+    # PLAN complete → land the requirement directory in version control
+    # (best-effort, path-limited; never touches unrelated changes). spec §4.5
+    commit_requirement_dir(
+        base,
+        str(record.work_id),
+        f"chore(r2p): plan {record.work_id}",
+    )
     print_and_exit(
         format_success({"work_id": str(record.work_id), "status": record.status.value}, message="Run closed"),
         EXIT_OK,
@@ -388,22 +436,17 @@ def _cmd_run_reopen(args):
     source_id = str(_validate_work_id(args.from_id))
     target_stage = _parse_reopen_stage(args.stage)
 
-    # Load source run
-    source_dir = _get_run_dir(source_id, args.base_path)
-    source_mgr = RunStateManager(source_dir)
-    try:
-        source_record = source_mgr.load()
-    except FileNotFoundError:
-        print_and_exit(
-            format_error(f"Source run not found: {source_id}", exit_code=EXIT_NOT_FOUND),
-            EXIT_NOT_FOUND,
-        )
+    # Load source run through the shared guard so reopen cannot follow a
+    # symlinked .req-to-plan/<work-id> outside the workspace.
+    source_record, source_mgr, source_dir = _load_run(source_id, args.base_path)
 
-    if source_record.status != RunStatus.CLOSED_AT_PLAN_CHECKPOINT:
+    reopenable_statuses = {RunStatus.CLOSED_AT_PLAN_CHECKPOINT, RunStatus.EXECUTING}
+    if source_record.status not in reopenable_statuses:
         print_and_exit(
             format_error(
-                f"Source run {source_id!r} is not CLOSED_AT_PLAN_CHECKPOINT "
-                f"(status={source_record.status.value!r})",
+                f"Source run {source_id!r} is not reopenable "
+                f"(status={source_record.status.value!r}); must be "
+                "closed_at_plan_checkpoint or executing",
                 exit_code=EXIT_CONFLICT,
             ),
             EXIT_CONFLICT,
@@ -428,7 +471,8 @@ def _cmd_run_reopen(args):
         except ValueError as e:
             print_and_exit(format_error(str(e), exit_code=EXIT_CLI_ERR), EXIT_CLI_ERR)
         candidate_dir = _get_run_dir(candidate, args.base_path)
-        if not candidate_dir.exists():
+        candidate_archive_dir = (args.base_path or Path.cwd()) / ".req-to-plan" / "archive" / candidate
+        if not candidate_dir.exists() and not candidate_archive_dir.exists():
             new_work_id = candidate_work_id
             new_work_id_str = candidate
             new_run_dir = candidate_dir
@@ -463,7 +507,12 @@ def _cmd_run_reopen(args):
     new_record = create_run_record(new_work_id)
     new_record.tier_estimate = source_record.tier_estimate
     new_record.tier_locked = source_record.tier_locked
-    new_record.reopen_lineage = f"reopened_from: {source_id}@plan_checkpoint reason: {args.reason}"
+    source_phase = (
+        "execution"
+        if source_record.status == RunStatus.EXECUTING
+        else "plan_checkpoint"
+    )
+    new_record.reopen_lineage = f"reopened_from: {source_id}@{source_phase} reason: {args.reason}"
     new_record.current_stage = target_stage
 
     # Copy approved checkpoints before target stage
@@ -476,6 +525,9 @@ def _cmd_run_reopen(args):
     # Repopulate active_artifacts for copied stages so the reopened record
     # matches the on-disk artifacts and approved checkpoints.
     for cp in new_record.approved_checkpoints:
+        # Invariant: cp.artifact == STAGE_ARTIFACT_MAP[cp.stage] (artifacts are
+        # only ever created via the map, artifact.py:23). The existence check and
+        # the recorded name are therefore interchangeable; no drift path exists.
         artifact_name = STAGE_ARTIFACT_MAP.get(cp.stage)
         if artifact_name and (new_run_dir / artifact_name).exists():
             upsert_active_artifact(
@@ -489,6 +541,19 @@ def _cmd_run_reopen(args):
     new_mgr = RunStateManager(new_run_dir)
     new_mgr.save(new_record)
 
+    if source_record.status == RunStatus.EXECUTING:
+        try:
+            source_record = update_run_status(source_record, RunStatus.CLOSED_AT_PLAN_CHECKPOINT)
+        except ValueError as e:
+            print_and_exit(format_error(str(e), exit_code=EXIT_CONFLICT), EXIT_CONFLICT)
+        source_record.current_stage = Stage.CLOSED
+        update_resume_context(
+            source_record,
+            last_operation="reopen_from_execution",
+            next_operation=f"continue_reopened_run:{new_work_id}",
+        )
+        source_mgr.save(source_record)
+
     print_and_exit(
         format_success(
             {
@@ -503,6 +568,126 @@ def _cmd_run_reopen(args):
     )
 
 
+def _cmd_run_archive(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+    base = args.base_path or Path.cwd()
+    archivable = {RunStatus.CLOSED_AT_PLAN_CHECKPOINT, RunStatus.EXECUTING}
+    if record.status not in archivable:
+        print_and_exit(
+            format_error(
+                f"Cannot archive run in status {record.status.value!r}; "
+                "must be closed_at_plan_checkpoint or executing",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    # 0. Completion gate: an executing run must show every PLAN-TASK done in its
+    # ledger before it can be archived. --force overrides (abandoned/superseded run).
+    if record.status == RunStatus.EXECUTING and not args.force:
+        gate = check_execution_complete(run_dir)
+        if not gate.passed:
+            detail = " ".join(gate.issues)
+            print_and_exit(
+                format_error(
+                    f"Execution incomplete: {detail} "
+                    "Re-run with --force to archive an unfinished run.",
+                    exit_code=gate.exit_code,
+                ),
+                gate.exit_code,
+            )
+    # 1. Refuse to clobber an existing archived copy before mutating state.
+    archive_dir = base / ".req-to-plan" / "archive" / str(record.work_id)
+    if archive_dir.exists():
+        print_and_exit(
+            format_error(
+                f"Archive target already exists: {archive_dir}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    # 2. Ensure /archive is ignored before anything lands under it.
+    _ensure_workspace_gitignore_or_exit(base)
+    # 3. Build the archived record, but do not persist it until the move succeeds.
+    try:
+        archived_record = update_run_status(record, RunStatus.ARCHIVED)
+    except ValueError as e:
+        print_and_exit(format_error(str(e), exit_code=EXIT_CONFLICT), EXIT_CONFLICT)
+    _reject_symlink_or_exit(archive_dir.parent, f"Archive parent is a symlink: {archive_dir.parent}")
+    archive_dir.parent.mkdir(parents=True, exist_ok=True)
+    # 4. Move the run dir into the (ignored) archive, then persist ARCHIVED there.
+    shutil.move(str(run_dir), str(archive_dir))
+    try:
+        RunStateManager(archive_dir).save(archived_record)
+    except Exception:
+        if archive_dir.exists() and not run_dir.exists():
+            shutil.move(str(archive_dir), str(run_dir))
+        raise
+    # 5. Commit the removal of the original path (untracks the dir). spec §4.6
+    commit_requirement_dir(
+        base, str(archived_record.work_id), f"chore(r2p): archive {archived_record.work_id}"
+    )
+    print_and_exit(
+        format_success(
+            {"work_id": str(archived_record.work_id), "status": "archived", "archived_to": str(archive_dir)},
+            message=f"Run archived: {archived_record.work_id}",
+        ),
+        EXIT_OK,
+    )
+
+
+def _cmd_run_execute_start(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+    if record.status != RunStatus.CLOSED_AT_PLAN_CHECKPOINT:
+        print_and_exit(
+            format_error(
+                f"Cannot start execution in status {record.status.value!r}; "
+                "must be closed_at_plan_checkpoint (plan_not_ready)",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    try:
+        plan_text = read_artifact(run_dir, Stage.PLAN)
+    except FileNotFoundError:
+        print_and_exit(
+            format_error("PLAN artifact not found; cannot start execution", exit_code=EXIT_NOT_FOUND),
+            EXIT_NOT_FOUND,
+        )
+    # Seed the structural progress ledger (IDs + checkboxes = structure, not
+    # semantics; the agent appends progress). CLI never generates artifact text.
+    anchors = plan_task_anchors(strip_readonly_sections(plan_text))
+    if not anchors:
+        print_and_exit(
+            format_error(
+                "PLAN contains no PLAN-TASK anchors; repair PLAN with "
+                "### PLAN-TASK-NNN headings before execution",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    lines = ["# Execution Progress", "", f"work_id: {record.work_id}", ""]
+    lines += [f"- [ ] {tid} {title}".rstrip() for tid, title in anchors]
+    exec_dir = run_dir / "execution"
+    _reject_symlink_or_exit(exec_dir, "unsafe_execution_dir_symlink")
+    exec_dir.mkdir(parents=True, exist_ok=True)
+    atomic_write_text(exec_dir / "progress.md", "\n".join(lines) + "\n")
+    record = update_run_status(record, RunStatus.EXECUTING)
+    update_resume_context(record, last_operation="execute_start", next_operation="implement_tasks")
+    mgr.save(record)
+    print_and_exit(
+        format_success(
+            {
+                "work_id": str(record.work_id),
+                "status": record.status.value,
+                "ledger": str(exec_dir / "progress.md"),
+                "task_count": len(anchors),
+            },
+            message=f"Execution started: {record.work_id}",
+        ),
+        EXIT_OK,
+    )
+
+
 def _cmd_gap_resolve(args):
     record, mgr, run_dir = _load_run(args.work_id, args.base_path)
     route = next(
@@ -1367,12 +1552,30 @@ def _register_run_commands(subparsers):
     p.set_defaults(func=_cmd_run_close)
 
     # run-reopen
-    p = subparsers.add_parser("run-reopen", help="Reopen a closed workflow run")
+    p = subparsers.add_parser(
+        "run-reopen",
+        help="Reopen a closed or executing workflow run",
+    )
     p.add_argument("--from", dest="from_id", required=True, help="Source work-id to reopen from")
     p.add_argument("--stage", required=True, help="Target stage to reopen at")
     p.add_argument("--reason", required=True, help="Reason for reopening")
     p.set_defaults(func=_cmd_run_reopen)
 
+    # run-archive
+    p = subparsers.add_parser("run-archive", help="Archive a closed run out of the active workspace")
+    p.add_argument("--work-id", required=True)
+    p.add_argument(
+        "--force",
+        action="store_true",
+        help="Archive an executing run even if its execution ledger is missing or has unfinished tasks",
+    )
+    p.set_defaults(func=_cmd_run_archive)
+
+    # run-execute-start
+    p = subparsers.add_parser("run-execute-start", help="Begin executing a closed run's PLAN in place")
+    p.add_argument("--work-id", required=True)
+    p.set_defaults(func=_cmd_run_execute_start)
+
 
 def _register_tier_commands(subparsers):
     # tier-estimate
@@ -1808,7 +2011,7 @@ def _cmd_context_build(args):
     from tools.workflow_cli.context_pack import build_context_pack, write_context_pack
 
     work_id = str(_validate_work_id(args.work_id))
-    run_dir = _get_run_dir(work_id, args.base_path)
+    run_dir = _reject_symlinked_run_paths(work_id, args.base_path)
     if not run_dir.exists():
         print_and_exit(
             format_error(f"run not found: {work_id}", exit_code=EXIT_NOT_FOUND),