okstra 0.201.3 → 0.204.0

package/runtime/python/okstra_ctl/manager_view.py

@@ -0,0 +1,217 @@
+"""manager 상태를 한 장짜리 HTML 로 그린다.
+
+manager 가 이미 저장한 파일(projects / task manifest / children / snapshots /
+directives / events)만 읽는다. 하위 프로젝트는 읽지 않는다 — 최신 상태가 필요하면
+먼저 `okstra manager task sync` 를 돌리고, 페이지는 각 task 의 마지막 sync 시각을
+보여 준다.
+"""
+from __future__ import annotations
+
+import html
+import re
+import shlex
+from datetime import datetime, timezone
+from pathlib import Path
+
+from okstra_ctl.jsonl import read_jsonl
+
+from .manager_paths import directives_jsonl_path, events_jsonl_path, view_html_path
+from .manager_store import ManagerError, list_projects, list_tasks, load_manager
+from .manager_sync import status_task
+from .paths import find_asset_root
+
+TEMPLATE_RELATIVE = ("templates", "manager", "view.template.html")
+_MARKER = re.compile(r"\{\{([A-Z]+)\}\}")
+BUCKETS = ("planned", "missing", "running", "done", "blocked")
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _e(value: object) -> str:
+    return html.escape("" if value is None else str(value))
+
+
+def _chip(bucket: str) -> str:
+    return f'<span class="chip {_e(bucket)}">{_e(bucket)}</span>'
+
+
+def _table(headers: tuple[str, ...], rows: list[list[str]], empty: str) -> str:
+    if not rows:
+        return f'<p class="empty">{_e(empty)}</p>'
+    head = "".join(f"<th>{_e(header)}</th>" for header in headers)
+    body = "".join("<tr>" + "".join(f"<td>{cell}</td>" for cell in row) + "</tr>" for row in rows)
+    return f'<div class="scroll"><table><thead><tr>{head}</tr></thead><tbody>{body}</tbody></table></div>'
+
+
+def _file_link(project_root: str, path: str) -> str:
+    """하위 프로젝트 기준 상대 경로를 절대 file 링크로 바꾼다. 빈 값은 `-`."""
+    if not path:
+        return "-"
+    target = Path(path)
+    if not target.is_absolute() and project_root:
+        target = Path(project_root) / target
+    if not target.is_absolute():
+        return f"<code>{_e(path)}</code>"
+    return f'<a href="{_e(target.as_uri())}"><code>{_e(path)}</code></a>'
+
+
+def _command(*args: str) -> str:
+    return shlex.join(["okstra", "manager", *args])
+
+
+def _summary_tiles(totals: dict[str, int]) -> str:
+    tiles = "".join(
+        f'<div class="tile"><div class="count">{totals[bucket]}</div>'
+        f'<div class="label">{_e(bucket)}</div></div>'
+        for bucket in BUCKETS
+    )
+    return f'<div class="tiles">{tiles}</div>'
+
+
+def _projects_table(projects: list[dict]) -> str:
+    rows = [
+        [
+            f"<code class=\"id\">{_e(project.get('projectId'))}</code>",
+            f"<code>{_e(project.get('projectRoot'))}</code>",
+            _e(project.get("role") or "-"),
+            _e(", ".join(project.get("tags") or []) or "-"),
+            _e(project.get("linkedAt") or "-"),
+        ]
+        for project in projects
+    ]
+    return _table(("Project", "Root", "Role", "Tags", "Linked at"), rows, "No projects registered.")
+
+
+def _child_rows(children: list[dict], roots: dict[str, str]) -> list[list[str]]:
+    rows = []
+    for child in children:
+        launch = child.get("launch") if isinstance(child.get("launch"), dict) else {}
+        phase = child.get("currentPhase") or ""
+        phase_state = child.get("currentPhaseState") or ""
+        assignment = " — ".join(part for part in (child.get("role"), child.get("assignment")) if part)
+        # `task split` 하위 태스크는 assignment 대신 범위 목록을 가진다.
+        assignment = assignment or "; ".join(child.get("scope") or [])
+        rows.append(
+            [
+                f"<code>{_e(child.get('taskKey'))}</code>"
+                + ("" if child.get("projectLinked", True) else " " + _chip("unlinked")),
+                _e(child.get("ticketId") or "-"),
+                _chip(str(child.get("summaryBucket") or "planned")),
+                _e(child.get("workStatus") or "-"),
+                _e(f"{phase} ({phase_state})" if phase and phase_state else phase or "-"),
+                _e(child.get("finalVerdict") or "-"),
+                _e(launch.get("status") or "-"),
+                f'<span class="wrap">{_e(assignment or "-")}</span>',
+                _e(child.get("error") or "-"),
+                _file_link("", str(child.get("briefPath") or "")),
+                _file_link(
+                    roots.get(str(child.get("projectId") or ""), ""),
+                    str(child.get("latestReportRecordPath") or ""),
+                ),
+            ]
+        )
+    return rows
+
+
+def _directive_list(directives: list[dict]) -> str:
+    if not directives:
+        return '<p class="empty">No directives.</p>'
+    items = "".join(
+        f"<li><strong>{_e(row.get('scope'))}"
+        f"{' · ' + _e(row.get('projectId')) if row.get('projectId') else ''}</strong>: "
+        f"{_e(row.get('body'))} <span class=\"meta\">{_e(row.get('createdAt'))}</span></li>"
+        for row in directives
+    )
+    return f'<ul class="plain">{items}</ul>'
+
+
+def _event_list(events: list[dict]) -> str:
+    if not events:
+        return '<p class="empty">No events.</p>'
+    items = "".join(
+        f"<li><code>{_e(row.get('createdAt'))}</code> {_e(row.get('event'))}"
+        f"{' · ' + _e(row.get('taskKey')) if row.get('taskKey') else ''}</li>"
+        for row in events
+    )
+    return f'<ul class="plain">{items}</ul>'
+
+
+def _task_panel(home: Path, manager_id: str, task: dict, status: dict, roots: dict[str, str]) -> str:
+    group, task_id = task["taskGroup"], task["taskId"]
+    synced_at = status["lastSnapshot"].get("syncedAt") or ""
+    sync_command = _command(
+        "task", "sync", "--manager-id", manager_id, "--task-group", group, "--task-id", task_id
+    )
+    counts = "".join(
+        f"{_chip(bucket)} {status['summary'][bucket]}"
+        for bucket in BUCKETS
+        if status["summary"][bucket]
+    )
+    head = (
+        f'<div class="task-head"><h3><code>{_e(group)} / {_e(task_id)}</code></h3>'
+        f'<div class="counts">{counts or "<span class=empty>no children</span>"}</div></div>'
+    )
+    meta = (
+        f'<div class="meta">Objective: {_e(task["objective"] or "-")} · '
+        f'Common brief: {_e(status["manifest"].get("commonBriefPath") or "-")} · '
+        f'Progress mode: {_e(task["progressMode"] or "-")}</div>'
+        f'<p class="hint">Last sync: {_e(synced_at or "never")} — refresh with '
+        f"<code>{_e(sync_command)}</code>, then re-run the view command.</p>"
+    )
+    children = _table(
+        ("Child", "Ticket", "Summary", "Work status", "Phase", "Verdict", "Launch", "Assignment", "Error",
+         "Brief", "Latest report"),
+        _child_rows(status["children"], roots),
+        "No child tasks.",
+    )
+    directives = read_jsonl(directives_jsonl_path(home, manager_id, group, task_id))
+    events = read_jsonl(events_jsonl_path(home, manager_id, group, task_id))
+    details = (
+        f"<details><summary>Directives ({len(directives)})</summary>{_directive_list(directives)}</details>"
+        f"<details><summary>Events ({len(events)})</summary>{_event_list(events)}</details>"
+    )
+    return f'<div class="panel">{head}{meta}{children}{details}</div>'
+
+
+def render_view(home: Path, manager_id: str, *, now: str | None = None) -> str:
+    """manager 한 개의 HTML 페이지 본문을 돌려준다."""
+    manager = load_manager(home, manager_id)
+    root = find_asset_root(TEMPLATE_RELATIVE)
+    if root is None:
+        raise ManagerError("manager view template not found: " + "/".join(TEMPLATE_RELATIVE))
+    template = root.joinpath(*TEMPLATE_RELATIVE).read_text(encoding="utf-8")
+    projects = list_projects(home, manager_id)
+    roots = {str(project.get("projectId")): str(project.get("projectRoot") or "") for project in projects}
+    tasks = list_tasks(home, manager_id)
+    totals = dict.fromkeys(BUCKETS, 0)
+    panels = []
+    for task in tasks:
+        status = status_task(home, manager_id, task["taskGroup"], task["taskId"])
+        for bucket in BUCKETS:
+            totals[bucket] += status["summary"][bucket]
+        panels.append(_task_panel(home, manager_id, task, status, roots))
+    meta = (
+        f"Created {_e(manager.get('createdAt') or '-')} · Generated {_e(now or _now_iso())} · "
+        f"{len(projects)} projects · {len(tasks)} manager tasks"
+    )
+    replacements = {
+        "TITLE": _e(f"Okstra manager · {manager.get('managerId') or manager_id}"),
+        "META": meta,
+        "SUMMARY": _summary_tiles(totals),
+        "PROJECTS": _projects_table(projects),
+        "TASKS": "".join(panels) or '<p class="empty">No manager tasks.</p>',
+    }
+    # 한 번에 치환한다. 차례로 바꾸면 앞에서 넣은 사용자 값 속 `{{TASKS}}` 같은
+    # 문자열이 뒤 치환에 다시 걸린다.
+    return _MARKER.sub(lambda match: replacements[match.group(1)], template)
+
+
+def write_view(home: Path, manager_id: str, *, now: str | None = None) -> dict:
+    """페이지를 `managers/<id>/view/index.html` 에 쓰고 경로를 돌려준다."""
+    page = render_view(home, manager_id, now=now)
+    path = view_html_path(home, manager_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(page, encoding="utf-8")
+    return {"managerId": manager_id, "viewPath": str(path), "viewUrl": path.as_uri()}

package/runtime/python/okstra_ctl/model_discovery.py

@@ -73,6 +73,25 @@ def _codex_home() -> Path:
     return Path.home() / ".codex"
 
 
+@lru_cache(maxsize=1)
+def codex_cli_version(codex_bin: str = "codex") -> str:
+    """디스패치에 쓸 codex CLI 의 버전, 알 수 없으면 "".
+
+    `codex --version` 은 `codex-cli 0.155.1` 처럼 마지막 마디에 버전을 싣는다.
+    """
+    try:
+        proc = subprocess.run(
+            [codex_bin, "--version"],
+            capture_output=True, text=True, timeout=20,
+        )
+    except (FileNotFoundError, OSError, subprocess.SubprocessError):
+        return ""
+    if proc.returncode != 0:
+        return ""
+    parts = proc.stdout.split()
+    return parts[-1].strip() if parts else ""
+
+
 def codex_availability(codex_home: Path | None = None) -> tuple[str, ...]:
     """Model slugs the codex CLI last fetched from the provider, or ().
 
@@ -100,6 +119,17 @@ def codex_availability(codex_home: Path | None = None) -> tuple[str, ...]:
     models = payload.get("models") if isinstance(payload, dict) else None
     if not isinstance(models, list):
         return ()
+    # 이 캐시는 codex 홈 하나를 쓰는 모든 클라이언트가 공유한다 — CLI 뿐 아니라
+    # ChatGPT 데스크톱 앱과 VS Code 확장도 자기 번들 버전으로 덮어쓴다. 그런데
+    # 카탈로그는 클라이언트 버전마다 다르다: 실측 2026-09-23, 같은 계정에서
+    # 0.155.1 은 gpt-6-sol·gpt-6-luna 를 내놓고 0.154.0·0.153.4 는 내놓지 않으며,
+    # 세 버전이 10분 사이 번갈아 이 파일을 썼다. 다른 클라이언트가 쓴 목록은
+    # okstra 가 실행할 CLI 의 카탈로그에 대한 근거가 아니므로 판정을 끈다 —
+    # 탐색 실패와 같은 처리이고, 정말 없는 모델이면 CLI 자신이 거절한다.
+    writer = payload.get("client_version")
+    running = codex_cli_version()
+    if running and isinstance(writer, str) and writer.strip() and writer.strip() != running:
+        return ()
     out: list[str] = []
     for entry in models:
         slug = entry.get("slug") if isinstance(entry, dict) else None

package/runtime/python/okstra_ctl/model_io/lines.py

@@ -10,6 +10,8 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any, Mapping
 
+from okstra_project.phase_pointer import promote
+
 from ..fixed_text import line as _line, scalar as _value
 from ..json_boundary import JsonBoundaryError
 
@@ -19,6 +21,17 @@ def _mapping(payload: Mapping[str, Any], key: str) -> Mapping[str, Any]:
     return value if isinstance(value, Mapping) else {}
 
 
+def next_phase_pointer(payload: Mapping[str, Any]) -> Mapping[str, Any]:
+    """`nextRecommendedPhase` 를 포인터로 읽는다. 구형 문자열도 승격한다.
+
+    `_mapping` 으로 읽으면 구형 문자열 포인터가 빈 매핑이 되어 `Next phase: -`
+    로 사라진다(ADR-0004 의 승격 예외가 이 읽기 경로에는 없었다). 값이 아예
+    없으면 빈 매핑 그대로 둔다 — 없는 포인터를 `pending` 으로 지어내지 않는다.
+    """
+    value = payload.get("nextRecommendedPhase")
+    return {} if value is None else promote(value)
+
+
 def _project_policy_lines(project: Mapping[str, Any]) -> str:
     packs = project.get("reviewRulePacks")
     pack_lines = (
@@ -84,7 +97,7 @@ def _worker_prompt_lines(run: Mapping[str, Any]) -> str:
 
 
 def _next_phase_lines(workflow: Mapping[str, Any]) -> str:
-    pointer = _mapping(workflow, "nextRecommendedPhase")
+    pointer = next_phase_pointer(workflow)
     return (
         _line("Next phase", pointer.get("phase"))
         + _line("Next phase status", pointer.get("status"))

package/runtime/python/okstra_ctl/model_io/renderers.py

@@ -29,6 +29,7 @@ from .lines import (
     _mapping,
     _next_phase_lines,
     _project_policy_lines,
+    next_phase_pointer,
     _provider_models,
     _status_overview_text,
     _worker_assignment_lines,
@@ -84,7 +85,7 @@ def _overview_rows(
         latest_run = _latest_timeline_run(project_root, manifest_path)
         _, group, _ = parse_task_key(task_key)
         workflow = _mapping(manifest, "workflow")
-        next_phase = _mapping(workflow, "nextRecommendedPhase")
+        next_phase = next_phase_pointer(workflow)
         # task 단위 현재 사실은 task-manifest 가 권위다(validate-run 이 run 종료
         # 시 거기에 쓴다). timeline 의 마지막 run 은 task-manifest 에 그 필드가
         # 없을 때의 폴백이고, 그 값도 run-manifest 로 덮어쓴 현재 사실이다.
@@ -372,7 +373,7 @@ def render_recap_input(project_root: Path, task_ref: str) -> str:
     for transition in transitions if isinstance(transitions, list) else []:
         if not isinstance(transition, Mapping):
             continue
-        pointer = _mapping(transition, "nextRecommendedPhase")
+        pointer = next_phase_pointer(transition)
         blocks.extend((
             "\n## Transition\n\n",
             _line("Run timestamp", transition.get("runTimestamp")),
@@ -420,7 +421,7 @@ def render_group_recap_input(project_root: Path, task_group: str) -> str:
     for task in tasks if isinstance(tasks, list) else []:
         if not isinstance(task, Mapping):
             continue
-        pointer = _mapping(task, "nextRecommendedPhase")
+        pointer = next_phase_pointer(task)
         memory = _mapping(task, "memory")
         blocks.extend((
             "\n## Task\n\n",

package/runtime/python/okstra_ctl/models.py

@@ -35,7 +35,7 @@ IMPLEMENTATION_ROLES = frozenset({"executor", "verifier"})
 # Legacy role-keyed compatibility defaults. Canonical assignments resolve a
 # provider first and then use ProviderSpec.default_models for that role.
 ROLE_DEFAULTS = {
-    "lead": "opus", "claude": "opus", "codex": "gpt-5.6-sol",
+    "lead": "opus", "claude": "opus", "codex": "gpt-6-sol",
     "antigravity": "gemini-3.1-pro", "report-writer": "sonnet",
 }
 

package/runtime/python/okstra_ctl/next_phase.py

@@ -235,8 +235,9 @@ def _from_option_selection(report_data: Mapping[str, Any]) -> dict[str, str]:
         # release-handoff 는 `routingRecommendation`.
         return make(status=STATUS_BLOCKED, rationale=_selection_guidance(selection))
     if routing == "pending-direction-selection":
-        # 이 상태는 **성공**이다 — 비교가 끝났고, 방향은 계획 단계의 위저드가
-        # 고르게 한다(`selected_direction_pick`). 그러니 다음 phase 는 지금 바로
+        # 이 상태는 **성공**이다 — 비교가 끝났고, 방향은 HTML 열람본의
+        # `DIRECTION SELECTION` Export 가 고르며 계획 위저드의
+        # `selected_direction_pick` 은 그 답이 딸린 리포트를 고른다. 그러니 다음 phase 는 지금 바로
         # 시작할 수 있는 `implementation-planning` 이고 status 는 `ready` 다.
         # 종전에는 phase 없는 `pending` 이었다: task 선택 화면이 `next: --
         # (pending)` 을 찍어 목적지를 지웠고, task-type 화면은 추천 없이 방금
@@ -276,11 +277,20 @@ def _direction_selection_reason(selection: Mapping[str, Any]) -> str:
     recommended = _text(selection.get("recommendedOptionId"))
     head = f"비교가 끝났습니다. 후보 {listed} 중 하나를 방향으로 고르세요"
     head += f" (권장 `{recommended}`)." if recommended else "."
+    # 위저드의 `selected_direction_pick` 은 후보가 아니라 **리포트**를 고른다
+    # (`wizard/steps_plan.py` `_build_selected_direction_pick`). 방향은 그 리포트
+    # 옆 `user-responses/` 의 `DIRECTION SELECTION` 사이드카가 정한다
+    # (`implementation_direction.py` `_comparison_selection`). 종전 문장은
+    # "위저드에 후보가 선택지로 나온다" 고 해서 사이드카 없이 계획을 열게 했다.
     return (
-        f"{head} 고르는 자리는 계획 단계의 위저드입니다 — `/okstra-run` 으로 "
-        "`implementation-planning` 을 시작하면 이 후보들이 선택지로 나옵니다. "
-        "이 phase 를 다시 돌리지 마세요: 비교는 이미 끝났고, 재실행은 같은 "
-        "비교를 처음부터 다시 합니다."
+        f"{head} 고르는 자리는 이 리포트의 HTML 열람본입니다 — 방향 선택 칸에서 "
+        "후보를 고르고 Export 한 파일을 "
+        "`runs/implementation-option-selection/user-responses/"
+        "user-response-implementation-option-selection-<이 리포트 번호>.md` 로 "
+        "저장하세요. 그다음 `/okstra-run` 으로 `implementation-planning` 을 "
+        "시작하고 위저드의 방향 보고서 단계에서 이 리포트를 고르면 저장한 방향이 "
+        "계획에 전달됩니다. 이 phase 를 다시 돌리지 마세요: 비교는 이미 끝났고, "
+        "재실행은 같은 비교를 처음부터 다시 합니다."
     )
 
 

package/runtime/python/okstra_ctl/operation_invocation.py

@@ -0,0 +1,86 @@
+"""okstra-run 밖에서 도는 Okstra 소유 LLM 작업의 준비.
+
+작업 계약(`agents/operations/<id>.json`)이 직무와 워커 수를 소유하고, 역할은 그
+직무의 `roleId` 에서 파생된다. 기술 문서는 작업 이름만 전달한다 — 역할·공급자·
+모델을 기술이 조립하면 같은 역할이 호출 표면마다 다른 규칙으로 배정된다
+(ADR-0017).
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from .contract_graph import (
+    ContractGraphError,
+    ContractGraphRoot,
+    ContractGraphValidator,
+    ContractSelection,
+)
+from .model_pool import ModelPool
+
+
+class OperationPreparationError(ValueError):
+    """작업을 디스패치 전에 준비할 수 없다. 메시지가 그 자리를 이름한다."""
+
+
+@dataclass(frozen=True)
+class OperationSlot:
+    """이 작업이 열 워커 한 칸. 모델은 칸마다 다르다."""
+
+    operation_id: str
+    duty_id: str
+    role_id: str
+    ordinal: int
+    model_ref: str
+    provider_id: str
+    display_name: str
+
+
+def resolve_operation_slots(
+    operation_id: str,
+    *,
+    contract_root: Path,
+    pool: ModelPool,
+) -> Sequence[OperationSlot]:
+    """작업 계약이 요구하는 칸과 각 칸의 모델.
+
+    모델은 런과 같은 기본값 사슬에서 고른다. 서로 다른 모델 참조를 요구한
+    수만큼 채우지 못하면 여기서 멈춘다 — 같은 모델을 반복하거나 워커 수를
+    줄이면 그 작업이 요구한 교차검증이 조용히 사라진다.
+    """
+    graph_root = ContractGraphRoot.from_base(contract_root)
+    try:
+        graph = ContractGraphValidator().validate(
+            graph_root, selected=ContractSelection(operation_id=operation_id)
+        )
+    except ContractGraphError as exc:
+        raise OperationPreparationError(str(exc)) from exc
+    operation = graph.operations.get(operation_id)
+    if operation is None:
+        known = ", ".join(sorted(graph.operations)) or "(none)"
+        raise OperationPreparationError(
+            f"unknown operation: {operation_id} (known: {known})"
+        )
+    duty_id = str(operation.payload["dutyId"])
+    count = int(operation.payload["count"])
+    role_id = graph.duties[duty_id].role_id
+
+    candidates = pool.default_candidates(role_id)
+    if len(candidates) < count:
+        raise OperationPreparationError(
+            f"operation {operation_id!r} requires {count} distinct models for role "
+            f"{role_id!r}, available {len(candidates)}"
+        )
+    slots = []
+    for ordinal, model in enumerate(candidates[:count], start=1):
+        slots.append(OperationSlot(
+            operation_id=operation_id,
+            duty_id=duty_id,
+            role_id=role_id,
+            ordinal=ordinal,
+            model_ref=str(model.model_ref),
+            provider_id=model.provider_id,
+            display_name=model.display_name,
+        ))
+    return tuple(slots)

package/runtime/python/okstra_ctl/option_comparison.py

@@ -0,0 +1,168 @@
+"""구현 방향 비교 자료 — 선택 리포트 기록 하나를 채팅용 사실 묶음으로 투영한다.
+
+사용자가 방향을 고르기 전에 비교 자료를 청하면 리드는 점수표·투표표·충족
+요약을 보여 준다. 그 숫자는 전부 `implementationOptionSelection` 기록에 있고
+`weightedScore` 는 발행 시점에 재계산 값과 대조된다
+(`implementation_options.py` `_validate_option_scores`). 리드가 JSON 을 손으로
+읽고 가중 점수를 다시 계산하던 자리를 이 명령이 대신한다. 서술(도입 문장,
+방향별 요지)은 리드가 `narrative` 와 각 방향의 근거 필드로 쓴다.
+
+읽기 전용이다. 어떤 파일도 쓰지 않는다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from okstra_ctl import next_phase
+from okstra_ctl.final_report_paths import final_report_data_path
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
+
+
+class OptionComparisonError(ValueError):
+    """비교 자료를 만들 수 없는 기록."""
+
+
+def _rows(value: object) -> list[Mapping[str, Any]]:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes)):
+        return []
+    return [row for row in value if isinstance(row, Mapping)]
+
+
+def _text(value: object) -> str:
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _count(value: object) -> int:
+    return len(value) if isinstance(value, Sequence) and not isinstance(value, str) else 0
+
+
+def _option(
+    option: Mapping[str, Any], recommended_id: str
+) -> dict[str, Any]:
+    coverage = option.get("coverageSummary")
+    coverage = coverage if isinstance(coverage, Mapping) else {}
+    scores = _rows(option.get("criterionScores"))
+    return {
+        "id": _text(option.get("id")),
+        "name": _text(option.get("name")),
+        "recommended": _text(option.get("id")) == recommended_id,
+        "goal": _text(option.get("goal")),
+        "coreMechanism": _text(option.get("coreMechanism")),
+        # 발행 검증이 재계산 값과 같음을 보장한 기록값이다. 다시 계산하지 않는다.
+        "weightedScore": option.get("weightedScore"),
+        "scores": {_text(row.get("criterion")): row.get("score") for row in scores},
+        "scoreRationales": {
+            _text(row.get("criterion")): _text(row.get("rationale")) for row in scores
+        },
+        "coverage": {
+            "verdict": _text(coverage.get("coverageVerdict")),
+            "coveredCount": coverage.get("coveredCount"),
+            "totalCount": coverage.get("totalCount"),
+            "requirementIds": [
+                _text(row.get("requirementId"))
+                for row in _rows(option.get("requirementCoverage"))
+                if _text(row.get("requirementId"))
+            ],
+        },
+        "safetyBlockers": _count(option.get("safetyBlockers")),
+        "unresolvedFeasibilityFacts": _count(option.get("unresolvedFeasibilityFacts")),
+        "votes": {
+            _text(vote.get("worker")): {
+                "verdict": _text(vote.get("verdict")),
+                "rationale": _text(vote.get("rationale")),
+                "counterevidence": _text(vote.get("counterevidence")),
+            }
+            for vote in _rows(option.get("feasibilityVotes"))
+            if _text(vote.get("worker"))
+        },
+    }
+
+
+def build_comparison(report_data: Mapping[str, Any]) -> dict[str, Any]:
+    """선택 리포트 기록 → 비교 자료 사실 묶음."""
+    selection = report_data.get("implementationOptionSelection")
+    if not isinstance(selection, Mapping):
+        raise OptionComparisonError(
+            "report has no implementationOptionSelection block; "
+            "pass an implementation-option-selection report record"
+        )
+    recommended_id = _text(selection.get("recommendedOptionId"))
+    options = [
+        _option(row, recommended_id) for row in _rows(selection.get("rankedOptions"))
+    ]
+    if not options:
+        raise OptionComparisonError("report ranks no direction; there is nothing to compare")
+    # 투표 열 순서는 처음 등장한 순서다 — 방향마다 같은 분석자 집합이 투표한다.
+    workers: list[str] = []
+    for option in options:
+        for worker in option["votes"]:
+            if worker not in workers:
+                workers.append(worker)
+    narrative = selection.get("userNarrative")
+    narrative = narrative if isinstance(narrative, Mapping) else {}
+    return {
+        "mode": _text(selection.get("mode")),
+        "routing": _text(selection.get("routing")),
+        "recommendedOptionId": recommended_id,
+        "criteria": [
+            {"criterion": _text(row.get("criterion")), "weight": row.get("weight")}
+            for row in _rows(selection.get("evaluationCriteria"))
+        ],
+        "workers": workers,
+        "options": options,
+        "narrative": {
+            key: _text(block.get("text"))
+            for key, block in narrative.items()
+            if isinstance(block, Mapping) and _text(block.get("text"))
+        },
+        # "남은 절차" 문단의 근거. 다음 phase 포인터와 같은 문장이다.
+        "nextStep": next_phase.project(report_data)["rationale"],
+    }
+
+
+def _load(report: Path) -> Mapping[str, Any]:
+    data_path = final_report_data_path(report)
+    try:
+        data = load_owned_object(data_path, artifact="implementation option data")
+    except (OSError, JsonBoundaryError) as exc:
+        raise OptionComparisonError(f"cannot read report record {data_path}: {exc}") from exc
+    return data
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="okstra option-comparison",
+        description=(
+            "Print the comparison facts of an implementation-option-selection "
+            "report as JSON: criteria and weights, per-direction scores and "
+            "recorded weighted score, requirement coverage, blocker counts, "
+            "per-worker feasibility votes, the report narrative, and the next step."
+        ),
+    )
+    parser.add_argument(
+        "--report",
+        required=True,
+        help="final-report-implementation-option-selection-<seq>.data.json (a .md sibling is accepted)",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        payload = build_comparison(_load(Path(args.report)))
+    except OptionComparisonError as exc:
+        print(f"option-comparison: {exc}", file=sys.stderr)
+        return 2
+    json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/runtime/python/okstra_ctl/path_hints.py

@@ -64,6 +64,7 @@ def compact_active_run_context(
         "run": {
             "stage": ctx.get("RUN_STAGE", ""),
             "fixRunCarry": ctx.get("FIX_RUN_CONTEXT", ""),
+            "hostSessionContract": ctx.get("HOST_SESSION_CONTRACT_PATH", ""),
         },
         "agentContract": dict(_mapping(payload.get("agentContract"))),
         "inputs": _compact_active_inputs(payload),
@@ -118,8 +119,13 @@ def hydrate_active_run_context(payload: Mapping[str, Any]) -> dict[str, Any]:
                     "IMPLEMENTATION_WORKER_PREAMBLE_PATH", ""
                 ),
                 "report-writer": ctx.get("REPORT_WRITER_PREAMBLE_PATH", ""),
+                "translator": ctx.get("TRANSLATOR_PREAMBLE_PATH", ""),
             },
             "workerErrorContractPath": ctx.get("WORKER_ERROR_CONTRACT_PATH", ""),
+            "hostSessionContractPath": (
+                str(_mapping(payload.get("run")).get("hostSessionContract", ""))
+                or ctx.get("HOST_SESSION_CONTRACT_PATH", "")
+            ),
         },
         "executorWorktree": dict(_mapping(payload.get("executorWorktree"))),
         "verificationTarget": dict(_mapping(payload.get("verificationTarget"))),
@@ -509,6 +515,9 @@ def _runtime_fields(paths: Mapping[str, Any]) -> dict[str, str]:
         "REPORT_WRITER_PREAMBLE_PATH": str(
             runtime_home / "templates" / "report-writer-prompt-preamble.md"
         ),
+        "TRANSLATOR_PREAMBLE_PATH": str(
+            runtime_home / "templates" / "translator-prompt-preamble.md"
+        ),
         "WORKER_ERROR_CONTRACT_PATH": str(
             runtime_home / "templates" / "worker-error-contract.md"
         ),