okstra 0.34.1 → 0.36.0

package/runtime/prompts/profiles/implementation-planning.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 option drafting)**: read the brief's frontmatter `reporter-confirmations:` field and inspect every `Open Questions` row prefixed `intent-check:` / `conversion-block:` for the `[CONFIRMED …]` marker.
-    - `reporter-confirmations: complete` → proceed normally.
-    - `reporter-confirmations: partial` → proceed; treat still-unmarked `intent-check:` / `conversion-block:` rows per the `skipped` branch below.
-    - `reporter-confirmations: skipped` (or `partial` with remainder) → do NOT silently infer the missing answers. Promote each unmarked `intent-check:` / `conversion-block:` row into this run's `## 5. Clarification Items` as `Kind=decision, Blocks=approval`, with the recommended answer drawn from the brief's matching `intent-inference` / `conversion-block:` text and clearly labelled `보고자 직접 확인 권장`. Then proceed; the operator cannot toggle `User Approval Request` until those rows are resolved.
-    - `reporter-confirmations: pending` (or field missing) → ABORT planning. Write only `## 0. Reporter Confirmation Required` summarising which rows are pending and stop. The final report carries `Blocks=approval`.
+  - Apply the shared reporter-confirmation precondition exactly as written. In this phase, unresolved `intent-check:` / `conversion-block:` rows use `Blocks=approval`; the operator cannot toggle `User Approval Request` until those rows are resolved.
   - never plan around an unconfirmed `intent-inference` augmentation as if it were a settled requirement. After the precondition runs, a `[CONFIRMED …]` marker on the matching `intent-check:` row is the signal that the inference can be treated as settled; otherwise it remains a `Blocks=approval` clarification item per the precondition's `skipped` branch.
   - `conversion-block:` rows are handled by the precondition; planning around an untranslated reporter phrase is forbidden until it is resolved.
 - Pre-planning context exploration (mandatory before option drafting):
@@ -22,7 +18,7 @@
   - skim recent commits touching those files (`git log -- <path>`) to surface in-flight work or contested areas
   - **codebase-first ambiguity resolution**: any ambiguity that can be answered by `Read` / `Grep` MUST be resolved that way and recorded with file:line evidence. Only ambiguities that genuinely require a human decision are escalated as `Clarification Items` rows. Writing a clarification row for something the code already answers is a defect of this phase.
   - flag any requirement that is ambiguous, contradictory, or missing success criteria — register each one as a row in the report's `## 5. Clarification Items` table with `Blocks=approval` instead of guessing
-  - read in priority order — (authoritative) `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` and `<PROJECT_ROOT>/.project-docs/okstra/decisions/` titles if present; (supplementary) `<PROJECT_ROOT>/CONTEXT.md` (or `CONTEXT-MAP.md` → per-context `CONTEXT.md`) and `<PROJECT_ROOT>/docs/adr/` titles if present. Absent external files are the normal state — do not error. Treat the brief's `terminology:*` resolutions from `requirements-discovery` (if any) as authoritative; if missing, resolve any remaining fuzzy term as a `Blocks=approval` clarification row.
+  - read `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` and `<PROJECT_ROOT>/.project-docs/okstra/decisions/` titles if present. Absent okstra memory files are the normal state — do not error. Treat the brief's `terminology:*` resolutions from `requirements-discovery` (if any) as authoritative; if missing, resolve any remaining fuzzy term as a `Blocks=approval` clarification row.
 - Primary focus areas:
   - requirement gaps
   - affected components and boundaries
@@ -30,7 +26,7 @@
   - implementation options and trade-offs
   - hidden dependency or migration risk
   - validation and rollout approach
-- Design principles applied when scoring options (borrowed from `brainstorming`):
+- Design principles applied when scoring options:
   - **Isolation & single responsibility**: each unit touched should have one clear purpose, well-defined interface, and be independently testable. Penalize options that widen a unit's responsibility.
   - **Files that change together live together**: split by responsibility, not by technical layer. Penalize options that scatter one logical change across unrelated layers.
   - **Follow established patterns**: in existing codebases, conform to current conventions. Targeted cleanup of a file you are already modifying is acceptable; unrelated refactors are not.
@@ -40,19 +36,19 @@
   - dependency and risk visibility
   - recommended execution order
 - Approval gate (phase-specific addendum to shared authority rule):
-  - The `User Approval Request (사용자 승인 게이트)` block at the **top of the final report** (immediately under the metadata header, before `Section 0`) is the only authorised approval gate. The user clears it either by (a) editing the single checkbox `- [ ] Approved` to `- [x] Approved` directly, or (b) invoking the next phase with `--approve` so the CLI invocation itself is treated as the approval signal and the runtime flips the checkbox on the user's behalf.
+  - The YAML frontmatter `approved: true|false` field is the only authorised approval gate. report-writer always emits `approved: false`. The user clears it either by (a) editing the frontmatter line to `approved: true` directly, or (b) invoking the next phase with `--approve` so the CLI flips the frontmatter on the user's behalf. `okstra_ctl.run._validate_approved_plan` reads this field and refuses entry until it is `true`.
 - Non-goals:
   - code-level micro-optimization unless it changes the implementation approach
   - **source code edits of any kind** — this run produces a plan document only; Edit/Write on project source files is forbidden until the plan is approved and a separate `implementation` run starts
   - executing builds, migrations, deployments, or any command that mutates project state outside the run's own artifact directories (`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`)
   - this run stays in `implementation-planning` regardless of user phrasing — the shared anti-escalation rule applies
   - dispatching parallel sub-agents beyond the required worker roster — okstra owns worker fan-out
-  - writing artifacts to `docs/superpowers/specs/` or `docs/superpowers/plans/` — the run's `reports/` directory is the canonical location
+  - writing artifacts anywhere except `<PROJECT_ROOT>/.project-docs/okstra/` — the run's `reports/` directory is the canonical location for this phase
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
-  - every clarification row carries a `Recommended` answer + one-line rationale; rows that lack a recommendation are rejected as half-formed.
-  - **`evidence-checked:` cell required**: every clarification row carries an `evidence-checked: <path:line> | none` cell. `evidence-checked: <path:line>` means the codebase was inspected and the row records what was found. `evidence-checked: none` is allowed ONLY when the row's nature is "only a human can answer this" (reporter intent, business priority, organisational decision); the row body must state which one in one line. A row with `evidence-checked: none` that *could* have been answered by the codebase is a defect of this phase, restated from the pre-planning rule above.
+  - 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.
+  - **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, organisational decision). A row with `none` that *could* have been answered by the codebase is a defect of this phase, restated from the pre-planning rule above.
 - Section heading contract (BLOCKING — validator scans for these literal English substrings):
-  - The final report MUST include section headings containing each of the following exact strings: `Option Candidates`, `Trade-off`, `Recommended Option`, `Stepwise Execution Order`, `Dependency`, `Validation Checklist`, `Rollback`, `User Approval Request`.
+  - The final report MUST include section headings containing each of the following exact strings: `Option Candidates`, `Trade-off`, `Recommended Option`, `Stage Map`, `Stage Exit Contract`, `Stage Validation`, `Dependency`, `Validation Checklist`, `Rollback`. (Approval is no longer a body section — it is the YAML frontmatter `approved` field.)
   - Korean translations are allowed in parentheses (e.g. `### Recommended Option (권장 옵션)`), but the English keyword must be present verbatim in the heading line.
   - The shape and ordering follow `final-report-template.md` section 4.5 (`Implementation Plan Deliverables`). Do NOT translate the heading keywords — `validators/validate-run.py` does substring matching on the raw report text and 7-of-8 missing strings is a real, repeatedly observed failure mode (root cause: writer translated the headings to Korean).
 - Required deliverable shape (final report, in addition to the standard sections):
@@ -62,24 +58,28 @@
     - estimated blast radius (units, configs, deployment manifests, data migrations)
   - trade-off matrix across options (rows = options, columns at minimum: complexity, risk, reversibility, test coverage cost, rollout cost)
   - recommended option with rationale tied to the design principles above
-  - **stepwise execution order for the recommended option**, written as bite-sized tasks:
-    - each step is one action completable in roughly 2–5 minutes (e.g. "write the failing test for X", "run it to confirm it fails", "implement minimal code", "run test to confirm pass", "commit")
-    - every step names exact file paths and exact commands; for code steps, include the actual code or the diff sketch — not a description
-    - prefer TDD ordering (failing test → implementation → green → commit) when the touched area has or can have tests
+  - **Stage Map (mandatory — always emitted, even when N=1):** a table of all stages with `stage | title | depends-on | step-count | exit-contract-summary`. `depends-on` is `(none)` or a comma-separated stage number list. Stages with `depends-on (none)` can be implemented in parallel by two simultaneous `implementation` runs.
+  - **Per-stage subsections** (`## 4.5.<i> Stage <i>: <title>` for each `i`), each containing the four required subsections:
+    - `### Carry-In` — for `depends-on (none)`: task-brief only. Otherwise: each depended-on stage's static exit contract + runtime sidecar path `runs/<impl-key>/carry/stage-<i>.json` placeholder.
+    - `### Stepwise Execution Order` — bite-sized table with `step | action | files | command | expected`. **Effective row count ≤ 6** (excluding header / divider / blank). Each step is one action completable in 2–5 minutes; for code steps include actual code or diff sketch; prefer TDD ordering (failing test → implementation → green → commit).
+    - `### Stage Exit Contract` — predicted added/modified files, newly exposed identifiers/types/endpoints, downstream-usable resources.
+    - `### Stage Validation` — pre / mid / post exact commands or observable outcomes for this stage only.
+  - **Parallelisation-first rule (1st-class):** the writer MUST prefer the partition that maximises the number of `depends-on (none)` stages. Given two partitions with equal total step count, the one with fewer `depends-on` edges wins. Conservative `let's serialise to be safe` groupings are forbidden — each `depends-on` link is justified by a concrete data/contract dependency, not a vague risk concern.
+  - **Stage exit contract is the carry surface:** keep it as narrow as possible. Wider surface = more downstream coupling.
   - dependency / migration risk assessment (ordering constraints, data backfills, feature-flag prerequisites, repo-internal sequencing)
   - validation checklist (pre / mid / post) — each item is an exact command or observable outcome
   - rollback strategy — exact revert path (commits, flags, migrations) and the signal that triggers rollback
-  - explicit `User Approval Request (사용자 승인 게이트)` block placed at the **top of the report** with a single canonical checkbox marker `- [ ] Approved` (user toggles to `- [x] Approved` to authorise the next `implementation` run). The `User Approval Request` validator key-substring is satisfied by this top block — do NOT recreate a `### 4.5.8 User Approval Request` body stub (the validator now fails reports that contain one, see `validators/validate-run.py` and `templates/reports/final-report.template.md` §4.5.8).
-  - **the marker line is rendered only when the plan-body verification gate (§4.5.9) returns `passed` or `passed-with-dissent`.** When the gate returns `blocked-by-disagreement` or `aborted-non-result`, the top-of-report Approval block is rendered **without** the canonical `- [ ] Approved` bullet (the rest of the block — title, summary, audit lines — stays). The `validators/validate-run.py` `validate_phase_boundary` function enforces this exact correspondence between gate result and marker line presence.
+  - the YAML frontmatter MUST include the line `approved: false` (report-writer always emits the unflipped value). The user authorises the next `implementation` run by flipping it to `approved: true` (manual edit or `--approve` CLI). Do NOT recreate any `User Approval Request` body block — the validator fails reports that contain one (see `validators/validate-run.py` deprecated patterns).
+  - **the frontmatter `approved: false` line is rendered unconditionally; if the plan-body verification gate (§4.5.9) returns `blocked-by-disagreement` or `aborted-non-result`, the writer MUST keep `approved: false` and the validator refuses any report that ships with `approved: true` under such a gate result.**
   - every ambiguity flagged during pre-planning that the user must resolve before approval registered as a `Blocks=approval` row in the `## 5. Clarification Items` table (do NOT create a separate `Open Questions` block under `4.5.x` — the unified table is the single home)
   - **§4.5.9 Plan Body Verification (BLOCKING).** After report-writer finishes the draft, the lead MUST run a worker peer-review round on the consolidated plan body (sections 4.5.1 – 4.5.7) and populate `### 4.5.9 Plan Body Verification` in the final report. The round protocol, plan-item ID scheme (`P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*`), verdict semantics, gate-result classification, and dissent log format are defined in `skills/okstra-convergence/SKILL.md` "Plan-body verification mode". The four gate-result values are `passed`, `passed-with-dissent`, `blocked-by-disagreement`, `aborted-non-result`. When the gate would have been `blocked-by-disagreement` or `aborted-non-result`, the lead MUST NOT silently flip it to one of the passing values to "unblock" the run — that is a contract violation.
-  - **ADR evaluation (grill-with-docs adopted, sole owner)**: this phase is the **single owner** of ADR evaluation in the okstra lifecycle. The brief never evaluates or drafts ADRs — it only forwards `adr-candidate:*` signals. Every `adr-candidate:*` entry inherited from the brief's `Open Questions` is a mandatory evaluation target. In addition, evaluate every decision the recommended option introduces against the three ADR criteria:
+  - **Decision-record evaluation (sole owner)**: this phase is the **single owner** of decision-record evaluation in the okstra lifecycle. The brief never evaluates or drafts decision records — it only forwards `adr-candidate:*` signals. Every `adr-candidate:*` entry inherited from the brief's `Open Questions` is a mandatory evaluation target. In addition, evaluate every decision the recommended option introduces against the three criteria:
     1. **Hard to reverse** — would changing the decision later cost meaningfully more than deciding now?
     2. **Surprising without context** — would a future reader, seeing only the code, wonder "why was it built this way?"?
     3. **Real trade-off** — were there named alternatives, and was one picked for specific reasons?
     If **all three** hold, attach a decision draft as a report appendix section titled `Decision Drafts` (one decision per subsection). Each draft uses the `## Context / ## Decision / ## Consequences / ## Alternatives Considered` shape, names the alternatives that were rejected and why, and starts with `## Status: Proposed`. The next decision number is `(max existing in <PROJECT_ROOT>/.project-docs/okstra/decisions/ + 1)` zero-padded to 4 digits. If any of the three criteria is missing, do NOT raise a decision draft — instead record `skipped adr-candidate: <topic> — reason: <criterion that failed>` on one line under `Decision Drafts` so the next reader knows the candidate was evaluated and intentionally dropped.
-    The drafts are NOT written by this phase. The approved plan's stepwise execution order MUST include the step `Create <PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md from the decision draft in section X` so the `implementation` run commits the file. External `<PROJECT_ROOT>/docs/adr/` is never touched.
-  - **Domain-doc proposals**: if `CONTEXT.md` / `CONTEXT-MAP.md` needs a new term or edited definition, add the step `Update CONTEXT.md: <term> = <definition>` to the stepwise execution order. Do NOT edit the file in this phase.
+    The drafts are NOT written by this phase. The approved plan's stepwise execution order MUST include the step `Create <PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md from the decision draft in section X` so the `implementation` run commits the file inside okstra's subtree.
+  - **Glossary proposals**: if a term or definition should become okstra institutional memory, add the step `Update <PROJECT_ROOT>/.project-docs/okstra/glossary.md: <term> = <definition>` to the stepwise execution order. Use no other project-memory path.
 - No-placeholder rule (plan failures — reject any option or step that contains these):
   - "TBD", "TODO", "implement later", "fill in details", "add appropriate error handling", "handle edge cases", "write tests for the above" without actual test code
   - "similar to Option/Task N" without repeating the concrete content (readers may consume sections out of order)
@@ -92,3 +92,4 @@
   4. **Ambiguity check** — any requirement that could be read two ways must be made explicit or moved to the `## 5. Clarification Items` table as a `Blocks=approval` row.
   5. **Scope check** — if the recommended plan now spans multiple independent subsystems, recommend splitting into separate planning runs rather than shipping an oversized plan.
   6. **Plan-body verification reconciliation (BLOCKING for implementation-planning).** Inspect the `### 4.5.9 Plan Body Verification` verdict table. For every plan-item row classified as `majority-disagree → C-<N>`, the corresponding `C-<N>` row MUST exist in `## 5. Clarification Items` with `Kind` chosen per the standard policy and `Blocks=approval`. Do NOT create a parallel `### 4.5.x Open Questions` block — the unified table is the single home. Conversely, the `Classification` column's `C-<N>` reference and the `## 5. Clarification Items` `ID` column MUST match 1:1; an orphan on either side is a contract violation. For `partial-consensus` and `worker-unique` plan-items, the dissenting opinion lives in §4.5.9 `Dissent log` and is NOT promoted to §5.
+  7. **Stage Map self-check** — for every stage, count the effective rows of its `Stepwise Execution Order` table by hand; reject the draft if any stage exceeds 6. Walk the `depends-on` graph and confirm it is a DAG (no cycle, no self-reference). For each `depends-on` link, ask "can this be removed by re-partitioning?" — if yes, re-partition and re-count.

package/runtime/prompts/profiles/implementation.md

@@ -43,11 +43,11 @@
   - **All-verifier-failure policy**: if every verifier present in the resolved roster (`Claude verifier`, `Codex verifier`, and `Gemini verifier` when opted in) ends with a non-result terminal status (`timeout`, `error`, `not-run`) — i.e. zero independent verdicts were produced — the run MUST end with status `blocked` and route to a follow-up `error-analysis` run. `Claude lead` MUST NOT substitute its own verdict in place of the missing verifier outputs; synthesis requires at least one independent verifier's verdict. If one or more verifiers fail but at least one returns a verdict, the run proceeds with the surviving verdict(s) and the final report MUST explicitly notate which verifiers were unavailable, with the captured error / timeout evidence per failed verifier.
 - Pre-implementation gate (mandatory — refuse to start if any item fails):
   - the run brief MUST cite `--approved-plan <path>` pointing to a `final-report.md` produced by a prior `implementation-planning` run located under `runs/implementation-planning/.../reports/final-report.md`
-  - that file MUST contain a `User Approval Request` block (canonically placed at the **top of the report**, immediately under the metadata header) AND a recorded user approval marker. The canonical, recommended form is the single markdown checkbox line `- [x] Approved`. The runtime regex in `okstra_ctl.run._validate_approved_plan` also accepts (case-insensitive, line-anchored, optional leading `-`/`*`/`+` bullet): `APPROVED` (alone, followed by `:`, or end-of-line), `[x] Approved`, or `User Approval: APPROVED|granted|yes`. Free-form approvals such as "lgtm", "go ahead", or paraphrased confirmations are intentionally NOT accepted; if the user's approval is informal, re-edit the plan file to flip the top checkbox to `- [x] Approved` before invoking the implementation run.
-  - Two equally-valid approval paths exist (both end up satisfying the same regex gate):
-    - **Manual edit** — the user opens the report, flips `- [ ] Approved` to `- [x] Approved`, saves, then runs `okstra ... --task-type implementation --approved-plan <path>`.
-    - **CLI ack** — the user runs `okstra ... --task-type implementation --approved-plan <path> --approve`. The CLI invocation itself is modelled as the user's act of approval; the runtime (`okstra_ctl.run._apply_cli_approval`) flips the checkbox in the report file and appends an audit line `- 승인 일시 (CLI ack): <ISO8601> — recorded by \`okstra --approve\`` before the standard regex validation runs. Use this when running unattended or when you want a single command to both approve and launch the next phase.
-  - The `--approve` flag is **only meaningful with `--task-type implementation` and `--approved-plan <path>`**. Passing it with any other task-type causes `PrepareError` (the runtime refuses to silently ignore approval signals). It is also a no-op if the file already carries a valid approval marker (idempotent — only an audit line is appended, the marker is not re-toggled).
+  - that file's YAML frontmatter MUST carry `approved: true`. report-writer emits `approved: false` by default; the user flips it to `true` to authorise this run. Free-form approvals such as "lgtm", "go ahead", or paraphrased confirmations are intentionally NOT accepted; if the user's approval is informal, re-edit the plan file's frontmatter line to `approved: true` before invoking the implementation run.
+  - Two equally-valid approval paths exist (both end up satisfying the same frontmatter check):
+    - **Manual edit** — the user opens the report, changes the frontmatter line `approved: false` to `approved: true`, saves, then runs `okstra ... --task-type implementation --approved-plan <path>`.
+    - **CLI ack** — the user runs `okstra ... --task-type implementation --approved-plan <path> --approve`. The CLI invocation itself is modelled as the user's act of approval; the runtime (`okstra_ctl.run._apply_cli_approval`) flips the frontmatter `approved` to `true` and appends an audit line `- 승인 일시 (CLI ack): <ISO8601> — recorded by \`okstra --approve\`` before the standard frontmatter validation runs. Use this when running unattended or when you want a single command to both approve and launch the next phase.
+  - The `--approve` flag is **only meaningful with `--task-type implementation` and `--approved-plan <path>`**. Passing it with any other task-type causes `PrepareError` (the runtime refuses to silently ignore approval signals). It is also a no-op if the frontmatter already has `approved: true` (idempotent — only an audit line is appended, the flag is not re-toggled).
   - the file's `Recommended option` and its bite-sized step list become the authoritative scope for this run; any deviation must be justified in the final report and routed back to a new `implementation-planning` run instead of being silently expanded.
 - Task worktree (provisioned by `okstra-ctl` at the first phase's run-prep time, reused for every subsequent phase of this task-key):
   - Status: `{{EXECUTOR_WORKTREE_STATUS}}` (one of: `created` | `reused` | `skipped-in-worktree` | `skipped-not-git`)
@@ -60,21 +60,32 @@
   - **Verifier behaviour**: all verifier roles in the resolved roster read from the SAME working tree path so they observe the exact diff the Executor produced. Verifiers remain strictly read-only there.
   - **Lifecycle**: the worktree is kept after the run completes (no automatic cleanup) and is reused by every subsequent phase of the same task-key. Cleanup, when the task is fully done, is manual: `git -C <main-worktree> worktree remove <path>` followed by `git -C <main-worktree> branch -D <branch>`, plus removing the task-key entry from `~/.okstra/worktrees/registry.json`.
   - **Skipped paths**: when status is `skipped-in-worktree` or `skipped-not-git`, the executor operates in `project_root` as before. Cite the status in the final report's metadata header so reviewers know which path was taken.
-  - **Synced state directories (symlinks into the MAIN worktree)**: at provision time `okstra-ctl` symlinks `.project-docs/`, `.scratch/`, and `graphify-out/` from the repo's **main worktree** into the task worktree (override via `OKSTRA_WORKTREE_SYNC_DIRS`; empty string disables). These are NOT independent copies — writes through them land in the main worktree. Inside this run the executor MUST confine writes under these paths to its own task scope (i.e. only `.project-docs/okstra/tasks/<this-task-id>/...`). Reading from elsewhere under the symlinks (other tasks, `graphify-out/GRAPH_REPORT.md`, `.scratch/` issues) is allowed and expected for context.
+  - **Synced okstra state directory (symlink into the MAIN worktree)**: at provision time `okstra-ctl` may symlink `.project-docs/` from the repo's **main worktree** into the task worktree. This is NOT an independent copy — writes through it land in the main worktree. Inside this run the executor MUST confine okstra artifact writes to its own task scope (i.e. `.project-docs/okstra/tasks/<this-task-id>/...`). Other synced directories, if present due to local configuration, are not implicit okstra context; read them only when the brief explicitly cites them as source material.
 - Pre-implementation context exploration (executor before first edit):
-  - **Mandatory skill invocation — `tdd`**: BEFORE the first `Edit` or `Write` call, the executor MUST invoke the `tdd` skill via the `Skill` tool and follow its red-green-refactor loop for every code change in this run. This is a hard requirement, not a recommendation; skipping it is a `contract-violated` outcome. The skill governs HOW each step is executed (failing test first → minimal implementation → refactor); it does not override the approved plan's WHAT/file scope.
+  - **Mandatory TDD loop**: BEFORE the first `Edit` or `Write` call, the executor MUST apply a red-green-refactor loop for every code change in this run. This is required; skipping it is a `contract-violated` outcome. This governs HOW each step is executed (failing test first → minimal implementation → refactor); it does not override the approved plan's WHAT/file scope.
     - Order of operations per plan step: (1) write/extend the test that captures the step's acceptance criterion and confirm it fails for the right reason, (2) commit the failing test (`test(<scope>): ...`), (3) implement the minimum change to make it pass, (4) commit the implementation (`feat|fix(<scope>): ...`), (5) refactor without changing behaviour and commit separately if any cleanup is made (`refactor(<scope>): ...`). The failing-then-passing transition between steps (2) and (4) is the `TDD evidence` required by the final report.
     - Doc-only / config-only / pure-rename steps that have no observable runtime behaviour are exempt from the failing-test requirement, but the executor MUST cite the exemption per step in the final report (`TDD exemption: <reason>`).
     - When the touched area has no existing test harness, the executor MUST stand up the minimum harness needed to host one regression test for this run rather than skipping TDD entirely. Record the harness-bootstrap step as an `Out-of-plan edit` if it is not in the plan.
-  - re-read the approved plan end-to-end and extract: file list, step order, validation commands, rollback path
+  - re-read the approved plan end-to-end and parse the `## 4.5 Stage Map`. Determine **start stage**:
+    - if `--stage <N>` is supplied, use N. Otherwise auto = the lowest stage number whose `depends-on` are all recorded as `status:done` in `runs/<plan-key>/consumers.jsonl` AND that itself has no `status:done` row. Multiple stages may match — two parallel `implementation` runs may pick different ones and proceed concurrently.
+    - load every `runs/<plan-key>/carry/stage-<i>.json` for `i ∈ depends-on(start_stage)` and inject them into the executor's working context as "runtime carry-in". For `depends-on (none)` stages, no sidecar load — task-brief only.
+    - extract the **start stage's** file list, step order, Stage Validation commands, Stage Exit Contract, and rollback path. These — not the whole plan — are the authoritative scope for this run.
   - inspect the current state of every file the plan names; if any file has changed materially since the plan was written, stop and route to a new `implementation-planning` run instead of editing speculatively
   - "materially changed" means: the function, class, section, or behaviour the plan targets has been edited, renamed, moved, removed, or otherwise altered in a way that invalidates the plan's reasoning. Cosmetic edits (whitespace, comment-only changes, unrelated function modifications elsewhere in the same file) do NOT trigger a re-plan; cite the diff (`git log --oneline <plan-created-at>..HEAD -- <file>`) in the final report and proceed.
   - distinguish the two file-scope rules (they are not in conflict):
     - **drift rule** (this section): if a file *named in the plan* has materially drifted, refuse to edit and route back to planning. This protects trust in the approved scope.
     - **out-of-plan rule** (Allowed actions section below): if a step *requires touching a file NOT in the plan list*, that is permitted with `Out-of-plan edits` justification. This handles honest scope discovery during execution.
   - confirm the test/build commands referenced in the plan still exist and run from a clean state
+- Stage execution contract (this run owns exactly one stage of the plan):
+  - **Sidecar evidence writer (BLOCKING).** When the start stage's Stage Validation `post` commands all succeed, the Executor MUST emit a JSON object matching the schema in `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2 and the lead MUST persist it to `runs/<impl-task-key>/carry/stage-<N>.json`. The file MUST NOT exist before the run starts (overwrite is refused — see `--force-stage` non-goal).
+  - **Reverse link (BLOCKING).** Before the first Edit/Write, append a `status:"started"` row to `runs/<plan-task-key>/consumers.jsonl` (lock via the okstra runtime). On stage completion, append a `status:"done"` row with `carry_path` populated.
+  - **One-PR-per-stage.** This run creates exactly one PR titled `Stage <N>: <stage title>`. The PR body MUST include:
+    - `## Stage` — number and title (from Stage Map row).
+    - `## Carry-In summary` — depends-on list + cited identifiers/SHAs from each loaded sidecar (omit when depends-on is empty).
+    - `## Next stage` — next stage number/title or `(last stage)`.
+    Stage PRs link back to each other in their bodies (`Previous: #<n>, Next: #<m>` lines) so a reviewer can navigate the chain.
 - Allowed actions during the run:
-  - **Edit / Write on any project file** (no path whitelist — scope is bounded by the approved plan's file list, not by directory). Editing files outside the plan's list is permitted only when strictly needed to satisfy a step, and MUST be recorded in the final report's `Out-of-plan edits` block with rationale.
+  - **Edit / Write on approved project source files**: scope is bounded first by the shared Resource boundary, then by the approved plan's file list. Editing files outside the plan's list is permitted only when strictly needed to satisfy a step, and MUST be recorded in the final report's `Out-of-plan edits` block with rationale.
   - read-only inspection commands: `git status`, `git diff`, `git log`, `grep`, `rg`, `find`, `cat`, `ls`, file Read tools
   - build, lint, type-check, and test commands (`npm test`, `pytest`, `go build`, `cargo test`, `bash -n`, etc.)
   - **local git operations only**: `git add`, `git commit`. Prefer small commits keyed to plan steps.
@@ -109,10 +120,11 @@
   - **(verifier-specific)** running integration / end-to-end tests that produce non-local side effects (DB writes against a non-local datastore, external API writes, docker compose against a non-isolated environment) unless that exact command is listed in the approved plan's validation set
   - **(verifier-specific)** redirecting tool caches or output to paths outside the worktree — e.g. setting `CARGO_TARGET_DIR`, `PYTEST_CACHE_DIR`, `NODE_OPTIONS=--require=<external>`, or any env var that causes the verifier's command to write outside the worktree's normal build artifact paths
 - Required deliverable shape (final report, in addition to the standard sections):
-  - **Plan link & approval evidence**: path to the approved `final-report.md` and the exact quoted approval marker
+  - **Plan link & approval evidence**: path to the approved `final-report.md`, the exact quoted approval marker, AND the executed stage number / title quoted from the Stage Map row.
   - **Commit list**: each commit's SHA (or short SHA), message, and the plan step it satisfies
   - **Diff summary**: `git diff --stat <base>..HEAD` output, plus a per-file one-line summary of changes
   - **Out-of-plan edits block**: every file edited that was not in the approved plan's file list, with rationale (empty block is acceptable and preferred)
+  - **Stage sidecar evidence**: the JSON payload of `runs/<impl-task-key>/carry/stage-<N>.json` is embedded verbatim in a fenced ```json``` block, AND the `consumers.jsonl` rows this run appended are quoted line-by-line, so reviewers can audit the carry surface without grepping artifact directories.
   - **Validation evidence**: actual command output (stdout/stderr) for every `pre / mid / post` validation command from the plan. Truncated output is acceptable but the command line and exit code MUST be exact. No paraphrasing of test results.
   - **TDD evidence (when applicable)**: for steps that should be TDD-ordered, show the failing-test output BEFORE the implementation commit and the passing-test output AFTER, with commit SHAs framing the transition.
   - **Verifier results**: a section per verifier present in the resolved roster (`Claude verifier`, `Codex verifier`, and `Gemini verifier` when opted in) containing:
@@ -140,5 +152,10 @@
      git diff <base>..HEAD | grep -E '^\+[^+].*\b(TBD|TODO|FIXME|XXX|implement later|handle edge cases|similar to|placeholder)\b' || echo 'clean'
      ```
      Only newly-added lines (those starting with `+` and not part of the `+++` header) are inspected. If output is anything other than `clean`, the run MUST either remove the placeholders before finalising or record an explicit justification per occurrence in the final report.
+- Lead post-stage persistence (BLOCKING — runs after the Executor emits `### Stage Carry Evidence`):
+  - Parse the executor's `### Stage Carry Evidence` JSON block. If absent or unparsable, end with status `contract-violated` and route to a follow-up `error-analysis`.
+  - Write the JSON verbatim to `runs/<impl-task-key>/carry/stage-<N>.json`. Refuse to overwrite an existing file (one stage = one sidecar; re-runs are out of scope for this version).
+  - Append a `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` with `completed_at`, `carry_path`, and the SHA of HEAD. Use the okstra runtime's `consumers_mutex` helper (NOT a raw filesystem write) to honour the lock.
+  - Quote both files' new contents (the sidecar JSON in full, the new consumers row by itself) in the final report's `Stage sidecar evidence` deliverable section.
 - In-phase debugging:
-  - follows the spirit of `systematic-debugging` (root cause before fix), but the executor MUST NOT route to a separate `error-analysis` phase mid-run; if a defect blocks plan progress, the executor records findings and routes to a new run after this one ends.
+  - isolate root cause before changing the fix direction, but the executor MUST NOT route to a separate `error-analysis` phase mid-run; if a defect blocks plan progress, the executor records findings and routes to a new run after this one ends.

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

@@ -0,0 +1,42 @@
+# Improvement Discovery Profile
+
+- Purpose: scan a codebase scope through a fixed lens whitelist and surface ranked improvement candidates with multi-worker consensus classification
+- Required workers:
+  - claude
+  - codex
+  - gemini
+  - report-writer
+- Optional workers (opt-in via `--workers`):
+  - none — every required worker stays required because lens diversity is the load-bearing value of this phase
+{{INCLUDE:_common-contract.md}}
+- Brief consumption (phase-specific addendum — shared rules live in `_common-contract.md` under "Brief handoff contract"):
+  - this phase REQUIRES a codebase-scan brief whose frontmatter contains `scope: codebase`. A brief without that marker is rejected before worker dispatch.
+  - the brief's `priority-lenses` MUST be a non-empty subset (size 1..4) of the lens whitelist defined in `scripts/okstra_ctl/improvement_lenses.py`. Lenses outside the whitelist are rejected.
+  - the brief's `scan-scope` defines the only paths workers may read for candidate evidence. `out-of-scope` paths MUST be ignored even when the codebase is otherwise reachable.
+  - the brief's `candidate-cap` (default 8 if absent, absolute cap 12) bounds the number of rows in `## 4.9 Improvement Candidates`.
+  - Apply the shared reporter-confirmation precondition as written. For this phase any unresolved `intent-check:` / `conversion-block:` row uses `Blocks=next-phase`.
+- Primary focus areas:
+  - candidate discovery within the lens whitelist
+  - per-candidate evidence (path:line) and scope mapping
+  - per-candidate severity / effort / recommended-next-phase
+  - convergence classification (full / partial / contested / worker-unique) across workers
+- Phase 1.5 — Lead reflect-back grilling (runs after Phase 1 context loading and before Phase 4 worker dispatch):
+  - Lead inspects scan-scope paths via `ls` / `Grep` / `Read` to map modules, entry points, dependencies, approximate LOC, and recent commit patterns.
+  - Lead emits a single reflect-back message covering: (a) understood scope per path (one-line summary), (b) understood meaning of each priority lens in this scope, (c) understood out-of-scope rationale, (d) ordered list of N open questions.
+  - For each open question Lead asks ONE `AskUserQuestion` with a `(Recommended)` answer drawn from a codebase-first inspection. Budget: at most 12 questions in this phase.
+  - Stop conditions (OR): all questions resolved / budget exhausted / user signals proceed.
+  - Lead persists the round at `<RUN_DIR>/state/phase-1.5-grilling.md` with one section per question (question / recommended / user answer) and a closing `Resolved scope` / `Resolved lenses` block. Worker prompts use this resolved block as the authoritative scope and lens definition.
+- Decision-tree walk (bounded):
+  - When candidates branch on a structural question (e.g. "is module X meant to own this responsibility?"), resolve via `Read` / `Grep` first. Only escalate to the user inside the Phase 1.5 budget.
+- Expected output emphasis:
+  - the `## 4.9 Improvement Candidates` table populated with rows that obey the 10-column schema from `validators/validate-improvement-report.py` (Cand ID `I-NNN`, Lens from whitelist, 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 as path:line list)
+  - `## 2. Final Verdict` Verdict Token ∈ {`candidates-ready`, `no-candidates`, `blocked`}; Direction `routing`; Next Step "사용자에게 후보 K개 선택 의뢰 (## 4.9 표 참조)"
+  - `## 6. Recommended Next Steps` first entry summarises per-candidate routing and proposes new task-key names of the form `<task-group>/imp-<Cand-ID>`
+- Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
+  - if scan-scope or priority-lenses cannot be made concrete during Phase 1.5, end the run with Verdict Token `blocked`, populate `## 5. Clarification Items` with `Blocks=next-phase` rows, and do not run worker dispatch
+  - every clarification row carries a recommended answer + one-line rationale inside the `Expected form` cell
+- Non-goals:
+  - concrete implementation plans, cost estimates, or code edits for any candidate
+  - inventing lenses outside the whitelist
+  - acting as a final-verification quality gate — this phase is discovery, not acceptance
+  - silently merging out-of-scope findings into in-scope candidates

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

@@ -0,0 +1,92 @@
+<!--
+모든 프로필이 INCLUDE 지시문으로 그대로 포함하는 공유 계약 조각입니다
+(scripts/okstra_ctl/run.py:_expand_profile_includes 참고).
+이 파일을 한 번 수정하면 다음 렌더링 때 모든 프로필에 반영됩니다. 이 파일에는
+phase별 규칙을 추가하지 마세요. phase 규칙은 각 프로필 문서에 둡니다.
+-->
+- Team contract (공통):
+  - `Claude lead`는 종합만 담당하며 `Claude worker`와 분리됩니다. `implementation`에서는 `Executor` 및 verifier와도 구분됩니다.
+  - `Report writer worker`는 final-report 파일의 **작성자**입니다. `Claude lead`는 작성된 초안을 검토하고 승인하며 파일을 직접 작성하지 않습니다. 권위 있는 계약은 `okstra-team-contract`와 `okstra-report-writer`를 참고하세요.
+  - 기본 모델 할당은 중앙화된 기본값에서 해석됩니다. fallback 값은 `Claude lead`/`Report writer worker`=`opus`, `Claude worker`=`sonnet`, `Codex worker`=`gpt-5.5`, `Gemini worker`=`auto`입니다. phase별 override(예: `implementation`의 executor binding)는 각 프로필 문서에 둡니다.
+  - 각 프로필의 `Required workers:` 블록에 나열된 모든 필수 worker는 반드시 시도해야 합니다. 최종 verdict는 각 worker가 결과를 내거나 명시적인 terminal status(`timeout`, `error`, `not-run`)에 도달할 때까지 기다립니다.
+  - 이름 없는 일반 병렬 worker가 필수 역할 roster를 대체해서는 안 되며, 이 roster를 넘어서는 추가 sub-agent dispatch는 허용되지 않습니다.
+- Worker interaction model (공통 - roster만 보고 동작을 추론하기 전에 읽을 것):
+  - 각 프로필의 `Required workers:` 블록은 **roster**이지 동작 계약이 아닙니다. 각 역할의 상호작용 방식은 같은 run 안에서도 운영 phase에 따라 달라집니다.
+  - **Phase 4 / 5 (independent analysis)**: analyser worker(`claude`, `codex`, opt-in된 `gemini`)는 서로의 출력에 접근하지 않고 독립적으로 findings를 생성합니다. `report-writer`는 분석하지 않습니다.
+  - **Phase 5.5 (convergence - workers peer review)**: lead는 각 analyser의 findings를 *다른* analyser들에게 replay하고 최대 `effectiveMaxRounds` 라운드 동안 `AGREE` / `DISAGREE` / `SUPPLEMENT` verdict를 수집합니다. 이 phase에서 worker들은 서로의 findings에 대한 peer reviewer로 행동합니다. lead는 중재하지만 투표하지 않습니다. 라운드 프로토콜, queue invariant, 최종 분류(`full-consensus` / `partial-consensus` / `contested` / `worker-unique`)는 `skills/okstra-convergence/SKILL.md`를 참고하세요.
+  - roster만 보고 "peer review가 일어나지 않는다"고 결론내리지 마세요. analyser worker를 2개 이상 나열한 모든 프로필은 기본적으로 convergence를 실행합니다(`task-manifest.json`의 `convergence.enabled=true`).
+- Tooling - read-only MCP availability (공통):
+  - MCP는 암묵적인 okstra context가 아닙니다. task brief가 이번 run의 source material로 명시적으로 나열한 MCP server만 조회합니다. MCP에서 파생한 모든 finding은 server, table, 사용한 SELECT를 인용해야 합니다. MCP는 절대 write path로 사용해서는 안 됩니다. schema/data mutation은 사람이 검토하는 repository migration file을 통해 수행합니다.
+- Resource boundary (공통 - artifact-home rule):
+  - okstra가 소유하는 project artifact는 `<PROJECT_ROOT>/.project-docs/okstra/**` 아래에만 둡니다. 해당 subtree의 `project.json`, task bundle, run artifact, `glossary.md`, `decisions/`가 okstra memory의 canonical source입니다.
+  - `<PROJECT_ROOT>/.project-docs/okstra/**` 밖 path는 task brief의 `Source Material` 또는 `Reporter Confirmations`가 명시적으로 cite한 경우에만 source material로 읽습니다. 이 path들은 okstra memory가 아닙니다.
+  - create, modify, delete는 `<PROJECT_ROOT>/.project-docs/okstra/**` 안에서만 수행합니다. brief가 특정 non-okstra edit를 verbatim으로 요청한 경우에만 예외이며, 수행 phase는 final report에 사용자 지시 원문을 인용해야 합니다. implementation source edit도 승인된 implementation plan이 추가로 필요합니다.
+- Authority & permissions assumption (모든 okstra task-type에 적용):
+  - **사용자와 사용자 팀이 예상된 작업, 진행 중인 작업, follow-up 작업에 필요한 모든 권한과 permission을 보유하고 있다고 가정합니다.** task brief가 명시적으로 달리 말하지 않는 한 external approval, third-party access grant, role/IAM permission, organisational sign-off, legal/compliance review, vendor coordination, "verify access exists" 단계는 이미 충족된 것으로 취급합니다.
+  - 이런 항목을 routing decision, missing-materials list, clarification question, option trade-off, dependency/migration risk, validation checklist, rollout plan, acceptance blocker, residual risk, release recommendation, `## 5. Clarification Items` table, day/effort estimate에 추가하지 마세요. 일정 연장의 정당한 근거가 아닙니다.
+  - okstra 내부 phase handoff(예: `implementation-planning`의 `User Approval Request` 블록)는 영향을 받지 않습니다. 이는 사용자 본인이 승인하는 것이며 외부 coordination 없이 진행됩니다.
+  - 이 규칙은 phase별 Forbidden actions list를 완화하지 않습니다. 각 프로필 문서의 safety rule은 사용자 권한과 무관하게 계속 적용됩니다.
+- Anti-escalation rule (공통):
+  - "다음 단계 진행해" 또는 동등한 사용자 표현을 *다른* lifecycle phase를 시작하라는 authorisation으로 취급하는 것은 금지됩니다. 다음 phase는 새 `--task-type`으로 실행된 별도의 okstra run에서만 시작됩니다. 각 프로필 문서는 자기 범위 안에서 이를 더 제한할 수 있습니다.
+- Phase wrap-up - worker trace pane disposition (공통, 사용자에게 제어권을 돌려주기 직전 *마지막* 단계여야 함):
+  - Codex / Gemini worker wrapper는 lead의 tmux session에 `<cli>-<role>-<pid>-trace` 제목의 `tail -F` trace pane을 생성합니다(예: `codex-worker-93421-trace`, `gemini-executor-93422-trace`). 대응하는 caller(worker) pane 제목은 `<cli>-<role>-<pid>`이므로 공유 `<pid>` suffix로 worker와 trace pair를 맞출 수 있습니다. 이 pane들은 operator가 최종 출력을 스크롤해 볼 수 있도록 모든 worker invocation 이후에도 의도적으로 남지만, phase가 누적되면 화면을 어지럽힙니다.
+  - `$TMUX_PANE`이 설정되어 있으면, final-report 파일 작성과 routing recommendation 발행이 끝난 뒤 lead는 `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list`를 정확히 한 번 실행해야 합니다. 출력은 이 Claude session에 등록된 모든 trace pane의 tab-separated `<pane_id>\t<pane_title>` 목록입니다.
+  - 목록이 비어 있으면 질문을 건너뜁니다. 물어볼 것이 없습니다.
+  - 그렇지 않으면 lead는 phase 완료를 선언하기 **전에** 사용자에게 엄격한 binary choice를 제시해야 합니다. 다음 형태의 prompt를 하나 사용하세요(나머지 run이 영어라면 영어도 허용되지만 한국어 권장):
+    > 현재 phase 종료 시점입니다. 다음 worker trace pane 이 열려 있습니다 — 닫을까요?
+    > <인용된 `--list` 출력>
+    > (예) 모두 닫기 / (아니오) 그대로 두기
+  - `예` / `y` / `close`이면 `$HOME/.okstra/bin/okstra-trace-cleanup.sh`(인자 없음)를 실행하고 kill count를 한 문장으로 보고합니다.
+  - `아니오` / `n` / `keep`이면 pane을 그대로 둡니다. Claude `/exit`가 `SessionEnd` hook을 실행할 때 자동으로 정리된다고 사용자에게 알려줍니다.
+  - 질문은 깨끗한 yes/no여야 합니다. "일부 닫기 / 일부 유지" 같은 부분 선택지를 제공하지 말고, "codex pane만 닫기" 같은 대안을 제안하지 마세요. 전체 집합 단위 결정이 wrap-up을 예측 가능하게 유지합니다.
+  - 이 단계는 모든 phase(`requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`)에 필수입니다. `$TMUX_PANE`이 unset이면(lead가 tmux 밖에서 실행 중) 조용히 skip합니다. 이 경우 lead는 synthetic pane list를 만들어내면 안 됩니다.
+- Brief handoff contract (공통 - `okstra-brief`가 만든 task brief를 run이 소비할 때마다 적용):
+  - brief는 **pre-discovery artifact**입니다. domain-reporter의 말(비전문가 또는 개발자)을 expert가 소비할 수 있는 형태로 변환하여 이 phase와 이후 phase가 operator에게 추가 질문 없이 실행되도록 합니다. brief는 solution decision의 권위가 아니며, reporter intent의 권위입니다.
+  - **Reporter confirmation precondition (BLOCKING)**: brief frontmatter에는 `okstra-brief` Step 6.5가 설정한 `reporter-confirmations: <complete | partial | pending | skipped>`가 있습니다. brief를 소비하는 모든 phase는 분석 전에 이 field를 읽어야 합니다. 처리 matrix는 다음과 같습니다.
+    - `complete` -> 정상 진행.
+    - `partial` -> 진행하되, 아직 표시되지 않은 `intent-check:` / `conversion-block:` row는 `skipped` branch로 취급합니다.
+    - `skipped` -> 누락된 답을 조용히 추론하지 마세요. 표시되지 않은 각 `intent-check:` / `conversion-block:` row를 이 run의 `## 5. Clarification Items`로 승격하고 `Kind=decision`을 사용합니다. `implementation-planning`에서는 approval을 gate하므로 `Blocks=approval`, 그 외에는 `Blocks=next-phase`를 사용합니다. 권장 답변은 brief의 대응 내용에서 가져오고 `보고자 직접 확인 권장`이라고 명확히 표시합니다.
+    - `pending`(또는 field missing) -> analysis를 ABORT합니다. `Verdict Card`를 `Verdict Token = blocked` + `Direction = hold`로 렌더링하고, pending row를 요약하는 단일 `## Reporter Confirmation Required` 블록을 작성합니다(앞 번호 없음). `## 5. Clarification Items` table에는 pending item마다 한 row를 넣고, `implementation-planning`에서는 `Blocks=approval`, 그 외에는 `Blocks=next-phase`를 사용합니다. operator는 `okstra-brief` Step 6.5를 다시 실행해야 합니다. 이 경우 `## 0.`을 emit하지 마세요. Section 0은 clarification-response carry-in 전용입니다.
+    `Open Questions` row의 `[CONFIRMED <YYYY-MM-DD> → RC-N]` marker는 reporter가 해당 row에 답했다는 per-row signal입니다. 답변 원문은 brief의 `## Reporter Confirmations` 아래에 있습니다.
+  - `Source Material`은 reporter-verbatim입니다. 이를 paraphrase, summarize, reorder, restructure하지 마세요. 필요할 때 직접 인용합니다.
+  - `Augmentation` entry에는 `evidence-link`, `format-conversion`, `terminology-mapping`, `intent-inference` 네 label 중 하나가 붙습니다. 다음과 같이 취급합니다.
+    - `evidence-link` / `format-conversion` -> 재검증 없이 신뢰합니다.
+    - `terminology-mapping` -> `<PROJECT_ROOT>/.project-docs/okstra/glossary.md`(권위 있음)에 비추어 검증합니다. mapping이 없거나 glossary와 모순되면 `Clarification Items` row를 올립니다.
+    - `intent-inference` -> **검증되지 않은 가설**로 취급합니다. 모든 `intent-inference` augmentation은 brief에서 `intent-check:` prefix가 붙은 `Open Questions` row와 pair여야 합니다. codebase inspection으로 inference를 확인하거나 반박할 수 있는 경우가 아니라면, 해당 row를 이 run의 `## 5. Clarification Items` table에 `Kind=decision, Blocks=next-phase`(`implementation-planning`에서는 `Blocks=approval`)로 승격하고 권장 답변은 "보고자에게 직접 확인 후 응답"으로 설정합니다.
+  - `Open Questions` row prefix는 signal입니다. 승격할 때 제거하지 마세요.
+    - `intent-check:` -> `Kind=decision`, recommended answer = reporter confirmation. 이 layer에서 `intent-check:`를 추론으로 조용히 해결해서는 절대 안 됩니다.
+    - `terminology:` -> `Kind=decision`, recommended answer = `<PROJECT_ROOT>/.project-docs/okstra/glossary.md`의 canonical term(또는 "extend okstra glossary via brief Step 4.5").
+    - `conversion-block:` -> `Kind=decision`, recommended answer = "보고자에게 직접 확인". brief가 translation failed를 명시적으로 알리는 것입니다. reporter가 명확히 하기 전까지 추가 추론은 금지됩니다.
+    - `adr-candidate:` -> `implementation-planning`에서 처리합니다. 수정 없이 carry forward합니다. 승인된 decision file은 `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`에만 저장합니다.
+    - `general:` -> free-form입니다. 표준 `Clarification Items` 규칙에 따라 분류합니다.
+  - 이 run의 어떤 decision이 brief의 `Source Material`과 모순되면 `Clarification Items` row를 통해 reporter에게 다시 올려야 합니다. 조용히 덮어쓰면 안 됩니다. reporter와의 불일치는 해당 row가 해결된 뒤에만 허용됩니다.
+  - 이 계약은 brief consumption에 대한 단일 권위입니다. phase-specific addendum은 이 규칙을 *강화*할 수 있지만 완화할 수 없습니다.
+- Clarification request policy (공통 - 프로필이 `## 5. Clarification Items`를 사용할 때마다 적용):
+  - **Canonical column schema (SSOT - `templates/reports/final-report.template.md` §5.1과 정확히 일치해야 함):** 모든 `## 5. Clarification Items` table은 정확히 다음 8개 column을 이 순서로 가집니다.
+    `| ID | Ticket ID | Kind | Statement | Expected form | Blocks | Status | User input |`.
+    프로필별 addendum은 cell content를 강화할 수 있지만 column을 추가, 제거, rename, reorder해서는 안 됩니다. `ID` cell은 `C-NNN`(3자리 zero-padded)을 사용하고, `Status` cell은 `{open, answered, resolved, obsolete}` 중 하나이며, `Kind` / `Blocks` legal value는 아래에 나열됩니다.
+  - section 5는 `final-report-template.md` 기준 **단일 unified table**입니다. 사용자가 파일을 첨부해야 하든, option을 골라야 하든, 단일 숫자/path를 제공해야 하든 모든 clarification item은 이 table의 한 row입니다. sub-section(`5.1 추가 자료 요청` / `5.2 사용자 확인 질문` / `4.5.9 Open Questions`)으로 쪼개지 말고, report 다른 곳에 parallel table을 만들지 말고, 같은 item을 top-of-report `User Approval Request (사용자 승인 게이트)` block이나 다른 section에 중복하지 마세요. 이를 다시 도입하면 validator가 실패합니다.
+  - 각 row의 `Kind` column은 `{material, decision, data-point}` 중 하나를 고릅니다. `material`은 사용자가 첨부해야 하는 파일/snapshot/log/screenshot입니다(`User input` cell에는 path 또는 URL이 들어갑니다). `decision`은 사용자만 할 수 있는 선택 및 yes/no confirmation입니다. `data-point`는 사용자가 inline으로 답할 수 있는 단일 숫자, ID, 날짜, 짧은 문자열입니다. "yes/no + yes이면 file path"가 섞인 item은 `Kind=material` 한 row로 표현하고 결합된 expectation을 `Expected form`에 씁니다.
+  - 각 row의 `Blocks` column은 `{approval, next-phase, none}` 중 하나를 고릅니다. `approval`은 approval action을 gate하는 item, 특히 `implementation-planning`의 User Approval Request용으로 예약됩니다. `implementation-planning` 밖에서는 unresolved brief reporter-confirmation row가 `next-phase`를 사용합니다. `next-phase`는 다음 run이 깨끗하게 시작되는 것을 막습니다. `none`은 정보/감사용입니다.
+  - 모든 entry는 비개발자가 추가 맥락 없이 실행할 수 있도록 완전하고 설명적인 문장으로 작성합니다. 약어와 내부 jargon을 피하세요. `Statement` cell은 *무엇*이 필요한지, 그 답변/첨부가 *왜* 다음 단계를 바꾸는지, (`material`의 경우) 사용자가 그것을 *어디에서 찾고 어디에 둘 수 있는지*를 말해야 합니다. `Expected form` cell은 답변 형태(예/아니오, 보기 중 하나, 숫자/날짜, 파일 경로, 짧은 서술 등)를 말해야 하며, 해당하면 구체적인 선택지를 제공합니다.
+  - phase가 recommended answer, alternative, evidence-check note를 요구하더라도 기존 8-column schema 안에 넣습니다. evidence note는 `Statement`에 `Evidence checked: <path:line>` 또는 `Evidence checked: none — <human-only reason>` 형태로 적고, recommendation/options는 `Expected form`에 `Recommended: <answer> — <rationale>; Alternatives: <options>` 형태로 적습니다. `Recommended`, `Evidence`, `Alternatives`, `evidence-checked` column을 추가하지 마세요.
+  - 같은 `final-report.md` 파일이 다음 run으로 carry되는 canonical artifact입니다. 사용자는 rerun 전에 답을 inline으로 append합니다. 권장 turnaround는 `scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>`입니다(최신 report를 `$EDITOR`로 열고, 저장 후 `--clarification-response` carry-in으로 같은 phase를 자동 rerun). lower-level 형식인 `--clarification-response <path>`는 scripted run용으로 계속 사용할 수 있습니다.
+  - 이 run에 clarification response가 carry-in되었으면 조건부 `## 0. Clarification Response Carried In From Previous Run` section을 렌더링합니다(template의 `RENDER_IF` guard가 활성화됨). 이전 report의 `## 5. Clarification Items` table에 있는 모든 `C-*` row를 확인하고, 새 evidence와 대조해 각 row의 `Status`를 `resolved` 또는 `obsolete`로 갱신한 뒤 다음 decision/verdict를 발행합니다. carry-in path가 없으면 `## 0.` heading 전체를 생략합니다. 빈 Section 0 stub(예: "No prior clarification response was provided for this run.")을 emit하면 validator가 실패합니다.
+- Verdict Card (공통 - 모든 final-report에 적용):
+  - report 상단의 `## Verdict Card` block은 모든 final-report에서 필수입니다. `Verdict Token`, `Direction`, `Next Step` cell은 `## 2. Final Verdict`의 대응 cell 및 `## 6. Recommended Next Steps`의 첫 item과 byte-match해야 합니다. validator는 card를 비권위 index로 취급합니다. card 값이 권위 section과 다르면 run은 `contract-violated`입니다.
+- Cross-worker traceability (공통 - 모든 analysis worker output 및 lead의 final-report `## 1.` / `## 3.` table에 적용):
+  - **Worker-side item IDs (free-form but unique within the worker).** analysis worker 출력의 sections 1-5(및 선택 section 6)에 있는 모든 row item은 해당 worker result file 안에서 고유한 item ID를 가져야 합니다. ID convention은 worker가 선택합니다. 제안 schema에 따른 `F-001` / `F-002`, Codex가 자주 쓰는 `1.1` / `1.2` / `1.3`, 또는 다른 형태 모두 가능하지만, table-form item에서는 leading column으로, bullet/numbered item에서는 `[<ID>]` prefix로 나타나야 합니다. ID 없는 finding을 emit하는 worker는 cross-worker reconciliation을 불가능하게 만듭니다.
+  - **Lead-side ID assignment + source preservation.** lead(또는 `report-writer-worker`)가 worker output에서 `## 1.1 Consensus` / `## 1.2 Differences` / `## 3.1 Primary Evidence` row를 종합할 때 lead는 새 `C-NNN` / `D-NNN` / `E-NNN` row ID를 할당합니다. `Source items` column(또는 template이 아직 `Supporting workers` / `Workers (position)` / `Source`라 부르는 같은 column)은 기여한 모든 worker:item pair를 나열해야 합니다(예: `claude:F-001, codex:1.1, gemini:F-3`). 이렇게 하면 reviewer가 모든 worker-results file을 다시 읽지 않고도 종합 row를 각 worker 원문으로 추적할 수 있습니다. item ID 없는 bare worker name(예: `claude, codex, gemini`)은 이 table에서 deprecated입니다. validator는 아직 실패시키지 않지만 readability pass는 이를 contract violation으로 취급합니다.
+  - **Why this matters.** 실제 run에서 `claude=F-1..F-11`, `codex=1.1..1.8`, `gemini=F-3..F-9`처럼 세 가지 incompatible ID scheme이 있었습니다. lead가 `C-1..C-8`을 종합하면서 `C-3`이 "어느 worker file의 어느 문장"으로 돌아가는 링크가 사라졌습니다. Source-item preservation은 모든 worker에게 단일 ID prefix를 강제하지 않고도 그 링크를 복원합니다.
+- Audit sidecar (공통 - 모든 analysis-worker output 및 모든 final-report에 적용):
+  - Reading Confirmation line(입력 파일을 끝까지 읽었음을 확인하는 짧은 line)은 **worker audit sidecar**인 `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md`에 둡니다. worker의 main worker-results file에는 두지 않습니다. worker-results body는 section 1(Findings)에서 시작합니다. worker-results file에 `## 0. Reading Confirmation` heading이 있으면 validator가 실패합니다.
+  - audit sidecar에는 worker가 기록하고 싶은 다른 meta(tool-call count, MCP query summary, timing note 등)도 담습니다. lead의 final-report는 이 내용을 중복하지 않습니다. 이는 validator와 post-run audit tooling이 소비하는 것이며 end-user reader용이 아닙니다.
+
+- Markdown authoring (공통 - okstra template/schema가 이미 지배하지 않는 markdown 문서에 적용):
+  - ad-hoc markdown document는 `Index` section으로 시작하는 것을 권장합니다. final-report, worker-results, brief처럼 template이 지배하는 artifact는 자기 schema를 먼저 따릅니다.
+  - 사용자가 명시한 목적과 직접 관련된 요구사항을 충족하는 데 필요한 정보만 포함합니다.
+  - 사용자에게 지정받은 section, format, tone, scope와 필수 `Index` section만 따릅니다.
+  - task instruction 또는 work order를 작성할 때는 작업 범위를 명확하고 구체적으로 정의하고, 관련 deliverable, acceptance criteria, verification step을 포함합니다.
+  - 포함되는 작업을 말하는 방식으로 scope를 긍정적으로 정의합니다. 정의된 scope 밖의 작업은 수행하지 않습니다.
+  - 명시적으로 지정되지 않은 구조나 내용을 추가하기 전에는 필수 `Index` section을 제외하고 사용자 확인을 요청합니다.
+  - 완료 전에 문서가 요청된 scope와 정확히 일치하고 관련 없는 내용을 포함하지 않는지 검증합니다.

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

@@ -0,0 +1,36 @@
+# Error Analysis Profile (오류 분석 프로필)
+
+- Purpose (목적): 보고된 error 또는 incident를 분석하고, 가능한 원인, 누락 evidence, validation path를 식별합니다.
+- 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`를 사용합니다. confirmed되지 않은 inference는 label된 hypothesis로만 사용할 수 있습니다.
+  - `Source Material`에 있는 reporter의 symptom description이 재현할 대상에 대한 ground truth입니다. report에서 symptom을 말할 때 paraphrase하지 말고 인용합니다.
+  - symptom을 다시 성격 규정하는 `intent-inference` augmentation(예: "가끔 안 됨"을 "특정 code path의 intermittent failure"로 분류)은 confirmed symptom이 아니라 **hypothesis**입니다. matching `intent-check:` row에 `[CONFIRMED …]`가 있으면 confirmation을 symptom으로 취급합니다. 그렇지 않으면 위 precondition의 `skipped` branch를 따르고 root-cause analysis에서 inference를 hypothesis로 label합니다.
+  - `conversion-block:` row는 brief가 reporter statement를 project vocabulary로 mapping하지 못했다는 뜻입니다. 이 phase에서 누락된 mapping을 invent하지 마세요. 위 precondition이 이미 처리합니다.
+- Primary focus areas:
+  - symptom 및 trigger clarification
+  - root-cause candidate
+  - reproduction gap
+  - 기록된 expected value를 위반하는 config file 또는 deployment manifest
+  - prior analysis의 misleading assumption
+  - validation 및 rollback risk
+- Expected output emphasis:
+  - evidence-backed cause analysis
+  - uncertainty boundary
+  - practical next diagnostic step
+- Clarification request policy (phase-specific addenda - 공유 policy는 `_common-contract.md`에 있음):
+  - final report 작성 시점에 blocking uncertainty가 남아 있으면 `final-report-template.md`의 `## 5. Clarification Items`를 채웁니다(단일 unified table; 다음 run이 없이 시작할 수 없는 item은 `Blocks=next-phase`).
+  - 약어보다 쉬운 한국어를 선호합니다(예: "QPS" 대신 "초당 평균 요청 수", "repro" 대신 "재현 절차").
+  - 모든 clarification row는 `Expected form` cell 안에 recommended answer + 한 줄 rationale을 가져야 합니다. recommendation 없는 row는 half-formed로 rejected됩니다.
+  - **Codebase-first ambiguity resolution (defect rule)**: repro, file behavior, symbol semantics에 관한 ambiguity 중 `Read` / `Grep` / log inspection으로 답할 수 있는 것은 반드시 그렇게 해결하고 file:line(또는 log-line) evidence로 기록해야 합니다. codebase 또는 shipped log가 이미 답하는 내용을 clarification row로 쓰는 것은 이 phase의 defect입니다.
+  - **Evidence note는 `Statement` 안에 작성**: 모든 clarification row는 `Statement` cell에 `Evidence checked: <path:line>` 또는 `Evidence checked: none — <reporter-only reason>`을 포함합니다. `none`은 row 성격이 "reporter만 답할 수 있음"(reporter-side data, business priority, reporter가 관찰한 environment)일 때만 허용됩니다. code나 log로 답할 수 있었던 row가 `none`이면 defect입니다.
+- Non-goals:
+  - cause validation에 필요한 경우가 아니면 implementation detail을 다루지 않습니다.
+  - **source code edit, build, migration, deployment** - 이 run은 evidence와 cause analysis만 생산합니다. fix는 후속 `implementation-planning` run과 그 뒤의 `implementation` run에 속합니다.
+  - 이 run은 사용자 표현과 무관하게 `error-analysis`에 머뭅니다. 공유 anti-escalation rule이 적용됩니다.

package/runtime/prompts/profiles/kr/final-verification.md

@@ -0,0 +1,48 @@
+# Final Verification Profile (최종 검증 프로필)
+
+- Purpose (목적): final acceptance 전에 완료된 작업을 분석하고 남은 defect, omission, delivery risk를 식별합니다.
+- Required workers:
+  - claude
+  - codex
+  - report-writer
+- Optional workers (opt-in via `--workers`):
+  - gemini - roster에 추가되면 analyser set에 참여합니다. 기본값은 omitted입니다.
+{{INCLUDE:_common-contract.md}}
+- Primary focus areas:
+  - requirement coverage
+  - delivered config file 및 deployment manifest가 기록된 expected value를 만족하는지 여부
+  - unresolved edge case
+  - regression risk
+  - documentation 또는 rollout gap
+  - change가 production에서 여전히 실패할 수 있는 이유
+- Expected output emphasis:
+  - acceptance blocker
+  - residual risk
+  - final release recommendation
+- Pre-verification entry gate (필수 - 하나라도 실패하면 시작 거부):
+  - task brief는 `## Source Implementation Report` 아래 originating `implementation` final-report path를 반드시 cite해야 합니다. lead는 해당 file을 열고 `Plan link & approval evidence`, `Commit list`, `Diff summary`, `Validation evidence`, `Routing recommendation for final-verification`가 포함되어 있는지 확인합니다.
+  - task brief는 verification 대상 worktree / checkout과 implementation base ref를 식별해야 합니다. implementation report가 task worktree를 naming하면 final-verification은 caller의 original checkout이 아니라 같은 worktree를 inspect해야 합니다.
+  - lead는 worker dispatch 전에 verification worktree에서 `git rev-parse HEAD`, `git status --short`, `git diff --stat <implementation-base>..HEAD`를 capture해야 합니다. 이 값들은 verification target이며 final report에 cite되어야 합니다.
+  - cited implementation report가 없거나, delivered code change에 대한 commit이 없거나, current checkout이 implementation report의 commit list / diff summary와 match하지 않으면 run은 status `blocked`로 끝나고 ambiguous target을 검증하는 대신 `implementation` 또는 `implementation-planning`으로 route해야 합니다.
+- Required deliverable shape (표준 section에 더해 final report에 필요):
+  - **Source Implementation Report**: originating `implementation` final-report file의 relative path, verification target으로 사용한 quoted commit list / diff summary, inspect한 worktree path, run start에 capture한 base/head SHA.
+  - **Verdict vocabulary**: Section 2(`Final Verdict`)는 value가 정확히 `accepted`, `conditional-accept`, `blocked` 중 하나인 `Verdict Token` field를 포함해야 합니다. `conditional-accept`에는 explicit하고 exhaustive한 condition list가 필요합니다. ambiguous verdict("looks good", "mostly ready")는 허용되지 않습니다.
+  - **Acceptance Blockers block**(section 4 아래): blocker마다 `id`, `severity`(`critical` / `major` / `minor`), evidence(file path, log excerpt, test output), recommended follow-up phase(`error-analysis` 또는 `implementation-planning`)를 담은 row 하나. empty block은 허용되고 선호됩니다. 단일 line `- No acceptance blockers found.`를 렌더링합니다.
+  - **Residual Risk block**(section 4 아래): blocker는 아니지만 track해야 하는 risk. 각 risk에는 mitigation owner와 blocker로 escalation되는 trigger가 있어야 합니다.
+  - **Validation Evidence**: originating plan 또는 task brief의 모든 requirement에 대해 coverage를 증명하는 artifact(commit SHA, test output, log line, MCP SELECT result)를 cite합니다. artifact 없는 paraphrased "verified" claim은 rejected됩니다.
+  - **Read-only command log**: 이 run 중 실행한 pre-existing test/validation command는 exact command line과 exit code와 함께 나열해야 합니다. 여기에 mutating command가 나타나면 안 됩니다.
+  - **Two-tier command lookup (`implementation`과 공유):** 이 phase가 자체 independent re-validation을 수행할 때 command source는 `implementation` verifier가 사용하는 동일한 두 tier입니다. Tier 1은 originating task brief / approved plan의 `validation` set, Tier 2는 `<PROJECT_ROOT>/.project-docs/okstra/project.json` 아래 `qaCommands`입니다. manifest file에서 tool을 auto-detect하는 것은 금지됩니다. missing tier는 `qa-command not configured: <category>`로 기록하며 guess를 trigger하지 않습니다. `cmd` deny-list(`--fix`, `--write`, ` -w`, ` -u`, `--snapshot-update`, `INSTA_UPDATE=<not-no>`, `cargo update`, `npm install` without `ci` 등)는 동일하게 enforce됩니다. NOTE: runtime fail-fast validation(`okstra_ctl.qa_commands.validate_qa_commands`)은 `--task-type implementation` run-prep에서만 fire되므로, 이 phase는 각 `qaCommands` entry를 실행하기 전에 deny-list에 대해 self-check해야 합니다. denied token이 있으면 command를 skip하고 `Read-only command log` line `qa-command rejected (denied token: <token>): <label>`로 기록합니다.
+  - **Routing recommendation**: verdict와 blocker list에 연결된 다음 안전 phase(`done`, `error-analysis`, `implementation-planning`)에 대한 짧은 note.
+- Clarification request policy (phase-specific addendum - 공유 policy는 `_common-contract.md`에 있음):
+  - blocker가 사용자만 제공할 수 있는 정보(deployment intent, intended target environment, business-rule interpretation)에 달려 있을 때만 `## 5. Clarification Items`를 채웁니다. release-handoff로 계속 가는 것을 gate하는 item에는 `Blocks=next-phase`를 사용합니다.
+- Self-review pass before finalising the report (`Claude lead`가 실행. generic subagent에 위임하지 말 것):
+  1. **Verdict precision** - section 2는 세 allowed verdict token 중 하나를 가진 `Verdict Token`을 포함합니다. `conditional-accept`는 모든 condition을 actionable item으로 나열합니다.
+  2. **Blocker traceability** - 모든 blocker는 concrete artifact(file:line, log excerpt, test exit code, MCP SELECT)를 cite합니다. evidence 없는 blocker는 residual risk로 demote하거나 제거합니다.
+  3. **Coverage check** - originating plan/task brief의 모든 requirement는 artifact와 함께 covered로 표시되거나 blocker로 나열되어야 합니다. silent omission 금지.
+  4. **Verifier dissent preserved** - worker가 다른 verdict에 도달하면 disagreement가 section 1.2에 보이는가? synthesis가 아무것도 숨기지 않는가?
+  5. **No-mutation audit** - run session transcript에서 Edit / Write / mutating Bash command 발생 여부를 scan합니다. 발생했다면 run이 implementation으로 넘어간 것이므로 반드시 re-route해야 합니다. evidence를 조용히 제거하지 마세요.
+- Non-goals:
+  - delivered scope를 넘어서는 unrelated refactor 제안
+  - **source code edit, follow-up bug fix, scope expansion** - 이 run은 verdict만 렌더링합니다. 여기서 발견된 defect는 새 `error-analysis` 또는 `implementation-planning` run의 input이 됩니다.
+  - pre-existing test 또는 validation command의 read-only execution은 허용되지만 source, schema, deployment state를 mutate하는 command는 금지됩니다.
+  - 이 run은 발견된 issue를 기록하고 종료합니다. 공유 anti-escalation rule은 사용자 표현과 무관하게 in-run fix를 금지합니다.