okstra 0.102.2 → 0.102.4

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

@@ -1,647 +0,0 @@
-# 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` 한 곳으로만 흐른다.