okstra 0.179.2 → 0.183.2

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

@@ -1,459 +1,119 @@
-# Okstra Report Writer Contract
+# Report Writer and Report Assembly Contract
 
-## File-author ownership (BLOCKING)
+## Phase 6 ownership
 
-The final-report data.json is authored by `Report writer worker` when that role is in the roster. The lead reviews the human HTML and the report record but does not write them. Lead-authored fallback is legal only after a real `dispatch_worker` attempt records `error`, `timeout`, or `not-run` with a concrete reason. `release-handoff` remains the intentional single-lead exception.
+Phase 6 gives the report writer all settled analysis, convergence, task, and planning context required for synthesis. Read access supplies context; it does not grant write authority over another owner's file.
 
-The JSON SSOT path is `runs/<task-type>/reports/final-report-<task-type>-<seq>.data.json`. Phase 7 produces the task-specific human HTML sibling from that record. The full reading copy is rendered on demand with `okstra render-final-report <data.json>`. The worker-result pointer at `**Worker Result Path:**` records the record path plus reconciled convergence input. Completion artifacts are the record, the pointer, and the audit sidecar; HTML follows during finalization.
+The report writer writes only the report narrative Markdown, its pointer record, and its audit sidecar. It must not write or patch `final-report-*.data.json`, the approval decision ledger, activity ledger, team state, convergence state, or design-preparation input.
 
-New bundles use `schemas/final-report-v2.0.schema.json`. The Markdown keeps verdict, routing, evidence, one structured task deliverable, and audit data for the next agent. The HTML uses `humanSummary`, task `userNarrative`, and structured facts for the user. Raw worker discussion, convergence mechanics, and usage belong to audit structures and never to the HTML human main body.
+The narrative owns judgments, plan body, summaries, user explanation, recommended steps, and follow-up descriptions. It never owns `designPreparation`, `designSurfaceCoverage`, `executionStatus`, `executionRoles`, `tokenUsage`, `crossVerification`, `approvalContext`, `clarificationItems`, `agentActivity`, or `planBodyVerification`. It must not pre-fill a future round, future gate result, activity identifier, usage value, or resolution.
 
-### Implementation-planning frontmatter contract
+Report assembly reads the role-owned inputs, validates them, derives links and statuses, and publishes the final record once. An error identifies `owner`, `artifactPath`, `fieldPath`, and `reason`; return it only to the named owner.
 
-#### Selected-direction
+## Role-owned inputs
 
-Emit `frontmatter.approved` as `false` and copy `implementationPlanning.selectedDirectionRef.snapshotPath` into `frontmatter.selectedDirectionRef`. You MUST omit `frontmatter.implementationOption`; the direction was selected upstream and cannot be selected again in planning. `schemas/final-report-v2.0.schema.json` enforces the required selected-direction reference and rejects an `implementationOption` property for this branch.
+| Input | Owner | Write boundary |
+|---|---|---|
+| report narrative Markdown | report-writer | `reportNarrativePath` |
+| approval decision ledger | lead | `approvalDecisionsPath` through `okstra approval-decision` |
+| activity ledger | activity recorder | `leadEventsPath` through `okstra agent-activity append` |
+| team state and usage | runtime/accounting adapter | `teamStatePath` |
+| convergence state and plan-body result | convergence engine | `convergenceStatePath` |
+| design-preparation snapshot | design-surface detector | `designPreparationPath` |
+| final report record | report assembly | `expectedReportRecordPath` |
 
-#### Legacy candidate-comparison
+An active clarification exists only in `activeClarifications[]`. A decision carried from a previous run exists only in `carriedDecisions[]`; do not recreate it as an active question.
 
-Emit `frontmatter.approved` as `false` and `frontmatter.implementationOption` as the empty string `""`. The user later flips `approved` to `true` and fills `implementationOption` with the chosen Option Candidate name to authorise and scope the next `implementation` run. Every other report type follows the same empty `implementationOption` default; the schema's non-selected-direction branch requires that field and rejects a selected-direction reference.
+Each decision option has `role`, `answer`, `rationale`, `disposition`, `reach`, optional `scopeEffects`, `addedWork`, and `directionChange`. `reach` is exactly one of `in-repo` or `cross-repo`. `scopeEffects` may contain `new-schema` and `deferrable`. A `correctness-critical` option cannot use `select` or `accept-risk`; a `noncritical-dissent` option cannot use `select`.
 
-**As the report-writer worker:** YOU write the report record; the file on disk is the canonical record, so do not return it inline. Do not invoke `okstra render-final-report`.
+Resolution `checkRefs` name existing `A-NNN` activity rows. Those activity rows carry `clarificationRefs[]`; their `planItemIds[]` let report assembly derive the reverse plan-item links. Do not store copied plan or activity identifiers in `approvalContext`.
 
-**As the lead:** prepare the report-writer prompt, dispatch the Report writer worker per the Phase 6 dispatch template in okstra-lead-contract.md, and review the record, the pointer, and the separate audit sidecar in Phase 7. Do not call `write_artifact` against the report paths or worker-result pointer yourself when Report writer worker is in the roster.
+## Report-writer dispatch
 
-## When to Use
+For report contract 3.0, prompt materialization first freezes one report synthesis
+packet. The packet contains the task brief, analysis packet, report template,
+report schema, convergence state, every successful settled worker result recorded
+by the run manifest, accumulated `user-responses/` sidecars, and the current
+session/token/cost accounting snapshot. Each file-backed source carries its owner,
+project-relative path, SHA-256 digest, and value. The report writer receives the
+packet's Markdown reading projection as the only task input instead of an
+independently assembled list of raw paths.
 
-- During okstra lead Phase 6 (final report assembly)
-- During okstra lead Phase 7 (artifact persistence — verification only when Report writer worker is in roster)
-- When verifying the structure of the final report
+The packet's authoring contract names the result path, narrative format, writing
+instructions, runtime-owned content, and validation rules. Missing configured
+paths and missing files are collected across the full source set before dispatch
+and reported together with their owners. Report assembly compares every frozen
+source digest again and reports every changed or missing source in one result.
+This is enforced by
+`initial_prompt_materialization._materialize_report_writer_packet()`,
+`report_synthesis_packet.build_report_synthesis_packet()`, and
+`report_assembly.assemble_report()`.
 
-## Phase 6 dispatch template (Report writer worker)
+Materialize the duty prompt with `okstra agent-prompt materialize --audience report-writer`. The prompt starts with these anchors in order:
 
-1. Resolve the Report writer worker assignment and all required prompt/result/error paths from the manifests.
-2. Write a call-specific task-instructions file containing the anchor headers and audience-specific reading list.
-3. Run `okstra agent-prompt materialize --audience report-writer --assignment-ref initial/report-writer --worker-id report-writer --dispatch-kind report-writer ...`, then run `okstra agent-prompt verify` against the returned `metadataPath`. Use the returned `promptPath` without appending role prose. A correction redispatch repeats this step with a fresh invocation ID and the same audience and assignment reference.
-4. Emit the Phase 6 checkpoint.
-5. For `runner=native-session`, first run `okstra agent-prompt record-dispatch` with the project root, run manifest, metadata path, and `--enforcement-mode host-native-spec-link-gate`, then call the host primitive with only the returned `hostModelValue`. After its result exists, run `okstra agent-prompt link-result` with `--dispatch-id <invocationId>:attempt-1` and the result path before accepting it. For `runner=cli-wrapper`, call `okstra team dispatch` when `terminalBackend` is `cmux-pane`, or `okstra worker-dispatch --workers report-writer` otherwise, which consumes `modelExecutionValue` and verifies the metadata before starting the provider process. Never combine this Phase 6 call with analysis workers.
-6. Call `await_workers([handle])` and verify the data.json Result Path and worker-result pointer at Worker Result Path. Verify the separate heartbeat audit sidecar before accepting the run. **Enforced:** both dispatch adapters keep the two completion paths in `WorkerJob.completion_paths`, and `validators/validate_session_conformance.py` validates the audit sidecar.
+1. `**Project Root:**`
+2. `**Prompt History Path:**`
+3. `**Result Path:**`
+4. `**Worker Result Path:**`
+5. `**Worker Preamble Path:**`
+6. `**Worker Error Contract Path:**`
+7. `**Errors log path:**`
+8. `**Errors sidecar path:**`
 
-The complete assignment supplies both runner-specific model values and the prompt header in item 9 below. A native host uses `hostModelValue`; a deterministic provider process uses `modelExecutionValue`; the recorded `**Model:**` header remains the canonical assignment label. Missing or unsupported model resolution is a pre-dispatch contract failure; the common contract does not choose a runtime fallback.
+The errors sidecar anchor reserves the runtime-owned write-artifact path used by dispatch validation. No model-authored error JSON file is part of report-writer dispatch; failures use the typed error-log command from the worker error contract.
 
-The prompt MUST include, in this order at the top:
+Register the dispatch with `okstra agent-prompt record-dispatch`. When `terminalBackend` is `cmux-pane`, run `okstra team dispatch`; for `runner: cli-wrapper`, run `okstra worker-dispatch --audience report-writer`. Attach the result through `okstra agent-prompt link-result`. The result path is the report narrative Markdown, not the final record.
 
-1. `**Project Root:** <absolute-path>`
-2. `**Prompt History Path:** <project-relative-path>` (under current run `prompts/`)
-3. `**Result Path:** runs/<task-type>/reports/final-report-<task-type>-<seq>.data.json` — canonical JSON SSOT. The full reading copy is rendered on demand.
-4. `**Worker Result Path:** runs/<task-type>/worker-results/report-writer-worker-<task-type>-<seq>.md` — canonical three-path worker-result pointer and source for the audit-path derivation.
-5. `**Audit sidecar path:** <absolute-path>` — the generated report-writer heartbeat/read-confirmation destination derived from the Markdown `**Worker Result Path:**`, never from Result Path.
-6. `Assigned worker prompt history path: <absolute-path>`
-7. The four BLOCKING dispatch anchor headers generated from the report-writer audience (the worker cannot synthesize any of these paths):
-   - `**Worker Preamble Path:** <absolute-path>` — selects `templates/report-writer-prompt-preamble.md`.
-   - `**Worker Error Contract Path:** <absolute-path>` — selects `templates/worker-error-contract.md`.
-   - `**Errors log path:** <absolute-path>` — run-level errors JSONL (`logs/errors-<task-type>-<seq>.jsonl`).
-   - `**Errors sidecar path:** <absolute-path>` — this worker's per-run sidecar JSON (`worker-results/report-writer-worker-errors-<task-type>-<seq>.json`).
-8. `**Prompt Delivery Mode:** <mode>` — the selected adapter's declared `initialPromptDeliveryMode`.
-9. `**Model:** Report writer worker, <modelExecutionValue>` (resolved per Phase 5.5 anchor-header rules)
-10. The full `[Required reading]` clause (see [team-contract](./team-contract.md)) — for Phase 6 it adds two **per-task-type, instruction-set-local** read-only files, both scoped to this run's task-type by `okstra-ctl` at prep time:
-   - `<instruction-set>/final-report-schema.json` — a task-type excerpt of schema v2. This is the binding authoring shape; the installed full schema is what the run is judged against. Do **NOT** pull the full repository schema because it is outside the task bundle.
-   - `<instruction-set>/final-report-template.md` — the full reading copy template. It shows the agent-facing ledger shape, not the human presentation. The task-specific HTML renderer reads data.json separately.
-11. The analysis packet path plus a one-line MCP pointer instead of copying the server block verbatim: `**MCP servers:** follow the analysis packet's "Available MCP Servers" section. If the section is absent or says none, treat MCP as unavailable for this run; never infer tools from host configuration.`
-12. `Convergence state: runs/<task-type>/state/convergence-<task-type>-<seq>.json`, followed by pointers to all analysis-worker result files under `worker-results/`. The convergence path is deterministic and is listed even before Phase 5.5 creates the file. Read its classifications (Full/Partial/Contested/Worker-Unique), `roundHistory[]`, `round2SkippedReason`, and `finalClassificationCounts`; populate `crossVerification.roundHistory` in data.json so Section 6 can show which rounds executed, queue sizes, and why Round 2 was (or was not) skipped. The renderer prints the full per-round table only when more than one round ran; single-round or zero-round histories are auto-collapsed to a one-line summary.
-13. `**Report Language:** <en|ko>` — must be either `en` or `ko`; `auto`
-    has been resolved by the lead from project.json / global config
-    before the dispatch is constructed. The worker copies this verbatim
-    into `data.json.meta.reportLanguage`.
-14. An explicit instruction: `You are the author of TWO files: (a) the report record at <Result Path>, and (b) the worker-result pointer at <Worker Result Path>. Maintain the separate heartbeat audit sidecar at <Audit sidecar path>. Do not return the report inline. Do not invoke okstra render-final-report. The dispatch fails when either completion artifact is missing, and session conformance fails when the audit sidecar is missing or invalid.`
-15. The prose budget (dedup contract): `verdictCard.finalConclusion` is the conclusion SSOT — at most 3 sentences. `rationale.*` fields stay within 2 sentences each; `humanSummary` entries stay concise; task `userNarrative` explains each user-facing section once with evidence references. Do not copy these narratives into the AI Markdown. `summary` stays at 3-5 rows unless the run covers multiple tickets. Generation time scales with output volume, so exceeding the budget is a cost bug, not extra diligence.
+The pointer record contains the narrative and audit paths. Completion never depends on the final record because assembly runs after writer completion.
 
-**Fix-run incremental authoring (applies when the run's profile carries a "Fix-Run Carry" block).** Do not author the data.json from scratch. Start by copying the previous run's data.json (the `Previous report` path in the Fix-Run Carry block) to this run's Result Path, then update ONLY the blocks the fix run changed: `meta`/`header` (run seq, dates), `executionStatus`, `implementation.verifierResults`, `implementation.validationEvidence`, `implementation.commitList` / `diffSummary`, `crossVerification`, `verdictCard`, `finalVerdict`, and any `evidence` rows the fix touched. Deliverable prose for unchanged sections is carried forward verbatim — do not re-generate it. Do not invoke the reading-copy renderer. The schema validation contract is unchanged, so an incrementally-authored data.json passes the same post-hoc gates. The lead's dispatch prompt MUST include the previous data.json path when the carry block is present.
+## Implementation-planning sequence
 
-**Completion detection after dispatch (BLOCKING).** A dispatch acknowledgement is NOT completion — detect completion via the SSOT protocol in [team-contract](./team-contract.md) "Worker-completion detection", with a pending set covering the data.json (Result Path) and worker-result pointer (Worker Result Path). Check the separate audit sidecar before accepting conformance. Do NOT end the turn with a prose "waiting for the report" statement. **Enforced:** the adapters reject a completed transition while any `completionPaths` entry is absent; `validators/validate_session_conformance.py` owns the audit check.
+1. Dispatch the report writer and wait for the narrative and pointer.
+2. Parse the narrative and extract the deterministic plan-item queue without publishing `data.json`.
+3. Run initial plan-body verification as round 1.
+4. Apply at most one automatic planner self-fix to the narrative.
+5. Run targeted re-verification as round 2 when needed.
+6. Persist the completed `planBodyVerification` value in convergence state.
+7. Complete the design-surface detector snapshot.
+8. Run Phase 7 report assembly.
 
-### Resume-safe dispatch
+The writer never predicts steps 3–7 in its draft. The plan-body verifier reads the plan body, and report assembly adds its completed result afterward.
 
-A resumed lead can always call `redispatch_worker` for a fresh Report writer worker. Resume/session mechanics are adapter-owned and are never a reason to bypass the role.
+**Implementation-planning direction branch.** A selected-direction narrative carries `selectedDirectionRef` and `directionRealization`; the `P-Dir-1` verifier checks that realization against the selected core mechanism, architecture boundaries, planning invariants, and any hidden direction change. A legacy candidate-comparison narrative retains `P-Opt-*` option comparison semantics. These are plan-body judgments, not frontmatter fields owned by the writer.
 
-### Lead-authored fallback (only if dispatch failed)
+**Implementation-option-selection comparison.** Candidate details remain direction-level and must not claim planning precision:
 
-Except for `release-handoff` (which is single-lead by design and never dispatches a Report writer worker — see "Release-handoff section contract" below), lead-authored fallback is permitted only if all of the following are true and recorded in team-state:
-
-1. A Report writer worker dispatch was actually attempted through `dispatch_worker`.
-2. The attempt recorded a terminal status of `error`, `timeout`, or `not-run` with a concrete reason (tool error message, timeout duration, or external blocker).
-3. The reason is logged via `okstra error-log append-observed --error-type cli-failure ...` (or `tool-failure` if the failure was internal).
-4. **The user permitted it.** Ask at a gate, and have the answer written to this run's `user-responses/` sidecar as a `## REPORT AUTHORING` block with `- Status: approved` (`okstra user-response write --report <data.json> --answers '[]' --report-authoring '{"status":"approved","reason":"<the user's words>"}'`). A failed dispatch is your cue to ask, not your permission — a lead that dispatches once, watches it fail, and proceeds has still decided alone. You cannot write this block for yourself; it is the user's answer, in the user's file.
-5. **Record it in the report.** Set `header.leadAuthoredFallback` with `dispatchFailureReason` quoted verbatim from the failed dispatch row and `approvalSidecar` set to that sidecar's project-relative path. The approval passes the gate; it does not retire it. This block renders under `Report Author`, so someone reading the report months later sees that this run left the report-writer path and why, without having to find the sidecar.
-
-Speculative reasons such as "session resume constraint", "runtime state is unavailable", or "lead can do it faster" are NOT valid.
-
-**Enforced:** `validators/validate-run.py` `_validate_lead_authored_report` checks all of it — the terminal failure status, its reason, the approving sidecar block, and the `header.leadAuthoredFallback` record whose reason must match the dispatch row. `release-handoff` is exempt because it never dispatches a report writer.
-
-
-## Phase 6 → Phase 7 execution sequence (BLOCKING order)
-
-Phase 6 first produces the report record at `runs/<task-type>/reports/final-report-<task-type>-<seq>.data.json`. Token Usage cells are `null` at this point, and Section 3 does not yet include auto-spawned follow-ups.
-
-For an implementation-planning run, the Report writer worker owns the Phase 6 design assessment snapshot: it writes `designPreparation` and every stage's `designSurfaceCoverage` into data.json from the detector output and consolidated plan. It does not create user inputs, consume a user answer as if it were part of that snapshot, or materialize `design-prep-requests/`; `schemas/final-report-v2.0.schema.json` and `validators/validate-run.py` `_validate_design_prep_contract` enforce the snapshot shape, detector coverage, and references.
-
-### Before `report-finalize`: the translation sidecar (BLOCKING order)
-
-The finalization renderer overlays the translation sidecar, so a non-English run must produce that sidecar before finalization. Use this fixed order:
-
-1. **For a non-English report only**, run `okstra report-finalize ... --only project-activity --only check-source`. The shared finalizer projects canonical activity before checking the English source. A historical manifest without `activityContractVersion: 1` leaves data.json unchanged.
-2. **Only when that check passes**, dispatch the translator worker, which writes `final-report-<task-type>-<seq>.i18n.<lang>.json`.
-3. Run the full `report-finalize` command below. English reports start here; the finalizer repeats the idempotent projection and source check before every downstream step.
-
-For step 2, write translator-only task instructions and run `okstra
-agent-prompt materialize` with `--audience translator`, `--assignment-ref
-translator`, `--worker-id translator`, and `--dispatch-kind translator`. Run
-`okstra agent-prompt verify` on the returned `metadataPath` before dispatch and
-use the returned `promptPath` unchanged. A native-session call uses only
-`hostModelValue`; first run `okstra agent-prompt record-dispatch` with the run
-manifest, metadata path, and `--enforcement-mode
-host-native-spec-link-gate`, then run `okstra agent-prompt link-result` with
-`--dispatch-id <invocationId>:attempt-1` and the translation result before
-accepting it. A CLI-wrapper call uses `okstra team dispatch` when `terminalBackend` is
-`cmux-pane`, or `okstra worker-dispatch` and its `modelExecutionValue`
-otherwise. The host-native record links the accepted result to a
-verified call specification but does not assert that Okstra observed the host's
-actual prompt delivery.
-
-**Never dispatch the translator before step 1.** The data.json is the English SSOT; a report-writer that authored it in the reader's language produces a translation *from that language into itself* — a full-cost, entirely useless artifact, and the run still fails at `check-source` afterwards. **Enforced:** `okstra report-translate extract` refuses to build a work list from a data.json over the Korean-prose limit, so a mis-ordered dispatch fails at the translator's first command instead of after it. When it does fail, the fix is a report-writer rewrite in English — discard the sidecar and `translation-source.json` produced from the Korean draft rather than editing them, because their English column is not English.
-
-Phase 7 post-processing is then **one command**. `okstra report-finalize` owns the ordered sequence — it is the same code path the Codex lead adapter runs automatically, so a Claude-led run and a Codex-led run finalize identically:
-
-```bash
-okstra report-finalize \
-  --project-root <project_root> \
-  --run-manifest <runDirectoryPath>/manifests/run-manifest-<task-type>-<seq>.json \
-  --report <runDirectoryPath>/reports/final-report-<task-type>-<seq>.data.json
-```
-
-Do NOT run the seven steps below by hand. Hand-running them is the recurring root cause of reports shipping with stale activity, `--` token cells, a missing html sibling, Section 3 missing follow-up entries, or Section 4 rows never spawning — the order is load-bearing and a skipped step surfaces only later, as a validator `contract-violated`. Every step is idempotent, so after fixing a reported failure just re-run the same command.
-
-The steps it executes, in this contractual order, and the contract each one carries:
-
-1. **`project-activity` — project canonical activity.** Replaces only `agentActivity[]` from this run's canonical events before translation source extraction. A legacy manifest without activity contract v1 is a byte-preserving no-op. Conformance compares IDs, order, and every core field against the canonical events.
-2. **`check-source` — verify the data.json is English.** The same gate as the pre-translator check above, run again here because everything after it derives from the data.json: rendering a Korean SSOT into English chrome, spawning follow-ups from it, and validating it all succeed on a record the next phase cannot read. A failure here means the report-writer authored in the reader's language; re-dispatch it with the English rule rather than editing the data.json by hand.
-3. **`token-usage` — collect usage.** Aggregates `leadUsage` / `workers[].usage` / `usageSummary` into team-state and populates `tokenUsage` and the execution-status usage fields in data.json. It does not render the full reading copy.
-
-   The data.json paths populated: `tokenUsage.lead.{totalTokens,billableTokens,costUsd}`, the `worker` / `grand` rows, `tokenUsage.cli.costUsd`, and each `executionStatus[].{totalTokens,billableTokens,costUsd,durationMs,cliTotalTokens,cliCostUsd}` for rows whose role matches a team-state worker. The data.json MUST already exist (Phase 6 output).
-
-   For implementation-planning, this Phase 7 canonical render calls `materialize_design_prep_requests()` after token substitution and creates deterministic request files only for `provisional` / `blocked` items. Later answers are append-only user-input sidecars; request generation and user input never rewrite the assessment fields, so the source report remains immutable as the design-input snapshot after this render. `validators/validate-run.py` `_validate_design_prep_requests` enforces request existence, canonical path, content, and assessment fingerprint.
-4. **`render-views` — render the human report artifact.** Runs against the substituted v2 data.json and its Markdown sibling.
-
-   Output (idempotent — re-running overwrites):
-   - `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — single-file self-contained human view, always generated for schema v2 from the dedicated template registered for that task type. Clarification rows with `Status` ∈ {`open`, `answered`} embed response controls and export a `user-response-<task-type>-<seq>.md` sidecar. The original data and Markdown artifacts are never mutated by user input.
-   - the implementation-planning report renders a **Plan Approval** section at the end of the body — an implementation-option `<select>` plus approval checkbox for legacy candidate-comparison, and an approval checkbox only for selected-direction plans. It stays disabled while any §1 `Blocks: approval` row is unresolved.
-   - Schema-v1 and quick compatibility reports retain the legacy conditional HTML path; this does not change the schema-v2 always-generated contract.
-
-   It runs after usage collection so token placeholders are substituted in any rendered html, and before routing persistence so the html artifact, when generated, exists for the validator step that checks it. It also overlays the translation sidecar, which is why a non-English run must dispatch the translator before this command — see the ordering rule above.
-5. **`spawn-followups` — routing and follow-up persistence.** Turns the report's `## 4. Follow-up Tasks` rows into `tasks/<task-group>/<new-task-id>/` stubs.
-
-   Behaviour contract:
-   - Idempotent: rows whose target dir exists are reported as `existing` and skipped. Reruns of the same parent task are safe.
-   - Rows with `autoSpawn != "yes"` are reported as `skipped` and never written; surface them in Section 3 if manual action is still needed.
-   - Rows whose `origin` is `phase-continuation` are reported as `skipped (no new task dir)` and never spawn — they advance the same task-key via `/okstra-run` instead.
-   - An invalid `origin`, `suggestedTaskType`, missing `title`, missing `reason`, or missing `newTaskId` exits `1`. (Schema validation in Phase 6 catches most of these before the spawner runs.)
-   - **Canonical spawn rule (single source of truth):** the spawner runs when `task-type` ∈ {`implementation`, `final-verification`, `release-handoff`}, OR when `followUpTasks` is non-empty for any other task-type. For the listed task-types `followUpTasks` must be present (schema enforces the phase-continuation row for non-terminal task-types); an empty array is permitted only for `release-handoff`. Missing arrays are no-ops (exit `0`). All other references to this rule (including the Persistence Checklist) defer to this statement.
-   After the spawner, the report writer MUST append one row per newly spawned task-key with its entry command:
-
-   ```
-   - Follow-up: `<task-group>/<new-task-id>` — in-session `/okstra-run task-key=<task-group>/<new-task-id> task-type=<suggested>` / standalone `scripts/okstra.sh --task-key <task-group>/<new-task-id> --task-type <suggested>`
-   ```
-
-   The status file is written after routing and follow-up persistence completes.
-6. **`validate-run` — validate the finished run.** Checks the completed artifact set, including exact canonical-event-to-`agentActivity[]` conformance and the report-views contract that catches a missing or stale html sibling. A failure here names the specific contract; fix it and re-run `okstra report-finalize`.
-
-7. **`teardown-stages` — reclaim the stage worktrees.** In-process, and a no-op for every run except a whole-task `final-verification` whose verdict clears the work for release (`accepted`, or `conditional-accept` with no condition blocking release). Whole-task entry merges the done stages but deliberately leaves their worktrees and registry stage-keys in place, because a `blocked` verdict routes straight back to rework on those trees. This step is where they are reclaimed once the verdict says the work is moving on. A stage worktree with uncommitted changes is preserved; stage branches are never deleted.
-
-After `okstra report-finalize` reports `"ok": true`, **execute the run-scoped cleanup gate.** Call `shutdown_workers` only after that success, all persistence work, and explicit user approval under [okstra-lead-contract](./okstra-lead-contract.md) "Run-scoped worker-resource lifecycle". If the user keeps resources, leave the selected adapter's resources intact and surface its manual cleanup guidance.
-
-## Schema-v2 report data responsibilities
-
-The binding authoring shape is the task bundle's `instruction-set/final-report-schema.json`. Populate both audiences in data.json: agent-facing verdict, routing, evidence, task facts, and audits; user-facing `humanSummary` and task `userNarrative`. The full reading copy template deliberately omits the full user narrative, while the task-specific HTML deliberately moves `crossVerification`, `executionStatus`, and `tokenUsage` into collapsed audit details.
-
-## Legacy schema-v1 Markdown structure reference
-
-The remaining numbered-section guide exists only for rendering or diagnosing historical schema-v1 data. New report-writer runs do not author against it; their instruction-set schema and full reading copy template are authoritative.
-
-### Report Header
-
-Read the exact permitted values for `header.reportOwner` and `header.reportAuthor` from the task bundle's `instruction-set/final-report-schema.json` excerpt, then write those values according to the actual authorship path. The current v2 contract uses the provider-neutral `Okstra lead`; a legacy v1 excerpt may retain historical compatibility values. Do not derive either header field from the selected runtime's provider-specific lead label. Runtime identity remains visible in the execution-status row and team-state audit fields.
-
-```markdown
-# <task-key> - Multi-Agent Cross Verification Final Report
-- Date: <ISO 8601 timestamp>
-- Task Key: <task-key>
-- Task Type: <task-type>
-- Report Owner: `<exact schema header.reportOwner compatibility value>`
-- Report Author: `<exact schema header.reportAuthor compatibility value for the actual authorship path>`
-- Lead model: `<lead-model>`
-- Preparation Method: Final report authored by Report writer worker (or lead-authored fallback — record the documented dispatch failure reason here when applicable; the machine-readable record is `header.leadAuthoredFallback`, which is what the validator and the rendered report both read)
-```
-
-### Agent-Specific Execution Status Table
-
-The template renders this table in the merged record-meta shape (same pattern as §1 / §2.1): one meta cell stacking the short fields, one findings cell. The writer supplies the per-agent fields in data.json; the rendered form is:
-
-```markdown
-| Record | Summary of Key Findings |
-|--------|-------------------------|
-| **<team-state.lead.agent>**<br>Role: <team-state.lead.role><br>Model: <model><br>Status: completed<br>Raw tokens: <tokens><br>Billable: <billable><br>Cost: <cost><br>Duration: <duration> | Final synthesis status |
-| **<team-state.workers[].agent>**<br>Role: <team-state.workers[].role><br>Model: <model><br>Status: <status><br>Raw tokens: <tokens><br>Billable: <billable><br>Cost: <cost><br>Duration: <duration> | Key findings summary |
-```
-
-Table Generation Rules:
-- **Exactly one row per team-state entry: the lead, then one per `team-state.workers[]` — never more, never fewer.** The first row's agent / role / usage come from `team-state.lead.agent` / `team-state.lead.role` / `leadUsage`. Each later row copies its `agent`, `role`, and `model` **verbatim from a `team-state.workers[]` entry** (e.g. role `Claude worker`, `Codex worker`, `Report writer worker`), ordered to follow `recommendedWorkers` / `resultContract.requiredWorkerRoles`. Do not infer labels from provider names.
-- **Never split one worker into multiple function rows or invent role labels** (`Analysis verifier`, `Acceptance critic`, …). A provider that played several roles — e.g. codex ran both the analysis-verify pass and the acceptance-critic pass — is still **one** `team-state.workers[]` entry with **one** usage figure: name the roles it played in that row's *Summary of Key Findings* cell, not in extra rows. Extra or renamed rows break Phase-7 token attribution, which keys each row's tokens to a single team-state worker — a split or renamed row lands as `--`.
-- **Raw tokens** = `usage.totalTokens` (input + output + cache_creation + cache_read; the raw volume processed).
-- **Billable tokens** = `usage.billableEquivalentTokens` (cache reads weighted at 0.1×, cache_creation 1.25×, output 5×; useful as a single number for "how big was this session in cost terms").
-- **Cost (USD)** = `usage.estimatedCostUsd`. For Codex/Antigravity workers that actually invoked the CLI, append `(+ CLI $X.XX)` from `usage.cliEstimatedCostUsd`.
-- For Codex/Antigravity workers, append `(CLI: <cliTotalTokens>)` to the Raw tokens cell when `usage.cliTotalTokens` is set.
-- Status values are retrieved from team-state; format duration as `Xm Ys` from `usage.durationMs`.
-- Workers with status `not-run` or unavailable usage evidence show `--` for tokens/cost/duration; quote the `note` underneath the table if useful.
-
-### Token Usage Summary Section
-
-Place this section immediately after the execution status table.
-
-Example (the Markdown renders in English whatever `meta.reportLanguage` says):
-
-```markdown
-### Token Usage Summary
-
-| Item | Raw tokens | Billable tokens (input-equiv.) | Cost (USD) |
-|------|------------|--------------------------------|------------|
-| Lead | 10,479,327 | 1,769,798 | $26.55 |
-| Worker subtotal | 7,988,699 | 2,075,192 | $25.43 |
-| **Grand total** | **18,468,026** | **3,844,990** | **$51.97** |
-| Codex/Antigravity CLI add-on |  |  | $4.12 |
-
-> **How to read**: "Raw tokens" is the total tokens the model actually processed (input + output + cache_creation + cache_read). In long sessions cache_read can account for 95%+ making the number look large. "Billable tokens" weights cache_read at 0.1×, cache_creation at 1.25×, and output at 5× to give an input-equivalent figure closer to actual cost. Costs are estimates based on published Anthropic/OpenAI/Google pricing.
+```json
+{"candidateDetailBoundary":{"expectedChangeAreas":"direction-level-only","expectedVerification":"direction-level-signals-only","forbidden":["exact-file-lists","stage-lists","test-commands"]}}
 ```
 
-Token Summary Generation Rules:
-- **You populate the data.json in Phase 6, BEFORE Phase 7 runs the collector.** Set `tokenUsage.lead.totalTokens` / `.billableTokens` / `.costUsd`, the `worker` and `grand` rows, `tokenUsage.cli.costUsd`, and each `executionStatus[].{totalTokens,billableTokens,costUsd,durationMs,cliTotalTokens,cliCostUsd}` to JSON `null`. The renderer emits `--` for nulls; `okstra-token-usage.py --substitute-data` populates them in Phase 7 and re-renders the markdown. Never set these cells to `0`, `"not-collected"`, `"--"`, `"N/A"`, or any other sentinel: nulls are the only valid placeholder, and the substitution step depends on them being null when it runs.
-- Set `meta.reportLanguage` to the resolved `en` or `ko` value passed in
-  **Report Language**. `auto` is forbidden in this field — the lead has
-  already resolved it. The field records **which language the human HTML
-  renders in**, not the language you author in: you always author English
-  (see "Writing Guidelines" below). Phase 7 reads it to decide whether to
-  dispatch the translator.
-- All values come from `usageSummary` (populated by `scripts/okstra-token-usage.py` at the start of Phase 7). Do not estimate or invent.
-- **Lead** row: `usageSummary.leadTotalTokens` / `usageSummary.leadBillableEquivalentTokens` / `usageSummary.estimatedCostUsd.lead`.
-- **Worker subtotal** row: `usageSummary.workerTotalTokens` / `usageSummary.workerBillableEquivalentTokens` / `usageSummary.estimatedCostUsd.claudeWorkers`.
-- **Grand total** row: `usageSummary.grandTotalTokens` / `usageSummary.grandBillableEquivalentTokens` / sum of `lead + claudeWorkers`.
-- **Codex/Antigravity CLI add-on** row: `usageSummary.estimatedCostUsd.cliWorkers`. The writer only supplies the value in data.json — the renderer emits the row when the CLI cost is > 0 and omits it entirely at 0 (`final-report.template.md` gates it on `tokenUsage.cli.costUsd > 0`), so do not expect a `$0.00` row in the rendered report.
-- Format tokens with comma separators (e.g., `32,500`); format USD with two decimals (e.g., `$1.43`).
-- If `lead` or any `worker.usage` records unavailable evidence, show `--` for that row and append a one-line note (`reason: <note>`).
-- If pricing for a model is unknown, the script omits `estimatedCostUsd` for that block — show `N/A` in that column and add a note like `pricing missing for model <model>`.
-
-### Implementation-planning section heading contract (schema v1 only)
-
-**This does not apply to any run you will author.** New runs are schema v2 (`report_contract.CURRENT_REPORT_SCHEMA_VERSION`), and `validate_phase_boundary` returns before the substring scan when `schemaVersion == "2.0"` — the v2 deliverable is gated by the schema instead, whose `implementationPlanning` block requires every one of these contents as a named key. The v2 full reading copy template carries nine headings and serialises the plan as JSON beneath them, so it cannot produce these strings and is not expected to.
-
-Reading this section as a live instruction is a known and expensive mistake: the writer is sent to author headings the v2 template has no place for, and the run reads as structurally unpassable when nothing is wrong with it. It is retained only for rendering or diagnosing historical schema-v1 reports.
-
-For those v1 reports, the final report must contain section headings whose **lines include each of the 12 literal English substrings below**. The rows mirror `PLANNING_REQUIRED_SECTIONS` in `validators/validate-run.py`, which is the SSOT. **Enforced:** `tests/contract/test_planning_required_sections_ssot.py` fails when this table and that tuple diverge, and pins the v1 scoping above so the section cannot silently become unconditional again.
+For historical schema-v1 Markdown only, the following heading table remains a read-side compatibility reference. It is not an authoring instruction for report contract 3.0.
 
 | # | Required substring | Recommended heading form |
-|---|--------------------|--------------------------|
-| 1 | `Option Candidates` | `### Option Candidates (Korean gloss)` |
-| 2 | `Trade-off` | `### Trade-off Matrix (Korean gloss)` |
-| 3 | `Recommended Option` | `### Recommended Option (Korean gloss)` |
-| 4 | `Stage Map` | `## 5.5 Stage Map (Korean gloss)` — the per-stage sections hang off it. |
-| 5 | `Stepwise Execution Order` | `### Stepwise Execution Order (Korean gloss)` |
-| 6 | `Dependency` | `### Dependency / Migration Risk (Korean gloss)` |
-| 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-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-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-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)
-
-Lead instructs a self-fix round as **cause groups**, not a flat `P-*` list (`plan-body-verification.md` §"Round protocol" step 7). Treat each group's `causeSummary` as the unit of work: remove that cause once, then confirm every derivative item it names is settled by that single correction. Correct the plan sections the group's items point to — do NOT rewrite the entire draft:
-
-- abbreviated path → replace with the full relative path from `<PROJECT_ROOT>` (File Structure / Stepwise `files`).
-- prose command → make it concrete as an executable command sequence including the working directory, arguments, and task-type.
-- placeholder (e.g. `stage-<N>`) → replace with concrete filenames / a regeneration plan.
-- requirement-coverage mapping error → remap to a real option/stage/step or XP row.
-- missing/weak design-prep contract → fix with kind-specific inline detail or an AI-prepared PREP item carrying a concrete `aiProposal`. Do NOT invent facts requiring user/external authority — keep them `blocked` + request material.
-
-**Carry the correction to its contradictions (BLOCKING).** "Only the section the item points to" bounds *which defect you fix*, not *how far the fix reaches*. When a correction changes a constant, an owner, a path, or a disposition, every other statement in the plan asserting the old value is now false — find and rewrite those too, in whatever section they sit.
-
-**Enumerate before you edit.** Patching at the positions the lead named is what makes a round trade one defect for another: the correction lands, its siblings keep asserting the old value, and the next round finds a *new* contradiction the fix itself created. So for each cause group, first list every place the plan mentions that decision — grep the constant, the symbol, the path, the requirement ID across the whole plan body including rejected options, per-stage `Test case (…)` lines, `Acceptance`, `exitContract`, `stageValidation`, and the Requirement Coverage row — then reconcile each hit against the new decision and only then write. `okstra plan-items derivations --data <data.json> --response <user-response sidecar>` does that grep mechanically: it extracts the symbols, paths, and ids the answer names and returns every plan string that mentions one, as a pointer plus excerpt. Its output is candidates, not verdicts — which hits are now false is yours to decide — but starting from it is what stops the enumeration from being skipped, which is the observed failure (17 of 23 blocked items in one run were a recorded decision whose derivations were never swept). Record the enumeration in the group's supersession entry so the next round can see what was considered in scope. A patch that leaves its own contradictions standing produces the same defect class in the next round, so the loop spends its budget re-finding what the previous round created. Record each retirement in `implementationPlanning.supersessionLedger[]` exactly as the answer-carry-in rule requires (`_common-contract.md` §"Supersession").
-
-**Record the reach.** For each cause group you rewrite, list the data.json paths you actually changed in that group's `rewrittenPaths`, and the subset of those lying outside the sections its `itemIds` point at in `outsideScopePaths` (e.g. `stages[0].stepwiseExecution`, `validationChecklist[3]`). Carrying a correction to its contradictions legitimately reaches past the flagged item, so the second list is a measurement and not a violation — no threshold is applied to either. It exists because "this round was a targeted correction, not a full regeneration" is currently a claim with nothing behind it, and a round that quietly rewrites the whole draft costs the same tokens every time it repeats. **Enforced:** `validators/validate-run.py` `_validate_self_fix_rewrite_scope` requires every `outsideScopePaths` entry to appear in `rewrittenPaths`.
-
-After correcting, leave `self-fixed in round <N>: <what was fixed>` in that `planItems[].selfFixNote`. Do NOT set `planBodyVerification.selfFixRoundsApplied` — the lead owns that count and records it at the round's end, so promotion eligibility does not hang on a worker's self-report. `needs-user-input` items are NEVER a correction target — they are promoted to clarification as-is.
-
-Lead may instruct several rounds (bounded by `selfFixMaxRounds`, see [plan-body-verification](./plan-body-verification.md) §"Round protocol" step 7). Each round targets only the items still broken, so a round that fixes nothing new ends the loop — correcting an item by breaking a sibling counts as no progress, not progress.
-
-### Final-verification verdict token contract (BLOCKING)
-
-When the run's `task-type` is `final-verification`, the report's `## 7. Final Verdict` table MUST contain a `Verdict Token` row whose value is **exactly one of** the literal strings below. The `release-handoff` profile reads this row as its entry gate; any other value blocks the next phase.
+|---:|---|---|
 
-| # | Required substring | Meaning |
-|---|--------------------|---------|
-| 1 | `accepted` | All acceptance criteria pass; `release-handoff` may proceed. |
-| 2 | `conditional-accept` | Acceptance passes with caveats; user must resolve listed conditions before `release-handoff`. |
-| 3 | `blocked` | Acceptance failed; routing returns to `error-analysis`, `implementation-option-selection`, or `implementation-planning` according to whether the cause, direction, or detailed plan failed. |
-
-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-v2.template.md` Section 7 already encodes this contract — copy that block verbatim and fill in.
-
-### Release-handoff section contract (release-handoff runs only)
-
-When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 5.6 Release Handoff Deliverables` with all eight sub-sections (`5.6.1` Source Verification Report, `5.6.2` Feature Branch & Working-Tree State, `5.6.3` User Selections, `5.6.4` Executed Commands, `5.6.5` Commit List, `5.6.6` Merge Conflict Probe, `5.6.7` Pull Request Outcome, `5.6.8` Routing Recommendation). Every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. H1 choices are `local checkout`, `push + PR`, or `skip`; release-handoff records existing implementation commits and MUST NOT create new commits. If the user picked `skip` (H1) or `cancel` (H3), keep 5.6.3 populated but leave 5.6.4–5.6.6 explicitly empty per the template's empty-state lines.
-
-**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-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)
-
-You (the report-writer worker) MUST write the worker-result pointer at `**Worker Result Path:**`, defaulting to:
-
-```
-runs/<task-type>/worker-results/report-writer-worker-<task-type>-<seq>.md
-```
-
-Its body contains exactly the project-relative data.json path and the convergence-state input path. Analysis-worker result files stay in `## Inputs`; do not copy their list into the pointer. **Enforced:** both dispatch adapters include this pointer in `WorkerJob.completion_paths` and refuse `completed` while it is absent.
-
-The pointer's frontmatter and header follow `team-contract` "Result Frontmatter" and the standard worker-result header sections. Use `workerId: "report-writer"` and copy the remaining canonical values from `analysis-material.md`; do not duplicate the final-report body.
-
-You MUST also write the separate heartbeat/read-confirmation audit file at `**Audit sidecar path:**`, derived from Worker Result Path and defaulting to:
-
-```
-runs/<task-type>/worker-results/report-writer-worker-audit-<task-type>-<seq>.md
-```
-
-The selected report-writer preamble defines that audit shape. **Enforced:** `validators/validate_session_conformance.py` checks its reading confirmation, progress stages, timestamps, and cadence whenever the role completes.
+## Phase 6 → Phase 7 execution sequence (BLOCKING order)
 
-### Main Body Section
+Do not run the seven steps below manually. Invoke `okstra report-finalize`; contract 3.0 runs them in this order:
 
-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.
+1. **`token-usage`** — collect usage into team state without touching the final record.
+2. **`project-activity`** — report assembly validates every owner input and publishes the final record once.
+3. **`check-source`** — verify the assembled English source.
+4. **`render-views`** — render the Markdown reading copy and human HTML.
+5. **`spawn-followups`** — materialize registered follow-up tasks.
+6. **`validate-run`** — validate the record, views, run manifest, and team state.
+7. **`teardown-stages`** — remove eligible stage worktrees after successful validation.
 
-**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`.
+### Before `report-finalize`: the translation sidecar
 
-**Background and Rationale (top-of-report, mandatory — every task-type).** Fill the data.json `rationale` object (rendered as `## Background and Rationale`, right after the Verdict Card). It is the reviewer-facing narrative that answers four questions, in order — write each as **prose**, not a table:
-- `motivation` — why we are doing this work (goal / context).
-- `problem` — why this is a problem (the flaw in the current state).
-- `approach` — what work is therefore needed (the chosen direction).
-- `justification` — why this is a reasonable choice (versus alternatives, with rationale).
+Never dispatch the translator before report assembly and `check-source`. For a non-English human report, first run `report-finalize --only token-usage --only project-activity --only check-source`; the extraction command refuses to build a work list from a non-English source. Then dispatch the translator worker with `okstra agent-prompt materialize --audience translator`, `okstra agent-prompt record-dispatch`, `okstra worker-dispatch --audience translator`, and `okstra agent-prompt link-result`. Resume with `report-finalize --only render-views --only spawn-followups --only validate-run --only teardown-stages`; do not assemble the record a second time.
 
-Every field MUST anchor its claim with at least one evidence reference — a `path:line`, an **in-report** ID (`C-001` / `E-006` / `§5.4`), or another cited source already present in this report. When the evidence is genuinely insufficient, say so explicitly (`insufficient evidence — <reason>`) instead of inventing one. `validators/validate-run.py` → `_validate_rationale_evidence` fails any field carrying neither a citation nor an insufficiency marker, so an ungrounded or fabricated rationale is rejected at validation time.
+## Routing pointer
 
-**Reader-facing prose MUST NOT cite a bare brief/worker-internal ID that this report never surfaces** — `RC-*` (reporter confirmations, defined in the brief), `RF-*` / `F-*` (findings, defined in worker-results) have no anchor in the final report, so a reader hits an opaque token with nothing to click. Either expand it inline (`the confirmed version target 1.27.47→1.27.48`) or, for an audit trail, namespace it (`claude:F-005`). **Enforced:** `_validate_no_opaque_id_references` fails a bare `RC-*` / `RF-*` / non-namespaced `F-*` appearing in `verdictCard` / `finalVerdict` / `rationale` / `clarificationItems[].statement`. (The renderer anchors + links in-report IDs of any digit width, so a surfaced `RC-4`-style id does resolve.) Do NOT restate the Verdict Card or the §5.4 trade-off matrix verbatim — this section is the *why*, in connected prose, that those tables compress.
+`workflow.nextRecommendedPhase` has `phase`, `status`, and `rationale`. The status vocabulary is `ready`, `pending`, `blocked`, and `terminal`.
 
-0. **Clarification Response Carried In** — render this `## 0.` heading ONLY when `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}` is non-empty. Walk every `C-*` row of the prior report's `## 1. Clarification Items` table, reconcile against new evidence, and record the outcome (`resolved` / `obsolete`) with citation before drafting the verdict. When no carry-in path was provided, OMIT the `## 0.` heading entirely — the validator fails an empty Section 0 stub. The lead calls `okstra incremental-scope` exactly once, combining answered-clarification stage impacts (`--impacted`) and changed PREP IDs (`--prep-items`); selected-option, Stage Map, or recommended-approach changes pass both CSVs empty to force full mode. Record that single decision JSON verbatim into `implementationPlanning.incrementalDecision` (`mode`, `reverifyStages`, `carryStages`, `reason`); the renderer emits the `### 0.1 Incremental Re-Verification Scope` audit block from it, and the validator fails an `incremental`-mode run whose Section 0 omits that block. In `incremental` mode this run's `planItems` MUST carry every plan-item id from the re-verified stages forward with its updated verdict; if re-verification concludes a plan item should be REMOVED, that is a signal the answer's blast radius is not local — do not drop it here, tell the lead to abandon incremental and re-route to a FULL re-verification, because the carry merge only adds prior items and would resurrect the removed item's stale verdict. After authoring the current data.json, call `okstra incremental-carry`, passing the decision's `carryStages` CSV to `--carry-stages` and its `reverifyStages` CSV to `--reverify-stages`. A `CarryError` means the stage/PREP ownership contract is unsafe: discard the partial merged output and route the run through full re-verification; never publish a partially merged report.
-1. **Clarification Items** — single unified `C-*` table; column schema (4 columns with the short fields stacked in one record-meta cell), ID convention, and rerun behaviour are owned by `_common-contract.md §Clarification request policy` (SSOT). The deprecated `5.5.9 Open Questions` / `1.1 Additional Material Request` / `1.2 User Confirmation Questions` sub-sections are removed; the validator fails reports that reintroduce them.
-   - **Open `Blocks=approval` rows carry `origin` and `userConfirmation`** (same SSOT). Lead's dispatch prompt MUST state, per intended blocker, which `origin` applies and what Lead did about it — the writer cannot observe either. When Lead instructed the writer to raise an item rather than decide it, that row's `origin` is `lead-directed` no matter how the workers subsequently voted on it: an instruction returning as a consensus is not a finding. Before writing such an instruction, run the confirmation sequence in [okstra-lead-contract](./okstra-lead-contract.md) "User confirmation before an approval blocker" — asking first is usually cheaper than the row.
-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.
-   - **Final-verification added-surface audit.** When `header.taskType` is `final-verification`, populate `finalVerification.addedSurfaceAudit` from the workers' enumeration of what the diff added — one row per identifier / module / configuration entry, each with the callers found across the repository and its disposition. Do not summarise the rows away: this table is the only machine-readable evidence for the over-delivery axis, and requirement coverage answers the opposite question. An `over-delivery` row's `note` MUST cite the `AB-NNN` (no caller) or `CA-NNN` (called, but no requirement) row it became, and that row MUST exist in this report. **Enforced:** `schemas/final-report-v2.0.schema.json` requires the array and rejects an unknown `disposition`; `validators/validate-run.py::_validate_added_surface_audit` enforces the citation and refuses a `traced` row that names no requirement.
-   - **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.
+`phase` is non-empty only for an authored `ready` pointer. `prepare` may lower `ready` to `pending` while retaining `phase` in `scripts/okstra_ctl/render.py::_derive_next_recommended_phase`; readers must use `status` for launchability. When `finalVerification.routingRecommendation.target` is `release-handoff(stage-group)`, write `phase` as `release-handoff`.
 
-```json
-{
-  "candidateDetailBoundary": {
-    "expectedChangeAreas": "direction-level-only",
-    "expectedVerification": "direction-level-signals-only",
-    "forbidden": ["exact-file-lists", "stage-lists", "test-commands"]
-  }
-}
-```
+## Compatibility
 
-   - **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.
-6. **Cross Verification Results** — 4 categories (Full / Partial / Contested / Worker-Unique) when convergence is enabled, per `convergence`. Prepend the Round History sub-table (columns: `Round | inputQueueSize | resolvedCount | carriedForwardCount | dispatches | skippedWorkers`) plus a `round2SkippedReason: <value>` note, pulled verbatim from `convergence-<task-type>-<seq>.json`. Empty contested list renders as `- No items lacking consensus.`. Convergence-disabled runs use the legacy Consensus/Differences format and omit the round table.
-7. **Final Verdict** — `Direction` ∈ `continue-investigation` / `begin-option-selection` / `begin-planning` / `begin-implementation` / `approve` / `reject` / `hold`. **Verdict Token** is `not-applicable` for every task-type except `final-verification` — see "Final-verification verdict token contract" below for that case.
-
-**§5.10 Fix History (data-presence gated).** When the run-manifest carries a `fixCycleId`, fill the data.json `fixCycle` block (`cycle` / `targetReport` / `symptom` / `runs`). Read the values from the task root's `history/fix-cycles.jsonl`: `cycle` MUST equal `fixCycleId`, `targetReport` / `symptom` come from that cycle's `opened` row, and `runs` lists its attached `run` rows (`taskType` / `runSeq` / `runManifest`). The validator (`validators/validate-run.py` → `_validate_fix_cycle`) fails the run when the block is missing or `fixCycle.cycle` does not match `fixCycleId`. When the run-manifest has no `fixCycleId`, OMIT the `fixCycle` block entirely — the renderer omits §5.10.
-
-### Writing Guidelines
-
-- Write in Markdown. **Prefer tables over prose bullet lists** for any section that enumerates multiple items with the same shape (evidence rows, risks, options, dependencies, rollback steps, follow-ups, open questions). Bullets are reserved for short, single-line standalone statements (e.g., "- No additional information requested."). When the template provides a table form, do NOT degrade it back to bullets in the rendered report. **Exception — `## Background and Rationale` (`rationale`) is deliberately prose**: it is connected narrative explaining the *why*, not a same-shape enumeration, so write full sentences there rather than forcing it into a table.
-- **Do not restate the same conclusion verbatim across sections.** The Verdict Card and Reader Summary are *digests*: give the outcome in one or two sentences and point to `## 7. Final Verdict` / `## 5.8.8 Routing Recommendation` for the full reasoning, rather than copying their multi-clause conclusion word-for-word. Only the `Verdict Token` and `Direction` cells must byte-match §7 (per the Verdict Card contract above). `Next Step` must point to the same routing target as §7, but its actionable command and prose need not be byte-identical. The prose conclusion must not be a duplicate.
-- **Keep each sentence to one main idea.** A single sentence that stacks four or five clauses with em-dashes and nested parentheticals (300+ characters) is hard to read, and the renderer can only line-break at sentence ends — so break such reasoning into separate sentences. Facts, evidence, and IDs still live in the tables; prose carries only the connective *why*.
-- **Write the report body in English, whatever the Report Language is.**
-  The data.json is the SSOT every later phase, validator and agent reads,
-  and its full reading copy has the same audience, so both stay
-  in one language. Only the human HTML follows the reader: when
-  **Report Language** is not `en`, Phase 7 dispatches the translator
-  worker, which writes a sidecar the HTML renderer overlays. You never
-  author that sidecar and never write a second language into the data.json.
-  The HTML's own fixed strings — headings, column headers, empty states,
-  enum labels — come from `templates/reports/html/i18n/<lang>.json` and
-  are not yours to write either.
-- If only one worker is usable, perform a reduced-confidence synthesis
-- If evidence is insufficient, explicitly state "I don't know"
-- If expected values are present in `reference-expectations.md`, list matches, gaps, and missing evidence separately
-- If `reference-expectations.md` is explicitly empty, report the absence of expected states as missing information
-- If there are no substantive differences between workers, state "No difference"
-- Write the actual analysis text instead of a meta-description
-- Do not make unfounded assertions
-- Include findings from all four categories. Do not omit "contested" or "worker-unique" findings
-- Include the convergence round history sub-table (Section 6) so the reader can audit which rounds executed and what `round2SkippedReason` indicates (e.g. `"not-skipped"` when Round 2 ran, or one of the three skip reasons). Pull values verbatim from `convergence-<task-type>-<seq>.json`; do NOT recompute.
-- For each finding, include a brief summary of votes per worker across executed rounds. `verification-error` votes are listed as such — never as `DISAGREE`.
-- The report writer worker does not participate in the re-verification vote. It is responsible only for drafting the final report
-
-## Artifact Persistence Checklist
-
-Persistence steps that must be performed in Phase 7:
-
-- [ ] 1. **Draft report record**: Save to `runs/<task-type>/reports/final-report-<task-type>-<seq>.data.json`
-- [ ] 2. **Update team state**: Update `runs/<task-type>/state/team-state-<task-type>-<seq>.json`
-   - Final status, start/end times, and result file paths for each worker
-   - Overall run status
-- [ ] 3. **Update run manifest**: Update `runs/<task-type>/manifests/run-manifest-<task-type>-<seq>.json`
-- [ ] 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`
-   - 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)
-- [ ] 7. **Save convergence state**: `runs/<task-type>/state/convergence-<task-type>-<seq>.json` (when convergence is enabled)
-- [ ] 8. **Spawn follow-up task stubs**: run `okstra spawn-followups` against the final-report per the canonical spawn rule defined in "Phase 7 follow-up task spawner" above. Do not restate the trigger condition here — that section is the single source of truth. The script is idempotent across reruns.
-- [ ] 9. **Human HTML report** (conditional): `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — produced by the Phase 7 `render-views` step per its generation predicate (≥1 §1 `C-*` clarification row OR an implementation-planning Plan Approval widget target; that step is the single source for the exact condition). Reports matching neither condition legitimately have no html sibling; do not treat its absence as a missing artifact.
-
-### Response after Persistence
-
-Provide a concise report in the Report Language covering the following:
-- Completion status
-- Human report path (`.html`)
-- Report record path (`.data.json`) and one line to render the full reading copy: `okstra render-final-report <task-qualified data.json>`
-- Team-state path
-- Validator results
-- Resume command path
-- Remaining blockers (if any)
+Contract 2.0 reports remain readable. They are never migrated or rewritten by report assembly. New writes use contract 3.0 only.