okstra 0.135.0 → 0.137.0

package/runtime/python/okstra_project/state.py

@@ -30,6 +30,7 @@ from .dirs import (
     DISCOVERY_RELATIVE,
     LATEST_TASK_RELATIVE,
     TASK_CATALOG_RELATIVE,
+    TASK_MANIFEST_FILENAME,
     TASKS_RELATIVE,
 )
 
@@ -82,7 +83,24 @@ def read_latest_task(project_root: Path) -> Optional[dict]:
 
 def read_task_manifest(task_root: Path) -> Optional[dict]:
     """<task-root>/task-manifest.json 을 dict 로. 파일 없으면 None."""
-    return _load_json(Path(task_root) / "task-manifest.json")
+    return _load_json(Path(task_root) / TASK_MANIFEST_FILENAME)
+
+
+def read_task_key(task_root: Path) -> str:
+    """manifest 의 taskKey. 파일이 없거나 깨졌으면 "".
+
+    리포트 렌더러(recap·time-report·error-report)는 taskKey 를 헤더 라벨로만 쓰므로
+    manifest 가 없어도 실패하지 않아야 한다 — 세 모듈이 각자 갖고 있던 관용 리더를
+    여기로 모은다.
+    """
+    try:
+        manifest = read_task_manifest(Path(task_root))
+    except (StateError, OSError):
+        return ""
+    if not isinstance(manifest, dict):
+        return ""
+    value = manifest.get("taskKey")
+    return value if isinstance(value, str) else ""
 
 
 def _reconcile_task_root_best_effort(project_root: Path, task_root: Path) -> None:
@@ -94,6 +112,31 @@ def _reconcile_task_root_best_effort(project_root: Path, task_root: Path) -> Non
         return
 
 
+_DERIVED_STATUS_STRING_FIELDS = (
+    "workStatus",
+    "currentStatus",
+    "latestRunStatus",
+    "latestReportPath",
+)
+
+
+def derived_task_status(manifest: dict) -> dict:
+    """Task status a caller acts on, projected off the raw manifest.
+
+    Both the task list rows and the read-side snapshot project through here so
+    the two views cannot disagree about whether a task is finished.
+    """
+    out: dict = {}
+    for field in _DERIVED_STATUS_STRING_FIELDS:
+        value = manifest.get(field)
+        if isinstance(value, str):
+            out[field] = value
+    phase_outcome = manifest.get("phaseOutcome")
+    if isinstance(phase_outcome, dict):
+        out["phaseOutcome"] = phase_outcome
+    return out
+
+
 def _entry_with_manifest_state(entry: dict, task_root: Path) -> dict:
     out = {**entry}
     manifest = read_task_manifest(task_root) or {}
@@ -107,13 +150,7 @@ def _entry_with_manifest_state(entry: dict, task_root: Path) -> dict:
         value = workflow.get(source)
         if isinstance(value, str):
             out[target] = value
-    for field in ("currentStatus", "latestRunStatus", "latestReportPath"):
-        value = manifest.get(field)
-        if isinstance(value, str):
-            out[field] = value
-    phase_outcome = manifest.get("phaseOutcome")
-    if isinstance(phase_outcome, dict):
-        out["phaseOutcome"] = phase_outcome
+    out.update(derived_task_status(manifest))
     return out
 
 
@@ -329,8 +366,41 @@ def task_read_side_snapshot(project_root: Path, task_key: str) -> dict:
             "routingStatus": workflow.get("routingStatus"),
             "phaseStates": workflow.get("phaseStates"),
         },
+        "status": derived_task_status(manifest),
         "resultContract": manifest.get("resultContract"),
         "artifacts": manifest.get("artifacts"),
         "modelAssignments": manifest.get("modelAssignments"),
         "latestRunPath": manifest.get("latestRunPath"),
     }
+
+
+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/` 경로를
+    직접 조립하지 않도록 하는 어댑터다.
+    """
+    from okstra_ctl.consumers import read_stage_consumer_state
+    from okstra_ctl.implementation_outcome import load_stage_map
+    from okstra_ctl.paths import RunRef
+
+    identity = resolve_task_identity(project_root, task_key)
+    task_root = Path(identity["taskRoot"])
+    stages = load_stage_map(task_root, identity["manifest"])
+    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"],
+        "stages": stages,
+        "doneStages": done,
+    }

package/runtime/validators/validate-run.py

@@ -43,6 +43,8 @@ from okstra_ctl.conformance import (  # noqa: E402
     qa_result_from_dict,
     validate_conformance_manifest,
 )
+from okstra_ctl.paths import RunRef  # noqa: E402
+from okstra_ctl.workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE  # noqa: E402
 from okstra_ctl.md_table import (  # noqa: E402
     is_separator_row as _is_markdown_separator,
     split_pipe_row as _split_pipe_row,
@@ -157,19 +159,7 @@ def write_json(path: Path, payload: dict) -> None:
 
 
 def default_next_phase(task_type: str) -> str:
-    mapping = {
-        "requirements-discovery": "pending-routing-decision",
-        "improvement-discovery": "pending-routing-decision",
-        "error-analysis": "implementation-planning",
-        "implementation-planning": "implementation",
-        "implementation": "final-verification",
-        # final-verification 의 다음 phase 는 verdict 에 따라 갈리므로
-        # 정적 매핑은 `pending-release-handoff` 로 두고, 실제 진입은
-        # release-handoff profile 의 entry gate (`accepted` 확인) 에서 강제한다.
-        "final-verification": "pending-release-handoff",
-        "release-handoff": "done-or-follow-up",
-    }
-    return mapping.get(task_type, "unknown")
+    return DEFAULT_NEXT_PHASE.get(task_type, "unknown")
 
 
 def advance_next_phase(
@@ -208,14 +198,7 @@ def update_workflow_metadata(
     )
     phase_sequence = workflow.get("phaseSequence", [])
     if not isinstance(phase_sequence, list) or not phase_sequence:
-        phase_sequence = [
-            "requirements-discovery",
-            "error-analysis",
-            "implementation-planning",
-            "implementation",
-            "final-verification",
-            "release-handoff",
-        ]
+        phase_sequence = list(PHASE_SEQUENCE)
 
     phase_states = workflow.get("phaseStates", {})
     if not isinstance(phase_states, dict):
@@ -1143,17 +1126,15 @@ def _scope_manifest_entries(manifest: dict, stage_name: str | None) -> dict:
 
 
 def _task_root_from_run_dir(run_dir: Path) -> Path:
-    """run_dir 에서 `runs` 디렉터리를 앵커로 task_root 를 복원한다.
+    """run_dir 에서 task_root 를 복원한다.
 
-    일반 task-type: run_dir = task_root/runs/<task-type> → task_root.
-    implementation(stage 격리): run_dir = task_root/runs/implementation/stage-<N>
-    → 같은 task_root. `runs` 를 위로 탐색하므로 stage-<N> 레벨이 추가돼도
-    안전하다. `runs` 가 조상에 없으면 기존 동작(두 단계 위)로 폴백한다.
+    레이아웃 해석은 `RunRef.from_run_dir` 이 소유한다. run 디렉터리가 아닌
+    입력에는 기존 동작(두 단계 위)으로 폴백해 검증기가 죽지 않게 한다.
     """
-    for parent in run_dir.parents:
-        if parent.name == "runs":
-            return parent.parent
-    return run_dir.parent.parent
+    try:
+        return RunRef.from_run_dir(run_dir).task_root
+    except ValueError:
+        return run_dir.parent.parent
 
 
 def _read_run_inputs_payload(
@@ -3129,19 +3110,15 @@ _PASSING_VERDICT_TOKENS = frozenset({"accepted", "conditional-accept"})
 def _consumers_rows(report_path: Path) -> list[dict] | None:
     """`runs/implementation-planning/consumers.jsonl` rows for this task.
 
-    The final-verification report sits at `runs/final-verification/[stage-N/]
-    reports/...`, so walk up to the `runs/` directory rather than guessing a
-    fixed depth. ``None`` when the file is absent, so the caller does not turn
-    a missing artifact into a false accusation.
+    ``None`` when the report path is unreadable as a run reference or the file
+    is absent, so the caller does not turn a missing artifact into a false
+    accusation.
     """
-    runs_dir = None
-    for parent in report_path.parents:
-        if parent.name == "runs":
-            runs_dir = parent
-            break
-    if runs_dir is None:
+    try:
+        ref = RunRef.from_report_path(report_path)
+    except ValueError:
         return None
-    path = runs_dir / "implementation-planning" / "consumers.jsonl"
+    path = ref.sibling("implementation-planning").run_dir / "consumers.jsonl"
     if not path.is_file():
         return None
     rows = []
@@ -3497,17 +3474,11 @@ def _validate_stage_carry_sidecar_exists(
     stage = evidence.get("stageNumber")
     if not isinstance(stage, int):
         return
-    # Carry sidecars are stage-SHARED: they live flat at
-    # `runs/implementation/carry/stage-<N>.json`, NOT under the stage-<N>/ run
-    # dir, because the next stage's carry-in and `consumers.backfill_done_from_carry`
-    # glob them without knowing the producing run's layout (storage-model.md
-    # §"representative files"). `report_path` is
-    # `runs/implementation/stage-<N>/reports/final-report-...md`, so drop the
-    # stage-<N>/ segment to reach the flat carry dir that `consumers` reads —
-    # resolving it under the stage run dir forced the lead to write the file twice.
-    run_dir = report_path.parent.parent
-    carry_root = run_dir.parent if _stage_isolated_name(run_dir) else run_dir
-    carry_path = carry_root / "carry" / f"stage-{stage}.json"
+    # Carry sidecars are stage-SHARED: the next stage's carry-in and
+    # `consumers.backfill_done_from_carry` glob them without knowing the
+    # producing run's layout. `RunRef.carry()` owns that flat-vs-staged rule;
+    # resolving it under the stage run dir forced the lead to write it twice.
+    carry_path = RunRef.from_report_path(report_path).carry(stage)
     if not carry_path.exists():
         failures.append(
             f"implementation run declares stage-{stage} sidecar evidence but "

package/src/commands/inspect/stage-map.mjs

@@ -40,9 +40,9 @@ function parseArgs(args) {
 const SCRIPT = `
 import json, sys
 from pathlib import Path
-from okstra_project import resolve_project_root, find_task_root, read_task_manifest, ResolverError
-from okstra_ctl.implementation_outcome import _load_stage_map
-from okstra_ctl.consumers import read_stage_consumer_state
+from okstra_project import (
+    resolve_project_root, stage_map_read_side_snapshot, ResolverError, StateError,
+)
 
 explicit, cwd, task_key = sys.argv[1], sys.argv[2], sys.argv[3]
 
@@ -52,24 +52,17 @@ except ResolverError as e:
     print(json.dumps({"ok": False, "stage": "resolve", "reason": str(e)}))
     sys.exit(2)
 
-task_root = find_task_root(Path(pr), task_key)
-if task_root is None:
-    print(json.dumps({"ok": False, "stage": "task_root", "reason": f"task root not found for {task_key}"}))
+try:
+    snapshot = stage_map_read_side_snapshot(Path(pr), task_key)
+except StateError as e:
+    print(json.dumps({
+        "ok": False,
+        "stage": getattr(e, "stage", None) or "stage_map",
+        "reason": str(e),
+    }))
     sys.exit(1)
 
-manifest = read_task_manifest(task_root) or {}
-stages = _load_stage_map(task_root, manifest)
-
-plan_run_root = task_root / "runs" / "implementation-planning"
-done = sorted(read_stage_consumer_state(plan_run_root, recover_from_carry=True).done_stages) if plan_run_root.is_dir() else []
-
-print(json.dumps({
-    "ok": True,
-    "taskKey": task_key,
-    "taskRoot": str(task_root),
-    "stages": stages,
-    "doneStages": done,
-}, ensure_ascii=False, indent=2))
+print(json.dumps({"ok": True, **snapshot}, ensure_ascii=False, indent=2))
 `;
 
 export async function run(args) {