okstra 0.206.0 → 0.207.0

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

@@ -0,0 +1,168 @@
+"""구현 방향 비교 자료 — 선택 리포트 기록 하나를 채팅용 사실 묶음으로 투영한다.
+
+사용자가 방향을 고르기 전에 비교 자료를 청하면 리드는 점수표·투표표·충족
+요약을 보여 준다. 그 숫자는 전부 `implementationOptionSelection` 기록에 있고
+`weightedScore` 는 발행 시점에 재계산 값과 대조된다
+(`implementation_options.py` `_validate_option_scores`). 리드가 JSON 을 손으로
+읽고 가중 점수를 다시 계산하던 자리를 이 명령이 대신한다. 서술(도입 문장,
+방향별 요지)은 리드가 `narrative` 와 각 방향의 근거 필드로 쓴다.
+
+읽기 전용이다. 어떤 파일도 쓰지 않는다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from okstra_ctl import next_phase
+from okstra_ctl.final_report_paths import final_report_data_path
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
+
+
+class OptionComparisonError(ValueError):
+    """비교 자료를 만들 수 없는 기록."""
+
+
+def _rows(value: object) -> list[Mapping[str, Any]]:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes)):
+        return []
+    return [row for row in value if isinstance(row, Mapping)]
+
+
+def _text(value: object) -> str:
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _count(value: object) -> int:
+    return len(value) if isinstance(value, Sequence) and not isinstance(value, str) else 0
+
+
+def _option(
+    option: Mapping[str, Any], recommended_id: str
+) -> dict[str, Any]:
+    coverage = option.get("coverageSummary")
+    coverage = coverage if isinstance(coverage, Mapping) else {}
+    scores = _rows(option.get("criterionScores"))
+    return {
+        "id": _text(option.get("id")),
+        "name": _text(option.get("name")),
+        "recommended": _text(option.get("id")) == recommended_id,
+        "goal": _text(option.get("goal")),
+        "coreMechanism": _text(option.get("coreMechanism")),
+        # 발행 검증이 재계산 값과 같음을 보장한 기록값이다. 다시 계산하지 않는다.
+        "weightedScore": option.get("weightedScore"),
+        "scores": {_text(row.get("criterion")): row.get("score") for row in scores},
+        "scoreRationales": {
+            _text(row.get("criterion")): _text(row.get("rationale")) for row in scores
+        },
+        "coverage": {
+            "verdict": _text(coverage.get("coverageVerdict")),
+            "coveredCount": coverage.get("coveredCount"),
+            "totalCount": coverage.get("totalCount"),
+            "requirementIds": [
+                _text(row.get("requirementId"))
+                for row in _rows(option.get("requirementCoverage"))
+                if _text(row.get("requirementId"))
+            ],
+        },
+        "safetyBlockers": _count(option.get("safetyBlockers")),
+        "unresolvedFeasibilityFacts": _count(option.get("unresolvedFeasibilityFacts")),
+        "votes": {
+            _text(vote.get("worker")): {
+                "verdict": _text(vote.get("verdict")),
+                "rationale": _text(vote.get("rationale")),
+                "counterevidence": _text(vote.get("counterevidence")),
+            }
+            for vote in _rows(option.get("feasibilityVotes"))
+            if _text(vote.get("worker"))
+        },
+    }
+
+
+def build_comparison(report_data: Mapping[str, Any]) -> dict[str, Any]:
+    """선택 리포트 기록 → 비교 자료 사실 묶음."""
+    selection = report_data.get("implementationOptionSelection")
+    if not isinstance(selection, Mapping):
+        raise OptionComparisonError(
+            "report has no implementationOptionSelection block; "
+            "pass an implementation-option-selection report record"
+        )
+    recommended_id = _text(selection.get("recommendedOptionId"))
+    options = [
+        _option(row, recommended_id) for row in _rows(selection.get("rankedOptions"))
+    ]
+    if not options:
+        raise OptionComparisonError("report ranks no direction; there is nothing to compare")
+    # 투표 열 순서는 처음 등장한 순서다 — 방향마다 같은 분석자 집합이 투표한다.
+    workers: list[str] = []
+    for option in options:
+        for worker in option["votes"]:
+            if worker not in workers:
+                workers.append(worker)
+    narrative = selection.get("userNarrative")
+    narrative = narrative if isinstance(narrative, Mapping) else {}
+    return {
+        "mode": _text(selection.get("mode")),
+        "routing": _text(selection.get("routing")),
+        "recommendedOptionId": recommended_id,
+        "criteria": [
+            {"criterion": _text(row.get("criterion")), "weight": row.get("weight")}
+            for row in _rows(selection.get("evaluationCriteria"))
+        ],
+        "workers": workers,
+        "options": options,
+        "narrative": {
+            key: _text(block.get("text"))
+            for key, block in narrative.items()
+            if isinstance(block, Mapping) and _text(block.get("text"))
+        },
+        # "남은 절차" 문단의 근거. 다음 phase 포인터와 같은 문장이다.
+        "nextStep": next_phase.project(report_data)["rationale"],
+    }
+
+
+def _load(report: Path) -> Mapping[str, Any]:
+    data_path = final_report_data_path(report)
+    try:
+        data = load_owned_object(data_path, artifact="implementation option data")
+    except (OSError, JsonBoundaryError) as exc:
+        raise OptionComparisonError(f"cannot read report record {data_path}: {exc}") from exc
+    return data
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="okstra option-comparison",
+        description=(
+            "Print the comparison facts of an implementation-option-selection "
+            "report as JSON: criteria and weights, per-direction scores and "
+            "recorded weighted score, requirement coverage, blocker counts, "
+            "per-worker feasibility votes, the report narrative, and the next step."
+        ),
+    )
+    parser.add_argument(
+        "--report",
+        required=True,
+        help="final-report-implementation-option-selection-<seq>.data.json (a .md sibling is accepted)",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        payload = build_comparison(_load(Path(args.report)))
+    except OptionComparisonError as exc:
+        print(f"option-comparison: {exc}", file=sys.stderr)
+        return 2
+    json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,27 @@
+"""방향 비교가 필요한 요구사항과 독립 분석자 수를 확인한다."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Sequence
+
+from okstra_ctl.prepare_error import PrepareError
+from okstra_ctl.scope_provenance import brief_end_state_id_sequence
+
+
+def validate_brief_requirements(brief_path: Path) -> None:
+    if not brief_end_state_id_sequence(brief_path):
+        raise PrepareError(
+            "regenerate the brief with stable end-state IDs before starting "
+            "implementation-option-selection"
+        )
+
+
+def validate_analyser_roster(
+    workers: Sequence[str]
+) -> None:
+    """Require independent analysis from three workers before option selection."""
+    analyser_count = sum(worker != "report-writer" for worker in workers)
+    if analyser_count < 3:
+        raise PrepareError(
+            "implementation-option-selection requires at least 3 analyser workers"
+        )

package/runtime/{prompts/profiles/implementation-option-selection.md → python/okstra_ctl/phases/implementation_option_selection/profile.md}

@@ -14,7 +14,7 @@
   - Apply the shared reporter-confirmation precondition exactly as written. Unresolved `intent-check:` and `conversion-block:` rows use `Blocks=next-phase`.
   - Treat each stable brief end-state ID as a required evaluation target. A missing ID is a preparation failure; do not invent a replacement requirement.
 - Worker direction-selection procedure:
-  - In `candidate-comparison` mode, produce candidate, supporting and contradicting evidence, criterion scores, and requirement mappings. For every candidate, state one feasibility verdict — `feasible`, `not-feasible`, or `uncertain` — with a one-sentence rationale and the strongest counterevidence, each citing inspected evidence. The report's `feasibilityVotes` row for this worker is built from that statement, so a candidate without one leaves the writer nothing but another worker's words.
+  - In `candidate-comparison` mode, produce candidate, supporting and contradicting evidence, criterion scores, and requirement mappings. For every candidate, state one feasibility verdict — `feasible`, `not-feasible`, or `uncertain` — with a rationale and the strongest counterevidence, each citing inspected evidence. Write the rationale as long as the argument needs: say why each cited finding supports the verdict, not only which findings do. The report's `feasibilityVotes` row for this worker is built from that statement, so a candidate without one leaves the writer nothing but another worker's words.
   - In `candidate-comparison` mode only, submit at most three candidates. A candidate must be feasible from inspected evidence, not from an assumed future change.
   - In `preselected-validation` mode, receive one preselected direction from the lead and validate its evidence, counterevidence, criterion scores, and requirement mappings, and state the same feasibility verdict with its rationale and counterevidence. The worker must not generate new candidates.
   - Do not produce detailed file lists, stage maps, execution commands, or a plan approval request.
@@ -29,7 +29,7 @@
   - Map every displayed candidate or preselected direction to the stable brief end-state IDs it satisfies, preserves, or leaves unresolved.
   - **Close the vote gaps before you conclude `blocked`.** Round 1 runs the designers in parallel, so each one votes only on the candidates it proposed and the merged set ends up with a different hole per analyser. A candidate that is otherwise sound then fails the every-analyser clause and drops out of the ranking — three such candidates blocked a run whose comparison had in fact converged (2026-09-10, dev-10629-4: IO-001, IO-002 and IO-003 each held two `feasible` votes and each was missing a different designer). Run `okstra option-votes gaps --task-manifest <taskManifestPath> --narrative <report writer narrative>` before assembly. For each analyser it names, dispatch one vote-completion assignment asking for that analyser's own feasibility verdict, rationale, and counterevidence on the named candidate — no new candidate, so the run stays in `candidate-comparison` mode. The command reports no gap when a vote cannot settle the block (safety blockers, unresolved feasibility facts, too few feasible verdicts); that is the honest `blocked`.
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
-  - Classify every `unresolvedFeasibilityFacts` entry with `resolutionKind`: `user-decision` requires nonempty `clarificationRefs` naming the actual C-NNN records for that fact; `technical-verification` requires source review, design evidence, or experiments and does not require a user question. Preserve `fact`, `whyItMatters`, and `evidence`. Reuse answered questions and their recorded dispositions; never reopen one merely to save the report. An unrelated open question does not satisfy a missing reference. Historical unclassified entries remain readable, but blocked report reassembly requires the writer to classify them explicitly. Enforced by `validate_blocked_answer_channel` in `scripts/okstra_ctl/implementation_options.py`, called by report assembly and `validate-run.py`. Saving preserves `routing: blocked` and does not make a candidate valid. In `humanSummary.actions`, `verdictCard.nextStep`, and selection guidance, distinguish pending user decisions from remaining technical verification; after the pilot route is answered, carry the selected route and remove the old answer-waiting instruction.
+  - Classify every `unresolvedFeasibilityFacts` entry with `resolutionKind`: `user-decision` requires nonempty `clarificationRefs` naming the actual C-NNN records for that fact; `technical-verification` requires source review, design evidence, or experiments and does not require a user question. Preserve `fact`, `whyItMatters`, and `evidence`. Reuse answered questions and their recorded dispositions; never reopen one merely to save the report. An unrelated open question does not satisfy a missing reference. Historical unclassified entries remain readable, but blocked report reassembly requires the writer to classify them explicitly. Enforced by `validate_blocked_answer_channel` in `scripts/okstra_ctl/phases/implementation_option_selection/validation.py`, called by report assembly and `validate-run.py`. Saving preserves `routing: blocked` and does not make a candidate valid. In `humanSummary.actions`, `verdictCard.nextStep`, and selection guidance, distinguish pending user decisions from remaining technical verification; after the pilot route is answered, carry the selected route and remove the old answer-waiting instruction.
 {{INCLUDE:_clarification-recommendation.md}}
 - Cross-verification mode:
   - Phase 5.5 convergence runs in adversarial mode (`convergence.adversarial=true`).
@@ -40,6 +40,6 @@
 
 ## Technical evidence loop
 
-When no candidate is valid and explicit eligible technical facts remain, route to `technical-verification` to collect experimental evidence. Keep `rankedOptions` empty and `recommendedOptionId` null. `validate_blocked_answer_channel` rejects this route while user decisions remain unresolved or no safe, explicitly classified technical fact is available. Historical blocked reports can be supplied explicitly without rewriting their verdict.
+Record candidate validity, unresolved user decisions, and explicitly classified technical facts. The lead chooses the next phase under `## implementation-option-selection` in `prompts/lead/phase-routing.md`.
 
 When `--clarification-response` carries a technical-verification report, read its source comparison, experiment plans, results and logs. Check that the tested environment matches current code, then author fresh feasibility votes. Do not directly convert a supported result into a feasible candidate, remove unrelated uncertainties or treat a failed or unrun probe as compatibility proof. Preserve the user's pilot scope and any deferred production rollout.

package/runtime/python/okstra_ctl/{report_html/view_models/implementation_option_selection.py → phases/implementation_option_selection/report.py}

@@ -1,8 +1,8 @@
 """Human-first implementation-direction comparison view."""
 from __future__ import annotations
 
-from ..common import evidence_index, scoped_anchor_map
-from ..models import HumanReportView
+from okstra_ctl.report_html.common import evidence_index, scoped_anchor_map
+from okstra_ctl.report_html.models import HumanReportView
 
 # Record fields this template anchors as `id-<row id>` (see
 # `HumanReportView.anchored_fields`); ids elsewhere land in the ledger.

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

@@ -0,0 +1,83 @@
+# implementation-option-selection process
+
+This directory owns candidate evaluation, vote completion, comparison projection, preparation rules, and report presentation. Selected-direction snapshots, user answers, exact coverage, and technical verification facts remain shared contracts.
+
+## Guarantees
+
+| ID | Guarantee | Enforcement |
+|---|---|---|
+| IOS-1 | Candidate scores, coverage, votes and ranking are recomputed | `scripts/okstra_ctl/phases/implementation_option_selection/validation.py::validate_implementation_option_selection` |
+| IOS-2 | Blocked facts retain their user decision or technical evidence channel | `scripts/okstra_ctl/phases/implementation_option_selection/validation.py::validate_blocked_answer_channel` |
+| IOS-3 | Comparison requires at least three independent analysers | `scripts/okstra_ctl/phases/implementation_option_selection/entry.py::validate_analyser_roster` |
+| IOS-4 | Candidate fingerprints deduplicate equivalent mechanisms | `scripts/okstra_ctl/phases/implementation_option_selection/tests/test_implementation_options.py::test_duplicate_candidates_share_a_fingerprint` |
+
+Report schemas remain in `schemas/final-report-v2.0.schema.json` and `schemas/final-report-v3.0.schema.json`, under `implementationOptionSelection`. Next-phase decisions belong to `prompts/lead/phase-routing.md`.
+
+## Index
+
+- [1. Purpose](#1-purpose)
+- [2. Execution modes](#2-execution-modes)
+- [3. Prepare gates](#3-prepare-gates)
+- [4. Candidate validation and ranking](#4-candidate-validation-and-ranking)
+- [5. Direction confirmation and planning handoff](#5-direction-confirmation-and-planning-handoff)
+- [6. Forbidden actions](#6-forbidden-actions)
+- [7. Verified code](#7-verified-code)
+
+## 1. Purpose
+
+`implementation-option-selection` is the read-only lifecycle phase between cause analysis and detailed planning. It decides which implementation mechanism and architecture boundary planning may realize. It does not name the exact file list, split stages, or prescribe test commands.
+
+Direction confirmation and detailed plan approval are independent user decisions. Confirming a direction permits planning to begin. It does not approve the plan or permit implementation.
+
+## 2. Execution modes
+
+| Mode | Input | Output |
+|---|---|---|
+| `candidate-comparison` | Requirement ledger, cause evidence, code evidence, independently proposed raw candidates | At most three ranked valid directions and a separate user selection |
+| `preselected-validation` | A direction already fixed by upstream evidence or an explicit user instruction | One normalized and validated direction, or `blocked`; no alternative is generated |
+
+The normal analyser roster contains at least three analyser workers plus the report writer. Each analyser may propose at most three raw candidates. All analysers reassess the merged candidate set before ranking.
+
+## 3. Prepare gates
+
+Prepare rejects the phase when the brief has no stable `EB-NNN`, `PB-NNN`, or `EO-NNN` requirement IDs. External Gates are not part of that denominator. Prepare also rejects a roster with fewer than three analysers.
+
+The phase reuses the task-key worktree and may inspect the code and prior task artifacts. It does not obtain a writable implementation-stage worktree.
+
+## 4. Candidate validation and ranking
+
+Every displayed candidate has all of the following properties:
+
+- `coveragePercent == 100`
+- `scopePrecisionPercent == 100`
+- `coverageVerdict == exact`
+- no `unmappedCommitments`
+- no `contradictedRequirements`
+- supporting code or upstream evidence
+- at least two feasibility votes
+- no safety blocker or unresolved implementation-critical external fact
+
+The final report can display one, two, or three valid candidates. Rejected candidates remain in `candidateAudit` with their rejection reasons and cannot be selected. If no candidate is valid, the report uses `blocked` and planning cannot start.
+
+Ranking uses eight fixed criteria with per-run weights: requirement fit, architecture fit, change locality, implementation complexity, correctness risk, reversibility, verification cost, and rollout cost. Safety and exact-coverage failures override the weighted score.
+
+## 5. Direction confirmation and planning handoff
+
+Comparison mode records a `DIRECTION SELECTION` block in the user-response sidecar, either through the HTML report's Export or in-session through `/okstra-user-response` (`okstra user-response direction`). Prepare validates the selected ID against the displayed candidates and binds the response to the report's sibling data JSON through its SHA-256 digest.
+
+A new planning run receives the selection report through `--selected-direction`. Prepare normalizes the validated choice into `instruction-set/selected-direction.json`. Planning cites that snapshot through `selectedDirectionRef` and writes `approved: false` until the user separately approves the detailed plan.
+
+If planning proves that the mechanism or architecture boundary cannot satisfy exact coverage, it emits `direction-invalidated` and routes back to `implementation-option-selection`. It never picks the next ranked direction automatically.
+
+## 6. Forbidden actions
+
+This phase does not edit source code, run builds or tests, execute migrations, deploy, or call a write API. Candidate details do not contain exact file lists, stage maps, or test commands. Those details belong to `implementation-planning` after direction confirmation.
+
+## 7. Verified code
+
+- [`prompts/profiles/implementation-option-selection.md`](profile.md)
+- [`prompts/duties/direction-selection-worker.json`](../../../../prompts/duties/direction-selection-worker.json)
+- [`scripts/okstra_ctl/phases/implementation_option_selection/validation.py`](validation.py)
+- [`scripts/okstra_ctl/implementation_direction.py`](../../../../scripts/okstra_ctl/implementation_direction.py)
+- [`scripts/okstra_ctl/exact_coverage.py`](../../../../scripts/okstra_ctl/exact_coverage.py)
+- [`validators/validate-run.py`](../../../../validators/validate-run.py)

package/runtime/python/okstra_ctl/{implementation_options.py → phases/implementation_option_selection/validation.py}

@@ -10,14 +10,14 @@ from dataclasses import dataclass
 from collections.abc import Mapping, Sequence
 from typing import Any
 
-from .clarification_items.dispositions import (
+from okstra_ctl.clarification_items.dispositions import (
     USER_INPUT_BLOCKS,
     clarification_disposition,
     incorporated_clarification_ids,
     row_blocks_progress,
 )
-from .exact_coverage import ExactCoverageError, calculate_exact_coverage
-from .technical_verification import TechnicalVerificationError, technical_verification_facts
+from okstra_ctl.exact_coverage import ExactCoverageError, calculate_exact_coverage
+from okstra_ctl.technical_verification_facts import TechnicalVerificationError, technical_verification_facts
 
 
 EVALUATION_CRITERIA = (

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

@@ -0,0 +1,194 @@
+"""전원 투표만 모자란 구현 후보와, 그 표를 받아야 할 분석자를 낸다.
+
+`implementation-option-selection` 의 1라운드는 설계자들이 병렬로 돌아 서로의
+후보를 보지 못한다. 그래서 자기가 낸 후보에만 실현 가능성 표를 남기고, 병합된
+집합에는 분석자마다 다른 구멍이 생긴다. 유효성 규칙은 전원 투표를 요구하므로
+(`implementation_options._validate_option_feasibility`) 그런 후보는 순위표에
+오르지 못하고, 남는 후보가 하나도 없으면 run 이 `routing: blocked` 로 끝난다 —
+실측(2026-09-10, dev-10629-4): 설계자 3명 로스터에서 IO-001·IO-002·IO-003 이
+각각 `feasible` 2표를 받고도 빠진 분석자가 하나씩 달라 전부 탈락했다.
+
+거절은 그 상태를 알려 줄 뿐 메우지 못한다. 이 명령이 앞으로 가는 길이다:
+표만 모자란 후보를 세고, 어느 분석자에게 어떤 후보를 부쳐야 하는지 말한다.
+재검증(reverify) 라운드는 주장을 반박하는 라운드이지 후보에 표를 남기는
+라운드가 아니므로, 그 구멍을 메우는 디스패치는 리드가 이 목록을 보고 연다.
+
+읽는 자리는 두 가지다. 조립 전이면 작성자 서사(`--narrative`), 이미 발행된
+run 이면 리포트 레코드(`--report`). 로스터는 task-manifest 의
+`recommendedWorkers` 에서 `report-writer` 를 뺀 것이고, 그것이 검증기가
+`participating analysers` 로 쓰는 값과 같은 정의다(`validators/validate-run.py`).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from okstra_ctl.final_report_schema import load_schema_version
+from okstra_ctl.phases.implementation_option_selection.validation import VoteGap, vote_gaps
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
+from okstra_ctl.report_contract import CURRENT_REPORT_SCHEMA_VERSION
+from okstra_ctl.report_narrative import parse_narrative_structure
+
+
+class OptionVotesError(ValueError):
+    """투표 구멍을 셀 입력이 없거나 읽히지 않는다."""
+
+
+def _record_from_report(path: Path) -> dict[str, Any]:
+    try:
+        return load_owned_object(path, artifact="final-report data.json")
+    except (JsonBoundaryError, OSError) as exc:
+        raise OptionVotesError(f"report record is unreadable: {exc}") from exc
+
+
+def _record_from_narrative(path: Path) -> dict[str, Any]:
+    """작성자 서사를 레코드 모양으로 읽는다.
+
+    값 결함은 무시한다 — 교정 원장이 고칠 자리이고, 표 구멍을 세는 데에는
+    후보 id 와 `feasibilityVotes` 만 있으면 된다. 여기서 서사 전체를 거절하면
+    아직 교정 중인 run 은 이 명령을 쓸 수 없다.
+    """
+    try:
+        markdown = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise OptionVotesError(f"narrative is unreadable: {exc}") from exc
+    schema = load_schema_version(CURRENT_REPORT_SCHEMA_VERSION)
+    record, _defects = parse_narrative_structure(markdown, schema)
+    return record
+
+
+def participating_analysers(manifest_path: Path) -> tuple[str, ...]:
+    try:
+        manifest = load_owned_object(manifest_path, artifact="task-manifest")
+    except (JsonBoundaryError, OSError) as exc:
+        raise OptionVotesError(f"task manifest is unreadable: {exc}") from exc
+    roster = manifest.get("recommendedWorkers")
+    if not isinstance(roster, list):
+        raise OptionVotesError("task manifest has no recommendedWorkers roster")
+    return tuple(
+        str(worker) for worker in roster if str(worker) != "report-writer"
+    )
+
+
+def _selection(record: Mapping[str, Any]) -> Mapping[str, Any]:
+    selection = record.get("implementationOptionSelection")
+    if not isinstance(selection, Mapping):
+        raise OptionVotesError(
+            "the source has no implementationOptionSelection block — "
+            "this command reads an implementation-option-selection run"
+        )
+    return selection
+
+
+def _dispatch_lines(gaps: list[VoteGap]) -> list[str]:
+    """분석자별로 부칠 후보 목록. 디스패치 단위가 분석자이기 때문이다."""
+    by_analyser: dict[str, list[str]] = {}
+    for gap in gaps:
+        for analyser in gap.missing:
+            by_analyser.setdefault(analyser, []).append(gap.option_id)
+    return [
+        f"  {analyser}: {', '.join(options)}"
+        for analyser, options in sorted(by_analyser.items())
+    ]
+
+
+def _render(gaps: list[VoteGap]) -> str:
+    if not gaps:
+        return (
+            "No candidate is short of votes alone. A blocked run here is "
+            "blocked by something a vote cannot settle — safety blockers, "
+            "unresolved feasibility facts, or too few feasible verdicts."
+        )
+    lines = [
+        f"{len(gaps)} candidate(s) need only the missing feasibility votes:",
+        "",
+    ]
+    lines += [
+        f"  {gap.option_id}: {gap.feasible_votes} feasible so far, "
+        f"missing {', '.join(gap.missing)}"
+        for gap in gaps
+    ]
+    lines += ["", "Dispatch one vote-completion assignment per analyser:"]
+    lines += _dispatch_lines(gaps)
+    lines += [
+        "",
+        "Each assignment asks that analyser for its own feasibility verdict, "
+        "rationale, and counterevidence on the named candidate — nothing else. "
+        "It generates no candidate, so the run stays in `candidate-comparison` "
+        "mode; `preselected-validation` is a whole-run mode that would collapse "
+        "the comparison to one direction.",
+    ]
+    return "\n".join(lines)
+
+
+def _gaps(args: argparse.Namespace) -> int:
+    if bool(args.report) == bool(args.narrative):
+        raise OptionVotesError("pass exactly one of --report or --narrative")
+    record = (
+        _record_from_report(args.report)
+        if args.report
+        else _record_from_narrative(args.narrative)
+    )
+    gaps = vote_gaps(
+        _selection(record), participating_analysers(args.task_manifest)
+    )
+    if args.json:
+        print(json.dumps(
+            {
+                "gaps": [
+                    {
+                        "optionId": gap.option_id,
+                        "missing": list(gap.missing),
+                        "feasibleVotes": gap.feasible_votes,
+                    }
+                    for gap in gaps
+                ]
+            },
+            ensure_ascii=False,
+            indent=2,
+        ))
+    else:
+        print(_render(gaps))
+    return 0
+
+
+_CLI_DESCRIPTION = (
+    "Report the implementation candidates that only lack feasibility votes, "
+    "and which analyser owes each one."
+)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION, prog="okstra option-votes"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    gaps_parser = subparsers.add_parser("gaps")
+    gaps_parser.add_argument(
+        "--task-manifest", type=Path, required=True,
+        help="the task's task-manifest.json — its roster names the analysers")
+    gaps_parser.add_argument(
+        "--report", type=Path,
+        help="a published final-report `.data.json`")
+    gaps_parser.add_argument(
+        "--narrative", type=Path,
+        help="the report writer's narrative markdown, before assembly")
+    gaps_parser.add_argument("--json", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        return _gaps(args)
+    except OptionVotesError as exc:
+        print(f"okstra option-votes: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

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

@@ -0,0 +1 @@
+"""구현 계획 단계의 전용 정책과 자원."""