okstra 0.178.0 → 0.179.0

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -98,6 +98,14 @@ _MATERIALIZABLE_AUDIENCES = frozenset({
     "report-writer",
 })
 _CLARIFICATION_INPUT_PREFIX = "- Clarification response:"
+# Both sides of a stage judge against the same answers. The verifier used to
+# get only the path under `## Inputs`, so whether it read the override was left
+# to the worker: one provider read it and judged on the replacement command,
+# another did not and reported the superseded plan's command as a stage defect.
+_CLARIFICATION_AUTHORITY_AUDIENCES = frozenset({
+    "implementation-executor",
+    "implementation-verifier",
+})
 _CLARIFICATION_AUTHORITY_HEADING = (
     "# Clarification answers carried in (authoritative)"
 )
@@ -578,8 +586,8 @@ def _resource_lines(
         ]
     bodies = [resource.text.rstrip() for resource in item.resources]
     clarification = (
-        _eager_executor_clarification(item.clarification_input)
-        if item.plan.audience == "implementation-executor"
+        _eager_clarification_authority(item.clarification_input)
+        if item.plan.audience in _CLARIFICATION_AUTHORITY_AUDIENCES
         else ""
     )
     if clarification:
@@ -630,7 +638,7 @@ def _resolve_clarification_input(
     return relative, path
 
 
-def _eager_executor_clarification(
+def _eager_clarification_authority(
     clarification_input: tuple[str, Path] | None,
 ) -> str:
     if clarification_input is None:
@@ -924,7 +932,7 @@ def _validate_existing_clarification_metadata(
             item,
             "Clarification response",
         )
-    _validate_eager_executor_clarification_authority(
+    _validate_eager_clarification_authority(
         context,
         item,
         text,
@@ -932,14 +940,14 @@ def _validate_existing_clarification_metadata(
     )
 
 
-def _validate_eager_executor_clarification_authority(
+def _validate_eager_clarification_authority(
     context: _MaterializationContext,
     item: _PromptItem,
     text: str,
     expected: str | None,
 ) -> None:
     authority_expected = (
-        item.plan.audience == "implementation-executor"
+        item.plan.audience in _CLARIFICATION_AUTHORITY_AUDIENCES
         and context.request.delivery_mode is PromptDeliveryMode.EAGER_INCLUDE
         and bool(_clarification_body(item.clarification_input))
     )
@@ -951,7 +959,7 @@ def _validate_eager_executor_clarification_authority(
     ]
     if not authority_expected and not heading_indexes:
         return
-    if expected is None or len(heading_indexes) != 1:
+    if not authority_expected or expected is None:
         _raise_existing_clarification_invalid(item, "clarification authority")
     expected_lines = [
         _CLARIFICATION_AUTHORITY_HEADING,
@@ -961,11 +969,17 @@ def _validate_eager_executor_clarification_authority(
         f"{_CLARIFICATION_SOURCE_PREFIX} `{expected}`",
         "",
     ]
-    heading_index = heading_indexes[0]
-    authority_lines = lines[
-        heading_index:heading_index + len(expected_lines)
+    # The block okstra injects is what this check owns; the carry-in body that
+    # follows it is the user's own document and may legitimately open with the
+    # same heading. Requiring the phrase to be unique made such a document
+    # undispatchable — the run failed `existing_prompt_invalid` with nothing in
+    # any contract telling the author to avoid that title.
+    matches = [
+        index
+        for index in heading_indexes
+        if lines[index:index + len(expected_lines)] == expected_lines
     ]
-    if not authority_expected or authority_lines != expected_lines:
+    if not matches or any(index < matches[0] for index in heading_indexes):
         _raise_existing_clarification_invalid(item, "clarification authority")
 
 
@@ -1167,7 +1181,7 @@ def _result_paths(
     worker_result = _required_string(state, "resultPath")
     if worker_id != REPORT_WRITER_WORKER_ID:
         return worker_result, None
-    expected_report = _required_string(context.manifest, "expectedReportPath")
+    expected_report = _required_string(context.manifest, "expectedReportRecordPath")
     return str(final_report_data_path(Path(expected_report))), worker_result
 
 

package/runtime/python/okstra_ctl/listing.py

@@ -169,11 +169,13 @@ def format_show(row: dict) -> str:
         f"leadModel       : {row.get('leadModel')}\n"
         f"validation      : {row.get('validation')}\n"
         f"runDirRel       : {row.get('runDirRel')}\n"
-        f"finalReportRel  : {row.get('finalReportRel')}\n"
+        f"finalReportRecordRel  : {row.get('finalReportRecordRel') or row.get('finalReportRel')}\n"
         f"invocationFile  : {inv}\n"
     )
 
 
 def absolute_final_report_path(row: dict) -> Optional[Path]:
-    target = resolve_under_root(row.get("projectRoot", ""), row.get("finalReportRel", ""))
+    from .final_report_paths import index_report_record_rel
+
+    target = resolve_under_root(row.get("projectRoot", ""), index_report_record_rel(row))
     return target.resolve() if target is not None else None

package/runtime/python/okstra_ctl/manager_launch.py

@@ -132,7 +132,7 @@ def _render_context(
     )
     for row in siblings:
         lines.append(
-            f"- {row.get('taskKey')}: {row.get('latestRunStatus') or 'unknown'} {row.get('latestReportPath') or ''}"
+            f"- {row.get('taskKey')}: {row.get('latestRunStatus') or 'unknown'} {row.get('latestReportRecordPath') or ''}"
         )
     if not siblings:
         lines.append("- none")

package/runtime/python/okstra_ctl/manager_sync.py

@@ -89,7 +89,7 @@ def _snapshot_child(project_root: Path, child: dict) -> dict:
             workflow.get("nextRecommendedPhase")
         ),
         "latestRunStatus": str(manifest.get("latestRunStatus") or manifest.get("currentStatus") or ""),
-        "latestReportPath": str(manifest.get("latestReportPath") or ""),
+        "latestReportRecordPath": str(manifest.get("latestReportRecordPath") or ""),
         "finalVerdict": str(outcome.get("finalVerdict") or ""),
         "crossProjectDependencies": _list_field(outcome, "crossProjectDependencies"),
         "recommendedNextSteps": _list_field(outcome, "recommendedNextSteps"),

package/runtime/python/okstra_ctl/path_hints.py

@@ -200,7 +200,7 @@ def _hydrate_active_run(
         "runManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
         "promptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
-        "finalReportPath": ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+        "finalReportRecordPath": ctx.get("FINAL_REPORT_RECORD_RELATIVE_PATH", ""),
         "convergenceStatePath": ctx.get("CONVERGENCE_STATE_RELATIVE_PATH", ""),
         "finalStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
         "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
@@ -651,7 +651,7 @@ def _relative_file_fields(project_root: Path, paths: Mapping[str, Any]) -> dict[
         "CODEX_WORKER_PROMPT_RELATIVE_PATH": _rel(project_root, paths["codex_worker_prompt"]),
         "ANTIGRAVITY_WORKER_PROMPT_RELATIVE_PATH": _rel(project_root, paths["antigravity_worker_prompt"]),
         "REPORT_WRITER_WORKER_PROMPT_RELATIVE_PATH": _rel(project_root, paths["report_writer_worker_prompt"]),
-        "FINAL_REPORT_RELATIVE_PATH": _rel(project_root, paths["final_report"]),
+        "FINAL_REPORT_RECORD_RELATIVE_PATH": _rel(project_root, paths["final_report"]),
         "CONVERGENCE_STATE_RELATIVE_PATH": _rel(
             project_root, paths["convergence_state"]
         ),

package/runtime/python/okstra_ctl/paths.py

@@ -83,11 +83,12 @@ def find_asset_root(
 
 
 _STAGED_TASK_TYPES = ("implementation", "final-verification")
-# 발견용: bash `find -name 'final-report-*.md'` 와 같은 범위 — seq 이전 세대의
-# 타임스탬프 파일명도 잡아야 옛 번들에서 조용히 실패하지 않는다.
-_REPORT_NAME_RE = re.compile(r"^final-report-.+\.md$")
-# seq 추출용: 정본 이름 `final-report-<task-type>-<NNN>.md` 일 때만.
-_REPORT_SEQ_RE = re.compile(r"^final-report-.+-(?P<seq>\d{3,})\.md$")
+# 발견용: 정본 `final-report-*.data.json` 과, 옛 원장 행이 가리키는 열람본.
+_REPORT_NAME_RE = re.compile(r"^final-report-.+\.(?:md|data\.json)$")
+# seq 추출용: `final-report-<task-type>-<NNN>.data.json` (옛 열람본 이름도).
+_REPORT_SEQ_RE = re.compile(
+    r"^final-report-.+-(?P<seq>\d{3,})\.(?:md|data\.json)$"
+)
 _TASKS_SEGMENTS = Path(TASKS_RELATIVE).parts
 
 
@@ -95,10 +96,12 @@ def _newest_report(reports_dir: Path) -> Optional[Path]:
     """reports 디렉터리에서 mtime 최신 final-report. 동률이면 basename 큰 쪽."""
     if not reports_dir.is_dir():
         return None
-    found = [
+    files = [
         entry for entry in reports_dir.iterdir()
         if entry.is_file() and _REPORT_NAME_RE.match(entry.name)
     ]
+    records = [entry for entry in files if entry.name.endswith(".data.json")]
+    found = records or files
     if not found:
         return None
     return max(found, key=lambda p: (p.stat().st_mtime, p.name))
@@ -182,7 +185,7 @@ class RunRef:
     def report(self) -> Path:
         if self.report_override is not None:
             return self.report_override
-        return self.reports_dir / f"final-report{self._suffix}.md"
+        return self.reports_dir / f"final-report{self._suffix}.data.json"
 
     @property
     def manifest(self) -> Path:
@@ -404,7 +407,7 @@ def _rel(project_root: Path, target: Path) -> str:
 def resolve_under_root(
     project_root: str | Path | None, rel: str | None
 ) -> Path | None:
-    """글로벌 인덱스의 신뢰 불가 상대경로 필드(runDirRel/finalReportRel/
+    """글로벌 인덱스의 신뢰 불가 상대경로 필드(runDirRel/finalReportRecordRel/
     teamStatePath 등)를 project_root 기준 절대경로로 푼다(_rel 의 역).
 
     이 필드들은 신뢰할 수 없어 절대경로나 '..' 가 들어오면 결합 결과가
@@ -538,7 +541,7 @@ def compute_run_paths(
     codex_worker_prompt = run_prompts / f"codex-worker-prompt{suffixes['prompts']}.md"
     antigravity_worker_prompt = run_prompts / f"antigravity-worker-prompt{suffixes['prompts']}.md"
     report_writer_worker_prompt = run_prompts / f"report-writer-worker-prompt{suffixes['prompts']}.md"
-    final_report = run_reports / f"final-report{suffixes['reports']}.md"
+    final_report = run_reports / f"final-report{suffixes['reports']}.data.json"
     final_status = run_status / f"final{suffixes['status']}.status"
     team_state = run_state / f"team-state{suffixes['state']}.json"
     active_run_context = run_state / f"active-run-context{suffixes['state']}.json"
@@ -712,7 +715,7 @@ def compute_run_paths(
         ("CODEX_WORKER_PROMPT_RELATIVE_PATH", codex_worker_prompt),
         ("ANTIGRAVITY_WORKER_PROMPT_RELATIVE_PATH", antigravity_worker_prompt),
         ("REPORT_WRITER_WORKER_PROMPT_RELATIVE_PATH", report_writer_worker_prompt),
-        ("FINAL_REPORT_RELATIVE_PATH", final_report),
+        ("FINAL_REPORT_RECORD_RELATIVE_PATH", final_report),
         ("FINAL_STATUS_RELATIVE_PATH", final_status),
         ("TEAM_STATE_RELATIVE_PATH", team_state),
         ("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", active_run_context),

package/runtime/python/okstra_ctl/plan_run_root.py

@@ -4,8 +4,8 @@
 원장) 과 approved-plan(final-report) 이 모두 이 루트 기준으로 놓인다.
 
 두 진입점이 같은 layout 규칙을 공유한다:
-- final-verification 은 사용자가 넘긴 approved-plan 파일 경로에서 역산한다
-  (``<plan_run_root>/reports/final-report-...md`` → ``parents[1]``).
+- final-verification 은 사용자가 넘긴 approved-plan 정본 경로에서 역산한다
+  (``<plan_run_root>/reports/final-report-....data.json`` → ``parents[1]``).
 - container 는 approved-plan 입력이 없으므로 task-key 로 planning run 디렉터리를
   스캔해 latest done run 을 고른다.
 """
@@ -17,7 +17,9 @@ from typing import NamedTuple
 
 from .stage_targets import PrepareError
 
-_FINAL_REPORT_RE = re.compile(r"final-report-implementation-planning-(\d+)\.md$")
+_FINAL_REPORT_RE = re.compile(
+    r"final-report-implementation-planning-(\d+)\.data\.json$"
+)
 
 
 class PlanRun(NamedTuple):
@@ -29,7 +31,9 @@ class PlanRun(NamedTuple):
 def list_implementation_planning_reports(reports_dir: Path) -> list[Path]:
     """Return numbered implementation-planning reports in latest-first order."""
     numbered: list[tuple[int, Path]] = []
-    for report in reports_dir.glob("final-report-implementation-planning-*.md"):
+    for report in reports_dir.glob(
+        "final-report-implementation-planning-*.data.json"
+    ):
         match = _FINAL_REPORT_RE.fullmatch(report.name)
         if match:
             numbered.append((int(match.group(1)), report))
@@ -40,7 +44,7 @@ def list_implementation_planning_reports(reports_dir: Path) -> list[Path]:
 def plan_run_root_from_approved_plan(approved_plan_path: str | Path) -> Path:
     """approved-plan(final-report) 경로에서 plan_run_root 를 역산한다.
 
-    final-report 는 ``<plan_run_root>/reports/final-report-...md`` 에 놓이므로
+    정본은 ``<plan_run_root>/reports/final-report-....data.json`` 에 놓이므로
     ``parents[1]`` 이 run-root 다. run.py(final-verification) 와 container 가
     이 한 규칙을 공유한다."""
     return Path(approved_plan_path).resolve().parents[1]

package/runtime/python/okstra_ctl/recap.py

@@ -18,6 +18,7 @@ from okstra_ctl.incremental_scope import preview_link_availability_for_report
 from okstra_ctl.paths import task_timeline_file
 from okstra_project import read_task_key
 from okstra_ctl.run_context import dir_flock
+from okstra_ctl.final_report_paths import timeline_report_record_rel
 from okstra_ctl.task_target import resolve_task_root, project_rel
 
 NOTE_KINDS = ("verification-evidence", "decision-draft", "analysis-note")
@@ -51,7 +52,7 @@ def _latest_planning_report(runs: list[dict], project_root: Path) -> Path | None
             continue
         if run.get("taskType") != "implementation-planning":
             continue
-        relative = str(run.get("reportPath") or "")
+        relative = timeline_report_record_rel(run)
         if not relative:
             continue
         report = project_root / relative
@@ -112,7 +113,7 @@ def assemble_recap(task_root: Path, project_root: Path) -> dict:
             "nextRecommendedPhase": next_phase.promote(
                 snap.get("nextRecommendedPhase")
             ),
-            "reportPath": run.get("reportPath", ""),
+            "reportRecordPath": timeline_report_record_rel(run),
         })
         prev_phase = cur
         # latestPhaseStates 는 항상 가장 최근 run 의 상태를 반영해야 한다.

package/runtime/python/okstra_ctl/reconcile.py

@@ -135,7 +135,9 @@ def _reconcile_active_locked(home: Path, *,
             survivors.append(row)
             continue
         project_root = Path(row.get("projectRoot", ""))
-        final_rel = row.get("finalReportRel", "")
+        from .final_report_paths import index_report_record_rel
+
+        final_rel = index_report_record_rel(row)
         final_abs = project_root / final_rel if final_rel else None
         if final_abs and final_abs.is_file():
             validation_status = _read_run_manifest_validation(

package/runtime/python/okstra_ctl/render.py

@@ -591,7 +591,7 @@ def _active_run(ctx: dict) -> dict:
         "runManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
         "promptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
-        "finalReportPath": ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+        "finalReportRecordPath": ctx.get("FINAL_REPORT_RECORD_RELATIVE_PATH", ""),
         "convergenceStatePath": ctx.get("CONVERGENCE_STATE_RELATIVE_PATH", ""),
         "finalStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
         "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
@@ -795,7 +795,7 @@ def render_team_state(team_state_path: str, ctx: dict) -> None:
         "artifacts": {
             "leadPromptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
             "workerPromptsDirectoryPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
-            "finalReportPath": ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+            "finalReportRecordPath": ctx.get("FINAL_REPORT_RECORD_RELATIVE_PATH", ""),
             "finalStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
             "workerResultsDirectoryPath": ctx.get("WORKER_RESULTS_RELATIVE_PATH", ""),
         },
@@ -952,7 +952,7 @@ def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
                 "latestTeamStatePath": s(latest_run, "teamStatePath"),
                 "latestRunStatus": s(manifest, "latestRunStatus")
                 or s(latest_run, "status"),
-                "latestReportPath": s(manifest, "latestReportPath")
+                "latestReportRecordPath": s(manifest, "latestReportRecordPath")
                 or s(latest_run, "reportPath"),
                 "latestResumeCommandPath": s(manifest, "latestResumeCommandPath")
                 or s(latest_run, "resumeCommandPath"),
@@ -1017,8 +1017,8 @@ def render_latest_task_discovery(output_path: str, ctx: dict) -> None:
         "latestRunPromptsPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
         "latestPromptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
         "latestTeamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
-        "latestReportPath": ctx.get("LATEST_REPORT_RELATIVE_PATH", ""),
-        "expectedReportPath": ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+        "latestReportRecordPath": ctx.get("LATEST_REPORT_RECORD_RELATIVE_PATH", ""),
+        "expectedReportRecordPath": ctx.get("FINAL_REPORT_RECORD_RELATIVE_PATH", ""),
         "expectedStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
         "latestResumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
         "historyTimelinePath": ctx.get("TIMELINE_RELATIVE_PATH", ""),
@@ -1297,8 +1297,8 @@ def _derive_latest_pointers(existing: dict, ctx: dict, current_report_relative:
                 "latestTeamStatePath": existing_checkpoint.get(
                     "latestTeamStatePath", existing.get("teamStatePath", "")
                 ),
-                "latestReportPath": existing_checkpoint.get(
-                    "latestReportPath", existing.get("latestReportPath", "")
+                "latestReportRecordPath": existing_checkpoint.get(
+                    "latestReportRecordPath", existing.get("latestReportRecordPath", "")
                 ),
                 "latestResumeCommandPath": existing_checkpoint.get(
                     "latestResumeCommandPath", existing.get("latestResumeCommandPath", "")
@@ -1310,7 +1310,7 @@ def _derive_latest_pointers(existing: dict, ctx: dict, current_report_relative:
             or ctx.get("CURRENT_RUN_STATUS", ""),
             "latestRunPromptsPath": existing.get("latestRunPromptsPath", "")
             or ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
-            "latestReportPath": existing.get("latestReportPath", "")
+            "latestReportRecordPath": existing.get("latestReportRecordPath", "")
             or current_report_relative,
             "latestTeamStatePath": existing.get("teamStatePath", "")
             or ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
@@ -1324,14 +1324,14 @@ def _derive_latest_pointers(existing: dict, ctx: dict, current_report_relative:
             "latestRunPath": ctx.get("LATEST_RUN_RELATIVE_PATH", ""),
             "latestRunManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
             "latestTeamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
-            "latestReportPath": current_report_relative,
+            "latestReportRecordPath": current_report_relative,
             "latestResumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
         },
         "latestRunPath": ctx.get("LATEST_RUN_RELATIVE_PATH", ""),
         "latestRunStatus": ctx.get("CURRENT_RUN_STATUS", ""),
         "latestRunPromptsPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
-        "latestReportPath": current_report_relative
-        or existing.get("latestReportPath", ""),
+        "latestReportRecordPath": current_report_relative
+        or existing.get("latestReportRecordPath", ""),
         "latestTeamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
         "latestResumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", "")
         or existing.get("latestResumeCommandPath", ""),
@@ -1357,8 +1357,8 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
         catalog[item]["role"] for item in reviewers
     ]
     related_tasks = json.loads(ctx.get("RELATED_TASKS_JSON", "[]"))
-    current_report_relative = ctx.get("LATEST_REPORT_RELATIVE_PATH") or ctx.get(
-        "FINAL_REPORT_RELATIVE_PATH", ""
+    current_report_relative = ctx.get("LATEST_REPORT_RECORD_RELATIVE_PATH") or ctx.get(
+        "FINAL_REPORT_RECORD_RELATIVE_PATH", ""
     )
     existing_workflow = (
         existing.get("workflow", {})
@@ -1385,7 +1385,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
     latest_run_relative = pointers["latestRunPath"]
     latest_run_status = pointers["latestRunStatus"]
     latest_run_prompts_relative = pointers["latestRunPromptsPath"]
-    latest_report_relative = pointers["latestReportPath"]
+    latest_report_relative = pointers["latestReportRecordPath"]
     latest_team_state_relative = pointers["latestTeamStatePath"]
     latest_resume_command_relative = pointers["latestResumeCommandPath"]
     convergence_block = _build_convergence_block(ctx)
@@ -1434,7 +1434,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
         "latestRunPath": latest_run_relative,
         "latestRunStatus": latest_run_status,
         "latestRunPromptsPath": latest_run_prompts_relative,
-        "latestReportPath": latest_report_relative,
+        "latestReportRecordPath": latest_report_relative,
         "latestResumeCommandPath": latest_resume_command_relative,
         "teamStatePath": latest_team_state_relative,
         "fixCycles": fix_cycles.summarize(
@@ -1762,7 +1762,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         ),
         "workerPromptsDirectoryPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
         "workerPromptPathByWorkerId": worker_prompt_paths,
-        "expectedReportPath": ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+        "expectedReportRecordPath": ctx.get("FINAL_REPORT_RECORD_RELATIVE_PATH", ""),
         "expectedStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
         "activeRunContextPath": ctx.get("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", ""),
@@ -1903,7 +1903,7 @@ _IMMUTABLE_INVOCATION_KEYS = (
     "workerPromptsDirectoryPath",
     "workerPromptPathByWorkerId",
     "workerResultsDirectoryPath",
-    "expectedReportPath",
+    "expectedReportRecordPath",
     "reportTemplatePath",
 )
 
@@ -2091,8 +2091,8 @@ def render_timeline(timeline_path: str, ctx: dict) -> None:
             "workerPromptPathByWorkerId": {
                 item: catalog[item]["promptPath"] for item in reviewers
             },
-            "reportPath": ctx.get("LATEST_REPORT_RELATIVE_PATH")
-            or ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+            "reportRecordPath": ctx.get("LATEST_REPORT_RECORD_RELATIVE_PATH")
+            or ctx.get("FINAL_REPORT_RECORD_RELATIVE_PATH", ""),
             "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
             "resumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
             "relatedTasks": json.loads(ctx.get("RELATED_TASKS_JSON", "[]")),
@@ -2172,7 +2172,7 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
         f"- Label: `{checkpoint.get('label', 'unknown')}`",
         f"- Run manifest: `{checkpoint.get('latestRunManifestPath', ctx.get('RUN_MANIFEST_RELATIVE_PATH', ''))}`",
         f"- Team state: `{checkpoint.get('latestTeamStatePath', ctx.get('TEAM_STATE_RELATIVE_PATH', ''))}`",
-        f"- Report: `{checkpoint.get('latestReportPath', task_manifest.get('latestReportPath', '--')) or '--'}`",
+        f"- Report: `{checkpoint.get('latestReportRecordPath', task_manifest.get('latestReportRecordPath', '--')) or '--'}`",
         f"- Resume command: `{checkpoint.get('latestResumeCommandPath', task_manifest.get('latestResumeCommandPath', '--')) or '--'}`",
     ]
     rc = (
@@ -2236,8 +2236,8 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
         "{{LATEST_RUN_RELATIVE_PATH}}": task_manifest.get(
             "latestRunPath", ctx.get("LATEST_RUN_RELATIVE_PATH", "")
         ),
-        "{{LATEST_REPORT_RELATIVE_PATH}}": task_manifest.get(
-            "latestReportPath", ctx.get("LATEST_REPORT_RELATIVE_PATH", "")
+        "{{LATEST_REPORT_RECORD_RELATIVE_PATH}}": task_manifest.get(
+            "latestReportRecordPath", ctx.get("LATEST_REPORT_RECORD_RELATIVE_PATH", "")
         ),
         "{{TEAM_STATE_RELATIVE_PATH}}": task_manifest.get(
             "teamStatePath", ctx.get("TEAM_STATE_RELATIVE_PATH", "")

package/runtime/python/okstra_ctl/report_finalize.py

@@ -338,7 +338,7 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
                 ctx.task_key,
             ],
         ),
-        (STEP_VALIDATE_RUN, _validate_run_command(ctx, markdown_path)),
+        (STEP_VALIDATE_RUN, _validate_run_command(ctx, ctx.data_path)),
         (
             STEP_TEARDOWN_STAGES,
             ["<in-process>", "teardown-stages", str(ctx.data_path)],
@@ -382,14 +382,14 @@ def _teardown_stage_worktrees(
     return _done(result)
 
 
-def _validate_run_command(ctx: FinalizeContext, markdown_path: Path) -> list[str]:
+def _validate_run_command(ctx: FinalizeContext, report_record_path: Path) -> list[str]:
     command = [
         sys.executable,
         str(resolve_workspace_validator(ctx.workspace_root, "validate-run.py")),
         "--team-state",
         str(ctx.team_state_path),
         "--report",
-        str(markdown_path),
+        str(report_record_path),
         "--run-manifest",
         str(ctx.manifest_path),
         "--task-manifest",
@@ -611,7 +611,7 @@ def _parser() -> argparse.ArgumentParser:
     parser.add_argument(
         "--report",
         required=True,
-        help="final-report markdown path (its .data.json sibling is derived)",
+        help="final-report record (.data.json); a leftover markdown path still locates the sibling record",
     )
     parser.add_argument("--workspace-root", required=True)
     parser.add_argument(

package/runtime/python/okstra_ctl/rollup.py

@@ -86,7 +86,7 @@ def _collect_task(entry: dict, project_root: Path) -> dict:
         ),
         "latestRunStatus": entry.get("latestRunStatus", ""),
         "updatedAt": entry.get("updatedAt", ""),
-        "reportPath": entry.get("latestReportPath", ""),
+        "reportPath": entry.get("latestReportRecordPath", ""),
         "runCount": len(runs),
         "cpuSumMs": time_agg["grandTotal"]["cpuSumMs"],
         "wallClockMs": sum(r["wallClockMs"] for r in time_agg["perRunWallClock"]),