okstra 0.205.1 → 0.206.1

package/runtime/python/okstra_ctl/option_comparison.py

@@ -1,168 +1,6 @@
-"""구현 방향 비교 자료 — 선택 리포트 기록 하나를 채팅용 사실 묶음으로 투영한다.
-
-사용자가 방향을 고르기 전에 비교 자료를 청하면 리드는 점수표·투표표·충족
-요약을 보여 준다. 그 숫자는 전부 `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
+"""기존 명령 이름을 단계의 실행 진입점으로 연결한다."""
+from okstra_ctl.phases.implementation_option_selection.comparison import main
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/option_votes.py

@@ -1,194 +1,6 @@
-"""전원 투표만 모자란 구현 후보와, 그 표를 받아야 할 분석자를 낸다.
-
-`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.implementation_options 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
+"""기존 명령 이름을 단계의 실행 진입점으로 연결한다."""
+from okstra_ctl.phases.implementation_option_selection.votes import main
 
 
 if __name__ == "__main__":
-    raise SystemExit(main(sys.argv[1:]))
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/paths.py

@@ -29,6 +29,8 @@ from okstra_project.dirs import (
 )
 from okstra_project.slug import slugify
 
+from .asset_roots import walk_to_asset_root as _walk_to_asset_root
+
 __all__ = [
     "OKSTRA_RELATIVE",
     "TASKS_RELATIVE",
@@ -88,12 +90,24 @@ def find_asset_root(
         root = Path(override)
         if is_present(root.joinpath(*relative)):
             return root
+    return walk_to_asset_root(relative, start=start, is_present=is_present)
 
-    here = Path(start or __file__).resolve()
-    for parent in [here, *here.parents]:
-        if is_present(parent.joinpath(*relative)):
-            return parent
-    return None
+
+def walk_to_asset_root(
+    relative: Sequence[str],
+    *,
+    start: Optional[Path] = None,
+    is_present: Callable[[Path], bool] = Path.is_file,
+) -> Optional[Path]:
+    """The nearest ancestor of ``start`` that carries ``relative``, or None.
+
+    This is the layout walk of `find_asset_root` without the `OKSTRA_HOME`
+    override. A caller that must stay inside the tree it started from (a phase
+    profile resolving its includes) calls this directly.
+    """
+    return _walk_to_asset_root(
+        relative, start=Path(start or __file__), is_present=is_present,
+    )
 
 
 _STAGED_TASK_TYPES = ("implementation", "final-verification")
@@ -609,6 +623,8 @@ def compute_run_paths(
     incremental_decision = run_state / f"incremental-decision-{task_type_segment}-{seqs['state']}.json"
 
     run_errors_log = run_logs / f"errors-{task_type_segment}-{seqs['state']}.jsonl"
+    from .phases.catalog import profile_sidecar
+
     runtime_home = okstra_home()
 
     claude_worker_errors_sidecar = worker_results / f"claude-worker-errors{suffixes['worker_results']}.json"
@@ -666,7 +682,7 @@ def compute_run_paths(
             runtime_home / "prompts" / "lead" / "convergence.md"
         ),
         "OKSTRA_PLAN_BODY_VERIFICATION_PATH": str(
-            runtime_home / "prompts" / "lead" / "plan-body-verification.md"
+            profile_sidecar(runtime_home, "prompts/lead/plan-body-verification.md")
         ),
         "OKSTRA_REPORT_WRITER_PATH": str(
             runtime_home / "prompts" / "lead" / "report-writer.md"

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

@@ -0,0 +1,4 @@
+"""단계 패키지.
+
+등록표는 ``catalog`` 다. 이 패키지를 import 해도 단계 실행 모듈은 적재되지 않는다.
+"""