okstra 0.21.0 → 0.22.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 스킬 마크다운 소스 (스킬 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,8 @@ 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.
+- **Phase 종료 시 사용자 확인**: 매 phase 의 마지막 단계로 lead 가 `okstra-trace-cleanup.sh --list` 로 등록된 pane 목록을 출력한 뒤 사용자에게 "모두 닫기 / 그대로 두기" 양자택일을 묻고 응답대로 처리합니다 (`prompts/profiles/_common-contract.md` 의 *Phase wrap-up* 항목). `$TMUX_PANE` 미설정 환경에서는 단계 자체가 silent-skip. `--list` 모드는 pane 을 죽이지 않고 `<pane_id>\t<pane_title>` 만 출력하므로 사용자가 무엇이 닫힐지 시각적으로 확인할 수 있습니다.
 - 디스크 누적은 `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 작업 수행 → 실패 시 사용자 안내**.
 
@@ -383,4 +385,57 @@ okstra/
 
 ---
 
+## 부록 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 사용자 확인 질문` |
+
+### A.2 Worker-result 행 ID (worker 가 자기 output 안에서 매기는 ID)
+
+`okstra-team-contract` 가 정의하는 worker output 6개 섹션 중 1, 2 섹션이 prefix 를 갖습니다.
+
+| 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` |
+
+---
+
 *작성일: 2026-05-14 · 분석 대상: `claude/objective-einstein-250add` 브랜치 기준 okstra v0.20.1*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.21.0",
+  "version": "0.22.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.21.0",
-  "builtAt": "2026-05-14T11:48:06.992Z",
+  "package": "0.22.0",
+  "builtAt": "2026-05-14T15:54:01.726Z",
   "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,75 @@
+#!/usr/bin/env bash
+#
+# okstra-trace-cleanup.sh — manage tmux trace panes spawned by okstra worker
+# wrappers (`okstra-codex-exec.sh`, `okstra-gemini-exec.sh`) for the current
+# Claude Code session.
+#
+# Two modes:
+#   (default)  kill every registered pane and remove the registry file.
+#              Used by the `SessionEnd` hook in
+#              `templates/reports/settings.template.json` so panes do not
+#              outlive Claude `/exit`. Also callable manually by the lead at
+#              phase-end (see `_common-contract.md`).
+#   --list     print one line per registered pane (`<pane_id>\t<pane_title>`)
+#              so the lead can show the user what *would* be closed before
+#              asking. Exits 0 with empty stdout when nothing is tracked.
+#
+# Pane registry is keyed by the caller's `$TMUX_PANE` — the pane Claude
+# itself is attached to. Multiple Claude instances in the same tmux session
+# therefore do not stomp 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
+
+MODE="kill"
+case "${1:-}" in
+  "")        MODE="kill" ;;
+  --list)    MODE="list" ;;
+  --dry-run) MODE="list" ;;  # alias
+  -h|--help)
+    cat <<'USAGE'
+usage: okstra-trace-cleanup.sh [--list]
+
+  (no args)   kill every pane registered for $TMUX_PANE; remove registry file.
+  --list      print "<pane_id>\t<pane_title>" per registered pane; no kill.
+  --dry-run   alias for --list.
+USAGE
+    exit 0 ;;
+  *)
+    printf 'okstra-trace-cleanup.sh: unknown option: %s\n' "$1" >&2
+    exit 2 ;;
+esac
+
+# No tmux pane context → nothing to clean / list.
+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
+
+if [[ "$MODE" == "list" ]]; then
+  while IFS= read -r pane_id; do
+    [[ -n "$pane_id" ]] || continue
+    # `display-message -p` resolves a *live* pane's title; for stale ids
+    # tmux exits non-zero — fall back to an empty title rather than failing.
+    title=$(tmux display-message -p -t "$pane_id" '#{pane_title}' 2>/dev/null || true)
+    printf '%s\t%s\n' "$pane_id" "$title"
+  done < "$registry_file"
+  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/prompts/profiles/_common-contract.md

@@ -20,6 +20,18 @@ profile document.
   - This rule does NOT relax any phase-specific Forbidden actions list; safety rules in the per-profile document remain in force regardless of the user's authority.
 - Anti-escalation rule (shared):
   - treating "다음 단계 진행해" or equivalent user phrases as authorisation to start a *different* lifecycle phase is forbidden. The next phase begins only in a separate okstra run launched with the new `--task-type`. Per-profile documents may further restrict this within their own scope.
+- Phase wrap-up — worker trace pane disposition (shared, MUST be the *last* step before returning control to the user):
+  - Codex / Gemini worker wrappers spawn `tail -F` trace panes in the lead's tmux session (`codex-<role>-trace`, `gemini-<role>-trace`). They survive every worker invocation by design so the operator can scroll back through the final output, but accumulate across phases and clutter the screen.
+  - When `$TMUX_PANE` is set, after the final-report file has been written and the routing recommendation has been issued, the lead MUST run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list` exactly once. The output is a tab-separated `<pane_id>\t<pane_title>` list of every trace pane registered for this Claude session.
+  - If the list is empty, skip the question — there is nothing to ask about.
+  - Otherwise the lead MUST present the user with a strict binary choice **before** declaring the phase complete. Use one prompt of this shape (Korean preferred, English acceptable if the rest of the run is in English):
+    > 현재 phase 종료 시점입니다. 다음 worker trace pane 이 열려 있습니다 — 닫을까요?
+    > <인용된 `--list` 출력>
+    > (예) 모두 닫기 / (아니오) 그대로 두기
+  - On `예` / `y` / `close` → run `$HOME/.okstra/bin/okstra-trace-cleanup.sh` (no args) and report the kill count back in one sentence.
+  - On `아니오` / `n` / `keep` → leave the panes intact; remind the user that they will be cleaned up automatically when Claude `/exit` fires the `SessionEnd` hook.
+  - The question MUST be a clean yes/no — do NOT offer "close some / keep some" partial answers, do NOT propose alternatives like "close only codex panes". The whole-set decision keeps the wrap-up predictable.
+  - This step is mandatory for every phase (`requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`). It is silent-skipped when `$TMUX_PANE` is unset (lead running outside tmux); the lead MUST NOT fabricate a synthetic pane list in that case.
 - Clarification request policy (shared — applies whenever a profile uses `## 5. Clarification Requests for the Next Run`):
   - section 5 MUST be split into two distinct sub-sections per `final-report-template.md` — `5.1 추가 자료 요청 (Additional Materials Requested)` for files/logs/screenshots/links the user must attach, and `5.2 사용자 확인 질문 (Questions for the User)` for decisions or facts only the user can confirm. Never mix material requests and decision questions in the same row or list.
   - write every entry in full, descriptive sentences that a non-developer can act on without further context. Avoid abbreviations and internal jargon. For each material request, state *why* it is needed, *where* the user can find it, and *where* to place it. For each question, state *why* the answer changes the next step, *what* is being asked in a complete sentence, and *what shape of answer* is expected (예/아니오, 보기 중 하나, 숫자/날짜, 짧은 서술 등); supply concrete option choices when applicable.

package/runtime/prompts/profiles/release-handoff.md

@@ -34,9 +34,10 @@
      - `cancel` — end the run without executing push or PR commands; record the cancellation in the final report.
 - Inline drafting rules (Claude lead):
   - read the run brief, the cited final-verification report, `git log --oneline <base>..HEAD`, and `git diff <base>..HEAD --stat` to ground the drafted text in actual committed changes.
+  - **PR body template** — the run context exposes `PR_TEMPLATE_PATH` (resolved by the prepare step in priority order: per-run override → `<project_root>/.project-docs/okstra/project.json` `prTemplatePath` → `~/.okstra/config.json` `prTemplatePath` → bundled default at `~/.claude/skills/okstra-run/templates/pr-body.template.md`) along with `PR_TEMPLATE_SOURCE` indicating which scope was used. The lead MUST `Read` this file verbatim, strip HTML comments, then fill in the placeholders. Do NOT hard-code a section list — the template is the source of truth for the structure. If the resolved file is missing at draft time, abort the run with a clear error rather than inventing a structure.
   - produce **two artifacts** before showing them to the user:
     1. **PR title** — by default the subject of the most recent implementation commit, or a concise Conventional Commits-style summary of the committed range.
-    2. **PR body** — markdown with sections `## Summary`, `## Changes`, `## Test plan`, `## Linked issues` (omit a section only if it is genuinely empty).
+    2. **PR body** — markdown filled from `PR_TEMPLATE_PATH`. The user-confirmation step's diff (Q3 `edit then proceed`) is computed against the filled template, not against the raw template file.
 - Allowed actions during the run (Claude lead only):
   - read-only inspection: `git status`, `git status --short`, `git diff`, `git log`, `git rev-parse`, `git ls-remote --heads origin <name>`, `gh pr list --head <branch>`, `gh pr view <url>`.
   - feature-branch push (only when the user picked `push + PR`): `git push -u origin <current-branch>`. The pushed ref MUST be the feature branch — never the chosen base branch.

package/runtime/python/okstra_ctl/index.py

@@ -57,6 +57,7 @@ def record_start(home: Path, *, project_id: str, project_root: str,
                  run_dir_rel: str, final_report_rel: str,
                  argv: list, cwd: str,
                  env_overrides: dict,
+                 okstra_version: str = "",
                  brief_sha256: str = "",
                  initial_status: str = "running",
                  final_status_rel: str = "") -> str:
@@ -122,7 +123,7 @@ def record_start(home: Path, *, project_id: str, project_root: str,
     _replace_or_append_project_row(home, project_id, run_id, row)
     save_invocation(home, project_id, task_group, task_id, task_type, run_seq, {
         "runId": run_id,
-        "okstraVersion": os.environ.get("OKSTRA_SCRIPT_VERSION", ""),
+        "okstraVersion": okstra_version or os.environ.get("OKSTRA_SCRIPT_VERSION", ""),
         "invokedAt": when,
         "cwd": cwd,
         "argv": argv,

package/runtime/python/okstra_ctl/pr_template.py

@@ -0,0 +1,126 @@
+"""PR body 템플릿 경로 해석.
+
+release-handoff 단계에서 lead 가 PR 본문을 작성할 때 사용하는 마크다운
+템플릿의 경로를 결정한다. 우선순위:
+
+    1. per-run override (okstra-run Step 6 에서 입력)
+    2. project: <project_root>/.project-docs/okstra/project.json 의 ``prTemplatePath``
+    3. global:  ~/.okstra/config.json 의 ``prTemplatePath``
+    4. default: 스킬 설치 디렉터리의 ``okstra-run/templates/pr-body.template.md``
+
+경로는 절대경로 또는 ``~`` 시작 경로를 권장한다. 상대경로일 경우 project
+스코프는 ``project_root`` 기준, override 는 호출자 cwd 기준으로 해석한다.
+global 스코프에서 상대경로는 모호하므로 거절한다.
+"""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+_DEFAULT_FILENAME = "pr-body.template.md"
+
+
+class PrTemplateError(Exception):
+    """invalid PR template configuration — surface to user."""
+
+
+@dataclass(frozen=True)
+class ResolvedPrTemplate:
+    path: Path
+    source: str  # "override" | "project" | "global" | "default"
+
+
+def _okstra_home() -> Path:
+    override = os.environ.get("OKSTRA_HOME", "").strip()
+    return Path(override) if override else Path.home() / ".okstra"
+
+
+def _default_template_candidates() -> list[Path]:
+    """디폴트 템플릿 후보 경로들 (우선순위 순)."""
+    out: list[Path] = []
+    env_dir = os.environ.get("OKSTRA_SKILLS_DIR", "").strip()
+    if env_dir:
+        out.append(Path(env_dir) / "okstra-run" / "templates" / _DEFAULT_FILENAME)
+    out.append(
+        Path.home() / ".claude" / "skills" / "okstra-run" / "templates" / _DEFAULT_FILENAME
+    )
+    return out
+
+
+def _read_json_field(path: Path, field: str) -> str:
+    if not path.is_file():
+        return ""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return ""
+    if not isinstance(data, dict):
+        return ""
+    return str(data.get(field) or "").strip()
+
+
+def _resolve_project_relative(value: str, project_root: Path) -> Path:
+    p = Path(value).expanduser()
+    return p if p.is_absolute() else (Path(project_root) / p).resolve()
+
+
+def resolve_pr_template_path(
+    project_root: Path,
+    override_path: str = "",
+) -> ResolvedPrTemplate:
+    """우선순위에 따라 PR 템플릿 경로를 해석한다.
+
+    Raises:
+      PrTemplateError: 설정된 경로가 존재하지 않거나, 디폴트조차 찾지 못한 경우.
+    """
+    project_root = Path(project_root)
+
+    # 1) per-run override
+    ov = (override_path or "").strip()
+    if ov:
+        p = _resolve_project_relative(ov, project_root)
+        if not p.is_file():
+            raise PrTemplateError(f"override PR template not found: {p}")
+        return ResolvedPrTemplate(path=p, source="override")
+
+    # 2) project.json
+    pj_path = Path(project_root) / ".project-docs" / "okstra" / "project.json"
+    pj_val = _read_json_field(pj_path, "prTemplatePath")
+    if pj_val:
+        p = _resolve_project_relative(pj_val, project_root)
+        if not p.is_file():
+            raise PrTemplateError(
+                f"project.json prTemplatePath points to missing file: {p} "
+                f"(configured in {pj_path})"
+            )
+        return ResolvedPrTemplate(path=p, source="project")
+
+    # 3) global config
+    gc_path = _okstra_home() / "config.json"
+    gv = _read_json_field(gc_path, "prTemplatePath")
+    if gv:
+        p = Path(gv).expanduser()
+        if not p.is_absolute():
+            raise PrTemplateError(
+                f"global config prTemplatePath must be absolute or start with '~/': got {gv!r} "
+                f"(configured in {gc_path})"
+            )
+        if not p.is_file():
+            raise PrTemplateError(
+                f"global prTemplatePath missing: {p} (configured in {gc_path})"
+            )
+        return ResolvedPrTemplate(path=p, source="global")
+
+    # 4) default
+    for cand in _default_template_candidates():
+        if cand.is_file():
+            return ResolvedPrTemplate(path=cand, source="default")
+
+    raise PrTemplateError(
+        "no PR template available: default skill template not found. "
+        f"Searched: {', '.join(str(c) for c in _default_template_candidates())}. "
+        "Reinstall okstra (`npx okstra install`) or set prTemplatePath in "
+        "project.json / ~/.okstra/config.json."
+    )

package/runtime/python/okstra_ctl/render.py

@@ -694,6 +694,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
     workflow = task_manifest.get("workflow", {}) if isinstance(task_manifest.get("workflow"), dict) else {}
     payload = {
         "schemaVersion": "1.0",
+        "okstraVersion": ctx.get("OKSTRA_VERSION", ""),
         "projectId": ctx.get("PROJECT_ID", ""),
         "taskGroup": ctx.get("TASK_GROUP", ""),
         "taskId": ctx.get("TASK_ID", ""),
@@ -907,6 +908,7 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
         "{{RELATED_TASKS_INLINE}}": ctx.get("RELATED_TASKS_INLINE", "None"),
         "{{RECOMMENDED_ANALYSERS}}": ", ".join(task_manifest.get("recommendedWorkers", [])),
         "{{LEAD_MODEL}}": rc.get("leadModel", ctx.get("LEAD_MODEL_DISPLAY", "")),
+        "{{OKSTRA_VERSION}}": ctx.get("OKSTRA_VERSION", ""),
         "{{LATEST_RUN_RELATIVE_PATH}}": task_manifest.get("latestRunPath", ctx.get("LATEST_RUN_RELATIVE_PATH", "")),
         "{{LATEST_REPORT_RELATIVE_PATH}}": task_manifest.get("latestReportPath", ctx.get("LATEST_REPORT_RELATIVE_PATH", "")),
         "{{TEAM_STATE_RELATIVE_PATH}}": task_manifest.get("teamStatePath", ctx.get("TEAM_STATE_RELATIVE_PATH", "")),
@@ -1161,6 +1163,7 @@ def render_template_file(template_path: str, output_path: str, ctx: dict) -> Non
         "{{REPORT_WRITER_WORKER_ERRORS_SIDECAR_RELATIVE_PATH}}": ctx.get("REPORT_WRITER_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", ""),
         "{{LEAD_MODEL}}": lead_model,
         "{{LEAD_MODEL_EXECUTION_VALUE}}": lead_model_execution,
+        "{{OKSTRA_VERSION}}": ctx.get("OKSTRA_VERSION", ""),
         "{{CLAUDE_WORKER_MODEL}}": ctx.get("CLAUDE_WORKER_MODEL_DISPLAY", ""),
         "{{CLAUDE_WORKER_MODEL_EXECUTION_VALUE}}": ctx.get("CLAUDE_WORKER_MODEL_EXECUTION_VALUE", ""),
         "{{CODEX_WORKER_MODEL}}": ctx.get("CODEX_WORKER_MODEL_DISPLAY", ""),

package/runtime/python/okstra_ctl/run.py

@@ -49,6 +49,7 @@ from .seeding import (
     SettingsLinkError,
     cleanup_obsolete_generated_docs,
     ensure_project_settings_symlink,
+    installed_version,
     verify_installation,
 )
 from .session import (
@@ -56,7 +57,12 @@ from .session import (
     resolve_inproc_lead_session_id,
     write_claude_resume_command_file,
 )
-from .workers import normalize_workers, resolve_profile_workers
+from .pr_template import PrTemplateError, resolve_pr_template_path
+from .workers import (
+    normalize_workers,
+    resolve_profile_workers,
+    validate_workers_against_profile,
+)
 from .workflow import compute_workflow_state
 from .worktree import provision_task_worktree
 
@@ -102,6 +108,9 @@ class PrepareInputs:
     base_ref: str = ""
     approved_plan_path: str = ""
     clarification_response_path: str = ""  # absolute or empty
+    # release-handoff 전용: PR 본문 템플릿 1회성 override. 빈 문자열이면
+    # project.json → global config → 스킬 디폴트 순으로 해석된다.
+    pr_template_path: str = ""
     render_only: bool = False
     refresh_assets: bool = False
     approve_plan_ack: bool = False
@@ -310,6 +319,7 @@ def _record_start(
             argv=canonical_argv,
             cwd=cwd,
             env_overrides={},
+            okstra_version=ctx.get("OKSTRA_VERSION", ""),
             initial_status=initial_status,
             brief_sha256=brief_sha256,
         )
@@ -495,12 +505,28 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     if inp.task_type == "release-handoff":
         workers: list[str] = []
     else:
-        profile_workers_csv = ",".join(resolve_profile_workers(profile_file))
+        profile_workers = resolve_profile_workers(profile_file)
+        profile_workers_csv = ",".join(profile_workers)
         workers = normalize_workers(inp.workers_override or profile_workers_csv)
+        if inp.workers_override.strip():
+            validate_workers_against_profile(workers, profile_workers)
         if not workers:
             raise PrepareError(f"no workers resolved for profile: {inp.task_type}")
     selected_reviewers = ",".join(workers)
 
+    # ---- PR template resolution (release-handoff only) ----
+    pr_template_path_str = ""
+    pr_template_source = ""
+    if inp.task_type == "release-handoff":
+        try:
+            resolved_tpl = resolve_pr_template_path(
+                Path(inp.project_root), inp.pr_template_path
+            )
+        except PrTemplateError as exc:
+            raise PrepareError(f"PR template resolution failed: {exc}") from exc
+        pr_template_path_str = str(resolved_tpl.path)
+        pr_template_source = resolved_tpl.source
+
     # ---- model assignments ----
     lead_default = _default("OKSTRA_DEFAULT_LEAD_MODEL", "opus")
     claude_default = _default("OKSTRA_DEFAULT_CLAUDE_MODEL", "sonnet")
@@ -634,6 +660,8 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     ctx.update({
         "REVIEW_PROFILE": inp.task_type,
         "SELECTED_REVIEWERS": selected_reviewers,
+        "PR_TEMPLATE_PATH": pr_template_path_str,
+        "PR_TEMPLATE_SOURCE": pr_template_source,
         "CLAUDE_SESSION_ID": claude_session_id,
         "CLARIFICATION_RESPONSE_PATH": inp.clarification_response_path,
         "CLARIFICATION_RESPONSE_FILE": inp.clarification_response_path,
@@ -666,6 +694,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "LATEST_REPORT_PATH": "",
         "LATEST_REPORT_RELATIVE_PATH": "",
         "RENDER_ONLY": "true" if inp.render_only else "false",
+        "OKSTRA_VERSION": installed_version(),
         **workflow_state,
     })
 
@@ -853,6 +882,15 @@ def main(argv: list[str]) -> int:
         ),
     )
     p.add_argument("--clarification-response", default="", dest="clarification_response_path")
+    p.add_argument(
+        "--pr-template-path",
+        default="",
+        dest="pr_template_path",
+        help=(
+            "release-handoff 전용 1회성 PR 본문 템플릿 경로. 빈 값이면 "
+            "project.json → ~/.okstra/config.json → 스킬 디폴트 순으로 해석."
+        ),
+    )
     p.add_argument("--render-only", action="store_true", dest="render_only")
     p.add_argument("--refresh-assets", action="store_true", dest="refresh_assets")
     p.add_argument(
@@ -917,6 +955,7 @@ def main(argv: list[str]) -> int:
         base_ref=args.base_ref,
         approved_plan_path=args.approved_plan_path,
         clarification_response_path=clarification_abs,
+        pr_template_path=args.pr_template_path,
         render_only=args.render_only,
         refresh_assets=args.refresh_assets,
         approve_plan_ack=args.approve_plan_ack,

package/runtime/python/okstra_ctl/seeding.py

@@ -23,6 +23,25 @@ class SettingsLinkError(Exception):
     """`<project>/.claude/settings.local.json` symlink provisioning 실패."""
 
 
+def installed_version() -> str:
+    """Read the version stamp written by `okstra install` to `~/.okstra/version`.
+
+    Returns an empty string if the stamp is missing or unreadable. Callers use
+    the result to label generated artifacts (run manifests, final reports) so
+    that consumers can tell which okstra release produced a given run — and
+    so that report readers can distinguish behaviour drift across upgrades
+    without having to dig through git history.
+
+    The stamp lives at `_okstra_home() / "version"`. `OKSTRA_HOME` overrides
+    the home directory for tests.
+    """
+    version_file = _okstra_home() / "version"
+    try:
+        return version_file.read_text(encoding="utf-8").strip()
+    except OSError:
+        return ""
+
+
 def required_install_paths() -> list[Path]:
     """okstra install 이 채워야 하는 최소 자산 경로."""
     okstra_home = Path.home() / ".okstra"

package/runtime/python/okstra_ctl/workers.py

@@ -68,3 +68,23 @@ def normalize_workers(value: str) -> list[str]:
         seen.add(v)
         out.append(v)
     return out
+
+
+def validate_workers_against_profile(
+    workers: list[str], profile_workers: list[str]
+) -> None:
+    """프로파일이 `Required workers:` 로 로스터를 선언했다면, 사용자
+    override 가 그 부분집합인지 검증한다.
+
+    `profile_workers` 가 비어 있으면(프로파일이 로스터를 선언하지 않은
+    구버전) 검증을 건너뛴다 — 하위 호환을 위해.
+    """
+    if not profile_workers:
+        return
+    allowed = set(profile_workers)
+    extras = [w for w in workers if w not in allowed]
+    if extras:
+        raise WorkersError(
+            "workers not allowed by profile roster: "
+            f"{','.join(extras)} (profile allows: {','.join(profile_workers)})"
+        )

package/runtime/skills/okstra-run/SKILL.md

@@ -208,19 +208,37 @@ Do NOT ask for `workers_override` in implementation — the profile's required r
 
 ### 6b. Other phases (`requirements-discovery`, `error-analysis`, `implementation-planning`, `final-verification`, `release-handoff`)
 
-Ask each in turn (model prompts use `AskUserQuestion` with the option lists above; others are free text):
+**Before asking any worker/model question, resolve the profile's allowed roster:**
 
-1. `AskUserQuestion` `"참여 워커 목록 (쉼표 구분, 빈 칸 = 프로필 기본값 claude,codex,report-writer). 선택지: claude, codex, gemini, report-writer — gemini는 옵션이므로 필요할 때 명시"` (free text) → `workers_override`
+```python
+from okstra_ctl.workers import resolve_profile_workers
+profile_workers = resolve_profile_workers(Path("<OKSTRA_PROMPTS_PROFILES_DIR>/<task-type>.md"))
+```
+
+This is the **only** set of worker IDs you may show or ask about. Never offer
+workers outside this list. Special cases:
+
+- If `profile_workers` is empty (e.g., `release-handoff` is lead-only with no
+  `- Required workers:` block), **skip the worker question and all
+  worker-model questions entirely** — only ask lead model, directive, related,
+  clarification. The backend forces `workers=[]` for these profiles.
+- Otherwise, the worker question must enumerate **only** `profile_workers` —
+  do NOT show `claude, codex, gemini, report-writer` blindly.
+
+Ask each in turn (model prompts use `AskUserQuestion` with the option lists above; others are free text). Skip any worker-model prompt whose worker is not in `profile_workers`.
+
+1. (only when `profile_workers` is non-empty) `AskUserQuestion` `"참여 워커 목록 (쉼표 구분, 빈 칸 = 프로필 기본값 <profile_workers_csv>). 선택지: <profile_workers_csv>"` (free text) → `workers_override`. Validate the answer is a subset of `profile_workers`; re-ask on failure. (Backend will also reject violations with `WorkersError`.)
 2. `AskUserQuestion` `"리더(Claude lead) 모델?"` (Claude options) → `lead_model`
-3. `AskUserQuestion` `"claude 워커 모델?"` (Claude options) → `claude_model`
-4. `AskUserQuestion` `"codex 워커 모델?"` (Codex options) → `codex_model`
-5. `AskUserQuestion` `"gemini 워커 모델?"` (Gemini options) → `gemini_model`
-6. `AskUserQuestion` `"리포트 작성자 모델?"` (Claude options) → `report_writer_model`
+3. (only if `claude` ∈ resolved workers) `AskUserQuestion` `"claude 워커 모델?"` (Claude options) → `claude_model`
+4. (only if `codex` ∈ resolved workers) `AskUserQuestion` `"codex 워커 모델?"` (Codex options) → `codex_model`
+5. (only if `gemini` ∈ resolved workers) `AskUserQuestion` `"gemini 워커 모델?"` (Gemini options) → `gemini_model`
+6. (only if `report-writer` ∈ resolved workers) `AskUserQuestion` `"리포트 작성자 모델?"` (Claude options) → `report_writer_model`
 7. `AskUserQuestion` `"추가 directive (선택, 빈 칸 가능)"` (free text) → `directive`
 8. `AskUserQuestion` `"관련 task id 목록, 쉼표 구분 (선택, 빈 칸 가능)"` (free text) → `related_tasks_raw`
 9. `AskUserQuestion` `"clarification-response 파일 경로 (follow-up 시에만, 빈 칸 가능)"` (free text) → `clarification_response_path`
+10. (only when `task_type == "release-handoff"`) `AskUserQuestion` `"PR 본문 템플릿 경로 1회성 override (빈 칸 = project.json → ~/.okstra/config.json → 스킬 디폴트 순으로 자동 해석)"` (free text) → `pr_template_path`. The backend (`okstra_ctl.pr_template.resolve_pr_template_path`) validates the file exists and surfaces `PrTemplateError` on failure. If the user wants to persist the choice instead of a one-shot override, tell them to set `prTemplatePath` in `<project_root>/.project-docs/okstra/project.json` (project scope) or `~/.okstra/config.json` (global scope).
 
-For prompts whose target worker is NOT in the resolved workers list (after override), skip the prompt and present a single line such as `gemini-model 생략 (workers에 gemini 없음)`.
+For prompts whose target worker is NOT in the resolved workers list (after override), present a single confirmation line such as `gemini-model 생략 (workers에 gemini 없음)` so the user can see why the question was skipped.
 
 ## Step 6.5: Confirm selections before rendering
 
@@ -267,7 +285,8 @@ okstra render-bundle \
   --lead-model "..." --claude-model "..." --codex-model "..." \
   --gemini-model "..." --report-writer-model "..." \
   --related-tasks "..." \
-  --clarification-response "<clarification-or-empty>"
+  --clarification-response "<clarification-or-empty>" \
+  --pr-template-path "<pr-template-override-or-empty; release-handoff only>"
 ```
 
 Stdout prints `okstra task root:`, `okstra instruction-set:`, and the full

package/runtime/skills/okstra-run/templates/pr-body.template.md

@@ -0,0 +1,41 @@
+<!--
+okstra release-handoff 기본 PR 본문 템플릿.
+
+이 파일은 사용자 정의 PR 템플릿이 없을 때 사용됩니다. 우선순위:
+  1. okstra-run Step 6 에서 입력한 per-run override 경로
+  2. <project-root>/.project-docs/okstra/project.json 의 `prTemplatePath`
+  3. ~/.okstra/config.json 의 `prTemplatePath`
+  4. 이 디폴트 파일
+
+프로젝트 또는 전역 설정으로 자체 템플릿을 쓰려면 위 경로 중 하나에
+`prTemplatePath` 키를 추가하세요. (절대경로 또는 project_root 기준 상대경로)
+
+플레이스홀더는 release-handoff 의 Claude lead 가 다음 입력을 근거로
+직접 채웁니다:
+  - run brief 의 의도/스코프
+  - 인용된 final-verification 리포트의 verdict 근거
+  - `git log --oneline <base>..HEAD` 의 commit 범위
+  - `git diff <base>..HEAD --stat` 의 변경 파일 통계
+
+빈 섹션은 그대로 두지 말고 통째로 삭제합니다. HTML 주석은 PR 생성 전에
+모두 제거됩니다.
+-->
+
+## Summary
+
+<!-- 1–3 bullets. 변경의 동기(WHY)와 결과(WHAT changed at a high level). -->
+
+## Changes
+
+<!-- 영역별로 묶은 구체적 변경 목록. 파일/모듈 단위 그룹화 권장. -->
+
+## Test plan
+
+<!-- 리뷰어가 따라 할 수 있는 검증 절차. 자동/수동 모두 가능. -->
+
+- [ ] <검증 항목>
+- [ ] <검증 항목>
+
+## Linked issues
+
+<!-- `Refs: TICKET-123`, `Closes #N`, 관련 PR 링크 등. 없으면 섹션 통째로 삭제. -->

package/runtime/templates/reports/final-report.template.md

@@ -16,6 +16,7 @@ project-id: "{{PROJECT_ID}}"
 - Task Type: {{TASK_TYPE}}
 - Report Owner: `Claude lead`
 - Lead Model: `{{LEAD_MODEL}}`
+- Okstra Version: `{{OKSTRA_VERSION}}`
 - Clarification Response Carried In: `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}`
 
 ## User Approval Request (사용자 승인 게이트)

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

@@ -131,11 +131,13 @@
       "Bash(codex exec:*)",
       "Bash(okstra)",
       "Bash(okstra:*)",
-      "Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)",
+      "Bash($HOME/.okstra/bin/:*)",
 
       "Bash(gemini)",
       "Bash(gemini:*)",
-      "Bash($HOME/.okstra/bin/okstra-gemini-exec.sh:*)",
+
+      "Bash($HOME/.okstra/bin/okstra-trace-cleanup.sh)",
+      "Bash($HOME/.okstra/bin/okstra-trace-cleanup.sh:*)",
 
       "Bash(claude)",
       "Bash(claude:*)",
@@ -143,5 +145,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/render-bundle.mjs

@@ -17,7 +17,8 @@ Usage:
     [--lead-model <m>] [--claude-model <m>] [--codex-model <m>] \\
     [--gemini-model <m>] [--report-writer-model <m>] \\
     [--related-tasks <list>] [--base-ref <ref>] \\
-    [--clarification-response <path>] [--work-category <cat>]
+    [--clarification-response <path>] [--work-category <cat>] \\
+    [--pr-template-path <path>]   # release-handoff only
 
 All flags pass through unchanged to \`python3 -m okstra_ctl.run\`. The
 shim auto-supplies \`--workspace-root\` (from \`okstra paths --field workspace\`)

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",