okstra 0.25.1 → 0.27.0

package/README.kr.md

@@ -4,6 +4,21 @@
 >
 > English: [`README.md`](README.md)
 
+## 인덱스
+
+- [1. 용도](#1-용도)
+- [2. 구조](#2-구조)
+  - [2.1 repo 레이아웃](#21-repo-레이아웃)
+  - [2.2 설치 후 사용자 머신 레이아웃](#22-설치-후-사용자-머신-레이아웃)
+  - [2.3 단일 권위 요약](#23-단일-권위-요약)
+- [3. 사용 매뉴얼](#3-사용-매뉴얼)
+  - [3.1 최초 셋업 (머신당 1회)](#31-최초-셋업-머신당-1회)
+  - [3.2 프로젝트 등록 (프로젝트당 1회)](#32-프로젝트-등록-프로젝트당-1회)
+  - [3.3 일상 명령](#33-일상-명령)
+  - [3.4 CLI 모드 (선택)](#34-cli-모드-선택)
+  - [3.5 운영 명령](#35-운영-명령)
+- [4. 더 읽을 자료](#4-더-읽을-자료)
+
 ## 1. 용도
 
 `okstra` 는 **Claude Code 안에서 lead + worker 모델로 작업을 cross-verify 하기 위한 정형화된 task 실행 러너**입니다. Claude lead 가 phase 진행을 주도하고, 독립된 분석 worker — **기본 Claude · Codex** (Gemini 는 옵션으로 명시할 때만 추가) — 와 최종 보고서 작성을 전담하는 report-writer 를 dispatch 합니다.
@@ -169,6 +184,7 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 - **`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 도 프로파일이 실제로 받는 워커만 보여줍니다.
+- **Phase 6 plan-body verification (implementation-planning 전용)** — Report writer worker 가 final-report draft 를 작성한 직후, User Approval gate 직전에 lead 가 1 라운드의 사후 검증을 추가로 돌립니다. 합성된 `## 4.5` plan 본문에서 `P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*` plan-item 을 추출해 모든 analyser 워커에게 `AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT` 평결을 요청합니다. 집계된 gate 결과는 `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result` 중 하나. 앞 둘은 final-report 상단의 `- [ ] Approved` 마커를 렌더하고, 뒤 둘은 `majority-disagree` 항목을 `## 5. Clarification Items` 의 `Blocks=approval` row 로 변환합니다. 빠른 반복용 opt-out: `--no-plan-verification` (기본값: 활성). 자세한 라운드 프로토콜은 [`skills/okstra-convergence/SKILL.md`](skills/okstra-convergence/SKILL.md) 의 "Plan-body verification mode" 섹션과 [`docs/kr/cli.md#--no-plan-verification`](docs/kr/cli.md#--no-plan-verification).
 
 ### 3.5 운영 명령
 

package/README.md

@@ -4,6 +4,21 @@
 >
 > 한국어 매뉴얼: [`README.kr.md`](README.kr.md)
 
+## Index
+
+- [1. Purpose](#1-purpose)
+- [2. Structure](#2-structure)
+  - [2.1 Repo layout](#21-repo-layout)
+  - [2.2 User-machine layout after install](#22-user-machine-layout-after-install)
+  - [2.3 Single-authority map](#23-single-authority-map)
+- [3. Manual](#3-manual)
+  - [3.1 First-time setup (once per machine)](#31-first-time-setup-once-per-machine)
+  - [3.2 Register a project (once per project)](#32-register-a-project-once-per-project)
+  - [3.3 Day-to-day commands](#33-day-to-day-commands)
+  - [3.4 CLI mode (optional)](#34-cli-mode-optional)
+  - [3.5 Ops commands](#35-ops-commands)
+- [4. Further reading](#4-further-reading)
+
 ## 1. Purpose
 
 `okstra` is a **structured task-execution runner for Claude Code that cross-verifies work with a lead + worker model**. The Claude lead drives phase progression and dispatches independent analysis workers — **Claude and Codex by default** (with **Gemini** available as an opt-in extra) — plus a dedicated report-writer for the final synthesis.
@@ -168,6 +183,7 @@ Recent workflow additions (post-0.8.0, on `main`):
 - **`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.
+- **Phase 6 plan-body verification (implementation-planning only)** — after the Report writer worker authors the final-report draft and before the User Approval gate, the lead now runs one additional verification round: it extracts `P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*` items from the consolidated `## 4.5` plan body and dispatches them to every analyser worker as `AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`. The aggregated gate result is one of `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`; only the first two render the top-of-report `- [ ] Approved` marker, the other two convert `majority-disagree` items into `## 5. Clarification Items` rows with `Blocks=approval`. Disable for fast iteration with `--no-plan-verification` (default: enabled). Details: [`skills/okstra-convergence/SKILL.md`](skills/okstra-convergence/SKILL.md) "Plan-body verification mode" and [`docs/kr/cli.md#--no-plan-verification`](docs/kr/cli.md#--no-plan-verification).
 
 ### 3.5 Ops commands
 

package/docs/kr/architecture.md

@@ -326,7 +326,7 @@ Claude launch prompt 본문은 항상 `prompts/launch.template.md` 템플릿에
 |---|---|---|---|---|
 | `requirements-discovery` | 요청을 bugfix/feature/refactor/ops/improvement 중 하나로 분류하고 안전한 다음 phase로 라우팅 | work category, routing decision, missing-input list, clarification requests | `pending-routing-decision` (사용자 답변 후 결정) | 금지 |
 | `error-analysis` | 보고된 에러/사고의 증상·원인·재현 갭을 증거 기반으로 분석 | symptom/trigger 정리, root-cause 가설, reproduction gap, validation 경로 | `implementation-planning` | 금지 |
-| `implementation-planning` | 코딩 시작 전 안전한 구현 방향과 옵션을 평가 | 최소 2개 구현 옵션, 영향 파일 목록, trade-off, 단계별 실행 순서, validation/rollback, **User Approval Request** 블록 | `implementation` (사용자 승인 후) | 금지 |
+| `implementation-planning` | 코딩 시작 전 안전한 구현 방향과 옵션을 평가 | 최소 2개 구현 옵션, 영향 파일 목록, trade-off, 단계별 실행 순서, validation/rollback, **User Approval Request** 블록, **§4.5.9 Plan Body Verification** (Phase 6 워커 사후 검증 라운드 — 합성된 plan 의 내적 일관성을 워커가 `AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT` 로 cross-verify; gate 결과가 `passed` / `passed-with-dissent` 일 때만 Approval 마커 렌더, `blocked-by-disagreement` / `aborted-non-result` 일 때는 majority DISAGREE 항목이 `## 5. Clarification Items` 의 `Blocks=approval` row 로 변환됨) | `implementation` (사용자 승인 후) | 금지 |
 | `implementation` | 승인된 `implementation-planning` final report의 단계대로 소스 코드를 수정 | commit list, diff summary, out-of-plan edits 블록, validation/TDD evidence, rollback 검증, verifier 결과(Gemini/Codex/Claude) | `final-verification` | 허용 (승인된 plan의 파일 목록 한정, `git push`/publish/deploy/실제 migration 금지) |
 | `final-verification` | 완료된 작업의 잔존 결함·회귀 위험을 점검하고 release 판단 | acceptance verdict, residual risk, follow-up 라우팅(`error-analysis`/`implementation-planning`/`release-handoff`) | `pending-release-handoff` (verdict 가 `accepted` 일 때만 `release-handoff` 로 진입; 그 외에는 `error-analysis` 또는 `implementation-planning` 으로 리라우팅) | 금지 (read-only 테스트만 허용) |
 | `release-handoff` | `accepted` 받은 변경을 사용자가 선택한 방식대로 커밋·푸시·PR 로 전달 | 사용자 메뉴 응답(H1 action / H2 PR base / H3 message handling) 기록, 실행한 git/gh 명령 로그, commit SHA 목록, PR URL | `done-or-follow-up` | 허용 — 단 **사용자가 메뉴로 선택한 mutating 명령만** 실행. `git push --force*`, base 브랜치 직접 push, `--no-verify`, `gh release`, publish/deploy 는 금지. source code 자체는 수정 금지(이전 `implementation` 의 diff 를 그대로 패키징). |
@@ -449,10 +449,7 @@ scripts/okstra.sh workflow가 사용하는 project-local Claude assets는 아래
 - `.project-docs/okstra/discovery/latest-task.json`: 현재 프로젝트에서 가장 최근에 준비된 okstra task bundle을 가리키는 current-task convenience pointer
 - `.project-docs/okstra/discovery/task-catalog.json`: 현재 프로젝트에 준비된 okstra task bundle 목록을 `taskKey`, `taskGroup`, `taskId` 기준으로 유지하는 canonical project-level catalog
 - `instruction-set/reference-expectations.md`: 현재 task가 참조해야 할 config files, deployment manifests, expected values를 task-level canonical artifact로 정리한 파일
-- `.claude/skills/...`, `.claude/agents/...`: `agents` 아래 Markdown asset을 project-local Claude asset 구조로 seed한 파일들
-
-기본 rerun에서는 이미 존재하는 project-local asset을 유지합니다.
-`--refresh-assets`를 주면 mapped okstra asset을 source 기준으로 다시 생성합니다.
+- `~/.claude/skills/okstra-*/...`, `~/.claude/agents/...`: `okstra install` 이 사용자 홈에 seed하는 Claude asset (project-local 시딩은 더 이상 발생하지 않음 — `okstra install --refresh` 로 갱신)
 
 이전의 아래 파일들은 더 이상 okstra 생성 대상이 아닙니다.
 
@@ -867,7 +864,6 @@ Claude가 작성하는 최종 보고서는 brief에 더 구체적인 형식이
 - brief의 `Configuration References and Expected Values`, `Deployment Manifests and Expected Values` 섹션은 task별 expected state의 canonical source입니다.
 - `task-type`가 프로필 선택까지 결정합니다.
 - `--render-only`는 dry-run 확인용이지만 task bundle과 run manifest는 생성합니다.
-- `--refresh-assets`는 `.claude/skills/`와 `.claude/agents/`의 okstra mapped asset을 source 기준으로 다시 생성합니다.
 - 기본 실행은 Claude print-mode 수집이 아니라 interactive handoff입니다.
 - 기본 최종 보고서 템플릿은 task bundle의 `instruction-set/final-report-template.md`에 렌더링됩니다.
 - task bundle의 `instruction-set/reference-expectations.md`는 config/deployment expected-state reference로 함께 생성됩니다.
@@ -880,7 +876,7 @@ Claude가 작성하는 최종 보고서는 brief에 더 구체적인 형식이
 - Executor 별 worktree cwd 주입: codex / gemini executor 는 wrapper(`okstra-codex-exec.sh -C` / `okstra-gemini-exec.sh --include-directories`) 가 CLI layer 에서 cwd 를 worktree 로 고정합니다. Claude executor 는 Bash tool 에 per-call cwd 인자가 없어 cwd 민감 toolchain (`cargo`/`npm`/`pnpm`/`bun`/`pytest`/`make`/`go`) 호출을 같은 Bash invocation 안에서 `cd {{EXECUTOR_WORKTREE_PATH}} && <cmd>` 로 prefix 합니다 — `bash -lc`/`bash -c` 래핑은 금지되며 (`cd` leading token 이 가려져 permission auto-allow 우회 실패), 작업 디렉터리 플래그 (`git -C`, `cargo --manifest-path` 등) 가 있으면 그것을 우선합니다. 자세한 규약은 `prompts/profiles/implementation.md` 의 *Executor Worktree* 블록과 `agents/workers/claude-worker.md` 의 Executor exception 항목 참고.
 - project-level current-task convenience pointer는 `.project-docs/okstra/discovery/latest-task.json`입니다.
 - project-level canonical task inventory는 `.project-docs/okstra/discovery/task-catalog.json`입니다.
-- project-local okstra Claude asset은 `.claude/skills/`와 `.claude/agents/` 아래에 seed되며, 기본 rerun에서는 보존되고 `--refresh-assets`로 다시 생성할 수 있습니다.
+- okstra Claude asset은 `~/.claude/skills/`와 `~/.claude/agents/` 아래에 `okstra install` 시점에 seed되며, `okstra install --refresh` 로 갱신할 수 있습니다 (per-project seeding은 더 이상 수행되지 않음).
 - seeded okstra Claude assets는 Agent Teams 우선, sequential/background fallback 차선 규칙을 Claude에게 제공합니다.
 - 최종 판단은 스크립트가 아니라 Claude가 수행합니다.
 - stable task key를 유지해야 이후 bug 추적, 재수정, 재검증이 가능합니다.

package/docs/kr/cli.md

@@ -4,12 +4,51 @@
 
 ---
 
+## 인덱스
+
+- [Command forms](#command-forms)
+- [Required arguments](#required-arguments)
+  - [`--project-id`](#--project-id)
+  - [`--task-group`](#--task-group)
+  - [`--task-id`](#--task-id)
+  - [`--task-type`](#--task-type)
+  - [`--task-brief`](#--task-brief)
+  - [`--yes`](#--yes)
+- [Optional arguments and options](#optional-arguments-and-options)
+  - [`--task-key`](#--task-key)
+  - [`--clarification-response`](#--clarification-response)
+  - [`--resume-clarification`](#--resume-clarification)
+  - [`--project-root`](#--project-root)
+  - [`--directive`](#--directive)
+  - [`--workers`](#--workers)
+  - [`--claude-model`](#--claude-model)
+  - [`--lead-model`](#--lead-model)
+  - [`--codex-model`](#--codex-model)
+  - [`--gemini-model`](#--gemini-model)
+  - [`--report-writer-model`](#--report-writer-model)
+  - [`--executor`](#--executor)
+  - [`--approved-plan`](#--approved-plan)
+  - [`--approve`](#--approve)
+  - [`--work-category`](#--work-category)
+  - [`--related-tasks`](#--related-tasks)
+  - [`--render-only`](#--render-only)
+- [Interactive input flow](#interactive-input-flow)
+- [Confirmation flow](#confirmation-flow)
+- [okstra Control Center — 설치 / 자주 쓰는 명령](#okstra-control-center--설치--자주-쓰는-명령)
+- [okstra Control Center](#okstra-control-center)
+  - [설치 (전역 wrapper)](#설치-전역-wrapper)
+  - [자주 쓰는 명령](#자주-쓰는-명령)
+  - [`okstra` Node CLI — introspection subcommands](#okstra-node-cli--introspection-subcommands)
+  - [Live-log sidecar](#live-log-sidecar)
+
+---
+
 ## Command forms
 
 기본 명령(첫 진입 / full args):
 
 ```bash
-scripts/okstra.sh [--render-only] [--yes] [--refresh-assets] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--executor claude|codex|gemini] [--related-tasks taskA,taskB] [--work-category bugfix|feature|refactor|ops|improvement|unknown] [--clarification-response <previous-final-report>] [--approved-plan <plan-path>] [--approve] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>]
+scripts/okstra.sh [--render-only] [--yes] [--no-plan-verification] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--executor claude|codex|gemini] [--related-tasks taskA,taskB] [--work-category bugfix|feature|refactor|ops|improvement|unknown] [--clarification-response <previous-final-report>] [--approved-plan <plan-path>] [--approve] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>]
 ```
 
 후속 phase 단축 형식(기존 task-manifest.json이 존재할 때):
@@ -394,10 +433,14 @@ scripts/okstra.sh --task-type error-analysis --related-tasks scanner-regression,
 - `history/timeline.json` 갱신
 - project-level discovery pointer 생성 또는 갱신
 
-### `--refresh-assets`
+### `--no-plan-verification`
+
+`implementation-planning` task-type 의 Phase 6 plan-body verification 라운드를 끕니다. 기본값은 활성. 다른 task-type 에서는 무시됩니다.
 
-project-local `.claude/skills/`와 `.claude/agents/` 아래의 okstra mapped asset을 workspace source 기준으로 다시 생성합니다.
-기본 rerun에서는 기존 project-local asset을 유지합니다.
+- **활성 (default)**: Phase 6 에서 Report writer worker 가 final-report draft 를 작성한 직후, lead 가 합성된 plan 의 §4.5 본문 (Option Candidates / Stepwise Execution Order / Dependency / Validation Checklist / Rollback) 을 `P-*` plan-item 단위로 쪼개 모든 analyser 워커 (`claude`, `codex`, 그리고 옵트인된 `gemini`) 에게 reverify dispatch 합니다. 워커의 평결 (`AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`) 을 집계해 4 가지 gate result (`passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`) 중 하나를 산출하고, `passed` / `passed-with-dissent` 일 때만 final-report 상단의 `- [ ] Approved` 마커가 렌더됩니다. majority DISAGREE 항목은 `## 5. Clarification Items` 의 `Blocks=approval` row 로 변환됩니다 (자동 revise 없음 — 사용자가 답변 후 같은 phase 를 resume 해야 함).
+- **비활성 (`--no-plan-verification` 전달 시)**: Phase 6 sub-step 전체가 skip 되고 final-report 상단의 Approval 마커가 무조건 렌더됩니다 (legacy 동작). 빠른 반복용 opt-out — handoff-ready plan 에는 권장하지 않습니다.
+- 본 flag 는 manifest 의 `convergence.planBodyVerification.enabled` 를 `false` 로 기록합니다. resume 명령에서도 같은 flag 를 명시해야 같은 동작이 유지됩니다 (`_canonical_argv` 가 resume fidelity emit 을 보장).
+- 자세한 라운드 프로토콜 / verdict semantics / state 파일 스키마는 `skills/okstra-convergence/SKILL.md` 의 "Plan-body verification mode (implementation-planning only)" 섹션 참고.
 
 
 ## Interactive input flow

package/docs/kr/performance-improvement-plan-v2.md

@@ -1,5 +1,28 @@
 # okstra-run 성능 개선 계획 v2
 
+## 인덱스
+
+- [1. 목적](#1-목적)
+- [2. 현재 구조 요약](#2-현재-구조-요약)
+  - [2.1 진입점](#21-진입점)
+  - [2.2 두 종류의 phase를 구분한다](#22-두-종류의-phase를-구분한다)
+  - [2.3 prepare 단계의 비용 특성](#23-prepare-단계의-비용-특성)
+  - [2.4 worker 구조](#24-worker-구조)
+- [3. 성능 병목 가설](#3-성능-병목-가설)
+- [4. 측정 기준](#4-측정-기준)
+- [5. 개선 우선순위](#5-개선-우선순위)
+  - [P0. Baseline 계측과 용어 정리](#p0-baseline-계측과-용어-정리)
+  - [P1. Convergence 재검증 범위 축소](#p1-convergence-재검증-범위-축소)
+  - [P2. Prompt diet: analysis worker 입력 축소](#p2-prompt-diet-analysis-worker-입력-축소)
+  - [P3. Fast-track routing](#p3-fast-track-routing)
+  - [P4. Prompt caching 가능성 검증](#p4-prompt-caching-가능성-검증)
+  - [P5. Prepare render 병렬화](#p5-prepare-render-병렬화)
+  - [P6. Token usage 증분화](#p6-token-usage-증분화)
+- [6. 병렬 작업 계획](#6-병렬-작업-계획)
+- [7. P1 구현 체크리스트](#7-p1-구현-체크리스트)
+- [8. 리스크와 방어선](#8-리스크와-방어선)
+- [9. 이번 계획의 결론](#9-이번-계획의-결론)
+
 ## 1. 목적
 
 `okstra-run` 스킬 또는 `scripts/okstra.sh`로 시작하는 cross-verification run이 무겁게 느껴지는 문제를 줄인다. 이 문서는 현재 구조를 정확한 레이어로 나누고, 개선 후보의 우선순위, 측정 기준, 병렬 작업 가능성, 1차 구현 범위를 정리한다.

package/docs/kr/performance-improvement-plan.md

@@ -1,5 +1,27 @@
 # okstra-run 성능 개선 계획
 
+## 인덱스
+
+- [1. 배경](#1-배경)
+- [2. 현재 구조 요약](#2-현재-구조-요약)
+  - [2.1 진입점](#21-진입점)
+  - [2.2 라이프사이클 (Phase 1~7)](#22-라이프사이클-phase-17)
+  - [2.3 워커 구조](#23-워커-구조)
+  - [2.4 핵심 파이프라인](#24-핵심-파이프라인)
+- [3. 무거움의 원인 분석](#3-무거움의-원인-분석)
+- [4. 개선 방안 우선순위](#4-개선-방안-우선순위)
+  - [4.1 (P1) Convergence 루프 축소](#41-p1-convergence-루프-축소--본-작업의-1번-대상)
+  - [4.2 (P2) 프롬프트 캐싱 적용](#42-p2-프롬프트-캐싱-적용)
+  - [4.3 (P3) Phase 1 fast-track 라우팅](#43-p3-phase-1-fast-track-라우팅)
+  - [4.4 (P4) 워커 정의 공통부 추출 / 템플릿 슬림화](#44-p4-워커-정의-공통부-추출--템플릿-슬림화)
+  - [4.5 (P5~) Render 병렬화, token-usage 증분화](#45-p5-render-병렬화-token-usage-증분화)
+- [5. 병렬 작업 가능성](#5-병렬-작업-가능성)
+  - [5.1 의존성 매트릭스](#51-의존성-매트릭스)
+  - [5.2 권장 분할](#52-권장-분할)
+  - [5.3 실행 형태](#53-실행-형태)
+- [6. P1 작업 착수 시 다음 단계](#6-p1-작업-착수-시-다음-단계)
+- [7. 트레이드오프 / 리스크](#7-트레이드오프--리스크)
+
 ## 1. 배경
 
 `okstra-run` 스킬(또는 `scripts/okstra.sh`)을 통한 cross-verification 실행이 무겁게 느껴진다는 사용자 피드백을 바탕으로, 현재 파이프라인 구조를 분석하고 개선 후보를 도출한다. 본 문서는 분석 결과와 우선순위, 그리고 병렬 작업 가능성을 정리한다.

package/docs/superpowers/specs/2026-05-15-implementation-plan-verification-design.md

@@ -0,0 +1,254 @@
+# Implementation Plan Body Verification — Design
+
+- Date: 2026-05-15
+- Scope: okstra phase `implementation-planning` only
+- Status: Designed (pending implementation)
+- Implementation plan: `docs/superpowers/plans/2026-05-15-implementation-plan-verification.md` (to be written)
+
+## 1. 목적
+
+`implementation-planning` phase는 현재 다음 흐름을 따른다.
+
+```
+Phase 4 (워커 독립 분석)
+  → Phase 5.5 (워커 finding 상호 검증 — convergence)
+  → Phase 6 (report-writer가 통합 plan draft 작성)
+  → User Approval gate
+  → implementation phase
+```
+
+Phase 5.5의 convergence는 **워커의 finding (section 1~5)** 만 cross-verify한다. 그 뒤 report-writer가 합성한 **통합 plan body (section 4.5: Option Candidates / Trade-off / Recommended Option / Stepwise Execution Order / Dependency / Validation Checklist / Rollback)** 에 대해서는 워커의 재검증이 없다. lead의 self-review pass만 거치고 User Approval로 직행한다.
+
+본 변경은 Phase 6 직후, User Approval 직전에 **합성 결과물 자체를 워커가 peer-review하는 라운드**를 끼워 넣는다. 통합 plan의 내적 일관성 / 실행 가능성 / 누락된 step / 깨진 file path 등을 워커들이 잡아내고, majority disagreement는 `## 5. Clarification Items`에 `Blocks=approval` row로 변환해 사용자에게 던진다.
+
+## 2. 결정된 분기 (대화에서 확정)
+
+| ID | 결정 |
+|----|-----|
+| Q1 | **gating**. majority DISAGREE는 User Approval 체크박스를 막고 clarification 변환 경로로 보낸다. `contested` 와 `partial-consensus` 는 보고서에 기록만 하고 통과. |
+| Q2 | **lifecycle 내부 step**. 외부 6-phase 계약 유지. `/okstra-status` 에는 implementation-planning 내부의 `plan-verification` sub-state로만 노출. |
+| Q3 | **maxRounds = 1**. plan body 검증은 사실 검증이 아닌 일관성·완전성 검증이며 추가 라운드 이득이 작음. manifest로 override 가능. |
+| Q4 | **자동 revise 안 함**. majority DISAGREE 항목은 lead가 직접 `## 5. Clarification Items` 표의 `Blocks=approval` row로 변환. report-writer 재호출 없음. |
+
+## 3. Plan Item 분리 규칙
+
+report-writer가 draft한 final-report의 `## 4.5 Implementation Plan Deliverables` 본문을 lead가 파싱해 다음 형식의 plan-item으로 쪼갠다.
+
+| Prefix | 출처 섹션 | 1 row의 정의 |
+|--------|----------|--------------|
+| `P-Opt-<N>` | `4.5 Option Candidates` | Option 1개 전체 (File Structure / 인터페이스 / blast radius 묶음) |
+| `P-Step-<N>` | `Stepwise Execution Order` | step 1개 (file path + command + 성공 신호) |
+| `P-Dep-<N>` | `Dependency` | dependency row 1개 |
+| `P-Val-<N>` | `Validation Checklist` | checklist item 1개 |
+| `P-Rb-<N>` | `Rollback` | rollback path 1개 (보통 1행) |
+
+`Trade-off matrix`, `Recommended Option`은 별도 plan-item으로 만들지 않는다 (각 Option 자체가 P-Opt-* 로 평가되므로 중복).
+
+Ticket ID 표기는 기존 규칙 그대로 (`[TICKETID: ...]`) plan-item 라인에 강제.
+
+## 4. 평결 스키마 (재사용)
+
+기존 convergence의 `AGREE` / `DISAGREE` / `SUPPLEMENT` 스키마와 워커 실패 처리 규칙을 그대로 재사용. plan-body 모드에서의 각 평결 의미는 다음과 같다.
+
+| 평결 | plan-body 모드 의미 |
+|------|--------------------|
+| `AGREE` | 항목이 실행 가능하고 다른 항목과 내적으로 일관됨 |
+| `DISAGREE` | 항목이 깨짐 — 다음 중 하나 이상: (a) 참조된 file path / symbol 이 다른 step·option과 불일치, (b) command가 실행 불가하거나 ambiguity, (c) validation step이 관측 불가, (d) rollback이 commit 순서·dependency 위반, (e) 명시된 trade-off와 모순 |
+| `SUPPLEMENT` | 항목 자체는 OK이나 누락된 dependency / edge case / 사전조건 보강이 필요함 |
+
+워커 non-result(`timeout`/`error`/no result file) 처리는 finding convergence와 동일 — DISAGREE로 집계하지 않고 `contract-violation` 이벤트만 기록.
+
+## 5. 최종 분류 → Gate 매핑
+
+`effectiveMaxRounds = 1` 이므로 단일 라운드 결과로 결정.
+
+| 항목 분류 | Gate 동작 |
+|----------|----------|
+| `full-consensus AGREE` | 통과. 보고서에 기록. |
+| `partial-consensus` (majority AGREE, 일부 DISAGREE) | 통과(`passed-with-dissent`). 반대 의견은 보고서 4.5.9 섹션에 기록. |
+| `majority DISAGREE` | **gate 차단**. clarification row 변환. User Approval 체크박스 라인 자체를 렌더하지 않음. |
+| `worker-unique DISAGREE` (1명만 반대) | 통과. 보고서 기록만. |
+| `contested` (round 1 종료 시 큐 잔류 — maxRounds=1에서는 partial-consensus 와 동일 취급) | partial-consensus 로 fold-in. |
+| 모든 워커 non-result | 라운드 전체 실패. `aborted-non-result` 기록 + User Approval 체크박스 라인 렌더하지 않음 + clarification에 "plan-body verification could not run" row 추가. |
+
+## 6. 변경 파일
+
+### 6.1 `prompts/profiles/implementation-planning.md`
+- `Required deliverable shape` 끝에 새 bullet: "the final report MUST include a `## 4.5.9 Plan Body Verification` section populated by the post-synthesis worker verification round (see `okstra-convergence` "Plan-body verification mode")."
+- `Approval gate` 항목 보강: User Approval 체크박스 라인은 **plan-body verification gate가 `passed` 또는 `passed-with-dissent`일 때만 렌더된다**. `blocked-by-disagreement` / `aborted-non-result` 면 라인 자체를 생략하고 clarification 표로 사용자에게 던진다.
+- `Self-review pass` 끝에 6번 항목 신설: "If plan-body verification produced `DISAGREE` majority on any P-* item, convert each into a row of `## 5. Clarification Items` with `Blocks=approval`. Do NOT create a parallel `Open Questions` block."
+
+### 6.2 `skills/okstra-convergence/SKILL.md`
+- 신규 섹션 추가: "Plan-body verification mode (implementation-planning only)"
+- 본문 내용:
+  - **선행 흐름**: Phase 5.5 finding convergence → Phase 6 report-writer → plan-body verification round → User Approval
+  - finding 큐와 plan-item 큐는 **서로 독립**. 같은 워커, 같은 평결 스키마, 같은 wrapper 인프라를 재사용하되 state file은 별도(`plan-body-verification.json`).
+  - **MUTUAL EXCLUSION (BLOCKING)**: finding convergence 의 reverify prompt에 P-* item을 끼워 넣거나, plan-body 라운드의 reverify prompt에 F-* finding을 끼워 넣지 말 것.
+  - plan-body 라운드 전용 reverify prompt 본문 템플릿 (§7 참고).
+  - prompt anchor 5종은 finding convergence와 동일하게 유지.
+
+### 6.3 `templates/reports/final-report.template.md`
+- 신규 sub-section `### 4.5.9 Plan Body Verification` 추가. 위치: 기존 `### 4.5.8 User Approval Request` 직후, `## 4.6 Release Handoff Deliverables` 직전 (implementation-planning 4.5 블록의 마지막 sub-section).
+- 필드:
+
+  ```
+  ## 4.5.9 Plan Body Verification
+
+  - Round count: <N>
+  - Gate result: <passed | passed-with-dissent | blocked-by-disagreement | aborted-non-result>
+  - Verdict table:
+
+  | Plan item | Ticket ID | Section | <worker1> | <worker2> | ... | Classification |
+  |-----------|-----------|---------|-----------|-----------|-----|----------------|
+  | P-Opt-1   | ...       | 4.5.1   | AGREE     | AGREE     | ... | full-consensus |
+  | P-Step-3  | ...       | 4.5.4   | DISAGREE  | DISAGREE  | ... | majority-disagree → C-7 |
+
+  - Dissent log: (partial-consensus / worker-unique 인 항목의 반대 의견 본문)
+  ```
+
+### 6.4 `validators/validate-run.py`
+- `implementation-planning` phase 일 때 final-report에서 다음 substring을 필수로 검사:
+  - `Plan Body Verification`
+- Approval gate 라인 검사 로직 보강: gate 결과가 `passed` / `passed-with-dissent` 이면 `- [ ] Approved` / `- [x] Approved` 라인이 반드시 존재해야 하고, `blocked-by-disagreement` / `aborted-non-result` 이면 해당 라인이 **존재하지 않아야** 한다.
+
+### 6.5 `scripts/okstra_ctl/render.py` (task-manifest payload)
+현재 codebase 에는 task-manifest 를 위한 Python dataclass 가 없다 (`models.py` 는 model alias 전용). manifest payload 는 `render_task_manifest()` 안에서 dict literal 로 직접 구성된다. 기존 `convergence` 블록은 아직 manifest 에 출력되지 않으며, skill 문서에만 "있으면 읽고 없으면 default" 로 기술돼 있다. 따라서:
+
+- `render_task_manifest()` payload 에 신규 `convergence` 블록을 명시적으로 출력한다:
+
+  ```json
+  "convergence": {
+    "enabled": true,
+    "maxRounds": <phase-aware default>,
+    "verificationMode": "lightweight",
+    "planBodyVerification": {
+      "enabled": true,
+      "maxRounds": 1,
+      "gating": true
+    }
+  }
+  ```
+
+  - `maxRounds`: `requirements-discovery` 면 1, 그 외 phase 면 2 (기존 skill 문서의 default 그대로).
+  - `planBodyVerification.enabled`: task-type 이 `implementation-planning` 일 때만 의미를 가진다. 다른 phase 에서는 무시되어도 안전한 dead-letter 필드 (스키마 일관성을 위해 항상 출력).
+- ctx 입력 키 (CLI / wizard / interactive 입력 → ctx env 로 합류):
+  - `OKSTRA_PLAN_VERIFICATION` ∈ `{"true","false",""}` — 빈 값이면 default(true). 명령행 `--no-plan-verification` 가 `"false"` 로 set.
+  - 추후 `OKSTRA_PLAN_VERIFICATION_MAX_ROUNDS` 같은 추가 knob 가능하지만 본 spec 범위에서는 1 고정.
+- 기존 manifest 와의 호환: render 마다 payload 가 매 회 다시 쓰이므로 (`render_task_manifest` 의 `existing` 머지 대상은 `workflow` 일부와 `createdAt`/`latestRunPath` 같은 lifecycle 키뿐) `convergence` 블록은 매 render 마다 새로 작성된다. legacy task-key 의 resume 시 ctx 가 default(true) 면 자동으로 enabled 가 set 된다 (§8 마이그레이션 항목 그대로).
+
+### 6.6 `agents/SKILL.md` (lead orchestration skill — markdown only, no Python)
+
+**아키텍처 정정**: okstra 의 orchestration 패턴은 conversational-only 다. Python 코드(`scripts/okstra_ctl/`)는 task bundle 준비 / 템플릿 렌더링 / validation 만 담당하고, Phase 4 (워커 dispatch), Phase 5.5 (convergence), Phase 6 (report-writer dispatch) 등 **모든 phase 실행은 lead 가 SKILL.md 명세를 따라 inline 으로 Agent() 호출**로 수행한다. `render.py:1133` 의 rendered prompt 문구 ("convergence loop. The Claude lead performs every step inline") 와 run.py 에 convergence 관련 dispatch 함수가 존재하지 않는 점이 이 패턴을 확인해 준다.
+
+따라서 plan-body verification 도 별도 Python 함수 추가 없이, lead skill 의 Phase 6 섹션 확장만으로 wiring 한다.
+
+- `agents/SKILL.md` 의 "Phase 6: Final report assembly" 섹션 끝에 새 sub-step 추가:
+  - report-writer draft 검토 후 → `task_type == "implementation-planning"` 이고 manifest 의 `convergence.planBodyVerification.enabled == true` 면 → `okstra-convergence` "Plan-body verification mode" sub-skill invoke (이 명세는 §6.2 Phase D 에서 추가됨).
+  - 라운드 결과(`gateResult`) 에 따라 §6.3 양식의 `### 4.5.9 Plan Body Verification` 섹션을 final-report 에 직접 채우고, `majority-disagree` 항목은 `## 5. Clarification Items` 의 `Blocks=approval` row 로 변환. (이 변환 로직은 §6.1 Phase C 의 self-review step 6 가 lead 에게 BLOCKING 으로 명령.)
+  - 변환 완료 후, Gate result 에 따라 top-of-report Approval marker 의 렌더 / 비렌더 결정 (이 룰은 §6.1 Phase C 의 Approval gate bullet 이 BLOCKING 으로 명령, §6.4 Phase B 의 validator 가 실행 후 검사).
+- `agents/SKILL.md` 상단 "Lifecycle / Skill index" 표(line 28 근처)에 plan-body verification 이 Phase 6 의 sub-step 임을 한 줄 명시 — 별도 phase 식별자는 부여하지 **않는다** (spec §2 Q2 = lifecycle 내부 step).
+
+**Single-reference-point invariant**: Python dispatch 함수가 존재하지 않으므로 분기 가능성 자체가 없다. 모든 entry point (CLI / skill / interactive) 가 동일한 `task-manifest.json` 의 `convergence.planBodyVerification` 블록을 읽고, 동일한 `okstra-convergence` SKILL.md "Plan-body verification mode" 명세를 따라 lead 가 수행한다. 메모리상의 `prepare_task_bundle` 수렴 invariant 는 manifest 생성 시점에서만 의미를 가지며, 이는 §6.5 Phase B 에서 이미 완료됨.
+
+### 6.7 CLI 진입점 (single reference point 준수)
+세 진입점 모두 동일한 manifest write 경로(`prepare_task_bundle`)로 수렴해야 한다.
+
+- `scripts/okstra.sh` — `--no-plan-verification` 플래그 추가 (boolean off)
+- `scripts/lib/okstra-ctl/` Bash 라우팅 — flag → CLI args 통과만 (business logic 없음)
+- `bin/okstra` (Node CLI) — `setup` / `config set` 경로에서 `plan-verification` 키 지원
+- `okstra config set plan-verification <on|off> [--scope project|global]` 명령 추가 (기존 `pr-template-path` 패턴 답습)
+
+flag 우선순위: 명령행 `--no-plan-verification` > 프로젝트 config (`project.json` `planVerification`) > 글로벌 config (`~/.okstra/config.json` `planVerification`) > 기본값 ON.
+
+### 6.8 인터랙티브 skill 진입점
+`skills/okstra-run/SKILL.md` 의 Step 6 (worker / option 선택) 에 다음 질문 추가:
+
+> "implementation-planning 의 plan-body 검증 라운드를 활성화할까요? (default: yes — 합성된 plan을 워커가 peer-review)"
+
+`AskUserQuestion` 의 옵션은 yes / no 단일 선택. 사용자 선택은 manifest의 `plan_body_verification.enabled` 로 기록.
+
+## 7. plan-body 모드 reverify prompt 템플릿 (lightweight 만 지원)
+
+`full-reanalysis` 모드는 plan-body에 대해서는 의미가 약함(원본은 워커 자신의 분석 + lead 합성 결과이므로 "원본 재검토"의 정의가 모호). 따라서 plan-body 모드는 lightweight만 지원하고 manifest의 `verificationMode` 와는 독립적으로 동작한다.
+
+```
+You are <worker-role> performing plan-body verification for <task-key> (round 1).
+
+## Instructions
+
+Review the following items extracted from the consolidated implementation plan
+authored after your initial analysis. For EACH item, respond with exactly one verdict:
+
+- **AGREE**: The item is executable as written and internally consistent with
+  other items in the plan.
+- **DISAGREE**: The item is broken. Cite which kind of breakage:
+  (a) referenced file path / symbol mismatches another step or option,
+  (b) command is not executable or is ambiguous,
+  (c) validation signal is not observable,
+  (d) rollback violates commit / dependency order,
+  (e) item contradicts the trade-off matrix.
+- **SUPPLEMENT**: The item is sound but a dependency / edge case / precondition
+  is missing.
+
+Do NOT re-analyze the original requirements. Judge solely from plan internal
+consistency and stated commands / paths.
+
+## Plan items to verify
+
+### P-Step-3 [TICKETID: <id>]: <one-line summary>
+**From section**: 4.5.4 Stepwise Execution Order
+**Original text**:
+> <verbatim quote of the step>
+
+**Check**:
+ - Are referenced file paths consistent with the option's File Structure list?
+ - Is the named command executable as written?
+ - Does the success criterion produce an observable signal?
+
+### P-Opt-2 [TICKETID: <id>]: <one-line summary>
+...
+
+## Response format
+
+### P-Step-3
+**Verdict**: AGREE | DISAGREE(<a|b|c|d|e>) | SUPPLEMENT
+**Explanation**: <2-3 sentences>
+
+### P-Opt-2
+...
+```
+
+## 8. 마이그레이션 / 호환성
+
+- **신규 task-key**: manifest에 plan_body_verification 기본값 ON으로 기록. 정상 동작.
+- **legacy task-key** (이미 implementation-planning을 한 번 돌렸으나 implementation으로 넘어가지 않은 task-key): manifest에 `plan_body_verification` 키 없음.
+  - resume 시 lead가 기본값 ON으로 채워 1라운드 dispatch를 추가 실행한다.
+  - **사용자 영향**: 기존 IP 산출물이 있어도 resume 시 한 라운드가 추가됨. 원치 않는 경우 resume 명령에 `--no-plan-verification`을 명시하거나 project config로 영구 off.
+  - 이 동작은 `CHANGES.md` 의 `사용자 영향:` 라인에 명시한다.
+
+## 9. 검증 가능성 / 테스트 포인트
+
+1. **manifest 기본값 / override**: `plan_body_verification` 키 누락 시 기본값 주입, `--no-plan-verification` 명령행 옵션 우선순위 (unit).
+2. **plan-item 파서**: §3 분리 규칙대로 P-Opt / P-Step / P-Dep / P-Val / P-Rb 가 추출되는지, Ticket ID 태그 보존 (unit).
+3. **verdict aggregation**: §5 매핑 4가지 케이스 모두 (unit).
+4. **majority DISAGREE → clarification row 변환** round-trip: P-* item → `## 5. Clarification Items` row(`Blocks=approval`) → `--resume-clarification` 흐름에서 사용자 응답이 다음 run에 carry-in (unit + e2e).
+5. **Approval 체크박스 라인 조건부 렌더**: gate 결과 4가지에 따라 라인 존재/부재 (unit + validator).
+6. **e2e 시나리오**: 의도적으로 깨진 plan(예: step의 file path가 option의 File Structure와 불일치)을 inject한 task를 돌려, DISAGREE 발생 → clarification 자동 추가 → resume 후 통과까지의 full happy path (e2e).
+7. **워커 non-result**: 모든 워커가 timeout / error 일 때 `aborted-non-result` 분류 + Approval 라인 부재 + clarification에 "could not run" row (unit).
+
+## 10. 위험 / 미해결 항목
+
+1. **report-writer 재호출 안 함** (Q4=b) 으로 인해, majority DISAGREE → clarification 변환 누락이 발생하면 사용자에게 dead-end(Approval 라인은 사라졌는데 무엇을 고쳐야 하는지 안 보이는 상태) 가 노출된다. 변환 round-trip 단위 테스트를 BLOCKING으로 잠근다.
+
+2. **convergence 스킬 안에 mode 두 개 공존** (finding / plan-body). 본문 첫 줄에 MUTUAL EXCLUSION 박스를 두고 future Claude 가 두 큐를 섞지 않도록 명시.
+
+3. **maxRounds=1의 `contested` 정의**: 기존 finding convergence의 `contested`는 maxRounds 도달 시점의 잔류 큐에 부여되는 라벨. plan-body 모드에서 maxRounds=1 인 경우 round 1 종료 직후의 partial-consensus와 사실상 구별 불가. §5 표에서 `contested → partial-consensus 로 fold-in` 으로 명시했지만, 사용자가 manifest 에서 maxRounds=2,3 으로 override 한 경우엔 finding 모드와 동일한 정의가 살아남는다는 점을 스킬 본문에 명시 필요.
+
+4. **plan-item 파서의 robustness**: report-writer 가 markdown 구조를 약간 다르게 작성할 가능성(예: option 헤더 들여쓰기 깊이). 파서는 `## 4.5`, `### 4.5.x` 헤더 + `Stepwise Execution Order` substring 같은 anchored 검색을 사용하고, 추출 실패 시 `aborted-non-result` 와 동등하게 처리한다.
+
+5. **CLI flag 단일 진입점**: 메모리상의 invariant(`prepare_task_bundle` 단일 수렴) 를 유지해야 함. flag → manifest 의 변환은 Python 측 한 곳에서만 수행되도록 분기 막기.
+
+## 11. 후속 작업 (out of scope)
+
+- error-analysis 결과물 (cause analysis 통합본) 에도 유사한 검증 라운드를 추가할지 여부 — 본 spec 범위 밖. plan-body 검증이 안정화된 후 별도 spec으로 검토.
+- requirements-discovery 의 routing decision 자체에 대한 검증 라운드 — 동일하게 후속 검토 대상.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.25.1",
+  "version": "0.27.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.25.1",
-  "builtAt": "2026-05-15T12:17:44.159Z",
+  "package": "0.27.0",
+  "builtAt": "2026-05-16T17:59:10.579Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -25,7 +25,7 @@ This SKILL.md is the operating contract and phase index. Detailed procedures liv
 |-------|-------|
 | [okstra-context-loader](./skills/okstra-context-loader/SKILL.md) | Phase 1 task-bundle discovery, manifest fields, run-directory layout |
 | [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) | Phase 2–5 worker roster, model assignment rules, prompt composition (anchor headers, `[Required reading]`, `[Error reporting]`), worker output contract, terminal statuses, usage tracking |
-| [okstra-convergence](./skills/okstra-convergence/SKILL.md) | Phase 5.5 convergence loop, finding categories, reverify dispatch (anchor headers, required-reading suppression), convergence state schema |
+| [okstra-convergence](./skills/okstra-convergence/SKILL.md) | Phase 5.5 finding convergence loop, finding categories, reverify dispatch (anchor headers, required-reading suppression), convergence state schema, **plus Phase 6 plan-body verification mode (implementation-planning only)** |
 | [okstra-report-writer](./skills/okstra-report-writer/SKILL.md) | Phase 6 final-report authorship, dispatch template, resume-safe dispatch, shared-graph integrity check, Phase 7 token-usage collector |
 | [okstra-status](./skills/okstra-status/SKILL.md) | Project/task status views and `workStatus` updates |
 | [okstra-history](./skills/okstra-history/SKILL.md) | Past-run history, re-run command assembly, resume helper |
@@ -45,7 +45,7 @@ This SKILL.md is the operating contract and phase index. Detailed procedures liv
 | 4. Execution | Spawn analysis workers (Teams preferred) | `okstra-team-contract` |
 | 5. Fallback | Sequential/background dispatch when Teams unavailable | `okstra-team-contract` |
 | 5.5 Convergence | Cross-verify findings across workers | `okstra-convergence` |
-| 6. Synthesis | Dispatch Report writer worker, review draft | `okstra-report-writer` |
+| 6. Synthesis | Dispatch Report writer worker, review draft. **For `implementation-planning`: then run the Phase 6 plan-body verification sub-step (see Phase 6 section below).** | `okstra-report-writer` + `okstra-convergence` (sub-step) |
 | 7. Persist | Run token-usage collector, update manifests | `okstra-report-writer` |
 
 ## Core operating contract
@@ -234,6 +234,34 @@ All categories must appear in the final synthesis. Do not omit contested or work
 
 If only one worker result is usable: reduced-confidence synthesis. If evidence is missing: say `I don't know`. If no meaningful worker differences: say so explicitly.
 
+### Phase 6 sub-step: Plan-body verification (implementation-planning only, BLOCKING)
+
+After the Report writer worker draft is reviewed (or after the lead-authored fallback completes), **if** `task_type == "implementation-planning"` **and** `task-manifest.json` `convergence.planBodyVerification.enabled == true` (default), the lead MUST run one additional verification round on the consolidated plan body before declaring Phase 6 complete and entering Phase 7.
+
+This is a Phase 6 sub-step — it does NOT introduce a new top-level lifecycle phase. The 6-phase model (1 Intake → 2 Render → 3 Team → 4 Workers → 5 Synthesis prep → 5.5 Convergence → 6 Synthesis → 7 Persist) is preserved.
+
+**REQUIRED SUB-SKILL:** Invoke [okstra-convergence](./skills/okstra-convergence/SKILL.md) "Plan-body verification mode (implementation-planning only)" for the round protocol, plan-item ID scheme (`P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*`), verdict semantics (`AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`), classification rules, gate-result resolution, and the state-file schema at `runs/<task-type>/state/plan-body-verification.json`.
+
+Distinct from Phase 5.5 finding convergence:
+
+- Phase 5.5 reconciles worker **findings** (F-*) from independent analysis.
+- This sub-step reconciles the **consolidated plan body** (P-*) authored by the Report writer worker.
+- The two rounds use disjoint queues and separate state files — see [okstra-convergence](./skills/okstra-convergence/SKILL.md) "MUTUAL EXCLUSION (BLOCKING)".
+
+Lead's responsibilities in this sub-step (in order):
+
+1. Extract `P-*` plan items from the draft report's `## 4.5 Implementation Plan Deliverables` per the prefix → source-section mapping in the convergence skill.
+2. Dispatch a single plan-body reverify round to every analyser worker in the roster (`claude`, `codex`, and `gemini` when opted in). `Report writer worker` is NOT a participant in this round.
+3. Aggregate verdicts and resolve the gate result to one of `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`.
+4. Write `runs/<task-type>/state/plan-body-verification.json` (schema in the convergence skill).
+5. Populate `### 4.5.9 Plan Body Verification` in the final-report file (template at `templates/reports/final-report.template.md` §4.5.9 — Round count, Gate result, Verdict table, Dissent log).
+6. For every `majority-disagree` plan item, append a row to `## 5. Clarification Items` with `Blocks=approval` and the 1:1 ID match in the verdict table's `Classification` column (`majority-disagree → C-<N>`). Do NOT create a parallel `Open Questions` block — see `prompts/profiles/implementation-planning.md` self-review step 6 for the orphan-on-either-side contract.
+7. Conditionally render the top-of-report `- [ ] Approved` marker line: present iff gate ∈ {passed, passed-with-dissent}, absent iff gate ∈ {blocked-by-disagreement, aborted-non-result}. `validators/validate-run.py` `validate_phase_boundary` enforces this correspondence. Manually flipping a blocked gate to passing in order to render the marker is a contract violation.
+
+If `convergence.planBodyVerification.enabled == false` (set by `--no-plan-verification` or by `okstra config set plan-verification off`), the entire sub-step is skipped and the top-of-report Approval marker is rendered unconditionally (legacy behaviour). This opt-out is intended for fast iteration only and is not recommended for handoff-ready plans.
+
+`/okstra-status` exposes the sub-step's state as a `planVerification` sub-field of the implementation-planning phase, not as a separate lifecycle phase identifier.
+
 ## Phase 7: Artifact persistence and validator handoff
 
 The detailed persistence checklist and the BLOCKING token-usage collector invocation live in [okstra-report-writer](./skills/okstra-report-writer/SKILL.md). Persist the run yourself — do not assume okstra saves the final artifacts for you.

package/runtime/bin/okstra.sh

@@ -121,7 +121,7 @@ PY_ARGS=(
 [[ -n "${WORK_CATEGORY-}" ]] && PY_ARGS+=(--work-category "$WORK_CATEGORY")
 [[ -n "${BASE_REF-}" ]] && PY_ARGS+=(--base-ref "$BASE_REF")
 [[ "$RENDER_ONLY" == "true" ]] && PY_ARGS+=(--render-only)
-[[ "$REFRESH_OKSTRA_ASSETS" == "true" ]] && PY_ARGS+=(--refresh-assets)
+[[ "$PLAN_VERIFICATION_ENABLED" == "false" ]] && PY_ARGS+=(--no-plan-verification)
 
 if [[ "$RENDER_ONLY" == "true" ]]; then
   okstra_py -m okstra_ctl.run "${PY_ARGS[@]}"