okstra 0.113.0 → 0.115.0

package/README.kr.md

@@ -157,7 +157,7 @@ Claude Code 세션 안에서 사용하는 슬래시 커맨드:
 
 | 커맨드 | 용도 |
 |---|---|
-| `/okstra-brief` | ticket, 요구사항 문서, 링크, 대화 내용을 `okstra-run`용 task brief로 변환 |
+| `/okstra-brief-gen` | 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 조회·정리 제안), `cost` (task bundle 컨텍스트/읽기 비용), `errors` (run 에러 로그를 리포트로 집계), `error-zip` (cross-project 에러 로그를 익명화 zip 으로 수집·클러스터 요약), `recap` (run 간 전/후 요약 + task 의 `.okstra` 산출물 위 자유 Q&A) |
@@ -201,7 +201,7 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 - **실험적 Codex lead adapter** — `okstra codex-run <render-bundle args...>` 가 Claude Code 를 띄우지 않고 `leadRuntime=codex` task bundle 을 준비합니다. 이어서 `okstra codex-dispatch --project-root <dir> --run-manifest <path>` 로 roster 중 Codex-side 지원 subset 을 실행합니다(Codex/Antigravity CLI worker 기본, Codex report-writer 는 `--enable-codex-report-writer --report-writer-codex-model <model>` opt-in 필요). 성공한 Codex report-writer dispatch 는 token/cost substitution, HTML view 렌더, follow-up stub 생성, run validation 을 순서대로 자동 실행합니다. Claude lead 경로와 같은 manifest/schema 를 공유하며, 프로젝트를 Codex 전용 fork 로 복제하지 않습니다.
 - **다단계 `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 라운드의 사후 검증을 추가로 돌립니다. 합성된 `## 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` 로 발행되며, blocking gate 결과는 이를 false 로 유지하고 `## 1. Clarification Items` row 로 변환합니다. 빠른 반복용 opt-out 은 `--no-plan-verification` 입니다. 세부 계약: [`prompts/lead/convergence.md`](prompts/lead/convergence.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`).
+- **Brief = translation layer + Step 6.5 reporter batch confirmation** — `okstra-brief-gen` 가 외부 입력 (이슈 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 에서 평가).
 - **Self-contained HTML final-report view** — Phase 7 가 `final-report-<task-type>-<seq>.md` 를 쓰면 `okstra render-views` 가 같은 `reports/` 폴더에 사람 reviewer 용 self-contained HTML view (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).

package/README.md

@@ -155,7 +155,7 @@ User-facing slash commands inside a Claude Code session:
 
 | Command | Use |
 |---|---|
-| `/okstra-brief` | Turn a ticket, requirements doc, link, or conversation into an `okstra-run` task brief |
+| `/okstra-brief-gen` | 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), `cost` (task bundle context/read cost), `errors` (aggregate run error logs into a report), `error-zip` (collect cross-project error logs into an anonymized zip and summarize clusters), `recap` (run-to-run before/after summary + free-form Q&A over a task's `.okstra` artifacts) |
@@ -199,7 +199,7 @@ Recent workflow additions (post-0.8.0, on `main`):
 - **Experimental Codex lead adapter** — `okstra codex-run <render-bundle args...>` prepares a `leadRuntime=codex` task bundle without launching Claude Code. `okstra codex-dispatch --project-root <dir> --run-manifest <path>` can then run the supported Codex-side subset of the roster (Codex/Antigravity CLI workers by default; Codex report-writer only with `--enable-codex-report-writer --report-writer-codex-model <model>`). Successful Codex report-writer dispatch runs token/cost substitution, HTML view rendering, follow-up stub generation, and run validation in order. This shares the same manifests/schemas as the Claude lead path; it does not clone the project into a separate Codex-specific fork.
 - **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 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`; blocking gate results keep it false and become `## 1. Clarification Items` rows. Details: [`prompts/lead/convergence.md`](prompts/lead/convergence.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`).
+- **Brief as translation layer + reporter batch confirmation (Step 6.5)** — `okstra-brief-gen` 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`).
 - **Self-contained HTML final-report view** — after Phase 7 writes `final-report-<task-type>-<seq>.md`, `okstra render-views` automatically emits a sibling self-contained HTML view (inline CSS/JS, no external URLs) in the same `reports/` directory 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).

package/docs/for-ai/README.md

@@ -17,7 +17,7 @@
 | 사용자 의도 | 사용할 스킬 | 매뉴얼 |
 |---|---|---|
 | 새 프로젝트나 새 머신에서 okstra 설치/초기화 | `okstra-setup` | [`skills/okstra-setup.md`](skills/okstra-setup.md) |
-| 요구사항, 티켓, 링크, 코드베이스 스캔, error-zip을 okstra 입력 brief로 변환 | `okstra-brief` | [`skills/okstra-brief.md`](skills/okstra-brief.md) |
+| 요구사항, 티켓, 링크, 코드베이스 스캔, error-zip을 okstra 입력 brief로 변환 | `okstra-brief-gen` | [`skills/okstra-brief-gen.md`](skills/okstra-brief-gen.md) |
 | 현재 Claude Code 세션에서 okstra run 시작 또는 다음 phase 실행 | `okstra-run` | [`skills/okstra-run.md`](skills/okstra-run.md) |
 | 여러 프로젝트에 걸친 okstra task 묶음, 할당, sync snapshot, child launch packet 관리 | `okstra-manager` | [`skills/okstra-manager.md`](skills/okstra-manager.md) |
 | 상태, history, report, time, logs, cost, errors, error-zip, recap 확인 | `okstra-inspect` | [`skills/okstra-inspect.md`](skills/okstra-inspect.md) |
@@ -48,7 +48,7 @@
 `src/lib/skill-catalog.mjs` 기준 공개 스킬은 다음 9개다.
 
 - `okstra-setup`
-- `okstra-brief`
+- `okstra-brief-gen`
 - `okstra-run`
 - `okstra-manager`
 - `okstra-memory`

package/docs/for-ai/skills/{okstra-brief.md → okstra-brief-gen.md}

@@ -1,15 +1,15 @@
-# okstra-brief AI Manual
+# okstra-brief-gen AI Manual
 
 ## 원천
 
-- 스킬 원문: [`skills/okstra-brief/SKILL.md`](../../../skills/okstra-brief/SKILL.md)
+- 스킬 원문: [`skills/okstra-brief-gen/SKILL.md`](../../../skills/okstra-brief-gen/SKILL.md)
 - brief 템플릿: [`templates/reports/brief.template.md`](../../../templates/reports/brief.template.md)
 - brief validator: [`validators/validate-brief.py`](../../../validators/validate-brief.py)
 - lens enum SSOT: [`scripts/okstra_ctl/improvement_lenses.py`](../../../scripts/okstra_ctl/improvement_lenses.py)
 
 ## 목적
 
-`okstra-brief`는 okstra pipeline에 넣을 task brief를 만든다. brief는 pre-discovery 산출물이다. 요구사항을 구현 계획으로 바꾸는 문서가 아니라, reporter가 준 원문과 AI가 확인한 증거/해석을 라벨로 분리해 다음 phase가 질문 없이 출발하게 만드는 handoff 문서다.
+`okstra-brief-gen`는 okstra pipeline에 넣을 task brief를 만든다. brief는 pre-discovery 산출물이다. 요구사항을 구현 계획으로 바꾸는 문서가 아니라, reporter가 준 원문과 AI가 확인한 증거/해석을 라벨로 분리해 다음 phase가 질문 없이 출발하게 만드는 handoff 문서다.
 
 출력 위치:
 

package/docs/for-ai/skills/okstra-inspect.md

@@ -213,7 +213,7 @@ okstra error-zip --out <path>
 - `clusterCount`
 - `projectCount`
 
-마지막에 `/okstra-brief`의 error-feedback variant로 brief를 만든 뒤 okstra repo에서 `error-analysis`를 실행하라고 안내한다.
+마지막에 `/okstra-brief-gen`의 error-feedback variant로 brief를 만든 뒤 okstra repo에서 `error-analysis`를 실행하라고 안내한다.
 
 ## recap
 

package/docs/kr/architecture.md

@@ -147,9 +147,9 @@ okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_ta
 - [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md) — main okstra lead contract. 런타임 리소스(`~/.okstra/prompts/lead/`)이며 agent skill 이 아닙니다.
 - [`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-setup/SKILL.md`, `skills/okstra-brief/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-inspect/SKILL.md`, `skills/okstra-rollup/SKILL.md`, `skills/okstra-schedule/SKILL.md`, `skills/okstra-container-build/SKILL.md` 9종뿐이며, 이것만 agent skill home 으로 복사됩니다 — brief 작성, phase 진행, cross-project manager task 조정, 전역 Memory Book 저장/검색, status/history/report/time/logs/cost/errors/recap read-side, task-group 단위 run 결과 종합(rollup), schedule 보조, 그리고 `okstra-container-build` 는 검증 완료된 task 코드를 docker compose 그룹으로 배포하고 컨테이너별 watcher 로 감시하는 비선형(PHASE_SEQUENCE 외부) 컨테이너 배포/감시 스킬. `okstra-manager` 는 `okstra manager` CLI JSON/launch packet 을 source of truth 로 사용하며, manager-owned plan/assignment/directive/snapshot/event 는 `~/.okstra/managers/<manager-id>/` 아래에 저장합니다. `okstra-rollup` 은 단일 task 집계기(`okstra-inspect` 의 time/errors/recap)를 task-group(또는 프로젝트 전체 catalog)으로 fan-out 하는 read-side 레이어로, deterministic 집계는 `okstra rollup` CLI 가 맡고 report 본문 종합 요약만 스킬(LLM)이 작성합니다. `okstra-inspect` 의 read-side facet 은 `skills/okstra-inspect/SKILL.md` 의 sub-command 표가 정본입니다. `okstra-inspect logs` 는 codex/antigravity wrapper 가 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` 로 남기는 live-log sidecar 의 인벤토리·정리 안내(read-only), `okstra-inspect cost` 는 `okstra context-cost` 결과 요약, `okstra-inspect errors` 는 task 의 okstra-run 에러 로그를 타임스탬프 markdown error-report 로 모아 렌더하고 요약을 출력, `okstra-inspect recap` 은 task 의 run 간 phase 전·후 요약에 더해 `.okstra` 산출물에 대한 자유 Q&A 까지 답합니다.
+- 사용자 호출 가능 스킬은 `skills/okstra-setup/SKILL.md`, `skills/okstra-brief-gen/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-inspect/SKILL.md`, `skills/okstra-rollup/SKILL.md`, `skills/okstra-schedule/SKILL.md`, `skills/okstra-container-build/SKILL.md` 9종뿐이며, 이것만 agent skill home 으로 복사됩니다 — brief 작성, phase 진행, cross-project manager task 조정, 전역 Memory Book 저장/검색, status/history/report/time/logs/cost/errors/recap read-side, task-group 단위 run 결과 종합(rollup), schedule 보조, 그리고 `okstra-container-build` 는 검증 완료된 task 코드를 docker compose 그룹으로 배포하고 컨테이너별 watcher 로 감시하는 비선형(PHASE_SEQUENCE 외부) 컨테이너 배포/감시 스킬. `okstra-manager` 는 `okstra manager` CLI JSON/launch packet 을 source of truth 로 사용하며, manager-owned plan/assignment/directive/snapshot/event 는 `~/.okstra/managers/<manager-id>/` 아래에 저장합니다. `okstra-rollup` 은 단일 task 집계기(`okstra-inspect` 의 time/errors/recap)를 task-group(또는 프로젝트 전체 catalog)으로 fan-out 하는 read-side 레이어로, deterministic 집계는 `okstra rollup` CLI 가 맡고 report 본문 종합 요약만 스킬(LLM)이 작성합니다. `okstra-inspect` 의 read-side facet 은 `skills/okstra-inspect/SKILL.md` 의 sub-command 표가 정본입니다. `okstra-inspect logs` 는 codex/antigravity wrapper 가 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` 로 남기는 live-log sidecar 의 인벤토리·정리 안내(read-only), `okstra-inspect cost` 는 `okstra context-cost` 결과 요약, `okstra-inspect errors` 는 task 의 okstra-run 에러 로그를 타임스탬프 markdown error-report 로 모아 렌더하고 요약을 출력, `okstra-inspect recap` 은 task 의 run 간 phase 전·후 요약에 더해 `.okstra` 산출물에 대한 자유 Q&A 까지 답합니다.
 - 내부 운영 계약 — `context-loader` / `team-contract` / `convergence` / `report-writer` 와 lead 계약 — 은 `prompts/lead/*.md` 로, 구현/검증 워커의 언어별 coding preflight 는 `prompts/coding-preflight/*` (overview 라우터 + clean-code + languages/frameworks/architectures 3단계 선택) 로 이동했습니다. 모두 `~/.okstra/prompts/` 에 설치되는 런타임 리소스이며 skill discovery 대상이 아닙니다. generated launch prompt 가 lead 에게 절대 경로를 제공하고, 재설치 시 과거 `okstra-context-loader` / `okstra-team-contract` / `okstra-convergence` / `okstra-report-writer` / `okstra-coding-preflight` / `okstra` skill 디렉터리는 exact-name prune 됩니다.
-- 플러그인 매니페스트: [`../../.claude-plugin/plugin.json`](../../.claude-plugin/plugin.json) — `npx skills@latest add Devonshin/okstra` 보조 채널이 참조. 일반 셋업에는 `npx okstra@latest install` 을 사용한다. 플러그인 매니페스트는 사용자 진입점 9개(`okstra-setup`, `okstra-brief`, `okstra-run`, `okstra-manager`, `okstra-memory`, `okstra-inspect`, `okstra-rollup`, `okstra-schedule`, `okstra-container-build`)만 노출한다.
+- 플러그인 매니페스트: [`../../.claude-plugin/plugin.json`](../../.claude-plugin/plugin.json) — `npx skills@latest add Devonshin/okstra` 보조 채널이 참조. 일반 셋업에는 `npx okstra@latest install` 을 사용한다. 플러그인 매니페스트는 사용자 진입점 9개(`okstra-setup`, `okstra-brief-gen`, `okstra-run`, `okstra-manager`, `okstra-memory`, `okstra-inspect`, `okstra-rollup`, `okstra-schedule`, `okstra-container-build`)만 노출한다.
 - 설치 위치: `~/.claude/skills/<name>/SKILL.md` 또는 `~/.agents/skills/<name>/SKILL.md`.
 - 릴리스 절차: [`../../RELEASING.md`](../../RELEASING.md) — npm publish 흐름과 release-please / manual fallback.
 
@@ -235,7 +235,7 @@ per-process 환경 변수에 task 정체성·경로·workflow 상태를 보관
 - standard workflow의 기본 worker role은 `Claude worker`, `Codex worker`, `Report writer worker`이며, `Antigravity worker`는 `--workers` 또는 프로필에서 명시할 때만 포함되는 옵션입니다.
 - worker 역할 분담과 최종 판단은 Claude가 task bundle을 읽고 수행합니다.
 - 사용자 홈에 설치된 okstra Claude assets(`~/.claude/skills`, `~/.claude/agents`) 는 `Agent(name: ...)` 로 워커를 dispatch 하도록 Claude 를 유도합니다 — 워커는 세션의 implicit team 에 자동 합류합니다.
-- **팀 lifecycle (Claude Code v2.1.178+)**: v2.1.178 이 `TeamCreate` / `TeamDelete` 도구와 `Agent(...)` 의 `team_name` 파라미터를 제거했습니다. `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`(`okstra install` 이 `settings.json` 에 시드) 이면 세션마다 implicit team 1개가 시작 시점에 자동 생성됩니다. lead 는 Phase 3 에서 팀을 만드는 도구를 호출하지 않고, `teamName` audit 라벨과 `teamCreate: { attempted: false, status: "implicit", splitPane: <$TMUX 유무> }` 만 기록한 뒤 워커를 `Agent(name: "<role>-worker", run_in_background: true)`(team_name 없음)로 dispatch 합니다. split-pane teammate 는 `$TMUX` 가 설정돼 있고 `teammateMode: auto` 일 때 나타나며, tmux 밖이면 in-process 로 돕니다(둘 다 정상). run 종료 시 Phase 7 토큰 집계 이후 잔여 tmux pane 정리를 확인하고, split-pane run 에서만 worker teammate 를 정리할지 확인합니다. 승인 시 `okstra-team-reconcile.sh` 로 dead-pane stale-active 멤버를 inactive 로 정리하고 각 완료 teammate 에 `SendMessage` shutdown_request 를 보냅니다 — implicit team 자체를 지우는 도구는 없으며, 팀은 세션 종료와 함께 사라집니다. 사용자가 유지하면 teammate 는 FleetView roster 에 남고, lead 는 Teams/FleetView 에서 제거하라고 안내합니다 (`prompts/profiles/_common-contract.md` 의 *Run-end teammate teardown*). Phase 7 토큰 집계는 `teamCreate.status` 가 `implicit`/`skipped`/`error` 일 때 `agentName` 기반으로 워커 세션을 찾습니다(implicit team 은 jsonl 을 `session-<leadSid>` 로 태깅하므로 okstra 의 `teamName` 라벨 needle 만으로는 lead 만 잡힘).
+- **팀 lifecycle (Claude Code v2.1.178+)**: v2.1.178 이 `TeamCreate` / `TeamDelete` 도구와 `Agent(...)` 의 `team_name` 파라미터를 제거했습니다. `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`(`okstra install` 이 `settings.json` 에 시드) 이면 세션마다 implicit team 1개가 시작 시점에 자동 생성됩니다. lead 는 Phase 3 에서 팀을 만드는 도구를 호출하지 않고, `teamName` audit 라벨과 `teamCreate: { attempted: false, status: "implicit", splitPane: <$TMUX 유무> }` 만 기록한 뒤 워커를 `Agent(name: "<role>-worker", run_in_background: true)`(team_name 없음)로 dispatch 합니다. split-pane teammate 는 `$TMUX` 가 설정돼 있고 `teammateMode: auto` 일 때 나타나며, tmux 밖이면 in-process 로 돕니다(둘 다 정상). run 종료 시 Phase 7 토큰 집계 이후 잔여 tmux pane 정리를 확인하고, split-pane run 에서만 worker teammate 를 정리할지 확인합니다. 승인 시 `okstra-team-reconcile.sh` 로 dead-pane stale-active 멤버를 inactive 로 정리하고 각 완료 teammate 에 `SendMessage` shutdown_request 를 보냅니다 — implicit team 자체를 지우는 도구는 없으며, 팀은 세션 종료와 함께 사라집니다. 사용자가 유지하면 teammate 는 FleetView roster 에 남고, lead 는 Teams/FleetView 에서 제거하라고 안내합니다 (`prompts/profiles/_common-contract.md` 의 *Run-end teammate teardown*). Phase 7 토큰 집계는 `teamCreate.status` 가 `implicit`/`skipped`/`error` 일 때 top-level `agentName` 또는 nested `subagents/agent-a<name>-<hash>.jsonl` 파일명 기반으로 워커 세션을 찾습니다.
 
 ## Claude prompt contract
 
@@ -316,7 +316,7 @@ okstra 의 project artifact root 는 `<PROJECT_ROOT>/.okstra/` 하나뿐입니
 okstra 는 자기 subtree 안에 자체 institutional memory 를 유지합니다.
 
 - `<PROJECT_ROOT>/.okstra/glossary.md` — run 을 가로지르며 누적되는 okstra 용어집.
-- `<PROJECT_ROOT>/.okstra/decisions/<NNNN>-<slug>.md` — okstra 의 결정 기록. 평가 시점은 `implementation-planning` phase 이며 `okstra-brief` 단계에서는 후보만 표시합니다.
+- `<PROJECT_ROOT>/.okstra/decisions/<NNNN>-<slug>.md` — okstra 의 결정 기록. 평가 시점은 `implementation-planning` phase 이며 `okstra-brief-gen` 단계에서는 후보만 표시합니다.
 
 okstra phase 는 PRD / issue file 을 직접 쓰지 않습니다. 동등한 결정 산출물은 `requirements-discovery` 와 `implementation-planning` 이 `.okstra/` 내부에 만듭니다.
 
@@ -369,7 +369,7 @@ release-handoff 까지 완료된 task 의 산출물에서 버그가 발견되면
 - **진입**: okstra-run wizard 가 완료 task + entry phase 재진입을 감지해 `fix_cycle_confirm` 단계로 확인합니다. CLI 는 `--fix-cycle <yes|no>` (미지정 시 기록하지 않음). `--fix-cycle yes` 는 두 가드를 모두 통과해야 cycle 을 엽니다 — task-type 이 entry phase 이고, manifest 의 `workflow.lastCompletedPhase` 가 `release-handoff` 여야 하며, 위반 시 `PrepareError`. open cycle 은 task 당 동시 1개입니다.
 - **부착**: cycle 이 open 인 동안 같은 task 의 모든 run 이 (이후 `--fix-cycle` 플래그 없이도) `run` 행으로 부착되고, run-manifest / timeline 항목에 `fixCycleId` 가 찍힙니다.
 - **종료**: open cycle 에 release-handoff run 이 부착된 뒤 manifest 의 `workflow.lastCompletedPhase` 가 `release-handoff` 가 되면, 다음 prepare 가 `closed` 행을 lazy-append 합니다.
-- **소비처 (전부 파생 뷰)**: ① 후속 run 의 analysis-packet `## Fix History` 섹션 ② okstra-brief 의 Task Continuity Notes 인용 ③ final-report `## 5.10 Fix History` (run-manifest 에 `fixCycleId` 가 있으면 data.json `fixCycle` 블록을 validator `_validate_fix_cycle` 가 강제) ④ task-manifest `fixCycles` 요약 + task-index / task-catalog 한 줄. 네 소비처 모두 `fix_cycles.summarize()` / `packet_summary()` 파생 뷰만 읽습니다.
+- **소비처 (전부 파생 뷰)**: ① 후속 run 의 analysis-packet `## Fix History` 섹션 ② okstra-brief-gen 의 Task Continuity Notes 인용 ③ final-report `## 5.10 Fix History` (run-manifest 에 `fixCycleId` 가 있으면 data.json `fixCycle` 블록을 validator `_validate_fix_cycle` 가 강제) ④ task-manifest `fixCycles` 요약 + task-index / task-catalog 한 줄. 네 소비처 모두 `fix_cycles.summarize()` / `packet_summary()` 파생 뷰만 읽습니다.
 
 ### release-handoff stage-group 모드
 
@@ -397,14 +397,14 @@ stage-group 의 상호작용 순서: **G1 base 선택 → G2 stage 확인(선택
 [requirements-discovery | implementation-planning | error-analysis] (선택된 후보별로 새 task-id 로)
 ````
 
-`PHASE_SEQUENCE` 의 정식 멤버에 들어가지 않는 sidetrack entry-point. 단방향 라이프사이클을 깨지 않으면서 코드베이스 발견 시나리오를 흡수한다. lens 화이트리스트와 candidate-cap 은 `scripts/okstra_ctl/improvement_lenses.py` SSOT 1개에서 통일된다. final-report 의 `## 5.9 Improvement Candidates` 표 (10 column) 는 `validators/validate_improvement_report.py` 의 11항목 contract 가 강제한다. 양방향 grilling 두 지점 (`okstra-brief` Step 4 강화 budget 8 + lead 의 Phase 1.5 reflect-back budget 12) 으로 사용자와 AI 의 이해도를 일치시킨다.
+`PHASE_SEQUENCE` 의 정식 멤버에 들어가지 않는 sidetrack entry-point. 단방향 라이프사이클을 깨지 않으면서 코드베이스 발견 시나리오를 흡수한다. lens 화이트리스트와 candidate-cap 은 `scripts/okstra_ctl/improvement_lenses.py` SSOT 1개에서 통일된다. final-report 의 `## 5.9 Improvement Candidates` 표 (10 column) 는 `validators/validate_improvement_report.py` 의 11항목 contract 가 강제한다. 양방향 grilling 두 지점 (`okstra-brief-gen` Step 4 강화 budget 8 + lead 의 Phase 1.5 reflect-back budget 12) 으로 사용자와 AI 의 이해도를 일치시킨다.
 
 ### requirements-discovery fan-out
 
 혼합/다항목 요청은 requirements-discovery 가 도메인(work-category 5-enum)별 packet 으로
 분해해 `runs/requirements-discovery/fan-out/unit-*.md` 에 발행한다. 각 packet 은
 `okstra-run --task-brief <경로>` 로 새 task-key 가 된다. 순서는 `index.md` 의 depends-on
-위상정렬이 담고, task 화 이후의 통합 일정은 okstra-schedule 이 맡는다. okstra-brief 는
+위상정렬이 담고, task 화 이후의 통합 일정은 okstra-schedule 이 맡는다. okstra-brief-gen 는
 이 경로에 개입하지 않는다. 검증: `validators/validate_fanout.py`(validate-run 훅).
 
 ### confirm 단계의 worktree 미리보기
@@ -433,7 +433,7 @@ okstra-run wizard 는 별도 분기 확인 단계를 두지 않고, 최종 `conf
 
 brief 의 **입력 시점은 entry phase 전용**입니다 — 사용자가 brief 경로를 직접 대는 것은 `requirements-discovery` / `error-analysis` / `improvement-discovery` 뿐이고, downstream phase(implementation-planning / implementation / final-verification)는 task manifest 의 `taskBriefPath` 를 자동 carry-in 합니다 (okstra-run wizard 가 묻지 않음; 미등록 시 entry 전환을 추천하는 fallback picker). `release-handoff` 는 brief 자체가 없으며 prepare 가 검증 보고서 인용 input 문서를 생성합니다.
 
-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 는 **translation layer** 입니다 — 외부 입력 (이슈 트래커 ticket, 요구사항 문서, 사용자 메시지) 을 okstra-readable 형식으로 옮기되, 원문은 verbatim 으로 보존하고 okstra 가 추가한 부분은 labelled augmentation 으로 명확히 구분합니다. `okstra-brief-gen` 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에는 보통 아래를 포함합니다.
 
@@ -446,10 +446,10 @@ brief에는 보통 아래를 포함합니다.
 - worker에게 줄 질문
 - 기대 출력
 - 이전 run 또는 연관 task 정보
-- (선택) glossary 추가 후보 — okstra-brief Step 4.5 가 `<PROJECT_ROOT>/.okstra/glossary.md` 에 직접 기록
+- (선택) glossary 추가 후보 — okstra-brief-gen Step 4.5 가 `<PROJECT_ROOT>/.okstra/glossary.md` 에 직접 기록
 - (선택) decisions 후보 — `implementation-planning` phase 에서 평가 후 `.okstra/decisions/<NNNN>-<slug>.md` 로 승격
 
-okstra-brief 의 Step 6.5 는 **reporter batch confirmation** 입니다. brief 가 외부 입력을 옮기는 도중 의미 변화가 발생했는지를 사용자에게 일괄 확인받고 그 결과를 `Reporter Confirmations` 섹션에 기록합니다. 모든 분석 profile 은 이 섹션의 존재를 phase 분석 진입의 precondition 으로 강제합니다 (validator: `validators/validate-brief.py`).
+okstra-brief-gen 의 Step 6.5 는 **reporter batch confirmation** 입니다. brief 가 외부 입력을 옮기는 도중 의미 변화가 발생했는지를 사용자에게 일괄 확인받고 그 결과를 `Reporter Confirmations` 섹션에 기록합니다. 모든 분석 profile 은 이 섹션의 존재를 phase 분석 진입의 precondition 으로 강제합니다 (validator: `validators/validate-brief.py`).
 
 기본 템플릿:
 
@@ -698,7 +698,7 @@ Phase 7 step 1.5 가 final-report MD 한 본을 입력으로 self-contained HTML
 
 - Helper CLI: `scripts/okstra-token-usage.py`
 - 수집 소스:
-  - Claude lead/workers: `~/.claude/projects/<cwd-as-dashes>/<sessionId>.jsonl`의 per-message `message.usage`
+  - Claude lead/workers: `~/.claude/projects/<cwd-as-dashes>/<sessionId>.jsonl` 또는 `~/.claude/projects/<cwd-as-dashes>/<lead-session>/subagents/agent-a<worker-name>-<hash>.jsonl` 의 per-message `message.usage`. nested subagent 파일은 파일명에서 worker name 을 복원하고, 현재 run 의 `team-state.lead.sessionId` 디렉터리 아래만 집계합니다.
   - Codex CLI: `~/.agent/sessions/Y/M/D/rollout-*.jsonl`의 마지막 `total_token_usage.total_tokens`
   - Antigravity CLI: `~/.antigravity/tmp/*/chats/session-*.json`의 per-message `tokens.total`
 - billable-equivalent token math와 USD cost estimation을 함께 기록합니다. Anthropic billing ratio(`cache_creation_5m=1.25x`, `cache_creation_1h=2.0x`, `cache_read=0.1x`, `output=5x`)를 반영합니다. transcript 의 `usage.cache_creation.ephemeral_5m_input_tokens` / `ephemeral_1h_input_tokens` 분해가 있으면 분리 집계합니다.

package/docs/kr/cli.md

@@ -127,7 +127,7 @@ interactive terminal에서 실행하면 다음 규칙이 추가로 적용됩니
 - Verdict Token: `candidates-ready` / `no-candidates` / `blocked`.
 - 라우팅: 자동 spin-off 없음. 사용자가 후보를 골라 새 task-id 로 `requirements-discovery` / `implementation-planning` / `error-analysis` 진입.
 - 워커: claude + codex + antigravity + report-writer 모두 필수.
-- 양방향 grilling 두 지점: `okstra-brief` Step 4 강화 (budget 8) + lead 의 Phase 1.5 reflect-back (budget 12).
+- 양방향 grilling 두 지점: `okstra-brief-gen` Step 4 강화 (budget 8) + lead 의 Phase 1.5 reflect-back (budget 12).
 - Validator: `validators/validate_improvement_report.py` 가 `improvement-discovery` final-report 의 11항목 contract 를 강제.
 - `improvement-discovery` run 은 `PHASE_SEQUENCE` 에 포함되지 않으므로 `--task-key` 단축 경로의 `nextRecommendedPhase` 자동 채움 대상이 아닙니다.
 

package/docs/kr/follow-ups/2026-07-10-final-report-option-3.md

@@ -0,0 +1,51 @@
+# Final Report 가독성 후속: 3안 재검토
+
+상태: 보류
+작성일: 2026-07-10
+
+## 배경
+
+이번 1차 가독성 개선은 범위를 좁게 유지했다.
+
+- `readerSummary`로 Markdown final-report 앞부분에 사람이 먼저 읽을 요약 진입점을 둔다.
+- HTML report view에 Reader Summary dashboard와 reader mode를 추가한다.
+- 기존 `final-report` data는 `verdictCard` fallback으로 계속 호환한다.
+
+이 문서는 더 큰 3안을 현재 변경에 섞지 않고, 나중에 별도 판단할 재검토 후보로 남긴다.
+
+## 보류한 3안
+
+`final-report` 산출물 자체를 목적별로 분리할지 재검토한다.
+
+현재 구조는 하나의 canonical Markdown 문서와 그 문서에서 생성되는 view를 유지한다. 3안은 요약 블록이나 HTML 필터링만으로 충분한지, 아니면 report를 목적별 artifact로 나누는 편이 더 나은지 비교하는 작업이다.
+
+비교 후보:
+
+- 짧은 human handoff report와 별도 audit appendix.
+- 같은 `data.json`에서 생성되는 `summary` view와 `audit` view.
+- 사람이 먼저 행동하는 섹션만 남기는 phase별 slim report template.
+- reporter handoff, implementer handoff, verifier audit, release handoff 같은 role별 view set.
+
+## 재검토 트리거
+
+아래 중 하나가 반복되면 이 문서를 다시 연다.
+
+- `readerSummary`와 HTML reader mode 배포 후에도 사용자가 `final-report`를 읽기 어렵다고 말한다.
+- 리뷰어가 항상 같은 audit 섹션을 건너뛰거나 더 작은 handoff artifact를 요구한다.
+- `final-report` 생성에서 같은 evidence가 여러 섹션에 반복된다.
+- 향후 schema migration에서 report artifact 계약을 어차피 건드려야 한다.
+
+## 결정할 질문
+
+- Markdown이 계속 primary human artifact인가, 아니면 `data.json`만 canonical source로 두고 view를 생성할 것인가?
+- follow-up task에 기본 첨부할 artifact는 무엇인가?
+- 어떤 섹션이 human-action material이고, 어떤 섹션이 audit-only material인가?
+- 분리를 validator가 강제해야 하는가, renderer convention으로 둘 것인가?
+- 분리가 기존 `render-views`, follow-up spawning, approval sidecar에 어떤 영향을 주는가?
+
+## 참조
+
+- 현재 schema: `schemas/final-report-v1.0.schema.json`
+- 현재 Markdown template: `templates/reports/final-report.template.md`
+- 현재 HTML renderer: `scripts/okstra_ctl/report_views.py`
+- 현재 report UI assets: `templates/reports/report.css`, `templates/reports/report.js`

package/docs/project-structure-overview.md

@@ -310,7 +310,7 @@ Token/cost accounting:
 
 | Skill | User-invocable | Role |
 |---|---:|---|
-| `okstra-brief` | yes | Produce task brief from ticket/doc/link/conversation |
+| `okstra-brief-gen` | 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), `cost` (task bundle context/read cost) |
@@ -454,7 +454,7 @@ Project-local `<PROJECT_ROOT>/.claude/settings.local.json` is provisioned as a s
 
 ### 7.2 Brief creation
 
-`/okstra-brief` turns source material into a validated task brief. It preserves source material verbatim, labels okstra augmentation, and records reporter confirmations.
+`/okstra-brief-gen` turns source material into a validated task brief. It preserves source material verbatim, labels okstra augmentation, and records reporter confirmations.
 
 ### 7.3 Task run
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.113.0",
+  "version": "0.115.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.113.0",
-  "builtAt": "2026-07-05T15:04:19.955Z",
+  "package": "0.115.0",
+  "builtAt": "2026-07-09T15:25:58.950Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -88,6 +88,7 @@ Rules (the schema enforces most of these — they are listed here so you know *w
 - `header.reportAuthor` is `"Report writer worker"`; `header.reportOwner` is `"Claude lead"`. Set author to `"Claude lead"` only for `release-handoff` runs (single-lead by design) or a recorded report-writer dispatch failure fallback.
 - **Source items (worker:item) preservation.** Every `consensus[].sourceItems`, `differences[].workersPosition[].itemId`, and `evidence.primary[].sourceItems` entry MUST carry the worker:item-id pair (e.g. `claude:F-001`, `codex:1.1`, `antigravity:F-3`, or `lead:mcp-1` for lead-only evidence). The schema enforces this via the `SourceItem` regex; bare worker-name lists no longer parse.
 - **Verdict Card consistency.** `verdictCard.verdictToken` / `.direction` / `.nextStep` MUST byte-match `finalVerdict.verdictToken` / `.direction` / `.nextStep` and `recommendedNextSteps[0].text`. The renderer pulls both from the same data structure — duplicating values across `verdictCard` and `finalVerdict` is intentional so the validator can diff them.
+- **Reader Summary.** Populate `readerSummary` when the schema excerpt exposes it. It is the human-first entrypoint for both Markdown and HTML: one sentence for the decision, one for the human action required, one for blockers, one for audit sections safe to skip on first read, and one runnable recommended command. Do not duplicate raw evidence tables here.
 - **§7 phase-continuation row (mandatory for non-terminal task-types).** When `header.taskType` is one of `requirements-discovery` / `implementation-planning` / `error-analysis` / `implementation` / `final-verification`, `followUpTasks` MUST contain at least one row whose `origin` is `phase-continuation`, `suggestedTaskType` equals the next phase (byte-identical to `finalVerdict.nextStep`'s referenced phase), `newTaskId` reuses the current task-id, `autoSpawn` is `"no"`, and `priority` is `"P0"`. For `release-handoff` runs, omit the phase-continuation row. Schema `allOf` clause enforces this via `contains`.
 - **No deprecated sections.** The schema has no `4.5.8 User Approval Request` body field, no `4.5.9 Open Questions`, no `5.1 추가 자료 요청`, no `5.2 사용자 확인 질문` — clarifications go under the unified `clarificationItems[]` array.
 - **Optional Section 0.** Include `clarificationCarryIn` ONLY when the lead's prompt provides a non-empty carry-in path. Omit the key entirely otherwise (do NOT set it to `null` or an empty object).

package/runtime/prompts/lead/context-loader.md

@@ -25,7 +25,7 @@
 4. If multiple candidates are found based on `task-id` alone, the situation is ambiguous, so `task-group` or the full `taskKey` is required.
 5. If the user has not provided an explicit task key/path, first read `.okstra/discovery/latest-task.json` using the current-task convenience pointer.
 6. If the latest-task pointer is missing or corrupted but the task catalog exists, list candidates from the catalog. Do not use the legacy `CLAUDE.md`, project guide, or task scan fallback.
-7. If **neither** `latest-task.json` **nor** `task-catalog.json` exists, ABORT Phase 1 with `OKSTRA_CONTEXT_NOT_INITIALIZED`. Suggest the user run `/okstra-setup` and `/okstra-brief` to bootstrap the project. Do NOT crawl `.okstra/tasks/` directly — discovery pointers are the only supported entry path.
+7. If **neither** `latest-task.json` **nor** `task-catalog.json` exists, ABORT Phase 1 with `OKSTRA_CONTEXT_NOT_INITIALIZED`. Suggest the user run `/okstra-setup` and `/okstra-brief-gen` to bootstrap the project. Do NOT crawl `.okstra/tasks/` directly — discovery pointers are the only supported entry path.
 
 ## Step 2: Open and Parse task-manifest.json
 
@@ -128,7 +128,7 @@ Read source files lazily:
 
 After reading `task-brief.md`, extract the frontmatter `reporter-confirmations` field (`complete | partial | pending | skipped`) and apply the shared handling matrix in `prompts/profiles/_common-contract.md` "Brief handoff contract" → "Reporter confirmation precondition" — that block is the single authority on per-value semantics; do not re-derive them here.
 
-Loader-level flow control only: on `pending` (or field missing), emit `REPORTER_CONFIRMATION_PENDING` and STOP — do not invoke `team-contract` or any analyser; the operator must rerun `okstra-brief` Step 6.5 before Phase 2 can start. Every other value proceeds to Step 5 (with the matrix's flags carried forward for the phase profile).
+Loader-level flow control only: on `pending` (or field missing), emit `REPORTER_CONFIRMATION_PENDING` and STOP — do not invoke `team-contract` or any analyser; the operator must rerun `okstra-brief-gen` Step 6.5 before Phase 2 can start. Every other value proceeds to Step 5 (with the matrix's flags carried forward for the phase profile).
 
 ## Step 5: Read Run Manifest and Team State
 

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -366,7 +366,7 @@ jq -s 'group_by(.errorType) | map({type: .[0].errorType, count: length})' <runDi
 
 The errors log is informational. Its presence/absence does not affect the final verdict. Do not block report writing on it.
 
-After persistence, reply briefly in the resolved Report Language with: completion status, final report path, team-state path, validator result, resume command path, any remaining blocker.
+After persistence, reply briefly in the resolved Report Language with: completion status, final report path, team-state path, validator result, resume command path, any remaining blocker. **Lead this reply with the run's task identity** — state `<task-group>/<task-id>` (or the full `taskKey`) first, so the reader knows which task the reply is about. **Every run-artifact path in this reply MUST be task-qualified** — report the final report as `.okstra/tasks/<task-group>/<task-id>/runs/<task-type>/reports/final-report-<task-type>-<seq>.md` (the full path rooted at the task bundle), NOT the bare `runs/<task-type>/reports/...` form. The bare `runs/...` prefix is byte-for-byte identical across every task-group / task-id of the same task-type, so it cannot tell one task's report from another's — always emit the `.okstra/tasks/<task-group>/<task-id>/` prefix. The same task-qualified rule applies to the team-state path, resume command path, and any other run-artifact path this reply cites.
 
 ## Run-scoped pane & teammate lifecycle
 

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

@@ -31,13 +31,13 @@ profile document.
 - Anti-escalation rule (shared):
   - treating "다음 단계 진행해" or equivalent user phrases as authorisation to start a *different* lifecycle phase is forbidden. The next phase begins only in a separate okstra run launched with the new `--task-type`. Per-profile documents may further restrict this within their own scope.
 - Run-scoped pane & teammate lifecycle (shared — run-start pane recording, per-batch cleanup, wrap-up pane disposition, run-end teammate teardown): these are lead-only operating duties and live in `prompts/lead/okstra-lead-contract.md` "Run-scoped pane & teammate lifecycle". Profiles do not restate them.
-- Brief handoff contract (shared — applies whenever the run consumes a task brief produced by `okstra-brief`):
+- Brief handoff contract (shared — applies whenever the run consumes a task brief produced by `okstra-brief-gen`):
   - 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:
+  - **Reporter confirmation precondition (BLOCKING)**: the brief's frontmatter carries `reporter-confirmations: <complete | partial | pending | skipped>` set by `okstra-brief-gen` 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 `## 1. Clarification Items` as `Kind=decision`. Use `Blocks=approval` in `implementation-planning`, where the row gates the `approved:` frontmatter flip; 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 `## 1. 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.
+    - `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 `## 1. 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-gen` 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.
   - `Related Task Graph` is the structured task-topology handoff. If the section is present and not `_(none)_`, read it before classification, diagnosis, candidate discovery, fan-out, or next-step routing. Preserve the edge direction exactly as written: `From` → `To` is load-bearing for `depends-on`, `blocks`, parent/child, follow-up, and split relations.

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

@@ -94,7 +94,7 @@
     - **Parallel-feasibility check (mandatory for every multi-project plan):** disjoint files (S9 below) is necessary but NOT sufficient for parallelism — a cross-project API/contract/schema/deploy-order dependency forces sequencing even when no file overlaps. For each pair of projects, explicitly determine and record (in the `Cross-project parallelism:` line) whether they are independent (run in parallel) or sequenced (and the exact dependency that forces the order).
   - **Parallel-safety invariant (BLOCKING):** any two stages that are both `depends-on (none)` MUST predict disjoint file sets in their `Stage Exit Contract`. Two parallel `implementation` runs would otherwise edit the same file concurrently. Work touching a shared file must either go in one stage or be ordered with `depends-on`. Enforced by `validators/validate-implementation-plan-stages.py` check S9.
   - **Cross-project dependency rows (`crossProjectDependencies` 배열 — 옛 `## Cross-Repo Carry` 부록을 대체):** 타 프로젝트(다른 repo / 다른 top-level 독립 배포 모듈 / published 패키지)에 대한 의존은 freeform `## Cross-Repo Carry` 부록이 아니라 **구조 필드 `crossProjectDependencies` 의 `XP-NNN` 행**으로 기록한다. 한 프로젝트 의존마다 한 XP 행을 두고, 양방향 중 해당하는 `direction` 을 채운다(렌더는 `### Cross-Project Dependencies` §5.4; 단일 프로젝트 계획은 빈 배열). 행 필드는 옛 세 subsection 을 다음으로 대체한다 — `requiredWork`(상대가 만들어야 할 구체 작업) / `verificationSignal`(이 run 이 관측할 신호) / `linkedWork`(신호 충족 전 막히는 이 계획의 stage·step) / `howToStart`(상대 repo 에서의 정확한 handoff).
-    - `direction: upstream-precondition` — 이 run 이 상대의 **선행 작업을 기다림(선행 필수)**: `requiredWork` = 상대가 먼저 구현해야 할 구체 작업, `verificationSignal` = 이 run 이 진행 전 관측해야 할 신호(PR 머지 / 엔드포인트 live / 버전 publish), `linkedWork` = 신호 충족 전 막히는 이 계획의 stage·step, `howToStart` = 상대 repo 에서 `okstra-brief`(**이 보고서의 절대경로를 Source Material 로 인용** — 유일하게 허용된 cross-`<PROJECT_ROOT>` read) → `okstra-run`.
+    - `direction: upstream-precondition` — 이 run 이 상대의 **선행 작업을 기다림(선행 필수)**: `requiredWork` = 상대가 먼저 구현해야 할 구체 작업, `verificationSignal` = 이 run 이 진행 전 관측해야 할 신호(PR 머지 / 엔드포인트 live / 버전 publish), `linkedWork` = 신호 충족 전 막히는 이 계획의 stage·step, `howToStart` = 상대 repo 에서 `okstra-brief-gen`(**이 보고서의 절대경로를 Source Material 로 인용** — 유일하게 허용된 cross-`<PROJECT_ROOT>` read) → `okstra-run`.
     - `direction: downstream-carry` — 이 run 이 상대가 쓸 것을 **만들어 줌(기존 carry)**: `requiredWork` = 상대가 후속 구현할 self-contained B-portion(상대 관점의 신규 `R-NNN`·제안 stage·영향 파일), `verificationSignal` = 상대가 진행 전 확인할(이 run 이 인도한) 신호, `linkedWork` = 그 신호를 인도하는 이 계획의 stage·step, `howToStart` 는 upstream 과 동일. 이 run 의 이미 `done` 인 stage 를 상대 stage 인 양 넘기지 않는다 — 상대가 아직 만들어야 할 portion 만 담는다.
     - **cross-repo 의존은 `depends-on` 으로 표현 불가:** 그 게이트는 한 repo git graph 내부 커밋만 해소하므로(`scripts/okstra_ctl/run.py` `_resolve_stage_base_commit`) 다른 repo 의 커밋을 가리킬 수 없다. cross-repo 작업은 stage 가 아니라 별도 okstra run + XP 행으로 분리한다(Different-repos 규칙). 상대 run 은 구조적으로 독립이라 이 run 의 완료 stage 를 `done` 으로 자동 인식하지 않으며(인식해서도 안 됨 — 이 repo 의 작업), XP 행은 상대 planning 을 seed 하는 narrative 입력일 뿐이다. 이 run 은 상대 repo 트리·그 `.okstra/` 에 쓰지 않는다(이 보고서의 XP 행만 emit). 옛 "Recognition caveat" 문구는 렌더 노트(i18n `crossProjectRecognitionNote`)로 이전돼 `### Cross-Project Dependencies` 섹션에 자동 출력된다.
   - **Stage exit contract is the carry surface:** keep it as narrow as possible. Wider surface = more downstream coupling.

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

@@ -49,7 +49,7 @@
   - 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>/.okstra/glossary.md` should be updated (proposal only — actual writes happen via `okstra-brief` Step 4.5 on a subsequent run)
+  - 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>/.okstra/glossary.md` should be updated (proposal only — actual writes happen via `okstra-brief-gen` 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 `## 1. 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.
@@ -62,6 +62,6 @@
 - 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
-  - **writes outside `<PROJECT_ROOT>/.okstra/`** — this phase only uses okstra's artifact root. Glossary additions land in `<PROJECT_ROOT>/.okstra/glossary.md` (via `okstra-brief` Step 4.5); decision drafts land in `<PROJECT_ROOT>/.okstra/decisions/` (via `implementation-planning`).
+  - **writes outside `<PROJECT_ROOT>/.okstra/`** — this phase only uses okstra's artifact root. Glossary additions land in `<PROJECT_ROOT>/.okstra/glossary.md` (via `okstra-brief-gen` Step 4.5); decision drafts land in `<PROJECT_ROOT>/.okstra/decisions/` (via `implementation-planning`).
   - 작업 단위 분해(fan-out)는 이 phase 의 in-scope 다 — 단, 각 단위의 *해법 설계*·소스
     편집·plan 작성은 여전히 non-goal 이며 다운스트림 phase 가 담당한다

package/runtime/python/okstra_ctl/fix_cycles.py

@@ -3,7 +3,7 @@
 완료(release-handoff)된 task 에 재진입하는 버그 핫픽스 run 묶음(fix cycle)의
 SSOT. consumers.jsonl 과 같은 idiom — append-only + dir flock + last-wins 읽기.
 이 모듈이 유일한 reader/writer 이며, 소비처(analysis-packet / manifest /
-final-report / okstra-brief)는 모두 summarize()/packet_summary() 파생 뷰를 쓴다.
+final-report / okstra-brief-gen)는 모두 summarize()/packet_summary() 파생 뷰를 쓴다.
 
 행 3종 (event 필드로 구분):
     {"event":"opened","cycle":"fc-01","target_report":...,"symptom":...,"opened_at":...}

package/runtime/python/okstra_ctl/implementation_stage.py

@@ -1,8 +1,8 @@
 """Implementation stage run orchestration.
 
-This module owns the lifecycle for one ``implementation`` stage run: recover
-consumer state, select an available Stage Map entry, provision the isolated
-stage worktree, and publish the selected stage into run context.
+This module owns the Stage Run Claim for one ``implementation`` stage run:
+recover consumer state, select an available Stage Map entry, provision the
+isolated stage worktree, and record the started event.
 """
 from __future__ import annotations
 
@@ -18,12 +18,12 @@ from .stage_reconcile import auto_reconcile_best_effort
 
 
 class ImplementationStageError(Exception):
-    """Implementation stage selection or provisioning failed."""
+    """Implementation stage claim or provisioning failed."""
 
 
 @dataclass
-class StageSelection:
-    """Resolved implementation stage and its isolated worktree coordinates."""
+class StageRunClaim:
+    """Claim over one Stage Map stage and its isolated worktree coordinates."""
 
     stage: int
     worktree_path: str
@@ -50,22 +50,20 @@ def _as_implementation_stage_error(exc: Exception) -> ImplementationStageError:
     return ImplementationStageError(str(exc))
 
 
-def select_and_provision_implementation_stage(
+def claim_implementation_stage_run(
     inp: Any,
     ctx_stage_map: list[dict[str, Any]],
     task_group_segment: str,
     task_id_segment: str,
     task_key: str,
     executor_worktree_status: str,
-) -> StageSelection:
-    """Select a ready implementation stage and provision its stage worktree.
+) -> StageRunClaim:
+    """Claim a ready implementation stage for one run.
 
-    The returned selection is path-independent with respect to run artifacts:
+    The returned claim is path-independent with respect to run artifacts:
     callers can compute stage-specific run paths after this function resolves
     the selected stage.
     """
-    del task_key  # The registry uses the split identity fields.
-
     from .consumers import backfill_done_from_carry
     from . import worktree as _worktree
     from . import worktree_registry as _reg
@@ -95,7 +93,7 @@ def select_and_provision_implementation_stage(
 
     if executor_worktree_status.startswith("skipped"):
         head = _git_out(inp.project_root, "rev-parse", "HEAD")
-        return StageSelection(
+        claim = StageRunClaim(
             stage=selected,
             worktree_path="",
             worktree_branch="",
@@ -105,6 +103,8 @@ def select_and_provision_implementation_stage(
             started_head_commit=head,
             concurrent_stages=concurrent_stages,
         )
+        _record_stage_run_claim_started(task_key, plan_run_root, claim)
+        return claim
 
     # The anchor and multi-dep candidate base must come from the task-key
     # worktree HEAD (where stage work accumulates), not from inp.project_root
@@ -166,7 +166,7 @@ def select_and_provision_implementation_stage(
             f"stage worktree provisioning failed: {exc}\n{hint}"
         ) from exc
 
-    return StageSelection(
+    claim = StageRunClaim(
         stage=selected,
         worktree_path=prov.path,
         worktree_branch=prov.branch,
@@ -176,22 +176,40 @@ def select_and_provision_implementation_stage(
         started_head_commit=prov.base_ref,
         concurrent_stages=concurrent_stages,
     )
+    _record_stage_run_claim_started(task_key, plan_run_root, claim)
+    return claim
+
+
+def _record_stage_run_claim_started(
+    task_key: str,
+    plan_run_root: Path,
+    claim: StageRunClaim,
+) -> None:
+    from .consumers import append_consumer
 
+    now = _dt.datetime.now(_dt.timezone.utc).isoformat()
+    append_consumer(
+        plan_run_root,
+        impl_task_key=task_key,
+        stage=claim.stage,
+        status="started",
+        started_at=now,
+        head_commit=claim.started_head_commit,
+    )
 
-def apply_implementation_stage(
+
+def publish_stage_run_claim(
     inp: Any,
     ctx: dict[str, Any],
     ctx_stage_map: list[dict[str, Any]],
-    sel: StageSelection,
+    claim: StageRunClaim,
 ) -> None:
-    """Publish a selected stage into run context and ``consumers.jsonl``."""
-    from .consumers import append_consumer
-
+    """Publish a Stage Run Claim into run context."""
     ctx["parsed_stage_map"] = ctx_stage_map
-    ctx["effective_stages"] = [sel.stage]
-    csv = str(sel.stage)
+    ctx["effective_stages"] = [claim.stage]
+    csv = str(claim.stage)
     ctx["EFFECTIVE_STAGES"] = csv
-    ctx["CONCURRENT_RUN_STAGES"] = ",".join(str(s) for s in sel.concurrent_stages)
+    ctx["CONCURRENT_RUN_STAGES"] = ",".join(str(s) for s in claim.concurrent_stages)
     ctx["STAGE_BATCH_DIRECTIVE"] = (
         f"- **Stage for this implementation run:** `{csv}`. "
         "Execute exactly this Stage Map stage — this is the authoritative scope. "
@@ -201,20 +219,9 @@ def apply_implementation_stage(
     inp.stage = csv
     print(f"selected stages: {csv}", file=sys.stdout)
 
-    if sel.worktree_status and not sel.worktree_status.startswith("skipped"):
-        ctx["EXECUTOR_WORKTREE_PATH"] = sel.worktree_path
-        ctx["EXECUTOR_WORKTREE_BRANCH"] = sel.worktree_branch
-        ctx["EXECUTOR_WORKTREE_BASE_REF"] = sel.worktree_base_ref
-        ctx["EXECUTOR_WORKTREE_STATUS"] = sel.worktree_status
-        ctx["EXECUTOR_WORKTREE_NOTE"] = sel.worktree_note
-
-    now = _dt.datetime.now(_dt.timezone.utc).isoformat()
-    plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
-    append_consumer(
-        plan_run_root,
-        impl_task_key=ctx["TASK_KEY"],
-        stage=sel.stage,
-        status="started",
-        started_at=now,
-        head_commit=sel.started_head_commit,
-    )
+    if claim.worktree_status and not claim.worktree_status.startswith("skipped"):
+        ctx["EXECUTOR_WORKTREE_PATH"] = claim.worktree_path
+        ctx["EXECUTOR_WORKTREE_BRANCH"] = claim.worktree_branch
+        ctx["EXECUTOR_WORKTREE_BASE_REF"] = claim.worktree_base_ref
+        ctx["EXECUTOR_WORKTREE_STATUS"] = claim.worktree_status
+        ctx["EXECUTOR_WORKTREE_NOTE"] = claim.worktree_note