okstra 0.206.0 → 0.207.0

package/runtime/python/okstra_ctl/phases/implementation/spec.md

@@ -0,0 +1,238 @@
+# implementation process
+
+## Index
+
+- [1. Purpose](#1-purpose)
+- [2. okstra-run wizard flow](#2-okstra-run-wizard-flow)
+- [Carry-in](#carry-in)
+- [3. runtime gate](#3-runtime-gate)
+  - [3.1 design-preparation preflight](#31-design-preparation-preflight)
+- [4. executor and verifier](#4-executor-and-verifier)
+- [5. stage and consumers](#5-stage-and-consumers)
+- [6. Deliverables](#6-deliverables)
+- [7. Forbidden actions](#7-forbidden-actions)
+- [8. Verified code](#8-verified-code)
+
+## 1. Purpose
+
+`implementation` executes an approved `implementation-planning` final report into actual code changes and local commits. Source edit is allowed only in this phase, but scope is limited to the approved plan and recorded out-of-plan justification.
+
+## 2. okstra-run wizard flow
+
+```mermaid
+flowchart TD
+    Start[/okstra-run/] --> Common[common task identity flow]
+    Common --> Type[task-type = implementation]
+    Type --> Worktree{active task worktree?}
+    Worktree -->|yes| PlanPick[approved plan pick/text]
+    Worktree -->|no| BaseRef[base-ref pick/text]
+    BaseRef --> PlanPick
+    PlanPick --> Approved{APPROVED marker present?}
+    Approved -->|no| Retry[re-prompt same step]
+    Approved -->|yes| Stage[stage multi-pick<br/>ready/active markers]
+    Stage --> Chain[render-args<br/>stage + chain-stages]
+    Chain --> RoleCount[role-count min..max<br/>omit uses recommended; skip if min==max]
+    RoleCount --> RoleModel[role-model provider/model per slot]
+    RoleModel --> RoleAdd[min=0 roles via role-add only<br/>default skip]
+    RoleAdd --> Extras[directive, related tasks, clarification]
+    Extras --> Confirm
+    Confirm --> Render[render-bundle]
+```
+
+Launch selection uses role slots and model refs only: current-session lead is this session (listed on the confirmation summary), then each static role's count in `min..max` (default **recommended**; the count step is skipped when `min == max`), then one `provider/model` per slot. Roles with `min = 0` stay closed unless the user opens them with role-add (default skip). Duplicate model refs in the same role are rejected. There is no provider roster multi-pick and no defaults-vs-customize fork. `executor` is only a compatibility alias for `implementer` in model refs; implementer slots are chosen through role-count / role-model. Dynamic verifiers are not chosen at launch. `--workers` is a CLI compatibility input only, not a launch picker. `stage_pick` is a multi-pick that shows done/in-progress/ready/waiting status. The selected stage set goes through dependency closure and topological sort into a `chain-stages` CSV, and each actual run executes only one of those stages.
+
+The current okstra-run wizard path does not expose `--approve` that directly flips the approval checkbox. The plan file must already have a recognized approval marker.
+
+## Carry-in
+
+Three facts about what reaches an implementation run from its approved plan, gathered
+here because they were previously readable only by tracing the runtime sources.
+
+- **What is attached automatically.** The user's answers to the approved plan's `## 1.
+  Clarification Items` rows — the `user-response-*.md` sidecars under
+  `runs/implementation-planning/user-responses/`, a sibling of the directory holding the
+  plan itself — are collected into `instruction-set/clarification-response.md`. Those
+  sidecars are written by the user, not by the report renderer. The report HTML's `Export
+  user response` button downloads a file the user then saves there. The in-session flow
+  reads `user-response list-view` and `user-response show-view --report <path>
+  --project-root <root>`, then uses `user-response begin`, typed `user-response answer`
+  and decision commands, and `user-response finalize` to publish the sidecar. The
+  renderer at most pre-creates that directory empty so the user does not
+  have to; it never puts a sidecar in it.
+  The plan document is *not* copied: it reaches the run as the `--approved-plan` path and
+  the executor re-reads it there. An explicit `--clarification-response` wins when given;
+  the automatic attachment is the fallback for an implementation run that supplies none
+  (`scripts/okstra_ctl/run.py`, the `implementation` carry-in branch).
+- **Who reads it, and when.** The executor, before its first edit
+  (`scripts/okstra_ctl/phases/implementation/instructions/_implementation-executor.md`). A CLI executor (codex/antigravity)
+  cannot reach that path from inside its sandbox, so the lead transcribes the file's body
+  into the dispatched executor prompt — a path reference alone never arrives.
+- **What happens when an answer contradicts the plan.** Each answer is an authoritative
+  refinement of its matching row's scope, but an answer that contradicts the approved plan
+  or expands scope beyond it is a re-plan trigger: it routes to a new
+  `implementation-planning` run rather than being absorbed silently mid-run. Quietly
+  widening scope inside an implementation run is what this branch exists to prevent.
+
+## 3. runtime gate
+
+```mermaid
+sequenceDiagram
+    participant W as okstra-run
+    participant P as prepare_task_bundle
+    participant Plan as approved final-report
+    participant QA as project.json qaCommands
+    participant Stage as stage target policy
+    participant Reg as worktree registry
+    participant WT as stage worktree
+
+    W->>P: task-type=implementation, approved-plan, stage, executor
+    P->>Plan: file exists?
+    P->>Plan: approval marker regex matches?
+    P->>Plan: unresolved Blocks=approval rows?
+    P->>Stage: build Stage Lifecycle Snapshot
+    P->>Reg: read active stage-key reservations
+    P->>Stage: select exactly one ready stage
+    P->>Plan: resolve selected stage design preparation
+    P->>WT: provision stage-N worktree + branch
+    P->>QA: validate qaCommands deny-list
+    P->>P: executor provider in resolved roster?
+    P->>P: namespace run artifacts under stage-N
+    P-->>W: prepared implementation prompt or PrepareError
+```
+
+`--approve` exists in the Python runtime, but the okstra-run wizard does not emit it as args. On the shell path, `--approve` sets the report record `frontmatter.approved` to `true` and then follows the same validation path.
+
+### 3.1 design-preparation preflight
+
+Right after stage selection, before worktree provisioning and appending `status:"started"` to `consumers.jsonl`, it resolves the design preparation of the approved plan. The resolver reads only items whose `stageRefs` includes the selected stage, so an undecided decision in another stage does not block the current run.
+
+| outcome | runtime behavior |
+|---|---|
+| `proceed` | Inject the effective AI proposal, confirmed override, guardrail, and provisional working assumption into the executor prompt as `DESIGN_PREP_CONTEXT`, and create the worktree. |
+| `wait_for_input` | Stop with `stage <N> waits for design input: ...; <request paths>`. Do not create the worktree or the started consumer row. |
+| `replan` | Stop with `stage <N> requires implementation-planning rerun: ...`. Let a newly approved/edited decision change the planning snapshot or the Stage Map. |
+
+`ready`, `not-applicable`, and `no-design-inputs` proceed. `provisional` can proceed even without a response because there is a safe working assumption, and a non-triggering approval/edit states that assumption and override in the prompt. A `blocked` non-response makes only that stage wait, and when a blocked draft is approved/edited, it replans so that authorization is reflected into the approved plan. A markerless legacy plan proceeds with a `legacy-unassessed` warning without modifying the report.
+
+`manual-user-test` input uses the same flexible status. The planning draft is a seed for implementation to concretize the verification method against the actual diff, and the SSOT of the final execution method is the implementation report's `implementation.manualUserTest`. final-verification does not directly execute the planning sidecar.
+
+Tier 3 conformance uses the same ownership boundary during execution and
+verification.
+
+| Entry policy | PASS | FAIL / MISSING / unavailable |
+|---|---|---|
+| `requires` contains `db`, `http`, or `external` | Evidence recorded | Advisory; user rerun method recorded; run continues |
+| `requires=[]` or `requires=[io]` | Evidence recorded | Blocking |
+
+These outcomes are enforced by
+`scripts/okstra_ctl/conformance.py::decide_conformance_gate` and
+`validators/validate-run.py::_validate_conformance`.
+
+## 4. executor and verifier
+
+```mermaid
+flowchart TD
+    Lead[Okstra lead<br/>host native] --> Exec[Executor<br/>selected provider]
+    Lead --> CV[Claude verifier<br/>read-only]
+    Lead --> XV[Codex verifier<br/>read-only]
+    Lead --> GV{Antigravity in roster?}
+    GV -->|yes| Gem[Antigravity verifier<br/>read-only]
+    Exec --> Diff[Source edits + local commits]
+    CV --> QA[Independent QA rerun]
+    XV --> QA
+    Gem --> QA
+    QA --> External{External Tier 3<br/>non-PASS?}
+    External -->|yes| Advisory[ADVISORY<br/>user-owned rerun]
+    External -->|no| Verdict[PASS / CONCERNS / FAIL]
+    Advisory --> Report
+    Verdict --> Report[Final report preserves dissent]
+```
+
+Only the executor may mutate project files. The verifier independently re-runs the diff and validation command read-only in the same worktree. Even a verifier with the same provider as the executor runs again in a separate fresh CLI session. This is to prevent a structure where the same session approves a diff the same session wrote.
+
+## 5. stage and consumers
+
+```mermaid
+flowchart LR
+    Plan[approved plan<br/>Stage Map] --> Parse[parse stage map]
+    Parse --> Snapshot[Stage Lifecycle Snapshot<br/>carry + consumers + reservations]
+    Snapshot --> Resolve{stage arg}
+    Resolve -->|auto| Next[lowest ready<br/>not done/started/reserved]
+    Resolve -->|number| Forced[selected stage]
+    Next --> Prep{selected-stage<br/>design preflight}
+    Forced --> Prep
+    Prep -->|proceed| Base[resolve stage base commit]
+    Prep -->|wait / replan| Stop[stop before worktree<br/>and started consumer]
+    Base --> WT[create/reuse stage worktree]
+    WT --> Started[append consumer status=started]
+    Started --> Run[implementation executes one selected stage]
+```
+
+Stage selection is `auto` or a number. If `--stage` comes from another task-type, it is a `PrepareError`. The runtime reads `done`/`started` of `consumers.jsonl`, carry sidecar backfill, and the active stage-key of the registry together in the Stage Lifecycle Snapshot, and excludes occupied stages. The Snapshot is not a new stored file but a read-side view of `stage_targets.py`.
+
+The stage worktree base is decided by dependency shape. An independent stage uses the task-key worktree HEAD fixed at first implementation entry as its anchor, and a single-dependency stage branches from the predecessor stage's done `head_commit`. A multi-dependency stage branches from a commit holding exactly its predecessors: the predecessor commit that already contains the others, or else an integration branch merging them (`<work-category-namespace>/<task-id-segment>-g<n1>-<n2>`). okstra creates that branch itself, so a predecessor that has not been merged into the task branch no longer blocks the stage; release-handoff later reuses the same branch as that stage's PR base.
+
+## 6. Deliverables
+
+```mermaid
+flowchart TD
+    Code[Commits] --> Report[implementation final report]
+    Diff[git diff --stat base..HEAD] --> Report
+    TDD[TDD evidence] --> Report
+    Validation[Validation evidence<br/>actual output + exit code] --> Report
+    Verifiers[Verifier results<br/>command logs + verdicts] --> Report
+    Rollback[Rollback verification] --> Report
+    Report --> Next[Routing recommendation<br/>final-verification or loop back]
+```
+
+The final report requires at least the following.
+
+- approved plan path and quoted approval marker
+- selected stage, isolated stage worktree path, run artifact path (`runs/implementation/stage-<N>/`)
+- commit SHA, message, plan step mapping
+- diff summary and per-file summary
+- out-of-plan edits block
+- actual stdout/stderr and exit code of the plan validation command
+- TDD failing-then-passing evidence
+- per-verifier independent validation rerun result
+- `carry/stage-<N>.json` evidence sidecar and `consumers.jsonl` started/done row
+- rollback verification
+- `implementation.manualUserTest` finalized against the actual diff and whether it is executable
+- follow-up tasks table
+
+## 7. Forbidden actions
+
+```mermaid
+flowchart TD
+    Impl[implementation] --> Allowed[local edit/write/build/test/git add/git commit]
+    Impl -. forbidden .-> Push[git push]
+    Impl -. forbidden .-> Publish[publish/release/deploy]
+    Impl -. forbidden .-> RealDB[source migration or<br/>shared/staging/prod datastore write]
+    Impl -. forbidden .-> VerifierWrite[verifier edit/write]
+    Impl -. forbidden .-> Scope[silent scope expansion]
+    Impl -. forbidden .-> Acceptance[declaring final acceptance]
+```
+
+This phase does not declare final acceptance. It says only ready for final-verification or needs new loop.
+
+## 8. Verified code
+
+- [`scripts/okstra_ctl/phases/implementation/profile.md`](profile.md)
+- [`scripts/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md`](report_assets/implementation-input.template.md)
+- [`scripts/okstra_ctl/run.py`](../../run.py)
+- [`scripts/okstra_ctl/wizard/`](../../wizard)
+- [`validators/validate-implementation-plan-stages.py`](../../../../validators/validate-implementation-plan-stages.py)
+- [`scripts/okstra_ctl/qa_commands.py`](../../qa_commands.py)
+- [`prompts/lead/okstra-lead-contract.md`](../../../../prompts/lead/okstra-lead-contract.md)
+
+## Phase ownership
+
+`entry.py` owns stage claim preparation, design-preparation checks and execution context publication. `wizard.py` owns implementation stage selection policy. `validation.py` enforces independent rerun and discrepancy verdicts. `tests/test_implementation_stage.py` checks claims and consumer publication; `tests/test_verifier_results.py` checks verifier verdicts. Shared plan records, stage lifecycle state and worktree registry remain common contracts. Report schema definitions remain in `schemas/final-report-v2.0.schema.json` and `schemas/final-report-v3.0.schema.json` under `implementation`.
+
+## Guarantees
+
+| ID | Guarantee | Enforcement |
+|---|---|---|
+| I-1 | An empty independent rerun record fails validation. | `scripts/okstra_ctl/phases/implementation/validation.py::_validate_verifier_reran_independently` |
+| I-2 | A verifier cannot report a discrepancy with a PASS verdict. | `scripts/okstra_ctl/phases/implementation/validation.py::_validate_verifier_discrepancy_is_not_passed` |
+| I-3 | Frozen legacy instruction pointers resolve within the selected installation without rewriting the frozen profile. | `scripts/okstra_ctl/phases/implementation/tests/test_assets.py::test_frozen_sidecar_reference_reads_the_owned_installation` |

package/runtime/python/okstra_ctl/phases/implementation/validation.py

@@ -0,0 +1,205 @@
+"""구현 검증자의 독립 재현과 판정 일관성 검사."""
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+
+_PASSING_VERDICT_TOKENS = frozenset({"accepted", "conditional-accept"})
+_CHECKLIST_ID_RE = re.compile(r"\bVC-\d{3,}\b")
+_CHECKLIST_PHASE_RE = re.compile(r"\bphase\W{0,3}(pre|mid|post)\b", re.IGNORECASE)
+
+
+def _validate_verifier_reran_independently(data: dict, failures: list[str]) -> None:
+    """`independentValidationRerun` 칸이 비어 있지 않아야 한다.
+
+    스키마는 필드 존재만 강제하고 값은 보지 않는다. 빈 칸은 재현 없이
+    통과시킨 것과 구별되지 않는다.
+
+    executor 인용 표현을 잡던 정규식 갈래는 삭제했다. 표현을 세는 검사라
+    같은 재현을 어떻게 서술했느냐로 통과가 갈렸다.
+    """
+    for who, row in _verifier_rows(data):
+        rerun = row.get("independentValidationRerun")
+        if not isinstance(rerun, str) or not rerun.strip():
+            failures.append(
+                f"verifier-rerun: {who} 가 independentValidationRerun 을 비워 뒀다 — "
+                "재현 없이 통과시킨 것과 구별되지 않는다"
+            )
+
+
+def _validate_verifier_discrepancy_is_not_passed(
+    data: dict, failures: list[str]
+) -> None:
+    """재현 결과가 executor 보고와 갈렸는데 PASS 로 넘기지 못하게 한다.
+
+    규칙(§"Discrepancy rule")은 Tier 1/2 와 blocking io-only Tier 3 의 divergence 에
+    `FAIL` 을 요구하고, Tier 3 외부 자문 divergence 만 제외한다. 리포트 구조에는
+    tier 필드가 없어 그 둘을 여기서 가릴 수 없다. 그래서 `PASS` 만 막는다 —
+    자문 divergence 는 `CONCERNS` 로 기록할 자리가 이미 있고, `PASS` 는 "갈렸는데
+    아무 일도 없었다" 는 뜻이라 어느 tier 로도 정당화되지 않는다.
+    """
+    for who, row in _verifier_rows(data):
+        discrepancy = row.get("discrepancy")
+        if not isinstance(discrepancy, str) or not discrepancy.strip():
+            continue
+        if row.get("verdict") == "PASS":
+            failures.append(
+                f"verifier-discrepancy: {who} 가 divergence 를 기록하고도 PASS 를 냈다 "
+                f"— FAIL(또는 자문 divergence 면 CONCERNS)이어야 한다: "
+                f"{discrepancy.strip()[:120]}"
+            )
+
+
+def _verifier_rows(data: dict):
+    """(표시 이름, verifierResults 행) 쌍."""
+    implementation = data.get("implementation")
+    if not isinstance(implementation, dict):
+        return
+    for row in implementation.get("verifierResults") or []:
+        if not isinstance(row, dict):
+            continue
+        yield str(row.get("verifier") or row.get("role") or "verifier"), row
+
+
+def _warn_out_of_plan_edits_not_in_diff(data: dict, warnings: list[str], changed_files: list[str]) -> None:
+    """소스 차이 목록은 별도 QA 산출물의 변경 여부를 증명하지 못한다."""
+    implementation = data.get("implementation")
+    if not isinstance(implementation, dict):
+        return
+    rows = implementation.get("outOfPlanEdits")
+    if not isinstance(rows, list) or not rows:
+        return
+    changed = set(changed_files)
+    if not changed:
+        return
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        target = row.get("file")
+        if isinstance(target, str) and target and target not in changed:
+            warnings.append(
+                f"out-of-plan-edit: {row.get('id') or 'OOP-???'} 가 `{target}` 을 "
+                "계획 밖 편집으로 신고했지만 diffSummary 에 그 파일이 없다"
+            )
+
+
+def _validate_verifier_discrepancy_names_checklist_phase(
+    data: dict,
+    plan: dict | None,
+    failures: list[str],
+) -> None:
+    """계획 `validationChecklist` 행을 근거로 적은 divergence 는 그 행의 `phase` 를 인용한다.
+
+    2026-09-05 실측(fontsninja-v3-site dev-10626 stage-1): codex 검증자가 `VC-003` 의
+    `git diff --name-only` 가 커밋 뒤 빈 출력이라며 FAIL 을 냈다. 그 행은 계획 레코드에
+    `phase: mid` — 편집과 커밋 사이의 체크포인트 — 로 선언돼 있어, 커밋 뒤의 빈 출력은
+    계획의 단계 순서 그 자체였다. 수렴에서 제기자 본인이 반대 읽기에 AGREE 했지만 FAIL
+    행은 남아 stage 가 `failed` 로 갔고, 리드도 그 주장을 열어 보지 않고 라우팅에 옮겼다.
+    `pre`/`mid`/`post` 는 행이 언제 성립하는지를 정하므로, 행을 인용하는 문장이 그 값을
+    함께 적어야 한다 — 읽지 않은 행을 근거로 쓰는 문장은 그러면 쓸 수 없다.
+
+    행에 `phase` 가 없거나 계획 레코드를 못 찾으면 판정하지 않는다.
+    """
+    if plan is None:
+        return
+    planning = plan.get("implementationPlanning")
+    rows = planning.get("validationChecklist") if isinstance(planning, dict) else None
+    phases = {
+        str(row["id"]): str(row["phase"]).strip().lower()
+        for row in (rows if isinstance(rows, list) else [])
+        if isinstance(row, dict)
+        and isinstance(row.get("id"), str)
+        and isinstance(row.get("phase"), str)
+    }
+    if not phases:
+        return
+    for who, row in _verifier_rows(data):
+        discrepancy = row.get("discrepancy")
+        if not isinstance(discrepancy, str) or not discrepancy.strip():
+            continue
+        cited = sorted(set(_CHECKLIST_ID_RE.findall(discrepancy)) & set(phases))
+        if not cited:
+            continue
+        named = {
+            match.group(1).lower()
+            for match in _CHECKLIST_PHASE_RE.finditer(discrepancy)
+        }
+        missing = [
+            f"{row_id} (phase: {phases[row_id]})"
+            for row_id in cited
+            if phases[row_id] not in named
+        ]
+        if missing:
+            failures.append(
+                f"verifier-discrepancy: {who} 가 계획 체크리스트 행을 근거로 divergence 를 "
+                f"적었지만 그 행의 phase 를 인용하지 않았다 — {', '.join(missing)}. "
+                "`pre`/`mid`/`post` 는 행이 언제 성립하는지를 정하므로 인용 문장에 "
+                "`VC-NNN (phase: <값>)` 으로 적는다 (`_implementation-verifier.md` § Tier 1)."
+            )
+
+
+def _validate_verifier_command_log_is_read_only(
+    data: dict,
+    failures: list[str],
+    verifier_mutation_hits: Callable[[str], list[tuple[str, str]]],
+) -> None:
+    """검증자의 Read-only command log 에 변조 모드가 없어야 한다.
+
+    규칙은 prompts/profiles/_implementation-verifier.md 가 "런타임 AND 검증자가
+    거부해야 한다"고 BLOCKING 으로 선언해 왔지만 런타임 검사는 없었다. 스키마는
+    로그의 **존재**만 강제하고 내용은 아무도 읽지 않았다 — 검증자가
+    `eslint --fix` 로 자기가 검증할 소스를 고쳐 놓아도 통과한다.
+
+    로그는 리포트에 그대로 복사되므로 여기서 읽는 것이 정본이다.
+    """
+    implementation = data.get("implementation")
+    if not isinstance(implementation, dict):
+        return
+    rows = [r for r in (implementation.get("verifierResults") or []) if isinstance(r, dict)]
+    if not rows:
+        return
+    for row in rows:
+        log = row.get("readOnlyCommandLog")
+        if not isinstance(log, str) or not log.strip():
+            continue
+        who = str(row.get("workerId") or row.get("role") or "verifier")
+        for label, line in verifier_mutation_hits(log):
+            failures.append(
+                f"verifier-command-log: {who} 의 read-only 로그에 변조 모드 "
+                f"`{label}` 이 있다: {line[:120]}"
+            )
+
+
+def _validate_verifier_fail_blocks_verdict(data: dict, failures: list[str]) -> None:
+    """A verifier FAIL cannot be dropped during synthesis.
+
+    `implementation.verifierResults[]` was written, read by the stage-fix carry
+    helper, and by nothing else — no check compared a recorded `FAIL` against
+    the verdict the lead published. A FAIL lost in synthesis lets
+    `final-verification` reach `accepted` and `release-handoff` push work a
+    verifier rejected.
+    """
+    implementation = data.get("implementation")
+    if not isinstance(implementation, dict):
+        return
+    failed = sorted({
+        str(row.get("verifier") or "<unknown>")
+        for row in (implementation.get("verifierResults") or [])
+        if isinstance(row, dict) and str(row.get("verdict") or "").strip() == "FAIL"
+    })
+    if not failed:
+        return
+    token = str((data.get("finalVerdict") or {}).get("verdictToken") or "").strip()
+    if token in _PASSING_VERDICT_TOKENS:
+        failures.append(
+            f"final-report data.json: verifier(s) {failed} recorded "
+            f"`verdict: FAIL` but `finalVerdict.verdictToken` is `{token}`. A "
+            "verifier rejection MUST survive into the published verdict — "
+            "dropping it during synthesis is how rejected work reaches "
+            "`release-handoff`. Carry the FAIL into a blocking verdict. There "
+            "is no synthesis-time override: a verifier that produced no "
+            "verdict records `not-run` and a Tier 3 advisory divergence "
+            "records `CONCERNS`, and both are the verifier's to write, not "
+            "the lead's to substitute "
+            '(`_implementation-verifier.md` "All-verifier-failure policy").'
+        )

package/runtime/python/okstra_ctl/phases/implementation/wizard.py

@@ -0,0 +1,39 @@
+"""구현 단계 선택의 상태 표기와 선택 가능 조건."""
+from __future__ import annotations
+
+from okstra_ctl.wizard.ids import ALL_STAGES
+from okstra_ctl.wizard.state import WizardError
+
+_STAGE_MARKER_KEYS = {
+    "done": "mark_done",
+    "active": "mark_active",
+    "ready": "mark_ready",
+    "blocked": "mark_blocked",
+}
+
+
+def _impl_stage_marker(t, lifecycle) -> str:
+    return t["options"][_STAGE_MARKER_KEYS[lifecycle.status]]
+
+
+def _impl_chosen_stages(t, picks, answer, all_nums, occupied) -> set:
+    if ALL_STAGES in picks:
+        if len(picks) > 1:
+            raise WizardError(t["errors"]["all_exclusive"])
+        chosen = {n for n in all_nums if n not in occupied}
+        if not chosen:
+            raise WizardError(t["errors"]["nothing_selectable"])
+        return chosen
+    try:
+        nums = {int(p) for p in picks}
+    except ValueError:
+        raise WizardError(t["errors"]["bad_number"].format(answer=answer))
+    unknown = sorted(nums - all_nums)
+    if unknown:
+        raise WizardError(t["errors"]["unknown_stage"].format(
+            bad=", ".join(map(str, unknown))))
+    bad = sorted(nums & occupied)
+    if bad:
+        raise WizardError(t["errors"]["occupied"].format(
+            bad=", ".join(map(str, bad))))
+    return nums

package/runtime/python/okstra_ctl/phases/implementation_option_selection/__init__.py

@@ -0,0 +1 @@
+"""구현 방향 비교와 후보 검증 단계의 정본."""

package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py

@@ -0,0 +1,80 @@
+"""후보 평가 결과를 작성하는 보고서 계약."""
+from __future__ import annotations
+
+from typing import Sequence
+
+from .validation import (
+    EVALUATION_CRITERIA,
+    MAX_CRITERION_VALUE,
+    MAX_RANKED_OPTIONS,
+    MAX_RAW_CANDIDATES_PER_ANALYSER,
+    MIN_CRITERION_VALUE,
+    MIN_FEASIBLE_VOTES,
+)
+from okstra_ctl.exact_coverage import COVERAGE_VERDICT_PRECEDENCE
+
+
+def requirement_instructions(original_requirement_ids: Sequence[str], participating_analysers: Sequence[str]) -> list[str]:
+    criteria = ", ".join(f"`{item}`" for item in EVALUATION_CRITERIA)
+    requirement_ids = ", ".join(
+        f"`{item}`" for item in original_requirement_ids
+    )
+    analysers = ", ".join(
+        f"`{item}`" for item in participating_analysers
+    )
+    return [
+        f"Original requirement ids, in order: {requirement_ids}.",
+        f"Participating analysers: {analysers}.",
+        f"Evaluation criteria, in exact order: {criteria}.",
+        "Every `rankedOptions` and `candidateAudit` row must contain one "
+        "`requirementCoverage` row per original requirement id and one "
+        "`criterionScores` row per evaluation criterion. Weights and scores "
+        f"are integers from {MIN_CRITERION_VALUE} through {MAX_CRITERION_VALUE}; "
+        "`weightedScore` is the recalculated weighted mean.",
+        "`proposedBy` names exactly one participating analyser id, never a "
+        "list. Counting `rankedOptions` and `candidateAudit` together, each "
+        f"analyser may propose at most {MAX_RAW_CANDIDATES_PER_ANALYSER} raw "
+        "candidates and the run may hold at most "
+        f"{MAX_RAW_CANDIDATES_PER_ANALYSER} times the analyser count.",
+        "`coverageSummary` is recalculated from the row's `requirementCoverage` "
+        "statuses and `scopeCommitments`, and every field must equal the "
+        "recalculation: `totalCount` = number of original requirement ids; "
+        "`coveredCount` = rows with status `covered`; `coveragePercent` = "
+        "round(coveredCount / totalCount * 100, 2); `unmappedCommitments` = "
+        "commitment ids whose `requirementIds` is empty or names an id outside "
+        "the original set; `scopePrecisionPercent` = round((commitments - "
+        "unmapped) / commitments * 100, 2); `contradictedRequirements` = "
+        "original ids with status `contradicted`, in original order; "
+        "`coverageVerdict` = the first that applies of "
+        + ", ".join(f"`{verdict}`" for verdict in COVERAGE_VERDICT_PRECEDENCE)
+        + " (any contradicted; coveredCount below totalCount; any unmapped; "
+        "otherwise).",
+        "A ranked option is valid only when every participating analyser "
+        "supplied one feasibility vote, at least "
+        f"{MIN_FEASIBLE_VOTES} votes are `feasible`, and both `safetyBlockers` "
+        "and `unresolvedFeasibilityFacts` are empty.",
+        ("Classify each `unresolvedFeasibilityFacts` entry with `resolutionKind`: "
+        "`user-decision` requires nonempty `clarificationRefs` linking that fact "
+        "to actual C-NNN records, including answered records; `technical-verification` "
+        "requires no user question. Preserve the fact, whyItMatters, and evidence. "
+        "Historical unclassified facts remain readable but require classification "
+        "before blocked report reassembly. Saving does not lift blocked routing."),
+        ("After a linked decision is answered, preserve its disposition and selected "
+        "value. Update humanSummary.actions, verdictCard.nextStep, and selection "
+        "guidance to name remaining technical verification separately from unanswered "
+        "user decisions; never reopen an answered question to permit saving."),
+        "Each `feasibilityVotes` row states that analyser's own verdict, "
+        "rationale, and strongest counterevidence as its result gives them. "
+        "Two non-`uncertain` votes with identical rationale and "
+        "counterevidence are rejected as one worker's text copied under "
+        "another's name.",
+        f"Rank at most {MAX_RANKED_OPTIONS} valid options by descending "
+        "`requirement-fit`, `correctness-risk`, `architecture-fit`, "
+        "`weightedScore`, then id.",
+        "In `candidate-comparison`, keep `preselectedDirection` null. In "
+        "`preselected-validation`, emit exactly one validated option, an empty "
+        "`candidateAudit`, and a cited `preselectedDirection`.",
+        "Record candidate validity and selection mode; the lead chooses the next "
+        "phase under `## implementation-option-selection` in "
+        "`prompts/lead/phase-routing.md`.",
+    ]

package/runtime/python/okstra_ctl/phases/implementation_option_selection/boundary.json

@@ -0,0 +1,10 @@
+{
+  "allowed": "  - candidate-comparison evidence for up to three options per worker\n  - preselected-validation of exactly ONE candidate: every analyser returns its own feasibility verdict on that one direction, `candidateAudit` stays empty, and no analyser generates an alternative. It is not a re-evaluation of the merged set — `okstra_ctl.phases.implementation_option_selection.validation._validate_mode` rejects a preselected-validation report carrying more than one option or a non-empty audit\n  - a ranked display of at most three options with requirement mappings\n  - an audit record for every rejected candidate\n  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)",
+  "forbidden": [
+    "source or configuration edits, refactors, or fix attempts",
+    "tests, builds, migrations, deployments, or any state-mutating command",
+    "detailed file lists, stage maps, execution commands, or plan approval",
+    "starting `implementation-planning` or `implementation` inside this run",
+    "displaying more than three merged candidates or omitting rejected-candidate audit records"
+  ]
+}