okstra 0.129.0 → 0.130.0

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -24,8 +24,19 @@ from .final_report_paths import (
 )
 from .lead_events import LeadEvent, append_lead_event
 from .path_hints import hydrate_active_run_context
+from .report_finalize import (
+    STEP_VALIDATE_RUN,
+    FinalizeContext,
+    FinalizeError,
+    project_relative_path as _project_relative_path,
+    require_string as _require_string,
+    resolve_optional_path as _resolve_optional_path,
+    resolve_project_path as _resolve_project_path,
+    run_finalize,
+    run_seq as _run_seq,
+    string_value as _string_value,
+)
 from .wrapper_status import status_path_for_prompt
-from .paths import task_dir
 from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
 from .worker_prompt_contract import PromptRecord, validate_initial_prompt_records
 from .worker_prompt_body import (
@@ -348,8 +359,6 @@ def _worker_dispatch_record(
     }
 
 
-
-
 def main(argv: Sequence[str] | None = None) -> int:
     parser = _parser()
     args = parser.parse_args(argv)
@@ -371,7 +380,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         code = dispatch_plan(plan)
         _print_json({**plan.to_payload(dry_run=False), "exitCode": code})
         return code
-    except DispatchError as exc:
+    except (DispatchError, FinalizeError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2
 
@@ -820,13 +829,6 @@ def _implementation_executor_tail(
     return "\n\n".join(parts)
 
 
-def _project_relative_path(project_root: Path, path: Path) -> str:
-    try:
-        return path.relative_to(project_root).as_posix()
-    except ValueError:
-        return str(path)
-
-
 def _resolve_report_language(
     project_root: Path,
     manifest: Mapping[str, Any],
@@ -875,12 +877,6 @@ def _infer_report_language(
     return "ko" if hangul_count >= 10 else "en"
 
 
-def _string_value(value: Any) -> str:
-    if not isinstance(value, str):
-        return ""
-    return value.strip()
-
-
 def _validate_codex_manifest(manifest: Mapping[str, Any], path: Path) -> None:
     if manifest.get("leadRuntime") != "codex":
         raise DispatchError(f"run manifest is not a Codex lead run: {path}")
@@ -1066,190 +1062,25 @@ def _post_process_report_writer_result(
 ) -> dict[str, Any]:
     if worker.worker_id != REPORT_WRITER_WORKER_ID:
         return {"ok": True, "reason": "", "steps": []}
-    steps = []
     try:
-        commands = _report_post_process_commands(plan, worker)
-    except DispatchError as exc:
-        return {"ok": False, "reason": str(exc), "steps": steps}
-    for name, command in commands:
-        if name == "validate-run":
-            _set_worker_status(plan.team_state_path, worker.worker_id, "completed", "")
-        result = subprocess.run(
-            command,
-            cwd=plan.project_root,
-            text=True,
-            capture_output=True,
+        ctx = FinalizeContext.from_manifest(
+            project_root=plan.project_root,
+            workspace_root=plan.workspace_root,
+            manifest_path=plan.manifest_path,
+            team_state_path=plan.team_state_path,
+            data_path=worker.result_path,
+            manifest=plan.manifest,
         )
-        step = _post_process_step_payload(name, command, result)
-        steps.append(step)
-        if result.returncode != 0:
-            return {
-                "ok": False,
-                "reason": f"{name} failed with exit code {result.returncode}",
-                "steps": steps,
-            }
-    return {"ok": True, "reason": "", "steps": steps}
-
-
-def _report_post_process_commands(
-    plan: DispatchPlan,
-    worker: WorkerDispatch,
-) -> list[tuple[str, list[str]]]:
-    markdown_path = _final_report_markdown_path(worker.result_path)
-    commands = [
-        (
-            "token-usage",
-            [
-                sys.executable,
-                str(_resolve_workspace_script(plan.workspace_root, "okstra-token-usage.py")),
-                str(plan.team_state_path),
-                "--project-root",
-                str(plan.project_root),
-                "--write",
-                "--substitute-data",
-                str(worker.result_path),
-            ],
-        ),
-        (
-            "render-views",
-            [
-                sys.executable,
-                str(_resolve_workspace_script(plan.workspace_root, "okstra-render-report-views.py")),
-                str(markdown_path),
-                "--task-key",
-                _require_string(plan.manifest, "taskKey"),
-                "--task-type",
-                _require_string(plan.manifest, "taskType"),
-                "--seq",
-                _run_seq(plan.manifest),
-                "--source-report",
-                _project_relative_path(plan.project_root, markdown_path),
-            ],
-        ),
-        (
-            "spawn-followups",
-            [
-                sys.executable,
-                str(_resolve_workspace_script(plan.workspace_root, "okstra-spawn-followups.py")),
-                str(worker.result_path),
-                "--project-root",
-                str(plan.project_root),
-                "--task-group",
-                _task_group(plan.manifest),
-                "--parent-task-key",
-                _require_string(plan.manifest, "taskKey"),
-            ],
-        ),
-    ]
-    commands.append(("validate-run", _validate_run_command(plan, markdown_path)))
-    return commands
-
-
-def _validate_run_command(plan: DispatchPlan, markdown_path: Path) -> list[str]:
-    task_manifest_path = _task_manifest_path(plan.project_root, plan.manifest)
-    command = [
-        sys.executable,
-        str(_resolve_workspace_validator(plan.workspace_root, "validate-run.py")),
-        "--team-state",
-        str(plan.team_state_path),
-        "--report",
-        str(markdown_path),
-        "--run-manifest",
-        str(plan.manifest_path),
-        "--task-manifest",
-        str(task_manifest_path),
-    ]
-    final_status_path = _resolve_optional_path(
-        plan.project_root, plan.manifest.get("finalStatusPath")
-    )
-    if final_status_path is not None:
-        command.extend(["--final-status", str(final_status_path)])
-    return command
-
-
-def _task_manifest_path(project_root: Path, manifest: Mapping[str, Any]) -> Path:
-    value = _string_value(manifest.get("taskManifestPath"))
-    if value:
-        return _resolve_project_path(project_root, value)
-    task_root = _string_value(manifest.get("taskRootPath"))
-    if task_root:
-        return _resolve_project_path(project_root, task_root) / "task-manifest.json"
-    return (
-        task_dir(project_root, _task_group(manifest), _task_id(manifest))
-        / "task-manifest.json"
-    )
-
-
-def _post_process_step_payload(
-    name: str,
-    command: Sequence[str],
-    result: subprocess.CompletedProcess[str],
-) -> dict[str, Any]:
-    return {
-        "name": name,
-        "command": list(command),
-        "exitCode": result.returncode,
-        "stdoutTail": _tail(result.stdout),
-        "stderrTail": _tail(result.stderr),
-    }
-
-
-def _resolve_workspace_script(workspace_root: Path, script_name: str) -> Path:
-    candidates = [
-        workspace_root / "scripts" / script_name,
-        workspace_root / script_name,
-    ]
-    for candidate in candidates:
-        if candidate.is_file():
-            return candidate.resolve()
-    searched = ", ".join(str(candidate) for candidate in candidates)
-    raise DispatchError(f"{script_name} not found (searched: {searched})")
-
-
-def _resolve_workspace_validator(workspace_root: Path, validator_name: str) -> Path:
-    candidates = [
-        workspace_root / "validators" / validator_name,
-        workspace_root / validator_name,
-    ]
-    for candidate in candidates:
-        if candidate.is_file():
-            return candidate.resolve()
-    searched = ", ".join(str(candidate) for candidate in candidates)
-    raise DispatchError(f"{validator_name} not found (searched: {searched})")
-
-
-def _task_group(manifest: Mapping[str, Any]) -> str:
-    value = _string_value(manifest.get("taskGroup"))
-    if value:
-        return value
-    task_key = _require_string(manifest, "taskKey")
-    colon_parts = task_key.split(":")
-    if len(colon_parts) >= 3 and colon_parts[-2].strip():
-        return colon_parts[-2].strip()
-    slash_parts = task_key.split("/")
-    if len(slash_parts) >= 2 and slash_parts[0].strip():
-        return slash_parts[0].strip()
-    raise DispatchError(f"cannot infer task group from taskKey: {task_key}")
-
-
-def _task_id(manifest: Mapping[str, Any]) -> str:
-    value = _string_value(manifest.get("taskId"))
-    if value:
-        return value
-    task_key = _require_string(manifest, "taskKey")
-    colon_parts = task_key.split(":")
-    if len(colon_parts) >= 3 and colon_parts[-1].strip():
-        return colon_parts[-1].strip()
-    slash_parts = task_key.split("/")
-    if len(slash_parts) >= 2 and slash_parts[-1].strip():
-        return slash_parts[-1].strip()
-    raise DispatchError(f"cannot infer task id from taskKey: {task_key}")
+    except FinalizeError as exc:
+        return {"ok": False, "reason": str(exc), "steps": []}
 
+    def settle_before(step_name: str) -> None:
+        # validate-run reads team-state; the writer is done by the time its
+        # artifacts pass the earlier steps.
+        if step_name == STEP_VALIDATE_RUN:
+            _set_worker_status(plan.team_state_path, worker.worker_id, "completed", "")
 
-def _tail(text: str, *, limit: int = 4000) -> str:
-    if len(text) <= limit:
-        return text
-    return text[-limit:]
+    return run_finalize(ctx, before_step=settle_before)
 
 
 def _append_event(
@@ -1411,37 +1242,12 @@ def _resolve_required_path(
     return _resolve_project_path(project_root, _require_string(manifest, key))
 
 
-def _resolve_optional_path(project_root: Path, value: Any) -> Path | None:
-    if not isinstance(value, str) or not value.strip():
-        return None
-    return _resolve_project_path(project_root, value)
-
-
-def _resolve_project_path(project_root: Path, value: str) -> Path:
-    path = Path(value)
-    return path if path.is_absolute() else project_root / path
-
-
-def _require_string(payload: Mapping[str, Any], key: str) -> str:
-    value = payload.get(key)
-    if not isinstance(value, str) or not value.strip():
-        raise DispatchError(f"missing required string field: {key}")
-    return value
-
-
 def _string_list(value: Any) -> list[str]:
     if not isinstance(value, list):
         return []
     return [str(item).strip() for item in value if str(item).strip()]
 
 
-def _run_seq(manifest: Mapping[str, Any]) -> str:
-    seqs = manifest.get("runSequencesByCategory")
-    if not isinstance(seqs, Mapping):
-        raise DispatchError("run manifest has no runSequencesByCategory object")
-    return _require_string(seqs, "manifests")
-
-
 def _failure_reason(exit_code: int, missing_paths: Sequence[Path]) -> str:
     if exit_code != 0:
         return f"wrapper exited with code {exit_code}"

package/runtime/python/okstra_ctl/report_finalize.py

@@ -0,0 +1,394 @@
+"""Phase 7 report post-processing — the single reference point.
+
+Phase 7 turns a Phase 6 final-report data.json into shippable artifacts through
+four ordered steps: usage substitution, html view rendering, follow-up task
+spawning, and run validation. The order is load-bearing — rendering before
+substitution ships `--` token cells, and validating before rendering trips the
+report-views contract.
+
+Every lead adapter drives Phase 7 through this module: the Codex adapter calls
+it in-process (``codex_dispatch``), and a Claude-led run reaches the same code
+through the ``okstra report-finalize`` CLI. Neither reimplements the sequence.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Mapping, Sequence
+
+from .final_report_paths import final_report_data_path, final_report_markdown_path
+from .paths import task_dir
+
+
+STEP_TOKEN_USAGE = "token-usage"
+STEP_RENDER_VIEWS = "render-views"
+STEP_SPAWN_FOLLOWUPS = "spawn-followups"
+STEP_VALIDATE_RUN = "validate-run"
+
+STEP_ORDER = (
+    STEP_TOKEN_USAGE,
+    STEP_RENDER_VIEWS,
+    STEP_SPAWN_FOLLOWUPS,
+    STEP_VALIDATE_RUN,
+)
+
+
+class FinalizeError(Exception):
+    """Raised when the Phase 7 sequence cannot be assembled."""
+
+
+def string_value(value: Any) -> str:
+    if not isinstance(value, str):
+        return ""
+    return value.strip()
+
+
+def require_string(payload: Mapping[str, Any], key: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise FinalizeError(f"missing required string field: {key}")
+    return value
+
+
+def resolve_project_path(project_root: Path, value: str) -> Path:
+    path = Path(value)
+    return path if path.is_absolute() else project_root / path
+
+
+def resolve_optional_path(project_root: Path, value: Any) -> Path | None:
+    if not isinstance(value, str) or not value.strip():
+        return None
+    return resolve_project_path(project_root, value)
+
+
+def project_relative_path(project_root: Path, path: Path) -> str:
+    try:
+        return path.relative_to(project_root).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def task_group(manifest: Mapping[str, Any]) -> str:
+    value = string_value(manifest.get("taskGroup"))
+    if value:
+        return value
+    task_key = require_string(manifest, "taskKey")
+    colon_parts = task_key.split(":")
+    if len(colon_parts) >= 3 and colon_parts[-2].strip():
+        return colon_parts[-2].strip()
+    slash_parts = task_key.split("/")
+    if len(slash_parts) >= 2 and slash_parts[0].strip():
+        return slash_parts[0].strip()
+    raise FinalizeError(f"cannot infer task group from taskKey: {task_key}")
+
+
+def task_id(manifest: Mapping[str, Any]) -> str:
+    value = string_value(manifest.get("taskId"))
+    if value:
+        return value
+    task_key = require_string(manifest, "taskKey")
+    colon_parts = task_key.split(":")
+    if len(colon_parts) >= 3 and colon_parts[-1].strip():
+        return colon_parts[-1].strip()
+    slash_parts = task_key.split("/")
+    if len(slash_parts) >= 2 and slash_parts[-1].strip():
+        return slash_parts[-1].strip()
+    raise FinalizeError(f"cannot infer task id from taskKey: {task_key}")
+
+
+def run_seq(manifest: Mapping[str, Any]) -> str:
+    seqs = manifest.get("runSequencesByCategory")
+    if not isinstance(seqs, Mapping):
+        raise FinalizeError("run manifest has no runSequencesByCategory object")
+    return require_string(seqs, "manifests")
+
+
+def task_manifest_path(project_root: Path, manifest: Mapping[str, Any]) -> Path:
+    value = string_value(manifest.get("taskManifestPath"))
+    if value:
+        return resolve_project_path(project_root, value)
+    task_root = string_value(manifest.get("taskRootPath"))
+    if task_root:
+        return resolve_project_path(project_root, task_root) / "task-manifest.json"
+    return (
+        task_dir(project_root, task_group(manifest), task_id(manifest))
+        / "task-manifest.json"
+    )
+
+
+def resolve_workspace_script(workspace_root: Path, script_name: str) -> Path:
+    return _resolve_workspace_file(workspace_root, "scripts", script_name)
+
+
+def resolve_workspace_validator(workspace_root: Path, validator_name: str) -> Path:
+    return _resolve_workspace_file(workspace_root, "validators", validator_name)
+
+
+def _resolve_workspace_file(
+    workspace_root: Path,
+    subdir: str,
+    name: str,
+) -> Path:
+    candidates = [workspace_root / subdir / name, workspace_root / name]
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate.resolve()
+    searched = ", ".join(str(candidate) for candidate in candidates)
+    raise FinalizeError(f"{name} not found (searched: {searched})")
+
+
+def tail(text: str, *, limit: int = 4000) -> str:
+    if len(text) <= limit:
+        return text
+    return text[-limit:]
+
+
+@dataclass(frozen=True)
+class FinalizeContext:
+    """Everything the Phase 7 sequence needs, resolved from a run manifest."""
+
+    project_root: Path
+    workspace_root: Path
+    manifest_path: Path
+    team_state_path: Path
+    data_path: Path
+    task_manifest_path: Path
+    task_key: str
+    task_type: str
+    task_group: str
+    seq: str
+    final_status_path: Path | None
+
+    @property
+    def markdown_path(self) -> Path:
+        return final_report_markdown_path(self.data_path)
+
+    @classmethod
+    def from_manifest(
+        cls,
+        *,
+        project_root: Path,
+        workspace_root: Path,
+        manifest_path: Path,
+        team_state_path: Path,
+        data_path: Path,
+        manifest: Mapping[str, Any],
+    ) -> "FinalizeContext":
+        return cls(
+            project_root=project_root,
+            workspace_root=workspace_root,
+            manifest_path=manifest_path,
+            team_state_path=team_state_path,
+            data_path=data_path,
+            task_manifest_path=task_manifest_path(project_root, manifest),
+            task_key=require_string(manifest, "taskKey"),
+            task_type=require_string(manifest, "taskType"),
+            task_group=task_group(manifest),
+            seq=run_seq(manifest),
+            final_status_path=resolve_optional_path(
+                project_root, manifest.get("finalStatusPath")
+            ),
+        )
+
+
+def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
+    """Assemble the ordered Phase 7 argv list. Order is contractual."""
+    markdown_path = ctx.markdown_path
+    return [
+        (
+            STEP_TOKEN_USAGE,
+            [
+                sys.executable,
+                str(resolve_workspace_script(ctx.workspace_root, "okstra-token-usage.py")),
+                str(ctx.team_state_path),
+                "--project-root",
+                str(ctx.project_root),
+                "--write",
+                "--substitute-data",
+                str(ctx.data_path),
+            ],
+        ),
+        (
+            STEP_RENDER_VIEWS,
+            [
+                sys.executable,
+                str(
+                    resolve_workspace_script(
+                        ctx.workspace_root, "okstra-render-report-views.py"
+                    )
+                ),
+                str(markdown_path),
+                "--task-key",
+                ctx.task_key,
+                "--task-type",
+                ctx.task_type,
+                "--seq",
+                ctx.seq,
+                "--source-report",
+                project_relative_path(ctx.project_root, markdown_path),
+            ],
+        ),
+        (
+            STEP_SPAWN_FOLLOWUPS,
+            [
+                sys.executable,
+                str(
+                    resolve_workspace_script(
+                        ctx.workspace_root, "okstra-spawn-followups.py"
+                    )
+                ),
+                str(ctx.data_path),
+                "--project-root",
+                str(ctx.project_root),
+                "--task-group",
+                ctx.task_group,
+                "--parent-task-key",
+                ctx.task_key,
+            ],
+        ),
+        (STEP_VALIDATE_RUN, _validate_run_command(ctx, markdown_path)),
+    ]
+
+
+def _validate_run_command(ctx: FinalizeContext, markdown_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),
+        "--run-manifest",
+        str(ctx.manifest_path),
+        "--task-manifest",
+        str(ctx.task_manifest_path),
+    ]
+    if ctx.final_status_path is not None:
+        command.extend(["--final-status", str(ctx.final_status_path)])
+    return command
+
+
+def step_payload(
+    name: str,
+    command: Sequence[str],
+    result: subprocess.CompletedProcess[str],
+) -> dict[str, Any]:
+    return {
+        "name": name,
+        "command": list(command),
+        "exitCode": result.returncode,
+        "stdoutTail": tail(result.stdout),
+        "stderrTail": tail(result.stderr),
+    }
+
+
+def run_finalize(
+    ctx: FinalizeContext,
+    *,
+    before_step: Callable[[str], None] | None = None,
+) -> dict[str, Any]:
+    """Run the Phase 7 steps in order, stopping at the first non-zero exit.
+
+    ``before_step`` fires immediately before each step is spawned, letting an
+    adapter settle state the step will read (the Codex adapter marks the report
+    writer `completed` before `validate-run` inspects team-state).
+    """
+    steps: list[dict[str, Any]] = []
+    try:
+        commands = build_commands(ctx)
+    except FinalizeError as exc:
+        return {"ok": False, "reason": str(exc), "steps": steps}
+
+    for name, command in commands:
+        if before_step is not None:
+            before_step(name)
+        result = subprocess.run(
+            command,
+            cwd=ctx.project_root,
+            text=True,
+            capture_output=True,
+        )
+        steps.append(step_payload(name, command, result))
+        if result.returncode != 0:
+            return {
+                "ok": False,
+                "reason": f"{name} failed with exit code {result.returncode}",
+                "steps": steps,
+            }
+    return {"ok": True, "reason": "", "steps": steps}
+
+
+def _load_manifest(path: Path) -> Mapping[str, Any]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise FinalizeError(f"run manifest not found: {path}") from exc
+    except json.JSONDecodeError as exc:
+        raise FinalizeError(f"run manifest is not valid JSON: {path} ({exc})") from exc
+    if not isinstance(payload, Mapping):
+        raise FinalizeError(f"run manifest is not a JSON object: {path}")
+    return payload
+
+
+def _context_from_args(args: argparse.Namespace) -> FinalizeContext:
+    project_root = Path(args.project_root).resolve()
+    manifest_path = resolve_project_path(project_root, args.run_manifest)
+    manifest = _load_manifest(manifest_path)
+    if args.team_state:
+        team_state_path = resolve_project_path(project_root, args.team_state)
+    else:
+        team_state_path = resolve_project_path(
+            project_root, require_string(manifest, "teamStatePath")
+        )
+    report_path = resolve_project_path(project_root, args.report)
+    return FinalizeContext.from_manifest(
+        project_root=project_root,
+        workspace_root=Path(args.workspace_root).resolve(),
+        manifest_path=manifest_path,
+        team_state_path=team_state_path,
+        data_path=final_report_data_path(report_path),
+        manifest=manifest,
+    )
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Run the Phase 7 report post-processing sequence.",
+    )
+    parser.add_argument("--project-root", required=True)
+    parser.add_argument("--run-manifest", required=True)
+    parser.add_argument(
+        "--report",
+        required=True,
+        help="final-report markdown path (its .data.json sibling is derived)",
+    )
+    parser.add_argument("--workspace-root", required=True)
+    parser.add_argument(
+        "--team-state",
+        default="",
+        help="defaults to the run manifest's teamStatePath",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        ctx = _context_from_args(args)
+    except FinalizeError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    result = run_finalize(ctx)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    if not result["ok"]:
+        print(f"error: {result['reason']}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())