okstra 0.135.0 → 0.137.0

package/runtime/python/okstra_ctl/implementation_outcome.py

@@ -6,7 +6,12 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
-from .consumers import read_stage_consumer_state
+from .consumers import (
+    FAILED_CARRY_STATUSES,
+    carry_head_commit,
+    read_stage_consumer_state,
+)
+from .paths import RunRef, task_manifest_file
 from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
 
 
@@ -22,16 +27,16 @@ class ImplementationOutcome:
 
 def derive_implementation_outcome(task_root: Path) -> ImplementationOutcome:
     task_root = Path(task_root)
-    manifest = _load_json(task_root / "task-manifest.json")
+    manifest = _load_json(task_manifest_file(task_root))
     workflow = manifest.get("workflow") if isinstance(manifest.get("workflow"), dict) else {}
     if workflow.get("currentPhase") != "implementation":
         return ImplementationOutcome(completed=False, reason="current phase is not implementation")
 
-    plan_run_root = task_root / "runs" / "implementation-planning"
+    plan_run_root = RunRef.from_task_root(task_root, "implementation-planning").run_dir
     if not plan_run_root.is_dir():
         return ImplementationOutcome(completed=False, reason="implementation-planning run root missing")
 
-    stage_map = _load_stage_map(task_root, manifest)
+    stage_map = load_stage_map(task_root, manifest)
     if not stage_map:
         return ImplementationOutcome(completed=False, reason="stage map unavailable")
 
@@ -52,7 +57,7 @@ def derive_implementation_outcome(task_root: Path) -> ImplementationOutcome:
     return ImplementationOutcome(
         completed=True,
         stages=sorted(required_stages),
-        head_commit=str(latest_done.get("head_commit") or "") or _carry_head_commit(latest_carry),
+        head_commit=str(latest_done.get("head_commit") or "") or carry_head_commit(latest_carry),
         report_path=_latest_implementation_report(task_root),
         next_recommended_phase=DEFAULT_NEXT_PHASE["implementation"],
         reason="all implementation stages have pass-grade carry and done rows",
@@ -66,7 +71,7 @@ def reconcile_implementation_outcome(project_root: Path, task_root: Path) -> boo
     if not outcome.completed:
         return False
 
-    manifest_path = task_root / "task-manifest.json"
+    manifest_path = task_manifest_file(task_root)
     manifest = _load_json(manifest_path)
     workflow = manifest.get("workflow")
     if not isinstance(workflow, dict):
@@ -109,7 +114,7 @@ def _load_json(path: Path) -> dict[str, Any]:
     return data if isinstance(data, dict) else {}
 
 
-def _load_stage_map(task_root: Path, manifest: dict[str, Any]) -> list[dict[str, Any]]:
+def load_stage_map(task_root: Path, manifest: dict[str, Any]) -> list[dict[str, Any]]:
     plan_path = _source_plan_path(task_root, manifest)
     if not plan_path.is_file():
         return []
@@ -133,7 +138,7 @@ def _load_stage_map(task_root: Path, manifest: dict[str, Any]) -> list[dict[str,
 
 
 def _source_plan_path(task_root: Path, manifest: dict[str, Any]) -> Path:
-    carry_dir = task_root / "runs" / "implementation" / "carry"
+    carry_dir = RunRef.from_task_root(task_root, "implementation").carry_dir
     for carry_path in sorted(carry_dir.glob("stage-*.json")):
         value = _load_json(carry_path).get("sourcePlanPath")
         if isinstance(value, str) and value:
@@ -143,7 +148,7 @@ def _source_plan_path(task_root: Path, manifest: dict[str, Any]) -> Path:
     if isinstance(latest, str) and "implementation-planning" in latest:
         return _resolve_relative(task_root, latest)
 
-    reports = task_root / "runs" / "implementation-planning" / "reports"
+    reports = RunRef.from_task_root(task_root, "implementation-planning").reports_dir
     candidates = sorted(reports.glob("final-report-implementation-planning-*.md"))
     return candidates[-1] if candidates else Path()
 
@@ -170,13 +175,13 @@ def _project_root_from_task_root(task_root: Path) -> Path:
 
 
 def _load_carry(task_root: Path, stage: int) -> dict[str, Any] | None:
-    data = _load_json(task_root / "runs" / "implementation" / "carry" / f"stage-{stage}.json")
+    data = _load_json(RunRef.from_task_root(task_root, "implementation").carry(stage))
     return data or None
 
 
 def _carry_passed(carry: dict[str, Any]) -> bool:
     status = str(carry.get("status") or "").lower()
-    if status in {"fail", "failed", "blocked", "error", "aborted"}:
+    if status in FAILED_CARRY_STATUSES:
         return False
     conformance = carry.get("conformance")
     if isinstance(conformance, dict):
@@ -187,25 +192,10 @@ def _carry_passed(carry: dict[str, Any]) -> bool:
     return not (isinstance(unverified, list) and unverified)
 
 
-def _carry_head_commit(carry: dict[str, Any]) -> str:
-    stage_range = carry.get("stageCommitRange")
-    if isinstance(stage_range, dict) and stage_range.get("head"):
-        return str(stage_range["head"])
-    for key in ("head_sha", "head_commit", "head"):
-        value = carry.get(key)
-        if value:
-            return str(value)
-    commits = carry.get("commits")
-    if isinstance(commits, list) and commits:
-        last = commits[-1]
-        if isinstance(last, dict) and last.get("sha"):
-            return str(last["sha"])
-    return ""
-
 
 def _latest_implementation_report(task_root: Path) -> str:
     reports = sorted(
-        (task_root / "runs" / "implementation").glob(
+        RunRef.from_task_root(task_root, "implementation").run_dir.glob(
             "stage-*/reports/final-report-implementation-*.md"
         )
     )

package/runtime/python/okstra_ctl/implementation_stage.py

@@ -14,7 +14,7 @@ from pathlib import Path
 from typing import Any
 
 from . import stage_targets
-from .design_prep import DesignPrepDecision, resolve_design_prep
+from .design_prep import DesignPrepDecision, DesignPrepError, resolve_design_prep
 from .final_report_paths import final_report_data_path
 from .stage_reconcile import auto_reconcile_best_effort
 
@@ -56,7 +56,12 @@ def _as_implementation_stage_error(exc: Exception) -> ImplementationStageError:
 def _resolve_stage_design_prep(plan_path: Path, stage: int) -> DesignPrepDecision:
     plan_data_path = final_report_data_path(plan_path)
     if plan_data_path.is_file():
-        return resolve_design_prep(plan_data_path, stage)
+        try:
+            return resolve_design_prep(plan_data_path, stage)
+        except DesignPrepError as exc:
+            # prepare catches ImplementationStageError → PrepareError; an
+            # untranslated DesignPrepError leaves okstra_ctl.run as a traceback.
+            raise _as_implementation_stage_error(exc) from exc
     return DesignPrepDecision(
         outcome="proceed",
         effective_items=(),

package/runtime/python/okstra_ctl/path_hints.py

@@ -12,6 +12,8 @@ from okstra_project.dirs import (
     okstra_home,
 )
 
+from .paths import runs_dir_of, task_manifest_file, task_timeline_file
+
 RUN_CONTEXT_KIND = "run-context"
 RUN_CONTEXT_SCHEMA_VERSION = "2.0"
 ACTIVE_CONTEXT_KIND = "active-run-context"
@@ -354,14 +356,14 @@ def _task_path_set(task_root: Path) -> dict[str, Path]:
     history_dir = task_root / "history"
     recap_dir = task_root / "recap"
     return {
-        "task_manifest": task_root / "task-manifest.json",
+        "task_manifest": task_manifest_file(task_root),
         "task_index": task_root / "task-index.md",
         "instruction_set": instruction_set,
         "analysis_packet": instruction_set / "analysis-packet.md",
         "task_qa": task_root / "qa",
-        "runs_dir": task_root / "runs",
+        "runs_dir": runs_dir_of(task_root),
         "history_dir": history_dir,
-        "timeline_file": history_dir / "timeline.json",
+        "timeline_file": task_timeline_file(task_root),
         "recap_dir": recap_dir,
         "recap_log": recap_dir / "recap-log.jsonl",
         "final_report_template": instruction_set / "final-report-template.md",

package/runtime/python/okstra_ctl/paths.py

@@ -15,11 +15,13 @@ from __future__ import annotations
 
 import os
 import re
+from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Optional
 
 from okstra_project.dirs import (
     DISCOVERY_RELATIVE,
+    TASK_MANIFEST_FILENAME,
     OKSTRA_RELATIVE,
     TASKS_RELATIVE,
     okstra_home,
@@ -30,6 +32,8 @@ __all__ = [
     "OKSTRA_RELATIVE",
     "TASKS_RELATIVE",
     "DISCOVERY_RELATIVE",
+    "RunRef",
+    "runs_dir_of",
     "compute_run_paths",
     "next_run_seq",
     "resolve_under_root",
@@ -40,6 +44,254 @@ __all__ = [
 ]
 
 
+_STAGED_TASK_TYPES = ("implementation", "final-verification")
+# 발견용: bash `find -name 'final-report-*.md'` 와 같은 범위 — seq 이전 세대의
+# 타임스탬프 파일명도 잡아야 옛 번들에서 조용히 실패하지 않는다.
+_REPORT_NAME_RE = re.compile(r"^final-report-.+\.md$")
+# seq 추출용: 정본 이름 `final-report-<task-type>-<NNN>.md` 일 때만.
+_REPORT_SEQ_RE = re.compile(r"^final-report-.+-(?P<seq>\d{3,})\.md$")
+_TASKS_SEGMENTS = Path(TASKS_RELATIVE).parts
+
+
+def _newest_report(reports_dir: Path) -> Optional[Path]:
+    """reports 디렉터리에서 mtime 최신 final-report. 동률이면 basename 큰 쪽."""
+    if not reports_dir.is_dir():
+        return None
+    found = [
+        entry for entry in reports_dir.iterdir()
+        if entry.is_file() and _REPORT_NAME_RE.match(entry.name)
+    ]
+    if not found:
+        return None
+    return max(found, key=lambda p: (p.stat().st_mtime, p.name))
+
+
+def _project_root_of(task_root: Path) -> Optional[Path]:
+    """canonical `<project>/.okstra/tasks/<g>/<t>` 일 때만 project root.
+
+    검증기는 이 형태가 아닌 트리(테스트 픽스처, 이식된 번들)에도 돌아간다.
+    그때는 project root 를 알 수 없으므로 지어내지 않고 None 을 돌려준다 —
+    경로 유래 ref 는 task_root 를 고정하므로 계산에 필요하지도 않다.
+    """
+    parts = task_root.parts
+    if len(parts) > len(_TASKS_SEGMENTS) + 2 and parts[-4:-2] == _TASKS_SEGMENTS:
+        return Path(*parts[:-4])
+    return None
+
+
+@dataclass(frozen=True)
+class RunRef:
+    """하나의 run 을 identity 로 지명하는 read-side 참조.
+
+    산출물 경로를 종류별로 계산해 돌려주되 내용은 읽지 않는다 — 파싱은
+    consumers / stage_targets / run_context 같은 기존 로더가 계속 소유한다.
+
+    stage 세그먼트는 아티팩트 종류마다 다르게 적용된다. run 디렉터리는
+    stage-isolated 이지만 carry 사이드카는 flat 이므로(stage N+1 이 N 의 사이드카를
+    N 의 run 레이아웃을 모른 채 찾아야 한다), 그 예외는 `carry()` 안에만 산다.
+    호출자가 `run_dir` 에서 손으로 올라가면 안 된다.
+
+    `compute_run_paths()` 가 같은 레이아웃을 write-side 에서 계산한다. 둘의 합의는
+    tests/contract/test_task_path_ssot.py 가 잠근다.
+    """
+
+    project_root: Optional[Path]
+    task_group: str
+    task_id: str
+    task_type: str
+    seq: Optional[int] = None
+    stage: Optional[int] = None
+    # 경로에서 만든 ref 는 받은 task_root 를 고정한다. identity 로 재계산하면
+    # canonical 하지 않은 트리에서 조용히 다른 곳을 가리킨다.
+    task_root_override: Optional[Path] = None
+    # 경로에서 만든 ref 는 찾은 파일을 그대로 고정한다 — 레거시 타임스탬프
+    # 이름은 identity 로 재구성할 수 없다.
+    report_override: Optional[Path] = None
+
+    @property
+    def task_root(self) -> Path:
+        if self.task_root_override is not None:
+            return self.task_root_override
+        if self.project_root is None:
+            raise ValueError("RunRef has neither a project_root nor a task_root")
+        return task_dir(self.project_root, self.task_group, self.task_id)
+
+    @property
+    def runs_dir(self) -> Path:
+        return runs_dir_of(self.task_root)
+
+    @property
+    def run_dir(self) -> Path:
+        segment = slugify(self.task_type)
+        run_dir = self.runs_dir / segment
+        if segment in _STAGED_TASK_TYPES and self.stage is not None:
+            return run_dir / f"stage-{int(self.stage)}"
+        return run_dir
+
+    @property
+    def reports_dir(self) -> Path:
+        return self.run_dir / "reports"
+
+    @property
+    def carry_dir(self) -> Path:
+        """implementation 의 carry 는 stage-SHARED 라 flat 이다(§carry 참고)."""
+        segment = slugify(self.task_type)
+        if segment == "implementation":
+            return self.runs_dir / segment / "carry"
+        return self.run_dir / "carry"
+
+    @property
+    def report(self) -> Path:
+        if self.report_override is not None:
+            return self.report_override
+        return self.reports_dir / f"final-report{self._suffix}.md"
+
+    @property
+    def manifest(self) -> Path:
+        return self.run_dir / "manifests" / f"run-manifest{self._suffix}.json"
+
+    def carry(self, stage: int) -> Path:
+        """stage 의 carry 사이드카. implementation 은 stage-SHARED(flat)다."""
+        return self.carry_dir / f"stage-{int(stage)}.json"
+
+    @property
+    def _suffix(self) -> str:
+        if self.seq is None:
+            raise ValueError(
+                "RunRef.seq is unset — a seq-less ref can name the run directory "
+                "but not an artifact file. Use RunRef.latest() or pass seq."
+            )
+        return f"-{slugify(self.task_type)}-{int(self.seq):03d}"
+
+    @classmethod
+    def from_task_root(
+        cls,
+        task_root: Path,
+        task_type: str,
+        *,
+        seq: Optional[int] = None,
+        stage: Optional[int] = None,
+    ) -> "RunRef":
+        """task_root 경로만 쥔 호출자를 위한 어댑터.
+
+        받은 task_root 를 고정하므로 canonical 하지 않은 트리에서도 왕복한다.
+        복원되는 group/id 는 slug 세그먼트다.
+        """
+        task_root = Path(task_root)
+        return cls(
+            project_root=_project_root_of(task_root),
+            task_group=task_root.parent.name,
+            task_id=task_root.name,
+            task_type=task_type,
+            seq=seq,
+            stage=stage,
+            task_root_override=task_root,
+        )
+
+    @classmethod
+    def from_run_dir(cls, run_dir: Path, *, seq: Optional[int] = None) -> "RunRef":
+        """run 디렉터리에서 정체를 복원한다.
+
+        `<task_root>/runs/<task-type>[/stage-<N>]` 를 해석한다. `runs` 앵커가
+        없으면 ValueError — 관대한 폴백이 필요한 호출자는 직접 감싸라.
+        """
+        run_dir = Path(run_dir)
+        stage = None
+        if run_dir.name.startswith("stage-"):
+            stage = int(run_dir.name[len("stage-"):])
+            run_dir = run_dir.parent
+        if run_dir.parent.name != "runs":
+            raise ValueError(f"not an okstra run directory: {run_dir}")
+
+        return cls.from_task_root(
+            run_dir.parent.parent, run_dir.name, seq=seq, stage=stage
+        )
+
+    @classmethod
+    def from_report_path(cls, report_path: Path) -> "RunRef":
+        """final-report 경로에서 정체를 복원한다.
+
+        복원되는 task-group/task-id 는 slug 세그먼트다. slugify 가 멱등이라
+        경로 왕복에는 영향이 없지만, 원래 표기가 필요하면 task-manifest 를 읽어라.
+        """
+        report_path = Path(report_path)
+        if not _REPORT_NAME_RE.match(report_path.name):
+            raise ValueError(f"not a final-report path: {report_path}")
+        matched = _REPORT_SEQ_RE.match(report_path.name)
+        ref = cls.from_run_dir(
+            report_path.parent.parent,
+            seq=int(matched.group("seq")) if matched else None,
+        )
+        return replace(ref, report_override=report_path)
+
+    def sibling(self, task_type: str) -> "RunRef":
+        """같은 task 의 다른 task-type 을 가리키는 ref.
+
+        seq/stage 는 이 run 의 것이므로 형제에게 물려주지 않는다.
+        """
+        return replace(
+            self, task_type=task_type, seq=None, stage=None, report_override=None
+        )
+
+    @classmethod
+    def latest(
+        cls, project_root: Path, task_group: str, task_id: str, task_type: str
+    ) -> Optional["RunRef"]:
+        """task-type 의 최신 final-report 를 가리키는 ref. 없으면 None.
+
+        최신 기준은 mtime 이고, 동률이면 basename 이 큰 쪽이다 — bash
+        `find_latest_final_report` 와 wizard 가 쓰던 규칙을 그대로 옮긴 것이다.
+        stage 하위 디렉터리는 훑지 않는다(옮겨온 두 구현과 동일 범위).
+        """
+        ref = cls(
+            project_root=Path(project_root), task_group=task_group,
+            task_id=task_id, task_type=task_type,
+        )
+        best = _newest_report(ref.reports_dir)
+        return None if best is None else cls.from_report_path(best)
+
+    @classmethod
+    def latest_across(
+        cls,
+        project_root: Path,
+        task_group: str,
+        task_id: str,
+        task_types: Optional[tuple[str, ...]] = None,
+    ) -> Optional["RunRef"]:
+        """여러 task-type 을 가로질러 최신 final-report 를 가리키는 ref.
+
+        `task_types` 를 주지 않으면 runs/ 에 실제로 존재하는 모든 task-type 을
+        훑는다. 비교 규칙은 `latest` 와 같다(mtime, 동률이면 basename).
+        """
+        return cls.latest_under(
+            task_dir(project_root, task_group, task_id), task_types
+        )
+
+    @classmethod
+    def latest_under(
+        cls, task_root: Path, task_types: Optional[tuple[str, ...]] = None
+    ) -> Optional["RunRef"]:
+        """`latest_across` 의 task_root 진입점.
+
+        task-key 단축키/오타 진단을 이미 거쳐 task_root 를 손에 쥔 호출자
+        (bash resume-clarification)가 쓴다.
+        """
+        runs_dir = runs_dir_of(task_root)
+        if task_types is None:
+            if not runs_dir.is_dir():
+                return None
+            task_types = tuple(sorted(p.name for p in runs_dir.iterdir() if p.is_dir()))
+        candidates = [
+            found for task_type in task_types
+            if (found := _newest_report(runs_dir / task_type / "reports")) is not None
+        ]
+        if not candidates:
+            return None
+        return cls.from_report_path(
+            max(candidates, key=lambda p: (p.stat().st_mtime, p.name))
+        )
+
+
 def task_dir(project_root: Path, task_group: str, task_id: str) -> Path:
     """task root 경로: ``<project>/.okstra/tasks/<group-seg>/<id-seg>``.
 
@@ -51,7 +303,29 @@ def task_dir(project_root: Path, task_group: str, task_id: str) -> Path:
 
 def task_runs_dir(project_root: Path, task_group: str, task_id: str) -> Path:
     """task 의 runs 디렉터리: ``task_dir/runs``."""
-    return task_dir(project_root, task_group, task_id) / "runs"
+    return runs_dir_of(task_dir(project_root, task_group, task_id))
+
+
+def runs_dir_of(task_root: Path) -> Path:
+    """task_root 만 쥔 호출자를 위한 runs 디렉터리 접근자.
+
+    task-type 을 모르는 스캐너(backfill·error-log glob·context-cost)가 쓴다.
+    `runs` 세그먼트 리터럴은 이 함수와 `compute_run_paths` 에만 존재한다."""
+    return Path(task_root) / "runs"
+
+
+def task_manifest_file(task_root: Path) -> Path:
+    """task 의 lifecycle manifest 경로.
+
+    task-type 을 모르는 호출자(recap·time-report·error-report·work-categories)가
+    쓰는 진입점이다. `RunRef.manifest` 는 한 *run* 의 run-manifest 이고, `report_finalize.task_manifest_path`
+    는 run manifest 의 fallback 체인을 타는 해소기다 — 셋 다 다른 것이므로 이름을 나눈다."""
+    return Path(task_root) / TASK_MANIFEST_FILENAME
+
+
+def task_timeline_file(task_root: Path) -> Path:
+    """task 의 history timeline 경로."""
+    return Path(task_root) / "history" / "timeline.json"
 
 
 def container_paths(project_root: Path, task_group: str, task_id: str) -> dict:
@@ -156,14 +430,14 @@ def compute_run_paths(
     discovery_dir = project_root / DISCOVERY_RELATIVE
 
     task_root = tasks_root / task_group_segment / task_id_segment
-    task_manifest = task_root / "task-manifest.json"
+    task_manifest = task_manifest_file(task_root)
     task_index = task_root / "task-index.md"
     instruction_set = task_root / "instruction-set"
     analysis_packet = instruction_set / "analysis-packet.md"
     task_qa = task_root / "qa"
-    runs_dir = task_root / "runs"
+    runs_dir = runs_dir_of(task_root)
     history_dir = task_root / "history"
-    timeline_file = history_dir / "timeline.json"
+    timeline_file = task_timeline_file(task_root)
     recap_dir = task_root / "recap"
     recap_log = recap_dir / "recap-log.jsonl"
 

package/runtime/python/okstra_ctl/plan_run_root.py

@@ -48,10 +48,10 @@ def resolve_plan_run_root_by_task_key(
     from . import paths
     from .consumers import read_consumers
 
-    reports_dir = (
-        paths.task_dir(project_root, task_group, task_id)
-        / "runs" / "implementation-planning" / "reports"
-    )
+    reports_dir = paths.RunRef(
+        project_root=project_root, task_group=task_group, task_id=task_id,
+        task_type="implementation-planning",
+    ).reports_dir
     if not reports_dir.is_dir():
         raise PrepareError(
             "container up: implementation-planning run 을 찾을 수 없습니다 "

package/runtime/python/okstra_ctl/recap.py

@@ -12,6 +12,8 @@ import sys
 from pathlib import Path
 
 from okstra_ctl.ids import slugify_task_segment
+from okstra_ctl.paths import task_timeline_file
+from okstra_project import read_task_key
 from okstra_ctl.run_context import dir_flock
 from okstra_ctl.task_target import resolve_task_root, project_rel
 
@@ -19,7 +21,7 @@ NOTE_KINDS = ("verification-evidence", "decision-draft", "analysis-note")
 
 
 def _load_timeline(task_root: Path) -> list[dict]:
-    path = task_root / "history" / "timeline.json"
+    path = task_timeline_file(task_root)
     if not path.is_file():
         return []
     try:
@@ -30,15 +32,6 @@ def _load_timeline(task_root: Path) -> list[dict]:
     return runs if isinstance(runs, list) else []
 
 
-def _task_key(task_root: Path) -> str:
-    path = task_root / "task-manifest.json"
-    if not path.is_file():
-        return ""
-    try:
-        return json.loads(path.read_text(encoding="utf-8")).get("taskKey", "")
-    except Exception:
-        return ""
-
 
 def assemble_recap(task_root: Path, project_root: Path) -> dict:
     runs = _load_timeline(task_root)
@@ -65,7 +58,7 @@ def assemble_recap(task_root: Path, project_root: Path) -> dict:
         # 최신 상태인 양 보고하게 된다.
         latest_states = snap.get("phaseStates", {}) or {}
     return {
-        "taskKey": _task_key(task_root),
+        "taskKey": read_task_key(task_root),
         "runCount": len(runs),
         "transitions": transitions,
         "latestPhaseStates": latest_states,
@@ -128,7 +121,7 @@ def write_note(task_root, project_root, *, kind, slug, purpose, scope_note,
     if not slug_seg:
         raise ValueError("slug must contain at least one alphanumeric character")
     path = _note_path(notes_dir, slug_seg, created_at)
-    task_key = _task_key(task_root)
+    task_key = read_task_key(task_root)
     frontmatter = _note_frontmatter(
         task_key=task_key, kind=kind, created_at=created_at,
         purpose=purpose, scope_note=scope_note)

package/runtime/python/okstra_ctl/render.py

@@ -23,7 +23,7 @@ import re
 import sys
 from pathlib import Path
 
-from okstra_project.dirs import OKSTRA_DIR_NAME, project_json_path
+from okstra_project.dirs import TASK_MANIFEST_FILENAME, OKSTRA_DIR_NAME, project_json_path
 
 # phase 시퀀스 / 기본 next-phase 매핑의 SSOT 는 workflow 모듈이다. 과거
 # render_task_manifest 가 동일한 리스트/딕셔너리를 로컬에 중복 정의했는데,
@@ -32,6 +32,7 @@ from . import fix_cycles
 from .paths import okstra_home
 from .lead_runtime import lead_runtime_info
 from .path_hints import compact_active_run_context, hydrate_run_context
+from .paths import task_timeline_file
 from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
 
 
@@ -589,7 +590,7 @@ def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
             return str(p)
 
     entries = []
-    for manifest_path in sorted(tasks_root.rglob("task-manifest.json")):
+    for manifest_path in sorted(tasks_root.rglob(TASK_MANIFEST_FILENAME)):
         try:
             manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
         except Exception:
@@ -601,15 +602,15 @@ def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
             continue
         task_root = manifest_path.parent
         timeline_relative = s(manifest, "historyTimelinePath").strip()
-        timeline_path = (
+        timeline_file = (
             (project_root / timeline_relative)
             if timeline_relative
-            else (task_root / "history" / "timeline.json")
+            else task_timeline_file(task_root)
         )
         latest_run = {}
-        if timeline_path.is_file():
+        if timeline_file.is_file():
             try:
-                payload = json.loads(timeline_path.read_text(encoding="utf-8"))
+                payload = json.loads(timeline_file.read_text(encoding="utf-8"))
             except Exception:
                 payload = {}
             runs = payload.get("runs", []) if isinstance(payload, dict) else []
@@ -675,7 +676,7 @@ def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
                 or s(latest_run, "reportPath"),
                 "latestResumeCommandPath": s(manifest, "latestResumeCommandPath")
                 or s(latest_run, "resumeCommandPath"),
-                "historyTimelinePath": timeline_relative or rel(timeline_path),
+                "historyTimelinePath": timeline_relative or rel(timeline_file),
                 "fixCycles": manifest.get("fixCycles")
                 or {"count": 0, "openCycleId": None, "latest": None},
             }
@@ -1525,14 +1526,7 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
     )
     phase_order = workflow.get("phaseSequence", [])
     if not isinstance(phase_order, list) or not phase_order:
-        phase_order = [
-            "requirements-discovery",
-            "error-analysis",
-            "implementation-planning",
-            "implementation",
-            "final-verification",
-            "release-handoff",
-        ]
+        phase_order = list(PHASE_SEQUENCE)
     phase_state_lines = [
         f"- `{phase}`: `{phase_states.get(phase, 'not-started')}`"
         for phase in phase_order

package/runtime/python/okstra_ctl/report_finalize.py

@@ -21,7 +21,7 @@ from pathlib import Path
 from typing import Any, Callable, Mapping, Sequence
 
 from .final_report_paths import final_report_data_path, final_report_markdown_path
-from .paths import task_dir
+from .paths import task_dir, task_manifest_file
 
 
 STEP_TOKEN_USAGE = "token-usage"
@@ -108,15 +108,19 @@ def run_seq(manifest: Mapping[str, Any]) -> str:
 
 
 def task_manifest_path(project_root: Path, manifest: Mapping[str, Any]) -> Path:
+    """Resolve a run manifest's task manifest, falling back through the identity.
+
+    Distinct from `paths.task_manifest_file`, which only names the file inside a
+    known task root — this one decides *which* task root applies.
+    """
     value = string_value(manifest.get("taskManifestPath"))
     if value:
         return resolve_project_path(project_root, value)
     task_root = string_value(manifest.get("taskRootPath"))
     if task_root:
-        return resolve_project_path(project_root, task_root) / "task-manifest.json"
-    return (
+        return task_manifest_file(resolve_project_path(project_root, task_root))
+    return task_manifest_file(
         task_dir(project_root, task_group(manifest), task_id(manifest))
-        / "task-manifest.json"
     )