okstra 0.21.1 → 0.23.0

package/README.kr.md

@@ -167,6 +167,8 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 
 - **`--task-type implementation` 격리 worktree 자동 provisioning** — prepare 단계에서 `okstra-ctl` 이 `git worktree add ~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>-<run-seq>` 를 수행해 격리된 working tree 와 브랜치 `<work-category-prefix>-<task-id-segment>-<run-seq>` (예: `feat-dev-9436-001`, `fix-dev-7311-002`) 를 만듭니다. base ref 는 사용자가 `--base-ref` 로 지정 (release-handoff PR base picker 와 동일한 메뉴: `main` / `dev` / `staging` / `preprod` / `prod` / 직접 입력). 첫 phase 에서는 필수이며, okstra-run skill 이 `AskUserQuestion` 으로 수집합니다 — 비대화형 호출자는 `--base-ref` 플래그를 직접 전달해야 prepare 가 통과합니다. Executor 와 verifier 모두 이 worktree 안에서 동작하므로 caller 의 작업 디렉터리는 깨끗하게 유지되고, worktree 는 PR 작성 · rollback 검증의 권위 artefact 로 남습니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 됩니다. 수동 cleanup: `git worktree remove <path>` → `git branch -D <branch>`. 상세: [`docs/kr/architecture.md`](docs/kr/architecture.md) *Task type* 섹션, [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
 - **`release-handoff` lifecycle phase** — `final-verification` 이 `verdict=accepted` 를 반환한 직후에 실행되는 신규 phase. lead 가 Claude worker (drafter) 를 통해 commit message · PR body 후보를 만들고, `AskUserQuestion` 으로 사용자에게 (1) action (`commit only` / `commit + PR` / `skip`), (2) PR base branch (`staging` / `preprod` / `prod` / `main` / `dev` / 직접 입력), (3) message handling (`use as-is` / `edit then proceed` / `cancel`) 세 가지를 순서대로 묻습니다. 사용자가 메뉴로 선택한 git / gh 명령만 실행되고, force-push, base 브랜치 직접 push, hook bypass (`--no-verify`), release publish (`gh release`, `npm publish`, ...) 는 금지됩니다. 이 phase 에서는 소스 코드를 수정하지 않습니다. profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
+- **PR 본문 템플릿 설정** (release-handoff) — PR 본문은 마크다운 템플릿에서 채워집니다. 해석 우선순위: 1회성 override (`--pr-template-path` 또는 okstra-run Step 6 prompt) → `<project_root>/.project-docs/okstra/project.json` 의 `prTemplatePath` → `~/.okstra/config.json` 의 `prTemplatePath` → 스킬 디폴트 `~/.claude/skills/okstra-run/templates/pr-body.template.md`. 템플릿 등록 명령: `okstra config set pr-template-path <path> [--scope project|global]` (project 스코프는 project root 기준 상대경로 허용, global 스코프는 절대경로 또는 `~/` 시작 경로만 허용). 현재 설정 확인: `okstra config get pr-template-path --scope all` 은 각 스코프 값 + 실제로 우승하는 경로(effective) 까지 보여줍니다. 디폴트 템플릿은 `## Summary` / `## Changes` / `## Test plan` / `## Linked issues` 4 섹션 + HTML 주석으로 lead 작성 가이드를 포함하며, PR 생성 직전에 lead 가 주석을 제거합니다.
+- **프로파일 워커 로스터 검증** — `--workers <csv>` 와 okstra-run Step 6 의 워커 prompt 는 해당 프로파일의 `Required workers:` 블록에 선언된 워커 ID 만 허용합니다. 프로파일에 없는 워커 (예: `release-handoff` 에서 `codex` / `gemini`) 를 요청하면 명확한 에러로 거절되고, 인터랙티브 prompt 도 프로파일이 실제로 받는 워커만 보여줍니다.
 
 ### 3.5 운영 명령
 
@@ -177,6 +179,7 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 | `npx -y okstra@latest ensure-installed` | Idempotent 체크, stale 이면 자동 재설치 (스킬이 내부적으로 호출) |
 | `npx -y okstra@latest setup --project-id <id>` | 현재 프로젝트를 등록 (`.project-docs/okstra/project.json`) |
 | `npx -y okstra@latest check-project` | 현재 프로젝트가 `setup` 으로 등록됐는지 검증 |
+| `npx -y okstra@latest config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | okstra 설정 읽기/쓰기. 현재 지원 키: `pr-template-path` (project.json 또는 `~/.okstra/config.json` 의 `prTemplatePath` 갱신) |
 | `npx -y okstra@latest uninstall` | 런타임 + 스킬 제거; 사용자 데이터(`recent.jsonl`, `projects/`, …)는 보존 |
 | `npx -y okstra@latest uninstall --purge -y` | 사용자 데이터까지 모두 제거 |
 

package/README.md

@@ -166,6 +166,8 @@ Recent workflow additions (post-0.8.0, on `main`):
 
 - **Isolated task worktree for every task-type** — prepare automatically runs `git worktree add ~/.okstra/worktrees/<project>/<group>/<task>/` on a fresh branch `<work-category-prefix>-<task-id-segment>` branched from the **user-chosen base ref** (`--base-ref`, mirroring the `release-handoff` PR-base picker: `main` / `dev` / `staging` / `preprod` / `prod` / any local ref) the first time a task-key is seen. `--base-ref` is required on first phase; the okstra-run skill collects it via `AskUserQuestion`, non-interactive callers must pass the flag explicitly. Every subsequent phase of the same task-key (`requirements-discovery` → `error-analysis` → `implementation-planning` → `implementation`) reuses the same path and branch, so phase N inherits the working-tree state phase N-1 left behind. A global registry at `~/.okstra/worktrees/registry.json` (flock-guarded) reserves task-keys and branches across concurrent runs; all path/branch segments are sanitised (`/`, `:`, etc. → `-`). The worktree is preserved after every run for follow-up phases, PR authoring, and rollback. Skip paths: when the caller is already inside another worktree or `project_root` is not a git repo, provisioning no-ops. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` plus removing the task-key entry from the registry. Details: [`docs/kr/architecture.md`](docs/kr/architecture.md) (*Task type* section) and [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
 - **`release-handoff` lifecycle phase** — runs after `final-verification` returns `verdict=accepted`. The lead drafts a commit message and PR body via a Claude worker, then prompts the user with `AskUserQuestion` for three choices: action (`commit only` / `commit + PR` / `skip`), PR base branch (`staging` / `preprod` / `prod` / `main` / `dev` / free-form), and message handling (`use as-is` / `edit then proceed` / `cancel`). Only user-selected mutating git/gh commands run. Force-push, base-branch direct push, hook bypass (`--no-verify`), and release publishing (`gh release`, `npm publish`, ...) are forbidden. Source code is not edited in this phase. Profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
+- **Configurable PR body template** (release-handoff) — the PR body is filled from a markdown template chosen in priority order: per-run override (`--pr-template-path` or the okstra-run Step 6 prompt) → `<project_root>/.project-docs/okstra/project.json` `prTemplatePath` → `~/.okstra/config.json` `prTemplatePath` → bundled skill default at `~/.claude/skills/okstra-run/templates/pr-body.template.md`. Register a template with `okstra config set pr-template-path <path> [--scope project|global]` (project scope accepts paths relative to the project root; global scope requires absolute or `~/`-prefixed). `okstra config get pr-template-path --scope all` reports every scope plus the effective winner. The bundled default ships `## Summary` / `## Changes` / `## Test plan` / `## Linked issues` with HTML comment guidance that the lead strips before opening the PR.
+- **Profile-roster worker validation** — `--workers <csv>` (and the okstra-run Step 6 worker prompt) are now restricted to the worker IDs declared by the chosen profile's `Required workers:` block. Asking for `codex` / `gemini` on a profile that does not list them (e.g. `release-handoff`) is rejected with a clear error, and the interactive prompt only offers workers the profile actually accepts.
 
 ### 3.5 Ops commands
 
@@ -176,6 +178,7 @@ Recent workflow additions (post-0.8.0, on `main`):
 | `npx -y okstra@latest ensure-installed` | Idempotent check, auto-reinstall if stale (skills call this internally) |
 | `npx -y okstra@latest setup --project-id <id>` | Register the current project (`.project-docs/okstra/project.json`) |
 | `npx -y okstra@latest check-project` | Verify the current project has been registered with `setup` |
+| `npx -y okstra@latest config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | Read / write okstra settings; initial key `pr-template-path` (writes `prTemplatePath` to project.json or `~/.okstra/config.json`) |
 | `npx -y okstra@latest uninstall` | Remove runtime + skills; preserves user data (`recent.jsonl`, `projects/`, …) |
 | `npx -y okstra@latest uninstall --purge -y` | Remove everything including user data |
 

package/bin/okstra

@@ -9,6 +9,7 @@ const COMMANDS = new Map([
   ["doctor", () => import("../src/doctor.mjs").then((m) => m.run)],
   ["setup", () => import("../src/setup.mjs").then((m) => m.run)],
   ["check-project", () => import("../src/check-project.mjs").then((m) => m.run)],
+  ["config", () => import("../src/config.mjs").then((m) => m.run)],
   ["task-list", () => import("../src/task-list.mjs").then((m) => m.run)],
   ["task-show", () => import("../src/task-show.mjs").then((m) => m.run)],
   ["worktree-lookup", () => import("../src/worktree-lookup.mjs").then((m) => m.run)],
@@ -40,6 +41,7 @@ Admin commands:
   setup                  Register the current project (.project-docs/okstra/project.json)
   doctor                 Diagnostic check of the installed runtime
   check-project          Verify the current project has been registered with setup
+  config                 Read / write okstra settings (e.g. PR template path)
   paths                  Print runtime paths (workspace/agents/pythonpath/bin/home/version)
 
 Introspection commands (JSON output, used by skills to avoid python heredocs):

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.23.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.23.0",
+  "builtAt": "2026-05-15T01:56:19.363Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -63,7 +63,9 @@ Before producing any output, you MUST read every input file enumerated in the `[
 
 ## Worker Output Structure
 
-When returning results, organize into the following sections in this exact order:
+When returning results, start the file with a YAML frontmatter block, then organize the body into the following sections in this exact order.
+
+**Frontmatter (mandatory)** — set `workerId: "claude"`. Copy `id`, `aliases`, `taskType`, `task-id`, `task-group`, `project-id`, `date` verbatim from the input files (`analysis-material.md` is canonical; if it lacks any field, record a `tool-failure` and stop). Full schema and a concrete example live in the `okstra-team-contract` skill's "Result Frontmatter" subsection.
 
 0. **Reading Confirmation** - one short line per input file confirming end-to-end reading (e.g. `- Read task-brief.md end-to-end (147 lines).`). If any file was skipped, record a `tool-failure` and do NOT produce sections 1–5.
 1. **Findings** - what you identified

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

@@ -130,7 +130,9 @@ Before producing any output, you MUST ensure the underlying Codex CLI run reads
 
 ## Worker Output Structure
 
-When returning results, organize into the following sections in this exact order:
+When returning results, start the file with a YAML frontmatter block, then organize the body into the following sections in this exact order.
+
+**Frontmatter (mandatory)** — set `workerId: "codex"`. Copy `id`, `aliases`, `taskType`, `task-id`, `task-group`, `project-id`, `date` verbatim from the input files (`analysis-material.md` is canonical; if it lacks any field, record a `tool-failure` and stop). Full schema and a concrete example live in the `okstra-team-contract` skill's "Result Frontmatter" subsection.
 
 0. **Reading Confirmation** - one short line per input file confirming end-to-end reading (e.g. `- Read task-brief.md end-to-end (147 lines).`). If any file was skipped, record a `tool-failure` and do NOT produce sections 1–5.
 1. **Findings** - what Codex identified

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

@@ -130,7 +130,9 @@ Before producing any output, you MUST ensure the underlying Gemini CLI run reads
 
 ## Worker Output Structure
 
-When returning results, organize into the following sections in this exact order:
+When returning results, start the file with a YAML frontmatter block, then organize the body into the following sections in this exact order.
+
+**Frontmatter (mandatory)** — set `workerId: "gemini"`. Copy `id`, `aliases`, `taskType`, `task-id`, `task-group`, `project-id`, `date` verbatim from the input files (`analysis-material.md` is canonical; if it lacks any field, record a `tool-failure` and stop). Full schema and a concrete example live in the `okstra-team-contract` skill's "Result Frontmatter" subsection.
 
 0. **Reading Confirmation** - one short line per input file confirming end-to-end reading (e.g. `- Read task-brief.md end-to-end (147 lines).`). If any file was skipped, record a `tool-failure` and do NOT produce sections 1–5.
 1. **Findings** - what Gemini identified

package/runtime/agents/workers/report-writer-worker.md

@@ -81,9 +81,22 @@ The validator (`validators/validate-run.py`) checks this file exists whenever th
 
 The lead's prompt provides this path as a second result destination — extract it from the `**Worker Result Path:**` line (or, if absent, derive it as `runs/<task-type>/worker-results/report-writer-worker-<task-type>-<seq>.md` under `Project Root`).
 
-The worker-results file must begin with the standard header from `okstra-team-contract`:
+The worker-results file MUST begin with a YAML frontmatter block (set `workerId: "report-writer"`; copy `id`, `aliases`, `taskType`, `task-id`, `task-group`, `project-id`, `date` verbatim from `analysis-material.md` — full schema lives in the `okstra-team-contract` "Result Frontmatter" subsection), followed by the standard header:
 
 ```markdown
+---
+title: OKSTRA Report Writer Worker Result - <task-key>
+id: "<task-key with ':' replaced by '-'>"
+aliases: ["<id>-<task-type>"]
+tags: ["obsidian", "okstra", "worker-result", "<task-type>"]
+taskType: "<task-type>"
+workerId: "report-writer"
+task-id: "<task-id>"
+task-group: "<task-group>"
+project-id: "<project-id>"
+date: <YYYY-MM-DD>
+---
+
 # Report Writer Worker Analysis — <task-key>
 
 **Task:** <task-type>
@@ -92,6 +105,8 @@ The worker-results file must begin with the standard header from `okstra-team-co
 **Model:** Report writer worker, opus
 ```
 
+The same frontmatter (with `workerId: "report-writer"`) MUST also appear on the final-report file you assemble — the `final-report.template.md` already encodes it, so simply preserve the template's frontmatter block when filling sections.
+
 Followed by a short body that:
 1. Names the canonical final-report file path written by this worker (relative to project root).
 2. Lists the input artifacts you reconciled (each analysis worker's result file path under `worker-results/`, plus the convergence-state file path if present).

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

@@ -28,17 +28,28 @@
      - `main`
      - `직접 입력` (free-form branch name; lead validates the name exists on origin via `git ls-remote --heads origin <name>` and re-asks on failure)
      The chosen base MUST NOT equal the feature branch. If it does, re-ask.
+  2b. **Pre-merge conflict probe** (only when the user picked `push + PR`) — before the push/PR step, the lead MUST refresh the base ref and probe for merge conflicts against it:
+     - run `git fetch origin <chosen-base>` (read-only on the local working tree).
+     - run `git merge-tree --write-tree --merge-base origin/<chosen-base> HEAD origin/<chosen-base>`. A non-zero exit code OR conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) in the output indicate a merge conflict against the chosen base.
+     - If no conflict is detected, proceed silently to Q3 (do NOT add a confirmation prompt — keep the happy path frictionless).
+     - If a conflict IS detected, present the conflicting paths (parsed from the `merge-tree` output) and capture exactly one:
+       - `proceed anyway` — continue to Q3; the PR will be opened with conflicts and the final report MUST flag this in `Merge Conflict Probe`.
+       - `change base branch` — return to Q2 and re-ask the base selection.
+       - `cancel` — end the run without push or PR; record the cancellation in the final report.
+     - The probe is read-only. It MUST NOT run `git merge`, `git rebase`, `git pull`, or any command that mutates the working tree or local refs.
   3. **PR title + PR body confirmation** — show the lead's inline draft verbatim and capture one of:
      - `use as-is` — proceed with the drafted text.
      - `edit then proceed` — accept inline edits from the user, then proceed with the edited text.
      - `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>`.
+  - merge-conflict probe (only when the user picked `push + PR`): `git fetch origin <chosen-base>` and `git merge-tree --write-tree --merge-base origin/<chosen-base> HEAD origin/<chosen-base>`. Both are non-mutating with respect to the working tree.
   - 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.
   - PR creation (only when the user picked `push + PR` AND no PR with the same head already exists on origin): `gh pr create --base <chosen-base> --head <current-branch> --title "<title>" --body "<body>"`. The title and body are the user-confirmed PR draft.
   - PR reuse: if `gh pr list --head <branch> --state open --json url --jq '.[0].url'` returns a URL, treat that PR as already existing — record the URL in the final report and SKIP `gh pr create`.
@@ -64,9 +75,14 @@
   - **User Selections**: a block recording each prompt and the user's verbatim answer.
     - Q1 action: `local only` | `push + PR` | `skip`.
     - Q2 PR base (if applicable): the chosen branch and how it was selected (menu pick vs free-form input).
+    - Q2b merge-conflict probe (if applicable): `clean` (no conflict, no prompt shown) | `proceed anyway` | `change base branch` | `cancel`. When a conflict was detected, list the conflicting paths.
     - Q3 title/body: `use as-is` | `edit then proceed` (with a diff between the lead's draft and the final text) | `cancel`.
   - **Executed Commands**: every git / gh command the lead actually ran, with its exit code and a one-line stdout/stderr summary. Read-only inspection commands MAY be summarised; mutating commands MUST be listed verbatim.
   - **Commit List**: each existing implementation commit in `git log <base>..HEAD`, with short/full SHA, subject line, and touched files. Release-handoff MUST NOT create new commits.
+  - **Merge Conflict Probe**: one of
+    - `- Not run (user picked local only or skip).`
+    - `- Clean — no conflicts against <base> at <origin/base SHA>.`
+    - `- Conflicts detected against <base> at <origin/base SHA>; user chose <proceed anyway | change base branch | cancel>. Conflicting paths: <list>.`
   - **Pull Request Outcome**: one of
     - `- No PR action requested.` (user picked `local only` or `skip`)
     - `- PR created: <url>` with title and base branch
@@ -79,6 +95,7 @@
   3. **Forbidden-action audit** — scan the run's session transcripts (`git`, `gh` invocations) for every entry in the Forbidden actions list above. Any occurrence means the run has crossed into unsafe territory and MUST be flagged as `contract-violated`.
   4. **Push-target audit** — for every `git push` recorded, confirm the refspec resolves to the feature branch, not the base branch.
   5. **Idempotency check** — if a PR with the same head already existed at run start, confirm the report records `PR reused` rather than a fresh `gh pr create` invocation.
+  6. **Merge-conflict probe audit** — for any `push + PR` run, confirm the report's `Merge Conflict Probe` section is present and either records `Clean` or records `Conflicts detected` with the user's verbatim choice. A missing or unparseable probe entry on a `push + PR` run is a contract violation.
 - Non-goals:
   - re-litigating the final-verification verdict — release-handoff trusts the cited `accepted` verdict and does not reopen acceptance checks.
   - creating, amending, squashing, or rewriting commits. Commit production belongs to `implementation`.

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

@@ -96,6 +96,16 @@ def _doc_type_from_template_path(template_path: str) -> str:
     return stem
 
 
+def _frontmatter_id_from_task_key(task_key: str) -> str:
+    """task_key (`project_id:task_group:task_id`) 를 ID 형식으로 변환.
+
+    `:` 를 `-` 로 치환한 단일 문자열. 예시:
+        ``fontsninja-classifier-v2:DEV-9388:DEV-9429``
+        -> ``fontsninja-classifier-v2-DEV-9388-DEV-9429``
+    """
+    return (task_key or "").strip().replace(":", "-")
+
+
 def _frontmatter_mapping(ctx: dict) -> dict:
     task_id = (ctx.get("TASK_ID") or "").strip()
     project_id = (ctx.get("PROJECT_ID") or "").strip()
@@ -103,15 +113,28 @@ def _frontmatter_mapping(ctx: dict) -> dict:
     task_key = (ctx.get("TASK_KEY") or "").strip()
     task_date = (ctx.get("TASK_DATE") or "").strip()
     doc_type = (ctx.get("DOC_TYPE") or "").strip()
+    # task_type 은 ctx 키가 두 곳에 분포 — 직접 키(`TASK_TYPE`), 또는
+    # `ANALYSIS_TYPE` fallback (workflow 의 render mapping 과 동일 우선순위).
+    task_type = (ctx.get("TASK_TYPE") or ctx.get("ANALYSIS_TYPE") or "").strip()
+
+    fm_id = _frontmatter_id_from_task_key(task_key)
+    fm_id_scalar = f'"{fm_id}"' if fm_id else f'"{_FM_DEFAULT}"'
+    alias_value = f"{fm_id}-{task_type}" if (fm_id and task_type) else fm_id
     return {
         "{{TASK_KEY}}": _fm_scalar(task_key),
         "{{TASK_ID}}": _fm_scalar(task_id),
         "{{PROJECT_ID}}": _fm_scalar(project_id),
         "{{TASK_GROUP}}": _fm_scalar(task_group),
         "{{TASK_DATE}}": _fm_scalar(task_date),
-        "{{FM_ID}}": _fm_array([task_id, project_id, task_group]),
-        "{{FM_ALIASES}}": _fm_array([task_id, project_id, task_group]),
+        # task_key 의 `:` 를 `-` 로 치환한 단일 스칼라.
+        # 예: "fontsninja-classifier-v2-DEV-9388-DEV-9429"
+        "{{FM_ID}}": fm_id_scalar,
+        # id 와 task-type 을 `-` 로 연결한 단일 alias 를 array 한 칸에 담는다
+        # (Obsidian aliases 컨벤션).
+        "{{FM_ALIASES}}": _fm_array([alias_value]) if alias_value else "[]",
         "{{FM_TAGS}}": _fm_tags(doc_type),
+        # 신규: 모든 okstra 산출물의 frontmatter 가 task type 을 명시한다.
+        "{{FM_TASK_TYPE}}": _fm_scalar(task_type),
     }
 
 
@@ -694,6 +717,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 +931,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 +1186,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", ""),