okstra 0.128.0 → 0.129.1

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())

package/runtime/python/okstra_ctl/worker_liveness.py

@@ -110,9 +110,13 @@ def main(argv: list[str] | None = None) -> int:
         description="Report whether pending workers are still alive (read-only).",
     )
     parser.add_argument("--audit", action="append", default=[],
-                        help="claude-worker audit sidecar path (repeatable)")
+                        help="in-process claude-worker audit sidecar path (repeatable)")
     parser.add_argument("--prompt", action="append", default=[],
-                        help="CLI-wrapper prompt-history path (repeatable)")
+                        help="CLI-wrapper (codex/antigravity) prompt-history path "
+                             "(repeatable). Only the wrappers write the artifacts "
+                             "this probe looks for, so passing an in-process "
+                             "claude-worker path here always reports "
+                             "did-not-launch — probe those with --audit")
     parser.add_argument("--max-idle", type=float, default=HEARTBEAT_MAX_GAP_SECONDS,
                         help="heartbeat staleness budget in seconds")
     parser.add_argument("--launch-grace", type=float, default=DEFAULT_LAUNCH_GRACE_SECONDS,

package/runtime/python/okstra_ctl/worker_prompt_body.py

@@ -0,0 +1,107 @@
+"""Shared initial analysis-worker prompt body rendering."""
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+from .worker_prompt_policy import PromptPlan
+
+
+ANALYSIS_WORKER_LABELS = {
+    "claude": "Claude worker",
+    "codex": "Codex worker",
+    "antigravity": "Antigravity worker",
+}
+
+
+def analysis_prompt_body(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    worker_id: str,
+    model: str,
+    role: str,
+    plan: PromptPlan,
+) -> list[str]:
+    """Render the provider-neutral body for an initial analysis audience."""
+    label = ANALYSIS_WORKER_LABELS.get(worker_id, f"{worker_id} worker")
+    return [
+        f"**Model:** {label}, {model}",
+        f"**Pane role:** {role}",
+        "",
+        f"# {label} Dispatch",
+        "",
+        "## Role",
+        (
+            f"You are the {label} for okstra cross-verification. "
+            "Produce an independent worker result."
+        ),
+        "",
+        "## Task",
+        f"- Task key: `{_require_string(manifest, 'taskKey')}`",
+        f"- Task type: `{_require_string(manifest, 'taskType')}`",
+        "",
+        "## Inputs",
+        *analysis_input_lines(manifest, active_context, plan),
+        "",
+        mcp_pointer_line(),
+        "",
+        "## Output Contract",
+        "- Read the Worker Preamble Path end-to-end before analysis.",
+        "- Write the worker result to Result Path and no other canonical result path.",
+        "- Write the audit sidecar and any tool-failure entries as the preamble requires.",
+        "- Cite evidence with file paths and line numbers whenever you make a claim.",
+    ]
+
+
+def analysis_input_lines(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    plan: PromptPlan,
+) -> list[str]:
+    if plan.packet_only:
+        packet_path = instruction_path(manifest, active_context, "analysisPacketPath")
+        return existing_input_lines((("Primary analysis packet", packet_path),))
+    inputs = [
+        ("Primary analysis packet", instruction_path(manifest, active_context, "analysisPacketPath")),
+        ("Task brief", instruction_path(manifest, active_context, "taskBriefPath")),
+        ("Analysis profile", instruction_path(manifest, active_context, "analysisProfilePath")),
+        ("Analysis material", instruction_path(manifest, active_context, "analysisMaterialPath")),
+        ("Reference expectations", instruction_path(manifest, active_context, "referenceExpectationsPath")),
+        ("Clarification response", instruction_path(manifest, active_context, "clarificationResponsePath")),
+    ]
+    return existing_input_lines(inputs)
+
+
+def existing_input_lines(inputs: Sequence[tuple[str, str]]) -> list[str]:
+    lines = [f"- {label}: `{path}`" for label, path in inputs if path]
+    return lines or ["- No input paths were recorded in active-run-context."]
+
+
+def instruction_path(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    key: str,
+) -> str:
+    instruction_set = active_context.get("instructionSet")
+    if isinstance(instruction_set, Mapping):
+        value = _string_value(instruction_set.get(key))
+        if value:
+            return value
+    return _string_value(manifest.get(key))
+
+
+def mcp_pointer_line() -> str:
+    return (
+        '**MCP servers:** follow the task brief\'s "## Available MCP Servers" '
+        "section (already in your Required reading)."
+    )
+
+
+def _require_string(payload: Mapping[str, Any], key: str) -> str:
+    value = _string_value(payload.get(key))
+    if not value:
+        raise ValueError(f"missing required string field: {key}")
+    return value
+
+
+def _string_value(value: Any) -> str:
+    return value.strip() if isinstance(value, str) else ""

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -2,14 +2,18 @@
 from __future__ import annotations
 
 import re
+from dataclasses import dataclass
 from pathlib import Path
-from typing import Mapping
+from typing import Any, Mapping, Sequence
+
+from .worker_prompt_policy import PromptPlan, resolve_prompt_plan_for_manifest
 
 
 MAX_FINAL_VERIFICATION_DIRECTIVE_LINES = 40
 MAX_FINAL_VERIFICATION_BODY_LINES = 96
 
 _DIRECTIVE_HEADING = "## Run-specific directive"
+_WORKER_ERROR_CONTRACT_HEADER = "**Worker Error Contract Path:**"
 _PRIMARY_PACKET_RE = re.compile(
     r"(?im)^-\s+Primary analysis packet:\s+`[^`\n]*analysis-packet\.md`\s*$"
 )
@@ -63,6 +67,13 @@ _WORKER_LABEL_RE = re.compile(
 )
 
 
+@dataclass(frozen=True)
+class PromptRecord:
+    worker_id: str
+    dispatch_kind: str
+    path: Path
+
+
 def validate_final_verification_initial_prompt(text: str) -> list[str]:
     """Return deterministic compact-prompt contract violations."""
     errors: list[str] = []
@@ -155,23 +166,105 @@ def validate_final_verification_prompt_paths(
     prompt_paths: Mapping[str, Path],
 ) -> list[str]:
     """Validate persisted initial prompts and their normalized equality."""
-    prompts: dict[str, str] = {}
+    records = [
+        PromptRecord(worker_id, "initial", path)
+        for worker_id, path in sorted(prompt_paths.items())
+    ]
+    return validate_initial_prompt_records(
+        manifest={"taskType": "final-verification"},
+        records=records,
+    )
+
+
+def validate_initial_prompt_records(
+    *,
+    manifest: Mapping[str, Any],
+    records: Sequence[PromptRecord],
+) -> list[str]:
+    """Validate prompt audiences and compare their normalized equality groups."""
     errors: list[str] = []
-    for worker_id, path in sorted(prompt_paths.items()):
+    equality_groups: dict[str, dict[str, str]] = {}
+    for record in records:
+        plan = _resolve_record_plan(manifest, record, errors)
+        if plan is None or plan.audience in {"lead-only", "reverify"}:
+            continue
         try:
-            text = path.read_text(encoding="utf-8")
+            text = record.path.read_text(encoding="utf-8")
         except OSError as exc:
-            errors.append(f"{worker_id}: cannot read prompt {path}: {exc}")
+            errors.append(
+                f"{record.worker_id}: cannot read prompt {record.path}: {exc}"
+            )
             continue
-        prompts[worker_id] = text
         errors.extend(
-            f"{worker_id}: {error}"
-            for error in validate_final_verification_initial_prompt(text)
+            f"{record.worker_id}: {error}"
+            for error in _validate_prompt_for_plan(text, plan, manifest)
         )
-    errors.extend(validate_analysis_prompt_set(prompts))
+        if plan.equality_group:
+            group = equality_groups.setdefault(plan.equality_group, {})
+            group[record.worker_id] = text
+    for prompts in equality_groups.values():
+        errors.extend(validate_analysis_prompt_set(prompts))
     return errors
 
 
+def _resolve_record_plan(
+    manifest: Mapping[str, Any],
+    record: PromptRecord,
+    errors: list[str],
+) -> PromptPlan | None:
+    try:
+        return resolve_prompt_plan_for_manifest(
+            manifest=manifest,
+            worker_id=record.worker_id,
+            dispatch_kind=record.dispatch_kind,
+        )
+    except ValueError as exc:
+        errors.append(f"{record.worker_id}: {exc}")
+        return None
+
+
+def _validate_prompt_for_plan(
+    text: str,
+    plan: PromptPlan,
+    manifest: Mapping[str, Any],
+) -> list[str]:
+    errors: list[str] = []
+    _require_non_empty_header(text, _WORKER_ERROR_CONTRACT_HEADER, errors)
+    if manifest.get("taskType") == "final-verification" and plan.audience == "analysis":
+        return [*errors, *validate_final_verification_initial_prompt(text)]
+    if not plan.allow_coding_preflight:
+        _reject_literal(
+            text,
+            "**Coding preflight pack:**",
+            "Coding preflight pack is forbidden for this prompt audience",
+            errors,
+        )
+    for prefix in plan.required_headers:
+        _require_non_empty_header(text, prefix, errors)
+    if plan.audience == "analysis":
+        packet_count = len(_PRIMARY_PACKET_RE.findall(text))
+        if packet_count != 1:
+            errors.append(
+                "exactly one Primary analysis packet path is required "
+                f"(found {packet_count})"
+            )
+    return errors
+
+
+def _require_non_empty_header(
+    text: str,
+    prefix: str,
+    errors: list[str],
+) -> None:
+    matches = [
+        line.strip()
+        for line in text.splitlines()
+        if line.strip().startswith(prefix)
+    ]
+    if len(matches) != 1 or not matches[0][len(prefix):].strip():
+        errors.append(f"exactly one non-empty {prefix} header is required")
+
+
 def _reject_literal(
     text: str,
     literal: str,