okstra 0.174.0 → 0.176.0

package/runtime/bin/okstra-provider-exec.py

@@ -8,12 +8,13 @@ write scope in the order the CLIs are told it, and the role's idle budget.
 """
 from __future__ import annotations
 
+import json
 import os
 import shutil
 import sys
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Mapping
+from typing import Any, Callable, Mapping
 
 _HERE = Path(__file__).resolve().parent
 # ``okstra_ctl`` sits beside this file in the repo (``scripts/``) but under
@@ -26,7 +27,13 @@ sys.path.insert(0, str(_HERE))
 if _HOME_LIB.is_dir() and str(_HOME_LIB) not in sys.path:
     sys.path.append(str(_HOME_LIB))
 
-from okstra_ctl.domain.provider import ProviderSpec, UnknownProviderError  # noqa: E402
+from okstra_ctl.domain.provider import (  # noqa: E402
+    ProviderSpec,
+    ServedModelAttestation,
+    ServedModelNormalizer,
+    UnknownProviderError,
+)
+from okstra_ctl.domain.role import normalize_role, role_for_duty  # noqa: E402
 from okstra_ctl.domain.worker_exec import (  # noqa: E402
     ExecutionStrategy,
     WorkerExecRequest,
@@ -36,15 +43,32 @@ from okstra_ctl.registry.provider_registry import (  # noqa: E402
 )
 from okstra_ctl.worker_request import build_request, idle_timeout  # noqa: E402
 from okstra_ctl.worker_runner import LIVE, QUIET, run_worker  # noqa: E402
+from okstra_ctl.dispatch_core import verify_served_model  # noqa: E402
+from okstra_ctl.dispatch_state import DispatchError  # noqa: E402
+from okstra_ctl.execution_manifest import read_execution_manifest  # noqa: E402
+from okstra_ctl.write_policy import (  # noqa: E402
+    WriteEnforcement,
+    WritePolicy,
+    write_enforcement_from_payload,
+    write_policy_from_payload,
+)
+from okstra_ctl.model_pool import ModelPool  # noqa: E402
+from okstra_ctl.agent_invocation import (  # noqa: E402
+    AgentInvocationError,
+    agent_model_assignment_from_payload,
+    invocation_metadata_identity,
+)
 
 _USAGE = (
     "usage: okstra-provider-exec.py <provider> <project-root> "
     "<model-execution-value> <prompt-path> [worktree-path] [role] "
-    "[idle-timeout-seconds] [--presentation live|quiet] [--session-id <uuid>]"
+    "[idle-timeout-seconds] [--presentation live|quiet] [--session-id <uuid>] "
+    "[--invocation-metadata path]"
 )
 
 _PRESENTATION_FLAG = "--presentation"
 _SESSION_ID_FLAG = "--session-id"
+_INVOCATION_METADATA_FLAG = "--invocation-metadata"
 _PRESENTATIONS = (LIVE, QUIET)
 
 
@@ -62,6 +86,16 @@ class Invocation:
     log_path: Path
     status_path: Path
     status_extra: Mapping[str, Any]
+    served_model_normalizer: ServedModelNormalizer | None
+    served_model_verifier: Callable[[ServedModelAttestation], str] | None
+
+
+@dataclass(frozen=True)
+class _V2InvocationContext:
+    status_extra: Mapping[str, Any]
+    verify_attestation: Callable[[ServedModelAttestation], str]
+    write_policy: WritePolicy
+    write_enforcement: WriteEnforcement
 
 
 def parse_invocation(argv: list[str]) -> Invocation:
@@ -70,6 +104,7 @@ def parse_invocation(argv: list[str]) -> Invocation:
     # Empty unless the dispatcher issued one. Without it the CLI picks its own
     # id and nothing downstream can map that session back to this worker.
     positional, session_id = _take_flag(positional, _SESSION_ID_FLAG, "")
+    positional, metadata_raw = _take_flag(positional, _INVOCATION_METADATA_FLAG, "")
     if not 4 <= len(positional) <= 7:
         raise PreflightError(64, _USAGE)
     provider_id, project_root_raw, model, prompt_raw = positional[:4]
@@ -77,7 +112,6 @@ def parse_invocation(argv: list[str]) -> Invocation:
     role = positional[5] if len(positional) >= 6 and positional[5] else "worker"
     timeout_raw = positional[6] if len(positional) >= 7 and positional[6] else ""
 
-    spec = _provider_spec(provider_id)
     project_root = _existing_dir(project_root_raw, 65, "project-root")
     if not model:
         raise PreflightError(66, "model-execution-value is empty")
@@ -86,6 +120,32 @@ def parse_invocation(argv: list[str]) -> Invocation:
     worktree = (
         _existing_dir(worktree_raw, 68, "worktree-path") if worktree_raw else None
     )
+    spec = _provider_spec(provider_id)
+    status_extra: dict[str, Any] = {"wrapper": spec.wrapper, "role": role}
+    served_model_normalizer: ServedModelNormalizer | None = None
+    served_model_verifier: Callable[[ServedModelAttestation], str] | None = None
+    write_policy: WritePolicy | None = None
+    write_enforcement: WriteEnforcement | None = None
+    if metadata_raw:
+        context = _v2_status_extra(
+            metadata_path=_existing_file(
+                metadata_raw, 64, "invocation-metadata"
+            ),
+            project_root=project_root,
+            prompt_path=prompt_path,
+            provider_id=provider_id,
+            model=model,
+            role=role,
+        )
+        status_extra.update(context.status_extra)
+        served_model_normalizer = spec.served_model_normalizer
+        served_model_verifier = context.verify_attestation
+        write_policy = context.write_policy
+        write_enforcement = context.write_enforcement
+        if not spec.supports_role(role):
+            raise PreflightError(
+                64, f"provider {provider_id!r} does not support role {role!r}"
+            )
 
     request = build_request(
         prompt_text=prompt_path.read_text(encoding="utf-8"),
@@ -95,6 +155,8 @@ def parse_invocation(argv: list[str]) -> Invocation:
         role=role,
         idle_timeout_seconds=idle_timeout_seconds,
         session_id=session_id,
+        write_policy=write_policy,
+        write_enforcement=write_enforcement,
     )
     strategy = spec.exec_strategy
     _check_command(strategy, request)
@@ -104,7 +166,9 @@ def parse_invocation(argv: list[str]) -> Invocation:
         presentation=presentation,
         log_path=_log_path(prompt_path),
         status_path=Path(f"{prompt_path}.status.json"),
-        status_extra={"wrapper": spec.wrapper, "role": role},
+        status_extra=status_extra,
+        served_model_normalizer=served_model_normalizer,
+        served_model_verifier=served_model_verifier,
     )
 
 
@@ -149,6 +213,152 @@ def _take_presentation(argv: list[str]) -> tuple[list[str], str]:
     return positional, presentation
 
 
+def _v2_status_extra(
+    *,
+    metadata_path: Path,
+    project_root: Path,
+    prompt_path: Path,
+    provider_id: str,
+    model: str,
+    role: str,
+) -> _V2InvocationContext:
+    try:
+        metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise PreflightError(64, "invocation metadata is invalid") from exc
+    if not isinstance(metadata, dict):
+        raise PreflightError(64, "invocation metadata must be an object")
+    try:
+        identity = invocation_metadata_identity(metadata)
+        assignment = agent_model_assignment_from_payload(
+            metadata.get("modelAssignment")
+        )
+    except AgentInvocationError as exc:
+        raise PreflightError(64, str(exc)) from exc
+    if identity is None:
+        raise PreflightError(64, "new worker dispatch requires v2 invocation metadata")
+    if (
+        assignment.provider != provider_id
+        or assignment.model_execution_value != model
+    ):
+        raise PreflightError(64, "invocation metadata model assignment does not match wrapper")
+    try:
+        expected_role = role_for_duty(identity.duty_id)
+        actual_role = normalize_role(role)
+    except ValueError as exc:
+        raise PreflightError(64, f"invocation metadata role is invalid: {exc}") from exc
+    if expected_role != actual_role:
+        raise PreflightError(64, "invocation metadata duty does not match role")
+    prompt = metadata.get("prompt")
+    recorded_path = prompt.get("path") if isinstance(prompt, Mapping) else None
+    if not isinstance(recorded_path, str):
+        raise PreflightError(64, "invocation metadata prompt path is invalid")
+    recorded = Path(recorded_path)
+    if not recorded.is_absolute():
+        recorded = project_root / recorded
+    if recorded.resolve(strict=False) != prompt_path.resolve(strict=True):
+        raise PreflightError(64, "invocation metadata prompt does not match wrapper")
+    role_execution, invocation, pool = _execution_authority(
+        metadata=metadata,
+        project_root=project_root,
+        role_execution_ref=identity.role_execution_ref,
+        invocation_ref=identity.invocation_ref,
+    )
+    binding = role_execution.binding
+    if (
+        role_execution.participant_ref != identity.participant_ref
+        or role_execution.role != expected_role
+        or role_execution.provider != assignment.provider
+        or binding is None
+        or binding.runner != assignment.runner
+        or binding.resolved_execution_value != assignment.model_execution_value
+    ):
+        raise PreflightError(
+            64, "invocation metadata role execution binding does not match run manifest"
+        )
+    if role_execution.execution_label != identity.execution_label:
+        raise PreflightError(
+            64, "invocation metadata execution label does not match run manifest"
+        )
+
+    def verify_attestation(attestation: ServedModelAttestation) -> str:
+        try:
+            verify_served_model(role_execution, attestation, pool=pool)
+        except DispatchError as exc:
+            return str(exc)
+        return ""
+
+    try:
+        write_policy = write_policy_from_payload(invocation.write_policy)
+        write_enforcement = write_enforcement_from_payload(
+            invocation.write_enforcement
+        )
+    except ValueError as exc:
+        raise PreflightError(64, f"invocation write contract is invalid: {exc}") from exc
+
+    return _V2InvocationContext({
+        "schemaVersion": "2.0",
+        "executionIdentityVersion": 2,
+        "participantRef": identity.participant_ref,
+        "roleExecutionRef": identity.role_execution_ref,
+        "executionLabel": identity.execution_label,
+        "dutyId": identity.duty_id,
+        "invocationRef": identity.invocation_ref,
+        "attempt": identity.attempt,
+        "servedModelAttestation": {
+            "observedModel": None,
+            "normalizedModelRef": None,
+            "level": "unknown",
+            "source": "unavailable",
+        },
+        "writePolicyDigest": invocation.write_policy_digest,
+        "writeEnforcement": write_enforcement.to_payload(),
+    }, verify_attestation, write_policy, write_enforcement)
+
+
+def _execution_authority(
+    *,
+    metadata: Mapping[str, Any],
+    project_root: Path,
+    role_execution_ref: str,
+    invocation_ref: str,
+):
+    source = metadata.get("contractSource")
+    manifest_raw = source.get("runManifestPath") if isinstance(source, Mapping) else None
+    if not isinstance(manifest_raw, str) or not manifest_raw:
+        raise PreflightError(64, "invocation metadata run manifest is invalid")
+    manifest_path = Path(manifest_raw)
+    if not manifest_path.is_absolute():
+        manifest_path = project_root / manifest_path
+    try:
+        manifest_path = manifest_path.resolve(strict=True)
+        manifest_path.relative_to(project_root.resolve(strict=True))
+        manifest = read_execution_manifest(manifest_path)
+    except (OSError, ValueError) as exc:
+        raise PreflightError(64, "invocation metadata run manifest is invalid") from exc
+    role_execution = next((
+        row for row in manifest.role_executions
+        if row.role_execution_ref == role_execution_ref
+    ), None)
+    if role_execution is None:
+        raise PreflightError(
+            64, "invocation metadata role execution does not match run manifest"
+        )
+    invocation = next((
+        row for row in manifest.invocations
+        if row.invocation_ref == invocation_ref
+    ), None)
+    if invocation is None or invocation.role_execution_ref != role_execution_ref:
+        raise PreflightError(
+            64, "invocation metadata invocation does not match run manifest"
+        )
+    return (
+        role_execution,
+        invocation,
+        ModelPool.from_registry(default_provider_registry()),
+    )
+
+
 def _provider_spec(provider_id: str) -> ProviderSpec:
     try:
         spec = default_provider_registry().resolve(provider_id)
@@ -214,6 +424,8 @@ def main(argv: list[str]) -> int:
             log_path=invocation.log_path,
             status_path=invocation.status_path,
             status_extra=invocation.status_extra,
+            served_model_normalizer=invocation.served_model_normalizer,
+            served_model_verifier=invocation.served_model_verifier,
         )
     except PreflightError as exc:
         print(f"okstra-provider-exec: {exc}", file=sys.stderr)

package/runtime/bin/okstra-spawn-followups.py

@@ -50,6 +50,7 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 
+from okstra_ctl import next_phase  # noqa: E402
 from okstra_ctl.final_report_paths import final_report_markdown_path  # noqa: E402
 from okstra_ctl.paths import task_manifest_file  # noqa: E402
 from okstra_ctl.workflow import PHASE_SEQUENCE  # noqa: E402
@@ -199,10 +200,11 @@ def _spawn_one(
         "workflow": {
             "currentPhase": suggested,
             "currentPhaseState": "not-started",
-            "nextRecommendedPhase": suggested,
+            "nextRecommendedPhase": next_phase.make(
+                suggested, next_phase.STATUS_READY, "follow-up 으로 생성됨"
+            ),
             "phaseStates": {},
             "awaitingApproval": False,
-            "routingStatus": "follow-up-spawned",
         },
     }
     _write_manifest(task_manifest_file(task_root), manifest_payload)

package/runtime/bin/okstra.sh

@@ -222,6 +222,16 @@ PY_ARGS=(
 [[ -n "${DIRECTIVE-}" ]] && PY_ARGS+=(--directive "$DIRECTIVE")
 [[ -n "${FIX_CYCLE-}" ]] && PY_ARGS+=(--fix-cycle "$FIX_CYCLE")
 [[ -n "${WORKERS_OVERRIDE-}" ]] && PY_ARGS+=(--workers "$WORKERS_OVERRIDE")
+for role_count in "${ROLE_COUNTS[@]-}"; do
+  [[ -z "$role_count" ]] && continue
+  PY_ARGS+=(--role-count "$role_count")
+done
+for role_model in "${ROLE_MODELS[@]-}"; do
+  [[ -z "$role_model" ]] && continue
+  PY_ARGS+=(--role-model "$role_model")
+done
+[[ -n "${HOST_SESSION_CONTEXT_JSON-}" ]] && \
+  PY_ARGS+=(--host-session-context-json "$HOST_SESSION_CONTEXT_JSON")
 [[ -n "${LEAD_PROVIDER_OVERRIDE-}" ]] && PY_ARGS+=(--lead-provider "$LEAD_PROVIDER_OVERRIDE")
 [[ -n "${LEAD_MODEL_OVERRIDE-}" ]] && PY_ARGS+=(--lead-model "$LEAD_MODEL_OVERRIDE")
 [[ -n "${CLAUDE_MODEL_OVERRIDE-}" ]] && PY_ARGS+=(--claude-model "$CLAUDE_MODEL_OVERRIDE")

package/runtime/prompts/launch.template.md

@@ -18,11 +18,11 @@ For a new `implementation-planning` run, the plan-body sequence is initial verif
 {{PHASE_ALLOWED_OUTPUTS}}
 - Forbidden actions in this phase:
 {{PHASE_FORBIDDEN_ACTIONS}}
-- This run executes `{{WORKFLOW_CURRENT_PHASE}}` only. Do not start `{{WORKFLOW_NEXT_RECOMMENDED_PHASE}}` or any later phase inside this run, even if the user says "proceed to the next step" or similar.
+- This run executes `{{WORKFLOW_CURRENT_PHASE}}` only. Do not start any later phase inside this run, even if the user says "proceed to the next step" or similar. Which phase comes next is not decided yet — this run's final report decides it.
 {{STAGE_BATCH_DIRECTIVE}}
 {{VERIFICATION_TARGET}}
 {{STAGE_INTEGRATION}}
-- Phase advancement requires a new okstra invocation launched with `--task-type {{WORKFLOW_NEXT_RECOMMENDED_PHASE}}` after this run's final report is written and approved. The lead must not write source code, run builds/migrations/deployments, or otherwise produce artifacts of a different phase from inside this run.
+- Phase advancement requires a new okstra invocation, launched with an explicit `--task-type` after this run's final report is written and approved. The target of that run comes from the pointer this run's report authors into `workflow.nextRecommendedPhase`, and only when that pointer's `status` says it can be started. The lead must not write source code, run builds/migrations/deployments, or otherwise produce artifacts of a different phase from inside this run.
 - See `Lifecycle Phase Boundaries` in the lifecycle core contract (`{{OKSTRA_LEAD_CONTRACT_PATH}}`) for the canonical rules and the phase-transition checklist.
 
 {{TEAM_CREATION_GATE}}

package/runtime/prompts/lead/context-loader.md

@@ -46,9 +46,8 @@
 | `workflow.currentPhaseState` | Current lifecycle phase state |
 | `workflow.phaseStates` | Phase-by-phase lifecycle state map |
 | `workflow.lastCompletedPhase` | Last completed lifecycle phase |
-| `workflow.nextRecommendedPhase` | Next recommended lifecycle phase |
+| `workflow.nextRecommendedPhase` | Next-Phase Pointer — an object carrying the target phase, whether it can be started, and why. A projection of this report's Phase Routing; not authored here. Written per the Artifact Persistence Checklist in [report-writer](./report-writer.md); do not re-derive its rules here. |
 | `workflow.awaitingApproval` | Approval wait marker |
-| `workflow.routingStatus` | Routing decision status |
 | `workflow.lastSafeCheckpoint` | Safe resume checkpoint metadata |
 | `instructionSetPath` | Path to the `instruction-set/` **directory** containing `analysis-packet.md`, `analysis-profile.md`, `analysis-material.md`, `reference-expectations.md`, `task-brief.md`, `final-report-template.md`, and — only for task types whose host orchestration carries gates — `host-orchestration-rules.md` (see Step 4). Not a single-file path. |
 | `referenceExpectationsPath` | config/deployment expectation artifact path |

package/runtime/prompts/lead/convergence.md

@@ -84,7 +84,7 @@ Read the worker result files generated in Phase 4/5 and extract individual findi
   - Same semantics but disjoint ticket sets → separate groups (do NOT over-merge across tickets).
   - Only one worker confirms a finding → one single-source group.
 4. When grouping is ambiguous, prefer splitting over merging (avoid over-merging). Semantic matching, ticket-set equality, and evidence interpretation remain lead judgments; the engine does not perform fuzzy matching or decide whether evidence is credible.
-5. Write `runs/<task-type>/state/convergence-groups-<task-type>-<seq>.json`. Each group carries its `ticketIds`, `originWorker`, `originEvidence`, `discoveredBy`, and every `<worker>:<item-id>` source in `sourceItems`. For analysis sidetracks where ticket tagging is not required, `ticketIds: []` is the canonical value; never synthesize `"unknown"` or another placeholder. `scripts/okstra_ctl/convergence_engine.py` and `schemas/convergence-groups-v1.0.schema.json` enforce the required array field and reject non-string or blank entries while allowing the empty array. When a live command or external read produced reproducible evidence, also include `evidenceArtifacts[]` with its `.okstra/` path, SHA-256 digest, command, and environment. The field is optional because historical or inaccessible evidence may not have a captured artifact. The lead and verifier MUST NOT infer live or external evidence from wording or keyword matching; they use the finding's explicit claim, provenance, and supplied artifacts. Include the resolved worker roster in order with functional `audience` values; do not derive scope from provider or model identity. The `audience` enum is a convergence role, not a phase label: every finding-producing worker uses `analysis` — an `implementation` run's verifiers included — and only the report author uses `report-writer`. There is no `implementation-verifier` audience here; map the verifier roster to `analysis`.
+5. Write `runs/<task-type>/state/convergence-groups-<task-type>-<seq>.json`. Each group carries its `ticketIds`, `originWorker`, `originEvidence`, `discoveredBy`, and every `<worker>:<item-id>` source in `sourceItems`. For analysis sidetracks where ticket tagging is not required, `ticketIds: []` is the canonical value; never synthesize `"unknown"` or another placeholder. `scripts/okstra_ctl/convergence_engine.py` and the version-selected convergence-groups schema enforce the required array field and reject non-string or blank entries while allowing the empty array. When a live command or external read produced reproducible evidence, also include `evidenceArtifacts[]` with its `.okstra/` path, SHA-256 digest, command, and environment. The field is optional because historical or inaccessible evidence may not have a captured artifact. The lead and verifier MUST NOT infer live or external evidence from wording or keyword matching; they use the finding's explicit claim, provenance, and supplied artifacts. Include the resolved worker roster in order with functional `audience` values; do not derive scope from provider or model identity. In a v2 run, set top-level `schemaVersion: "2.0"`, `executionIdentityVersion: 2`, and `runManifestPath` to the current run manifest's exact canonical project-relative path. Write the groups artifact under that same resolved run directory's `state/` directory. Every v2 worker row also carries the paired `participantRef` and `sourceRoleExecutionRef` from that run manifest's canonical role state. Set `sourceRoleExecutionRef` to the selected source `RoleExecution` row's `roleExecutionRef`, not that row's `sourceRoleExecutionRef` field; a static source row has null in the latter field. Copy `participantRef` from that same selected row. Never derive those references from the worker name, provider, model, or execution label. A legacy v1 document keeps `schemaVersion: "1.0"` and omits `executionIdentityVersion`, `runManifestPath`, and both worker reference fields. The `audience` enum is a convergence role, not a phase label: every finding-producing worker uses `analysis` and selects an `analyser`, `designer`, `planner`, or `verifier` source role. Only the report author uses `report-writer`, paired with a `report-writer` source role. There is no `implementation-verifier` audience here; map an implementation verifier to `analysis`.
 6. Do not write a queue or classification in this grouped-input artifact. `okstra convergence seed` classifies Round 0 by mode:
    - Collaborative mode: multi-source groups become `full-consensus` immediately; only single-source groups enter the working queue.
    - Adversarial mode: every finding enters the working queue regardless of source count. Semantic grouping merges provenance only; it does not decide a finding is reliable.
@@ -106,8 +106,8 @@ convergence-<task-type>-<seq>.json
 
 Follow this protocol exactly:
 
-0. Two schemas describe what the reducer reads: `schemas/convergence-groups-v1.0.schema.json` feeds step 1's `seed --groups`, and `schemas/convergence-round-results-v1.0.schema.json` feeds step 4's `apply-round --results`. `schemas/convergence-critic-results-v1.0.schema.json` is a third shape but **not** a reducer input — it describes the critic worker's own result document. Step 6's `apply-critic-gaps --results` takes the coverage batch you assemble from those candidates plus each analyser's vote (`{schemaVersion, taskKey, mode, provider, modelExecutionValue, dispatches[], gaps[]}`, spelled out in §"Coverage critic pass" §"State"); feeding the critic document straight in is rejected, by design. `okstra convergence example --kind <groups|round-results|critic-results>` prints a deterministic valid instance of each and writes only JSON to stdout.
-1. Run `okstra convergence seed --groups <groups> --work-state <work> --final-state <final> --migration-dir <state/migrations>`. A `reuse-final` action means validate the existing final and continue to Phase 6. `create-work`, `resume-work`, and `restart-round0` continue with planning.
+0. Version-selected schemas describe what the reducer reads: `schemas/convergence-groups-v1.0.schema.json` accepts only legacy groups, `schemas/convergence-groups-v2.0.schema.json` accepts only explicit v2 execution identity, and `schemas/convergence-round-results-v1.0.schema.json` feeds step 4's `apply-round --results`. `schemas/convergence-critic-results-v1.0.schema.json` is a fourth shape but **not** a reducer input — it describes the critic worker's own result document. Step 6's `apply-critic-gaps --results` takes the coverage batch you assemble from those candidates plus each analyser's vote (`{schemaVersion, taskKey, mode, provider, modelExecutionValue, dispatches[], gaps[]}`, spelled out in §"Coverage critic pass" §"State"); feeding the critic document straight in is rejected, by design. `okstra convergence example --kind <groups|round-results|critic-results>` prints a deterministic valid v1 instance of each and writes only JSON to stdout.
+1. Run `okstra convergence seed --groups <groups> --run-manifest <current-run-manifest> --work-state <work> --final-state <final> --migration-dir <state/migrations>` for a v2 worker roster. `--run-manifest` must be the exact current manifest named by the groups document's `runManifestPath`; a previous run from the same task is not interchangeable. Omit the flag for a legacy v1 roster. A `reuse-final` action means validate the existing final and continue to Phase 6. `create-work`, `resume-work`, and `restart-round0` continue with planning.
 2. Run `okstra convergence plan-round --work-state <work> --plan <round-plan>`. This is read-only with respect to the working state.
 3. When the plan action is `dispatch`, create exactly one reverify prompt for each `dispatches[]` row and dispatch it through the selected runtime adapter. Its findings are exactly that row's `findingIds`.
 4. Convert parsed verdicts and every terminal dispatch outcome into `convergence-round-<N>-results-<task-type>-<seq>.json`; then run `okstra convergence apply-round --work-state <work> --plan <round-plan> --results <round-results>`.
@@ -228,21 +228,30 @@ Design intent: one `counter-evidence` refute denies a claim consensus (it cannot
 
 For every finding reverify row and critic-gap verification row, first write a
 call-specific task-instructions file under the current run's `state/`
-directory. Then run `okstra agent-prompt materialize` with `--audience
-reverification-worker`, `--assignment-ref reverify/<workerId>`, the exact
-`--worker-id`, `--dispatch-kind reverify-r<N>`, and the authorized
-prompt/result/audit paths. The returned `promptPath` is the only body that may
-be dispatched; do not append role prose or reconstruct model headers after
-materialization.
-
-If the dispatch gate then rejects that prompt, fix the task-instructions file
-and re-run the same `materialize` call with `--replace-undispatched` — keep the
-`--invocation-id`. A published prompt is otherwise immutable, so without that
-flag the retry fails as `existing_invocation_conflict`; do NOT delete the
-reservation under `prompts/.agent-invocations` and do NOT mint a second
-invocation id to get around it, because both detach the audit chain from the
-call it describes. The flag is checked: once any dispatch row names this
-invocation, the prompt is history and the replacement is refused.
+directory. For a v2 run, take `participantRef` and
+`sourceRoleExecutionRef` from the canonical round-plan dispatch row or the
+matching canonical working-state worker row. That stored reference is the
+selected source `RoleExecution` row's `roleExecutionRef`, not that row's
+`sourceRoleExecutionRef` field. Then run `okstra agent-prompt
+materialize` with `--audience
+reverification-worker`, `--assignment-ref reverify/<workerId>`,
+`--source-role-execution-ref
+<sourceRoleExecutionRef>`, the exact `--worker-id`, `--dispatch-kind
+reverify-r<N>`, and the authorized prompt/result/audit paths. Do not derive the
+source role execution from `workerId`, provider, model, or execution-label
+text. A legacy v1 run omits `--source-role-execution-ref`; the materializer
+keeps its legacy read-only identity resolution for that schema version. The
+returned `promptPath` is the only body that may be dispatched; do not append
+role prose or reconstruct model headers after materialization.
+
+If the dispatch gate then rejects that prompt, preserve its prompt, metadata,
+reservation, and append-only Invocation bytes. A v2 reverify correction uses a
+fresh `--invocation-id` and fresh prompt/metadata path; the materializer rejects
+`--replace-undispatched` for this dynamic identity path. A legacy v1 correction
+may fix the task-instructions file and re-run the same `materialize` call with
+`--replace-undispatched` while keeping the `--invocation-id`. Once any dispatch
+row names the invocation, replacement is rejected even for v1 and the prompt is
+history. Do not delete prompt, metadata, or reservation files by hand.
 
 Run `okstra agent-prompt verify --run-manifest <path> --metadata
 <metadataPath> --json` immediately before dispatch. A failed verification is a

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -44,9 +44,10 @@ Read-side inspection (`/okstra-inspect`) and scheduling (`/okstra-schedule-gen`)
 
 ## Core operating contract
 
-- The `lead` owns orchestration, convergence supervision, and final-report review/approval. It does not author the final-report file when `Report writer worker` is in the roster.
-- Standard worker roles remain `Claude worker`, `Codex worker`, `Antigravity worker`, and `Report writer worker`; these are provider/functional-role identities, not lead-runtime primitives.
-- `Report writer worker`, when in the roster, is the **author** of the final-report file. Lead reviews the draft and may request a revision via a follow-up dispatch, but MUST NOT write the report itself as a "shortcut". The only legal lead-authored fallback is when a Report writer worker dispatch was actually attempted and recorded a terminal status of `error`/`timeout`/`not-run` with an explicit reason in team-state — see [report-writer](./report-writer.md) "Lead-authored fallback".
+- The `leader` owns orchestration, convergence supervision, and final-report review/approval. It does not author the final-report file when `Report writer worker` is in the roster. `lead` is a compatibility alias for `leader` and must not be written on new artifacts.
+- Dispatch consumes stored role executions, not provider-named worker IDs. Canonical roles are `leader`, `analyser`, `critic`, `designer`, `planner`, `implementer`, `verifier`, `report-writer`, and `translator`. `executor` is a compatibility alias for `implementer`.
+- Pane titles and operational rows use the stored `executionLabel`. Do not rebuild that label from a provider name or model string.
+- `report-writer`, when in the roster, is the **author** of the final-report file. Lead reviews the draft and may request a revision via a follow-up dispatch, but MUST NOT write the report itself as a "shortcut". The only legal lead-authored fallback is when a Report writer worker dispatch was actually attempted and recorded a terminal status of `error`/`timeout`/`not-run` with an explicit reason in team-state — see [report-writer](./report-writer.md) "Lead-authored fallback".
 - "Session resume", "team is no longer alive", and similar are NOT valid reasons to skip Report writer worker dispatch — see [report-writer](./report-writer.md) "Resume-safe dispatch".
 - A shell command the lead runs must not be able to ask a question. The lead's shell is the user's own, where `cp`, `mv`, and `rm` are commonly aliased to their `-i` form; the confirmation that alias raises has nobody to answer it, so the call hangs until it is killed — observed as a `cp` over an existing state file stalling a whole self-fix round. Invoke these as `command cp` / `command mv` / `command rm`, which skips alias expansion and leaves the tool's own behaviour untouched. `-f` is not a substitute: it changes what the tool does on failure (`rm -f` reports success on a path that never existed).
 - If the brief is incomplete, continue with explicit uncertainty markers rather than fabricating confidence.
@@ -71,14 +72,14 @@ Phase-transition checklist (lead, end of run):
 
 1. Confirm the current phase's required outputs are complete and recorded in the final report.
 2. Set `workflow.phaseStates.<currentPhase>.state = "completed"` in `task-manifest.json` (validator does this when the run passes; verify the value).
-3. Update `workflow.lastCompletedPhase` and `workflow.nextRecommendedPhase`.
+3. Record **Phase Routing** in the final report — it is the source the Next-Phase Pointer is projected from, and Phase 7 validation recomputes the pointer from it. Update `workflow.lastCompletedPhase`. The Next-Phase Pointer (`workflow.nextRecommendedPhase`) itself is written per the Artifact Persistence Checklist in [report-writer](./report-writer.md), which owns its shape and its rules.
 4. **Do NOT start the next phase inside the current run.** A new okstra invocation with the new `--task-type` is the only legal way to advance.
 
 User-utterance interpretation rule:
 
 - "proceed to the next step" / "move on to the next step" / equivalent phrases are scoped to **the current phase only**. Interpret them as "produce the remaining outputs of the current phase," never as "start the next lifecycle phase."
 - If the current phase's outputs are already complete and the user clearly wants to advance, reply with the phase-transition checklist above and the exact next-run command. Wait for explicit user confirmation before any action that belongs to the next phase.
-- If `nextRecommendedPhase` is `implementation-planning`, the next run produces a **plan**, not code. The next run after that is `implementation`.
+- If the Next-Phase Pointer target (`nextRecommendedPhase.phase`) is `implementation-planning`, the next run produces a **plan**, not code. The next run after that is `implementation`.
 
 ## Progress reporting (BLOCKING)
 

package/runtime/prompts/lead/plan-body-verification.md

@@ -202,7 +202,14 @@ Before each verifier call, write one task-instructions file under the current
 run's `state/` directory and run `okstra agent-prompt materialize` with
 `--audience reverification-worker`,
 `--assignment-ref reverify/<workerId>`, the exact `--worker-id`, and
-`--dispatch-kind reverify-r<N>`. Run `okstra agent-prompt verify` against the
+`--dispatch-kind reverify-r<N>`. For a v2 run, select the verifier's canonical
+source `RoleExecution` row from the run manifest's static role state. Use its
+`participantRef`, and set `sourceRoleExecutionRef` to the selected source
+`RoleExecution` row's `roleExecutionRef`, not that row's
+`sourceRoleExecutionRef` field. Pass `--source-role-execution-ref
+<sourceRoleExecutionRef>`. Do not derive that reference from `workerId`,
+provider, model, or execution-label text. A legacy v1 run omits this flag. Run
+`okstra agent-prompt verify` against the
 returned `metadataPath` before dispatch and use the returned `promptPath`
 without modification. Native-session calls use only `hostModelValue`; before
 the host primitive, run `okstra agent-prompt record-dispatch` with the project
@@ -268,9 +275,9 @@ round before any host or provider process starts.
    - **Round completion.** A round is complete only after the renderer has run on the corrected data.json, lead has appended the round to the state file per step 6, lead has reconciled instructed groups against applied corrections — every `itemIds` entry either carries a `selfFixNote` or is still recorded as broken — **`okstra plan-verify --report <report>` exits 0** (step 5), and lead has then set that round's immutable `completedAt`. A round left with a non-zero exit carries its defect into the next round's inputs, which is how a mis-scored gate survives a whole self-fix budget. A round that was instructed but never rendered has not happened, and counting it inflates the budget that gates promotion. The state-file append is not optional bookkeeping: the next re-verification overwrites data.json's `planItems[].verdicts`, so a round that never reached `roundHistory[]` leaves no record anywhere of what it blocked on — which is the whole reason this file exists. **Enforced:** `validators/validate-run.py` `_validate_plan_body_state_rounds` requires one `roundHistory[]` entry per round `1..roundCount`, each carrying its own `gateResult` and cited by at least one item's `rounds[]`, and requires the file's `selfFixRoundsApplied` to match the report's. For a resolved correctness-critical user response, `_validate_target_round_causality` additionally requires the cited round's `completedAt` to be after every linked canonical `user-decision-required` event and no later than every linked canonical `user-decision-evaluated` event.
    - **Loop termination.** Lead — not the report-writer worker — records the round count in `planBodyVerification.selfFixRoundsApplied` at each round's end, and why the loop stopped in `planBodyVerification.selfFixStopReason`. The count must equal the highest `round` in `selfFixGroups[]`, so it is derivable from recorded work rather than self-reported. A user-directed correction does not consume the automatic self-fix limit, and a verification failure after that correction does not restart the automatic loop:
      - `all-resolved` — no planner-fixable `majority-disagree` item remains. Exit.
-     - `no-progress` — the round resolved **zero** planner-fixable items relative to the previous round. Exit even with budget left: the same rewrite would repeat. Newly *introduced* defects count against progress, so a rewrite that trades one defect for another stops the loop rather than churning.
+     - `no-progress` — the round resolved **zero** planner-fixable items relative to the previous round. Exit even with budget left: the same rewrite would repeat. Newly *introduced* defects count against progress, so a rewrite that trades one defect for another stops the loop rather than churning. A round that re-targets only what the previous round left unresolved is this same conclusion reached one dispatch earlier — exit on it under this reason rather than paying for the round that proves it. **Enforced (advisory):** `validators/validate-run.py` `_detect_self_fix_recurrence` warns on that shape and names this stop reason.
      - `max-rounds-reached` — `selfFixRoundsApplied == selfFixMaxRounds`. Exit.
-     - `cause-group-recurrence` — legacy read-only value for reports produced before activity contract v1. A new activity-contract-v1 run MUST NOT emit it because there is no second automatic self-fix round in which a cause group can recur. **Enforced:** `validators/validate-run.py` `_validate_activity_contract_plan_limits`.
+     - `cause-group-recurrence` — legacy read-only value for reports produced before activity contract v1. A new activity-contract-v1 run MUST NOT emit it because there is no second automatic self-fix round in which a cause group can recur. **Enforced:** `validators/validate-run.py` `_validate_activity_contract_plan_limits`. A legacy report that already carries it is still an *exhausted* loop, so step 8 may promote its surviving items: `_SELF_FIX_EXHAUSTED_REASONS` admits this value alongside `no-progress` / `max-rounds-reached`. Refusing it there left such a report with no exit at all — the loop may not run again, and the item may not be promoted either.
      - `not-attempted` — the loop never ran because no item qualified.
      The `no-progress` and `max-rounds-reached` exits are what make the loop terminate; `selfFixMaxRounds` alone is the backstop.
    - a `majority-disagree` item with a majority of its deciding `DISAGREE` votes at `needs-user-input` is NOT a self-fix target — after correctness-critical precedence, it goes straight to the next step as `user-decision` rather than generic `noncritical-dissent`. **Enforced:** `validators/validate-run.py` `_expected_approval_classification`.

package/runtime/prompts/lead/report-writer.md

@@ -357,6 +357,8 @@ Every field MUST anchor its claim with at least one evidence reference — a `pa
 2. **Evidence and Detailed Analysis** — primary evidence rows (file path, line, snippet); secondary evidence / alternate interpretations. If `reference-expectations.md` lists explicit expected values, record match/gap per row.
    - **Error-analysis diagnosis and routing.** When `header.taskType` is `error-analysis`, populate the required `errorAnalysis` object. Copy `errorAnalysis.symptomVerbatim` byte-for-byte from the symptom stated in the brief's `Source Material`; do not paraphrase it. Every `causeCandidates[]` row includes the full `supportingEvidence`, `falsifyingEvidenceChecked`, `confidence`, and `disproveWith` fields. When a candidate is a step in a propagation chain rather than a competing explanation — the analysis calls it a downstream step, a second stage, or a consequence of another candidate — set its `downstreamOf` to the ids of the candidates immediately upstream of it; leave the field absent for a candidate that stands on its own. Every id listed MUST be another candidate in the same report, no row may name itself, and the links MUST NOT form a cycle; `validators/validate-run.py::_validate_cause_chain` rejects all three. This is the only place the chain is machine-readable — prose calling a candidate "the second step of the chain" while `downstreamOf` is absent leaves the report's figure claiming the candidates are alternatives. Route `errorAnalysis.routing.nextTaskType=implementation-option-selection` with `direction=begin-option-selection`, or route `errorAnalysis.routing.nextTaskType=error-analysis` with `direction=continue-investigation`; no other pairing is valid. `verdictCard.nextStep`, `finalVerdict.nextStep`, the first `recommendedNextSteps` action and command, and the unique `followUpTasks` row whose `origin` is `phase-continuation` MUST all point to the same `errorAnalysis.routing.nextTaskType` target. The schema enforces only the presence of a `phase-continuation` row; `validators/validate-run.py::_validate_error_analysis_consistency` enforces exact target agreement and uniqueness.
    - **Implementation-option-selection comparison.** When `header.taskType` is `implementation-option-selection`, populate `implementationOptionSelection` from the converged direction-selection findings. Preserve every merged or rejected raw candidate in `candidateAudit`, and put at most three selectable candidates in `rankedOptions`. Each displayed candidate carries its requirement coverage, scope commitments, criterion scores, feasibility votes, safety blockers, unresolved feasibility facts, planning invariants, and exact coverage summary. In each displayed candidate, `expectedChangeAreas` names direction-level change surfaces, never exact file paths or an exact file list. `expectedVerification` names direction-level verification signals, never a stage list or executable test commands. `schemas/final-report-v2.0.schema.json` enforces the displayed-summary constants and the three-option cap; semantic recalculation belongs to `validators/validate-run.py`.
+     - **Routing.** `implementationOptionSelection.routing` is a required **string enum** — not an object — with exactly three values: `implementation-planning`, `pending-direction-selection`, `blocked`. It is the only field in this report that records where the task goes next, and Phase 7 projects `workflow.nextRecommendedPhase` from it (`scripts/okstra_ctl/next_phase.py`): `implementation-planning` becomes a `ready` pointer naming that phase, while `pending-direction-selection` and `blocked` become `pending` and `blocked` pointers carrying no phase. Only the first proposes a next run.
+     - **The value is determined by this run's mode and candidate set, not chosen freely.** `preselected-validation` mode routes to `implementation-planning` — the direction was already selected and this run only validated it. `candidate-comparison` mode that displays any candidate routes to `pending-direction-selection` — the user still owes the direction pick, so a comparison never routes straight to planning. `blocked` is legal only when no valid candidate exists at all, and is required in that case. **Enforced:** `scripts/okstra_ctl/implementation_options.py::validate_implementation_option_selection` rejects all three mismatches (`validated preselected direction must route to implementation-planning`, `candidate-comparison with options must await direction selection`, `routing must be blocked only when no valid options exist` / `routing may be blocked only when no valid options exist`).
    - **Implementation-planning direction branch.** When `implementationPlanning.planningContract == "selected-direction"`, read `selectedDirectionRef` and the snapshot before authoring. Materialize the snapshot into `directionRealization`, stages, validation, rollback, and bidirectional original-requirement links. Author exactly one `P-Dir-1`; its payload is the complete `directionRealization`. Its verification covers the core mechanism, architecture boundaries, planning invariants, and any hidden direction change against `selectedDirectionRef`. Do not author Option Candidates, candidate scores, a Recommended Option, or user candidate-selection fields. When current evidence requires changing the direction, author `outcome: "direction-invalidated"` and omit the execution plan. Legacy candidate-comparison reruns retain `P-Opt-*`, Option Candidates, trade-off, and Recommended Option semantics.
 
 ```json
@@ -370,6 +372,12 @@ Every field MUST anchor its claim with at least one evidence reference — a `pa
 ```
 
    - **Implementation-option-selection is non-terminal.** Its `followUpTasks` includes a `phase-continuation` row with `autoSpawn: "no"` and `priority: "P0"`; the schema's non-terminal conditional enforces row presence.
+   - **Implementation and final-verification routing.** Both phases record where the task goes next in a `routingRecommendation` **object** with exactly two fields: `target` is one enum value, `rationale` is the sentence that justifies it. Neither field takes free-form routing prose, and a target named only in the prose does not count — Phase 7 projects `workflow.nextRecommendedPhase` from `target` alone (`scripts/okstra_ctl/next_phase.py`), so the value you write there is the route the task actually takes.
+     - `implementation.routingRecommendation.target` is one of `final-verification`, `error-analysis`, `implementation-planning`, `implementation`. Pick `final-verification` when this stage's plan items landed and validation passed; `error-analysis` when a failure's cause is not understood; `implementation-planning` when the approved plan itself no longer fits the evidence; `implementation` when work remains inside this stage (the next run is a fix run).
+     - `finalVerification.routingRecommendation.target` is one of `release-handoff`, `release-handoff(stage-group)`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `implementation`, `done`. Both `release-handoff` values require the `accepted` verdict, and plain `release-handoff` additionally requires `verificationScope` `whole-task` — a `single-stage` accepted run routes to `release-handoff(stage-group)` instead. `done` ends the lifecycle here. `error-analysis` / `implementation-option-selection` / `implementation-planning` follow the cause-vs-direction-vs-plan split of the verdict token table above.
+     - `rationale` is one or two sentences on why that target and nothing else, citing the blocker ids or evidence rows behind the choice. It is the only free-form half of the field; the digest sections still point here for the full reasoning.
+     - `releaseHandoff.routingRecommendation` is unchanged — it stays a single prose field, because `release-handoff` is terminal and nothing projects a next phase from it.
+     - **Enforced:** `schemas/final-report-v2.0.schema.json` rejects a `target` outside the enum, a missing `rationale`, and any string value in either field; `validators/validate-run.py::_validate_final_verification_consistency` rejects a final-verification report whose `routingRecommendation.target` is absent, and rejects the verdict↔routing and scope↔routing combinations named above.
 3. **Recommended Next Steps** — prioritized actions. After Phase 7's follow-up spawner runs, append a row per newly created task-key (see "Phase 6 → Phase 7 execution sequence" above). **Approval-gate consistency:** when §1 carries any `Blocks: approval` row with `Status` ∈ {open, answered}, the Verdict Card `Next Step` and the first recommended step MUST point to the clarification rerun (`resume-clarification` of the SAME task-type) — never to "flip frontmatter `approved: true` → jump straight to `implementation`". Run-prep enforces this gate (`run.py _validate_approved_plan` fail-closes on those rows and on a blocking data.json `gateResult`), so a direct-implementation next-step is an instruction the reader cannot actually follow. **Cross-project pointer rule:** for cross-project dependencies (another repo / a different top-level deployment module / a published package), `crossProjectDependencies` (§5.4 Cross-Project Dependencies) is authoritative — do NOT duplicate that substance (prerequisite work / verification signals / handoff) into `recommendedNextSteps`; put only a one-line pointer to that section (no double-recording).
 4. **Follow-up Tasks** — auto-spawn-eligible table. Each row drives `okstra-spawn-followups.py`; see template §4 for the row schema.
 5. **Missing Information and Risks** — uncertain / "I don't know" items. `implementation-planning` adds §5.5 (see heading contract below); `release-handoff` adds §5.6.
@@ -417,7 +425,13 @@ Persistence steps that must be performed in Phase 7:
 - [ ] 4. **Update task-manifest.json**: Reflect task-level status and workflow lifecycle metadata
    - Update `workCategory` if the run produced a confident classification
    - Update `workflow.currentPhase`, `workflow.currentPhaseState`, `workflow.lastCompletedPhase`, and `workflow.phaseStates`
-   - Update `workflow.nextRecommendedPhase`, `workflow.awaitingApproval`, and `workflow.routingStatus`
+   - Write `workflow.nextRecommendedPhase` as an object with exactly three string fields — `phase`, `status`, `rationale`. **This checklist item is the canonical statement of that field**; the lead contract, the context loader and every okstra skill point here instead of restating it, so a change to the rule belongs in this bullet.
+     - `status` is one of `ready` (the named phase can be started now), `pending` (this run did not settle where the task goes next), `blocked` (something outside this run must change before any phase can start), or `terminal` (the lifecycle ends here; there is no next phase).
+     - `phase` carries a lifecycle phase name only when `status` is `ready`; under the other three, write the empty string. This is an authoring rule for the value **you** write, not a constraint the struct enforces or a shape you can rely on when reading. `prepare` lowers a `ready` pointer to `pending` and keeps its `phase` (`scripts/okstra_ctl/render.py::_derive_next_recommended_phase`), so every in-flight task's manifest holds a non-`ready` pointer that still names a phase. Never infer launchability from a non-empty `phase` — read `status`, which is the one field that answers it.
+     - `rationale` is one sentence saying why. It is the only free-form field, and it is the only part of the pointer that survives a correction.
+     - **`phase` and `status` MUST agree with this report's own routing field.** Which field that is depends on the task-type: `requirementsDiscovery.routing.nextTaskType`, `errorAnalysis.routing.nextTaskType`, `implementationOptionSelection.routing`, `implementationPlanning.outcome`, `implementation.routingRecommendation.target`, or `finalVerification.routingRecommendation.target` (see "Implementation and final-verification routing" above for those two enums). Two task-type groups have no routing field that Phase 7 projects from: `release-handoff` (its `routingRecommendation` is prose that nothing reads) is always `terminal`, and the analysis sidetracks — `improvement-discovery`, `project-analysis`, `feature-analysis`, `change-impact-analysis` — are always `pending`, whatever a per-candidate recommendation inside the report says. One routing value is not a phase name: when `finalVerification.routingRecommendation.target` is `release-handoff(stage-group)`, write `phase` as `release-handoff`. The parenthesised part names the handoff's scope, not a different phase, and Phase 7 projects it that way — writing the parenthesised form here records a correction against a report that was right.
+     - **Enforced:** Phase 7 validation recomputes `phase` and `status` from that routing field (`scripts/okstra_ctl/next_phase.py::project`). On a passing run whose authored pair disagrees with the recomputed pair, `validators/validate-run.py` overwrites both with the recomputed values, replaces your `rationale` with a pointer sentence, and preserves what you wrote under `workflow.nextRecommendedPhaseCorrection.authored`. A run whose validation fails ends with the pointer `blocked`, keeping your `rationale`. So the routing field is what actually moves the task — a pointer authored against the report body changes nothing but the audit trail.
+   - Update `workflow.awaitingApproval`
    - Update `workflow.lastSafeCheckpoint` to the best resume point for the current task
 - [ ] 5. **Update task-index.md**: Refresh human-readable summary
 - [ ] 6. **Generate final status file**: `runs/<task-type>/status/final-<task-type>-<seq>.status` (if necessary)