okstra 0.21.1 → 0.22.0

package/docs/kr/architecture.md

@@ -838,6 +838,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.
+- **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/project-structure-overview.md

@@ -385,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.1",
+  "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.1",
-  "builtAt": "2026-05-14T12:50:20.728Z",
+  "package": "0.22.0",
+  "builtAt": "2026-05-14T15:54:01.726Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -1,26 +1,48 @@
 #!/usr/bin/env bash
 #
-# okstra-trace-cleanup.sh — kill tmux trace panes spawned by okstra worker
+# 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.
 #
-# 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.
+# 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.
 #
-# 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.
+# 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
 
-# No tmux pane context → nothing to clean.
+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
@@ -33,6 +55,17 @@ 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

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:*)",

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\`)