okstra 0.22.0 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.22.0",
+  "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.22.0",
-  "builtAt": "2026-05-14T15:54:01.726Z",
+  "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/prompts/profiles/release-handoff.md

@@ -28,6 +28,15 @@
      - `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.
@@ -40,6 +49,7 @@
     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`.
@@ -65,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
@@ -80,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/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),
     }
 
 

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,8 +213,8 @@ 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=""`.
 
@@ -225,9 +237,9 @@ workers outside this list. Special cases:
 - 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`.
+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. (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`.)
+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. (only if `claude` ∈ resolved workers) `AskUserQuestion` `"claude 워커 모델?"` (Claude options) → `claude_model`
 4. (only if `codex` ∈ resolved workers) `AskUserQuestion` `"codex 워커 모델?"` (Codex options) → `codex_model`
@@ -236,7 +248,12 @@ Ask each in turn (model prompts use `AskUserQuestion` with the option lists abov
 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).
+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), present a single confirmation line such as `gemini-model 생략 (workers에 gemini 없음)` so the user can see why the question was skipped.
 

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

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/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

package/src/config.mjs

@@ -0,0 +1,392 @@
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve, isAbsolute } from "node:path";
+import { spawn } from "node:child_process";
+import { resolvePaths } from "./paths.mjs";
+
+const USAGE = `okstra config — read / write okstra settings (project + global scopes)
+
+Settings are persisted as JSON keys in one of two files:
+  project: <project-root>/.project-docs/okstra/project.json
+  global:  ~/.okstra/config.json
+
+Supported keys (CLI alias -> JSON field):
+  pr-template-path   -> prTemplatePath
+                       PR body template used by the release-handoff phase.
+                       Path may be absolute, ~/-prefixed, or (project scope
+                       only) relative to <project-root>.
+
+Usage:
+  okstra config get <key> [--scope project|global|all]
+      Print the value at the requested scope.
+      'all' prints every scope, plus the effective resolved value where
+      available (for pr-template-path the resolver may fall back to the
+      bundled skill default).
+
+  okstra config set <key> <value> [--scope project|global]
+      Write the value. Scope is required unless cwd is inside an okstra
+      project (then defaults to 'project'). Global scope only accepts
+      absolute or ~/-prefixed paths.
+
+  okstra config unset <key> [--scope project|global]
+      Remove the key from the chosen scope.
+
+  okstra config show [--scope project|global|all]
+      Dump every okstra-managed key from the chosen scope as JSON.
+
+Common options:
+  --cwd <dir>           Search starting point for project root (default: pwd)
+  --json                Force JSON output for get/show (default for show)
+  --quiet               Suppress informational stdout on set/unset; exit
+                        code alone reports success
+`;
+
+// CLI-key -> { jsonField, scopes, validate }
+// validate(value, ctx) returns null on success or an error string.
+const KEYS = {
+  "pr-template-path": {
+    jsonField: "prTemplatePath",
+    scopes: ["project", "global"],
+    validate(value, ctx) {
+      if (typeof value !== "string" || value.trim() === "") {
+        return "value must be a non-empty path";
+      }
+      const v = value.trim();
+      if (ctx.scope === "global") {
+        if (!v.startsWith("~/") && !v.startsWith("~\\") && !isAbsolute(v)) {
+          return (
+            "global scope requires an absolute path or '~/'-prefixed path " +
+            `(got ${JSON.stringify(v)}). Use --scope project for project-root-relative paths.`
+          );
+        }
+      }
+      return null;
+    },
+  },
+};
+
+function parseArgs(args) {
+  const opts = {
+    op: null,
+    key: null,
+    value: null,
+    scope: null,
+    cwd: process.cwd(),
+    json: false,
+    quiet: false,
+  };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--scope") {
+      const next = args[i + 1];
+      if (!next) throw new Error("--scope requires a value (project|global|all)");
+      opts.scope = next;
+      i++;
+    } else if (a === "--cwd") {
+      const next = args[i + 1];
+      if (!next) throw new Error("--cwd requires a path");
+      opts.cwd = next;
+      i++;
+    } else if (a === "--json") {
+      opts.json = true;
+    } else if (a === "--quiet" || a === "-q") {
+      opts.quiet = true;
+    } else if (a.startsWith("--")) {
+      throw new Error(`unknown flag ${a}`);
+    } else {
+      positional.push(a);
+    }
+  }
+  opts.op = positional[0] ?? null;
+  opts.key = positional[1] ?? null;
+  opts.value = positional[2] ?? null;
+  return opts;
+}
+
+function okstraHome() {
+  const override = (process.env.OKSTRA_HOME || "").trim();
+  return override !== "" ? override : join(homedir(), ".okstra");
+}
+
+function globalConfigPath() {
+  return join(okstraHome(), "config.json");
+}
+
+function projectConfigPath(projectRoot) {
+  return join(projectRoot, ".project-docs", "okstra", "project.json");
+}
+
+async function fileExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJson(p) {
+  if (!(await fileExists(p))) return null;
+  const text = await fs.readFile(p, "utf8");
+  try {
+    const data = JSON.parse(text);
+    return typeof data === "object" && data !== null ? data : {};
+  } catch (err) {
+    throw new Error(`failed to parse ${p}: ${err.message}`);
+  }
+}
+
+async function writeJsonAtomic(p, data) {
+  await fs.mkdir(dirname(p), { recursive: true });
+  const tmp = `${p}.tmp.${process.pid}`;
+  await fs.writeFile(tmp, JSON.stringify(data, null, 2) + "\n", "utf8");
+  await fs.rename(tmp, p);
+}
+
+function spawnCapture(cmd, args, env) {
+  return new Promise((resolveProc) => {
+    const child = spawn(cmd, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, ...env },
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (b) => (stdout += b.toString()));
+    child.stderr.on("data", (b) => (stderr += b.toString()));
+    child.on("error", (err) => resolveProc({ code: -1, stdout, stderr: err.message }));
+    child.on("close", (code) => resolveProc({ code, stdout, stderr }));
+  });
+}
+
+async function resolveProjectRoot(cwd) {
+  const paths = await resolvePaths();
+  const result = await spawnCapture(
+    "python3",
+    [
+      "-c",
+      [
+        "import sys",
+        "from okstra_project import resolve_project_root, ResolverError",
+        "try:",
+        "    print(resolve_project_root(explicit_root='', cwd=sys.argv[1]))",
+        "except ResolverError as e:",
+        "    sys.stderr.write(str(e)+'\\n'); sys.exit(2)",
+      ].join("\n"),
+      cwd,
+    ],
+    { PYTHONPATH: paths.pythonpath },
+  );
+  if (result.code === 0) return result.stdout.trim();
+  return null;
+}
+
+function emit(opts, payload) {
+  if (opts.quiet) return;
+  if (opts.json || typeof payload !== "string") {
+    process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+  } else {
+    process.stdout.write(`${payload}\n`);
+  }
+}
+
+async function effectivePrTemplatePath(projectRoot) {
+  // Mirror the python resolver order without depending on it for the simple
+  // case where we just want to surface the chain in 'config get --scope all'.
+  // Python remains the source of truth at run time; this is informational.
+  const paths = await resolvePaths();
+  const result = await spawnCapture(
+    "python3",
+    [
+      "-c",
+      [
+        "import json, sys",
+        "from pathlib import Path",
+        "from okstra_ctl.pr_template import resolve_pr_template_path, PrTemplateError",
+        "try:",
+        "    r = resolve_pr_template_path(Path(sys.argv[1]))",
+        "    print(json.dumps({'ok': True, 'path': str(r.path), 'source': r.source}))",
+        "except PrTemplateError as e:",
+        "    print(json.dumps({'ok': False, 'reason': str(e)}))",
+      ].join("\n"),
+      projectRoot ?? process.cwd(),
+    ],
+    { PYTHONPATH: paths.pythonpath },
+  );
+  if (result.code !== 0) return null;
+  try {
+    return JSON.parse(result.stdout.trim());
+  } catch {
+    return null;
+  }
+}
+
+async function opGet(opts) {
+  const spec = KEYS[opts.key];
+  const scope = opts.scope ?? "all";
+  const projectRoot = await resolveProjectRoot(opts.cwd);
+
+  const out = {};
+  if (scope === "project" || scope === "all") {
+    if (!projectRoot) {
+      out.project = { available: false, reason: "cwd not inside an okstra project" };
+    } else {
+      const cfg = (await readJson(projectConfigPath(projectRoot))) ?? {};
+      out.project = {
+        available: true,
+        path: projectConfigPath(projectRoot),
+        value: cfg[spec.jsonField] ?? null,
+      };
+    }
+  }
+  if (scope === "global" || scope === "all") {
+    const cfg = (await readJson(globalConfigPath())) ?? {};
+    out.global = {
+      available: true,
+      path: globalConfigPath(),
+      value: cfg[spec.jsonField] ?? null,
+    };
+  }
+
+  if (scope === "all" && opts.key === "pr-template-path") {
+    const effective = await effectivePrTemplatePath(projectRoot);
+    if (effective) out.effective = effective;
+  }
+
+  if (scope !== "all" && !opts.json) {
+    const entry = out[scope];
+    if (entry?.available && entry.value !== null) {
+      emit(opts, entry.value);
+    } else {
+      emit(opts, "");
+    }
+    return 0;
+  }
+  emit(opts, out);
+  return 0;
+}
+
+async function opSet(opts) {
+  const spec = KEYS[opts.key];
+  if (opts.value === null) throw new Error(`'config set ${opts.key}' requires a value argument`);
+  let scope = opts.scope;
+  const projectRoot = await resolveProjectRoot(opts.cwd);
+  if (!scope) {
+    scope = projectRoot ? "project" : null;
+    if (!scope) {
+      throw new Error(
+        "--scope is required when cwd is not inside an okstra project. " +
+          "Pass --scope project or --scope global.",
+      );
+    }
+  }
+  if (!spec.scopes.includes(scope)) {
+    throw new Error(`key '${opts.key}' does not support scope '${scope}'`);
+  }
+  const ctx = { scope, projectRoot };
+  const err = spec.validate(opts.value, ctx);
+  if (err) throw new Error(err);
+
+  const targetPath =
+    scope === "project" ? projectConfigPath(projectRoot) : globalConfigPath();
+  if (scope === "project" && !projectRoot) {
+    throw new Error("cwd not inside an okstra project — cannot write project scope");
+  }
+  const existing = (await readJson(targetPath)) ?? {};
+  existing[spec.jsonField] = opts.value;
+  await writeJsonAtomic(targetPath, existing);
+  emit(opts, { ok: true, scope, path: targetPath, key: opts.key, value: opts.value });
+  return 0;
+}
+
+async function opUnset(opts) {
+  const spec = KEYS[opts.key];
+  let scope = opts.scope;
+  const projectRoot = await resolveProjectRoot(opts.cwd);
+  if (!scope) {
+    scope = projectRoot ? "project" : null;
+    if (!scope) throw new Error("--scope is required (project|global)");
+  }
+  const targetPath =
+    scope === "project" ? projectConfigPath(projectRoot) : globalConfigPath();
+  if (scope === "project" && !projectRoot) {
+    throw new Error("cwd not inside an okstra project — cannot unset project scope");
+  }
+  const existing = (await readJson(targetPath)) ?? {};
+  if (!(spec.jsonField in existing)) {
+    emit(opts, { ok: true, scope, path: targetPath, key: opts.key, removed: false });
+    return 0;
+  }
+  delete existing[spec.jsonField];
+  await writeJsonAtomic(targetPath, existing);
+  emit(opts, { ok: true, scope, path: targetPath, key: opts.key, removed: true });
+  return 0;
+}
+
+async function opShow(opts) {
+  const scope = opts.scope ?? "all";
+  const projectRoot = await resolveProjectRoot(opts.cwd);
+  const out = {};
+  if (scope === "project" || scope === "all") {
+    out.project = projectRoot
+      ? {
+          path: projectConfigPath(projectRoot),
+          data: (await readJson(projectConfigPath(projectRoot))) ?? {},
+        }
+      : { available: false, reason: "cwd not inside an okstra project" };
+  }
+  if (scope === "global" || scope === "all") {
+    out.global = {
+      path: globalConfigPath(),
+      data: (await readJson(globalConfigPath())) ?? {},
+    };
+  }
+  emit({ ...opts, json: true }, out);
+  return 0;
+}
+
+export async function run(args) {
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return args.length === 0 ? 2 : 0;
+  }
+  const opts = parseArgs(args);
+  if (!opts.op) {
+    process.stderr.write("missing subcommand (get|set|unset|show)\n");
+    return 2;
+  }
+  if (opts.scope !== null && !["project", "global", "all"].includes(opts.scope)) {
+    process.stderr.write(`invalid --scope: ${opts.scope}\n`);
+    return 2;
+  }
+  if (["get", "set", "unset"].includes(opts.op)) {
+    if (!opts.key) {
+      process.stderr.write(`'config ${opts.op}' requires a key argument\n`);
+      return 2;
+    }
+    if (!KEYS[opts.key]) {
+      process.stderr.write(
+        `unknown key '${opts.key}'. Supported: ${Object.keys(KEYS).join(", ")}\n`,
+      );
+      return 2;
+    }
+  }
+  try {
+    switch (opts.op) {
+      case "get":
+        return await opGet(opts);
+      case "set":
+        return await opSet(opts);
+      case "unset":
+        return await opUnset(opts);
+      case "show":
+        return await opShow(opts);
+      default:
+        process.stderr.write(`unknown subcommand '${opts.op}'\n`);
+        return 2;
+    }
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n`);
+    return 1;
+  }
+}