okstra 0.196.0 → 0.197.1

package/runtime/python/okstra_ctl/stage_close.py

@@ -0,0 +1,244 @@
+"""`okstra stage-close` — 이미 랜딩한 stage 를 기록만 남겨 done 으로 닫는다.
+
+stage 완료의 정본은 `runs/implementation-planning/consumers.jsonl` 의 `done`
+행이고, 그 행은 두 경로로만 생겼다: implementation run 이 정상 종료하거나,
+`backfill_done_from_carry` 가 carry 사이드카에서 복원하거나. 두 경로 모두
+없는 상태가 실재한다 — 제품 변경은 커밋되고 conformance 결과도 PASS 인데
+run 이 carry 를 쓰기 전에 끝난 경우다. 그러면 `stage-map` 은 `doneStages: []`
+을 보고하고, 다음 계획은 아무 일도 없었던 것처럼 그 stage 를 다시 쓰며, 거기서
+나오는 RED 기대는 전부 도달 불가다(실측 2026-09-10, fontsninja-v3-site
+dev-10628-3: 마지막 행이 `started`, carry 디렉터리는 빈 폴더, stage 결과는
+`overall: PASS`).
+
+이 명령은 그 복구 경로다. 커밋과 conformance 결과라는 두 증거를 확인한 뒤
+done 행을 append 한다 — 증거 없이 닫는 수단은 아니다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+from pathlib import Path
+
+from okstra_project import (
+    ResolverError,
+    StateError,
+    resolve_project_root,
+    resolve_task_identity,
+)
+
+from .conformance import (
+    conformance_result_file,
+    decide_conformance_gate,
+    qa_result_from_dict,
+)
+from .consumers import append_consumer, last_lifecycle_status_by_stage, read_consumers
+from .json_boundary import JsonBoundaryError, load_owned_object
+from .paths import RunRef, task_conformance_manifest_file, task_qa_dir
+from .stage_map import StageMapError, load_latest_plan_stage_map
+
+# 이 status 를 이미 가진 stage 는 리드가 판정을 내린 것이다. 되쓰기는 그 판정을
+# 덮는 일이므로 여기서 하지 않는다.
+_SETTLED = ("done", "failed")
+
+
+def _git_commit_exists(repo_root: Path, commit: str) -> bool:
+    probe = subprocess.run(
+        ["git", "-C", str(repo_root), "cat-file", "-e", f"{commit}^{{commit}}"],
+        capture_output=True,
+    )
+    return probe.returncode == 0
+
+
+def _manifest_entry(task_root: Path, stage: int) -> dict | None:
+    """이 stage 의 conformance entry, 선언이 없으면 None.
+
+    stageKey 의 `<task-id>` 는 planning 이 쓴 원문이라 디렉터리 segment 와 표기가
+    다를 수 있으므로 `-stage-<N>` 접미사로 맞춘다 — `_clear_stale_stage_waiver`
+    와 같은 규칙이다.
+    """
+    path = task_conformance_manifest_file(task_root)
+    if not path.is_file():
+        return None
+    try:
+        manifest = load_owned_object(path, artifact="conformance manifest")
+    except JsonBoundaryError as exc:
+        raise StateError(str(exc), stage="conformance") from exc
+    entries = manifest.get("entries")
+    if not isinstance(entries, list):
+        return None
+    suffix = f"-stage-{stage}"
+    return next(
+        (
+            entry for entry in entries
+            if isinstance(entry, dict)
+            and isinstance(entry.get("stageKey"), str)
+            and entry["stageKey"].endswith(suffix)
+        ),
+        None,
+    )
+
+
+def _conformance_state(task_root: Path, stage: int) -> tuple[bool, str]:
+    """(닫아도 되는가, 사람이 읽는 근거).
+
+    선언 자체가 없으면 게이트할 것이 없다. 있으면 그 stage 의 결과 사이드카로
+    `decide_conformance_gate` 를 그대로 돌린다 — 검증기가 쓰는 것과 같은 판정
+    함수라, 여기서 통과한 stage 는 검증기에서도 통과한다.
+    """
+    entry = _manifest_entry(task_root, stage)
+    if entry is None:
+        return True, "no conformance entry declared for this stage"
+    key = str(entry.get("stageKey"))
+    sidecar = conformance_result_file(task_qa_dir(task_root), key)
+    result = None
+    if sidecar.is_file():
+        try:
+            result = qa_result_from_dict(
+                load_owned_object(sidecar, artifact="conformance result")
+            )
+        except JsonBoundaryError:
+            # 읽을 수 없는 결과는 결과가 아니다 — MISSING 으로 게이트에 넘겨
+            # 판정을 `decide_conformance_gate` 가 내리게 한다. 검증기도 같다.
+            result = qa_result_from_dict(None)
+    verdict = decide_conformance_gate(entry, result)
+    return verdict.ok, f"{verdict.status}: {verdict.message}"
+
+
+def close_stage(
+    project_root: Path, task_key: str, stage: int, head_commit: str,
+) -> dict:
+    """stage 를 done 으로 닫고 그 근거를 함께 돌려준다."""
+    identity = resolve_task_identity(project_root, task_key)
+    task_root = Path(identity["taskRoot"])
+    plan_run_root = RunRef.from_task_root(task_root, "implementation-planning").run_dir
+    if not plan_run_root.is_dir():
+        raise StateError(
+            f"this task has no implementation-planning run at {plan_run_root} — "
+            "there is no Stage Map to close a stage of",
+            stage="plan-run",
+        )
+
+    try:
+        stage_map = load_latest_plan_stage_map(task_root)
+    except StageMapError as exc:
+        raise StateError(str(exc), stage=exc.code) from exc
+    known = sorted(
+        row["stage_number"] for row in stage_map.stages
+        if isinstance(row, dict) and isinstance(row.get("stage_number"), int)
+    )
+    if stage not in known:
+        raise StateError(
+            f"stage {stage} is not in this task's Stage Map (has {known or 'none'})",
+            stage="stage-map",
+        )
+
+    recorded = last_lifecycle_status_by_stage(read_consumers(plan_run_root))
+    if recorded.get(stage) in _SETTLED:
+        raise StateError(
+            f"stage {stage} is already recorded {recorded[stage]!r} — a lead's "
+            "ruling is not rewritten here",
+            stage="consumers",
+        )
+
+    if not _git_commit_exists(project_root, head_commit):
+        raise StateError(
+            f"{head_commit} is not a commit in {project_root} — pass the commit "
+            "the stage's work actually landed as",
+            stage="git",
+        )
+
+    ok, conformance = _conformance_state(task_root, stage)
+    if not ok:
+        raise StateError(
+            f"stage {stage} conformance does not permit closing it "
+            f"({conformance}) — run the stage's conformance script, or record a "
+            'user waiver with prepare `--qa-waiver "<stageKey>:<reason>"`, '
+            "before closing the stage",
+            stage="conformance",
+        )
+
+    append_consumer(
+        plan_run_root,
+        impl_task_key=identity["taskKey"],
+        stage=stage,
+        status="done",
+        head_commit=head_commit,
+        closed_by="stage-close",
+    )
+    return {
+        "taskKey": identity["taskKey"],
+        "taskRoot": str(task_root),
+        "stage": stage,
+        "headCommit": head_commit,
+        "conformance": conformance,
+        "consumersPath": str(plan_run_root / "consumers.jsonl"),
+    }
+
+
+_CLI_EPILOG = r"""Usage:
+  okstra stage-close <task-key> --stage <N> --from-commit <sha>
+  okstra stage-close <task-key> --stage <N> --from-commit <sha> --project <dir>
+
+Records the `done` row an implementation run would have written, for a stage
+whose work is already committed but which never registered as done (the run
+ended before writing its carry sidecar). Refuses unless the Stage Map has that
+stage, no `done`/`failed` row exists for it, `--from-commit` resolves to a
+commit in the project repo, and the stage's conformance gate permits progress.
+
+Output: JSON { ok, taskKey, taskRoot, stage, headCommit, conformance,
+consumersPath }. Exit 1 on a refusal (the reason names what to do), 2 when
+PROJECT_ROOT cannot be resolved.
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Close an already-landed implementation stage as done.",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra stage-close")
+    parser.add_argument("task_key", metavar="task-key",
+                        help="project-id:task-group:task-id")
+    parser.add_argument("--stage", type=int, required=True,
+                        help="the Stage Map number to close")
+    parser.add_argument("--from-commit", required=True, dest="from_commit",
+                        help="the commit the stage's work landed as")
+    parser.add_argument("--project-root", "--project", default="",
+                        help="use this directory as PROJECT_ROOT")
+    parser.add_argument("--cwd", default=".",
+                        help="resolve PROJECT_ROOT starting from here")
+    args = parser.parse_args(argv)
+
+    def emit(payload: dict) -> None:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+    try:
+        resolved = resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
+    except ResolverError as exc:
+        emit({"ok": False, "stage": "resolve", "reason": str(exc)})
+        return 2
+
+    if args.stage < 1:
+        emit({"ok": False, "stage": "stage-map",
+              "reason": f"--stage must be a positive integer, got {args.stage}"})
+        return 1
+
+    try:
+        closed = close_stage(
+            Path(resolved), args.task_key, args.stage, args.from_commit.strip(),
+        )
+    except StateError as exc:
+        emit({
+            "ok": False,
+            "stage": getattr(exc, "stage", None) or "stage-close",
+            "reason": str(exc),
+        })
+        return 1
+
+    emit({"ok": True, **closed})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/tdd_bypass.py

@@ -0,0 +1,131 @@
+"""사용자 확인형 TDD 우회 원장 — `<task-root>/qa/tdd-bypass.json`.
+
+S10c 는 모든 stage 의 첫 step 에 `RED:` 를, 뒤 step 중 하나에 `GREEN:` 을
+요구하고, S10e 는 그 요구를 `doc-only` / `config-only` / `pure-rename` 세
+사유로만 면제한다. 세 사유 중 어느 것도 맞지 않는 stage 는 통과할 값이
+없으므로, 계획서가 가장 가까운 토큰을 골라 자기를 잘못 기술하게 된다
+(실측 2026-09-10, fontsninja-v3-site dev-10628-3 implementation-planning 002:
+제품 변경이 이전 run 에서 이미 커밋·적합성 PASS 까지 끝난 stage 를
+`config-only` 로 신고).
+
+그래서 네 번째 사유 `user-bypass` 는 계획서의 선언만으로는 성립하지 않는다.
+사용자가 `okstra prepare --tdd-bypass "<stage>:<reason>"` 로 이 파일에 사유를
+원문 그대로 남겨야 검증기가 인정한다 — `qa/self-mock-waivers.json` 이 gate A/B
+의 우회를 담는 방식과 같은 idiom 이고, 같은 `{reason, acknowledgedBy}` 계약을
+쓴다. 계획서가 스스로에게 면제를 발급하는 경로는 없다.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+from .json_boundary import (
+    JsonBoundaryError,
+    load_owned_object,
+    write_owned_object_atomic,
+)
+
+ARTIFACT = "tdd bypass ledger"
+FILENAME = "tdd-bypass.json"
+SCHEMA_VERSION = "1.0"
+
+# `tddExemption` 에 적는 값. S10e 가 이 토큰을 볼 때만 원장을 조회한다.
+REASON_TOKEN = "user-bypass"
+
+
+class TddBypassError(ValueError):
+    """TDD 우회 원장 입력이 계약을 위반했다."""
+
+
+def bypass_file(task_root: Path) -> Path:
+    """이 task 의 우회 원장 경로. conformance 산출물과 같은 `qa/` 아래다."""
+    return task_root / "qa" / FILENAME
+
+
+def parse_bypass_arg(value: object) -> tuple[int, str] | None:
+    """`--tdd-bypass` 값 `<stage>:<reason>` 를 (stage, reason) 로 분해.
+
+    형식이 아니거나 stage 가 1 이상의 정수가 아니면 None — 호출 측이 무엇을
+    받았는지 그대로 보여 주며 거절한다.
+    """
+    if not isinstance(value, str) or ":" not in value:
+        return None
+    raw_stage, reason = value.split(":", 1)
+    raw_stage, reason = raw_stage.strip(), reason.strip()
+    if not raw_stage.isdigit() or not reason:
+        return None
+    stage = int(raw_stage)
+    if stage < 1:
+        return None
+    return stage, reason
+
+
+def _entries(ledger: object) -> list[dict[str, Any]]:
+    rows = ledger.get("entries") if isinstance(ledger, Mapping) else None
+    return [row for row in rows if isinstance(row, dict)] if isinstance(rows, list) else []
+
+
+def record_bypass(
+    path: Path, stage: int, reason: str, *, at: str, acknowledged_by: str = "user",
+) -> None:
+    """stage 의 우회 사유를 원문 그대로 기록한다(같은 stage 는 마지막 값이 이긴다).
+
+    사용자가 사유를 고쳐 다시 부여하는 것이 정상 경로이므로 중복은 오류가
+    아니라 교체다. 파일이 없으면 만든다 — 전제 파일 부재로 거절하면 사용자가
+    빈 원장을 손으로 만들어야 한다.
+    """
+    if not isinstance(stage, int) or stage < 1:
+        raise TddBypassError(f"stage must be a positive integer, got {stage!r}")
+    if not isinstance(reason, str) or not reason.strip():
+        raise TddBypassError("reason must be a non-empty string")
+    if not isinstance(acknowledged_by, str) or not acknowledged_by.strip():
+        raise TddBypassError("acknowledgedBy must be a non-empty string")
+    ledger: dict[str, Any]
+    if path.is_file():
+        try:
+            ledger = load_owned_object(path, artifact=ARTIFACT)
+        except JsonBoundaryError as exc:
+            raise TddBypassError(str(exc)) from exc
+    else:
+        ledger = {"schemaVersion": SCHEMA_VERSION, "entries": []}
+    rows = [row for row in _entries(ledger) if row.get("stage") != stage]
+    rows.append({
+        "stage": stage,
+        "reason": reason.strip(),
+        "acknowledgedBy": acknowledged_by.strip(),
+        "at": at,
+    })
+    ledger["schemaVersion"] = ledger.get("schemaVersion") or SCHEMA_VERSION
+    ledger["entries"] = sorted(rows, key=lambda row: row["stage"])
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        write_owned_object_atomic(path, ledger, artifact=ARTIFACT)
+    except JsonBoundaryError as exc:
+        raise TddBypassError(str(exc)) from exc
+
+
+def granted_stages(path: Path) -> dict[int, str]:
+    """`{stage: reason}` — 사용자가 우회를 부여한 stage 들.
+
+    파일이 없으면 빈 map 이다(우회 없음). 사유나 승인자가 빈 행은 우회로
+    세지 않는다 — 그 행은 사용자가 무엇을 승인했는지 말하지 못한다.
+    """
+    if not path.is_file():
+        return {}
+    try:
+        ledger = load_owned_object(path, artifact=ARTIFACT)
+    except JsonBoundaryError as exc:
+        raise TddBypassError(str(exc)) from exc
+    granted: dict[int, str] = {}
+    for row in _entries(ledger):
+        stage = row.get("stage")
+        reason = row.get("reason")
+        acknowledged_by = row.get("acknowledgedBy")
+        if not isinstance(stage, int) or isinstance(stage, bool) or stage < 1:
+            continue
+        if not isinstance(reason, str) or not reason.strip():
+            continue
+        if not isinstance(acknowledged_by, str) or not acknowledged_by.strip():
+            continue
+        granted[stage] = reason.strip()
+    return granted

package/runtime/python/okstra_ctl/wizard/engine.py

@@ -35,10 +35,10 @@ from .state import Prompt, WizardError, WizardState, _is_role_selection_step
 from .prompts import _domain_prompt
 from .picker_navigation import (
     accept_picker_answer,
-    is_split_checkbox,
-    merge_split_checkbox_answer,
+    is_split_picker,
+    merge_split_picker_answer,
     present_picker,
-    split_checkbox,
+    split_picker,
 )
 from .roles import _submit_role_prompt, next_role_prompt
 from .steps_identity import _submit_task_pick
@@ -140,15 +140,18 @@ def next_prompt(state: WizardState) -> Prompt:
 def _native_picker_screen(state: WizardState, prompt: Prompt) -> Prompt:
     """호스트 네이티브 선택기 한도에 맞춘 화면.
 
-    단일 선택이 한도를 넘으면 쪽으로 나눈다(`present_picker`). 체크박스(`multi`)는
-    쪽으로 나누지 않는다 — 종전엔 한 줄씩 토글하는 쪽으로 내렸는데, claude-code
-    한도 4 에서 후보 12개는 쪽당 2개가 됐고, 쪽 사본이 추천 표시를 단 채 단일
-    선택이 돼 `Prompt` 의 추천 불변식(단일 선택은 추천 정확히 하나)에 걸려
-    화면이 열리지 않았다(실측 2026-09-09, verifier 전체 후보 화면). 대신
-    네이티브 질문 묶음에 실리는 크기(claude-code 4×4=16)면 같은 화면의 체크박스
-    질문 여러 개로 자른다(`split_checkbox`) — 묶음이 네이티브에 실릴 때만이고,
-    아니면 `CapabilityInteractionPort.plan` 이 `numbered-multi` 로 내려 전체
-    목록을 한 번에 보인다.
+    한도를 넘는 픽은 체크박스든 단일 선택이든 네이티브 질문 묶음에 실리는
+    크기(claude-code 4×4=16)까지 같은 화면의 체크박스 질문 여러 개로 자른다
+    (`split_picker`) — 사용자는 탭을 옮겨 다니며 한 번에 답한다. 단일 선택을
+    쪽으로 나누던 종전 화면은 후보 하나를 고르는 데 "다음 선택지" 를 누를
+    때마다 턴이 하나씩 들었다(실측 2026-09-09, 후보 13개인 critic 화면).
+
+    묶음에 못 실리면(옵션 16개 초과, 라벨 중복, 질문 묶음이 없는 세션)
+    단일 선택은 종전대로 쪽으로 나누고(`present_picker`), 체크박스는
+    `CapabilityInteractionPort.plan` 이 `numbered-multi` 로 내려 전체 목록을
+    한 번에 보인다. 체크박스는 쪽으로 나누지 않는다 — 쪽 사본이 추천 표시를
+    단 채 단일 선택이 돼 `Prompt` 의 추천 불변식(단일 선택은 추천 정확히
+    하나)에 걸려 화면이 열리지 않았다(실측 2026-09-09, verifier 전체 후보 화면).
     """
     if "native_single_select" not in state.available_functions:
         return prompt
@@ -157,14 +160,14 @@ def _native_picker_screen(state: WizardState, prompt: Prompt) -> Prompt:
             return prompt
         prompt = prompt.questions[0]
     port = default_host_registry().resolve(state.host_runtime).interaction()
+    split = split_picker(
+        prompt,
+        max_options=port.native_option_limit,
+        max_questions=port.native_question_limit,
+    )
+    if split is not prompt and _interaction_plan(state, split).kind == "native-group":
+        return split
     if prompt.multi:
-        split = split_checkbox(
-            prompt,
-            max_options=port.native_option_limit,
-            max_questions=port.native_question_limit,
-        )
-        if split is not prompt and _interaction_plan(state, split).kind == "native-group":
-            return split
         return prompt
     return present_picker(state, prompt, limit=port.native_option_limit)
 
@@ -219,7 +222,7 @@ def _sim_answer(prompt: Prompt) -> str:
 def _sim_advance(state: WizardState, prompt: Prompt) -> None:
     """기본답으로 한 화면 전진한다. progress 를 재계산하는 submit()/
     _submit_group() 은 호출하지 않고 step.submit 만 직접 호출해 재귀를 막는다."""
-    if is_split_checkbox(prompt):
+    if is_split_picker(prompt):
         # 조각 질문의 step 은 등록된 step 이 아니다 — 잘리지 않은 원본으로 낸다.
         prompt = _next_prompt_screen(state)
     try:
@@ -402,10 +405,10 @@ def submit(state: WizardState, value: str) -> dict[str, Any]:
         value = accept_picker_answer(state, original, value)
         if value is None:
             return {"echo": "", "next": prompt_payload(state, next_prompt(state))}
-    if is_split_checkbox(prompt):
-        # 질문 묶음으로 잘린 체크박스 — 탭별 CSV 를 한 줄로 합쳐 원본 step 의
-        # 제출 경로로 보낸다. 원본의 선택지로 검증한다.
-        value = merge_split_checkbox_answer(prompt, value)
+    if is_split_picker(prompt):
+        # 질문 묶음으로 잘린 픽 — 탭별 CSV 를 한 줄로 합쳐 원본 step 의 제출
+        # 경로로 보낸다. 원본의 선택지로 검증한다.
+        value = merge_split_picker_answer(prompt, value)
         prompt = _next_prompt_screen(state)
     elif prompt.kind == "pick_group":
         return _submit_group(state, prompt, value)

package/runtime/python/okstra_ctl/wizard/picker_navigation.py

@@ -1,13 +1,16 @@
 """호스트 선택기 한도 안에서 원래 선택지를 보존하는 두 가지 강등.
 
-단일 선택은 쪽으로 나눈다(`present_picker`). 체크박스(`multi`)는 쪽으로 나누지
-않는다 — 쪽 사본이 추천 표시를 단 채 단일 선택으로 바뀌면 `Prompt` 의 추천
-불변식에 걸리므로, 한 줄씩 토글하던 체크박스 쪽 나누기는 2026-09-09 에 뺐다.
-대신 네이티브 질문 묶음(claude-code `AskUserQuestion` 의 질문 4개 × 옵션 4개)에
-실리는 크기면 같은 화면 안의 체크박스 질문 여러 개로 자른다(`split_checkbox`):
-사용자는 탭마다 체크하고, 답은 하나의 CSV 로 합쳐져(`merge_split_checkbox_answer`)
-원래 step 의 제출 경로로 간다. 그 크기도 넘으면 `numbered-multi` 로 전체 목록을
-한 번에 보인다(`engine._native_picker_screen`).
+네이티브 질문 묶음(claude-code `AskUserQuestion` 의 질문 4개 × 옵션 4개)에
+실리는 크기면 같은 화면 안의 체크박스 질문 여러 개로 자른다(`split_picker`):
+사용자는 탭마다 체크하고, 답은 하나의 CSV 로 합쳐져(`merge_split_picker_answer`)
+원래 step 의 제출 경로로 간다. 단일 선택(예: critic 처럼 최대 1개인 역할)도
+같은 방식으로 자르되 통틀어 하나만 고른 답이어야 한다.
+
+그 크기도 넘거나 질문 묶음이 없는 세션이면, 단일 선택은 쪽으로 나누고
+(`present_picker`) 체크박스는 `numbered-multi` 로 전체 목록을 한 번에 보인다
+(`engine._native_picker_screen`). 체크박스를 쪽으로 나누던 경로는 쪽 사본이
+추천 표시를 단 채 단일 선택이 돼 `Prompt` 의 추천 불변식에 걸리므로
+2026-09-09 에 뺐다.
 """
 import json
 import math
@@ -20,10 +23,18 @@ _PAGE_PREFIX = "__okstra_picker_page__:"
 _SPLIT_SEPARATOR = "#"
 
 
-def split_checkbox(
+def split_picker(
     prompt: Prompt, *, max_options: int, max_questions: int,
 ) -> Prompt:
-    """옵션이 `max_options` 를 넘는 체크박스를 같은 화면의 질문 묶음으로 자른다.
+    """옵션이 `max_options` 를 넘는 픽을 같은 화면의 체크박스 질문 묶음으로 자른다.
+
+    조각은 원래 픽이 단일 선택이어도 체크박스다. 단일 선택 조각으로 두면 고를
+    것이 없는 조각에도 답이 있어야 해서 조각마다 "여기 없음" 한 줄이 들어가고,
+    조각당 실선택지가 하나 줄어 후보 13개짜리 critic 화면은 조각 5개가 돼
+    묶음에 아예 못 실린다(claude-code 한도 4×4). 체크박스 조각은 아무것도
+    고르지 않은 조각이 곧 답 없는 조각이라 그 줄이 필요 없다. 원래 픽이 단일
+    선택이었다는 사실은 그룹의 `multi=False` 로 남고, `merge_split_picker_answer`
+    가 통틀어 하나만 골랐는지 본다.
 
     질문 수는 옵션이 들어가는 최소 개수이고 옵션은 질문에 고르게 나눈다 —
     마지막 질문이 한 줄짜리가 되면 호스트 최소 옵션 수(2)에 걸려 묶음 전체가
@@ -31,7 +42,7 @@ def split_checkbox(
     앞머리 run 이 된다(`Prompt._check_recommendations`). `max_questions` 도
     넘으면 자르지 않고 그대로 돌려준다.
     """
-    if prompt.kind != "pick" or not prompt.multi or len(prompt.options) <= max_options:
+    if prompt.kind != "pick" or len(prompt.options) <= max_options:
         return prompt
     count = len(prompt.options)
     questions = math.ceil(count / max_options)
@@ -48,6 +59,7 @@ def split_checkbox(
             step=f"{prompt.step}{_SPLIT_SEPARATOR}{index + 1}",
             label=f"{prompt.label} ({offset + 1}–{offset + size}/{count})",
             options=shown,
+            multi=True,
         ))
         offset += size
     return Prompt(
@@ -56,11 +68,12 @@ def split_checkbox(
         label=prompt.label,
         help=prompt.help,
         echo_template=prompt.echo_template,
+        multi=prompt.multi,
         questions=chunks,
     )
 
 
-def is_split_checkbox(prompt: Prompt) -> bool:
+def is_split_picker(prompt: Prompt) -> bool:
     return prompt.kind == "pick_group" and bool(prompt.questions) and all(
         question.multi
         and question.step.startswith(f"{prompt.step}{_SPLIT_SEPARATOR}")
@@ -68,8 +81,13 @@ def is_split_checkbox(prompt: Prompt) -> bool:
     )
 
 
-def merge_split_checkbox_answer(prompt: Prompt, value: str) -> str:
-    """질문 묶음 답(JSON, 조각 step → CSV)을 원래 체크박스의 CSV 한 줄로 합친다."""
+def merge_split_picker_answer(prompt: Prompt, value: str) -> str:
+    """질문 묶음 답(JSON, 조각 step → CSV)을 원래 픽의 CSV 한 줄로 합친다.
+
+    원래 픽이 단일 선택이면(그룹의 `multi=False`) 통틀어 한 줄만 고른 답이어야
+    한다 — 두 조각에서 고른 답을 그대로 합치면 원래 step 은 `a,b` 를 값 하나로
+    받아 "선택지가 아니다" 라고만 말한다.
+    """
     try:
         answers = json.loads(value or "{}")
     except json.JSONDecodeError as exc:
@@ -87,6 +105,11 @@ def merge_split_checkbox_answer(prompt: Prompt, value: str) -> str:
     for question in prompt.questions:
         raw = str(answers.get(question.step, "") or "")
         chosen.extend(item.strip() for item in raw.split(",") if item.strip())
+    if not prompt.multi and len(chosen) > 1:
+        raise WizardError(
+            f"wizard step {prompt.step!r}: this screen takes one choice, "
+            f"but {len(chosen)} were picked across its tabs: {', '.join(chosen)}"
+        )
     return ",".join(chosen)
 
 

package/runtime/python/okstra_ctl/wizard/roles.py

@@ -7,15 +7,16 @@ verifier: `max > 1`)은 체크박스 한 장이고, 고른 모델 수가 곧 인
 (`min = 0`, 예: critic)은 같은 화면에 "추가 안 함" 줄이 있다(종전 `role-add:`).
 고정 단일 역할(`min = max = 1`, 예: report-writer·implementer)은 단일 선택 한 장이다.
 
-체크박스 화면(`role-models:<role>`)은 실행 가능한 전체 후보를 한 번에 싣는다.
-기본 후보(프로젝트 `modelDefaults`, 없으면 카탈로그 기본값)가 앞이고 권장
-수만큼의 앞줄이 추천이다. 호스트 네이티브 선택기의 옵션 한도(claude-code 4,
-codex 3, grok 15)를 넘으면 네이티브 질문 묶음에 실리는 크기(claude-code 4×4)
-까지는 같은 화면의 체크박스 질문 여러 개로 자르고(`picker_navigation.split_checkbox`),
-그것도 넘으면 `CapabilityInteractionPort.plan` 이 `numbered-multi` 로 내려 번호
-목록이 된다 — 기본 후보만 실은 짧은 화면과 "직접 선택" 이 여는 두 번째 화면으로
-나누던 설계는 2026-09-09 사용자 요청으로 뺐다(후보 12개 중 3개만 보이고, 두
-번째 화면은 쪽 나누기가 추천 불변식을 깨 열리지도 않았다).
+모델 화면(`role-models:<role>`, `role-model:<role>:1`)은 실행 가능한 전체 후보를
+한 번에 싣는다. 기본 후보(프로젝트 `modelDefaults`, 없으면 카탈로그 기본값)가
+앞이고 권장 수만큼의 앞줄이 추천이다. 호스트 네이티브 선택기의 옵션 한도
+(claude-code 4, codex 3, grok 15)를 넘으면 체크박스든 단일 선택이든 네이티브
+질문 묶음에 실리는 크기(claude-code 4×4)까지는 같은 화면의 체크박스 질문 여러
+개로 자르고(`picker_navigation.split_picker`), 그것도 넘으면 체크박스는
+`CapabilityInteractionPort.plan` 이 `numbered-multi` 로 내려 번호 목록이,
+단일 선택은 쪽 나누기가 된다 — 기본 후보만 실은 짧은 화면과 "직접 선택" 이 여는
+두 번째 화면으로 나누던 설계는 2026-09-09 사용자 요청으로 뺐다(후보 12개 중
+3개만 보이고, 두 번째 화면은 쪽 나누기가 추천 불변식을 깨 열리지도 않았다).
 """
 from __future__ import annotations
 
@@ -199,12 +200,16 @@ def _available_role_models(
 
 def _skip_option(requirement: RoleRequirement, t: dict, *, recommended: bool) -> Option:
     # 역할을 빼면 그 역할이 맡던 판정이 사라진다. 그 결과를 아는 역할만 경고를
-    # 단다 — 예: critic 이 없으면 분석자 동수를 가를 주체가 없다.
+    # 단다 — 예: critic 이 없으면 분석자 동수를 가를 주체가 없다. 경고는 라벨이
+    # 아니라 설명에 실린다: 체크박스 탭의 답은 고른 라벨을 `, ` 로 이어 붙인
+    # 한 줄이라(claude-code relay), 쉼표가 든 라벨 하나가 그 화면 전체를
+    # 네이티브 묶음에서 떨어뜨려 쪽 나누기로 되돌린다.
     warnings = t["options"].get("skip_warnings", {})
     warning = warnings.get(requirement.role, "") if isinstance(warnings, dict) else ""
     return _opt(
         ROLE_SKIP_TOKEN,
-        t["options"]["skip"].format(skip_warning=warning),
+        t["options"]["skip"],
+        warning,
         recommended=recommended,
     )
 

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -13,6 +13,7 @@ from .convergence_reverify_prompt import RENDERED_BY_LINE
 from .convergence_critic_verify_prompt import (
     RENDERED_BY_LINE as CRITIC_VERIFY_RENDERED_BY_LINE,
 )
+from .plan_items import RENDERED_BY_LINE as PLAN_VERIFY_RENDERED_BY_LINE
 from .worker_prompt_body import analysis_worker_label
 from .json_boundary import load_owned_object
 from .worker_prompt_policy import (
@@ -20,6 +21,7 @@ from .worker_prompt_policy import (
     IMPLEMENTATION_HEADERS,
     CRITIC_VERIFY_DISPATCH_KIND,
     PromptPlan,
+    is_plan_verify_dispatch_kind,
     resolve_prompt_plan_for_manifest,
 )
 from .worker_prompt_headers import EVIDENCE_LEDGER_HEADER
@@ -325,7 +327,19 @@ def validate_reverify_prompt(
     ):
         errors.append("phase boundary block must precede reverify instructions")
     instructions = normalized[_task_instructions_offset(normalized):]
-    if dispatch_kind == CRITIC_VERIFY_DISPATCH_KIND:
+    if is_plan_verify_dispatch_kind(dispatch_kind):
+        # 계획 본문 라운드의 정본 렌더러는 convergence 가 아니라 `okstra
+        # plan-items prompt` 다. 같은 서명을 요구하면 통과할 값이 하나도 없다
+        # (2026-09-09 dev-10642 implementation-planning 001: 라운드 0회).
+        if PLAN_VERIFY_RENDERED_BY_LINE not in instructions:
+            errors.append(
+                "plan-verify instruction is not the output of `okstra plan-items "
+                "prompt` (missing the `**Rendered by:**` line) — render it with "
+                "`okstra plan-items prompt --run-manifest <run-manifest>` and pass "
+                "that output verbatim as --instruction; hand-written plan item "
+                "queues are refused"
+            )
+    elif dispatch_kind == CRITIC_VERIFY_DISPATCH_KIND:
         if CRITIC_VERIFY_RENDERED_BY_LINE not in instructions:
             errors.append(
                 "critic-verify instruction is not the output of `okstra convergence "