okstra 0.125.5 → 0.125.6

package/package.json

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

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.125.5",
-  "builtAt": "2026-07-20T12:43:22.033Z",
+  "package": "0.125.6",
+  "builtAt": "2026-07-20T13:12:23.932Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -87,7 +87,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` / `.direction` / `.nextStep` MUST byte-match `finalVerdict.verdictToken` / `.direction` / `.nextStep` and `recommendedNextSteps[0].text`. The renderer pulls both from the same data structure — duplicating values across `verdictCard` and `finalVerdict` is intentional so the validator can diff them.
+- **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.
 - **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.
 - **§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`.
 - **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.

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

@@ -70,7 +70,7 @@ profile document.
   - the same `final-report.md` file is the canonical artifact carried into the next run; the user appends answers inline before rerunning. The preferred turn-around is `scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>` (opens the latest report in `$EDITOR`, then auto-reruns the same phase with `--clarification-response` carry-in). The lower-level form `--clarification-response <path>` remains available for scripted runs.
   - if a clarification response was carried in for this run, render the conditional `## 0. Clarification Response Carried In From Previous Run` section (the template's `RENDER_IF` guard activates it), walk every `C-*` row of the prior report's `## 1. Clarification Items` table, reconcile each one against new evidence, and update its `Status` to `resolved` or `obsolete` before issuing the next decision/verdict. When no carry-in path was provided, omit the `## 0.` heading entirely — the validator fails reports that emit an empty Section 0 stub (e.g. "No prior clarification response was provided for this run.").
 - Verdict Card (shared — applies to every final-report regardless of profile):
-  - The top-of-report `## Verdict Card` block is mandatory in every final-report. Its `Verdict Token`, `Direction`, and `Next Step` cells MUST byte-match the corresponding cells in `## 7. Final Verdict` and the first item of `## 3. Recommended Next Steps`. The validator treats the card as a non-authoritative index — when card values diverge from the authoritative sections, the run is `contract-violated`.
+  - The top-of-report `## Verdict Card` block is mandatory in every final-report. Its `Verdict Token` and `Direction` cells MUST byte-match the corresponding cells in `## 7. Final Verdict` — the card is a non-authoritative index and divergence makes the run `contract-violated`. **Enforced:** `validators/validate-run.py` `_validate_verdict_card_consistency` (token, on the rendered markdown) and `_validate_verdict_card_fields` (direction, on data.json). The `Next Step` cell points at the SAME action as `## 7. Final Verdict` and the first item of `## 3. Recommended Next Steps`, but is written as the actionable command the reader runs (`/okstra-run task-type=release-handoff`) where §7 states it as prose — it is not a byte copy and is not compared.
 - Cross-worker traceability (shared — applies to every analysis worker output and to the lead's `## 6.` / `## 2.` tables in the final-report):
   - **Worker-side item IDs (free-form but unique within the worker).** Every row item in sections 1–5 (and any optional section 6) of an analysis worker's output MUST carry an item ID that is unique within that one worker's result file. The ID convention is the worker's choice — `F-001` / `F-002` per the suggested schema, `1.1` / `1.2` / `1.3` as Codex tends to use, or any other shape — but it MUST appear as the leading column of the row (for table-form items) or as a `[<ID>]` prefix (for bullet/numbered items). Workers that emit findings without IDs make cross-worker reconciliation impossible.
   - **Lead-side ID assignment + source preservation.** When the lead (or `report-writer-worker`) synthesises `## 6.1 Consensus` / `## 6.2 Differences` / `## 2.1 Primary Evidence` rows from worker outputs, the lead assigns a fresh `C-NNN` / `D-NNN` / `E-NNN` row ID. The `Source items` column (or, where the template still calls it `Supporting workers` / `Workers (position)` / `Source`, that same column) MUST list every contributing worker:item pair (e.g. `claude:F-001, codex:1.1, antigravity:F-3`) so a reviewer can trace the synthesised row back to each worker's original wording without re-reading every worker-results file. Bare worker names without item IDs (e.g. `claude, codex, antigravity`) are deprecated for these tables; the validator does not yet fail on them but the readability pass treats it as a contract violation.

package/runtime/validators/validate-run.py

@@ -1529,6 +1529,32 @@ def _validate_verdict_card_consistency(content: str, failures: list[str]) -> Non
         )
 
 
+def _validate_verdict_card_fields(data: dict, failures: list[str]) -> None:
+    """`verdictCard.direction` must byte-match its authoritative home in §7.
+
+    The markdown check above compares only the Verdict Token, so a Card whose
+    Direction contradicted §7 shipped silently. `nextStep` is deliberately NOT
+    compared: every shipped fixture authors the Card's cell as the actionable
+    command (`/okstra-run task-type=release-handoff`) while §7 states the same
+    action as prose ("Proceed to release-handoff."), so a byte-match rule there
+    would reject the reference reports.
+    """
+    card = data.get("verdictCard")
+    final = data.get("finalVerdict")
+    if not isinstance(card, dict) or not isinstance(final, dict):
+        return
+    card_value = str(card.get("direction") or "").strip()
+    final_value = str(final.get("direction") or "").strip()
+    if not card_value or not final_value or card_value == final_value:
+        return
+    failures.append(
+        f"final-report data.json: verdictCard.direction `{card_value}` does not "
+        f"match finalVerdict.direction `{final_value}` — the Card is a "
+        "non-authoritative index and MUST byte-match §7 "
+        "(_common-contract.md Verdict Card)."
+    )
+
+
 def _load_final_report_data(report_path: Path) -> dict:
     """Best-effort parse of the final-report data.json sibling. Returns {} when
     absent or unparseable — those conditions are already surfaced as failures by
@@ -1596,6 +1622,7 @@ def validate_final_report_data(
 
     _validate_rationale_evidence(data, failures)
     _validate_no_opaque_id_references(data, failures)
+    _validate_verdict_card_fields(data, failures)
     # Phase-agnostic: the coverage critic runs in every finding-producing phase.
     _validate_unverified_critic_gaps_recorded(data, failures)
 
@@ -1907,6 +1934,27 @@ _PLAN_ITEM_SOURCES = (
 )
 
 
+def _plan_item_source_count(planning: dict, field: str) -> int:
+    """Row count for one plan-body deliverable array.
+
+    `stepwiseExecution` has two homes: the top-level array is the legacy flat
+    summary (schema: "Legacy flat summary kept for compatibility only. New
+    reports use stageMap/stages") and is absent from `implementationPlanning.
+    required`, while a current report carries the real steps per stage. Counting
+    only the legacy field made this whole check a no-op for the largest
+    category — a modern plan could drop every `P-Step-*` item and still pass.
+    """
+    rows = [r for r in (planning.get(field) or []) if isinstance(r, dict)]
+    if field != "stepwiseExecution":
+        return len(rows)
+    per_stage = sum(
+        len([s for s in (stage.get("stepwiseExecution") or []) if isinstance(s, dict)])
+        for stage in (planning.get("stages") or [])
+        if isinstance(stage, dict)
+    )
+    return per_stage or len(rows)
+
+
 def _validate_plan_item_extraction_completeness(
     data: dict,
     failures: list[str],
@@ -1934,7 +1982,7 @@ def _validate_plan_item_extraction_completeness(
         if isinstance(it, dict)
     ]
     for field, prefix, label in _PLAN_ITEM_SOURCES:
-        source_count = len([r for r in (ip.get(field) or []) if isinstance(r, dict)])
+        source_count = _plan_item_source_count(ip, field)
         if source_count == 0:
             continue
         extracted = len(
@@ -3041,6 +3089,65 @@ def _validate_forbidden_actions(
     failures.extend(f"forbidden-action: {v}" for v in violations)
 
 
+CLASSIFICATION_COUNT_KEYS = {
+    "full-consensus": "fullConsensus",
+    "partial-consensus": "partialConsensus",
+    "contested": "contested",
+    "worker-unique": "workerUnique",
+}
+
+
+def classification_counts_from_findings(findings) -> dict:
+    """Recompute `finalClassificationCounts` from `findings[].classification`.
+
+    Shared with `tests/contract/test_convergence_state_contract.py` so the
+    invariant has one definition — it used to live only in that test, which
+    meant it was checked against four hand-written fixtures and never against
+    the state a lead actually writes.
+    """
+    counts = {value: 0 for value in CLASSIFICATION_COUNT_KEYS.values()}
+    for finding in findings or []:
+        if not isinstance(finding, dict):
+            continue
+        key = CLASSIFICATION_COUNT_KEYS.get(finding.get("classification"))
+        if key:
+            counts[key] += 1
+    return counts
+
+
+def _validate_convergence_state_counts(run_dir, failures) -> None:
+    """A run's convergence state must agree with its own findings list.
+
+    `finalClassificationCounts` is a lead-authored summary of
+    `findings[].classification`. Nothing recomputed it against the real
+    artifact, so a miscount survived into the report as two different truths
+    (observed on dev-6901 planning 009: declared partial 6 / worker-unique 4
+    against an actual 5 / 5). Downstream readers pick one arbitrarily.
+    """
+    from pathlib import Path as _Path
+
+    state_dir = _Path(run_dir) / "state"
+    if not state_dir.is_dir():
+        return
+    for state_path in sorted(state_dir.glob("convergence-*.json")):
+        try:
+            state = json.loads(state_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            failures.append(f"convergence state {state_path.name} unreadable: {exc}")
+            continue
+        declared = state.get("finalClassificationCounts")
+        if not isinstance(declared, dict):
+            continue
+        actual = classification_counts_from_findings(state.get("findings"))
+        if declared != actual:
+            failures.append(
+                f"convergence state {state_path.name}: finalClassificationCounts "
+                f"{declared} does not match findings[].classification {actual}. "
+                "The counts are a summary of the findings list — a mismatch means "
+                "the run reports two different classifications for the same work."
+            )
+
+
 def _validate_requirements_discovery_fanout(run_dir, failures) -> None:
     """requirements-discovery run 에 fan-out/ 이 있으면 packet+index 를 검증해
     실패를 ``requirements-discovery: `` 접두로 folding 한다. fan-out 이 없으면 no-op.
@@ -3478,6 +3585,8 @@ def main() -> int:
     if task_type == "requirements-discovery":
         run_dir = report_path.parent.parent
         _validate_requirements_discovery_fanout(run_dir, failures)
+    # Phase-agnostic: convergence runs in every finding-producing phase.
+    _validate_convergence_state_counts(report_path.parent.parent, failures)
     validate_report_views(report_path, failures)
 
     validation_status = "passed" if not failures else "failed"