okstra 0.91.1 → 0.92.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.91.1",
+  "version": "0.92.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.91.1",
-  "builtAt": "2026-06-18T06:51:56.885Z",
+  "package": "0.92.0",
+  "builtAt": "2026-06-18T07:29:46.716Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/implementation_stage.py

@@ -0,0 +1,217 @@
+"""Implementation stage run orchestration.
+
+This module owns the lifecycle for one ``implementation`` stage run: recover
+consumer state, select an available Stage Map entry, provision the isolated
+stage worktree, and publish the selected stage into run context.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import stage_targets
+from .stage_reconcile import auto_reconcile_best_effort
+
+
+class ImplementationStageError(Exception):
+    """Implementation stage selection or provisioning failed."""
+
+
+@dataclass
+class StageSelection:
+    """Resolved implementation stage and its isolated worktree coordinates."""
+
+    stage: int
+    worktree_path: str
+    worktree_branch: str
+    worktree_base_ref: str
+    worktree_status: str
+    worktree_note: str
+    started_head_commit: str
+    concurrent_stages: list[int] = field(default_factory=list)
+
+
+def _git_out(cwd: str | Path, *args: str) -> str:
+    result = subprocess.run(
+        ["git", "-C", str(cwd), *args],
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout.strip() if result.returncode == 0 else ""
+
+
+def _as_implementation_stage_error(exc: Exception) -> ImplementationStageError:
+    if isinstance(exc, ImplementationStageError):
+        return exc
+    return ImplementationStageError(str(exc))
+
+
+def select_and_provision_implementation_stage(
+    inp: Any,
+    ctx_stage_map: list[dict[str, Any]],
+    task_group_segment: str,
+    task_id_segment: str,
+    task_key: str,
+    executor_worktree_status: str,
+) -> StageSelection:
+    """Select a ready implementation stage and provision its stage worktree.
+
+    The returned selection is path-independent with respect to run artifacts:
+    callers can compute stage-specific run paths after this function resolves
+    the selected stage.
+    """
+    del task_key  # The registry uses the split identity fields.
+
+    from .consumers import read_consumers, backfill_done_from_carry
+    from . import worktree as _worktree
+    from . import worktree_registry as _reg
+
+    plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
+    backfill_done_from_carry(plan_run_root)
+    auto_reconcile_best_effort(inp, plan_run_root)
+    consumed = read_consumers(plan_run_root)
+    done_stages = {r["stage"] for r in consumed if r.get("status") == "done"}
+    started_stages = {r["stage"] for r in consumed if r.get("status") == "started"}
+    reserved_stages = _reg.list_active_stage_numbers(
+        inp.project_id,
+        inp.task_group,
+        inp.task_id,
+    )
+
+    try:
+        batch = stage_targets.resolve_effective_stages(
+            ctx_stage_map,
+            done_stages,
+            inp.stage,
+            started_stages=started_stages,
+            reserved_stages=reserved_stages,
+        )
+    except stage_targets.StageTargetError as exc:
+        raise _as_implementation_stage_error(exc) from exc
+
+    selected = batch[0]
+    concurrent_stages = sorted(reserved_stages - done_stages - {selected})
+
+    if executor_worktree_status.startswith("skipped"):
+        head = _git_out(inp.project_root, "rev-parse", "HEAD")
+        return StageSelection(
+            stage=selected,
+            worktree_path="",
+            worktree_branch="",
+            worktree_base_ref="",
+            worktree_status=executor_worktree_status,
+            worktree_note="",
+            started_head_commit=head,
+            concurrent_stages=concurrent_stages,
+        )
+
+    head_sha = _git_out(inp.project_root, "rev-parse", "HEAD")
+    if head_sha:
+        _reg.set_implementation_base(
+            inp.project_id,
+            inp.task_group,
+            inp.task_id,
+            head_sha,
+        )
+    anchor = _reg.get_implementation_base(
+        inp.project_id,
+        inp.task_group,
+        inp.task_id,
+    ) or ""
+
+    selected_stage = next(
+        s for s in ctx_stage_map if s["stage_number"] == selected
+    )
+    consumer_done_rows = [r for r in consumed if r.get("status") == "done"]
+    try:
+        stage_base = stage_targets.resolve_stage_base_commit(
+            selected_stage,
+            consumer_done_rows,
+            anchor_base_commit=anchor,
+            candidate_base=head_sha,
+            project_root=Path(inp.project_root),
+            plan_run_root=plan_run_root,
+        )
+    except stage_targets.StageTargetError as exc:
+        raise _as_implementation_stage_error(exc) from exc
+
+    try:
+        prov = _worktree.provision_stage_worktree(
+            project_root=Path(inp.project_root),
+            project_id=inp.project_id,
+            task_group_segment=task_group_segment,
+            task_id_segment=task_id_segment,
+            work_category=inp.work_category,
+            stage_number=selected,
+            base_commit=stage_base,
+        )
+    except RuntimeError as exc:
+        from .git_reconcile import guidance
+
+        hint = guidance(
+            plan_run_root=plan_run_root,
+            project_id=inp.project_id,
+            task_group=inp.task_group,
+            task_id=inp.task_id,
+            work_category=inp.work_category,
+        )
+        raise ImplementationStageError(
+            f"stage worktree provisioning failed: {exc}\n{hint}"
+        ) from exc
+
+    return StageSelection(
+        stage=selected,
+        worktree_path=prov.path,
+        worktree_branch=prov.branch,
+        worktree_base_ref=prov.base_ref,
+        worktree_status=prov.status,
+        worktree_note=prov.note,
+        started_head_commit=prov.base_ref,
+        concurrent_stages=concurrent_stages,
+    )
+
+
+def apply_implementation_stage(
+    inp: Any,
+    ctx: dict[str, Any],
+    ctx_stage_map: list[dict[str, Any]],
+    sel: StageSelection,
+) -> None:
+    """Publish a selected stage into run context and ``consumers.jsonl``."""
+    from .consumers import append_consumer
+
+    ctx["parsed_stage_map"] = ctx_stage_map
+    ctx["effective_stages"] = [sel.stage]
+    csv = str(sel.stage)
+    ctx["EFFECTIVE_STAGES"] = csv
+    ctx["CONCURRENT_RUN_STAGES"] = ",".join(str(s) for s in sel.concurrent_stages)
+    ctx["STAGE_BATCH_DIRECTIVE"] = (
+        f"- **Stage for this implementation run:** `{csv}`. "
+        "Execute exactly this Stage Map stage — this is the authoritative scope. "
+        "Do NOT recompute from `consumers.jsonl`; the runtime already selected "
+        "and reserved this stage."
+    )
+    inp.stage = csv
+    print(f"selected stages: {csv}", file=sys.stdout)
+
+    if sel.worktree_status and not sel.worktree_status.startswith("skipped"):
+        ctx["EXECUTOR_WORKTREE_PATH"] = sel.worktree_path
+        ctx["EXECUTOR_WORKTREE_BRANCH"] = sel.worktree_branch
+        ctx["EXECUTOR_WORKTREE_BASE_REF"] = sel.worktree_base_ref
+        ctx["EXECUTOR_WORKTREE_STATUS"] = sel.worktree_status
+        ctx["EXECUTOR_WORKTREE_NOTE"] = sel.worktree_note
+
+    now = _dt.datetime.now(_dt.timezone.utc).isoformat()
+    plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
+    append_consumer(
+        plan_run_root,
+        impl_task_key=ctx["TASK_KEY"],
+        stage=sel.stage,
+        status="started",
+        started_at=now,
+        head_commit=sel.started_head_commit,
+    )

package/runtime/python/okstra_ctl/run.py

@@ -89,6 +89,11 @@ from .workers import (
 )
 from .workflow import compute_workflow_state, load_phase_forbidden
 from .locks import worktree_provision_mutex
+from . import stage_targets as _stage_targets
+from . import implementation_stage as _implementation_stage
+from .stage_reconcile import (
+    auto_reconcile_best_effort as _stage_auto_reconcile_best_effort,
+)
 from .worktree import (
     WorktreeProvision,
     okstra_clean_gate_excludes,
@@ -418,7 +423,12 @@ def _validate_stage_structure(plan_path: str) -> None:
         )
 
 
-RUN_STEP_BUDGET = 8
+RUN_STEP_BUDGET = _stage_targets.RUN_STEP_BUDGET
+_FVTarget = _stage_targets.FinalVerificationTarget
+
+
+def _stage_target_prepare_error(exc: _stage_targets.StageTargetError) -> PrepareError:
+    return PrepareError(str(exc))
 
 
 def _resolve_effective_stages(
@@ -429,98 +439,40 @@ def _resolve_effective_stages(
     started_stages: set = None,
     reserved_stages: set = None,
 ) -> list:
-    """Return the ordered list of stage numbers this run executes.
-
-    `requested` is "auto" or a decimal string. For "auto" the run batches all
-    ready stages (depends-on all done, itself neither done nor occupied) in
-    stage-number order up to `budget` effective steps. A numeric request is a
-    single forced stage. `started_stages`/`reserved_stages` are stages a
-    concurrent run already holds (consumers.jsonl `started` and the registry
-    stage reservations); they are excluded so two simultaneous runs never pick
-    the same stage. Raises PrepareError on rejection cases."""
-    started_stages = started_stages or set()
-    reserved_stages = reserved_stages or set()
-    occupied = done_stages | started_stages | reserved_stages
-    if requested != "auto":
-        try:
-            n = int(requested)
-        except ValueError:
-            raise PrepareError(
-                f"--stage must be 'auto' or an integer, got {requested!r}"
-            )
-        target = next((s for s in stages if s["stage_number"] == n), None)
-        if target is None:
-            raise PrepareError(
-                f"--stage {n} not in Stage Map "
-                f"(have {[s['stage_number'] for s in stages]})"
-            )
-        if n in done_stages:
-            raise PrepareError(
-                f"--stage {n} already completed (consumers.jsonl status:done exists)"
-            )
-        if n in started_stages or n in reserved_stages:
-            raise PrepareError(
-                f"--stage {n} already in progress or reserved by another run"
-            )
-        return [n]
-
-    ready = [
-        s for s in stages
-        if s["stage_number"] not in occupied
-        and all(d in done_stages for d in s["depends_on"])
-    ]
-    if not ready:
-        raise PrepareError(
-            "no stage is ready: every remaining stage has unsatisfied depends-on"
+    """Compatibility wrapper for the public stage-target policy module."""
+    try:
+        return _stage_targets.resolve_effective_stages(
+            stages,
+            done_stages,
+            requested,
+            budget=budget,
+            started_stages=started_stages,
+            reserved_stages=reserved_stages,
         )
-    batch: list = []
-    total = 0
-    for s in ready:
-        sc = s.get("step_count", 0) or 0
-        if batch and total + sc > budget:
-            break
-        batch.append(s["stage_number"])
-        total += sc
-    return batch
+    except _stage_targets.StageTargetError as exc:
+        raise _stage_target_prepare_error(exc) from exc
 
 
 def _commit_is_ancestor(project_root, ancestor: str, descendant: str) -> bool:
-    """True iff `ancestor` is an ancestor of `descendant` in project_root's git
-    history (`git merge-base --is-ancestor`, exit 0). Used to detect whether a
-    predecessor stage's done commit has been merged into the task worktree HEAD."""
-    r = _subprocess.run(
-        ["git", "merge-base", "--is-ancestor", ancestor, descendant],
-        cwd=str(project_root), capture_output=True, text=True,
-    )
-    return r.returncode == 0
+    """Compatibility wrapper for tests and older internal callers."""
+    return _stage_targets.commit_is_ancestor(project_root, ancestor, descendant)
 
 
 def _check_multi_dep_merged(project_root, plan_run_root, latest,
                             pred_commits: dict, candidate_base: str,
                             stage_n: int) -> None:
-    """모든 선행 done commit 이 candidate 에 (내용 기준으로라도) 머지됐는지
-    검증. patch-equivalent 면 보정 row 를 자동 기록(다음 run 은 ancestor 로
-    바로 통과). 아니면 회복 안내를 담아 PrepareError."""
-    from .git_reconcile import content_merged, _record_reconciled
-    for d, head in pred_commits.items():
-        if _commit_is_ancestor(project_root, head, candidate_base):
-            continue
-        match = content_merged(project_root, head, candidate_base)
-        if match.status in ("ancestor", "patch-equivalent"):
-            if plan_run_root is not None:
-                _record_reconciled(
-                    plan_run_root,
-                    impl_task_key=(latest.get(d) or {}).get("impl_task_key", ""),
-                    stage=d, new_commit=match.matched_commit,
-                    replaced=head, reason="auto-patch-id")
-            continue
-        raise PrepareError(
-            f"multi-dependency stage {stage_n}: predecessor stage {d} "
-            f"({head[:8]}) is not merged into the task worktree "
-            f"({candidate_base[:8]}). Merge stage branches "
-            f"(e.g. the `-s{d}` branches) into the task worktree "
-            "(or into main, then refresh the worktree) and retry."
+    """Compatibility wrapper for the stage-target dependency gate."""
+    try:
+        _stage_targets.check_multi_dep_merged(
+            project_root,
+            plan_run_root,
+            latest,
+            pred_commits,
+            candidate_base,
+            stage_n,
         )
+    except _stage_targets.StageTargetError as exc:
+        raise _stage_target_prepare_error(exc) from exc
 
 
 def _resolve_stage_base_commit(
@@ -531,70 +483,18 @@ def _resolve_stage_base_commit(
     project_root=None,
     plan_run_root=None,
 ) -> str:
-    """Pick the git base commit a stage's isolated worktree branches from.
-
-    - 독립 (`depends-on (none)`): anchor (= implementation_base_commit fixed
-      at first stage entry).
-    - 단일 의존 (`depends-on X`): predecessor X 의 `done.head_commit`.
-    - 다중 의존 (`depends-on X,Y…`): spec §9 옵션 A 자동 감지. candidate_base
-      (= task-key worktree HEAD) 에 모든 선행 done commit 이 ancestor 면
-      candidate 를 반환(사용자가 선행을 머지함). 아니면 PrepareError.
-
-    Raises PrepareError on missing predecessor / anchor / unmerged predecessor."""
-    from .consumers import latest_done_by_stage
-    latest = latest_done_by_stage(consumer_done_rows)
-    deps = stage.get("depends_on") or []
-    if len(deps) >= 2:
-        n = stage["stage_number"]
-        # 1) 모든 선행의 done head_commit 수집
-        pred_commits = {}
-        for d in deps:
-            head = (latest.get(d) or {}).get("head_commit")
-            if not head:
-                raise PrepareError(
-                    f"predecessor stage {d} has no done row with head_commit "
-                    f"in consumers.jsonl; multi-dependency stage {n} cannot start"
-                )
-            pred_commits[d] = head
-        # 2) candidate (task-key worktree HEAD) 필요
-        if not candidate_base or project_root is None:
-            raise PrepareError(
-                f"candidate base missing for multi-dependency stage {n}; "
-                "task-key worktree HEAD could not be resolved"
-            )
-        # 3) 모든 선행 done 이 candidate 에 (ancestor 또는 patch-equivalent 로)
-        #    머지됐는지 — patch-equivalent 면 보정 row 를 자동 기록한다.
-        _check_multi_dep_merged(project_root, plan_run_root, latest,
-                                pred_commits, candidate_base, n)
-        return candidate_base
-    if not deps:
-        if not anchor_base_commit:
-            raise PrepareError(
-                f"anchor base commit missing for independent stage "
-                f"{stage['stage_number']}; first-stage prepare should have "
-                "fixed it via worktree_registry.set_implementation_base"
-            )
-        return anchor_base_commit
-    # 단일 의존
-    pred = deps[0]
-    head = (latest.get(pred) or {}).get("head_commit") or ""
-    if head:
-        return head
-    raise PrepareError(
-        f"predecessor stage {pred} has no done row with head_commit in "
-        "consumers.jsonl; cannot derive base for stage "
-        f"{stage['stage_number']}"
-    )
-
-
-@dataclass
-class _FVTarget:
-    scope: str            # "whole-task" | "single-stage"
-    base: str
-    head: str
-    worktree_path: str
-    stages: list          # list[int]
-    reports: list         # list[str], report_path 값(없으면 "")
+    """Compatibility wrapper for stage worktree base selection."""
+    try:
+        return _stage_targets.resolve_stage_base_commit(
+            stage,
+            consumer_done_rows,
+            anchor_base_commit,
+            candidate_base=candidate_base,
+            project_root=project_root,
+            plan_run_root=plan_run_root,
+        )
+    except _stage_targets.StageTargetError as exc:
+        raise _stage_target_prepare_error(exc) from exc
 
 
 def _resolve_whole_task_target(
@@ -602,66 +502,37 @@ def _resolve_whole_task_target(
     task_worktree_path: str, task_head: str, task_dirty: bool,
     merged: dict,
 ) -> "_FVTarget":
-    """전체-task 검증 target. 모든 Stage Map stage 가 done + HEAD 에 머지 +
-    worktree clean 이어야 한다. 위반 시 PrepareError."""
-    from .consumers import latest_done_by_stage
-    done_by_stage = latest_done_by_stage(done_rows)
-    for s in stage_map:
-        n = s["stage_number"]
-        if n not in done_by_stage:
-            raise PrepareError(
-                f"final-verification(whole-task): stage {n} not done — "
-                f"run implementation --stage {n} first"
-            )
-        if not merged.get(n, False):
-            sha = done_by_stage[n].get("head_commit", "")
-            raise PrepareError(
-                f"final-verification(whole-task): stage {n} done commit "
-                f"{sha} not merged into task worktree HEAD — merge stage "
-                "branches then retry"
-            )
-    if task_dirty:
-        raise PrepareError(
-            "final-verification: worktree has uncommitted source changes "
-            "(outside .okstra/) — commit or stash before verifying"
+    """Compatibility wrapper for whole-task verification target selection."""
+    try:
+        return _stage_targets.resolve_whole_task_target(
+            stage_map=stage_map,
+            done_rows=done_rows,
+            anchor_base=anchor_base,
+            task_worktree_path=task_worktree_path,
+            task_head=task_head,
+            task_dirty=task_dirty,
+            merged=merged,
         )
-    stages = [s["stage_number"] for s in stage_map]
-    reports = [done_by_stage[n].get("report_path", "") for n in stages]
-    return _FVTarget(
-        scope="whole-task", base=anchor_base, head=task_head,
-        worktree_path=task_worktree_path, stages=stages, reports=reports,
-    )
+    except _stage_targets.StageTargetError as exc:
+        raise _stage_target_prepare_error(exc) from exc
 
 
 def _resolve_single_stage_target(
     *, requested_stage: str, done_rows: list, stage_base: str,
     stage_worktree_path: str, stage_head: str, stage_dirty: bool,
 ) -> "_FVTarget":
-    """단독-stage 검증 target. stage N 만 done + stage worktree 존재 + clean.
-    다른 stage 의 done/머지 여부와 무관. 위반 시 PrepareError."""
-    from .consumers import latest_done_by_stage
-    n = int(requested_stage)
-    done_by_stage = latest_done_by_stage(done_rows)
-    if n not in done_by_stage:
-        raise PrepareError(
-            f"final-verification(single-stage): stage {n} not done — "
-            f"run implementation --stage {n} first"
-        )
-    if not stage_worktree_path:
-        raise PrepareError(
-            f"final-verification(single-stage): stage worktree not found for "
-            f"stage {n} (torn down?) — use whole-task mode (--stage auto)"
-        )
-    if stage_dirty:
-        raise PrepareError(
-            "final-verification: worktree has uncommitted source changes "
-            "(outside .okstra/) — commit or stash before verifying"
+    """Compatibility wrapper for single-stage verification target selection."""
+    try:
+        return _stage_targets.resolve_single_stage_target(
+            requested_stage=requested_stage,
+            done_rows=done_rows,
+            stage_base=stage_base,
+            stage_worktree_path=stage_worktree_path,
+            stage_head=stage_head,
+            stage_dirty=stage_dirty,
         )
-    return _FVTarget(
-        scope="single-stage", base=stage_base, head=stage_head,
-        worktree_path=stage_worktree_path, stages=[n],
-        reports=[done_by_stage[n].get("report_path", "")],
-    )
+    except _stage_targets.StageTargetError as exc:
+        raise _stage_target_prepare_error(exc) from exc
 
 
 def _parse_stage_map_into_ctx(plan_path: str) -> list:
@@ -1511,23 +1382,13 @@ def _resolve_model_bindings(inp: PrepareInputs, workers: list[str]) -> _ModelBin
     )
 
 
-@dataclass
-class StageSelection:
-    """Result of `_select_and_provision_implementation_stage`.
-
-    Path-independent: carries the chosen stage + its isolated worktree
-    coordinates, separated from any run-artifact path so the caller can
-    resolve run paths AFTER the stage is known. `worktree_*` are empty when
-    the surrounding flow degraded (non-git / nested worktree); in that case
-    `started_head_commit` is the project HEAD instead of the worktree base."""
-    stage: int
-    worktree_path: str
-    worktree_branch: str
-    worktree_base_ref: str
-    worktree_status: str
-    worktree_note: str
-    started_head_commit: str
-    concurrent_stages: list = field(default_factory=list)
+StageSelection = _implementation_stage.StageSelection
+
+
+def _implementation_stage_prepare_error(
+    exc: _implementation_stage.ImplementationStageError,
+) -> PrepareError:
+    return PrepareError(str(exc))
 
 
 def _select_and_provision_implementation_stage(
@@ -1538,102 +1399,18 @@ def _select_and_provision_implementation_stage(
     task_key: str,
     executor_worktree_status: str,
 ) -> StageSelection:
-    """Resolve the first ready implementation stage and provision its isolated
-    worktree, without touching any run-artifact path.
-
-    spec §2.3: 한 run = 한 stage. `_resolve_effective_stages` 가 backward compat
-    로 batch 를 반환하지만 첫 번째만 실행한다 — stage 마다 격리 worktree·branch
-    가 필요해 batch 가 의미를 잃기 때문. `executor_worktree_status` 가
-    "skipped*" 면 worktree 없이 degrade 하고 project HEAD 만 기록한다."""
-    from .consumers import read_consumers, backfill_done_from_carry
-    from . import worktree as _worktree
-    from . import worktree_registry as _reg
-
-    plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
-    # carry sidecars are the SSOT for stage completion; recover any `done` rows
-    # the lead failed to append before the dependency gate reads them.
-    backfill_done_from_carry(plan_run_root)
-    _auto_reconcile_best_effort(inp, plan_run_root)
-    consumed = read_consumers(plan_run_root)
-    done_stages = {r["stage"] for r in consumed if r.get("status") == "done"}
-    started_stages = {r["stage"] for r in consumed if r.get("status") == "started"}
-    reserved_stages = _reg.list_active_stage_numbers(
-        inp.project_id, inp.task_group, inp.task_id,
-    )
-
-    batch = _resolve_effective_stages(
-        ctx_stage_map, done_stages, inp.stage,
-        started_stages=started_stages, reserved_stages=reserved_stages,
-    )
-    selected = batch[0]
-    # done stage 는 동시 run 이 아니다 — done 기록 시 점유는 해제되지만
-    # (consumers._release_stage_reservation), crash·구버전 기록의 잔존
-    # 예약이 남을 수 있어 읽기에서도 차감한다.
-    concurrent_stages = sorted(reserved_stages - done_stages - {selected})
-
-    # spec §2.1 degradation: 주변 흐름이 non-git / nested-worktree 로 skipped 면
-    # stage 격리도 동일하게 degrade — worktree 없이 project HEAD 만 기록.
-    if executor_worktree_status.startswith("skipped"):
-        head = _git_out(inp.project_root, "rev-parse", "HEAD")
-        return StageSelection(
-            stage=selected,
-            worktree_path="",
-            worktree_branch="",
-            worktree_base_ref="",
-            worktree_status=executor_worktree_status,
-            worktree_note="",
-            started_head_commit=head,
-            concurrent_stages=concurrent_stages,
-        )
-
-    # anchor base commit 1회 고정 (task-key worktree HEAD 기준)
-    head_sha = _git_out(inp.project_root, "rev-parse", "HEAD")
-    if head_sha:
-        _reg.set_implementation_base(
-            inp.project_id, inp.task_group, inp.task_id, head_sha,
-        )
-    anchor = _reg.get_implementation_base(
-        inp.project_id, inp.task_group, inp.task_id,
-    ) or ""
-
-    # stage 격리 worktree 발급 — 의존 종류별 base 결정
-    selected_stage = next(
-        s for s in ctx_stage_map if s["stage_number"] == selected
-    )
-    consumer_done_rows = [r for r in consumed if r.get("status") == "done"]
-    stage_base = _resolve_stage_base_commit(
-        selected_stage, consumer_done_rows, anchor_base_commit=anchor,
-        candidate_base=head_sha, project_root=Path(inp.project_root),
-        plan_run_root=plan_run_root,
-    )
+    """Compatibility wrapper for implementation stage selection."""
     try:
-        prov = _worktree.provision_stage_worktree(
-            project_root=Path(inp.project_root),
-            project_id=inp.project_id,
-            task_group_segment=task_group_segment,
-            task_id_segment=task_id_segment,
-            work_category=inp.work_category,
-            stage_number=selected,
-            base_commit=stage_base,
+        return _implementation_stage.select_and_provision_implementation_stage(
+            inp,
+            ctx_stage_map,
+            task_group_segment,
+            task_id_segment,
+            task_key,
+            executor_worktree_status,
         )
-    except RuntimeError as exc:
-        from .git_reconcile import guidance
-        hint = guidance(plan_run_root=plan_run_root, project_id=inp.project_id,
-                        task_group=inp.task_group, task_id=inp.task_id,
-                        work_category=inp.work_category)
-        raise PrepareError(
-            f"stage worktree provisioning failed: {exc}\n{hint}") from exc
-
-    return StageSelection(
-        stage=selected,
-        worktree_path=prov.path,
-        worktree_branch=prov.branch,
-        worktree_base_ref=prov.base_ref,
-        worktree_status=prov.status,
-        worktree_note=prov.note,
-        started_head_commit=prov.base_ref,
-        concurrent_stages=concurrent_stages,
-    )
+    except _implementation_stage.ImplementationStageError as exc:
+        raise _implementation_stage_prepare_error(exc) from exc
 
 
 def _apply_implementation_stage(
@@ -1642,44 +1419,8 @@ def _apply_implementation_stage(
     ctx_stage_map: list,
     sel: StageSelection,
 ) -> None:
-    """Wire a resolved `StageSelection` into ctx + consumers.jsonl. ctx-dependent
-    counterpart to `_select_and_provision_implementation_stage`."""
-    from .consumers import append_consumer
-    import datetime as _dt
-
-    ctx["parsed_stage_map"] = ctx_stage_map
-    ctx["effective_stages"] = [sel.stage]
-    csv = str(sel.stage)
-    ctx["EFFECTIVE_STAGES"] = csv
-    ctx["CONCURRENT_RUN_STAGES"] = ",".join(str(s) for s in sel.concurrent_stages)
-    ctx["STAGE_BATCH_DIRECTIVE"] = (
-        f"- **Stage for this implementation run:** `{csv}`. "
-        "Execute exactly this Stage Map stage — this is the authoritative scope. "
-        "Do NOT recompute from `consumers.jsonl`; the runtime already selected "
-        "and reserved this stage."
-    )
-    inp.stage = csv
-    # Observable contract: callers (okstra.sh, e2e harness) scan stdout for the
-    # resolved stage. Keep this line — it is the run's stage-selection receipt.
-    print(f"selected stages: {csv}", file=sys.stdout)
-
-    if sel.worktree_status and not sel.worktree_status.startswith("skipped"):
-        ctx["EXECUTOR_WORKTREE_PATH"] = sel.worktree_path
-        ctx["EXECUTOR_WORKTREE_BRANCH"] = sel.worktree_branch
-        ctx["EXECUTOR_WORKTREE_BASE_REF"] = sel.worktree_base_ref
-        ctx["EXECUTOR_WORKTREE_STATUS"] = sel.worktree_status
-        ctx["EXECUTOR_WORKTREE_NOTE"] = sel.worktree_note
-
-    now = _dt.datetime.now(_dt.timezone.utc).isoformat()
-    plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
-    append_consumer(
-        plan_run_root,
-        impl_task_key=ctx["TASK_KEY"],
-        stage=sel.stage,
-        status="started",
-        started_at=now,
-        head_commit=sel.started_head_commit,
-    )
+    """Compatibility wrapper for publishing implementation stage selection."""
+    _implementation_stage.apply_implementation_stage(inp, ctx, ctx_stage_map, sel)
 
 
 def _git_out(cwd, *args) -> str:
@@ -1689,17 +1430,7 @@ def _git_out(cwd, *args) -> str:
 
 
 def _auto_reconcile_best_effort(inp: "PrepareInputs", plan_run_root: Path) -> None:
-    try:
-        from .git_reconcile import auto_reconcile
-        for it in auto_reconcile(
-                project_root=Path(inp.project_root), plan_run_root=plan_run_root,
-                project_id=inp.project_id, task_group=inp.task_group,
-                task_id=inp.task_id, work_category=inp.work_category):
-            print(f"git-reconcile: stage {it.stage} done commit "
-                  f"{it.recorded[:8]} -> {it.suggested_commit[:8]} "
-                  "(patch-equivalent)", file=sys.stdout)
-    except Exception as exc:  # 화해는 부가 기능 — 실패 시 기존 gate 가 판정
-        print(f"git-reconcile skipped: {exc}", file=sys.stderr)
+    _stage_auto_reconcile_best_effort(inp, plan_run_root)
 
 
 def _is_ancestor(cwd, commit, head) -> bool:

package/runtime/python/okstra_ctl/stage_reconcile.py

@@ -0,0 +1,33 @@
+"""Best-effort git reconciliation shared by stage prepare flows."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def auto_reconcile_best_effort(inp: Any, plan_run_root: Path) -> None:
+    """Run patch-equivalence reconciliation without changing prepare outcome.
+
+    Reconciliation is advisory: failures are reported to stderr and the normal
+    dependency gates still make the authoritative decision.
+    """
+    try:
+        from .git_reconcile import auto_reconcile
+
+        for item in auto_reconcile(
+            project_root=Path(inp.project_root),
+            plan_run_root=plan_run_root,
+            project_id=inp.project_id,
+            task_group=inp.task_group,
+            task_id=inp.task_id,
+            work_category=inp.work_category,
+        ):
+            print(
+                f"git-reconcile: stage {item.stage} done commit "
+                f"{item.recorded[:8]} -> {item.suggested_commit[:8]} "
+                "(patch-equivalent)",
+                file=sys.stdout,
+            )
+    except Exception as exc:
+        print(f"git-reconcile skipped: {exc}", file=sys.stderr)

package/runtime/python/okstra_ctl/stage_targets.py

@@ -0,0 +1,277 @@
+"""Stage readiness and verification target rules.
+
+This module owns the policy that decides which Stage Map stage can run, which
+commit it branches from, and what final-verification should inspect. It keeps
+the stage lifecycle rules behind one interface instead of leaking raw
+``consumers.jsonl`` rows and git ancestry checks into prepare callers.
+"""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+RUN_STEP_BUDGET = 8
+
+
+class StageTargetError(Exception):
+    """Stage target selection or verification precondition failed."""
+
+
+@dataclass
+class FinalVerificationTarget:
+    scope: str            # "whole-task" | "single-stage"
+    base: str
+    head: str
+    worktree_path: str
+    stages: list[int]
+    reports: list[str]
+
+
+def resolve_effective_stages(
+    stages: list[dict[str, Any]],
+    done_stages: set[int],
+    requested: str,
+    budget: int = RUN_STEP_BUDGET,
+    started_stages: set[int] | None = None,
+    reserved_stages: set[int] | None = None,
+) -> list[int]:
+    """Return ordered stage numbers this run should execute.
+
+    ``requested`` is ``"auto"`` or a decimal string. Auto selection returns all
+    ready stages within the step budget, excluding done/started/reserved stages.
+    Numeric selection returns one forced stage.
+    """
+    started_stages = started_stages or set()
+    reserved_stages = reserved_stages or set()
+    occupied = done_stages | started_stages | reserved_stages
+    if requested != "auto":
+        try:
+            n = int(requested)
+        except ValueError as exc:
+            raise StageTargetError(
+                f"--stage must be 'auto' or an integer, got {requested!r}"
+            ) from exc
+        target = next((s for s in stages if s["stage_number"] == n), None)
+        if target is None:
+            raise StageTargetError(
+                f"--stage {n} not in Stage Map "
+                f"(have {[s['stage_number'] for s in stages]})"
+            )
+        if n in done_stages:
+            raise StageTargetError(
+                f"--stage {n} already completed (consumers.jsonl status:done exists)"
+            )
+        if n in started_stages or n in reserved_stages:
+            raise StageTargetError(
+                f"--stage {n} already in progress or reserved by another run"
+            )
+        return [n]
+
+    ready = [
+        s for s in stages
+        if s["stage_number"] not in occupied
+        and all(d in done_stages for d in s["depends_on"])
+    ]
+    if not ready:
+        raise StageTargetError(
+            "no stage is ready: every remaining stage has unsatisfied depends-on"
+        )
+    batch: list[int] = []
+    total = 0
+    for stage in ready:
+        step_count = stage.get("step_count", 0) or 0
+        if batch and total + step_count > budget:
+            break
+        batch.append(stage["stage_number"])
+        total += step_count
+    return batch
+
+
+def commit_is_ancestor(project_root: Path, ancestor: str, descendant: str) -> bool:
+    """True iff ``ancestor`` is an ancestor of ``descendant`` in git history."""
+    result = subprocess.run(
+        ["git", "merge-base", "--is-ancestor", ancestor, descendant],
+        cwd=str(project_root),
+        capture_output=True,
+        text=True,
+    )
+    return result.returncode == 0
+
+
+def check_multi_dep_merged(
+    project_root: Path,
+    plan_run_root: Path | None,
+    latest: dict[int, dict[str, Any]],
+    pred_commits: dict[int, str],
+    candidate_base: str,
+    stage_n: int,
+) -> None:
+    """Ensure all predecessor commits are merged into the candidate base."""
+    from .git_reconcile import content_merged, _record_reconciled
+
+    for dep_stage, head in pred_commits.items():
+        if commit_is_ancestor(project_root, head, candidate_base):
+            continue
+        match = content_merged(project_root, head, candidate_base)
+        if match.status in ("ancestor", "patch-equivalent"):
+            if plan_run_root is not None:
+                _record_reconciled(
+                    plan_run_root,
+                    impl_task_key=(latest.get(dep_stage) or {}).get("impl_task_key", ""),
+                    stage=dep_stage,
+                    new_commit=match.matched_commit,
+                    replaced=head,
+                    reason="auto-patch-id",
+                )
+            continue
+        raise StageTargetError(
+            f"multi-dependency stage {stage_n}: predecessor stage {dep_stage} "
+            f"({head[:8]}) is not merged into the task worktree "
+            f"({candidate_base[:8]}). Merge stage branches "
+            f"(e.g. the `-s{dep_stage}` branches) into the task worktree "
+            "(or into main, then refresh the worktree) and retry."
+        )
+
+
+def resolve_stage_base_commit(
+    stage: dict[str, Any],
+    consumer_done_rows: list[dict[str, Any]],
+    anchor_base_commit: str,
+    candidate_base: str = "",
+    project_root: Path | None = None,
+    plan_run_root: Path | None = None,
+) -> str:
+    """Pick the git base commit a stage's isolated worktree branches from."""
+    from .consumers import latest_done_by_stage
+
+    latest = latest_done_by_stage(consumer_done_rows)
+    deps = stage.get("depends_on") or []
+    if len(deps) >= 2:
+        stage_number = stage["stage_number"]
+        pred_commits: dict[int, str] = {}
+        for dep_stage in deps:
+            head = (latest.get(dep_stage) or {}).get("head_commit")
+            if not head:
+                raise StageTargetError(
+                    f"predecessor stage {dep_stage} has no done row with head_commit "
+                    f"in consumers.jsonl; multi-dependency stage {stage_number} cannot start"
+                )
+            pred_commits[dep_stage] = head
+        if not candidate_base or project_root is None:
+            raise StageTargetError(
+                f"candidate base missing for multi-dependency stage {stage_number}; "
+                "task-key worktree HEAD could not be resolved"
+            )
+        check_multi_dep_merged(
+            project_root,
+            plan_run_root,
+            latest,
+            pred_commits,
+            candidate_base,
+            stage_number,
+        )
+        return candidate_base
+    if not deps:
+        if not anchor_base_commit:
+            raise StageTargetError(
+                f"anchor base commit missing for independent stage "
+                f"{stage['stage_number']}; first-stage prepare should have "
+                "fixed it via worktree_registry.set_implementation_base"
+            )
+        return anchor_base_commit
+    pred = deps[0]
+    head = (latest.get(pred) or {}).get("head_commit") or ""
+    if head:
+        return head
+    raise StageTargetError(
+        f"predecessor stage {pred} has no done row with head_commit in "
+        "consumers.jsonl; cannot derive base for stage "
+        f"{stage['stage_number']}"
+    )
+
+
+def resolve_whole_task_target(
+    *,
+    stage_map: list[dict[str, Any]],
+    done_rows: list[dict[str, Any]],
+    anchor_base: str,
+    task_worktree_path: str,
+    task_head: str,
+    task_dirty: bool,
+    merged: dict[int, bool],
+) -> FinalVerificationTarget:
+    """Resolve whole-task final-verification target, enforcing all gates."""
+    from .consumers import latest_done_by_stage
+
+    done_by_stage = latest_done_by_stage(done_rows)
+    for stage in stage_map:
+        n = stage["stage_number"]
+        if n not in done_by_stage:
+            raise StageTargetError(
+                f"final-verification(whole-task): stage {n} not done — "
+                f"run implementation --stage {n} first"
+            )
+        if not merged.get(n, False):
+            sha = done_by_stage[n].get("head_commit", "")
+            raise StageTargetError(
+                f"final-verification(whole-task): stage {n} done commit "
+                f"{sha} not merged into task worktree HEAD — merge stage "
+                "branches then retry"
+            )
+    if task_dirty:
+        raise StageTargetError(
+            "final-verification: worktree has uncommitted source changes "
+            "(outside .okstra/) — commit or stash before verifying"
+        )
+    stages = [s["stage_number"] for s in stage_map]
+    reports = [done_by_stage[n].get("report_path", "") for n in stages]
+    return FinalVerificationTarget(
+        scope="whole-task",
+        base=anchor_base,
+        head=task_head,
+        worktree_path=task_worktree_path,
+        stages=stages,
+        reports=reports,
+    )
+
+
+def resolve_single_stage_target(
+    *,
+    requested_stage: str,
+    done_rows: list[dict[str, Any]],
+    stage_base: str,
+    stage_worktree_path: str,
+    stage_head: str,
+    stage_dirty: bool,
+) -> FinalVerificationTarget:
+    """Resolve single-stage final-verification target, enforcing all gates."""
+    from .consumers import latest_done_by_stage
+
+    n = int(requested_stage)
+    done_by_stage = latest_done_by_stage(done_rows)
+    if n not in done_by_stage:
+        raise StageTargetError(
+            f"final-verification(single-stage): stage {n} not done — "
+            f"run implementation --stage {n} first"
+        )
+    if not stage_worktree_path:
+        raise StageTargetError(
+            f"final-verification(single-stage): stage worktree not found for "
+            f"stage {n} (torn down?) — use whole-task mode (--stage auto)"
+        )
+    if stage_dirty:
+        raise StageTargetError(
+            "final-verification: worktree has uncommitted source changes "
+            "(outside .okstra/) — commit or stash before verifying"
+        )
+    return FinalVerificationTarget(
+        scope="single-stage",
+        base=stage_base,
+        head=stage_head,
+        worktree_path=stage_worktree_path,
+        stages=[n],
+        reports=[done_by_stage[n].get("report_path", "")],
+    )