okstra 0.20.1 → 0.21.1

package/docs/project-structure-overview.md

@@ -0,0 +1,388 @@
+# Okstra — 폴더 구조 및 기능 요약
+
+> 본 문서는 PRD 작성을 위한 선행 분석 자료다. Okstra 프로젝트 전체의 폴더 구조, 주요 스킬, Python/Node.js 클래스·함수의 용도를 한눈에 정리한다.
+
+---
+
+## 목차
+
+- [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-작성을-위한-다음-단계)
+
+---
+
+## 1. 프로젝트 정체성
+
+**Okstra** (v0.20.1)는 **Claude Code 기반 다중 에이전트 크로스 검증 오케스트레이터 런타임**이다.
+
+- **모델**: 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`가 명령별로 동적 로드한다.
+
+| 파일 | 용도 |
+|------|------|
+| `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()` 산출 미리보기 |
+| `uninstall.mjs` | `~/.okstra` 및 스킬 제거 |
+
+**핵심 설계**: 모든 CLI 명령은 `okstra paths --shell` 결과를 환경변수로 로드한 뒤, Python의 단일 진입점 `okstra_ctl.run.prepare_task_bundle`을 호출한다. CLI(`okstra.sh`)와 skill(`okstra-run`)이 같은 Python 함수를 공유하는 **Rule of Two**를 강제한다.
+
+---
+
+### 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` 데이터클래스 |
+
+#### 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 엔트리 |
+
+---
+
+### 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 산출물 템플릿
+
+- `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)
+
+---
+
+### 3.5 `validators/` — Workflow / Schedule 검증
+
+| 파일 | 용도 |
+|------|------|
+| `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.6 `agents/` — Lead 정의 & Worker 정의
+
+| 파일 | 역할 |
+|------|------|
+| `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) |
+
+---
+
+### 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 작업 수행 → 실패 시 사용자 안내**.
+
+---
+
+### 3.8 `bin/okstra` — Node.js CLI
+
+12개 명령(`paths`, `install`, `ensure-installed`, `uninstall`, `doctor`, `setup`, `check-project`, `task-list`, `task-show`, `worktree-lookup`, `plan-validate`, `render-bundle`) 라우터. 명령 파싱 → `src/<cmd>.mjs` 동적 로드 → `run(args)` 호출 → exit code 반환.
+
+---
+
+### 3.9 `tools/build.mjs` — 빌드 시스템
+
+`runtime/` 디렉토리를 `scripts/`, `skills/`, `agents/`, `prompts/`, `templates/`, `validators/`에서 동기화. `prepack` hook으로 npm publish 시 자동 실행.
+
+---
+
+### 3.10 `tests/`, `tests-e2e/` — 검증
+
+| 종류 | 파일 수 | 용도 |
+|------|--------|------|
+| pytest 단위 | 36개 | `okstra_ctl.*` 모듈 단위 검증 |
+| bash E2E | 4개 | record_start / rerun / lock / agent install |
+
+---
+
+### 3.11 `docs/` — 문서
+
+- `docs/kr/architecture.md` — 내부 아키텍처
+- `docs/kr/cli.md` — `okstra.sh` 인자 레퍼런스
+- `docs/superpowers/plans/`, `docs/superpowers/specs/` — 내부 설계
+
+---
+
+## 4. Python 주요 모듈 · 클래스 요약
+
+### 4.1 데이터 클래스 (`okstra_ctl.models`)
+
+- `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 메타
+
+### 4.2 주요 함수
+
+- `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 조합
+
+### 4.3 보조 영역
+
+- `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()`
+
+---
+
+## 5. Node.js 주요 모듈 요약
+
+모든 ES 모듈은 `(args) → Promise<number>` 시그니처. `bin/okstra`가 동적 import로 라우팅한다.
+
+| 카테고리 | 모듈 |
+|---------|------|
+| 설치 | `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` |
+
+---
+
+## 6. 런타임 저장소 구조 (설치 후)
+
+```
+~/.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개 슬래시 커맨드
+~/.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>/
+    ├── task-manifest.json
+    ├── run-context.json
+    ├── runs/<phase>/                phase별 입력·산출
+    ├── reports/final-report.md
+    └── sessions/                    Lead/Worker transcript
+```
+
+---
+
+## 7. 주요 워크플로우
+
+### 7.1 새 Task 시작 (`/okstra-run`)
+
+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
+
+`requirements-discovery → error-analysis → implementation-planning → implementation → final-verification → release-handoff`
+
+각 phase의 허용/금지 규칙은 `prompts/profiles/<task-type>.md` + `_common-contract.md`로 정의된다.
+
+### 7.3 Worker 검증 (Phase 4-5)
+
+- **Codex executor**: worktree 내 코드 편집 + commit
+- **Gemini verifier**: read-only 코드 리뷰 (선택)
+- **Claude verifier**: read-only 최종 검증
+- **Consensus**: Lead가 여러 verifier 판정을 종합 (`okstra-convergence`)
+
+### 7.4 최종 보고서 (Phase 6-7)
+
+- **Phase 6 release-handoff**: Commit / PR 초안, 사용자 선택
+- **Phase 7 report-writer**: 최종 보고서 작성 후 archive
+
+---
+
+## 8. PRD 작성을 위한 다음 단계
+
+본 문서는 다음 PRD 작성 단계에서 다음 항목의 입력 자료가 된다:
+
+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
+
+---
+
+*작성일: 2026-05-14 · 분석 대상: `claude/objective-einstein-250add` 브랜치 기준 okstra v0.20.1*