okstra 0.34.0 → 0.36.0

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.0",
+  "version": "0.36.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.34.0",
-  "builtAt": "2026-05-19T16:31:42.883Z",
+  "package": "0.36.0",
+  "builtAt": "2026-05-23T15:38:53.956Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -136,7 +136,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).
@@ -150,21 +150,27 @@ Executor is chosen at run-prep time via `--executor <claude|codex|gemini>` (or `
 
 Treat cross verify input as a task bundle, not as a single file. If the user did not specify an explicit task key or task path, use `.project-docs/okstra/discovery/latest-task.json` as the current-task convenience pointer. If task browsing, task-id disambiguation, or project-level task inventory is needed, inspect `.project-docs/okstra/discovery/task-catalog.json` first.
 
-After context-loader completes, read the following files. The ordering below reflects logical priority for synthesis; for execution, lead MUST issue all Read calls **in a single message (parallel reads)** — these files are independent and serial reads waste several seconds per run with no benefit.
+After context-loader completes, read **only the five mandatory files below** in a single parallel-Read message at the start of Phase 1. The other instruction-set files are loaded lazily at the phase that actually needs them — see "Lazy reading discipline" below. This split came from observed lead-token bloat: in `fontsninja-classifier-v2:dev-9461:dev-9495` RD-001 the lead burned 71 M tokens (97 % cache_read) largely because every phase entry re-absorbed a 93 KB instruction-set baseline that included files only one downstream phase ever actually used.
+
+**Mandatory at Phase 1 start (parallel Read, one message):**
 
 1. `task-manifest.json` (found by context-loader)
-2. `task-index.md` only if a quick human summary is useful
-3. `instruction-set/analysis-profile.md`
-4. `instruction-set/analysis-material.md`
-5. `instruction-set/reference-expectations.md`
-6. `instruction-set/task-brief.md`
-7. `instruction-set/final-report-template.md`
-8. the current run manifest under `runs/<task-type>/manifests/`
-9. the current run team-state artifact
+2. `instruction-set/task-brief.md` — needed to compose every worker prompt
+3. `instruction-set/analysis-profile.md` — needed to compose worker prompts and pick the right `Required workers:` block
+4. the current run manifest under `runs/<task-type>/manifests/`
+5. the current run team-state artifact
+
+**Lazy reading discipline (do NOT read at Phase 1):**
+
+- `task-index.md` — only when the user explicitly asks for a human summary or when history disambiguation is required.
+- `instruction-set/analysis-material.md` — read at Phase 2 only if it is referenced by `analysis-profile.md` or by the brief. Many task bundles have no material file (the placeholder `> 자료가 제공되지 않았습니다` is canonical); in that case skip.
+- `instruction-set/reference-expectations.md` — read at Phase 6 synthesis (or whenever the report-writer worker is dispatched) — it informs the match/gap assessment, not worker dispatch.
+- `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.
 
-Extract: 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.
+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 `history/timeline.json` exists, use it to review past runs. 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, treat that as missing information and say `I don't know` rather than inventing expected states.
+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.
 
 ## Phase 2 — Phase 5: Prompt preparation, team creation, execution, fallback
 
@@ -246,6 +252,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
@@ -313,7 +329,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,6 +52,8 @@ 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.
@@ -117,3 +119,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

@@ -79,7 +79,7 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
    ```
    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.
 
-   **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:
@@ -227,3 +229,27 @@ pre-flight terminal status, not a runtime CLI error.
 - 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".
+
+## 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/gemini-worker.md

@@ -79,7 +79,7 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
    ```
    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 `-p -`, `-m`, `-o text`, `--include-directories`, the stdin redirect from the prompt file, and stderr suppression internally. Calling `gemini` directly (without the wrapper) is an error in this skill: the redirect tokens disqualify the prefix match against `Bash(gemini:*)` 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 Gemini CLI (via `okstra-gemini-exec.sh`). The CLI process itself is the analysis engine; this subagent's only job is to dispatch it and forward output. Therefore:
@@ -227,3 +229,27 @@ pre-flight terminal status, not a runtime CLI error.
 - Return error messages as-is on failure.
 - Do not summarize or modify Gemini results.
 - Sections 1–5 of the worker output are the common core shared with the Claude and Codex workers — the dispatched prompt asks identical questions for all three roles, and the Gemini CLI must answer all of them, not only requirement-interpretation findings. Your specialization (requirement interpretation, consistency, safety, documentation quality, alternative viewpoints) belongs only in optional Section 6 as additive depth. A Gemini result whose Findings section is populated solely with requirement-interpretation 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.

package/runtime/agents/workers/report-writer-worker.md

@@ -16,6 +16,10 @@ tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "TodoWrite", "WebFetch"
 
 You are the `Report writer worker` for okstra cross-verification. Your sole responsibility is to **author the final-report data.json** (the JSON SSOT) at the assigned `Result Path`, plus an audit sidecar. You are NOT an analysis worker — you do not produce independent findings, you do not vote in convergence, and you do not re-do the workers' analysis.
 
+- The `**Report Language:**` header in your dispatch prompt is already
+  resolved to `en` or `ko` by the lead. Copy it verbatim into
+  `data.json.meta.reportLanguage`. Never write `auto` here.
+
 ## Authority
 
 You are the canonical author of `runs/<task-type>/reports/final-report-<task-type>-<seq>.data.json` for this run. Claude lead has explicitly delegated file-authorship to you. The lead reviews your output but does not write the file.
@@ -60,6 +64,8 @@ Before writing the data.json, you MUST read every input file enumerated in the `
 
 - `schemas/final-report-v1.0.schema.json` — the JSON Schema you must conform to. The renderer + validator both consume this.
 - `templates/reports/final-report.template.md` — the Jinja2 template the renderer uses. Read this to understand which data.json fields appear where in the rendered markdown, but do NOT edit it.
+- `templates/reports/i18n/en.json`
+- `templates/reports/i18n/ko.json`
 - Every analysis worker's result file under `worker-results/`.
 - `state/convergence-<task-type>-<seq>.json` (if present).
 
@@ -75,7 +81,7 @@ You author the final-report data.json (the JSON SSOT). The schema is `schemas/fi
 
 The rendered markdown (`final-report-<task-type>-<seq>.md`) is produced by `scripts/okstra-render-final-report.py` immediately after you write the data.json. The HTML view (`*.html`) is produced from the markdown by Phase 7 step 1.5 (`scripts/okstra-render-report-views.py`). The data.json is the only file you write; the rest are derived.
 
-Hard rules (the schema enforces most of these — they are listed here so you know *what* to populate, not *how* to validate):
+Rules (the schema enforces most of these — they are listed here so you know *what* to populate, not *how* to validate):
 
 - `header.reportAuthor` is `"Report writer worker"`; `header.reportOwner` is `"Claude lead"`. Set author to `"Claude lead"` only for `release-handoff` runs (single-lead by design) or a recorded report-writer dispatch failure fallback.
 - **Source items (worker:item) preservation.** Every `consensus[].sourceItems`, `differences[].workersPosition[].itemId`, and `evidence.primary[].sourceItems` entry MUST carry the worker:item-id pair (e.g. `claude:F-001`, `codex:1.1`, `gemini:F-3`, or `lead:mcp-1` for lead-only evidence). The schema enforces this via the `SourceItem` regex; bare worker-name lists no longer parse.
@@ -92,6 +98,7 @@ Hard rules (the schema enforces most of these — they are listed here so you kn
 - If evidence is missing, write `"I don't know"` in the relevant statement field rather than fabricating confidence.
 - Cite file paths and line numbers in every `evidence.primary[].source` / `consensus[].evidence` cell.
 - Preserve every analysis worker's ticket tagging — every row's `ticketId` field carries the ticket key or the task-fallback. For single-ticket runs, set `ticketCoverage` to `{"singleTicket": "<ticket>"}`. For runs that do not require ticket tagging (`release-handoff`, `final-verification`), set `ticketCoverage` to `{"omit": true}`.
+- When the `Task Type` is `improvement-discovery`, populate `## 4.9 Improvement Candidates` with the 10-column schema enforced by `validators/validate-improvement-report.py`. Source the row IDs (`I-NNN`), lens whitelist, and Source workers patterns from `scripts/okstra_ctl/improvement_lenses.py` — do NOT introduce new lens names or worker prefixes.
 
 Write the data.json with your `Write` tool against the absolute `Result Path`. Then invoke the renderer (`Bash`): `python3 scripts/okstra-render-final-report.py <data.json path>`. Confirm both files exist and respond with a short status line: `data.json written to <abs path>; markdown rendered to <abs path>. Sections populated: <count>.`
 

package/runtime/bin/okstra-central.sh

@@ -102,11 +102,11 @@ print(json.dumps({k: v for k, v in zip(it, it)}, ensure_ascii=False))
     PROJECT_ROOT "${PROJECT_ROOT-}" \
     TASK_GROUP "${TASK_GROUP-}" \
     TASK_ID "${TASK_ID-}" \
-    ANALYSIS_TYPE "${ANALYSIS_TYPE-}" \
+    TASK_TYPE "${TASK_TYPE-}" \
     OKSTRA_RUN_SEQ "$_run_seq" \
     RUN_TIMESTAMP_ISO "${RUN_TIMESTAMP_ISO-}" \
-    SELECTED_REVIEWERS "${SELECTED_REVIEWERS-}" \
-    LEAD_MODEL_DISPLAY "${LEAD_MODEL_DISPLAY-}" \
+    RECOMMENDED_ANALYSERS "${RECOMMENDED_ANALYSERS-}" \
+    LEAD_MODEL "${LEAD_MODEL-}" \
     RUN_DIR_RELATIVE_PATH "${RUN_DIR_RELATIVE_PATH-}" \
     FINAL_REPORT_RELATIVE_PATH "${FINAL_REPORT_RELATIVE_PATH-}" \
     FINAL_STATUS_RELATIVE_PATH "${FINAL_STATUS_RELATIVE_PATH-}" \
@@ -134,11 +134,11 @@ with lockfile.open("r+") as lock:
         project_root=payload["PROJECT_ROOT"],
         task_group=payload["TASK_GROUP"],
         task_id=payload["TASK_ID"],
-        task_type=payload.get("ANALYSIS_TYPE", ""),
+        task_type=payload.get("TASK_TYPE", ""),
         run_seq=int(payload["OKSTRA_RUN_SEQ"]),
         when=payload["RUN_TIMESTAMP_ISO"],
-        workers=[w for w in payload.get("SELECTED_REVIEWERS", "").split(",") if w],
-        lead_model=payload.get("LEAD_MODEL_DISPLAY", ""),
+        workers=[w for w in payload.get("RECOMMENDED_ANALYSERS", "").split(",") if w],
+        lead_model=payload.get("LEAD_MODEL", ""),
         run_dir_rel=payload.get("RUN_DIR_RELATIVE_PATH", ""),
         final_report_rel=payload.get("FINAL_REPORT_RELATIVE_PATH", ""),
         final_status_rel=payload.get("FINAL_STATUS_RELATIVE_PATH", ""),