@xenonbyte/req-2-plan 0.2.3

package/tools/workflow_cli/cli.py

@@ -0,0 +1,1779 @@
+"""
+req-to-plan workflow CLI — internal Agent command router.
+
+Usage:
+    python3 -m tools.workflow_cli [--base-path <dir>] <command> [options]
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+import sys
+from pathlib import Path
+
+from tools.workflow_cli.models import (
+    RunStatus,
+    Stage,
+    TierBase,
+    TierModifier,
+    WorkId,
+    STAGE_ARTIFACT_MAP,
+    STAGE_ORDER,
+    is_command_allowed,
+    is_transition_allowed,
+)
+from tools.workflow_cli.state import (
+    RunStateManager,
+    create_run_record,
+    update_run_status,
+    upsert_active_artifact,
+    update_resume_context,
+    get_active_artifact,
+    add_checkpoint,
+    add_open_route,
+    close_route,
+    record_stale_artifact,
+)
+from tools.workflow_cli.artifact import (
+    ArtifactManager,
+    write_artifact,
+    read_artifact,
+    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.output import (
+    format_success,
+    format_error,
+    format_gate_result,
+    print_and_exit,
+    EXIT_OK,
+    EXIT_CLI_ERR,
+    EXIT_GATE_FAIL,
+    EXIT_REVIEW_REQ,
+    EXIT_CONFLICT,
+    EXIT_NOT_FOUND,
+)
+from tools.workflow_cli.tier import estimate_tier, scan_keywords
+
+
+# ---------------------------------------------------------------------------
+# Path helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_run_dir(work_id: str, base_path: Path | None = None) -> Path:
+    root = base_path or Path.cwd()
+    valid_work_id = _validate_work_id(str(work_id))
+    return root / ".req-to-plan" / str(valid_work_id)
+
+
+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)
+    mgr = RunStateManager(run_dir)
+    try:
+        return mgr.load(), mgr, run_dir
+    except FileNotFoundError:
+        print_and_exit(
+            format_error(f"Run not found: {work_id}", exit_code=EXIT_NOT_FOUND),
+            EXIT_NOT_FOUND,
+        )
+
+
+def _validate_work_id(raw: str) -> WorkId:
+    """Parse WorkId or exit with CLI error."""
+    try:
+        return WorkId(raw)
+    except ValueError as e:
+        print_and_exit(format_error(str(e), exit_code=EXIT_CLI_ERR), EXIT_CLI_ERR)
+
+
+def _parse_stage(raw: str) -> Stage:
+    """Parse Stage enum or exit with CLI error."""
+    try:
+        return Stage(raw)
+    except ValueError:
+        valid = [s.value for s in Stage]
+        print_and_exit(
+            format_error(f"Unknown stage {raw!r}. Valid: {valid}", exit_code=EXIT_CLI_ERR),
+            EXIT_CLI_ERR,
+        )
+
+
+def _parse_reopen_stage(raw: str) -> Stage:
+    """Parse a stage that can be used as the active target of a reopened run."""
+    stage = _parse_stage(raw)
+    if stage not in STAGE_ORDER:
+        valid = [s.value for s in STAGE_ORDER]
+        print_and_exit(
+            format_error(
+                f"Stage {raw!r} cannot be reopened into. Valid: {valid}",
+                exit_code=EXIT_CLI_ERR,
+            ),
+            EXIT_CLI_ERR,
+        )
+    return stage
+
+
+def _parse_tier_base(raw: str) -> TierBase:
+    """Parse TierBase enum or exit with CLI error."""
+    try:
+        return TierBase(raw)
+    except ValueError:
+        valid = [b.value for b in TierBase]
+        print_and_exit(
+            format_error(f"Unknown tier base {raw!r}. Valid: {valid}", exit_code=EXIT_CLI_ERR),
+            EXIT_CLI_ERR,
+        )
+
+
+def _parse_modifiers(raw: str | None) -> frozenset[TierModifier]:
+    """Parse comma-separated modifier list or return empty set."""
+    if not raw:
+        return frozenset()
+    mods: list[TierModifier] = []
+    for part in raw.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        try:
+            mods.append(TierModifier(part))
+        except ValueError:
+            valid = [m.value for m in TierModifier]
+            print_and_exit(
+                format_error(f"Unknown modifier {part!r}. Valid: {valid}", exit_code=EXIT_CLI_ERR),
+                EXIT_CLI_ERR,
+            )
+    return frozenset(mods)
+
+
+# ---------------------------------------------------------------------------
+# Run lifecycle commands
+# ---------------------------------------------------------------------------
+
+
+def _read_requirement_arg(args) -> str:
+    """Return the raw requirement text from --requirement or --requirement-file.
+
+    --requirement-file reads the file's contents (deterministic input ingestion).
+    A missing file fails loudly with EXIT_CLI_ERR rather than silently falling back.
+    """
+    req_file = getattr(args, "requirement_file", None)
+    if req_file:
+        path = Path(req_file)
+        if not path.is_file():
+            print_and_exit(
+                format_error(f"Requirement file not found: {req_file}", exit_code=EXIT_CLI_ERR),
+                EXIT_CLI_ERR,
+            )
+        return path.read_text(encoding="utf-8")
+    return args.requirement or ""
+
+
+def _cmd_run_start(args):
+    work_id = _validate_work_id(args.work_id)
+    requirement = _read_requirement_arg(args)
+    if not requirement.strip():
+        print_and_exit(
+            format_error("Requirement must not be blank", exit_code=EXIT_CLI_ERR),
+            EXIT_CLI_ERR,
+        )
+    run_dir = _get_run_dir(work_id, args.base_path)
+    mgr = RunStateManager(run_dir)
+
+    run_dir_occupied = False
+    if run_dir.exists():
+        run_dir_occupied = (
+            True
+            if run_dir.is_symlink() or not run_dir.is_dir()
+            else any(run_dir.iterdir())
+        )
+
+    if run_dir_occupied and not getattr(args, "overwrite", False):
+        print_and_exit(
+            format_error(
+                f"Run {work_id!r} already exists. Use --overwrite to reset or choose a different --work-id.",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    if run_dir_occupied and getattr(args, "overwrite", False):
+        if run_dir.is_symlink() or run_dir.is_file():
+            run_dir.unlink()
+        else:
+            shutil.rmtree(run_dir)
+
+    # Create run record
+    record = create_run_record(work_id)
+
+    # Write raw requirement artifact
+    run_dir.mkdir(parents=True, exist_ok=True)
+    write_artifact(run_dir, Stage.RAW_REQUIREMENT, requirement, version=1, status="draft")
+
+    # Tier estimation
+    repo_path = Path(args.repo_path) if args.repo_path else None
+    tier_estimate, evidence = estimate_tier(requirement, repo_path=repo_path)
+    record.tier_estimate = tier_estimate
+
+    # Update active artifacts in record
+    artifact_file = STAGE_ARTIFACT_MAP[Stage.RAW_REQUIREMENT]
+    upsert_active_artifact(record, Stage.RAW_REQUIREMENT, artifact_file, 1, "draft")
+
+    # Write intake brief (01-intake-brief.md) with evidence block
+    brief_lines = [
+        "# Intake Brief",
+        "",
+        f"work_id: {work_id}",
+        f"requirement: {requirement}",
+        "",
+        "## Tier Estimate",
+        f"base: {tier_estimate.base.value}",
+        f"modifiers: {', '.join(sorted(m.value for m in tier_estimate.modifiers))}",
+        "",
+        "## Evidence Block",
+        f"keywords_hit: {evidence.keywords_hit or []}",
+        f"repo_baseline_summary: {evidence.repo_baseline_summary}",
+        f"linked_context: {evidence.linked_context}",
+        f"scope_signals: {evidence.scope_signals or []}",
+        f"escalation_candidates: {evidence.escalation_candidates or []}",
+        f"confirm_status: {evidence.confirm_status}",
+    ]
+    (run_dir / "01-intake-brief.md").write_text("\n".join(brief_lines), encoding="utf-8")
+
+    # Save run record
+    mgr.save(record)
+
+    print_and_exit(
+        format_success(
+            {
+                "work_id": str(work_id),
+                "tier_floor": tier_estimate.base.value,
+                "modifiers": sorted(m.value for m in tier_estimate.modifiers),
+                "run_dir": str(run_dir),
+            },
+            message=f"Run started: {work_id}",
+        ),
+        EXIT_OK,
+    )
+
+
+def _cmd_run_resume(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+    rc = record.resume_context
+    print_and_exit(
+        format_success(
+            {
+                "work_id": record.work_id,
+                "status": record.status.value,
+                "current_stage": record.current_stage.value,
+                "last_operation": rc.last_completed_operation,
+                "next_operation": rc.next_allowed_operation,
+                "active_item": rc.active_item,
+                "resume_reason": rc.resume_reason,
+            },
+            message="Resume context",
+        ),
+        EXIT_OK,
+    )
+
+
+def _cmd_run_close(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+    if record.status != RunStatus.CHECKPOINT_APPROVED:
+        print_and_exit(
+            format_error(
+                f"Cannot close run in status {record.status.value!r}; "
+                "must be in checkpoint_approved",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    if record.current_stage != Stage.PLAN:
+        print_and_exit(
+            format_error(
+                f"Cannot close run at stage {record.current_stage.value!r}; "
+                "current stage must be plan",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    aa = get_active_artifact(record, Stage.PLAN)
+    if aa is None or aa.status != "approved":
+        print_and_exit(
+            format_error("PLAN active artifact must be approved before run-close", exit_code=EXIT_CONFLICT),
+            EXIT_CONFLICT,
+        )
+    disk_version = get_artifact_version(run_dir, Stage.PLAN)
+    if disk_version != aa.version:
+        print_and_exit(
+            format_error(
+                f"Active artifact version v{aa.version} does not match on-disk v{disk_version}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    has_matching_plan_checkpoint = any(
+        cp.stage == Stage.PLAN
+        and cp.artifact == aa.artifact
+        and cp.version == aa.version
+        for cp in record.approved_checkpoints
+    )
+    if not has_matching_plan_checkpoint:
+        print_and_exit(
+            format_error(
+                f"No approved PLAN checkpoint matching {aa.artifact} v{aa.version}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    open_routes = [r.route_id for r in record.open_routes if r.status == "open"]
+    if open_routes:
+        print_and_exit(
+            format_error(
+                "Cannot close run while routes remain open",
+                details=open_routes,
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    try:
+        record = update_run_status(record, RunStatus.CLOSED_AT_PLAN_CHECKPOINT)
+    except ValueError as e:
+        print_and_exit(format_error(str(e), exit_code=EXIT_CONFLICT), EXIT_CONFLICT)
+    record.current_stage = Stage.CLOSED
+    update_resume_context(record, last_operation="close_at_plan_checkpoint")
+    mgr.save(record)
+    print_and_exit(
+        format_success({"work_id": str(record.work_id), "status": record.status.value}, message="Run closed"),
+        EXIT_OK,
+    )
+
+
+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,
+        )
+
+    if source_record.status != RunStatus.CLOSED_AT_PLAN_CHECKPOINT:
+        print_and_exit(
+            format_error(
+                f"Source run {source_id!r} is not CLOSED_AT_PLAN_CHECKPOINT "
+                f"(status={source_record.status.value!r})",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    # Determine new work_id suffix: -r1, -r2, etc.
+    base = source_id
+    suffix = 1
+    # Remove existing -rN suffix from base if present
+    m = re.match(r"^(WF-\d{8}-.+?)-r(\d+)$", source_id)
+    if m:
+        base = m.group(1)
+        suffix = int(m.group(2)) + 1
+
+    new_work_id = None
+    new_work_id_str = ""
+    new_run_dir = None
+    for candidate_suffix in range(suffix, 100):
+        candidate = f"{base}-r{candidate_suffix}"
+        try:
+            candidate_work_id = WorkId(candidate)
+        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():
+            new_work_id = candidate_work_id
+            new_work_id_str = candidate
+            new_run_dir = candidate_dir
+            break
+    if new_work_id is None or new_run_dir is None:
+        print_and_exit(
+            format_error(
+                f"Could not find an unused reopen work ID for {source_id!r}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    new_run_dir.mkdir(parents=True, exist_ok=False)
+
+    # Copy artifacts up to (not including) target_stage
+    import shutil
+    for stage in STAGE_ORDER:
+        if stage == target_stage:
+            break
+        artifact_file = STAGE_ARTIFACT_MAP.get(stage)
+        if artifact_file:
+            src_path = source_dir / artifact_file
+            if src_path.exists():
+                shutil.copy2(src_path, new_run_dir / artifact_file)
+
+    # Create new run record
+    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}"
+    new_record.current_stage = target_stage
+
+    # Copy approved checkpoints before target stage
+    for cp in source_record.approved_checkpoints:
+        cp_stage_idx = STAGE_ORDER.index(cp.stage) if cp.stage in STAGE_ORDER else -1
+        target_idx = STAGE_ORDER.index(target_stage) if target_stage in STAGE_ORDER else 999
+        if cp_stage_idx < target_idx:
+            new_record.approved_checkpoints.append(cp)
+
+    new_mgr = RunStateManager(new_run_dir)
+    new_mgr.save(new_record)
+
+    print_and_exit(
+        format_success(
+            {
+                "new_work_id": str(new_work_id),
+                "source_work_id": source_id,
+                "target_stage": target_stage.value,
+                "run_dir": str(new_run_dir),
+            },
+            message=f"Run reopened as {new_work_id}",
+        ),
+        EXIT_OK,
+    )
+
+
+def _cmd_gap_resolve(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+    route = next(
+        (r for r in record.open_routes if r.route_id == args.route_id and r.status == "open"),
+        None,
+    )
+    if route is None:
+        print_and_exit(
+            format_error(f"No open route with id {args.route_id!r}", exit_code=EXIT_NOT_FOUND),
+            EXIT_NOT_FOUND,
+        )
+    owner = route.owner_stage
+    aa = get_active_artifact(record, owner)
+    checkpoint_ready_statuses = {
+        RunStatus.READY_FOR_CHECKPOINT_REVIEW,
+        RunStatus.CHECKPOINT_REVIEW,
+    }
+    if aa is None or aa.status != "ready" or record.status not in checkpoint_ready_statuses:
+        print_and_exit(
+            format_error(
+                f"Owner stage {owner.value!r} must pass gate-quality before resolving the route",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    close_route(record, args.route_id)
+    next_operation = (
+        "checkpoint_decide"
+        if record.status == RunStatus.CHECKPOINT_REVIEW
+        else "checkpoint_review"
+    )
+    update_resume_context(
+        record, last_operation=f"gap_resolve_{args.route_id}",
+        next_operation=next_operation, active_item=owner.value,
+        reason=f"owner repaired for {args.route_id}; resume checkpoint approval",
+    )
+    mgr.save(record)
+    print_and_exit(
+        format_success(
+            {"route_id": args.route_id, "status": "repaired", "owner_stage": owner.value,
+             "resume_from": owner.value},
+            message=f"Route {args.route_id} resolved; continue owner checkpoint approval",
+        ),
+        EXIT_OK,
+    )
+
+
+def _cmd_gap_open(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+    owner = _parse_stage(args.owner_stage)
+
+    if record.status == RunStatus.CLOSED_AT_PLAN_CHECKPOINT:
+        print_and_exit(
+            format_error("Cannot gap-open a closed run; use run-reopen", exit_code=EXIT_CONFLICT),
+            EXIT_CONFLICT,
+        )
+    if not args.required_action or not args.required_action.strip():
+        print_and_exit(
+            format_error("--required-action must be non-empty", exit_code=EXIT_CLI_ERR),
+            EXIT_CLI_ERR,
+        )
+    if "\n" in args.required_action or "\r" in args.required_action:
+        print_and_exit(
+            format_error("--required-action must be a single line", exit_code=EXIT_CLI_ERR),
+            EXIT_CLI_ERR,
+        )
+
+    cur = record.current_stage
+    if owner not in STAGE_ORDER or cur not in STAGE_ORDER:
+        print_and_exit(
+            format_error(f"Stage {owner.value!r} not in stage order", exit_code=EXIT_CONFLICT),
+            EXIT_CONFLICT,
+        )
+    if STAGE_ORDER.index(owner) >= STAGE_ORDER.index(cur):
+        print_and_exit(
+            format_error(
+                f"owner-stage {owner.value!r} must be strictly upstream of current stage {cur.value!r}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    if not is_transition_allowed(record.status, RunStatus.UPSTREAM_GAP_ROUTING):
+        print_and_exit(
+            format_error(
+                f"Cannot route a gap from status {record.status.value!r}; resolve the current step first",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    open_route_ids = [r.route_id for r in record.open_routes if r.status == "open"]
+    if open_route_ids:
+        print_and_exit(
+            format_error(
+                "Cannot gap-open while another route is open; resolve it before opening a new route",
+                details=open_route_ids,
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    run_md_path = run_dir / "run.md"
+    run_md_before = run_md_path.read_text(encoding="utf-8")
+    affected = []
+    for d in STAGE_ORDER[STAGE_ORDER.index(owner): STAGE_ORDER.index(cur) + 1]:
+        aa = get_active_artifact(record, d)
+        cp = next(
+            (checkpoint for checkpoint in record.approved_checkpoints if checkpoint.stage == d),
+            None,
+        )
+        artifact_file = STAGE_ARTIFACT_MAP[d]
+        artifact_path = run_dir / artifact_file
+        if aa is None and cp is None and not artifact_path.exists():
+            continue
+        version = aa.version if aa is not None else (
+            cp.version if cp is not None else get_artifact_version(run_dir, d)
+        )
+        if not artifact_path.exists():
+            print_and_exit(
+                format_error(
+                    f"Cannot gap-open: downstream artifact file missing for {d.value!r}: {artifact_file}",
+                    exit_code=EXIT_NOT_FOUND,
+                ),
+                EXIT_NOT_FOUND,
+            )
+        affected.append(
+            (
+                d,
+                version,
+                artifact_file,
+                artifact_path,
+                artifact_path.read_text(encoding="utf-8"),
+            )
+        )
+
+    route_id = f"R-{len(record.open_routes) + 1}"
+    am = ArtifactManager(run_dir)
+    reason = f"upstream gap at {owner.value}"
+    staled = []
+    try:
+        add_open_route(record, route_id, from_stage=cur, owner_stage=owner, required_action=args.required_action)
+        for d, version, artifact_file, _artifact_path, _artifact_before in affected:
+            record_stale_artifact(
+                record, artifact=artifact_file, reason=reason,
+                replaced_by="(pending re-derivation)", required_action=route_id,
+            )
+            am.mark_stale(d, reason, "(pending re-derivation)")
+            upsert_active_artifact(record, d, artifact_file, version, "stale")
+            record.approved_checkpoints = [cp for cp in record.approved_checkpoints if cp.stage != d]
+            staled.append(d.value)
+
+        record.current_stage = owner
+        record = update_run_status(record, RunStatus.UPSTREAM_GAP_ROUTING)
+        record = update_run_status(record, RunStatus.ACTIVE_STAGE_DRAFT)
+        update_resume_context(
+            record, last_operation=f"gap_open_{route_id}",
+            next_operation="stage_update", active_item=owner.value,
+            reason=f"repair owner for {route_id}",
+        )
+        mgr.save(record)
+    except Exception as e:
+        run_md_path.write_text(run_md_before, encoding="utf-8")
+        for _d, _aa, _artifact_file, artifact_path, artifact_before in reversed(affected):
+            artifact_path.write_text(artifact_before, encoding="utf-8")
+        print_and_exit(
+            format_error(
+                f"Cannot gap-open: failed to mark downstream stale atomically ({e})",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    print_and_exit(
+        format_success(
+            {"route_id": route_id, "owner_stage": owner.value, "from_stage": cur.value, "staled_stages": staled},
+            message=f"Gap routed to {owner.value}; repair it, then gap-resolve --route-id {route_id}",
+        ),
+        EXIT_OK,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tier commands
+# ---------------------------------------------------------------------------
+
+
+def _cmd_tier_estimate(args):
+    repo_path = Path(args.repo_path) if args.repo_path else None
+    tier, evidence = estimate_tier(args.text, repo_path=repo_path)
+    print_and_exit(
+        format_success(
+            {
+                "tier_base": tier.base.value,
+                "modifiers": sorted(m.value for m in tier.modifiers),
+                "keywords_hit": evidence.keywords_hit or [],
+                "repo_summary": evidence.repo_baseline_summary,
+                "confirm_status": evidence.confirm_status,
+            },
+            message=f"Tier estimate: {tier.base.value}",
+        ),
+        EXIT_OK,
+    )
+
+
+def _cmd_tier_lock(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+
+    if not is_command_allowed(record.status, "CMD-TIER-LOCK"):
+        print_and_exit(
+            format_error(
+                f"Cannot tier-lock in status {record.status.value!r}; "
+                "must be active_stage_draft",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    if not args.confirm:
+        print_and_exit(
+            format_error(
+                "Locking tier requires --confirm",
+                exit_code=EXIT_CLI_ERR,
+            ),
+            EXIT_CLI_ERR,
+        )
+
+    base = _parse_tier_base(args.base)
+    modifiers = _parse_modifiers(args.modifiers)
+
+    if record.tier_estimate is None:
+        # If no estimate, create a minimal one
+        from tools.workflow_cli.models import TierEstimate
+        record.tier_estimate = TierEstimate(base=TierBase.LIGHT, modifiers=frozenset())
+
+    if args.override_floor:
+        if not args.confirm:
+            print_and_exit(
+                format_error(
+                    "Overriding floor requires --confirm flag as well",
+                    exit_code=EXIT_CLI_ERR,
+                ),
+                EXIT_CLI_ERR,
+            )
+        from tools.workflow_cli.models import TierEstimate
+        record.tier_locked = TierEstimate(base=base, modifiers=modifiers)
+    else:
+        try:
+            record.tier_locked = record.tier_estimate.lock(base, modifiers)
+        except ValueError as e:
+            print_and_exit(format_error(str(e), exit_code=EXIT_CLI_ERR), EXIT_CLI_ERR)
+
+    mgr.save(record)
+    print_and_exit(
+        format_success(
+            {
+                "work_id": str(record.work_id),
+                "tier_base": record.tier_locked.base.value,
+                "modifiers": sorted(m.value for m in record.tier_locked.modifiers),
+            },
+            message="Tier locked",
+        ),
+        EXIT_OK,
+    )
+
+
+def _cmd_tier_escalate(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+
+    try:
+        modifier = TierModifier(args.modifier)
+    except ValueError:
+        valid = [m.value for m in TierModifier]
+        print_and_exit(
+            format_error(f"Unknown modifier {args.modifier!r}. Valid: {valid}", exit_code=EXIT_CLI_ERR),
+            EXIT_CLI_ERR,
+        )
+
+    if record.tier_locked is None:
+        print_and_exit(
+            format_error("Tier is not locked; run tier-lock first", exit_code=EXIT_CLI_ERR),
+            EXIT_CLI_ERR,
+        )
+    if record.status == RunStatus.CHECKPOINT_APPROVED:
+        print_and_exit(
+            format_error(
+                "Cannot escalate tier after checkpoint approval; advance or reopen the run first",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    if not is_command_allowed(record.status, "CMD-TIER-ESCALATE"):
+        print_and_exit(
+            format_error(
+                f"Cannot tier-escalate in status {record.status.value!r}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    previous_tier = record.tier_locked
+    record.tier_locked = record.tier_locked.escalate(modifier)
+
+    plan_gate_passed_statuses = {
+        RunStatus.READY_FOR_CHECKPOINT_REVIEW,
+        RunStatus.CHECKPOINT_REVIEW,
+    }
+    standard_plan_gate_became_applicable = (
+        record.current_stage == Stage.PLAN
+        and previous_tier.base != TierBase.STANDARD
+        and record.tier_locked.base == TierBase.STANDARD
+        and record.status in plan_gate_passed_statuses
+    )
+    if standard_plan_gate_became_applicable:
+        record = update_run_status(record, RunStatus.ACTIVE_STAGE_DRAFT)
+        update_resume_context(
+            record,
+            last_operation=f"tier_escalated_{modifier.value}",
+            next_operation="gate_quality",
+            active_item=Stage.PLAN.value,
+        )
+
+    # Revoke affected bundle authorizations that cover high-tier stages
+    from tools.workflow_cli.gates import _FORCED_REVIEW_MODIFIERS
+    high_modifiers = {TierModifier.MIGRATION, TierModifier.SAFETY, TierModifier.CROSS_PROJECT}
+    from datetime import datetime, timezone
+    if modifier in high_modifiers:
+        revoke_ts = datetime.now(timezone.utc).isoformat()
+        from tools.workflow_cli.models import STAGE_REQUIRED_UPSTREAM_CHECKPOINTS
+        affected_stages = {Stage.DESIGN, Stage.SPEC, Stage.PLAN}
+        for ba in record.bundle_authorizations:
+            if ba.stages & affected_stages and ba.revoked_at is None:
+                ba.revoked_at = revoke_ts
+
+    mgr.save(record)
+    print_and_exit(
+        format_success(
+            {
+                "work_id": str(record.work_id),
+                "tier_base": record.tier_locked.base.value,
+                "modifiers": sorted(m.value for m in record.tier_locked.modifiers),
+                "added_modifier": modifier.value,
+            },
+            message=f"Tier escalated with modifier: {modifier.value}",
+        ),
+        EXIT_OK,
+    )
+
+
+def _cmd_tier_status(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+
+    est = record.tier_estimate
+    locked = record.tier_locked
+
+    data = {
+        "work_id": str(record.work_id),
+        "tier_estimate": (
+            {"base": est.base.value, "modifiers": sorted(m.value for m in est.modifiers)}
+            if est else "none"
+        ),
+        "tier_locked": (
+            {"base": locked.base.value, "modifiers": sorted(m.value for m in locked.modifiers)}
+            if locked else "unlocked"
+        ),
+    }
+    print_and_exit(format_success(data, message="Tier status"), EXIT_OK)
+
+
+# ---------------------------------------------------------------------------
+# Gate commands
+# ---------------------------------------------------------------------------
+
+
+def _cmd_gate_entry(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+    stage = _parse_stage(args.stage)
+
+    # Precondition: if in NEXT_STAGE or ENTRY_GATE_FAILED, stage must match current_stage
+    if record.status in (RunStatus.NEXT_STAGE, RunStatus.ENTRY_GATE_FAILED) and stage != record.current_stage:
+        print_and_exit(
+            format_error(
+                f"Cannot run entry gate for {stage.value!r}; current stage is {record.current_stage.value!r}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    result = check_entry_gate(
+        run_dir,
+        stage,
+        record.approved_checkpoints,
+        record.bundle_authorizations,
+    )
+
+    # Persist state if in NEXT_STAGE or ENTRY_GATE_FAILED
+    if record.status in (RunStatus.NEXT_STAGE, RunStatus.ENTRY_GATE_FAILED):
+        target = RunStatus.ACTIVE_STAGE_DRAFT if result.passed else RunStatus.ENTRY_GATE_FAILED
+        if target != record.status:
+            record = update_run_status(record, target)
+        update_resume_context(
+            record,
+            last_operation=f"entry_gate_{'passed' if result.passed else 'failed'}_{stage.value}",
+            next_operation="produce_stage_artifact" if result.passed else "repair_upstream_checkpoint",
+            active_item=stage.value,
+        )
+        mgr.save(record)
+
+    output = format_gate_result(result, gate_type="entry-gate")
+    exit_code = EXIT_OK if result.passed else result.exit_code
+    print_and_exit(output, exit_code)
+
+
+def _cmd_gate_quality(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+    stage = _parse_stage(args.stage)
+
+    # Precondition: only an active draft can be quality-gated. Re-running after a
+    # pass (ready_for_checkpoint_review) or failure (quality_gate_failed) would
+    # otherwise attempt an illegal self-transition; return a clean conflict instead.
+    if record.status != RunStatus.ACTIVE_STAGE_DRAFT:
+        print_and_exit(
+            format_error(
+                f"Cannot run quality gate in status {record.status.value!r}; "
+                "must be active_stage_draft",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    # Precondition: stage must be current and artifact must be ready
+    if stage != record.current_stage:
+        print_and_exit(
+            format_error(
+                f"Stage {stage.value!r} is not the current stage {record.current_stage.value!r}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    aa = get_active_artifact(record, stage)
+    if aa is None or aa.status != "ready":
+        print_and_exit(
+            format_error(
+                f"Stage {stage.value!r} artifact is not ready; run stage-ready first",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    version = get_artifact_version(run_dir, stage)
+    if version != aa.version:
+        print_and_exit(
+            format_error(
+                f"Active artifact version v{aa.version} does not match on-disk v{version}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    # Read artifact content
+    try:
+        content = read_artifact(run_dir, stage)
+    except FileNotFoundError:
+        print_and_exit(
+            format_error(
+                f"Artifact not found for stage {stage.value!r}",
+                exit_code=EXIT_NOT_FOUND,
+            ),
+            EXIT_NOT_FOUND,
+        )
+
+    # Check quality gate
+    result = check_quality_gate(
+        run_dir,
+        stage,
+        record.tier_locked,
+        record.approved_checkpoints,
+        content,
+    )
+
+    if not result.passed:
+        if record.tier_locked is None:
+            print_and_exit(format_gate_result(result, gate_type="quality-gate"), result.exit_code)
+
+        record = update_run_status(record, RunStatus.QUALITY_GATE_FAILED)
+        update_resume_context(
+            record,
+            last_operation=f"quality_gate_failed_{stage.value}",
+            next_operation="repair_stage_artifact",
+            active_item=stage.value,
+        )
+        mgr.save(record)
+        print_and_exit(format_gate_result(result, gate_type="quality-gate"), result.exit_code)
+
+    record = update_run_status(record, RunStatus.READY_FOR_CHECKPOINT_REVIEW)
+    update_resume_context(
+        record,
+        last_operation=f"quality_gate_passed_{stage.value}",
+        next_operation="checkpoint_review",
+        active_item=stage.value,
+    )
+    mgr.save(record)
+    print_and_exit(format_gate_result(result, gate_type="quality-gate"), EXIT_OK)
+
+
+# ---------------------------------------------------------------------------
+# Status commands
+# ---------------------------------------------------------------------------
+
+
+def _cmd_status_run(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+
+    open_route_ids = [r.route_id for r in record.open_routes if r.status == "open"]
+    open_routes_detail = [
+        {
+            "route_id": r.route_id,
+            "from_stage": r.from_stage.value,
+            "owner_stage": r.owner_stage.value,
+            "required_action": r.required_action,
+            "status": r.status,
+        }
+        for r in record.open_routes
+        if r.status == "open"
+    ]
+    stale_artifacts = [
+        {
+            "artifact": s.artifact,
+            "reason": s.reason,
+            "replaced_by": s.replaced_by,
+            "required_action": s.required_action,
+        }
+        for s in record.stale_artifacts
+    ]
+    outstanding_stale = [aa.stage.value for aa in record.active_artifacts if aa.status == "stale"]
+
+    print_and_exit(
+        format_success(
+            {
+                "work_id": str(record.work_id),
+                "status": record.status.value,
+                "current_stage": record.current_stage.value,
+                "tier_locked": (
+                    record.tier_locked.base.value if record.tier_locked else "unlocked"
+                ),
+                "open_routes": open_route_ids,
+                "open_routes_detail": open_routes_detail,
+                "stale_artifacts": stale_artifacts,
+                "outstanding_stale": outstanding_stale,
+                "approved_checkpoints": [cp.stage.value for cp in record.approved_checkpoints],
+            },
+            message="Run status",
+        ),
+        EXIT_OK,
+    )
+
+
+def _cmd_status_next(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+    rc = record.resume_context
+    print_and_exit(
+        format_success(
+            {
+                "work_id": str(record.work_id),
+                "next_allowed_operation": rc.next_allowed_operation,
+                "active_item": rc.active_item,
+                "last_completed_operation": rc.last_completed_operation,
+                "resume_reason": rc.resume_reason,
+            },
+            message="Next operation",
+        ),
+        EXIT_OK,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Stage commands
+# ---------------------------------------------------------------------------
+
+
+def _resolve_content(args) -> str:
+    """Resolve content from --content or --content-file option."""
+    if args.content:
+        return args.content
+    if args.content_file:
+        path = Path(args.content_file)
+        if not path.exists():
+            print_and_exit(
+                format_error(f"Content file not found: {path}", exit_code=EXIT_NOT_FOUND),
+                EXIT_NOT_FOUND,
+            )
+        return path.read_text(encoding="utf-8")
+    print_and_exit(
+        format_error("Either --content or --content-file is required", exit_code=EXIT_CLI_ERR),
+        EXIT_CLI_ERR,
+    )
+
+
+def _cmd_stage_produce(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+    stage = _parse_stage(args.stage)
+    repair_state = record.status in (
+        RunStatus.CHECKPOINT_CHANGES_REQUESTED,
+        RunStatus.QUALITY_GATE_FAILED,
+    )
+
+    if record.status in (RunStatus.NEXT_STAGE, RunStatus.ENTRY_GATE_FAILED):
+        next_step = "gate-entry first to enter the stage draft"
+        if record.status == RunStatus.ENTRY_GATE_FAILED:
+            next_step = "gate-entry after repairing upstream checkpoints"
+        print_and_exit(
+            format_error(
+                f"Cannot produce in {record.status.value}; run {next_step}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    if stage != record.current_stage:
+        print_and_exit(
+            format_error(
+                f"Cannot produce stage {stage.value!r}; current stage is "
+                f"{record.current_stage.value!r}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    entry_result = check_entry_gate(
+        run_dir,
+        stage,
+        record.approved_checkpoints,
+        record.bundle_authorizations,
+    )
+    if not entry_result.passed:
+        if not repair_state:
+            record = update_run_status(record, RunStatus.ENTRY_GATE_FAILED)
+        update_resume_context(
+            record,
+            last_operation=f"entry_gate_failed_{stage.value}",
+            next_operation="repair_upstream_checkpoint",
+            active_item=stage.value,
+        )
+        mgr.save(record)
+        print_and_exit(
+            format_gate_result(entry_result, gate_type="entry-gate"),
+            entry_result.exit_code,
+        )
+
+    content = _resolve_content(args)
+
+    am = ArtifactManager(run_dir)
+    artifact_file = STAGE_ARTIFACT_MAP[stage]
+    try:
+        if repair_state:
+            path = am.stage_update(stage, content)
+            from tools.workflow_cli.artifact import get_artifact_version
+            new_version = get_artifact_version(run_dir, stage)
+        else:
+            path = am.stage_produce(stage, content)
+            new_version = 1
+    except FileExistsError as e:
+        print_and_exit(format_error(str(e), exit_code=EXIT_CONFLICT), EXIT_CONFLICT)
+
+    # Update run record active artifacts
+    record = update_run_status(record, RunStatus.ACTIVE_STAGE_DRAFT)
+    upsert_active_artifact(record, stage, artifact_file, new_version, "draft")
+    update_resume_context(record, last_operation=f"produce_{stage.value}")
+    mgr.save(record)
+
+    print_and_exit(
+        format_success(
+            {"work_id": str(record.work_id), "stage": stage.value, "artifact": str(path)},
+            message=f"Artifact produced for stage: {stage.value}",
+        ),
+        EXIT_OK,
+    )
+
+
+def _cmd_stage_update(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+    stage = _parse_stage(args.stage)
+
+    if record.status in (RunStatus.NEXT_STAGE, RunStatus.ENTRY_GATE_FAILED):
+        next_step = "gate-entry first to enter the stage draft"
+        if record.status == RunStatus.ENTRY_GATE_FAILED:
+            next_step = "gate-entry after repairing upstream checkpoints"
+        print_and_exit(
+            format_error(
+                f"Cannot update in {record.status.value}; run {next_step}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    if record.status == RunStatus.CHECKPOINT_REVIEW:
+        print_and_exit(
+            format_error(
+                "Cannot update artifacts while checkpoint review is open; "
+                "use checkpoint-decide to approve or request changes first",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    if record.status == RunStatus.CHECKPOINT_APPROVED:
+        print_and_exit(
+            format_error(
+                "Cannot update artifacts after checkpoint approval; "
+                "use stage-advance or run-close",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    if stage != record.current_stage:
+        print_and_exit(
+            format_error(
+                f"Cannot update stage {stage.value!r}; current stage is "
+                f"{record.current_stage.value!r}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    # Repair and post-gate edits invalidate the current artifact's gate/review readiness.
+    repair_state = record.status in (
+        RunStatus.CHECKPOINT_CHANGES_REQUESTED,
+        RunStatus.QUALITY_GATE_FAILED,
+    )
+    review_ready_state = record.status == RunStatus.READY_FOR_CHECKPOINT_REVIEW
+    needs_draft_reset = repair_state or review_ready_state
+
+    content = _resolve_content(args)
+
+    am = ArtifactManager(run_dir)
+    path = am.stage_update(stage, content)
+
+    # Update run record
+    from tools.workflow_cli.artifact import get_artifact_version
+    new_version = get_artifact_version(run_dir, stage)
+    artifact_file = STAGE_ARTIFACT_MAP[stage]
+    upsert_active_artifact(record, stage, artifact_file, new_version, "draft")
+
+    # Any post-gate edit invalidates the previous gate/review readiness.
+    # The stage must be marked ready and pass gate-quality again.
+    if needs_draft_reset:
+        record = update_run_status(record, RunStatus.ACTIVE_STAGE_DRAFT)
+
+    update_resume_context(record, last_operation=f"update_{stage.value}")
+    mgr.save(record)
+
+    print_and_exit(
+        format_success(
+            {
+                "work_id": str(record.work_id),
+                "stage": stage.value,
+                "artifact": str(path),
+                "version": new_version,
+            },
+            message=f"Artifact updated for stage: {stage.value}",
+        ),
+        EXIT_OK,
+    )
+
+
+def _cmd_stage_ready(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+    stage = _parse_stage(args.stage)
+
+    stage_ready_statuses = {
+        RunStatus.ACTIVE_STAGE_DRAFT,
+        RunStatus.QUALITY_GATE_FAILED,
+    }
+    if record.status not in stage_ready_statuses:
+        print_and_exit(
+            format_error(
+                f"Cannot mark artifacts ready in status {record.status.value!r}; "
+                "stage-ready is only allowed while drafting or after quality-gate failure; "
+                "checkpoint changes_requested requires stage-update or stage-produce first",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    repair_state = record.status == RunStatus.QUALITY_GATE_FAILED
+
+    if stage != record.current_stage:
+        print_and_exit(
+            format_error(
+                f"Cannot mark stage {stage.value!r} ready while current stage is "
+                f"{record.current_stage.value!r}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    am = ArtifactManager(run_dir)
+    try:
+        am.stage_ready(stage)
+    except FileNotFoundError:
+        print_and_exit(
+            format_error(
+                f"Artifact not found for stage {stage.value!r}; produce it first",
+                exit_code=EXIT_NOT_FOUND,
+            ),
+            EXIT_NOT_FOUND,
+        )
+    except ValueError as e:
+        print_and_exit(
+            format_error(str(e), exit_code=EXIT_CONFLICT),
+            EXIT_CONFLICT,
+        )
+
+    # Update run record
+    from tools.workflow_cli.artifact import get_artifact_version
+    version = get_artifact_version(run_dir, stage)
+    artifact_file = STAGE_ARTIFACT_MAP[stage]
+    upsert_active_artifact(record, stage, artifact_file, version, "ready")
+    if repair_state:
+        record = update_run_status(record, RunStatus.ACTIVE_STAGE_DRAFT)
+    update_resume_context(record, last_operation=f"ready_{stage.value}")
+    mgr.save(record)
+
+    print_and_exit(
+        format_success(
+            {"work_id": str(record.work_id), "stage": stage.value},
+            message=f"Stage marked ready: {stage.value}",
+        ),
+        EXIT_OK,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Subparser registration
+# ---------------------------------------------------------------------------
+
+
+def _register_run_commands(subparsers):
+    # run-start
+    p = subparsers.add_parser("run-start", help="Start a new workflow run")
+    p.add_argument("--work-id", required=True, help="Workflow ID (WF-YYYYMMDD-slug)")
+    src = p.add_mutually_exclusive_group(required=True)
+    src.add_argument("--requirement", default=None, help="Raw requirement text")
+    src.add_argument(
+        "--requirement-file",
+        dest="requirement_file",
+        default=None,
+        help="Path to a file whose contents are the raw requirement",
+    )
+    p.add_argument("--repo-path", default=None, help="Path to repository for baseline scan")
+    p.add_argument("--overwrite", action="store_true", help="Overwrite an existing run")
+    p.set_defaults(func=_cmd_run_start)
+
+    # run-resume
+    p = subparsers.add_parser("run-resume", help="Resume a workflow run")
+    p.add_argument("--work-id", required=True)
+    p.set_defaults(func=_cmd_run_resume)
+
+    # run-close
+    p = subparsers.add_parser("run-close", help="Close a workflow run")
+    p.add_argument("--work-id", required=True)
+    p.set_defaults(func=_cmd_run_close)
+
+    # run-reopen
+    p = subparsers.add_parser("run-reopen", help="Reopen a closed 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)
+
+
+def _register_tier_commands(subparsers):
+    # tier-estimate
+    p = subparsers.add_parser("tier-estimate", help="Estimate tier for requirement text")
+    p.add_argument("--text", required=True, help="Requirement text to estimate")
+    p.add_argument("--repo-path", default=None, help="Path to repository for baseline scan")
+    p.set_defaults(func=_cmd_tier_estimate)
+
+    # tier-lock
+    p = subparsers.add_parser("tier-lock", help="Lock tier for a run")
+    p.add_argument("--work-id", required=True)
+    p.add_argument("--base", required=True, choices=["light", "standard"])
+    p.add_argument("--modifiers", default=None, help="Comma-separated modifiers")
+    p.add_argument("--override-floor", action="store_true", help="Allow locking below floor")
+    p.add_argument("--confirm", action="store_true", help="Required confirmation before locking tier")
+    p.set_defaults(func=_cmd_tier_lock)
+
+    # tier-escalate
+    p = subparsers.add_parser("tier-escalate", help="Add a modifier to locked tier")
+    p.add_argument("--work-id", required=True)
+    p.add_argument(
+        "--modifier",
+        required=True,
+        choices=[m.value for m in TierModifier],
+        help="Modifier to add",
+    )
+    p.set_defaults(func=_cmd_tier_escalate)
+
+    # tier-status
+    p = subparsers.add_parser("tier-status", help="Print tier estimate and lock status")
+    p.add_argument("--work-id", required=True)
+    p.set_defaults(func=_cmd_tier_status)
+
+
+def _register_gate_commands(subparsers):
+    # gate-entry
+    p = subparsers.add_parser("gate-entry", help="Check entry gate for a stage")
+    p.add_argument("--work-id", required=True)
+    p.add_argument("--stage", required=True)
+    p.set_defaults(func=_cmd_gate_entry)
+
+    # gate-quality
+    p = subparsers.add_parser("gate-quality", help="Check quality gate for a stage")
+    p.add_argument("--work-id", required=True)
+    p.add_argument("--stage", required=True)
+    p.set_defaults(func=_cmd_gate_quality)
+
+
+def _register_status_commands(subparsers):
+    # status-run
+    p = subparsers.add_parser("status-run", help="Print run state, stage, tier, open routes")
+    p.add_argument("--work-id", required=True)
+    p.set_defaults(func=_cmd_status_run)
+
+    # status-next
+    p = subparsers.add_parser("status-next", help="Print next allowed operation from resume context")
+    p.add_argument("--work-id", required=True)
+    p.set_defaults(func=_cmd_status_next)
+
+
+def _cmd_review_checkpoint(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+    stage = _parse_stage(args.stage)
+
+    if record.status not in {
+        RunStatus.READY_FOR_CHECKPOINT_REVIEW,
+        RunStatus.CHECKPOINT_REVIEW,
+    }:
+        print_and_exit(
+            format_error(
+                f"Cannot review-checkpoint in status {record.status.value!r}; "
+                "must be ready_for_checkpoint_review or checkpoint_review",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    if stage != record.current_stage:
+        print_and_exit(
+            format_error(
+                f"Stage {stage.value!r} is not the current stage {record.current_stage.value!r}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    aa = get_active_artifact(record, stage)
+    if aa is None:
+        print_and_exit(
+            format_error(f"No active artifact for stage {stage.value!r}", exit_code=EXIT_CONFLICT),
+            EXIT_CONFLICT,
+        )
+    if aa.status != "ready":
+        print_and_exit(
+            format_error(
+                f"Stage {stage.value!r} artifact must be ready before checkpoint review",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    version = get_artifact_version(run_dir, stage)
+    if version != aa.version:
+        print_and_exit(
+            format_error(
+                f"Active artifact version v{aa.version} does not match on-disk v{version}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    reviews_dir = run_dir / "reviews"
+    reviews_dir.mkdir(parents=True, exist_ok=True)
+    marker = reviews_dir / f"{stage.value}-checkpoint-review-v{aa.version}.md"
+    marker.write_text(
+        f"# Checkpoint review marker\n\nstage: {stage.value}\nversion: {aa.version}\n"
+        "status: ready for human decision\n",
+        encoding="utf-8",
+    )
+
+    if record.status == RunStatus.READY_FOR_CHECKPOINT_REVIEW:
+        record = update_run_status(record, RunStatus.CHECKPOINT_REVIEW)
+    update_resume_context(
+        record,
+        last_operation=f"review_checkpoint_{stage.value}",
+        next_operation="checkpoint_decide",
+        active_item=stage.value,
+    )
+    mgr.save(record)
+    print_and_exit(
+        format_success(
+            {"work_id": str(record.work_id), "stage": stage.value, "marker": str(marker)},
+            message=f"Checkpoint review opened: {stage.value}",
+        ),
+        EXIT_OK,
+    )
+
+
+def _register_stage_commands(subparsers):
+    def _add_content_args(p):
+        grp = p.add_mutually_exclusive_group()
+        grp.add_argument("--content", default=None, help="Artifact content (inline)")
+        grp.add_argument("--content-file", default=None, help="Path to file containing content")
+
+    # stage-produce
+    p = subparsers.add_parser("stage-produce", help="Write initial draft of a stage artifact")
+    p.add_argument("--work-id", required=True)
+    p.add_argument("--stage", required=True)
+    _add_content_args(p)
+    p.set_defaults(func=_cmd_stage_produce)
+
+    # stage-update
+    p = subparsers.add_parser("stage-update", help="Increment version and update stage artifact")
+    p.add_argument("--work-id", required=True)
+    p.add_argument("--stage", required=True)
+    _add_content_args(p)
+    p.set_defaults(func=_cmd_stage_update)
+
+    # stage-ready
+    p = subparsers.add_parser("stage-ready", help="Mark a stage artifact as ready")
+    p.add_argument("--work-id", required=True)
+    p.add_argument("--stage", required=True)
+    p.set_defaults(func=_cmd_stage_ready)
+
+
+def _cmd_checkpoint_decide(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+    stage = _parse_stage(args.stage)
+
+    if record.status != RunStatus.CHECKPOINT_REVIEW:
+        print_and_exit(
+            format_error(
+                f"Cannot decide in status {record.status.value!r}; must be checkpoint_review",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    if stage != record.current_stage:
+        print_and_exit(
+            format_error(
+                f"Stage {stage.value!r} is not the current stage {record.current_stage.value!r}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    aa = get_active_artifact(record, stage)
+    if aa is None:
+        print_and_exit(
+            format_error(f"No active artifact for stage {stage.value!r}", exit_code=EXIT_CONFLICT),
+            EXIT_CONFLICT,
+        )
+    if aa.status != "ready":
+        print_and_exit(
+            format_error(
+                f"Stage {stage.value!r} artifact must be ready before checkpoint decision",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    version = get_artifact_version(run_dir, stage)
+    if version != aa.version:
+        print_and_exit(
+            format_error(
+                f"Active artifact version v{aa.version} does not match on-disk v{version}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    if args.decision == "changes_requested":
+        record = update_run_status(record, RunStatus.CHECKPOINT_CHANGES_REQUESTED)
+        update_resume_context(
+            record,
+            last_operation=f"changes_requested_{stage.value}",
+            next_operation="repair_stage_artifact",
+            active_item=stage.value,
+        )
+        mgr.save(record)
+        print_and_exit(
+            format_success(
+                {"work_id": str(record.work_id), "stage": stage.value, "decision": "changes_requested"},
+                message=f"Changes requested: {stage.value}",
+            ),
+            EXIT_OK,
+        )
+
+    # decision == "approved"
+    if not args.confirm:
+        print_and_exit(
+            format_error(
+                "Approval requires --confirm",
+                exit_code=EXIT_REVIEW_REQ,
+            ),
+            EXIT_REVIEW_REQ,
+        )
+
+    open_routes = [r.route_id for r in record.open_routes if r.status == "open"]
+    if open_routes:
+        print_and_exit(
+            format_error(
+                "Cannot approve checkpoint while routes remain open",
+                details=open_routes,
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    # Duplicate-approval guard.
+    if any(cp.stage == stage and cp.version == aa.version for cp in record.approved_checkpoints):
+        print_and_exit(
+            format_error(
+                f"Stage {stage.value!r} v{aa.version} already has an approved checkpoint",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    reviews_dir = run_dir / "reviews"
+    # Precondition: checkpoint-review marker for this version must exist (GR5).
+    marker = reviews_dir / f"{stage.value}-checkpoint-review-v{aa.version}.md"
+    if not marker.exists():
+        print_and_exit(
+            format_error(
+                f"Missing checkpoint-review marker for {stage.value} v{aa.version}; "
+                "run review-checkpoint first",
+                exit_code=EXIT_REVIEW_REQ,
+            ),
+            EXIT_REVIEW_REQ,
+        )
+
+    # Forced-review guard (version-aware; subagent file required).
+    review_result = check_forced_subagent_review(stage, record.tier_locked, reviews_dir, aa.version)
+    if not review_result.passed:
+        print_and_exit(
+            format_gate_result(review_result, gate_type="subagent-review"),
+            EXIT_REVIEW_REQ,
+        )
+
+    from tools.workflow_cli.models import NEXT_STAGE_MAP
+    next_stage = NEXT_STAGE_MAP.get(stage)
+    downstream = args.downstream_authorization or (next_stage.value if next_stage else "close_workflow_run")
+    artifact_file = STAGE_ARTIFACT_MAP[stage]
+    add_checkpoint(record, stage, artifact_file, aa.version, downstream)
+    upsert_active_artifact(record, stage, artifact_file, aa.version, "approved")
+    update_artifact_status(run_dir, stage, "approved")
+    record = update_run_status(record, RunStatus.CHECKPOINT_APPROVED)
+    update_resume_context(
+        record,
+        last_operation=f"approved_{stage.value}",
+        next_operation="stage_advance" if next_stage else "run_close",
+        active_item=stage.value,
+    )
+    mgr.save(record)
+    print_and_exit(
+        format_success(
+            {"work_id": str(record.work_id), "stage": stage.value, "decision": "approved"},
+            message=f"Checkpoint approved: {stage.value}",
+        ),
+        EXIT_OK,
+    )
+
+
+def _cmd_stage_advance(args):
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+
+    if record.status != RunStatus.CHECKPOINT_APPROVED:
+        print_and_exit(
+            format_error(
+                f"Cannot advance in status {record.status.value!r}; must be checkpoint_approved",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    stage = record.current_stage
+    if stage == Stage.PLAN:
+        print_and_exit(
+            format_error(
+                "Cannot advance past plan; use run-close",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    aa = get_active_artifact(record, stage)
+    if aa is None:
+        print_and_exit(
+            format_error(
+                f"No active artifact for stage {stage.value!r}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    if aa.status != "approved":
+        print_and_exit(
+            format_error(
+                f"Stage {stage.value!r} artifact must be approved before stage-advance",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    version = get_artifact_version(run_dir, stage)
+    if version != aa.version:
+        print_and_exit(
+            format_error(
+                f"Active artifact version v{aa.version} does not match on-disk v{version}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    if not any(
+        cp.stage == stage and cp.artifact == aa.artifact and cp.version == aa.version
+        for cp in record.approved_checkpoints
+    ):
+        print_and_exit(
+            format_error(
+                f"No approved checkpoint matching {stage.value} v{aa.version}",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    open_routes = [r.route_id for r in record.open_routes if r.status == "open"]
+    if open_routes:
+        print_and_exit(
+            format_error(
+                "Cannot advance stage while routes remain open",
+                details=open_routes,
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+
+    from tools.workflow_cli.models import NEXT_STAGE_MAP
+    next_stage = NEXT_STAGE_MAP[stage]
+    record = update_run_status(record, RunStatus.NEXT_STAGE)
+    record.current_stage = next_stage
+    update_resume_context(
+        record,
+        last_operation=f"advance_to_{next_stage.value}",
+        next_operation="gate_entry",
+        active_item=next_stage.value,
+    )
+    mgr.save(record)
+    print_and_exit(
+        format_success(
+            {"work_id": str(record.work_id), "current_stage": next_stage.value},
+            message=f"Advanced to {next_stage.value}",
+        ),
+        EXIT_OK,
+    )
+
+
+def _register_checkpoint_commands(subparsers):
+    p = subparsers.add_parser("review-checkpoint", help="Open checkpoint review for a stage")
+    p.add_argument("--work-id", required=True)
+    p.add_argument("--stage", required=True)
+    p.set_defaults(func=_cmd_review_checkpoint)
+
+    p = subparsers.add_parser("checkpoint-decide", help="Approve or request changes on a checkpoint")
+    p.add_argument("--work-id", required=True)
+    p.add_argument("--stage", required=True)
+    p.add_argument("--decision", required=True, choices=["approved", "changes_requested"])
+    p.add_argument("--confirm", action="store_true")
+    p.add_argument("--downstream-authorization", default=None)
+    p.set_defaults(func=_cmd_checkpoint_decide)
+
+    p = subparsers.add_parser("stage-advance", help="Advance an approved stage to the next stage")
+    p.add_argument("--work-id", required=True)
+    p.set_defaults(func=_cmd_stage_advance)
+
+
+def _register_route_commands(subparsers):
+    # gap-open
+    p = subparsers.add_parser("gap-open", help="Route an upstream gap back to an owner stage")
+    p.add_argument("--work-id", required=True)
+    p.add_argument("--owner-stage", required=True)
+    p.add_argument("--required-action", required=True)
+    p.add_argument("--confirm", action="store_true")
+    p.set_defaults(func=_cmd_gap_open)
+
+    # gap-resolve
+    p = subparsers.add_parser("gap-resolve", help="Resolve an open upstream-gap route")
+    p.add_argument("--work-id", required=True)
+    p.add_argument("--route-id", required=True)
+    p.add_argument("--confirm", action="store_true")
+    p.set_defaults(func=_cmd_gap_resolve)
+
+
+# ---------------------------------------------------------------------------
+# main
+# ---------------------------------------------------------------------------
+
+
+def main(args=None):
+    parser = argparse.ArgumentParser(
+        prog="workflow",
+        description="req-to-plan CLI — internal Agent commands",
+    )
+    parser.add_argument(
+        "--base-path",
+        type=Path,
+        default=None,
+        help="Override base path for .req-to-plan/ directory (for testing)",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    _register_run_commands(subparsers)
+    _register_route_commands(subparsers)
+    _register_tier_commands(subparsers)
+    _register_gate_commands(subparsers)
+    _register_status_commands(subparsers)
+    _register_stage_commands(subparsers)
+    _register_checkpoint_commands(subparsers)
+
+    parsed = parser.parse_args(args)
+    parsed.func(parsed)
+
+
+if __name__ == "__main__":
+    main()