okstra 0.25.0 → 0.26.0

package/runtime/skills/okstra-run/SKILL.md

@@ -9,6 +9,8 @@ Launch an okstra task — gather inputs interactively via the **wizard state mac
 
 **Single authority**: this skill drives `okstra wizard`, which owns every step (ordering, branching, validation). The skill is just a thin prompt-relay loop — it never decides "what to ask next" itself. If the flow needs to change, edit `scripts/okstra_ctl/wizard.py`, not this file.
 
+**Bash invocation rule (permission-friendly)**: every Bash command in this skill MUST begin with the literal token `okstra` (or another already-allowed binary) and pass literal argument values. Do not introduce shell variables (`$STATE_FILE`, `$ANSWER`, `$projectRoot`, ...), `$(...)` command substitution, or leading `VAR=...` assignments — any of those make the leading token non-literal, defeat the `Bash(okstra:*)` permission match, and force a confirmation prompt on every wizard call. When a prior tool call emitted a path or value, read it from the tool output and paste the literal string into the next command.
+
 ## When to Use
 
 - The user is inside a Claude Code session and asks to start an okstra task ("run okstra here", "start an error-analysis on this branch", "okstra implementation-planning for INV-1234").
@@ -48,39 +50,41 @@ Never invent additional questions. Never reorder. Never use `AskUserQuestion` fo
 
 ```bash
 if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
+  okstra ensure-installed >/dev/null 2>&1 || { echo "FAIL: okstra ensure-installed failed" >&2; exit 1; }
+  eval "$(okstra paths --shell)"
+  export PYTHONPATH="$OKSTRA_PYTHONPATH"
+  okstra check-project --json || { echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2; exit 1; }
 else
-  OKSTRA_CMD="npx -y okstra@latest"
+  npx -y okstra@latest ensure-installed >/dev/null 2>&1 || { echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2; exit 1; }
+  eval "$(npx -y okstra@latest paths --shell)"
+  export PYTHONPATH="$OKSTRA_PYTHONPATH"
+  npx -y okstra@latest check-project --json || { echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2; exit 1; }
 fi
-
-$OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
-  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
-  exit 1
-}
-
-eval "$($OKSTRA_CMD paths --shell)"
-export PYTHONPATH="$OKSTRA_PYTHONPATH"
-
-OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
-  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
-  echo "$OKSTRA_PROJECT_INFO" >&2
-  exit 1
-}
 ```
 
-If `OKSTRA_PROJECT_INFO.ok` is `false`, ask the user with a **plain text prompt** for an absolute project-root path; rerun `okstra check-project --cwd <path>`. Re-prompt with plain text on failure.
+The `check-project --json` output goes to stdout; read it from the tool result. If its `ok` field is `false`, ask the user with a **plain text prompt** for an absolute project-root path; rerun `okstra check-project --cwd <path> --json`. Re-prompt with plain text on failure.
 
-Parse `projectRoot` and `projectId` from `OKSTRA_PROJECT_INFO`.
+Parse `projectRoot` and `projectId` from that JSON output.
 
 ## Step 2: Initialize the wizard
 
+> **Permission-friendly invocation rule**: every `okstra wizard ...` / `okstra render-bundle ...` call below MUST start with the literal token `okstra` and use literal argument values copied from prior tool outputs. Do **not** introduce shell variables (`$STATE_FILE`, `$ANSWER`, `$projectRoot`, ...), `$(...)` command substitution, or leading assignments — they break the `Bash(okstra:*)` permission match and force a confirmation prompt on every call.
+
+First, generate a state-file path:
+
 ```bash
-STATE_FILE="$(mktemp -t okstra-wizard.XXXX.json)"
+okstra wizard new-state-file
+```
+
+This prints one absolute path on stdout (e.g. `/var/folders/.../okstra-wizard.AbCd.json`). Read that path from the tool output and **paste it literally** into every subsequent `--state-file` argument.
 
+Then initialize the wizard with the literal `projectRoot` / `projectId` you parsed from Step 1 and the literal state-file path from above:
+
+```bash
 okstra wizard init \
-  --state-file "$STATE_FILE" \
-  --project-root "$projectRoot" \
-  --project-id "$projectId"
+  --state-file /var/folders/.../okstra-wizard.AbCd.json \
+  --project-root /abs/path/to/project \
+  --project-id   my-project-id
 ```
 
 Output: the same `{ok, next}` JSON described above. The first `next` is always `step: "task_pick"`.
@@ -92,10 +96,11 @@ Repeat until `next.kind == "done"`:
 1. **Render** the prompt according to `kind`:
    - `pick` → `AskUserQuestion` with `label` and `options`. The user's chosen option's `value` is the answer string.
    - `text` → plain text message containing `label`. Consume the user's next reply verbatim as the answer string (empty reply = empty string).
-2. **Submit** the answer:
+2. **Submit** the answer — call `okstra wizard step` with the literal state-file path from Step 2 and the literal user answer (no shell variables, no `$(...)`):
    ```bash
-   okstra wizard step --state-file "$STATE_FILE" --answer "$ANSWER"
+   okstra wizard step --state-file /var/folders/.../okstra-wizard.AbCd.json --answer preprod
    ```
+   If the answer contains spaces or shell metacharacters, wrap it in double quotes around the literal string only — never inside `"$VAR"`.
 3. **Handle result**:
    - `ok: true` → echo `result.echo` to the user on one short line, then loop with `result.next`.
    - `ok: false` → show `result.error` to the user verbatim, then loop with `result.current` (re-prompt the same step).
@@ -118,9 +123,11 @@ Do not second-guess the wizard. If the next prompt seems out of place, the bug i
 When `next.step == "confirm"`, before relaying the picker, fetch the human-readable selection summary:
 
 ```bash
-okstra wizard confirmation --state-file "$STATE_FILE"
+okstra wizard confirmation --state-file /var/folders/.../okstra-wizard.AbCd.json
 ```
 
+(Substitute the literal state-file path captured in Step 2 — no `$STATE_FILE`.)
+
 Output: `{ok: true, text: "선택 확인:\n  task-type     : ...\n  ..."}`. Print `text` to the user, then render the `confirm` picker (Proceed / Edit).
 
 ## Step 5: Render the task bundle
@@ -128,9 +135,11 @@ Output: `{ok: true, text: "선택 확인:\n  task-type     : ...\n  ..."}`. Prin
 When `next.kind == "done"`, fetch the final args:
 
 ```bash
-okstra wizard render-args --state-file "$STATE_FILE"
+okstra wizard render-args --state-file /var/folders/.../okstra-wizard.AbCd.json
 ```
 
+(Again: literal state-file path, no `$STATE_FILE`.)
+
 Output: `{ok: true, args: {"project-root": "...", "task-type": "...", ...}}`. Build the `okstra render-bundle` invocation from `args`, passing each key as `--<key>` and the value verbatim (including empty strings — they are intentional `use phase default` markers).
 
 ```bash
@@ -160,7 +169,7 @@ okstra render-bundle \
 
 The python function underneath is mutex-protected (`~/.okstra/.locks/<task-key>.lock`), writes `run-context-*.json` + `run-inputs-*.json` + all manifests + discovery files, and registers the run in `~/.okstra/recent.jsonl` with status `prepared`.
 
-You can delete `$STATE_FILE` after this point — its job is done.
+You can delete the literal state-file path after this point — its job is done. Invoke `rm` with the literal path (e.g. `rm /var/folders/.../okstra-wizard.AbCd.json`), not a shell variable.
 
 ## Step 6: Take over as Claude lead
 
@@ -190,11 +199,7 @@ okstra config set pr-template-path "<path>" --scope global
 
 The scope is exposed via `wizard render-args` only as the `pr-template-path` value (1-shot override); the persist hint lives in the wizard state. Read it with:
 
-```bash
-python3 -c "import json,sys; print(json.load(open(sys.argv[1])).get('pr_template_scope',''))" "$STATE_FILE"
-```
-
-(or just inspect the JSON state file directly — it is a plain serialized `WizardState`).
+Read the JSON state file directly with the `Read` tool (literal path captured in Step 2) and inspect the `pr_template_scope` field — it is a plain serialized `WizardState`. Avoid `python3 -c "...$STATE_FILE"` style commands; they trip Bash static analysis.
 
 ## Concurrency
 

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);