okstra 0.173.0 → 0.175.1

package/runtime/bin/okstra-trace-cleanup.sh

@@ -1,45 +1,45 @@
 #!/usr/bin/env bash
 #
-# okstra-trace-cleanup.sh — close tmux panes created during okstra runs.
+# okstra-trace-cleanup.sh — close the harness-owned worker panes of an okstra run.
 #
-# Worker-compute panes are tmux-pane backend siblings. Their dispatcher tags
-# each pane it owns with a pane-level user option (`@okstra_worker_run=<RUN_DIR>`),
-# so panes are found server-wide by tag — no tmux env var or pane-id registry is
-# needed, and the run-scoped tag keeps concurrent okstra runs from closing each
-# other's panes.
+# The panes this closes are the teammate panes the HARNESS splits for dispatched
+# worker agents. okstra does not create them and cannot tag them, so they are
+# found by a title allowlist scoped to the lead's window. They accumulate until
+# the pane budget runs out, and `shutdown_request` only idles the agent without
+# freeing its pane — this script is the only thing that closes them, which is why
+# the lead calls it at every round boundary and before every user gate.
 #
-# Trace panes were `tail -F` siblings the provider wrappers split, tagged
-# `@okstra_trace_run` / `@okstra_status`. Those wrappers are now four-line
-# entrypoints and worker progress renders into the worker's own pane, so
-# NOTHING SPAWNS A TRACE PANE and neither tag has a writer left. The trace
-# paths below still run and simply match nothing; `--reclaim-completed`, which
-# keys on `@okstra_status`, is inert for the same reason. Kept rather than
-# deleted because the hooks that call this script are already seeded on user
-# machines — retiring the trace machinery is a deliberate follow-up.
+# Two tag-driven paths used to live here and both are gone:
 #
-# Two invocation shapes:
+#   - Worker-compute panes of the `tmux-pane` dispatch backend, tagged
+#     `@okstra_worker_run`. That backend was removed — a worker now gets a cmux
+#     surface or a cli-wrapper subprocess, and neither is a tmux pane okstra owns.
+#   - Trace panes, tagged `@okstra_trace_run` / `@okstra_status`, which the
+#     provider wrappers used to split as `tail -F` siblings. The wrappers became
+#     four-line entrypoints and worker progress renders into the worker's own
+#     pane, so nothing had spawned a trace pane for some time.
 #
-#   --run-dir <RUN_DIR>   Used by the LEAD between phases and at wrap-up. Closes
-#                         (a) trace panes tagged with this run's dir and
-#                         (b) worker-agent panes the harness gives to dispatched
-#                         subagents (`claude-worker` / `codex-worker` /
-#                         `antigravity-worker` / `report-writer-worker`), identified
-#                         by a title allowlist scoped to the LEAD's WINDOW. The
-#                         lead pane is read from `<RUN_DIR>/state/lead-pane.id`
-#                         (recorded once by the lead in its own foreground pane —
-#                         reliable even though Claude Code's Bash tool strips
-#                         `$TMUX`/`$TMUX_PANE`); it scopes the title scan and is
-#                         NEVER killed. Window scope keeps a second lead running
-#                         in another window of the same session out of range.
+# With both writers gone the tag scan matched nothing, so it was removed along
+# with the two modes that existed only to drive it (`--reap`, which the SessionEnd
+# hook called, and `--reclaim-completed`, which `okstra-subagent-reclaim.sh` drove
+# from SubagentStop / TaskCompleted). Those hooks are gone from the seeded
+# settings too.
 #
-#   --reap                Used by the `SessionEnd` hook, where no single run-dir
-#                         applies. Closes every trace pane whose tag points under
-#                         `$CLAUDE_PROJECT_DIR/.okstra/` (or every tagged trace
-#                         pane if that env var is unset). Harness-owned
-#                         worker-agent panes are left to the harness.
+# Invocation:
+#
+#   --run-dir <RUN_DIR>   Closes the run's worker-agent panes (`claude-worker` /
+#                         `codex-worker` / `antigravity-worker` /
+#                         `report-writer-worker` and the FleetView teammate
+#                         prefixes), scoped to the LEAD's WINDOW. The lead pane is
+#                         read from `<RUN_DIR>/state/lead-pane.id` (recorded once
+#                         by the lead in its own foreground pane — reliable even
+#                         though Claude Code's Bash tool strips `$TMUX` /
+#                         `$TMUX_PANE`); it scopes the scan and is NEVER killed.
+#                         Window scope keeps a second lead running in another
+#                         window of the same session out of range.
 #
 # `--list` (alias `--dry-run`) prints `<pane_id>\t<pane_title>` per pane instead
-# of killing — only meaningful with `--run-dir`.
+# of killing.
 #
 # `--keep <substr>` (repeatable) spares any pane whose current title contains
 # <substr>, in both the kill and the list set. Used to preserve an in-flight
@@ -50,7 +50,7 @@
 
 set -u
 
-# Trace-pane caller resolution helper (okstra_resolve_caller_pane) — see
+# Caller-pane resolution helper (okstra_resolve_caller_pane) — see
 # lib/okstra/tmux-pane.sh. Used as the lead-pane fallback below so a missing /
 # stale lead-pane.id resolves to the pane THIS process actually runs in (via
 # ancestor-PID ↔ tmux pane_pid matching), never a foreign active-client pane.
@@ -58,43 +58,26 @@ set -u
 _clean_script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
 [ -r "$_clean_script_dir/lib/okstra/tmux-pane.sh" ] && . "$_clean_script_dir/lib/okstra/tmux-pane.sh"
 
-# --reclaim-completed shells out to `python3 -m okstra_ctl.pane_reclaim`. The
-# package is a bin-sibling in the repo layout (scripts/okstra_ctl) and under
-# $OKSTRA_HOME/lib/python in the installed layout. Put both on PYTHONPATH so the
-# import resolves regardless of where this script runs from.
-_okstra_home="${OKSTRA_HOME:-$HOME/.okstra}"
-export PYTHONPATH="${_clean_script_dir}:${_okstra_home}/lib/python${PYTHONPATH:+:$PYTHONPATH}"
-
 MODE="kill"   # kill | list
-RECLAIM=0     # 1: trace pane 은 @okstra_status 가 완료(exited)일 때만 회수 (--reclaim-completed)
-REAP=0
 run_dir=""
 KEEP_PATTERNS=()   # --keep <substr>: panes whose title contains substr are spared from kill/list
 while [[ $# -gt 0 ]]; do
   case "$1" in
-    --list|--dry-run)    MODE="list" ;;
-    --reclaim-completed) RECLAIM=1 ;;
-    --reap)              REAP=1 ;;
+    --list|--dry-run) MODE="list" ;;
     --run-dir)        shift; run_dir="${1-}" ;;
     --run-dir=*)      run_dir="${1#--run-dir=}" ;;
     --keep)           shift; KEEP_PATTERNS+=("${1-}") ;;
     --keep=*)         KEEP_PATTERNS+=("${1#--keep=}") ;;
     -h|--help)
       cat <<'USAGE'
-usage: okstra-trace-cleanup.sh (--run-dir <RUN_DIR> [--list] [--reclaim-completed] [--keep <substr>]... | --reap)
+usage: okstra-trace-cleanup.sh --run-dir <RUN_DIR> [--list] [--keep <substr>]...
 
-  --run-dir            okstra run directory; closes that run's trace + worker-agent panes.
-  --list               with --run-dir: print "<pane_id>\t<pane_title>" per pane; no kill.
+  --run-dir            okstra run directory; closes that run's worker-agent panes.
+  --list               print "<pane_id>\t<pane_title>" per pane; no kill.
   --dry-run            alias for --list.
   --keep <substr>      exclude any pane whose title contains <substr> from the
                        kill/list set (repeatable). Used to spare an in-flight
                        report-writer at a round boundary.
-  --reclaim-completed  with --run-dir: restrict trace panes to those whose
-                       @okstra_status sidecar is terminal (stage=exited); in-flight
-                       and teammate panes are preserved. Skips the title-allowlist
-                       teammate scan. Combinable with --list.
-  --reap               close every okstra trace pane under $CLAUDE_PROJECT_DIR/.okstra
-                       (SessionEnd hook; no single run-dir applies).
 USAGE
       exit 0 ;;
     *)
@@ -104,29 +87,16 @@ USAGE
   shift
 done
 
-if [[ "$REAP" -eq 0 && -z "$run_dir" ]]; then
-  printf 'okstra-trace-cleanup.sh: --run-dir <RUN_DIR> (or --reap) is required\n' >&2
+if [[ -z "$run_dir" ]]; then
+  printf 'okstra-trace-cleanup.sh: --run-dir <RUN_DIR> is required\n' >&2
   exit 2
 fi
 
-# Canonicalize paths used in tag string-compares. The wrappers tag panes with
-# `pwd -P` (symlink-resolved), so the scope paths must be resolved the same way
-# — else a symlinked component (e.g. macOS /tmp -> /private/tmp) makes the
-# compare miss. Fall back to the literal value if the dir does not resolve.
-_resolve() { (cd "$1" 2>/dev/null && pwd -P) || printf '%s' "$1"; }
-[[ -n "$run_dir" ]] && run_dir="$(_resolve "$run_dir")"
-project_dir=""
-[[ -n "${CLAUDE_PROJECT_DIR:-}" ]] && project_dir="$(_resolve "$CLAUDE_PROJECT_DIR")"
-
-# Lead pane. For a run, prefer the value the lead recorded in its own foreground
-# pane; fall back to the active-pane probe. Rejected if the recorded pane is
-# gone. For --reap there is no run state — probe the active pane, used only to
-# avoid killing whatever pane the reap runs from.
+# Lead pane. Prefer the value the lead recorded in its own foreground pane; fall
+# back to the active-pane probe. Rejected if the recorded pane is gone.
 lead_pane=""
-if [[ "$REAP" -eq 0 ]]; then
-  lead_pane_file="$run_dir/state/lead-pane.id"
-  [[ -r "$lead_pane_file" ]] && lead_pane="$(head -n1 "$lead_pane_file" 2>/dev/null || true)"
-fi
+lead_pane_file="$run_dir/state/lead-pane.id"
+[[ -r "$lead_pane_file" ]] && lead_pane="$(head -n1 "$lead_pane_file" 2>/dev/null || true)"
 if [[ -z "$lead_pane" ]] || ! tmux display-message -p -t "$lead_pane" '#{pane_id}' >/dev/null 2>&1; then
   if type okstra_resolve_caller_pane >/dev/null 2>&1; then
     lead_pane="$(okstra_resolve_caller_pane 2>/dev/null || true)"
@@ -135,17 +105,6 @@ if [[ -z "$lead_pane" ]] || ! tmux display-message -p -t "$lead_pane" '#{pane_id
   fi
 fi
 
-# Does a trace pane's tag belong to the set we are closing?
-_tag_in_scope() {
-  local tag="$1"
-  if [[ "$REAP" -eq 1 ]]; then
-    [[ -z "$tag" ]] && return 1
-    [[ -n "$project_dir" ]] && { [[ "$tag" == "$project_dir/"* ]]; return; }
-    return 0   # no project scope available → reap every tagged trace pane
-  fi
-  [[ "$tag" == "$run_dir" ]]
-}
-
 _title_in_okstra_scope() {
   local title="$1"
   case "$title" in
@@ -168,7 +127,6 @@ _title_in_okstra_scope() {
 }
 
 # A collected pane whose current title contains any --keep substring is spared.
-# Applied at the final emit so both the tag scan and the title scan honour it.
 _keep_excluded() {
   local pid="$1" title pat
   (( ${#KEEP_PATTERNS[@]} )) || return 1
@@ -181,54 +139,25 @@ _keep_excluded() {
 
 collect_okstra_panes() {
   local -a panes=()
-  local pid trace_tag worker_tag status_tag title
-
-  # (1) Trace and worker-compute panes tagged in scope — found server-wide by
-  # tag, so no tmux env var or pane-id registry is needed. Each `@okstra_*`
-  # column carries a leading `x` sentinel (stripped after read): tmux's `-F`
-  # drops an UNSET user option AND its adjacent tab, which would otherwise
-  # shift later columns left (e.g. an empty worker tag stealing the status
-  # value). The sentinel keeps every column present so positional parsing holds.
-  # `#x` strip 은 실제 태그 값을 깎지 않는다: 모든 태그 값(trace_run/worker_run/
-  # status)은 절대경로라 `/` 로 시작 → `x` 로 시작하는 일이 없어 sentinel 만 벗겨진다.
-  while IFS=$'\t' read -r pid trace_tag worker_tag status_tag; do
-    trace_tag="${trace_tag#x}"; worker_tag="${worker_tag#x}"; status_tag="${status_tag#x}"
+  local pid title
+
+  # Title-allowlisted worker-agent panes in the lead's WINDOW. `list-panes -t
+  # <pane>` (no `-s`, no `-a`) resolves the window containing that pane and lists
+  # only that window's panes. Split-pane teammates always land in the lead's
+  # window, so this catches all of THIS run's worker panes while a second okstra
+  # lead in another window of the same tmux session is left untouched. Skipped
+  # when the lead pane is unknown.
+  [[ -n "$lead_pane" ]] || return 0
+  while IFS=$'\t' read -r pid title; do
     [[ -n "$pid" ]] || continue
     [[ "$pid" == "$lead_pane" ]] && continue
-    if _tag_in_scope "$trace_tag" || _tag_in_scope "$worker_tag"; then
-      if [[ "$RECLAIM" -eq 1 ]]; then
-        # reclaim 모드: 완료(stage=exited)된 worker 의 pane 만. status 태그가
-        # 없거나(teammate/비-wrapper pane) 미완료면 보존.
-        [[ -n "$status_tag" ]] || continue
-        python3 -m okstra_ctl.pane_reclaim "$status_tag" || continue
-      fi
+    if _title_in_okstra_scope "$title"; then
       panes+=("$pid")
     fi
-  done < <(tmux list-panes -a \
-             -F '#{pane_id}'$'\t''x#{@okstra_trace_run}'$'\t''x#{@okstra_worker_run}'$'\t''x#{@okstra_status}' \
-             2>/dev/null || true)
-  # (2) Title-allowlisted worker-agent panes in the lead's WINDOW. Only for a
-  # run (reap leaves these harness-owned panes to the harness). `list-panes -t
-  # <pane>` (no `-s`, no `-a`) resolves the window containing that pane and
-  # lists only that window's panes. Split-pane teammates always land in the
-  # lead's window, so this catches all of THIS run's worker panes while a second
-  # okstra lead in another window of the same tmux session — whose in-flight
-  # worker panes are untagged and title-only — is left untouched. Skipped when
-  # the lead pane is unknown. reclaim 모드는 teammate pane 을 회수하지 않으므로
-  # (완료 판정 불가, trace-only) 이 스캔을 건너뛴다.
-  if [[ "$REAP" -eq 0 && "$RECLAIM" -eq 0 && -n "$lead_pane" ]]; then
-    while IFS=$'\t' read -r pid title; do
-      [[ -n "$pid" ]] || continue
-      [[ "$pid" == "$lead_pane" ]] && continue
-      if _title_in_okstra_scope "$title"; then
-        panes+=("$pid")
-      fi
-    done < <(tmux list-panes -t "$lead_pane" \
-               -F '#{pane_id}'$'\t''#{pane_title}' 2>/dev/null || true)
-  fi
+  done < <(tmux list-panes -t "$lead_pane" \
+             -F '#{pane_id}'$'\t''#{pane_title}' 2>/dev/null || true)
 
-  # Dedupe — a live trace pane can match both the tag scan and the title scan.
-  # Then drop any pane a --keep pattern spares (in-flight report-writer).
+  # Drop any pane a --keep pattern spares (in-flight report-writer).
   if (( ${#panes[@]} )); then
     printf '%s\n' "${panes[@]}" | awk 'NF && !seen[$0]++' | while IFS= read -r _pid; do
       _keep_excluded "$_pid" && continue

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/lead/adapters/cmux.md

@@ -34,6 +34,8 @@ It overrides only the worker-dispatch portion of the selected host relay, not th
 | `record_lead_event` | Append progress and activity records to the manifest-provided `leadEventsPath`. Emit the matching `PROGRESS:` line and, when an activity record is required, the immediately following `ACTIVITY:` line from the same structured fields. |
 | `collect_usage` | Collect artifact/CLI-log-backed usage through the existing Okstra token-usage path; never substitute another runtime's session log. |
 
+An `implementation` run calls `dispatch_worker` twice: once for the Executor, then — after `await_workers` settles it — once for the verifiers. That second call's `--workers` list must omit the Executor's worker ID: it is materialized as the Executor on every dispatch, so a batch still carrying it is refused again. A verifier started beside the Executor observes base HEAD instead of the stage diff, so a single batch holding both is refused by `scripts/okstra_ctl/dispatch_core.py` `_validate_implementation_phase_order`, `--dry-run` included.
+
 ## Pane placement is not yours to compute
 
 Okstra creates, sizes, labels, and closes every worker pane. Do not issue terminal-multiplexer commands of any kind — not to place a worker, not to resize the lead, not to reclaim a finished round. Pane geometry depends on the display, and a lead that recomputes it per run gets it wrong differently on every host.

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,7 +44,9 @@ 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.
+- 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.
 - 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".
 - "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".
@@ -181,7 +183,7 @@ For `--task-type implementation` runs, the task bundle additionally pins one of
 - `instruction-set/analysis-profile.md` — top "Executor binding" block (provider, display name, model, runner, and dispatch mode)
 - `runs/implementation/manifests/run-manifest-*.json` — `teamContract.executor` object (the same binding plus `appliesTo: "implementation"`)
 
-Lead MUST dispatch Edit/Write-bearing work only through that executor binding: use the host primitive with `hostModelValue` for `runner=native-session`, or `okstra worker-dispatch` with `modelExecutionValue` for `runner=cli-wrapper`. The other two providers still run as read-only verifiers in the same run; the executor's own provider is *also* dispatched separately as a verifier in a fresh session, so the diff is reviewed context-isolated. Session isolation is the primary self-review safeguard — same-model executor and same-provider verifier is acceptable in distinct sessions. A different model variant (e.g. executor=opus / Claude verifier=sonnet) is recommended but not mandatory.
+Lead MUST dispatch Edit/Write-bearing work only through that executor binding: use the host primitive with `hostModelValue` for `runner=native-session`, or `okstra worker-dispatch` with `modelExecutionValue` for `runner=cli-wrapper`. The other providers in the roster still run as read-only verifiers in the same run; the executor's own provider does not, because its worker ID materializes as the executor on every dispatch — so the diff is reviewed context-isolated by the remaining verifiers. Session isolation is the primary self-review safeguard — a verifier reusing the executor's model variant is acceptable in a distinct session. A different model variant (e.g. executor=opus / Claude verifier=sonnet) is recommended but not mandatory.
 
 Executor is chosen at run-prep time via `--executor <claude|codex|antigravity>` (or `OKSTRA_DEFAULT_EXECUTOR`, fallback `claude`); the model used by the executor is taken from the corresponding worker model flag (`--claude-model` / `--codex-model` / `--antigravity-model`). For CLI-backed executors, the underlying file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --sandbox workspace-write`), not through the lead runtime's `write_artifact` operation.
 

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

@@ -53,7 +53,7 @@ The shared Majority definition and the auto-disable rule (fewer than 2 analyser
 
 ## Plan-item extraction (Round 0 equivalent)
 
-From the report-writer's draft of `## 5.4 Implementation Plan Deliverables`, the lead creates the verification queue only through this sequence (see also `templates/reports/final-report.template.md` §5.5.9):
+From the report-writer's draft of `## 5.4 Implementation Plan Deliverables`, the lead creates the verification queue only through this sequence (see also `templates/reports/final-report-v2.template.md` §5.5.9):
 
 ```text
 okstra plan-items extract --data <data.json> --output <state>/plan-items-....json
@@ -124,7 +124,7 @@ The verdict tokens `AGREE` / `DISAGREE` / `SUPPLEMENT` are reused, but their mea
 `P-Prep-S<stage>-<kind>` applies the same verdict tokens and adds these disposition checks:
 
 - `inline-contract`: AGREE only when the contract contains the kind-specific fields needed to implement the stage; a label or generic prose is insufficient.
-- `prep-item`: AGREE only when every referenced PREP item has a concrete `aiProposal`, correct `stageRefs`/`kind`, and state-specific safeguards required by `schemas/final-report-v1.0.schema.json`.
+- `prep-item`: AGREE only when every referenced PREP item has a concrete `aiProposal`, correct `stageRefs`/`kind`, and state-specific safeguards required by `schemas/final-report-v2.0.schema.json`.
 - `not-applicable`: AGREE only when the rationale is consistent with the stage action; otherwise DISAGREE with `fixability` (`planner-fixable` when the plan can supply the missing contract, `needs-user-input` only for genuinely external facts).
 - A declared `blocked` item is not itself a plan-body failure. Missing or duplicate coverage, an empty proposal, a mismatched reference, or an unjustified disposition is a failure and receives `DISAGREE(<kind>)` with `fixability`.
 
@@ -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
@@ -254,7 +261,7 @@ round before any host or provider process starts.
 
    **How the corrective round is recorded.** The first prompt was dispatched, so it is immutable — `--replace-undispatched` refuses it, correctly. Materialize the correction under a NEW `--invocation-id` and a new prompt path. Before linking its result, retire the first attempt's link: `okstra agent-prompt reject-result --run-manifest <path> --dispatch-id <first dispatch id> --superseded-by <corrective dispatch id> --reason "<what was wrong with the returned result>"`. Without that step the corrective `link-result` fails with `agent result is already linked to another dispatch`, which is how a worker that ran for twenty minutes and wrote a good result ends up unrecordable. Nothing is deleted: the rejected link stays in `agentResultLinks` carrying `supersededBy` and `rejectionReason`, so the ledger shows both attempts and why the second exists.
 
-   Then lead writes `runs/<task-type>/state/plan-body-verification-<task-type>-<seq>.json` (schema below), **appending this round** — one new `roundHistory[]` entry plus this round's votes on each verified item's `planItems[].rounds[]`. The file accumulates across rounds; it is never truncated to the latest one. After `okstra plan-verify` exits 0, lead sets that new round's `completedAt` to the current ISO 8601 UTC time exactly once; a prior round's `completedAt` is immutable. Lead then populates `### 5.5.9 Plan Body Verification` in the final report's data.json (`implementationPlanning.planBodyVerification`, schema `schemas/final-report-v1.0.schema.json`; template at `templates/reports/final-report.template.md`). The §5.5.9 body is **grouped by plan item**: `planItems[]`, each carrying its `id`, its plain-language `subject` (rendered as the item heading), an optional `sourceSection`, an optional `clarificationId` (the `C-<N>` this item blocks on when `majority-disagree`), and a `verdicts[]` list (`worker / verdict / breakageKind / note`) — one verdict row per worker under that item. The renderer prints three fixed legends (gate values, verdict tokens, breakage kinds a–f) so the reader can decode every cell without opening this spec. The older flat `#### Verdict details` table (`Plan item / Worker / …`, one row per plan-item × worker pair) is superseded by the grouped layout — it hid *what* each vote was about behind a bare `P-*` ID; the subject heading is the fix. The validator's `Plan Body Verification` + `Gate result:` substring checks still gate this section.
+   Then lead writes `runs/<task-type>/state/plan-body-verification-<task-type>-<seq>.json` (schema below), **appending this round** — one new `roundHistory[]` entry plus this round's votes on each verified item's `planItems[].rounds[]`. The file accumulates across rounds; it is never truncated to the latest one. After `okstra plan-verify` exits 0, lead sets that new round's `completedAt` to the current ISO 8601 UTC time exactly once; a prior round's `completedAt` is immutable. Lead then populates `### 5.5.9 Plan Body Verification` in the final report's data.json (`implementationPlanning.planBodyVerification`, schema `schemas/final-report-v2.0.schema.json`; template at `templates/reports/final-report-v2.template.md`). The §5.5.9 body is **grouped by plan item**: `planItems[]`, each carrying its `id`, its plain-language `subject` (rendered as the item heading), an optional `sourceSection`, an optional `clarificationId` (the `C-<N>` this item blocks on when `majority-disagree`), and a `verdicts[]` list (`worker / verdict / breakageKind / note`) — one verdict row per worker under that item. The renderer prints three fixed legends (gate values, verdict tokens, breakage kinds a–f) so the reader can decode every cell without opening this spec. The older flat `#### Verdict details` table (`Plan item / Worker / …`, one row per plan-item × worker pair) is superseded by the grouped layout — it hid *what* each vote was about behind a bare `P-*` ID; the subject heading is the fix. The validator's `Plan Body Verification` + `Gate result:` substring checks still gate this section.
 7. **Self-fix loop (one rewrite, targeting planner-fixable defects).** After round 1, lead may run one report-writer rewrite when at least one `majority-disagree` item has a majority of its `DISAGREE` verdicts at `fixability == planner-fixable`. The targeted re-verification after that rewrite is round 2. After round 2, stop automatic self-fix regardless of outcome. Classify every remaining item as `user-decision`, `noncritical-dissent`, or `correctness-critical`. A second automatic self-fix is a contract violation. The fixed order is initial verification → one planner self-fix → targeted re-verification → user gate.
    - **Group the targets by cause before instructing (BLOCKING).** Blocked items are usually several derivatives of one defect — one constant declared twice, one responsibility given two owners — and the coverage rows that cite them fail as a consequence, not independently. Lead MUST partition this round's targets into cause groups and instruct each group as **"remove this cause"**, naming the derivatives it accounts for. **Handing report-writer a bare item list is forbidden**: patched one at a time, each correction leaves the sibling sections still asserting the old value, so the next round re-finds the same family and the budget drains without converging. Record the partition in `planBodyVerification.selfFixGroups[]` (`round`, `causeSummary`, `itemIds`). One group per item is a legitimate outcome only when the items genuinely share no cause — recorded that way, it is a visible diagnosis rather than a skipped one. **Enforced:** `validators/validate-run.py` `_validate_self_fix_grouping` requires the partition, ties `selfFixRoundsApplied` to the highest recorded round, and fails any corrected item that belongs to no group.
    - lead instructs report-writer to rewrite the items in each cause group (NOT a full draft regeneration; procedure in [report-writer](./report-writer.md) §"Self-fix rewrite").
@@ -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

@@ -261,17 +261,17 @@ For those v1 reports, the final report must contain section headings whose **lin
 | 7 | `Validation Checklist` | `### Validation Checklist (Korean gloss)` |
 | 8 | `Rollback` | `### Rollback Strategy (Korean gloss)` |
 | 9 | `Requirement Coverage` | `### Requirement Coverage (Korean gloss)` |
-| 10 | `Plan Body Verification` + `Gate result:` | `### Plan Body Verification (Korean gloss)` containing a `Gate result:` line — copy `templates/reports/final-report.template.md §5.5.9` verbatim. Validator checks both substrings. |
+| 10 | `Plan Body Verification` + `Gate result:` | `### Plan Body Verification (Korean gloss)` containing a `Gate result:` line — copy `templates/reports/final-report-v2.template.md §5.5.9` verbatim. Validator checks both substrings. |
 | 11 | `Cross-Project Dependencies` | `### Cross-Project Dependencies (Korean gloss)` — `_(none)_` when the plan is single-project. |
 | 12 | `Decision Drafts` | `### Decision Drafts (Korean gloss)` |
 
 **Never author a `User Approval Request` section.** The approval gate moved to the YAML frontmatter `approved: true|false` field, and `validators/validate-run.py` fails any report containing a `## User Approval Request` block or a `### 5.5.8 User Approval Request` stub. This paragraph replaces an earlier row that listed the heading as required — following it produced a report the validator rejected.
 
-`Implementation Design Preparation` is NOT in the substring list: `templates/reports/final-report.template.md` §5.5.10 renders that heading from `implementationPlanning.designPreparation`, so it is enforced by the schema + renderer rather than by a heading scan.
+`Implementation Design Preparation` is NOT in the substring list: `templates/reports/final-report-v2.template.md` §5.5.10 renders that heading from `implementationPlanning.designPreparation`, so it is enforced by the schema + renderer rather than by a heading scan.
 
 The English keyword is mandatory and the body of each section is written in English, like everything else you author — see "Writing Guidelines" below. For non-`implementation-planning` runs, omit this entire block — these headings are NOT validator-checked for other task-types.
 
-The final-report template `templates/reports/final-report.template.md` Section 5.5 already encodes this contract — copy that block verbatim and fill in.
+The final-report template `templates/reports/final-report-v2.template.md` Section 5.5 already encodes this contract — copy that block verbatim and fill in.
 
 ### Self-fix rewrite (plan-body self-fix round)
 
@@ -305,7 +305,7 @@ When the run's `task-type` is `final-verification`, the report's `## 7. Final Ve
 
 For every other task-type, set the `Verdict Token` cell to `not-applicable`. Do NOT omit the row — the template renders it for all task-types and downstream tooling expects the field to exist.
 
-The final-report template `templates/reports/final-report.template.md` Section 7 already encodes this contract — copy that block verbatim and fill in.
+The final-report template `templates/reports/final-report-v2.template.md` Section 7 already encodes this contract — copy that block verbatim and fill in.
 
 ### Release-handoff section contract (release-handoff runs only)
 
@@ -313,7 +313,7 @@ When the run's `task-type` is `release-handoff`, the final report MUST include S
 
 **Single-lead authorship (release-handoff only):** release-handoff has no worker roster. The lead authors the final-report file directly — there is no `Report writer worker` dispatch to perform in Phase 6, no resume-safe dispatch concern, and no mandatory worker-results file for a report-writer role. The rest of this contract's dispatch / resume / fallback machinery applies ONLY when `Report writer worker` is in the roster (i.e. every task-type other than `release-handoff`).
 
-The final-report template `templates/reports/final-report.template.md` Section 5.6 already encodes this contract — copy that block verbatim and fill in. For non-`release-handoff` runs, omit Section 5.6 entirely.
+The final-report template `templates/reports/final-report-v2.template.md` Section 5.6 already encodes this contract — copy that block verbatim and fill in. For non-`release-handoff` runs, omit Section 5.6 entirely.
 
 ### Mandatory worker-result pointer and audit sidecar (BLOCKING)
 
@@ -337,7 +337,7 @@ The selected report-writer preamble defines that audit shape. **Enforced:** `val
 
 ### Main Body Section
 
-Section numbering follows `templates/reports/final-report.template.md` exactly — that file is the documentation SSOT for section names and ordering. For full body structure at authoring time, consult your run's **phase-stripped** `final-report-template.md` (the per-task-type instruction-set copy defined in Phase 6 dispatch item 10); the "copy that block verbatim" references below mean the §-block as it appears in that stripped copy, not a re-read of the full source.
+Section numbering follows `templates/reports/final-report-v2.template.md` exactly — that file is the documentation SSOT for section names and ordering. For full body structure at authoring time, consult your run's **phase-stripped** `final-report-template.md` (the per-task-type instruction-set copy defined in Phase 6 dispatch item 10); the "copy that block verbatim" references below mean the §-block as it appears in that stripped copy, not a re-read of the full source.
 
 **Verdict Card (top-of-report, mandatory).** Render `## Verdict Card` between the report header and the (conditional) Approval block. Its `Verdict Token` and `Direction` cells MUST byte-match the corresponding cells in `## 7. Final Verdict`. Its `Next Step`, the final-verdict next step, and the first item of `## 3. Recommended Next Steps` MUST name the same route target, though the actionable command and prose need not be byte-identical. Divergence is `contract-violated`.
 

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

@@ -164,7 +164,7 @@ After each worker attempt returns (regardless of role), Lead MUST verify the can
 - The result file exists but its audit sidecar does not, at `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md`. Workers write both in the same step, so a result without a sidecar means the Reading Confirmation block — the only evidence the worker read its inputs — was never produced. `validate-run.py` fails the run on this at Phase 7 either way (`validate_worker_results_audit`); checking it here spends the existing one-retry budget while the role can still be re-dispatched, instead of surfacing hours later when the worker session is gone.
 - `okstra worker-audit-check --run-dir <runs/<task-type>/> --task-type <t> --seq <n> --worker <id>` exits 2 on a backticked `path:line` citation in the worker's result that has no matching Evidence read row in its audit sidecar. Run it the moment you collect each result. Phase 7 enforces the same rules from the same implementation (`okstra_ctl.worker_audit_ledger`), but by then the worker session is gone and the only remaining moves are editing the result yourself — which destroys the audit chain the ledger exists to provide — or ending the run `contract-violated`. While the session is alive, `SendMessage` to the worker so it corrects its own citation; that costs about a minute against a re-dispatch or a failed run.
 
-The same audit check parses command evidence from canonical rows such as `- Evidence command: {"command":"npm run check","cwd":"<project-root>","exitCode":0,"outputSummary":"all checks passed"}`. Workers record only commands that produced or verified a conclusion, not exploratory `rg`, `ls`, or file-opening commands. Environment variable values, tokens, credentials, and authorization headers are excluded. A malformed row or potential sensitive material is a contract failure returned by `okstra_ctl.worker_audit_ledger`; send the failure to the worker while its session is still available.
+The same audit check parses command evidence from canonical rows such as `- Evidence command: {"command":"npm run check","cwd":"<project-root>","exitCode":0,"outputSummary":"all checks passed"}`. Workers record only commands that produced or verified a conclusion, not exploratory `rg`, `ls`, or file-opening commands. A malformed row is a contract failure returned by `okstra_ctl.worker_audit_ledger`; send the failure to the worker while its session is still available. Nothing scans these rows for secrets, so a row is never refused for how a setting is named — `AUTH_MODE=off` and `TOKEN_TTL=60` record verbatim. Do not tell a worker to drop or paraphrase a row on those grounds: a worker that cannot record the command it ran has no way to satisfy the evidence ledger that demands it.
 
 **One-retry policy:**
 

package/runtime/prompts/profiles/_common-contract.md

@@ -12,7 +12,7 @@ profile document.
   - **Phase 5.5 (convergence — peer review by workers)**: workers peer-review each other's findings across up to `effectiveMaxRounds` rounds; the lead mediates but does not vote. See `prompts/lead/convergence.md` for the round protocol (replay of findings, `AGREE` / `DISAGREE` / `SUPPLEMENT` verdicts), queue invariants, and final classification (`full-consensus` / `partial-consensus` / `contested` / `worker-unique`). For `requirements-discovery`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `project-analysis`, `feature-analysis`, and `change-impact-analysis` this phase runs in **adversarial mode** (`convergence.adversarial=true`): verifiers try to refute each finding against its cited evidence and the burden of proof sits on the claim — see that skill's §"Adversarial Verification Mode".
   - Do NOT conclude "no peer review happens" from the roster alone — every profile that lists ≥2 analyser workers runs convergence by default (`convergence.enabled=true` in `task-manifest.json`).
   - For a new `implementation-planning` run, the plan-body sequence is initial verification → one planner self-fix → targeted re-verification → user gate. The initial verification is round 1, the targeted re-verification is round 2, and a second automatic self-fix is a contract violation. 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.
-  - **provider-unavailable fallback (tolerance).** A worker dispatch can fail to produce a result for two distinct reasons, and both take the same recovery path. (1) **Pane budget:** the dispatch is rejected with `no room for another tmux split` (or an equivalent teammate-pane creation failure). (2) **Sandbox CLI-start failure (non-tmux path):** an external CLI worker wrapper exits non-zero within seconds with empty stdout and its live-log shows `operation not permitted`. In either case the lead spends the one shared retry budget through the assignment's recorded runner. If the provider is still unavailable, record that terminal status and continue only under the convergence quorum rules; never replace it silently with a fixed provider or count a substitute as the original provider's vote. Completed external-CLI worker panes are reclaimed by the selected runtime adapter's resource lifecycle. (This is a prompt instruction, not a code-enforced gate.)
+  - **provider-unavailable fallback (tolerance).** A worker dispatch can fail to produce a result for two distinct reasons, and both take the same recovery path. (1) **Pane budget:** the dispatch is rejected with `no room for another tmux split` (or an equivalent teammate-pane creation failure) — this is the harness running out of room for its own teammate panes, not okstra placing a worker. (2) **Sandbox CLI-start failure:** an external CLI worker wrapper exits non-zero within seconds with empty stdout and its live-log shows `operation not permitted`. In either case the lead spends the one shared retry budget through the assignment's recorded runner. If the provider is still unavailable, record that terminal status and continue only under the convergence quorum rules; never replace it silently with a fixed provider or count a substitute as the original provider's vote. Completed external-CLI workers hold no pane of their own; the harness teammate panes are reclaimed by the selected runtime adapter's resource lifecycle. (This is a prompt instruction, not a code-enforced gate.)
 - Dual-audience final-report contract (shared):
   - data.json is the sole authored report artifact. AI handoff Markdown and human HTML are independently derived from it; neither derived artifact is the other's source.
   - User-facing information belongs in `humanSummary` and the selected task block's `userNarrative`; it must not exist only in Markdown. The HTML human main body explains the result with those fields plus task facts.
@@ -69,7 +69,7 @@ profile document.
     - `origin` — who raised it. `worker-finding` (an analyser or verifier reached it on its own evidence), `material-gap` (neither the brief nor the codebase answers it), or `lead-directed` (the lead's own judgment, **including anything the lead instructed a worker to raise**). A lead that seeds its conclusion into a worker prompt and then reports the worker's agreement as an independent finding has mislabelled the row; that shape is what let one run block on a question its own lead had authored.
     - `userConfirmation` — what happened before the row was written. `asked-and-answered`, `asked-awaiting` (asked, no answer yet), or `deferred-no-interactive-session` (this run had no user to ask). Record an answer in `userInput` and move `status` to `answered`.
     - Neither field is required once `status` is `answered` / `resolved` — the record lives in `userInput` by then.
-  - **Legacy canonical column schema (must match `templates/reports/final-report.template.md` §1 exactly):** every `## 1. Clarification Items` table has exactly these 4 columns, in this order:
+  - **Legacy canonical column schema (must match `templates/reports/final-report-v2.template.md` §1 exactly):** every `## 1. Clarification Items` table has exactly these 4 columns, in this order:
     `| <record-meta> | Statement | Expected form | User input |` (the first header is the i18n `columns.recordMeta` label — `Record`).
     The five short fields (ID, Ticket ID, Kind, Blocks, Status) are stacked inside the single record-meta cell, one per line separated by `<br>`, in this fixed order (mirrors the §2.1 Primary-Evidence meta column):
 

package/runtime/prompts/profiles/_implementation-executor.md

@@ -94,6 +94,8 @@ persisted prompt lacks the heading `Coding-conventions preflight`
 - **local git operations only**: `git add`, `git commit`. Prefer small commits keyed to plan steps.
 - **Explicit-path staging only (BLOCKING).** Stage exactly the files a plan step touches by naming each path — `git add <path1> <path2>`. Never use the bulk forms `git add .`, `git add -A`, `git add -u`, or `git add --all`: they sweep in unrelated edits, stray build output, and editor scratch files. Never use `git add -f` (force) under any circumstance — `-f` is the *only* way a `.gitignore`d path reaches a commit, and a forced ignored file is always a defect. If `git add <path>` reports the path is ignored, that file does not belong in the commit; do not override it — leave it untracked.
 - **No ignored / okstra files in commits (BLOCKING).** Before every `git commit`, run `git diff --cached --name-only` and pipe the staged paths through `git check-ignore --stdin --no-index`; abort the commit if it reports **any** match — a staged path that `.gitignore` excludes means a bulk-add or `-f` leaked it in. The check explicitly covers `.okstra/` (and `.project-docs/` when the legacy symlink is present): `.okstra/**` is gitignored, and force-staging it onto the stage branch is the one way these verification artifacts reach the upstream PR. Conformance/qa evidence belongs in the carry sidecar and verifier result — committing it is never correct, even when a step's instructions seem to ask for it.
+- **Clean-tree checks use `okstra worktree-status --check-clean` (BLOCKING).** The worktree you execute in carries okstra's own provisioning — `.okstra`, the synced entries (`.project-docs`, `.claude`, …), and the nested `stage-<N>/` worktree — so `git status --porcelain` is never empty here and its emptiness proves nothing about your stage. Use `okstra worktree-status --check-clean`: it asks the same question over source paths only and exits 1 when dirty, so it chains as an assertion. This applies to a check you write yourself AND to one you inherit: when a plan step's `command` cell asserts cleanliness with a bare `git status`, run the okstra command in its place and record the substitution in `Out-of-plan edits` — the step's intent was a clean stage, not a literal empty status.
+- **Never read an `.okstra/` artifact from a git object (BLOCKING).** `.okstra/**` is gitignored and never committed (see the staging rules above), so `git cat-file -e <tag>:.okstra/…`, `git show <tag>:.okstra/…`, and every variant of that read fail by construction — the answer is never "commit it after all". When a plan step's command depends on such a read, the step is unsatisfiable as written: read the artifact from the working tree instead, record the deviation, and carry the artifact forward through the stage carry sidecar.
 - **Commit message format (mandatory)**: every commit message MUST follow Conventional Commits — `<type>(<scope>): <subject>` for the first line, optional body separated by a blank line, optional footer. Constraints:
   - `<type>` MUST be one of: `feat` / `fix` / `perf` / `revert` / `deps` / `docs` / `refactor` / `build` / `ci` / `chore` / `test`. When the repo is `release-please`-managed, this aligns the commit with a configured changelog section.
   - `<scope>` SHOULD be the plan step identifier or the primary module touched (e.g. `feat(report-writer): ...`). Omit the parentheses only when no meaningful scope applies.