okstra 0.21.0 → 0.21.1

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 스킬 마크다운 소스 (스킬 12종)
+├── skills/                      Claude Code 스킬 마크다운 소스 (스킬 13종)
 ├── agents/                      lead SKILL.md + workers/
 ├── prompts/, templates/, validators/
 ├── docs/kr/                     한국어 상세 매뉴얼 (architecture.md, cli.md)
@@ -87,7 +87,7 @@ okstra/                          npm 패키지 = repo 루트
 npx -y okstra@latest install
 ```
 
-`~/.okstra/{lib/python, bin, version}`, `~/.claude/skills/` 아래 스킬 마크다운 12개, `~/.okstra/installed-skills.json` 을 생성합니다. 재실행은 idempotent — 파일별 hash 를 비교하고 바뀐 파일만 갱신합니다.
+`~/.okstra/{lib/python, bin, version}`, `~/.claude/skills/` 아래 스킬 마크다운 13개, `~/.okstra/installed-skills.json` 을 생성합니다. 재실행은 idempotent — 파일별 hash 를 비교하고 바뀐 파일만 갱신합니다.
 
 검증:
 

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 (12 skills)
+├── skills/                      Claude Code skill markdown sources (13 skills)
 ├── agents/                      lead SKILL.md + workers/
 ├── prompts/, templates/, validators/
 ├── tests/, tests-e2e/
@@ -86,7 +86,7 @@ okstra/                          npm package = repo root
 npx -y okstra@latest install
 ```
 
-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.
+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.
 
 Verify:
 

package/docs/kr/architecture.md

@@ -837,6 +837,7 @@ Claude가 작성하는 최종 보고서는 brief에 더 구체적인 형식이
 
 - `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-worker-trace`, `gemini-worker-trace`); role 은 wrapper 의 5번째 optional positional 인자이며, 누락 시 기본값 `worker` 로 떨어집니다. caller 가 다른 라벨(예: `executor`)을 원하면 5번째 인자로 명시해야 합니다. focus 는 caller pane 으로 복귀하고, CLI 종료 후 pane 은 유지돼 스크롤백 가능. `$TMUX` 미설정, split 실패, 구버전 tmux 등 모든 경로는 silent degrade.
+- **Claude `/exit` 시 자동 정리**: trace pane 의 `tail -F` 는 tmux 셸의 자식이라 Claude 가 종료돼도 살아남는 문제를 막기 위해, wrapper 는 spawn 한 pane id 를 caller `$TMUX_PANE` 으로 키된 registry (`${TMPDIR:-/tmp}/okstra-trace-panes/<caller-pane>.list`) 에 append 합니다. `templates/reports/settings.template.json` 의 `hooks.SessionEnd` 가 `$HOME/.okstra/bin/okstra-trace-cleanup.sh` 를 호출해 자신의 caller pane registry 만 읽어 `tmux kill-pane` 합니다. caller pane 단위로 scope 가 잡혀 있어 같은 tmux 세션에 Claude 인스턴스가 여러 개 떠 있어도 서로의 trace pane 을 죽이지 않습니다. tmux 가 없거나 stale pane id 인 경우 silent degrade.
 - 디스크 누적은 `okstra-logs` skill 이 read-only 로 인벤토리 + cleanup 명령을 제안합니다 (실행은 사용자 copy-paste).
 
 ### Linked-worktree `.git/` write 권한 (codex / gemini)

package/docs/kr/cli.md

@@ -497,5 +497,5 @@ chmod +x ~/.local/bin/okstra-ctl
 
 ### 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* 절 참고.
+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`). 분할된 trace pane 은 caller `$TMUX_PANE` 으로 키된 registry 에 등록돼, Claude `/exit` 시 `SessionEnd` 훅이 `okstra-trace-cleanup.sh` 로 자동 정리합니다. 사용량 인벤토리와 `find … -delete` cleanup 명령은 `okstra-logs` skill 이 read-only 로 제안합니다. 자세한 와이어링은 [`docs/kr/architecture.md`](architecture.md) 의 *Live-log mirror* 절 참고.
 

package/docs/project-structure-overview.md

@@ -165,6 +165,7 @@ okstra/
 | `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 엔트리 |
@@ -217,7 +218,7 @@ okstra/
 
 ---
 
-### 3.7 `skills/` — 12개 Claude Code 슬래시 커맨드
+### 3.7 `skills/` — 13개 Claude Code 슬래시 커맨드
 
 | ID | 이름 | 공개 | 용도 |
 |----|------|------|------|
@@ -233,6 +234,7 @@ okstra/
 | 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 작업 수행 → 실패 시 사용자 안내**.
 

package/package.json

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

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.21.0",
-  "builtAt": "2026-05-14T11:48:06.992Z",
+  "package": "0.21.1",
+  "builtAt": "2026-05-14T12:50:20.728Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/claude-worker.md

@@ -44,7 +44,9 @@ Unlike the Codex / Gemini workers, you are an in-process Claude subagent — you
    - If the parent directory does not exist yet, create it before writing.
 
 4. Anchor all file operations to the absolute `Project Root` from the lead prompt. Use absolute paths — do NOT rely on inherited cwd. Never use `cd` to change directory.
-   - **Executor exception (implementation phase only):** when this worker is dispatched as the `Executor` and the lead prompt provides an `EXECUTOR_WORKTREE_PATH` that differs from the session's inherited cwd, cwd-sensitive Bash commands (`cargo *`, `npm *`, `pnpm *`, `bun *`, `pytest`, `make *`, `go *`, language-toolchain test/build commands) MUST be prefixed with `cd <EXECUTOR_WORKTREE_PATH> && ` in the same Bash invocation — e.g. `cd /Users/.../worktrees/foo && cargo test -p bar`. Do NOT wrap the whole thing in `bash -lc "..."` or `bash -c "..."`; pass the chained command directly to the Bash tool so the leading `cd` token remains visible to the permission layer. The `cd` is scoped to the single Bash subshell and does not mutate the session's shell state, so this does not conflict with the "never use cd" rule above (which prevents the worker from drifting the session cwd across calls). Verifier roles do NOT use this exception — they read with absolute paths only.
+   - **Executor exception (implementation phase only):** when this worker is dispatched as the `Executor` and the lead prompt provides an `EXECUTOR_WORKTREE_PATH` that differs from the session's inherited cwd, cwd-sensitive Bash commands (`cargo *`, `npm *`, `pnpm *`, `bun *`, `pytest`, `make *`, `go *`, language-toolchain test/build commands) MUST be prefixed with `cd <EXECUTOR_WORKTREE_PATH> && ` in the same Bash invocation — e.g. `cd /Users/.../worktrees/foo && cargo test -p bar`. Do NOT wrap the whole thing in `bash -lc "..."` or `bash -c "..."`; pass the chained command directly to the Bash tool so the leading `cd` token remains visible to the permission layer. The `cd` is scoped to the single Bash subshell and does not mutate the session's shell state, so this does not conflict with the "never use cd" rule above (which prevents the worker from drifting the session cwd across calls).
+   - **Verifier QA-gate exception:** verifier roles MAY use the same `cd <WORKTREE> && <cmd>` shape when executing project-declared `qaCommands` (lint / format / typecheck / test) from `project.json`, since those commands are cwd-sensitive by nature. Outside the QA gate, verifiers still read with absolute paths only — do NOT use `cd` for file inspection.
+   - **No extra chaining beyond `cd && cmd`:** the permission matcher only allows the exact two-segment shape `cd <PATH> && <single-command>`. Do NOT append additional pipes, semicolons, redirects, or `&&` chains — e.g. `cd ... && cargo test ... 2>&1 | tail -20; echo "exit:$?"` will trigger a permission prompt every dispatch because the trailing `| tail`, `; echo`, and `2>&1` tokens disqualify the prefix match against `Bash(cargo:*)`. Let Claude Code capture the full stdout/stderr and exit code natively — do not post-process with `tail`, `head`, or `echo "exit:$?"`. If output truncation is genuinely needed, run the command first and read the result in a separate tool call.
 
 5. **MCP usage**: The canonical list of MCP servers and tools available for this run lives in the lead prompt's `## Available MCP Servers` section (sourced from `.project-docs/okstra/project.json`'s `mcpServers` array). When the task requires inspection of an external system covered by one of those servers, call the listed tool directly by name (e.g. `mcp__<server>__<tool>`). Do NOT shell out via `claude --mcp-cli call ...` or run the tool name as a Bash command — those are not valid invocation paths. If a server you need is not listed, record `MCP not available for this run` in your worker output rather than guessing a tool name.
 

package/runtime/bin/okstra-codex-exec.sh

@@ -172,6 +172,17 @@ if [[ -n "${TMUX:-}" ]]; then
   if [[ -n "$trace_pane" ]]; then
     tmux select-pane -t "$trace_pane" -T "codex-${role}-trace" 2>/dev/null || true
     tmux last-pane 2>/dev/null || true
+    # Register the spawned pane so the `SessionEnd` hook (see
+    # `okstra-trace-cleanup.sh`) can kill it when the caller's Claude
+    # session exits. Scope by caller `$TMUX_PANE` — the pane Claude itself
+    # is attached to — so concurrent Claude instances in the same tmux
+    # session do not stomp each other's trace panes.
+    if [[ -n "${TMUX_PANE:-}" ]]; then
+      registry_dir="${TMPDIR:-/tmp}/okstra-trace-panes"
+      mkdir -p "$registry_dir" 2>/dev/null || true
+      safe_pane="${TMUX_PANE//[^A-Za-z0-9]/_}"
+      printf '%s\n' "$trace_pane" >> "$registry_dir/${safe_pane}.list" 2>/dev/null || true
+    fi
   fi
 fi
 

package/runtime/bin/okstra-gemini-exec.sh

@@ -121,6 +121,13 @@ if [[ -n "${TMUX:-}" ]]; then
   if [[ -n "$trace_pane" ]]; then
     tmux select-pane -t "$trace_pane" -T "gemini-${role}-trace" 2>/dev/null || true
     tmux last-pane 2>/dev/null || true
+    # See `okstra-codex-exec.sh` for the registry rationale — kept in lock-step.
+    if [[ -n "${TMUX_PANE:-}" ]]; then
+      registry_dir="${TMPDIR:-/tmp}/okstra-trace-panes"
+      mkdir -p "$registry_dir" 2>/dev/null || true
+      safe_pane="${TMUX_PANE//[^A-Za-z0-9]/_}"
+      printf '%s\n' "$trace_pane" >> "$registry_dir/${safe_pane}.list" 2>/dev/null || true
+    fi
   fi
 fi
 

package/runtime/bin/okstra-trace-cleanup.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+#
+# okstra-trace-cleanup.sh — kill tmux trace panes spawned by okstra worker
+# wrappers (`okstra-codex-exec.sh`, `okstra-gemini-exec.sh`) for the current
+# Claude Code session.
+#
+# Invoked from the `SessionEnd` hook in
+# `templates/reports/settings.template.json`. The wrappers register every
+# pane they split into a registry file keyed by the caller's `$TMUX_PANE`
+# (i.e. the pane Claude itself is attached to). On Claude `/exit`, the hook
+# runs in that same pane's env, reads its own registry file, and kills each
+# registered pane.
+#
+# Scoping by caller `$TMUX_PANE` (not by tmux session) lets multiple Claude
+# instances coexist in the same tmux session without stomping each other's
+# trace panes.
+#
+# Failures are tolerated silently — a stale pane id, missing $TMUX, or a
+# locked tmux client must never prevent Claude from exiting cleanly.
+
+set -u
+
+# No tmux pane context → nothing to clean.
+if [[ -z "${TMUX_PANE:-}" ]]; then
+  exit 0
+fi
+
+registry_dir="${TMPDIR:-/tmp}/okstra-trace-panes"
+safe_pane="${TMUX_PANE//[^A-Za-z0-9]/_}"
+registry_file="$registry_dir/${safe_pane}.list"
+
+if [[ ! -f "$registry_file" ]]; then
+  exit 0
+fi
+
+while IFS= read -r pane_id; do
+  [[ -n "$pane_id" ]] || continue
+  tmux kill-pane -t "$pane_id" 2>/dev/null || true
+done < "$registry_file"
+
+rm -f "$registry_file" 2>/dev/null || true
+exit 0

package/runtime/templates/reports/settings.template.json

@@ -143,5 +143,14 @@
       "mcp__test-context7__resolve-library-id",
       "mcp__test-context7__query-docs"
     ]
+  },
+  "hooks": {
+    "SessionEnd": [
+      {
+        "hooks": [
+          { "type": "command", "command": "$HOME/.okstra/bin/okstra-trace-cleanup.sh" }
+        ]
+      }
+    ]
   }
 }

package/src/install.mjs

@@ -20,6 +20,7 @@ const BIN_ENTRYPOINTS = [
   "okstra.sh",
   "okstra-codex-exec.sh",
   "okstra-gemini-exec.sh",
+  "okstra-trace-cleanup.sh",
   "okstra-central.sh",
   "okstra-token-usage.py",
   "okstra-error-log.py",

package/src/uninstall.mjs

@@ -7,6 +7,7 @@ const BIN_ENTRYPOINTS = [
   "okstra.sh",
   "okstra-codex-exec.sh",
   "okstra-gemini-exec.sh",
+  "okstra-trace-cleanup.sh",
   "okstra-central.sh",
   "okstra-token-usage.py",
   "okstra-error-log.py",