okstra 0.97.1 → 0.98.1

package/runtime/python/okstra_ctl/run.py

@@ -91,6 +91,7 @@ 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 .plan_run_root import plan_run_root_from_approved_plan
 from . import stage_integrate as _stage_integrate
 from . import implementation_stage as _implementation_stage
 from .stage_reconcile import (
@@ -287,8 +288,9 @@ def _set_data_json_approved_true_if_present(path: Path) -> bool:
     return True
 
 
-class PrepareError(Exception):
-    """surface to caller — task bundle prepare failed."""
+# PrepareError 는 stage_targets(저수준)에 정의돼 final-verification 과 container
+# 가 whole-task 통합 실패를 동일 타입으로 받는다. run.py 는 재노출만 한다.
+PrepareError = _stage_targets.PrepareError
 
 
 _ALLOWED_LEAD_RUNTIMES = ALLOWED_LEAD_RUNTIMES
@@ -543,9 +545,27 @@ def _resolve_single_stage_target(
         raise _stage_target_prepare_error(exc) from exc
 
 
-def _parse_stage_map_into_ctx(plan_path: str) -> list:
-    """Reuse the validator's parser to extract StageMeta dicts for the ctx."""
-    text = Path(plan_path).read_text(encoding="utf-8")
+def _stage_map_reject_detail(stages, errs):
+    """빈/손상 Stage Map 의 거부 사유 문자열을 돌려준다. 정상이면 None.
+
+    빈/손상 Stage Map 을 흘려보내면 whole-task 완료 게이트
+    (resolve_whole_task_target 의 `for stage in stage_map`)가 0회 순회로 vacuous
+    통과해 미완 task 를 '완성'으로 배포·검증한다. 빈 파싱(heading rename·표 손상)과
+    stage 번호 비단조(중간 행 누락 → S2)의 판정을 한 곳에 모아, run.py 의 prepare
+    게이트와 wizard 의 stage picker 가 같은 기준을 상속하게 한다(single-reference)."""
+    if stages and not errs:
+        return None
+    return (
+        "; ".join(e.message for e in errs) if errs
+        else "'## 5.5 Stage Map' heading 이 없거나 표가 비었습니다")
+
+
+def _load_parsed_stage_map(text: str):
+    """validator 모듈을 로드해 `_parse_stage_map(text)` 의 (stages, errs) 를 돌려준다.
+
+    run.py 와 wizard 가 공유하는 단일 validator-load 경로 — 둘 다 `_STAGE_VALIDATOR_PATH`
+    (설치 시 `~/.okstra/lib/validators` 로 배치돼 `parents[2]/validators` 로 해소)로
+    수렴해 경로 해소가 갈라지지 않게 한다."""
     spec = importlib.util.spec_from_file_location(
         "_ip_stage_validator", _STAGE_VALIDATOR_PATH
     )
@@ -557,9 +577,20 @@ def _parse_stage_map_into_ctx(plan_path: str) -> list:
     sys.modules["_ip_stage_validator"] = mod
     try:
         spec.loader.exec_module(mod)
+        return mod._parse_stage_map(text)
     finally:
         sys.modules.pop("_ip_stage_validator", None)
-    stages, _errs = mod._parse_stage_map(text)
+
+
+def _parse_stage_map_into_ctx(plan_path: str) -> list:
+    """Reuse the validator's parser to extract StageMeta dicts for the ctx."""
+    text = Path(plan_path).read_text(encoding="utf-8")
+    stages, errs = _load_parsed_stage_map(text)
+    detail = _stage_map_reject_detail(stages, errs)
+    if detail is not None:
+        raise PrepareError(
+            f"approved-plan 의 Stage Map 을 신뢰할 수 없어 거부합니다 ({plan_path}): "
+            f"{detail}. plan 의 Stage Map 을 점검하세요.")
     return [
         {
             "stage_number": s.stage_number,
@@ -1105,9 +1136,7 @@ def _materialize_release_handoff_input(
     if not plan.is_file():
         raise PrepareError(f"approved plan not found: {plan}")
     stage_map = _parse_stage_map_into_ctx(str(plan))
-    if not stage_map:
-        raise PrepareError(f"approved plan has no parsable Stage Map: {plan}")
-    rows = read_consumers(plan.resolve().parents[1])
+    rows = read_consumers(plan_run_root_from_approved_plan(plan))
 
     if inp.stages:
         try:
@@ -1488,7 +1517,7 @@ def _reserve_final_verification_target(
     from .consumers import read_consumers, backfill_done_from_carry
     from . import worktree_registry as _reg
 
-    plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
+    plan_run_root = plan_run_root_from_approved_plan(inp.approved_plan_path)
     # carry sidecars are the SSOT for stage completion — recover missing `done`
     # rows before the whole-task gate checks every stage.
     backfill_done_from_carry(plan_run_root)
@@ -1520,27 +1549,16 @@ def _reserve_final_verification_target(
         wt_path = ctx["EXECUTOR_WORKTREE_PATH"]
         anchor = _reg.get_implementation_base(
             inp.project_id, inp.task_group, inp.task_id) or ""
-        try:
-            integ = _stage_integrate.integrate_stages(
-                project_id=inp.project_id, task_group=inp.task_group,
-                task_id=inp.task_id, task_worktree_path=wt_path,
-                stage_map=ctx_stage_map, done_rows=done_rows,
-            )
-        except _stage_integrate.IntegrateError as exc:
-            raise PrepareError(str(exc)) from exc
-        ctx["STAGE_INTEGRATION"] = _format_integration(integ)
-        head = _git_out(wt_path, "rev-parse", "HEAD")
-        # integrate 가 registry 기반으로 머지/skip 한 것과 별개로, 각 stage done
-        # commit 이 실제 task HEAD 의 ancestor 인지 ground-truth 로 확인한다 —
-        # stage-key 가 이미 teardown 된 stage 라도 커밋이 HEAD 에 남아있으면 통과.
-        from .consumers import latest_done_by_stage
-        merged = {s: _is_ancestor(wt_path, r.get("head_commit", ""), head)
-                  for s, r in latest_done_by_stage(done_rows).items()}
-        target = _resolve_whole_task_target(
-            stage_map=ctx_stage_map, done_rows=done_rows, anchor_base=anchor,
-            task_worktree_path=wt_path, task_head=head,
-            task_dirty=_is_dirty_excluding_okstra(wt_path), merged=merged,
+        # whole-task 통합(머지+teardown)+게이트 강제는 container 와 공유하는
+        # 순수 헬퍼가 단일 책임. ctx 주입만 run.py 측에 남긴다.
+        whole = _stage_targets.resolve_and_integrate_whole_task(
+            project_id=inp.project_id, task_group=inp.task_group,
+            task_id=inp.task_id, task_worktree_path=wt_path,
+            stage_map=ctx_stage_map, done_rows=done_rows,
+            anchor_base=anchor, teardown=True,
         )
+        ctx["STAGE_INTEGRATION"] = _format_integration(whole["integrate_result"])
+        target = whole["target"]
 
     diff_stat = _git_out(target.worktree_path, "diff", "--stat",
                          f"{target.base}..{target.head}")

package/runtime/python/okstra_ctl/stage_integrate.py

@@ -60,8 +60,13 @@ def integrate_stages(
     *, project_id: str, task_group: str, task_id: str,
     task_worktree_path: str, stage_map: list[dict[str, Any]],
     done_rows: list[dict[str, Any]],
+    teardown: bool = True,
 ) -> IntegrateResult:
-    """whole-task 통합: Phase A 머지 → Phase B teardown."""
+    """whole-task 통합: Phase A 머지 → Phase B teardown.
+
+    teardown=False 면 Phase B(stage worktree·브랜치·registry 키 정리)를 건너뛴다 —
+    container 는 머지만 하고 stage 트리를 보존한다(스펙 §10). final-verification
+    호출은 기본값(True)으로 기존 행위를 유지한다."""
     from .consumers import latest_done_by_stage
 
     res = IntegrateResult()
@@ -91,7 +96,8 @@ def integrate_stages(
             raise
         (res.merged if outcome == "merged" else res.already_merged).append(n)
 
-    _teardown_all(project_id, task_group, task_id, task_worktree_path, res)
+    if teardown:
+        _teardown_all(project_id, task_group, task_id, task_worktree_path, res)
     return res
 
 

package/runtime/python/okstra_ctl/stage_targets.py

@@ -19,6 +19,14 @@ class StageTargetError(Exception):
     """Stage target selection or verification precondition failed."""
 
 
+class PrepareError(Exception):
+    """surface to caller — task bundle prepare failed.
+
+    Defined here(저수준 모듈)so both run.py(final-verification)와
+    container.py 가 whole-task 통합 헬퍼의 실패를 동일 타입으로 받을 수 있다.
+    run.py 는 이 클래스를 그대로 재노출한다(단일 참조점)."""
+
+
 @dataclass
 class FinalVerificationTarget:
     scope: str            # "whole-task" | "single-stage"
@@ -232,6 +240,77 @@ def resolve_whole_task_target(
     )
 
 
+def _merged_stage_map(
+    task_worktree_path: str, done_rows: list[dict[str, Any]], head: str,
+) -> dict[int, bool]:
+    """각 stage 의 done commit 이 실제 task HEAD 의 ancestor 인지 ground-truth 로
+    판정한다 — stage-key 가 teardown 됐어도 커밋이 HEAD 에 남아있으면 merged.
+    run.py 의 기존 패턴을 그대로 옮긴 것."""
+    from .consumers import latest_done_by_stage
+    from .worktree import is_ancestor
+
+    return {
+        s: is_ancestor(task_worktree_path, r.get("head_commit", ""), head)
+        for s, r in latest_done_by_stage(done_rows).items()
+    }
+
+
+def resolve_and_integrate_whole_task(
+    *, project_id: str, task_group: str, task_id: str,
+    task_worktree_path: str, stage_map: list[dict[str, Any]],
+    done_rows: list[dict[str, Any]], anchor_base: str, teardown: bool,
+) -> dict[str, Any]:
+    """whole-task stage 통합(머지[+선택 teardown]) → 게이트 강제 → target 해소.
+
+    final-verification(teardown=True)과 container(teardown=False)의 단일 참조점.
+    ctx/PrepareInputs 결합 없는 헬퍼. 머지 충돌·미머지·dirty(.okstra 외)면
+    `PrepareError`. 반환: head_commit / merged_stage_map / target_ref / target /
+    integrate_result.
+
+    머지(`git merge`)+teardown 은 task-key 단위 `worktree_provision_mutex` 로
+    감싼다 — 동시 `container up` 둘 또는 container up × whole-task
+    final-verification 이 같은 공유 worktree 의 index/HEAD 에 동시에 머지하면
+    index.lock 충돌·반쯤 적용된 머지로 트리가 깨진다. 두 호출 지점(container 의
+    `_integrate_source_tree`, run.py 의 `_reserve_final_verification_target`)
+    모두 이 락 밖에서 진입하므로 self-deadlock 없이 여기서 1회만 잡는다."""
+    from .stage_integrate import IntegrateError, integrate_stages
+    from .worktree import _git, is_dirty_excluding_okstra
+    from .locks import worktree_provision_mutex
+    from okstra_project.dirs import okstra_home
+    from okstra_project.state import slugify
+
+    with worktree_provision_mutex(
+        okstra_home(), project_id, slugify(task_group), slugify(task_id),
+    ):
+        try:
+            integ = integrate_stages(
+                project_id=project_id, task_group=task_group, task_id=task_id,
+                task_worktree_path=task_worktree_path, stage_map=stage_map,
+                done_rows=done_rows, teardown=teardown,
+            )
+        except IntegrateError as exc:
+            raise PrepareError(str(exc)) from exc
+
+        head = _git(task_worktree_path, "rev-parse", "HEAD").stdout.strip()
+        merged = _merged_stage_map(task_worktree_path, done_rows, head)
+        try:
+            target = resolve_whole_task_target(
+                stage_map=stage_map, done_rows=done_rows, anchor_base=anchor_base,
+                task_worktree_path=task_worktree_path, task_head=head,
+                task_dirty=is_dirty_excluding_okstra(task_worktree_path),
+                merged=merged,
+            )
+        except StageTargetError as exc:
+            raise PrepareError(str(exc)) from exc
+    return {
+        "head_commit": head,
+        "merged_stage_map": merged,
+        "target_ref": target.head,
+        "target": target,
+        "integrate_result": integ,
+    }
+
+
 def resolve_single_stage_target(
     *,
     requested_stage: str,

package/runtime/python/okstra_ctl/time_report.py

@@ -0,0 +1,200 @@
+"""Read-side time aggregation for a task.
+
+timeline.json 의 runs[] 를 순회하며 각 run 의 team-state(leadUsage/workers
+usage)를 읽어, task-type·worker 별 cross-run roll-up 과 per-run wall-clock /
+phase timeline 을 만든다. skill markdown 이 LLM 에게 시키던 집계(byTaskType /
+perWorker)를 코드 SSOT 로 옮긴 것 — 출력은 raw ms 이고 HH:MM:SS 포맷·Markdown
+표 렌더는 호출자(skill)에 남긴다.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import sys
+from pathlib import Path
+
+from okstra_ctl.paths import resolve_under_root
+from okstra_ctl.task_target import resolve_task_root
+
+
+def _load_runs(task_root: Path) -> list[dict]:
+    try:
+        data = json.loads((task_root / "history" / "timeline.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return []
+    runs = data.get("runs", [])
+    return runs if isinstance(runs, list) else []
+
+
+def _task_key(task_root: Path) -> str:
+    try:
+        return json.loads((task_root / "task-manifest.json").read_text(encoding="utf-8")).get("taskKey", "")
+    except (OSError, ValueError):
+        return ""
+
+
+def _duration_ms(block) -> int:
+    """usage / leadUsage block 의 durationMs — na_block·missing·None 은 0."""
+    block = block or {}
+    if block.get("source") == "unavailable":
+        return 0
+    try:
+        return int(block.get("durationMs", 0) or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _parse_iso(value: str) -> dt.datetime:
+    return dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _wall_clock_ms(state: dict) -> int:
+    """run 의 실제 경과(벽시계) = max(endedAt) − min(startedAt). lead·worker 윈도가
+    겹치므로 cpuSum 과 다르다. timestamp 부족하면 0."""
+    times: list[dt.datetime] = []
+    blocks = [state.get("leadUsage")] + [
+        w.get("usage") for w in (state.get("workers") or []) if isinstance(w, dict)]
+    for block in blocks:
+        block = block or {}
+        if block.get("source") == "unavailable":
+            continue
+        for key in ("startedAt", "endedAt"):
+            raw = block.get(key)
+            if not raw:
+                continue
+            try:
+                times.append(_parse_iso(raw))
+            except (TypeError, ValueError):
+                pass
+    if len(times) < 2:
+        return 0
+    return int((max(times) - min(times)).total_seconds() * 1000)
+
+
+def _phase_rows(state: dict) -> list[dict]:
+    pt = state.get("phaseTimeline")
+    if not isinstance(pt, dict):
+        return []
+    return [{"phase": ph.get("phase", ""), "firstAt": ph.get("firstAt", ""),
+             "wallMsToNext": ph.get("wallMsToNext")}
+            for ph in (pt.get("phases") or []) if isinstance(ph, dict)]
+
+
+def _read_state(project_root: Path, rel: str) -> dict | None:
+    target = resolve_under_root(project_root, rel)
+    if target is None:
+        return None
+    try:
+        state = json.loads(target.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    return state if isinstance(state, dict) else None
+
+
+def _collect_run(run: dict, project_root: Path) -> dict:
+    """timeline run + team-state → 정규화된 측정. 결과에 `unavailable` reason 또는
+    측정 필드(leadMs/workers/wallClockMs/phases)를 담는다."""
+    ts, task_type = run.get("runTimestamp", ""), run.get("taskType", "")
+    base = {"runTimestamp": ts, "taskType": task_type}
+    state = _read_state(project_root, run.get("teamStatePath", ""))
+    if state is None:
+        return {**base, "reason": "team-state missing"}
+    lead = _duration_ms(state.get("leadUsage"))
+    workers = [{"workerId": w.get("workerId", ""), "agent": w.get("agent", ""),
+                "durationMs": _duration_ms(w.get("usage"))}
+               for w in (state.get("workers") or []) if isinstance(w, dict)]
+    if lead == 0 and all(w["durationMs"] == 0 for w in workers):
+        return {**base, "reason": "no durationMs (Phase 7 not reached)"}
+    return {**base, "leadMs": lead, "workers": workers,
+            "wallClockMs": _wall_clock_ms(state), "phases": _phase_rows(state)}
+
+
+def _by_task_type(collected: list[dict]) -> list[dict]:
+    order: list[str] = []
+    acc: dict[str, dict] = {}
+    for run in collected:
+        tt = run["taskType"]
+        if tt not in acc:
+            acc[tt] = {"taskType": tt, "runs": 0, "leadMs": 0, "workersMs": 0}
+            order.append(tt)
+        acc[tt]["runs"] += 1
+        acc[tt]["leadMs"] += run["leadMs"]
+        acc[tt]["workersMs"] += sum(w["durationMs"] for w in run["workers"])
+    for tt in order:
+        acc[tt]["cpuSumMs"] = acc[tt]["leadMs"] + acc[tt]["workersMs"]
+    return [acc[tt] for tt in order]
+
+
+def _add_worker(agg: dict, order: list, wid: str, agent: str, ms: int) -> None:
+    if wid not in agg:
+        agg[wid] = {"runs": 0, "totalMs": 0, "agents": set()}
+        order.append(wid)
+    if ms > 0:
+        agg[wid]["runs"] += 1
+        agg[wid]["totalMs"] += ms
+        if agent:
+            agg[wid]["agents"].add(agent)
+
+
+def _per_worker(collected: list[dict]) -> dict:
+    out: dict[str, list[dict]] = {}
+    for tt in dict.fromkeys(r["taskType"] for r in collected):
+        agg: dict[str, dict] = {}
+        order: list[str] = []
+        for run in (r for r in collected if r["taskType"] == tt):
+            _add_worker(agg, order, "lead", "", run["leadMs"])
+            for w in run["workers"]:
+                _add_worker(agg, order, w["workerId"], w["agent"], w["durationMs"])
+        rows = []
+        for wid in order:
+            a = agg[wid]
+            if a["runs"] == 0:
+                continue
+            agents = sorted(x for x in a["agents"] if x and x != wid)
+            rows.append({"workerId": wid, "agents": agents, "runs": a["runs"],
+                         "totalMs": a["totalMs"], "avgMs": a["totalMs"] // a["runs"]})
+        out[tt] = rows
+    return out
+
+
+def aggregate_time(runs: list[dict], project_root: Path) -> dict:
+    collected, unavailable = [], []
+    for run in runs:
+        if not isinstance(run, dict):
+            continue
+        c = _collect_run(run, project_root)
+        (unavailable if "reason" in c else collected).append(c)
+    by_tt = _by_task_type(collected)
+    grand = {k: sum(r[k] for r in by_tt) for k in ("runs", "leadMs", "workersMs", "cpuSumMs")}
+    return {
+        "byTaskType": by_tt,
+        "grandTotal": grand,
+        "perWorker": _per_worker(collected),
+        "perRunWallClock": [{"runTimestamp": c["runTimestamp"], "taskType": c["taskType"],
+                             "wallClockMs": c["wallClockMs"]} for c in collected],
+        "phaseTimelines": [{"runTimestamp": c["runTimestamp"], "taskType": c["taskType"],
+                            "phases": c["phases"]} for c in collected if c["phases"]],
+        "unavailable": unavailable,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="okstra time-report",
+        description="Aggregate elapsed work time across a task's runs (raw ms).")
+    parser.add_argument("target", help="task root path or task-key")
+    parser.add_argument("--project-root", default="")
+    parser.add_argument("--cwd", default=".")
+    parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
+    args = parser.parse_args(argv)
+
+    task_root, project_root = resolve_task_root(args.target, args.project_root, args.cwd)
+    result = {"ok": True, "taskKey": _task_key(task_root)}
+    result.update(aggregate_time(_load_runs(task_root), project_root))
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/tmux.py

@@ -10,6 +10,13 @@ from pathlib import Path
 from typing import Optional, Sequence
 
 
+# container watcher/tail pane 전용 태그. SessionEnd `--reap`
+# (scripts/okstra-trace-cleanup.sh `_tag_in_scope`)는 `@okstra_trace_run` /
+# `@okstra_worker_run` 만 스캔하므로, 이 태그가 붙은 pane 은 세션 종료 후에도
+# 생존한다 — watcher/tail 의 "세션 후 생존" 불변식의 핵심.
+CONTAINER_TAG_OPTION = "@okstra_container_run"
+
+
 @dataclass(frozen=True)
 class TmuxPane:
     pane_id: str
@@ -135,6 +142,66 @@ def split_worker_pane(
     return pane_id
 
 
+def new_detached_session(
+    session_name: str, cwd: str, first_cmd: str | None = None
+) -> str:
+    """detached tmux 세션을 띄우고 첫 pane id 를 반환한다.
+
+    cmd-rerun.sh 의 detached spawn 패턴을 python 으로 옮긴 것
+    (`tmux new-session -d -s <name> -c <cwd> [cmd]`). `-P -F #{pane_id}` 로
+    생성된 pane id 를 받아 이후 split_container_pane 의 `-t` 대상으로 쓴다.
+    first_cmd 미지정 시 기본 셸이 첫 pane 을 점유한다 — `true` 처럼 즉시 끝나는
+    명령을 주면 단일-윈도우 세션이 split 전에 무너질 수 있으므로(remain-on-exit
+    off), holder pane 은 오래 사는 명령이어야 한다.
+    """
+    args = ["new-session", "-d", "-s", session_name, "-c", cwd,
+            "-P", "-F", "#{pane_id}"]
+    if first_cmd:
+        args.append(first_cmd)
+    result = run_tmux(args)
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or "tmux new-session failed")
+    return result.stdout.strip()
+
+
+def split_container_pane(
+    *,
+    session_pane: Optional[str],
+    cwd: str,
+    command: str,
+    title: str,
+    scope_value: str,
+    kind: str,
+) -> Optional[str]:
+    """container watcher/tail pane 을 split 하고 container 전용 태그만 부착한다.
+
+    reap 가 스캔하는 두 worker/trace 태그는 절대 부착하지 않는다 — tag_pane 의
+    기본 경로를 거치지 않고 CONTAINER_TAG_OPTION 으로 직접 set-option 한다.
+    session_pane 가 빈값/None(tmux 미사용 경로)이면 raise 없이 None 반환(degrade).
+    """
+    if not session_pane:
+        return None
+    result = run_tmux(
+        ["split-window", "-h", "-P", "-F", "#{pane_id}",
+         "-c", cwd, "-t", session_pane, command]
+    )
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or "tmux split-window failed")
+    pane_id = result.stdout.strip()
+    set_pane_title(pane_id, title)
+    tag_container_pane(pane_id, scope_value)
+    return pane_id
+
+
+def tag_container_pane(pane_id: str, scope_value: str) -> None:
+    """container 전용 태그(CONTAINER_TAG_OPTION)만 부착한다.
+
+    reap 가 스캔하는 worker/trace 태그(tag_pane 기본 경로)는 절대 거치지 않는다 —
+    이 태그가 붙은 pane 은 세션 종료 후에도 생존하고 `down`/`stop-watcher` 의
+    스코프 reap 로만 회수된다. holder pane 도 이 태그로 묶어 회수 대상에 포함한다."""
+    run_tmux(["set-option", "-p", "-t", pane_id, CONTAINER_TAG_OPTION, scope_value])
+
+
 def set_pane_title(pane_id: str, title: str) -> None:
     result = run_tmux(["select-pane", "-t", pane_id, "-T", title])
     if result.returncode != 0:

package/runtime/python/okstra_ctl/wizard.py

@@ -41,8 +41,10 @@ from okstra_ctl.run import (
     _apply_cli_implementation_option,
     _extract_frontmatter_block,
     _load_final_report_data_if_present,
+    _load_parsed_stage_map,
     _reject_blocking_plan_body_gate,
     _set_data_json_approved_true_if_present,
+    _stage_map_reject_detail,
     recommended_role_models,
 )
 from okstra_ctl.user_response import (
@@ -934,22 +936,25 @@ def _stage_auto_allowed(state: WizardState) -> bool:
 
 def _parse_stage_objects(state: WizardState) -> list:
     """승인 plan 의 Stage Map stage 객체 목록. validator 의 _parse_stage_map 재사용.
-    `_build_stage_pick` 과 `_whole_task_allowed` 가 공유한다."""
-    import importlib.util as _ilu
-    import sys as _sys
+    `_build_stage_pick` 과 `_whole_task_allowed` 가 공유한다.
+
+    빈/손상 Stage Map 은 prepare 게이트(`_parse_stage_map_into_ctx`)와 같은 기준
+    (`_stage_map_reject_detail`)으로 거부한다 — 안 그러면 손상된 맵이 stage 일부만
+    파싱돼 picker 가 '전체 task' 검증을 제안·수락하지만 prepare 가 같은 맵을 하드
+    거부하는 불일치가 생긴다.
+
+    validator 로드는 prepare 와 같은 단일 경로(`_load_parsed_stage_map`)로 위임하고,
+    PrepareError 는 picker 디스패처가 처리하는 WizardError 로 변환한다."""
     plan_text = Path(state.approved_plan_path).read_text(encoding="utf-8")
-    validator_path = (Path(state.workspace_root) / "validators"
-                      / "validate-implementation-plan-stages.py")
-    spec = _ilu.spec_from_file_location("_ip_stage_v_wizard", str(validator_path))
-    if spec is None or spec.loader is None:
-        raise WizardError(f"cannot load stage validator at {validator_path}")
-    mod = _ilu.module_from_spec(spec)
-    _sys.modules["_ip_stage_v_wizard"] = mod
     try:
-        spec.loader.exec_module(mod)
-        stages, _errs = mod._parse_stage_map(plan_text)
-    finally:
-        _sys.modules.pop("_ip_stage_v_wizard", None)
+        stages, errs = _load_parsed_stage_map(plan_text)
+    except PrepareError as exc:
+        raise WizardError(str(exc)) from exc
+    detail = _stage_map_reject_detail(stages, errs)
+    if detail is not None:
+        raise WizardError(
+            f"approved plan 의 Stage Map 을 신뢰할 수 없습니다 "
+            f"({state.approved_plan_path}): {detail}. plan 의 Stage Map 을 점검하세요.")
     return stages
 
 
@@ -1893,10 +1898,13 @@ def _handoff_eligibility(state: WizardState) -> list:
     from okstra_ctl.run import _parse_stage_map_into_ctx
     from okstra_ctl.consumers import read_consumers
     plan = _resolve_handoff_plan(state)
-    stage_map = _parse_stage_map_into_ctx(str(plan))
-    if not stage_map:
-        raise WizardError(
-            _handoff_msgs(state)["errors"]["no_stage_map"].format(plan=plan))
+    try:
+        stage_map = _parse_stage_map_into_ctx(str(plan))
+    except PrepareError as exc:
+        # PrepareError 가 비어있음(heading rename)·손상(비단조 등)을 이미 구체적으로
+        # 구분해 전달하므로 그 메시지를 그대로 surface 한다 — 'no_stage_map' 으로
+        # 덮으면 손상된 맵을 '맵 없음'으로 오표기하고 어느 행이 깨졌는지 detail 을 잃는다.
+        raise WizardError(str(exc)) from exc
     rows = read_consumers(plan.resolve().parents[1])
     return compute_eligibility(stage_map, rows)
 
@@ -3612,8 +3620,15 @@ def _cli(argv: list[str]) -> int:
                 result = submit(state, args.answer)
         except WizardError as exc:
             save_state_file(state_path, state)
-            print(json.dumps({"ok": False, "error": str(exc),
-                              "current": prompt_payload(state, next_prompt(state))},
+            try:
+                current = prompt_payload(state, next_prompt(state))
+            except WizardError:
+                # 현재 step 의 build 자체가 실패하면(예: 손상된 Stage Map 으로
+                # _build_stage_pick·_build_handoff_stage_pick 가 raise) recovery 재렌더가
+                # 같은 예외를 다시 던져 이중 실패한다 — try 밖이라 _cli 를 탈출해
+                # traceback 으로 죽는다. current 를 비워 첫 예외를 깨끗한 envelope 로 낸다.
+                current = None
+            print(json.dumps({"ok": False, "error": str(exc), "current": current},
                              ensure_ascii=False, indent=2))
             return 0
         save_state_file(state_path, state)

package/runtime/python/okstra_project/__init__.py

@@ -34,6 +34,7 @@ from .state import (
     read_latest_task,
     read_task_catalog,
     read_task_manifest,
+    resolve_task_id,
     resolve_task_identity,
     slugify,
 )
@@ -58,6 +59,7 @@ __all__ = [
     "read_task_catalog",
     "read_task_manifest",
     "resolve_project_root",
+    "resolve_task_id",
     "resolve_task_identity",
     "slugify",
     "tasks_root",