okstra 0.117.0 → 0.119.0

package/README.kr.md

@@ -1,231 +0,0 @@
-# okstra
-
-> npm: [`okstra`](https://www.npmjs.com/package/okstra) · 설치: `npx -y okstra@latest install`
->
-> English: [`README.md`](README.md)
-
-## 인덱스
-
-- [1. 용도](#1-용도)
-- [2. 구조](#2-구조)
-  - [2.1 repo 레이아웃](#21-repo-레이아웃)
-  - [2.2 설치 후 사용자 머신 레이아웃](#22-설치-후-사용자-머신-레이아웃)
-  - [2.3 단일 권위 요약](#23-단일-권위-요약)
-- [3. 사용 매뉴얼](#3-사용-매뉴얼)
-  - [3.1 최초 셋업 (머신당 1회)](#31-최초-셋업-머신당-1회)
-  - [3.2 프로젝트 등록 (프로젝트당 1회)](#32-프로젝트-등록-프로젝트당-1회)
-  - [3.3 일상 명령](#33-일상-명령)
-  - [3.4 CLI 모드 (선택)](#34-cli-모드-선택)
-  - [3.5 운영 명령](#35-운영-명령)
-- [4. 더 읽을 자료](#4-더-읽을-자료)
-
-## 1. 용도
-
-`okstra` 는 **Claude Code 안에서 lead + worker 모델로 작업을 cross-verify 하기 위한 정형화된 task 실행 러너**입니다. Claude lead 가 phase 진행을 주도하고, 독립된 분석 worker — **기본 Claude · Codex** (Antigravity 는 옵션으로 명시할 때만 추가) — 와 최종 보고서 작성을 전담하는 report-writer 를 dispatch 합니다.
-
-설계의 세 가지 원칙:
-
-- **단일 진입점 (`prepare_task_bundle`)**: 어떤 호출자(스킬, bash CLI, in-session) 가 들어와도 같은 task 디렉터리 구조 · 매니페스트 · 검증 경로를 산출합니다.
-- **task 정체성의 영구화**: `<project-id>/<task-group>/<task-id>` stable task key 가 phase 간 / 세션 간 / 모델 업그레이드 사이의 컨텍스트를 잇습니다.
-- **lead/worker 계약 강제**: 산출 schema 와 검증 절차가 `templates/` + `validators/` 에 묶여 있고, worker roster 는 phase 별로 고정되어 있습니다.
-
-okstra 는 단발성 코드 리뷰 도구가 **아닙니다**. **여러 phase 로 나뉘고, 여러 에이전트가 의견을 내야 하며, 각 phase 의 출력이 다음 phase 의 입력이 되는** 작업을 위한 도구입니다.
-
-## 2. 구조
-
-### 2.1 repo 레이아웃
-
-```
-okstra/                          npm 패키지 = repo 루트
-├── package.json                 name: "okstra"
-├── bin/okstra                   노드 CLI 진입점
-├── src/                         Node CLI 명령 모듈 (install, wizard, config, render, token usage, ...)
-├── tools/build.mjs              runtime/ 동기화 스크립트 (prepack 에서 호출)
-├── runtime/                     gitignored 설치 payload; ~/.okstra 로 복사
-├── scripts/                     python + bash 런타임 소스
-├── skills/                      public 스킬 마크다운 소스 (사용자 노출 8종)
-├── agents/                      worker agent 마크다운 소스
-├── prompts/, schemas/, templates/, validators/
-├── docs/kr/                     한국어 상세 매뉴얼 (architecture.md, cli.md)
-├── tests/, tests-e2e/
-├── .claude-plugin/plugin.json   보조 skills-CLI 채널 매니페스트
-├── .github/workflows/           release-please.yml, release.yml
-└── RELEASING.md, CHANGELOG.md, README.md, README.kr.md
-```
-
-`runtime/` 은 `prepack` 시점에 `tools/build.mjs` 가 `scripts/`, `skills/`, `agents/`, `prompts/`, `schemas/`, `templates/`, `validators/` 로부터 다시 빌드합니다. `~/.okstra` 로 복사되는 설치 payload이며, npm package는 이 payload와 함께 Node CLI(`bin/`, `src/`), docs, README를 배포합니다.
-
-### 2.2 설치 후 사용자 머신 레이아웃
-
-```
-~/.okstra/                       런타임 홈, `okstra install` 이 생성
-├── version                      패키지 버전 stamp
-├── lib/python/                  okstra_project/, okstra_ctl/, okstra_token_usage/, lib/
-├── bin/                         okstra.sh, codex-exec, antigravity-exec, ...
-├── templates/                   report asset, settings template
-├── prompts/                     lead 운영 계약(prompts/lead/*) + coding-preflight 리소스 팩
-├── installed-runtimes.json      설치된 runtime adapter 매니페스트
-├── installed-skills.json        설치된 스킬 매니페스트 (uninstall 이 사용)
-├── installed-agents.json        설치된 워커 에이전트 매니페스트 (uninstall 이 사용)
-├── recent.jsonl, active.jsonl   run 인덱스
-├── memory-book/                 전역 대화 메모리 (`okstra memory`)
-├── projects/                    프로젝트별 메타데이터 미러
-├── worktrees/                   task-key 당 하나의 격리 git worktree
-│                                (모든 phase가 공유; run 종료 후 자동 삭제하지 않음)
-├── archive/                     완료된 run
-└── .locks/                      central/task mutex 파일
-
-~/.claude/skills/                Claude Code 가 자동 인식 (`~/.claude` 가 있을 때)
-~/.agents/skills/                Agent 호환 host 가 인식 (`install` 이 생성)
-└── okstra-*/SKILL.md            사용자 노출 스킬 8종만 (setup/brief/run/memory/inspect/schedule/container/manager)
-
-~/.claude/agents/                Claude Code 가 자동 인식 (`~/.claude` 가 있을 때)
-└── {claude,codex,antigravity,report-writer}-worker.md   worker subagent 정의
-                                 (Claude Code multi-agent dispatch 필수)
-
-<프로젝트 루트>/.okstra/
-├── project.json                 {projectId, projectRoot, ...} (`/okstra-setup` 이 작성)
-├── discovery/{task-catalog,latest-task}.json
-├── glossary.md                  okstra-owned project terminology
-├── decisions/<NNNN>-<slug>.md   okstra-owned decision records
-└── tasks/<task-group>/<task-id>/   task bundle (runs, manifest, reports)
-```
-
-### 2.3 단일 권위 요약
-
-| 리소스 | 위치 | 소유자 |
-|---|---|---|
-| 런타임 코드 (python + bash) | `~/.okstra/{lib/python, bin}` | `okstra install` |
-| agents/prompts/schemas/templates/validators | npm 패키지의 `runtime/` | `okstra` 패키지 자체 (`okstra paths` 로 해석) |
-| 스킬 마크다운 | `~/.claude/skills` 또는 `~/.agents/skills` | `okstra install` (`installed-skills.json` 에 target별 트래킹) |
-| 워커 에이전트 마크다운 | `~/.claude/agents/<worker>.md` | `~/.claude` 가 있을 때 `okstra install` (`installed-agents.json` 에 트래킹) |
-| 프로젝트 메타데이터 | `<project>/.okstra/` | `/okstra-setup` + 프로젝트 자체 |
-| Run 인덱스 | `~/.okstra/{recent,active}.jsonl` | `prepare_task_bundle` |
-
-## 3. 사용 매뉴얼
-
-### 3.1 최초 셋업 (머신당 1회)
-
-```bash
-npx -y okstra@latest install
-```
-
-`~/.okstra/{lib/python, bin, templates, prompts, version}` 과 `~/.okstra/` 의 설치 asset manifest 를 생성합니다. 스킬 설치는 host home 기준입니다. `~/.claude` 가 있으면 public skill 을 `~/.claude/skills/` 에, worker agent 를 `~/.claude/agents/` 에 설치하고, `~/.agents/skills/` 는 항상 생성해 Agent 호환 host 용 public skill 을 설치합니다. 사용자 진입점 스킬만 목록에 보이고, lead/support 운영 계약은 `~/.okstra/prompts/` 아래 runtime resource 로 설치되어 skill discovery 대상이 아닙니다. 재실행은 idempotent — 파일별 hash 를 비교하고 바뀐 파일만 갱신합니다.
-
-검증:
-
-```bash
-npx -y okstra@latest doctor
-```
-
-`result: OK` 라인이 보이면 준비 완료입니다. FAIL row 가 있으면 그 줄에 바로 복구 방법이 인쇄됩니다 (대개는 install 재실행).
-
-#### (선택) `okstra` 명령을 글로벌로 설치
-
-이 README 의 모든 예제는 `npx -y okstra@latest <cmd>` 를 씁니다 — 글로벌 설치 없이도 동작합니다. 매번 npx 의 패키지 fetch / 버전 체크를 거치지 않고 `okstra` 한 단어로 호출하고 싶다면 글로벌 설치:
-
-```bash
-npm i -g okstra
-okstra --version       # CLI 가 PATH 에 잡혔는지 확인
-okstra install          # 'npx -y okstra@latest install' 과 동일
-```
-
-글로벌 설치는 Node CLI 를 PATH 에 등록할 뿐입니다. 런타임(`~/.okstra/`) 과 host skill directory(`~/.claude/skills/` 또는 `~/.agents/skills/`) 는 여전히 `okstra install` 이 생성합니다 — `npm i -g` 에 포함되지 않습니다. 이후 업그레이드: `npm i -g okstra@latest && okstra install`. 글로벌 바이너리 제거: `npm uninstall -g okstra` (`~/.okstra/` 는 그대로; 그것까지 지우려면 `okstra uninstall`).
-
-**글로벌 설치 시 스킬 동작.** 모든 okstra 스킬은 PATH 에 잡힌 `okstra` 를 자동 감지하여 `npx -y okstra@latest` 대신 우선 사용합니다. 즉 글로벌 설치를 해두면 매 스킬 호출(`okstra-run`, `okstra-inspect`, `okstra-schedule`, `okstra-setup` Step 2 의 Step 0) 마다 npx 가 패키지 fetch / 버전 체크하던 비용이 사라집니다. 스킬이 본인이 설치한 버전을 그대로 쓰므로 **업그레이드 타이밍은 사용자가 통제** 합니다 — 더 이상 호출마다 `@latest` 가 강제되지 않습니다. 새 릴리스를 받으려면 원하는 시점에 `npm i -g okstra@latest && okstra install` 을 실행하세요. `okstra` 가 PATH 에 없으면 스킬은 자동으로 npx fallback 으로 동작하므로 글로벌 설치가 없는 환경에서도 변경 없이 그대로 동작합니다.
-
-### 3.2 프로젝트 등록 (프로젝트당 1회)
-
-CLI 에서:
-
-```bash
-cd <대상 프로젝트>
-npx -y okstra@latest setup --project-id <id>     # 예: INV-1234, my-app, okstra
-```
-
-또는 Claude Code 세션 안에서 동일한 슬래시 커맨드:
-
-```
-/okstra-setup
-```
-
-둘 다 `<project>/.okstra/project.json` 을 작성합니다. CLI 는 `--project-id` 가 주어지면 non-interactive 로 동작하므로 CI 에서 사용할 수 있고, 슬래시 커맨드는 `AskUserQuestion` 으로 prompt 합니다. 이 파일이 존재하기 전에는 다른 모든 사용자 스킬이 실행을 거부합니다.
-
-### 3.3 일상 명령
-
-Claude Code 세션 안에서 사용하는 슬래시 커맨드:
-
-| 커맨드 | 용도 |
-|---|---|
-| `/okstra-brief-gen` | 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 컨텍스트/읽기 비용), `errors` (run 에러 로그를 리포트로 집계), `error-zip` (cross-project 에러 로그를 익명화 zip 으로 수집·클러스터 요약), `recap` (run 간 전/후 요약 + task 의 `.okstra` 산출물 위 자유 Q&A) |
-| `/okstra-rollup` | task-group(또는 프로젝트 전체)의 모든 task run 결과를 모아 task별 run수/소요시간/에러와 그룹 합계를 집계하고, report 들을 묶어 task 횡단 종합 요약 작성 |
-| `/okstra-schedule` | task-group 전체에 대한 작업 계획표 생성 |
-| `/okstra-container-build` | 검증 완료된 task 의 코드를 로컬 docker compose 그룹으로 배포하고 컨테이너별 로그를 감시 (sub-command: `up` / `status` / `logs` / `stop-watcher` / `down`) |
-| `/okstra-graphify` | 프로젝트 자체 `.okstra/` 메모리(final report, `decisions/*.md`, `glossary.md`)를 지식그래프로 빌드·질의 (범위는 `.okstra/` 로 한정, 산출물은 `.okstra/graph/` 아래; sub-command: `build` / `query` / `path` / `explain` / `mcp` / `wiki`) |
-| `/okstra-manager` | 여러 프로젝트에 걸친 okstra task 를 manager-owned plan, assignment, 단방향 project sync snapshot, status, child launch context packet 으로 조정 |
-| `/okstra-setup` | 프로젝트별 부트스트랩 (§3.2) |
-
-lead 운영 계약과 지원 계약 — context-loader, team-contract, convergence, report-writer, 그리고 coding-preflight 팩 — 은 더 이상 agent 스킬로 설치되지 않습니다. okstra 런타임 리소스로 `~/.okstra/prompts/` (`prompts/lead/*.md`, `prompts/coding-preflight/*`) 아래에 배치되고, generated launch prompt 가 lead 에게 절대 경로를 전달합니다. 재설치 시 agent skill home 에 남은 과거 복사본은 prune 되므로 슬래시 커맨드로 노출되지 않습니다.
-
-### 3.4 CLI 모드 (선택)
-
-Claude Code 세션 밖에서 task 를 시작하려면:
-
-```bash
-~/.okstra/bin/okstra.sh \
-  --project-id <id> \
-  --task-group <group> \
-  --task-id <id> \
-  --task-type <requirements-discovery|improvement-discovery|error-analysis|implementation-planning|implementation|final-verification|release-handoff> \
-  --base-ref <branch|tag|sha> \
-  --task-brief ./brief.md
-```
-
-새 `claude` 프로세스를 띄워 lead 역할로 동작시킵니다. 전체 인자 목록은 `okstra.sh --help` 또는 [`docs/kr/cli.md`](docs/kr/cli.md) 참조.
-
-0.7.0 / 0.8.0 에서 추가된 주요 플래그:
-
-- `--executor claude|codex|antigravity` — `--task-type implementation` 에서 파일을 mutate 할 provider 를 선택합니다. 나머지 두 provider 는 같은 run 에서 strict read-only verifier 로 dispatch 됩니다 ([`docs/kr/cli.md`](docs/kr/cli.md#--executor)).
-- `--work-category bugfix|feature|refactor|ops|improvement` — `requirements-discovery` phase 를 건너뛰는 경우 작업 분류를 직접 지정합니다.
-- `--approve` — `--approved-plan` 과 함께 사용하면 plan 의 YAML frontmatter `approved` field 를 `false` → `true` 로 toggle 합니다 (제거된 `--ack-approved` alias 와 구 `[ ] Approved` 체크박스 마커 대체).
-
-0.8.0 이후 `main` 에 추가된 workflow 변경:
-
-- **모든 task-type 격리 worktree 자동 provisioning** — prepare 단계에서 `okstra-ctl` 이 task-key 당 한 번 `git worktree add ~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>` 를 수행해 격리된 working tree 와 브랜치 `<work-category-namespace>/<task-id-segment>` (예: `feature/dev-9436`, `fix/dev-7311`) 를 만듭니다. base ref 는 사용자가 `--base-ref` 로 지정 (release-handoff PR base picker 와 동일한 메뉴: `main` / `dev` / `staging` / `preprod` / `prod` / 직접 입력). 첫 phase 에서는 필수이며, okstra-run skill 이 `AskUserQuestion` 으로 수집합니다 — 비대화형 호출자는 `--base-ref` 플래그를 직접 전달해야 prepare 가 통과합니다. 같은 task-key 의 후속 **비-`implementation`** phase(`requirements-discovery` → `error-analysis` → `implementation-planning` → `final-verification` → `release-handoff`)는 같은 path/branch를 재사용합니다. 반면 `implementation` run 은 **stage 격리** 로 동작합니다 — 각 run 이 자신의 `.../<task>/stage-<N>/` worktree(브랜치 `<work-category-namespace>/<task>-s<N>`)에서 한 stage 만 실행하므로, 독립(`depends-on (none)`) stage 를 별도 run 으로 **동시에 병렬 구현** 할 수 있습니다(트리 공유 없음). registry 는 task-key 와 **stage-key** 를 함께 flock 예약합니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 됩니다(stage 격리도 평면 경로로 degrade). 수동 cleanup: `git worktree remove <path>` → `git branch -D <branch>` + registry 항목 release/remove. 상세: [`docs/kr/architecture.md`](docs/kr/architecture.md) *Task type* 섹션, [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
-- **`release-handoff` lifecycle phase** — `final-verification` 이 `verdict=accepted` 를 반환한 직후에 실행되는 신규 phase. lead 가 Claude worker (drafter) 를 통해 commit message · PR body 후보를 만들고, `AskUserQuestion` 으로 사용자에게 (1) action (`commit only` / `commit + PR` / `skip`), (2) PR base branch (`staging` / `preprod` / `prod` / `main` / `dev` / 직접 입력), (3) message handling (`use as-is` / `edit then proceed` / `cancel`) 세 가지를 순서대로 묻습니다. 사용자가 메뉴로 선택한 git / gh 명령만 실행되고, force-push, base 브랜치 직접 push, hook bypass (`--no-verify`), release publish (`gh release`, `npm publish`, ...) 는 금지됩니다. 이 phase 에서는 소스 코드를 수정하지 않습니다. profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
-- **PR 본문 템플릿 설정** (release-handoff) — PR 본문은 마크다운 템플릿에서 채워집니다. 해석 우선순위: 1회성 override (`--pr-template-path` 또는 okstra-run Step 6 prompt) → `<project_root>/.okstra/project.json` 의 `prTemplatePath` → `~/.okstra/config.json` 의 `prTemplatePath` → 스킬 디폴트 `~/.claude/skills/templates/prd/pr-body.template.md`. 템플릿 등록 명령: `okstra config set pr-template-path <path> [--scope project|global]` (project 스코프는 project root 기준 상대경로 허용, global 스코프는 절대경로 또는 `~/` 시작 경로만 허용). 현재 설정 확인: `okstra config get pr-template-path --scope all` 은 각 스코프 값 + 실제로 우승하는 경로(effective) 까지 보여줍니다. 디폴트 템플릿은 `## Summary` / `## Changes` / `## Test plan` / `## Linked issues` 4 섹션 + HTML 주석으로 lead 작성 가이드를 포함하며, PR 생성 직전에 lead 가 주석을 제거합니다.
-- **프로파일 워커 로스터 검증** — `--workers <csv>` 와 okstra-run Step 6 의 워커 prompt 는 해당 프로파일의 `Required workers:` 블록에 선언된 워커 ID 만 허용합니다. 프로파일에 없는 워커 (예: `release-handoff` 에서 `codex` / `antigravity`) 를 요청하면 명확한 에러로 거절되고, 인터랙티브 prompt 도 프로파일이 실제로 받는 워커만 보여줍니다.
-- **실험적 Codex lead adapter** — `okstra codex-run <render-bundle args...>` 가 Claude Code 를 띄우지 않고 `leadRuntime=codex` task bundle 을 준비합니다. 이어서 `okstra codex-dispatch --project-root <dir> --run-manifest <path>` 로 roster 중 Codex-side 지원 subset 을 실행합니다(Codex/Antigravity CLI worker 기본, Codex report-writer 는 `--enable-codex-report-writer --report-writer-codex-model <model>` opt-in 필요). 성공한 Codex report-writer dispatch 는 token/cost substitution, HTML view 렌더, follow-up stub 생성, run validation 을 순서대로 자동 실행합니다. Claude lead 경로와 같은 manifest/schema 를 공유하며, 프로젝트를 Codex 전용 fork 로 복제하지 않습니다.
-- **다단계 `implementation-planning` / `implementation`** — `implementation-planning` 은 항상 Stage Map + N 개 stage 섹션으로 산출합니다. 각 stage 의 step 은 ≤ 6 이며 `depends-on (none)` 인 stage 들은 별도 `implementation` run 으로 병렬 실행할 수 있습니다. 각 `implementation` 호출은 한 stage 만 실행하고 (`--stage <auto|N>`), 자동 생성되는 evidence sidecar (`carry/stage-<N>.json`) 가 다음 stage 의 carry-in 으로 흡수됩니다. `implementation-planning` run 디렉터리에 `consumers.jsonl` 역링크가 누적되어 어느 run 이 어느 stage 를 소비했는지 추적됩니다.
-- **Phase 6 plan-body verification (implementation-planning 전용)** — Report writer worker 가 final-report draft 를 작성한 직후, 사용자 승인 gate 직전에 lead 가 1 라운드의 사후 검증을 추가로 돌립니다. 합성된 `## 5.5` implementation plan deliverables 본문에서 `P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*` plan-item 을 추출해 모든 analyser 워커에게 `AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT` 평결을 요청합니다. 집계된 gate 결과는 `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result` 중 하나입니다. frontmatter `approved` 필드는 항상 `false` 로 발행되며, blocking gate 결과는 이를 false 로 유지하고 `## 1. Clarification Items` row 로 변환합니다. 빠른 반복용 opt-out 은 `--no-plan-verification` 입니다. 세부 계약: [`prompts/lead/convergence.md`](prompts/lead/convergence.md) "Plan-body verification mode", [`docs/kr/cli.md#--no-plan-verification`](docs/kr/cli.md#--no-plan-verification).
-- **Brief = translation layer + Step 6.5 reporter batch confirmation** — `okstra-brief-gen` 가 외부 입력 (이슈 ticket, 요구사항 문서, 사용자 메시지) 을 verbatim 으로 옮기되 okstra 가 추가한 부분은 labelled augmentation 으로 구분하는 translation layer 가 됐습니다. Step 6.5 가 brief 가 옮기는 과정에서 의미 변화가 발생했는지 사용자에게 일괄 확인받아 `Reporter Confirmations` 섹션에 기록하고, 모든 분석 profile 은 이 섹션의 존재를 phase 분석 진입 precondition 으로 강제합니다 (validator: `validators/validate-brief.py`).
-- **Artifact-home rule (`.okstra/`)** — okstra 의 project artifact root 는 `<project>/.okstra/` 하나뿐입니다. 이 root 밖은 okstra memory 가 아니며, Source Material 또는 Reporter Confirmations 가 명시적으로 cite 한 경우에만 read-only 로 읽습니다. 쓰기는 같은 explicit request path 를 요구합니다. okstra-internal 등가물: 용어집 `glossary.md`, 결정 기록 `decisions/<NNNN>-<slug>.md` (`implementation-planning` phase 에서 평가).
-- **Self-contained HTML final-report view** — Phase 7 가 `final-report-<task-type>-<seq>.md` 를 쓰면 `okstra render-views` 가 같은 `reports/` 폴더에 사람 reviewer 용 self-contained HTML view (CSS/JS 인라인, 외부 URL 0) 를 자동 생성합니다. HTML 의 `Export user response` 버튼은 `## 1. Clarification Items` 입력을 `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md` 사이드카로 직렬화해 다음 phase 가 소비합니다. 원본 MD 는 어떤 경우에도 view 생성으로 인해 수정되지 않습니다.
-- **`improvement-discovery` task-type (sidetrack entry-point)** — 코드베이스 범위 + 우선순위 lens 화이트리스트 안에서 multi-worker 합의 기반 개선 후보 N개 (기본 8, 절대 cap 12) 도출. `PHASE_SEQUENCE` 외부 sidetrack entry-point — 사용자가 후보를 골라 각각 새 task-id 로 `requirements-discovery` / `implementation-planning` / `error-analysis` 진입. lens enum SSOT: [`scripts/okstra_ctl/improvement_lenses.py`](scripts/okstra_ctl/improvement_lenses.py). 출력 섹션: `## 4.9 Improvement Candidates` (10-column 표). validator: [`validators/validate_improvement_report.py`](validators/validate_improvement_report.py).
-
-### 3.5 운영 명령
-
-| 커맨드 | 용도 |
-|---|---|
-| `npx -y okstra@latest paths` | 런타임 경로 출력 (`--field <name>` 또는 `--shell`) |
-| `npx -y okstra@latest doctor [--runtime claude-code\|codex\|all] [--phase <phase>]` | 런타임 + 스킬 + python import 진단. `codex` 는 Claude skill checks 를 제외하고, `--phase` 는 implementation / final-verification / release-handoff / improvement-discovery readiness 체크를 추가 |
-| `npx -y okstra@latest ensure-installed` | Idempotent 체크, stale 이면 자동 재설치 (스킬이 내부적으로 호출) |
-| `npx -y okstra@latest setup --project-id <id>` | 현재 프로젝트를 등록 (`.okstra/project.json`) |
-| `npx -y okstra@latest check-project` | 현재 프로젝트가 `setup` 으로 등록됐는지 검증 |
-| `npx -y okstra@latest config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | okstra 설정 읽기/쓰기. 현재 지원 키: `pr-template-path` (project.json 또는 `~/.okstra/config.json` 의 `prTemplatePath` 갱신) |
-| `npx -y okstra@latest memory <add\|list\|search\|show\|archive>` | `~/.okstra/memory-book` 전역 대화 메모리 저장·검색·보관 |
-| `npx -y okstra@latest context-cost <task-key\|task-root> [--project-root <path>]` | task bundle 의 lead/worker/report-writer 컨텍스트·읽기 비용 추정 |
-| `npx -y okstra@latest render-views <final-report.md>` | final-report MD 한 본을 입력으로 self-contained HTML view 를 (재)생성 (Phase 7 step 1.5; 멱등) |
-| `npx -y okstra@latest token-usage ...` | run token usage 수집/치환. 설치된 Python token usage CLI를 감싼 Node wrapper |
-| `npx -y okstra@latest uninstall` | 런타임 + 스킬 제거; 사용자 데이터(`recent.jsonl`, `projects/`, …)는 보존 |
-| `npx -y okstra@latest uninstall --purge -y` | 사용자 데이터까지 모두 제거 |
-
-## 4. 더 읽을 자료
-
-- [`docs/kr/architecture.md`](docs/kr/architecture.md) — 한국어 상세 매뉴얼: prompt contract, team contract, storage model, task type 별 phase 규칙, lifecycle, workflow.
-- [`docs/kr/cli.md`](docs/kr/cli.md) — `okstra.sh` 의 모든 인자 / 옵션과 인터랙티브 입력 흐름.
-- [`RELEASING.md`](RELEASING.md) — 버전 컷과 publish 절차 (release-please + 수동 fallback).
-- [`CHANGELOG.md`](CHANGELOG.md) — release 별 변경 이력.

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

@@ -1,297 +0,0 @@
-# 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>.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 안에 직접 작성하는 결과물입니다.
-self-contained 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 installed skill assets
-프로젝트 공용 discovery pointer는 아래 경로에 생성합니다.
-
-```text
-<target-project>/.okstra/discovery/latest-task.json
-<target-project>/.okstra/discovery/task-catalog.json
-```
-
-역할 구분:
-
-- `.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-*/...`, `~/.agents/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`
-
-### 4. Manager-owned cross-project state
-
-`okstra manager` 는 project-local `.okstra` 정본을 대체하지 않고, 여러 project-local task 를 묶는 전역 manager state 를 사용자 홈에 저장합니다.
-
-```text
-~/.okstra/managers/<manager-id>/
-├── manager.json
-├── projects.json
-└── task-groups/<safe-task-group>/<safe-task-id>/
-    ├── manifest.json
-    ├── children.json
-    ├── directives.jsonl
-    ├── snapshots.json
-    ├── events.jsonl
-    └── child-context/<safe-project-id>-<safe-child-task-id>.md
-```
-
-저장 권위:
-
-- `manager.json`: manager identity 와 schema version.
-- `projects.json`: manager 에 등록된 projectId / projectRoot / role / tags. `projectRoot` 는 이미 존재하는 디렉터리여야 하며, project-local `.okstra/project.json` 이 없을 때만 setup-equivalent registration 을 수행합니다.
-- `manifest.json`, `children.json`, `directives.jsonl`: manager-owned plan, child assignment, shared/project directive.
-- `snapshots.json`: `task sync` 가 child project `.okstra` 에서 읽어온 read-side snapshot. project state 의 source of truth 가 아닙니다.
-- `events.jsonl`: `task-created`, `child-launch-prepared` 같은 manager event.
-- `child-context/*.md`: `task run` 이 준비한 child lead context. sibling project report/snapshot 은 read-side source material 로만 전달합니다.
-
-Path segment 는 slug 로 정규화합니다. 비 ASCII 값처럼 slug 가 비는 경우에는 `u-<sha1-prefix>` fallback segment 를 쓰지만, `manifest.json` 과 child `taskKey` 는 원래 입력값(`project-id:task-group:task-id`)을 보존합니다.
-
-## 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`
-- `phaseOutcome` *(artifact-derived semantic phase outcome; 예: implementation carry 가 모든 stage 통과를 증명하면 run contract validation 실패가 남아 있어도 implementation phase outcome 은 completed 로 기록될 수 있음)*
-- `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-context-<task-type>-<seq>.json`은 schemaVersion `2.0`부터 모든 legacy path key를 직접 저장하지 않고 `identity` + `pathHints`를 저장합니다. host-side reader는 `pathHints`를 hydrate해 기존 flat key(`RUN_MANIFEST_RELATIVE_PATH`, `TEAM_STATE_PATH` 등)를 메모리에서 재구성합니다.
-
-`state/active-run-context-<task-type>-<seq>.json`도 schemaVersion `2.0`부터 lead Phase 1용 compact intake입니다. 반복 path 문자열 대신 `identity` + `pathHints`와 worker identity만 저장하고, deterministic dispatcher는 읽을 때 legacy active context shape로 hydrate합니다.
-
-`manifests/run-manifest-<task-type>-<seq>.json`의 path 계열 필드는 아직 validator / team dispatch / inspect 호환을 위해 대상 프로젝트 루트 기준 상대경로로 저장합니다.
-`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차 입력으로 읽습니다. 이 파일은 `identity` + `pathHints` 단서로 run artifact 경로를 재구성하는 compact intake입니다. 없으면 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`