okstra 0.111.0 → 0.112.0

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

@@ -53,13 +53,9 @@ Show the final summary line back to the user (`version stamp: x.y.z`).
 If install fails, surface the stderr verbatim. Do NOT try to "fix" it by
 running the legacy `okstra-install.sh` — that path is dev-only.
 
-## Step 2: Load runtime paths (no-op)
+**Bash invocation rule (permission-friendly)**: after Step 1, every Bash command in this skill MUST begin with the literal token `okstra` and pass literal argument values. Do not introduce shell variables (`$PROJECT_ROOT`, `$PROJECT_ID`, ...), `$(...)` command substitution, leading `VAR=...` assignments, or wrap commands in `if`/`eval`/`||`/`&&` — any of those make the leading token non-literal, defeat the `Bash(okstra:*)` permission match, and force a confirmation prompt on every call. When a prior tool call emitted a path or value, paste the literal string into the next command. Every `okstra <subcmd>` call self-bootstraps its Python path — never run `okstra paths --shell` / `export PYTHONPATH=...`.
 
-After `okstra install`, every `okstra <subcmd>` call self-bootstraps its Python path, so this skill does NOT run `okstra paths --shell` / `eval ...` / `export PYTHONPATH=...`. The previously-set `$OKSTRA_WORKSPACE`, `$OKSTRA_AGENTS_DIR`, `$OKSTRA_PYTHONPATH`, `$OKSTRA_BIN`, `$OKSTRA_HOME` env vars are NOT set by this skill. If a later step needs one of those paths, call `okstra paths --json` as a **separate Bash tool call** (literal-token-first) and read the value from JSON output.
-
-**Bash invocation rule (permission-friendly)**: from this step on, every Bash command in this skill MUST begin with the literal token `okstra` and pass literal argument values. Do not introduce shell variables (`$PROJECT_ROOT`, `$PROJECT_ID`, ...), `$(...)` command substitution, leading `VAR=...` assignments, or wrap commands in `if`/`eval`/`||`/`&&` — any of those make the leading token non-literal, defeat the `Bash(okstra:*)` permission match, and force a confirmation prompt on every call. When a prior tool call emitted a path or value, read it from the tool output and paste the literal string into the next command.
-
-## Step 3: Resolve PROJECT_ROOT
+## Step 2: Resolve PROJECT_ROOT
 
 ```bash
 okstra check-project --json
@@ -74,12 +70,12 @@ Parse the JSON from stdout. The shape is `{ok, projectRoot, projectJsonPath, pro
   okstra check-project --cwd /abs/path/from/user --json
   ```
 
-- `ok: false`, `stage: "project_json_missing"` → proceed to Step 4 (this is the normal create path).
+- `ok: false`, `stage: "project_json_missing"` → proceed to Step 3 (this is the normal create path).
 - `ok: false`, any other `stage` (`python`, `parse`, `project_json_invalid`) → show the JSON `reason` field to the user verbatim and follow the recovery it names (typically `okstra doctor` to diagnose, then `okstra ensure-installed` or re-running the Step 1 install). `reason` is the SSOT — do not hand-enumerate stage causes.
 
-## Step 4: Inspect or create `project.json`
+## Step 3: Inspect or create `project.json`
 
-Use the `Read` tool on the literal absolute path `<projectRoot>/.okstra/project.json` (substitute the literal `projectRoot` value parsed in Step 3). If `Read` errors with "file does not exist", treat that as the "create" branch below; otherwise the file exists and you can inspect its contents inline.
+Use the `Read` tool on the literal absolute path `<projectRoot>/.okstra/project.json` (substitute the literal `projectRoot` value parsed in Step 2). If `Read` errors with "file does not exist", treat that as the "create" branch below; otherwise the file exists and you can inspect its contents inline.
 
 If the file exists, surface its `projectId`/`projectRoot` and ask whether to
 keep or overwrite. Default is to keep — okstra refuses to change `projectId`
@@ -95,226 +91,32 @@ If the file does NOT exist, ask via `AskUserQuestion`:
   `error: --project-id is required (no existing project.json, not a TTY)`,
   so passing the user's empty answer through is a silent failure path.
 
-Then create the file — paste the literal `projectRoot` from Step 3 and the literal `projectId` from the user's answer (no shell variables):
+Then create the file — paste the literal `projectRoot` from Step 2 and the literal `projectId` from the user's answer (no shell variables):
 
 ```bash
 okstra setup --yes --project-root /abs/path/to/projectRoot --project-id my-project-id
 ```
 
-> After this, **Steps 4.5–4.8 are all optional**. The built-in defaults
-> work for most projects — skip straight to Step 5 (`doctor`) unless the
-> user explicitly asks to customise worktree sync, declare QA commands,
-> or register a PR-body template. Step 4.7 (settings.local.json symlink)
-> is automatic; it is documented for diagnostic purposes only.
-
-## Step 4.5 (optional): customise worktree sync dirs
-
-Each okstra run provisions a task-scoped git worktree under
-`~/.okstra/worktrees/.../`. A small set of project-root-relative
-directories is symlinked from the main checkout into that worktree so
-every task sees the shared state. The built-in default is
-`.project-docs`, `.scratch`, `graphify-out`, `.claude`.
-Syncing a directory does not make it okstra memory; okstra-owned context
-and writes still stay under `<PROJECT_ROOT>/.okstra/**`
-unless the task brief explicitly authorizes a non-okstra path.
-
-To override per-project, add a `worktreeSyncDirs` array to
-`project.json`. Empty array disables the feature; the field is
-preserved across the runtime's auto-upserts (see Step 4.6 for the
-canonical list of runtime-owned fields).
-
-```json
-{
-  "projectId": "...",
-  "projectRoot": "...",
-  "worktreeSyncDirs": [".project-docs", ".scratch", "graphify-out", ".claude", "my-custom-dir"]
-}
-```
-
-Resolution precedence: `OKSTRA_WORKTREE_SYNC_DIRS` env var → this
-field → built-in default. Only edit when defaults don't cover the
-project's working files (e.g. additional cache or local-config dirs
-that must follow the executor into the worktree).
-
-## Step 4.6 (optional but recommended): declare project QA commands
-
-`implementation`-phase verifiers run an independent QA gate over the
-executor's diff and need a project-wide baseline of check-only
-lint / format / typecheck / test commands. okstra does NOT auto-detect
-tooling from manifest files — declare the commands explicitly in
-`project.json` under `qaCommands`. Skipping this declaration is
-allowed but the verifier will then only run the plan's per-task
-`validation` set, with `qa-command not configured: <category>`
-recorded per missing category in the final report.
-
-Each category is an array of `{ "label", "cmd", "language"? }`
-objects. `language` is optional; when present the verifier MAY skip
-commands whose language is not represented in this run's diff.
-
-```json
-{
-  "projectId": "...",
-  "projectRoot": "...",
-  "qaCommands": {
-    "lint":      [{ "label": "cargo clippy", "cmd": "cargo clippy --all-targets -- -D warnings", "language": "rust" }],
-    "format":    [{ "label": "cargo fmt",    "cmd": "cargo fmt --check",                          "language": "rust" }],
-    "typecheck": [{ "label": "tsc",          "cmd": "pnpm exec tsc --noEmit",                     "language": "ts"   }],
-    "test":      [{ "label": "cargo test",   "cmd": "cargo test --workspace --locked",            "language": "rust" }]
-  }
-}
-```
-
-**`cmd` deny-list (mutation guard):** the verifier rejects any `cmd`
-containing tokens that imply mutation — declare commands in their
-check-only form only. Representative denied tokens: `--fix` / `--write`
-(formatters), `--updateSnapshot`, `npm install` (use `npm ci`),
-`pip install -U`, `cargo add`. The authoritative deny list is
-`scripts/okstra_ctl/qa_commands.py::find_denied_tokens`
-(`_DENIED_LITERAL_TOKENS` / `_DENIED_SUBSTRINGS` plus the dynamic
-`npm install` and `INSTA_UPDATE=` checks) — do not re-enumerate it here.
-
-Encountering a denied token aborts the verifier with status
-`contract-violated`; re-declare the command in check-only form to
-recover (e.g. swap `prettier --write` → `prettier --check`).
-
-The field is preserved across the runtime's auto-upserts of
-`project.json` — only `projectId`, `projectRoot`, `createdAt`,
-`updatedAt` are runtime-owned, so manual edits to `qaCommands`
-survive every subsequent `okstra setup` / `okstra run` invocation.
-
-### Step 4.6.1 (optional): `qaEnv` — Tier 3 conformance environment
-
-`implementation` / `final-verification` verifiers run **stage
-conformance scripts** (Tier 3) that may need to reach a database or an
-HTTP endpoint to prove the diff satisfies upstream requirements. Declare
-the environment those scripts are allowed to touch under `qaEnv`. Every
-field is optional; declare only what your conformance scripts use.
-
-```json
-"qaEnv": {
-  "replicaDbDsn": "<replica/test DB DSN — never shared/staging/prod>",
-  "appBaseUrl": "http://localhost:3000",
-  "envFile": ".okstra/qa.env",
-  "surfacePatterns": { "db": ["*.sql", "*repository*"], "http": ["*controller*"] }
-}
-```
-
-- `replicaDbDsn` — DSN the conformance script connects to. MUST be a
-  replica / disposable test DB, **never** a shared, staging, or
-  production database (conformance scripts may write).
-- `appBaseUrl` — base URL for endpoint-level conformance checks
-  (local app only).
-- `envFile` — path (under `.okstra/`) to an env file the verifier
-  sources before running conformance scripts.
-- `surfacePatterns` — per-project **override** of the diff-surface
-  cross-check map (`capability → glob list`). The validator maps each
-  changed file to a capability surface (`db` / `http` / `io`) and fails
-  the run when the diff touches a surface no stage `requires`. The
-  built-in patterns (e.g. `*router*` for `http`, `*storage*` for `io`)
-  are broad and match many front-end files, so front-end-heavy repos
-  should override with narrower globs to avoid false BLOCKING verdicts
-  (Phase 4b review note). An over-broad pattern over-blocks; an
-  over-narrow one lets an undeclared surface through — tune to the
-  repo's real db/http/io file naming.
-
-## Step 4.7 (automatic): project-local Claude settings symlink
-
-`okstra setup` (and `okstra run` on its first invocation per project)
-provisions `<PROJECT_ROOT>/.claude/settings.local.json` as a symlink to
-`~/.okstra/templates/settings.local.json`. The template is installed
-by `okstra install` 0.14.0+ and contains the Bash permission rules
-required for the codex/antigravity worker wrappers:
-
-- `Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)`
-- `Bash($HOME/.okstra/bin/okstra-antigravity-exec.sh:*)`
-
-Claude Code automatically loads `.claude/settings.local.json` whenever
-it operates inside that project, so okstra workers dispatched from
-**any** Claude Code session (host or okstra.sh-spawned) are allowed to
-run their wrapper scripts without further configuration.
-
-This replaces the previous per-run `--settings` injection model
-(`<run-dir>/okstra-runtime-settings.json`) and the earlier guidance to
-modify the user's global `~/.claude/settings.json`.
-
-If a non-symlink `.claude/settings.local.json` already exists, the
-setup step backs it up to `.claude/settings.local.json.bak.<timestamp>`
-before installing the symlink — surface that to the user so they can
-merge any project-specific rules back into a downstream file (the
-symlinked template is okstra-owned and gets refreshed when okstra
-updates).
-
-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, opt-in): register a project PR body template
-
-`release-handoff` fills the PR body from a template. By default it uses the
-installed template at
-`~/.okstra/templates/prd/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.
-
-**Pre-registration during setup is opt-in.** The same prompt is also
-offered on the first `release-handoff` run in this project, so it is
-safe to defer this step (`나중에`) — most users should skip unless they
-explicitly want to lock the template in now.
-
-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>/.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 4.9 (optional): choose final report language
-
-기본은 영어. 이 step 을 skip 하면 `reportLanguage` 필드를 두지 않고
-runtime 이 `auto` 로 처리한다 — 즉 task brief 의 주 서술 언어를 따라
-간다 (한국어 brief → 한국어 report, 영어 brief → 영어 report).
-
-사용자가 명시적으로 선택하면 `okstra config set` 으로 `project.json`
-에 기록한다.
-
-AskUserQuestion (fixed options):
-- Question: `"Final report 를 어느 언어로 작성할까요?"`
-- Options:
-  1. `English (recommended)` → reportLanguage: "en"
-  2. `한국어` → reportLanguage: "ko"
-  3. `Auto (task brief 언어로 추론, 불분명하면 영어)` → reportLanguage: "auto"
-  4. `나중에` → skip (필드 미설정 → runtime 이 auto 로 처리)
-
-If the user picks 1/2/3, run:
+## Step 3.5 (optional): project customisation
 
-`okstra config set report-language <en|ko|auto> --scope project`
+The built-in defaults work for most projects — skip straight to Step 4
+(`doctor`) unless the user explicitly asks for one of these. When they do,
+**read `references/project-config.md` next to this SKILL.md** and follow the
+matching section:
 
-전역 기본값을 두고 싶다면 README 의 "global config" 안내를 따라
-`--scope global` 로 수동 설정한다. 이 step 에서는 project 스코프만 제공한다.
+- **A. worktree sync dirs** (`worktreeSyncDirs`) — extra directories symlinked
+  into task worktrees.
+- **B. project QA commands** (`qaCommands`, recommended) + **B.1 `qaEnv`** —
+  check-only lint/format/typecheck/test baseline and the Tier 3 conformance
+  environment the `implementation` verifiers use.
+- **C. `.claude/settings.local.json` symlink** — automatic; read only to
+  diagnose a symlink/backup warning.
+- **D. PR body template** (release-handoff) — opt-in pre-registration; also
+  offered on the first release-handoff run.
+- **E. final report language** (`reportLanguage`) — default is auto (follows
+  the brief's language).
 
-## Step 5: Verify
+## Step 4: Verify
 
 ```bash
 okstra doctor --runtime claude-code
@@ -323,7 +125,7 @@ okstra doctor --runtime claude-code
 If all checks return `OK`, the setup is complete. If any check fails, surface
 the output and let the user decide whether to re-run install or skip.
 
-## Step 6: Hand-off
+## Step 5: Hand-off
 
 Inform the user with a short summary:
 
@@ -337,7 +139,7 @@ Inform the user with a short summary:
 |---|---|---|
 | `command not found: npx` | Node missing | Install node 18+. |
 | `okstra ensure-installed` keeps reinstalling | `~/.okstra/version` write fails (permissions) | Check `~/.okstra` ownership and writability. |
-| `error: --project-id is required (no existing project.json, not a TTY)` | `okstra setup --yes` invoked without `--project-id`, or with empty answer to Step 4 prompt | Re-ask Step 4 and pass a non-empty id via `--project-id`. |
+| `error: --project-id is required (no existing project.json, not a TTY)` | `okstra setup --yes` invoked without `--project-id`, or with empty answer to Step 3 prompt | Re-ask Step 3 and pass a non-empty id via `--project-id`. |
 | `projectId mismatch` / `projectId 불일치` | `project.json` already exists with a different id | Decide which id is canonical; manually delete `<PROJECT_ROOT>/.okstra/project.json` to re-register, or re-run with the existing id. |
 | `EACCES` writing under `.okstra/` | directory owned by another user (e.g. created by a previous root-shell run) | `chown -R "$USER" <PROJECT_ROOT>/.okstra` or delete and let setup recreate. |
 | `warning: failed to provision .claude/settings.local.json symlink` | a non-symlink `.claude/settings.local.json` already exists and the backup-and-replace step failed | Inspect `<PROJECT_ROOT>/.claude/settings.local.json{,.bak.*}`; manually merge project-specific rules, then re-run setup. |

package/runtime/skills/okstra-setup/references/project-config.md

@@ -0,0 +1,188 @@
+# Optional project configuration (okstra-setup)
+
+Read this only when the user asks to customise one of the areas below after
+`project.json` exists. The built-in defaults work for most projects — none of
+these sections is required for a working setup.
+
+The Bash invocation rule from SKILL.md applies to every command here.
+
+## A. Worktree sync dirs (`worktreeSyncDirs`)
+
+Each okstra run provisions a task-scoped git worktree under
+`~/.okstra/worktrees/.../`. A small set of project-root-relative directories is
+symlinked from the main checkout into that worktree so every task sees the
+shared state. The built-in default is `.project-docs`, `.scratch`,
+`graphify-out`, `.claude`. Syncing a directory does not make it okstra memory;
+okstra-owned context and writes still stay under `<PROJECT_ROOT>/.okstra/**`
+unless the task brief explicitly authorizes a non-okstra path.
+
+To override per-project, add a `worktreeSyncDirs` array to `project.json`.
+Empty array disables the feature; the field is preserved across the runtime's
+auto-upserts (only `projectId`, `projectRoot`, `createdAt`, `updatedAt` are
+runtime-owned).
+
+```json
+{
+  "projectId": "...",
+  "projectRoot": "...",
+  "worktreeSyncDirs": [".project-docs", ".scratch", "graphify-out", ".claude", "my-custom-dir"]
+}
+```
+
+Resolution precedence: `OKSTRA_WORKTREE_SYNC_DIRS` env var → this field →
+built-in default. Only edit when defaults don't cover the project's working
+files (e.g. additional cache or local-config dirs that must follow the
+executor into the worktree).
+
+## B. Project QA commands (`qaCommands`) — recommended
+
+`implementation`-phase verifiers run an independent QA gate over the
+executor's diff and need a project-wide baseline of check-only lint / format /
+typecheck / test commands. okstra does NOT auto-detect tooling — declare the
+commands explicitly in `project.json` under `qaCommands`. Skipping this is
+allowed but the verifier will then only run the plan's per-task `validation`
+set, with `qa-command not configured: <category>` recorded per missing
+category in the final report.
+
+Each category is an array of `{ "label", "cmd", "language"? }` objects.
+`language` is optional; when present the verifier MAY skip commands whose
+language is not represented in this run's diff.
+
+```json
+{
+  "projectId": "...",
+  "projectRoot": "...",
+  "qaCommands": {
+    "lint":      [{ "label": "cargo clippy", "cmd": "cargo clippy --all-targets -- -D warnings", "language": "rust" }],
+    "format":    [{ "label": "cargo fmt",    "cmd": "cargo fmt --check",                          "language": "rust" }],
+    "typecheck": [{ "label": "tsc",          "cmd": "pnpm exec tsc --noEmit",                     "language": "ts"   }],
+    "test":      [{ "label": "cargo test",   "cmd": "cargo test --workspace --locked",            "language": "rust" }]
+  }
+}
+```
+
+**`cmd` deny-list (mutation guard):** the verifier rejects any `cmd`
+containing tokens that imply mutation — declare commands in their check-only
+form only. Representative denied tokens: `--fix` / `--write` (formatters),
+`--updateSnapshot`, `npm install` (use `npm ci`), `pip install -U`,
+`cargo add`. The authoritative deny list is
+`scripts/okstra_ctl/qa_commands.py::find_denied_tokens`
+(`_DENIED_LITERAL_TOKENS` / `_DENIED_SUBSTRINGS` plus the dynamic
+`npm install` and `INSTA_UPDATE=` checks) — do not re-enumerate it here.
+
+Encountering a denied token aborts the verifier with status
+`contract-violated`; re-declare the command in check-only form to recover
+(e.g. swap `prettier --write` → `prettier --check`).
+
+The field is preserved across the runtime's auto-upserts of `project.json`, so
+manual edits to `qaCommands` survive every subsequent `okstra setup` /
+`okstra run` invocation.
+
+### B.1 `qaEnv` — Tier 3 conformance environment
+
+`implementation` / `final-verification` verifiers run **stage conformance
+scripts** (Tier 3) that may need to reach a database or an HTTP endpoint to
+prove the diff satisfies upstream requirements. Declare the environment those
+scripts are allowed to touch under `qaEnv`. Every field is optional; declare
+only what your conformance scripts use.
+
+```json
+"qaEnv": {
+  "replicaDbDsn": "<replica/test DB DSN — never shared/staging/prod>",
+  "appBaseUrl": "http://localhost:3000",
+  "envFile": ".okstra/qa.env",
+  "surfacePatterns": { "db": ["*.sql", "*repository*"], "http": ["*controller*"] }
+}
+```
+
+- `replicaDbDsn` — DSN the conformance script connects to. MUST be a replica /
+  disposable test DB, **never** a shared, staging, or production database
+  (conformance scripts may write).
+- `appBaseUrl` — base URL for endpoint-level conformance checks (local app
+  only).
+- `envFile` — path (under `.okstra/`) to an env file the verifier sources
+  before running conformance scripts.
+- `surfacePatterns` — per-project **override** of the diff-surface cross-check
+  map (`capability → glob list`). The validator maps each changed file to a
+  capability surface (`db` / `http` / `io`) and fails the run when the diff
+  touches a surface no stage `requires`. The built-in patterns (e.g. `*router*`
+  for `http`, `*storage*` for `io`) are broad and match many front-end files,
+  so front-end-heavy repos should override with narrower globs to avoid false
+  BLOCKING verdicts. An over-broad pattern over-blocks; an over-narrow one
+  lets an undeclared surface through — tune to the repo's real db/http/io file
+  naming.
+
+## C. Project-local Claude settings symlink (automatic — diagnostics only)
+
+`okstra setup` (and `okstra run` on its first invocation per project)
+provisions `<PROJECT_ROOT>/.claude/settings.local.json` as a symlink to
+`~/.okstra/templates/settings.local.json`. The template contains the Bash
+permission rules required for the codex/antigravity worker wrappers:
+
+- `Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)`
+- `Bash($HOME/.okstra/bin/okstra-antigravity-exec.sh:*)`
+
+Claude Code automatically loads `.claude/settings.local.json` inside that
+project, so okstra workers dispatched from **any** Claude Code session are
+allowed to run their wrapper scripts without further configuration.
+
+If a non-symlink `.claude/settings.local.json` already exists, setup backs it
+up to `.claude/settings.local.json.bak.<timestamp>` before installing the
+symlink — surface that to the user so they can merge project-specific rules
+back (the symlinked template is okstra-owned and refreshed on okstra updates).
+To opt out (advanced): replace the symlink with a regular file; okstra will
+back it up as `.bak.<timestamp>` on its next setup call rather than
+overwriting silently.
+
+## D. Project PR body template (release-handoff)
+
+`release-handoff` fills the PR body from a template — by default
+`~/.okstra/templates/prd/pr-body.template.md`. Most projects want their own
+(e.g. `.github/PULL_REQUEST_TEMPLATE.md`). Pre-registration during setup is
+opt-in; the same prompt is offered again on the first `release-handoff` run,
+so deferring (`나중에`) is safe.
+
+Ask with `AskUserQuestion` (fixed options — file path entry happens in the
+follow-up plain text prompt):
+
+- **Question**: `"이 프로젝트에서 release-handoff 가 사용할 PR 본문 템플릿을 등록할까요?"`
+- **Options**:
+  1. `이번 프로젝트만 (project scope)` — writes `prTemplatePath` to `<PROJECT_ROOT>/.okstra/project.json`.
+  2. `전역 (global scope)` — writes `prTemplatePath` to `~/.okstra/config.json`.
+  3. `나중에` — skip.
+
+If 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. If the user chose `나중에`, tell them
+they can register later via the same `okstra config set` command or the
+per-run override prompt during the next release-handoff run.
+
+## E. Final report language (`reportLanguage`)
+
+기본은 영어. Skip 하면 `reportLanguage` 필드를 두지 않고 runtime 이 `auto` 로
+처리한다 — task brief 의 주 서술 언어를 따라간다 (한국어 brief → 한국어
+report, 영어 brief → 영어 report).
+
+AskUserQuestion (fixed options):
+- Question: `"Final report 를 어느 언어로 작성할까요?"`
+- Options:
+  1. `English (recommended)` → `en`
+  2. `한국어` → `ko`
+  3. `Auto (task brief 언어로 추론, 불분명하면 영어)` → `auto`
+  4. `나중에` → skip (필드 미설정 → runtime 이 auto 로 처리)
+
+If the user picks 1/2/3:
+
+```bash
+okstra config set report-language <en|ko|auto> --scope project
+```
+
+전역 기본값은 README 의 "global config" 안내대로 `--scope global` 로 수동
+설정한다 — 이 flow 에서는 project 스코프만 제공한다.

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

@@ -81,9 +81,9 @@ _의존 정보 없음_
 <!-- OPTIONAL: include only when per-task day estimates are available.
      If included, MUST use this exact heading literal `## Gantt Chart`.
      Render as ASCII inside a fenced ``` block with NO language tag.
-     Mermaid / PlantUML / Graphviz are forbidden — see SKILL §"ASCII Gantt format".
+     Mermaid / PlantUML / Graphviz are forbidden.
      The axis is RELATIVE DAY-COUNTS (Day 1 / J1, …) — never calendar dates.
-     If day estimates are missing, omit this whole section and replace it with one blockquote: `> _Gantt Chart 생략: <reason>_` (SKILL §"MUST — emit a skip-reason note"). -->
+     If day estimates are missing, omit this whole section and replace it with one blockquote: `> _Gantt Chart 생략: <reason>_`. -->
 
 ```
 Day:            1    5    10   15   20   25   30

package/runtime/templates/worker-prompt-preamble.md

@@ -20,7 +20,7 @@ Work like a senior engineer who owns this result, not a commentator on it.
 
 You are required to read every primary input file enumerated by the dispatcher (the lead's prompt lists them under `[Required reading]`) from the very first character to the very last character before you produce any analysis output. Skimming, partial reads, jumping to a single section, or relying on prior knowledge of a similar file's structure is not acceptable. Source files listed as fallback/evidence paths are read on demand when you need to verify a citation, resolve ambiguity, or inspect material the packet says it omitted.
 
-### Audience-scoped enumeration (BLOCKING — performance optimization)
+### Audience-scoped enumeration (performance optimization — mandatory)
 
 Different recipients need different files. Do NOT include `final-report-template.md` in analysis worker prompts: analysis workers produce findings (not the final report), and forcing them to read the template inflates token usage without changing finding quality.
 

package/runtime/validators/validate-run.py

@@ -1715,7 +1715,7 @@ _SINGLE_VOTE_BLOCKING_KINDS = {"a", "d"}
 
 def _classify_plan_item_gate(item: dict) -> str:
     """Recompute one plan item's gate class from its per-worker verdicts,
-    per `prompts/lead/convergence.md` "Round protocol". Returns one of
+    per `prompts/lead/plan-body-verification.md` "Round protocol". Returns one of
     ``majority-disagree`` / ``has-dissent`` / ``full-consensus`` /
     ``all-non-result``. Collapses ``partial-consensus`` and
     ``dissent-isolated`` into ``has-dissent`` because they resolve to the
@@ -1797,12 +1797,12 @@ def _validate_plan_body_gate_recompute(data: dict, failures: list[str]) -> None:
             f"only support `{recomputed}` (a majority DISAGREE, a DISAGREE(f) on "
             "a P-Req item, or all-non-result dispatches were recorded). The gate "
             "value must honestly aggregate the worker votes — do not upgrade it "
-            "to unblock the run (convergence.md Round protocol)."
+            "to unblock the run (plan-body-verification.md Round protocol)."
         )
 
 
 # Each plan-body deliverable array and the P-* verdict-item prefix it must be
-# extracted into for §5.5.9 cross-verification (convergence.md Plan-item
+# extracted into for §5.5.9 cross-verification (plan-body-verification.md Plan-item
 # extraction). A weak item dropped from planItems escapes the gate entirely.
 _PLAN_ITEM_SOURCES = (
     ("optionCandidates", "P-Opt", "Option Candidates (§4.5.1)"),
@@ -1848,7 +1848,7 @@ def _validate_plan_item_extraction_completeness(data: dict, failures: list[str])
                 f"planBodyVerification.planItems carries only {extracted} "
                 f"`{prefix}-*` verdict item(s). Every plan-body item MUST be "
                 "extracted for cross-verification — a dropped item escapes the "
-                "gate (convergence.md Plan-item extraction)."
+                "gate (plan-body-verification.md Plan-item extraction)."
             )
 
 
@@ -1885,7 +1885,7 @@ def _validate_plan_item_subject_substance(data: dict, failures: list[str]) -> No
                 f"placeholder subject `{subject}`. Give a plain-language label of "
                 "what the item is (e.g. 'Option A: upload v2 를 신규 모듈로 분리') so "
                 "the §5.5.9 reader knows what each verdict is about "
-                "(convergence.md Plan-item extraction)."
+                "(plan-body-verification.md Plan-item extraction)."
             )
 
 
@@ -1894,7 +1894,7 @@ def _validate_plan_body_clarification_matching(data: dict, failures: list[str])
     must point (via `clarificationId`) at an existing `blocks: approval`
     clarification row. Closes the hole where a majority-disagree item blocks the
     gate but no §1 Clarification row is raised, so the user never sees why
-    approval is withheld (convergence.md self-review step 7).
+    approval is withheld (implementation-planning.md self-review step 7).
     """
     ip = data.get("implementationPlanning")
     if not isinstance(ip, dict):
@@ -1920,7 +1920,7 @@ def _validate_plan_body_clarification_matching(data: dict, failures: list[str])
                 f"final-report data.json: plan item `{item_id}` is majority-disagree "
                 "but carries no `clarificationId`. A blocking disagreement MUST "
                 "surface as a `## 1. Clarification Items` row (blocks=approval) so "
-                "the user sees the blocker (convergence.md self-review step 7)."
+                "the user sees the blocker (implementation-planning.md self-review step 7)."
             )
         elif cid not in approval_ids:
             reason = (

package/src/cli-registry.mjs

@@ -45,6 +45,13 @@ export const COMMAND_REGISTRY = [
     category: "admin",
     summary: ["Verify the current project has been registered with setup"],
   },
+  {
+    name: "preflight",
+    module: "./commands/lifecycle/preflight.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["One-call skill preflight: ensure-installed + check-project (JSON)"],
+  },
   {
     name: "config",
     module: "./commands/lifecycle/config.mjs",
@@ -117,6 +124,13 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Resolve a bare task-id to candidate task-keys from the catalog"],
   },
+  {
+    name: "set-work-status",
+    module: "./commands/inspect/set-work-status.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Set a task's user-managed workStatus in task-manifest.json"],
+  },
   {
     name: "time-report",
     module: "./commands/inspect/time-report.mjs",

package/src/commands/inspect/set-work-status.mjs

@@ -0,0 +1,31 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra set-work-status — set a task's user-managed workStatus
+
+Usage:
+  okstra set-work-status <token> <status> [--note <text>] [--task-group <g>]
+                         [--project-root <dir>] [--cwd <dir>] [--json]
+
+<token> is a full task-key (<project-id>:<task-group>:<task-id>) or a bare
+task-id. <status> is one of: todo | in-progress | blocked | done.
+
+Updates workStatus + workStatusUpdatedAt in task-manifest.json (workStatusNote
+only when --note is passed) using the same JSON serialization as the manifest
+renderer. Output: JSON { ok, taskKey, previousWorkStatus, workStatus, ... };
+ok:false stages: resolve | catalog | not-found | ambiguous (pick from
+matches[]) | manifest-missing | manifest-invalid.
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const result = await runPythonModule({
+    module: "okstra_ctl.set_work_status",
+    args,
+    stdio: "inherit-stdout",
+  });
+  return result.code;
+}