okstra 0.135.0 → 0.136.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.135.0",
+  "version": "0.136.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.135.0",
-  "builtAt": "2026-07-25T13:20:54.916Z",
+  "package": "0.136.0",
+  "builtAt": "2026-07-25T16:28:08.933Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/lib/okstra/interactive.sh

@@ -11,19 +11,6 @@ is_interactive_session() {
   [[ -t 0 && -t 1 ]]
 }
 
-file_mtime() {
-  # Epoch mtime; portable across GNU (stat -c) and macOS/BSD (stat -f).
-  # Validate that the output is a bare integer before accepting it: GNU
-  # `stat -f %m` (a BSD-ism) does NOT fail cleanly — it succeeds with
-  # non-numeric filesystem output, so a plain `a || b` would return that
-  # garbage and later break `-gt`/`-eq` arithmetic under `set -u`.
-  local m=""
-  m="$(stat -c %Y "$1" 2>/dev/null)"
-  [[ "$m" =~ ^[0-9]+$ ]] || m="$(stat -f %m "$1" 2>/dev/null)"
-  [[ "$m" =~ ^[0-9]+$ ]] || m="0"
-  printf '%s' "$m"
-}
-
 split_task_key() {
   local raw_key=""
   raw_key="$(trim_whitespace "${TASK_KEY_INPUT-}")"
@@ -293,74 +280,44 @@ find_latest_final_report() {
   # Args: project_root task_group task_id task_type_filter(optional)
   # Echoes: <abs path to latest final-report-*.md>\t<task-type>
   # Returns: 1 if not found.
+  #
+  # 선택 규칙(mtime 최신, 동률이면 basename)과 산출물 위치 지식은
+  # okstra_ctl.paths.RunRef 가 정본이다. 과거 이 함수는 그 규칙을 bash 로
+  # 재구현해 python 쪽과 손으로 동기화해야 했다.
   local project_root="$1"
   local task_group="$2"
   local task_id="$3"
   local task_type_filter="$4"
 
+  # task-key 단축키 해소와 오타 진단(실제 task-key 목록 출력)은 이 resolver 가
+  # 소유한다. 최신 보고서 선택만 python 정본에 위임한다.
   local task_root=""
   task_root="$(resolve_task_root_for_shortcut "$project_root" "$PROJECT_ID" "$task_group" "$task_id")" || {
     printf 'resume-clarification: unable to resolve task root for the given task-key. See diagnostics above.\n' >&2
     return 1
   }
 
-  local runs_root="$task_root/runs"
-  if [[ ! -d "$runs_root" ]]; then
-    printf 'resume-clarification: no runs/ directory under %s\n' "$task_root" >&2
-    return 1
-  fi
-
-  local search_dirs=()
-  if [[ -n "$task_type_filter" ]]; then
-    search_dirs+=("$runs_root/$task_type_filter/reports")
-  else
-    [[ -d "$runs_root/error-analysis/reports" ]] && search_dirs+=("$runs_root/error-analysis/reports")
-    [[ -d "$runs_root/requirements-discovery/reports" ]] && search_dirs+=("$runs_root/requirements-discovery/reports")
-  fi
-
-  if (( ${#search_dirs[@]} == 0 )); then
-    printf 'resume-clarification: no requirements-discovery or error-analysis reports/ directory under %s/runs/. Run that phase first before invoking --resume-clarification.\n' "$task_root" >&2
-    return 1
-  fi
-
-  # Pick the chronologically newest report (mtime first), matching the Python
-  # resume path (okstra_ctl.wizard's mtime-max). A pure basename sort conflates
-  # phases: across error-analysis/ and requirements-discovery/ dirs the filename
-  # embeds the task-type, so a lexicographic max always favors one phase
-  # regardless of which run is actually newer. Ties (same-second mtime within a
-  # phase dir) fall back to the greater basename so the highest seq/timestamp
-  # wins deterministically.
-  local best_path=""
-  local best_mtime=-1
-  local best_basename=""
-  local candidate=""
-  local candidate_mtime=""
-  local candidate_base=""
-  local d=""
-  for d in "${search_dirs[@]}"; do
-    [[ -d "$d" ]] || continue
-    while IFS= read -r candidate; do
-      candidate_mtime="$(file_mtime "$candidate")"
-      candidate_base="$(basename "$candidate")"
-      if [[ -z "$best_path" \
-            || "$candidate_mtime" -gt "$best_mtime" \
-            || ( "$candidate_mtime" -eq "$best_mtime" && "$candidate_base" > "$best_basename" ) ]]; then
-        best_path="$candidate"
-        best_mtime="$candidate_mtime"
-        best_basename="$candidate_base"
-      fi
-    done < <(find "$d" -maxdepth 1 -type f -name 'final-report-*.md' 2>/dev/null)
-  done
+  local found=""
+  found="$(PYTHONPATH="$WORKSPACE_ROOT/scripts:${PYTHONPATH-}" python3 - \
+             "$task_root" "$task_type_filter" <<'PY'
+import sys
+from okstra_ctl.paths import RunRef
+
+task_root, task_type_filter = sys.argv[1:3]
+types = ((task_type_filter,) if task_type_filter
+         else ("error-analysis", "requirements-discovery"))
+ref = RunRef.latest_under(task_root, types)
+if ref is not None:
+    sys.stdout.write(f"{ref.report}\t{ref.task_type}")
+PY
+)" || return 1
 
-  if [[ -z "$best_path" ]]; then
-    printf 'resume-clarification: no final-report-*.md found for task %s:%s under %s\n' \
-      "$task_group" "$task_id" "$runs_root" >&2
+  if [[ -z "$found" ]]; then
+    printf 'resume-clarification: no final-report-*.md found for task %s:%s under %s/runs\n' \
+      "$task_group" "$task_id" "$task_root" >&2
     return 1
   fi
-
-  local resolved_type=""
-  resolved_type="$(basename "$(dirname "$(dirname "$best_path")")")"
-  printf '%s\t%s\n' "$best_path" "$resolved_type"
+  printf '%s\n' "$found"
 }
 
 run_resume_clarification() {

package/runtime/bin/okstra-antigravity-exec.sh

@@ -290,15 +290,17 @@ if (( idle_timeout_secs > 0 )); then
     while kill -0 "$agy_pid" 2>/dev/null; do
       sleep "$poll_interval"
       kill -0 "$agy_pid" 2>/dev/null || exit 0
-      # GNU `stat -c` 우선 + 숫자 검증. BSD-ism `stat -f %m` 은 Linux 에서 깨끗이
-      # 실패하지 않고 비숫자 파일시스템 출력으로 성공해 아래 산술을 set -u 에서
-      # 깨뜨린다 — file_mtime(lib/okstra/interactive.sh) 와 동일 가드.
+      # Portable mtime probe: GNU (stat -c %Y) first, macOS/BSD (stat -f %m) as
+      # the fallback, 0 as the floor. Validate each result as a bare integer
+      # before accepting it — on Linux the BSD-ism `stat -f %m` does NOT fail
+      # cleanly; it succeeds and prints non-numeric filesystem output, which
+      # would break the arithmetic below under `set -u`.
       #
-      # `|| true` 는 필수다. macOS 에는 GNU `stat -c` 가 없어 exit 1 이고,
-      # `2>/dev/null` 은 stderr 만 막지 종료코드는 막지 못한다. 이 워치독은 명시적
-      # `( ) &` 서브셸이라 위쪽 `set -e` 를 상속하므로, 실패한 할당 하나가 첫 폴링에서
-      # 워치독을 통째로 죽인다 — 조용히, 로그 한 줄 없이. file_mtime 이 같은 코드로도
-      # 멀쩡한 것은 항상 `$( )` 안에서 호출돼 errexit 을 상속하지 않기 때문이다.
+      # `|| true` is mandatory. macOS has no GNU `stat -c`, so that call exits 1,
+      # and `2>/dev/null` suppresses stderr but not the exit code. This watchdog
+      # is an explicit `( ) &` subshell, so it inherits whatever errexit setting
+      # is in force; under `set -e` a single failed assignment kills the whole
+      # watchdog on the first poll — silently, without a log line.
       last_mtime="$(stat -c %Y "$log_path" 2>/dev/null || true)"
       [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime="$(stat -f %m "$log_path" 2>/dev/null || true)"
       [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime=0

package/runtime/bin/okstra-claude-exec.sh

@@ -132,15 +132,17 @@ if (( idle_timeout_secs > 0 )); then
     while kill -0 "$claude_pid" 2>/dev/null; do
       sleep "$poll_interval"
       kill -0 "$claude_pid" 2>/dev/null || exit 0
-      # GNU `stat -c` 우선 + 숫자 검증. BSD-ism `stat -f %m` 은 Linux 에서 깨끗이
-      # 실패하지 않고 비숫자 파일시스템 출력으로 성공해 아래 산술을 set -u 에서
-      # 깨뜨린다 — file_mtime(lib/okstra/interactive.sh) 와 동일 가드.
+      # Portable mtime probe: GNU (stat -c %Y) first, macOS/BSD (stat -f %m) as
+      # the fallback, 0 as the floor. Validate each result as a bare integer
+      # before accepting it — on Linux the BSD-ism `stat -f %m` does NOT fail
+      # cleanly; it succeeds and prints non-numeric filesystem output, which
+      # would break the arithmetic below under `set -u`.
       #
-      # `|| true` 는 필수다. macOS 에는 GNU `stat -c` 가 없어 exit 1 이고,
-      # `2>/dev/null` 은 stderr 만 막지 종료코드는 막지 못한다. 이 워치독은 명시적
-      # `( ) &` 서브셸이라 위쪽 `set -e` 를 상속하므로, 실패한 할당 하나가 첫 폴링에서
-      # 워치독을 통째로 죽인다 — 조용히, 로그 한 줄 없이. file_mtime 이 같은 코드로도
-      # 멀쩡한 것은 항상 `$( )` 안에서 호출돼 errexit 을 상속하지 않기 때문이다.
+      # `|| true` is mandatory. macOS has no GNU `stat -c`, so that call exits 1,
+      # and `2>/dev/null` suppresses stderr but not the exit code. This watchdog
+      # is an explicit `( ) &` subshell, so it inherits whatever errexit setting
+      # is in force; under `set -e` a single failed assignment kills the whole
+      # watchdog on the first poll — silently, without a log line.
       last_mtime="$(stat -c %Y "$log_path" 2>/dev/null || true)"
       [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime="$(stat -f %m "$log_path" 2>/dev/null || true)"
       [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime=0

package/runtime/bin/okstra-codex-exec.sh

@@ -421,15 +421,17 @@ if (( idle_timeout_secs > 0 )); then
     while kill -0 "$codex_pid" 2>/dev/null; do
       sleep "$poll_interval"
       kill -0 "$codex_pid" 2>/dev/null || exit 0
-      # GNU `stat -c` 우선 + 숫자 검증. BSD-ism `stat -f %m` 은 Linux 에서 깨끗이
-      # 실패하지 않고 비숫자 파일시스템 출력으로 성공해 아래 산술을 set -u 에서
-      # 깨뜨린다 — file_mtime(lib/okstra/interactive.sh) 와 동일 가드.
+      # Portable mtime probe: GNU (stat -c %Y) first, macOS/BSD (stat -f %m) as
+      # the fallback, 0 as the floor. Validate each result as a bare integer
+      # before accepting it — on Linux the BSD-ism `stat -f %m` does NOT fail
+      # cleanly; it succeeds and prints non-numeric filesystem output, which
+      # would break the arithmetic below under `set -u`.
       #
-      # `|| true` 는 필수다. macOS 에는 GNU `stat -c` 가 없어 exit 1 이고,
-      # `2>/dev/null` 은 stderr 만 막지 종료코드는 막지 못한다. 이 워치독은 명시적
-      # `( ) &` 서브셸이라 위쪽 `set -e` 를 상속하므로, 실패한 할당 하나가 첫 폴링에서
-      # 워치독을 통째로 죽인다 — 조용히, 로그 한 줄 없이. file_mtime 이 같은 코드로도
-      # 멀쩡한 것은 항상 `$( )` 안에서 호출돼 errexit 을 상속하지 않기 때문이다.
+      # `|| true` is mandatory. macOS has no GNU `stat -c`, so that call exits 1,
+      # and `2>/dev/null` suppresses stderr but not the exit code. This watchdog
+      # is an explicit `( ) &` subshell, so it inherits whatever errexit setting
+      # is in force; under `set -e` a single failed assignment kills the whole
+      # watchdog on the first poll — silently, without a log line.
       last_mtime="$(stat -c %Y "$log_path" 2>/dev/null || true)"
       [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime="$(stat -f %m "$log_path" 2>/dev/null || true)"
       [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime=0

package/runtime/python/okstra_ctl/backfill.py

@@ -10,6 +10,7 @@ from typing import List
 from okstra_project.dirs import tasks_root
 
 from .ids import build_run_id
+from .paths import runs_dir_of
 from .invocation import save_invocation
 from .jsonl import append_jsonl, read_jsonl, rotate_recent_if_needed
 from .project_meta import _project_meta_path
@@ -130,7 +131,7 @@ def backfill_project(home: Path, project_id: str, project_root: Path) -> int:
     manifest_re = _re.compile(r"^run-manifest-(?P<tt>.+)-(?P<seq>\d+)\.json$")
     for group_dir in sorted(p for p in base.iterdir() if p.is_dir()):
         for task_dir in sorted(p for p in group_dir.iterdir() if p.is_dir()):
-            runs = task_dir / "runs"
+            runs = runs_dir_of(task_dir)
             if not runs.is_dir():
                 continue
             for manifests in _iter_manifest_dirs(runs):

package/runtime/python/okstra_ctl/context_cost.py

@@ -13,6 +13,7 @@ import sys
 from pathlib import Path
 from typing import Iterable
 
+from okstra_ctl.paths import RunRef, runs_dir_of
 from okstra_ctl.task_target import resolve_task_root, project_rel
 
 
@@ -102,7 +103,7 @@ def _find_current_run_dir(
     task_type = manifest.get("workflow", {}).get("currentPhase") or manifest.get("taskType")
     if not isinstance(task_type, str) or not task_type:
         return None
-    candidate = task_root / "runs" / task_type
+    candidate = RunRef.from_task_root(task_root, task_type).run_dir
     return candidate if candidate.is_dir() else None
 
 
@@ -407,7 +408,7 @@ def analyze_task_bundle(task_root: Path, project_root: Path) -> dict:
     task_file_count, task_bytes = _count_files(all_task_files)
     current_run_file_count, current_run_bytes = _count_files(_all_files(run_dir)) if run_dir else (0, 0)
     legacy_timestamp_files = [
-        path for path in (task_root / "runs").rglob("*")
+        path for path in runs_dir_of(task_root).rglob("*")
         if path.is_file() and _is_timestamped_legacy_artifact(path)
     ]
 

package/runtime/python/okstra_ctl/error_log_core.py

@@ -8,9 +8,11 @@ from __future__ import annotations
 import json
 from pathlib import Path
 
+from .paths import runs_dir_of
+
 
 def glob_error_logs(task_root: Path) -> list[Path]:
-    runs = task_root / "runs"
+    runs = runs_dir_of(task_root)
     if not runs.exists():
         return []
     flat = runs.glob("*/logs/errors-*.jsonl")

package/runtime/python/okstra_ctl/handoff.py

@@ -14,6 +14,7 @@ from typing import Any, Callable, Dict, List, Optional, Tuple
 
 from . import consumers, stage_targets, worktree_registry
 from .final_report_paths import final_report_markdown_path
+from .paths import RunRef
 from .worktree import (compute_branch_name, compute_worktree_path,
                        main_worktree_path, is_dirty_excluding_okstra,
                        nested_worktree_excludes, is_ancestor, merge_branch,
@@ -62,7 +63,7 @@ def latest_whole_task_fv_accepted(project_root, project_id: str,
                           f"{project_id}:{task_group}:{task_id}")
     if root is None:
         return ""
-    reports_dir = root / "runs" / "final-verification" / "reports"
+    reports_dir = RunRef.from_task_root(root, "final-verification").reports_dir
     for dj in sorted(reports_dir.glob("final-report-*.data.json"),
                      reverse=True):
         try:

package/runtime/python/okstra_ctl/implementation_outcome.py

@@ -7,6 +7,7 @@ from pathlib import Path
 from typing import Any
 
 from .consumers import read_stage_consumer_state
+from .paths import RunRef
 from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
 
 
@@ -27,7 +28,7 @@ def derive_implementation_outcome(task_root: Path) -> ImplementationOutcome:
     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")
 
@@ -133,7 +134,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 +144,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,7 +171,7 @@ 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
 
 
@@ -205,7 +206,7 @@ def _carry_head_commit(carry: dict[str, Any]) -> str:
 
 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/path_hints.py

@@ -12,6 +12,8 @@ from okstra_project.dirs import (
     okstra_home,
 )
 
+from .paths import runs_dir_of
+
 RUN_CONTEXT_KIND = "run-context"
 RUN_CONTEXT_SCHEMA_VERSION = "2.0"
 ACTIVE_CONTEXT_KIND = "active-run-context"
@@ -359,7 +361,7 @@ def _task_path_set(task_root: Path) -> dict[str, Path]:
         "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",
         "recap_dir": recap_dir,

package/runtime/python/okstra_ctl/paths.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 
 import os
 import re
+from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Optional
 
@@ -30,6 +31,8 @@ __all__ = [
     "OKSTRA_RELATIVE",
     "TASKS_RELATIVE",
     "DISCOVERY_RELATIVE",
+    "RunRef",
+    "runs_dir_of",
     "compute_run_paths",
     "next_run_seq",
     "resolve_under_root",
@@ -40,6 +43,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 +302,15 @@ 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 container_paths(project_root: Path, task_group: str, task_id: str) -> dict:
@@ -161,7 +420,7 @@ def compute_run_paths(
     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"
     recap_dir = task_root / "recap"

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/wizard.py

@@ -84,7 +84,7 @@ from okstra_ctl.worktree import (
     preview_stage_worktree_decision,
     preview_worktree_decision,
 )
-from okstra_ctl.paths import task_dir, task_runs_dir
+from okstra_ctl.paths import RunRef, task_dir, task_runs_dir
 from okstra_ctl.work_categories import resolve_work_category
 from okstra_ctl.run_context import latest_run_inputs
 from okstra_project.dirs import project_json_path
@@ -1794,8 +1794,10 @@ def _list_implementation_planning_reports(
     # Run seq lives in the filename, not a per-run subdirectory: every
     # implementation-planning run writes into the same flat `reports/`
     # dir (see paths.py — `run_reports = runs/<task-type>/reports`).
-    reports_dir = (task_runs_dir(state.project_root, state.task_group, state.task_id)
-                   / "implementation-planning" / "reports")
+    reports_dir = RunRef(
+        project_root=state.project_root, task_group=state.task_group,
+        task_id=state.task_id, task_type="implementation-planning",
+    ).reports_dir
     if not reports_dir.is_dir():
         return []
     pat = re.compile(r"^final-report-implementation-planning-(\d+)\.md$")

package/runtime/validators/validate-run.py

@@ -43,6 +43,7 @@ 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.md_table import (  # noqa: E402
     is_separator_row as _is_markdown_separator,
     split_pipe_row as _split_pipe_row,
@@ -1143,17 +1144,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 +3128,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 +3492,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 "