okstra 0.73.0 → 0.74.0

package/runtime/python/okstra_ctl/report_views.py

@@ -22,6 +22,7 @@ from __future__ import annotations
 
 import hashlib
 import html
+import json
 import re
 from dataclasses import dataclass
 from pathlib import Path
@@ -56,12 +57,13 @@ def _strip_leading_frontmatter(text: str) -> str:
     return _LEADING_FRONTMATTER_RE.sub("", text, count=1)
 
 from .clarification_items import (
-    _is_separator_row,
     _section_1_slice,
     _split_pipe_row,
     parse_clarification_items,
     parse_meta_cell,
+    scan_approval_gate,
 )
+from .md_table import is_separator_row as _is_separator_row
 
 
 # --------------------------------------------------------------------------- #
@@ -91,7 +93,14 @@ class RunMeta:
     source_report: str  # relative path of the .md the HTML is derived from
 
 
-def render_html(src_md: str, *, run_meta: RunMeta, css: str, js: str) -> str:
+def render_html(
+    src_md: str,
+    *,
+    run_meta: RunMeta,
+    css: str,
+    js: str,
+    approval_ctx: PlanApprovalContext | None = None,
+) -> str:
     """Return a single self-contained HTML document for ``src_md``.
 
     ``css`` / ``js`` are inlined verbatim. No external URLs are written
@@ -127,6 +136,7 @@ def render_html(src_md: str, *, run_meta: RunMeta, css: str, js: str) -> str:
         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"<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> 가 다운로드됩니다 — "
@@ -321,7 +331,15 @@ def _emit_table(lines: list[str], start: int, section_path: list[str]) -> tuple[
     rows: list[list[str]] = []
     i = start + 2  # skip header + separator
     while i < len(lines) and lines[i].lstrip().startswith("|"):
-        rows.append(_split_pipe_row(lines[i]))
+        cells = _split_pipe_row(lines[i])
+        # A row with more cells than the header means an unescaped `|`
+        # inside cell text (the writer should have used `\|`). Merge the
+        # overflow back into the last header column instead of spilling
+        # extra <td>s outside the table border.
+        if len(cells) > len(header_cells):
+            keep = len(header_cells) - 1
+            cells = cells[:keep] + ["|".join(cells[keep:])]
+        rows.append(cells)
         i += 1
 
     # §1 Clarification Items is the only interactive table. Its short columns
@@ -620,6 +638,22 @@ def _plain_len(raw_cell: str) -> int:
     return len(_INLINE_MD_STRIP_RE.sub("", raw_cell or "").strip())
 
 
+# Under report.css `td.td-narrow { white-space: nowrap }` a cell's longest
+# <br>-separated line dictates the column's intrinsic width. Lines past half
+# of `main`'s 120ch budget would crush or push the prose neighbours off-screen,
+# so such a column must not be pinned narrow even when its header is
+# whitelisted.
+_NARROW_WHITELIST_MAX_LINE_LEN = 60
+_BR_TAG_RE = re.compile(r"<br\s*/?\s*>", re.IGNORECASE)
+
+
+def _max_plain_line_len(raw_cell: str) -> int:
+    return max(
+        (_plain_len(segment) for segment in _BR_TAG_RE.split(raw_cell or "")),
+        default=0,
+    )
+
+
 def _matches_narrow_whitelist(header: str) -> bool:
     plain = _INLINE_MD_STRIP_RE.sub("", header or "").strip().lower()
     return any(plain.startswith(p) for p in _NARROW_HEADER_PREFIXES)
@@ -634,8 +668,11 @@ def _narrow_columns(
     A column qualifies when EITHER:
       (a) its header matches `_NARROW_HEADER_PREFIXES` — these are
           ``ID`` / ``출처`` / ``에이전트`` etc. whose values are
-          conventionally short across every final-report even when a
-          single row drops in 60+ chars of prose; OR
+          conventionally short (or <br>-stacked into short lines) across
+          every final-report — UNLESS some cell carries a single line
+          longer than ``_NARROW_WHITELIST_MAX_LINE_LEN``: nowrap would
+          let that line dictate the column width and starve the prose
+          neighbours; OR
       (b) every cell in the column (header + body) fits within
           ``_NARROW_COL_MAX_PLAIN_LEN`` plain chars — this catches
           ad-hoc short columns that the whitelist did not anticipate.
@@ -645,14 +682,13 @@ def _narrow_columns(
     """
     narrow: set[int] = set()
     for col, header in enumerate(header_cells):
+        column_cells = [header] + [row[col] for row in rows if col < len(row)]
         if _matches_narrow_whitelist(header):
-            narrow.add(col)
+            longest_line = max(_max_plain_line_len(c) for c in column_cells)
+            if longest_line <= _NARROW_WHITELIST_MAX_LINE_LEN:
+                narrow.add(col)
             continue
-        max_len = _plain_len(header)
-        for row in rows:
-            if col < len(row):
-                max_len = max(max_len, _plain_len(row[col]))
-        if max_len <= _NARROW_COL_MAX_PLAIN_LEN:
+        if max(_plain_len(c) for c in column_cells) <= _NARROW_COL_MAX_PLAIN_LEN:
             narrow.add(col)
     return narrow
 
@@ -697,11 +733,20 @@ class UserResponseEntry:
     rationale: Optional[str] = None
 
 
+@dataclass(frozen=True)
+class UserResponseApproval:
+    """HTML Plan Approval 위젯의 Export 결과. ``implementation_option`` 이 빈
+    문자열이면 라인을 생략한다 (소비 측은 Recommended Option 폴백)."""
+    approved: bool
+    implementation_option: str = ""
+
+
 def serialize_user_response(
     *,
     run_meta: RunMeta,
     entries: list[UserResponseEntry],
     created_at: str,
+    approval: UserResponseApproval | None = None,
 ) -> str:
     """Return the canonical markdown text the HTML 'Export user
     response' button must produce. Used by validators to confirm that
@@ -720,6 +765,7 @@ def serialize_user_response(
         "\n"
         "# User Response\n"
     )
+    has_approval = approval is not None and approval.approved
     body_chunks: list[str] = []
     for e in entries:
         chunk = (
@@ -731,8 +777,13 @@ def serialize_user_response(
         if e.rationale:
             chunk += f"- Rationale: {e.rationale.strip()}\n"
         body_chunks.append(chunk)
-    if not entries:
+    if not entries and not has_approval:
         body_chunks.append("\n_(No user responses recorded.)_\n")
+    if has_approval:
+        chunk = "\n## APPROVAL\n- Approved: true\n"
+        if approval.implementation_option:
+            chunk += f"- Implementation-Option: {approval.implementation_option.strip()}\n"
+        body_chunks.append(chunk)
     return head + "".join(body_chunks)
 
 
@@ -754,6 +805,86 @@ def report_has_clarification_items(src_md: str) -> bool:
     )
 
 
+@dataclass(frozen=True)
+class PlanApprovalContext:
+    """Plan Approval 위젯 렌더 입력. ``disabled_reason`` 이 비어 있지 않으면
+    위젯은 disabled 로 렌더된다 (run-prep 승인 게이트와 동일한 fail-closed 기준)."""
+    option_names: tuple[str, ...]
+    recommended_option: str
+    disabled_reason: str
+
+
+def plan_approval_context(
+    src_md_path: Path, src_text: str
+) -> PlanApprovalContext | None:
+    """implementation-planning 보고서 + sibling data.json 의 optionCandidates 가
+    있을 때만 컨텍스트를 만든다. planning 여부는 task-type 문자열이 아니라
+    data.json 의 ``implementationPlanning`` 키(SSOT)로 판정한다 — renderer 와
+    validator 가 같은 판정을 공유한다. recommendedOption 이 비거나 후보에 없으면
+    첫 후보로 폴백한다 — 항상 정확히 한 옵션이 selected 가 되어 브라우저 자동선택분의
+    묵시 Export 를 차단한다."""
+    data_path = src_md_path.with_name(src_md_path.stem + ".data.json")
+    if not data_path.is_file():
+        return None
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        return None
+    names = tuple(
+        c.get("name", "")
+        for c in (planning.get("optionCandidates") or [])
+        if isinstance(c, dict) and c.get("name")
+    )
+    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]
+    scan = scan_approval_gate(src_text)
+    if scan.unreadable_reason:
+        reason = "§1 승인 게이트를 읽을 수 없어 승인이 비활성화되었습니다 — 보고서를 재렌더하세요."
+    elif scan.blockers:
+        reason = (
+            f"§1 승인 차단 항목 {len(scan.blockers)}건 미해소 — 답변을 채워 Export 한 뒤 "
+            "resume-clarification 으로 해소한 다음 보고서에서 승인하세요."
+        )
+    else:
+        reason = ""
+    return PlanApprovalContext(
+        option_names=names, recommended_option=recommended, disabled_reason=reason
+    )
+
+
+def _plan_approval_section(ctx: PlanApprovalContext) -> str:
+    disabled = " disabled" if ctx.disabled_reason else ""
+    opts: list[str] = []
+    for name in ctx.option_names:
+        is_rec = name == ctx.recommended_option
+        label = f"{name} (권장)" if is_rec else name
+        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 ""
+    )
+    return (
+        '<section id="plan-approval">\n'
+        "  <h2>Plan Approval</h2>\n"
+        f'  <label>구현 옵션: <select id="approval-option"{disabled}>{"".join(opts)}</select></label>\n'
+        f'  <label><input type="checkbox" id="approval-checkbox"{disabled}> '
+        "이 plan 을 승인합니다 — Export 시 sidecar 에 APPROVAL 블록으로 기록되고, "
+        "implementation 시작 마법사가 확인 후 적용합니다.</label>"
+        f"{reason_html}\n"
+        "</section>\n"
+    )
+
+
 def render_html_view(
     src_md_path: Path,
     *,
@@ -762,19 +893,23 @@ def render_html_view(
     js: str,
 ) -> Path | None:
     """Write ``<stem>.html`` next to ``src_md_path`` and return its path,
-    or return ``None`` when generation is skipped because the report has
-    no §1 clarification rows (see ``report_has_clarification_items``).
+    or return ``None`` when the report needs no interactive view — §1
+    clarification rows 도 없고 Plan Approval 위젯 대상도 아닐 때
+    (``report_has_clarification_items`` / ``plan_approval_context``).
     Idempotent — overwrites an existing html sibling, and removes a stale
-    one when a previously-clarification-bearing report no longer has rows."""
+    one when the report no longer needs a view."""
     src_text = src_md_path.read_text(encoding="utf-8")
     html_path = src_md_path.with_name(src_md_path.stem + ".html")
-    if not report_has_clarification_items(src_text):
-        # Conditional generation: no interactive forms to render. Drop any
-        # stale html left over from a prior clarification-bearing run so the
-        # validator's "no rows → no html" branch stays consistent.
+    approval_ctx = plan_approval_context(src_md_path, src_text)
+    if not report_has_clarification_items(src_text) and approval_ctx is None:
         if html_path.is_file():
             html_path.unlink()
         return None
-    html_text = render_html(src_text, run_meta=run_meta, css=css, js=js)
+    html_text = render_html(
+        src_text, run_meta=run_meta, css=css, js=js, approval_ctx=approval_ctx
+    )
     html_path.write_text(html_text, encoding="utf-8")
+    # 사용자 확인(폼/승인)이 필요한 보고서 — Export 파일의 저장 위치를 미리
+    # 만들어 사용자가 디렉토리를 만들 필요가 없게 한다 (reports/ 의 sibling).
+    (src_md_path.parent.parent / "user-responses").mkdir(parents=True, exist_ok=True)
     return html_path

package/runtime/python/okstra_ctl/user_response.py

@@ -0,0 +1,55 @@
+"""Parse the user-response sidecar files exported from the final-report HTML view.
+
+The sidecar format is documented in ``templates/reports/user-response.template.md``
+and produced byte-identically by ``report_views.serialize_user_response`` (Python)
+and ``templates/reports/report.js`` (browser). This module owns the read side of
+the ``## APPROVAL`` block — the implementation wizard consumes it to offer
+"승인 + 옵션 적용" at the approve-confirm step.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+_APPROVAL_HEADING_RE = re.compile(r"^## APPROVAL\s*$", re.MULTILINE)
+_NEXT_RESPONSE_HEADING_RE = re.compile(r"^## ", re.MULTILINE)
+
+
+@dataclass(frozen=True)
+class UserResponseApprovalRecord:
+    """sidecar 의 ``## APPROVAL`` 블록 + 매칭에 필요한 frontmatter 필드."""
+    approved: bool
+    implementation_option: str
+    source_report: str
+    seq: str
+
+
+def parse_user_response_approval(
+    sidecar_text: str,
+) -> Optional[UserResponseApprovalRecord]:
+    """``## APPROVAL`` 블록이 ``- Approved: true`` 를 가질 때만 record 를
+    반환한다. 옵션 라인은 블록 내부에서만 읽는다 (다른 응답 본문의 우연한
+    동일 문구를 옵션으로 오인하지 않도록).
+
+    strictness 는 의도적이다: producer 출력과 byte-identical 한 소문자
+    ``true`` 만 인정하며, 손편집 변형(``TRUE``/``True``)은 fail-closed 로
+    불인정한다."""
+    m = _APPROVAL_HEADING_RE.search(sidecar_text)
+    if not m:
+        return None
+    block = sidecar_text[m.end():]
+    nxt = _NEXT_RESPONSE_HEADING_RE.search(block)
+    if nxt:
+        block = block[: nxt.start()]
+    if re.search(r"^- Approved:\s*true\s*$", block, re.MULTILINE) is None:
+        return None
+    om = re.search(r"^- Implementation-Option:\s*(\S.*?)\s*$", block, re.MULTILINE)
+    sm = re.search(r"^seq:\s*(\S+)\s*$", sidecar_text, re.MULTILINE)
+    rm = re.search(r"^source-report:\s*(\S.*?)\s*$", sidecar_text, re.MULTILINE)
+    return UserResponseApprovalRecord(
+        approved=True,
+        implementation_option=om.group(1) if om else "",
+        source_report=rm.group(1) if rm else "",
+        seq=sm.group(1) if sm else "",
+    )

package/runtime/python/okstra_ctl/wizard.py

@@ -35,12 +35,18 @@ from okstra_ctl.clarification_items import scan_approval_gate
 from okstra_ctl.pr_template import PrTemplateError, resolve_pr_template_path
 from okstra_ctl.run import (
     APPROVED_FRONTMATTER_PATTERN,
+    PrepareError,
+    _apply_cli_implementation_option,
     _extract_frontmatter_block,
     _load_final_report_data_if_present,
     _reject_blocking_plan_body_gate,
     _set_data_json_approved_true_if_present,
     _validate_data_json_approval_consistency,
 )
+from okstra_ctl.user_response import (
+    UserResponseApprovalRecord,
+    parse_user_response_approval,
+)
 from okstra_ctl.workers import (
     ALLOWED_WORKERS,
     WorkersError,
@@ -341,6 +347,11 @@ class WizardState:
     # A plan that is approvable (gate ok, no blockers) but not yet `approved`.
     # Set when the user selects such a plan; the approve-confirm step reads it.
     approve_plan_candidate: str = ""
+    # HTML Plan Approval 위젯이 남긴 sidecar 감지 결과. 선택된 plan 과
+    # source-report·seq 가 일치하는 APPROVAL 블록이 있을 때만 채워지고,
+    # approve-confirm 단계가 3-옵션(yes_apply/yes/no)으로 확장된다.
+    html_approval_sidecar: str = ""
+    html_approval_option: str = ""
     selected_stage: str = "auto"
     executor: str = ""
     critic: str = ""
@@ -553,6 +564,58 @@ def _approve_plan_in_place(plan_path: Path) -> None:
     plan_path.write_text(flipped, encoding="utf-8")
 
 
+def _find_html_approval_sidecar(
+    plan_path: Path,
+) -> Optional[tuple[Path, UserResponseApprovalRecord]]:
+    """plan 의 run 디렉토리 sibling ``user-responses/`` 에서 APPROVAL 블록을
+    가진 sidecar 를 찾는다. source-report 파일명과 seq 가 plan 과 일치해야
+    하며, 복수면 mtime 최신을 택한다."""
+    responses_dir = plan_path.parent.parent / "user-responses"
+    if not responses_dir.is_dir():
+        return None
+    m = re.search(r"-(\d+)\.md$", plan_path.name)
+    plan_seq = m.group(1) if m else ""
+    best: Optional[tuple[float, Path, UserResponseApprovalRecord]] = None
+    for f in sorted(responses_dir.glob("user-response-*.md")):
+        try:
+            text = f.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        rec = parse_user_response_approval(text)
+        if rec is None or rec.seq != plan_seq:
+            continue
+        if Path(rec.source_report).name != plan_path.name:
+            continue
+        mtime = f.stat().st_mtime
+        if best is None or mtime > best[0]:
+            best = (mtime, f, rec)
+    return (best[1], best[2]) if best else None
+
+
+def _validate_sidecar_option(plan_path: Path, option_name: str, errors_t: dict) -> None:
+    """sidecar 의 옵션 이름이 plan data.json 의 optionCandidates 에 있는지
+    검증한다. 없으면 유효 후보를 나열하며 거부한다 (fail-closed)."""
+    data_path = plan_path.with_name(plan_path.name[: -len(".md")] + ".data.json")
+    candidates: list[str] = []
+    if data_path.is_file():
+        try:
+            data = json.loads(data_path.read_text(encoding="utf-8"))
+            planning = data.get("implementationPlanning") or {}
+            candidates = [
+                c.get("name", "") for c in planning.get("optionCandidates") or []
+                if isinstance(c, dict) and c.get("name")
+            ]
+        except (OSError, json.JSONDecodeError):
+            candidates = []
+    if option_name not in candidates:
+        raise WizardError(
+            errors_t["unknown_option"].format(
+                option=option_name,
+                candidates=", ".join(candidates) if candidates else "(없음)",
+            )
+        )
+
+
 def _stage_plan_for_confirmation(
     state: WizardState, path_str: str, *, suffix: str = ""
 ) -> Optional[str]:
@@ -564,6 +627,13 @@ def _stage_plan_for_confirmation(
     state.approved_plan_pending_text = False
     state.approved_plan_path = ""
     state.approve_plan_candidate = str(p)
+    state.html_approval_sidecar = ""
+    state.html_approval_option = ""
+    found = _find_html_approval_sidecar(p)
+    if found is not None:
+        sidecar_path, record = found
+        state.html_approval_sidecar = str(sidecar_path)
+        state.html_approval_option = record.implementation_option
     t = _p(state.workspace_root, "approve_plan_confirm", path=str(p))
     msg = t["echo_variants"]["selected"].format(path=p)
     return f"{msg} {suffix}".rstrip() if suffix else msg
@@ -711,6 +781,10 @@ def _p(workspace_root: str, step_id: str, **vars: str) -> dict:
         "label": label,
         "echo_template": raw.get("echo_template", ""),
         "options": raw.get("options", {}),
+        "options_html_approval": raw.get("options_html_approval", {}),
+        "html_approval_note": raw.get("html_approval_note", ""),
+        "html_approval_note_default_option": raw.get(
+            "html_approval_note_default_option", ""),
         "echo_variants": raw.get("echo_variants", {}),
         "errors": raw.get("errors", {}),
         "labels": raw.get("labels", {}),
@@ -1605,17 +1679,27 @@ def _submit_approved_plan(state: WizardState, value: str) -> Optional[str]:
 def _build_approve_plan_confirm(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "approve_plan_confirm",
            path=state.approve_plan_candidate)
+    label = t["label"]
+    options_map = t["options"]
+    if state.html_approval_sidecar:
+        label += t["html_approval_note"].format(
+            sidecar=state.html_approval_sidecar,
+            option=state.html_approval_option
+            or t["html_approval_note_default_option"],
+        )
+        options_map = t["options_html_approval"]
     return Prompt(
         step=S_APPROVE_PLAN_CONFIRM, kind="pick",
-        label=t["label"],
-        options=[_opt(k, v) for k, v in t["options"].items()],
+        label=label,
+        options=[_opt(k, v) for k, v in options_map.items()],
         echo_template=t["echo_template"],
     )
 
 
 def _submit_approve_plan_confirm(state: WizardState, value: str) -> Optional[str]:
-    if value not in ("yes", "no"):
-        raise WizardError(f"expected 'yes' or 'no', got: {value!r}")
+    allowed = ("yes_apply", "yes", "no") if state.html_approval_sidecar else ("yes", "no")
+    if value not in allowed:
+        raise WizardError(f"expected one of {allowed}, got: {value!r}")
     candidate = state.approve_plan_candidate
     if not candidate:
         raise WizardError("approve-plan: no candidate plan to approve")
@@ -1624,19 +1708,39 @@ def _submit_approve_plan_confirm(state: WizardState, value: str) -> Optional[str
         # Declining leaves the candidate set so the confirm step re-prompts;
         # implementation cannot proceed without choosing to proceed.
         raise WizardError(t["errors"]["declined"])
+    apply_option = value == "yes_apply" and bool(state.html_approval_option)
     p = Path(candidate)
+    if apply_option:
+        # 승인 플립 전에 옵션 유효성부터 검증한다 — 무효 옵션으로 plan 이
+        # 절반만(승인만) 적용되는 상태를 만들지 않는다.
+        _validate_sidecar_option(p, state.html_approval_option, t["errors"])
     resolved, fully_approved = _classify_approved_plan(
         str(p), Path(state.project_root))
-    if not fully_approved:
-        # Not yet approved → flip data.json (SSOT) + re-render, then re-verify.
-        _approve_plan_in_place(p)
-        resolved, fully_approved = _classify_approved_plan(
-            str(p), Path(state.project_root))
+    # flip / 옵션 적용은 PrepareError 를 던질 수 있는데, 마법사 디스패처는
+    # WizardError 만 재프롬프트로 처리한다. raw PrepareError 가 새면 (승인이
+    # 디스크에 반영된 채) state 저장 없이 traceback 으로 죽으므로 여기서 번역한다.
+    try:
         if not fully_approved:
-            raise WizardError(t["errors"]["still_unapproved"].format(path=resolved))
+            # Not yet approved → flip data.json (SSOT) + re-render, then re-verify.
+            _approve_plan_in_place(p)
+            resolved, fully_approved = _classify_approved_plan(
+                str(p), Path(state.project_root))
+            if not fully_approved:
+                raise WizardError(
+                    t["errors"]["still_unapproved"].format(path=resolved))
+        echo = t["echo_variants"]["approved"].format(path=resolved)
+        if apply_option:
+            _apply_cli_implementation_option(
+                str(resolved), state.html_approval_option)
+            echo = t["echo_variants"]["approved_with_option"].format(
+                path=resolved, option=state.html_approval_option)
+    except PrepareError as exc:
+        raise WizardError(str(exc)) from exc
     state.approved_plan_path = str(resolved)
     state.approve_plan_candidate = ""
-    return t["echo_variants"]["approved"].format(path=resolved)
+    state.html_approval_sidecar = ""
+    state.html_approval_option = ""
+    return echo
 
 
 def _build_stage_pick(state: WizardState) -> Prompt:
@@ -3005,6 +3109,7 @@ _FIELD_DEFAULTS: dict[str, Any] = {
     "reuse_worktree": None, "base_ref": "",
     "base_ref_pending_text": False, "approved_plan_path": "",
     "approved_plan_pending_text": False, "approve_plan_candidate": "",
+    "html_approval_sidecar": "", "html_approval_option": "",
     "selected_stage": "auto",
     "handoff_mode": "", "handoff_stages": "",
     "executor": "", "critic": "", "critic_pending_text": False,

package/runtime/python/okstra_token_usage/collect.py

@@ -26,9 +26,11 @@ def match_prefixes(worker_id: str) -> list[str]:
     `-reverify-r1`, `-impl`, `-2`) when it dispatches the same role multiple
     times or in different sub-flows. We treat every `agentName` matching one of
     these prefixes — either exactly or as `<prefix>-<suffix>` — as belonging
-    to this worker so its tokens get aggregated. For implementation runs the
-    executor variant `<provider>-executor` is also attributed back to the
-    matching provider worker.
+    to this worker so its tokens get aggregated. For implementation /
+    final-verification runs the role variants `<provider>-executor` and
+    `<provider>-verifier` are also attributed back to the matching provider
+    worker (the bare `<provider>` prefix's `<prefix>-<suffix>` match covers
+    any role suffix Lead assigns).
     """
     if not worker_id:
         return []

package/runtime/skills/okstra-report-writer/SKILL.md

@@ -105,8 +105,9 @@ The four steps below MUST execute in this exact order. Reordering them is the re
    ```
 
    Output (idempotent — re-running overwrites):
-   - `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — single-file self-contained human view, **generated only when the report has at least one §5 `C-*` clarification row**. Those rows with `Status` ∈ {`open`, `answered`} embed form widgets (`<select>` for enum-style decisions, `<input>` for material / data-point kinds, `<textarea>` fallback); an `Export user response` button serialises form values to a markdown sidecar (schema in [`templates/reports/user-response.template.md`](../../templates/reports/user-response.template.md)) and downloads it as `user-response-<task-type>-<seq>.md`; the user saves it to `runs/<task-type>/user-responses/`, and `--resume-clarification` auto-appends every sidecar found there to the next run's `clarification-response.md` (`clarification_items.clarification_response_with_sidecars`). The original final-report MD is **never** mutated by user input — the sidecar is the single write target.
-   - When the report has **no** `C-*` clarification rows, the html carries no interactive forms (it would only duplicate the MD), so the renderer prints `html: skipped (...)` and writes nothing. This is the expected state for clarification-free runs — `validators/validate-report-views.py` treats "no C-* rows + no html" as a pass, not a missing artifact.
+   - `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — single-file self-contained human view, **generated when the report has at least one §1 `C-*` clarification row OR an implementation-planning Plan Approval widget target** (a sibling `final-report-*.data.json` carrying `implementationPlanning.optionCandidates`). Clarification rows with `Status` ∈ {`open`, `answered`} embed form widgets (`<select>` for enum-style decisions, `<input>` for material / data-point kinds, `<textarea>` fallback); an `Export user response` button serialises form values to a markdown sidecar (schema in [`templates/reports/user-response.template.md`](../../templates/reports/user-response.template.md)) and downloads it as `user-response-<task-type>-<seq>.md`; the user saves it to `runs/<task-type>/user-responses/` (the renderer pre-creates that directory), and `--resume-clarification` auto-appends every sidecar found there to the next run's `clarification-response.md` (`clarification_items.clarification_response_with_sidecars`). The original final-report MD is **never** mutated by user input — the sidecar is the single write target.
+   - implementation-planning 보고서에는 본문 끝에 **Plan Approval** 섹션(구현 옵션 `<select>` + 승인 체크박스)이 렌더된다 — §1 `Blocks: approval` 행이 미해소면 disabled. 승인을 체크하고 Export 하면 sidecar 본문에 `## APPROVAL` 블록이 실리고, implementation 시작 마법사의 approve-confirm 단계가 그것을 감지해 사용자 확인 후 기존 `--approve` / `--implementation-option` 경로로 적용한다.
+   - When the report has **no** `C-*` clarification rows and is **not** a Plan Approval widget target, the html carries no interactive forms (it would only duplicate the MD), so the renderer prints `html: skipped (...)` and writes nothing. This is the expected state for such runs — `validators/validate-report-views.py` treats "no C-* rows + no approval target + no html" as a pass, not a missing artifact.
 
    Must run AFTER step 1 (so token placeholders are substituted in any rendered html) and BEFORE step 2 (so the html artifact, when generated, exists for the validator step that checks it).
 4. **Phase 7 step 2 — Follow-up task spawner** (BLOCKING when Section 4 is non-empty). Turns the report's `## 4. Follow-up Tasks (후속 작업)` rows into `tasks/<task-group>/<new-task-id>/` stubs.

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

@@ -123,7 +123,7 @@ That is the entire interactive flow. The wizard handles:
 - task-type pick (추천 3개 — `nextRecommendedPhase` recommended / 현재 phase 재실행 / 라이프사이클 다음 단계 — + 직접 입력; 직접 입력은 후속 `text` 단계에서 전체 task-type 화이트리스트로 검증),
 - brief path — **entry task-type(requirements-discovery / error-analysis / improvement-discovery)에서만 질문** (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, direct input last; `유지 / 변경` for existing entry tasks). downstream task-type 은 manifest 의 brief 를 자동 carry-in 하고, 등록 brief 가 없으면 `brief_carry` 3-옵션(entry 전환 추천 / 직접 입력 / 중단)이 뜬다. `release-handoff` 는 brief 단계가 아예 없다 — prepare 가 검증 보고서 인용 input 문서를 생성한다,
 - base-ref pick + git rev-parse validation (skipped when reusing an active worktree),
-- `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = 의존성 충족된 가장 빠른 미완료 stage, 또는 특정 stage 번호) + executor pick,
+- `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 가 일치하는 HTML `## APPROVAL` sidecar 를 감지하면 approve-confirm 단계가 3-옵션(`yes_apply` HTML 기록대로 승인+옵션 적용 추천 / `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,
 - `release-handoff` PR template override + persist scope,

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -323,7 +323,7 @@ without proceeding — this is the contractual replacement for the previous
 empty run-level error logs in production.
 
 - `cli-failure` events are recorded by the wrapper subagent itself (Codex / Gemini), but **directly to the run-level error log** via `okstra error-log append-observed --error-type cli-failure ...` — NOT via the sidecar. The sidecar is an in-process tool-failure channel only.
-- **Wrapper invocation arity.** Both `okstra-codex-exec.sh` and `okstra-gemini-exec.sh` accept four required positional arguments plus an optional fifth `<role>`: `<project-root> <model> <prompt-path> <worktree-path> [<role>]`. The fourth (worktree) argument is **mandatory for implementation phase** and optional otherwise. For codex it becomes `--add-dir <worktree>` (sandbox write access); for gemini it is appended to `--include-directories`. Omitting it during implementation causes the codex sandbox to reject every Edit/Write targeting the worktree with EPERM. Workers extract the path from the `**Worktree:**` / `EXECUTOR_WORKTREE_PATH` / `cwd for every mutating command:` line in the lead prompt. The optional fifth `<role>` is folded into both the caller (worker) pane title `<cli>-<role>-<pid>` and the sibling trace-pane title `<cli>-<role>-<pid>-trace[from=<caller-pane-id>]` (e.g. `codex-worker-93421` ↔ `codex-worker-93421-trace[from=%5]`). `<pid>` is the wrapper's own PID and disambiguates concurrent dispatches of the same role; the embedded caller pane id keeps the trace ↔ worker correlation visible even when the worker pane's title is overwritten by the parent process (Claude Code's TUI emits OSC 2 title escape sequences on its own pane). Always pass the literal string `worker` so the dispatch is self-describing (the wrapper defaults to `worker` if omitted).
+- **Wrapper invocation arity.** Both `okstra-codex-exec.sh` and `okstra-gemini-exec.sh` accept four required positional arguments plus an optional fifth `<role>`: `<project-root> <model> <prompt-path> <worktree-path> [<role>]`. The fourth (worktree) argument is **mandatory for implementation phase** and optional otherwise. For codex it becomes `--add-dir <worktree>` (sandbox write access); for gemini it is appended to `--include-directories`. Omitting it during implementation causes the codex sandbox to reject every Edit/Write targeting the worktree with EPERM. Workers extract the path from the `**Worktree:**` / `EXECUTOR_WORKTREE_PATH` / `cwd for every mutating command:` line in the lead prompt. The optional fifth `<role>` is folded into both the caller (worker) pane title `<cli>-<role>-<pid>` and the sibling trace-pane title `<cli>-<role>-<pid>-tail` (e.g. `codex-executor-93421` ↔ `codex-executor-93421-tail`). `<pid>` is the wrapper's own PID and disambiguates concurrent dispatches of the same role. The role value comes from the dispatch prompt's `**Pane role:**` line: `executor` on an `implementation` Executor dispatch, `verifier` on an `implementation` / `final-verification` verifier dispatch, so the trace pane names the actual job rather than a generic `worker`. When no `**Pane role:**` line is present (analysis phases), pass the literal `worker` (the wrapper also defaults to `worker` if the argument is omitted).
 - **Background dispatch + polling contract (Codex / Gemini wrappers).** Both wrapper subagents MUST dispatch `okstra-codex-exec.sh` / `okstra-gemini-exec.sh` via `Bash(run_in_background: true)` and poll with `BashOutput(bash_id)` until the shell reports `status == "completed"`, capped at 30 minutes (1800s) of wall-clock elapsed time. `BashOutput` itself is the wait primitive — call it back-to-back; do NOT insert a standalone `sleep` between polls. The Claude Code harness blocks `sleep` calls of 5 seconds or longer as a circumvention vector and explicitly forbids chaining shorter sleeps inside until-loops to work around the block. Workers that hit the contract bug must NOT self-recover with `until ...; do sleep 2; done` wrappers — that path violates the harness anti-circumvention rule, even though it superficially "works". The legacy "single foreground `Bash` with 120000ms timeout" rule, and the subsequent "60-second cadence with `sleep 60` between polls" rule, are both retired. The current rule applies in **every phase** (analysis runs typically complete in 1–2 `BashOutput` calls, so there is no regression for short jobs). Recording responsibilities:
   - Successful completion: return the wrapper's accumulated stdout from the final `BashOutput`. No log entry.
   - Non-zero `exit_code` reported by `BashOutput`: record a `cli-failure` to the run-level error log with the real `exit_code` and observed `duration-ms`.