okstra 0.125.0 → 0.125.2

package/docs/architecture.md

@@ -298,7 +298,7 @@ The standard `okstra` workflow applies the following team contract consistently
 - The main Claude is always the `Claude lead` and operates in synthesis-only mode.
 - The default required worker roles are `Claude worker`, `Codex worker`, and `Report writer worker`. `Antigravity worker` is optional and is included as required only when explicitly named by `--workers` or the profile's `- Workers:` section.
 - `Report writer worker` focuses on report structure and evidence organization, but `Claude lead` remains the final synthesis owner.
-- The default model contract is computed from central defaults. Fallbacks are `Claude lead`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.6-sol`, and `Antigravity worker`=`auto` (when opted in). Without a separate override, `Report writer worker` follows the `Claude lead` model (therefore `opus` by default).
+- The default model contract is computed from central defaults. Fallbacks are `Claude lead`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.6-sol`, `Report writer worker`=`sonnet`, and `Antigravity worker`=`auto` (when opted in). `Report writer worker` no longer inherits the `Claude lead` model — it resolves from its own catalog `ROLE_DEFAULTS` entry because it does not vote in convergence; `--report-writer-model opus` or `OKSTRA_DEFAULT_REPORT_WRITER_MODEL` restores the previous behavior.
 - Because `Antigravity worker` is optional, it is attempted only in runs where it is explicitly included.
 - Before the final judgment, each required role in the current run's worker roster must have either a result or an explicit terminal status (`completed`, `timeout`, `error`, `not-run`).
 - Every attempted worker (`completed`, `timeout`, `error`) must have an assigned worker prompt history file under the current run's `prompts/` directory.

package/docs/cli.md

@@ -383,7 +383,7 @@ The central-default environment variables are:
 Fallback defaults are:
 
 - `Claude lead`: `opus`
-- `Report writer worker`: `opus`
+- `Report writer worker`: `sonnet`
 - `Claude worker`: `opus`
 - `Codex worker`: `gpt-5.6-sol`
 - `Antigravity worker`: `auto`

package/docs/project-structure-overview.md

@@ -54,13 +54,14 @@ okstra/
 │   ├── okstra_vendor/               vendored Jinja2 / MarkupSafe + graphify / networkx (okstra-graphify skill)
 │   ├── lib/okstra/                  Bash helpers for okstra.sh
 │   └── lib/okstra-ctl/              Bash control-center subcommands
-├── skills/                          Claude Code skills (11)
+├── skills/                          Claude Code skills (13); `_fragments/` holds shared marker blocks
 ├── agents/                          lead SKILL.md + worker agent specs
 ├── prompts/                         launch template, phase profiles, wizard prompt JSON
 ├── schemas/                         JSON schema for final-report data.json
 ├── templates/                       report, setup, PR, project-doc templates/assets
 ├── validators/                      run / brief / schedule / view validators
 ├── tools/build.mjs                  source → runtime sync
+├── tools/sync-skill-fragments.mjs   expand shared fragment blocks into skills/*/SKILL.md
 ├── tools/docs_publication/          public-manual publication pipeline (build-time only; not shipped)
 ├── config/docs-publication.json     publication inventory: every tracked Markdown path + classification
 ├── runtime/                         generated install payload; do not edit directly
@@ -220,6 +221,7 @@ Important modules:
 | `run.py` | `prepare_task_bundle()` single authority and CLI parser |
 | `implementation_stage.py` | `implementation` single-stage run orchestration — read the Stage Lifecycle Snapshot → pick an available Stage Map entry → provision an isolated stage worktree → publish the selected stage as run context (extracted from `run.py`) |
 | `stage_targets.py` | Stage readiness/verification policy SSOT — from the Stage Lifecycle Snapshot (`consumers.jsonl` ledger + carry sidecar backfill + active registry reservation) it decides which stage is runnable, which commit it branches from, and what final-verification checks. `order_stage_closure` topologically sorts (Kahn) the dependency closure of the wizard's multi-selected stage set to produce the unattended `chain-stages` chaining order |
+| `stage_fix_carry.py` | fix-run carry derivation for a re-run on an `implementation` stage whose latest final-report data.json carries verifier `FAIL` verdicts — collects the previous report path, previous run HEAD, failed verifiers, carried blocking findings, and a routing recommendation, which `run.py` renders into the analysis profile through the `{{FIX_RUN_CONTEXT}}` token. A first run, or a re-run after `PASS`, yields no carry and renders the token empty |
 | `stage_reconcile.py` | best-effort git reconciliation shared by the stage prepare flow (delegates to `git_reconcile.auto_reconcile`; advisory — failures are only reported to stderr, the dependency gate stays authoritative) |
 | `design_surfaces.py` | deterministic detection of an `implementation-planning` stage's design surface — matches the stage's file-path tokens/suffixes/patterns and action wording via `SurfaceRule` to derive which design input the stage needs among domain contract, DB/table schema, external interface, transaction/consistency, transformation mapping, lifecycle, rollout/observability, and manual user test, plus its evidence (`TriggerEvidence`). An unmappable structure raises `DesignSurfaceError` |
 | `design_prep.py` | fingerprint / materialize / resolve backend for design-preparation requests (CLI: `okstra design-prep <list\|show\|write>`) — computes an assessment fingerprint from the approved planning snapshot's `ASSESSMENT_FIELDS`, idempotently writes an Okstra-owned request under `design-prep-requests/`, and resolves the highest-revision append-only user response under `design-prep-inputs/` whose fingerprint matches as the effective response. Keeps the three authorities (report snapshot / Okstra request / user input) separate and never modifies the report or existing revisions. Sidecar I/O is protected by a directory-fd anchor + flock |
@@ -342,14 +344,16 @@ Optional (v1.0 backward-compatible) top-level keys:
 
 ### 4.10 `skills/`
 
-13 user-facing skills (the only skills `okstra install` copies). The list SSOT is `USER_SKILL_NAMES` in `src/lib/skill-catalog.mjs`; the Claude plugin manifest and the installer both derive from it:
+13 user-facing skills (the only skills `okstra install` copies). The list SSOT is `USER_SKILL_NAMES` in `src/lib/skill-catalog.mjs`; the Claude plugin manifest and the installer both derive from it.
+
+Boilerplate shared by several skills (bash invocation rule, outdated-CLI preflight, python bootstrap note) is kept canonical in `skills/_fragments/*.md` and expanded in place inside each `SKILL.md` between `<!-- BEGIN FRAGMENT: <name> -->` / `<!-- END FRAGMENT: <name> -->` markers by `tools/sync-skill-fragments.mjs` (`--check` fails on drift). Sources stay fully expanded, so `runtime/` and installed copies remain self-contained; the guards are `tests-js/skill-fragments.test.mjs` and `tests/contract/test_prompt_fragment_ownership.py`.
 
 | Skill | User-invocable | Role |
 |---|---:|---|
 | `okstra-brief-gen` | yes | Produce task brief from ticket/doc/link/conversation |
 | `okstra-run` | yes | Start/resume okstra task in current Claude Code session |
 | `okstra-memory` | yes | Store/search/archive global conversation memory under `~/.okstra/memory-book` |
-| `okstra-inspect` | yes | Unified read-side — sub-commands `status` (lifecycle + workStatus), `history` (past runs / re-run / resume), `report` (find final-report), `time` (elapsed-time breakdown), `logs` (wrapper log inventory + cleanup), `cost` (task bundle context/read cost) |
+| `okstra-inspect` | yes | Unified read-side — sub-commands `status` (lifecycle + workStatus), `history` (past runs / re-run / resume), `report` (find final-report), `time` (elapsed-time breakdown), `logs` (wrapper log inventory + cleanup), `cost` (task bundle context/read cost), `errors` (error-log aggregation), `error-zip` (anonymized cross-project error bundle), `recap` (cross-run phase recap). `SKILL.md` is a thin core (preflight + dispatch table + shared rules) and each sub-command body lives in `skills/okstra-inspect/facets/<sub-command>.md`, lazily read only after dispatch resolves; the 1:1 match between dispatch rows and facet files is enforced by `tests/contract/test_okstra_inspect_facets.py` |
 | `okstra-rollup` | yes | Cross-task roll-up — aggregate runs/time/errors across a task-group (or whole project) and synthesize a digest from the report files |
 | `okstra-usage` | yes | Read-only project usage snapshot — aggregate recent run coverage, tokens, known cost, CPU, and wall-clock time by task type (default: 30 days) |
 | `okstra-schedule-gen` | yes | Generate task-group schedule |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.125.0",
+  "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.0",
-  "builtAt": "2026-07-19T16:21:54.855Z",
+  "package": "0.125.2",
+  "builtAt": "2026-07-20T09:08:03.300Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/okstra-antigravity-exec.sh

@@ -254,6 +254,16 @@ mkfifo "$stdout_fifo"
 tee -a "$log_path" < "$stdout_fifo" &
 stdout_tee_pid=$!
 
+# Disable git's fsmonitor for every git command agy runs in this process tree —
+# the main worktree's fsmonitor daemon leaks its IPC socket into task worktrees,
+# so git status/commit here intermittently fail with `fsmonitor_ipc__send_query`
+# errors. GIT_CONFIG_* scopes the override to this process tree without touching
+# the user's repo config. See `okstra-codex-exec.sh` for the full rationale.
+_gc_idx="${GIT_CONFIG_COUNT:-0}"
+export "GIT_CONFIG_KEY_${_gc_idx}=core.fsmonitor"
+export "GIT_CONFIG_VALUE_${_gc_idx}=false"
+export GIT_CONFIG_COUNT="$(( _gc_idx + 1 ))"
+
 agy --print "$(cat "$prompt_path")" --model "$model" "${add_dir_args[@]}" \
   --print-timeout "$PRINT_TIMEOUT" --dangerously-skip-permissions \
   2>> "$log_path" \

package/runtime/bin/okstra-codex-exec.sh

@@ -328,6 +328,18 @@ mkfifo "$stdout_fifo"
 tee -a "$log_path" < "$stdout_fifo" &
 stdout_tee_pid=$!
 
+# Disable git's fsmonitor for every git command codex runs in this process
+# tree. The main worktree's fsmonitor daemon leaks its IPC socket into task
+# worktrees, so git status/commit here intermittently fail with
+# `fsmonitor_ipc__send_query` errors (workers otherwise recover by hand with
+# `git -c core.fsmonitor=false`). Injecting it via GIT_CONFIG_* scopes the
+# override to this process tree without touching the user's repo config, and
+# appends after any GIT_CONFIG_* the caller already set.
+_gc_idx="${GIT_CONFIG_COUNT:-0}"
+export "GIT_CONFIG_KEY_${_gc_idx}=core.fsmonitor"
+export "GIT_CONFIG_VALUE_${_gc_idx}=false"
+export GIT_CONFIG_COUNT="$(( _gc_idx + 1 ))"
+
 codex exec -C "$project_root" ${extra_args[@]+"${extra_args[@]}"} --model "$model" --sandbox workspace-write -c approval_policy=never - \
   < "$prompt_path" \
   2>> "$log_path" \

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/templates/worker-prompt-preamble.md

@@ -43,9 +43,17 @@ Different recipients need different files. Do NOT include `final-report-template
 
 ## Error reporting (all workers)
 
-If any tool call you make (Bash, Read, Edit, MCP, etc.) returns a non-zero exit code, raises an exception, or otherwise fails its intended effect, append a single entry to your worker errors sidecar at the absolute path the lead provided as `**Errors sidecar path:** <abs-path>`.
+Record a tool call only when its failure **blocked the step you intended** — a test you needed to run did not start, a file you needed to read was missing, a config resolved against the wrong tree, an edit was rejected. When that happens, append a single entry to your worker errors sidecar at the absolute path the lead provided as `**Errors sidecar path:** <abs-path>`.
 
-If the sidecar file does not exist, create it with `{"schemaVersion": 1, "errors": []}` then append.
+A non-zero exit code is NOT by itself a failure to record. Many tools use non-zero to report a normal, expected result. Do **NOT** record an entry when:
+
+- a search/probe tool (`rg`, `grep`, `find`, `ls`, `test`, `git check-ignore`) exits non-zero solely because it found **no matches**, and you proceed unaffected;
+- you probe an **optional / expected-absent** path (`graphify-out/`, `.project-docs/`, `.scratch/`, an optional lint config, a review pack) and it is absent — detecting absence was the point of the probe;
+- output was truncated but you re-ran and read the content end-to-end.
+
+The test: if the non-zero exit changed nothing about what you could do next, it is a normal result, not a `tool-failure`. When in doubt about whether a failure blocked you, record it — under-recording a real blocker is worse than one noisy entry. These benign non-zero exits are the single largest source of error-log noise; keeping them out is what makes the log a signal.
+
+If the sidecar file does not exist and you have a real entry to record, create it with `{"schemaVersion": 1, "errors": []}` then append.
 
 ### Entry schema
 
@@ -109,7 +117,13 @@ For the **improvement-discovery phase** specifically, the dispatched prompt MUST
 
 - `**Phase 1.5 Grilling Log:** <absolute-path>` — the lead's Phase 1.5 reflect-back log (`<RUN_DIR>/state/phase-1.5-grilling.md`, written before dispatch). Its `Resolved scope` / `Resolved lenses` blocks are the authoritative scope and lens definition for this run. Read the file at this absolute path; do NOT re-derive it from `<RUN_DIR>`, and do NOT re-interpret the brief's raw `scan-scope` / `priority-lenses`. The presence of this anchor is itself the signal that this is an improvement-discovery run — no separate task-type detection is required.
 
-When a worker reads any project-relative path from the prompt, it MUST resolve it against `Project Root` (e.g. `<Project Root>/<Result Path>`) — never use bare relative paths that depend on cwd.
+### Path anchoring (BLOCKING — the single largest source of worker tool-failures)
+
+Every `.okstra/...` path is anchored at `**Project Root:**`, **never** at your cwd. When your run has a worktree (`**Worktree:**` is present), your cwd is that worktree — and the stage/task worktree does **not** contain the project's `.okstra/` directory. So a bare `Read`/`cat .okstra/tasks/...` from cwd resolves inside the worktree and fails "no such file". This is the same trap whether the path came from the prompt, a manifest field, a prior report's citation, or your own reasoning.
+
+- Resolve any project-relative path (`.okstra/...`, `<Result Path>`, `<Prompt History Path>`, a prior-report `path:line` citation) against `**Project Root:**`: `<Project Root>/.okstra/...`. Never use the bare relative form.
+- Mutating build/test commands still run from the worktree cwd (`cd <Worktree> && ...`) — but reads of okstra artifacts (`.okstra/**`) always go through `<Project Root>`, even while cwd is the worktree.
+- If a `.okstra/...` read fails "no such file / does not exist in the worktree", do not retry the same relative path — re-anchor it to `<Project Root>` and read the absolute path.
 
 ---
 

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)."
             )