okstra 0.186.3 → 0.186.4

package/docs/architecture.md

@@ -865,7 +865,7 @@ The manifest-provided `lead-events-*.jsonl` file is the canonical record for str
 
 `activityContractVersion: 1` is an interpretation version for new `implementation-planning` artifacts. A run without that field remains a historical run and does not require activity events or an `agentActivity[]` projection.
 
-The shared `okstra report-finalize` entrypoint reads canonical activity before translation source checking. Under contract v3 its in-process `project-activity` step assembles the report, filtering events by run identity and validating activity ID order before `agentActivity[]` is published. A historical v2 manifest retains the in-place projection path. For a non-English report, the lead runs `token-usage`, `project-activity`, and `check-source` before translator dispatch, then resumes at `render-views` after the translation sidecar exists. Conformance compares the resulting `agentActivity[]` IDs, order, and core fields with the canonical events for every lead host.
+The shared `okstra report-finalize` entrypoint reads canonical activity before translation source checking. Under contract v3 its in-process `project-activity` step assembles the report, filtering events by run identity and validating activity ID order before `agentActivity[]` is published. A schema-invalid composed record is still published so `validate-run` can scan it; the step itself fails. A historical v2 manifest retains the in-place projection path. A failed Phase 7 step does not skip later checks: `validate-run` still runs, and only `teardown-stages` is skipped. For a non-English report, the lead runs `token-usage`, `project-activity`, and `check-source` before translator dispatch, then resumes at `render-views` after the translation sidecar exists. Conformance compares the resulting `agentActivity[]` IDs, order, and core fields with the canonical events for every lead host.
 
 Approval blockers use `open`, `answered`, `resolved`, and `obsolete`. `open` blocks until the user judges. `answered` with `accept-risk` / `select` / `answer` does not block approval or the next phase; the DISAGREE votes stay on the plan item as evidence. A response sidecar with a proceeding disposition unblocks the same way. `request-revision` and `reject` still withhold the next phase.
 

package/docs/cli.md

@@ -862,7 +862,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra approval-decision <open\|resolve\|carry> --ledger <approval-decisions.json> …` | Write the lead-owned clarification and approval ledger. `open` validates classification-specific dispositions and complete option fields, `resolve` requires real `A-NNN` check references, and `carry` keeps prior resolved decisions outside the active clarification list. |
 | `okstra design-snapshot --narrative <report-narrative.md> --output <design-preparation.json>` | Detect implementation-planning design surfaces and write the detector-owned snapshot consumed by final report assembly. |
 | `okstra plan-verify --narrative <report-narrative.md> --state <plan-body-verification.json>` | Recompute the plan-body gate from the convergence-owned state before `data.json` publication. `--report <historical-data.json>` remains the v2 reader. |
-| `okstra report-finalize --project-root <dir> --run-manifest <path> --report <final-report.md>` | Run Phase 7 in the manifest's contract order. Contract v3 collects usage into team state, assembles all single-owner inputs into `data.json` once, then checks, renders, spawns follow-ups, validates, and tears down eligible stage worktrees. Contract v2 retains its historical in-place projection sequence as a read-only compatibility path. Stops at the first non-zero exit except deferred token collection, reports each step, and prints the ordered `--only` recovery tail. This is the shared path for every lead adapter. |
+| `okstra report-finalize --project-root <dir> --run-manifest <path> --report <final-report.md>` | Run Phase 7 in the manifest's contract order. Contract v3 collects usage into team state, assembles all single-owner inputs into `data.json` once, then checks, renders, spawns follow-ups, validates, and tears down eligible stage worktrees. Contract v2 retains its historical in-place projection sequence as a read-only compatibility path. A failed step still runs every later check through `validate-run`; only `teardown-stages` is skipped so a failed run does not reclaim worktrees. Reports each step and prints the ordered `--only` recovery tail from the earliest failure. This is the shared path for every lead adapter. |
 | `okstra render-views <final-report.data.json\|final-report.md>` | The Phase 7 `render-views` step, runnable on its own. Schema v2 data is rendered directly, and schema v3 data uses the same always-generated, task-specific human HTML path. The full reading copy uses `templates/reports/final-report-v2.template.md` and is rendered on demand with `okstra render-final-report`. Passing the Markdown sibling locates the same data.json. Schema v1 and quick reports keep the legacy conditional renderer. The Node wrapper calls `scripts/okstra-render-report-views.py`; `validators/validate-report-views.py` verifies source/schema/template digests, required human fields, form controls, external assets, diagram/table ID parity, and Response ID parity. |
 | `okstra design-prep <list\|show\|write>` | Review AI-prepared implementation design requests, inspect their effective confirmed response, or append a confirmed user/wizard response without editing the planning report |
 | `okstra wizard <init\|step\|render-args\|confirmation\|outcome> --state-file <path>` | Interactive input state machine for okstra-run, implemented by `okstra_ctl.wizard`. Seed a state file with `init`, then repeatedly call `step --answer <val>` to receive the next `Prompt` JSON. `--answer` is **required**; use `--no-submit` to peek at the next prompt without submitting a response. A `pick` with more choices than the host picker can display keeps `kind: "pick"` but adds `presentation: "numbered-text"`; render every option as a numbered Markdown list and submit the user's 1-based number, exact value, or exact label. Invalid, out-of-range, and ambiguous answers re-prompt without dropping choices. `render-args` returns the final `render-bundle` argument map, and `confirmation` returns the user echo block. On a completed wizard, `outcome` returns `renderArgs`, `persistActions`, and `confirmationText` together; project/global release-handoff PR-template persistence appears as `persistActions[].command == "config.set"`. For an `implementation` task type, `stage_pick` follows `approved_plan_pick` and selects the stage before `executor_pick`. The brief step appears only for entry task types—requirements-discovery, error-analysis, improvement-discovery, project-analysis, feature-analysis, and change-impact-analysis. Analysis inputs use `feature_evidence_pick` / `feature_evidence`, `project_evidence_pick` / `project_evidence`, and `analysis_target_pick` / `analysis_target`; a revision-requested report prioritizes its same-task, same-type rerun. Downstream lifecycle phases automatically carry the manifest brief, with a three-option `brief_carry` fallback when none is registered; `release-handoff` has no brief and enters multi-select `handoff_stage_pick` for eligible stage groups or the whole task |

package/docs/project-structure-overview.md

@@ -343,7 +343,7 @@ Important modules:
 | `plan_derivations.py` | the supersession sweep `_common-contract.md` requires an author to do by hand — extracts the symbols, paths, and ids an answered clarification names and reports every plan string that mentions one. Advisory: it locates candidates and never judges which are now false |
 | `scope_provenance.py` | single source of truth for the scope-provenance grammar every phase-emitted requirement must declare, shared by `validators/validate-run.py` and `validators/validate_fanout.py` so the planning report and fan-out packets cannot drift |
 | `worker_artifact_paths.py` | canonical worker artifact path derivation (e.g. `audit_sidecar_rel` inserts `-audit-` after the first `-worker-` token), so dispatch and validation agree on non-canonical-path rejection |
-| `report_finalize.py` | Phase 7 post-report sequence **SSOT** — runs `check-source` → `token-usage` → `render-views` → `spawn-followups` → `validate-run` in that load-bearing order, stops at the first non-zero exit and names the failing step — except `token-usage`, whose failure defers so the later steps still produce their artifacts. Both lead paths converge here: the Codex adapter calls it in-process (`codex_dispatch`), a Claude-led run reaches it through `okstra report-finalize`. Neither reimplements the sequence |
+| `report_finalize.py` | Phase 7 post-report sequence **SSOT** — runs `check-source` → `token-usage` → `render-views` → `spawn-followups` → `validate-run` in that load-bearing order. A non-zero exit still runs every later check through `validate-run` and names the earliest failure; `teardown-stages` is skipped when any earlier step failed. Both lead paths converge here: the Codex adapter calls it in-process (`codex_dispatch`), a Claude-led run reaches it through `okstra report-finalize`. Neither reimplements the sequence |
 | `wrapper_status.py` | worker wrapper status sidecar reader — the host-side reader of the sidecar `worker_runner.py` writes. `is_terminal` is the one question it answers for the dispatch record and the pane reclaim: does `stage` read `exited` |
 | `worker_runner.py` | runs one worker CLI and records what happened — shared by every provider entrypoint. Owns the `selectors` pump over the child's streams, the stream-arrival idle watchdog (`killpg` on breach), the run-wide progress cap on the log copy, and the status sidecar's whole life. A run that dies after launch still closes its sidecar, so `worker_liveness` never reads a dead worker as running |
 | `session_transcript.py` | worker session transcript — one line per event (time, speaker, body) with a run-wide progress-line cap (`LOG_LINE_CAP`, elision notice) so a single-file dispatch's tool echo cannot dominate the project's `.okstra/` bytes; the fixed shape lets a later lead write share the same file |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.186.3",
+  "version": "0.186.4",
   "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.186.3",
-  "builtAt": "2026-08-24T04:42:58.072Z",
+  "package": "0.186.4",
+  "builtAt": "2026-08-24T05:51:42.489Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/report_assembly.py

@@ -464,7 +464,12 @@ def assemble_report(
     project_root: Path, manifest_path: Path, *,
     replace: Callable[[str, str], None] = os.replace,
 ) -> dict[str, Any]:
-    """모든 입력이 유효할 때만 계약 3.0 정본을 한 번 교체한다."""
+    """계약 3.0 정본을 조립해 게시한다.
+
+    입력이 없어 조립 자체가 안 되면 기존 파일을 건드리지 않는다. 조립은
+    됐는데 스키마만 깨진 기록은 게시한 뒤 거부한다. 게시를 건너뛰면
+    `validate-run` 이 이번 런 내용을 보지 못한다.
+    """
     manifest_row = ReportInputPath("run-manifest", "orchestrator", manifest_path)
     manifest = _read_json(manifest_row)
     if not uses_report_contract_v3(manifest):
@@ -490,9 +495,13 @@ def assemble_report(
         raise ReportAssemblyError(tuple(input_issues))
     data = _compose(project_root, manifest_path, manifest, inputs, schema)
     errors = validate(data, schema)
+    value = manifest.get("expectedReportRecordPath")
+    if not isinstance(value, str) or not value:
+        _fail("orchestrator", manifest_path, "expectedReportRecordPath", "required")
+    target = Path(value)
+    target = target if target.is_absolute() else project_root / target
+    _publish(target, data, replace)
     if errors:
-        target = Path(str(manifest.get("expectedReportRecordPath") or "data.json"))
-        target = target if target.is_absolute() else project_root / target
         raise ReportAssemblyError(
             tuple(
                 AssemblyIssue(
@@ -504,10 +513,4 @@ def assemble_report(
                 for error in errors
             )
         )
-    value = manifest.get("expectedReportRecordPath")
-    if not isinstance(value, str) or not value:
-        _fail("orchestrator", manifest_path, "expectedReportRecordPath", "required")
-    target = Path(value)
-    target = target if target.is_absolute() else project_root / target
-    _publish(target, data, replace)
     return data

package/runtime/python/okstra_ctl/report_finalize.py

@@ -7,17 +7,21 @@ read-only compatibility. The order is load-bearing: rendering before assembly
 or usage collection publishes stale derived views, and validating before
 rendering trips the report-views contract.
 
-`token-usage` is the one step whose failure does not stop the sequence, which
-deliberately accepts that first state: its input is the lead session log, so a
-refusal there would otherwise delete every artifact the later steps produce.
-The run does not pass in that state. `validators/validate-run.py` re-collects
-when the recorded usage is all zeros against an `unavailable` session source
-(`_needs_token_autofix`) and refuses the run rather than ship zeroed counts
-(`accuracy-failed`); a legacy v1 report is caught earlier still, by its
-unsubstituted `{{...}}` placeholders, which a v2 report never carries because
-its numeric cells are `null` until this step fills them. Substituting the
-tokens on a later retry then leaves the already-rendered html stale for
-`validators/validate-report-views.py`.
+A non-zero exit no longer stops the sequence before `validate-run`. A schema
+cap used to hide the contract scan: assembly refused, later steps never ran,
+and the lead only saw those failures after a second finalize. Each step still
+records its own exit; `ok` stays False when any step failed. `teardown-stages`
+is the exception — it reclaims worktrees, so a failed prefix skips it.
+
+`token-usage` reads the lead session log (state outside this run). A refusal
+there used to delete every later artifact; it no longer does, because the
+sequence continues. `validators/validate-run.py` re-collects when the recorded
+usage is all zeros against an `unavailable` session source (`_needs_token_autofix`)
+and refuses the run rather than ship zeroed counts (`accuracy-failed`). A
+legacy v1 report is caught earlier still, by its unsubstituted `{{...}}`
+placeholders, which a v2 report never carries because its numeric cells are
+`null` until this step fills them. Substituting the tokens on a later retry
+then leaves the already-rendered html stale for `validators/validate-report-views.py`.
 
 The translation sidecar is NOT one of these steps. `render-views` overlays it,
 so a non-English run dispatches the translator before this sequence starts —
@@ -447,26 +451,14 @@ def run_finalize(
     before_step: Callable[[str], None] | None = None,
     only: Sequence[str] | None = None,
 ) -> dict[str, Any]:
-    """Run the Phase 7 steps in contractual order.
-
-    A non-zero exit stops the sequence, with one exception: ``token-usage``
-    defers. Its input is the lead session log — state outside this run — so a
-    refusal there is not evidence that the artifacts after it are unwritable.
-    The deferred failure becomes the result's ``reason`` when nothing later
-    fails, and yields to any later failure, which is the step that actually
-    blocked the run.
-
-    ``before_step`` fires immediately before each step is spawned, letting an
-    adapter settle state the step will read (the Codex adapter marks the report
-    writer `completed` before `validate-run` inspects team-state).
-
-    ``only`` restricts the run to the named steps, preserving contractual
-    order. The last step (`validate-run`) is the one that usually fails, and
-    re-running the whole sequence to retry it repeats every preceding idempotent
-    step at full token and wall-clock cost.
+    """계약 순서로 Phase 7 을 돌리고, 실패해도 `validate-run` 까지 모은다.
+
+    `before_step` 은 각 단계 프로세스 직전에 호출된다. Codex 어댑터가
+    `validate-run` 앞에 작성기 상태를 `completed` 로 표시하는 자리이다.
+
+    `only` 는 고른 단계만 계약 순서로 남긴다.
     """
     steps: list[dict[str, Any]] = []
-    deferred = ""
     try:
         if ctx.report_contract_version != "3.0":
             write_execution_roles(ctx)
@@ -476,7 +468,9 @@ def run_finalize(
 
     if only:
         selected = set(only)
-        contract_order = V3_STEP_ORDER if ctx.report_contract_version == "3.0" else STEP_ORDER
+        contract_order = (
+            V3_STEP_ORDER if ctx.report_contract_version == "3.0" else STEP_ORDER
+        )
         unknown = sorted(selected - set(contract_order))
         if unknown:
             return {
@@ -486,75 +480,70 @@ def run_finalize(
             }
         commands = [(name, cmd) for name, cmd in commands if name in selected]
 
+    first_failure = ""
     for name, command in commands:
+        # 실패한 시퀀스가 worktree 를 거두면 재작업 대상이 사라진다.
+        if name == STEP_TEARDOWN_STAGES and first_failure:
+            continue
         if before_step is not None:
             before_step(name)
-        if name == STEP_PROJECT_ACTIVITY:
-            try:
-                if ctx.report_contract_version == "3.0":
-                    assembled = assemble_report(ctx.project_root, ctx.manifest_path)
-                    count = len(assembled.get("agentActivity") or [])
-                else:
-                    rows = project_agent_activity(
-                        ctx.project_root,
-                        ctx.manifest_path,
-                        ctx.data_path,
-                    )
-                    count = len(rows)
-            except (ActivityProjectionError, ReportAssemblyError) as exc:
-                result = subprocess.CompletedProcess(
-                    command,
-                    1,
-                    "",
-                    str(exc),
-                )
-            else:
-                result = subprocess.CompletedProcess(
-                    command,
-                    0,
-                    json.dumps({"count": count}),
-                    "",
-                )
-        else:
-            result = None
-        if name == STEP_TEARDOWN_STAGES:
-            result = _teardown_stage_worktrees(ctx, command)
-        if name == STEP_VALIDATE_RUN:
-            try:
-                _link_lead_result_for_validation(ctx)
-            except (DispatchError, OSError, json.JSONDecodeError) as exc:
-                return {
-                    "ok": False,
-                    "reason": f"lead result linkage failed: {exc}",
-                    "steps": steps,
-                }
-        if result is None:
-            result = subprocess.run(
-                command,
-                cwd=ctx.project_root,
-                text=True,
-                capture_output=True,
-            )
+        result = _run_finalize_step(ctx, name, command)
         steps.append(step_payload(name, command, result))
-        if result.returncode != 0:
-            failure = f"{name} failed with exit code {result.returncode}"
-            # Token collection reads the lead session log, which lives outside
-            # this run. One refusal there (`grandTotalTokens=0`) took the whole
-            # run's output with it: html never rendered, follow-ups never
-            # spawned, and `validate-run` then blocked on `report-views:
-            # missing html artifact`. So this step alone defers instead of
-            # stopping the sequence. It hides nothing — the non-zero exit stays
-            # in `steps`, `ok` stays False, and the closing `validate-run`
-            # still refuses the run.
-            if name == STEP_TOKEN_USAGE:
-                deferred = failure
-                continue
-            return {"ok": False, "reason": failure, "steps": steps}
-    if deferred:
-        return {"ok": False, "reason": deferred, "steps": steps}
+        if result.returncode != 0 and not first_failure:
+            first_failure = f"{name} failed with exit code {result.returncode}"
+    if first_failure:
+        return {"ok": False, "reason": first_failure, "steps": steps}
     return {"ok": True, "reason": "", "steps": steps}
 
 
+def _run_finalize_step(
+    ctx: FinalizeContext,
+    name: str,
+    command: Sequence[str],
+) -> subprocess.CompletedProcess[str]:
+    """한 Phase 7 단계를 실행하고 그 단계의 종료 코드만 돌려준다."""
+    if name == STEP_PROJECT_ACTIVITY:
+        return _run_project_activity(ctx, command)
+    if name == STEP_TEARDOWN_STAGES:
+        return _teardown_stage_worktrees(ctx, command)
+    if name == STEP_VALIDATE_RUN:
+        try:
+            _link_lead_result_for_validation(ctx)
+        except (DispatchError, OSError, json.JSONDecodeError) as exc:
+            return subprocess.CompletedProcess(
+                command, 1, "", f"lead result linkage failed: {exc}"
+            )
+    return subprocess.run(
+        command,
+        cwd=ctx.project_root,
+        text=True,
+        capture_output=True,
+    )
+
+
+def _run_project_activity(
+    ctx: FinalizeContext,
+    command: Sequence[str],
+) -> subprocess.CompletedProcess[str]:
+    """계약 3.0 은 조립, 그 외는 활동 투영만 한다."""
+    try:
+        if ctx.report_contract_version == "3.0":
+            assembled = assemble_report(ctx.project_root, ctx.manifest_path)
+            count = len(assembled.get("agentActivity") or [])
+        else:
+            rows = project_agent_activity(
+                ctx.project_root,
+                ctx.manifest_path,
+                ctx.data_path,
+            )
+            count = len(rows)
+    except (ActivityProjectionError, ReportAssemblyError) as exc:
+        return subprocess.CompletedProcess(command, 1, "", str(exc))
+    return subprocess.CompletedProcess(
+        command, 0, json.dumps({"count": count}), ""
+    )
+
+
 def write_execution_roles(ctx: FinalizeContext) -> None:
     """Write the exact manifest role set onto the final-report data.json."""
     if not ctx.data_path.is_file() or not ctx.manifest_path.is_file():
@@ -685,13 +674,11 @@ def _recovery_step_names(
     """The steps a retry has to re-run: every step from the earliest failure on.
 
     Naming only the failed steps would prescribe half a recovery. `token-usage`
-    defers, so `render-views` already wrote an html view from unsubstituted
-    data; substituting the tokens on a retry leaves that view stale
+    can fail while `render-views` still writes html from unsubstituted data;
+    substituting the tokens on a retry leaves that view stale
     (`validators/validate-report-views.py` checks `source-sha256` against the
-    md body). And a sequence that stopped early never reached `validate-run`,
-    which is the step that decides whether the run is shippable. Resuming from
-    the earliest failure redoes both while still skipping the prefix that
-    succeeded — the saving `--only` exists for.
+    md body). Resuming from the earliest failure redoes the tail while skipping
+    the prefix that succeeded — the saving `--only` exists for.
     """
     failed = {
         string_value(step.get("name"))