okstra 0.95.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.95.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.95.0",
-  "builtAt": "2026-06-18T19:01:30.042Z",
+  "package": "0.96.0",
+  "builtAt": "2026-06-19T14:40:32.132Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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(

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

@@ -1,7 +1,7 @@
 ---
 name: okstra-inspect
 description: |
-  Use for any read-side okstra inspection or status mutation. Single skill dispatches by sub-command to seven facets — status, history, report, time, logs, cost, errors. Trigger words include "okstra status", "task status", "current phase", "next phase", "okstra status set", "okstra mark", "<task-id> done|in-progress|진행중|완료", "okstra history", "past runs", "re-run", "resume", "list tasks", "find report", "show report for", "read the okstra report", "continue from report", "작업 시간", "소요 시간", "time summary", "duration", "elapsed", "얼마나 걸렸", "시간 분석", "okstra logs", "로그 현황", "로그 파일", "log size", "log status", "로그 정리", "log cleanup", "okstra context-cost", "context cost", "context-cost", "컨텍스트 비용", "읽기 비용", "산출물 비용", "okstra errors", "error report", "에러 리포트", "에러 보고", "에러 모아줘", "실패 로그 정리".
+  Use for any read-side okstra inspection or status mutation. Single skill dispatches by sub-command to eight facets — status, history, report, time, logs, cost, errors, recap. Trigger words include "okstra status", "task status", "current phase", "next phase", "okstra status set", "okstra mark", "<task-id> done|in-progress|진행중|완료", "okstra history", "past runs", "re-run", "resume", "list tasks", "find report", "show report for", "read the okstra report", "continue from report", "작업 시간", "소요 시간", "time summary", "duration", "elapsed", "얼마나 걸렸", "시간 분석", "okstra logs", "로그 현황", "로그 파일", "log size", "log status", "로그 정리", "log cleanup", "okstra context-cost", "context cost", "context-cost", "컨텍스트 비용", "읽기 비용", "산출물 비용", "okstra errors", "error report", "에러 리포트", "에러 보고", "에러 모아줘", "okstra recap", "recap", "작업 요약", "이 task 요약", "전후 요약", "이 작업 설명해줘", "task 질문", "실패 로그 정리".
 ---
 
 # OKSTRA Inspect
@@ -17,6 +17,7 @@ Single read-side entry point for okstra runtime inspection plus the one status m
 | `logs` | Inventory codex/antigravity wrapper `.log` sidecars; emit cleanup commands. |
 | `cost` | Estimate file/read context cost for a task bundle. |
 | `errors` | Aggregate okstra-run error logs for a task into a timestamped markdown report; print a summary. |
+| `recap` | Summarize a task's run-to-run phase transitions, then answer free-form questions over its `.okstra` artifacts. Appends each summary/Q&A to `recap/recap-log.jsonl`. |
 
 ## Step 0: Verify okstra runtime + project setup (shared)
 
@@ -758,6 +759,64 @@ Parse the stdout JSON and report:
 
 ---
 
+## recap
+
+Trigger phrases: "okstra recap", "recap", "작업 요약", "이 task 요약", "전후 요약", "이 작업 설명해줘", "task 질문".
+
+task-id 하나에 쌓인 `.okstra` 산출물 위에서 (a) 처리 전/후 요약을 내고, (b) 그 작업에 대한 자유 질문에 답한다. 기본은 `.okstra/` 서브트리만 읽는다(artifact 모드). 사용자가 명시적으로 코드 변경까지 봐 달라고 요청할 때만 code 모드로 확장한다. 이 sub-command 는 `recap/recap-log.jsonl` 만 append 하고 `task-manifest.json` / catalog / timeline 은 절대 mutate 하지 않는다.
+
+### recap.1 — Resolve target
+
+`cost` / `errors` 와 동일한 3형식: ① full task-key, ② task-id 만(→ `.okstra/discovery/task-catalog.json` 의 `taskId` 대소문자 무시 매칭; 복수면 나열·질문, 없으면 not-found), ③ task-root path.
+
+### recap.2 — Assemble the before/after summary
+
+CLI 출력을 source of truth 로 쓴다:
+
+```bash
+okstra recap assemble <resolved-target> --project-root <projectRoot>
+```
+
+stdout JSON(`{taskKey, runCount, transitions[], latestPhaseStates}`)을 파싱해 run 단위 전/후 전이를 서술한다. 각 `transitions[]` 항목의 `fromPhase → toPhase`(직전 run currentPhase → 이번 run currentPhase), `status`, `lastCompletedPhase`, `nextRecommendedPhase`, `reportPath` 를 시간순으로 보여준다. `runCount == 0` 이면 "이 task 에는 기록된 run 이 없습니다." 라고만 답하고 파일을 읽었다고 주장하지 않는다.
+
+`reportPath` 가 있는 run 은 사용자가 더 깊은 요약을 원할 때만 해당 final-report 를 읽어 보강한다(자동으로 모두 읽지 않는다).
+
+### recap.3 — Free-form Q&A loop
+
+요약 출력 뒤 사용자의 임의 질문을 받는다.
+
+- **artifact 모드(기본)**: `.okstra/` 산출물(timeline, task-manifest, 해당 run 의 final-report)만 근거로 답한다. 모든 사실 주장은 `.okstra` 파일 `path:line` 인용을 동반한다.
+- **code 모드(opt-in)**: 사용자가 "코드 변경까지 / diff 까지 봐줘" 류로 **명시적으로 요청**할 때만, 해당 task 의 worktree/브랜치에서 `git diff` · `git log` 를 추가로 읽어 코드 레벨로 답한다. recap 진입만으로는 절대 code 모드로 넘어가지 않는다.
+
+### recap.4 — Persist each turn
+
+요약 1건과 각 Q&A 답변을 로그에 남긴다(append-only):
+
+```bash
+okstra recap record <resolved-target> --project-root <projectRoot> \
+  --kind <summary|qa> --mode <artifact|code> \
+  --question "<질문 또는 생략>" --answer "<한두 줄 요약>" \
+  --citation "<path:line>" --citation "<path:line>"
+```
+
+`--answer` 에는 전체 답변 전사가 아니라 한두 줄 요약을 넣는다. 인용이 여러 개면 `--citation` 을 반복한다. 기록 실패(비정상 종료)는 조용히 넘기지 말고 사용자에게 알린다.
+
+### recap — Output template
+
+```markdown
+## okstra Recap — <task-key>
+
+전/후 요약 (runs: <N>):
+
+| # | when | task-type | from → to | status | next |
+|---|---|---|---|---|---|
+| 1 | <ts> | requirements-discovery | (시작) → requirements-discovery | done | error-analysis |
+
+<이후 자유 질문을 받습니다. 코드 변경까지 보려면 "diff 까지 봐줘" 라고 요청하세요.>
+```
+
+---
+
 ## Output Rules (shared)
 
 - Responses should be concise and written in Korean unless the user requests otherwise.