npm - okstra - Versions diffs - 0.72.0 → 0.74.0 - Mend

okstra 0.72.0 → 0.74.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (44) hide show

package/runtime/python/okstra_ctl/report_views.py CHANGED Viewed

@@ -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
@@ -109,6 +118,8 @@ def render_html(src_md: str, *, run_meta: RunMeta, css: str, js: str) -> str:
     title = html.escape(f"{run_meta.task_key} — {run_meta.task_type} #{run_meta.seq}")
     response_ids_json = "[" + ",".join('"' + html.escape(rid) + '"' for rid in response_ids) + "]"
+    sidecar_name = html.escape(f"user-response-{run_meta.task_type}-{run_meta.seq}.md")
+    sidecar_dir = html.escape(f"runs/{run_meta.task_type}/user-responses/")
     return (
         f"<!DOCTYPE html>\n"
@@ -125,8 +136,11 @@ 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> 가 다운로드됩니다 — "
+        f"<code>{sidecar_dir}</code> 에 저장하면 resume-clarification 이 자동으로 첨부합니다.</p>\n"
         f"  <pre id=\"user-response-output\" aria-live=\"polite\"></pre>\n"
         f"  <button type=\"button\" data-action=\"copy-user-response\">Copy</button>\n"
         f"</footer>\n"
@@ -317,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
@@ -353,6 +375,10 @@ def _emit_table(lines: list[str], start: int, section_path: list[str]) -> tuple[
         (j for j, h in enumerate(header_cells) if h.startswith("Statement")),
         -1,
     )
+    expected_form_col = next(
+        (j for j, h in enumerate(header_cells) if h.startswith("Expected form")),
+        -1,
+    )
     user_input_col = (
         header_cells.index("User input") if "User input" in header_cells else -1
     )
@@ -367,11 +393,14 @@ def _emit_table(lines: list[str], start: int, section_path: list[str]) -> tuple[
             statement = (
                 row[statement_col] if 0 <= statement_col < len(row) else ""
             )
+            expected_form = (
+                row[expected_form_col] if 0 <= expected_form_col < len(row) else ""
+            )
             cells_html: list[str] = []
             for idx, cell in enumerate(row):
                 if idx == user_input_col:
                     cells_html.append(
-                        f"<td>{_form_control(meta.row_id, meta.kind, meta.status, cell, statement)}</td>"
+                        f"<td>{_form_control(meta.row_id, meta.kind, meta.status, cell, statement, expected_form)}</td>"
                     )
                 else:
                     cells_html.append(
@@ -439,12 +468,51 @@ def _parse_enum_options(statement: str) -> list[tuple[str, str]]:
     return out if len(out) >= 2 else []
+_RECOMMENDED_CUE = "Recommended:"
+_ALTERNATIVES_CUE = "Alternatives:"
+def _parse_expected_form_options(expected_form: str) -> list[tuple[str, str]]:
+    """Parse the ``Expected form`` contract format
+    (``Recommended: <answer> — <rationale>; Alternatives: <options>``,
+    `_common-contract.md` §Clarification request policy) into select
+    ``(value, label)`` options. Returns ``[]`` when the cell carries no
+    ``Recommended:`` cue — the caller falls back to the statement enum."""
+    if not expected_form:
+        return []
+    rec_idx = expected_form.find(_RECOMMENDED_CUE)
+    if rec_idx < 0:
+        return []
+    rec_body = expected_form[rec_idx + len(_RECOMMENDED_CUE):]
+    alt_body = ""
+    alt_idx = rec_body.find(_ALTERNATIVES_CUE)
+    if alt_idx >= 0:
+        alt_body = rec_body[alt_idx + len(_ALTERNATIVES_CUE):]
+        rec_body = rec_body[:alt_idx]
+    # The rationale follows " — "; the option keeps only the answer part.
+    answer = rec_body.split(" — ", 1)[0].strip(" .,;—-")
+    options: list[tuple[str, str]] = []
+    if answer:
+        options.append(("recommended", f"추천: {answer}"))
+    enum_alts = _parse_enum_options(alt_body)
+    if enum_alts:
+        options.extend(
+            (letter, f"({letter}) {text}") for letter, text in enum_alts
+        )
+    else:
+        alt_text = alt_body.strip(" .,;—-")
+        if alt_text:
+            options.append(("alternative", alt_text))
+    return options
 def _form_control(
     response_id: str,
     kind: str,
     status: str,
     current_value: str,
     statement: str = "",
+    expected_form: str = "",
 ) -> str:
     rid = html.escape(response_id)
     disabled = "" if status.lower() in ("open", "answered", "") else " disabled"
@@ -456,14 +524,21 @@ def _form_control(
         "data-point": "값",
     }.get(kind_lc, "응답")
-    # decision 인 경우 statement 에서 (a)(b)(c) 후보를 추출해 select+기타 input 으로 렌더.
+    # decision 의 후보는 Expected form 의 `Recommended: …; Alternatives: …`
+    # 계약(_common-contract.md §Clarification request policy)이 1순위,
+    # statement 안 (a)(b)(c) 열거가 fallback. 후보가 있으면 select+기타 input.
     if kind_lc == "decision":
-        opts = _parse_enum_options(statement)
+        opts = _parse_expected_form_options(expected_form)
+        if not opts:
+            opts = [
+                (letter, f"({letter}) {text}")
+                for letter, text in _parse_enum_options(statement)
+            ]
         if opts:
             select_opts = "".join(
-                f'<option value="{letter}">'
-                f'{_inline(f"({letter}) " + text)}</option>'
-                for letter, text in opts
+                f'<option value="{html.escape(value)}">'
+                f"{_inline(label)}</option>"
+                for value, label in opts
             )
             select_html = (
                 f'<select name="{rid}" data-response-id="{rid}" '
@@ -563,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)
@@ -577,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.
@@ -588,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
@@ -640,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
@@ -663,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 = (
@@ -674,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)
@@ -697,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,
     *,
@@ -705,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/run.py CHANGED Viewed

@@ -30,7 +30,7 @@ from okstra_project import project_json_path, upsert_project_json
 from okstra_project.state import slugify
 from . import fix_cycles
 from .analysis_packet import build_analysis_packet
-from .clarification_items import scan_approval_gate
+from .clarification_items import clarification_response_with_sidecars, scan_approval_gate
 from .qa_commands import format_errors as _format_qa_errors, validate_qa_commands
 from .material import (
     build_analysis_material,
@@ -1776,9 +1776,9 @@ def _write_instruction_set_sources(
     (instruction_set / "analysis-material.md").write_text(review_material, encoding="utf-8")
     shutil.copyfile(inp.brief_path, instruction_set / "task-brief.md")
     if inp.clarification_response_path:
-        shutil.copyfile(
-            inp.clarification_response_path,
-            instruction_set / "clarification-response.md",
+        (instruction_set / "clarification-response.md").write_text(
+            clarification_response_with_sidecars(Path(inp.clarification_response_path)),
+            encoding="utf-8",
         )
     if inp.directive:
         (instruction_set / "directive.txt").write_text(inp.directive + "\n", encoding="utf-8")

package/runtime/python/okstra_ctl/user_response.py ADDED Viewed

@@ -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 CHANGED Viewed

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