okstra 0.170.0 → 0.170.1

package/docs/cli.md

@@ -756,7 +756,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra plan-items derivations --data <data.json> --response <user-response sidecar> [--clarification C-NNN]` | List the plan statements an answered clarification may have falsified. Extracts the symbols, paths, and ids the answer names (backticked spans plus `R-001` / `DEV-10174`-style ids) and reports every string in the plan body that mentions one, as a JSON pointer plus excerpt. Advisory: it says where a decision's subject is mentioned, never which mentions are now wrong — the supersession rule (`prompts/profiles/_common-contract.md`) requires the author to enumerate before editing, and this supplies the enumeration |
 | `okstra plan-items seed --data <data.json>` | Create the `implementationPlanning.planBodyVerification.planItems[]` row every verdict lands in, from the same deterministic extraction `extract` uses. `apply-verdicts` refuses a verdict whose item has no row, and the report writer leaves the array empty, so this is the step between them. Idempotent by id: an existing row keeps its verdicts and carried fields, so it is safe to re-run between rounds. Reports `seeded` / `existing` counts |
 | `okstra plan-items collect-verdicts --result <worker-id>=<path>… --items <items.json> --output <verdicts.json>` | Read one plan-verify round's worker responses into a verdicts envelope, using the `### <item-id>` / `**Verdict**` block shape fixed by `prompts/lead/plan-body-verification.md`. Exits 2 on an assigned item the worker left unanswered, a verdict for an item outside the persisted queue, a `DISAGREE` with no breakage kind, or a `DISAGREE` without a fixability value — every failure mode a per-round regex drops silently |
-| `okstra plan-items apply-verdicts --data <data.json> --verdicts <verdicts.json>` | Overwrite `implementationPlanning.planBodyVerification.planItems[].verdicts` with that envelope. Overwrites rather than merges, because the contract records one round at a time and a merged table lets the previous round's votes keep voting. Exits 2 when the report carries no row for an incoming item |
+| `okstra plan-items apply-verdicts --data <data.json> --verdicts <verdicts.json> --round <N>` | Overwrite `implementationPlanning.planBodyVerification.planItems[].verdicts` with that envelope. Overwrites rather than merges, because the contract records one round at a time and a merged table lets the previous round's votes keep voting. Exits 2 when the report carries no row for an incoming item. `--round` stamps the verification round on every written row: a self-fix round rewrites the plan after a verification round, so an item left out of a later round keeps a verdict on text that has changed. `validate-run.py` fails a gate resting on any verdict whose round is at or before `selfFixRoundsApplied`. |
 | `okstra config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | Manage persistent settings such as `pr-template-path` with atomic JSON writes |
 | `okstra memory <add\|list\|search\|show\|archive>` | Manage global conversation memory in `~/.okstra/memory-book`, a user-home store separate from project `.okstra/` and the CLI basis of the `save this in okstra` natural-language skill |
 | `okstra manager <init\|discover-projects\|new\|task>` | Public CLI for grouping cross-project okstra tasks into manager-owned context. `new project`, `new task-group`, and `new task` create manager plans; `task assign`, `task note`, `task sync`, `task status`, and `task run` manage per-project assignments and snapshots. `new project --project-root` accepts only existing directories and performs setup-equivalent registration only if `.okstra/project.json` is absent. Public documentation uses the full `project-id:task-group:task-id` child task key; when child task IDs differ within the same manager task, select the exact child with `--child-task-id`. `task run` does not execute the child lead directly; it returns `prepared` launch metadata/event and a child launch-context packet as JSON |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.170.0",
+  "version": "0.170.1",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.170.0",
-  "builtAt": "2026-08-14T06:32:18.506Z",
+  "package": "0.170.1",
+  "builtAt": "2026-08-14T07:11:14.334Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -243,7 +243,8 @@ round before any host or provider process starts.
    - lead instructs report-writer to rewrite the items in each cause group (NOT a full draft regeneration; 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.
    - **Drop plan items whose element the round deleted.** A self-fix rewrite may remove a plan element (a validation check, a rollback row). `P-*` ids are positional, so a deletion shifts every later row and silently re-points surviving verdicts at their neighbours — and a verdict recorded against a removed element keeps blocking a gate while being unfindable in the plan, so reading the plan never reveals the cause. After each round, re-extract plan items with `okstra plan-items extract` and re-verify any item whose `subject` no longer matches; never carry the old vote forward across a shift. **Enforced:** `validators/validate-run.py` `_validate_verdicts_match_current_subjects` (re-pointing) and `_validate_plan_item_extraction_completeness` (dangling ids).
-   - 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. **The round's verdicts MUST be transcribed into `planBodyVerification.planItems[].verdicts` in the final report's data.json before the gate is declared** — the gate is re-derived from that table, so declaring a gate over an empty one leaves it unauditable. **Enforced:** `_validate_round_recorded_verdicts`. Transcribe with `okstra plan-items collect-verdicts --result <worker>=<path> … --items <plan-items.json> --output <verdicts.json>` then `okstra plan-items apply-verdicts --data <data.json> --verdicts <verdicts.json>`, never with a per-round script: the CLI reads the response shape this section fixes and **fails** on an assigned item the worker left unanswered, on a verdict for an item outside the queue, and on a `DISAGREE` with no breakage kind. A hand-written regex reports none of those — it drops them, and the round is then scored on a table that silently does not match the queue.
+   - **A verdict older than the last self-fix is not a verdict (BLOCKING).** Rounds interleave with rewrites — round 1, self-fix 1, round 2, self-fix 2 — so a verdict cast in round R judged the text as it stood after self-fix R-1. Once self-fix R runs, that judgement is about a plan that no longer exists. `--round <N>` on `apply-verdicts` stamps each row, and `validators/validate-run.py` `_validate_verdict_rounds_outlive_self_fix` fails any non-carried item whose verdict round is at or before `selfFixRoundsApplied`. This is why "adjacent items the rewrite touched" is not sufficient on its own: adjacency is judged from `subject` changes, and the observed failure was items whose own subject never moved while the stage they point at was rewritten under them. On one run the gate read `passed-with-dissent` with zero blockers and a single re-run flipped 3 of 27 items to `majority-disagree`, all correctness-critical. Before declaring the gate, every item still holding a pre-self-fix verdict MUST be re-verified in a round after the last rewrite.
+   - 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. **The round's verdicts MUST be transcribed into `planBodyVerification.planItems[].verdicts` in the final report's data.json before the gate is declared** — the gate is re-derived from that table, so declaring a gate over an empty one leaves it unauditable. **Enforced:** `_validate_round_recorded_verdicts`. Transcribe with `okstra plan-items collect-verdicts --result <worker>=<path> … --items <plan-items.json> --output <verdicts.json>` then `okstra plan-items apply-verdicts --data <data.json> --verdicts <verdicts.json> --round <N>`, never with a per-round script: the CLI reads the response shape this section fixes and **fails** on an assigned item the worker left unanswered, on a verdict for an item outside the queue, and on a `DISAGREE` with no breakage kind. A hand-written regex reports none of those — it drops them, and the round is then scored on a table that silently does not match the queue.
    - 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.
    - **Each round is a worker batch.** Before dispatching round N ≥ 2, reclaim the previous round's completed verifiers exactly as at any other batch boundary ([okstra-lead-contract](./okstra-lead-contract.md) "Run-scoped worker-resource lifecycle") and emit `PROGRESS: phase-batch-cleanup panes=<n>`, then announce the round with `PROGRESS: phase-5.5.9-plan-verify round=<N> items=<count>`. Saying a round will "reuse" the previous verifiers and then dispatching under fresh names leaves every prior round holding its panes — five rounds of that is what exhausts the pane budget and blocks the next dispatch. **Enforced:** `validators/validate_session_conformance.py` `_check_plan_verify_cleanup_checkpoints` requires both lines once the state file records two or more rounds.
    - **Round completion.** A round is complete only after the renderer has run on the corrected data.json, lead has appended the round to the state file per step 6, lead has reconciled instructed groups against applied corrections — every `itemIds` entry either carries a `selfFixNote` or is still recorded as broken — and **`okstra plan-verify --report <report>` exits 0** (step 5). A round left with a non-zero exit carries its defect into the next round's inputs, which is how a mis-scored gate survives a whole self-fix budget. A round that was instructed but never rendered has not happened, and counting it inflates the budget that gates promotion. The state-file append is not optional bookkeeping: the next re-verification overwrites data.json's `planItems[].verdicts`, so a round that never reached `roundHistory[]` leaves no record anywhere of what it blocked on — which is the whole reason this file exists. **Enforced:** `validators/validate-run.py` `_validate_plan_body_state_rounds` requires one `roundHistory[]` entry per round `1..roundCount`, each carrying its own `gateResult` and cited by at least one item's `rounds[]`, and requires the file's `selfFixRoundsApplied` to match the report's.

package/runtime/python/okstra_ctl/agent_invocation.py

@@ -935,7 +935,7 @@ def _publish_or_reuse(
     if metadata_exists and not prompt_exists:
         raise _existing_conflict("metadata exists without prompt")
     if prompt_exists and prompt.read_bytes() != materialized.prompt_bytes:
-        _replace_undispatched(request, materialized)
+        _replace_undispatched(request, materialized, _prompt_difference(prompt, materialized))
         return
     if prompt_exists and metadata_exists:
         if metadata.read_bytes() != materialized.metadata_bytes:
@@ -946,8 +946,37 @@ def _publish_or_reuse(
     _publish_exclusive(metadata, materialized.metadata_bytes)
 
 
+def _prompt_difference(prompt: Path, materialized: _MaterializedInvocation) -> str:
+    """What actually differs between the published prompt and this one.
+
+    "existing prompt differs" alone cannot be acted on: it does not say whether
+    the file on disk is a stale sibling, a partially written artifact, or the
+    same prompt built from an edited instruction file — and the evidence is
+    destroyed by the very republish that unblocks the caller. One real
+    investigation ended undecided for exactly this reason. Digests identify the
+    two bodies, and the first differing line points at the edit.
+    """
+    try:
+        existing = prompt.read_bytes()
+    except OSError as exc:
+        return f"existing prompt is unreadable: {exc}"
+    composed = materialized.prompt_bytes
+    detail = (
+        f"existing {_sha256(existing)}, composed {_sha256(composed)}"
+    )
+    existing_lines = existing.decode("utf-8", errors="replace").splitlines()
+    composed_lines = composed.decode("utf-8", errors="replace").splitlines()
+    for index, (left, right) in enumerate(zip(existing_lines, composed_lines), start=1):
+        if left != right:
+            return f"{detail}, first differing line {index}"
+    shorter = min(len(existing_lines), len(composed_lines))
+    return f"{detail}, identical through line {shorter} then one body continues"
+
+
 def _replace_undispatched(
-    request: AgentInvocationRequest, materialized: _MaterializedInvocation
+    request: AgentInvocationRequest,
+    materialized: _MaterializedInvocation,
+    difference: str,
 ) -> None:
     """Rewrite a prompt this invocation id wrote but no dispatch ever used.
 
@@ -963,7 +992,7 @@ def _replace_undispatched(
     agent — puts the prompt back under the original rule.
     """
     if not request.replace_undispatched:
-        raise _existing_conflict("existing prompt differs")
+        raise _existing_conflict(f"existing prompt differs ({difference})")
     dispatched = _recorded_dispatch_ids(request)
     if dispatched:
         raise _existing_conflict(

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -91,6 +91,11 @@ def _parser() -> argparse.ArgumentParser:
     )
     apply_verdicts.add_argument("--data", type=Path, required=True)
     apply_verdicts.add_argument("--verdicts", type=Path, required=True)
+    apply_verdicts.add_argument(
+        "--round", type=int, required=True, dest="round_number",
+        help="the verification round these verdicts were cast in; stamped on "
+             "every row so a later self-fix can be told from a current judgement",
+    )
     return parser
 
 
@@ -322,11 +327,22 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
             f"gate is re-derived from that table, so a verdict with nowhere to "
             f"land would be scored as if it were never cast"
         )
+    if args.round_number < 1:
+        raise PlanItemContractError("--round must be 1 or greater")
     for item in recorded:
         if isinstance(item, Mapping) and item.get("id") in rows:
             # Overwrite, never merge: the contract records one round at a time,
             # and a merged table lets a previous round's votes keep voting.
-            item["verdicts"] = rows[item["id"]]
+            #
+            # Each row carries the round it was cast in. A self-fix round
+            # rewrites the plan *after* a verification round, so an item left out
+            # of a later round keeps a verdict on text that has since changed —
+            # invisibly, because the gate reads the table without knowing any
+            # row's vintage. Stamping it here is what lets the validator tell a
+            # current judgement from one two rewrites old.
+            item["verdicts"] = [
+                {**row, "round": args.round_number} for row in rows[item["id"]]
+            ]
     write_json_atomic(args.data, data)
     return {"ok": True, "operation": "apply-verdicts", "path": str(args.data)}
 

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

@@ -7746,6 +7746,11 @@
                     },
                     "note": {
                       "type": "string"
+                    },
+                    "round": {
+                      "description": "The plan-body verification round this verdict was cast in. A self-fix round rewrites the plan after a verification round, so a verdict whose round is at or before `selfFixRoundsApplied` judged text that has since changed. Without it there is no way to tell how many rewrites a surviving verdict predates, and a gate can pass on judgements two generations stale.",
+                      "type": "integer",
+                      "minimum": 1
                     }
                   }
                 }

package/runtime/validators/validate-run.py

@@ -5351,6 +5351,76 @@ def _validate_round_recorded_verdicts(data: dict, failures: list[str]) -> None:
     )
 
 
+def _validate_verdict_rounds_outlive_self_fix(
+    data: dict,
+    failures: list[str],
+) -> None:
+    """A verdict must judge the plan the gate is about to pass.
+
+    Rounds interleave with rewrites: round 1, self-fix 1, round 2, self-fix 2 …
+    so a verdict cast in round R judged the text as it stood after self-fix
+    R-1. If any self-fix ran afterwards — `selfFixRoundsApplied >= R` — that
+    text has changed and the verdict is stale by construction. No semantic
+    analysis is needed to know that; the arithmetic settles it.
+
+    The sibling `_validate_verdicts_match_current_subjects` cannot see this. It
+    compares each row's own recorded `subject`, which catches a positional shift
+    but not the case that matters here: an item whose own wording never changed
+    while the stage it points at was rewritten under it. Observed on a real run
+    — the gate read `passed-with-dissent` with zero blockers, and re-running one
+    round flipped 3 of 27 items to `majority-disagree`, all correctness-critical,
+    because their surviving verdicts predated two self-fix rounds.
+
+    Scoped to items this run verified: a `carriedForwardFromSeq` row belongs to
+    the prior run's record and is judged by that run's seq, not this one's
+    rounds.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    pbv = ip.get("planBodyVerification")
+    if not isinstance(pbv, dict):
+        return
+    applied = pbv.get("selfFixRoundsApplied")
+    if not isinstance(applied, int) or applied < 1:
+        # With no rewrite after any round there is nothing a verdict can be
+        # stale against, and an unstamped row is then simply unremarkable.
+        return
+
+    stale: list[str] = []
+    unstamped: list[str] = []
+    for item in pbv.get("planItems") or []:
+        if not isinstance(item, dict) or item.get("carriedForwardFromSeq"):
+            continue
+        item_id = str(item.get("id") or "").strip()
+        for verdict in item.get("verdicts") or []:
+            if not isinstance(verdict, dict):
+                continue
+            round_number = verdict.get("round")
+            if not isinstance(round_number, int) or isinstance(round_number, bool):
+                unstamped.append(item_id)
+            elif round_number <= applied:
+                stale.append(item_id)
+    if unstamped:
+        failures.append(
+            f"final-report data.json: plan item(s) {sorted(set(unstamped))} carry "
+            f"a verdict with no `round`, and {applied} self-fix round(s) rewrote "
+            "the plan. Without the round there is no way to tell whether the "
+            "verdict judged the current text or a version two rewrites old. "
+            "Re-record the round's votes with `okstra plan-items apply-verdicts "
+            "--round <N>`."
+        )
+    if stale:
+        failures.append(
+            f"final-report data.json: plan item(s) {sorted(set(stale))} carry a "
+            f"verdict from a round at or before self-fix round {applied}, so the "
+            "text they judged has since been rewritten. The gate is computed "
+            "from these votes, so passing on them declares a plan verified that "
+            "nobody verified. Re-verify those items in a round after the last "
+            'self-fix (plan-body-verification.md §"Round protocol" step 7).'
+        )
+
+
 def _validate_verdicts_match_current_subjects(
     data: dict,
     failures: list[str],
@@ -6367,6 +6437,7 @@ def validate_plan_body_section(
     _validate_aborted_gate_has_clarification(data, failures)
     _validate_round_recorded_verdicts(data, failures)
     _validate_verdicts_match_current_subjects(data, failures)
+    _validate_verdict_rounds_outlive_self_fix(data, failures)
     _validate_plan_item_extraction_completeness(data, failures)
     _validate_plan_item_subject_substance(data, failures)
     _validate_plan_body_clarification_matching(data, failures)