okstra 0.19.1 → 0.20.0

package/README.kr.md

@@ -28,7 +28,7 @@ okstra/                          npm 패키지 = repo 루트
 ├── tools/build.mjs              runtime/ 동기화 스크립트 (prepack 에서 호출)
 ├── runtime/                     gitignored 빌드 산출물; ~/.okstra 로 배포되는 유일한 자산
 ├── scripts/                     python + bash 런타임 소스
-├── skills/                      Claude Code 스킬 마크다운 소스 (스킬 11종)
+├── skills/                      Claude Code 스킬 마크다운 소스 (스킬 12종)
 ├── agents/                      lead SKILL.md + workers/
 ├── prompts/, templates/, validators/
 ├── docs/kr/                     한국어 상세 매뉴얼 (architecture.md, cli.md)
@@ -56,7 +56,7 @@ okstra/                          npm 패키지 = repo 루트
 └── archive/                     완료된 run
 
 ~/.claude/skills/                Claude Code 가 자동 인식
-└── okstra-*/SKILL.md            스킬 11종 (§3.3 참조)
+└── okstra-*/SKILL.md            스킬 12종 (§3.3 참조)
 
 ~/.claude/agents/                Claude Code 가 자동 인식 (subagent 디스커버리 경로)
 └── {claude,codex,gemini,report-writer}-worker.md   worker subagent 정의
@@ -87,7 +87,7 @@ okstra/                          npm 패키지 = repo 루트
 npx -y okstra@latest install
 ```
 
-`~/.okstra/{lib/python, bin, version}`, `~/.claude/skills/` 아래 스킬 마크다운 11개, `~/.okstra/installed-skills.json` 을 생성합니다. 재실행은 idempotent — 파일별 hash 를 비교하고 바뀐 파일만 갱신합니다.
+`~/.okstra/{lib/python, bin, version}`, `~/.claude/skills/` 아래 스킬 마크다운 12개, `~/.okstra/installed-skills.json` 을 생성합니다. 재실행은 idempotent — 파일별 hash 를 비교하고 바뀐 파일만 갱신합니다.
 
 검증:
 
@@ -140,7 +140,7 @@ Claude Code 세션 안에서 사용하는 슬래시 커맨드:
 | `/okstra-schedule` | task-group 전체에 대한 작업 계획표 생성 |
 | `/okstra-setup` | 프로젝트별 부트스트랩 (§3.2) |
 
-이 외에 `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-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 명령을 제시하되 직접 실행하지는 않음)로 자동 호출합니다.
 
 ### 3.4 CLI 모드 (선택)
 

package/README.md

@@ -28,7 +28,7 @@ okstra/                          npm package = repo root
 ├── tools/build.mjs              runtime/ sync script (invoked by prepack)
 ├── runtime/                     gitignored build output; the only thing shipped to ~/.okstra
 ├── scripts/                     python + bash runtime sources
-├── skills/                      Claude Code skill markdown sources (11 skills)
+├── skills/                      Claude Code skill markdown sources (12 skills)
 ├── agents/                      lead SKILL.md + workers/
 ├── prompts/, templates/, validators/
 ├── tests/, tests-e2e/
@@ -55,7 +55,7 @@ okstra/                          npm package = repo root
 └── archive/                     completed runs
 
 ~/.claude/skills/                discovered automatically by Claude Code
-└── okstra-*/SKILL.md            11 skills total (see §3.3)
+└── okstra-*/SKILL.md            12 skills total (see §3.3)
 
 ~/.claude/agents/                discovered automatically by Claude Code
 └── {claude,codex,gemini,report-writer}-worker.md   subagent definitions
@@ -86,7 +86,7 @@ okstra/                          npm package = repo root
 npx -y okstra@latest install
 ```
 
-Provisions `~/.okstra/{lib/python, bin, version}`, the 11 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, version}`, the 12 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.
 
 Verify:
 
@@ -139,7 +139,7 @@ User-facing slash commands inside a Claude Code session:
 | `/okstra-schedule` | Generate a work schedule for an entire task-group |
 | `/okstra-setup` | Per-project bootstrap (§3.2) |
 
-Six additional 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 (e.g. "이 task 얼마나 걸렸어?" routes to `okstra-time-summary`; "show me the report for X" routes to `okstra-report-finder`).
+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).
 
 ### 3.4 CLI mode (optional)
 

package/docs/kr/architecture.md

@@ -149,7 +149,7 @@ okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_ta
 - [`agents/SKILL.md`](agents/SKILL.md) — main okstra skill (cross-verify 트리거).
 - [`skills/okstra-setup/SKILL.md`](skills/okstra-setup/SKILL.md) — **첫 실행 부트스트랩**. `okstra install` + `project.json` 생성.
 - [`skills/okstra-run/SKILL.md`](skills/okstra-run/SKILL.md) — **현재 claude 세션 안에서 okstra task 를 시작**하는 in-session 진입점. `prepare_task_bundle` 직접 호출.
-- `skills/okstra-{status,history,convergence,schedule,context-loader,team-contract,report-finder,report-writer,time-summary}/SKILL.md` — phase 진행·status·history 보조 skill.
+- `skills/okstra-{status,history,convergence,schedule,context-loader,team-contract,report-finder,report-writer,time-summary,logs}/SKILL.md` — phase 진행·status·history 보조 skill. `okstra-logs` 는 codex/gemini wrapper 가 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` 로 남기는 live-log sidecar 의 인벤토리·정리 안내 (read-only, find-delete cleanup 명령 제안만 함).
 - 플러그인 매니페스트: [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) — `npx skills@latest add Devonshin/okstra` 보조 채널이 참조. 0.3.0 부터는 `npx okstra install` 한 명령이 동일 결과를 보장하므로 일반 셋업에는 이 채널이 필요 없다.
 - 설치 위치: `~/.claude/skills/<name>/SKILL.md` (`okstra-install.sh` dev 설치, 또는 위 npx 채널).
 - 릴리스 절차: [`RELEASING.md`](RELEASING.md) — npm publish 흐름과 GitHub Actions 워크플로(`v*.*.*` tag → 자동 publish), 자동화 토큰 셋업, 검증/롤백.
@@ -828,10 +828,22 @@ Claude가 작성하는 최종 보고서는 brief에 더 구체적인 형식이
 - `source` 필드(`worker-reported` | `lead-observed`)와 `errorType`(`tool-failure` | `cli-failure` | `contract-violation`)으로 발생원과 종류를 구분합니다.
 - `stderrExcerpt`는 한 줄 jsonl 가독성을 위해 2KB 상한, `PIPE_BUF`(4096B) atomic append 가드를 강제합니다.
 - run-manifest 또는 team-state의 `errorsLogPath` 필드에 `logs/errors-<task-type>-<seq>.jsonl` 경로를 1회 기록해 발견 가능하게 합니다.
+- Path delivery 와이어링 (`f6f9f69`): `scripts/okstra_ctl/paths.py` 가 `RUN_ERRORS_LOG_FILE` / `RUN_ERRORS_LOG_RELATIVE_PATH` 와 worker 별 sidecar 경로를 export 하고, `scripts/okstra_ctl/render.py` 가 `{{RUN_ERRORS_LOG_PATH}}` / `{{<WORKER>_ERRORS_SIDECAR_PATH}}` 템플릿 토큰을 노출합니다. `prompts/launch.template.md` 의 `## Run Logs (error-log wiring)` 섹션이 resolved absolute path 를 lead 에 전달하고, lead 는 이를 worker dispatch prompt 의 `**Errors log path:**` / `**Errors sidecar path:**` 라인으로 forward 해야 합니다 — literal `<runDir>/logs/...` template fragment 만 들고 있을 때 worker 가 argparse-exit 으로 entry 를 흘리는 회귀가 있어 path delivery 가 정식 contract 화 됐습니다.
 - Helper CLI: `scripts/okstra-error-log.py`
   - 단일 진입점으로 record를 append 합니다.
   - 워커 sidecar dump(`append_observed`, schema version 가드)와 lead 관찰(`lead-observed`) 모두 동일 helper를 사용합니다.
 
+### Live-log mirror (codex / gemini wrapper)
+
+- `scripts/okstra-codex-exec.sh`, `scripts/okstra-gemini-exec.sh` 는 dispatch 마다 prompt path 옆에 `<prompt>.log` sidecar 를 만들고 stdout 을 거기로 mirror 합니다 (`tee`, `PIPESTATUS[0]` 로 종료코드 보존). stderr 은 같은 파일에 append (subagent stderr 캡처 contract 보존), 매 dispatch 시 truncate. 호출 subagent 의 `BashOutput` 폴링은 60s 간격이라 long-running run (analysis 의 large-codebase scan, implementation 의 cargo / pytest) 동안 사용자가 stalled state 를 탐지할 수 없는 문제를 해소합니다.
+- `$TMUX` 가 셋팅된 lead 환경이면 wrapper 가 sibling pane 을 자동 분할해 `tail -F <log-path>` 를 띄웁니다. pane title 은 `<cli>-<role>-trace` (e.g. `codex-executor-trace`, `gemini-worker-trace`); role 은 wrapper 의 5번째 optional positional 인자로 명시 가능하며, 누락 시 worktree-path 인자 유무에 따라 `executor` / `worker` 로 자동 결정. focus 는 caller pane 으로 복귀하고, CLI 종료 후 pane 은 유지돼 스크롤백 가능. `$TMUX` 미설정, split 실패, 구버전 tmux 등 모든 경로는 silent degrade.
+- 디스크 누적은 `okstra-logs` skill 이 read-only 로 인벤토리 + cleanup 명령을 제안합니다 (실행은 사용자 copy-paste).
+
+### Linked-worktree `.git/` write 권한 (codex / gemini)
+
+- `--executor codex|gemini` 의 worktree 안에서 `git add` / `git commit` 은 main repo 의 per-worktree metadata (`<main-repo>/.git/worktrees/<name>/index`, refs, HEAD) 와 shared object DB (`<main-repo>/.git/objects/`) 에 써야 하지만, 이 경로는 worktree directory 밖이라 단순히 worktree path 만 sandbox 에 열어주면 index.lock 생성 시 EPERM 으로 실패합니다 (executor 가 step commit contract 를 만족하지 못해 edit 을 revert 하고 종료).
+- wrapper 가 worktree 안에서 `git -C <worktree> rev-parse --git-common-dir` 로 main repo `.git/` 절대경로를 해석하고 `--add-dir <main-repo>/.git` (codex) 또는 `--include-directories <main-repo>/.git` append (gemini) 로 sandbox 에 함께 forward 합니다.
+
 상세 설계 및 jq 회고 레시피는 `docs/superpowers/specs/2026-04-28-worker-error-collection-design.md`를 참고합니다.
 
 ## Token usage and cost accounting

package/docs/kr/cli.md

@@ -481,3 +481,21 @@ chmod +x ~/.local/bin/okstra-ctl
 | 활성 run 재조정 | `okstra-ctl reconcile [--project <id|all>]` |
 | 배치 진행 | `okstra-ctl batch status <batch-id>` |
 
+### `okstra` Node CLI — introspection subcommands
+
+`okstra` Node CLI (`bin/okstra`) 가 skill / agent 에서 사용하는 read-only introspection subcommand 를 제공합니다. 모두 JSON 을 stdout 으로 emit 합니다. 별도 python heredoc 대신 단일 allowlisted command 로 호출 가능 — Claude Code 가 매 호출마다 permission prompt 를 띄우지 않습니다 (`Bash(okstra:*)` 가 runtime settings template 의 allow 룰에 포함).
+
+| 명령 | 용도 |
+|---|---|
+| `okstra task-list [--project-root <path>]` | `list_project_tasks` + `read_latest_task` 결과를 합쳐 task 카탈로그 + 최근 task 를 JSON 으로 반환 |
+| `okstra task-show <task-key> [--project-root <path>]` | task-manifest.json 의 workflow / phase / status 요약 |
+| `okstra worktree-lookup <task-key>` | `worktree_registry.lookup` 결과 (예약된 path / branch / base ref / 현재 상태) |
+| `okstra plan-validate <plan-path>` | `_validate_approved_plan` — approval marker 인식 결과와 sanitization 후 diff |
+| `okstra render-bundle <args…>` | `prepare_task_bundle(render_only=True)` 의 thin shim — `python3 -m okstra_ctl.run --render-only` 와 동일 시그니처 |
+
+> 모든 subcommand 는 `bin/okstra` 가 spawn 하는 python 헬퍼 (`src/_python-helper.mjs`) 가 `PYTHONPATH` 와 `~/.okstra/lib/python` 을 wire 합니다. 직접 `python3 -m okstra_ctl.*` 으로 호출하면 `PYTHONPATH` 를 사용자가 직접 셋업해야 합니다.
+
+### Live-log sidecar
+
+codex / gemini wrapper 는 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` sidecar 를 만들고 stdout / stderr 를 mirror 합니다. tmux 안에서 lead 를 띄우면 wrapper 가 자동으로 `tail -F` pane 을 분할합니다 (title: `<cli>-<role>-trace`). 사용량 인벤토리와 `find … -delete` cleanup 명령은 `okstra-logs` skill 이 read-only 로 제안합니다. 자세한 와이어링은 [`docs/kr/architecture.md`](architecture.md) 의 *Live-log mirror* 절 참고.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.19.1",
-  "builtAt": "2026-05-13T15:21:25.918Z",
+  "package": "0.20.0",
+  "builtAt": "2026-05-13T15:25:34.223Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }