okstra 0.167.0 → 0.169.0

package/runtime/python/okstra_ctl/render.py

@@ -21,6 +21,7 @@ import hashlib
 import json
 import re
 import sys
+from collections.abc import Mapping
 from pathlib import Path
 
 from okstra_project.dirs import TASK_MANIFEST_FILENAME, OKSTRA_DIR_NAME, project_json_path
@@ -354,6 +355,58 @@ def _lead_assignment(ctx: dict) -> dict:
     }
 
 
+def _invocation_assignments(ctx: dict) -> dict:
+    raw = ctx.get("INVOCATION_ASSIGNMENTS_JSON", "")
+    try:
+        parsed = json.loads(raw) if raw else {}
+    except json.JSONDecodeError as exc:
+        raise ValueError("invalid invocation assignments JSON") from exc
+    if not isinstance(parsed, dict):
+        raise ValueError("invocation assignments must be an object")
+    return parsed
+
+
+def _agent_contract(ctx: dict) -> dict:
+    raw = ctx.get("AGENT_CONTRACT_JSON", "")
+    try:
+        parsed = json.loads(raw) if raw else {}
+    except json.JSONDecodeError as exc:
+        raise ValueError("invalid agent contract JSON") from exc
+    if not isinstance(parsed, dict):
+        raise ValueError("agent contract must be an object")
+    return parsed
+
+
+def _executor_contract(ctx: dict) -> dict:
+    runner = ctx.get("EXECUTOR_RUNNER", "")
+    dispatch_mode = ctx.get("EXECUTOR_DISPATCH_MODE", "")
+    host_model_value = ctx.get("EXECUTOR_HOST_MODEL_VALUE") or None
+    expected_mode = {
+        "native-session": "host-native",
+        "cli-wrapper": "worker-dispatch",
+    }.get(runner)
+    if expected_mode is None or dispatch_mode != expected_mode:
+        raise ValueError(
+            "executor runner and dispatch mode must be native-session/host-native "
+            "or cli-wrapper/worker-dispatch"
+        )
+    if runner == "native-session" and not host_model_value:
+        raise ValueError("native-session executor requires host model value")
+    if runner == "cli-wrapper" and host_model_value is not None:
+        raise ValueError("cli-wrapper executor must not define host model value")
+    return {
+        "workerId": ctx.get("EXECUTOR_WORKER_ID", ""),
+        "provider": ctx.get("EXECUTOR_PROVIDER", ""),
+        "displayName": ctx.get("EXECUTOR_DISPLAY_NAME", ""),
+        "model": ctx.get("EXECUTOR_MODEL_DISPLAY", ""),
+        "modelExecutionValue": ctx.get("EXECUTOR_MODEL_EXECUTION_VALUE", ""),
+        "hostModelValue": host_model_value,
+        "runner": runner,
+        "dispatchMode": dispatch_mode,
+        "appliesTo": "implementation",
+    }
+
+
 def _worker_assignments(ctx: dict) -> list[dict]:
     raw = ctx.get("WORKER_ASSIGNMENTS_JSON", "")
     if raw:
@@ -648,6 +701,7 @@ def render_active_run_context(active_context_path: str, ctx: dict) -> None:
         "task": _active_task(ctx),
         "workflow": _active_workflow(ctx),
         "run": _active_run(ctx),
+        "agentContract": _agent_contract(ctx),
         "instructionSet": _active_instruction_set(ctx),
         "workers": _active_workers(ctx),
         "errorLogs": _active_error_logs(ctx),
@@ -690,6 +744,8 @@ def render_team_state(team_state_path: str, ctx: dict) -> None:
         "leadRuntime": _lead_runtime(ctx),
         "leadAssignment": _lead_assignment(ctx),
         "workerAssignments": _worker_assignments(ctx),
+        "agentContract": _agent_contract(ctx),
+        "invocationAssignments": _invocation_assignments(ctx),
         "leadAdapter": _lead_adapter(ctx, worker_dispatch_plan),
         "leadEventsPath": ctx.get("LEAD_EVENTS_RELATIVE_PATH", ""),
         "runDirectoryPath": ctx.get("RUN_DIR_RELATIVE_PATH", ""),
@@ -1341,10 +1397,8 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
             "referenceExpectationsPath": ctx.get(
                 "REFERENCE_EXPECTATIONS_RELATIVE_PATH", ""
             ),
-            "leadExecutionPromptPath": ctx.get("INSTRUCTION_SET_RELATIVE_PATH", "")
-            + "/lead-execution-prompt.md",
-            "claudeExecutionPromptPath": ctx.get("INSTRUCTION_SET_RELATIVE_PATH", "")
-            + "/claude-execution-prompt.md",
+            "leadExecutionPromptPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
+            "claudeExecutionPromptPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
             "leadPromptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
             "workerPromptsDirectoryPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
             "workerPromptPathByWorkerId": worker_prompt_paths,
@@ -1567,6 +1621,8 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "runtimeResolution": _runtime_resolution(ctx),
         "leadAssignment": _lead_assignment(ctx),
         "workerAssignments": _worker_assignments(ctx),
+        "agentContract": _agent_contract(ctx),
+        "invocationAssignments": _invocation_assignments(ctx),
         "leadAdapter": _lead_adapter(ctx, worker_dispatch_plan),
         "workCategory": task_manifest.get(
             "workCategory", ctx.get("WORKFLOW_WORK_CATEGORY", "unknown")
@@ -1595,6 +1651,33 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "runManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
         "leadEventsPath": ctx.get("LEAD_EVENTS_RELATIVE_PATH", ""),
         "promptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
+        "leadInstructionsPath": ctx.get("LEAD_INSTRUCTIONS_RELATIVE_PATH", ""),
+        "leadExecutionPromptPath": ctx.get(
+            "RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""
+        ),
+        "leadPromptMetadataPath": ctx.get(
+            "LEAD_PROMPT_METADATA_RELATIVE_PATH", ""
+        ),
+        "resources": {
+            "leadInstructionsPath": ctx.get(
+                "LEAD_INSTRUCTIONS_RELATIVE_PATH", ""
+            ),
+            "leadExecutionPromptPath": ctx.get(
+                "RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""
+            ),
+            "leadPromptMetadataPath": ctx.get(
+                "LEAD_PROMPT_METADATA_RELATIVE_PATH", ""
+            ),
+            "leadPromptSnapshotPath": ctx.get(
+                "RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""
+            ),
+            "claudeExecutionPromptPath": ctx.get(
+                "RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""
+            ),
+        },
+        "invocationReservationRootPath": ctx.get(
+            "INVOCATION_RESERVATION_ROOT_RELATIVE_PATH", ""
+        ),
         "workerPromptsDirectoryPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
         "workerPromptPathByWorkerId": worker_prompt_paths,
         "expectedReportPath": ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
@@ -1664,14 +1747,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
             "disallowLeadSoloAnalysisAsWorkerResult": True,
             "disallowGenericParallelOnlyExecution": True,
             "preferredCompletedWorkerResults": len(reviewers),
-            "executor": {
-                "provider": ctx.get("EXECUTOR_PROVIDER", ""),
-                "displayName": ctx.get("EXECUTOR_DISPLAY_NAME", ""),
-                "workerAgent": ctx.get("EXECUTOR_WORKER_AGENT", ""),
-                "model": ctx.get("EXECUTOR_MODEL_DISPLAY", ""),
-                "modelExecutionValue": ctx.get("EXECUTOR_MODEL_EXECUTION_VALUE", ""),
-                "appliesTo": "implementation",
-            },
+            "executor": _executor_contract(ctx),
         },
         "validation": {
             "required": True,
@@ -1698,9 +1774,138 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
     )
     if _lead_runtime(ctx) == "claude-code":
         payload["claudeSessionId"] = ctx.get("CLAUDE_SESSION_ID", "")
+    _guard_invocation_manifest_rewrite(existing_run_manifest, payload)
     _write_json(Path(run_manifest_path), payload)
 
 
+_MODEL_ASSIGNMENT_KEYS = {
+    "provider",
+    "model",
+    "modelExecutionValue",
+    "runner",
+    "hostRuntime",
+    "hostModelValue",
+}
+_AGENT_CONTRACT_KEYS = {
+    "schemaVersion",
+    "dutyRootPath",
+    "catalogDigest",
+    "invocationReservationRootPath",
+    "allowedAudiences",
+    "authorizedPaths",
+}
+_IMMUTABLE_INVOCATION_KEYS = (
+    "agentContract",
+    "invocationAssignments",
+    "leadAssignment",
+    "workerAssignments",
+    "runDirectoryPath",
+    "runManifestPath",
+    "leadInstructionsPath",
+    "leadExecutionPromptPath",
+    "promptSnapshotPath",
+    "leadPromptMetadataPath",
+    "resources",
+    "invocationReservationRootPath",
+    "workerPromptsDirectoryPath",
+    "workerPromptPathByWorkerId",
+    "workerResultsDirectoryPath",
+    "expectedReportPath",
+    "reportTemplatePath",
+)
+
+
+def _guard_invocation_manifest_rewrite(
+    existing: Mapping[str, object],
+    proposed: Mapping[str, object],
+) -> None:
+    existing_has_contract = bool(existing.get("agentContract"))
+    proposed_has_contract = bool(proposed.get("agentContract"))
+    if existing_has_contract:
+        _validate_invocation_manifest(existing)
+    if proposed_has_contract:
+        _validate_invocation_manifest(proposed)
+    elif existing_has_contract:
+        raise ValueError("incomplete invocation manifest: proposed contract missing")
+    if not existing_has_contract:
+        return
+    drift = [
+        key
+        for key in _IMMUTABLE_INVOCATION_KEYS
+        if existing.get(key) != proposed.get(key)
+    ]
+    if drift:
+        raise ValueError(
+            "immutable invocation manifest fields changed: " + ", ".join(drift)
+        )
+
+
+def _validate_invocation_manifest(payload: Mapping[str, object]) -> None:
+    contract = payload.get("agentContract")
+    assignments = payload.get("invocationAssignments")
+    if (
+        not isinstance(contract, Mapping)
+        or set(contract) != _AGENT_CONTRACT_KEYS
+        or contract.get("schemaVersion") != 1
+        or not isinstance(assignments, Mapping)
+        or not assignments
+    ):
+        raise ValueError("incomplete invocation manifest")
+    if any(
+        not isinstance(item, Mapping) or set(item) != _MODEL_ASSIGNMENT_KEYS
+        for item in assignments.values()
+    ):
+        raise ValueError("incomplete invocation manifest assignments")
+    _validate_compatibility_projections(payload, assignments)
+    for key in (
+        item
+        for item in _IMMUTABLE_INVOCATION_KEYS[4:]
+        if item != "workerPromptPathByWorkerId"
+    ):
+        if not payload.get(key):
+            raise ValueError(f"incomplete invocation manifest path: {key}")
+    workers = payload.get("workerAssignments")
+    worker_prompt_paths = payload.get("workerPromptPathByWorkerId")
+    expected_worker_ids = {
+        str(worker.get("workerId") or "")
+        for worker in workers
+        if isinstance(worker, Mapping)
+    }
+    if (
+        not isinstance(worker_prompt_paths, Mapping)
+        or set(worker_prompt_paths) != expected_worker_ids
+        or any(
+            not isinstance(path, str) or not path
+            for path in worker_prompt_paths.values()
+        )
+    ):
+        raise ValueError(
+            "incomplete invocation manifest path: workerPromptPathByWorkerId"
+        )
+
+
+def _validate_compatibility_projections(
+    payload: Mapping[str, object],
+    assignments: Mapping[str, object],
+) -> None:
+    lead = payload.get("leadAssignment")
+    workers = payload.get("workerAssignments")
+    if not isinstance(lead, Mapping) or not isinstance(workers, list):
+        raise ValueError("incomplete invocation manifest compatibility projection")
+    if _model_projection(lead) != assignments.get("lead"):
+        raise ValueError("immutable invocation manifest lead projection drift")
+    for worker in workers:
+        if not isinstance(worker, Mapping):
+            raise ValueError("incomplete invocation manifest worker projection")
+        reference = f"initial/{worker.get('workerId', '')}"
+        if _model_projection(worker) != assignments.get(reference):
+            raise ValueError("immutable invocation manifest worker projection drift")
+
+
+def _model_projection(value: Mapping[str, object]) -> dict[str, object]:
+    return {key: value.get(key) for key in _MODEL_ASSIGNMENT_KEYS}
+
+
 def render_timeline(timeline_path: str, ctx: dict) -> None:
     task_manifest_path = Path(ctx.get("TASK_MANIFEST_PATH", ""))
     task_manifest = {}

package/runtime/python/okstra_ctl/report_finalize.py

@@ -27,6 +27,7 @@ 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, task_manifest_file
+from .dispatch_state import DispatchError, link_agent_dispatch_result
 
 
 STEP_CHECK_SOURCE = "check-source"
@@ -371,6 +372,15 @@ def run_finalize(
     for name, command in commands:
         if before_step is not None:
             before_step(name)
+        if name == STEP_VALIDATE_RUN:
+            try:
+                _link_lead_result_for_validation(ctx)
+            except (DispatchError, OSError, json.JSONDecodeError) as exc:
+                return {
+                    "ok": False,
+                    "reason": f"lead result linkage failed: {exc}",
+                    "steps": steps,
+                }
         result = subprocess.run(
             command,
             cwd=ctx.project_root,
@@ -387,6 +397,40 @@ def run_finalize(
     return {"ok": True, "reason": "", "steps": steps}
 
 
+def _link_lead_result_for_validation(ctx: FinalizeContext) -> None:
+    """Link the lead-authored synthesis artifact before Phase 7 validation."""
+    manifest = _load_manifest(ctx.manifest_path)
+    contract = manifest.get("agentContract")
+    if not isinstance(contract, Mapping) or contract.get("schemaVersion") != 1:
+        return
+    team_state = _load_manifest(ctx.team_state_path)
+    lead_dispatches = [
+        row for row in (team_state.get("agentDispatches") or [])
+        if isinstance(row, Mapping)
+        and row.get("audience") == "lead"
+        and row.get("workerId") == "lead"
+    ]
+    if len(lead_dispatches) != 1:
+        return
+    convergence_value = string_value(manifest.get("convergenceStatePath"))
+    convergence_path = (
+        resolve_project_path(ctx.project_root, convergence_value)
+        if convergence_value else None
+    )
+    if convergence_path is not None and convergence_path.is_file():
+        result_path = convergence_path
+    elif ctx.task_type == "release-handoff" and ctx.data_path.is_file():
+        result_path = ctx.data_path
+    else:
+        return
+    link_agent_dispatch_result(
+        project_root=ctx.project_root,
+        run_manifest_path=ctx.manifest_path,
+        dispatch_id=str(lead_dispatches[0]["dispatchId"]),
+        result_path=result_path,
+    )
+
+
 def _load_manifest(path: Path) -> Mapping[str, Any]:
     try:
         payload = json.loads(path.read_text(encoding="utf-8"))