okstra 0.94.0 → 0.96.0

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.

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

@@ -50,7 +50,7 @@ The wizard tells you *which UI to use* via `kind` (and the optional `multi` flag
 - `kind: "done"` → input collection finished; move to Step 5.
 - `kind: "aborted"` → the user picked 중단; the wizard is terminally cancelled. Tell the user on one short line that the run setup was aborted, delete the state file (`rm` with the literal path), and stop this skill — do NOT call `render-args` or `render-bundle` (the wizard rejects `render-args` on an aborted state).
 
-The `branch_confirm` step (shown just before `confirm`) is a normal `pick` step and is rendered the same way — no special handling needed. Its options always include `중단` (abort); `base-ref 다시 고르기` (edit) appears only when a new branch would be created from the user-chosen base-ref. For `implementation` runs the wizard previews the **stage worktree** this run will actually use (not the task-key directory); render its label verbatim.
+The final `confirm` step is a normal `pick` step with three options — `Proceed` / `Edit` / `중단`(abort) — and is rendered the same way (no special handling). `Edit` rewinds to any earlier step (including `base-ref`); `중단` terminally cancels the wizard. The branch/worktree decision the run will actually use (for `implementation`, the **stage worktree** — not the task-key directory) is folded into the Step 4 confirmation summary block as a `worktree` line, so there is no separate branch-confirm prompt.
 
 Never invent additional questions. Never reorder. **Never drop, hide, or merge a `pick` / `pick_group` option** — render every `options[]` entry as its own selectable `AskUserQuestion` choice, including entries that carry a `(default)` / `(recommended)` suffix. Do NOT collapse a multi-option pick into a "recommended + 직접 입력 / Other" shortlist: the wizard's `options[]` array IS the complete, authoritative choice set. Example: the `executor` step always emits `claude` / `codex` / `antigravity` — show all three, never just `claude`. The run-prompt recommendation rule (1–2 추천 + 직접 입력) applies ONLY to prompts this skill authors itself (e.g. the conformance-waiver picker), never to wizard-provided `options[]`. Never use `AskUserQuestion` for `text` prompts — the wizard explicitly chose `text` to avoid the picker-Other re-render lag.
 

package/src/cli-registry.mjs

@@ -110,6 +110,13 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Aggregate okstra-run error logs into a task-level report"],
   },
+  {
+    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"],
+  },
   {
     name: "worktree-lookup",
     module: "./worktree-lookup.mjs",

package/src/recap.mjs

@@ -0,0 +1,27 @@
+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;
+}