okstra 0.88.2 → 0.90.0

package/runtime/python/okstra_ctl/report_views.py

@@ -57,6 +57,7 @@ def _strip_leading_frontmatter(text: str) -> str:
     return _LEADING_FRONTMATTER_RE.sub("", text, count=1)
 
 from .clarification_items import (
+    _CELL_ANCHOR_RE,
     _section_1_slice,
     _split_pipe_row,
     parse_clarification_items,
@@ -139,7 +140,7 @@ def render_html(
         f"  <button type=\"button\" data-action=\"export-user-response\">Export user response</button>\n"
         f"</header>\n"
         f"<main>{body_html}</main>\n"
-        f"{_plan_approval_section(approval_ctx) if approval_ctx else ''}"
+        f"{_plan_approval_section(approval_ctx, run_meta) if approval_ctx else ''}"
         f"<footer class=\"report-footer\">\n"
         f"  <button type=\"button\" data-action=\"export-user-response\">Export user response</button>\n"
         f"  <p class=\"user-response-hint\">Export 클릭 시 <code>{sidecar_name}</code> 가 다운로드됩니다 — "
@@ -336,6 +337,12 @@ def _section_forbids_form(path: Iterable[str]) -> bool:
 def _emit_table(lines: list[str], start: int, section_path: list[str]) -> tuple[str, int]:
     header_cells = _split_pipe_row(lines[start])
     rows: list[list[str]] = []
+    # `_split_pipe_row` strips the ID-defining scroll anchor (`<a id="c-001">`)
+    # out of every first cell, so the lowercase fragment that the ID-Index and
+    # in-body references link to (`[C-001](#c-001)`) would have no landing
+    # element. Capture each row's stripped anchor id here and re-attach it to
+    # the emitted `<tr>` below so those `href="#…"` links actually jump.
+    row_anchor_ids: list[Optional[str]] = []
     i = start + 2  # skip header + separator
     while i < len(lines) and lines[i].lstrip().startswith("|"):
         cells = _split_pipe_row(lines[i])
@@ -347,6 +354,8 @@ def _emit_table(lines: list[str], start: int, section_path: list[str]) -> tuple[
             keep = len(header_cells) - 1
             cells = cells[:keep] + ["|".join(cells[keep:])]
         rows.append(cells)
+        anchor = _CELL_ANCHOR_RE.search(lines[i])
+        row_anchor_ids.append(anchor.group(1).lower() if anchor else None)
         i += 1
 
     # §1 Clarification Items is the only interactive table. Its short columns
@@ -390,7 +399,7 @@ def _emit_table(lines: list[str], start: int, section_path: list[str]) -> tuple[
         header_cells.index("User input") if "User input" in header_cells else -1
     )
     body_rows: list[str] = []
-    for row in rows:
+    for row, anchor_id in zip(rows, row_anchor_ids):
         meta = parse_meta_cell(row[0]) if (is_clarification_table and row) else None
         if (
             meta is not None
@@ -422,8 +431,11 @@ def _emit_table(lines: list[str], start: int, section_path: list[str]) -> tuple[
                 + "</tr>"
             )
         else:
+            tr_open = (
+                f'<tr id="{html.escape(anchor_id)}">' if anchor_id else "<tr>"
+            )
             body_rows.append(
-                "<tr>"
+                tr_open
                 + "".join(
                     f"<td{_col_class(idx, narrow_cols)}>{_inline(c)}</td>"
                     for idx, c in enumerate(row)
@@ -809,10 +821,13 @@ def report_has_clarification_items(src_md: str) -> bool:
 @dataclass(frozen=True)
 class PlanApprovalContext:
     """Plan Approval 위젯 렌더 입력. ``disabled_reason`` 이 비어 있지 않으면
-    위젯은 disabled 로 렌더된다 (run-prep 승인 게이트와 동일한 fail-closed 기준)."""
+    위젯은 disabled 로 렌더된다 (run-prep 승인 게이트와 동일한 fail-closed 기준).
+    ``blocker_ids`` 는 §1 미해소 승인-차단 항목 ID 목록 — 화면 안내가 사용자에게
+    '어느 항목을 답해야 하는지' 를 보여주는 데 쓴다 (unreadable 사유면 빈 튜플)."""
     option_names: tuple[str, ...]
     recommended_option: str
     disabled_reason: str
+    blocker_ids: tuple[str, ...]
 
 
 def plan_approval_context(
@@ -841,28 +856,71 @@ def plan_approval_context(
     )
     if not names:
         return None
-    recommended = ""
     rec = planning.get("recommendedOption")
-    if isinstance(rec, dict):
-        recommended = rec.get("name") or ""
-    if recommended not in names:
-        recommended = names[0]
+    rec_name = rec.get("name") or "" if isinstance(rec, dict) else ""
+    recommended = _resolve_recommended_option(rec_name, names)
     scan = scan_approval_gate(src_text)
+    blocker_ids: tuple[str, ...] = ()
     if scan.unreadable_reason:
         reason = "§1 승인 게이트를 읽을 수 없어 승인이 비활성화되었습니다 — 보고서를 재렌더하세요."
     elif scan.blockers:
-        reason = (
-            f"§1 승인 차단 항목 {len(scan.blockers)}건 미해소 — 답변을 채워 Export 한 뒤 "
-            "resume-clarification 으로 해소한 다음 보고서에서 승인하세요."
-        )
+        blocker_ids = tuple(b.row_id for b in scan.blockers)
+        reason = f"§1 승인 차단 항목 {len(scan.blockers)}건 미해소"
     else:
         reason = ""
     return PlanApprovalContext(
-        option_names=names, recommended_option=recommended, disabled_reason=reason
+        option_names=names,
+        recommended_option=recommended,
+        disabled_reason=reason,
+        blocker_ids=blocker_ids,
+    )
+
+
+def _resolve_recommended_option(rec_name: str, names: tuple[str, ...]) -> str:
+    """``recommendedOption.name`` 을 후보 이름에 맞춘다. 정확 일치가 없으면
+    접두 일치(후보가 ``(RECOMMENDED)`` 같은 표식 접미를 더 달고 있는 흔한 경우)를
+    허용하고, 그래도 없으면 첫 후보로 폴백한다 — 항상 정확히 한 옵션이 selected 가
+    되어 브라우저 자동선택분의 묵시 Export 를 차단한다."""
+    if rec_name in names:
+        return rec_name
+    if rec_name:
+        for name in names:
+            if name.startswith(rec_name) or rec_name.startswith(name):
+                return name
+    return names[0]
+
+
+def _approval_blocked_guidance(ctx: PlanApprovalContext, run_meta: RunMeta) -> str:
+    """disabled 사유를 화면에서 바로 따라할 수 있는 단계별 안내로 렌더한다.
+    핵심: 이 화면에서 답을 입력하는 것만으로는 승인이 풀리지 않으며,
+    Export → 저장 → resume-clarification → 재렌더 라운드트립이 필요하다는 것."""
+    if not ctx.blocker_ids:  # unreadable 사유 — 재렌더 외에 따라할 단계가 없다.
+        return f'<p class="approval-disabled-reason">{html.escape(ctx.disabled_reason)}</p>'
+    sidecar_dir = f"runs/{run_meta.task_type}/user-responses/"
+    ids = ", ".join(ctx.blocker_ids)
+    steps = [
+        f"위 <strong>§1 Clarification Items</strong> 표에서 차단 항목 "
+        f"<strong>{html.escape(ids)}</strong> 의 'User input' 칸에 답을 입력합니다.",
+        "헤더 또는 맨 아래의 <strong>[Export user response]</strong> 버튼을 눌러 응답 파일을 내려받습니다.",
+        f"내려받은 파일을 <code>{html.escape(sidecar_dir)}</code> 에 그대로 저장합니다.",
+        f"터미널에서 <code>scripts/okstra.sh --resume-clarification --task-key "
+        f"{html.escape(run_meta.task_key)}</code> (Claude Code 에서는 "
+        f"<code>/okstra-run resume-clarification task-key={html.escape(run_meta.task_key)}</code>) "
+        "을 실행합니다.",
+        "명령이 끝나면 <strong>새로 생성된 보고서</strong>를 여세요 — "
+        "그 보고서에서 이 체크박스가 활성화됩니다.",
+    ]
+    lis = "".join(f"<li>{s}</li>" for s in steps)
+    return (
+        '<div class="approval-disabled-reason">'
+        f"<p><strong>{html.escape(ctx.disabled_reason)}</strong>라 아직 승인할 수 없습니다. "
+        "이 화면에서 답만 입력해서는 풀리지 않습니다 — 아래 순서로 해소하세요:</p>"
+        f'<ol class="approval-steps">{lis}</ol>'
+        "</div>"
     )
 
 
-def _plan_approval_section(ctx: PlanApprovalContext) -> str:
+def _plan_approval_section(ctx: PlanApprovalContext, run_meta: RunMeta) -> str:
     disabled = " disabled" if ctx.disabled_reason else ""
     opts: list[str] = []
     for name in ctx.option_names:
@@ -871,8 +929,7 @@ def _plan_approval_section(ctx: PlanApprovalContext) -> str:
         attrs = ' data-recommended="true" selected' if is_rec else ""
         opts.append(f'<option value="{html.escape(name)}"{attrs}>{html.escape(label)}</option>')
     reason_html = (
-        f'\n  <p class="approval-disabled-reason">{html.escape(ctx.disabled_reason)}</p>'
-        if ctx.disabled_reason else ""
+        "\n  " + _approval_blocked_guidance(ctx, run_meta) if ctx.disabled_reason else ""
     )
     return (
         '<section id="plan-approval">\n'

package/runtime/python/okstra_ctl/wizard.py

@@ -18,7 +18,9 @@ imports this module directly.
 """
 from __future__ import annotations
 
+import copy
 import json
+import math
 import re
 import subprocess
 from dataclasses import asdict, dataclass, field
@@ -3235,6 +3237,83 @@ def next_prompt(state: WizardState) -> Prompt:
     return Prompt(step=S_DONE, kind="done")
 
 
+def _passed_screens(state: WizardState) -> int:
+    """이미 답한 화면 수. pick_group 멤버는 GROUP_MAX_TABS 묶음당 1화면으로 환산."""
+    count = 0
+    group_hits: dict[str, int] = {}
+    for sid in state.answered:
+        gid = _STEP_TO_GROUP.get(sid)
+        if gid is None:
+            count += 1
+        else:
+            group_hits[gid] = group_hits.get(gid, 0) + 1
+    for hits in group_hits.values():
+        count += math.ceil(hits / GROUP_MAX_TABS)
+    return count
+
+
+def _sim_answer(prompt: Prompt) -> str:
+    """분모 추정 시뮬레이션의 기본답: pick 은 첫 옵션(추천), text 는 빈 값."""
+    if prompt.kind == "pick" and prompt.options:
+        return prompt.options[0].value
+    return ""
+
+
+def _sim_advance(state: WizardState, prompt: Prompt) -> None:
+    """기본답으로 한 화면 전진한다. progress 를 재계산하는 submit()/
+    _submit_group() 은 호출하지 않고 step.submit 만 직접 호출해 재귀를 막는다."""
+    try:
+        if prompt.kind == "pick_group":
+            for q in prompt.questions:
+                STEP_BY_ID[q.step].submit(state, _sim_answer(q))
+            for q in prompt.questions:
+                if q.step not in state.answered:
+                    state.answered.append(q.step)
+            return
+        STEP_BY_ID[prompt.step].submit(state, _sim_answer(prompt))
+        if prompt.step not in state.answered:
+            state.answered.append(prompt.step)
+    except Exception:
+        # 추천 경로가 막히는 드문 text 분기: answered 마킹만으로 전진시킨다.
+        members = prompt.questions if prompt.kind == "pick_group" else [prompt]
+        for p in members:
+            if p.step not in state.answered:
+                state.answered.append(p.step)
+
+
+def _remaining_screens(state: WizardState) -> int:
+    """현재 화면부터 confirm(=done 직전)까지 남은 화면 수를 시뮬레이션으로 센다."""
+    sim = copy.deepcopy(state)
+    screens = 0
+    for _ in range(len(STEPS) * 2 + 5):  # Edit 루프 등에 대한 상한 가드
+        try:
+            prompt = next_prompt(sim)
+        except Exception:
+            break
+        if prompt.kind in ("done", "aborted"):
+            break
+        screens += 1
+        _sim_advance(sim, prompt)
+        if prompt.step == S_CONFIRM:  # confirm 이후는 done — Edit 는 가정하지 않는다
+            break
+    return screens
+
+
+def _screen_progress(state: WizardState) -> dict[str, int]:
+    passed = _passed_screens(state)
+    total = passed + _remaining_screens(state)
+    index = passed + 1
+    return {"index": index, "total": total, "remaining": max(0, total - index)}
+
+
+def prompt_payload(state: WizardState, prompt: Prompt) -> dict[str, Any]:
+    """Prompt JSON 에 진행 카운터를 덧붙인다. done/aborted 는 progress 를 생략."""
+    out = prompt.to_json()
+    if prompt.kind not in ("done", "aborted"):
+        out["progress"] = _screen_progress(state)
+    return out
+
+
 def _submit_group(state: WizardState, prompt: Prompt, value: str) -> dict[str, Any]:
     """pick_group 답(JSON 객체)을 각 멤버 submit() 으로 라우팅한다.
 
@@ -3258,7 +3337,7 @@ def _submit_group(state: WizardState, prompt: Prompt, value: str) -> dict[str, A
         if q.step not in state.answered:
             state.answered.append(q.step)
     nxt = next_prompt(state)
-    return {"echo": "; ".join(echoes), "next": nxt.to_json()}
+    return {"echo": "; ".join(echoes), "next": prompt_payload(state, nxt)}
 
 
 def submit(state: WizardState, value: str) -> dict[str, Any]:
@@ -3269,7 +3348,7 @@ def submit(state: WizardState, value: str) -> dict[str, Any]:
     """
     prompt = next_prompt(state)
     if prompt.kind in ("done", "aborted"):
-        return {"echo": "", "next": prompt.to_json()}
+        return {"echo": "", "next": prompt_payload(state, prompt)}
     if prompt.kind == "pick_group":
         return _submit_group(state, prompt, value)
     step = STEP_BY_ID[prompt.step]
@@ -3277,7 +3356,7 @@ def submit(state: WizardState, value: str) -> dict[str, Any]:
     if prompt.step not in state.answered:
         state.answered.append(prompt.step)
     nxt = next_prompt(state)
-    return {"echo": echo or "", "next": nxt.to_json()}
+    return {"echo": echo or "", "next": prompt_payload(state, nxt)}
 
 
 def render_args(state: WizardState) -> dict[str, str]:
@@ -3471,7 +3550,7 @@ def _cli(argv: list[str]) -> int:
             state.critic = args.critic
         save_state_file(state_path, state)
         first = next_prompt(state)
-        print(json.dumps({"ok": True, "next": first.to_json()},
+        print(json.dumps({"ok": True, "next": prompt_payload(state, first)},
                          ensure_ascii=False, indent=2))
         return 0
 
@@ -3497,13 +3576,13 @@ def _cli(argv: list[str]) -> int:
             return 2
         try:
             if args.no_submit:
-                result = {"echo": "", "next": next_prompt(state).to_json()}
+                result = {"echo": "", "next": prompt_payload(state, next_prompt(state))}
             else:
                 result = submit(state, args.answer)
         except WizardError as exc:
             save_state_file(state_path, state)
             print(json.dumps({"ok": False, "error": str(exc),
-                              "current": next_prompt(state).to_json()},
+                              "current": prompt_payload(state, next_prompt(state))},
                              ensure_ascii=False, indent=2))
             return 0
         save_state_file(state_path, state)

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

@@ -28,9 +28,12 @@ Every wizard call returns JSON. The two shapes you'll see:
 
 ```json
 { "ok": true, "echo": "task-group: backend-api",
-  "next": { "step": "task_id", "kind": "text", "label": "...", "options": [], "echoTemplate": "..." } }
+  "next": { "step": "task_id", "kind": "text", "label": "...", "options": [], "echoTemplate": "...",
+            "progress": { "index": 5, "total": 11, "remaining": 6 } } }
 ```
 
+Every non-terminal `next` carries a `progress` object (`done` / `aborted` omit it). `index` is the 1-based number of the **current screen** (pick_group counts as one screen), `total` is the wizard's estimate of the full screen count, and `remaining` = `total − index`. The total is a forward estimate from the current answers, so it may grow by a few when the user opens a branch (e.g. choosing *Customize* adds the model screen). **Always suffix the rendered prompt with the progress marker** — see Step 3.
+
 ```json
 { "ok": false, "error": "approved plan has no APPROVED marker: ...",
   "current": { "step": "approved_plan", "kind": "text", "label": "..." } }
@@ -93,7 +96,7 @@ Output: the same `{ok, next}` JSON described above. The first `next` is always `
 
 Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How the wizard talks to you"):
 
-1. **Render** the prompt according to `kind` (and `multi` for pick):
+1. **Render** the prompt according to `kind` (and `multi` for pick). **Always append the progress marker to the rendered question label** (the `AskUserQuestion` question text, or the `text`-prompt message): suffix `label` with ` (Step <index>/<total> · 남은 <remaining>단계)`, using `next.progress`. When `remaining == 0` (the final `confirm` screen), use `(Step <index>/<total> · 마지막 단계)` instead. Example: `모델을 선택하세요 (Step 8/11 · 남은 3단계)`. Re-prompts after `ok: false` reuse `current.progress` the same way. The progress marker is presentation-only — never send it back to the wizard as part of an answer.
    - `pick` + `multi: false` → `AskUserQuestion` with `multiSelect: false`, `label`, and `options`. The user's chosen option's `value` is the answer string.
    - `pick` + `multi: true` → `AskUserQuestion` with `multiSelect: true`, `label`, and `options`. Join the selected `value`s with `,` into a single literal CSV string (e.g. `"claude,codex,antigravity"`) and submit it as a single `--answer "claude,codex,antigravity"`. Empty selection submits `--answer ""` and the wizard re-prompts.
    - `pick_group` → one `AskUserQuestion` with one question per `questions[]` entry (tab). Map each tab's selected `value` back by `questions[].step`, assemble a JSON object, and submit it as a single literal `--answer '<json>'`.

package/runtime/templates/reports/report.css

@@ -207,7 +207,16 @@ button[data-action]:hover { background: color-mix(in srgb, Highlight 20%, Button
 #plan-approval h2 { margin-top: 0; }
 #plan-approval label { display: block; margin: 0.4em 0; }
 #plan-approval select { font: inherit; max-width: 100%; }
-.approval-disabled-reason { color: GrayText; margin: 0.4em 0 0; }
+.approval-disabled-reason {
+  margin: 0.6em 0 0;
+  padding: 0.7em 0.9em;
+  border-radius: 4px;
+  background: color-mix(in srgb, Highlight 12%, transparent);
+  border: 1px solid color-mix(in srgb, Highlight 45%, transparent);
+}
+.approval-disabled-reason p { margin: 0 0 0.5em; }
+.approval-steps { margin: 0.3em 0 0; padding-left: 1.4em; }
+.approval-steps li { margin: 0.25em 0; }
 
 @media print {
   .report-header, .report-footer { position: static; }

package/runtime/templates/reports/settings.template.json

@@ -48,6 +48,26 @@
           }
         ]
       }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$HOME/.okstra/bin/okstra-subagent-reclaim.sh"
+          }
+        ]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$HOME/.okstra/bin/okstra-subagent-reclaim.sh"
+          }
+        ]
+      }
     ]
   }
 }

package/src/doctor.mjs

@@ -194,11 +194,13 @@ export async function run(args) {
     env: process.env,
     capabilities: { tmuxAvailable: Boolean(process.env.TMUX) },
   });
-  if (!runtimeResolution.ok) {
-    process.stderr.write(`error: ${runtimeResolution.reason}\n`);
-    return 2;
-  }
-  const resolvedRuntime = runtimeResolution.resolvedRuntime;
+  // doctor is an environment diagnostic, not a dispatch path. A failed host
+  // auto-detection only means we cannot attribute the optional skill checks to a
+  // runtime, so degrade it to a warning and keep running the host-independent
+  // checks. Dispatch callers of resolveRuntime stay fail-closed by design — this
+  // leniency lives only here. With resolvedRuntime null the skill checks skip
+  // (requiredSkillNamesForRuntime → []); pass --runtime to include them.
+  const resolvedRuntime = runtimeResolution.ok ? runtimeResolution.resolvedRuntime : null;
 
   const results = [
     await check("python3", checkPython3),
@@ -258,6 +260,11 @@ export async function run(args) {
     return allOk ? 0 : 1;
   }
 
+  if (!runtimeResolution.ok) {
+    process.stdout.write(
+      `  [WARN] runtime host: ${runtimeResolution.reason} skill checks skipped — pass --runtime <claude-code|codex|external> to include them.\n`,
+    );
+  }
   for (const r of results) {
     const mark = r.ok ? "OK  " : "FAIL";
     process.stdout.write(`  [${mark}] ${r.name}: ${r.detail}\n`);

package/src/install.mjs

@@ -32,6 +32,7 @@ const BIN_ENTRYPOINTS = [
   "okstra-claude-exec.sh",
   "okstra-antigravity-exec.sh",
   "okstra-trace-cleanup.sh",
+  "okstra-subagent-reclaim.sh",
   "okstra-team-reconcile.sh",
   "okstra-central.sh",
   "okstra-token-usage.py",