okstra 0.125.1 → 0.125.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.125.1",
+  "version": "0.125.2",
   "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.1",
-  "builtAt": "2026-07-20T08:47:14.936Z",
+  "package": "0.125.2",
+  "builtAt": "2026-07-20T09:08:03.300Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -42,6 +42,7 @@ Plan-body verification is configured under `convergence.planBodyVerification` in
 |---------|---------|-------------|
 | `enabled` | `true` | If `false`, the round is skipped and the top-of-report Approval marker is rendered unconditionally (legacy behaviour). |
 | `maxRounds` | `1` | Upper bound. Plan-body verification is consistency / completeness checking, not fact checking — additional rounds rarely help. Range 1–3. |
+| `selfFixMaxRounds` | `3` | Upper bound on the report-writer self-fix loop (§"Round protocol" step 7). Range 1–5. The loop also stops early on no-progress, so this is a ceiling, not a target. |
 | `gating` | `true` | If `true` (default), `majority-disagree` blocks the Approval marker. If `false`, the round is advisory-only and the marker always renders. |
 
 Default values are emitted into the manifest by `scripts/okstra_ctl/render.py` (`_build_convergence_block`). The ctx knob `OKSTRA_PLAN_VERIFICATION=false` flips `planBodyVerification.enabled` to false.
@@ -126,27 +127,33 @@ Plan-body verification stays **lightweight** even under this posture — the `ve
    - `partial-consensus` — majority `AGREE`, dissenting `DISAGREE` recorded.
    - `dissent-isolated` — only one worker `DISAGREE`s, others `AGREE` — treat as `partial-consensus` for gate purposes; record dissent. (Distinct from finding-convergence `worker-unique`, which means the *opposite*: only one worker AGREEs. Plan-body classifications use this dedicated label to avoid the collision.)
    - `majority-disagree` — a *majority* of analysers `DISAGREE` (majority needs ≥2 participating non-error votes), OR any single-vote-blocking kind fires: one `DISAGREE(a)` / `DISAGREE(d)` on any item, or one `DISAGREE(f)` on a `P-Req-*` item (see §"Single-vote-blocking kinds"). This classification **blocks the Approval marker**.
+   - `needs-reverify` — a single-vote-blocking kind fired but the item has **fewer than 2 participating non-error votes**, i.e. the lone dissent was never cross-verified because its peer returned `verification-error`. A single-vote-blocking kind means "one *confirmed* DISAGREE is enough"; an unconfirmed one is not. This does **not** block the Approval marker — blocking on it would make a worker failure produce a stricter gate than a healthy roster, the same paradox the ≥2-vote majority rule already rules out. The item is re-dispatched in the next round (step 7); if it survives the round budget it is promoted per step 8 with a Statement that says verification never completed. **Enforced:** `validators/validate-run.py` `_classify_plan_item_gate` returns `needs-reverify` for this shape and `_recompute_plan_body_gate` folds it into `passed-with-dissent`.
    - `contested` only meaningful when `maxRounds > 1`; at default `maxRounds=1`, fold any unresolved item into `partial-consensus`.
 5. Gate result resolution:
    - any `majority-disagree` item present AND `gating=true` → `blocked-by-disagreement`
    - all dispatches non-result → `aborted-non-result`
-   - any `partial-consensus` / `dissent-isolated` present, no `majority-disagree` → `passed-with-dissent`
+   - any `partial-consensus` / `dissent-isolated` / `needs-reverify` present, no `majority-disagree` → `passed-with-dissent`
    - all items `full-consensus` → `passed`
 6. Lead writes `runs/<task-type>/state/plan-body-verification-<task-type>-<seq>.json` (schema below) and populates `### 5.5.9 Plan Body Verification` in the final report's data.json (`implementationPlanning.planBodyVerification`, schema `schemas/final-report-v1.0.schema.json`; template at `templates/reports/final-report.template.md`). The §5.5.9 body is **grouped by plan item**: `planItems[]`, each carrying its `id`, its plain-language `subject` (rendered as the item heading), an optional `sourceSection`, an optional `clarificationId` (the `C-<N>` this item blocks on when `majority-disagree`), and a `verdicts[]` list (`worker / verdict / breakageKind / note`) — one verdict row per worker under that item. The renderer prints three fixed legends (gate values, verdict tokens, breakage kinds a–f) so the reader can decode every cell without opening this spec. The older flat `#### Verdict details` table (`Plan item / Worker / …`, one row per plan-item × worker pair) is superseded by the grouped layout — it hid *what* each vote was about behind a bare `P-*` ID; the subject heading is the fix. The validator's `Plan Body Verification` + `Gate result:` substring checks still gate this section.
-7. **Self-fix round (at most once, targeting planner-fixable defects).** After aggregation, if at least one `majority-disagree` item has a majority of its `DISAGREE` verdicts at `fixability == planner-fixable`, lead attempts one self-fix **before** promoting it to the user:
+7. **Self-fix loop (up to `selfFixMaxRounds`, targeting planner-fixable defects).** After aggregation, while at least one `majority-disagree` item has a majority of its `DISAGREE` verdicts at `fixability == planner-fixable`, lead runs self-fix rounds **before** promoting anything to the user:
    - lead instructs report-writer to rewrite only those planner-fixable items for correction (NOT a full draft regeneration — patch only the plan section each `P-*` points to; procedure in [report-writer](./report-writer.md) §"Self-fix rewrite").
    - missing or weak `P-Prep-*` contracts are repaired by adding kind-specific inline detail or an AI-prepared PREP item with a concrete proposal. Facts that require user or external authority remain `blocked` and keep their request material; never invent those facts during self-fix.
-   - lead re-runs plan-body verification once (focused on the corrected items + adjacent items the rewrite touched). After re-verification, overwrite `planItems[].verdicts` with the new verdicts.
+   - lead re-runs plan-body verification (focused on the corrected items + adjacent items the rewrite touched, plus any `needs-reverify` items whose peer failed to vote last round). After re-verification, overwrite `planItems[].verdicts` with the new verdicts.
    - for an item whose `majority-disagree` was resolved by self-fix, record `self-fixed in round <N>: <what was fixed>` in `planItems[].selfFixNote`. A resolved item does not create a clarification.
-   - this round runs **at most once** (infinite-loop cap). If a self-fix round was attempted, record `planBodyVerification.selfFixRoundApplied = true`.
+   - **Loop termination.** Record the round count in `planBodyVerification.selfFixRoundsApplied` and why the loop stopped in `planBodyVerification.selfFixStopReason`:
+     - `all-resolved` — no planner-fixable `majority-disagree` item remains. Exit.
+     - `no-progress` — the round resolved **zero** planner-fixable items relative to the previous round. Exit even with budget left: the same rewrite would repeat. Newly *introduced* defects count against progress, so a rewrite that trades one defect for another stops the loop rather than churning.
+     - `max-rounds-reached` — `selfFixRoundsApplied == selfFixMaxRounds`. Exit.
+     - `not-attempted` — the loop never ran because no item qualified.
+     The `no-progress` and `max-rounds-reached` exits are what make the loop terminate; `selfFixMaxRounds` alone is the backstop.
    - a `majority-disagree` item with a majority of `needs-user-input` is NOT a self-fix target — it goes straight to the next step's clarification promotion.
-8. For every `majority-disagree` item **that remains after the self-fix round** (items not resolved by self-fix, or with a `needs-user-input` majority from the start), lead adds a row to `## 1. Clarification Items` with:
+8. For every `majority-disagree` item **that remains after the self-fix loop** (items not resolved by self-fix, or with a `needs-user-input` majority from the start), lead adds a row to `## 1. Clarification Items` with:
    - new `C-<N>` ID (numbering continues from any existing rows)
    - `Statement` summarising the disagreement and the worker breakage `<kind>`
    - `Kind` chosen per the standard policy (usually `decision` for option-level conflicts, `data-point` for path/symbol mismatches)
    - `Blocks=approval`
    - the item's `planItems[].clarificationId` set to that `C-<N>` (1:1 link). `validators/validate-run.py` `_validate_plan_body_clarification_matching` recomputes each item's class and fails when a majority-disagree item's `clarificationId` is missing, dangling, or points at a non-`approval` row.
-   - a `planner-fixable` item that survives the self-fix round is still promoted, but its `Statement` MUST state "planner self-fix attempted but unresolved" (the cap prevents repeating the rewrite). `validators/validate-run.py` `_validate_self_fix_before_clarification` fails when `selfFixRoundApplied != true` yet a planner-fixable majority item is promoted.
+   - a `planner-fixable` item that survives the self-fix loop is still promoted, but its `Statement` MUST state "planner self-fix attempted but unresolved" and name the stop reason. `validators/validate-run.py` `_validate_self_fix_before_clarification` fails when a planner-fixable majority item is promoted while the budget is not exhausted — it requires `selfFixRoundsApplied >= 1` **and** `selfFixStopReason` in `{no-progress, max-rounds-reached}`, so neither `all-resolved` nor `not-attempted` can excuse a promotion.
 9. The top-of-report `- [ ] Approved` marker line is rendered if and only if the Gate result is `passed` or `passed-with-dissent`. `validators/validate-run.py` `validate_phase_boundary` enforces this correspondence; manually adding the marker line when the gate did not pass is a contract violation.
 
 ## `plan-body-verification-<task-type>-<seq>.json` schema
@@ -160,7 +167,8 @@ Plan-body verification stays **lightweight** even under this posture — the `ve
   "gating": true,
   "verificationMode": "lightweight",
   "gateResult": "passed | passed-with-dissent | blocked-by-disagreement | aborted-non-result",
-  "selfFixRoundApplied": false,
+  "selfFixRoundsApplied": 0,
+  "selfFixStopReason": "not-attempted | all-resolved | no-progress | max-rounds-reached",
   "planItems": [
     {
       "id": "P-Opt-1",
@@ -193,7 +201,7 @@ Plan-body verification stays **lightweight** even under this posture — the `ve
 
 `planItems[].votes.<worker>` is the verbatim verdict token emitted by the worker — `AGREE | DISAGREE(<a|b|c|d|e|f>) | SUPPLEMENT` — or `verification-error` for terminal non-result dispatches. The `DISAGREE` token retains its `<kind>` suffix so the breakage class is recoverable from the state file alone.
 
-`planBodyVerification.selfFixRoundApplied` (bool, default false): whether a self-fix round was attempted at least once. `planItems[].verdicts[].fixability` is each `DISAGREE`'s `planner-fixable | needs-user-input` judgement, recorded in the final data.json (`§5.5.9`).
+`planBodyVerification.selfFixRoundsApplied` (int, default 0): how many self-fix rounds actually ran. `planBodyVerification.selfFixStopReason` (enum, default `not-attempted`): why the loop exited — see §"Round protocol" step 7. `planItems[].verdicts[].fixability` is each `DISAGREE`'s `planner-fixable | needs-user-input` judgement, recorded in the final data.json (`§5.5.9`).
 
 ## Plan-body reverify prompt
 

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

@@ -235,7 +235,9 @@ When lead instructs a self-fix round (passing the target `P-*` list + the reason
 - 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.
 
-After correcting, leave `self-fixed in round <N>: <what was fixed>` in that `planItems[].selfFixNote` and mark `planBodyVerification.selfFixRoundApplied = true`. `needs-user-input` items are NEVER a correction target — they are promoted to clarification as-is.
+After correcting, leave `self-fixed in round <N>: <what was fixed>` in that `planItems[].selfFixNote` and set `planBodyVerification.selfFixRoundsApplied` to the number of rounds run so far. `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)
 

package/runtime/python/okstra_ctl/render.py

@@ -1160,6 +1160,8 @@ def _build_convergence_block(ctx: dict) -> dict:
       False otherwise
     - `planBodyVerification` is implementation-planning specific; the key is
       always emitted (dead-letter on other phases) so the schema stays stable.
+      Its `selfFixMaxRounds` default 3 bounds the report-writer self-fix loop
+      that runs before a planner-fixable defect is promoted to the user.
 
     ctx knobs honoured:
     - `OKSTRA_PLAN_VERIFICATION`: "true" | "false" | "" (empty → default True).
@@ -1199,6 +1201,7 @@ def _build_convergence_block(ctx: dict) -> dict:
         "planBodyVerification": {
             "enabled": plan_verify_enabled,
             "maxRounds": 1,
+            "selfFixMaxRounds": 3,
             "gating": True,
         },
     }

package/runtime/schemas/final-report-v1.0.schema.json

@@ -1844,7 +1844,15 @@
             "aborted-non-result"
           ]
         },
-        "selfFixRoundApplied": { "type": "boolean" },
+        "selfFixRoundsApplied": { "type": "integer", "minimum": 0 },
+        "selfFixStopReason": {
+          "enum": [
+            "not-attempted",
+            "all-resolved",
+            "no-progress",
+            "max-rounds-reached"
+          ]
+        },
         "planItems": {
           "type": "array",
           "items": {

package/runtime/templates/reports/final-report.template.md

@@ -262,10 +262,10 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 
 ### Validation Checklist{% if t("sectionAside.validationChecklist") != "Validation Checklist" %} ({{ t("sectionAside.validationChecklist") }}){% endif %}
 
-| ID | Phase | Ticket ID | Check | Command / Observation | Expected outcome |
-|----|-------|-----------|-------|------------------------|-------------------|
+| {{ t("columns.recordMeta") }} | Check | Command / Observation | Expected outcome |
+|--------|-------|------------------------|-------------------|
 {% for row in implementationPlanning.validationChecklist -%}
-| {{ row.id | mdcell }} | {{ row.phase | mdcell }} | `{{ row.ticketId | mdcell }}` | {{ row.check | mdcell }} | `{{ row.commandOrObservation | mdcell }}` | {{ row.expectedOutcome | mdcell }} |
+| **{{ row.id | mdcell }}**<br>Ticket: `{{ row.ticketId | mdcell }}`<br>Phase: {{ row.phase | mdcell }} | {{ row.check | mdcell }} | `{{ row.commandOrObservation | mdcell }}` | {{ row.expectedOutcome | mdcell }} |
 {% endfor %}
 
 ### Rollback Strategy{% if t("sectionAside.rollbackStrategy") != "Rollback Strategy" %} ({{ t("sectionAside.rollbackStrategy") }}){% endif %}

package/runtime/validators/validate-run.py

@@ -1800,8 +1800,8 @@ _SINGLE_VOTE_BLOCKING_KINDS = {"a", "d"}
 def _classify_plan_item_gate(item: dict) -> str:
     """Recompute one plan item's gate class from its per-worker verdicts,
     per `prompts/lead/plan-body-verification.md` "Round protocol". Returns one of
-    ``majority-disagree`` / ``has-dissent`` / ``full-consensus`` /
-    ``all-non-result``. Collapses ``partial-consensus`` and
+    ``majority-disagree`` / ``needs-reverify`` / ``has-dissent`` /
+    ``full-consensus`` / ``all-non-result``. Collapses ``partial-consensus`` and
     ``dissent-isolated`` into ``has-dissent`` because they resolve to the
     same gate value; only the majority-disagree boundary changes the gate.
     """
@@ -1827,6 +1827,13 @@ def _classify_plan_item_gate(item: dict) -> str:
     # `a`/`d` for any item; `f` only for P-Req items (requirement coverage).
     is_req = str(item.get("id") or "").upper().startswith("P-REQ")
     if disagree_kinds & _SINGLE_VOTE_BLOCKING_KINDS or (is_req and "f" in disagree_kinds):
+        # "One confirmed DISAGREE" presupposes the item was actually
+        # cross-verified. When the peer returned a non-result nothing confirmed
+        # the dissent, so blocking here would reproduce the same
+        # worker-failure-makes-the-gate-stricter paradox the majority branch
+        # below guards against. Route it to a re-verify round instead.
+        if len(non_error) < 2:
+            return "needs-reverify"
         return "majority-disagree"
     # Otherwise a genuine majority is required — and a majority needs at least
     # two participating votes, so a lone surviving DISAGREE (its peer returned a
@@ -1852,7 +1859,7 @@ def _recompute_plan_body_gate(pbv: dict) -> str | None:
         return "aborted-non-result"
     if any(c == "majority-disagree" for c in classes):
         return "blocked-by-disagreement"
-    if any(c == "has-dissent" for c in classes):
+    if any(c in ("has-dissent", "needs-reverify") for c in classes):
         return "passed-with-dissent"
     return "passed"
 
@@ -2402,8 +2409,14 @@ def _validate_plan_body_clarification_matching(data: dict, failures: list[str])
             )
 
 
+# Stop reasons that justify promoting a still-broken planner-fixable item to the
+# user: the self-fix budget ran out, or a round produced no net resolution so
+# further rounds would repeat themselves.
+_SELF_FIX_EXHAUSTED_REASONS = frozenset({"max-rounds-reached", "no-progress"})
+
+
 def _validate_self_fix_before_clarification(data: dict, failures: list[str]) -> None:
-    """A planner-fixable defect MUST pass through a self-fix round before it is
+    """A planner-fixable defect MUST exhaust the self-fix budget before it is
     promoted to a `## 1. Clarification Items` row. Closes the hole where the
     lead dumps a fixable plan defect (abbreviated path, prose command,
     placeholder, coverage remap) onto the user instead of having report-writer
@@ -2418,7 +2431,14 @@ def _validate_self_fix_before_clarification(data: dict, failures: list[str]) ->
     round_count = pbv.get("roundCount")
     if not isinstance(round_count, int) or round_count < 1:
         return
-    if pbv.get("selfFixRoundApplied") is True:
+    rounds_applied = pbv.get("selfFixRoundsApplied")
+    stop_reason = pbv.get("selfFixStopReason")
+    budget_exhausted = (
+        isinstance(rounds_applied, int)
+        and rounds_applied >= 1
+        and stop_reason in _SELF_FIX_EXHAUSTED_REASONS
+    )
+    if budget_exhausted:
         return
     for item in pbv.get("planItems") or []:
         if not isinstance(item, dict):
@@ -2431,12 +2451,16 @@ def _validate_self_fix_before_clarification(data: dict, failures: list[str]) ->
         ]
         fixable = [v for v in disagrees if v.get("fixability") == "planner-fixable"]
         if disagrees and len(fixable) * 2 > len(disagrees):
+            allowed = " / ".join(sorted(_SELF_FIX_EXHAUSTED_REASONS))
             failures.append(
                 "final-report data.json: plan item "
                 f"`{item.get('id') or '<unknown>'}` is majority-disagree with a "
-                "planner-fixable majority but `selfFixRoundApplied` is not true. A "
-                "planner-fixable defect MUST be corrected by a report-writer self-fix "
-                "round before it becomes a clarification row "
+                f"planner-fixable majority but the self-fix budget is not "
+                f"exhausted (`selfFixRoundsApplied`={rounds_applied!r}, "
+                f"`selfFixStopReason`={stop_reason!r}; need >=1 rounds and a stop "
+                f"reason of {allowed}). A planner-fixable defect MUST be corrected "
+                "by report-writer self-fix rounds until the budget runs out or a "
+                "round makes no progress, before it becomes a clarification row "
                 "(plan-body-verification.md Self-fix round)."
             )