okstra 0.34.0 → 0.36.0

package/docs/project-structure-overview.md

@@ -1,444 +1,448 @@
 # Okstra — 폴더 구조 및 기능 요약
 
-> 본 문서는 PRD 작성을 위한 선행 분석 자료다. Okstra 프로젝트 전체의 폴더 구조, 주요 스킬, Python/Node.js 클래스·함수의 용도를 한눈에 정리한다.
+> 현재 저장소 기준의 living map입니다. 빠른 사용법은 [`README.kr.md`](../README.kr.md), 내부 실행 계약은 [`docs/kr/architecture.md`](kr/architecture.md), CLI 세부 옵션은 [`docs/kr/cli.md`](kr/cli.md)를 함께 보세요.
 
 ---
 
 ## 목차
 
 - [1. 프로젝트 정체성](#1-프로젝트-정체성)
-- [2. 최상위 폴더 트리 (depth 2-3)](#2-최상위-폴더-트리-depth-2-3)
-- [3. 폴더별 역할 및 주요 파일](#3-폴더별-역할-및-주요-파일)
-  - [3.1 `src/` — Node.js CLI 진입점 & 설치/진단](#31-src--nodejs-cli-진입점--설치진단)
-  - [3.2 `scripts/` — Python + Bash 런타임 소스](#32-scripts--python--bash-런타임-소스)
-    - [3.2.1 `okstra_ctl/` — 오케스트레이션 핵심](#321-scriptsokstra_ctl--오케스트레이션-핵심-python-약-30-모듈)
-    - [3.2.2 `okstra_project/` — 프로젝트 메타 리졸버](#322-scriptsokstra_project--프로젝트-메타-리졸버)
-    - [3.2.3 `okstra_token_usage/` — 토큰 & 비용 추적](#323-scriptsokstra_token_usage--토큰--비용-추적)
-    - [3.2.4 `lib/okstra/` — Bash 헬퍼](#324-scriptslibokstra--bash-헬퍼)
-    - [3.2.5 `lib/okstra-ctl/` — Bash CLI 라우팅](#325-scriptslibokstra-ctl--bash-cli-라우팅)
-    - [3.2.6 기타 최상위 스크립트](#326-기타-최상위-스크립트)
-  - [3.3 `prompts/` — Phase별 프롬프트 템플릿](#33-prompts--phase별-프롬프트-템플릿)
-  - [3.4 `templates/` — Render 산출물 템플릿](#34-templates--render-산출물-템플릿)
-  - [3.5 `validators/` — Workflow / Schedule 검증](#35-validators--workflow--schedule-검증)
-  - [3.6 `agents/` — Lead 정의 & Worker 정의](#36-agents--lead-정의--worker-정의)
-  - [3.7 `skills/` — 12개 Claude Code 슬래시 커맨드](#37-skills--12개-claude-code-슬래시-커맨드)
-  - [3.8 `bin/okstra` — Node.js CLI](#38-binokstra--nodejs-cli)
-  - [3.9 `tools/build.mjs` — 빌드 시스템](#39-toolsbuildmjs--빌드-시스템)
-  - [3.10 `tests/`, `tests-e2e/` — 검증](#310-tests-tests-e2e--검증)
-  - [3.11 `docs/` — 문서](#311-docs--문서)
-- [4. Python 주요 모듈 · 클래스 요약](#4-python-주요-모듈--클래스-요약)
-- [5. Node.js 주요 모듈 요약](#5-nodejs-주요-모듈-요약)
-- [6. 런타임 저장소 구조 (설치 후)](#6-런타임-저장소-구조-설치-후)
-- [7. 주요 워크플로우](#7-주요-워크플로우)
-  - [7.1 새 Task 시작 (`/okstra-run`)](#71-새-task-시작-okstra-run)
-  - [7.2 Phase Routing](#72-phase-routing)
-  - [7.3 Worker 검증 (Phase 4-5)](#73-worker-검증-phase-4-5)
-  - [7.4 최종 보고서 (Phase 6-7)](#74-최종-보고서-phase-6-7)
-- [8. PRD 작성을 위한 다음 단계](#8-prd-작성을-위한-다음-단계)
+- [2. 최상위 구조](#2-최상위-구조)
+- [3. Build / install 경계](#3-build--install-경계)
+- [4. 폴더별 역할](#4-폴더별-역할)
+- [5. 주요 런타임 모듈](#5-주요-런타임-모듈)
+- [6. 설치 후 저장소 구조](#6-설치-후-저장소-구조)
+- [7. 핵심 워크플로우](#7-핵심-워크플로우)
+- [8. 문서 유지보수 체크리스트](#8-문서-유지보수-체크리스트)
+- [부록 A. Report / row ID 용어](#부록-a-report--row-id-용어)
 
 ---
 
 ## 1. 프로젝트 정체성
 
-**Okstra** (v0.20.1)는 **Claude Code 기반 다중 에이전트 크로스 검증 오케스트레이터 런타임**이다.
+`okstra`는 npm package `okstra`로 배포되는 Claude Code용 multi-agent cross-verification runtime입니다. 단발성 reviewer가 아니라 stable task key를 중심으로 lead + worker 모델을 여러 lifecycle phase에 걸쳐 운영합니다.
 
-- **모델**: Lead(사용자) + Worker(Claude / Codex / Gemini) 분업 구조
-- **핵심 원칙**:
-  1. 단일 진입점 — `prepare_task_bundle()` (CLI / Skill 양쪽이 동일 함수 호출)
-  2. 지속적 작업 정체성 — `<project-id>/<task-group>/<task-id>` 키가 모든 phase·session·모델 업그레이드 동안 불변
-  3. 의무적 Lead/Worker 계약 — phase별 허용/금지 산출·행동 규칙
-- **배포 형태**: npm 패키지 `okstra` → 설치 시 `~/.okstra` 런타임 + `~/.claude/skills/` 내 12개 슬래시 커맨드 + 4종 worker 에이전트 자동 등록
-- **Phase 흐름**: requirements-discovery → error-analysis → implementation-planning → implementation → final-verification → release-handoff
+현재 기준:
 
----
-
-## 2. 최상위 폴더 트리 (depth 2-3)
-
-```
-okstra/
-├── bin/okstra                       Node.js CLI 진입점 (12 sub-command 라우터)
-├── src/                             설치·진단·경로 해석 (Node.js ES 모듈)
-├── scripts/                         Python + Bash 런타임 소스
-│   ├── okstra.sh                    주 CLI 래퍼
-│   ├── okstra_ctl/                  순수 오케스트레이션 로직 (Python)
-│   ├── okstra_project/              프로젝트 메타 리졸버
-│   ├── okstra_token_usage/          토큰 / 비용 계산기
-│   ├── lib/okstra/                  bash 헬퍼 라이브러리
-│   └── lib/okstra-ctl/              bash 서브커맨드 라우팅
-├── prompts/                         Phase별 프롬프트 + 6개 task-type 프로필
-├── templates/                       Render 산출물 템플릿 (reports, prd, project-docs)
-├── validators/                      Workflow / Schedule / Run 검증 스크립트
-├── agents/                          Lead SKILL.md + 4종 worker 정의
-├── skills/                          12개 Claude Code 슬래시 커맨드 (markdown)
-├── runtime/                         build 산출물 (gitignored, install 대상)
-├── tools/build.mjs                  runtime/ 동기화 빌드 스크립트
-├── tests/                           pytest 단위 테스트 36개
-├── tests-e2e/                       bash E2E 시나리오 4개
-├── docs/                            한글 아키텍처 + 설계 문서
-├── package.json                     npm 메타 (v0.20.1)
-├── README.md / README.kr.md         영문 / 한글 사용 설명서
-└── CHANGELOG.md / CHANGES.md        변경 이력
-```
-
----
-
-## 3. 폴더별 역할 및 주요 파일
-
-### 3.1 `src/` — Node.js CLI 진입점 & 설치/진단
-
-각 모듈은 `run(args: string[]) → Promise<number>` 시그니처를 따른다. `bin/okstra`가 명령별로 동적 로드한다.
+- package version: `0.34.1`
+- Node CLI entrypoint: `bin/okstra`
+- Python orchestration authority: `scripts/okstra_ctl/run.py::prepare_task_bundle`
+- lifecycle: `requirements-discovery → error-analysis → implementation-planning → implementation → final-verification → release-handoff`
+- installed skills: 13개
+- worker agents: `claude`, `codex`, `gemini`, `report-writer`
+- final report SSOT: `schemas/final-report-v1.0.schema.json` + `*.data.json`
 
-| 파일 | 용도 |
-|------|------|
-| `version.mjs` | 패키지 버전 조회 |
-| `install.mjs` | `~/.okstra` 자동 프로비저닝, 스킬 MD 등록 |
-| `doctor.mjs` | 런타임 상태 진단 (설치, Python import, 권한) |
-| `paths.mjs` | 런타임 경로 JSON/Shell 출력 (`OKSTRA_*` 환경 변수) |
-| `setup.mjs` | 프로젝트별 `.project-docs/okstra/project.json` 생성 |
-| `check-project.mjs` | 현재 디렉토리가 okstra 프로젝트인지 검증 |
-| `task-list.mjs` | 프로젝트 내 task 목록 JSON 반환 |
-| `task-show.mjs` | 특정 task의 manifest + workflow phase 상태 |
-| `worktree-lookup.mjs` | 작업별 git worktree 경로 조회 |
-| `plan-validate.mjs` | Approved plan 파일의 approval marker 검증 |
-| `render-bundle.mjs` | `prepare_task_bundle()` 산출 미리보기 |
-| `wizard.mjs` | okstra-run 인터랙티브 입력 상태머신 구동 (`init`/`step`/`render-args`/`confirmation`) |
-| `uninstall.mjs` | `~/.okstra` 및 스킬 제거 |
+설계 원칙:
 
-**핵심 설계**: 모든 CLI 명령은 `okstra paths --shell` 결과를 환경변수로 로드한 뒤, Python의 단일 진입점 `okstra_ctl.run.prepare_task_bundle`을 호출한다. CLI(`okstra.sh`)와 skill(`okstra-run`)이 같은 Python 함수를 공유하는 **Rule of Two**를 강제한다.
+1. **Single prepare authority**: slash skill, Bash CLI, Node preview 모두 `prepare_task_bundle()`로 수렴합니다.
+2. **Stable task identity**: `<project-id>/<task-group>/<task-id>`가 phase, run, worktree, report를 관통합니다.
+3. **Artifact-home rule**: okstra-owned project artifact root는 `<PROJECT_ROOT>/.project-docs/okstra/**` 하나입니다.
+4. **Template/schema/validator lockstep**: `templates/`, `schemas/`, `validators/`, worker/report-writer 계약이 같은 report shape를 강제합니다.
 
 ---
 
-### 3.2 `scripts/` — Python + Bash 런타임 소스
-
-#### 3.2.1 `scripts/okstra_ctl/` — 오케스트레이션 핵심 (Python, 약 30 모듈)
-
-| 모듈 | 주요 클래스 / 함수 |
-|------|-------------------|
-| `run.py` | `prepare_task_bundle(PrepareInputs) → PrepareOutputs` — 단일 권위 진입점 |
-| `render.py` | `_render_*()` — 9개 산출물 (manifest, settings, discovery, brief, input, prompt, team-state, workflow, brief-input) |
-| `workflow.py` | Phase sequence + 허용/금지 산출·행동 규칙 |
-| `paths.py` | `compute_run_paths()` — Run 디렉토리 트리 계산 |
-| `ids.py` | Run ID 조합/파싱, task segment slugify |
-| `index.py` | `~/.okstra/recent.jsonl`, `active.jsonl` 기록 |
-| `reconcile.py` | Active run 상태 수집 / 정규화 (타임아웃 처리) |
-| `listing.py` | Task/run 테이블 포맷팅 |
-| `resolver.py` | Run ID → file path 해석 |
-| `worktree.py` | Git worktree 자동 프로비저닝 및 레지스트리 |
-| `workers.py` | Worker 모델 할당 (Claude/Codex/Gemini) |
-| `backfill.py` | 레거시 run 자동 마이그레이션 |
-| `models.py` | `ModelAssignment`, `PrepareInputs`, `PrepareOutputs` 데이터클래스 |
-| `wizard.py` | `WizardState`, `Prompt`, `STEPS` — okstra-run 입력 수집 상태머신 (단일 권위) |
-
-#### 3.2.2 `scripts/okstra_project/` — 프로젝트 메타 리졸버
-
-| 모듈 | 역할 |
-|------|------|
-| `resolver.py` | CWD에서 프로젝트 루트 및 `project.json` 찾기 |
-| `state.py` | Project metadata 읽기 / 쓰기 |
-
-#### 3.2.3 `scripts/okstra_token_usage/` — 토큰 & 비용 추적
-
-| 모듈 | 역할 |
-|------|------|
-| `collect.py` | Claude/Codex/Gemini 세션 집계 |
-| `pricing.py` | 모델별 가격 계산 (USD) |
-| `report.py` | 최종 보고서에 토큰 블록 삽입 |
-| `claude.py`, `codex.py`, `gemini.py` | 각 모델 세션 조회 어댑터 |
-
-#### 3.2.4 `scripts/lib/okstra/` — Bash 헬퍼
-
-| 파일 | 용도 |
-|------|------|
-| `globals.sh` | 환경 변수, 경로, 기본값 |
-| `cli.sh` | `--task-type`, `--executor`, `--approve`, `--base-ref` 파싱 |
-| `interactive.sh` | 사용자 입력 수집 (project root, task, model) |
-| `project-resolver.sh` | CWD 기반 프로젝트 루트 찾기 (Bash 버전) |
-| `usage.sh` | `okstra.sh --help` 텍스트 |
-
-#### 3.2.5 `scripts/lib/okstra-ctl/` — Bash CLI 라우팅
-
-`cmd-batch.sh`, `cmd-list.sh`, `cmd-rerun.sh`, `cmd-tail.sh`, `cmd-show.sh`, `cmd-open.sh`, `cmd-reconcile.sh`, `cmd-projects.sh`, `cmd-reindex.sh` 등 12개 서브커맨드.
-
-#### 3.2.6 기타 최상위 스크립트
-
-| 파일 | 용도 |
-|------|------|
-| `okstra.sh` | 주 CLI 진입점 |
-| `okstra-central.sh` | `record_start` 중앙 lock 관리 |
-| `okstra-codex-exec.sh` | Codex worker executor (live log mirror, tmux trace pane) |
-| `okstra-gemini-exec.sh` | Gemini worker executor |
-| `okstra-trace-cleanup.sh` | Claude `/exit` 시 trace pane registry 청소 (`SessionEnd` 훅에서 호출) |
-| `okstra-error-log.py` | Worker 오류 패턴 분석 |
-| `okstra-spawn-followups.py` | Phase 완료 후 다음 phase dispatch |
-| `okstra-token-usage.py` | Token collection CLI 엔트리 |
+## 2. 최상위 구조
 
----
-
-### 3.3 `prompts/` — Phase별 프롬프트 템플릿
-
-| 파일 | 용도 |
-|------|------|
-| `launch.template.md` | Lead 시작 프롬프트 (task brief, worker 할당, 규칙 로드) |
-| `profiles/_common-contract.md` | 모든 phase 공통 Lead/Worker 계약 |
-| `profiles/requirements-discovery.md` | Phase 1: 작업 분류 & 라우팅 |
-| `profiles/error-analysis.md` | Phase 2: 증상 재현 & 근본 원인 |
-| `profiles/implementation-planning.md` | Phase 3: 옵션 검토 & 승인 대기 |
-| `profiles/implementation.md` | Phase 4: 코드 편집 & Worker 검증 |
-| `profiles/final-verification.md` | Phase 5: 최종 verdict |
-| `profiles/release-handoff.md` | Phase 6: Commit/PR/Deploy |
-
----
-
-### 3.4 `templates/` — Render 산출물 템플릿
+```text
+okstra/
+├── bin/okstra                       Node CLI router
+├── src/                             Node command modules
+├── scripts/                         Python + Bash runtime sources
+│   ├── okstra_ctl/                  orchestration core
+│   ├── okstra_project/              project root / project.json resolver
+│   ├── okstra_token_usage/          token usage + cost accounting
+│   ├── okstra_vendor/               vendored Jinja2 / MarkupSafe
+│   ├── lib/okstra/                  Bash helpers for okstra.sh
+│   └── lib/okstra-ctl/              Bash control-center subcommands
+├── skills/                          Claude Code skills (13)
+├── agents/                          lead SKILL.md + worker agent specs
+├── prompts/                         launch template, phase profiles, wizard prompt JSON
+├── schemas/                         JSON schema for final-report data.json
+├── templates/                       report, setup, PR, project-doc templates/assets
+├── validators/                      run / brief / schedule / view validators
+├── tools/build.mjs                  source → runtime sync
+├── runtime/                         generated install payload; do not edit directly
+├── tests/                           pytest unit suite
+├── tests-e2e/                       Bash end-to-end scenarios
+├── docs/                            architecture, CLI, plans/specs
+├── package.json                     npm metadata and published file list
+├── README.md / README.kr.md         user manuals
+├── CHANGES.md / CHANGELOG.md        human-authored and generated changelogs
+└── RELEASING.md                     release process
+```
 
-- `templates/reports/` — task-brief, quick-input, implementation-planning-input, implementation-input, error-analysis-input, final-verification-input, release-handoff-input, final-report, schedule, settings.template.json
-- `templates/prd/` — PRD 스타일 brief
-- `templates/project-docs/` — Project-level task 카탈로그(task-index)
+`runtime/` is build output. Source edits go to `scripts/`, `skills/`, `agents/`, `prompts/`, `schemas/`, `templates/`, `validators/`; then `npm run build` syncs them into `runtime/`.
 
 ---
 
-### 3.5 `validators/` — Workflow / Schedule 검증
+## 3. Build / install 경계
 
-| 파일 | 용도 |
-|------|------|
-| `validate-run.py` | Single run 검증 (manifest 스키마, 산출물 존재, phase 규칙) |
-| `validate-schedule.py` | Task Group schedule 가능성 (의존성, 시간 추정) |
-| `validate-workflow.sh` | Phase rule 적용 (forbidden actions 감지) |
-| `lib/validate-*.sh` | 공용 검증 함수 (assets, prompt metadata, tasks) |
+### 3.1 npm package
 
----
+`package.json` publishes:
 
-### 3.6 `agents/` — Lead 정의 & Worker 정의
+- `bin/`
+- `src/`
+- `runtime/`
+- `docs/`
+- `README.md`
+- `README.kr.md`
 
-| 파일 | 역할 |
-|------|------|
-| `SKILL.md` (28KB) | **okstra-lead** 에이전트 정의 (Phase 라우팅, Worker roster 검증) |
-| `workers/claude-worker.md` | Claude read-only analyzer (phase 2-5 기본) |
-| `workers/codex-worker.md` | Codex executor (implementation phase) |
-| `workers/gemini-worker.md` | Gemini verifier (선택) |
-| `workers/report-writer-worker.md` | Final report 작성 (phase 6) |
+So `runtime/` is not the only npm-published content. It is the install payload copied into `~/.okstra`.
 
----
+### 3.2 Build sync
 
-### 3.7 `skills/` — 13개 Claude Code 슬래시 커맨드
-
-| ID | 이름 | 공개 | 용도 |
-|----|------|------|------|
-| 1 | okstra-run | YES | 새 task 시작 또는 다음 phase 진행 |
-| 2 | okstra-status | YES | 현재 phase / blocker / workStatus 조회·갱신 |
-| 3 | okstra-history | YES | 과거 실행 목록 + 재실행 |
-| 4 | okstra-schedule | YES | Task Group 작업 일정 생성 |
-| 5 | okstra-setup | YES | 프로젝트 첫 등록 (`project.json` 생성) |
-| 6 | okstra-context-loader | NO | Task bundle 경로 / manifest 로드 (자동) |
-| 7 | okstra-team-contract | NO | Lead/Worker 규칙 검증 (자동) |
-| 8 | okstra-convergence | NO | Phase 5.5 consensus 수집 |
-| 9 | okstra-report-writer | NO | Phase 6-7 최종 보고서 작성 |
-| 10 | okstra-report-finder | NO | 보고서 검색 (자동 트리거) |
-| 11 | okstra-time-summary | NO | 소요 시간 분석 |
-| 12 | okstra-logs | YES | 로그 인벤토리·정리 (worker wrapper `*.log` sidecars 조회 및 cleanup 제안) |
-| 13 | okstra-brief | YES | 요구사항 문서·티켓·링크·대화로부터 `okstra-run` 입력용 task brief 마크다운 생성 |
-
-각 skill 구조: **Step 0 런타임 검증 → Step 1-N 작업 수행 → 실패 시 사용자 안내**.
+`tools/build.mjs` rebuilds `runtime/` from:
 
----
+| Source | Runtime destination |
+|---|---|
+| `scripts/okstra_project` | `runtime/python/okstra_project` |
+| `scripts/okstra_ctl` | `runtime/python/okstra_ctl` |
+| `scripts/okstra_token_usage` | `runtime/python/okstra_token_usage` |
+| `scripts/okstra_vendor` | `runtime/python/okstra_vendor` |
+| `scripts/lib` | `runtime/python/lib` |
+| selected `scripts/okstra*.sh` / `*.py` entrypoints | `runtime/bin/` |
+| `agents`, `prompts`, `schemas`, `templates`, `validators`, `skills` | same relative tree under `runtime/` |
 
-### 3.8 `bin/okstra` — Node.js CLI
+`npm run build` and `prepack` both run this sync. Never hand-edit `runtime/`.
 
-13개 명령(`paths`, `install`, `ensure-installed`, `uninstall`, `doctor`, `setup`, `check-project`, `task-list`, `task-show`, `worktree-lookup`, `plan-validate`, `render-bundle`, `wizard`) 라우터. 명령 파싱 → `src/<cmd>.mjs` 동적 로드 → `run(args)` 호출 → exit code 반환.
+### 3.3 Install output
 
----
+`okstra install` copies or symlinks:
 
-### 3.9 `tools/build.mjs` — 빌드 시스템
+- `runtime/python/*` → `~/.okstra/lib/python/`
+- `runtime/bin/*` → `~/.okstra/bin/`
+- `runtime/templates/*` → `~/.okstra/templates/`
+- `runtime/skills/<name>` → `~/.claude/skills/<name>`
+- `runtime/agents/workers/*.md` → `~/.claude/agents/*-worker.md`
+- install manifests → `~/.okstra/installed-skills.json`, `~/.okstra/installed-agents.json`
+- version stamp → `~/.okstra/version`
 
-`runtime/` 디렉토리를 `scripts/`, `skills/`, `agents/`, `prompts/`, `templates/`, `validators/`에서 동기화. `prepack` hook으로 npm publish 시 자동 실행.
+`--link <repo>` mode is for development and symlinks installed files back to repo sources.
 
 ---
 
-### 3.10 `tests/`, `tests-e2e/` — 검증
-
-| 종류 | 파일 수 | 용도 |
-|------|--------|------|
-| pytest 단위 | 36개 | `okstra_ctl.*` 모듈 단위 검증 |
-| bash E2E | 4개 | record_start / rerun / lock / agent install |
+## 4. 폴더별 역할
+
+### 4.1 `bin/` and `src/` — Node CLI
+
+`bin/okstra` is a thin dynamic-import router. Every command module exports `run(args) -> Promise<number>` or a named install/uninstall runner.
+
+| Command | Module | Role |
+|---|---|---|
+| `paths` | `src/paths.mjs` | Resolve package/runtime/home paths |
+| `install`, `ensure-installed` | `src/install.mjs` | Install or refresh runtime, skills, agents, templates |
+| `uninstall` | `src/uninstall.mjs` | Remove managed runtime/skills/agents, optionally purge data |
+| `doctor` | `src/doctor.mjs` | Diagnose runtime and Python imports |
+| `setup` | `src/setup.mjs` | Create/update `<PROJECT_ROOT>/.project-docs/okstra/project.json` |
+| `check-project` | `src/check-project.mjs` | Verify project registration |
+| `config` | `src/config.mjs` | Read/write project/global settings such as PR template path |
+| `task-list`, `task-show` | `src/task-list.mjs`, `src/task-show.mjs` | Task/run introspection for skills |
+| `worktree-lookup` | `src/worktree-lookup.mjs` | Look up a task-key's registered worktree |
+| `plan-validate` | `src/plan-validate.mjs` | Check approved-plan approval marker |
+| `render-bundle` | `src/render-bundle.mjs` | Preview `prepare_task_bundle(render_only=True)` |
+| `render-views` | `src/render-views.mjs` | Generate slim MD + self-contained HTML report views |
+| `wizard` | `src/wizard.mjs` | Drive the `okstra-run` interactive state machine |
+| `token-usage` | `src/token-usage.mjs` | Wrap installed Python token usage CLI |
+
+`src/_python-helper.mjs` centralizes Node → Python execution so command modules do not duplicate subprocess wiring.
+
+### 4.2 `scripts/` — Runtime source
+
+Top-level scripts:
+
+| File | Role |
+|---|---|
+| `okstra.sh` | Bash CLI wrapper around `prepare_task_bundle`, optionally launches `claude` |
+| `okstra-ctl.sh` | Bash control center for list/show/open/rerun/reconcile/project commands |
+| `okstra-central.sh` | Central run index writer / reconciler entrypoint |
+| `okstra-codex-exec.sh`, `okstra-gemini-exec.sh` | Worker CLI wrappers with log/status sidecars |
+| `okstra-wrapper-status.py` | Heartbeat sidecar writer used by worker wrappers |
+| `okstra-token-usage.py` | Token usage CLI entrypoint |
+| `okstra-render-final-report.py` | Render final-report Markdown from data.json |
+| `okstra-render-report-views.py` | Render slim MD + HTML views from final-report Markdown |
+| `okstra-error-log.py` | Normalize worker/lead error sidecars |
+| `okstra-spawn-followups.py` | Follow-up spawning helper |
+| `okstra-trace-cleanup.sh` | tmux trace pane cleanup |
+
+### 4.3 `scripts/okstra_ctl/` — Python orchestration core
+
+Important modules:
+
+| Module | Role |
+|---|---|
+| `run.py` | `prepare_task_bundle()` single authority and CLI parser |
+| `run_context.py` | Per-task mutex, run context and run-input persistence; `consumers_mutex` helper for atomic `consumers.jsonl` writes |
+| `consumers.py` | Append-only `consumers.jsonl` writer + reader — records which `implementation` runs consumed which `implementation-planning` stage |
+| `paths.py` | Path/sequence computation for task/run artifacts |
+| `render.py` | task manifest, run manifest, timeline, task index, discovery, team-state, prompt/template render |
+| `workflow.py` | Phase sequence, allowed outputs, forbidden actions, next phase |
+| `workers.py`, `models.py` | Worker roster and model metadata resolution |
+| `worktree.py`, `worktree_registry.py` | One worktree per task-key, branch registry, sync dirs/files/snapshots |
+| `project_meta.py`, `resolver.py`, `path_resolve.py` | Project/task/run resolution |
+| `clarification_items.py` | Unified §5 clarification table parser and approval blockers |
+| `qa_commands.py` | QA command deny-list validation for plans |
+| `pr_template.py` | PR body template resolution for release-handoff |
+| `report_views.py`, `render_final_report.py`, `final_report_schema.py` | Final-report data.json → Markdown → slim/HTML pipeline |
+| `wizard.py` | `okstra-run` prompt state machine; user-facing Korean strings live in `prompts/wizard/prompts.ko.json` |
+| `index.py`, `jsonl.py`, `reconcile.py`, `listing.py`, `batch.py`, `backfill.py` | `~/.okstra` run index and history operations |
+| `session.py`, `tmux.py`, `seeding.py`, `locks.py`, `invocation.py`, `sequence.py`, `ids.py`, `material.py` | Supporting lifecycle helpers |
+| `improvement_lenses.py` | improvement-discovery phase 의 lens enum SSOT + cap 상수 (DEFAULT 8, ABSOLUTE 12, MIN/MAX PRIORITY 1/4, SOURCE_WORKERS) |
+
+### 4.4 `scripts/okstra_project/`
+
+Project resolver and read-only state helpers:
+
+- `resolver.py`: locate project root and upsert `project.json`
+- `state.py`: read project metadata, task catalog, task manifest
+
+### 4.5 `scripts/okstra_token_usage/`
+
+Token/cost accounting:
+
+- provider adapters: `claude.py`, `codex.py`, `gemini.py`
+- aggregation: `collect.py`, `blocks.py`, `jsonl_io.py`, `paths.py`
+- pricing: `pricing.py`
+- report substitution: `report.py`
+- CLI: `cli.py` via `scripts/okstra-token-usage.py` and `okstra token-usage`
+
+### 4.6 `prompts/`
+
+| Path | Role |
+|---|---|
+| `launch.template.md` | Lead prompt template rendered for each run |
+| `profiles/_common-contract.md` | Shared phase contract |
+| `profiles/<task-type>.md` | English phase profiles |
+| `profiles/kr/<task-type>.md` | Korean phase profile mirrors |
+| `wizard/prompts.ko.json` | Korean wizard prompt single source of truth |
+
+### 4.7 `templates/`
+
+| Path | Role |
+|---|---|
+| `templates/reports/final-report.template.md` | Jinja2 final-report Markdown template |
+| `templates/reports/report.css`, `report.js` | Inline assets for self-contained HTML report view |
+| `templates/reports/*.template.md` | Inputs, schedule, user-response, settings templates |
+| `templates/prd/brief.template.md` | Brief template |
+| `templates/project-docs/task-index.template.md` | Project task index template |
+| `templates/okstra.CLAUDE.md` | Per-project okstra guidance import target |
+
+### 4.8 `schemas/`
+
+`schemas/final-report-v1.0.schema.json` is the final-report data.json contract. The report-writer worker writes `final-report-<task-type>-<seq>.data.json`; the renderer produces Markdown from that JSON.
+
+### 4.9 `validators/`
+
+| File | Role |
+|---|---|
+| `validate-run.py` | Run/final-report contract validation |
+| `validate-brief.py`, `validate-brief.sh` | Brief frontmatter/body contract validation |
+| `validate-report-views.py` | Slim/HTML view validation |
+| `validate-schedule.py` | Schedule section/order/code validation |
+| `validate-implementation-plan-stages.py` | Stage Map 구조 강제 — S1–S8 규칙 검사 (`## 4.5 Stage Map` + `## 4.5.<i> Stage <i>` 섹션, stage 당 step ≤ 6 등) |
+| `validate_improvement_report.py` | improvement-discovery final-report 의 11항목 contract 강제. `validate-run.py` 가 `task_type == "improvement-discovery"` 일 때 자동 호출 |
+| `validate-workflow.sh` | End-to-end fixture workflow validation |
+| `lib/*.sh` | Shared shell validator helpers and fixtures |
+
+### 4.10 `skills/`
+
+13 installed skills:
+
+| Skill | User-invocable | Role |
+|---|---:|---|
+| `okstra-brief` | yes | Produce task brief from ticket/doc/link/conversation |
+| `okstra-run` | yes | Start/resume okstra task in current Claude Code session |
+| `okstra-status` | yes | Inspect/update task lifecycle state |
+| `okstra-history` | yes | List previous runs and choose resume points |
+| `okstra-schedule` | yes | Generate task-group schedule |
+| `okstra-setup` | yes | Install/check runtime and register project |
+| `okstra-logs` | yes | Inspect wrapper log sidecars; suggest cleanup commands |
+| `okstra-context-loader` | no | Load task bundle paths/manifests for phase start |
+| `okstra-team-contract` | no | Worker roster/model/rule contract |
+| `okstra-convergence` | no | Cross-worker convergence and plan-body verification |
+| `okstra-report-writer` | no | Final report data.json authoring flow |
+| `okstra-report-finder` | no | Locate/read previous reports |
+| `okstra-time-summary` | no | Duration/time breakdown |
+
+### 4.11 `agents/`
+
+| File | Role |
+|---|---|
+| `agents/SKILL.md` | Lead operating contract |
+| `agents/workers/claude-worker.md` | Claude analyzer/verifier/executor spec |
+| `agents/workers/codex-worker.md` | Codex analyzer/verifier/executor wrapper spec |
+| `agents/workers/gemini-worker.md` | Gemini analyzer/verifier/executor wrapper spec |
+| `agents/workers/report-writer-worker.md` | data.json SSOT author and audit sidecar writer |
+
+### 4.12 `tests/` and `tests-e2e/`
+
+- `tests/`: 61 pytest modules covering project resolver, run preparation, worktrees, final-report rendering, validators, wizard, token usage, config, wrapper status, etc.
+- `tests-e2e/`: 5 shell scenarios covering record-start/reconcile, rerun, task lock, agent install, and report view rendering.
 
 ---
 
-### 3.11 `docs/` — 문서
+## 5. 주요 런타임 모듈
 
-- `docs/kr/architecture.md` — 내부 아키텍처
-- `docs/kr/cli.md` — `okstra.sh` 인자 레퍼런스
-- `docs/superpowers/plans/`, `docs/superpowers/specs/` — 내부 설계
+### 5.1 Prepare flow
 
----
+`prepare_task_bundle()` coordinates:
 
-## 4. Python 주요 모듈 · 클래스 요약
+1. Resolve project root and verify/upsert `project.json`.
+2. Resolve profile, required workers, model assignments, executor provider.
+3. Compute task/run paths and persist run context under `runs/<task-type>/manifests/`.
+4. Provision or reuse the task-key worktree.
+5. Materialize `instruction-set/` files and lead prompt snapshot.
+6. Persist run inputs, team state, task manifest, task index, run manifest, timeline, discovery pointers.
+7. Record the run in `~/.okstra/{active,recent}.jsonl` and project index.
 
-### 4.1 데이터 클래스 (`okstra_ctl.models`)
+### 5.2 Worktree model
 
-- `PrepareInputs` — Task 입력 (task-type, brief path, projectId, models, base-ref, executor 등)
-- `PrepareOutputs` — 산출물 경로 + 메타 (run_id, run_dir, manifest_path 등)
-- `ModelAssignment` — Worker 모델 할당 (claude_worker_model / codex_executor_model / gemini_worker_model)
-- `WorktreeEntry`, `WorktreeProvision` — Git worktree 메타
+One task-key owns one worktree:
 
-### 4.2 주요 함수
+```text
+~/.okstra/worktrees/<project-id>/<task-group>/<task-id>/
+```
 
-- `prepare_task_bundle(inp)` — 단일 권위 진입점
-- `compute_run_paths(ctx)` — Run 디렉토리 구조 계산
-- `render_*()` — 9개 산출물 렌더
-- `workflow_state(task_type, current_phase)` — 다음 phase 추천
-- `reconcile_active(run_id)` — Active run 상태 수집
-- `list_runs(project_root, since, filter)` — 과거 runs 조회
-- `build_run_id(project_id, task_group, task_id, seq)` — Run ID 조합
+Branch name:
 
-### 4.3 보조 영역
+```text
+<work-category-prefix>-<task-id-segment>
+```
 
-- `okstra_project`: `resolve_project_root(cwd)`, `load_project_meta()`, `upsert_project_meta()`
-- `okstra_token_usage`: `collect()`, `claude_cost_usd()`, `codex_cost_usd()`, `gemini_cost_usd()`, `substitute_final_report()`
+The same worktree/branch is reused across all phases. `worktreeSyncDirs`, `worktreeSyncFiles`, and `worktreeSnapshotFiles` provide filesystem continuity only; they do not expand okstra's context/write boundary.
 
----
+### 5.3 Final report model
 
-## 5. Node.js 주요 모듈 요약
+Current report pipeline:
 
-모든 ES 모듈은 `(args) → Promise<number>` 시그니처. `bin/okstra`가 동적 import로 라우팅한다.
+1. Analysis workers write worker result files.
+2. Convergence writes `state/convergence-<task-type>-<seq>.json` when applicable.
+3. Report-writer worker writes `reports/final-report-<task-type>-<seq>.data.json`.
+4. `scripts/okstra-render-final-report.py` renders Markdown.
+5. Token usage substitution fills usage/cost cells.
+6. `scripts/okstra-render-report-views.py` emits `.slim.md` and `.html`.
 
-| 카테고리 | 모듈 |
-|---------|------|
-| 설치 | `install.mjs`, `uninstall.mjs` |
-| 진단 | `doctor.mjs`, `paths.mjs`, `version.mjs` |
-| 프로젝트 | `setup.mjs`, `check-project.mjs` |
-| Task 조회 | `task-list.mjs`, `task-show.mjs` |
-| 실행 보조 | `worktree-lookup.mjs`, `plan-validate.mjs`, `render-bundle.mjs` |
-| 스킬 구동 | `wizard.mjs` |
+The Markdown is derived, not the authoring source. The schema is the contract.
 
 ---
 
-## 6. 런타임 저장소 구조 (설치 후)
+## 6. 설치 후 저장소 구조
 
-```
+```text
 ~/.okstra/
 ├── version
-├── lib/python/{okstra_ctl, okstra_project, okstra_token_usage, lib/}
-├── bin/{okstra.sh, okstra-codex-exec.sh, okstra-gemini-exec.sh, *.py}
-├── recent.jsonl                     모든 runs 기록 (최신순)
-├── active.jsonl                     진행 중인 runs
-├── worktrees/registry.json          worktree 레지스트리
-├── projects/                        프로젝트별 메타 미러
-└── archive/                         완료된 runs
-
-~/.claude/skills/okstra-*/SKILL.md   12개 슬래시 커맨드
+├── lib/python/{okstra_ctl,okstra_project,okstra_token_usage,okstra_vendor,lib/}
+├── bin/{okstra.sh,okstra-codex-exec.sh,okstra-gemini-exec.sh,...}
+├── templates/
+├── installed-skills.json
+├── installed-agents.json
+├── active.jsonl
+├── recent.jsonl
+├── projects/<project-id>/{meta.json,index.jsonl}
+├── worktrees/{registry.json,registry.lock,<project>/<group>/<task>/}
+├── archive/
+└── .locks/
+
+~/.claude/skills/okstra-*/SKILL.md
 ~/.claude/agents/{claude,codex,gemini,report-writer}-worker.md
 
 <PROJECT_ROOT>/.project-docs/okstra/
-├── project.json                     {projectId, projectRoot, ...}
-├── discovery/{task-catalog.json, latest-task.json}
-└── tasks/<task-group>/<task-id>/<seq>/
+├── project.json
+├── CLAUDE.md
+├── glossary.md
+├── decisions/<NNNN>-<slug>.md
+├── discovery/{task-catalog.json,latest-task.json}
+└── tasks/<task-group>/<task-id>/
     ├── task-manifest.json
-    ├── run-context.json
-    ├── runs/<phase>/                phase별 입력·산출
-    ├── reports/final-report.md
-    └── sessions/                    Lead/Worker transcript
+    ├── task-index.md
+    ├── history/timeline.json
+    └── runs/<task-type>/
+        ├── instruction-set/
+        ├── manifests/
+        ├── state/
+        ├── prompts/
+        ├── reports/
+        ├── status/
+        ├── sessions/
+        ├── worker-results/
+        ├── user-responses/
+        ├── carry/                    # implementation 전용: stage-<N>.json evidence sidecar
+        ├── logs/
+        └── (consumers.jsonl)         # implementation-planning 전용: impl-run 역링크 누적 파일
 ```
 
----
-
-## 7. 주요 워크플로우
-
-### 7.1 새 Task 시작 (`/okstra-run`)
+Project-local `<PROJECT_ROOT>/.claude/settings.local.json`, `<PROJECT_ROOT>/.project-docs/okstra/CLAUDE.md`, and `<PROJECT_ROOT>/AGENTS.md` are provisioned as symlink/import helpers so spawned agents can load okstra permissions and guidance.
 
-1. **Step 0** — `okstra ensure-installed`, `okstra paths --shell`
-2. **Step 1** — `okstra check-project --json`로 프로젝트 검증
-3. **Step 2** — 기존 vs 신규 task 선택
-4. **Step 3** — 입력 수집 (task-type, brief, model, executor, base-ref)
-5. **Step 4** — `prepare_task_bundle(PrepareInputs)` 호출
-   - Task key 생성 / 검증
-   - Git worktree 자동 프로비저닝 (첫 phase)
-   - 9개 산출물 렌더
-   - `~/.okstra/recent.jsonl` 기록
-6. **Step 5** — Lead 프롬프트 로드 후 `exec claude`
+---
 
-### 7.2 Phase Routing
+## 7. 핵심 워크플로우
 
-`requirements-discovery → error-analysis → implementation-planning → implementation → final-verification → release-handoff`
+### 7.1 First setup
 
-각 phase의 허용/금지 규칙은 `prompts/profiles/<task-type>.md` + `_common-contract.md`로 정의된다.
+1. `okstra install`
+2. `okstra doctor`
+3. inside target repo: `okstra setup --project-id <id>` or `/okstra-setup`
 
-### 7.3 Worker 검증 (Phase 4-5)
+### 7.2 Brief creation
 
-- **Codex executor**: worktree 내 코드 편집 + commit
-- **Gemini verifier**: read-only 코드 리뷰 (선택)
-- **Claude verifier**: read-only 최종 검증
-- **Consensus**: Lead가 여러 verifier 판정을 종합 (`okstra-convergence`)
+`/okstra-brief` turns source material into a validated task brief. It preserves source material verbatim, labels okstra augmentation, and records reporter confirmations.
 
-### 7.4 최종 보고서 (Phase 6-7)
+### 7.3 Task run
 
-- **Phase 6 release-handoff**: Commit / PR 초안, 사용자 선택
-- **Phase 7 report-writer**: 최종 보고서 작성 후 archive
+`/okstra-run` or `~/.okstra/bin/okstra.sh` collects task inputs and calls `prepare_task_bundle()`. The lead then works from the rendered instruction-set.
 
----
+### 7.4 Phase flow
 
-## 8. PRD 작성을 위한 다음 단계
+| Phase | Purpose | Typical next step |
+|---|---|---|
+| `requirements-discovery` | Classify and route work | `error-analysis` or `implementation-planning` |
+| `error-analysis` | Reproduce and explain failure | `implementation-planning` |
+| `implementation-planning` | Compare options, produce approval-ready plan; 산출은 항상 `## 4.5 Stage Map` + N 개의 `## 4.5.<i> Stage <i>` 섹션 구조. `implementation` 은 stage 단위로 분할 실행 가능 | `implementation` after approval |
+| `implementation` | Executor changes code, verifiers check independently | `final-verification` |
+| `final-verification` | Read-only acceptance verification | `release-handoff` if accepted |
+| `release-handoff` | User-selected commit/PR handoff | done or follow-up |
 
-본 문서는 다음 PRD 작성 단계에서 다음 항목의 입력 자료가 된다:
+### 7.5 Report and follow-up
 
-1. **제품 정의**: §1 정체성 → PRD의 Problem / Solution
-2. **사용자 흐름**: §7 워크플로우 → User Journey
-3. **기능 명세**: §3.7 Skills 12종, §3.6 Worker 4종, §4.2 주요 함수 → Feature list
-4. **시스템 경계**: §6 런타임 저장소 → System Architecture
-5. **검증 기준**: §3.5 validators, §3.10 tests → Acceptance Criteria
+Final report artifacts live under `runs/<task-type>/reports/`. Human responses from the HTML view are saved as `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md` and can be carried into the next run.
 
 ---
 
-## 부록 A. 보고서 row ID prefix 용어집
-
-okstra 가 산출하는 final-report 와 worker-result 의 표·리스트는 섹션별 두-글자 prefix 로 행을 식별합니다. 같은 prefix 는 어느 task / phase / project 에서도 의미가 동일하므로, 한 run 의 `C-005` 를 후속 run 이나 follow-up task 에서 그대로 인용해 cross-reference 할 수 있습니다.
-
-### A.1 Final-report 행 ID
-
-| Prefix | 의미 | 정의 위치 (template / contract) |
-|--------|------|----------------------------------|
-| `P-NNN` | Problem / Verification Target — 본 run 이 해결하려는 문제·검증 대상 한 줄 요약 | `## Summary of the Problem or Verification Target` |
-| `C-NNN` | Consensus — 모든 worker 가 합의한 결론 | `### 1.1 Consensus` |
-| `D-NNN` | Differences — worker 간 의미 있는 불일치 | `### 1.2 Differences` |
-| `E-NNN` | Primary Evidence — 본 verdict 의 1차 근거 | `### 3.1 Primary Evidence` |
-| `S-NNN` | Secondary Evidence / Alternate Interpretations — 보조 근거·대안 해석 | `### 3.2 Secondary Evidence or Alternate Interpretations` |
-| `R-NNN` | Missing Information / Risks — 누락 정보·인지된 위험 | `## 4. Missing Information and Risks` |
-| `RR-NNN` | Residual Risk — verdict 를 막진 않지만 추적해야 하는 잔여 위험 | `### 4.2 Residual Risk` |
-| `OF-NNN` | Option File-structure rows — implementation-planning 의 옵션별 파일 책임 | `### 4.5.1 Option Candidates` |
-| `DM-NNN` | Dependency / Migration risk — 순서·백필·feature-flag 선행 조건 | `### 4.5.5 Dependency / Migration Risk` |
-| `RB-NNN` | Rollback step — revert 경로·트리거 신호 | `### 4.5.7 Rollback Strategy` |
-| `OQ-NNN` | Open Question — pre-planning 에서 발견된 모호점 | `### 4.5.9 Open Questions` |
-| `FU-NNN` | Follow-up Task — 본 run 범위 밖이지만 후속 처리해야 하는 항목 | `## 7. Follow-up Tasks` |
-| `FU-VNN` | Verifier-harness Follow-up — verifier 환경 결함을 잡는 후속 (okstra 본체 fix) | `## 7.` (lead synthesis, `Origin = manual` 표기) |
-| `A1, A2, …` | Additional materials requested — 다음 run 시작 전 사용자가 채워야 할 자료 요청. **run 사이에 ID 유지**, 답변 완료 시 `Status` 만 갱신 | `### 5.1 추가 자료 요청` |
-| `Q1, Q2, …` | Questions for the user — 동일 규칙으로 run 간 ID 유지 | `### 5.2 사용자 확인 질문` |
+## 8. 문서 유지보수 체크리스트
 
-### A.2 Worker-result 행 ID (worker 가 자기 output 안에서 매기는 ID)
+When changing code, keep these docs in sync:
 
-`okstra-team-contract` 가 정의하는 worker output 6개 섹션 중 1, 2 섹션이 prefix 를 갖습니다.
+- New Node command: update `bin/okstra` usage, `README*`, this file, and `docs/kr/cli.md`.
+- New runtime source copied to users: update `tools/build.mjs`, install/uninstall manifests if applicable, and this file.
+- New skill/agent: update `README*`, this file, install/uninstall fallback lists, and `CHANGES.md`.
+- New report field/section: update schema, template, report-writer worker, validator tests, this file's report model if user-visible.
+- New phase/profile behavior: update `prompts/profiles/*`, `docs/kr/architecture.md`, `docs/kr/cli.md`, and `README*` if user-facing.
 
-| Prefix | 의미 | Worker output 섹션 |
-|--------|------|-------------------|
-| `F-NNN` | Finding — worker 의 핵심 발견 | §1 Findings |
-| `M-NNN` | Missing Information / Assumption — worker 가 인지한 누락 정보·가정 | §2 Missing Information or Assumptions |
-
-§3 Safe Areas, §4 Uncertain Points, §5 Recommended Next Actions, §6 Specialization Lens 는 표 형태가 아니라 별도 prefix 가 없습니다.
-
-### A.3 Phase / 입력 도메인 약어
-
-| 약어 | 의미 |
-|------|------|
-| `AC` | Acceptance Criteria — `final-verification-input.template.md` 의 `## Acceptance Criteria` 섹션에 사용자가 적어두는 합격 기준 (예: `AC1`, `AC2`, … `AC10`). Verifier 는 한 AC 당 한 줄로 `covered` / `not covered` 판정 |
-| `OQ` | Open Question — implementation-planning 의 `### 4.5.9` 행 ID. final-report 의 다른 섹션에서 `OQ-A`, `OQ-D` 처럼 알파벳 인덱스로도 인용됨 |
-| `FU-V` | Follow-up — Verifier harness 카테고리. `okstra-codex-exec.sh`, worktree provisioner 등 okstra 본체의 verifier 환경 결함을 잡는 후속 task |
-
-### A.4 Ticket / Verdict 토큰
+---
 
-| 토큰 | 위치 | 허용 값 |
-|------|------|---------|
-| `Verdict Token` | `## 2. Final Verdict` | `accepted`, `conditional-accept`, `blocked`, `not-applicable` (final-verification 만 의미 있음, release-handoff 가 진입 gate 로 사용) |
-| `Direction` | `## 2. Final Verdict` | `continue-investigation`, `begin-implementation`, `approve`, `reject`, `hold` |
-| `Ticket ID` | 모든 행 표에 컬럼으로 등장 | brief 의 `Issue / Ticket` 값 → 비어 있으면 `Task ID` → 둘 다 없으면 `unknown` |
+## 부록 A. Report / row ID 용어
+
+| Prefix / token | Meaning |
+|---|---|
+| `P-NNN` | Problem / verification target summary |
+| `C-NNN` | Consensus or clarification item, depending on section context |
+| `D-NNN` | Difference between workers |
+| `E-NNN` | Primary evidence |
+| `S-NNN` | Secondary evidence or alternate interpretation |
+| `R-NNN` | Missing information / risk |
+| `RR-NNN` | Residual risk |
+| `P-Opt-*` | Plan option item used by plan-body verification |
+| `P-Step-*` | Plan execution step item |
+| `P-Dep-*` | Plan dependency / migration item |
+| `P-Val-*` | Plan validation checklist item |
+| `P-Rb-*` | Plan rollback item |
+| `FU-NNN` | Follow-up task |
+| `worker:item` | Source item pointer preserved from worker result into final report |
+| `Verdict Token` | `accepted`, `conditional-accept`, `blocked`, `not-applicable` |
+| `Direction` | `continue-investigation`, `begin-implementation`, `approve`, `reject`, `hold` |
+
+Clarifications now live in the unified `## 5. Clarification Items` table. Deprecated `5.1` / `5.2` split sections are no longer part of the schema.
 
 ---
 
-*작성일: 2026-05-14 · 분석 대상: `claude/objective-einstein-250add` 브랜치 기준 okstra v0.20.1*
+*Updated: 2026-05-20 · Source of truth checked against `package.json`, `bin/okstra`, `tools/build.mjs`, `scripts/`, `skills/`, `agents/`, `templates/`, `schemas/`, `validators/`, and tests.*