okstra 0.1.0 → 0.3.0

package/README.md

@@ -1,36 +1,1299 @@
-# okstra
+# OKSTRA Usage Manual
 
-Runtime installer and path resolver for [okstra](https://github.com/Devonshin/okstra) cross-verification skills.
+## At a glance
 
-This package is **not** the okstra skills themselves. It carries the python and bash runtime that the skills depend on, and exposes commands that the skills invoke to discover where everything lives.
+`okstra`는 Claude Code의 cross-verify 워크플로를 위한 **task bundle 준비 도구**입니다. 단일 파일 리뷰 도구가 아니라, stable task key를 중심으로 task brief · profile · prompt · run history · project-level discovery metadata를 정형화해 Claude가 안정적으로 lead/worker orchestration을 수행할 수 있도록 돕는 보조 러너입니다.
 
-## Companion: skills
+핵심 기능을 한눈에 정리하면 다음과 같습니다.
 
-Skills are distributed separately through the `skills` CLI:
+- **Task identity**: `<project-id>/<task-group>/<task-id>` 기반 stable task key로 task root를 생성하거나 재사용하고, manifest · index · timeline을 일관되게 갱신합니다.
+- **Task type별 profile**: `requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification` 등 표준 task type 프로파일을 로드해 instruction-set을 렌더링합니다.
+- **Run lifecycle**: 매 실행마다 per-run 디렉터리(`runs/<timestamp>/`)에 prompt snapshot, sessions/, expected-state, final report 템플릿, run manifest, timeline 이벤트를 저장합니다.
+- **Single python authority**: 모든 prepare wiring(profile/workers/model 해소, path 계산, 9개 render, central record_start)이 [`okstra_ctl.run.prepare_task_bundle()`](scripts/okstra_ctl/run.py) 한 함수에 모여 있습니다. `okstra.sh` 와 `okstra-run` skill 은 같은 함수를 호출하는 thin caller 이며, 환경 변수로 상태를 전달하지 않습니다 — task 정체성·경로·workflow 상태는 모두 디스크 권위 파일에서 매번 계산됩니다.
+- **Claude handoff (두 모드)**: (a) `okstra.sh` 가 새 `claude` 프로세스를 띄우는 전통 방식, (b) `okstra-run` skill 이 현재 claude 세션 안에서 prepare 후 lead 역할을 그대로 인계받는 in-session 모드. 둘 다 `prepare_task_bundle` 의 산출물(instruction-set 등)을 그대로 사용합니다.
+- **Required team contract**: `Claude lead` + `Claude worker` · `Codex worker` · `Gemini worker` · `Report writer worker`의 필수 구성과 Agent Teams 우선 시도를 강제합니다.
+- **User-home install + project-local task bundles**: `npx okstra@latest install` 한 명령이 런타임(`~/.okstra/{lib/python, bin}`) + 스킬 마크다운(`~/.claude/skills/<name>/SKILL.md`) 을 모두 깐다. 대상 프로젝트에는 task bundle 과 discovery metadata 만 `.project-docs/okstra/` 아래 저장됩니다 — 사용자의 `~/.claude/settings.json` 이나 프로젝트 `.claude/settings.local.json` 은 건드리지 않으며, per-session permission 은 `claude --settings` 로 런타임 주입합니다. (개발용으로는 `okstra-install.sh` 가 `--link` 모드 symlink 설치를 제공합니다.)
+- **Resume and clarification**: `--task-key`, `--resume-clarification`, `--clarification-response`로 같은 task 재개와 lead의 추가 질문 응답 흐름을 지원합니다.
+- **Optional integrations**: worker error sidecar, token usage / cost accounting을 옵션으로 제공합니다.
+
+판단 정책과 worker orchestration은 Claude lead가 담당하고, `okstra`는 Claude가 잘 일할 수 있는 정형화된 입력 묶음과 출력 골격을 준비하는 역할에 집중합니다.
+
+## Table of contents
+
+- [Purpose](#purpose)
+- [What okstra does](#what-okstra-does)
+- [Runtime assets vs support assets](#runtime-assets-vs-support-assets)
+- [Architecture: python authority + thin callers](#architecture-python-authority--thin-callers)
+- [Claude execution behavior](#claude-execution-behavior)
+- [Claude prompt contract](#claude-prompt-contract)
+- [Required team contract](#required-team-contract)
+- [Stable task identity](#stable-task-identity)
+- [Project self-registration](#project-self-registration)
+- [Task type](#task-type)
+  - [표준 task type](#표준-task-type)
+  - [Phase 간 정보 전달](#phase-간-정보-전달)
+- [Command forms](#command-forms)
+- [Required arguments](#required-arguments)
+  - [`--project-id`](#--project-id)
+  - [`--task-group`](#--task-group)
+  - [`--task-id`](#--task-id)
+  - [`--task-type`](#--task-type)
+  - [`--task-brief`](#--task-brief)
+  - [`--yes`](#--yes)
+- [Optional arguments and options](#optional-arguments-and-options)
+  - [`--task-key`](#--task-key)
+  - [`--clarification-response`](#--clarification-response)
+  - [`--resume-clarification`](#--resume-clarification)
+  - [`--project-root`](#--project-root)
+  - [`--directive`](#--directive)
+  - [`--workers`](#--workers)
+  - [`--claude-model`](#--claude-model)
+  - [`--lead-model`](#--lead-model)
+  - [`--codex-model`](#--codex-model)
+  - [`--gemini-model`](#--gemini-model)
+  - [`--report-writer-model`](#--report-writer-model)
+  - [`--related-tasks`](#--related-tasks)
+  - [`--render-only`](#--render-only)
+  - [`--refresh-assets`](#--refresh-assets)
+- [Interactive input flow](#interactive-input-flow)
+- [Confirmation flow](#confirmation-flow)
+- [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)
+- [Task brief usage](#task-brief-usage)
+- [Recommended workflow](#recommended-workflow)
+  - [1. 초안 작성](#1-초안-작성)
+  - [2. 정식 brief 작성](#2-정식-brief-작성)
+  - [2.5. 필요 시 요구사항 triage](#25-필요-시-요구사항-triage)
+  - [3. Render-only 검증](#3-render-only-검증)
+  - [4. Claude 실행](#4-claude-실행)
+  - [5. 필요 시 에러 분석](#5-필요-시-에러-분석)
+  - [5.5. 답변 후 즉시 재실행](#55-답변-후-즉시-재실행)
+  - [6. 필요 시 구현 계획 검토](#6-필요-시-구현-계획-검토)
+  - [7. 승인된 plan 기반 구현](#7-승인된-plan-기반-구현)
+  - [8. 구현 후 최종 검토](#8-구현-후-최종-검토)
+  - [9. 같은 task 재개](#9-같은-task-재개)
+- [Lifecycle status and resume](#lifecycle-status-and-resume)
+- [Preferred final report structure](#preferred-final-report-structure)
+- [Worker error collection (optional sidecar)](#worker-error-collection-optional-sidecar)
+- [Token usage and cost accounting](#token-usage-and-cost-accounting)
+- [Practical notes](#practical-notes)
+- [Related documents](#related-documents)
+
+## Purpose
+
+이 문서는 `Okstra` 기준의 `okstra` 사용법을 task-key 중심으로 정리한 운영 가이드입니다.
+`README.md`가 빠른 진입점이라면, 이 문서는 `okstra`의 실행 계약과 storage model, lifecycle, Claude handoff 규칙을 설명하는 상세 기준 문서입니다.
+
+`okstra`는 단일 파일 리뷰 도구가 아닙니다.
+`okstra`는 Claude Code가 cross verify를 수행할 수 있도록 안정적인 task bundle, run history, project-level discovery metadata를 준비하는 보조 도구입니다.
+
+## What okstra does
+
+okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_task_bundle`](scripts/okstra_ctl/run.py) 에 모여 있습니다. 이 함수가 다음을 한 트랜잭션으로 수행합니다.
+
+- okstra 설치 자산(`~/.claude/skills/okstra/...`, `~/.claude/agents/...`, `~/.okstra/bin/...`) 존재 확인
+- `<PROJECT_ROOT>/.project-docs/okstra/project.json` self-registration (또는 projectId 일치 검증)
+- task type → `prompts/profiles/<task-type>.md` 로드 + 권장 workers 추출
+- 사용자 worker/model 오버라이드 정규화 (Claude/Codex/Gemini/Report-writer 각각 display ↔ execution-value 매핑)
+- task brief / clarification response 경로 해석 (cwd 우선 → PROJECT_ROOT fallback)
+- per-task mutex(`~/.okstra/.locks/<task-key>.lock`) 안에서 stable task root + 모든 path/seq 계산 후 `<run-dir>/manifests/run-context-<seq>.json` 으로 영속화
+- 사용자 입력을 `<run-dir>/manifests/run-inputs-<seq>.json` 으로 영속화
+- instruction-set 9 파일 렌더 (`analysis-profile.md`, `analysis-material.md`, `task-brief.md`, `reference-expectations.md`, `final-report-template.md`, `clarification-response.md`, `directive.txt`, `claude-execution-prompt.md`, lead prompt snapshot)
+- `task-manifest.json` · `task-index.md` · `run-manifest-*.json` · `history/timeline.json` · `discovery/{latest-task,task-catalog}.json` 갱신
+- preassigned Claude session ID + `sessions/claude-resume-*.sh` 작성 (`--render-only` 가 아닐 때)
+- 중앙 인덱스(`~/.okstra/{active,recent}.jsonl`, `projects/<id>/{index.jsonl, meta.json}`) record_start
+
+`prepare_task_bundle` 의 두 caller:
+
+1. **`scripts/okstra.sh`**: CLI 인자를 파싱·확인하고 → `prepare_task_bundle` 호출 → `--render-only` 가 아니면 `claude --model ... --session-id ... "$PROMPT"` 를 `exec` 으로 띄움. ~160 줄의 thin wrapper.
+2. **`okstra-run` skill**: 같은 claude 세션 안에서 `AskUserQuestion` 으로 인자를 모은 뒤 → `prepare_task_bundle(render_only=True)` 직접 호출 → 렌더된 lead prompt 를 현재 세션이 그대로 읽어 lead 역할 수행. 새 claude 프로세스를 띄우지 않음.
+
+판단 정책과 worker orchestration 은 lead claude 가 담당하고, okstra 의 prepare 단계는 그 lead 가 정확한 입력 묶음과 출력 골격을 받아 일을 시작할 수 있게 정형화된 자산을 준비할 뿐입니다.
+
+## Runtime assets vs support assets
+
+런타임 진입점은 python 패키지에 모여 있고, bash 와 skill 은 거기로 호출만 보냅니다.
+
+### Python module 진입점 (single authority)
+
+- [`okstra_ctl.run`](scripts/okstra_ctl/run.py) — `prepare_task_bundle()` orchestrator + argparse CLI (`python3 -m okstra_ctl.run --workspace-root ... --project-root ... ...`).
+- [`okstra_ctl.paths`](scripts/okstra_ctl/paths.py) — `compute_run_paths()` pure path/seq 계산.
+- [`okstra_ctl.run_context`](scripts/okstra_ctl/run_context.py) — `compute_and_write_run_context()`, `write_run_inputs()`, per-task mutex.
+- [`okstra_ctl.render`](scripts/okstra_ctl/render.py) — task-manifest / run-manifest / timeline / task-index / team-state / launch.template / reference-expectations / discovery 9개 render 함수 + `python3 -m okstra_ctl.render <subcommand>` dispatcher.
+- [`okstra_ctl.workers`](scripts/okstra_ctl/workers.py) · [`okstra_ctl.models`](scripts/okstra_ctl/models.py) — worker / model 해소.
+- [`okstra_ctl.workflow`](scripts/okstra_ctl/workflow.py) — phase rules (PHASE_ALLOWED_OUTPUTS / PHASE_FORBIDDEN_ACTIONS).
+- [`okstra_ctl.material`](scripts/okstra_ctl/material.py) — `analysis-material.md` 본문 + related-tasks 빌더.
+- [`okstra_ctl.session`](scripts/okstra_ctl/session.py) · [`okstra_ctl.seeding`](scripts/okstra_ctl/seeding.py) — Claude session id / resume command / 설치 검증 / runtime settings.
+- [`okstra_ctl.{ids,index,invocation,jsonl,project_meta,reconcile,resolver,sequence,batch,backfill,listing,locks,tmux}`](scripts/okstra_ctl/) — 중앙 인덱스 (`~/.okstra`) 의 기존 모듈군.
+- [`okstra_project.{resolver,state}`](scripts/okstra_project/) — PROJECT_ROOT 해석 + project.json upsert + task-catalog/manifest reader.
+
+### Bash entry points (thin)
+
+- [`scripts/okstra.sh`](scripts/okstra.sh) ~160 줄. CLI 파싱 / interactive prompt / confirm-execution-plan / `prepare_task_bundle` 호출 / `exec claude`.
+- [`scripts/lib/okstra/{cli,globals,interactive,project-resolver,usage}.sh`](scripts/lib/okstra/) — CLI/인터랙티브 보조만. 산출물 생성 로직 보유 없음.
+- [`scripts/okstra-ctl.sh`](scripts/okstra-ctl.sh) + [`scripts/lib/okstra-ctl/`](scripts/lib/okstra-ctl/) — 중앙 컨트롤 센터 CLI (list / show / open / rerun / reconcile / 등).
+
+### Claude assets (templates + skills)
+
+- `prompts/launch.template.md` — lead 프롬프트 템플릿.
+- `prompts/profiles/*.md` — 5종 task-type profile.
+- `templates/project-docs/task-index.template.md` · `templates/reports/final-report.template.md` · `templates/reports/settings.template.json` — 런타임 렌더 입력.
+- `<PROJECT_ROOT>/.project-docs/okstra/project.json` — 프로젝트 self-registration. okstra.sh 첫 실행 시 자동 생성/검증되며, `--project-root` 미지정 시 ancestor / `git toplevel` 로 PROJECT_ROOT 해석.
+
+### Support assets (런타임 비참조)
+
+- `templates/reports/*-input.template.md` — 사용자 입력 작성 보조.
+- `validators/validate-workflow.sh`, `validators/validate-schedule.py`, `validators/validate-run.py` — 수동/CI 검증용. `validate-run.py` 의 경로는 run metadata 에 기록.
+
+### Skills (`skills/`, `agents/`)
+
+- [`agents/SKILL.md`](agents/SKILL.md) — main okstra skill (cross-verify 트리거).
+- [`skills/setup-okstra/SKILL.md`](skills/setup-okstra/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-{status,history,convergence,schedule,context-loader,team-contract,report-finder,report-writer,time-summary}/SKILL.md` — phase 진행·status·history 보조 skill.
+- 플러그인 매니페스트: [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) — `npx skills@latest add Devonshin/okstra` 보조 채널이 참조. 0.3.0 부터는 `npx okstra install` 한 명령이 동일 결과를 보장하므로 일반 셋업에는 이 채널이 필요 없다.
+- 설치 위치: `~/.claude/skills/<name>/SKILL.md` (`okstra-install.sh` dev 설치, 또는 위 npx 채널).
+- 릴리스 절차: [`RELEASING.md`](RELEASING.md) — npm publish 흐름과 GitHub Actions 워크플로(`v*.*.*` tag → 자동 publish), 자동화 토큰 셋업, 검증/롤백.
+
+## Architecture: python authority + thin callers
+
+okstra 의 prepare 단계는 디스크 권위 + 단일 python 진입점 모델을 따릅니다. 이 설계가 두 가지 목표를 동시에 만족합니다.
+
+1. **Claude Code 의 병렬 실행과 호환**: 같은 claude 세션이 subagent / 병렬 Bash tool / 백그라운드 작업으로 여러 자식을 띄워도 환경 변수가 공유 변경되지 않으므로 race 가 발생하지 않습니다.
+2. **bash CLI 와 in-session skill 의 동작 동일성**: `okstra.sh` 와 `okstra-run` skill 이 같은 `prepare_task_bundle()` 을 부르기 때문에 산출물·중앙 인덱스 등록·검증 경로가 같습니다.
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│ Two callers, one authority                                     │
+├────────────────────────────────────────────────────────────────┤
+│                                                                │
+│ scripts/okstra.sh         skills/okstra-run/SKILL.md           │
+│ (CLI: bash 인자 파싱)     (current claude 세션 안 AskUserQuestion) │
+│      │                              │                          │
+│      └─────────────┬────────────────┘                          │
+│                    ▼                                           │
+│        okstra_ctl.run.prepare_task_bundle()                    │
+│        (single python function — 산출물 전부 책임)             │
+│                    │                                           │
+│       ┌────────────┴────────────────┐                          │
+│       ▼                             ▼                          │
+│  on-disk authority             ~/.okstra (central index)       │
+│  <PROJECT_ROOT>/.project-docs/  per-task mutex + record_start  │
+└────────────────────────────────────────────────────────────────┘
+```
+
+### State authority on disk
+
+per-process 환경 변수에 task 정체성·경로·workflow 상태를 보관하지 않습니다. 모든 reader 는 다음 파일에서 매번 계산합니다.
+
+| 데이터 | 권위 파일 |
+|---|---|
+| projectId, projectRoot | `<PROJECT_ROOT>/.project-docs/okstra/project.json` |
+| task identity / workflow | `<task-root>/task-manifest.json` |
+| task 후보 목록 | `<PROJECT_ROOT>/.project-docs/okstra/discovery/task-catalog.json` |
+| 최신 task 포인터 | `<PROJECT_ROOT>/.project-docs/okstra/discovery/latest-task.json` |
+| run 입력값 | `<run-dir>/manifests/run-inputs-<task-type>-<seq>.json` |
+| run paths / seq | `<run-dir>/manifests/run-context-<task-type>-<seq>.json` |
+| run 이력 | `<task-root>/history/timeline.json` |
+| 글로벌 인덱스 | `~/.okstra/{active,recent}.jsonl`, `~/.okstra/projects/<id>/{index.jsonl, meta.json}` |
+
+### Concurrency
+
+두 종류의 파일 락이 모든 동시성을 처리합니다.
+
+- `~/.okstra/.locks/<task-key>.lock` — per-task mutex. `compute_and_write_run_context` 가 seq 계산과 `run-context.json` 영속화를 한 트랜잭션으로 묶음. 같은 task 의 두 호출은 직렬화.
+- `~/.okstra/.lock` — 중앙 인덱스 mutex. `record_start` / `reconcile` / `rotate_recent_if_needed` 에서 사용.
+
+다른 (project, task-group, task-id) 사이에는 직렬화가 없습니다 — 디스크 경로가 분리되므로 충돌 자체가 없음. 환경 변수 race 가 사라졌으므로 같은 claude 세션이 여러 task 를 병렬 진행해도 안전.
+
+### Allowed env vars (사용자 knob 한정)
+
+상태 전달 용도가 아닌, 사용자 설정용으로만 다음 env var 를 읽습니다.
+
+- `OKSTRA_HOME` — 중앙 디렉터리 위치 override (기본 `~/.okstra`).
+- `OKSTRA_DEFAULT_LEAD_MODEL`, `OKSTRA_DEFAULT_CLAUDE_MODEL`, `OKSTRA_DEFAULT_CODEX_MODEL`, `OKSTRA_DEFAULT_GEMINI_MODEL`, `OKSTRA_DEFAULT_REPORT_WRITER_MODEL` — 모델 default.
+- `OKSTRA_TOOL_NAME`, `OKSTRA_COMMAND_NAME` — usage 출력의 표시 이름.
+- `OKSTRA_RUN_SEQ_OVERRIDE` — okstra-ctl rerun / 테스트 hook 이 강제하는 run-seq (per-process).
+
+이 외의 `PROJECT_ID`, `TASK_GROUP`, `RUN_*`, `FINAL_*`, `CLAUDE_*` 등은 export 하지 않으며, 자식 프로세스로 leak 되지 않습니다.
+
+## Claude execution behavior
+
+현재 구현 기준으로 `okstra`의 Claude 실행 방식은 아래와 같습니다.
+
+**Mode A — `okstra.sh` 가 새 claude 프로세스를 띄움**
+- `--render-only`를 사용하면 Claude를 실행하지 않고 instruction-set 만 만든 뒤 종료합니다.
+- `--render-only`가 없으면 prepare 단계가 Claude session ID 를 선할당하고 current run 의 `sessions/` 아래에 `claude-resume-<task-type>-<seq>.sh` 를 생성합니다.
+- 이후 대상 프로젝트 루트에서 resolved `Claude lead` model execution value 로 `claude --model <lead> --session-id "$CLAUDE_SESSION_ID" --settings <runtime-settings> "$PROMPT"` 를 `exec` 합니다.
+- `okstra.sh` 는 handoff 까지만 수행하고, 최종 보고서 저장과 run/task 상태 갱신은 Claude lead 가 이어서 수행합니다.
+
+**Mode B — `okstra-run` skill 이 현재 claude 세션 안에서 인계**
+- 사용자가 이미 claude 세션에 있고 거기서 새 okstra task 를 시작하고 싶을 때 사용합니다.
+- skill 이 `AskUserQuestion` 으로 task 후보·task-type·brief 등을 받고 `prepare_task_bundle(render_only=True)` 를 호출해 동일한 instruction-set 을 디스크에 만듭니다.
+- 새 claude 프로세스는 띄우지 않고, 현재 세션이 렌더된 lead prompt 를 읽어 lead 역할로 즉시 진입합니다.
+
+두 모드 모두 동일한 산출물(task-manifest, run-manifest, timeline, instruction-set, central index 등록) 을 만들며, `okstra-ctl` 의 후속 명령(list / show / rerun / reconcile)은 산출물 차이를 알지 못한 채 일관되게 동작합니다.
+- handoff된 메인 Claude는 `Claude lead`로 동작하며 orchestration과 final synthesis를 담당합니다.
+- standard workflow의 required worker role은 `Claude worker`, `Codex worker`, `Gemini worker`, `Report writer worker`입니다.
+- worker 역할 분담과 최종 판단은 Claude가 task bundle을 읽고 수행합니다.
+- 사용자 홈에 설치된 okstra Claude assets(`~/.claude/skills`, `~/.claude/agents`) 는 Agent Teams 를 우선 시도하고, 팀 구성이 불가능할 때만 sequential/background fallback 을 사용하도록 Claude 를 유도합니다.
+
+## Claude prompt contract
+
+Claude launch prompt 본문은 항상 `prompts/launch.template.md` 템플릿에서만 렌더링됩니다.
+
+- 프롬프트 치환은 task key, session ID, 절대/상대 경로 같은 scalar placeholder 값으로만 제한합니다.
+- 선택된 profile 본문은 `instruction-set/analysis-profile.md`로 렌더링합니다.
+- 분석 자료 본문은 `instruction-set/analysis-material.md`로 렌더링합니다.
+- config/deployment expected-state 본문은 `instruction-set/reference-expectations.md`로 렌더링합니다.
+- Claude는 위 artifact 파일들을 직접 읽어야 하며, 긴 task-specific 본문이 launch prompt 안에 inline으로 복제되면 안 됩니다.
+
+## Required team contract
+
+표준 `okstra` workflow는 아래 팀 계약을 runtime prompt, profile, manifest, skill 문서에 공통으로 반영합니다.
+
+- 메인 Claude는 항상 `Claude lead`이며 synthesis-only로 동작합니다.
+- required worker role은 `Claude worker`, `Codex worker`, `Gemini worker`, `Report writer worker`입니다.
+- `Report writer worker`는 보고서 구조화와 근거 정리에 집중하지만 최종 synthesis owner는 여전히 `Claude lead`입니다.
+- 기본 모델 계약은 중앙 기본값에서 계산합니다. 기본 fallback은 `Claude lead`=`opus`, `Claude worker`=`sonnet`, `Codex worker`=`gpt-5.5`, `Gemini worker`=`auto`이며, `Report writer worker`는 별도 override가 없으면 `Claude lead` 모델을 따릅니다(즉, 기본값에서는 `opus`).
+- `Gemini worker`는 반드시 시도해야 합니다.
+- 최종 판단 전에는 각 required worker role별로 결과 또는 명시적인 terminal status(`completed`, `timeout`, `error`, `not-run`)가 필요합니다.
+- 시도된 worker(`completed`, `timeout`, `error`)는 현재 run의 `prompts/` 아래 assigned worker prompt history file을 반드시 가져야 합니다.
+- 이름 없는 generic parallel worker는 required role 대체 수단으로 허용하지 않습니다.
+
+## Stable task identity
+
+`okstra`의 기본 식별자는 아래 조합입니다.
+
+- `project-id`
+- `task-group`
+- `task-id`
+
+논리적 task key는 아래 형식입니다.
+
+```text
+<project-id>:<task-group>:<task-id>
+```
+
+같은 버그를 다시 열거나 같은 작업을 이어서 진행할 때는 같은 `task-group`과 `task-id`를 재사용합니다.
+새로운 unrelated 작업이면 새 `task-group` 또는 새 `task-id`를 사용합니다.
+
+## Project self-registration
+
+`okstra.sh` 는 외부 등록 디렉토리(과거 `examples/projects/*.conf.sh` 모델은 폐기됨) 없이 동작합니다. 매 실행 시작 시 PROJECT_ROOT 를 다음 우선순위로 해석한 뒤 그 위치의 `.project-docs/okstra/project.json` 을 권위 소스로 자기 등록합니다.
+
+해석 우선순위:
+
+1. CLI 인자 `--project-root <path>`.
+2. cwd 또는 그 조상 디렉토리 중 `.project-docs/okstra/project.json` 보유 위치.
+3. cwd 의 `git rev-parse --show-toplevel`.
+
+셋 다 실패하면 `okstra.sh` 는 즉시 에러로 종료합니다 (자동 추정 없음).
+
+`<PROJECT_ROOT>/.project-docs/okstra/project.json` 스키마:
+
+```json
+{
+  "projectId": "fontradar-v2-api",
+  "projectRoot": "/Volumes/Workspaces/workspace/projects/fontradar",
+  "createdAt": "2026-05-10T00:00:00Z",
+  "updatedAt": "2026-05-10T00:00:00Z"
+}
+```
+
+처음 실행이면 위 4-필드를 새로 작성합니다. 이미 존재하면 `--project-id` 인자값과 저장된 `projectId` 가 일치하는지 검증한 뒤 `projectRoot`/`updatedAt` 만 갱신합니다. 불일치 시 즉시 종료해 동일 디렉토리에서 두 개의 ID 가 혼용되는 것을 막습니다.
+
+`okstra-ctl` 의 reindex/backfill 도 신규 모델에서 권위 소스를 변경했습니다. 과거에는 `examples/projects/*.conf.sh` 를 source 했지만, 지금은 `~/.okstra/projects/<projectId>/meta.json` (record_start 가 위 project.json 정보를 mirror 한 결과) 을 스캔하여 (projectId, projectRoot) 매핑을 복원합니다. `OKSTRA_PROJECT_DEFINITION_DIR_OVERRIDE` 환경변수도 함께 폐기되었습니다.
+
+## Task type
+
+`task-type`은 이번 run의 목적과 profile 선택, 그리고 lifecycle phase 라우팅을 동시에 결정합니다.
+
+선택 규칙:
+
+- `--task-type <name>`을 주면 `prompts/profiles/<name>.md`가 task bundle의 `instruction-set/analysis-profile.md`로 렌더링됩니다.
+- 외부 인터페이스 기준 단일 선택자는 `task-type`입니다.
+- 선택된 task type은 task-manifest.json의 `taskType`, `workflow.currentPhase`, `workflow.nextRecommendedPhase`에 그대로 반영됩니다.
+- run directory 경로 세그먼트로도 사용됩니다(`runs/<task-type>/...`).
+
+### 표준 task type
+
+각 task type은 phase별 허용/금지 행동을 강제하며, 한 run은 자기 task type의 산출물만 만들고 다음 phase로 이행하지 않습니다. 다음 phase는 항상 새로운 `okstra.sh` 실행에서 시작합니다.
+
+| task type | 목적 | 핵심 산출물 | 다음 권장 phase | 코드 변경 허용 여부 |
+|---|---|---|---|---|
+| `requirements-discovery` | 요청을 bugfix/feature/refactor/ops/improvement 중 하나로 분류하고 안전한 다음 phase로 라우팅 | work category, routing decision, missing-input list, clarification requests | `pending-routing-decision` (사용자 답변 후 결정) | 금지 |
+| `error-analysis` | 보고된 에러/사고의 증상·원인·재현 갭을 증거 기반으로 분석 | symptom/trigger 정리, root-cause 가설, reproduction gap, validation 경로 | `implementation-planning` | 금지 |
+| `implementation-planning` | 코딩 시작 전 안전한 구현 방향과 옵션을 평가 | 최소 2개 구현 옵션, 영향 파일 목록, trade-off, 단계별 실행 순서, validation/rollback, **User Approval Request** 블록 | `implementation` (사용자 승인 후) | 금지 |
+| `implementation` | 승인된 `implementation-planning` final report의 단계대로 소스 코드를 수정 | commit list, diff summary, out-of-plan edits 블록, validation/TDD evidence, rollback 검증, verifier 결과(Gemini/Codex/Claude) | `final-verification` | 허용 (승인된 plan의 파일 목록 한정, `git push`/publish/deploy/실제 migration 금지) |
+| `final-verification` | 완료된 작업의 잔존 결함·회귀 위험을 점검하고 release 판단 | acceptance verdict, residual risk, follow-up 라우팅(`error-analysis`/`implementation-planning`) | `done-or-follow-up` | 금지 (read-only 테스트만 허용) |
+
+공통 제약:
+
+- `implementation`을 제외한 모든 phase는 source code edit, build, migration, deployment, 그 밖의 state-mutating 명령을 금지합니다(`final-verification`은 read-only 테스트 명령만 허용). `implementation`은 승인된 plan의 파일 목록 안에서만 edit/commit이 허용되며, `git push`·publish·deploy·실제 migration·third-party write API는 여전히 금지됩니다.
+- 사용자가 "다음 단계 진행해" 같은 표현을 보내도, 그 발화만으로 다음 phase가 자동 시작되지 않습니다. 다음 phase는 새 `okstra.sh` 실행으로만 시작합니다.
+- **Authority & permissions assumption (HARD RULE — 모든 task-type 및 `okstra-schedule` 공통)**: 사용자(및 팀)는 예상되는 모든 작업에 대해 완전한 권한·승인 권한을 보유한다고 가정합니다. 외부 승인, 서드파티 액세스, 역할/IAM 권한, 조직적 sign-off, 법무·보안 검토, 벤더 협의, "권한 보유 여부 확인" 같은 항목을 routing 결정·missing inputs·clarification questions·risk·dependency·open questions·effort/day 추정에 포함하지 않습니다. okstra 내부 phase 핸드오프(`User Approval Request` 등)는 사용자 본인이 즉시 승인 가능한 내부 게이트이므로 영향 없으며, `implementation`의 forbidden actions(`git push`, prod deploy, shared-DB migration 등)도 권한 사유가 아닌 **안전 사유**로 계속 적용됩니다.
+- Phase별 상세 규칙은 `prompts/profiles/<task-type>.md`에 정의되어 있고, 그 본문이 그대로 `instruction-set/analysis-profile.md`로 렌더링됩니다.
+
+### Phase 간 정보 전달
+
+- `requirements-discovery` 또는 `error-analysis`가 남긴 final report의 `## 5. Clarification Requests for the Next Run` 섹션에 사용자가 답변을 채운 뒤, 다음 run에서 `--clarification-response <previous-final-report.md>`로 그 파일을 carry-in합니다.
+- carry-in된 파일은 현재 run의 `instruction-set/clarification-response.md`로 복사되고, lead가 Section 0에서 prior `Q*` 행의 `Status`(`resolved` / `obsolete`)를 갱신한 뒤 진행합니다.
+- 답변 편집과 재실행을 한 번에 처리하려면 `--resume-clarification` 모드를 사용합니다. 자세한 동작은 `### --resume-clarification` 섹션을 참고합니다.
+
+
+## Command forms
+
+기본 명령(첫 진입 / full args):
+
+```bash
+scripts/okstra.sh [--render-only] [--yes] [--refresh-assets] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--related-tasks taskA,taskB] [--clarification-response <previous-final-report>] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>]
+```
+
+후속 phase 단축 형식(기존 task-manifest.json이 존재할 때):
+
+```bash
+scripts/okstra.sh --task-key <project-id>:<task-group>:<task-id> [--task-type <task-type>]
+```
+
+Clarification 답변 즉시 재실행:
+
+```bash
+scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>
+```
+
+interactive terminal에서 실행하면 다음 규칙이 추가로 적용됩니다.
+
+- 필수 인자가 비어 있으면 stdin으로 직접 입력을 받습니다.
+- 입력이 모두 준비되면 실행 전 요약을 보여줍니다.
+- `y` 또는 `yes`를 입력했을 때만 실제 생성 또는 실행 단계로 진행합니다.
+- interactive가 아닌 실행에서는 누락 인자를 prompt하지 않고 에러로 종료합니다.
+- `--yes`를 사용하면 prompt와 confirmation을 모두 건너뛰지만, 이때는 모든 필수 인자가 반드시 이미 채워져 있어야 합니다.
+- 우선순위는 `명시적 CLI 인자 > interactive prompt 또는 non-interactive 에러`입니다.
+
+## Required arguments
+
+### `--project-id`
+
+전역에서 고유해야 하는 프로젝트 ID입니다. 첫 실행 시 `<PROJECT_ROOT>/.project-docs/okstra/project.json` 에 자기 등록(self-registration)되며, 동일 PROJECT_ROOT 에서 재실행할 때 인자값과 저장된 `projectId` 가 다르면 즉시 에러로 종료합니다.
+
+예:
+
+- `fontradar-v2-api`
+- `jobs`
+
+### `--task-group`
+
+관련 task를 묶는 논리 그룹입니다.
+
+예:
+
+- `feature-8858`
+- `bugfix-auth`
+- `tasks`
+
+### `--task-id`
+
+같은 그룹 안에서 안정적으로 재사용할 task 식별자입니다.
+
+예:
+
+- `email-recipient-loss`
+- `8852`
+
+### `--task-type`
+
+이번 run의 목적과 profile 선택, run directory 세그먼트, lifecycle phase 라우팅을 결정하는 단일 입력값입니다.
+표준 값과 phase별 책임은 위 [Task type](#task-type) 섹션을 참고합니다.
+
+### `--task-brief`
+
+분석의 기준이 되는 task brief 문서 경로입니다.
+상대 경로는 대상 프로젝트 루트를 기준으로 해석됩니다.
+
+예:
+
+- `.project-docs/linear/feature/8858/okstra-task-brief.md`
+- `.project-docs/tasks/8852/BUG_REPORT.md`
+
+### `--yes`
+
+interactive prompt와 confirmation을 생략합니다.
+
+대신 아래 조건이 강제됩니다.
+
+- `project-id`
+- `task-group`
+- `task-id`
+- `task-type`
+- `brief-path`
+
+즉, 필수 인자가 하나라도 비어 있으면 prompt하지 않고 즉시 종료합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --yes --render-only --task-type error-analysis --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+## Optional arguments and options
+
+### `--task-key`
+
+기존 task에 대한 후속 phase를 시작할 때 `--project-id`/`--task-group`/`--task-id`를 한 번에 전달하는 단축 형식입니다.
+
+- 입력 형식: `<project-id>:<task-group>:<task-id>`
+- 동작:
+  - 세 ID로 split하여 `PROJECT_ID`/`TASK_GROUP`/`TASK_ID`에 채웁니다.
+  - 명시적으로 같은 값들이 함께 들어오면 일치할 때만 허용하고, 충돌하면 즉시 에러로 종료합니다.
+  - 해당 task의 `task-manifest.json`이 존재하면 누락된 `--task-brief`를 manifest의 `taskBriefPath` 로, 누락된 `--task-type`을 `workflow.nextRecommendedPhase` 로 자동 채웁니다.
+  - manifest가 없으면(첫 진입) 기존 누락-인자 검증이 그대로 동작합니다(=full args 강제).
+- 명시적으로 전달된 인자가 항상 manifest 값보다 우선합니다.
+- `nextRecommendedPhase`가 `pending-routing-decision` 또는 `done-or-follow-up`이면 자동 채움하지 않고, 사용자가 명시적으로 `--task-type`을 주거나 brief을 보강한 뒤 다시 실행해야 합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-key jobs:tasks:8852
+```
+
+```bash
+scripts/okstra.sh --task-key jobs:tasks:8852 --task-type final-verification
+```
+
+### `--clarification-response`
+
+이전 run의 final report(`Section 5. Clarification Requests for the Next Run`에 사용자가 답변을 inline으로 채운 파일)를 다음 run으로 carry-in합니다.
+
+- 입력: `<previous-run>/reports/final-report-<task-type>-<seq>.md` 경로
+- 동작: 파일을 현재 run의 `instruction-set/clarification-response.md`로 복사하고, lead가 Section 0에서 prior `Q*` 행의 `Status`(`resolved` / `obsolete`)를 갱신한 뒤 진행합니다.
+- 사용 시점: `requirements-discovery`, `error-analysis`처럼 미해결 질문을 남기는 phase 이후, 사용자가 답변을 채워 다음 phase로 넘길 때.
+
+예:
+
+```bash
+scripts/okstra.sh \
+  --task-type implementation-planning \
+  --project-id jobs --task-group tasks --task-id 8852 \
+  --task-brief .project-docs/tasks/8852/BUG_REPORT.md \
+  --clarification-response .project-docs/okstra/tasks/tasks/8852/runs/2026-04-29/error-analysis/reports/final-report-2026-04-29_10-15-30.md
+```
+
+### `--resume-clarification`
+
+직전 `requirements-discovery` 또는 `error-analysis` run의 final report를 즉시 편집하고, 같은 phase를 자동으로 재실행합니다. `--clarification-response` 경로를 사용자가 직접 들고 다닐 필요가 없습니다.
+
+- 입력: task identity (`--project-id` + `--task-group` + `--task-id`, 또는 `--task-key <p>:<g>:<i>`)
+- 동작 순서:
+  1. task의 `runs/{requirements-discovery,error-analysis}/reports/final-report-*.md` 중 가장 최신 timestamp 파일을 자동 선택합니다.
+  2. `$EDITOR`(미설정 시 `vi`)로 해당 파일을 엽니다. 사용자는 Section 5의 `Q*` 행에 답변을 inline으로 채운 뒤 저장하고 종료합니다.
+  3. okstra가 같은 task-type으로 자기 자신을 `exec` 재호출하면서 편집된 파일을 `--clarification-response`로 carry-in 합니다.
+  4. 이후 confirmation, render, Claude handoff 흐름은 일반 실행과 동일합니다.
+- 명시적 `--task-type`을 함께 주면 그 task type의 reports/ 만 검색합니다. 생략 시 `error-analysis` → `requirements-discovery` 순으로 검색하고 timestamp가 더 큰 보고서를 사용합니다.
+- 다음 옵션과 함께 쓸 수 없습니다: `--render-only`, `--clarification-response`, `--approved-plan`.
+- `EDITOR`를 비대화형 도구(예: `true`)로 설정하면 답변 편집을 건너뛴 채 곧바로 재실행됩니다. 디버깅용으로만 권장합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --resume-clarification --task-key jobs:tasks:8852
+```
+
+```bash
+EDITOR=code\ -w scripts/okstra.sh --resume-clarification --project-id jobs --task-group tasks --task-id 8852
+```
+
+내부적으로는 다음과 동등합니다.
+
+```bash
+$EDITOR <project-root>/.project-docs/okstra/tasks/<group>/<id>/runs/<task-type>/reports/final-report-<latest>.md
+scripts/okstra.sh --task-type <same-type> \
+  --project-id <p> --task-group <g> --task-id <i> \
+  --task-brief <from manifest> \
+  --clarification-response <edited final-report-<latest>.md>
+```
+
+### `--project-root`
+
+대상 프로젝트의 절대 경로입니다. 명시하지 않으면 `okstra.sh` 가 다음 우선순위로 자동 해석합니다.
+
+1. cwd 또는 그 조상 디렉토리 중 `.project-docs/okstra/project.json` 보유 위치를 찾아 PROJECT_ROOT 로 채택합니다.
+2. 위가 실패하면 `git rev-parse --show-toplevel` 결과를 사용합니다.
+3. 모두 실패하면 즉시 에러로 종료합니다.
+
+해석된 PROJECT_ROOT 에서 첫 실행이라면 `<PROJECT_ROOT>/.project-docs/okstra/project.json` 이 다음 스키마로 자동 생성됩니다.
+
+```json
+{
+  "projectId": "<--project-id 인자 값>",
+  "projectRoot": "<resolved absolute path>",
+  "createdAt": "<ISO8601 UTC>",
+  "updatedAt": "<ISO8601 UTC>"
+}
+```
+
+이미 존재하면 `projectId` 일치 검사 후 `projectRoot`/`updatedAt` 만 갱신합니다. `projectId` 가 다르면 즉시 에러로 종료해 동일 디렉토리에서 두 개의 ID 가 혼용되는 것을 막습니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type error-analysis --project-id jobs --project-root /Volumes/Workspaces/workspace/projects/jobs ...
+```
+
+### `--directive`
+
+사용자 의도를 자유 텍스트로 lead·worker·downstream skill에 전달하는 채널입니다. 값은 `instruction-set/analysis-material.md` 끝에 `## Directive` 섹션으로 임베딩되고, 동시에 `instruction-set/directive.txt`로 백업됩니다.
+
+용도:
+
+- 기본 heuristic을 뒤집고 싶을 때 — 예: "단일 XL task여도 Gantt 그려줘 (Phase 2개, 총 ~10d)", "Gantt 생략 사유를 명시해줘" (참고: `## Cumulative Timeline`은 schedule contract에서 제거되었으므로 더 이상 toggle 대상이 아닙니다)
+- 분석/계획의 강조점 지시 — 예: "rollout 리스크 우선 분석", "test 커버리지 부재를 별도 finding으로"
+- Phase/Step 분할이나 day 추정을 미리 제시 — 예: "Part 1: 4d, measure: 0.5d, Part 2: 4d, ops: 1d"
+
+해석 규칙:
+
+- lead·worker는 `analysis-material.md`를 이미 end-to-end로 읽으므로 별도 작업 없이 자동 전파됩니다.
+- skill 측은 자체 contract보다 user prompt를 **우선** 적용해야 하며 (예: `okstra-schedule` 스킬의 "Directive override (highest priority)" 절), heuristic을 뒤집은 경우 결과 문서에 그 사실을 한 줄로 표시합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type implementation-planning ... \
+  --directive "Phase 2개(Part 1 ~4d, Part 2 ~5d, 순차)로 총 ~10d. Gantt 꼭 그려줘 (임계 경로 표시)."
+```
+
+### `--workers`
+
+이번 run에서 사용할 worker 목록을 직접 지정합니다.
+생략하면 기본값 `claude,codex,gemini,report-writer`를 사용합니다.
+지정하면 전달한 worker subset만 dedupe 후 기록됩니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type implementation-planning --workers claude,codex --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+### `--claude-model`
+
+`Claude worker`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_CLAUDE_MODEL` 또는 fallback `sonnet`을 사용합니다.
+
+### `--lead-model`
+
+`Claude lead`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_LEAD_MODEL` 또는 fallback `opus`를 사용합니다.
+
+### `--codex-model`
+
+`Codex worker`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_CODEX_MODEL` 또는 fallback `gpt-5.5`를 사용합니다.
+
+### `--gemini-model`
+
+`Gemini worker`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_GEMINI_MODEL` 또는 fallback `auto`를 사용합니다.
+
+### `--report-writer-model`
+
+`Report writer worker`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_REPORT_WRITER_MODEL` 또는 lead 기본값을 사용합니다.
+
+중앙 기본값 환경 변수는 아래와 같습니다.
+
+- `OKSTRA_DEFAULT_LEAD_MODEL`
+- `OKSTRA_DEFAULT_CLAUDE_MODEL`
+- `OKSTRA_DEFAULT_CODEX_MODEL`
+- `OKSTRA_DEFAULT_GEMINI_MODEL`
+- `OKSTRA_DEFAULT_REPORT_WRITER_MODEL`
+
+fallback 기본값은 아래와 같습니다.
+
+- `Claude lead`: `opus`
+- `Report writer worker`: `opus`
+- `Claude worker`: `sonnet`
+- `Codex worker`: `gpt-5.5`
+- `Gemini worker`: `auto`
+
+### `--related-tasks`
+
+간단한 연관 task 식별자 목록을 쉼표로 전달합니다.
+
+예:
 
 ```bash
-npx skills@latest add Devonshin/okstra
+scripts/okstra.sh --task-type error-analysis --related-tasks scanner-regression,reply-ui --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
 ```
 
-## Install runtime
+연관 task는 참고용 메타데이터이며 현재 task key를 대체하지 않습니다.
+
+### `--render-only`
+
+실제 Claude 실행 없이 프롬프트와 task bundle만 생성합니다.
+
+이 모드에서는 아래를 수행하지 않습니다.
+
+- Claude 실행
+- `final-report-<task-type>-<seq>.md` 생성
+- `final-<task-type>-<seq>.status` 생성
+
+하지만 아래는 수행합니다.
+
+- stable task root 생성 또는 갱신
+- `task-manifest.json` 생성 또는 갱신
+- `task-index.md` 생성 또는 갱신
+- `instruction-set/` 생성 또는 갱신
+- `instruction-set/reference-expectations.md` 생성 또는 갱신
+- `instruction-set/final-report-template.md` 생성 또는 갱신
+- current `manifests/run-manifest-<task-type>-<seq>.json` 기록
+- `history/timeline.json` 갱신
+- project-level discovery pointer 생성 또는 갱신
+
+### `--refresh-assets`
+
+project-local `.claude/skills/`와 `.claude/agents/` 아래의 okstra mapped asset을 workspace source 기준으로 다시 생성합니다.
+기본 rerun에서는 기존 project-local asset을 유지합니다.
+
+
+## Interactive input flow
+
+interactive terminal에서 필수 인자 일부를 생략하면 `okstra`가 아래 항목을 순서대로 물을 수 있습니다.
+
+- `Project ID`
+- `Task Group`
+- `Task ID`
+- `Task Type`
+- `Task Brief Path`
+
+예를 들어 아래처럼 실행할 수 있습니다.
 
 ```bash
-npx okstra@latest install
+scripts/okstra.sh --render-only --task-type error-analysis
+```
+
+그러면 누락된 필수값을 stdin으로 입력받은 뒤, 최종 요약과 confirmation을 거쳐 진행합니다.
+
+## Confirmation flow
+
+interactive 실행에서는 실제 파일 생성 전에 아래 성격의 요약을 보여줍니다.
+
+- render-only 여부
+- task type
+- project id
+- task group
+- task id
+- task brief path
+- analysis target
+- related tasks
+- selected workers
+- lead model
+- configured worker models
+- task key
+- task root
+- current run dir
+
+이후 `Continue? [y/yes]:` 프롬프트가 표시되며, `y` 또는 `yes`가 아니면 실행하지 않고 종료합니다.
+
+`--yes`를 사용하면 이 confirmation flow 자체를 건너뜁니다.
+
+## Storage model
+
+`okstra`가 만드는 파일은 용도에 따라 아래 3개 영역에 나뉘어 저장됩니다.
+
+### 1. Stable task root
+
+task 자체의 기준 폴더입니다.
+task manifest, task index, instruction-set, runs, history가 이 루트 아래에 모입니다.
+
+```text
+<target-project>/.project-docs/okstra/tasks/<task-group>/<task-id>/
+├── task-manifest.json
+├── task-index.md
+├── instruction-set/
+│   ├── analysis-profile.md
+│   ├── analysis-material.md
+│   ├── reference-expectations.md
+│   ├── task-brief.md
+│   ├── directive.txt                  # optional (mirrors --directive)
+│   ├── 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
+│       │   ├── gemini-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
+```
+
+실제 디렉터리 세그먼트는 안전한 경로 생성을 위해 slug 형태로 정규화될 수 있습니다.
+하지만 논리 task key는 항상 원래 입력값 기준 `project-id:task-group:task-id`를 유지합니다.
+
+### 2. Per-run execution artifacts
+
+실행별 산출물은 아래 경로에 누적됩니다.
+
+```text
+<target-project>/.project-docs/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`
+- `status/final-<task-type>-<seq>.status`
+최종 결과 파일 둘은 `okstra`가 stdout을 저장해서 만드는 파일이 아닙니다.
+`okstra`가 준비한 task bundle을 바탕으로 Claude가 현재 run 안에 직접 작성하는 결과물입니다.
+반면 `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>/.project-docs/okstra/discovery/latest-task.json
+<target-project>/.project-docs/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
 ```
 
-This populates `~/.okstra/lib/python/`, `~/.okstra/bin/`, and `~/.okstra/version`. The `agents/` directory stays inside this package — skills resolve its path with `okstra paths --field agents`.
+역할 구분:
+
+- `.project-docs/okstra/discovery/latest-task.json`: 현재 프로젝트에서 가장 최근에 준비된 okstra task bundle을 가리키는 current-task convenience pointer
+- `.project-docs/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/...`, `.claude/agents/...`: `agents` 아래 Markdown asset을 project-local Claude asset 구조로 seed한 파일들
+
+기본 rerun에서는 이미 존재하는 project-local asset을 유지합니다.
+`--refresh-assets`를 주면 mapped okstra asset을 source 기준으로 다시 생성합니다.
+
+이전의 아래 파일들은 더 이상 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`
+
+이 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
+
+## 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
+같은 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 필드입니다.
 
-## Commands
+## Claude operating contract
 
-| Command | Description |
+`okstra` 실행 후 Claude는 아래 순서로 현재 task를 읽는 것을 기본 규칙으로 삼아야 합니다.
+
+1. task browsing 또는 task-id disambiguation이 필요하면 `.project-docs/okstra/discovery/task-catalog.json`을 먼저 읽습니다.
+2. 현재 task key나 task path가 명시되지 않았다면 `.project-docs/okstra/discovery/latest-task.json`을 current-task pointer로 읽습니다.
+3. `task-manifest.json`을 읽습니다.
+4. `task-index.md`는 quick summary가 필요할 때만 선택적으로 읽습니다.
+5. `instruction-set/analysis-profile.md`를 읽습니다.
+6. `instruction-set/analysis-material.md`를 읽습니다.
+7. `instruction-set/reference-expectations.md`를 읽습니다.
+8. `instruction-set/task-brief.md`를 읽습니다.
+9. `instruction-set/final-report-template.md`를 읽습니다.
+10. current `manifests/run-manifest-<task-type>-<seq>.json`을 읽습니다.
+11. 필요하면 `history/timeline.json`과 이전 run 결과를 참고합니다.
+12. `Claude lead`로서 required worker `Claude worker`, `Codex worker`, `Gemini worker`, `Report writer worker`를 기준으로 역할을 구성합니다.
+13. 각 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`
+
+## Task brief usage
+
+`okstra`는 brief-first 구조입니다. brief 가 분석의 정본 입력이며, 워커가 필요로 할 추가 자료(보고서, 코드 스니펫, 로그 등)는 brief 내부의 `Evidence and Source Materials` 섹션에 inline 또는 path 로 모두 포함시킵니다.
+
+brief에는 보통 아래를 포함합니다.
+
+- 문제 설명
+- 요구사항
+- 기존 분석
+- raw sample 또는 log
+- 관련 코드 경로
+- 제약사항
+- worker에게 줄 질문
+- 기대 출력
+- 이전 run 또는 연관 task 정보
+
+기본 템플릿:
+
+- `templates/reports/quick-input.template.md`
+- `templates/reports/task-brief.template.md`
+- `templates/reports/error-analysis-input.template.md`
+- `templates/reports/implementation-planning-input.template.md`
+- `templates/reports/implementation-input.template.md`
+- `templates/reports/final-verification-input.template.md`
+
+입력 템플릿에서는 최소한 아래 항목을 채우는 것을 권장합니다.
+
+- `Project ID`
+- `Task Group`
+- `Task ID`
+- `Related Tasks`
+- `Task Type`
+- `Requested Outcome`
+
+## Recommended workflow
+
+### 1. 초안 작성
+
+빠르게 메모를 정리할 때는 `okstra-quick-input.template.md`를 사용합니다.
+
+### 2. 정식 brief 작성
+
+최종 입력은 `okstra-task-brief.md`로 정리합니다.
+같은 task를 다시 이어갈 계획이면 같은 `task-group`과 `task-id`를 유지합니다.
+
+### 2.5. 필요 시 요구사항 triage
+
+요청이 버그 수정인지 신규 기능인지, 요구사항이 충분한지 먼저 분류해야 하면 같은 `okstra-task-brief.md`에 `Task Type: requirements-discovery`를 넣고 실행합니다.
+이 단계는 이후 phase를 자동 실행하지 않고, work category와 다음 권장 phase를 task lifecycle metadata에 남기는 역할만 합니다.
+
+```bash
+scripts/okstra.sh --task-type requirements-discovery --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path>
+```
+
+### 3. Render-only 검증
+
+```bash
+scripts/okstra.sh --render-only --task-type error-analysis --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path>
+```
+
+### 4. Claude 실행
+
+두 가지 진입 방식이 있으며 산출물은 동일합니다.
+
+**Option A — 새 claude 프로세스를 띄움 (`okstra.sh`)**
+
+```bash
+scripts/okstra.sh --task-type error-analysis --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path>
+```
+
+이 경로로 실행하면 `okstra.sh` 가 prepare 단계를 마친 뒤 대상 프로젝트 루트에서 새 Claude interactive session 을 `exec` 합니다. handoff 까지만 수행하고 최종 보고서 저장은 Claude lead 가 이어서 수행합니다. 실행 직전에 `sessions/claude-resume-<task-type>-<seq>.sh` 가 미리 작성되므로 세션이 중간에 끊겨도 같은 run 을 재개할 수 있습니다.
+
+**Option B — 현재 claude 세션 안에서 인계 (`okstra-run` skill)**
+
+이미 Claude Code 세션을 사용 중이라면 새 프로세스를 띄우지 않고 같은 세션이 그대로 Claude lead 로 인계받게 할 수 있습니다. trigger 예: `"run okstra here"`, `"start error-analysis on this project"`.
+
+skill 흐름:
+
+1. `okstra-run` skill 이 활성화되고 `AskUserQuestion` 으로 task 후보 / task-type / brief 경로를 받습니다.
+2. 사용자의 입력으로 `okstra_ctl.run.prepare_task_bundle(render_only=True)` 를 호출합니다 — `okstra.sh` 를 거치지 않고 같은 python 함수를 직접 호출합니다.
+3. 같은 instruction-set 산출물이 디스크에 만들어지면 현재 claude 가 그 prompt 를 읽어 lead 역할로 진입합니다.
+
+자세한 절차는 [`skills/okstra-run/SKILL.md`](skills/okstra-run/SKILL.md) 참조.
+
+### 5. 필요 시 에러 분석
+
+```bash
+scripts/okstra.sh --task-type error-analysis --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path>
+```
+
+첫 진입 이후 같은 task에 추가 run이 필요하면 단축 형식 사용:
+
+```bash
+scripts/okstra.sh --task-key <project-id>:<task-group>:<task-id> --task-type error-analysis
+```
+
+### 5.5. 답변 후 즉시 재실행
+
+`requirements-discovery` 또는 `error-analysis` final report의 Section 5에 답변을 채워야 한다면, 경로를 손으로 들고 다닐 필요 없이 한 번에 처리합니다.
+
+```bash
+scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>
+```
+
+`$EDITOR`로 최신 final report가 열리고, 저장 후 같은 phase가 자동으로 `--clarification-response` carry-in 으로 재실행됩니다.
+
+### 6. 필요 시 구현 계획 검토
+
+```bash
+scripts/okstra.sh --task-type implementation-planning --workers claude,codex --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path>
+```
+
+후속 phase 단축 형식 (manifest의 `workflow.nextRecommendedPhase`가 `implementation-planning`이면 `--task-type` 도 생략 가능):
+
+```bash
+scripts/okstra.sh --task-key <project-id>:<task-group>:<task-id> --workers claude,codex
+```
+
+### 7. 승인된 plan 기반 구현
+
+`implementation-planning` final report의 `User Approval Request` 블록에 사용자 승인이 기록된 뒤에만 실행합니다. 승인된 plan 경로를 `--approved-plan`으로 carry-in해야 하며, plan이 없거나 승인 마커가 없으면 run은 `contract-violated`로 거부됩니다.
+
+승인 마커는 line-anchored, case-insensitive로 다음 중 하나와 일치해야 합니다(코드 진실: `scripts/okstra.sh`).
+
+- `APPROVED` (라인 시작에 단독, 또는 뒤에 공백/콜론)
+- `[x] Approved`
+- `User Approval: APPROVED` / `User Approval: granted` / `User Approval: yes`
+
+```bash
+scripts/okstra.sh --task-type implementation --workers claude,codex,gemini --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> --approved-plan <runs/implementation-planning/.../reports/final-report.md>
+```
+
+단축 형식:
+
+```bash
+scripts/okstra.sh --task-key <project-id>:<task-group>:<task-id> --task-type implementation --workers claude,codex,gemini --approved-plan <runs/implementation-planning/.../reports/final-report.md>
+```
+
+### 8. 구현 후 최종 검토
+
+```bash
+scripts/okstra.sh --task-type final-verification --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path>
+```
+
+단축 형식:
+
+```bash
+scripts/okstra.sh --task-key <project-id>:<task-group>:<task-id> --task-type final-verification
+```
+
+### 9. 같은 task 재개
+
+같은 bugfix나 same workstream을 다시 열면 기존과 같은 `task-group`과 `task-id`를 사용합니다.
+그러면 기존 task root 아래 `runs/`와 `history/timeline.json`에 이력이 계속 누적됩니다.
+첫 진입 이후에는 `--task-key <p>:<g>:<i>` 단축 형식이 가장 간결하며, 누락된 brief/task-type은 manifest에서 자동 채워집니다.
+
+## Lifecycle status and resume
+
+장기 작업에서는 `task-manifest.json`의 `workflow`가 canonical lifecycle 상태입니다.
+특히 아래 항목을 먼저 확인하면 현재 위치와 재개 지점을 빠르게 판단할 수 있습니다.
+
+- `workflow.currentPhase`
+- `workflow.currentPhaseState`
+- `workflow.phaseStates`
+- `workflow.lastCompletedPhase`
+- `workflow.nextRecommendedPhase`
+- `workflow.awaitingApproval`
+- `workflow.routingStatus`
+- `workflow.lastSafeCheckpoint`
+
+프로젝트 전체 상태를 훑을 때는 `.project-docs/okstra/discovery/task-catalog.json`을 사용합니다.
+특정 task의 최신 상태를 볼 때는 `.project-docs/okstra/discovery/latest-task.json`, `task-manifest.json`, 최신 `run-manifest`, `history/timeline.json` 순서로 확인합니다.
+
+Claude에서는 seeded `okstra-status` skill을 사용해 아래 질문을 직접 처리할 수 있습니다.
+
+- 전체 okstra task status 보여줘
+- 특정 `task-key`의 current phase와 next phase 알려줘
+- approval 대기 중인 task와 resume 가능한 task를 보여줘
+- `<task-id>`의 `workStatus`를 `todo` / `in-progress` / `blocked` / `done`으로 업데이트해줘 (예: "okstra mark <task-id> done", "<task-id> 진행중") — skill이 해당 `task-manifest.json`의 `workStatus`, `workStatusUpdatedAt`, `workStatusNote`를 갱신합니다.
+
+resume 판단 기준:
+
+- 현재 run 재개: `latestResumeCommandPath`가 있으면 그 경로를 우선 사용합니다.
+- 현재 phase 재시작: 같은 `task-key`와 현재 `task-type`으로 다시 실행합니다.
+- 다음 phase 시작: `workflow.nextRecommendedPhase`가 구체적인 phase면 그 값으로 다음 `okstra.sh` 실행을 준비합니다.
+- 추가 자료 필요: `routingStatus=pending` 또는 `nextRecommendedPhase=pending-routing-decision`이면 brief 보강이 먼저입니다.
+
+## Preferred final report structure
+
+기본 최종 보고서 템플릿은 `templates/reports/final-report.template.md`입니다.
+Claude가 작성하는 최종 보고서는 brief에 더 구체적인 형식이 없다면 아래 구조를 우선 사용합니다.
+
+1. 문제 또는 검증 대상 요약
+2. 에이전트별 실행 현황
+3. Cross Verification 결과
+4. 최종 판단
+5. 근거 및 세부 분석
+6. 누락 정보 및 리스크
+7. 권장 다음 단계
+
+차이점이 실질적으로 없으면 억지로 대비를 만들지 말고, 차이가 없음을 명시합니다.
+저장 실패나 세션 제한에 대한 메타 설명 대신 실제 Markdown 보고서 본문을 파일에 작성해야 합니다.
+
+## Worker error collection (optional sidecar)
+
+워커(Claude/Codex/Gemini worker, Report writer, Claude lead) 실행 중 발생한 에러를 단일 시계열 로그로 수집해 사후 회고에 사용할 수 있습니다.
+
+- 저장 위치: `runs/<task-type>/logs/errors-<task-type>-<seq>.jsonl`
+- append-only JSON Lines, run 단위 격리이므로 별도 회전 정책은 두지 않습니다.
+- **Single writer**: 동시 append 충돌을 피하기 위해 `Claude lead`만 직접 이 파일에 씁니다. `<seq>`는 카테고리(`logs/`, `manifests/`, `state/` 등) 디렉토리별로 독립 스캔되는 3-digit zero-padded counter (`001`, `002`, …)이므로 같은 run에서도 카테고리별 값이 다를 수 있습니다(이전 run이 일부 카테고리만 기록한 경우). 한 run의 cross-category 식별자는 manifest의 `runDateTimeSegment` ISO timestamp 필드입니다.
+  - 워커 내부 도구 실패는 워커 결과 매니페스트의 `errors[]`에 보고 → lead가 merge 직후 dump
+  - Codex/Gemini CLI 실패·타임아웃·rate-limit는 lead가 wrapper에서 직접 관찰
+  - resultContract 위반·스키마 mismatch·필수 필드 누락은 lead 검증 단계에서 직접 관찰
+- `source` 필드(`worker-reported` | `lead-observed`)와 `errorType`(`tool-failure` | `cli-failure` | `contract-violation`)으로 발생원과 종류를 구분합니다.
+- `stderrExcerpt`는 한 줄 jsonl 가독성을 위해 2KB 상한, `PIPE_BUF`(4096B) atomic append 가드를 강제합니다.
+- run-manifest 또는 team-state의 `errorsLogPath` 필드에 `logs/errors-<task-type>-<seq>.jsonl` 경로를 1회 기록해 발견 가능하게 합니다.
+- Helper CLI: `scripts/okstra-error-log.py`
+  - 단일 진입점으로 record를 append 합니다.
+  - 워커 sidecar dump(`append_observed`, schema version 가드)와 lead 관찰(`lead-observed`) 모두 동일 helper를 사용합니다.
+
+상세 설계 및 jq 회고 레시피는 `docs/superpowers/specs/2026-04-28-worker-error-collection-design.md`를 참고합니다.
+
+## Token usage and cost accounting
+
+각 run에 사용된 토큰을 lead/worker 세션 트랜스크립트에서 수집해 `team-state.json`의 `leadUsage` / `workers[].usage`에 다시 기록합니다.
+
+- Helper CLI: `scripts/okstra-token-usage.py`
+- 수집 소스:
+  - Claude lead/workers: `~/.claude/projects/<cwd-as-dashes>/<sessionId>.jsonl`의 per-message `message.usage`
+  - Codex CLI: `~/.codex/sessions/Y/M/D/rollout-*.jsonl`의 마지막 `total_token_usage.total_tokens`
+  - Gemini CLI: `~/.gemini/tmp/*/chats/session-*.json`의 per-message `tokens.total`
+- billable-equivalent token math와 USD cost estimation을 함께 기록합니다. Anthropic billing ratio(`cache_creation=1.25x`, `cache_read=0.1x`, `output=5x`)를 반영합니다.
+- 가격표는 helper 상단에서 중앙 관리합니다. 모델 가격이 바뀌면 helper의 `*_PRICING` 상수를 갱신해야 합니다.
+
+## Practical notes
+
+- `okstra`는 brief 없이 쓰는 옛 방식이 아닙니다.
+- brief이 분석의 정본 입력입니다. 추가 자료는 brief 내부의 `Evidence and Source Materials` 섹션에 inline 또는 path 로 포함시키며, 별도의 추가 자료 CLI 옵션은 제공하지 않습니다.
+- brief의 `Configuration References and Expected Values`, `Deployment Manifests and Expected Values` 섹션은 task별 expected state의 canonical source입니다.
+- `task-type`가 프로필 선택까지 결정합니다.
+- `--render-only`는 dry-run 확인용이지만 task bundle과 run manifest는 생성합니다.
+- `--refresh-assets`는 `.claude/skills/`와 `.claude/agents/`의 okstra mapped asset을 source 기준으로 다시 생성합니다.
+- 기본 실행은 Claude print-mode 수집이 아니라 interactive handoff입니다.
+- 기본 최종 보고서 템플릿은 task bundle의 `instruction-set/final-report-template.md`에 렌더링됩니다.
+- task bundle의 `instruction-set/reference-expectations.md`는 config/deployment expected-state reference로 함께 생성됩니다.
+- 현재 run 세션의 resume helper는 `runs/<task-type>/sessions/claude-resume-<task-type>-<seq>.sh`에 생성됩니다.
+- run directory 내부는 `manifests/`, `state/`, `prompts/`, `reports/`, `status/`, `sessions/`, `worker-results/`처럼 유형별 하위 폴더로 구성되고, prompt snapshot은 `prompts/` 아래에 먼저 준비됩니다.
+- worker 생성과 결과 취합은 Claude가 수행합니다.
+- standard workflow는 `Claude lead` + required worker `Claude worker`, `Codex worker`, `Gemini worker`, `Report writer worker`를 사용합니다.
+- worker 모델은 `--lead-model`, `--claude-model`, `--codex-model`, `--gemini-model`, `--report-writer-model`로 override할 수 있고, 기본값은 `OKSTRA_DEFAULT_*` 환경 변수에서 중앙 관리합니다. fallback 기본값은 `Claude lead`/`Report writer worker`=`opus`, `Claude worker`=`sonnet`, `Codex worker`=`gpt-5.5`, `Gemini worker`=`auto`입니다.
+- project-level current-task convenience pointer는 `.project-docs/okstra/discovery/latest-task.json`입니다.
+- project-level canonical task inventory는 `.project-docs/okstra/discovery/task-catalog.json`입니다.
+- project-local okstra Claude asset은 `.claude/skills/`와 `.claude/agents/` 아래에 seed되며, 기본 rerun에서는 보존되고 `--refresh-assets`로 다시 생성할 수 있습니다.
+- seeded okstra Claude assets는 Agent Teams 우선, sequential/background fallback 차선 규칙을 Claude에게 제공합니다.
+- 최종 판단은 스크립트가 아니라 Claude가 수행합니다.
+- stable task key를 유지해야 이후 bug 추적, 재수정, 재검증이 가능합니다.
+- 워커 에러는 옵션 sidecar `runs/<task-type>/logs/errors-<task-type>-<seq>.jsonl`로 수집되며 lead가 단독 writer입니다. 진입점 helper는 `scripts/okstra-error-log.py`입니다.
+- 토큰 사용 및 비용 집계는 `scripts/okstra-token-usage.py`가 담당하며.
+- `okstra.sh`는 worker CLI 호출 anchoring을 위해 절대 projectRoot를 강제합니다.
+
+## Related documents
+
+- `README.md`
+- `templates/reports/task-brief.template.md`
+- `templates/reports/final-report.template.md`
+- `agents/SKILL.md`
+- `docs/superpowers/specs/2026-04-28-worker-error-collection-design.md`
+- `docs/superpowers/plans/2026-04-28-worker-error-collection.md`
+- `scripts/okstra-error-log.py`
+- `scripts/okstra-token-usage.py`
+
+## okstra Control Center
+
+`okstra-ctl` 은 사용자 홈의 `~/.okstra/` 인덱스를 사용해 모든 타깃 프로젝트의 okstra run 을 가로질러 조회·모니터링·재실행할 수 있는 CLI 다.
+
+### 설치 (전역 wrapper)
+
+`okstra` 와 동일하게 `~/.local/bin/` 아래에 wrapper 를 두면 어디서든 호출 가능하다.
+
+```bash
+cat > ~/.local/bin/okstra-ctl <<'WRAPPER'
+#!/usr/bin/env bash
+exec /Volumes/Workspaces/workspace/projects/Okstra/scripts/okstra-ctl.sh "$@"
+WRAPPER
+chmod +x ~/.local/bin/okstra-ctl
+```
+
+(`~/.local/bin` 이 `PATH` 에 포함되어 있어야 한다.)
+
+### 자주 쓰는 명령
+
+| 목적 | 명령 |
 |---|---|
-| `okstra install` | Install runtime into `~/.okstra` |
-| `okstra ensure-installed` | Idempotent check + reinstall if stale; skills call this on every run |
-| `okstra paths` | Print runtime paths (`agents`, `pythonpath`, `bin`, `home`, `version`) |
-| `okstra doctor` | Diagnose the installed runtime |
+| 작업한 프로젝트 목록 | `okstra-ctl projects` |
+| 최근 run 검색 | `okstra-ctl list --since 7d` |
+| 특정 프로젝트만 | `okstra-ctl list --project fontradar` |
+| 진행 중 run 보기 | `okstra-ctl tail active` |
+| 단일 run 결과 메타 | `okstra-ctl show <runId-or-prefix>` |
+| 결과 보고서 경로 | `okstra-ctl open <runId-or-prefix>` |
+| 단일 재실행 | `okstra-ctl rerun <runId-or-prefix> --yes` |
+| 다중 재실행 | `okstra-ctl rerun --filter --project X --status failed --yes` |
+| 가장 최근 재실행 | `okstra-ctl rerun last --project X --task-group Y --yes` |
+| 백필/재스캔 | `okstra-ctl reindex` |
+| 활성 run 재조정 | `okstra-ctl reconcile [--project <id|all>]` |
+| 배치 진행 | `okstra-ctl batch status <batch-id>` |
+
+### 동작 모델
+
+- `okstra.sh` 는 시작 시 1번 `record_start` hook 으로 인덱스에 메타와 invocation 을 기록한다.
+- 종료 처리는 `okstra-ctl` 의 모든 진입점에서 호출되는 lazy reconcile 이 수행한다(타깃 프로젝트의 `final-report-*.md` 존재로 추론).
+- 다중 rerun 은 대상 1건당 tmux 세션 1개를 detached 로 spawn 하고 즉시 반환한다(fire-and-forget). 사용자는 반환된 attach 명령으로 임의 세션에 접속한다.
+- spawn 임계 기본값은 10. `--max-spawn N` 또는 `OKSTRA_CTL_MAX_SPAWN` 으로 변경 가능.
+- runId 형식: `<project-id>/<task-group>/<task-id>/<task-type>/r<run-seq>` (예: `fontradar/payment/fail/error-analysis/r07`). 입력 시 prefix substring 매칭을 지원한다.
+
+### 동시성 제어 (두 단계 mutex)
+
+`okstra-ctl` 과 `record_start` hook 은 두 가지 서로 다른 스코프의 fcntl `LOCK_EX` 를 사용한다. 둘은 책임이 분리되어 있어 함께 들고 있어도 데드락이 발생하지 않는다.
+
+| Lock | 위치 | 스코프 | 보유 시점 | 목적 |
+|---|---|---|---|---|
+| central lock | `~/.okstra/.lock` | 전역(인덱스 단위) | `record_start` 의 `active.jsonl`/`recent.jsonl`/`projects/<id>/index.jsonl` 쓰기 구간, ctl 의 reconcile / reservation 쓰기 구간 | 인덱스 jsonl 의 read-modify-write 직렬화. 동시에 일어나는 record_start append 와 reconcile rotation 이 서로 leak 하지 않게 한다. |
+| task lock | `~/.okstra/.locks/<projectId>-<taskGroup>-<taskId>-<taskType>.lock` | task-key + task-type 별 mutex | `okstra-ctl rerun` 의 seq 예측 + tmux spawn 구간 전체 | 동일 task 의 동시 rerun 이 같은 run-seq 를 받아 manifest/디렉토리 경합으로 깨지는 것을 막는다. central lock 보다 바깥에서 잡으므로, 다른 task 의 rerun 은 서로 블록하지 않는다. |
+
+호출 순서는 항상 `task lock` → `central lock` (ctl rerun) 또는 `central lock` 단독(record_start, reconcile). 역순 보유는 발생하지 않는다.
 
-Run `okstra --help` for full usage.
+`task_lock_filename` 은 각 세그먼트를 fs-safe 슬러그로 정규화한 뒤 `-` 를 `--` 로 escape 해 `-` 로 join 하므로, `('p','feature-8','email','x')` 와 `('p','feature','8-email','x')` 가 같은 파일명으로 충돌해 mutex 가 공유되는 문제를 방지한다 ([scripts/okstra_ctl/locks.py](scripts/okstra_ctl/locks.py)).
 
-## Status
+### 환경변수
 
-Pre-release (`0.1.0-pre.x`). Layout and command surface may change before `0.1.0`.
+- `OKSTRA_HOME`: 중앙 디렉터리 위치 override (기본 `~/.okstra`).
+- `OKSTRA_CTL_MAX_SPAWN`: rerun 동시 spawn 임계 기본값.
+- `OKSTRA_CTL_SKIP_BACKFILL=1`: 첫 호출 시 자동 백필 스킵.
+- `OKSTRA_CTL_SKIP_RECONCILE=1`: lazy reconcile 스킵(테스트/디버깅용).
+- `OKSTRA_RUN_SEQ_OVERRIDE`: rerun 시 okstra.sh 가 사용할 run-seq 강제값 (okstra-ctl 내부 자동 주입).