okstra 0.205.1 → 0.206.1

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}

@@ -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/{docs/task-process/implementation-option-selection.md → runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md}

@@ -1,5 +1,18 @@
 # 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)
@@ -50,7 +63,7 @@ Ranking uses eight fixed criteria with per-run weights: requirement fit, archite
 
 ## 5. Direction confirmation and planning handoff
 
-Comparison mode exports a `DIRECTION SELECTION` block in the user-response sidecar. 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.
+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.
 
@@ -62,9 +75,9 @@ This phase does not edit source code, run builds or tests, execute migrations, d
 
 ## 7. Verified code
 
-- [`prompts/profiles/implementation-option-selection.md`](../../prompts/profiles/implementation-option-selection.md)
-- [`prompts/duties/direction-selection-worker.json`](../../prompts/duties/direction-selection-worker.json)
-- [`scripts/okstra_ctl/implementation_options.py`](../../scripts/okstra_ctl/implementation_options.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)
+- [`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 @@
+"""구현 계획 단계의 전용 정책과 자원."""