okstra 0.98.0 → 0.98.2

package/docs/for-ai/README.md

@@ -0,0 +1,55 @@
+# Okstra Skills AI Manuals
+
+이 디렉터리는 AI가 okstra 공개 스킬을 빠르게 선택하고 정확히 실행하기 위한 압축 매뉴얼이다. 원문 계약은 `skills/*/SKILL.md`이고, 이 문서는 AI용 운영 가이드다. 원문 스킬, 템플릿, validator, CLI registry가 충돌하면 원문 스킬과 실제 validator/CLI 구현을 우선한다.
+
+## 확인한 원천
+
+- 공개 스킬 목록: [`src/lib/skill-catalog.mjs`](../../src/lib/skill-catalog.mjs)
+- 스킬 원문: [`skills/`](../../skills/)
+- CLI 명령 표면: [`src/cli-registry.mjs`](../../src/cli-registry.mjs)
+- brief 템플릿: [`templates/reports/brief.template.md`](../../templates/reports/brief.template.md)
+- schedule 템플릿: [`templates/reports/schedule.template.md`](../../templates/reports/schedule.template.md)
+- brief 검증기: [`validators/validate-brief.py`](../../validators/validate-brief.py)
+- schedule 검증기: [`validators/validate-schedule.py`](../../validators/validate-schedule.py)
+
+## 스킬 라우팅
+
+| 사용자 의도 | 사용할 스킬 | 매뉴얼 |
+|---|---|---|
+| 새 프로젝트나 새 머신에서 okstra 설치/초기화 | `okstra-setup` | [`skills/okstra-setup.md`](skills/okstra-setup.md) |
+| 요구사항, 티켓, 링크, 코드베이스 스캔, error-zip을 okstra 입력 brief로 변환 | `okstra-brief` | [`skills/okstra-brief.md`](skills/okstra-brief.md) |
+| 현재 Claude Code 세션에서 okstra run 시작 또는 다음 phase 실행 | `okstra-run` | [`skills/okstra-run.md`](skills/okstra-run.md) |
+| 상태, history, report, time, logs, cost, errors, error-zip, recap 확인 | `okstra-inspect` | [`skills/okstra-inspect.md`](skills/okstra-inspect.md) |
+| task-group 전체의 클라이언트용 작업 일정 생성 | `okstra-schedule` | [`skills/okstra-schedule.md`](skills/okstra-schedule.md) |
+| 대화/결정/선호/요구사항을 전역 Memory Book에 저장 또는 검색 | `okstra-memory` | [`skills/okstra-memory.md`](skills/okstra-memory.md) |
+| implementation task worktree 기반 docker compose 사용자 테스트 환경 관리 | `okstra-container` | [`skills/okstra-container.md`](skills/okstra-container.md) |
+
+## 공통 실행 규칙
+
+1. 명령은 스킬 원문이 요구하는 경우 각각 별도의 Bash 호출로 실행한다. 특히 `okstra ensure-installed`, `okstra check-project --json`, `okstra wizard ...`, `okstra container ...` 호출을 `&&`, `||`, `$(...)`, 선행 변수 할당, `eval`, `export`로 감싸지 않는다.
+2. `okstra <subcmd>` 호출은 자체적으로 Python path를 부트스트랩한다. 스킬에서 명시하지 않는 한 `okstra paths --shell`이나 `export PYTHONPATH=...`를 만들지 않는다.
+3. `okstra-setup`을 제외한 대부분의 스킬은 `npx` fallback을 쓰지 않는다. runtime이 없으면 사용자에게 `/okstra-setup`을 실행하라고 알리고 멈춘다.
+4. 프로젝트 산출물은 기본적으로 `<PROJECT_ROOT>/.okstra/` 아래에 둔다. 예외는 `okstra-memory`이며, 이 스킬은 전역 사용자 메모리 `~/.okstra/memory-book/`을 사용한다.
+5. `runtime/`은 build output이다. 스킬 원문이나 템플릿을 고칠 때는 `skills/`, `templates/`, `validators/`, `scripts/`, `src/`의 source를 수정하고 build로 반영한다.
+6. tracker, URL, 파일, report, log, zip, template, validator 내용을 추측하지 않는다. 도구로 읽거나 실행해서 확인한 내용만 사용한다.
+7. read-side 스킬도 일부 산출물을 만든다. `okstra-inspect errors`는 error report Markdown을 만들고, `okstra-inspect error-zip`은 anonymized zip을 만든다. 이런 경우에도 CLI stdout JSON을 source of truth로 둔다.
+
+## AI가 읽는 순서
+
+1. 이 파일에서 스킬을 고른다.
+2. 해당 `docs/for-ai/skills/<skill>.md`만 읽는다.
+3. 스킬이 실제 실행을 요구하면 원문 [`skills/<skill>/SKILL.md`](../../skills/)에서 해당 step을 확인한다.
+4. brief나 schedule을 쓰는 경우 템플릿과 validator도 함께 확인한다.
+
+## 공개 스킬 목록
+
+`src/lib/skill-catalog.mjs` 기준 공개 스킬은 다음 7개다.
+
+- `okstra-setup`
+- `okstra-brief`
+- `okstra-run`
+- `okstra-memory`
+- `okstra-inspect`
+- `okstra-schedule`
+- `okstra-container`
+

package/docs/for-ai/skills/okstra-brief.md

@@ -0,0 +1,240 @@
+# okstra-brief AI Manual
+
+## 원천
+
+- 스킬 원문: [`skills/okstra-brief/SKILL.md`](../../../skills/okstra-brief/SKILL.md)
+- brief 템플릿: [`templates/reports/brief.template.md`](../../../templates/reports/brief.template.md)
+- brief validator: [`validators/validate-brief.py`](../../../validators/validate-brief.py)
+- lens enum SSOT: [`scripts/okstra_ctl/improvement_lenses.py`](../../../scripts/okstra_ctl/improvement_lenses.py)
+
+## 목적
+
+`okstra-brief`는 okstra pipeline에 넣을 task brief를 만든다. brief는 pre-discovery 산출물이다. 요구사항을 구현 계획으로 바꾸는 문서가 아니라, reporter가 준 원문과 AI가 확인한 증거/해석을 라벨로 분리해 다음 phase가 질문 없이 출발하게 만드는 handoff 문서다.
+
+출력 위치:
+
+```text
+<PROJECT_ROOT>/.okstra/briefs/<task-group>/<brief-id>.md
+<PROJECT_ROOT>/.okstra/briefs/<task-group>/sub/.../<brief-id>.md
+```
+
+## 세 가지 variant
+
+| Variant | 입력 | Recommended next phase |
+|---|---|---|
+| Reporter input | 파일, 티켓, URL, 대화/자유 텍스트 | `requirements-discovery` 또는 `error-analysis` |
+| Codebase scan | scan scope, priority lenses, candidate cap, context | `improvement-discovery` |
+| Error feedback | `okstra error-zip`이 만든 zip의 단일 error cluster | `error-analysis` |
+
+## 핵심 불변식
+
+1. Source Material은 원문 보존 영역이다. paraphrase, 요약, 재정렬을 하지 않는다.
+2. AI의 해석, 파일 링크, 용어 매핑, format 변환은 모두 `Augmentation` 또는 `> augmented:` blockquote에 둔다.
+3. augmentation은 네 label 중 하나를 가진다: `evidence-link`, `format-conversion`, `terminology-mapping`, `intent-inference`.
+4. `intent-inference`는 `Open Questions`의 `intent-check:`와 짝을 이룬다. 이 관계는 `validators/validate-brief.py`가 검사한다.
+5. unresolved `terminology-mapping`은 `Open Questions`의 `terminology:`와 짝을 이룬다. 이 관계도 validator가 검사한다.
+6. reporter만 답할 수 있는 질문은 Step 6.5에서 모아 `## Reporter Confirmations`에 verbatim으로 기록한다.
+7. 모든 okstra-owned write는 `<PROJECT_ROOT>/.okstra/` 안에 둔다. 외부 파일은 reporter가 source로 명시한 경우에만 읽는다.
+
+## Preflight
+
+두 명령을 각각 별도 호출로 실행한다.
+
+```bash
+okstra ensure-installed --runtime claude-code
+okstra check-project --json
+```
+
+runtime이나 project setup이 없으면 `/okstra-setup`을 안내하고 멈춘다. 이 스킬에서 `npx` fallback을 쓰지 않는다.
+
+## 입력 수집
+
+### Reporter input
+
+소스 종류는 하나 이상 가능하지만 각 소스는 `Source Material`에 별도 block으로 저장한다.
+
+- File: 전체 파일을 읽고 그대로 넣는다.
+- Issue tracker ticket: Linear/Jira/GitHub/Notion을 감지하고 MCP 또는 `gh` CLI를 사용한다. 접근 도구가 없으면 사용자에게 body paste 또는 skip을 묻는다.
+- Link URL: fetch한다. 실패/로그인 wall/본문 truncation이면 사용자에게 paste를 요청한다.
+- User input: 대화 맥락이 충분하면 conversation synthesis, 부족하면 한 번만 free-text를 받는다.
+
+티켓에 child/sub-task가 있으면 parent에서 한 번만 tree 처리 방식을 묻는다.
+
+- Full tree: descendant별 brief 생성.
+- Parent only: child key/URL만 Related Artifacts에 둔다.
+- Selected: 선택한 direct child branch만 재귀 처리.
+
+재귀 시 visited set은 `<tracker>:<ticket-id>`로 관리하고, 재실행에서는 기존 brief frontmatter의 `ticket-id` + `source-type`으로 reseed한다.
+
+### Codebase scan
+
+수집값:
+
+- `scan_scope`: 프로젝트 내부 실제 경로 목록.
+- `priority_lenses`: `LENSES` enum 중 1-4개.
+- `out_of_scope`: 선택.
+- `candidate_cap`: 1-12, 기본 8.
+- context, desired outcome, constraints.
+
+경로 존재, lens enum subset, candidate cap 범위는 작성 전 확인한다. 최종 검증은 `validate-brief.py`가 `scope: codebase`, `Scan Scope`, `Priority Lenses`를 검사한다.
+
+### Error feedback
+
+입력은 `okstra error-zip --out <path>`가 만든 zip이다.
+
+처리:
+
+1. zip에 `report.md`, `errors/anonymized.jsonl`이 있는지 확인한다.
+2. 빈발 cluster 표에서 cluster 하나만 선택한다.
+3. 선택 cluster의 anonymized records만 Source Material에 옮긴다.
+4. 서로 다른 errorType을 한 brief에 섞지 않는다.
+5. 다음 단계 안내는 `error-analysis`로 둔다.
+
+## task-group과 파일명
+
+task-group은 기존 group 추천을 먼저 보여준다. `okstra task-list`를 호출해 `tasks[]`의 distinct `taskGroup`을 최신순으로 뽑고, 최근 2개 + 직접 입력을 제공한다. tracker recursion에서는 child path를 만들기 전에 task-group을 먼저 받아야 한다.
+
+파일 경로 규칙:
+
+```text
+depth 0: .okstra/briefs/<task-group>/<ticket-id>-<file-title>.md
+depth 1: .okstra/briefs/<task-group>/sub/<ticket-id>-<file-title>.md
+depth N: .okstra/briefs/<task-group>/<sub/ repeated N>/<ticket-id>-<file-title>.md
+```
+
+frontmatter의 `depth`는 path의 `sub/` 개수와 같아야 한다. validator가 검사한다.
+
+충돌 시 기본은 Skip이다. Append suffix 또는 Overwrite를 제공할 수 있다. tracker multi-generation에서 bulk overwrite를 조용히 수행하지 않는다.
+
+## Domain alignment
+
+먼저 okstra 내부 memory를 본다.
+
+- `<PROJECT_ROOT>/.okstra/glossary.md`
+- `<PROJECT_ROOT>/.okstra/decisions/`
+- 관련 task의 `history/fix-cycles.jsonl`
+
+외부 domain docs는 reporter가 source material로 명시했을 때만 읽는다. 충돌/모호 용어는 `Augmentation > Domain alignment`에 `terminology-mapping`으로 기록하고, `Open Questions`에 `terminology:` row를 둔다.
+
+파일 path나 symbol이 언급되면 `Read`/`Grep`으로 실제 in-repo reference를 찾고 `evidence-link`로 남긴다. 매핑할 수 없으면 추측하지 않고 `conversion-block:` row로 둔다.
+
+## Sharpening pass
+
+full interview를 하지 않는다. source와 codebase로 채울 수 없는 gap만 묻는다.
+
+기본 budget:
+
+- 원문 스킬이 채움 대상으로 지정한 section당 최대 1문항.
+- terminology/fuzzy disambiguation 최대 2문항.
+- 전체 최대 6문항.
+- codebase-scan은 최대 8문항.
+
+질문보다 codebase-first 확인을 우선한다. 남은 gap은 `_(none)_` 또는 `Open Questions`에 둔다.
+
+## template 작성 규칙
+
+템플릿은 `templates/reports/brief.template.md`가 SSOT다. section 순서, frontmatter key, top blockquote shape, HTML comment guidance를 따른다.
+
+Reporter input과 Error feedback:
+
+- `## Source Material` 유지.
+- `## Problem / Symptom` 유지.
+- `## Scan Scope`, `## Priority Lenses` 생략.
+
+Codebase scan:
+
+- frontmatter에 `scope: codebase`.
+- `## Source Material`, `## Problem / Symptom` 생략.
+- `## Scan Scope`, `## Priority Lenses` 유지.
+
+빈 섹션을 날조하지 않는다. 값이 없으면 `_(none)_`를 사용한다.
+
+## frontmatter key
+
+모든 brief는 다음 key를 가진다. key set은 `validate-brief.py`에서 검사한다.
+
+- `type`
+- `brief-id`
+- `parent-id`
+- `ticket-id`
+- `source-type`
+- `task-group`
+- `depth`
+- `created`
+- `generator`
+- `reporter-confirmations`
+
+`brief-id`는 filename stem과 같아야 한다. depth 0의 `parent-id`는 `self`, descendant의 `parent-id`는 direct parent의 `brief-id`다.
+
+## Recommended next phase
+
+brief 본문 top blockquote의 `Recommended next phase:`에 쓴다.
+
+- observable error, repro, stack trace, error-zip record: `error-analysis`
+- ambiguity나 Open Questions가 큰 요구사항: `requirements-discovery`
+- `scope: codebase`: `improvement-discovery`
+- 애매하면 `requirements-discovery`
+
+`okstra-run`을 자동으로 시작하지 않는다.
+
+## Reporter Confirmations
+
+`Open Questions`에서 reporter만 답할 수 있는 row를 모은다.
+
+- `intent-check:`
+- `conversion-block:`
+
+이미 `[CONFIRMED <date> → RC-N]` marker가 있으면 pending에서 제외한다. 사용자에게 지금 답할지 묻고, 답하면 `## Reporter Confirmations`에 verbatim으로 기록한다. row는 삭제하지 않고 marker를 붙인다.
+
+상태값:
+
+- `complete`: pending reporter-only row가 모두 답변됨.
+- `partial`: 일부만 답변됨.
+- `skipped`: 사용자가 downstream phase에 넘기기로 함.
+- `pending`: handoff 전 상태로 보고 진행하지 않는다.
+
+## 검증
+
+작성 후 handoff 메시지를 내기 전에 validator를 실행한다.
+
+설치본:
+
+```bash
+~/.okstra/lib/validators/validate-brief.sh "<PROJECT_ROOT>/.okstra/briefs" --briefs-root "<PROJECT_ROOT>/.okstra/briefs"
+```
+
+repo checkout:
+
+```bash
+validators/validate-brief.sh "<PROJECT_ROOT>/.okstra/briefs" --briefs-root "<PROJECT_ROOT>/.okstra/briefs"
+```
+
+실패하면 cited brief를 고치고 재실행한다. validator가 없을 때만 manual checklist로 대체한다.
+
+## 완료 메시지
+
+단일 brief:
+
+```text
+brief saved: <abs-path>
+next: /okstra-run  (recommended task-type: <phase>)
+```
+
+multi-brief:
+
+```text
+briefs saved (N):
+  - <abs>/<task-group>/<brief>.md (depth 0, parent, recommended: <phase>)
+  - <abs>/<task-group>/sub/<brief>.md (depth 1, child, recommended: <phase>)
+next: /okstra-run
+```
+
+## 금지 패턴
+
+- Source Material을 요약하거나 정리해서 넣기.
+- tracker/URL 내용을 도구 확인 없이 추측하기.
+- unlabelled augmentation 작성하기.
+- `intent-inference`를 `intent-check:` 없이 남기기.
+- 외부 docs/ADR에 decision file을 쓰기. okstra decision은 `<PROJECT_ROOT>/.okstra/decisions/`에만 해당한다.
+- child tree 전체를 silent overwrite하기.
+- brief 생성 직후 자동으로 `okstra-run` 시작하기.

package/docs/for-ai/skills/okstra-container.md

@@ -0,0 +1,161 @@
+# okstra-container AI Manual
+
+## 원천
+
+- 스킬 원문: [`skills/okstra-container/SKILL.md`](../../../skills/okstra-container/SKILL.md)
+- container CLI wrapper: [`src/commands/inspect/container.mjs`](../../../src/commands/inspect/container.mjs)
+- container runtime: [`scripts/okstra_ctl/container.py`](../../../scripts/okstra_ctl/container.py)
+- container registry: [`scripts/okstra_ctl/container_registry.py`](../../../scripts/okstra_ctl/container_registry.py)
+- stage integration gate: [`scripts/okstra_ctl/stage_targets.py`](../../../scripts/okstra_ctl/stage_targets.py)
+
+## 목적
+
+`okstra-container`는 implementation task worktree의 `docker-compose.yml`을 이용해 사용자 테스트용 container group을 관리한다. okstra는 compose group에 task/run trace label을 붙이고, tmux watcher pane으로 로그/상태를 관찰한다.
+
+## sub-command
+
+| Sub-command | 역할 | side effect |
+|---|---|---|
+| `up` | implementation stages를 task worktree에 통합하고 `docker compose up -d`, healthcheck poll, watcher pane attach | container 생성/시작, watcher pane 생성 |
+| `status` | label query 기반 running container와 watcher metadata 확인 | 읽기 |
+| `logs` | watcher findings dir와 watcher entries 안내 | 읽기 |
+| `stop-watcher` | watcher/tail tmux panes만 회수 | container 유지, pane 제거 |
+| `down` | label query로 container group 제거, orphan watcher panes 회수 | container 종료/제거 |
+
+## Preflight
+
+각각 별도 호출:
+
+```bash
+okstra ensure-installed --runtime claude-code
+okstra check-project --json
+```
+
+project setup이 없으면 `/okstra-setup` 안내 후 멈춘다. Docker daemon이 필요하다. Docker connection error가 나오면 Docker Desktop/daemon을 시작하라고 안내하고, 직접 Docker를 시작하지 않는다.
+
+## task-key 해석
+
+대부분 sub-command는 full task-key가 필요하다.
+
+1. full task-key가 있으면 그대로 사용.
+2. bare task-id는 resolver 사용:
+
+```bash
+okstra resolve-task-key <task-id> --project-root <projectRoot> --json
+```
+
+3. multiple match면 후보를 보여주고 선택 받는다.
+4. `down --all`만 task-key 없이 실행할 수 있다.
+
+## intent routing
+
+명확한 동사:
+
+- "띄워", "올려", "up": `up`
+- "상태", "status": `status`
+- "로그", "logs": `logs`
+- "watcher 멈춰", "stop-watcher": `stop-watcher`
+- "내려", "down", "종료": `down`
+
+애매하면 full facet list를 보여주고 직접 입력 option을 둔다. 여러 facet이 한 메시지에 있으면 Step 0은 한 번만 실행하고 sub-command를 순차 실행한다.
+
+## up
+
+실행:
+
+```bash
+okstra container up --project-root <projectRoot> --task-key <task-key>
+```
+
+전제:
+
+- task는 implementation worktree가 registry에 있어야 한다.
+- worktree root에 `docker-compose.yml`이 있어야 한다.
+- approved plan의 모든 stage가 `done`이어야 한다. partial stage 상태를 완성 task처럼 deploy하지 않는다.
+
+실패 메시지 처리:
+
+- registry에 task worktree가 없다는 메시지: implementation phase를 먼저 실행하라고 말한다.
+- compose file 없음: CLI 메시지를 그대로 보여준다.
+- `final-verification(whole-task): stage N not done`: 해당 stage를 implementation으로 끝내야 한다고 말한다.
+- healthcheck 실패: failing service와 CLI가 제공한 `docker compose ... logs` line을 그대로 전달한다.
+
+성공하면 stdout JSON을 파싱해 services, watcher pane, published ports를 요약한다. 이후 관리는 `okstra container status <task-key>`와 `down <task-key>`로 한다고 안내한다.
+
+## status
+
+실행:
+
+```bash
+okstra container status --project-root <projectRoot> --task-key <task-key>
+```
+
+stdout JSON:
+
+- `projectName`: compose project name
+- `containers`: run-trace label로 찾은 running containers
+- `watchers`: registry의 watcher metadata
+
+alive 여부는 `containers` label query가 authoritative다. watcher registry는 lag할 수 있다. `containers`가 비어 있으면 group이 실행 중이 아니라고 말하고 `up`을 제안한다.
+
+## logs
+
+실행:
+
+```bash
+okstra container logs --project-root <projectRoot> --task-key <task-key>
+```
+
+service scope:
+
+```bash
+okstra container logs --project-root <projectRoot> --task-key <task-key> --service <service>
+```
+
+stdout JSON의 `watchersDir`, `watchers`를 보여준다. live stream은 file이 아니라 tmux watcher pane에 있다. raw compose logs가 필요하면 `status`에서 `projectName`을 확인한 뒤 사용자가 `docker compose -p <projectName> logs -f <service>`를 실행할 수 있다고 안내한다.
+
+## stop-watcher
+
+실행:
+
+```bash
+okstra container stop-watcher --project-root <projectRoot> --task-key <task-key>
+```
+
+watcher/tail panes만 제거하고 containers는 유지한다. stdout JSON의 `reapedPanes`, `note`를 요약한다. 사용자가 containers까지 내리려는 의도면 `down`으로 라우팅한다.
+
+## down
+
+단일 task:
+
+```bash
+okstra container down --project-root <projectRoot> --task-key <task-key>
+```
+
+프로젝트 전체:
+
+```bash
+okstra container down --project-root <projectRoot> --all
+```
+
+단일 task down은 task-key 해석 후 실행해도 된다. `--all`은 프로젝트의 모든 okstra container group을 내리므로 실행 전 사용자 확인을 받는다.
+
+stdout JSON의 `downed`, `orphanPanesReaped`를 보고한다. 각 `projectName`과 회수된 panes를 표시한다.
+
+## 출력 규칙
+
+- stdout JSON이 source of truth다.
+- raw `docker` 명령으로 second-guess하지 않는다. CLI가 실패했고 사용자가 manual fallback을 요청한 경우만 예외다.
+- resolved task-key를 heading이나 첫 줄에 표시한다.
+- CLI failure message는 remediation line을 포함해 그대로 보여준다.
+- container/service state는 JSON 값을 normalize하지 않고 보여준다.
+
+## 금지 패턴
+
+- Docker daemon을 직접 시작하려고 하기.
+- `up` 실패 원인을 추측해서 compose를 수정하기.
+- partial stage task를 deploy 가능한 것으로 포장하기.
+- watcher registry만 보고 container alive라고 판단하기.
+- `down --all`을 사용자 확인 없이 실행하기.
+- raw docker query로 CLI 결과를 임의로 덮어쓰기.
+