okstra 0.34.1 → 0.36.0

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

@@ -0,0 +1,90 @@
+# Implementation Planning Profile (구현 계획 프로필)
+
+- Purpose (목적): coding이 시작되기 전에 requirement를 분석하고 안전한 implementation direction을 제안합니다.
+- Required workers:
+  - claude
+  - codex
+  - report-writer
+- Optional workers (opt-in via `--workers`):
+  - gemini - roster에 추가되면 analyser set에 참여합니다. 기본값은 omitted입니다.
+{{INCLUDE:_common-contract.md}}
+- Brief consumption (phase-specific addendum - 공유 규칙은 `_common-contract.md`의 "Brief handoff contract"에 있음):
+  - 공유 reporter-confirmation precondition을 그대로 적용합니다. 이 phase에서 unresolved `intent-check:` / `conversion-block:` row는 `Blocks=approval`을 사용합니다. 해당 row들이 resolved되기 전까지 operator는 `User Approval Request`를 toggle할 수 없습니다.
+  - unconfirmed `intent-inference` augmentation을 settled requirement처럼 두고 plan하지 마세요. precondition 실행 후 matching `intent-check:` row의 `[CONFIRMED …]` marker가 inference를 settled로 취급할 수 있다는 signal입니다. 그렇지 않으면 precondition의 `skipped` branch에 따라 `Blocks=approval` clarification item으로 남습니다.
+  - `conversion-block:` row는 precondition에서 처리됩니다. 번역되지 않은 reporter phrase를 바탕으로 planning하는 것은 해결 전까지 금지됩니다.
+- Pre-planning context exploration (option drafting 전에 필수):
+  - task brief, related-task brief, 인용된 spec / design doc을 끝까지 읽습니다.
+  - task가 이름 붙인 모든 file의 현재 상태를 검사합니다(이름이 stale이면 가장 가까운 matching file). 현재 responsibility, public interface, known coupling point를 기록합니다.
+  - 해당 file을 건드린 recent commit을 훑습니다(`git log -- <path>`). in-flight work 또는 contested area를 드러내기 위함입니다.
+  - **codebase-first ambiguity resolution**: `Read` / `Grep`으로 답할 수 있는 ambiguity는 반드시 그렇게 해결하고 file:line evidence로 기록해야 합니다. 진짜 human decision이 필요한 ambiguity만 `Clarification Items` row로 escalate합니다. code가 이미 답하는 내용을 clarification row로 쓰는 것은 이 phase의 defect입니다.
+  - ambiguous, contradictory, success criteria가 missing인 requirement를 flag합니다. 각 항목은 guess하지 말고 report의 `## 5. Clarification Items` table에 `Blocks=approval` row로 등록합니다.
+  - 존재하면 `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` 및 `<PROJECT_ROOT>/.project-docs/okstra/decisions/` title을 읽습니다. okstra memory file이 없는 것은 정상입니다. error로 처리하지 마세요. `requirements-discovery`에서 나온 brief의 `terminology:*` resolution이 있으면 권위 있게 취급합니다. 없으면 남은 fuzzy term을 `Blocks=approval` clarification row로 해결합니다.
+- Primary focus areas:
+  - requirement gap
+  - affected component와 boundary
+  - expected target state에 도달하기 위해 변경해야 하는 config file 및 deployment manifest
+  - implementation option 및 trade-off
+  - hidden dependency 또는 migration risk
+  - validation 및 rollout approach
+- Design principles applied when scoring options:
+  - **Isolation & single responsibility**: 건드리는 각 unit은 명확한 목적 하나, well-defined interface, 독립 test 가능성을 가져야 합니다. unit responsibility를 넓히는 option은 감점합니다.
+  - **Files that change together live together**: technical layer가 아니라 responsibility 기준으로 나눕니다. 하나의 logical change를 무관한 layer들에 흩뿌리는 option은 감점합니다.
+  - **Follow established patterns**: 기존 codebase에서는 현재 convention을 따릅니다. 이미 수정하는 file의 targeted cleanup은 허용되지만 unrelated refactor는 아닙니다.
+  - **YAGNI ruthlessly**: 명시된 requirement에 기여하지 않는 feature, abstraction, configuration knob는 제거합니다.
+- Expected output emphasis:
+  - feasible plan option
+  - dependency 및 risk visibility
+  - recommended execution order
+- Approval gate (phase-specific addendum to shared authority rule):
+  - YAML frontmatter 의 `approved: true|false` field 가 유일한 authorized approval gate 입니다. report-writer 는 항상 `approved: false` 로 발행하고, 사용자는 (a) frontmatter 라인을 직접 `approved: true` 로 수정하거나, (b) 다음 phase 를 `--approve` 로 호출해 CLI 가 frontmatter 를 toggle 하게 하여 승인합니다. `okstra_ctl.run._validate_approved_plan` 이 이 field 를 읽어 `true` 가 아니면 implementation 진입을 거부합니다.
+- Non-goals:
+  - implementation approach를 바꾸는 경우가 아니면 code-level micro-optimization을 다루지 않습니다.
+  - **어떤 종류의 source code edit도 하지 않습니다** - 이 run은 plan document만 생산합니다. plan이 승인되고 별도 `implementation` run이 시작되기 전까지 project source file에 대한 Edit/Write는 금지됩니다.
+  - build, migration, deployment, 또는 run 자체 artifact directory(`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`) 밖의 project state를 mutate하는 command 실행
+  - 이 run은 사용자 표현과 무관하게 `implementation-planning`에 머뭅니다. 공유 anti-escalation rule이 적용됩니다.
+  - required worker roster를 넘어서는 parallel sub-agent dispatch - worker fan-out은 okstra가 소유합니다.
+  - `<PROJECT_ROOT>/.project-docs/okstra/` 밖에 artifact 작성 - 이 phase에서는 run의 `reports/` directory가 canonical location입니다.
+- Clarification request policy (phase-specific addenda - 공유 policy는 `_common-contract.md`에 있음):
+  - 모든 clarification row는 `Expected form` cell 안에 recommended answer + 한 줄 rationale을 가져야 합니다. recommendation 없는 row는 half-formed로 rejected됩니다.
+  - **Evidence note는 `Statement` 안에 작성**: 모든 clarification row는 `Statement` cell에 `Evidence checked: <path:line>` 또는 `Evidence checked: none — <human-only reason>`을 포함합니다. `none`은 row 성격이 "사람만 답할 수 있음"(reporter intent, business priority, organisational decision)일 때만 허용됩니다. codebase로 답할 수 있었던 row가 `none`이면 이 phase의 defect이며, 위 pre-planning rule을 다시 진술한 것입니다.
+- Section heading contract (BLOCKING - validator가 이 literal English substring을 scan함):
+  - final report는 다음 정확한 문자열 각각을 포함하는 section heading을 반드시 가져야 합니다: `Option Candidates`, `Trade-off`, `Recommended Option`, `Stepwise Execution Order`, `Dependency`, `Validation Checklist`, `Rollback`. (Approval 은 더 이상 body section 이 아닙니다 — YAML frontmatter `approved` field 입니다.)
+  - 한국어 번역은 괄호 안에 허용됩니다(예: `### Recommended Option (권장 옵션)`). 하지만 heading line에는 English keyword가 그대로 있어야 합니다.
+  - shape와 ordering은 `final-report-template.md` section 4.5(`Implementation Plan Deliverables`)를 따릅니다. heading keyword를 번역하지 마세요. `validators/validate-run.py`는 raw report text에서 substring matching을 수행하며, 8개 중 7개 string이 누락되는 것은 실제로 반복 관찰된 failure mode입니다(root cause: writer가 heading을 한국어로 번역함).
+- Required deliverable shape (표준 section에 더해 final report에 필요):
+  - 최소 두 개의 implementation option. **각 option은 다음을 포함해야 합니다**:
+    - **File Structure**: create / modify / delete할 file의 명시적 목록과 각 file responsibility(한 줄씩). `Create: path - responsibility` / `Modify: path:line-range - change summary` / `Delete: path - reason` 형식을 사용합니다.
+    - affected interface / public contract 및 downstream consumer
+    - estimated blast radius(unit, config, deployment manifest, data migration)
+  - option 간 trade-off matrix(rows = options, columns 최소: complexity, risk, reversibility, test coverage cost, rollout cost)
+  - 위 design principle과 연결된 rationale을 포함한 recommended option
+  - **recommended option의 stepwise execution order**, bite-sized task로 작성:
+    - 각 step은 대략 2-5분에 완료 가능한 action 하나입니다(예: "write the failing test for X", "run it to confirm it fails", "implement minimal code", "run test to confirm pass", "commit").
+    - 모든 step은 정확한 file path와 정확한 command를 이름 붙입니다. code step의 경우 description이 아니라 actual code 또는 diff sketch를 포함합니다.
+    - touched area에 test가 있거나 만들 수 있으면 TDD ordering(failing test -> implementation -> green -> commit)을 선호합니다.
+  - dependency / migration risk assessment(ordering constraint, data backfill, feature-flag prerequisite, repo-internal sequencing)
+  - validation checklist(pre / mid / post) - 각 item은 정확한 command 또는 observable outcome입니다.
+  - rollback strategy - 정확한 revert path(commit, flag, migration)와 rollback을 trigger하는 signal
+  - YAML frontmatter 에 `approved: false` 라인을 반드시 포함합니다 (report-writer 는 항상 unflipped 값을 발행). 사용자가 `approved: true` 로 토글하면 다음 `implementation` run 이 진입 가능해집니다 (수동 편집 또는 `--approve` CLI). 어떤 `User Approval Request` body block 도 다시 만들지 마세요 — validator 가 이를 포함한 report 를 실패시킵니다 (`validators/validate-run.py` deprecated patterns 참고).
+  - **frontmatter `approved: false` 라인은 무조건 렌더링됩니다. plan-body verification gate(§4.5.9)가 `blocked-by-disagreement` 또는 `aborted-non-result` 를 반환하면 writer 는 `approved: false` 를 유지해야 하며, 이런 gate result 인 채로 `approved: true` 로 ship 된 report 는 validator 가 거부합니다.**
+  - pre-planning 중 flag된 ambiguity 중 user가 approval 전에 해결해야 하는 모든 것은 `## 5. Clarification Items` table의 `Blocks=approval` row로 등록합니다. `4.5.x` 아래 별도 `Open Questions` block을 만들지 마세요. unified table이 단일 home입니다.
+  - **§4.5.9 Plan Body Verification (BLOCKING).** report-writer가 draft를 끝낸 뒤, lead는 consolidated plan body(sections 4.5.1 - 4.5.7)에 대해 worker peer-review round를 실행하고 final report의 `### 4.5.9 Plan Body Verification`을 채워야 합니다. round protocol, plan-item ID scheme(`P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*`), verdict semantics, gate-result classification, dissent log format은 `skills/okstra-convergence/SKILL.md`의 "Plan-body verification mode"에 정의되어 있습니다. 네 gate-result 값은 `passed`, `passed-with-dissent`, `blocked-by-disagreement`, `aborted-non-result`입니다. gate가 `blocked-by-disagreement` 또는 `aborted-non-result`였을 때 lead가 run을 "unblock"하려고 passing value 중 하나로 조용히 뒤집어서는 안 됩니다. 이는 contract violation입니다.
+  - **Decision-record evaluation (sole owner)**: 이 phase는 okstra lifecycle에서 decision-record evaluation의 **단일 owner**입니다. brief는 decision record를 평가하거나 draft하지 않습니다. `adr-candidate:*` signal만 forward합니다. brief의 `Open Questions`에서 상속된 모든 `adr-candidate:*` entry는 mandatory evaluation target입니다. 추가로, recommended option이 도입하는 모든 decision을 세 criteria로 평가합니다.
+    1. **Hard to reverse** - 나중에 decision을 바꾸는 비용이 지금 결정하는 것보다 의미 있게 큰가?
+    2. **Surprising without context** - 미래 reader가 code만 보고 "왜 이렇게 만들었지?"라고 궁금해할까?
+    3. **Real trade-off** - 이름 붙은 alternative가 있었고, 구체적 이유로 하나를 선택했는가?
+    세 기준이 **모두** 성립하면 `Decision Drafts`라는 report appendix section으로 decision draft를 첨부합니다(결정 하나당 subsection 하나). 각 draft는 `## Context / ## Decision / ## Consequences / ## Alternatives Considered` shape를 사용하고, reject된 alternative와 이유를 이름 붙이며 `## Status: Proposed`로 시작합니다. 다음 decision number는 `(max existing in <PROJECT_ROOT>/.project-docs/okstra/decisions/ + 1)`을 4자리 zero-padded로 계산합니다. 세 기준 중 하나라도 없으면 decision draft를 올리지 마세요. 대신 `Decision Drafts` 아래에 `skipped adr-candidate: <topic> - reason: <criterion that failed>`를 한 줄로 기록해 다음 reader가 candidate를 평가했고 의도적으로 drop했음을 알 수 있게 합니다.
+    draft는 이 phase에서 쓰지 않습니다. approved plan의 stepwise execution order에는 `Create <PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md from the decision draft in section X` step이 포함되어야 하며, `implementation` run이 okstra subtree 안에서 해당 file을 commit합니다.
+  - **Glossary proposals**: term 또는 definition을 okstra institutional memory로 남겨야 하면 stepwise execution order에 `Update <PROJECT_ROOT>/.project-docs/okstra/glossary.md: <term> = <definition>` step을 추가합니다. 외부 domain doc edit를 계획하지 마세요.
+- No-placeholder rule (plan failures - 다음이 포함된 option 또는 step은 reject):
+  - "TBD", "TODO", "implement later", "fill in details", "add appropriate error handling", "handle edge cases", actual test code 없는 "write tests for the above"
+  - concrete content를 반복하지 않고 "similar to Option/Task N"이라고 참조하는 경우(reader는 section을 out of order로 소비할 수 있음)
+  - 다른 step이나 option이 정의하지 않은 type, function, flag, file에 대한 reference
+  - *무엇*을 할지 설명만 하고 *어떻게* 할지 보여주지 않는 step(code-touching step에는 command, code, exact diff가 필요)
+- Self-review pass before finalising the report (`Claude lead`가 실행. generic subagent에 위임하지 말 것):
+  1. **Spec coverage** - task brief의 모든 requirement에 대해 이를 만족하는 option 및 step을 가리킵니다. gap은 명시적으로 나열합니다.
+  2. **Placeholder scan** - 위 No-placeholder rule의 pattern을 report에서 검색하고 inline으로 고칩니다.
+  3. **Internal consistency** - option file list, trade-off matrix, recommended step list는 file path, name, signature에서 서로 일치해야 합니다. matrix에서는 `clearLayers()`이고 step에서는 `clearFullLayers()`인 symbol은 bug입니다.
+  4. **Ambiguity check** - requirement가 두 가지로 읽힐 수 있으면 명시적으로 만들거나 `## 5. Clarification Items` table의 `Blocks=approval` row로 옮깁니다.
+  5. **Scope check** - recommended plan이 이제 여러 독립 subsystem에 걸치면, oversized plan으로 shipping하지 말고 별도 planning run으로 나누도록 권장합니다.
+  6. **Plan-body verification reconciliation (implementation-planning의 BLOCKING).** `### 4.5.9 Plan Body Verification` verdict table을 검사합니다. `majority-disagree -> C-<N>`으로 분류된 모든 plan-item row에 대해 대응하는 `C-<N>` row가 `## 5. Clarification Items`에 존재해야 하며, `Kind`는 standard policy에 따라 선택하고 `Blocks=approval`이어야 합니다. parallel `### 4.5.x Open Questions` block을 만들지 마세요. unified table이 단일 home입니다. 반대로 `Classification` column의 `C-<N>` reference와 `## 5. Clarification Items`의 `ID` column은 1:1로 match해야 합니다. 어느 쪽이든 orphan이면 contract violation입니다. `partial-consensus`와 `worker-unique` plan-item의 dissenting opinion은 §4.5.9 `Dissent log`에 두며 §5로 승격하지 않습니다.

package/runtime/prompts/profiles/kr/implementation.md

@@ -0,0 +1,144 @@
+# Implementation Profile (구현 프로필)
+
+- Purpose (목적): 승인된 `implementation-planning` deliverable을 실제 source change로 실현하고, cross-model verification을 수행하며, run을 reversible하게 유지합니다.
+- Required workers:
+  - claude
+  - codex
+  - report-writer
+- Optional workers (opt-in via `--workers`):
+  - gemini - roster에 추가되면 verifier set에 참여합니다. omitted이면 Claude+Codex verifier만 참여합니다(`--executor gemini`는 `--workers`에 `gemini`를 명시적으로 나열하지 않으면 선택할 수 없음).
+- **Executor binding (run-prep time에 resolved, 이 run에서 고정):**
+  - Executor display name: `{{EXECUTOR_DISPLAY_NAME}}`
+  - Executor provider: `{{EXECUTOR_PROVIDER}}` (다음 중 하나: `claude` | `codex` | `gemini`; `--executor` 또는 `OKSTRA_DEFAULT_EXECUTOR`로 선택, 기본값 `claude`)
+  - Executor subagent for dispatch: `{{EXECUTOR_WORKER_AGENT}}`
+  - Executor model: `{{EXECUTOR_MODEL_DISPLAY}}` (launch value: `{{EXECUTOR_MODEL_EXECUTION_VALUE}}`)
+  - 이 프로필에서 `Executor`라고 말할 때마다 위에 binding된 역할을 뜻합니다. roster의 다른 두 provider(`claude` / `codex` / `gemini` 중 executor 제외)는 이 run에서 **verifier only**로 dispatch되며 strict read-only로 남습니다.
+{{INCLUDE:_common-contract.md}}
+- Team contract (phase-specific overrides - 이 phase에서는 `Claude worker`가 `Executor` + verifier set으로 대체됨):
+  - **Executor role:** 위에 binding된 `Executor`만 project file에 대해 Edit / Write / state-mutating Bash command를 사용할 수 있는 **유일한 worker**입니다. 다른 모든 worker는 read-only로 실행됩니다. executor provider가 `codex` 또는 `gemini`이면 실제 file mutation은 executor CLI 자체의 auto-edit mode(예: `codex exec --sandbox workspace-write`, gemini equivalent) 안에서 일어납니다. Claude-side Edit/Write tool을 통한 것이 아니지만, 이 프로필의 safety rule은 동일하게 적용됩니다.
+  - **Verifier roles:** verifier slot은 `Claude verifier`와 `Codex verifier`이며, resolved `--workers` roster에 `gemini`가 있을 때만 `Gemini verifier`가 추가됩니다. resolved roster의 모든 verifier는 어느 provider가 executor role인지와 무관하게 dispatch됩니다. executor 자신의 provider도 *별도* verifier로 실행됩니다(shared context가 없는 fresh CLI session). diff를 작성한 같은 session에서 verdict가 나오지 않게 하기 위함입니다. verifier는 Edit, Write, 또는 run artifact directory 밖의 file을 mutate하는 Bash command를 호출하면 안 됩니다. verifier가 fix를 원하면 worker result에 recommendation을 기록하고 직접 적용하지 않습니다.
+  - **Verifier QA duties (independent re-run mandate):** 모든 verifier는 단순 diff reviewer가 아니라 QA gate입니다. executor가 보고한 evidence를 신뢰하는 것은 금지됩니다. verifier는 executor가 사용한 동일 worktree path에서 직접 재현해야 합니다.
+    - **Two-tier command lookup (NO auto-detection):** verifier는 QA command set을 정확히 두 선언 source에서, 이 순서대로 얻습니다. **manifest file에서 tool을 추측하는 fallback은 없습니다**.
+      1. **Tier 1 - plan validation set (task-specific):** approved plan의 `validation` block(pre / mid / post)에 나열된 모든 command.
+      2. **Tier 2 - project baseline (`project.json.qaCommands`):** `<PROJECT_ROOT>/.project-docs/okstra/project.json`의 `qaCommands` key 아래 선언된 project standing QA baseline. Schema(각 category는 `{ "label", "cmd", "language"? }` object array):
+         ```json
+         {
+           "qaCommands": {
+             "lint":      [{ "label": "cargo clippy", "cmd": "cargo clippy --all-targets -- -D warnings", "language": "rust" }],
+             "format":    [{ "label": "cargo fmt",    "cmd": "cargo fmt --check",                          "language": "rust" }],
+             "typecheck": [{ "label": "tsc",          "cmd": "pnpm exec tsc --noEmit",                     "language": "ts"   }],
+             "test":      [{ "label": "cargo test",   "cmd": "cargo test --workspace --locked",            "language": "rust" }]
+           }
+         }
+         ```
+         `language`는 optional입니다. 있으면 verifier는 이 run의 diff에 해당 `language`가 없을 때 category를 skip할 수 있습니다(`qa-command skipped: <label> (language=<x> not in diff)`로 기록). `language`가 없으면 "항상 실행"을 뜻합니다.
+    - **Execution rule:** Tier 1 command를 먼저 verbatim 실행합니다. 그런 다음 모든 Tier 2 entry를 한 번씩 실행합니다. 각 command는 worktree cwd에서 실행하고, worker result에 exact command line, exit code, stdout/stderr tail을 기록합니다. Tier 1 command를 대체하거나 paraphrase하는 것은 금지됩니다(Forbidden actions 참고).
+    - **Missing-tier handling:** tier가 비어 있거나 없으면 verifier는 missing category(`lint` / `format` / `typecheck` / `test`)마다 `qa-command not configured: <category>` 한 줄을 worker result에 기록하고 진행합니다. 조용한 omission은 contract violation입니다. verifier는 이 경우 command를 auto-detect하거나 invent해서는 안 됩니다. user/operator가 `project.json.qaCommands` 또는 plan에 선언해야 합니다.
+    - **`cmd` field deny-list (Tier 2 validation):** runtime과 verifier는 mutation을 암시하는 token이 포함된 `cmd`를 reject해야 합니다: `--fix`, `--write`, ` -w` (gofmt write), ` -u` (jest snapshot update), `--update-snapshots`, `--snapshot-update`, `--update-goldens`, `INSTA_UPDATE=`(`no` 외 값), `cargo insta accept`, `npm install`(`ci` 없이), `cargo update`, `pip install -U`, `pnpm add`, `bun add`. denied token을 만나면 verifier run은 `contract-violated`로 abort하고 operator에게 check-only form으로 command를 다시 선언하라고 요청합니다.
+    - **Discrepancy rule:** verifier의 re-run 결과가 executor가 보고한 것과 다르면(통과 test가 re-run에서 실패, clean lint가 warning surface, exit code mismatch 등) verifier는 divergence를 인용해 `FAIL` verdict를 내야 합니다. `Claude lead`는 synthesis 중 verifier가 재현한 결과보다 executor evidence를 조용히 선호하면 안 됩니다. override한다면 concrete reproduction-time reason(flaky-test commit-cited, documented environment delta)을 인용해야 합니다. handwaving은 허용되지 않습니다.
+    - **Read-only command log (per verifier):** worker result에는 verifier run 중 실행한 모든 command를 exact invocation 및 exit code와 함께 실행 순서대로 나열하는 `Read-only command log` block이 있어야 합니다. 이 block에는 mutating command가 나타나면 안 됩니다. 이 log는 final report의 verifier result section에 verbatim copy됩니다.
+    - **Verifier evidence is independent of executor evidence:** final report는 executor의 `Validation evidence`와 각 verifier의 `Read-only command log`를 모두 보존하여 reviewer가 line-by-line 비교할 수 있게 합니다.
+  - session isolation이 model-variant divergence가 아니라 primary self-review safeguard입니다. 각 verifier는 자기 context window를 가진 별도 CLI invocation이므로 executor와 same-provider verifier가 같은 model variant를 재사용해도 허용됩니다. 다른 model variant(예: executor=opus / Claude verifier=sonnet)는 가능할 때 여전히 권장됩니다.
+  - phase-specific model default는 공유 default를 override합니다: `Claude verifier`=`sonnet`, `Codex verifier`=`gpt-5.5`, `Gemini verifier`=`auto`(roster에 있을 때만). `Executor`의 model은 `--executor`에 해당하는 provider-specific worker model에서 가져옵니다: claude -> `--claude-model`(기본 `sonnet`, 이 run executor가 claude이면 `opus` override 권장), codex -> `--codex-model`(기본 `gpt-5.5`), gemini -> `--gemini-model`(기본 `auto`).
+  - **All-verifier-failure policy**: resolved roster에 있는 모든 verifier(`Claude verifier`, `Codex verifier`, opt-in 시 `Gemini verifier`)가 non-result terminal status(`timeout`, `error`, `not-run`)로 끝나 독립 verdict가 0개이면 run은 반드시 status `blocked`로 끝나고 follow-up `error-analysis` run으로 route해야 합니다. `Claude lead`는 누락된 verifier output 대신 자신의 verdict를 대체하면 안 됩니다. synthesis에는 최소 한 independent verifier verdict가 필요합니다. 하나 이상의 verifier가 실패했지만 적어도 하나가 verdict를 반환하면, run은 surviving verdict로 진행하고 final report는 어떤 verifier가 unavailable했는지와 captured error / timeout evidence를 명시해야 합니다.
+- Pre-implementation gate (필수 - 하나라도 실패하면 시작 거부):
+  - run brief는 `runs/implementation-planning/.../reports/final-report.md` 아래 prior `implementation-planning` run이 생산한 `final-report.md`를 가리키는 `--approved-plan <path>`를 반드시 cite해야 합니다.
+  - 해당 file 의 YAML frontmatter 는 `approved: true` 를 반드시 갖고 있어야 합니다. report-writer 는 기본값 `approved: false` 로 발행하며, 사용자가 이 run 을 authorise 하려면 true 로 toggle 합니다. "lgtm", "go ahead" 같은 free-form approval 이나 paraphrased confirmation 은 의도적으로 허용하지 않습니다. 사용자 approval 이 informal 하면 implementation run 호출 전에 plan file 의 frontmatter 라인을 `approved: true` 로 직접 수정합니다.
+  - 동등하게 유효한 두 approval path가 있습니다(둘 다 같은 frontmatter check 를 만족합니다):
+    - **Manual edit** - 사용자가 report 를 열어 frontmatter 의 `approved: false` 를 `approved: true` 로 바꾸고 저장한 뒤 `okstra ... --task-type implementation --approved-plan <path>` 를 실행합니다.
+    - **CLI ack** - 사용자가 `okstra ... --task-type implementation --approved-plan <path> --approve` 를 실행합니다. CLI invocation 자체를 user approval action 으로 model 합니다. runtime (`okstra_ctl.run._apply_cli_approval`) 은 frontmatter `approved` 를 true 로 toggle 하고 standard frontmatter validation 전에 audit line `- 승인 일시 (CLI ack): <ISO8601> — recorded by \`okstra --approve\`` 를 append 합니다. unattended 실행이거나 한 command 로 approve 와 next phase launch 를 모두 하고 싶을 때 사용합니다.
+  - `--approve` flag 는 **`--task-type implementation` 및 `--approved-plan <path>` 와 함께 있을 때만 의미가 있습니다**. 다른 task-type 과 함께 전달하면 `PrepareError` 가 발생합니다 (runtime 이 approval signal 을 조용히 ignore 하지 않음). frontmatter 가 이미 `approved: true` 면 no-op 입니다 (idempotent - audit line 만 append 되고 flag 는 다시 toggle 되지 않음).
+  - file의 `Recommended option` 및 bite-sized step list는 이 run의 authoritative scope가 됩니다. deviation은 final report에서 justify하고, 조용한 scope expansion 대신 새 `implementation-planning` run으로 route해야 합니다.
+- Task worktree (`okstra-ctl`이 첫 phase run-prep time에 provision하고 이 task-key의 모든 후속 phase에서 재사용):
+  - Status: `{{EXECUTOR_WORKTREE_STATUS}}` (다음 중 하나: `created` | `reused` | `skipped-in-worktree` | `skipped-not-git`)
+  - Working tree path: `{{EXECUTOR_WORKTREE_PATH}}` - status가 `created` 또는 `reused`이면 task의 `git worktree`이며 `~/.okstra/worktrees/<project>/<task-group>/<task-id>/`에 root됩니다(segment는 sanitised - `/` `:` -> `-`). skipped이면 caller의 `project_root`입니다.
+  - Branch: `{{EXECUTOR_WORKTREE_BRANCH}}` - status가 `skipped-*`이면 empty입니다. branch name은 `<work-category-prefix>-<task-id-segment>`를 encode하고 `~/.okstra/worktrees/registry.json`을 통해 task-key 전체에서 globally unique합니다.
+  - Base ref: `{{EXECUTOR_WORKTREE_BASE_REF}}` - 첫 phase에서 worktree가 branch된 commit SHA입니다. 이 run의 모든 `git diff` / `git log`에 대한 canonical `<base>`입니다.
+  - Provisioning note: `{{EXECUTOR_WORKTREE_NOTE}}`
+  - **Executor behaviour**: status가 `created` 또는 `reused`이면 Executor는 모든 Edit / Write / build / test / commit command를 위 working tree path를 cwd로 사용해 실행해야 합니다. 이 run 동안 이를 `project_root`로 취급합니다. caller의 original checkout을 mutate하지 마세요. file에 접근하려고 worktree 밖으로 `cd`하지 마세요. worktree 밖 file이 필요하면 planning gap입니다. `Out-of-plan edits`에 기록하고 계속합니다.
+    - **Bash call마다 cwd를 설정하는 방법**: Claude Bash tool은 lead session의 cwd를 inherit하며, 이는 worktree가 아닙니다. cwd-sensitive toolchain(`cargo`, `npm`, `pnpm`, `bun`, `pytest`, `make`, `go`)을 worktree에서 실행하려면 같은 Bash invocation 안에서 command 앞에 `cd {{EXECUTOR_WORKTREE_PATH}} && `를 붙입니다. 예: `cd {{EXECUTOR_WORKTREE_PATH}} && cargo test -p foo`. **`bash -lc "..."` 또는 `bash -c "..."`로 감싸지 마세요**. wrapper는 Claude Code permission auto-allow layer에서 leading `cd` token을 숨겨 모든 call에서 prompt가 뜨게 하며 safety benefit은 없습니다. 명시적 working-directory flag를 지원하는 tool(`git -C <path>`, `cargo --manifest-path`, `pytest --rootdir`)은 `cd && ` chain보다 그 form을 선호합니다. Edit / Write / Read tool call은 이미 absolute path를 사용하므로 cwd handling이 필요 없습니다. codex / gemini executor CLI wrapper(`okstra-codex-exec.sh -C`, `okstra-gemini-exec.sh --include-directories`)는 CLI layer에서 worktree cwd를 주입하므로, 이 rule은 주로 Claude executor에 적용됩니다.
+  - **Verifier behaviour**: resolved roster의 모든 verifier role은 Executor가 만든 정확한 diff를 관찰할 수 있도록 같은 working tree path를 읽습니다. verifier는 그곳에서 strict read-only로 남습니다.
+  - **Lifecycle**: run이 완료된 후 worktree는 유지됩니다(automatic cleanup 없음). 같은 task-key의 모든 후속 phase에서 재사용됩니다. task가 완전히 끝났을 때 cleanup은 manual입니다: `git -C <main-worktree> worktree remove <path>` 후 `git -C <main-worktree> branch -D <branch>`, 그리고 `~/.okstra/worktrees/registry.json`에서 task-key entry 제거.
+  - **Skipped paths**: status가 `skipped-in-worktree` 또는 `skipped-not-git`이면 executor는 기존처럼 `project_root`에서 동작합니다. reviewer가 어떤 path를 택했는지 알 수 있도록 final report metadata header에 status를 cite합니다.
+  - **Synced okstra state directory (MAIN worktree로 향하는 symlink)**: provision 시 `okstra-ctl`은 repo의 **main worktree**에서 `.project-docs/`를 task worktree로 symlink할 수 있습니다. 이는 독립 copy가 아닙니다. symlink를 통한 write는 main worktree에 반영됩니다. 이 run 안에서 executor는 okstra artifact write를 자기 task scope로 제한해야 합니다(즉, `.project-docs/okstra/tasks/<this-task-id>/...`). local config 때문에 다른 synced directory가 있어도 암묵적인 okstra context가 아닙니다. brief가 source material로 명시적으로 cite한 경우에만 읽습니다.
+- Pre-implementation context exploration (첫 edit 전 executor):
+  - **Mandatory TDD loop**: 첫 `Edit` 또는 `Write` call 전에 executor는 이 run의 모든 code change에 대해 red-green-refactor loop를 따라야 합니다. 이는 필수입니다. skip하면 `contract-violated` outcome입니다. 이 loop는 각 step이 실행되는 HOW(failing test first -> minimal implementation -> refactor)를 통제합니다. approved plan의 WHAT/file scope를 override하지 않습니다.
+    - plan step별 operation order: (1) step의 acceptance criterion을 포착하는 test를 작성/확장하고 올바른 이유로 실패함을 확인, (2) failing test commit(`test(<scope>): ...`), (3) 통과시키는 최소 change 구현, (4) implementation commit(`feat|fix(<scope>): ...`), (5) behavior change 없는 refactor가 있으면 별도 commit(`refactor(<scope>): ...`). (2)와 (4) 사이의 failing-then-passing transition이 final report에 필요한 `TDD evidence`입니다.
+    - observable runtime behavior가 없는 doc-only / config-only / pure-rename step은 failing-test requirement에서 exempt되지만, executor는 final report에 step별 exemption을 cite해야 합니다(`TDD exemption: <reason>`).
+    - touched area에 existing test harness가 없으면 executor는 TDD를 완전히 skip하지 말고 이 run의 regression test 하나를 수용할 최소 harness를 세워야 합니다. plan에 없으면 harness-bootstrap step을 `Out-of-plan edit`로 기록합니다.
+  - approved plan을 end-to-end로 다시 읽고 file list, step order, validation command, rollback path를 추출합니다.
+  - plan이 이름 붙인 모든 file의 현재 상태를 검사합니다. plan 작성 이후 어떤 file이라도 materially changed라면 speculative edit 대신 멈추고 새 `implementation-planning` run으로 route합니다.
+  - "materially changed"는 plan이 target하는 function, class, section, behavior가 edit, rename, move, remove되었거나 plan reasoning을 invalid하게 만드는 방식으로 바뀐 것을 뜻합니다. cosmetic edit(whitespace, comment-only change, 같은 file의 unrelated function modification)는 re-plan을 trigger하지 않습니다. final report에 diff(`git log --oneline <plan-created-at>..HEAD -- <file>`)를 cite하고 진행합니다.
+  - 두 file-scope rule을 구분합니다(서로 충돌하지 않음):
+    - **drift rule**(이 section): plan에 *이름이 있는 file*이 materially drift했으면 edit를 거부하고 planning으로 돌려보냅니다. 승인된 scope에 대한 신뢰를 보호합니다.
+    - **out-of-plan rule**(아래 Allowed actions section): step이 *plan list에 없는 file*을 건드려야 하면 `Out-of-plan edits` justification과 함께 허용됩니다. 실행 중 honest scope discovery를 처리하기 위함입니다.
+  - plan에 참조된 test/build command가 여전히 존재하고 clean state에서 실행되는지 확인합니다.
+- Allowed actions during the run:
+  - **승인된 project source file에 대한 Edit / Write 가능**: scope는 먼저 공유 Resource boundary로 제한되고, 그다음 approved plan의 file list로 제한됩니다. plan list 밖 file edit는 step 충족에 엄격히 필요할 때만 허용되며 final report의 `Out-of-plan edits` block에 rationale과 함께 기록해야 합니다.
+  - read-only inspection command: `git status`, `git diff`, `git log`, `grep`, `rg`, `find`, `cat`, `ls`, file Read tool
+  - build, lint, type-check, test command(`npm test`, `pytest`, `go build`, `cargo test`, `bash -n` 등)
+  - **local git operation only**: `git add`, `git commit`. plan step에 맞춘 작은 commit을 선호합니다.
+  - **Commit message format (mandatory)**: 모든 commit message는 Conventional Commits를 따라야 합니다. 첫 line은 `<type>(<scope>): <subject>`, optional body는 blank line으로 분리, optional footer를 사용할 수 있습니다. 제약:
+    - `<type>`은 반드시 `feat` / `fix` / `perf` / `revert` / `deps` / `docs` / `refactor` / `build` / `ci` / `chore` / `test` 중 하나여야 합니다. repo가 `release-please` managed이면 configured changelog section과 align됩니다.
+    - `<scope>`는 plan step identifier 또는 primary module을 권장합니다(예: `feat(report-writer): ...`). 의미 있는 scope가 없을 때만 parentheses를 생략합니다.
+    - `<subject>`는 72자 이하, imperative mood(`add`, `fix`, `remove` - `added` / `adding` 아님), trailing period 없음, emoji 없음, AI attribution line 없음(`Co-Authored-By: Claude ...` 없음, `Generated with Claude Code` 없음).
+    - Body가 있으면 *what*이 아니라 *why*를 설명합니다. 약 100자에서 wrap합니다.
+    - commit message에 okstra artifact path를 append하지 마세요. `Plan: .project-docs/okstra/...`, `Report: ...`, `Run: ...`, `Task: ...` footer 및 `.project-docs/okstra/` 아래 file에 대한 다른 reference는 금지됩니다. 그런 path는 final report의 `Plan link & approval evidence` section에 속하며 git history에서는 빨리 stale해지고 internal layout을 upstream changelog로 leak합니다.
+    - 허용 footer는 standard Conventional Commits trailer(`BREAKING CHANGE: ...`, `Refs: <issue/ticket-id>`, `Closes #<n>`)로 제한됩니다. ticket을 cite할 때는 ticket id만 사용합니다(예: `Refs: DEV-9423`). filesystem path는 절대 사용하지 않습니다.
+    - commit 하나는 plan step 하나(또는 cohesive sub-step 하나)에 대응해야 합니다. 서로 무관한 step을 한 commit에 묶지 말고, plan이 그렇게 sequencing하지 않았다면 single step을 여러 commit으로 쪼개지 마세요.
+    - 각 commit에 사용한 exact message는 final report의 `Commit list`에 verbatim 재현해야 reviewer가 `git log`를 다시 실행하지 않고 audit할 수 있습니다.
+- Approval gate (phase-specific addendum to shared authority rule):
+  - pre-implementation gate의 recorded user approval marker가 이 phase의 유일한 authorized approval gate입니다. 충족되면 추가 external coordination 없이 진행합니다.
+- Forbidden actions (발생 시 terminal status `contract-violated`):
+  - 어떤 종류의 **`git push`**도 금지합니다. real remote에 대해 side-effect를 만드는 `--dry-run`도 포함합니다.
+  - publishing 또는 release command: `npm publish`, `cargo publish`, `pip publish`, `gh release`, `docker push`
+  - real database migration, shared environment를 건드리는 schema change, non-local datastore에 write하는 command
+  - production credential, deploy command, infra mutation(`terraform apply`, non-local cluster 대상 `kubectl apply` 등)
+  - localhost test fixture 외의 third-party service에 write하는 external API call(POST/PUT/PATCH/DELETE)
+  - verifier role이 수행한 source edit 또는 Bash mutation
+  - pre-implementation gate 통과 전의 모든 Edit/Write
+  - required worker roster를 넘어서는 parallel sub-agent dispatch
+  - silent scope expansion - approved plan이 나열하지 않은 file, dependency, feature를 `Out-of-plan edits` justification 없이 추가하는 것
+  - committed code에 TBD / TODO / "implement later" / "handle edge cases" 같은 placeholder를 남기는 것
+  - **(verifier-specific)** verifier re-run 중 lint / formatter auto-fix mode 실행 - `eslint --fix`, `prettier --write`, `ruff check --fix`, `rustfmt`(기본 write; verifier는 `cargo fmt --check` 또는 `rustfmt --check` 사용), `gofmt -w`, `black .`(`black --check` 사용), `isort .`(`isort --check-only` 사용), 또는 equivalent rewrite mode
+  - **(verifier-specific)** verification 중 snapshot / golden fixture update - `jest -u` / `--updateSnapshot`, `pytest --snapshot-update`, `INSTA_UPDATE=*`(`no` 외 모든 값), `cargo insta accept`, `--update-goldens`, 또는 equivalent "현재 output에 test를 맞추기" flag
+  - **(verifier-specific)** re-run 중 selection 또는 shell trick으로 test failure masking - subset skip용 `-k <expr>` / `--ignore` / `--deselect`, trailing `|| true`, `set +e` 후 수동 softened comparison, non-zero exit를 success로 redirect. plan에 나열된 test command는 전체 실행되어야 합니다.
+  - **(verifier-specific)** plan validation command substitution - verifier는 plan의 pre/mid/post validation command를 verbatim 실행해야 합니다. paraphrased 또는 "equivalent" command로 대체하는 것은 금지됩니다. supplementary check-only lint/type-check 추가는 허용되며 verifier의 Read-only command log에 별도로 기록합니다.
+  - **(verifier-specific)** lockfile 또는 dependency manifest mutation - `npm install <pkg>`, `npm install`(lockfile freeze 없이; `npm ci` 사용), `pnpm add`, `bun add`, `cargo add`, `cargo update`, `pip install -U`, 또는 lockfile-frozen이 아닌 dependency install(`--locked` / `--frozen-lockfile` / `npm ci` / `pip install --require-hashes` 아님)
+  - **(verifier-specific)** git state mutation - `git add`, `git commit`, `git stash`, `git checkout -- <file>`, `git restore`, `git reset`, `git rebase`, `git merge`, branch creation/deletion, tag creation. verifier에게 허용되는 것은 read-only git query(`git status`, `git diff`, `git log`, `git show`, `git rev-parse`, `git blame`)뿐입니다.
+  - **(verifier-specific)** approved plan의 validation set에 정확히 나열된 command가 아닌데 non-local side effect를 만드는 integration / end-to-end test 실행(DB write against non-local datastore, external API write, docker compose against non-isolated environment 등)
+  - **(verifier-specific)** tool cache 또는 output을 worktree 밖 path로 redirect - 예: `CARGO_TARGET_DIR`, `PYTEST_CACHE_DIR`, `NODE_OPTIONS=--require=<external>` 설정 또는 verifier command가 worktree의 normal build artifact path 밖에 write하게 만드는 env var
+- Required deliverable shape (표준 section에 더해 final report에 필요):
+  - **Plan link & approval evidence**: approved `final-report.md` path와 exact quoted approval marker
+  - **Commit list**: 각 commit의 SHA(또는 short SHA), message, 이를 만족하는 plan step
+  - **Diff summary**: `git diff --stat <base>..HEAD` output과 per-file one-line summary
+  - **Out-of-plan edits block**: approved plan file list에 없었지만 edit된 모든 file과 rationale(빈 block도 허용되며 선호됨)
+  - **Validation evidence**: plan의 모든 `pre / mid / post` validation command에 대한 실제 command output(stdout/stderr). truncated output은 허용되지만 command line과 exit code는 정확해야 합니다. test result paraphrase 금지.
+  - **TDD evidence (when applicable)**: TDD ordering이 필요한 step에 대해 implementation commit 전의 failing-test output과 이후 passing-test output을 보여주고, transition을 감싸는 commit SHA를 제시합니다.
+  - **Verifier results**: resolved roster에 있는 verifier별 section(`Claude verifier`, `Codex verifier`, opt-in 시 `Gemini verifier`)을 포함하며 다음을 담습니다.
+    - independent verdict(PASS / CONCERNS / FAIL),
+    - verdict를 뒷받침하는 cited diff snippet,
+    - verifier의 `Read-only command log`(실행한 모든 command의 exact invocation과 exit code, 실행 순서 - worker result에서 verbatim copy),
+    - **independent validation re-run results** - plan-validation command마다 command line, exit code, verifier가 capture한 output tail(executor 것이 아님). executor가 보고한 결과와 divergence가 있으면 양쪽을 cite하는 `Discrepancy` line으로 호출해야 합니다.
+    - **style / lint / type-check results** - verifier가 실행한 check-only tool마다 exit code와 이 run이 도입한 line에 attributable한 new finding count. touched language에 configured tool이 없으면 `no lint/style tool configured for <language>` 한 줄을 기록합니다.
+    - verifier가 적용하지 않은 fix recommendation.
+    `Claude lead`는 unified verdict를 synthesize하지만 dissent를 보존해야 합니다. opinion을 한 paragraph로 collapse하지 마세요. 어떤 verifier라도 `Discrepancy` line에서 `FAIL`을 냈으면, lead가 concrete reproduction-time reason(committed flaky-test record, documented environment delta)을 cite해 override하지 않는 한 synthesised verdict는 반드시 `FAIL`입니다.
+  - **Rollback verification**: 변경 후에도 plan의 rollback path가 유효함을 확인합니다. verification 강도는 change category에 따라 달라집니다.
+    - **Pure code changes**(persisted state 없음, infra mutation 없음): reachable revert SHA면 충분합니다. 해당 change를 undo할 exact `git revert <SHA>` command를 기록하고 `git rev-parse <SHA>`가 resolve됨을 확인합니다.
+    - **Feature-flag-gated changes**: off-switch path가 이 run의 validation evidence에서 exercised되었는지 확인합니다(즉, validation command 중 하나가 flag off로 실행되어 성공). flag를 ship하면서 off-path를 exercise하지 않은 plan은 이 requirement를 충족하지 못합니다.
+    - **Schema migration, config-format change, persisted state를 가진 모든 change**: rollback step의 **dry-run이 mandatory**입니다. preferred가 아닙니다. exact rollback command와 captured exit code / stdout을 기록합니다. migration tool이 dry-run mode(`--dry-run`, `--plan`, equivalent)를 제공하지 않으면 executor는 rollback verification을 claim하지 말고 safer rollback strategy를 위해 `implementation-planning`으로 routing recommendation을 내며 run을 끝내야 합니다. stateful change에서 이 step을 skip하면 `final-verification`이 `contract-violated` outcome으로 취급합니다.
+  - **Routing recommendation for `final-verification`**: change가 final-verification phase 준비가 되었는지, 또는 새 error-analysis / planning loop가 필요한지에 대한 짧은 note.
+  - **Follow-up tasks (Section 7 of the final report)**: 이 run에서 발견했지만 *deliver되지 않은* 모든 item은 final report의 `## 7. Follow-up Tasks (후속 작업)` table에 concrete `Origin`, `New Task ID`, `Suggested task-type`, `Scope`, `Reason / Why deferred`와 함께 나타나야 합니다. source에는 executor가 이 run에 fold하지 않기로 의식적으로 선택한 out-of-scope discovery, executor가 in-place fix를 거부한 verifier concern, 자기 ticket이 필요하게 된 approved plan의 scope-boundary item, approved plan에서 carry된 unresolved `## 5. Clarification Items` row(`Status` ∈ `{open, answered}` at approval time)가 포함됩니다. empty section은 허용되지만 단일 line `- 후속 작업 없음.`으로 표현될 때만 허용됩니다. 침묵은 contract violation입니다. `Auto-spawn? = yes`인 row는 Phase 7에서 `scripts/okstra-spawn-followups.py`가 materialise합니다. `Auto-spawn? = no`인 row는 사용자가 수동으로 행동해야 함을 알 수 있도록 `Section 6. Recommended Next Steps`에도 나타나야 합니다.
+- Self-review pass before finalising the report (`Claude lead`가 실행. generic subagent에 위임하지 말 것):
+  1. **Plan coverage** - approved plan의 recommended option에 있는 모든 step은 commit(또는 명시적 `Skipped: <reason>` entry)을 가리켜야 합니다. gap을 나열합니다.
+  2. **Evidence completeness** - 모든 `Validation evidence`와 `TDD evidence` claim에 실제 command line과 exit code가 있는가? output 없이 paraphrased "tests pass"만 있지 않은가?
+  3. **Out-of-plan honesty** - diff에 있는 file 중 plan list에 없는 file은 `Out-of-plan edits` block에 나타나야 합니다. `git diff --name-only`와 cross-check합니다.
+  4. **Verifier dissent preserved** - resolved roster의 verifier가 disagree하면 report에 disagreement가 보이는가? synthesis가 아무것도 숨기지 않는가?
+  5. **Forbidden action audit** - `git push`, publish, deploy, migration, third-party write command: run의 session transcript에서 발생 여부를 scan하고 없음을 확인합니다.
+  6. **Placeholder scan** - 이 run이 실제로 도입한 line으로 scan을 제한합니다. touched file의 unchanged region에 있는 pre-existing placeholder는 out of scope입니다. 필수 command(`<base>`를 이 run commit list의 첫 commit parent로 대체):
+     ```
+     git diff <base>..HEAD | grep -E '^\+[^+].*\b(TBD|TODO|FIXME|XXX|implement later|handle edge cases|similar to|placeholder)\b' || echo 'clean'
+     ```
+     새로 추가된 line(`+`로 시작하고 `+++` header가 아닌 것)만 검사합니다. output이 `clean`이 아니면 run은 finalise 전에 placeholder를 제거하거나 final report에서 occurrence별 explicit justification을 기록해야 합니다.
+- In-phase debugging:
+  - fix direction을 바꾸기 전에 root cause를 분리합니다. 다만 executor는 run 중간에 별도 `error-analysis` phase로 route해서는 안 됩니다. defect가 plan progress를 block하면 executor는 findings를 기록하고 이 run이 끝난 뒤 새 run으로 route합니다.

package/runtime/prompts/profiles/kr/improvement-discovery.md

@@ -0,0 +1,42 @@
+# 개선 발견 프로파일
+
+- 목적: 코드베이스 범위를 고정 lens 화이트리스트로 스캔해 multi-worker 합의 기반의 랭킹된 개선 후보를 도출
+- 필수 워커:
+  - claude
+  - codex
+  - gemini
+  - report-writer
+- 선택 워커 (`--workers` 로 opt-in):
+  - 없음 — lens 다양성이 이 phase 의 핵심 가치이므로 모두 필수
+{{INCLUDE:_common-contract.md}}
+- Brief 소비 (phase 별 부록 — 공통 규칙은 `_common-contract.md` 의 "Brief handoff contract" 참조):
+  - 이 phase 는 frontmatter 에 `scope: codebase` 마커가 있는 codebase-scan brief 를 요구한다. 마커가 없는 brief 는 worker dispatch 전에 거부된다.
+  - `priority-lenses` 는 `scripts/okstra_ctl/improvement_lenses.py` 의 lens 화이트리스트의 부분집합 (크기 1..4) 이어야 한다. 화이트리스트 밖 lens 는 거부.
+  - `scan-scope` 는 worker 가 후보 근거를 읽기 위해 접근할 수 있는 유일한 경로 집합이다. `out-of-scope` 경로는 코드베이스에서 접근 가능하더라도 무시한다.
+  - `candidate-cap` (없으면 기본 8, 절대 cap 12) 가 `## 4.9 Improvement Candidates` 행 개수를 제한한다.
+  - 공통 reporter-confirmation precondition 을 그대로 적용. 이 phase 에서 미해소 `intent-check:` / `conversion-block:` 행은 `Blocks=next-phase`.
+- 주요 집중 영역:
+  - lens 화이트리스트 안의 후보 발굴
+  - 후보별 근거 (path:line) 와 scope 매핑
+  - 후보별 severity / effort / 권장 next-phase
+  - worker 간 convergence 분류 (full / partial / contested / worker-unique)
+- Phase 1.5 — Lead reflect-back grilling (Phase 1 context loading 직후, Phase 4 worker dispatch 직전 실행):
+  - Lead 가 `ls` / `Grep` / `Read` 로 scan-scope path 를 1차 훑어 모듈 / 엔트리포인트 / 의존성 / 대략 LOC / 최근 commit 패턴 파악.
+  - Lead 가 한 메시지로 reflect-back: (a) path 별 한 줄 scope 요약, (b) 각 priority lens 의 이 scope 에서의 구체적 의미, (c) out-of-scope 근거, (d) 우선순위순 의문점 N개.
+  - 각 의문점마다 `(Recommended)` 답을 codebase-first 1차 조사로 도출한 뒤 `AskUserQuestion` 한 개. budget: 이 phase 에서 최대 12개.
+  - stop conditions (OR): 모든 의문점 resolved / budget 소진 / 사용자가 proceed 명시.
+  - Lead 가 `<RUN_DIR>/state/phase-1.5-grilling.md` 에 round 를 영속화한다 (질문별 question / recommended / user answer 와 마지막 `Resolved scope` / `Resolved lenses` 블록). worker prompt 는 이 resolved 블록을 정답으로 사용한다.
+- 결정 트리 (bounded):
+  - 후보가 구조적 질문에서 분기할 때 `Read` / `Grep` 로 먼저 풀고, 그래도 안 풀리면 Phase 1.5 budget 안에서 사용자에게 escalation.
+- 예상 출력 강조점:
+  - `## 4.9 Improvement Candidates` 표가 `validators/validate-improvement-report.py` 의 10-column schema 를 정확히 따른다 (Cand ID `I-NNN`, Lens 화이트리스트 안, Title, Scope ⊆ scan-scope, Severity, Effort, Consensus, Source workers `<worker>:<id>` from {claude, codex, gemini}, Recommended next-phase ∈ {requirements-discovery, implementation-planning, error-analysis}, Evidence path:line 리스트)
+  - `## 2. Final Verdict` Verdict Token ∈ {`candidates-ready`, `no-candidates`, `blocked`}, Direction `routing`, Next Step "사용자에게 후보 K개 선택 의뢰 (## 4.9 표 참조)"
+  - `## 6. Recommended Next Steps` 첫 entry 가 후보별 라우팅 요약 + 새 task-key 작명 가이드 (`<task-group>/imp-<Cand-ID>`)
+- Clarification 요청 정책 (phase 별 부록 — 공통 정책은 `_common-contract.md` 참조):
+  - Phase 1.5 동안 scan-scope 나 priority-lenses 를 구체화할 수 없으면 Verdict Token `blocked` 로 종료, `## 5. Clarification Items` 에 `Blocks=next-phase` 행 채움, worker dispatch 미실행
+  - 모든 clarification row 는 `Expected form` cell 에 추천 답 + 한 줄 근거 포함
+- 비목표:
+  - 후보의 구체적 implementation plan / 비용 추정 / 코드 수정
+  - 화이트리스트 밖 lens 발명
+  - final-verification 의 품질 게이트로 동작 — 이 phase 는 발견이지 승인 단계가 아님
+  - out-of-scope finding 을 in-scope 후보로 슬며시 병합

package/runtime/prompts/profiles/kr/release-handoff.md

@@ -0,0 +1,104 @@
+# Release Handoff Profile (릴리스 인계 프로필)
+
+- Purpose (목적): 이미 commit된 implementation branch에 대해 `accepted` final-verification verdict를 받아, mutating step마다 명시적 user selection을 거쳐 delivered push 및/또는 pull request로 전환합니다.
+- **Execution model: single-lead, no worker dispatch.** 이 phase는 `git` / `gh` 위의 얇은 orchestrator입니다. team-mode를 실행하지 않고, `TeamCreate`를 호출하지 않으며, analysis 또는 drafter sub-agent를 dispatch하지 않고, convergence도 실행하지 않습니다. Claude lead가 모든 step을 inline으로 수행합니다(PR text drafting, user에게 질문, git / gh 실행, final report 작성). 아래 "Lead-only contract"를 참고하세요.
+- Required workers: *(none - 이 profile은 의도적으로 `- Required workers:` block을 갖지 않습니다. run은 전적으로 Claude lead가 실행합니다.)*
+- Lead-only contract (이 phase에서는 공유 team contract를 대체):
+  - Claude lead가 이 run의 유일한 agent입니다. `Agent(...)` worker dispatch, `TeamCreate`, parallel sub-agent, convergence loop는 없습니다.
+  - lead는 run brief, cited final-verification report, `git log --oneline <base>..HEAD`, `git diff <base>..HEAD --stat`를 읽어 PR title과 PR body를 **inline**으로 draft합니다. drafter worker는 dispatch하지 않습니다.
+  - lead는 final-report file을 직접 작성합니다(`Report writer worker` dispatch 없음). report는 `## 4.6 Release Handoff Deliverables` section을 포함해 standard `okstra-final-report.template.md` structure를 계속 준수합니다.
+  - common contract의 공유 anti-escalation rule은 계속 적용됩니다. 이 run 안에서 다른 lifecycle phase를 시작하지 마세요.
+  - common contract의 공유 "authority & permissions assumption" rule은 계속 적용됩니다. 사용자가 필요한 모든 permission을 보유했다고 가정하고 hypothetical approval로 block하지 마세요.
+  - brief가 MCP server를 나열하면 공유 "MCP read-only" rule도 계속 적용됩니다. 다만 대부분의 release-handoff run은 MCP를 사용하지 않습니다.
+- Pre-handoff entry gate (필수 - 하나라도 실패하면 시작 거부):
+  - task brief는 `## Source Verification Report` 아래 originating `final-verification` final-report path를 반드시 cite해야 합니다. lead는 해당 file을 열고 section `## 2. Final Verdict`에 value가 정확히 `accepted`인 `Verdict Token` field가 포함되어 있는지 확인합니다.
+  - verdict가 `conditional-accept`, `blocked`, 또는 다른 token("looks good" 같은 ambiguous phrasing 포함)이면 run은 즉시 status `blocked`로 끝나고 `error-analysis` 또는 `implementation-planning`으로 routing recommendation을 냅니다. 사용자에게 prompt하지 마세요. 어떤 git command도 실행하지 마세요.
+  - lead는 `git status --short`를 capture하고 working tree가 clean인지 확인해야 합니다. dirty state면 run을 abort합니다. release-handoff는 `implementation`이 생산한 commit을 package하며, stage하거나 commit하지 않습니다.
+  - lead는 `git rev-parse --abbrev-ref HEAD`를 capture하고 이를 **feature branch**로 기록해야 합니다. current branch 자체가 `main`, `master`, `prod`, `preprod`, `staging`, `dev`이면 run을 즉시 종료합니다. release-handoff는 base branch에서 동작하지 않습니다.
+  - lead는 `git log --oneline <base>..HEAD`에 최소 하나의 implementation commit이 있는지 확인해야 합니다. 비어 있으면 run은 status `blocked`로 끝나고 `implementation`으로 route합니다.
+- User interaction protocol (Claude lead - 순서대로 수행, `AskUserQuestion` 또는 equivalent interactive prompt 사용):
+  1. **Action selection** - 세 선택지를 제시하고 정확히 하나를 capture합니다.
+     - `local only` - accepted된 already-committed branch를 기록하고 push 또는 PR 없이 종료합니다.
+     - `push + PR` - feature branch를 push한 뒤 pull request를 열거나 재사용합니다.
+     - `skip` - verified state를 기록하고 git command 없이 run을 종료합니다.
+     사용자가 `skip`을 고르면 final-report self-review pass로 바로 route합니다.
+  2. **PR base branch**(`push + PR`을 골랐을 때만) - 여섯 option을 제시하고 정확히 하나를 capture합니다.
+     - `staging`
+     - `preprod`
+     - `main`
+     - `직접 입력` (free-form branch name. lead는 `git ls-remote --heads origin <name>`으로 origin에 name이 존재하는지 validate하고 실패하면 다시 묻습니다.)
+     선택한 base는 feature branch와 같으면 안 됩니다. 같으면 다시 묻습니다.
+  2b. **Pre-merge conflict probe**(`push + PR`을 골랐을 때만) - push/PR step 전에 lead는 base ref를 refresh하고 그 base와의 merge conflict를 probe해야 합니다.
+     - `git fetch origin <chosen-base>`를 실행합니다(local working tree에 read-only).
+     - `git merge-tree --write-tree --merge-base origin/<chosen-base> HEAD origin/<chosen-base>`를 실행합니다. non-zero exit code 또는 output의 conflict marker(`<<<<<<<`, `=======`, `>>>>>>>`)는 chosen base와 merge conflict가 있음을 뜻합니다.
+     - conflict가 감지되지 않으면 조용히 Q3로 진행합니다(happy path friction을 유지하기 위해 confirmation prompt를 추가하지 마세요).
+     - conflict가 감지되면 conflicting path(`merge-tree` output에서 parse)를 제시하고 정확히 하나를 capture합니다.
+       - `proceed anyway` - Q3로 계속합니다. PR은 conflict가 있는 상태로 열리며 final report는 이를 `Merge Conflict Probe`에 flag해야 합니다.
+       - `change base branch` - Q2로 돌아가 base selection을 다시 묻습니다.
+       - `cancel` - push 또는 PR 없이 run을 끝냅니다. cancellation을 final report에 기록합니다.
+     - probe는 read-only입니다. `git merge`, `git rebase`, `git pull`, 또는 working tree나 local refs를 mutate하는 command를 실행하면 안 됩니다.
+  3. **PR title + PR body confirmation** - lead의 inline draft를 verbatim 보여주고 다음 중 하나를 capture합니다.
+     - `use as-is` - drafted text로 진행합니다.
+     - `edit then proceed` - 사용자의 inline edit를 받은 뒤 edited text로 진행합니다.
+     - `cancel` - push 또는 PR command를 실행하지 않고 run을 끝냅니다. cancellation을 final report에 기록합니다.
+- Inline drafting rules (Claude lead):
+  - run brief, cited final-verification report, `git log --oneline <base>..HEAD`, `git diff <base>..HEAD --stat`를 읽어 actual committed change에 근거한 draft text를 작성합니다.
+  - **PR body template** - run context는 `PR_TEMPLATE_PATH`와 `PR_TEMPLATE_SOURCE`를 노출합니다. path는 `<PROJECT_ROOT>/.project-docs/okstra/**` 아래의 okstra-owned project artifact이거나 prepare step이 이 run의 artifact directory로 이미 materialise한 file이어야 합니다. lead는 이 file을 verbatim `Read`하고 HTML comment를 제거한 뒤 placeholder를 채워야 합니다. section list를 hard-code하지 마세요. template이 structure의 source of truth입니다. resolved file이 draft time에 missing이거나 okstra resource boundary 밖이면 structure를 invent하지 말고 clear error로 run을 abort합니다.
+  - 사용자에게 보여주기 전에 **두 artifact**를 생산합니다.
+    1. **PR title** - 기본값은 가장 최근 implementation commit의 subject 또는 committed range에 대한 concise Conventional Commits-style summary입니다.
+    2. **PR body** - `PR_TEMPLATE_PATH`에서 채운 markdown입니다. user-confirmation step의 diff(Q3 `edit then proceed`)는 raw template file이 아니라 filled template을 기준으로 계산합니다.
+- Allowed actions during the run (Claude lead only):
+  - read-only inspection: `git status`, `git status --short`, `git diff`, `git log`, `git rev-parse`, `git ls-remote --heads origin <name>`, `gh pr list --head <branch>`, `gh pr view <url>`.
+  - merge-conflict probe(`push + PR`을 골랐을 때만): `git fetch origin <chosen-base>` 및 `git merge-tree --write-tree --merge-base origin/<chosen-base> HEAD origin/<chosen-base>`. 둘 다 working tree에 대해서는 non-mutating입니다.
+  - feature-branch push(`push + PR`을 골랐을 때만): `git push -u origin <current-branch>`. pushed ref는 반드시 feature branch여야 합니다. chosen base branch는 절대 안 됩니다.
+  - PR creation(`push + PR`을 골랐고 origin에 같은 head를 가진 PR이 아직 없을 때만): `gh pr create --base <chosen-base> --head <current-branch> --title "<title>" --body "<body>"`. title과 body는 user-confirmed PR draft입니다.
+  - PR reuse: `gh pr list --head <branch> --state open --json url --jq '.[0].url'`이 URL을 반환하면 해당 PR을 already existing으로 취급합니다. final report에 URL을 기록하고 `gh pr create`를 SKIP합니다.
+- Forbidden actions (발생 시 terminal status `contract-violated`):
+  - 모든 local commit command(`git add`, `git commit`, `git restore --staged`, `git stash`). commit은 prior `implementation` phase에 속합니다.
+  - user가 "force it"이라고 말했는지와 무관하게 다음 git push variant는 모두 금지됩니다.
+    - `git push --force`
+    - `git push --force-with-lease`
+    - `git push -f`
+    - `git push +<refspec>`
+    - remote history를 rewrite하는 그 외 invocation
+  - base branch로 직접 push - 즉 `<branch>`가 `main`, `master`, `prod`, `preprod`, `staging`, `dev`, 또는 이 run에서 사용자가 PR base로 고른 branch인 `git push origin <branch>`. 허용되는 push target은 current feature branch뿐입니다.
+  - repo safeguard bypass: `git push`의 `--no-verify` / `-n`, equivalent flag로 safeguard disable, 또는 hook bypass
+  - release-publishing command: `gh release create`, `gh release edit`, `npm publish`, `cargo publish`, `pip publish`, `twine upload`, `docker push`, `terraform apply`, non-local cluster 대상 `kubectl apply`
+  - source-code edit, refactor, 또는 run 자체 artifact directory(`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`) 밖 file modification. shipping되는 diff는 prior `implementation` run이 생산한 것과 정확히 같아야 합니다. release-handoff는 이를 package할 뿐 re-author하지 않습니다.
+  - 사용자가 선택하지 않은 mutating command 실행. 예: 사용자가 `local only`를 골랐는데 PR 열기, `skip`을 골랐는데 push하기, 사용자가 이미 고른 PR base branch를 조용히 바꾸기.
+  - 실패한 git / gh command를 더 약한 safety flag로 retry. `git push`가 non-fast-forward로 실패하면 lead는 멈추고 실패를 사용자에게 설명한 뒤 instruction을 물어야 합니다. `--force`를 추가하면 안 됩니다.
+  - `TeamCreate`, 어떤 종류의 `Agent(...)` dispatch, 또는 parallel sub-agent fan-out. 이 phase는 전적으로 Claude lead 아래에서 실행됩니다.
+  - 인식할 수 없는 user reply를 menu option 중 하나로 조용히 취급하기. 사용자 답이 제시된 choice와 match하지 않으면 질문을 verbatim 다시 묻습니다.
+- Required deliverable shape (표준 section에 더해 final report에 필요):
+  - **Source Verification Report**: originating `final-verification` final-report file의 relative path와 value가 `accepted`인 literal quoted `Verdict Token` row.
+  - **Feature Branch & Working-Tree State**: `git rev-parse --abbrev-ref HEAD`의 branch name, run start의 `git status --short` output.
+  - **User Selections**: 각 prompt와 사용자 verbatim answer를 기록하는 block.
+    - Q1 action: `local only` | `push + PR` | `skip`.
+    - Q2 PR base(해당 시): chosen branch와 선택 방식(menu pick vs free-form input).
+    - Q2b merge-conflict probe(해당 시): `clean`(conflict 없음, prompt shown 없음) | `proceed anyway` | `change base branch` | `cancel`. conflict가 감지되었으면 conflicting path를 나열합니다.
+    - Q3 title/body: `use as-is` | `edit then proceed`(lead draft와 final text 간 diff 포함) | `cancel`.
+  - **Executed Commands**: lead가 실제로 실행한 모든 git / gh command와 exit code 및 stdout/stderr one-line summary. read-only inspection command는 summarize해도 됩니다. mutating command는 verbatim 나열해야 합니다.
+  - **Commit List**: `git log <base>..HEAD`에 있는 각 existing implementation commit과 short/full SHA, subject line, touched files. Release-handoff는 새 commit을 만들면 안 됩니다.
+  - **Merge Conflict Probe**: 다음 중 하나.
+    - `- Not run (user picked local only or skip).`
+    - `- Clean — no conflicts against <base> at <origin/base SHA>.`
+    - `- Conflicts detected against <base> at <origin/base SHA>; user chose <proceed anyway | change base branch | cancel>. Conflicting paths: <list>.`
+  - **Pull Request Outcome**: 다음 중 하나.
+    - `- No PR action requested.` (user picked `local only` 또는 `skip`)
+    - `- PR created: <url>` with title and base branch
+    - `- PR reused: <url>` when an existing PR was found via `gh pr list`
+    - `- PR creation skipped: <reason>` for any user-driven cancellation
+  - **Routing recommendation**: release-handoff는 terminal lifecycle phase이므로 explicit `done` token. run이 `skip` 또는 `cancel`로 끝났으면 recommendation은 release-handoff 재진입이 적절한지도 말해야 합니다.
+- Self-review pass before finalising the report (`Claude lead`가 실행):
+  1. **Entry-gate audit** - section 2는 originating final-verification report path와 value가 `accepted`인 literal `Verdict Token` row를 cite합니다. 둘 중 하나라도 없으면 run은 invalid이며 반드시 `final-verification`으로 re-route해야 합니다.
+  2. **User-selection traceability** - 실행된 모든 mutating command는 report에 capture된 user selection과 mapping됩니다. 대응 user answer 없는 mutating command는 contract violation입니다.
+  3. **Forbidden-action audit** - Forbidden actions list의 모든 entry에 대해 run session transcript(`git`, `gh` invocation)를 scan합니다. 발생 시 run은 unsafe territory로 넘어간 것이며 `contract-violated`로 flag해야 합니다.
+  4. **Push-target audit** - 기록된 모든 `git push`에 대해 refspec이 base branch가 아니라 feature branch로 resolve되는지 확인합니다.
+  5. **Idempotency check** - 같은 head의 PR이 run start에 이미 존재했다면 fresh `gh pr create` invocation이 아니라 `PR reused`를 report가 기록하는지 확인합니다.
+  6. **Merge-conflict probe audit** - `push + PR` run이면 report의 `Merge Conflict Probe` section이 존재하고 `Clean`을 기록하거나 `Conflicts detected`와 사용자 verbatim choice를 기록하는지 확인합니다. `push + PR` run에서 probe entry가 없거나 parse할 수 없으면 contract violation입니다.
+- Non-goals:
+  - final-verification verdict를 다시 다투지 않습니다. release-handoff는 cited `accepted` verdict를 신뢰하고 acceptance check를 다시 열지 않습니다.
+  - commit 생성, amend, squash, rewrite. commit production은 `implementation`에 속합니다.
+  - 사용자가 만들기로 선택한 단일 PR을 넘어서는 추가 PR, release, deployment 열기.
+  - PR merge. merge는 release-handoff가 끝난 뒤 사용자(또는 repo automation)가 수행하는 별도 manual step입니다. lead는 `gh pr merge`를 호출하면 안 됩니다.
+  - user phrasing을 근거로 menu choice를 넘어서는 escalation. 모든 mutating action에는 explicit menu selection이 필요합니다.

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

@@ -0,0 +1,42 @@
+# Requirements Discovery Profile (요구사항 발견 프로필)
+
+- Purpose (목적): implementation이 시작되기 전에 작업 요청을 분류하고, 누락된 requirement evidence를 식별하며, task를 가장 안전한 다음 lifecycle phase로 route합니다.
+- Required workers:
+  - claude
+  - codex
+  - report-writer
+- Optional workers (opt-in via `--workers`):
+  - gemini - roster에 추가되면 analyser set에 참여합니다. 기본값은 omitted입니다.
+{{INCLUDE:_common-contract.md}}
+- Brief consumption (phase-specific addendum - 공유 규칙은 `_common-contract.md`의 "Brief handoff contract"에 있음):
+  - 공유 reporter-confirmation precondition을 그대로 적용합니다. 이 phase에서 unresolved `intent-check:` / `conversion-block:` row는 `Blocks=next-phase`를 사용합니다.
+  - 분류 전(precondition 통과 후), `intent-check:` / `terminology:` / `conversion-block:` prefix가 붙은 모든 `Open Questions` row와 `intent-inference` / `terminology-mapping` label이 붙은 모든 `Augmentation` entry를 scan합니다. 이들은 이 phase가 해결하거나 carry forward해야 하는 translation signal입니다.
+  - paired `intent-check:` row에 `[CONFIRMED …]`가 있는 `intent-inference` augmentation은 **confirmed**로 취급합니다. 확인 text가 원래 inference와 다르면 `## Reporter Confirmations`의 confirmation text를 신뢰합니다. `reporter-confirmations: skipped` 아래의 unconfirmed `intent-inference` row는 위 precondition의 `skipped` branch를 따릅니다.
+  - `conversion-block:` row는 명시적인 "translation failed" signal입니다. 여기에서 inference로 해결하려고 시도하지 마세요. 위 precondition이 이미 처리합니다.
+- Primary focus areas:
+  - 작업을 bugfix, feature, improvement, refactor, ops-change 중 하나로 분류
+  - `error-analysis` 또는 `implementation-planning` 중 어느 것이 다음 안전한 단계인지 판단. 직접 `implementation` handoff는 유효한 routing target이 아닙니다. implementation에는 승인된 `implementation-planning` report가 필요합니다.
+  - 신뢰할 수 있는 routing을 막는 누락 material 식별
+  - 같은 task key 아래 장기 작업의 task continuity expectation 정의
+  - 다음 phase 시작 전 approval 또는 confirmation point 포착
+  - **domain alignment check**: 존재하면 `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` 및 `<PROJECT_ROOT>/.project-docs/okstra/decisions/` title을 읽습니다. okstra memory file이 없는 것은 정상입니다. error로 처리하지 마세요. brief의 `Open Questions` 아래 모든 `terminology:*` entry가 routing 전에 canonical resolution을 가졌는지 검증합니다. brief의 fuzzy 또는 overloaded term은 이 phase에서 단일 canonical term으로 해결해야 합니다.
+- Decision-tree walk (bounded):
+  - brief의 `Desired Outcome`, classification, routing target이 decision chain에 의존하면 그 chain을 branch 하나씩 따라갑니다. 각 branch는 free-form interview가 아니라 `Clarification Items` row 하나입니다.
+  - 모든 clarification row에서 단일 최선 답변과 한 줄 rationale은 `Expected form` cell에 `Recommended: ...` 형태로 작성합니다. 다른 option과 한 문장 consequence도 같은 cell에 `Alternatives: ...`로 적습니다.
+  - **Codebase-first rule**: branch가 `Read` / `Grep` / file inspection으로 해결 가능하면 그렇게 해결하고 `Statement` cell에 `Evidence checked: <path:line>`을 기록합니다. 사용자에게 escalate하지 마세요.
+  - Budget: unified `## 5. Clarification Items` table은 (a) unresolved decision branch당 한 row, (b) 총 8 row 중 작은 값으로 제한됩니다. cap을 넘는 ambiguity는 routing recommendation의 risk note에 접습니다.
+- Expected output emphasis:
+  - evidence-backed routing decision
+  - uncertainty boundary와 missing input
+  - 다음 권장 phase 및 안전한 resume guidance
+  - 모든 `terminology:*` brief item에 대한 canonical-term resolution. final report의 새 `Domain Alignment` subsection에 한 줄 `<term> = <definition>` 형식으로 작성합니다. 각 항목 옆에는 `<PROJECT_ROOT>/.project-docs/okstra/glossary.md`를 업데이트해야 하는지 제안합니다(제안만 - 실제 write는 후속 run의 `okstra-brief` Step 4.5에서 수행).
+- Clarification request policy (phase-specific addenda - 공유 policy는 `_common-contract.md`에 있음):
+  - final report 작성 시점에 blocking input이 누락되어 있으면 `final-report-template.md`의 `## 5. Clarification Items`를 채웁니다(단일 unified table; 다음 run이 없이 시작할 수 없는 item은 `Blocks=next-phase`).
+  - 답이 routing decision(`bugfix` vs `feature`, `error-analysis` vs `implementation-planning` 등)에 직접 mapping되는 구체적인 질문을 선호합니다. 각 option을 쉬운 말로 적고, 그 선택이 다음 phase에 무엇을 의미하는지 한 문장으로 설명합니다.
+  - 모든 clarification row는 `Expected form` cell 안에 `Recommended` answer + 한 줄 rationale을 가져야 합니다. recommendation 없는 row는 half-formed로 rejected됩니다.
+  - **Codebase-first ambiguity resolution (defect rule)**: `Read` / `Grep` / file inspection으로 답할 수 있는 ambiguity는 반드시 그렇게 해결하고 file:line evidence로 기록해야 합니다. codebase가 이미 답하는 내용을 clarification row로 쓰는 것은 이 phase의 defect입니다.
+  - **Evidence note는 `Statement` 안에 작성**: 모든 clarification row는 `Statement` cell에 `Evidence checked: <path:line>` 또는 `Evidence checked: none — <human-only reason>`을 포함합니다. `none`은 row 성격이 "사람만 답할 수 있음"(reporter intent, business priority, external authority)일 때만 허용됩니다. codebase로 답할 수 있었던 row가 `none`이면 defect입니다.
+- Non-goals:
+  - 다음 phase를 결정하는 데 필요한 경우가 아니면 full implementation design을 하지 않습니다.
+  - **source code edit, plan authoring, build, deployment** - 이 run은 작업을 분류하고 route만 합니다. 더 깊은 analysis와 planning은 후속 phase에 속합니다.
+  - **`<PROJECT_ROOT>/.project-docs/okstra/` 밖 write** - 이 phase는 okstra artifact root만 사용합니다. glossary addition은 `<PROJECT_ROOT>/.project-docs/okstra/glossary.md`에 저장됩니다(`okstra-brief` Step 4.5 경유). decision draft는 `<PROJECT_ROOT>/.project-docs/okstra/decisions/`에 저장됩니다(`implementation-planning` 경유).

package/runtime/prompts/profiles/release-handoff.md

@@ -43,7 +43,7 @@
      - `cancel` — end the run without executing push or PR commands; record the cancellation in the final report.
 - Inline drafting rules (Claude lead):
   - read the run brief, the cited final-verification report, `git log --oneline <base>..HEAD`, and `git diff <base>..HEAD --stat` to ground the drafted text in actual committed changes.
-  - **PR body template** — the run context exposes `PR_TEMPLATE_PATH` (resolved by the prepare step in priority order: per-run override → `<project_root>/.project-docs/okstra/project.json` `prTemplatePath` → `~/.okstra/config.json` `prTemplatePath` → bundled default at `~/.claude/skills/okstra-run/templates/pr-body.template.md`) along with `PR_TEMPLATE_SOURCE` indicating which scope was used. The lead MUST `Read` this file verbatim, strip HTML comments, then fill in the placeholders. Do NOT hard-code a section list — the template is the source of truth for the structure. If the resolved file is missing at draft time, abort the run with a clear error rather than inventing a structure.
+  - **PR body template** — the run context exposes `PR_TEMPLATE_PATH` and `PR_TEMPLATE_SOURCE`. The path MUST be an okstra-owned project artifact under `<PROJECT_ROOT>/.project-docs/okstra/**` or a file already materialised into this run's artifact directory by the prepare step. The lead MUST `Read` this file verbatim, strip HTML comments, then fill in the placeholders. Do NOT hard-code a section list — the template is the source of truth for the structure. If the resolved file is missing or outside the okstra resource boundary at draft time, abort the run with a clear error rather than inventing a structure.
   - produce **two artifacts** before showing them to the user:
     1. **PR title** — by default the subject of the most recent implementation commit, or a concise Conventional Commits-style summary of the committed range.
     2. **PR body** — markdown filled from `PR_TEMPLATE_PATH`. The user-confirmation step's diff (Q3 `edit then proceed`) is computed against the filled template, not against the raw template file.

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

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