okstra 0.95.0 → 0.96.0

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

@@ -0,0 +1,647 @@
+# okstra-inspect `recap` facet 구현 계획
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** okstra-inspect 에 task-id 단위 전/후 요약 + 자유 Q&A 를 제공하는 8번째 facet `recap` 을 추가한다.
+
+**Architecture:** 결정론적 부분(timeline run 간 phase 전이 계산 = `recap assemble`, recap-log append = `recap record`)은 python `okstra_ctl/recap.py` 에 두고 단위 테스트로 검증한다. 요약 서술과 자유 Q&A 는 skill-markdown(okstra-inspect)이 그 산출물 위에서 수행한다. 경로는 SSOT 인 `compute_run_paths` 에만 추가한다.
+
+**Tech Stack:** Python 3 (argparse, 4-space indent, snake_case) · Node ES modules (`src/*.mjs`, 2-space indent) · skill markdown · pytest.
+
+## Global Constraints
+
+- `runtime/` 는 빌드 산출물 — 절대 손으로 수정하지 않는다. 소스는 `scripts/`, `skills/`, `src/` 등에서만 고치고 `npm run build` 로 동기화한다.
+- 모든 okstra 산출물은 `<PROJECT_ROOT>/.okstra/` 안에만 쓴다. recap 은 `<task-root>/recap/recap-log.jsonl` 만 append 하고 다른 task 산출물(`task-manifest.json`, catalog, timeline)은 mutate 하지 않는다.
+- read-side python 모듈은 task-key/ task-root 입력 계약을 `okstra_ctl.task_target.resolve_task_root(target, project_root, cwd)` 로 공유한다 (context-cost / error-report 와 동일).
+- 사용자-노출 문서·주석 산문은 한국어, 코드 식별자/경로/CLI 인자는 영어.
+- 새 함수는 유효 코드 50줄 이하로 유지한다.
+- 타임스탬프는 `datetime.datetime.now(datetime.timezone.utc).isoformat()` (error_report 와 동일 패턴).
+
+---
+
+### Task 1: `compute_run_paths` 에 recap 경로 추가
+
+**Files:**
+- Modify: `scripts/okstra_ctl/paths.py` (task-root 레벨 경로 블록 `paths.py:122-130`, `abs_paths` 딕셔너리 `paths.py:206-302`, `rel_pairs` 리스트 `paths.py:303-350`)
+- Test: `tests/test_okstra_ctl_paths.py`
+
+**Interfaces:**
+- Consumes: 기존 `compute_run_paths(...)` 시그니처와 `task_root` 지역변수.
+- Produces: 컨텍스트 딕셔너리에 새 키 `RECAP_DIR`, `RECAP_LOG_PATH`(절대), `RECAP_DIR_RELATIVE_PATH`, `RECAP_LOG_RELATIVE_PATH`(project-root 상대). 경로 규약: `<task-root>/recap/` 디렉터리와 `<task-root>/recap/recap-log.jsonl` 파일.
+
+- [ ] **Step 1: Write the failing test**
+
+`tests/test_okstra_ctl_paths.py` 끝에 추가:
+
+```python
+def test_recap_paths_present():
+    ctx = compute_run_paths(**_common())
+    assert ctx["RECAP_DIR"].endswith("/.okstra/tasks/g/t/recap")
+    assert ctx["RECAP_LOG_PATH"].endswith("/.okstra/tasks/g/t/recap/recap-log.jsonl")
+    assert ctx["RECAP_DIR_RELATIVE_PATH"] == ".okstra/tasks/g/t/recap"
+    assert ctx["RECAP_LOG_RELATIVE_PATH"] == ".okstra/tasks/g/t/recap/recap-log.jsonl"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `python3 -m pytest tests/test_okstra_ctl_paths.py::test_recap_paths_present -v`
+Expected: FAIL with `KeyError: 'RECAP_DIR'`.
+
+- [ ] **Step 3: Add the path locals**
+
+`scripts/okstra_ctl/paths.py` 의 `timeline_file = history_dir / "timeline.json"` (`paths.py:130`) 바로 다음 줄에 추가:
+
+```python
+    recap_dir = task_root / "recap"
+    recap_log = recap_dir / "recap-log.jsonl"
+```
+
+- [ ] **Step 4: Register absolute keys**
+
+`abs_paths` 딕셔너리에서 `"TIMELINE_PATH": str(timeline_file),` (`paths.py:249`) 다음 줄에 추가:
+
+```python
+        "RECAP_DIR": str(recap_dir),
+        "RECAP_LOG_PATH": str(recap_log),
+```
+
+- [ ] **Step 5: Register relative keys**
+
+`rel_pairs` 리스트에서 `("TIMELINE_RELATIVE_PATH", timeline_file),` (`paths.py:314`) 다음 줄에 추가:
+
+```python
+        ("RECAP_DIR_RELATIVE_PATH", recap_dir),
+        ("RECAP_LOG_RELATIVE_PATH", recap_log),
+```
+
+- [ ] **Step 6: Run test to verify it passes**
+
+Run: `python3 -m pytest tests/test_okstra_ctl_paths.py -v`
+Expected: PASS (신규 + 기존 테스트 모두).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add scripts/okstra_ctl/paths.py tests/test_okstra_ctl_paths.py
+git commit -m "feat(paths): compute_run_paths 에 recap 디렉터리/로그 경로 추가"
+```
+
+---
+
+### Task 2: `recap assemble` — timeline run 간 phase 전이 조립
+
+**Files:**
+- Create: `scripts/okstra_ctl/recap.py`
+- Test: `tests/test_okstra_recap.py`
+
+**Interfaces:**
+- Consumes: `okstra_ctl.task_target.resolve_task_root`, `project_rel`. task-root 의 `history/timeline.json`(`{"runs": [ {runTimestamp, taskType, status, reportPath, workflowSnapshot:{currentPhase, lastCompletedPhase, nextRecommendedPhase, phaseStates}} ... ]}`).
+- Produces: `assemble_recap(task_root: Path, project_root: Path) -> dict` 반환:
+  ```
+  {
+    "taskKey": str,
+    "runCount": int,
+    "transitions": [ {"index": int, "runTimestamp": str, "taskType": str,
+                      "status": str, "fromPhase": str, "toPhase": str,
+                      "lastCompletedPhase": str, "nextRecommendedPhase": str,
+                      "reportPath": str} ... ],
+    "latestPhaseStates": dict
+  }
+  ```
+  `fromPhase` = 직전 run 의 `currentPhase`(첫 run 은 `""`), `toPhase` = 해당 run 의 `currentPhase`.
+
+- [ ] **Step 1: Write the failing test**
+
+`tests/test_okstra_recap.py` 생성:
+
+```python
+import json
+import sys
+from pathlib import Path
+
+LIB_DIR = Path(__file__).resolve().parents[1] / "scripts"
+if str(LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(LIB_DIR))
+
+from okstra_ctl import recap
+
+
+def _run(ts, current, last="", nxt="", task_type="implementation",
+         status="done", report=""):
+    return {
+        "runTimestamp": ts, "taskType": task_type, "status": status,
+        "reportPath": report,
+        "workflowSnapshot": {
+            "currentPhase": current, "lastCompletedPhase": last,
+            "nextRecommendedPhase": nxt, "phaseStates": {current: "done"},
+        },
+    }
+
+
+def _write_timeline(task_root: Path, runs: list[dict]) -> None:
+    hist = task_root / "history"
+    hist.mkdir(parents=True, exist_ok=True)
+    (hist / "timeline.json").write_text(
+        json.dumps({"runs": runs}, ensure_ascii=False), encoding="utf-8")
+    (task_root / "task-manifest.json").write_text(
+        json.dumps({"taskKey": "p:g:DEV-1"}, ensure_ascii=False), encoding="utf-8")
+
+
+def test_assemble_computes_adjacent_transitions(tmp_path):
+    _write_timeline(tmp_path, [
+        _run("2026-06-01T00:00:00+00:00", "requirements-discovery",
+             nxt="error-analysis"),
+        _run("2026-06-02T00:00:00+00:00", "error-analysis",
+             last="requirements-discovery", nxt="implementation-planning"),
+    ])
+    result = recap.assemble_recap(tmp_path, tmp_path)
+    assert result["taskKey"] == "p:g:DEV-1"
+    assert result["runCount"] == 2
+    assert result["transitions"][0]["fromPhase"] == ""
+    assert result["transitions"][0]["toPhase"] == "requirements-discovery"
+    assert result["transitions"][1]["fromPhase"] == "requirements-discovery"
+    assert result["transitions"][1]["toPhase"] == "error-analysis"
+    assert result["latestPhaseStates"] == {"error-analysis": "done"}
+
+
+def test_assemble_empty_timeline(tmp_path):
+    (tmp_path / "history").mkdir(parents=True)
+    (tmp_path / "history" / "timeline.json").write_text(
+        json.dumps({"runs": []}), encoding="utf-8")
+    (tmp_path / "task-manifest.json").write_text(
+        json.dumps({"taskKey": "p:g:DEV-1"}), encoding="utf-8")
+    result = recap.assemble_recap(tmp_path, tmp_path)
+    assert result["runCount"] == 0
+    assert result["transitions"] == []
+    assert result["latestPhaseStates"] == {}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `python3 -m pytest tests/test_okstra_recap.py -v`
+Expected: FAIL with `ModuleNotFoundError: No module named 'okstra_ctl.recap'`.
+
+- [ ] **Step 3: Write the module with assemble**
+
+`scripts/okstra_ctl/recap.py` 생성:
+
+```python
+"""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,
+    }
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `python3 -m pytest tests/test_okstra_recap.py -v`
+Expected: PASS (2 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add scripts/okstra_ctl/recap.py tests/test_okstra_recap.py
+git commit -m "feat(recap): timeline run 간 phase 전이 조립(assemble_recap)"
+```
+
+---
+
+### Task 3: `recap record` — recap-log.jsonl append + CLI 진입점
+
+**Files:**
+- Modify: `scripts/okstra_ctl/recap.py`
+- Test: `tests/test_okstra_recap.py`
+
+**Interfaces:**
+- Consumes: Task 2 의 `assemble_recap`, `resolve_task_root`, `project_rel`.
+- Produces:
+  - `append_recap_entry(task_root, project_root, *, kind, mode, question, answer_summary, citations, now) -> dict` — `<task-root>/recap/recap-log.jsonl` 에 한 줄 append, `{"logPath": <project-rel>, "entry": <written dict>}` 반환. entry 스키마: `{ts, kind, mode, question, answerSummary, citations}`.
+  - `main(argv)` — `okstra recap` 의 두 서브커맨드(`assemble`, `record`)를 argparse 로 디스패치하고 결과 JSON 을 stdout 에 출력.
+
+- [ ] **Step 1: Write the failing test**
+
+`tests/test_okstra_recap.py` 에 추가:
+
+```python
+def test_append_recap_entry_appends_one_line(tmp_path):
+    (tmp_path / "task-manifest.json").write_text(
+        json.dumps({"taskKey": "p:g:DEV-1"}), encoding="utf-8")
+    now = dt.datetime(2026, 6, 19, tzinfo=dt.timezone.utc)
+    first = recap.append_recap_entry(
+        tmp_path, tmp_path, kind="qa", mode="artifact",
+        question="무엇을 했나?", answer_summary="phase 2 까지 진행",
+        citations=["history/timeline.json:1"], now=now)
+    second = recap.append_recap_entry(
+        tmp_path, tmp_path, kind="summary", mode="code",
+        question="", answer_summary="요약", citations=[], now=now)
+    log = tmp_path / "recap" / "recap-log.jsonl"
+    lines = [l for l in log.read_text(encoding="utf-8").splitlines() if l.strip()]
+    assert len(lines) == 2
+    rec0 = json.loads(lines[0])
+    assert rec0["kind"] == "qa"
+    assert rec0["mode"] == "artifact"
+    assert rec0["question"] == "무엇을 했나?"
+    assert rec0["answerSummary"] == "phase 2 까지 진행"
+    assert rec0["citations"] == ["history/timeline.json:1"]
+    assert rec0["ts"] == "2026-06-19T00:00:00+00:00"
+    assert first["logPath"].endswith("recap/recap-log.jsonl")
+    assert second["entry"]["kind"] == "summary"
+
+
+def test_main_assemble_prints_json(tmp_path, capsys):
+    _write_timeline(tmp_path, [
+        _run("2026-06-01T00:00:00+00:00", "implementation"),
+    ])
+    rc = recap.main(["assemble", str(tmp_path)])
+    out = json.loads(capsys.readouterr().out)
+    assert rc == 0
+    assert out["runCount"] == 1
+
+
+def test_main_record_appends_and_prints(tmp_path, capsys):
+    (tmp_path / "task-manifest.json").write_text(
+        json.dumps({"taskKey": "p:g:DEV-1"}), encoding="utf-8")
+    rc = recap.main([
+        "record", str(tmp_path), "--kind", "qa", "--mode", "artifact",
+        "--question", "q?", "--answer", "a.",
+        "--citation", "x:1", "--citation", "y:2",
+    ])
+    out = json.loads(capsys.readouterr().out)
+    assert rc == 0
+    assert out["entry"]["citations"] == ["x:1", "y:2"]
+    log = tmp_path / "recap" / "recap-log.jsonl"
+    assert len([l for l in log.read_text().splitlines() if l.strip()]) == 1
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `python3 -m pytest tests/test_okstra_recap.py -v`
+Expected: FAIL with `AttributeError: module 'okstra_ctl.recap' has no attribute 'append_recap_entry'`.
+
+- [ ] **Step 3: Add append + main**
+
+`scripts/okstra_ctl/recap.py` 끝(`assemble_recap` 다음)에 추가:
+
+```python
+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 main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="okstra recap")
+    parser.add_argument("--project-root", default="")
+    parser.add_argument("--cwd", default=".")
+    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")
+
+    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")
+    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:]))
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `python3 -m pytest tests/test_okstra_recap.py -v`
+Expected: PASS (5 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add scripts/okstra_ctl/recap.py tests/test_okstra_recap.py
+git commit -m "feat(recap): recap-log.jsonl append + assemble/record CLI 디스패치"
+```
+
+---
+
+### Task 4: Node CLI 래퍼 `okstra recap`
+
+**Files:**
+- Create: `src/recap.mjs`
+- Modify: `src/cli-registry.mjs` (introspection 카테고리, `error-report` 항목 `cli-registry.mjs:106-112` 바로 다음)
+
+**Interfaces:**
+- Consumes: `./_python-helper.mjs` 의 `runPythonModule({module, args, stdio})` (error-report.mjs 와 동일).
+- Produces: `okstra recap <assemble|record> <target> ...` 가 `okstra_ctl.recap` 파이썬 모듈로 인자를 그대로 전달하고 stdout 을 그대로 흘려보낸다.
+
+- [ ] **Step 1: Create the wrapper**
+
+`src/recap.mjs` 생성:
+
+```javascript
+import { runPythonModule } from "./_python-helper.mjs";
+
+const USAGE = `okstra recap — assemble a task's run-to-run phase recap, or append a recap log entry
+
+Usage:
+  okstra recap assemble <task-root|task-key> [--project-root <dir>] [--cwd <dir>]
+  okstra recap record <task-root|task-key> --kind <summary|qa> --mode <artifact|code> \\
+    [--question <text>] --answer <text> [--citation <path:line> ...]
+
+\`assemble\` is read-only and prints a JSON summary of phase transitions across runs.
+\`record\` appends one line to <task-root>/recap/recap-log.jsonl; it never mutates
+other task artifacts.
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const result = await runPythonModule({
+    module: "okstra_ctl.recap",
+    args,
+    stdio: "inherit-stdout",
+  });
+  return result.code ?? 0;
+}
+```
+
+- [ ] **Step 2: Register in cli-registry**
+
+`src/cli-registry.mjs` 의 `error-report` 객체(`cli-registry.mjs:106-112`) 닫는 `},` 다음에 추가:
+
+```javascript
+  {
+    name: "recap",
+    module: "./recap.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Assemble a task's run-to-run phase recap or append a recap log entry"],
+  },
+```
+
+- [ ] **Step 3: Smoke-test the CLI wiring**
+
+Run: `node bin/okstra recap --help`
+Expected: USAGE 텍스트 출력, exit 0.
+
+- [ ] **Step 4: Smoke-test the python bridge**
+
+Run: `node bin/okstra recap assemble /nonexistent-task-root`
+Expected: `no task root for task key:` 류의 메시지로 비정상 종료(파이썬 브리지가 연결됐다는 증거). 경로/스택 추적 없이 SystemExit 메시지면 정상.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/recap.mjs src/cli-registry.mjs
+git commit -m "feat(cli): okstra recap Node 래퍼 + cli-registry 등록"
+```
+
+---
+
+### Task 5: okstra-inspect 에 `recap` facet 추가
+
+**Files:**
+- Modify: `skills/okstra-inspect/SKILL.md` (frontmatter description `SKILL.md:3-4`, facet 테이블 `SKILL.md:11-19`, facet 본문 — `errors` 섹션 `SKILL.md:695` 다음 끝에 추가)
+
+**Interfaces:**
+- Consumes: Task 4 의 `okstra recap assemble` / `okstra recap record` CLI. Step 0 의 공유 부트스트랩(`okstra ensure-installed`, `okstra check-project --json`)과 target 해석 규약(task-key / task-id catalog 매칭 / task-root path — `cost`·`errors` 와 동일).
+- Produces: 사용자에게 노출되는 8번째 sub-command `recap`.
+
+- [ ] **Step 1: Extend the frontmatter description**
+
+`SKILL.md:3-4` 의 `description` 에서 `dispatches by sub-command to seven facets — status, history, report, time, logs, cost, errors.` 를 `dispatches by sub-command to eight facets — status, history, report, time, logs, cost, errors, recap.` 로 바꾸고, 트리거 문자열 목록 끝(`"실패 로그 정리".` 직전)에 다음을 추가:
+
+```
+"okstra recap", "recap", "작업 요약", "이 task 요약", "전후 요약", "이 작업 설명해줘", "task 질문",
+```
+
+- [ ] **Step 2: Add the facet table row**
+
+`SKILL.md:19` 의 `errors` 행 바로 다음에 추가:
+
+```
+| `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`. |
+```
+
+그리고 `SKILL.md:9` 문장의 "Sub-commands:" 앞에 있는 facet 나열 설명이 7개를 가정하면 8개로 맞춘다(해당 문장에 숫자가 박혀 있지 않으면 변경 불필요 — 확인 후 진행).
+
+- [ ] **Step 3: Add the `recap` facet body**
+
+`errors — Output template` 블록(`SKILL.md:757` 부근, 파일 끝) 다음에 추가:
+
+````markdown
+---
+
+## 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 까지 봐줘" 라고 요청하세요.>
+```
+````
+
+- [ ] **Step 4: Verify the facet count is consistent**
+
+Run: `grep -n "seven facets\|eight facets\|seven\b" skills/okstra-inspect/SKILL.md`
+Expected: `seven` 잔존 없음, `eight facets` 만 존재. 잔존하면 그 자리를 8개 표현으로 고친다.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add skills/okstra-inspect/SKILL.md
+git commit -m "feat(inspect): recap facet — task-id 전/후 요약 + 자유 Q&A"
+```
+
+---
+
+### Task 6: 아키텍처 문서 갱신 + 빌드 동기화 + 전체 검증
+
+**Files:**
+- Modify: `docs/kr/architecture.md` (task-root 트리, `architecture.md:443-478` 부근)
+- (빌드) `npm run build` → `runtime/` 동기화
+
+**Interfaces:**
+- Consumes: Task 1–5 의 결과. 새 정보 없음(문서·빌드만).
+
+- [ ] **Step 1: Document the recap directory**
+
+`docs/kr/architecture.md` 의 task-root 트리(`history/`·`timeline.json` 가 그려진 블록, `architecture.md:443-478`)에 `recap/` 노드를 추가하고, 한 줄 설명을 단다:
+
+```
+└── recap/
+    └── recap-log.jsonl   # recap facet 의 전/후 요약·Q&A append-only 로그 (다른 산출물 불변)
+```
+
+- [ ] **Step 2: Sync runtime**
+
+Run: `npm run build`
+Expected: 에러 없이 완료. `recap.py` / `recap.mjs` / 갱신된 `SKILL.md` 가 `runtime/` 에 복사됨.
+
+- [ ] **Step 3: Run the full python suite**
+
+Run: `python3 -m pytest tests/ -q`
+Expected: 전부 PASS (신규 `tests/test_okstra_recap.py` 포함, 회귀 없음).
+
+- [ ] **Step 4: CLI smoke**
+
+Run: `node bin/okstra recap --help`
+Expected: USAGE 출력, exit 0.
+
+Run: `node bin/okstra --help`
+Expected: introspection 카테고리에 `recap` 이 나열됨.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add docs/kr/architecture.md runtime/
+git commit -m "docs(architecture): task-root 트리에 recap/ 추가 + runtime 동기화"
+```
+
+---
+
+## 검증 (계획 전체)
+
+- 결정론적 로직(`compute_run_paths` recap 경로 / `assemble_recap` 전이 계산 / `append_recap_entry` append)은 모두 단위 테스트로 커버(Task 1·2·3).
+- facet 동작(요약 서술·Q&A·2-모드)은 skill-markdown 주도라 자동 단위 테스트 대상이 아님 → Task 4·6 의 CLI 스모크 + 수동 `okstra recap assemble <task-id>` 로 확인.
+- "요약 품질"은 휴리스틱이라 자동 검증 범위 밖(spec §5 와 동일 입장).
+- 단일 참조점: 경로는 `compute_run_paths` 한 곳, target 해석은 `task_target.resolve_task_root` 한 곳, Node↔python 브리지는 `runPythonModule` 한 곳으로만 흐른다.