okstra 0.34.1 → 0.36.1

package/docs/task-process/release-handoff.md

@@ -0,0 +1,206 @@
+# release-handoff process
+
+## Index
+
+- [1. 목적](#1-목적)
+- [2. okstra-run wizard 흐름](#2-okstra-run-wizard-흐름)
+- [3. prepare 단계](#3-prepare-단계)
+- [4. entry gate](#4-entry-gate)
+- [5. lead-only 실행 흐름](#5-lead-only-실행-흐름)
+- [6. PR template 결정](#6-pr-template-결정)
+- [7. 산출물](#7-산출물)
+- [8. 금지선](#8-금지선)
+- [9. 확인한 코드](#9-확인한-코드)
+
+## 1. 목적
+
+`release-handoff`는 `accepted` verdict가 나온 already-committed implementation branch를 push하거나 PR로 넘기는 terminal phase다. 새 commit을 만들지 않고, 검증된 diff를 그대로 포장한다.
+
+이 phase는 worker dispatch가 없다. `claude`, `codex`, `report-writer` roster를 쓰지 않으며 Claude lead가 inline으로 git/gh inspection, 사용자 질문, PR draft, final report 작성을 모두 수행한다.
+
+## 2. okstra-run wizard 흐름
+
+```mermaid
+flowchart TD
+    Start[/okstra-run/] --> Common[공통 task identity flow]
+    Common --> Type[task-type = release-handoff]
+    Type --> Worktree{active task worktree?}
+    Worktree -->|yes| Defaults[Use defaults / Customize]
+    Worktree -->|no| BaseRef[base-ref pick/text]
+    BaseRef --> Defaults
+    Defaults -->|defaults| Confirm[confirmation]
+    Defaults -->|customize| Models[lead model prompt]
+    Models --> Extras[directive, related tasks, clarification]
+    Extras --> Template[PR template override?]
+    Template --> Scope[save template to project/global?]
+    Scope --> Confirm
+    Confirm --> Render[render-bundle]
+```
+
+`release-handoff`는 worker roster prompt가 없다. wizard의 `render_args()`는 `pr-template-path`를 release-handoff일 때만 포함하고, runtime은 worker list를 강제로 empty로 만든다.
+
+주의할 점은 이 phase도 task worktree provisioning 대상이라는 것이다. 정상 흐름은 같은 task-key의 implementation/final-verification worktree를 재사용한다. 새 task로 시작하면 새 branch가 만들어질 수 있고, entry gate의 "implementation commit exists" 조건에서 막힐 가능성이 높다.
+
+## 3. prepare 단계
+
+```mermaid
+sequenceDiagram
+    participant W as okstra-run
+    participant P as prepare_task_bundle
+    participant T as PR template resolver
+    participant WT as worktree registry
+    participant FS as task artifacts
+
+    W->>P: task-type=release-handoff, brief, optional pr-template-path
+    P->>P: validate profile and brief
+    P->>P: force workers=[]
+    P->>T: resolve PR template
+    P->>WT: reuse or provision task worktree
+    P->>FS: write manifests with empty roster
+    P->>FS: expose PR_TEMPLATE_PATH and PR_TEMPLATE_SOURCE
+    P-->>W: lead prompt for current session
+```
+
+profile에 `Required workers:` block이 없고 `run.py`도 `release-handoff`에서는 worker override를 비운다. 따라서 `agents/SKILL.md`의 일반 TeamCreate / convergence / report-writer 흐름을 타지 않는 것이 의도된 동작이다.
+
+## 4. entry gate
+
+```mermaid
+flowchart TD
+    Brief[task brief] --> Source{Source Verification Report present?}
+    Source -->|no| Block[blocked<br/>route final-verification]
+    Source -->|yes| Verdict{Verdict Token == accepted?}
+    Verdict -->|no| Block
+    Verdict -->|yes| Status{git status --short clean?}
+    Status -->|no| Dirty[blocked<br/>dirty tree]
+    Status -->|yes| Branch{current branch is base branch?}
+    Branch -->|yes| BaseBlock[blocked<br/>never operate on base branch]
+    Branch -->|no| Commits{git log base..HEAD non-empty?}
+    Commits -->|no| ImplBlock[blocked<br/>route implementation]
+    Commits -->|yes| Ready[handoff questions may begin]
+```
+
+lead는 사용자에게 push/PR 여부를 묻기 전에 다음을 확인한다.
+
+- task brief가 `## Source Verification Report`를 가리킨다.
+- 그 report의 `## 2. Final Verdict`에 `Verdict Token = accepted`가 정확히 있다.
+- working tree가 clean이다.
+- 현재 branch가 `main`, `master`, `prod`, `preprod`, `staging`, `dev` 같은 base branch가 아니다.
+- `<base>..HEAD` commit range가 비어 있지 않다.
+
+`conditional-accept`, `blocked`, 애매한 문장 verdict는 모두 즉시 종료 대상이다.
+
+## 5. lead-only 실행 흐름
+
+```mermaid
+stateDiagram-v2
+    [*] --> Gate: entry gate
+    Gate --> Q1: action selection
+    Q1 --> ReportOnly: local only
+    Q1 --> Skip: skip
+    Q1 --> Q2: push + PR
+    Q2 --> Probe: choose PR base
+    Probe --> Q3: no conflict
+    Probe --> Conflict: conflict detected
+    Conflict --> Q2: change base branch
+    Conflict --> Q3: proceed anyway
+    Conflict --> Cancel: cancel
+    Q3 --> Push: use as-is or edit then proceed
+    Q3 --> Cancel: cancel
+    Push --> ReuseOrCreate: git push feature branch
+    ReuseOrCreate --> FinalReport: gh pr list / gh pr create
+    ReportOnly --> FinalReport
+    Skip --> FinalReport
+    Cancel --> FinalReport
+    FinalReport --> [*]
+```
+
+사용자 interaction은 정확히 세 단계다.
+
+1. Q1 action: `local only`, `push + PR`, `skip`
+2. Q2 PR base: `staging`, `preprod`, `main`, 직접 입력 등 profile menu의 branch
+3. Q3 PR title/body: `use as-is`, `edit then proceed`, `cancel`
+
+`push + PR`에서만 merge-conflict probe를 한다.
+
+```mermaid
+flowchart TD
+    PushPR[push + PR selected] --> Fetch[git fetch origin chosen-base]
+    Fetch --> MergeTree[git merge-tree --write-tree --merge-base<br/>origin/base HEAD origin/base]
+    MergeTree --> Conflict{conflict?}
+    Conflict -->|no| Draft[show PR draft]
+    Conflict -->|yes| Ask[ask proceed/change base/cancel]
+    Ask -->|proceed anyway| Draft
+    Ask -->|change base branch| Base[return to Q2]
+    Ask -->|cancel| Report[final report without push/PR]
+```
+
+probe는 working tree를 바꾸지 않아야 한다. `git merge`, `git rebase`, `git pull`은 이 probe에 포함되지 않는다.
+
+## 6. PR template 결정
+
+```mermaid
+flowchart TD
+    Override[--pr-template-path from wizard] --> Chosen{exists?}
+    Chosen -->|yes| UseOverride[use override]
+    Chosen -->|no| Project[project config template]
+    Project -->|exists| UseProject[use project template]
+    Project -->|missing| Global[global config template]
+    Global -->|exists| UseGlobal[use global template]
+    Global -->|missing| Default[okstra skill default template]
+```
+
+customize path에서 사용자가 template을 고르면 okstra-run skill이 render-bundle 전에 project/global scope 저장을 수행한다. runtime은 resolved `PR_TEMPLATE_PATH`와 `PR_TEMPLATE_SOURCE`를 run context에 넣고, lead는 이 파일을 그대로 읽어 HTML comment를 제거한 뒤 placeholder를 채운다. section 구조를 hard-code하면 안 된다.
+
+## 7. 산출물
+
+```mermaid
+flowchart TD
+    Verdict[Source Verification Report<br/>accepted token] --> Report[release-handoff final report]
+    State[feature branch + clean status] --> Report
+    User[Q1/Q2/Q2b/Q3 user selections] --> Report
+    Commands[git/gh commands + exit codes] --> Report
+    Commits[git log base..HEAD commit list] --> Report
+    Probe[Merge Conflict Probe] --> Report
+    PR[PR created / reused / skipped] --> Report
+    Report --> Done[routing recommendation: done]
+```
+
+final report에는 최소 다음이 필요하다.
+
+- originating final-verification report path와 quoted `accepted` verdict row
+- feature branch와 run start `git status --short`
+- 사용자 선택 기록
+- 실행한 모든 git/gh command와 exit code
+- implementation commit list
+- merge-conflict probe 결과
+- PR 생성, 재사용, 생략 결과
+- routing recommendation `done`
+
+## 8. 금지선
+
+```mermaid
+flowchart TD
+    RH[release-handoff] --> Allowed[read git/gh, fetch base, merge-tree probe,<br/>push feature branch, create/reuse PR]
+    RH -. forbidden .-> Commit[git add / commit / stash]
+    RH -. forbidden .-> Force[force push or +refspec]
+    RH -. forbidden .-> BasePush[push directly to base branch]
+    RH -. forbidden .-> NoVerify[--no-verify / -n]
+    RH -. forbidden .-> Publish[release publish / deploy]
+    RH -. forbidden .-> Edit[source edit]
+    RH -. forbidden .-> Team[TeamCreate or Agent dispatch]
+    RH -. forbidden .-> Merge[gh pr merge]
+```
+
+실패한 `git push`를 더 약한 안전장치로 재시도하면 안 된다. non-fast-forward 같은 실패가 나면 멈추고 사용자 지시를 받아야 하며, `--force` 계열 flag는 사용자 요청이 있어도 금지다.
+
+## 9. 확인한 코드
+
+- [`prompts/profiles/release-handoff.md`](../../prompts/profiles/release-handoff.md)
+- [`templates/reports/release-handoff-input.template.md`](../../templates/reports/release-handoff-input.template.md)
+- [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md)
+- [`scripts/okstra_ctl/wizard.py`](../../scripts/okstra_ctl/wizard.py)
+- [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py)
+- [`scripts/okstra_ctl/pr_template.py`](../../scripts/okstra_ctl/pr_template.py)
+- [`src/config.mjs`](../../src/config.mjs)
+- [`scripts/okstra_ctl/worktree.py`](../../scripts/okstra_ctl/worktree.py)

package/docs/task-process/requirements-discovery.md

@@ -0,0 +1,115 @@
+# requirements-discovery process
+
+## Index
+
+- [1. 목적](#1-목적)
+- [2. okstra-run wizard 흐름](#2-okstra-run-wizard-흐름)
+- [3. prepare_task_bundle 처리](#3-prepare_task_bundle-처리)
+- [4. lead 실행 흐름](#4-lead-실행-흐름)
+- [5. 산출물과 routing](#5-산출물과-routing)
+- [6. 확인한 코드](#6-확인한-코드)
+
+## 1. 목적
+
+`requirements-discovery`는 구현 전에 요청을 분류한다. bugfix, feature, improvement, refactor, ops-change 중 무엇인지 판단하고, 다음 안전 phase가 `error-analysis`인지 `implementation-planning`인지 고른다. 직접 `implementation`으로 넘기는 것은 profile상 유효하지 않다. implementation은 승인된 `implementation-planning` report가 있어야 시작할 수 있다.
+
+## 2. okstra-run wizard 흐름
+
+```mermaid
+flowchart TD
+    Start[/okstra-run/] --> Check[ensure-installed / paths / check-project]
+    Check --> Pick{new task or existing task?}
+    Pick -->|new| Brief[brief path]
+    Brief --> Suggest{brief frontmatter suggestions?}
+    Suggest -->|yes| GroupPick[task-group pick]
+    Suggest -->|no| GroupText[task-group text]
+    GroupPick --> Id
+    GroupText --> Id
+    Id[task-id pick/text] --> Type[task-type = requirements-discovery]
+    Pick -->|existing| Type
+    Type --> Keep{existing brief?}
+    Keep -->|keep| Base
+    Keep -->|change/no brief| Brief
+    Type --> Base{active task worktree?}
+    Base -->|yes| Defaults[Use defaults / Customize]
+    Base -->|no| BaseRef[base-ref pick/text]
+    BaseRef --> Defaults
+    Defaults --> Workers[worker multi-pick<br/>still asked even on defaults]
+    Workers --> Custom{customize?}
+    Custom -->|yes| ModelsAndExtras[models, directive, related tasks, clarification]
+    Custom -->|no| Confirm
+    ModelsAndExtras --> Confirm
+    Confirm --> Render[render-bundle]
+```
+
+worker multi-pick에서 picker는 `report-writer`를 옵션으로 보여주지 않는다. 사용자가 `claude`만 골라도 wizard가 `report-writer`를 강제 append한다. optional `gemini`는 사용자가 골랐을 때만 포함된다.
+
+## 3. prepare_task_bundle 처리
+
+```mermaid
+sequenceDiagram
+    participant W as wizard/render-bundle
+    participant P as prepare_task_bundle
+    participant Prof as requirements-discovery.md
+    participant Git as worktree registry
+    participant FS as task artifacts
+
+    W->>P: task-type=requirements-discovery, brief, base-ref, workers
+    P->>Prof: profile exists, Required workers parsed
+    P->>P: verify installation, upsert project.json
+    P->>P: resolve workers from profile + override
+    P->>Git: create or reuse task worktree
+    P->>P: expand _common-contract include
+    P->>FS: write instruction-set and manifests
+    P->>FS: render workflow currentPhase=requirements-discovery
+    P-->>W: prepared lead prompt
+```
+
+runtime에서 이 phase만을 위한 추가 hard gate는 없다. 중요한 gate는 profile file 존재, brief file 존재, base-ref가 first phase에서 resolvable해야 한다는 worktree gate, worker override가 profile roster 범위를 벗어나지 않아야 한다는 gate다.
+
+## 4. lead 실행 흐름
+
+```mermaid
+flowchart TD
+    P1[Phase 1 intake<br/>manifest, brief, profile, run manifest, team-state] --> P2[Phase 2 prompts]
+    P2 --> P3[Phase 3 TeamCreate]
+    P3 --> P4[Phase 4/5 dispatch analysers<br/>claude/codex + optional gemini]
+    P4 --> C[Phase 5.5 convergence<br/>default maxRounds = 1]
+    C --> R[Phase 6 report-writer authors final report]
+    R --> P7[Phase 7 token usage, validate, persist]
+```
+
+`requirements-discovery`는 convergence default가 1 round다. 이 예외는 `render._build_convergence_block()`와 `agents/SKILL.md` 모두에서 명시된다.
+
+## 5. 산출물과 routing
+
+```mermaid
+flowchart LR
+    RD[requirements-discovery final report] --> Class[work-category classification]
+    RD --> Missing[missing materials / clarification items]
+    RD --> Domain[Domain Alignment<br/>terminology resolution]
+    RD --> Route{next safe phase}
+    Route --> EA[error-analysis]
+    Route --> IP[implementation-planning]
+    Route -. invalid .-> Impl[implementation<br/>not allowed directly]
+```
+
+final report는 다음을 특히 강조한다.
+
+- evidence-backed routing decision
+- missing input과 uncertainty boundary
+- 다음 phase 및 safe resume guidance
+- `terminology:*` brief item에 대한 canonical term resolution
+- blocking input이 있으면 `## 5. Clarification Items` unified table에 `Blocks=next-phase`
+
+Non-goal은 source edit, plan authoring, build, deployment다.
+
+## 6. 확인한 코드
+
+- [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md)
+- [`scripts/okstra_ctl/wizard.py`](../../scripts/okstra_ctl/wizard.py)
+- [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py)
+- [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py)
+- [`prompts/profiles/requirements-discovery.md`](../../prompts/profiles/requirements-discovery.md)
+- [`agents/SKILL.md`](../../agents/SKILL.md)
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.34.1",
+  "version": "0.36.1",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.34.1",
-  "builtAt": "2026-05-19T16:34:08.806Z",
+  "package": "0.36.1",
+  "builtAt": "2026-05-24T11:52:05.811Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -27,11 +27,8 @@ This SKILL.md is the operating contract and phase index. Detailed procedures liv
 | [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 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 |
-| [okstra-report-finder](./skills/okstra-report-finder/SKILL.md) | Locate the final report for a given task key |
+| [okstra-inspect](./skills/okstra-inspect/SKILL.md) | Unified read-side skill — sub-commands `status` (workStatus updates), `history` (past runs, re-run, resume), `report` (find/read final-report), `time` (per-task/per-worker elapsed-time breakdown), `logs` (wrapper log sidecar inventory + cleanup suggestions) |
 | [okstra-schedule](./skills/okstra-schedule/SKILL.md) | Generate a consolidated work schedule for a task-group |
-| [okstra-time-summary](./skills/okstra-time-summary/SKILL.md) | Per-task / per-worker elapsed-time breakdown |
 
 ## Quick Reference
 
@@ -136,7 +133,7 @@ Executor is chosen at run-prep time via `--executor <claude|codex|gemini>` (or `
 - Location: `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/` (override `OKSTRA_HOME` only for tests). All segments are sanitised — `/`, `:`, and other special chars collapse to `-`.
 - Branch: `<work-category-prefix>-<task-id-segment>` (e.g. `feat-dev-9436`, `fix-dev-7311`). Branched from `HEAD` of the repo's **main** worktree at the first phase's prep time; base SHA is recorded in `EXECUTOR_WORKTREE_BASE_REF`.
 - A global registry at `~/.okstra/worktrees/registry.json` (flock-guarded) maps each task-key to its path + branch and prevents concurrent runs from colliding. Branch names are globally unique across task-keys on this machine.
-- Sync dirs (`.project-docs`, `.scratch`, `graphify-out` by default; override with `OKSTRA_WORKTREE_SYNC_DIRS`) are symlinked from the **main worktree** so every task observes the same shared state irrespective of which checkout invoked okstra.
+- Worktree sync mirrors the configured project-relative directories from the **main worktree** so task checkouts see the same filesystem state. This is filesystem continuity only: okstra-owned context and writes still stay inside `<PROJECT_ROOT>/.project-docs/okstra/**` unless the brief explicitly authorizes a non-okstra path.
 - The path, branch, base ref, and provisioning status (`created` | `reused` | `skipped-in-worktree` | `skipped-not-git`) are exposed through the launch prompt's `## Executor Worktree` section and the implementation profile's worktree block.
 - **Skip conditions** (worktree provisioning is a no-op; task uses `project_root` directly):
   - `project_root` is already inside a non-main worktree (the run reuses the caller's worktree to avoid nesting).
@@ -168,6 +165,22 @@ After context-loader completes, read **only the five mandatory files below** in
 - `instruction-set/final-report-template.md` — never read by Lead. The Report writer worker reads it as part of its own [Required reading]; Lead only references its path when dispatching.
 - `history/timeline.json` — read only on user request or when carry-in resolution requires it.
 
+**Implementation profile lazy reading discipline (BLOCKING — applies only when `task_type == "implementation"`):**
+
+The `implementation` profile's thin core (`prompts/profiles/implementation.md`) is intentionally minimal so the Phase 1 baseline stays small. Three sidecar files carry the bulk of the rules and MUST be read at the listed phase — do NOT pre-load them at Phase 1.
+
+| Sidecar | Read at | Owned by |
+|---------|---------|----------|
+| `prompts/profiles/_implementation-executor.md` | **Phase 5**, after Stage Map parse, BEFORE issuing the Executor's first `Edit` / `Write` | Executor role binding, Pre-implementation context exploration, TDD loop, Stage execution contract, allowed actions, commit-message format |
+| `prompts/profiles/_implementation-verifier.md` | **Phase 5**, between Executor stage completion and the first verifier dispatch | Verifier roles, Two-tier command lookup, deny-list, discrepancy rule, Read-only command log, verifier-specific forbidden actions |
+| `prompts/profiles/_implementation-deliverable.md` | **Phase 6**, after Phase 5.5 convergence completes, BEFORE constructing the report-writer dispatch prompt | Required deliverable shape, Validation / TDD evidence rules, Verifier results structure, Self-review pass, Lead post-stage persistence |
+
+**Entry guard (BLOCKING).** Before transitioning into Phase 5 or Phase 6 for an `implementation` run, lead MUST emit a single Read tool call for the sidecar(s) above whose `Read at` matches the entering phase. If lead enters the phase without that Read on record (visible in the lead session jsonl), phase 진입 거부 — lead writes a `contract-violation` to the run-level errors log with `--message "implementation-sidecar-not-loaded"` and stops. Re-entry requires the sidecar Read first.
+
+The guard is not satisfied by remembering content from a prior run — each implementation run reads the sidecar fresh, because the sidecars are part of the runtime shipped via `okstra install` and may have been updated between runs.
+
+This pattern is implementation-only. Other profiles (`requirements-discovery`, `error-analysis`, `implementation-planning`, `final-verification`, `release-handoff`) load their whole profile body at Phase 1 as before — they are short enough not to benefit from a split.
+
 Extract from the five mandatory files: task key, task type, work category, workflow lifecycle snapshot, selected worker roster, assigned models, worker result paths, worker prompt history paths, current run prompt directory, final report path, final status path, validator path, resume helper path, config-file references, deployment-manifest references, and their expected values or invariants.
 
 If previous run reports exist, use as historical context only. If discovery metadata or current artifacts conflict with a newer user instruction, prefer the user instruction. If `reference-expectations.md` explicitly says expectations were not provided (you can confirm this without reading the file if the brief's "Expected state" section is empty), treat that as missing information and say `I don't know` rather than inventing expected states.
@@ -252,6 +265,16 @@ If convergence is disabled, proceed directly to Phase 6 with the raw worker resu
 
 If `Report writer worker` is in the selected roster (`recommendedWorkers` / `resultContract.requiredWorkerRoles`), **Lead MUST dispatch it to write `runs/<task-type>/reports/final-report-<task-type>-<seq>.md`**. Lead does NOT write that file. Lead's role in this phase is: prepare the report-writer prompt (carrying convergence output, all worker results, and reference expectations), dispatch, then review the produced file.
 
+Before constructing the dispatch prompt, the lead MUST:
+
+- Resolve report language: read `project.json.reportLanguage` (fallback
+  `~/.okstra/config.json.reportLanguage`, then literal `auto`). If the
+  resolved value is `auto`, inspect the task brief and pick `en` or `ko`
+  based on its main prose language (default `en` when the brief is
+  mostly code/identifiers). Pass the final `en` or `ko` value as
+  `**Report Language:**` in the report-writer dispatch prompt, and ensure
+  the worker writes the same value into `data.json.meta.reportLanguage`.
+
 Do not write the final verdict until every analysis worker role has either a saved result or a terminal status entry. The convergence output provides four finding categories:
 
 1. Full Consensus
@@ -289,7 +312,7 @@ Lead's responsibilities in this sub-step (in order):
 
 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.
+The `okstra-inspect status` sub-command 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
 
@@ -319,7 +342,7 @@ jq -s 'group_by(.errorType) | map({type: .[0].errorType, count: length})' <runDi
 
 The errors log is informational. Its presence/absence does not affect the final verdict. Do not block report writing on it.
 
-After persistence, reply briefly in Korean with: completion status, final report path, team-state path, validator result, resume command path, any remaining blocker.
+After persistence, reply briefly in the resolved Report Language with: completion status, final report path, team-state path, validator result, resume command path, any remaining blocker.
 
 ## Common Mistakes
 

package/runtime/agents/workers/claude-worker.md

@@ -52,15 +52,16 @@ Unlike the Codex / Gemini workers, you are an in-process Claude subagent — you
 
 6. If the task brief includes an `## Available MCP Servers` section in the lead prompt, treat that as the canonical list of MCP tools you may invoke for this run. If a needed server is not listed, record `MCP not available for this run` rather than calling it.
 
+7. When `Task Type` is `improvement-discovery`, the lead's Phase 1.5 reflect-back log at `<RUN_DIR>/state/phase-1.5-grilling.md` is the authoritative scope and lens definition. Read its `Resolved scope` and `Resolved lenses` blocks and do NOT re-interpret the brief's raw `scan-scope` / `priority-lenses` fields. Findings that violate the resolved lens whitelist or scope are rejected by `validators/validate-improvement-report.py`.
+
 ## Required Reading Before Any Analysis
 
-Before producing any output, you MUST read every input file enumerated in the `[Required reading]` block of the lead's prompt from the very first character to the very last character. For analysis workers this includes the task brief, analysis profile, analysis material (if present), reference expectations, and the carry-in clarification response (if present). Analysis workers do NOT read `final-report-template.md` — that file is for the Report writer worker only (see `okstra-team-contract` "Audience-scoped enumeration"). Producing findings without the template is the intended contract; the report writer in Phase 6 owns final-report structure.
+Before producing any output, you MUST:
+
+1. Extract the absolute path from the lead's `**Worker Preamble Path:**` anchor header and Read that file end-to-end with a single `Read` call (no `offset`, no `limit`). This is the canonical SSOT for the Required Reading + Error Reporting + Output sections contract.
+2. Read every input file the lead enumerated under `## Inputs` (or equivalent heading) in the dispatch prompt body, end-to-end, following the rules stated in the preamble. For analysis workers this is task-brief + analysis-profile + analysis-material (if present) + reference-expectations + clarification-response (if carry-in). Analysis workers do NOT read `final-report-template.md` — that file is for the report writer only.
 
-- Use a single `Read` call per file with no `offset` and no `limit`. If a file is genuinely too large for one read, page through it with explicit `offset` / `limit` calls that together cover the entire file, and record the page boundaries in your Findings.
-- For the carry-in clarification response, walk every row of `## 5. Clarification Items` (`C-001`, `C-002`, ...) in full, including rows whose `User input` cell is blank — a blank `User input` with `Status=open` is itself a signal you must surface, not skip. Skimming these rows is the most common failure mode here; the fact that the file you will eventually contribute to has a structurally similar section 5 is NOT a license to skim.
-- Before listing any Findings, write a Reading Confirmation block to your **audit sidecar** at `runs/<task-type>/worker-results/claude-worker-audit-<task-type>-<seq>.md` (sibling to your main worker-results file — substitute `claude-worker-<task-type>-<seq>.md` → `claude-worker-audit-<task-type>-<seq>.md`). The sidecar's body begins with `# Claude Worker Audit — <task-key>` followed by one short line per input file confirming end-to-end reading (e.g. `- Read task-brief.md end-to-end (147 lines).`). Do NOT include a `## 0. Reading Confirmation` heading in the main worker-results file — the validator now fails worker-results that contain one. If you cannot truthfully confirm a file end-to-end, record a `tool-failure` in the errors sidecar instead of fabricating Findings.
-- **Heartbeat — write the audit sidecar EARLY and APPEND per stage (BLOCKING).** Because this worker runs as an in-process Agent or a fresh-session tmux pane, the lead has no `BashOutput`-style liveness signal while waiting for your return. The audit sidecar is the only signal that survives a silent hang. Write the sidecar immediately after extracting `Project Root` and the assigned paths — BEFORE the per-file end-to-end reads — with just the heading line (`# Claude Worker Audit — <task-key>`) and one `- PROGRESS: started <ISO-8601-UTC>` line. Then APPEND one short progress line per stage as you advance: `read-<filename>`, `analysis-start`, `findings-draft-start`, `findings-draft-complete`, `write-result-start`. Each line: `- PROGRESS: <stage> <ISO-8601-UTC>`. The append cadence MUST NOT exceed 5 minutes — if a single analysis stage is taking longer, emit a `- PROGRESS: in-stage:<stage> <ISO-8601-UTC>` heartbeat. A 5-minute stale sidecar mtime is the canonical "this worker has hung" signal for the operator (the lead is blocked on the Agent call and cannot detect this itself, but a human watching via `tail -F <audit-sidecar>` from another terminal can). Sidecar write/append uses `Write` (for the initial creation) and `Edit` / heredoc `>>` for the per-stage append — heredoc append is the lighter option once the file exists.
-- Do not skip a file because its name suggests its content is already familiar from a prior run. Each file is canonical for the current run only.
+**Heartbeat — write the audit sidecar EARLY and APPEND per stage (BLOCKING).** Because this worker runs as an in-process Agent or a fresh-session tmux pane, the lead has no `BashOutput`-style liveness signal while waiting for your return. The audit sidecar is the only signal that survives a silent hang. Write the sidecar at `runs/<task-type>/worker-results/claude-worker-audit-<task-type>-<seq>.md` immediately after extracting `Project Root` and the assigned paths — BEFORE the per-file end-to-end reads — with just the heading line (`# Claude Worker Audit — <task-key>`) and one `- PROGRESS: started <ISO-8601-UTC>` line. Then APPEND one short progress line per stage as you advance: `read-<filename>`, `analysis-start`, `findings-draft-start`, `findings-draft-complete`, `write-result-start`. The append cadence MUST NOT exceed 5 minutes — if a single analysis stage is taking longer, emit a `- PROGRESS: in-stage:<stage> <ISO-8601-UTC>` heartbeat. A 5-minute stale sidecar mtime is the canonical "this worker has hung" signal for the operator. Sidecar write/append uses `Write` (initial) and `Edit` / heredoc `>>` (per-stage append).
 
 ## Worker Output Structure
 
@@ -117,3 +118,27 @@ There is NO `cli-failure` category for this worker — Claude worker has no exte
 - Return error messages as-is on failure.
 - Do not summarize or modify your own analysis output beyond the structured sections above.
 - Sections 1–5 are the common core — same dimensions for every analysis worker. Your specialization (broad reasoning depth, hidden-assumption surfacing, execution-risk decomposition) only enters Section 6 if you have additive content beyond the core. See `skills/okstra-team-contract/SKILL.md` "Worker Output Contract" for the authoritative split.
+
+## Stage evidence emission (BLOCKING, implementation task only)
+
+When this run's `task_type` is `implementation` and you are acting as the **Executor**, after the Stage Validation `post` commands all return exit code 0 you MUST emit a single JSON document matching `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2:
+
+```json
+{
+  "schemaVersion": 1,
+  "sourcePlanPath": "<approved-plan path>",
+  "stageNumber": <int>,
+  "stageTitle": "<from Stage Map>",
+  "completedAt": "<ISO-8601 with tz>",
+  "stageCommitRange": { "base": "<sha>", "head": "<sha>" },
+  "filesChanged": ["<rel/path>", "..."],
+  "newIdentifiers": ["<name>", "..."],
+  "stepResults": [{"step": <int>, "status": "done", "commit": "<sha>"}],
+  "validationsPassed": ["<label>", "..."],
+  "notes": []
+}
+```
+
+Emit this as a fenced ```json``` block in your worker result under the heading `### Stage Carry Evidence`. The lead (`Claude lead`) is responsible for persisting the block as `runs/<impl-task-key>/carry/stage-<N>.json` — you do not write the file yourself.
+
+This applies only when `task_type` is `implementation`. For other task types, skip this block entirely.

package/runtime/agents/workers/codex-worker.md

@@ -39,7 +39,7 @@ The wrapper internally runs:
 codex exec -C "<project-root>" [--add-dir "<worktree-path>"] --model "<model>" --sandbox workspace-write - < "<prompt-path>" 2>/dev/null
 ```
 
-The wrapper exists because Claude Code's Bash permission matcher rejects simple-prefix matches when the command contains stdin/stderr redirects. Calling `codex exec ... - < <path> 2>/dev/null` directly triggers a permission prompt every dispatch even when `Bash(codex exec:*)` is allowlisted. The wrapper folds the redirects inside, so the harness sees a single non-redirect command that matches `Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)`.
+The wrapper exists because Claude Code's Bash permission matcher rejects simple-prefix matches when the command contains stdin/stderr redirects. Calling `codex exec ... < <path> 2>/dev/null` directly triggers a permission prompt every dispatch even when `Bash(codex exec:*)` is allowlisted. The wrapper folds the redirects inside, so the harness sees a single non-redirect command that matches `Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)`.
 
 **Do NOT use** non-existent flags like `-q` or `-a never`. **Do NOT** invoke `codex exec ... < ... 2>/dev/null` directly — always go through the wrapper.
 
@@ -68,7 +68,7 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
 6. Extract the assigned model execution value for `Codex worker`.
    - First, look for a `**Model:** Codex worker, <execution-value>` line in the lead prompt and use `<execution-value>`.
    - If only a display model is listed, look up the canonical execution value from the referenced task bundle metadata (`task-manifest.json` → `resultContract.requiredWorkerRoles[]` for the codex role).
-   - If neither is available, immediately return `CODEX_MODEL_MISSING: assigned Codex model execution value was not provided`. Do NOT fall back to training-data defaults — historical codex defaults like `o4-mini` are NOT acceptable substitutes for the assigned model. Returning the sentinel is the correct behavior; the lead is responsible for fixing its prompt and redispatching.
+   - If no assigned model execution value can be determined, immediately return `CODEX_MODEL_MISSING: assigned Codex model execution value was not provided`. Do NOT fall back to training-data defaults — historical Codex defaults like `o4-mini` are NOT acceptable substitutes for the assigned model. Returning the sentinel is the correct behavior; the lead is responsible for fixing its prompt and redispatching.
    - This rule applies equally to convergence reverify rounds. The reverify prompt MUST carry the same `**Model:**` line as the initial run (see `okstra-convergence` skill, "Required reverify-prompt anchor headers"). If the line is absent in a reverify prompt, return `CODEX_MODEL_MISSING` rather than guessing.
 
 7. If installed, dispatch the wrapper as a **background** Bash command and poll for completion. The two-minute foreground Bash timeout is insufficient for implementation-phase Codex runs and forced workers into ad-hoc background dispatch with lost output. The polling contract below is the formal replacement.
@@ -77,9 +77,9 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
    ```bash
    $HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" "<absolute-worktree-path>" "worker"
    ```
-   Call `Bash` with `run_in_background: true`. Capture the returned `bash_id` (a.k.a. `shell_id`). Pass the positional arguments verbatim — do NOT use environment variables, `cd`, `&&` chains, or pipes from `cat`. Substitute the literal extracted Project Root, model execution value, prompt-history path, and worktree path. The fourth argument is **mandatory for implementation phase** (extract from `EXECUTOR_WORKTREE_PATH` in the lead prompt's run context or the `**Worktree:**` / `cwd for every mutating command:` line) and **may be omitted only for non-implementation analysis phases** that do not mutate the worktree. Omitting it during implementation will cause every Edit/Write to fail with EPERM. The wrapper handles `-C`, `--add-dir`, `--model`, `--sandbox workspace-write`, the stdin redirect from the prompt file, and stderr suppression internally. Calling `codex exec` directly (without the wrapper) is an error in this skill: the redirect tokens disqualify the prefix match against `Bash(codex exec:*)` and produce a permission prompt every dispatch.
+   Call `Bash` with `run_in_background: true`. Capture the returned `bash_id` (a.k.a. `shell_id`). Pass the positional arguments verbatim — do NOT use environment variables, `cd`, `&&` chains, or pipes from `cat`. Substitute the literal extracted Project Root, model execution value, prompt-history path, and worktree path. The fourth argument is **mandatory for implementation phase** (extract from `EXECUTOR_WORKTREE_PATH` in the lead prompt's run context or the `**Worktree:**` / `cwd for every mutating command:` line) and **may be omitted only for non-implementation analysis phases** that do not mutate the worktree. The wrapper handles `-C`, `--add-dir`, `--model`, `--sandbox workspace-write`, the stdin redirect from the prompt file, and stderr suppression internally. Calling `codex exec` directly (without the wrapper) is an error in this skill: the redirect tokens disqualify the prefix match against `Bash(codex exec:*)` and produce a permission prompt every dispatch.
 
-   **Poll loop (BashOutput-only, 30-minute hard cap):**
+   **Poll loop (BashOutput-only, 30-minute cap):**
    - Record `start_ts` at dispatch time via a single `Bash` call: `date +%s` (output captured).
    - Repeat:
      1. Call `BashOutput(bash_id: <shell_id>)`. Inspect `status`. The harness's `BashOutput` primitive already waits internally for new output before returning; back-to-back calls are the canonical wait mechanism for a background shell.
@@ -108,6 +108,8 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
 
    d. **Normal return.** Otherwise (`exit_code == 0` AND result file exists), concatenate the wrapper's accumulated stdout from `BashOutput` and return it as-is without modification.
 
+9. When `Task Type` is `improvement-discovery`, the lead's Phase 1.5 reflect-back log at `<RUN_DIR>/state/phase-1.5-grilling.md` is the authoritative scope and lens definition. Read its `Resolved scope` and `Resolved lenses` blocks and do NOT re-interpret the brief's raw `scan-scope` / `priority-lenses` fields. Findings that violate the resolved lens whitelist or scope are rejected by `validators/validate-improvement-report.py`.
+
 ## Stop Condition
 
 This wrapper is a thin Bash-execution shell over the Codex CLI (via `okstra-codex-exec.sh`). The CLI process itself is the analysis engine; this subagent's only job is to dispatch it and forward output. Therefore:
@@ -130,7 +132,7 @@ This wrapper does NOT invoke MCP tools directly. MCP availability inside the Cod
 - The assigned model execution value is canonical for CLI execution. Do not substitute a different Codex model unless the task bundle explicitly changes it.
 - Pass the prompt received from Lead directly to codex after persisting the exact prompt to the assigned path.
 - Include context (code, diff, file paths) if provided.
-- For long prompts, the wrapper script reads from the saved project-local prompt history file via stdin redirect internally. The caller invokes the wrapper with three required positional args + the worktree path for implementation phase:
+- For long prompts, dispatch through the wrapper with literal absolute paths (plus the worktree path for implementation phase):
   ```bash
   $HOME/.okstra/bin/okstra-codex-exec.sh "<literal-project-root>" "<assigned-model-execution-value>" "<literal-prompt-history-path>" "<literal-worktree-path>" "worker"
   ```
@@ -138,11 +140,12 @@ This wrapper does NOT invoke MCP tools directly. MCP availability inside the Cod
 
 ## Required Reading Before Any Analysis
 
-Before producing any output, you MUST ensure the underlying Codex CLI run reads every input file enumerated in the `[Required reading]` block of the lead's prompt from the very first character to the very last character. For analysis workers this includes the task brief, analysis profile, analysis material (if present), reference expectations, and the carry-in clarification response (if present). Analysis workers do NOT read `final-report-template.md` — that file is for the Report writer worker only (see `okstra-team-contract` "Audience-scoped enumeration"). Producing findings without the template is the intended contract; the report writer in Phase 6 owns final-report structure.
+Before invoking the Codex CLI, you MUST:
+
+1. Extract the absolute path from the lead's `**Worker Preamble Path:**` anchor header and verify the CLI run will Read that file end-to-end (canonical SSOT for the Required Reading + Error Reporting + Output sections contract). The lead's prompt body — which you persist verbatim and feed into Codex via stdin — already contains this anchor; do not strip it.
+2. Verify the lead's prompt body lists the per-run input files under `## Inputs` (task-brief, analysis-profile, analysis-material if present, reference-expectations, clarification-response if carry-in). Analysis workers do NOT read `final-report-template.md` — that file is for the report writer only.
 
-- The lead's prompt body, which you persist verbatim and feed into Codex via stdin, already contains the explicit list of files and the end-to-end reading rule. Do not strip or summarize that block before passing it to the CLI.
-- For the carry-in clarification response, the CLI must walk every row of `## 5. Clarification Items` (`C-001`, `C-002`, ...) in full, including rows whose `User input` cell is blank — a blank `User input` with `Status=open` is itself a signal you must surface. The fact that the prior run's final report and the upcoming output share section 5 structure is NOT a license to skim.
-- The wrapper writes a Reading Confirmation block to the **audit sidecar** at `runs/<task-type>/worker-results/codex-worker-audit-<task-type>-<seq>.md` (sibling to the main worker-results file). The sidecar's body begins with `# Codex Worker Audit — <task-key>` followed by one short line per input file confirming end-to-end reading (e.g. `- Read task-brief.md end-to-end (147 lines).`). The main Codex output MUST NOT contain a `## 0. Reading Confirmation` heading — the validator now fails worker-results that contain one. If any file was skipped, record a `tool-failure` in the errors sidecar instead of fabricating Findings.
+The CLI writes a Reading Confirmation block to the **audit sidecar** at `runs/<task-type>/worker-results/codex-worker-audit-<task-type>-<seq>.md`. The sidecar's body begins with `# Codex Worker Audit — <task-key>` followed by one short line per input file confirming end-to-end reading. The main Codex output MUST NOT contain a `## 0. Reading Confirmation` heading — the validator fails worker-results that contain one. If any file was skipped, record a `tool-failure` in the errors sidecar instead of fabricating Findings.
 
 ## Worker Output Structure
 
@@ -226,4 +229,28 @@ pre-flight terminal status, not a runtime CLI error.
 - Ignore stderr warnings from MCP integration.
 - Return error messages as-is on failure.
 - Do not summarize or modify Codex results.
-- Sections 1–5 of the worker output are the common core shared with the Claude and Gemini workers — the dispatched prompt asks identical questions for all three roles, and the Codex CLI must answer all of them, not only implementation-realism findings. Your specialization (implementation realism, code-path implications, edge cases, technical trade-offs) belongs only in optional Section 6 as additive depth. A Codex result whose Findings section is populated solely with implementation-feasibility items is in breach of contract; see `skills/okstra-team-contract/SKILL.md` "Worker Output Contract".
+- Sections 1–5 of the worker output are the common core shared with the Claude and Gemini workers — the dispatched prompt asks identical questions for all three roles, and the Codex CLI must answer all of them, not only implementation-feasibility findings. Your specialization (implementation realism, code-path implications, edge cases, technical trade-offs) belongs only in optional Section 6 as additive depth. A Codex result whose Findings section is populated solely with implementation-feasibility items is in breach of contract; see `skills/okstra-team-contract/SKILL.md` "Worker Output Contract".
+
+## Stage evidence emission (BLOCKING, implementation task only)
+
+When this run's `task_type` is `implementation` and you are acting as the **Executor**, after the Stage Validation `post` commands all return exit code 0 you MUST emit a single JSON document matching `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2:
+
+```json
+{
+  "schemaVersion": 1,
+  "sourcePlanPath": "<approved-plan path>",
+  "stageNumber": <int>,
+  "stageTitle": "<from Stage Map>",
+  "completedAt": "<ISO-8601 with tz>",
+  "stageCommitRange": { "base": "<sha>", "head": "<sha>" },
+  "filesChanged": ["<rel/path>", "..."],
+  "newIdentifiers": ["<name>", "..."],
+  "stepResults": [{"step": <int>, "status": "done", "commit": "<sha>"}],
+  "validationsPassed": ["<label>", "..."],
+  "notes": []
+}
+```
+
+Emit this as a fenced ```json``` block in your worker result under the heading `### Stage Carry Evidence`. The lead (`Claude lead`) is responsible for persisting the block as `runs/<impl-task-key>/carry/stage-<N>.json` — you do not write the file yourself.
+
+This applies only when `task_type` is `implementation`. For other task types, skip this block entirely.