` below so those `href="#…"` links actually jump.
row_anchor_ids: list[Optional[str]] = []
i = start + 2 # skip header + separator
while i < len(lines) and lines[i].lstrip().startswith("|"):
cells = _split_pipe_row(lines[i])
# A row with more cells than the header means an unescaped `|`
# inside cell text (the writer should have used `\|`). Merge the
# overflow back into the last header column instead of spilling
# extra s outside the table border.
if len(cells) > len(header_cells):
keep = len(header_cells) - 1
cells = cells[:keep] + ["|".join(cells[keep:])]
rows.append(cells)
anchor = _CELL_ANCHOR_RE.search(lines[i])
row_anchor_ids.append(anchor.group(1).lower() if anchor else None)
i += 1
# §1 Clarification Items is the only interactive table. Its short columns
# are collapsed into one stacked meta cell (`**C-101**"
+ "".join(
f"{_inline(c)}"
for idx, c in enumerate(header_cells)
)
+ " {_form_control(meta.row_id, meta.kind, meta.status, cell, statement, expected_form)} "
)
else:
cells_html.append(
f"{_inline(cell)}"
)
body_rows.append(
f''
+ "".join(cells_html)
+ " "
)
else:
tr_open = (
f'' if anchor_id else " "
)
body_rows.append(
tr_open
+ "".join(
f"{_inline(c)}"
for idx, c in enumerate(row)
)
+ " "
)
body = "" + "".join(body_rows) + " "
return f"", i - start
_ENUM_LETTERS = "abcde"
_ENUM_CUE_WORDS: tuple[str, ...] = (
"권장은", "권장 ", "추천은", "추천 ", "사유:", "사유 ", "근거:",
)
def _parse_enum_options(statement: str) -> list[tuple[str, str]]:
"""Return ``[(letter, text)]`` pairs if ``statement`` looks like a
``(a) X (b) Y (c) Z`` enumeration, else ``[]``. The sequence may start
at any letter — a statement enum starts at ``(a)``, while the
``Alternatives`` cell of the Expected-form contract starts at ``(b)``
(the recommended answer is ``(a)``) — so parsing keys off the first
``(letter)`` marker found and walks the sequence from there. Stops at
the first recommendation cue (``권장``/``추천``/``사유``/``근거``) so the
"(c) — recommended because ..." tail doesn't leak into the last
option's text. Requires ≥ 2 options to trigger select rendering.
"""
if not statement:
return []
first = re.search(r"\(([a-z])\) ", statement)
if not first:
return []
letters = [chr(c) for c in range(ord(first.group(1)), ord("z") + 1)]
out: list[tuple[str, str]] = []
cursor = 0
for i, letter in enumerate(letters):
anchor = f"({letter}) "
idx = statement.find(anchor, cursor)
if idx < 0:
break
start = idx + len(anchor)
end_candidates: list[int] = []
if i + 1 < len(letters):
n_idx = statement.find(f"({letters[i + 1]}) ", start)
if n_idx >= 0:
end_candidates.append(n_idx)
for cue in _ENUM_CUE_WORDS:
c_idx = statement.find(cue, start)
if c_idx >= 0:
end_candidates.append(c_idx)
end = min(end_candidates) if end_candidates else len(statement)
text = statement[start:end].strip(" .,—-")
if not text:
break
out.append((letter, text))
cursor = end
return out if len(out) >= 2 else []
_RECOMMENDED_CUE = "Recommended:"
_ALTERNATIVES_CUE = "Alternatives:"
# Authors sometimes append a pick-one answer-space summary like
# "(A / B 중 택1)" to the Expected form. The rendered already
# enforces single choice, so this annotation must never reach an option
# label — strip a trailing parenthetical that contains "택".
_PICK_ONE_ANNOTATION = re.compile(r"\s*\([^()]*택\s*\d+\s*\)\s*$")
def _lettered_option(letter: str, text: str) -> str:
return f"({letter}) {text}"
def _strip_leading_letter_label(text: str) -> str:
"""Drop a leading ``(a)`` / ``(b)`` … contract label so the caller can
re-letter the option exactly once (the contract labels the recommended
answer `(a)` and alternatives from `(b)`)."""
return re.sub(r"^\([a-z]\)\s*", "", text)
def parse_expected_form_options(expected_form: str) -> list[tuple[str, str]]:
"""Parse the ``Expected form`` contract format
(``Recommended: — ; Alternatives: ``,
`_common-contract.md` §Clarification request policy) into select
``(value, label)`` options. Returns ``[]`` when the cell carries no
``Recommended:`` cue — the caller falls back to the statement enum.
The single parser for this cell. Both the HTML view and
``user_response.show_open_rows`` call it; a second implementation is
exactly how the two option boards drifted apart once already."""
if not expected_form:
return []
expected_form = _PICK_ONE_ANNOTATION.sub("", expected_form)
rec_idx = expected_form.find(_RECOMMENDED_CUE)
if rec_idx < 0:
return []
rec_body = expected_form[rec_idx + len(_RECOMMENDED_CUE):]
alt_body = ""
alt_idx = rec_body.find(_ALTERNATIVES_CUE)
if alt_idx >= 0:
alt_body = rec_body[alt_idx + len(_ALTERNATIVES_CUE):]
rec_body = rec_body[:alt_idx]
# The rationale follows " — "; the option keeps only the answer part.
answer = _strip_leading_letter_label(rec_body.split(" — ", 1)[0].strip(" .,;—-"))
options: list[tuple[str, str]] = []
next_letter_idx = 0
if answer:
letter = _ENUM_LETTERS[next_letter_idx]
options.append(("recommended", _lettered_option(letter, answer)))
next_letter_idx += 1
enum_alts = _parse_enum_options(alt_body)
if enum_alts:
for _original_letter, text in enum_alts:
if next_letter_idx >= len(_ENUM_LETTERS):
break
letter = _ENUM_LETTERS[next_letter_idx]
options.append((letter, _lettered_option(letter, text)))
next_letter_idx += 1
else:
alt_text = _strip_leading_letter_label(alt_body.strip(" .,;—-"))
if alt_text and next_letter_idx < len(_ENUM_LETTERS):
letter = _ENUM_LETTERS[next_letter_idx]
options.append((letter, _lettered_option(letter, alt_text)))
return options
_OPTION_LABEL_PREFIX = re.compile(r"^(추천:\s*|\([0-9a-z]\)\s*)")
# 옵션 본문이 이보다 짧으면 prefix 매칭을 건너뛰고 정확 일치만 인정 —
# "혼합" 같은 짧은 라벨이 더 긴 다른 응답의 접두어로 오매칭되는 것을 막는다.
_MIN_OPTION_PREFIX_LEN = 6
def _match_option_value(
current_value: str, opts: list[tuple[str, str]]
) -> str | None:
"""Re-select the option a user previously picked when a carried-in
``User input`` cell is rendered read-only. Compares ``current_value``
against each option's label body (``추천:`` / ``(a)`` prefix stripped).
Exact match wins over a prefix match; returns ``None`` when nothing
matches so the caller falls back to the ``기타`` branch."""
cv = (current_value or "").strip()
if not cv:
return None
normalized_current = _OPTION_LABEL_PREFIX.sub("", cv).strip()
bodies = [
(value, _OPTION_LABEL_PREFIX.sub("", label).strip())
for value, label in opts
]
for value, body in bodies:
if body and (normalized_current == body or cv == body or cv == value):
return value
for value, body in bodies:
if (
len(body) >= _MIN_OPTION_PREFIX_LEN
and (normalized_current.startswith(body) or cv.startswith(body))
):
return value
return None
def _form_control(
response_id: str,
kind: str,
status: str,
current_value: str,
statement: str = "",
expected_form: str = "",
) -> str:
rid = html.escape(response_id)
disabled = "" if status.lower() in ("open", "answered", "") else " disabled"
safe_value = html.escape(current_value or "")
kind_lc = kind.lower()
placeholder = {
"material": "파일 경로 또는 본문",
"decision": "선택 또는 짧은 응답",
"data-point": "값",
}.get(kind_lc, "응답")
# decision 의 후보는 Expected form 의 `Recommended: …; Alternatives: …`
# 계약(_common-contract.md §Clarification request policy)이 1순위,
# statement 안 (a)(b)(c) 열거가 fallback. 후보가 있으면 select+기타 input.
if kind_lc == "decision":
opts = parse_expected_form_options(expected_form)
if not opts:
opts = [
(letter, f"({letter}) {text}")
for letter, text in _parse_enum_options(statement)
]
if opts:
matched = _match_option_value(current_value, opts)
use_other = matched is None and bool((current_value or "").strip())
select_opts = "".join(
f''
f"{_inline(label)} "
for value, label in opts
)
other_attr = " selected" if use_other else ""
other_hidden = "" if use_other else " hidden"
select_html = (
f''
'(선택) '
f"{select_opts}"
f'기타 (직접 입력) '
" "
)
other_html = (
f' "
)
return select_html + other_html
# 나머지 kind(material/data-point/decision-without-enum)는 모두 자유 입력.
# 한 줄 넘는 응답을 편하게 적도록 고정 높이 input 대신 textarea 로 렌더한다.
return (
f'"
)
def _emit_list(lines: list[str], start: int) -> tuple[str, int]:
i = start
first = lines[start]
is_numbered = bool(_LIST_NUMBERED_PATTERN.match(first))
tag = "ol" if is_numbered else "ul"
items: list[str] = []
while i < len(lines):
ln = lines[i]
m_b = _LIST_BULLET_PATTERN.match(ln) if not is_numbered else None
m_n = _LIST_NUMBERED_PATTERN.match(ln) if is_numbered else None
if not (m_b or m_n):
if _BLANK_PATTERN.match(ln):
# Blank inside a list — peek; if next line continues the
# list, swallow the blank, else end.
if i + 1 < len(lines) and (
_LIST_BULLET_PATTERN.match(lines[i + 1])
or _LIST_NUMBERED_PATTERN.match(lines[i + 1])
):
i += 1
continue
break
text = m_b.group(2) if m_b else m_n.group(3)
items.append(f"{_inline(text)} ")
i += 1
return f"<{tag}>" + "".join(items) + f"", i - start
_NARROW_COL_MAX_PLAIN_LEN = 30
_INLINE_MD_STRIP_RE = re.compile(r"[`*_]")
# Header-name whitelist: columns whose width is effectively fixed by
# convention even when one row carries a long body cell (e.g. "출처"
# starts with a short token but the prose body of a single citation
# row may run 60+ chars). Matched as case-insensitive prefix on the
# header's first plain token, so "Ticket ID" / "출처 (brief/source/worker)"
# / "환산 토큰 (input 기준)" all hit the same entry. Keep this list
# tight — every entry is a promise that the column is *always* one of
# a handful of canonical short values across every final-report.
_NARROW_HEADER_PREFIXES: tuple[str, ...] = (
# English / latin
"id",
"ticket id",
"kind",
"status",
"blocks",
"origin",
"priority",
"auto-spawn",
# merged record-meta column (columns.recordMeta) — "Record" in en, "항목" in ko
"record",
# Korean
"출처",
"에이전트",
"역할",
"모델",
"상태",
"항목",
"처리 토큰",
"환산 토큰",
"비용",
)
def _plain_len(raw_cell: str) -> int:
return len(_INLINE_MD_STRIP_RE.sub("", raw_cell or "").strip())
# Under report.css `td.td-narrow { white-space: nowrap }` a cell's longest
# ", re.IGNORECASE)
def _max_plain_line_len(raw_cell: str) -> int:
return max(
(_plain_len(segment) for segment in _BR_TAG_RE.split(raw_cell or "")),
default=0,
)
def _matches_narrow_whitelist(header: str) -> bool:
plain = _INLINE_MD_STRIP_RE.sub("", header or "").strip().lower()
return any(plain.startswith(p) for p in _NARROW_HEADER_PREFIXES)
def _narrow_columns(
header_cells: list[str], rows: list[list[str]]
) -> set[int]:
"""Return the set of column indices that should render with the
fixed-narrow ``td-narrow`` width (5% under report.css).
A column qualifies when EITHER:
(a) its header matches `_NARROW_HEADER_PREFIXES` — these are
``ID`` / ``출처`` / ``에이전트`` etc. whose values are
conventionally short (or {m.group(1)}", out)
out = _BOLD_PATTERN.sub(lambda m: f"{m.group(1)} ", out)
out = _LINK_PATTERN.sub(
lambda m: f'{m.group(1)} ', out
)
# Preserve explicit ` demotes a cell's technical detail line below its plain-language
# first line (File Structure `details`). Allowlisted alongside ").replace("</small>", " ")
return out
def _slugify(text: str) -> str:
s = text.strip().lower()
s = re.sub(r"[^a-z0-9ㄱ-힝\-\.\s]", "", s)
s = re.sub(r"\s+", "-", s)
return s or "section"
# --------------------------------------------------------------------------- #
# User-response sidecar serialiser (reference for the validator;
# templates/reports/report.js implements the byte-identical client side).
# --------------------------------------------------------------------------- #
@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 = ""
@dataclass(frozen=True)
class UserDirectionSelection:
option_id: str
option_name: str
confirmed: bool
selection_note: str = ""
constraints: str = ""
@dataclass(frozen=True)
class UserResponseAnalysisReview:
status: str
affected_ids: tuple[str, ...] = ()
reason: str = ""
additional_evidence: str = ""
requested_scope_change: str = ""
_ANALYSIS_REVIEW_STATUSES = frozenset({
"accepted",
"revision-requested",
"rejected",
})
PLAN_DECISION_APPROVED = "approved"
@dataclass(frozen=True)
class UserReportAuthoring:
"""사용자가 리드의 최종 리포트 직접 저작을 허가했는지에 대한 답.
승인이어도 ``reason`` 이 필수다 — 리포트 헤더가 이 사유를 그대로 실어
나중에 읽는 사람이 이 run 이 왜 report-writer 경로를 벗어났는지 본다."""
status: str
reason: str = ""
REPORT_AUTHORING_APPROVED = "approved"
_REPORT_AUTHORING_STATUSES = frozenset({REPORT_AUTHORING_APPROVED, "denied"})
_PLAN_DECISION_STATUSES = frozenset({
PLAN_DECISION_APPROVED,
"revision-requested",
"rejected",
})
_DIRECTION_IDENTITY_WHITESPACE = frozenset(
"\u0009\u000a\u000b\u000c\u000d"
"\u001c\u001d\u001e\u001f\u0020\u0085\u00a0\u1680"
"\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a"
"\u2028\u2029\u202f\u205f\u3000\ufeff"
)
_DIRECTION_IDENTITY_ERROR = (
"DIRECTION SELECTION Option-ID and Option-Name must be "
"non-empty single-line values"
)
def _trim_direction_identity(value: str) -> str:
start = 0
end = len(value)
while start < end and value[start] in _DIRECTION_IDENTITY_WHITESPACE:
start += 1
while end > start and value[end - 1] in _DIRECTION_IDENTITY_WHITESPACE:
end -= 1
return value[start:end]
def normalize_direction_selection_identity(
option_id: str, option_name: str,
) -> tuple[str, str]:
if (
"\r" in option_id
or "\n" in option_id
or "\r" in option_name
or "\n" in option_name
):
raise ValueError(_DIRECTION_IDENTITY_ERROR)
normalized_id = _trim_direction_identity(option_id)
normalized_name = _trim_direction_identity(option_name)
if not normalized_id or not normalized_name:
raise ValueError(_DIRECTION_IDENTITY_ERROR)
return normalized_id, normalized_name
def _quoted_sidecar_field(label: str, value: str) -> str:
cleaned = value.strip()
if not cleaned:
return f"- {label}:\n"
quoted = "".join(f" > {line}\n" for line in cleaned.split("\n"))
return f"- {label}:\n{quoted}"
def _serialize_analysis_review(review: UserResponseAnalysisReview) -> str:
if review.status not in _ANALYSIS_REVIEW_STATUSES:
raise ValueError(f"invalid ANALYSIS REVIEW status: {review.status}")
if review.status in {"revision-requested", "rejected"} and (
not review.affected_ids or not review.reason.strip()
):
raise ValueError(
f"ANALYSIS REVIEW {review.status} requires Affected-IDs and Reason"
)
return (
"\n## ANALYSIS REVIEW\n"
f"- Status: {review.status}\n"
f"- Affected-IDs: {', '.join(review.affected_ids)}\n"
f"{_quoted_sidecar_field('Reason', review.reason)}"
f"{_quoted_sidecar_field('Additional-Evidence', review.additional_evidence)}"
f"{_quoted_sidecar_field('Requested-Scope-Change', review.requested_scope_change)}"
)
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_report_authoring(decision: UserReportAuthoring) -> str:
"""The user's answer on letting the lead author the final report itself.
Same shape as PLAN DECISION because it is the same kind of fact: a decision
only the user may make, written into the sidecar the user owns. A reason is
required even on approval — the report carries it forward, so a later reader
sees why this run left the report-writer path.
"""
if decision.status not in _REPORT_AUTHORING_STATUSES:
raise ValueError(f"invalid REPORT AUTHORING status: {decision.status}")
if not decision.reason.strip():
raise ValueError("REPORT AUTHORING requires a Reason")
return (
"\n## REPORT AUTHORING\n"
f"- Status: {decision.status}\n"
f"{_quoted_sidecar_field('Reason', decision.reason)}"
)
def _serialize_direction_selection(selection: UserDirectionSelection) -> str:
option_id, option_name = normalize_direction_selection_identity(
selection.option_id, selection.option_name
)
if not selection.confirmed:
raise ValueError("DIRECTION SELECTION requires Confirmed: true")
return (
"\n## DIRECTION SELECTION\n"
"- Status: selected\n"
f"- Option-ID: {option_id}\n"
f"- Option-Name: {option_name}\n"
"- Confirmed: true\n"
f"{_quoted_sidecar_field('Selection-Note', selection.selection_note)}"
f"{_quoted_sidecar_field('Constraints', selection.constraints)}"
)
def serialize_user_response(
*,
run_meta: RunMeta,
entries: list[UserResponseEntry],
created_at: str,
plan_decision: UserPlanDecision | None = None,
analysis_review: UserResponseAnalysisReview | None = None,
direction_selection: UserDirectionSelection | None = None,
report_authoring: UserReportAuthoring | None = None,
) -> str:
"""Return the canonical markdown text the HTML 'Export user
response' button must produce. Used by validators to confirm that
pasted sidecar files conform to the schema and that the JS
serialiser stayed in sync.
"""
source_data_lines = ""
if run_meta.source_data:
source_data_lines += f"source-data: {run_meta.source_data}\n"
if run_meta.source_data_sha256:
source_data_lines += (
f"source-data-sha256: {run_meta.source_data_sha256}\n"
)
head = (
"---\n"
f"task-key: {run_meta.task_key}\n"
f"task-type: {run_meta.task_type}\n"
f"seq: {run_meta.seq}\n"
f"source-report: {run_meta.source_report}\n"
f"{source_data_lines}"
"created-by: user\n"
f"created-at: {created_at}\n"
"---\n"
"\n"
"# User Response\n"
)
has_plan_decision = plan_decision is not None
has_analysis_review = analysis_review is not None
has_direction_selection = direction_selection is not None
body_chunks: list[str] = []
for e in entries:
chunk = f"\n## {e.response_id}\n- Kind: {e.kind}\n"
if e.disposition != "answer":
chunk += f"- Disposition: {e.disposition}\n"
value_lines = e.value.strip().split("\n")
chunk += "- Value:\n" + "".join(f" > {ln}\n" for ln in value_lines)
if e.rationale:
chunk += f"- Rationale: {e.rationale.strip()}\n"
body_chunks.append(chunk)
if (
not entries
and not has_plan_decision
and not has_analysis_review
and not has_direction_selection
):
body_chunks.append("\n_(No user responses recorded.)_\n")
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))
if direction_selection is not None:
body_chunks.append(_serialize_direction_selection(direction_selection))
if report_authoring is not None:
body_chunks.append(_serialize_report_authoring(report_authoring))
return head + "".join(body_chunks)
# --------------------------------------------------------------------------- #
# Convenience entrypoint for tests + CLI.
# --------------------------------------------------------------------------- #
def report_has_clarification_items(src_md: str) -> bool:
"""True when the final-report MD has at least one §1``C-*``
clarification row. This is the single predicate that gates HTML-view
generation: the self-contained html's only value over the markdown is
the embedded ``