okstra 0.178.0 → 0.179.0

package/runtime/python/okstra_ctl/wizard.py

@@ -119,6 +119,7 @@ from okstra_ctl.run import (
     _extract_frontmatter_block,
     _load_final_report_data_if_present,
     _assignment_resolution_message,
+    _record_approved_flag,
     _reject_blocking_plan_body_gate,
     _set_data_json_approved_true_if_present,
     _model_default_scopes,
@@ -711,7 +712,7 @@ def _planning_rerun_selected(state: WizardState) -> bool:
         path.is_file()
         and not path.is_symlink()
         and re.fullmatch(
-            r"final-report-implementation-planning-\d{3,}\.md", path.name
+            r"final-report-implementation-planning-\d{3,}\.(?:md|data\.json)", path.name
         )
         is not None
         and path.parent == reports
@@ -746,32 +747,23 @@ def _submit_selected_direction_pick(
     return f"selected-direction: {value}"
 
 
-def _data_json_approved_state(plan_path: Path) -> Optional[bool]:
-    """`approved` flag of the sibling final-report data.json (the SSOT).
-
-    Returns the bool when present, or None when there is no data.json or the
-    flag is missing / non-bool (legacy report — markdown frontmatter governs)."""
-    loaded = _load_final_report_data_if_present(plan_path)
-    if loaded is None:
-        return None
-    frontmatter = loaded[1].get("frontmatter")
-    if not isinstance(frontmatter, dict) or "approved" not in frontmatter:
-        return None
-    value = frontmatter.get("approved")
-    return value if isinstance(value, bool) else None
-
-
 def _classify_approved_plan(path_str: str, project_root: Path) -> tuple[Path, bool]:
     """Resolve the plan and classify it as fully-approved vs approvable.
 
     Returns ``(resolved_path, already_fully_approved)``. Raises WizardError ONLY
-    for failures that approval cannot fix: missing frontmatter / `approved:`
-    field, a blocking plan-body gate, an unparseable §1, or unresolved
-    `Blocks=approval` rows. A plan that is merely not-yet-approved (markdown or
-    data.json `approved: false`, gate ok, no blockers) returns
+    for failures that approval cannot fix: missing `approved` on the report
+    record (or schema-v1 frontmatter), a blocking plan-body gate, an unparseable
+    §1, or unresolved `Blocks=approval` rows. A plan that is merely
+    not-yet-approved (record `approved: false`, gate ok, no blockers) returns
     ``already_fully_approved=False`` — the approve-confirm step offers to flip it.
     """
-    p = _require_file(path_str, project_root, "approved plan")
+    from okstra_ctl.final_report_paths import require_approved_plan_record
+
+    resolved = _require_file(path_str, project_root, "approved plan")
+    try:
+        p = require_approved_plan_record(resolved)
+    except ValueError as exc:
+        raise WizardError(str(exc)) from exc
     loaded = _load_final_report_data_if_present(p)
     if loaded is not None:
         planning = loaded[1].get("implementationPlanning")
@@ -784,23 +776,9 @@ def _classify_approved_plan(path_str: str, project_root: Path) -> tuple[Path, bo
                 "direction-invalidated planning reports are not approvable; "
                 "re-enter implementation-option-selection"
             )
-    body = p.read_text(encoding="utf-8", errors="replace")
-    frontmatter = _extract_frontmatter_block(body)
-    if frontmatter is None:
-        raise WizardError(
-            f"approved plan has no YAML frontmatter block: {p}\n"
-            "  expected the report to begin with `---\\n...\\n---\\n`."
-        )
-    m = APPROVED_FRONTMATTER_PATTERN.search(frontmatter)
-    if not m:
-        raise WizardError(
-            f"approved plan frontmatter has no `approved:` field: {p}\n"
-            "  expected `approved: true` / `approved: false`. Re-render the "
-            "report if the field is missing."
-        )
     # A blocking gate or an open Blocks=approval row makes the plan UN-approvable
     # — these raise regardless of the current flag value.
-    _reject_blocking_plan_body_gate(p, body, action="approved plan validation")
+    _reject_blocking_plan_body_gate(p, "", action="approved plan validation")
     scan = scan_approval_gate(p)
     if scan.unreadable_reason:
         raise WizardError(
@@ -819,28 +797,19 @@ def _classify_approved_plan(path_str: str, project_root: Path) -> tuple[Path, bo
             lines.append(f"  - {b.row_id} (Status={b.raw_status})")
         lines.append(f"  file: {p}")
         raise WizardError("\n".join(lines))
-    markdown_approved = m.group(1).lower() == "true"
-    data_state = _data_json_approved_state(p)
-    fully_approved = markdown_approved and data_state is not False
-    return p, fully_approved
+    try:
+        record_approved = _record_approved_flag(p)
+    except PrepareError as exc:
+        raise WizardError(str(exc)) from exc
+    return p, record_approved is True
 
 
 def _approve_plan_in_place(plan_path: Path) -> None:
-    """Flip the plan to approved at the source of truth and re-render.
-
-    data.json present → `_set_data_json_approved_true_if_present` sets
-    `frontmatter.approved=true` there and re-renders the markdown from it (so
-    both agree). data.json absent (legacy) → flip the markdown frontmatter line."""
-    rendered = _set_data_json_approved_true_if_present(plan_path)
-    if rendered:
-        return
-    body = plan_path.read_text(encoding="utf-8", errors="replace")
-    flipped = APPROVED_FRONTMATTER_PATTERN.sub("approved: true", body, count=1)
-    if flipped == body:
+    """Flip the report record `frontmatter.approved` to true and re-render."""
+    if not _set_data_json_approved_true_if_present(plan_path):
         raise WizardError(
-            f"approve-plan: could not flip the markdown `approved:` line: {plan_path}"
+            f"approve-plan: report record could not be updated: {plan_path}"
         )
-    plan_path.write_text(flipped, encoding="utf-8")
 
 
 def _find_html_approval_sidecar(
@@ -864,7 +833,7 @@ def _find_html_approval_sidecar(
     responses_dir = plan_path.parent.parent / "user-responses"
     if not responses_dir.is_dir():
         return None
-    m = re.search(r"-(\d+)\.md$", plan_path.name)
+    m = re.search(r"-(\d+)\.(?:md|data\.json)$", plan_path.name)
     plan_seq = m.group(1) if m else ""
     best: Optional[tuple[float, Path, PlanDecisionRecord]] = None
     for f in sorted(responses_dir.glob("user-response-*.md")):
@@ -875,7 +844,17 @@ def _find_html_approval_sidecar(
         rec = parse_plan_decision(text)
         if rec is None or not rec.approved or rec.seq != plan_seq:
             continue
-        if Path(rec.source_report).name != plan_path.name:
+        from okstra_ctl.final_report_paths import (
+            final_report_markdown_path,
+            is_report_record_path,
+        )
+
+        expected_name = (
+            final_report_markdown_path(plan_path).name
+            if is_report_record_path(plan_path)
+            else plan_path.name
+        )
+        if Path(rec.source_report).name != expected_name:
             continue
         mtime = f.stat().st_mtime
         if best is None or mtime > best[0]:
@@ -909,10 +888,12 @@ def _validate_sidecar_option(plan_path: Path, option_name: str, errors_t: dict)
 
 def _plan_short_label(candidate: str) -> str:
     """plan 파일명에서 사용자용 짧은 식별자를 뽑는다.
-    final-report-implementation-planning-002.md → implementation-planning-002"""
+    final-report-implementation-planning-002.data.json → implementation-planning-002"""
     if not candidate:
         return ""
-    return Path(candidate).stem.removeprefix("final-report-")
+    name = Path(candidate).name
+    stem = name[: -len(".data.json")] if name.endswith(".data.json") else Path(name).stem
+    return stem.removeprefix("final-report-")
 
 
 def _stage_plan_for_confirmation(
@@ -2782,7 +2763,7 @@ def _latest_revision_requested_analysis_report(
         return None
     expected_task_key = f"{state.project_id}:{state.task_group}:{state.task_id}"
     candidates: list[tuple[int, Path]] = []
-    for report in reports.glob("final-report-*.md"):
+    for report in reports.glob("final-report-*.data.json"):
         candidate = _analysis_revision_candidate(
             state,
             report,
@@ -3498,14 +3479,11 @@ def _ensure_design_prep_queue(state: WizardState) -> None:
         return
     report_path = Path(state.approved_plan_path)
     if not re.fullmatch(
-        r"final-report-implementation-planning-\d+\.md",
+        r"final-report-implementation-planning-\d+\.data\.json",
         report_path.name,
     ):
         return
-    data_path = report_path.with_name(
-        report_path.name.removesuffix(".md") + ".data.json"
-    )
-    if not data_path.is_file():
+    if not report_path.is_file():
         return
     try:
         items = load_design_prep_items(report_path)
@@ -3976,14 +3954,14 @@ def _suggest_latest_final_report(state: WizardState) -> str:
         best = _newest_contained_final_report(
             runs_base,
             task_root,
-            f"{seg}/reports/final-report-*.md",
+            f"{seg}/reports/final-report-*.data.json",
             Path(state.project_root),
         )
     if best is None:
         best = _newest_contained_final_report(
             runs_base,
             task_root,
-            "*/reports/final-report-*.md",
+            "*/reports/final-report-*.data.json",
             Path(state.project_root),
         )
     if best is None:

package/runtime/python/okstra_ctl/worker_prompt_body.py

@@ -107,18 +107,17 @@ def report_writer_prompt_body(
         mcp_pointer_line(),
         "",
         "## Output Contract",
-        "You are the author of THREE files:",
-        "- The final-report data.json at Result Path.",
-        "- The rendered Markdown sibling produced through okstra render-final-report.",
+        "You are the author of TWO files:",
+        "- The report record (data.json) at Result Path.",
         "- The worker-result pointer at Worker Result Path.",
         (
-            "Keep the pointer to three entries: the data.json path, rendered "
-            "Markdown path, and Convergence state input path."
+            "Keep the pointer to two entries: the data.json path and the "
+            "Convergence state input path."
         ),
         "Maintain the separate audit sidecar at Audit sidecar path.",
         (
-            'After writing the data.json, invoke "okstra render-final-report '
-            '<Result Path>" so the markdown sibling is rendered before you return.'
+            "Do not invoke okstra render-final-report; the full reading copy "
+            "is on-demand."
         ),
         "Do not return the report inline.",
         "Copy Report Language verbatim into data.json.meta.reportLanguage.",

package/runtime/python/okstra_ctl/worker_runner.py

@@ -15,21 +15,19 @@ import os
 import selectors
 import signal
 import subprocess
-import sys
 import time
-from functools import partial
 from pathlib import Path
 from typing import Any, Callable, Mapping
 
 from .domain.provider import ServedModelAttestation, ServedModelNormalizer
 from .domain.worker_exec import (
     SERVED_MODEL_MISMATCH_EXIT_CODE,
-    STREAM_JSON,
     ExecCommand,
     ExecutionStrategy,
     WorkerExecRequest,
 )
-from .domain.worker_stream import Normalise, final_text, format_live, format_log
+from .domain.worker_presentation import JsonEvents, Presentation
+from .session_transcript import SessionTranscript
 
 LIVE = "live"
 QUIET = "quiet"
@@ -45,16 +43,6 @@ _READ_SIZE = 8192
 _WRITE_SIZE = 8192
 _NO_STATUS_EXTRA: Mapping[str, Any] = {}
 
-# How many progress lines reach the log copy before it starts eliding. Progress
-# is where a text CLI's bulk is — a dispatch that only reads one file already
-# puts kilobytes of tool echo on stderr, and observed sidecars reach 8MB and
-# dominate a project's `.okstra/` bytes. The cap is run-wide rather than
-# per-block because block boundaries are a provider's own vocabulary and this
-# runner has none; the cost is that a very long run keeps its opening rather
-# than a sample throughout, which the elision notices make visible.
-_LOG_PROGRESS_LINE_CAP = 5000
-_ELISION_NOTICE_EVERY = 500
-
 # The signals that end this process without raising anything Python can catch on
 # the way out. SIGINT is absent on purpose: it arrives as KeyboardInterrupt and
 # the exception path already closes the sidecar.
@@ -89,6 +77,9 @@ def run_worker(
                 idle_timeout_seconds=request.idle_timeout_seconds,
                 on_spawn=guard.watch,
             )
+            at_exit = getattr(command.presentation, "served_model_at_exit", None)
+            if raw_model is None and at_exit is not None and request.session_id:
+                raw_model = at_exit(request.session_id, command.cwd)
     except BaseException as exc:
         # Whatever ended this run — an OS error, a Ctrl-C, a bug in this file —
         # the sidecar has to stop saying `started`. Nothing downstream rewrites
@@ -179,33 +170,62 @@ def _launch(
     idle_timeout_seconds: int,
     on_spawn: Callable[[subprocess.Popen[bytes]], None],
 ) -> tuple[int, bool, int, str | None]:
-    log_path.parent.mkdir(parents=True, exist_ok=True)
-    with log_path.open("w", encoding="utf-8") as log_file:
+    live = presentation == LIVE
+    transcript = SessionTranscript(log_path, live=live)
+    observation = _ServedModelObservation()
+    strategy = _with_served_model_observation(command.presentation, observation)
+    try:
         # The strategy decided where this provider runs — some CLIs work in the
         # stage tree, others in the project root and reach the tree by flag.
         process = subprocess.Popen(
             list(command.argv),
             cwd=str(command.cwd),
-            stdin=subprocess.PIPE if command.stdin_text is not None else None,
+            # 보낼 것이 없으면 DEVNULL 이다. `None` 은 부모의 stdin 을 물려주는
+            # 것이라, stdin 을 읽는 CLI 가 터미널에서 실행됐을 때 EOF 를 못 받고
+            # 영원히 기다린다 — 워커는 대화형이 아니므로 물려줄 이유가 없다.
+            stdin=(
+                subprocess.PIPE
+                if command.stdin_text is not None
+                else subprocess.DEVNULL
+            ),
             stdout=subprocess.PIPE,
-            stderr=_stderr_target(command.stream_format),
+            stderr=_stderr_target(strategy),
             start_new_session=True,
             env=_child_env(),
         )
         on_spawn(process)
-        observation = _ServedModelObservation()
         exit_code, timed_out, idle_seconds = _pump(
             process,
-            log_file,
-            stream_format=command.stream_format,
-            normalise=command.normalise,
+            transcript,
+            strategy=strategy,
             presentation=presentation,
             idle_timeout_seconds=idle_timeout_seconds,
             stdin_text=command.stdin_text,
-            observe_served_model=command.observe_served_model,
-            model_observation=observation,
         )
         return exit_code, timed_out, idle_seconds, observation.raw_model
+    finally:
+        transcript.close()
+
+
+def _with_served_model_observation(
+    presentation: Presentation,
+    observation: _ServedModelObservation,
+) -> Presentation:
+    """JSON 경로의 서빙 모델 관측을 러너가 모아 둔다.
+
+    해석 전략은 이벤트를 보고 모델 문자열만 돌려준다. 그 값을 사이드카에
+    적는 일은 러너의 것이라, 여기서 한 번 감싼다.
+    """
+    if not isinstance(presentation, JsonEvents):
+        return presentation
+    original = presentation.observe
+
+    def observe(event: Mapping[str, Any]) -> str | None:
+        observed = original(event)
+        observation.record(observed)
+        return observed
+
+    return JsonEvents(normalise=presentation.normalise, observe=observe)
 
 
 class _ServedModelObservation:
@@ -311,39 +331,27 @@ def _started_status(status_extra: Mapping[str, Any], log_path: Path) -> dict[str
     }
 
 
-def _stderr_target(stream_format: str) -> int:
-    """Whether the child's two streams stay apart.
+def _stderr_target(presentation: Presentation) -> int:
+    """stderr 를 stdout 에 합칠지는 전략이 정한다.
 
-    A JSON-stream CLI puts events on stdout and only its own error text on
-    stderr, so folding the two loses nothing and leaves one reader. A text CLI
-    splits meaning across them — the result on stdout, progress on stderr — and
-    merging destroys the only way to tell the answer from the noise.
+    한 스트림에 진행과 결과가 함께 오는 CLI 는 합쳐 읽어야 순서가 보존되고,
+    둘을 갈라 내는 CLI 는 갈라 읽어야 답과 진행이 섞이지 않는다.
     """
-    return subprocess.STDOUT if stream_format == STREAM_JSON else subprocess.PIPE
+    return subprocess.STDOUT if presentation.merges_stderr() else subprocess.PIPE
 
 
 def _pump(
     process: subprocess.Popen[bytes],
-    log_file,
+    transcript: SessionTranscript,
     *,
-    stream_format: str,
-    normalise: Normalise,
+    strategy: Presentation,
     presentation: str,
     idle_timeout_seconds: int,
     stdin_text: str | None = None,
-    observe_served_model: Callable[[Mapping[str, Any]], str | None],
-    model_observation: _ServedModelObservation,
 ) -> tuple[int, bool, int]:
     selector = selectors.DefaultSelector()
-    readers, finalize_log = _register_output(
-        selector,
-        process,
-        log_file,
-        stream_format=stream_format,
-        normalise=normalise,
-        observe_served_model=observe_served_model,
-        model_observation=model_observation,
-        presentation=presentation,
+    readers = _register_streams(
+        selector, process, strategy, transcript, presentation == LIVE
     )
     outgoing = _register_prompt(selector, process, stdin_text)
     closing_text: str | None = None
@@ -379,23 +387,19 @@ def _pump(
 
     for reader in readers.values():
         closing_text = reader.flush() or closing_text
-    finalize_log()
 
     exit_code = process.wait()
-    if closing_text is None:
-        # A JSON stream is supposed to end in a result event. Ending without one
-        # means the CLI stopped without saying what it concluded, and the caller
-        # would otherwise read an empty stdout under `quiet` as a run that
-        # simply had nothing to report. A text CLI has no result event to miss.
-        if stream_format == STREAM_JSON:
-            print(
-                f"okstra worker: no result event in the CLI's output — "
-                f"see {log_file.name}",
-                file=sys.stderr,
-                flush=True,
-            )
-    elif presentation == QUIET:
-        print(closing_text, flush=True)
+    if closing_text is None and isinstance(strategy, JsonEvents):
+        # JSON 스트림은 결과 이벤트로 끝나야 한다. 텍스트를 흘리는 CLI 에는
+        # 놓칠 결과 이벤트가 없다.
+        transcript.note("no result event in the CLI's output")
+    elif closing_text is not None:
+        # Result 는 format_* 가 줄을 만들지 않는다. 아카이브 결론은 러너가 적는다.
+        # 상한 밖에 둔다 — 잘린 결론은 사후 분석 전체를 잃게 한다.
+        if isinstance(strategy, JsonEvents):
+            transcript.write("worker", closing_text, capped=False)
+        if presentation == QUIET:
+            print(closing_text, flush=True)
     return (_TIMEOUT_EXIT_CODE if timed_out else exit_code), timed_out, idle_seconds
 
 
@@ -432,55 +436,23 @@ def _stop_reading(selector: selectors.BaseSelector) -> None:
         selector.unregister(key.fileobj)
 
 
-def _register_output(
+def _register_streams(
     selector: selectors.BaseSelector,
     process: subprocess.Popen[bytes],
-    log_file,
-    *,
-    stream_format: str,
-    normalise: Normalise,
-    observe_served_model: Callable[[Mapping[str, Any]], str | None],
-    model_observation: _ServedModelObservation,
-    presentation: str,
-) -> tuple[dict[int, _LineReader], Callable[[], None]]:
-    """Register every stream this child speaks, each with its own destination.
-
-    Returns the readers plus the finalizer a capped sink needs to report what it
-    dropped once the streams are done. A JSON stream caps nothing.
-    """
+    presentation: Presentation,
+    transcript: SessionTranscript,
+    live: bool,
+) -> dict[int, _LineReader]:
+    """이 자식이 말하는 스트림마다 전략이 지정한 싱크를 붙인다."""
     assert process.stdout is not None
-    if stream_format == STREAM_JSON:
-        sinks = [
-            (
-                process.stdout,
-                partial(
-                    _emit_event,
-                    log_file,
-                    presentation,
-                    normalise,
-                    observe_served_model,
-                    model_observation,
-                ),
-            )
-        ]
-        finalize_log: Callable[[], None] = _nothing_to_finalize
-    else:
-        assert process.stderr is not None
-        progress = _ProgressSink(log_file, presentation)
-        sinks = [
-            (process.stdout, partial(_emit_result, log_file)),
-            (process.stderr, progress),
-        ]
-        finalize_log = progress.report_elided
+    streams = {"stdout": process.stdout, "stderr": process.stderr}
     readers: dict[int, _LineReader] = {}
-    for stream, emit in sinks:
+    for channel, sink in presentation.sinks(transcript, live):
+        stream = streams[channel]
+        assert stream is not None, channel
         selector.register(stream, selectors.EVENT_READ)
-        readers[stream.fileno()] = _LineReader(emit)
-    return readers, finalize_log
-
-
-def _nothing_to_finalize() -> None:
-    """A JSON stream elides nothing, so it has nothing to report at the end."""
+        readers[stream.fileno()] = _LineReader(sink)
+    return readers
 
 
 class _LineReader:
@@ -557,109 +529,6 @@ def _close_prompt(selector: selectors.BaseSelector, key: selectors.SelectorKey)
     key.fileobj.close()
 
 
-def _emit_result(log_file, line: str) -> None:
-    """A text CLI's stdout is its answer, so the caller gets it in either mode.
-
-    ``quiet`` withholds progress, not the result — and unlike a JSON stream
-    there is no result event to hold back and print at the end, so the answer
-    passes through as it arrives.
-    """
-    _write_log(log_file, [line])
-    print(line, flush=True)
-
-
-class _ProgressSink:
-    """A text CLI's stderr: shown live, archived up to a cap.
-
-    Progress goes to this process's stderr rather than its stdout so the
-    caller's stdout stays the result alone. A pane shows both, and a pane is
-    exactly where ``live`` lands.
-
-    Only the log copy is capped, never the screen and never the result stream.
-    That asymmetry is the point: a truncated tool echo costs detail, while a
-    truncated answer costs the whole post-mortem — and the caller's streams are
-    read by a person or a subagent that was promised the CLI's output verbatim.
-    """
-
-    def __init__(self, log_file, presentation: str) -> None:
-        self._log_file = log_file
-        self._presentation = presentation
-        self._archived = 0
-        self._elided = 0
-
-    def __call__(self, line: str) -> None:
-        if self._presentation == LIVE:
-            print(line, file=sys.stderr, flush=True)
-        if self._archived < _LOG_PROGRESS_LINE_CAP:
-            self._archived += 1
-            _write_log(self._log_file, [line])
-            return
-        self._elided += 1
-        # Periodic rather than only at the end: a reader tailing the log has to
-        # see that the run is still producing progress, not a file that stopped.
-        if self._elided % _ELISION_NOTICE_EVERY == 0:
-            self._note_elision()
-
-    def report_elided(self) -> None:
-        """Close the archive with the exact total, if the last notice missed some."""
-        if self._elided % _ELISION_NOTICE_EVERY:
-            self._note_elision()
-
-    def _note_elision(self) -> None:
-        _write_log(
-            self._log_file,
-            [f"  [okstra log-cap] {self._elided} progress line(s) elided"],
-        )
-
-
-def _emit_event(
-    log_file,
-    presentation: str,
-    normalise: Normalise,
-    observe_served_model: Callable[[Mapping[str, Any]], str | None],
-    model_observation: _ServedModelObservation,
-    line: str,
-) -> str | None:
-    """Write one line of a JSON stream out; return closing text if this is it.
-
-    The provider's own wire shape gets no further than ``normalise`` — what
-    reaches the projections is the normalised vocabulary, which is the only
-    thing this runner and the formatter are allowed to know.
-    """
-    stripped = line.strip()
-    if not stripped:
-        return None
-    try:
-        event = json.loads(stripped)
-    except ValueError:
-        # Not an event. The CLI's stderr is folded into this stream, so this is
-        # where its own error text arrives — the caller has to see it, and the
-        # archive alone does not show it to anyone. stderr rather than stdout so
-        # it reaches the caller without posing as progress, in either mode.
-        _write_log(log_file, [stripped])
-        print(stripped, file=sys.stderr, flush=True)
-        return None
-    if not isinstance(event, dict):
-        return None
-    model_observation.record(observe_served_model(event))
-
-    closing: str | None = None
-    for entry in normalise(event):
-        _write_log(log_file, format_log(entry))
-        if presentation == LIVE:
-            for row in format_live(entry):
-                print(row, flush=True)
-        text = final_text(entry)
-        if text is not None:
-            closing = text
-    if closing is not None:
-        # Whatever the presentation, the archive ends with the worker's own
-        # conclusion — otherwise it stops at the last tool call and the reader
-        # never learns what the run decided.
-        _write_log(log_file, closing.splitlines())
-    return closing
-
-
 def _attestation_payload(attestation: ServedModelAttestation) -> dict[str, Any]:
     return {
         "observedModel": attestation.observed_model,
@@ -669,12 +538,6 @@ def _attestation_payload(attestation: ServedModelAttestation) -> dict[str, Any]:
     }
 
 
-def _write_log(log_file, lines) -> None:
-    for line in lines:
-        log_file.write(line + "\n")
-    log_file.flush()
-
-
 def _terminate(process: subprocess.Popen[bytes]) -> None:
     """SIGTERM the worker's process group, then SIGKILL whatever survives.
 

package/runtime/python/okstra_ctl/workflow.py

@@ -102,7 +102,7 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - bite-sized stepwise execution order for the selected direction or legacy recommended option (each step ~2-5 min, exact file paths and commands, TDD ordering when applicable, no placeholders)\n"
             "  - dependency / migration risk assessment, validation checklist (pre / mid / post with exact commands), rollback strategy with revert path and trigger signal\n"
             "  - every unresolved ambiguity registered as a `Blocks=approval` row in the `## 1. Clarification Items` table (do NOT create a separate `Open Questions` block under `5.5.x` — the unified table is the single home)\n"
-            "  - YAML frontmatter line `approved: false` awaiting human flip to `true`\n"
+            "  - report record `frontmatter.approved: false` awaiting `--approve` or the in-session wizard\n"
             "  - self-review confirmation (spec coverage, placeholder scan, internal consistency, ambiguity, scope)\n"
             "  - one endStateCoverage row per brief end-state id, each mapped to the R-NNN row that carries it"
         ),

package/runtime/python/okstra_ctl/wrapper_status.py

@@ -40,6 +40,29 @@ def log_path_for_prompt(prompt_path: Path) -> Path:
     return Path(f"{prompt_path}.log")
 
 
+def mutation_snapshot_path_for_prompt(prompt_path: Path) -> Path:
+    """Where okstra writes this prompt's pre-dispatch mutation snapshot."""
+    return prompt_path.with_suffix(prompt_path.suffix + ".mutation-audit.json")
+
+
+def prompt_derived_paths(prompt_path: Path) -> tuple[Path, ...]:
+    """The three files okstra writes beside a prompt: status, log, snapshot.
+
+    They are written together and must be authorised together. Listing them by
+    hand let the two sides drift: dispatch added the snapshot to its write
+    policy while `agent-prompt materialize` kept its own five-path list, so the
+    two policies hashed differently and `record_invocation_attempt` refused
+    every dynamically materialized invocation as `invocationRef drift` — which
+    took Phase 5.5 reverify with it. One function, so a fourth derived file
+    cannot reach one caller and miss the other.
+    """
+    return (
+        status_path_for_prompt(prompt_path),
+        log_path_for_prompt(prompt_path),
+        mutation_snapshot_path_for_prompt(prompt_path),
+    )
+
+
 def read_wrapper_status(path: Path) -> WrapperStatus | None:
     try:
         raw = json.loads(path.read_text(encoding="utf-8"))