okstra 0.186.7 → 0.187.0

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

@@ -0,0 +1,135 @@
+"""처분(disposition)의 어휘와 그것이 진행을 막는지의 판정.
+
+`Blocks` 값과 답변 처분만 보고 결정한다 — 파일도, 표도 열지 않는다. 게이트를
+읽는 쪽(`.scan`)과 리포트를 읽는 쪽(`.rows`)이 같은 정의를 쓰게 하는 것이
+이 층이 따로 있는 이유다.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+
+APPROVAL_BLOCKS = frozenset({"approval"})
+
+
+USER_INPUT_BLOCKS = frozenset({"approval", "next-phase"})
+
+
+PROCEEDING_DISPOSITIONS = frozenset({"answer", "select", "accept-risk"})
+
+
+RETURN_DISPOSITIONS = frozenset({"request-revision", "reject"})
+
+
+INCORPORATED_LEDGER_DISPOSITIONS = frozenset(
+    {"superseded", "no-dependent-statement"}
+)
+
+
+def clarification_disposition(row: Mapping[str, object]) -> str:
+    """행에 기록된 사용자 처분. 없으면 빈 문자열."""
+    resolution = row.get("resolution")
+    if not isinstance(resolution, Mapping):
+        context = row.get("approvalContext")
+        if isinstance(context, Mapping):
+            resolution = context.get("resolution")
+    if isinstance(resolution, Mapping):
+        disposition = str(resolution.get("disposition") or "").strip()
+        if disposition:
+            return disposition
+    user_input = str(row.get("userInput") or "").strip()
+    options = row.get("options")
+    if user_input and isinstance(options, list):
+        for option in options:
+            if (
+                isinstance(option, Mapping)
+                and str(option.get("answer") or "").strip() == user_input
+            ):
+                return str(option.get("disposition") or "").strip()
+    return ""
+
+
+def incorporated_clarification_ids(
+    report_data: Mapping[str, object] | None,
+) -> frozenset[str]:
+    """이 런이 답을 본문에 반영했다고 원장에 적은 C-id.
+
+    `superseded` 와 `no-dependent-statement` 만 센다. 원장에 없는
+    `request-revision` / `reject` 는 아직 다음 계획을 막는 되돌림이다.
+    """
+    if not isinstance(report_data, Mapping):
+        return frozenset()
+    planning = report_data.get("implementationPlanning")
+    if not isinstance(planning, Mapping):
+        return frozenset()
+    ledger = planning.get("supersessionLedger")
+    if not isinstance(ledger, list):
+        return frozenset()
+    ids: set[str] = set()
+    for entry in ledger:
+        if not isinstance(entry, Mapping):
+            continue
+        row_id = str(entry.get("clarificationId") or "").strip()
+        disposition = str(entry.get("disposition") or "").strip().lower()
+        if row_id and disposition in INCORPORATED_LEDGER_DISPOSITIONS:
+            ids.add(row_id)
+    return frozenset(ids)
+
+
+def row_blocks_progress(
+    status: str,
+    disposition: str = "",
+    *,
+    incorporated: bool = False,
+) -> bool:
+    """이 행이 승인·다음 단계 진입을 막는가.
+
+    진행 처분(`accept-risk` / `select` / `answer`)은 고치지 않은 DISAGREE 를
+    행과 투표에 남긴 채로 게이트만 내린다. `request-revision` / `reject` 는
+    사용자가 진행을 거절한 것이므로 막는다. 다만 이 보고서 원장이 그 답을
+    이미 반영했으면(`incorporated`) 같은 되돌림이 다음 계획 런을 강제하지
+    않는다. 처분이 없는 `answered` 도 판단 기록이므로 막지 않는다.
+    """
+    normalized_status = status.strip().lower()
+    normalized_disposition = disposition.strip().lower()
+    if normalized_status == "obsolete":
+        return False
+    if normalized_disposition in PROCEEDING_DISPOSITIONS:
+        return False
+    if normalized_disposition in RETURN_DISPOSITIONS:
+        return not incorporated
+    return normalized_status not in {"answered", "resolved"}
+
+
+def progress_blocking_ids(
+    rows: object,
+    blocking_values: frozenset[str] = APPROVAL_BLOCKS,
+    *,
+    report_data: Mapping[str, object] | None = None,
+) -> list[str]:
+    """게이트를 아직 막는 행 id. 사용자 진행 처분이 있는 행은 빠진다.
+
+    ``report_data`` 가 있으면 원장에 반영된 되돌림 행도 빠진다.
+    """
+    if not isinstance(rows, list):
+        return []
+    incorporated = incorporated_clarification_ids(report_data)
+    ids: list[str] = []
+    for row in rows:
+        if not isinstance(row, Mapping):
+            continue
+        blocks = str(row.get("blocks") or "").strip().lower()
+        status = str(row.get("status") or "").strip()
+        row_id = row.get("id")
+        if (
+            blocks in blocking_values
+            and row_blocks_progress(
+                status,
+                clarification_disposition(row),
+                incorporated=isinstance(row_id, str) and row_id in incorporated,
+            )
+            and isinstance(row_id, str)
+            and row_id
+        ):
+            ids.append(row_id)
+    return ids

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

@@ -0,0 +1,253 @@
+"""schema-v1 의 `## 1. Clarification Items` 표를 읽는다.
+
+행 하나가 `ClarificationItem` 이 되고, 그 표를 찾고 걷고 메타 셀을 푸는 것이
+여기 전부다. 판정(무엇이 진행을 막는가)은 `.dispositions`, 파일을 여는 것은
+`.rows` 다.
+"""
+from __future__ import annotations
+
+from ..md_table import is_separator_row, split_pipe_row, to_cell_text
+from dataclasses import dataclass
+from typing import Optional
+import re
+
+
+SECTION_HEADING_PATTERN = re.compile(
+    r'^##\s+1\.\s+Clarification Items\s*(?:<a id="[^"]+"></a>\s*)?$',
+    re.MULTILINE,
+)
+
+
+NEXT_TOP_LEVEL_HEADING_PATTERN = re.compile(r"^##\s+(?!1\.)", re.MULTILINE)
+
+
+@dataclass(frozen=True)
+class ClarificationItem:
+    """One row of the §1 table.
+
+    ``raw_*`` fields preserve the exact cell text (after backtick stripping)
+    for diagnostics; canonical lowercased versions live in ``blocks`` /
+    ``status`` for predicate use.
+    """
+    row_id: str
+    kind: str  # "material" | "decision" | "data-point" | other
+    blocks: str  # canonical lowercase: "approval" | "next-phase" | "none" | other
+    status: str  # canonical lowercase: "open" | "answered" | "resolved" | "obsolete" | other
+    raw_blocks: str
+    raw_status: str
+
+
+_CELL_ANCHOR_RE = re.compile(r'<a id="([^"]*)"></a>')
+
+
+def _strip_backticks(cell: str) -> str:
+    s = _CELL_ANCHOR_RE.sub("", cell.strip()).strip()
+    if s.startswith("`") and s.endswith("`") and len(s) >= 2:
+        s = s[1:-1].strip()
+    return s
+
+
+def _split_pipe_row(line: str) -> list[str]:
+    """``md_table.split_pipe_row`` + §1-specific cell normalization
+    (scroll-anchor removal, outer-backtick unwrap)."""
+    return [_strip_backticks(c) for c in split_pipe_row(line)]
+
+
+def _section_1_slice(report_text: str) -> Optional[str]:
+    """Return the substring spanning the §1 section (heading exclusive of the
+    next ``##`` heading), or None if §1 is absent."""
+    start_match = SECTION_HEADING_PATTERN.search(report_text)
+    if not start_match:
+        return None
+    rest = report_text[start_match.end():]
+    end_match = NEXT_TOP_LEVEL_HEADING_PATTERN.search(rest)
+    return rest[: end_match.start()] if end_match else rest
+
+
+_META_ID_RE = re.compile(r"([A-Za-z][A-Za-z0-9]*-\d+)")
+
+
+def _meta_field(cell: str, key: str) -> str:
+    """Extract a ``<key>: value`` field from a stacked §1 meta cell.
+
+    The §1 table collapses the short columns into one ``<br>``-delimited
+    metadata cell (``**C-101**<br>Ticket: `DEV-1`<br>Kind: `decision`<br>
+    Blocks: `approval`<br>Status: open``). Values may be backtick-wrapped.
+    """
+    m = re.search(
+        rf"{re.escape(key)}:\s*`?\s*([^`<|]+?)\s*`?\s*(?:<br\s*/?>|$)",
+        cell,
+        re.IGNORECASE,
+    )
+    return m.group(1).strip() if m else ""
+
+
+def _meta_id(cell: str) -> str:
+    """The bold headline ID of a §1 meta cell (the part before the first <br>)."""
+    headline = re.split(r"<br\s*/?>", cell, maxsplit=1)[0]
+    m = _META_ID_RE.search(headline)
+    return m.group(1) if m else ""
+
+
+def parse_meta_cell(cell: str) -> Optional[ClarificationItem]:
+    """Parse one §1 stacked meta cell into a ``ClarificationItem``, or ``None``
+    when the cell is not a §1 meta cell (no ``Blocks:``/``Status:`` markers —
+    e.g. a header or an unrelated table). Shared by the approval-gate parser
+    and the HTML view's form-attach pass so both read the cell identically.
+    """
+    raw_blocks = _meta_field(cell, "Blocks")
+    raw_status = _meta_field(cell, "Status")
+    if not (raw_blocks and raw_status):
+        return None
+    return ClarificationItem(
+        row_id=_meta_id(cell),
+        kind=_meta_field(cell, "Kind").lower(),
+        blocks=raw_blocks.lower(),
+        status=raw_status.lower(),
+        raw_blocks=raw_blocks,
+        raw_status=raw_status,
+    )
+
+
+@dataclass(frozen=True)
+class _Section1Table:
+    """Outcome of walking the §1 slice for its data table.
+
+    ``items`` is ``None`` when no recognizable table header exists among the
+    pipe lines. ``unparsed_row_count`` counts body rows whose metadata cell
+    failed ``parse_meta_cell`` (all-empty filler rows excluded).
+    ``has_pipe_lines`` distinguishes the renderer's legitimate table-less
+    placeholder (emptyState bullet) from a table whose header drifted.
+    """
+    items: Optional[list[ClarificationItem]]
+    unparsed_row_count: int
+    has_pipe_lines: bool
+
+
+def _walk_section_1_table(section: str) -> _Section1Table:
+    lines = section.splitlines()
+    has_pipe_lines = any(line.lstrip().startswith("|") for line in lines)
+    # Locate the §1 data table by its header. The merged-meta layout collapses
+    # ID/Ticket/Kind/Blocks/Status into one metadata cell and keeps the
+    # English `Statement` + `User input` columns; detect on those two (any
+    # other table — intro, legacy 5.1/5.2 — is rejected).
+    header_idx = -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):
+            header_idx = idx
+            break
+    if header_idx < 0:
+        return _Section1Table(None, 0, has_pipe_lines)
+
+    items: list[ClarificationItem] = []
+    unparsed = 0
+    body_started = False
+    for line in lines[header_idx + 1:]:
+        if not line.lstrip().startswith("|"):
+            if body_started:
+                break
+            continue
+        if is_separator_row(line):
+            body_started = True
+            continue
+        if not body_started:
+            continue
+        cells = _split_pipe_row(line)
+        if not any(cells):
+            continue
+        item = parse_meta_cell(cells[0])
+        if item is None:
+            unparsed += 1
+            continue
+        items.append(item)
+    return _Section1Table(items, unparsed, True)
+
+
+def parse_clarification_items(report_text: str) -> Optional[list[ClarificationItem]]:
+    """Return the list of §1 rows. ``None`` means "no §1 meta table detected"
+    (missing section or unrecognized table header) — caller must NOT treat
+    that as "table is empty".
+
+    Lenient view-renderer contract: rows whose metadata cell fails to parse
+    are skipped, not surfaced. The approval gate must use
+    ``scan_approval_gate`` instead, which fail-closes on those rows.
+    """
+    section = _section_1_slice(report_text)
+    if section is None:
+        return None
+    return _walk_section_1_table(section).items
+
+
+def parse_section_1_rows(report_text: str) -> list[dict]:
+    """§1 테이블 한 행마다 메타(ClarificationItem) + 원문 Statement / Expected
+    form 셀.
+
+    입력은 §1 을 담은 마크다운 본문이다 — 리포트 전문일 수도 있고, 다음 run 에
+    첨부되는 carry-in 본문(``clarification_response_with_sidecars``)일 수도
+    있다. §1 셀 추출의 단일 참조점 — 다른 모듈이 §1 레이아웃을 다시 훑지 않도록
+    이 함수로 통일한다.
+    """
+    section = _section_1_slice(report_text)
+    if section is None:
+        return []
+    lines = section.splitlines()
+    header_idx = -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):
+            header_idx = idx
+            break
+    if header_idx < 0:
+        return []
+    header = [c.lower() for c in _split_pipe_row(lines[header_idx])]
+    s_col = next((j for j, h in enumerate(header) if h.startswith("statement")), -1)
+    e_col = next((j for j, h in enumerate(header) if h.startswith("expected form")), -1)
+    rows: list[dict] = []
+    body = False
+    for line in lines[header_idx + 1:]:
+        if not line.lstrip().startswith("|"):
+            if body:
+                break
+            continue
+        if is_separator_row(line):
+            body = True
+            continue
+        if not body:
+            continue
+        cells = _split_pipe_row(line)
+        item = parse_meta_cell(cells[0]) if cells else None
+        if item is None:
+            continue
+        rows.append({
+            "item": item,
+            "statement": cells[s_col] if 0 <= s_col < len(cells) else "",
+            "expected_form": cells[e_col] if 0 <= e_col < len(cells) else "",
+            # v1 cells are strings; the structured options live only in v2's
+            # data sibling. The key stays so callers never branch on schema.
+            "options": [],
+        })
+    return rows
+
+
+_LOOSE_SECTION_1_RE = re.compile(r"^##\s+1\.\s+Clarification Items\b", re.MULTILINE)
+
+
+def section_1_present_but_unparsed(report_text: str) -> bool:
+    """§1 헤딩이 느슨 탐지엔 잡히지만 엄격 SECTION_HEADING_PATTERN 에는 매칭하지
+    못하는 경우 True — 헤딩 형태가 어긋나(앵커·포맷 drift) §1 슬라이스 자체가
+    실패하는 상태다.
+
+    이때 ``_section_1_slice`` 가 None 을 반환해 parse 가 통째로 None 이 되고 승인
+    게이트가 "schema 없음 → soft-pass" 로 조용히 열린다. §1 앵커 버그가 정확히 이
+    메커니즘으로 터졌다. 헤딩 자체가 없는 legacy 리포트(둘 다 불매칭)와, 엄격
+    매칭에 성공하는 정상 헤딩(테이블이 없는 emptyState placeholder 포함)은 False —
+    placeholder 는 헤딩이 멀쩡하므로 fail-closed 로 오인하지 않는다. 정규식만 넓혀 온
+    과거 수정과 달리, 이 판별은 "헤딩 형태 drift" 자체를 차단해 재발 클래스를 닫는다."""
+    if SECTION_HEADING_PATTERN.search(report_text):
+        return False
+    return bool(_LOOSE_SECTION_1_RE.search(report_text))

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

@@ -0,0 +1,115 @@
+"""리포트에서 clarification 행을 읽는다 — 어느 스키마가 썼든.
+
+schema-v2 는 `.data.json` 의 `clarificationItems[]`, schema-v1 은 §1 표다.
+읽기 함수가 텍스트가 아니라 **경로**를 받는 이유가 이것이다.
+"""
+from __future__ import annotations
+
+from ..final_report_paths import final_report_data_path
+from ..json_boundary import load_owned_object
+from pathlib import Path
+from typing import Optional
+from .parsing import (
+    ClarificationItem,
+    parse_section_1_rows,
+)
+from .dispositions import (
+    clarification_disposition,
+)
+
+
+STRUCTURED_REPORT_VERSIONS = frozenset({"2.0", "3.0"})
+
+
+def _read_report_text(report_path: Path) -> str:
+    return report_path.read_text(encoding="utf-8", errors="replace")
+
+
+def _structured_report_data(report_path: Path) -> Optional[dict]:
+    """``report_path`` 의 구조화 리포트 레코드, 아니면 ``None``.
+
+    파일이 없거나 JSON 이 깨졌거나 구조화 판본이 아니면 ``None`` — 호출자는 v1
+    마크다운 경로로 폴백하고, 진짜 구조화 리포트인데 레코드가 깨진 경우는 그
+    폴백이 "§1 없음" fail-closed 로 잡는다.
+
+    판본을 `2.0` 하나로 못박아 두던 동안 3.0 리포트가 여기서 ``None`` 이 됐고,
+    그러면 호출자가 JSON 본문에서 `## 1.` 헤딩을 찾다 실패해 **리포트 전문을
+    그대로 복사**했다 — 이 좁히기가 막으려던 바로 그 중복이다. 실측: 66K 짜리
+    추출본이 나와야 할 자리에 693K data.json 이 스테이징됐고, 패킷의
+    `## Clarification Carry-In Extract` 가 0행이 되어 워커가 사용자 답변을
+    전혀 받지 못했다.
+    """
+    data_path = final_report_data_path(report_path)
+    if not data_path.is_file():
+        return None
+    try:
+        data = load_owned_object(data_path, artifact="final report record")
+    except (OSError, ValueError):
+        return None
+    if (
+        not isinstance(data, dict)
+        or data.get("schemaVersion") not in STRUCTURED_REPORT_VERSIONS
+    ):
+        return None
+    return data
+
+
+def _v2_row(entry: dict) -> Optional[dict]:
+    """``clarificationItems[]`` 한 행을 §1 행과 같은 shape 으로. 필수 필드가
+    빠졌으면 ``None`` — 호출자가 fail-closed 로 셀 수 있게 한다."""
+    row_id = entry.get("id")
+    raw_blocks = entry.get("blocks")
+    raw_status = entry.get("status")
+    if not (isinstance(row_id, str) and row_id):
+        return None
+    if not (isinstance(raw_blocks, str) and raw_blocks):
+        return None
+    if not (isinstance(raw_status, str) and raw_status):
+        return None
+    kind = entry.get("kind")
+    item = ClarificationItem(
+        row_id=row_id,
+        kind=kind.lower() if isinstance(kind, str) else "",
+        blocks=raw_blocks.lower(),
+        status=raw_status.lower(),
+        raw_blocks=raw_blocks,
+        raw_status=raw_status,
+    )
+    options = entry.get("options")
+    return {
+        "item": item,
+        "statement": str(entry.get("statement") or ""),
+        "expected_form": str(entry.get("expectedForm") or ""),
+        "options": (
+            [option for option in options if isinstance(option, dict)]
+            if isinstance(options, list)
+            else []
+        ),
+        "disposition": clarification_disposition(entry),
+    }
+
+
+def _v2_clarification_rows(report_path: Path) -> Optional[list[dict]]:
+    """schema-v2 clarification 행들, 이 리포트가 v2 가 아니면 ``None``.
+    필수 필드가 빠진 행은 건너뛰는 lenient 계약(§1 파서와 동일)."""
+    data = _structured_report_data(report_path)
+    if data is None:
+        return None
+    entries = data.get("clarificationItems")
+    if not isinstance(entries, list):
+        return []
+    rows = [_v2_row(e) for e in entries if isinstance(e, dict)]
+    return [row for row in rows if row is not None]
+
+
+def read_clarification_rows(report_path: Path) -> list[dict]:
+    """리포트 한 건의 clarification 행 — schema-v2 는 data.json 사이드카에서,
+    schema-v1 은 §1 테이블에서. 스키마 버전을 아는 유일한 읽기 지점이다.
+
+    ``parse_section_1_rows`` 와 같은 lenient 계약: 어느 쪽에서도 행을 못 찾으면
+    ``[]``.
+    """
+    v2_rows = _v2_clarification_rows(report_path)
+    if v2_rows is not None:
+        return v2_rows
+    return parse_section_1_rows(_read_report_text(report_path))