okstra 0.122.0 → 0.124.0

package/docs/for-ai/skills/okstra-graphify.md

@@ -0,0 +1,64 @@
+# okstra-graphify AI Manual
+
+## Sources
+
+- Skill source: [`skills/okstra-graphify/SKILL.md`](../../../skills/okstra-graphify/SKILL.md)
+- Graph core (CLI): [`scripts/okstra_ctl/graphify_cmd.py`](../../../scripts/okstra_ctl/graphify_cmd.py)
+- Node wrapper: [`src/commands/graphify.mjs`](../../../src/commands/graphify.mjs)
+
+## Purpose
+
+`okstra-graphify` builds and queries a **knowledge graph** over the project's own okstra memory (the final reports, `decisions/*.md`, `glossary.md`, and briefs under `<projectRoot>/.okstra`). The corpus is **fixed** to `.okstra` and the outputs land at `<projectRoot>/.okstra/graph/` — the CLI enforces both, so this skill takes no user path argument and never touches files outside `.okstra/`.
+
+- Docs-only. There is no code AST extraction here (that is the standalone `/graphify`).
+- Distinguish it from the arbitrary-code / non-okstra folder graph (`/graphify`), single-task inspection (`okstra-inspect`), and rollup (`okstra-rollup`).
+
+## Sub-commands
+
+| Sub-command | What it does |
+|---|---|
+| `build` | Extract entities/relationships from `.okstra` docs (parallel subagent dispatch), then assemble the graph + report + HTML |
+| `query` | BFS/DFS traversal over the graph to answer a broad question |
+| `path` | Shortest path between two named concepts |
+| `explain` | Plain-language explanation of one node and its connections |
+| `wiki` | Agent-crawlable wiki (`index.md` + one article per community) |
+| `mcp` | A stdio MCP server exposing the graph to other agents (opt-in — additionally needs `pip install mcp`) |
+
+## Preflight
+
+A single Bash call starting with the literal token `okstra` (not wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=`/`||`/`&&`/`npx`):
+
+```bash
+okstra preflight --runtime claude-code --json
+```
+
+`ok:true` → carry `projectRoot` as a literal string. Every `okstra graphify` call passes `--project-root <projectRoot>` (**REQUIRED**, no cwd injection — a bare `okstra graphify build` is a usage error). `ok:false` → first check once whether the user pointed at a specific project directory; if it is still `ok:false`, point to `/okstra-setup` and stop. On `unknown command: preflight`, the `okstra` on PATH is older than the skill — point to `npm i -g okstra@latest` and stop.
+
+## build (the core division of labor)
+
+Two parts: **semantic extraction** (subagents read `.okstra` docs and write chunk JSON) → **assemble** (the CLI does clustering and output generation).
+
+1. Detect the corpus: `find <projectRoot>/.okstra -type f -name '*.md' -not -path '*/graph/*'`. If zero, stop.
+2. Semantic extraction: **you MUST use the Agent tool** (reading files one-by-one is forbidden — far slower). Split into chunks of 20-25 files and **dispatch in parallel, once per chunk in a single response**, with `subagent_type="general-purpose"` fixed (`Explore` is read-only, cannot write chunk files, and silently drops results). Each subagent writes `<projectRoot>/.okstra/graph/.chunks/chunk-NN.json`. It MUST fill in EXTRACTED/INFERRED/AMBIGUOUS + `confidence_score`.
+3. Assemble: `okstra graphify build --project-root <projectRoot>` — merges `graph/.chunks/*.json` and writes `graph.json`, `GRAPH_REPORT.md`, `graph.html`. On a `no extraction chunks` error, the subagents did not write their files — re-dispatch.
+
+After a successful build, paste **only** the God Nodes / Surprising Connections / Suggested Questions sections of `GRAPH_REPORT.md` (not the whole file), then offer to trace the single most interesting question via `query`.
+
+## query / path / explain / wiki / mcp
+
+```bash
+okstra graphify query "<question>" --project-root <projectRoot>
+okstra graphify path "<ConceptA>" "<ConceptB>" --project-root <projectRoot>
+okstra graphify explain "<NodeName>" --project-root <projectRoot>
+okstra graphify wiki --project-root <projectRoot>
+okstra graphify mcp --project-root <projectRoot>
+```
+
+`query`/`path`/`explain`/`wiki`/`mcp` **require a built graph** — if the CLI says none exists, run `build` first. `mcp` additionally needs `pip install mcp` and is long-running (the user stops it with Ctrl+C). After doc changes, re-run `build` to re-extract.
+
+## Output Rules
+
+- Be concise, in Korean, unless the user requests otherwise.
+- Outputs go under `<projectRoot>/.okstra/graph/`, in project-relative paths where possible.
+- **Never invent an edge** — if unsure, it is AMBIGUOUS. Never hide cohesion/confidence scores.
+- Say plainly when a fact is not in the graph. Quote `source_file`/`source_location`.

package/docs/for-ai/skills/okstra-inspect.md

@@ -1,81 +1,81 @@
 # okstra-inspect AI Manual
 
-## 원천
+## Source
 
-- 스킬 원문: [`skills/okstra-inspect/SKILL.md`](../../../skills/okstra-inspect/SKILL.md)
+- Skill source: [`skills/okstra-inspect/SKILL.md`](../../../skills/okstra-inspect/SKILL.md)
 - CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
 - context-cost CLI: `src/commands/inspect/context-cost.mjs`
 - time-report CLI: `src/commands/inspect/time-report.mjs`
 - log-report CLI: `src/commands/inspect/log-report.mjs`
 - error-report CLI: `src/commands/inspect/error-report.mjs`
-- container는 별도 스킬: [`okstra-container-build.md`](okstra-container-build.md)
+- container is a separate skill: [`okstra-container-build.md`](okstra-container-build.md)
 
-## 목적
+## Purpose
 
-`okstra-inspect`는 okstra read-side 작업의 단일 진입점이다. 대부분은 읽기 전용이지만 두 예외가 있다.
+`okstra-inspect` is the single entry point for okstra read-side work. Most of it is read-only, with two exceptions.
 
-- `status.4`: 사용자가 요청한 `workStatus`를 `task-manifest.json`에 기록한다.
-- `errors`, `error-zip`, `recap record`: 읽은 정보를 바탕으로 report/zip/log 산출물을 만든다.
+- `status.4`: writes the user-requested `workStatus` into `task-manifest.json`.
+- `errors`, `error-zip`, `recap record`: produce report/zip/log artifacts from the information read.
 
-## sub-command 목록
+## sub-command list
 
-| Sub-command | 역할 | 쓰기 여부 |
+| Sub-command | Role | Writes? |
 |---|---|---|
-| `status` | task/phase/workflow 상태 확인, workStatus 변경 | `status.4`에서 manifest 수정 |
-| `history` | 과거 run 목록, rerun/resume command 조립 | 기본 읽기 |
-| `report` | final-report 경로 해석 및 선택적 읽기 | 읽기 |
-| `time` | task type/worker별 소요 시간 집계 | 읽기 |
-| `logs` | wrapper `.log` sidecar inventory와 cleanup command 제안 | 읽기 |
-| `cost` | task bundle context/read cost 추정 | 읽기 |
-| `errors` | task error logs를 timestamped markdown report로 집계 | report 생성 |
-| `error-zip` | cross-project error logs 익명화 zip 생성 | zip 생성 |
-| `recap` | task run 전후 요약과 Q&A 기록 | `recap-log.jsonl` append |
+| `status` | check task/phase/workflow status, change workStatus | manifest edit in `status.4` |
+| `history` | list past runs, assemble rerun/resume command | read by default |
+| `report` | resolve final-report path and optionally read | read |
+| `time` | aggregate elapsed time per task type/worker | read |
+| `logs` | inventory wrapper `.log` sidecars and suggest cleanup commands | read |
+| `cost` | estimate task bundle context/read cost | read |
+| `errors` | aggregate task error logs into a timestamped markdown report | generates report |
+| `error-zip` | build an anonymized zip of cross-project error logs | generates zip |
+| `recap` | summarize a task's before/after runs and record Q&A | appends `recap-log.jsonl` |
 
 ## Preflight
 
-모든 sub-command 전에 한 번만 실행한다.
+Run once before any sub-command.
 
 ```bash
 okstra preflight --runtime claude-code --json
 ```
 
-프로젝트 확인은 Bash 호출의 cwd만 본다. cwd가 아닌 프로젝트(형제 repo·monorepo 하위·요청에 명시된 프로젝트)에서 `ok:false`는 setup 부재가 아니라 false negative다 — 바로 멈추지 말고 `okstra preflight --runtime claude-code --cwd <that-dir> --json`으로 재시도한다(`--cwd`는 leading `cd` 없이 프로젝트를 지정하는 sanctioned 방식). 그것도 `ok:false`일 때만 `/okstra-setup` 안내 후 멈춘다. 이후 `projectRoot`를 literal 값으로 사용하고, 이를 받는 sub-command CLI(`recap`, `context-cost` 등)에는 `--cwd`/`--project-root <projectRoot>`로 전달한다.
+The project check only sees the cwd of the Bash call. For a project that is not the cwd (a sibling repo, a monorepo subdir, or a project named in the request), `ok:false` is a false negative, not a missing setup — do not stop immediately; retry with `okstra preflight --runtime claude-code --cwd <that-dir> --json` (`--cwd` is the sanctioned way to target a project without a leading `cd`). Only when that also returns `ok:false` do you guide the user to `/okstra-setup` and stop. Then use `projectRoot` as a literal value, and pass it to the sub-command CLIs that accept it (`recap`, `context-cost`, etc.) via `--cwd`/`--project-root <projectRoot>`.
 
 ## intent routing
 
-사용자 요청을 하나 이상의 facet으로 분류한다. 애매하면 sub-command 표 전체를 보여주고 번호/이름으로 선택하게 한다. AskUserQuestion option 제한 때문에 facet을 숨기지 않는다.
+Classify the user request into one or more facets. If ambiguous, show the entire sub-command table and let the user pick by number/name. Do not hide a facet because of AskUserQuestion's option limit.
 
-여러 facet이 한 메시지에 있으면 순차 실행한다. Step 0은 한 번만 실행한다.
+If several facets appear in one message, execute them sequentially. Step 0 runs only once.
 
-## task-key 해석 공통 규칙
+## task-key resolution — shared rule
 
-많은 facet은 다음 target 형식을 받는다.
+Many facets accept the following target forms.
 
 1. full task-key: `<project-id>:<task-group>:<task-id>`
 2. bare task-id
 3. task root path
 
-bare task-id는 shared resolver를 사용한다.
+A bare task-id uses the shared resolver.
 
 ```bash
 okstra resolve-task-key <task-id> --project-root <projectRoot> --json
 ```
 
-`matches[]` 처리:
+Handling `matches[]`:
 
-- 0개: 찾을 수 없다고 말하고 추측하지 않는다.
-- 1개: 해당 `taskKey` 사용.
-- N개: 후보 `taskKey`와 `updatedAt`를 보여주고 disambiguation을 받는다.
+- 0: say it cannot be found; do not guess.
+- 1: use that `taskKey`.
+- N: show the candidate `taskKey`s and `updatedAt`, and take a disambiguation.
 
 ## status
 
 ### Project overview
 
-`.okstra/discovery/task-catalog.json`을 읽는다. overview에서는 개별 manifest를 다시 열지 않는다. catalog가 projected source다.
+Read `.okstra/discovery/task-catalog.json`. Do not re-open individual manifests for the overview. The catalog is the projected source.
 
-정렬: `updatedAt` desc, `taskKey`.
+Sort: `updatedAt` desc, then `taskKey`.
 
-표는 좁게 유지한다.
+Keep the table narrow.
 
 - Task Key
 - Category
@@ -83,13 +83,13 @@ okstra resolve-task-key <task-id> --project-root <projectRoot> --json
 - workStatus
 - Next
 
-`awaitingApproval` 또는 `routingStatus == "pending"`이면 Next cell에 marker를 붙이고 설명한다.
+If `awaitingApproval` or `routingStatus == "pending"`, add a marker to the Next cell and explain it.
 
 ### Specific task
 
-task 하나의 detail은 catalog를 먼저 보고, 필요하면 `.okstra/tasks/<group>/<id>/task-manifest.json`, `history/timeline.json`, latest run manifest를 읽는다.
+For a single task's detail, check the catalog first, then if needed read `.okstra/tasks/<group>/<id>/task-manifest.json`, `history/timeline.json`, and the latest run manifest.
 
-보여줄 정보:
+Information to show:
 
 - work category
 - current phase/state
@@ -105,70 +105,70 @@ task 하나의 detail은 catalog를 먼저 보고, 필요하면 `.okstra/tasks/<
 
 ### workStatus update
 
-사용자가 명시적으로 상태 변경을 요청할 때만 쓴다.
+Write only when the user explicitly requests a status change.
 
-허용값:
+Allowed values:
 
 - `todo`
 - `in-progress`
 - `blocked`
 - `done`
 
-절차: `okstra set-work-status <token> <status> [--note <text>] --project-root <projectRoot> --json` 단일 호출로 갱신한다 — manifest 를 손으로 편집하지 않는다. `stage:"ambiguous"` 면 `matches[]` 로 되묻고, `stage:"not-found"` 면 못 찾았다고 답한다.
+Procedure: update via a single `okstra set-work-status <token> <status> [--note <text>] --project-root <projectRoot> --json` call — do not edit the manifest by hand. On `stage:"ambiguous"`, re-ask with `matches[]`; on `stage:"not-found"`, answer that it cannot be found.
 
-읽기 표시에서 `workStatus`가 없으면 lifecycle state로 추론하되, 읽기만으로 back-fill하지 않는다.
+When `workStatus` is absent in a read display, infer it from the lifecycle state, but do not back-fill on read alone.
 
 ## history
 
-첫 분기: re-run과 resume을 구분한다.
+First branch: distinguish re-run from resume.
 
-- Re-run: 이전 run parameters로 새 run을 만든다. 새 run-seq가 생긴다.
-- Resume: 중단된 기존 run을 이어간다. 새 run-seq를 만들지 않는다.
+- Re-run: create a new run from previous run parameters. A new run-seq is created.
+- Resume: continue an interrupted existing run. No new run-seq is created.
 
-catalog가 없으면 `.okstra/tasks/*/*/task-manifest.json` glob으로 fallback한다. disk manifest가 source of truth다.
+If the catalog is absent, fall back to the `.okstra/tasks/*/*/task-manifest.json` glob. The disk manifest is the source of truth.
 
-Re-run은 source run-manifest에서 `projectId`, `taskGroup`, `taskId`, `taskType`, `taskBriefPath`, workers, relatedTasks, model overrides 등을 뽑아 command를 조립한다. `implementation`의 `--base-ref`는 run-manifest에 없고 worktree registry에 있으므로 상황에 따라 묻는다.
+Re-run extracts `projectId`, `taskGroup`, `taskId`, `taskType`, `taskBriefPath`, workers, relatedTasks, model overrides, and so on from the source run-manifest to assemble the command. `implementation`'s `--base-ref` is not in the run-manifest but in the worktree registry, so ask for it as the situation requires.
 
-Resume은 `latestResumeCommandPath` 또는 timeline entry의 `resumeCommandPath`를 확인하고 파일이 있으면 `bash <resume-command-path>`를 안내/실행한다. 경로가 비었거나 파일이 없으면 "resume 없음"으로 선언하고 history.3(re-run)을 안내한다.
+Resume checks `latestResumeCommandPath` or the timeline entry's `resumeCommandPath`, and if the file exists, guides/runs `bash <resume-command-path>`. If the path is empty or the file is missing, declare "no resume" and guide to history.3 (re-run).
 
 ## report
 
-report path 해석 우선순위:
+report path resolution priority:
 
-1. `.okstra/discovery/task-catalog.json`의 `latestReportPath`
-2. direct `task-manifest.json`의 `latestReportPath`
-3. `history/timeline.json`의 특정 run `reportPath`
-4. 특정 task-type fallback: `runs/<task-type>/reports/final-report-*.md`, stage-isolated path 포함
+1. `latestReportPath` in `.okstra/discovery/task-catalog.json`
+2. `latestReportPath` in the direct `task-manifest.json`
+3. a specific run's `reportPath` in `history/timeline.json`
+4. specific task-type fallback: `runs/<task-type>/reports/final-report-*.md`, including stage-isolated paths
 
-읽기 깊이를 요청에 맞춘다(final report는 300+줄/50K+ 토큰). 요약/결론/통과 여부 질문("요약", "핵심만", "결론", "통과했어?")은 전체를 읽지 말고 `runs/<task-type-segment>/status/final-<task-type-segment>-<NNN>.status`(stage-isolated: `runs/<task-type-segment>/stage-<N>/status/`) sidecar의 판정 + report 선두 요약 블록만 읽는다. "전체/다 읽어/본문"일 때만 전체 ingest한다. 완료 signal은 있는데 file이 없으면 missing report로 말하고, 아직 완료되지 않았으면 current status와 workStatus를 보여준다.
+Match read depth to the request (a final report is 300+ lines / 50K+ tokens). For summary/conclusion/pass questions ("summary", "just the key points", "conclusion", "did it pass?"), do not read the whole thing — read only the verdict in the `runs/<task-type-segment>/status/final-<task-type-segment>-<NNN>.status` (stage-isolated: `runs/<task-type-segment>/stage-<N>/status/`) sidecar plus the report's leading summary block. Ingest the whole file only for "the whole thing / read it all / full body". If a completion signal exists but the file does not, report it as a missing report; if it is not yet complete, show the current status and workStatus.
 
 ## time
 
-시간 계산은 CLI가 한다. AI가 duration을 직접 recompute하지 않는다.
+The CLI does the time computation. The AI does not recompute duration by hand.
 
 ```bash
 okstra time-report <task-key> --project-root <projectRoot> --json
 ```
 
-모든 `*Ms`는 `HH:MM:SS`로 변환해 보여준다. `CPU sum`은 lead와 workers 시간을 합친 overlapping cost이며 wall-clock이 아니다. wall-clock은 사용자가 명시적으로 물을 때만 `perRunWallClock`에서 보여준다. `단계별`/`stage별`/`어느 단계가 오래`는 task-type 뷰(By task type 표)가 기본 답이다 — '측정 불가'로 처리하지 않는다. intra-run `phaseTimelines`는 'Phase 1~7'·'어느 phase가' 같은 명시적 요청일 때만 렌더하고, 비어 있으면 헤드라인이 아니라 각주로만 언급한다.
+Convert every `*Ms` to `HH:MM:SS` for display. `CPU sum` is the overlapping cost of lead and workers time combined, not wall-clock. Show wall-clock from `perRunWallClock` only when the user explicitly asks. For `by stage`/`per stage`/`which stage took longest`, the task-type view (the By task type table) is the default answer — do not treat it as 'not measurable'. Render the intra-run `phaseTimelines` only on an explicit request like 'Phase 1–7' / 'which phase', and when it is empty, mention it only as a footnote rather than a headline.
 
-`unavailable[]`은 totals에 합치지 않고 별도 note로 표시한다.
+`unavailable[]` is not summed into totals; show it as a separate note.
 
 ## cost
 
-context/read cost는 CLI output이 source of truth다.
+For context/read cost, the CLI output is the source of truth.
 
 ```bash
 okstra context-cost <task-key> --project-root <projectRoot>
 ```
 
-해석 포인트:
+Interpretation points:
 
-- token estimate는 heuristic이지 billing 수치가 아니다.
-- `leadPhase1.mode == "active-run-context"`면 compact lead intake가 primary다.
-- `analysisWorker.mode == "analysis-packet-primary"`면 worker는 analysis-packet을 먼저 읽고 필요할 때 full source를 연다.
-- `skillAssets`가 크면 prompt diet 대상이다.
-- legacy timestamp artifacts가 많으면 destructive delete가 아니라 current-view/cold-artifact 분리를 제안한다.
+- the token estimate is a heuristic, not a billing figure.
+- if `leadPhase1.mode == "active-run-context"`, the compact lead intake is primary.
+- if `analysisWorker.mode == "analysis-packet-primary"`, the worker reads the analysis-packet first and opens the full source only when needed.
+- if `skillAssets` is large, it is a prompt-diet target.
+- if there are many legacy timestamp artifacts, propose current-view/cold-artifact separation rather than a destructive delete.
 
 ## logs
 
@@ -178,33 +178,33 @@ wrapper sidecar log inventory:
 okstra log-report --project-root <projectRoot> --json
 ```
 
-`.okstra/tasks/**/runs/*/prompts/*.log`를 스캔한다. 삭제하지 않는다. cleanup command는 dry-run과 `-delete` pair를 fenced bash로 제시할 뿐이다.
+Scans `.okstra/tasks/**/runs/*/prompts/*.log`. Does not delete. The cleanup command merely presents a dry-run and `-delete` pair as fenced bash.
 
-active run의 log를 지우면 live trace를 잃으므로 먼저 `status` 확인을 권한다.
+Deleting an active run's log loses the live trace, so recommend checking `status` first.
 
 ## errors
 
-task error logs를 markdown report로 집계한다.
+Aggregate task error logs into a markdown report.
 
 ```bash
 okstra error-report <task-key> --project-root <projectRoot>
 ```
 
-stdout JSON에서 `reportPath`, totals, byPhase, byAgent, parseSkipped를 읽어 요약한다. `reportPath`가 없고 errorCount가 0이면 기록된 error log가 없다고 말한다. `parseSkipped > 0`은 숨기지 않는다.
+Read `reportPath`, totals, byPhase, byAgent, parseSkipped from the stdout JSON and summarize. If `reportPath` is absent and errorCount is 0, say there are no recorded error logs. Do not hide `parseSkipped > 0`.
 
 ## error-zip
 
-머신 내 cross-project okstra errors를 익명화 zip으로 묶는다.
+Bundle the machine's cross-project okstra errors into an anonymized zip.
 
-출력 경로는 `~/.okstra/error-zip.json`의 `lastOutputPath`를 우선 추천하고, 없으면 `~/okstra-error-feedback-<YYYY-MM-DD>.zip`을 제안한다.
+For the output path, recommend `lastOutputPath` from `~/.okstra/error-zip.json` first, and if absent, propose `~/okstra-error-feedback-<YYYY-MM-DD>.zip`.
 
-실행:
+Run:
 
 ```bash
 okstra error-zip --out <path>
 ```
 
-요약 필드:
+Summary fields:
 
 - `outPath`
 - `errorCount`
@@ -213,11 +213,11 @@ okstra error-zip --out <path>
 - `clusterCount`
 - `projectCount`
 
-마지막에 `/okstra-brief-gen`의 error-feedback variant로 brief를 만든 뒤 okstra repo에서 `error-analysis`를 실행하라고 안내한다.
+At the end, guide the user to build a brief with the error-feedback variant of `/okstra-brief-gen`, then run `error-analysis` in the okstra repo.
 
 ## recap
 
-기본은 artifact mode다. `.okstra/` 산출물만 근거로 전후 요약과 질문 답변을 만든다.
+The default is artifact mode. It builds the before/after summary and answers questions using only `.okstra/` artifacts.
 
 assemble:
 
@@ -231,22 +231,22 @@ record:
 okstra recap record <task-key> --project-root <projectRoot> --kind <summary|qa> --mode <artifact|code> --question "<question>" --answer "<summary>" --citation "<path:line>"
 ```
 
-code mode는 사용자가 "diff까지", "코드 변경까지"처럼 명시적으로 요청할 때만 진입한다. recap 진입만으로 code diff를 읽지 않는다.
+Enter code mode only when the user explicitly requests it, such as "including the diff" or "the code changes too". Entering recap alone does not read the code diff.
 
-## 출력 규칙
+## Output rules
 
-- 한국어로 간결히 답한다.
-- project-relative path를 우선 표시한다.
-- disk field 값은 normalize하지 않고 그대로 보여준다.
-- approval 대기 상태는 명확히 표시한다.
-- 최신 report가 없으면 `--`로 표시한다.
-- 날짜는 `YYYY-MM-DD HH:MM`로 표시한다.
+- Answer concisely in Korean.
+- Prefer project-relative paths.
+- Show disk field values as-is without normalizing.
+- Clearly indicate an awaiting-approval state.
+- If there is no recent report, show `--`.
+- Display dates in `YYYY-MM-DD HH:MM`.
 
-## 금지 패턴
+## Forbidden patterns
 
-- catalog가 없다고 바로 실패하기. manifest fallback이 있다.
-- `workStatus`와 `currentStatus`를 혼동하기.
-- time duration을 CLI 없이 손계산하기.
-- cleanup command를 직접 실행하기.
-- `errors`/`cost`/`time`에서 CLI output 대신 raw files를 임의로 재해석하기.
-- recap artifact mode에서 코드 변경까지 자동으로 읽기.
+- Failing immediately because the catalog is absent. There is a manifest fallback.
+- Confusing `workStatus` with `currentStatus`.
+- Hand-computing time duration without the CLI.
+- Running a cleanup command directly.
+- Arbitrarily reinterpreting raw files instead of CLI output in `errors`/`cost`/`time`.
+- Automatically reading code changes in recap artifact mode.

package/docs/for-ai/skills/okstra-manager.md

@@ -1,25 +1,25 @@
 # okstra-manager
 
-여러 프로젝트에 걸친 okstra task 를 하나의 manager-owned context 로 묶을 때 사용한다. 원문 계약은 [`skills/okstra-manager/SKILL.md`](../../../skills/okstra-manager/SKILL.md), CLI 구현은 [`src/commands/manager.mjs`](../../../src/commands/manager.mjs) 와 [`scripts/okstra_ctl/manager_cli.py`](../../../scripts/okstra_ctl/manager_cli.py) 이다.
+Use this to bundle okstra tasks across multiple projects into a single manager-owned context. The authoritative contract is [`skills/okstra-manager/SKILL.md`](../../../skills/okstra-manager/SKILL.md); the CLI implementation is [`src/commands/manager.mjs`](../../../src/commands/manager.mjs) and [`scripts/okstra_ctl/manager_cli.py`](../../../scripts/okstra_ctl/manager_cli.py).
 
-## 언제 쓰나
+## When to Use
 
-- 사용자가 "여러 프로젝트", "cross-project", "okstra manager", "프로젝트 묶어서" 같은 의도를 말한다.
-- manager 아래에 프로젝트를 등록하거나 후보 프로젝트를 찾는다.
-- 공통 task-group/task-id 아래 child project task 를 계획하고 역할/지시를 배정한다.
-- child project `.okstra` 상태를 manager snapshot 으로 동기화하거나 status 를 본다.
-- 특정 child task 실행을 위한 launch packet 과 manager child context 를 준비한다.
+- The user says something like "multiple projects", "cross-project", "okstra manager", or "group projects together".
+- Register projects under a manager, or discover candidate projects.
+- Plan child project tasks under a shared task-group/task-id and assign roles/directives.
+- Sync child project `.okstra` state into the manager snapshot, or view status.
+- Prepare a launch packet and a manager child context for running a specific child task.
 
-## 실행 규칙
+## Execution Rules
 
-1. 모든 명령은 literal `okstra` 로 시작한다. 셸 변수, `$(...)`, `&&`, `eval`, 선행 env assignment 로 감싸지 않는다.
-2. JSON stdout 이 source of truth 다. manager 상태나 child launch args 를 문서/메모리에서 재구성하지 않는다.
-3. `--workspace-root` 는 Node wrapper 가 소유한다. 사용자가 넘기면 CLI 가 거부한다.
-4. `new project` 의 `--project-root` 는 이미 존재하는 디렉터리여야 한다. 그 안의 `.okstra/project.json` 이 없을 때만 setup-equivalent registration 을 수행한다.
-5. public child task identity 는 `project-id:task-group:task-id` 이다. `new task --task` 예시는 full key form 을 우선 보여준다.
-6. 같은 manager task id 아래 실제 child task id 가 다르면 `task assign` 과 `task run` 에 `--child-task-id <id>` 를 같이 넘긴다.
+1. Every command starts with the literal `okstra`. Do not wrap it in shell variables, `$(...)`, `&&`, `eval`, or a leading env assignment.
+2. JSON stdout is the source of truth. Do not reconstruct manager state or child launch args from docs/memory.
+3. `--workspace-root` is owned by the Node wrapper. The CLI rejects it if the user passes it.
+4. `new project`'s `--project-root` must be an already-existing directory. It performs setup-equivalent registration only when there is no `.okstra/project.json` inside it.
+5. The public child task identity is `project-id:task-group:task-id`. The `new task --task` example shows the full key form first.
+6. When the actual child task id differs under the same manager task id, pass `--child-task-id <id>` to both `task assign` and `task run`.
 
-## 명령 표면
+## Command Surface
 
 ```bash
 okstra manager init --manager-id <manager-id> --json
@@ -34,35 +34,35 @@ okstra manager task status --manager-id <manager-id> --task-group <task-group> -
 okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>] --json
 ```
 
-## 저장 모델
+## Storage Model
 
-Manager state 는 `~/.okstra/managers/<manager-id>/` 아래에 저장되며, manager 루트와 task 디렉터리 두 계층으로 나뉜다.
+Manager state is stored under `~/.okstra/managers/<manager-id>/`, split into two layers: the manager root and the task directory.
 
-manager 루트 직하:
+Directly under the manager root:
 
 - `manager.json`: manager id / schema / createdAt
-- `projects.json`: 등록된 projectId, projectRoot, role, tags
+- `projects.json`: registered projectId, projectRoot, role, tags
 
-task 디렉터리 `task-groups/<safe-group>/<safe-task>/` 아래:
+Under the task directory `task-groups/<safe-group>/<safe-task>/`:
 
 - `manifest.json`: manager task objective, common brief, progress mode
 - `children.json`: child task plan, assignment, launch metadata
 - `directives.jsonl`: shared/project directive rows
-- `snapshots.json`: `task sync` 가 project-local `.okstra` 에서 읽어온 read-side snapshot
-- `events.jsonl`: `task-created`, `child-launch-prepared` 같은 manager event
-- `child-context/<safe-project>-<safe-task>.md`: `task run` 이 만든 child lead context
+- `snapshots.json`: the read-side snapshot `task sync` read from the project-local `.okstra`
+- `events.jsonl`: manager events such as `task-created` and `child-launch-prepared`
+- `child-context/<safe-project>-<safe-task>.md`: the child lead context `task run` produced
 
-비 ASCII task-group/task-id 처럼 slug 가 비는 segment 는 `u-<sha1-prefix>` path segment 를 사용하지만, manifest 와 child `taskKey` 는 원래 입력값을 보존한다.
+A segment whose slug is empty (e.g. a non-ASCII task-group/task-id) uses a `u-<sha1-prefix>` path segment, but the manifest and the child `taskKey` preserve the original input value.
 
 ## Child launch
 
-`task run` 은 child 작업을 직접 실행하지 않고 launch packet 을 준비한다. 반환 packet 의 핵심 필드는:
+`task run` does not run the child work directly; it prepares a launch packet. The key fields of the returned packet:
 
-- `taskKey`: child 의 `project-id:task-group:task-id` (child 식별 공개 키 — `child-launch-prepared` event 에도 기록)
-- `backend`: `$TMUX` 가 있으면 `tmux-child-lead`, 없으면 `subagent-child-lead`
-- `workerDispatchBackend`: v1 에서는 항상 `subagent`
-- `projectRoot`: child project root
-- `contextPath`: manager child context markdown
-- `runArgs`: host launcher 가 사용할 `okstra run ... --directive "Read manager child context: ..."` 인자
+- `taskKey`: the child's `project-id:task-group:task-id` (the public child-identity key — also recorded on the `child-launch-prepared` event)
+- `backend`: `tmux-child-lead` if `$TMUX` is present, otherwise `subagent-child-lead`
+- `workerDispatchBackend`: always `subagent` in v1
+- `projectRoot`: the child project root
+- `contextPath`: the manager child context markdown
+- `runArgs`: the `okstra run ... --directive "Read manager child context: ..."` args for the host launcher to use
 
-packet 생성이 성공하면 `children.json` 의 해당 child launch 상태가 `prepared` 로 갱신되고, `events.jsonl` 에 `child-launch-prepared` 가 append 된다. 실패해도 project-local task state 는 수정하지 않는다.
+When packet creation succeeds, that child launch's status in `children.json` is updated to `prepared`, and a `child-launch-prepared` is appended to `events.jsonl`. On failure it does not modify the project-local task state.