okstra 0.127.0 → 0.129.0

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -24,30 +24,23 @@ PROFILE_SECTIONS = (
     "Primary focus areas",
     "Expected output emphasis",
     "Non-goals",
-    "Clarification request policy",
 )
-PROFILE_SECTIONS_BY_TASK_TYPE = {
+WORKER_PROFILE_SECTIONS_BY_TASK_TYPE = {
     "requirements-discovery": (
-        "Fan-out",
-        "Decision-tree walk",
+        "Worker discovery procedure",
     ),
     "error-analysis": (
-        "Diagnosis loop",
+        "Worker diagnosis procedure",
     ),
     "implementation-planning": (
-        "Section heading contract",
-        "Required deliverable shape",
-        "No-placeholder rule",
-        "Self-review pass before finalising the report",
+        "Worker planning procedure",
+        "Design principles applied when scoring options",
     ),
     "final-verification": (
-        "Required deliverable shape",
-        "Self-review pass before finalising the report",
+        "Worker verification procedure",
     ),
     "improvement-discovery": (
-        "Phase 1.5 — Lead reflect-back grilling",
-        "Worker diversity rule",
-        "Decision-tree walk",
+        "Worker candidate procedure",
     ),
 }
 CLARIFICATION_SECTIONS = (
@@ -81,6 +74,7 @@ def build_analysis_packet(
     parts.extend(
         _intro_block(
             task_key,
+            task_type,
             instruction_set_relative_path,
             bool(clarification_response_path),
         )
@@ -113,6 +107,7 @@ def _packet_frontmatter(brief_text: str, task_key: str) -> str:
 
 def _intro_block(
     task_key: str,
+    task_type: str,
     instruction_set: str,
     has_clarification: bool,
 ) -> list[str]:
@@ -132,6 +127,10 @@ def _intro_block(
         f"- Analysis material: `{instruction_set}/analysis-material.md`",
         f"- Reference expectations: `{instruction_set}/reference-expectations.md`",
     ]
+    if task_type == "final-verification":
+        lines.append(
+            f"- Verification target: `{instruction_set}/verification-target.md`"
+        )
     if has_clarification:
         lines.append(
             f"- Clarification response: `{instruction_set}/clarification-response.md`"
@@ -151,7 +150,7 @@ def _brief_block(brief_text: str) -> list[str]:
 def _profile_block(task_type: str, profile_text: str) -> list[str]:
     section_names = (
         PROFILE_SECTIONS
-        + PROFILE_SECTIONS_BY_TASK_TYPE.get(task_type, ())
+        + WORKER_PROFILE_SECTIONS_BY_TASK_TYPE.get(task_type, ())
     )
     profile_sections = _extract_sections(profile_text, section_names)
     profile_bullets = _extract_bullet_sections(profile_text, section_names)

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -27,6 +27,18 @@ from .path_hints import hydrate_active_run_context
 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 (
+    analysis_input_lines as _analysis_input_lines,
+    analysis_prompt_body as _analysis_prompt_body,
+    existing_input_lines as _existing_input_lines,
+    instruction_path as _instruction_path,
+    mcp_pointer_line as _mcp_pointer_line,
+)
+from .worker_prompt_policy import (
+    PromptPlan,
+    resolve_prompt_plan_for_manifest,
+)
 
 
 SUPPORTED_CLI_WORKERS = {
@@ -38,10 +50,6 @@ BACKEND_MIXED = "mixed"
 MAX_WORKER_ATTEMPTS = 2
 REPORT_WRITER_WORKER_ID = "report-writer"
 REPORT_LANGUAGE_VALUES = {"en", "ko", "auto"}
-ANALYSIS_WORKER_LABELS = {
-    "codex": "Codex worker",
-    "antigravity": "Antigravity worker",
-}
 
 
 class DispatchError(Exception):
@@ -182,6 +190,7 @@ def build_dispatch_plan(
         )
         for worker_id in selected_workers
     )
+    _validate_initial_prompts(manifest, workers)
     return DispatchPlan(
         project_root=project_root,
         workspace_root=workspace_root,
@@ -193,6 +202,20 @@ def build_dispatch_plan(
     )
 
 
+def _validate_initial_prompts(
+    manifest: Mapping[str, Any],
+    workers: Sequence[WorkerDispatch],
+) -> None:
+    records = [
+        PromptRecord(worker.worker_id, "initial", worker.prompt_path)
+        for worker in workers
+    ]
+    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) -> int:
     _set_dispatch_mode(plan.team_state_path, _dispatch_mode(plan.workers))
     for worker in plan.workers:
@@ -441,6 +464,7 @@ def _render_missing_analysis_worker_prompt(
     prompt_rel = _worker_prompt_path(manifest, worker_id)
     model = _require_string(worker_state, "modelExecutionValue")
     role = _analysis_pane_role(manifest, active_context, worker_id)
+    plan = _initial_prompt_plan(manifest, worker_id)
     lines = _base_prompt_headers(
         project_root=project_root,
         manifest=manifest,
@@ -450,7 +474,16 @@ def _render_missing_analysis_worker_prompt(
         result_rel=result_rel,
     )
     lines.extend(_worktree_headers(manifest, active_context, role))
-    lines.extend(_analysis_prompt_body(manifest, active_context, worker_id, model, role))
+    lines.extend(
+        _analysis_prompt_body(
+            manifest,
+            active_context,
+            worker_id,
+            model,
+            role,
+            plan,
+        )
+    )
     executor_tail = _implementation_executor_tail(
         manifest,
         active_context,
@@ -595,43 +628,6 @@ def _build_report_writer_dispatch(
     )
 
 
-def _analysis_prompt_body(
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    worker_id: str,
-    model: str,
-    role: str,
-) -> list[str]:
-    label = ANALYSIS_WORKER_LABELS[worker_id]
-    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),
-        "",
-        _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 _report_writer_prompt_body(
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any],
@@ -669,13 +665,6 @@ def _report_writer_prompt_body(
     ]
 
 
-def _mcp_pointer_line() -> str:
-    return (
-        '**MCP servers:** follow the task brief\'s "## Available MCP Servers" '
-        "section (already in your Required reading)."
-    )
-
-
 def _base_prompt_headers(
     *,
     project_root: Path,
@@ -691,6 +680,7 @@ def _base_prompt_headers(
             prompt_rel=prompt_rel,
             result_rel=result_rel,
             worker_id=worker_id,
+            dispatch_kind="initial",
             manifest=manifest,
             active_context=active_context,
         )
@@ -698,19 +688,18 @@ def _base_prompt_headers(
         raise DispatchError(str(exc)) from exc
 
 
-def _analysis_input_lines(
+def _initial_prompt_plan(
     manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-) -> list[str]:
-    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)
+    worker_id: str,
+) -> PromptPlan:
+    try:
+        return resolve_prompt_plan_for_manifest(
+            manifest=manifest,
+            worker_id=worker_id,
+            dispatch_kind="initial",
+        )
+    except ValueError as exc:
+        raise DispatchError(str(exc)) from exc
 
 
 def _report_writer_input_lines(
@@ -733,11 +722,6 @@ def _report_writer_input_lines(
     return lines or ["- No report-writer inputs were recorded in active-run-context."]
 
 
-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 _analysis_worker_result_lines(team_state: Mapping[str, Any]) -> list[str]:
     lines = []
     workers = team_state.get("workers")
@@ -755,19 +739,6 @@ def _analysis_worker_result_lines(team_state: Mapping[str, Any]) -> list[str]:
     return lines
 
 
-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 _analysis_pane_role(
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any],
@@ -800,7 +771,7 @@ def _worktree_headers(
 ) -> list[str]:
     task_type = _require_string(manifest, "taskType")
     worktree = _worktree_path(manifest, active_context)
-    if task_type not in {"implementation", "final-verification"} or not worktree:
+    if task_type != "implementation" or not worktree:
         return []
     headers = [f"**Worktree:** {worktree}"]
     if role == "executor":

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