okstra 0.34.0 → 0.36.0

package/README.kr.md

@@ -39,13 +39,13 @@ okstra 는 단발성 코드 리뷰 도구가 **아닙니다**. **여러 phase
 okstra/                          npm 패키지 = repo 루트
 ├── package.json                 name: "okstra"
 ├── bin/okstra                   노드 CLI 진입점
-├── src/                         설치자 + 리졸버 (install, paths, doctor, check-project, uninstall)
+├── src/                         Node CLI 명령 모듈 (install, wizard, config, render, token usage, ...)
 ├── tools/build.mjs              runtime/ 동기화 스크립트 (prepack 에서 호출)
-├── runtime/                     gitignored 빌드 산출물; ~/.okstra 로 배포되는 유일한 자산
+├── runtime/                     gitignored 설치 payload; ~/.okstra 로 복사
 ├── scripts/                     python + bash 런타임 소스
 ├── skills/                      Claude Code 스킬 마크다운 소스 (스킬 13종)
 ├── agents/                      lead SKILL.md + workers/
-├── prompts/, templates/, validators/
+├── prompts/, schemas/, templates/, validators/
 ├── docs/kr/                     한국어 상세 매뉴얼 (architecture.md, cli.md)
 ├── tests/, tests-e2e/
 ├── .claude-plugin/plugin.json   보조 skills-CLI 채널 매니페스트
@@ -53,7 +53,7 @@ okstra/                          npm 패키지 = repo 루트
 └── RELEASING.md, CHANGELOG.md, README.md, README.kr.md
 ```
 
-`runtime/` 은 `prepack` 시점에 `tools/build.mjs` 가 `scripts/`, `skills/`, `agents/`, `prompts/`, `templates/`, `validators/` 로부터 다시 빌드합니다. npm 에 publish 되고 `~/.okstra` 로 복사되는 유일한 산출물입니다.
+`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 설치 후 사용자 머신 레이아웃
 
@@ -62,16 +62,18 @@ okstra/                          npm 패키지 = repo 루트
 ├── version                      패키지 버전 stamp
 ├── lib/python/                  okstra_project/, okstra_ctl/, okstra_token_usage/, lib/
 ├── bin/                         okstra.sh, codex-exec, gemini-exec, ...
+├── templates/                   report asset, settings template, okstra.CLAUDE.md
 ├── installed-skills.json        설치된 스킬 매니페스트 (uninstall 이 사용)
 ├── installed-agents.json        설치된 워커 에이전트 매니페스트 (uninstall 이 사용)
 ├── recent.jsonl, active.jsonl   run 인덱스
 ├── projects/                    프로젝트별 메타데이터 미러
-├── worktrees/                   `--task-type implementation` run 마다 자동 생성되는
-│                                격리 git worktree (run 종료 후 자동 삭제하지 않음)
-└── archive/                     완료된 run
+├── worktrees/                   task-key 당 하나의 격리 git worktree
+│                                (모든 phase가 공유; run 종료 후 자동 삭제하지 않음)
+├── archive/                     완료된 run
+└── .locks/                      central/task mutex 파일
 
 ~/.claude/skills/                Claude Code 가 자동 인식
-└── okstra-*/SKILL.md            스킬 12종 (§3.3 참조)
+└── okstra-*/SKILL.md            스킬 13종 (§3.3 참조)
 
 ~/.claude/agents/                Claude Code 가 자동 인식 (subagent 디스커버리 경로)
 └── {claude,codex,gemini,report-writer}-worker.md   worker subagent 정의
@@ -80,6 +82,8 @@ okstra/                          npm 패키지 = repo 루트
 <프로젝트 루트>/.project-docs/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)
 ```
 
@@ -88,7 +92,7 @@ okstra/                          npm 패키지 = repo 루트
 | 리소스 | 위치 | 소유자 |
 |---|---|---|
 | 런타임 코드 (python + bash) | `~/.okstra/{lib/python, bin}` | `okstra install` |
-| agents/prompts/templates/validators | npm 패키지의 `runtime/` | `okstra` 패키지 자체 (`okstra paths` 로 해석) |
+| agents/prompts/schemas/templates/validators | npm 패키지의 `runtime/` | `okstra` 패키지 자체 (`okstra paths` 로 해석) |
 | 스킬 마크다운 | `~/.claude/skills/<name>/SKILL.md` | `okstra install` (`installed-skills.json` 에 트래킹) |
 | 워커 에이전트 마크다운 | `~/.claude/agents/<worker>.md` | `okstra install` (`installed-agents.json` 에 트래킹) |
 | 프로젝트 메타데이터 | `<project>/.project-docs/okstra/` | `/okstra-setup` + 프로젝트 자체 |
@@ -102,7 +106,7 @@ okstra/                          npm 패키지 = repo 루트
 npx -y okstra@latest install
 ```
 
-`~/.okstra/{lib/python, bin, version}`, `~/.claude/skills/` 아래 스킬 마크다운 13개, `~/.okstra/installed-skills.json` 을 생성합니다. 재실행은 idempotent — 파일별 hash 를 비교하고 바뀐 파일만 갱신합니다.
+`~/.okstra/{lib/python, bin, templates, version}`, `~/.claude/skills/` 아래 스킬 마크다운 13개, `~/.claude/agents/` 아래 worker agent 4개, `~/.okstra/` 의 설치 asset manifest 를 생성합니다. 재실행은 idempotent — 파일별 hash 를 비교하고 바뀐 파일만 갱신합니다.
 
 검증:
 
@@ -149,13 +153,15 @@ Claude Code 세션 안에서 사용하는 슬래시 커맨드:
 
 | 커맨드 | 용도 |
 |---|---|
+| `/okstra-brief` | ticket, 요구사항 문서, 링크, 대화 내용을 `okstra-run`용 task brief로 변환 |
 | `/okstra-run` | 새 task 시작 (또는 기존 task 의 다음 phase 이어가기) |
 | `/okstra-status` | phase / 상태 조회, task 의 workStatus 설정 |
 | `/okstra-history` | 과거 task 목록, 이어할 task 선택 |
 | `/okstra-schedule` | task-group 전체에 대한 작업 계획표 생성 |
 | `/okstra-setup` | 프로젝트별 부트스트랩 (§3.2) |
+| `/okstra-logs` | worker wrapper log sidecar를 조회하고 cleanup 명령을 제안하되 직접 실행하지 않음 |
 
-이 외에 `okstra-context-loader`, `okstra-team-contract`, `okstra-convergence`, `okstra-report-writer`, `okstra-time-summary`, `okstra-report-finder`, `okstra-logs` 7종은 `user-invocable: false` 로 표시되어 슬래시 커맨드로 노출되지 않습니다. lead 또는 Claude 가 자연어 트리거(예: "이 task 얼마나 걸렸어?" → `okstra-time-summary`, "보고서 찾아줘" → `okstra-report-finder`, "codex/gemini 로그 용량 보여줘" → `okstra-logs` — wrapper 가 매 dispatch 마다 남기는 `<prompt>.log` sidecar 의 용량을 집계하고 task / phase / worker 별로 즉시 복사 가능한 `find … -delete` cleanup 명령을 제시하되 직접 실행하지는 않음)로 자동 호출합니다.
+이 외에 `okstra-context-loader`, `okstra-team-contract`, `okstra-convergence`, `okstra-report-writer`, `okstra-time-summary`, `okstra-report-finder` 6종은 `user-invocable: false` 로 표시되어 슬래시 커맨드로 노출되지 않습니다. lead 또는 Claude 가 자연어 트리거(예: "이 task 얼마나 걸렸어?" → `okstra-time-summary`, "보고서 찾아줘" → `okstra-report-finder`)나 okstra phase 흐름에 따라 자동 호출합니다.
 
 ### 3.4 CLI 모드 (선택)
 
@@ -166,7 +172,8 @@ Claude Code 세션 밖에서 task 를 시작하려면:
   --project-id <id> \
   --task-group <group> \
   --task-id <id> \
-  --task-type <error-analysis|implementation-planning|...> \
+  --task-type <requirements-discovery|improvement-discovery|error-analysis|implementation-planning|implementation|final-verification|release-handoff> \
+  --base-ref <branch|tag|sha> \
   --task-brief ./brief.md
 ```
 
@@ -176,18 +183,20 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 
 - `--executor claude|codex|gemini` — `--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` 과 함께 사용하면 CLI 호출 자체를 implementation-planning 승인 신호로 처리합니다 (제거된 `--ack-approved` alias 대체).
+- `--approve` — `--approved-plan` 과 함께 사용하면 plan 의 YAML frontmatter `approved` field 를 `false` → `true` 로 toggle 합니다 (제거된 `--ack-approved` alias 와 구 `[ ] Approved` 체크박스 마커 대체).
 
 0.8.0 이후 `main` 에 추가된 workflow 변경:
 
-- **`--task-type implementation` 격리 worktree 자동 provisioning** — prepare 단계에서 `okstra-ctl` 이 `git worktree add ~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>-<run-seq>` 를 수행해 격리된 working tree 와 브랜치 `<work-category-prefix>-<task-id-segment>-<run-seq>` (예: `feat-dev-9436-001`, `fix-dev-7311-002`) 를 만듭니다. base ref 는 사용자가 `--base-ref` 로 지정 (release-handoff PR base picker 와 동일한 메뉴: `main` / `dev` / `staging` / `preprod` / `prod` / 직접 입력). 첫 phase 에서는 필수이며, okstra-run skill 이 `AskUserQuestion` 으로 수집합니다 — 비대화형 호출자는 `--base-ref` 플래그를 직접 전달해야 prepare 가 통과합니다. Executor 와 verifier 모두 이 worktree 안에서 동작하므로 caller 의 작업 디렉터리는 깨끗하게 유지되고, worktree 는 PR 작성 · rollback 검증의 권위 artefact 로 남습니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 됩니다. 수동 cleanup: `git worktree remove <path>` → `git branch -D <branch>`. 상세: [`docs/kr/architecture.md`](docs/kr/architecture.md) *Task type* 섹션, [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
+- **모든 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-prefix>-<task-id-segment>` (예: `feat-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 의 모든 후속 phase(`requirements-discovery` → `error-analysis` → `implementation-planning` → `implementation` → `final-verification` → `release-handoff`)는 같은 path/branch를 재사용합니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 됩니다. 수동 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>/.project-docs/okstra/project.json` 의 `prTemplatePath` → `~/.okstra/config.json` 의 `prTemplatePath` → 스킬 디폴트 `~/.claude/skills/okstra-run/templates/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` / `gemini`) 를 요청하면 명확한 에러로 거절되고, 인터랙티브 prompt 도 프로파일이 실제로 받는 워커만 보여줍니다.
-- **Phase 6 plan-body verification (implementation-planning 전용)** — Report writer worker 가 final-report draft 를 작성한 직후, User Approval gate 직전에 lead 가 1 라운드의 사후 검증을 추가로 돌립니다. 합성된 `## 4.5` plan 본문에서 `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` 중 하나. 앞 둘은 final-report 상단의 `- [ ] Approved` 마커를 렌더하고, 뒤 둘은 `majority-disagree` 항목을 `## 5. Clarification Items` 의 `Blocks=approval` row 로 변환합니다. 빠른 반복용 opt-out: `--no-plan-verification` (기본값: 활성). 자세한 라운드 프로토콜은 [`skills/okstra-convergence/SKILL.md`](skills/okstra-convergence/SKILL.md) 의 "Plan-body verification mode" 섹션과 [`docs/kr/cli.md#--no-plan-verification`](docs/kr/cli.md#--no-plan-verification).
+- **다단계 `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 라운드의 사후 검증을 추가로 돌립니다. 합성된 `## 4.5` plan 본문에서 `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` 로 발행되며, gate 가 `blocked-by-disagreement` 또는 `aborted-non-result` 일 때 writer 는 `approved: false` 를 유지해야 하고 (이런 gate 결과로 `approved: true` 로 ship 된 report 는 validator 가 거부), `majority-disagree` 항목을 `## 5. Clarification Items` 의 `Blocks=approval` row 로 변환합니다. 빠른 반복용 opt-out: `--no-plan-verification` (기본값: 활성). 자세한 라운드 프로토콜은 [`skills/okstra-convergence/SKILL.md`](skills/okstra-convergence/SKILL.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` 가 외부 입력 (이슈 ticket, 요구사항 문서, 사용자 메시지) 을 verbatim 으로 옮기되 okstra 가 추가한 부분은 labelled augmentation 으로 구분하는 translation layer 가 됐습니다. Step 6.5 가 brief 가 옮기는 과정에서 의미 변화가 발생했는지 사용자에게 일괄 확인받아 `Reporter Confirmations` 섹션에 기록하고, 모든 분석 profile 은 이 섹션의 존재를 phase 분석 진입 precondition 으로 강제합니다 (validator: `validators/validate-brief.py`).
-- **Artifact-home rule (`.project-docs/okstra/`)** — okstra 가 사용자 프로젝트에 쓰는 모든 파일은 `<project>/.project-docs/okstra/` subtree 안에만 위치합니다. 외부 경로 (`CONTEXT.md`, `docs/adr/`, `.scratch/`, 소스 코드) 는 read-only reference 이며 부재해도 정상 상태입니다. okstra-internal 등가물: 용어집 `glossary.md`, 결정 기록 `decisions/<NNNN>-<slug>.md` (`implementation-planning` phase 에서 평가).
+- **Artifact-home rule (`.project-docs/okstra/`)** — okstra 의 project artifact root 는 `<project>/.project-docs/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 에서 평가).
 - **Dual-format final-report views** — Phase 7 가 `final-report-<task-type>-<seq>.md` 를 쓰면 `okstra render-views` 가 같은 `reports/` 폴더에 두 view 를 자동 생성합니다: AI 다음-phase 입력용 슬림 markdown, 사람 reviewer 용 self-contained HTML (CSS/JS 인라인, 외부 URL 0). HTML 의 `Export user response` 버튼은 `## 5. 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 운영 명령
 
@@ -200,6 +209,7 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 | `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 render-views <final-report.md>` | final-report MD 한 본을 입력으로 슬림 MD + 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` | 사용자 데이터까지 모두 제거 |
 

package/README.md

@@ -39,20 +39,20 @@ okstra is **not** a one-shot code reviewer. It targets work that **spans multipl
 okstra/                          npm package = repo root
 ├── package.json                 name: "okstra"
 ├── bin/okstra                   Node CLI entrypoint
-├── src/                         installer + resolvers (install, paths, doctor, check-project, uninstall)
+├── src/                         Node CLI command modules (install, wizard, config, render, token usage, ...)
 ├── tools/build.mjs              runtime/ sync script (invoked by prepack)
-├── runtime/                     gitignored build output; the only thing shipped to ~/.okstra
+├── runtime/                     gitignored install payload copied to ~/.okstra
 ├── scripts/                     python + bash runtime sources
 ├── skills/                      Claude Code skill markdown sources (13 skills)
 ├── agents/                      lead SKILL.md + workers/
-├── prompts/, templates/, validators/
+├── prompts/, schemas/, templates/, validators/
 ├── tests/, tests-e2e/
 ├── .claude-plugin/plugin.json   secondary skills-CLI channel manifest
 ├── .github/workflows/           release-please.yml, release.yml
 └── RELEASING.md, CHANGELOG.md, README.md, README.kr.md
 ```
 
-`runtime/` is rebuilt from `scripts/`, `skills/`, `agents/`, `prompts/`, `templates/`, and `validators/` by `tools/build.mjs` during `prepack`. It is the only artifact published to npm and copied to `~/.okstra`.
+`runtime/` is rebuilt from `scripts/`, `skills/`, `agents/`, `prompts/`, `schemas/`, `templates/`, and `validators/` by `tools/build.mjs` during `prepack`. It is the install payload copied into `~/.okstra`; the npm package also ships the Node CLI (`bin/`, `src/`), docs, and READMEs.
 
 ### 2.2 User-machine layout after install
 
@@ -61,16 +61,18 @@ okstra/                          npm package = repo root
 ├── version                      package version stamp
 ├── lib/python/                  okstra_project/, okstra_ctl/, okstra_token_usage/, lib/
 ├── bin/                         okstra.sh, codex-exec, gemini-exec, ...
+├── templates/                   report assets, settings template, okstra.CLAUDE.md
 ├── installed-skills.json        manifest of installed skills (used by uninstall)
 ├── installed-agents.json        manifest of installed worker agents (used by uninstall)
 ├── recent.jsonl, active.jsonl   run index
 ├── projects/                    per-project metadata mirror
-├── worktrees/                   isolated git worktrees auto-provisioned per
-│                                `--task-type implementation` run (not auto-removed)
-└── archive/                     completed runs
+├── worktrees/                   one isolated git worktree per task-key
+│                                (shared by all phases; not auto-removed)
+├── archive/                     completed runs
+└── .locks/                      central/task mutex files
 
 ~/.claude/skills/                discovered automatically by Claude Code
-└── okstra-*/SKILL.md            12 skills total (see §3.3)
+└── okstra-*/SKILL.md            13 skills total (see §3.3)
 
 ~/.claude/agents/                discovered automatically by Claude Code
 └── {claude,codex,gemini,report-writer}-worker.md   subagent definitions
@@ -79,6 +81,8 @@ okstra/                          npm package = repo root
 <project-root>/.project-docs/okstra/
 ├── project.json                 {projectId, projectRoot, ...} (written by /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)
 ```
 
@@ -87,7 +91,7 @@ okstra/                          npm package = repo root
 | Resource | Location | Owner |
 |---|---|---|
 | Runtime code (python + bash) | `~/.okstra/{lib/python, bin}` | `okstra install` |
-| agents/prompts/templates/validators | npm package's `runtime/` | the `okstra` package (resolved via `okstra paths`) |
+| agents/prompts/schemas/templates/validators | npm package's `runtime/` | the `okstra` package (resolved via `okstra paths`) |
 | Skill markdown | `~/.claude/skills/<name>/SKILL.md` | `okstra install` (tracked in `installed-skills.json`) |
 | Worker agent markdown | `~/.claude/agents/<worker>.md` | `okstra install` (tracked in `installed-agents.json`) |
 | Project metadata | `<project>/.project-docs/okstra/` | `/okstra-setup` + the project itself |
@@ -101,7 +105,7 @@ okstra/                          npm package = repo root
 npx -y okstra@latest install
 ```
 
-Provisions `~/.okstra/{lib/python, bin, version}`, the 13 skill markdown files under `~/.claude/skills/`, and `~/.okstra/installed-skills.json`. Re-running is idempotent — per-file hashes are compared and only changed files are touched.
+Provisions `~/.okstra/{lib/python, bin, templates, version}`, the 13 skill markdown files under `~/.claude/skills/`, the 4 worker agents under `~/.claude/agents/`, and the installed-asset manifests in `~/.okstra/`. Re-running is idempotent — per-file hashes are compared and only changed files are touched.
 
 Verify:
 
@@ -148,13 +152,15 @@ User-facing slash commands inside a Claude Code session:
 
 | Command | Use |
 |---|---|
+| `/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-status` | Phase / state overview, or set a task's workStatus |
 | `/okstra-history` | List past tasks, choose what to resume |
 | `/okstra-schedule` | Generate a work schedule for an entire task-group |
 | `/okstra-setup` | Per-project bootstrap (§3.2) |
+| `/okstra-logs` | Inspect worker wrapper log sidecars and print cleanup commands without executing them |
 
-Seven additional skills — `okstra-context-loader`, `okstra-team-contract`, `okstra-convergence`, `okstra-report-writer`, `okstra-time-summary`, `okstra-report-finder`, `okstra-logs` — are marked `user-invocable: false` and do not appear as slash commands. Claude still invokes them automatically via natural-language triggers (e.g. "이 task 얼마나 걸렸어?" routes to `okstra-time-summary`; "show me the report for X" routes to `okstra-report-finder`; "codex/gemini 로그 용량 보여줘" routes to `okstra-logs`, which inventories the `<prompt>.log` sidecars produced by every CLI dispatch and emits ready-to-copy `find … -delete` cleanup lines without executing them).
+Six support skills — `okstra-context-loader`, `okstra-team-contract`, `okstra-convergence`, `okstra-report-writer`, `okstra-time-summary`, `okstra-report-finder` — are marked `user-invocable: false` and do not appear as slash commands. Claude still invokes them automatically via natural-language triggers or okstra phase flow (e.g. "이 task 얼마나 걸렸어?" routes to `okstra-time-summary`; "show me the report for X" routes to `okstra-report-finder`).
 
 ### 3.4 CLI mode (optional)
 
@@ -165,7 +171,8 @@ To kick off a task from outside a Claude Code session:
   --project-id <id> \
   --task-group <group> \
   --task-id <id> \
-  --task-type <error-analysis|implementation-planning|...> \
+  --task-type <requirements-discovery|improvement-discovery|error-analysis|implementation-planning|implementation|final-verification|release-handoff> \
+  --base-ref <branch|tag|sha> \
   --task-brief ./brief.md
 ```
 
@@ -175,18 +182,20 @@ Notable flags added in 0.7.0 / 0.8.0:
 
 - `--executor claude|codex|gemini` — pick the provider that mutates files during `--task-type implementation`. The other two providers are still dispatched as read-only verifiers (see [`docs/kr/cli.md`](docs/kr/cli.md#--executor)).
 - `--work-category bugfix|feature|refactor|ops|improvement` — classify a task when the lifecycle skips `requirements-discovery`.
-- `--approve` — combined with `--approved-plan`, treats the CLI invocation itself as the implementation-planning approval signal (replaces the removed `--ack-approved` alias).
+- `--approve` — combined with `--approved-plan`, flips the plan's YAML frontmatter `approved` field from `false` to `true` (replaces the removed `--ack-approved` alias and the older `[ ] Approved` checkbox marker).
 
 Recent workflow additions (post-0.8.0, on `main`):
 
-- **Isolated task worktree for every task-type** — prepare automatically runs `git worktree add ~/.okstra/worktrees/<project>/<group>/<task>/` on a fresh branch `<work-category-prefix>-<task-id-segment>` branched from the **user-chosen base ref** (`--base-ref`, mirroring the `release-handoff` PR-base picker: `main` / `dev` / `staging` / `preprod` / `prod` / any local ref) the first time a task-key is seen. `--base-ref` is required on first phase; the okstra-run skill collects it via `AskUserQuestion`, non-interactive callers must pass the flag explicitly. Every subsequent phase of the same task-key (`requirements-discovery` → `error-analysis` → `implementation-planning` → `implementation`) reuses the same path and branch, so phase N inherits the working-tree state phase N-1 left behind. A global registry at `~/.okstra/worktrees/registry.json` (flock-guarded) reserves task-keys and branches across concurrent runs; all path/branch segments are sanitised (`/`, `:`, etc. → `-`). The worktree is preserved after every run for follow-up phases, PR authoring, and rollback. Skip paths: when the caller is already inside another worktree or `project_root` is not a git repo, provisioning no-ops. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` plus removing the task-key entry from the registry. Details: [`docs/kr/architecture.md`](docs/kr/architecture.md) (*Task type* section) and [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
+- **Isolated task worktree for every task-type** — prepare automatically runs `git worktree add ~/.okstra/worktrees/<project>/<group>/<task>/` on a fresh branch `<work-category-prefix>-<task-id-segment>` branched from the **user-chosen base ref** (`--base-ref`, mirroring the `release-handoff` PR-base picker: `main` / `dev` / `staging` / `preprod` / `prod` / any local ref) the first time a task-key is seen. `--base-ref` is required on first phase; the okstra-run skill collects it via `AskUserQuestion`, non-interactive callers must pass the flag explicitly. Every subsequent phase of the same task-key (`requirements-discovery` → `error-analysis` → `implementation-planning` → `implementation` → `final-verification` → `release-handoff`) reuses the same path and branch, so phase N inherits the working-tree state phase N-1 left behind. A global registry at `~/.okstra/worktrees/registry.json` (flock-guarded) reserves task-keys and branches across concurrent runs; all path/branch segments are sanitised (`/`, `:`, etc. → `-`). The worktree is preserved after every run for follow-up phases, PR authoring, and rollback. Skip paths: when the caller is already inside another worktree or `project_root` is not a git repo, provisioning no-ops. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` plus releasing/removing the task-key from the registry. Details: [`docs/kr/architecture.md`](docs/kr/architecture.md) (*Task type* section) and [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
 - **`release-handoff` lifecycle phase** — runs after `final-verification` returns `verdict=accepted`. The lead drafts a commit message and PR body via a Claude worker, then prompts the user with `AskUserQuestion` for three choices: action (`commit only` / `commit + PR` / `skip`), PR base branch (`staging` / `preprod` / `prod` / `main` / `dev` / free-form), and message handling (`use as-is` / `edit then proceed` / `cancel`). Only user-selected mutating git/gh commands run. Force-push, base-branch direct push, hook bypass (`--no-verify`), and release publishing (`gh release`, `npm publish`, ...) are forbidden. Source code is not edited in this phase. Profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
 - **Configurable PR body template** (release-handoff) — the PR body is filled from a markdown template chosen in priority order: per-run override (`--pr-template-path` or the okstra-run Step 6 prompt) → `<project_root>/.project-docs/okstra/project.json` `prTemplatePath` → `~/.okstra/config.json` `prTemplatePath` → bundled skill default at `~/.claude/skills/okstra-run/templates/pr-body.template.md`. Register a template with `okstra config set pr-template-path <path> [--scope project|global]` (project scope accepts paths relative to the project root; global scope requires absolute or `~/`-prefixed). `okstra config get pr-template-path --scope all` reports every scope plus the effective winner. The bundled default ships `## Summary` / `## Changes` / `## Test plan` / `## Linked issues` with HTML comment guidance that the lead strips before opening the PR.
 - **Profile-roster worker validation** — `--workers <csv>` (and the okstra-run Step 6 worker prompt) are now restricted to the worker IDs declared by the chosen profile's `Required workers:` block. Asking for `codex` / `gemini` on a profile that does not list them (e.g. `release-handoff`) is rejected with a clear error, and the interactive prompt only offers workers the profile actually accepts.
-- **Phase 6 plan-body verification (implementation-planning only)** — after the Report writer worker authors the final-report draft and before the User Approval gate, the lead now runs one additional verification round: it extracts `P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*` items from the consolidated `## 4.5` plan body and dispatches them to every analyser worker as `AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`. The aggregated gate result is one of `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`; only the first two render the top-of-report `- [ ] Approved` marker, the other two convert `majority-disagree` items into `## 5. Clarification Items` rows with `Blocks=approval`. Disable for fast iteration with `--no-plan-verification` (default: enabled). Details: [`skills/okstra-convergence/SKILL.md`](skills/okstra-convergence/SKILL.md) "Plan-body verification mode" and [`docs/kr/cli.md#--no-plan-verification`](docs/kr/cli.md#--no-plan-verification).
+- **Multi-stage `implementation-planning` / `implementation`** — `implementation-planning` always produces a Stage Map plus N stage sections; each stage has ≤6 steps and stages whose `depends-on (none)` can be executed in parallel by separate `implementation` runs. Each `implementation` invocation picks one stage (via `--stage <auto|N>`) and emits an evidence sidecar (`carry/stage-<N>.json`) that the next stage automatically inherits. The `implementation-planning` run directory accumulates a `consumers.jsonl` reverse-link showing which `implementation` runs consumed which stage.
+- **Phase 6 plan-body verification (implementation-planning only)** — after the Report writer worker authors the final-report draft and before the user approval gate, the lead now runs one additional verification round: it extracts `P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*` items from the consolidated `## 4.5` plan body and dispatches them to every analyser worker as `AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`. The aggregated gate result is one of `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`. The frontmatter `approved` flag is always emitted as `false`; when the gate is `blocked-by-disagreement` or `aborted-non-result` the writer MUST keep it `false` (the validator refuses any report that publishes `approved: true` under such a gate) and convert `majority-disagree` items into `## 5. Clarification Items` rows with `Blocks=approval`. Disable for fast iteration with `--no-plan-verification` (default: enabled). Details: [`skills/okstra-convergence/SKILL.md`](skills/okstra-convergence/SKILL.md) "Plan-body verification mode" and [`docs/kr/cli.md#--no-plan-verification`](docs/kr/cli.md#--no-plan-verification).
 - **Brief as translation layer + reporter batch confirmation (Step 6.5)** — `okstra-brief` now produces the brief as a translation layer that preserves external inputs (issue ticket, requirements doc, user message) verbatim while labelling okstra augmentations. A new Step 6.5 walks the user through a single batch confirmation of any rewordings, recorded in a `Reporter Confirmations` section. Every analysis profile blocks phase entry until this section exists (validator: `validators/validate-brief.py`).
-- **Artifact-home rule (`.project-docs/okstra/`)** — okstra writes only inside `<project>/.project-docs/okstra/`. External paths (`CONTEXT.md`, `docs/adr/`, `.scratch/`, source code) are read-only references; their absence is normal. okstra-internal equivalents: `glossary.md` for terminology and `decisions/<NNNN>-<slug>.md` for decision records (evaluated in `implementation-planning`).
+- **Artifact-home rule (`.project-docs/okstra/`)** — okstra's project artifact root is only `<project>/.project-docs/okstra/`. Anything outside that root is not okstra memory; it may be read only when explicitly cited as Source Material or Reporter Confirmations, and writes require the same explicit request path. okstra-internal equivalents: `glossary.md` for terminology and `decisions/<NNNN>-<slug>.md` for decision records (evaluated in `implementation-planning`).
 - **Dual-format final-report views** — after Phase 7 writes `final-report-<task-type>-<seq>.md`, `okstra render-views` automatically emits two sibling views in the same `reports/` directory: a slim Markdown for downstream AI input and a self-contained HTML (inline CSS/JS, no external URLs) for human review. The HTML lets a reviewer fill in `## 5. Clarification Items` decisions and export them to `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md`, which the next phase consumes as input. The original MD is never modified by view generation.
+- **`improvement-discovery` task-type (sidetrack entry-point)** — Discover ranked improvement candidates within a codebase scope and lens whitelist via multi-worker consensus (default top-8, hard cap 12). Outside `PHASE_SEQUENCE`; the user selects candidates and opens each as a new task with `requirements-discovery`, `implementation-planning`, or `error-analysis`. Lens enum SSOT: [`scripts/okstra_ctl/improvement_lenses.py`](scripts/okstra_ctl/improvement_lenses.py). Output section: `## 4.9 Improvement Candidates` (10-column table). Validator: [`validators/validate_improvement_report.py`](validators/validate_improvement_report.py).
 
 ### 3.5 Ops commands
 
@@ -199,6 +208,7 @@ Recent workflow additions (post-0.8.0, on `main`):
 | `npx -y okstra@latest check-project` | Verify the current project has been registered with `setup` |
 | `npx -y okstra@latest config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | Read / write okstra settings; initial key `pr-template-path` (writes `prTemplatePath` to project.json or `~/.okstra/config.json`) |
 | `npx -y okstra@latest render-views <final-report.md>` | Regenerate the slim-MD + HTML sibling views from a final-report MD (Phase 7 step 1.5; idempotent) |
+| `npx -y okstra@latest token-usage ...` | Collect/substitute token usage for a run; wraps the installed Python token usage CLI |
 | `npx -y okstra@latest uninstall` | Remove runtime + skills; preserves user data (`recent.jsonl`, `projects/`, …) |
 | `npx -y okstra@latest uninstall --purge -y` | Remove everything including user data |