okstra 0.49.0 → 0.51.0

package/runtime/python/okstra_ctl/sequence.py

@@ -5,10 +5,9 @@ import re as _re
 from pathlib import Path
 from typing import Optional
 
-from okstra_project.dirs import tasks_root
-
 from .ids import slugify_task_segment
 from .jsonl import read_jsonl
+from .paths import task_runs_dir
 
 
 def predict_next_run_seq(project_root: Path, task_group: str, task_id: str,
@@ -26,9 +25,7 @@ def predict_next_run_seq(project_root: Path, task_group: str, task_id: str,
     이 셋의 max + 1 이 안전한 다음 seq.
     """
     task_type_segment = slugify_task_segment(task_type)
-    base = (tasks_root(project_root)
-            / slugify_task_segment(task_group) / slugify_task_segment(task_id)
-            / "runs" / task_type_segment)
+    base = task_runs_dir(project_root, task_group, task_id) / task_type_segment
     max_seq = 0
     rep_pat = _re.compile(rf"^final-report-{_re.escape(task_type_segment)}-(\d+)\.md$")
     man_pat = _re.compile(rf"^run-manifest-{_re.escape(task_type_segment)}-(\d+)\.json$")

package/runtime/python/okstra_ctl/team_reconcile.py

@@ -0,0 +1,131 @@
+"""Stale team-member reconciliation for run-end teardown.
+
+A Claude Code team member clears its own ``isActive`` flag in
+``~/.claude/teams/<team>/config.json`` when its ``Agent()`` dispatch returns, so
+by Phase 7 every worker is normally already inactive and ``TeamDelete()``
+succeeds immediately. The one failure mode is a member whose tmux pane died
+WITHOUT clearing the flag (killed mid-turn): it stays ``isActive: true`` forever,
+and ``TeamDelete`` then refuses the whole team with an "active members" error
+that re-sending ``shutdown_request`` cannot clear — the addressee is already
+gone.
+
+This module reconciles exactly that case: a member with ``isActive`` truthy
+whose recorded tmux pane is no longer live is flipped to inactive. It NEVER
+touches a member whose pane is still live, the lead, or a member with no
+recorded pane — those are left for graceful shutdown.
+
+Note: the active-member flag is the harness's source of truth, but whether
+``TeamDelete`` re-reads ``config.json`` at delete time (vs. caching the roster in
+the owning session) is a harness behaviour that can only be confirmed inside a
+real run — see _common-contract.md "Run-end team teardown".
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+def live_pane_ids() -> tuple[bool, set[str]]:
+    """Return ``(tmux_available, live_pane_ids)``.
+
+    ``tmux_available`` is False when no tmux server is reachable; the caller must
+    then skip reconciliation rather than treat every pane as dead.
+    """
+    try:
+        out = subprocess.run(
+            ["tmux", "list-panes", "-a", "-F", "#{pane_id}"],
+            capture_output=True, text=True,
+        )
+    except FileNotFoundError:
+        return False, set()
+    if out.returncode != 0:
+        return False, set()
+    return True, {ln.strip() for ln in out.stdout.splitlines() if ln.strip()}
+
+
+def reconcile_members(config: dict, live_panes: set[str]) -> list[str]:
+    """Flip dead-pane stale-active members to inactive in-place.
+
+    Returns the names of members that were flipped. A member qualifies only when
+    it is not the lead, ``isActive`` is truthy, it has a recorded ``tmuxPaneId``,
+    and that pane is not among ``live_panes``.
+    """
+    lead = config.get("leadAgentId")
+    flipped: list[str] = []
+    for member in config.get("members", []):
+        if member.get("agentId") == lead:
+            continue
+        pane = (member.get("tmuxPaneId") or "").strip()
+        if not member.get("isActive") or not pane:
+            continue
+        if pane not in live_panes:
+            member["isActive"] = False
+            flipped.append(member.get("name", member.get("agentId", "?")))
+    return flipped
+
+
+def _config_path(team_arg: str) -> Path:
+    """Resolve a team name, a team dir, or a config.json path to the config file."""
+    p = Path(team_arg)
+    if p.name == "config.json":
+        return p
+    if p.is_dir():
+        return p / "config.json"
+    return Path.home() / ".claude" / "teams" / team_arg / "config.json"
+
+
+def _atomic_write(path: Path, text: str) -> None:
+    """Replace ``path`` atomically — config.json is load-bearing for the next
+    TeamDelete, so a partial write on crash must never be observable."""
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=".reconcile-")
+    try:
+        with os.fdopen(fd, "w") as handle:
+            handle.write(text)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def main(argv: list[str]) -> int:
+    dry_run = False
+    rest: list[str] = []
+    for arg in argv:
+        if arg in ("--list", "--dry-run"):
+            dry_run = True
+        else:
+            rest.append(arg)
+    if len(rest) != 1:
+        print("usage: okstra-team-reconcile.sh [--list] <team-name|team-dir|config.json>",
+              file=sys.stderr)
+        return 2
+
+    cfg_path = _config_path(rest[0])
+    if not cfg_path.is_file():
+        print(f"team-reconcile: no team config at {cfg_path}", file=sys.stderr)
+        return 1
+
+    config = json.loads(cfg_path.read_text())
+    available, live = live_pane_ids()
+    if not available:
+        print("team-reconcile: tmux unavailable — skipped (no flip)")
+        return 0
+
+    flipped = reconcile_members(config, live)
+    if not flipped:
+        print("team-reconcile: no stale-active members")
+        return 0
+    if dry_run:
+        print("team-reconcile (dry-run): would deactivate " + ", ".join(flipped))
+        return 0
+
+    _atomic_write(cfg_path, json.dumps(config, indent=2, ensure_ascii=False) + "\n")
+    print(f"team-reconcile: deactivated {len(flipped)} stale member(s): " + ", ".join(flipped))
+    return 0

package/runtime/python/okstra_ctl/wizard.py

@@ -46,8 +46,13 @@ from okstra_ctl.workers import (
     validate_workers_against_profile,
 )
 from okstra_ctl import worktree_registry
-from okstra_ctl.worktree import preview_worktree_decision
-from okstra_project.dirs import project_json_path, tasks_root
+from okstra_ctl.worktree import (
+    is_git_work_tree,
+    main_worktree_path,
+    preview_worktree_decision,
+)
+from okstra_ctl.paths import task_runs_dir
+from okstra_project.dirs import project_json_path
 from okstra_project.state import (
     StateError,
     list_project_tasks,
@@ -205,6 +210,28 @@ S_CONFIRM = "confirm"
 S_EDIT_TARGET = "edit_target"
 S_DONE = "done"
 
+# ---- 멀티탭 배치 프롬프트 그룹 (방출 계층 전용) ----
+# 그룹 id 는 S_* 가 아니므로 prompts JSON SOT / step-id 동기화 검사 대상이 아니다.
+GROUP_MODELS = "models"
+GROUP_OPTIONS = "options"
+GROUP_MAX_TABS = 4  # AskUserQuestion 의 질문(탭) 수 한도
+
+# 멤버는 모두 서로 의존이 없는 단일선택 픽 step 이어야 한다.
+# *_TEXT 후속 / workers_override / pr_template_scope 는 의존성 때문에 개별 유지.
+PROMPT_GROUPS: dict[str, tuple[str, ...]] = {
+    GROUP_MODELS: (S_LEAD_MODEL, S_EXECUTOR_MODEL, S_CLAUDE_MODEL,
+                   S_CODEX_MODEL, S_GEMINI_MODEL, S_REPORT_WRITER_MODEL),
+    GROUP_OPTIONS: (S_DIRECTIVE_PICK, S_RELATED_TASKS_PICK,
+                    S_CLARIFICATION_PICK, S_PR_TEMPLATE_PICK),
+}
+GROUP_LABELS: dict[str, str] = {
+    GROUP_MODELS: "모델 선택 (탭별로 선택)",
+    GROUP_OPTIONS: "추가 옵션 (탭별로 선택)",
+}
+_STEP_TO_GROUP: dict[str, str] = {
+    sid: gid for gid, ids in PROMPT_GROUPS.items() for sid in ids
+}
+
 
 # ---- Data types ----------------------------------------------------------
 
@@ -305,9 +332,11 @@ class Prompt:
     help: str = ""
     echo_template: str = ""  # e.g. "task-group: {value}"
     multi: bool = False  # only meaningful when kind == "pick"
+    # only meaningful when kind == "pick_group": one entry per AskUserQuestion tab
+    questions: list["Prompt"] = field(default_factory=list)
 
     def to_json(self) -> dict[str, Any]:
-        return {
+        out = {
             "step": self.step,
             "kind": self.kind,
             "label": self.label,
@@ -316,6 +345,14 @@ class Prompt:
             "echoTemplate": self.echo_template,
             "multi": self.multi,
         }
+        if self.kind == "pick_group":
+            out["questions"] = [
+                {"step": q.step, "label": q.label,
+                 "options": [asdict(o) for o in q.options],
+                 "multi": q.multi}
+                for q in self.questions
+            ]
+        return out
 
 
 class WizardError(Exception):
@@ -373,12 +410,12 @@ def _validate_approved_plan(path_str: str, project_root: Path) -> Path:
             "  edit the report and change the line to `approved: true`, or re-run "
             "okstra with `--approve` to flip it from the CLI."
         )
-    # frontmatter approved == true 라도 §5 의 Blocks=approval 행이 미해결이면
+    # frontmatter approved == true 라도 §1 의 Blocks=approval 행이 미해결이면
     # 승인이 무효 — prepare_task_bundle 의 _validate_approved_plan 과 동일 규약.
     blockers = unresolved_approval_blockers(body)
     if blockers:
         lines = [
-            f"approved plan frontmatter has `approved: true` but §5 has {len(blockers)} "
+            f"approved plan frontmatter has `approved: true` but §1 has {len(blockers)} "
             f"unresolved `Blocks=approval` row(s); resolve them or mark them obsolete first:",
         ]
         for b in blockers:
@@ -389,15 +426,12 @@ def _validate_approved_plan(path_str: str, project_root: Path) -> Path:
 
 
 def _git_main_worktree(project_root: Path) -> Path:
-    try:
-        common = subprocess.check_output(
-            ["git", "-C", str(project_root), "rev-parse",
-             "--path-format=absolute", "--git-common-dir"],
-            stderr=subprocess.DEVNULL,
-        ).decode().strip()
-    except (subprocess.CalledProcessError, FileNotFoundError) as exc:
-        raise WizardError(f"git unavailable in {project_root}: {exc}")
-    return Path(common).parent
+    # main worktree 해소는 worktree 모듈의 public seam(main_worktree_path)에
+    # 위임한다. base-ref 검증은 git 이 없으면 의미가 없으므로, 자체 메시지로
+    # 먼저 fail-fast 한다 (과거 자체 `--git-common-dir` 구현을 대체).
+    if not is_git_work_tree(project_root):
+        raise WizardError(f"git unavailable or not a work tree in {project_root}")
+    return main_worktree_path(project_root)
 
 
 def _validate_base_ref(ref: str, project_root: Path) -> str:
@@ -1075,10 +1109,8 @@ def _list_implementation_planning_reports(
     # Run seq lives in the filename, not a per-run subdirectory: every
     # implementation-planning run writes into the same flat `reports/`
     # dir (see paths.py — `run_reports = runs/<task-type>/reports`).
-    reports_dir = (tasks_root(state.project_root)
-                   / slugify_task_segment(state.task_group)
-                   / slugify_task_segment(state.task_id)
-                   / "runs" / "implementation-planning" / "reports")
+    reports_dir = (task_runs_dir(state.project_root, state.task_group, state.task_id)
+                   / "implementation-planning" / "reports")
     if not reports_dir.is_dir():
         return []
     pat = re.compile(r"^final-report-implementation-planning-(\d+)\.md$")
@@ -1224,9 +1256,7 @@ def _suggest_latest_final_report(state: WizardState) -> str:
     """
     if not state.task_group or not state.task_id or not state.project_root:
         return ""
-    runs_base = (tasks_root(state.project_root)
-                 / slugify_task_segment(state.task_group)
-                 / slugify_task_segment(state.task_id) / "runs")
+    runs_base = task_runs_dir(state.project_root, state.task_group, state.task_id)
     if not runs_base.is_dir():
         return ""
     candidates = [
@@ -1253,9 +1283,7 @@ def _suggest_last_directive(state: WizardState) -> str:
     """같은 task 의 가장 최근 run-inputs-*.json 에서 directive 값을 자동 추출."""
     if not state.task_group or not state.task_id or not state.project_root:
         return ""
-    runs_base = (tasks_root(state.project_root)
-                 / slugify_task_segment(state.task_group)
-                 / slugify_task_segment(state.task_id) / "runs")
+    runs_base = task_runs_dir(state.project_root, state.task_group, state.task_id)
     if not runs_base.is_dir():
         return ""
     candidates: list[tuple[float, Path]] = []
@@ -1279,43 +1307,96 @@ def _suggest_last_directive(state: WizardState) -> str:
     return val if isinstance(val, str) else ""
 
 
-def _build_directive_pick(state: WizardState) -> Prompt:
-    last = _suggest_last_directive(state)
-    t = _p(state.workspace_root, "directive_pick")
-    options: list[Option] = []
-    options.append(_opt(PICK_SKIP, t["options"][PICK_SKIP]))
-    if last:
-        snippet = last[:60] + ("…" if len(last) > 60 else "")
-        label_template = t["labels"]["reuse_last"]
-        options.append(_opt(_REUSE_LAST_TOKEN, label_template.format(snippet=snippet)))
-        state.last_directive_cached = last
+# ---------------------------------------------------------------------------
+# "optional cached pick" seam.
+#
+# directive / related-tasks / clarification / pr-template 단계는 모두 동일한
+# 3-옵션 picker 구조를 갖는다: [건너뛰기 / 추천값(이전 directive·siblings·최근
+# 리포트·프로젝트 기본) / 직접 입력]. 추천값은 디스크에서 suggest 하고, 선택 시
+# state 의 cache 필드에 담아 submit 에서 꺼낸다. 과거에는 이 구조가 네 곳에
+# 기계적으로 복제돼 한 곳을 고치면 나머지가 drift 했다. 변이점만 담은 선언적
+# spec + 제네릭 build/submit 으로 단일 seam 화한다.
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class _OptionalCachedPickSpec:
+    step: str
+    prompt_key: str          # _p() 의 step_id
+    recommend_token: str     # 추천 옵션의 sentinel value
+    label_key: str           # t["labels"] 의 추천 라벨 키
+    echo_suffix_key: str     # t["echo_suffixes"] 의 추천 echo 키
+    suggest: Callable[[WizardState], str]
+    snippet_style: str       # "prefix" (앞 60자+…) | "suffix" (…+뒤 60자)
+    cache_attr: str          # 추천값을 담아둘 state 속성
+    target_attr: str         # 확정값을 쓸 state 속성
+    pending_attr: str        # 직접 입력 대기 플래그 state 속성
+    extra_clear_attrs: tuple[str, ...] = ()  # skip 시 추가로 비울 속성
+
+
+def _pick_snippet(value: str, style: str) -> str:
+    if len(value) <= 60:
+        return value
+    return value[:60] + "…" if style == "prefix" else "…" + value[-60:]
+
+
+def _build_optional_cached_pick(state: WizardState, spec: _OptionalCachedPickSpec) -> Prompt:
+    suggestion = spec.suggest(state)
+    t = _p(state.workspace_root, spec.prompt_key)
+    options: list[Option] = [_opt(PICK_SKIP, t["options"][PICK_SKIP])]
+    if suggestion:
+        snippet = _pick_snippet(suggestion, spec.snippet_style)
+        options.append(_opt(spec.recommend_token, t["labels"][spec.label_key].format(snippet=snippet)))
+        setattr(state, spec.cache_attr, suggestion)
     options.append(_opt(PICK_TYPE_CUSTOM, t["options"][PICK_TYPE_CUSTOM]))
     return Prompt(
-        step=S_DIRECTIVE_PICK, kind="pick",
+        step=spec.step, kind="pick",
         label=t["label"], options=options,
         echo_template=t["echo_template"],
     )
 
 
-def _submit_directive_pick(state: WizardState, value: str) -> Optional[str]:
-    t = _p(state.workspace_root, "directive_pick")
+def _submit_optional_cached_pick(
+    state: WizardState, value: str, spec: _OptionalCachedPickSpec
+) -> Optional[str]:
+    t = _p(state.workspace_root, spec.prompt_key)
     if value == PICK_SKIP:
-        state.directive = ""
-        state.directive_pending_text = False
+        setattr(state, spec.target_attr, "")
+        for attr in spec.extra_clear_attrs:
+            setattr(state, attr, "")
+        setattr(state, spec.pending_attr, False)
         return t["echo_suffixes"]["skip"]
-    if value == _REUSE_LAST_TOKEN:
-        state.directive = state.last_directive_cached
-        state.directive_pending_text = False
-        return t["echo_suffixes"]["reuse"].format(value=state.directive)
+    if value == spec.recommend_token:
+        cached = getattr(state, spec.cache_attr)
+        setattr(state, spec.target_attr, cached)
+        setattr(state, spec.pending_attr, False)
+        return t["echo_suffixes"][spec.echo_suffix_key].format(value=cached)
     if value == PICK_TYPE_CUSTOM:
-        state.directive_pending_text = True
+        setattr(state, spec.pending_attr, True)
         return None
     raise WizardError(
-        f"unexpected directive value: {value!r} "
-        f"(expected {PICK_SKIP!r}, {_REUSE_LAST_TOKEN!r}, or {PICK_TYPE_CUSTOM!r})"
+        f"unexpected {spec.prompt_key} value: {value!r} "
+        f"(expected {PICK_SKIP!r}, {spec.recommend_token!r}, or {PICK_TYPE_CUSTOM!r})"
     )
 
 
+_DIRECTIVE_PICK_SPEC = _OptionalCachedPickSpec(
+    step=S_DIRECTIVE_PICK, prompt_key="directive_pick",
+    recommend_token=_REUSE_LAST_TOKEN, label_key="reuse_last", echo_suffix_key="reuse",
+    suggest=_suggest_last_directive, snippet_style="prefix",
+    cache_attr="last_directive_cached", target_attr="directive",
+    pending_attr="directive_pending_text",
+)
+
+
+def _build_directive_pick(state: WizardState) -> Prompt:
+    return _build_optional_cached_pick(state, _DIRECTIVE_PICK_SPEC)
+
+
+def _submit_directive_pick(state: WizardState, value: str) -> Optional[str]:
+    return _submit_optional_cached_pick(state, value, _DIRECTIVE_PICK_SPEC)
+
+
 def _suggest_sibling_task_ids(state: WizardState) -> str:
     """같은 task-group 의 다른 task-id 를 CSV 로 반환 (현재 task 제외, 빈 결과면 '')."""
     if not state.project_root or not state.task_group:
@@ -1337,74 +1418,39 @@ def _suggest_sibling_task_ids(state: WizardState) -> str:
     return ",".join(siblings)
 
 
+_RELATED_TASKS_PICK_SPEC = _OptionalCachedPickSpec(
+    step=S_RELATED_TASKS_PICK, prompt_key="related_tasks_pick",
+    recommend_token=_SIBLINGS_TOKEN, label_key="siblings", echo_suffix_key="siblings",
+    suggest=_suggest_sibling_task_ids, snippet_style="prefix",
+    cache_attr="last_siblings_cached", target_attr="related_tasks_raw",
+    pending_attr="related_tasks_pending_text",
+)
+
+
 def _build_related_tasks_pick(state: WizardState) -> Prompt:
-    siblings = _suggest_sibling_task_ids(state)
-    t = _p(state.workspace_root, "related_tasks_pick")
-    options: list[Option] = []
-    options.append(_opt(PICK_SKIP, t["options"][PICK_SKIP]))
-    if siblings:
-        snippet = siblings if len(siblings) <= 60 else siblings[:60] + "…"
-        label_template = t["labels"]["siblings"]
-        options.append(_opt(_SIBLINGS_TOKEN, label_template.format(snippet=snippet)))
-        state.last_siblings_cached = siblings
-    options.append(_opt(PICK_TYPE_CUSTOM, t["options"][PICK_TYPE_CUSTOM]))
-    return Prompt(step=S_RELATED_TASKS_PICK, kind="pick",
-                  label=t["label"], options=options,
-                  echo_template=t["echo_template"])
+    return _build_optional_cached_pick(state, _RELATED_TASKS_PICK_SPEC)
 
 
 def _submit_related_tasks_pick(state: WizardState, value: str) -> Optional[str]:
-    t = _p(state.workspace_root, "related_tasks_pick")
-    if value == PICK_SKIP:
-        state.related_tasks_raw = ""
-        state.related_tasks_pending_text = False
-        return t["echo_suffixes"]["skip"]
-    if value == _SIBLINGS_TOKEN:
-        state.related_tasks_raw = state.last_siblings_cached
-        state.related_tasks_pending_text = False
-        return t["echo_suffixes"]["siblings"].format(value=state.related_tasks_raw)
-    if value == PICK_TYPE_CUSTOM:
-        state.related_tasks_pending_text = True
-        return None
-    raise WizardError(
-        f"unexpected related-tasks value: {value!r} "
-        f"(expected {PICK_SKIP!r}, {_SIBLINGS_TOKEN!r}, or {PICK_TYPE_CUSTOM!r})"
-    )
+    return _submit_optional_cached_pick(state, value, _RELATED_TASKS_PICK_SPEC)
+
+
+_CLARIFICATION_PICK_SPEC = _OptionalCachedPickSpec(
+    step=S_CLARIFICATION_PICK, prompt_key="clarification_pick",
+    recommend_token=_LATEST_REPORT_TOKEN, label_key="latest_report",
+    echo_suffix_key="latest_report",
+    suggest=_suggest_latest_final_report, snippet_style="suffix",
+    cache_attr="last_final_report_cached", target_attr="clarification_response_path",
+    pending_attr="clarification_pending_text",
+)
 
 
 def _build_clarification_pick(state: WizardState) -> Prompt:
-    latest = _suggest_latest_final_report(state)
-    t = _p(state.workspace_root, "clarification_pick")
-    options: list[Option] = []
-    options.append(_opt(PICK_SKIP, t["options"][PICK_SKIP]))
-    if latest:
-        snippet = latest if len(latest) <= 60 else "…" + latest[-60:]
-        label_template = t["labels"]["latest_report"]
-        options.append(_opt(_LATEST_REPORT_TOKEN, label_template.format(snippet=snippet)))
-        state.last_final_report_cached = latest
-    options.append(_opt(PICK_TYPE_CUSTOM, t["options"][PICK_TYPE_CUSTOM]))
-    return Prompt(step=S_CLARIFICATION_PICK, kind="pick",
-                  label=t["label"], options=options,
-                  echo_template=t["echo_template"])
+    return _build_optional_cached_pick(state, _CLARIFICATION_PICK_SPEC)
 
 
 def _submit_clarification_pick(state: WizardState, value: str) -> Optional[str]:
-    t = _p(state.workspace_root, "clarification_pick")
-    if value == PICK_SKIP:
-        state.clarification_response_path = ""
-        state.clarification_pending_text = False
-        return t["echo_suffixes"]["skip"]
-    if value == _LATEST_REPORT_TOKEN:
-        state.clarification_response_path = state.last_final_report_cached
-        state.clarification_pending_text = False
-        return t["echo_suffixes"]["latest_report"].format(value=state.clarification_response_path)
-    if value == PICK_TYPE_CUSTOM:
-        state.clarification_pending_text = True
-        return None
-    raise WizardError(
-        f"unexpected clarification value: {value!r} "
-        f"(expected {PICK_SKIP!r}, {_LATEST_REPORT_TOKEN!r}, or {PICK_TYPE_CUSTOM!r})"
-    )
+    return _submit_optional_cached_pick(state, value, _CLARIFICATION_PICK_SPEC)
 
 
 def _suggest_project_pr_template(state: WizardState) -> str:
@@ -1425,42 +1471,24 @@ def _suggest_project_pr_template(state: WizardState) -> str:
     return val if isinstance(val, str) else ""
 
 
+_PR_TEMPLATE_PICK_SPEC = _OptionalCachedPickSpec(
+    step=S_PR_TEMPLATE_PICK, prompt_key="pr_template_pick",
+    recommend_token=_PROJECT_DEFAULT_TOKEN, label_key="project_default",
+    echo_suffix_key="project_default",
+    suggest=_suggest_project_pr_template, snippet_style="suffix",
+    cache_attr="last_pr_template_cached", target_attr="pr_template_path",
+    pending_attr="pr_template_pending_text",
+    # skip 시 scope 도 함께 비운다 (원래 _submit_pr_template_pick 의 동작).
+    extra_clear_attrs=("pr_template_scope",),
+)
+
+
 def _build_pr_template_pick(state: WizardState) -> Prompt:
-    project_default = _suggest_project_pr_template(state)
-    t = _p(state.workspace_root, "pr_template_pick")
-    options: list[Option] = []
-    options.append(_opt(PICK_SKIP, t["options"][PICK_SKIP]))
-    if project_default:
-        snippet = project_default if len(project_default) <= 60 else "…" + project_default[-60:]
-        label_template = t["labels"]["project_default"]
-        options.append(_opt(_PROJECT_DEFAULT_TOKEN, label_template.format(snippet=snippet)))
-        state.last_pr_template_cached = project_default
-    options.append(_opt(PICK_TYPE_CUSTOM, t["options"][PICK_TYPE_CUSTOM]))
-    return Prompt(
-        step=S_PR_TEMPLATE_PICK, kind="pick",
-        label=t["label"], options=options,
-        echo_template=t["echo_template"],
-    )
+    return _build_optional_cached_pick(state, _PR_TEMPLATE_PICK_SPEC)
 
 
 def _submit_pr_template_pick(state: WizardState, value: str) -> Optional[str]:
-    t = _p(state.workspace_root, "pr_template_pick")
-    if value == PICK_SKIP:
-        state.pr_template_path = ""
-        state.pr_template_scope = ""
-        state.pr_template_pending_text = False
-        return t["echo_suffixes"]["skip"]
-    if value == _PROJECT_DEFAULT_TOKEN:
-        state.pr_template_path = state.last_pr_template_cached
-        state.pr_template_pending_text = False
-        return t["echo_suffixes"]["project_default"].format(value=state.pr_template_path)
-    if value == PICK_TYPE_CUSTOM:
-        state.pr_template_pending_text = True
-        return None
-    raise WizardError(
-        f"unexpected pr-template value: {value!r} "
-        f"(expected {PICK_SKIP!r}, {_PROJECT_DEFAULT_TOKEN!r}, or {PICK_TYPE_CUSTOM!r})"
-    )
+    return _submit_optional_cached_pick(state, value, _PR_TEMPLATE_PICK_SPEC)
 
 
 CRITIC_CHOICES = ["off", "claude", "codex", "gemini"]
@@ -2218,6 +2246,30 @@ def init_state(
     )
 
 
+def _build_group_prompt(state: WizardState, group_id: str) -> Prompt:
+    """그룹의 적용가능·미답변 픽 멤버를 최대 GROUP_MAX_TABS 개 모은다.
+
+    멤버가 1개뿐이면 멀티탭 UI가 불필요하므로 그 멤버의 평범한 픽을 반환한다.
+    호출부(next_prompt)는 적용 가능한 멤버가 최소 1개일 때만 진입하므로 빈 그룹은
+    도달 불가다.
+    """
+    members: list[Prompt] = []
+    for sid in PROMPT_GROUPS[group_id]:
+        if sid in state.answered:
+            continue
+        step = STEP_BY_ID[sid]
+        if not step.applies(state):
+            continue
+        members.append(step.build(state))
+        if len(members) >= GROUP_MAX_TABS:
+            break
+    assert members, f"group {group_id!r} reached with no applicable members"
+    if len(members) == 1:
+        return members[0]
+    return Prompt(step=group_id, kind="pick_group",
+                  label=GROUP_LABELS[group_id], questions=members)
+
+
 def next_prompt(state: WizardState) -> Prompt:
     if state.confirmed:
         return Prompt(step=S_DONE, kind="done")
@@ -2225,10 +2277,39 @@ def next_prompt(state: WizardState) -> Prompt:
         if step.id in state.answered:
             continue
         if step.applies(state):
+            group_id = _STEP_TO_GROUP.get(step.id)
+            if group_id is not None:
+                return _build_group_prompt(state, group_id)
             return step.build(state)
     return Prompt(step=S_DONE, kind="done")
 
 
+def _submit_group(state: WizardState, prompt: Prompt, value: str) -> dict[str, Any]:
+    """pick_group 답(JSON 객체)을 각 멤버 submit() 으로 라우팅한다.
+
+    멤버 submit 이 WizardError 를 던지면 그대로 전파되어 같은 그룹을 재-프롬프트한다.
+    answered 마킹은 모든 멤버 submit 이 통과한 뒤에만 일괄 수행한다(answered 단위의
+    전부-아니면-전무). 개별 멤버가 변경한 state 필드는 롤백하지 않지만, 재-프롬프트 시
+    같은 그룹이 다시 나와 사용자 입력으로 덮어쓰므로 무해하다.
+    """
+    try:
+        answers = json.loads(value or "{}")
+    except json.JSONDecodeError as exc:
+        raise WizardError(f"pick_group answer must be a JSON object: {exc}")
+    if not isinstance(answers, dict):
+        raise WizardError("pick_group answer must be a JSON object")
+    echoes: list[str] = []
+    for q in prompt.questions:
+        echo = STEP_BY_ID[q.step].submit(state, str(answers.get(q.step, "") or ""))
+        if echo:
+            echoes.append(echo)
+    for q in prompt.questions:
+        if q.step not in state.answered:
+            state.answered.append(q.step)
+    nxt = next_prompt(state)
+    return {"echo": "; ".join(echoes), "next": nxt.to_json()}
+
+
 def submit(state: WizardState, value: str) -> dict[str, Any]:
     """Validate the answer for the *currently active* step and advance.
 
@@ -2238,6 +2319,8 @@ def submit(state: WizardState, value: str) -> dict[str, Any]:
     prompt = next_prompt(state)
     if prompt.kind == "done":
         return {"echo": "", "next": prompt.to_json()}
+    if prompt.kind == "pick_group":
+        return _submit_group(state, prompt, value)
     step = STEP_BY_ID[prompt.step]
     echo = step.submit(state, value or "")
     if prompt.step not in state.answered:

package/runtime/python/okstra_ctl/workflow.py

@@ -87,7 +87,7 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - trade-off matrix across options (complexity, risk, reversibility, test cost, rollout cost) and recommended option with rationale tied to isolation / single-responsibility / YAGNI principles\n"
             "  - bite-sized stepwise execution order for the recommended option (each step ~2-5 min, exact file paths and commands, TDD ordering when applicable, no placeholders)\n"
             "  - dependency / migration risk assessment, validation checklist (pre / mid / post with exact commands), rollback strategy with revert path and trigger signal\n"
-            "  - every unresolved ambiguity registered as a `Blocks=approval` row in the `## 5. Clarification Items` table (do NOT create a separate `Open Questions` block under `4.5.x` — the unified table is the single home)\n"
+            "  - every unresolved ambiguity registered as a `Blocks=approval` row in the `## 1. Clarification Items` table (do NOT create a separate `Open Questions` block under `5.5.x` — the unified table is the single home)\n"
             "  - YAML frontmatter line `approved: false` awaiting human flip to `true`\n"
             "  - self-review confirmation (spec coverage, placeholder scan, internal consistency, ambiguity, scope)"
         ),