okstra 0.50.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,
@@ -421,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:
@@ -1107,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$")
@@ -1256,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 = [
@@ -1285,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]] = []
@@ -1311,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:
@@ -1369,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:
@@ -1457,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"]

package/runtime/python/okstra_ctl/worktree.py

@@ -172,7 +172,7 @@ def preview_worktree_decision(
     helpers so preview never diverges from the actual provisioning result.
     """
     project_root = Path(project_root)
-    if not _is_git_repo(project_root):
+    if not is_git_work_tree(project_root):
         return WorktreeDecision(status="skipped-not-git", path=str(project_root))
     if _is_inside_non_main_worktree(project_root):
         return WorktreeDecision(status="skipped-in-worktree", path=str(project_root))
@@ -232,8 +232,16 @@ def _is_inside_non_main_worktree(project_root: Path) -> bool:
     return common_abs != per_tree_abs
 
 
-def _is_git_repo(project_root: Path) -> bool:
-    res = _git(project_root, "rev-parse", "--is-inside-work-tree")
+def is_git_work_tree(project_root: Path) -> bool:
+    """project_root 가 git work tree 내부인지 판정하는 public git-introspection seam.
+
+    git 미설치(FileNotFoundError) 를 포함한 모든 실패는 False — 호출자(migrate
+    등)가 non-git 레이아웃으로 안전하게 폴백할 수 있도록 한다. 과거 migrate.py
+    가 같은 판정을 자체 구현(`--show-toplevel`)했는데 이 seam 으로 통합한다."""
+    try:
+        res = _git(project_root, "rev-parse", "--is-inside-work-tree")
+    except (OSError, FileNotFoundError):
+        return False
     return res.returncode == 0 and res.stdout.strip() == "true"
 
 
@@ -260,7 +268,7 @@ def _resolve_commit_sha(cwd: Path, ref: str) -> str:
     return res.stdout.strip()
 
 
-def _main_worktree_path(project_root: Path) -> Path:
+def main_worktree_path(project_root: Path) -> Path:
     """Locate the repository's MAIN worktree (the original checkout).
 
     `git worktree list --porcelain` lists worktrees in a stable order
@@ -601,7 +609,7 @@ def provision_task_worktree(
             "work-category before retrying."
         )
 
-    main_root = _main_worktree_path(project_root)
+    main_root = main_worktree_path(project_root)
     requested_base = (base_ref or "").strip()
     if not requested_base and require_base_ref:
         raise RuntimeError(

package/runtime/schemas/final-report-v1.0.schema.json

@@ -83,6 +83,10 @@
         "approved": {
           "type": "boolean",
           "description": "사용자 승인 플래그. report-writer 는 항상 false 로 발행하고, 사용자가 `--approve` 또는 직접 편집으로 true 로 토글합니다. `implementation` task-type 의 prepare 단계가 `--approved-plan` 으로 지정된 보고서의 이 필드를 읽어 진입 여부를 결정합니다. 다른 task-type 에서는 의미 없이 false 로 유지됩니다."
+        },
+        "implementationOption": {
+          "type": "string",
+          "description": "유저가 implementation-planning final-report 에서 고른 Option Candidate 이름. report-writer 는 항상 빈 문자열로 발행하고, 사용자가 `--implementation-option <name>` 또는 직접 편집으로 채웁니다. `implementation` task-type 이 이 값으로 진행하며, 비어 있으면 plan 의 `Recommended Option` 으로 폴백합니다. 다른 task-type 에서는 의미 없이 빈 값으로 유지됩니다."
         }
       }
     },

package/runtime/skills/okstra-coding-preflight/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: okstra-coding-preflight
+description: Provides language-specific coding conventions, idioms, and test-writing guidance for Java, Kotlin, JavaScript, TypeScript, Node.js, Python, SQL, and Rust. okstra lead/workers MUST consult this skill before writing, editing, refactoring, or testing code in any of these languages — including any new file, function, or test — even when the task seems simple enough to handle directly. Detect the target language from the file extension, project config (package.json/Cargo.toml/pyproject.toml/pom.xml/build.gradle), or task brief, and apply the matching conventions.
+user-invocable: false
+---
+
+# okstra Code Preflight
+
+## These apply to every worker writing or editing project code (executor and verifiers alike). Enforcement is self-check: the agent runs each rule's check immediately before reporting "done"; skipping a check is itself a contract violation.
+
+1. **DRY — single reference point** — One implementation per capability. A second caller signals "extract shared logic", not "duplicate path".
+2. **KISS — simplest sufficient design** — Add abstraction layers (helper modules, strategy/factory, configuration flags, indirection) only when an existing concrete call site requires them. *Self-check: name the second caller now; if you cannot, inline.* *Example violation: extracting `formatUserName()` helper used by exactly one call site, "in case we need it elsewhere".*
+3. **YAGNI — build only for current requirements** — No speculative parameters, optional configs, "future-proof" hooks, or pre-1.0 backwards-compat shims. *Self-check: every newly introduced identifier has ≥1 current internal caller, or was explicitly user-requested.* *Example violation: adding `options?: { retries?, timeout? }` parameter when the current call passes nothing.*
+4. **Clean Code — names carry WHAT, comments explain WHY** — Identifiers must make intent obvious; if a comment would describe WHAT the code does, rename instead. Reserve comments for non-obvious WHY (hidden constraint, workaround, surprising invariant). Delete dead/commented-out code immediately — git history is the archive. *Example — WHAT (rename instead): `// increment counter` above `i++`. WHY (keep): `// retry up to 3x: upstream returns 502 during deploys`.*
+5. **Function length cap — 50 lines** — A single function/method body must stay within 50 lines, counting only effective code (exclude blank lines, comments, and pure data declarations such as large enums, lookup tables, or constant maps). Crossing the cap is an extraction signal, not a style nit. *Self-check: for any function newly added or substantially edited, count effective body lines; if over 50, split before declaring complete, or surface the violation and confirm with the user.*
+
+
+## Quick start
+
+Before writing or editing **any** code:
+
+1. Identify the target language (file extension, project config, or explicit user request).
+2. Read the matching language reference from `languages/`.
+3. Read [clean-code.md](clean-code.md) for the language-agnostic principles.
+4. **Check for architecture overlays.** If the project uses ports-and-adapters (signals: `domain/` + `ports/` + `adapters/` folders, `*.port.*` files, NestJS hex split), also read [architecture/hexagonal.md](architecture/hexagonal.md). Record the detected layout in one line so later edits don't re-discover it.
+5. In **one short sentence** to the user, state which conventions you will apply (e.g., *"Applying Kotlin conventions + hexagonal overlay; domain at `src/domain/`."*).
+6. Then write code.
+
+If the language is not listed below, stop and ask the user for the canonical style guide they want to follow before writing code.
+
+## Language router
+
+| Language | Reference | Triggers |
+|---|---|---|
+| Java | [languages/java.md](languages/java.md) | `.java`, `pom.xml`, `build.gradle` |
+| Kotlin | [languages/kotlin.md](languages/kotlin.md) | `.kt`, `.kts`, `build.gradle.kts` |
+| JavaScript / TypeScript | [languages/javascript-typescript.md](languages/javascript-typescript.md) | `.js`, `.ts`, `.tsx`, `.jsx` |
+| Node.js (server) | [languages/nodejs.md](languages/nodejs.md) | `package.json` with server entry, `express`, `fastify`, `nestjs` |
+| Python | [languages/python.md](languages/python.md) | `.py`, `pyproject.toml`, `requirements.txt`, `setup.py`, `setup.cfg` |
+| SQL | [languages/sql.md](languages/sql.md) | `.sql`, migration directories, `prisma/schema.prisma`, raw queries embedded in code |
+| Rust | [languages/rust.md](languages/rust.md) | `.rs`, `Cargo.toml` |
+
+For Node.js work, load **both** `javascript-typescript.md` and `nodejs.md`.
+
+## Architecture overlays
+
+Loaded **in addition to** the language reference when the project matches. Overlays add architectural rules that cut across languages.
+
+| Overlay | Reference | When to load |
+|---|---|---|
+| Hexagonal (ports & adapters) | [architecture/hexagonal.md](architecture/hexagonal.md) | Project has `domain/` + `ports/` + `adapters/` (or equivalent: `core/`, `infrastructure/`, `application/`), `*.port.*` files, or `abstract class` files at a domain boundary. Confirm once with the user if ambiguous. |
+
+If you suspect an overlay applies but the layout is non-standard, ask one question — *"does this project follow ports-and-adapters? where is the domain?"* — and record the answer.
+
+## Mandatory pre-write checks (every language)
+
+- [ ] Language reference read for this turn.
+- [ ] `clean-code.md` principles applied: DRY, KISS, SOLID, YAGNI, meaningful naming (truthful + standalone), single-purpose functions, plain-English summary test, 50-line cap, no magic numbers, shallow nesting, comments-explain-why.
+- [ ] Tests planned: which test(s) cover this change. New behaviour without a test is **incomplete** unless the user has explicitly opted out for this change.
+- [ ] **Testing discipline:** the test does not stub/spy methods on the SUT itself (collaborators are fine), and assertions are on outcomes (return values, state, events, boundary calls) — not on which internal helper was called.
+- [ ] **Hexagonal overlay (if loaded):** no business logic inside any port body, adapter methods are I/O only (no post-fetch JS filtering on domain state, no `findValid*`/`findActive*` adapter names hiding rules), all domain objects declared under `domain/`.
+- [ ] Existing code searched: `grep` for the symbol / file / identifier you are about to add. Do not duplicate.
+- [ ] Project conventions checked: `.editorconfig`, `CONTRIBUTING.md`, formatter config (`.prettierrc`, `rustfmt.toml`, `ktlint`, `google-java-format`, etc.). **Project rules override this skill on conflict.**
+
+## Boundaries
+
+- This skill does **not** auto-format. Run the project's formatter yourself.
+- This skill does **not** replace repo-local rules. Repo rules win on conflict.
+- This skill does **not** cover every language. If the target language is missing, stop and ask.