okstra 0.191.2 → 0.192.0

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

@@ -34,6 +34,8 @@ class WizardState:
     role_counts: dict[str, int] = field(default_factory=dict)
     role_models: dict[str, list[str]] = field(default_factory=dict)
     role_selection_order: list[str] = field(default_factory=list)
+    # 체크박스 화면에서 "직접 선택" 을 골라 전체 후보 화면을 기다리는 역할들.
+    role_models_custom: list[str] = field(default_factory=list)
 
     # bootstrap
     workspace_root: str = ""
@@ -212,32 +214,43 @@ class Prompt:
         막는다.
         """
         values = [option.value for option in self.options]
-        if PICK_TYPE_CUSTOM not in values:
-            return
-        after = values[values.index(PICK_TYPE_CUSTOM) + 1:]
-        offenders = [value for value in after if value != _ABORT_OPTION]
-        if offenders:
-            raise WizardError(
-                f"wizard step {self.step!r}: the free-input option "
-                f"({PICK_TYPE_CUSTOM!r}) must come after every real choice — "
-                f"only {_ABORT_OPTION!r} may follow it, but {offenders} do"
-            )
+        if PICK_TYPE_CUSTOM in values:
+            after = values[values.index(PICK_TYPE_CUSTOM) + 1:]
+            offenders = [value for value in after if value != _ABORT_OPTION]
+            if offenders:
+                raise WizardError(
+                    f"wizard step {self.step!r}: the free-input option "
+                    f"({PICK_TYPE_CUSTOM!r}) must come after every real choice — "
+                    f"only {_ABORT_OPTION!r} may follow it, but {offenders} do"
+                )
+        # 추천 불변식은 탈출구가 없는 목록에도 적용된다.
         self._check_recommendations()
 
     def _check_recommendations(self) -> None:
-        """추천은 목록 앞머리에 모여 있고, 탈출구는 추천이 아니다.
-
-        추천을 목록 중간에 흩어 놓으면 화면에서 어디까지가 이 run 의 판단인지
-        읽히지 않는다. 그리고 `직접 입력` / `중단` 은 앞의 선택지가 전부 맞지
-        않을 때의 탈출구이므로 추천 대상이 될 수 없다.
+        """단일 선택의 추천은 정확히 하나이고 1번이다. 탈출구는 추천이 아니다.
+
+        실측(2026-09-09, task 선택 화면): 남은 task 세 줄이 전부 `(추천)` 을
+        달고 나왔고, 리드는 산문에서 2번을 권했다. 추천이 여럿이면 라벨은
+        아무것도 고르지 않은 것이고, 추천이 1번이 아니면 사용자는 목록을
+        끝까지 읽어야 추천을 찾는다. 체크박스(`multi`)는 추천이 기본 선택
+        집합이라 여럿일 수 있되 앞머리에 모여 있다. 그리고 `직접 입력` /
+        `중단` 은 앞의 선택지가 전부 맞지 않을 때의 탈출구이므로 추천 대상이
+        될 수 없다.
         """
         flags = [option.recommended for option in self.options]
-        if any(flags) and any(flags[index] for index in range(len(flags))
-                              if index > 0 and not flags[index - 1]):
-            raise WizardError(
-                f"wizard step {self.step!r}: recommended options must be the "
-                "leading run of the list"
-            )
+        if any(flags):
+            if self.multi:
+                if any(flags[index] for index in range(1, len(flags))
+                       if not flags[index - 1]):
+                    raise WizardError(
+                        f"wizard step {self.step!r}: recommended options must "
+                        "be the leading run of the list"
+                    )
+            elif sum(flags) != 1 or not flags[0]:
+                raise WizardError(
+                    f"wizard step {self.step!r}: a single-select step carries "
+                    "exactly one recommendation and it is the first option"
+                )
         escapes = {PICK_TYPE_CUSTOM, _ABORT_OPTION}
         marked = [
             option.value for option in self.options
@@ -436,8 +449,6 @@ def _convert_v1_provider_selections(
             )
         if cross_requirement.min_count < cross_requirement.max_count:
             state.role_counts[cross_requirement.role] = selected_count
-            count_id = f"role-count:{cross_requirement.role}"
-            state.role_selection_order.append(count_id)
         if not providers:
             providers = [
                 model.provider_id
@@ -458,9 +469,9 @@ def _convert_v1_provider_selections(
             if model_ref is None:
                 break
             state.role_models.setdefault(cross_requirement.role, []).append(model_ref)
-            state.role_selection_order.append(
-                f"role-model:{cross_requirement.role}:{ordinal}"
-            )
+        if cross_requirement.role in state.role_models:
+            # 여러 인스턴스 역할의 답은 체크박스 한 장이다.
+            state.role_selection_order.append(f"role-models:{cross_requirement.role}")
 
     provider_rows = (
         (
@@ -572,7 +583,7 @@ def _validate_v2_state_fields(data: dict[str, Any]) -> None:
 
 
 def _is_role_selection_step(step_id: str) -> bool:
-    return step_id.startswith(("role-count:", "role-model:", "role-add:"))
+    return step_id.startswith(("role-model:", "role-models:", "role-models-custom:"))
 
 
 def _discard_implicit_leader_selection(state: WizardState) -> None:
@@ -661,6 +672,7 @@ _FIELD_DEFAULTS: dict[str, Any] = {
     "executor": "", "critic": "", "critic_pending_text": False,
     "execution_identity_version": 1,
     "role_counts": {}, "role_models": {}, "role_selection_order": [],
+    "role_models_custom": [],
     "reuse_previous": None,
     "use_defaults": None, "workers_override": "",
     "workers_custom_pending": False,

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

@@ -129,6 +129,28 @@ def _next_phase_cell(raw: Any) -> str:
     return f"{cell} ({pointer['status']})"
 
 
+def _recommended_task_entry(remaining: list[dict], latest_key: str) -> dict | None:
+    """남은 task 중 이 run 이 권하는 하나.
+
+    포인터가 `ready` 인 task 는 지금 바로 다음 phase 를 시작할 수 있는 task 다
+    — 그중 최신(카탈로그는 updatedAt 내림차순)을 권한다. `ready` 가 없으면
+    마지막으로 만진 task(`latest-task.json`)를, 그것도 목록에 없으면 최신
+    task 를 권한다. 실측(2026-09-09): 세 줄 전부가 `(추천)` 이었고 리드는
+    산문에서 2번을 권했다 — 추천이 여럿이면 라벨은 아무것도 고르지 않은
+    것이다.
+    """
+    if not remaining:
+        return None
+    for entry in remaining:
+        pointer = next_phase.promote(entry.get("nextRecommendedPhase"))
+        if pointer["status"] == next_phase.STATUS_READY:
+            return entry
+    for entry in remaining:
+        if latest_key and entry.get("taskKey") == latest_key:
+            return entry
+    return remaining[0]
+
+
 def _build_task_pick(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "task_pick")
     project_root = Path(state.project_root)
@@ -137,8 +159,14 @@ def _build_task_pick(state: WizardState) -> Prompt:
     latest_key = latest.get("taskKey") or ""
     latest_suffix = t["options"].get("_LATEST_SUFFIX", "")
     remaining = [e for e in tasks if (e.get("workStatus") or "") != "done"]
+    # 추천은 하나이고 1번이다. 나머지는 최신순 그대로.
+    recommended = _recommended_task_entry(remaining, latest_key)
+    ordered = (
+        [recommended, *(e for e in remaining if e is not recommended)]
+        if recommended is not None else remaining
+    )
     options: list[Option] = []
-    for entry in remaining[:_recommendation_budget(state)]:
+    for entry in ordered[:_recommendation_budget(state)]:
         key = entry.get("taskKey") or ""
         ttype = entry.get("taskType") or ""
         # catalog entries are flat (render_task_catalog_discovery) — there is
@@ -147,7 +175,8 @@ def _build_task_pick(state: WizardState) -> Prompt:
         nxt = _next_phase_cell(entry.get("nextRecommendedPhase"))
         suffix = latest_suffix if key == latest_key else ""
         label = f"{key}  ·  {phase}  ·  next: {nxt}{_contract_outcome_suffix(entry)}{suffix}"
-        options.append(_opt(value=key, label=label, recommended=True))
+        options.append(_opt(value=key, label=label,
+                            recommended=entry is recommended))
     for value, label in _static_options(t):
         options.append(_opt(value=value, label=label))
     return Prompt(step=S_TASK_PICK, kind="pick",
@@ -335,9 +364,11 @@ def _build_task_group(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "task_group_no_suggestion")
     recent_prefix = t.get("recent_label_prefix", "")
     options: list[Option] = []
-    for tg in recent:
+    # 추천은 하나뿐이다: 가장 최근에 task·brief 활동이 있던 group — 새 task 는
+    # 진행 중인 작업 흐름에 속할 가능성이 가장 크다. 나머지는 후보다.
+    for index, tg in enumerate(recent):
         options.append(_opt(f"{_RECENT_PREFIX}{tg}", f"{recent_prefix}{tg}",
-                            recommended=True))
+                            recommended=index == 0))
     options.append(_opt(PICK_TYPE_CUSTOM, t["options"][PICK_TYPE_CUSTOM]))
     return Prompt(
         step=S_TASK_GROUP, kind="pick",
@@ -410,9 +441,11 @@ def _build_task_id(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "task_id_no_suggestion")
     recent_prefix = t.get("recent_label_prefix", "")
     options: list[Option] = []
+    # 새 task 의 id 로 같은 group 의 기존 id 를 권할 근거는 없다 — 후보로만
+    # 싣고 추천은 비운다. 추천이 있는 경우는 brief frontmatter 의 제안뿐이고,
+    # 그것은 위의 `task_id_with_suggestion` 분기다.
     for tid in recent:
-        options.append(_opt(f"{_RECENT_PREFIX}{tid}", f"{recent_prefix}{tid}",
-                            recommended=True))
+        options.append(_opt(f"{_RECENT_PREFIX}{tid}", f"{recent_prefix}{tid}"))
     options.append(_opt(PICK_TYPE_CUSTOM, t["options"][PICK_TYPE_CUSTOM]))
     return Prompt(
         step=S_TASK_ID, kind="pick",
@@ -713,12 +746,21 @@ def _build_brief_path_pick(state: WizardState) -> Prompt:
     def add(value: str, label: str) -> None:
         if len(options) >= budget:
             return
-        options.append(_opt(value, label, recommended=True))
+        # 첫 후보만 추천이다: 이 task 의 기존 brief → (있으면) 표준 경로의
+        # brief → 그룹 시작 순서상 첫 미착수 brief. 각각이 그 자리에서 가장
+        # 타당한 입력이고, 그 뒤 줄들은 대안이다.
+        options.append(_opt(value, label, recommended=not options))
 
     if existing:
         add("__existing__",
             t["options"]["__existing__"].format(existing=existing))
-    if standard and standard != existing:
+    # 표준 경로는 파일이 실제로 있을 때만 후보다. 없는 파일을 고르면
+    # `_require_file` 이 거절하므로, 그 줄은 선택지가 아니라 함정이고 추천은
+    # 더더욱 아니다.
+    if (
+        standard and standard != existing
+        and (Path(state.project_root) / standard).is_file()
+    ):
         add("__standard__",
             t["options"]["__standard__"].format(standard=standard))
     brief_label = t["labels"].get("brief_candidate", "{path}")

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

@@ -293,6 +293,7 @@ def _submit_reuse_previous(state: WizardState, value: str) -> Optional[str]:
         conversion_payload.setdefault("kimiModel", state.kimi_model)
         state.role_counts.clear()
         state.role_models.clear()
+        state.role_models_custom.clear()
         state.role_selection_order.clear()
         _convert_v1_provider_selections(state, conversion_payload)
     directive = inputs.get("directive")

package/runtime/skills/okstra-run/SKILL.md

@@ -61,7 +61,7 @@ The final `confirm` step is a normal `pick` step with three options — `Proceed
 
 Never invent additional questions. **Never drop, hide, merge, reorder, or truncate** a `pick` / `pick_group` option — relay every `options[]` entry, including entries that carry a `(default)` / `(recommended)` suffix. Do not collapse a multi-option pick into a "recommended + Enter directly / Other" shortlist. The wizard's arrays are the complete authoritative choice sets, regardless of the current host UI's usual option limit. The run-prompt recommendation rule (1–2 recommendations + Enter directly) shapes the **option set** only for prompts this skill authors itself, never for wizard-provided options — you may not add, drop, or reorder a wizard option to produce a shortlist. It does not excuse you from recommending: before relaying a wizard step whose answer turns on something readable (the carried report, the sidecar the user already wrote, the prior Stage Map), read it, put what you found in the question body, and name which of the wizard's own options you recommend and why. Relaying a step with no context and no recommendation hands the whole question back to the user — see the lifecycle core contract "Asking the user (BLOCKING)".
 
-**One recommendation, shown in one place.** An option carrying `recommended: true` is what this run computed — append ` (추천)` to that option's label when you render it, and to no other. Your prose recommendation names one of the flagged options. If you believe a different option is right, do not quietly recommend it in prose while the flagged one still reads as recommended on screen: say you disagree, name both, and let the user pick. When no option carries the flag, the run computed nothing for this step — recommend one from what you read and mark that one, and do not present the first option as a default just because it is first. **Enforced:** `scripts/okstra_ctl/wizard/state.py` `Prompt.__post_init__` refuses a step whose free-input option is not last, whose recommended options are not the leading run of the list, or that marks the free-input / abort escape as a recommendation.
+**One recommendation, shown in one place, and it is option 1.** The option carrying `recommended: true` is what this run computed, and the wizard already placed it first — append ` (추천)` to that option's label when you render it, and to no other. A checkbox step (`multi: true`) may flag several leading options: they are the recommended set, rendered the same way. Your prose recommendation names one of the flagged options. If you believe a different option is right, do not quietly recommend it in prose while the flagged one still reads as recommended on screen: say you disagree, name both, and let the user pick. When no option carries the flag, the run computed nothing for this step — recommend one from what you read and mark that one, and do not present the first option as a default just because it is first. **Enforced:** `scripts/okstra_ctl/wizard/state.py` `Prompt.__post_init__` refuses a step whose free-input option is not last, whose single-select recommendation is not exactly one option placed first (a checkbox step's recommended options must be its leading run), or that marks the free-input / abort escape as a recommendation.
 
 ## Step 1: Preflight
 
@@ -198,7 +198,7 @@ That is the entire interactive flow. The wizard handles:
 - base-ref pick + git rev-parse validation (skipped when reusing an active worktree),
 - `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = the earliest incomplete stage whose dependencies are satisfied, or a specific stage number). Implementer slots use role-count / role-model like every other role (`executor` is only a compatibility alias for `implementer`). When an approved plan is selected and a `## PLAN DECISION` sidecar carrying `Status: approved`, exported from the report — matching the plan on source-report·seq — is detected in that run's sibling `user-responses/`, the approve-confirm step expands to 3 options (`yes_apply` recommended: approve + apply the option as exported / `yes` approve only / `no` abort) — `yes_apply` validates the option against the plan's `optionCandidates` before applying it via the existing approval·option path,
 - `release-handoff`-only sub-flow: after the approved plan auto-resolves, a `handoff_stage_pick` multi-select — choose an eligible stage bundle (stage-group) or the whole task (when an accepted whole-task verification report exists); the result goes out as render-args' `stages` key (csv, empty when whole-task),
-- launch selection after identity/worktree steps: role-count per static role (`min..max`, omit uses **recommended**, skip when `min == max`) → role-model `provider/model` per slot → min=0 roles only via role-add (default skip). current-session lead is this session and is listed on the confirmation summary, not as a wizard step. The wizard does not fork on defaults-vs-customize, does not show a provider roster multi-pick, and does not offer a separate implementer-provider pick. Dynamic verifiers are not chosen at launch. `--workers` is compatibility-only, not a launch picker. Repeated `--role-count` / `--role-model` tokens on `renderArgv` are intentional,
+- launch selection after identity/worktree steps: one screen per static role, in profile order. A role that can run several instances (`max > 1`) is a checkbox step `role-models:<role>` (`multi: true`) — the number of models checked is the number of instances, there is no separate count question; the label states the profile range and recommended count, the recommended set is flagged, and the last row (`직접 선택`) opens `role-models-custom:<role>` with every executable candidate. An optional role (`min = 0`, e.g. critic) carries a `추가 안 함` row. A fixed single role (`min = max = 1`, e.g. report-writer) is a single pick `role-model:<role>:1`. current-session lead is this session and is listed on the confirmation summary, not as a wizard step. The wizard does not fork on defaults-vs-customize, does not show a provider roster multi-pick, and does not offer a separate implementer-provider pick. Dynamic verifiers are not chosen at launch. `--workers` is compatibility-only, not a launch picker. Repeated `--role-count` / `--role-model` tokens on `renderArgv` are intentional,
 - **resume-clarification (in-session equivalent)** — there is no separate mode or flag matching the shell's `okstra.sh --resume-clarification`; two steps of the standard flow carry out its substance. (1) `reuse_previous` (yes/no to reuse the previous run's settings — in `requirements-discovery` / `error-analysis` / `implementation-planning`, only when prior run-inputs exist): YES prefills role-count·role-model·directive·related-tasks at once. (2) `clarification_pick`: if the **task-type's own** previous `final-report` exists it is auto-recommended as the carry-in input (falling back to the newest by mtime across all phases when absent), and the same run's `user-responses/` sidecar (answers the user filled in) is attached alongside. The chosen path is passed to prepare as `--clarification-response` — the user makes the sidecar via the report's `Export user response`, places it in `runs/<task-type>/user-responses/`, and re-runs the same phase,
 - **re-verification scope (`reverify_scope_pick`, `implementation-planning` clarification re-runs only)** — asked right before `confirm` when the re-run is narrowable **or** an answered `C-NNN` traces to no stage. When every answered id traces to a stage: 3 options — `auto` (recommended — leave it to the lead's `okstra incremental-scope` decision) / `full` (re-verify every stage) / Enter directly (a stage-number CSV, validated against the prior report's Stage Map). When an id is unlinked, `auto` is omitted and the user names stages or picks `full`; that unlinked id does not freeze the run at full. The answer goes out as `--reverify-scope` and reaches the lead prompt as the `REVERIFY_SCOPE_MODE` / `REVERIFY_SCOPE_STAGES` tokens; it shapes that CLI's inputs rather than replacing the decision. The confirmation block's `reverify-scope` line names unlinked ids as needing stage numbers, not as a forced full re-run,
 - `release-handoff` PR template override + persist scope,

package/runtime/validators/validate-run.py

@@ -8108,8 +8108,8 @@ def _validate_translation_sidecar(
         failures.append(
             f"final-report has reportLanguage {lang!r} but no translation "
             f"sidecar at {sidecar.name}. The human HTML rendered from the "
-            "English source instead; re-run `report-finalize --only "
-            "render-views` once the translation lands."
+            "English source instead; re-run `report-finalize --only translate "
+            "--only render-views` to dispatch the translator and overlay it."
         )