okstra 0.149.0 → 0.151.0

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -299,17 +299,39 @@ def _top_level_bullet_heading(line: str) -> str:
     return label
 
 
+# Report headings carry a section number and the renderer's scroll anchor
+# (`## 1. Clarification Items <a id="1-clarification-items"></a>`), while the
+# section names above are written bare. Keying a heading by both spellings is
+# what lets a lookup for `Clarification Items` find it — without the alias the
+# Carry-In Extract rendered `No matching source sections were available` for
+# every carry-in ever staged. No section name starts with a digit, so the
+# stripped alias cannot collide with a name meant to be matched literally.
+_HEADING_NUMBER_RE = re.compile(r"^\d+(?:\.\d+)*\.?\s+")
+_HEADING_ANCHOR_RE = re.compile(r'\s*<a id="[^"]*"></a>\s*$')
+
+
+def _heading_alias(heading: str) -> str:
+    return _HEADING_NUMBER_RE.sub("", _HEADING_ANCHOR_RE.sub("", heading)).strip()
+
+
 def _section_map(text: str) -> dict[str, str]:
     result: dict[str, list[str]] = {}
+    aliases: dict[str, str] = {}
     current = ""
     for line in _strip_frontmatter(text).splitlines():
         if line.startswith("## "):
             current = line[3:].strip()
             result.setdefault(current, [])
+            alias = _heading_alias(current)
+            if alias and alias != current:
+                aliases.setdefault(alias, current)
             continue
         if current:
             result[current].append(line)
-    return {key: "\n".join(lines).strip() for key, lines in result.items()}
+    sections = {key: "\n".join(lines).strip() for key, lines in result.items()}
+    for alias, heading in aliases.items():
+        sections.setdefault(alias, sections[heading])
+    return sections
 
 
 def _strip_frontmatter(text: str) -> str:

package/runtime/python/okstra_ctl/clarification_items.py

@@ -1,32 +1,42 @@
-"""Parse the ``## 1. Clarification Items`` table from a final-report markdown.
-
-The unified §1 table (introduced when §4.5.9 / §5.1 / §5.2 collapsed into a
-single section) is the canonical home for every clarification an
-implementation-planning run owes the user — decisions, file attachments,
-single data points. Each row carries a ``Blocks`` column whose value picks
-one of ``{approval, next-phase, none}``. Rows with ``Blocks=approval`` are
-the approval gate: they MUST resolve before the user flips the frontmatter
+"""Read a final-report's clarification rows, whichever schema wrote them.
+
+A clarification is what a run owes the user — a decision, a file attachment,
+a single data point. Each row carries a ``Blocks`` value out of
+``{approval, next-phase, none}``. Rows with ``Blocks=approval`` are the
+approval gate: they MUST resolve before the user flips the frontmatter
 ``approved`` field to ``true`` and starts the next ``implementation`` run.
 
-This module exposes one read function for that gate
-(``scan_approval_gate``) so both ``_validate_approved_plan``
-(pre-implementation run-prep) and the wizard share the same parsing logic.
+The two schemas store those rows in different places, and that is why the
+read functions take a report **path**, not its text:
+
+* schema-v1 — the ``## 1. Clarification Items`` markdown table (introduced
+  when §4.5.9 / §5.1 / §5.2 collapsed into a single section).
+* schema-v2 — ``clarificationItems[]`` in the ``.data.json`` sibling. Its AI
+  handoff markdown serialises them as a JSON block under
+  ``## Clarification and User Decisions``, so the §1 table walk finds nothing
+  there by construction.
 
-Gate semantics are fail-closed: when the §1 schema cannot be read with
-confidence (heading missing/drifted, table header unrecognized, or any
-body row whose metadata cell fails to parse), the scan reports an
-``unreadable_reason`` and callers must refuse approval instead of
+Every gate goes through ``scan_approval_gate`` / ``scan_open_user_input`` so
+run-prep (``_validate_approved_plan``), the wizard, and the user-response CLI
+cannot disagree about what is still open.
+
+Gate semantics are fail-closed: when the rows cannot be read with confidence
+(§1 heading missing/drifted, table header unrecognized, a body row whose
+metadata cell fails to parse, or a v2 row missing id/blocks/status), the scan
+reports an ``unreadable_reason`` and callers must refuse approval instead of
 soft-passing. ``parse_clarification_items`` keeps the lenient
-None-on-absence contract for the HTML-view renderers, which only need
-best-effort row extraction.
+None-on-absence contract for the schema-v1 HTML-view renderers, which only
+need best-effort row extraction.
 """
 from __future__ import annotations
 
+import json
 import re
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Optional
 
+from okstra_ctl.final_report_paths import final_report_data_path
 from okstra_ctl.md_table import is_separator_row, split_pipe_row, to_cell_text
 
 
@@ -208,12 +218,100 @@ def parse_clarification_items(report_text: str) -> Optional[list[ClarificationIt
     return _walk_section_1_table(section).items
 
 
-def parse_clarification_rows(report_text: str) -> list[dict]:
-    """§1 행마다 메타(ClarificationItem) + 원문 Statement / Expected form 셀.
+# schema-v2 는 clarification 을 §1 마크다운 테이블이 아니라 data.json 의
+# `clarificationItems[]` 로 들고, AI 핸드오프 Markdown 은 그것을
+# `## Clarification and User Decisions` 아래 JSON 블록으로 직렬화한다. §1 테이블
+# 워크는 거기서 아무것도 못 찾으므로, 게이트가 v1 파서만 쓰면 열린 항목이 있는
+# v2 리포트를 "읽을 수 없음"으로 떨어뜨린다. data.json 은 두 렌더러가 이미 읽는
+# SSOT 다 — clarification 상태도 여기서 읽는다.
+SCHEMA_VERSION_V2 = "2.0"
+
 
-    ``parse_clarification_items`` 와 같은 lenient 계약: §1 부재 또는 헤더
-    미인식이면 ``[]``. §1 테이블 셀 추출의 단일 참조점 — 다른 모듈이 §1
-    레이아웃을 다시 훑지 않도록 이 함수로 통일한다.
+def _read_report_text(report_path: Path) -> str:
+    return report_path.read_text(encoding="utf-8", errors="replace")
+
+
+def _v2_report_data(report_path: Path) -> Optional[dict]:
+    """``report_path`` 의 schema-v2 data 사이드카, 아니면 ``None``.
+
+    파일이 없거나 JSON 이 깨졌거나 v2 가 아니면 ``None`` — 호출자는 v1
+    마크다운 경로로 폴백하고, 진짜 v2 인데 사이드카가 깨진 경우는 그 폴백이
+    "§1 없음" fail-closed 로 잡는다.
+    """
+    data_path = final_report_data_path(report_path)
+    if not data_path.is_file():
+        return None
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(data, dict) or data.get("schemaVersion") != SCHEMA_VERSION_V2:
+        return None
+    return data
+
+
+def _v2_row(entry: dict) -> Optional[dict]:
+    """``clarificationItems[]`` 한 행을 §1 행과 같은 shape 으로. 필수 필드가
+    빠졌으면 ``None`` — 호출자가 fail-closed 로 셀 수 있게 한다."""
+    row_id = entry.get("id")
+    raw_blocks = entry.get("blocks")
+    raw_status = entry.get("status")
+    if not (isinstance(row_id, str) and row_id):
+        return None
+    if not (isinstance(raw_blocks, str) and raw_blocks):
+        return None
+    if not (isinstance(raw_status, str) and raw_status):
+        return None
+    kind = entry.get("kind")
+    item = ClarificationItem(
+        row_id=row_id,
+        kind=kind.lower() if isinstance(kind, str) else "",
+        blocks=raw_blocks.lower(),
+        status=raw_status.lower(),
+        raw_blocks=raw_blocks,
+        raw_status=raw_status,
+    )
+    return {
+        "item": item,
+        "statement": str(entry.get("statement") or ""),
+        "expected_form": str(entry.get("expectedForm") or ""),
+    }
+
+
+def _v2_clarification_rows(report_path: Path) -> Optional[list[dict]]:
+    """schema-v2 clarification 행들, 이 리포트가 v2 가 아니면 ``None``.
+    필수 필드가 빠진 행은 건너뛰는 lenient 계약(§1 파서와 동일)."""
+    data = _v2_report_data(report_path)
+    if data is None:
+        return None
+    entries = data.get("clarificationItems")
+    if not isinstance(entries, list):
+        return []
+    rows = [_v2_row(e) for e in entries if isinstance(e, dict)]
+    return [row for row in rows if row is not None]
+
+
+def read_clarification_rows(report_path: Path) -> list[dict]:
+    """리포트 한 건의 clarification 행 — schema-v2 는 data.json 사이드카에서,
+    schema-v1 은 §1 테이블에서. 스키마 버전을 아는 유일한 읽기 지점이다.
+
+    ``parse_section_1_rows`` 와 같은 lenient 계약: 어느 쪽에서도 행을 못 찾으면
+    ``[]``.
+    """
+    v2_rows = _v2_clarification_rows(report_path)
+    if v2_rows is not None:
+        return v2_rows
+    return parse_section_1_rows(_read_report_text(report_path))
+
+
+def parse_section_1_rows(report_text: str) -> list[dict]:
+    """§1 테이블 한 행마다 메타(ClarificationItem) + 원문 Statement / Expected
+    form 셀.
+
+    입력은 §1 을 담은 마크다운 본문이다 — 리포트 전문일 수도 있고, 다음 run 에
+    첨부되는 carry-in 본문(``clarification_response_with_sidecars``)일 수도
+    있다. §1 셀 추출의 단일 참조점 — 다른 모듈이 §1 레이아웃을 다시 훑지 않도록
+    이 함수로 통일한다.
     """
     section = _section_1_slice(report_text)
     if section is None:
@@ -269,33 +367,46 @@ USER_INPUT_BLOCKS = frozenset({"approval", "next-phase"})
 
 @dataclass(frozen=True)
 class ClarificationScan:
-    """Fail-closed read of §1 for rows blocking on one `Blocks` value set.
+    """Fail-closed read of the clarification rows blocking on one `Blocks`
+    value set.
 
-    ``unreadable_reason`` is ``None`` only when the scan is confident: §1
-    parsed cleanly (or is the legitimate table-less placeholder) and
-    ``blockers`` is therefore authoritative. A non-None reason means the
-    caller must refuse to act — never soft-pass.
+    ``unreadable_reason`` is ``None`` only when the scan is confident: the
+    rows parsed cleanly (or the report is the legitimate table-less
+    placeholder) and ``blockers`` is therefore authoritative. A non-None
+    reason means the caller must refuse to act — never soft-pass.
     """
     blockers: list[ClarificationItem]
     unreadable_reason: Optional[str]
 
 
-def scan_approval_gate(report_text: str) -> ClarificationScan:
-    """Scan §1 for unresolved ``Blocks=approval`` rows (``Status`` in
+def scan_approval_gate(report_path: Path) -> ClarificationScan:
+    """Scan for unresolved ``Blocks=approval`` rows (``Status`` in
     ``{open, answered}``), refusing to guess whenever the schema drifted."""
-    return scan_clarification_blockers(report_text, APPROVAL_BLOCKS)
+    return scan_clarification_blockers(report_path, APPROVAL_BLOCKS)
 
 
-def scan_open_user_input(report_text: str) -> ClarificationScan:
-    """Scan §1 for every unresolved row that still owes the user an answer
+def scan_open_user_input(report_path: Path) -> ClarificationScan:
+    """Scan for every unresolved row that still owes the user an answer
     (``Blocks`` in ``{approval, next-phase}``)."""
-    return scan_clarification_blockers(report_text, USER_INPUT_BLOCKS)
+    return scan_clarification_blockers(report_path, USER_INPUT_BLOCKS)
 
 
 def scan_clarification_blockers(
+    report_path: Path, blocking_values: frozenset[str]
+) -> ClarificationScan:
+    """Shared fail-closed clarification walk for both gates above — schema-v2
+    reads its rows from the data sibling, schema-v1 from the §1 table."""
+    v2_scan = _scan_v2_blockers(report_path, blocking_values)
+    if v2_scan is not None:
+        return v2_scan
+    return scan_section_1_blockers(_read_report_text(report_path), blocking_values)
+
+
+def scan_section_1_blockers(
     report_text: str, blocking_values: frozenset[str]
 ) -> ClarificationScan:
-    """Shared fail-closed §1 walk for both gates above."""
+    """Fail-closed §1 walk over any markdown carrying the table — a schema-v1
+    report, or the carry-in body a reconciliation just produced."""
     section = _section_1_slice(report_text)
     if section is None:
         if _LOOSE_SECTION_1_RE.search(report_text):
@@ -333,6 +444,37 @@ def scan_clarification_blockers(
     return ClarificationScan(blockers, None)
 
 
+def _scan_v2_blockers(
+    report_path: Path, blocking_values: frozenset[str]
+) -> Optional[ClarificationScan]:
+    """schema-v2 data.json 기준 스캔, 이 리포트가 v2 가 아니면 ``None``.
+    필수 필드가 빠진 행은 §1 의 unparsed row 와 같이 fail-closed 로 다룬다."""
+    data = _v2_report_data(report_path)
+    if data is None:
+        return None
+    entries = data.get("clarificationItems")
+    if entries is None:
+        return ClarificationScan([], None)
+    if not isinstance(entries, list):
+        return ClarificationScan([], (
+            "schema-v2 data.json `clarificationItems` is not an array — the "
+            "gate cannot read the clarification rows"
+        ))
+    rows = [_v2_row(e) if isinstance(e, dict) else None for e in entries]
+    unparsed = sum(1 for row in rows if row is None)
+    if unparsed:
+        return ClarificationScan([], (
+            f"schema-v2 data.json has {unparsed} `clarificationItems` row(s) "
+            "missing id/blocks/status"
+        ))
+    blockers = [
+        row["item"] for row in rows
+        if row["item"].blocks in blocking_values
+        and row["item"].status in UNRESOLVED_STATUSES
+    ]
+    return ClarificationScan(blockers, None)
+
+
 # 느슨한 §1 헤딩 탐지: 엄격한 SECTION_HEADING_PATTERN 이 실패해도 이게 매칭되면
 # "§1 헤딩은 있는데 형태가 어긋나 파싱에 실패" 한 상태다. trailing 부분을 보지
 # 않으므로 앵커 변형·수동 편집·미래 렌더 변경 어디서든 헤딩의 존재만 잡는다.
@@ -494,10 +636,11 @@ def clarification_response_with_sidecars(source: Path) -> str:
     리포트는 run 이 누적될수록 커지므로 이 중복은 스스로 악화된다(실측: 283K
     리포트가 892K 의 중복 읽기를 만들어 report-writer 를 timeout 시켰다).
 
-    그래서 소스가 final-report 일 때는 답변이 실린 §1 만 잘라내고 원문은 경로로
-    가리킨다 — `attached_user_responses_section` 이 implementation carry-in 에서
-    이미 쓰는 "원문은 경로로, 답변만 첨부" 규칙과 같다. §1 이 없는 소스(사용자가
-    직접 쓴 답변 파일)는 그대로 복사한다.
+    그래서 소스가 final-report 일 때는 답변이 실린 clarification 행만 잘라내고
+    원문은 경로로 가리킨다 — `attached_user_responses_section` 이 implementation
+    carry-in 에서 이미 쓰는 "원문은 경로로, 답변만 첨부" 규칙과 같다. 행을 어디서
+    읽는지는 스키마가 정한다(v1 은 §1 표, v2 는 data.json). clarification 을
+    아예 담지 않은 소스(사용자가 직접 쓴 답변 파일)만 원문 그대로 복사한다.
     """
     text = source.read_text(encoding="utf-8")
     section = attached_user_responses_section(source)
@@ -508,6 +651,14 @@ def clarification_response_with_sidecars(source: Path) -> str:
     return body.rstrip("\n") + "\n\n---\n\n" + section
 
 
+SECTION_1_HEADING = "## 1. Clarification Items"
+_SECTION_1_TABLE_HEADER = (
+    "| Record | Statement | Expected form | User input |\n"
+    "|---|---|---|---|"
+)
+_SECTION_1_EMPTY_STATE = "- The source report recorded no clarification items."
+
+
 def _clarification_carry_body(
     source: Path, text: str, answers: dict[str, str]
 ) -> str:
@@ -516,12 +667,10 @@ def _clarification_carry_body(
     §1 이 있으면 사이드카 답변을 그 표의 `User input` 열에 병합해, 답이 표 안에
     자리하도록 한다(파일 헤더가 선언하는 "답은 User input 열에" 계약을 실제로
     참으로 만든다)."""
-    slice_ = _section_1_slice(text)
-    if slice_ is None:
+    carried = _carry_section_1(source, text)
+    if carried is None:
         return text
-    heading = SECTION_HEADING_PATTERN.search(text)
-    assert heading is not None  # _section_1_slice returned a slice
-    section_body = slice_.rstrip()
+    heading, section_body = carried
     if answers:
         section_body = _reconcile_user_input(section_body, answers)
     return (
@@ -531,10 +680,58 @@ def _clarification_carry_body(
         "section; the report itself is read from the path above when a phase "
         "needs it. Do not re-read the source report to find the answers — they "
         "are in the `User input` column below.\n\n"
-        f"{heading.group(0)}\n{section_body}\n"
+        f"{heading}\n{section_body}\n"
     )
 
 
+def _carry_section_1(source: Path, text: str) -> Optional[tuple[str, str]]:
+    """carry-in 본문에 실을 (헤딩, §1 본문). clarification 을 담지 않은 소스면
+    ``None``.
+
+    schema-v2 는 행을 data.json 에 들고 AI 마크다운에는 §1 표가 없다. §1 슬라이스
+    만 보던 동안 v2 소스는 "좁힐 것이 없다" 로 판정돼 **리포트 전문이 그대로
+    복사**됐다 — 이 좁히기가 막으려던 바로 그 중복이다. carry-in 은 파생 문서이고
+    다운스트림(승인 게이트·프롬프트 빌더·검증 워커)이 §1 표 하나만 읽으므로, v2
+    행도 같은 표로 렌더한다."""
+    data = _v2_report_data(source)
+    if data is not None:
+        entries = data.get("clarificationItems")
+        return SECTION_1_HEADING, _v2_section_1_body(
+            entries if isinstance(entries, list) else []
+        )
+    slice_ = _section_1_slice(text)
+    if slice_ is None:
+        return None
+    heading = SECTION_HEADING_PATTERN.search(text)
+    assert heading is not None  # _section_1_slice returned a slice
+    return heading.group(0), slice_.rstrip()
+
+
+def _v2_section_1_body(entries: list) -> str:
+    """schema-v2 `clarificationItems[]` 를 §1 표 본문으로.
+
+    메타 셀은 렌더러가 쓰는 모양 그대로다 — `Status:` 는 따옴표 없이 써야
+    `_reconcile_user_input` 이 답을 병합하면서 상태를 resolved 로 넘길 수 있다."""
+    rows = [e for e in entries if isinstance(e, dict) and e.get("id")]
+    if not rows:
+        return f"\n{_SECTION_1_EMPTY_STATE}"
+    lines = ["", _SECTION_1_TABLE_HEADER]
+    for entry in rows:
+        meta = (
+            f"**{entry['id']}**"
+            f"<br>Ticket: `{to_cell_text(entry.get('ticketId'))}`"
+            f"<br>Kind: `{to_cell_text(entry.get('kind'))}`"
+            f"<br>Blocks: `{to_cell_text(entry.get('blocks'))}`"
+            f"<br>Status: {to_cell_text(entry.get('status'))}"
+        )
+        lines.append(
+            f"| {meta} | {to_cell_text(entry.get('statement'))} "
+            f"| {to_cell_text(entry.get('expectedForm'))} "
+            f"| {to_cell_text(entry.get('userInput'))} |"
+        )
+    return "\n".join(lines)
+
+
 # The final-report renderer writes `Status: open` / `Status: answered` unquoted
 # in the stacked meta cell; only those two are unresolved. Resolve in place so
 # the meta cell's other fields (ID, Ticket, Kind, Blocks) are left untouched.

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -37,6 +37,7 @@ from .dispatch_state import (
     dispatch_mode as _dispatch_mode,
     load_json_object as _load_json_object,
     missing_completion_paths as _missing_completion_paths,
+    LIVENESS_WRAPPER_STATUS,
     require_string as _require_string,
     resolve_project_path as _resolve_project_path,
     resolve_required_path as _resolve_required_path,
@@ -437,7 +438,7 @@ def _worker_dispatch_record(
         "promptPath": str(worker.prompt_path),
         "resultPath": str(worker.result_path),
         "workerResultPath": str(worker.worker_result_path),
-        "livenessMode": "wrapper-status",
+        "livenessMode": LIVENESS_WRAPPER_STATUS,
         "statusSidecarPath": str(status_path_for_prompt(worker.prompt_path)),
         "degradedFrom": "",
         "reason": reason,

package/runtime/python/okstra_ctl/convergence.py

@@ -123,7 +123,21 @@ def _parser() -> argparse.ArgumentParser:
     subparsers = parser.add_subparsers(dest="operation", required=True)
 
     example = subparsers.add_parser(
-        "example", help="print a deterministic input artifact example"
+        "example",
+        help="print a deterministic input artifact example",
+        description=(
+            "Print one deterministic valid example as JSON.\n\n"
+            "`groups` feeds `seed --groups` and `round-results` feeds "
+            "`apply-round --results`, but `critic-results` is the critic "
+            "worker's own result document — NOT the `apply-critic-gaps "
+            "--results` input. That input is the coverage batch the lead "
+            "assembles from those candidates plus each analyser's vote "
+            '({schemaVersion, taskKey, mode: "coverage", provider, '
+            "modelExecutionValue, dispatches[], gaps[]}); see "
+            'prompts/lead/convergence.md §"Coverage critic". Feeding this '
+            "example straight into `apply-critic-gaps` is rejected, by design."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     example.add_argument(
         "--kind",

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -18,6 +18,8 @@ from .dispatch_state import (
     DispatchError,
     WorkerJob,
     dispatch_mode as _dispatch_mode,
+    LIVENESS_AUDIT_HEARTBEAT,
+    LIVENESS_WRAPPER_STATUS,
     load_json_object as _load_json_object,
     missing_completion_paths as _missing_completion_paths,
     require_string as _require_string,
@@ -52,8 +54,6 @@ from .worker_artifact_paths import audit_sidecar_rel
 from .wrapper_status import read_wrapper_status, status_path_for_prompt
 
 
-LIVENESS_AUDIT_HEARTBEAT = "audit-heartbeat"
-LIVENESS_WRAPPER_STATUS = "wrapper-status"
 MAX_WORKER_ATTEMPTS = 2
 TERMINAL_DISPATCH_STATUSES = {"completed", "timeout", "error", "not-run"}
 

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -34,6 +34,13 @@ BACKEND_CLI_WRAPPER = "cli-wrapper"
 BACKEND_TMUX_PANE = "tmux-pane"
 BACKEND_MIXED = "mixed"
 
+# `livenessMode` picks which artifact answers "is this worker still alive": the
+# in-process worker's audit sidecar heartbeat, or the CLI wrapper's status
+# sidecar. Both dispatchers write it and `worker_liveness` reads it, so the
+# vocabulary lives here rather than in whichever module happened to need it.
+LIVENESS_AUDIT_HEARTBEAT = "audit-heartbeat"
+LIVENESS_WRAPPER_STATUS = "wrapper-status"
+
 # The worktree argument grants the wrapper `--add-dir` write access outside
 # project-root. Only the phases whose workers mutate a stage worktree get it;
 # analysis phases write their artifacts under project-root (see the contract in
@@ -214,7 +221,11 @@ def transition_worker_status(
             else:
                 worker["endedAt"] = timestamp
             if model_execution_value:
-                worker["model"] = model_execution_value
+                # `model` is the catalog display name the task-manifest
+                # declares; only the execution identifier belongs here. Writing
+                # both from one value destroys the display name on every worker
+                # whose two differ, and `validate-run` compares team-state's
+                # `model` against the manifest.
                 worker["modelExecutionValue"] = model_execution_value
             write_json(team_state_path, payload)
             return

package/runtime/python/okstra_ctl/final_report_paths.py

@@ -1,4 +1,4 @@
-"""Path helpers for the final-report markdown/data.json pair."""
+"""Path helpers for the final-report markdown/data.json pair and its sidecars."""
 from __future__ import annotations
 
 from pathlib import Path
@@ -6,6 +6,12 @@ from pathlib import Path
 
 DATA_JSON_SUFFIX = ".data.json"
 MARKDOWN_SUFFIX = ".md"
+TRANSLATION_SOURCE_SUFFIX = ".translation-source.json"
+
+
+def _stem(data_path: Path) -> str:
+    name = data_path.name
+    return name[: -len(DATA_JSON_SUFFIX)] if name.endswith(DATA_JSON_SUFFIX) else data_path.stem
 
 
 def final_report_data_path(report_path: Path) -> Path:
@@ -22,3 +28,18 @@ def final_report_markdown_path(data_path: Path) -> Path:
     if name.endswith(DATA_JSON_SUFFIX):
         return data_path.with_name(name[: -len(DATA_JSON_SUFFIX)] + MARKDOWN_SUFFIX)
     return data_path.with_suffix(MARKDOWN_SUFFIX)
+
+
+def translation_source_path(data_path: Path) -> Path:
+    """Return the translator's work list for a final-report data.json path."""
+    return data_path.with_name(_stem(data_path) + TRANSLATION_SOURCE_SUFFIX)
+
+
+def translation_sidecar_path(data_path: Path, lang: str) -> Path:
+    """Return the filled translation sidecar the HTML renderer overlays.
+
+    One file per language beside the report it translates, so the renderer
+    finds it from the data.json alone and a run for another language does not
+    overwrite it.
+    """
+    return data_path.with_name(f"{_stem(data_path)}.i18n.{lang}.json")

package/runtime/python/okstra_ctl/i18n.py

@@ -13,35 +13,40 @@ from typing import Any, Callable
 
 SUPPORTED_LANGS = ("en", "ko")
 DICTIONARY_REL = ("templates", "reports", "i18n")
+# The human HTML has its own fixed strings — table headings, empty states,
+# enum labels — that the AI-handoff Markdown never renders. Same loader, its
+# own dictionary, so a heading added to one does not have to exist in the other.
+HTML_DICTIONARY_REL = ("templates", "reports", "html", "i18n")
 
 
 class I18nError(RuntimeError):
     """사전 lookup 실패 또는 사전 로드 실패."""
 
 
-def _i18n_dir() -> Path:
+def _i18n_dir(rel: tuple[str, ...] = DICTIONARY_REL) -> Path:
     okstra_home = os.environ.get("OKSTRA_HOME")
     if okstra_home:
-        candidate = Path(okstra_home).joinpath(*DICTIONARY_REL)
+        candidate = Path(okstra_home).joinpath(*rel)
         if candidate.is_dir():
             return candidate
     here = Path(__file__).resolve()
     for parent in [here, *here.parents]:
-        candidate = parent.joinpath(*DICTIONARY_REL)
+        candidate = parent.joinpath(*rel)
         if candidate.is_dir():
             return candidate
+    joined = "/".join(rel)
     raise I18nError(
-        "could not locate templates/reports/i18n/. Set OKSTRA_HOME or "
-        "run from a checkout that contains templates/reports/i18n/."
+        f"could not locate {joined}/. Set OKSTRA_HOME or "
+        f"run from a checkout that contains {joined}/."
     )
 
 
-def load_dictionary(lang: str) -> dict[str, Any]:
+def load_dictionary(lang: str, rel: tuple[str, ...] = DICTIONARY_REL) -> dict[str, Any]:
     if lang not in SUPPORTED_LANGS:
         raise I18nError(
             f"unsupported reportLanguage {lang!r}; supported: {SUPPORTED_LANGS}"
         )
-    path = _i18n_dir() / f"{lang}.json"
+    path = _i18n_dir(rel) / f"{lang}.json"
     try:
         return json.loads(path.read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError) as exc: