okstra 0.180.0 → 0.183.2

package/runtime/python/okstra_ctl/agent_prompt_cli.py

@@ -34,6 +34,8 @@ from .agent_invocation import (
     verify_agent_invocation,
     v2_role_assignment_authority_errors,
 )
+from .fixed_text import line
+from .json_boundary import JsonBoundaryError, load_owned_object
 from .convergence_store import (
     DYNAMIC_VERIFIER_SOURCE_ROLES,
     reserve_dynamic_verifier,
@@ -48,6 +50,7 @@ from .wrapper_status import (
     prompt_derived_paths,
     status_path_for_prompt,
 )
+from .report_inputs import report_narrative_path, uses_report_contract_v3
 from .worker_prompt_policy import (
     CRITIC_DUTY_BY_ASSIGNMENT_SEGMENT,
     resolve_prompt_plan_for_manifest,
@@ -73,6 +76,13 @@ class AgentPromptCliError(RuntimeError):
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="okstra agent-prompt")
     commands = parser.add_subparsers(dest="command", required=True)
+    _add_materialize_parser(commands)
+    _add_completion_parsers(commands)
+    _add_dispatch_parsers(commands)
+    return parser
+
+
+def _add_materialize_parser(commands: argparse._SubParsersAction) -> None:
     materialize = commands.add_parser("materialize")
     _common_paths(materialize)
     materialize.add_argument("--invocation-id", required=True)
@@ -113,7 +123,10 @@ def _parser() -> argparse.ArgumentParser:
     verify.add_argument("--run-manifest")
     verify.add_argument("--metadata", required=True)
     verify.add_argument("--json", action="store_true")
+    verify.add_argument("--text", action="store_true")
 
+
+def _add_completion_parsers(commands: argparse._SubParsersAction) -> None:
     materialize_result = commands.add_parser("materialize-result")
     _standalone_completion_args(materialize_result)
     materialize_result.add_argument("--returned-body-file", required=True)
@@ -127,6 +140,8 @@ def _parser() -> argparse.ArgumentParser:
     verify_completion.add_argument("--completion", required=True)
     verify_completion.add_argument("--json", action="store_true")
 
+
+def _add_dispatch_parsers(commands: argparse._SubParsersAction) -> None:
     record_dispatch = commands.add_parser("record-dispatch")
     _common_paths(record_dispatch)
     record_dispatch.add_argument("--run-manifest", required=True)
@@ -156,7 +171,6 @@ def _parser() -> argparse.ArgumentParser:
     link_result.add_argument("--dispatch-id", required=True)
     link_result.add_argument("--result", required=True)
     link_result.add_argument("--json", action="store_true")
-    return parser
 
 
 def _common_paths(parser: argparse.ArgumentParser) -> None:
@@ -182,6 +196,7 @@ def main(argv: list[str] | None = None) -> int:
             _emit(
                 {"ok": True, "metadataPath": str(Path(args.metadata).resolve())},
                 args.json,
+                args.text,
             )
             return 0
         if args.command == "materialize-result":
@@ -317,16 +332,32 @@ def _materialize_run(
     )
     if args.audience == "report-writer" and not args.audit_source:
         # The report writer is the one audience whose result path is not its own
-        # worker result: it writes the report narrative, while the audit
-        # sidecar is derived from its `.md`. With both collapsed into one value
-        # the prompt loses its `**Worker Result Path:**` anchor and the writer
-        # puts the report where the audit file belongs — silently, because every
-        # header is still present and well-formed. The roster path derives both
-        # from the manifest; a dynamic call has to name them.
+        # worker result: it writes the report body, while the audit sidecar is
+        # derived from its `.md`. With both collapsed into one value the prompt
+        # loses its `**Worker Result Path:**` anchor and the writer puts the
+        # report where the audit file belongs — silently, because every header
+        # is still present and well-formed. The roster path derives both from
+        # the manifest; a dynamic call has to name them.
+        #
+        # Which artifact `--result` names depends on the report contract, and
+        # `dispatch_state.dispatch_result_path` is what decides it. Naming only
+        # the v2 answer here sent v3 runs to the data.json, so the narrative
+        # `report-finalize` assembles from was never written and the phase
+        # failed later, at a place that does not point back here.
+        if uses_report_contract_v3(manifest):
+            expected = report_narrative_path(project_root, manifest)
+            raise AgentPromptCliError(
+                "report-writer materialization requires --audit-source: under "
+                f"report contract 3.0 --result is the narrative ({expected}), "
+                "which `report-finalize` assembles the report data.json from, "
+                "and --audit-source the worker-result .md the audit sidecar is "
+                "derived from"
+            )
         raise AgentPromptCliError(
-            "report-writer materialization requires --audit-source: --result is "
-            "the report data.json, --audit-source the worker-result .md the "
-            "audit sidecar is derived from"
+            "report-writer materialization requires --audit-source: under "
+            "report contract 2.0 --result is the report data.json, and "
+            "--audit-source the worker-result .md the audit sidecar is "
+            "derived from"
         )
     audit_source_path = (
         _authorized_path(
@@ -636,11 +667,12 @@ def _validate_run_identity(
         expected = CRITIC_DUTY_BY_ASSIGNMENT_SEGMENT.get(scope, "")
         if not expected or dispatch_kind != "critic":
             raise AgentPromptCliError("critic assignment identity is invalid")
-        convergence = manifest.get("convergence")
-        critic = convergence.get("critic") if isinstance(convergence, Mapping) else None
-        provider = critic.get("provider") if isinstance(critic, Mapping) else None
-        if provider and provider != worker_id:
-            raise AgentPromptCliError("critic worker does not match manifest provider")
+        # provider 대조는 여기 두지 않는다. critic 의 `worker_id` 는 배정 참조의
+        # 마지막 마디(`scope` / `acceptance`)이고 provider 이름이 아니다
+        # (`render.py` 의 로스터 행이 `assignment_ref.rsplit("/", 1)[-1]` 로 만든다).
+        # 종전에 있던 `provider != worker_id` 검사는 두 어휘를 비교해서 늘 참이 되는
+        # 형태였고, 설정을 run manifest 에서 찾다 못 찾아 조용히 건너뛰었기에
+        # 드러나지 않았다. 정본에서 읽게 고치면 모든 critic 디스패치가 거부된다.
     else:
         try:
             expected = resolve_prompt_plan_for_manifest(
@@ -1039,8 +1071,8 @@ def _relative(project_root: Path, path: Path) -> str:
 
 def _read_json_object(path: Path, label: str) -> dict[str, Any]:
     try:
-        value = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        value = load_owned_object(path, artifact="agent prompt metadata")
+    except JsonBoundaryError as exc:
         raise AgentPromptCliError(f"{label} is invalid: {path}") from exc
     if not isinstance(value, dict):
         raise AgentPromptCliError(f"{label} must be a JSON object: {path}")
@@ -1098,12 +1130,27 @@ def _prepared_payload(
     }
 
 
-def _emit(payload: Mapping[str, object], as_json: bool) -> None:
+def _emit(
+    payload: Mapping[str, object], as_json: bool, as_text: bool = False
+) -> None:
     if as_json:
         print(json.dumps(payload, ensure_ascii=False, indent=2))
+    elif as_text:
+        print(render_agent_prompt_text(payload), end="")
     else:
         print(payload.get("promptPath") or payload.get("metadataPath") or "ok")
 
 
+def render_agent_prompt_text(payload: Mapping[str, object]) -> str:
+    """agent prompt 검증 결과의 승인된 경로만 투영한다."""
+    rows = ["Okstra agent prompt\n"]
+    rows.append(line("Status", "ready" if payload.get("ok", True) else "error"))
+    for label, key in (("Prompt path", "promptPath"), ("Metadata path", "metadataPath"),
+                       ("Assignment ID", "assignmentId"), ("Worker role", "workerRole")):
+        if key in payload:
+            rows.append(line(label, payload.get(key)))
+    return "".join(rows)
+
+
 if __name__ == "__main__":
     raise SystemExit(main())

package/runtime/python/okstra_ctl/analysis_inputs.py

@@ -11,6 +11,7 @@ from typing import Mapping, Sequence
 
 from .final_report_paths import final_report_data_path
 from .paths import task_manifest_file
+from .json_boundary import JsonBoundaryError, load_owned_object
 from .user_response import (
     UserResponseError,
     load_authoritative_analysis_review,
@@ -196,8 +197,8 @@ def _task_key_from_manifest(task_root: Path, okstra_root: Path) -> str:
         task_manifest_file(task_root), okstra_root, "task manifest path"
     )
     try:
-        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
+        manifest = load_owned_object(manifest_path, artifact="task manifest")
+    except JsonBoundaryError as exc:
         raise AnalysisInputError(f"cannot read task manifest: {manifest_path}") from exc
     if not isinstance(manifest, dict):
         raise AnalysisInputError("task manifest must contain an object")
@@ -219,8 +220,8 @@ def load_analysis_report_candidate(
         raise AnalysisInputError("report filename is not a final report")
     data_path = _resolved_within(final_report_data_path(report), okstra_root, "data.json path")
     try:
-        data = json.loads(data_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
+        data = load_owned_object(data_path, artifact="analysis report record")
+    except JsonBoundaryError as exc:
         raise AnalysisInputError(f"cannot read data.json: {data_path}") from exc
     if not isinstance(data, dict):
         raise AnalysisInputError("data.json must contain an object")

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -128,7 +128,87 @@ def build_analysis_packet(
     parts.extend(_stage_ledger_unavailable_block(stage_ledger_notice))
     parts.extend(_clarification_block(clarification_text))
     parts.extend(_directive_block(directive))
-    return "\n".join(part.rstrip() for part in parts).rstrip() + "\n"
+    body = "\n".join(part.rstrip() for part in parts).rstrip() + "\n"
+    return _with_section_index(body)
+
+
+_HEADING_RE = re.compile(r"\A#{1,2} \S")
+_FENCE_RE = re.compile(r"\A\s*(```|~~~)")
+# 목차 자신이 차지하는 줄 수 중 표제 행을 뺀 나머지. 행 수는 표제 개수로
+# 정해지므로 삽입 전에 전체 이동량을 계산할 수 있다.
+_INDEX_PREAMBLE_LINES = 5
+
+
+def _with_section_index(body: str) -> str:
+    """Prefix the rendered packet with every section's line range.
+
+    The packet's own structure is the only thing a worker can navigate it by,
+    and a worker cannot navigate what it cannot see. Measured 2026-08-21: the
+    antigravity CLI's `view_file` truncates at 46,080 bytes per call, carries
+    no line-range parameter, and reports only `<n> lines, <m> bytes` — the same
+    string whether it returned the file or 40% of it. On a 114KB packet that
+    first call ended at line 510, so `## Stage Ledger` (572) and
+    `## Clarification Carry-In Extract` (680) never arrived and the worker
+    planned from the pre-migration brief that fills the first 42KB. Every
+    evidence line it cited was under 400. With the ranges here a truncated
+    reader can fetch the block it is missing by range instead of re-reading
+    the head; the lead had to write those ranges by hand to get a usable
+    retry.
+    """
+    lines = body.splitlines()
+    anchor = next(
+        (i for i, line in enumerate(lines)
+         if line.startswith("# OKSTRA Analysis Packet")),
+        None,
+    )
+    if anchor is None:
+        return body
+    headings = _heading_lines(lines)
+    if not headings:
+        return body
+    shift = _INDEX_PREAMBLE_LINES + len(headings)
+    total = len(lines) + shift
+    starts = [number + shift for number, _ in headings]
+    rows = [
+        f"- {start}-{end} `{text}`"
+        for start, end, (_, text) in zip(
+            starts, [nxt - 1 for nxt in starts[1:]] + [total], headings
+        )
+    ]
+    block = [
+        "",
+        "## Section Index",
+        "",
+        f"This packet is {total} lines. Read a section by line range with"
+        " `sed -n '<start>,<end>p'` rather than opening the whole file: a"
+        " whole-file read is truncated by some worker CLIs without reporting"
+        " it, and the sections that describe current state are last.",
+        "",
+        *rows,
+    ]
+    assert len(block) == shift, (len(block), shift)
+    return "\n".join(lines[:anchor + 1] + block + lines[anchor + 1:]) + "\n"
+
+
+def _heading_lines(lines: list[str]) -> list[tuple[int, str]]:
+    """Every `#`/`##` heading outside a fence, as (1-based line, text).
+
+    Fences are tracked because the Stage Ledger and the carried-in
+    clarification rows embed JSON and shell text where a `#` starts a comment,
+    not a section.
+    """
+    out: list[tuple[int, str]] = []
+    fenced = False
+    for number, line in enumerate(lines, start=1):
+        if _FENCE_RE.match(line):
+            fenced = not fenced
+            continue
+        if fenced or not _HEADING_RE.match(line):
+            continue
+        if line.startswith("# OKSTRA Analysis Packet"):
+            continue
+        out.append((number, line.strip()))
+    return out
 
 
 def _packet_frontmatter(brief_text: str, task_key: str) -> str:

package/runtime/python/okstra_ctl/approval_decisions.py

@@ -11,6 +11,7 @@ from pathlib import Path
 from typing import Any, Mapping, Sequence
 
 from .convergence_store import write_json_atomic
+from .json_boundary import JsonBoundaryError, load_owned_object
 
 
 DISPOSITIONS = frozenset({"select", "accept-risk", "request-revision", "reject"})
@@ -87,8 +88,8 @@ def _new_ledger(task_key: str, task_type: str, run_seq: str) -> dict[str, Any]:
 
 def _read_ledger(path: Path) -> dict[str, Any]:
     try:
-        value = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        value = load_owned_object(path, artifact="approval decision ledger")
+    except JsonBoundaryError as exc:
         raise ApprovalDecisionError(f"cannot read approval ledger {path}: {exc}") from exc
     if not isinstance(value, dict) or value.get("owner") != "lead":
         raise ApprovalDecisionError(f"approval ledger owner must be lead: {path}")

package/runtime/python/okstra_ctl/attempt_evidence.py

@@ -12,6 +12,7 @@ from .domain.worker_stream import host_event_row
 from .execution_identity import Attempt, ExecutionManifestError
 from .execution_manifest import read_execution_manifest
 from .execution_manifest import _replace_manifest, _write_manifest_over_existing
+from .jsonl import append_jsonl
 from .run_context import task_mutex
 
 
@@ -104,8 +105,7 @@ class HostEventStreamWriter:
             payload=payload,
             timestamp=_utc_now(),
         )
-        with self.path.open("a", encoding="utf-8") as handle:
-            handle.write(json.dumps(row, ensure_ascii=False) + "\n")
+        append_jsonl(self.path, row, ensure_ascii=False, compact=False)
         return row
 
 

package/runtime/python/okstra_ctl/backfill.py

@@ -13,6 +13,7 @@ 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 .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
 from .project_meta import _project_meta_path
 from .reconcile import _now_iso, normalize_central_status
 from .run_index_row import build_run_index_row
@@ -64,8 +65,8 @@ def discover_project_roots(home: Path) -> List[tuple]:
         if not meta_file.is_file():
             continue
         try:
-            meta = json.loads(meta_file.read_text())
-        except (OSError, json.JSONDecodeError):
+            meta = load_owned_object(meta_file, artifact="project metadata")
+        except JsonBoundaryError:
             continue
         pid = str(meta.get("projectId") or "")
         root = str(meta.get("projectRoot") or "")
@@ -89,7 +90,7 @@ def _apply_backfill_meta(home: Path, project_id: str, project_root: Path, *,
     target = _project_meta_path(home, project_id)
     target.parent.mkdir(parents=True, exist_ok=True)
     if target.is_file():
-        meta = json.loads(target.read_text())
+        meta = load_owned_object(target, artifact="project metadata")
     else:
         meta = {"projectId": project_id, "projectRoot": str(project_root),
                 "firstRunAt": "", "lastRunAt": "",
@@ -108,9 +109,7 @@ def _apply_backfill_meta(home: Path, project_id: str, project_root: Path, *,
     meta["runCount"] = int(meta.get("runCount", 0)) + run_count_inc
     meta["activeCount"] = max(
         0, int(meta.get("activeCount", 0)) + active_count_inc)
-    tmp = target.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(meta, indent=2) + "\n")
-    os.replace(tmp, target)
+    write_owned_object_atomic(target, meta, artifact="project metadata")
 
 
 def backfill_project(home: Path, project_id: str, project_root: Path) -> int:
@@ -142,8 +141,8 @@ def backfill_project(home: Path, project_id: str, project_root: Path) -> int:
                     task_type = m.group("tt")
                     seq = int(m.group("seq"))
                     try:
-                        manifest = json.loads(mf.read_text())
-                    except (OSError, json.JSONDecodeError):
+                        manifest = load_owned_object(mf, artifact="run manifest")
+                    except JsonBoundaryError:
                         # 부분 기록 / 손상된 매니페스트를 빈 dict 로 강등해 row 를
                         # 만들면, 빈 status 가 'completed' 로 normalize 되어
                         # recent 에 박히고, 같은 runId 가 existing_ids 로 인덱싱
@@ -268,6 +267,10 @@ def backfill_project(home: Path, project_id: str, project_root: Path) -> int:
 
 def mark_backfilled(home: Path) -> None:
     state_file = home / "state.json"
-    state = json.loads(state_file.read_text()) if state_file.is_file() else {}
+    state = (
+        load_owned_object(state_file, artifact="okstra home state")
+        if state_file.is_file()
+        else {}
+    )
     state["backfilledAt"] = _now_iso()
-    state_file.write_text(json.dumps(state, indent=2) + "\n")
+    write_owned_object_atomic(state_file, state, artifact="okstra home state")

package/runtime/python/okstra_ctl/batch.py

@@ -9,6 +9,7 @@ from pathlib import Path
 from typing import List, Optional
 
 from .listing import list_runs
+from .json_boundary import write_owned_object_atomic
 from .resolver import resolve_last, resolve_run_id
 
 
@@ -20,10 +21,7 @@ def make_batch_id() -> str:
 
 def write_batch_meta(home: Path, batch_id: str, payload: dict) -> Path:
     target = home / "batches" / f"{batch_id}.json"
-    target.parent.mkdir(parents=True, exist_ok=True)
-    tmp = target.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(payload, indent=2) + "\n")
-    os.replace(tmp, target)
+    write_owned_object_atomic(target, payload, artifact="batch metadata")
     return target
 
 

package/runtime/python/okstra_ctl/build_tools.py

@@ -16,6 +16,8 @@ import json
 import shlex
 from pathlib import Path
 
+from .json_boundary import JsonBoundaryError, load_owned_object
+
 DEFAULT_BUILD_TOOL_TOKENS: tuple[str, ...] = (
     "npm",
     "yarn",
@@ -49,10 +51,11 @@ def resolve_build_tool_tokens(project_root: Path) -> tuple[str, ...]:
     uses, so one rule covers both.
     """
     try:
-        payload = json.loads(
-            (Path(project_root) / ".okstra" / "project.json").read_text(encoding="utf-8")
+        payload = load_owned_object(
+            Path(project_root) / ".okstra" / "project.json",
+            artifact="project configuration",
         )
-    except (OSError, json.JSONDecodeError):
+    except JsonBoundaryError:
         return DEFAULT_BUILD_TOOL_TOKENS
     configured = payload.get("buildToolTokens") if isinstance(payload, dict) else None
     if not isinstance(configured, list):

package/runtime/python/okstra_ctl/claim_reproduction.py

@@ -0,0 +1,101 @@
+"""사실 주장의 재현.
+
+계획 검증의 1표 차단(`kind a`, `P-Req` 의 `kind f`)에는 근거가 있다 — 명시된 두
+인용이 서로 모순이라는 것은 한 명이 실측으로 확정할 수 있는 사실이고, 사실을
+다수결로 기각하면 안 된다. 문제는 1표라는 것이 아니라 **1표에 재현 요구가 없다**는
+것이었다. 검증자가 "이 경로는 존재하지 않는다" 라고 쓰면 그대로 차단이 됐다.
+
+여기서 재현은 워커가 아니라 이 코드가 실행한다. 워커가 결과까지 신고하면 판정이
+자기신고 위에 서고, 같은 주장이 워커마다 다르게 결론난다.
+
+대가는 표현력이다. 여기서 돌릴 수 있는 형태로만 사실 주장을 쓸 수 있고, 그 밖의
+것은 `judgement` 로 내어 정족수로 판정한다. 강등이 아니라 분류다 — 기계가 확인할
+수 없는 것에 1표 차단을 주는 것이 애초에 틀렸다.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+REPRODUCED = "reproduced"
+NOT_REPRODUCED = "not-reproduced"
+NOT_RUNNABLE = "not-runnable"
+
+PROBE_KINDS = (
+    "path-exists",
+    "path-absent",
+    "literal-present",
+    "literal-absent",
+    "citations-differ",
+)
+
+_MAX_READ_BYTES = 4_000_000
+
+
+def _within(project_root: Path, value: object) -> Path | None:
+    """프로젝트 안의 경로. 밖으로 나가거나 모양이 아니면 ``None``.
+
+    재현은 검증자가 쓴 문자열을 그대로 받는다. 담아 두지 않으면 그 문자열 하나로
+    프로젝트 밖을 읽게 된다.
+    """
+    if not isinstance(value, str) or not value.strip():
+        return None
+    candidate = Path(value)
+    resolved = (
+        candidate if candidate.is_absolute() else project_root / candidate
+    )
+    try:
+        resolved = resolved.resolve()
+        root = project_root.resolve()
+    except (OSError, RuntimeError):
+        return None
+    return resolved if resolved == root or root in resolved.parents else None
+
+
+def _read(path: Path) -> str | None:
+    try:
+        if not path.is_file() or path.stat().st_size > _MAX_READ_BYTES:
+            return None
+        return path.read_text(encoding="utf-8", errors="replace")
+    except (OSError, ValueError):
+        return None
+
+
+def reproduce(probe: object, *, project_root: Path) -> str:
+    """이 프로브를 실행한 결과.
+
+    ``reproduced`` 는 주장이 성립한다는 뜻이고, ``not-reproduced`` 는 근거가
+    성립하지 않는다는 뜻이다. ``not-runnable`` 은 판정하지 않았다는 뜻이며 —
+    프로브의 모양이 아니거나, 경로가 프로젝트 밖이거나, 파일을 못 읽은 경우다 —
+    소비처는 이것을 `judgement` 와 같게 다뤄야 한다. 못 돌린 것을 재현 실패로
+    읽으면 도구의 한계가 주장의 기각이 된다.
+    """
+    if not isinstance(probe, Mapping):
+        return NOT_RUNNABLE
+    kind = str(probe.get("kind") or "")
+    if kind not in PROBE_KINDS:
+        return NOT_RUNNABLE
+
+    if kind in ("path-exists", "path-absent"):
+        path = _within(project_root, probe.get("path"))
+        if path is None:
+            return NOT_RUNNABLE
+        exists = path.exists()
+        return REPRODUCED if exists == (kind == "path-exists") else NOT_REPRODUCED
+
+    if kind in ("literal-present", "literal-absent"):
+        path = _within(project_root, probe.get("path"))
+        literal = probe.get("literal")
+        if path is None or not isinstance(literal, str) or not literal:
+            return NOT_RUNNABLE
+        text = _read(path)
+        if text is None:
+            return NOT_RUNNABLE
+        present = literal in text
+        return REPRODUCED if present == (kind == "literal-present") else NOT_REPRODUCED
+
+    left, right = probe.get("left"), probe.get("right")
+    if not isinstance(left, str) or not isinstance(right, str) or not left or not right:
+        return NOT_RUNNABLE
+    # 주장은 "이 둘이 서로 모순이다" 이므로, 다르면 재현된 것이다.
+    return REPRODUCED if left.strip() != right.strip() else NOT_REPRODUCED

package/runtime/python/okstra_ctl/clarification_items.py

@@ -37,6 +37,7 @@ from pathlib import Path
 from typing import Optional
 
 from okstra_ctl.final_report_paths import final_report_data_path
+from okstra_ctl.json_boundary import load_owned_object
 from okstra_ctl.md_table import is_separator_row, split_pipe_row, to_cell_text
 
 
@@ -224,28 +225,41 @@ def parse_clarification_items(report_text: str) -> Optional[list[ClarificationIt
 # 워크는 거기서 아무것도 못 찾으므로, 게이트가 v1 파서만 쓰면 열린 항목이 있는
 # v2 리포트를 "읽을 수 없음"으로 떨어뜨린다. data.json 은 두 렌더러가 이미 읽는
 # SSOT 다 — clarification 상태도 여기서 읽는다.
-SCHEMA_VERSION_V2 = "2.0"
+# 리포트 정본의 구조화 판본. 2.0 과 3.0 은 `clarificationItems[]` 를 같은 자리에
+# 같은 모양으로 들고 있으므로 이 좁히기에는 차이가 없다. ADR-0019 가 2.0 을 계속
+# 판독하라고 정했으므로 둘 다 받는다 — `stage_map.structured_report` 와 같은 규칙.
+STRUCTURED_REPORT_VERSIONS = frozenset({"2.0", "3.0"})
 
 
 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``.
+def _structured_report_data(report_path: Path) -> Optional[dict]:
+    """``report_path`` 의 구조화 리포트 레코드, 아니면 ``None``.
 
-    파일이 없거나 JSON 이 깨졌거나 v2 가 아니면 ``None`` — 호출자는 v1
-    마크다운 경로로 폴백하고, 진짜 v2 인데 사이드카가 깨진 경우는 그 폴백이
-    "§1 없음" fail-closed 로 잡는다.
+    파일이 없거나 JSON 이 깨졌거나 구조화 판본이 아니면 ``None`` — 호출자는 v1
+    마크다운 경로로 폴백하고, 진짜 구조화 리포트인데 레코드가 깨진 경우는 그
+    폴백이 "§1 없음" fail-closed 로 잡는다.
+
+    판본을 `2.0` 하나로 못박아 두던 동안 3.0 리포트가 여기서 ``None`` 이 됐고,
+    그러면 호출자가 JSON 본문에서 `## 1.` 헤딩을 찾다 실패해 **리포트 전문을
+    그대로 복사**했다 — 이 좁히기가 막으려던 바로 그 중복이다. 실측: 66K 짜리
+    추출본이 나와야 할 자리에 693K data.json 이 스테이징됐고, 패킷의
+    `## Clarification Carry-In Extract` 가 0행이 되어 워커가 사용자 답변을
+    전혀 받지 못했다.
     """
     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"))
+        data = load_owned_object(data_path, artifact="final report record")
     except (OSError, ValueError):
         return None
-    if not isinstance(data, dict) or data.get("schemaVersion") != SCHEMA_VERSION_V2:
+    if (
+        not isinstance(data, dict)
+        or data.get("schemaVersion") not in STRUCTURED_REPORT_VERSIONS
+    ):
         return None
     return data
 
@@ -287,7 +301,7 @@ def _v2_row(entry: dict) -> Optional[dict]:
 def _v2_clarification_rows(report_path: Path) -> Optional[list[dict]]:
     """schema-v2 clarification 행들, 이 리포트가 v2 가 아니면 ``None``.
     필수 필드가 빠진 행은 건너뛰는 lenient 계약(§1 파서와 동일)."""
-    data = _v2_report_data(report_path)
+    data = _structured_report_data(report_path)
     if data is None:
         return None
     entries = data.get("clarificationItems")
@@ -503,7 +517,7 @@ def _scan_v2_blockers(
 ) -> Optional[ClarificationScan]:
     """schema-v2 data.json 기준 스캔, 이 리포트가 v2 가 아니면 ``None``.
     필수 필드가 빠진 행은 §1 의 unparsed row 와 같이 fail-closed 로 다룬다."""
-    data = _v2_report_data(report_path)
+    data = _structured_report_data(report_path)
     if data is None:
         return None
     entries = data.get("clarificationItems")
@@ -758,10 +772,10 @@ def _carry_section_1(source: Path, text: str) -> Optional[tuple[str, str]]:
     복사**됐다 — 이 좁히기가 막으려던 바로 그 중복이다. carry-in 은 파생 문서이고
     다운스트림(승인 게이트·프롬프트 빌더·검증 워커)이 §1 표 하나만 읽으므로, v2
     행도 같은 표로 렌더한다."""
-    data = _v2_report_data(source)
+    data = _structured_report_data(source)
     if data is not None:
         entries = data.get("clarificationItems")
-        return SECTION_1_HEADING, _v2_section_1_body(
+        return SECTION_1_HEADING, _structured_section_1_body(
             entries if isinstance(entries, list) else []
         )
     slice_ = _section_1_slice(text)
@@ -772,7 +786,7 @@ def _carry_section_1(source: Path, text: str) -> Optional[tuple[str, str]]:
     return heading.group(0), slice_.rstrip()
 
 
-def _v2_section_1_body(entries: list) -> str:
+def _structured_section_1_body(entries: list) -> str:
     """schema-v2 `clarificationItems[]` 를 §1 표 본문으로.
 
     메타 셀은 렌더러가 쓰는 모양 그대로다 — `Status:` 는 따옴표 없이 써야