okstra 0.178.0 → 0.179.0

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import json
+import re
 import subprocess
 import time
 from dataclasses import dataclass, field, replace
@@ -110,6 +111,8 @@ from .worker_prompt_headers import (
 from .worker_artifact_paths import audit_sidecar_rel
 from .wrapper_status import (
     log_path_for_prompt,
+    mutation_snapshot_path_for_prompt,
+    prompt_derived_paths,
     read_wrapper_status,
     status_path_for_prompt,
 )
@@ -1462,7 +1465,7 @@ def _mutation_snapshot(
 
 
 def _mutation_snapshot_path(job: WorkerJob) -> Path:
-    return job.prompt_path.with_suffix(job.prompt_path.suffix + ".mutation-audit.json")
+    return mutation_snapshot_path_for_prompt(job.prompt_path)
 
 
 def _record_execution_attempt(plan: DispatchPlan, job: WorkerJob) -> None:
@@ -1517,6 +1520,11 @@ def _canonical_write_contract(
         raise DispatchError("worker write policy has no runner write capability")
     artifacts = _worker_artifact_paths(plan, job)
     worktree = Path(job.worktree_path) if job.worktree_path else None
+    planned = (
+        planned_paths_from_run_manifest(plan.project_root, plan.manifest)
+        if execution.role == "implementer"
+        else ((), True)
+    )
     try:
         return build_invocation_write_contract(
             role=execution.role,
@@ -1524,11 +1532,8 @@ def _canonical_write_contract(
             worktree=worktree,
             artifact_paths=artifacts,
             maximum_precision=capability.max_boundary_precision,
-            planned_paths=(
-                planned_paths_from_run_manifest(plan.project_root, plan.manifest)
-                if execution.role == "implementer"
-                else ()
-            ),
+            planned_paths=planned[0],
+            planned_paths_declared=planned[1],
             auxiliary_roots=verifier_extra_dirs(execution.role),
             validated_auxiliary_roots=verifier_extra_dirs(execution.role),
         )
@@ -1545,14 +1550,12 @@ def _worker_artifact_paths(plan: DispatchPlan, job: WorkerJob) -> tuple[Path, ..
         job.worker_result_path,
         *job.completion_paths,
         Path(audit_sidecar_rel(str(job.worker_result_path))),
-        status_path_for_prompt(job.prompt_path),
-        log_path_for_prompt(job.prompt_path),
         # The prompt's three derived files are written together and belong in
         # one list. The audit snapshot used to be listed only for the job whose
         # snapshot it was, so a sibling's snapshot — written by okstra as that
         # sibling started — landed inside this worker's window as an
         # unauthorized artifact-root change.
-        _mutation_snapshot_path(job),
+        *prompt_derived_paths(job.prompt_path),
     }
     error_logs = active_context.get("errorLogs")
     if isinstance(error_logs, Mapping):
@@ -1914,8 +1917,41 @@ def _audit_attempt(
     )
 
 
+def _declared_out_of_plan_paths(result_path: Path) -> tuple[str, ...]:
+    """워커가 자기 결과의 `Out-of-plan edits` 블록에 선언한 경로.
+
+    감사는 워커가 끝나는 시점에 돈다. 그때 디스크에 있는 것은 워커 결과
+    마크다운뿐이고, `implementation.outOfPlanEdits` 는 리드가 나중에 쓰는 최종
+    리포트의 필드다. JSON 형태만 읽었기 때문에 executor 의 선언이 한 번도 보이지
+    않았고, 계약대로 선언한 편집까지 미허가 변경으로 집계됐다. 블록의 형태는 이
+    판독기를 위해 `_implementation-executor.md` 가 고정한다 — `- ` 줄마다 첫 백틱
+    토큰이 경로다.
+    """
+    if not result_path.is_file() or result_path.suffix != ".md":
+        return ()
+    try:
+        text = result_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError):
+        return ()
+    paths: list[str] = []
+    inside = False
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("#"):
+            inside = stripped.lstrip("#").strip().lower() == "out-of-plan edits"
+            continue
+        if not inside or not stripped.startswith("- "):
+            continue
+        quoted = re.findall(r"`([^`\n]+)`", stripped)
+        if quoted and quoted[0].strip():
+            paths.append(quoted[0].strip())
+    return tuple(paths)
+
+
 def _out_of_plan_edit_paths(result_path: Path) -> tuple[str, ...]:
-    if not result_path.is_file() or result_path.suffix != ".json":
+    if result_path.suffix != ".json":
+        return _declared_out_of_plan_paths(result_path)
+    if not result_path.is_file():
         return ()
     try:
         payload = json.loads(result_path.read_text(encoding="utf-8"))
@@ -2917,7 +2953,7 @@ def _reject_stale_schema_excerpt(
     )
     if writer is None:
         return
-    expected = _string_value(manifest.get("expectedReportPath"))
+    expected = _string_value(manifest.get("expectedReportRecordPath"))
     if not expected:
         return
     excerpt_path = bundle_excerpt_path(_resolve_project_path(project_root, expected))

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -46,10 +46,7 @@ from .execution_manifest import (
     record_invocation_attempt,
 )
 from .execution_mutation_audit import ExecutionMutationAudit, MutationSnapshot
-from .final_report_paths import (
-    final_report_data_path,
-    final_report_markdown_path,
-)
+from .final_report_paths import final_report_data_path
 from .worker_prompt_body import REPORT_WRITER_WORKER_ID
 from .worker_prompt_contract import (
     PromptRecord,
@@ -59,7 +56,11 @@ from .worker_prompt_contract import (
 from .worker_runner import LIVE, QUIET
 from .worker_request import verifier_extra_dirs
 from .worker_artifact_paths import audit_sidecar_rel
-from .wrapper_status import log_path_for_prompt, status_path_for_prompt
+from .wrapper_status import (
+    log_path_for_prompt,
+    prompt_derived_paths,
+    status_path_for_prompt,
+)
 from .write_policy import (
     build_invocation_write_contract,
     planned_paths_from_run_manifest,
@@ -812,6 +813,11 @@ def _agent_write_contract(
         maximum_precision = capability.max_boundary_precision
     else:
         raise DispatchError("agent write policy has no runner capability")
+    planned = (
+        planned_paths_from_run_manifest(project_root, authority)
+        if execution.role == "implementer"
+        else ((), True)
+    )
     try:
         return build_invocation_write_contract(
             role=execution.role,
@@ -819,11 +825,8 @@ def _agent_write_contract(
             worktree=worktree,
             artifact_paths=artifacts,
             maximum_precision=maximum_precision,
-            planned_paths=(
-                planned_paths_from_run_manifest(project_root, authority)
-                if execution.role == "implementer"
-                else ()
-            ),
+            planned_paths=planned[0],
+            planned_paths_declared=planned[1],
             auxiliary_roots=verifier_extra_dirs(execution.role),
             validated_auxiliary_roots=verifier_extra_dirs(execution.role),
         )
@@ -927,8 +930,7 @@ def _prompt_write_paths(
     artifacts = {
         _project_or_absolute(project_root, value) for value in artifact_values
     }
-    artifacts.add(status_path_for_prompt(prompt_path))
-    artifacts.add(log_path_for_prompt(prompt_path))
+    artifacts.update(prompt_derived_paths(prompt_path))
     worktree_value = values.get("Worktree")
     worktree = (
         _project_or_absolute(project_root, worktree_value)
@@ -1467,7 +1469,7 @@ def dispatch_result_path(
     if worker_id != REPORT_WRITER_WORKER_ID:
         return worker_result_path
     return final_report_data_path(
-        resolve_required_path(project_root, manifest, "expectedReportPath")
+        resolve_required_path(project_root, manifest, "expectedReportRecordPath")
     )
 
 
@@ -1479,17 +1481,16 @@ def dispatch_completion_paths(
 ) -> tuple[Path, ...]:
     """Every artifact that must exist before this worker counts as done.
 
-    The report writer's three are the data.json, its rendered Markdown sibling,
-    and the worker-result pointer (`prompts/lead/report-writer.md` §"Completion
-    detection"). Same reason as `dispatch_result_path`: both constructors need
-    the same answer.
+    The report writer's two are the report record and the worker-result
+    pointer. The full reading copy is rendered on demand and is not a
+    completion artifact.
     """
     if worker_id != REPORT_WRITER_WORKER_ID:
         return (worker_result_path,)
     data_json = final_report_data_path(
-        resolve_required_path(project_root, manifest, "expectedReportPath")
+        resolve_required_path(project_root, manifest, "expectedReportRecordPath")
     )
-    return (data_json, final_report_markdown_path(data_json), worker_result_path)
+    return (data_json, worker_result_path)
 
 
 def validate_initial_prompts(

package/runtime/python/okstra_ctl/domain/worker_exec.py

@@ -7,30 +7,16 @@ regardless of provider — see ``ExecutionPolicy``.
 """
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from pathlib import Path
-from collections.abc import Callable, Mapping
-from typing import Any, Literal, Protocol, runtime_checkable
+from typing import Literal, Protocol, runtime_checkable
 
-from .worker_stream import Normalise, no_events
+from .worker_presentation import Presentation
 from ..write_policy import WriteEnforcement, WritePolicy
 
-# What ``ExecCommand.stream_format`` may hold. The value decides whether the
-# runner pipes the CLI's output through the stream formatter or forwards it
-# unchanged, so it is part of the contract rather than a display hint.
-STREAM_JSON = "stream-json"
-TEXT = "text"
 SERVED_MODEL_MISMATCH_EXIT_CODE = 78
 
 
-def no_model_observation(_event: Mapping[str, Any]) -> str | None:
-    """Truthful default for provider output that exposes no model identity."""
-    return None
-
-
-ObserveServedModel = Callable[[Mapping[str, Any]], str | None]
-
-
 @dataclass(frozen=True)
 class ExecutionPolicy:
     """How a non-interactive worker is allowed to act.
@@ -75,31 +61,24 @@ class WorkerExecRequest:
 
 @dataclass(frozen=True)
 class ExecCommand:
-    """One provider invocation, fully resolved.
+    """공급자 호출 하나, 완전히 해소된 상태.
 
-    ``stdin_text`` is None when the provider takes its prompt as an argument
-    rather than on stdin.
+    ``stdin_text`` 는 프롬프트를 인자로 받는 CLI 에서 None 이다.
 
-    ``cwd`` is part of the contract because it is not derivable from the argv:
-    some CLIs name their working directory in a flag, others inherit the
-    process's, and the two groups do not choose the same directory. A runner
-    that had to re-derive it would be guessing at what the strategy already
-    decided.
+    ``cwd`` 가 계약에 있는 이유는 argv 에서 유도할 수 없기 때문이다 — 어떤
+    CLI 는 작업 디렉터리를 플래그로 받고 어떤 CLI 는 프로세스의 것을 물려받는데,
+    두 무리가 같은 디렉터리를 고르지 않는다.
 
-    ``normalise`` is the companion of ``stream_format``: declaring a JSON stream
-    without saying how to read it is what left one provider's pane blank for a
-    whole run. The two are named together so a provider whose events are shaped
-    differently cannot be silently handed a formatter that cannot see them.
+    ``presentation`` 은 이 CLI 의 출력을 무엇으로 볼 것인가를 정한다. 스트림
+    형식을 따로 선언하고 읽는 법을 나중에 붙이던 구조에서는, 형식만 선언하고
+    읽는 법이 어긋난 공급자의 화면이 런 내내 비어 있었다. 둘을 한 값으로 묶어
+    그 상태를 표현 불가능하게 만든다.
     """
 
     argv: tuple[str, ...]
     stdin_text: str | None
-    stream_format: str
     cwd: Path
-    normalise: Normalise = field(default=no_events)
-    observe_served_model: ObserveServedModel = field(
-        default=no_model_observation
-    )
+    presentation: Presentation
 
 
 @dataclass(frozen=True)

package/runtime/python/okstra_ctl/domain/worker_presentation.py

@@ -0,0 +1,128 @@
+"""워커 출력의 표현 전략.
+
+공급자 CLI 는 저마다 다른 것을 뱉는다 — 사람이 읽는 텍스트를 흘리는 CLI 도
+있고, 자기 어휘의 JSON 을 흘리는 CLI 도 있다. okstra 가 그 형식을 알아야만
+화면이 나오는 구조에서는 공급자가 형식을 바꿀 때마다 화면이 조용히 빈다.
+그래서 "해석하지 않는다" 를 1급 선택지로 둔다.
+
+전략은 두 가지를 답한다. stderr 를 stdout 에 합칠 것인가, 그리고 각 스트림의
+줄을 누가 받는가. 둘을 함께 두는 이유는 배치와 해석이 짝이기 때문이다 —
+JSON 을 요청하면 한 스트림으로 합쳐 읽어야 하고, 결과와 진행을 나눠 내는
+CLI 는 갈라 읽어야 한다.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Literal, Mapping, Protocol, runtime_checkable
+
+from .worker_stream import (
+    Normalise,
+    final_text,
+    format_live,
+    format_log,
+)
+
+Sink = Callable[[str], str | None]
+Channel = Literal["stdout", "stderr"]
+SinkSpec = tuple[Channel, Sink]
+ObserveServedModel = Callable[[Mapping[str, Any]], str | None]
+
+WORKER = "worker"
+
+
+class TranscriptWriter(Protocol):
+    """세션 기록에 한 줄을 남긴다. 화면 출력도 이 구현이 함께 맡는다."""
+
+    def write(self, speaker: str, line: str) -> None: ...
+
+
+@runtime_checkable
+class Presentation(Protocol):
+    def merges_stderr(self) -> bool: ...
+
+    def sinks(self, writer: TranscriptWriter, live: bool) -> tuple[SinkSpec, ...]: ...
+
+
+@dataclass(frozen=True)
+class MergedText:
+    """CLI 가 사람에게 보여주는 출력을 그대로 흘린다.
+
+    한 스트림에 진행과 결과가 함께 온다. 해석하지 않으므로 공급자가 형식을
+    바꿔도 화면이 깨지지 않는다.
+    """
+
+    served_model_at_exit: Callable[[str, Path], str | None] | None = None
+
+    def merges_stderr(self) -> bool:
+        return True
+
+    def sinks(self, writer: TranscriptWriter, live: bool) -> tuple[SinkSpec, ...]:
+        def emit(line: str) -> str | None:
+            writer.write(WORKER, line)
+            return line
+
+        return (("stdout", emit),)
+
+
+@dataclass(frozen=True)
+class SplitText:
+    """결과와 진행을 다른 스트림으로 내는 CLI.
+
+    stdout 은 답이고 stderr 는 진행이다. 답은 어느 모드에서도 호출자에게
+    가야 하므로 종결 텍스트로 돌려주고, 진행은 기록과 화면에만 남는다.
+    """
+
+    def merges_stderr(self) -> bool:
+        return False
+
+    def sinks(self, writer: TranscriptWriter, live: bool) -> tuple[SinkSpec, ...]:
+        def result(line: str) -> str | None:
+            writer.write(WORKER, line)
+            return line
+
+        def progress(line: str) -> str | None:
+            writer.write(WORKER, line)
+            return None
+
+        return (("stdout", result), ("stderr", progress))
+
+
+@dataclass(frozen=True)
+class JsonEvents:
+    """공급자 어휘의 JSON 을 공통 이벤트로 옮겨 적는다.
+
+    사람이 읽는 출력에 진행이 없는 CLI 를 위한 경로다. 어휘를 아는 대가로
+    도구 호출을 구조로 보여줄 수 있다.
+    """
+
+    normalise: Normalise
+    observe: ObserveServedModel
+
+    def merges_stderr(self) -> bool:
+        return True
+
+    def sinks(self, writer: TranscriptWriter, live: bool) -> tuple[SinkSpec, ...]:
+        def emit(line: str) -> str | None:
+            stripped = line.strip()
+            if not stripped:
+                return None
+            try:
+                event = json.loads(stripped)
+            except ValueError:
+                # 이벤트가 아니다. CLI 자신의 오류 텍스트가 이 스트림으로
+                # 오므로 삼키면 아무도 못 본다.
+                writer.write(WORKER, stripped)
+                return None
+            if not isinstance(event, dict):
+                return None
+            self.observe(event)
+            closing: str | None = None
+            for entry in self.normalise(event):
+                for row in (format_live(entry) if live else format_log(entry)):
+                    writer.write(WORKER, row)
+                closing = final_text(entry) or closing
+            return closing
+
+        return (("stdout", emit),)

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -571,6 +571,11 @@ def _git_policy_failures(
     if not _is_ancestor(root, str(git.get("expectedBaseCommit")), str(after.git_projection.get("head"))):
         failures.append("final HEAD is not a fast-forward descendant")
     allowed = set(policy.source_policy.get("plannedPaths", ())) | set(out_of_plan_edits)
+    if policy.source_policy.get("plannedPathsDeclared") is False:
+        # The plan predates the declared path column, so `allowed` was derived
+        # from prose and is not a ledger anyone can be held to. Every other
+        # check above still applies; only the path comparison stands down.
+        return failures
     if any(
         not paths <= allowed
         for paths in _commit_paths_by_commit(

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 형태로.