okstra 0.89.0 → 0.91.0

package/runtime/python/okstra_ctl/report_views.py

@@ -140,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> 가 다운로드됩니다 — "
@@ -490,6 +490,11 @@ def _parse_enum_options(statement: str) -> list[tuple[str, str]]:
 
 _RECOMMENDED_CUE = "Recommended:"
 _ALTERNATIVES_CUE = "Alternatives:"
+# Authors sometimes append a pick-one answer-space summary like
+# "(A / B 중 택1)" to the Expected form. The rendered <select> already
+# enforces single choice, so this annotation must never reach an option
+# label — strip a trailing parenthetical that contains "택<n>".
+_PICK_ONE_ANNOTATION = re.compile(r"\s*\([^()]*택\s*\d+\s*\)\s*$")
 
 
 def _parse_expected_form_options(expected_form: str) -> list[tuple[str, str]]:
@@ -500,6 +505,7 @@ def _parse_expected_form_options(expected_form: str) -> list[tuple[str, str]]:
     ``Recommended:`` cue — the caller falls back to the statement enum."""
     if not expected_form:
         return []
+    expected_form = _PICK_ONE_ANNOTATION.sub("", expected_form)
     rec_idx = expected_form.find(_RECOMMENDED_CUE)
     if rec_idx < 0:
         return []
@@ -821,10 +827,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(
@@ -853,28 +862,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:
@@ -883,8 +935,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
@@ -1926,24 +1928,19 @@ def _submit_handoff_stage_pick(state: WizardState, value: str) -> Optional[str]:
 
 
 def _suggest_latest_final_report(state: WizardState) -> str:
-    """task 의 모든 phase runs 디렉토리에서 가장 최근 final-report-*.md 의 relpath 를 반환.
+    """clarification carry-in 으로 추천할 직전 final-report 의 relpath.
 
-    찾지 못하면 빈 문자열.
+    resume-clarification 은 "같은 phase 를 답변과 함께 재실행" 이므로 재실행
+    task-type **자신의** 보고서(``runs/<task-type>/reports/final-report-*.md``)를
+    우선한다. 그 phase 에 보고서가 없을 때만(예: 다음 phase 로 진행) 전체 phase 의
+    mtime 최신으로 폴백한다 — 과거엔 무조건 전체 mtime 최신이라 더 최근에 재렌더된
+    다른 phase 보고서를 잘못 집을 수 있었다. 못 찾으면 빈 문자열.
     """
     if not state.task_group or not state.task_id or not state.project_root:
         return ""
     runs_base = task_runs_dir(state.project_root, state.task_group, state.task_id)
     if not runs_base.is_dir():
         return ""
-    # run 산출물 구조는 runs/<task-type>/reports/final-report-*.md (1단계).
-    # 과거 `*/*/reports/...` (2단계) glob 은 실제 구조와 어긋나 항상 빈 결과여서
-    # clarification 단계가 직전 final-report 를 추천하지 못했다.
-    candidates = [
-        p for p in runs_base.glob("*/reports/final-report-*.md")
-        if p.is_file()
-    ]
-    if not candidates:
-        return ""
 
     def _mtime_safe(p: Path) -> float:
         try:
@@ -1951,7 +1948,19 @@ def _suggest_latest_final_report(state: WizardState) -> str:
         except OSError:
             return -1.0
 
-    best = max(candidates, key=_mtime_safe)
+    def _newest(glob_pattern: str) -> Optional[Path]:
+        cands = [p for p in runs_base.glob(glob_pattern) if p.is_file()]
+        return max(cands, key=_mtime_safe) if cands else None
+
+    # 산출물 구조는 runs/<task-type>/reports/final-report-*.md (1단계).
+    best: Optional[Path] = None
+    if state.task_type:
+        seg = slugify_task_segment(state.task_type)
+        best = _newest(f"{seg}/reports/final-report-*.md")
+    if best is None:
+        best = _newest("*/reports/final-report-*.md")
+    if best is None:
+        return ""
     try:
         return str(best.relative_to(Path(state.project_root)))
     except ValueError:
@@ -3235,6 +3244,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 +3344,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 +3355,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 +3363,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 +3557,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 +3583,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/schemas/final-report-v1.0.schema.json

@@ -10,6 +10,7 @@
     "frontmatter",
     "header",
     "verdictCard",
+    "rationale",
     "summary",
     "executionStatus",
     "tokenUsage",
@@ -153,6 +154,19 @@
       }
     },
 
+    "rationale": {
+      "type": "object",
+      "description": "## 작업 배경과 근거 — reviewer-facing narrative answering the four questions in order. Each field is prose (not a table) and MUST carry at least one evidence reference (path:line, a report ID such as C-001/F-013/§5.4, or another cited source) OR an explicit insufficiency marker (e.g. '근거 불충분'). validate-run.py fails a field with neither. Required for every task-type.",
+      "required": ["motivation", "problem", "approach", "justification"],
+      "additionalProperties": false,
+      "properties": {
+        "motivation": { "type": "string", "minLength": 1, "description": "왜 이 작업을 하는가 — 목표·맥락." },
+        "problem": { "type": "string", "minLength": 1, "description": "왜 이게 문제인가 — 현재 상태의 결함을 증거로." },
+        "approach": { "type": "string", "minLength": 1, "description": "그래서 어떤 작업이 필요한가 — 택한 방향." },
+        "justification": { "type": "string", "minLength": 1, "description": "왜 이게 합리적 선택인가 — 대안 대비 근거." }
+      }
+    },
+
     "summary": {
       "type": "array",
       "description": "## Summary of the Problem or Verification Target. 3-5 rows.",

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>'`.
@@ -124,6 +127,7 @@ That is the entire interactive flow. The wizard handles:
 - `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = 의존성 충족된 가장 빠른 미완료 stage, 또는 특정 stage 번호) + executor pick. approved-plan 선택 시 그 run 의 sibling `user-responses/` 에서 plan 과 source-report·seq 가 일치하는, 보고서에서 내보낸 `## APPROVAL` sidecar 를 감지하면 approve-confirm 단계가 3-옵션(`yes_apply` 내보낸 기록대로 승인+옵션 적용 추천 / `yes` 승인만 / `no` 중단)으로 확장된다 — `yes_apply` 는 옵션을 plan 의 `optionCandidates` 에 대해 검증한 뒤 기존 승인·옵션 경로로 적용한다,
 - `release-handoff`-only sub-flow: approved plan 자동 해소 후 `handoff_stage_pick` 멀티선택 — eligible stage 묶음(stage-group) 또는 전체 task(accepted whole-task 검증 보고서 존재 시) 선택; 결과는 render-args 의 `stages` 키(csv, whole-task 면 빈 값)로 나간다,
 - `Use defaults / Customize` branch with profile-aware worker/model questions,
+- **resume-clarification (in-session 등가)** — 셸의 `okstra.sh --resume-clarification` 에 대응하는 별도 모드나 플래그는 없고, 표준 흐름의 두 단계가 그 실질을 수행한다. (1) `reuse_previous` (직전 run 설정 재사용 예/아니오 — `requirements-discovery` / `error-analysis` / `implementation-planning` 에서, 직전 run-inputs 가 있을 때만): YES 면 워커·모델·directive·related-tasks 를 한 번에 prefill 한다. (2) `clarification_pick`: 재실행하는 **task-type 자신의** 직전 `final-report` 가 있으면 그것을 carry-in 입력으로 자동 추천하고(없으면 전체 phase 중 mtime 최신으로 폴백), 같은 run 의 `user-responses/` 사이드카(사용자가 채운 답변)를 함께 첨부한다. 선택된 경로는 prepare 의 `--clarification-response` 로 전달된다 — 사용자는 보고서의 `Export user response` 로 사이드카를 만들어 `runs/<task-type>/user-responses/` 에 둔 뒤 같은 phase 를 다시 실행하면 된다,
 - `release-handoff` PR template override + persist scope,
 - final `Proceed / Edit` confirmation; on `Edit` the wizard asks which step to rewind to and clears every later answer.
 

package/runtime/templates/reports/final-report.template.md

@@ -67,6 +67,18 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 | Approval Required? | `{% if verdictCard.approvalRequired %}yes — {{ t("verdictCard.approvalRequiredSuffix") }}{% else %}no{% endif %}` |
 | Next Step | {{ verdictCard.nextStep | mdcell }} |
 
+## {{ t("rationale.heading") }}
+
+{{ t("rationale.intro") }}
+
+**{{ t("rationale.motivationLabel") }}** — {{ rationale.motivation }}
+
+**{{ t("rationale.problemLabel") }}** — {{ rationale.problem }}
+
+**{{ t("rationale.approachLabel") }}** — {{ rationale.approach }}
+
+**{{ t("rationale.justificationLabel") }}** — {{ rationale.justification }}
+
 ## 1. Clarification Items
 
 {{ t("sectionIntro.clarificationItems") }}

package/runtime/templates/reports/i18n/en.json

@@ -62,6 +62,14 @@
     "rationaleLabel": "Rationale summary",
     "nextStepLabel": "Next step"
   },
+  "rationale": {
+    "heading": "Background and Rationale",
+    "intro": "Why this work, what it changes, and why the chosen approach is sound — written so a reviewer can follow it. Each item cites its evidence (path:line, report ID, etc.).",
+    "motivationLabel": "Why this work",
+    "problemLabel": "Why it is a problem",
+    "approachLabel": "What work is needed",
+    "justificationLabel": "Why this is the reasonable choice"
+  },
   "ticketCoverage": {
     "intro": "The tickets this run covered, with the sections and related items where each ticket appears.",
     "columnSections": "Sections",

package/runtime/templates/reports/i18n/ko.json

@@ -62,6 +62,14 @@
     "rationaleLabel": "근거 요약",
     "nextStepLabel": "다음 단계"
   },
+  "rationale": {
+    "heading": "작업 배경과 근거",
+    "intro": "이 작업을 왜·무엇을·왜 그렇게 하는지 검토자가 따라갈 수 있도록 정리한다. 각 항목은 근거(파일:줄, 보고서 ID 등)를 인용한다.",
+    "motivationLabel": "왜 이 작업을 하는가",
+    "problemLabel": "왜 이게 문제인가",
+    "approachLabel": "그래서 어떤 작업이 필요한가",
+    "justificationLabel": "왜 이게 합리적 선택인가"
+  },
   "ticketCoverage": {
     "intro": "이 run 이 다룬 ticket 과, 각 ticket 이 등장한 섹션·관련 항목 목록입니다.",
     "columnSections": "등장 섹션",

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/runtime/validators/validate-run.py

@@ -1462,10 +1462,50 @@ def validate_final_report_data(report_path: Path, failures: list[str]) -> None:
     for err in errors:
         failures.append(f"final-report data.json: {err}")
 
+    _validate_rationale_evidence(data, failures)
+
     if (data.get("header") or {}).get("taskType") == "final-verification":
         _validate_final_verification_consistency(data, failures)
 
 
+# path:line (foo.service.ts:268), report ID (C-001 / F-013 / G-crit-002 / RC-1),
+# or a section reference (§5.4) — any one satisfies "this claim is anchored".
+_EVIDENCE_TOKEN = re.compile(
+    r"[\w./-]+\.\w+:\d+|\b[A-Z]{1,3}(?:-[a-z]+)?-\d+\b|§\s*\d")
+# Explicit "I don't know" escapes — anti-fabrication's other valid answer.
+_INSUFFICIENCY_MARKERS = (
+    "근거 불충분", "근거가 불충분", "증거 불충분", "증거가 불충분",
+    "증거 없음", "증거가 없", "모름", "알 수 없", "확인 불가",
+    "i don't know", "unknown", "insufficient evidence", "no evidence",
+)
+_RATIONALE_FIELDS = ("motivation", "problem", "approach", "justification")
+
+
+def _validate_rationale_evidence(data: dict, failures: list[str]) -> None:
+    """Every `## 작업 배경과 근거` field must anchor its claim: carry at least
+    one evidence reference (path:line, report ID, §section) OR an explicit
+    insufficiency marker. Neither present → unverifiable narrative, which is
+    the fabrication the section exists to prevent. Schema guarantees the
+    fields are present and non-empty; this enforces they are *grounded*."""
+    rationale = data.get("rationale")
+    if not isinstance(rationale, dict):
+        return  # absence/shape is the schema's job; don't double-report.
+    for field in _RATIONALE_FIELDS:
+        text = rationale.get(field)
+        if not isinstance(text, str):
+            continue
+        if _EVIDENCE_TOKEN.search(text):
+            continue
+        if any(m in text.lower() for m in _INSUFFICIENCY_MARKERS):
+            continue
+        failures.append(
+            f"final-report data.json: rationale.{field} cites no evidence "
+            f"(expected a path:line, a report ID like C-001/F-013, or a §"
+            f"section reference) and gives no explicit insufficiency marker "
+            f"(e.g. '근거 불충분'). Anchor the claim or state what is unknown."
+        )
+
+
 def _validate_final_verification_consistency(data: dict, failures: list[str]) -> None:
     """Enforce verdict ↔ blocker/condition/routing consistency on the
     final-verification data.json (SSOT). The schema guarantees field SHAPE;

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",