okstra 0.25.1 → 0.26.0

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

@@ -225,6 +225,40 @@ revert 경로와 롤백 트리거 신호를 표로 정리합니다. 추상적
 - 본 섹션에는 승인 결정에 영향을 주는 *플랜 측 보충 메모*만 적습니다(예: 위험을 줄이기 위한 사전 작업, 승인 전 사용자가 확인해 두어야 할 사항). 승인 마커는 본 섹션이 아니라 상단 블록의 체크박스로만 부여합니다.
 - 사용자가 답하거나 자료를 첨부해야만 승인이 가능한 항목은 **이 섹션에 적지 않습니다** — `## 5. Clarification Items` 표에 한 행으로 등록하고 `Blocks=approval` 로 표시하세요. 같은 항목을 두 위치에 적으면 sync 가 깨집니다.
 
+### 4.5.9 Plan Body Verification (워커 사후 검증)
+
+> **이 sub-section 은 `task-type` = `implementation-planning` 실행 결과에만 포함하세요.** Phase 6 에서 report-writer 가 합성한 4.5 본문(Option Candidates / Stepwise Execution Order / Dependency / Validation Checklist / Rollback)을 lead 가 plan-item 단위로 쪼개 워커들에게 다시 던지고 `AGREE / DISAGREE / SUPPLEMENT` 평결을 수집한 결과입니다. 자세한 라운드 프로토콜은 `skills/okstra-convergence/SKILL.md` "Plan-body verification mode" 섹션을 참고하세요.
+
+- **Round count**: `<N>` (default: 1)
+- **Gate result**: `<passed | passed-with-dissent | blocked-by-disagreement | aborted-non-result>`
+  - `passed` → 본 보고서 상단 `User Approval Request` 체크박스가 렌더됩니다.
+  - `passed-with-dissent` → 상단 체크박스가 렌더되되, 반대 의견은 아래 `Dissent log` 에 기록.
+  - `blocked-by-disagreement` → 상단 체크박스 라인 자체를 **렌더하지 않습니다**. majority DISAGREE 인 plan item 마다 `## 5. Clarification Items` 에 `Blocks=approval` row 가 추가되며, 사용자가 응답해야 다음 phase 로 넘어갈 수 있습니다.
+  - `aborted-non-result` → 워커 dispatch 가 모두 non-result (timeout / error). 상단 체크박스 라인 렌더하지 않음 + `## 5. Clarification Items` 에 "plan-body verification could not run" row 가 추가됩니다.
+
+#### Verdict table
+
+각 plan item 1 행. `Plan item` 열은 `P-Opt-<N>` / `P-Step-<N>` / `P-Dep-<N>` / `P-Val-<N>` / `P-Rb-<N>` prefix 사용. `Section` 열은 4.5 내부 sub-section 번호 (예: `4.5.4`).
+
+| Plan item | Ticket ID | Section | <worker1> | <worker2> | ... | Classification |
+|-----------|-----------|---------|-----------|-----------|-----|----------------|
+| P-Opt-1   | `<id>`    | 4.5.1   | AGREE     | AGREE     | ... | full-consensus |
+| P-Step-3  | `<id>`    | 4.5.4   | DISAGREE(a) | DISAGREE(a) | ... | majority-disagree → C-7 |
+
+- DISAGREE 셀에는 spec 의 `(a|b|c|d|e)` breakage kind 를 함께 표기 (예: `DISAGREE(a)` = 참조 file path / symbol 불일치).
+- 마지막 열 `Classification` ∈ `{full-consensus, partial-consensus, worker-unique, majority-disagree → C-<N>}`. `majority-disagree → C-<N>` 의 `C-<N>` 은 본 보고서 `## 5. Clarification Items` 표에서 해당 변환 row 의 ID 와 일치해야 합니다.
+
+#### Dissent log
+
+`partial-consensus` 와 `worker-unique` 로 분류된 plan item 의 반대 의견을 plan item 별로 묶어 적습니다. `majority-disagree` 항목의 반대 의견은 본 섹션 대신 `## 5. Clarification Items` 의 해당 row 의 `Statement` 컬럼에 옮겨 적습니다.
+
+- **P-XXX-N**: `<worker-role>` — `<반대 의견 본문 2-3 sentences>`
+
+#### Notes
+
+- 본 sub-section 이 누락된 채로 task-type = implementation-planning final report 가 생성되면 validator 가 `contract-violated` 로 종료합니다.
+- `Gate result` 가 `blocked-by-disagreement` / `aborted-non-result` 인데 상단 `User Approval Request` 체크박스 라인이 존재하면 동일하게 contract violation 입니다.
+
 ## 4.6 Release Handoff Deliverables (release-handoff runs only)
 
 > **이 섹션은 `task-type` = `release-handoff` 실행 결과에만 포함하세요. 다른 task-type에서는 섹션 전체를 삭제하고 5번 섹션으로 넘어갑니다.**

package/runtime/validators/validate-run.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import re
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
@@ -527,6 +528,35 @@ PLANNING_REQUIRED_SECTIONS = (
     "Validation Checklist",
     "Rollback",
     "User Approval Request",
+    "Plan Body Verification",
+)
+
+PLAN_VERIFY_GATE_VALUES = (
+    "passed",
+    "passed-with-dissent",
+    "blocked-by-disagreement",
+    "aborted-non-result",
+)
+
+# `Gate result:` line in §4.5.9 of the final report — captures the value
+# token that follows. Tolerates arbitrary markdown formatting between the
+# label and the value (backticks for inline code, double-asterisks for
+# bold, colons, hyphens, whitespace). The captured value is then
+# validated against `PLAN_VERIFY_GATE_VALUES` below so typo'd or unknown
+# values surface as their own failure rather than silently no-matching.
+_GATE_RESULT_RE = re.compile(
+    r"Gate result[^A-Za-z\n]+(?P<value>[a-z][a-z\-]+)",
+    re.IGNORECASE,
+)
+
+# Approval marker line — the bullet that toggles to grant approval. Both
+# unchecked (`- [ ] Approved`) and checked (`- [x] Approved`) forms count
+# as "checkbox present" for this gate. Line-anchored to avoid false
+# positives from inline-code prose examples elsewhere in the template
+# (mirrors `APPROVED_PLAN_PATTERN` in scripts/okstra_ctl/run.py:79).
+_APPROVAL_CHECKBOX_RE = re.compile(
+    r"^[ \t]*(?:[-*+][ \t]+)?`?\[[ xX]\][ \t]*Approved`?[ \t]*$",
+    re.MULTILINE,
 )
 
 
@@ -541,6 +571,13 @@ def validate_phase_boundary(
     required deliverable sections; absence indicates a planning run that
     skipped its core outputs (or an implementation run that ran under the
     wrong task type).
+
+    Additionally enforces the Plan Body Verification gate (§4.5.9):
+    - gate ∈ {passed, passed-with-dissent} → top-level Approval checkbox
+      MUST be present.
+    - gate ∈ {blocked-by-disagreement, aborted-non-result} → checkbox
+      MUST be absent (lead converted findings into Clarification rows
+      instead of opening the gate).
     """
     if task_type != "implementation-planning":
         return
@@ -554,6 +591,40 @@ def validate_phase_boundary(
                 f"`{needle}`"
             )
 
+    gate_match = _GATE_RESULT_RE.search(content)
+    if gate_match is None:
+        # The `Plan Body Verification` heading check above already covers
+        # the wholly-missing case; a heading present without a `Gate result`
+        # line is its own contract violation.
+        if "Plan Body Verification" in content:
+            failures.append(
+                "implementation-planning report has `Plan Body Verification` "
+                "section but no `Gate result:` line — required by §4.5.9."
+            )
+        return
+    gate_value = gate_match.group("value").strip().lower()
+    if gate_value not in PLAN_VERIFY_GATE_VALUES:
+        failures.append(
+            "implementation-planning report `Gate result` value "
+            f"`{gate_value}` is not one of "
+            f"{', '.join(PLAN_VERIFY_GATE_VALUES)}."
+        )
+        return
+    checkbox_present = _APPROVAL_CHECKBOX_RE.search(content) is not None
+    if gate_value in ("passed", "passed-with-dissent") and not checkbox_present:
+        failures.append(
+            "implementation-planning report Gate result is "
+            f"`{gate_value}` but the top-level `User Approval Request` "
+            "checkbox line (`- [ ] Approved` / `- [x] Approved`) is missing."
+        )
+    if gate_value in ("blocked-by-disagreement", "aborted-non-result") and checkbox_present:
+        failures.append(
+            "implementation-planning report Gate result is "
+            f"`{gate_value}` but a top-level `User Approval Request` "
+            "checkbox line is present — gate must NOT render the checkbox "
+            "for this gate result."
+        )
+
 
 def _refresh_task_catalog(project_root: Path, task_manifest: dict) -> tuple[bool, str]:
     """Regenerate `discovery/task-catalog.json` so it stops trailing the

package/src/wizard.mjs

@@ -1,3 +1,7 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
 import { runPythonModule } from "./_python-helper.mjs";
 import { resolvePaths } from "./paths.mjs";
 
@@ -7,12 +11,14 @@ Used by the okstra-run skill to drive the per-step prompt loop. Each
 subcommand round-trips a JSON state file held by the skill.
 
 Subcommands:
-  init         seed a fresh wizard state and emit the first prompt
-  step         submit an answer (or fetch the current prompt) and emit next
-  render-args  emit the final --flag/value map for 'okstra render-bundle'
-  confirmation emit the multi-line confirmation echo block
+  new-state-file  print a fresh absolute state-file path on stdout (no I/O on the file itself)
+  init            seed a fresh wizard state and emit the first prompt
+  step            submit an answer (or fetch the current prompt) and emit next
+  render-args     emit the final --flag/value map for 'okstra render-bundle'
+  confirmation    emit the multi-line confirmation echo block
 
 Usage:
+  okstra wizard new-state-file
   okstra wizard init --state-file <path> --project-root <p> --project-id <id>
   okstra wizard step --state-file <path> [--answer <value>]
   okstra wizard render-args --state-file <path>
@@ -50,11 +56,21 @@ export async function run(args) {
   }
 
   const [sub, ...rest] = args;
-  if (!["init", "step", "render-args", "confirmation"].includes(sub)) {
+  if (!["new-state-file", "init", "step", "render-args", "confirmation"].includes(sub)) {
     process.stderr.write(`error: unknown wizard subcommand '${sub}'\n\n${USAGE}`);
     return 2;
   }
 
+  if (sub === "new-state-file") {
+    if (rest.length > 0) {
+      process.stderr.write("error: new-state-file takes no arguments\n");
+      return 2;
+    }
+    const dir = mkdtempSync(join(tmpdir(), "okstra-wizard-"));
+    process.stdout.write(join(dir, "state.json") + "\n");
+    return 0;
+  }
+
   let flags;
   try {
     flags = parseFlags(rest);