okstra 0.28.0 → 0.29.0

package/runtime/python/okstra_ctl/report_views.py

@@ -0,0 +1,701 @@
+"""Render two derived views of an okstra final-report markdown.
+
+Two products, one source of truth:
+
+* ``slim_markdown(src_md)`` — deterministic token-saving stripper that
+  removes presentational fluff while preserving every substring the
+  ``validators/validate-run.py`` substring checks rely on. Intended as
+  the AI consumption surface (next-phase lead prompt input).
+* ``render_html(src_md, *, run_meta)`` — deterministic self-contained
+  HTML renderer for human readers. Sections §5/§6/§7 user-actionable
+  rows (those reachable from §5 ``C-*`` IDs) get embedded ``<form>``
+  controls. §4.6 / §4.7 / §4.8 deliverable sub-sections are explicitly
+  excluded from form attachment — they are read-only deliverables.
+
+User responses are NEVER merged back into the original report. The HTML
+serialises a ``user-response`` markdown sidecar via ``Export user
+response`` button (client-side JS, single-reference-point with the
+Python ``serialize_user_response`` function below) and the user pastes
+it to ``runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md``.
+
+Strip rules (deterministic):
+  - ``STRIP_TOKEN_PLACEHOLDER_ZEROS`` — remove ``$0.00`` cost rows
+    except the ``Codex/Gemini CLI 추가 비용`` row (keep, as the literal
+    zero is meaningful audit info).
+  - ``STRIP_DECORATIVE_HR`` — collapse 3+ consecutive horizontal rules
+    to a single ``---``.
+  - ``STRIP_VERDICT_DETAIL`` — drop ``### 4.5.9 Verdict details`` wide
+    matrix body when the preceding ``Verdict summary`` card is present.
+    Keep the heading line itself so heading-set invariants hold.
+  - ``STRIP_INTRO_RECIPE`` — drop the ``> **읽는 법**:`` quoted recipe
+    paragraph beneath the Token Usage Summary table. The definition is
+    audience-facing; the slim AI consumer already knows the schema.
+  - ``COLLAPSE_BLANK_LINES`` — normalise 3+ blank lines to one.
+
+Absolutely-preserve invariants (validator hard-fail prevention):
+  - ``## Verdict Card`` block content byte-identical
+  - ``## 2. Final Verdict`` table rows for ``Verdict Token`` /
+    ``Direction`` / ``Next Step``
+  - ``## 0. Clarification Response Carried In`` (when present)
+  - implementation-planning 9 substrings (Option Candidates,
+    Trade-off, Recommended Option, Stepwise Execution Order,
+    Dependency, Validation Checklist, Rollback, User Approval Request,
+    Plan Body Verification + Gate result:)
+  - implementation §4.7 8 sub-section substrings (Approved Plan
+    Reference, Commit List, Diff Summary, Out-of-plan Edits,
+    Validation Evidence, Verifier Results, Rollback Verification,
+    Routing Recommendation)
+  - final-verification §4.8 6 sub-section substrings (Source
+    Implementation Report, Acceptance Blockers, Residual Risk,
+    Validation Evidence, Read-only Command Log, Routing Recommendation)
+  - release-handoff §4.6.1–4.6.7 sub-section substrings (Source
+    Verification Report, Feature Branch & Working-Tree State, User
+    Selections, Executed Commands, Commit List, Merge Conflict Probe,
+    Pull Request Outcome, Routing Recommendation)
+
+The substring list is sourced from validate-run.py via
+``preserved_substrings()`` so a future contract change touches one
+place only.
+"""
+from __future__ import annotations
+
+import hashlib
+import html
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Optional
+
+
+def source_digest(src_md: str) -> str:
+    """Stable identifier for a final-report markdown body. Both
+    derived views embed this so the validator can detect a stale
+    slim/html that was generated from an older MD."""
+    return hashlib.sha256(src_md.encode("utf-8")).hexdigest()
+
+
+_SOURCE_DIGEST_COMMENT_RE = re.compile(
+    r"^<!--\s*source-sha256:\s*([0-9a-f]{64})\s*-->\s*$", re.MULTILINE
+)
+
+
+def extract_slim_digest(slim_text: str) -> Optional[str]:
+    """Return the source-sha256 token embedded in a slim MD's first
+    comment line, or None if absent (older artifacts)."""
+    first_nonblank = next(
+        (ln for ln in slim_text.splitlines() if ln.strip()), ""
+    )
+    m = _SOURCE_DIGEST_COMMENT_RE.match(first_nonblank)
+    return m.group(1) if m else None
+
+
+_HTML_DIGEST_RE = re.compile(r'"source-sha256":"([0-9a-f]{64})"')
+
+
+def extract_html_digest(html_text: str) -> Optional[str]:
+    m = _HTML_DIGEST_RE.search(html_text)
+    return m.group(1) if m else None
+
+
+def _strip_leading_digest_comment(text: str) -> str:
+    """Remove a leading ``<!-- source-sha256: <hex> -->\\n`` line if
+    present. Used so ``slim_markdown`` and ``render_html`` can be called
+    on their own previously-stripped output without producing a
+    different digest the second time around."""
+    head, _, rest = text.partition("\n")
+    if _SOURCE_DIGEST_COMMENT_RE.match(head):
+        return rest
+    return text
+
+from .clarification_items import (
+    _is_separator_row,
+    _section_5_slice,
+    _split_pipe_row,
+    parse_clarification_items,
+)
+
+
+# --------------------------------------------------------------------------- #
+# Preserved substrings (single source of truth — keep in sync with
+# validators/validate-run.py).
+# --------------------------------------------------------------------------- #
+
+PRESERVED_SUBSTRINGS_PLANNING: tuple[str, ...] = (
+    "Option Candidates",
+    "Trade-off",
+    "Recommended Option",
+    "Stepwise Execution Order",
+    "Dependency",
+    "Validation Checklist",
+    "Rollback",
+    "User Approval Request",
+    "Plan Body Verification",
+    "Gate result:",
+)
+
+PRESERVED_SUBSTRINGS_IMPLEMENTATION: tuple[str, ...] = (
+    "Approved Plan Reference",
+    "Commit List",
+    "Diff Summary",
+    "Out-of-plan Edits",
+    "Validation Evidence",
+    "Verifier Results",
+    "Rollback Verification",
+    "Routing Recommendation",
+)
+
+PRESERVED_SUBSTRINGS_FINAL_VERIFICATION: tuple[str, ...] = (
+    "Source Implementation Report",
+    "Acceptance Blockers",
+    "Residual Risk",
+    "Validation Evidence",
+    "Read-only Command Log",
+    "Routing Recommendation",
+)
+
+PRESERVED_SUBSTRINGS_RELEASE_HANDOFF: tuple[str, ...] = (
+    "Source Verification Report",
+    "Feature Branch & Working-Tree State",
+    "User Selections",
+    "Executed Commands",
+    "Commit List",
+    "Merge Conflict Probe",
+    "Pull Request Outcome",
+    "Routing Recommendation",
+)
+
+PRESERVED_HEADINGS_ALWAYS: tuple[str, ...] = (
+    "## Verdict Card",
+    "## 0. Clarification Response Carried In",
+    "## 2. Final Verdict",
+    "## 5. Clarification Items",
+    "## 6. Recommended Next Steps",
+    "## 7. Follow-up Tasks",
+)
+
+
+def preserved_substrings(task_type: Optional[str]) -> tuple[str, ...]:
+    """Return every substring slim_markdown MUST keep byte-identical."""
+    extras: tuple[str, ...] = ()
+    if task_type == "implementation-planning":
+        extras = PRESERVED_SUBSTRINGS_PLANNING
+    elif task_type == "implementation":
+        extras = PRESERVED_SUBSTRINGS_IMPLEMENTATION
+    elif task_type == "final-verification":
+        extras = PRESERVED_SUBSTRINGS_FINAL_VERIFICATION
+    elif task_type == "release-handoff":
+        extras = PRESERVED_SUBSTRINGS_RELEASE_HANDOFF
+    return PRESERVED_HEADINGS_ALWAYS + extras
+
+
+# --------------------------------------------------------------------------- #
+# Slim stripper
+# --------------------------------------------------------------------------- #
+
+_HR_PATTERN = re.compile(r"^-{3,}\s*$")
+_BLANK_PATTERN = re.compile(r"^\s*$")
+_RECIPE_QUOTE_PATTERN = re.compile(r"^>\s*\*\*읽는 법\*\*")
+_CLI_COST_ROW_HINT = "Codex/Gemini CLI 추가 비용"
+# Verdict details heading historically lived under ``### 4.5.9 Verdict
+# details`` and is now (post-c2c603d split) written as ``#### Verdict
+# details`` directly under §4.5.9 Plan Body Verification. Match both
+# forms so the slim stripper drops the wide matrix body regardless of
+# which template the report was generated against. The trailing ``$``
+# anchor avoids accidentally matching ``Verdict details (excerpt)`` etc.
+_VERDICT_DETAIL_RE = re.compile(
+    r"^#{3,4}\s+(?:4\.5\.9\s+)?Verdict details\s*$"
+)
+_VERDICT_SUMMARY_RE = re.compile(
+    r"^#{3,4}\s+(?:4\.5\.9\s+)?Verdict summary\s*$"
+)
+_ANY_HEADING_RE = re.compile(r"^#{1,6}\s+\S")
+
+
+def slim_markdown(src_md: str, *, task_type: Optional[str] = None) -> str:
+    """Return a slimmed copy of ``src_md`` per the rules in the module
+    docstring. Deterministic — same input always yields the same output.
+
+    Idempotency note: the returned slim begins with a
+    ``<!-- source-sha256: ... -->`` comment so the validator can detect
+    a stale slim against a later MD. Re-running slim on its own output
+    must produce a byte-identical result, so we first strip the leading
+    digest comment (if any) before re-deriving everything from the
+    normalized body.
+    """
+    src_md = _strip_leading_digest_comment(src_md)
+    lines = src_md.splitlines()
+    out: list[str] = []
+
+    hr_run = 0
+    blank_run = 0
+    in_verdict_detail = False  # inside the §4.5.9 Verdict details wide matrix
+
+    for line in lines:
+        # STRIP_VERDICT_DETAIL — drop body of Verdict details (both
+        # ``### 4.5.9 Verdict details`` and ``#### Verdict details``
+        # forms), keep the heading line itself.
+        if _VERDICT_DETAIL_RE.match(line):
+            in_verdict_detail = True
+            out.append(line)
+            continue
+        if in_verdict_detail:
+            if _ANY_HEADING_RE.match(line):
+                in_verdict_detail = False
+                # fall through and emit this heading
+            else:
+                continue
+
+        # STRIP_INTRO_RECIPE — drop the "> **읽는 법**:" quote paragraph.
+        if _RECIPE_QUOTE_PATTERN.match(line):
+            continue
+
+        # STRIP_TOKEN_PLACEHOLDER_ZEROS — drop $0.00 rows except CLI cost.
+        if _is_zero_cost_row(line) and _CLI_COST_ROW_HINT not in line:
+            continue
+
+        # STRIP_DECORATIVE_HR — collapse runs of horizontal rules.
+        if _HR_PATTERN.match(line):
+            hr_run += 1
+            if hr_run > 1:
+                continue
+        else:
+            hr_run = 0
+
+        # COLLAPSE_BLANK_LINES — collapse 3+ blank lines to one.
+        if _BLANK_PATTERN.match(line):
+            blank_run += 1
+            if blank_run > 1:
+                continue
+        else:
+            blank_run = 0
+
+        out.append(line)
+
+    result = "\n".join(out)
+    # STRIP_DECORATIVE_HR (post-process) — collapse runs of HRs that
+    # were separated only by blank lines (the line scanner above can't
+    # reach across blanks without losing blank-line semantics elsewhere).
+    result = re.sub(r"(?:^---\s*\n(?:\s*\n)*){2,}", "---\n", result, flags=re.MULTILINE)
+    if src_md.endswith("\n") and not result.endswith("\n"):
+        result += "\n"
+
+    _assert_preserved(src_md, result, task_type)
+    # Prepend the source-digest comment so the validator can detect a
+    # stale slim that was generated from an older MD. The digest is
+    # over the slim BODY itself, not over the original MD, so the
+    # validator's expected-slim recomputation embeds the same digest
+    # (any byte difference between expected and actual body shows up
+    # as a mismatched digest).
+    digest_line = f"<!-- source-sha256: {source_digest(result)} -->\n"
+    return digest_line + result
+
+
+def _is_zero_cost_row(line: str) -> bool:
+    """True iff this is a markdown table row whose cost cell is exactly
+    ``$0.00`` and no other meaningful cell content suggests audit
+    relevance.
+    """
+    if not line.lstrip().startswith("|"):
+        return False
+    if "$0.00" not in line:
+        return False
+    # Heuristic — defer to the CLI-cost guard at the caller.
+    return True
+
+
+def _assert_preserved(original: str, slim: str, task_type: Optional[str]) -> None:
+    """Raise AssertionError if any preserved substring was dropped."""
+    missing = [s for s in preserved_substrings(task_type) if s in original and s not in slim]
+    if missing:
+        raise AssertionError(
+            "slim_markdown dropped preserved substring(s): " + ", ".join(missing)
+        )
+
+
+# --------------------------------------------------------------------------- #
+# HTML renderer — minimal markdown-to-HTML converter (no external deps)
+# --------------------------------------------------------------------------- #
+
+_HEADING_PATTERN = re.compile(r"^(#{1,6})\s+(.*?)\s*$")
+_CODEFENCE_PATTERN = re.compile(r"^```(.*)$")
+_LIST_BULLET_PATTERN = re.compile(r"^(\s*)[-*]\s+(.*)$")
+_LIST_NUMBERED_PATTERN = re.compile(r"^(\s*)(\d+)\.\s+(.*)$")
+_INLINE_CODE_PATTERN = re.compile(r"`([^`]+)`")
+_BOLD_PATTERN = re.compile(r"\*\*([^*]+)\*\*")
+_LINK_PATTERN = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
+
+# Sections whose Response-ID-bearing rows must NOT get form attachment
+# (read-only deliverables — see plan §1.4).
+_NO_FORM_SECTION_PREFIXES = ("## 4.6", "### 4.6", "## 4.7", "### 4.7", "## 4.8", "### 4.8")
+
+
+@dataclass(frozen=True)
+class RunMeta:
+    task_key: str
+    task_type: str
+    seq: str
+    source_report: str  # relative path of the .md the HTML is derived from
+
+
+def render_html(src_md: str, *, run_meta: RunMeta, css: str, js: str) -> str:
+    """Return a single self-contained HTML document for ``src_md``.
+
+    ``css`` / ``js`` are inlined verbatim. No external URLs are written
+    into the document (validator enforces this — see
+    validate-report-views.py).
+    """
+    # Normalise the input so a digest-bearing leading comment from a
+    # previous slim cycle doesn't leak into the rendered HTML body, then
+    # compute the digest over the normalised MD body. The validator
+    # recomputes the same digest from the current MD and compares it to
+    # the value embedded in run-meta below.
+    src_md = _strip_leading_digest_comment(src_md)
+    body_html = _markdown_to_html(src_md)
+    response_ids = sorted({item.row_id for item in (parse_clarification_items(src_md) or [])})
+    digest = source_digest(src_md)
+
+    title = html.escape(f"{run_meta.task_key} — {run_meta.task_type} #{run_meta.seq}")
+    response_ids_json = "[" + ",".join('"' + html.escape(rid) + '"' for rid in response_ids) + "]"
+
+    return (
+        f"<!DOCTYPE html>\n"
+        f"<html lang=\"ko\">\n"
+        f"<head>\n"
+        f"<meta charset=\"utf-8\">\n"
+        f"<meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">\n"
+        f"<title>{title}</title>\n"
+        f"<style>{css}</style>\n"
+        f"</head>\n"
+        f"<body>\n"
+        f"<header class=\"report-header\">\n"
+        f"  <div>{title}</div>\n"
+        f"  <button type=\"button\" data-action=\"export-user-response\">Export user response</button>\n"
+        f"</header>\n"
+        f"<main>{body_html}</main>\n"
+        f"<footer class=\"report-footer\">\n"
+        f"  <button type=\"button\" data-action=\"export-user-response\">Export user response</button>\n"
+        f"  <pre id=\"user-response-output\" aria-live=\"polite\"></pre>\n"
+        f"  <button type=\"button\" data-action=\"copy-user-response\">Copy</button>\n"
+        f"</footer>\n"
+        f"<script id=\"run-meta\" type=\"application/json\">"
+        f"{{\"task-key\":\"{html.escape(run_meta.task_key)}\","
+        f"\"task-type\":\"{html.escape(run_meta.task_type)}\","
+        f"\"seq\":\"{html.escape(run_meta.seq)}\","
+        f"\"source-report\":\"{html.escape(run_meta.source_report)}\","
+        f"\"source-sha256\":\"{digest}\","
+        f"\"response-ids\":{response_ids_json}}}"
+        f"</script>\n"
+        f"<script>{js}</script>\n"
+        f"</body>\n"
+        f"</html>\n"
+    )
+
+
+def _markdown_to_html(src_md: str) -> str:
+    """Tiny line-based markdown→HTML emitter. Handles only what the
+    final-report template uses: headings, paragraphs, pipe tables,
+    fenced code blocks, blockquotes, ordered+unordered lists, inline
+    code/bold/links. Anything outside that surface is passed through
+    as escaped text inside a paragraph — there are no extension points.
+    """
+    lines = src_md.splitlines()
+    out: list[str] = []
+    i = 0
+    n = len(lines)
+    current_section_path: list[str] = []  # ['## 5. ...', '### 5.1 ...'] etc.
+
+    while i < n:
+        line = lines[i]
+
+        m_heading = _HEADING_PATTERN.match(line)
+        if m_heading:
+            level = len(m_heading.group(1))
+            text = m_heading.group(2)
+            slug = _slugify(text)
+            current_section_path = _update_section_path(current_section_path, level, line)
+            out.append(f'<h{level} id="{slug}">{_inline(text)}</h{level}>')
+            i += 1
+            continue
+
+        m_code = _CODEFENCE_PATTERN.match(line)
+        if m_code:
+            lang = m_code.group(1).strip()
+            code_lines: list[str] = []
+            i += 1
+            while i < n and not _CODEFENCE_PATTERN.match(lines[i]):
+                code_lines.append(lines[i])
+                i += 1
+            if i < n:
+                i += 1
+            cls = f' class="lang-{html.escape(lang)}"' if lang else ""
+            code = html.escape("\n".join(code_lines))
+            out.append(f"<pre><code{cls}>{code}</code></pre>")
+            continue
+
+        if line.lstrip().startswith("|") and i + 1 < n and _is_separator_row(lines[i + 1]):
+            table_html, consumed = _emit_table(lines, i, current_section_path)
+            out.append(table_html)
+            i += consumed
+            continue
+
+        if line.startswith(">"):
+            quote_lines: list[str] = []
+            while i < n and lines[i].startswith(">"):
+                quote_lines.append(lines[i][1:].lstrip())
+                i += 1
+            out.append("<blockquote>" + _inline(" ".join(quote_lines)) + "</blockquote>")
+            continue
+
+        if _LIST_BULLET_PATTERN.match(line) or _LIST_NUMBERED_PATTERN.match(line):
+            list_html, consumed = _emit_list(lines, i)
+            out.append(list_html)
+            i += consumed
+            continue
+
+        if _BLANK_PATTERN.match(line):
+            i += 1
+            continue
+
+        # Plain paragraph — collect until next blank line or block element.
+        para_lines: list[str] = []
+        while i < n and not _BLANK_PATTERN.match(lines[i]):
+            ln = lines[i]
+            if (
+                _HEADING_PATTERN.match(ln)
+                or _CODEFENCE_PATTERN.match(ln)
+                or ln.lstrip().startswith("|")
+                or ln.startswith(">")
+            ):
+                break
+            para_lines.append(ln)
+            i += 1
+        if para_lines:
+            out.append("<p>" + _inline(" ".join(para_lines)) + "</p>")
+
+    return "\n".join(out)
+
+
+def _update_section_path(path: list[str], level: int, line: str) -> list[str]:
+    while path and _heading_level(path[-1]) >= level:
+        path.pop()
+    path.append(line.strip())
+    return path
+
+
+def _heading_level(heading_line: str) -> int:
+    m = _HEADING_PATTERN.match(heading_line)
+    return len(m.group(1)) if m else 0
+
+
+def _section_forbids_form(path: Iterable[str]) -> bool:
+    return any(any(h.startswith(p) for p in _NO_FORM_SECTION_PREFIXES) for h in path)
+
+
+def _emit_table(lines: list[str], start: int, section_path: list[str]) -> tuple[str, int]:
+    header_cells = _split_pipe_row(lines[start])
+    rows: list[list[str]] = []
+    i = start + 2  # skip header + separator
+    while i < len(lines) and lines[i].lstrip().startswith("|"):
+        rows.append(_split_pipe_row(lines[i]))
+        i += 1
+
+    is_clarification_table = (
+        not _section_forbids_form(section_path)
+        and any("Clarification Items" in h for h in section_path)
+        and "ID" in header_cells
+        and "Blocks" in header_cells
+        and "Status" in header_cells
+    )
+
+    head = (
+        "<thead><tr>"
+        + "".join(f"<th>{_inline(c)}</th>" for c in header_cells)
+        + "</tr></thead>"
+    )
+
+    body_rows: list[str] = []
+    id_col = header_cells.index("ID") if "ID" in header_cells else -1
+    kind_col = header_cells.index("Kind") if "Kind" in header_cells else -1
+    status_col = header_cells.index("Status") if "Status" in header_cells else -1
+    user_input_col = (
+        header_cells.index("User input") if "User input" in header_cells else -1
+    )
+    for row in rows:
+        if (
+            is_clarification_table
+            and id_col >= 0
+            and id_col < len(row)
+            and re.fullmatch(r"C-\d+", row[id_col])
+            and user_input_col >= 0
+        ):
+            response_id = row[id_col]
+            kind = row[kind_col] if 0 <= kind_col < len(row) else ""
+            status = row[status_col] if 0 <= status_col < len(row) else ""
+            cells_html: list[str] = []
+            for idx, cell in enumerate(row):
+                if idx == user_input_col:
+                    cells_html.append(
+                        f"<td>{_form_control(response_id, kind, status, cell)}</td>"
+                    )
+                else:
+                    cells_html.append(f"<td>{_inline(cell)}</td>")
+            body_rows.append(
+                f'<tr data-response-id="{html.escape(response_id)}" '
+                f'data-kind="{html.escape(kind)}" '
+                f'data-status="{html.escape(status)}">'
+                + "".join(cells_html)
+                + "</tr>"
+            )
+        else:
+            body_rows.append(
+                "<tr>" + "".join(f"<td>{_inline(c)}</td>" for c in row) + "</tr>"
+            )
+
+    body = "<tbody>" + "".join(body_rows) + "</tbody>"
+    return f"<table>{head}{body}</table>", i - start
+
+
+def _form_control(response_id: str, kind: str, status: str, current_value: str) -> str:
+    rid = html.escape(response_id)
+    disabled = "" if status.lower() in ("open", "answered", "") else " disabled"
+    safe_value = html.escape(current_value or "")
+    placeholder = {
+        "material": "파일 경로 또는 본문",
+        "decision": "선택 또는 짧은 응답",
+        "data-point": "값",
+    }.get(kind.lower(), "응답")
+    return (
+        f'<textarea name="{rid}" data-response-id="{rid}" '
+        f'data-kind="{html.escape(kind)}" rows="2" '
+        f'placeholder="{html.escape(placeholder)}"{disabled}>'
+        f"{safe_value}</textarea>"
+    )
+
+
+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"<li>{_inline(text)}</li>")
+        i += 1
+    return f"<{tag}>" + "".join(items) + f"</{tag}>", i - start
+
+
+def _inline(text: str) -> str:
+    out = html.escape(text)
+    # Restore inline markdown after escaping (we re-process the escaped
+    # forms — backticks/asterisks/brackets survive html.escape).
+    out = _INLINE_CODE_PATTERN.sub(lambda m: f"<code>{m.group(1)}</code>", out)
+    out = _BOLD_PATTERN.sub(lambda m: f"<strong>{m.group(1)}</strong>", out)
+    out = _LINK_PATTERN.sub(
+        lambda m: f'<a href="{m.group(2)}">{m.group(1)}</a>', out
+    )
+    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
+
+
+def serialize_user_response(
+    *,
+    run_meta: RunMeta,
+    entries: list[UserResponseEntry],
+    created_at: str,
+) -> 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.
+    """
+    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"
+        "created-by: user\n"
+        f"created-at: {created_at}\n"
+        "---\n"
+        "\n"
+        "# User Response\n"
+    )
+    body_chunks: list[str] = []
+    for e in entries:
+        chunk = (
+            f"\n## {e.response_id}\n"
+            f"- Kind: {e.kind}\n"
+            "- Value:\n"
+            f"  > {e.value.strip()}\n"
+        )
+        if e.rationale:
+            chunk += f"- Rationale: {e.rationale.strip()}\n"
+        body_chunks.append(chunk)
+    if not entries:
+        body_chunks.append("\n_(No user responses recorded.)_\n")
+    return head + "".join(body_chunks)
+
+
+# --------------------------------------------------------------------------- #
+# Convenience entrypoint for tests + CLI.
+# --------------------------------------------------------------------------- #
+
+def render_both_views(
+    src_md_path: Path,
+    *,
+    run_meta: RunMeta,
+    css: str,
+    js: str,
+) -> tuple[Path, Path]:
+    """Write ``*.slim.md`` and ``*.html`` next to ``src_md_path`` and
+    return their paths. Idempotent."""
+    src_text = src_md_path.read_text(encoding="utf-8")
+
+    slim_path = src_md_path.with_suffix(".slim.md")
+    if src_md_path.suffix == ".md":
+        # ``with_suffix`` replaces the LAST suffix only; we want
+        # ``foo.md`` → ``foo.slim.md`` (insert before ``.md``).
+        slim_path = src_md_path.with_name(src_md_path.stem + ".slim.md")
+
+    html_path = src_md_path.with_name(src_md_path.stem + ".html")
+
+    slim_text = slim_markdown(src_text, task_type=run_meta.task_type)
+    html_text = render_html(src_text, run_meta=run_meta, css=css, js=js)
+
+    slim_path.write_text(slim_text, encoding="utf-8")
+    html_path.write_text(html_text, encoding="utf-8")
+    return slim_path, html_path