okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/run_audit.py

@@ -456,8 +456,21 @@ def audit_runs(home: Path, *, now: dt.datetime) -> list[dict]:
     return violations
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra run-audit
+
+Walks the global run-index and checks each run's artifacts (run-manifest,
+final-report data, worker results) against invariants that no error log
+would catch: verification rounds that never ran, reports that never
+appeared, rosters that came up short, approvals waiting past the window.
+Read-only. Prints a JSON summary to stdout.
+"""
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         prog="okstra run-audit",
         description="런 아티팩트에서 불변식 위반을 찾는다 (읽기 전용).",
     )

package/runtime/python/okstra_ctl/run_index_row.py

@@ -104,15 +104,3 @@ def _rewrite_slim(path: Path) -> int:
     rewrite_jsonl(path, [slim_run_row(row) for row in rows])
     return len(rows)
 
-
-def reindex_slim(home: Path) -> int:
-    """기존 run-index 파일들을 slim 으로 일괄 재작성. 멱등. 변환 row 총수 반환."""
-    total = 0
-    targets = [home / "recent.jsonl", home / "active.jsonl"]
-    projects = home / "projects"
-    if projects.is_dir():
-        targets += sorted(projects.glob("*/index.jsonl"))
-    for path in targets:
-        if path.is_file():
-            total += _rewrite_slim(path)
-    return total

package/runtime/python/okstra_ctl/seeding.py

@@ -10,6 +10,7 @@ okstra worker wrapper 호출이 자동 허용되도록 한다.
 from __future__ import annotations
 
 import os
+import sys
 import time
 from pathlib import Path
 from typing import Optional
@@ -69,9 +70,8 @@ def verify_installation(workspace_root: Path) -> None:
     이 검사는 ~/.okstra 자산만을 본다; workspace_root 의 존재는 별도 검증.
 
     `OKSTRA_SKIP_INSTALL_CHECK=1` 이면 설치 자산 검사를 건너뛴다 — 격리
-    OKSTRA_HOME 으로 subprocess 를 띄우는 테스트용 게이트(conftest 가 설정,
-    OKSTRA_CTL_SKIP_RECONCILE/BACKFILL 과 같은 패턴). workspace_root 검증은
-    게이트와 무관하게 항상 수행한다.
+    OKSTRA_HOME 으로 subprocess 를 띄우는 테스트용 게이트(conftest 가 설정).
+    workspace_root 검증은 게이트와 무관하게 항상 수행한다.
     """
     if os.environ.get("OKSTRA_SKIP_INSTALL_CHECK", "").strip():
         missing = []
@@ -105,24 +105,34 @@ def cleanup_obsolete_generated_docs(
     ):
         target = legacy_root / rel
         if target.exists():
-            try:
-                target.unlink()
-            except OSError:
-                pass
+            _unlink_deprecated(target)
     obsolete = Path(instruction_set_dir) / "okstra-skill.md"
     if obsolete.exists():
-        try:
-            obsolete.unlink()
-        except OSError:
-            pass
+        _unlink_deprecated(obsolete)
     okstra_dir = legacy_root / "okstra"
     if okstra_dir.is_dir():
         try:
             okstra_dir.rmdir()
         except OSError:
+            # expected-miss: 사용자가 이 디렉터리에 자기 파일을 두었으면 비어 있지
+            # 않아 rmdir 이 실패한다. 남의 파일을 지우지 않는 것이 맞는 동작이다.
             pass
 
 
+def _unlink_deprecated(target: Path) -> None:
+    """이미 존재를 확인한 deprecated 파일을 지운다. 실패는 stderr 로 보고한다.
+
+    존재를 확인하고 부르므로 여기서 나는 OSError 는 권한·I/O 오류다. 조용히 넘기면
+    다음 run 이 같은 파일을 또 만나 같은 자리에서 또 실패하는데, 왜 안 지워지는지는
+    아무 데도 남지 않는다.
+    """
+    try:
+        target.unlink()
+    except OSError as exc:
+        print(f"seeding: cannot remove the deprecated file {target} ({exc})",
+              file=sys.stderr)
+
+
 def installed_settings_template_path() -> Path:
     """okstra install 이 만들어 둔 settings.local.json template 의 절대경로."""
     return okstra_home() / "templates" / "settings.local.json"

package/runtime/python/okstra_ctl/sequence.py

@@ -20,7 +20,7 @@ def predict_next_run_seq(project_root: Path, task_group: str, task_id: str,
       1. reports/ 의 final-report-<task_type>-<seq:03d>.md (완료된 run)
       2. manifests/ 의 run-manifest-<task_type>-<seq:03d>.json (시작했지만 종료 전)
       3. home/active.jsonl 의 같은 (project_id, group, task_id, task_type) row
-         (다른 okstra-ctl 프로세스가 이미 예약한 in-flight run) — home/project_id 가 주어진 경우만
+         (다른 prepare 프로세스가 이미 예약한 in-flight run) — home/project_id 가 주어진 경우만
 
     이 셋의 max + 1 이 안전한 다음 seq.
     """

package/runtime/python/okstra_ctl/session.py

@@ -27,20 +27,26 @@ def _claude_projects_dir_for(cwd: Path) -> Path:
     return Path.home() / ".claude" / "projects" / encoded
 
 
-def resolve_inproc_lead_session_id(project_root: Path) -> str:
+def resolve_inproc_lead_session_id(session_cwd: Path) -> str:
     """Best-effort detection of the running Claude session's id when okstra is
     invoked render-only from inside a live session (the `okstra-run` skill
     path). The current session's jsonl is being actively written to under
     `~/.claude/projects/<encoded-cwd>/`, so the most recently modified file
     in that directory is, with very high probability, the calling session.
 
+    인자는 **부르는 세션의 cwd** 다. 대상 프로젝트 루트를 넘기면 안 된다 —
+    `okstra preflight --cwd <다른 프로젝트>` 로 프로젝트 B 를 A 의 세션에서 몰 때
+    B 의 디렉터리에서 가장 최근 파일을 집으면 남의 세션 id 가 run manifest 에
+    박힌다(실측 2026-08-18). 그 id 는 실재하는 파일을 가리키므로 조용히 통과하고,
+    Phase 7 에서 리드 토큰과 PROGRESS 증거를 통째로 잃는다.
+
     Returns the UUID stem on success, empty string on failure (directory
     missing, no jsonl files, permission error). Callers must treat this as
     best-effort — a failure does not invalidate the session, it just means
     auto-detection could not confirm one.
     """
     try:
-        d = _claude_projects_dir_for(project_root)
+        d = _claude_projects_dir_for(session_cwd)
         if not d.exists():
             return ""
         candidates = [p for p in d.iterdir() if p.suffix == ".jsonl"]
@@ -95,24 +101,68 @@ def resolve_lead_session_id_for_run(
     경로를 언급하므로 needle 에도 걸린다. 워커가 리드보다 늦게 끝나면 mtime
     정렬에서 먼저 잡혀 워커 세션이 리드로 기록된다 — dispatch 가 발급한 id 를
     호출자가 넘겨 그 세션들을 후보에서 뺀다.
+
+    프로젝트 디렉터리에서 아무도 안 잡히면 나머지 인코딩 디렉터리까지 넓힌다.
+    리드 세션의 cwd 가 대상 프로젝트 루트와 다를 수 있기 때문이다 —
+    `okstra preflight --cwd <다른 프로젝트>` 로 프로젝트 B 의 태스크를 A 의
+    세션에서 몰 때, transcript 는 A 로 인코딩된 디렉터리에 놓인다. 넓힌 패스는
+    run 디렉터리가 생기기 전에 마지막으로 쓰인 파일을 건너뛴다 — 그런 세션은
+    아직 존재하지 않던 경로를 언급할 수 없다.
     """
-    proj_dir = _claude_projects_dir_for(project_root)
-    try:
-        candidates = [p for p in proj_dir.iterdir() if p.suffix == ".jsonl"]
-    except OSError:
-        return ""
     needle = str(run_dir)
     excluded = set(exclude_session_ids)
-    for path in sorted(candidates, key=lambda p: p.stat().st_mtime, reverse=True):
-        if path.stem in excluded:
-            continue
-        if _session_has_agent_name(path):
-            continue
-        if _session_mentions(path, needle):
-            return path.stem
+    for candidates in _lead_session_candidate_passes(project_root, run_dir):
+        for path in sorted(candidates, key=lambda p: p.stat().st_mtime, reverse=True):
+            if path.stem in excluded:
+                continue
+            if _session_has_agent_name(path):
+                continue
+            if _session_mentions(path, needle):
+                return path.stem
     return ""
 
 
+def _run_dir_created_at(run_dir: Path) -> float:
+    """run 디렉터리가 생긴 시각. 넓힌 스캔의 하한이다."""
+    try:
+        st = run_dir.stat()
+    except OSError:
+        return 0.0
+    return float(getattr(st, "st_birthtime", st.st_ctime))
+
+
+def _lead_session_candidate_passes(project_root: Path, run_dir: Path):
+    """후보 파일 묶음을 순서대로 내준다 — 프로젝트 디렉터리, 그다음 나머지.
+
+    첫 묶음에서 리드가 잡히면 두 번째는 열리지 않는다. 같은 cwd 로 도는 보통의
+    런은 예전과 같은 비용으로 끝나고, 넓은 스캔은 지금 통째로 실패하는
+    cross-project 런에서만 값을 치른다.
+    """
+    proj_dir = _claude_projects_dir_for(project_root)
+    try:
+        yield [p for p in proj_dir.iterdir() if p.suffix == ".jsonl"]
+    except OSError:
+        yield []
+    floor = _run_dir_created_at(run_dir)
+    others: list[Path] = []
+    try:
+        for entry in proj_dir.parent.iterdir():
+            if not entry.is_dir() or entry == proj_dir:
+                continue
+            for path in entry.iterdir():
+                if path.suffix != ".jsonl":
+                    continue
+                try:
+                    if path.stat().st_mtime < floor:
+                        continue
+                except OSError:
+                    continue
+                others.append(path)
+    except OSError:
+        return
+    yield others
+
+
 def record_observed_lead_session(project_root: Path, team_state_path: Path) -> str:
     """이 run 의 live lead 세션을 관측해 team-state 에 append(멱등). 이 run 을
     다룬 lead 세션을 못 찾거나 중복이면 '' 반환. 재발급으로 갈린 세대를 축1 이

package/runtime/python/okstra_ctl/set_work_status.py

@@ -61,8 +61,26 @@ def _manifest_path(project_root: Path, entry: dict) -> Path:
     return task_manifest_file(task_dir(project_root, group_seg, id_seg))
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra set-work-status <token> <status> [--note <text>] [--task-group <g>]
+                         [--project-root <dir>] [--cwd <dir>] [--json]
+
+<token> is a full task-key (<project-id>:<task-group>:<task-id>) or a bare
+task-id. <status> is one of: todo | in-progress | blocked | done.
+
+Updates workStatus + workStatusUpdatedAt in task-manifest.json (workStatusNote
+only when --note is passed) using the same JSON serialization as the manifest
+renderer. Output: JSON { ok, taskKey, previousWorkStatus, workStatus, ... };
+ok:false stages: resolve | catalog | not-found | ambiguous (pick from
+matches[]) | manifest-missing | manifest-invalid.
+"""
+
+
 def _parse_args(argv: list[str] | None):
     parser = argparse.ArgumentParser(
+        prog="okstra set-work-status",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         description="Set a task's user-managed workStatus in task-manifest.json."
     )
     parser.add_argument(

package/runtime/python/okstra_ctl/stage_integrate.py

@@ -187,6 +187,16 @@ def _teardown_stage(project_id, task_group, task_id, task_wt, stage_n, row):
     return ("torn_down", "")
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra integrate-stages --project-id <id> \
+    --task-group <g> --task-id <t> --plan-run-root <dir> \
+    --task-worktree-path <dir> [--stage-map-json '<json>']
+
+Exit codes: 0 ok / 2 stage 간 merge 충돌 / 1 python 프로세스 비정상 종료(폴백)
+"""
+_CLI_DESCRIPTION = "Stage \ub4e4\uc744 task \ube0c\ub79c\uce58\uc5d0 \ud1b5\ud569 \uba38\uc9c0 + worktree \uc815\ub9ac."
+
+
 def main(argv: list[str] | None = None) -> int:
     import argparse
     import json
@@ -194,7 +204,11 @@ def main(argv: list[str] | None = None) -> int:
 
     from .consumers import read_consumers
 
-    p = argparse.ArgumentParser(prog="okstra integrate-stages")
+    p = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra integrate-stages")
     p.add_argument("--project-id", required=True)
     p.add_argument("--task-group", required=True)
     p.add_argument("--task-id", required=True)

package/runtime/python/okstra_ctl/stage_ledger.py

@@ -30,7 +30,7 @@ from .stage_map import (
     load_task_stage_map,
 )
 from .stage_targets import stage_lifecycle_snapshot_from_state
-from .task_target import infer_project_root
+from .paths import infer_project_root
 
 
 def build_stage_ledger(task_root: Path) -> dict[str, Any] | None:

package/runtime/python/okstra_ctl/stage_map.py

@@ -13,7 +13,7 @@ from .fixed_text import line, value_lines
 from .md_table import is_separator_row, split_pipe_row
 from .paths import RunRef
 from .plan_run_root import list_implementation_planning_reports
-from .task_target import infer_project_root
+from .paths import infer_project_root
 
 
 STAGE_MAP_HEADING = re.compile(r"^##\s+5\.5\s+Stage\s+Map\b", re.MULTILINE)
@@ -506,22 +506,63 @@ def load_task_stage_map(
 ) -> StageMapSnapshot:
     """완료된 stage 를 무엇으로 지었는지 답하는 Stage Map.
 
-    carry 사이드카가 가리키는 계획을 우선한다 — 그게 실행이 실제로 따른
-    문서이기 때문이다. "어떤 stage 번호가 이미 쓰였나" 는 다른 질문이며
-    `load_latest_plan_stage_map` 이 답한다.
+    carry 사이드카가 가리키는 계획을 읽는다 — 그게 실행이 실제로 따른
+    문서이기 때문이다. 오직 그 질문에만 답한다. "어떤 stage 가 존재하나" 와
+    "어떤 번호가 이미 쓰였나" 는 최신 계획이 답하며, 그쪽을 물어야 하는
+    소비자는 `load_latest_plan_stage_map` 을 쓴다 — 계획을 고친 task 에서
+    carry 소스는 새로 붙은 stage 를 아직 모른다.
     """
     carried = _unique_carry_source_paths(task_root)
     if len(carried) > 1:
-        paths = tuple(str(path) for path in carried)
-        raise StageMapError(
-            "plan-source-conflict",
-            "implementation carries reference different source plans",
-            conflicting_paths=paths,
-        )
-    source = carried[0] if carried else _latest_plan_report(task_root)
+        source: Path | None = _reconcile_carried_sources(carried)
+    else:
+        source = carried[0] if carried else _latest_plan_report(task_root)
     return _snapshot_for(source)
 
 
+def _reconcile_carried_sources(carried: list[Path]) -> Path:
+    """서로 다른 계획을 가리키는 carry 들을 하나로 접는다.
+
+    ADR-0016 은 계획 수정의 산출물을 새 planning 리포트로 정한다. 그래서 수정을
+    한 번이라도 거친 task 에서는 carry 들이 서로 다른 계획을 가리키는 것이
+    정상이다 — 먼저 끝난 stage 는 그때의 계획을, 그 뒤 stage 는 새 계획을
+    적는다. 이 모양을 무조건 충돌로 올리면 계획을 수정한 모든 task 가 Stage Map
+    을 영구히 잃는다.
+
+    ADR-0015 의 append-only 가 지켜졌다면 두 계획은 공유하는 번호에서 같은
+    작업을 가리킨다. 그 조건을 실제로 확인한 뒤에만 가장 긴 계획을 답으로 쓴다
+    — 확인 없이 하나를 고르면 번호 재배치가 조용히 통과하고 완료 커밋이 엉뚱한
+    stage 에 귀속된다.
+    """
+    titles = {
+        path: {
+            record["stage_number"]: record["title"]
+            for record in stage_map_records(parse_stage_map_file(path))
+        }
+        for path in carried
+    }
+    conflicts = tuple(str(path) for path in carried)
+    for index, left in enumerate(carried):
+        for right in carried[index + 1:]:
+            renamed = [
+                number
+                for number in sorted(set(titles[left]) & set(titles[right]))
+                if titles[left][number] != titles[right][number]
+            ]
+            if renamed:
+                raise StageMapError(
+                    "plan-source-conflict",
+                    "implementation carries reference plans that name different "
+                    "work under the same stage number: "
+                    + ", ".join(f"stage {number}" for number in renamed),
+                    conflicting_paths=conflicts,
+                )
+    # `_validate_stage_numbers` 가 stage 번호를 `1..N` 단조로 강제하므로 계획의
+    # 번호 집합은 언제나 앞이 막힌 구간이다. 그래서 가장 긴 계획이 나머지의
+    # superset 인 것은 따로 검사할 명제가 아니라 파서가 이미 보장하는 사실이다.
+    return max(carried, key=lambda path: len(titles[path]))
+
+
 def load_latest_plan_stage_map(task_root: Path) -> StageMapSnapshot:
     """이 task 의 최신 계획 리포트가 선언한 Stage Map.
 
@@ -579,3 +620,8 @@ def _resolve_plan_path(task_root: Path, value: str) -> Path:
     if task_relative.exists():
         return task_relative
     return project_relative
+
+# ---- read-side view -------------------------------------------------------
+# 예전에는 okstra_project.state 가 이 어댑터를 들고 okstra_ctl 을 함수 본문에서
+# 지연 import 했다. 하위 계층이 상위를 되짚는 배치였다. 읽는 대상이 okstra_ctl 의
+# Stage Map 과 consumer 상태이므로 소유자를 여기로 옮긴다.

package/runtime/python/okstra_ctl/stage_map_cli.py

@@ -0,0 +1,83 @@
+"""`okstra stage-map` 의 프로젝션 — 한 task 의 구현 계획 Stage Map 과 완료 stage.
+
+원래 `src/commands/inspect/stage-map.mts` 의 문자열 리터럴 안에 있던 코드다
+(docs/coding-rules.md R1 위반). 로직은 그대로 옮겼다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from okstra_project import ResolverError, StateError, resolve_project_root
+
+from .stage_map import render_stage_map_text
+from .stage_map_view import stage_map_read_side_snapshot
+
+
+def emit(payload: dict, output_mode: str) -> None:
+    if output_mode == "text":
+        print(render_stage_map_text(payload))
+    else:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+_CLI_EPILOG = r"""Usage:
+  okstra stage-map <task-key>                  task-key is project-id:task-group:task-id
+  okstra stage-map <task-key> --cwd <dir>      Resolve PROJECT_ROOT from <dir>
+  okstra stage-map <task-key> --project <dir>  Use <dir> directly as PROJECT_ROOT
+  okstra stage-map <task-key> --text           Emit fixed text fields for model use
+
+Output: default and --json emit JSON { ok, taskKey, taskRoot, state, sourcePlanPath,
+stages:[…], doneStages:[int], planning:{…} }; --text emits fixed count/name/value fields.
+Each stage row carries stage_number, title, depends_on, step_count and exit_contract_summary; a
+schema-v2 report adds that stage's sliceValue, acceptance and exitContract.
+planning carries the report's task-level rows — rollbackStrategy, validationChecklist,
+crossProjectDependencies, dependencyMigrationRisk, recommendedOption — so a consumer renders the
+plan instead of re-summarising the report body. Both are absent for a schema-v1 report.
+stages is [] when no implementation-planning Stage Map exists.
+"""
+_CLI_DESCRIPTION = "Dump a task's implementation-planning Stage Map + done stages."
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra stage-map")
+    parser.add_argument("task_key", metavar="task-key",
+                        help="project-id:task-group:task-id")
+    parser.add_argument("--project-root", "--project", default="",
+                        help="use this directory as PROJECT_ROOT")
+    parser.add_argument("--cwd", default=".",
+                        help="resolve PROJECT_ROOT starting from here")
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument("--json", dest="output_mode", action="store_const",
+                      const="json", default="json", help="emit JSON (default)")
+    mode.add_argument("--text", dest="output_mode", action="store_const",
+                      const="text", help="emit fixed text fields")
+    args = parser.parse_args(argv)
+
+    try:
+        resolved = resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
+    except ResolverError as exc:
+        emit({"ok": False, "stage": "resolve", "reason": str(exc)}, args.output_mode)
+        return 2
+
+    try:
+        snapshot = stage_map_read_side_snapshot(Path(resolved), args.task_key)
+    except StateError as exc:
+        emit({
+            "ok": False,
+            "stage": getattr(exc, "stage", None) or "stage_map",
+            "reason": str(exc),
+        }, args.output_mode)
+        return 1
+
+    emit({"ok": True, **snapshot}, args.output_mode)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/stage_map_view.py

@@ -0,0 +1,65 @@
+"""stage-map inspect 용 read-side view.
+
+Stage Map(okstra_ctl) 과 task identity(okstra_project) 를 한 자리에서 합친다.
+전에는 이 함수가 okstra_project.state 안에 있었다 — 하위 계층이 okstra_ctl 을
+함수 본문에서 지연 import 하는 배치였다. 그렇다고 stage_map 으로 옮기면
+stage_map 이 okstra_project 를 끌어오고, okstra_project.state 가 다시
+implementation_outcome → stage_map 으로 돌아와 순환이 된다.
+
+그래서 소비자 쪽 얇은 조립 모듈을 따로 둔다. 이 모듈은 아무도 import 하지
+않으므로 어느 순환에도 들어갈 수 없다. 소비자는 `okstra stage-map` 하나다.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from okstra_project import StateError, resolve_task_identity
+
+from .consumers import read_stage_consumer_state
+from .paths import RunRef
+from .stage_map import (
+    PlanningDetail,
+    StageMapError,
+    load_latest_plan_stage_map,
+    load_planning_detail,
+    merge_planning_detail,
+)
+
+
+def stage_map_read_side_snapshot(project_root: Path, task_key: str) -> dict:
+    """stage-map inspect 용 read-side view: Stage Map + done 처리된 stage 번호.
+
+    Stage Map 파싱과 planning run-root 위치를 caller 에게 노출하지 않는다 —
+    Node inspect 가 okstra_ctl 의 private 심볼을 import 하거나 `runs/` 경로를
+    직접 조립하지 않도록 하는 어댑터다.
+    """
+    identity = resolve_task_identity(project_root, task_key)
+    task_root = Path(identity["taskRoot"])
+    try:
+        stage_snapshot = load_latest_plan_stage_map(task_root)
+        detail = (
+            load_planning_detail(Path(stage_snapshot.source_plan_path))
+            if stage_snapshot.source_plan_path
+            else PlanningDetail({}, {})
+        )
+    except StageMapError as exc:
+        raise StateError(str(exc), stage=exc.code) from exc
+    plan_run_root = RunRef.from_task_root(
+        task_root, "implementation-planning"
+    ).run_dir
+    done: list[int] = []
+    if plan_run_root.is_dir():
+        done = sorted(
+            read_stage_consumer_state(
+                plan_run_root, recover_from_carry=True
+            ).done_stages
+        )
+    return {
+        "taskKey": identity["taskKey"],
+        "taskRoot": identity["taskRoot"],
+        "state": stage_snapshot.state,
+        "sourcePlanPath": stage_snapshot.source_plan_path,
+        "stages": merge_planning_detail(stage_snapshot.stages, detail),
+        "doneStages": done,
+        "planning": detail.task_narratives,
+    }

package/runtime/python/okstra_ctl/stage_targets.py

@@ -14,7 +14,10 @@ from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Any
 
+from .plan_run_root import plan_run_root_from_approved_plan
+from .prepare_error import PrepareError  # noqa: F401 — 재노출(단일 참조점)
 from .stage_integrate import IntegrateResult
+from okstra_project.slug import slugify
 
 
 RUN_STEP_BUDGET = 8
@@ -24,14 +27,6 @@ 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"
@@ -671,7 +666,6 @@ def resolve_and_integrate_whole_task(
 ) -> dict[str, Any]:
     """Locked whole-task integration interface shared with the container."""
     from okstra_project.dirs import okstra_home
-    from okstra_project.state import slugify
 
     from .locks import worktree_provision_mutex
 
@@ -734,7 +728,6 @@ def _read_final_verification_done_rows(
     registry_coordinates: tuple[str, str, str],
 ) -> list[dict[str, Any]]:
     from .consumers import backfill_done_from_carry, read_stage_consumer_state
-    from .plan_run_root import plan_run_root_from_approved_plan
     from .stage_reconcile import auto_reconcile_best_effort
 
     plan_run_root = plan_run_root_from_approved_plan(request.approved_plan_path)
@@ -755,7 +748,6 @@ def _read_final_verification_done_rows(
 def _final_verification_registry_coordinates(
     request: FinalVerificationTargetRequest,
 ) -> tuple[str, str, str]:
-    from okstra_project.state import slugify
 
     def segment(value: str) -> str:
         return slugify(value) or "_"
@@ -913,7 +905,6 @@ def acquire_final_verification_target(
 ) -> FinalVerificationTargetAcquisition:
     """Acquire a stable final-verification target behind one task-key lock."""
     from okstra_project.dirs import okstra_home
-    from okstra_project.state import slugify
 
     from .locks import worktree_provision_mutex