okstra 0.54.0 → 0.56.0

package/runtime/python/okstra_ctl/render_final_report.py

@@ -10,9 +10,17 @@ the canonical user-facing markdown.
 Why this exists: prior to v0.32, report-writer-worker wrote the markdown
 directly. Free-form authoring led to silent contract violations — missing
 columns in the Execution Status table, omitted §4 phase-continuation
-rows, invented ``## Index`` sections. Routing everything through one
+rows, ad-hoc ``## Index`` sections. Routing everything through one
 template + schema cuts those failure modes to zero.
 
+The top-of-report ``## Index`` is now a *deterministic* post-render
+section: after Jinja2 renders the body, ``_inject_index_and_anchors``
+appends a scroll anchor to every heading and every ID-defining table row,
+links in-body ID references to their definition, and builds the index
+(section list + ID index) — so every ``FU-001`` / ``E-001`` / ``S-001``
+token is clickable and the reader can jump to any section. This runs on
+every render (including the Phase 7 re-render) and is idempotent.
+
 Phase 7 mutation flow: ``okstra-token-usage.py --substitute-data`` fills
 the ``tokenUsage`` and ``executionStatus[].totalTokens`` etc. cells in
 data.json, then re-invokes this renderer so the markdown stays in sync.
@@ -27,6 +35,7 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import sys
 from pathlib import Path
 from typing import Any
@@ -110,6 +119,215 @@ def _yaml_inline_list(values: list[str]) -> str:
     return "[" + ", ".join(_yaml_scalar(v) for v in values) + "]"
 
 
+# --- Index / scroll-anchor post-render pass -------------------------------
+# After Jinja2 renders the body, every report gets a top-of-report index and
+# clickable scroll anchors. An ID is *defined* when it is the leading token of
+# a table row's first cell (`| **FU-001**<br>… |` or `| C-001 | …`); that row
+# gets an `<a id="…">` anchor. Every other in-body mention of a *uniquely*
+# defined ID becomes a `[ID](#anchor)` link. Same ID string defined in two
+# sections (e.g. `C-001` in §1 Clarification AND §6.1 Consensus) gets two
+# distinct anchors and its bare references are left unlinked — an ambiguous
+# reference must not silently jump to the wrong row.
+_HEADING_RE = re.compile(r"^(#{1,6})[ \t]+(.*?)[ \t]*$")
+_FENCE_RE = re.compile(r"^[ \t]*(?:```|~~~)")
+_FIRST_CELL_ID_RE = re.compile(r"^[ \t]*\*{0,2}([A-Z]{1,4}-\d{3,})\b")
+# A reference token: an ID not glued to a word char / `-` on either side and
+# not prefixed by `:` (which would make it a `<worker>:<item-id>` source ref).
+_REF_ID_RE = re.compile(r"(?<![:\w-])[A-Z]{1,4}-\d{3,}(?![\w-])")
+
+
+def _slugify(text: str) -> str:
+    slug = re.sub(r"[^\w\s-]", "", text.strip().lower())
+    slug = re.sub(r"[\s_]+", "-", slug).strip("-")
+    return slug or "section"
+
+
+def _dedupe(base: str, used: set[str]) -> str:
+    candidate, suffix = base, 1
+    while candidate in used:
+        suffix += 1
+        candidate = f"{base}-{suffix}"
+    used.add(candidate)
+    return candidate
+
+
+def _code_line_mask(lines: list[str]) -> list[bool]:
+    """Mark lines the anchor / reference passes must never rewrite: fenced
+    code blocks (git status dumps, etc.) and the leading YAML frontmatter
+    (a `task-id` that happens to look like an ID must not be linkified)."""
+    frontmatter_end = -1
+    if lines and lines[0].strip() == "---":
+        for k in range(1, len(lines)):
+            if lines[k].strip() == "---":
+                frontmatter_end = k
+                break
+    mask, in_fence = [], False
+    for i, line in enumerate(lines):
+        if i <= frontmatter_end:
+            mask.append(True)
+        elif _FENCE_RE.match(line):
+            mask.append(True)
+            in_fence = not in_fence
+        else:
+            mask.append(in_fence)
+    return mask
+
+
+def _first_cell(line: str) -> str | None:
+    if not line.lstrip().startswith("|"):
+        return None
+    parts = line.split("|")
+    return parts[1] if len(parts) >= 3 else None
+
+
+def _scan_structure(lines: list[str], mask: list[bool]) -> tuple[list, list]:
+    """Collect (level, text, slug, line_idx) headings and {id, section,
+    line} definitions in document order. H1 (the title) is skipped."""
+    headings: list = []
+    definitions: list = []
+    used_slugs: set[str] = set()
+    current_section: str | None = None
+    for i, line in enumerate(lines):
+        if mask[i]:
+            continue
+        heading = _HEADING_RE.match(line)
+        if heading:
+            if len(heading.group(1)) < 2:
+                continue  # H1 title — not an index entry, no anchor
+            text = heading.group(2).strip()
+            slug = _dedupe(_slugify(text), used_slugs)
+            headings.append((len(heading.group(1)), text, slug, i))
+            current_section = text
+            continue
+        cell = _first_cell(line)
+        if cell is None:
+            continue
+        match = _FIRST_CELL_ID_RE.match(cell)
+        if match:
+            definitions.append({"id": match.group(1), "section": current_section, "line": i})
+    return headings, definitions
+
+
+def _assign_anchors(definitions: list) -> dict[str, str]:
+    """Give every definition a unique anchor; return the id→anchor map for
+    the subset of IDs that are defined exactly once (safe to link)."""
+    used: set[str] = set()
+    counts: dict[str, int] = {}
+    for d in definitions:
+        counts[d["id"]] = counts.get(d["id"], 0) + 1
+    for d in definitions:
+        d["anchor"] = _dedupe(d["id"].lower(), used)
+    return {d["id"]: d["anchor"] for d in definitions if counts[d["id"]] == 1}
+
+
+def _inject_anchors(lines: list[str], headings: list, definitions: list) -> None:
+    for _level, _text, slug, i in headings:
+        if "<a id=" not in lines[i]:
+            lines[i] = lines[i].rstrip() + f' <a id="{slug}"></a>'
+    for d in definitions:
+        i = d["line"]
+        pos = lines[i].index(d["id"])
+        lines[i] = lines[i][:pos] + f'<a id="{d["anchor"]}"></a>' + lines[i][pos:]
+
+
+def _maybe_link(match: re.Match, id_to_anchor: dict[str, str]) -> str:
+    token = match.group(0)
+    anchor = id_to_anchor.get(token)
+    if anchor is None:
+        return token
+    # The definition site is already `<a id="…"></a>**FU-001**`; never wrap it.
+    if match.string[: match.start()].rstrip("*").endswith("</a>"):
+        return token
+    return f"[{token}](#{anchor})"
+
+
+def _link_references(lines: list[str], mask: list[bool], id_to_anchor: dict[str, str]) -> None:
+    if not id_to_anchor:
+        return
+    for i, line in enumerate(lines):
+        if mask[i]:
+            continue
+        # Split on backticks so inline-code spans (odd segments) are skipped.
+        segments = line.split("`")
+        for j in range(0, len(segments), 2):
+            segments[j] = _REF_ID_RE.sub(lambda m: _maybe_link(m, id_to_anchor), segments[j])
+        lines[i] = "`".join(segments)
+
+
+def _build_index(headings: list, definitions: list, labels: dict) -> list[str]:
+    # The section list / ID index use bold labels, not `###` sub-headings, so
+    # the HTML view's auto-TOC (report_views._build_toc) doesn't pick them up
+    # as navigable headings.
+    heading = labels.get("heading", "Index")
+    block = [f'## {heading} <a id="report-index"></a>', "", f'**{labels.get("sectionsLabel", "Sections")}**', ""]
+    for level, text, slug, _i in headings:
+        block.append(f'{"  " * (level - 2)}- [{text}](#{slug})')
+    block += ["", f'**{labels.get("idIndexLabel", "ID Index")}**', ""]
+    if not definitions:
+        block += [labels.get("noIds", "- (no tracked IDs in this report.)"), ""]
+        return block
+    groups: list = []
+    order: dict = {}
+    for d in definitions:
+        section = d["section"] or "—"
+        if section not in order:
+            order[section] = len(groups)
+            groups.append((section, []))
+        groups[order[section]][1].append((d["id"], d["anchor"]))
+    for section, items in groups:
+        links = ", ".join(f"[{tok}](#{anchor})" for tok, anchor in items)
+        block.append(f"- **{section}**: {links}")
+    block.append("")
+    return block
+
+
+def _inject_index_and_anchors(markdown: str, dictionary: dict | None) -> str:
+    """Append scroll anchors + a top-of-report index to a rendered report.
+    Idempotent: re-running on already-anchored markdown is a no-op for
+    headings (anchor already present) and re-derives the same anchors."""
+    # Idempotent: a markdown that already carries the index anchor has been
+    # processed (or hand-seeded) — re-running must not stack a second index.
+    if '<a id="report-index"' in markdown:
+        return markdown
+    labels = (dictionary or {}).get("index", {})
+    lines = markdown.split("\n")
+    mask = _code_line_mask(lines)
+    headings, definitions = _scan_structure(lines, mask)
+    if not headings:
+        return markdown
+    id_to_anchor = _assign_anchors(definitions)
+    _inject_anchors(lines, headings, definitions)
+    _link_references(lines, mask, id_to_anchor)
+    insert_at = headings[0][3]
+    lines = lines[:insert_at] + _build_index(headings, definitions, labels) + lines[insert_at:]
+    return "\n".join(lines)
+
+
+def inject_index_into_file(md_path: Path, *, report_language: str = "en") -> int:
+    """Apply the top-of-report index + scroll anchors to an already-written
+    markdown report, in place. This is the seam for task-types that author
+    the markdown free-form (``improvement-discovery``) instead of through the
+    data.json renderer — every other task-type gets the same treatment inside
+    ``render()``. Idempotent (the index anchor guards re-runs). Returns the
+    number of bytes written.
+    """
+    if not md_path.is_file():
+        raise FinalReportRenderError(f"report markdown not found: {md_path}")
+    if report_language not in SUPPORTED_LANGS:
+        raise FinalReportRenderError(
+            f"report_language must be one of {SUPPORTED_LANGS}, got {report_language!r}"
+        )
+    try:
+        dictionary = load_dictionary(report_language)
+    except I18nError as exc:
+        raise FinalReportRenderError(str(exc)) from exc
+    injected = _inject_index_and_anchors(md_path.read_text(encoding="utf-8"), dictionary)
+    tmp = md_path.with_suffix(md_path.suffix + f".tmp.{os.getpid()}")
+    tmp.write_text(injected, encoding="utf-8")
+    tmp.replace(md_path)
+    return len(injected.encode("utf-8"))
+
+
 def _enforce_schema(data: dict) -> None:
     """렌더 전에 data.json 을 스키마에 대해 검증하는 seam.
 
@@ -203,7 +421,8 @@ def render(
 
     try:
         template = env.get_template(template_path.name)
-        return template.render(**data)
+        rendered = template.render(**data)
+        return _inject_index_and_anchors(rendered, dictionary)
     except I18nError as exc:
         raise FinalReportRenderError(
             f"i18n lookup failed while rendering {template_path.name}: {exc}"

package/runtime/python/okstra_ctl/report_views.py

@@ -169,8 +169,12 @@ def _markdown_to_html(
         m_heading = _HEADING_PATTERN.match(line)
         if m_heading:
             level = len(m_heading.group(1))
-            text = m_heading.group(2)
-            slug = _slugify(text)
+            # The final-report renderer appends an explicit scroll anchor to
+            # each heading (`## Verdict Card <a id="verdict-card"></a>`). Honor
+            # that id as the slug (keeps markdown ↔ HTML anchors consistent and
+            # language-independent) and drop it from the displayed text.
+            explicit_id, text = _split_heading_anchor(m_heading.group(2))
+            slug = explicit_id or _slugify(text)
             current_section_path = _update_section_path(current_section_path, level, line)
             out.append(f'<h{level} id="{slug}">{_inline(text)}</h{level}>')
             headings.append((level, slug, text))
@@ -235,11 +239,26 @@ def _markdown_to_html(
     return "\n".join(out), headings
 
 
+_HEADING_ANCHOR_RE = re.compile(r'\s*<a id="([^"]+)"></a>\s*$')
+
+# The renderer's top-of-report Index section (`## Index`/`## 목차` carrying
+# `<a id="report-index">`, followed by bold-labelled bullet lists). The whole
+# section — heading through the bullet lists, up to the next h2 — is replaced
+# by the auto-built nav.
 _INDEX_BLOCK_RE = re.compile(
-    r'<h2 id="index">Index</h2>\n<ul>.*?</ul>', re.DOTALL
+    r'<h2 id="report-index">.*?(?=<h2|\Z)', re.DOTALL
 )
 
 
+def _split_heading_anchor(text: str) -> tuple[Optional[str], str]:
+    """Split a trailing ``<a id="…"></a>`` off a heading's text. Returns
+    ``(explicit_id_or_None, display_text)``."""
+    match = _HEADING_ANCHOR_RE.search(text)
+    if match:
+        return match.group(1), text[: match.start()].rstrip()
+    return None, text
+
+
 def _build_toc(headings: list[tuple[int, str, str]]) -> str:
     """Render a ``<nav class="toc">`` block from collected h2/h3 entries.
     h1 (the report title) is omitted; h4+ are too granular for the TOC."""
@@ -247,7 +266,7 @@ def _build_toc(headings: list[tuple[int, str, str]]) -> str:
     for level, slug, text in headings:
         if level not in (2, 3):
             continue
-        if slug == "index":  # skip the source "Index" heading itself
+        if slug == "report-index":  # skip the source Index/목차 heading itself
             continue
         cls = "toc-h2" if level == 2 else "toc-h3"
         items.append(

package/runtime/python/okstra_ctl/run.py

@@ -276,6 +276,9 @@ class PrepareInputs:
     work_category: str = ""
     base_ref: str = ""
     approved_plan_path: str = ""
+    # implementation 전용: `--qa-waiver "<stageKey>:<reason>"` 사용자 확인형 우회.
+    # prepare-time 에 task-level conformance 매니페스트 entry.waiver 를 채운다.
+    qa_waiver: str = ""
     stage: str = "auto"
     clarification_response_path: str = ""  # absolute or empty
     # release-handoff 전용: PR 본문 템플릿 1회성 override. 빈 문자열이면
@@ -1092,6 +1095,28 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
     return ctx_stage_map
 
 
+def _apply_qa_waiver_if_requested(inp: "PrepareInputs", project_root: Path) -> None:
+    """`--qa-waiver` 가 있으면 task-level 매니페스트 entry 의 waiver 를 채운다."""
+    if not inp.qa_waiver:
+        return
+    from .conformance import apply_qa_waiver, parse_qa_waiver_arg
+    from .paths import task_dir
+    parsed = parse_qa_waiver_arg(inp.qa_waiver)
+    if parsed is None:
+        raise PrepareError(
+            f'--qa-waiver must be "<stageKey>:<reason>", got {inp.qa_waiver!r}'
+        )
+    stage_key, reason = parsed
+    manifest_path = task_dir(project_root, inp.task_group, inp.task_id) / "qa" / "conformance-manifest.json"
+    if not manifest_path.is_file():
+        raise PrepareError(f"--qa-waiver: conformance manifest not found at {manifest_path}")
+    manifest = json.loads(manifest_path.read_text())
+    when = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    if not apply_qa_waiver(manifest, stage_key, reason, at=when):
+        raise PrepareError(f"--qa-waiver: stageKey {stage_key!r} not in manifest {manifest_path}")
+    manifest_path.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n")
+
+
 def _register_and_check_project(project_root: Path, inp: PrepareInputs) -> None:
     """project.json self-registration + (implementation 한정) qaCommands gate 검증."""
     from okstra_project import ResolverError
@@ -1120,6 +1145,7 @@ def _register_and_check_project(project_root: Path, inp: PrepareInputs) -> None:
             qa_errors = validate_qa_commands(project_meta.get("qaCommands"))
             if qa_errors:
                 raise PrepareError(_format_qa_errors(qa_errors))
+        _apply_qa_waiver_if_requested(inp, project_root)
 
 
 def _resolve_roster(inp: PrepareInputs, profile_file: Path) -> tuple[list[str], str]:
@@ -1860,6 +1886,8 @@ def main(argv: list[str]) -> int:
     p.add_argument("--critic", default="")
     p.add_argument("--related-tasks", default="", dest="related_tasks_raw")
     p.add_argument("--approved-plan", default="", dest="approved_plan_path")
+    p.add_argument("--qa-waiver", default="", dest="qa_waiver",
+                   help='Stage conformance 우회: "<stageKey>:<reason>" (사용자 확인형, 매니페스트 entry.waiver 기록)')
     p.add_argument(
         "--stage", default="auto", dest="stage",
         help=(
@@ -1975,6 +2003,7 @@ def main(argv: list[str]) -> int:
         work_category=args.work_category,
         base_ref=args.base_ref,
         approved_plan_path=args.approved_plan_path,
+        qa_waiver=args.qa_waiver,
         stage=args.stage,
         clarification_response_path=clarification_abs,
         pr_template_path=args.pr_template_path,

package/runtime/skills/okstra-run/SKILL.md

@@ -184,6 +184,18 @@ The python function underneath is mutex-protected (`~/.okstra/.locks/<task-key>.
 
 You can delete the literal state-file path after this point — its job is done. Invoke `rm` with the literal path (e.g. `rm /var/folders/.../okstra-wizard.AbCd.json`), not a shell variable.
 
+### Step 5.1 (implementation only): conformance waiver offer
+
+`render-bundle` accepts an optional `--qa-waiver "<stageKey>:<reason>"` flag (implementation only). It records a **user-acknowledged** waiver into the task-level conformance manifest entry (`entry.waiver`), letting the run proceed when a stage's Tier 3 conformance script genuinely cannot run (e.g. the replica DB is unreachable). The waiver records the user's reason **verbatim**.
+
+This is **never** a lead/worker self-exemption — only the user may waive. Offer it **only** when conformance BLOCKING is expected (the chosen stage declares a conformance entry whose script you cannot run in this environment). Surface it as a 3-option recommendation picker (per the run-prompt recommendation rule):
+
+1. (recommended) Run the conformance script — no waiver.
+2. Waive this stage — ask the user for the exact `<stageKey>` and reason, then pass `--qa-waiver "<stageKey>:<reason>"` to `render-bundle` (reason = the user's words, unedited).
+3. 직접 입력 — the user types the full `<stageKey>:<reason>` value.
+
+When the user picks a waiver, append `--qa-waiver "<stageKey>:<reason>"` to the `render-bundle` invocation above. Omit the flag entirely otherwise (do **not** pass `--qa-waiver ""`). A malformed value or unknown `<stageKey>` aborts `render-bundle` with a `PrepareError`.
+
 ## Step 6: Take over as Claude lead
 
 Read `<INSTRUCTION_SET_PATH>/claude-execution-prompt.md` verbatim and enter `Claude lead` mode. The lead prompt now points to compact intake artifacts first (`active-run-context`, `analysis-profile.md`, and `analysis-packet.md`); full source files such as `analysis-material.md`, `reference-expectations.md`, and `final-report-template.md` are lazy/fallback inputs. Follow the rendered prompt order, do not preempt it.

package/runtime/skills/okstra-setup/SKILL.md

@@ -181,6 +181,41 @@ The field is preserved across the runtime's auto-upserts of
 `updatedAt` are runtime-owned, so manual edits to `qaCommands`
 survive every subsequent `okstra setup` / `okstra run` invocation.
 
+### Step 4.6.1 (optional): `qaEnv` — Tier 3 conformance environment
+
+`implementation` / `final-verification` verifiers run **stage
+conformance scripts** (Tier 3) that may need to reach a database or an
+HTTP endpoint to prove the diff satisfies upstream requirements. Declare
+the environment those scripts are allowed to touch under `qaEnv`. Every
+field is optional; declare only what your conformance scripts use.
+
+```json
+"qaEnv": {
+  "replicaDbDsn": "<replica/test DB DSN — never shared/staging/prod>",
+  "appBaseUrl": "http://localhost:3000",
+  "envFile": ".okstra/qa.env",
+  "surfacePatterns": { "db": ["*.sql", "*repository*"], "http": ["*controller*"] }
+}
+```
+
+- `replicaDbDsn` — DSN the conformance script connects to. MUST be a
+  replica / disposable test DB, **never** a shared, staging, or
+  production database (conformance scripts may write).
+- `appBaseUrl` — base URL for endpoint-level conformance checks
+  (local app only).
+- `envFile` — path (under `.okstra/`) to an env file the verifier
+  sources before running conformance scripts.
+- `surfacePatterns` — per-project **override** of the diff-surface
+  cross-check map (`capability → glob list`). The validator maps each
+  changed file to a capability surface (`db` / `http` / `io`) and fails
+  the run when the diff touches a surface no stage `requires`. The
+  built-in patterns (e.g. `*router*` for `http`, `*storage*` for `io`)
+  are broad and match many front-end files, so front-end-heavy repos
+  should override with narrower globs to avoid false BLOCKING verdicts
+  (Phase 4b review note). An over-broad pattern over-blocks; an
+  over-narrow one lets an undeclared surface through — tune to the
+  repo's real db/http/io file naming.
+
 ## Step 4.7 (automatic): project-local Claude settings symlink
 
 `okstra setup` (and `okstra run` on its first invocation per project)

package/runtime/templates/reports/i18n/en.json

@@ -137,5 +137,11 @@
     "columnRequirement": "Requirement (plan/brief citation)",
     "verificationScope": "Verification scope",
     "stageReportsLabel": "Source implementation reports (per stage)"
+  },
+  "index": {
+    "heading": "Index",
+    "sectionsLabel": "Sections",
+    "idIndexLabel": "ID Index",
+    "noIds": "- (no tracked IDs in this report.)"
   }
 }

package/runtime/templates/reports/i18n/ko.json

@@ -137,5 +137,11 @@
     "columnRequirement": "Requirement (plan/brief 인용)",
     "verificationScope": "검증 범위",
     "stageReportsLabel": "stage 별 구현 리포트"
+  },
+  "index": {
+    "heading": "목차",
+    "sectionsLabel": "섹션",
+    "idIndexLabel": "ID 색인",
+    "noIds": "- (이 보고서에 추적 대상 ID 가 없습니다.)"
   }
 }

package/runtime/validators/lib/fixtures.sh

@@ -323,6 +323,15 @@ if not isinstance(required_status_entries, list):
 report_lines = [
     "# Validation Fixture Report",
     "",
+    # Top-of-report Index — the renderer injects this on real runs; the
+    # hand-crafted fixture mirrors it so validate_report's index/anchor
+    # contract (introduced with the clickable-ID pass) is satisfied.
+    '## Index <a id="report-index"></a>',
+    "",
+    "### Sections",
+    "",
+    "- [Verdict Card](#verdict-card)",
+    "",
     "## Verdict Card",
     "",
     "| 항목 | 값 |",

package/runtime/validators/validate-implementation-plan-stages.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""S1–S10 checks for the Stage Map structure of an approved
+"""S1–S11 checks for the Stage Map structure of an approved
 implementation-planning final-report.md. Run from prepare_task_bundle
 of `implementation` task or standalone."""
 
@@ -40,7 +40,7 @@ class StageMeta:
 
 @dataclass
 class ValidationError:
-    code: str   # S1..S10
+    code: str   # S1..S11
     stage: int  # 0 = global
     message: str
 
@@ -168,6 +168,8 @@ def _check_each_stage_section(text: str, stages: List[StageMeta]) -> List[Valida
 SLICE_VALUE = re.compile(r"^\s*Slice value\s*:\s*(.+?)\s*$", re.M)
 ACCEPTANCE = re.compile(r"^\s*Acceptance\s*:\s*(.+?)\s*$", re.M)
 TDD_EXEMPTION = re.compile(r"^\s*TDD exemption\s*:\s*\S", re.M)
+CONFORMANCE_TESTS = re.compile(r"^\s*Conformance tests\s*:\s*\S", re.M)
+CONFORMANCE_EXEMPTION = re.compile(r"^\s*Conformance exemption\s*:\s*\S", re.M)
 
 
 def _check_slice_tdd(text: str, stages: List[StageMeta]) -> List[ValidationError]:
@@ -204,6 +206,28 @@ def _check_slice_tdd(text: str, stages: List[StageMeta]) -> List[ValidationError
     return errs
 
 
+def _check_conformance_declaration(
+    text: str, stages: List[StageMeta]
+) -> List[ValidationError]:
+    """S11: 각 stage 는 conformance 검증을 선언하거나 명시적으로 면제한다.
+
+    S11 — `Conformance tests:` 라인(Tier3 검증 스크립트 선언) 또는
+          `Conformance exemption:` 라인(테스트 불필요 사유) 중 하나 필수.
+    diff 가 db/io/http surface 를 건드렸는데 아무 선언이 없는 silent-pass(DEV-9184)
+    를 planning boundary 에서 차단한다.
+    """
+    errs: List[ValidationError] = []
+    for s in stages:
+        section = _slice_stage_section(text, s.stage_number)
+        if not (CONFORMANCE_TESTS.search(section) or CONFORMANCE_EXEMPTION.search(section)):
+            errs.append(ValidationError(
+                "S11", s.stage_number,
+                "S11: stage must declare 'Conformance tests:' (Tier3 검증 스크립트) "
+                "or 'Conformance exemption:' (사유) — stage conformance QA design §12.2",
+            ))
+    return errs
+
+
 def _check_depends_on(stages: List[StageMeta]) -> List[ValidationError]:
     errs: List[ValidationError] = []
     valid = {s.stage_number for s in stages}
@@ -274,7 +298,7 @@ def _check_parallel_safety(text: str, stages: List[StageMeta]) -> List[Validatio
 
 
 def collect_validation_errors(text: str) -> List[ValidationError]:
-    """All S1–S10 checks against the report text; empty list means valid.
+    """All S1–S11 checks against the report text; empty list means valid.
 
     S1 (missing `## 5.5 Stage Map` heading) makes the rest unparseable, so it
     short-circuits. Shared by `main()` (CLI / implementation entry) and the
@@ -290,6 +314,7 @@ def collect_validation_errors(text: str) -> List[ValidationError]:
     if stages:
         errors.extend(_check_each_stage_section(text, stages))
         errors.extend(_check_slice_tdd(text, stages))
+        errors.extend(_check_conformance_declaration(text, stages))
         errors.extend(_check_depends_on(stages))
         errors.extend(_check_parallel_safety(text, stages))
     return errors