okstra 0.127.0 → 0.129.0

package/runtime/python/okstra_ctl/convergence_migration.py

@@ -0,0 +1,184 @@
+"""Resume and legacy-state migration decisions for convergence seeding."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import os
+from pathlib import Path
+import tempfile
+from typing import Any, Literal, Mapping
+
+from .convergence_engine import (
+    ConvergenceContractError,
+    grouped_input_digest,
+    validate_final_state,
+    validate_working_state,
+)
+from .convergence_store import load_json_object
+
+
+SeedAction = Literal[
+    "create-work",
+    "resume-work",
+    "reuse-final",
+    "restart-round0",
+]
+
+
+@dataclass(frozen=True)
+class SeedDecision:
+    action: SeedAction
+    archive_path: Path | None
+    legacy_digest: str | None
+    reason: str
+
+
+def decide_seed_action(
+    *,
+    grouped_input: Mapping[str, Any],
+    work_state_path: Path,
+    final_state_path: Path,
+    restart_from_round0: bool,
+) -> SeedDecision:
+    """Classify existing new-engine/legacy state without mutating files."""
+    task_key = grouped_input.get("taskKey")
+    digest = grouped_input_digest(grouped_input)
+    final_status, final_value = _inspect_final(final_state_path)
+    if final_status == "terminal":
+        return SeedDecision("reuse-final", None, None, "valid terminal final state")
+
+    work_status, work_value = _inspect_work(work_state_path)
+    invalid_final = final_status == "invalid"
+    if work_status == "valid":
+        assert work_value is not None
+        if work_value.get("taskKey") != task_key:
+            raise ConvergenceContractError(
+                "existing working state taskKey does not match grouped input"
+            )
+        if work_value.get("groupsDigest") != digest:
+            raise ConvergenceContractError(
+                "existing working state groupsDigest does not match grouped input"
+            )
+        if invalid_final:
+            archive_path, legacy_digest = _archive_identity(
+                final_state_path, final_state_path.parent / "migrations"
+            )
+            return SeedDecision(
+                "resume-work",
+                archive_path,
+                legacy_digest,
+                "matching working state with invalid legacy final",
+            )
+        return SeedDecision("resume-work", None, None, "matching working state")
+
+    if work_status == "invalid" and not restart_from_round0:
+        raise ConvergenceContractError(
+            "existing convergence working state is invalid; pass "
+            "--restart-from-round0 to archive it and restart"
+        )
+    if work_status == "invalid":
+        source = final_state_path if invalid_final else work_state_path
+        archive_path, legacy_digest = _archive_identity(
+            source, source.parent / "migrations"
+        )
+        return SeedDecision(
+            "restart-round0",
+            archive_path,
+            legacy_digest,
+            "explicit restart of invalid working state",
+        )
+    if invalid_final:
+        archive_path, legacy_digest = _archive_identity(
+            final_state_path, final_state_path.parent / "migrations"
+        )
+        return SeedDecision(
+            "restart-round0",
+            archive_path,
+            legacy_digest,
+            "invalid or partial legacy final state",
+        )
+    return SeedDecision("create-work", None, None, "no existing convergence state")
+
+
+def archive_state_bytes(
+    *,
+    source_path: Path,
+    migration_dir: Path,
+) -> tuple[Path, str]:
+    """Archive source bytes under a digest-derived immutable filename."""
+    data = source_path.read_bytes()
+    digest = hashlib.sha256(data).hexdigest()
+    archive_path = migration_dir / f"{source_path.name}.{digest[:12]}.json"
+    if archive_path.exists():
+        if archive_path.read_bytes() != data:
+            raise ConvergenceContractError(
+                f"migration archive path contains different bytes: {archive_path}"
+            )
+        return archive_path, digest
+    migration_dir.mkdir(parents=True, exist_ok=True)
+    temp_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="wb",
+            dir=migration_dir,
+            prefix=f".{archive_path.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as handle:
+            temp_path = Path(handle.name)
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp_path, archive_path)
+        temp_path = None
+    finally:
+        if temp_path is not None:
+            temp_path.unlink(missing_ok=True)
+    return archive_path, digest
+
+
+def migration_record(
+    source_path: Path,
+    archive_path: Path,
+    digest: str,
+) -> dict[str, str]:
+    return {
+        "mode": "restart-round0",
+        "sourcePath": str(source_path),
+        "archivePath": str(archive_path),
+        "legacyDigest": digest,
+    }
+
+
+def _inspect_final(path: Path) -> tuple[str, dict[str, Any] | None]:
+    if not path.exists():
+        return "absent", None
+    try:
+        value = load_json_object(path)
+    except (OSError, ValueError):
+        return "invalid", None
+    if validate_final_state(value):
+        return "invalid", value
+    if value.get("finalState") not in {
+        "converged",
+        "max-rounds-reached",
+        "aborted-non-result",
+    }:
+        return "invalid", value
+    return "terminal", value
+
+
+def _inspect_work(path: Path) -> tuple[str, dict[str, Any] | None]:
+    if not path.exists():
+        return "absent", None
+    try:
+        value = load_json_object(path)
+    except (OSError, ValueError):
+        return "invalid", None
+    return ("valid", value) if not validate_working_state(value) else ("invalid", value)
+
+
+def _archive_identity(source_path: Path, migration_dir: Path) -> tuple[Path, str]:
+    data = source_path.read_bytes()
+    digest = hashlib.sha256(data).hexdigest()
+    return migration_dir / f"{source_path.name}.{digest[:12]}.json", digest

package/runtime/python/okstra_ctl/convergence_store.py

@@ -0,0 +1,85 @@
+"""Validated JSON loading and atomic persistence for convergence artifacts."""
+from __future__ import annotations
+
+import json
+import hashlib
+import os
+from pathlib import Path
+import tempfile
+from typing import Any, Mapping
+
+from .convergence_engine import ConvergenceContractError
+
+
+def load_json_object(path: Path) -> dict[str, Any]:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ConvergenceContractError(f"JSON input must be an object: {path}")
+    return value
+
+
+def write_json_atomic(path: Path, payload: Mapping[str, Any]) -> None:
+    if not isinstance(payload, Mapping):
+        raise ConvergenceContractError("JSON output payload must be an object")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=path.parent,
+            prefix=f".{path.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as handle:
+            temp_path = Path(handle.name)
+            json.dump(
+                payload,
+                handle,
+                ensure_ascii=False,
+                sort_keys=True,
+                indent=2,
+            )
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp_path, path)
+        temp_path = None
+    finally:
+        if temp_path is not None:
+            temp_path.unlink(missing_ok=True)
+
+
+def write_final_state_atomic(
+    path: Path,
+    payload: Mapping[str, Any],
+    *,
+    migration: Mapping[str, Any] | None,
+) -> None:
+    """Replace a legacy final only when its byte archive proves preservation."""
+    if path.exists():
+        _validate_final_replacement(path, migration)
+    write_json_atomic(path, payload)
+
+
+def _validate_final_replacement(
+    path: Path,
+    migration: Mapping[str, Any] | None,
+) -> None:
+    if not isinstance(migration, Mapping) or migration.get("mode") != "restart-round0":
+        raise ConvergenceContractError(
+            "existing final state requires a restart-round0 migration archive"
+        )
+    if migration.get("sourcePath") != str(path):
+        raise ConvergenceContractError("migration archive sourcePath does not match final state")
+    archive_value = migration.get("archivePath")
+    digest = migration.get("legacyDigest")
+    if not isinstance(archive_value, str) or not isinstance(digest, str):
+        raise ConvergenceContractError("migration archive metadata is incomplete")
+    archive_path = Path(archive_value)
+    if not archive_path.is_file():
+        raise ConvergenceContractError(f"migration archive is missing: {archive_path}")
+    archived = archive_path.read_bytes()
+    current = path.read_bytes()
+    if hashlib.sha256(archived).hexdigest() != digest or archived != current:
+        raise ConvergenceContractError("migration archive bytes do not match legacy final")

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -18,6 +18,9 @@ from .final_report_paths import (
 from .lead_events import LeadEvent, append_lead_event
 from .path_hints import hydrate_active_run_context
 from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
+from .worker_prompt_body import analysis_prompt_body
+from .worker_prompt_contract import PromptRecord, validate_initial_prompt_records
+from .worker_prompt_policy import resolve_prompt_plan_for_manifest
 from .wrapper_status import read_wrapper_status, status_path_for_prompt
 
 
@@ -183,6 +186,7 @@ def build_dispatch_plan(
         report_writer_model,
         options,
     )
+    _validate_initial_prompts(manifest, jobs)
     return DispatchPlan(
         project_root=project_root,
         workspace_root=workspace_root.resolve(),
@@ -195,6 +199,20 @@ def build_dispatch_plan(
     )
 
 
+def _validate_initial_prompts(
+    manifest: Mapping[str, Any],
+    jobs: Sequence[WorkerJob],
+) -> None:
+    records = [
+        PromptRecord(job.worker_id, job.dispatch_kind, job.prompt_path)
+        for job in jobs
+    ]
+    errors = validate_initial_prompt_records(manifest=manifest, records=records)
+    if errors:
+        task_type = _require_string(manifest, "taskType")
+        raise DispatchError(f"{task_type} prompt contract: " + "; ".join(errors))
+
+
 def dispatch_plan(plan: DispatchPlan, *, wait: bool = True) -> int:
     if wait:
         if any(job.backend == BACKEND_TMUX_PANE for job in plan.jobs):
@@ -314,6 +332,9 @@ def _job_from_roster_worker(
         project_root=project_root,
         manifest=manifest,
         active_context=active_context,
+        dispatch_kind=options.dispatch_kind,
+        model=model,
+        role=_string_value(state.get("role")) or "worker",
     )
     return WorkerJob(
         worker_id=worker_id,
@@ -778,6 +799,9 @@ def _materialize_prompt_if_missing(
     project_root: Path,
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any],
+    dispatch_kind: str,
+    model: str,
+    role: str,
 ) -> None:
     if prompt_path.is_file():
         return
@@ -788,12 +812,47 @@ def _materialize_prompt_if_missing(
             prompt_rel=prompt_rel,
             result_rel=result_rel,
             worker_id=worker_id,
+            dispatch_kind=dispatch_kind,
             manifest=manifest,
             active_context=active_context,
         )
     except WorkerPromptHeaderError as exc:
         raise DispatchError(str(exc)) from exc
-    prompt_path.write_text("\n".join([*headers, ""]), encoding="utf-8")
+    try:
+        plan = resolve_prompt_plan_for_manifest(
+            manifest=manifest,
+            worker_id=worker_id,
+            dispatch_kind=dispatch_kind,
+        )
+    except ValueError as exc:
+        raise DispatchError(str(exc)) from exc
+    lines = list(headers)
+    if plan.audience in {
+        "analysis",
+        "implementation-executor",
+        "implementation-verifier",
+    }:
+        if _string_value(manifest.get("taskType")) == "implementation":
+            worktree = _worktree_path(active_context)
+            if not worktree:
+                raise DispatchError(
+                    "implementation prompt generation requires a worktree path"
+                )
+            lines.append(f"**Worktree:** {worktree}")
+        try:
+            lines.extend(
+                analysis_prompt_body(
+                    manifest,
+                    active_context,
+                    worker_id,
+                    model,
+                    role,
+                    plan,
+                )
+            )
+        except ValueError as exc:
+            raise DispatchError(str(exc)) from exc
+    prompt_path.write_text("\n".join([*lines, ""]), encoding="utf-8")
 
 
 def _provider_for_worker(worker_id: str) -> str:

package/runtime/python/okstra_ctl/improvement_assignment.py

@@ -0,0 +1,61 @@
+"""Assign improvement-discovery primary passes from the resolved roster."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+
+def assign_primary_lenses(
+    worker_ids: list[str],
+    priority_lenses: list[str],
+) -> dict[str, str]:
+    """Round-robin resolved worker instances over resolved priority lenses."""
+    if not worker_ids:
+        raise ValueError("worker IDs must not be empty")
+    if not priority_lenses:
+        raise ValueError("priority lenses must not be empty")
+    if len(set(worker_ids)) != len(worker_ids):
+        raise ValueError("worker IDs must be unique")
+    return {
+        worker_id: priority_lenses[index % len(priority_lenses)]
+        for index, worker_id in enumerate(worker_ids)
+    }
+
+
+def validate_primary_lens_assignments(
+    assignments: Mapping[str, str],
+    worker_ids: list[str],
+    priority_lenses: list[str],
+) -> list[str]:
+    """Require every selected analyser once at its roster-order lens."""
+    errors: list[str] = []
+    if not worker_ids:
+        return ["resolved analyser worker IDs must not be empty"]
+    if not priority_lenses:
+        return ["resolved priority lenses must not be empty"]
+    try:
+        expected = assign_primary_lenses(worker_ids, priority_lenses)
+    except ValueError as exc:
+        return [str(exc)]
+    if list(assignments) != worker_ids:
+        errors.append(
+            "assignment order must match resolved analyser worker order: "
+            + ", ".join(worker_ids)
+        )
+    for worker_id in worker_ids:
+        if worker_id not in assignments:
+            errors.append(f"missing worker assignment: {worker_id}")
+    for worker_id, lens in assignments.items():
+        if worker_id not in expected:
+            errors.append(f"extra worker assignment: {worker_id}")
+            continue
+        if lens not in priority_lenses:
+            errors.append(
+                f"{worker_id}: primary lens {lens!r} is outside resolved priority lenses"
+            )
+            continue
+        if lens != expected[worker_id]:
+            errors.append(
+                f"{worker_id}: expected primary lens {expected[worker_id]!r}, "
+                f"got {lens!r}"
+            )
+    return errors

package/runtime/python/okstra_ctl/log_report.py

@@ -53,6 +53,34 @@ def _per_task(files: list[dict]) -> list[dict]:
     return sorted(acc.values(), key=lambda a: a["totalBytes"], reverse=True)
 
 
+def _prompt_pair(log_path: Path, transcript_bytes: int) -> dict:
+    prompt_path = log_path.with_suffix(".md")
+    if not prompt_path.is_file():
+        return {
+            "transcriptPath": str(log_path),
+            "transcriptBytes": transcript_bytes,
+            "promptPath": "",
+            "promptBytes": 0,
+            "transcriptToPromptRatio": None,
+        }
+    try:
+        prompt_bytes = prompt_path.stat().st_size
+    except OSError:
+        prompt_bytes = 0
+    ratio = (
+        round(transcript_bytes / prompt_bytes, 2)
+        if prompt_bytes > 0
+        else None
+    )
+    return {
+        "transcriptPath": str(log_path),
+        "transcriptBytes": transcript_bytes,
+        "promptPath": str(prompt_path),
+        "promptBytes": prompt_bytes,
+        "transcriptToPromptRatio": ratio,
+    }
+
+
 def scan_logs(logs_root: Path, project_root: Path, top: int = 20) -> dict:
     project_id = _project_id(project_root)
     files: list[dict] = []
@@ -68,16 +96,27 @@ def scan_logs(logs_root: Path, project_root: Path, top: int = 20) -> dict:
                 continue
             meta = _parse(parts, p.stem)
             tk = f"{project_id}:{meta['taskGroup']}:{meta['taskId']}" if meta["taskGroup"] else ""
-            files.append({"path": str(p), "sizeBytes": size, "mtimeEpoch": mtime,
-                          "taskKey": tk, **meta})
+            files.append({
+                "path": str(p),
+                "sizeBytes": size,
+                "mtimeEpoch": mtime,
+                "taskKey": tk,
+                **meta,
+                **_prompt_pair(p, size),
+            })
     files.sort(key=lambda f: f["sizeBytes"], reverse=True)
     return {
         "logsRoot": str(logs_root),
         "topLargest": files[:top],
         "perTask": _per_task(files),
-        "totals": {"fileCount": len(files),
-                   "totalBytes": sum(f["sizeBytes"] for f in files),
-                   "taskCount": len({f["taskKey"] for f in files if f["taskKey"]})},
+        "totals": {
+            "fileCount": len(files),
+            "totalBytes": sum(f["sizeBytes"] for f in files),
+            "taskCount": len({f["taskKey"] for f in files if f["taskKey"]}),
+            "promptBytes": sum(f["promptBytes"] for f in files),
+            "transcriptBytes": sum(f["transcriptBytes"] for f in files),
+            "pairedFileCount": sum(1 for f in files if f["promptPath"]),
+        },
     }
 
 

package/runtime/python/okstra_ctl/path_hints.py

@@ -59,6 +59,7 @@ def compact_active_run_context(
         "inputs": _compact_active_inputs(payload),
         "workers": _compact_active_workers(payload),
         "executorWorktree": dict(_mapping(payload.get("executorWorktree"))),
+        "verificationTarget": dict(_mapping(payload.get("verificationTarget"))),
         "lazyReadPlan": dict(_mapping(payload.get("lazyReadPlan"))),
     }
 
@@ -97,8 +98,20 @@ def hydrate_active_run_context(payload: Mapping[str, Any]) -> dict[str, Any]:
         "errorLogs": _hydrate_active_error_logs(ctx),
         "runtimeResources": {
             "codingPreflightDir": ctx.get("OKSTRA_CODING_PREFLIGHT_DIR", ""),
+            "workerPreamblePathByAudience": {
+                "analysis": ctx.get("ANALYSIS_WORKER_PREAMBLE_PATH", ""),
+                "implementation-executor": ctx.get(
+                    "IMPLEMENTATION_WORKER_PREAMBLE_PATH", ""
+                ),
+                "implementation-verifier": ctx.get(
+                    "IMPLEMENTATION_WORKER_PREAMBLE_PATH", ""
+                ),
+                "report-writer": ctx.get("REPORT_WRITER_PREAMBLE_PATH", ""),
+            },
+            "workerErrorContractPath": ctx.get("WORKER_ERROR_CONTRACT_PATH", ""),
         },
         "executorWorktree": dict(_mapping(payload.get("executorWorktree"))),
+        "verificationTarget": dict(_mapping(payload.get("verificationTarget"))),
         "sourceArtifacts": _hydrate_active_source_artifacts(ctx),
         "lazyReadPlan": dict(_mapping(payload.get("lazyReadPlan"))),
     }
@@ -190,6 +203,7 @@ def _hydrate_active_instruction_set(
     clarification_response = ""
     if inputs.get("hasClarificationResponse"):
         clarification_response = f"{instruction_set}/clarification-response.md"
+    target = _mapping(payload.get("verificationTarget"))
     return {
         "path": instruction_set,
         "analysisPacketPath": ctx.get("ANALYSIS_PACKET_RELATIVE_PATH", ""),
@@ -200,6 +214,8 @@ def _hydrate_active_instruction_set(
         "clarificationResponsePath": clarification_response,
         "finalReportTemplatePath": ctx.get("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", ""),
         "finalReportSchemaPath": ctx.get("FINAL_REPORT_SCHEMA_RELATIVE_PATH", ""),
+        "verificationTargetPath": str(target.get("path") or ""),
+        "verificationTargetDigest": str(target.get("digest") or ""),
     }
 
 
@@ -451,7 +467,18 @@ def _runtime_fields(paths: Mapping[str, Any]) -> dict[str, str]:
     runtime_home = Path(paths["runtime_home"])
     lead = runtime_home / "prompts" / "lead"
     return {
-        "WORKER_PROMPT_PREAMBLE_PATH": str(runtime_home / "templates" / "worker-prompt-preamble.md"),
+        "ANALYSIS_WORKER_PREAMBLE_PATH": str(
+            runtime_home / "templates" / "worker-prompt-preamble.md"
+        ),
+        "IMPLEMENTATION_WORKER_PREAMBLE_PATH": str(
+            runtime_home / "templates" / "implementation-worker-preamble.md"
+        ),
+        "REPORT_WRITER_PREAMBLE_PATH": str(
+            runtime_home / "templates" / "report-writer-prompt-preamble.md"
+        ),
+        "WORKER_ERROR_CONTRACT_PATH": str(
+            runtime_home / "templates" / "worker-error-contract.md"
+        ),
         "OKSTRA_LEAD_CONTRACT_PATH": str(lead / "okstra-lead-contract.md"),
         "OKSTRA_CONTEXT_LOADER_PATH": str(lead / "context-loader.md"),
         "OKSTRA_TEAM_CONTRACT_PATH": str(lead / "team-contract.md"),

package/runtime/python/okstra_ctl/paths.py

@@ -265,9 +265,18 @@ def compute_run_paths(
         "TASK_TYPE_SEGMENT": task_type_segment,
         "OKSTRA_ROOT": str(okstra_root),
         "OKSTRA_TASKS_ROOT": str(tasks_root),
-        "WORKER_PROMPT_PREAMBLE_PATH": str(
+        "ANALYSIS_WORKER_PREAMBLE_PATH": str(
             runtime_home / "templates" / "worker-prompt-preamble.md"
         ),
+        "IMPLEMENTATION_WORKER_PREAMBLE_PATH": str(
+            runtime_home / "templates" / "implementation-worker-preamble.md"
+        ),
+        "REPORT_WRITER_PREAMBLE_PATH": str(
+            runtime_home / "templates" / "report-writer-prompt-preamble.md"
+        ),
+        "WORKER_ERROR_CONTRACT_PATH": str(
+            runtime_home / "templates" / "worker-error-contract.md"
+        ),
         "OKSTRA_LEAD_CONTRACT_PATH": str(
             runtime_home / "prompts" / "lead" / "okstra-lead-contract.md"
         ),