okstra 0.96.0 → 0.97.0

package/README.kr.md

@@ -161,7 +161,7 @@ Claude Code 세션 안에서 사용하는 슬래시 커맨드:
 | `/okstra-brief` | ticket, 요구사항 문서, 링크, 대화 내용을 `okstra-run`용 task brief로 변환 |
 | `/okstra-run` | 새 task 시작 (또는 기존 task 의 다음 phase 이어가기) |
 | `/okstra-memory` | `~/.okstra/memory-book` 전역 대화 메모리 저장·검색·보관 |
-| `/okstra-inspect` | 통합 read-side 스킬. sub-command: `status` (phase / 상태, workStatus 설정), `history` (과거 task / re-run / resume), `report` (final-report 조회·읽기), `time` (소요 시간 breakdown), `logs` (wrapper log sidecar 조회·정리 제안), `cost` (task bundle 컨텍스트/읽기 비용) |
+| `/okstra-inspect` | 통합 read-side 스킬. sub-command: `status` (phase / 상태, workStatus 설정), `history` (과거 task / re-run / resume), `report` (final-report 조회·읽기), `time` (소요 시간 breakdown), `logs` (wrapper log sidecar 조회·정리 제안), `cost` (task bundle 컨텍스트/읽기 비용), `errors` (run 에러 로그를 리포트로 집계), `recap` (run 간 전/후 요약 + task 의 `.okstra` 산출물 위 자유 Q&A) |
 | `/okstra-schedule` | task-group 전체에 대한 작업 계획표 생성 |
 | `/okstra-setup` | 프로젝트별 부트스트랩 (§3.2) |
 

package/README.md

@@ -159,7 +159,7 @@ User-facing slash commands inside a Claude Code session:
 | `/okstra-brief` | Turn a ticket, requirements doc, link, or conversation into an `okstra-run` task brief |
 | `/okstra-run` | Start a new task (or resume the next phase of an existing one) |
 | `/okstra-memory` | Store/search/archive global conversation memory in `~/.okstra/memory-book` |
-| `/okstra-inspect` | Unified read-side. Sub-commands: `status` (phase / state, workStatus update), `history` (past runs, re-run, resume), `report` (find/read final-report), `time` (elapsed-time breakdown), `logs` (wrapper log sidecar inventory + cleanup), `cost` (task bundle context/read cost) |
+| `/okstra-inspect` | Unified read-side. Sub-commands: `status` (phase / state, workStatus update), `history` (past runs, re-run, resume), `report` (find/read final-report), `time` (elapsed-time breakdown), `logs` (wrapper log sidecar inventory + cleanup), `cost` (task bundle context/read cost), `errors` (aggregate run error logs into a report), `recap` (run-to-run before/after summary + free-form Q&A over a task's `.okstra` artifacts) |
 | `/okstra-schedule` | Generate a work schedule for an entire task-group |
 | `/okstra-setup` | Per-project bootstrap (§3.2) |
 

package/bin/okstra

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { getPackageVersion } from "../src/version.mjs";
+import { getPackageVersion } from "../src/lib/version.mjs";
 import { COMMANDS, USAGE } from "../src/cli-registry.mjs";
 
 async function main(argv) {

package/docs/contributor-change-matrix.md

@@ -6,7 +6,7 @@ Use this matrix before changing high-risk repo contracts. Update the source file
 |---|---|---|
 | Add CLI flag | `src/`, `scripts/okstra_ctl/run.py`, `docs/kr/cli.md`, `prompts/wizard/` | JS CLI tests and pytest CLI contracts |
 | Add phase | `scripts/okstra_ctl/workflow.py`, `prompts/profiles/`, `validators/`, `tests/` | workflow and validation contract tests |
-| Change worker roster | `prompts/profiles/*.md`, `scripts/okstra_ctl/workers.py`, `tests/test_repo_contracts.py` | worker roster contract tests |
+| Change worker roster | `prompts/profiles/*.md`, `scripts/okstra_ctl/workers.py`, `tests/contract/test_repo_contracts.py` | worker roster contract tests |
 | Change report section | `schemas/final-report-v1.0.schema.json`, `templates/reports/final-report.template.md`, `scripts/okstra_ctl/render_final_report.py`, `validators/validate-run.py` | final-report schema, renderer, and validator tests |
 
 `runtime/` is build output. Never edit it directly; change source files and rebuild the runtime payload instead.

package/docs/kr/architecture/storage-model.md

@@ -0,0 +1,273 @@
+# Storage model & on-disk contracts
+
+> [`docs/kr/architecture.md`](../architecture.md) 의 storage / 계약 상세 절. 본문이 1000 줄을 넘어 이 부분을 분리했습니다.
+
+## Storage model
+
+`okstra`가 만드는 파일은 용도에 따라 아래 3개 영역에 나뉘어 저장됩니다.
+
+### 1. Stable task root
+
+task 자체의 기준 폴더입니다.
+task manifest, task index, instruction-set, runs, history가 이 루트 아래에 모입니다.
+
+```text
+<target-project>/.okstra/tasks/<task-group>/<task-id>/
+├── task-manifest.json
+├── task-index.md
+├── instruction-set/
+│   ├── analysis-profile.md
+│   ├── analysis-packet.md       # analysis worker primary compact input
+│   ├── analysis-material.md
+│   ├── reference-expectations.md
+│   ├── task-brief.md
+│   ├── directive.txt                  # optional (mirrors --directive)
+│   ├── final-report-schema.json
+│   ├── final-report-template.md
+│   └── claude-execution-prompt.md
+├── runs/
+│   └── <task-type>/
+│       ├── manifests/
+│       │   └── run-manifest-<task-type>-<seq>.json
+│       ├── state/
+│       │   └── team-state-<task-type>-<seq>.json
+│       ├── prompts/
+│       │   ├── claude-execution-prompt-<task-type>-<seq>.md
+│       │   ├── claude-worker-prompt-<task-type>-<seq>.md
+│       │   ├── codex-worker-prompt-<task-type>-<seq>.md
+│       │   ├── antigravity-worker-prompt-<task-type>-<seq>.md
+│       │   └── report-writer-worker-prompt-<task-type>-<seq>.md
+│       ├── reports/
+│       │   └── final-report-<task-type>-<seq>.md
+│       ├── status/
+│       │   └── final-<task-type>-<seq>.status
+│       ├── sessions/
+│       │   └── claude-resume-<task-type>-<seq>.sh
+│       ├── logs/
+│       │   └── errors-<task-type>-<seq>.jsonl        # optional, lead-only writer
+│       └── worker-results/
+├── history/
+│   ├── timeline.json
+│   └── fix-cycles.jsonl          # optional, fix cycle 진입 시에만 생성 (append-only)
+└── recap/
+    └── recap-log.jsonl          # optional, recap facet 의 전/후 요약·Q&A append-only 로그 (다른 산출물 불변)
+```
+
+실제 디렉터리 세그먼트는 안전한 경로 생성을 위해 slug 형태로 정규화될 수 있습니다.
+하지만 논리 task key는 항상 원래 입력값 기준 `project-id:task-group:task-id`를 유지합니다.
+
+### 2. Per-run execution artifacts
+
+실행별 산출물은 아래 경로에 누적됩니다.
+
+```text
+<target-project>/.okstra/tasks/<task-group>/<task-id>/runs/<task-type>/
+```
+
+여기에 저장되는 대표 파일:
+
+- `manifests/run-manifest-<task-type>-<seq>.json`
+- `state/team-state-<task-type>-<seq>.json`
+- `prompts/claude-execution-prompt-<task-type>-<seq>.md`
+- `prompts/<worker>-worker-prompt-<task-type>-<seq>.md`
+
+그리고 `--render-only`가 아니면 handoff된 Claude session이 보통 아래 결과 파일을 현재 run에 추가합니다.
+- `sessions/claude-resume-<task-type>-<seq>.sh`
+- `reports/final-report-<task-type>-<seq>.md`
+- `reports/final-report-<task-type>-<seq>.slim.md`  *(Phase 7 결정론적 후처리: AI 다음-phase 입력용 슬림 markdown)*
+- `reports/final-report-<task-type>-<seq>.html`     *(Phase 7 결정론적 후처리: 사람 reviewer 용 self-contained HTML, CSS/JS 인라인)*
+- `user-responses/user-response-<task-type>-<seq>.md` *(HTML 의 `Export user response` 버튼이 같은 이름으로 다운로드해 주는 사이드카; 여기 저장해 두면 `--resume-clarification` 이 instruction-set 의 `clarification-response.md` 에 자동 첨부한다 — `clarification_items.clarification_response_with_sidecars`)*
+- `worker-results/<worker>-audit-<task-type>-<seq>.md` *(워커별 Reading Confirmation 사이드카; 본문이 아니라 audit 용)*
+- `status/final-<task-type>-<seq>.status`
+- `carry/stage-<N>.json` *(implementation 전용: stage N 실행 evidence sidecar; 다음 stage 가 자동 carry-in)*
+- `consumers.jsonl` *(implementation-planning 전용: 이 plan 의 각 stage 를 소비한 impl-run 역링크; append-only)*
+최종 결과 파일 (`final-report` MD / status) 은 `okstra`가 stdout을 저장해서 만드는 파일이 아닙니다.
+`okstra`가 준비한 task bundle을 바탕으로 Claude가 현재 run 안에 직접 작성하는 결과물입니다.
+slim MD / HTML 두 view 는 `okstra render-views <final-report.md>` (Phase 7 step 1.5) 가 final-report MD 한 본을 입력으로 결정론적으로 생성합니다. 원본 MD 는 view 생성으로 인해 수정되지 않습니다.
+반면 `sessions/claude-resume-<task-type>-<seq>.sh`는 `okstra`가 Claude launch 전에 미리 생성하는 interruption recovery helper입니다.
+
+run directory는 task-type 단위로 task 실행 이력을 모으고, 내부를 `manifests/`, `state/`, `prompts/`, `reports/`, `status/`, `sessions/`, `worker-results/`처럼 유형별 하위 폴더로 나눈 뒤 각 run-level artifact와 result 파일을 `-<task-type>-<seq>` suffix(per-category 3-digit zero-padded counter, 예: `001`, `002`)로 구분합니다.
+worker prompt history는 `/tmp`가 아니라 항상 현재 run의 `prompts/` 아래 canonical artifact로 남깁니다.
+이전처럼 `analysis-profile.md`, `analysis-material.md`, `reference-expectations.md`, `task-brief.md`, skill 복사본, `final-report-template.md`를 run마다 중복 저장하지 않습니다.
+이 자료들은 stable task root의 `instruction-set/`에 canonical copy를 유지합니다.
+같은 task-type으로 다시 실행하면 동일한 `runs/<task-type>/` 폴더를 재사용하지만, 유형별 하위 폴더 아래에서 run-level 파일명이 `-<task-type>-<seq>` suffix로 분리되므로 기존 산출물을 덮어쓰지 않습니다. `<seq>`는 카테고리 디렉토리(`manifests/`, `prompts/`, `reports/`, `status/`, `state/`, `sessions/`, `worker-results/`)별로 독립 스캔되므로 같은 run에서도 카테고리별 값이 다를 수 있습니다.
+이전 flat legacy artifact가 task-type run 폴더 최상위에 남아 있으면 다음 실행 시 해당 유형별 하위 폴더로 자동 정리합니다.
+
+### 3. Project-level discovery and skill documents
+프로젝트 공용 discovery pointer는 아래 경로에 생성합니다.
+
+```text
+<target-project>/.okstra/discovery/latest-task.json
+<target-project>/.okstra/discovery/task-catalog.json
+```
+scripts/okstra.sh workflow가 사용하는 project-local Claude assets는 아래 경로들에 seed합니다.
+
+```text
+<target-project>/.claude/skills/okstra/SKILL.md
+<target-project>/.claude/skills/<sub-skill>/SKILL.md
+<target-project>/.claude/agents/<agent>.md
+```
+
+역할 구분:
+
+- `.okstra/discovery/latest-task.json`: 현재 프로젝트에서 가장 최근에 준비된 okstra task bundle을 가리키는 current-task convenience pointer
+- `.okstra/discovery/task-catalog.json`: 현재 프로젝트에 준비된 okstra task bundle 목록을 `taskKey`, `taskGroup`, `taskId` 기준으로 유지하는 canonical project-level catalog
+- `instruction-set/reference-expectations.md`: 현재 task가 참조해야 할 config files, deployment manifests, expected values를 task-level canonical artifact로 정리한 파일
+- `~/.claude/skills/okstra-*/...`, `~/.codex/skills/okstra-*/...`, `~/.omp/agent/skills/okstra-*/...`, `~/.claude/agents/...`: `okstra install` 이 사용자 홈에 seed하는 skill/agent asset (project-local 시딩은 더 이상 발생하지 않음 — `okstra install --refresh` 로 갱신)
+
+이전의 아래 파일들은 더 이상 okstra 생성 대상이 아닙니다.
+
+- `CLAUDE.md`
+- `.project-docs/ai/claude-project-guide.md`
+- `.project-docs/ai/claude-skill-index.md`
+- `.project-docs/ai/okstra/okstra-guide.md`
+- `.project-docs/ai/okstra/worker-catalog.md`
+
+## Task manifest contract
+
+`task-manifest.json`은 Claude가 task continuity를 이해할 때 기준이 되는 canonical metadata 파일입니다.
+이 manifest는 `projectRoot` 절대경로를 한 번만 기록하고, 나머지 생성 경로들은 가능한 한 project-relative field로 정리하는 것을 기본 원칙으로 합니다.
+
+핵심 필드 예시:
+
+- `projectId`
+- `taskGroup`
+- `taskId`
+- `taskKey`
+- `projectRoot`
+- `taskType`
+- `workCategory`
+- `taskBriefPath`
+- `relatedTasks`
+- `currentStatus`
+- `taskRootPath`
+- `instructionSetPath`
+- `referenceExpectationsPath`
+- `runsPath`
+- `historyTimelinePath`
+- `latestRunPath`
+- `latestRunStatus`
+- `latestRunPromptsPath`
+- `latestReportPath`
+- `latestResumeCommandPath`
+- `workflow.currentPhase`
+- `workflow.currentPhaseState`
+- `workflow.phaseStates`
+- `workflow.lastCompletedPhase`
+- `workflow.nextRecommendedPhase`
+- `workflow.awaitingApproval`
+- `workflow.routingStatus`
+- `workflow.lastSafeCheckpoint`
+- `inputs`
+- `artifacts`
+- `resultContract`
+- `claudeSession`
+- `fixCycles` *(파생 요약 — `{count, openCycleId, latest:{cycle, symptom, targetReport, closedAt}}`; 매 prepare 재계산)*
+
+이 manifest는 아래 목적을 가집니다.
+
+- Claude가 brief보다 먼저 task continuity를 이해하게 함
+- 어떤 파일을 우선 읽어야 하는지 고정함
+- 어떤 config files와 deployment manifests를 어떤 expected values로 해석해야 하는지 고정함
+- 어떤 task key 아래 결과가 누적되는지 고정함
+- related task와 latest run 위치를 빠르게 확인하게 함
+
+## Task index contract
+
+`task-index.md`는 사람이 빠르게 읽기 위한 요약 문서입니다.
+
+주요 내용:
+- task key
+- current task type
+- work category
+- 현재 task 상태
+- 최신 run 상태
+- current phase
+- current phase state
+- next recommended phase
+- reference expectations
+- latest run
+- latest report
+- resume command
+
+이 문서는 quick summary일 뿐이며 source of truth가 아닙니다.
+canonical metadata는 항상 `task-manifest.json`을 기준으로 확인합니다.
+
+## Run manifest contract
+
+각 실행은 `runs/<task-type>/manifests/run-manifest-<task-type>-<seq>.json`에 현재 run 계약을 남깁니다.
+
+`manifests/run-manifest-<task-type>-<seq>.json`의 path 계열 필드는 모두 대상 프로젝트 루트 기준 상대경로만 저장합니다.
+`okstra`가 Claude handoff를 시작한 직후에는 현재 run 상태가 보통 `in-progress`로 기록됩니다.
+이후 최종 결과 저장과 상태 갱신은 Claude가 이어서 수행합니다.
+또한 `okstra`는 launch 전에 session ID를 선할당하고, 같은 run의 `sessions/` 아래에 `claude-resume-<task-type>-<seq>.sh`를 생성합니다.
+
+주요 내용:
+
+- task key
+- task type
+- work category
+- run datetime segment
+- task brief relative path
+- analysis target
+- related tasks
+- selected workers
+- worker model assignments
+- claude session id
+- resume command relative path
+- expected report relative path
+- expected status relative path
+- prompt snapshot relative path
+- `worker prompt directory relative path`
+- `worker prompt relative path by worker id`
+- current run status
+- workflow snapshot
+- team contract
+- `fixCycleId` *(fix cycle 부착 시에만; 없으면 필드 생략)*
+
+## Timeline contract
+
+`history/timeline.json`은 task에 속한 run 이력을 누적합니다.
+
+이력에는 보통 아래가 포함됩니다.
+
+- run timestamp
+- run directory relative path
+- run manifest relative path
+- run time segment
+- task type
+- work category
+- status
+- worker prompt directory relative path
+- report relative path
+- resume command relative path
+- related tasks
+- workflow snapshot
+- `fixCycleId` *(fix cycle 부착 시에만; 없으면 필드 생략)*
+같은 task-type을 다시 실행하면 같은 `runs/<task-type>/` 폴더를 재사용하더라도 `run-manifest-<task-type>-<seq>.json`과 관련 artifact 경로가 per-category sequence suffix(`<task-type>-<seq>`)로 분리되므로 각 실행이 별도 이력으로 누적됩니다. cross-category 식별자는 manifest의 `runDateTimeSegment` ISO timestamp 필드입니다.
+
+## Claude operating contract
+
+`okstra` 실행 후 Claude는 아래 순서로 현재 task를 읽는 것을 기본 규칙으로 삼아야 합니다.
+
+1. task browsing 또는 task-id disambiguation이 필요하면 `.okstra/discovery/task-catalog.json`을 먼저 읽습니다.
+2. 현재 task key나 task path가 명시되지 않았다면 `.okstra/discovery/latest-task.json`을 current-task pointer로 읽습니다.
+3. `task-manifest.json`을 읽습니다.
+4. current `state/active-run-context-<task-type>-<seq>.json`이 있으면 lead Phase 1의 1차 입력으로 읽습니다. 없으면 current `manifests/run-manifest-<task-type>-<seq>.json`과 `team-state`로 fallback합니다.
+5. `instruction-set/analysis-profile.md`와 `instruction-set/analysis-packet.md`를 읽습니다.
+6. `task-index.md`는 quick summary가 필요할 때만 선택적으로 읽습니다.
+7. `analysis-material.md`, `reference-expectations.md`, `task-brief.md`, `final-report-template.md`는 packet이 불충분하거나 source citation/보고서 작성에 필요할 때 lazy read합니다.
+8. 필요하면 `history/timeline.json`과 이전 run 결과를 참고합니다.
+9. `Claude lead`로서 현재 run의 worker roster (기본 `Claude worker`, `Codex worker`, `Report writer worker`; `Antigravity worker`는 명시 포함된 경우에만)에 따라 역할을 구성합니다.
+10. 각 selected worker prompt를 assigned worker prompt history path로 현재 run의 `prompts/` 아래에 먼저 저장한 뒤 worker를 dispatch합니다.
+14. 각 required worker에 대해 결과 또는 terminal status를 수집합니다.
+15. brief이 더 구체적인 형식을 강제하지 않으면 `final-report-template.md` 구조로 Markdown 최종 보고서를 작성합니다.
+16. 결과를 현재 run의 `reports/final-report-<task-type>-<seq>.md`에 직접 저장하고, 필요하면 `status/final-<task-type>-<seq>.status`, `manifests/run-manifest-<task-type>-<seq>.json`, `task-manifest.json`, `task-index.md`도 현재 상태에 맞게 갱신합니다.
+
+권장 worker 상태값:
+
+- `completed`
+- `timeout`
+- `error`
+- `not-run`
+

package/docs/kr/architecture.md

@@ -40,15 +40,9 @@
   - [표준 task type](#표준-task-type)
   - [Phase 간 정보 전달](#phase-간-정보-전달)
 - (CLI 인자 / 옵션 / 인터랙티브 입력은 [cli.md](cli.md) 참조)
-- [Storage model](#storage-model)
-  - [1. Stable task root](#1-stable-task-root)
-  - [2. Per-run execution artifacts](#2-per-run-execution-artifacts)
-  - [3. Project-level discovery and skill documents](#3-project-level-discovery-and-skill-documents)
-- [Task manifest contract](#task-manifest-contract)
-- [Task index contract](#task-index-contract)
-- [Run manifest contract](#run-manifest-contract)
-- [Timeline contract](#timeline-contract)
-- [Claude operating contract](#claude-operating-contract)
+- [Storage model & contracts](#storage-model--contracts) → [`architecture/storage-model.md`](architecture/storage-model.md)
+  - Stable task root / per-run artifacts / `~/.okstra` 인덱스
+  - Task manifest · task index · run manifest · timeline · Claude operating 계약
 - [Task brief usage](#task-brief-usage)
 - [Recommended workflow](#recommended-workflow)
   - [1. 초안 작성](#1-초안-작성)
@@ -152,7 +146,7 @@ okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_ta
 - [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md) — main okstra lead contract. 런타임 리소스(`~/.okstra/prompts/lead/`)이며 agent skill 이 아닙니다.
 - [`skills/okstra-setup/SKILL.md`](../../skills/okstra-setup/SKILL.md) — **첫 실행 부트스트랩**. `okstra install` + `project.json` 생성.
 - [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md) — **현재 claude 세션 안에서 okstra task 를 시작**하는 in-session 진입점. `prepare_task_bundle` 직접 호출.
-- 사용자 호출 가능 스킬은 `skills/okstra-{setup,brief,run,memory,inspect,schedule}/SKILL.md` 6종뿐이며, 이것만 agent skill home 으로 복사됩니다 — brief 작성, phase 진행, 전역 Memory Book 저장/검색, status/history/report/time/log/cost read-side, schedule 보조. `okstra-inspect logs` 는 codex/antigravity wrapper 가 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` 로 남기는 live-log sidecar 의 인벤토리·정리 안내(read-only), `okstra-inspect cost` 는 `okstra context-cost` 결과 요약입니다.
+- 사용자 호출 가능 스킬은 `skills/okstra-{setup,brief,run,memory,inspect,schedule}/SKILL.md` 6종뿐이며, 이것만 agent skill home 으로 복사됩니다 — brief 작성, phase 진행, 전역 Memory Book 저장/검색, status/history/report/time/logs/cost/errors/recap read-side, schedule 보조. `okstra-inspect` 의 read-side facet 은 `skills/okstra-inspect/SKILL.md` 의 sub-command 표가 정본인 8종입니다. `okstra-inspect logs` 는 codex/antigravity wrapper 가 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` 로 남기는 live-log sidecar 의 인벤토리·정리 안내(read-only), `okstra-inspect cost` 는 `okstra context-cost` 결과 요약, `okstra-inspect errors` 는 task 의 okstra-run 에러 로그를 타임스탬프 markdown error-report 로 모아 렌더하고 요약을 출력, `okstra-inspect recap` 은 task 의 run 간 phase 전·후 요약에 더해 `.okstra` 산출물에 대한 자유 Q&A 까지 답합니다.
 - 내부 운영 계약 — `context-loader` / `team-contract` / `convergence` / `report-writer` 와 lead 계약 — 은 `prompts/lead/*.md` 로, 구현/검증 워커의 언어별 coding preflight 는 `prompts/coding-preflight/*` (overview 라우터 + clean-code + languages/frameworks/architectures 3단계 선택) 로 이동했습니다. 모두 `~/.okstra/prompts/` 에 설치되는 런타임 리소스이며 skill discovery 대상이 아닙니다. generated launch prompt 가 lead 에게 절대 경로를 제공하고, 재설치 시 과거 `okstra-context-loader` / `okstra-team-contract` / `okstra-convergence` / `okstra-report-writer` / `okstra-coding-preflight` / `okstra` skill 디렉터리는 exact-name prune 됩니다.
 - 플러그인 매니페스트: [`../../.claude-plugin/plugin.json`](../../.claude-plugin/plugin.json) — `npx skills@latest add Devonshin/okstra` 보조 채널이 참조. 일반 셋업에는 `npx okstra@latest install` 을 사용한다. 플러그인 매니페스트는 사용자 진입점 6개(`okstra-setup`, `okstra-brief`, `okstra-run`, `okstra-memory`, `okstra-inspect`, `okstra-schedule`)만 노출한다.
 - 설치 위치: `~/.claude/skills/<name>/SKILL.md`, `~/.codex/skills/<name>/SKILL.md`, 또는 fallback `~/.omp/agent/skills/<name>/SKILL.md`.
@@ -428,274 +422,9 @@ okstra-run wizard 는 별도 분기 확인 단계를 두지 않고, 최종 `conf
 
 ---
 
-## Storage model
+## Storage model & contracts
 
-`okstra`가 만드는 파일은 용도에 따라 아래 3개 영역에 나뉘어 저장됩니다.
-
-### 1. Stable task root
-
-task 자체의 기준 폴더입니다.
-task manifest, task index, instruction-set, runs, history가 이 루트 아래에 모입니다.
-
-```text
-<target-project>/.okstra/tasks/<task-group>/<task-id>/
-├── task-manifest.json
-├── task-index.md
-├── instruction-set/
-│   ├── analysis-profile.md
-│   ├── analysis-packet.md       # analysis worker primary compact input
-│   ├── analysis-material.md
-│   ├── reference-expectations.md
-│   ├── task-brief.md
-│   ├── directive.txt                  # optional (mirrors --directive)
-│   ├── final-report-schema.json
-│   ├── final-report-template.md
-│   └── claude-execution-prompt.md
-├── runs/
-│   └── <task-type>/
-│       ├── manifests/
-│       │   └── run-manifest-<task-type>-<seq>.json
-│       ├── state/
-│       │   └── team-state-<task-type>-<seq>.json
-│       ├── prompts/
-│       │   ├── claude-execution-prompt-<task-type>-<seq>.md
-│       │   ├── claude-worker-prompt-<task-type>-<seq>.md
-│       │   ├── codex-worker-prompt-<task-type>-<seq>.md
-│       │   ├── antigravity-worker-prompt-<task-type>-<seq>.md
-│       │   └── report-writer-worker-prompt-<task-type>-<seq>.md
-│       ├── reports/
-│       │   └── final-report-<task-type>-<seq>.md
-│       ├── status/
-│       │   └── final-<task-type>-<seq>.status
-│       ├── sessions/
-│       │   └── claude-resume-<task-type>-<seq>.sh
-│       ├── logs/
-│       │   └── errors-<task-type>-<seq>.jsonl        # optional, lead-only writer
-│       └── worker-results/
-├── history/
-│   ├── timeline.json
-│   └── fix-cycles.jsonl          # optional, fix cycle 진입 시에만 생성 (append-only)
-└── recap/
-    └── recap-log.jsonl          # optional, recap facet 의 전/후 요약·Q&A append-only 로그 (다른 산출물 불변)
-```
-
-실제 디렉터리 세그먼트는 안전한 경로 생성을 위해 slug 형태로 정규화될 수 있습니다.
-하지만 논리 task key는 항상 원래 입력값 기준 `project-id:task-group:task-id`를 유지합니다.
-
-### 2. Per-run execution artifacts
-
-실행별 산출물은 아래 경로에 누적됩니다.
-
-```text
-<target-project>/.okstra/tasks/<task-group>/<task-id>/runs/<task-type>/
-```
-
-여기에 저장되는 대표 파일:
-
-- `manifests/run-manifest-<task-type>-<seq>.json`
-- `state/team-state-<task-type>-<seq>.json`
-- `prompts/claude-execution-prompt-<task-type>-<seq>.md`
-- `prompts/<worker>-worker-prompt-<task-type>-<seq>.md`
-
-그리고 `--render-only`가 아니면 handoff된 Claude session이 보통 아래 결과 파일을 현재 run에 추가합니다.
-- `sessions/claude-resume-<task-type>-<seq>.sh`
-- `reports/final-report-<task-type>-<seq>.md`
-- `reports/final-report-<task-type>-<seq>.slim.md`  *(Phase 7 결정론적 후처리: AI 다음-phase 입력용 슬림 markdown)*
-- `reports/final-report-<task-type>-<seq>.html`     *(Phase 7 결정론적 후처리: 사람 reviewer 용 self-contained HTML, CSS/JS 인라인)*
-- `user-responses/user-response-<task-type>-<seq>.md` *(HTML 의 `Export user response` 버튼이 같은 이름으로 다운로드해 주는 사이드카; 여기 저장해 두면 `--resume-clarification` 이 instruction-set 의 `clarification-response.md` 에 자동 첨부한다 — `clarification_items.clarification_response_with_sidecars`)*
-- `worker-results/<worker>-audit-<task-type>-<seq>.md` *(워커별 Reading Confirmation 사이드카; 본문이 아니라 audit 용)*
-- `status/final-<task-type>-<seq>.status`
-- `carry/stage-<N>.json` *(implementation 전용: stage N 실행 evidence sidecar; 다음 stage 가 자동 carry-in)*
-- `consumers.jsonl` *(implementation-planning 전용: 이 plan 의 각 stage 를 소비한 impl-run 역링크; append-only)*
-최종 결과 파일 (`final-report` MD / status) 은 `okstra`가 stdout을 저장해서 만드는 파일이 아닙니다.
-`okstra`가 준비한 task bundle을 바탕으로 Claude가 현재 run 안에 직접 작성하는 결과물입니다.
-slim MD / HTML 두 view 는 `okstra render-views <final-report.md>` (Phase 7 step 1.5) 가 final-report MD 한 본을 입력으로 결정론적으로 생성합니다. 원본 MD 는 view 생성으로 인해 수정되지 않습니다.
-반면 `sessions/claude-resume-<task-type>-<seq>.sh`는 `okstra`가 Claude launch 전에 미리 생성하는 interruption recovery helper입니다.
-
-run directory는 task-type 단위로 task 실행 이력을 모으고, 내부를 `manifests/`, `state/`, `prompts/`, `reports/`, `status/`, `sessions/`, `worker-results/`처럼 유형별 하위 폴더로 나눈 뒤 각 run-level artifact와 result 파일을 `-<task-type>-<seq>` suffix(per-category 3-digit zero-padded counter, 예: `001`, `002`)로 구분합니다.
-worker prompt history는 `/tmp`가 아니라 항상 현재 run의 `prompts/` 아래 canonical artifact로 남깁니다.
-이전처럼 `analysis-profile.md`, `analysis-material.md`, `reference-expectations.md`, `task-brief.md`, skill 복사본, `final-report-template.md`를 run마다 중복 저장하지 않습니다.
-이 자료들은 stable task root의 `instruction-set/`에 canonical copy를 유지합니다.
-같은 task-type으로 다시 실행하면 동일한 `runs/<task-type>/` 폴더를 재사용하지만, 유형별 하위 폴더 아래에서 run-level 파일명이 `-<task-type>-<seq>` suffix로 분리되므로 기존 산출물을 덮어쓰지 않습니다. `<seq>`는 카테고리 디렉토리(`manifests/`, `prompts/`, `reports/`, `status/`, `state/`, `sessions/`, `worker-results/`)별로 독립 스캔되므로 같은 run에서도 카테고리별 값이 다를 수 있습니다.
-이전 flat legacy artifact가 task-type run 폴더 최상위에 남아 있으면 다음 실행 시 해당 유형별 하위 폴더로 자동 정리합니다.
-
-### 3. Project-level discovery and skill documents
-프로젝트 공용 discovery pointer는 아래 경로에 생성합니다.
-
-```text
-<target-project>/.okstra/discovery/latest-task.json
-<target-project>/.okstra/discovery/task-catalog.json
-```
-scripts/okstra.sh workflow가 사용하는 project-local Claude assets는 아래 경로들에 seed합니다.
-
-```text
-<target-project>/.claude/skills/okstra/SKILL.md
-<target-project>/.claude/skills/<sub-skill>/SKILL.md
-<target-project>/.claude/agents/<agent>.md
-```
-
-역할 구분:
-
-- `.okstra/discovery/latest-task.json`: 현재 프로젝트에서 가장 최근에 준비된 okstra task bundle을 가리키는 current-task convenience pointer
-- `.okstra/discovery/task-catalog.json`: 현재 프로젝트에 준비된 okstra task bundle 목록을 `taskKey`, `taskGroup`, `taskId` 기준으로 유지하는 canonical project-level catalog
-- `instruction-set/reference-expectations.md`: 현재 task가 참조해야 할 config files, deployment manifests, expected values를 task-level canonical artifact로 정리한 파일
-- `~/.claude/skills/okstra-*/...`, `~/.codex/skills/okstra-*/...`, `~/.omp/agent/skills/okstra-*/...`, `~/.claude/agents/...`: `okstra install` 이 사용자 홈에 seed하는 skill/agent asset (project-local 시딩은 더 이상 발생하지 않음 — `okstra install --refresh` 로 갱신)
-
-이전의 아래 파일들은 더 이상 okstra 생성 대상이 아닙니다.
-
-- `CLAUDE.md`
-- `.project-docs/ai/claude-project-guide.md`
-- `.project-docs/ai/claude-skill-index.md`
-- `.project-docs/ai/okstra/okstra-guide.md`
-- `.project-docs/ai/okstra/worker-catalog.md`
-
-## Task manifest contract
-
-`task-manifest.json`은 Claude가 task continuity를 이해할 때 기준이 되는 canonical metadata 파일입니다.
-이 manifest는 `projectRoot` 절대경로를 한 번만 기록하고, 나머지 생성 경로들은 가능한 한 project-relative field로 정리하는 것을 기본 원칙으로 합니다.
-
-핵심 필드 예시:
-
-- `projectId`
-- `taskGroup`
-- `taskId`
-- `taskKey`
-- `projectRoot`
-- `taskType`
-- `workCategory`
-- `taskBriefPath`
-- `relatedTasks`
-- `currentStatus`
-- `taskRootPath`
-- `instructionSetPath`
-- `referenceExpectationsPath`
-- `runsPath`
-- `historyTimelinePath`
-- `latestRunPath`
-- `latestRunStatus`
-- `latestRunPromptsPath`
-- `latestReportPath`
-- `latestResumeCommandPath`
-- `workflow.currentPhase`
-- `workflow.currentPhaseState`
-- `workflow.phaseStates`
-- `workflow.lastCompletedPhase`
-- `workflow.nextRecommendedPhase`
-- `workflow.awaitingApproval`
-- `workflow.routingStatus`
-- `workflow.lastSafeCheckpoint`
-- `inputs`
-- `artifacts`
-- `resultContract`
-- `claudeSession`
-- `fixCycles` *(파생 요약 — `{count, openCycleId, latest:{cycle, symptom, targetReport, closedAt}}`; 매 prepare 재계산)*
-
-이 manifest는 아래 목적을 가집니다.
-
-- Claude가 brief보다 먼저 task continuity를 이해하게 함
-- 어떤 파일을 우선 읽어야 하는지 고정함
-- 어떤 config files와 deployment manifests를 어떤 expected values로 해석해야 하는지 고정함
-- 어떤 task key 아래 결과가 누적되는지 고정함
-- related task와 latest run 위치를 빠르게 확인하게 함
-
-## Task index contract
-
-`task-index.md`는 사람이 빠르게 읽기 위한 요약 문서입니다.
-
-주요 내용:
-- task key
-- current task type
-- work category
-- 현재 task 상태
-- 최신 run 상태
-- current phase
-- current phase state
-- next recommended phase
-- reference expectations
-- latest run
-- latest report
-- resume command
-
-이 문서는 quick summary일 뿐이며 source of truth가 아닙니다.
-canonical metadata는 항상 `task-manifest.json`을 기준으로 확인합니다.
-
-## Run manifest contract
-
-각 실행은 `runs/<task-type>/manifests/run-manifest-<task-type>-<seq>.json`에 현재 run 계약을 남깁니다.
-
-`manifests/run-manifest-<task-type>-<seq>.json`의 path 계열 필드는 모두 대상 프로젝트 루트 기준 상대경로만 저장합니다.
-`okstra`가 Claude handoff를 시작한 직후에는 현재 run 상태가 보통 `in-progress`로 기록됩니다.
-이후 최종 결과 저장과 상태 갱신은 Claude가 이어서 수행합니다.
-또한 `okstra`는 launch 전에 session ID를 선할당하고, 같은 run의 `sessions/` 아래에 `claude-resume-<task-type>-<seq>.sh`를 생성합니다.
-
-주요 내용:
-
-- task key
-- task type
-- work category
-- run datetime segment
-- task brief relative path
-- analysis target
-- related tasks
-- selected workers
-- worker model assignments
-- claude session id
-- resume command relative path
-- expected report relative path
-- expected status relative path
-- prompt snapshot relative path
-- `worker prompt directory relative path`
-- `worker prompt relative path by worker id`
-- current run status
-- workflow snapshot
-- team contract
-- `fixCycleId` *(fix cycle 부착 시에만; 없으면 필드 생략)*
-
-## Timeline contract
-
-`history/timeline.json`은 task에 속한 run 이력을 누적합니다.
-
-이력에는 보통 아래가 포함됩니다.
-
-- run timestamp
-- run directory relative path
-- run manifest relative path
-- run time segment
-- task type
-- work category
-- status
-- worker prompt directory relative path
-- report relative path
-- resume command relative path
-- related tasks
-- workflow snapshot
-- `fixCycleId` *(fix cycle 부착 시에만; 없으면 필드 생략)*
-같은 task-type을 다시 실행하면 같은 `runs/<task-type>/` 폴더를 재사용하더라도 `run-manifest-<task-type>-<seq>.json`과 관련 artifact 경로가 per-category sequence suffix(`<task-type>-<seq>`)로 분리되므로 각 실행이 별도 이력으로 누적됩니다. cross-category 식별자는 manifest의 `runDateTimeSegment` ISO timestamp 필드입니다.
-
-## Claude operating contract
-
-`okstra` 실행 후 Claude는 아래 순서로 현재 task를 읽는 것을 기본 규칙으로 삼아야 합니다.
-
-1. task browsing 또는 task-id disambiguation이 필요하면 `.okstra/discovery/task-catalog.json`을 먼저 읽습니다.
-2. 현재 task key나 task path가 명시되지 않았다면 `.okstra/discovery/latest-task.json`을 current-task pointer로 읽습니다.
-3. `task-manifest.json`을 읽습니다.
-4. current `state/active-run-context-<task-type>-<seq>.json`이 있으면 lead Phase 1의 1차 입력으로 읽습니다. 없으면 current `manifests/run-manifest-<task-type>-<seq>.json`과 `team-state`로 fallback합니다.
-5. `instruction-set/analysis-profile.md`와 `instruction-set/analysis-packet.md`를 읽습니다.
-6. `task-index.md`는 quick summary가 필요할 때만 선택적으로 읽습니다.
-7. `analysis-material.md`, `reference-expectations.md`, `task-brief.md`, `final-report-template.md`는 packet이 불충분하거나 source citation/보고서 작성에 필요할 때 lazy read합니다.
-8. 필요하면 `history/timeline.json`과 이전 run 결과를 참고합니다.
-9. `Claude lead`로서 현재 run의 worker roster (기본 `Claude worker`, `Codex worker`, `Report writer worker`; `Antigravity worker`는 명시 포함된 경우에만)에 따라 역할을 구성합니다.
-10. 각 selected worker prompt를 assigned worker prompt history path로 현재 run의 `prompts/` 아래에 먼저 저장한 뒤 worker를 dispatch합니다.
-14. 각 required worker에 대해 결과 또는 terminal status를 수집합니다.
-15. brief이 더 구체적인 형식을 강제하지 않으면 `final-report-template.md` 구조로 Markdown 최종 보고서를 작성합니다.
-16. 결과를 현재 run의 `reports/final-report-<task-type>-<seq>.md`에 직접 저장하고, 필요하면 `status/final-<task-type>-<seq>.status`, `manifests/run-manifest-<task-type>-<seq>.json`, `task-manifest.json`, `task-index.md`도 현재 상태에 맞게 갱신합니다.
-
-권장 worker 상태값:
-
-- `completed`
-- `timeout`
-- `error`
-- `not-run`
+`okstra` 산출물의 3개 저장 영역(stable task root / per-run artifacts / `~/.okstra` 인덱스)과 task manifest · task index · run manifest · timeline · Claude operating 계약의 전체 스펙은 분리된 문서로 옮겼습니다 — [`architecture/storage-model.md`](architecture/storage-model.md).
 
 ## Task brief usage
 

package/docs/kr/cli.md

@@ -322,7 +322,7 @@ Lead runtime independence boundary:
 
 ### Runtime auto-detection (`auto`)
 
-`okstra run` 의 기본 runtime은 `auto` 입니다. `auto` 는 host 기반으로 `claude-code`, `codex`, `external` 중 하나로 resolve 됩니다 (`src/runtime-resolver.mjs`). 우선순위: 명시 runtime > `OKSTRA_RUNTIME_HOST` env > Claude Code skill handoff > tmux 가용 시 external > 그 외 fail-fast (safe fallback: 의도와 다른 runtime 으로 조용히 넘어가지 않음).
+`okstra run` 의 기본 runtime은 `auto` 입니다. `auto` 는 host 기반으로 `claude-code`, `codex`, `external` 중 하나로 resolve 됩니다 (`src/lib/runtime-resolver.mjs`). 우선순위: 명시 runtime > `OKSTRA_RUNTIME_HOST` env > Claude Code skill handoff > tmux 가용 시 external > 그 외 fail-fast (safe fallback: 의도와 다른 runtime 으로 조용히 넘어가지 않음).
 
 - Claude Code 안에서는 `/okstra-run` 이 front door 입니다. bare `okstra run` 은 Claude Code `TeamCreate` / `Agent(...)` 를 호출할 수 없습니다.
 - Codex host: `okstra run` 이 `codex-run` -> `codex-dispatch` 를 orchestration 합니다.