okstra 0.164.0 → 0.165.0

package/runtime/python/okstra_ctl/report_html/common.py

@@ -5,21 +5,36 @@ import re
 
 
 # Every block whose rows prose cites but no section of its own renders, with
-# the keys each one names its content and its provenance by. A key hunt across
-# all of them would misread `crossVerification.consensus`, whose `evidence` key
-# holds provenance while `evidence.primary` uses the same word for content —
-# so the block a row came from is named here rather than guessed.
+# the keys each one names its content, its provenance, and its confidence by. A
+# key hunt across all of them would misread `crossVerification.consensus`, whose
+# `evidence` key holds provenance while `evidence.primary` uses the same word
+# for content — so the block a row came from is named here rather than guessed.
+#
+# Source and confidence are separate columns because most blocks carry only one
+# of the two: `evidence.primary` cites a file and never rates itself, while
+# `evidence.secondary` rates itself and cites nothing. Folding them into one
+# field is what made the ledger label every row "source · confidence" and then
+# print a single value under it.
+#
+# `endStateCoverage` is deliberately absent. Its rows hold an id pair
+# (`EB-001` covered by `R-001`) rather than a statement, so the ledger rendered
+# them as an id with no body, and the requirement-coverage table already names
+# every one of them in its Source column.
+#
+# The kind each row carries is a vocabulary key, not the words the reader sees:
+# the labels live in the i18n `ledgerKind` table so they arrive in the reader's
+# language. `evidence.primary` was previously stamped "unclassified", which
+# named the renderer's own indecision rather than anything about the row.
 _LEDGER_BLOCKS = (
-    (("evidence", "primary"), "evidence", "source", "unclassified"),
-    (("evidence", "secondary"), "hypothesis", "confidence", "hypothesis"),
-    (("analysisCommon", "confirmedFacts"), "statement", "", "confirmed fact"),
-    (("analysisCommon", "inferences"), "statement", "confidence", "inference"),
-    (("analysisCommon", "unknowns"), "question", "reason", "unknown"),
-    (("crossVerification", "consensus"), "statement", "evidence", "cross-check consensus"),
-    (("crossVerification", "differences"), "disagreement", "workersPosition", "cross-check dissent"),
-    (("missingInformation",), "item", "risk", "missing information"),
-    (("endStateCoverage",), "coveredBy", "evidence", "exit contract"),
-    (("followUpTasks",), "title", "reason", "follow-up"),
+    (("evidence", "primary"), "evidence", "source", "", "code-evidence"),
+    (("evidence", "secondary"), "hypothesis", "", "confidence", "hypothesis"),
+    (("analysisCommon", "confirmedFacts"), "statement", "", "", "confirmed-fact"),
+    (("analysisCommon", "inferences"), "statement", "", "confidence", "inference"),
+    (("analysisCommon", "unknowns"), "question", "reason", "", "unknown"),
+    (("crossVerification", "consensus"), "statement", "evidence", "", "cross-check-consensus"),
+    (("crossVerification", "differences"), "disagreement", "workersPosition", "", "cross-check-dissent"),
+    (("missingInformation",), "item", "risk", "", "missing-information"),
+    (("followUpTasks",), "title", "reason", "", "follow-up"),
 )
 
 
@@ -32,23 +47,39 @@ def _dig(data: dict, path: tuple[str, ...]) -> list:
     return node if isinstance(node, list) else []
 
 
-def _ledger_row(row: dict, text_key: str, source_key: str, kind: str) -> dict[str, object]:
+def _joined(value: object) -> str:
+    """One reader-facing string for a cell a block may fill with either a
+    sentence or a list of citations. `str()` on a list prints Python's own
+    repr — quotes, brackets and all — straight into the report.
+    """
+    if isinstance(value, (list, tuple)):
+        return " · ".join(str(item) for item in value if item)
+    return str(value or "")
+
+
+def _ledger_row(
+    row: dict, text_key: str, source_key: str, confidence_key: str, kind: str
+) -> dict[str, object]:
     return {
         "id": row.get("id", ""),
         "kind": kind,
-        "text": str(row.get(text_key) or ""),
+        "text": _joined(row.get(text_key)),
         "codeEvidence": row.get("currentCodeEvidence") or [],
-        "source": str(row.get(source_key) or "") if source_key else "",
+        "source": _joined(row.get(source_key)) if source_key else "",
+        "confidence": _joined(row.get(confidence_key)) if confidence_key else "",
     }
 
 
-def _own_section_ids(data: dict) -> set[str]:
+def _own_section_ids(data: dict, omitted_fields: tuple[str, ...] = ()) -> set[str]:
     """Ids a section of the report already renders and anchors.
 
     The ledger is the fallback home for a cited row, so it must not claim an id
     that has one — two elements with the same anchor send half the links to the
     wrong place. `crossVerification.consensus` numbers its rows `C-001` in some
     runs, exactly where a clarification lives.
+
+    `omitted_fields` names task-block fields the HTML template does not render,
+    so their ids do not count as anchored.
     """
     from ..report_contract import TASK_TYPE_DATA_PROPERTY
 
@@ -56,20 +87,34 @@ def _own_section_ids(data: dict) -> set[str]:
     _collect_ids(data.get("clarificationItems", []), found)
     property_name = TASK_TYPE_DATA_PROPERTY.get(data.get("header", {}).get("taskType", ""))
     if property_name:
-        _collect_ids(data.get(property_name, {}), found)
+        block = data.get(property_name, {})
+        if omitted_fields and isinstance(block, dict):
+            block = {
+                key: value for key, value in block.items() if key not in omitted_fields
+            }
+        _collect_ids(block, found)
     return found
 
 
 def evidence_index(data: dict) -> dict[str, object]:
+    """The rows the ledger carries, keyed by id.
+
+    A row whose statement came out empty is dropped rather than listed: the
+    ledger exists so a cited id resolves to something the reader can read, and
+    an id above a blank line resolves to nothing.
+    """
     owned = _own_section_ids(data)
     rows: dict[str, object] = {}
-    for path, text_key, source_key, kind in _LEDGER_BLOCKS:
+    for path, text_key, source_key, confidence_key, kind in _LEDGER_BLOCKS:
         for row in _dig(data, path):
             if not isinstance(row, dict):
                 continue
             row_id = row.get("id")
-            if row_id and row_id not in owned and row_id not in rows:
-                rows[row_id] = _ledger_row(row, text_key, source_key, kind)
+            if not row_id or row_id in owned or row_id in rows:
+                continue
+            entry = _ledger_row(row, text_key, source_key, confidence_key, kind)
+            if entry["text"]:
+                rows[row_id] = entry
     return rows
 
 
@@ -88,7 +133,7 @@ def _collect_ids(value: object, found: set[str]) -> None:
 _ROW_ID = re.compile(r"[A-Z]{1,3}-\d+")
 
 
-def anchor_index(data: dict) -> dict[str, str]:
+def anchor_index(data: dict, omitted_fields: tuple[str, ...] = ()) -> dict[str, str]:
     """Map every row a reader can reach to the anchor name that lands on it.
 
     Prose cites ids across section boundaries — a hotspot names a
@@ -98,9 +143,10 @@ def anchor_index(data: dict) -> dict[str, str]:
 
     It stops there. `summary` is the AI-facing digest and
     `analysisCommon.scope` describes the analysis target rather than listing
-    rows; neither renders, so a link to one would land nowhere.
+    rows; neither renders, so a link to one would land nowhere. Same for the
+    blocks a template declares in `omitted_fields`.
     """
-    found = _own_section_ids(data) | set(evidence_index(data))
+    found = _own_section_ids(data, omitted_fields) | set(evidence_index(data))
     return {row_id: f"id-{row_id}" for row_id in sorted(found) if _ROW_ID.fullmatch(row_id)}
 
 

package/runtime/python/okstra_ctl/report_html/models.py

@@ -66,6 +66,11 @@ class HumanReportView:
     template_name: str
     context: dict[str, object]
     figures: tuple[FigureModel, ...]
+    # Task-block fields this template leaves out of the HTML. Their rows still
+    # exist in the data and the markdown, so prose keeps citing their ids — but
+    # an anchor to a row this document never renders scrolls nowhere, which
+    # reads as a broken report rather than as a deliberate omission.
+    omitted_fields: tuple[str, ...] = ()
 
 
 @dataclass(frozen=True)

package/runtime/python/okstra_ctl/report_html/render.py

@@ -130,7 +130,7 @@ def render_v2_html_view(
     env.policies["json.dumps_kwargs"] = {"sort_keys": True, "ensure_ascii": False}
     # Binding the index here is what lets a template cite an id without
     # threading the index through every macro and call site.
-    anchors = anchor_index(data)
+    anchors = anchor_index(data, view.omitted_fields)
     chrome = load_dictionary(lang, HTML_DICTIONARY_REL)
     translate = make_jinja_global(chrome)
     env.globals["t"] = translate

package/runtime/python/okstra_ctl/report_html/run_usage.py

@@ -23,6 +23,7 @@ def _totals_row(row: object) -> dict[str, str]:
     values = row if isinstance(row, dict) else {}
     return {
         "rawTokens": format_int(values.get("totalTokens")),
+        "cacheReadTokens": format_int(values.get("cacheReadTokens")),
         "billableTokens": format_int(values.get("billableTokens")),
         "cost": format_usd(values.get("costUsd")),
     }
@@ -43,6 +44,7 @@ def _agent_row(row: dict) -> dict[str, str]:
         "model": str(row.get("model") or ""),
         "status": str(row.get("status") or ""),
         "rawTokens": format_int(row.get("totalTokens")),
+        "cacheReadTokens": format_int(row.get("cacheReadTokens")),
         "billableTokens": format_int(row.get("billableTokens")),
         "cost": format_usd(row.get("costUsd")),
         "duration": format_duration_ms(row.get("durationMs")),
@@ -70,15 +72,31 @@ def _unaccounted(rows: list[dict], grand: dict) -> dict[str, str] | None:
     gap = grand_tokens - _sum(rows, "totalTokens")
     if gap <= 0:
         return None
+    cache_gap = (_number(grand.get("cacheReadTokens")) or 0) - _sum(rows, "cacheReadTokens")
     billable_gap = (_number(grand.get("billableTokens")) or 0) - _sum(rows, "billableTokens")
     cost_gap = (_number(grand.get("costUsd")) or 0) - _sum(rows, "costUsd")
     return {
         "rawTokens": format_int(gap),
+        "cacheReadTokens": format_int(max(0, cache_gap)),
         "billableTokens": format_int(max(0, billable_gap)),
         "cost": format_usd(max(0.0, cost_gap)),
     }
 
 
+def _task_cumulative(row: object) -> dict[str, str] | None:
+    """What the task has spent over every run, when more than this one exists.
+
+    A single-run task would repeat the grand total word for word, and a reader
+    seeing the same figure twice reads it as a second charge.
+    """
+    if not isinstance(row, dict):
+        return None
+    run_count = _number(row.get("runCount")) or 0
+    if run_count < 2:
+        return None
+    return {**_totals_row(row), "runCount": format_int(run_count)}
+
+
 _MEASURED_KEYS = ("totalTokens", "billableTokens", "costUsd", "durationMs")
 
 
@@ -106,5 +124,6 @@ def run_usage(data: dict) -> dict[str, object] | None:
         "rows": [_agent_row(row) for row in rows],
         "unaccounted": _unaccounted(rows, usage.get("grand") or {}),
         **totals,
+        "taskCumulative": _task_cumulative(usage.get("taskCumulative")),
         "cliCost": format_usd(cli_cost) if cli_cost else "",
     }

package/runtime/python/okstra_ctl/report_html/view_models/implementation_planning.py

@@ -74,6 +74,19 @@ def _stage_figure(planning: dict):
     return stage_map_figure(nodes=nodes, edges=edges, title="Implementation stage dependencies")
 
 
+# Blocks the approver's view leaves to the markdown report: the checklist the
+# implementer works from, the dependency and rollback tables an incident reader
+# needs, and the verification rounds the audit trail keeps. Declared here so the
+# ids they carry stop being anchor targets in this document.
+_OMITTED_FIELDS = (
+    "validationChecklist",
+    "crossProjectDependencies",
+    "dependencyMigrationRisk",
+    "rollbackStrategy",
+    "planBodyVerification",
+)
+
+
 def build_implementation_planning_view(data: dict) -> HumanReportView:
     planning = data["implementationPlanning"]
     figure = _stage_figure(planning)
@@ -97,4 +110,5 @@ def build_implementation_planning_view(data: dict) -> HumanReportView:
         "html/tasks/implementation-planning.template.html",
         context,
         (figure,),
+        _OMITTED_FIELDS,
     )

package/runtime/python/okstra_ctl/report_views.py

@@ -1050,11 +1050,16 @@ class UserResponseEntry:
 
 
 @dataclass(frozen=True)
-class UserResponseApproval:
-    """HTML Plan Approval 위젯의 Export 결과. ``implementation_option`` 이 빈
-    문자열이면 라인을 생략한다 (소비 측은 Recommended Option 폴백)."""
-    approved: bool
+class UserPlanDecision:
+    """HTML 계획 결정 위젯의 Export 결과.
+
+    ``status`` 가 승인이 아니면 ``reason`` 이 필수다 — 사유 없는 반려는 다음
+    run 이 무엇을 고쳐야 하는지 알 수 없어 되돌아올 수밖에 없다.
+    ``implementation_option`` 이 빈 문자열이면 라인을 생략한다 (소비 측은
+    Recommended Option 폴백)."""
+    status: str
     implementation_option: str = ""
+    reason: str = ""
 
 
 @dataclass(frozen=True)
@@ -1072,6 +1077,13 @@ _ANALYSIS_REVIEW_STATUSES = frozenset({
     "rejected",
 })
 
+PLAN_DECISION_APPROVED = "approved"
+_PLAN_DECISION_STATUSES = frozenset({
+    PLAN_DECISION_APPROVED,
+    "revision-requested",
+    "rejected",
+})
+
 
 def _quoted_sidecar_field(label: str, value: str) -> str:
     cleaned = value.strip()
@@ -1100,12 +1112,25 @@ def _serialize_analysis_review(review: UserResponseAnalysisReview) -> str:
     )
 
 
+def _serialize_plan_decision(decision: UserPlanDecision) -> str:
+    if decision.status not in _PLAN_DECISION_STATUSES:
+        raise ValueError(f"invalid PLAN DECISION status: {decision.status}")
+    if decision.status != PLAN_DECISION_APPROVED and not decision.reason.strip():
+        raise ValueError(f"PLAN DECISION {decision.status} requires a Reason")
+    chunk = f"\n## PLAN DECISION\n- Status: {decision.status}\n"
+    if decision.implementation_option:
+        chunk += f"- Implementation-Option: {decision.implementation_option.strip()}\n"
+    if decision.reason.strip():
+        chunk += _quoted_sidecar_field("Reason", decision.reason)
+    return chunk
+
+
 def serialize_user_response(
     *,
     run_meta: RunMeta,
     entries: list[UserResponseEntry],
     created_at: str,
-    approval: UserResponseApproval | None = None,
+    plan_decision: UserPlanDecision | None = None,
     analysis_review: UserResponseAnalysisReview | None = None,
 ) -> str:
     """Return the canonical markdown text the HTML 'Export user
@@ -1125,7 +1150,7 @@ def serialize_user_response(
         "\n"
         "# User Response\n"
     )
-    has_approval = approval is not None and approval.approved
+    has_plan_decision = plan_decision is not None
     has_analysis_review = analysis_review is not None
     body_chunks: list[str] = []
     for e in entries:
@@ -1137,13 +1162,10 @@ def serialize_user_response(
         if e.rationale:
             chunk += f"- Rationale: {e.rationale.strip()}\n"
         body_chunks.append(chunk)
-    if not entries and not has_approval and not has_analysis_review:
+    if not entries and not has_plan_decision and not has_analysis_review:
         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)
+    if plan_decision is not None:
+        body_chunks.append(_serialize_plan_decision(plan_decision))
     if analysis_review is not None:
         body_chunks.append(_serialize_analysis_review(analysis_review))
     return head + "".join(body_chunks)
@@ -1369,11 +1391,17 @@ def _plan_approval_section(ctx: PlanApprovalContext, run_meta: RunMeta) -> str:
     )
     return (
         '<section id="plan-approval">\n'
-        "  <h2>Plan Approval</h2>\n"
+        "  <h2>Plan Decision</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>"
+        '  <fieldset id="plan-decision"><legend>판정</legend>'
+        f'<label><input type="radio" name="plan-decision-status" value="approved"{disabled}> '
+        "이 plan 을 승인합니다</label>"
+        '<label><input type="radio" name="plan-decision-status" '
+        'value="revision-requested"> 고쳐서 다시 가져오게 합니다</label>'
+        '<label><input type="radio" name="plan-decision-status" value="rejected"> '
+        "이 plan 을 반려합니다</label></fieldset>\n"
+        '  <label>사유 — 반려하거나 다시 고치게 할 때는 반드시 적어야 합니다'
+        '<textarea id="plan-decision-reason" rows="4"></textarea></label>'
         f"{reason_html}\n"
         "</section>\n"
     )

package/runtime/python/okstra_ctl/stage_citations.py

@@ -9,6 +9,7 @@ which decides whether a re-run narrows or stays full.
 from __future__ import annotations
 
 import re
+from collections.abc import Iterator
 
 _RANGE = r"(?:[-–]|\bto\b|\bthrough\b)"
 _ITEM = rf"\d+(?:\s*{_RANGE}\s*\d+)?"
@@ -23,25 +24,61 @@ _ITEM_RE = re.compile(rf"(\d+)(?:\s*{_RANGE}\s*(\d+))?", re.IGNORECASE)
 RANGE_MAX_SPAN = 64
 
 
+def _stage_citation_items(text: str) -> Iterator[tuple[int, int | None]]:
+    """Each `stage`-anchored citation in *text* as `(start, end)`.
+
+    *end* is None for a bare number and the far endpoint for a range. Numbers
+    stay anchored to a word-initial `stage`/`stages` token on the same line;
+    harvesting bare numbers — or letting the anchor reach across a line break,
+    or match the tail of `Substage`/`Backstage` — would let any prose, including
+    a row disclaiming every stage, justify any stage.
+    """
+    for span in _LIST_RE.finditer(text):
+        for item in _ITEM_RE.finditer(span.group(1)):
+            end = item.group(2)
+            yield int(item.group(1)), int(end) if end is not None else None
+
+
 def cited_stage_numbers(text: str) -> set[int]:
     """Stage numbers *text* cites, in every prose form a planner writes.
 
-    Numbers stay anchored to a word-initial `stage`/`stages` token on the same
-    line; harvesting bare numbers — or letting the anchor reach across a line
-    break, or match the tail of `Substage`/`Backstage` — would let any prose,
-    including a row disclaiming every stage, justify any stage.
+    A range reaches every number between its endpoints here, which is what a
+    reader asking "could this touch stage 5" needs.
     """
     cited: set[int] = set()
+    for start, end in _stage_citation_items(text):
+        cited.add(start)
+        if end is None:
+            continue
+        cited.add(end)
+        # A reversed or absurdly wide range is a typo, not a citation of
+        # everything between its endpoints.
+        if 0 <= end - start <= RANGE_MAX_SPAN:
+            cited.update(range(start, end))
+    return cited
+
+
+def enumerated_stage_numbers(text: str) -> set[int]:
+    """Stage numbers *text* names one by one — a range's interior excluded.
+
+    The two readers of this grammar ask opposite questions, and a range answers
+    only one of them. The incremental-scope back-trace asks "could this answer
+    reach stage 5", so it must read `Stages 1-8` as reaching it — that is
+    `cited_stage_numbers`, and widening there is the safe direction. Coverage
+    provenance asks "did the planner confirm stage 5 satisfies this
+    requirement", and a range answers that for free: one `Stages 1-64` cell
+    stamps every stage in the map without the planner looking at any of them.
+
+    So the interior is dropped here and only hand-written numbers count. A
+    range's endpoints ARE hand-written and stay, which keeps `Stages 7-8`
+    honest while forcing the wide case to be spelled out. The cost of a
+    legitimately broad requirement is typing each number, and that typing is
+    the confirmation this check is asking for.
+    """
+    enumerated: set[int] = set()
     for span in _LIST_RE.finditer(text):
         for item in _ITEM_RE.finditer(span.group(1)):
-            start = int(item.group(1))
-            cited.add(start)
-            if item.group(2) is None:
-                continue
-            end = int(item.group(2))
-            cited.add(end)
-            # A reversed or absurdly wide range is a typo, not a citation of
-            # everything between its endpoints.
-            if 0 <= end - start <= RANGE_MAX_SPAN:
-                cited.update(range(start, end))
-    return cited
+            enumerated.add(int(item.group(1)))
+            if item.group(2) is not None:
+                enumerated.add(int(item.group(2)))
+    return enumerated

package/runtime/python/okstra_ctl/user_response.py

@@ -3,7 +3,7 @@
 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 used by the implementation wizard and the optional
+the ``## PLAN DECISION`` block used by the implementation wizard and the optional
 ``## ANALYSIS REVIEW`` block used by analysis reruns.
 """
 from __future__ import annotations
@@ -19,7 +19,8 @@ from pathlib import Path
 from typing import Optional
 
 from okstra_ctl.report_views import (
-    serialize_user_response, UserResponseEntry, UserResponseApproval, infer_run_meta,
+    PLAN_DECISION_APPROVED,
+    serialize_user_response, UserResponseEntry, UserPlanDecision, infer_run_meta,
     parse_expected_form_options,
 )
 from okstra_ctl.report_view_artifacts import user_responses_dir_for_report
@@ -32,7 +33,7 @@ from okstra_ctl.clarification_items import (
     _section_1_slice,
 )
 
-_APPROVAL_HEADING_RE = re.compile(r"^## APPROVAL\s*$", re.MULTILINE)
+_PLAN_DECISION_HEADING_RE = re.compile(r"^## PLAN DECISION\s*$", re.MULTILINE)
 _NEXT_RESPONSE_HEADING_RE = re.compile(r"^## ", re.MULTILINE)
 _ANALYSIS_REVIEW_HEADING_RE = re.compile(r"^## ANALYSIS REVIEW\s*$", re.MULTILINE)
 _ANALYSIS_SIDECAR_HEADING_RE = re.compile(
@@ -50,13 +51,18 @@ class UserResponseError(ValueError):
 
 
 @dataclass(frozen=True)
-class UserResponseApprovalRecord:
-    """sidecar 의 ``## APPROVAL`` 블록 + 매칭에 필요한 frontmatter 필드."""
-    approved: bool
+class PlanDecisionRecord:
+    """sidecar 의 ``## PLAN DECISION`` 블록 + 매칭에 필요한 frontmatter 필드."""
+    status: str
     implementation_option: str
+    reason: str
     source_report: str
     seq: str
 
+    @property
+    def approved(self) -> bool:
+        return self.status == PLAN_DECISION_APPROVED
+
 
 @dataclass(frozen=True)
 class AnalysisReviewRecord:
@@ -353,31 +359,37 @@ def load_authoritative_analysis_review(
     return review
 
 
-def parse_user_response_approval(
-    sidecar_text: str,
-) -> Optional[UserResponseApprovalRecord]:
-    """``## APPROVAL`` 블록이 ``- Approved: true`` 를 가질 때만 record 를
-    반환한다. 옵션 라인은 블록 내부에서만 읽는다 (다른 응답 본문의 우연한
-    동일 문구를 옵션으로 오인하지 않도록).
+_PLAN_DECISION_STATUS_RE = re.compile(
+    r"^- Status:\s*(approved|revision-requested|rejected)\s*$", re.MULTILINE
+)
+
+
+def parse_plan_decision(sidecar_text: str) -> Optional[PlanDecisionRecord]:
+    """``## PLAN DECISION`` 블록을 읽어 record 로 돌려준다. 승인·재작업·반려를
+    구분하지 않고 그대로 싣는다 — 어느 판정을 받아들일지는 소비 측 정책이다.
+    옵션·사유 라인은 블록 내부에서만 읽는다 (다른 응답 본문의 우연한 동일
+    문구를 옵션으로 오인하지 않도록).
 
-    strictness 는 의도적이다: producer 출력과 byte-identical 한 소문자
-    ``true`` 만 인정하며, 손편집 변형(``TRUE``/``True``)은 fail-closed 로
+    strictness 는 의도적이다: producer 출력과 byte-identical 한 소문자 status
+    만 인정하며, 손편집 변형(``Approved``/``REJECTED``)은 fail-closed 로
     불인정한다."""
-    m = _APPROVAL_HEADING_RE.search(sidecar_text)
+    m = _PLAN_DECISION_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:
+    status = _PLAN_DECISION_STATUS_RE.search(block)
+    if status 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,
+    return PlanDecisionRecord(
+        status=status.group(1),
         implementation_option=om.group(1) if om else "",
+        reason=_quoted_review_value(block, "Reason"),
         source_report=rm.group(1) if rm else "",
         seq=sm.group(1) if sm else "",
     )
@@ -404,8 +416,8 @@ def _value(block: str) -> str:
 
 def parse_user_response_entries(sidecar_text: str) -> list[UserResponseEntry]:
     """Reverse of ``serialize_user_response`` for the per-response ``## C-*``
-    blocks. The ``## APPROVAL`` block is skipped (read separately by
-    ``parse_user_response_approval``)."""
+    blocks. The ``## PLAN DECISION`` block is skipped (read separately by
+    ``parse_plan_decision``)."""
     entries: list[UserResponseEntry] = []
     matches = list(_RESPONSE_HEADING_RE.finditer(sidecar_text))
     for i, m in enumerate(matches):
@@ -581,7 +593,7 @@ def show_open_rows(report_path: Path) -> dict:
 
 
 def write_sidecar(report_path: Path, answers: list[dict],
-                  approval: Optional[dict], created_at: str,
+                  plan_decision: Optional[dict], created_at: str,
                   task_key: str = "") -> Path:
     run_meta = infer_run_meta(report_path, task_key=task_key or None)
     out_dir = user_responses_dir_for_report(report_path)
@@ -597,13 +609,15 @@ def write_sidecar(report_path: Path, answers: list[dict],
             response_id=a["id"], kind=a.get("kind", ""), value=a["value"],
             rationale=a.get("rationale"), disposition=a.get("disposition", "answer"))
 
-    appr = None
-    if approval and approval.get("approved"):
-        appr = UserResponseApproval(
-            approved=True, implementation_option=approval.get("implementationOption", ""))
+    decision = None
+    if plan_decision and plan_decision.get("status"):
+        decision = UserPlanDecision(
+            status=plan_decision["status"],
+            implementation_option=plan_decision.get("implementationOption", ""),
+            reason=plan_decision.get("reason", ""))
     sidecar.write_text(
         serialize_user_response(run_meta=run_meta, entries=list(merged.values()),
-                                created_at=created_at, approval=appr),
+                                created_at=created_at, plan_decision=decision),
         encoding="utf-8")
     return sidecar
 
@@ -623,7 +637,9 @@ def main(argv: Optional[list[str]] = None) -> int:
     pw = sub.add_parser("write")
     pw.add_argument("--report", required=True)
     pw.add_argument("--answers", required=True, help="JSON array of answer entries")
-    pw.add_argument("--approval", default="", help="JSON approval object")
+    pw.add_argument(
+        "--plan-decision", default="",
+        help='JSON plan decision, e.g. {"status":"rejected","reason":"..."}')
     pw.add_argument("--task-key", default="", help="task-key from list/show context")
 
     ns = parser.parse_args(argv)
@@ -636,9 +652,9 @@ def main(argv: Optional[list[str]] = None) -> int:
         return 0
     if ns.cmd == "write":
         answers = json.loads(ns.answers)
-        approval = json.loads(ns.approval) if ns.approval else None
+        decision = json.loads(ns.plan_decision) if ns.plan_decision else None
         created_at = dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-        p = write_sidecar(Path(ns.report), answers, approval, created_at,
+        p = write_sidecar(Path(ns.report), answers, decision, created_at,
                           task_key=ns.task_key)
         json.dump({"sidecar": str(p)}, sys.stdout, ensure_ascii=False)
         return 0