okstra 0.29.0 → 0.30.0

package/README.kr.md

@@ -185,6 +185,9 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 - **PR 본문 템플릿 설정** (release-handoff) — PR 본문은 마크다운 템플릿에서 채워집니다. 해석 우선순위: 1회성 override (`--pr-template-path` 또는 okstra-run Step 6 prompt) → `<project_root>/.project-docs/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 도 프로파일이 실제로 받는 워커만 보여줍니다.
 - **Phase 6 plan-body verification (implementation-planning 전용)** — Report writer worker 가 final-report draft 를 작성한 직후, User Approval 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` 중 하나. 앞 둘은 final-report 상단의 `- [ ] Approved` 마커를 렌더하고, 뒤 둘은 `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).
+- **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 (`.project-docs/okstra/`)** — okstra 가 사용자 프로젝트에 쓰는 모든 파일은 `<project>/.project-docs/okstra/` subtree 안에만 위치합니다. 외부 경로 (`CONTEXT.md`, `docs/adr/`, `.scratch/`, 소스 코드) 는 read-only reference 이며 부재해도 정상 상태입니다. 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 생성으로 인해 수정되지 않습니다.
 
 ### 3.5 운영 명령
 
@@ -196,6 +199,7 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 | `npx -y okstra@latest setup --project-id <id>` | 현재 프로젝트를 등록 (`.project-docs/okstra/project.json`) |
 | `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 render-views <final-report.md>` | final-report MD 한 본을 입력으로 슬림 MD + HTML 두 view 를 (재)생성 (Phase 7 step 1.5; 멱등) |
 | `npx -y okstra@latest uninstall` | 런타임 + 스킬 제거; 사용자 데이터(`recent.jsonl`, `projects/`, …)는 보존 |
 | `npx -y okstra@latest uninstall --purge -y` | 사용자 데이터까지 모두 제거 |
 

package/README.md

@@ -184,6 +184,9 @@ 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>/.project-docs/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.
 - **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`; only the first two render the top-of-report `- [ ] Approved` marker, the other two 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).
+- **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 (`.project-docs/okstra/`)** — okstra writes only inside `<project>/.project-docs/okstra/`. External paths (`CONTEXT.md`, `docs/adr/`, `.scratch/`, source code) are read-only references; their absence is normal. 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.
 
 ### 3.5 Ops commands
 
@@ -195,6 +198,7 @@ Recent workflow additions (post-0.8.0, on `main`):
 | `npx -y okstra@latest setup --project-id <id>` | Register the current project (`.project-docs/okstra/project.json`) |
 | `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 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 uninstall` | Remove runtime + skills; preserves user data (`recent.jsonl`, `projects/`, …) |
 | `npx -y okstra@latest uninstall --purge -y` | Remove everything including user data |
 

package/docs/kr/architecture.md

@@ -35,6 +35,7 @@
 - [Required team contract](#required-team-contract)
 - [Stable task identity](#stable-task-identity)
 - [Project self-registration](#project-self-registration)
+- [Artifact-home rule](#artifact-home-rule)
 - [Task type](#task-type)
   - [표준 task type](#표준-task-type)
   - [Phase 간 정보 전달](#phase-간-정보-전달)
@@ -62,9 +63,11 @@
   - [8. 구현 후 최종 검토](#8-구현-후-최종-검토)
   - [9. 같은 task 재개](#9-같은-task-재개)
 - [Lifecycle status and resume](#lifecycle-status-and-resume)
-- [Preferred final report structure](#preferred-final-report-structure)
+- [Final report structure](#final-report-structure)
+- [Final report views (slim MD + HTML)](#final-report-views-slim-md--html)
 - [Worker error collection (optional sidecar)](#worker-error-collection-optional-sidecar)
 - [Token usage and cost accounting](#token-usage-and-cost-accounting)
+- [Validators](#validators)
 - [Practical notes](#practical-notes)
 - [Related documents](#related-documents)
 
@@ -307,6 +310,19 @@ Claude launch prompt 본문은 항상 `prompts/launch.template.md` 템플릿에
 
 `okstra-ctl` 의 reindex/backfill 도 신규 모델에서 권위 소스를 변경했습니다. 과거에는 `examples/projects/*.conf.sh` 를 source 했지만, 지금은 `~/.okstra/projects/<projectId>/meta.json` (record_start 가 위 project.json 정보를 mirror 한 결과) 을 스캔하여 (projectId, projectRoot) 매핑을 복원합니다. `OKSTRA_PROJECT_DEFINITION_DIR_OVERRIDE` 환경변수도 함께 폐기되었습니다.
 
+## Artifact-home rule
+
+okstra 가 사용자 프로젝트에 생성·수정·삭제하는 모든 파일은 `<PROJECT_ROOT>/.project-docs/okstra/` subtree 안에만 위치합니다. 외부 경로 (예: `<PROJECT_ROOT>/CONTEXT.md`, `<PROJECT_ROOT>/docs/adr/`, `<PROJECT_ROOT>/.scratch/`, 소스 코드) 는 **read-only reference** 입니다. okstra phase 는 그 파일들이 존재하면 읽을 수 있지만 부재해도 정상 상태로 간주하며, 자체 판단으로 외부 경로에 쓰지 않습니다.
+
+유일한 예외: brief 의 `Source Material` 또는 `Reporter Confirmations` 섹션에서 사용자가 **verbatim** 으로 특정 외부 파일 편집을 요청한 경우. 해당 편집을 수행하는 phase 는 자신의 final-report 에 사용자 원문 인용을 함께 남겨야 합니다.
+
+okstra 는 자기 subtree 안에 자체 institutional memory 를 유지합니다.
+
+- `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` — run 을 가로지르며 누적되는 okstra 용어집. 외부 `CONTEXT.md` 류 skill 의 기능을 흡수합니다.
+- `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md` — okstra 의 결정 기록. 외부 ADR 시스템의 기능을 흡수합니다. 평가 시점은 `implementation-planning` phase 이며 `okstra-brief` 단계에서는 후보만 표시합니다.
+
+okstra phase 는 PRD / issue file 을 직접 쓰지 않습니다. 동등한 결정 산출물은 `requirements-discovery` 와 `implementation-planning` 이 `.project-docs/okstra/` 내부에 만듭니다.
+
 ## Task type
 
 `task-type`은 이번 run의 목적과 profile 선택, 그리고 lifecycle phase 라우팅을 동시에 결정합니다.
@@ -417,9 +433,14 @@ task manifest, task index, instruction-set, runs, history가 이 루트 아래
 그리고 `--render-only`가 아니면 handoff된 Claude session이 보통 아래 결과 파일을 현재 run에 추가합니다.
 - `sessions/claude-resume-<task-type>-<seq>.sh`
 - `reports/final-report-<task-type>-<seq>.md`
+- `reports/final-report-<task-type>-<seq>.slim.md`  *(Phase 7 결정론적 후처리: AI 다음-phase 입력용 슬림 markdown)*
+- `reports/final-report-<task-type>-<seq>.html`     *(Phase 7 결정론적 후처리: 사람 reviewer 용 self-contained HTML, CSS/JS 인라인)*
+- `user-responses/user-response-<task-type>-<seq>.md` *(HTML 의 `Export user response` 버튼이 생성하는 사이드카; 사용자가 채워 저장하면 다음 phase 가 입력으로 소비)*
+- `worker-results/<worker>-audit-<task-type>-<seq>.md` *(워커별 Reading Confirmation 사이드카; 본문이 아니라 audit 용)*
 - `status/final-<task-type>-<seq>.status`
-최종 결과 파일 둘은 `okstra`가 stdout을 저장해서 만드는 파일이 아닙니다.
+최종 결과 파일 (`final-report` MD / status) 은 `okstra`가 stdout을 저장해서 만드는 파일이 아닙니다.
 `okstra`가 준비한 task bundle을 바탕으로 Claude가 현재 run 안에 직접 작성하는 결과물입니다.
+slim MD / HTML 두 view 는 `okstra render-views <final-report.md>` (Phase 7 step 1.5) 가 final-report MD 한 본을 입력으로 결정론적으로 생성합니다. 원본 MD 는 view 생성으로 인해 수정되지 않습니다.
 반면 `sessions/claude-resume-<task-type>-<seq>.sh`는 `okstra`가 Claude launch 전에 미리 생성하는 interruption recovery helper입니다.
 
 run directory는 task-type 단위로 task 실행 이력을 모으고, 내부를 `manifests/`, `state/`, `prompts/`, `reports/`, `status/`, `sessions/`, `worker-results/`처럼 유형별 하위 폴더로 나눈 뒤 각 run-level artifact와 result 파일을 `-<task-type>-<seq>` suffix(per-category 3-digit zero-padded counter, 예: `001`, `002`)로 구분합니다.
@@ -611,6 +632,8 @@ canonical metadata는 항상 `task-manifest.json`을 기준으로 확인합니
 
 `okstra`는 brief-first 구조입니다. brief 가 분석의 정본 입력이며, 워커가 필요로 할 추가 자료(보고서, 코드 스니펫, 로그 등)는 brief 내부의 `Evidence and Source Materials` 섹션에 inline 또는 path 로 모두 포함시킵니다.
 
+brief 는 **translation layer** 입니다 — 외부 입력 (이슈 트래커 ticket, 요구사항 문서, 사용자 메시지) 을 okstra-readable 형식으로 옮기되, 원문은 verbatim 으로 보존하고 okstra 가 추가한 부분은 labelled augmentation 으로 명확히 구분합니다. okstra-brief skill 의 산출이 정식 SSOT 이며, 분석 워커들이 phase 시작 전에 일률적으로 읽어들이는 단일 입력입니다.
+
 brief에는 보통 아래를 포함합니다.
 
 - 문제 설명
@@ -622,6 +645,10 @@ brief에는 보통 아래를 포함합니다.
 - worker에게 줄 질문
 - 기대 출력
 - 이전 run 또는 연관 task 정보
+- (선택) glossary 추가 후보 — okstra-brief Step 4.5 가 `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` 에 직접 기록
+- (선택) decisions 후보 — `implementation-planning` phase 에서 평가 후 `.project-docs/okstra/decisions/<NNNN>-<slug>.md` 로 승격
+
+okstra-brief 의 Step 6.5 는 **reporter batch confirmation** 입니다. brief 가 외부 입력을 옮기는 도중 의미 변화가 발생했는지를 사용자에게 일괄 확인받고 그 결과를 `Reporter Confirmations` 섹션에 기록합니다. 모든 분석 profile 은 이 섹션의 존재를 phase 분석 진입의 precondition 으로 강제합니다 (validator: `validators/validate-brief.py`).
 
 기본 템플릿:
 
@@ -796,22 +823,42 @@ resume 판단 기준:
 - 다음 phase 시작: `workflow.nextRecommendedPhase`가 구체적인 phase면 그 값으로 다음 `okstra.sh` 실행을 준비합니다.
 - 추가 자료 필요: `routingStatus=pending` 또는 `nextRecommendedPhase=pending-routing-decision`이면 brief 보강이 먼저입니다.
 
-## Preferred final report structure
+## Final report structure
 
 기본 최종 보고서 템플릿은 `templates/reports/final-report.template.md`입니다.
-Claude가 작성하는 최종 보고서는 brief에 더 구체적인 형식이 없다면 아래 구조를 우선 사용합니다.
+Claude가 작성하는 최종 보고서는 아래 구조를 우선 사용합니다 (brief 의 augmentation 이 더 구체적인 형식을 요구할 때만 그것을 따릅니다).
 
-1. 문제 또는 검증 대상 요약
-2. 에이전트별 실행 현황
-3. Cross Verification 결과
-4. 최종 판단
-5. 근거 및 세부 분석
-6. 누락 정보 및 리스크
-7. 권장 다음 단계
+- `## Verdict Card` — **최상단 의무 섹션**. Final Conclusion / Verdict Token / Direction / Approval Required? / Next Step 5 행. Verdict Token / Direction / Next Step 셀은 본문 §2 (실행 현황) 와 §6 (다음 단계) 의 권위 셀과 byte-match 해야 합니다.
+- (선택) `## 0. Clarification Response Carried In From Previous Run` — 직전 run 에서 응답이 carry-in 된 경우에만 렌더링. 빈 carry-in 일 때는 헤딩 자체를 출력하지 않습니다.
+- `## 1. 문제 또는 검증 대상 요약` — §1.1 Consensus / §1.2 Differences 표 각각 `Source items (worker:item)` 컬럼 보존 (cross-worker traceability).
+- `## 2. 에이전트별 실행 현황`
+- `## 3. Cross Verification 결과` — §3.1 Primary Evidence 에 `Source items (worker:item)` + `Source (path:line / log)` 컬럼.
+- `## 4. 최종 판단` — `implementation-planning` 의 §4.5.9 Plan Body Verification 은 두 표 (`Verdict summary` 4-열, `Verdict details` 5-열, plan item × worker) 로 분할 emit.
+- `## 5. Clarification Items` — 통합 8-열 표 한 곳. 기존 §5.1 / §5.2 / §4.5.8 / §4.5.9 Open Questions 는 deprecated 되어 validator 가 등장 시 fail.
+- `## 6. 권장 다음 단계`
+- `## Token Usage Summary` — sentinel (`pending` / `N/A` / `--` / `?` / 빈 셀) 또는 zero (`0` / `$0.00`) 박제 시 validator 가 출고를 차단합니다. `Codex/Gemini CLI 추가 비용` 행만 "CLI 미사용" 의미로 `$0.00` 허용.
+
+워커 출력의 `## 0. Reading Confirmation` 블록은 본문에 두지 않고 `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md` 사이드카에 작성합니다 (validator 강제).
 
 차이점이 실질적으로 없으면 억지로 대비를 만들지 말고, 차이가 없음을 명시합니다.
 저장 실패나 세션 제한에 대한 메타 설명 대신 실제 Markdown 보고서 본문을 파일에 작성해야 합니다.
 
+## Final report views (slim MD + HTML)
+
+Phase 7 step 1.5 가 final-report MD 한 본을 입력으로 두 view 를 결정론적으로 자동 생성합니다.
+
+- `reports/final-report-<task-type>-<seq>.slim.md` — AI 다음-phase 입력용. 장식·캡션·sentinel 셀을 제거한 토큰-경제 버전. `validate-run.py` 의 phase substring 검사를 byte-identical 로 통과합니다.
+- `reports/final-report-<task-type>-<seq>.html` — 사람 reviewer 용 self-contained HTML. CSS / JS 인라인 임베드 (외부 URL 0), system color 다크모드, sticky header, 인쇄 대응. §5 `C-*` 행의 의사결정 입력 (체크박스 / 셀렉트 / textarea) 을 화면에서 채우고 `Export user response` 버튼으로 사이드카 markdown 을 생성합니다.
+
+진입점:
+
+- Python 단일 reference: `scripts/okstra_ctl/report_views.py` (`slim_markdown(...)`, `render_html(..., css, js)`, `serialize_user_response(...)`). HTML 내 JS `buildUserResponseMarkdown` 은 Python `serialize_user_response` 와 **byte-identical** (Node `vm.runInThisContext` 단위 테스트로 자동 검증).
+- CLI: `scripts/okstra-render-report-views.py <final-report.md>` 또는 Node 위임 wrapper `bin/okstra render-views <md>`.
+- 검증: `validators/validate-report-views.py` — slim 의 phase substring 보존, HTML 내 form control 위치, 외부 URL 부재, Response ID parity (`C-*` ↔ HTML), 두 모듈 substring 상수 drift 모두 검사.
+- 사용자 응답 사이드카 스키마 SSOT: `templates/reports/user-response.template.md`.
+
+원본 final-report MD 는 어떤 경우에도 view 생성으로 인해 수정되지 않습니다.
+
 ## Worker error collection (optional sidecar)
 
 워커(Claude/Codex/Gemini worker, Report writer, Claude lead) 실행 중 발생한 에러를 단일 시계열 로그로 수집해 사후 회고에 사용할 수 있습니다.
@@ -854,8 +901,19 @@ Claude가 작성하는 최종 보고서는 brief에 더 구체적인 형식이
   - Claude lead/workers: `~/.claude/projects/<cwd-as-dashes>/<sessionId>.jsonl`의 per-message `message.usage`
   - Codex CLI: `~/.codex/sessions/Y/M/D/rollout-*.jsonl`의 마지막 `total_token_usage.total_tokens`
   - Gemini CLI: `~/.gemini/tmp/*/chats/session-*.json`의 per-message `tokens.total`
-- billable-equivalent token math와 USD cost estimation을 함께 기록합니다. Anthropic billing ratio(`cache_creation=1.25x`, `cache_read=0.1x`, `output=5x`)를 반영합니다.
-- 가격표는 helper 상단에서 중앙 관리합니다. 모델 가격이 바뀌면 helper의 `*_PRICING` 상수를 갱신해야 합니다.
+- 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` 분해가 있으면 분리 집계합니다.
+- 가격표는 `scripts/okstra_token_usage/pricing.py` 에서 중앙 관리합니다. 모델 가격이 바뀌면 거기서 갱신합니다. 가격 매칭에 실패한 모델 id 는 `usageSummary.unmatchedModels` 필드로 사용자에게 노출됩니다 (silent zero 사고 방지).
+
+## Validators
+
+phase 산출물의 출고 가능 여부를 강제하는 진입점:
+
+- `validators/validate-workflow.sh` — phase contract 통합 검증.
+- `validators/validate-run.py` — run-level final-report 본문 contract (Verdict Card 존재, deprecated §5.1/§5.2/§4.5.8/§4.5.9 Open Questions 부재, Plan Body Verification gate × Approval 마커 cross-check, Token Usage sentinel/zero 차단, 워커-결과 audit 사이드카 존재).
+- `validators/validate-report-views.py` — slim MD / HTML view 의 phase substring 보존 및 form-control 영역 검사.
+- `validators/validate-brief.py` — brief schema (front-matter, `Reporter Confirmations` 섹션 존재, root parent-id self 규칙, slug 컨벤션 등) 강제. `bash validators/validate-brief.sh <brief.md>` 가 thin wrapper.
+
+각 validator 는 contract 위반 시 `contract-violated` exit code 로 phase 를 차단합니다. 위반은 다음 phase 실행 시점에 적용되므로 이전 산출물은 그대로 둡니다.
 
 ## Practical notes
 
@@ -883,6 +941,9 @@ Claude가 작성하는 최종 보고서는 brief에 더 구체적인 형식이
 - 워커 에러는 옵션 sidecar `runs/<task-type>/logs/errors-<task-type>-<seq>.jsonl`로 수집되며 lead가 단독 writer입니다. 진입점 helper는 `scripts/okstra-error-log.py`입니다.
 - 토큰 사용 및 비용 집계는 `scripts/okstra-token-usage.py`가 담당하며.
 - `okstra.sh`는 worker CLI 호출 anchoring을 위해 절대 projectRoot를 강제합니다.
+- `okstra wizard step` 은 `--answer <val>` 을 **필수** 로 받습니다. 응답을 줄 차례가 아니라 다음 prompt 만 미리 보고 싶다면 `--no-submit` 으로 peek 합니다.
+- `okstra history` 는 manifest fallback / 페이지네이션 / 필터를 지원하며, `--base-ref` 는 워크트리 registry 에서 해석합니다.
+- 사용자 프로젝트에 대한 모든 쓰기는 `<PROJECT_ROOT>/.project-docs/okstra/` 안에만 발생합니다 (Artifact-home rule 참조).
 
 ## Related documents
 

package/docs/kr/cli.md

@@ -32,6 +32,7 @@
   - [`--work-category`](#--work-category)
   - [`--related-tasks`](#--related-tasks)
   - [`--render-only`](#--render-only)
+  - [`--no-plan-verification`](#--no-plan-verification)
 - [Interactive input flow](#interactive-input-flow)
 - [Confirmation flow](#confirmation-flow)
 - [okstra Control Center — 설치 / 자주 쓰는 명령](#okstra-control-center--설치--자주-쓰는-명령)
@@ -517,6 +518,7 @@ chmod +x ~/.local/bin/okstra-ctl
 | 진행 중 run 보기 | `okstra-ctl tail active` |
 | 단일 run 결과 메타 | `okstra-ctl show <runId-or-prefix>` |
 | 결과 보고서 경로 | `okstra-ctl open <runId-or-prefix>` |
+| final-report 두 view 재생성 | `okstra render-views <final-report.md>` |
 | 단일 재실행 | `okstra-ctl rerun <runId-or-prefix> --yes` |
 | 다중 재실행 | `okstra-ctl rerun --filter --project X --status failed --yes` |
 | 가장 최근 재실행 | `okstra-ctl rerun last --project X --task-group Y --yes` |
@@ -535,7 +537,10 @@ chmod +x ~/.local/bin/okstra-ctl
 | `okstra worktree-lookup <task-key>` | `worktree_registry.lookup` 결과 (예약된 path / branch / base ref / 현재 상태) |
 | `okstra plan-validate <plan-path>` | `_validate_approved_plan` — approval marker 인식 결과와 sanitization 후 diff |
 | `okstra render-bundle <args…>` | `prepare_task_bundle(render_only=True)` 의 thin shim — `python3 -m okstra_ctl.run --render-only` 와 동일 시그니처 |
-| `okstra wizard <init\|step\|render-args\|confirmation> --state-file <path>` | okstra-run 인터랙티브 입력 상태머신 (`okstra_ctl.wizard`). `init` 으로 state file 을 시드한 뒤 skill 이 `step --answer <val>` 을 반복 호출하면 다음 `Prompt` JSON 을 받음. `render-args` 는 최종 `render-bundle` 인자 맵, `confirmation` 은 사용자 echo 블록을 반환 |
+| `okstra render-views <final-report.md>` | Phase 7 step 1.5 — 토큰 치환된 final-report MD 한 본을 입력으로 sibling `*.slim.md` (AI 입력용) + `*.html` (사람용 self-contained) 두 view 를 결정론적으로 생성. 원본 MD 는 수정하지 않음. Node 위임 wrapper는 `scripts/okstra-render-report-views.py` 를 호출. `validators/validate-report-views.py` 가 substring 보존 / form-control 위치 / Response ID parity 를 검사 |
+| `okstra wizard <init\|step\|render-args\|confirmation> --state-file <path>` | okstra-run 인터랙티브 입력 상태머신 (`okstra_ctl.wizard`). `init` 으로 state file 을 시드한 뒤 skill 이 `step --answer <val>` 을 반복 호출하면 다음 `Prompt` JSON 을 받음. `--answer` 는 **필수**. 응답을 주지 않고 다음 prompt 만 미리 보고 싶다면 `--no-submit` 으로 peek. `render-args` 는 최종 `render-bundle` 인자 맵, `confirmation` 은 사용자 echo 블록을 반환 |
+| `okstra history [--limit N] [--offset M] [--project <id>] [--status <enum>]` | run history 페이지네이션 / 필터 조회. 중앙 인덱스가 비어 있으면 프로젝트별 task-manifest 들을 스캔해 fallback 으로 채움. `--base-ref` 는 워크트리 registry 에서 해석 |
+| `okstra config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | 영구 설정 관리 (예: `pr-template-path`). 원자적 JSON 쓰기. global scope 의 상대경로는 거절 |
 
 > 모든 subcommand 는 `bin/okstra` 가 spawn 하는 python 헬퍼 (`src/_python-helper.mjs`) 가 `PYTHONPATH` 와 `~/.okstra/lib/python` 을 wire 합니다. 직접 `python3 -m okstra_ctl.*` 으로 호출하면 `PYTHONPATH` 를 사용자가 직접 셋업해야 합니다.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.29.0",
+  "version": "0.30.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.29.0",
-  "builtAt": "2026-05-17T06:30:39.418Z",
+  "package": "0.30.0",
+  "builtAt": "2026-05-17T08:21:41.472Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/wizard.py

@@ -73,12 +73,93 @@ GEMINI_MODEL_OPTIONS = ["default", "gemini-3-pro-preview", "gemini-3-flash-previ
 # special pick value: start a brand-new task
 TASK_PICK_NEW_TOKEN = "__new__"
 
+# Pick-vs-free-text tokens shared by suggestion-aware prompts.
+PICK_USE_SUGGESTED = "__use_suggested__"
+PICK_TYPE_CUSTOM = "__free_input__"
+
+# Lines of `key: value` we pull from a brief markdown frontmatter. The
+# parser is intentionally lightweight (no yaml dep) and tolerant — a
+# malformed brief returns an empty dict.
+_BRIEF_FRONTMATTER_LINE_RE = re.compile(r"^([a-zA-Z0-9_\-]+)\s*:\s*(.*)$")
+
+
+def _parse_brief_frontmatter(path: Path) -> dict[str, str]:
+    """Read the YAML-style frontmatter at the top of a brief markdown file
+    and return a flat ``{key: value}`` map.
+
+    Returns ``{}`` if the file is unreadable, has no frontmatter, or the
+    frontmatter is malformed. Comments (``# ...``) and quoted values are
+    stripped. Placeholder values like ``<task-group>`` are kept verbatim;
+    callers decide whether to treat them as a real suggestion.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    if not text.startswith("---"):
+        return {}
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}
+    out: dict[str, str] = {}
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        # strip trailing inline comment
+        comment_idx = line.find("#")
+        if comment_idx >= 0:
+            line = line[:comment_idx]
+        m = _BRIEF_FRONTMATTER_LINE_RE.match(line.strip())
+        if not m:
+            continue
+        key, val = m.group(1), m.group(2).strip()
+        # strip matching quotes
+        if (len(val) >= 2 and val[0] == val[-1] and val[0] in ("'", '"')):
+            val = val[1:-1]
+        out[key] = val
+    return out
+
+
+def _looks_like_template_placeholder(value: str) -> bool:
+    """Treat ``<task-group>``, ``<...>``, empty strings, and ``self`` as
+    non-suggestions. Anything else (a real slug-like value) is honored."""
+    v = (value or "").strip()
+    if not v:
+        return True
+    if v.startswith("<") and v.endswith(">"):
+        return True
+    if v.lower() in ("self", "tbd", "n/a", "na", "none"):
+        return True
+    return False
+
+
+def _brief_suggestions(path: Path) -> tuple[str, str]:
+    """Return ``(task_group_suggestion, task_id_suggestion)`` extracted from
+    the brief's frontmatter, or empty strings when no usable value exists.
+
+    - ``task_group`` ← frontmatter ``task-group``.
+    - ``task_id``    ← frontmatter ``brief-id`` (which matches the
+                       filename stem in okstra-brief output and is the
+                       strongest single identifier of the task).
+
+    A brief without frontmatter, or with placeholder values, yields two
+    empty strings — callers fall back to plain-text input.
+    """
+    fm = _parse_brief_frontmatter(path)
+    tg_raw = fm.get("task-group", "")
+    bid_raw = fm.get("brief-id", "")
+    tg = "" if _looks_like_template_placeholder(tg_raw) else tg_raw
+    tid = "" if _looks_like_template_placeholder(bid_raw) else bid_raw
+    return tg, tid
+
 
 # ---- Step IDs ------------------------------------------------------------
 
 S_TASK_PICK = "task_pick"
 S_TASK_GROUP = "task_group"
+S_TASK_GROUP_TEXT = "task_group_text"
 S_TASK_ID = "task_id"
+S_TASK_ID_TEXT = "task_id_text"
 S_TASK_TYPE = "task_type"
 S_BRIEF_KEEP = "brief_keep"
 S_BRIEF_PATH = "brief_path"
@@ -123,6 +204,13 @@ class WizardState:
     task_group: str = ""
     task_id: str = ""
     existing_brief_path: str = ""
+    # brief-derived suggestions (new-task flow only; set when brief is
+    # accepted, cleared if the user picks "type custom" so the next
+    # `_build_*` falls back to plain text input)
+    task_group_suggestion: str = ""
+    task_id_suggestion: str = ""
+    task_group_pending_text: bool = False
+    task_id_pending_text: bool = False
 
     # task-type + dependents
     task_type: str = ""
@@ -421,24 +509,98 @@ def _submit_task_pick(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_task_group(state: WizardState) -> Prompt:
+    sugg = state.task_group_suggestion
+    if sugg:
+        return Prompt(
+            step=S_TASK_GROUP, kind="pick",
+            label=f"Task group? (brief 추천: {sugg})",
+            options=[
+                _opt(PICK_USE_SUGGESTED, f"brief 값 사용: {sugg}"),
+                _opt(PICK_TYPE_CUSTOM, "다른 값 입력"),
+            ],
+            echo_template="task-group: {value}",
+        )
     return Prompt(step=S_TASK_GROUP, kind="text",
                   label="Task group 을 알려주세요 (예: backend-api, INV-1234, refactor)",
                   echo_template="task-group: {value}")
 
 
 def _submit_task_group(state: WizardState, value: str) -> Optional[str]:
+    if state.task_group_suggestion:
+        if value == PICK_USE_SUGGESTED:
+            state.task_group = _slug_or_die(
+                state.task_group_suggestion, "task_group"
+            )
+            state.task_group_pending_text = False
+            return f"task-group: {state.task_group} (brief)"
+        if value == PICK_TYPE_CUSTOM:
+            state.task_group_pending_text = True
+            return f"task-group: (직접 입력)"
+        raise WizardError(
+            f"expected {PICK_USE_SUGGESTED!r} or {PICK_TYPE_CUSTOM!r}, "
+            f"got: {value!r}"
+        )
+    state.task_group = _slug_or_die(value, "task_group")
+    state.task_group_pending_text = False
+    return f"task-group: {state.task_group}"
+
+
+def _build_task_group_text(state: WizardState) -> Prompt:
+    return Prompt(step=S_TASK_GROUP_TEXT, kind="text",
+                  label="Task group 을 입력해주세요 (예: backend-api, INV-1234, refactor)",
+                  echo_template="task-group: {value}")
+
+
+def _submit_task_group_text(state: WizardState, value: str) -> Optional[str]:
     state.task_group = _slug_or_die(value, "task_group")
+    state.task_group_pending_text = False
     return f"task-group: {state.task_group}"
 
 
 def _build_task_id(state: WizardState) -> Prompt:
+    sugg = state.task_id_suggestion
+    if sugg:
+        return Prompt(
+            step=S_TASK_ID, kind="pick",
+            label=f"Task id? (brief 추천: {sugg})",
+            options=[
+                _opt(PICK_USE_SUGGESTED, f"brief 값 사용: {sugg}"),
+                _opt(PICK_TYPE_CUSTOM, "다른 값 입력"),
+            ],
+            echo_template="task-id: {value}",
+        )
     return Prompt(step=S_TASK_ID, kind="text",
                   label="Task id 를 알려주세요 (예: login-error-analysis, dev-9043)",
                   echo_template="task-id: {value}")
 
 
 def _submit_task_id(state: WizardState, value: str) -> Optional[str]:
+    if state.task_id_suggestion:
+        if value == PICK_USE_SUGGESTED:
+            state.task_id = _slug_or_die(state.task_id_suggestion, "task_id")
+            state.task_id_pending_text = False
+            return f"task-id: {state.task_id} (brief)"
+        if value == PICK_TYPE_CUSTOM:
+            state.task_id_pending_text = True
+            return f"task-id: (직접 입력)"
+        raise WizardError(
+            f"expected {PICK_USE_SUGGESTED!r} or {PICK_TYPE_CUSTOM!r}, "
+            f"got: {value!r}"
+        )
     state.task_id = _slug_or_die(value, "task_id")
+    state.task_id_pending_text = False
+    return f"task-id: {state.task_id}"
+
+
+def _build_task_id_text(state: WizardState) -> Prompt:
+    return Prompt(step=S_TASK_ID_TEXT, kind="text",
+                  label="Task id 를 입력해주세요 (예: login-error-analysis, dev-9043)",
+                  echo_template="task-id: {value}")
+
+
+def _submit_task_id_text(state: WizardState, value: str) -> Optional[str]:
+    state.task_id = _slug_or_die(value, "task_id")
+    state.task_id_pending_text = False
     return f"task-id: {state.task_id}"
 
 
@@ -502,6 +664,14 @@ def _build_brief_path(state: WizardState) -> Prompt:
 def _submit_brief_path(state: WizardState, value: str) -> Optional[str]:
     p = _require_file(value, Path(state.project_root), "task brief")
     state.brief_path = str(p)
+    # When the user is starting a brand-new task, pull task-group /
+    # task-id candidates from the brief frontmatter so the next two
+    # prompts can offer them as a one-click pick instead of forcing a
+    # free-text retype of what the brief already declares.
+    if state.is_new_task and not state.task_group and not state.task_id:
+        tg, tid = _brief_suggestions(p)
+        state.task_group_suggestion = tg
+        state.task_id_suggestion = tid
     return f"brief: {p}"
 
 
@@ -1002,15 +1172,57 @@ STEPS: list[Step] = [
          applies=lambda s: s.is_new_task is None,
          build=_build_task_pick, submit=_submit_task_pick,
          owns=("is_new_task", "task_group", "task_id", "task_type",
-               "existing_brief_path", "profile_workers")),
+               "existing_brief_path", "profile_workers",
+               "task_group_suggestion", "task_id_suggestion",
+               "task_group_pending_text", "task_id_pending_text")),
+    Step(S_BRIEF_PATH,
+         applies=lambda s: (
+             not s.brief_path
+             and (
+                 # new-task flow: collect brief FIRST so task-group /
+                 # task-id can be offered as one-click picks from the
+                 # brief's frontmatter.
+                 (s.is_new_task is True)
+                 # existing-task flow: brief comes after task-type and
+                 # the optional brief-keep step (unchanged behavior).
+                 or (s.is_new_task is False
+                     and S_TASK_TYPE in s.answered
+                     and (s.keep_existing_brief is False
+                          or not s.existing_brief_path))
+             )
+         ),
+         build=_build_brief_path, submit=_submit_brief_path,
+         owns=("brief_path", "task_group_suggestion", "task_id_suggestion")),
     Step(S_TASK_GROUP,
-         applies=lambda s: bool(s.is_new_task) and not s.task_group,
+         applies=lambda s: (bool(s.is_new_task)
+                            and bool(s.brief_path)
+                            and not s.task_group
+                            and not s.task_group_pending_text),
          build=_build_task_group, submit=_submit_task_group,
-         owns=("task_group",)),
+         owns=("task_group", "task_group_pending_text")),
+    Step(S_TASK_GROUP_TEXT,
+         applies=lambda s: (bool(s.is_new_task)
+                            and bool(s.brief_path)
+                            and not s.task_group
+                            and s.task_group_pending_text),
+         build=_build_task_group_text, submit=_submit_task_group_text,
+         owns=("task_group", "task_group_pending_text")),
     Step(S_TASK_ID,
-         applies=lambda s: bool(s.is_new_task) and bool(s.task_group) and not s.task_id,
+         applies=lambda s: (bool(s.is_new_task)
+                            and bool(s.brief_path)
+                            and bool(s.task_group)
+                            and not s.task_id
+                            and not s.task_id_pending_text),
          build=_build_task_id, submit=_submit_task_id,
-         owns=("task_id",)),
+         owns=("task_id", "task_id_pending_text")),
+    Step(S_TASK_ID_TEXT,
+         applies=lambda s: (bool(s.is_new_task)
+                            and bool(s.brief_path)
+                            and bool(s.task_group)
+                            and not s.task_id
+                            and s.task_id_pending_text),
+         build=_build_task_id_text, submit=_submit_task_id_text,
+         owns=("task_id", "task_id_pending_text")),
     Step(S_TASK_TYPE,
          applies=lambda s: (s.is_new_task is not None
                             and (s.is_new_task is False or bool(s.task_id))
@@ -1023,15 +1235,7 @@ STEPS: list[Step] = [
                             and s.keep_existing_brief is None
                             and S_TASK_TYPE in s.answered),
          build=_build_brief_keep, submit=_submit_brief_keep,
-         owns=("keep_existing_brief", "brief_path")),
-    Step(S_BRIEF_PATH,
-         applies=lambda s: (S_TASK_TYPE in s.answered
-                            and not s.brief_path
-                            and (s.is_new_task
-                                 or s.keep_existing_brief is False
-                                 or (not s.is_new_task and not s.existing_brief_path))),
-         build=_build_brief_path, submit=_submit_brief_path,
-         owns=("brief_path",)),
+         owns=("keep_existing_brief",)),
     Step(S_BASE_REF_PICK,
          applies=lambda s: (S_TASK_TYPE in s.answered
                             and s.reuse_worktree is False
@@ -1240,6 +1444,8 @@ def _reset_from(state: WizardState, target_step: str) -> None:
 _FIELD_DEFAULTS: dict[str, Any] = {
     "is_new_task": None, "task_group": "", "task_id": "",
     "existing_brief_path": "", "task_type": "",
+    "task_group_suggestion": "", "task_id_suggestion": "",
+    "task_group_pending_text": False, "task_id_pending_text": False,
     "profile_workers": [], "keep_existing_brief": None,
     "brief_path": "", "reuse_worktree": None, "base_ref": "",
     "base_ref_pending_text": False, "approved_plan_path": "",

package/runtime/skills/okstra-brief/SKILL.md

@@ -648,11 +648,15 @@ reporter-confirmations: <complete | partial | pending | skipped>  # set by Step
 > Recommended next phase: <requirements-discovery | error-analysis>  ← from Step 6
 > Handoff contract: see `prompts/profiles/_common-contract.md` § "Brief handoff contract"
 
-## Source Material (verbatim — do not modify)
+## Source Material
 
+<!-- author guidance — strip out at fill-in time:
 Paste each source separately and as-is. No paraphrasing, summarizing, or
 restructuring. Format conversion (e.g. Jira ADF → Markdown) is allowed and
-must be annotated in the header meta.
+must be annotated in the header meta. Heading was originally
+"Source Material (verbatim — do not modify)" — the parenthetical is a
+reviewer note, not body text.
+-->
 
 ### Source 1 — <type: file | linear | jira | github | notion | url | user-input>
 
@@ -665,30 +669,31 @@ must be annotated in the header meta.
 <Paste the raw source here without changing a single character.>
 ```
 
-### Source 2 — ...
-
-(Repeat as needed.)
+<!-- Repeat `### Source N — …` blocks as needed. -->
 
 ## Context
 
 <Background / scope / why now. If self-evident from Source Material, quote
 it briefly and stop. Use the blockquote below when augmentation is needed.>
 
-> augmented: <label> — <Interpretation added by the skill or user. Label
-> MUST be one of: `evidence-link` / `format-conversion` /
-> `terminology-mapping` / `intent-inference`. Do NOT add any extra
-> interpretation outside this blockquote.>
+> augmented: <label> — <Interpretation added by the skill or user.>
+
+<!-- label MUST be one of: `evidence-link` / `format-conversion` /
+`terminology-mapping` / `intent-inference`. Do NOT add any extra
+interpretation outside the `> augmented:` blockquote. -->
 
 ## Problem / Symptom
 
 <Current state. For bugs: repro / observed / expected. For greenfield: gap
-between current and desired. Same source-quote + `> augmented:` rule as
-above.>
+between current and desired.>
+
+<!-- Same source-quote + `> augmented:` rule as the Context section. -->
 
 ## Desired Outcome
 
-<Shape of success. Do NOT prescribe a solution — that belongs to
-implementation-planning.>
+<Shape of success.>
+
+<!-- Do NOT prescribe a solution — that belongs to implementation-planning. -->
 
 ## Constraints
 
@@ -701,14 +706,18 @@ none.>
 
 ## Open Questions
 
+<!-- author guidance — strip out at fill-in time:
 Prefix every row with one of these signals so the next phase knows how to
 handle it. Free-form rows are allowed only as `general:`.
 
+Allowed signals:
 - `general: <unresolved question the user flagged>`
-- `terminology: <reporter word> — needs canonical resolution against <PROJECT_ROOT>/.project-docs/okstra/glossary.md`
+- `terminology: <reporter word> — needs canonical resolution against
+  <PROJECT_ROOT>/.project-docs/okstra/glossary.md`
 - `intent-check: <restated inference> — confirm with reporter`
   (auto-paired with every `intent-inference` augmentation)
-- `conversion-block: <reporter statement> — could not be mapped to project vocabulary; reporter query required`
+- `conversion-block: <reporter statement> — could not be mapped to project
+  vocabulary; reporter query required`
 - `adr-candidate: <topic>` — signal only; `implementation-planning`
   evaluates and, if accepted, drafts a decision file at
   `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`.
@@ -718,11 +727,14 @@ Use `_(none)_` only if every signal is empty. `intent-check:` and
 from this list — they receive a `[CONFIRMED <YYYY-MM-DD> → RC-N]`
 marker that links to the corresponding entry under
 `## Reporter Confirmations`.
+-->
+
+- <fill in one row per signal, or replace with `_(none)_`>
 
 ## Reporter Confirmations
 
-Populated by Step 6.5. Each subsection records one reporter answer
-verbatim, with a link back to the originating `Open Questions` row.
+<!-- Populated by Step 6.5. Each subsection records one reporter answer
+verbatim, with a link back to the originating `Open Questions` row. -->
 
 _(none — pending or skipped)_
 
@@ -737,6 +749,7 @@ _(none — pending or skipped)_
 
 ## Augmentation
 
+<!-- author guidance — strip out at fill-in time:
 Cross-references / interpretation / context added by the user or skill that
 is not in the original source. May be empty. Keep this section visually
 separated from Source Material — never inline it inside Source Material.
@@ -744,44 +757,59 @@ separated from Source Material — never inline it inside Source Material.
 Every entry below must start with one of the four labels:
 `evidence-link` / `format-conversion` / `terminology-mapping` /
 `intent-inference`. Unlabelled entries are forbidden.
+-->
 
 ### Domain alignment
 
-Observations from Step 3b and the outcome of Step 4.5 (glossary
-applied vs. skipped). The actual glossary edits live in
+<!-- author guidance — strip out at fill-in time:
+Observations from Step 3b and the outcome of Step 4.5 (glossary applied
+vs. skipped). The actual glossary edits live in
 `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` when applied; this
-section records what happened. Decision candidates are NOT recorded
-here — they flow through `Open Questions` as `adr-candidate:` rows for
+section records what happened. Decision candidates are NOT recorded here —
+they flow through `Open Questions` as `adr-candidate:` rows for
 `implementation-planning` to evaluate (and, if accepted, draft into
 `<PROJECT_ROOT>/.project-docs/okstra/decisions/`).
 
+Allowed entry shapes:
 - `terminology-mapping: <reporter word> → <okstra glossary canonical>` —
   routine glossary alignment, paired with `terminology:` in Open Questions
   when unresolved.
-- `terminology-mapping: applied glossary: <term> → <PROJECT_ROOT>/.project-docs/okstra/glossary.md` /
-  `terminology-mapping: skipped glossary: <term> = <definition>` — Step
-  4.5 outcomes.
-- Use `_(none)_` if every alignment entry is empty.
+- `terminology-mapping: applied glossary: <term> → <PROJECT_ROOT>/.project-docs/okstra/glossary.md`
+- `terminology-mapping: skipped glossary: <term> = <definition>` —
+  Step 4.5 outcomes.
+Use `_(none)_` if every alignment entry is empty.
+-->
+
+- <fill in one entry per alignment, or replace with `_(none)_`>
 
 ### Evidence links (file / symbol resolution)
 
-- `evidence-link: <reporter phrase> → <relative path>:<line>` /
-  `evidence-link: <reporter phrase> → <symbol> in <relative path>`
-- `_(none)_` if none.
+<!-- Allowed entry shapes:
+`evidence-link: <reporter phrase> → <relative path>:<line>` or
+`evidence-link: <reporter phrase> → <symbol> in <relative path>`.
+Use `_(none)_` if none. -->
+
+- <fill in one entry per link, or replace with `_(none)_`>
 
 ### Intent inferences
 
-Every entry here is an unverified hypothesis. Each one MUST have a paired
-`intent-check:` row under Open Questions.
+<!-- Every entry here is an unverified hypothesis. Each one MUST have a
+paired `intent-check:` row under Open Questions.
+
+Allowed entry shape:
+`intent-inference: <reporter phrase> → <qualitative restatement>`
+(qualitative only — never invent numeric thresholds).
+Use `_(none)_` if none. -->
 
-- `intent-inference: <reporter phrase> → <qualitative restatement>`
-  (qualitative only — never invent numeric thresholds)
-- `_(none)_` if none.
+- <fill in one entry per inference, or replace with `_(none)_`>
 
 ### Format conversions
 
-- `format-conversion: <ref> — <e.g. Jira ADF → Markdown, semantics preserved>`
-- `_(none)_` if none.
+<!-- Allowed entry shape:
+`format-conversion: <ref> — <e.g. Jira ADF → Markdown, semantics preserved>`.
+Use `_(none)_` if none. -->
+
+- <fill in one entry per conversion, or replace with `_(none)_`>
 ````
 
 ### Frontmatter rules
@@ -966,6 +994,16 @@ started.
   is allowed, and the conversion must be annotated in the `format:` meta.
   Augmentation / interpretation goes only into the `Augmentation` section
   or a `> augmented:` blockquote inside the required section.
+- **No template author-guidance in the artifact body.** The Step 5
+  template above carries author guidance in HTML comments
+  (`<!-- ... -->`); preserve those comments when writing the brief but do
+  NOT promote them to body prose. Section headings stay clean — never copy
+  parenthetical reviewer notes onto the heading itself (e.g. emit
+  `## Source Material`, not `## Source Material (verbatim — do not modify)`).
+  Placeholder prose inside angle brackets (`<Background / scope / why
+  now…>`) is intentional and is meant to be replaced with the reporter's
+  actual content; do not strip the angle-bracket placeholders, replace
+  them.
 - If the tracker MCP is not connected, do not guess — ask the user to paste
   the body or skip the source.
 - If a URL fetch fails or hits an auth wall, do not guess — ask for a