okstra 0.50.0 → 0.51.0

package/README.kr.md

@@ -43,7 +43,7 @@ okstra/                          npm 패키지 = repo 루트
 ├── tools/build.mjs              runtime/ 동기화 스크립트 (prepack 에서 호출)
 ├── runtime/                     gitignored 설치 payload; ~/.okstra 로 복사
 ├── scripts/                     python + bash 런타임 소스
-├── skills/                      Claude Code 스킬 마크다운 소스 (스킬 10종)
+├── skills/                      Claude Code 스킬 마크다운 소스 (스킬 11종)
 ├── agents/                      lead SKILL.md + workers/
 ├── prompts/, schemas/, templates/, validators/
 ├── docs/kr/                     한국어 상세 매뉴얼 (architecture.md, cli.md)
@@ -74,7 +74,7 @@ okstra/                          npm 패키지 = repo 루트
 └── .locks/                      central/task mutex 파일
 
 ~/.claude/skills/                Claude Code 가 자동 인식
-└── okstra-*/SKILL.md            스킬 10종 (§3.3 참조)
+└── okstra-*/SKILL.md            스킬 11종 (§3.3 참조)
 
 ~/.claude/agents/                Claude Code 가 자동 인식 (subagent 디스커버리 경로)
 └── {claude,codex,gemini,report-writer}-worker.md   worker subagent 정의
@@ -107,7 +107,7 @@ okstra/                          npm 패키지 = repo 루트
 npx -y okstra@latest install
 ```
 
-`~/.okstra/{lib/python, bin, templates, version}`, `~/.claude/skills/` 아래 스킬 마크다운 10개, `~/.claude/agents/` 아래 worker agent 4개, `~/.okstra/` 의 설치 asset manifest 를 생성합니다. 재실행은 idempotent — 파일별 hash 를 비교하고 바뀐 파일만 갱신합니다.
+`~/.okstra/{lib/python, bin, templates, version}`, `~/.claude/skills/` 아래 스킬 마크다운 11개, `~/.claude/agents/` 아래 worker agent 4개, `~/.okstra/` 의 설치 asset manifest 를 생성합니다. 재실행은 idempotent — 파일별 hash 를 비교하고 바뀐 파일만 갱신합니다.
 
 검증:
 
@@ -157,11 +157,11 @@ Claude Code 세션 안에서 사용하는 슬래시 커맨드:
 | `/okstra-brief` | ticket, 요구사항 문서, 링크, 대화 내용을 `okstra-run`용 task brief로 변환 |
 | `/okstra-run` | 새 task 시작 (또는 기존 task 의 다음 phase 이어가기) |
 | `/okstra-memory` | `~/.okstra/memory-book` 전역 대화 메모리 저장·검색·보관 |
-| `/okstra-inspect` | 통합 read-side 스킬. sub-command: `status` (phase / 상태, workStatus 설정), `history` (과거 task / re-run / resume), `report` (final-report 조회·읽기), `time` (소요 시간 breakdown), `logs` (wrapper log sidecar 조회·정리 제안) |
+| `/okstra-inspect` | 통합 read-side 스킬. sub-command: `status` (phase / 상태, workStatus 설정), `history` (과거 task / re-run / resume), `report` (final-report 조회·읽기), `time` (소요 시간 breakdown), `logs` (wrapper log sidecar 조회·정리 제안), `cost` (task bundle 컨텍스트/읽기 비용) |
 | `/okstra-schedule` | task-group 전체에 대한 작업 계획표 생성 |
 | `/okstra-setup` | 프로젝트별 부트스트랩 (§3.2) |
 
-이 외에 `okstra-context-loader`, `okstra-team-contract`, `okstra-convergence`, `okstra-report-writer` 4종은 `user-invocable: false` 로 표시되어 슬래시 커맨드로 노출되지 않습니다. lead 또는 Claude 가 자연어 트리거나 okstra phase 흐름에 따라 자동 호출합니다.
+이 외에 `okstra-context-loader`, `okstra-team-contract`, `okstra-convergence`, `okstra-report-writer`, `okstra-coding-preflight` 5종은 `user-invocable: false` 로 표시되어 슬래시 커맨드로 노출되지 않습니다. lead 또는 Claude 가 자연어 트리거나 okstra phase 흐름에 따라 자동 호출합니다.
 
 ### 3.4 CLI 모드 (선택)
 
@@ -192,10 +192,10 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 - **PR 본문 템플릿 설정** (release-handoff) — PR 본문은 마크다운 템플릿에서 채워집니다. 해석 우선순위: 1회성 override (`--pr-template-path` 또는 okstra-run Step 6 prompt) → `<project_root>/.okstra/project.json` 의 `prTemplatePath` → `~/.okstra/config.json` 의 `prTemplatePath` → 스킬 디폴트 `~/.claude/skills/okstra-run/templates/pr-body.template.md`. 템플릿 등록 명령: `okstra config set pr-template-path <path> [--scope project|global]` (project 스코프는 project root 기준 상대경로 허용, global 스코프는 절대경로 또는 `~/` 시작 경로만 허용). 현재 설정 확인: `okstra config get pr-template-path --scope all` 은 각 스코프 값 + 실제로 우승하는 경로(effective) 까지 보여줍니다. 디폴트 템플릿은 `## Summary` / `## Changes` / `## Test plan` / `## Linked issues` 4 섹션 + HTML 주석으로 lead 작성 가이드를 포함하며, PR 생성 직전에 lead 가 주석을 제거합니다.
 - **프로파일 워커 로스터 검증** — `--workers <csv>` 와 okstra-run Step 6 의 워커 prompt 는 해당 프로파일의 `Required workers:` 블록에 선언된 워커 ID 만 허용합니다. 프로파일에 없는 워커 (예: `release-handoff` 에서 `codex` / `gemini`) 를 요청하면 명확한 에러로 거절되고, 인터랙티브 prompt 도 프로파일이 실제로 받는 워커만 보여줍니다.
 - **다단계 `implementation-planning` / `implementation`** — `implementation-planning` 은 항상 Stage Map + N 개 stage 섹션으로 산출합니다. 각 stage 의 step 은 ≤ 6 이며 `depends-on (none)` 인 stage 들은 별도 `implementation` run 으로 병렬 실행할 수 있습니다. 각 `implementation` 호출은 한 stage 만 실행하고 (`--stage <auto|N>`), 자동 생성되는 evidence sidecar (`carry/stage-<N>.json`) 가 다음 stage 의 carry-in 으로 흡수됩니다. `implementation-planning` run 디렉터리에 `consumers.jsonl` 역링크가 누적되어 어느 run 이 어느 stage 를 소비했는지 추적됩니다.
-- **Phase 6 plan-body verification (implementation-planning 전용)** — Report writer worker 가 final-report draft 를 작성한 직후, 사용자 승인 gate 직전에 lead 가 1 라운드의 사후 검증을 추가로 돌립니다. 합성된 `## 4.5` plan 본문에서 `P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*` plan-item 을 추출해 모든 analyser 워커에게 `AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT` 평결을 요청합니다. 집계된 gate 결과는 `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result` 중 하나. frontmatter `approved` 필드는 항상 `false` 로 발행되며, gate 가 `blocked-by-disagreement` 또는 `aborted-non-result` 일 때 writer 는 `approved: false` 를 유지해야 하고 (이런 gate 결과로 `approved: true` 로 ship 된 report 는 validator 가 거부), `majority-disagree` 항목을 `## 5. Clarification Items` 의 `Blocks=approval` row 로 변환합니다. 빠른 반복용 opt-out: `--no-plan-verification` (기본값: 활성). 자세한 라운드 프로토콜은 [`skills/okstra-convergence/SKILL.md`](skills/okstra-convergence/SKILL.md) 의 "Plan-body verification mode" 섹션과 [`docs/kr/cli.md#--no-plan-verification`](docs/kr/cli.md#--no-plan-verification).
+- **Phase 6 plan-body verification (implementation-planning 전용)** — Report writer worker 가 final-report draft 를 작성한 직후, 사용자 승인 gate 직전에 lead 가 1 라운드의 사후 검증을 추가로 돌립니다. 합성된 `## 5.5` implementation plan deliverables 본문에서 `P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*` plan-item 을 추출해 모든 analyser 워커에게 `AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT` 평결을 요청합니다. 집계된 gate 결과는 `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result` 중 하나. frontmatter `approved` 필드는 항상 `false` 로 발행되며, gate 가 `blocked-by-disagreement` 또는 `aborted-non-result` 일 때 writer 는 `approved: false` 를 유지해야 하고 (이런 gate 결과로 `approved: true` 로 ship 된 report 는 validator 가 거부), `majority-disagree` 항목을 `## 1. Clarification Items` 의 `Blocks=approval` row 로 변환합니다. 빠른 반복용 opt-out: `--no-plan-verification` (기본값: 활성). 자세한 라운드 프로토콜은 [`skills/okstra-convergence/SKILL.md`](skills/okstra-convergence/SKILL.md) 의 "Plan-body verification mode" 섹션과 [`docs/kr/cli.md#--no-plan-verification`](docs/kr/cli.md#--no-plan-verification).
 - **Brief = translation layer + Step 6.5 reporter batch confirmation** — `okstra-brief` 가 외부 입력 (이슈 ticket, 요구사항 문서, 사용자 메시지) 을 verbatim 으로 옮기되 okstra 가 추가한 부분은 labelled augmentation 으로 구분하는 translation layer 가 됐습니다. Step 6.5 가 brief 가 옮기는 과정에서 의미 변화가 발생했는지 사용자에게 일괄 확인받아 `Reporter Confirmations` 섹션에 기록하고, 모든 분석 profile 은 이 섹션의 존재를 phase 분석 진입 precondition 으로 강제합니다 (validator: `validators/validate-brief.py`).
 - **Artifact-home rule (`.okstra/`)** — okstra 의 project artifact root 는 `<project>/.okstra/` 하나뿐입니다. 이 root 밖은 okstra memory 가 아니며, Source Material 또는 Reporter Confirmations 가 명시적으로 cite 한 경우에만 read-only 로 읽습니다. 쓰기는 같은 explicit request path 를 요구합니다. okstra-internal 등가물: 용어집 `glossary.md`, 결정 기록 `decisions/<NNNN>-<slug>.md` (`implementation-planning` phase 에서 평가).
-- **Dual-format final-report views** — Phase 7 가 `final-report-<task-type>-<seq>.md` 를 쓰면 `okstra render-views` 가 같은 `reports/` 폴더에 두 view 를 자동 생성합니다: AI 다음-phase 입력용 슬림 markdown, 사람 reviewer 용 self-contained HTML (CSS/JS 인라인, 외부 URL 0). HTML 의 `Export user response` 버튼은 `## 5. Clarification Items` 입력을 `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md` 사이드카로 직렬화해 다음 phase 가 소비합니다. 원본 MD 는 어떤 경우에도 view 생성으로 인해 수정되지 않습니다.
+- **Dual-format final-report views** — Phase 7 가 `final-report-<task-type>-<seq>.md` 를 쓰면 `okstra render-views` 가 같은 `reports/` 폴더에 두 view 를 자동 생성합니다: AI 다음-phase 입력용 슬림 markdown, 사람 reviewer 용 self-contained HTML (CSS/JS 인라인, 외부 URL 0). HTML 의 `Export user response` 버튼은 `## 1. Clarification Items` 입력을 `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md` 사이드카로 직렬화해 다음 phase 가 소비합니다. 원본 MD 는 어떤 경우에도 view 생성으로 인해 수정되지 않습니다.
 - **`improvement-discovery` task-type (sidetrack entry-point)** — 코드베이스 범위 + 우선순위 lens 화이트리스트 안에서 multi-worker 합의 기반 개선 후보 N개 (기본 8, 절대 cap 12) 도출. `PHASE_SEQUENCE` 외부 sidetrack entry-point — 사용자가 후보를 골라 각각 새 task-id 로 `requirements-discovery` / `implementation-planning` / `error-analysis` 진입. lens enum SSOT: [`scripts/okstra_ctl/improvement_lenses.py`](scripts/okstra_ctl/improvement_lenses.py). 출력 섹션: `## 4.9 Improvement Candidates` (10-column 표). validator: [`validators/validate_improvement_report.py`](validators/validate_improvement_report.py).
 
 ### 3.5 운영 명령
@@ -209,6 +209,7 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 | `npx -y okstra@latest check-project` | 현재 프로젝트가 `setup` 으로 등록됐는지 검증 |
 | `npx -y okstra@latest config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | okstra 설정 읽기/쓰기. 현재 지원 키: `pr-template-path` (project.json 또는 `~/.okstra/config.json` 의 `prTemplatePath` 갱신) |
 | `npx -y okstra@latest memory <add\|list\|search\|show\|archive>` | `~/.okstra/memory-book` 전역 대화 메모리 저장·검색·보관 |
+| `npx -y okstra@latest context-cost <task-key\|task-root> [--project-root <path>]` | task bundle 의 lead/worker/report-writer 컨텍스트·읽기 비용 추정 |
 | `npx -y okstra@latest render-views <final-report.md>` | final-report MD 한 본을 입력으로 슬림 MD + HTML 두 view 를 (재)생성 (Phase 7 step 1.5; 멱등) |
 | `npx -y okstra@latest token-usage ...` | run token usage 수집/치환. 설치된 Python token usage CLI를 감싼 Node wrapper |
 | `npx -y okstra@latest uninstall` | 런타임 + 스킬 제거; 사용자 데이터(`recent.jsonl`, `projects/`, …)는 보존 |

package/README.md

@@ -43,7 +43,7 @@ okstra/                          npm package = repo root
 ├── tools/build.mjs              runtime/ sync script (invoked by prepack)
 ├── runtime/                     gitignored install payload copied to ~/.okstra
 ├── scripts/                     python + bash runtime sources
-├── skills/                      Claude Code skill markdown sources (14 skills)
+├── skills/                      Claude Code skill markdown sources (11 skills)
 ├── agents/                      lead SKILL.md + workers/
 ├── prompts/, schemas/, templates/, validators/
 ├── tests/, tests-e2e/
@@ -73,7 +73,7 @@ okstra/                          npm package = repo root
 └── .locks/                      central/task mutex files
 
 ~/.claude/skills/                discovered automatically by Claude Code
-└── okstra-*/SKILL.md            14 skills total (see §3.3)
+└── okstra-*/SKILL.md            11 skills total (see §3.3)
 
 ~/.claude/agents/                discovered automatically by Claude Code
 └── {claude,codex,gemini,report-writer}-worker.md   subagent definitions
@@ -106,7 +106,7 @@ okstra/                          npm package = repo root
 npx -y okstra@latest install
 ```
 
-Provisions `~/.okstra/{lib/python, bin, templates, version}`, the 14 skill markdown files under `~/.claude/skills/`, the 4 worker agents under `~/.claude/agents/`, and the installed-asset manifests in `~/.okstra/`. Re-running is idempotent — per-file hashes are compared and only changed files are touched.
+Provisions `~/.okstra/{lib/python, bin, templates, version}`, the 11 skill markdown files under `~/.claude/skills/`, the 4 worker agents under `~/.claude/agents/`, and the installed-asset manifests in `~/.okstra/`. Re-running is idempotent — per-file hashes are compared and only changed files are touched.
 
 Verify:
 
@@ -156,11 +156,11 @@ User-facing slash commands inside a Claude Code session:
 | `/okstra-brief` | Turn a ticket, requirements doc, link, or conversation into an `okstra-run` task brief |
 | `/okstra-run` | Start a new task (or resume the next phase of an existing one) |
 | `/okstra-memory` | Store/search/archive global conversation memory in `~/.okstra/memory-book` |
-| `/okstra-inspect` | Unified read-side. Sub-commands: `status` (phase / state, workStatus update), `history` (past runs, re-run, resume), `report` (find/read final-report), `time` (elapsed-time breakdown), `logs` (wrapper log sidecar inventory + cleanup) |
+| `/okstra-inspect` | Unified read-side. Sub-commands: `status` (phase / state, workStatus update), `history` (past runs, re-run, resume), `report` (find/read final-report), `time` (elapsed-time breakdown), `logs` (wrapper log sidecar inventory + cleanup), `cost` (task bundle context/read cost) |
 | `/okstra-schedule` | Generate a work schedule for an entire task-group |
 | `/okstra-setup` | Per-project bootstrap (§3.2) |
 
-Four support skills — `okstra-context-loader`, `okstra-team-contract`, `okstra-convergence`, `okstra-report-writer` — are marked `user-invocable: false` and do not appear as slash commands. Claude still invokes them automatically via natural-language triggers or okstra phase flow.
+Five support skills — `okstra-context-loader`, `okstra-team-contract`, `okstra-convergence`, `okstra-report-writer`, `okstra-coding-preflight` — are marked `user-invocable: false` and do not appear as slash commands. Claude still invokes them automatically via natural-language triggers or okstra phase flow.
 
 ### 3.4 CLI mode (optional)
 
@@ -191,10 +191,10 @@ Recent workflow additions (post-0.8.0, on `main`):
 - **Configurable PR body template** (release-handoff) — the PR body is filled from a markdown template chosen in priority order: per-run override (`--pr-template-path` or the okstra-run Step 6 prompt) → `<project_root>/.okstra/project.json` `prTemplatePath` → `~/.okstra/config.json` `prTemplatePath` → bundled skill default at `~/.claude/skills/okstra-run/templates/pr-body.template.md`. Register a template with `okstra config set pr-template-path <path> [--scope project|global]` (project scope accepts paths relative to the project root; global scope requires absolute or `~/`-prefixed). `okstra config get pr-template-path --scope all` reports every scope plus the effective winner. The bundled default ships `## Summary` / `## Changes` / `## Test plan` / `## Linked issues` with HTML comment guidance that the lead strips before opening the PR.
 - **Profile-roster worker validation** — `--workers <csv>` (and the okstra-run Step 6 worker prompt) are now restricted to the worker IDs declared by the chosen profile's `Required workers:` block. Asking for `codex` / `gemini` on a profile that does not list them (e.g. `release-handoff`) is rejected with a clear error, and the interactive prompt only offers workers the profile actually accepts.
 - **Multi-stage `implementation-planning` / `implementation`** — `implementation-planning` always produces a Stage Map plus N stage sections; each stage has ≤6 steps and stages whose `depends-on (none)` can be executed in parallel by separate `implementation` runs. Each `implementation` invocation picks one stage (via `--stage <auto|N>`) and emits an evidence sidecar (`carry/stage-<N>.json`) that the next stage automatically inherits. The `implementation-planning` run directory accumulates a `consumers.jsonl` reverse-link showing which `implementation` runs consumed which stage.
-- **Phase 6 plan-body verification (implementation-planning only)** — after the Report writer worker authors the final-report draft and before the user approval gate, the lead now runs one additional verification round: it extracts `P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*` items from the consolidated `## 4.5` plan body and dispatches them to every analyser worker as `AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`. The aggregated gate result is one of `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`. The frontmatter `approved` flag is always emitted as `false`; when the gate is `blocked-by-disagreement` or `aborted-non-result` the writer MUST keep it `false` (the validator refuses any report that publishes `approved: true` under such a gate) and convert `majority-disagree` items into `## 5. Clarification Items` rows with `Blocks=approval`. Disable for fast iteration with `--no-plan-verification` (default: enabled). Details: [`skills/okstra-convergence/SKILL.md`](skills/okstra-convergence/SKILL.md) "Plan-body verification mode" and [`docs/kr/cli.md#--no-plan-verification`](docs/kr/cli.md#--no-plan-verification).
+- **Phase 6 plan-body verification (implementation-planning only)** — after the Report writer worker authors the final-report draft and before the user approval gate, the lead now runs one additional verification round: it extracts `P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*` items from the consolidated `## 5.5` implementation plan deliverables body and dispatches them to every analyser worker as `AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`. The aggregated gate result is one of `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`. The frontmatter `approved` flag is always emitted as `false`; when the gate is `blocked-by-disagreement` or `aborted-non-result` the writer MUST keep it `false` (the validator refuses any report that publishes `approved: true` under such a gate) and convert `majority-disagree` items into `## 1. Clarification Items` rows with `Blocks=approval`. Disable for fast iteration with `--no-plan-verification` (default: enabled). Details: [`skills/okstra-convergence/SKILL.md`](skills/okstra-convergence/SKILL.md) "Plan-body verification mode" and [`docs/kr/cli.md#--no-plan-verification`](docs/kr/cli.md#--no-plan-verification).
 - **Brief as translation layer + reporter batch confirmation (Step 6.5)** — `okstra-brief` now produces the brief as a translation layer that preserves external inputs (issue ticket, requirements doc, user message) verbatim while labelling okstra augmentations. A new Step 6.5 walks the user through a single batch confirmation of any rewordings, recorded in a `Reporter Confirmations` section. Every analysis profile blocks phase entry until this section exists (validator: `validators/validate-brief.py`).
 - **Artifact-home rule (`.okstra/`)** — okstra's project artifact root is only `<project>/.okstra/`. Anything outside that root is not okstra memory; it may be read only when explicitly cited as Source Material or Reporter Confirmations, and writes require the same explicit request path. okstra-internal equivalents: `glossary.md` for terminology and `decisions/<NNNN>-<slug>.md` for decision records (evaluated in `implementation-planning`).
-- **Dual-format final-report views** — after Phase 7 writes `final-report-<task-type>-<seq>.md`, `okstra render-views` automatically emits two sibling views in the same `reports/` directory: a slim Markdown for downstream AI input and a self-contained HTML (inline CSS/JS, no external URLs) for human review. The HTML lets a reviewer fill in `## 5. Clarification Items` decisions and export them to `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md`, which the next phase consumes as input. The original MD is never modified by view generation.
+- **Dual-format final-report views** — after Phase 7 writes `final-report-<task-type>-<seq>.md`, `okstra render-views` automatically emits two sibling views in the same `reports/` directory: a slim Markdown for downstream AI input and a self-contained HTML (inline CSS/JS, no external URLs) for human review. The HTML lets a reviewer fill in `## 1. Clarification Items` decisions and export them to `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md`, which the next phase consumes as input. The original MD is never modified by view generation.
 - **`improvement-discovery` task-type (sidetrack entry-point)** — Discover ranked improvement candidates within a codebase scope and lens whitelist via multi-worker consensus (default top-8, hard cap 12). Outside `PHASE_SEQUENCE`; the user selects candidates and opens each as a new task with `requirements-discovery`, `implementation-planning`, or `error-analysis`. Lens enum SSOT: [`scripts/okstra_ctl/improvement_lenses.py`](scripts/okstra_ctl/improvement_lenses.py). Output section: `## 4.9 Improvement Candidates` (10-column table). Validator: [`validators/validate_improvement_report.py`](validators/validate_improvement_report.py).
 
 ### 3.5 Ops commands
@@ -208,6 +208,7 @@ Recent workflow additions (post-0.8.0, on `main`):
 | `npx -y okstra@latest check-project` | Verify the current project has been registered with `setup` |
 | `npx -y okstra@latest config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | Read / write okstra settings; initial key `pr-template-path` (writes `prTemplatePath` to project.json or `~/.okstra/config.json`) |
 | `npx -y okstra@latest memory <add\|list\|search\|show\|archive>` | Store and find global conversation memory in `~/.okstra/memory-book` |
+| `npx -y okstra@latest context-cost <task-key\|task-root> [--project-root <path>]` | Estimate lead/worker/report-writer context and read cost for a task bundle |
 | `npx -y okstra@latest render-views <final-report.md>` | Regenerate the slim-MD + HTML sibling views from a final-report MD (Phase 7 step 1.5; idempotent) |
 | `npx -y okstra@latest token-usage ...` | Collect/substitute token usage for a run; wraps the installed Python token usage CLI |
 | `npx -y okstra@latest uninstall` | Remove runtime + skills; preserves user data (`recent.jsonl`, `projects/`, …) |

package/bin/okstra

@@ -13,6 +13,7 @@ const COMMANDS = new Map([
   ["migrate", () => import("../src/migrate.mjs").then((m) => m.run)],
   ["task-list", () => import("../src/task-list.mjs").then((m) => m.run)],
   ["task-show", () => import("../src/task-show.mjs").then((m) => m.run)],
+  ["context-cost", () => import("../src/context-cost.mjs").then((m) => m.run)],
   ["worktree-lookup", () => import("../src/worktree-lookup.mjs").then((m) => m.run)],
   ["plan-validate", () => import("../src/plan-validate.mjs").then((m) => m.run)],
   ["render-bundle", () => import("../src/render-bundle.mjs").then((m) => m.run)],
@@ -53,6 +54,7 @@ Admin commands:
 Introspection commands (JSON output, used by skills to avoid python heredocs):
   task-list              List tasks registered in the current project
   task-show              Summarize a task's manifest + workflow phase state
+  context-cost           Estimate file/read context cost for a task bundle
   worktree-lookup        Look up registered worktree for a task-key
   plan-validate          Check an approved-plan file for the approval marker
   render-bundle          Preview prepare_task_bundle() output (forwards to

package/docs/kr/architecture.md

@@ -18,7 +18,7 @@
 - **Single python authority**: 모든 prepare wiring(profile/workers/model 해소, path 계산, render, central record_start)이 [`okstra_ctl.run.prepare_task_bundle()`](../../scripts/okstra_ctl/run.py) 한 함수에 모여 있습니다. `okstra.sh` 와 `okstra-run` skill 은 같은 함수를 호출하는 thin caller 이며, 환경 변수로 상태를 전달하지 않습니다 — task 정체성·경로·workflow 상태는 모두 디스크 권위 파일에서 매번 계산됩니다.
 - **Claude handoff (두 모드)**: (a) `okstra.sh` 가 새 `claude` 프로세스를 띄우는 전통 방식, (b) `okstra-run` skill 이 현재 claude 세션 안에서 prepare 후 lead 역할을 그대로 인계받는 in-session 모드. 둘 다 `prepare_task_bundle` 의 산출물(instruction-set 등)을 그대로 사용합니다.
 - **Required team contract**: 각 phase profile의 `Required workers:` 블록이 roster의 권위입니다. 일반 분석 phase는 Claude/Codex analyser + report-writer를 기본으로 하고, Gemini는 profile과 `--workers`가 허용할 때만 포함됩니다. `release-handoff`처럼 lead-only에 가까운 phase는 별도 roster를 가집니다.
-- **User-home install + project-local task bundles**: `npx okstra@latest install` 한 명령이 런타임(`~/.okstra/{lib/python, bin, templates}`), 스킬 10종(`~/.claude/skills/<name>/SKILL.md`), worker agent 4종(`~/.claude/agents/*-worker.md`)을 설치합니다. 전역 대화 메모리는 프로젝트와 분리된 `~/.okstra/memory-book/` 에 저장됩니다. 대상 프로젝트에는 task bundle 과 discovery metadata 가 `.okstra/` 아래 저장되고, **추가로 `<PROJECT_ROOT>/.claude/settings.local.json` 이 `~/.okstra/templates/settings.local.json` 을 가리키는 symlink 로 provisioning** 됩니다 (`okstra setup` 또는 `okstra-ctl` prepare 가 idempotent 하게 관리; 기존에 일반 파일이 있었다면 `.bak.<timestamp>` 로 백업 후 교체). 이 symlink 가 host Claude Code 세션에 자동 로드되어 codex/gemini worker wrapper 호출 권한을 부여하므로, 사용자의 글로벌 `~/.claude/settings.json` 은 건드리지 않습니다. 개발용 `okstra install --link <repo>` 는 설치 파일을 repo source로 symlink합니다.
+- **User-home install + project-local task bundles**: `npx okstra@latest install` 한 명령이 런타임(`~/.okstra/{lib/python, bin, templates}`), 스킬 11종(`~/.claude/skills/<name>/SKILL.md`), worker agent 4종(`~/.claude/agents/*-worker.md`)을 설치합니다. 전역 대화 메모리는 프로젝트와 분리된 `~/.okstra/memory-book/` 에 저장됩니다. 대상 프로젝트에는 task bundle 과 discovery metadata 가 `.okstra/` 아래 저장되고, **추가로 `<PROJECT_ROOT>/.claude/settings.local.json` 이 `~/.okstra/templates/settings.local.json` 을 가리키는 symlink 로 provisioning** 됩니다 (`okstra setup` 또는 `okstra-ctl` prepare 가 idempotent 하게 관리; 기존에 일반 파일이 있었다면 `.bak.<timestamp>` 로 백업 후 교체). 이 symlink 가 host Claude Code 세션에 자동 로드되어 codex/gemini worker wrapper 호출 권한을 부여하므로, 사용자의 글로벌 `~/.claude/settings.json` 은 건드리지 않습니다. 개발용 `okstra install --link <repo>` 는 설치 파일을 repo source로 symlink합니다.
 - **Resume and clarification**: `--task-key`, `--resume-clarification`, `--clarification-response`로 같은 task 재개와 lead의 추가 질문 응답 흐름을 지원합니다.
 - **Derived views and telemetry**: final-report data.json → Markdown → slim MD / self-contained HTML view, worker error sidecar, wrapper log sidecar, token usage / cost accounting을 제공합니다.
 
@@ -90,7 +90,7 @@ okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_ta
 - task brief / clarification response 경로 해석 (cwd 우선 → PROJECT_ROOT fallback)
 - per-task mutex(`~/.okstra/.locks/<task-key>.lock`) 안에서 stable task root + 모든 path/seq 계산 후 `<run-dir>/manifests/run-context-<seq>.json` 으로 영속화
 - 사용자 입력을 `<run-dir>/manifests/run-inputs-<seq>.json` 으로 영속화
-- instruction-set 9 파일 렌더 (`analysis-profile.md`, `analysis-material.md`, `task-brief.md`, `reference-expectations.md`, `final-report-template.md`, `clarification-response.md`, `directive.txt`, `claude-execution-prompt.md`, lead prompt snapshot)
+- instruction-set 렌더 (`analysis-profile.md`, `analysis-packet.md`, `analysis-material.md`, `task-brief.md`, `reference-expectations.md`, `final-report-template.md`, `final-report-schema.json`, optional `clarification-response.md`, optional `directive.txt`, `claude-execution-prompt.md`) + run prompt snapshot 작성
 - `task-manifest.json` · `task-index.md` · `run-manifest-*.json` · `history/timeline.json` · `discovery/{latest-task,task-catalog}.json` 갱신
 - preassigned Claude session ID + `sessions/claude-resume-*.sh` 작성 (`--render-only` 가 아닐 때)
 - 중앙 인덱스(`~/.okstra/{active,recent}.jsonl`, `projects/<id>/{index.jsonl, meta.json}`) record_start
@@ -152,7 +152,7 @@ okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_ta
 - [`agents/SKILL.md`](../../agents/SKILL.md) — main okstra lead contract.
 - [`skills/okstra-setup/SKILL.md`](../../skills/okstra-setup/SKILL.md) — **첫 실행 부트스트랩**. `okstra install` + `project.json` 생성.
 - [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md) — **현재 claude 세션 안에서 okstra task 를 시작**하는 in-session 진입점. `prepare_task_bundle` 직접 호출.
-- `skills/okstra-{brief,run,memory,inspect,schedule,context-loader,team-contract,convergence,report-writer}/SKILL.md` — brief 작성, phase 진행, 전역 Memory Book 저장/검색, status/history/report/time/log read-side, schedule 보조 skill. `okstra-inspect logs` 는 codex/gemini wrapper 가 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` 로 남기는 live-log sidecar 의 인벤토리·정리 안내 (read-only, find-delete cleanup 명령 제안만 함).
+- `skills/okstra-{brief,run,memory,inspect,schedule,context-loader,team-contract,convergence,report-writer,coding-preflight}/SKILL.md` — brief 작성, phase 진행, 전역 Memory Book 저장/검색, status/history/report/time/log/cost read-side, schedule 보조 skill, 구현/검증 워커의 언어별 coding preflight. `okstra-inspect logs` 는 codex/gemini wrapper 가 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` 로 남기는 live-log sidecar 의 인벤토리·정리 안내 (read-only, find-delete cleanup 명령 제안만 함). `okstra-inspect cost` 는 `okstra context-cost` CLI 결과를 요약해 task bundle 의 lead/worker/report-writer 읽기 비용을 보여준다.
 - 플러그인 매니페스트: [`../../.claude-plugin/plugin.json`](../../.claude-plugin/plugin.json) — `npx skills@latest add Devonshin/okstra` 보조 채널이 참조. 일반 셋업에는 `npx okstra@latest install` 을 사용한다.
 - 설치 위치: `~/.claude/skills/<name>/SKILL.md` (`okstra-install.sh` dev 설치, 또는 위 npx 채널).
 - 릴리스 절차: [`../../RELEASING.md`](../../RELEASING.md) — npm publish 흐름과 release-please / manual fallback.
@@ -359,7 +359,7 @@ okstra phase 는 PRD / issue file 을 직접 쓰지 않습니다. 동등한 결
 
 ### Phase 간 정보 전달
 
-- `requirements-discovery` 또는 `error-analysis`가 남긴 final report의 `## 5. Clarification Requests for the Next Run` 섹션에 사용자가 답변을 채운 뒤, 다음 run에서 `--clarification-response <previous-final-report.md>`로 그 파일을 carry-in합니다.
+- `requirements-discovery`, `error-analysis`, 또는 `implementation-planning` 이 남긴 final report 의 `## 1. Clarification Items` 섹션에 사용자가 답변을 채운 뒤, 다음 run 에서 `--clarification-response <previous-final-report.md>` 로 그 파일을 carry-in합니다.
 - carry-in된 파일은 현재 run의 `instruction-set/clarification-response.md`로 복사되고, lead가 Section 0에서 prior `Q*` 행의 `Status`(`resolved` / `obsolete`)를 갱신한 뒤 진행합니다.
 - 답변 편집과 재실행을 한 번에 처리하려면 `--resume-clarification` 모드를 사용합니다. 자세한 동작은 `### --resume-clarification` 섹션을 참고합니다.
 - **Stage carry-in (`implementation` → 다음 stage)**: 각 `implementation` run 은 `runs/implementation/carry/stage-<N>.json` evidence sidecar 를 남깁니다. 다음 stage 가 실행될 때 이 파일을 자동으로 carry-in 합니다. 어떤 `implementation` run 이 어떤 stage 를 소비했는지는 `runs/implementation-planning/consumers.jsonl` 에 역링크로 누적됩니다.
@@ -410,10 +410,12 @@ task manifest, task index, instruction-set, runs, history가 이 루트 아래
 ├── task-index.md
 ├── instruction-set/
 │   ├── analysis-profile.md
+│   ├── analysis-packet.md       # analysis worker primary compact input
 │   ├── analysis-material.md
 │   ├── reference-expectations.md
 │   ├── task-brief.md
 │   ├── directive.txt                  # optional (mirrors --directive)
+│   ├── final-report-schema.json
 │   ├── final-report-template.md
 │   └── claude-execution-prompt.md
 ├── runs/
@@ -638,16 +640,13 @@ canonical metadata는 항상 `task-manifest.json`을 기준으로 확인합니
 1. task browsing 또는 task-id disambiguation이 필요하면 `.okstra/discovery/task-catalog.json`을 먼저 읽습니다.
 2. 현재 task key나 task path가 명시되지 않았다면 `.okstra/discovery/latest-task.json`을 current-task pointer로 읽습니다.
 3. `task-manifest.json`을 읽습니다.
-4. `task-index.md`는 quick summary가 필요할 때만 선택적으로 읽습니다.
-5. `instruction-set/analysis-profile.md`를 읽습니다.
-6. `instruction-set/analysis-material.md`를 읽습니다.
-7. `instruction-set/reference-expectations.md`를 읽습니다.
-8. `instruction-set/task-brief.md`를 읽습니다.
-9. `instruction-set/final-report-template.md`를 읽습니다.
-10. current `manifests/run-manifest-<task-type>-<seq>.json`을 읽습니다.
-11. 필요하면 `history/timeline.json`과 이전 run 결과를 참고합니다.
-12. `Claude lead`로서 현재 run의 worker roster (기본 `Claude worker`, `Codex worker`, `Report writer worker`; `Gemini worker`는 명시 포함된 경우에만)에 따라 역할을 구성합니다.
-13. 각 selected worker prompt를 assigned worker prompt history path로 현재 run의 `prompts/` 아래에 먼저 저장한 뒤 worker를 dispatch합니다.
+4. current `state/active-run-context-<task-type>-<seq>.json`이 있으면 lead Phase 1의 1차 입력으로 읽습니다. 없으면 current `manifests/run-manifest-<task-type>-<seq>.json`과 `team-state`로 fallback합니다.
+5. `instruction-set/analysis-profile.md`와 `instruction-set/analysis-packet.md`를 읽습니다.
+6. `task-index.md`는 quick summary가 필요할 때만 선택적으로 읽습니다.
+7. `analysis-material.md`, `reference-expectations.md`, `task-brief.md`, `final-report-template.md`는 packet이 불충분하거나 source citation/보고서 작성에 필요할 때 lazy read합니다.
+8. 필요하면 `history/timeline.json`과 이전 run 결과를 참고합니다.
+9. `Claude lead`로서 현재 run의 worker roster (기본 `Claude worker`, `Codex worker`, `Report writer worker`; `Gemini worker`는 명시 포함된 경우에만)에 따라 역할을 구성합니다.
+10. 각 selected worker prompt를 assigned worker prompt history path로 현재 run의 `prompts/` 아래에 먼저 저장한 뒤 worker를 dispatch합니다.
 14. 각 required worker에 대해 결과 또는 terminal status를 수집합니다.
 15. brief이 더 구체적인 형식을 강제하지 않으면 `final-report-template.md` 구조로 Markdown 최종 보고서를 작성합니다.
 16. 결과를 현재 run의 `reports/final-report-<task-type>-<seq>.md`에 직접 저장하고, 필요하면 `status/final-<task-type>-<seq>.status`, `manifests/run-manifest-<task-type>-<seq>.json`, `task-manifest.json`, `task-index.md`도 현재 상태에 맞게 갱신합니다.
@@ -661,9 +660,9 @@ canonical metadata는 항상 `task-manifest.json`을 기준으로 확인합니
 
 ## Task brief usage
 
-`okstra`는 brief-first 구조입니다. brief 가 분석의 정본 입력이며, 워커가 필요로 할 추가 자료(보고서, 코드 스니펫, 로그 등)는 brief 내부의 `Evidence and Source Materials` 섹션에 inline 또는 path 로 모두 포함시킵니다.
+`okstra`는 brief-first 구조입니다. brief 는 외부 입력과 okstra 보강을 보존하는 정본 source material 이며, 워커가 필요로 할 추가 자료(보고서, 코드 스니펫, 로그 등)는 brief 내부의 `Evidence and Source Materials` 섹션에 inline 또는 path 로 모두 포함시킵니다.
 
-brief 는 **translation layer** 입니다 — 외부 입력 (이슈 트래커 ticket, 요구사항 문서, 사용자 메시지) 을 okstra-readable 형식으로 옮기되, 원문은 verbatim 으로 보존하고 okstra 가 추가한 부분은 labelled augmentation 으로 명확히 구분합니다. okstra-brief skill 의 산출이 정식 SSOT 이며, 분석 워커들이 phase 시작 전에 일률적으로 읽어들이는 단일 입력입니다.
+brief 는 **translation layer** 입니다 — 외부 입력 (이슈 트래커 ticket, 요구사항 문서, 사용자 메시지) 을 okstra-readable 형식으로 옮기되, 원문은 verbatim 으로 보존하고 okstra 가 추가한 부분은 labelled augmentation 으로 명확히 구분합니다. `okstra-brief` skill 의 산출이 source SSOT 이고, `prepare_task_bundle()` 은 분석 phase 마다 여기서 필요한 frontmatter, task-specific brief 섹션, reference expectations, carry-in clarification, directive 를 추출해 `instruction-set/analysis-packet.md` 를 만듭니다. 분석 워커의 1차 입력은 이 compact packet 이며, 원본 brief 와 profile/material 파일은 근거 확인이나 누락 보완이 필요할 때만 여는 fallback evidence 입니다.
 
 brief에는 보통 아래를 포함합니다.
 

package/docs/kr/cli.md

@@ -183,11 +183,11 @@ scripts/okstra.sh --task-key jobs:tasks:8852 --task-type final-verification
 
 ### `--clarification-response`
 
-이전 run의 final report(`Section 5. Clarification Requests for the Next Run`에 사용자가 답변을 inline으로 채운 파일)를 다음 run으로 carry-in합니다.
+이전 run의 final report(`## 1. Clarification Items`에 사용자가 답변을 inline으로 채운 파일)를 다음 run으로 carry-in합니다.
 
 - 입력: `<previous-run>/reports/final-report-<task-type>-<seq>.md` 경로
 - 동작: 파일을 현재 run의 `instruction-set/clarification-response.md`로 복사하고, lead가 Section 0에서 prior `Q*` 행의 `Status`(`resolved` / `obsolete`)를 갱신한 뒤 진행합니다.
-- 사용 시점: `requirements-discovery`, `error-analysis`처럼 미해결 질문을 남기는 phase 이후, 사용자가 답변을 채워 다음 phase로 넘길 때.
+- 사용 시점: `requirements-discovery`, `error-analysis`, `implementation-planning`처럼 미해결 질문이나 approval-blocking clarification 을 남기는 phase 이후, 사용자가 답변을 채워 다음 phase 또는 같은 phase resume 으로 넘길 때.
 
 예:
 
@@ -262,7 +262,7 @@ scripts/okstra.sh --task-type error-analysis --project-id jobs --project-root /V
 
 ### `--directive`
 
-사용자 의도를 자유 텍스트로 lead·worker·downstream skill에 전달하는 채널입니다. 값은 `instruction-set/analysis-material.md` 끝에 `## Directive` 섹션으로 임베딩되고, 동시에 `instruction-set/directive.txt`로 백업됩니다.
+사용자 의도를 자유 텍스트로 lead·worker·downstream skill에 전달하는 채널입니다. 값은 `instruction-set/analysis-material.md` 끝에 `## Directive` 섹션으로 임베딩되고, analysis worker 의 1차 입력인 `instruction-set/analysis-packet.md` 에도 포함됩니다. 동시에 `instruction-set/directive.txt`로 백업됩니다.
 
 용도:
 
@@ -272,7 +272,7 @@ scripts/okstra.sh --task-type error-analysis --project-id jobs --project-root /V
 
 해석 규칙:
 
-- lead·worker는 `analysis-material.md`를 이미 end-to-end로 읽으므로 별도 작업 없이 자동 전파됩니다.
+- lead·analysis worker는 compact intake(`active-run-context`, `analysis-packet.md`)를 1차 입력으로 읽으므로 directive가 별도 작업 없이 전파됩니다. `analysis-material.md`는 packet이 불충분하거나 source citation 검증이 필요할 때 여는 fallback입니다.
 - skill 측은 자체 contract보다 user prompt를 **우선** 적용해야 하며 (예: `okstra-schedule` 스킬의 "Directive override (highest priority)" 절), heuristic을 뒤집은 경우 결과 문서에 그 사실을 한 줄로 표시합니다.
 
 예:
@@ -475,7 +475,7 @@ scripts/okstra.sh --task-type error-analysis --related-tasks scanner-regression,
 
 `implementation-planning` task-type 의 Phase 6 plan-body verification 라운드를 끕니다. 기본값은 활성. 다른 task-type 에서는 무시됩니다.
 
-- **활성 (default)**: Phase 6 에서 Report writer worker 가 final-report draft 를 작성한 직후, lead 가 합성된 plan 의 §4.5 본문 (Option Candidates / Stepwise Execution Order / Dependency / Validation Checklist / Rollback) 을 `P-*` plan-item 단위로 쪼개 모든 analyser 워커 (`claude`, `codex`, 그리고 옵트인된 `gemini`) 에게 reverify dispatch 합니다. 워커의 평결 (`AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`) 을 집계해 4 가지 gate result (`passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`) 중 하나를 산출하고, `passed` / `passed-with-dissent` 일 때만 final-report 상단의 `- [ ] Approved` 마커가 렌더됩니다. majority DISAGREE 항목은 `## 1. Clarification Items` 의 `Blocks=approval` row 로 변환됩니다 (자동 revise 없음 — 사용자가 답변 후 같은 phase 를 resume 해야 함).
+- **활성 (default)**: Phase 6 에서 Report writer worker 가 final-report draft 를 작성한 직후, lead 가 합성된 plan 의 §5.5 implementation plan deliverables 본문 (Option Candidates / Stepwise Execution Order / Dependency / Validation Checklist / Rollback) 을 `P-*` plan-item 단위로 쪼개 모든 analyser 워커 (`claude`, `codex`, 그리고 옵트인된 `gemini`) 에게 reverify dispatch 합니다. 워커의 평결 (`AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`) 을 집계해 4 가지 gate result (`passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`) 중 하나를 산출하고, `passed` / `passed-with-dissent` 일 때만 final-report 상단의 `- [ ] Approved` 마커가 렌더됩니다. majority DISAGREE 항목은 `## 1. Clarification Items` 의 `Blocks=approval` row 로 변환됩니다 (자동 revise 없음 — 사용자가 답변 후 같은 phase 를 resume 해야 함).
 - **비활성 (`--no-plan-verification` 전달 시)**: Phase 6 sub-step 전체가 skip 되고 final-report 상단의 Approval 마커가 무조건 렌더됩니다 (legacy 동작). 빠른 반복용 opt-out — handoff-ready plan 에는 권장하지 않습니다.
 - 본 flag 는 manifest 의 `convergence.planBodyVerification.enabled` 를 `false` 로 기록합니다. resume 명령에서도 같은 flag 를 명시해야 같은 동작이 유지됩니다 (`_canonical_argv` 가 resume fidelity emit 을 보장).
 - 자세한 라운드 프로토콜 / verdict semantics / state 파일 스키마는 `skills/okstra-convergence/SKILL.md` 의 "Plan-body verification mode (implementation-planning only)" 섹션 참고.

package/docs/project-structure-overview.md

@@ -24,11 +24,11 @@
 
 현재 기준:
 
-- package version: `0.34.1`
+- package version: `0.50.0`
 - Node CLI entrypoint: `bin/okstra`
 - Python orchestration authority: `scripts/okstra_ctl/run.py::prepare_task_bundle`
 - lifecycle: `requirements-discovery → error-analysis → implementation-planning → implementation → final-verification → release-handoff`
-- installed skills: 10개
+- installed skills: 11개
 - worker agents: `claude`, `codex`, `gemini`, `report-writer`
 - final report SSOT: `schemas/final-report-v1.0.schema.json` + `*.data.json`
 
@@ -54,7 +54,7 @@ okstra/
 │   ├── okstra_vendor/               vendored Jinja2 / MarkupSafe
 │   ├── lib/okstra/                  Bash helpers for okstra.sh
 │   └── lib/okstra-ctl/              Bash control-center subcommands
-├── skills/                          Claude Code skills (10)
+├── skills/                          Claude Code skills (11)
 ├── agents/                          lead SKILL.md + worker agent specs
 ├── prompts/                         launch template, phase profiles, wizard prompt JSON
 ├── schemas/                         JSON schema for final-report data.json
@@ -137,13 +137,16 @@ So `runtime/` is not the only npm-published content. It is the install payload c
 | `setup` | `src/setup.mjs` | Create/update `<PROJECT_ROOT>/.okstra/project.json` |
 | `check-project` | `src/check-project.mjs` | Verify project registration |
 | `config` | `src/config.mjs` | Read/write project/global settings such as PR template path |
+| `migrate` | `src/migrate.mjs` | Move legacy `.project-docs/okstra/` state into `.okstra/` |
 | `task-list`, `task-show` | `src/task-list.mjs`, `src/task-show.mjs` | Task/run introspection for skills |
+| `context-cost` | `src/context-cost.mjs` | Estimate task bundle file/read context cost |
 | `worktree-lookup` | `src/worktree-lookup.mjs` | Look up a task-key's registered worktree |
 | `plan-validate` | `src/plan-validate.mjs` | Check approved-plan approval marker |
 | `render-bundle` | `src/render-bundle.mjs` | Preview `prepare_task_bundle(render_only=True)` |
 | `render-views` | `src/render-views.mjs` | Generate slim MD + self-contained HTML report views |
 | `wizard` | `src/wizard.mjs` | Drive the `okstra-run` interactive state machine |
 | `token-usage` | `src/token-usage.mjs` | Wrap installed Python token usage CLI |
+| `memory` | `src/memory.mjs` | Store/find global conversation memory under `~/.okstra/memory-book` |
 
 `src/_python-helper.mjs` centralizes Node → Python execution so command modules do not duplicate subprocess wiring.
 
@@ -244,20 +247,21 @@ Token/cost accounting:
 
 ### 4.10 `skills/`
 
-10 installed skills:
+11 installed skills:
 
 | Skill | User-invocable | Role |
 |---|---:|---|
 | `okstra-brief` | yes | Produce task brief from ticket/doc/link/conversation |
 | `okstra-run` | yes | Start/resume okstra task in current Claude Code session |
 | `okstra-memory` | yes | Store/search/archive global conversation memory under `~/.okstra/memory-book` |
-| `okstra-inspect` | yes | Unified read-side — sub-commands `status` (lifecycle + workStatus), `history` (past runs / re-run / resume), `report` (find final-report), `time` (elapsed-time breakdown), `logs` (wrapper log inventory + cleanup) |
+| `okstra-inspect` | yes | Unified read-side — sub-commands `status` (lifecycle + workStatus), `history` (past runs / re-run / resume), `report` (find final-report), `time` (elapsed-time breakdown), `logs` (wrapper log inventory + cleanup), `cost` (task bundle context/read cost) |
 | `okstra-schedule` | yes | Generate task-group schedule |
 | `okstra-setup` | yes | Install/check runtime and register project |
 | `okstra-context-loader` | no | Load task bundle paths/manifests for phase start |
 | `okstra-team-contract` | no | Worker roster/model/rule contract |
 | `okstra-convergence` | no | Cross-worker convergence and plan-body verification |
 | `okstra-report-writer` | no | Final report data.json authoring flow |
+| `okstra-coding-preflight` | no | Language-specific coding conventions and architecture overlays for implementation executors/verifiers |
 
 ### 4.11 `agents/`
 
@@ -440,4 +444,4 @@ Clarifications now live in the unified `## 1. Clarification Items` table. Deprec
 
 ---
 
-*Updated: 2026-05-20 · Source of truth checked against `package.json`, `bin/okstra`, `tools/build.mjs`, `scripts/`, `skills/`, `agents/`, `templates/`, `schemas/`, `validators/`, and tests.*
+*Updated: 2026-06-05 · Source of truth checked against `package.json`, `bin/okstra`, `tools/build.mjs`, `scripts/`, `skills/`, `agents/`, `templates/`, `schemas/`, `validators/`, and tests.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.50.0",
+  "version": "0.51.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.50.0",
-  "builtAt": "2026-06-05T10:53:30.670Z",
+  "package": "0.51.0",
+  "builtAt": "2026-06-05T15:09:03.772Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -44,7 +44,7 @@ This SKILL.md is the operating contract and phase index. Detailed procedures liv
 | 5.5 Convergence | Cross-verify findings across workers | `okstra-convergence` |
 | 5.6 Critic pass | (opt-in) reused-worker critic pass: coverage gaps (discovery/error-analysis/impl-planning) or acceptance devil's-advocate (final-verification), each verified one round | `okstra-convergence` "Coverage critic pass" / "Acceptance critic pass" |
 | 6. Synthesis | Dispatch Report writer worker, review draft. **For `implementation-planning`: then run the Phase 6 plan-body verification sub-step (see Phase 6 section below).** | `okstra-report-writer` + `okstra-convergence` (sub-step) |
-| 7. Persist | Run token-usage collector, update manifests, then disband the worker team (shutdown teammates + `TeamDelete`, after collection) | `okstra-report-writer` + `_common-contract.md` "Run-end team teardown" |
+| 7. Persist | Run token-usage collector, update manifests, then disband the worker team (reconcile stale members + `TeamDelete`, after collection) | `okstra-report-writer` + `_common-contract.md` "Run-end team teardown" |
 
 ## Core operating contract
 
@@ -96,7 +96,7 @@ Required checkpoints:
 - `PROGRESS: phase-5.6-critic provider=<provider> gaps=<n>` — when the coverage critic pass runs (Phase 5.6, opt-in). Omitted when `convergence.critic.enabled == false`.
 - `PROGRESS: phase-6-synthesis dispatching report-writer-worker` — at the start of Phase 6.
 - `PROGRESS: phase-7-persist updating manifests` — at the start of Phase 7.
-- `PROGRESS: phase-7-teardown disbanding team` — after token-usage collection, immediately before shutting down worker teammates + `TeamDelete` (Teams mode only; see `_common-contract.md` "Run-end team teardown"). Skipped in the no-`team_name` fallback.
+- `PROGRESS: phase-7-teardown disbanding team` — after token-usage collection, immediately before reconciling stale members + `TeamDelete` (Teams mode only; see `_common-contract.md` "Run-end team teardown"). Skipped in the no-`team_name` fallback.
 - `PROGRESS: complete final-report=<relative-path>` — final summary line, after all persistence.
 
 These lines are the only structured signal the user has during a long run. Do NOT replace them with prose ("Now I'm starting Phase 2..."), do NOT skip a checkpoint because "the previous message already said that", and do NOT batch multiple checkpoints into one. Each line stands alone so the user (or any operator scraping stdout) can timestamp it externally.
@@ -107,6 +107,8 @@ These lines are the only structured signal the user has during a long run. Do NO
 
 **The lead never invents a model.** Every role's model is read from `task-manifest.json` → `resultContract.requiredWorkerRoles[*].modelExecutionValue` (and the lead model metadata). A missing assignment is a manifest defect, not a license to fall back — see [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) "Model Assignment Rules". The manifest is always populated at run-prep time by the CLI, which seeds these values from `OKSTRA_DEFAULT_*_MODEL` (`scripts/okstra_ctl/run.py`).
 
+**Reading the assignment is not enough — it must be applied at spawn.** For the in-process Claude subagents (`Claude worker`, `Report writer worker`), the manifest value is bound only when lead passes it as the `Agent(...)` `model:` parameter; their `model: inherit` frontmatter otherwise follows the lead's own model. See "Model Assignment Rules" #3–#5 in [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) for the spawn rule, the family-token mapping, and the Codex/Gemini exemption.
+
 The table below documents those prep-time seed values **for reference only** — it is NOT a lead-applied fallback:
 
 | Role | Seed model | subagent_type | Source definition |
@@ -152,21 +154,21 @@ 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 `.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 `.okstra/discovery/task-catalog.json` first.
 
-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.
+After context-loader completes, read **only the compact intake 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. `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
+2. `runs/<task-type>/state/active-run-context-<task-type>-<seq>.json` — compact current-run intake; if absent, fall back to the current run manifest + team-state artifact
+3. `instruction-set/analysis-profile.md` — needed to pick the right `Required workers:` block and phase rules
+4. `instruction-set/analysis-packet.md` — primary compact input for analysis worker dispatch
 
 **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/task-brief.md` — read only if the packet is insufficient, a cited source needs verification, or report-writer synthesis requires the full source.
+- `instruction-set/analysis-material.md` — read only if the packet is insufficient or a source citation needs verification. Many task bundles have no meaningful material file beyond a duplicate brief wrapper.
+- `instruction-set/reference-expectations.md` — read at Phase 6 synthesis (or whenever the report-writer worker is dispatched) — it informs the match/gap assessment. Analysis workers use the packet excerpt unless they need source verification.
 - `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.
 
@@ -186,7 +188,7 @@ The guard is not satisfied by remembering content from a prior run — each impl
 
 This pattern is implementation-only. Other profiles (`requirements-discovery`, `error-analysis`, `implementation-planning`, `final-verification`, `release-handoff`) load their whole profile body at Phase 1 as before — they are short enough not to benefit from a split.
 
-Extract from the five mandatory files: task key, task type, work category, workflow lifecycle snapshot, selected worker roster, assigned models, worker result paths, worker prompt history paths, current run prompt directory, final report path, final status path, validator path, resume helper path, config-file references, deployment-manifest references, and their expected values or invariants.
+Extract from the compact intake files: task key, task type, work category, workflow lifecycle snapshot, selected worker roster, assigned models, worker result paths, worker prompt history paths, current run prompt directory, final report path, final status path, validator path, resume helper path, config-file references, deployment-manifest references, and their expected values or invariants.
 
 If previous run reports exist, use as historical context only. If discovery metadata or current artifacts conflict with a newer user instruction, prefer the user instruction. If `reference-expectations.md` explicitly says expectations were not provided (you can confirm this without reading the file if the brief's "Expected state" section is empty), treat that as missing information and say `I don't know` rather than inventing expected states.
 
@@ -195,7 +197,7 @@ If previous run reports exist, use as historical context only. If discovery meta
 These phases are governed by [okstra-team-contract](./skills/okstra-team-contract/SKILL.md). It is the canonical source for:
 
 - Worker prompt anchor headers and body composition rules.
-- The `[Required reading]` clause (audience-scoped enumeration: analysis workers vs report-writer vs reverify dispatches).
+- The `[Required reading]` clause (analysis-packet primary input for analysis workers, full source files for report-writer, scoped inputs for reverify dispatches).
 - The `[Error reporting]` clause and the asymmetry between claude-worker and codex/gemini-worker prompts.
 - Worker output contract (sections 0–5), header standard, terminal statuses, errors-sidecar schema.
 - Token-usage tracking conventions.
@@ -220,6 +222,8 @@ Spawn **analysis workers only** in the same turn (Phase 4 in Teams mode; Phase 5
 
 **Agent `name` on dispatch (BLOCKING — token-usage attribution depends on it).** Every analysis-worker `Agent(...)` call MUST set `name: "<workerId>-worker"` — `name: "claude-worker"` / `name: "codex-worker"` / `name: "gemini-worker"` — exactly as the report-writer dispatch sets `name: "report-writer"` ([okstra-report-writer](./skills/okstra-report-writer/SKILL.md)). The Agent harness records this `name` as `agentName` in the subagent session jsonl, and the Phase 7 token collector matches each worker's session by that `agentName` (`okstra_token_usage/collect.py`). A worker dispatched **without** `name` produces a session with no `agentName`; the collector cannot attribute it and records the worker as `source: "unavailable"` even though the session exists and is team-tagged (observed in `dev-9692` error-analysis: `claude`/`codex` workers dispatched without `name` → both `unavailable`, while the named `report-writer` collected normally). Convergence reverify dispatches keep the prefix (`<workerId>-worker-reverify-r<N>`); implementation executor/verifier variants keep `<workerId>-worker` / `<workerId>-executor`.
 
+**Agent `model:` on dispatch (BLOCKING — assignment is otherwise ignored).** The `Claude worker` `Agent(...)` call MUST set `model: "<family token of that role's modelExecutionValue>"` (`opus` / `sonnet` / `haiku`), per [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) "Model Assignment Rules" #3–#4. The claude-worker definition is `model: inherit`, so omitting this parameter makes the worker silently run on the lead's model instead of its manifest assignment — the assigned-vs-actual deviation. `Codex worker` / `Gemini worker` are exempt: their CLI model is applied via the wrapper's own `--model` argument, so leave their Agent `model:` at `inherit` (rule #5).
+
 The no-`team_name` fallback (Phase 5) is only legal when team-state's `teamCreate.status` is `"error"` for this run. If `teamCreate` is missing or `attempted: false`, the correct action when an Agent dispatch is rejected for a missing team is to GO BACK to Phase 3 and call `TeamCreate` — never to strip `team_name` and continue.
 
 ### Errors log path wiring (BLOCKING)

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

@@ -45,7 +45,7 @@ Unlike the Codex / Gemini workers, you are an in-process Claude subagent — you
 
 4. Anchor all file operations to the absolute `Project Root` from the lead prompt. Use absolute paths — do NOT rely on inherited cwd. Never use `cd` to change directory.
    - **Executor exception (implementation phase only):** when this worker is dispatched as the `Executor` and the lead prompt provides an `EXECUTOR_WORKTREE_PATH` that differs from the session's inherited cwd, cwd-sensitive Bash commands (`cargo *`, `npm *`, `pnpm *`, `bun *`, `pytest`, `make *`, `go *`, language-toolchain test/build commands) MUST be prefixed with `cd <EXECUTOR_WORKTREE_PATH> && ` in the same Bash invocation — e.g. `cd /Users/.../worktrees/foo && cargo test -p bar`. Do NOT wrap the whole thing in `bash -lc "..."` or `bash -c "..."`; pass the chained command directly to the Bash tool so the leading `cd` token remains visible to the permission layer. The `cd` is scoped to the single Bash subshell and does not mutate the session's shell state, so this does not conflict with the "never use cd" rule above (which prevents the worker from drifting the session cwd across calls).
-   - **Executor coding-conventions preflight (BLOCKING, before your first `Edit` / `Write`):** when dispatched as the `Executor`, you MUST run the coding-conventions preflight defined in the executor sidecar (`prompts/profiles/_implementation-executor.md` → "Pre-implementation context exploration") before writing any code — detect each touched file's language and invoke the project's coding-conventions skill (`coding-preflight` when installed; it routes the matching `languages/<lang>.md` + `clean-code.md` + any hexagonal overlay), then state in one line which conventions apply. Subagents do NOT auto-trigger skills, so this is an explicit step you must perform; if no such skill is reachable in your runtime, degrade per that sidecar section (agnostic principles + project lint/convention files) — never skip the gate.
+   - **Executor coding-conventions preflight (BLOCKING, before your first `Edit` / `Write`):** when dispatched as the `Executor`, you MUST run the coding-conventions preflight defined in the executor sidecar (`prompts/profiles/_implementation-executor.md` → "Pre-implementation context exploration") before writing any code — detect each touched file's language and read okstra's installed coding-conventions files directly — `~/.claude/skills/okstra-coding-preflight/languages/<lang>.md` + `clean-code.md` + any `architecture/hexagonal.md` overlay (placed by `okstra install`), then state in one line which conventions apply. The skill is `user-invocable: false` and subagents do NOT auto-trigger skills, so read the files via the Read tool by absolute path rather than relying on Skill invocation; if those files are not readable in your runtime, degrade per that sidecar section (agnostic principles + project lint/convention files) — never skip the gate.
    - **Verifier QA-gate exception:** verifier roles MAY use the same `cd <WORKTREE> && <cmd>` shape when executing project-declared `qaCommands` (lint / format / typecheck / test) from `project.json`, since those commands are cwd-sensitive by nature. Outside the QA gate, verifiers still read with absolute paths only — do NOT use `cd` for file inspection.
    - **No extra chaining beyond `cd && cmd`:** the permission matcher only allows the exact two-segment shape `cd <PATH> && <single-command>`. Do NOT append additional pipes, semicolons, redirects, or `&&` chains — e.g. `cd ... && cargo test ... 2>&1 | tail -20; echo "exit:$?"` will trigger a permission prompt every dispatch because the trailing `| tail`, `; echo`, and `2>&1` tokens disqualify the prefix match against `Bash(cargo:*)`. Let Claude Code capture the full stdout/stderr and exit code natively — do not post-process with `tail`, `head`, or `echo "exit:$?"`. If output truncation is genuinely needed, run the command first and read the result in a separate tool call.
 
@@ -60,7 +60,7 @@ Unlike the Codex / Gemini workers, you are an in-process Claude subagent — you
 Before producing any output, you MUST:
 
 1. Extract the absolute path from the lead's `**Worker Preamble Path:**` anchor header and Read that file end-to-end with a single `Read` call (no `offset`, no `limit`). This is the canonical SSOT for the Required Reading + Error Reporting + Output sections contract.
-2. Read every input file the lead enumerated under `## Inputs` (or equivalent heading) in the dispatch prompt body, end-to-end, following the rules stated in the preamble. For analysis workers this is task-brief + analysis-profile + analysis-material (if present) + reference-expectations + clarification-response (if carry-in). Analysis workers do NOT read `final-report-template.md` — that file is for the report writer only.
+2. Read every primary input file the lead enumerated under `## Inputs` (or equivalent heading) in the dispatch prompt body, end-to-end, following the rules stated in the preamble. For analysis workers this is normally `analysis-packet.md`; the source files named inside that packet are fallback/evidence paths to open when needed. Analysis workers do NOT read `final-report-template.md` — that file is for the report writer only.
 
 **Heartbeat — write the audit sidecar EARLY and APPEND per stage (BLOCKING).** Because this worker runs as an in-process Agent or a fresh-session tmux pane, the lead has no `BashOutput`-style liveness signal while waiting for your return. The audit sidecar is the only signal that survives a silent hang. Write the sidecar at `runs/<task-type>/worker-results/claude-worker-audit-<task-type>-<seq>.md` immediately after extracting `Project Root` and the assigned paths — BEFORE the per-file end-to-end reads — with just the heading line (`# Claude Worker Audit — <task-key>`) and one `- PROGRESS: started <ISO-8601-UTC>` line. Then APPEND one short progress line per stage as you advance: `read-<filename>`, `analysis-start`, `findings-draft-start`, `findings-draft-complete`, `write-result-start`. The append cadence MUST NOT exceed 5 minutes — if a single analysis stage is taking longer, emit a `- PROGRESS: in-stage:<stage> <ISO-8601-UTC>` heartbeat. A 5-minute stale sidecar mtime is the canonical "this worker has hung" signal for the operator. Sidecar write/append uses `Write` (initial) and `Edit` / heredoc `>>` (per-stage append).
 
@@ -68,7 +68,7 @@ Before producing any output, you MUST:
 
 When returning results, start the file with a YAML frontmatter block, then organize the body into the following sections in this exact order.
 
-**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.
+**Frontmatter (mandatory)** — set `workerId: "claude"`. Copy `id`, `aliases`, `taskType`, `task-id`, `task-group`, `project-id`, `date` verbatim from the primary input (`analysis-packet.md`; fall back to `analysis-material.md` only if the packet is missing a field). Full schema and a concrete example live in the `okstra-team-contract` skill's "Result Frontmatter" subsection.
 
 1. **Findings** - what you identified
 2. **Missing Information or Assumptions** - gaps in the analysis

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

@@ -143,7 +143,7 @@ This wrapper does NOT invoke MCP tools directly. MCP availability inside the Cod
 Before invoking the Codex CLI, you MUST:
 
 1. Extract the absolute path from the lead's `**Worker Preamble Path:**` anchor header and verify the CLI run will Read that file end-to-end (canonical SSOT for the Required Reading + Error Reporting + Output sections contract). The lead's prompt body — which you persist verbatim and feed into Codex via stdin — already contains this anchor; do not strip it.
-2. Verify the lead's prompt body lists the per-run input files under `## Inputs` (task-brief, analysis-profile, analysis-material if present, reference-expectations, clarification-response if carry-in). Analysis workers do NOT read `final-report-template.md` — that file is for the report writer only.
+2. Verify the lead's prompt body lists the per-run primary input files under `## Inputs` (normally `analysis-packet.md` for analysis workers). The source files named inside that packet are fallback/evidence paths to open when needed. Analysis workers do NOT read `final-report-template.md` — that file is for the report writer only.
 
 The CLI writes a Reading Confirmation block to the **audit sidecar** at `runs/<task-type>/worker-results/codex-worker-audit-<task-type>-<seq>.md`. The sidecar's body begins with `# Codex Worker Audit — <task-key>` followed by one short line per input file confirming end-to-end reading. The main Codex output MUST NOT contain a `## 0. Reading Confirmation` heading — the validator fails worker-results that contain one. If any file was skipped, record a `tool-failure` in the errors sidecar instead of fabricating Findings.
 
@@ -151,7 +151,7 @@ The CLI writes a Reading Confirmation block to the **audit sidecar** at `runs/<t
 
 When returning results, start the file with a YAML frontmatter block, then organize the body into the following sections in this exact order.
 
-**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.
+**Frontmatter (mandatory)** — set `workerId: "codex"`. Copy `id`, `aliases`, `taskType`, `task-id`, `task-group`, `project-id`, `date` verbatim from the primary input (`analysis-packet.md`; fall back to `analysis-material.md` only if the packet is missing a field). Full schema and a concrete example live in the `okstra-team-contract` skill's "Result Frontmatter" subsection.
 
 1. **Findings** - what Codex identified
 2. **Missing Information or Assumptions** - gaps in the analysis

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

@@ -143,7 +143,7 @@ This wrapper does NOT invoke MCP tools directly. MCP availability inside the Gem
 Before invoking the Gemini CLI, you MUST:
 
 1. Extract the absolute path from the lead's `**Worker Preamble Path:**` anchor header and verify the CLI run will Read that file end-to-end (canonical SSOT for the Required Reading + Error Reporting + Output sections contract). The lead's prompt body — which you persist verbatim and feed into Gemini via stdin — already contains this anchor; do not strip it.
-2. Verify the lead's prompt body lists the per-run input files under `## Inputs` (task-brief, analysis-profile, analysis-material if present, reference-expectations, clarification-response if carry-in). Analysis workers do NOT read `final-report-template.md` — that file is for the report writer only.
+2. Verify the lead's prompt body lists the per-run primary input files under `## Inputs` (normally `analysis-packet.md` for analysis workers). The source files named inside that packet are fallback/evidence paths to open when needed. Analysis workers do NOT read `final-report-template.md` — that file is for the report writer only.
 
 The CLI writes a Reading Confirmation block to the **audit sidecar** at `runs/<task-type>/worker-results/gemini-worker-audit-<task-type>-<seq>.md`. The sidecar's body begins with `# Gemini Worker Audit — <task-key>` followed by one short line per input file confirming end-to-end reading. The main Gemini output MUST NOT contain a `## 0. Reading Confirmation` heading — the validator fails worker-results that contain one. If any file was skipped, record a `tool-failure` in the errors sidecar instead of fabricating Findings.
 
@@ -151,7 +151,7 @@ The CLI writes a Reading Confirmation block to the **audit sidecar** at `runs/<t
 
 When returning results, start the file with a YAML frontmatter block, then organize the body into the following sections in this exact order.
 
-**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.
+**Frontmatter (mandatory)** — set `workerId: "gemini"`. Copy `id`, `aliases`, `taskType`, `task-id`, `task-group`, `project-id`, `date` verbatim from the primary input (`analysis-packet.md`; fall back to `analysis-material.md` only if the packet is missing a field). Full schema and a concrete example live in the `okstra-team-contract` skill's "Result Frontmatter" subsection.
 
 1. **Findings** - what Gemini identified
 2. **Missing Information or Assumptions** - gaps in the analysis