okstra 0.178.0 → 0.179.1

package/runtime/python/okstra_ctl/final_report_paths.py

@@ -14,9 +14,46 @@ def _stem(data_path: Path) -> str:
     return name[: -len(DATA_JSON_SUFFIX)] if name.endswith(DATA_JSON_SUFFIX) else data_path.stem
 
 
+def require_approved_plan_record(path: Path) -> Path:
+    """`--approved-plan` accepts the report record only.
+
+    A full reading copy (`.md`) is rejected with the sibling record path.
+    Schema-v1 plans have no record and cannot enter this gate.
+    """
+    resolved = Path(path)
+    if is_full_reading_copy_path(resolved):
+        suggested = final_report_data_path(resolved)
+        raise ValueError(
+            f"--approved-plan must be the report record (.data.json), not the "
+            f"full reading copy: {path}\n"
+            "  schema-v1 plans have no record and cannot be used here.\n"
+            f"  for a schema-v2 plan use: {suggested}"
+        )
+    if not is_report_record_path(resolved):
+        raise ValueError(
+            f"--approved-plan must be a report record ending in .data.json: {path}"
+        )
+    if not resolved.is_file():
+        raise ValueError(f"approved plan record not found: {path}")
+    return resolved
+
+
+def is_report_record_path(path: Path) -> bool:
+    return path.name.endswith(DATA_JSON_SUFFIX)
+
+
+def is_full_reading_copy_path(path: Path) -> bool:
+    return path.name.endswith(MARKDOWN_SUFFIX)
+
+
 def final_report_data_path(report_path: Path) -> Path:
-    """Return the data.json sibling for a final-report markdown path."""
+    """Return the report record path for a final-report pair.
+
+    Already a `.data.json` path is returned unchanged.
+    """
     name = report_path.name
+    if name.endswith(DATA_JSON_SUFFIX):
+        return report_path
     if name.endswith(MARKDOWN_SUFFIX):
         return report_path.with_name(name[: -len(MARKDOWN_SUFFIX)] + DATA_JSON_SUFFIX)
     return report_path.with_suffix(DATA_JSON_SUFFIX)
@@ -30,6 +67,45 @@ def final_report_markdown_path(data_path: Path) -> Path:
     return data_path.with_suffix(MARKDOWN_SUFFIX)
 
 
+def report_record_rel_from_legacy_pointer(relative: str) -> str:
+    """Turn a stored pointer into a report-record relative path.
+
+    New rows store the record. Rows written before that stored the full
+    reading copy (`.md`); the record is the sibling `.data.json`.
+    """
+    relative = str(relative or "")
+    if not relative:
+        return ""
+    path = Path(relative)
+    if is_report_record_path(path):
+        return relative
+    return str(final_report_data_path(path))
+
+
+def index_report_record_rel(row: dict) -> str:
+    """Report-record pointer from a run-index row.
+
+    New rows use `finalReportRecordRel`. Older rows used `finalReportRel`
+    for the full reading copy.
+    """
+    current = str(row.get("finalReportRecordRel") or "")
+    if current:
+        return current
+    return report_record_rel_from_legacy_pointer(str(row.get("finalReportRel") or ""))
+
+
+def timeline_report_record_rel(run: dict) -> str:
+    """Report-record pointer from a timeline / recap run entry.
+
+    New entries use `reportRecordPath`. Older entries used `reportPath`
+    for the full reading copy.
+    """
+    current = str(run.get("reportRecordPath") or "")
+    if current:
+        return current
+    return report_record_rel_from_legacy_pointer(str(run.get("reportPath") or ""))
+
+
 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)

package/runtime/python/okstra_ctl/handoff.py

@@ -81,8 +81,7 @@ def latest_whole_task_fv_release_ready(project_root, project_id: str,
         if ((data.get("header") or {}).get("taskType") == "final-verification"
                 and data.get("verificationScope") == "whole-task"
                 and release_handoff_allowed(data)):
-            md = final_report_markdown_path(dj)
-            return str(md if md.is_file() else dj)
+            return str(dj)
     return ""
 
 

package/runtime/python/okstra_ctl/implementation_outcome.py

@@ -212,7 +212,7 @@ def _update_task_catalog(project_root: Path, manifest: dict[str, Any]) -> bool:
         entry["nextRecommendedPhase"] = next_phase.promote(
             workflow.get("nextRecommendedPhase")
         )
-        entry["latestReportPath"] = manifest.get("latestReportPath", "")
+        entry["latestReportRecordPath"] = manifest.get("latestReportRecordPath", "")
         entry["latestRunStatus"] = manifest.get("latestRunStatus", entry.get("latestRunStatus", ""))
         entry["currentStatus"] = manifest.get("currentStatus", entry.get("currentStatus", ""))
         entry["phaseOutcome"] = outcome

package/runtime/python/okstra_ctl/index.py

@@ -33,7 +33,7 @@ def _replace_or_append_row(path: Path, run_id: str, row: dict) -> None:
 def record_start(home: Path, *, project_id: str, project_root: str,
                  task_group: str, task_id: str, task_type: str,
                  run_seq: int, when: str, workers: list, lead_model: str,
-                 run_dir_rel: str, final_report_rel: str,
+                 run_dir_rel: str, final_report_record_rel: str,
                  argv: list, cwd: str,
                  env_overrides: dict,
                  okstra_version: str = "",
@@ -55,7 +55,7 @@ def record_start(home: Path, *, project_id: str, project_root: str,
         run_seq=run_seq, status=initial_status, started_at=when,
         finished_at=when if is_terminal else None,
         workers=workers, lead_model=lead_model, validation="not-run",
-        run_dir_rel=run_dir_rel, final_report_rel=final_report_rel,
+        run_dir_rel=run_dir_rel, final_report_record_rel=final_report_record_rel,
         final_status_rel=final_status_rel,
         execution_manifest_path=execution_manifest_path,
         role_execution_refs=role_execution_refs)
@@ -115,7 +115,7 @@ def reserve_run_in_active(home: Path, *,
                           project_id: str, project_root: str,
                           task_group: str, task_id: str, task_type: str,
                           run_seq: int, when: str,
-                          run_dir_rel: str, final_report_rel: str,
+                          run_dir_rel: str, final_report_record_rel: str,
                           final_status_rel: str = "") -> None:
     """예약 row 를 active.jsonl 에 즉시 기록한다. 중앙 락 보호 필수.
     record_start 가 나중에 같은 (project, group, task, task_type, seq) 를 만나면
@@ -126,7 +126,7 @@ def reserve_run_in_active(home: Path, *,
         task_group=task_group, task_id=task_id, task_type=task_type,
         run_seq=run_seq, status="reserving", started_at=when,
         finished_at=None, workers=[], lead_model="", validation="not-run",
-        run_dir_rel=run_dir_rel, final_report_rel=final_report_rel,
+        run_dir_rel=run_dir_rel, final_report_record_rel=final_report_record_rel,
         final_status_rel=final_status_rel)
     append_jsonl(home / "active.jsonl", row)
     # project index 도 미리 한 줄 — record_start 가 나중에 update 하므로 동일 row 형태로.

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:
@@ -374,16 +377,22 @@ def container_paths(project_root: Path, task_group: str, task_id: str) -> dict:
 
 
 def next_run_seq(run_seq_dir: Path, task_type_segment: str) -> int:
-    """run_seq_dir 안에서 `*-<task-type>-NNN.<ext>` 파일을 스캔해 다음 seq 번호를
+    """run_seq_dir 안에서 `*-<task-type>-NNN[.<ext>]` 항목을 스캔해 다음 seq 번호를
     돌려준다. 디렉터리 부재 시 1.
+
+    파일과 디렉터리를 함께 센다. 이 카운터가 배정하는 자리 중 하나는
+    `prompts/duty-contracts-<task-type>-NNN/` 이라는 **디렉터리**다(확장자도 없다).
+    파일만 세면 중단된 prepare 가 남긴 그 디렉터리가 카운터에 안 잡히고, 다음 런이
+    같은 seq 를 배정받아 남은 스냅샷 위에 착지한다. digest 가 다르면
+    `run._snapshot_duty_catalog` 이 매번 같은 자리에서 PrepareError 를 내므로,
+    잔재를 손으로 치우기 전까지 그 task 의 prepare 가 영구히 막힌다.
     """
-    pattern = re.compile(rf"-{re.escape(task_type_segment)}-(\d{{3,}})\.[^.]+$")
+    pattern = re.compile(
+        rf"-{re.escape(task_type_segment)}-(\d{{3,}})(?:\.[^.]+)?$"
+    )
     max_seq = 0
     if run_seq_dir.is_dir():
         for entry in os.listdir(run_seq_dir):
-            full = run_seq_dir / entry
-            if not full.is_file():
-                continue
             m = pattern.search(entry)
             if m:
                 n = int(m.group(1))
@@ -404,7 +413,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 +547,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 +721,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", "")