okstra 0.191.2 → 0.192.0

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

@@ -1,4 +1,18 @@
-"""역할 인스턴스 선택 루프 — `next_role_prompt` 와 역할 수·모델 픽의 검증·되감기."""
+"""역할 인스턴스 선택 루프 — `next_role_prompt` 와 역할 모델 픽의 검증·되감기.
+
+역할 하나에 화면 하나다. 여러 인스턴스를 띄우는 역할(analyser·designer·planner·
+verifier: `max > 1`)은 체크박스 한 장이고, 고른 모델 수가 곧 인스턴스 수다 —
+"몇 개를 띄울까" 를 따로 묻지 않는다(종전 `role-count:` 화면, 실측 2026-09-09
+사용자 요청으로 제거). 허용 범위와 권장 수는 화면 문구가 말한다. 선택 역할
+(`min = 0`, 예: critic)은 같은 화면에 "추가 안 함" 줄이 있다(종전 `role-add:`).
+고정 단일 역할(`min = max = 1`, 예: report-writer·implementer)은 단일 선택 한 장이다.
+
+체크박스 화면은 두 장이다. `role-models:<role>` 은 기본 후보(프로젝트
+`modelDefaults` 또는 카탈로그 기본값)만 싣고 권장 수만큼 앞줄을 추천으로 표시한다
+— 호스트 네이티브 선택기의 옵션 한도(claude-code 4, codex 3, grok 15) 안에
+들어가야 체크박스로 렌더되기 때문이다. 마지막 줄 "직접 선택" 이
+`role-models-custom:<role>` 을 열고, 거기에 실행 가능한 전체 후보가 실린다.
+"""
 from __future__ import annotations
 
 from pathlib import Path
@@ -23,6 +37,7 @@ from okstra_ctl.run import (
     _model_default_scopes,
 )
 
+from .ids import PICK_TYPE_CUSTOM
 from .state import (
     Option,
     Prompt,
@@ -35,17 +50,37 @@ from .state import (
 )
 from .prompts import _opt, _p
 
+# 선택 역할의 "추가 안 함" 값. 모델 참조는 `<provider>/<model>` 꼴이라 겹치지 않는다.
+ROLE_SKIP_TOKEN = "0"
 
-def _role_count_prompt_id(role: str) -> str:
-    return f"role-count:{role}"
+_MODELS_PREFIX = "role-models:"
+_CUSTOM_PREFIX = "role-models-custom:"
+_SINGLE_PREFIX = "role-model:"
 
 
-def _role_add_prompt_id(role: str) -> str:
-    return f"role-add:{role}"
+def _role_models_prompt_id(role: str) -> str:
+    return f"{_MODELS_PREFIX}{role}"
+
+
+def _role_models_custom_prompt_id(role: str) -> str:
+    return f"{_CUSTOM_PREFIX}{role}"
 
 
 def _role_model_prompt_id(role: str, ordinal: int) -> str:
-    return f"role-model:{role}:{ordinal}"
+    return f"{_SINGLE_PREFIX}{role}:{ordinal}"
+
+
+def _step_role(step_id: str) -> str:
+    """역할 선택 step id 가 가리키는 역할. 역할 선택 step 이 아니면 빈 문자열."""
+    for prefix in (_CUSTOM_PREFIX, _MODELS_PREFIX, _SINGLE_PREFIX):
+        if step_id.startswith(prefix):
+            return step_id[len(prefix):].split(":", 1)[0]
+    return ""
+
+
+def _fixed_single(requirement: RoleRequirement) -> bool:
+    """정확히 한 인스턴스만 두는 역할 — 단일 선택 화면이다."""
+    return requirement.min_count == requirement.max_count == 1
 
 
 def _selected_role_count(
@@ -74,93 +109,34 @@ def _selectable_static_requirements(
     )
 
 
-def _count_prompt(
-    state: WizardState,
-    requirement: RoleRequirement,
-) -> Prompt:
-    prompt = _p(
-        state.workspace_root,
-        "role_count",
-        role=requirement.role,
-        minimum=str(requirement.min_count),
-        maximum=str(requirement.max_count),
-        default=str(requirement.recommended_count),
-    )
-    return Prompt(
-        step=_role_count_prompt_id(requirement.role),
-        kind="pick",
-        label=prompt["label"],
-        options=[
-            _opt(
-                str(count),
-                prompt["options"]["count"].format(
-                    count=count,
-                    default_suffix=(
-                        prompt["options"].get("default_suffix", "")
-                        if count == requirement.recommended_count
-                        else ""
-                    ),
-                ),
-            )
-            for count in range(requirement.min_count, requirement.max_count + 1)
-        ],
-        echo_template=prompt["echo_template"],
+def _static_requirements(profile: RoleProfile) -> tuple[RoleRequirement, ...]:
+    return tuple(
+        requirement for requirement in profile.roles
+        if not requirement.dynamic and requirement.max_count > 0
     )
 
 
-def _role_add_prompt(
-    state: WizardState,
-    requirement: RoleRequirement,
-) -> Prompt:
-    """min=0 선택 역할: 프로필의 적정 수량이 기본이고, 1..max 를 이 스텝에서 고른다.
-
-    적정이 0 이면 기본은 추가 안 함이다. 0 보다 큰 적정을 선언한 역할만 기본이 열린
-    상태로 뜬다 — 어느 쪽이든 사용자는 이 화면에서 바꿀 수 있다.
-    """
-    prompt = _p(
-        state.workspace_root,
-        "role_add",
-        role=requirement.role,
-        maximum=str(requirement.max_count),
-    )
-    suffix = prompt["options"].get("default_suffix", "")
-    # 역할을 빼면 그 역할이 맡던 판정이 사라진다. 그 결과를 아는 역할만 0 옵션에
-    # 경고를 단다 — 예: critic 이 없으면 분석자 동수를 가를 주체가 없다.
-    skip_warnings = prompt["options"].get("skip_warnings", {})
-    skip_warning = (
-        skip_warnings.get(requirement.role, "")
-        if isinstance(skip_warnings, dict)
-        else ""
+def _count_range_text(requirement: RoleRequirement, t: dict) -> str:
+    """화면 문구의 허용 범위: "허용 2..5개, 권장 3개" 또는 "정확히 2개"."""
+    ranges = t["labels"]
+    if requirement.min_count == requirement.max_count:
+        return ranges["exact"].format(count=requirement.max_count)
+    return ranges["range"].format(
+        minimum=requirement.min_count,
+        maximum=requirement.max_count,
+        recommended=requirement.recommended_count,
     )
 
-    def _default_suffix(count: int) -> str:
-        return suffix if count == requirement.recommended_count else ""
 
-    options = [
-        _opt(
-            "0",
-            prompt["options"]["skip"].format(
-                default_suffix=_default_suffix(0),
-                skip_warning=skip_warning,
-            ),
-        ),
-    ]
-    for count in range(1, requirement.max_count + 1):
-        options.append(
-            _opt(
-                str(count),
-                prompt["options"]["add"].format(
-                    count=count, default_suffix=_default_suffix(count),
-                ),
-            )
-        )
-    return Prompt(
-        step=_role_add_prompt_id(requirement.role),
-        kind="pick",
-        label=prompt["label"],
-        options=options,
-        echo_template=prompt["echo_template"],
-    )
+def _role_models_texts(
+    state: WizardState, prompt_key: str, requirement: RoleRequirement,
+) -> dict:
+    """`role_models` / `role_models_custom` 문구. 허용 범위 문장은 `range` 키다."""
+    probe = _p(state.workspace_root, prompt_key, role=requirement.role, range="")
+    range_text = _count_range_text(requirement, probe)
+    texts = _p(state.workspace_root, prompt_key, role=requirement.role, range=range_text)
+    texts["range"] = range_text
+    return texts
 
 
 def _role_default_candidates(
@@ -193,55 +169,153 @@ def _role_default_candidates(
     )
 
 
-def _role_model_options(
+def _available_role_models(
+    state: WizardState,
+    profile: RoleProfile,
+    requirement: RoleRequirement,
+    context: AssignmentContext,
+    scopes: ModelDefaultScopes,
+) -> tuple[tuple[str, ...], tuple[str, ...]]:
+    """(기본 후보, 실행 가능한 전체 후보). 전체 후보는 기본 후보를 앞에 둔다.
+
+    실행 가능 여부는 prepare 와 같은 배정 스냅샷(`resolve_model_assignment`)으로
+    판정한다 — 카탈로그에는 있지만 이 호스트·환경에서 못 띄우는 모델은 싣지
+    않는다.
+    """
+    role = requirement.role
+    executable = set(_executable_role_models(state, profile, requirement, context))
+    defaults = tuple(
+        model_ref
+        for model_ref in _role_default_candidates(state, role, context.pool, scopes)
+        if model_ref in executable
+    )
+    everything = tuple(dict.fromkeys([
+        *defaults,
+        *(
+            str(model.model_ref) for model in context.pool.list(role=role)
+            if str(model.model_ref) in executable
+        ),
+    ]))
+    return defaults, everything
+
+
+def _shortlist_budget(state: WizardState, requirement: RoleRequirement) -> int:
+    """`role-models:` 화면에 실을 모델 줄 수.
+
+    호스트에 네이티브 선택기가 있으면 그 한도에서 "직접 선택" 한 줄과, 선택
+    역할이면 "추가 안 함" 한 줄을 뺀 수다. 한도를 넘기는 순간
+    `CapabilityInteractionPort.plan` 이 번호 목록으로 내려 체크박스가 아니게
+    된다. 선택기 자체가 없는 호스트는 어차피 번호 목록이므로 자르지 않는다.
+    """
+    functions = set(state.available_functions)
+    if "native_single_select" not in functions and "native_multi_select" not in functions:
+        return 10**6
+    port = default_host_registry().resolve(state.host_runtime).interaction()
+    reserved = 1 + (1 if requirement.min_count == 0 else 0)
+    return max(1, port.native_option_limit - reserved)
+
+
+def _skip_option(requirement: RoleRequirement, t: dict, *, recommended: bool) -> Option:
+    # 역할을 빼면 그 역할이 맡던 판정이 사라진다. 그 결과를 아는 역할만 경고를
+    # 단다 — 예: critic 이 없으면 분석자 동수를 가를 주체가 없다.
+    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),
+        recommended=recommended,
+    )
+
+
+def _role_models_prompt(
+    state: WizardState,
+    profile: RoleProfile,
+    requirement: RoleRequirement,
+    context: AssignmentContext,
+    scopes: ModelDefaultScopes,
+    *,
+    full: bool,
+) -> Prompt:
+    """역할 하나의 모델 화면. `full` 이면 전체 후보, 아니면 기본 후보 + 직접 선택.
+
+    추천은 권장 수만큼의 앞줄이다 — 프로젝트 `modelDefaults`(없으면 카탈로그
+    기본값) 순서가 그 근거다. 권장이 0인 선택 역할은 "추가 안 함" 이 추천이다.
+    """
+    role = requirement.role
+    pool = context.pool
+    defaults, everything = _available_role_models(
+        state, profile, requirement, context, scopes,
+    )
+    if not everything:
+        _validate_role_selection_feasibility(state, profile, context, scopes)
+        raise WizardError(f"role {role!r} has no executable model candidates")
+    custom = full
+    if not full:
+        shown = defaults[: _shortlist_budget(state, requirement)]
+        # 기본 후보만으로 최소 수를 못 채우면 줄인 목록은 답이 될 수 없다 —
+        # 같은 화면에 전체 후보를 싣는다.
+        if len(shown) < min(requirement.min_count, len(everything)) or not shown:
+            full = True
+    if full:
+        shown = everything
+    prompt_key = "role_models_custom" if custom else "role_models"
+    t = _role_models_texts(state, prompt_key, requirement)
+    label = t["label"]
+    optional = requirement.min_count == 0
+    skip_first = optional and requirement.recommended_count == 0
+    options: list[Option] = []
+    if skip_first:
+        options.append(_skip_option(requirement, t, recommended=True))
+    for index, model_ref in enumerate(shown):
+        model = pool.resolve(model_ref)
+        options.append(_opt(
+            model_ref,
+            t["options"]["model"].format(model_ref=model_ref, display=model.display_name),
+            recommended=index < requirement.recommended_count,
+        ))
+    if optional and not skip_first:
+        options.append(_skip_option(requirement, t, recommended=False))
+    if not full:
+        options.append(_opt(
+            PICK_TYPE_CUSTOM,
+            t["options"][PICK_TYPE_CUSTOM].format(total=len(everything)),
+        ))
+    return Prompt(
+        step=(
+            _role_models_custom_prompt_id(role) if custom
+            else _role_models_prompt_id(role)
+        ),
+        kind="pick",
+        multi=requirement.max_count > 1,
+        label=label,
+        options=options,
+        echo_template=t["echo_template"],
+    )
+
+
+def _single_model_options(
     state: WizardState,
     profile: RoleProfile,
     role: str,
-    ordinal: int,
     context: AssignmentContext,
     scopes: ModelDefaultScopes,
 ) -> list[Option]:
+    """고정 단일 역할의 후보 전체. 기본 후보가 앞이고 첫 줄이 추천이다."""
     pool = context.pool
-    defaults = _role_default_candidates(state, role, pool, scopes)
-    if defaults:
-        offset = (ordinal - 1) % len(defaults)
-        defaults = (*defaults[offset:], *defaults[:offset])
-    candidate_refs = [
-        *defaults,
-        *(str(model.model_ref) for model in pool.list(role=role)),
-    ]
-    ordered_refs = tuple(dict.fromkeys(candidate_refs))
-    default_refs = frozenset(defaults)
-    prompt = _p(
-        state.workspace_root,
-        "role_model",
-        role=role,
-        ordinal="1",
-        count="1",
+    requirement = next(row for row in profile.roles if row.role == role)
+    defaults, everything = _available_role_models(
+        state, profile, requirement, context, scopes,
     )
+    prompt = _p(state.workspace_root, "role_model", role=role)
     options: list[Option] = []
-    for model_ref in ordered_refs:
-        availability = pool.availability(
-            model_ref,
-            role,
-            state.host_runtime,
-            "new-session",
-        )
-        if not availability.available:
-            continue
+    for model_ref in everything:
         candidate_models = {
             selected_role: tuple(models)
             for selected_role, models in state.role_models.items()
         }
-        selected = list(candidate_models.get(role, ()))[: ordinal - 1]
-        selected.append(model_ref)
-        candidate_models[role] = tuple(selected)
+        candidate_models[role] = (model_ref,)
         if not _role_selection_can_complete(
-            state,
-            profile,
-            context,
-            candidate_models,
-            scopes,
+            state, profile, context, candidate_models, scopes,
         ):
             continue
         model = pool.resolve(model_ref)
@@ -252,10 +326,11 @@ def _role_model_options(
                 display=model.display_name,
                 default_suffix=(
                     prompt["options"].get("default_suffix", "")
-                    if model_ref in default_refs
+                    if model_ref in defaults
                     else ""
                 ),
             ),
+            recommended=not options,
         ))
     if not options:
         _validate_role_selection_feasibility(state, profile, context, scopes)
@@ -267,60 +342,36 @@ def _model_prompt(
     state: WizardState,
     profile: RoleProfile,
     requirement: RoleRequirement,
-    ordinal: int,
     context: AssignmentContext,
     scopes: ModelDefaultScopes,
 ) -> Prompt:
-    prompt = _p(
-        state.workspace_root,
-        "role_model",
-        role=requirement.role,
-        ordinal=str(ordinal),
-        count=str(_selected_role_count(state, requirement)),
-    )
+    prompt = _p(state.workspace_root, "role_model", role=requirement.role)
     return Prompt(
-        step=_role_model_prompt_id(requirement.role, ordinal),
+        step=_role_model_prompt_id(requirement.role, 1),
         kind="pick",
         label=prompt["label"],
-        options=_role_model_options(
-            state,
-            profile,
-            requirement.role,
-            ordinal,
-            context,
-            scopes,
+        options=_single_model_options(
+            state, profile, requirement.role, context, scopes,
         ),
         echo_template=prompt["echo_template"],
     )
 
 
-def _rewind_invalid_role_models(
-    state: WizardState,
-    requirements: tuple[RoleRequirement, ...],
-    requirement_index: int,
-    model_index: int,
-) -> None:
-    requirement = requirements[requirement_index]
-    del state.role_models[requirement.role][model_index:]
-    invalid_ids: set[str] = set()
-    for later_index, later_requirement in enumerate(
-        requirements[requirement_index:],
-        start=requirement_index,
-    ):
-        first_ordinal = model_index + 1 if later_index == requirement_index else 1
-        later_count = _selected_role_count(state, later_requirement)
-        invalid_ids.update(
-            _role_model_prompt_id(later_requirement.role, ordinal)
-            for ordinal in range(first_ordinal, later_count + 1)
-        )
-        if later_index != requirement_index:
-            state.role_models.pop(later_requirement.role, None)
+def _drop_role_selection(state: WizardState, roles: set[str]) -> None:
+    """이 역할들의 선택값과 step 기록을 지운다."""
+    for role in roles:
+        state.role_models.pop(role, None)
+        state.role_counts.pop(role, None)
+    state.role_models_custom = [
+        role for role in state.role_models_custom if role not in roles
+    ]
     state.role_selection_order = [
         step_id for step_id in state.role_selection_order
-        if step_id not in invalid_ids
+        if _step_role(step_id) not in roles
     ]
     state.answered = [
-        step_id for step_id in state.answered if step_id not in invalid_ids
+        step_id for step_id in state.answered
+        if not (_is_role_selection_step(step_id) and _step_role(step_id) in roles)
     ]
 
 
@@ -331,46 +382,35 @@ def _discard_invalid_previous_models(
     context: AssignmentContext,
     scopes: ModelDefaultScopes,
 ) -> None:
+    """재개한 상태의 선택값이 지금의 배정 스냅샷에서 무효면 그 역할부터 되감는다.
+
+    무효 판정은 역할 단위다 — 체크박스 한 장이 그 역할의 답이므로, 그 안의 모델
+    하나가 빠졌어도 같은 화면을 다시 묻는다. 그 뒤 역할들은 앞 역할의 답에
+    따라 후보가 달라지므로 함께 비운다.
+    """
     selected_models = {
         role: tuple(models) for role, models in state.role_models.items()
     }
     if _role_selection_error(
-        state,
-        profile,
-        context,
-        selected_models,
-        scopes,
+        state, profile, context, selected_models, scopes,
     ) is None:
         return
-    selected_prefix: dict[str, tuple[str, ...]] = {}
-    for requirement_index, requirement in enumerate(requirements):
-        count = _selected_role_count(state, requirement)
+    prefix: dict[str, tuple[str, ...]] = {}
+    for index, requirement in enumerate(requirements):
         selected = state.role_models.get(requirement.role, [])
-        if len(selected) > count:
-            raise WizardError(
-                f"role {requirement.role!r} has {len(selected)} models for "
-                f"{count} instances"
-            )
-        for index, model_ref in enumerate(selected):
-            candidate_prefix = dict(selected_prefix)
-            candidate_prefix[requirement.role] = tuple(selected[: index + 1])
-            if _role_selection_can_complete(
-                state,
-                profile,
-                context,
-                candidate_prefix,
-                scopes,
-            ):
-                continue
-            _rewind_invalid_role_models(
-                state,
-                requirements,
-                requirement_index,
-                index,
+        if not selected:
+            continue
+        count = _selected_role_count(state, requirement)
+        candidate = dict(prefix)
+        candidate[requirement.role] = tuple(selected)
+        if len(selected) > count or not _role_selection_can_complete(
+            state, profile, context, candidate, scopes,
+        ):
+            _drop_role_selection(
+                state, {later.role for later in requirements[index:]},
             )
             return
-        if selected:
-            selected_prefix[requirement.role] = tuple(selected)
+        prefix[requirement.role] = tuple(selected)
 
 
 def _host_session_context(state: WizardState) -> HostSessionContext:
@@ -475,11 +515,7 @@ def _role_selection_can_complete(
 ) -> bool:
     completed = _completed_role_models(state, profile, context, role_models)
     return completed is not None and _role_selection_error(
-        state,
-        profile,
-        context,
-        completed,
-        scopes,
+        state, profile, context, completed, scopes,
     ) is None
 
 
@@ -507,45 +543,7 @@ def _validate_role_selection_feasibility(
         raise WizardError(error)
 
 
-def next_role_prompt(state: WizardState) -> Prompt | None:
-    """Ask every adjustable count before one model question per role instance."""
-    if not _role_selection_enabled(state) or not _identity_ready(state):
-        return None
-    state.use_defaults = False
-    profile = _load_role_profile_for_state(state)
-    for requirement in profile.roles:
-        # 필수 수량: min < max 이고 min > 0 일 때만.
-        if (
-            requirement.dynamic
-            or requirement.min_count == requirement.max_count
-            or requirement.min_count == 0
-        ):
-            continue
-        if requirement.role not in state.role_counts:
-            return _count_prompt(state, requirement)
-        count = state.role_counts[requirement.role]
-        if count < requirement.min_count or count > requirement.max_count:
-            raise WizardError(
-                f"role {requirement.role!r} count must be in "
-                f"{requirement.min_count}..{requirement.max_count}: {count}"
-            )
-    for requirement in profile.roles:
-        # 선택 역할(min=0, max>0): 기본은 추가 안 함. role-add 로만 연다.
-        if (
-            requirement.dynamic
-            or requirement.min_count != 0
-            or requirement.max_count == 0
-        ):
-            continue
-        if requirement.role not in state.role_counts:
-            return _role_add_prompt(state, requirement)
-        count = state.role_counts[requirement.role]
-        if count < 0 or count > requirement.max_count:
-            raise WizardError(
-                f"role {requirement.role!r} count must be in "
-                f"0..{requirement.max_count}: {count}"
-            )
-    requirements = _selectable_static_requirements(state, profile)
+def _load_context(state: WizardState) -> tuple[AssignmentContext, ModelDefaultScopes]:
     try:
         scopes = _model_default_scopes(Path(state.project_root))
     except (PrepareError, ValueError) as exc:
@@ -554,41 +552,123 @@ def next_role_prompt(state: WizardState) -> Prompt | None:
         host_runtime=state.host_runtime,
         terminal_backend=detect_terminal_backend(),
     )
-    _discard_invalid_previous_models(
-        state,
-        profile,
-        requirements,
-        context,
-        scopes,
-    )
+    return context, scopes
+
+
+def next_role_prompt(state: WizardState) -> Prompt | None:
+    """프로필 순서대로 역할마다 화면 하나 — 답이 없는 첫 역할의 화면을 낸다."""
+    if not _role_selection_enabled(state) or not _identity_ready(state):
+        return None
+    state.use_defaults = False
+    profile = _load_role_profile_for_state(state)
+    requirements = _static_requirements(profile)
+    context, scopes = _load_context(state)
+    _discard_invalid_previous_models(state, profile, requirements, context, scopes)
     for requirement in requirements:
-        count = _selected_role_count(state, requirement)
-        selected = state.role_models.get(requirement.role, [])
-        if len(selected) < count:
-            return _model_prompt(
+        role = requirement.role
+        selected = state.role_models.get(role, [])
+        if _fixed_single(requirement):
+            if not selected:
+                return _model_prompt(state, profile, requirement, context, scopes)
+            continue
+        if role in state.role_models_custom:
+            return _role_models_prompt(
+                state, profile, requirement, context, scopes, full=True,
+            )
+        if role not in state.role_counts:
+            return _role_models_prompt(
+                state, profile, requirement, context, scopes, full=False,
+            )
+        count = state.role_counts[role]
+        if count != len(selected) or not (
+            (0 if requirement.min_count == 0 else requirement.min_count)
+            <= count <= requirement.max_count
+        ):
+            # 재개한 상태의 수와 모델이 어긋난다 — 그 역할부터 다시 묻는다.
+            _drop_role_selection(
                 state,
-                profile,
-                requirement,
-                len(selected) + 1,
-                context,
-                scopes,
+                {later.role for later in requirements[requirements.index(requirement):]},
+            )
+            return _role_models_prompt(
+                state, profile, requirement, context, scopes, full=False,
             )
     _validate_role_selection_feasibility(state, profile, context, scopes)
     return None
 
 
+def _requirement_for(profile: RoleProfile, role: str) -> RoleRequirement:
+    requirement = next((row for row in profile.roles if row.role == role), None)
+    if requirement is None or requirement.dynamic or requirement.max_count == 0:
+        raise WizardError(f"role {role!r} does not accept a model selection")
+    return requirement
+
+
+def _submit_role_models(
+    state: WizardState,
+    profile: RoleProfile,
+    requirement: RoleRequirement,
+    prompt: Prompt,
+    value: str,
+) -> str:
+    """체크박스(또는 선택 역할 단일 픽)의 답을 그 역할의 수와 모델로 확정한다."""
+    role = requirement.role
+    prompt_key = (
+        "role_models_custom" if prompt.step.startswith(_CUSTOM_PREFIX)
+        else "role_models"
+    )
+    t = _role_models_texts(state, prompt_key, requirement)
+    range_text = t["range"]
+    # 같은 값이 두 번 오면(번호 목록에서 `1,1`) 한 번으로 센다 — 거절할 일이 아니다.
+    picked = list(dict.fromkeys(
+        item.strip() for item in (value or "").split(",") if item.strip()
+    ))
+    if PICK_TYPE_CUSTOM in picked:
+        if role not in state.role_models_custom:
+            state.role_models_custom.append(role)
+        return t["echo_variants"]["custom"]
+    allowed = {option.value for option in prompt.options}
+    unknown = [item for item in picked if item not in allowed]
+    if unknown:
+        raise WizardError(t["errors"]["unknown_option"].format(values=", ".join(unknown)))
+    models = [item for item in picked if item != ROLE_SKIP_TOKEN]
+    # "추가 안 함" 과 모델을 같이 고르면 모델을 고른 것이다.
+    if not models:
+        if ROLE_SKIP_TOKEN not in picked:
+            raise WizardError(t["errors"]["min_one_required"].format(range=range_text))
+        previous = (state.role_counts.get(role), state.role_models.get(role))
+        state.role_counts[role] = 0
+        state.role_models.pop(role, None)
+        state.role_models_custom = [r for r in state.role_models_custom if r != role]
+        return t["echo_variants"]["skipped"]
+    if not requirement.min_count <= len(models) <= requirement.max_count:
+        raise WizardError(t["errors"]["count_out_of_range"].format(
+            range=range_text, count=len(models),
+        ))
+    previous_count = state.role_counts.get(role)
+    previous_models = state.role_models.get(role)
+    state.role_counts[role] = len(models)
+    state.role_models[role] = list(models)
+    state.role_models_custom = [r for r in state.role_models_custom if r != role]
+    try:
+        _validate_submitted_role_model(state, profile)
+    except WizardError:
+        if previous_count is None:
+            state.role_counts.pop(role, None)
+        else:
+            state.role_counts[role] = previous_count
+        if previous_models is None:
+            state.role_models.pop(role, None)
+        else:
+            state.role_models[role] = previous_models
+        raise
+    return t["echo_template"].format(value=f"{role}={','.join(models)}")
+
+
 def _validate_submitted_role_model(
     state: WizardState,
     profile: RoleProfile,
 ) -> None:
-    try:
-        scopes = _model_default_scopes(Path(state.project_root))
-    except (PrepareError, ValueError) as exc:
-        raise WizardError(str(exc)) from exc
-    context = load_assignment_context(
-        host_runtime=state.host_runtime,
-        terminal_backend=detect_terminal_backend(),
-    )
+    context, scopes = _load_context(state)
     role_models = {
         role: tuple(models) for role, models in state.role_models.items()
     }
@@ -602,133 +682,56 @@ def _validate_submitted_role_model(
         _validate_role_selection_feasibility(state, profile, context, scopes)
         return
     if not _role_selection_can_complete(
-        state,
-        profile,
-        context,
-        role_models,
-        scopes,
+        state, profile, context, role_models, scopes,
     ):
         raise WizardError("selected role model leaves no complete role assignment")
 
 
 def _submit_role_prompt(state: WizardState, prompt: Prompt, value: str) -> str:
-    if prompt.step.startswith("role-count:"):
-        role = prompt.step.split(":", 1)[1]
-        profile = _load_role_profile_for_state(state)
-        requirement = next(
-            (row for row in profile.roles if row.role == role),
-            None,
-        )
-        if (
-            requirement is None
-            or requirement.dynamic
-            or requirement.min_count == requirement.max_count
-            or requirement.min_count == 0
-        ):
-            raise WizardError(f"role {role!r} does not accept a count selection")
-        try:
-            count = int(value)
-        except ValueError as exc:
-            raise WizardError(f"role {role!r} count must be an integer") from exc
-        if count < requirement.min_count or count > requirement.max_count:
-            raise WizardError(
-                f"role {role!r} count must be in "
-                f"{requirement.min_count}..{requirement.max_count}: {count}"
-            )
-        state.role_counts[role] = count
-        state.role_models.pop(role, None)
-        return f"role-count: {role}={count}"
-    if prompt.step.startswith("role-add:"):
-        role = prompt.step.split(":", 1)[1]
-        profile = _load_role_profile_for_state(state)
-        requirement = next(
-            (row for row in profile.roles if row.role == role),
-            None,
-        )
-        if (
-            requirement is None
-            or requirement.dynamic
-            or requirement.min_count != 0
-            or requirement.max_count == 0
-        ):
-            raise WizardError(f"role {role!r} does not accept an optional add")
-        allowed = {option.value for option in prompt.options}
-        if value not in allowed:
-            raise WizardError(
-                f"role {role!r} add selection must be one of "
-                f"{sorted(allowed, key=int)}: {value}"
-            )
-        try:
-            count = int(value)
-        except ValueError as exc:
-            raise WizardError(f"role {role!r} count must be an integer") from exc
-        if count < 0 or count > requirement.max_count:
-            raise WizardError(
-                f"role {role!r} count must be in "
-                f"0..{requirement.max_count}: {count}"
-            )
-        state.role_counts[role] = count
-        state.role_models.pop(role, None)
-        return f"role-add: {role}={count}"
-    _, role, ordinal_raw = prompt.step.split(":", 2)
-    ordinal = int(ordinal_raw)
+    profile = _load_role_profile_for_state(state)
+    role = _step_role(prompt.step)
+    requirement = _requirement_for(profile, role)
+    if prompt.step.startswith((_MODELS_PREFIX, _CUSTOM_PREFIX)):
+        if _fixed_single(requirement):
+            raise WizardError(f"role {role!r} takes exactly one model")
+        return _submit_role_models(state, profile, requirement, prompt, value)
+    # 고정 단일 역할의 `role-model:<role>:1`.
+    if not _fixed_single(requirement):
+        raise WizardError(f"role {role!r} is chosen on its checkbox step")
     allowed = {option.value for option in prompt.options}
     if value not in allowed:
         raise WizardError(
             f"model {value!r} is not a compatible candidate for role {role!r}"
         )
-    selected = state.role_models.setdefault(role, [])
-    if ordinal != len(selected) + 1:
-        raise WizardError(
-            f"role {role!r} model selection is out of order at ordinal {ordinal}"
-        )
-    selected.append(value)
+    previous = state.role_models.get(role)
+    state.role_models[role] = [value]
     try:
-        profile = _load_role_profile_for_state(state)
         _validate_submitted_role_model(state, profile)
     except WizardError:
-        selected.pop()
+        if previous is None:
+            state.role_models.pop(role, None)
+        else:
+            state.role_models[role] = previous
         raise
-    return f"role-model: {role}#{ordinal}={value}"
+    return f"role-model: {role}#1={value}"
 
 
 def _reset_role_selection_from(state: WizardState, target_step: str) -> None:
+    """편집 대상 step 부터 되감는다 — 그 step 의 역할과 그 뒤 역할의 답을 비운다."""
     try:
         target_index = state.role_selection_order.index(target_step)
     except ValueError as exc:
         raise WizardError(f"unknown role selection step: {target_step!r}") from exc
-    kept_ids = state.role_selection_order[:target_index]
-    kept_counts = {
-        step_id.split(":", 1)[1]
-        for step_id in kept_ids
-        if step_id.startswith(("role-count:", "role-add:"))
+    removed_roles = {
+        _step_role(step_id) for step_id in state.role_selection_order[target_index:]
     }
-    kept_models: dict[str, int] = {}
-    for step_id in kept_ids:
-        if not step_id.startswith("role-model:"):
-            continue
-        _, role, _ = step_id.split(":", 2)
-        kept_models[role] = kept_models.get(role, 0) + 1
-    state.role_counts = {
-        role: count
-        for role, count in state.role_counts.items()
-        if role in kept_counts
-    }
-    state.role_models = {
-        role: models[:kept_models[role]]
-        for role, models in state.role_models.items()
-        if kept_models.get(role, 0) > 0
-    }
-    removed_ids = set(state.role_selection_order[target_index:])
-    state.role_selection_order = kept_ids
-    state.answered = [
-        step_id for step_id in state.answered if step_id not in removed_ids
-    ]
+    _drop_role_selection(state, removed_roles)
 
 
 def _clear_role_selection(state: WizardState) -> None:
     state.role_counts.clear()
     state.role_models.clear()
+    state.role_models_custom.clear()
     state.role_selection_order.clear()
     state.answered = [
         step_id