okstra 0.25.1 → 0.27.0

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

@@ -36,6 +36,9 @@ multi-MB logs; analysis-phase dispatches are typically smaller.
 
 ## Step 0: Verify okstra runtime + project setup
 
+Before any other step, ensure both the okstra runtime and the current
+project's okstra metadata are in place:
+
 ```bash
 if command -v okstra >/dev/null 2>&1; then
   OKSTRA_CMD="okstra"
@@ -46,6 +49,8 @@ $OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
   echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
   exit 1
 }
+eval "$($OKSTRA_CMD paths --shell)"
+export PYTHONPATH="$OKSTRA_PYTHONPATH"
 OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
   echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
   echo "$OKSTRA_PROJECT_INFO" >&2
@@ -68,7 +73,7 @@ LOGS_ROOT="$PROJECT_ROOT/.project-docs/okstra/tasks"
 # columns: size_bytes | mtime_epoch | path
 find "$LOGS_ROOT" -type f -path '*/runs/*/prompts/*.log' \
   -printf '%s\t%T@\t%p\n' 2>/dev/null \
-  | sort -k2,2nr
+  | sort -k1,1nr
 ```
 
 On macOS, `find -printf` is unavailable. Fall back to `stat`:
@@ -78,7 +83,7 @@ find "$LOGS_ROOT" -type f -path '*/runs/*/prompts/*.log' 2>/dev/null \
   | while IFS= read -r p; do
       stat -f '%z%t%m%t%N' "$p"
     done \
-  | sort -k2,2nr
+  | sort -k1,1nr
 ```
 
 If the result is empty, report `No wrapper log files found under <PROJECT_ROOT>` and exit.
@@ -117,27 +122,40 @@ Total: N files, X.X MB across M tasks under <PROJECT_ROOT>
 ## Step 3: Suggested cleanup commands
 
 Emit a fenced bash block the user can copy-paste. Do NOT execute these.
+Each block pairs a dry-run preview (`-print`) with the destructive
+(`-delete`) command so the user can confirm the match set before
+committing.
 
 ```markdown
 ## Cleanup options (manual)
 
 # 7일 이상 된 로그만 삭제
+find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -mtime +7 -print    # dry-run
 find <PROJECT_ROOT>/.project-docs/okstra/tasks \
   -type f -path '*/runs/*/prompts/*.log' -mtime +7 -delete
 
 # 30일 이상 된 로그만 삭제
+find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -mtime +30 -print   # dry-run
 find <PROJECT_ROOT>/.project-docs/okstra/tasks \
   -type f -path '*/runs/*/prompts/*.log' -mtime +30 -delete
 
 # 특정 task-group 의 로그 일괄 삭제 (예: dev-9388)
+find <PROJECT_ROOT>/.project-docs/okstra/tasks/dev-9388 \
+  -type f -name '*.log' -print    # dry-run
 find <PROJECT_ROOT>/.project-docs/okstra/tasks/dev-9388 \
   -type f -name '*.log' -delete
 
 # 특정 task-id 의 로그 일괄 삭제 (예: dev-9428)
+find <PROJECT_ROOT>/.project-docs/okstra/tasks/*/dev-9428 \
+  -type f -name '*.log' -print    # dry-run
 find <PROJECT_ROOT>/.project-docs/okstra/tasks/*/dev-9428 \
   -type f -name '*.log' -delete
 
 # 전체 일괄 삭제 (주의)
+find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -print    # dry-run
 find <PROJECT_ROOT>/.project-docs/okstra/tasks \
   -type f -path '*/runs/*/prompts/*.log' -delete
 ```
@@ -152,10 +170,14 @@ End the response with these short reminders:
 - Logs are truncated on each re-dispatch of the same `seq`, so deleting an
   in-flight run's log will cause the wrapper to recreate an empty file on
   the next dispatch — no data loss beyond the current trace.
+- **If a dispatch is currently running, check `okstra status` first** and
+  avoid deleting logs for tasks in `in-progress` state — you will lose
+  the live trace for the active run.
 - Prompt history files (`.md`) are separate and are NOT touched by these
   commands — only `.log` sidecars.
-- This skill does not modify `.gitignore`. If the project commits
-  `.project-docs/okstra/`, the user may want to add
+- This skill **does not modify any external files itself**, including
+  `.gitignore`. If the project commits `.project-docs/okstra/`, the user
+  may want to add
   `.project-docs/okstra/tasks/**/runs/**/prompts/*.log` to `.gitignore`
   manually to keep large logs out of git.
 

package/runtime/skills/okstra-report-finder/SKILL.md

@@ -40,54 +40,81 @@ OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
 
 task-key 형식: `<project-id>:<task-group>:<task-id>`
 
+**Normalization**: task-key 매칭은 lowercase 로 수행한다. 디스크상의 group/id 세그먼트는 slugify (lowercase + non-alphanumeric runs → `-`) 된다 (`scripts/lib/okstra/interactive.sh:147`). 따라서 catalog 조회는 case-insensitive 이지만 파일 경로를 만들 때는 slugified segment 를 사용해야 한다.
+
 ### 방법 A: task-catalog.json (빠름)
 
 1. `.project-docs/okstra/discovery/task-catalog.json`을 읽는다.
-2. `tasks` 배열에서 `taskKey`가 일치하는 항목을 찾는다.
-3. `latestReportPath` 필드가 최신 보고서 경로이다.
+2. `tasks` 배열에서 `taskKey` 를 lowercase 비교로 매칭한다.
+3. `latestReportPath` 필드는 task-type 과 무관한 "가장 최근 보고서" 이다.
 
 ### 방법 B: task-manifest.json (직접)
 
-task-catalog가 없거나 최신이 아닌 경우:
+task-catalog 가 없는 경우:
+
+1. task-key 에서 task-group / task-id 를 추출하고 slugify 한다.
+2. `.project-docs/okstra/tasks/<group-segment>/<id-segment>/task-manifest.json` 을 읽는다.
+3. `latestReportPath` 필드 (task-type 무관, 최신).
+
+### 방법 C: timeline.json (특정 run 의 보고서)
 
-1. task-key에서 task-group과 task-id를 추출한다.
-2. `.project-docs/okstra/tasks/<task-group>/<task-id>/task-manifest.json`을 읽는다.
-3. `latestReportPath` 필드가 최신 보고서 경로이다.
+특정 날짜나 run 의 보고서가 필요한 경우:
 
-### 방법 C: timeline.json (특정 run의 보고서)
+1. `.project-docs/okstra/tasks/<group-segment>/<id-segment>/history/timeline.json` 을 읽는다.
+2. `runs[]` 배열에서 필터한다. 실제 필드:
+   - `runs[].runTimestamp` (ISO-8601 시작 시각)
+   - `runs[].status` (run 종료 상태)
+   - `runs[].taskType` (`requirements-discovery` 등 phase 이름)
+   - `runs[].reportPath` (해당 run 의 보고서 상대 경로)
 
-특정 날짜나 run의 보고서가 필요한 경우:
+### 방법 D: 특정 task-type 의 최신 보고서 (fallback)
 
-1. `.project-docs/okstra/tasks/<task-group>/<task-id>/history/timeline.json`을 읽는다.
-2. `runs` 배열에서 원하는 run을 찾는다 (날짜, 상태 등으로 필터).
-3. `reportPath` 필드가 해당 run의 보고서 경로이다.
+`latestReportPath` (방법 A/B) 는 task-type 을 가리지 않는다. 사용자가 *특정* task-type (예: `implementation-planning`) 의 최신 보고서를 요청하면:
+
+1. 디렉토리: `.project-docs/okstra/tasks/<group-segment>/<id-segment>/runs/<task-type-segment>/reports/`
+2. 파일명 패턴: `final-report-<task-type-segment>-<NNN>.md` (`scripts/okstra_ctl/sequence.py:31`)
+3. seq 가 가장 큰 파일이 해당 task-type 의 최신 보고서.
+4. timeline.json 의 `runs[].taskType == <task-type>` 으로 교차검증 가능.
 
 ## Step 2: Report 존재 확인
 
-1. 찾은 경로에 파일이 실제로 존재하는지 확인한다.
+1. `latestReportPath`가 비어있지 않고, 해당 경로의 파일이 실제로 존재하는지 확인한다.
+   - 두 신호 중 하나라도 보고서 존재를 가리키면 경로를 표시한다 (tolerant).
 2. 존재하면 경로를 표시하고 읽을지 사용자에게 확인한다.
-3. 존재하지 않으면:
-   - `task-manifest.json`의 `currentStatus`를 확인한다.
-   - status가 `completed`가 아니면: "이 task는 아직 완료되지 않았습니다 (status: `<status>`)."
-   - 파일만 없으면: "보고서 파일이 존재하지 않습니다: `<path>`"
+3. 존재하지 않으면 `task-manifest.json`에서 다음 신호를 확인한다:
+   - `latestReportPath`가 비어있거나 누락된 경우, 그리고
+   - `currentStatus`가 `completed`가 아니고, `workStatus`가 `done`이 아니며, `workflow.routingStatus`도 완료를 가리키지 않는 경우
+     → "이 task는 아직 완료되지 않았습니다 (currentStatus: `<currentStatus>`, workStatus: `<workStatus>`)."
+   - 위 신호 중 하나라도 완료를 가리키는데 파일만 없는 경우
+     → "보고서 파일이 존재하지 않습니다: `<path>`"
+
+워크플로 상태 enum은 `todo | in-progress | blocked | done` (workStatus) 와 `currentStatus`의 `completed` / `contract-violated` 등이다. `"completed"` 문자열은 `workStatus`에는 존재하지 않으므로 두 필드를 혼동하지 말 것.
 
 ## Step 3: Report 읽기 및 후속 작업 안내
 
 보고서를 읽은 후 사용자에게 가능한 후속 작업을 안내한다:
 
 1. **구현 진행**: 보고서의 "권장 다음 단계" 섹션 기반으로 코드 수정
-2. **추가 검증**: 같은 task-key로 새 okstra run 실행 (`okstra-history` 스킬로 재실행 커맨드 생성)
-3. **관련 task 확인**: 보고서의 관련 task 참조가 있으면 해당 task의 보고서도 조회
+2. **추가 검증**: 같은 task-key 로 새 okstra run 실행. 구체 커맨드:
+   ```bash
+   scripts/okstra.sh --task-key <task-key> --task-type <task-type>
+   ```
+   더 풍부한 옵션 (base-ref, workers, render-only 등) 이 필요하면 `okstra-history` 스킬을 사용한다.
+3. **관련 task 확인**: 보고서의 관련 task 참조가 있으면 해당 task 의 보고서도 조회
 
 ## Output
 
 ```markdown
 ## Report for <task-key>
 
-- Status: `<status>`
-- Report path: `<relative-path>`
-- Run date: `<YYYY-MM-DD HH:MM>`
-- Task type: `<task-type>`
+| Field        | Value                                              |
+| ------------ | -------------------------------------------------- |
+| Status       | `<status>`                                         |
+| Task type    | `<task-type>`                                      |
+| Run seq      | `<NNN>`                                            |
+| Run date     | `<runTimestamp ISO-8601>`                          |
+| Report (rel) | `<relative-path-from-project-root>`                |
+| Report (abs) | `<absolute-path>`                                  |
 ```
 
 이후 사용자 요청에 따라 보고서를 읽고 후속 작업을 진행한다.

package/runtime/skills/okstra-report-writer/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 
 ## File-author ownership (BLOCKING)
 
-The final-report file at `runs/<task-type>/reports/final-report-<task-type>-<seq>.md` is authored by the `Report writer worker` subagent when that worker is in the run's roster. Claude lead reviews the file but does NOT write it itself in that case. Lead-authored fallback is permitted only after a real Report writer worker dispatch attempt with a recorded non-`completed` terminal status (`error` / `timeout` / `not-run`) and a logged reason (`okstra-error-log.py`).
+The final-report file at `runs/<task-type>/reports/final-report-<task-type>-<seq>.md` is authored by the `Report writer worker` subagent when that worker is in the run's roster. Claude lead reviews the file but does NOT write it itself in that case. Lead-authored fallback is permitted only after a real Report writer worker dispatch attempt with a recorded non-`completed` terminal status (`error` / `timeout` / `not-run`) and a logged reason (`okstra-error-log.py`). **Except for `release-handoff`**, which has no worker roster — the Claude lead authors the final-report directly by design (see "Release-handoff section contract" below), and the fallback rules in this section do not apply.
 
 If you are reading this skill **as the report-writer-worker subagent**, YOU are the one calling the `Write` tool against the result path. Do not return the report inline — the file on disk is the canonical artifact.
 
@@ -60,7 +60,7 @@ A resumed lead session can ALWAYS dispatch a fresh Report writer worker. The Age
 
 ### Lead-authored fallback (only if dispatch failed)
 
-Lead-authored fallback is permitted only if all of the following are true and recorded in team-state:
+Except for `release-handoff` (which is single-lead by design and never dispatches a Report writer worker — see "Release-handoff section contract" below), lead-authored fallback is permitted only if all of the following are true and recorded in team-state:
 
 1. A Report writer worker dispatch was actually attempted (Agent call was issued).
 2. The attempt recorded a terminal status of `error`, `timeout`, or `not-run` with a concrete reason (tool error message, timeout duration, or external blocker).
@@ -68,50 +68,43 @@ Lead-authored fallback is permitted only if all of the following are true and re
 
 Speculative reasons such as "session resume constraint", "team object no longer exists", or "lead can do it faster" are NOT valid.
 
-## Phase 7 follow-up task spawner (BLOCKING when Section 7 is non-empty)
+## Phase 6 → Phase 7 execution sequence (BLOCKING order)
 
-After the token-usage collector finishes (the next subsection), Phase 7 must run the follow-up task spawner against the final-report file. This step is what turns the report's `## 7. Follow-up Tasks (후속 작업)` table into actual `tasks/<task-group>/<new-task-id>/` stubs that show up in `okstra-status`.
+The four steps below MUST execute in this exact order. Reordering them is the recurring root cause of reports shipping with unsubstituted `{{LEAD_TOTAL_TOKENS}}` placeholders, Section 6 missing the follow-up entries, or Section 7 rows never spawning.
 
-```bash
-python3 scripts/okstra-spawn-followups.py \
-  <runDirectoryPath>/reports/final-report-<task-type>-<seq>.md \
-  --project-root <project_root> \
-  --task-group <task-group> \
-  --parent-task-key <task-key>
-```
-
-Behaviour contract:
-
-- The script is **idempotent**: rows whose target directory already exists are reported as `existing` and skipped without modification. Re-running the spawner across reruns of the same parent task is safe.
-- Rows with `Auto-spawn? != yes` are reported as `skipped` and never written to disk. Surface them in the final-report's Section 6 if the user should still take manual action.
-- A row with an invalid `Origin`, `Suggested task-type`, missing `Title`, or missing `Reason / Why deferred` causes the script to exit `1`. The report-writer worker MUST refuse to ship a final-report whose Section 7 contains such rows. Either fix the row or change `Auto-spawn?` to `no` and document why in Section 6.
-- For `task-type` ∈ {`implementation`, `final-verification`, `release-handoff`}, Section 7 must be present in the final report. An empty section is acceptable and is expressed as the single line `- 후속 작업 없음.` under the heading. The spawner treats a missing or empty section as a no-op (exit `0`).
-
-After the spawner completes, the report-writer worker MUST update Section 6 ("Recommended Next Steps") to list every newly created task-key together with its entry command, so the user can pick the follow-up up immediately:
+1. **Phase 6 — Report writer worker drafts the final-report file** at `runs/<task-type>/reports/final-report-<task-type>-<seq>.md`. Token placeholders are left verbatim; Section 6 lists prioritized actions but does NOT yet include auto-spawned follow-ups (they don't exist yet).
+2. **Phase 7 step 1 — Token-usage collector with `--substitute-final-report`** (BLOCKING). One invocation aggregates `leadUsage` / `workers[].usage` / `usageSummary` into team-state AND substitutes the 10 placeholders in the final-report file. Skipping the flag ships literal `{{...}}` in the Token Usage Summary table.
 
-```
-- Follow-up: `<task-group>/<new-task-id>` — Claude Code 세션 안 `/okstra-run task-key=<task-group>/<new-task-id> task-type=<suggested>` / 별도 터미널 `scripts/okstra.sh --task-key <task-group>/<new-task-id> --task-type <suggested>`
-```
+   ```bash
+   python3 scripts/okstra-token-usage.py \
+     <runDirectoryPath>/state/team-state-<task-type>-<seq>.json \
+     --write --summary \
+     --substitute-final-report <runDirectoryPath>/reports/final-report-<task-type>-<seq>.md
+   ```
 
-## Phase 7 token-usage collector (BLOCKING)
+   The 10 substituted placeholders: `{{LEAD_TOTAL_TOKENS}}`, `{{LEAD_BILLABLE_TOKENS}}`, `{{LEAD_COST_USD}}`, `{{WORKER_TOTAL_TOKENS}}`, `{{WORKER_BILLABLE_TOKENS}}`, `{{WORKER_COST_USD}}`, `{{GRAND_TOTAL_TOKENS}}`, `{{GRAND_BILLABLE_TOKENS}}`, `{{GRAND_COST_USD}}`, `{{CLI_COST_USD}}`. The final-report file MUST already exist (Phase 6 output).
+3. **Phase 7 step 2 — Follow-up task spawner** (BLOCKING when Section 7 is non-empty). Turns the report's `## 7. Follow-up Tasks (후속 작업)` rows into `tasks/<task-group>/<new-task-id>/` stubs.
 
-At the start of Phase 7, run the token-usage collector with the final-report substitution flag. This step is BLOCKING — both the team-state aggregation AND the final-report placeholder substitution happen here, in one invocation:
-
-```bash
-python3 scripts/okstra-token-usage.py \
-  <runDirectoryPath>/state/team-state-<task-type>-<seq>.json \
-  --write --summary \
-  --substitute-final-report <runDirectoryPath>/reports/final-report-<task-type>-<seq>.md
-```
+   ```bash
+   python3 scripts/okstra-spawn-followups.py \
+     <runDirectoryPath>/reports/final-report-<task-type>-<seq>.md \
+     --project-root <project_root> \
+     --task-group <task-group> \
+     --parent-task-key <task-key>
+   ```
 
-This:
+   Behaviour contract:
+   - Idempotent: rows whose target dir exists are reported as `existing` and skipped. Reruns of the same parent task are safe.
+   - Rows with `Auto-spawn? != yes` are reported as `skipped` and never written; surface them in Section 6 if manual action is still needed.
+   - An invalid `Origin`, `Suggested task-type`, missing `Title`, or missing `Reason / Why deferred` exits `1`. The report-writer MUST refuse to ship a Section 7 with such rows.
+   - **Canonical spawn rule (single source of truth):** the spawner runs when `task-type` ∈ {`implementation`, `final-verification`, `release-handoff`}, OR when Section 7 is non-empty for any other task-type. For the listed task-types Section 7 must be present in the report; an empty section renders as `- 후속 작업 없음.`. Missing / empty sections are no-ops (exit `0`). All other references to this rule (including the Persistence Checklist) defer to this statement.
+4. **Phase 7 step 3 — Update Section 6** after the spawner. The report-writer MUST append one row per newly spawned task-key with its entry command:
 
-- Populates `leadUsage`, every `workers[].usage`, and `usageSummary` in team-state from session transcripts.
-- Substitutes the 10 token-related placeholders (`{{LEAD_TOTAL_TOKENS}}`, `{{LEAD_BILLABLE_TOKENS}}`, `{{LEAD_COST_USD}}`, `{{WORKER_TOTAL_TOKENS}}`, `{{WORKER_BILLABLE_TOKENS}}`, `{{WORKER_COST_USD}}`, `{{GRAND_TOTAL_TOKENS}}`, `{{GRAND_BILLABLE_TOKENS}}`, `{{GRAND_COST_USD}}`, `{{CLI_COST_USD}}`) in the final-report file with concrete values from the freshly computed usageSummary.
+   ```
+   - Follow-up: `<task-group>/<new-task-id>` — Claude Code 세션 안 `/okstra-run task-key=<task-group>/<new-task-id> task-type=<suggested>` / 별도 터미널 `scripts/okstra.sh --task-key <task-group>/<new-task-id> --task-type <suggested>`
+   ```
 
-Skipping `--substitute-final-report` is the recurring root cause of reports shipping with literal `{{LEAD_TOTAL_TOKENS}}` etc. in their Token Usage Summary table. Always pass the flag — never run the collector without it during Phase 7.
-
-The final-report file MUST already exist before this step runs (it's authored by Report writer worker in Phase 6, or by Lead in the documented fallback case). The status file can be written after this step completes.
+The status file is written after step 3 completes.
 
 ## Final Report Structure
 
@@ -181,7 +174,7 @@ Token Summary Generation Rules:
 
 ### Implementation-planning section heading contract (BLOCKING)
 
-When the run's `task-type` is `implementation-planning`, the final report MUST contain section headings whose **lines include each of the 8 literal English substrings below**. The validator (`validators/validate-run.py`) does plain substring matching on the report text — 7-of-8 missing was a real, repeatedly observed failure mode caused by translating the headings to Korean.
+When the run's `task-type` is `implementation-planning`, the final report MUST contain section headings whose **lines include each of the 9 literal English substrings below**. The validator (`validators/validate-run.py`) does plain substring matching on the report text — missing headings was a real, repeatedly observed failure mode caused by translating the headings to Korean.
 
 | # | Required substring | Recommended heading form |
 |---|--------------------|--------------------------|
@@ -193,11 +186,26 @@ When the run's `task-type` is `implementation-planning`, the final report MUST c
 | 6 | `Validation Checklist` | `### Validation Checklist (검증 체크리스트)` |
 | 7 | `Rollback` | `### Rollback Strategy (롤백 전략)` |
 | 8 | `User Approval Request` | `### User Approval Request (사용자 승인 요청)` |
+| 9 | `Plan Body Verification` + `Gate result:` | `### Plan Body Verification (계획 본문 검증)` containing a `Gate result:` line — copy `okstra-final-report.template.md §4.5.9` verbatim. Validator (`validators/validate-run.py` lines 531, 548) checks both substrings. |
 
 The Korean translation in parentheses is optional but the English keyword is mandatory. The body of each section is written in Korean per the writing rules below. For non-`implementation-planning` runs, omit this entire block — these headings are NOT validator-checked for other task-types.
 
 The final-report template `okstra-final-report.template.md` Section 4.5 already encodes this contract — copy that block verbatim and fill in.
 
+### Final-verification verdict token contract (BLOCKING)
+
+When the run's `task-type` is `final-verification`, the report's `## 2. Final Verdict` table MUST contain a `Verdict Token` row whose value is **exactly one of** the literal strings below. The `release-handoff` profile reads this row as its entry gate; any other value blocks the next phase.
+
+| # | Required substring | Meaning |
+|---|--------------------|---------|
+| 1 | `accepted` | All acceptance criteria pass; `release-handoff` may proceed. |
+| 2 | `conditional-accept` | Acceptance passes with caveats; user must resolve listed conditions before `release-handoff`. |
+| 3 | `blocked` | Acceptance failed; routing returns to `error-analysis` or `implementation-planning`. |
+
+For every other task-type, set the `Verdict Token` cell to `not-applicable`. Do NOT omit the row — the template renders it for all task-types and downstream tooling expects the field to exist.
+
+The final-report template `okstra-final-report.template.md` Section 2 already encodes this contract — copy that block verbatim and fill in.
+
 ### Release-handoff section contract (release-handoff runs only)
 
 When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 4.6 Release Handoff Deliverables` with all seven sub-sections (`4.6.1` Source Verification Report, `4.6.2` Feature Branch & Working-Tree State, `4.6.3` User Selections, `4.6.4` Executed Commands, `4.6.5` Commit List, `4.6.6` Pull Request Outcome, `4.6.7` Routing Recommendation). Every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. H1 choices are `local only`, `push + PR`, or `skip`; release-handoff records existing implementation commits and MUST NOT create new commits. If the user picked `skip` (H1) or `cancel` (H3), keep 4.6.3 populated but leave 4.6.4–4.6.6 explicitly empty per the template's empty-state lines.
@@ -216,35 +224,22 @@ runs/<task-type>/worker-results/report-writer-worker-<task-type>-<seq>.md
 
 This file is checked by the validator whenever the role's terminal status is `completed`. Without it the run fails with `report-writer is completed but worker result file is missing`.
 
-The file content is short: it begins with the standard worker-result header from `okstra-team-contract`, then names the canonical final-report path you wrote, lists the input artifacts you reconciled, and records any structural deviations from `final-report-template.md`. Do NOT duplicate the full final-report body here — it's an audit pointer, not a second copy.
+**Frontmatter + header schema** — both the worker-results audit file AND the final-report file are governed by `okstra-team-contract` ("Result Frontmatter" and the standard worker-result header sections). That document is the single source of truth; do NOT restate the field list here. Use `workerId: "report-writer"` for both files and copy every other frontmatter value verbatim from `analysis-material.md`. The body of this audit file is short: name the canonical final-report path you wrote, list the input artifacts you reconciled, and record any structural deviations from `final-report.template.md`. Do NOT duplicate the full final-report body here — it's an audit pointer, not a second copy.
 
 Skipping this file because "the real report is in `reports/`" is wrong. Both files are required.
 
 ### Main Body Section
 
-Section numbering matches `okstra-final-report.template.md`. Section 0 is the carry-in reconciliation that runs first when a clarification response was provided; sections 1–7 follow the template's main body order.
-
-0. **Clarification Response Carried In** - if `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}` is non-empty, read `instruction-set/clarification-response.md`, walk every `C-*` row of the prior report's `## 5. Clarification Items` table, reconcile each one against new evidence, and record the outcome (`resolved`/`obsolete`) plus the citation in this section before drafting the verdict. If the prior report uses the deprecated `4.5.9 Open Questions` / `5.1` / `5.2` layout with `OQ-*`/`A*`/`Q*` IDs, follow the legacy-carry-in mapping rule in `final-report-template.md` section 0.
-1. **Problem or Verification Summary** - Key summary based on the brief and data (3–5 bullet points)
-2. **Cross Verification Results** (Use 4 categories when convergence is enabled, per `okstra-convergence`)
-   - Round History sub-table (convergence-enabled runs only): one row per executed round with columns `Round | inputQueueSize | resolvedCount | carriedForwardCount | dispatches (worker:status:durationMs) | skippedWorkers (worker:reason)`. Add a one-line note immediately under the table with `round2SkippedReason: <value>` (always present, even when `"not-skipped"`). Pull all values verbatim from `convergence-<task-type>-<seq>.json`.
-   - Full Consensus: Findings agreed upon by all workers
-   - Partial Consensus: Agreed upon by a majority of workers; dissenting opinions are specified
-   - Contested: No consensus after the last executed round; each worker’s position specified. Empty contested list is shown as the literal line `- 합의 미달 항목 없음.`
-   - Worker-Unique: Verified only by the discoverer; verification history specified
-   - In runs with convergence disabled, maintain the existing Consensus/Differences format and omit the Round History sub-table.
-3. **Final Verdict** - Conclusion based on comprehensive evidence; direction provided. For `final-verification`, include a `Verdict Token` field whose value is exactly `accepted`, `conditional-accept`, or `blocked`; `release-handoff` uses that field as its entry gate.
-4. **Evidence and Detailed Analysis**
-   - Key Evidence: File path, line number, actual evidence
-   - If explicit expected values are present in `reference-expectations.md`, specify whether they match or differ from the expected values in config files / deployment manifests
-   - Supporting evidence or alternative interpretations
-5. **Missing Information and Risks** - Uncertain/I don't know items
-6. **Clarification Items** - single unified table (`C-001`, `C-002`, ...) the user fills inline before reruns. Columns: `ID`, `Ticket ID`, `Kind` (`material` / `decision` / `data-point`), `Statement`, `Expected form`, `Blocks` (`approval` / `next-phase` / `none`), `Status`, `User input`. Replaces the legacy `4.5.9 Open Questions` / `5.1` / `5.2` triple; never create those sub-sections — same item appearing in two places is the failure mode this table prevents.
-   - Required for `task-type` `error-analysis` and `requirements-discovery` whenever blocking uncertainty remains
-   - Optional for other task-types; explicitly state "no clarification needed" when none
-   - Follow the table format from `final-report-template.md` exactly (columns: Question ID, Blocking, Why this matters, Question, Expected answer shape, Status, Answer)
-   - Use stable `Q1`, `Q2`, ... ids and never delete prior ids on rerun; mark them `resolved` or `obsolete` instead
-7. **Recommended Next Steps** - Actions by Priority
+Section numbering follows `templates/reports/final-report.template.md` exactly — that file is the single source of truth. Below is a one-line summary of each section's writer obligation; consult the template for full body structure.
+
+0. **Clarification Response Carried In** — if `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}` is non-empty, walk every `C-*` row of the prior report's `## 5. Clarification Items` table, reconcile each one against new evidence, and record the outcome (`resolved` / `obsolete`) with citation before drafting the verdict. Legacy `4.5.9 / 5.1 / 5.2` carry-in mapping is documented in the template's Section 0.
+1. **Cross Verification Results** — 4 categories (Full / Partial / Contested / Worker-Unique) when convergence is enabled, per `okstra-convergence`. Prepend the Round History sub-table (columns: `Round | inputQueueSize | resolvedCount | carriedForwardCount | dispatches | skippedWorkers`) plus a `round2SkippedReason: <value>` note, pulled verbatim from `convergence-<task-type>-<seq>.json`. Empty contested list renders as `- 합의 미달 항목 없음.`. Convergence-disabled runs use the legacy Consensus/Differences format and omit the round table.
+2. **Final Verdict** — `Direction` ∈ `continue-investigation` / `begin-implementation` / `approve` / `reject` / `hold`. **Verdict Token** is `not-applicable` for every task-type except `final-verification` — see "Final-verification verdict token contract" below for that case.
+3. **Evidence and Detailed Analysis** — primary evidence rows (file path, line, snippet); secondary evidence / alternate interpretations. If `reference-expectations.md` lists explicit expected values, record match/gap per row.
+4. **Missing Information and Risks** — uncertain / "I don't know" items. `implementation-planning` adds §4.5 (see heading contract below); `release-handoff` adds §4.6.
+5. **Clarification Items** — single unified `C-*` table; column schema, ID convention, and rerun behaviour are owned by `_common-contract.md §Clarification request policy` (8-column SSOT). Never recreate the deprecated `4.5.9 Open Questions` / `5.1` / `5.2` sub-sections.
+6. **Recommended Next Steps** — prioritized actions. After Phase 7's follow-up spawner runs, append a row per newly created task-key (see "Phase 6 → Phase 7 execution sequence" above).
+7. **Follow-up Tasks** — auto-spawn-eligible table. Each row drives `okstra-spawn-followups.py`; see template §7 for the row schema.
 
 ### Writing Guidelines
 
@@ -280,7 +275,7 @@ Persistence steps that must be performed in Phase 7:
 - [ ] 5. **Update task-index.md**: Refresh human-readable summary
 - [ ] 6. **Generate final status file**: `runs/<task-type>/status/final-<task-type>-<seq>.status` (if necessary)
 - [ ] 7. **Save convergence state**: `runs/<task-type>/state/convergence-<task-type>-<seq>.json` (when convergence is enabled)
-- [ ] 8. **Spawn follow-up task stubs**: run `scripts/okstra-spawn-followups.py` against the final-report when the run's `task-type` ∈ {`implementation`, `final-verification`, `release-handoff`}, OR when Section 7 is non-empty for any other task-type. See "Phase 7 follow-up task spawner" above for the exact command and contract. The script is idempotent across reruns.
+- [ ] 8. **Spawn follow-up task stubs**: run `scripts/okstra-spawn-followups.py` against the final-report per the canonical spawn rule defined in "Phase 7 follow-up task spawner" above. Do not restate the trigger condition here — that section is the single source of truth. The script is idempotent across reruns.
 
 ### Response after Persistence
 

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

@@ -9,6 +9,8 @@ Launch an okstra task — gather inputs interactively via the **wizard state mac
 
 **Single authority**: this skill drives `okstra wizard`, which owns every step (ordering, branching, validation). The skill is just a thin prompt-relay loop — it never decides "what to ask next" itself. If the flow needs to change, edit `scripts/okstra_ctl/wizard.py`, not this file.
 
+**Bash invocation rule (permission-friendly)**: every Bash command in this skill MUST begin with the literal token `okstra` (or another already-allowed binary) and pass literal argument values. Do not introduce shell variables (`$STATE_FILE`, `$ANSWER`, `$projectRoot`, ...), `$(...)` command substitution, or leading `VAR=...` assignments — any of those make the leading token non-literal, defeat the `Bash(okstra:*)` permission match, and force a confirmation prompt on every wizard 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.
+
 ## When to Use
 
 - The user is inside a Claude Code session and asks to start an okstra task ("run okstra here", "start an error-analysis on this branch", "okstra implementation-planning for INV-1234").
@@ -16,7 +18,7 @@ Launch an okstra task — gather inputs interactively via the **wizard state mac
 
 ## When NOT to Use
 
-- User explicitly asks to spawn a new terminal / new claude — use `okstra-history` Step 4 (resume command) or instruct them to run `okstra.sh` in another terminal.
+- User explicitly asks to spawn a new terminal / new claude — use `okstra-history` Step 4 (resume command) or instruct them to run `okstra` in another terminal.
 - User wants status only — use `okstra-status`.
 - User wants past runs — use `okstra-history`.
 
@@ -46,33 +48,40 @@ Never invent additional questions. Never reorder. Never use `AskUserQuestion` fo
 
 ## Step 1: Verify okstra runtime + project setup
 
-```bash
-if command -v okstra >/dev/null 2>&1; then
-  okstra ensure-installed >/dev/null 2>&1 || { echo "FAIL: okstra ensure-installed failed" >&2; exit 1; }
-  eval "$(okstra paths --shell)"
-  export PYTHONPATH="$OKSTRA_PYTHONPATH"
-  okstra check-project --json || { echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2; exit 1; }
-else
-  npx -y okstra@latest ensure-installed >/dev/null 2>&1 || { echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2; exit 1; }
-  eval "$(npx -y okstra@latest paths --shell)"
-  export PYTHONPATH="$OKSTRA_PYTHONPATH"
-  npx -y okstra@latest check-project --json || { echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2; exit 1; }
-fi
-```
+Run each of the following commands as a **separate Bash tool call**. Each command starts with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&` — those leading tokens defeat the permission match and force a confirmation prompt on every call. The LLM (you) inspects each command's JSON output and decides what to do next in natural language — never in shell.
+
+1. `okstra ensure-installed`
+   If this exits non-zero, tell the user: "okstra runtime missing — run `npx okstra@latest install` once and retry." Then stop.
+
+2. `okstra paths --json`
+   Read `pythonPath` and other path fields from the JSON output. **Do not** `export PYTHONPATH=...` from this skill — every subsequent `okstra <subcmd>` call already self-bootstraps its Python path. Keep the parsed values in mind only as diagnostic context.
 
-The `check-project --json` output goes to stdout; read it from the tool result. If its `ok` field is `false`, ask the user with a **plain text prompt** for an absolute project-root path; rerun `okstra check-project --cwd <path> --json`. Re-prompt with plain text on failure.
+3. `okstra check-project --json`
+   Reads the project from the current working directory. Parse the JSON from stdout. If `ok` is `false`, ask the user with a **plain text prompt** for an absolute project-root path, then rerun as a separate tool call (still literal-token-first):
+   `okstra check-project --cwd /abs/path/from/user --json`
+   Substitute the literal absolute path the user gave you (no `$(pwd)`, no shell variables). Re-prompt with plain text on continued failure.
 
-Parse `projectRoot` and `projectId` from that JSON output.
+Parse `projectRoot` and `projectId` from the successful `check-project --json` output and carry them as literal strings into Step 2.
+
+> If the `okstra` binary is not on `PATH` at all, none of the commands above will run. In that case tell the user verbatim: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." Do **not** try to invoke `npx -y okstra@latest ...` from this skill — `npx` is not on the literal-token allow-list and will force a confirmation prompt on every wizard call afterward.
 
 ## Step 2: Initialize the wizard
 
+First, generate a state-file path (Bash invocation rule from the top of this file applies to every command below):
+
 ```bash
-STATE_FILE="$(mktemp -t okstra-wizard.XXXX.json)"
+okstra wizard new-state-file
+```
+
+This prints one absolute path on stdout (e.g. `/var/folders/.../okstra-wizard.AbCd.json`). Read that path from the tool output and **paste it literally** into every subsequent `--state-file` argument.
+
+Then initialize the wizard with the literal `projectRoot` / `projectId` you parsed from Step 1 and the literal state-file path from above:
 
+```bash
 okstra wizard init \
-  --state-file "$STATE_FILE" \
-  --project-root "$projectRoot" \
-  --project-id "$projectId"
+  --state-file /var/folders/.../okstra-wizard.AbCd.json \
+  --project-root /abs/path/to/project \
+  --project-id   my-project-id
 ```
 
 Output: the same `{ok, next}` JSON described above. The first `next` is always `step: "task_pick"`.
@@ -84,10 +93,19 @@ Repeat until `next.kind == "done"`:
 1. **Render** the prompt according to `kind`:
    - `pick` → `AskUserQuestion` with `label` and `options`. The user's chosen option's `value` is the answer string.
    - `text` → plain text message containing `label`. Consume the user's next reply verbatim as the answer string (empty reply = empty string).
-2. **Submit** the answer:
+2. **Submit** the answer — call `okstra wizard step` with the literal state-file path from Step 2 and the literal user answer (no shell variables, no `$(...)`):
    ```bash
-   okstra wizard step --state-file "$STATE_FILE" --answer "$ANSWER"
+   okstra wizard step --state-file /var/folders/.../okstra-wizard.AbCd.json --answer preprod
    ```
+   If the answer contains spaces or shell metacharacters, wrap it in double quotes around the literal string only — never inside `"$VAR"`.
+
+   **MANDATORY: empty answers must pass `--answer ""` explicitly.** If the user's reply is the empty string, the call MUST still include the flag with an empty literal value:
+   ```bash
+   okstra wizard step --state-file /var/folders/.../okstra-wizard.AbCd.json --answer ""
+   ```
+   Omitting `--answer` entirely is forbidden. The wizard interprets a missing `--answer` flag as "re-emit the current prompt" (a `get-current-prompt` style no-op), not as "submit empty" — so dropping the flag will loop the same prompt forever. Submitting `--answer ""` is the only way to advance past an intentionally-blank step (e.g. "use phase default").
+
+   **Escaping rule**: if the literal answer contains `"`, escape each occurrence as `\"` inside the double-quoted argument. Empty values must still be `--answer ""` — the flag itself is mandatory, even when the value is empty.
 3. **Handle result**:
    - `ok: true` → echo `result.echo` to the user on one short line, then loop with `result.next`.
    - `ok: false` → show `result.error` to the user verbatim, then loop with `result.current` (re-prompt the same step).
@@ -110,7 +128,7 @@ Do not second-guess the wizard. If the next prompt seems out of place, the bug i
 When `next.step == "confirm"`, before relaying the picker, fetch the human-readable selection summary:
 
 ```bash
-okstra wizard confirmation --state-file "$STATE_FILE"
+okstra wizard confirmation --state-file /var/folders/.../okstra-wizard.AbCd.json
 ```
 
 Output: `{ok: true, text: "선택 확인:\n  task-type     : ...\n  ..."}`. Print `text` to the user, then render the `confirm` picker (Proceed / Edit).
@@ -120,11 +138,15 @@ Output: `{ok: true, text: "선택 확인:\n  task-type     : ...\n  ..."}`. Prin
 When `next.kind == "done"`, fetch the final args:
 
 ```bash
-okstra wizard render-args --state-file "$STATE_FILE"
+okstra wizard render-args --state-file /var/folders/.../okstra-wizard.AbCd.json
 ```
 
 Output: `{ok: true, args: {"project-root": "...", "task-type": "...", ...}}`. Build the `okstra render-bundle` invocation from `args`, passing each key as `--<key>` and the value verbatim (including empty strings — they are intentional `use phase default` markers).
 
+**Empty-value rule (same as Step 3)**: every flag whose value is the empty string MUST still be passed explicitly as `--<key> ""`. For example: `--workers ""`, `--directive ""`, `--related-tasks ""`. Omitting the flag is forbidden — `render-bundle` distinguishes "flag absent" from "flag present with empty value", and the wizard's intent is always the latter.
+
+**Escaping rule**: inside a double-quoted value, escape any literal `"` as `\"`. Do not collapse `--key ""` into `--key` even when the value is empty.
+
 ```bash
 okstra render-bundle \
   --project-root "<args.project-root>" \
@@ -152,17 +174,11 @@ okstra render-bundle \
 
 The python function underneath is mutex-protected (`~/.okstra/.locks/<task-key>.lock`), writes `run-context-*.json` + `run-inputs-*.json` + all manifests + discovery files, and registers the run in `~/.okstra/recent.jsonl` with status `prepared`.
 
-You can delete `$STATE_FILE` after this point — its job is done.
+You can delete the literal state-file path after this point — its job is done. Invoke `rm` with the literal path (e.g. `rm /var/folders/.../okstra-wizard.AbCd.json`), not a shell variable.
 
 ## Step 6: Take over as Claude lead
 
-Read these files (do not paraphrase) and enter `Claude lead` mode:
-
-1. `<INSTRUCTION_SET_DIR>/claude-execution-prompt.md` — the lead prompt
-2. `<INSTRUCTION_SET_DIR>/analysis-profile.md` — per-task-type allowed outputs / forbidden actions
-3. `<INSTRUCTION_SET_DIR>/analysis-material.md` — task brief + directive
-4. `<INSTRUCTION_SET_DIR>/reference-expectations.md`
-5. `<INSTRUCTION_SET_DIR>/final-report-template.md`
+Read `<INSTRUCTION_SET_DIR>/claude-execution-prompt.md` verbatim and enter `Claude lead` mode. The lead prompt itself enumerates every other instruction-set file to load (`analysis-profile.md`, `analysis-material.md`, `reference-expectations.md`, `final-report-template.md`, the run manifest, the team-state artifact, etc.) — follow its order, do not preempt it.
 
 Then proceed through the phases exactly as the lead prompt directs (Phase 1 context → Phase 2+ worker dispatch → final synthesis → final report).
 
@@ -180,19 +196,17 @@ okstra config set pr-template-path "<path>" --scope project
 okstra config set pr-template-path "<path>" --scope global
 ```
 
-The scope is exposed via `wizard render-args` only as the `pr-template-path` value (1-shot override); the persist hint lives in the wizard state. Read it with:
+The scope is held in the wizard state but is not yet exposed by any `okstra wizard` subcommand. Until the subcommand below ships, read the JSON state file directly with the `Read` tool (literal path captured in Step 2) and inspect the `pr_template_scope` field — it is a plain serialized `WizardState`. Do not shell out (`python3 -c`, `jq`, etc.); the literal-token Bash rule rejects them.
 
-```bash
-python3 -c "import json,sys; print(json.load(open(sys.argv[1])).get('pr_template_scope',''))" "$STATE_FILE"
-```
+## Out-of-scope backlog
 
-(or just inspect the JSON state file directly — it is a plain serialized `WizardState`).
+- **`okstra wizard pr-template-scope --state-file PATH`**: add a thin subcommand to `scripts/okstra_ctl/wizard.py` that prints `{ok: true, scope: "once" | "project" | "global"}` so this skill can drop the `Read`-the-raw-state-file detour. The subcommand should reuse the existing `load_state_file` path; no schema changes required.
 
 ## Concurrency
 
 - `prepare_task_bundle` serializes per-task via `~/.okstra/.locks/<task-key>.lock`. Concurrent skill invocations on the same task wait; different tasks proceed in parallel.
-- Each wizard run owns its own `$STATE_FILE`; two parallel skill invocations do not collide.
-- The skill must NOT call `okstra.sh` or any other bash entrypoint that would re-implement the orchestration. The wizard + `render-bundle` is the single authority.
+- Each wizard run owns its own state file (one per `okstra wizard new-state-file`); two parallel skill invocations do not collide.
+- The skill must NOT call `okstra.sh` (or any other bash entrypoint) that would re-implement the orchestration. The wizard + `render-bundle` is the single authority.
 
 ## Failure Modes