okstra 0.201.3 → 0.204.0

package/runtime/python/okstra_ctl/paths.py

@@ -647,6 +647,9 @@ def compute_run_paths(
         "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"
         ),

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -26,6 +26,7 @@ from .convergence_store import write_json_atomic
 from .incremental_carry import sync_prepared_dispatch_queue
 from .json_boundary import JsonBoundaryError, load_owned_object
 from .report_finalize import task_manifest_path
+from .qa_commands import split_verification_command
 from .plan_derivations import extract_tokens, find_derivations
 from .plan_items import (
     NextDispatch,
@@ -577,7 +578,11 @@ def _render_scalar_or_list(key: str, value: object, indent: str = "") -> list[st
     if isinstance(value, Mapping):
         raise PlanItemContractError(f"plan item {key} must be scalar")
     if key in {"command", "commandOrObservation"} and isinstance(value, str):
-        return _render_literal(_label(key), value, indent)
+        command, annotation = split_verification_command(value)
+        rows = _render_literal(_label(key), command, indent)
+        if annotation is not None:
+            rows.append(indent + line("Command annotation (not executable)", annotation))
+        return rows
     return [indent + line(_label(key), value)]
 
 

package/runtime/python/okstra_ctl/profile_show.py

@@ -19,6 +19,7 @@ import sys
 from pathlib import Path
 
 from .paths import find_asset_root
+from .role_requirements import RoleProfileError, load_role_profile
 from .run import PrepareError, _expand_profile_includes
 
 _PROFILES_REL = ("prompts", "profiles")
@@ -82,9 +83,49 @@ def sidecar_bodies(root: Path, profile_text: str) -> list[str]:
 def render(root: Path, task_type: str, *, resolved: bool) -> str:
     path = profile_path(root, task_type)
     if not resolved:
+        # 계약상 이 출력은 디스크의 파일 그대로다. 역할 구조는 이제 `.json` 에
+        # 있으므로 `--resolved` 가 렌더한다.
         return path.read_text(encoding="utf-8")
     expanded = _expand_profile_includes(path)
-    return expanded + "".join(sidecar_bodies(root, expanded))
+    body = expanded + "".join(sidecar_bodies(root, expanded))
+    return body + _role_requirements_section(path)
+
+
+def _role_requirements_section(profile_path: Path) -> str:
+    """Render the profile's role structure from its contract.
+
+    The structure moved out of the Markdown into the `.json` sibling, so a
+    reader of `okstra profile show` would otherwise no longer see which roles
+    the phase runs — which is most of what the command is read for.
+    """
+    try:
+        profile = load_role_profile(profile_path)
+    except RoleProfileError as exc:
+        return f"\n## Role requirements\n\nunavailable: {exc}\n"
+    if not profile.roles:
+        return "\n## Role requirements\n\nThis phase runs a single lead and no workers.\n"
+    lines = [
+        "",
+        "## Role requirements",
+        "",
+        "| Role | Duty | Count (min/recommended/max) | Activation |",
+        "|---|---|---|---|",
+    ]
+    for requirement in profile.roles:
+        if requirement.dynamic:
+            sources = ", ".join(f"`{role}`" for role in requirement.source_role_ids)
+            counts = f"one per activated {sources} slot"
+            activation = requirement.activation
+        else:
+            counts = (
+                f"{requirement.min_count} / {requirement.recommended_count} / "
+                f"{requirement.max_count}"
+            )
+            activation = "static"
+        lines.append(
+            f"| `{requirement.role}` | `{requirement.duty}` | {counts} | {activation} |"
+        )
+    return "\n".join(lines) + "\n"
 
 
 def _write_stdout(text: str) -> None:

package/runtime/python/okstra_ctl/qa_commands.py

@@ -98,6 +98,21 @@ def find_unfrozen_installs(cmd: str) -> list[str]:
     return found
 
 
+def split_verification_command(command: str) -> tuple[str, str | None]:
+    """기존 계획의 파일 인용 설명만 분리하며 일반 셸 구문은 보존한다."""
+    match = re.search(r";\s*(existing helper:\s*[^;&|<>$`\n]+:\d+(?:-\d+)?)\s*$", command)
+    if match is None:
+        return command, None
+    executable = command[:match.start()].rstrip()
+    try:
+        words = shlex.split(executable)
+    except ValueError:
+        return command, None
+    if not words:
+        return command, None
+    return executable, match.group(1).strip()
+
+
 def verification_command_defects(command: str) -> list[str]:
     """선언된 작업 폴더를 셸에서 다른 체크아웃으로 바꾸는 명령을 거부한다."""
     try:

package/runtime/python/okstra_ctl/registry/host_discovery.py

@@ -18,6 +18,8 @@ class HostManifest:
     native_provider_id: str
     required_executables: tuple[str, ...]
     relay_contract: Path
+    # 선언하지 않은 호스트는 None. 이 호스트 세션 안에서 도는 워커가 읽는 계약이다.
+    worker_session_contract: Path | None = None
 
 
 def discover_host_manifests(roots: Iterable[Path]) -> tuple[HostManifest, ...]:
@@ -54,7 +56,15 @@ def _read_manifest(manifest_path: Path) -> HostManifest:
     native_provider_id = _optional_id(raw, "nativeProviderId", manifest_path)
     required_executables = _string_tuple(raw, "requiredExecutables", manifest_path)
     relay_ref = _required_string(raw, "relayContract", manifest_path)
-    relay_contract = _resolve_relay_contract(manifest_path, relay_ref)
+    relay_contract = _resolve_adapter_file(manifest_path, relay_ref, "relay contract")
+    session_ref = raw.get("workerSessionContract")
+    if session_ref is not None and (not isinstance(session_ref, str) or not session_ref):
+        raise HostAdapterContractError(f"invalid host manifest: {manifest_path}")
+    worker_session_contract = (
+        _resolve_adapter_file(manifest_path, session_ref, "worker session contract")
+        if session_ref is not None
+        else None
+    )
     return HostManifest(
         path=manifest_path,
         host_id=host_id,
@@ -62,6 +72,7 @@ def _read_manifest(manifest_path: Path) -> HostManifest:
         native_provider_id=native_provider_id,
         required_executables=required_executables,
         relay_contract=relay_contract,
+        worker_session_contract=worker_session_contract,
     )
 
 
@@ -111,15 +122,12 @@ def _string_tuple(
     return tuple(value)
 
 
-def _resolve_relay_contract(manifest_path: Path, relay_ref: str) -> Path:
+def _resolve_adapter_file(manifest_path: Path, ref: str, label: str) -> Path:
+    """어댑터 디렉터리 안의 파일 하나를 해석한다. 밖을 가리키면 거절한다."""
     adapter_root = manifest_path.parent.resolve()
-    if Path(relay_ref).is_absolute():
-        raise HostAdapterContractError(
-            f"relay contract escapes adapter root: {relay_ref!r}"
-        )
-    relay_contract = (adapter_root / relay_ref).resolve()
-    if adapter_root not in relay_contract.parents or not relay_contract.is_file():
-        raise HostAdapterContractError(
-            f"relay contract escapes adapter root: {relay_ref!r}"
-        )
-    return relay_contract
+    if Path(ref).is_absolute():
+        raise HostAdapterContractError(f"{label} escapes adapter root: {ref!r}")
+    resolved = (adapter_root / ref).resolve()
+    if adapter_root not in resolved.parents or not resolved.is_file():
+        raise HostAdapterContractError(f"{label} escapes adapter root: {ref!r}")
+    return resolved

package/runtime/python/okstra_ctl/registry/host_registry.py

@@ -248,6 +248,15 @@ def _validated_descriptor(adapter: object, manifest: HostManifest) -> HostDescri
         raise HostAdapterContractError(
             f"relay contract mismatch for {manifest.host_id!r}"
         )
+    declared = (
+        Path(descriptor.worker_session_contract).resolve()
+        if descriptor.worker_session_contract
+        else None
+    )
+    if declared != manifest.worker_session_contract:
+        raise HostAdapterContractError(
+            f"worker session contract mismatch for {manifest.host_id!r}"
+        )
     return descriptor
 
 
@@ -286,6 +295,8 @@ def _copy_descriptor(raw: object, host_id: str) -> HostDescriptor:
             session_accounting=raw.session_accounting,
             has_claude_session=raw.has_claude_session,
             relay_contract=raw.relay_contract,
+            worker_session_contract=getattr(raw, "worker_session_contract", ""),
+            initial_prompt_delivery_mode=raw.initial_prompt_delivery_mode,
         )
     except (AttributeError, TypeError) as exc:
         raise HostAdapterContractError(

package/runtime/python/okstra_ctl/render.py

@@ -455,6 +455,10 @@ def _worker_assignments(ctx: dict) -> list[dict]:
             # 다른데 반환값만 봐서는 구별되지 않는다.
             print(f"render: WORKER_ASSIGNMENTS_JSON is not valid JSON, "
                   f"falling back to the worker catalog ({exc})", file=sys.stderr)
+    # 여기 도달하면 이 run 에는 해소된 배정이 없다 — 준비 경로는 언제나
+    # `WORKER_ASSIGNMENTS_JSON` 을 채운다(`run.py` `_model_tokens`). 남은 정보가
+    # 워커 id 뿐이라 역할을 복원할 수 없고, 아래 값은 분석 run 로스터의 모양을
+    # 가정한 것이다. 이 로스터로 implementation 프롬프트를 고를 수는 없다.
     catalog = _worker_catalog(ctx, include_assignments=False)
     return [
         {
@@ -690,9 +694,13 @@ def _active_runtime_resources(ctx: dict) -> dict:
             or str(runtime_home / "templates" / "implementation-worker-preamble.md"),
             "report-writer": ctx.get("REPORT_WRITER_PREAMBLE_PATH")
             or str(runtime_home / "templates" / "report-writer-prompt-preamble.md"),
+            "translator": ctx.get("TRANSLATOR_PREAMBLE_PATH")
+            or str(runtime_home / "templates" / "translator-prompt-preamble.md"),
         },
         "workerErrorContractPath": ctx.get("WORKER_ERROR_CONTRACT_PATH")
         or str(runtime_home / "templates" / "worker-error-contract.md"),
+        "hostSessionContractPath": ctx.get("HOST_SESSION_CONTRACT_PATH")
+        or _host_session_contract_path(ctx),
     }
 
 
@@ -2019,6 +2027,9 @@ _V2_INVOCATION_IDENTITY_KEYS = {
 }
 _AGENT_CONTRACT_KEYS = {
     "schemaVersion",
+    # 이 run 이 동결한 계약의 형식. 없는 run 은 Markdown 직무를 동결했고, 그
+    # 형식의 리더는 제거됐다.
+    "contractFormatVersion",
     "dutyRootPath",
     "catalogDigest",
     "invocationReservationRootPath",
@@ -2610,9 +2621,15 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
     report_writer_preamble = ctx.get("REPORT_WRITER_PREAMBLE_PATH") or str(
         runtime_templates / "report-writer-prompt-preamble.md"
     )
+    translator_preamble = ctx.get("TRANSLATOR_PREAMBLE_PATH") or str(
+        runtime_templates / "translator-prompt-preamble.md"
+    )
     worker_error_contract = ctx.get("WORKER_ERROR_CONTRACT_PATH") or str(
         runtime_templates / "worker-error-contract.md"
     )
+    host_session_contract = ctx.get(
+        "HOST_SESSION_CONTRACT_PATH"
+    ) or _host_session_contract_path(ctx)
     okstra_runtime_resources_block = (
         "## Okstra Runtime Resources\n"
         "\n"
@@ -2629,8 +2646,14 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         f"- Analysis worker preamble: `{analysis_preamble}`\n"
         f"- Implementation worker preamble: `{implementation_preamble}`\n"
         f"- Report writer preamble: `{report_writer_preamble}`\n"
+        f"- Translator preamble: `{translator_preamble}`\n"
+
         f"- Shared worker error contract: `{worker_error_contract}`"
     )
+    if host_session_contract:
+        okstra_runtime_resources_block += (
+            f"\n- Host worker session contract: `{host_session_contract}`"
+        )
 
     def fmt_assignment(role: str, model: str, execution: str) -> str:
         if execution and execution != model:
@@ -2814,6 +2837,23 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
     ctx["EXECUTION_STATUS_TABLE_ROWS"] = "\n".join(execution_status_table_lines)
 
 
+def _host_session_contract_path(ctx: Mapping[str, object]) -> str:
+    """이 run 의 호스트가 선언한 워커 세션 계약의 절대 경로. 없으면 빈 문자열.
+
+    호스트를 못 찾는 것은 여기서 실패할 일이 아니다 — 계약이 없는 호스트와
+    같게 다루고, 헤더를 빼면 그 워커는 세션 규칙 없이 돈다. 호스트 해석 실패
+    자체는 이 함수를 부르기 전에 이미 run 준비를 막는다.
+    """
+    host_id = str(ctx.get("HOST_RUNTIME", "") or _lead_runtime(ctx) or "").strip()
+    if not host_id:
+        return ""
+    try:
+        descriptor = default_host_registry().resolve(host_id).descriptor
+    except Exception:
+        return ""
+    return descriptor.worker_session_contract or ""
+
+
 def apply_lead_prompt_defaults(ctx: dict) -> None:
     """Apply default values for optional lead-prompt ctx fields.
 
@@ -2853,10 +2893,20 @@ def apply_lead_prompt_defaults(ctx: dict) -> None:
         "REPORT_WRITER_PREAMBLE_PATH",
         str(runtime_home / "templates" / "report-writer-prompt-preamble.md"),
     )
+    ctx.setdefault(
+        "TRANSLATOR_PREAMBLE_PATH",
+        str(runtime_home / "templates" / "translator-prompt-preamble.md"),
+    )
     ctx.setdefault(
         "WORKER_ERROR_CONTRACT_PATH",
         str(runtime_home / "templates" / "worker-error-contract.md"),
     )
+    # 호스트가 선언한 워커 세션 계약. 선언하지 않은 호스트는 빈 문자열이고,
+    # 그러면 헤더가 방출되지 않는다.
+    ctx.setdefault(
+        "HOST_SESSION_CONTRACT_PATH",
+        _host_session_contract_path(ctx),
+    )
     # Lead resource paths the launch template references directly. paths.py
     # seeds the production values; setdefault backfills callers that render the
     # template without the full path ctx.

package/runtime/python/okstra_ctl/report_contract.py

@@ -123,7 +123,7 @@ TASK_TYPE_REQUIRED_HUMAN_FIELDS = {
     "release-handoff": (
         "releaseHandoff.userSelections",
         "releaseHandoff.featureBranchState",
-        "releaseHandoff.pullRequestOutcome",
+        "releaseHandoff.pullRequestOutcomes",
         "releaseHandoff.mergeConflictProbe",
     ),
 }

package/runtime/python/okstra_ctl/report_finalize.py

@@ -737,6 +737,8 @@ def _closeout_report_paths(ctx: FinalizeContext) -> dict[str, Any]:
     답장을 마크다운으로 그리므로 괄호 안에 경로가 들어간 형태만 클릭되고,
     백틱으로 감싼 경로는 글자로만 남아 사용자가 직접 옮겨 적어야 한다. 리드가
     그 형태를 매번 다시 만들면 어긋날 자리가 생기므로 완성된 문자열을 준다.
+    링크 목적지는 절대 경로다 — 프로젝트 기준 상대 경로는 호스트 cwd 가 다르거나
+    외부 프로그램으로 열 때 해석되지 않는다. 공백이 든 경로는 `<...>` 로 감싼다.
     """
     def rel(path: Path) -> str:
         try:
@@ -744,17 +746,22 @@ def _closeout_report_paths(ctx: FinalizeContext) -> dict[str, Any]:
         except ValueError:
             return str(path)
 
-    paths = {
-        "humanReport": rel(html_view_path(ctx.data_path)),
-        "reportRecord": rel(ctx.data_path),
-        "teamState": rel(ctx.team_state_path),
+    def link_target(path: Path) -> str:
+        target = path.resolve().as_posix()
+        return f"<{target}>" if " " in target else target
+
+    sources = {
+        "humanReport": html_view_path(ctx.data_path),
+        "reportRecord": ctx.data_path,
+        "teamState": ctx.team_state_path,
     }
+    paths = {key: rel(path) for key, path in sources.items()}
     return {
         **paths,
         "renderFullCopy": f"okstra render-final-report {paths['reportRecord']}",
         "markdown": {
-            key: f"[{Path(value).name}]({value})"
-            for key, value in paths.items()
+            key: f"[{path.name}]({link_target(path)})"
+            for key, path in sources.items()
         },
     }
 

package/runtime/python/okstra_ctl/report_html/view_models/final_verification.py

@@ -3,8 +3,7 @@ from __future__ import annotations
 
 from ...release_gate import release_handoff_allowed
 from ..common import evidence_index
-from ..models import HumanReportView, VisualNode
-from ..visualizations import coverage_figure
+from ..models import HumanReportView
 
 # Record fields this template anchors as `id-<row id>` (see
 # `HumanReportView.anchored_fields`); ids elsewhere land in the ledger.
@@ -17,25 +16,8 @@ ANCHORED_FIELDS = (
 )
 
 
-def _coverage_nodes(final: dict) -> tuple[VisualNode, ...]:
-    return tuple(
-        VisualNode(
-            row["id"],
-            row["requirement"],
-            "requirement",
-            row["status"],
-            row["artifact"],
-            note=row["status"],
-        )
-        for row in final["validationEvidence"]
-    )
-
-
 def build_final_verification_view(data: dict) -> HumanReportView:
     final = data["finalVerification"]
-    figure = coverage_figure(
-        rows=_coverage_nodes(final), title="Requirement verification coverage"
-    )
     verdict_token = data["finalVerdict"]["verdictToken"]
     context = {
         "humanSummary": data["humanSummary"],
@@ -44,7 +26,6 @@ def build_final_verification_view(data: dict) -> HumanReportView:
         "finalVerdict": data["finalVerdict"],
         "final": final,
         "narrative": final["userNarrative"],
-        "coverageFigure": figure,
         "releaseAllowed": release_handoff_allowed(data),
         "evidenceIndex": evidence_index(data, ANCHORED_FIELDS),
     }
@@ -52,6 +33,6 @@ def build_final_verification_view(data: dict) -> HumanReportView:
         "final-verification",
         "html/tasks/final-verification.template.html",
         context,
-        (figure,),
+        (),
         anchored_fields=ANCHORED_FIELDS,
     )

package/runtime/python/okstra_ctl/report_html/view_models/release_handoff.py

@@ -18,16 +18,31 @@ def _safe_http_url(value: str) -> str:
     return value if parsed.scheme in {"http", "https"} and parsed.netloc else ""
 
 
+def _pr_summary(outcomes: list) -> str:
+    """PR 은 stage 당 하나라 결과도 여러 개다. 타임라인 한 칸에는 종류별 건수로
+    접어 넣는다 — 대표 하나를 고르면 나머지 stage 의 결과가 사라진다."""
+    if not outcomes:
+        return "no-action"
+    counts: dict[str, int] = {}
+    for row in outcomes:
+        kind = row.get("kind", "")
+        counts[kind] = counts.get(kind, 0) + 1
+    return ", ".join(f"{kind} {n}" for kind, n in sorted(counts.items()))
+
+
 def _timeline_nodes(handoff: dict) -> tuple[VisualNode, ...]:
     selection = handoff["userSelections"]["h1"]
     branch = handoff["featureBranchState"]["branchName"]
     conflict = handoff["mergeConflictProbe"]["kind"]
-    pr = handoff["pullRequestOutcome"]["kind"]
+    outcomes = handoff["pullRequestOutcomes"]
+    kinds = {row.get("kind", "") for row in outcomes}
+    status = kinds.pop() if len(kinds) == 1 else "mixed"
     return (
         VisualNode("selection", selection, "handoff", "completed", "User-selected handoff"),
         VisualNode("branch", branch, "handoff", "completed", "Feature branch state"),
         VisualNode("conflict", conflict, "handoff", conflict, "Merge conflict probe"),
-        VisualNode("pull-request", pr, "handoff", pr, "Pull request outcome"),
+        VisualNode("pull-request", _pr_summary(outcomes), "handoff", status,
+                   "Pull request outcome, one per stage"),
     )
 
 
@@ -41,7 +56,10 @@ def build_release_handoff_view(data: dict) -> HumanReportView:
         "handoff": handoff,
         "narrative": handoff["userNarrative"],
         "handoffFigure": figure,
-        "prUrl": _safe_http_url(handoff["pullRequestOutcome"].get("url", "")),
+        "prOutcomes": [
+            {**row, "url": _safe_http_url(row.get("url", ""))}
+            for row in handoff["pullRequestOutcomes"]
+        ],
         "evidenceIndex": evidence_index(data, ANCHORED_FIELDS),
     }
     return HumanReportView(

package/runtime/python/okstra_ctl/report_html/visualizations.py

@@ -356,11 +356,6 @@ def matrix_figure(*, items: Iterable[VisualNode], title: str, x_label: str, y_la
     return replace(dependency_figure(nodes=nodes, edges=(), title=title), kind="matrix", figure_id="matrix", summary=summary)
 
 
-def coverage_figure(*, rows: Iterable[VisualNode], title: str) -> FigureModel:
-    nodes = tuple(rows)
-    return replace(dependency_figure(nodes=nodes, edges=(), title=title), kind="coverage", figure_id="coverage")
-
-
 def timeline_figure(*, events: Iterable[VisualNode], title: str) -> FigureModel:
     nodes = tuple(events)
     edges = tuple(VisualEdge(nodes[i].id, nodes[i + 1].id, "next", "sequence") for i in range(len(nodes) - 1))