okstra 0.102.2 → 0.102.4

package/docs/superpowers/specs/2026-06-14-host-runtime-auto-execution-design.md

@@ -1,404 +0,0 @@
-# Host 기반 runtime auto-detection + auto-execution 설계
-
-- 날짜: 2026-06-14
-- 상태: 설계 초안
-- 대상: `okstra install`, `okstra doctor`, `okstra run`, lead runtime resolution, runtime manifest
-- 선행 문서:
-  - [`2026-06-12-codex-lead-adapter-design.md`](2026-06-12-codex-lead-adapter-design.md)
-  - [`2026-06-13-neutral-tmux-lead-adapter-design.md`](2026-06-13-neutral-tmux-lead-adapter-design.md)
-
-## 1. 배경
-
-현재 runtime 선택은 자동 감지가 아니다. `okstra install` 은 기본값 `claude-code` 를 사용하고, `installed-runtimes.json` 의 `codexAdapter` / `externalAdapter` 는 실제 adapter 실행 가능성이 아니라 install 인자 선택값만 반영한다.
-
-확인된 현재 상태:
-
-- `installed-runtimes.json` 은 `runtime === "codex" || "all"` 일 때만 `codexAdapter:true`, `runtime === "external" || "all"` 일 때만 `externalAdapter:true` 를 쓴다([runtime-manifest.mjs:8](../../../src/runtime-manifest.mjs:8)).
-- `okstra install` 기본 runtime 은 `claude-code` 다([install.mjs:606](../../../src/install.mjs:606)).
-- `okstra doctor` 기본 runtime 도 `claude-code` 다([doctor.mjs:37](../../../src/doctor.mjs:37)).
-- Python prepare layer 는 `leadRuntime != "claude-code"` 이고 non-render 이면 막는다([run.py:2053](../../../scripts/okstra_ctl/run.py:2053)).
-- `--lead-runtime` 기본값도 `claude-code` 다([run.py:2416](../../../scripts/okstra_ctl/run.py:2416)).
-- `okstra team` 은 `leadRuntime=external` bundle 을 받아 tmux-pane worker dispatch/await/teardown 을 수행하는 Node→Python CLI 경계다([team.mjs:4](../../../src/team.mjs:4)).
-
-사용자 결정:
-
-1. 자동 감지 범위는 **실행까지 자동**이다.
-2. runtime 우선순위는 **host 기반**이다.
-3. fallback 은 **safe fallback** 이다. 의도와 다른 runtime 으로 조용히 넘어가지 않는다.
-
-## 2. 문제
-
-현재 이름과 동작이 서로 맞지 않는다.
-
-- `codexAdapter:false` / `externalAdapter:false` 는 adapter 미설치 또는 CLI 부재처럼 보이지만, 실제 의미는 "이번 install 선택값이 `claude-code`" 이다.
-- 공유 runtime 은 항상 `~/.okstra/bin` 으로 복사되므로 wrapper 파일 존재와 manifest flag 가 일치하지 않는다.
-- 사용자는 `okstra install` / `okstra run` 이 현재 host 를 이해한다고 기대하지만, 실제로는 `claude-code` 로 고정된다.
-- `external` 실행은 Python non-render gate 때문에 직접 full-run 으로 열 수 없고, Node driver 가 render-only prepare → team dispatch/await 를 orchestration 해야 한다.
-
-## 3. 결정
-
-`auto` 를 runtime 값 자체가 아니라 **resolver 입력값**으로 도입한다.
-
-```text
-explicit runtime: claude-code | codex | external | all
-auto request: host/context 를 감지해 위 runtime 중 하나로 resolve
-```
-
-새 단일 참조점:
-
-```text
-src/runtime-resolver.mjs
-```
-
-역할:
-
-1. host signal 수집
-2. 설치 자산과 실행 capability 검사
-3. command 별 허용 runtime 계산
-4. safe fallback 적용
-5. 최종 runtime, 이유, 경고를 구조화해서 반환
-
-예상 API:
-
-```js
-resolveRuntime({
-  requestedRuntime: "auto" | "claude-code" | "codex" | "external" | "all",
-  command: "install" | "ensure-installed" | "doctor" | "render" | "run" | "dispatch",
-  env: process.env,
-  paths,
-})
-```
-
-반환:
-
-```json
-{
-  "requestedRuntime": "auto",
-  "resolvedRuntime": "external",
-  "host": "generic-terminal",
-  "confidence": "high",
-  "reason": "No Claude Code or Codex host signal; tmux is available.",
-  "fallbackFrom": null,
-  "warnings": []
-}
-```
-
-핵심 규칙:
-
-- 명시 runtime 은 자동 override 하지 않는다.
-- `auto` 일 때만 감지한다.
-- resolver 결과는 install manifest, run manifest, doctor JSON, console output 에 남긴다.
-- `codexAdapter` / `externalAdapter` 는 새 manifest 에서 쓰지 않는다. v1 manifest read compatibility 에서만 해석한다.
-
-## 4. 용어
-
-| 용어 | 의미 |
-|---|---|
-| install runtime | 어떤 asset set 을 설치/보장할지 결정하는 값 |
-| lead runtime | 이번 run 의 lead adapter 정체성: `claude-code`, `codex`, `external` |
-| host | 현재 `okstra` 를 실행 중인 환경: Claude Code session, Codex CLI/session, generic terminal |
-| dispatch backend | worker 를 어떻게 실행하는지: Claude Teams, CLI wrapper, tmux pane |
-| capability | 현재 시점에서 실행 가능한 조건: CLI binary, tmux, installed assets, phase support |
-| safe fallback | 같은 intent 를 보존할 수 있을 때만 fallback 하는 정책 |
-
-## 5. Host 감지
-
-Resolver 는 allowlist 기반 signal 만 사용한다. 불명확한 signal 은 runtime 을 결정하지 않고 warning 으로 남긴다.
-
-감지 우선순위:
-
-1. **Explicit runtime**
-   - CLI flag 또는 env override 가 `auto` 가 아니면 그대로 사용한다.
-   - 예: `--lead-runtime external`, `OKSTRA_LEAD_RUNTIME=codex`.
-2. **Explicit host override**
-   - 새 env `OKSTRA_RUNTIME_HOST=claude-code|codex|external`.
-   - 테스트와 wrapper 가 안정적으로 host 를 주입할 수 있는 public contract 다.
-3. **Claude Code host**
-   - Claude Code slash skill 또는 agent contract 가 `OKSTRA_RUNTIME_HOST=claude-code` 를 넘기는 방식이 primary signal 이다.
-   - 환경 fingerprint 는 보조 signal 로만 사용한다.
-4. **Codex host**
-   - Codex wrapper/entrypoint 가 `OKSTRA_RUNTIME_HOST=codex` 를 넘기는 방식이 primary signal 이다.
-   - `codex` executable 존재만으로 Codex host 라고 판단하지 않는다. binary availability 는 capability 일 뿐 host 가 아니다.
-5. **External host**
-   - 명시 host 가 없고, 일반 terminal 에서 `tmux` 가 사용 가능하면 `external`.
-6. **Unknown**
-   - host 와 capability 가 모두 부족하면 fail-fast.
-
-이 설계는 "binary가 설치되어 있으니 그 runtime으로 실행" 을 피한다. host 기반 결정과 capability 검사를 분리해야 예측 가능하다.
-
-## 6. Safe fallback matrix
-
-Fallback 은 `requestedRuntime:auto` 에서만 동작한다. 명시 runtime 은 실패를 사용자에게 보여주고 중단한다.
-
-| resolved candidate | 실행 불가 이유 | fallback |
-|---|---|---|
-| `claude-code` | Claude Code host signal 은 있으나 Claude assets 누락 | `ensure-installed --runtime claude-code` 로 보강 후 재시도 |
-| `claude-code` | Claude Code host 가 아닌 것으로 판정 | `external` if tmux 가능, 아니면 fail |
-| `codex` | Codex host signal 은 있으나 Codex CLI 없음 | fail. Claude/external 로 조용히 전환하지 않음 |
-| `codex` | requested roster 에 unsupported worker 포함 | fail with supported worker/report-writer opt-in 안내 |
-| `external` | tmux 없음 | prepare/render-only 까지는 가능, dispatch 는 fail |
-| `external` | `claude` worker 포함, Claude CLI wrapper 실행 불가 | 해당 worker dispatch fail. roster 를 몰래 줄이지 않음 |
-| unknown | host signal 없음 + tmux 없음 | fail with next-command suggestion |
-
-Fallback reason 은 run manifest 에 남긴다.
-
-## 7. CLI UX
-
-### 7.1 기본값
-
-다음 command 의 기본 runtime 을 `auto` 로 바꾼다.
-
-```bash
-okstra install
-okstra ensure-installed
-okstra doctor
-okstra render-bundle ...
-okstra run ...
-```
-
-명시 선택은 유지한다.
-
-```bash
-okstra install --runtime claude-code
-okstra install --runtime codex
-okstra install --runtime external
-okstra install --runtime all
-okstra run --lead-runtime external ...
-```
-
-`all` 은 감지값이 아니다. 모든 runtime asset set 을 명시 설치/검사하는 admin mode 로 유지한다.
-
-### 7.2 Execution front doors
-
-Auto execution has two front doors because Claude Code native tools are not available to a plain Node process.
-
-| Front door | Host | Responsibility |
-|---|---|---|
-| `/okstra-run` skill | Claude Code | Uses resolver context, keeps the existing Claude Code interactive/team path |
-| `okstra run` Node CLI | Codex / generic terminal | Resolves runtime and orchestrates CLI-backed `codex` or `external` execution |
-
-New Node driver `okstra run` is still useful, but it must not pretend it can call Claude Code `TeamCreate` / `Agent(...)` from a terminal. If `okstra run` resolves `claude-code` without being invoked by a Claude Code skill handoff, it fails with an instruction to use `/okstra-run` or pass another explicit runtime.
-
-```text
-okstra run ...
-  → resolveRuntime(requestedRuntime=auto by default, command=run)
-  → if resolvedRuntime=codex: codex-run → codex-dispatch
-  → if resolvedRuntime=external: render-bundle → team dispatch → team await
-  → if resolvedRuntime=claude-code outside skill handoff: fail with /okstra-run guidance
-```
-
-`external` 은 Python `prepare_task_bundle()` 의 non-render gate 를 열지 않는다. Node `okstra run` 이 render-only prepare 이후 dispatch/await 를 소유한다.
-
-### 7.3 기존 command 와의 관계
-
-- `okstra codex-run`: 유지. Codex lead prompt materialization 의 explicit low-level command.
-- `okstra codex-dispatch`: 유지. Prepared Codex run 의 explicit dispatch command.
-- `okstra team dispatch/await/teardown`: 유지. External/tmux backend 의 explicit low-level command.
-- `okstra render-bundle`: 유지. Preview/debug 목적의 low-level prepare command.
-- `okstra run`: 위 command 들을 host-aware 하게 묶는 high-level command.
-
-## 8. Manifest 변경
-
-### 8.1 installed-runtimes.json v2
-
-현재 v1 의 `codexAdapter` / `externalAdapter` 는 쓰지 않는다. 새 manifest 는 설치 요청과 설치 자산을 분리한다.
-
-```json
-{
-  "schemaVersion": 2,
-  "installedAt": "2026-06-14T00:00:00.000Z",
-  "installRequest": "auto",
-  "runtimeResolution": {
-    "requestedRuntime": "auto",
-    "resolvedRuntime": "external",
-    "host": "generic-terminal",
-    "reason": "No Claude Code or Codex host signal; tmux is available.",
-    "fallbackFrom": null,
-    "warnings": []
-  },
-  "installedRuntimes": ["external"],
-  "installedAssets": {
-    "sharedRuntime": true,
-    "claudeSkills": false,
-    "claudeAgents": false,
-    "binWrappers": true,
-    "templates": true,
-    "schemas": true,
-    "validators": true
-  }
-}
-```
-
-Dynamic capability 는 install manifest 에 고정하지 않는다. `tmux`, `codex`, `claude` CLI availability 는 시간이 지나면 바뀌므로 `doctor` 와 `run` 이 매번 검사한다.
-
-### 8.2 run manifest additions
-
-Run manifest 에 runtime request/resolution 을 기록한다.
-
-```json
-{
-  "leadRuntimeRequest": "auto",
-  "leadRuntime": "external",
-  "runtimeResolution": {
-    "requestedRuntime": "auto",
-    "resolvedRuntime": "external",
-    "host": "generic-terminal",
-    "reason": "No Claude Code or Codex host signal; tmux is available.",
-    "fallbackFrom": null,
-    "warnings": []
-  }
-}
-```
-
-`leadRuntime` 은 기존 consumer 호환을 위해 최종 resolved runtime 을 유지한다.
-
-## 9. Install / ensure / doctor 동작
-
-### 9.1 install
-
-`okstra install` 기본값은 `--runtime auto` 와 같다.
-
-- Claude Code host → `claude-code` assets 설치: shared runtime + Claude skills/agents.
-- Codex host → `codex` assets 설치: shared runtime only.
-- Generic terminal + tmux → `external` assets 설치: shared runtime only.
-- `--runtime all` → shared runtime + Claude skills/agents + all installedRuntimes 기록.
-
-공유 runtime 은 모든 install mode 에서 복사한다. 이 때문에 `bin/okstra-codex-exec.sh` 같은 wrapper 존재만으로 `codex` runtime 설치를 의미하지 않는다. v2 manifest 는 이 혼동을 `installedAssets` 와 `installedRuntimes` 로 나눠 제거한다.
-
-### 9.2 ensure-installed
-
-`okstra ensure-installed` 기본값도 auto다.
-
-- 현재 host 에 필요한 asset 이 없으면 같은 host-resolved runtime 으로 install 을 수행한다.
-- generic terminal 에서 `external` 로 설치된 뒤 Claude Code 에서 `/okstra-run` 이 실행되면, Claude Code host signal 이 `claude-code` 로 resolve 되고 Claude assets 를 보강 설치한다.
-- v1 manifest 는 읽을 수 있어야 한다. v1 에서 `runtime:"claude-code"` 이면 `installedRuntimes:["claude-code"]` 로 해석한다.
-
-### 9.3 doctor
-
-`okstra doctor --runtime auto` 는 현재 host 에 필요한 readiness 만 검사한다.
-
-`okstra doctor --runtime all` 은 admin check 로 다음을 모두 검사한다.
-
-- shared runtime files
-- Claude assets
-- Codex CLI availability
-- external/tmux availability
-- manifest v1/v2 해석
-
-JSON output 에 `runtimeResolution` 을 포함한다.
-
-## 10. Execution flow
-
-### 10.1 Claude Code host
-
-```text
-/okstra-run
-  → resolver context = claude-code
-  → ensure-installed claude-code
-  → existing Claude Code interactive/team path
-```
-
-Bare `okstra run` must not claim Claude Code execution unless it is part of a Claude Code skill handoff. A Node process cannot invoke native `TeamCreate` / `Agent(...)` directly.
-
-이 경로는 기존 slash skill UX 를 깨지 않는다.
-
-### 10.2 Codex host
-
-```text
-okstra run ...
-  → resolveRuntime = codex
-  → ensure-installed codex
-  → okstra codex-run ...
-  → okstra codex-dispatch ...
-```
-
-Report-writer 는 기존 Codex opt-in 정책을 따른다. 필요한 phase 에서 report-writer 가 required 인데 opt-in 이 없으면 fail-fast 한다. Worker roster 를 몰래 줄이지 않는다.
-
-### 10.3 External/generic terminal host
-
-```text
-okstra run ...
-  → resolveRuntime = external
-  → ensure-installed external
-  → okstra render-bundle ... --lead-runtime external
-  → read produced run manifest
-  → okstra team dispatch --run-manifest <path>
-  → okstra team await --run-manifest <path>
-  → post-processing / validation
-```
-
-Python `prepare_task_bundle()` 의 non-render gate 는 유지한다. Full external execution 은 Node driver 가 orchestration 한다.
-
-## 11. Error handling
-
-All resolver failures should be actionable.
-
-Examples:
-
-- `auto resolved codex but codex CLI is unavailable. Install Codex CLI or run with --lead-runtime external.`
-- `auto resolved external but tmux is unavailable. Run render-only or install tmux.`
-- `explicit --lead-runtime codex requested, but worker claude is unsupported by codex-dispatch. Choose supported workers or use claude-code/external.`
-- `host unknown. Set OKSTRA_RUNTIME_HOST=claude-code|codex|external or pass --lead-runtime explicitly.`
-
-No fallback may change worker roster, phase, task type, executor, or report-writer role without explicit user input.
-
-## 12. Backward compatibility
-
-- Existing explicit flags keep working.
-- Existing `okstra codex-run`, `okstra codex-dispatch`, `okstra team *`, `okstra render-bundle` keep working.
-- v1 `installed-runtimes.json` remains readable.
-- New installs write v2.
-- Existing v1 `codexAdapter` / `externalAdapter` are interpreted only while reading old manifests.
-- `leadRuntime` in run manifest remains final resolved runtime, so validators that already read `leadRuntime` do not need a broad schema break.
-
-## 13. Tests
-
-Required test groups:
-
-1. `runtime-resolver` unit tests
-   - explicit runtime bypasses auto
-   - host override resolves each runtime
-   - generic terminal + tmux resolves external
-   - binary availability alone does not imply host
-   - safe fallback matrix
-2. install tests
-   - default install writes v2 auto manifest
-   - Claude host installs Claude assets
-   - external host skips Claude assets
-   - v1 manifest read compatibility
-3. doctor tests
-   - `--runtime auto` reports runtimeResolution
-   - `--runtime all` checks all readiness categories
-4. run driver tests
-   - auto external builds render-only bundle and invokes team dispatch/await in dry-run/fake mode
-   - auto codex invokes codex-run/codex-dispatch in dry-run/fake mode
-   - bare `okstra run` resolving `claude-code` fails with `/okstra-run` guidance
-   - unsupported Codex worker fails without roster shrink
-5. docs contract tests
-   - default runtime is auto
-   - host-based priority documented
-   - safe fallback documented
-   - manifest v2 no longer documents `codexAdapter` / `externalAdapter` as live fields
-
-## 14. Rollout plan
-
-Recommended implementation order:
-
-1. Add `runtime-resolver.mjs` and tests.
-2. Add v2 runtime manifest writer/reader while preserving v1 read path.
-3. Switch install/ensure/doctor defaults from `claude-code` to `auto`.
-4. Add `okstra run` high-level driver with dry-run/fake subprocess tests.
-5. Wire external execution path through render-bundle → team dispatch → team await.
-6. Wire codex execution path through codex-run → codex-dispatch.
-7. Update docs and CLI help.
-8. Keep explicit low-level commands unchanged.
-
-## 15. Non-goals
-
-- Do not remove explicit runtime flags.
-- Do not remove Claude Code slash skill UX.
-- Do not make binary availability alone choose a host.
-- Do not open Python `prepare_task_bundle()` non-render for `external` in this change.
-- Do not silently shrink worker roster for fallback.
-- Do not implement non-tmux external dispatch backends.
-- Do not change phase profile/schema/validator contracts by provider fork.

package/docs/superpowers/specs/2026-06-17-okstra-error-report-design.md

@@ -1,123 +0,0 @@
-# okstra-run 에러 집계 리포트 (`okstra error-report` + inspect `errors` facet) 설계
-
-- 날짜: 2026-06-17
-- 상태: 설계 초안
-- 대상: 신규 `scripts/okstra_ctl/error_report.py`, 신규 `src/error-report.mjs`, `src/cli-registry.mjs`, `skills/okstra-inspect/SKILL.md`
-- 선행 문서:
-  - [`2026-06-06-stage-worktree-isolation-design.md`](2026-06-06-stage-worktree-isolation-design.md) (stage-isolated run 경로)
-
-## 1. 배경
-
-okstra-run 은 실행 중 발생한 에러를 이미 구조화된 형태로 적재하고 있다. 그러나 그 데이터를 **읽어서 사람에게 리포트로 보여주는 소비자가 없다.**
-
-확인된 현재 상태:
-
-- 에러는 run 별 JSONL 로 적재된다: `runs/<task-type>/logs/errors-<task-type>-<seq>.jsonl` ([paths.py:196](../../../scripts/okstra_ctl/paths.py:196)).
-- 단일 writer 헬퍼가 스키마를 강제한다. 레코드 필드는 `ts / recordedAt / taskKey / phase / agent / agentRole / model / source / errorType / command / commandKind / exitCode / durationMs / message / stderrExcerpt / context` ([okstra-error-log.py:122](../../../scripts/okstra-error-log.py:122)).
-- 두 경로로 수집된다: lead 가 직접 관측한 에러(`append-observed`)와 워커 사이드카(`worker-results/<id>-worker-errors-*.json`)에서 끌어온 에러(`append-from-worker`) ([okstra-error-log.py:96](../../../scripts/okstra-error-log.py:96), [okstra-error-log.py:144](../../../scripts/okstra-error-log.py:144)). `source` 는 각각 `lead-observed` / `worker-reported`.
-- `errorType` 화이트리스트: `tool-failure`, `cli-failure`, `contract-violation` ([okstra-error-log.py:17](../../../scripts/okstra-error-log.py:17)).
-- `_active_error_logs` 는 이 경로들을 **lead 에게 "여기 기록하라"고 알려주는 쓰기 타깃**으로만 노출한다 ([render.py:361](../../../scripts/okstra_ctl/render.py:361), [render.py:430](../../../scripts/okstra_ctl/render.py:430)). errors.jsonl 을 읽어 보고하는 코드는 없다(grep 확인).
-- okstra-inspect 는 현재 `latestRunStatus == error` 라는 **run 단위 거친 상태**만 노출할 뿐, 개별 에러 이벤트(어느 phase 에서 어느 워커가 무슨 command 로 exitCode 몇으로 실패했는지)는 어디서도 리포트하지 않는다 ([skills/okstra-inspect/SKILL.md:206](../../../skills/okstra-inspect/SKILL.md:206)).
-
-## 2. 사용자 결정
-
-브레인스토밍에서 4개 핵심을 확정했다.
-
-1. **리포트 성격 = 파일 산출물.** 화면 출력에 그치지 않고 `.md` 파일로 저장한다.
-2. **범위 = task 전체 집계.** 한 task 의 모든 run 에 걸친 errors.jsonl 을 합쳐 phase / worker / errorType 별로 집계한다.
-3. **렌더링 주체 = 신규 CLI `okstra error-report`.** 여러 run 의 JSONL 집계는 결정론적이어야 정확하므로 Python 렌더러가 수행한다. inspect facet 은 이 CLI 를 호출하고 결과를 표시한다 — `cost` facet 이 `okstra context-cost` 를 호출하는 것과 동일한 패턴 ([skills/okstra-inspect/SKILL.md:528](../../../skills/okstra-inspect/SKILL.md:528)).
-4. **저장 방식 = timestamp 누적.** 매 호출마다 새 파일을 만들어 이력을 파일로 보존한다 — schedule 산출물과 동일한 누적 패턴 ([skills/okstra-schedule/SKILL.md:160](../../../skills/okstra-schedule/SKILL.md:160)).
-
-## 3. 아키텍처
-
-4개 변경. 모두 기존 컴포넌트를 복제하므로 새 패턴을 만들지 않는다.
-
-| 컴포넌트 | 역할 | 복제 대상 |
-|---|---|---|
-| `scripts/okstra_ctl/error_report.py` (신규) | task-key → task_root resolve → errors.jsonl glob → 집계 → `.md` 렌더 + stdout JSON 요약 | [`context_cost.py`](../../../scripts/okstra_ctl/context_cost.py) |
-| `src/error-report.mjs` (신규) | Node CLI 래퍼. `runPythonModule({module: "okstra_ctl.error_report"})` | [`src/context-cost.mjs`](../../../src/context-cost.mjs) |
-| `src/cli-registry.mjs` | `error-report` 명령 등록 (`introspection` 카테고리) | [`cli-registry.mjs:100`](../../../src/cli-registry.mjs:100) (context-cost 항목) |
-| `skills/okstra-inspect/SKILL.md` | 신규 `errors` facet 섹션 + dispatch 테이블 1행 + 트리거 phrase | `cost` facet 섹션 |
-
-### 단일 참조점 준수
-
-task-key → task_root 해석의 SSOT 는 공유 모듈 `okstra_project` 의 `find_task_root` / `resolve_project_root` 다 ([context_cost.py:16](../../../scripts/okstra_ctl/context_cost.py:16) 가 이를 `_resolve_task_root` 로 감싸 사용, [context_cost.py:92](../../../scripts/okstra_ctl/context_cost.py:92)). `error_report.py` 는 새 해석 경로를 만들지 않고 같은 공유 모듈을 직접 재사용한다 — `context_cost.py` 의 `_resolve_task_root`(target = task-root path / task-key + project-root / task-key + cwd 3형태)와 동일한 입력 계약을 따른다.
-
-## 4. CLI 인터페이스
-
-```
-okstra error-report <task-root>
-okstra error-report <task-key> --project-root <dir>
-okstra error-report <task-key> --cwd <dir>
-```
-
-- 입력 형태는 `context-cost` 와 동일(task-root 직접 / task-key + project-root / task-key + cwd).
-- 동작: errors.jsonl 들을 모아 집계 → `.md` 파일을 쓰고 → **stdout 으로 요약 JSON** 을 낸다.
-- stdout JSON shape(초안):
-  ```json
-  {
-    "taskKey": "<project-id>:<task-group>:<task-id>",
-    "reportPath": "<project-root-relative .md path>",
-    "totals": { "errorCount": 12, "runCount": 4, "byErrorType": {...}, "bySource": {...} },
-    "byPhase": [ { "phase": "...", "count": N } ],
-    "byAgent": [ { "agent": "...", "count": N } ]
-  }
-  ```
-- inspect `errors` facet 은 이 JSON 을 파싱해 생성 경로 + 요약 카운트만 화면에 표시한다(전체 본문은 `.md` 파일이 SSOT).
-
-## 5. 산출물 위치 / 구조
-
-- 저장 경로: **`<task_root>/error-reports/error-report-<YYYY-MM-DD_HH-MM-SS>.md`**
-  - task 레벨 집계 산출물이므로 task root 하위 전용 디렉터리(`error-reports/`)에 둔다. run 별 산출물(`runs/<type>/reports/`, [paths.py:148](../../../scripts/okstra_ctl/paths.py:148))과 레벨이 다르므로 디렉터리를 분리해 혼동을 막는다.
-  - timestamp 형식은 schedule 과 동일한 `<YYYY-MM-DD_HH-MM-SS>`.
-  - artifact-home 규칙 준수: 모든 산출물이 `<PROJECT_ROOT>/.okstra/` 하위에 있다.
-- 리포트 `.md` 섹션 구조:
-  1. **요약** — 총 에러 N건, 집계된 run 수, `errorType` 별 카운트, `source`(lead-observed / worker-reported) 별 카운트, 생성 시각.
-  2. **phase 별 집계** — `| Phase | Count |` (lifecycle phase 순).
-  3. **worker(agent) 별 집계** — `| Agent | Role | Count |`.
-  4. **run 별 분해** — `| Run (type/seq) | Errors | 최초 ts | 최종 ts |`.
-  5. **개별 에러 이벤트** — `ts / phase / agent / errorType / command / exitCode / message` 테이블 + `stderrExcerpt` 는 접힌 코드블록. `ts` 오름차순.
-
-## 6. 데이터 흐름
-
-1. task-key → task_root resolve (context_cost 와 동일).
-2. errors.jsonl glob:
-   - flat: `<task_root>/runs/*/logs/errors-*.jsonl`
-   - stage-isolated: `<task_root>/runs/*/stage-*/logs/errors-*.jsonl` ([2026-06-06-stage-worktree-isolation-design.md](2026-06-06-stage-worktree-isolation-design.md) 의 stage 경로 규칙)
-3. 각 파일을 줄 단위 JSON 으로 파싱. 깨진 줄은 건너뛰되 카운트해 리포트 말미에 `parse-skipped: N` 으로 surface(조용한 누락 금지).
-4. 집계 → `.md` 렌더 + stdout JSON.
-
-## 7. inspect 의 "두 번째 write" 경계
-
-현재 SKILL 첫 줄은 "read-side inspection plus the one write-side mutation (`workStatus`)" ([SKILL.md:9](../../../skills/okstra-inspect/SKILL.md:9)).
-
-`errors` facet 은 `task-manifest.json` 같은 **okstra 상태를 mutate 하지 않는다.** CLI 를 호출해 **읽은 에러 데이터에서 파생한 산출물(.md)을 렌더**할 뿐이며, 이는 `cost` 가 추정치를 내는 것과 같은 read-derived 동작이다. 따라서 SKILL 의 정체성 문구를 다음으로 정정한다:
-
-> read-side okstra inspection + 상태 mutation 하나(`workStatus`) + read-derived 산출물 렌더(`errors` 리포트).
-
-이로써 "유일한 write 는 workStatus" 라는 기존 불변식과 모순되지 않게 경계를 명시한다(상태 mutation 은 여전히 workStatus 하나뿐).
-
-## 8. 엣지케이스
-
-- **glob 결과 0개** (errors.jsonl 자체가 없음): "이 task 에는 기록된 에러 로그가 없습니다" 를 facet 이 보고하고 `.md` 를 생성하지 않는다.
-- **파일은 있으나 레코드 0건**: 빈 결과와 구분해, "에러 0건" 을 명시한 리포트를 생성한다.
-- **깨진 JSONL 줄**: 건너뛰고 `parse-skipped` 카운트로 surface.
-- **stage-isolated + flat 혼재**: 둘 다 glob 해 합산.
-
-## 9. 테스트 계획
-
-- `tests/test_okstra_error_report.py` (신규):
-  - flat / stage-isolated / 혼재 fixture 에서 errorCount·byPhase·byAgent·bySource 집계 정확성.
-  - errors.jsonl 0개 / 빈 파일 / 깨진 줄(parse-skipped) 처리.
-  - 생성 `.md` 의 섹션 헤딩·테이블 컬럼 존재.
-  - stdout JSON shape.
-- 기존 `tests/test_okstra_error_log.py` 와 충돌하지 않게 별도 모듈.
-- e2e: 기존 시나리오에 에러를 적재한 뒤 `okstra error-report` 를 돌려 `.md` 가 생성되는지 확인하는 시나리오를 선택적으로 추가(범위 밖일 수 있음 — plan 단계에서 판단).
-
-## 10. 범위 밖 (YAGNI)
-
-- 단일 run 한정 모드 / `--all` 토글 — 이번엔 task 집계 단일 모드만.
-- task-group 단위 집계.
-- run 종료 훅에서의 자동 생성(on-demand 보고가 의도).
-- HTML / slim-AI 뷰 렌더.
-- errors.jsonl 의 timeline/catalog 경로 노출(facet 이 결정론적 glob 으로 resolve 하므로 불필요).