okstra 0.193.0 → 0.194.0

package/docs/cli.md

@@ -801,7 +801,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 <prepare\|prompt\|validate-prepared> --run-manifest <path> …` | Bind the implementation-planning verification queue to the run manifest. `prepare` extracts the exact queue from `--narrative` and, when `designPreparation.mode` is `no-design-inputs` and the Stage Map has one row, flips `convergence.planBodyVerification.gating` to `false` (stdout `Gating`). `prompt` emits its fixed lossless view, ending with the parser-facing `## Response format` block so the block reaches every verifier with the queue; `validate-prepared` proves the prepared queue still matches the narrative. With `--state <plan-body-verification.json>` the round is a re-verification: `prepare` also carries each queued item's recorded votes and `selfFixNote` into the envelope as `priorRounds`, `prompt` renders them as that item's `**Prior round dissent**` block behind a re-verification preamble, and `validate-prepared` re-derives the carry and rejects an envelope that dropped it. Python resolves the convergence-owned state path, so model callers never choose it. |
 | `okstra plan-items seed --narrative <report-narrative.md> --state <plan-body-verification.json> [--prior-state <previous plan-body-verification.json>]` | Create the convergence-owned `planBodyVerification.planItems[]` rows every verdict lands in, from the same deterministic extraction `extract` uses. The historical v2 form is `--data <data.json>`. Idempotent by id: an existing row keeps its verdicts and carried fields. Reports `seeded` / `existing` counts. `--prior-state` carries the previous **run**'s verdicts into this one: a newly seeded item whose `contentHash` equals that run's `verifiedContentHash` for the same id inherits its `verdicts[]` and is tagged `carriedForwardFromSeq` with the seq read off the prior filename, so round 1 does not re-judge text nobody changed. A matching id alone never carries — `P-*` ids are positional and shift. It requires `--state`, refuses a prior state whose task root differs from the one `--state` lives under (the state file carries no task identity, so its path is the only identity there is), and when it carries anything it rewrites the sibling `plan-items-*.json` `dispatchQueue` the way `incremental-carry` does. Adds `carried` / `carriedForwardFromSeq` to the reported counts. |
-| `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker-id>=<result.md>… --round <N>` | Read each worker's Markdown verdict directly, validate every current `P-*` id, reject duplicate worker submissions, and overwrite that round's stored verdicts. The historical `--verdicts <file>` form remains automation compatibility only. Without `--append` every recorded verdict row of the queued items is replaced; when a row belongs to a round `complete-round` never closed, the command refuses before writing and names the `complete-round --round <M>` to run first. `--discard-open-rounds` replaces anyway — the recovery path when those rounds are being re-applied from their result files in order (the discarded rows are printed). |
+| `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker-id>=<result.md>… --round <N>` | Read each worker's Markdown verdict directly, validate every current `P-*` id, reject duplicate worker submissions, and overwrite that round's stored verdicts. The historical `--verdicts <file>` form remains automation compatibility only. Without `--append` every recorded verdict row of the queued items is replaced; when a row belongs to a round `complete-round` never closed, the command refuses before writing and names the `complete-round --round <M>` to run first. `--discard-open-rounds` replaces anyway — the recovery path when those rounds are being re-applied from their result files in order (the discarded rows are printed); it also restores `dispatchQueue` to the items those result files answer, since the persisted queue belongs to the latest round and an earlier round's verdicts would otherwise be refused as outside it. |
 | `okstra plan-items complete-round --state <plan-body-verification.json> --run-manifest <current-run-manifest.json> --round <N> [--self-fix-note <item-id>=<markdown-file>]… [--self-fix-group <cause-file>=<item-id>[,<item-id>...]]… [--self-fix-stop-reason <all-resolved\|no-progress\|max-rounds-reached>]` | After `plan-verify` succeeds, atomically derive and record the round's per-item votes, gate result, participant counts from the actual assigned roster, immutable completion time, convergence history, and optional self-fix notes/groups read from Markdown files. `--self-fix-group` requires `--self-fix-stop-reason` — there is no default. `--self-fix-stop-reason` alone records a stop for a round that rewrote nothing and leaves `selfFixGroups` / `selfFixRoundsApplied` untouched. Models do not write the state JSON. Stdout also carries `nextDispatch`. |
 | `okstra plan-items next-dispatch --state <plan-body-verification.json> [--run-manifest <path>]` | After `apply-verdicts`, decide whether this round opens a worker batch. `kind: none` — missing-dependency `UNVERIFIABLE` only, no new batch. `kind: worker-correction` — re-prompt only those workers; peers stay idle. `kind: critic-tie` — unsettled analyser 1-1 on a run that rostered a critic, `critic-worker` on those item ids only. `kind: user-decision` — the same 1-1 on a run with no critic rostered: no in-band vote can break it, so open one `okstra approval-decision open` per item (classification `noncritical-dissent`) plus its `## 1. Clarification Items` row and dispatch no further verification for them. `--run-manifest` is what tells the two apart (`invocationAssignments` `critic/*`); without it the answer stays `critic-tie`. A missing path is never environment-unverifiable. |
 | `okstra plan-items correction-prompt --state <plan-body-verification.json> --run-manifest <path> --worker <id>` | Emit the planning-time environment-gap paragraph, then the assigned queue. The environment exception is first. Exits 2 unless `next-dispatch` named that worker as a blanket-UNVERIFIABLE correction target. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.193.0",
+  "version": "0.194.0",
   "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.193.0",
-  "builtAt": "2026-09-09T09:27:49.565Z",
+  "package": "0.194.0",
+  "builtAt": "2026-09-09T10:41:11.699Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -427,7 +427,7 @@ round before any host or provider process starts.
    - **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).
    - **Classify each cause group before instructing it (BLOCKING).** A group is either an *authoring* defect — the plan says something wrong, incomplete, or self-contradictory, which self-fix owns — or a *citation* defect, where the plan points at an analysis artifact incorrectly. Only the first is self-fix work. For the second the finding already exists and already went through convergence, so the fix is to re-cite the converged artifact; instructing report-writer to re-derive the fact means the author reads the source material and produces a **finding that never went through convergence**, which the plan then carries as if it had. That is the role boundary the lead contract draws ("keep analysis, execution, verification, and report authoring responsibilities distinct; return defects to the role that owns them"), and report-writer is authoring-only by its own contract. `P-Req-*` items with breakage kind `f` are where this goes wrong most often: the question is usually whether a coverage row points correctly at something already measured, not whether the measurement is right. State the classification in the group's instruction so the author knows which of the two it is being asked to do.
    - **A verdict older than the last self-fix is not a verdict unless the item's content is unchanged (BLOCKING).** A verdict cast in round 1 judged the text before the only automatic rewrite. Once that rewrite runs, a changed item's judgement is about a plan that no longer exists. `--round <N>` on `apply-verdicts` stamps each row and copies `contentHash` onto `verifiedContentHash`. `validators/validate-run.py` `_validate_verdict_rounds_outlive_self_fix` fails an in-scope item whose verdict round is at or before `selfFixRoundsApplied` **and** whose `contentHash` does not match `verifiedContentHash`. Matching hashes keep the prior verdict — that is what avoids a sweep round over unchanged stages. Deferred and observed items are out of the gate and do not need a post-self-fix verdict. **Enforced:** `_validate_verdict_rounds_outlive_self_fix`.
-   - Lead re-runs plan-body verification, then records each worker Markdown result through `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker>=<result.md> --round <N>`. Score the result with `okstra plan-verify --narrative <report-writer-narrative.md> --state <plan-body-verification.json>`, then call `okstra plan-items complete-round --state <plan-body-verification.json> --run-manifest <current-run-manifest.json> --round <N>`. These commands fail on an assigned item the worker left unanswered, on a verdict for an item outside the queue, and on a duplicate worker result. `apply-verdicts` without `--append` replaces every recorded row of the queued items, so it also refuses — before writing — when a row belongs to a round that `complete-round` never closed, naming the round to close first; the votes of a closed round live in `planItems[].rounds`. Skipping `complete-round` between rounds and applying the next one lost 19 items' round-1 votes (2026-09-09). `--discard-open-rounds` is only for re-applying the lost rounds from their result files in order. **Enforced:** `okstra_ctl.plan_items_cli._reject_uncompleted_round_loss`.
+   - Lead re-runs plan-body verification, then records each worker Markdown result through `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker>=<result.md> --round <N>`. Score the result with `okstra plan-verify --narrative <report-writer-narrative.md> --state <plan-body-verification.json>`, then call `okstra plan-items complete-round --state <plan-body-verification.json> --run-manifest <current-run-manifest.json> --round <N>`. These commands fail on an assigned item the worker left unanswered, on a verdict for an item outside the queue, and on a duplicate worker result. `apply-verdicts` without `--append` replaces every recorded row of the queued items, so it also refuses — before writing — when a row belongs to a round that `complete-round` never closed, naming the round to close first; the votes of a closed round live in `planItems[].rounds`. Skipping `complete-round` between rounds and applying the next one lost 19 items' round-1 votes (2026-09-09). `--discard-open-rounds` is only for re-applying the lost rounds from their result files in order: it also restores `dispatchQueue` to the items those result files answer, because the persisted queue is the latest round's and a verdict for an earlier, wider queue is otherwise refused as outside it (round 1 = 26 items, critic tie = 8, round 3 = 19 on that same run — only the 19 survived). Re-apply each lost round with the flag, `complete-round` it, then the next. **Enforced:** `okstra_ctl.plan_items_cli._reject_uncompleted_round_loss` and `_restore_queue_from_results`.
    - For a self-fix, record the correction through the typed convergence command rather than writing `selfFixNote` or `selfFixGroups` JSON. 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 `okstra plan-verify` exits 0 and `okstra plan-items complete-round` succeeds. A round left with a non-zero exit carries its defect into the next round's inputs. Exit 0 with a non-empty `advisories[]` is a complete round: those findings are recorded, not round-blocking (step 5, §"`failures[]` carries only the blocking findings"). Report assembly and rendering occur only after the convergence state is terminal. **Enforced:** `validators/validate-run.py` `_validate_plan_body_state_rounds` requires one stored round per round number and a corresponding item vote.

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -263,7 +263,9 @@ def _parser() -> argparse.ArgumentParser:
         "--discard-open-rounds", action="store_true",
         help="replace even the rows of a round that complete-round never "
              "closed — the recovery path when those rows are being re-applied "
-             "from their result files in order; the discarded rows are listed",
+             "from their result files in order; the discarded rows are listed, "
+             "and dispatchQueue is restored to the items those result files "
+             "answer, since the persisted queue belongs to the latest round",
     )
     complete = commands.add_parser(
         "complete-round",
@@ -1367,6 +1369,9 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
         data["planBodyVerification"] if args.state is not None
         else _planning(data)["planBodyVerification"]
     )
+    discard_open_rounds = bool(getattr(args, "discard_open_rounds", False))
+    if discard_open_rounds and args.state is not None and args.result:
+        _restore_queue_from_results(verification, args.result, recorded)
     queue = verification.get("dispatchQueue") if isinstance(verification, Mapping) else None
     assigned = (
         {item_id for item_id in queue if isinstance(item_id, str)}
@@ -1399,7 +1404,7 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
     if not append:
         _reject_uncompleted_round_loss(
             recorded, rows, data.get("roundHistory"), args.round_number, target,
-            discard_open_rounds=bool(getattr(args, "discard_open_rounds", False)),
+            discard_open_rounds=discard_open_rounds,
         )
     writer = _append_item_verdicts if append else _replace_item_verdicts
     for item in recorded:
@@ -1459,6 +1464,47 @@ def _append_item_verdicts(
     _remember_verified_hash(item)
 
 
+def _restore_queue_from_results(
+    verification: Any,
+    raw_results: list[str],
+    recorded: Sequence[Mapping[str, Any]],
+) -> None:
+    """재적용하는 라운드의 큐를 그 라운드의 결과 파일이 답한 항목 집합으로 되돌린다.
+
+    `dispatchQueue` 는 값이 하나뿐이라 라운드마다 덮인다 — 라운드 1 이 26개,
+    critic 동수 라운드가 8개, 라운드 3 이 19개였던 run 에서 상태에 남는 것은
+    19개뿐이다. `apply-verdicts` 와 `complete-round` 는 둘 다 그 큐로 스코프하고,
+    `_queue_for` 는 이미 두 번 전진한 해시로부터의 순수 계산이라 지난 큐를
+    되살릴 명령이 없었다. 그래서 `--discard-open-rounds` 로 라운드 1 을 다시
+    적용하면 큐 밖 id 라며 거절됐고, 복구는 상태 파일을 손으로 고쳐야만 됐다
+    (실측 2026-09-09, `fontsninja-v3-site` dev-10627 planning 002).
+
+    결과 파일의 `### P-*` 블록 집합이 곧 그 라운드의 큐다 — 워커는 배정된 항목
+    전부에 답해야 통과하고(`_worker_blocks`), 큐 밖 항목에는 답할 수 없었다.
+    순서는 계획 항목 순서를 따른다. 계획에 없는 id 는 큐에 넣지 않으므로 뒤의
+    `_worker_blocks` 가 그 id 를 이름하며 거절한다.
+    """
+    if not isinstance(verification, dict):
+        return
+    answered: set[str] = set()
+    for raw in raw_results:
+        _worker, path = _split_result_arg(raw)
+        try:
+            answered |= set(parse_verdict_blocks(path.read_text(encoding="utf-8")))
+        except (OSError, UnicodeError) as exc:
+            raise PlanItemContractError(f"cannot read result {path}: {exc}") from exc
+    restored = [
+        str(item["id"]) for item in recorded
+        if isinstance(item, Mapping) and item.get("id") in answered
+    ]
+    verification["dispatchQueue"] = restored
+    print(
+        f"apply-verdicts: dispatchQueue restored from the result files "
+        f"({len(restored)} items)",
+        file=sys.stderr,
+    )
+
+
 def _reject_uncompleted_round_loss(
     recorded: Sequence[Mapping[str, Any]],
     rows: Mapping[str, Any],

package/runtime/python/okstra_ctl/session_transcript.py

@@ -5,12 +5,23 @@
 """
 from __future__ import annotations
 
+import os
+import sys
 from datetime import datetime
 from pathlib import Path
 from typing import Callable
 
 OKSTRA = "okstra"
 _SPEAKER_WIDTH = 14
+_RESET = "\x1b[0m"
+_MUTED = "\x1b[90m"
+_LIVE_COLORS = (
+    ("→ ", "\x1b[36m"),
+    ("  ← ok", "\x1b[32m"),
+    ("  ← error", "\x1b[31m"),
+    ("!! PERMISSION DENIED", "\x1b[1;31m"),
+    ("  ← done", "\x1b[33m"),
+)
 
 # 파일 사본이 담는 워커 진행 줄의 상한. 진행은 워커 출력의 부피가 몰리는
 # 자리다 — 파일 하나만 읽는 디스패치도 킬로바이트 단위 도구 에코를 남기고,
@@ -39,6 +50,12 @@ class SessionTranscript:
         path.parent.mkdir(parents=True, exist_ok=True)
         self._file = path.open("w", encoding="utf-8")
         self._live = live
+        self._color = (
+            live
+            and sys.stdout.isatty()
+            and not os.environ.get("NO_COLOR")
+            and os.environ.get("TERM") != "dumb"
+        )
         self._clock = clock
         self._archived = 0
         self._elided = 0
@@ -51,7 +68,7 @@ class SessionTranscript:
         잘린 결론은 사후 분석 전체를 잃는다.
         """
         row = self._row(speaker, line)
-        self._show(row)
+        self._show(row, line)
         self._keep(row, capped=capped)
 
     def write_event(
@@ -67,7 +84,7 @@ class SessionTranscript:
         기록에서는 46KB 를 읽은 호출과 잘린 호출이 같은 줄로 보인다.
         """
         for line in screen:
-            self._show(self._row(speaker, line))
+            self._show(self._row(speaker, line), line)
         for line in archive:
             self._keep(self._row(speaker, line), capped=True)
 
@@ -77,9 +94,22 @@ class SessionTranscript:
         label = f"[{speaker}]".ljust(_SPEAKER_WIDTH)
         return f"{self._clock()} {label}{line}".rstrip()
 
-    def _show(self, row: str) -> None:
+    def _show(self, row: str, line: str) -> None:
         # 화면은 상한과 무관하다. 사람이 보고 있는 것을 잘라 낼 이유가 없다.
         if self._live:
+            if self._color:
+                color = next(
+                    (color for prefix, color in _LIVE_COLORS if line.startswith(prefix)),
+                    "",
+                )
+                if line.lstrip().startswith("… +"):
+                    color = "\x1b[33m"
+                # 시각·화자는 낮은 대비로 두고 본문은 터미널 기본색을 유지한다.
+                prefix_size = len(row) - len(line.rstrip())
+                row = (
+                    f"{_MUTED}{row[:prefix_size]}{_RESET}"
+                    f"{color}{row[prefix_size:]}{_RESET}"
+                )
             print(row, flush=True)
 
     def _keep(self, row: str, *, capped: bool) -> None:

package/runtime/validators/validate-run.py

@@ -6353,7 +6353,12 @@ def _plan_verify_dispatched_results(
         for row in payload.get("workerDispatches") or []:
             if not isinstance(row, dict):
                 continue
-            if not str(row.get("kind") or "").startswith("reverify-r"):
+            # critic 동수 라운드는 `kind: "critic"` 으로 나간다 — 결과 파일명은
+            # 같은 `-plan-verify-r<N>-` 꼴이다. reverify 계열만 세면 동수가 있던
+            # run 마다 critic 표가 "디스패치 기록 없음" 으로 오탐된다(2026-09-09,
+            # fontsninja-v3-site dev-10627 planning 002).
+            kind = str(row.get("kind") or "")
+            if not (kind.startswith("reverify-r") or kind == "critic"):
                 continue
             name = Path(str(row.get("workerResultPath") or "")).name
             if "-plan-verify-r" not in name: