okstra 0.142.0 → 0.143.0

package/docs/project-structure-overview.md

@@ -243,6 +243,7 @@ Important modules:
 | `incremental_carry.py` | carry merge for an incremental re-run — merges the previous run's plan-item verdicts that this run does not re-verify into the current data.json with a `carriedForwardFromSeq` tag. On `schemaVersion` drift it exits non-zero with `CarryError` to force a full fallback. CLI: `okstra incremental-carry` |
 | `build_tools.py` | allowlist SSOT for deciding whether a plan's command cell invokes the project build toolchain (`npm`/`pytest`/`cargo`/`gradle`/… behind transparent leaders like `sudo`/`env`). The planning worktree has no dependencies installed, so `validators/validate-run.py` uses this to warn (advisory) when a toolchain stage declares no install precondition. Intentionally an allowlist, not a denylist, so unknown tokens go undetected rather than firing on `grep`/`sed` in every plan |
 | `stage_citations.py` | shared grammar SSOT for reading the Stage Map stage numbers a prose cell cites (`Stages 1, 2, and 3`, ranges, etc.). One definition serves two readers that must not drift — the coverage check in `validators/validate-run.py` proving every stage traces to a requirement, and `incremental_scope.py`'s back-trace resolving which stages an answered clarification touches |
+| `self_mock_signals.py` | self-mock signal SSOT — language-keyed regexes (`SIGNALS`), the `EXT_TO_LANG` extension map, and `selfmock_path_key` (the one path-normalization the coverage check and the waiver matcher both share). The signals are each ported from a `prompts/coding-preflight/languages/<lang>.md` "Self-mock signals to refuse" bullet with the source `doc_keyword` retained so a drift guard fails when doc and module diverge. Patterns stay deliberately narrow (only the "stub the subject's own method, then assert the stub" shape and reaching into the subject's privates; subject identity is never inferred beyond the literal `sut` token). Both the static detector `validators/detect_self_mock.py` and the drift guard MUST import from here; four documented shapes needing subject identity no regex has are left to the mutation gate |
 | `run_context.py` | Per-task mutex, run context and run-input persistence; `consumers_mutex` helper for atomic `consumers.jsonl` writes |
 | `path_hints.py` | Compact path-hint persistence + legacy context hydration — stores `run-context` / `active-run-context` in the schemaVersion `2.0` `identity` + `pathHints` compact schema, and hydrates the legacy flat path keys (`RUN_MANIFEST_RELATIVE_PATH`, `TEAM_STATE_PATH`, etc.) in memory the moment the host-side reader reads them |
 | `consumers.py` | Append-only `consumers.jsonl` writer + reader — records which `implementation` runs consumed which `implementation-planning` stage |
@@ -378,6 +379,7 @@ Optional (v1.0 backward-compatible) top-level keys:
 | `validate-schedule.py` | Schedule section/order/code validation |
 | `validate-implementation-plan-stages.py` | enforces the Stage Map structure — checks the S1–S8 rules (`## 5.5 Stage Map` + `## 5.5.<i> Stage <i>` sections, ≤ 8 steps per stage, etc.) |
 | `validate_improvement_report.py` | enforces the 11-item contract of the improvement-discovery final-report. Automatically invoked by `validate-run.py` when `task_type == "improvement-discovery"` |
+| `detect_self_mock.py` | static self-mock detector — scans the changed TEST files for SUT-stub signals (patterns imported from the SSOT `scripts/okstra_ctl/self_mock_signals.py`, never redefined here), matching each file as one whole-file string so multi-line signals are caught. Writes a `qa/self-mock[-stage-<N>].json` sidecar and prints `QA-RESULT: PASS|FAIL` as its last line (exit 0 = no hits, exit 1 = at least one hit). The sidecar records `scannedFiles`/`skippedFiles` so the gate can prove every changed test file was actually scanned (a run that skips them cannot pass on empty input). An optional `--waivers <path>` moves hits matching `(file,line,signal)` from `staticDetect.hits` to `staticDetect.waived` (each carrying the user's `reason`/`acknowledgedBy`) and records the file as `waiverSource`. Its verdict feeds the fail-closed `_validate_selfmock` gate in `validate-run.py` (implementation / final-verification): a diff that touches test files with no readable PASS sidecar blocks the run; a `waived` entry missing `reason`/`acknowledgedBy`, or a `waiverSource` that is not the task's own `qa/self-mock-waivers.json`, also blocks |
 | `validate-workflow.sh` | End-to-end fixture workflow validation |
 | `lib/*.sh` | Shared shell validator helpers and fixtures |
 

package/docs/task-process/error-analysis.md

@@ -47,14 +47,17 @@ sequenceDiagram
     Skill->>Wizard: task-type error-analysis selected
     Wizard-->>Skill: workers/base-ref/model args
     Skill->>Run: render-bundle --render-only
+    Run->>Run: canonical brief preflight
     Run->>Run: validate brief/profile
     Run->>Run: resolve worker roster
     Run->>WT: provision/reuse worktree
     Run->>Art: analysis-profile.md includes common contract
-    Run->>Art: task-manifest workflow next=implementation-planning
+    Run->>Art: task-manifest workflow next=validated report route
 ```
 
-The static next phase in `workflow.py` is `implementation-planning`. The actual final report may say more investigation is needed, but in the lifecycle the fix does not go straight ahead; it moves on to planning.
+For canonical briefs, preflight runs before worker resolution, worktree provisioning, or report creation. A brief whose `reporter-confirmations` status is `pending` stops at this point; legacy briefs keep the compatibility path.
+
+The final report records its next phase in `errorAnalysis.routing.nextTaskType`. After report validation passes, workflow metadata persists that route as `nextRecommendedPhase`. The static `error-analysis` → `implementation-planning` mapping is a fallback only when report data is missing, legacy, or not an error-analysis report.
 
 ## 4. lead execution flow
 
@@ -69,7 +72,7 @@ flowchart TD
     Report --> Persist[Phase 7 persist + validate]
 ```
 
-The workers analyze the symptom and evidence independently. The report-writer does not analyze during Phase 4/5 but writes the final report in Phase 6.
+The workers analyze the symptom and evidence independently. In adversarial mode, even a finding reported by multiple workers enters the verification queue instead of receiving automatic consensus. Evidence-backed counter-evidence remains in the finding's round history, so later agreement cannot turn it into full consensus. The report-writer does not analyze during Phase 4/5 but writes the final report in Phase 6.
 
 ## 5. Deliverables and prohibitions
 
@@ -82,13 +85,15 @@ flowchart LR
     Hyp -. forbidden .-> Fix[Code fix in this run]
 ```
 
-The final report must contain the following.
+The expected final-report content is:
 
 - evidence-backed cause analysis
 - uncertainty boundary
 - practical next diagnostic steps
 - if there is blocking uncertainty, `## 1. Clarification Items`, usually `Blocks=next-phase`
 
+For `error-analysis`, the structured `errorAnalysis` object is the source of truth for the verbatim symptom, reproduction status, `EA-NNN` cause candidates and their counter-evidence, the next diagnostic, and routing. Its shape is enforced by `schemas/final-report-v1.0.schema.json` `$defs.ErrorAnalysis`; `validators/validate-run.py::_validate_error_analysis_consistency` enforces the cross-field semantics. A route to `implementation-planning` needs a credible referenced leading cause and `begin-planning`. A route back to `error-analysis` needs the sharp next diagnostic and `continue-investigation`.
+
 What is prohibited is source edit, refactor, fix attempt, implementation design artifact, and running build/migration/deploy. Deferring ambiguity that could be answered from code or logs to a user question is also a defect per the profile.
 
 ## 6. Code reviewed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.142.0",
+  "version": "0.143.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.142.0",
-  "builtAt": "2026-07-31T06:10:23.526Z",
+  "package": "0.143.0",
+  "builtAt": "2026-08-02T11:16:25.811Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/report-writer-worker.md

@@ -95,6 +95,7 @@ Rules (the schema enforces most of these — they are listed here so you know *w
 - `header.reportAuthor` is `"Report writer worker"`; `header.reportOwner` is `"Claude lead"`. Set author to `"Claude lead"` only for `release-handoff` runs (single-lead by design) or a recorded report-writer dispatch failure fallback.
 - **Source items (worker:item) preservation.** Every `consensus[].sourceItems`, `differences[].workersPosition[].itemId`, and `evidence.primary[].sourceItems` entry MUST carry the worker:item-id pair (e.g. `claude:F-001`, `codex:1.1`, `antigravity:F-3`, or `lead:mcp-1` for lead-only evidence). The schema enforces this via the `SourceItem` regex; bare worker-name lists no longer parse.
 - **Verdict Card consistency.** `verdictCard.verdictToken` and `verdictCard.direction` MUST byte-match `finalVerdict.verdictToken` / `.direction`; `validators/validate-run.py` diffs both and fails the run on divergence. `verdictCard.nextStep` names the same action as `finalVerdict.nextStep` and `recommendedNextSteps[0].text` but is written as the actionable command the reader runs (e.g. `/okstra-run task-key=… task-type=release-handoff`) where the other two are prose — it is deliberately not a byte copy. Duplicating the compared values across `verdictCard` and `finalVerdict` is intentional so the validator can diff them.
+- **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. Route `errorAnalysis.routing.nextTaskType=implementation-planning` with `direction=begin-planning`, 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. Phase validation MUST enforce exact target agreement and uniqueness through `validators/validate-run.py::_validate_error_analysis_consistency`; until that check is implemented and executed, those semantics are contract requirements rather than enforced guarantees.
 - **Reader Summary.** Populate `readerSummary` when the schema excerpt exposes it. It is the human-first entrypoint for both Markdown and HTML: one sentence for the decision, one for the human action required, one for blockers, one for audit sections safe to skip on first read, and one runnable recommended command. Do not duplicate raw evidence tables here.
 - **External QA advisory.** A Tier 3 entry requiring `db`, `http`, or
   `external` may be non-PASS without changing approval or final verdict. Render
@@ -103,7 +104,7 @@ Rules (the schema enforces most of these — they are listed here so you know *w
   and add the exact rerun command to `recommendedNextSteps`. Never turn this
   advisory alone into a clarification, Acceptance Blocker, conditional
   acceptance condition, or blocked routing.
-- **§7 phase-continuation row (mandatory for non-terminal task-types).** When `header.taskType` is one of `requirements-discovery` / `implementation-planning` / `error-analysis` / `implementation` / `final-verification`, `followUpTasks` MUST contain at least one row whose `origin` is `phase-continuation`, `suggestedTaskType` equals the next phase (byte-identical to `finalVerdict.nextStep`'s referenced phase), `newTaskId` reuses the current task-id, `autoSpawn` is `"no"`, and `priority` is `"P0"`. For `release-handoff` runs, omit the phase-continuation row. Schema `allOf` clause enforces this via `contains`.
+- **§7 phase-continuation row (mandatory for non-terminal task-types).** When `header.taskType` is one of `requirements-discovery` / `implementation-planning` / `error-analysis` / `implementation` / `final-verification`, `followUpTasks` MUST contain at least one row whose `origin` is `phase-continuation`, `newTaskId` reuses the current task-id, `autoSpawn` is `"no"`, and `priority` is `"P0"`. For `release-handoff` runs, omit the phase-continuation row. The schema `allOf` / `contains` clause enforces row presence, not exact route-target agreement or uniqueness; phase validation must enforce those error-analysis semantics as specified above.
 - **No deprecated sections.** The schema has no `4.5.8 User Approval Request` body field, no `4.5.9 Open Questions`, no `5.1 Additional Material Request`, no `5.2 User Confirmation Questions` — clarifications go under the unified `clarificationItems[]` array.
 - **Optional Section 0.** Include `clarificationCarryIn` ONLY when the lead's prompt provides a non-empty carry-in path. Omit the key entirely otherwise (do NOT set it to `null` or an empty object).
 - **Reading Confirmation** goes at `**Audit sidecar path:**` per the selected report-writer preamble's `Required reading` section — never in the data.json or the main worker-results file.

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

@@ -126,9 +126,9 @@ Read source files lazily:
 
 ### Brief Reporter-Confirmation Precondition (BLOCKING)
 
-After reading `task-brief.md`, extract the frontmatter `reporter-confirmations` field (`complete | partial | pending | skipped`) and apply the shared handling matrix in `prompts/profiles/_common-contract.md` "Brief handoff contract" → "Reporter confirmation precondition" — that block is the single authority on per-value semantics; do not re-derive them here.
+After reading `task-brief.md`, extract the frontmatter `reporter-confirmations` field (`complete | partial | pending | skipped`) when present and apply the shared handling matrix in `prompts/profiles/_common-contract.md` "Brief handoff contract" → "Reporter confirmation precondition" — that block is the single authority on per-value semantics; do not re-derive them here.
 
-Loader-level flow control only: on `pending` (or field missing), emit `REPORTER_CONFIRMATION_PENDING` and STOP — do not invoke `team-contract` or any analyser; the operator must rerun `okstra-brief-gen` Step 6.5 before Phase 2 can start. Every other value proceeds to Step 5 (with the matrix's flags carried forward for the phase profile).
+Loader-level defensive flow control only: on `pending`, emit `REPORTER_CONFIRMATION_PENDING` and STOP — do not invoke `team-contract` or any analyser, and do not write a final report. Regenerate the brief with `okstra-brief-gen` Step 6.5 and prepare a fresh run. A missing field is a legacy brief, not `pending`, and proceeds to Step 5. Current-format missing or invalid values are rejected during preparation, before a fresh run can reach this loader. Every other value proceeds to Step 5 with the matrix's flags carried forward for the phase profile.
 
 ## Step 5: Read Run Manifest and Team State
 

package/runtime/prompts/lead/convergence.md

@@ -85,7 +85,10 @@ Read the worker result files generated in Phase 4/5 and extract individual findi
   - 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`. 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`.
-6. Do not write a queue or classification in this grouped-input artifact. `okstra convergence seed` deterministically marks multi-source groups `full-consensus` and puts only single-source groups in the working queue. Section 6 never enters the grouped input.
+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.
+   Section 6 never enters the grouped input.
 
 ### Round 1-N: Re-verification Loop (queue-pruned)
 
@@ -208,7 +211,7 @@ ELSE:
 
 `contested` remains a **final classification only** (per §"Scope and Terminology"): a disputed finding is carried forward through intermediate rounds and labelled `contested` only at the last executed round. For `requirements-discovery` (`effectiveMaxRounds = 1`) the single round IS the last round, so a split-with-hard-refute finding is labelled `contested` in that one round. The final-classifier block of §"Convergence Algorithm" honours this: its first branch classifies an adversarially carried-forward finding `contested` regardless of the AGREE tally, so the two sections cannot assign the same finding different labels.
 
-Design intent: one `counter-evidence` refute denies a claim consensus (it cannot rise above `contested` however many others AGREE); a lone `burden-not-met` doubt does not sink an otherwise-surviving claim — only a majority of them does. When every non-discoverer refutes (all_others_disagree) the finding is worker-unique regardless of refute basis — only the discoverer still holds it. A SUPPLEMENT/caveat with zero disagrees lands partial-consensus, not full-consensus, because a caveat means the claim does not pass cleanly (unlike the collaborative classifier, where SUPPLEMENT counts as full agreement).
+Design intent: one `counter-evidence` refute denies a claim consensus (it cannot rise above `contested` however many others AGREE); later-round agreement does not erase that refutation history. The only resolution that overrides prior `counter-evidence` is a later round where every non-discoverer non-error worker disagrees, producing `worker-unique`. A lone `burden-not-met` doubt does not sink an otherwise-surviving claim — only a majority of them does. When every non-discoverer refutes (all_others_disagree) the finding is worker-unique regardless of refute basis — only the discoverer still holds it. A SUPPLEMENT/caveat with zero disagrees lands partial-consensus, not full-consensus, because a caveat means the claim does not pass cleanly (unlike the collaborative classifier, where SUPPLEMENT counts as full agreement).
 
 ## Re-verification Dispatch
 

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

@@ -291,7 +291,7 @@ Skipping this file because "the real report is in `reports/`" is wrong. Both fil
 
 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.
 
-**Verdict Card (top-of-report, mandatory).** Render `## Verdict Card` between the report header and the (conditional) Approval block. Its `Verdict Token` / `Direction` / `Next Step` cells MUST byte-match the corresponding cells in `## 7. Final Verdict` and the first item of `## 3. Recommended Next Steps`. Divergence is `contract-violated`.
+**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`.
 
 **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).
@@ -306,18 +306,19 @@ Every field MUST anchor its claim with at least one evidence reference — a `pa
 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.
 2. **Evidence and Detailed Analysis** — primary evidence rows (file path, line, snippet); secondary evidence / alternate interpretations. If `reference-expectations.md` lists explicit expected values, record match/gap per row.
+   - **Error-analysis diagnosis and routing.** When `header.taskType` is `error-analysis`, populate the required `errorAnalysis` object. Copy `errorAnalysis.symptomVerbatim` byte-for-byte from the symptom stated in the brief's `Source Material`; do not paraphrase it. Every `causeCandidates[]` row includes the full `supportingEvidence`, `falsifyingEvidenceChecked`, `confidence`, and `disproveWith` fields. Route `errorAnalysis.routing.nextTaskType=implementation-planning` with `direction=begin-planning`, 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. Phase validation MUST enforce exact target agreement and uniqueness through `validators/validate-run.py::_validate_error_analysis_consistency`; until that check is implemented and executed, those semantics are contract requirements rather than enforced guarantees.
 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-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.
+7. **Final Verdict** — `Direction` ∈ `continue-investigation` / `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` / `Direction` / `Next Step` cells must byte-match §7 (per the Verdict Card contract above); the prose conclusion must not be a duplicate.
+- **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 final report body in the language passed in **Report Language**
   above (`en` or `ko`). The template's fixed labels (section asides,

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

@@ -32,7 +32,9 @@ profile document.
     - `complete` → proceed normally.
     - `partial` → proceed; treat still-unmarked `intent-check:` / `conversion-block:` rows as the `skipped` branch.
     - `skipped` → do NOT silently infer the missing answers. Promote each unmarked `intent-check:` / `conversion-block:` row into this run's `## 1. Clarification Items` as `Kind=decision`. Use `Blocks=approval` in `implementation-planning`, where the row gates the `approved:` frontmatter flip; otherwise use `Blocks=next-phase`. The recommended answer is drawn from the brief's matching content and clearly labelled `reporter direct-confirmation recommended`.
-    - `pending` (or field missing) → ABORT analysis; render the Verdict Card with `Verdict Token = blocked` + `Direction = hold` and write a single `## Reporter Confirmation Required` block (no leading number) summarising which rows are pending. The `## 1. Clarification Items` table carries one row per pending item with `Blocks=approval` in `implementation-planning`, otherwise `Blocks=next-phase`. The operator must rerun `okstra-brief-gen` Step 6.5. Do NOT emit `## 0.` for this case — Section 0 is reserved for clarification-response carry-in only.
+    - Current-format `pending`, missing, or invalid values are rejected during task-bundle preparation, so they never reach a new run. A brief is current-format only when its frontmatter contains the `reporter-confirmations` key; its value, `type`, and `generator` are then validated together.
+    - Defensive upgrade path: if an already-prepared bundle contains `pending`, the context loader emits `REPORTER_CONFIRMATION_PENDING` and stops before worker or report-writer dispatch. It writes no final report. Regenerate the brief with `okstra-brief-gen` Step 6.5 and prepare a fresh run.
+    - A legacy brief with no `reporter-confirmations` field is not reinterpreted as `pending`; it keeps the compatibility path and proceeds without this reporter-confirmation gate.
     `[CONFIRMED <YYYY-MM-DD> → RC-N]` markers on `Open Questions` rows are the per-row signal that the reporter has answered; their answers live verbatim under `## Reporter Confirmations` in the brief.
   - `Source Material` is reporter-verbatim. Do NOT paraphrase, summarize, reorder, or restructure it. Quote it directly when needed.
   - `Related Task Graph` is the structured task-topology handoff. If the section is present and not `_(none)_`, read it before classification, diagnosis, candidate discovery, fan-out, or next-step routing. Preserve the edge direction exactly as written: `From` → `To` is load-bearing for `depends-on`, `blocks`, parent/child, follow-up, and split relations.

package/runtime/prompts/profiles/error-analysis.md

@@ -22,6 +22,10 @@
   - **Graph-aware scope:** a graph edge can explain ordering or duplication, but it is not proof of cause by itself. Cite code/log evidence before claiming an upstream related task caused the current symptom.
   - **Sharp next diagnostic:** end with the single highest-value diagnostic command, log capture, or file inspection that should happen next, plus the expected signal that would confirm or reject the leading cause.
   - **Fix-design boundary:** do not design the implementation fix beyond what is necessary to validate the cause. If the cause is credible, route to `implementation-planning` with the verified evidence; if the cause is still unclear, route to another `error-analysis` run with the next diagnostic.
+- Structured diagnosis and routing contract:
+  - `errorAnalysis` is the source of truth for reproduction status, `EA-NNN` cause candidates, the sharp next diagnostic, and the next route.
+  - A route to `implementation-planning` requires a credible leading cause referenced by `routing.leadingCauseId` and `begin-planning` as the direction. A route back to `error-analysis` requires the sharp next diagnostic and `continue-investigation` as the direction.
+  - Structure is enforced by `schemas/final-report-v1.0.schema.json` `$defs.ErrorAnalysis`. Cross-field diagnosis and route semantics are enforced by `validators/validate-run.py::_validate_error_analysis_consistency`.
 - Primary focus areas:
   - symptom and trigger clarification
   - root-cause candidates
@@ -40,7 +44,7 @@
   - **Codebase-first ambiguity resolution (defect rule)**: any ambiguity about repro, file behavior, or symbol semantics that can be answered by `Read` / `Grep` / log inspection MUST be resolved that way and recorded with file:line (or log-line) evidence. Writing a clarification row for something the codebase or shipped logs already answer is a defect of this phase.
   - **Evidence note required inside `Statement`**: every clarification row includes `Evidence checked: <path:line>` or `Evidence checked: none — <reporter-only reason>` in the `Statement` cell. `none` is allowed ONLY when the row's nature is "only the reporter can answer this" (reporter-side data, business priority, environment they observed). A row with `none` that *could* have been answered by code or logs is a defect.
 - Cross-verification mode:
-  - Phase 5.5 convergence runs in **adversarial mode** for this phase (`convergence.adversarial=true`). Verifiers actively try to refute each root-cause / reproduction claim by directly re-inspecting the cited code, logs, or config; the burden of proof sits on the claim. See `prompts/lead/convergence.md` §"Adversarial Verification Mode". A single evidence-backed refutation prevents a finding from reaching consensus.
+  - Phase 5.5 convergence runs in **adversarial mode** for this phase (`convergence.adversarial=true`). Verifiers actively try to refute each root-cause / reproduction claim by directly re-inspecting the cited code, logs, or config; the burden of proof sits on the claim. See `prompts/lead/convergence.md` §"Adversarial Verification Mode". Multi-source findings enter the adversarial queue rather than becoming automatic consensus. A single evidence-backed refutation prevents a finding from reaching consensus, remains in the round history, and cannot be erased into full consensus by later agreement.
 {{INCLUDE:_coverage-critic.md}}
 - Non-goals:
   - implementation details unless they are necessary to validate the cause

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -20,6 +20,27 @@ BRIEF_SECTIONS = (
     "Task Continuity Notes",
     "Available MCP Servers",
 )
+ERROR_ANALYSIS_BRIEF_SECTIONS = (
+    "Source Material",
+    "Context",
+    "Problem / Symptom",
+    "Desired Outcome",
+    "Expected Behavior",
+    "Preserved Behavior",
+    "Expected Outcome",
+    "External Gates",
+    "Constraints",
+    "Scan Scope",
+    "Priority Lenses",
+    "Related Artifacts",
+    "Related Task Graph",
+    "Open Questions",
+    "Reporter Confirmations",
+    "Augmentation",
+) + BRIEF_SECTIONS
+BRIEF_SECTIONS_BY_TASK_TYPE = {
+    "error-analysis": ERROR_ANALYSIS_BRIEF_SECTIONS,
+}
 PROFILE_SECTIONS = (
     "Primary focus areas",
     "Expected output emphasis",
@@ -30,6 +51,7 @@ WORKER_PROFILE_SECTIONS_BY_TASK_TYPE = {
         "Worker discovery procedure",
     ),
     "error-analysis": (
+        "Brief consumption",
         "Worker diagnosis procedure",
     ),
     "implementation-planning": (
@@ -79,7 +101,7 @@ def build_analysis_packet(
             bool(clarification_response_path),
         )
     )
-    parts.extend(_brief_block(brief_text))
+    parts.extend(_brief_block(task_type, brief_text))
     parts.extend(_profile_block(task_type, profile_text))
     parts.extend(_reference_block(reference_text))
     parts.extend(_fix_history_block(fix_history_text))
@@ -138,12 +160,15 @@ def _intro_block(
     return lines
 
 
-def _brief_block(brief_text: str) -> list[str]:
+def _brief_block(task_type: str, brief_text: str) -> list[str]:
     return [
         "",
         "## Task-Specific Brief Extract",
         "",
-        _extract_sections(brief_text, BRIEF_SECTIONS),
+        _extract_sections(
+            brief_text,
+            BRIEF_SECTIONS_BY_TASK_TYPE.get(task_type, BRIEF_SECTIONS),
+        ),
     ]
 
 

package/runtime/python/okstra_ctl/brief_frontmatter.py

@@ -0,0 +1,56 @@
+"""Shared lightweight parser for brief markdown frontmatter."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Mapping
+
+
+_BRIEF_FRONTMATTER_LINE_RE = re.compile(r"^([a-zA-Z0-9_\-]+)\s*:\s*(.*)$")
+
+
+def read_brief_frontmatter(path: Path) -> dict[str, str]:
+    """Read a brief's YAML-style frontmatter into a flat key-value map.
+
+    Returns ``{}`` if the file is unreadable, has no frontmatter, or the
+    frontmatter is malformed. Comments and quoted values are stripped.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    if not text.startswith("---"):
+        return {}
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}
+    out: dict[str, str] = {}
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        comment_idx = line.find("#")
+        if comment_idx >= 0:
+            line = line[:comment_idx]
+        match = _BRIEF_FRONTMATTER_LINE_RE.match(line.strip())
+        if not match:
+            continue
+        key, value = match.group(1), match.group(2).strip()
+        if (
+            len(value) >= 2
+            and value[0] == value[-1]
+            and value[0] in ("'", '"')
+        ):
+            value = value[1:-1]
+        out[key] = value
+    return out
+
+
+def is_canonical_generated_brief(frontmatter: Mapping[str, str]) -> bool:
+    return (
+        frontmatter.get("type") == "brief"
+        and frontmatter.get("generator") == "okstra-brief-gen"
+    )
+
+
+def has_reporter_confirmation_contract(frontmatter: Mapping[str, str]) -> bool:
+    return "reporter-confirmations" in frontmatter

package/runtime/python/okstra_ctl/convergence_engine.py

@@ -78,7 +78,9 @@ def seed_working_state(grouped_input: Mapping[str, Any]) -> dict[str, Any]:
         state["stopReason"] = "auto-disabled"
         return state
 
-    findings, queue = _parse_groups(source.get("groups"), analysis_workers)
+    findings, queue = _parse_groups(
+        source.get("groups"), analysis_workers, adversarial=config["adversarial"]
+    )
     state["findings"] = findings
     state["queueFindingIds"] = queue
     return state
@@ -206,6 +208,37 @@ def classify_adversarial_round(
     return "partial-consensus"
 
 
+def _round_has_counter_evidence(
+    votes: Mapping[str, Mapping[str, Any]],
+) -> bool:
+    return any(
+        vote.get("verdict") == "disagree"
+        and vote.get("disagreeBasis") == "counter-evidence"
+        for vote in votes.values()
+        if isinstance(vote, Mapping)
+    )
+
+
+def _classify_adversarial_history(
+    rounds: list[Mapping[str, Any]],
+) -> str | None:
+    """Classify adversarial rounds without erasing earlier counter-evidence."""
+    counter_evidence_seen = False
+    for row in rounds:
+        votes = row.get("votes") if isinstance(row, Mapping) else None
+        if not isinstance(votes, Mapping):
+            continue
+        counter_evidence_seen = (
+            counter_evidence_seen or _round_has_counter_evidence(votes)
+        )
+        classification = classify_adversarial_round(votes)
+        if classification == "worker-unique":
+            return classification
+        if classification is not None and not counter_evidence_seen:
+            return classification
+    return None
+
+
 def apply_round_results(
     state: Mapping[str, Any],
     plan: Mapping[str, Any],
@@ -251,7 +284,7 @@ def apply_round_results(
             {"round": expected_plan["round"], "votes": round_votes}
         )
         classification = (
-            classify_adversarial_round(round_votes)
+            _classify_adversarial_history(finding["rounds"])
             if adversarial
             else classify_collaborative_round(round_votes)
         )
@@ -1321,20 +1354,21 @@ def _expected_final_classification(
     rounds = finding.get("rounds")
     if not isinstance(rounds, list) or not rounds:
         return None
+    if adversarial:
+        try:
+            return _classify_adversarial_history(rounds) or "contested"
+        except ConvergenceContractError:
+            return "contested"
     for row in rounds:
         if not isinstance(row, Mapping) or not isinstance(row.get("votes"), Mapping):
             continue
         try:
-            resolved = (
-                classify_adversarial_round(row["votes"])
-                if adversarial
-                else classify_collaborative_round(row["votes"])
-            )
+            resolved = classify_collaborative_round(row["votes"])
         except ConvergenceContractError:
             continue
         if resolved is not None:
             return resolved
-    return "contested" if adversarial else _final_collaborative_classification(finding)
+    return _final_collaborative_classification(finding)
 
 
 def _validate_round_ledger_counts(
@@ -1347,7 +1381,7 @@ def _validate_round_ledger_counts(
         if not isinstance(history_row, Mapping):
             continue
         ledgers = _round_ledgers(findings, round_number)
-        resolved = _resolved_ledger_count(ledgers, adversarial)
+        resolved = _resolved_ledger_count(findings, round_number, adversarial)
         expected = (len(ledgers), resolved, len(ledgers) - resolved)
         actual = (
             history_row.get("inputQueueSize"),
@@ -1381,17 +1415,32 @@ def _round_ledgers(
 
 
 def _resolved_ledger_count(
-    ledgers: list[Mapping[str, Any]],
+    findings: list[Any],
+    round_number: int,
     adversarial: bool,
 ) -> int:
     resolved = 0
-    for row in ledgers:
-        votes = row.get("votes")
+    for finding in findings:
+        rounds = finding.get("rounds") if isinstance(finding, Mapping) else None
+        if not isinstance(rounds, list):
+            continue
+        current_rounds = [
+            row
+            for row in rounds
+            if isinstance(row, Mapping)
+            and isinstance(row.get("round"), int)
+            and row["round"] <= round_number
+        ]
+        current = next(
+            (row for row in current_rounds if row.get("round") == round_number),
+            None,
+        )
+        votes = current.get("votes") if isinstance(current, Mapping) else None
         if not isinstance(votes, Mapping):
             continue
         try:
             classification = (
-                classify_adversarial_round(votes)
+                _classify_adversarial_history(current_rounds)
                 if adversarial
                 else classify_collaborative_round(votes)
             )
@@ -1486,7 +1535,7 @@ def _validate_no_reappearance_after_resolution(
             continue
         try:
             classification = (
-                classify_adversarial_round(votes)
+                _classify_adversarial_history(rounds[: index + 1])
                 if adversarial
                 else classify_collaborative_round(votes)
             )
@@ -1842,6 +1891,8 @@ def _parse_workers(value: Any) -> list[dict[str, str]]:
 def _parse_groups(
     value: Any,
     analysis_workers: list[str],
+    *,
+    adversarial: bool,
 ) -> tuple[list[dict[str, Any]], list[str]]:
     if not isinstance(value, list):
         raise ConvergenceContractError("groups must be an array")
@@ -1855,7 +1906,7 @@ def _parse_groups(
             raise ConvergenceContractError(f"duplicate findingId: {finding_id}")
         seen_ids.add(finding_id)
         finding, source_workers = _parse_group(group, index, analysis_workers)
-        if len(source_workers) >= 2:
+        if len(source_workers) >= 2 and not adversarial:
             finding["classification"] = "full-consensus"
         else:
             queue.append(finding_id)