okstra 0.21.1 → 0.23.0

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

@@ -20,6 +20,16 @@ Launch an okstra task — gather inputs interactively, render the full task bund
 - User wants status only — use `okstra-status`.
 - User wants past runs — use `okstra-history`.
 
+## Prompt convention (use the right tool for the right input shape)
+
+`AskUserQuestion` always renders a picker UI with a forced auto-attached `Other` option. While the user types into `Other`, the picker re-renders and the experience feels out of sync. So:
+
+- **Use `AskUserQuestion` ONLY when the answer is a fixed pick from a short option set** (2–4 distinct, mutually exclusive choices). Examples in this skill: task-type choice (Step 4), executor provider (claude/codex/gemini), model picker (default/opus/sonnet/haiku per provider), Use defaults vs Customize, Proceed vs Edit confirmation.
+- **For pure free-text inputs** (file paths, task identifiers, CSV strings, free directives, branch names typed by the user) **do NOT use `AskUserQuestion`**. Instead, write a plain text message (e.g. `"Task group (예: backend-api, INV-1234)을 알려주세요. 빈 줄이면 취소."`) and consume the user's NEXT message as the answer. Then validate and re-prompt with another plain text message on failure.
+- **For "menu + free-text" places** (base-ref pickers, PR base branch) — show the menu with `AskUserQuestion` listing only the canonical options + a literal option labeled `직접 입력`. When the user picks `직접 입력`, follow up with a **separate** plain text prompt and consume the next user message. Do NOT rely on `Other` auto-text inside the picker — its re-render is the root cause of the lag.
+
+Echo each captured answer on one short line (e.g. `task-group: backend-api`) so the user sees what was registered, regardless of which prompt shape was used.
+
 ## Authority Files (disk-only — no env var caching for per-run identity)
 
 Every step reads disk afresh. The `OKSTRA_*` env vars below identify the
@@ -82,7 +92,7 @@ okstra check-project --cwd "$(pwd)"
 ```
 
 - If `ok: true`: read `projectRoot` and `projectId` from the JSON.
-- If `ok: false`: ask the user (`AskUserQuestion`, free text) for an absolute project-root path; rerun with `okstra check-project --cwd <their input>`.
+- If `ok: false`: ask the user with a **plain text prompt** (not `AskUserQuestion` — this is pure free text per the convention above) for an absolute project-root path; rerun with `okstra check-project --cwd <their input>`. Re-prompt with another plain text message on failure.
 
 ## Step 2: Choose task — existing vs new
 
@@ -103,12 +113,12 @@ For an existing pick, read its `task-manifest.json` to capture `taskType` and `w
 
 Skip if continuing existing.
 
-`AskUserQuestion` (free text, one at a time):
+Use **plain text prompts** (one at a time — write the message and consume the user's next reply; do NOT use `AskUserQuestion` for these per the convention above):
 
-1. `"Task group (e.g. backend-api, INV-1234, refactor)"` → `task_group`
-2. `"Task id (e.g. login-error-analysis, dev-9043)"` → `task_id`
+1. `"Task group 을 알려주세요 (예: backend-api, INV-1234, refactor)"` → `task_group`
+2. `"Task id 를 알려주세요 (예: login-error-analysis, dev-9043)"` → `task_id`
 
-Validate that slugified `task_group` and `task_id` each contain at least one alphanumeric character. Re-ask if not.
+Validate that slugified `task_group` and `task_id` each contain at least one alphanumeric character. On failure, re-prompt with another plain text message stating the validation failure.
 
 ## Step 4: Choose task-type
 
@@ -125,9 +135,9 @@ Validate that slugified `task_group` and `task_id` each contain at least one alp
 
 For existing tasks, present `nextRecommendedPhase` as the first option (recommended default).
 
-If `implementation` chosen, ask two more `AskUserQuestion` in order:
-- `"Path to the approved final-report.md (must contain APPROVED marker)"` — the underlying python `prepare_task_bundle` re-validates the marker, but you can pre-check with `grep`.
-- `"Executor provider for this run (claude | codex | gemini)?"` — only this provider mutates project files; the other two run as read-only verifiers. Default `claude` (or `OKSTRA_DEFAULT_EXECUTOR` if set). Pass the answer through `PrepareInputs.executor`.
+If `implementation` chosen, ask two more questions in order:
+- **Plain text prompt** (file path is pure free text): `"approved final-report.md 의 경로를 알려주세요 (APPROVED 마커가 있어야 합니다)"`. The underlying python `prepare_task_bundle` re-validates the marker, but you can pre-check with `grep`. Re-prompt with plain text on failure.
+- **`AskUserQuestion`** with three options (`claude` / `codex` / `gemini`) — only this provider mutates project files; the other two run as read-only verifiers. Default `claude` (or `OKSTRA_DEFAULT_EXECUTOR` if set). Pass the answer through `PrepareInputs.executor`.
 
 ## Step 4.6: Base ref for the task worktree (first phase only)
 
@@ -149,16 +159,17 @@ non-null `entry` with `status: "active"` → **REUSE**.
   question (the registered base is authoritative).
 - `ASK` → this is the first phase for this task-key. Continue.
 
-`AskUserQuestion` (mirrors the `release-handoff` PR-base picker):
+Use the **menu + free-text two-step pattern** (per the convention above):
 
-- **Label**: `"이 task worktree 의 base branch?"`
-- **Options** (single-select):
-  1. `main` (recommended)
-  2. `dev`
-  3. `staging`
-  4. `preprod`
-  5. `prod`
-  6. Free text — let the user type any local ref (branch, tag, or full/short SHA).
+1. `AskUserQuestion` with label `"이 task worktree 의 base branch?"` and exactly these single-select options (NO auto-Other typing — the literal `직접 입력` option is the typed-input escape hatch):
+   1. `main` (recommended)
+   2. `dev`
+   3. `staging`
+   4. `preprod`
+   5. `prod`
+   6. `직접 입력`
+2. If the user picks `직접 입력`, follow up with a **plain text prompt**: `"base ref 를 입력해주세요 (branch, tag, 또는 short/full SHA)"`. Consume the user's next message as the chosen ref.
+3. Otherwise the picked option label is the chosen ref directly.
 
 Validate the chosen ref exists in the MAIN worktree before continuing:
 
@@ -168,14 +179,15 @@ git -C "$(git -C "$PROJECT_ROOT" rev-parse --path-format=absolute --git-common-d
   || { echo "ref not found locally: <chosen-ref>"; exit 1; }
 ```
 
-Re-ask on failure. Echo the resolved short SHA back to the user
-(`base 확정: <ref> (<short-sha>)`) and capture `base_ref=<chosen-ref>` for
-Step 7.
+On failure, re-prompt with a plain text message (or return to step 1's
+menu if the user wants to pick a different canonical branch). Echo the
+resolved short SHA back to the user (`base 확정: <ref> (<short-sha>)`)
+and capture `base_ref=<chosen-ref>` for Step 7.
 
 ## Step 5: Brief path
 
-- New task: `AskUserQuestion` (free text) `"Path to the task brief markdown (relative to project root)"`. Verify file exists; re-ask on failure.
-- Existing task: default to the manifest's `taskBriefPath`. Show it; ask whether to keep or change.
+- New task: **plain text prompt** (file path is pure free text per the convention) `"task brief markdown 의 경로를 알려주세요 (project root 기준 상대경로 또는 절대경로)"`. Consume the user's next message; verify the file exists; on failure, re-prompt with another plain text message.
+- Existing task: default to the manifest's `taskBriefPath`. Show it; ask `AskUserQuestion` `"기존 경로를 유지할까요?"` with options `유지` / `변경`. On `변경`, follow up with a plain text prompt for the new path.
 
 ## Step 6 (optional): Directive / workers / models / related / clarification
 
@@ -201,26 +213,49 @@ In this phase the roster is fixed by the profile (executor + two verifiers + rep
 1. `AskUserQuestion` `"리더(Claude lead) 모델?"` (Claude options) → `lead_model`
 2. `AskUserQuestion` `"실행자({executor-provider}) 모델?"` with options matching the executor's provider (Claude / Codex / Gemini list above) → maps to `claude_model` / `codex_model` / `gemini_model`. The other two provider model fields stay empty (verifiers use defaults).
 3. `AskUserQuestion` `"리포트 작성자(report-writer) 모델?"` (Claude options) → `report_writer_model`
-4. `AskUserQuestion` `"추가 directive (선택, 빈 칸 가능)"` (free text) → `directive`
-5. `AskUserQuestion` `"관련 task id 목록, 쉼표 구분 (선택, 빈 칸 가능)"` (free text) → `related_tasks_raw`
+4. **Plain text prompt** (free text) `"추가 directive 가 있으면 적어주세요 (없으면 빈 줄)"` → `directive`. Consume the user's next message verbatim; an empty line means "no directive".
+5. **Plain text prompt** (free text) `"관련 task id 목록을 쉼표로 구분해서 적어주세요 (없으면 빈 줄)"` → `related_tasks_raw`.
 
 Do NOT ask for `workers_override` in implementation — the profile's required roster must be preserved (verifier slots are mandatory). Leave `workers_override=""`.
 
 ### 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:**
+
+```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 fixed option lists above. **All other prompts use plain text messages** (do NOT wrap free-text inputs in `AskUserQuestion` — the auto-Other re-render lag is what we're avoiding). Skip any worker-model prompt whose worker is not in `profile_workers`.
 
-1. `AskUserQuestion` `"참여 워커 목록 (쉼표 구분, 빈 칸 = 프로필 기본값 claude,codex,report-writer). 선택지: claude, codex, gemini, report-writer — gemini는 옵션이므로 필요할 때 명시"` (free text) → `workers_override`
+1. (only when `profile_workers` is non-empty) **Plain text prompt** `"참여 워커 목록을 쉼표로 구분해서 적어주세요. 빈 줄이면 프로필 기본값 <profile_workers_csv> 을 그대로 씁니다. 사용 가능한 워커: <profile_workers_csv>"` → `workers_override`. Validate the answer is a subset of `profile_workers`; on failure, re-prompt with another plain text message. (Backend also rejects 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"`) **Plain text prompt** `"PR 본문 템플릿 경로 1회성 override (빈 줄이면 project.json → ~/.okstra/config.json → 스킬 디폴트 순으로 자동 해석)"` → `pr_template_path`. The backend (`okstra_ctl.pr_template.resolve_pr_template_path`) validates the file exists and surfaces `PrTemplateError` on failure.
+    - **Persist follow-up** (only when the user typed a non-empty path AND it differs from any currently-registered project/global value): ask `AskUserQuestion` `"방금 입력한 경로를 영구 저장할까요?"` with three options:
+      1. `이번 run 만 (1회성)` — proceed with the override; do NOT touch project.json or global config.
+      2. `프로젝트에 저장 (project scope)` — run `okstra config set pr-template-path "<path>" --scope project` and use the override for this run too.
+      3. `전역에 저장 (global scope)` — run `okstra config set pr-template-path "<path>" --scope global` (must be absolute or `~/`-prefixed; if not, re-ask with a plain text prompt for an absolute version) and use the override for this run too.
+    - Skip the persist follow-up entirely when the user left the override blank, or when the typed value matches the value already stored at the scope it would land in (avoid no-op confirmations).
 
-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 +302,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/skills/okstra-setup/SKILL.md

@@ -209,6 +209,43 @@ To opt out (advanced): replace the symlink with a regular file. okstra
 will detect that it is no longer a symlink on its next setup call and
 back it up as `.bak.<timestamp>` rather than overwriting silently.
 
+## Step 4.8 (optional): register a project PR body template
+
+`release-handoff` fills the PR body from a template. By default it uses the
+bundled skill template at
+`~/.claude/skills/okstra-run/templates/pr-body.template.md`. Most projects
+want their own — e.g. the repo's `.github/PULL_REQUEST_TEMPLATE.md` — to
+keep PRs consistent with what the team already merges manually.
+
+Ask the user with `AskUserQuestion` (fixed options, NOT free text — file
+path entry happens in the follow-up plain text prompt per the
+okstra-run prompt convention):
+
+- **Question**: `"이 프로젝트에서 release-handoff 가 사용할 PR 본문 템플릿을 등록할까요?"`
+- **Options**:
+  1. `이번 프로젝트만 (project scope)` — write to `<PROJECT_ROOT>/.project-docs/okstra/project.json` `prTemplatePath`.
+  2. `전역 (global scope)` — write to `~/.okstra/config.json` `prTemplatePath`.
+  3. `나중에` — skip.
+
+If the user picks scope 1 or 2, follow up with a **plain text prompt**:
+`"PR 본문 템플릿 파일 경로를 알려주세요. project 스코프는 project-root 기준 상대경로 또는 절대경로, global 스코프는 절대경로 또는 ~/ 시작 경로만 허용됩니다."` Consume the next user message, then run:
+
+```bash
+okstra config set pr-template-path "<typed-path>" --scope <project|global>
+```
+
+The command validates the value (global rejects relative paths) and
+writes atomically. Surface its stdout JSON so the user sees which file
+was updated.
+
+If the user chose `나중에`, tell them they can register later with one of:
+
+- `okstra config set pr-template-path <path> --scope project|global` from a
+  terminal, or
+- the per-run 1회성 override prompt during the next release-handoff run
+  (the run can also persist that override to project/global scope on the
+  spot — see the okstra-run skill).
+
 ## Step 5: Verify
 
 ```bash

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -202,7 +202,52 @@ Terminal statuses that can be recorded for a worker:
 
 **Authoritative source.** If other documents (SKILL.md, worker agent definitions) disagree with this section, this section wins.
 
-A successful worker result must include the following sections in this exact order:
+### Result Frontmatter (mandatory, precedes Section 0)
+
+Every worker result file MUST begin with a YAML frontmatter block. The values are sourced from the corresponding fields of the input files' frontmatter (e.g. `analysis-material.md`, `task-brief.md`) — copy them verbatim; do NOT regenerate them. Only `workerId` and `title` are worker-specific.
+
+```yaml
+---
+title: OKSTRA <Worker Role> Result - <task-key>
+id: "<task-key with ':' replaced by '-'>"
+aliases: ["<id>-<task-type>"]
+tags: ["obsidian", "okstra", "worker-result", "<task-type>"]
+taskType: "<task-type>"
+workerId: "<claude|codex|gemini|report-writer>"
+task-id: "<task-id>"
+task-group: "<task-group>"
+project-id: "<project-id>"
+date: <YYYY-MM-DD>
+---
+```
+
+Concrete example for a `claude-worker` result on task-key `fontsninja-classifier-v2:DEV-9388:DEV-9429` and task-type `implementation`:
+
+```yaml
+---
+title: OKSTRA Claude Worker Result - fontsninja-classifier-v2:DEV-9388:DEV-9429
+id: "fontsninja-classifier-v2-DEV-9388-DEV-9429"
+aliases: ["fontsninja-classifier-v2-DEV-9388-DEV-9429-implementation"]
+tags: ["obsidian", "okstra", "worker-result", "implementation"]
+taskType: "implementation"
+workerId: "claude"
+task-id: "DEV-9429"
+task-group: "DEV-9388"
+project-id: "fontsninja-classifier-v2"
+date: 2026-05-15
+---
+```
+
+Rules:
+- `id` is the run's `task-key` with `:` replaced by `-`. It is a scalar string, NOT an array.
+- `aliases` is a YAML array containing a single value `"<id>-<task-type>"`.
+- `taskType` mirrors the run's task type (`requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`).
+- `workerId` identifies which worker produced the file. Required values: `claude` / `codex` / `gemini` / `report-writer`.
+- Other fields (`task-id`, `task-group`, `project-id`, `date`) MUST match the input files' frontmatter exactly. If the input frontmatter is missing or unreadable, the worker MUST record a `tool-failure` and stop instead of guessing.
+
+The same frontmatter contract applies to the `Report writer worker`'s final-report file — the report-writer copies these values from its inputs and only swaps `workerId` to `report-writer`.
+
+A successful worker result must include the following sections in this exact order, beneath the frontmatter block:
 
 0. **Reading Confirmation** — one short line per input file (`task-brief.md`, `analysis-profile.md`, `analysis-material.md` if present, `reference-expectations.md`, `clarification-response.md` if a carry-in was provided, `final-report-template.md`) stating that the worker read it end-to-end. Each line takes the form `- Read <file-name> end-to-end (<line-count> lines).`. If a file was skipped or only partially read, the worker MUST NOT produce sections 1–5; instead it records a `tool-failure` in the errors sidecar and stops. This section exists specifically to counteract the common failure mode where workers skim long inputs because they share structure with the file the run will eventually write into.
 1. Findings

package/runtime/templates/prd/brief.template.md

@@ -8,6 +8,7 @@ date: {{TASK_DATE}}
 task-id: "{{TASK_ID}}"
 task-group: "{{TASK_GROUP}}"
 project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
 ---
 
 # OKSTRA Task Brief

package/runtime/templates/project-docs/task-index.template.md

@@ -8,6 +8,7 @@ date: {{TASK_DATE}}
 task-id: "{{TASK_ID}}"
 task-group: "{{TASK_GROUP}}"
 project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
 ---
 
 # OKSTRA Task Summary

package/runtime/templates/reports/error-analysis-input.template.md

@@ -8,6 +8,7 @@ date: {{TASK_DATE}}
 task-id: "{{TASK_ID}}"
 task-group: "{{TASK_GROUP}}"
 project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
 ---
 
 # OKSTRA Error Analysis Input

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

@@ -8,6 +8,7 @@ date: {{TASK_DATE}}
 task-id: "{{TASK_ID}}"
 task-group: "{{TASK_GROUP}}"
 project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
 ---
 
 # {{TASK_KEY}} - Multi-Agent Cross Verification Final Report
@@ -16,6 +17,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/final-verification-input.template.md

@@ -8,6 +8,7 @@ date: {{TASK_DATE}}
 task-id: "{{TASK_ID}}"
 task-group: "{{TASK_GROUP}}"
 project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
 ---
 
 # OKSTRA Final Verification Input

package/runtime/templates/reports/implementation-input.template.md

@@ -8,6 +8,7 @@ date: {{TASK_DATE}}
 task-id: "{{TASK_ID}}"
 task-group: "{{TASK_GROUP}}"
 project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
 ---
 
 # OKSTRA Implementation Input

package/runtime/templates/reports/implementation-planning-input.template.md

@@ -8,6 +8,7 @@ date: {{TASK_DATE}}
 task-id: "{{TASK_ID}}"
 task-group: "{{TASK_GROUP}}"
 project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
 ---
 
 # OKSTRA Implementation Planning Input

package/runtime/templates/reports/quick-input.template.md

@@ -8,6 +8,7 @@ date: {{TASK_DATE}}
 task-id: "{{TASK_ID}}"
 task-group: "{{TASK_GROUP}}"
 project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
 ---
 
 # OKSTRA Quick Input

package/runtime/templates/reports/release-handoff-input.template.md

@@ -8,6 +8,7 @@ date: {{TASK_DATE}}
 task-id: "{{TASK_ID}}"
 task-group: "{{TASK_GROUP}}"
 project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
 ---
 
 # OKSTRA Release Handoff Input

package/runtime/templates/reports/schedule.template.md

@@ -8,6 +8,7 @@ date: {{TASK_DATE}}
 task-id: "{{TASK_ID}}"
 task-group: "{{TASK_GROUP}}"
 project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
 ---
 
 # <Title> — Work Schedule

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/runtime/templates/reports/task-brief.template.md

@@ -8,6 +8,7 @@ date: {{TASK_DATE}}
 task-id: "{{TASK_ID}}"
 task-group: "{{TASK_GROUP}}"
 project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
 ---
 
 # OKSTRA Task Brief