okstra 0.128.0 → 0.129.0

package/runtime/python/okstra_ctl/context_cost.py

@@ -125,6 +125,57 @@ def _installed_or_dev(installed: Path, dev_relative: str) -> Path:
     return Path(__file__).resolve().parents[2] / dev_relative
 
 
+def _runtime_template(filename: str) -> Path:
+    return _installed_or_dev(
+        Path.home() / ".okstra" / "templates" / filename,
+        f"templates/{filename}",
+    )
+
+
+def _header_path(prompt_path: Path | None, header: str) -> Path | None:
+    if prompt_path is None or not prompt_path.is_file():
+        return None
+    prefix = f"**{header}:**"
+    for line in prompt_path.read_text(encoding="utf-8", errors="replace").splitlines():
+        stripped = line.strip()
+        if stripped.startswith(prefix):
+            value = stripped[len(prefix):].strip().strip("`")
+            return Path(value) if value else None
+    return None
+
+
+def _prompt_contract_paths(
+    prompt_path: Path | None,
+    default_preamble: str,
+) -> tuple[Path, Path]:
+    selected_preamble = _header_path(prompt_path, "Worker Preamble Path")
+    selected_error = _header_path(prompt_path, "Worker Error Contract Path")
+    preamble = (
+        selected_preamble
+        if selected_preamble and selected_preamble.is_file()
+        else _runtime_template(
+            selected_preamble.name if selected_preamble else default_preamble
+        )
+    )
+    error_contract = (
+        selected_error
+        if selected_error and selected_error.is_file()
+        else _runtime_template("worker-error-contract.md")
+    )
+    return preamble, error_contract
+
+
+def _initial_prompt(run_dir: Path | None, *, report_writer: bool) -> Path | None:
+    if run_dir is None:
+        return None
+    candidates = sorted((run_dir / "prompts").glob("*.md"))
+    for path in candidates:
+        is_report_writer = "report-writer" in path.name
+        if is_report_writer == report_writer and "-reverify-r" not in path.name:
+            return path
+    return None
+
+
 def _instruction_set_metric(task_root: Path, project_root: Path) -> dict:
     instruction_set = task_root / "instruction-set"
     files = _all_files(instruction_set)
@@ -233,21 +284,31 @@ def _lead_phase1_metric(
     }
 
 
-def _analysis_worker_metric(task_root: Path, project_root: Path) -> dict:
+def _analysis_worker_metric(
+    task_root: Path,
+    project_root: Path,
+    run_dir: Path | None,
+    task_type: str,
+) -> dict:
     instruction_set = task_root / "instruction-set"
     full_contract_files = [instruction_set / name for name in INPUT_FILES]
-    preamble = _installed_or_dev(
-        Path.home() / ".okstra" / "templates" / "worker-prompt-preamble.md",
-        "templates/worker-prompt-preamble.md",
+    default_preamble = (
+        "implementation-worker-preamble.md"
+        if task_type == "implementation"
+        else "worker-prompt-preamble.md"
     )
-    full_contract_files.append(preamble)
+    preamble, error_contract = _prompt_contract_paths(
+        _initial_prompt(run_dir, report_writer=False),
+        default_preamble,
+    )
+    full_contract_files.extend((preamble, error_contract))
     full_file_count, full_byte_count = _count_files(full_contract_files)
 
     packet = instruction_set / "analysis-packet.md"
     legacy_packet = instruction_set / "task-packet.md"
     primary_packet = packet if packet.is_file() else legacy_packet
     has_packet = primary_packet.is_file()
-    packet_files = [primary_packet, preamble] if has_packet else []
+    packet_files = [primary_packet, preamble, error_contract] if has_packet else []
     packet_file_count, packet_byte_count = _count_files(packet_files)
     mode = "analysis-packet-primary" if packet.is_file() else "full-input-contract"
     byte_count = packet_byte_count if packet.is_file() else full_byte_count
@@ -266,6 +327,8 @@ def _analysis_worker_metric(task_root: Path, project_root: Path) -> dict:
         "legacyFullContractFileCount": full_file_count,
         "estimatedPacketModeBytesPerWorker": packet_byte_count,
         "estimatedReductionPercent": reduction_percent,
+        "promptPreamblePath": str(preamble),
+        "workerErrorContractPath": str(error_contract),
         "files": [project_rel(path, project_root) for path in current_files if path.is_file()],
         "legacyFullContractFiles": [
             project_rel(path, project_root)
@@ -313,6 +376,11 @@ def _report_writer_metric(run_dir: Path | None, task_root: Path, project_root: P
         instruction_set / "final-report-template.md",
         instruction_set / "final-report-schema.json",
     ])
+    preamble, error_contract = _prompt_contract_paths(
+        _initial_prompt(run_dir, report_writer=True),
+        "report-writer-prompt-preamble.md",
+    )
+    files.extend((preamble, error_contract))
     if run_dir is not None:
         files.extend(_current_seq_worker_results(run_dir))
         convergence = _latest_matching_file(
@@ -326,6 +394,8 @@ def _report_writer_metric(run_dir: Path | None, task_root: Path, project_root: P
         "fileCount": file_count,
         "bytes": byte_count,
         "estimatedTokens": _estimate_tokens(files),
+        "promptPreamblePath": str(preamble),
+        "workerErrorContractPath": str(error_contract),
         "files": [project_rel(path, project_root) for path in files if path.is_file()],
     }
 
@@ -357,7 +427,12 @@ def analyze_task_bundle(task_root: Path, project_root: Path) -> dict:
         },
         "instructionSet": _instruction_set_metric(task_root, project_root),
         "leadPhase1": _lead_phase1_metric(task_root, run_dir, manifest, project_root),
-        "analysisWorker": _analysis_worker_metric(task_root, project_root),
+        "analysisWorker": _analysis_worker_metric(
+            task_root,
+            project_root,
+            run_dir,
+            str(manifest.get("taskType") or ""),
+        ),
         "reportWriter": _report_writer_metric(run_dir, task_root, project_root),
         "skillAssets": _skill_assets_metric(),
     }

package/runtime/python/okstra_ctl/convergence.py

@@ -0,0 +1,223 @@
+"""CLI orchestration for deterministic Phase 5.5 convergence state."""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+from typing import Any
+
+from .convergence_engine import (
+    ConvergenceContractError,
+    apply_round_results,
+    finalize_working_state,
+    plan_next_round,
+    seed_working_state,
+    validate_final_state,
+    validate_working_state,
+)
+from .convergence_migration import (
+    SeedDecision,
+    archive_state_bytes,
+    decide_seed_action,
+    migration_record,
+)
+from .convergence_store import (
+    load_json_object,
+    write_final_state_atomic,
+    write_json_atomic,
+)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="okstra convergence",
+        description="Advance and validate deterministic re-verification state.",
+    )
+    subparsers = parser.add_subparsers(dest="operation", required=True)
+
+    seed = subparsers.add_parser("seed", help="create, resume, or recover working state")
+    seed.add_argument("--groups", type=Path, required=True)
+    seed.add_argument("--work-state", type=Path, required=True)
+    seed.add_argument("--final-state", type=Path, required=True)
+    seed.add_argument("--migration-dir", type=Path, required=True)
+    seed.add_argument("--restart-from-round0", action="store_true")
+
+    plan = subparsers.add_parser("plan-round", help="write the next dispatch plan")
+    plan.add_argument("--work-state", type=Path, required=True)
+    plan.add_argument("--plan", type=Path, required=True)
+
+    apply = subparsers.add_parser("apply-round", help="apply structured round results")
+    apply.add_argument("--work-state", type=Path, required=True)
+    apply.add_argument("--plan", type=Path, required=True)
+    apply.add_argument("--results", type=Path, required=True)
+
+    finalize = subparsers.add_parser("finalize", help="write the public final state")
+    finalize.add_argument("--work-state", type=Path, required=True)
+    finalize.add_argument("--output", type=Path, required=True)
+
+    validate = subparsers.add_parser("validate", help="validate a persisted state")
+    validate.add_argument("--state", type=Path, required=True)
+    validate.add_argument("--kind", choices=("working", "final"), required=True)
+    return parser
+
+
+def _emit(operation: str, action: str, path: Path) -> None:
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "operation": operation,
+                "action": action,
+                "path": str(path),
+            },
+            ensure_ascii=False,
+        )
+    )
+
+
+def _archive_existing_states(
+    *,
+    work_state_path: Path,
+    final_state_path: Path,
+    migration_dir: Path,
+) -> dict[str, str] | None:
+    records: list[dict[str, str]] = []
+    for path in (work_state_path, final_state_path):
+        if not path.exists():
+            continue
+        archive_path, digest = archive_state_bytes(
+            source_path=path,
+            migration_dir=migration_dir,
+        )
+        records.append(migration_record(path, archive_path, digest))
+    if not records:
+        return None
+    final_record = next(
+        (record for record in records if record["sourcePath"] == str(final_state_path)),
+        None,
+    )
+    return final_record or records[0]
+
+
+def _resume_after_legacy_final(
+    decision: SeedDecision,
+    *,
+    work_state_path: Path,
+    final_state_path: Path,
+    migration_dir: Path,
+) -> None:
+    if decision.archive_path is None:
+        return
+    archive_path, digest = archive_state_bytes(
+        source_path=final_state_path,
+        migration_dir=migration_dir,
+    )
+    state = load_json_object(work_state_path)
+    state["migration"] = migration_record(final_state_path, archive_path, digest)
+    write_json_atomic(work_state_path, state)
+
+
+def _seed(args: argparse.Namespace) -> tuple[str, Path]:
+    grouped_input = load_json_object(args.groups)
+    decision = decide_seed_action(
+        grouped_input=grouped_input,
+        work_state_path=args.work_state,
+        final_state_path=args.final_state,
+        restart_from_round0=args.restart_from_round0,
+    )
+    if decision.action == "reuse-final":
+        return decision.action, args.final_state
+    if decision.action == "resume-work":
+        _resume_after_legacy_final(
+            decision,
+            work_state_path=args.work_state,
+            final_state_path=args.final_state,
+            migration_dir=args.migration_dir,
+        )
+        return decision.action, args.work_state
+
+    state = seed_working_state(grouped_input)
+    if decision.action == "restart-round0":
+        migration = _archive_existing_states(
+            work_state_path=args.work_state,
+            final_state_path=args.final_state,
+            migration_dir=args.migration_dir,
+        )
+        if migration is None:
+            raise ConvergenceContractError("restart-round0 has no state to archive")
+        state["migration"] = migration
+    write_json_atomic(args.work_state, state)
+    return decision.action, args.work_state
+
+
+def _plan_round(args: argparse.Namespace) -> tuple[str, Path]:
+    state = load_json_object(args.work_state)
+    errors = validate_working_state(state)
+    if errors:
+        raise ConvergenceContractError("invalid working state: " + "; ".join(errors))
+    plan = plan_next_round(state)
+    write_json_atomic(args.plan, plan)
+    return str(plan["action"]), args.plan
+
+
+def _apply_round(args: argparse.Namespace) -> tuple[str, Path]:
+    state = load_json_object(args.work_state)
+    plan = load_json_object(args.plan)
+    results = load_json_object(args.results)
+    updated = apply_round_results(state, plan, results)
+    errors = validate_working_state(updated)
+    if errors:
+        raise ConvergenceContractError("invalid updated working state: " + "; ".join(errors))
+    write_json_atomic(args.work_state, updated)
+    return "applied", args.work_state
+
+
+def _finalize(args: argparse.Namespace) -> tuple[str, Path]:
+    state = load_json_object(args.work_state)
+    final = finalize_working_state(state)
+    migration = state.get("migration")
+    write_final_state_atomic(args.output, final, migration=migration)
+    return "finalized", args.output
+
+
+def _validate(args: argparse.Namespace) -> tuple[str, Path]:
+    state = load_json_object(args.state)
+    errors = (
+        validate_working_state(state)
+        if args.kind == "working"
+        else validate_final_state(state)
+    )
+    if errors:
+        raise ConvergenceContractError("; ".join(errors))
+    return "valid", args.state
+
+
+def _execute(args: argparse.Namespace) -> tuple[str, Path]:
+    operations: dict[str, Any] = {
+        "seed": _seed,
+        "plan-round": _plan_round,
+        "apply-round": _apply_round,
+        "finalize": _finalize,
+        "validate": _validate,
+    }
+    return operations[args.operation](args)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        action, path = _execute(args)
+    except (ConvergenceContractError, json.JSONDecodeError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except OSError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    _emit(args.operation, action, path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+