okstra 0.26.0 → 0.28.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 합니다.

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.

package/docs/kr/architecture.md

@@ -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] [--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>]
+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,11 +433,6 @@ scripts/okstra.sh --task-type error-analysis --related-tasks scanner-regression,
 - `history/timeline.json` 갱신
 - project-level discovery pointer 생성 또는 갱신
 
-### `--refresh-assets`
-
-project-local `.claude/skills/`와 `.claude/agents/` 아래의 okstra mapped asset을 workspace source 기준으로 다시 생성합니다.
-기본 rerun에서는 기존 project-local asset을 유지합니다.
-
 ### `--no-plan-verification`
 
 `implementation-planning` task-type 의 Phase 6 plan-body verification 라운드를 끕니다. 기본값은 활성. 다른 task-type 에서는 무시됩니다.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.26.0",
+  "version": "0.28.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.26.0",
-  "builtAt": "2026-05-15T14:37:59.243Z",
+  "package": "0.28.0",
+  "builtAt": "2026-05-17T03:21:22.744Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -57,8 +57,8 @@ Unlike the Codex / Gemini workers, you are an in-process Claude subagent — you
 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. This includes the task brief, analysis profile, analysis material (if present), reference expectations, the carry-in clarification response (if present), and the final report template.
 
 - 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. If the prior report uses the deprecated `4.5.9 Open Questions` / `5.1` / `5.2` layout with `OQ-*` / `A*` / `Q*` IDs, walk all three blocks the same way (legacy carry-in transitional rule).
-- Before listing any Findings, state one sentence per input file confirming you read it end-to-end (e.g. "Read task-brief.md end-to-end (147 lines)."). If you cannot truthfully say this for a file, record a `tool-failure` in the errors sidecar instead of fabricating 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.
 - 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.
 
 ## Worker Output Structure
@@ -67,7 +67,6 @@ When returning results, start the file with a YAML frontmatter block, then organ
 
 **Frontmatter (mandatory)** — set `workerId: "claude"`. Copy `id`, `aliases`, `taskType`, `task-id`, `task-group`, `project-id`, `date` verbatim from the input files (`analysis-material.md` is canonical; if it lacks any field, record a `tool-failure` and stop). Full schema and a concrete example live in the `okstra-team-contract` skill's "Result Frontmatter" subsection.
 
-0. **Reading Confirmation** - one short line per input file confirming end-to-end reading (e.g. `- Read task-brief.md end-to-end (147 lines).`). If any file was skipped, record a `tool-failure` and do NOT produce sections 1–5.
 1. **Findings** - what you identified
 2. **Missing Information or Assumptions** - gaps in the analysis
 3. **Safe or Reasonable Areas** - parts that look correct
@@ -76,6 +75,8 @@ When returning results, start the file with a YAML frontmatter block, then organ
 
 Include file paths and line numbers when discussing code evidence.
 
+**Item IDs (mandatory).** Every row in sections 1–5 (and any optional section 6) MUST carry a worker-internal item ID unique within this file. Use the leading column for table-form items (`F-001`, `M-001`, `S-001`, `U-001`, `R-001` per section) or a `[<ID>]` prefix for bullet/numbered items. The ID shape is your choice but it MUST appear — the lead's §1.1 / §1.2 / §3.1 synthesis preserves these IDs in its `Source items (worker:item)` column to keep cross-worker traceability intact. See `prompts/profiles/_common-contract.md` "Cross-worker traceability" SSOT.
+
 **Ticket tagging:** For runs whose task type is `requirements-discovery`, `error-analysis`, `implementation-planning`, or `implementation`, every item in sections 1–5 MUST carry a ticket identifier. Use the `Ticket ID` column in table-form items and the `[TICKETID: <id>]` prefix in bullet/numbered items. Fill priority: `Issue / Ticket` from the input → `Task ID` (no prefix, e.g. `8852`) → `unknown`. Multiple tickets are comma-separated. Full rules live in the `okstra-team-contract` skill's Ticket Tagging section.
 
 This contract mirrors the `okstra-team-contract` skill's Worker Output Contract — that skill is the authoritative source if the two ever diverge.

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

@@ -125,8 +125,8 @@ This wrapper does NOT invoke MCP tools directly. MCP availability inside the Cod
 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. This includes the task brief, analysis profile, analysis material (if present), reference expectations, the carry-in clarification response (if present), and the final report template.
 
 - 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. If the prior report uses the deprecated `4.5.9 Open Questions` / `5.1` / `5.2` layout with `OQ-*` / `A*` / `Q*` IDs, walk all three blocks the same way (legacy carry-in transitional rule).
-- The Codex output you return MUST begin with one sentence per input file confirming end-to-end reading (e.g. "Read task-brief.md end-to-end (147 lines)."). If any file was skipped, record a `tool-failure` in the errors sidecar instead of fabricating Findings.
+- 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.
 
 ## Worker Output Structure
 
@@ -134,7 +134,6 @@ When returning results, start the file with a YAML frontmatter block, then organ
 
 **Frontmatter (mandatory)** — set `workerId: "codex"`. Copy `id`, `aliases`, `taskType`, `task-id`, `task-group`, `project-id`, `date` verbatim from the input files (`analysis-material.md` is canonical; if it lacks any field, record a `tool-failure` and stop). Full schema and a concrete example live in the `okstra-team-contract` skill's "Result Frontmatter" subsection.
 
-0. **Reading Confirmation** - one short line per input file confirming end-to-end reading (e.g. `- Read task-brief.md end-to-end (147 lines).`). If any file was skipped, record a `tool-failure` and do NOT produce sections 1–5.
 1. **Findings** - what Codex identified
 2. **Missing Information or Assumptions** - gaps in the analysis
 3. **Safe or Reasonable Areas** - parts that look correct
@@ -143,6 +142,8 @@ When returning results, start the file with a YAML frontmatter block, then organ
 
 Include file paths and line numbers when discussing code evidence.
 
+**Item IDs (mandatory).** Every row in sections 1–5 (and any optional section 6) MUST carry a worker-internal item ID unique within this file. Codex tends to use hierarchical numbering (`1.1`, `1.2`, `1.3`, ...); that shape is fine — keep what's natural. What matters is that each item is addressable. The lead's §1.1 / §1.2 / §3.1 synthesis preserves these IDs as `codex:<your-id>` entries in its `Source items (worker:item)` column. See `prompts/profiles/_common-contract.md` "Cross-worker traceability" SSOT.
+
 **Ticket tagging:** For runs whose task type is `requirements-discovery`, `error-analysis`, `implementation-planning`, or `implementation`, every item in sections 1–5 MUST carry a ticket identifier. Use the `Ticket ID` column in table-form items and the `[TICKETID: <id>]` prefix in bullet/numbered items. Fill priority: `Issue / Ticket` from the input → `Task ID` (no prefix, e.g. `8852`) → `unknown`. Multiple tickets are comma-separated. Full rules live in the `okstra-team-contract` skill's Ticket Tagging section.
 
 This contract mirrors the `okstra-team-contract` skill's Worker Output Contract — that skill is the authoritative source if the two ever diverge.

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

@@ -125,8 +125,8 @@ This wrapper does NOT invoke MCP tools directly. MCP availability inside the Gem
 Before producing any output, you MUST ensure the underlying Gemini 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. This includes the task brief, analysis profile, analysis material (if present), reference expectations, the carry-in clarification response (if present), and the final report template.
 
 - The lead's prompt body, which you persist verbatim and feed into Gemini 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 structural similarity between the prior final report and the upcoming output is the most common reason this step gets skipped — do not repeat that. If the prior report uses the deprecated `4.5.9 Open Questions` / `5.1` / `5.2` layout with `OQ-*` / `A*` / `Q*` IDs, walk all three blocks the same way (legacy carry-in transitional rule).
-- The Gemini output you return MUST begin with one sentence per input file confirming end-to-end reading (e.g. "Read task-brief.md end-to-end (147 lines)."). If any file was skipped, record a `tool-failure` in the errors sidecar instead of fabricating Findings.
+- 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 structural similarity between the prior final report and the upcoming output is the most common reason this step gets skipped — do not repeat that.
+- The wrapper writes a Reading Confirmation block to the **audit sidecar** at `runs/<task-type>/worker-results/gemini-worker-audit-<task-type>-<seq>.md` (sibling to the main worker-results file). The sidecar's body begins with `# Gemini 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 Gemini 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.
 
 ## Worker Output Structure
 
@@ -134,7 +134,6 @@ When returning results, start the file with a YAML frontmatter block, then organ
 
 **Frontmatter (mandatory)** — set `workerId: "gemini"`. Copy `id`, `aliases`, `taskType`, `task-id`, `task-group`, `project-id`, `date` verbatim from the input files (`analysis-material.md` is canonical; if it lacks any field, record a `tool-failure` and stop). Full schema and a concrete example live in the `okstra-team-contract` skill's "Result Frontmatter" subsection.
 
-0. **Reading Confirmation** - one short line per input file confirming end-to-end reading (e.g. `- Read task-brief.md end-to-end (147 lines).`). If any file was skipped, record a `tool-failure` and do NOT produce sections 1–5.
 1. **Findings** - what Gemini identified
 2. **Missing Information or Assumptions** - gaps in the analysis
 3. **Safe or Reasonable Areas** - parts that look correct
@@ -143,6 +142,8 @@ When returning results, start the file with a YAML frontmatter block, then organ
 
 Include file paths and line numbers when discussing code evidence.
 
+**Item IDs (mandatory).** Every row in sections 1–5 (and any optional section 6) MUST carry a worker-internal item ID unique within this file. Gemini may use `F-1`, `F-2`, ... or numbered hierarchical IDs — either is fine. What matters is that each item is addressable. The lead's §1.1 / §1.2 / §3.1 synthesis preserves these IDs as `gemini:<your-id>` entries in its `Source items (worker:item)` column. See `prompts/profiles/_common-contract.md` "Cross-worker traceability" SSOT.
+
 **Ticket tagging:** For runs whose task type is `requirements-discovery`, `error-analysis`, `implementation-planning`, or `implementation`, every item in sections 1–5 MUST carry a ticket identifier. Use the `Ticket ID` column in table-form items and the `[TICKETID: <id>]` prefix in bullet/numbered items. Fill priority: `Issue / Ticket` from the input → `Task ID` (no prefix, e.g. `8852`) → `unknown`. Multiple tickets are comma-separated. Full rules live in the `okstra-team-contract` skill's Ticket Tagging section.
 
 This contract mirrors the `okstra-team-contract` skill's Worker Output Contract — that skill is the authoritative source if the two ever diverge.

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

@@ -46,9 +46,9 @@ If you find yourself thinking "I'll just return the report inline and let lead s
 Before writing the final report, 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. This always includes `final-report-template.md` and every analysis worker's result file under `worker-results/`, plus the convergence output under `state/convergence-<task-type>-<seq>.json` (if present).
 
 - Use a single `Read` call per file with no `offset` and no `limit`. If a file is too large for one read, page through it with explicit `offset` / `limit` calls covering the full file.
-- For the carry-in `clarification-response.md` (if present), walk every row of `## 5. Clarification Items` (`C-001`, `C-002`, ...) including rows whose `User input` cell is blank — a blank cell with `Status=open` is itself a signal you must surface in section 0. The fact that the file you write has a structurally similar section 5 is NOT an excuse to skim. If the prior report uses the deprecated `4.5.9 Open Questions` / `5.1` / `5.2` layout with `OQ-*` / `A*` / `Q*` IDs, walk all three blocks the same way (legacy carry-in transitional rule).
+- For the carry-in `clarification-response.md` (if present), walk every row of `## 5. Clarification Items` (`C-001`, `C-002`, ...) including rows whose `User input` cell is blank — a blank cell with `Status=open` is itself a signal you must surface in the conditional `## 0. Clarification Response Carried In From Previous Run` section (the template's `RENDER_IF` guard activates it when the carry-in path is non-empty). The fact that the file you write has a structurally similar section 5 is NOT an excuse to skim. When no carry-in path was provided, OMIT the `## 0.` heading entirely — do NOT write an empty-state stub.
 - Open every analysis-worker result file under `worker-results/` end-to-end. Do not summarize them from convergence output alone — convergence captures classifications, not full evidence.
-- Before writing, state one sentence per input file confirming end-to-end reading. If you cannot truthfully say this for a file, record a `tool-failure` in the errors sidecar instead of fabricating the report.
+- Write a Reading Confirmation block to your **audit sidecar** at `runs/<task-type>/worker-results/report-writer-worker-audit-<task-type>-<seq>.md` (sibling to the main worker-results file). The sidecar's body begins with `# Report Writer Worker Audit — <task-key>` followed by one short line per input file confirming end-to-end reading. The main final-report and the main worker-results file MUST NOT contain a `## 0. Reading Confirmation` heading — the validator now fails reports that contain one. If you cannot truthfully confirm a file end-to-end, record a `tool-failure` in the errors sidecar instead of fabricating the report.
 - When the convergence-state file is present, read it fully and reproduce the `roundHistory[]` array, `round2SkippedReason`, and `finalClassificationCounts` in the final report's Section 1 Round History sub-table. Do not derive these values from worker results alone — they live in `state/convergence-<task-type>-<seq>.json`.
 
 ## Authoring Contract
@@ -58,6 +58,11 @@ The final-report file MUST follow `instruction-set/final-report-template.md` if
 Hard rules:
 
 - The file's `Author:` header line is `Report writer worker` (your role) — NOT `Claude lead`.
+- **Source items (worker:item) preservation.** When synthesising `## 1.1 Consensus` / `## 1.2 Differences` / `## 3.1 Primary Evidence` rows from worker outputs, the `Source items` / `Supporting workers` / `Workers (position)` / `Source` column MUST list each contributing worker's item ID as `worker:item-id` (e.g. `claude:F-001, codex:1.1, gemini:F-3`). Bare worker-name lists (e.g. `claude, codex, gemini`) are deprecated — they break traceability back to the original worker-results files. See `prompts/profiles/_common-contract.md` "Cross-worker traceability" SSOT.
+- **Verdict Card (top)** is mandatory in every final-report. Its `Verdict Token` / `Direction` / `Next Step` cells MUST byte-match the corresponding cells in `## 2. Final Verdict` and the first item of `## 6. Recommended Next Steps`. The validator treats the card as a non-authoritative index — divergence is `contract-violated`.
+- **No deprecated sections.** Do NOT emit `4.5.8 User Approval Request` (the body stub is deleted; the top-of-report Approval block is the only one), `4.5.9 Open Questions`, `5.1 추가 자료 요청`, or `5.2 사용자 확인 질문`. The validator fails reports that contain any of these headings.
+- **Conditional Section 0.** Render `## 0. Clarification Response Carried In From Previous Run` ONLY when the carry-in path is non-empty. Never write an empty-state stub (`"No prior clarification response was provided."`). The validator fails empty Section 0.
+- **Reading Confirmation** lives in the audit sidecar (`runs/<task-type>/worker-results/report-writer-worker-audit-<task-type>-<seq>.md`), never in the final-report or main worker-results file.
 - Include all four convergence categories (Full Consensus, Partial Consensus, Contested, Worker-Unique). Do not omit Contested or Worker-Unique findings.
 - Include a Round History sub-table in Section 1 (one row per executed round) and a `round2SkippedReason` line below it. When convergence is disabled, omit both. The values are quoted verbatim from `state/convergence-<task-type>-<seq>.json` — do not recompute.
 - Treat `verification-error` votes as their own verdict. They are listed in vote summaries as `verification-error`, not folded into AGREE/DISAGREE counts.

package/runtime/bin/okstra.sh

@@ -121,7 +121,6 @@ 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

package/runtime/prompts/launch.template.md

@@ -85,4 +85,4 @@ Invoke the `okstra` skill now. Read the manifests below for all task metadata, p
 
 - Source path: `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}`
 - If the source path above is empty, no prior clarification response was attached to this run.
-- If the source path is set, a copy is staged at `{{INSTRUCTION_SET_RELATIVE_PATH}}/clarification-response.md`. Read it before running workers; reconcile each `C-*` row in section 5 (`## 5. Clarification Items`) of the prior report against new evidence and record the outcome in section 0 of this run's final report. If the prior report uses the deprecated `4.5.9 Open Questions` / `5.1` / `5.2` layout with `OQ-*` / `A*` / `Q*` IDs, follow the legacy-carry-in mapping rule in `final-report-template.md` section 0.
+- If the source path is set, a copy is staged at `{{INSTRUCTION_SET_RELATIVE_PATH}}/clarification-response.md`. Read it before running workers; reconcile each `C-*` row in section 5 (`## 5. Clarification Items`) of the prior report against new evidence and record the outcome in the conditional `## 0. Clarification Response Carried In From Previous Run` section of this run's final report (render that heading only when carry-in is non-empty — the validator fails empty Section 0 stubs).

package/runtime/prompts/profiles/_common-contract.md

@@ -37,11 +37,43 @@ profile document.
   - On `아니오` / `n` / `keep` → leave the panes intact; remind the user that they will be cleaned up automatically when Claude `/exit` fires the `SessionEnd` hook.
   - The question MUST be a clean yes/no — do NOT offer "close some / keep some" partial answers, do NOT propose alternatives like "close only codex panes". The whole-set decision keeps the wrap-up predictable.
   - This step is mandatory for every phase (`requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`). It is silent-skipped when `$TMUX_PANE` is unset (lead running outside tmux); the lead MUST NOT fabricate a synthetic pane list in that case.
+- Brief handoff contract (shared — applies whenever the run consumes a task brief produced by `okstra-brief`):
+  - the brief is a **pre-discovery artifact**: it converts a domain-reporter's words (non-expert *or* developer) into expert-consumable form so this and later phases can run with zero fill-in questions to the operator. The brief is **not** authoritative on solution decisions; it is authoritative on the reporter's intent.
+  - **Reporter confirmation precondition (BLOCKING)**: the brief's frontmatter carries `reporter-confirmations: <complete | partial | pending | skipped>` set by `okstra-brief` Step 6.5. Every phase that consumes the brief MUST read this field before doing analysis. The handling matrix is:
+    - `complete` → proceed normally.
+    - `partial` → proceed; treat still-unmarked `intent-check:` / `conversion-block:` rows as the `skipped` branch.
+    - `skipped` → do NOT silently infer the missing answers. Promote each unmarked `intent-check:` / `conversion-block:` row into this run's `## 5. Clarification Items` as `Kind=decision`. Use `Blocks=approval` in `implementation-planning`, where the row gates the User Approval Request; otherwise use `Blocks=next-phase`. The recommended answer is drawn from the brief's matching content and clearly labelled `보고자 직접 확인 권장`.
+    - `pending` (or field missing) → ABORT analysis; render the Verdict Card with `Verdict Token = blocked` + `Direction = hold` and write a single `## Reporter Confirmation Required` block (no leading number) summarising which rows are pending. The `## 5. Clarification Items` table carries one row per pending item with `Blocks=approval` in `implementation-planning`, otherwise `Blocks=next-phase`. The operator must rerun `okstra-brief` Step 6.5. Do NOT emit `## 0.` for this case — Section 0 is reserved for clarification-response carry-in only.
+    `[CONFIRMED <YYYY-MM-DD> → RC-N]` markers on `Open Questions` rows are the per-row signal that the reporter has answered; their answers live verbatim under `## Reporter Confirmations` in the brief.
+  - `Source Material` is reporter-verbatim. Do NOT paraphrase, summarize, reorder, or restructure it. Quote it directly when needed.
+  - `Augmentation` entries carry one of four labels — `evidence-link`, `format-conversion`, `terminology-mapping`, `intent-inference`. Treat them as follows:
+    - `evidence-link` / `format-conversion` → trust without re-verification.
+    - `terminology-mapping` → verify against `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` (authoritative); raise a `Clarification Items` row if the mapping is missing or contradicts the glossary.
+    - `intent-inference` → treat as an **unverified hypothesis**. Every `intent-inference` augmentation MUST be paired in the brief with an `Open Questions` row prefixed `intent-check:`. Promote that row into the run's `## 5. Clarification Items` table as `Kind=decision, Blocks=next-phase` (or `Blocks=approval` for `implementation-planning`) with the recommended answer set to "보고자에게 직접 확인 후 응답" unless the codebase can be inspected to confirm or refute the inference.
+  - `Open Questions` row prefixes are signals — do not strip them when promoting:
+    - `intent-check:` → `Kind=decision`, recommended answer = reporter confirmation. NEVER silently resolve an `intent-check:` by inference at this layer.
+    - `terminology:` → `Kind=decision`, recommended answer = canonical term from `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` (or "extend okstra glossary via brief Step 4.5").
+    - `conversion-block:` → `Kind=decision`, recommended answer = "보고자에게 직접 확인". The brief is explicitly signalling that translation failed; further inference is forbidden until the reporter clarifies.
+    - `adr-candidate:` → handled by `implementation-planning`; carry forward without modification. Approved decision files land at `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md` (okstra-internal), never at external `<PROJECT_ROOT>/docs/adr/`.
+    - `general:` → free-form; classify per the standard `Clarification Items` rules.
+  - Any decision in this run that contradicts the brief's `Source Material` must be raised back to the reporter via a `Clarification Items` row; it must NOT be silently overridden. Disagreement with the reporter is allowed only after the row is resolved.
+  - This contract is the single authority on brief consumption. Phase-specific addenda may *tighten* these rules but may not relax them.
 - Clarification request policy (shared — applies whenever a profile uses `## 5. Clarification Items`):
-  - section 5 is a **single unified table** per `final-report-template.md`. Every clarification item — whether the user must attach a file, choose between options, or supply a single number/path — is one row of that table. Do not split it into sub-sections, do not create a parallel table elsewhere in the report, and do not duplicate the same item into `## 4.5.8 User Approval Request` or any other section.
+  - **Canonical column schema (SSOT — must match `templates/reports/final-report.template.md` §5.1 exactly):** every `## 5. Clarification Items` table has exactly these 8 columns, in this order:
+    `| ID | Ticket ID | Kind | Statement | Expected form | Blocks | Status | User input |`.
+    Profile-specific addenda may tighten cell content but MUST NOT add, remove, rename, or reorder columns. The `ID` cell uses `C-NNN` (3-digit zero-padded), the `Status` cell ∈ `{open, answered, resolved, obsolete}`, and the `Kind` / `Blocks` legal values are listed below.
+  - section 5 is a **single unified table** per `final-report-template.md`. Every clarification item — whether the user must attach a file, choose between options, or supply a single number/path — is one row of that table. Do not split it into sub-sections (`5.1 추가 자료 요청` / `5.2 사용자 확인 질문` / `4.5.9 Open Questions` are removed and the validator fails reports that reintroduce them), do not create a parallel table elsewhere in the report, and do not duplicate the same item into the top-of-report `User Approval Request (사용자 승인 게이트)` block or any other section.
   - each row's `Kind` column picks one of `{material, decision, data-point}`: `material` for files / snapshots / logs / screenshots the user must attach (the `User input` cell will hold a path or URL); `decision` for choices and yes/no confirmations only the user can make; `data-point` for a single number, ID, date, or short string the user can answer inline. Items that mix "yes/no + file path if yes" are one row of `Kind=material` with the combined expectation written into `Expected form`.
-  - each row's `Blocks` column picks one of `{approval, next-phase, none}`. `approval` is reserved for items that gate the `implementation-planning` User Approval Request — never use `approval` outside that task-type. `next-phase` blocks the next run from starting cleanly. `none` is informational/audit-only.
+  - each row's `Blocks` column picks one of `{approval, next-phase, none}`. `approval` is reserved for items that gate an approval action, especially the `implementation-planning` User Approval Request; outside `implementation-planning`, unresolved brief reporter-confirmation rows use `next-phase` instead. `next-phase` blocks the next run from starting cleanly. `none` is informational/audit-only.
   - write every entry in full, descriptive sentences that a non-developer can act on without further context. Avoid abbreviations and internal jargon. The `Statement` cell must state *what* is needed, *why* the answer / attachment changes the next step, and (for `material`) *where* the user can find it and *where* to place it. The `Expected form` cell must state the shape of the answer (예/아니오, 보기 중 하나, 숫자/날짜, 파일 경로, 짧은 서술 등); supply concrete option choices when applicable.
   - the same `final-report.md` file is the canonical artifact carried into the next run; the user appends answers inline before rerunning. The preferred turn-around is `scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>` (opens the latest report in `$EDITOR`, then auto-reruns the same phase with `--clarification-response` carry-in). The lower-level form `--clarification-response <path>` remains available for scripted runs.
-  - if a clarification response was carried in for this run, walk every `C-*` row of the prior report's `## 5. Clarification Items` table in section 0 of this report, reconcile each one against new evidence, and update its `Status` to `resolved` or `obsolete` before issuing the next decision/verdict.
-  - transitional rule for legacy carry-in (one release cycle): if the prior report uses the deprecated `4.5.9 Open Questions` / `5.1 Additional Materials` / `5.2 Questions for the User` layout, follow the mapping described in section 0 of `final-report-template.md` — collapse `OQ-*` / `A*` / `Q*` into `C-*` rows in this run's new section 5 (legacy ID preserved in the Statement for traceability).
+  - if a clarification response was carried in for this run, render the conditional `## 0. Clarification Response Carried In From Previous Run` section (the template's `RENDER_IF` guard activates it), walk every `C-*` row of the prior report's `## 5. Clarification Items` table, reconcile each one against new evidence, and update its `Status` to `resolved` or `obsolete` before issuing the next decision/verdict. When no carry-in path was provided, omit the `## 0.` heading entirely — the validator fails reports that emit an empty Section 0 stub (e.g. "No prior clarification response was provided for this run.").
+- Verdict Card (shared — applies to every final-report regardless of profile):
+  - The top-of-report `## Verdict Card` block is mandatory in every final-report. Its `Verdict Token`, `Direction`, and `Next Step` cells MUST byte-match the corresponding cells in `## 2. Final Verdict` and the first item of `## 6. Recommended Next Steps`. The validator treats the card as a non-authoritative index — when card values diverge from the authoritative sections, the run is `contract-violated`.
+- Cross-worker traceability (shared — applies to every analysis worker output and to the lead's `## 1.` / `## 3.` tables in the final-report):
+  - **Worker-side item IDs (free-form but unique within the worker).** Every row item in sections 1–5 (and any optional section 6) of an analysis worker's output MUST carry an item ID that is unique within that one worker's result file. The ID convention is the worker's choice — `F-001` / `F-002` per the suggested schema, `1.1` / `1.2` / `1.3` as Codex tends to use, or any other shape — but it MUST appear as the leading column of the row (for table-form items) or as a `[<ID>]` prefix (for bullet/numbered items). Workers that emit findings without IDs make cross-worker reconciliation impossible.
+  - **Lead-side ID assignment + source preservation.** When the lead (or `report-writer-worker`) synthesises `## 1.1 Consensus` / `## 1.2 Differences` / `## 3.1 Primary Evidence` rows from worker outputs, the lead assigns a fresh `C-NNN` / `D-NNN` / `E-NNN` row ID. The `Source items` column (or, where the template still calls it `Supporting workers` / `Workers (position)` / `Source`, that same column) MUST list every contributing worker:item pair (e.g. `claude:F-001, codex:1.1, gemini:F-3`) so a reviewer can trace the synthesised row back to each worker's original wording without re-reading every worker-results file. Bare worker names without item IDs (e.g. `claude, codex, gemini`) are deprecated for these tables; the validator does not yet fail on them but the readability pass treats it as a contract violation.
+  - **Why this matters.** A real run had `claude=F-1..F-11`, `codex=1.1..1.8`, `gemini=F-3..F-9` — three incompatible ID schemes. When the lead synthesised `C-1..C-8`, the link from `C-3` back to "which sentence in which worker file" was lost. Source-item preservation restores that link without forcing every worker to adopt a single ID prefix, which would over-constrain worker output style.
+- Audit sidecar (shared — applies to every analysis-worker output and every final-report):
+  - Reading Confirmation lines (one short line per input file confirming end-to-end reading) live in the **worker audit sidecar** at `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md`, NOT in the worker's main worker-results file. The worker-results body starts at section 1 (Findings). The validator fails worker-results files that contain a `## 0. Reading Confirmation` heading.
+  - The audit sidecar carries any other meta the worker wants to log (tool-call counts, MCP query summaries, timing notes). The lead's final-report does NOT duplicate this content — it is consumed by the validator and by post-run audit tooling, not by end-user readers.

package/runtime/prompts/profiles/error-analysis.md

@@ -8,6 +8,15 @@
 - Optional workers (opt-in via `--workers`):
   - gemini — when added to the roster it joins the analyser set; omitted by default
 {{INCLUDE:_common-contract.md}}
+- Brief consumption (phase-specific addendum — shared rules live in `_common-contract.md` under "Brief handoff contract"):
+  - **Precondition check (BLOCKING — runs before any analysis)**: read the brief's frontmatter `reporter-confirmations:` field and inspect every `Open Questions` row prefixed `intent-check:` / `conversion-block:` for the `[CONFIRMED …]` marker.
+    - `reporter-confirmations: complete` → proceed normally.
+    - `reporter-confirmations: partial` → proceed; treat still-unmarked `intent-check:` / `conversion-block:` rows per the `skipped` branch below.
+    - `reporter-confirmations: skipped` (or `partial` with remainder) → do NOT silently infer the missing answers. Promote each unmarked `intent-check:` / `conversion-block:` row into this run's `## 5. Clarification Items` as `Kind=decision, Blocks=next-phase`, with the recommended answer drawn from the brief's matching `intent-inference` / `conversion-block:` text and clearly labelled `보고자 직접 확인 권장`. Then proceed with the root-cause analysis using the inference as a *hypothesis* only.
+    - `reporter-confirmations: pending` (or field missing) → ABORT analysis. Write only `## 0. Reporter Confirmation Required` summarising which rows are pending and stop. The final report carries `Blocks=next-phase`.
+  - the reporter's symptom description in `Source Material` is the ground truth for what to reproduce. Do not paraphrase it when stating the symptom in the report; quote it.
+  - any `intent-inference` augmentation that re-characterises the symptom (e.g. classifying "가끔 안 됨" as "intermittent failure on a specific code path") is a **hypothesis**, not a confirmed symptom. If `[CONFIRMED …]` appears on the matching `intent-check:` row, treat the confirmation as the symptom; otherwise, follow the precondition's `skipped` branch above and keep the inference labelled as hypothesis in the root-cause analysis.
+  - `conversion-block:` rows mean the brief could not map a reporter statement to project vocabulary; never attempt to invent the missing mapping in this phase — the precondition above already handled them.
 - Primary focus areas:
   - symptom and trigger clarification
   - root-cause candidates
@@ -22,6 +31,9 @@
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
   - if any blocking uncertainty remains at the time of writing the final report, populate `## 5. Clarification Items` in `final-report-template.md` (a single unified table; `Blocks=next-phase` for items the next run cannot start without)
   - prefer plain Korean over abbreviations (e.g. write "초당 평균 요청 수" instead of "QPS", "재현 절차" instead of "repro")
+  - every clarification row carries a `Recommended` answer + one-line rationale; rows that lack a recommendation are rejected as half-formed.
+  - **Codebase-first ambiguity resolution (defect rule)**: any ambiguity about repro, file behavior, or symbol semantics that can be answered by `Read` / `Grep` / log inspection MUST be resolved that way and recorded with file:line (or log-line) evidence. Writing a clarification row for something the codebase or shipped logs already answer is a defect of this phase.
+  - **`evidence-checked:` cell required**: every clarification row carries an `evidence-checked: <path:line> | none` cell. `evidence-checked: <path:line>` means the codebase / log / reproducer was inspected and the row records what was found. `evidence-checked: none` is allowed ONLY when the row's nature is "only the reporter can answer this" (reporter-side data, business priority, environment they observed); the row body must state which one in one line. A row with `evidence-checked: none` that *could* have been answered by code or logs is a defect.
 - Non-goals:
   - implementation details unless they are necessary to validate the cause
   - **source code edits, builds, migrations, or deployments** — this run produces evidence and cause analysis only; the fix belongs to a later `implementation-planning` run followed by an `implementation` run

package/runtime/prompts/profiles/implementation-planning.md

@@ -8,11 +8,21 @@
 - Optional workers (opt-in via `--workers`):
   - gemini — when added to the roster it joins the analyser set; omitted by default
 {{INCLUDE:_common-contract.md}}
+- Brief consumption (phase-specific addendum — shared rules live in `_common-contract.md` under "Brief handoff contract"):
+  - **Precondition check (BLOCKING — runs before option drafting)**: read the brief's frontmatter `reporter-confirmations:` field and inspect every `Open Questions` row prefixed `intent-check:` / `conversion-block:` for the `[CONFIRMED …]` marker.
+    - `reporter-confirmations: complete` → proceed normally.
+    - `reporter-confirmations: partial` → proceed; treat still-unmarked `intent-check:` / `conversion-block:` rows per the `skipped` branch below.
+    - `reporter-confirmations: skipped` (or `partial` with remainder) → do NOT silently infer the missing answers. Promote each unmarked `intent-check:` / `conversion-block:` row into this run's `## 5. Clarification Items` as `Kind=decision, Blocks=approval`, with the recommended answer drawn from the brief's matching `intent-inference` / `conversion-block:` text and clearly labelled `보고자 직접 확인 권장`. Then proceed; the operator cannot toggle `User Approval Request` until those rows are resolved.
+    - `reporter-confirmations: pending` (or field missing) → ABORT planning. Write only `## 0. Reporter Confirmation Required` summarising which rows are pending and stop. The final report carries `Blocks=approval`.
+  - never plan around an unconfirmed `intent-inference` augmentation as if it were a settled requirement. After the precondition runs, a `[CONFIRMED …]` marker on the matching `intent-check:` row is the signal that the inference can be treated as settled; otherwise it remains a `Blocks=approval` clarification item per the precondition's `skipped` branch.
+  - `conversion-block:` rows are handled by the precondition; planning around an untranslated reporter phrase is forbidden until it is resolved.
 - Pre-planning context exploration (mandatory before option drafting):
   - read the task brief, related-task briefs, and any cited spec / design doc end-to-end
   - inspect the current state of every file the task names (or the closest matching files if names are stale) — record current responsibilities, public interfaces, and known coupling points
   - skim recent commits touching those files (`git log -- <path>`) to surface in-flight work or contested areas
+  - **codebase-first ambiguity resolution**: any ambiguity that can be answered by `Read` / `Grep` MUST be resolved that way and recorded with file:line evidence. Only ambiguities that genuinely require a human decision are escalated as `Clarification Items` rows. Writing a clarification row for something the code already answers is a defect of this phase.
   - flag any requirement that is ambiguous, contradictory, or missing success criteria — register each one as a row in the report's `## 5. Clarification Items` table with `Blocks=approval` instead of guessing
+  - read in priority order — (authoritative) `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` and `<PROJECT_ROOT>/.project-docs/okstra/decisions/` titles if present; (supplementary) `<PROJECT_ROOT>/CONTEXT.md` (or `CONTEXT-MAP.md` → per-context `CONTEXT.md`) and `<PROJECT_ROOT>/docs/adr/` titles if present. Absent external files are the normal state — do not error. Treat the brief's `terminology:*` resolutions from `requirements-discovery` (if any) as authoritative; if missing, resolve any remaining fuzzy term as a `Blocks=approval` clarification row.
 - Primary focus areas:
   - requirement gaps
   - affected components and boundaries
@@ -38,6 +48,9 @@
   - this run stays in `implementation-planning` regardless of user phrasing — the shared anti-escalation rule applies
   - dispatching parallel sub-agents beyond the required worker roster — okstra owns worker fan-out
   - writing artifacts to `docs/superpowers/specs/` or `docs/superpowers/plans/` — the run's `reports/` directory is the canonical location
+- Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
+  - every clarification row carries a `Recommended` answer + one-line rationale; rows that lack a recommendation are rejected as half-formed.
+  - **`evidence-checked:` cell required**: every clarification row carries an `evidence-checked: <path:line> | none` cell. `evidence-checked: <path:line>` means the codebase was inspected and the row records what was found. `evidence-checked: none` is allowed ONLY when the row's nature is "only a human can answer this" (reporter intent, business priority, organisational decision); the row body must state which one in one line. A row with `evidence-checked: none` that *could* have been answered by the codebase is a defect of this phase, restated from the pre-planning rule above.
 - Section heading contract (BLOCKING — validator scans for these literal English substrings):
   - The final report MUST include section headings containing each of the following exact strings: `Option Candidates`, `Trade-off`, `Recommended Option`, `Stepwise Execution Order`, `Dependency`, `Validation Checklist`, `Rollback`, `User Approval Request`.
   - Korean translations are allowed in parentheses (e.g. `### Recommended Option (권장 옵션)`), but the English keyword must be present verbatim in the heading line.
@@ -60,6 +73,13 @@
   - **the marker line is rendered only when the plan-body verification gate (§4.5.9) returns `passed` or `passed-with-dissent`.** When the gate returns `blocked-by-disagreement` or `aborted-non-result`, the top-of-report Approval block is rendered **without** the canonical `- [ ] Approved` bullet (the rest of the block — title, summary, audit lines — stays). The `validators/validate-run.py` `validate_phase_boundary` function enforces this exact correspondence between gate result and marker line presence.
   - every ambiguity flagged during pre-planning that the user must resolve before approval registered as a `Blocks=approval` row in the `## 5. Clarification Items` table (do NOT create a separate `Open Questions` block under `4.5.x` — the unified table is the single home)
   - **§4.5.9 Plan Body Verification (BLOCKING).** After report-writer finishes the draft, the lead MUST run a worker peer-review round on the consolidated plan body (sections 4.5.1 – 4.5.7) and populate `### 4.5.9 Plan Body Verification` in the final report. The round protocol, plan-item ID scheme (`P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*`), verdict semantics, gate-result classification, and dissent log format are defined in `skills/okstra-convergence/SKILL.md` "Plan-body verification mode". The four gate-result values are `passed`, `passed-with-dissent`, `blocked-by-disagreement`, `aborted-non-result`. When the gate would have been `blocked-by-disagreement` or `aborted-non-result`, the lead MUST NOT silently flip it to one of the passing values to "unblock" the run — that is a contract violation.
+  - **ADR evaluation (grill-with-docs adopted, sole owner)**: this phase is the **single owner** of ADR evaluation in the okstra lifecycle. The brief never evaluates or drafts ADRs — it only forwards `adr-candidate:*` signals. Every `adr-candidate:*` entry inherited from the brief's `Open Questions` is a mandatory evaluation target. In addition, evaluate every decision the recommended option introduces against the three ADR criteria:
+    1. **Hard to reverse** — would changing the decision later cost meaningfully more than deciding now?
+    2. **Surprising without context** — would a future reader, seeing only the code, wonder "why was it built this way?"?
+    3. **Real trade-off** — were there named alternatives, and was one picked for specific reasons?
+    If **all three** hold, attach a decision draft as a report appendix section titled `Decision Drafts` (one decision per subsection). Each draft uses the `## Context / ## Decision / ## Consequences / ## Alternatives Considered` shape, names the alternatives that were rejected and why, and starts with `## Status: Proposed`. The next decision number is `(max existing in <PROJECT_ROOT>/.project-docs/okstra/decisions/ + 1)` zero-padded to 4 digits. If any of the three criteria is missing, do NOT raise a decision draft — instead record `skipped adr-candidate: <topic> — reason: <criterion that failed>` on one line under `Decision Drafts` so the next reader knows the candidate was evaluated and intentionally dropped.
+    The drafts are NOT written by this phase. The approved plan's stepwise execution order MUST include the step `Create <PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md from the decision draft in section X` so the `implementation` run commits the file. External `<PROJECT_ROOT>/docs/adr/` is never touched.
+  - **Domain-doc proposals**: if `CONTEXT.md` / `CONTEXT-MAP.md` needs a new term or edited definition, add the step `Update CONTEXT.md: <term> = <definition>` to the stepwise execution order. Do NOT edit the file in this phase.
 - No-placeholder rule (plan failures — reject any option or step that contains these):
   - "TBD", "TODO", "implement later", "fill in details", "add appropriate error handling", "handle edge cases", "write tests for the above" without actual test code
   - "similar to Option/Task N" without repeating the concrete content (readers may consume sections out of order)

package/runtime/prompts/profiles/requirements-discovery.md

@@ -8,19 +8,39 @@
 - Optional workers (opt-in via `--workers`):
   - gemini — when added to the roster it joins the analyser set; omitted by default
 {{INCLUDE:_common-contract.md}}
+- Brief consumption (phase-specific addendum — shared rules live in `_common-contract.md` under "Brief handoff contract"):
+  - **Precondition check (BLOCKING — runs before any analysis)**: read the brief's frontmatter `reporter-confirmations:` field and inspect every `Open Questions` row prefixed `intent-check:` / `conversion-block:` for the `[CONFIRMED …]` marker.
+    - `reporter-confirmations: complete` → proceed normally (no unresolved reporter-only rows).
+    - `reporter-confirmations: partial` → proceed; treat the still-unmarked `intent-check:` / `conversion-block:` rows per the `skipped` branch below.
+    - `reporter-confirmations: skipped` (or `partial` with remainder) → do NOT silently infer the missing answers. Promote each unmarked `intent-check:` / `conversion-block:` row into this run's `## 5. Clarification Items` as `Kind=decision, Blocks=next-phase`, with the recommended answer drawn from the brief's matching `intent-inference` / `conversion-block:` text and clearly labelled `보고자 직접 확인 권장`. Then proceed with the rest of the classification work.
+    - `reporter-confirmations: pending` (or field missing) → ABORT analysis. Write only `## 0. Reporter Confirmation Required` summarising which rows are pending and stop. The operator must rerun `okstra-brief` Step 6.5 to collect answers, then restart this phase. The final report carries `Blocks=next-phase`.
+  - before classifying (after the precondition passes), scan the brief for every `Open Questions` row prefixed `intent-check:` / `terminology:` / `conversion-block:` and every `Augmentation` entry labelled `intent-inference` / `terminology-mapping`. Each one is a translation signal that this phase must resolve OR carry forward.
+  - `intent-inference` augmentations whose paired `intent-check:` row carries `[CONFIRMED …]` are treated as **confirmed**; trust the confirmation text in `## Reporter Confirmations` over the original inference if they differ. Unconfirmed `intent-inference` rows under `reporter-confirmations: skipped` follow the precondition's `skipped` branch above.
+  - `conversion-block:` rows are explicit "translation failed" signals — never attempt to resolve them by inference here; the precondition above already handled them.
 - Primary focus areas:
   - classify the work as bugfix, feature, improvement, refactor, or ops-change
   - determine whether `error-analysis` or `implementation-planning` is the next safe step; direct `implementation` handoff is not a valid routing target because implementation requires an approved `implementation-planning` report
   - identify missing materials that block reliable routing
   - define task continuity expectations for long-running work under the same task key
   - capture approval or confirmation points before the next phase starts
+  - **domain alignment check**: read in priority order — (authoritative) `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` and `<PROJECT_ROOT>/.project-docs/okstra/decisions/` titles if present; (supplementary) `<PROJECT_ROOT>/CONTEXT.md` (or `CONTEXT-MAP.md` → per-context `CONTEXT.md`) and `<PROJECT_ROOT>/docs/adr/` titles if present. Absent external files are normal — do not error. Validate that every `terminology:*` entry under the brief's `Open Questions` has a canonical resolution before routing. Fuzzy or overloaded terms in the brief MUST be resolved to a single canonical term in this phase.
+- Decision-tree walk (grill-me adopted, bounded):
+  - When the brief's `Desired Outcome`, classification, or routing target depends on a chain of decisions, walk that chain one branch at a time. Each branch is one `Clarification Items` row, not a free-form interview.
+  - For every clarification row, write the row's `Recommended` cell with the single best answer plus a one-line rationale. Other options are listed in `Alternatives` with one-sentence consequences.
+  - **Codebase-first rule**: if a branch can be resolved by `Read` / `Grep` / file inspection, resolve it that way and record the evidence in the same row's `Evidence` cell. Do NOT escalate to the user.
+  - Budget: the unified `## 5. Clarification Items` table caps at the smaller of (a) one row per unresolved decision branch, (b) 8 rows total. Beyond the cap, fold remaining ambiguity into the routing recommendation's risk notes.
 - Expected output emphasis:
   - evidence-backed routing decision
   - uncertainty boundaries and missing inputs
   - next recommended phase and safe resume guidance
+  - canonical-term resolution for every `terminology:*` brief item, written as a one-line `<term> = <definition>` line in a new `Domain Alignment` subsection of the final report; alongside each, propose whether `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` should be updated (proposal only — actual writes happen via `okstra-brief` Step 4.5 on a subsequent run)
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
   - if any blocking input is missing at the time of writing the final report, populate `## 5. Clarification Items` in `final-report-template.md` (a single unified table; `Blocks=next-phase` for items the next run cannot start without)
   - prefer concrete questions whose answers map directly to a routing decision (`bugfix` vs `feature`, `error-analysis` vs `implementation-planning`, etc.). State each option in plain language with one sentence describing what choosing it would mean for the next phase.
+  - every clarification row carries a `Recommended` answer + one-line rationale; rows that lack a recommendation are rejected as half-formed.
+  - **Codebase-first ambiguity resolution (defect rule)**: any ambiguity that can be answered by `Read` / `Grep` / file inspection MUST be resolved that way and recorded with file:line evidence. Writing a clarification row for something the codebase already answers is a defect of this phase.
+  - **`evidence-checked:` cell required**: every clarification row carries an `evidence-checked: <path:line> | none` cell. `evidence-checked: <path:line>` means the codebase was inspected and the row records what was found (or that the code did not contain the answer). `evidence-checked: none` is allowed ONLY when the row's nature is "only a human can answer this" (reporter intent, business priority, external authority); the row body must state which one in one line. A row with `evidence-checked: none` that *could* have been answered by the codebase is a defect.
 - Non-goals:
   - full implementation design unless it is required to decide the next phase
   - **source code edits, plan authoring, builds, or deployments** — this run only classifies the work and routes it; deeper analysis and planning belong to subsequent phases
+  - **edits to any path outside `<PROJECT_ROOT>/.project-docs/okstra/`** — okstra never writes to external paths. Glossary additions land in `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` (via `okstra-brief` Step 4.5); decision drafts land in `<PROJECT_ROOT>/.project-docs/okstra/decisions/` (via `implementation-planning`). External `<PROJECT_ROOT>/CONTEXT.md` / `CONTEXT-MAP.md` / `docs/adr/` are read-only references.