okstra 0.110.0 → 0.111.0

package/runtime/prompts/profiles/_implementation-self-check.md

@@ -9,12 +9,18 @@ appends this file's body into the persisted executor prompt at dispatch time
 
 # Implementation self-check (BLOCKING — before you claim done)
 
-Before declaring the change complete, write one confirming line per item to your
-audit sidecar. If any item fails, fix it or surface the violation — do not claim
-done on a failing item.
+Before declaring the change complete, confirm each item below against the ACTUAL
+diff — not from memory. This is a re-derivation, not a rubber stamp: enumerate the
+changed files (`git diff --name-only <stage-base>..HEAD`) and, for the per-file
+items, write the confirming evidence per file, not one global "✓". If any item
+fails, fix it or surface the violation — do not claim done on a failing item.
 
-- functions: every new/edited function ≤50 effective lines, single purpose
+- diff-review done: the `Pre-commit diff review sweep` ran over the full diff and its `Coverage:` footer is in your audit sidecar (every changed file named with the rule set applied). No footer → the sweep is unfinished; do not claim done.
+- functions: every new/edited function ≤50 effective lines, single purpose — cite the longest function's actual line count, not "all under 50"
 - conventions: applied the routed pack + project patterns (name which ones)
 - names & comments: names say what, comments say why; no obvious-restatement comments; no truthful-name violations
-- verification: ran the actual build/test (paste the command + its result)
+- verification: ran the actual build/test — paste the exact command line and its real exit code / output tail, never a paraphrased "tests pass"
 - cleanup: no dead or commented-out code left behind
+
+Close with a `Self-check coverage:` line naming the files you verified the
+per-file items against, so the Coverage footer above and this gate reconcile.

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -818,6 +818,9 @@ def _implementation_executor_tail(
         parts.append(preflight_path.read_text(encoding="utf-8"))
     else:
         parts.append("# Coding-conventions preflight\n\nApply project-local conventions before editing.")
+    diff_review_path = profiles / "_implementation-diff-review.md"
+    if diff_review_path.is_file():
+        parts.append(diff_review_path.read_text(encoding="utf-8"))
     selfcheck_path = profiles / "_implementation-self-check.md"
     if selfcheck_path.is_file():
         parts.append(selfcheck_path.read_text(encoding="utf-8"))

package/runtime/python/okstra_ctl/consumers.py

@@ -68,6 +68,10 @@ def read_stage_consumer_state(
     if recover_from_carry:
         backfill_done_from_carry(plan_run_root)
     rows = read_consumers(plan_run_root)
+    return stage_consumer_state_from_rows(rows)
+
+
+def stage_consumer_state_from_rows(rows: List[Dict[str, Any]]) -> StageConsumerState:
     done_rows = [r for r in rows if r.get("status") == "done"]
     done_by_stage = latest_done_by_stage(rows)
     started = {

package/runtime/python/okstra_ctl/handoff.py

@@ -12,7 +12,7 @@ import subprocess
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Tuple
 
-from . import consumers, worktree_registry
+from . import consumers, stage_targets, worktree_registry
 from .final_report_paths import final_report_markdown_path
 from .worktree import (compute_branch_name, compute_worktree_path,
                        main_worktree_path, is_dirty_excluding_okstra,
@@ -44,28 +44,10 @@ def compute_eligibility(stage_map: List[Dict[str, Any]],
                         rows: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
     """stage 별 PR 가능 여부와 차단 사유. 의존 폐포는 선택 집합의 속성이라
     여기서는 판정하지 않는다 (assemble 의 check_dependency_closure 가 담당)."""
-    done = consumers.latest_done_by_stage(rows)
-    verified = consumers.verified_accepted_stages(rows)
-    in_pr = consumers.pr_covered_stages(rows)
-    out = []
-    for s in stage_map:
-        n = s["stage_number"]
-        reasons = []
-        if n in in_pr:
-            reasons.append("already-in-pr")
-        else:
-            if n not in done:
-                reasons.append("not-done")
-            if n not in verified:
-                reasons.append("not-verified-accepted")
-        out.append({
-            "stage": n,
-            "depends_on": list(s["depends_on"]),
-            "eligible": not reasons,
-            "reasons": reasons,
-            "head_commit": (done.get(n) or {}).get("head_commit", ""),
-        })
-    return out
+    return stage_targets.stage_lifecycle_snapshot_from_rows(
+        stage_map,
+        rows,
+    ).handoff_eligibility()
 
 
 def latest_whole_task_fv_accepted(project_root, project_id: str,

package/runtime/python/okstra_ctl/implementation_stage.py

@@ -66,32 +66,32 @@ def select_and_provision_implementation_stage(
     """
     del task_key  # The registry uses the split identity fields.
 
-    from .consumers import backfill_done_from_carry, read_stage_consumer_state
+    from .consumers import backfill_done_from_carry
     from . import worktree as _worktree
     from . import worktree_registry as _reg
 
     plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
     backfill_done_from_carry(plan_run_root)
     auto_reconcile_best_effort(inp, plan_run_root)
-    consumers = read_stage_consumer_state(plan_run_root)
     reserved_stages = _reg.list_active_stage_numbers(
         inp.project_id,
         inp.task_group,
         inp.task_id,
     )
+    snapshot = stage_targets.read_stage_lifecycle_snapshot(
+        ctx_stage_map,
+        plan_run_root,
+        reserved_stages=reserved_stages,
+    )
 
     try:
-        selected = stage_targets.resolve_implementation_stage(
-            ctx_stage_map,
-            consumers.done_stages,
-            inp.stage,
-            started_stages=consumers.started_stages,
-            reserved_stages=reserved_stages,
-        )
+        selected = snapshot.resolve_implementation_stage(inp.stage)
     except stage_targets.StageTargetError as exc:
         raise _as_implementation_stage_error(exc) from exc
 
-    concurrent_stages = sorted(reserved_stages - consumers.done_stages - {selected})
+    concurrent_stages = snapshot.concurrent_stage_numbers(
+        selected_stage=selected,
+    )
 
     if executor_worktree_status.startswith("skipped"):
         head = _git_out(inp.project_root, "rev-parse", "HEAD")
@@ -133,7 +133,7 @@ def select_and_provision_implementation_stage(
     try:
         stage_base = stage_targets.resolve_stage_base_commit(
             selected_stage,
-            consumers.done_rows,
+            snapshot.done_rows,
             anchor_base_commit=anchor,
             candidate_base=head_sha,
             project_root=Path(task_worktree_path),

package/runtime/python/okstra_ctl/report_views.py

@@ -2,11 +2,17 @@
 
 Single product, single source of truth:
 
-* ``render_html(src_md, *, run_meta)`` — deterministic self-contained
-  HTML renderer for human readers. Sections §1/§3/§4 user-actionable
-  rows (those reachable from §1 ``C-*`` IDs) get embedded ``<form>``
-  controls. §5.6 / §5.7 / §5.8 deliverable sub-sections are explicitly
-  excluded from form attachment — they are read-only deliverables.
+* ``build_report_view_model(src_md, *, run_meta)`` — deterministic
+  server-side Report View Model for human readers. It carries source digest,
+  rendered body HTML, response IDs, sidecar hints, and optional approval
+  context.
+* ``render_report_view_model(model, *, css, js)`` — self-contained HTML
+  renderer over that model. Sections §1/§3/§4 user-actionable rows (those
+  reachable from §1 ``C-*`` IDs) get embedded ``<form>`` controls. §5.6 /
+  §5.7 / §5.8 deliverable sub-sections are explicitly excluded from form
+  attachment — they are read-only deliverables.
+* ``render_html(src_md, *, run_meta)`` remains a compatibility wrapper around
+  the model builder + renderer.
 
 User responses are NEVER merged back into the original report. The HTML
 serialises a ``user-response`` markdown sidecar via ``Export user
@@ -101,34 +107,56 @@ class RunMeta:
     source_report: str  # relative path of the .md the HTML is derived from
 
 
-def render_html(
+@dataclass(frozen=True)
+class ReportViewModel:
+    run_meta: RunMeta
+    title: str
+    body_html: str
+    source_digest: str
+    response_ids: tuple[str, ...]
+    sidecar_name: str
+    sidecar_dir: str
+    approval_ctx: PlanApprovalContext | None = None
+
+
+def build_report_view_model(
     src_md: str,
     *,
     run_meta: RunMeta,
-    css: str,
-    js: str,
     approval_ctx: PlanApprovalContext | None = None,
-) -> str:
-    """Return a single self-contained HTML document for ``src_md``.
-
-    ``css`` / ``js`` are inlined verbatim. No external URLs are written
-    into the document (validator enforces this — see
-    validate-report-views.py).
-    """
-    # Compute the digest over the source MD body. The validator
-    # recomputes the same digest from the current MD and compares it to
-    # the value embedded in run-meta below.
+) -> ReportViewModel:
     digest = source_digest(src_md)
     body_md = _strip_leading_frontmatter(src_md)
     body_html, toc_headings = _markdown_to_html(body_md)
     body_html = _inject_toc(body_html, toc_headings)
-    response_ids = sorted({item.row_id for item in (parse_clarification_items(body_md) or [])})
+    response_ids = tuple(
+        sorted({item.row_id for item in (parse_clarification_items(body_md) or [])})
+    )
+    return ReportViewModel(
+        run_meta=run_meta,
+        title=f"{run_meta.task_key} — {run_meta.task_type} #{run_meta.seq}",
+        body_html=body_html,
+        source_digest=digest,
+        response_ids=response_ids,
+        sidecar_name=f"user-response-{run_meta.task_type}-{run_meta.seq}.md",
+        sidecar_dir=f"runs/{run_meta.task_type}/user-responses/",
+        approval_ctx=approval_ctx,
+    )
 
-    title = html.escape(f"{run_meta.task_key} — {run_meta.task_type} #{run_meta.seq}")
-    response_ids_json = "[" + ",".join('"' + html.escape(rid) + '"' for rid in response_ids) + "]"
-    sidecar_name = html.escape(f"user-response-{run_meta.task_type}-{run_meta.seq}.md")
-    sidecar_dir = html.escape(f"runs/{run_meta.task_type}/user-responses/")
 
+def render_report_view_model(
+    model: ReportViewModel,
+    *,
+    css: str,
+    js: str,
+) -> str:
+    title = html.escape(model.title)
+    response_ids_json = "[" + ",".join(
+        '"' + html.escape(rid) + '"' for rid in model.response_ids
+    ) + "]"
+    sidecar_name = html.escape(model.sidecar_name)
+    sidecar_dir = html.escape(model.sidecar_dir)
+    run_meta = model.run_meta
     return (
         f"<!DOCTYPE html>\n"
         f"<html lang=\"ko\">\n"
@@ -143,8 +171,8 @@ def render_html(
         f"  <div>{title}</div>\n"
         f"  <button type=\"button\" data-action=\"export-user-response\">Export user response</button>\n"
         f"</header>\n"
-        f"<main>{body_html}</main>\n"
-        f"{_plan_approval_section(approval_ctx, run_meta) if approval_ctx else ''}"
+        f"<main>{model.body_html}</main>\n"
+        f"{_plan_approval_section(model.approval_ctx, run_meta) if model.approval_ctx else ''}"
         f"<footer class=\"report-footer\">\n"
         f"  <button type=\"button\" data-action=\"export-user-response\">Export user response</button>\n"
         f"  <p class=\"user-response-hint\">Export 클릭 시 <code>{sidecar_name}</code> 가 다운로드됩니다 — "
@@ -158,7 +186,7 @@ def render_html(
         f"\"task-type\":\"{html.escape(run_meta.task_type)}\","
         f"\"seq\":\"{html.escape(run_meta.seq)}\","
         f"\"source-report\":\"{html.escape(run_meta.source_report)}\","
-        f"\"source-sha256\":\"{digest}\","
+        f"\"source-sha256\":\"{model.source_digest}\","
         f"\"response-ids\":{response_ids_json}}}"
         f"</script>\n"
         f"<script>{js}</script>\n"
@@ -167,6 +195,28 @@ def render_html(
     )
 
 
+def render_html(
+    src_md: str,
+    *,
+    run_meta: RunMeta,
+    css: str,
+    js: str,
+    approval_ctx: PlanApprovalContext | None = None,
+) -> str:
+    """Return a single self-contained HTML document for ``src_md``.
+
+    ``css`` / ``js`` are inlined verbatim. No external URLs are written
+    into the document (validator enforces this — see
+    validate-report-views.py).
+    """
+    model = build_report_view_model(
+        src_md,
+        run_meta=run_meta,
+        approval_ctx=approval_ctx,
+    )
+    return render_report_view_model(model, css=css, js=js)
+
+
 def _markdown_to_html(
     src_md: str,
 ) -> tuple[str, list[tuple[int, str, str]]]:

package/runtime/python/okstra_ctl/stage_targets.py

@@ -38,6 +38,158 @@ class FinalVerificationTarget:
     reports: list[str]
 
 
+@dataclass(frozen=True)
+class StageLifecycle:
+    stage: int
+    depends_on: list[int]
+    done: bool
+    started: bool
+    reserved: bool
+    verified_accepted: bool
+    pr_covered: bool
+    head_commit: str
+    report_path: str
+
+    def handoff_eligibility_record(self) -> dict[str, Any]:
+        reasons: list[str] = []
+        if self.pr_covered:
+            reasons.append("already-in-pr")
+        else:
+            if not self.done:
+                reasons.append("not-done")
+            if not self.verified_accepted:
+                reasons.append("not-verified-accepted")
+        return {
+            "stage": self.stage,
+            "depends_on": list(self.depends_on),
+            "eligible": not reasons,
+            "reasons": reasons,
+            "head_commit": self.head_commit,
+        }
+
+
+@dataclass(frozen=True)
+class StageLifecycleSnapshot:
+    stage_map: list[dict[str, Any]]
+    rows: list[dict[str, Any]]
+    done_rows: list[dict[str, Any]]
+    done_by_stage: dict[int, dict[str, Any]]
+    done_stages: set[int]
+    started_stages: set[int]
+    reserved_stages: set[int]
+    verified_accepted_stages: set[int]
+    pr_covered_stages: set[int]
+    lifecycles: list[StageLifecycle]
+
+    def lifecycle_for(self, stage_number: int) -> StageLifecycle:
+        for lifecycle in self.lifecycles:
+            if lifecycle.stage == stage_number:
+                return lifecycle
+        raise StageTargetError(f"stage {stage_number} not in Stage Map")
+
+    def resolve_effective_stages(
+        self,
+        requested: str,
+        budget: int = RUN_STEP_BUDGET,
+    ) -> list[int]:
+        return resolve_effective_stages(
+            self.stage_map,
+            self.done_stages,
+            requested,
+            budget=budget,
+            started_stages=self.started_stages,
+            reserved_stages=self.reserved_stages,
+        )
+
+    def resolve_implementation_stage(self, requested: str) -> int:
+        return self.resolve_effective_stages(requested)[0]
+
+    def concurrent_stage_numbers(self, *, selected_stage: int) -> list[int]:
+        return sorted(self.reserved_stages - self.done_stages - {selected_stage})
+
+    def handoff_eligibility(self) -> list[dict[str, Any]]:
+        return [
+            lifecycle.handoff_eligibility_record()
+            for lifecycle in self.lifecycles
+        ]
+
+
+def _stage_consumer_state_from_rows(rows: list[dict[str, Any]]) -> Any:
+    from .consumers import stage_consumer_state_from_rows
+
+    return stage_consumer_state_from_rows(rows)
+
+
+def stage_lifecycle_snapshot_from_state(
+    stage_map: list[dict[str, Any]],
+    consumer_state: Any,
+    *,
+    reserved_stages: set[int] | None = None,
+) -> StageLifecycleSnapshot:
+    reserved = set(reserved_stages or set())
+    lifecycles: list[StageLifecycle] = []
+    for stage in stage_map:
+        stage_number = stage["stage_number"]
+        done_row = consumer_state.done_by_stage.get(stage_number) or {}
+        lifecycles.append(StageLifecycle(
+            stage=stage_number,
+            depends_on=list(stage.get("depends_on") or []),
+            done=stage_number in consumer_state.done_stages,
+            started=stage_number in consumer_state.started_stages,
+            reserved=stage_number in reserved,
+            verified_accepted=stage_number in (
+                consumer_state.verified_accepted_stages
+            ),
+            pr_covered=stage_number in consumer_state.pr_covered_stages,
+            head_commit=str(done_row.get("head_commit") or ""),
+            report_path=str(done_row.get("report_path") or ""),
+        ))
+    return StageLifecycleSnapshot(
+        stage_map=stage_map,
+        rows=list(consumer_state.rows),
+        done_rows=list(consumer_state.done_rows),
+        done_by_stage=dict(consumer_state.done_by_stage),
+        done_stages=set(consumer_state.done_stages),
+        started_stages=set(consumer_state.started_stages),
+        reserved_stages=reserved,
+        verified_accepted_stages=set(consumer_state.verified_accepted_stages),
+        pr_covered_stages=set(consumer_state.pr_covered_stages),
+        lifecycles=lifecycles,
+    )
+
+
+def stage_lifecycle_snapshot_from_rows(
+    stage_map: list[dict[str, Any]],
+    rows: list[dict[str, Any]],
+    *,
+    reserved_stages: set[int] | None = None,
+) -> StageLifecycleSnapshot:
+    return stage_lifecycle_snapshot_from_state(
+        stage_map,
+        _stage_consumer_state_from_rows(rows),
+        reserved_stages=reserved_stages,
+    )
+
+
+def read_stage_lifecycle_snapshot(
+    stage_map: list[dict[str, Any]],
+    plan_run_root: Path,
+    *,
+    recover_from_carry: bool = False,
+    reserved_stages: set[int] | None = None,
+) -> StageLifecycleSnapshot:
+    from .consumers import read_stage_consumer_state
+
+    return stage_lifecycle_snapshot_from_state(
+        stage_map,
+        read_stage_consumer_state(
+            plan_run_root,
+            recover_from_carry=recover_from_carry,
+        ),
+        reserved_stages=reserved_stages,
+    )
+
+
 def resolve_effective_stages(
     stages: list[dict[str, Any]],
     done_stages: set[int],

package/runtime/python/okstra_ctl/wizard.py

@@ -12,6 +12,7 @@ Public surface:
 - ``next_prompt()`` - deterministic; pure read on state.
 - ``submit()``      - validate + advance.
 - ``render_args()`` - final args for ``okstra render-bundle``.
+- ``wizard_outcome()`` - final args plus persistence actions and confirmation.
 
 The skill calls these via the ``okstra wizard`` CLI subcommand; it never
 imports this module directly.
@@ -3707,6 +3708,36 @@ def confirmation_block(state: WizardState) -> str:
     return "\n".join(lines)
 
 
+def _wizard_persist_actions(state: WizardState) -> list[dict[str, str]]:
+    if state.task_type != "release-handoff":
+        return []
+    if not state.pr_template_path:
+        return []
+    if state.pr_template_scope not in ("project", "global"):
+        return []
+    return [
+        {
+            "command": "config.set",
+            "key": "pr-template-path",
+            "scope": state.pr_template_scope,
+            "value": state.pr_template_path,
+        }
+    ]
+
+
+def wizard_outcome(state: WizardState) -> dict[str, Any]:
+    """Public outcome for callers that need launch data and follow-up writes."""
+    if state.aborted:
+        raise WizardError("wizard was aborted by the user — outcome is unavailable")
+    if state.confirmed is not True:
+        raise WizardError("wizard is not complete — outcome is unavailable")
+    return {
+        "renderArgs": render_args(state),
+        "persistActions": _wizard_persist_actions(state),
+        "confirmationText": confirmation_block(state),
+    }
+
+
 # ---- File I/O helpers (used by CLI) -------------------------------------
 
 def load_state_file(path: Path) -> WizardState:
@@ -3731,6 +3762,7 @@ def _cli(argv: list[str]) -> int:
       step  --state-file PATH (--answer VALUE | --no-submit)
       render-args --state-file PATH
       confirmation --state-file PATH
+      outcome --state-file PATH
     """
     import argparse
 
@@ -3759,6 +3791,9 @@ def _cli(argv: list[str]) -> int:
     p_conf = sub.add_parser("confirmation")
     p_conf.add_argument("--state-file", required=True)
 
+    p_outcome = sub.add_parser("outcome")
+    p_outcome.add_argument("--state-file", required=True)
+
     args = parser.parse_args(argv)
     state_path = Path(args.state_file)
 
@@ -3836,6 +3871,18 @@ def _cli(argv: list[str]) -> int:
                          ensure_ascii=False, indent=2))
         return 0
 
+    if args.cmd == "outcome":
+        state = load_state_file(state_path)
+        try:
+            out = wizard_outcome(state)
+        except WizardError as exc:
+            print(json.dumps({"ok": False, "error": str(exc)},
+                             ensure_ascii=False, indent=2))
+            return 0
+        print(json.dumps({"ok": True, "outcome": out},
+                         ensure_ascii=False, indent=2))
+        return 0
+
     return 2
 
 

package/runtime/python/okstra_project/__init__.py

@@ -38,6 +38,7 @@ from .state import (
     resolve_task_identity,
     resolve_task_reference,
     slugify,
+    task_read_side_snapshot,
 )
 
 __all__ = [
@@ -64,6 +65,7 @@ __all__ = [
     "resolve_task_identity",
     "resolve_task_reference",
     "slugify",
+    "task_read_side_snapshot",
     "tasks_root",
     "upsert_project_json",
 ]

package/runtime/python/okstra_project/state.py

@@ -37,6 +37,10 @@ from .dirs import (
 class StateError(Exception):
     """state file 읽기/파싱 실패 — 호출자가 surface 해야 할 오류."""
 
+    def __init__(self, message: str, *, stage: Optional[str] = None):
+        super().__init__(message)
+        self.stage = stage
+
 
 def _load_json(path: Path) -> Optional[dict]:
     if not path.is_file():
@@ -268,10 +272,16 @@ def resolve_task_identity(project_root: Path, task_key: str) -> dict:
     """
     task_root = find_task_root(project_root, task_key)
     if task_root is None:
-        raise StateError(f"task root not found for {task_key!r}")
+        raise StateError(
+            f"task root not found for {task_key!r}",
+            stage="task_root_missing",
+        )
     manifest = read_task_manifest(task_root)
     if manifest is None:
-        raise StateError(f"task-manifest.json missing under {task_root}")
+        raise StateError(
+            f"task-manifest.json missing under {task_root}",
+            stage="manifest_missing",
+        )
     workflow = manifest.get("workflow") or {}
     if not isinstance(workflow, dict):
         workflow = {}
@@ -292,3 +302,35 @@ def resolve_task_identity(project_root: Path, task_key: str) -> dict:
         "taskBriefPath": manifest.get("taskBriefPath") or "",
         "manifest": manifest,
     }
+
+
+def task_read_side_snapshot(project_root: Path, task_key: str) -> dict:
+    """task-show / inspect 용 curated task 상태 view 를 반환한다.
+
+    resolve_task_identity 가 내부 raw manifest 를 들고 있지만, 이 accessor 는
+    caller 에게 manifest shape 를 노출하지 않는 read-side 계약이다.
+    """
+    identity = resolve_task_identity(project_root, task_key)
+    manifest = identity["manifest"]
+    workflow = manifest.get("workflow")
+    if not isinstance(workflow, dict):
+        workflow = {}
+    return {
+        "projectRoot": identity["projectRoot"],
+        "taskKey": manifest.get("taskKey"),
+        "taskType": manifest.get("taskType"),
+        "taskRoot": identity["taskRoot"],
+        "taskBriefPath": manifest.get("taskBriefPath"),
+        "workflow": {
+            "currentPhase": workflow.get("currentPhase"),
+            "currentPhaseState": workflow.get("currentPhaseState"),
+            "lastCompletedPhase": workflow.get("lastCompletedPhase"),
+            "nextRecommendedPhase": workflow.get("nextRecommendedPhase"),
+            "routingStatus": workflow.get("routingStatus"),
+            "phaseStates": workflow.get("phaseStates"),
+        },
+        "resultContract": manifest.get("resultContract"),
+        "artifacts": manifest.get("artifacts"),
+        "modelAssignments": manifest.get("modelAssignments"),
+        "latestRunPath": manifest.get("latestRunPath"),
+    }

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

@@ -145,13 +145,30 @@ Output: `{ok: true, text: "선택 확인:\n  task-type     : ...\n  ..."}`. Prin
 
 ## Step 5: Render the task bundle
 
-When `next.kind == "done"`, fetch the final args:
+When `next.kind == "done"`, fetch the public wizard outcome:
 
 ```bash
-okstra wizard render-args --state-file /var/folders/.../okstra-wizard.AbCd.json
+okstra wizard outcome --state-file /var/folders/.../okstra-wizard.AbCd.json
 ```
 
-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).
+Output: `{ok: true, outcome: {renderArgs: {...}, persistActions: [...], confirmationText: "..."}}`.
+
+Run every `outcome.persistActions[]` entry BEFORE `render-bundle`. The only supported action is:
+
+```json
+{"command":"config.set","key":"pr-template-path","scope":"project|global","value":"<path>"}
+```
+
+Execute the matching command for `scope`:
+
+```bash
+okstra config set pr-template-path "<value>" --scope project
+okstra config set pr-template-path "<value>" --scope global
+```
+
+If an action has an unknown `command`, `key`, or `scope`, stop and report the wizard output instead of inventing a command.
+
+Build the `okstra render-bundle` invocation from `outcome.renderArgs`, passing each key as `--<key>` and the value verbatim (including empty strings — they are intentional `use phase default` markers).
 
 **Empty-value rule (same as Step 3)**: every flag whose value is the empty string MUST still be passed explicitly as `--<key> ""`. For example: `--workers ""`, `--directive ""`, `--related-tasks ""`. Omitting the flag is forbidden — `render-bundle` distinguishes "flag absent" from "flag present with empty value", and the wizard's intent is always the latter.
 
@@ -295,20 +312,7 @@ stale-SHA 재조정(git-reconcile 분기)을 띄우면, **그 stage 에서 연
 
 ## Persisting the PR template scope (release-handoff)
 
-When `wizard render-args` returns a non-empty `pr-template-path` AND the state has `pr_template_scope == "project"` or `"global"`, run the matching config command BEFORE `render-bundle`:
-
-```bash
-# project scope
-okstra config set pr-template-path "<path>" --scope project
-# global scope (must be absolute or ~/-prefixed)
-okstra config set pr-template-path "<path>" --scope global
-```
-
-The scope is held in the wizard state but is not yet exposed by any `okstra wizard` subcommand. Until the subcommand below ships, 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`. Do not shell out (`python3 -c`, `jq`, etc.); the literal-token Bash rule rejects them.
-
-## Out-of-scope backlog
-
-- **`okstra wizard pr-template-scope --state-file PATH`**: add a thin subcommand to `scripts/okstra_ctl/wizard.py` that prints `{ok: true, scope: "once" | "project" | "global"}` so this skill can drop the `Read`-the-raw-state-file detour. The subcommand should reuse the existing `load_state_file` path; no schema changes required.
+Do not read the wizard state file directly. `okstra wizard outcome` exposes any release-handoff PR template write as `outcome.persistActions[]`; execute those actions before `render-bundle`.
 
 ## Concurrency