okstra 0.128.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,7 +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_contract import validate_final_verification_prompt_paths
+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
 
 
@@ -184,7 +186,7 @@ def build_dispatch_plan(
         report_writer_model,
         options,
     )
-    _validate_initial_final_verification_prompts(manifest, jobs)
+    _validate_initial_prompts(manifest, jobs)
     return DispatchPlan(
         project_root=project_root,
         workspace_root=workspace_root.resolve(),
@@ -197,22 +199,18 @@ def build_dispatch_plan(
     )
 
 
-def _validate_initial_final_verification_prompts(
+def _validate_initial_prompts(
     manifest: Mapping[str, Any],
     jobs: Sequence[WorkerJob],
 ) -> None:
-    if manifest.get("taskType") != "final-verification":
-        return
-    prompt_paths = {
-        job.worker_id: job.prompt_path
+    records = [
+        PromptRecord(job.worker_id, job.dispatch_kind, job.prompt_path)
         for job in jobs
-        if job.worker_id != REPORT_WRITER_WORKER_ID
-        and job.dispatch_kind == "initial"
-        and "-reverify-r" not in job.prompt_path.name
-    }
-    errors = validate_final_verification_prompt_paths(prompt_paths)
+    ]
+    errors = validate_initial_prompt_records(manifest=manifest, records=records)
     if errors:
-        raise DispatchError("final-verification prompt contract: " + "; ".join(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:
@@ -334,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,
@@ -798,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
@@ -808,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/path_hints.py

@@ -98,6 +98,17 @@ 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"))),
@@ -456,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"
         ),

package/runtime/python/okstra_ctl/render.py

@@ -376,6 +376,22 @@ def _active_runtime_resources(ctx: dict) -> dict:
     return {
         "codingPreflightDir": ctx.get("OKSTRA_CODING_PREFLIGHT_DIR")
         or str(runtime_home / "prompts" / "coding-preflight"),
+        "workerPreamblePathByAudience": {
+            "analysis": ctx.get("ANALYSIS_WORKER_PREAMBLE_PATH")
+            or str(runtime_home / "templates" / "worker-prompt-preamble.md"),
+            "implementation-executor": ctx.get(
+                "IMPLEMENTATION_WORKER_PREAMBLE_PATH"
+            )
+            or str(runtime_home / "templates" / "implementation-worker-preamble.md"),
+            "implementation-verifier": ctx.get(
+                "IMPLEMENTATION_WORKER_PREAMBLE_PATH"
+            )
+            or str(runtime_home / "templates" / "implementation-worker-preamble.md"),
+            "report-writer": ctx.get("REPORT_WRITER_PREAMBLE_PATH")
+            or str(runtime_home / "templates" / "report-writer-prompt-preamble.md"),
+        },
+        "workerErrorContractPath": ctx.get("WORKER_ERROR_CONTRACT_PATH")
+        or str(runtime_home / "templates" / "worker-error-contract.md"),
     }
 
 
@@ -1783,6 +1799,19 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
     coding_preflight_dir = ctx.get("OKSTRA_CODING_PREFLIGHT_DIR") or str(
         home_prompts / "coding-preflight"
     )
+    runtime_templates = okstra_home() / "templates"
+    analysis_preamble = ctx.get("ANALYSIS_WORKER_PREAMBLE_PATH") or str(
+        runtime_templates / "worker-prompt-preamble.md"
+    )
+    implementation_preamble = ctx.get("IMPLEMENTATION_WORKER_PREAMBLE_PATH") or str(
+        runtime_templates / "implementation-worker-preamble.md"
+    )
+    report_writer_preamble = ctx.get("REPORT_WRITER_PREAMBLE_PATH") or str(
+        runtime_templates / "report-writer-prompt-preamble.md"
+    )
+    worker_error_contract = ctx.get("WORKER_ERROR_CONTRACT_PATH") or str(
+        runtime_templates / "worker-error-contract.md"
+    )
     okstra_runtime_resources_block = (
         "## Okstra Runtime Resources\n"
         "\n"
@@ -1795,7 +1824,11 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         f"- Convergence contract: `{convergence_path}`\n"
         f"- Plan-body verification contract (implementation-planning Phase 6 sub-step only): `{plan_body_verification_path}`\n"
         f"- Report writer contract: `{report_writer_path}`\n"
-        f"- Coding preflight pack: `{coding_preflight_dir}`"
+        f"- Coding preflight pack: `{coding_preflight_dir}`\n"
+        f"- Analysis worker preamble: `{analysis_preamble}`\n"
+        f"- Implementation worker preamble: `{implementation_preamble}`\n"
+        f"- Report writer preamble: `{report_writer_preamble}`\n"
+        f"- Shared worker error contract: `{worker_error_contract}`"
     )
 
     def fmt_assignment(role: str, model: str, execution: str) -> str:
@@ -1915,10 +1948,6 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         "the selected adapter's mapping. Follow the lifecycle core's lazy-read rules "
         "for support resources; do not invoke hidden/internal skills."
     )
-    worker_preamble_path = ctx.get(
-        "WORKER_PROMPT_PREAMBLE_PATH",
-        str(okstra_home() / "templates" / "worker-prompt-preamble.md"),
-    )
     worker_dispatch_guidance = (
         "## Worker Dispatch Contract\n"
         "\n"
@@ -1932,10 +1961,14 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         "- Use `await_workers` through the selected adapter and confirm terminal state "
         "plus every required Result Path. File presence alone is never a signal to "
         "skip; worker selection and skipped status come from `team-state`.\n"
-        "- Every worker prompt must include the anchor header "
-        f"`**Worker Preamble Path:** {worker_preamble_path}`. That file is the canonical "
-        "source for Required Reading, Error Reporting, and Output sections; do not "
-        "re-inline those blocks into worker prompt bodies."
+        "- Resolve the worker's PromptPlan audience and inject exactly one "
+        "`**Worker Preamble Path:**` from the audience map: "
+        f"analysis=`{analysis_preamble}`, implementation executor/verifier="
+        f"`{implementation_preamble}`, report-writer=`{report_writer_preamble}`.\n"
+        "- Every initial worker prompt also injects "
+        f"`**Worker Error Contract Path:** {worker_error_contract}`. The selected "
+        "preamble owns audience procedure; the shared error contract owns error "
+        "schema and write rules. Do not re-inline either contract."
     )
 
     if lead_runtime == "external":
@@ -2006,12 +2039,24 @@ def apply_lead_prompt_defaults(ctx: dict) -> None:
     ctx.setdefault("STAGE_INTEGRATION", "")
     runtime_home = okstra_home()
     ctx.setdefault(
-        "WORKER_PROMPT_PREAMBLE_PATH",
+        "ANALYSIS_WORKER_PREAMBLE_PATH",
         str(runtime_home / "templates" / "worker-prompt-preamble.md"),
     )
+    ctx.setdefault(
+        "IMPLEMENTATION_WORKER_PREAMBLE_PATH",
+        str(runtime_home / "templates" / "implementation-worker-preamble.md"),
+    )
+    ctx.setdefault(
+        "REPORT_WRITER_PREAMBLE_PATH",
+        str(runtime_home / "templates" / "report-writer-prompt-preamble.md"),
+    )
+    ctx.setdefault(
+        "WORKER_ERROR_CONTRACT_PATH",
+        str(runtime_home / "templates" / "worker-error-contract.md"),
+    )
     # Lead resource paths the launch template references directly. paths.py
     # seeds the production values; setdefault backfills callers that render the
-    # template without the full path ctx (mirrors WORKER_PROMPT_PREAMBLE_PATH).
+    # template without the full path ctx.
     ctx.setdefault(
         "OKSTRA_LEAD_CONTRACT_PATH",
         str(runtime_home / "prompts" / "lead" / "okstra-lead-contract.md"),