okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/blocking_checks.py

@@ -0,0 +1,251 @@
+"""차단(blocking) 검사 허용목록 — phase 를 멈출 수 있는 실패만 여기 등록한다.
+
+배경: 검증 실패에는 등급이 없었다. 한 건이라도 나오면 run 이
+`contract-violated` 가 되고 phase 가 전진하지 못한다
+(`validators/validate-run.py` 의 `update_validation_metadata`,
+`scripts/okstra_ctl/workflow.py` 의 `compute_workflow_state`). 그래서 리포트
+문서의 상호참조 표기 하나가 실행 전체를 멈춰 세웠다.
+
+실측 근거: 2026-08-20 이후 run-manifest 의 `validation.failures` 1209건 중
+약 78% 가 리포트 문서 안의 기록·상호참조 항목이었다 — 승인 항목의 역추적
+링크, `Evidence checked:` 문구, 활동 원장 backlink, 역할 이름 대조 같은
+것들이다. 이 항목들이 틀려도 다음 단계가 읽는 파일은 그대로 읽히고,
+렌더러도 그대로 돈다.
+
+정책 — 허용목록(allowlist):
+
+- 여기 등록된 조각(fragment)을 포함하는 실패만 run 을 실패시킨다.
+- 등록되지 않은 실패는 advisory 로 강등된다. `validation.advisories` 에
+  그대로 남고 stderr 로도 출력되지만 phase 를 막지 않는다.
+- 새 검사는 기본이 advisory 다. 차단이 필요하면 여기 한 줄을 추가하되,
+  **그 실패가 어떤 소비자를 실제로 깨뜨리는지** 함께 적는다. 그 문장을
+  쓸 수 없으면 차단이 아니라 advisory 다.
+
+2026-08-28 정리(`.project-docs/reports/2026-08-28-validate-run-audit.md`):
+도달 불가·중복 조각 5개를 빼고, 접두 일치로 문서 표기 검사를 끌어들이던 조각
+2개를 조이고, 릴리스 경로를 여는 값 4계열과 self-mock 게이트를 승격했다.
+"""
+
+from __future__ import annotations
+
+# (조각, 왜 차단인가 — 이 실패가 깨뜨리는 소비자)
+#
+# 조각은 실패 메시지에 substring 으로 존재하면 일치로 본다.
+_BLOCKING: tuple[tuple[str, str], ...] = (
+    # 1. 다음 단계가 읽어야 할 산출물이 없거나 파싱되지 않는다.
+    (
+        "final-report data.json is missing",
+        "렌더러의 단일 입력이 없다 — 마크다운/HTML 산출 자체가 불가능하다.",
+    ),
+    (
+        "final-report data.json is not valid JSON",
+        "같은 입력이 파싱되지 않는다.",
+    ),
+    (
+        "final-report schema could not be loaded",
+        "스키마 없이는 데이터 형태를 판정할 수 없어 렌더 결과를 보증할 수 없다.",
+    ),
+    (
+        "final-report data.json schema:",
+        "스키마 구조 위반 — 템플릿이 데이터를 순회하므로 필수 필드가 없으면 렌더가 깨진다.",
+    ),
+    # 콜론이 붙어야 파일 부재 1건(validate-run.py 의
+    # `final report is missing: {report_path}`)만 잡는다. 콜론 없는 조각은
+    # `final report is missing the ...` 로 시작하는 문서 섹션 검사 3건(Token
+    # Usage Summary / Verdict Card / Index)까지 접두 일치로 끌어들여, 표시
+    # 제목을 차단 사유에서 뺀 ADR-0024 와 정면으로 어긋났다.
+    (
+        "final report is missing:",
+        "리포트 파일 자체가 없다.",
+    ),
+    # 주어 없는 `is not importable` 은 어떤 모듈이 못 올라와도 차단이 됐다.
+    # 실제 메시지는 validate-run.py 의
+    # `validate-run: okstra_ctl.final_report_schema is not importable — ...`
+    # 한 곳뿐이다.
+    (
+        "okstra_ctl.final_report_schema is not importable",
+        "스키마 모듈이 없으면 final-report 를 검증하지 않고 통과시킨다 — "
+        "통과 판정 자체를 신뢰할 수 없다.",
+    ),
+    (
+        "report-views: missing html artifact",
+        "열람본이 생성되지 않았다 — 사용자에게 전달할 산출물이 없다.",
+    ),
+    (
+        "report-views validator timed out",
+        "열람본 생성 여부를 판정하지 못했다.",
+    ),
+    # 타임아웃과 같은 등급이다. 둘 다 "열람본이 계약을 지켰는지 판정하지
+    # 못했다" 이고, 대리 스크립트 부재는 설치가 깨졌다는 뜻이라 이후 run 도
+    # 전부 같은 상태다.
+    (
+        "validate-report-views.py missing under",
+        "열람본 검증기가 설치본에 없다 — 판정 없이 통과가 된다.",
+    ),
+    (
+        "conformance manifest unreadable",
+        "적합성 결과를 읽지 못해 게이트 통과 여부를 알 수 없다.",
+    ),
+    (
+        "plan-body verification state file is unreadable",
+        "검증 라운드 상태를 읽지 못해 라운드 수행 여부를 알 수 없다.",
+    ),
+    # 파싱 불가와 같은 등급이다. 소비자(`scripts/okstra_ctl/incremental_carry.py`
+    # 의 상태 파일 읽기)는 "파일이 없다" 와 "파일이 안 읽힌다" 를 구분하지
+    # 못하고 둘 다 라운드 이력 없음으로 떨어진다.
+    (
+        "`state/plan-body-verification-*.json` was written",
+        "덮어써진 검증 라운드의 유일한 기록이 없다 — 라운드 이력을 복원할 "
+        "방법이 사라진다.",
+    ),
+    (
+        "is missing worker prompt history file",
+        "디스패치됐다고 기록된 워커가 받은 프롬프트가 없다 — 그 워커가 무엇을 "
+        "지시받았는지 확인할 방법이 없어 결과를 감사할 수 없다.",
+    ),
+    (
+        "persisted initial prompt path is missing",
+        "같은 이유 — 워커의 최초 프롬프트 경로가 기록되지 않았다.",
+    ),
+    # 2. 다음 단계가 읽는 입력이 실제 내용과 어긋난다.
+    #
+    # 여기에 수렴 분류 재생 불일치와 triggerEvidence 불일치는 없다. 둘 다
+    # 리포트 본문의 사실 주장이 틀렸다는 뜻이지만, 그 값을 읽어 실행을
+    # 구동하는 소비자가 없다 — 검증기와 리포트 투영(report_projections)만
+    # 읽는다. 프로그램 진행에는 문제가 없으므로 advisory 다.
+    (
+        "design-prep request content or fingerprint is stale",
+        "디자인 준비 요청이 실제 내용과 어긋난다 — implementation 단계가 "
+        "이 요청을 읽어 `wait_for_input` 까지 분기하므로"
+        "(scripts/okstra_ctl/implementation_stage.py:113) 옛 요청으로 진행한다.",
+    ),
+    # selected-direction 계획의 두 조각. 주 집행은 조립 게시 게이트
+    # (report_assembly `_selected_direction_publication_errors`)이고, 여기는
+    # 게시 후 변조·우회 경로의 백스톱이다. dev-10341 실측: 이 접두 17건이
+    # advisory 로 통과 발행된 계획을 구현 진입이 그대로 하드 거부해 run 이
+    # wedge 됐다.
+    (
+        "implementation-planning selected-direction:",
+        "구현 진입(scripts/okstra_ctl/run.py `_validate_selected_implementation_plan`)"
+        "이 같은 검증을 하드 거부한다 — 통과 발행된 계획이 다음 phase 에서 "
+        "준비 자체가 안 된다.",
+    ),
+    (
+        "has malformed conformanceTests declaration",
+        "승인 경계(scripts/okstra_ctl/run.py `_validate_approved_plan_conformance`)"
+        "가 같은 형식을 하드 거부한다 — 같은 이유로 구현 준비가 막힌다.",
+    ),
+    # 3. 게이트 결과가 없거나 무의미하다.
+    #
+    # `conformance gate BLOCKING` 이 실제로 잡는 범위는 "스크립트가 안 돌았다"
+    # 한 갈래보다 넓다. validate-run.py 의 발생 지점 22곳은 세 갈래다 —
+    # 게이트 미실행, 승인된 계획 증거의 배관 실패(run-inputs 부재·approvedPlanPath
+    # 부재·경로 해석 실패), 선언 규칙 위반(선언되지 않은 경로를 만진 diff,
+    # 선언된 스크립트 누락). 세 갈래 전부 같은 소비자 문장으로 정당화된다:
+    # 이후 단계가 "이 stage 는 적합성 검사를 통과했다"를 전제로 진행하는데,
+    # 그 전제를 세울 근거 자체가 없다.
+    #
+    # 접두 결합에 주의한다. `missing_declared_scripts` 와
+    # `_declared_conformance_errors` 가 만든 임의 문자열이 이 접두 뒤에 붙어
+    # (`f"conformance gate BLOCKING: {error}"`) 여기 등록되지 않은 검사가
+    # 자동으로 차단 등급을 얻는다. 그 함수들에 새 오류 문구를 추가하는 것은
+    # 곧 이 허용목록에 한 줄을 추가하는 것과 같다.
+    (
+        "conformance gate BLOCKING",
+        "적합성 게이트의 결과가 없다 — 이후 단계가 적합성 전제를 세울 수 없다.",
+    ),
+    # self-mock 게이트(PR #356)는 차단 목적으로 설계됐다. 테스트가 SUT 를
+    # 스텁하면 통과 판정이 "무엇도 검증하지 않았다"와 같은 뜻이 되고,
+    # final-verification 과 릴리스 게이트(scripts/okstra_ctl/release_gate.py)가
+    # 검증되지 않은 코드를 통과시킨다. validate-run.py 의 self-mock 실패는
+    # 전부 이 접두를 단다.
+    (
+        "self-mock gate BLOCKING:",
+        "테스트가 SUT 를 스텁해 통과 판정이 무의미하다 — 검증되지 않은 코드가 "
+        "릴리스 게이트를 지난다.",
+    ),
+    # 4. 검증되지 않은 결과가 릴리스·후속 stage 로 넘어간다.
+    #
+    # 이 군은 전부 릴리스 경로를 여는 값을 읽는 소비자가 검증기 밖에 있다.
+    # 리포트 본문 표기가 아니라 판정 자체가 틀린 경우다.
+    (
+        "final-verification report declares",
+        "리포트가 선언한 verificationScope·worktree·base/head 가 준비된 검증 "
+        "대상과 다르다 — scripts/okstra_ctl/handoff.py 가 verificationScope 로 "
+        "stage-group 적격성과 release-handoff 라우팅을 정하므로, 검증하지 않은 "
+        "head 가 릴리스로 간다.",
+    ),
+    (
+        "final-verification report covers stages",
+        "같은 이유 — 증거를 준비하지 않은 stage 집합에 판정이 내려진다.",
+    ),
+    (
+        "`verdict: FAIL` but `finalVerdict.verdictToken` is",
+        "검증자가 기록한 FAIL 이 통과 판정과 공존한다 — release_gate.py 와 "
+        "stage_fix_carry.py 가 통과 판정만 보므로 거부된 작업이 "
+        "release-handoff 로 넘어간다.",
+    ),
+    (
+        "implementation run declares stage-",
+        "stage 캐리 사이드카가 디스크에 없다 — consumers.py 의 "
+        "backfill_done_from_carry 가 이 파일로 stage 를 done 처리하므로, "
+        "없으면 후속 stage 가 전부 PrepareError 로 준비에 실패한다.",
+    ),
+    # final-verification 판정의 교차 필드 모순. 세 조각으로 나눠 등록한 이유는
+    # `final-verification: ` 접두 하나로 묶으면 같은 접두를 쓰는
+    # addedSurfaceAudit 표기 검사 3건까지 차단으로 끌려오기 때문이다.
+    (
+        "final-verification: verdict ",
+        "판정과 blocker/condition 이 모순이다 — release_gate.py 와 "
+        "next_phase.py 가 이 판정으로 분기하므로 잘못된 다음 phase 가 열린다.",
+    ),
+    (
+        "final-verification: routingRecommendation",
+        "같은 이유 — 라우팅 대상이 없거나 판정이 허용하지 않는 대상을 가리킨다.",
+    ),
+    (
+        "final-verification: verificationScope ",
+        "같은 이유 — 검증 범위가 열거값 밖이거나 단일 stage 검증이 전체 "
+        "release-handoff 를 요구한다.",
+    ),
+)
+
+# 2026-08-28 에 제거한 조각과 근거 (감사 보고서 §2):
+#
+# - `failed to parse JSON:` — validate-run.py 의 `load_json` 이 이 문구로
+#   ValueError 를 raise 하는데, 호출부가 failures 리스트를 만들기 전이라
+#   프로세스가 그대로 죽는다. partition() 에 도달하지 못한다.
+# - `cannot load Stage Map validator` — `spec_from_file_location` 은 파일이
+#   없어도 spec 을 돌려주므로 조건이 성립하지 않고, 파일 부재는 그 다음
+#   `exec_module` 에서 예외로 끝난다.
+# - `missing or malformed at` — 유일 발생 지점(approvedPlanPath 부재)이
+#   `conformance gate BLOCKING:` 접두를 함께 달고 있어 고유 승격이 0 이었다.
+# - `unreadable at` — 발생 지점 4곳 중 3곳이 `conformance gate BLOCKING:`
+#   접두 2곳과 `conformance manifest unreadable at` 1곳으로 이미 덮이고,
+#   남은 1곳(self-mock 사이드카)은 위 `self-mock gate BLOCKING:` 로 덮인다.
+#   이 조각이 하던 일은 self-mock 게이트에서 "사이드카를 못 읽었다" 갈래만
+#   차단하고 실제 FAIL·미검출 뮤턴트는 advisory 로 두는 등급 역전이었다.
+# - `phase-boundary:` — 판정 근거가 리드가 손으로 쓴 에러 로그 산문의
+#   substring 스캔이었고 검사 자체가 삭제됐다.
+
+BLOCKING_FRAGMENTS: tuple[str, ...] = tuple(fragment for fragment, _why in _BLOCKING)
+
+BLOCKING_REASONS: dict[str, str] = {fragment: why for fragment, why in _BLOCKING}
+
+
+def is_blocking(failure: str) -> bool:
+    """``failure`` 가 허용목록에 걸리면 True."""
+    return any(fragment in failure for fragment in BLOCKING_FRAGMENTS)
+
+
+def partition(failures: list[str]) -> tuple[list[str], list[str]]:
+    """``failures`` 를 (차단, advisory) 로 나눈다.
+
+    순서는 입력 순서를 유지한다 — 리포트에 실릴 때 원래 검사 순서가 곧
+    읽는 순서이기 때문이다.
+    """
+    blocking: list[str] = []
+    advisory: list[str] = []
+    for failure in failures:
+        (blocking if is_blocking(failure) else advisory).append(failure)
+    return blocking, advisory

package/runtime/python/okstra_ctl/brief_frontmatter.py

@@ -45,12 +45,5 @@ def read_brief_frontmatter(path: Path) -> dict[str, str]:
     return out
 
 
-def is_canonical_generated_brief(frontmatter: Mapping[str, str]) -> bool:
-    return (
-        frontmatter.get("type") == "brief"
-        and frontmatter.get("generator") == "okstra-brief-gen"
-    )
-
-
 def has_reporter_confirmation_contract(frontmatter: Mapping[str, str]) -> bool:
     return "reporter-confirmations" in frontmatter

package/runtime/python/okstra_ctl/clarification_items/__init__.py

@@ -0,0 +1,102 @@
+"""Read a final-report's clarification rows, whichever schema wrote them.
+
+A clarification is what a run owes the user — a decision, a file attachment,
+a single data point. Each row carries a ``Blocks`` value out of
+``{approval, next-phase, none}``. Rows with ``Blocks=approval`` are the
+approval gate: they MUST resolve before the user flips the frontmatter
+``approved`` field to ``true`` and starts the next ``implementation`` run.
+A ``request-revision`` / ``reject`` answer still blocks the report that has
+not yet incorporated it. The report that recorded the same id in
+``supersessionLedger`` has already absorbed that return and does not block.
+
+The two schemas store those rows in different places, and that is why the
+read functions take a report **path**, not its text:
+
+* schema-v1 — the ``## 1. Clarification Items`` markdown table (introduced
+  when §4.5.9 / §5.1 / §5.2 collapsed into a single section).
+* schema-v2 — ``clarificationItems[]`` in the ``.data.json`` sibling. Its AI
+  handoff markdown renders them as one section per row under
+  ``## Clarification and User Decisions``, not as a §1 table, so the §1 table
+  walk finds nothing there by construction.
+
+Every gate goes through ``scan_approval_gate`` / ``scan_open_user_input`` so
+run-prep (``_validate_approved_plan``), the wizard, and the user-response CLI
+cannot disagree about what is still open.
+
+Gate semantics are fail-closed: when the rows cannot be read with confidence
+(§1 heading missing/drifted, table header unrecognized, a body row whose
+metadata cell fails to parse, or a v2 row missing id/blocks/status), the scan
+reports an ``unreadable_reason`` and callers must refuse approval instead of
+soft-passing. ``parse_clarification_items`` keeps the lenient
+None-on-absence contract for the schema-v1 HTML-view renderers, which only
+need best-effort row extraction.
+
+구현은 여섯 층으로 나뉜다 — `parsing` · `dispositions` 가 바닥이고,
+`rows` · `sidecars` 가 그 위, `scan` · `carry` 가 그 둘을 쓴다. 이 파일은
+밖으로 나가는 이름만 모아 둔다.
+"""
+from __future__ import annotations
+
+from .parsing import (
+    ClarificationItem,
+    _CELL_ANCHOR_RE,
+    _section_1_slice,
+    _split_pipe_row,
+    parse_clarification_items,
+    parse_meta_cell,
+    section_1_present_but_unparsed,
+)
+from .dispositions import (
+    APPROVAL_BLOCKS,
+    PROCEEDING_DISPOSITIONS,
+    USER_INPUT_BLOCKS,
+    clarification_disposition,
+    incorporated_clarification_ids,
+    progress_blocking_ids,
+    row_blocks_progress,
+)
+from .rows import (
+    STRUCTURED_REPORT_VERSIONS,
+    read_clarification_rows,
+)
+from .sidecars import (
+    attached_user_responses_section,
+    sidecar_answers,
+    user_response_sidecars,
+)
+from .scan import (
+    scan_approval_gate,
+    scan_open_user_input,
+)
+from .carry import (
+    UNRESOLVED_STATUSES,
+    carried_clarification_rows,
+    clarification_response_with_sidecars,
+)
+
+__all__ = [
+    "APPROVAL_BLOCKS",
+    "ClarificationItem",
+    "PROCEEDING_DISPOSITIONS",
+    "STRUCTURED_REPORT_VERSIONS",
+    "UNRESOLVED_STATUSES",
+    "USER_INPUT_BLOCKS",
+    "_CELL_ANCHOR_RE",
+    "_section_1_slice",
+    "_split_pipe_row",
+    "attached_user_responses_section",
+    "carried_clarification_rows",
+    "clarification_disposition",
+    "clarification_response_with_sidecars",
+    "incorporated_clarification_ids",
+    "parse_clarification_items",
+    "parse_meta_cell",
+    "progress_blocking_ids",
+    "read_clarification_rows",
+    "row_blocks_progress",
+    "scan_approval_gate",
+    "scan_open_user_input",
+    "section_1_present_but_unparsed",
+    "sidecar_answers",
+    "user_response_sidecars",
+]

package/runtime/python/okstra_ctl/clarification_items/carry.py

@@ -0,0 +1,224 @@
+"""다음 run 으로 넘길 clarification 응답 본문을 만든다.
+
+이전 리포트의 §1 과 사용자 답변 사이드카를 합쳐 하나의 이어받기 본문으로
+정리한다. 답이 온 행은 상태를 갱신하고, 아직 열린 행은 그대로 넘긴다.
+"""
+from __future__ import annotations
+
+from ..md_table import is_separator_row, split_pipe_row, to_cell_text
+from pathlib import Path
+from typing import Optional
+import re
+from .parsing import (
+    SECTION_HEADING_PATTERN,
+    _section_1_slice,
+    _split_pipe_row,
+    parse_meta_cell,
+)
+from .rows import (
+    _structured_report_data,
+)
+from .sidecars import (
+    attached_user_responses_section,
+    sidecar_answers,
+)
+
+
+UNRESOLVED_STATUSES = {"open"}
+
+
+def clarification_response_with_sidecars(source: Path) -> str:
+    """clarification-response 본문에 `user-responses/` 사이드카를 덧붙인 본문.
+
+    `resume-clarification` 의 설계된 입력은 사용자가 §1 의 `User input` 열을
+    채운 **직전 final-report 자체**다. 그 전문을 그대로 복사하면 리포트가
+    instruction-set 안에 두 번째로 존재하게 되고, report-writer 는 같은 내용을
+    `clarification-response.md` 로 한 번, 직전 리포트 경로로 다시 한 번 읽는다.
+    리포트는 run 이 누적될수록 커지므로 이 중복은 스스로 악화된다(실측: 283K
+    리포트가 892K 의 중복 읽기를 만들어 report-writer 를 timeout 시켰다).
+
+    그래서 소스가 final-report 일 때는 답변이 실린 clarification 행만 잘라내고
+    원문은 경로로 가리킨다 — `attached_user_responses_section` 이 implementation
+    carry-in 에서 이미 쓰는 "원문은 경로로, 답변만 첨부" 규칙과 같다. 행을 어디서
+    읽는지는 스키마가 정한다(v1 은 §1 표, v2 는 data.json). clarification 을
+    아예 담지 않은 소스(사용자가 직접 쓴 답변 파일)만 원문 그대로 복사한다.
+    """
+    text = source.read_text(encoding="utf-8")
+    section = attached_user_responses_section(source)
+    answers = sidecar_answers(source)
+    body = _clarification_carry_body(source, text, answers)
+    if not section:
+        return body
+    return body.rstrip("\n") + "\n\n---\n\n" + section
+
+
+SECTION_1_HEADING = "## 1. Clarification Items"
+
+
+_SECTION_1_TABLE_HEADER = (
+    "| Record | Statement | Expected form | User input |\n"
+    "|---|---|---|---|"
+)
+
+
+_SECTION_1_EMPTY_STATE = "- The source report recorded no clarification items."
+
+
+def _clarification_carry_body(
+    source: Path, text: str, answers: dict[str, str]
+) -> str:
+    """final-report 소스는 §1 + 원문 포인터로 좁히고, 그 외는 원문 그대로.
+
+    §1 이 있으면 사이드카 답변을 그 표의 `User input` 열에 병합해, 답이 표 안에
+    자리하도록 한다(파일 헤더가 선언하는 "답은 User input 열에" 계약을 실제로
+    참으로 만든다)."""
+    carried = _carry_section_1(source, text)
+    if carried is None:
+        return text
+    heading, section_body = carried
+    if answers:
+        section_body = _reconcile_user_input(section_body, answers)
+    return (
+        "# Clarification Response (carry-in)\n\n"
+        f"- Source report: `{source}`\n"
+        "- This file carries **only** the source report's Clarification Items "
+        "section; the report itself is read from the path above when a phase "
+        "needs it. Do not re-read the source report to find the answers — they "
+        "are in the `User input` column below.\n\n"
+        f"{heading}\n{section_body}\n"
+    )
+
+
+def carried_clarification_rows(source: Path) -> str:
+    """``source`` 리포트의 §1 표 본문만. clarification 을 담지 않았으면 빈 문자열.
+
+    `clarification_response_with_sidecars` 가 carry-in 본문에 싣는 것과 **같은**
+    잘라내기다. 직전 계획 run 의 clarification 을 packet 에 실을 때 이 함수를
+    쓰지 않고 따로 긁으면 같은 리포트가 소비처마다 다른 clarification 집합으로
+    읽힌다. 리포트 전문은 절대 싣지 않는다 — 그것이 이 모듈이 존재하는 이유다.
+    """
+    carried = _carry_section_1(source)
+    return "" if carried is None else carried[1].strip()
+
+
+def _carry_section_1(
+    source: Path, text: Optional[str] = None
+) -> Optional[tuple[str, str]]:
+    """carry-in 본문에 실을 (헤딩, §1 본문). clarification 을 담지 않은 소스면
+    ``None``.
+
+    schema-v2 는 행을 data.json 에 들고 AI 마크다운에는 §1 표가 없다. §1 슬라이스
+    만 보던 동안 v2 소스는 "좁힐 것이 없다" 로 판정돼 **리포트 전문이 그대로
+    복사**됐다 — 이 좁히기가 막으려던 바로 그 중복이다. carry-in 은 파생 문서이고
+    다운스트림(승인 게이트·프롬프트 빌더·검증 워커)이 §1 표 하나만 읽으므로, v2
+    행도 같은 표로 렌더한다.
+
+    ``text`` 를 생략하면 v1 슬라이스가 필요할 때만 소스를 읽는다. v2/v3 소스는
+    본문이 data.json 에 있어 마크다운을 읽을 이유가 없고, 그 파일은 실측 693K
+    까지 커진다."""
+    data = _structured_report_data(source)
+    if data is not None:
+        entries = data.get("clarificationItems")
+        return SECTION_1_HEADING, _structured_section_1_body(
+            entries if isinstance(entries, list) else []
+        )
+    if text is None:
+        text = source.read_text(encoding="utf-8", errors="replace")
+    slice_ = _section_1_slice(text)
+    if slice_ is None:
+        return None
+    heading = SECTION_HEADING_PATTERN.search(text)
+    assert heading is not None  # _section_1_slice returned a slice
+    return heading.group(0), slice_.rstrip()
+
+
+def _structured_section_1_body(entries: list) -> str:
+    """schema-v2 `clarificationItems[]` 를 §1 표 본문으로.
+
+    메타 셀은 렌더러가 쓰는 모양 그대로다 — `Status:` 는 따옴표 없이 써야
+    `_reconcile_user_input` 이 답을 병합하면서 상태를 answered 로 넘길 수 있다."""
+    rows = [e for e in entries if isinstance(e, dict) and e.get("id")]
+    if not rows:
+        return f"\n{_SECTION_1_EMPTY_STATE}"
+    lines = ["", _SECTION_1_TABLE_HEADER]
+    for entry in rows:
+        meta = (
+            f"**{entry['id']}**"
+            f"<br>Ticket: `{to_cell_text(entry.get('ticketId'))}`"
+            f"<br>Kind: `{to_cell_text(entry.get('kind'))}`"
+            f"<br>Blocks: `{to_cell_text(entry.get('blocks'))}`"
+            f"<br>Status: {to_cell_text(entry.get('status'))}"
+        )
+        lines.append(
+            f"| {meta} | {to_cell_text(entry.get('statement'))} "
+            f"| {to_cell_text(entry.get('expectedForm'))} "
+            f"| {to_cell_text(entry.get('userInput'))} |"
+        )
+    return "\n".join(lines)
+
+
+_STATUS_ANSWER_RE = re.compile(r"(Status:\s*)(?:open|answered)\b", re.IGNORECASE)
+
+
+def _locate_user_input_column(lines: list[str]) -> tuple[int, int]:
+    """§1 데이터 표의 헤더 줄 인덱스와 `User input` 열 인덱스. 표가 없으면 (-1, -1)."""
+    for idx, line in enumerate(lines):
+        if not line.lstrip().startswith("|"):
+            continue
+        cells = [c.lower() for c in _split_pipe_row(line)]
+        if "user input" in cells and any(c.startswith("statement") for c in cells):
+            return idx, cells.index("user input")
+    return -1, -1
+
+
+def _reconcile_row(line: str, ui_col: int, answers: dict[str, str]) -> str:
+    """답이 있고 open/answered 인 행이면 `User input` 칸을 그 답으로 채우고 Status 를
+    answered 로 바꾼 줄을, 그 외에는 원본 줄을 그대로 돌려준다.
+
+    칸에 이미 값이 있어도 사용자의 사이드카 답이 이긴다. 그 칸을 채우는 것은
+    run 자신(직전 렌더가 옮겨 적은 값)이고, 사용자가 나중에 답을 바꾸면 둘이
+    갈라진다 — 사용자가 쓴 쪽을 정본으로 삼지 않으면 run 이 자기가 적어둔 값으로
+    계속 되돌아간다.
+
+    판정은 앵커/백틱을 벗긴 셀(`_split_pipe_row`)로 — 그래야 `_meta_id` 가 스크롤
+    앵커의 소문자 slug 대신 진짜 대문자 ID 를 읽는다. 재조립은 원본 셀
+    (`split_pipe_row`)로 해서 앵커를 보존한다."""
+    norm = _split_pipe_row(line)
+    item = parse_meta_cell(norm[0]) if norm else None
+    if item is None or item.row_id not in answers:
+        return line
+    if item.status not in UNRESOLVED_STATUSES:
+        return line
+    raw = split_pipe_row(line)
+    if not 0 <= ui_col < len(raw):
+        return line
+    raw[ui_col] = answers[item.row_id]
+    raw[0] = _STATUS_ANSWER_RE.sub(r"\1answered", raw[0])
+    return "| " + " | ".join(to_cell_text(c) for c in raw) + " |"
+
+
+def _reconcile_user_input(section: str, answers: dict[str, str]) -> str:
+    """§1 표에서 사이드카 답이 있는 미해결 행의 `User input` 칸을 답으로 채우고
+    Status 를 answered 로 바꾼 §1 본문을 돌려준다.
+
+    답의 정본 위치를 §1 표 안으로 옮긴다 — 표만 읽는 승인 게이트·프롬프트
+    빌더·검증 워커가 모두 답을 보게 하려는 것. 사이드카는 §1 표 밖 별도 섹션에만
+    있어서 표만 신뢰하는 소비자는 그 답을 놓쳤다."""
+    lines = section.splitlines()
+    header_idx, ui_col = _locate_user_input_column(lines)
+    if header_idx < 0:
+        return section
+    out = list(lines)
+    body = False
+    for i in range(header_idx + 1, len(lines)):
+        line = lines[i]
+        if not line.lstrip().startswith("|"):
+            if body:
+                break
+            continue
+        if is_separator_row(line):
+            body = True
+            continue
+        if body:
+            out[i] = _reconcile_row(line, ui_col, answers)
+    return "\n".join(out)