okstra 0.94.0 → 0.96.0

package/docs/superpowers/specs/2026-06-19-okstra-inspect-recap-facet-design.md

@@ -0,0 +1,96 @@
+# okstra-inspect `recap` facet 설계 — task-id 전/후 요약 + 자유 Q&A
+
+> 작성: 2026-06-19 · 상태: 설계 승인 대기
+
+## 1. 배경 / 문제
+
+okstra 는 작업을 `task-id` 단위로 나누고, task-id 하나에 충분한 맥락이 이미 축적된다:
+
+- `task-manifest.json` 의 `workflow.phaseStates` 등 현재 시점 스냅샷 ([scripts/okstra_ctl/render.py:1010](../../../scripts/okstra_ctl/render.py))
+- `history/timeline.json` 의 `runs[]` — 각 run 기록 시점의 `workflowSnapshot`(`currentPhase / currentPhaseState / lastCompletedPhase / nextRecommendedPhase`)이 append-only 로 누적 ([render.py:1388](../../../scripts/okstra_ctl/render.py))
+- 각 phase 의 `runs/<task-type>/reports/final-report-*.md` ([paths.py:180](../../../scripts/okstra_ctl/paths.py))
+
+읽기 기능은 `okstra-inspect` 스킬에 7개 facet(status / history / report / time / logs / cost / errors)이 있으나 전부 **정형 출력**이다. `report` facet 은 final-report **원문을 그대로 보여줄 뿐** 내용 요약·질의는 하지 않는다 ([skills/okstra-inspect/SKILL.md:285](../../../skills/okstra-inspect/SKILL.md)).
+
+빠진 것: **"이 task-id 에 쌓인 맥락 위에서 처리 전/후를 요약하고, 그 작업에 대해 자유롭게 묻고 답하는"** 읽기 기능. 현재 task-id 단위 자유 Q&A 는 존재하지 않는다 — `task-root/qa/` 는 이름과 달리 구현 검증 산출물 저장소이고([paths.py:127](../../../scripts/okstra_ctl/paths.py)), `clarification` 은 final-report 의 정해진 섹션을 다음 run 으로 carry-in 하는 구조화 플로우라 임의 질문과 다르다.
+
+목표: task-id 단위 **전/후 요약 + 자유 Q&A** 를 담는 8번째 facet `recap` 추가.
+
+## 2. 범위 / 결정 (brainstorming 합의)
+
+| 항목 | 결정 |
+|---|---|
+| 전달 형태 | `okstra-inspect` 의 **8번째 facet `recap`** — 기존 7개와 동일한 dispatch·task-key 해소 경로 재사용 |
+| 동작 | (a) 진입 시 **전/후 요약** 기본 출력 + (b) 이어지는 **자유 Q&A 루프** |
+| 요약 깊이 | **run 단위 변화 추적** — `timeline.runs[].workflowSnapshot` 을 인접 run 끼리 비교 |
+| 맥락 범위 | **2-모드**: 기본 = `.okstra/` 서브트리만 / 코드 모드 = 사용자가 명시 요청할 때만 해당 task worktree 의 `git diff`·`git log` 추가 |
+| 결과 저장 | **`.okstra/` 안에 저장** — `<task-root>/recap/recap-log.jsonl` append-only |
+| 저장 경유 | python 엔트리포인트 `okstra recap record`(skill 이 JSON 을 손으로 쓰지 않음) |
+| CLI 노출 | `okstra recap <assemble\|record>` — Node 래퍼(`src/recap.mjs` + cli-registry) → python. 다른 read facet(`error-report`/`context-cost`)과 동일하게 skill 은 항상 `okstra <verb>` 를 호출하고 PYTHONPATH 를 직접 다루지 않음 |
+
+**비목표**: `okstra.sh` 인터랙티브 wizard 에 `recap` 노출(읽기 facet 이라 불필요) · 기존 산출물 변형(recap 은 자기 로그만 append) · clarification carry-in 플로우 변경.
+
+## 3. 설계
+
+### 3.1 경로 SSOT 확장
+
+`compute_run_paths` 가 레이아웃 단일 출처이므로 여기에 recap 경로를 추가한다 ([paths.py:87](../../../scripts/okstra_ctl/paths.py)).
+
+```
+<task-root>/recap/
+  recap-log.jsonl        # append-only Q&A·요약 로그
+```
+
+- task-manifest 에 포인터가 필요하면 `recapLogPath` 를 `render_task_manifest` payload 에 추가 ([render.py:968](../../../scripts/okstra_ctl/render.py)). 1차 구현에서는 경로가 결정론적(task-root 상대)이므로 포인터는 선택.
+
+### 3.2 전/후 요약 (run 단위 변화 추적)
+
+facet 진입 시 기본 출력. 맥락 소스는 전부 기존 산출물이며 **신규 측정 없음**:
+
+1. `history/timeline.json` 의 `runs[]` 를 시간순으로 읽어, **인접 두 run 의 `workflowSnapshot` 을 비교** → "이 run 전/후로 `currentPhase` / `lastCompletedPhase` / `nextRecommendedPhase` 가 어떻게 바뀌었나"를 run 단위로 재구성.
+2. 각 run 의 `reportPath`(final-report) 핵심 섹션과 `task-manifest.workflow.phaseStates` 로 "무엇을 했나"를 보강.
+3. 출력: run 별 전→후 phase 전이 + 한 줄 요약 타임라인.
+
+별도의 "before/after" 전용 레코드는 없으므로 인접 snapshot 비교가 1차 소스다. `team-state.phaseTimeline`(lead operating-phase 타임스탬프)은 존재하면 보조로만 쓰고 의존하지 않는다(collector 버전·Phase 7 도달 여부에 따라 부재 가능).
+
+### 3.3 자유 Q&A 루프
+
+요약 출력 뒤 사용자의 임의 질문을 받아, §3.2 의 산출물 위에서 답한다.
+
+- 모든 사실 주장은 `.okstra` 파일 `path:line` 인용을 동반(검증 가능).
+- 후속 질문 반복. 각 질문·답변은 §3.5 로 기록.
+
+### 3.4 2-모드 (맥락 범위)
+
+- **기본 모드** — `.okstra/` 서브트리만 읽음. artifact-home 규칙 준수, 모든 인용이 `.okstra` 파일로 귀결.
+- **코드 모드** — 사용자가 명시적으로 "코드 변경까지 봐줘" 류로 요청할 때만, 해당 task 의 worktree/브랜치 `git diff`·`git log` 를 추가로 읽어 코드 레벨로 답. **진입 시 자동 확장 금지** — 사용자의 verbatim 요청이 있을 때만.
+
+### 3.5 결과 저장 (`recap-log.jsonl` append-only)
+
+- 형식: 줄당 한 엔트리
+  ```json
+  {"ts": "<ISO8601>", "kind": "summary|qa", "mode": "artifact|code",
+   "question": "<질문 또는 빈 문자열>", "answerSummary": "<요약>", "citations": ["path:line", ...]}
+  ```
+  summary 엔트리처럼 질문이 없으면 `question` 은 `null` 이 아니라 빈 문자열 `""` 로 저장한다(타입 일관성).
+- **append-only** 이므로 중복 제거 로직 불필요.
+- 쓰기는 **python 엔트리포인트 `okstra recap record` 서브커맨드** 경유 — skill 이 JSON 을 직접 작성하지 않음(단일 참조점 규칙; errors facet 이 .md 리포트를 산출하는 선례와 동일 결).
+- recap 은 `recap-log.jsonl` 만 append 하고 **다른 산출물은 불변**. status facet 외 "read-only" 철학을 깨는 유일한 지점이므로 facet 문서에 이 경계를 명시.
+
+## 4. 영향 범위 (수정 파일)
+
+| 파일 | 변경 |
+|---|---|
+| [scripts/okstra_ctl/paths.py](../../../scripts/okstra_ctl/paths.py) | `compute_run_paths` 에 `recap/` + `recap-log.jsonl` 경로 추가 |
+| `scripts/okstra_ctl/recap.py` (신규) | `assemble`(run 간 전이 조립) + `record`(append 1줄) 서브커맨드 |
+| `src/recap.mjs` (신규) + [src/cli-registry.mjs](../../../src/cli-registry.mjs) | `okstra recap` Node 래퍼 + introspection 카테고리 등록 |
+| [skills/okstra-inspect/SKILL.md](../../../skills/okstra-inspect/SKILL.md) | facet 테이블에 `recap` 등록 + recap 섹션(요약/Q&A/2-모드/저장 경계) |
+| [docs/kr/architecture.md](../../../docs/kr/architecture.md) | task-root 트리에 `recap/` 추가 |
+| 빌드 | `npm run build` 로 runtime 동기화 |
+
+## 5. 검증
+
+- `paths.py` recap 경로: 기존 `compute_task_paths` 테스트 패턴에 recap 경로 assert 추가(`tests/`).
+- `recap record` append: 빈 로그 → 1줄 → 2줄 append 단위 테스트.
+- facet 동작(요약·Q&A·2-모드)은 skill-markdown 주도라 자동 단위 테스트 대상이 아님 → e2e 또는 수동 스모크(`okstra recap <task-id>`)로 확인.
+- 정형 검증 불가한 "요약 품질"은 spec 의 범위 밖(휴리스틱).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.94.0",
+  "version": "0.96.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.94.0",
-  "builtAt": "2026-06-18T18:35:57.621Z",
+  "package": "0.96.0",
+  "builtAt": "2026-06-19T14:40:32.132Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/antigravity-worker.md

@@ -21,7 +21,7 @@ color: green
 tools: ["Bash", "BashOutput", "KillShell", "Read", "Write", "Glob", "Grep"]
 ---
 
-You are a Antigravity worker agent. Your job is to execute the Google Antigravity CLI and return the analysis result.
+Execute the Google Antigravity CLI and return the analysis result.
 
 ## CLI Command
 

package/runtime/agents/workers/claude-worker.md

@@ -21,7 +21,7 @@ color: blue
 tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "TodoWrite", "WebFetch", "WebSearch"]
 ---
 
-You are a Claude worker agent for okstra cross-verification. You share an **identical core responsibility** with the Codex and Antigravity workers: cover every brief question across feasibility, requirement interpretation, hidden assumptions, alternatives, and execution risk in sections 1–5 of the worker output. Cross-verification only triangulates if all three workers answer the same questions against the same brief.
+You share an **identical core responsibility** with the Codex and Antigravity workers: cover every brief question across feasibility, requirement interpretation, hidden assumptions, alternatives, and execution risk in sections 1–5 of the worker output. Cross-verification only triangulates if all three workers answer the same questions against the same brief.
 
 Your specialization lens — **broad reasoning depth, hidden-assumption surfacing, execution-risk decomposition** — is the only content that belongs in optional Section 6 (additive, not subject to convergence). Do NOT let the lens narrow sections 1–5: a Claude-only "Findings" populated solely with assumption-class items is a contract violation.
 

package/runtime/agents/workers/codex-worker.md

@@ -21,7 +21,7 @@ color: cyan
 tools: ["Bash", "BashOutput", "KillShell", "Read", "Write", "Glob", "Grep"]
 ---
 
-You are a Codex worker agent. Your job is to execute the OpenAI Codex CLI and return the analysis result.
+Execute the OpenAI Codex CLI and return the analysis result.
 
 ## CLI Command
 

package/runtime/agents/workers/report-writer-worker.md

@@ -14,7 +14,7 @@ model: inherit
 tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "TodoWrite", "WebFetch", "WebSearch"]
 ---
 
-You are the `Report writer worker` for okstra cross-verification. Your sole responsibility is to **author the final-report data.json** (the JSON SSOT) at the assigned `Result Path`, plus an audit sidecar. You are NOT an analysis worker — you do not produce independent findings, you do not vote in convergence, and you do not re-do the workers' analysis.
+**Author the final-report data.json** (the JSON SSOT) at the assigned `Result Path`, plus an audit sidecar — that is the `Report writer worker`'s sole responsibility for okstra cross-verification. You are NOT an analysis worker — you do not produce independent findings, you do not vote in convergence, and you do not re-do the workers' analysis.
 
 - The `**Report Language:**` header in your dispatch prompt is already
   resolved to `en` or `ko` by the lead. Copy it verbatim into

package/runtime/prompts/wizard/prompts.ko.json

@@ -167,20 +167,6 @@
         "__free_input__": "직접 입력"
       }
     },
-    "branch_confirm": {
-      "label": "{summary}",
-      "labels": {
-        "new": "새 브랜치 `{branch}` 를 base-ref `{base_ref}` 에서 분기해 `{task_key}` 디렉터리(`{path}`)에 체크아웃합니다 — 진행할까요?",
-        "reuse": "기존 `{task_key}` 디렉터리(`{path}`, 브랜치 `{branch}`)에서 이어서 진행합니다 — 진행할까요?",
-        "in_worktree": "현재 worktree(`{path}`)에서 그대로 진행합니다(이미 non-main worktree) — 진행할까요?",
-        "not_git": "git 저장소가 아니므로 `{path}` 에서 직접 진행합니다 — 진행할까요?",
-        "impl_stage_new": "implementation 은 stage 격리로 동작합니다 — stage {stage} worktree 를 `{path}` 에 브랜치 `{branch}` 로 새로 만들고, base 커밋은 의존 stage 의 done 커밋 기준으로 run 준비 시점에 해소됩니다 — 진행할까요?",
-        "impl_stage_reuse": "기존 stage {stage} worktree(`{path}`, 브랜치 `{branch}`)에서 이어서 진행합니다 — 진행할까요?",
-        "impl_stage_auto": "implementation 은 stage 격리로 동작합니다 — stage 번호는 run 준비 시점에 자동 선택되고, `{task_key}` 디렉터리(`{path}`) 아래 `stage-<N>/` worktree 가 새로 만들어지거나 재사용됩니다 — 진행할까요?"
-      },
-      "options": { "proceed": "진행", "edit": "base-ref 다시 고르기", "abort": "중단" },
-      "echo_template": "branch-confirm: {value}"
-    },
     "fix_cycle_confirm": {
       "label": "이 task 는 release-handoff 까지 완료된 task 입니다. 이번 재진입을 기존 산출물에 대한 버그 픽스 사이클로 기록할까요?",
       "options": {
@@ -429,7 +415,8 @@
       "echo_template": "confirm: {value}",
       "options": {
         "proceed": "Proceed",
-        "edit": "Edit"
+        "edit": "Edit",
+        "abort": "중단"
       }
     },
     "edit_target": {
@@ -442,6 +429,13 @@
     "workers_implementation_default": "  workers       : (프로필 기본 — executor + verifier 2 + report-writer)",
     "base_ref_stage_isolated": "  base-ref      : (stage 격리 — 의존 stage 기준으로 run 준비 시점에 자동 해소)",
     "base_ref_reuse_task_dir": "  base-ref      : (기존 `{task_key}` 디렉터리 재사용 — 최초 base 유지)",
+    "worktree_new": "  worktree      : 새 브랜치 `{branch}` (base-ref `{base_ref}`) → `{path}`",
+    "worktree_reuse": "  worktree      : 기존 디렉터리 재사용 — `{path}` (브랜치 `{branch}`)",
+    "worktree_in_worktree": "  worktree      : 현재 worktree 그대로 — `{path}`",
+    "worktree_not_git": "  worktree      : git 저장소 아님 — `{path}` 에서 직접 진행",
+    "worktree_impl_new": "  worktree      : stage {stage} 새 worktree `{path}` (브랜치 `{branch}`, base 는 run 준비 시 해소)",
+    "worktree_impl_reuse": "  worktree      : 기존 stage {stage} worktree `{path}` (브랜치 `{branch}`)",
+    "worktree_impl_auto": "  worktree      : stage 자동 선택 — `{path}` 아래 stage-<N>/ worktree 생성/재사용",
     "stage_whole_task": "전체 task",
     "handoff_scope_whole_task": "전체 task (whole-task 검증 기반)",
     "handoff_scope_stage_group": "stage-group ({stages})"

package/runtime/python/okstra_ctl/paths.py

@@ -128,6 +128,8 @@ def compute_run_paths(
     runs_dir = task_root / "runs"
     history_dir = task_root / "history"
     timeline_file = history_dir / "timeline.json"
+    recap_dir = task_root / "recap"
+    recap_log = recap_dir / "recap-log.jsonl"
 
     run_dir = runs_dir / task_type_segment
     # Stage isolation: each stage's run artifacts live in a dedicated
@@ -247,6 +249,8 @@ def compute_run_paths(
         "RUNS_DIR": str(runs_dir),
         "HISTORY_DIR": str(history_dir),
         "TIMELINE_PATH": str(timeline_file),
+        "RECAP_DIR": str(recap_dir),
+        "RECAP_LOG_PATH": str(recap_log),
         "RUN_DIR": str(run_dir),
         "RUN_STAGE": "" if stage is None else str(int(stage)),
         "RUN_MANIFESTS_DIR": str(run_manifests),
@@ -312,6 +316,8 @@ def compute_run_paths(
         ("RUNS_RELATIVE_PATH", runs_dir),
         ("HISTORY_RELATIVE_PATH", history_dir),
         ("TIMELINE_RELATIVE_PATH", timeline_file),
+        ("RECAP_DIR_RELATIVE_PATH", recap_dir),
+        ("RECAP_LOG_RELATIVE_PATH", recap_log),
         ("RUN_DIR_RELATIVE_PATH", run_dir),
         ("RUN_MANIFESTS_RELATIVE_PATH", run_manifests),
         ("RUN_STATE_RELATIVE_PATH", run_state),

package/runtime/python/okstra_ctl/recap.py

@@ -0,0 +1,126 @@
+"""Read-side recap for a task: assemble run-to-run phase transitions and
+append a recap Q&A log. Mutates only <task-root>/recap/recap-log.jsonl;
+never touches task-manifest / catalog / timeline.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import sys
+from pathlib import Path
+
+from okstra_ctl.task_target import resolve_task_root, project_rel
+
+
+def _load_timeline(task_root: Path) -> list[dict]:
+    path = task_root / "history" / "timeline.json"
+    if not path.is_file():
+        return []
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return []
+    runs = data.get("runs", [])
+    return runs if isinstance(runs, list) else []
+
+
+def _task_key(task_root: Path) -> str:
+    path = task_root / "task-manifest.json"
+    if not path.is_file():
+        return ""
+    try:
+        return json.loads(path.read_text(encoding="utf-8")).get("taskKey", "")
+    except Exception:
+        return ""
+
+
+def assemble_recap(task_root: Path, project_root: Path) -> dict:
+    runs = _load_timeline(task_root)
+    transitions = []
+    prev_phase = ""
+    latest_states: dict = {}
+    for idx, run in enumerate(runs):
+        snap = run.get("workflowSnapshot", {}) if isinstance(run, dict) else {}
+        cur = snap.get("currentPhase", "")
+        transitions.append({
+            "index": idx,
+            "runTimestamp": run.get("runTimestamp", ""),
+            "taskType": run.get("taskType", ""),
+            "status": run.get("status", ""),
+            "fromPhase": prev_phase,
+            "toPhase": cur,
+            "lastCompletedPhase": snap.get("lastCompletedPhase", ""),
+            "nextRecommendedPhase": snap.get("nextRecommendedPhase", ""),
+            "reportPath": run.get("reportPath", ""),
+        })
+        prev_phase = cur
+        latest_states = snap.get("phaseStates", {}) or latest_states
+    return {
+        "taskKey": _task_key(task_root),
+        "runCount": len(runs),
+        "transitions": transitions,
+        "latestPhaseStates": latest_states,
+    }
+
+
+def append_recap_entry(task_root, project_root, *, kind, mode, question,
+                       answer_summary, citations, now) -> dict:
+    recap_dir = task_root / "recap"
+    recap_dir.mkdir(parents=True, exist_ok=True)
+    log_path = recap_dir / "recap-log.jsonl"
+    entry = {
+        "ts": now.isoformat(),
+        "kind": kind,
+        "mode": mode,
+        "question": question,
+        "answerSummary": answer_summary,
+        "citations": list(citations),
+    }
+    with log_path.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    return {"logPath": project_rel(log_path, project_root), "entry": entry}
+
+
+def _add_common(sp) -> None:
+    # skill 이 쓰는 `<verb> <target> --project-root <root>` 형태를 받으려면
+    # 공통 옵션을 부모가 아닌 각 서브파서에 등록해야 한다.
+    sp.add_argument("--project-root", default="")
+    sp.add_argument("--cwd", default=".")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="okstra recap")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_asm = sub.add_parser("assemble", help="assemble run-to-run phase transitions")
+    p_asm.add_argument("target", help="task root path or task-key")
+    _add_common(p_asm)
+
+    p_rec = sub.add_parser("record", help="append a recap Q&A/summary log entry")
+    p_rec.add_argument("target", help="task root path or task-key")
+    _add_common(p_rec)
+    p_rec.add_argument("--kind", choices=["summary", "qa"], required=True)
+    p_rec.add_argument("--mode", choices=["artifact", "code"], required=True)
+    p_rec.add_argument("--question", default="")
+    p_rec.add_argument("--answer", required=True)
+    p_rec.add_argument("--citation", action="append", default=[])
+
+    args = parser.parse_args(argv)
+    task_root, project_root = resolve_task_root(
+        args.target, args.project_root, args.cwd)
+
+    if args.command == "assemble":
+        result = assemble_recap(task_root, project_root)
+    else:
+        result = append_recap_entry(
+            task_root, project_root, kind=args.kind, mode=args.mode,
+            question=args.question, answer_summary=args.answer,
+            citations=args.citation,
+            now=dt.datetime.now(dt.timezone.utc))
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/task_target.py

@@ -7,7 +7,12 @@ from __future__ import annotations
 
 from pathlib import Path
 
-from okstra_project import ResolverError, find_task_root, resolve_project_root
+from okstra_project import (
+    ResolverError,
+    StateError,
+    find_task_root,
+    resolve_project_root,
+)
 
 
 def resolve_task_root(target: str, project_root: str, cwd: str) -> tuple[Path, Path]:
@@ -23,7 +28,13 @@ def resolve_task_root(target: str, project_root: str, cwd: str) -> tuple[Path, P
     except ResolverError as exc:
         raise SystemExit(f"project root resolution failed: {exc}") from exc
 
-    task_root = find_task_root(resolved_project, target)
+    try:
+        task_root = find_task_root(resolved_project, target)
+    except StateError as exc:
+        raise SystemExit(
+            f"target is neither an existing path nor a valid task-key: "
+            f"{target!r} ({exc})"
+        ) from exc
     if task_root is None:
         raise SystemExit(f"no task root for task key: {target}")
     return task_root.resolve(), resolved_project

package/runtime/python/okstra_ctl/wizard.py

@@ -287,7 +287,6 @@ S_PR_TEMPLATE_PICK = "pr_template_pick"
 S_PR_TEMPLATE = "pr_template"
 S_PR_TEMPLATE_SCOPE = "pr_template_scope"
 S_FIX_CYCLE_CONFIRM = "fix_cycle_confirm"
-S_BRANCH_CONFIRM = "branch_confirm"
 S_CONFIRM = "confirm"
 S_EDIT_TARGET = "edit_target"
 S_DONE = "done"
@@ -402,7 +401,6 @@ class WizardState:
     # confirm / edit
     # "" | "yes" | "no" — done(release-handoff) task 재진입의 fix-cycle 기록 여부
     fix_cycle: str = ""
-    branch_confirmed: Optional[bool] = None
     confirmed: Optional[bool] = None
     edit_target: str = ""
     # terminal: user picked 중단 — no further prompt ever applies
@@ -905,7 +903,9 @@ def _base_ref_ready(state: WizardState) -> bool:
     return not _base_ref_required(state) or S_BASE_REF_PICK in state.answered
 
 
-def _branch_confirm_required(state: WizardState) -> bool:
+def _worktree_preview_required(state: WizardState) -> bool:
+    """final-verification 은 stage worktree 를 읽기 전용으로 재사용하므로
+    별도 worktree 미리보기 줄을 confirmation 블록에 넣지 않는다."""
     return state.task_type != "final-verification"
 
 
@@ -2674,93 +2674,54 @@ def _submit_fix_cycle_confirm(state: WizardState, value: str) -> Optional[str]:
     return f"fix-cycle: {v}"
 
 
-def _build_branch_confirm(state: WizardState) -> Prompt:
+def _worktree_preview_line(state: WizardState) -> Optional[str]:
+    """confirm 직전 요약 블록에 넣을 worktree 미리보기 한 줄.
+    final-verification 은 stage worktree 를 읽기 전용 재사용하므로 None."""
+    if not _worktree_preview_required(state):
+        return None
     if state.task_type == "implementation":
-        return _build_branch_confirm_impl_stage(state)
+        return _worktree_preview_line_impl(state)
     decision = preview_worktree_decision(
         project_root=Path(state.project_root),
         project_id=state.project_id,
         task_group_segment=state.task_group,
         task_id_segment=state.task_id,
         # okstra-run 경로는 --work-category 를 넘기지 않으므로 provision 도 ""(→ "task-" prefix)로
-        # 브랜치를 만든다. 이 단계에서 미리보기 브랜치명은 실제 생성 브랜치와 정확히 일치한다.
+        # 브랜치를 만든다. 이 미리보기 브랜치명은 실제 생성 브랜치와 정확히 일치한다.
         work_category="",
         base_ref=state.base_ref,
     )
     key = {
-        "new": "new", "reused": "reuse",
-        "skipped-in-worktree": "in_worktree", "skipped-not-git": "not_git",
+        "new": "worktree_new", "reused": "worktree_reuse",
+        "skipped-in-worktree": "worktree_in_worktree",
+        "skipped-not-git": "worktree_not_git",
     }[decision.status]
-    # Fetch raw step data first so we can compute the label before calling _p.
-    raw = _load_wizard_root(state.workspace_root)["steps"]["branch_confirm"]
-    label = raw["labels"][key].format(
-        branch=decision.branch or "(none)",
-        base_ref=decision.base_ref or "(HEAD)",
-        path=decision.path,
-        task_key=f"{state.task_group}/{state.task_id}",
-    )
-    # Pass the computed label as `summary` so _p's placeholder interpolation works.
-    t = _p(state.workspace_root, "branch_confirm", summary=label)
-    opts = t["options"]
-    options = [_opt("proceed", opts["proceed"])]
-    if decision.status == "new":
-        options.append(_opt("edit", opts["edit"]))
-    options.append(_opt("abort", opts["abort"]))
-    return Prompt(step=S_BRANCH_CONFIRM, kind="pick", label=label,
-                  options=options, echo_template=t["echo_template"])
+    return _msg(state.workspace_root, "confirmation", key,
+                branch=decision.branch or "(none)",
+                base_ref=decision.base_ref or "(HEAD)",
+                path=str(decision.path))
 
 
-def _build_branch_confirm_impl_stage(state: WizardState) -> Prompt:
+def _worktree_preview_line_impl(state: WizardState) -> str:
     """implementation 은 stage 격리로 동작하므로 task-key 디렉터리가 아니라
     이번 run 이 실제로 사용할 stage worktree 관점으로 미리보기를 보여준다."""
-    raw = _load_wizard_root(state.workspace_root)["steps"]["branch_confirm"]
-    task_key = f"{state.task_group}/{state.task_id}"
     stage = (state.selected_stage or "auto").strip()
     if stage == "auto":
         parent_dir = compute_worktree_path(
             project_id=state.project_id, task_group_segment=state.task_group,
             task_id_segment=state.task_id,
         )
-        label = raw["labels"]["impl_stage_auto"].format(
-            task_key=task_key, path=str(parent_dir),
-        )
-        decision_status = "new"
-    else:
-        decision = preview_stage_worktree_decision(
-            project_id=state.project_id, task_group_segment=state.task_group,
-            task_id_segment=state.task_id, work_category="",
-            stage_number=int(stage),
-        )
-        key = "impl_stage_reuse" if decision.status == "reused" else "impl_stage_new"
-        label = raw["labels"][key].format(
-            stage=stage, path=decision.path, branch=decision.branch,
-            task_key=task_key,
-        )
-        decision_status = decision.status
-    t = _p(state.workspace_root, "branch_confirm", summary=label)
-    opts = t["options"]
-    options = [_opt("proceed", opts["proceed"])]
-    if decision_status == "new" and _base_ref_required(state):
-        options.append(_opt("edit", opts["edit"]))
-    options.append(_opt("abort", opts["abort"]))
-    return Prompt(step=S_BRANCH_CONFIRM, kind="pick", label=label,
-                  options=options, echo_template=t["echo_template"])
-
-
-def _submit_branch_confirm(state: WizardState, value: str) -> Optional[str]:
-    if value == "edit":
-        _reset_from(state, S_BASE_REF_PICK)
-        state.branch_confirmed = None
-        return "branch-confirm: edit"
-    if value == "abort":
-        state.aborted = True
-        return "branch-confirm: abort"
-    if value != "proceed":
-        raise WizardError(
-            f"expected 'proceed' / 'edit' / 'abort', got: {value!r}"
-        )
-    state.branch_confirmed = True
-    return "branch-confirm: proceed"
+        return _msg(state.workspace_root, "confirmation", "worktree_impl_auto",
+                    path=str(parent_dir))
+    decision = preview_stage_worktree_decision(
+        project_id=state.project_id, task_group_segment=state.task_group,
+        task_id_segment=state.task_id, work_category="",
+        stage_number=int(stage),
+    )
+    key = ("worktree_impl_reuse" if decision.status == "reused"
+           else "worktree_impl_new")
+    return _msg(state.workspace_root, "confirmation", key,
+                stage=stage, path=str(decision.path), branch=decision.branch)
 
 
 def _build_confirm(state: WizardState) -> Prompt:
@@ -2774,8 +2735,13 @@ def _build_confirm(state: WizardState) -> Prompt:
 
 
 def _submit_confirm(state: WizardState, value: str) -> Optional[str]:
+    if value == "abort":
+        state.aborted = True
+        return "confirm: abort"
     if value not in ("proceed", "edit"):
-        raise WizardError(f"expected 'proceed' or 'edit', got: {value!r}")
+        raise WizardError(
+            f"expected 'proceed' / 'edit' / 'abort', got: {value!r}"
+        )
     state.confirmed = value == "proceed"
     return f"confirm: {value}"
 
@@ -2785,7 +2751,7 @@ def _build_edit_target(state: WizardState) -> Prompt:
     # offer every step that has been answered.
     options: list[Option] = []
     for sid in state.answered:
-        if sid in (S_BRANCH_CONFIRM, S_CONFIRM, S_EDIT_TARGET):
+        if sid in (S_CONFIRM, S_EDIT_TARGET):
             continue
         options.append(_opt(sid, sid))
     return Prompt(
@@ -3110,20 +3076,10 @@ STEPS: list[Step] = [
                             and not s.fix_cycle),
          build=_build_fix_cycle_confirm, submit=_submit_fix_cycle_confirm,
          owns=("fix_cycle",)),
-    Step(S_BRANCH_CONFIRM,
-         applies=lambda s: (_ready_for_confirm(s)
-                            and (not _fix_cycle_confirm_required(s)
-                                 or bool(s.fix_cycle))
-                            and _branch_confirm_required(s)
-                            and s.branch_confirmed is None),
-         build=_build_branch_confirm, submit=_submit_branch_confirm,
-         owns=("branch_confirmed",)),
     Step(S_CONFIRM,
          applies=lambda s: (_ready_for_confirm(s)
                             and (not _fix_cycle_confirm_required(s)
                                  or bool(s.fix_cycle))
-                            and (not _branch_confirm_required(s)
-                                 or s.branch_confirmed is True)
                             and s.confirmed is None),
          build=_build_confirm, submit=_submit_confirm,
          owns=("confirmed", "edit_target")),
@@ -3222,7 +3178,7 @@ _FIELD_DEFAULTS: dict[str, Any] = {
     "pr_template_path": "", "pr_template_pending_text": False,
     "pr_template_scope": "",
     "fix_cycle": "",
-    "branch_confirmed": None, "confirmed": None, "edit_target": "",
+    "confirmed": None, "edit_target": "",
 }
 
 
@@ -3493,6 +3449,9 @@ def confirmation_block(state: WizardState) -> str:
                           task_key=f"{state.task_group}/{state.task_id}"))
     else:
         lines.append(f"  base-ref      : {state.base_ref}")
+    worktree_line = _worktree_preview_line(state)
+    if worktree_line is not None:
+        lines.append(worktree_line)
     if state.task_type == "implementation":
         lines.append(f"  executor      : {state.executor or '(default)'}")
         lines.append(