okstra 0.186.7 → 0.188.0

package/runtime/python/okstra_ctl/user_response.py

@@ -40,6 +40,7 @@ from okstra_ctl.final_report_paths import (
     final_report_data_path,
     final_report_markdown_path,
     is_report_record_path,
+    sidecar_source_rel,
 )
 from okstra_ctl.json_boundary import (
     JsonBoundaryError,
@@ -55,6 +56,25 @@ from okstra_ctl.ids import slugify_task_segment
 from okstra_ctl.listing import list_runs, absolute_final_report_path
 from okstra_ctl.paths import resolve_under_root
 from okstra_ctl.run_context import dir_flock
+from .user_response_values import (  # noqa: F401 — 재노출
+    AnalysisReviewRecord,
+    UserResponseError,
+    _ANALYSIS_REVIEW_HEADING_RE,
+    _ANALYSIS_REVIEW_STATUSES,
+    _ANALYSIS_SIDECAR_HEADING_RE,
+    _FRONTMATTER_DELIMITER_RE,
+    _NEXT_RESPONSE_HEADING_RE,
+    _YAML_FRONTMATTER_RE,
+    _authoritative_analysis_review_match,
+    _field,
+    _nearest_frontmatter_value,
+    _nearest_sidecar_filename,
+    _parsed_created_at,
+    _quoted_review_value,
+    _sidecar_metadata_value,
+    parse_analysis_review,
+    parse_user_response_entries,
+)
 from okstra_ctl.clarification_items import (
     ClarificationItem,
     UNRESOLVED_STATUSES,
@@ -64,28 +84,12 @@ from okstra_ctl.clarification_items import (
 )
 
 _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)
 _DIRECTION_SELECTION_HEADING_RE = re.compile(
     r"^## DIRECTION SELECTION\s*$", re.MULTILINE
 )
 _REPORT_AUTHORING_HEADING_RE = re.compile(
     r"^## REPORT AUTHORING\s*$", re.MULTILINE
 )
-_ANALYSIS_SIDECAR_HEADING_RE = re.compile(
-    r"^## (?P<filename>user-response-[^\n]+\.md)\s*$", re.MULTILINE
-)
-_YAML_FRONTMATTER_RE = re.compile(
-    r"\A---[ \t]*\r?\n(?P<body>.*?)(?:\r?\n)---[ \t]*(?:\r?\n|\Z)",
-    re.DOTALL,
-)
-_FRONTMATTER_DELIMITER_RE = re.compile(r"^---[ \t]*$", re.MULTILINE)
-
-
-class UserResponseError(ValueError):
-    """Raised when a user-response sidecar violates its supported format."""
-
-
 @dataclass(frozen=True)
 class PlanDecisionRecord:
     """sidecar 의 ``## PLAN DECISION`` 블록 + 매칭에 필요한 frontmatter 필드."""
@@ -100,21 +104,6 @@ class PlanDecisionRecord:
         return self.status == PLAN_DECISION_APPROVED
 
 
-@dataclass(frozen=True)
-class AnalysisReviewRecord:
-    """Validated user review of an analysis report."""
-
-    status: str
-    affected_ids: tuple[str, ...]
-    reason: str
-    additional_evidence: str
-    requested_scope_change: str
-    task_key: str
-    task_type: str
-    source_report: str
-    seq: str
-
-
 @dataclass(frozen=True)
 class DirectionSelectionRecord:
     status: str
@@ -129,152 +118,12 @@ class DirectionSelectionRecord:
     seq: str
 
 
-_ANALYSIS_REVIEW_STATUSES = frozenset({
-    "accepted",
-    "revision-requested",
-    "rejected",
-})
 _ANALYSIS_REPORT_RE = re.compile(
     r"^final-report-(?P<task_type>project-analysis|feature-analysis|"
     r"change-impact-analysis)-(?P<seq>\d{3})\.(?:md|data\.json)$"
 )
 
 
-def _quoted_review_value(block: str, key: str) -> str:
-    match = re.search(
-        rf"^- {re.escape(key)}:\s*\n((?:\s*>.*\n?)+)", block, re.MULTILINE
-    )
-    if not match:
-        return ""
-    return "\n".join(
-        re.sub(r"^\s*>\s?", "", line)
-        for line in match.group(1).splitlines()
-    ).strip()
-
-
-def _sidecar_metadata_value(sidecar_text: str, key: str) -> str:
-    frontmatter = _YAML_FRONTMATTER_RE.match(sidecar_text)
-    if frontmatter is None:
-        return ""
-    match = re.search(
-        rf"^{re.escape(key)}:[ \t]*(\S.*?)[ \t]*$",
-        frontmatter.group("body"),
-        re.MULTILINE,
-    )
-    return match.group(1) if match else ""
-
-
-def _nearest_frontmatter_value(
-    sidecar_text: str, key: str, before_offset: int
-) -> str:
-    delimiters = [
-        match
-        for match in _FRONTMATTER_DELIMITER_RE.finditer(sidecar_text)
-        if match.start() < before_offset
-    ]
-    for opening, closing in reversed(list(zip(delimiters, delimiters[1:]))):
-        body = sidecar_text[opening.end():closing.start()]
-        match = re.search(
-            rf"^{re.escape(key)}:[ \t]*(\S.*?)[ \t]*$",
-            body,
-            re.MULTILINE,
-        )
-        if match:
-            return match.group(1)
-    return _sidecar_metadata_value(sidecar_text, key)
-
-
-def _parsed_created_at(value: str) -> dt.datetime | None:
-    if re.fullmatch(
-        r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z",
-        value,
-    ) is None:
-        return None
-    try:
-        parsed = dt.datetime.fromisoformat(value[:-1] + "+00:00")
-    except ValueError:
-        return None
-    if parsed.tzinfo is None:
-        return None
-    return parsed.astimezone(dt.timezone.utc)
-
-
-def _nearest_sidecar_filename(sidecar_text: str, before_offset: int) -> str:
-    headings = [
-        match
-        for match in _ANALYSIS_SIDECAR_HEADING_RE.finditer(sidecar_text)
-        if match.start() < before_offset
-    ]
-    return headings[-1].group("filename") if headings else ""
-
-
-def _authoritative_analysis_review_match(
-    sidecar_text: str, matches: list[re.Match[str]]
-) -> re.Match[str]:
-    candidates: list[tuple[dt.datetime, str, int, re.Match[str]]] = []
-    for match in matches:
-        created_at = _parsed_created_at(
-            _nearest_frontmatter_value(sidecar_text, "created-at", match.start())
-        )
-        if created_at is None:
-            continue
-        candidates.append((
-            created_at,
-            _nearest_sidecar_filename(sidecar_text, match.start()),
-            match.start(),
-            match,
-        ))
-    if not candidates:
-        raise UserResponseError(
-            "ANALYSIS REVIEW requires a valid canonical created-at"
-        )
-    return max(candidates, key=lambda candidate: candidate[:3])[3]
-
-
-def parse_analysis_review(sidecar_text: str) -> AnalysisReviewRecord | None:
-    """Parse the bounded ``## ANALYSIS REVIEW`` block from a sidecar.
-
-    A sidecar without this optional block is not a review.  Once the block is
-    present, status and the fields that make a rejection actionable are
-    validated fail-closed.
-    """
-    matches = list(_ANALYSIS_REVIEW_HEADING_RE.finditer(sidecar_text))
-    if not matches:
-        return None
-    match = _authoritative_analysis_review_match(sidecar_text, matches)
-    block = sidecar_text[match.end():]
-    next_heading = _NEXT_RESPONSE_HEADING_RE.search(block)
-    if next_heading:
-        block = block[:next_heading.start()]
-    status = _field(block, "Status")
-    if status not in _ANALYSIS_REVIEW_STATUSES:
-        raise UserResponseError("ANALYSIS REVIEW Status is invalid")
-    affected = _field(block, "Affected-IDs") or ""
-    affected_ids = tuple(item.strip() for item in affected.split(",") if item.strip())
-    reason = _quoted_review_value(block, "Reason")
-    if status in {"revision-requested", "rejected"} and (not affected_ids or not reason):
-        raise UserResponseError(
-            f"ANALYSIS REVIEW {status} requires Affected-IDs and Reason"
-        )
-    return AnalysisReviewRecord(
-        status=status,
-        affected_ids=affected_ids,
-        reason=reason,
-        additional_evidence=_quoted_review_value(block, "Additional-Evidence"),
-        requested_scope_change=_quoted_review_value(block, "Requested-Scope-Change"),
-        task_key=_nearest_frontmatter_value(
-            sidecar_text, "task-key", match.start()
-        ),
-        task_type=_nearest_frontmatter_value(
-            sidecar_text, "task-type", match.start()
-        ),
-        source_report=_nearest_frontmatter_value(
-            sidecar_text, "source-report", match.start()
-        ),
-        seq=_nearest_frontmatter_value(sidecar_text, "seq", match.start()),
-    )
-
-
 def _matching_analysis_review_sidecars(
     report_path: Path,
     sidecar_name: re.Pattern[str],
@@ -474,16 +323,6 @@ def parse_report_authoring(sidecar_text: str) -> UserReportAuthoring | None:
     return UserReportAuthoring(status=status, reason=reason)
 
 
-_RESPONSE_HEADING_RE = re.compile(r"^## (?P<id>[A-Za-z][A-Za-z0-9]*-\d+)\s*$", re.MULTILINE)
-
-
-def _field(block: str, key: str) -> Optional[str]:
-    m = re.search(
-        rf"^- {re.escape(key)}:[ \t]*(\S.*?)[ \t]*$", block, re.MULTILINE
-    )
-    return m.group(1) if m else None
-
-
 def _direction_identity_fields(block: str) -> tuple[str, str]:
     match = re.search(
         r"^- Option-ID:[ \t]*(?P<option_id>[^\r\n]*)\r?\n"
@@ -497,15 +336,6 @@ def _direction_identity_fields(block: str) -> tuple[str, str]:
     return match.group("option_id"), match.group("option_name")
 
 
-def _value(block: str) -> str:
-    # Value 는 "- Value:" 다음 줄들의 "  > " 인용 블록.
-    m = re.search(r"^- Value:\s*\n((?:\s*>.*\n?)+)", block, re.MULTILINE)
-    if not m:
-        return ""
-    lines = [re.sub(r"^\s*>\s?", "", ln) for ln in m.group(1).splitlines()]
-    return "\n".join(lines).strip()
-
-
 def parse_direction_selection(
     sidecar_text: str,
 ) -> DirectionSelectionRecord | None:
@@ -550,26 +380,6 @@ def parse_direction_selection(
     )
 
 
-def parse_user_response_entries(sidecar_text: str) -> list[UserResponseEntry]:
-    """Reverse of ``serialize_user_response`` for the per-response ``## C-*``
-    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):
-        end = matches[i + 1].start() if i + 1 < len(matches) else len(sidecar_text)
-        block = sidecar_text[m.end():end]
-        rationale = _field(block, "Rationale")
-        entries.append(UserResponseEntry(
-            response_id=m.group("id"),
-            kind=_field(block, "Kind") or "",
-            value=_value(block),
-            rationale=rationale,
-            disposition=_field(block, "Disposition") or "answer",
-        ))
-    return entries
-
-
 _SEQ_FROM_REPORT_RE = re.compile(
     r"final-report-.+-(\w+)\.(?:md|data\.json)$"
 )
@@ -633,9 +443,6 @@ def _load_report_record(
     return record
 
 
-def _relative_from_runs(path: Path) -> str:
-    indices = [index for index, part in enumerate(path.parts) if part == "runs"]
-    return Path(*path.parts[indices[-1]:]).as_posix() if indices else path.name
 
 
 def _record_identity(record: Mapping[str, Any]) -> tuple[str, str]:
@@ -678,7 +485,7 @@ def resolve_report_context(
         raise UserResponseError("report filename has no run sequence")
     run_root = resolved.parent.parent
     data_path = final_report_data_path(resolved) if record else None
-    source_data = _relative_from_runs(data_path) if data_path else ""
+    source_data = sidecar_source_rel(data_path) if data_path else ""
     task_type_root = run_root.parent if run_root.name.startswith("stage-") else run_root
     task_root = task_type_root.parent.parent
     project_root = task_root.parents[3] if len(task_root.parents) >= 4 else task_root
@@ -689,7 +496,7 @@ def resolve_report_context(
         task_key=task_key,
         task_type=task_type,
         seq=seq,
-        source_report=_relative_from_runs(markdown),
+        source_report=sidecar_source_rel(markdown),
         source_data=source_data,
         source_data_sha256=(
             hashlib.sha256(data_path.read_bytes()).hexdigest() if data_path else ""
@@ -764,9 +571,14 @@ def _validate_owned_report_context(
         raise UserResponseError("report resolves outside the selected project")
     _reject_symlinks_below(project_root, data_path, "report")
     markdown = _lexical_absolute(final_report_markdown_path(data_path))
+    # 읽기 사본(`.md`)은 on-demand 로만 렌더된다. 타입드 트랜잭션은 바로 아래에서
+    # 버전 있는 레코드를 요구하고, 그 경로는 `.md` 본문을 한 번도 읽지 않는다
+    # (schema-v1 만 `markdown_path` 를 읽으며, 그때 그 경로는 리포트 자신이다).
+    # 존재를 요구하면 `.md` 를 렌더한 적 없는 리포트의 응답 채널이 통째로 닫힌다.
+    # 경로는 sidecar 의 `source-report` 신원 문자열로만 쓰이므로 계산은 유지한다.
     _reject_symlinks_below(project_root, markdown, "report reading copy")
-    if not data_path.is_file() or not markdown.is_file():
-        raise UserResponseError("report record and reading copy must be regular files")
+    if not data_path.is_file():
+        raise UserResponseError("report record must be a regular file")
     record = _load_report_record(data_path, validate_schema=True)
     if record is None:
         raise UserResponseError("typed transactions require a versioned report record")
@@ -2283,8 +2095,33 @@ def _add_list_arguments(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--limit", type=int, default=3)
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra user-response list --home <dir> --project <id> [--limit <n>]
+  okstra user-response list-view --home <dir> --project <id> [--limit <n>]
+  okstra user-response show --report <md>
+  okstra user-response show-view --report <md|data.json> --project-root <dir>
+  okstra user-response begin --report <md|data.json> --task-key <key>
+  okstra user-response answer --transaction <id> --clarification-id <C-NNN> \
+    --kind <kind> --option-number <N>
+  okstra user-response answer --transaction <id> --clarification-id <C-NNN> \
+    --kind <kind> --disposition <value> --value-file <md> [--rationale-file <md>]
+  okstra user-response plan-decision --transaction <id> --status <value> \
+    [--implementation-option <name>] [--reason-file <md>]
+  okstra user-response legacy-report-authoring --transaction <id> \
+    --status <approved|denied> --reason-file <md>
+  okstra user-response finalize --transaction <id>
+
+Exit codes: 0 ok / 1 오류
+"""
+_CLI_DESCRIPTION = "\uc5f4\ub9b0 clarification\uc744 \uace0\uc815 \ud14d\uc2a4\ud2b8\ub85c \uc77d\uace0 sidecar \ud2b8\ub79c\uc7ad\uc158 \uae30\ub85d."
+
+
 def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="okstra user-response")
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra user-response")
     sub = parser.add_subparsers(dest="cmd", required=True)
     _add_list_arguments(sub.add_parser("list"))
     _add_list_arguments(sub.add_parser("list-view"))

package/runtime/python/okstra_ctl/user_response_values.py

@@ -0,0 +1,242 @@
+"""사용자 응답 사이드카의 값 타입과 파싱.
+
+`user_response`(2,383줄) 와 `report_views`(1,000줄+) 에 흩어져 있던
+자족적인 값·파싱 단위다. 어떤 사이드카를 분석
+리포트에 붙일지 고르는 `clarification_items._sidecars_for_attachment` 가
+`parse_analysis_review` 하나 때문에 `user_response` 전체를 함수 본문에서 지연
+import 해야 했다 — `user_response` 는 반대로 `clarification_items` 를 최상위에서
+끌어오기 때문이다.
+
+이 모듈은 표준 라이브러리 외에 아무것도 import 하지 않는다. `user_response` 가
+모든 이름을 재노출하므로 기존 호출부는 바뀌지 않는다.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+
+_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(
+    r"^## (?P<filename>user-response-[^\n]+\.md)\s*$", re.MULTILINE
+)
+
+_YAML_FRONTMATTER_RE = re.compile(
+    r"\A---[ \t]*\r?\n(?P<body>.*?)(?:\r?\n)---[ \t]*(?:\r?\n|\Z)",
+    re.DOTALL,
+)
+
+_FRONTMATTER_DELIMITER_RE = re.compile(r"^---[ \t]*$", re.MULTILINE)
+
+class UserResponseError(ValueError):
+    """Raised when a user-response sidecar violates its supported format."""
+
+@dataclass(frozen=True)
+class AnalysisReviewRecord:
+    """Validated user review of an analysis report."""
+
+    status: str
+    affected_ids: tuple[str, ...]
+    reason: str
+    additional_evidence: str
+    requested_scope_change: str
+    task_key: str
+    task_type: str
+    source_report: str
+    seq: str
+
+_ANALYSIS_REVIEW_STATUSES = frozenset({
+    "accepted",
+    "revision-requested",
+    "rejected",
+})
+
+def _quoted_review_value(block: str, key: str) -> str:
+    match = re.search(
+        rf"^- {re.escape(key)}:\s*\n((?:\s*>.*\n?)+)", block, re.MULTILINE
+    )
+    if not match:
+        return ""
+    return "\n".join(
+        re.sub(r"^\s*>\s?", "", line)
+        for line in match.group(1).splitlines()
+    ).strip()
+
+def _sidecar_metadata_value(sidecar_text: str, key: str) -> str:
+    frontmatter = _YAML_FRONTMATTER_RE.match(sidecar_text)
+    if frontmatter is None:
+        return ""
+    match = re.search(
+        rf"^{re.escape(key)}:[ \t]*(\S.*?)[ \t]*$",
+        frontmatter.group("body"),
+        re.MULTILINE,
+    )
+    return match.group(1) if match else ""
+
+def _nearest_frontmatter_value(
+    sidecar_text: str, key: str, before_offset: int
+) -> str:
+    delimiters = [
+        match
+        for match in _FRONTMATTER_DELIMITER_RE.finditer(sidecar_text)
+        if match.start() < before_offset
+    ]
+    for opening, closing in reversed(list(zip(delimiters, delimiters[1:]))):
+        body = sidecar_text[opening.end():closing.start()]
+        match = re.search(
+            rf"^{re.escape(key)}:[ \t]*(\S.*?)[ \t]*$",
+            body,
+            re.MULTILINE,
+        )
+        if match:
+            return match.group(1)
+    return _sidecar_metadata_value(sidecar_text, key)
+
+def _parsed_created_at(value: str) -> dt.datetime | None:
+    if re.fullmatch(
+        r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z",
+        value,
+    ) is None:
+        return None
+    try:
+        parsed = dt.datetime.fromisoformat(value[:-1] + "+00:00")
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        return None
+    return parsed.astimezone(dt.timezone.utc)
+
+def _nearest_sidecar_filename(sidecar_text: str, before_offset: int) -> str:
+    headings = [
+        match
+        for match in _ANALYSIS_SIDECAR_HEADING_RE.finditer(sidecar_text)
+        if match.start() < before_offset
+    ]
+    return headings[-1].group("filename") if headings else ""
+
+def _authoritative_analysis_review_match(
+    sidecar_text: str, matches: list[re.Match[str]]
+) -> re.Match[str]:
+    candidates: list[tuple[dt.datetime, str, int, re.Match[str]]] = []
+    for match in matches:
+        created_at = _parsed_created_at(
+            _nearest_frontmatter_value(sidecar_text, "created-at", match.start())
+        )
+        if created_at is None:
+            continue
+        candidates.append((
+            created_at,
+            _nearest_sidecar_filename(sidecar_text, match.start()),
+            match.start(),
+            match,
+        ))
+    if not candidates:
+        raise UserResponseError(
+            "ANALYSIS REVIEW requires a valid canonical created-at"
+        )
+    return max(candidates, key=lambda candidate: candidate[:3])[3]
+
+def parse_analysis_review(sidecar_text: str) -> AnalysisReviewRecord | None:
+    """Parse the bounded ``## ANALYSIS REVIEW`` block from a sidecar.
+
+    A sidecar without this optional block is not a review.  Once the block is
+    present, status and the fields that make a rejection actionable are
+    validated fail-closed.
+    """
+    matches = list(_ANALYSIS_REVIEW_HEADING_RE.finditer(sidecar_text))
+    if not matches:
+        return None
+    match = _authoritative_analysis_review_match(sidecar_text, matches)
+    block = sidecar_text[match.end():]
+    next_heading = _NEXT_RESPONSE_HEADING_RE.search(block)
+    if next_heading:
+        block = block[:next_heading.start()]
+    status = _field(block, "Status")
+    if status not in _ANALYSIS_REVIEW_STATUSES:
+        raise UserResponseError("ANALYSIS REVIEW Status is invalid")
+    affected = _field(block, "Affected-IDs") or ""
+    affected_ids = tuple(item.strip() for item in affected.split(",") if item.strip())
+    reason = _quoted_review_value(block, "Reason")
+    if status in {"revision-requested", "rejected"} and (not affected_ids or not reason):
+        raise UserResponseError(
+            f"ANALYSIS REVIEW {status} requires Affected-IDs and Reason"
+        )
+    return AnalysisReviewRecord(
+        status=status,
+        affected_ids=affected_ids,
+        reason=reason,
+        additional_evidence=_quoted_review_value(block, "Additional-Evidence"),
+        requested_scope_change=_quoted_review_value(block, "Requested-Scope-Change"),
+        task_key=_nearest_frontmatter_value(
+            sidecar_text, "task-key", match.start()
+        ),
+        task_type=_nearest_frontmatter_value(
+            sidecar_text, "task-type", match.start()
+        ),
+        source_report=_nearest_frontmatter_value(
+            sidecar_text, "source-report", match.start()
+        ),
+        seq=_nearest_frontmatter_value(sidecar_text, "seq", match.start()),
+    )
+
+def _field(block: str, key: str) -> Optional[str]:
+    m = re.search(
+        rf"^- {re.escape(key)}:[ \t]*(\S.*?)[ \t]*$", block, re.MULTILINE
+    )
+    return m.group(1) if m else None
+
+
+@dataclass(frozen=True)
+class UserResponseEntry:
+    response_id: str
+    kind: str
+    value: str
+    rationale: Optional[str] = None
+    disposition: str = "answer"
+
+@dataclass(frozen=True)
+class UserPlanDecision:
+    """HTML 계획 결정 위젯의 Export 결과.
+
+    ``status`` 가 승인이 아니면 ``reason`` 이 필수다 — 사유 없는 반려는 다음
+    run 이 무엇을 고쳐야 하는지 알 수 없어 되돌아올 수밖에 없다.
+    ``implementation_option`` 이 빈 문자열이면 라인을 생략한다 (소비 측은
+    Recommended Option 폴백)."""
+    status: str
+    implementation_option: str = ""
+    reason: str = ""
+
+
+_RESPONSE_HEADING_RE = re.compile(r"^## (?P<id>[A-Za-z][A-Za-z0-9]*-\d+)\s*$", re.MULTILINE)
+
+def _value(block: str) -> str:
+    # Value 는 "- Value:" 다음 줄들의 "  > " 인용 블록.
+    m = re.search(r"^- Value:\s*\n((?:\s*>.*\n?)+)", block, re.MULTILINE)
+    if not m:
+        return ""
+    lines = [re.sub(r"^\s*>\s?", "", ln) for ln in m.group(1).splitlines()]
+    return "\n".join(lines).strip()
+
+def parse_user_response_entries(sidecar_text: str) -> list[UserResponseEntry]:
+    """Reverse of ``serialize_user_response`` for the per-response ``## C-*``
+    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):
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(sidecar_text)
+        block = sidecar_text[m.end():end]
+        rationale = _field(block, "Rationale")
+        entries.append(UserResponseEntry(
+            response_id=m.group("id"),
+            kind=_field(block, "Kind") or "",
+            value=_value(block),
+            rationale=rationale,
+            disposition=_field(block, "Disposition") or "answer",
+        ))
+    return entries

package/runtime/python/okstra_ctl/validation_contract.py

@@ -0,0 +1,3 @@
+"""실행 준비 시 고정하는 검증 계약 버전."""
+
+CURRENT_VALIDATION_CONTRACT_VERSION = 1

package/runtime/python/okstra_ctl/verdict_blocks.py

@@ -106,10 +106,33 @@ def parse_finding_votes(text: str, *, adversarial: bool) -> dict[str, FindingVot
     an unfamiliar token silently read as a different verdict.
     """
     vocabulary = ADVERSARIAL_VERDICTS if adversarial else COLLABORATIVE_VERDICTS
-    return {
-        finding_id: _finding_vote(finding_id, fields, vocabulary)
-        for finding_id, fields in _scan_blocks(text).items()
-    }
+    return _collect_blocks(
+        _scan_blocks(text),
+        lambda item_id, fields: _finding_vote(item_id, fields, vocabulary),
+    )
+
+
+def _collect_blocks(blocks: dict[str, dict[str, str]], parse) -> dict:
+    """모든 블록을 읽고 결함을 한 번에 보고한다.
+
+    첫 결함에서 멈추면 15건 중 13건이 같은 결함인 응답도 한 건씩만 드러나,
+    교정 디스패치를 그 수만큼 반복하게 된다(2026-09-02 실측). 한 응답의 결함은
+    서로 독립이므로 전부 모아 하나의 오류로 낸다.
+    """
+    parsed: dict = {}
+    errors: list[str] = []
+    for item_id, fields in blocks.items():
+        try:
+            parsed[item_id] = parse(item_id, fields)
+        except VerdictBlockError as exc:
+            errors.append(str(exc))
+    if errors:
+        if len(errors) == 1:
+            raise VerdictBlockError(errors[0])
+        raise VerdictBlockError(
+            f"{len(errors)} of {len(blocks)} blocks are malformed: " + "; ".join(errors)
+        )
+    return parsed
 
 
 def _finding_vote(
@@ -155,10 +178,7 @@ class VerdictBlock:
 
 def parse_verdict_blocks(text: str) -> dict[str, VerdictBlock]:
     """Every `### <item-id>` plan-body verdict block in *text*, keyed by item id."""
-    return {
-        item_id: _block(item_id, fields)
-        for item_id, fields in _scan_blocks(text).items()
-    }
+    return _collect_blocks(_scan_blocks(text), _block)
 
 
 def _verdict_token(item_id: str, raw: str) -> tuple[str, str]: