okstra 0.25.1 → 0.26.0

package/runtime/python/okstra_ctl/wizard.py

@@ -84,6 +84,7 @@ S_BRIEF_KEEP = "brief_keep"
 S_BRIEF_PATH = "brief_path"
 S_BASE_REF_PICK = "base_ref_pick"
 S_BASE_REF_TEXT = "base_ref_text"
+S_APPROVED_PLAN_PICK = "approved_plan_pick"
 S_APPROVED_PLAN = "approved_plan"
 S_EXECUTOR = "executor"
 S_DEFAULTS_OR_CUSTOM = "defaults_or_custom"
@@ -94,9 +95,13 @@ S_CLAUDE_MODEL = "claude_model"
 S_CODEX_MODEL = "codex_model"
 S_GEMINI_MODEL = "gemini_model"
 S_REPORT_WRITER_MODEL = "report_writer_model"
+S_DIRECTIVE_PICK = "directive_pick"
 S_DIRECTIVE = "directive"
+S_RELATED_TASKS_PICK = "related_tasks_pick"
 S_RELATED_TASKS = "related_tasks"
+S_CLARIFICATION_PICK = "clarification_pick"
 S_CLARIFICATION = "clarification"
+S_PR_TEMPLATE_PICK = "pr_template_pick"
 S_PR_TEMPLATE = "pr_template"
 S_PR_TEMPLATE_SCOPE = "pr_template_scope"
 S_CONFIRM = "confirm"
@@ -134,6 +139,7 @@ class WizardState:
 
     # impl extras
     approved_plan_path: str = ""
+    approved_plan_pending_text: bool = False
     executor: str = ""
 
     # customize
@@ -145,9 +151,13 @@ class WizardState:
     gemini_model: str = ""
     report_writer_model: str = ""
     directive: str = ""
+    directive_pending_text: bool = False
     related_tasks_raw: str = ""
+    related_tasks_pending_text: bool = False
     clarification_response_path: str = ""
+    clarification_pending_text: bool = False
     pr_template_path: str = ""
+    pr_template_pending_text: bool = False
     pr_template_scope: str = ""  # "once" | "project" | "global"
 
     # confirm / edit
@@ -533,6 +543,81 @@ def _submit_base_ref_text(state: WizardState, value: str) -> Optional[str]:
     return f"base-ref: {ref}"
 
 
+PICK_USE_DEFAULT = "__use_default__"
+PICK_OTHER = "__other__"
+PICK_SKIP = "__skip__"
+PICK_ENTER = "__enter__"
+
+
+def _latest_implementation_planning_report(state: WizardState) -> Optional[Path]:
+    """Find the latest ``final-report-implementation-planning-<seq>.md`` under
+    the current task's runs directory.
+
+    Returns the path relative to ``project_root`` if found, otherwise ``None``.
+    """
+    if not state.task_group or not state.task_id or not state.project_root:
+        return None
+    base = (Path(state.project_root) / ".project-docs" / "okstra" / "tasks"
+            / slugify_task_segment(state.task_group)
+            / slugify_task_segment(state.task_id)
+            / "runs" / "implementation-planning")
+    if not base.is_dir():
+        return None
+    pat = re.compile(r"^final-report-implementation-planning-(\d+)\.md$")
+    best: tuple[int, Path] | None = None
+    for run_dir in base.iterdir():
+        reports = run_dir / "reports"
+        if not reports.is_dir():
+            continue
+        for child in reports.iterdir():
+            m = pat.match(child.name)
+            if not m:
+                continue
+            n = int(m.group(1))
+            if best is None or n > best[0]:
+                best = (n, child)
+    if best is None:
+        return None
+    try:
+        return best[1].relative_to(Path(state.project_root))
+    except ValueError:
+        return best[1]
+
+
+def _build_approved_plan_pick(state: WizardState) -> Prompt:
+    default = _latest_implementation_planning_report(state)
+    options = [
+        _opt(PICK_USE_DEFAULT, f"기본 경로 사용: {default}"),
+        _opt(PICK_OTHER, "다른 경로 입력"),
+    ]
+    return Prompt(
+        step=S_APPROVED_PLAN_PICK, kind="pick",
+        label=f"approved final-report 경로 (기본: {default})",
+        options=options,
+        echo_template="approved-plan(pick): {value}",
+    )
+
+
+def _submit_approved_plan_pick(state: WizardState, value: str) -> Optional[str]:
+    if value == PICK_USE_DEFAULT:
+        default = _latest_implementation_planning_report(state)
+        if default is None:
+            raise WizardError(
+                "기본 approved-plan 경로를 찾을 수 없습니다. '다른 경로 입력'을 선택하세요."
+            )
+        p = _validate_approved_plan(str(default), Path(state.project_root))
+        state.approved_plan_path = str(p)
+        state.approved_plan_pending_text = False
+        return f"approved-plan: {p}"
+    if value == PICK_OTHER:
+        state.approved_plan_pending_text = True
+        state.approved_plan_path = ""
+        return None
+    raise WizardError(
+        f"expected '{PICK_USE_DEFAULT}' or '{PICK_OTHER}', got: {value!r}"
+    )
+
+
 def _build_approved_plan(state: WizardState) -> Prompt:
     return Prompt(
         step=S_APPROVED_PLAN, kind="text",
@@ -544,9 +629,103 @@ def _build_approved_plan(state: WizardState) -> Prompt:
 def _submit_approved_plan(state: WizardState, value: str) -> Optional[str]:
     p = _validate_approved_plan(value, Path(state.project_root))
     state.approved_plan_path = str(p)
+    state.approved_plan_pending_text = False
     return f"approved-plan: {p}"
 
 
+def _build_directive_pick(state: WizardState) -> Prompt:
+    return Prompt(
+        step=S_DIRECTIVE_PICK, kind="pick",
+        label="추가 directive 가 있나요?",
+        options=[
+            _opt(PICK_SKIP, "없음 (건너뛰기)"),
+            _opt(PICK_ENTER, "있음 (입력)"),
+        ],
+        echo_template="directive(pick): {value}",
+    )
+
+
+def _submit_directive_pick(state: WizardState, value: str) -> Optional[str]:
+    if value == PICK_SKIP:
+        state.directive = ""
+        state.directive_pending_text = False
+        return "directive: (none)"
+    if value == PICK_ENTER:
+        state.directive_pending_text = True
+        return None
+    raise WizardError(f"expected '{PICK_SKIP}' or '{PICK_ENTER}', got: {value!r}")
+
+
+def _build_related_tasks_pick(state: WizardState) -> Prompt:
+    return Prompt(
+        step=S_RELATED_TASKS_PICK, kind="pick",
+        label="관련 task id 목록이 있나요?",
+        options=[
+            _opt(PICK_SKIP, "없음 (건너뛰기)"),
+            _opt(PICK_ENTER, "있음 (입력)"),
+        ],
+        echo_template="related-tasks(pick): {value}",
+    )
+
+
+def _submit_related_tasks_pick(state: WizardState, value: str) -> Optional[str]:
+    if value == PICK_SKIP:
+        state.related_tasks_raw = ""
+        state.related_tasks_pending_text = False
+        return "related-tasks: (none)"
+    if value == PICK_ENTER:
+        state.related_tasks_pending_text = True
+        return None
+    raise WizardError(f"expected '{PICK_SKIP}' or '{PICK_ENTER}', got: {value!r}")
+
+
+def _build_clarification_pick(state: WizardState) -> Prompt:
+    return Prompt(
+        step=S_CLARIFICATION_PICK, kind="pick",
+        label="clarification-response 파일 경로가 있나요? (follow-up 시에만)",
+        options=[
+            _opt(PICK_SKIP, "없음 (건너뛰기)"),
+            _opt(PICK_ENTER, "있음 (입력)"),
+        ],
+        echo_template="clarification(pick): {value}",
+    )
+
+
+def _submit_clarification_pick(state: WizardState, value: str) -> Optional[str]:
+    if value == PICK_SKIP:
+        state.clarification_response_path = ""
+        state.clarification_pending_text = False
+        return "clarification: (none)"
+    if value == PICK_ENTER:
+        state.clarification_pending_text = True
+        return None
+    raise WizardError(f"expected '{PICK_SKIP}' or '{PICK_ENTER}', got: {value!r}")
+
+
+def _build_pr_template_pick(state: WizardState) -> Prompt:
+    return Prompt(
+        step=S_PR_TEMPLATE_PICK, kind="pick",
+        label="PR 본문 템플릿 경로를 직접 지정할까요?",
+        options=[
+            _opt(PICK_SKIP, "자동 해석 (project.json → config → 기본)"),
+            _opt(PICK_ENTER, "직접 경로 입력 (1회성 override)"),
+        ],
+        echo_template="pr-template(pick): {value}",
+    )
+
+
+def _submit_pr_template_pick(state: WizardState, value: str) -> Optional[str]:
+    if value == PICK_SKIP:
+        state.pr_template_path = ""
+        state.pr_template_scope = ""
+        state.pr_template_pending_text = False
+        return "pr-template: (auto-resolve)"
+    if value == PICK_ENTER:
+        state.pr_template_pending_text = True
+        return None
+    raise WizardError(f"expected '{PICK_SKIP}' or '{PICK_ENTER}', got: {value!r}")
+
+
 def _build_executor(state: WizardState) -> Prompt:
     options = [_opt(e, e + (" (default)" if e == "claude" else ""))
                for e in EXECUTORS]
@@ -689,6 +868,7 @@ def _build_directive(state: WizardState) -> Prompt:
 
 def _submit_directive(state: WizardState, value: str) -> Optional[str]:
     state.directive = (value or "").strip()
+    state.directive_pending_text = False
     return f"directive: {state.directive or '(none)'}"
 
 
@@ -702,6 +882,7 @@ def _build_related_tasks(state: WizardState) -> Prompt:
 
 def _submit_related_tasks(state: WizardState, value: str) -> Optional[str]:
     state.related_tasks_raw = (value or "").strip()
+    state.related_tasks_pending_text = False
     return f"related-tasks: {state.related_tasks_raw or '(none)'}"
 
 
@@ -715,6 +896,7 @@ def _build_clarification(state: WizardState) -> Prompt:
 
 def _submit_clarification(state: WizardState, value: str) -> Optional[str]:
     val = (value or "").strip()
+    state.clarification_pending_text = False
     if not val:
         state.clarification_response_path = ""
         return "clarification: (none)"
@@ -734,6 +916,7 @@ def _build_pr_template(state: WizardState) -> Prompt:
 
 def _submit_pr_template(state: WizardState, value: str) -> Optional[str]:
     val = (value or "").strip()
+    state.pr_template_pending_text = False
     if not val:
         state.pr_template_path = ""
         state.pr_template_scope = ""
@@ -860,15 +1043,29 @@ STEPS: list[Step] = [
          applies=lambda s: s.base_ref_pending_text,
          build=_build_base_ref_text, submit=_submit_base_ref_text,
          owns=("base_ref", "base_ref_pending_text")),
+    Step(S_APPROVED_PLAN_PICK,
+         applies=lambda s: (s.task_type == "implementation"
+                            and not s.approved_plan_path
+                            and not s.approved_plan_pending_text
+                            and S_APPROVED_PLAN_PICK not in s.answered
+                            and bool(s.brief_path)
+                            and (s.reuse_worktree is True
+                                 or S_BASE_REF_PICK in s.answered)
+                            and not s.base_ref_pending_text
+                            and _latest_implementation_planning_report(s) is not None),
+         build=_build_approved_plan_pick, submit=_submit_approved_plan_pick,
+         owns=("approved_plan_path", "approved_plan_pending_text")),
     Step(S_APPROVED_PLAN,
          applies=lambda s: (s.task_type == "implementation"
                             and not s.approved_plan_path
                             and bool(s.brief_path)
                             and (s.reuse_worktree is True
                                  or S_BASE_REF_PICK in s.answered)
-                            and not s.base_ref_pending_text),
+                            and not s.base_ref_pending_text
+                            and (s.approved_plan_pending_text
+                                 or _latest_implementation_planning_report(s) is None)),
          build=_build_approved_plan, submit=_submit_approved_plan,
-         owns=("approved_plan_path",)),
+         owns=("approved_plan_path", "approved_plan_pending_text")),
     Step(S_EXECUTOR,
          applies=lambda s: (s.task_type == "implementation"
                             and bool(s.approved_plan_path)
@@ -927,27 +1124,52 @@ STEPS: list[Step] = [
                             and S_REPORT_WRITER_MODEL not in s.answered),
          build=_build_report_writer_model, submit=_submit_report_writer_model,
          owns=("report_writer_model",)),
+    Step(S_DIRECTIVE_PICK,
+         applies=lambda s: (s.use_defaults is False
+                            and S_DIRECTIVE_PICK not in s.answered),
+         build=_build_directive_pick, submit=_submit_directive_pick,
+         owns=("directive", "directive_pending_text")),
     Step(S_DIRECTIVE,
          applies=lambda s: (s.use_defaults is False
+                            and s.directive_pending_text
                             and S_DIRECTIVE not in s.answered),
          build=_build_directive, submit=_submit_directive,
-         owns=("directive",)),
+         owns=("directive", "directive_pending_text")),
+    Step(S_RELATED_TASKS_PICK,
+         applies=lambda s: (s.use_defaults is False
+                            and S_RELATED_TASKS_PICK not in s.answered),
+         build=_build_related_tasks_pick, submit=_submit_related_tasks_pick,
+         owns=("related_tasks_raw", "related_tasks_pending_text")),
     Step(S_RELATED_TASKS,
          applies=lambda s: (s.use_defaults is False
+                            and s.related_tasks_pending_text
                             and S_RELATED_TASKS not in s.answered),
          build=_build_related_tasks, submit=_submit_related_tasks,
-         owns=("related_tasks_raw",)),
+         owns=("related_tasks_raw", "related_tasks_pending_text")),
+    Step(S_CLARIFICATION_PICK,
+         applies=lambda s: (s.use_defaults is False
+                            and S_CLARIFICATION_PICK not in s.answered),
+         build=_build_clarification_pick, submit=_submit_clarification_pick,
+         owns=("clarification_response_path", "clarification_pending_text")),
     Step(S_CLARIFICATION,
          applies=lambda s: (s.use_defaults is False
+                            and s.clarification_pending_text
                             and S_CLARIFICATION not in s.answered),
          build=_build_clarification, submit=_submit_clarification,
-         owns=("clarification_response_path",)),
+         owns=("clarification_response_path", "clarification_pending_text")),
+    Step(S_PR_TEMPLATE_PICK,
+         applies=lambda s: (s.use_defaults is False
+                            and s.task_type == "release-handoff"
+                            and S_PR_TEMPLATE_PICK not in s.answered),
+         build=_build_pr_template_pick, submit=_submit_pr_template_pick,
+         owns=("pr_template_path", "pr_template_scope", "pr_template_pending_text")),
     Step(S_PR_TEMPLATE,
          applies=lambda s: (s.use_defaults is False
                             and s.task_type == "release-handoff"
+                            and s.pr_template_pending_text
                             and S_PR_TEMPLATE not in s.answered),
          build=_build_pr_template, submit=_submit_pr_template,
-         owns=("pr_template_path", "pr_template_scope")),
+         owns=("pr_template_path", "pr_template_scope", "pr_template_pending_text")),
     Step(S_PR_TEMPLATE_SCOPE,
          applies=lambda s: (s.use_defaults is False
                             and s.task_type == "release-handoff"
@@ -1021,11 +1243,15 @@ _FIELD_DEFAULTS: dict[str, Any] = {
     "profile_workers": [], "keep_existing_brief": None,
     "brief_path": "", "reuse_worktree": None, "base_ref": "",
     "base_ref_pending_text": False, "approved_plan_path": "",
+    "approved_plan_pending_text": False,
     "executor": "", "use_defaults": None, "workers_override": "",
     "lead_model": "", "claude_model": "", "codex_model": "",
     "gemini_model": "", "report_writer_model": "", "directive": "",
-    "related_tasks_raw": "", "clarification_response_path": "",
-    "pr_template_path": "", "pr_template_scope": "",
+    "directive_pending_text": False,
+    "related_tasks_raw": "", "related_tasks_pending_text": False,
+    "clarification_response_path": "", "clarification_pending_text": False,
+    "pr_template_path": "", "pr_template_pending_text": False,
+    "pr_template_scope": "",
     "confirmed": None, "edit_target": "",
 }
 

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

@@ -407,3 +407,206 @@ Information to be passed to Phase 6 after executing this skill:
 ## Convergence Disabled
 
 If `convergence.enabled: false`, this skill is skipped. Phase 6 operates using the existing consensus/divergence method.
+
+## Plan-body verification mode (implementation-planning only)
+
+This section defines a **second, independent** convergence round that fires only for `task-type = implementation-planning`. The round verifies the *consolidated plan* that the report-writer worker has authored, not the worker findings that were already reconciled earlier.
+
+### Lifecycle position (BLOCKING)
+
+Plan-body verification runs **after** finding convergence and **after** the report-writer draft is written. Sequence inside a single implementation-planning run:
+
+```
+Phase 4   workers produce independent analyses (Findings F-001…)
+  → Phase 5.5   FINDING convergence (this skill, sections "Convergence Algorithm" through "Convergence State Artifact")
+  → Phase 6   report-writer authors final-report draft (consolidated Option Candidates / Stepwise Execution Order / Dependency / Validation Checklist / Rollback)
+  → PLAN-BODY VERIFICATION ROUND ← new — described below
+  → User Approval gate (top-of-report `- [ ] Approved` marker is rendered only when this round's Gate result is `passed` or `passed-with-dissent`)
+  → implementation phase (separate run)
+```
+
+Plan-body verification MUST NOT replace, precede, or be conflated with the Phase 5.5 finding convergence above. They are two distinct rounds with different inputs (findings vs. consolidated plan body), different ID schemes (`F-*` vs. `P-*`), and different state files.
+
+### MUTUAL EXCLUSION (BLOCKING)
+
+The finding queue (Phase 5.5) and the plan-item queue (this section) are **disjoint**:
+
+- A finding-convergence reverify prompt MUST NOT contain any `P-*` item.
+- A plan-body verification prompt MUST NOT contain any `F-*` finding.
+- The two rounds write to **different state files**: `runs/<task-type>/state/convergence-state.json` (findings) vs. `runs/<task-type>/state/plan-body-verification.json` (plan items).
+- Aggregation logic (verdict counting, classification) MUST NOT carry votes from one queue into the other.
+
+Mixing the two queues — for example, parsing a Phase 6 draft's Stepwise Execution Order step as if it were an `F-*` finding — is a contract violation. Future Claude reading this skill: if you find yourself tempted to "just reuse the finding queue for plan items, they're similar enough", stop. They are not similar enough; the verdict semantics differ (see §"Plan-body verdict semantics" below).
+
+### Configuration
+
+Plan-body verification is configured under `convergence.planBodyVerification` in `task-manifest.json`:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `enabled` | `true` | If `false`, the round is skipped and the top-of-report Approval marker is rendered unconditionally (legacy behaviour). |
+| `maxRounds` | `1` | Hard upper bound. Plan-body verification is consistency / completeness checking, not fact checking — additional rounds rarely help. Range 1–3. |
+| `gating` | `true` | If `true` (default), `majority-disagree` blocks the Approval marker. If `false`, the round is advisory-only and the marker always renders. |
+
+Default values are emitted into the manifest by `scripts/okstra_ctl/render.py` (`_build_convergence_block`). The ctx knob `OKSTRA_PLAN_VERIFICATION=false` flips `planBodyVerification.enabled` to false.
+
+### Plan-item extraction (Round 0 equivalent)
+
+From the report-writer's draft of `## 4.5 Implementation Plan Deliverables`, lead extracts plan items with the following prefixes (see also `templates/reports/final-report.template.md` §4.5.9):
+
+| Prefix | Source sub-section | One row per |
+|--------|--------------------|-------------|
+| `P-Opt-<N>` | `4.5.1 Option Candidates` | one Option (its File Structure list + interfaces + blast radius) |
+| `P-Step-<N>` | `4.5.4 Stepwise Execution Order` | one step (path + command + success signal) |
+| `P-Dep-<N>` | `4.5.5 Dependency / Migration Risk` | one dependency row |
+| `P-Val-<N>` | `4.5.6 Validation Checklist` | one checklist item |
+| `P-Rb-<N>` | `4.5.7 Rollback Strategy` | one rollback path |
+
+`4.5.2 Trade-off Matrix` and `4.5.3 Recommended Option` are NOT extracted as standalone plan items — the trade-off matrix is evaluated implicitly through each option's `P-Opt-*` verification, and the recommended option is one of those `P-Opt-*` rows.
+
+Each plan item inherits the `[TICKETID: ...]` tag of its source section (per the standard ticket-tagging contract).
+
+### Plan-body verdict semantics
+
+The verdict tokens `AGREE` / `DISAGREE` / `SUPPLEMENT` are reused, but their meaning is plan-specific:
+
+- **AGREE**: the item is executable as written *and* internally consistent with other items in the plan.
+- **DISAGREE(<kind>)**: the item is broken. `<kind>` MUST be one of:
+  - `a` — referenced file path / symbol mismatches another step or option's File Structure list
+  - `b` — command is not executable or is ambiguous
+  - `c` — validation signal is not observable
+  - `d` — rollback violates commit / dependency order
+  - `e` — item contradicts the trade-off matrix
+- **SUPPLEMENT**: the item is sound but is missing a dependency / edge case / precondition.
+
+Worker non-result handling (`timeout`, `error`, no result file, wrapper `cli-failure`) is identical to finding convergence: do NOT aggregate as DISAGREE, record `contract-violation`, and apply the round-level abort rule below.
+
+### Mode constraint
+
+Plan-body verification only supports **lightweight mode** (defined in §"Verification Mode" above). `full-reanalysis` is not meaningful here because the "original source materials" for a plan item are the worker's own analysis plus the lead-mediated synthesis — there is no independent ground truth to re-read. The manifest's top-level `verificationMode` is ignored for this round; lightweight is always used.
+
+### Round protocol (single round at default `maxRounds=1`)
+
+1. Lead parses the report-writer draft and extracts the `P-*` plan items.
+2. For each analyser worker in the roster (`claude`, `codex`, and `gemini` if opted in), lead constructs a reverify prompt using the template in §"Plan-body reverify prompt" below.
+3. Dispatch uses the same wrapper infrastructure as finding convergence. The `--role-slug` is `<role>-plan-verify-r<N>`. Result file path: `runs/<task-type>/worker-results/<role-slug>-plan-verify-r<N>-implementation-planning-<seq>.md`.
+4. After all dispatches return, lead aggregates verdicts per `P-*` item across workers and classifies each:
+   - `full-consensus` — all participating analysers `AGREE` (SUPPLEMENT counts as agree on the item itself).
+   - `partial-consensus` — majority `AGREE`, dissenting `DISAGREE` recorded.
+   - `worker-unique` — only one worker `DISAGREE`s, others `AGREE` — treat as `partial-consensus` for gate purposes; record dissent.
+   - `majority-disagree` — majority of analysers `DISAGREE` on this item. This is the only classification that **blocks the Approval marker**.
+   - `contested` only meaningful when `maxRounds > 1`; at default `maxRounds=1`, fold any unresolved item into `partial-consensus`.
+5. Gate result resolution:
+   - any `majority-disagree` item present AND `gating=true` → `blocked-by-disagreement`
+   - all dispatches non-result → `aborted-non-result`
+   - any `partial-consensus` / `worker-unique` present, no `majority-disagree` → `passed-with-dissent`
+   - all items `full-consensus` → `passed`
+6. Lead writes `runs/<task-type>/state/plan-body-verification.json` (schema below) and populates `### 4.5.9 Plan Body Verification` in the final report (template at `templates/reports/final-report.template.md`).
+7. For every `majority-disagree` item, lead adds a row to `## 5. Clarification Items` with:
+   - new `C-<N>` ID (numbering continues from any existing rows)
+   - `Statement` summarising the disagreement and the worker breakage `<kind>`
+   - `Kind` chosen per the standard policy (usually `decision` for option-level conflicts, `data-point` for path/symbol mismatches)
+   - `Blocks=approval`
+   - the §4.5.9 verdict table's `Classification` column for that row reads `majority-disagree → C-<N>` (1:1 ID match — orphan on either side is a contract violation per `prompts/profiles/implementation-planning.md` self-review step 6).
+8. The top-of-report `- [ ] Approved` marker line is rendered if and only if the Gate result is `passed` or `passed-with-dissent`. `validators/validate-run.py` `validate_phase_boundary` enforces this correspondence; manually adding the marker line when the gate did not pass is a contract violation.
+
+### `plan-body-verification.json` schema
+
+```json
+{
+  "schemaVersion": "1.0",
+  "phase": "implementation-planning",
+  "round": 1,
+  "effectiveMaxRounds": 1,
+  "gating": true,
+  "verificationMode": "lightweight",
+  "gateResult": "passed | passed-with-dissent | blocked-by-disagreement | aborted-non-result",
+  "planItems": [
+    {
+      "id": "P-Opt-1",
+      "sourceSection": "4.5.1",
+      "ticketId": "<id-or-unknown>",
+      "votes": {"claude-worker": "AGREE", "codex-worker": "AGREE"},
+      "classification": "full-consensus",
+      "clarificationId": null
+    },
+    {
+      "id": "P-Step-3",
+      "sourceSection": "4.5.4",
+      "ticketId": "TICKET-123",
+      "votes": {"claude-worker": "DISAGREE(a)", "codex-worker": "DISAGREE(a)"},
+      "classification": "majority-disagree",
+      "clarificationId": "C-7"
+    }
+  ],
+  "dispatches": [
+    {"role": "claude-worker", "resultPath": "...", "terminalStatus": "completed"}
+  ]
+}
+```
+
+`dispatches[].terminalStatus` mirrors finding convergence (`completed | timeout | error | not-run | cli-failure`).
+
+### Plan-body reverify prompt
+
+Required prompt anchor headers are identical to finding convergence (see §"Required reverify-prompt anchor headers"). The prompt body changes from F-* listing to P-* listing:
+
+```
+You are <worker-role> performing plan-body verification for <task-key> (round 1).
+
+## Instructions
+
+Review the following items extracted from the consolidated implementation plan
+authored after your initial analysis. For EACH item, respond with exactly one
+verdict:
+
+- **AGREE**: The item is executable as written and internally consistent with
+  other items in the plan.
+- **DISAGREE(<kind>)**: The item is broken. Cite which kind:
+  (a) referenced file path / symbol mismatches another step or option,
+  (b) command is not executable or is ambiguous,
+  (c) validation signal is not observable,
+  (d) rollback violates commit / dependency order,
+  (e) item contradicts the trade-off matrix.
+- **SUPPLEMENT**: The item is sound but a dependency / edge case / precondition
+  is missing.
+
+Do NOT re-analyze the original requirements. Judge solely from plan internal
+consistency and stated commands / paths. Do NOT inspect the original task brief
+or worker analyses for this round.
+
+## Plan items to verify
+
+### P-Step-3 [TICKETID: <id>]: <one-line summary>
+**From section**: 4.5.4 Stepwise Execution Order
+**Original text**:
+> <verbatim quote of the step>
+
+**Check**:
+ - Are referenced file paths consistent with the option's File Structure list?
+ - Is the named command executable as written?
+ - Does the success criterion produce an observable signal?
+
+### P-Opt-2 [TICKETID: <id>]: <one-line summary>
+...
+
+## Response format
+
+### P-Step-3
+**Verdict**: AGREE | DISAGREE(<a|b|c|d|e>) | SUPPLEMENT
+**Explanation**: <2-3 sentences>
+
+### P-Opt-2
+...
+```
+
+The "Reverify prompt: required-reading suppression (BLOCKING)" rule (lightweight mode does NOT inject a `[Required reading]` clause) applies here as well.
+
+### Worker non-result handling in plan-body round (BLOCKING)
+
+Mirrors finding convergence (§"Worker failure handling in reverify"). Concretely:
+
+- A dispatch that returns terminal non-result MUST NOT be aggregated as `DISAGREE`.
+- If at least one dispatch was issued AND **all** plan-body dispatches return non-result, the Gate result is `aborted-non-result`. Record one `contract-violation` event per non-result dispatch.
+- The Approval marker is NOT rendered when the gate is `aborted-non-result`. A single row is added to `## 5. Clarification Items` with `Statement="plan-body verification could not run — all workers returned non-result"`, `Kind=decision`, `Blocks=approval`, allowing the user to either retry the phase or override by manually approving the plan (via `--approve` on the resume command).
+

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").
@@ -66,13 +68,23 @@ 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"`.
@@ -84,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).
@@ -110,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
@@ -120,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
@@ -152,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
 
@@ -182,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