"""Phase Z-2 MVP-1.5b — single slide + Type B + frame-derived adapted blocks.

원래 Phase Z 설계 복귀 (멀티-슬라이드 / native-fit 모두 폐기) :
- MDX 1 = slide 1
- slide-base → slide-body → layout preset (Type B) → zones[] → frame-derived block (zone-compatible adapt)
- frame은 시각 언어 / slot 구성 / 패턴의 source. native geometry 통째 삽입 X.
- AI 는 layout / zone / frame / variant 선택에 관여 X — code / catalog 가 결정.

MVP-1.5b spec :
- 대상 : MDX 03 (회귀)
- 출력 : data/runs/{run_id}/phase_z2/final.html (single slide)
- AI : 미사용 — MDX → slot_payload 결정론적 매핑
- status : matched_zone only — non-matched 발생 시 abort + error.json
- layout : 2 sections → Type B (top + bottom zones)
- Frame partials : templates/phase_z2/families/{template_id}.html (Figma 시각 언어 promote, geometry adapt)
- Assets : render time copy → data/runs/{run_id}/phase_z2/assets/{template_id}/

상세 설계 :
- docs/architecture/PHASE-Z-CATALOG-RUNTIME-DESIGN.md § 17 (frame-derived partial promotion + zone-compatible adapt)

이전 실험 실패 기록 :
- mvp1_test5    : scaffold 임의 — frame 느낌 부재
- mvp1.5_test3  : frame native 통째 — slide 대체
- mvp1.5a_test1 : 멀티-슬라이드 — MDX 1=slide 1 위반
- mvp1.5b_test*  : 본 모듈, 원래 설계 라인 합류
"""

import copy
import hashlib
import json
import os
import re
import shutil
import sys
import time
from dataclasses import asdict, dataclass, field, replace
from html.parser import HTMLParser
from pathlib import Path
from typing import Any, NoReturn, Optional

import yaml
from jinja2 import Environment, FileSystemLoader, select_autoescape

try:
    from mdx_text_atoms import extract_text_atoms, normalize_text_atom
except ImportError:  # pragma: no cover - script/module invocation compatibility
    from src.mdx_text_atoms import extract_text_atoms, normalize_text_atom

from phase_z2_composition import (
    LAYOUT_PRESETS,
    CompositionUnit,
    compose_zone_popup_payload,
    derive_parent_id,
    plan_composition,
    resplit_all_reject_merges,
    select_display_strategy_candidates,
    select_layout_preset,
    select_layout_candidates,
    select_region_layout_candidates,
)
from phase_z2_mapper import (
    FitError,
    compute_capacity_fit,
    get_contract,
    load_frame_contracts,
    load_v4_fallback_policy,
    map_with_contract,
    normalize_markdown_inline_text,
)
from phase_z2_classifier import classify_visual_runtime_check
from phase_z2_router import plan_details_popup_escalation, route_fit_classification
from phase_z2_retry import (
    DEFAULT_SAFETY_MARGIN_PX,
    apply_cross_zone_redistribute_css,
    apply_frame_internal_fit_candidate_css,
    apply_glue_compression_css,
    apply_image_fit_css,
    apply_layout_adjust_layout_css,
    apply_retry_to_layout_css,
    plan_cross_zone_redistribute,
    plan_frame_internal_fit_candidate,
    plan_glue_compression,
    plan_image_fit,
    plan_layout_adjust,
    plan_zone_ratio_retry,
)
from phase_z2_failure_router import (
    enrich_retry_trace_with_failure_classification,
    route_retry_failure,
)

# trace-only runtime 연결 v0 — B1 → B4 chain.
# final.html / mapper / render path 미영향. debug_zones[i].placement_trace 만 기록.
from phase_z2_content_extractor import extract_content_objects, extract_rich_content_objects
from phase_z2_placement_planner import (
    TRACE_KEY_B4_PARTIAL_MISSING_SKIP,
    TRACE_KEY_B4_V0_FALLBACK_REASON,
    TRACE_KEY_FRAME_SELECTION_BASIS,
    TRACE_KEY_V4_B4_FRAME_MATCH,
    TRACE_KEY_V4_EVIDENCE_CONSUMED,
    TRACE_KEY_V4_RANK_USED,
    plan_placement,
)

# IMP-47B u4 — Step 12 AI repair wiring. gather() short-circuits at the
# router when settings.ai_fallback_enabled is False (default), so import
# at module load is safe for the AI=0 normal path (PZ-1). Activation gate
# stays in src/config.py + src/phase_z2_ai_fallback/router.py.
from src.phase_z2_ai_fallback.step12 import gather_step12_ai_repair_proposals

# IMP-35 (#64) u5 — Step 17 deterministic POPUP gate executor. Runs after
# the salvage cascade exhausts at cascade-terminal action
# ``details_popup_escalation`` (router u3 / failure_router u2) and BEFORE
# the AI_REPAIR cascade stage. Stamps ``popup_escalation_plan`` and the
# idempotent ``has_popup`` marker onto retry_trace per unit. No AI call.
from src.phase_z2_ai_fallback.step17 import run_step17_popup_gate

# IMP-43 (#72) u3 — Step 6 reuse snapshot sidecar (JSON-only). Schema +
# serializers + validator live in u2 (``src.phase_z2_reuse_snapshot``);
# this module's call site at the Step 6 boundary writes the sidecar
# alongside ``steps/step06_composition_plan.json`` so that future
# ``--reuse-from`` runs (u4) can resume at Step 7 without re-deriving
# Step 0/1/2/5/6 state. ``--reuse-from`` is u4 scope; here we only
# WRITE the snapshot — restore wiring lands in u4.
from src.phase_z2_reuse_snapshot import build_snapshot, SNAPSHOT_FILENAME

# IMP-56 (#90) u5 — Step 12 text_overrides apply. Pure deterministic; no AI.
# u4 resolver imports are aliased with leading-underscore so the helper at
# `_apply_text_overrides_to_zones` reads as a pipeline-private wrapper
# (mirrors the AI-repair u5 / image-overrides u7 wrapper naming pattern).
from src.text_override_resolver import (
    apply_text_override as _apply_text_override,
    validate_text_overrides as _validate_text_overrides,
    InvalidTextOverride as _InvalidTextOverride,
)
# IMP-56 (#90) u7 — Step 12 structure_overrides apply. Pure deterministic; no AI.
# u6 resolver imports are aliased with leading-underscore so the helper at
# `_apply_structure_overrides_to_zones` reads as a pipeline-private wrapper
# (mirrors the u5 text_overrides wrapper naming pattern). SCOPE LOCKED to
# slot_order + hidden_slots — frame swap stays on the existing `frames`
# axis to preserve Phase Z's no-AI-HTML-structure invariant.
from src.structure_override_resolver import (
    apply_structure_override as _apply_structure_override,
    validate_structure_overrides as _validate_structure_overrides,
)
# IMP-56 (#90) u9 — Step 13 text_path stamping wired into render_slide.
# u8 stamper injects ``data-text-path="{slot_key}.{line_index}"`` onto each
# ``text-line`` opening tag so the frontend SlideCanvas (u10+) can attribute
# per-line edits back to the ``text_overrides`` axis (u1 schema, u4 resolver,
# u5 Step-12 apply). Pure deterministic; no AI / HTTP / subprocess.
from src.text_path_stamper import stamp_zone_html as _stamp_zone_html
# IMP-94 (#94) u2 — Step 11/13/21 region/content marker stamping wired into
# render_slide. u1 stamper injects ``data-region-id`` + ``data-content-unit-id``
# onto each family-partial root ``<div>`` so Layer A telemetry (placement_trace
# ↔ DOM parity, Step 21 self-report, fit_classifier read targets §6.4) can
# resolve a rendered zone back to its PlacementPlan ``slot_assignments[]``
# entry. Pure deterministic; AI=0. Marker values flow via the per-zone
# ``placement_markers`` list (u3 projects live B4 PlacementPlan; u4 ensures
# non-live append paths default to ``placement_markers=[]``). Disjoint from
# #96 (``data-frame-slot-id``) by attribute name.
from src.region_marker_stamper import stamp_zone_html as _stamp_region_markers


# ─── Constants ──────────────────────────────────────────────────

PROJECT_ROOT = Path(__file__).parent.parent
TEMPLATE_DIR = PROJECT_ROOT / "templates" / "phase_z2"
TEMPLATE_ASSETS_BASE = TEMPLATE_DIR / "assets"
ASSETS_SOURCE_BASE = PROJECT_ROOT / "figma_to_html_agent" / "blocks"
V4_RESULT_PATH = PROJECT_ROOT / "tests" / "matching" / "v4_full32_result.yaml"
RUNS_DIR = PROJECT_ROOT / "data" / "runs"


def _rel_to_project(path: Path) -> str:
    """Return a project-relative trace path, falling back for external paths."""
    try:
        return str(path.relative_to(PROJECT_ROOT))
    except ValueError:
        return str(path)

# IMP-39 (#68) u1 — single-source ranking sort policy yaml.
# Loader + apply_ranking_sort helper below `to_phase_z_status`.
RANKING_SORT_POLICY_PATH = (
    PROJECT_ROOT / "templates" / "phase_z2" / "catalog" / "ranking_sort_policy.yaml"
)

# V4 label → Phase Z status (§ 7.4 매트릭스)
V4_LABEL_TO_PHASE_Z_STATUS = {
    "use_as_is": "matched_zone",
    "light_edit": "adapt_matched_zone",
    "restructure": "extract_matched_zone",
    "reject": "fallback_candidate",
}
MVP1_ALLOWED_STATUSES = {"matched_zone", "adapt_matched_zone"}

# Emergency P3 (2026-05-26) — generic_fallback frame for "no auto_renderable + no
# ai_adaptation_required candidates" case (= true catalog gap). Used by Phase B
# (empty_shell terminal 우회). 정책 :
#   - "__empty__" placeholder 금지 — 반드시 real catalog frame
#   - mdx 별 dispatch 금지 — universal (section count 무관)
#   - AI adaptation route mandatory (direct render X)
# 기본값 = three_parallel_requirements (mdx 03 검증된 안정 frame, 3-zone 으로 1~3
# sections 모두 대응). 환경 변수 PHASE_Z_GENERIC_FALLBACK_FRAME 로 override 가능.
GENERIC_FALLBACK_FRAME_TEMPLATE_ID = os.environ.get(
    "PHASE_Z_GENERIC_FALLBACK_FRAME",
    "three_parallel_requirements",
)
GENERIC_FALLBACK_FRAME_ID = "1171281190"  # three_parallel_requirements default frame_id


# Emergency P4 (2026-05-26) — inline AI redistribute helper.
# FitError + ai_adaptation_required unit 에 대해 direct anthropic 호출 (AiFallbackProposal
# strict schema 우회). 원문 보존 prompt + frame slot schema hint → JSON slot_payload.
# 실패 시 None 반환 — caller 가 기존 adapter_needed path 로 fallback.
# 정책: emergency.md §1 ("empty shell 금지, AI 가 원문 보존하며 frame slot 에 재배치").
_EMERGENCY_P4_AI_SCHEMA_HINTS: dict[str, str] = {
    "three_parallel_requirements": """{
  "title": "<slide title from raw content>",
  "pillars": [
    {
      "label": "<short label, 예: 기술(디지털)>",
      "label_main": "<main word>",
      "label_paren": "<(parenthetical)>",
      "color_class": "tech",
      "sections": [
        {"heading": "<sub heading>", "text_lines": [{"text": "<bullet text>", "indent": 0}, ...]}
      ]
    },
    {"label": "...", "label_main": "...", "label_paren": "...", "color_class": "people", "sections": [...]},
    {"label": "...", "label_main": "...", "label_paren": "...", "color_class": "nature", "sections": [...]}
  ]
}""",
}


# ════════════════════════════════════════════════════════════════════════
# Emergency P4b (2026-05-26) — code-side verbatim slot_payload builder
# (B-lite : per-frame verbatim builder, no AI, no fake labels).
#
# 정책 :
#   - 원문 텍스트 verbatim (mdx heading / bullets 그대로 사용)
#   - 가짜 라벨 생성 금지 — color_class 같은 CSS hint 만 deterministic cycle
#   - MDX content < frame slots → 빈 slot 유지 (가짜 채움 X)
#   - MDX content > frame slots → 일단 truncate (frame extension 은 후속 axis C)
#   - AI 호출 0회
# ════════════════════════════════════════════════════════════════════════


def _looks_like_logical_group_label(label: str) -> bool:
    """Return True for short frame-internal labels such as ``안전과 품질``."""
    normalized = normalize_markdown_inline_text(label or "")
    compact = re.sub(r"[\s()（）\[\]·ㆍ:：/-]+", "", normalized)
    return bool(compact) and len(compact) <= 8


def _split_label_main_paren(label: str) -> tuple[str, str]:
    """Split labels like ``기술(디지털)`` into main and parenthetical slots."""
    normalized = normalize_markdown_inline_text(label or "")
    m = re.match(r"^(.+?)(\([^)]*\)|（[^）]*）)\s*$", normalized)
    if not m:
        return normalized, ""
    return m.group(1).strip(), m.group(2).strip()


def _parse_mdx_raw_content(raw_content: str) -> list[dict]:
    """unit.raw_content 를 bullet_groups list 로 parse.

    Pattern : ``- **<label>**`` 가 group 시작, 그 아래 ``  - <text>`` 가 item.
    Returns : [{'label': str, 'items': [str]}, ...]
    """
    if not raw_content:
        return []
    groups: list[dict] = []
    current: Optional[dict] = None
    previous_blank = True
    for line in raw_content.splitlines():
        stripped = line.strip()
        if not stripped:
            previous_blank = True
            continue
        m_heading = re.match(r"^#{2,6}\s+(.+?)\s*$", stripped)
        if m_heading:
            label = normalize_markdown_inline_text(m_heading.group(1))
            current = {"label": label, "items": []}
            groups.append(current)
            previous_blank = False
            continue
        # group label: "- **xxx**"
        m_label = re.match(r"^[-*]\s*\*\*(.+?)\*\*\s*$", stripped)
        if m_label:
            label = normalize_markdown_inline_text(m_label.group(1))
            if current is None or previous_blank or _looks_like_logical_group_label(label):
                current = {"label": label, "items": []}
                groups.append(current)
            else:
                current["items"].append(label)
            previous_blank = False
            continue
        # nested item: "  - text" (2 spaces indent)
        m_item = re.match(r"^[-*]\s+(.+)$", stripped)
        if m_item and current is not None:
            txt = normalize_markdown_inline_text(m_item.group(1))
            if txt:
                current["items"].append(txt)
            previous_blank = False
            continue
        # top-level prose (no group yet) — start anonymous group
        if current is None and stripped:
            txt = normalize_markdown_inline_text(stripped)
            current = {"label": "", "items": [txt] if txt else []}
            groups.append(current)
        elif current is not None:
            txt = normalize_markdown_inline_text(stripped)
            if txt:
                current["items"].append(txt)
        previous_blank = False
    return groups


def _build_text_lines(items: list[str]) -> list[dict]:
    """items list → text_lines [{'text': str, 'indent': int}] verbatim."""
    return [
        {"text": normalized, "indent": 0}
        for item in items
        if (normalized := normalize_markdown_inline_text(item))
    ]


_THREE_COLOR_CYCLE = ["tech", "people", "nature"]
_PERSONA_COLOR_CYCLE = ["client", "constructor", "designer"]


def _registered_persona_role_labels(component_name: str = "DxEffect") -> set[str]:
    entry = ((_load_component_expansion_registry().get("components") or {}).get(component_name) or {})
    labels = entry.get("persona_role_labels") or []
    return {
        normalize_markdown_inline_text(str(label))
        for label in labels
        if normalize_markdown_inline_text(str(label))
    }


def _looks_like_decimal_subsection_label(label: str) -> bool:
    return bool(re.match(r"^\s*\d+\.\d+\s+", normalize_markdown_inline_text(label or "")))


def _merge_internal_context_groups(groups: list[dict]) -> list[dict]:
    """Keep child headings as context sections and nest local bullet labels.

    ``_parse_mdx_raw_content`` intentionally stays simple. For frame-internal
    persona mapping, headings such as ``2.1 ...`` are context sections, while
    short bold labels below them are local body labels, not independent
    persona cards.
    """

    merged: list[dict] = []
    current: Optional[dict] = None
    for group in groups:
        label = group.get("label", "") or ""
        items = list(group.get("items", []) or [])
        if _looks_like_decimal_subsection_label(label) or current is None:
            current = {"label": label, "items": items}
            merged.append(current)
            continue
        if label:
            current["items"].append(label)
        current["items"].extend(items)
    return merged


class _DxEffectTableParser(HTMLParser):
    """Extract source text from the registered DxEffect table component."""

    def __init__(self) -> None:
        super().__init__(convert_charrefs=True)
        self._tag_stack: list[str] = []
        self._current_cell: list[str] | None = None
        self._current_row: list[list[str]] | None = None
        self.header_rows: list[list[str]] = []
        self.body_rows: list[list[str]] = []

    def handle_starttag(self, tag: str, attrs) -> None:
        tag = tag.lower()
        self._tag_stack.append(tag)
        if tag == "tr":
            self._current_row = []
        elif tag in {"td", "th"}:
            self._current_cell = []
        elif tag == "br" and self._current_cell is not None:
            self._current_cell.append(" ")

    def handle_endtag(self, tag: str) -> None:
        tag = tag.lower()
        if tag in {"td", "th"} and self._current_cell is not None and self._current_row is not None:
            text = normalize_markdown_inline_text(" ".join(self._current_cell))
            self._current_row.append(text)
            self._current_cell = None
        elif tag == "tr" and self._current_row is not None:
            if any(self._current_row):
                if "thead" in self._tag_stack:
                    self.header_rows.append(self._current_row)
                else:
                    self.body_rows.append(self._current_row)
            self._current_row = None
        if tag in self._tag_stack:
            idx = len(self._tag_stack) - 1 - self._tag_stack[::-1].index(tag)
            del self._tag_stack[idx:]

    def handle_data(self, data: str) -> None:
        if self._current_cell is not None:
            cleaned = normalize_markdown_inline_text(data)
            if cleaned:
                self._current_cell.append(cleaned)


def _load_component_expansion_registry() -> dict:
    path = TEMPLATE_DIR / "catalog" / "component_expansion_registry.yaml"
    try:
        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
    except FileNotFoundError:
        return {"version": 0, "components": {}}
    return data if isinstance(data, dict) else {"version": 0, "components": {}}


def _expand_dx_effect_component(raw_content: str) -> tuple[str, list[dict]]:
    """Expand registered ``<DxEffect />`` into persona bullet groups."""

    if "<DxEffect" not in (raw_content or ""):
        return raw_content, []
    registry = _load_component_expansion_registry()
    entry = (registry.get("components") or {}).get("DxEffect")
    if not isinstance(entry, dict):
        return raw_content, [{
            "component": "DxEffect",
            "status": "unsupported",
            "reason": "component_not_registered",
        }]
    source_path = PROJECT_ROOT / str(entry.get("source_path") or "")
    try:
        source = source_path.read_text(encoding="utf-8")
    except FileNotFoundError:
        return raw_content, [{
            "component": "DxEffect",
            "status": "unsupported",
            "reason": "source_path_missing",
            "source_path": str(source_path),
        }]

    parser = _DxEffectTableParser()
    parser.feed(source)
    headers = parser.header_rows[0] if parser.header_rows else []
    persona_headers = [h for h in headers[1:] if h]
    personas: list[dict] = [{"label": h, "items": []} for h in persona_headers]
    for row in parser.body_rows:
        if len(row) < 2:
            continue
        category = row[0] or ""
        for idx, cell in enumerate(row[1:]):
            if idx >= len(personas) or not cell:
                continue
            item = f"{category}: {cell}" if category else cell
            personas[idx]["items"].append(item)

    lines: list[str] = []
    for persona in personas:
        label = persona.get("label") or ""
        if not label:
            continue
        lines.append(f"- **{label}**")
        items = persona.get("items") or []
        if items:
            lines.append(f"  - {' / '.join(items)}")
    expansion = "\n".join(lines).strip()
    expanded = re.sub(
        r"(?m)^\s*<DxEffect\s*/>\s*$",
        expansion,
        raw_content or "",
    )
    return expanded, [{
        "component": "DxEffect",
        "status": "expanded",
        "source_path": str(source_path.relative_to(PROJECT_ROOT)),
        "persona_count": len(personas),
        "body_row_count": len(parser.body_rows),
        "expanded_node_types": list(entry.get("expands_to") or []),
    }]


def _build_verbatim_three_parallel_requirements(unit) -> dict:
    """three_parallel_requirements verbatim builder.

    Task 11c: do not truncate when MDX has more groups. Task 11d: do not
    render empty padding pillars in verbatim fallback, because that traps one
    long MDX group in 1/3 width and creates avoidable overflow.
    """
    groups = _parse_mdx_raw_content(getattr(unit, "raw_content", "") or "")
    pillars = []
    pillar_count = max(1, len(groups))
    for i in range(pillar_count):
        if i < len(groups):
            g = groups[i]
            label = g.get("label", "") or ""
            label_main, label_paren = _split_label_main_paren(label)
            pillars.append({
                "label": label,
                "label_main": label_main,
                "label_paren": label_paren,
                "color_class": _THREE_COLOR_CYCLE[i % len(_THREE_COLOR_CYCLE)],
                "sections": [
                    {
                        "heading": "",
                        "text_lines": _build_text_lines(g.get("items", [])),
                    }
                ] if label or g.get("items") else [],
            })
        else:
            pillars.append({
                "label": "",
                "label_main": "",
                "label_paren": "",
                "color_class": _THREE_COLOR_CYCLE[i % len(_THREE_COLOR_CYCLE)],
                "sections": [],
            })
    return {"title": normalize_markdown_inline_text(getattr(unit, "title", "") or ""), "pillars": pillars}


def _build_verbatim_three_persona_benefits(unit) -> dict:
    """three_persona_benefits verbatim builder.

    Task 11c: do not truncate extra groups. Task 11d: avoid empty padding
    personas in verbatim fallback so actual MDX text gets usable width.
    """
    groups = _parse_mdx_raw_content(getattr(unit, "raw_content", "") or "")
    context_groups: list[dict] = []
    persona_groups = groups
    persona_role_labels = _registered_persona_role_labels()
    role_indexes = [
        i for i, g in enumerate(groups)
        if normalize_markdown_inline_text(g.get("label", "")) in persona_role_labels
    ]
    if len(role_indexes) >= 3:
        first_role_index = role_indexes[0]
        context_groups = _merge_internal_context_groups(groups[:first_role_index])
        persona_groups = [groups[i] for i in role_indexes[:3]]

    intro_sections = []
    for g in context_groups:
        body = _build_text_lines(g.get("items", []))
        if g.get("label") or body:
            intro_sections.append({
                "label": g.get("label", "") or "",
                "body": body,
            })

    personas = []
    persona_count = max(1, len(persona_groups))
    for i in range(persona_count):
        if i < len(persona_groups):
            g = persona_groups[i]
            body = []
            for item in g.get("items", []):
                normalized = normalize_markdown_inline_text(item)
                if normalized:
                    body.append({"text": normalized, "indent": 0})
            personas.append({
                "label": g.get("label", "") or "",
                "body": body,
                "color_class": _PERSONA_COLOR_CYCLE[i % len(_PERSONA_COLOR_CYCLE)],
            })
        else:
            personas.append({
                "label": "",
                "body": [],
                "color_class": _PERSONA_COLOR_CYCLE[i % len(_PERSONA_COLOR_CYCLE)],
            })
    return {
        "title": normalize_markdown_inline_text(getattr(unit, "title", "") or ""),
        "intro_sections": intro_sections,
        "personas": personas,
        "slot_mapping_trace": {
            "task25": "persona_columns_and_internal_context",
            "source_group_count": len(groups),
            "context_group_count": len(context_groups),
            "persona_group_count": len(persona_groups),
            "persona_role_labels": [p.get("label", "") for p in persona_groups],
            "persona_role_source": "component_expansion_registry:DxEffect",
        },
    }


def _build_verbatim_cards_n_grid(unit, slot_count: int, label_pattern: str, body_pattern: str) -> dict:
    """quadrant/cards N-grid verbatim builder.

    label_pattern 예: 'problem_{n}_label' or 'pill_{n}_label'.
    body_pattern  예: 'problem_{n}_body'  or 'pill_{n}_body'.
    """
    groups = _parse_mdx_raw_content(getattr(unit, "raw_content", "") or "")
    dynamic_slot_count = max(slot_count, len(groups))
    out: dict = {
        "title": normalize_markdown_inline_text(getattr(unit, "title", "") or ""),
        "_slot_count": dynamic_slot_count,
    }
    for i in range(dynamic_slot_count):
        n = i + 1
        if i < len(groups):
            g = groups[i]
            out[label_pattern.format(n=n)] = g.get("label", "") or ""
            out[body_pattern.format(n=n)] = _build_text_lines(g.get("items", []))
        else:
            out[label_pattern.format(n=n)] = ""
            out[body_pattern.format(n=n)] = []
    return out


def _join_verbatim_items(items: list[str]) -> str:
    return "<br>".join(
        normalized for item in items
        if (normalized := normalize_markdown_inline_text(item))
    )


def _build_verbatim_cycle_intersect_3(unit) -> dict:
    groups = _parse_mdx_raw_content(getattr(unit, "raw_content", "") or "")
    payload = {
        "title": normalize_markdown_inline_text(getattr(unit, "title", "") or ""),
        "intersection": "",
    }
    visible = groups[:3]
    overflow = groups[3:]
    for i in range(3):
        key = f"circle_{i + 1}_label"
        if i < len(visible):
            g = visible[i]
            label = g.get("label", "") or ""
            payload[key] = label
        else:
            payload[key] = ""
    intersection_items = [item for g in visible for item in (g.get("items", []) or [])]
    if overflow:
        intersection_items += (
            [g.get("label", "") for g in overflow] +
            [item for g in overflow for item in (g.get("items", []) or [])]
        )
    payload["intersection"] = _join_verbatim_items(intersection_items)
    return payload


def _build_verbatim_compare_table_2col(unit) -> dict:
    groups = _parse_mdx_raw_content(getattr(unit, "raw_content", "") or "")
    rows = []
    for g in groups:
        items = [normalize_markdown_inline_text(i) for i in (g.get("items", []) or [])]
        items = [i for i in items if i]
        rows.append({
            "label": g.get("label", "") or "",
            "col_a": items[0] if items else "",
            "col_b": "<br>".join(items[1:]) if len(items) > 1 else "",
        })
    return {
        "title": normalize_markdown_inline_text(getattr(unit, "title", "") or ""),
        "col_a_label": "",
        "col_b_label": "",
        "rows": rows,
    }


# issue #17 — verbatim builder 를 보유한 template 집합 (아래 dispatch 와 동기).
# renderable-aware provisional 이 reject 라벨 후보를 승격해도 안전한지(원문
# 무손실 코드 렌더 가능한지) 판단하는 데 사용.
_VERBATIM_BUILDER_TEMPLATE_IDS: frozenset[str] = frozenset({
    "three_parallel_requirements",
    "three_persona_benefits",
    "construction_goals_three_circle_intersection",
    "construction_bim_three_usage",
    "bim_dx_comparison_table",
    "bim_issues_quadrant_four",
    "sw_dependency_four_problems",
    "pre_construction_model_info_stacked",
})


def _emergency_p4b_build_verbatim_slot_payload(
    unit, template_id: str, override_slot_count: Optional[int] = None,
) -> Optional[dict]:
    """Per-frame verbatim slot_payload builder. AI 없음, 원문 보존만.

    Returns slot_payload dict OR None (해당 frame 의 builder 없음 OR Jinja partial
    없음 → 기존 adapter_needed path 로 fallback).

    override_slot_count (issue #14) — design_adaptation_plan 의
    set_repeat_count / increase_repeat_count op 적용용. repeat 패턴
    builder(cards_n_grid 계열)의 base slot_count 를 대체한다. 최종 count 는
    max(override, len(groups)) 이므로 **원문 그룹은 절대 잘리지 않는다**
    (Task 11c no-truncate) — override 는 빈 padding slot 의 개수만 조정.
    비-repeat builder 에는 영향 없음.
    """
    # Partial template 존재 check — visual_pending frame (contract 있지만 .html 없음)
    # 차단. _is_visual_pending 기준 + 직접 file 존재 확인 동시.
    _partial_path = (
        PROJECT_ROOT / "templates" / "phase_z2" / "families" / f"{template_id}.html"
    )
    if not _partial_path.exists():
        return None
    try:
        if template_id == "three_parallel_requirements":
            return _build_verbatim_three_parallel_requirements(unit)
        if template_id == "three_persona_benefits":
            return _build_verbatim_three_persona_benefits(unit)
        if template_id == "construction_goals_three_circle_intersection":
            return _build_verbatim_cycle_intersect_3(unit)
        if template_id == "construction_bim_three_usage":
            return _build_verbatim_cards_n_grid(
                unit, slot_count=override_slot_count or 3,
                label_pattern="category_{n}_label",
                body_pattern="category_{n}_body",
            )
        if template_id == "bim_dx_comparison_table":
            return _build_verbatim_compare_table_2col(unit)
        if template_id == "bim_issues_quadrant_four":
            return _build_verbatim_cards_n_grid(
                unit, slot_count=override_slot_count or 4,
                label_pattern="quadrant_{n}_label",
                body_pattern="quadrant_{n}_body",
            )
        if template_id == "sw_dependency_four_problems":
            return _build_verbatim_cards_n_grid(
                unit, slot_count=override_slot_count or 4,
                label_pattern="problem_{n}_label",
                body_pattern="problem_{n}_body",
            )
        if template_id == "pre_construction_model_info_stacked":
            return _build_verbatim_cards_n_grid(
                unit, slot_count=override_slot_count or 5,
                label_pattern="pill_{n}_label",
                body_pattern="pill_{n}_body",
            )
        return None
    except Exception as e:
        print(f"[Emergency P4b] verbatim builder failed for {template_id}: {e}", file=sys.stderr)
        return None


def _emergency_p4_ai_redistribute(unit, template_id: str) -> Optional[tuple[str, dict]]:
    """Emergency P4 inline AI redistribute — ROLLED BACK 2026-05-26.

    Returns None unconditionally. AI 가 schema 채우는 방식 = "내용 generator" 가 되어
    사용자 정책 (원문 verbatim 보존 / 가짜 라벨 생성 금지) 위반. emergency.md §2 +
    [[feedback_ai_isolation_contract]] 위반 인지 후 즉시 disable.

    올바른 후속 architecture (별 axis) :
      1. CODE: parse_mdx_structure → MdxTree
      2. CODE: parse_frame_structure → FrameTree
      3. CODE: match_structure_compatibility + initial slot mapping (verbatim)
      4. AI: frame adaptation plan only (row+1 / col+1 등 구조 조정, 텍스트 X)
      5. CODE: apply adaptation plan + render

    현재 disable 상태 — FitError 시 기존 adapter_needed path (__empty__) 로 흐름.
    mdx 04/05 의 reject-only / V4-source-missing 케이스 = catalog gap honest 노출.
    """
    return None
    # ↓ Deprecated body — 정책 violation 으로 비활성. 후속 architecture 결정 후 재설계.
    from src.config import settings as _ai_settings
    if not _ai_settings.ai_fallback_enabled:
        return None
    schema_hint = _EMERGENCY_P4_AI_SCHEMA_HINTS.get(template_id)
    if not schema_hint:
        template_id = GENERIC_FALLBACK_FRAME_TEMPLATE_ID
        schema_hint = _EMERGENCY_P4_AI_SCHEMA_HINTS.get(template_id)
        if not schema_hint:
            return None
    try:
        import anthropic as _anthropic
        client = _anthropic.Anthropic(
            api_key=_ai_settings.anthropic_api_key,
            timeout=_ai_settings.ai_fallback_timeout_s,
        )
        raw_content = getattr(unit, "raw_content", "") or ""
        unit_title = getattr(unit, "title", "") or ""
        system = (
            "당신은 슬라이드 콘텐츠 분배 helper. 원문 텍스트를 frame slot 구조에 맞게 "
            "재배치. 원문 의미 보존 (새 정보 추가 / 누락 금지). 한국어 보존. "
            "JSON 만 반환 — 다른 설명 / markdown fence X."
        )
        user = (
            f"Frame template: {template_id}\n"
            f"Slide title (참고): {unit_title}\n\n"
            f"Required slot_payload schema (exact key names):\n{schema_hint}\n\n"
            f"원문 raw text (보존 필수):\n{raw_content}\n\n"
            f"위 schema 형식의 JSON 만 반환. "
            f"pillars 는 반드시 3 개 (color_class: tech / people / nature 순서). "
            f"sections 의 text_lines 는 원문 bullet 그대로."
        )
        response = client.messages.create(
            model=_ai_settings.ai_fallback_model,
            max_tokens=4096,
            system=system,
            messages=[{"role": "user", "content": user}],
        )
        text = "".join(block.text for block in response.content if hasattr(block, "text"))
        text = text.strip()
        # strip markdown code fence if AI added it despite instructions
        if text.startswith("```"):
            parts = text.split("```")
            if len(parts) >= 2:
                text = parts[1]
                if text.lstrip().startswith("json"):
                    text = text.lstrip()[4:]
                text = text.strip()
        return (template_id, json.loads(text))
    except Exception as e:
        print(f"[Emergency P4] AI redistribute failed for {template_id}: {e}", file=sys.stderr)
        return None

# Step 9 v0 (사용자 lock 2026-05-08) — V4 label → application_mode 변환.
# tuple = (application_mode, auto_applicable, delegated_to).
# status.md §2 Q3 / Q7 lock 따라.
APPLICATION_MODE_BY_V4_LABEL = {
    "use_as_is":   ("direct_insert",              True,  "step10_contract_check"),
    "light_edit":  ("same_frame_with_adjustment", True,  "step10_contract_check"),
    "restructure": ("layout_or_region_change",    False, "human_review"),
    "reject":      ("exclude",                    False, None),
}
# adapt_matched_zone (V4 light_edit) = frame 구조 동일, 텍스트만 minor edit 필요.
# minor edit 정책 (mapper 의무) :
#   1. MDX item 수 < frame slot 수 → 빈 slot 그대로 (Jinja2 {% if %} 로 스킵)
#   2. MDX item 수 > frame slot 수 → 추가 item 누락 (truncate) — debug.json 에 기록
#   3. 텍스트 길이 mismatch → 그대로 통과 (overflow 는 zone-fit + Selenium check 가 처리)
#   4. slot ↔ MDX item 의미 매핑 → 순서 기반 (간단). V4 anchor_match 정교화는 future
# AI 호출 X — MVP-1.5b 의 "MDX 1:1 결정론적 매핑" 룰 그대로.

# Slide canvas / body geometry — front 기준 정상화 (2026-05-07)
# 참조: D:/ad-hoc/kei/design_agent_front/slide-base.html
# slide-base.html CSS 와 1:1 일치해야 함 (불일치 시 layout 계산 어긋남)
SLIDE_W = 1280
SLIDE_H = 720
SLIDE_BODY_LEFT = 50
SLIDE_BODY_TOP = 76            # 사용자 직설 (divider-body 16px 여백) 2026-05-07
SLIDE_BODY_WIDTH = 1180        # calc(100% - 100px)
SLIDE_BODY_HEIGHT = 585        # 사용자 직설 (body-footer 10px 여백) 2026-05-07
SLIDE_FOOTER_HEIGHT = 41       # was 32, front 기준
GRID_GAP = 14                  # zone 간격 (사용자 직설 2026-05-07)

# zone min-height fallback — contract 에 visual_hints.min_height_px 없을 때 사용.
# token-based font (var(--font-body) 11px 등) 기준 최소 가독 높이.
DEFAULT_ZONE_MIN_HEIGHT_PX = 100

# Step 14 image_aspect_mismatch tolerance — |natural_ratio - rendered_ratio| > TOL ⇒ fail.
# Local anchor : IMP-15 실행-1 (Gitea issue #45) — image axis acceptance criteria.
# Spec doc row (PHASE-Z-FIT-CLASSIFIER-ROUTER-SPEC) update deferred to IMP-15 실행-4.
IMAGE_ASPECT_DELTA_TOL = 0.05

# Step 14 table_self_overflow tolerance — scrollW−clientW or scrollH−clientH > TOL ⇒ fail.
# Local anchor : IMP-15 실행-2 (Gitea issue #46) — table axis acceptance criteria.
# Mirrors existing inline 5px tolerance used by slide/zone/clipped scans in run_overflow_check.
TABLE_SCROLL_TOL_PX = 5
T28_5_LINE_HEIGHT_COMPRESSION_MIN_RATIO = 0.5

# content_weight 계산 가중치
CONTENT_WEIGHT_COEFFS = {
    "text_per_chars": 800,    # text_len / 800 = score
    "top_bullet": 0.4,
    "nested_bullet": 0.15,
    "table_bonus": 1.5,
    "subsection": 0.6,
}


# ─── Data classes ───────────────────────────────────────────────

@dataclass
class MdxSection:
    section_id: str
    section_num: int
    title: str
    raw_content: str
    # IMP-08 B-3 sub-section schema (additive, defaults preserve 4-positional callers).
    # heading_number: decimal "2.1" from MDX `### 2.1 Title` capture (U2-populated).
    # v4_alias_keys: legacy V4 keys to try when canonical ordinal id misses (e.g. "04-2.1").
    # sub_sections: raw child payloads from section_parser (Stage 0 adapter consumes).
    heading_number: Optional[str] = None
    v4_alias_keys: list = field(default_factory=list)
    sub_sections: list = field(default_factory=list)


@dataclass
class V4Match:
    section_id: str
    frame_id: str
    frame_number: int
    template_id: str
    confidence: float
    label: str
    v4_rank: Optional[int] = None
    selection_path: str = "rank_1"
    fallback_reason: Optional[str] = None
    # IMP-30 u1 — provisional first-render flag. True when the selector
    # synthesizes a rank-1 V4 candidate after chain_exhausted because the
    # opt-in allow_provisional kwarg was set. Default False keeps IMP-05
    # behavior byte-identical; downstream surfaces this for zone-level
    # "needs adaptation" marking without altering V4 evidence.
    provisional: bool = False
    # Emergency P2 (2026-05-26) — 3-status classification per emergency.md policy.
    #   auto_renderable        : V4 label ∈ {use_as_is, light_edit, restructure}
    #                            → 직접 렌더 가능
    #   ai_adaptation_required : V4 label = reject (or downstream needs_adaptation /
    #                            fallback_candidate). AI 가 원문 보존하며 frame slot 에 재배치.
    #   blocked_runtime        : visual_pending = True (catalog scaffolding only).
    # 단일 source of truth = _classify_candidate_status() helper. Default 값은
    # use_as_is 같은 가장 흔한 케이스 (auto_renderable) — 빈 V4Match 생성 시 안전.
    candidate_status: str = "auto_renderable"
    coverage_state: str = "covered_native"


# Emergency P2 (2026-05-26) — single source of truth for candidate_status mapping.
# Used by _v4_match_from_judgment + Step 5 evidence emission + composition routing (P3).
# 정책 lock (emergency.md §3 Resolution table) :
#   visual_pending=True   → "blocked_runtime"
#   label in {reject}     → "ai_adaptation_required"
#   label in {use_as_is, light_edit, restructure} → "auto_renderable"
#   unknown               → "ai_adaptation_required" (보수적 — auto 렌더 안 함)
def _classify_candidate_status(label: str, visual_pending: bool = False) -> str:
    if visual_pending:
        return "blocked_runtime"
    if label in ("use_as_is", "light_edit", "restructure"):
        return "auto_renderable"
    if label == "reject":
        return "ai_adaptation_required"
    # unknown / future labels → conservative default (AI 가 다룸, 자동 렌더 X)
    return "ai_adaptation_required"


def _candidate_coverage_state(
    candidate_status: Optional[str] = None,
    *,
    label: Optional[str] = None,
    catalog_registered: Optional[bool] = None,
    selection_path: Optional[str] = None,
) -> str:
    """Map candidate status to the T21.6 coverage-state contract."""
    if catalog_registered is False:
        return "unsupported"
    if selection_path in {"generic_fallback", "catalog_fallback", "no_drop_fallback"}:
        return "requires_adaptation"
    if candidate_status == "auto_renderable":
        return "covered_native"
    if candidate_status == "ai_adaptation_required":
        return "requires_adaptation"
    if candidate_status == "blocked_runtime":
        return "unsupported"
    if label in ("use_as_is", "light_edit", "restructure"):
        return "covered_native"
    if label == "reject":
        return "requires_adaptation"
    return "requires_adaptation"


def to_phase_z_status(match: V4Match) -> str:
    return V4_LABEL_TO_PHASE_Z_STATUS.get(match.label, "unknown")


# ─── IMP-39 (#68) u1 — single-source ranking sort policy ──────────
#
# Single source of (label_priority, tie-break) ordering shared by:
#   - backend `lookup_v4_match_with_fallback` selector loop (wired in u2)
#   - Step 9 `_build_application_plan_unit` payload (wired in u3)
#   - frontend `designAgentApi.ts` candidate builder (wired in u4)
#
# u1 scope = additive only (yaml + loader + helper). No selector wiring,
# no behavior change. Default-fallback matches yaml so missing-file boot
# keeps deterministic ordering identical to the file-loaded policy.

_RANKING_SORT_POLICY_DEFAULT: dict = {
    "policy_type": "deterministic_label_priority_then_confidence",
    "label_priority": {
        "use_as_is": 0,
        "light_edit": 1,
        "restructure": 2,
        "reject": 3,
    },
    "unknown_label_priority": 99,
    "tie_break_axes": ["confidence_desc", "v4_rank_asc"],
}

_RANKING_SORT_POLICY_CACHE: Optional[dict] = None


def load_ranking_sort_policy() -> dict:
    """IMP-39 u1 — ranking sort policy loader (separate yaml, additive).

    Returns dict with keys: policy_type, label_priority (dict),
    unknown_label_priority (int), tie_break_axes (list[str]).

    Graceful fallback: yaml 파일 없을 시 _RANKING_SORT_POLICY_DEFAULT
    (위 dict) 그대로 — backward-compat boot-safe.

    Cache: module-level, mirrors `load_v4_fallback_policy` pattern.
    """
    global _RANKING_SORT_POLICY_CACHE
    if _RANKING_SORT_POLICY_CACHE is None:
        if RANKING_SORT_POLICY_PATH.exists():
            loaded = (
                yaml.safe_load(RANKING_SORT_POLICY_PATH.read_text(encoding="utf-8"))
                or {}
            )
            # merge with default so partial yaml falls through cleanly
            merged = dict(_RANKING_SORT_POLICY_DEFAULT)
            for k, v in loaded.items():
                merged[k] = v
            _RANKING_SORT_POLICY_CACHE = merged
        else:
            _RANKING_SORT_POLICY_CACHE = dict(_RANKING_SORT_POLICY_DEFAULT)
    return _RANKING_SORT_POLICY_CACHE


def apply_ranking_sort(
    records: list,
    *,
    policy: Optional[dict] = None,
    label_key: str = "label",
    confidence_key: str = "confidence",
    v4_rank_key: str = "v4_rank",
) -> list:
    """IMP-39 u1 — stable sort by (label_priority asc, confidence desc, v4_rank asc).

    Shared ordering primitive — backend selector / Step 9 payload / frontend
    mirror invariant. Sample-agnostic; no hardcoded sample IDs.

    Args:
        records: list of dicts (selector loop, trace candidates) OR V4Match
            objects. Field access falls through getitem → getattr.
        policy: optional explicit policy dict; defaults to `load_ranking_sort_policy()`.
        label_key / confidence_key / v4_rank_key: per-record field names.

    Returns:
        NEW list — input is not mutated. Records lacking a key get the
        unknown-label priority / confidence=0.0 / v4_rank=inf so they sink
        to the bottom in a deterministic way.
    """
    pol = policy if policy is not None else load_ranking_sort_policy()
    priority_map: dict = pol.get("label_priority", {}) or {}
    unknown_priority: int = int(pol.get("unknown_label_priority", 99))

    def _get(rec, key):
        if isinstance(rec, dict):
            return rec.get(key)
        return getattr(rec, key, None)

    def _key(rec):
        label = _get(rec, label_key)
        conf = _get(rec, confidence_key)
        v4_rank = _get(rec, v4_rank_key)
        label_pri = priority_map.get(label, unknown_priority)
        conf_val = float(conf) if conf is not None else 0.0
        # confidence desc → negate for asc sort key
        rank_val = int(v4_rank) if v4_rank is not None else 10**9
        return (label_pri, -conf_val, rank_val)

    return sorted(records, key=_key)


def _b4_mapper_source_enabled() -> bool:
    """IMP-89 89-a u1 — PHASE_Z_B4_MAPPER_SOURCE env flag reader (default OFF).

    Switches slot_payload source-of-truth from mapper-only (legacy) to B4
    PlacementPlan.selected_template_id. Distinct from PHASE_Z_B4_GATEKEEPER
    (mismatch render-skip semantics). u2 wires this into the slot_payload
    construction site; u3 adds BLOCKED exits for no-cover and FitError under
    flag ON. Truthy values: '1', 'true', 'yes' (case-insensitive, trimmed).
    """
    return os.environ.get("PHASE_Z_B4_MAPPER_SOURCE", "").strip().lower() in {
        "1",
        "true",
        "yes",
    }


def _select_mapper_template_id(
    placement_plan, unit_frame_template_id: str
) -> Optional[str]:
    """IMP-89 89-a u2 — slot_payload source-of-truth selector.

    Returns the template_id that drives slot_payload construction at the
    single switch site in the runtime loop:
        flag ON  → placement_plan.selected_template_id (B4 PlacementPlan,
                   Layer A render-active path)
        flag OFF → unit_frame_template_id (legacy mapper-only / V4 rank-1;
                   byte-equivalent default; final.html SHA parity guarded
                   by u4)

    Under flag ON the returned value may be None when B4 found no covering
    frame. u3 adds the BLOCKED exit for None and for FitError on the
    B4-selected template — NO silent fallback (IMP-87 honesty gate pattern).
    """
    if _b4_mapper_source_enabled():
        return placement_plan.selected_template_id
    return unit_frame_template_id


def _b4_mapper_source_blocked_exit(
    reason: str, *, position: str, context: dict
) -> "NoReturn":  # type: ignore[name-defined]
    """IMP-89 89-a u3 — BLOCKED exit (sys.exit(1)) when PHASE_Z_B4_MAPPER_SOURCE
    is ON and the Layer A render path cannot resolve a covering frame.

    Stage 1 Q2 lock: when the user explicitly opts into the B4-driven render
    path, a content-bearing zone MUST NOT silently degrade to adapter_needed
    or to the legacy V4 rank-1 mapper input. Mirrors IMP-87 u3 honesty-gate
    pattern (`_is_blocked_overall` → `sys.exit(1)`): the BLOCKED signal
    preempts the silent adapter_needed fallback so the operator sees the
    Layer A failure immediately on stderr instead of inheriting a
    pseudo-rendered partial.

    Reasons (locked enum):
        b4_no_cover            — PlacementPlan.selected_template_id is None
                                 (B4 found no covering frame on the unit)
        b4_selected_fit_error  — map_mdx_to_slots raised FitError against the
                                 B4-selected template (frame contract reject)

    Always raises SystemExit(1) via sys.exit. The `NoReturn` annotation makes
    the call-site control flow explicit for type-checkers; behavior is the
    same as IMP-87 u3's sys.exit(1) at L6387.
    """
    print(
        f"\n[Phase Z-2 IMP-89 89-a u3] BLOCKED @ {reason} (zone--{position})",
        file=sys.stderr,
    )
    print(
        "  policy   : PHASE_Z_B4_MAPPER_SOURCE=ON requires B4-driven render "
        "(NO silent fallback — IMP-87 honesty gate pattern)",
        file=sys.stderr,
    )
    for key, value in context.items():
        print(f"  {key:9}: {value}", file=sys.stderr)
    sys.exit(1)


def _derive_placement_markers(placement_plan) -> list[dict]:
    """IMP-94 (#94) u3 — project ``PlacementPlan.slot_assignments[]`` → list of
    marker dicts consumed by the u1/u2 ``_stamp_region_markers`` chain.

    Each marker carries ``region_id`` + ``content_unit_id`` (consumed by u1
    stamper) + ``frame_slot_id`` (reserved for #96 89-d per-slot axis — u1
    stamper silently ignores extras and excess markers). Pure deterministic
    projection; AI=0; no mutation of ``placement_plan``.

    Args:
        placement_plan: ``src.phase_z2_placement_planner.PlacementPlan`` instance
            produced by ``plan_placement(...)`` at the runtime call site
            (L6581-6585). ``slot_assignments`` empty/None → return ``[]`` so the
            u2 call-site fallback ``or []`` is the deterministic no-op path.

    Returns:
        list[dict] — one entry per ``SlotAssignment``. Empty when the plan has
        no assignments (rejection path / no covering frame / empty section).

    Disjoint from #96 by attribute name — this helper only emits the marker
    dict shape; the partial root-div ``data-region-id`` + ``data-content-unit-id``
    stamping happens in u1, not here.
    """
    if placement_plan is None:
        return []
    assignments = getattr(placement_plan, "slot_assignments", None) or []
    markers: list[dict] = []
    for sa in assignments:
        markers.append({
            "region_id": getattr(sa, "region_id", "") or "",
            "content_unit_id": getattr(sa, "content_unit_id", "") or "",
            "frame_slot_id": getattr(sa, "frame_slot_id", "") or "",
        })
    return markers


# ─── MDX parsing ────────────────────────────────────────────────

def parse_mdx(mdx_path: Path) -> tuple[str, list[MdxSection], Optional[str]]:
    """basic MDX parser — ## level sections only. V4 무관 (matching artifact 모름).

    section.raw_content 에 ### sub-section 그대로 포함. V4 granularity 와 align 은
    align_sections_to_v4_granularity() 가 처리.
    """
    text = mdx_path.read_text(encoding="utf-8")

    fm_match = re.match(r"^---\n(.*?)\n---\n", text, re.DOTALL)
    slide_title = ""
    if fm_match:
        fm = yaml.safe_load(fm_match.group(1))
        slide_title = fm.get("title", "")
        text = text[fm_match.end():]

    summary_fragments: list[str] = []

    def _note_repl(match: re.Match) -> str:
        title = match.group(1) or ""
        body = match.group(2) or ""
        if _is_summary_title(title):
            summary = _normalize_summary_text(body)
            if summary:
                summary_fragments.append(summary)
            return "\n"
        return match.group(0)

    text = re.sub(r":::note\[([^\]]*)\]\n(.*?)\n:::", _note_repl, text, flags=re.DOTALL)

    sections = []
    section_pattern = re.compile(r"^##\s+(\d+)\.\s+(.+?)$", re.MULTILINE)
    matches = list(section_pattern.finditer(text))

    mdx_num_match = re.match(r"(\d+)", mdx_path.stem)
    mdx_id = mdx_num_match.group(1).zfill(2) if mdx_num_match else "00"

    pre_intro_source = text[:matches[0].start()] if matches else text
    pre_intro_body = _normalize_pre_intro_body(pre_intro_source)
    if pre_intro_body:
        sections.append(MdxSection(
            section_id=f"{mdx_id}-intro",
            section_num=0,
            title=_derive_pre_intro_title(pre_intro_body),
            raw_content=pre_intro_body,
        ))

    for i, m in enumerate(matches):
        section_num = int(m.group(1))
        title_text = m.group(2).strip()
        start = m.end()
        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
        raw_content = text[start:end].strip()
        raw_content, section_summaries = _strip_summary_subsections(raw_content)
        raw_content, component_expansions = _expand_registered_components(raw_content)
        raw_content = _normalize_mdx_semantic_body(raw_content)
        summary_fragments.extend(section_summaries)
        sections.append(MdxSection(
            section_id=f"{mdx_id}-{section_num}",
            section_num=section_num,
            title=f"{section_num}. {title_text}",
            raw_content=raw_content,
            sub_sections=component_expansions,
        ))

    footer_text = " / ".join(s for s in summary_fragments if s) or None
    return slide_title, sections, footer_text


def _normalize_pre_intro_body(raw_content: str) -> str:
    """Normalize visible content before the first numbered section.

    Import/export declarations and purely structural separators are not visible
    author content, but bullets, details, tables, and images before ``## 1`` are.
    """

    kept_lines: list[str] = []
    for line in (raw_content or "").splitlines():
        stripped = line.strip()
        if not stripped:
            kept_lines.append("")
            continue
        if re.match(r"^import\s+\w+", stripped):
            continue
        if re.match(r"^export\s+", stripped):
            continue
        if stripped in {"---", "----"}:
            continue
        if re.fullmatch(r"<br\s*/?>", stripped, flags=re.IGNORECASE):
            continue
        kept_lines.append(line)
    normalized = _normalize_mdx_semantic_body("\n".join(kept_lines))
    return normalized.strip()


def _derive_pre_intro_title(raw_content: str) -> str:
    """Derive a stable display title from the first visible intro atom."""

    for line in (raw_content or "").splitlines():
        stripped = line.strip()
        if not stripped:
            continue
        stripped = re.sub(r"^(?:[-*]|\d+[.)])\s+", "", stripped)
        stripped = re.sub(r"^#+\s+", "", stripped)
        title = normalize_markdown_inline_text(stripped)
        if title:
            return title
    return "Intro"


def _expand_registered_components(raw_content: str) -> tuple[str, list[dict]]:
    """Expand registered component tags inside normalized section content."""

    expanded, dx_trace = _expand_dx_effect_component(raw_content)
    traces = list(dx_trace)
    return expanded, traces


_SINGLE_LINE_SEMANTIC_TAG_RE = re.compile(
    r"<(?P<tag>h[1-6]|p|li|summary|span|strong|em)\b[^>]*>(?P<body>.*?)</(?P=tag)>",
    re.IGNORECASE,
)
_HTML_TAG_RE = re.compile(r"<[^>]+>")
_JSX_STYLE_PROP_LINE_RE = re.compile(
    r"^\s*[A-Za-z][A-Za-z0-9_-]*\s*:\s*['\"#]?[A-Za-z0-9#().,%/ -]+['\"]?\s*,?\s*}*>?\s*$"
)
_JSX_EVENT_LINE_RE = re.compile(r"^\s*on[A-Z][A-Za-z0-9_]*\s*=", re.ASCII)
_JSX_WRAPPER_LINE_RE = re.compile(
    r"^\s*</?(?:div|ul|ol|p|h[1-6]|li|span|section|article|br)\b[^>]*>?\s*$",
    re.IGNORECASE,
)


def _normalize_mdx_semantic_body(raw_content: str) -> str:
    """Keep author text while dropping JSX/CSS wrapper syntax."""

    normalized_lines: list[str] = []
    for raw_line in (raw_content or "").splitlines():
        stripped = raw_line.strip()
        if not stripped:
            if normalized_lines and normalized_lines[-1] != "":
                normalized_lines.append("")
            continue

        extracted = False
        for match in _SINGLE_LINE_SEMANTIC_TAG_RE.finditer(stripped):
            body = normalize_markdown_inline_text(match.group("body"))
            if not body:
                continue
            tag = match.group("tag").lower()
            normalized_lines.append(f"### {body}" if tag.startswith("h") else f"- {body}")
            extracted = True
        if extracted:
            continue

        if _is_mdx_syntax_noise_line(stripped):
            continue

        if "<" in stripped and ">" in stripped:
            stripped = _HTML_TAG_RE.sub(" ", stripped)
            stripped = re.sub(r"^\s*}+>?\s*", "", stripped)
            stripped = normalize_markdown_inline_text(stripped)
            if not stripped:
                continue

        normalized_lines.append(stripped)

    while normalized_lines and normalized_lines[-1] == "":
        normalized_lines.pop()
    return "\n".join(normalized_lines).strip()


def _is_mdx_syntax_noise_line(stripped: str) -> bool:
    if stripped in {"{", "}", "});", "}}", "}}>", ">", "</div>", "</ul>", "</ol>"}:
        return True
    if re.fullmatch(r"<br\s*/?>", stripped, flags=re.IGNORECASE):
        return True
    if stripped.startswith(("e.currentTarget.", "event.currentTarget.")):
        return True
    if _JSX_EVENT_LINE_RE.match(stripped):
        return True
    if "style={{" in stripped or "style={" in stripped:
        return True
    if _JSX_STYLE_PROP_LINE_RE.match(stripped):
        return True
    if _JSX_WRAPPER_LINE_RE.match(stripped):
        return True
    return False


SUMMARY_TITLE_RE = re.compile(r"(핵심\s*요약|요약|결론|시사점)")


def _is_summary_title(title: str) -> bool:
    return bool(SUMMARY_TITLE_RE.search(normalize_markdown_inline_text(title or "")))


def _normalize_summary_text(body: str) -> str:
    """Normalize summary/footer text without generating new content."""
    parts: list[str] = []
    for line in (body or "").splitlines():
        stripped = line.strip()
        if not stripped or stripped in {"---", ":::"}:
            continue
        if re.fullmatch(r"<br\s*/?>", stripped, flags=re.IGNORECASE):
            continue
        stripped = re.sub(r"^[*\-]\s+", "", stripped)
        normalized = normalize_markdown_inline_text(stripped)
        if normalized:
            parts.append(normalized)
    return " ".join(parts).strip()


def _strip_summary_subsections(raw_content: str) -> tuple[str, list[str]]:
    """Remove summary subsections from body content and return their text."""
    lines = (raw_content or "").splitlines()
    kept: list[str] = []
    summaries: list[str] = []
    collecting: list[str] = []
    in_summary = False

    def flush_summary() -> None:
        nonlocal collecting
        summary = _normalize_summary_text("\n".join(collecting))
        if summary:
            summaries.append(summary)
        collecting = []

    for line in lines:
        heading = re.match(r"^(#{3,6})\s+(.+?)\s*$", line.strip())
        if heading:
            if in_summary:
                flush_summary()
            in_summary = _is_summary_title(heading.group(2))
            if in_summary:
                continue
        if in_summary:
            collecting.append(line)
        else:
            kept.append(line)

    if in_summary:
        flush_summary()

    return "\n".join(kept).strip(), summaries


# IMP-02 (Phase Z Step 2) — Stage 0 normalize chained adapter.
# scope-lock 7 조건 (Gitea #2):
#   1. inline helper near parse_mdx()
#   2. PHASE_Z_STAGE0_ADAPTER_ENABLED env flag, default OFF (canary, matches PHASE_Z_B4_*)
#   3. env=1 sample verification required (in review loop)
#   4. fallback_reason: str | None flat — 5 hard cases
#   5. verify normalize_mdx_content(raw_mdx)["sections"] is list
#   6. preserve Step 2 existing fields; stage0_adapter_diagnostics additive only
#   7. out of scope: V4 / align / composition / AI/Kei / frame selection / status semantics
_STAGE0_FALLBACK_REASONS = {
    "ADAPTER_EXCEPTION",
    "NO_USABLE_SECTIONS",
    "MISSING_INVALID_IDS",
    "DUPLICATE_IDS",
    "NON_POSITIVE_SECTION_NUM",
}


def _stage0_chained_adapter(
    mdx_path: Path,
    legacy_slide_title: str,
    legacy_sections: list[MdxSection],
    legacy_footer: Optional[str],
) -> tuple[str, list[MdxSection], Optional[str], dict, dict]:
    """IMP-02 — chained adapter for Stage 0 normalize → Phase Z Step 2 input.

    Chain: mdx_normalizer.normalize_mdx_content + section_parser.extract_major_sections
    + section_parser.extract_conclusion_text → reconstructed MdxSection list.

    Default OFF (canary, env=`1/true/yes` to enable). When OFF, returns legacy parse_mdx
    output with diagnostics indicating disabled. When ON, runs adapter chain; on any
    hard contract failure or exception, falls back to legacy and records fallback_reason.

    Returns (slide_title, sections, footer, diagnostics, normalized_assets).
      normalized_assets = {"popups": [...], "images": [...], "tables": [...]}
                          — IMP-03 Step 3 handoff. env=OFF or hard fallback 시 빈 list.
    """
    diagnostics: dict = {
        "enabled": False,
        "used": False,
        "fallback_reason": None,
        "id_reconstruction_log": [],
        "adapter_counts": None,
        "legacy_counts": {"sections": len(legacy_sections)},
    }
    # IMP-03 — Step 3 handoff. env=OFF / fallback 시 모든 list 가 비어 있음.
    normalized_assets: dict = {"popups": [], "images": [], "tables": []}

    raw_flag = os.environ.get("PHASE_Z_STAGE0_ADAPTER_ENABLED", "").strip().lower()
    enabled = raw_flag in {"1", "true", "yes"}
    diagnostics["enabled"] = enabled
    if not enabled:
        return legacy_slide_title, legacy_sections, legacy_footer, diagnostics, normalized_assets

    try:
        # Defer imports — legacy path must not depend on these modules.
        from mdx_normalizer import normalize_mdx_content
        from section_parser import extract_conclusion_text, extract_major_sections

        raw_mdx = mdx_path.read_text(encoding="utf-8")
        normalized = normalize_mdx_content(raw_mdx)
        if not isinstance(normalized, dict) or not isinstance(normalized.get("sections"), list):
            diagnostics["fallback_reason"] = "MISSING_INVALID_IDS"
            return legacy_slide_title, legacy_sections, legacy_footer, diagnostics, normalized_assets

        majors = extract_major_sections(normalized["sections"])
        if not majors:
            diagnostics["fallback_reason"] = "NO_USABLE_SECTIONS"
            return legacy_slide_title, legacy_sections, legacy_footer, diagnostics, normalized_assets

        adapter_title = (normalized.get("title") or "").strip() or legacy_slide_title
        conclusion = extract_conclusion_text(raw_mdx)
        adapter_footer = conclusion if conclusion else None

        mdx_num_match = re.match(r"(\d+)", mdx_path.stem)
        mdx_id = mdx_num_match.group(1).zfill(2) if mdx_num_match else "00"

        # Pre-scan raw MDX `## N. Title` headings → {title: section_num} map.
        # Required to make scope-lock §5 "raw heading reuse first" functionally
        # reachable, since extract_major_sections strips the leading `N.` from
        # its level=2 group titles (Codex implementation review #6 catch).
        raw_heading_map: dict[str, int] = {}
        for h in re.finditer(r"^##\s+(\d+)\.\s+(.+?)$", raw_mdx, re.MULTILINE):
            raw_heading_map[h.group(2).strip()] = int(h.group(1))

        adapter_sections: list[MdxSection] = []
        used_nums: set[int] = set()
        for idx, m in enumerate(majors, start=1):
            mtitle = (m.get("title") or "").strip()
            content = (m.get("content") or "").strip()

            if mtitle in raw_heading_map:
                section_num = raw_heading_map[mtitle]
                clean_title = mtitle
                reuse_source = "raw_heading"
            else:
                inline_match = re.match(r"^(\d+)\.\s*(.+)$", mtitle)
                if inline_match:
                    section_num = int(inline_match.group(1))
                    clean_title = inline_match.group(2).strip()
                    reuse_source = "raw_heading_inline"
                else:
                    section_num = idx
                    clean_title = mtitle
                    reuse_source = "order_fallback"

            if section_num <= 0:
                diagnostics["fallback_reason"] = "NON_POSITIVE_SECTION_NUM"
                return legacy_slide_title, legacy_sections, legacy_footer, diagnostics, normalized_assets
            if section_num in used_nums:
                diagnostics["fallback_reason"] = "DUPLICATE_IDS"
                return legacy_slide_title, legacy_sections, legacy_footer, diagnostics, normalized_assets
            used_nums.add(section_num)

            diagnostics["id_reconstruction_log"].append({
                "input_title": mtitle,
                "section_num": section_num,
                "reuse_source": reuse_source,
            })

            adapter_sections.append(MdxSection(
                section_id=f"{mdx_id}-{section_num}",
                section_num=section_num,
                title=f"{section_num}. {clean_title}",
                raw_content=content,
            ))

        diagnostics["adapter_counts"] = {
            "sections": len(adapter_sections),
            "majors": len(majors),
            "normalized_sections": len(normalized["sections"]),
            "popups": len(normalized.get("popups", []) or []),
            "images": len(normalized.get("images", []) or []),
            "tables": len(normalized.get("tables", []) or []),
        }
        diagnostics["diff_vs_legacy"] = {
            "title_match": adapter_title == legacy_slide_title,
            "count_match": len(adapter_sections) == len(legacy_sections),
            "footer_match": adapter_footer == legacy_footer,
        }
        diagnostics["used"] = True
        # IMP-03 — populate Step 3 handoff (success path only).
        # All fallback paths leave normalized_assets as empty lists (defined at fn top).
        normalized_assets = {
            "popups": normalized.get("popups", []) or [],
            "images": normalized.get("images", []) or [],
            "tables": normalized.get("tables", []) or [],
        }
        return adapter_title, adapter_sections, adapter_footer, diagnostics, normalized_assets

    except Exception as exc:  # noqa: BLE001 — adapter must never break legacy path
        diagnostics["fallback_reason"] = "ADAPTER_EXCEPTION"
        diagnostics["exception"] = repr(exc)
        return legacy_slide_title, legacy_sections, legacy_footer, diagnostics, normalized_assets


# ─── V4 lookup ──────────────────────────────────────────────────

def load_v4_result() -> dict:
    return yaml.safe_load(V4_RESULT_PATH.read_text(encoding="utf-8"))


def align_sections_to_v4_granularity(
    sections: list[MdxSection],
    v4: dict,
    *,
    override_target_section_ids: Optional[list[str]] = None,
) -> list[MdxSection]:
    """Align MDX sections to canonical sub-section granularity.

    Default behaviour (V4-driven granularity, backward compatible) :
      - V4 has section_id exact key   -> keep section unchanged (parent
        granularity rendering, parent-level V4 evidence applies).
      - V4 missing + H3 sub-sections  -> drill into sub-sections, emit
        canonical ids ``${section_id}-sub-${ordinal}`` with optional
        decimal alias for legacy V4 keys (e.g. ``04-2.1``).
      - V4 missing + no H3            -> pass through (downstream V4 lookup
        will naturally abort with no_v4_section).

    IMP-08 B-3 / Stage 5 R2 blocker-fix — ``override_target_section_ids``
    is the list of section ids that drag/drop override CLI flags target.
    When any override target matches ``${section_id}-sub-N`` for a section
    whose parent is otherwise V4-aligned, that section is force-drilled so
    sub-section ids become addressable. This keeps the default rendering
    path on V4 granularity while making drag/drop deterministic regardless
    of whether V4 carries a parent exact key.

    Each drilled sub-section carries :
      - heading_number : decimal "2.1" / integer "1" / None (bare H3 title).
      - v4_alias_keys  : legacy V4 keys to try when the canonical ordinal
        id misses. Populated only when ``heading_number`` matches the
        decimal pattern ``\\d+\\.\\d+`` (N-R5 guard) — integer-only or
        bare H3 produces no alias to avoid sibling-parent V4 collisions.

    Design boundary :
      - parser (``parse_mdx``)  = MDX-only knowledge (V4-agnostic).
      - aligner (this function) = canonical sub-id schema, MDX-driven on
        force_drill, V4-driven otherwise.
      - resolver (``_resolve_v4_section_key``) = exact > alias > None,
        never auto-promotes to parent/sibling (axis 7 hybrid lock).
    """
    v4_keys = set(v4.get("mdx_sections", {}).keys())

    # Build the set of parent ids whose sub-ids are explicitly targeted by
    # an override. These sections must be drilled even if V4 also carries
    # the parent key exactly. Parents derived from canonical "X-sub-N" ids
    # only — non-sub ids (top-level overrides) do not trigger drilling.
    force_drill_parents: set[str] = set()
    if override_target_section_ids:
        for sid in override_target_section_ids:
            parent = derive_parent_id(sid)
            if parent and sid != parent:
                force_drill_parents.add(parent)

    aligned: list[MdxSection] = []

    # Capture optional heading-number prefix (decimal "2.1" or integer "1")
    # plus the heading title. None group = bare "### Title".
    sub_pattern = re.compile(
        r"^###\s+(?:(\d+(?:\.\d+)?)\s+)?(.+?)$", re.MULTILINE
    )
    decimal_re = re.compile(r"\d+\.\d+")

    for section in sections:
        force_drill = section.section_id in force_drill_parents
        if section.section_id in v4_keys and not force_drill:
            # V4 carries this section exactly and no override targets a
            # sub-id under it: keep parent granularity (backward compat).
            aligned.append(section)
            continue

        sub_matches = list(sub_pattern.finditer(section.raw_content))
        if not sub_matches:
            # No H3 sub-sections: cannot drill. Pass section through;
            # downstream V4 lookup aborts with no_v4_section when needed.
            aligned.append(section)
            continue

        mdx_id = section.section_id.split("-")[0]   # e.g., "04"
        for ordinal, m in enumerate(sub_matches, start=1):
            heading_number = m.group(1)  # decimal "2.1" / integer "1" / None
            sub_title = m.group(2).strip()
            start = m.end()
            end = (
                sub_matches[ordinal].start()
                if ordinal < len(sub_matches)
                else len(section.raw_content)
            )
            raw = section.raw_content[start:end].strip()

            # N-R5 : alias only for decimal heading numbers. integer-only
            # H3 (`### 1`) or undecorated H3 produce no alias to avoid
            # sibling-parent V4 collisions (e.g., 05.mdx integer H3s).
            alias_keys: list[str] = []
            if heading_number and decimal_re.fullmatch(heading_number):
                alias_keys.append(f"{mdx_id}-{heading_number}")

            title = (
                f"{heading_number} {sub_title}" if heading_number else sub_title
            )
            aligned.append(MdxSection(
                section_id=f"{section.section_id}-sub-{ordinal}",
                section_num=section.section_num,
                title=title,
                raw_content=raw,
                heading_number=heading_number,
                v4_alias_keys=alias_keys,
            ))

    return aligned


def _group_sections_by_top_level_parent(sections: list[MdxSection]) -> list[tuple[str, list[MdxSection]]]:
    """Group aligned sections by top-level source parent while preserving order.

    Task 9 invariant: fallback/adaptation paths may drill a section into
    sub-sections, but must not merge separate top-level sections such as
    ``05-1`` and ``05-2`` into one render unit.
    """
    grouped: list[tuple[str, list[MdxSection]]] = []
    group_index: dict[str, int] = {}
    for section in sections:
        group_id = derive_parent_id(section.section_id) or section.section_id
        if group_id not in group_index:
            group_index[group_id] = len(grouped)
            grouped.append((group_id, []))
        grouped[group_index[group_id]][1].append(section)
    return grouped


def _make_emergency_p3_generic_unit(
    *,
    group_id: str,
    group_sections: list[MdxSection],
    fallback_reason: str,
    rationale_extra: Optional[dict[str, Any]] = None,
) -> CompositionUnit:
    """Build one source-preserving Emergency P3 generic fallback unit."""
    fallback_candidates = lookup_catalog_fallback_candidates(group_id)
    rationale = {
        "emergency_p3": "generic_fallback_no_v4_evidence",
        "policy": "empty_shell_forbidden_per_emergency_md",
        "task9": "top_level_group_preserving_fallback",
        "frame_choice_source": "GENERIC_FALLBACK_FRAME_TEMPLATE_ID",
        "reason": fallback_reason,
        "aligned_section_ids": [s.section_id for s in group_sections],
        "ai_adaptation_required": True,
    }
    if rationale_extra:
        rationale.update(rationale_extra)
    return CompositionUnit(
        source_section_ids=[s.section_id for s in group_sections],
        merge_type="generic_fallback_group",
        frame_template_id=GENERIC_FALLBACK_FRAME_TEMPLATE_ID,
        frame_id=GENERIC_FALLBACK_FRAME_ID,
        frame_number=0,
        confidence=0.0,
        label="reject",
        phase_z_status="fallback_candidate",
        raw_content="\n\n".join((s.raw_content or "") for s in group_sections),
        title=" / ".join((s.title or "") for s in group_sections) or group_id,
        v4_rank=None,
        selection_path="generic_fallback",
        fallback_reason=fallback_reason,
        score=0.0,
        v4_candidates=fallback_candidates,
        rationale=rationale,
        provisional=True,
    )


def _build_emergency_p3_generic_fallback_units(
    *,
    sections: list[MdxSection],
    fallback_reason: str,
    section_assignment_plan: Optional[list[dict]] = None,
    plan_unit_by_position: Optional[dict[str, object]] = None,
) -> tuple[list[CompositionUnit], dict]:
    """Build Emergency P3 units without corrupting manual position truth.

    When a section-assignment plan is active, position identity is the source of
    truth. Rebuilding fallback units by top-level parent would mix auto
    top/bottom groups with manual left/right positions, so this helper creates
    one fallback unit per assigned position instead.
    """
    sections_by_id = {s.section_id: s for s in sections}
    if section_assignment_plan is not None:
        units: list[CompositionUnit] = []
        position_groups: list[dict] = []
        for entry in section_assignment_plan:
            position = str(entry.get("position") or "")
            source_ids = list(entry.get("source_section_ids") or [])
            group_sections = [
                sections_by_id[sid] for sid in source_ids if sid in sections_by_id
            ]
            if not position:
                continue
            if not group_sections:
                if plan_unit_by_position is not None:
                    plan_unit_by_position[position] = None
                position_groups.append({
                    "position": position,
                    "source_section_ids": source_ids,
                    "renderable": False,
                    "reason": "no_source_sections_for_position",
                })
                continue
            unit = _make_emergency_p3_generic_unit(
                group_id=position,
                group_sections=group_sections,
                fallback_reason=fallback_reason,
                rationale_extra={
                    "task28_5e": "section_assignment_position_preserving_fallback",
                    "position": position,
                    "section_assignment_fallback_preserved": True,
                },
            )
            units.append(unit)
            if plan_unit_by_position is not None:
                plan_unit_by_position[position] = unit
            position_groups.append({
                "position": position,
                "source_section_ids": [s.section_id for s in group_sections],
                "renderable": True,
                "template_id": unit.frame_template_id,
            })
        return units, {
            "grouping_mode": "section_assignment_positions",
            "section_assignment_fallback_preserved": True,
            "position_groups": position_groups,
            "text_source_section_ids": [
                sid
                for group in position_groups
                for sid in group.get("source_section_ids", [])
            ],
        }

    grouped_sections = _group_sections_by_top_level_parent(sections)
    units = [
        _make_emergency_p3_generic_unit(
            group_id=group_id,
            group_sections=group_sections,
            fallback_reason=fallback_reason,
            rationale_extra={"top_level_group_id": group_id},
        )
        for group_id, group_sections in grouped_sections
    ]
    return units, {
        "grouping_mode": "top_level_parent",
        "section_assignment_fallback_preserved": False,
        "top_level_groups": [
            {
                "group_id": group_id,
                "source_section_ids": [s.section_id for s in grouped],
            }
            for group_id, grouped in grouped_sections
        ],
    }


def _collapse_units_to_parent_sections(
    units: list[CompositionUnit],
    aligned_sections: list[MdxSection],
    parent_sections: list[MdxSection],
    *,
    fallback_template_id: str,
    fallback_frame_id: str,
) -> tuple[list[CompositionUnit], list[MdxSection], dict]:
    """Collapse render units back to top-level MDX sections.

    Task 14 invariant: V4 alignment may split a parent section into child
    sections for candidate lookup, but final composition/render units must use
    the original top-level section ids. Child ids stay as evidence only.
    """
    parent_by_id = {s.section_id: s for s in parent_sections}
    if not parent_sections:
        return units, aligned_sections, {
            "applied": False,
            "reason": "no_parent_sections",
        }

    groups_by_parent = {
        group_id: group_sections
        for group_id, group_sections in _group_sections_by_top_level_parent(aligned_sections)
    }
    output_units: list[CompositionUnit] = []
    collapsed_groups: list[dict] = []
    added_fallbacks: list[dict] = []

    for parent in parent_sections:
        parent_id = parent.section_id
        group_sections = groups_by_parent.get(parent_id) or [parent]
        child_ids = [s.section_id for s in group_sections]
        id_set = {parent_id, *child_ids}

        matching_units = []
        for unit in units:
            unit_ids = list(getattr(unit, "source_section_ids", []) or [])
            if any((sid in id_set) or ((derive_parent_id(sid) or sid) == parent_id) for sid in unit_ids):
                matching_units.append(unit)

        if matching_units:
            # Keep the strongest frame choice, but replace its section identity
            # and content with the parent section. This preserves candidate
            # value without promoting child headings into frame titles.
            matching_units.sort(
                key=lambda u: (
                    u.source_section_ids != [parent_id],
                    -float(getattr(u, "score", 0.0) or 0.0),
                    "+".join(getattr(u, "source_section_ids", []) or []),
                )
            )
            chosen = matching_units[0]
            rationale = dict(getattr(chosen, "rationale", {}) or {})
            rationale["task14_parent_section_unit"] = {
                "parent_section_id": parent_id,
                "aligned_child_section_ids": child_ids,
                "representative_source_section_ids": list(chosen.source_section_ids),
                "policy": "sub_sections_are_internal_groups_not_frame_titles",
            }
            notes = list(getattr(chosen, "notes", []) or [])
            if "task14_parent_section_collapse" not in notes:
                notes.append("task14_parent_section_collapse")
            output_units.append(replace(
                chosen,
                source_section_ids=[parent_id],
                merge_type=(
                    chosen.merge_type
                    if chosen.source_section_ids == [parent_id]
                    else "parent_section_unit"
                ),
                raw_content=parent.raw_content,
                title=parent.title,
                rationale=rationale,
                notes=notes,
            ))
            collapsed_groups.append({
                "parent_section_id": parent_id,
                "aligned_child_section_ids": child_ids,
                "representative_source_section_ids": list(chosen.source_section_ids),
                "frame_template_id": chosen.frame_template_id,
            })
        else:
            fallback = CompositionUnit(
                source_section_ids=[parent_id],
                merge_type="parent_no_drop_fallback",
                frame_template_id=fallback_template_id,
                frame_id=fallback_frame_id,
                frame_number=0,
                confidence=0.0,
                label="reject",
                phase_z_status="fallback_candidate",
                raw_content=parent.raw_content,
                title=parent.title,
                v4_rank=None,
                selection_path="task14_parent_no_drop_fallback",
                fallback_reason="task14_parent_section_uncovered",
                score=0.0,
                rationale={
                    "task14_parent_section_unit": {
                        "parent_section_id": parent_id,
                        "aligned_child_section_ids": child_ids,
                        "policy": "top_level_section_must_not_drop",
                    }
                },
                provisional=True,
            )
            output_units.append(fallback)
            added_fallbacks.append({
                "parent_section_id": parent_id,
                "aligned_child_section_ids": child_ids,
                "frame_template_id": fallback_template_id,
            })

    return output_units, list(parent_sections), {
        "applied": True,
        "parent_section_ids": [s.section_id for s in parent_sections],
        "aligned_section_ids": [s.section_id for s in aligned_sections],
        "collapsed_groups": collapsed_groups,
        "added_fallbacks": added_fallbacks,
    }


def _v4_match_from_judgment(section_id: str, judgment: dict, rank: Optional[int] = None) -> V4Match:
    resolved_rank = rank if rank is not None else judgment.get("v4_full_rank")
    tid = judgment["template_id"]
    label = judgment["label"]
    # Emergency P2 (2026-05-26) — auto-classify candidate_status at construction time.
    # visual_pending lookup is data-driven (frame_contracts.yaml) per IMP-#85 u4.
    vp = bool(tid and _is_visual_pending(tid))
    candidate_status = _classify_candidate_status(label, visual_pending=vp)
    return V4Match(
        section_id=section_id,
        frame_id=str(judgment["frame_id"]),
        frame_number=int(judgment["frame_number"]),
        template_id=tid,
        confidence=float(judgment["confidence"]),
        label=label,
        v4_rank=int(resolved_rank) if resolved_rank is not None else None,
        candidate_status=candidate_status,
        coverage_state=_candidate_coverage_state(
            candidate_status,
            label=label,
            catalog_registered=get_contract(tid) is not None,
        ),
    )


def _resolve_v4_section_key(
    v4: dict,
    section_id: str,
    *,
    alias_keys: Optional[list] = None,
) -> Optional[str]:
    """Resolve a V4 ``mdx_sections`` key for *section_id*.

    Resolution order :
      1. exact match (canonical ordinal id wins)
      2. alias_keys in given order (e.g. legacy decimal ``04-2.1`` for ``04-2-sub-1``)
      3. None on miss.

    Never promotes to parent or sibling — that would reinterpret V4 evidence
    (axis 7 hybrid lock, RULE 0). U1 callers pass alias_keys=None so the
    function is byte-identical to the previous exact-match lookup; U2 populates
    aliases from MDX heading_number metadata.
    """
    keys = v4.get("mdx_sections", {})
    if section_id in keys:
        return section_id
    if alias_keys:
        for a in alias_keys:
            if a and a in keys:
                return a
    return None


def _resolve_v4_section_keys_with_children(
    v4: dict,
    section_id: str,
    *,
    alias_keys: Optional[list] = None,
) -> list[str]:
    """Emergency P2.5 (2026-05-26) — universal parent ↔ child key alignment.

    Resolution order :
      1. exact match → [section_id]
      2. alias_keys 첫 매치 → [alias]
      3. child key scan (X.\\d+) → sorted list of all matching children
         (예: "04-2" miss → ["04-2.1", "04-2.2"])
      4. miss → []

    emergency.md C2 policy : V4 source 의 split key (예: 04-2.1, 04-2.2) 와
    pipeline normalize 의 parent key (예: 04-2) mismatch 를 child pool merge 로
    해소. mdx 별 dispatch 없는 universal — "02-2" / "04-2" 자동 cover.

    별 함수 (기존 _resolve_v4_section_key 는 single key 반환 — 호환 보존).
    lookup_v4_candidates 가 이 새 함수 를 사용.
    """
    keys = v4.get("mdx_sections", {})
    if section_id in keys:
        return [section_id]
    if alias_keys:
        for a in alias_keys:
            if a and a in keys:
                return [a]
    # child key fallback (universal — emergency P2.5 / C2)
    pattern = re.compile(re.escape(section_id) + r"\.\d+$")
    children = sorted(k for k in keys if pattern.match(k))
    return children


def lookup_v4_match(
    v4: dict, section_id: str, *, alias_keys: Optional[list] = None
) -> Optional[V4Match]:
    resolved = _resolve_v4_section_key(v4, section_id, alias_keys=alias_keys)
    sec = v4.get("mdx_sections", {}).get(resolved) if resolved else None
    if not sec:
        return None
    judgments = sec.get("judgments_full32", [])
    if not judgments:
        return None
    top = judgments[0]
    return _v4_match_from_judgment(section_id, top, rank=1)


# IMP-05 L2/L5 route hint — V4 label → execution route guidance for future consumers
# (frontend zone-level override / AI-assisted adaptation). Codex #2 conceptual model :
#   use_as_is    → Phase Z direct render
#   light_edit   → deterministic minor adjustment
#   restructure  → AI-assisted frame-aware adaptation (deferred to IMP-17 — carve-out, AI fallback only, normal path 밖)
#   reject       → AI re-construction over the rank-1 reject frame (IMP-47B u1, 2026-05-21);
#                  policy correction supersedes the legacy "design reference only" disposition.
#                  Frame visual / contract stays untouched; AI only re-maps MDX content into
#                  declared slots. Activation still gated by ai_fallback_enabled (default OFF).
_IMP05_ROUTE_HINTS: dict[str, str] = {
    "use_as_is":   "direct_render",
    "light_edit":  "deterministic_minor_adjustment",
    "restructure": "ai_adaptation_required",
    "reject":      "ai_adaptation_required",
}


def _imp05_route_hint(label: Optional[str]) -> Optional[str]:
    """Map V4 label to execution route hint. Returns None for unknown labels."""
    if label is None:
        return None
    return _IMP05_ROUTE_HINTS.get(label)


def _load_frame_partial_html(template_id: str) -> str:
    """IMP-47B u4 — Read templates/phase_z2/families/{template_id}.html.

    Missing partial (e.g., ``__empty__`` shell from IMP-30) returns an
    empty string so gather_step12_ai_repair_proposals can still build a
    record with skip_reason without raising on file IO.
    """
    partial_path = TEMPLATE_DIR / "families" / f"{template_id}.html"
    if not partial_path.is_file():
        return ""
    return partial_path.read_text(encoding="utf-8")


def _b4_partial_exists(template_id: str) -> bool:
    """IMP-95 u6 — partial_exists callable forwarded to plan_placement.

    Returns True iff ``templates/phase_z2/families/{template_id}.html`` is a
    real file on disk. Used by ``_select_frame_v4_aware`` to skip the 19
    contract-only templates (no partial HTML) before accepting a V4 rank.
    Filesystem check only — no IO content read. Sibling of
    ``_load_frame_partial_html`` so both use the same TEMPLATE_DIR /
    families/{id}.html convention; drift between them would be a bug.
    """
    if not template_id:
        return False
    return (TEMPLATE_DIR / "families" / f"{template_id}.html").is_file()


def _run_step12_ai_repair(units) -> list[dict]:
    """IMP-47B u4 — Wire gather_step12_ai_repair_proposals into Step 12.

    Routes provisional units whose IMP-05 hint maps to
    ``ai_adaptation_required`` (``restructure`` + ``reject`` per u1)
    through ``src.phase_z2_ai_fallback.router``. Normal-path units
    (``use_as_is`` / ``light_edit`` / non-provisional) record a
    skip_reason without invoking the router; flag-off runs short-circuit
    at the router (``settings.ai_fallback_enabled=False`` default).
    Returns the per-unit record list — u5 consumes records for
    PARTIAL_OVERRIDES apply and u6 writes the audit artifact.
    """
    return gather_step12_ai_repair_proposals(
        units,
        route_for_label=_imp05_route_hint,
        get_contract_fn=get_contract,
        frame_visual_loader=_load_frame_partial_html,
    )


_REJECT_SUPPORTED_PROPOSAL_KINDS: frozenset[str] = frozenset({"partial_overrides"})

# ── issue #14 — design_adaptation_plan apply (Gitea #98 Task 12 완결) ──
# 롤백된 _emergency_p4_ai_redistribute docstring 이 명시한 승인 아키텍처의
# 5단계: "AI: frame adaptation plan only (구조 조정, 텍스트 X) → CODE: apply".
# op 분류 정책:
#   set_repeat_count / increase_repeat_count → builder 재실행 (원문 무손실 —
#       override 는 max(override, len(groups)) floor 로만 작동)
#   preserve_source_order → already_default (Task 9 가 기본 보장)
#   compact_spacing → policy_skip (T28.5 no_font_shrink + spacing lock —
#       font/line-height/padding 축소는 fit lever 로 금지)
#   rebalance_zone_ratio → policy_skip (CSS/grid 는 code 소유; zone ratio 는
#       retry engine 소유 — AI CSS 주입 금지)
#   split_group_across_repeat_blocks(frame_repeat) → unsupported (frame 다중
#       인스턴스 = 슬라이드 분할 axis, GitHub #26)
#   use_repeatable_frame → unsupported (frame_id locked — V4 rank-1 보호)
_DESIGN_PLAN_KIND = "design_adaptation_plan"
_DESIGN_PLAN_COUNT_OPS = frozenset({"set_repeat_count", "increase_repeat_count"})
# 모델별 count 필드 어휘 변동 관측 (count / repeat_count / to) — 관용 추출.
_DESIGN_PLAN_COUNT_KEYS = ("count", "repeat_count", "to", "target_count")


def _extract_design_plan_count(op: dict) -> Optional[int]:
    for key in _DESIGN_PLAN_COUNT_KEYS:
        val = op.get(key)
        if isinstance(val, bool):
            continue
        if isinstance(val, int) and val > 0:
            return val
        if isinstance(val, str) and val.isdigit() and int(val) > 0:
            return int(val)
    return None
_DESIGN_PLAN_OP_STATUS: dict[str, str] = {
    "preserve_source_order": "already_default:task9_source_order",
    "compact_spacing": "policy_skip:no_font_shrink_spacing_lock",
    "rebalance_zone_ratio": "policy_skip:css_code_owned",
    "split_group_across_repeat_blocks": "unsupported:multi_instance_requires_deck_split",
    "use_repeatable_frame": "unsupported:frame_swap_locked",
}


def _apply_design_adaptation_plan(record: dict, unit, zone: Optional[dict]) -> None:
    """issue #14 — Apply one design_adaptation_plan proposal to its zone.

    구조 op(repeat count)만 verbatim builder 재실행으로 반영하고, 나머지
    op 는 분류 사유와 함께 기록만 한다 (침묵 drop 금지 — PZ-4 surface).
    텍스트는 항상 code(verbatim builder)가 배치하므로 AI 텍스트 유입 경로
    없음 (feedback_ai_isolation_contract).
    """
    payload = (record.get("proposal") or {}).get("payload") or {}
    operations = payload.get("operations") or []
    op_status: list[dict] = []
    target_count: Optional[int] = None
    for op in operations:
        if not isinstance(op, dict):
            op_status.append({"op": str(op), "status": "unsupported_op"})
            continue
        name = str(op.get("op") or "")
        if name in _DESIGN_PLAN_COUNT_OPS:
            op_target = str(op.get("target") or "")
            if "frame_contract" in op_target or "add_sub_zone" in (op.get("details") or {}):
                # frame contract 자체 변이(cardinality/sub_zone 추가)는 catalog
                # 소유 — AI plan 으로 적용 불가 (사용자/코드 승인 axis).
                op_status.append({
                    "op": name,
                    "status": "unsupported:contract_mutation_requires_catalog_change",
                })
                continue
            count = _extract_design_plan_count(op)
            if count is not None:
                target_count = max(target_count or 0, count)
                op_status.append({"op": name, "status": "effective"})
            else:
                op_status.append({"op": name, "status": "invalid_count"})
        else:
            op_status.append({
                "op": name,
                "status": _DESIGN_PLAN_OP_STATUS.get(name, "unsupported_op"),
            })
    record["design_plan_op_status"] = op_status

    if target_count is None:
        record["apply_status"] = "design_plan_no_applicable_op"
        return
    if zone is None:
        record["apply_status"] = "no_zone_match"
        return
    if unit is None:
        record["apply_status"] = "design_plan_unit_unavailable"
        return
    template_id = zone.get("template_id")
    rebuilt = _emergency_p4b_build_verbatim_slot_payload(
        unit, template_id, override_slot_count=target_count,
    )
    if rebuilt is None:
        record["apply_status"] = f"design_plan_builder_unavailable:{template_id}"
        return
    if rebuilt == zone.get("slot_payload"):
        record["apply_status"] = "applied:design_adaptation_plan_no_delta"
        return
    zone["slot_payload"] = rebuilt
    record["apply_status"] = "applied:design_adaptation_plan"


def _apply_ai_repair_proposals_to_zones(
    ai_repair_records: list[dict],
    unit_positions: list[str],
    zones_data: list[dict],
    units: Optional[list] = None,
) -> None:
    """IMP-47B u5 — Apply PARTIAL_OVERRIDES into zones_data.slot_payload.

    Mutates each record's ``apply_status`` in place and merges
    ``proposal.payload.slots`` into the matching zone. Out-of-scope
    kinds (``builder_options_patch``, ``slot_mapping_proposal``)
    loud-fail with ``unsupported_kind_for_reject_route:<kind>`` — zones
    untouched (human_review surfacing → u8). IMP-33 u5 validator
    guarantees declared-slot completeness, so ``dict.update`` is the
    structural merge (``feedback_ai_isolation_contract``).

    issue #14 — ``design_adaptation_plan`` kind 는
    :func:`_apply_design_adaptation_plan` 로 위임 (``units`` 필요 — 미제공
    시 backward-compat 로 ``design_plan_unit_unavailable`` 기록).
    """
    zone_by_position = {z["position"]: z for z in zones_data}
    for record in ai_repair_records:
        proposal = record.get("proposal")
        if proposal is None:
            record["apply_status"] = "no_proposal"
            continue
        kind = proposal.get("proposal_kind")
        # model_dump() 는 str-mixin Enum 멤버를 그대로 반환할 수 있음 —
        # artifact 에 "ProposalKind.X" repr 이 박히지 않도록 value 로 정규화.
        kind = getattr(kind, "value", kind)
        unit_index = record["unit_index"]
        position = (
            unit_positions[unit_index]
            if 0 <= unit_index < len(unit_positions) else None
        )
        zone = zone_by_position.get(position) if position is not None else None
        if kind == _DESIGN_PLAN_KIND:
            unit = (
                units[unit_index]
                if units is not None and 0 <= unit_index < len(units) else None
            )
            _apply_design_adaptation_plan(record, unit, zone)
            continue
        if kind not in _REJECT_SUPPORTED_PROPOSAL_KINDS:
            record["apply_status"] = f"unsupported_kind_for_reject_route:{kind}"
            print(
                f"  [ai-repair-apply] unit {record['unit_index']} "
                f"proposal_kind='{kind}' out-of-scope for reject route — "
                "skipping apply; human_review required.",
                file=sys.stderr,
            )
            continue
        if zone is None:
            record["apply_status"] = "no_zone_match"
            continue
        slots = (proposal.get("payload") or {}).get("slots") or {}
        zone["slot_payload"].update(slots)
        record["apply_status"] = "applied:partial_overrides"


def _apply_text_overrides_to_zones(
    text_overrides: dict,
    zones_data: list[dict],
) -> dict:
    """IMP-56 (#90) u5 — Apply persisted ``text_overrides`` to Step 12 zones.

    Captures the audit shape the Step 12 ``text_overrides`` artifact emits
    so reviewers can see which user text edits re-applied to the next render
    and which silently skipped (stale ``text_path`` after a frame swap /
    layout regression). Per-entry tolerant by design — mirrors the
    ``image_overrides`` u7 contract so a single malformed row never blocks
    a batch (Phase Z PZ-4 "no silent shrink" — surface, don't drop).

    raw_content preservation : the function mutates ``zone["slot_payload"]``
    in place only — ``debug_zones[i].source_section_ids`` and the
    ``MdxSection`` graph live elsewhere and stay byte-identical. This honours
    the Stage 1 binding contract ("raw_content preserved at Step 12") and
    the global no-silent-shrink rule (PZ-4).
    """
    sanitized = _validate_text_overrides(text_overrides or {})
    applied = 0
    skipped = 0
    per_zone: list[dict] = []
    for zone in zones_data:
        zone_id = zone.get("position")
        if not isinstance(zone_id, str) or zone_id not in sanitized:
            continue
        slot_payload = zone.get("slot_payload")
        if not isinstance(slot_payload, dict):
            continue
        z_applied = 0
        z_skipped = 0
        for text_path, value in sanitized[zone_id].items():
            try:
                ok = _apply_text_override(slot_payload, text_path, value)
            except _InvalidTextOverride:
                ok = False
            if ok:
                z_applied += 1
            else:
                z_skipped += 1
        applied += z_applied
        skipped += z_skipped
        per_zone.append({
            "position": zone_id,
            "applied": z_applied,
            "skipped": z_skipped,
        })
    return {"applied": applied, "skipped": skipped, "per_zone": per_zone}


def _apply_structure_overrides_to_zones(
    structure_overrides: dict,
    zones_data: list[dict],
) -> dict:
    """IMP-56 (#90) u7 — Apply persisted ``structure_overrides`` at Step 12.

    SCOPE LOCK : only top-level ``slot_payload`` key membership + ordering
    is mutated (reorder + hide). NO DOM rebuild. NO frame swap — the u6
    validate gate drops any non-``slot_order`` / non-``hidden_slots`` inner
    key silently. Frame swap stays on the existing ``frames`` axis.

    Per-zone tolerant — stale slot_keys (frame swap / layout regression
    between renders) silently no-op via ``apply_structure_override``'s
    ``False`` return (counted as ``skipped_zones``).

    raw_content preservation : per-slot ``list[str]`` line content is
    NEVER inspected or modified here — the resolver only reorders /
    removes top-level slot_payload keys. ``debug_zones[i].source_section_ids``
    + the ``MdxSection`` graph stay byte-identical (mirrors the u5 wiring
    invariant + Stage 1 binding contract).
    """
    sanitized = _validate_structure_overrides(structure_overrides or {})
    applied_zones = 0
    skipped_zones = 0
    per_zone: list[dict] = []
    for zone in zones_data:
        zone_id = zone.get("position")
        if not isinstance(zone_id, str) or zone_id not in sanitized:
            continue
        slot_payload = zone.get("slot_payload")
        if not isinstance(slot_payload, dict):
            continue
        mutated = _apply_structure_override(slot_payload, sanitized[zone_id])
        if mutated:
            applied_zones += 1
        else:
            skipped_zones += 1
        per_zone.append({"position": zone_id, "mutated": mutated})
    return {
        "applied_zones": applied_zones,
        "skipped_zones": skipped_zones,
        "per_zone": per_zone,
    }


def _check_post_ai_coverage_invariant(
    units,
    ai_repair_records: list[dict],
) -> dict:
    """IMP-47B u7 — Verify AI repair preserved every source_section_id.

    Compares the union of unit-level ``source_section_ids`` (pre-AI) to
    the union present on ``ai_repair_records`` post-apply. Per the AI
    isolation contract + dropped 절대 룰
    (``feedback_ai_isolation_contract``), AI repair never removes a
    unit's section coverage. Any divergence indicates a regression that
    u8 surfaces through ``slide_status.ai_repair_status``. The check is
    structural (set membership); the per-record ``source_section_ids``
    list is a copy populated by ``gather_step12_ai_repair_proposals``
    (``step12.py:124``) so apply mutations cannot silently drop it.
    """
    pre_ai_ids: set[str] = set()
    for unit in units:
        pre_ai_ids.update(getattr(unit, "source_section_ids", []) or [])
    post_ai_ids: set[str] = set()
    for record in ai_repair_records:
        post_ai_ids.update(record.get("source_section_ids") or [])
    dropped = sorted(pre_ai_ids - post_ai_ids)
    return {
        "pre_ai_section_ids": sorted(pre_ai_ids),
        "post_ai_section_ids": sorted(post_ai_ids),
        "dropped_section_ids": dropped,
        "status": "ok" if not dropped else "violated",
    }


def _persist_ai_repair_proposals_to_cache(
    ai_repair_records: list[dict],
    *,
    visual_check_passed: bool,
    user_approved: bool,
    auto_cache: bool,
) -> None:
    """IMP-47B u13 — Persist applied AI repair proposals through IMP-46 gates.

    Mutates each record in place with a ``cache_save_status`` axis.
    Only records whose ``apply_status`` starts with ``"applied:"`` and
    that still carry the original ``cache_key`` + ``fingerprints`` + a
    serialized ``proposal`` dict are eligible — everything else marked
    ``not_applied``. Eligible records go through
    ``cache.save_proposal`` with the IMP-46 dual-gate truth table; the
    helper catches :class:`AiFallbackCacheGateError` so a gate block is
    surfaced (``gate_blocked:<reason>``) without raising into the
    pipeline runtime (the cache is a hint, never a hard dependency —
    cache.py contract). ``visual_check_passed`` is never bypassable;
    ``auto_cache=True`` bypasses ONLY the ``user_approved`` gate per
    IMP-46 u5. Pure save layer: no AI call, no MDX touch.
    """
    from src.phase_z2_ai_fallback.cache import (
        AiFallbackCacheGateError,
        save_proposal,
    )
    from src.phase_z2_ai_fallback.schema import AiFallbackProposal
    for record in ai_repair_records:
        apply_status = record.get("apply_status") or ""
        proposal_dict = record.get("proposal")
        cache_key = record.get("cache_key")
        fingerprints = record.get("fingerprints")
        if (
            not apply_status.startswith("applied:")
            or not isinstance(proposal_dict, dict)
            or not cache_key
            or not isinstance(fingerprints, dict)
        ):
            record["cache_save_status"] = "not_applied"
            continue
        try:
            proposal_obj = AiFallbackProposal.model_validate(proposal_dict)
        except Exception as exc:  # noqa: BLE001 — invalid payload → skip, never raise
            record["cache_save_status"] = f"invalid_proposal:{type(exc).__name__}"
            continue
        try:
            save_proposal(
                cache_key,
                proposal_obj,
                visual_check_passed=visual_check_passed,
                user_approved=user_approved,
                auto_cache=auto_cache,
                fingerprints=fingerprints,
            )
        except AiFallbackCacheGateError as gate_exc:
            record["cache_save_status"] = f"gate_blocked:{gate_exc}"
            continue
        record["cache_save_status"] = "saved"


def _summarize_ai_repair_status(
    ai_repair_records: list[dict],
    coverage_invariant: dict,
) -> dict:
    """IMP-47B u8 — Classify Step 12 AI repair outcomes for slide_status surfacing.

    Reads u4 gather ``error`` + u5 ``apply_status`` + u7 coverage_invariant
    to derive a single ``ai_repair_status`` axis attached to
    ``slide_status``. Failure-axis priority (highest → lowest):
    ``error`` > ``coverage_violated`` > ``unsupported_kind`` > ``applied`` > ``ok``.
    ``human_review_required`` flips True on the three failure axes so the
    frontend (u11) can surface a notification per the IMP-47B policy
    ("AI 호출 실패 / proposal validation 실패 / coverage 미달 → frontend notification").
    Pure: no IO, no AI call.

    IMP-92 u3 — propagate ``api_error_kind`` (quota / billing / auth /
    other) stamped by Step 12 (u2 ``classify_operational_error``) through
    ``ai_repair_status`` so the frontend operational formatter can route
    only operational kinds (quota / billing / auth) to user-visible
    alerts. ``api_error_kinds`` aggregates counts by kind at the summary
    level; ``error_records[i]["api_error_kind"]`` retains the per-record
    kind for unit-level surfacing.
    """
    counts = {
        "total": len(ai_repair_records),
        "applied": 0,
        "no_proposal": 0,
        "no_zone_match": 0,
        "unsupported_kind": 0,
        "error": 0,
    }
    api_error_kinds = {"quota": 0, "billing": 0, "auth": 0, "other": 0}
    unsupported_records: list[dict] = []
    error_records: list[dict] = []
    for record in ai_repair_records:
        if record.get("error"):
            counts["error"] += 1
            kind = record.get("api_error_kind")
            if kind in api_error_kinds:
                api_error_kinds[kind] += 1
            error_records.append({
                "unit_index": record.get("unit_index"),
                "source_section_ids": list(record.get("source_section_ids") or []),
                "error": record.get("error"),
                "api_error_kind": kind,
            })
            continue
        apply_status = record.get("apply_status") or ""
        if apply_status.startswith("applied:"):
            counts["applied"] += 1
        elif apply_status.startswith("unsupported_kind_for_reject_route:"):
            counts["unsupported_kind"] += 1
            unsupported_records.append({
                "unit_index": record.get("unit_index"),
                "source_section_ids": list(record.get("source_section_ids") or []),
                "apply_status": apply_status,
            })
        elif apply_status == "no_zone_match":
            counts["no_zone_match"] += 1
        else:
            counts["no_proposal"] += 1
    coverage_status = (coverage_invariant or {}).get("status", "ok")
    dropped = list((coverage_invariant or {}).get("dropped_section_ids") or [])
    if counts["error"]:
        status = "error"
    elif coverage_status != "ok":
        status = "coverage_violated"
    elif counts["unsupported_kind"]:
        status = "unsupported_kind"
    elif counts["applied"]:
        status = "applied"
    else:
        status = "ok"
    return {
        "status": status,
        "counts": counts,
        "api_error_kinds": api_error_kinds,
        "unsupported_kind_records": unsupported_records,
        "error_records": error_records,
        "coverage_status": coverage_status,
        "dropped_section_ids": dropped,
        "human_review_required": status in {"error", "coverage_violated", "unsupported_kind"},
    }


def lookup_v4_match_with_fallback(
    v4: dict,
    section_id: str,
    *,
    raw_content: Optional[str] = None,
    max_rank: Optional[int] = None,
    alias_keys: Optional[list] = None,
    allow_provisional: bool = False,
) -> tuple[Optional[V4Match], dict]:
    """Select V4 rank-1, or promote rank-2..N when rank-1 is not auto-renderable.

    This is an IMP-05 selector only. It uses existing V4 labels, frame-contract
    presence, and the Phase Z capacity precheck; it does not call calculate_fit.

    IMP-30 u1 — when ``allow_provisional=True`` and the rank-1..effective_max_rank
    chain is exhausted (no candidate passes MVP1 filter + contract + capacity),
    the selector synthesizes a *provisional* V4Match from the rank-1 judgment so
    the first-render invariant can be satisfied downstream. The synthesized
    match carries ``provisional=True``, ``selection_path="provisional_rank_1"``,
    and ``fallback_reason`` mirrors the existing chain-exhaust reason. The
    candidate trace shape is unchanged (synthetic injection only updates the
    top-level ``selection_path`` + ``selected_*`` mirrors). When the rank-1
    judgment itself is missing (``empty_v4_judgments`` / ``no_v4_section``),
    no provisional is synthesized — the caller handles those cases with a
    placeholder zone or empty-shell.

    Default ``allow_provisional=False`` keeps the IMP-05 behavior byte-identical.

    IMP-38 — dynamic effective max_rank via ``load_v4_fallback_policy()``
    (4 round 합의 / Codex #1~#3 + Claude #1~#4 LOCK at #67 comment 23195):
      - ``max_rank=None`` (default) → policy applied:
          usable_count = candidates in rank 1..default_max_rank passing 3-tier
          predicate (status in MVP1 + catalog registered + optional capacity).
          usable_count >= usable_threshold → effective_max_rank = default_max_rank.
          Otherwise → effective_max_rank = min(extended_max_rank,
          len(judgments_full32)) = effective_extended_ceiling (Codex #2 정정).
      - ``max_rank`` explicitly passed → caller_override: that value is used
          as-is (backward compat for tests / explicit IMP-05/IMP-30 paths).

    Trace gains 8 IMP-38 fields: ``requested_max_rank``, ``default_max_rank``,
    ``configured_extended_max_rank``, ``judgments_count``,
    ``effective_extended_ceiling``, ``effective_max_rank``, ``usable_count``,
    ``policy_applied``. ``max_rank`` legacy field kept as alias for backward
    compat (= effective_max_rank).
    """
    resolved = _resolve_v4_section_key(v4, section_id, alias_keys=alias_keys)
    sec = v4.get("mdx_sections", {}).get(resolved) if resolved else None
    all_judgments = (sec.get("judgments_full32") if sec else None) or []
    judgments_count = len(all_judgments)

    # IMP-38 — load policy (graceful: yaml 없을 시 default_max_rank=3, extended=3)
    _policy = load_v4_fallback_policy()
    default_max_rank = int(_policy.get("default_max_rank", 3))
    configured_extended_max_rank = int(_policy.get("extended_max_rank", default_max_rank))
    usable_threshold = int(_policy.get("usable_threshold", 1))
    # Codex #2 정정: min(configured, len(judgments_full32)) — yaml ceiling 무력화 방지
    effective_extended_ceiling = min(configured_extended_max_rank, judgments_count) if judgments_count else default_max_rank

    usable_count: Optional[int] = None  # set only when policy path active
    if max_rank is not None:
        # caller override (backward compat — explicit IMP-05/IMP-30 paths, tests)
        effective_max_rank = int(max_rank)
        policy_applied = "caller_override"
    elif judgments_count == 0:
        # no judgments — slicing 빈 list 라 어차피 영향 X
        effective_max_rank = default_max_rank
        policy_applied = "no_judgments"
    else:
        # IMP-38 policy path — 3-tier predicate usable_count on default window
        usable_count = 0
        default_window = all_judgments[:default_max_rank]
        for _j in default_window:
            _m = _v4_match_from_judgment(section_id, _j, rank=0)
            if to_phase_z_status(_m) not in MVP1_ALLOWED_STATUSES:
                continue
            if get_contract(_m.template_id) is None:
                continue
            if raw_content is not None:
                _cap = compute_capacity_fit(_m.template_id, raw_content)
                if _cap and _cap.get("fit_status") not in {
                    "ok", "no_contract", "unknown_source_shape",
                }:
                    continue
            usable_count += 1

        if usable_count >= usable_threshold:
            effective_max_rank = default_max_rank
            policy_applied = "default_max_rank"
        else:
            effective_max_rank = effective_extended_ceiling
            policy_applied = "extended_max_rank"

    trace = {
        "section_id": section_id,
        # IMP-38 — 8 trace fields (4 round LOCK)
        "requested_max_rank": max_rank,
        "default_max_rank": default_max_rank,
        "configured_extended_max_rank": configured_extended_max_rank,
        "judgments_count": judgments_count,
        "effective_extended_ceiling": effective_extended_ceiling,
        "effective_max_rank": effective_max_rank,
        "usable_count": usable_count,
        "policy_applied": policy_applied,
        # legacy alias for backward compat (= effective_max_rank)
        "max_rank": effective_max_rank,
        "selection_path": "no_v4_candidate",
        "selected_rank": None,
        "selected_template_id": None,
        "selected_frame_id": None,
        "selected_label": None,
        "fallback_used": False,
        "fallback_reason": None,
        "candidates": [],
    }
    if not sec:
        trace["fallback_reason"] = "no_v4_section"
        return None, trace

    judgments = all_judgments[:effective_max_rank]
    if not judgments:
        trace["fallback_reason"] = "empty_v4_judgments"
        return None, trace

    # IMP-39 (#68) u2 — apply single-source ranking sort policy to the selected
    # window AFTER IMP-38 raw-window calc (default_window / usable_count above
    # remain RAW all_judgments-based — no silent interaction with fallback
    # expansion). Selection order now follows
    #   (label_priority asc, confidence desc, v4_rank asc)
    # so backend selected rank-1 matches frontend frame_candidates[0]
    # (designAgentApi.ts:578-597 LABEL_PRIORITY + confidence-desc mirror).
    # `v4_rank_key="v4_full_rank"` reads the RAW V4 confidence-rank from each
    # judgment dict for tie-break (yaml: tie_break_axes=[confidence_desc,
    # v4_rank_asc]). Input list is NOT mutated (apply_ranking_sort returns a
    # new list). Trace fields (sorted_candidate_evidence / ranking_sort_policy)
    # are forwarded through Step 9 payload in u3.
    ranking_sort_policy = load_ranking_sort_policy()
    judgments = apply_ranking_sort(
        judgments,
        policy=ranking_sort_policy,
        label_key="label",
        confidence_key="confidence",
        v4_rank_key="v4_full_rank",
    )
    trace["ranking_sort_policy_applied"] = ranking_sort_policy.get(
        "policy_type", "deterministic_label_priority_then_confidence"
    )

    first_skip_reason: Optional[str] = None
    # IMP-05 L4 dedup (Codex #14 ordering — Claude #16 placement precision) :
    # first occurrence claims template_id for the chain regardless of decision
    # (selected/non-direct/rejected/missing-contract/capacity-skipped). Defensive
    # against V4 anomaly where same template_id appears at multiple ranks with
    # different labels — first label/reason is preserved, later duplicates skip.
    seen_template_ids: set[str] = set()
    for i, judgment in enumerate(judgments, start=1):
        match = _v4_match_from_judgment(section_id, judgment, rank=i)
        status = to_phase_z_status(match)
        # IMP-05 L2 (Codex #10 E4) — informative candidate_evidence schema.
        # `v4_label` naming matches Codex schema (Claude #13 §1 lock).
        # `filtered_for_direct_execution` + `route_hint` = L5 restructure/reject trace 보존
        # 단일 source (frontend/AI future consumer guidance).
        is_direct_eligible = status in MVP1_ALLOWED_STATUSES
        catalog_registered = get_contract(match.template_id) is not None
        candidate_trace = {
            "rank": i,
            "template_id": match.template_id,
            "frame_id": match.frame_id,
            "frame_number": match.frame_number,
            "confidence": match.confidence,
            "label": match.label,                    # existing — kept for backward compat
            "v4_label": match.label,                 # IMP-05 L2 alias (Codex schema)
            "phase_z_status": status,
            "candidate_status": match.candidate_status,
            "coverage_state": _candidate_coverage_state(
                match.candidate_status,
                label=match.label,
                catalog_registered=catalog_registered,
                selection_path=match.selection_path,
            ),
            "catalog_registered": catalog_registered,
            "filtered_for_direct_execution": not is_direct_eligible,  # IMP-05 L2/L5
            "route_hint": _imp05_route_hint(match.label),             # IMP-05 L2/L5
            "decision": "skipped",
            "reason": None,
        }

        # IMP-05 L4 dedup — duplicate check BEFORE rank evaluation.
        # First occurrence reserves template_id even if non-direct/rejected/skipped.
        # Later rank with same template_id is skipped as duplicate, audit fields preserved.
        if match.template_id in seen_template_ids:
            candidate_trace["reason"] = "duplicate_template_id"
            trace["candidates"].append(candidate_trace)
            continue
        seen_template_ids.add(match.template_id)

        if status not in MVP1_ALLOWED_STATUSES:
            candidate_trace["reason"] = f"phase_z_status_not_allowed:{status}"
        elif get_contract(match.template_id) is None:
            candidate_trace["reason"] = "skipped_no_contract"
        else:
            capacity_fit = None
            if raw_content is not None:
                capacity_fit = compute_capacity_fit(match.template_id, raw_content)
                candidate_trace["capacity_fit"] = capacity_fit
            if capacity_fit and capacity_fit.get("fit_status") not in {
                "ok", "no_contract", "unknown_source_shape",
            }:
                candidate_trace["reason"] = f"capacity_mismatch:{capacity_fit.get('fit_status')}"
            else:
                fallback_used = i > 1
                fallback_reason = first_skip_reason if fallback_used else None
                match.selection_path = f"rank_{i}" if not fallback_used else f"rank_{i}_fallback"
                match.fallback_reason = fallback_reason
                candidate_trace["decision"] = "selected"
                candidate_trace["reason"] = "primary_selected" if i == 1 else "fallback_selected"
                trace["candidates"].append(candidate_trace)
                trace.update({
                    "selection_path": match.selection_path,
                    "selected_rank": i,
                    "selected_template_id": match.template_id,
                    "selected_frame_id": match.frame_id,
                    "selected_label": match.label,
                    "fallback_used": fallback_used,
                    "fallback_reason": fallback_reason,
                })
                return match, trace

        if i == 1:
            first_skip_reason = candidate_trace["reason"]
        trace["candidates"].append(candidate_trace)

    trace["selection_path"] = "chain_exhausted"
    trace["fallback_reason"] = first_skip_reason or f"no_auto_renderable_rank_1_to_{effective_max_rank}"

    # IMP-30 u1 — opt-in provisional first-render synthesis. When the caller
    # signals allow_provisional, promote rank-1 judgment as a provisional
    # match so downstream composition can satisfy the first-render invariant.
    # Top-level mirrors (selection_path / selected_*) are updated; candidate
    # trace entries are left intact (their skip reasons remain accurate).
    # Default-off keeps IMP-05 behavior byte-identical.
    if allow_provisional:
        # issue #17 — renderable-aware provisional. rank 순서는 유지하되
        # 승격 가능 조건: partial HTML 존재 (IMP-95 u6 partial_exists 원칙)
        # AND (비-reject 라벨 OR verbatim builder 지원). 근거 실측:
        #   - partial 없는 frame 승격 → mapper FitError → verbatim 복구 →
        #     selected_frame_not_applied 라벨 (mdx05 05-2 rank-1 F6)
        #   - reject 라벨 + verbatim builder 없는 frame 의 mapper 네이티브
        #     렌더는 원문 drop 위험 (mdx05 05-2 F23: 1 atom 손실 실측 —
        #     원문 보존이 design 개선보다 우선)
        # 조건 만족 후보가 없으면 기존대로 rank-1 (동작 보존 — verbatim
        # 복구가 텍스트 무손실을 보장).
        provisional_judgment = judgments[0]
        provisional_rank = 1
        for _rank, _judgment in enumerate(judgments, start=1):
            _tid = str(_judgment.get("template_id") or "")
            if not _b4_partial_exists(_tid):
                continue
            _label = str(_judgment.get("label") or "")
            if _label == "reject" and _tid not in _VERBATIM_BUILDER_TEMPLATE_IDS:
                continue
            provisional_judgment, provisional_rank = _judgment, _rank
            break
        provisional_match = _v4_match_from_judgment(
            section_id, provisional_judgment, rank=provisional_rank
        )
        _prov_path = (
            "provisional_rank_1"
            if provisional_rank == 1
            else f"provisional_renderable_rank_{provisional_rank}"
        )
        provisional_match.selection_path = _prov_path
        provisional_match.fallback_reason = trace["fallback_reason"]
        provisional_match.provisional = True
        trace.update({
            "selection_path": _prov_path,
            "selected_rank": provisional_rank,
            "selected_template_id": provisional_match.template_id,
            "selected_frame_id": provisional_match.frame_id,
            "selected_label": provisional_match.label,
            "fallback_used": True,
            "provisional": True,
        })
        return provisional_match, trace

    return None, trace


def lookup_v4_all_judgments(
    v4: dict, section_id: str, *, alias_keys: Optional[list] = None
) -> list[V4Match]:
    """V4 raw 32 entry 그대로 반환 — reject 포함, max_n filter 없음.

    Step 7-A axis 보강 (사용자 lock 2026-05-08) — 사용자 UI 가 모든 frame 의
    png 를 보여줄 수 있도록 reject 까지 trace. lookup_v4_candidates 는 변경 없음
    (backward compat — non-reject + max_n 만 반환).

    Returns :
      list[V4Match] — 0~32 길이. raw judgments_full32 순서 (= V4 score desc) 보존.
    """
    resolved = _resolve_v4_section_key(v4, section_id, alias_keys=alias_keys)
    sec = v4.get("mdx_sections", {}).get(resolved) if resolved else None
    if not sec:
        return []
    judgments = sec.get("judgments_full32", [])
    out: list[V4Match] = []
    for j in judgments:
        out.append(_v4_match_from_judgment(section_id, j))
    return out


def _is_visual_pending(template_id: str) -> bool:
    """IMP-#85 u4 — return True iff catalog marks contract as ``visual_pending``.

    Data-driven from ``frame_contracts.yaml`` (no hard-coded frame allow-list).
    Used by ``lookup_v4_candidates`` to exclude VP frames from the live
    candidate set; ``lookup_v4_all_judgments`` raw telemetry stays untouched
    (Step 7-A axis preserves full 32-frame evidence for the frontend).
    """
    contract = get_contract(template_id)
    if not isinstance(contract, dict):
        return False
    return contract.get("visual_pending") is True


def lookup_v4_candidates(
    v4: dict,
    section_id: str,
    max_n: int = 6,
    *,
    alias_keys: Optional[list] = None,
    include_reject: bool = True,
    include_blocked_runtime: bool = True,
) -> list[V4Match]:
    """V4 후보 list 반환 — Emergency P2 + P2.5 (2026-05-26) policy 반영.

    이전 동작 (May 8 lock) : reject drop + visual_pending drop. 0 길이 가능.
    신 동작 (emergency.md §3 policy) :
      include_reject=True (default)          : reject 도 보존 (candidate_status =
                                                ai_adaptation_required).
      include_reject=False                   : reject drop (backward compat).
      include_blocked_runtime=True (default) : visual_pending 도 보존 (candidate_status =
                                                blocked_runtime — frontend / telemetry surface).
      include_blocked_runtime=False          : visual_pending drop (backward compat).
      max_n                                  : 그대로 — 상한선.

    Emergency P2.5 (C2) : V4 source 의 split child keys (예: 04-2.1 / 04-2.2) 와
      pipeline parent key (예: 04-2) mismatch 를 universal child pool merge 로 해소.
      _resolve_v4_section_keys_with_children 가 parent → children list 반환.
      모든 child 의 candidates 를 합쳐 max_n 까지 trim. 각 V4Match 의 section_id 는
      parent 그대로 (downstream 가 parent 관점 유지).

    Returns :
      list[V4Match] — 0~max_n 길이. 각 V4Match 에 candidate_status field.
      0 길이 = catalog gap (V4 source 에 parent + children 모두 없음 OR 필터 후 0) —
              P3 의 generic_fallback route 로 흐름.

    Backward compat (May 8 lock 동작 byte-identical) :
      include_reject=False, include_blocked_runtime=False
        + parent ↔ child merge 효과 는 동일 (parent key miss 시 OLD 도 [] 반환했음 →
        새 child merge 로 후보 surface 는 OLD 보다 풍성. 단 OLD caller 는
        empty 또는 매우 적은 후보 받는 케이스 만 영향 — 회귀 아니라 fix).
    """
    resolved_keys = _resolve_v4_section_keys_with_children(
        v4, section_id, alias_keys=alias_keys,
    )
    if not resolved_keys:
        return []
    sections_map = v4.get("mdx_sections", {})
    candidates: list[V4Match] = []
    for resolved in resolved_keys:
        sec = sections_map.get(resolved)
        if not sec:
            continue
        judgments = sec.get("judgments_full32", [])
        for j in judgments:
            label = j.get("label")
            if label == "reject" and not include_reject:
                continue
            tid = j.get("template_id")
            if not include_blocked_runtime and tid and _is_visual_pending(tid):
                continue
            # V4Match 의 section_id = parent (downstream 의 parent 관점 유지).
            # child origin 은 frame_id / template_id 로 implicit 추적 가능 (별도 origin
            # field 불필요 — debug 시 v4_full32_result.yaml 의 children section 으로
            # 역추적 가능).
            candidates.append(_v4_match_from_judgment(section_id, j))
            if len(candidates) >= max_n:
                break
        if len(candidates) >= max_n:
            break
    return candidates


_CATALOG_FALLBACK_TEMPLATE_ORDER = [
    "three_parallel_requirements",
    "three_persona_benefits",
    "construction_bim_three_usage",
    "construction_goals_three_circle_intersection",
    "bim_dx_comparison_table",
    "bim_issues_quadrant_four",
    "pre_construction_model_info_stacked",
    "process_product_two_way",
]


def lookup_catalog_fallback_candidates(section_id: str, max_n: int = 6) -> list[V4Match]:
    """Return renderable catalog candidates when V4 evidence is absent.

    T20e policy: a missing V4 source is a catalog/matching gap, not "no
    candidates".  Surface reusable frame structures as ai_adaptation_required
    candidates so the frontend can show a selectable 3-6 candidate pool while
    preserving the selected generic fallback path.
    """
    contracts = load_frame_contracts()
    out: list[V4Match] = []
    for idx, template_id in enumerate(_CATALOG_FALLBACK_TEMPLATE_ORDER, start=1):
        contract = contracts.get(template_id) or {}
        partial_path = PROJECT_ROOT / "templates" / "phase_z2" / "families" / f"{template_id}.html"
        if not contract or not partial_path.exists() or contract.get("visual_pending") is True:
            continue
        out.append(V4Match(
            section_id=section_id,
            frame_id=str(contract.get("frame_id") or template_id),
            frame_number=int(contract.get("frame_number") or idx),
            template_id=template_id,
            confidence=0.0,
            label="reject",
            v4_rank=None,
            selection_path="catalog_fallback",
            fallback_reason="no_v4_source:catalog_fallback",
            provisional=True,
            candidate_status="ai_adaptation_required",
            coverage_state="requires_adaptation",
        ))
        if len(out) >= max_n:
            break
    return out


def _apply_frame_override_to_unit(unit, new_tid: str, v4: dict) -> str:
    """IMP-47B u3 — apply a frame override to *unit* in place.

    Returns a meta_source string for the override book-keeping. Three
    probe layers, in order:

      1. ``unit.v4_candidates`` (non-reject, max_n bounded). Copies
         frame_id / frame_number / confidence / label from the matching
         candidate so Step 9 metadata stays consistent. Returns
         ``"v4_candidates"``.
      2. Full 32 V4 judgments (reject inclusive). When the override
         target matches a reject judgment for the unit's primary section,
         the unit is promoted to ``provisional=True`` with ``label="reject"``
         so Step 12 (IMP-47B u4) admits the AI repair path. Returns
         ``"v4_reject_judgment_provisional"``.
      3. Raw fall-through. Updates only ``frame_template_id``; returns
         ``"raw_template_id_only"``.

    Frame visual / contract stay untouched per the AI isolation contract
    (frame auto-swap forbidden — AI re-places content into the existing
    frame only). The caller validates catalog contract presence before
    invoking this helper.
    """
    for cand in (unit.v4_candidates or []):
        if getattr(cand, "template_id", None) == new_tid:
            unit.frame_template_id = cand.template_id
            unit.frame_id = cand.frame_id
            unit.frame_number = cand.frame_number
            unit.confidence = cand.confidence
            unit.label = cand.label
            return "v4_candidates"
    primary_sid = (
        unit.source_section_ids[0] if unit.source_section_ids else None
    )
    if primary_sid:
        for j in lookup_v4_all_judgments(v4, primary_sid):
            if j.template_id == new_tid and j.label == "reject":
                unit.frame_template_id = j.template_id
                unit.frame_id = j.frame_id
                unit.frame_number = j.frame_number
                unit.confidence = j.confidence
                unit.label = "reject"
                unit.provisional = True
                return "v4_reject_judgment_provisional"
    unit.frame_template_id = new_tid
    return "raw_template_id_only"


# ─── Content weight + zone layout 계산 ─────────────────────────
# layout preset 선택은 phase_z2_composition.select_layout_preset (composition v0) 가 담당.
# 본 모듈의 select_layout_preset 은 이전 단순 count-based 구현이었고 dead code 로 제거 (2026-04-29).

def compute_content_weight(section: MdxSection) -> dict:
    """Section 의 콘텐츠 부피 측정 — text/bullet/table/subsection 합성 score."""
    text = section.raw_content
    lines = text.splitlines()

    text_len = len(text)
    top_bullets = sum(1 for l in lines if re.match(r"^[\*\-]\s", l))
    nested_bullets = sum(1 for l in lines if re.match(r"^\s+[\*\-]\s", l))
    has_table = bool(re.search(r"\|[^\n]+\|\n[ \t]*\|[\s\-:|]+\|", text))
    subsections = len(re.findall(r"^###\s", text, re.MULTILINE))

    c = CONTENT_WEIGHT_COEFFS
    score = (
        text_len / c["text_per_chars"]
        + top_bullets * c["top_bullet"]
        + nested_bullets * c["nested_bullet"]
        + (c["table_bonus"] if has_table else 0)
        + subsections * c["subsection"]
    )
    return {
        "score": round(score, 3),
        "text_length": text_len,
        "top_bullets": top_bullets,
        "nested_bullets": nested_bullets,
        "has_table": has_table,
        "subsection_count": subsections,
    }


def _count_payload_text_lines(value: Any) -> int:
    """Count verbatim text-line atoms in a slot payload tree."""
    if value is None:
        return 0
    if isinstance(value, list):
        return sum(_count_payload_text_lines(v) for v in value)
    if isinstance(value, dict):
        if "text" in value:
            return 1
        return sum(_count_payload_text_lines(v) for v in value.values())
    if isinstance(value, str):
        return len([part for part in value.split("<br>") if normalize_markdown_inline_text(part)])
    return 0


def _estimate_payload_min_height_px(zone: dict) -> Optional[int]:
    """Estimate a zone min-height from the actual slot payload.

    T20d policy: never reduce font size to force fit.  If a frame has more
    text-bearing internal slots than its catalog min-height expects, prefer a
    payload-aware row budget so layout solves fit by geometry.
    """
    payload = zone.get("slot_payload") or {}
    template_id = zone.get("template_id") or ""
    if not payload:
        return None

    if template_id == "three_parallel_requirements":
        pillars = payload.get("pillars") or []
        max_lines = 0
        for pillar in pillars:
            max_lines = max(max_lines, _count_payload_text_lines(pillar.get("sections") or []))
        return max(180, 108 + max_lines * 18)

    if template_id == "process_product_two_way":
        process_lines = _count_payload_text_lines((payload.get("process") or {}).get("sections") or [])
        product_lines = _count_payload_text_lines((payload.get("product") or {}).get("sections") or [])
        return max(360, 220 + max(process_lines, product_lines) * 10)

    if template_id == "bim_issues_quadrant_four":
        slot_count = int(payload.get("_slot_count") or 4)
        max_lines = 0
        for n in range(1, slot_count + 1):
            max_lines = max(max_lines, _count_payload_text_lines(payload.get(f"quadrant_{n}_body") or []))
        return max(300, 176 + max_lines * 24)

    if template_id == "construction_bim_three_usage":
        max_lines = 0
        for n in range(1, int(payload.get("_slot_count") or 3) + 1):
            max_lines = max(max_lines, _count_payload_text_lines(payload.get(f"category_{n}_body") or []))
        return max(220, 140 + max_lines * 36)

    if template_id == "pre_construction_model_info_stacked":
        slot_count = int(payload.get("_slot_count") or 5)
        max_lines = 0
        for n in range(1, slot_count + 1):
            max_lines = max(max_lines, _count_payload_text_lines(payload.get(f"pill_{n}_body") or []))
        return max(240, 150 + max_lines * 25)

    if template_id == "three_persona_benefits":
        personas = payload.get("personas") or []
        max_lines = 0
        for persona in personas:
            max_lines = max(max_lines, _count_payload_text_lines(persona.get("body") or []))
        return max(220, 130 + max_lines * 26)

    return None


def _payload_repeat_count(template_id: str, payload: dict) -> Optional[int]:
    if not isinstance(payload, dict):
        return None
    if "_slot_count" in payload:
        try:
            return int(payload.get("_slot_count") or 0)
        except (TypeError, ValueError):
            return None
    if template_id == "three_parallel_requirements":
        return len(payload.get("pillars") or [])
    if template_id == "three_persona_benefits":
        return len(payload.get("personas") or [])
    if template_id == "bim_dx_comparison_table":
        return len(payload.get("rows") or [])
    return None


def _frame_expansion_trace(template_id: str, payload: dict) -> dict:
    contract = get_contract(template_id) or {}
    dynamic = contract.get("dynamic_cardinality") or {}
    base_items = dynamic.get("base_items")
    if base_items is None:
        cardinality = contract.get("cardinality") or {}
        base_items = cardinality.get("strict")
    try:
        base = int(base_items) if base_items is not None else None
    except (TypeError, ValueError):
        base = None
    actual = _payload_repeat_count(template_id, payload)
    repeatable = bool(dynamic.get("repeatable"))
    expanded = bool(repeatable and base is not None and actual is not None and actual > base)
    return {
        "coverage_state": "covered_via_expand" if expanded else "covered_native",
        "expanded": expanded,
        "repeatable": repeatable,
        "repeat_axis": dynamic.get("repeat_axis"),
        "expand_policy": dynamic.get("expand_policy"),
        "base_items": base,
        "actual_items": actual,
        "font_policy": "no_font_shrink",
    }


def compute_zone_layout(zones_data: list[dict],
                        total_height: int = SLIDE_BODY_HEIGHT,
                        gap: int = GRID_GAP) -> dict:
    """zone height 계산 — frame_min_height_px 우선 + 남은 공간 content_weight 비율 분배.

    Returns dict with per-zone heights + reasoning trace.
    """
    n = len(zones_data)
    if n == 0:
        return {"heights_px": [], "ratios": [], "zones": []}

    available = total_height - gap * (n - 1)

    # Step 1: 각 zone 의 min_height 할당 — pipeline 가 zones_data 에 frame contract 의
    # visual_hints.min_height_px 를 미리 주입했음. 없으면 DEFAULT_ZONE_MIN_HEIGHT_PX.
    catalog_min_heights = [
        z.get("min_height_px", DEFAULT_ZONE_MIN_HEIGHT_PX)
        for z in zones_data
    ]
    payload_min_heights = [_estimate_payload_min_height_px(z) for z in zones_data]
    min_heights = [
        payload_min if payload_min is not None else catalog_min
        for catalog_min, payload_min in zip(catalog_min_heights, payload_min_heights)
    ]
    total_min = sum(min_heights)
    min_scaled = False
    if total_min > available:
        scale = available / total_min
        min_heights = [int(m * scale) for m in min_heights]
        total_min = sum(min_heights)
        min_scaled = True

    remaining = available - total_min

    # Step 2: 남은 공간을 content_weight 비율로 분배
    weights = [z["content_weight"]["score"] for z in zones_data]
    total_w = sum(weights) if sum(weights) > 0 else n
    extras = [int(round(remaining * (w / total_w))) for w in weights]

    # Step 3: rounding 보정 (마지막 zone 잔여 흡수)
    heights = [m + e for m, e in zip(min_heights, extras)]
    diff = available - sum(heights)
    if diff != 0 and heights:
        heights[-1] += diff

    ratios = [round(h / total_height, 3) for h in heights]

    return {
        "computation": "min_height_first + content_weight_distribution",
        "slide_body_height": total_height,
        "gap": gap,
        "available_after_gap": available,
        "min_heights_px": min_heights,
        "catalog_min_heights_px": catalog_min_heights,
        "payload_min_heights_px": payload_min_heights,
        "min_scaled": min_scaled,
        "total_min_height": total_min,
        "remaining_after_min": remaining,
        "content_weights": [{"position": z["position"],
                              "template_id": z["template_id"],
                              "score": w}
                             for z, w in zip(zones_data, weights)],
        "weight_shares": [round(w / total_w, 3) for w in weights],
        "extras_px": extras,
        "heights_px": heights,
        "ratios": ratios,
    }


# ─── IMP-09 PR 1 helpers (8-preset layout vocabulary) ────────────────
# Catalog css_areas / css_cols / css_rows parsing + per-zone aggregation
# + col-axis solver. Symmetric counterparts to compute_zone_layout (row-axis).


def _parse_css_areas(css_areas: str) -> tuple[list[list[str]], list[str]]:
    """Parse CSS grid-template-areas string into (row x col) cell grid.

    Input  : '"top top" "bottom-left bottom-right"'
    Output : (
        [["top", "top"], ["bottom-left", "bottom-right"]],
        ["top", "bottom-left", "bottom-right"],
    )

    Raises ValueError on empty input, missing quotes, empty row, or
    non-rectangular layout (rows with mismatched column counts).
    """
    rows: list[list[str]] = []
    seen: list[str] = []
    quoted = re.findall(r'"([^"]+)"', css_areas)
    if not quoted:
        raise ValueError(
            f"_parse_css_areas: no quoted row strings found in {css_areas!r}"
        )
    for row_str in quoted:
        tokens = row_str.split()
        if not tokens:
            raise ValueError(
                f"_parse_css_areas: empty row in {css_areas!r}"
            )
        rows.append(tokens)
        for token in tokens:
            if token not in seen:
                seen.append(token)
    col_counts = {len(r) for r in rows}
    if len(col_counts) > 1:
        raise ValueError(
            f"_parse_css_areas: non-rectangular grid, row column counts = "
            f"{col_counts} in {css_areas!r}"
        )
    return rows, seen


def _parse_fr_string(spec: str, total: int) -> list[int]:
    """Parse '1fr' / '1fr 1fr' / 'Nfr Mfr' into integer px lengths.

    Catalog presets (templates/phase_z2/layouts/layouts.yaml) only use
    1fr-only specs; mixed px/fr is out of scope. Raises ValueError on
    non-fr tokens or zero total.
    """
    fractions: list[float] = []
    for token in spec.split():
        m = re.fullmatch(r"(\d+(?:\.\d+)?)fr", token)
        if not m:
            raise ValueError(
                f"_parse_fr_string: non-fr token {token!r} in {spec!r}"
            )
        fractions.append(float(m.group(1)))
    if not fractions:
        raise ValueError(f"_parse_fr_string: empty spec {spec!r}")
    total_fr = sum(fractions)
    if total_fr <= 0:
        raise ValueError(f"_parse_fr_string: total fr = 0 in {spec!r}")
    sizes = [int(round(total * (f / total_fr))) for f in fractions]
    sizes[-1] += total - sum(sizes)
    return sizes


def compute_zone_layout_cols(zones_data: list[dict],
                             total_width: int = SLIDE_BODY_WIDTH,
                             gap: int = GRID_GAP) -> dict:
    """Per-zone column width allocation — weight-only distribution.

    Symmetric counterpart of compute_zone_layout for the column axis.
    No min_width_px contract exists in frame_contracts.yaml (verified
    empty as of IMP-09), so column allocation is purely content_weight
    score based.
    """
    n = len(zones_data)
    if n == 0:
        return {"widths_px": [], "width_ratios": [], "zones": []}

    available = total_width - gap * (n - 1)
    weights = [z["content_weight"]["score"] for z in zones_data]
    total_w = sum(weights)

    if total_w <= 0:
        # Zero-weight guard (override-empty zone where score=0).
        widths_px = [available // n] * n
        widths_px[-1] += available - sum(widths_px)
        weight_shares = [round(1.0 / n, 3)] * n
    else:
        # Task 11d: keep every occupied grid track renderable. A 2-D layout
        # can have a low/zero-score sibling column that still owns a zone; if
        # pure proportional allocation gives it 0px, the frame overflows
        # horizontally and looks like an overlay. Reserve a conservative floor
        # before distributing the remaining width by content weight.
        min_width_px = min(260, max(1, available // n))
        reserved = min_width_px * n
        if reserved < available:
            distributable = available - reserved
            widths_px = [
                min_width_px + int(round(distributable * (w / total_w)))
                for w in weights
            ]
        else:
            widths_px = [available // n] * n
        diff = available - sum(widths_px)
        if diff != 0:
            widths_px[-1] += diff
        weight_shares = [round(w / total_w, 3) for w in weights]

    width_ratios = [round(w / total_width, 3) for w in widths_px]

    return {
        "computation": "content_weight_distribution_cols",
        "slide_body_width": total_width,
        "gap": gap,
        "available_after_gap": available,
        "content_weights": [
            {"position": z["position"],
             "template_id": z["template_id"],
             "score": w}
            for z, w in zip(zones_data, weights)
        ],
        "weight_shares": weight_shares,
        "widths_px": widths_px,
        "width_ratios": width_ratios,
    }


def _aggregate_zone_signals_per_track(
    preset: dict,
    zones_data: list[dict],
) -> tuple[list[dict], list[dict]]:
    """Build per-row + per-col virtual zones for 2-D dynamic dispatch.

    Each virtual zone aggregates content_weight.score (max) and
    min_height_px (max) across single-span zones on that track
    (occupied_rows == {r} for rows, occupied_cols == {c} for cols).
    Falls back to all-span zones (touching every track on the axis)
    when a track has no single-span zone.
    """
    rows_grid, _ = _parse_css_areas(preset["css_areas"])
    R = len(rows_grid)
    C = len(rows_grid[0])

    occupancy: list[tuple[dict, set[int], set[int]]] = []
    for z in zones_data:
        pos = z["position"]
        occ_rows = {r for r, row in enumerate(rows_grid) if pos in row}
        occ_cols = {
            c for row in rows_grid for c, tok in enumerate(row) if tok == pos
        }
        occupancy.append((z, occ_rows, occ_cols))

    def _track_virtual(idx: int, axis: str) -> dict:
        if axis == "row":
            single = [z for z, rr, _cc in occupancy if rr == {idx}]
            allspan = [z for z, rr, _cc in occupancy if rr == set(range(R))]
        else:
            single = [z for z, _rr, cc in occupancy if cc == {idx}]
            allspan = [z for z, _rr, cc in occupancy if cc == set(range(C))]
        candidates = single or allspan
        return {
            "position": f"_virtual_{axis}_{idx}",
            "template_id": f"_virtual_{axis}_{idx}",
            "content_weight": {
                "score": max(c["content_weight"]["score"] for c in candidates)
            },
            "min_height_px": max(
                c.get("min_height_px", DEFAULT_ZONE_MIN_HEIGHT_PX)
                for c in candidates
            ),
        }

    row_virtuals = [_track_virtual(r, "row") for r in range(R)]
    col_virtuals = [_track_virtual(c, "col") for c in range(C)]
    return row_virtuals, col_virtuals


def _compute_per_zone_geometry(
    layout_css: dict,
    debug_zones: list[dict],
    gap: int = GRID_GAP,
) -> list[dict]:
    """Aggregate grid-track sizes into per-zone dimensions for ALL layouts.

    Parses layout_css["areas"] (catalog css_areas) into an R x C cell
    grid, then for each zone in debug_zones sums the heights_px of its
    occupied rows and widths_px of its occupied columns, including the
    inter-track gap absorbed by a spanning zone.

    Length contract: layout_css["heights_px"] MUST have length R, and
    layout_css["widths_px"] MUST have length C. Mismatch raises
    ValueError because that indicates a broken build path, not a
    runtime input issue.
    """
    rows_grid, _ = _parse_css_areas(layout_css["areas"])
    R = len(rows_grid)
    C = len(rows_grid[0])
    heights_px = layout_css.get("heights_px") or []
    widths_px = layout_css.get("widths_px") or []

    if len(heights_px) != R:
        raise ValueError(
            f"_compute_per_zone_geometry: heights_px length "
            f"{len(heights_px)} != grid rows R={R} "
            f"(css_areas={layout_css.get('areas')!r})"
        )
    if len(widths_px) != C:
        raise ValueError(
            f"_compute_per_zone_geometry: widths_px length "
            f"{len(widths_px)} != grid cols C={C} "
            f"(css_areas={layout_css.get('areas')!r})"
        )

    per_zone: list[dict] = []
    for dz in debug_zones:
        pos = dz["position"]
        occupied_rows = sorted(
            {r for r, row in enumerate(rows_grid) if pos in row}
        )
        occupied_cols = sorted(
            {c for r, row in enumerate(rows_grid)
             for c, tok in enumerate(row) if tok == pos}
        )
        if not occupied_rows or not occupied_cols:
            raise ValueError(
                f"_compute_per_zone_geometry: zone position {pos!r} "
                f"not present in css_areas {rows_grid}"
            )
        zh = (
            sum(heights_px[r] for r in occupied_rows)
            + gap * (len(occupied_rows) - 1)
        )
        zw = (
            sum(widths_px[c] for c in occupied_cols)
            + gap * (len(occupied_cols) - 1)
        )
        per_zone.append({
            "position": pos,
            "zone_height_px": zh,
            "zone_width_px": zw,
            "zone_height_ratio": round(zh / SLIDE_BODY_HEIGHT, 3),
            "zone_width_ratio": round(zw / SLIDE_BODY_WIDTH, 3),
        })
    return per_zone


def _build_fr_default(preset: dict) -> dict:
    """fr-default sink — populate widths_px / heights_px from catalog fr ratios.

    Replaces the legacy empty-array sink so that downstream consumers
    (Step 7/8 trace, _compute_per_zone_geometry) always receive
    length-locked arrays matching the catalog grid dimensions.
    """
    rows_grid, _ = _parse_css_areas(preset["css_areas"])
    R = len(rows_grid)
    C = len(rows_grid[0])

    avail_h = SLIDE_BODY_HEIGHT - GRID_GAP * (R - 1)
    avail_w = SLIDE_BODY_WIDTH - GRID_GAP * (C - 1)

    heights_px = _parse_fr_string(preset["css_rows"], avail_h)
    widths_px = _parse_fr_string(preset["css_cols"], avail_w)
    return {
        "areas": preset["css_areas"],
        "cols": preset["css_cols"],
        "rows": preset["css_rows"],
        "heights_px": heights_px,
        "widths_px": widths_px,
        "ratios": [round(h / SLIDE_BODY_HEIGHT, 3) for h in heights_px],
        "width_ratios": [round(w / SLIDE_BODY_WIDTH, 3) for w in widths_px],
        "computation": "fr_default_from_preset",
        "dynamic_rows": False,
        "dynamic_cols": False,
        "raw_zone_layout": None,
    }


def _build_rows_dynamic(preset: dict, zones_data: list[dict],
                        gap: int = GRID_GAP) -> dict:
    """horizontal-2 path — dynamic row heights, static fr column widths.

    Preserves the legacy compute_zone_layout output (heights_px / ratios /
    computation / raw_zone_layout) byte-for-byte; only adds the new
    col-axis keys (widths_px from css_cols fr, width_ratios, dynamic_cols=False).
    """
    rows_grid, _ = _parse_css_areas(preset["css_areas"])
    C = len(rows_grid[0])
    avail_w = SLIDE_BODY_WIDTH - gap * (C - 1)
    widths_px = _parse_fr_string(preset["css_cols"], avail_w)

    zl = compute_zone_layout(zones_data, gap=gap)
    rows_str = " ".join(f"{h}px" for h in zl["heights_px"])
    return {
        "areas": preset["css_areas"],
        "cols": preset["css_cols"],
        "rows": rows_str,
        "heights_px": zl["heights_px"],
        "widths_px": widths_px,
        "ratios": zl["ratios"],
        "width_ratios": [round(w / SLIDE_BODY_WIDTH, 3) for w in widths_px],
        "computation": zl["computation"],
        "dynamic_rows": True,
        "dynamic_cols": False,
        "raw_zone_layout": zl,
    }


def _build_grid_dynamic_2d(preset: dict, zones_data: list[dict],
                           gap: int = GRID_GAP) -> dict:
    """2-D dynamic path — dynamic row heights + dynamic column widths.

    IMP-09 PR 2 (B-4) handler for the five preset families whose topology
    is neither pure 'rows' nor pure 'cols':
      - T              (top-1-bottom-2)
      - inverted-T     (top-2-bottom-1)
      - side-T-left    (left-1-right-2)
      - side-T-right   (left-2-right-1)
      - 2x2            (grid-2x2)

    Strategy:
      1) _aggregate_zone_signals_per_track builds R per-row + C per-col
         virtual zones (max content_weight.score + max min_height_px of
         single-span zones, falling back to all-span zones).
      2) Row virtuals → compute_zone_layout → heights_px (R).
      3) Col virtuals → compute_zone_layout_cols → widths_px (C).
      4) Assemble layout_css dict with computation='2d_dynamic_aggregated'
         and dynamic_rows=True, dynamic_cols=True.

    raw_zone_layout carries both solver outputs + the virtual zone lists
    so step08 trace can explain the per-track aggregation.
    """
    row_virtuals, col_virtuals = _aggregate_zone_signals_per_track(
        preset, zones_data
    )
    zl_row = compute_zone_layout(row_virtuals, gap=gap)
    zl_col = compute_zone_layout_cols(col_virtuals, gap=gap)

    heights_px = zl_row["heights_px"]
    widths_px = zl_col["widths_px"]
    rows_str = " ".join(f"{h}px" for h in heights_px)
    cols_str = " ".join(f"{w}px" for w in widths_px)

    return {
        "areas": preset["css_areas"],
        "cols": cols_str,
        "rows": rows_str,
        "heights_px": heights_px,
        "widths_px": widths_px,
        "ratios": [round(h / SLIDE_BODY_HEIGHT, 3) for h in heights_px],
        "width_ratios": [round(w / SLIDE_BODY_WIDTH, 3) for w in widths_px],
        "computation": "2d_dynamic_aggregated",
        "dynamic_rows": True,
        "dynamic_cols": True,
        "raw_zone_layout": {
            "row_layout": zl_row,
            "col_layout": zl_col,
            "row_virtuals": row_virtuals,
            "col_virtuals": col_virtuals,
        },
    }


def _build_cols_dynamic(preset: dict, zones_data: list[dict],
                        gap: int = GRID_GAP) -> dict:
    """vertical-2 path — dynamic column widths, static fr row heights.

    Mirror of _build_rows_dynamic. Returns a pixel grid-template-columns
    string. PR 2 promotes vertical-2 override to dynamic_rows=True; in
    PR 1 dynamic_rows stays False (legacy).
    """
    rows_grid, _ = _parse_css_areas(preset["css_areas"])
    R = len(rows_grid)
    avail_h = SLIDE_BODY_HEIGHT - gap * (R - 1)
    heights_px = _parse_fr_string(preset["css_rows"], avail_h)

    zl = compute_zone_layout_cols(zones_data, gap=gap)
    cols_str = " ".join(f"{w}px" for w in zl["widths_px"])
    return {
        "areas": preset["css_areas"],
        "cols": cols_str,
        "rows": preset["css_rows"],
        "heights_px": heights_px,
        "widths_px": zl["widths_px"],
        "ratios": [round(h / SLIDE_BODY_HEIGHT, 3) for h in heights_px],
        "width_ratios": zl["width_ratios"],
        "computation": zl["computation"],
        "dynamic_rows": False,
        "dynamic_cols": True,
        "raw_zone_layout": zl,
    }


def _override_to_grid_tracks(
    preset: dict,
    zones_data: list[dict],
    override_zone_geometries: dict[str, dict],
    gap: int = GRID_GAP,
) -> dict:
    """2-D override path — derive heights_px (R) + widths_px (C) from
    user-supplied zone_id -> {x, y, w, h} (0~1 within slide-body).

    IMP-09 PR 2 (B-4) override handler for the five preset families
    whose topology is neither pure 'rows' nor pure 'cols':
      - T              (top-1-bottom-2)
      - inverted-T     (top-2-bottom-1)
      - side-T-left    (left-1-right-2)
      - side-T-right   (left-2-right-1)
      - 2x2            (grid-2x2)

    Strategy:
      1) Parse css_areas into R x C grid.
      2) For each row r: aggregate h via max over single-row zones
         (occupied_rows == {r}); fallback to all-span zones; else 0.0.
      3) For each col c: same with w.
      4) Normalize per-axis (divide by total) and multiply by avail_*,
         absorbing rounding diff into the last element.
      5) If total_h or total_w == 0 (degenerate / empty override),
         fall back to _build_grid_dynamic_2d default path.
    """
    rows_grid, _ = _parse_css_areas(preset["css_areas"])
    R = len(rows_grid)
    C = len(rows_grid[0])

    # Hot-fix (2026-05-22): partial override 버그 fix — override 없는 track 은
    # default 비율로 fallback. 이전엔 0 반환 → normalize 후 다른 track 이 모든 공간 흡수.
    _default_result = _build_grid_dynamic_2d(preset, zones_data, gap=gap)
    _default_widths = _default_result.get("widths_px", []) or []
    _default_heights = _default_result.get("heights_px", []) or []
    _sum_w = sum(_default_widths) if _default_widths else 1.0
    _sum_h = sum(_default_heights) if _default_heights else 1.0

    occupancy: list[tuple[dict, set[int], set[int]]] = []
    for z in zones_data:
        pos = z["position"]
        occ_rows = {r for r, row in enumerate(rows_grid) if pos in row}
        occ_cols = {
            c for row in rows_grid for c, tok in enumerate(row) if tok == pos
        }
        occupancy.append((z, occ_rows, occ_cols))

    def _track_value(idx: int, axis: str) -> float:
        if axis == "row":
            single = [z for z, rr, _cc in occupancy if rr == {idx}]
            allspan = [z for z, rr, _cc in occupancy if rr == set(range(R))]
            key = "h"
            _fallback = (_default_heights[idx] / _sum_h) if idx < len(_default_heights) and _sum_h else (1.0 / R)
        else:
            single = [z for z, _rr, cc in occupancy if cc == {idx}]
            allspan = [z for z, _rr, cc in occupancy if cc == set(range(C))]
            key = "w"
            _fallback = (_default_widths[idx] / _sum_w) if idx < len(_default_widths) and _sum_w else (1.0 / C)
        candidates = single or allspan
        vals = [
            float(override_zone_geometries[z["position"]][key])
            for z in candidates
            if z["position"] in override_zone_geometries
        ]
        return max(vals) if vals else _fallback

    row_values = [_track_value(r, "row") for r in range(R)]
    col_values = [_track_value(c, "col") for c in range(C)]

    total_h = sum(row_values)
    total_w = sum(col_values)
    if total_h == 0 or total_w == 0:
        return _build_grid_dynamic_2d(preset, zones_data, gap=gap)

    row_ratios = [v / total_h for v in row_values]
    col_ratios = [v / total_w for v in col_values]

    avail_h = SLIDE_BODY_HEIGHT - gap * (R - 1)
    avail_w = SLIDE_BODY_WIDTH - gap * (C - 1)
    heights_px = [int(round(r * avail_h)) for r in row_ratios]
    widths_px = [int(round(r * avail_w)) for r in col_ratios]
    diff_h = avail_h - sum(heights_px)
    if diff_h != 0 and heights_px:
        heights_px[-1] += diff_h
    diff_w = avail_w - sum(widths_px)
    if diff_w != 0 and widths_px:
        widths_px[-1] += diff_w

    rows_str = " ".join(f"{h}px" for h in heights_px)
    cols_str = " ".join(f"{w}px" for w in widths_px)
    return {
        "areas": preset["css_areas"],
        "cols": cols_str,
        "rows": rows_str,
        "heights_px": heights_px,
        "widths_px": widths_px,
        "ratios": [round(rr, 3) for rr in row_ratios],
        "width_ratios": [round(rr, 3) for rr in col_ratios],
        "computation": "user_override_geometry",
        "dynamic_rows": True,
        "dynamic_cols": True,
        "raw_zone_layout": {
            "override_applied": True,
            "source": override_zone_geometries,
        },
    }


# Layout preset → zone position 순서 = LAYOUT_PRESETS[preset]["positions"] 직접 사용.
# 이전 ZONE_POSITIONS_BY_PRESET (type-b 등 legacy 명) 는 dead code 로 제거 (2026-04-29).


def build_layout_css(layout_preset: str, zones_data: list[dict],
                     gap: int = GRID_GAP,
                     override_zone_geometries: Optional[dict[str, dict]] = None) -> dict:
    """Composition v0 layout preset → CSS grid 문자열.

    IMP-09 PR 1 contract — every layout_css return path carries
    matching-length heights_px (= grid rows R) and widths_px (= grid cols C),
    plus ratios / width_ratios / dynamic_rows / dynamic_cols. The
    horizontal-2 grid CSS strings (areas/cols/rows) remain byte-identical
    to the legacy path.

    Dynamic dispatch:
      - topology="rows" -> _build_rows_dynamic (horizontal-2: row heights)
      - topology="cols" -> _build_cols_dynamic (vertical-2: col widths)
      - other topologies (single / T / inverted-T / side-T / 2x2) fall
        through to _build_fr_default in PR 1; PR 2 enables the 2-D
        dispatcher.

    Step D-ext (사용자 lock 2026-05-08) — override_zone_geometries (zone_id ->
    {x,y,w,h} slide-body 내부 0~1) 가 들어오면 그 비율로 layout_css 강제.
    PR 1 lock: horizontal-2 / vertical-2 만 처리 (legacy inline preserve).
    다른 preset 은 warn-and-fallthrough (PR 2 가 unified _override_to_grid_tracks
    로 promote).
    """
    preset = LAYOUT_PRESETS[layout_preset]
    positions = preset["positions"]
    topology = preset.get("topology")

    # ── Step D-ext : user override 처리 ──
    if override_zone_geometries:
        if layout_preset == "horizontal-2":
            # IMP-44 u1 — unknown-key guard: drop foreign-preset keys
            # (예: vertical-2 keys {left,right} sent to horizontal-2), emit
            # structured warning, keep matching keys. All-unknown → fall
            # through to default dynamic dispatch (no false override_applied).
            unknown_keys = sorted(
                k for k in override_zone_geometries if k not in positions
            )
            if unknown_keys:
                print(
                    f"  [override-warning] layout_preset={layout_preset} "
                    f"expected_positions={list(positions)} unknown_keys={unknown_keys} "
                    f"(dropped foreign-preset keys; default split for non-overridden).",
                    file=sys.stderr,
                )
            filtered_overrides = {
                k: v for k, v in override_zone_geometries.items() if k in positions
            }
            if filtered_overrides:
                # heights_px override — zone 의 h 비율로 SLIDE_BODY_HEIGHT 분배.
                # Hot-fix (2026-05-22): partial override = 나머지 공간을 비-override zone 들에
                # 균등 분배 (drag boundary intent). 이전엔 0.0 fallback → 100/0 깨짐.
                overridden_h = sum(
                    float(filtered_overrides[p]["h"])
                    for p in positions if p in filtered_overrides
                )
                non_overridden = [p for p in positions if p not in filtered_overrides]
                per_non = max(0.0, 1.0 - overridden_h) / max(len(non_overridden), 1)
                ratios = []
                for pos in positions:
                    geom = filtered_overrides.get(pos)
                    ratios.append(float(geom["h"]) if geom else per_non)
                total = sum(ratios)
                if total > 0:
                    heights_px = [int(round(r / total * SLIDE_BODY_HEIGHT)) for r in ratios]
                    rows = " ".join(f"{h}px" for h in heights_px)
                    return {
                        "areas": preset["css_areas"],
                        "cols": preset["css_cols"],
                        "rows": rows,
                        "heights_px": heights_px,
                        "widths_px": [SLIDE_BODY_WIDTH],
                        "ratios": [round(r / total, 3) for r in ratios],
                        "width_ratios": [1.0],
                        "computation": "user_override_geometry",
                        "dynamic_rows": True,
                        "dynamic_cols": False,
                        "raw_zone_layout": {"override_applied": True, "source": filtered_overrides},
                    }
        elif layout_preset == "vertical-2":
            # IMP-44 u1 — unknown-key guard: drop foreign-preset keys
            # (예: horizontal-2 keys {top,bottom} sent to vertical-2), emit
            # structured warning, keep matching keys. All-unknown → fall
            # through to default dynamic dispatch (no false override_applied).
            unknown_keys = sorted(
                k for k in override_zone_geometries if k not in positions
            )
            if unknown_keys:
                print(
                    f"  [override-warning] layout_preset={layout_preset} "
                    f"expected_positions={list(positions)} unknown_keys={unknown_keys} "
                    f"(dropped foreign-preset keys; default split for non-overridden).",
                    file=sys.stderr,
                )
            filtered_overrides = {
                k: v for k, v in override_zone_geometries.items() if k in positions
            }
            if filtered_overrides:
                # cols override — zone 의 w 비율로 fr 분배 (legacy: fr-string cols).
                # PR 1 keeps fr-string cols for legacy preserve; widths_px is
                # populated in pixels for _compute_per_zone_geometry length contract.
                # Hot-fix (2026-05-22): partial override = 나머지 공간을 비-override zone 들에
                # 균등 분배 (drag boundary intent). 이전엔 0.0 fallback → 100/0 깨짐.
                overridden_w = sum(
                    float(filtered_overrides[p]["w"])
                    for p in positions if p in filtered_overrides
                )
                non_overridden = [p for p in positions if p not in filtered_overrides]
                per_non = max(0.0, 1.0 - overridden_w) / max(len(non_overridden), 1)
                ratios = []
                for pos in positions:
                    geom = filtered_overrides.get(pos)
                    ratios.append(float(geom["w"]) if geom else per_non)
                total = sum(ratios)
                if total > 0:
                    cols = " ".join(f"{round(r / total * 100, 2)}fr" for r in ratios)
                    normalized = [r / total for r in ratios]
                    widths_px = [
                        int(round(rr * (SLIDE_BODY_WIDTH - gap * (len(ratios) - 1))))
                        for rr in normalized
                    ]
                    diff = (SLIDE_BODY_WIDTH - gap * (len(ratios) - 1)) - sum(widths_px)
                    if diff != 0 and widths_px:
                        widths_px[-1] += diff
                    return {
                        "areas": preset["css_areas"],
                        "cols": cols,
                        "rows": preset["css_rows"],
                        "heights_px": [SLIDE_BODY_HEIGHT],
                        "widths_px": widths_px,
                        "ratios": [1.0],
                        "width_ratios": [round(rr, 3) for rr in normalized],
                        "computation": "user_override_geometry",
                        "dynamic_rows": False,
                        "dynamic_cols": True,
                        "raw_zone_layout": {"override_applied": True, "source": filtered_overrides},
                    }
        elif topology in ("T", "inverted-T", "side-T-left", "side-T-right", "2x2"):
            # IMP-09 PR 2 — 2-D override path (T / inverted-T / side-T / 2x2).
            # Degenerate inputs (total_h == 0 or total_w == 0) fall back to
            # _build_grid_dynamic_2d inside the helper.
            #
            # IMP-44 u2 — unknown-key guard mirrors u1 (1-D): drop foreign-
            # preset keys (예: vertical-2 keys {left,right} sent to T-preset),
            # emit structured warning, keep matching keys. All-unknown → fall
            # through to _build_grid_dynamic_2d default (no false override_applied).
            unknown_keys = sorted(
                k for k in override_zone_geometries if k not in positions
            )
            if unknown_keys:
                print(
                    f"  [override-warning] layout_preset={layout_preset} "
                    f"expected_positions={list(positions)} unknown_keys={unknown_keys} "
                    f"(dropped foreign-preset keys; default split for non-overridden).",
                    file=sys.stderr,
                )
            filtered_overrides = {
                k: v for k, v in override_zone_geometries.items() if k in positions
            }
            if filtered_overrides:
                return _override_to_grid_tracks(
                    preset, zones_data, filtered_overrides, gap=gap
                )
            return _build_grid_dynamic_2d(preset, zones_data, gap=gap)
        else:
            # warn-and-fallthrough preserved for remaining presets (single).
            # PR 3 territory.
            print(
                f"  [override-warning] zone-geometry override 는 layout '{layout_preset}' 미지원 "
                f"(현재 horizontal-2 / vertical-2 / 2-D presets 만). default layout_css 사용.",
                file=sys.stderr,
            )

    # ── Dynamic branch — topology dispatch ──
    if topology == "rows":
        return _build_rows_dynamic(preset, zones_data, gap)
    if topology == "cols":
        return _build_cols_dynamic(preset, zones_data, gap)
    if topology in ("T", "inverted-T", "side-T-left", "side-T-right", "2x2"):
        return _build_grid_dynamic_2d(preset, zones_data, gap)
    # PR 3 will dispatch single here.
    return _build_fr_default(preset)


# ─── Abort ──────────────────────────────────────────────────────

def abort_with_error(run_dir: Path, section: MdxSection,
                     match: Optional[V4Match], stage: str, reason: str):
    error_data = {
        "section": {"id": section.section_id, "title": section.title},
        "frame": {
            "id": match.frame_id if match else None,
            "number": match.frame_number if match else None,
            "template_id": match.template_id if match else None,
        },
        "v4_label": match.label if match else None,
        "phase_z_status": to_phase_z_status(match) if match else None,
        "confidence": match.confidence if match else None,
        "stage": stage,
        "reason": reason,
    }
    run_dir.mkdir(parents=True, exist_ok=True)
    err_path = run_dir / "error.json"
    err_path.write_text(json.dumps(error_data, ensure_ascii=False, indent=2), encoding="utf-8")
    print(f"\n[Phase Z-2 MVP-1.5b] ABORT @ {stage}", file=sys.stderr)
    print(f"  section : {section.section_id} — {section.title}", file=sys.stderr)
    if match:
        print(f"  frame   : {match.frame_id} ({match.template_id})", file=sys.stderr)
        print(f"  status  : V4 label '{match.label}' → Phase Z '{to_phase_z_status(match)}'", file=sys.stderr)
    print(f"  reason  : {reason}", file=sys.stderr)
    print(f"  error   : {err_path}", file=sys.stderr)
    sys.exit(1)


# ─── IMP-06 Step 6 zone-section assignment override (backend/CLI/composition only) ──


def _build_position_assignment_plan(
    units: list,
    positions: list[str],
    override_section_assignments: Optional[dict[str, list[str]]],
    sections_by_id: dict[str, "MdxSection"],
    override_frames: Optional[dict[str, str]] = None,
    v4: Optional[dict] = None,
) -> tuple[list[dict], dict]:
    """IMP-06 (#6 / Codex #6,#7 15-axis lock) — section-to-position assignment plan.

    Pure helper invoked AFTER ``plan_composition()`` returns ``units`` and
    AFTER ``override_layout`` has been applied so ``positions`` is the final
    layout-preset position vocabulary.

    Locked behavior :
      - explicit override wins per position
      - no section id appears in more than one final rendered position
      - overlapping auto units are skipped WHOLE (no split, no cascade, no replan)
      - template_id resolution ladder :
          (1) ``override_frames`` exact ``unit_id``  (catalog validation downstream)
          (2) exact existing auto unit reuse (same ``source_section_ids``)
          (3) single-section override -> ``lookup_v4_match_with_fallback`` with
              ``raw_content=section.raw_content`` (direct executable only)
          (4) multi-section ad-hoc override (no exact auto + no override-frame)
              -> skipped_reason='ad_hoc_merged_no_template'
      - additive trace : ``previous_source_section_ids`` (position-level history),
        ``skipped_collided_auto_units`` (collision-level), ``uncovered_section_ids``
        (post-override coverage gap), ``v4_selector_trace`` (selector failure embed),
        ``skipped_reason`` for failed assignments

    Returns ``(plan, summary)`` where :
      - ``plan``       : list[dict] keyed by position with the per-position record
      - ``summary``    : dict with applied/skipped counts + uncovered ids

    NOTE : the helper does NOT mutate ``units`` and does NOT raise on validation
    failures; caller is responsible for fail-fast validation of unknown zone ids
    or unknown section ids before calling.
    """
    overrides = override_section_assignments or {}
    override_frames = override_frames or {}

    # Section ids reserved by any explicit override.
    overridden_section_ids: set[str] = set()
    for _zid, sids in overrides.items():
        overridden_section_ids.update(sids)

    # Build position -> auto unit baseline. Auto plan uses sequential mapping of
    # ``units`` over ``positions`` (the same order Step 6 of the pipeline uses).
    auto_by_position: dict[str, object] = {}
    for i, pos in enumerate(positions):
        auto_by_position[pos] = units[i] if i < len(units) else None

    # Reverse lookup : section_id -> auto unit (for collision detection).
    auto_unit_by_section: dict[str, object] = {}
    for u in units:
        for sid in u.source_section_ids:
            auto_unit_by_section[sid] = u

    # Track auto units that get whole-skipped because of collision.
    skipped_collided_unit_ids: set[str] = set()

    plan: list[dict] = []

    def _unit_id(sids: list[str]) -> str:
        return "+".join(sids)

    def _resolve_template_for_override(zone_id: str, sids: list[str]) -> tuple[
        Optional[str], Optional[str], Optional[dict]
    ]:
        """template_id resolution ladder. Returns (template_id, skipped_reason, v4_selector_trace)."""
        unit_id = _unit_id(sids)
        # (1) explicit --override-frame for exact unit_id
        if unit_id in override_frames:
            return override_frames[unit_id], None, None
        # (2) exact existing auto unit reuse
        for u in units:
            if list(u.source_section_ids) == list(sids):
                return getattr(u, "frame_template_id", None) or getattr(u, "template_id", None), None, None
        # (3) single-section selector
        if len(sids) == 1:
            sid = sids[0]
            section = sections_by_id.get(sid)
            if v4 is None or section is None:
                return None, "no_v4_section", None
            raw_content = getattr(section, "raw_content", None)
            # IMP-08 B-3 : forward sub-section V4 aliases (decimal heading_number)
            # when canonical ordinal id misses; safe for top-level sids (empty list).
            alias_keys = list(getattr(section, "v4_alias_keys", []) or [])
            match, trace = lookup_v4_match_with_fallback(
                v4, sid, raw_content=raw_content, alias_keys=alias_keys
            )
            if match is None:
                return None, "no_direct_render_template", trace
            return match.template_id, None, trace
        # (4) ad-hoc multi-section override without exact auto + without override-frame
        return None, "ad_hoc_merged_no_template", None

    # Iterate positions deterministically. Explicit overrides win.
    for pos in positions:
        if pos in overrides:
            sids = overrides[pos]
            auto_unit = auto_by_position.get(pos)
            previous_source_section_ids = (
                list(auto_unit.source_section_ids) if auto_unit is not None else []
            )
            # Sections that the previous auto unit at this position contained but
            # the explicit override did not take = uncovered post-override.
            sids_set = set(sids)
            uncovered_from_previous = [
                sid for sid in previous_source_section_ids if sid not in sids_set
            ]
            template_id, skipped_reason, selector_trace = _resolve_template_for_override(pos, sids)
            # IMP-06 Stage 4 (Codex #9 R1 + Claude #9 Catch L + Codex #10) — replaced_auto_unit
            # populated only when the same position previously had an auto unit and that
            # auto unit was different from the requested override. Documents "this auto
            # unit was removed from this position to apply the override" as a distinct
            # audit fact (vs skipped_collided_auto_units which is cross-position skip).
            replaced_auto_unit = None
            if auto_unit is not None and list(auto_unit.source_section_ids) != list(sids):
                replaced_auto_unit = {
                    "unit_id": _unit_id(list(auto_unit.source_section_ids)),
                    "source_section_ids": list(auto_unit.source_section_ids),
                    "reason": "same_position_override_replacement",
                }
            plan.append({
                "position": pos,
                "assignment_source": "cli_override",
                "unit_id": _unit_id(sids),
                "source_section_ids": list(sids),
                "template_id": template_id,
                "previous_source_section_ids": previous_source_section_ids,
                "section_assignment_override": {
                    "override_applied": True,
                    "override_source": "cli",
                    "zone_id": pos,
                    "requested_section_ids": list(sids),
                },
                "replaced_auto_unit": replaced_auto_unit,
                "skipped_collided_auto_units": [],
                "uncovered_section_ids": uncovered_from_previous,
                "skipped_reason": skipped_reason,
                "v4_selector_trace": selector_trace,
            })
        else:
            # Auto-retain unless overlap with overridden sections.
            auto_unit = auto_by_position.get(pos)
            if auto_unit is None:
                plan.append({
                    "position": pos,
                    "assignment_source": "empty",
                    "unit_id": None,
                    "source_section_ids": [],
                    "template_id": None,
                    "previous_source_section_ids": [],
                    "section_assignment_override": None,
                    "replaced_auto_unit": None,
                    "skipped_collided_auto_units": [],
                    "uncovered_section_ids": [],
                    "skipped_reason": "no_auto_unit_available",
                    "v4_selector_trace": None,
                })
                continue
            overlap = [sid for sid in auto_unit.source_section_ids if sid in overridden_section_ids]
            if overlap:
                # Whole-skip the auto unit. Sections in the auto unit that were NOT taken
                # by an override become uncovered.
                unit_id_str = _unit_id(list(auto_unit.source_section_ids))
                skipped_collided_unit_ids.add(unit_id_str)
                uncovered = [
                    sid for sid in auto_unit.source_section_ids
                    if sid not in overridden_section_ids
                ]
                plan.append({
                    "position": pos,
                    "assignment_source": "empty",
                    "unit_id": None,
                    "source_section_ids": [],
                    "template_id": None,
                    "previous_source_section_ids": list(auto_unit.source_section_ids),
                    "section_assignment_override": None,
                    "replaced_auto_unit": None,
                    "skipped_collided_auto_units": [{
                        "unit_id": unit_id_str,
                        "source_section_ids": list(auto_unit.source_section_ids),
                        "reason": "override_collision",
                    }],
                    "uncovered_section_ids": uncovered,
                    "skipped_reason": "override_collision",
                    "v4_selector_trace": None,
                })
            else:
                plan.append({
                    "position": pos,
                    "assignment_source": "auto",
                    "unit_id": _unit_id(list(auto_unit.source_section_ids)),
                    "source_section_ids": list(auto_unit.source_section_ids),
                    "template_id": (
                        getattr(auto_unit, "frame_template_id", None)
                        or getattr(auto_unit, "template_id", None)
                    ),
                    "previous_source_section_ids": list(auto_unit.source_section_ids),
                    "section_assignment_override": None,
                    "replaced_auto_unit": None,
                    "skipped_collided_auto_units": [],
                    "uncovered_section_ids": [],
                    "skipped_reason": None,
                    "v4_selector_trace": None,
                })

    # Summary aggregates.
    applied = [p for p in plan if p["assignment_source"] == "cli_override"]
    skipped_assignments = [p for p in plan if p["skipped_reason"] is not None]
    all_uncovered: list[str] = []
    for p in plan:
        all_uncovered.extend(p.get("uncovered_section_ids", []))
    summary = {
        "section_assignment_overrides_applied": [
            {"position": p["position"], "source_section_ids": p["source_section_ids"]}
            for p in applied
        ],
        "section_assignment_overrides_skipped": [
            {"position": p["position"], "reason": p["skipped_reason"]}
            for p in skipped_assignments
        ],
        "applied_count": len(applied),
        "skipped_count": len(skipped_assignments),
        "uncovered_section_ids": all_uncovered,
        "skipped_collided_auto_unit_ids": sorted(skipped_collided_unit_ids),
    }
    return plan, summary


def _build_section_id_aliases(sections: list[MdxSection]) -> dict[str, str]:
    """Build compatibility aliases for newly materialized structural units.

    T22 (#98): pre-intro units use stable ids such as ``01-intro``. Older
    persisted overrides may have pointed at the next numeric placeholder such
    as ``01-3`` when only ``01-1`` and ``01-2`` existed. Keep that migration
    generic: for each ``<mdx>-intro`` unit, map the next unused numeric id to
    the intro id when it is not already a real section.
    """

    section_ids = {s.section_id for s in sections}
    aliases: dict[str, str] = {}
    by_mdx: dict[str, list[MdxSection]] = {}
    for section in sections:
        mdx_id = section.section_id.split("-", 1)[0]
        by_mdx.setdefault(mdx_id, []).append(section)

    for mdx_id, group in by_mdx.items():
        intro = next((s for s in group if s.section_id == f"{mdx_id}-intro"), None)
        if intro is None:
            continue
        numeric_nums = [
            int(s.section_num)
            for s in group
            if isinstance(s.section_num, int) and int(s.section_num) > 0
        ]
        next_numeric_id = f"{mdx_id}-{(max(numeric_nums) if numeric_nums else 0) + 1}"
        if next_numeric_id not in section_ids:
            aliases[next_numeric_id] = intro.section_id
        zero_alias = f"{mdx_id}-0"
        if zero_alias not in section_ids:
            aliases[zero_alias] = intro.section_id
    return aliases


def _apply_section_id_aliases_to_overrides(
    override_section_assignments: Optional[dict[str, list[str]]],
    override_frames: Optional[dict[str, str]],
    aliases: dict[str, str],
) -> tuple[
    Optional[dict[str, list[str]]],
    Optional[dict[str, str]],
    dict,
]:
    """Apply section-id aliases to persisted/CLI override payloads."""

    if not aliases:
        return override_section_assignments, override_frames, {
            "applied": False,
            "section_id_aliases": {},
            "zone_section_rewrites": [],
            "frame_key_rewrites": [],
        }

    zone_rewrites: list[dict] = []
    frame_rewrites: list[dict] = []

    rewritten_assignments = None
    if override_section_assignments is not None:
        rewritten_assignments = {}
        for zone_id, sids in override_section_assignments.items():
            rewritten_sids: list[str] = []
            for sid in sids:
                new_sid = aliases.get(sid, sid)
                rewritten_sids.append(new_sid)
                if new_sid != sid:
                    zone_rewrites.append({
                        "zone_id": zone_id,
                        "from": sid,
                        "to": new_sid,
                    })
            rewritten_assignments[zone_id] = rewritten_sids

    rewritten_frames = None
    if override_frames is not None:
        rewritten_frames = dict(override_frames)
        for key, template_id in list(override_frames.items()):
            new_key = aliases.get(key, key)
            if new_key == key:
                continue
            if new_key not in rewritten_frames:
                rewritten_frames[new_key] = template_id
            frame_rewrites.append({
                "from": key,
                "to": new_key,
                "template_id": template_id,
                "target_preexisting": new_key in override_frames,
            })

    return rewritten_assignments, rewritten_frames, {
        "applied": bool(zone_rewrites or frame_rewrites),
        "section_id_aliases": dict(aliases),
        "zone_section_rewrites": zone_rewrites,
        "frame_key_rewrites": frame_rewrites,
    }


def _infer_layout_from_zone_section_keys(
    override_section_assignments: Optional[dict[str, list[str]]],
    *,
    unit_count: int,
) -> Optional[str]:
    """Infer a layout when manual zone ids exactly match a catalog layout."""

    if not override_section_assignments:
        return None
    requested_positions = set(override_section_assignments.keys())
    for layout_id, spec in LAYOUT_PRESETS.items():
        if not spec.get("render_ready", False):
            continue
        positions = set(spec.get("positions") or [])
        if len(positions) != unit_count:
            continue
        if requested_positions == positions:
            return layout_id
    return None


# ─── Slot mapping (catalog-only dispatch) ──────────────────────

def _build_task24_layout_decision_basis(
    *,
    units: list,
    zones_data: list[dict],
    slide_footer: Optional[str],
    layout_preset: str,
    auto_layout_preset: Optional[str],
    layout_override_applied: bool,
) -> dict:
    """Record the T24 layout contract from normalized top-level units.

    T24 intentionally does not inspect child nodes or summary/footer text when
    choosing the body-zone count. At this point Task 14 has already collapsed
    aligned child evidence back to top-level parent units, so ``units`` is the
    source of truth for body layout cardinality.
    """

    return {
        "task24": "normalized_top_level_unit_layout",
        "top_level_unit_count": len(units),
        "fixed_footer_present": bool(slide_footer),
        "summary_footer_excluded_from_zone_count": bool(slide_footer),
        "layout_preset": layout_preset,
        "auto_layout_preset": auto_layout_preset,
        "override_applied": bool(layout_override_applied),
        "zone_count": len(zones_data),
        "unit_source_section_ids": [list(u.source_section_ids) for u in units],
        "zone_content_weights": [
            {
                "position": z.get("position"),
                "template_id": z.get("template_id"),
                "score": (z.get("content_weight") or {}).get("score"),
                "text_length": (z.get("content_weight") or {}).get("text_length"),
                "subsection_count": (z.get("content_weight") or {}).get("subsection_count"),
                "min_height_px": z.get("min_height_px"),
            }
            for z in zones_data
        ],
        "policy": (
            "normalized top-level units decide body-zone count; child sections "
            "and registered component expansions are frame-internal by default; "
            "summary/footer is fixed outside body zones; row/column sizing uses "
            "content_weight + frame min height"
        ),
    }


def _known_contract_ids() -> list[str]:
    from phase_z2_mapper import load_frame_contracts
    return list(load_frame_contracts().keys())


def map_mdx_to_slots(section: MdxSection, template_id: str) -> dict:
    """template_id → slot_payload via catalog contract only.

    F13/F29/F16 등 모든 frame 의 slot 구조 / cardinality / role / payload builder 는
    `templates/phase_z2/catalog/frame_contracts.yaml` 에 선언. legacy hand-coded
    mapper / MAPPER_BY_TEMPLATE / COLOR_CLASS_BY_KEYWORD / 관련 helper 는
    F13/F29/F16 transition (2026-04-29) 후 모두 제거.

    template_id 가 catalog 에 없으면 ValueError — fallback 없음.
    새 frame 추가 = catalog yaml 에 entry 추가 + (필요시) 새 builder/parser 등록.
    """
    contract = get_contract(template_id)
    if contract is None:
        raise ValueError(
            f"No frame_contracts entry for template_id='{template_id}'. "
            f"Add an entry in templates/phase_z2/catalog/frame_contracts.yaml. "
            f"Known contracts: {sorted(_known_contract_ids())}."
        )
    return map_with_contract(section, contract)


# ─── Asset copy ─────────────────────────────────────────────────

def copy_assets(
    template_id: str,
    run_dir: Path,
    *,
    trace: Optional[list[dict]] = None,
) -> Optional[Path]:
    """Frame asset (Figma) 폴더 복사 — frame_id 는 catalog contract 에서 도출.

    contract 에 `frame_id` 없으면 (asset 없는 frame) None 반환.
    이전엔 pipeline.py 에 TEMPLATE_TO_FRAME_ID Python dict 가 있었지만 catalog 로 이전 (2026-04-29).
    """
    record: dict = {
        "template_id": template_id,
        "src": None,
        "dst": None,
        "source_kind": None,
        "copied_count": 0,
        "skipped_reason": None,
        "error": None,
    }

    def _finish(path: Optional[Path]) -> Optional[Path]:
        if trace is not None:
            trace.append(record)
        return path

    contract = get_contract(template_id)
    frame_id = (contract or {}).get("frame_id")
    if not frame_id:
        record["skipped_reason"] = "no_frame_id"
        return None

    template_src = TEMPLATE_ASSETS_BASE / template_id
    figma_src = ASSETS_SOURCE_BASE / str(frame_id) / "assets"
    if template_src.exists():
        src = template_src
        record["source_kind"] = "template_assets"
    else:
        src = figma_src
        record["source_kind"] = "figma_assets_fallback"
    record["src"] = str(src.relative_to(PROJECT_ROOT)) if src.exists() else str(src)
    if not src.exists():
        record["skipped_reason"] = "source_missing"
        return _finish(None)

    dst = run_dir / "assets" / template_id
    record["dst"] = _rel_to_project(dst)
    dst.parent.mkdir(parents=True, exist_ok=True)
    try:
        if dst.exists():
            shutil.rmtree(dst)
        shutil.copytree(src, dst)
        record["copied_count"] = sum(1 for p in dst.rglob("*") if p.is_file())
    except Exception as exc:
        record["error"] = str(exc)
        if trace is not None:
            trace.append(record)
        raise
    return _finish(dst)


# ─── Render (single slide + Type B) ────────────────────────────

def _read_token_css() -> str:
    token_dir = PROJECT_ROOT / "templates" / "styles" / "tokens"
    files = ["typography.css", "spacing.css", "colors.css"]
    parts = []
    for f in files:
        path = token_dir / f
        if path.exists():
            parts.append(f"/* === {f} === */\n{path.read_text(encoding='utf-8')}")
    return "\n\n".join(parts)


def _attempt_zone_ratio_retry(
    *,
    run_dir: Path,
    out_path: Path,
    slide_title: str,
    slide_footer: Optional[str],
    zones_data: list[dict],
    debug_zones: list[dict],
    layout_preset: str,
    layout_css: dict,
    overflow: dict,
    fit_classification: dict,
    router_decision: dict,
    gap_px: int,
    override_zone_geometries: Optional[dict[str, dict]] = None,
) -> dict:
    """A3 zone_ratio_retry orchestration.

    locked rules :
      - retry budget = 1
      - slide-base / spacing / gap 고정
      - target zone height 만 증가, sibling donor 에서 같은 양 차감
      - donor 룰 strict (visual ok / capacity ok / slack > 0 / min_height 보존)
      - (b) revert : redistribution fail 또는 rerender 후 visual fail 시 original final.html 그대로

    Returns:
        retry_trace dict (always returned, even when no retry attempted) with :
          retry_attempted             : bool
          retry_action                : 'zone_ratio_retry' or None
          plan                        : phase_z2_retry.plan_zone_ratio_retry() 결과 (있을 때만)
          rerender_attempted          : bool
          retry_passed                : bool
          retry_failure_reason        : str or None
          retried_candidate_path      : str or None (rerender 한 경우 진단 artifact 경로)
          post_retry_overflow         : dict (retry_passed=True 일 때만)
          post_retry_debug_zones      : list (retry_passed=True 일 때만 — height_px 갱신본)
          post_retry_layout_css       : dict (retry_passed=True 일 때만)
    """
    base_trace = {
        "retry_attempted": False,
        "retry_action": None,
        "plan": None,
        "rerender_attempted": False,
        "retry_passed": False,
        "retry_failure_reason": None,
        "retried_candidate_path": None,
        "safety_margin_px": DEFAULT_SAFETY_MARGIN_PX,
        "policy": (
            "A3 locked rules : retry budget=1, slide-base/spacing/gap fixed, "
            "donor strict (sibling/visual ok/capacity ok/slack>0/min_height 보존), "
            "(b) revert on redistribution fail or rerender visual fail."
        ),
    }

    # 1. retry attempt 자체가 적절한지 판단
    if not router_decision.get("router_active"):
        base_trace["retry_skipped_reason"] = "router_active=False (visual check passed — no overflow)"
        return base_trace

    proposed = router_decision.get("proposed_actions_summary") or []
    if "zone_ratio_retry" not in proposed:
        base_trace["retry_skipped_reason"] = (
            f"zone_ratio_retry not in proposed_actions {proposed} (다른 action category)"
        )
        return base_trace

    # IMP-09 PR 1 retry gate — row-axis retry is only valid for layouts whose
    # row geometry is dynamic. 2-D / dynamic_cols layouts and fr_default sinks
    # would either misapply row-only redistribution or produce a no-op trace.
    if layout_css.get("dynamic_cols", False):
        base_trace["retry_skipped_reason"] = (
            "layout has dynamic_cols (2-D topology) — "
            "row-axis retry not applicable to 2-D layouts (IMP-09 lock)"
        )
        return base_trace
    if not layout_css.get("dynamic_rows", False):
        base_trace["retry_skipped_reason"] = (
            "layout is fr_default_from_preset (no dynamic geometry) — retry no-op"
        )
        return base_trace

    # 2. plan
    base_trace["retry_attempted"] = True
    base_trace["retry_action"] = "zone_ratio_retry"
    plan = plan_zone_ratio_retry(
        debug_zones=debug_zones,
        overflow=overflow,
        fit_classification=fit_classification,
        router_decision=router_decision,
        safety_margin_px=DEFAULT_SAFETY_MARGIN_PX,
        override_zone_geometries=override_zone_geometries,
    )
    base_trace["plan"] = plan

    if plan is None:
        base_trace["retry_failure_reason"] = "plan_zone_ratio_retry returned None — no target classification matched zone_ratio_retry"
        return base_trace

    if not plan.get("feasible"):
        # redistribution check 실패 → rerender 안 함, original final.html 그대로
        base_trace["retry_failure_reason"] = plan.get("failure_reason")
        print(
            f"  retry   : zone_ratio_retry redistribution INFEASIBLE — "
            f"target {plan['target_zone_position']} needs {plan['target_added_px']}px, "
            f"{plan.get('failure_reason')}"
        )
        return base_trace

    # 3. feasible — apply plan to layout_css, rerender to candidate path (NOT final.html yet)
    new_layout_css = apply_retry_to_layout_css(
        layout_css, plan, zones_data,
        total_height=SLIDE_BODY_HEIGHT, gap_px=gap_px,
    )
    candidate_path = run_dir / "retried_candidate.html"
    candidate_html = render_slide(
        slide_title, slide_footer, zones_data, layout_preset, new_layout_css, gap_px=gap_px,
    )
    candidate_path.write_text(candidate_html, encoding="utf-8")
    base_trace["rerender_attempted"] = True
    base_trace["retried_candidate_path"] = _rel_to_project(candidate_path)

    print(
        f"  retry   : zone_ratio_retry attempted — target {plan['target_zone_position']} "
        f"+{plan['target_added_px']}px (donor {plan['donor_zone_position']} -{plan['donor_reduced_px']}px) "
        f"→ rerender to retried_candidate.html → visual check"
    )

    # 4. 후 visual check on candidate
    candidate_overflow = run_overflow_check(candidate_path)

    if candidate_overflow.get("passed", False):
        # 성공 — final.html 을 candidate 로 promote
        out_path.write_text(candidate_html, encoding="utf-8")
        # debug_zones height_px / ratio 갱신 (post-retry 상태)
        new_heights = new_layout_css["heights_px"]
        new_ratios = new_layout_css["ratios"]
        post_retry_debug_zones = []
        for i, dz in enumerate(debug_zones):
            new_dz = dict(dz)
            new_dz["height_px"] = new_heights[i] if i < len(new_heights) else dz.get("height_px")
            new_dz["ratio"] = new_ratios[i] if i < len(new_ratios) else dz.get("ratio")
            new_dz["zone_height_post_retry"] = True
            post_retry_debug_zones.append(new_dz)

        base_trace["retry_passed"] = True
        base_trace["post_retry_overflow"] = candidate_overflow
        base_trace["post_retry_debug_zones"] = post_retry_debug_zones
        base_trace["post_retry_layout_css"] = new_layout_css
        print(f"  retry   : PASSED — final.html promoted to retried version")
        return base_trace

    # 5. rerender 후에도 visual fail → (b) revert : final.html 은 original 그대로 (이미 written)
    base_trace["retry_passed"] = False
    base_trace["retry_failure_reason"] = (
        f"rerender visual_check failed: {candidate_overflow.get('fail_reasons')}. "
        f"reverting to original final.html (retried_candidate.html stays as diagnostic only)."
    )
    base_trace["candidate_overflow_summary"] = {
        "passed": False,
        "fail_reasons": candidate_overflow.get("fail_reasons", []),
    }
    print(f"  retry   : FAILED — candidate visual_check 도 실패. revert to original. ({candidate_path.name} 은 diagnostic 으로 보존)")
    return base_trace


# IMP-12 u8 — Step 17 salvage cascade orchestrator (deterministic, no normal-path AI).
# Plan/apply pairs: phase_z2_retry (u4/u5/u6). Routing: failure_router.route_retry_failure (u3).
# Pipeline wiring (cascade_inputs assembly + retry_trace merge) lands in u9.
# IMP-88 u6 — extended with layout_adjust + frame_internal_fit_candidate dispatch.
# Mirror of failure_router.SALVAGE_FAILURE_TYPE_BY_ACTION (single source-of-truth lives
# there; this local map gates which actions the salvage loop can execute and feeds the
# loop-cap range(len(...)) so cascade depth scales with implemented executors).
_SALVAGE_FAIL_BY_ACTION = {
    "cross_zone_redistribute": "cross_zone_redistribute_insufficient",
    "glue_compression": "glue_absorption_insufficient",
    "font_step_compression": "font_step_insufficient",
    "layout_adjust": "layout_adjust_insufficient",
    "frame_internal_fit_candidate": "frame_internal_fit_candidate_insufficient",
}


def _attempt_salvage_chain(
    *, run_dir: Path, out_path: Path, slide_title: str, slide_footer: Optional[str],
    zones_data: list[dict], layout_preset: str, layout_css: dict,
    cascade_inputs: dict, initial_failure_type: str, gap_px: int,
) -> dict:
    """IMP-12 u8 — deterministic Step 17 salvage cascade (cross_zone → glue → font_step).
    Per stage: plan → apply CSS → rerender → run_overflow_check. PASS promotes final.html;
    cascade-exit (layout_adjust/frame_reselect/none) or all-fail preserves (b) revert.
    Honors IMP-09 dynamic_cols / fr_default gate.
    """
    trace = {"salvage_attempted": False, "salvage_passed": False, "salvage_steps": []}
    if layout_css.get("dynamic_cols", False) or not layout_css.get("dynamic_rows", False):
        trace["salvage_skipped_reason"] = "IMP-09 gate — dynamic_cols/no dynamic_rows; cascade no-op"
        return trace
    trace["salvage_attempted"] = True
    failure_type = initial_failure_type
    ci = cascade_inputs
    for _ in range(len(_SALVAGE_FAIL_BY_ACTION)):
        routing = route_retry_failure(failure_type) or {}
        next_action = routing.get("next_proposed_action")
        if next_action not in _SALVAGE_FAIL_BY_ACTION:
            trace["salvage_terminal_action"] = next_action
            trace["salvage_terminal_rationale"] = routing.get("rationale")
            return trace
        # IMP-88 u6 — layout_adjust takes a distinct render path (fresh
        # render_slide with the new preset + remapped zones_data + new
        # layout_css), so it is dispatched BEFORE the shared CSS-overlay
        # planner cluster below. No common margin / slide-body shrink
        # ([[feedback_phase_z_spacing_direction]]) — topology swap only.
        if next_action == "layout_adjust":
            # T19d (#98): no silent topology mutation. A retry/salvage path
            # must not rewrite final.html from top/bottom to left/right unless
            # an explicit layout override is committed.
            trace["salvage_terminal_action"] = "layout_adjust_blocked_no_silent_layout_mutation"
            trace["salvage_terminal_rationale"] = (
                "layout_adjust would change final.html zone positions; kept original layout"
            )
            return trace
            plan = plan_layout_adjust(
                current_layout_preset=layout_preset, zones_data=zones_data)
            new_layout_css = (
                apply_layout_adjust_layout_css(plan, gap_px=gap_px)
                if (plan and plan.get("feasible")) else None
            )
            candidate_path = run_dir / f"salvage_{next_action}_candidate.html"
            candidate_html, candidate_overflow, passed = None, None, False
            if new_layout_css:
                candidate_html = render_slide(
                    slide_title, slide_footer,
                    plan["new_zones_data"], plan["new_layout_preset"],
                    new_layout_css, gap_px=gap_px,
                )
                candidate_path.write_text(candidate_html, encoding="utf-8")
                candidate_overflow = run_overflow_check(candidate_path)
                passed = bool(candidate_overflow.get("passed", False))
            step = {
                "action": next_action, "plan": plan, "passed": passed,
                "new_layout_preset": (
                    plan.get("new_layout_preset") if isinstance(plan, dict) else None
                ),
                "candidate_path": (
                    _rel_to_project(candidate_path)
                    if new_layout_css else None
                ),
            }
            if passed:
                out_path.write_text(candidate_html, encoding="utf-8")
                step["post_salvage_overflow"] = candidate_overflow
                trace["salvage_steps"].append(step)
                trace["salvage_passed"] = True
                return trace
            step["failure_reason"] = (
                (plan.get("failure_reason") if isinstance(plan, dict) else None)
                or (candidate_overflow.get("fail_reasons") if candidate_overflow else None)
                or "infeasible or render emitted no candidate")
            trace["salvage_steps"].append(step)
            failure_type = _SALVAGE_FAIL_BY_ACTION[next_action]
            continue
        if next_action == "cross_zone_redistribute":
            if ci.get("fit_analysis") is None:
                plan = {"action": "cross_zone_redistribute", "feasible": False,
                        "failure_reason": "cascade_inputs.fit_analysis missing — cross_zone_redistribute requires fit_analysis."}
            else:
                plan = plan_cross_zone_redistribute(
                    fit_analysis=ci["fit_analysis"], containers=ci.get("containers") or {},
                    min_margin_px=ci.get("min_margin_px"),
                    manual_zone_positions=set(ci.get("manual_zone_positions") or []))
            apply_fn = apply_cross_zone_redistribute_css
        elif next_action == "glue_compression":
            plan = plan_glue_compression(
                excess_px=float(ci.get("excess_px") or 0.0),
                block_count=int(ci.get("block_count") or 0),
                zone_position=str(ci.get("zone_position") or ""))
            apply_fn = apply_glue_compression_css
        elif next_action == "frame_internal_fit_candidate":
            # IMP-88 u6 — per-zone frame-scoped envelope variant. Resolves
            # frame_template_id from zones_data via cascade_inputs.zone_position
            # so the planner stays within the frame contract envelope
            # (no shared margin shrink per [[feedback_phase_z_spacing_direction]]).
            _target_pos = str(ci.get("zone_position") or "")
            _target_zone = next(
                (z for z in zones_data if z.get("position") == _target_pos), {},
            ) or {}
            _frame_tid = str(_target_zone.get("template_id") or "")
            plan = plan_frame_internal_fit_candidate(
                frame_template_id=_frame_tid,
                overflow_zone={"excess_y": float(ci.get("excess_px") or 0.0)},
            )
            apply_fn = apply_frame_internal_fit_candidate_css
        else:
            trace["salvage_terminal_action"] = "font_step_compression_blocked_no_font_shrink"
            trace["salvage_terminal_rationale"] = (
                "T28.5 policy forbids inner font-size/scale changes as a fit lever"
            )
            trace["salvage_steps"].append({
                "action": next_action,
                "passed": False,
                "blocked_by_policy": "no_font_shrink",
                "failure_reason": (
                    "font_step_compression is disabled; use zone redistribution, "
                    "frame/layout re-selection, popup/details separation, or "
                    "presentation_not_ready"
                ),
            })
            return trace
        css_override = apply_fn(plan) if (plan and plan.get("feasible")) else ""
        candidate_path = run_dir / f"salvage_{next_action}_candidate.html"
        candidate_html, candidate_overflow, passed = None, None, False
        if css_override:
            base = render_slide(slide_title, slide_footer, zones_data, layout_preset, layout_css, gap_px=gap_px)
            style = f"<style>\n{css_override}\n</style>"
            candidate_html = base.replace("</head>", f"{style}\n</head>", 1) if "</head>" in base else style + base
            candidate_path.write_text(candidate_html, encoding="utf-8")
            candidate_overflow = run_overflow_check(candidate_path)
            passed = bool(candidate_overflow.get("passed", False))
        step = {"action": next_action, "plan": plan, "passed": passed,
                "css_override": css_override or None,
                "candidate_path": _rel_to_project(candidate_path) if css_override else None}
        if passed:
            out_path.write_text(candidate_html, encoding="utf-8")
            step["post_salvage_overflow"] = candidate_overflow
            trace["salvage_steps"].append(step)
            trace["salvage_passed"] = True
            return trace
        step["failure_reason"] = (
            (plan.get("failure_reason") if isinstance(plan, dict) else None)
            or (candidate_overflow.get("fail_reasons") if candidate_overflow else None)
            or "infeasible or no CSS emitted")
        trace["salvage_steps"].append(step)
        failure_type = _SALVAGE_FAIL_BY_ACTION[next_action]
    return trace


# IMP-88 (#88) u7 — Step 17 image_fit single-pass entry executor.
# image_fit is NOT a salvage cascade stage (deliberately OUT of
# _SALVAGE_FAIL_BY_ACTION per u6 guard). Instead it is a Step 17 ENTRY
# single-pass: aggregate per-image plan/apply via plan_image_fit (u4) +
# apply_image_fit_css (u4), emit one CSS overlay, re-render once,
# run_overflow_check. PASS promotes final.html; FAIL records `image_fit`
# step with failure_reason so failure_router (u2)
# SALVAGE_FAILURE_TYPE_BY_ACTION classifies it as `image_fit_insufficient`
# and the cascade entry block routes onto layout_adjust.
# Honors [[feedback_phase_z_spacing_direction]] — frame-scoped img CSS only,
# no common margin / slide-body / zone gap shrink. AI isolation contract
# (PZ-1) — deterministic data-surface, no AI call.
def _attempt_step17_image_fit_single_pass(
    *, run_dir: Path, out_path: Path, slide_title: str, slide_footer: Optional[str],
    zones_data: list[dict], layout_preset: str, layout_css: dict,
    image_events: list[dict], gap_px: int,
    delta_tol: float = IMAGE_ASPECT_DELTA_TOL,
) -> dict:
    """IMP-88 u7 — Step 17 image_fit single-pass executor.

    Returns a result dict with shape:
      - triggered : bool — True iff any feasible image_fit plan emitted CSS.
      - passed    : bool — True iff post-rerender overflow check passed.
      - step      : dict|None — salvage_steps[] entry shape (action="image_fit",
                    image_fit_event_plans, candidate_path, post_salvage_overflow
                    on pass / failure_reason on fail).
      - candidate_html : str|None — rendered HTML when triggered (None otherwise).
      - candidate_overflow : dict|None — run_overflow_check result when triggered.
      - event_plans : list[dict] — every plan_image_fit result (feasible + no-op),
                      surfaced for telemetry even when none emit CSS.
    Side effect on PASS only: writes candidate_html to out_path.
    """
    event_plans = []
    css_chunks = []
    for ev in (image_events or []):
        plan = plan_image_fit(image_event=ev, delta_tol=delta_tol)
        event_plans.append(plan)
        if plan.get("feasible"):
            css = apply_image_fit_css(plan)
            if css:
                css_chunks.append(css)
    if not css_chunks:
        return {
            "triggered": False, "passed": False, "step": None,
            "candidate_html": None, "candidate_overflow": None,
            "event_plans": event_plans,
        }
    candidate_path = run_dir / "salvage_image_fit_candidate.html"
    base = render_slide(
        slide_title, slide_footer, zones_data, layout_preset, layout_css,
        gap_px=gap_px,
    )
    style = "<style>\n" + "\n".join(css_chunks) + "\n</style>"
    candidate_html = (
        base.replace("</head>", f"{style}\n</head>", 1)
        if "</head>" in base else style + base
    )
    candidate_path.write_text(candidate_html, encoding="utf-8")
    candidate_overflow = run_overflow_check(candidate_path)
    passed = bool(candidate_overflow.get("passed", False))
    step = {
        "action": "image_fit", "passed": passed,
        "image_fit_event_plans": event_plans,
        "candidate_path": (
            _rel_to_project(candidate_path)
            if candidate_path.is_absolute() else str(candidate_path)
        ),
    }
    if passed:
        step["post_salvage_overflow"] = candidate_overflow
        out_path.write_text(candidate_html, encoding="utf-8")
    else:
        step["failure_reason"] = (
            candidate_overflow.get("fail_reasons")
            or "image_fit single-pass: overflow persists"
        )
    return {
        "triggered": True, "passed": passed, "step": step,
        "candidate_html": candidate_html, "candidate_overflow": candidate_overflow,
        "event_plans": event_plans,
    }


def _remeasure_after_frame_reselect(
    *, candidate_path: Path, plan: Optional[dict] = None,
) -> dict:
    """IMP-35 (#64) u1 — post-frame remeasure helper for the cascade terminal.

    Contract (q4 / Stage 2): frame_reselect_insufficient is detected by an
    *explicit overflow re-measure* after a V4 top-k alternate frame swap —
    NOT a failure-flag carryover. This helper runs run_overflow_check on the
    re-rendered candidate HTML and shapes the salvage_steps entry that
    classify_retry_failure / SALVAGE_FAILURE_TYPE_BY_ACTION read.

    Future frame_reselect orchestrator (post-IMP-35) writes the candidate
    HTML and calls this helper to append the entry to retry_trace.salvage_steps.
    On passed=True the orchestrator promotes the candidate to final.html; on
    passed=False the classifier emits frame_reselect_insufficient → u2 routes
    onto details_popup_escalation (Step 17 POPUP gate / u5).
    """
    candidate_overflow = run_overflow_check(candidate_path)
    passed = bool(candidate_overflow.get("passed", False))
    return {
        "action": "frame_reselect",
        "plan": plan,
        "passed": passed,
        "candidate_path": (
            _rel_to_project(candidate_path)
            if candidate_path.is_absolute() else str(candidate_path)
        ),
        "post_salvage_overflow": candidate_overflow,
        "failure_reason": (
            None if passed
            else (candidate_overflow.get("fail_reasons") or "post-frame remeasure: overflow persists")
        ),
    }


# ─── IMP-42 u3 (#71) — unconditional Step 12 / Step 13 DIAG log helper ──


def _emit_diag_zones_shape(stage_label: str, zones_data: list[dict], **extra_fields) -> None:
    """IMP-42 u3 (#71) — emit shape-only zone metadata to stdout.

    Used at the Step 12 slot_payload emit site and the Step 13 render_slide
    entry site to make the silent 3-hop handoff visible in the terminal.
    Shape-only — never logs raw slot_payload values — so the diag is
    sample-agnostic (RULE 0) and never leaks user content.

    No env gate: silence is the bug this IMP fights, so the log fires
    unconditionally on every slide loop.
    """
    payload = {
        "zones_count": len(zones_data),
        "zones": [
            {
                "i": i,
                "position": z.get("position"),
                "template_id": z.get("template_id"),
                "slot_keys": (
                    sorted(z["slot_payload"].keys())
                    if isinstance(z.get("slot_payload"), dict) else None
                ),
            }
            for i, z in enumerate(zones_data)
        ],
    }
    payload.update(extra_fields)
    print(
        f"[DIAG] phase_z2 {stage_label} "
        + json.dumps(payload, ensure_ascii=False, sort_keys=True),
        flush=True,
    )


# ─── IMP-42 u2 (#71) — post-render HTML invalid path char detector ──

_INVALID_PATH_ATTR_RE = re.compile(
    r"""(src|href)\s*=\s*["']([^"']*)["']|url\(\s*['"]?([^)'"\s]+)['"]?\s*\)""",
    re.IGNORECASE,
)
_INVALID_PATH_CHARS = ("\\", "&amp;", "&#39;")


def _scan_rendered_html_for_invalid_path_chars(html: str, context: str) -> None:
    """IMP-42 u2 (#71) — fail loud when rendered HTML asset references
    contain invalid path characters in src / href / url(...) values.

    Catches three silent fail vectors at the rendered HTML boundary that
    surface downstream as 404 / asset-load failures far from upstream cause:
      - Windows backslash from str(Path) (e.g. ``assets\\img.png``).
      - Autoescape entity ``&amp;`` (raw ``&`` in raw path source string).
      - Autoescape entity ``&#39;`` (raw ``'`` in raw path source string).

    Raises ValueError on first hit, citing context, attr type, value snippet.
    Scope-locked to rendered HTML asset attrs only; never inspects CSS grid
    metadata or static template strings.
    """
    for match in _INVALID_PATH_ATTR_RE.finditer(html):
        if match.group(3) is not None:
            attr_label = "url(...)"
            value = match.group(3)
        else:
            attr_label = match.group(1).lower()
            value = match.group(2)
        for bad in _INVALID_PATH_CHARS:
            if bad in value:
                snippet = value if len(value) <= 120 else value[:117] + "..."
                raise ValueError(
                    f"render_slide: {context} — invalid path char {bad!r} in "
                    f"{attr_label} value (value={snippet}). "
                    "Likely upstream: Windows backslash from str(Path) or "
                    "autoescape of '&' / \"'\" in raw path string."
                )


def render_slide(slide_title: str, slide_footer: Optional[str],
                 zones_data: list[dict], layout_preset: str,
                 layout_css: dict, gap_px: int = GRID_GAP,
                 *, embedded_mode: str = "auto") -> str:
    """Single slide HTML — slide_base.html + 8-preset layout vocabulary.

    layout_css = build_layout_css() 결과 — areas/cols/rows 문자열 + 동적 heights flag.
    Template 은 layout_css.{areas,cols,rows} 를 grid CSS 에 직접 주입.

    embedded_mode (IMP-14): "auto" | "embedded" | "standalone". Controls
    slide_base.html body CSS contract. Default "auto" preserves backward-compat
    with run_overflow_check standalone path and lets iframe consumers signal via
    ?embedded=1 or window.self!==window.top.
    """
    if embedded_mode not in ("auto", "embedded", "standalone"):
        raise ValueError(
            f"render_slide: invalid embedded_mode={embedded_mode!r}; "
            "expected one of 'auto', 'embedded', 'standalone'"
        )
    # IMP-42 u3 (#71) — unconditional Step 13 entry DIAG log.
    _emit_diag_zones_shape(
        "Step 13 render_slide entry",
        zones_data,
        layout_preset=layout_preset,
        embedded_mode=embedded_mode,
    )
    env = Environment(
        loader=FileSystemLoader(str(TEMPLATE_DIR)),
        autoescape=select_autoescape(["html"]),
    )
    for zone_index, zone in enumerate(zones_data):
        # Stage 4 Part 2 (Codex #10 Catch N) — empty zone produced by section
        # assignment override has no partial template; render an empty string so
        # the slide_base zones loop preserves grid identity without TemplateNotFound.
        if zone.get("template_id") == "__empty__":
            zone["partial_html"] = ""
            continue
        # IMP-42 u1 (#71) — fail-loud precondition for Step 13 partial render.
        # Catches the silent fail vector where Step 12 emits a zone dict missing
        # `template_id` / `slot_payload`. Error message cites zone_index +
        # missing key so the diag is actionable (vs Jinja TemplateNotFound /
        # KeyError surfacing far from the upstream emit site).
        template_id = zone.get("template_id")
        if not isinstance(template_id, str) or not template_id:
            raise TypeError(
                f"render_slide: zones_data[{zone_index}] precondition failed — "
                f"`template_id` must be a non-empty str, got {type(template_id).__name__}={template_id!r}"
            )
        if "slot_payload" not in zone:
            raise TypeError(
                f"render_slide: zones_data[{zone_index}] precondition failed — "
                f"`slot_payload` key missing (template_id={template_id!r})"
            )
        slot_payload = zone["slot_payload"]
        if not isinstance(slot_payload, dict):
            raise TypeError(
                f"render_slide: zones_data[{zone_index}] precondition failed — "
                f"`slot_payload` must be a dict, got {type(slot_payload).__name__} "
                f"(template_id={template_id!r})"
            )
        partial = env.get_template(f"families/{template_id}.html")
        rendered_partial = partial.render(slot_payload=slot_payload)
        # IMP-42 u2 (#71) — fail loud on invalid path chars in rendered HTML
        # asset refs (src / href / url(...)). Catches Windows backslash and
        # autoescape entity vectors before they reach the browser as 404.
        _scan_rendered_html_for_invalid_path_chars(
            rendered_partial,
            f"zones_data[{zone_index}] template_id={template_id!r}",
        )
        # IMP-56 (#90) u9 — Step 13 text_path stamp (u8 stamper, pure
        # deterministic). Injects ``data-text-path="{slot_key}.{line_index}"``
        # onto each ``text-line`` opening tag so the frontend SlideCanvas
        # (u10+) can attribute per-line edits back to the text_overrides
        # axis. Idempotent + forward-compat: non-list slots are silently
        # skipped, excess text-lines pass through unstamped, and an
        # already-stamped element is left unchanged.
        zone["partial_html"] = _stamp_zone_html(rendered_partial, slot_payload)
        # IMP-94 (#94) u2 — Step 11/13/21 region/content marker stamp
        # chained after IMP-56 u9. Marker source = per-zone
        # ``placement_markers`` (u3 live B4 path, u4 non-live defaults).
        # Missing / None → empty list fallback keeps Codex #16 P4b
        # crash risk closed and the stamper deterministically no-ops.
        zone["partial_html"] = _stamp_region_markers(
            zone["partial_html"], zone.get("placement_markers") or []
        )

    base = env.get_template("slide_base.html")
    rendered_base = base.render(
        slide_title=slide_title,
        slide_footer=slide_footer,
        zones=zones_data,
        layout_preset=layout_preset,
        layout_css=layout_css,
        gap_px=gap_px,
        token_css=_read_token_css(),
        embedded_mode=embedded_mode,
    )
    # IMP-42 u2 (#71) — also scan the assembled slide_base output to cover
    # asset refs introduced by the slide-base shell itself (title / footer /
    # popup slots) outside the per-zone partial scope.
    _scan_rendered_html_for_invalid_path_chars(rendered_base, "slide_base")
    return rendered_base


# ─── Selenium check (single slide + per-zone) ──────────────────

def run_overflow_check(html_path: Path) -> dict:
    """Single slide + per-zone overflow + clipping check."""
    from selenium import webdriver
    from selenium.webdriver.chrome.options import Options
    from selenium.webdriver.chrome.service import Service

    options = Options()
    options.add_argument("--headless=new")
    options.add_argument("--no-sandbox")
    options.add_argument("--disable-dev-shm-usage")
    options.add_argument("--window-size=1400,900")

    chromedriver_candidates = [
        PROJECT_ROOT / "chromedriver",
        PROJECT_ROOT / "chromedriver.exe",
    ]
    driver = None
    last_err = None
    for path in chromedriver_candidates:
        if path.is_file():
            try:
                driver = webdriver.Chrome(service=Service(str(path)), options=options)
                break
            except Exception as e:
                last_err = e
    if driver is None:
        try:
            driver = webdriver.Chrome(options=options)
        except Exception as e:
            return {"passed": False, "error": f"selenium init failed: {last_err or e}"}

    try:
        driver.get(html_path.resolve().as_uri())
        driver.set_window_size(1400, 900)
        driver.implicitly_wait(1)
        result = driver.execute_script(r"""
            const measure = (el) => ({
                clientWidth: el.clientWidth,
                clientHeight: el.clientHeight,
                scrollWidth: el.scrollWidth,
                scrollHeight: el.scrollHeight,
                excess_x: Math.max(0, el.scrollWidth - el.clientWidth),
                excess_y: Math.max(0, el.scrollHeight - el.clientHeight),
                overflowed: (el.scrollWidth > el.clientWidth + 5) ||
                            (el.scrollHeight > el.clientHeight + 5),
            });
            const slide = document.querySelector('.slide');
            if (!slide) return { error: '.slide not found' };

            const slideM = measure(slide);
            slideM.size_correct = slide.clientWidth === 1280 && slide.clientHeight === 720;
            // A-6 (IMP-01 #1) — slide-relative bbox base
            const slideRect = slide.getBoundingClientRect();

            const body = document.querySelector('.slide-body');
            const bodyM = body ? measure(body) : null;

            const zones = [];
            const zone_geometries_px = [];

            // IMP-15 실행-2 (issue #46) — element-identity dedup map for table_events.
            // Map<Element, integer> keyed by DOM node reference (NOT class string) so that
            // two wrappers sharing identical className resolve to distinct map entries.
            // Populated alongside the existing per-zone clipped_inner scan below.
            const clippedWrapperMap = new Map();
            let clippedIdxCounter = 0;

            slide.querySelectorAll('.zone').forEach((z) => {
                const pos = z.getAttribute('data-zone-position') || 'unknown';
                const tid = z.getAttribute('data-template-id') || '?';
                const m = measure(z);
                m.position = pos;
                m.template_id = tid;

                // A-6 (IMP-01 #1) — zone bbox in slide-relative px (additive trace, no layout side effect)
                const zoneRect = z.getBoundingClientRect();
                zone_geometries_px.push({
                    position: pos,
                    template_id: tid,
                    x: Math.round(zoneRect.left - slideRect.left),
                    y: Math.round(zoneRect.top - slideRect.top),
                    w: Math.round(zoneRect.width),
                    h: Math.round(zoneRect.height),
                });

                // 내부 clipping 검사 — frame-family root/cell 단위.
                // tolerance / threshold 그대로. inner_content_signals 만 추가 보강 (detection 데이터 늘림).
                const clipped = [];
                z.querySelectorAll('[class*="f13b"], [class*="f29b"], [class*="f16b"]').forEach((el) => {
                    const dx = el.scrollWidth - el.clientWidth;
                    const dy = el.scrollHeight - el.clientHeight;
                    if (dx > 5 || dy > 5) {
                        // inner content signals — clipped cell 안에 *어떤 종류의 콘텐츠가 들어있는지* 보고.
                        // classifier 가 frame_internal_cell 만 봐서는 부족하니 inner 까지 본다.
                        const inner_signals = [];
                        if (el.querySelector('.transform-block, .transform-row, .transform-rows')) {
                            inner_signals.push('structural_unit');
                        }
                        if (el.querySelector('table')) {
                            inner_signals.push('tabular');
                        }
                        if (el.querySelector('.text-line')) {
                            inner_signals.push('text_flow');
                        }
                        clipped.push({
                            class_name: el.className,
                            inner_content_signals: inner_signals,
                            excess_x: Math.max(0, dx),
                            excess_y: Math.max(0, dy),
                            clientWidth: el.clientWidth,
                            clientHeight: el.clientHeight,
                            scrollWidth: el.scrollWidth,
                            scrollHeight: el.scrollHeight,
                        });
                        // IMP-15 실행-2 (issue #46) — element-identity registration.
                        // Key by DOM node `el`, NOT className: two wrappers with identical
                        // class string still hash to distinct Map entries.
                        if (!clippedWrapperMap.has(el)) {
                            clippedWrapperMap.set(el, clippedIdxCounter);
                            clippedIdxCounter++;
                        }
                    }
                });
                m.clipped_inner = clipped;
                zones.push(m);
            });

            // B5 v0 — frame_slot_metrics (per-cell measurement of [data-frame-slot-id])
            // 현재 F29 partial 만 marker 보유 (process_column / product_column × 3 cells = 6 entries 기대).
            // 다른 frame (F13 / F16) 은 marker 미적용 → entry 0 — 정상.
            const frame_slot_metrics = [];
            slide.querySelectorAll('[data-frame-slot-id]').forEach((cell) => {
                const slotId = cell.getAttribute('data-frame-slot-id');
                const m2 = measure(cell);
                const parentZone = cell.closest('.zone');
                const zonePos = parentZone
                    ? (parentZone.getAttribute('data-zone-position') || 'unknown')
                    : 'unknown';
                const zoneTid = parentZone
                    ? (parentZone.getAttribute('data-template-id') || '?')
                    : '?';
                frame_slot_metrics.push({
                    zone_position: zonePos,
                    zone_template_id: zoneTid,
                    frame_slot_id: slotId,
                    class_name: cell.className,
                    clientWidth: m2.clientWidth,
                    clientHeight: m2.clientHeight,
                    scrollWidth: m2.scrollWidth,
                    scrollHeight: m2.scrollHeight,
                    excess_x: m2.excess_x,
                    excess_y: m2.excess_y,
                    overflowed: m2.overflowed,
                });
            });

            // IMP-15 실행-1 (issue #45) — image_events[] for image_aspect_mismatch detection.
            // 하나의 entry per <img> under .slide. natural vs rendered aspect 비교.
            // zone_position : closest('.zone') data-zone-position. 없으면 literal "unknown".
            const image_events = [];
            slide.querySelectorAll('img').forEach((img) => {
                const parentZone = img.closest('.zone');
                const zonePos = parentZone
                    ? (parentZone.getAttribute('data-zone-position') || 'unknown')
                    : 'unknown';
                const zoneTid = parentZone
                    ? (parentZone.getAttribute('data-template-id') || '?')
                    : '?';
                const imgRect = img.getBoundingClientRect();
                const rendered_w = imgRect.width;
                const rendered_h = imgRect.height;
                const natural_w = img.naturalWidth;
                const natural_h = img.naturalHeight;
                const natural_ratio = (natural_w > 0 && natural_h > 0)
                    ? (natural_w / natural_h)
                    : null;
                const rendered_ratio = (rendered_w > 0 && rendered_h > 0)
                    ? (rendered_w / rendered_h)
                    : null;
                const delta = (natural_ratio !== null && rendered_ratio !== null)
                    ? (rendered_ratio - natural_ratio)
                    : null;
                image_events.push({
                    src: img.getAttribute('src') || '',
                    zone_position: zonePos,
                    zone_template_id: zoneTid,
                    allow_aspect_crop: img.getAttribute('data-allow-aspect-crop') === '1',
                    natural_w: natural_w,
                    natural_h: natural_h,
                    rendered_w: Math.round(rendered_w),
                    rendered_h: Math.round(rendered_h),
                    natural_ratio: natural_ratio,
                    rendered_ratio: rendered_ratio,
                    delta: delta,
                    bbox: {
                        x: Math.round(imgRect.left - slideRect.left),
                        y: Math.round(imgRect.top - slideRect.top),
                        w: Math.round(rendered_w),
                        h: Math.round(rendered_h),
                    },
                });
            });

            // IMP-15 실행-2 (issue #46) — table_events[] for table_self_overflow detection.
            // One entry per <table> under .slide. wrapper_clipped_index is the integer index
            // (from clippedWrapperMap) of the nearest ancestor that is itself in the clipped
            // wrapper set, or null. Element-identity walk (NOT className) so that two same-class
            // wrappers (W1 clipped, W2 not) resolve independently for any contained <table>.
            const table_events = [];
            slide.querySelectorAll('table').forEach((tbl) => {
                const parentZone = tbl.closest('.zone');
                const zonePos = parentZone
                    ? (parentZone.getAttribute('data-zone-position') || 'unknown')
                    : 'unknown';
                const zoneTid = parentZone
                    ? (parentZone.getAttribute('data-template-id') || '?')
                    : '?';
                let wrapper_clipped_index = null;
                let node = tbl.parentElement;
                while (node && node !== slide) {
                    if (clippedWrapperMap.has(node)) {
                        wrapper_clipped_index = clippedWrapperMap.get(node);
                        break;
                    }
                    node = node.parentElement;
                }
                const tblRect = tbl.getBoundingClientRect();
                const dx = tbl.scrollWidth - tbl.clientWidth;
                const dy = tbl.scrollHeight - tbl.clientHeight;
                table_events.push({
                    zone_position: zonePos,
                    zone_template_id: zoneTid,
                    clientWidth: tbl.clientWidth,
                    clientHeight: tbl.clientHeight,
                    scrollWidth: tbl.scrollWidth,
                    scrollHeight: tbl.scrollHeight,
                    excess_x: Math.max(0, dx),
                    excess_y: Math.max(0, dy),
                    wrapper_clipped_index: wrapper_clipped_index,
                    bbox: {
                        x: Math.round(tblRect.left - slideRect.left),
                        y: Math.round(tblRect.top - slideRect.top),
                        w: Math.round(tblRect.width),
                        h: Math.round(tblRect.height),
                    },
                });
            });

            return { slide: slideM, slide_body: bodyM, zones, frame_slot_metrics, zone_geometries_px, image_events, table_events };
        """)

        screenshot_path = html_path.parent / "preview.png"
        try:
            driver.save_screenshot(str(screenshot_path))
            result["screenshot"] = _rel_to_project(screenshot_path)
        except Exception as e:
            result["screenshot_error"] = str(e)
    finally:
        driver.quit()

    if "error" in result:
        return {"passed": False, **result}

    fail_reasons = []
    if not result["slide"]["size_correct"]:
        fail_reasons.append(
            f"slide size != 1280x720 (got {result['slide']['clientWidth']}x{result['slide']['clientHeight']})"
        )
    if result["slide"]["overflowed"]:
        fail_reasons.append(
            f"slide overflowed by {result['slide']['excess_y']}px (vert) / {result['slide']['excess_x']}px (horiz)"
        )
    if result.get("slide_body") and result["slide_body"]["overflowed"]:
        fail_reasons.append(
            f"slide-body overflowed by {result['slide_body']['excess_y']}px (vert)"
        )
    for z in result["zones"]:
        if z["overflowed"]:
            fail_reasons.append(
                f"zone--{z['position']} ({z['template_id']}) overflowed by {z['excess_y']}px (vert) / {z['excess_x']}px (horiz)"
            )
        for c in z.get("clipped_inner", []):
            fail_reasons.append(
                f"zone--{z['position']}: inner clipped .{c['class_name']} — "
                f"excess {c['excess_y']}px vert / {c['excess_x']}px horiz "
                f"(content {c['scrollHeight']} vs container {c['clientHeight']})"
            )

    # IMP-15 실행-1 (issue #45) — image_aspect_mismatch aggregation.
    # |natural_ratio - rendered_ratio| > IMAGE_ASPECT_DELTA_TOL ⇒ fail_reason append.
    # Entries with null ratio (image not loaded / natural dims = 0) are skipped (no false positive).
    for ev in result.get("image_events", []):
        if ev.get("natural_w", 0) <= 0 or ev.get("natural_h", 0) <= 0:
            src = ev.get("src", "")
            pos = ev.get("zone_position", "unknown")
            tid = ev.get("zone_template_id", "?")
            fail_reasons.append(
                f"image failed to load in zone--{pos}: natural size is "
                f"{ev.get('natural_w')}x{ev.get('natural_h')} "
                f"(template={tid}, src={src})"
            )
            continue
        delta = ev.get("delta")
        if delta is None:
            continue
        if ev.get("allow_aspect_crop"):
            continue
        if abs(delta) > IMAGE_ASPECT_DELTA_TOL:
            n_ratio = ev.get("natural_ratio")
            r_ratio = ev.get("rendered_ratio")
            src = ev.get("src", "")
            pos = ev.get("zone_position", "unknown")
            tid = ev.get("zone_template_id", "?")
            fail_reasons.append(
                f"image aspect mismatch in zone--{pos}: "
                f"natural={n_ratio:.3f} rendered={r_ratio:.3f} delta={delta:+.3f} "
                f"(template={tid}, tol={IMAGE_ASPECT_DELTA_TOL}, src={src})"
            )

    # IMP-15 실행-2 (issue #46) — table_self_overflow aggregation.
    # Emit fail_reason only when (excess_x>TOL OR excess_y>TOL) AND wrapper_clipped_index is None.
    # The clipped-wrapper case is already accounted for by the clipped_inner fail_reason above;
    # element-identity dedup (clippedWrapperMap keyed by DOM node ref, NOT className) prevents
    # double-counting and—critically—prevents two same-class wrappers from masking each other.
    for ev in result.get("table_events", []):
        if ev.get("wrapper_clipped_index") is not None:
            continue
        excess_x = ev.get("excess_x", 0) or 0
        excess_y = ev.get("excess_y", 0) or 0
        if excess_x > TABLE_SCROLL_TOL_PX or excess_y > TABLE_SCROLL_TOL_PX:
            pos = ev.get("zone_position", "unknown")
            tid = ev.get("zone_template_id", "?")
            fail_reasons.append(
                f"table self-overflow in zone--{pos}: "
                f"excess {excess_y}px vert / {excess_x}px horiz "
                f"(content {ev.get('scrollWidth')}x{ev.get('scrollHeight')} vs "
                f"container {ev.get('clientWidth')}x{ev.get('clientHeight')}, "
                f"template={tid}, tol={TABLE_SCROLL_TOL_PX})"
            )

    result["passed"] = len(fail_reasons) == 0
    result["fail_reasons"] = fail_reasons
    result["presentation_measurements"] = _build_presentation_fit_report(
        overflow=result,
        override_zone_geometries=None,
    )["zones"]
    return result


def _recommended_geometry_for_overflow(
    geom: dict,
    *,
    overflow_px: int,
    axis: str,
) -> dict:
    """Return a suggestion only; never mutate the user's manual geometry."""
    out = dict(geom or {})
    if axis == "x":
        current = float(out.get("w") or 0.0)
        out["w"] = round(min(1.0, current + overflow_px / max(SLIDE_BODY_WIDTH, 1)), 4)
    else:
        current = float(out.get("h") or 0.0)
        out["h"] = round(min(1.0, current + overflow_px / max(SLIDE_BODY_HEIGHT, 1)), 4)
    return out


def _build_presentation_fit_report(
    *,
    overflow: dict,
    override_zone_geometries: Optional[dict[str, dict]] = None,
) -> dict:
    """T28.5 deterministic presentation-fit measurement/report.

    This is an honesty/reporting layer. It records measured fit data and manual
    geometry warnings; it does not resize zones, change frames, shrink fonts, or
    move text into popups by itself.
    """
    manual_geoms = (
        override_zone_geometries
        if isinstance(override_zone_geometries, dict)
        else {}
    )
    zones: list[dict] = []
    for z in overflow.get("zones") or []:
        pos = str(z.get("position") or "unknown")
        available_h = int(round(float(z.get("clientHeight") or 0)))
        available_w = int(round(float(z.get("clientWidth") or 0)))
        scroll_h = int(round(float(z.get("scrollHeight") or available_h)))
        scroll_w = int(round(float(z.get("scrollWidth") or available_w)))
        inner_overflow_y = max(
            [int(round(float(c.get("excess_y") or 0))) for c in z.get("clipped_inner", [])]
            or [0]
        )
        inner_overflow_x = max(
            [int(round(float(c.get("excess_x") or 0))) for c in z.get("clipped_inner", [])]
            or [0]
        )
        overflow_y = max(int(round(float(z.get("excess_y") or 0))), inner_overflow_y)
        overflow_x = max(int(round(float(z.get("excess_x") or 0))), inner_overflow_x)
        required_h = max(scroll_h, available_h + overflow_y) if overflow_y else scroll_h
        required_w = max(scroll_w, available_w + overflow_x) if overflow_x else scroll_w
        manual = pos in manual_geoms
        rec = {
            "position": pos,
            "template_id": z.get("template_id"),
            "required_height": required_h,
            "available_height": available_h,
            "overflow_px": overflow_y,
            "underflow_px": max(0, available_h - required_h),
            "required_width": required_w,
            "available_width": available_w,
            "overflow_x_px": overflow_x,
            "underflow_x_px": max(0, available_w - required_w),
            "inner_clipped": bool(z.get("clipped_inner")),
            "manual_geometry_applied": manual,
            "auto_fit_suggestion_available": bool(manual and (overflow_y > 0 or overflow_x > 0)),
        }
        if rec["auto_fit_suggestion_available"]:
            axis = "x" if overflow_x > overflow_y else "y"
            rec["recommended_geometry"] = _recommended_geometry_for_overflow(
                manual_geoms.get(pos) or {},
                overflow_px=max(overflow_x, overflow_y),
                axis=axis,
            )
        zones.append(rec)

    passed = bool(overflow.get("passed", False)) and not any(
        z.get("overflow_px", 0) > 0 or z.get("overflow_x_px", 0) > 0
        for z in zones
    )
    return {
        "passed": passed,
        "status": "presentation_ready" if passed else "presentation_not_ready",
        "zones": zones,
        "manual_geometry_policy": "respect_and_warn",
        "font_policy": "no_font_shrink",
        "line_height_compression_min_ratio": T28_5_LINE_HEIGHT_COMPRESSION_MIN_RATIO,
        "popup_text_coverage_required": True,
        "deterministic_popup_selection_required": True,
    }


def write_overflow_error(run_dir: Path, overflow: dict) -> Path:
    error_data = {
        "stage": "visual_runtime_check",
        "reason": "Visual runtime contract 위반 — slide / slide-body / zone overflow / clipping.",
        "fail_reasons": overflow.get("fail_reasons", []),
        "details": overflow,
    }
    err_path = run_dir / "error.json"
    err_path.write_text(json.dumps(error_data, ensure_ascii=False, indent=2), encoding="utf-8")
    return err_path


# ─── Debug.json (single slide + zones[]) ───────────────────────


def _is_empty_shell_unit(u: CompositionUnit) -> bool:
    """IMP-87 u1 — true when a CompositionUnit is the IMP-30 u4 empty-shell
    placeholder (frame_template_id="__empty__" / label="empty_shell" /
    merge_type="empty_shell").

    Used by compute_slide_status to redefine `full_mdx_coverage` over
    rendered content units only: an empty-shell unit attaches the aligned
    section_ids to a ``__empty__`` frame for layout purposes, but the slide
    surface carries no MDX content for those sections. Counting it as
    coverage would violate feedback_artifact_status_naming (overall /
    coverage must reflect actual content state, not pipeline completion).

    The three markers are checked as independent OR-branches so a
    CompositionUnit synthesised by any of the IMP-30 u4 entry points
    (phase A / phase B / e2e) is classified consistently.
    """
    if getattr(u, "frame_template_id", None) == "__empty__":
        return True
    if getattr(u, "label", None) == "empty_shell":
        return True
    if getattr(u, "merge_type", None) == "empty_shell":
        return True
    return False


def _final_status_html_class(overall: str) -> str:
    """IMP-87 u3 — map ``overall`` enum string → CSS class for the step20
    final_status.html dashboard.

    EMPTY_SHELL_NO_CONTENT MUST resolve to ``"fail"`` (red) so the Case B
    honesty defect (Stage 1 mdx05) surfaces in the same colour band as visual
    failures and regressions, not the legacy ``"partial"`` amber band. The
    explicit check runs BEFORE the legacy substring-based mapping because
    the literal ``"EMPTY_SHELL_NO_CONTENT"`` contains neither ``"PASS"`` nor
    ``"FAIL"`` / ``"REGRESSION"`` and would otherwise default to
    ``"partial"`` (Stage 2 axis A5 lock).

    All other enums preserve pre-IMP-87 substring semantics so the legacy
    PASS / RENDERED_WITH_VISUAL_REGRESSION / PARTIAL_COVERAGE / etc. paths
    keep the colour they had before u3.
    """
    if overall == "EMPTY_SHELL_NO_CONTENT":
        return "fail"
    if "PASS" in overall:
        return "pass"
    if "FAIL" in overall or "REGRESSION" in overall:
        return "fail"
    return "partial"


def _is_blocked_overall(overall: str) -> bool:
    """IMP-87 u3 — true iff ``overall`` warrants a BLOCKED CLI exit
    (returncode 1) independent of the visual_check / full_mdx_coverage axes.

    Currently the single blocked enum is EMPTY_SHELL_NO_CONTENT (Stage 1
    mdx05 Case B). The CLI consults this helper BEFORE the legacy
    visual_fail / partial_coverage branches so a content-empty placeholder
    slide that happens to pass Selenium overflow checks (no content → no
    overflow) cannot silently return a content-empty artifact without an
    exit signal (Stage 2 axis A4 lock).
    """
    return overall == "EMPTY_SHELL_NO_CONTENT"


def _strip_html_to_visible_text(html: str) -> str:
    html = re.sub(r"(?is)<script.*?</script>", "\n", html or "")
    html = re.sub(r"(?is)<style.*?</style>", "\n", html)
    html = re.sub(r"(?is)<[^>]+>", "\n", html)
    return html


def _compact_render_text(text: str) -> str:
    return re.sub(r"[^0-9A-Za-z가-힣]+", "", normalize_text_atom(text or ""))


def _compute_rendered_text_coverage(
    *,
    slide_title: str,
    slide_footer: Optional[str],
    sections: list[MdxSection],
    rendered_html: str,
    max_items: int = 20,
) -> dict:
    source_parts: list[str] = []
    if slide_title:
        source_parts.append(slide_title)
    for section in sections:
        if section.title:
            source_parts.append(section.title)
        if section.raw_content:
            source_parts.append(section.raw_content)
    if slide_footer:
        source_parts.append(slide_footer)
    source_atoms = extract_text_atoms("\n\n".join(source_parts))
    rendered_atoms = extract_text_atoms(_strip_html_to_visible_text(rendered_html))
    rendered_compact = _compact_render_text(" ".join(a.normalized for a in rendered_atoms))
    missing_atoms = [
        atom for atom in source_atoms
        if _compact_render_text(atom.normalized)
        and _compact_render_text(atom.normalized) not in rendered_compact
    ]
    return {
        "passed": len(missing_atoms) == 0,
        "source_atoms_count": len(source_atoms),
        "rendered_atoms_count": len(rendered_atoms),
        "missing_atoms_count": len(missing_atoms),
        "missing_atoms_sample": [
            {
                "kind": atom.kind,
                "line_no": atom.line_no,
                "text": atom.text,
                "normalized": atom.normalized,
            }
            for atom in missing_atoms[:max_items]
        ],
    }


_FORBIDDEN_RENDERED_SYNTAX_RE = re.compile(
    r"(?:onMouse[A-Za-z]*|e\.currentTarget|style=\{\{|boxShadow\s*:|borderRadius\s*:|"
    r"fontSize\s*:|fontWeight\s*:|background\s*:\s*['\"]?#|width\s*:\s*['\"]?100%|"
    r"cursor\s*:|transition\s*:|padding[A-Za-z]*\s*:|margin[A-Za-z]*\s*:|"
    r"font[A-Za-z]*\s*:|display\s*:|flex[A-Za-z]*\s*:|align[A-Za-z]*\s*:|"
    r"justify[A-Za-z]*\s*:|}}\s*>)",
    re.IGNORECASE,
)


def _detect_forbidden_rendered_syntax(rendered_html: str, *, max_items: int = 20) -> dict:
    visible_lines = _strip_html_to_visible_text(rendered_html).splitlines()
    samples: list[dict] = []
    count = 0
    for line_no, line in enumerate(visible_lines, start=1):
        compact = line.strip()
        if not compact:
            continue
        if _FORBIDDEN_RENDERED_SYNTAX_RE.search(compact):
            count += 1
            if len(samples) < max_items:
                samples.append({"line_no": line_no, "text": compact[:220]})
    return {
        "passed": count == 0,
        "forbidden_syntax_count": count,
        "forbidden_syntax_sample": samples,
    }


def _extract_final_zone_positions(rendered_html: str) -> list[str]:
    positions: list[str] = []
    for match in re.finditer(r"<div\b[^>]*>", rendered_html or "", flags=re.IGNORECASE):
        tag = match.group(0)
        class_match = re.search(r'\bclass="([^"]*)"', tag, flags=re.IGNORECASE)
        if not class_match:
            continue
        classes = set(class_match.group(1).split())
        if "zone" not in classes:
            continue
        position_match = re.search(r'\bdata-zone-position="([^"]+)"', tag, flags=re.IGNORECASE)
        if position_match:
            positions.append(position_match.group(1))
    return positions


def _compute_applied_render_consistency(
    *,
    layout_preset: str,
    rendered_html: str,
    debug_zones: list[dict],
) -> dict:
    """T19b (#98): verify selected frames/layout survived to final render."""
    expected_positions: list[str] = []
    try:
        expected_positions = _parse_css_areas(LAYOUT_PRESETS[layout_preset]["css_areas"])[1]
    except Exception:
        expected_positions = []
    final_positions = _extract_final_zone_positions(rendered_html)

    frame_mismatches: list[dict] = []
    for zone in debug_zones:
        selected = (
            zone.get("v4_template_id")
            or zone.get("v4_rank1_template_id")
            or zone.get("contract_id")
        )
        actual = (
            zone.get("render_template_id")
            or zone.get("template_id")
            or zone.get("contract_id")
        )
        if selected and actual and selected != actual:
            frame_mismatches.append({
                "position": zone.get("position"),
                "source_section_ids": list(zone.get("source_section_ids") or []),
                "selected_template_id": selected,
                "actual_template_id": actual,
                "reason": zone.get("verbatim_builder_reason")
                or zone.get("ai_redistribute_reason")
                or zone.get("skipped_reason")
                or "selected_frame_not_applied",
            })

    layout_mismatch = bool(expected_positions and final_positions and final_positions != expected_positions)
    failures: list[str] = []
    if frame_mismatches:
        failures.append("selected_frame_not_applied")
    if layout_mismatch:
        failures.append("final_layout_positions_mismatch")

    return {
        "passed": not failures,
        "failures": failures,
        "layout_preset": layout_preset,
        "expected_positions": expected_positions,
        "final_positions": final_positions,
        "frame_mismatch_count": len(frame_mismatches),
        "frame_mismatches": frame_mismatches,
    }


# ── issue #15 — density/readability gate (Gitea #98 추천 1·2) ──────────
# 기계 PASS vs 사람 "빽빽함" 판정의 간극(false-positive, MDX02 최악)을 잡는
# 결정론적 신호. B5 slot metrics(#20) 부재 상태의 v0 휴리스틱:
#   px_per_line = (zone 측정 높이 − 오버헤드) / 카드당 최대 추정 라인 수
# 임계값은 mdx 01~05 실측 캘리브레이션 (2026-07-06, 사람 판정과 정렬):
#   mdx03 105.8(ready) / mdx05 50~64(density 문제 아님) / mdx02 40~44(cramped)
#   / mdx04 top 37(dense) / mdx01 bottom-right 11.5("bottom comparison dense")
_DENSITY_PX_PER_LINE_DENSE = 16.0   # 물리적 한 줄 높이 미만 — 확실한 과밀
_DENSITY_PX_PER_LINE_TIGHT = 45.0   # 사람 판정 cramped 경계 (mdx02 44.0 포함)
_DENSITY_ZONE_OVERHEAD_PX = 56      # zone title + padding 추정 오버헤드
_CARD_SLOT_RE = re.compile(r".+?_(\d+)_(label|body)$")


def _estimate_max_card_lines(slot_payload: dict) -> int:
    """카드/행 단위 최대 라인 수 추정 (휴리스틱 v0 — payload 결정론).

    인식 형태: ``{prefix}_{n}_{label|body}`` repeat 슬롯, ``pillars`` 등
    list-of-dict 컬럼, str 값의 ``<br>`` 라인. B5 marker(#20) 성숙 시 실측
    DOM 라인으로 대체 예정.
    """
    if not isinstance(slot_payload, dict):
        return 0
    cards: dict[str, int] = {}
    for key, value in slot_payload.items():
        if key in ("title", "_slot_count") or not value:
            continue
        m = _CARD_SLOT_RE.match(str(key))
        if m:
            n_lines = (
                len(value) if isinstance(value, list)
                else str(value).count("<br>") + 1
            )
            cards[m.group(1)] = cards.get(m.group(1), 0) + n_lines
            continue
        if isinstance(value, list) and value and isinstance(value[0], dict):
            for i, card in enumerate(value):
                n = 0
                for v in card.values():
                    if not v:
                        continue
                    n += len(v) if isinstance(v, list) else str(v).count("<br>") + 1
                cards[f"{key}[{i}]"] = n
    return max(cards.values()) if cards else 0


def _compute_density_gate(zones_data: list[dict], overflow: dict) -> dict:
    """issue #15 — per-zone 밀도 판정 (dense / tight / comfortable).

    측정 높이(run_overflow_check 의 clientHeight)와 payload 라인 추정만 사용
    — 렌더/최종 HTML 에 영향 없는 순수 리포팅 계층 (slide_status 전용).
    라인 추정 불가 zone(카드 패턴 아님)은 판정 제외 (not_measurable).
    """
    heights = {
        str(z.get("position")): z.get("clientHeight")
        for z in (overflow.get("zones") or [])
        if isinstance(z, dict)
    }
    zone_records: list[dict] = []
    worst = "comfortable"
    for zone in zones_data or []:
        pos = str(zone.get("position"))
        payload = zone.get("slot_payload") or {}
        max_lines = _estimate_max_card_lines(payload)
        height = heights.get(pos)
        rec: dict = {
            "position": pos,
            "template_id": zone.get("template_id"),
            "estimated_max_lines": max_lines,
        }
        if not max_lines or not isinstance(height, (int, float)) or height <= 0:
            rec["verdict"] = "not_measurable"
            zone_records.append(rec)
            continue
        px_per_line = (float(height) - _DENSITY_ZONE_OVERHEAD_PX) / max_lines
        rec["zone_height_px"] = int(height)
        rec["px_per_line"] = round(px_per_line, 1)
        if px_per_line < _DENSITY_PX_PER_LINE_DENSE:
            rec["verdict"] = "dense"
            worst = "dense"
        elif px_per_line < _DENSITY_PX_PER_LINE_TIGHT:
            rec["verdict"] = "tight"
            if worst != "dense":
                worst = "tight"
        else:
            rec["verdict"] = "comfortable"
        zone_records.append(rec)
    return {
        "passed": worst == "comfortable",
        "worst_verdict": worst,
        "zones": zone_records,
        "thresholds": {
            "dense_px_per_line": _DENSITY_PX_PER_LINE_DENSE,
            "tight_px_per_line": _DENSITY_PX_PER_LINE_TIGHT,
            "zone_overhead_px": _DENSITY_ZONE_OVERHEAD_PX,
        },
        "heuristic": "payload_line_estimate_v0",
    }


def _apply_quality_gate_downgrades(
    slide_status: dict,
    *,
    rendered_text_coverage: dict,
    forbidden_rendered_syntax: dict,
    applied_render_consistency: dict,
) -> None:
    """issue #17 — quality gate 3종의 overall 강등을 단일 헬퍼로.

    두 slide_status 조립 경로(최초 + T28.5d popup 승격 후 재계산)가 동일한
    강등 규칙을 공유해야 한다 — 재계산 경로에 이 블록이 없어서 텍스트
    손실(rendered_text_coverage fail)이 overall=PASS 로 통과하는 버그가
    있었음 (mdx05 05-2 F23 렌더 1-atom 손실 실측).
    """
    if not rendered_text_coverage.get("passed"):
        slide_status.setdefault("quality_gate_failures", []).append(
            "rendered_text_coverage_missing"
        )
        slide_status.setdefault("visual_fail_reasons", []).append(
            "rendered_text_coverage_missing: "
            f"{rendered_text_coverage.get('missing_atoms_count')} source text atom(s) "
            "not visible in final.html"
        )
        if slide_status.get("overall") == "PASS":
            slide_status["overall"] = "PARTIAL_COVERAGE"

    if not forbidden_rendered_syntax.get("passed"):
        slide_status.setdefault("quality_gate_failures", []).append(
            "forbidden_rendered_syntax"
        )
        slide_status.setdefault("visual_fail_reasons", []).append(
            "forbidden_rendered_syntax: "
            f"{forbidden_rendered_syntax.get('forbidden_syntax_count')} JSX/CSS/code "
            "fragment(s) visible in final.html"
        )
        if slide_status.get("overall") == "PASS":
            slide_status["overall"] = "PARTIAL_COVERAGE"

    if not applied_render_consistency.get("passed"):
        for failure in applied_render_consistency.get("failures") or []:
            slide_status.setdefault("quality_gate_failures", []).append(failure)
        if applied_render_consistency.get("frame_mismatch_count"):
            slide_status.setdefault("visual_fail_reasons", []).append(
                "selected_frame_not_applied: "
                f"{applied_render_consistency.get('frame_mismatch_count')} zone(s) "
                "rendered with a different template than Step 6 selected"
            )
        if "final_layout_positions_mismatch" in (applied_render_consistency.get("failures") or []):
            slide_status.setdefault("visual_fail_reasons", []).append(
                "final_layout_positions_mismatch: "
                f"expected {applied_render_consistency.get('expected_positions')} but "
                f"final.html has {applied_render_consistency.get('final_positions')}"
            )
        if slide_status.get("overall") == "PASS":
            slide_status["overall"] = "PARTIAL_COVERAGE"


def _compute_design_readiness(
    *,
    units: list[CompositionUnit],
    rendered_text_coverage: dict,
    applied_render_consistency: dict,
    density_gate: Optional[dict] = None,
) -> dict:
    """T20f: separate technical PASS from design-readiness.

    A slide can render and preserve all source atoms while still being a design
    review case, for example when it uses a generic fallback frame or only
    ai_adaptation_required catalog candidates.
    """
    failures: list[dict] = []
    warnings: list[dict] = []

    if not rendered_text_coverage.get("passed"):
        failures.append({
            "code": "source_text_missing",
            "detail": f"{rendered_text_coverage.get('missing_atoms_count')} source atom(s) missing",
        })
    if not applied_render_consistency.get("passed"):
        failures.append({
            "code": "selected_render_contract_failed",
            "detail": ",".join(applied_render_consistency.get("failures") or []),
        })

    for unit in units:
        section_ids = list(getattr(unit, "source_section_ids", []) or [])
        selection_path = getattr(unit, "selection_path", None)
        label = getattr(unit, "label", None)
        candidates = list(getattr(unit, "v4_candidates", []) or [])
        candidate_statuses = [
            getattr(c, "candidate_status", None)
            for c in candidates
            if getattr(c, "candidate_status", None)
        ]
        record_base = {
            "section_ids": section_ids,
            "template_id": getattr(unit, "frame_template_id", None),
            "selection_path": selection_path,
            "label": label,
        }
        if selection_path in {
            "generic_fallback",
            "no_drop_fallback",
            "task14_parent_no_drop_fallback",
        }:
            failures.append({
                **record_base,
                "code": "generic_fallback_frame",
                "detail": "Rendered via fallback frame; semantic catalog/matching quality is not ready.",
            })
        if not candidates:
            failures.append({
                **record_base,
                "code": "no_frame_candidate_pool",
                "detail": "No candidate pool is available for user correction.",
            })
        elif candidate_statuses and all(s != "auto_renderable" for s in candidate_statuses):
            warnings.append({
                **record_base,
                "code": "candidate_pool_requires_adaptation",
                "detail": "Candidate pool exists, but every candidate requires adaptation or review.",
            })
        if label == "reject":
            warnings.append({
                **record_base,
                "code": "selected_reject_candidate",
                "detail": "The rendered frame is selected from a reject/provisional path.",
            })

    # issue #15 — density 신호 통합 (#98 추천 1: readiness 신호 통합).
    # 사람 판정 캘리브레이션상 dense/tight 모두 needs_review 계층 (not_ready
    # 아님 — mdx01 bottom 11.5px/line 도 사람 판정은 needs_review 였음).
    if density_gate and not density_gate.get("passed", True):
        for z in density_gate.get("zones") or []:
            if z.get("verdict") in ("dense", "tight"):
                warnings.append({
                    "position": z.get("position"),
                    "template_id": z.get("template_id"),
                    "code": f"density_{z['verdict']}",
                    "detail": (
                        f"{z.get('px_per_line')}px/line "
                        f"(max {z.get('estimated_max_lines')} lines/card in "
                        f"{z.get('zone_height_px')}px zone) — 카드 과밀 신호"
                    ),
                })

    status = "ready"
    if warnings:
        status = "needs_review"
    if failures:
        status = "not_ready"
    return {
        "passed": not failures,
        "status": status,
        "failure_count": len(failures),
        "warning_count": len(warnings),
        "failures": failures,
        "warnings": warnings,
        "policy": (
            "Technical PASS means rendered + no visual overflow + full source coverage. "
            "Design readiness additionally requires semantic frame selection and a usable candidate pool."
        ),
    }


def _build_t28_5c_reselection_trace(
    *,
    units: list[CompositionUnit],
    debug_zones: list[dict],
    layout_preset: str,
    router_decision: dict,
    presentation_fit: dict,
    override_zone_geometries: Optional[dict[str, dict]] = None,
) -> dict:
    """Trace-only T28.5c abort -> frame/layout re-selection evaluation."""
    actions = list(router_decision.get("proposed_actions_summary") or [])
    manual_positions = set((override_zone_geometries or {}).keys())
    overflow_zones = [
        z for z in (presentation_fit.get("zones") or [])
        if int(z.get("overflow_px") or 0) > 0 or int(z.get("overflow_x_px") or 0) > 0
    ]
    triggered = "abort" in actions and bool(overflow_zones)

    def _unit_for_source_ids(source_ids: list[str]):
        source_tuple = tuple(source_ids or [])
        for unit in units:
            if tuple(getattr(unit, "source_section_ids", []) or []) == source_tuple:
                return unit
        source_set = set(source_ids or [])
        for unit in units:
            if source_set and source_set.intersection(getattr(unit, "source_section_ids", []) or []):
                return unit
        return None

    zones: list[dict] = []
    zone_debug_by_pos = {z.get("position"): z for z in debug_zones}
    for fit_zone in overflow_zones:
        pos = fit_zone.get("position")
        dz = zone_debug_by_pos.get(pos) or {}
        source_ids = list(dz.get("source_section_ids") or [])
        unit = _unit_for_source_ids(source_ids)
        current_template = (
            dz.get("render_template_id")
            or dz.get("template_id")
            or dz.get("contract_id")
            or getattr(unit, "frame_template_id", None)
        )
        candidates: list[dict] = []
        for cand in list(getattr(unit, "v4_candidates", []) or []):
            template_id = getattr(cand, "template_id", None)
            label = getattr(cand, "label", None)
            candidate_status = getattr(cand, "candidate_status", None)
            coverage_state = (
                getattr(cand, "coverage_state", None)
                or _candidate_coverage_state(
                    candidate_status,
                    label=label,
                    catalog_registered=get_contract(template_id) is not None,
                    selection_path=getattr(cand, "selection_path", None),
                )
            )
            eligible = bool(
                template_id
                and template_id != current_template
                and coverage_state in {"covered_native", "covered_via_expand"}
                and get_contract(template_id) is not None
            )
            candidates.append({
                "template_id": template_id,
                "frame_id": getattr(cand, "frame_id", None),
                "label": label,
                "candidate_status": candidate_status,
                "coverage_state": coverage_state,
                "eligible": eligible,
                "ineligible_reason": None if eligible else (
                    "current_template"
                    if template_id == current_template else
                    "coverage_state_not_auto_selectable"
                    if coverage_state not in {"covered_native", "covered_via_expand"} else
                    "catalog_unregistered"
                ),
            })
        eligible_candidates = [c for c in candidates if c.get("eligible")]
        zones.append({
            "position": pos,
            "source_section_ids": source_ids,
            "current_template_id": current_template,
            "overflow_px": fit_zone.get("overflow_px"),
            "overflow_x_px": fit_zone.get("overflow_x_px"),
            "manual_geometry_applied": pos in manual_positions,
            "frame_reselection_evaluated": bool(unit),
            "candidate_count": len(candidates),
            "eligible_candidate_count": len(eligible_candidates),
            "selected_candidate": eligible_candidates[0] if eligible_candidates else None,
            "candidates": candidates[:6],
        })

    if 1 <= len(units) <= 4:
        layout_candidates = list(select_layout_candidates(len(units)) or [])
    else:
        layout_candidates = []
    layout_alternatives = [p for p in layout_candidates if p != layout_preset]
    layout_allowed = bool(layout_alternatives) and not manual_positions
    return {
        "triggered": triggered,
        "policy": "trace_only_no_silent_swap",
        "router_actions": actions,
        "current_layout_preset": layout_preset,
        "manual_zone_positions": sorted(manual_positions),
        "zones": zones,
        "layout_reselection": {
            "evaluated": triggered,
            "allowed": layout_allowed,
            "blocked_reason": "manual_geometry_present" if manual_positions else None,
            "candidate_presets": layout_candidates,
            "eligible_presets": layout_alternatives if layout_allowed else [],
        },
        "next_step": (
            "frame_or_layout_candidate_available"
            if any(z.get("selected_candidate") for z in zones) or layout_allowed
            else "escalate_to_t28_5d_or_presentation_not_ready"
        ),
    }


def _unit_for_t28_5_source_ids(
    units: list[CompositionUnit],
    source_ids: list[str],
):
    source_tuple = tuple(source_ids or [])
    for unit in units:
        if tuple(getattr(unit, "source_section_ids", []) or []) == source_tuple:
            return unit
    source_set = set(source_ids or [])
    for unit in units:
        if source_set and source_set.intersection(getattr(unit, "source_section_ids", []) or []):
            return unit
    return None


# issue #16 — salvage 정책 차단 터미널 집합. 이 터미널에 도달했다는 것은
# 자동 fit 레버(cross_zone/glue)가 소진되고 나머지(font/layout)는 정책
# 잠금이라는 뜻 — popup escalation 이 유일한 무손실 자동 레버.
_SALVAGE_POLICY_BLOCKED_TERMINALS = frozenset({
    "layout_adjust_blocked_no_silent_layout_mutation",
    "font_step_compression_blocked_no_font_shrink",
})


def _build_t28_5d_popup_targets(
    *,
    units: list[CompositionUnit],
    presentation_reselection: dict,
    retry_trace: Optional[dict] = None,
) -> dict:
    """Select T28.5d popup targets from the T28.5c terminal trace.

    This is a deterministic bridge from T28.5c's abort/no-recovery signal
    onto the existing popup/details chain. It does not mutate units or HTML.

    issue #16 — 두 번째 트리거 추가: salvage cascade 가 정책 차단 터미널로
    소진됐는데 overflow 가 남은 zone (기존 트리거의
    ``eligible_candidate_count == 0`` 조건은 이 분기에 미적용 — 그 후보들은
    사용자 수동 경로일 뿐 자동 소비가 T19d 로 금지돼 있어, 후보가 있다는
    이유로 무손실 popup 레버를 막으면 mdx04 처럼 영구 미발화가 됨).
    """
    layout_reselection = presentation_reselection.get("layout_reselection") or {}
    terminal = (
        presentation_reselection.get("triggered") is True
        and presentation_reselection.get("next_step")
        == "escalate_to_t28_5d_or_presentation_not_ready"
        and layout_reselection.get("allowed") is False
    )
    salvage_exhausted = bool(
        retry_trace
        and retry_trace.get("salvage_attempted")
        and not retry_trace.get("salvage_passed")
        and retry_trace.get("salvage_terminal_action")
        in _SALVAGE_POLICY_BLOCKED_TERMINALS
    )
    targets: list[dict] = []
    seen_positions: set = set()
    for zone in presentation_reselection.get("zones") or []:
        overflow_px = int(zone.get("overflow_px") or 0)
        overflow_x_px = int(zone.get("overflow_x_px") or 0)
        if overflow_px <= 0 and overflow_x_px <= 0:
            continue
        trigger_reason = None
        if terminal and int(zone.get("eligible_candidate_count") or 0) == 0:
            trigger_reason = "t28_5c_terminal_no_candidates"
        elif salvage_exhausted:
            trigger_reason = "salvage_exhausted_overflow_pressure"
        if trigger_reason is None:
            continue
        source_ids = list(zone.get("source_section_ids") or [])
        unit = _unit_for_t28_5_source_ids(units, source_ids)
        if unit is None or zone.get("position") in seen_positions:
            continue
        seen_positions.add(zone.get("position"))
        targets.append({
            "position": zone.get("position"),
            "source_section_ids": source_ids,
            "current_template_id": zone.get("current_template_id"),
            "overflow_px": overflow_px,
            "overflow_x_px": overflow_x_px,
            "manual_geometry_applied": bool(zone.get("manual_geometry_applied")),
            "trigger_reason": trigger_reason,
        })
    return {
        "triggered": bool(targets),
        "policy": "t28_5d_second_popup_pass_reuse_existing_chain",
        "terminal_next_step": presentation_reselection.get("next_step"),
        "salvage_exhausted_trigger": salvage_exhausted,
        "target_count": len(targets),
        "targets": targets,
    }


# issue #16 — popup escalation 시 zone 본문을 예산 내로 트리밍하는 헬퍼.
# 기존 구조 결함: slide_base 는 partial_html 을 그대로 렌더하고 <details>
# 를 덧붙이기만 함 (preview_text 는 렌더 경로 어디에서도 미소비) — popup
# 이 높이를 전혀 줄이지 못해 escalation 이 항상 실패했음. 트리밍된 라인의
# 전문은 popup body(raw_content 원문)에 보존 — 자세히보기 원칙, 텍스트
# 무손실 (rendered_text_coverage 는 details 내부 텍스트도 집계).
_POPUP_TRIM_LINE_PX = 18  # 13px font × 1.4lh 근사 (보수적)


def _trim_slot_payload_for_overflow(
    slot_payload: dict, overflow_px: int,
) -> tuple[dict, int]:
    """list-값 슬롯에서 overflow 해소에 필요한 만큼 라인을 제거 (긴 슬롯부터
    round-robin, 슬롯당 최소 1라인 유지, label/title/_slot_count 무접촉).

    두 형태를 지원:
      - top-level list-of-str 슬롯 (예: ``pill_1_body``)
      - list-of-dict 컬럼 내부의 list-of-str 값 (예: ``pillars[i].lines`` —
        f13b three_parallel_requirements 계열)

    Returns (새 payload, 제거 라인 수). 라인 경계에서만 자름 — 라인 내부
    truncate 금지 (IMP-35 preview 철학과 동일).
    """
    if overflow_px <= 0 or not isinstance(slot_payload, dict):
        return dict(slot_payload or {}), 0
    need = int(overflow_px // _POPUP_TRIM_LINE_PX) + 1
    new_payload = copy.deepcopy(slot_payload)

    def _is_lines(v) -> bool:
        # 라인 리스트 두 형태: list-of-str (verbatim builder 계열) 또는
        # list-of-{text,...} line-object (f13b pillars.sections.text_lines 계열)
        if not isinstance(v, list) or not v:
            return False
        if all(isinstance(x, str) for x in v):
            return True
        return all(
            isinstance(x, dict) and isinstance(x.get("text"), str) for x in v
        )

    # trimmable pool: (container_dict, key) 참조를 재귀 수집 (깊이 제한 5)
    pools: list[tuple[dict, str]] = []

    def _collect(node, depth: int = 0) -> None:
        if depth > 5:
            return
        if isinstance(node, dict):
            for k, v in node.items():
                if _is_lines(v):
                    pools.append((node, k))
                elif isinstance(v, (dict, list)):
                    _collect(v, depth + 1)
        elif isinstance(node, list):
            for item in node:
                if isinstance(item, (dict, list)):
                    _collect(item, depth + 1)

    _collect(new_payload)
    trimmed = 0
    while trimmed < need:
        candidates = [(c, k) for c, k in pools if len(c[k]) > 1]
        if not candidates:
            break
        container, key = max(candidates, key=lambda p: len(p[0][p[1]]))
        container[key] = container[key][:-1]
        trimmed += 1
    return new_payload, trimmed


def _t28_5d_popup_escalation_plan(target: dict) -> dict:
    return {
        "action": "details_popup_escalation",
        "feasible": True,
        "stub": False,
        "category": "abort_overflow_no_recovery",
        "mapping_source": "T28.5d second popup pass",
        "needs_split_decision": False,
        "rationale": (
            "T28.5c found abort+overflow with no eligible frame/layout recovery; "
            "reuse existing popup/details renderer without AI or text rewrite."
        ),
        "target": {
            "position": target.get("position"),
            "source_section_ids": list(target.get("source_section_ids") or []),
            "overflow_px": target.get("overflow_px"),
            "overflow_x_px": target.get("overflow_x_px"),
        },
    }


def _attempt_t28_5d_popup_second_pass(
    *,
    units: list[CompositionUnit],
    zones_data: list[dict],
    presentation_reselection: dict,
    run_dir: Path,
    out_path: Path,
    slide_title: str,
    slide_footer: Optional[str],
    layout_preset: str,
    layout_css: dict,
    gap_px: int,
    postprocess_html=None,
    render_func=render_slide,
    overflow_check_func=run_overflow_check,
    retry_trace: Optional[dict] = None,
) -> dict:
    """T28.5d: re-render final.html with existing popup/details payloads.

    The pass is intentionally after T28.5c because its trigger depends on
    presentation_fit + reselection trace. It is not marker-only: a candidate is
    rendered, measured, and promoted only if the visual check passes.

    issue #16 — 두 가지 확장:
      1. salvage 정책 차단 소진 시에도 트리거 (retry_trace 기반)
      2. 대상 zone 의 본문 라인을 overflow 예산만큼 트리밍 — popup 이 실제로
         높이를 줄이도록 (전문은 popup body 에 보존, 무손실)
    """
    target_plan = _build_t28_5d_popup_targets(
        units=units,
        presentation_reselection=presentation_reselection,
        retry_trace=retry_trace,
    )
    result = {
        "triggered": target_plan["triggered"],
        "attempted": False,
        "passed": False,
        "promoted": False,
        "policy": "recorded_promote_only_after_candidate_visual_pass",
        "target_plan": target_plan,
        "candidate_path": None,
        "post_popup_overflow": None,
        "failure_reason": None,
    }
    if not target_plan["triggered"]:
        result["failure_reason"] = "no_t28_5d_popup_targets"
        return result

    zones_candidate = [dict(zone) for zone in zones_data]
    zone_by_position = {zone.get("position"): zone for zone in zones_candidate}
    old_unit_attrs = []
    applied_targets: list[dict] = []
    for target in target_plan["targets"]:
        unit = _unit_for_t28_5_source_ids(units, list(target.get("source_section_ids") or []))
        zone = zone_by_position.get(target.get("position"))
        if unit is None or zone is None:
            continue
        old_unit_attrs.append((
            unit,
            getattr(unit, "has_popup", None),
            getattr(unit, "popup_escalation_plan", None),
        ))
        plan = _t28_5d_popup_escalation_plan(target)
        setattr(unit, "has_popup", True)
        setattr(unit, "popup_escalation_plan", plan)
        popup_payload = compose_zone_popup_payload(
            unit,
            float(zone.get("min_height_px") or 0.0),
        )
        zone.update(popup_payload)
        zone["t28_5d_popup_escalated"] = True
        # issue #16 — 본문 라인 트리밍으로 높이 실감소 (전문은 popup body).
        trimmed_payload, trimmed_lines = _trim_slot_payload_for_overflow(
            zone.get("slot_payload") or {},
            int(target.get("overflow_px") or 0),
        )
        if trimmed_lines:
            zone["slot_payload"] = trimmed_payload
            zone["popup_trimmed_lines"] = trimmed_lines
        applied_targets.append({
            **target,
            "popup_plan": plan,
            "trimmed_lines": trimmed_lines,
        })

    if not applied_targets:
        result["failure_reason"] = "target_units_or_zones_not_found"
        return result

    # issue #16 — 측정 피드백 트림 루프 (최대 3회). 라인당 px 추정치(18)가
    # frame 마다 다를 수 있어, 후보 렌더의 측정 잔여 excess 로 추가 트림.
    candidate_path = run_dir / "t28_5d_popup_candidate.html"
    target_positions = {t.get("position") for t in applied_targets}
    candidate_html = ""
    candidate_overflow: dict = {}
    passed = False
    for _trim_round in range(3):
        candidate_html = render_func(
            slide_title,
            slide_footer,
            zones_candidate,
            layout_preset,
            layout_css,
            gap_px=gap_px,
        )
        if postprocess_html is not None:
            candidate_html = postprocess_html(candidate_html)
        candidate_path.write_text(candidate_html, encoding="utf-8")
        candidate_overflow = overflow_check_func(candidate_path)
        passed = bool(candidate_overflow.get("passed", False))
        if passed:
            break
        # 대상 zone 의 측정 잔여 excess 산출 → 추가 트림
        extra_trimmed = 0
        for oz in candidate_overflow.get("zones") or []:
            pos = oz.get("position")
            if pos not in target_positions:
                continue
            remaining = max(
                int(round(float(oz.get("excess_y") or 0))),
                max(
                    [int(round(float(c.get("excess_y") or 0)))
                     for c in oz.get("clipped_inner") or []] or [0]
                ),
            )
            if remaining <= 0:
                continue
            zone = zone_by_position.get(pos)
            if zone is None:
                continue
            more_payload, more = _trim_slot_payload_for_overflow(
                zone.get("slot_payload") or {}, remaining,
            )
            if more:
                zone["slot_payload"] = more_payload
                zone["popup_trimmed_lines"] = (
                    int(zone.get("popup_trimmed_lines") or 0) + more
                )
                for t in applied_targets:
                    if t.get("position") == pos:
                        t["trimmed_lines"] = (
                            int(t.get("trimmed_lines") or 0) + more
                        )
                extra_trimmed += more
        if extra_trimmed == 0:
            break  # 더 줄일 여지 없음 — 정직 실패
    result.update({
        "attempted": True,
        "passed": passed,
        "candidate_path": (
            _rel_to_project(candidate_path)
            if candidate_path.is_absolute() else str(candidate_path)
        ),
        "post_popup_overflow": candidate_overflow,
        "applied_targets": applied_targets,
    })
    if passed:
        out_path.write_text(candidate_html, encoding="utf-8")
        zones_data[:] = zones_candidate
        result["promoted"] = True
        return result

    result["failure_reason"] = (
        candidate_overflow.get("fail_reasons")
        or "T28.5d popup candidate visual check failed"
    )
    for unit, old_has_popup, old_plan in old_unit_attrs:
        if old_has_popup is None:
            if hasattr(unit, "has_popup"):
                delattr(unit, "has_popup")
        else:
            setattr(unit, "has_popup", old_has_popup)
        if old_plan is None:
            if hasattr(unit, "popup_escalation_plan"):
                delattr(unit, "popup_escalation_plan")
        else:
            setattr(unit, "popup_escalation_plan", old_plan)
    return result


def _postprocess_phase_z2_rendered_html(
    html: str,
    *,
    stage0_normalized_assets: dict,
    override_image_overrides: Optional[dict],
    override_slide_css: Optional[str],
    mdx_source_text: str,
) -> str:
    """Apply the existing post-render HTML transforms used by final.html."""
    from src.image_id_stamper import (
        build_image_overrides_style,
        inject_image_overrides_style,
        stamp_user_content_images,
    )

    user_content_image_srcs = [
        (entry.get("path") or entry.get("src") or "")
        for entry in (stage0_normalized_assets.get("images") or [])
        if isinstance(entry, dict)
    ]
    html, stamped_image_ids = stamp_user_content_images(
        html,
        sources=user_content_image_srcs,
    )
    if override_image_overrides:
        image_overrides_css = build_image_overrides_style(
            override_image_overrides,
            stamped_image_ids,
        )
        if image_overrides_css:
            html = inject_image_overrides_style(html, image_overrides_css)

    effective_slide_css = override_slide_css
    if effective_slide_css is None:
        effective_slide_css = _resolve_slide_css_from_frontmatter(mdx_source_text)
    if effective_slide_css:
        from src.slide_css_injector import inject_slide_css
        html = inject_slide_css(html, effective_slide_css)
    return html


def compute_slide_status(sections: list[MdxSection],
                         units: list[CompositionUnit],
                         comp_debug: dict,
                         overflow: dict,
                         adapter_needed_units: Optional[list[dict]] = None,
                         debug_zones: Optional[list[dict]] = None) -> dict:
    """Slide 산출물의 정확한 상태 계산 — 자동 파이프라인 결과 보고.

    축 :
      - rendered            : final.html 이 디스크에 쓰였는가
      - visual_check_passed : Selenium per-zone overflow / clipping 통과 여부
      - full_mdx_coverage   : aligned 된 모든 section_id 가 어떤 selected unit 에 의해 covered
      - adapter_needed_count : mapper FitError 로 자동 렌더 못 한 unit 수 (별 review 개념 X — 자동 실패 보고)
      - content_truncated_count : builder 가 truncate 한 zone 수 (informational)
      - provisional_first_render_count : IMP-30 first-render invariant 로 합성된 unit 수
                                         (u1 V4Match synthesis / u3 last-resort fill /
                                         u4 empty-shell — needs user/AI adaptation 신호)

    overall enum :
      EMPTY_SHELL_NO_CONTENT                  — IMP-87 u2 : every selected unit is an
                                                IMP-30 u4 empty-shell placeholder
                                                (no content-rendered units). Takes
                                                precedence over the 4-way ladder below
                                                because such a slide can technically
                                                pass Selenium overflow checks but
                                                carries no MDX content.
      PASS                                    — visual OK + full coverage + adapter_needed=0
      RENDERED_WITH_VISUAL_REGRESSION         — full coverage 이지만 visual fail
      PARTIAL_COVERAGE                        — 일부 section 필터됨, 렌더된 부분만 visual OK
      PARTIAL_COVERAGE_WITH_VISUAL_REGRESSION — 둘 다
      (adapter_needed > 0 시 status note 추가, overall 은 위 enum 사용)
      (IMP-30 u6 : provisional_first_render_count 도 qualifier 일 뿐, overall enum 변경 X.
       Stage 1 Q3 + Codex #10 D4 lock.)
    """
    aligned_ids = [s.section_id for s in sections]
    # IMP-87 u1 — split coverage into legacy display vs honesty axis.
    # ``covered`` (legacy, preserved for downstream display / IMP-05 / IMP-06
    # readers) still tracks every section attached to any selected unit.
    # ``content_covered`` is the new honesty axis: only non-empty-shell units
    # count as "rendered with content". Sections attached solely to an
    # empty-shell placeholder (IMP-30 u4 frame_template_id="__empty__")
    # are routed into ``filtered_section_ids`` so an EMPTY-SHELL-only slide
    # cannot inherit full_mdx_coverage=True (Case B honesty defect lock,
    # Stage 1 anchor c53722ad).
    covered: set = set()
    content_covered: set = set()
    for u in units:
        covered.update(u.source_section_ids)
        if not _is_empty_shell_unit(u):
            content_covered.update(u.source_section_ids)
    filtered_ids = sorted(set(aligned_ids) - content_covered)
    full_coverage = len(filtered_ids) == 0
    visual_passed = bool(overflow.get("passed", False))
    adapter_needed_units = list(adapter_needed_units or [])
    debug_zone_list = list(debug_zones or [])

    # #98 Task 3 — render honesty axis. A section is not "content rendered"
    # merely because it was attached to a selected CompositionUnit. Mapper
    # FitError branches intentionally keep the grid shape by emitting
    # template_id="__empty__" + slot_payload={}, but those zones carry no
    # visible MDX content and must not let full_mdx_coverage/PASS survive.
    render_blocked_section_ids: set[str] = set()
    render_blocked_units: list[dict] = []
    _render_block_seen: set[tuple] = set()

    def _record_render_block(
        *,
        source_section_ids,
        position=None,
        template_id=None,
        reason: str,
        source: str,
    ) -> None:
        sids = [str(sid) for sid in (source_section_ids or []) if sid]
        if not sids:
            return
        render_blocked_section_ids.update(sids)
        key = (position, tuple(sids), template_id)
        if key in _render_block_seen:
            return
        _render_block_seen.add(key)
        render_blocked_units.append({
            "position": position,
            "source_section_ids": sids,
            "template_id": template_id,
            "reason": reason,
            "source": source,
        })

    for rec in adapter_needed_units:
        _record_render_block(
            source_section_ids=rec.get("source_section_ids"),
            position=rec.get("position"),
            template_id=rec.get("template_id"),
            reason=rec.get("reason") or "adapter_needed",
            source="adapter_needed_units",
        )

    for z in debug_zone_list:
        mapper_type = z.get("mapper_type")
        template_id = (
            z.get("v4_template_id")
            or z.get("template_id")
            or z.get("contract_id")
        )
        slot_payload_keys = z.get("slot_payload_keys")
        reason = None
        if z.get("adapter_needed") is True or mapper_type == "adapter_needed":
            reason = z.get("skipped_reason") or "adapter_needed"
        elif mapper_type in {"empty", "empty_shell"}:
            reason = z.get("skipped_reason") or mapper_type
        elif template_id == "__empty__":
            reason = z.get("skipped_reason") or "empty_template"
        elif slot_payload_keys == []:
            reason = "empty_slot_payload"
        if reason:
            _record_render_block(
                source_section_ids=z.get("source_section_ids"),
                position=z.get("position"),
                template_id=template_id,
                reason=reason,
                source="debug_zones",
            )

    if render_blocked_section_ids:
        content_covered.difference_update(render_blocked_section_ids)
        filtered_ids = sorted(set(aligned_ids) - content_covered)
        full_coverage = len(filtered_ids) == 0

    # IMP-87 u2 — Additive empty/content accounting (used by the overall enum
    # precedence block below and surfaced on the return dict for downstream
    # introspection). ``content_rendered_section_ids`` mirrors the new honesty
    # axis (content_covered) at the surface level so consumers can ask "how
    # much real MDX content actually rendered" without re-running the helper.
    # ``empty_shell_section_ids`` exposes the placeholder counterpart for the
    # same reason. Both pairs are purely additive — no existing field is
    # removed or repurposed (legacy ``covered_section_ids`` display semantics
    # locked by u1).
    empty_shell_units_list = [u for u in units if _is_empty_shell_unit(u)]
    content_units_list = [
        u for u in units
        if not _is_empty_shell_unit(u)
        and any(
            sid not in render_blocked_section_ids
            for sid in (getattr(u, "source_section_ids", None) or [])
        )
    ]
    empty_shell_section_ids = sorted({
        sid
        for u in empty_shell_units_list
        for sid in (u.source_section_ids or [])
    })
    content_rendered_section_ids = sorted(content_covered)

    content_truncated = []
    fallback_selections = []
    for z in debug_zone_list:
        if z.get("fallback_used"):
            fallback_selections.append({
                "position": z["position"],
                "source_section_ids": z["source_section_ids"],
                "template_id": z["v4_template_id"],
                "selected_v4_rank": z.get("v4_selected_rank"),
                "selection_path": z.get("selection_path"),
                "fallback_reason": z.get("fallback_reason"),
            })
        tc = z.get("content_truncated_count")
        if tc:
            content_truncated.append({
                "position": z["position"],
                "source_section_ids": z["source_section_ids"],
                "template_id": z["v4_template_id"],
                "truncated_count": tc,
            })

    # 필터된 section 의 사유 (auto pipeline 결정 트레이스 — review 개념 X)
    filtered_section_reasons = []
    for c in comp_debug.get("candidates_summary", []):
        if c.get("selection_state") == "selected":
            continue
        cand_ids = c.get("source_section_ids", [])
        if any(sid in filtered_ids for sid in cand_ids):
            filtered_section_reasons.append({
                "section_ids": cand_ids,
                "merge_type": c.get("merge_type"),
                "template_id": c.get("template_id"),
                "v4_label": c.get("label"),
                "phase_z_status": c.get("phase_z_status"),
                "score": c.get("score"),
                "selection_state": c.get("selection_state"),  # filtered_status / filtered_weak / filtered_lost
                "filter_reasons": c.get("filter_reasons", []),
            })

    # IMP-06 blocker-fix (Codex #10 Catch O schema + Codex #16 coverage invariant) —
    # surface override-uncovered sections as additive list entries in
    # `filtered_section_reasons` and ensure `filtered_section_ids` includes them
    # so coverage does not silently miss sections that were dropped by an explicit
    # zone-section override.
    v4_fb_summary = comp_debug.get("v4_fallback_summary", {}) or {}
    section_assignment_summary = comp_debug.get("section_assignment_summary") or {}
    section_assignment_uncovered_ids: list[str] = list(
        section_assignment_summary.get("uncovered_section_ids") or []
    )
    if section_assignment_uncovered_ids:
        # Codex #16 invariant : final filtered_section_ids must contain the
        # override-uncovered ids even if they were originally "covered" by the
        # pre-override auto plan. full_coverage must be re-evaluated too so
        # Step 20 `overall` enum reflects the post-override reality.
        for sid in section_assignment_uncovered_ids:
            if sid not in filtered_ids:
                filtered_ids.append(sid)
        filtered_ids = sorted(set(filtered_ids))
        full_coverage = len(filtered_ids) == 0
        # Append a separate list entry per override-uncovered section so existing
        # readers of filtered_section_reasons (list-shaped) keep working.
        plan_by_position = {
            (p.get("position") or ""): p
            for p in (comp_debug.get("section_assignment_plan") or [])
        }
        for sid in section_assignment_uncovered_ids:
            # Find the position whose plan entry recorded this uncovered id.
            source_position = None
            for pos, entry in plan_by_position.items():
                if sid in (entry.get("uncovered_section_ids") or []):
                    source_position = pos
                    break
            filtered_section_reasons.append({
                "section_ids": [sid],
                "merge_type": None,
                "template_id": None,
                "v4_label": None,
                "phase_z_status": None,
                "score": None,
                "selection_state": "section_assignment_override_uncovered",
                "filter_reasons": ["section_assignment_override_uncovered"],
                "source": "section_assignment_override",
                "position": source_position,
            })

    for block in render_blocked_units:
        block_ids = list(block.get("source_section_ids") or [])
        if not any(sid in filtered_ids for sid in block_ids):
            continue
        filtered_section_reasons.append({
            "section_ids": block_ids,
            "merge_type": None,
            "template_id": block.get("template_id"),
            "v4_label": None,
            "phase_z_status": None,
            "score": None,
            "selection_state": "render_blocked",
            "filter_reasons": [block.get("reason") or "render_blocked"],
            "source": block.get("source") or "render_status",
            "position": block.get("position"),
        })

    # IMP-87 u2 — EMPTY_SHELL_NO_CONTENT precedence over the legacy 4-way
    # ladder (Stage 2 axis A3). If the slide has aligned MDX sections but
    # every selected unit is an IMP-30 u4 empty-shell placeholder (zero
    # content units selected, at least one empty-shell unit selected), the
    # visible artifact carries no real content — ``overall`` MUST report
    # EMPTY_SHELL_NO_CONTENT so the u3 CLI exit / final_status.html styling
    # can branch on it. The check runs before the visual/coverage ladder
    # because a content-empty placeholder slide can technically pass Selenium
    # overflow checks (no content → no overflow); without this precedence the
    # ladder would mislabel it PASS (Stage 1 mdx05 Case B honesty defect).
    is_empty_shell_only = (
        len(aligned_ids) > 0
        and len(empty_shell_units_list) > 0
        and len(content_units_list) == 0
    )
    if is_empty_shell_only:
        overall = "EMPTY_SHELL_NO_CONTENT"
    elif full_coverage and visual_passed:
        overall = "PASS"
    elif full_coverage and not visual_passed:
        overall = "RENDERED_WITH_VISUAL_REGRESSION"
    elif not full_coverage and visual_passed:
        overall = "PARTIAL_COVERAGE"
    else:
        overall = "PARTIAL_COVERAGE_WITH_VISUAL_REGRESSION"

    # IMP-05 L3 (Codex #10 D4 / #17 idea F / Claude #21 idea J) — Step 20 qualifier fields.
    # Additive only — top-level overall enum unchanged. Defensive defaults so non-fallback
    # paths (empty v4_fallback_summary) do not crash and report 0 / [] cleanly.
    _v4_fb_summary = comp_debug.get("v4_fallback_summary", {}) or {}
    _fallback_selection_count = _v4_fb_summary.get("fallback_selection_count", 0)
    _selection_paths = _v4_fb_summary.get("selection_paths", [])

    # IMP-30 u6 — Step 20 additive qualifier fields for the first-render invariant.
    # provisional_first_render_count = number of selected units whose .provisional
    # flag is True (set by u1 V4Match synthesis → u2 CompositionUnit propagation,
    # u3 last-resort fill, or u4 empty-shell synthesis). The list mirrors the shape
    # of fallback_selections / adapter_needed_units for symmetry. Top-level overall
    # enum stays unchanged per IMP-05 Codex #10 D4 + Stage 1 Q3 decision: this
    # signal is a qualifier, not a new failure class. Defensive getattr keeps the
    # function safe when units come from legacy code paths predating u2.
    provisional_first_render_units: list[dict] = []
    for u in units:
        if not getattr(u, "provisional", False):
            continue
        provisional_first_render_units.append({
            "source_section_ids": list(getattr(u, "source_section_ids", []) or []),
            "phase_z_status": getattr(u, "phase_z_status", None),
            "frame_template_id": getattr(u, "frame_template_id", None),
            "frame_id": getattr(u, "frame_id", None),
            "label": getattr(u, "label", None),
            "selection_path": getattr(u, "selection_path", None),
            "fallback_reason": getattr(u, "fallback_reason", None),
            "v4_rank": getattr(u, "v4_rank", None),
        })

    return {
        "rendered": True,
        "visual_check_passed": visual_passed,
        "full_mdx_coverage": full_coverage,
        "aligned_section_ids": aligned_ids,
        "covered_section_ids": sorted(covered),
        # IMP-87 u2 — additive empty/content accounting (overall enum precedence above).
        "content_rendered_section_ids": content_rendered_section_ids,
        "content_rendered_unit_count": len(content_units_list),
        "empty_shell_section_ids": empty_shell_section_ids,
        "empty_shell_unit_count": len(empty_shell_units_list),
        "filtered_section_ids": filtered_ids,
        "filtered_section_reasons": filtered_section_reasons,
        "selection_path": "fallback_used" if fallback_selections else "rank_1",
        "fallback_used": bool(fallback_selections),
        "fallback_selections": fallback_selections,
        # IMP-05 L3 qualifier fields — grouped near existing fallback fields for readability.
        "fallback_selection_count": _fallback_selection_count,
        "selection_paths": _selection_paths,
        "visual_fail_reasons": list(overflow.get("fail_reasons") or []),
        "adapter_needed_count": len(adapter_needed_units),
        "adapter_needed_units": adapter_needed_units,
        "render_blocked_section_ids": sorted(render_blocked_section_ids),
        "render_blocked_units": render_blocked_units,
        "render_blocked_unit_count": len(render_blocked_units),
        "content_truncated_count": len(content_truncated),
        "content_truncated_units": content_truncated,
        # IMP-30 u6 — additive provisional qualifiers (overall enum unchanged).
        "provisional_first_render_count": len(provisional_first_render_units),
        "provisional_first_render_units": provisional_first_render_units,
        "overall": overall,
        "note": (
            "자동 파이프라인 결과 보고. review/UI 개념 X. final.html 파일명 != PASS 의미. "
            "overall == PASS 는 visual OK + full coverage + adapter_needed=0 일 때만. "
            "adapter_needed_count > 0 = mapper 가 contract 와 안 맞아 자동 렌더 못 한 zone 존재. "
            "content_truncated_count > 0 = builder 가 truncate 한 zone 존재 (rendered 됐지만 일부 콘텐츠 손실). "
            "provisional_first_render_count > 0 = IMP-30 first-render invariant 가 작동한 unit 존재 "
            "(empty_shell / chain_exhausted_provisional / 등 — needs user/AI adaptation)."
        ),
    }


# ─── Per-step artifact write (locked schema) ────────────────────
# 모든 step JSON 공통 필드: step_num, step_name, step_status,
#   pipeline_path_connected, input, output, note, data
# 사용자 lock — 한 슬라이드 결과물 고치지 말고 시스템 layer 박기 (오답노트 #2)


def _write_step_artifact(
    run_dir: Path,
    step_num: int,
    name: str,
    data,
    *,
    step_status: str = "done",
    pipeline_path_connected: bool = True,
    inputs: Optional[list[str]] = None,
    outputs: Optional[list[str]] = None,
    note: Optional[str] = None,
) -> Path:
    """Write per-step JSON artifact to {run_dir}/steps/step{NN}_{name}.json.

    Locked schema (사용자 직설):
      step_num, step_name, step_status, pipeline_path_connected,
      input, output, note, data.
    Status values: 'done' / 'partial' / 'trace-only' / 'future' / 'failed'.
    """
    steps_dir = run_dir / "steps"
    steps_dir.mkdir(exist_ok=True)
    fname = f"step{step_num:02d}_{name}.json"
    fpath = steps_dir / fname
    payload = {
        "step_num": step_num,
        "step_name": name,
        "step_status": step_status,
        "pipeline_path_connected": pipeline_path_connected,
        "input": inputs or [],
        "output": outputs or [fname],
        "note": note,
        "data": data,
    }
    fpath.write_text(
        json.dumps(payload, ensure_ascii=False, indent=2, default=str),
        encoding="utf-8",
    )
    return fpath


# IMP-43 (#72) u3 — Step 6 reuse snapshot sidecar writer.
#
# Scope (u3 only — Stage 2 unit split):
#   * Writes ``run_dir/_reuse_snapshot.json`` *after* the Step 6 artifact.
#   * JSON-only (per Stage 2 guardrail — pickle forbidden); schema +
#     ``build_snapshot`` live in u2 (``src.phase_z2_reuse_snapshot``).
#   * Write failure WARNS and CONTINUES — the snapshot is an OPTIONAL
#     sidecar; absence means future ``--reuse-from`` (u4) will fail
#     closed when it cannot find / load the file. The main pipeline
#     run must not abort on snapshot write failure.
#   * Returns the run_dir-relative path (``"_reuse_snapshot.json"``) on
#     success, ``None`` on failure. The caller stamps the returned value
#     (or the constant when known ahead of time) into the Step 6 artifact.
def _write_reuse_snapshot(
    run_dir: Path,
    *,
    mdx_source_text: str,
    slide_title: Optional[str],
    slide_footer: Optional[str],
    sections: list,
    stage0_adapter_diagnostics: Optional[dict],
    stage0_normalized_assets: Optional[dict],
    v4_evidence: list,
    layout_preset_pre_override: Optional[str],
    units: list,
    comp_debug: Optional[dict],
    v4_fallback_traces: Optional[dict],
    ai_preflight: Optional[dict],
) -> Optional[str]:
    try:
        mdx_sha256 = hashlib.sha256(mdx_source_text.encode("utf-8")).hexdigest()
        snapshot = build_snapshot(
            mdx_sha256=mdx_sha256,
            slide_title=slide_title,
            slide_footer=slide_footer,
            sections=sections,
            stage0_adapter_diagnostics=stage0_adapter_diagnostics,
            stage0_normalized_assets=stage0_normalized_assets,
            v4_evidence=v4_evidence,
            layout_preset_pre_override=layout_preset_pre_override,
            units=units,
            comp_debug=comp_debug,
            v4_fallback_traces=v4_fallback_traces,
            ai_preflight=ai_preflight,
        )
        fpath = run_dir / SNAPSHOT_FILENAME
        fpath.write_text(
            json.dumps(snapshot, ensure_ascii=False, indent=2),
            encoding="utf-8",
        )
        return SNAPSHOT_FILENAME
    except Exception as exc:
        print(
            f"  [reuse-snapshot] WARN — failed to write {SNAPSHOT_FILENAME} "
            f"(reason={type(exc).__name__}: {exc}); --reuse-from will not be "
            f"available from this run.",
            file=sys.stderr,
        )
        return None


# IMP-43 (#72) u4 — --reuse-from copy + restore + entry helpers.
#
# Scope (u4 only — Stage 2 unit split):
#   * Pure path resolution / file copy / snapshot load+validate /
#     section + unit rehydration / marker writing.
#   * NO edits to ``run_phase_z2_mvp1`` body — the kwarg threading and
#     the entry-point branch that invokes these helpers land in u5.
#   * NO sys.exit(2) translation — helpers RAISE
#     (FileNotFoundError / SnapshotValidationError / OSError); u4b adds
#     the stderr + exit-code-2 wrapper, the prev_run_dir == new_run_dir
#     accidental-write guard, and the mdx_sha256 mismatch surface
#     fingerprint.
#
# Restore contract (Stage 2 boundary): Step 0/1/2/5/6 artifacts +
# ``_reuse_snapshot.json``. Step numbers 3 / 4 are deliberately absent
# — the pipeline DOES write ``step03_content_objects.json`` and
# ``step04_internal_composition.json`` AFTER the Step 6 artifact and
# BEFORE the Step 7 artifact (see ``_write_step_artifact`` call sites
# for ``run_dir, 3`` and ``run_dir, 4`` above the ``run_dir, 7`` call
# in this file), but both are emitted with
# ``step_status="trace-only"`` and ``pipeline_path_connected=False``:
# they are diagnostic projections derived from the Step 6
# ``debug_zones`` snapshot, not deterministic inputs that Step 7+
# consume. Restoring them is unnecessary because downstream code
# reads ``debug_zones`` directly (rehydrated from the snapshot), and
# copying trace-only files would muddle the boundary audit. Stage 2
# boundary lock = pipeline-path-connected pre-Step 7 artifacts only.

_REUSE_STEP_ARTIFACTS: tuple[str, ...] = (
    "step00_preconditions.json",
    "step01_mdx_upload.json",
    "step01_mdx_source.md",
    "step02_normalized.json",
    "step05_v4_evidence.json",
    "step06_composition_plan.json",
)

REUSE_MARKER_FILENAME = "_reuse_marker.json"


def _resolve_reuse_from_prev_run_dir(reuse_from: str) -> Path:
    """Resolve ``--reuse-from PREV_RUN_ID`` to its ``phase_z2`` run_dir.

    Pure path computation — does NOT check existence. u4b adds the
    fail-closed prev-run-missing translation around this helper.
    """
    return RUNS_DIR / reuse_from / "phase_z2"


def _copy_reuse_artifacts_from_prev_run(
    prev_run_dir: Path, new_run_dir: Path
) -> dict[str, str]:
    """Copy Step 0/1/2/5/6 artifacts + ``_reuse_snapshot.json`` into new_run_dir.

    Returns ``{artifact_name: new_run_dir-relative_path}`` for all
    copied files. Raises ``FileNotFoundError`` when any required
    artifact is missing in ``prev_run_dir`` (u4b translates to exit 2).
    """
    new_steps = new_run_dir / "steps"
    new_steps.mkdir(parents=True, exist_ok=True)
    copied: dict[str, str] = {}
    for fname in _REUSE_STEP_ARTIFACTS:
        src = prev_run_dir / "steps" / fname
        if not src.exists():
            raise FileNotFoundError(
                f"reuse artifact missing in prev_run_dir: steps/{fname} "
                f"(expected at {src})"
            )
        shutil.copyfile(src, new_steps / fname)
        copied[fname] = f"steps/{fname}"
    snap_src = prev_run_dir / SNAPSHOT_FILENAME
    if not snap_src.exists():
        raise FileNotFoundError(
            f"reuse snapshot missing in prev_run_dir: {SNAPSHOT_FILENAME} "
            f"(expected at {snap_src})"
        )
    shutil.copyfile(snap_src, new_run_dir / SNAPSHOT_FILENAME)
    copied[SNAPSHOT_FILENAME] = SNAPSHOT_FILENAME
    return copied


def _load_and_validate_reuse_snapshot(
    new_run_dir: Path, *, mdx_source_text: str
) -> dict:
    """Load + validate the reuse snapshot already copied into ``new_run_dir``.

    Computes the expected ``mdx_sha256`` from ``mdx_source_text`` UTF-8
    bytes — same derivation as ``_write_reuse_snapshot`` so the
    integrity check is symmetric. Delegates structural validation to
    u2's ``validate_snapshot``; that raises
    ``SnapshotValidationError`` (subclass of ``ValueError``) on
    schema_version mismatch, mdx_sha256 mismatch, missing required
    keys, or malformed wrappers — u4b catches and translates.
    """
    from src.phase_z2_reuse_snapshot import validate_snapshot

    snap_path = new_run_dir / SNAPSHOT_FILENAME
    snapshot = json.loads(snap_path.read_text(encoding="utf-8"))
    expected_sha = hashlib.sha256(mdx_source_text.encode("utf-8")).hexdigest()
    validate_snapshot(snapshot, expected_mdx_sha256=expected_sha)
    return snapshot


@dataclass
class _RehydratedV4Candidate:
    """V4Match-shape duck type restored from snapshot ``v4_candidates``.

    Exposes the 6-attribute contract that the reuse path's downstream
    consumers read off ``unit.v4_candidates`` entries:
      * template_id / frame_id / frame_number / confidence / label —
        read by ``_apply_frame_override_to_unit`` (frame swap).
      * v4_rank — read by ``_build_application_plan_unit`` (Step 9
        payload, ``data.application_plan.zones[i].v4_candidates[j]``).
        Default ``None`` keeps the dataclass safe to construct from
        legacy snapshots that pre-date the u4 fix where the snapshot
        serializer did not persist per-candidate rank.
    Kept local — circular-dep-free; the production ``V4Match`` dataclass
    additionally carries section_id / selection_path / fallback_reason /
    provisional that the reuse boundary deliberately does not require.
    """
    template_id: str
    frame_id: str
    frame_number: int
    confidence: float
    label: str
    v4_rank: Optional[int] = None


def _rehydrate_mdx_sections_from_snapshot(snapshot: dict) -> list:
    """Rebuild ``list[MdxSection]`` from snapshot ``sections`` wrapper.

    Mirrors the ``serialize_section`` field list (u2 source of truth).
    Returns a Python list of ``MdxSection`` dataclass instances so the
    Step 7+ pipeline code that does ``[s.section_id for s in sections]``
    keeps byte-for-byte behavior.
    """
    entries = snapshot["sections"]["value"]
    return [
        MdxSection(
            section_id=e["section_id"],
            section_num=e["section_num"],
            title=e["title"],
            raw_content=e["raw_content"],
            heading_number=e.get("heading_number"),
            v4_alias_keys=list(e.get("v4_alias_keys") or []),
            sub_sections=list(e.get("sub_sections") or []),
        )
        for e in entries
    ]


def _rehydrate_composition_units_from_snapshot(snapshot: dict) -> list:
    """Rebuild ``list[CompositionUnit]`` from snapshot ``units`` wrapper.

    ``v4_candidates`` entries are restored as ``_RehydratedV4Candidate``
    instances so attribute access (``cand.template_id`` etc.) works
    end-to-end through ``_apply_frame_override_to_unit`` without
    serializing the production ``V4Match`` dataclass shape.

    Uses the ``src.phase_z2_composition`` import path to match
    line 4976 / 5125's local re-imports — the module is loaded under
    both ``phase_z2_composition`` and ``src.phase_z2_composition`` due
    to historical sys.path duality, so a top-level CompositionUnit
    reference would create a class-identity mismatch against tests and
    downstream code that imports via the ``src.`` path.
    """
    from src.phase_z2_composition import CompositionUnit as _CompositionUnit

    entries = snapshot["units"]["value"]
    units: list = []
    for e in entries:
        cands = [
            _RehydratedV4Candidate(
                template_id=c["template_id"],
                frame_id=c["frame_id"],
                frame_number=int(c["frame_number"]),
                confidence=float(c["confidence"]),
                label=c["label"],
                v4_rank=(
                    int(c["v4_rank"])
                    if c.get("v4_rank") is not None
                    else None
                ),
            )
            for c in (e.get("v4_candidates") or [])
        ]
        units.append(_CompositionUnit(
            source_section_ids=list(e["source_section_ids"]),
            merge_type=e["merge_type"],
            frame_template_id=e["frame_template_id"],
            frame_id=e["frame_id"],
            frame_number=int(e["frame_number"]),
            confidence=float(e["confidence"]),
            label=e["label"],
            phase_z_status=e["phase_z_status"],
            raw_content=e["raw_content"],
            title=e["title"],
            v4_rank=e.get("v4_rank"),
            selection_path=e.get("selection_path") or "rank_1",
            fallback_reason=e.get("fallback_reason"),
            score=float(e.get("score") or 0.0),
            rationale=dict(e.get("rationale") or {}),
            auto_selectable=bool(e.get("auto_selectable", True)),
            filter_reasons=list(e.get("filter_reasons") or []),
            notes=list(e.get("notes") or []),
            v4_candidates=cands,
            provisional=bool(e.get("provisional", False)),
        ))
    return units


REUSE_MARKER_SCHEMA_VERSION = 1


def _write_reuse_marker(
    new_run_dir: Path,
    *,
    prev_run_id: str,
    copied_artifacts: dict[str, str],
) -> Path:
    """Write ``_reuse_marker.json`` to ``new_run_dir`` for audit trail.

    Records prev_run_id, copied artifact map, the locked Step 0/1/2/5/6
    boundary, and ``resume_at_step=7``. Informational sidecar — absence
    does not break the reused run; presence lets operators trace which
    prev_run_id the reuse path was sourced from. u5 invokes this after
    a successful copy + restore.
    """
    marker = {
        "schema_version": REUSE_MARKER_SCHEMA_VERSION,
        "reuse_from_prev_run_id": prev_run_id,
        "snapshot_filename": SNAPSHOT_FILENAME,
        "copied_artifacts": dict(copied_artifacts),
        "boundary_steps": list(_REUSE_STEP_ARTIFACTS),
        "resume_at_step": 7,
        "note": (
            "IMP-43 (#72) u4 — this run was sourced from prev_run_id via "
            "--reuse-from. Steps 0/1/2/5/6 artifacts copied; Step 7+ "
            "re-executed in this run_dir."
        ),
    }
    fpath = new_run_dir / REUSE_MARKER_FILENAME
    fpath.write_text(
        json.dumps(marker, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )
    return fpath


# IMP-43 (#72) u4b — fail-closed wrapper around the u4 helpers.
#
# Scope (u4b only — Stage 2 unit split):
#   * Translate the u4 raises (FileNotFoundError, SnapshotValidationError,
#     json.JSONDecodeError, OSError) into the CLI fail-closed contract:
#     stderr message + ``sys.exit(2)``.
#   * Add the prev_run_dir == new_run_dir accidental-write guard BEFORE
#     any copy attempt — otherwise ``_copy_reuse_artifacts_from_prev_run``
#     would overwrite prev_run_dir's own step files with itself and
#     mutate the "read-only" reuse source.
#   * Add the missing-prev-run-dir surface so the user gets a clean
#     "run id not found" message instead of the raw FileNotFoundError
#     stack from inside _copy_reuse_artifacts_from_prev_run.
#   * Surface the mdx_sha256 mismatch as its OWN axis (distinct from
#     generic snapshot validation failures) so the operator can tell
#     "wrong --mdx-path for this prev_run_id" apart from "snapshot file
#     is broken".
#
# Out of scope: signature threading into ``run_phase_z2_mvp1`` (u5),
# the actual call site dispatch into Step 7+ (u5).
#
# Diagnostic format (factual-verification guardrail):
#   [error] --reuse-from fail-closed: <axis>
#     value: <repr>
#     path: <fs path / resource locator>
#     upstream: <where the value originated>
#     reason: <type>: <message>     (only when exc != None)
#
# axis vocabulary (closed enum — tests pin this set):
#   * prev_run_dir_missing
#   * prev_run_dir_equals_new_run_dir
#   * reuse_artifact_missing
#   * reuse_copy_os_error            # OSError != FileNotFoundError during copy
#                                    # (PermissionError, IsADirectoryError,
#                                    # OSError(errno.EXDEV), full-disk, etc.)
#   * snapshot_missing_after_copy
#   * snapshot_corrupt_json
#   * snapshot_read_os_error         # OSError != FileNotFoundError during
#                                    # snapshot read (permission denied,
#                                    # path-became-dir, lower-level IO)
#   * mdx_sha256_mismatch
#   * snapshot_validation_failed


REUSE_FAIL_CLOSED_AXES: frozenset[str] = frozenset({
    "prev_run_dir_missing",
    "prev_run_dir_equals_new_run_dir",
    "reuse_artifact_missing",
    "reuse_copy_os_error",
    "snapshot_missing_after_copy",
    "snapshot_corrupt_json",
    "snapshot_read_os_error",
    "mdx_sha256_mismatch",
    "snapshot_validation_failed",
})


def _abort_reuse_from(
    *,
    axis: str,
    value: Any,
    path: str,
    upstream: str,
    exc: Optional[BaseException] = None,
) -> "NoReturn":
    """Print provenance-tagged stderr message and ``sys.exit(2)``.

    All four `value+path+upstream+axis` fields are mandatory so the
    operator can pinpoint the failed precondition without grepping the
    pipeline source. ``exc`` (when supplied) adds the underlying type
    + message — useful for ``json.JSONDecodeError`` line/col info or
    OSError errno.
    """
    if axis not in REUSE_FAIL_CLOSED_AXES:
        raise AssertionError(
            f"_abort_reuse_from: unknown axis {axis!r} "
            f"(expected one of {sorted(REUSE_FAIL_CLOSED_AXES)})"
        )
    lines = [
        f"[error] --reuse-from fail-closed: {axis}",
        f"  value: {value!r}",
        f"  path: {path}",
        f"  upstream: {upstream}",
    ]
    if exc is not None:
        lines.append(f"  reason: {type(exc).__name__}: {exc}")
    print("\n".join(lines), file=sys.stderr)
    sys.exit(2)


def _paths_equivalent(a: Path, b: Path) -> bool:
    """Return True when ``a`` and ``b`` resolve to the same filesystem
    location, falling back to lexical equality when ``a`` doesn't
    exist yet (Path.resolve(strict=False) still normalizes case + sep
    on Windows + collapses ``..`` segments).
    """
    try:
        return a.resolve(strict=False) == b.resolve(strict=False)
    except (OSError, RuntimeError):
        return a == b


def execute_reuse_from_or_fail_closed(
    *,
    reuse_from: str,
    new_run_dir: Path,
    mdx_source_text: str,
) -> tuple[Path, dict[str, str], dict]:
    """Orchestrate u4 helpers under the u4b fail-closed contract.

    Returns ``(prev_run_dir, copied_artifacts, snapshot)`` on success.
    Calls ``sys.exit(2)`` on any of the seven fail-closed axes; does
    NOT return in that case.

    The caller (u5, into ``run_phase_z2_mvp1``) does NOT need to wrap
    this in its own try/except — every reachable failure inside this
    function terminates the process directly.
    """
    from src.phase_z2_reuse_snapshot import SnapshotValidationError

    prev_run_dir = _resolve_reuse_from_prev_run_dir(reuse_from)

    # Guard 1: prev_run_dir must exist.
    if not prev_run_dir.exists():
        _abort_reuse_from(
            axis="prev_run_dir_missing",
            value=reuse_from,
            path=str(prev_run_dir),
            upstream="--reuse-from CLI argument",
        )

    # Guard 2: prev_run_dir must NOT be the same as new_run_dir.
    # Without this, the copy step would overwrite prev_run_dir's own
    # files with themselves and break the RO guarantee on the reuse
    # source. The check resolves both sides so a relative-vs-absolute
    # or symlinked collision still trips it.
    if _paths_equivalent(prev_run_dir, new_run_dir):
        _abort_reuse_from(
            axis="prev_run_dir_equals_new_run_dir",
            value=reuse_from,
            path=str(prev_run_dir),
            upstream=(
                "_resolve_reuse_from_prev_run_dir(reuse_from) == new_run_dir "
                "(would overwrite prev_run_dir during copy)"
            ),
        )

    # Copy step 0/1/2/5/6 + snapshot from prev_run_dir → new_run_dir.
    # FileNotFoundError MUST be caught before the bare OSError handler —
    # it is a subclass of OSError and the missing-artifact case has its
    # own dedicated axis.
    try:
        copied = _copy_reuse_artifacts_from_prev_run(prev_run_dir, new_run_dir)
    except FileNotFoundError as exc:
        _abort_reuse_from(
            axis="reuse_artifact_missing",
            value=str(exc),
            path=str(prev_run_dir),
            upstream=(
                "Step 0/1/2/5/6 deterministic artifacts + "
                f"{SNAPSHOT_FILENAME} under prev_run_dir/steps/"
            ),
            exc=exc,
        )
    except OSError as exc:
        # PermissionError, IsADirectoryError, OSError(errno.EXDEV) when
        # crossing filesystems with shutil.copyfile, disk-full, etc.
        # Without this branch the raw traceback would escape the wrapper
        # and contradict the docstring contract ("every reachable
        # failure inside this function terminates the process directly").
        _abort_reuse_from(
            axis="reuse_copy_os_error",
            value=str(exc),
            path=str(prev_run_dir),
            upstream=(
                "_copy_reuse_artifacts_from_prev_run "
                "(OSError != FileNotFoundError; shutil.copyfile or "
                "Path.mkdir surface)"
            ),
            exc=exc,
        )

    # Load + validate snapshot. Exception fan-out below mirrors the
    # u4 helper raise surface; each fail-closed axis is reported
    # separately so operators can tell the cases apart.
    # FileNotFoundError MUST be caught before the bare OSError handler.
    try:
        snapshot = _load_and_validate_reuse_snapshot(
            new_run_dir, mdx_source_text=mdx_source_text,
        )
    except FileNotFoundError as exc:
        # Should not happen — copy step would have failed first — but
        # left explicit to make the contract symmetric.
        _abort_reuse_from(
            axis="snapshot_missing_after_copy",
            value=str(exc),
            path=str(new_run_dir / SNAPSHOT_FILENAME),
            upstream="_copy_reuse_artifacts_from_prev_run side effect",
            exc=exc,
        )
    except json.JSONDecodeError as exc:
        _abort_reuse_from(
            axis="snapshot_corrupt_json",
            value=str(exc),
            path=str(new_run_dir / SNAPSHOT_FILENAME),
            upstream=f"json.loads({SNAPSHOT_FILENAME})",
            exc=exc,
        )
    except OSError as exc:
        # Permission denied on the copied snapshot, snap_path turned out
        # to be a directory, lower-level IO error. JSONDecodeError is
        # ValueError (independent of OSError) so order with that branch
        # does not matter; this branch only needs to follow FNF.
        _abort_reuse_from(
            axis="snapshot_read_os_error",
            value=str(exc),
            path=str(new_run_dir / SNAPSHOT_FILENAME),
            upstream=(
                "_load_and_validate_reuse_snapshot "
                "(OSError != FileNotFoundError; Path.read_text surface)"
            ),
            exc=exc,
        )
    except SnapshotValidationError as exc:
        msg = str(exc)
        if "mdx_sha256 mismatch" in msg:
            _abort_reuse_from(
                axis="mdx_sha256_mismatch",
                value=msg,
                path=str(new_run_dir / SNAPSHOT_FILENAME),
                upstream=(
                    "sha256(mdx_source_text) vs "
                    f"{SNAPSHOT_FILENAME}#/mdx_sha256"
                ),
                exc=exc,
            )
        else:
            _abort_reuse_from(
                axis="snapshot_validation_failed",
                value=msg,
                path=str(new_run_dir / SNAPSHOT_FILENAME),
                upstream="src.phase_z2_reuse_snapshot.validate_snapshot",
                exc=exc,
            )

    return prev_run_dir, copied, snapshot


def _write_step_html(
    run_dir: Path,
    step_num: int,
    name: str,
    title: str,
    body_html: str,
    *,
    step_status: str = "done",
    inputs: Optional[list[str]] = None,
    outputs: Optional[list[str]] = None,
) -> Path:
    """Write per-step HTML artifact with locked header (input/output/status).

    HTML 산출물 = 사용자가 시각으로 판단해야 하는 step (7/8/9/13/20).
    """
    steps_dir = run_dir / "steps"
    steps_dir.mkdir(exist_ok=True)
    fname = f"step{step_num:02d}_{name}.html"
    fpath = steps_dir / fname
    inputs_lines = "\n".join(f"  - {i}" for i in (inputs or []))
    outputs_lines = "\n".join(f"  - {o}" for o in (outputs or [fname]))
    status_class = (
        "pass" if step_status == "done"
        else "fail" if step_status == "failed"
        else "partial"
    )
    inputs_li = "".join(f"<li><code>{i}</code></li>" for i in (inputs or []))
    outputs_li = "".join(f"<li><code>{o}</code></li>" for o in (outputs or [fname]))
    full_html = f"""<!--
Step {step_num:02d}: {title}
Status: {step_status}
Input:
{inputs_lines}
Output:
{outputs_lines}
-->
<!DOCTYPE html>
<html lang="ko"><head>
<meta charset="UTF-8">
<title>Step {step_num:02d} — {title}</title>
<style>
  body {{ font-family: 'Pretendard', 'Noto Sans KR', sans-serif; padding: 24px; max-width: 1280px; margin: 0 auto; color: #1e293b; }}
  h1 {{ border-bottom: 2px solid #333; padding-bottom: 8px; margin-top: 0; }}
  h2 {{ margin-top: 32px; }}
  .meta {{ background: #f8fafc; padding: 16px; border-left: 4px solid #2563eb; margin-bottom: 24px; }}
  .meta ul {{ margin: 4px 0; padding-left: 20px; }}
  .meta li {{ margin-bottom: 2px; }}
  .pass {{ color: #16a34a; font-weight: 700; }}
  .fail {{ color: #dc2626; font-weight: 700; }}
  .partial {{ color: #ca8a04; font-weight: 700; }}
  table {{ border-collapse: collapse; width: 100%; margin-top: 12px; }}
  th, td {{ border: 1px solid #cbd5e1; padding: 8px 12px; text-align: left; vertical-align: top; }}
  th {{ background: #f1f5f9; }}
  code {{ background: #f1f5f9; padding: 2px 6px; border-radius: 3px; font-size: 0.9em; }}
  .grid-preview {{ border: 2px solid #cbd5e1; padding: 8px; margin-top: 12px; }}
  .zone-box {{ background: #e2e8f0; border: 1px solid #94a3b8; padding: 12px; margin: 4px 0; border-radius: 4px; }}
  .candidate-card {{ border: 1px solid #cbd5e1; padding: 12px; margin: 8px 0; border-radius: 4px; }}
  .candidate-rank1 {{ border-left: 4px solid #16a34a; background: #f0fdf4; }}
</style>
</head><body>
<h1>Step {step_num:02d} — {title}</h1>
<div class="meta">
  <strong>Status:</strong> <span class="{status_class}">{step_status}</span><br>
  <strong>Input:</strong>
  <ul>{inputs_li}</ul>
  <strong>Output:</strong>
  <ul>{outputs_li}</ul>
</div>
{body_html}
</body>
</html>"""
    fpath.write_text(full_html, encoding="utf-8")
    return fpath


def write_debug_json(run_dir: Path, layout_preset: str,
                     debug_zones: list[dict],
                     layout_css: dict,
                     visual_runtime_check: Optional[dict] = None,
                     composition_debug: Optional[dict] = None,
                     slide_status: Optional[dict] = None,
                     fit_classification: Optional[dict] = None,
                     router_decision: Optional[dict] = None,
                     retry_trace: Optional[dict] = None,
                     asset_copy_traces: Optional[list[dict]] = None) -> Path:
    debug = {
        "v4_source": str(V4_RESULT_PATH.relative_to(PROJECT_ROOT)),
        "v4_label_to_phase_z_status": V4_LABEL_TO_PHASE_Z_STATUS,
        "mvp1_allowed_statuses": sorted(MVP1_ALLOWED_STATUSES),
        "mode": "composition_v0_layout_8preset",
        "mode_note": (
            "MVP-1.5b w/ composition planner v0 — sections → candidates (separate / "
            "parent_merged) → score → greedy select → 8-preset layout vocabulary "
            "(single / horizontal-2 / vertical-2 / top-1-bottom-2 / top-2-bottom-1 / "
            "left-1-right-2 / left-2-right-1 / grid-2x2). v0 layout = count-based; "
            "v1 axes (cardinality_fit / hierarchy_coherence / density_score) 추후."
        ),
        "layout_preset": layout_preset,
        "layout_css": layout_css,
        "slide_status": slide_status,
        "fit_classification": fit_classification,
        "router_decision": router_decision,
        "retry_trace": retry_trace,
        "composition_planner_debug": composition_debug,
        "zones": debug_zones,
        "asset_copy_traces": list(asset_copy_traces or []),
        "visual_runtime_check": visual_runtime_check,
        # A-6 (IMP-01 #1) — additive top-level zone bbox trace (slide-relative px)
        "zone_geometries_px": (visual_runtime_check or {}).get("zone_geometries_px", []),
        # IMP-15 실행-4 (issue #48) — additive top-level Step 14 event streams
        "image_events": (visual_runtime_check or {}).get("image_events", []),
        "table_events": (visual_runtime_check or {}).get("table_events", []),
    }
    debug_path = run_dir / "debug.json"
    debug_path.write_text(json.dumps(debug, ensure_ascii=False, indent=2), encoding="utf-8")
    return debug_path


# ─── Step 9 application-plan helpers (IMP-32 u1) ───────────────

def _application_candidates_for_unit(unit) -> list[dict]:
    """Step 9 (IMP-32 u1) — application candidate dicts from unit.v4_candidates.

    Pure extraction of inline block at src/phase_z2_pipeline.py:4487-4501.
    Behavior preserved: key set/order, APPLICATION_MODE_BY_V4_LABEL lookup,
    required_changes placeholder = [] (v0 = trace-only).
    """
    app_candidates = []
    for c in unit.v4_candidates:
        mode, auto_app, delegated = APPLICATION_MODE_BY_V4_LABEL.get(
            c.label, ("exclude", False, None)
        )
        app_candidates.append({
            "template_id": c.template_id,
            "frame_id": c.frame_id,
            "v4_label": c.label,
            "candidate_status": getattr(c, "candidate_status", None),
            "coverage_state": _candidate_coverage_state(
                getattr(c, "candidate_status", None),
                label=c.label,
                catalog_registered=get_contract(c.template_id) is not None,
                selection_path=getattr(c, "selection_path", None),
            ),
            "application_mode": mode,
            "auto_applicable": auto_app,
            "required_changes": [],   # v0 = trace-only
            "delegated_to": delegated,
        })
    return app_candidates


def _v4_all_judgments_for_unit(v4_all_for_unit) -> list[dict]:
    """Step 9 (IMP-32 u2) — V4 all-judgment dicts (reject 포함) for a unit.

    Pure extraction of inline block at src/phase_z2_pipeline.py:4529-4545
    (post-u1 line numbers). IMP-11 D-2 markers preserved in this helper:
    single `_contract = get_contract(c.template_id)` bind, `catalog_registered`
    boolean, and `min_height_px` chain `(_contract or {}).get("visual_hints", {}).get("min_height_px")`.
    Key set/order unchanged: template_id, frame_id, frame_number, v4_rank,
    confidence, label, catalog_registered, min_height_px.
    """
    # IMP-11 D-2 (u1) — per-candidate min_height_px source = catalog
    # frame_contracts[template_id].visual_hints.min_height_px (logical 1280×720 px).
    # None when contract unregistered (frontend tolerates undefined).
    # Single get_contract lookup binds both catalog_registered and min_height_px.
    v4_all_judgments_list = []
    for c in v4_all_for_unit:
        _contract = get_contract(c.template_id)
        _catalog_registered = _contract is not None
        v4_all_judgments_list.append({
            "template_id": c.template_id,
            "frame_id": c.frame_id,
            "frame_number": c.frame_number,
            "v4_rank": c.v4_rank,
            "confidence": c.confidence,
            "label": c.label,
            "candidate_status": getattr(c, "candidate_status", None),
            "coverage_state": _candidate_coverage_state(
                getattr(c, "candidate_status", None),
                label=c.label,
                catalog_registered=_catalog_registered,
                selection_path=getattr(c, "selection_path", None),
            ),
            "catalog_registered": _catalog_registered,
            "min_height_px": (_contract or {}).get("visual_hints", {}).get("min_height_px"),
        })
    return v4_all_judgments_list


def _build_application_plan_unit(
    unit,
    zone_plan,
    selection_trace,
    plan_record,
    v4_all_for_unit,
    layout_preset,
    layout_candidates_list,
) -> dict:
    """Step 9 (IMP-32 u3) — per-unit application_plan dict assembly.

    Pure extraction of the inline `application_plan_units.append({...})` block
    currently at src/phase_z2_pipeline.py:4577-4623 (post-u1/u2 line numbers).
    Byte-identical output (key set + key order + value identity) when called
    with the same per-unit inputs:

    - unit                    : Step 6 unit (source_section_ids, v4_candidates,
                                v4_rank, selection_path, fallback_reason,
                                frame_template_id).
    - zone_plan               : Step 8 per-unit zone_plan dict (region_layout_
                                candidates, display_strategy_candidates).
    - selection_trace         : v4_fallback_traces[unit.source_section_ids[0]]
                                (candidates list for candidate_evidence /
                                fallback_chain compat alias).
    - plan_record             : plan_record_by_unit_id[id(unit)] or None
                                (IMP-06 plan-aware additive fields).
    - v4_all_for_unit         : lookup_v4_all_judgments(...) result (Step 7-A
                                axis trace — reject 포함 모든 V4 후보).
    - layout_preset           : Step 7 preset name (e.g., "Type A").
    - layout_candidates_list  : Step 7 candidate list.

    Per-index/per-id lookups (zone_region_plans[i], v4_fallback_traces.get(...),
    plan_record_by_unit_id.get(id(unit)), section_alias_by_id, lookup_v4_all_
    judgments(...)) stay at the call-site (u4).

    Invariants preserved:
    - candidate_evidence = selection_trace.get("candidates", []) — primary field.
    - fallback_chain     = same list — compat alias for pre-IMP-05 readers.
    - v4_candidates list comprehension fields + order unchanged.
    - IMP-06 additive plan fields (position / assignment_source / section_
      assignment_override / replaced_auto_unit / skipped_collided_auto_units /
      skipped_reason) — None / False / [] when no override CLI used.

    IMP-39 u3 (issue #68) additive fields :
    - ``ranking_sort_policy``       : full policy dict from
      ``load_ranking_sort_policy()`` (cached). Forwards the single-source
      ordering contract (label_priority map + tie_break_axes) to the Step 9
      payload so the frontend (``designAgentApi.ts``) can mirror the backend
      sort without re-implementing the policy locally. u4 wires consumption.
    - ``sorted_candidate_evidence`` : explicit alias of the policy-sorted
      ``selection_trace["candidates"]`` list. Identical contents to
      ``candidate_evidence`` (u2 sorted the underlying ``judgments`` window
      before the selector loop appended ``trace["candidates"]``), but the
      explicit name documents the post-u2 contract for the frontend.
    """
    unit_id = "+".join(unit.source_section_ids)

    has_v4 = bool(unit.v4_candidates)
    candidate_status = "ok" if has_v4 else "no_non_reject_v4_candidate"
    application_status = "ok" if has_v4 else "no_v4_candidate"
    current_default = unit.frame_template_id if has_v4 else None

    # IMP-39 u3 (issue #68) — forward the single-source ranking policy to the
    # Step 9 per-unit payload. ``load_ranking_sort_policy()`` is module-cached
    # (``_RANKING_SORT_POLICY_CACHE``), so the per-unit call is O(1) after
    # first invocation. The full policy dict (not just ``policy_type``) is
    # forwarded so the frontend can mirror label_priority + tie_break_axes
    # without re-declaring the contract locally.
    ranking_sort_policy = load_ranking_sort_policy()

    # IMP-06 blocker-fix (Codex #13 Blocker 3 / #16) — plan-aware additive
    # fields. additive = pre-IMP-06 readers (no override CLI used) see
    # position=None / assignment_source=None / section_assignment_override
    # =False / replaced_auto_unit=None / skipped_collided_auto_units=[] /
    # skipped_reason=None — i.e. byte-identical absent overrides.
    plan_position = plan_record.get("position") if plan_record else None
    plan_assignment_source = plan_record.get("assignment_source") if plan_record else None
    plan_section_override = bool(plan_record.get("section_assignment_override")) if plan_record else False
    plan_replaced_auto = plan_record.get("replaced_auto_unit") if plan_record else None
    plan_skipped_collided = list(plan_record.get("skipped_collided_auto_units") or []) if plan_record else []
    plan_skipped_reason = plan_record.get("skipped_reason") if plan_record else None

    app_candidates = _application_candidates_for_unit(unit)
    v4_all_judgments_list = _v4_all_judgments_for_unit(v4_all_for_unit)

    return {
        "unit_id": unit_id,
        "layout_preset": layout_preset,
        "layout_candidates": layout_candidates_list,
        "region_layout_candidates": zone_plan.get("region_layout_candidates", []),
        "display_strategy_candidates": zone_plan.get("display_strategy_candidates", []),
        "candidate_status": candidate_status,
        "application_status": application_status,
        "current_default_candidate": current_default,
        "selected_v4_rank": unit.v4_rank,
        "selection_path": unit.selection_path,
        "fallback_used": bool(unit.selection_path and "fallback" in unit.selection_path),
        "fallback_reason": unit.fallback_reason,
        # IMP-05 L2 (Codex #10 D4 / #16 idea A) — Step 9 per-unit candidate evidence.
        # candidate_evidence is the primary field for future frontend / AI consumers.
        # fallback_chain is kept as a compat alias for any pre-IMP-05 reader.
        "candidate_evidence": selection_trace.get("candidates", []),
        "fallback_chain": selection_trace.get("candidates", []),  # compat alias; prefer candidate_evidence
        "v4_candidates": [
            {
                "template_id": c.template_id,
                "frame_id": c.frame_id,
                "frame_number": c.frame_number,
                "v4_rank": c.v4_rank,
                "confidence": c.confidence,
                "label": c.label,
                "candidate_status": getattr(c, "candidate_status", None),
                "coverage_state": _candidate_coverage_state(
                    getattr(c, "candidate_status", None),
                    label=c.label,
                    catalog_registered=get_contract(c.template_id) is not None,
                    selection_path=getattr(c, "selection_path", None),
                ),
            }
            for c in unit.v4_candidates
        ],
        # Step 7-A axis 보강 (사용자 lock 2026-05-08) — frontend UI 가 reject
        # 포함 모든 V4 후보를 시각 차별 (회색) 로 보여줄 수 있도록 trace.
        # length = 0~32. label 별 count : v4_candidates 는 non-reject only,
        # v4_all_judgments 는 reject 포함.
        # catalog_registered = frame_contracts.yaml 에 contract 있는지 여부.
        # false 면 사용자가 override 시도해도 Step 7-A 가 skip (render path 미연결).
        # IMP-11 D-2 (u1) : per-candidate min_height_px added (None when unregistered).
        "v4_all_judgments": v4_all_judgments_list,
        "application_candidates": app_candidates,
        # IMP-06 blocker-fix (Codex #13 Blocker 3 / #16) — plan-aware
        # additive fields. None / False / [] when no override CLI used.
        "position": plan_position,
        "assignment_source": plan_assignment_source,
        "section_assignment_override": plan_section_override,
        "replaced_auto_unit": plan_replaced_auto,
        "skipped_collided_auto_units": plan_skipped_collided,
        "skipped_reason": plan_skipped_reason,
        # IMP-39 u3 (issue #68) — single-source ranking policy forwarded to
        # frontend so backend selector "rank 1" and frontend
        # ``frame_candidates[0]`` share one ordering contract. Additive only;
        # pre-u3 readers ignore both keys.
        "ranking_sort_policy": ranking_sort_policy,
        "sorted_candidate_evidence": selection_trace.get("candidates", []),
    }


# ─── Main entry ────────────────────────────────────────────────


class Step0PreflightError(RuntimeError):
    """IMP-92 u4 — Step 0 AI preflight fail-fast surface.

    Raised at boot when ``settings.ai_fallback_enabled`` is True and the
    Anthropic API ping reveals a persistent setup problem (invalid API
    key, invalid model ID, billing / permission denied). Transient errors
    (429 / 5xx) do NOT fail boot — they are recorded as ``"transient"``
    in the Step 0 artifact and the pipeline proceeds; the in-pipeline
    retry layer + u2 operational classifier handle them downstream.
    """


def _run_step0_ai_preflight() -> dict:
    """IMP-92 u4 — Boot-time AI fallback preflight ping (gated).

    When ``settings.ai_fallback_enabled`` is False (default), returns
    ``{"status": "skipped", "reason": "ai_fallback_disabled", ...}``
    without instantiating ``anthropic.Anthropic`` — preserves the PZ-1
    AI=0 normal path and the ``feedback_demo_env_toggle_policy``
    default-OFF contract (no API call on normal runs).

    When enabled, issues a single 1-token Anthropic ``messages.create``
    to validate the configured ``(ai_fallback_model, anthropic_api_key)``
    pair. Persistent setup errors raise ``Step0PreflightError`` so the
    pipeline fails fast at boot rather than at first AI repair attempt.
    Transient errors are recorded as ``"transient"`` and the pipeline
    continues.

    Setup errors (fail-fast):
      * ``anthropic.AuthenticationError`` (401)     — invalid API key
      * ``anthropic.PermissionDeniedError`` (403)   — billing / permission
      * ``anthropic.NotFoundError`` (404)           — invalid model ID
      * generic ``anthropic.APIStatusError`` (402)  — billing / payment
        required (Anthropic surfaces 402 without a typed subclass;
        dispatched here by HTTP status code, mirroring u2
        ``classify_operational_error``).

    Transient (record + continue):
      * ``anthropic.RateLimitError`` (429)
      * ``anthropic.InternalServerError`` (5xx)
      * generic ``anthropic.APIStatusError`` with HTTP 429 / 5xx
    """
    import anthropic

    from src.config import settings as _settings

    if not _settings.ai_fallback_enabled:
        return {
            "status": "skipped",
            "reason": "ai_fallback_disabled",
            "model": _settings.ai_fallback_model,
        }
    try:
        client = anthropic.Anthropic(
            api_key=_settings.anthropic_api_key,
            timeout=_settings.ai_fallback_timeout_s,
        )
        client.messages.create(
            model=_settings.ai_fallback_model,
            max_tokens=1,
            messages=[{"role": "user", "content": "ping"}],
        )
    except (
        anthropic.AuthenticationError,
        anthropic.PermissionDeniedError,
        anthropic.NotFoundError,
    ) as exc:
        raise Step0PreflightError(
            f"Anthropic API preflight failed for model "
            f"{_settings.ai_fallback_model!r}: "
            f"{type(exc).__name__}: {exc}. "
            "Check ANTHROPIC_API_KEY / ai_fallback_model in .env."
        ) from exc
    except (anthropic.RateLimitError, anthropic.InternalServerError) as exc:
        return {
            "status": "transient",
            "model": _settings.ai_fallback_model,
            "transient_error": f"{type(exc).__name__}: {exc}",
        }
    except anthropic.APIStatusError as exc:
        # IMP-92 u4 — fall back to HTTP status code dispatch when the SDK
        # surfaces a setup error as the generic ``APIStatusError`` instead
        # of a typed subclass. Mirrors u2 ``classify_operational_error``
        # so HTTP 402 (Payment Required / billing) becomes a fail-fast
        # Step0PreflightError, matching the issue body's explicit
        # operational contract.
        status_code = getattr(exc, "status_code", None)
        if status_code is None:
            status_code = getattr(getattr(exc, "response", None), "status_code", None)
        if status_code == 429 or (status_code is not None and 500 <= status_code < 600):
            return {
                "status": "transient",
                "model": _settings.ai_fallback_model,
                "transient_error": f"{type(exc).__name__}: {exc}",
            }
        raise Step0PreflightError(
            f"Anthropic API preflight failed for model "
            f"{_settings.ai_fallback_model!r}: "
            f"HTTP {status_code} {type(exc).__name__}: {exc}. "
            "Check ANTHROPIC_API_KEY / ai_fallback_model in .env."
        ) from exc
    return {
        "status": "passed",
        "model": _settings.ai_fallback_model,
    }


def _resolve_slide_css_from_frontmatter(mdx_source_text: str) -> Optional[str]:
    """IMP-45 (#74) u4 — minimal frontmatter probe for ``slide_overrides.css``.

    Targeted re-parse of the same YAML frontmatter block that
    :func:`parse_mdx` reads at line 415-418 — extracts only the
    nested ``slide_overrides.css`` string when present. Kept inline
    rather than routed through :func:`src.mdx_normalizer.normalize_mdx_content`
    so Step 13 render does not depend on the Stage 0 normalize adapter
    (project lock 2026-05-08).

    Mirrors the validation rules in
    :func:`src.mdx_normalizer._extract_slide_overrides` (u2) :

    - No frontmatter / unparseable YAML / non-mapping → ``None``.
    - Missing ``slide_overrides`` mapping → ``None``.
    - ``slide_overrides.css`` non-string or empty → ``None``.
    - ``slide_overrides.css`` non-empty ``str`` → that string.
    """
    fm_match = re.match(r"^---\n(.*?)\n---\n", mdx_source_text, re.DOTALL)
    if fm_match is None:
        return None
    try:
        fm = yaml.safe_load(fm_match.group(1))
    except yaml.YAMLError:
        return None
    if not isinstance(fm, dict):
        return None
    overrides = fm.get("slide_overrides")
    if not isinstance(overrides, dict):
        return None
    css = overrides.get("css")
    if isinstance(css, str) and css:
        return css
    return None


def run_phase_z2_mvp1(
    mdx_path: Path,
    run_id: Optional[str] = None,
    *,
    override_layout: Optional[str] = None,
    override_frames: Optional[dict[str, str]] = None,
    override_zone_geometries: Optional[dict[str, dict]] = None,
    override_section_assignments: Optional[dict[str, list[str]]] = None,
    override_image_overrides: Optional[dict[str, dict]] = None,
    override_slide_css: Optional[str] = None,
    override_text_overrides: Optional[dict[str, dict[str, str]]] = None,
    override_structure_overrides: Optional[dict[str, dict[str, list[str]]]] = None,
    reuse_from: Optional[str] = None,
) -> Path:
    """MVP-1.5b entry — single slide + composition planner v0 + 8 preset vocabulary.

    Pipeline :
      parse_mdx → align_sections_to_v4_granularity → plan_composition →
      mapper per unit → render slide_base + frame partial → Selenium check

    User overrides (Step 7-A axis, 2026-05-08) :
      override_layout : 자동 결정된 layout_preset 을 사용자 선택값으로 강제 (8 preset 중 하나).
      override_frames : {unit_id: template_id} — 자동 결정된 frame template 을 사용자 선택값
                        으로 강제. unit_id = "+".join(source_section_ids) (e.g., "03-1"
                        또는 "03-1+03-2"). 매칭 unit 의 v4_candidates 에 있는 entry 면
                        그 entry 의 score / label 도 함께 갱신. 없으면 template_id 만 변경.
      override_image_overrides : {image_id: {x, y, w, h}} — IMP-51 (#79) u5 axis.
                        image_id = stable id stamped on user-content `<img>` tags by
                        ``src/image_id_stamper.py`` (u4). x/y/w/h are percent-of-slide
                        coordinates (0–100, slide-absolute). Forward-compat kwarg: the
                        render-time CSS injection that consumes this mapping lands in
                        u7; until u7 wires the consumer, accepting the kwarg keeps the
                        backend contract (KNOWN_AXES u1 + Vite allowlist u2 + typed
                        client u3 + stamper u4) end-to-end addressable from CLI without
                        diverging the function signature.
      override_text_overrides : {zone_id: {text_path: value}} — IMP-56 (#90) u5
                        axis. ``text_path`` = ``{slot_key}.{line_index}`` stamped
                        by the u8 ``text_path_stamper`` (pending). Applied at
                        Step 12 AFTER the AI-repair apply (IMP-47B u5) and
                        BEFORE the ``step12_slot_payload.json`` artifact emit so
                        the audit reflects user-edit final state. Per-zone
                        tolerant — stale paths (frame swap / layout regression)
                        skip silently. raw_content preserved (mutates
                        ``zone['slot_payload']`` only ; ``debug_zones`` graph
                        untouched). CLI / persistence fallback wiring is u16
                        scope.
      override_structure_overrides : {zone_id: {slot_order|hidden_slots: [slot_key,...]}}
                        — IMP-56 (#90) u7 axis. SCOPE LOCKED to
                        ``slot_order`` (partial reorder) + ``hidden_slots``
                        (hide). Frame swap is rejected at the u6 validate
                        gate (stays on the existing ``frames`` axis) so the
                        Phase Z no-AI-HTML-structure invariant remains
                        intact. Applied at Step 12 AFTER the u5
                        text_overrides apply and BEFORE the
                        ``step12_slot_payload.json`` artifact emit. Per-zone
                        tolerant — stale slot_keys silently no-op (counted
                        as ``skipped_zones``). raw_content preserved (only
                        top-level slot_payload key membership + ordering
                        mutated ; per-slot ``list[str]`` line content +
                        ``debug_zones`` graph untouched). CLI / persistence
                        fallback wiring is u16 scope.
      override_slide_css : Optional slide-level CSS string — IMP-45 (#74) u4 axis.
                        Marker-wrapped <style> block injected into ``final.html``
                        at Step 13 via :func:`src.slide_css_injector.inject_slide_css`
                        (mirrors the image_id_stamper injection contract). When
                        ``None``, the MDX frontmatter ``slide_overrides.css`` value
                        is used as fallback via
                        :func:`_resolve_slide_css_from_frontmatter`. Kwarg always
                        wins over frontmatter when provided. The CLI surface
                        (``--override-slide-css`` inline + ``--slide-css-file``
                        PATH) lands in u5.

    Incremental rerun (IMP-43 #72, u5) :
      reuse_from : Optional PREV_RUN_ID. When set, Steps 0/1/2/5/6 artifacts
                        are copied from ``RUNS_DIR / PREV_RUN_ID / phase_z2``
                        and the in-memory state (sections, units, layout_preset,
                        comp_debug, v4_fallback_traces, slide_title/footer,
                        stage0_*, v4_evidence, ai_preflight) is rehydrated
                        from ``_reuse_snapshot.json`` via the u4 helpers,
                        wrapped by u4b's fail-closed contract. Step 7+ then
                        re-executes against ``override_frames`` in this new
                        run_dir. ``None`` preserves the legacy single-pass
                        behaviour (Steps 0-6 derive state from scratch).
                        The post-merge u1 guard at the CLI surface rejects
                        any layout / zone_geometry / zone_section / image
                        override under ``--reuse-from`` so only frame
                        overrides reach this kwarg's reuse branch.
    """
    mdx_path = Path(mdx_path)
    if run_id is None:
        run_id = time.strftime("%Y%m%d_%H%M%S") + "_phase_z2"
    run_dir = RUNS_DIR / run_id / "phase_z2"
    run_dir.mkdir(parents=True, exist_ok=True)  # step artifacts 위해 미리 생성

    print(f"[Phase Z-2 MVP-1.5b] start — mdx={mdx_path.name}, run_id={run_id}")

    # IMP-43 (#72) u5 — Steps 0/1/2/5/6 entry-point branch.
    # ``reuse_from is None`` = normal pipeline (Steps 0-6 derive state).
    # ``reuse_from is not None`` = restore Steps 0/1/2/5/6 state from
    # prev_run snapshot via the u4 helpers wrapped by u4b's fail-closed
    # contract, then fall through to the shared Step 7+ block below.
    # The post-merge u1 guard has already rejected any layout /
    # zone_geometry / zone_section / image override on the reuse path,
    # so only --override-frame (handled at the Step 7-A axis below the
    # branch) survives into this code path.
    if reuse_from is None:
        # ─── Step 0: 사전 준비 (precondition snapshot) ───
        # IMP-92 u4 — boot-time AI fallback preflight (gated on
        # settings.ai_fallback_enabled; default OFF = skipped, no API call).
        # Persistent setup errors raise Step0PreflightError before Step 1.
        ai_preflight = _run_step0_ai_preflight()
        _write_step_artifact(
            run_dir, 0, "preconditions",
            data={
                "v4_source": str(V4_RESULT_PATH.relative_to(PROJECT_ROOT)),
                "templates_dir": str(TEMPLATE_DIR.relative_to(PROJECT_ROOT)),
                "assets_source_base": str(ASSETS_SOURCE_BASE.relative_to(PROJECT_ROOT)),
                "frame_contracts_loaded": len(load_frame_contracts()),
                "frame_contracts_template_ids": sorted(load_frame_contracts().keys()),
                "v4_label_to_phase_z_status": V4_LABEL_TO_PHASE_Z_STATUS,
                "mvp1_allowed_statuses": sorted(MVP1_ALLOWED_STATUSES),
                "ai_preflight": ai_preflight,
            },
            step_status="partial",
            pipeline_path_connected=True,
            inputs=[
                "templates/phase_z2/catalog/frame_contracts.yaml",
                "tests/matching/v4_full32_result.yaml",
                "templates/phase_z2/families/*.html",
                "figma_to_html_agent/blocks/",
            ],
            outputs=["step00_preconditions.json"],
            note=(
                "frame_contracts.yaml 에 등록된 frame 만 mapping 가능. "
                "V4 결과의 32 frame 중 다수 (F11/F14/F18 등) 미등록 — Step 0 ⚠ partial."
            ),
        )

        # ─── Step 1: MDX 업로드 ───
        mdx_source_text = mdx_path.read_text(encoding="utf-8")
        (run_dir / "steps").mkdir(exist_ok=True)
        (run_dir / "steps" / "step01_mdx_source.md").write_text(mdx_source_text, encoding="utf-8")
        _write_step_artifact(
            run_dir, 1, "mdx_upload",
            data={
                "mdx_path": str(mdx_path),
                "run_id": run_id,
                "run_dir": str(run_dir),
                "mdx_source_size_bytes": len(mdx_source_text.encode("utf-8")),
                "mdx_source_lines": mdx_source_text.count("\n") + 1,
            },
            step_status="done",
            pipeline_path_connected=True,
            inputs=[str(mdx_path)],
            outputs=["step01_mdx_upload.json", "step01_mdx_source.md"],
            note="MDX 원본 그대로 step01_mdx_source.md 에 복사.",
        )

        # 1. Parse MDX (V4 무관)
        legacy_slide_title, legacy_sections, legacy_footer = parse_mdx(mdx_path)
        # IMP-02 — Stage 0 chained adapter dispatch (default OFF canary).
        # When env PHASE_Z_STAGE0_ADAPTER_ENABLED=1/true/yes the adapter chain
        # (mdx_normalizer + section_parser) replaces legacy parse_mdx output;
        # on any contract failure or exception, falls back to legacy with
        # fallback_reason recorded in stage0_adapter_diagnostics.
        # IMP-03 — 5-tuple return adds stage0_normalized_assets (Step 3 handoff).
        (
            slide_title,
            sections,
            slide_footer,
            stage0_adapter_diagnostics,
            stage0_normalized_assets,
        ) = _stage0_chained_adapter(
            mdx_path, legacy_slide_title, legacy_sections, legacy_footer,
        )
        _adapter_tag = (
            "adapter-used" if stage0_adapter_diagnostics["used"]
            else f"legacy({stage0_adapter_diagnostics['fallback_reason'] or 'disabled'})"
        )
        section_id_aliases = _build_section_id_aliases(sections)
        (
            override_section_assignments,
            override_frames,
            override_alias_trace,
        ) = _apply_section_id_aliases_to_overrides(
            override_section_assignments,
            override_frames,
            section_id_aliases,
        )
        print(f"  parsed  : title='{slide_title}', sections={len(sections)} "
              f"({[s.section_id for s in sections]}), footer={'yes' if slide_footer else 'no'}, "
              f"stage0={_adapter_tag}")

        # ─── Step 2: MDX 정규화 ───
        # orphans / details 필드는 schema lock — 빈 배열이라도 박혀야
        # "검사 안 함" vs "없음" 구분 가능 (사용자 직설 2026-05-07).
        # 실제 orphan / details 감지 로직은 별 axis (Step 2 보강).
        _write_step_artifact(
            run_dir, 2, "normalized",
            data={
                "slide_title": slide_title,
                "slide_footer": slide_footer,
                "sections_count": len(sections),
                "sections": [
                    {
                        "section_id": s.section_id,
                        "section_num": s.section_num,
                        "title": s.title,
                        "raw_content_length": len(s.raw_content),
                        "raw_content": s.raw_content,
                        "component_expansions": list(getattr(s, "sub_sections", []) or []),
                    }
                    for s in sections
                ],
                "orphans": [],   # schema lock — 중목차에 안 속한 텍스트 (감지 미구현)
                "details": [],   # schema lock — <details> 팝업 콘텐츠 (감지 미구현)
                # IMP-02 — additive only. enabled/used/fallback_reason + id reconstruction
                # trace + count diff. Out of scope: V4 / align / composition.
                "stage0_adapter_diagnostics": stage0_adapter_diagnostics,
                # IMP-03 — Step 3 handoff (slide-level rich asset list).
                # env=OFF / fallback 시 모든 list 가 비어 있음. consumer = Step 3
                # rich extractor (PHASE_Z_STEP3_RICH_OBJECTS_ENABLED canary).
                "stage0_normalized_assets": stage0_normalized_assets,
                "section_id_aliases": section_id_aliases,
                "override_alias_trace": override_alias_trace,
            },
            step_status="partial",
            pipeline_path_connected=True,
            inputs=["step01_mdx_source.md"],
            outputs=["step02_normalized.json"],
            note=(
                "parse_mdx 결과: title / sections / footer 분리 + raw_content 보존. "
                "heading tree 미생성, orphan / details 감지 미완 (Step 2 ⚠ partial — 별 axis). "
                "orphans / details 필드는 schema lock — 빈 배열이라도 'detection 미수행' marker. "
                "stage0_adapter_diagnostics = IMP-02 chained adapter trace (default OFF canary). "
                "stage0_normalized_assets = IMP-03 Step 3 slide-level handoff (popups/images/tables list)."
            ),
        )

        # 2. Load V4
        v4 = load_v4_result()

        # 3. Align sections to V4 granularity (### drill if needed).
        # IMP-08 B-3 / Stage 5 R2 : forward override target ids so sub-id
        # drag/drop targets force-drill their parent section even when V4
        # carries the parent exact key (deterministic drag/drop addressing).
        _override_target_sids: list[str] = []
        if override_section_assignments:
            for _sids in override_section_assignments.values():
                for _sid in _sids:
                    if isinstance(_sid, str) and _sid:
                        _override_target_sids.append(_sid)
        parent_sections_for_task14 = list(sections)
        sections_for_status = sections
        sections = align_sections_to_v4_granularity(
            sections,
            v4,
            override_target_section_ids=_override_target_sids or None,
        )
        sections_for_status = sections
        print(f"  aligned : sections={len(sections)} ({[s.section_id for s in sections]})")

        # ─── Step 5: V4 매칭 evidence (Emergency P2 + P2a mitigation) ───
        # Emergency P2 (2026-05-26) — emergency.md §3 policy 반영.
        #   include_reject=True (default) 로 reject 후보도 candidate_status =
        #   "ai_adaptation_required" 로 표시. visual_pending 는 "blocked_runtime".
        # Emergency P2a (2026-05-26) — backward compat mitigation.
        #   section-level `candidate_status` = old semantic ("ok" / "no_non_reject_v4_candidate")
        #   보존 — IMP-91 integration snapshot + tests/test_phase_z2_reuse_*.py fixtures 와
        #   schema 일치 유지. 새 의미는 `candidate_pool_status` + `candidate_status_counts`
        #   별 field 로 surface. per-candidate `candidate_status` 는 새 의미 (auto / ai_adaptation /
        #   blocked) — additive 라 break 없음.
        v4_evidence_list = []
        for s in sections:
            # NEW (P2): all candidates incl reject + visual_pending, with candidate_status field
            candidates = lookup_v4_candidates(v4, s.section_id)
            # OLD (May 8 lock): non-reject + non-vp only — byte-identical to pre-P2 behavior.
            # IMP-91 snapshot legacy semantic 정확히 보존. **OLD resolver (single-key, no child
            # merge) 사용** — P2.5 의 child merge 가 snapshot semantic 변경 가능성 차단.
            # alias_keys 는 section 객체에서 직접 (section_alias_by_id 는 아래서 정의됨).
            _legacy_alias_keys = list(getattr(s, "v4_alias_keys", []) or [])
            _legacy_resolved = _resolve_v4_section_key(
                v4, s.section_id, alias_keys=_legacy_alias_keys or None,
            )
            _legacy_sec = v4.get("mdx_sections", {}).get(_legacy_resolved) if _legacy_resolved else None
            legacy_non_reject_candidates: list = []
            if _legacy_sec:
                for _j in _legacy_sec.get("judgments_full32", []):
                    if _j.get("label") == "reject":
                        continue
                    _tid = _j.get("template_id")
                    if _tid and _is_visual_pending(_tid):
                        continue
                    legacy_non_reject_candidates.append(_j)
                    if len(legacy_non_reject_candidates) >= 6:
                        break
            status_counts = {"auto_renderable": 0, "ai_adaptation_required": 0, "blocked_runtime": 0}
            for c in candidates:
                if c.candidate_status in status_counts:
                    status_counts[c.candidate_status] += 1
            # section-level pool status (NEW field — emergency.md policy):
            #   auto_renderable 1+          → "auto_renderable_pool"
            #   only ai_adaptation_required → "ai_adaptation_pool"
            #   only blocked_runtime        → "blocked_runtime_pool"
            #   total 0 (raw 후보 0)         → "catalog_gap" (P3 generic_fallback route)
            if status_counts["auto_renderable"] > 0:
                pool_status = "auto_renderable_pool"
            elif status_counts["ai_adaptation_required"] > 0:
                pool_status = "ai_adaptation_pool"
            elif status_counts["blocked_runtime"] > 0:
                pool_status = "blocked_runtime_pool"
            else:
                pool_status = "catalog_gap"
            # section-level OLD candidate_status — IMP-91 snapshot + reuse fixtures backward
            # compat. 의미: "non-reject 후보 1+ 가 존재하는가?" (May 8 lock 의 원 의미).
            # legacy_non_reject_candidates (위에서 별 호출) 로 OLD 동작 byte-identical.
            section_legacy_status = (
                "ok" if legacy_non_reject_candidates else "no_non_reject_v4_candidate"
            )
            v4_evidence_list.append({
                "section_id": s.section_id,
                "v4_candidates": [
                    {
                        "template_id": c.template_id,
                        "frame_id": c.frame_id,
                        "frame_number": c.frame_number,
                        "confidence": c.confidence,
                        "label": c.label,
                        "candidate_status": c.candidate_status,  # NEW per-candidate (auto/ai/blocked)
                        "coverage_state": _candidate_coverage_state(
                            c.candidate_status,
                            label=c.label,
                            catalog_registered=get_contract(c.template_id) is not None,
                            selection_path=getattr(c, "selection_path", None),
                        ),
                    }
                    for c in candidates
                ],
                "candidate_status": section_legacy_status,        # OLD semantic — backward compat
                "candidate_pool_status": pool_status,             # NEW semantic — emergency.md policy
                "candidate_status_counts": status_counts,         # NEW — per-status count
            })
        _write_step_artifact(
            run_dir, 5, "v4_evidence",
            data={
                "v4_source": str(V4_RESULT_PATH.relative_to(PROJECT_ROOT)),
                "aligned_section_ids": [s.section_id for s in sections],
                "evidence_per_section": v4_evidence_list,
            },
            step_status="done",
            pipeline_path_connected=True,
            inputs=["step02_normalized.json", "tests/matching/v4_full32_result.yaml"],
            outputs=["step05_v4_evidence.json"],
            note=(
                "V4 max-6 후보 list (Step 9 application_plan input). "
                "Emergency P2 (2026-05-26) — include_reject=True default. reject 후보 도 보존, "
                "각 candidate 에 candidate_status (auto_renderable / ai_adaptation_required / blocked_runtime). "
                "raw 32 entry 는 tests/matching/v4_full32_result.yaml 에 영속 (stale fixture). "
                "section-level fields: "
                "candidate_status='ok' (후보 1+) / 'no_non_reject_v4_candidate' (raw 0) — backward compat. "
                "candidate_pool_status='auto_renderable_pool' / 'ai_adaptation_pool' / "
                "'blocked_runtime_pool' / 'catalog_gap' — NEW emergency.md policy semantic. "
                "candidate_status_counts = per-status count. "
                "Step 6 plan_composition() 은 include_reject=False 로 호출 (P3 까지 backward compat)."
            ),
        )

        # 4. Composition planner v0 — replaces per-section + select_layout_preset.
        #    candidate (separate / parent_merged) → score → greedy non-overlapping select →
        #    layout preset (count-based v0).
        section_content_by_id = {s.section_id: s.raw_content for s in sections}
        # IMP-08 B-3 : sub-section ordinal id -> legacy V4 key aliases (e.g. "04-2.1").
        # Empty list for canonical (top-level) sections — U1 baseline path is exact-only.
        section_alias_by_id: dict[str, list] = {
            s.section_id: list(getattr(s, "v4_alias_keys", []) or []) for s in sections
        }
        v4_fallback_traces: dict[str, dict] = {}

        def lookup_fn(sid: str) -> Optional[V4Match]:
            match, trace = lookup_v4_match_with_fallback(
                v4,
                sid,
                raw_content=section_content_by_id.get(sid),
                alias_keys=section_alias_by_id.get(sid),
            )
            v4_fallback_traces[sid] = trace
            return match

        # Step 6-A axis (사용자 lock 2026-05-08) — V4 raw dict 흡수 fn.
        # composition module 은 V4 yaml shape 모름. 본 fn 만 통해 후보 list 받음.
        # Emergency P2 (2026-05-26) — composition path 는 P3 까지 backward compat 유지.
        #   include_reject=False + include_blocked_runtime=False = pre-P2 May 8 lock 동작.
        #   단 P2.5 child key merge 는 통과 — 04-2 / 02-2 같은 parent 가 child candidates
        #   를 받음 (부수 효과: composition 이 이전엔 empty 받던 케이스를 이제 non-reject
        #   후보 받음 → 04-2 자동 cover. 회귀 아니라 fix).
        #   P3 에서 include_reject=True 로 전환 + status 기반 routing.
        def candidates_lookup_fn(sid: str) -> list[V4Match]:
            candidates = lookup_v4_candidates(
                v4, sid,
                alias_keys=section_alias_by_id.get(sid),
                include_reject=True,
                include_blocked_runtime=True,
            )
            if candidates:
                return candidates
            return lookup_catalog_fallback_candidates(sid)

        units, layout_preset, comp_debug = plan_composition(
            sections, lookup_fn, V4_LABEL_TO_PHASE_Z_STATUS, MVP1_ALLOWED_STATUSES,
            capacity_fit_fn=compute_capacity_fit,
            v4_candidates_lookup_fn=candidates_lookup_fn,
        )
        comp_debug["v4_fallback_selections"] = list(v4_fallback_traces.values())
        # IMP-05 L3 (Codex #10 D4) — Step 20 qualifier fields (additive only, no top-level enum change).
        # `fallback_selection_count` = number of sections where rank-2/3 was promoted.
        # `selection_paths` = per-section selection_path summary (rank_1 / rank_N_fallback / chain_exhausted).
        # Top-level slide status enum (PASS / PARTIAL_COVERAGE / ...) remains stable.
        _imp05_selection_paths = [
            {
                "section_id": sid,
                "selection_path": t.get("selection_path"),
                "selected_rank": t.get("selected_rank"),
                "selected_template_id": t.get("selected_template_id"),
                "fallback_trigger": t.get("fallback_reason") if t.get("fallback_used") else None,
            }
            for sid, t in v4_fallback_traces.items()
        ]
        comp_debug["v4_fallback_summary"] = {
            "fallback_used_count": sum(1 for t in v4_fallback_traces.values() if t.get("fallback_used")),
            "fallback_selection_count": sum(1 for t in v4_fallback_traces.values() if t.get("fallback_used")),
            "chain_exhausted_count": sum(
                1 for t in v4_fallback_traces.values()
                if t.get("selection_path") == "chain_exhausted"
            ),
            "selection_paths": _imp05_selection_paths,
            "policy": (
                "IMP-05: rank-1 is kept when usable; rank-2/3 may be promoted only when "
                "the earlier rank is not auto-renderable, has no catalog contract, or fails "
                "capacity precheck. calculate_fit is not used."
            ),
        }

        # IMP-47B u12 — mixed direct+reject first-render admission.
        # When initial plan_composition produces a viable layout but at least one
        # section remains uncovered (typically chain_exhausted / reject), re-run
        # with allow_provisional in the lookup + allow_provisional_fill=True so
        # reject sections gain a provisional rank-1 V4Match and a last-resort
        # provisional candidate fill. This admits the mixed direct+reject case
        # to the AI repair path (IMP-47B u4/u5) on first render. Skipped under
        # --override-section-assignments to preserve the operator's plan and
        # mirror the IMP-30 u4 retry's section_assignment_plan gate. All-direct
        # slides have no uncovered sections so this is a no-op. The all-reject
        # case is still handled by the IMP-30 u4 retry block below (initial
        # plan_composition returns units=[]).
        if units and layout_preset is not None and not override_section_assignments:
            _u12_covered_ids: set[str] = set()
            for _u in units:
                _u12_covered_ids.update(_u.source_section_ids)
            _u12_uncovered_ids = [
                s.section_id for s in sections if s.section_id not in _u12_covered_ids
            ]
            if _u12_uncovered_ids:
                def _lookup_fn_mixed_admission(sid: str) -> Optional[V4Match]:
                    match, trace = lookup_v4_match_with_fallback(
                        v4,
                        sid,
                        raw_content=section_content_by_id.get(sid),
                        alias_keys=section_alias_by_id.get(sid),
                        allow_provisional=True,
                    )
                    v4_fallback_traces[sid] = trace
                    return match

                units_mixed, layout_preset_mixed, _comp_debug_mixed = plan_composition(
                    sections,
                    _lookup_fn_mixed_admission,
                    V4_LABEL_TO_PHASE_Z_STATUS,
                    MVP1_ALLOWED_STATUSES,
                    capacity_fit_fn=compute_capacity_fit,
                    v4_candidates_lookup_fn=candidates_lookup_fn,
                    allow_provisional_fill=True,
                )
                if units_mixed and layout_preset_mixed is not None:
                    units = units_mixed
                    layout_preset = layout_preset_mixed
                    comp_debug["v4_fallback_selections"] = list(v4_fallback_traces.values())
                    comp_debug["imp47b_u12_mixed_admission"] = {
                        "applied": True,
                        "uncovered_before": _u12_uncovered_ids,
                        "result_unit_count": len(units_mixed),
                        "result_layout_preset": layout_preset_mixed,
                    }

        # ── Step 7-A axis : layout override ──
        # 사용자가 LayoutPanel 에서 다른 preset 을 선택했을 때 자동 결정값을 강제 변경.
        # 길이 mismatch (positions count vs unit count) 는 zone loop 의 fallback (zone_{i})
        # 으로 처리됨. 알 수 없는 preset 이면 ValueError.
        auto_layout_preset = layout_preset
        layout_override_applied = False
        inferred_layout_from_zone_sections = None
        if override_layout is None and override_section_assignments and layout_preset is not None:
            inferred_layout_from_zone_sections = _infer_layout_from_zone_section_keys(
                override_section_assignments,
                unit_count=len(units),
            )
            if inferred_layout_from_zone_sections is not None:
                override_layout = inferred_layout_from_zone_sections
        if override_layout is not None and override_layout != layout_preset:
            if override_layout not in LAYOUT_PRESETS:
                raise ValueError(
                    f"--override-layout '{override_layout}' is not a known preset. "
                    f"Available: {sorted(LAYOUT_PRESETS.keys())}"
                )
            print(
                f"  [override] layout_preset: {layout_preset} → {override_layout}",
                file=sys.stderr,
            )
            layout_preset = override_layout
            layout_override_applied = True
            if inferred_layout_from_zone_sections is not None:
                comp_debug["section_assignment_layout_inference"] = {
                    "applied": True,
                    "from_layout_preset": auto_layout_preset,
                    "to_layout_preset": inferred_layout_from_zone_sections,
                    "zone_section_keys": sorted(override_section_assignments.keys()),
                    "reason": "manual_zone_sections_match_layout_positions",
                }

        # IMP-06 (#6 / Codex #6/#7/#10/#11/#12 lock) — zone-section assignment override.
        # Applied AFTER final layout_preset resolution. ZONE_ID = layout positions.
        # The helper validates unknown zone ids / unknown section ids and builds a
        # `position_assignment_plan`. Immediately below, Stage 4 Part 2 rebuilds the
        # `units` list aligned with that plan: cli_override entries synthesize a
        # CompositionUnit, auto entries reuse the original planner unit, and empty/
        # collision-skipped entries become None placeholders. The downstream
        # zones_data / debug_zones loop then handles None entries by emitting an
        # explicit empty zone record (template_id="__empty__") so the slide grid
        # preserves position identity without distorting layout allocation.
        section_assignment_plan: Optional[list[dict]] = None
        section_assignment_summary: Optional[dict] = None
        if override_section_assignments and layout_preset is not None:
            positions = list(LAYOUT_PRESETS[layout_preset]["positions"])
            # Validate ZONE_IDs against active layout positions (fail-fast).
            unknown_zones = [z for z in override_section_assignments if z not in positions]
            if unknown_zones:
                raise ValueError(
                    f"--override-section-assignment unknown ZONE_ID(s) {unknown_zones} for "
                    f"layout '{layout_preset}'. Available positions: {positions}"
                )
            # Validate section_ids against aligned sections (fail-fast).
            aligned_section_ids = {s.section_id for s in sections}
            sections_by_id = {s.section_id: s for s in sections}
            unknown_sections: list[str] = []
            for zid, sids in override_section_assignments.items():
                for sid in sids:
                    if sid not in aligned_section_ids:
                        unknown_sections.append(sid)
            if unknown_sections:
                raise ValueError(
                    f"--override-section-assignment unknown section_id(s) {unknown_sections}. "
                    f"Aligned sections: {sorted(aligned_section_ids)}"
                )
            section_assignment_plan, section_assignment_summary = _build_position_assignment_plan(
                units=units,
                positions=positions,
                override_section_assignments=override_section_assignments,
                sections_by_id=sections_by_id,
                override_frames=override_frames,
                v4=v4,
            )
            comp_debug["section_assignment_plan"] = section_assignment_plan
            comp_debug["section_assignment_summary"] = section_assignment_summary
            print(
                f"  [override] section_assignment applied: "
                f"{section_assignment_summary['applied_count']} position(s), "
                f"{section_assignment_summary['skipped_count']} skipped, "
                f"uncovered_sections={section_assignment_summary['uncovered_section_ids']}",
                file=sys.stderr,
            )

            # Stage 4 blocker-fix (Codex #13/#14/#15/#16/#17) — rebuild units as a pure
            # `list[CompositionUnit]` (renderable only, no None). Position-aware truth
            # lives in `render_records` (built after frame_overrides apply) per Codex
            # internal contract: units = canonical renderable list, render_records =
            # canonical per-position view including empty/skipped entries.
            from src.phase_z2_composition import CompositionUnit
            plan_units: list = []
            # Maintain ordered alignment with section_assignment_plan for the
            # render_records build step below: plan_unit_by_position[pos] = unit | None.
            plan_unit_by_position: dict[str, object] = {}
            for entry in section_assignment_plan:
                assignment_source = entry["assignment_source"]
                pos = entry["position"]
                if assignment_source == "cli_override" and entry["template_id"] is not None:
                    sids = entry["source_section_ids"]
                    raw_content_parts = []
                    title_parts = []
                    for sid in sids:
                        sect = sections_by_id.get(sid)
                        if sect is None:
                            continue
                        raw_content_parts.append(sect.raw_content or "")
                        if sect.title:
                            title_parts.append(sect.title)
                    contract = get_contract(entry["template_id"])
                    contract_frame_id = (contract or {}).get("frame_id") or ""
                    override_unit = CompositionUnit(
                        source_section_ids=list(sids),
                        merge_type="cli_override",
                        frame_template_id=entry["template_id"],
                        frame_id=str(contract_frame_id),
                        frame_number=0,
                        confidence=0.0,
                        label="use_as_is",
                        phase_z_status="matched_zone",
                        raw_content="\n\n".join(raw_content_parts),
                        title=" / ".join(title_parts) if title_parts else "+".join(sids),
                        v4_rank=None,
                        selection_path="cli_override",
                        fallback_reason=None,
                        score=0.0,
                        rationale={
                            "section_assignment_override": entry["section_assignment_override"],
                            "replaced_auto_unit": entry["replaced_auto_unit"],
                        },
                    )
                    plan_units.append(override_unit)
                    plan_unit_by_position[pos] = override_unit
                elif assignment_source == "auto":
                    # Find original auto unit by source_section_ids.
                    matched = None
                    for u in units:
                        if list(u.source_section_ids) == entry["source_section_ids"]:
                            matched = u
                            break
                    if matched is not None:
                        plan_units.append(matched)
                        plan_unit_by_position[pos] = matched
                    else:
                        # Unexpected — auto plan entry without a matching original unit.
                        plan_unit_by_position[pos] = None
                else:
                    # empty / collision-skipped — NO None in units list, but the position
                    # is preserved in plan_unit_by_position so render_records can emit
                    # an empty zone record below (after frame_overrides apply).
                    plan_unit_by_position[pos] = None
            units = plan_units

        if not units or layout_preset is None:
            # IMP-30 u4 — first-render invariant. The pre-u4 path here was
            # `sys.exit(1)` after writing error.json. That violated the invariant
            # ("final.html + Step 20 slide_status MUST be written for every input
            # where Step 0~5 succeed") whenever V4 evidence for any section was
            # restructure/reject (chain_exhausted) or missing (no_v4_section /
            # empty_v4_judgments).
            #
            # Recovery has two phases:
            #   Phase A — provisional retry (u1 + u3 opt-in). Re-run plan_composition
            #     with allow_provisional=True (in lookup_fn) and allow_provisional_fill
            #     =True. Synthesizes rank-1 provisional V4Match on chain_exhausted
            #     (u1) and last-resort-fills uncovered sections with provisional
            #     candidates (u3). Skipped when the CLI override path was used —
            #     re-running plan_composition there would discard the override.
            #   Phase B — terminal empty-shell. If retry still yields zero units
            #     (true "no rank-1 V4 anywhere" case, or override path with no
            #     resolvable assignments), synthesize a single placeholder
            #     CompositionUnit with frame_template_id="__empty__", layout_preset
            #     ="single". The per-unit loop's __empty__ guard emits a placeholder
            #     zones_data / debug_zones record; final.html renders the slide
            #     base shell (title + footer + empty zone) so the first-render
            #     invariant holds. Provisional flag = True surfaces the "needs
            #     adaptation" signal (u5 zone class + u6 status qualifier).
            provisional_recovered = False
            if section_assignment_plan is None:
                def _lookup_fn_provisional(sid: str) -> Optional[V4Match]:
                    match, trace = lookup_v4_match_with_fallback(
                        v4,
                        sid,
                        raw_content=section_content_by_id.get(sid),
                        alias_keys=section_alias_by_id.get(sid),
                        allow_provisional=True,
                    )
                    v4_fallback_traces[sid] = trace
                    return match

                units_retry, layout_preset_retry, comp_debug_retry = plan_composition(
                    sections,
                    _lookup_fn_provisional,
                    V4_LABEL_TO_PHASE_Z_STATUS,
                    MVP1_ALLOWED_STATUSES,
                    capacity_fit_fn=compute_capacity_fit,
                    v4_candidates_lookup_fn=candidates_lookup_fn,
                    allow_provisional_fill=True,
                )
                comp_debug["imp30_u4_provisional_retry"] = {
                    "applied": True,
                    "result_unit_count": len(units_retry),
                    "result_layout_preset": layout_preset_retry,
                    "candidates_summary": comp_debug_retry.get("candidates_summary"),
                }
                if units_retry and layout_preset_retry is not None:
                    units = units_retry
                    layout_preset = layout_preset_retry
                    provisional_recovered = True
                    # v4_fallback_traces was overwritten by _lookup_fn_provisional;
                    # refresh the IMP-05 selection_paths telemetry so Step 20 reflects
                    # the actual selection (provisional_rank_1) rather than the stale
                    # chain_exhausted state from the first attempt.
                    _imp05_selection_paths_retry = [
                        {
                            "section_id": sid,
                            "selection_path": t.get("selection_path"),
                            "selected_rank": t.get("selected_rank"),
                            "selected_template_id": t.get("selected_template_id"),
                            "fallback_trigger": (
                                t.get("fallback_reason") if t.get("fallback_used") else None
                            ),
                        }
                        for sid, t in v4_fallback_traces.items()
                    ]
                    comp_debug["v4_fallback_selections"] = list(v4_fallback_traces.values())
                    if "v4_fallback_summary" in comp_debug:
                        comp_debug["v4_fallback_summary"]["selection_paths"] = (
                            _imp05_selection_paths_retry
                        )
                    print(
                        f"  [IMP-30 u4] provisional retry recovered {len(units)} unit(s) "
                        f"— first-render invariant preserved.",
                        file=sys.stderr,
                    )

            if not provisional_recovered:
                # Phase B — Emergency P3 (2026-05-26) — generic_fallback unit (universal,
                # mdx 별 dispatch 금지). No rank-1 V4 evidence for any section, or override
                # path produced no renderable assignments.
                #
                # 이전 (IMP-30 u4 terminal) : empty_shell unit (frame_template_id="__empty__",
                # selection_path="empty_shell") — 빈 slide. AI adaptation 도달 X.
                # 신 정책 (emergency.md §1 lock) : empty shell 금지. real catalog frame
                # (GENERIC_FALLBACK_FRAME_TEMPLATE_ID) + provisional=True (needs adaptation)
                # + label="reject" (status → ai_adaptation_required) + selection_path=
                # "generic_fallback". 원문 텍스트 보존, AI 가 frame slot 에 재배치 (P4 routing).
                run_dir.mkdir(parents=True, exist_ok=True)
                _fallback_reason = (
                    "no_rank_1_V4_evidence_in_any_section"
                    if section_assignment_plan is None
                    else "section_assignment_override_yielded_no_renderable_units"
                )
                generic_fallback_units, _p3_fallback_trace = (
                    _build_emergency_p3_generic_fallback_units(
                        sections=sections,
                        fallback_reason=_fallback_reason,
                        section_assignment_plan=section_assignment_plan,
                        plan_unit_by_position=(
                            plan_unit_by_position
                            if section_assignment_plan is not None
                            else None
                        ),
                    )
                )
                units = generic_fallback_units
                _fallback_layout_rederive_skipped = bool(
                    layout_override_applied or section_assignment_plan is not None
                )
                if not _fallback_layout_rederive_skipped:
                    layout_preset = select_layout_preset(units)
                comp_debug["emergency_p3_generic_fallback"] = {
                    "applied": True,
                    "frame_template_id": GENERIC_FALLBACK_FRAME_TEMPLATE_ID,
                    "reason": _fallback_reason,
                    "aligned_section_ids": [s.section_id for s in sections],
                    **_p3_fallback_trace,
                    "fallback_layout_rederive_skipped": _fallback_layout_rederive_skipped,
                    "layout_preset_after_fallback": layout_preset,
                    "ai_adaptation_required": True,
                }
                print(
                    f"\n[Phase Z-2 Emergency P3] GENERIC_FALLBACK @ composition_planner",
                    file=sys.stderr,
                )
                print(
                    f"  reason : {_fallback_reason}",
                    file=sys.stderr,
                )
                print(
                    f"  frame  : {GENERIC_FALLBACK_FRAME_TEMPLATE_ID} (ai_adaptation_required) "
                    f"(sections={[s.section_id for s in sections]})",
                    file=sys.stderr,
                )

        # IMP-48 (#77) — re-split merged-reject units into per-section singles.
        # One-shot, deterministic (AI=0) post-pass. Fires AFTER all Step 6 settling
        # chains (initial plan_composition / u12 mixed admission / u4 provisional
        # retry / empty-shell) and AFTER section_assignment_plan is known, but
        # BEFORE the Step 6 artifact write below — so the artifact reflects the
        # post-resplit unit list. SKIPS when --override-section-assignments is
        # active (IMP-06 / #6 is the ground truth). Helper guardrails (coverage
        # equality / beneficial split / layout cap ≤ 4) keep mdx03 byte-identical
        # (no-op on use_as_is / light_edit slides). u5 re-derives layout_preset
        # below using the audit payload.
        units, _imp48_audit = resplit_all_reject_merges(
            units,
            sections,
            lookup_fn,
            V4_LABEL_TO_PHASE_Z_STATUS,
            MVP1_ALLOWED_STATUSES,
            capacity_fit_fn=compute_capacity_fit,
            v4_candidates_lookup_fn=candidates_lookup_fn,
            section_assignment_override=section_assignment_plan is not None,
        )
        comp_debug["imp48_resplit"] = _imp48_audit
        # u5 — re-derive layout_preset from helper audit (post-split count via
        # select_layout_preset(out_units)). Helper guarantees post_split_unit_count
        # ≤ 4 (layout cap abort), so the derived preset is always renderable by
        # LAYOUT_PRESETS. Respect --override-layout when present (user's explicit
        # choice wins over auto-redrive; mirrors the override gate above at L3697).
        if _imp48_audit.get("applied"):
            _imp48_post_preset = _imp48_audit.get("post_split_layout_preset")
            if _imp48_post_preset and not layout_override_applied:
                if _imp48_post_preset != layout_preset:
                    print(
                        f"  [IMP-48] layout_preset re-derived: {layout_preset} → "
                        f"{_imp48_post_preset} (post-split unit count="
                        f"{_imp48_audit.get('post_split_unit_count')})",
                        file=sys.stderr,
                    )
                    layout_preset = _imp48_post_preset
            print(
                f"  [IMP-48] re-split applied — "
                f"split={len(_imp48_audit.get('split_units', []))} "
                f"skipped={len(_imp48_audit.get('skipped_units', []))} "
                f"post_count={_imp48_audit.get('post_split_unit_count')} "
                f"post_preset={_imp48_audit.get('post_split_layout_preset')!r}",
                file=sys.stderr,
            )

        # Task 10 (2026-05-28): no-drop coverage repair.
        # If Step 6 still leaves aligned sections uncovered, keep the existing
        # auto selections and append source-order generic fallback units for
        # the missing sections. This is not a quality/final-fit solution; it
        # prevents silent section loss so Task 11 can improve the structure.
        _covered_after_resplit = {
            sid
            for _unit in units
            for sid in (getattr(_unit, "source_section_ids", []) or [])
        }
        _uncovered_sections = [
            s for s in sections if s.section_id not in _covered_after_resplit
        ]
        if _uncovered_sections:
            from src.phase_z2_composition import CompositionUnit as _CompositionUnit
            _fallback_added_units = []
            for _group_id, _group_sections in _group_sections_by_top_level_parent(_uncovered_sections):
                _fallback_candidates = lookup_catalog_fallback_candidates(_group_id)
                _fallback_added_units.append(_CompositionUnit(
                    source_section_ids=[s.section_id for s in _group_sections],
                    merge_type="no_drop_fallback_group",
                    frame_template_id=GENERIC_FALLBACK_FRAME_TEMPLATE_ID,
                    frame_id=GENERIC_FALLBACK_FRAME_ID,
                    frame_number=0,
                    confidence=0.0,
                    label="reject",
                    phase_z_status="fallback_candidate",
                    raw_content="\n\n".join((s.raw_content or "") for s in _group_sections),
                    title=" / ".join((s.title or "") for s in _group_sections) or _group_id,
                    v4_rank=None,
                    selection_path="no_drop_fallback",
                    fallback_reason="task10_uncovered_aligned_section",
                    score=0.0,
                    v4_candidates=_fallback_candidates,
                    rationale={
                        "task10": "no_drop_coverage_repair",
                        "reason": "aligned_section_not_covered_by_step6",
                        "top_level_group_id": _group_id,
                        "aligned_section_ids": [s.section_id for s in _group_sections],
                    },
                    provisional=True,
                ))
            _candidate_units = list(units) + _fallback_added_units
            try:
                _candidate_preset = select_layout_preset(_candidate_units)
            except ValueError as exc:
                comp_debug["task10_no_drop_repair"] = {
                    "applied": False,
                    "reason": "layout_cap_exceeded",
                    "uncovered_section_ids": [s.section_id for s in _uncovered_sections],
                    "error": str(exc),
                }
            else:
                units = _candidate_units
                if not layout_override_applied:
                    layout_preset = _candidate_preset
                comp_debug["task10_no_drop_repair"] = {
                    "applied": True,
                    "added_units": [
                        {
                            "source_section_ids": list(u.source_section_ids),
                            "frame_template_id": u.frame_template_id,
                            "selection_path": u.selection_path,
                        }
                        for u in _fallback_added_units
                    ],
                    "layout_preset": layout_preset,
                }

        if section_assignment_plan is None:
            units, sections_for_status, _task14_audit = _collapse_units_to_parent_sections(
                units,
                sections,
                parent_sections_for_task14,
                fallback_template_id=GENERIC_FALLBACK_FRAME_TEMPLATE_ID,
                fallback_frame_id=GENERIC_FALLBACK_FRAME_ID,
            )
            comp_debug["task14_parent_section_units"] = _task14_audit
            try:
                _task14_preset = select_layout_preset(units)
            except ValueError as exc:
                comp_debug["task14_parent_section_units"]["layout_error"] = str(exc)
            else:
                if not layout_override_applied:
                    layout_preset = _task14_preset
                    auto_layout_preset = layout_preset
        else:
            sections_for_status = sections
            comp_debug["task14_parent_section_units"] = {
                "applied": False,
                "reason": "section_assignment_override_active",
            }

        print(f"  preset  : {layout_preset} ({len(units)} units, composition v0 count-based)")
        for u in units:
            print(f"    unit  : {u.source_section_ids} merge={u.merge_type} → "
                  f"frame {u.frame_number} ({u.frame_template_id}) "
                  f"label={u.label} score={u.score:.3f}")

        # ─── Step 6: Composition Planning ───
        _write_step_artifact(
            run_dir, 6, "composition_plan",
            data={
                "selected_units_count": len(units),
                "layout_preset_decided": layout_preset,
                "candidates_summary": comp_debug.get("candidates_summary"),
                "candidates_total": comp_debug.get("candidates_total"),
                "candidates_viable_auto": comp_debug.get("candidates_viable_auto"),
                "selected_units": [
                    {
                        "source_section_ids": u.source_section_ids,
                        "merge_type": u.merge_type,
                        "frame_id": u.frame_id,
                        "frame_number": u.frame_number,
                        "frame_template_id": u.frame_template_id,
                        "label": u.label,
                        "v4_rank": u.v4_rank,
                        "selection_path": u.selection_path,
                        "fallback_reason": u.fallback_reason,
                        "score": u.score,
                        "phase_z_status": u.phase_z_status,
                        "rationale": u.rationale,
                        "notes": list(u.notes),
                        # Step 6-A axis (사용자 lock 2026-05-08) — V4 후보 list.
                        # 단일 frame_* / label / confidence 와 일관 (candidates[0] = rank-1 non-reject).
                        "v4_candidates": [
                            {
                                "template_id": c.template_id,
                                "frame_id": c.frame_id,
                                "frame_number": c.frame_number,
                                "confidence": c.confidence,
                                "label": c.label,
                                "candidate_status": getattr(c, "candidate_status", None),
                                "coverage_state": _candidate_coverage_state(
                                    getattr(c, "candidate_status", None),
                                    label=c.label,
                                    catalog_registered=get_contract(c.template_id) is not None,
                                    selection_path=getattr(c, "selection_path", None),
                                ),
                            }
                            for c in u.v4_candidates
                        ],
                    }
                    for u in units
                ],
                # IMP-48 (#77) — re-split audit. Additive field. AI=0 deterministic
                # one-shot post-pass on Step 6 settling result. applied=True means
                # ≥1 parent_merged / parent_merged_inferred reject unit was split
                # into per-section singles; selected_units already reflects the
                # post-split list. Skipped reasons (incomplete_rebuild /
                # no_beneficial_split / layout_cap_exceeded) keep the merged unit
                # for IMP-47B (#76) AI handoff. section_assignment_override skip
                # honors IMP-06 (#6) zoneSections ground truth.
                "imp48_resplit": _imp48_audit,
                "emergency_p3_generic_fallback": comp_debug.get("emergency_p3_generic_fallback"),
                "task14_parent_section_units": comp_debug.get("task14_parent_section_units"),
                # IMP-43 (#72) u3 — additive informational field recording the
                # run_dir-relative location of the ``--reuse-from`` sidecar
                # (written immediately after this artifact). Path is stamped
                # unconditionally so that a future ``--reuse-from`` consumer
                # (u4) can locate the expected sidecar even when its write
                # failed (u4 then fail-closes on missing/invalid sidecar via
                # u2's ``validate_snapshot``).
                "reuse_snapshot_path": SNAPSHOT_FILENAME,
            },
            step_status="done",
            pipeline_path_connected=True,
            inputs=["step02_normalized.json", "step05_v4_evidence.json"],
            outputs=["step06_composition_plan.json", SNAPSHOT_FILENAME],
            note=(
                "composition v0 count-based — sections → candidates → score → greedy select. "
                "Step 6-A (사용자 lock 2026-05-08): selected_units[i].v4_candidates 추가 "
                "(non-reject max-6 후보 list, candidates[0] = 단일 frame_* 와 일관). "
                "IMP-48 (#77, 2026-05-22): merged-reject 자동 분리 post-pass — "
                "parent_merged / parent_merged_inferred + label=reject + ≥2 sections "
                "→ per-section singles (each own rank-1 V4 evidence + raw_content 보존). "
                "guardrails: coverage equality / beneficial split (≥1 non-reject) / "
                "layout cap (≤4 units). imp48_resplit audit additive. "
                "logic 무변 — runtime 결과 동일. Step 9 application_plan input. "
                "IMP-43 (#72) u3: _reuse_snapshot.json sidecar written next to "
                "this artifact (run_dir level) for future --reuse-from (u4) "
                "consumption. Optional sidecar — write failure warns + continues."
            ),
        )

        # IMP-43 (#72) u3 — write Step 6 reuse snapshot sidecar AFTER the
        # step06 artifact. The sidecar captures the in-memory state that
        # downstream steps need but that the canonical step02 / step05 /
        # step06 artifacts do not preserve in a deserialize-ready form (e.g.
        # ``CompositionUnit`` instances, raw ``comp_debug``, untruncated
        # ``v4_fallback_traces``, pre-override ``layout_preset``). Helper
        # warns + returns ``None`` on failure — does NOT abort the run.
        # Restore wiring (``--reuse-from``) lands in u4.
        _write_reuse_snapshot(
            run_dir,
            mdx_source_text=mdx_source_text,
            slide_title=slide_title,
            slide_footer=slide_footer,
            sections=sections,
            stage0_adapter_diagnostics=stage0_adapter_diagnostics,
            stage0_normalized_assets=stage0_normalized_assets,
            v4_evidence=v4_evidence_list,
            layout_preset_pre_override=layout_preset,
            units=units,
            comp_debug=comp_debug,
            v4_fallback_traces=v4_fallback_traces,
            ai_preflight=ai_preflight,
        )
    else:
        # IMP-43 (#72) u5 — reuse path: restore Steps 0/1/2/5/6 state
        # from prev_run snapshot. u4b's execute_reuse_from_or_fail_closed
        # handles all nine fail-closed axes (prev_run_dir_missing,
        # snapshot_corrupt_json, mdx_sha256_mismatch, etc.) — on success
        # it returns ``(prev_run_dir, copied_artifacts, snapshot)``;
        # any reachable failure terminates the process before this branch
        # binds a local.
        #
        # State variable shape matches the locals produced by Steps 0-6
        # above so the Step 7+ block reads them transparently:
        #   ai_preflight                : Step 0 preflight dict
        #   slide_title / slide_footer  : parse_mdx output
        #   sections                    : list[MdxSection], post-align
        #   stage0_adapter_diagnostics  : Stage 0 adapter trace dict
        #   stage0_normalized_assets    : Step 3 handoff dict (popups/...)
        #   v4_evidence_list            : list[dict] (Step 5 artifact)
        #   layout_preset               : Step 6 post-IMP-48 preset
        #   units                       : list[CompositionUnit]
        #   comp_debug                  : Step 6 debug dict
        #   v4_fallback_traces          : dict[sid -> trace dict]
        #
        # NOT serialized (deterministic from external sources or restored
        # sections — recomputed here):
        #   v4                  : load_v4_result() — V4_RESULT_PATH on disk
        #   section_alias_by_id : derived from restored sections
        #
        # u1 guard ensures override_layout is None on the reuse path, so
        # layout_override_applied / auto_layout_preset reflect the
        # restored Step 6 preset for the Step 7 artifact.
        mdx_source_text = mdx_path.read_text(encoding="utf-8")
        (run_dir / "steps").mkdir(exist_ok=True)
        _prev_run_dir, _copied_artifacts, _snapshot = execute_reuse_from_or_fail_closed(
            reuse_from=reuse_from,
            new_run_dir=run_dir,
            mdx_source_text=mdx_source_text,
        )
        ai_preflight = _snapshot["ai_preflight"]["value"]
        slide_title = _snapshot["slide_title"]["value"]
        slide_footer = _snapshot["slide_footer"]["value"]
        sections = _rehydrate_mdx_sections_from_snapshot(_snapshot)
        sections_for_status = sections
        stage0_adapter_diagnostics = _snapshot["stage0_adapter_diagnostics"]["value"]
        stage0_normalized_assets = _snapshot["stage0_normalized_assets"]["value"]
        v4_evidence_list = _snapshot["v4_evidence"]["value"]
        layout_preset = _snapshot["layout_preset_pre_override"]["value"]
        units = _rehydrate_composition_units_from_snapshot(_snapshot)
        comp_debug = _snapshot["comp_debug"]["value"]
        v4_fallback_traces = _snapshot["v4_fallback_traces"]["value"]
        v4 = load_v4_result()
        section_alias_by_id = {
            s.section_id: list(getattr(s, "v4_alias_keys", []) or [])
            for s in sections
        }
        auto_layout_preset = layout_preset
        layout_override_applied = False
        # IMP-43 (#72) u4 fix — shared Step 7+ block reads
        # ``section_assignment_plan`` unconditionally at the render_records
        # gate below, and ``section_assignment_summary`` is mirrored into
        # comp_debug via the normal-path override branch. Both stay at
        # their "no override applied" defaults on the reuse path because
        # u1's fail-closed guard already rejected --override-section-
        # assignment when --reuse-from is set. Without these explicit
        # defaults the reuse branch falls through to ``if
        # section_assignment_plan is not None:`` (line ~5754) with an
        # unbound local and the run aborts with UnboundLocalError before
        # Step 7 can begin (see Codex #14 rewind report).
        section_assignment_plan: Optional[list[dict]] = None
        section_assignment_summary: Optional[dict] = None
        _write_reuse_marker(
            run_dir,
            prev_run_id=reuse_from,
            copied_artifacts=_copied_artifacts,
        )
        print(
            f"  reuse   : sections={len(sections)} "
            f"({[s.section_id for s in sections]}), "
            f"units={len(units)}, layout={layout_preset}, "
            f"prev_run_id={reuse_from}"
        )

    # 5. Per-unit: synthesize MdxSection → mapper → assets → zone data
    #    mapper FitError 는 catch — 자동 파이프라인은 다른 zone 계속 진행. abort X.
    positions = LAYOUT_PRESETS[layout_preset]["positions"]
    zones_data = []
    debug_zones = []
    asset_copy_traces: list[dict] = []
    adapter_needed_units: list[dict] = []

    # ── Step 7-A axis : frame override ──
    # {unit_id: template_id} 형식. unit_id 매칭 시 unit.frame_template_id 강제 변경.
    # v4_candidates 안에서 같은 template_id 를 가진 entry 를 찾으면 frame_id /
    # frame_number / confidence / label 까지 그 entry 에서 가져와 갱신 — 그래야 step09
    # artifact 의 메타가 일관됨. IMP-47B u3 (2026-05-21) : v4_candidates miss 시
    # 전 32 judgments 까지 probe — reject 라벨 frame 을 사용자가 선택한 경우
    # unit 을 provisional=True 로 승격해 Step 12 AI 재구성 게이트를 통과시킴
    # (frame 유지, 자동 frame swap 금지 — [[feedback_ai_isolation_contract]]).
    # frame contract 가 catalog 에 등록 안 된 template_id 면 skip + warning —
    # crash 방지 (V4 score 는 매겨지지만 catalog partial 은 없는 후보 존재).
    frame_overrides_applied: list[dict] = []
    frame_overrides_skipped: list[dict] = []
    if override_frames:
        for unit in units:
            unit_id = "+".join(unit.source_section_ids)
            if unit_id not in override_frames:
                continue
            new_tid = override_frames[unit_id]
            old_tid = unit.frame_template_id
            if new_tid == old_tid:
                continue
            # catalog contract 존재 확인 — 없으면 override 거부.
            new_contract = get_contract(new_tid)
            if new_contract is None:
                frame_overrides_skipped.append({
                    "unit_id": unit_id,
                    "from": old_tid,
                    "to": new_tid,
                    "reason": "no_frame_contract_in_catalog",
                })
                print(
                    f"  [override-skip] unit {unit_id}: '{new_tid}' has no entry in "
                    f"frame_contracts catalog — keeping {old_tid}",
                    file=sys.stderr,
                )
                continue
            meta_source = _apply_frame_override_to_unit(unit, new_tid, v4)
            frame_overrides_applied.append({
                "unit_id": unit_id,
                "from": old_tid,
                "to": new_tid,
                "meta_source": meta_source,
            })
            print(
                f"  [override] unit {unit_id} frame: {old_tid} → {new_tid} "
                f"({meta_source})",
                file=sys.stderr,
            )

    # IMP-06 blocker-fix (Codex #13/#14/#15/#16/#17) — build render_records AFTER
    # frame_overrides so each record points to the post-override CompositionUnit
    # object (Codex #15 Catch R). render_records is the canonical per-position
    # plan-derived view: cli_override / auto / empty / collision-skipped all carry
    # a record. `unit` is the same instance reference as in `units` when
    # renderable, otherwise None. This drives debug_zones/Step 9/Step 20 traces
    # without forcing None into the renderable `units` list.
    render_records: list[dict] = []
    if section_assignment_plan is not None:
        for entry in section_assignment_plan:
            pos = entry["position"]
            unit_ref = plan_unit_by_position.get(pos)
            render_records.append({
                "position": pos,
                "assignment_source": entry["assignment_source"],
                "unit": unit_ref,
                "source_section_ids": list(entry.get("source_section_ids") or []),
                "section_assignment_override": entry.get("section_assignment_override"),
                "replaced_auto_unit": entry.get("replaced_auto_unit"),
                "skipped_collided_auto_units": list(entry.get("skipped_collided_auto_units") or []),
                "uncovered_section_ids": list(entry.get("uncovered_section_ids") or []),
                "skipped_reason": entry.get("skipped_reason"),
            })

    # IMP-06 blocker-fix (Codex #13/#14/#15/#16/#17) — index render_records by
    # unit object identity so the renderable zones loop below can stamp each
    # zones_data / debug_zones entry with plan-aware fields (assignment_source,
    # section_assignment_override, replaced_auto_unit, skipped_collided_auto_units,
    # uncovered_section_ids, skipped_reason). Empty positions handled later by
    # the post-loop "empty zone records" block — those records carry the same
    # plan-aware fields directly from their plan entry.
    render_record_by_unit_id: dict[int, dict] = {}
    if render_records:
        for rec in render_records:
            u = rec.get("unit")
            if u is not None:
                render_record_by_unit_id[id(u)] = rec

    for i, unit in enumerate(units):
        position = positions[i] if i < len(positions) else f"zone_{i}"
        plan_record = render_record_by_unit_id.get(id(unit))
        # When render_records exists (override path) prefer its position to
        # guard against future drifts. positions[i] is the legacy auto path
        # and is byte-identical to plan_record.position in the normal case.
        if plan_record is not None and plan_record.get("position"):
            position = plan_record["position"]

        # IMP-30 u4 — empty-shell synthesized unit. frame_template_id="__empty__"
        # has no catalog contract by design; bypass mapper/contract path and emit
        # a placeholder zone record so render_slide() short-circuits to empty
        # partial_html (existing `__empty__` branch at render_slide:2106). The
        # slide_base still renders title + footer + empty grid cell so the
        # first-render invariant holds; u5 will surface the provisional flag as
        # a zone class + needs-adaptation badge.
        if unit.frame_template_id == "__empty__":
            # IMP-35 u7 — popup payload wiring. Empty-shell units never go
            # through the Step 17 POPUP gate (no raw content to escalate),
            # so compose_zone_popup_payload returns the no-popup branch
            # (has_popup=False, popup_html=None, preview_text=None).
            _popup_payload = compose_zone_popup_payload(unit, 0)
            zones_data.append({
                "position": position,
                "template_id": "__empty__",
                "slot_payload": {},
                "content_weight": {"score": 0},
                "min_height_px": 0,
                "assignment_source": "imp30_u4_empty_shell",
                "section_assignment_override": False,
                "provisional": bool(getattr(unit, "provisional", False)),
                # IMP-94 (#94) u4 — non-live empty-shell path. No
                # PlacementPlan exists for this branch (empty unit), so
                # default to ``[]`` matching the u2 call-site ``or []``
                # fallback. Keeps zone shape uniform; u1 stamper no-ops.
                "placement_markers": [],
                **_popup_payload,
            })
            debug_zones.append({
                "position": position,
                "source_section_ids": list(unit.source_section_ids),
                "merge_type": unit.merge_type,
                "title": unit.title,
                "v4_rank1_frame_id": unit.frame_id,
                "v4_rank1_frame_number": unit.frame_number,
                "v4_template_id": "__empty__",
                "v4_label": unit.label,
                "v4_confidence": float(unit.confidence or 0.0),
                "v4_selected_rank": unit.v4_rank,
                "selection_path": unit.selection_path,
                "fallback_reason": unit.fallback_reason,
                "fallback_used": False,
                "phase_z_status": unit.phase_z_status,
                "composition_score": float(unit.score or 0.0),
                "composition_rationale": dict(unit.rationale or {}),
                "composition_notes": list(unit.notes),
                "mapper_type": "empty_shell",
                "contract_id": "__empty__",
                "contract_frame_id": None,
                "builder": None,
                "min_height_px": 0,
                "slot_payload_keys": [],
                "content_truncated_count": None,
                "assets_dir": None,
                "content_weight": {"score": 0},
                "placement_trace": None,
                "assignment_source": "imp30_u4_empty_shell",
                "section_assignment_override": False,
                "replaced_auto_unit": None,
                "skipped_collided_auto_units": [],
                "uncovered_section_ids": [],
                "skipped_reason": "imp30_u4_empty_shell_no_v4_evidence",
                "provisional": bool(getattr(unit, "provisional", False)),
            })
            continue

        synth_section = MdxSection(
            section_id="+".join(unit.source_section_ids),
            section_num=0,
            title=unit.title,
            raw_content=unit.raw_content,
        )
        contract = get_contract(unit.frame_template_id)
        builder_name = contract["payload"].get("builder")
        visual_hints = contract.get("visual_hints") or {}
        min_height_px = visual_hints.get("min_height_px", DEFAULT_ZONE_MIN_HEIGHT_PX)
        contract_frame_id = contract.get("frame_id")

        # ─── trace-only runtime 연결 v0 — B1 → B4 chain (final.html 영향 X) ───
        # B1~B4 의 dormant chain 을 *real MDX runtime data* 로 처음 호출.
        # 결과 (PlacementPlan) = debug_zones[i].placement_trace 로 *기록만*.
        # render path / mapper output / final.html 모두 미변경 — B5 baseline SHA 유지.
        # B4 frame selection = catalog declaration order (V4 evidence 미사용 — 별 axis).
        # Option 1 (PHASE_Z_B4_SOURCE_SHAPE_ENABLED, default OFF) : pilot = F13 top_bullets only.
        b4_source_shape_enabled = (
            os.environ.get("PHASE_Z_B4_SOURCE_SHAPE_ENABLED", "").strip().lower()
            in {"1", "true", "yes"}
        )
        b1_source_shape = (
            contract.get("source_shape")
            if b4_source_shape_enabled and contract.get("source_shape") == "top_bullets"
            else None
        )
        content_objects = extract_content_objects(synth_section, source_shape=b1_source_shape)
        content_weight = compute_content_weight(synth_section)
        # IMP-95 u4 — forward CompositionUnit.v4_candidates as B4 evidence.
        # Flag OFF (default) → plan_placement ignores the kwarg verbatim
        # (declaration-order parity, Stage 2 A1 + A10). Flag ON → routed
        # to _select_frame_v4_aware (u2) inside plan_placement. Defensive
        # getattr keeps non-CompositionUnit shapes working.
        unit_v4_candidates = getattr(unit, "v4_candidates", None) or None
        # IMP-95 u6 — partial_exists callable. Inside plan_placement the
        # callable is consulted ONLY when PHASE_Z_B4_V4_EVIDENCE is ON (the
        # V4-aware selector); flag OFF (default) ignores the kwarg verbatim,
        # so SHA parity (Stage 2 A10) and pre-u6 V4-aware behavior are both
        # preserved. _b4_partial_exists is a sibling of _load_frame_partial_html
        # — same templates/phase_z2/families/{id}.html convention.
        placement_plan = plan_placement(
            content_objects=content_objects,
            frame_contracts=list(load_frame_contracts().values()),
            section_id=synth_section.section_id,
            v4_candidates=unit_v4_candidates,
            partial_exists=_b4_partial_exists,
        )
        mapper_frame_template_id = unit.frame_template_id
        matches_mapper = (
            placement_plan.selected_template_id == mapper_frame_template_id
        )
        match_note: Optional[str] = None
        if not matches_mapper:
            if placement_plan.selected_template_id is None:
                match_note = "no_frame_covers_content_types"
            else:
                match_note = (
                    f"B4 selected '{placement_plan.selected_template_id}' but "
                    f"mapper uses '{mapper_frame_template_id}' (composition V4 rank-1)"
                )
        # IMP-95 u4 — hoist selection_trace keys to placement_trace top-level.
        # asdict(placement_plan) already nests ``selection_trace`` from u3; the
        # hoist is additive (Stage 2 A5 + A6) so downstream consumers (u5
        # gatekeeper, u10 trace-field regression) can read presence/type at the
        # outer dict without traversing nested keys. Under flag OFF the values
        # are the declaration_order defaults, so the new top-level keys exist
        # on every code path (asserted by u4 tests).
        _b4_selection_trace = getattr(placement_plan, "selection_trace", None) or {}
        placement_trace = {
            **asdict(placement_plan),
            "mapper_frame_template_id": mapper_frame_template_id,
            "frame_selection_matches_mapper": matches_mapper,
            "frame_selection_match_note": match_note,
            TRACE_KEY_FRAME_SELECTION_BASIS: _b4_selection_trace.get(
                TRACE_KEY_FRAME_SELECTION_BASIS
            ),
            TRACE_KEY_V4_EVIDENCE_CONSUMED: _b4_selection_trace.get(
                TRACE_KEY_V4_EVIDENCE_CONSUMED, False
            ),
            TRACE_KEY_V4_RANK_USED: _b4_selection_trace.get(TRACE_KEY_V4_RANK_USED),
            TRACE_KEY_V4_B4_FRAME_MATCH: _b4_selection_trace.get(
                TRACE_KEY_V4_B4_FRAME_MATCH, False
            ),
            TRACE_KEY_B4_V0_FALLBACK_REASON: _b4_selection_trace.get(
                TRACE_KEY_B4_V0_FALLBACK_REASON
            ),
            TRACE_KEY_B4_PARTIAL_MISSING_SKIP: _b4_selection_trace.get(
                TRACE_KEY_B4_PARTIAL_MISSING_SKIP, []
            ),
        }
        # ─── end trace-only runtime 연결 v0 ───

        # ─── IMP-95 u5 — v4_short_circuit derived telemetry ─────────
        # True iff V4 evidence was consumed (PHASE_Z_B4_V4_EVIDENCE flag
        # ON + a V4 rank resolved) AND the resulting B4 selection matches
        # the mapper's V4 rank-1 template_id. Records the V4-driven path
        # that would otherwise require gatekeeper adjudication on the
        # legacy declaration-order branch. The gatekeeper logic itself
        # (next block) is UNCHANGED — PHASE_Z_B4_V4_EVIDENCE and
        # PHASE_Z_B4_GATEKEEPER remain independent flags (Stage 2 A7 + A8 :
        # flag independence preserved; gatekeeper still triggers purely
        # on ``not matches_mapper`` regardless of V4 path). Default OFF
        # for PHASE_Z_B4_V4_EVIDENCE keeps ``v4_evidence_consumed=False``
        # → ``v4_short_circuit=False`` on every code path, preserving the
        # IMP-95 u8 final.html SHA parity precondition.
        v4_short_circuit = bool(
            placement_trace[TRACE_KEY_V4_EVIDENCE_CONSUMED]
            and matches_mapper
        )
        placement_trace["v4_short_circuit"] = v4_short_circuit

        # ─── B4 gatekeeper (Q-V4B4 / PHASE_Z_B4_GATEKEEPER, default OFF) ───
        if (
            os.environ.get("PHASE_Z_B4_GATEKEEPER", "").strip().lower()
            in {"1", "true", "yes"}
            and not matches_mapper
        ):
            adapter_record = {
                "position": position,
                "source_section_ids": unit.source_section_ids,
                "merge_type": unit.merge_type,
                "template_id": unit.frame_template_id,
                "reason": "v4_b4_mismatch",
                "v4_short_circuit": v4_short_circuit,
                "mismatch_detail": {
                    "v4_template_id": mapper_frame_template_id,
                    "b4_selected_template_id": placement_plan.selected_template_id,
                    "match_note": match_note,
                },
            }
            adapter_needed_units.append(adapter_record)
            print(f"  adapter : zone--{position} {unit.source_section_ids} → "
                  f"{unit.frame_template_id} v4_b4_mismatch → adapter_needed (skip render)")
            continue
        # ─── end B4 gatekeeper ───

        # ─── IMP-89 89-a u2 — slot_payload source-of-truth switch ───
        # PHASE_Z_B4_MAPPER_SOURCE (u1 flag, default OFF):
        #   ON  → mapper input = B4 PlacementPlan.selected_template_id
        #         (Layer A render-active; B4 drives slot_payload)
        #   OFF → mapper input = unit.frame_template_id (legacy mapper-only /
        #         V4 rank-1; byte-equivalent default — final.html SHA parity
        #         guarded by u4)
        # u3 layers BLOCKED exits for (selected_template_id is None OR
        # FitError on B4-selected template) under flag ON — NO silent
        # fallback (IMP-87 honesty gate pattern). Under flag OFF semantics
        # preserved verbatim.
        mapper_template_id = _select_mapper_template_id(
            placement_plan, unit.frame_template_id
        )

        # IMP-89 89-a u3 — BLOCKED exit on B4 no-cover under flag ON.
        # When PHASE_Z_B4_MAPPER_SOURCE=ON and PlacementPlan produced no
        # covering frame, refuse to fall back to the legacy V4 rank-1 mapper
        # input. NO silent fallback (Stage 1 Q2 lock; IMP-87 honesty gate
        # pattern). Under flag OFF this branch is never entered, so the
        # default render path remains byte-identical.
        if _b4_mapper_source_enabled() and mapper_template_id is None:
            _b4_mapper_source_blocked_exit(
                "b4_no_cover",
                position=position,
                context={
                    "unit": (
                        f"source_section_ids={list(unit.source_section_ids)} "
                        f"merge_type={unit.merge_type}"
                    ),
                    "v4_rank1": unit.frame_template_id,
                    "b4_pick": placement_plan.selected_template_id,
                },
            )

        # mapper 시도 — 실패 (FitError) 시 zone 을 adapter_needed 로 표시하고 skip
        try:
            slot_payload = map_mdx_to_slots(synth_section, mapper_template_id)
        except FitError as e:
            _fit_error_str = str(e)
            # IMP-89 89-a u3 — BLOCKED exit on B4-selected FitError under flag
            # ON. When PHASE_Z_B4_MAPPER_SOURCE=ON the mapper rejecting the
            # B4-selected template is a Layer A honesty failure — adapter_needed
            # would mask it (Stage 1 Q2 lock). Under flag OFF the legacy
            # adapter_needed silent-fallback path executes unchanged.
            if _b4_mapper_source_enabled():
                _b4_mapper_source_blocked_exit(
                    "b4_selected_fit_error",
                    position=position,
                    context={
                        "template": f"{mapper_template_id} (B4 selected)",
                        "unit": (
                            f"source_section_ids={list(unit.source_section_ids)}"
                        ),
                        "v4_rank1": unit.frame_template_id,
                        "fit_error": _fit_error_str,
                    },
                )
            _unit_provisional = bool(getattr(unit, "provisional", False))

            # Emergency P4 (2026-05-26) — inline AI redistribute for ai_adaptation_required units.
            # FitError + (provisional unit OR generic_fallback OR reject label) → 직접 anthropic
            # 호출 → JSON slot_payload 받아서 zones_data 에 actual frame_template_id 로 emit.
            # 정책 (emergency.md §1): empty_shell 금지. 실패 시 기존 adapter_needed path 로 fallback.
            _ai_eligible = (
                _unit_provisional
                or getattr(unit, "label", None) == "reject"
                or getattr(unit, "selection_path", None) in ("generic_fallback", "ai_adaptation_required")
            )
            # Emergency P4b (2026-05-26) — code-side verbatim builder 먼저 시도.
            # AI 호출 X, mdx 원문 verbatim 만, frame schema 에 맞춰 배치.
            _prefer_generic_verbatim = (
                _unit_provisional
                or getattr(unit, "label", None) == "reject"
                or "fallback" in str(getattr(unit, "selection_path", "") or "")
            )
            _verbatim_candidates = [unit.frame_template_id, GENERIC_FALLBACK_FRAME_TEMPLATE_ID]
            _verbatim_payload = None
            _verbatim_template_id = unit.frame_template_id
            _verbatim_reason = "fit_error_recovered_by_code_verbatim"
            for _candidate_template_id in dict.fromkeys(_verbatim_candidates):
                _verbatim_payload = _emergency_p4b_build_verbatim_slot_payload(
                    unit, _candidate_template_id,
                )
                if _verbatim_payload is not None:
                    _verbatim_template_id = _candidate_template_id
                    if _candidate_template_id != unit.frame_template_id:
                        _verbatim_reason = "fit_error_recovered_by_task11d_generic_verbatim"
                    break
            if _verbatim_payload is not None:
                _expansion_trace = _frame_expansion_trace(
                    _verbatim_template_id, _verbatim_payload
                )
                _assets_dir = copy_assets(
                    _verbatim_template_id,
                    run_dir,
                    trace=asset_copy_traces,
                )
                print(
                    f"  [Emergency P4b] verbatim slot_payload built: {position} → {unit.frame_template_id}",
                    file=sys.stderr,
                )
                _placeholder_popup = compose_zone_popup_payload(unit, 0)
                zones_data.append({
                    "position": position,
                    "template_id": _verbatim_template_id,
                    "slot_payload": _verbatim_payload,
                    "content_weight": content_weight,
                    "min_height_px": min_height_px,
                    "assignment_source": "emergency_p4b_verbatim_code",
                    "section_assignment_override": False,
                    "provisional": _unit_provisional,
                    "verbatim_builder": True,
                    "verbatim_builder_reason": _verbatim_reason,
                    "verbatim_builder_original_template_id": unit.frame_template_id,
                    "coverage_state": _expansion_trace["coverage_state"],
                    "frame_expansion_trace": _expansion_trace,
                    "assets_dir": str(_assets_dir.relative_to(run_dir)) if _assets_dir else None,
                    "mapper_fit_error": _fit_error_str,
                    # IMP-94 (#94) u4 — non-live Emergency P4b verbatim
                    # code path. No PlacementPlan reaches this branch
                    # (fit_error recovered by code), so default to ``[]``
                    # matching the u2 call-site ``or []`` fallback. u1
                    # stamper no-ops; zone shape stays uniform.
                    "placement_markers": [],
                    **_placeholder_popup,
                })
                debug_zones.append({
                    "position": position,
                    "source_section_ids": list(unit.source_section_ids),
                    "merge_type": unit.merge_type,
                    "title": unit.title,
                    "v4_rank1_frame_id": unit.frame_id,
                    "v4_rank1_frame_number": unit.frame_number,
                    "v4_rank1_template_id": unit.frame_template_id,
                    "v4_template_id": unit.frame_template_id,
                    "template_id": _verbatim_template_id,
                    "render_template_id": _verbatim_template_id,
                    "label": unit.label,
                    "verbatim_builder": True,
                    "content_weight": content_weight,
                    "min_height_px": min_height_px,
                    "slot_payload_keys": sorted(_verbatim_payload.keys()),
                    "verbatim_builder_reason": _verbatim_reason,
                    "coverage_state": _expansion_trace["coverage_state"],
                    "frame_expansion_trace": _expansion_trace,
                    "assets_dir": str(_assets_dir.relative_to(run_dir)) if _assets_dir else None,
                    # issue #10 — IMP-95 B4 trace 를 P4b verbatim 복구 경로에서도
                    # 보존. placement_trace 는 같은 iteration 의 L8913 에서 이미
                    # 계산됨 (plan_placement 는 mapper FitError 이전에 실행) —
                    # 이 debug 기록 누락 때문에 flag ON 에서 v4_evidence_consumed
                    # 가 전 zone 에서 관측 불가였음 (u10 aggregate 실패 원인).
                    # debug_zones 전용 — zones_data / final.html 영향 X.
                    "placement_trace": placement_trace,
                })
                continue  # skip adapter_needed path — code 가 채움

            _ai_result = None
            if _ai_eligible:
                _ai_result = _emergency_p4_ai_redistribute(unit, unit.frame_template_id)
            if _ai_result is not None:
                _actual_template_id, _ai_slot_payload = _ai_result
                _swapped = _actual_template_id != unit.frame_template_id
                _assets_dir = copy_assets(
                    _actual_template_id,
                    run_dir,
                    trace=asset_copy_traces,
                )
                print(
                    f"  [Emergency P4] AI redistribute OK: {position} → {_actual_template_id}"
                    + (f" (swapped from {unit.frame_template_id})" if _swapped else ""),
                    file=sys.stderr,
                )
                _placeholder_popup = compose_zone_popup_payload(unit, 0)
                zones_data.append({
                    "position": position,
                    "template_id": _actual_template_id,
                    "slot_payload": _ai_slot_payload,
                    "content_weight": {"score": 0},
                    "min_height_px": min_height_px,
                    "assignment_source": "emergency_p4_ai_inline",
                    "section_assignment_override": False,
                    "provisional": _unit_provisional,
                    "ai_redistribute": True,
                    "ai_redistribute_reason": "fit_error_recovered_by_inline_ai",
                    "ai_redistribute_template_swap": _swapped,
                    "ai_redistribute_original_template_id": unit.frame_template_id,
                    "assets_dir": str(_assets_dir.relative_to(run_dir)) if _assets_dir else None,
                    "mapper_fit_error": _fit_error_str,
                    # IMP-94 (#94) u4 — non-live Emergency P4 inline-AI
                    # recovery path. No PlacementPlan reaches this branch
                    # (fit_error recovered by inline AI), so default to
                    # ``[]`` matching the u2 call-site ``or []`` fallback.
                    # u1 stamper no-ops; zone shape stays uniform.
                    "placement_markers": [],
                    **_placeholder_popup,
                })
                debug_zones.append({
                    "position": position,
                    "source_section_ids": list(unit.source_section_ids),
                    "merge_type": unit.merge_type,
                    "title": unit.title,
                    "v4_rank1_frame_id": unit.frame_id,
                    "v4_rank1_frame_number": unit.frame_number,
                    "v4_rank1_template_id": unit.frame_template_id,
                    "label": unit.label,
                    "ai_redistribute": True,
                    "ai_redistribute_actual_template": _actual_template_id,
                    "assets_dir": str(_assets_dir.relative_to(run_dir)) if _assets_dir else None,
                    # issue #10 — verbatim 경로와 동일: B4 placement_trace 보존
                    # (debug_zones 전용, render 영향 X).
                    "placement_trace": placement_trace,
                })
                continue  # skip adapter_needed path — AI 가 채움

            adapter_record = {
                "position": position,
                "source_section_ids": unit.source_section_ids,
                "merge_type": unit.merge_type,
                "template_id": unit.frame_template_id,
                "reason": "fit_error",
                "fit_error": _fit_error_str,
            }
            adapter_needed_units.append(adapter_record)
            # IMP-86 u1 — placeholder zones_data + debug_zone keep the failed
            # unit's preset position so downstream build_layout_css /
            # _compute_per_zone_geometry observe len(zones_data) == active
            # layout preset's css_areas rows (R). Without this both arrays
            # drift relative to R, raising
            # ValueError("heights_px length N != grid rows R=M") at
            # _compute_per_zone_geometry. Mirrors the IMP-30 empty-shell
            # pattern: zones_data uses template_id="__empty__" so render_slide
            # short-circuits to empty partial_html; debug_zone keeps the
            # original V4 evidence and adapter_needed_units stays the
            # authoritative adapter signal.
            # IMP-86 u5 — per-record telemetry. adapter_needed=True +
            # mapper_fit_error=<str(FitError)> + provisional mirror the
            # adapter signal directly on each placeholder record so
            # debug.json / final.html consumers can identify the adapter
            # contract surface from the zones array alone, without joining
            # against slide_status.adapter_needed_units. adapter_needed_units
            # itself is unchanged (still the authoritative per-slide list).
            _placeholder_popup = compose_zone_popup_payload(unit, 0)
            zones_data.append({
                "position": position,
                "template_id": "__empty__",
                "slot_payload": {},
                "content_weight": {"score": 0},
                "min_height_px": min_height_px,
                "assignment_source": "imp86_u1_adapter_needed",
                "section_assignment_override": False,
                "provisional": _unit_provisional,
                "adapter_needed": True,
                "mapper_fit_error": _fit_error_str,
                # IMP-94 (#94) u4 — non-live IMP-86 u1 adapter_needed
                # placeholder path. Unit skipped render (FitError →
                # adapter contract), so no PlacementPlan exists. Default
                # to ``[]`` matching the u2 call-site ``or []`` fallback.
                "placement_markers": [],
                **_placeholder_popup,
            })
            debug_zones.append({
                "position": position,
                "source_section_ids": list(unit.source_section_ids),
                "merge_type": unit.merge_type,
                "title": unit.title,
                "v4_rank1_frame_id": unit.frame_id,
                "v4_rank1_frame_number": unit.frame_number,
                "v4_template_id": unit.frame_template_id,
                "v4_label": unit.label,
                "v4_confidence": float(unit.confidence or 0.0),
                "v4_selected_rank": unit.v4_rank,
                "selection_path": unit.selection_path,
                "fallback_reason": unit.fallback_reason,
                "fallback_used": bool(unit.selection_path and "fallback" in unit.selection_path),
                "phase_z_status": unit.phase_z_status,
                "composition_score": float(unit.score or 0.0),
                "composition_rationale": dict(unit.rationale or {}),
                "composition_notes": list(unit.notes),
                "mapper_type": "adapter_needed",
                "contract_id": unit.frame_template_id,
                "contract_frame_id": contract_frame_id,
                "builder": builder_name,
                "min_height_px": min_height_px,
                "slot_payload_keys": [],
                "content_truncated_count": None,
                "assets_dir": None,
                "content_weight": {"score": 0},
                "placement_trace": placement_trace,
                "assignment_source": "imp86_u1_adapter_needed",
                "section_assignment_override": False,
                "replaced_auto_unit": None,
                "skipped_collided_auto_units": [],
                "uncovered_section_ids": [],
                "skipped_reason": "imp86_u1_adapter_needed_mapper_fit_error",
                "provisional": _unit_provisional,
                "adapter_needed": True,
                "mapper_fit_error": _fit_error_str,
            })
            print(f"  adapter : zone--{position} {unit.source_section_ids} → "
                  f"{unit.frame_template_id} FitError → adapter_needed (skip render)")
            continue

        run_dir.mkdir(parents=True, exist_ok=True)
        assets_dir = copy_assets(
            unit.frame_template_id,
            run_dir,
            trace=asset_copy_traces,
        )
        content_weight = compute_content_weight(synth_section)
        truncated_count = slot_payload.get("_truncated_count")  # builder 가 truncate 한 경우
        expansion_trace = _frame_expansion_trace(unit.frame_template_id, slot_payload)

        # IMP-06 blocker-fix (Codex #13/#14/#15/#16/#17) — plan-aware additive
        # fields. When no override CLI was used (plan_record is None), these
        # default to None/False/[] so pre-IMP-06 readers see byte-equivalent
        # data. Empty zone records appended below (post-loop) carry the same
        # field shape from their plan entry directly.
        plan_assignment_source = (
            plan_record.get("assignment_source") if plan_record else None
        )
        plan_section_override = (
            bool(plan_record.get("section_assignment_override"))
            if plan_record else False
        )
        plan_replaced_auto = (
            plan_record.get("replaced_auto_unit") if plan_record else None
        )
        plan_skipped_collided = list(
            plan_record.get("skipped_collided_auto_units") or []
        ) if plan_record else []
        plan_uncovered = list(
            plan_record.get("uncovered_section_ids") or []
        ) if plan_record else []
        plan_skipped_reason = (
            plan_record.get("skipped_reason") if plan_record else None
        )

        # IMP-30 u5 — `provisional` flag flows as data through V4Match (u1) →
        # CompositionUnit (u2) → zones_data here. slide_base.html reads
        # zone.provisional to apply the `zone--provisional` class + inline
        # needs-adaptation badge. Default False keeps non-provisional zones
        # byte-identical to pre-u5; only u1-synthesized rank-1 fills or u4
        # empty-shell synthesize provisional=True units.
        #
        # IMP-35 u7 — popup payload wiring. `compose_zone_popup_payload(unit,
        # min_height_px)` reads u6 binding (yaml strategy + popup_body_source)
        # AND derives a px-budgeted preview from min_height_px. Surfaces three
        # uniform render-context fields per zone (has_popup / popup_html /
        # preview_text) plus the full u6 binding under `popup_binding` for
        # u8 / u9 downstream consumers. Non-popup units (has_popup=False)
        # return the no-popup branch — byte-identical zone shape pre-u7.
        _popup_payload = compose_zone_popup_payload(unit, min_height_px)
        zones_data.append({
            "position": position,
            "template_id": unit.frame_template_id,
            "slot_payload": slot_payload,
            "content_weight": content_weight,
            "min_height_px": min_height_px,
            "assignment_source": plan_assignment_source,
            "section_assignment_override": plan_section_override,
            "provisional": bool(getattr(unit, "provisional", False)),
            "coverage_state": expansion_trace["coverage_state"],
            "frame_expansion_trace": expansion_trace,
            # IMP-94 (#94) u3 — live B4 PlacementPlan → marker dicts.
            # u1 stamper consumes only the first marker's region_id /
            # content_unit_id; frame_slot_id is reserved for #96 89-d.
            # Empty/None slot_assignments → [], so the u2 chain ``or []``
            # call-site fallback remains the deterministic no-op surface.
            "placement_markers": _derive_placement_markers(placement_plan),
            **_popup_payload,
        })
        debug_zones.append({
            "position": position,
            "source_section_ids": unit.source_section_ids,
            "merge_type": unit.merge_type,
            "title": unit.title,
            "v4_rank1_frame_id": unit.frame_id,
            "v4_rank1_frame_number": unit.frame_number,
            "v4_template_id": unit.frame_template_id,
            "v4_label": unit.label,
            "v4_confidence": unit.confidence,
            "v4_selected_rank": unit.v4_rank,
            "selection_path": unit.selection_path,
            "fallback_reason": unit.fallback_reason,
            "fallback_used": bool(unit.selection_path and "fallback" in unit.selection_path),
            "phase_z_status": unit.phase_z_status,
            "composition_score": unit.score,
            "composition_rationale": unit.rationale,
            "composition_notes": list(unit.notes),             # parent_merged_inferred 정보 신호
            "mapper_type": "contract",
            "contract_id": unit.frame_template_id,
            "contract_frame_id": contract_frame_id,
            "builder": builder_name,
            "min_height_px": min_height_px,
            "slot_payload_keys": sorted(slot_payload.keys()),
            "content_truncated_count": truncated_count,        # None / N (builder 가 N 개 자름)
            "coverage_state": expansion_trace["coverage_state"],
            "frame_expansion_trace": expansion_trace,
            "assets_dir": str(assets_dir.relative_to(run_dir)) if assets_dir else None,
            "content_weight": content_weight,
            # trace-only runtime 연결 v0 — B1 → B2 → B4 chain 결과 (render 미영향).
            "placement_trace": placement_trace,
            # IMP-06 blocker-fix — plan-aware additive fields.
            "assignment_source": plan_assignment_source,
            "section_assignment_override": plan_section_override,
            "replaced_auto_unit": plan_replaced_auto,
            "skipped_collided_auto_units": plan_skipped_collided,
            "uncovered_section_ids": plan_uncovered,
            "skipped_reason": plan_skipped_reason,
            # IMP-30 u5 — provisional signal mirror for debug.json consumers.
            "provisional": bool(getattr(unit, "provisional", False)),
        })

    # IMP-06 blocker-fix (Codex #10 Catch N) — append explicit empty zone records
    # for positions whose section-assignment plan produced no renderable unit
    # (cli_override with no resolvable template, ad-hoc multi-section,
    # override_collision whole-skip with no replacement, etc.). Empty records
    # preserve zone identity in zones_data/debug_zones (template_id="__empty__",
    # content_weight=0, min_height_px=0) so layout/grid stay structurally
    # consistent without distorting allocation, and the partial-render loop
    # short-circuits "__empty__" to an empty string (no TemplateNotFound).
    if render_records:
        renderable_positions = {z["position"] for z in zones_data}
        for record in render_records:
            pos = record["position"]
            if pos in renderable_positions:
                continue
            # IMP-35 u7 — popup payload wiring for unrenderable empty
            # plan record. No CompositionUnit exists for this branch
            # (section-assignment plan produced no unit), so we stamp the
            # no-popup defaults directly. Keeps the zone shape uniform
            # across all three append paths so slide_base.html (u8) does
            # not have to branch on the presence of popup fields.
            zones_data.append({
                "position": pos,
                "template_id": "__empty__",
                "slot_payload": {},
                "content_weight": {"score": 0},
                "min_height_px": 0,
                "assignment_source": "empty",
                "skipped_reason": (
                    record.get("skipped_reason")
                    or "section_assignment_override_empty_or_unrenderable"
                ),
                "has_popup": False,
                "popup_html": None,
                "preview_text": None,
                "popup_binding": None,
                # IMP-94 (#94) u4 — non-live post-loop unrenderable
                # plan-record path. No CompositionUnit / PlacementPlan
                # for this branch (section-assignment plan produced no
                # unit). Default to ``[]`` matching the u2 call-site
                # ``or []`` fallback. u1 stamper no-ops.
                "placement_markers": [],
            })
            debug_zones.append({
                "position": pos,
                "source_section_ids": list(record.get("source_section_ids") or []),
                "merge_type": "empty",
                "title": "",
                "v4_template_id": "__empty__",
                "v4_label": None,
                "v4_confidence": 0.0,
                "selection_path": "section_assignment_empty",
                "fallback_reason": None,
                "fallback_used": False,
                "phase_z_status": None,
                "composition_score": 0.0,
                "composition_rationale": {},
                "composition_notes": [],
                "mapper_type": "empty",
                "contract_id": "__empty__",
                "contract_frame_id": None,
                "assignment_source": record.get("assignment_source"),
                "skipped_reason": (
                    record.get("skipped_reason")
                    or "section_assignment_override_empty_or_unrenderable"
                ),
                "section_assignment_override": record.get("section_assignment_override"),
                "replaced_auto_unit": record.get("replaced_auto_unit"),
                "skipped_collided_auto_units": list(record.get("skipped_collided_auto_units") or []),
                "uncovered_section_ids": list(record.get("uncovered_section_ids") or []),
            })

    # ─── Step 3: Content Object 추출 (B1, trace-only) ───
    # IMP-03 — slide-level rich ContentObject 추출 (default OFF canary).
    # scope-lock 16 조건 (Gitea #3) :
    #   - 별 함수 (extract_rich_content_objects) — v0 extract_content_objects unchanged
    #   - slide-level — section_id=None, id=`{mdx_id}.{type}-N`, scope='slide'
    #   - root-level once (per-zone duplication X)
    #   - plan_placement() 는 v0 list 만 받음 (B4 회귀 X) — 본 rich 결과는 artifact only
    #   - transform_table dedup : arrow row 감지 시 skip
    rich_flag = os.environ.get("PHASE_Z_STEP3_RICH_OBJECTS_ENABLED", "").strip().lower()
    rich_enabled_flag = rich_flag in {"1", "true", "yes"}
    _assets_total = (
        len(stage0_normalized_assets.get("popups") or [])
        + len(stage0_normalized_assets.get("images") or [])
        + len(stage0_normalized_assets.get("tables") or [])
    )
    rich_disabled_reason: Optional[str] = None
    if not rich_enabled_flag:
        rich_disabled_reason = "FLAG_OFF"
    elif _assets_total == 0:
        rich_disabled_reason = "NO_NORMALIZED_ASSETS"

    rich_objects: list = []
    rich_skips: list = []
    if rich_disabled_reason is None:
        mdx_num_match = re.match(r"(\d+)", mdx_path.stem)
        rich_mdx_id = mdx_num_match.group(1).zfill(2) if mdx_num_match else "00"
        rich_objects, rich_skips = extract_rich_content_objects(
            stage0_normalized_assets, mdx_id=rich_mdx_id,
        )

    # Count/list invariant check (IMP-02 ↔ IMP-03 chain) — soft warning, no fail.
    invariant_warnings: list[dict] = []
    _adapter_counts = (stage0_adapter_diagnostics or {}).get("adapter_counts") or {}
    if _adapter_counts:
        for key in ("popups", "images", "tables"):
            expected = _adapter_counts.get(key)
            actual = len(stage0_normalized_assets.get(key) or [])
            if expected is not None and expected != actual:
                invariant_warnings.append({
                    "field": key,
                    "adapter_counts": expected,
                    "stage0_normalized_assets_len": actual,
                })

    _write_step_artifact(
        run_dir, 3, "content_objects",
        data={
            "per_zone": [
                {
                    "position": dz["position"],
                    "section_ids": dz["source_section_ids"],
                    "internal_regions": (dz.get("placement_trace") or {}).get("internal_regions") or [],
                }
                for dz in debug_zones
            ],
            # IMP-03 — slide-level rich trace (additive, trace-only).
            "rich_content_objects": [asdict(o) for o in rich_objects],
            "rich_content_objects_enabled": rich_disabled_reason is None,
            "rich_content_objects_scope": "slide",
            "rich_content_objects_source": "stage0_normalized_assets",
            "rich_content_objects_disabled_reason": rich_disabled_reason,
            "rich_content_objects_skips": rich_skips,
            "rich_content_objects_invariant_warnings": invariant_warnings,
        },
        step_status="trace-only",
        pipeline_path_connected=False,
        inputs=["step02_normalized.json"],
        outputs=["step03_content_objects.json"],
        note=(
            "현재는 trace 로 기록되지만 render payload 를 직접 만들지는 않음. "
            "mapper.py 가 별도로 MDX 직접 파싱. "
            "IMP-03 rich_content_objects = slide-level popup/image/table trace "
            "(PHASE_Z_STEP3_RICH_OBJECTS_ENABLED canary, default OFF)."
        ),
    )

    # ─── Step 4: Section Internal Composition (B2, trace-only) ───
    _write_step_artifact(
        run_dir, 4, "internal_composition",
        data={
            "per_zone": [
                {
                    "position": dz["position"],
                    "section_ids": dz["source_section_ids"],
                    "selected_template_id": (dz.get("placement_trace") or {}).get("selected_template_id"),
                    "frame_selection_matches_mapper": (dz.get("placement_trace") or {}).get("frame_selection_matches_mapper"),
                    "frame_selection_match_note": (dz.get("placement_trace") or {}).get("frame_selection_match_note"),
                }
                for dz in debug_zones
            ],
        },
        step_status="trace-only",
        pipeline_path_connected=False,
        inputs=["step03_content_objects.json"],
        outputs=["step04_internal_composition.json"],
        note="현재는 trace 로 기록되지만 render payload 를 직접 만들지는 않음. composition_planner_debug 가 main 결정 (Step 6).",
    )

    # ─── Step 9: Frame Selection (per zone) ───
    _write_step_artifact(
        run_dir, 9, "frame_selection",
        data={
            "per_zone": [
                {
                    "position": dz["position"],
                    "v4_rank1_frame_number": dz.get("v4_rank1_frame_number"),
                    "v4_selected_rank": dz.get("v4_selected_rank"),
                    "v4_template_id": dz.get("v4_template_id"),
                    "v4_confidence": dz.get("v4_confidence"),
                    "v4_label": dz.get("v4_label"),
                    "selection_path": dz.get("selection_path"),
                    "fallback_reason": dz.get("fallback_reason"),
                    "phase_z_status": dz.get("phase_z_status"),
                    "selected_template_id": dz.get("contract_id"),
                    "mapper_type": dz.get("mapper_type"),
                    "composition_score": dz.get("composition_score"),
                    "composition_rationale": dz.get("composition_rationale"),
                }
                for dz in debug_zones
            ],
        },
        step_status="partial",
        pipeline_path_connected=True,
        inputs=["step05_v4_evidence.json", "step06_composition_plan.json"],
        outputs=["step09_frame_selection.json", "step09_frame_matching_candidates.html"],
        note="V4 evidence 와 B4 통합 미완 — 별 axis. 현재 = composition planner 의 V4 rank-1 채택.",
    )
    # Step 9 HTML — V4 top candidates per zone (rank 1~4)
    # IMP-08 N-R6 diagnostic exemption : this report path is post-decision
    # reporting only. Runtime selection goes through _resolve_v4_section_key
    # (4 sites). Direct dict lookup here is intentional — debug_zones carries
    # dict-shape entries without v4_alias_keys plumbing, and a miss here only
    # yields a "V4 entry missing" report line (runtime impact zero).
    try:
        with open(V4_RESULT_PATH, encoding="utf-8") as _vf:
            _v4_full = yaml.safe_load(_vf)
        _v4_sections = (_v4_full or {}).get("mdx_sections", {}) or {}
    except Exception:
        _v4_sections = {}
    _candidates_html = ""
    # path from steps/ 에서 figma_to_html_agent/blocks/{frame_id}/index.html
    # steps → phase_z2 → run_id → runs → data → design_agent (5 levels up)
    _frame_iframe_base = "../../../../../figma_to_html_agent/blocks"
    for dz in debug_zones:
        _section_ids = dz.get("source_section_ids", [])
        _candidates_html += f"<h2>zone--{dz['position']} (sections: {', '.join(_section_ids)})</h2>"
        for _sid in _section_ids:
            _sec = _v4_sections.get(_sid)
            if not _sec:
                _candidates_html += f"<p>section <code>{_sid}</code>: V4 entry 없음</p>"
                continue
            _candidates_html += (
                f"<h3>section <code>{_sid}</code>: {_sec.get('mdx_title', '?')}</h3>"
                f"<p>answer_frame_number: <strong>{_sec.get('answer_frame_number', '-')}</strong>"
                f" | is_holdout: {_sec.get('is_holdout', '-')}</p>"
                f'<div style="display:grid;grid-template-columns:repeat(2,1fr);gap:16px;margin-bottom:24px;">'
            )
            for _j in (_sec.get("judgments_full32") or [])[:4]:
                _rank = _j.get("v4_full_rank")
                _frame_id = _j.get("frame_id")
                _frame_index = ASSETS_SOURCE_BASE / str(_frame_id) / "index.html"
                _has_preview = _frame_index.exists()
                _css = "candidate-card candidate-rank1" if _rank == 1 else "candidate-card"
                _preview_html = (
                    f'<div style="margin-top:8px;width:320px;height:180px;overflow:hidden;'
                    f'border:1px solid #cbd5e1;background:#fff;">'
                    f'<iframe src="{_frame_iframe_base}/{_frame_id}/index.html" '
                    f'style="width:1280px;height:720px;border:none;'
                    f'transform:scale(0.25);transform-origin:0 0;"></iframe>'
                    f'</div>'
                    if _has_preview else
                    f'<div style="margin-top:8px;width:320px;height:180px;'
                    f'border:1px dashed #cbd5e1;background:#f8fafc;display:flex;'
                    f'align-items:center;justify-content:center;color:#94a3b8;font-size:13px;">'
                    f'preview missing<br>'
                    f'(figma_to_html_agent/blocks/{_frame_id}/index.html 없음)'
                    f'</div>'
                )
                _candidates_html += (
                    f'<div class="{_css}">'
                    f'<strong>rank {_rank}: frame {_j.get("frame_number")} '
                    f'(<code>{_j.get("template_id")}</code>)</strong><br>'
                    f'confidence: {_j.get("confidence", 0):.4f} | '
                    f'label: <strong>{_j.get("label", "-")}</strong> | '
                    f'base: {_j.get("base", 0):.4f} | penalty: {_j.get("penalty", 0)}'
                    f'{_preview_html}'
                    f"</div>"
                )
            _candidates_html += "</div>"
    _write_step_html(
        run_dir, 9, "frame_matching_candidates",
        title="V4 Frame Matching Candidates (top 4 per section)",
        body_html=(
            f"<p>각 zone 의 source section 마다 V4 rank 1~4 후보 표시. "
            f"녹색 강조 = rank-1 (현재 선택된 frame).</p>{_candidates_html}"
        ),
        step_status="done",
        inputs=["step05_v4_evidence.json", "tests/matching/v4_full32_result.yaml"],
        outputs=["step09_frame_selection.json", "step09_frame_matching_candidates.html"],
    )

    # ─── Step 10: Frame Contract 확인 ───
    contracts_per_zone = []
    for dz in debug_zones:
        c = get_contract(dz.get("contract_id"))
        contracts_per_zone.append({
            "position": dz["position"],
            "contract_id": dz.get("contract_id"),
            "frame_id": (c or {}).get("frame_id"),
            "family": (c or {}).get("family"),
            "source_shape": (c or {}).get("source_shape"),
            "cardinality": (c or {}).get("cardinality"),
            "visual_hints": (c or {}).get("visual_hints"),
            "accepted_content_types": (c or {}).get("accepted_content_types"),
            "sub_zones": (c or {}).get("sub_zones"),
            "payload_builder": ((c or {}).get("payload") or {}).get("builder"),
            "payload_builder_options": ((c or {}).get("payload") or {}).get("builder_options"),
        })
    _write_step_artifact(
        run_dir, 10, "frame_contract",
        data={"per_zone": contracts_per_zone},
        step_status="partial",
        pipeline_path_connected=True,
        inputs=["step09_frame_selection.json", "templates/phase_z2/catalog/frame_contracts.yaml"],
        outputs=["step10_frame_contract.json"],
        note="full contract dict (sub_zones / cardinality / visual_hints 포함). density envelope 미선언 (별 axis).",
    )

    # ─── Step 11: Slot Mapping (B4 placement, trace-only) ───
    _write_step_artifact(
        run_dir, 11, "slot_mapping",
        data={
            "per_zone": [
                {
                    "position": dz["position"],
                    "selected_template_id": (dz.get("placement_trace") or {}).get("selected_template_id"),
                    "slot_assignments": (dz.get("placement_trace") or {}).get("slot_assignments") or [],
                    "rejection": (dz.get("placement_trace") or {}).get("rejection") or [],
                    "overflow_buffer": (dz.get("placement_trace") or {}).get("overflow_buffer") or [],
                }
                for dz in debug_zones
            ],
        },
        step_status="trace-only",
        pipeline_path_connected=False,
        inputs=["step04_internal_composition.json", "step10_frame_contract.json"],
        outputs=["step11_slot_mapping.json"],
        note="B4 PlacementPlan slot_assignments — render path 미연결. 실제 render slot 매핑은 mapper.py 의 builder.",
    )

    # ─── Step 12 IMP-47B u4 — AI repair proposal gather ───
    # Wire gather_step12_ai_repair_proposals so reject / restructure
    # provisional units reach the AI fallback router. Normal-path units
    # (use_as_is / light_edit / non-provisional) skip via the catch-all
    # route gate; flag-off runs short-circuit at the router. Stored locally
    # for u5 (PARTIAL_OVERRIDES apply) + u6 (step12_ai_repair.json audit).
    ai_repair_records = _run_step12_ai_repair(units)

    # ─── Step 12 IMP-47B u5 — Apply PARTIAL_OVERRIDES proposals ───
    # Mirror the per-unit position derivation from the render loop above
    # (L3789-3796); apply merges slots into zone slot_payload, loud-fails
    # unsupported kinds via apply_status marker.
    unit_positions: list[str] = []
    for _i, _unit in enumerate(units):
        _pos = positions[_i] if _i < len(positions) else f"zone_{_i}"
        _plan_record = render_record_by_unit_id.get(id(_unit))
        if _plan_record is not None and _plan_record.get("position"):
            _pos = _plan_record["position"]
        unit_positions.append(_pos)
    _apply_ai_repair_proposals_to_zones(
        ai_repair_records, unit_positions, zones_data, units=units,
    )

    # ─── Step 12 IMP-47B u7 — Post-AI source_section_ids coverage invariant ───
    # Structural defense: AI repair must not silently drop a unit's
    # source_section_ids. dropped 절대 룰 — text_block / table / image /
    # details deletion forbidden. Result feeds u6 audit (below) and
    # u8 slide_status.ai_repair_status surfacing.
    ai_repair_coverage_invariant = _check_post_ai_coverage_invariant(
        units, ai_repair_records,
    )

    # ─── Step 12 IMP-47B u6 — AI repair audit artifact ───
    # Persist per-unit gather/apply outcomes (route_hint, skip_reason,
    # apply_status, ai_called, proposal kind, cache_key, fingerprints)
    # so reviewers can audit which units reached the AI fallback router
    # and what happened. Flag-off default → every record has
    # ai_called=False + apply_status='no_proposal'; flag-on +
    # provisional reject/restructure → router_short_circuit (cache miss
    # without client) or applied:partial_overrides (cache hit / live AI).
    # u7 coverage_invariant rides alongside per_unit for reviewers.
    _write_step_artifact(
        run_dir, 12, "ai_repair",
        data={
            "per_unit": ai_repair_records,
            "coverage_invariant": ai_repair_coverage_invariant,
        },
        step_status="done",
        pipeline_path_connected=True,
        inputs=["step10_frame_contract.json", "step02_normalized.json"],
        outputs=["step12_ai_repair.json"],
        note="IMP-47B u6 — Step 12 AI repair gather + apply records per unit (route, skip_reason, apply_status, proposal). u7 coverage_invariant = pre/post AI source_section_ids set comparison.",
    )

    # ─── Step 12 IMP-56 #90 u5 — Apply persisted text_overrides ───
    # User text edits captured by the frontend (u12 capture path, pending)
    # re-apply here so the next render shows them without re-clicking.
    # Per-zone tolerant — stale ``text_path`` entries (frame swap / layout
    # regression) skip silently. raw_content preserved : the helper only
    # mutates ``zone["slot_payload"]`` ; ``debug_zones[i].source_section_ids``
    # + ``MdxSection`` graph untouched. Audit artifact emits BEFORE the
    # slot_payload artifact so reviewers see the post-override state.
    text_overrides_audit = _apply_text_overrides_to_zones(
        override_text_overrides or {}, zones_data,
    )
    _write_step_artifact(
        run_dir, 12, "text_overrides",
        data=text_overrides_audit,
        step_status="done",
        pipeline_path_connected=True,
        inputs=["data/user_overrides/*.json"],
        outputs=["step12_text_overrides.json"],
        note=(
            "IMP-56 #90 u5 — user text edit re-apply to slot_payload "
            "(per-zone tolerant; raw_content preserved). text_path = "
            "{slot_key}.{line_index} (u8 stamper contract)."
        ),
    )

    # ─── Step 12 IMP-56 #90 u7 — Apply persisted structure_overrides ───
    # User reorder / hide choices captured by the frontend (u13 capture
    # path, pending) re-apply here. SCOPE LOCKED to slot_order +
    # hidden_slots — frame swap rejected at u6 validate gate (stays on
    # the existing `frames` axis) so the Phase Z no-AI-HTML-structure
    # invariant remains intact. raw_content preserved : helper only
    # reorders / removes top-level slot_payload keys ; per-slot line
    # lists + ``debug_zones`` + ``MdxSection`` graph untouched. Audit
    # artifact emits BEFORE the slot_payload artifact so reviewers see
    # the post-override state.
    structure_overrides_audit = _apply_structure_overrides_to_zones(
        override_structure_overrides or {}, zones_data,
    )
    _write_step_artifact(
        run_dir, 12, "structure_overrides",
        data=structure_overrides_audit,
        step_status="done",
        pipeline_path_connected=True,
        inputs=["data/user_overrides/*.json"],
        outputs=["step12_structure_overrides.json"],
        note=(
            "IMP-56 #90 u7 — user reorder / hide re-apply to "
            "slot_payload (SCOPE LOCKED to slot_order + hidden_slots ; "
            "frame swap stays on the `frames` axis ; raw_content "
            "preserved)."
        ),
    )

    # ─── Step 12: Slot Payload (actual values, mapper.py 결과) ───
    _write_step_artifact(
        run_dir, 12, "slot_payload",
        data={
            "per_zone": [
                {
                    "position": zd["position"],
                    "template_id": zd["template_id"],
                    "builder": (get_contract(zd["template_id"]) or {}).get("payload", {}).get("builder"),
                    "slot_payload": zd["slot_payload"],
                    "content_weight": zd.get("content_weight"),
                    "min_height_px": zd.get("min_height_px"),
                    "coverage_state": zd.get("coverage_state"),
                    "frame_expansion_trace": zd.get("frame_expansion_trace"),
                }
                for zd in zones_data
            ],
        },
        step_status="done",
        pipeline_path_connected=True,
        inputs=["step10_frame_contract.json", "step02_normalized.json"],
        outputs=["step12_slot_payload.json"],
        note="map_with_contract 결과 — actual slot_payload 값 그대로 (key 만 X).",
    )
    # IMP-42 u3 (#71) — unconditional Step 12 slot_payload emit DIAG log.
    _emit_diag_zones_shape("Step 12 slot_payload emit", zones_data)

    # 6. Build layout CSS — horizontal-2 = dynamic heights (regression preserve), 그 외 = fr default.
    #    Step D-ext : override_zone_geometries 가 들어오면 layout_css 강제.
    # IMP-86 u2 — pre-build layout invariant guard. zones_data / debug_zones
    # MUST be cardinality- and position-aligned with the active layout
    # preset's css_areas tokens before build_layout_css derives heights_px
    # / widths_px and _compute_per_zone_geometry validates them against R/C.
    # If a mapper FitError path (IMP-86 u1) — or any future zone-drop path —
    # forgets to append a placeholder, the resulting shape drift would
    # surface as a confusing `heights_px length N != grid rows R=M`
    # ValueError deep inside the geometry helper. This guard fails fast at
    # the pipeline boundary with preset / expected positions / actual
    # positions / count diagnostics so the root cause is obvious from the
    # log line (factual_verification: value + path + upstream).
    _active_preset = LAYOUT_PRESETS[layout_preset]
    _expected_positions = _parse_css_areas(_active_preset["css_areas"])[1]
    _actual_positions = [zd["position"] for zd in zones_data]
    _debug_positions = [dz["position"] for dz in debug_zones]
    if (
        len(zones_data) != len(_expected_positions)
        or len(debug_zones) != len(_expected_positions)
        or sorted(_actual_positions) != sorted(_expected_positions)
        or sorted(_debug_positions) != sorted(_expected_positions)
    ):
        raise ValueError(
            "phase_z2_pipeline pre-build layout invariant violation: "
            f"layout_preset={layout_preset!r} "
            f"css_areas={_active_preset['css_areas']!r} "
            f"expected_positions={_expected_positions!r} "
            f"zones_data_positions={_actual_positions!r} "
            f"debug_zones_positions={_debug_positions!r} "
            f"zones_count={len(zones_data)} "
            f"debug_count={len(debug_zones)} "
            f"expected_count={len(_expected_positions)}"
        )
    layout_decision_basis = _build_task24_layout_decision_basis(
        units=units,
        zones_data=zones_data,
        slide_footer=slide_footer,
        layout_preset=layout_preset,
        auto_layout_preset=auto_layout_preset,
        layout_override_applied=layout_override_applied,
    )
    layout_css = build_layout_css(
        layout_preset, zones_data, override_zone_geometries=override_zone_geometries
    )
    # IMP-09 PR 1 — unified per-zone geometry aggregation across all
    # layouts. Spanning zones in 2-D layouts (T / 2x2 from PR 2 onward)
    # are handled by _compute_per_zone_geometry; in PR 1 the helper
    # operates on row/col-static or row-dynamic / col-dynamic outputs.
    per_zone_geo = _compute_per_zone_geometry(layout_css, debug_zones, GRID_GAP)
    for dz, geo in zip(debug_zones, per_zone_geo):
        dz["height_px"] = geo["zone_height_px"]
        dz["ratio"] = geo["zone_height_ratio"]
        dz["width_px"] = geo["zone_width_px"]
        dz["width_ratio"] = geo["zone_width_ratio"]
    if layout_css["dynamic_rows"] and layout_css.get("dynamic_cols"):
        print(
            f"  zones   : 2-D heights {layout_css['heights_px']} px, "
            f"widths {layout_css['widths_px']} px, "
            f"ratios {layout_css['ratios']}, "
            f"width_ratios {layout_css['width_ratios']}"
        )
    elif layout_css["dynamic_rows"]:
        print(f"  zones   : heights {layout_css['heights_px']} px, ratios {layout_css['ratios']}")
    elif layout_css.get("dynamic_cols"):
        print(f"  zones   : widths {layout_css['widths_px']} px, width_ratios {layout_css['width_ratios']}")
    else:
        print(f"  zones   : fr default ({layout_css['cols']} / {layout_css['rows']})")

    # ─── Step 7: Slide-Level Layout (선택된 layout + 후보 list — Step 7-conn) ───
    # Step 7-conn axis (사용자 lock 2026-05-08) — select_layout_candidates(unit_count)
    # 결과를 artifact 에 기록 (passive). default 결정 자체는 무변 (layout_preset 그대로).
    layout_candidates_list = select_layout_candidates(len(units))
    _write_step_artifact(
        run_dir, 7, "layout",
        data={
            "layout_preset": layout_preset,
            "layout_css": layout_css,
            "zones_count": len(zones_data),
            "unit_count": len(units),
            "layout_candidates": layout_candidates_list,
            "layout_decision_basis": layout_decision_basis,
            # Step 7-A axis : user override trace
            "layout_override_applied": layout_override_applied,
            "auto_layout_preset": auto_layout_preset,
        },
        step_status="partial",
        pipeline_path_connected=True,
        inputs=["step06_composition_plan.json"],
        outputs=["step07_layout.json", "step07_selected_layout.html"],
        note=(
            "count-based v0 — 들여쓰기 / 정렬 미세 layout 미구현 (Step 7 ⚠ partial). "
            "Step 7-conn (사용자 lock 2026-05-08): unit_count → layout_candidates list "
            "(select_layout_candidates) artifact 기록. default 결정 자체는 무변 — "
            "candidates[0] 가 default (default_selection: true), 나머지는 alternative. "
            "Step 9 application_plan input."
        ),
    )
    # Step 7 HTML — slide-base 위 실제 zone 박스 위치 시각화 (constants 와 1:1 일치)
    _slide_w, _slide_h, _body_h = SLIDE_W, SLIDE_H, SLIDE_BODY_HEIGHT
    _zone_palette = ["#dbeafe", "#fef3c7", "#dcfce7", "#fce7f3", "#ede9fe"]
    _zone_borders = ["#3b82f6", "#f59e0b", "#16a34a", "#db2777", "#7c3aed"]
    _grid_template = layout_css.get("rows") or "1fr"
    _zone_visuals_7 = ""
    for i, dz in enumerate(debug_zones):
        _color = _zone_palette[i % len(_zone_palette)]
        _border = _zone_borders[i % len(_zone_borders)]
        _zone_visuals_7 += (
            f'<div style="background:{_color};border:3px solid {_border};'
            f'display:flex;flex-direction:column;justify-content:center;align-items:center;'
            f'padding:16px;text-align:center;">'
            f'<div style="font-size:18px;font-weight:700;margin-bottom:6px;">zone--{dz["position"]}</div>'
            f'<div style="font-size:14px;"><code>{dz.get("v4_template_id") or "-"}</code></div>'
            f'<div style="font-size:13px;color:#475569;margin-top:4px;">'
            f'height: {dz.get("height_px") or "?"}px / ratio: {dz.get("ratio") or "?"}'
            f'</div></div>'
        )
    _slide_visual_7 = (
        f'<div style="width:{_slide_w}px;border:2px solid #1e293b;background:#fff;margin:16px 0;'
        f'box-shadow:0 4px 16px rgba(0,0,0,0.1);">'
        f'<div style="padding:14px 40px;border-bottom:1px solid #cbd5e1;background:#f8fafc;">'
        f'<div style="font-size:15px;color:#64748b;">[slide-title placeholder]</div></div>'
        f'<div style="padding:0 40px;height:{_body_h}px;display:grid;'
        f'grid-template-rows:{_grid_template};grid-template-columns:{layout_css.get("cols") or "1fr"};'
        f'gap:{GRID_GAP}px;box-sizing:border-box;padding-top:12px;padding-bottom:12px;">'
        f'{_zone_visuals_7}</div>'
        f'<div style="padding:10px 40px;border-top:1px solid #cbd5e1;background:#f8fafc;text-align:right;">'
        f'<span style="font-size:13px;color:#64748b;">[slide-footer]</span></div>'
        f'</div>'
    )
    # Step 7-conn — layout 후보 list 시각 (default = candidates[0]).
    _candidates_rows = ""
    for i, lc in enumerate(layout_candidates_list):
        _is_default = (i == 0)
        _is_selected = (lc == layout_preset)
        _badge = (
            '<span style="background:#dcfce7;color:#166534;padding:2px 8px;border-radius:3px;'
            'font-size:11px;font-weight:600;margin-left:6px;">selected</span>'
            if _is_selected else ''
        )
        _default_mark = (
            '<span style="background:#e0e7ff;color:#3730a3;padding:2px 8px;border-radius:3px;'
            'font-size:11px;font-weight:600;margin-left:6px;">default</span>'
            if _is_default else
            '<span style="background:#f1f5f9;color:#64748b;padding:2px 8px;border-radius:3px;'
            'font-size:11px;font-weight:600;margin-left:6px;">alternative</span>'
        )
        _candidates_rows += (
            f'<li style="padding:6px 0;"><code>{lc}</code>{_default_mark}{_badge}</li>'
        )
    _candidates_block = (
        f'<h2>Layout Candidates (unit_count={len(units)})</h2>'
        f'<p>source: <code>templates/phase_z2/layouts/layouts.yaml</code> + '
        f'<code>select_layout_candidates(unit_count)</code> '
        f'(Step 7-B). default = first entry. <strong>현재 single-decision logic 은 '
        f'default 만 사용</strong> — Step 9 application_plan 진입 시 후보 평가.</p>'
        f'<ul>{_candidates_rows}</ul>'
    )
    _write_step_html(
        run_dir, 7, "selected_layout",
        title=f"Selected Layout — {layout_preset}",
        body_html=(
            f"<h2>Layout Preset: <code>{layout_preset}</code></h2>"
            f"<p>slide canvas {_slide_w}×{_slide_h}px / slide-body {SLIDE_BODY_WIDTH}×{_body_h}px (left {SLIDE_BODY_LEFT} / top {SLIDE_BODY_TOP}). "
            f"안 zone 박스 = 실제 비율 그대로.</p>"
            f"{_slide_visual_7}"
            f"{_candidates_block}"
            f"<h2>Layout CSS (raw)</h2>"
            f"<pre><code>{json.dumps(layout_css, ensure_ascii=False, indent=2)}</code></pre>"
        ),
        step_status="partial",
        inputs=["step06_composition_plan.json"],
        outputs=["step07_layout.json", "step07_selected_layout.html"],
    )

    # ─── Step 8: Zone + Region Ratio (계획값 only — render 전) ───
    # Step 8-conn axis (사용자 lock 2026-05-08) — region/display 후보 list per zone (passive 기록).
    # placeholder signals (Step 3/4 부재 종속) :
    #   region_count = 1 (text-only assumption)
    #   content_type = "text_block"
    #   flow_type / role_pattern / has_visual_element / details_presence /
    #   large_table / long_text / fits_in_region = None or False
    # Step 3/4 (Content Object 추출 + Internal Composition Planning) 활성화 시
    # 이 placeholder 가 실제 content_object 신호로 교체됨 (별 axis).
    _step8_placeholder_signals = {
        "region_count": 1,
        "content_type": "text_block",
        "flow_type": None,
        "role_pattern": None,
        "ratio_asymmetric": False,
        "has_visual_element": False,
        "details_presence": False,
        "large_table": False,
        "long_text": False,
        "fits_in_region": None,
        "_note": (
            "Step 3/4 부재 종속 placeholder — 모든 zone 을 text-only / region_count=1 "
            "로 가정. 실제 content_object 신호 활성화는 별 axis."
        ),
    }
    zone_region_plans = []
    for dz in debug_zones:
        contract = get_contract(dz.get("contract_id")) or {}
        sub_zones = contract.get("sub_zones") or []
        cardinality = contract.get("cardinality") or {}
        visual_hints = contract.get("visual_hints") or {}
        # Step 8-conn — region / display strategy 후보 (placeholder signals).
        _region_cands = select_region_layout_candidates(
            region_count=_step8_placeholder_signals["region_count"],
            flow_type=_step8_placeholder_signals["flow_type"],
            role_pattern=_step8_placeholder_signals["role_pattern"],
            ratio_asymmetric=_step8_placeholder_signals["ratio_asymmetric"],
            has_visual_element=_step8_placeholder_signals["has_visual_element"],
            details_presence=_step8_placeholder_signals["details_presence"],
            large_table=_step8_placeholder_signals["large_table"],
            long_text=_step8_placeholder_signals["long_text"],
        )
        _display_cands = select_display_strategy_candidates(
            content_type=_step8_placeholder_signals["content_type"],
            long_text=_step8_placeholder_signals["long_text"],
            large_table=_step8_placeholder_signals["large_table"],
            fits_in_region=_step8_placeholder_signals["fits_in_region"],
        )
        zone_region_plans.append({
            "position": dz["position"],
            "zone_height_px_planned": dz.get("height_px"),
            "zone_ratio_planned": dz.get("ratio"),
            "zone_width_px_planned": dz.get("width_px"),
            "zone_col_ratio_planned": dz.get("width_ratio"),
            "min_height_px": visual_hints.get("min_height_px"),
            "frame_cardinality_strict": cardinality.get("strict"),
            "sub_zones_planned": [
                {
                    "id": sz.get("id"),
                    "role": sz.get("role"),
                    "accepts": sz.get("accepts"),
                    "cardinality_strict": (sz.get("cardinality") or {}).get("strict"),
                    "partial_target_path": sz.get("partial_target_path"),
                }
                for sz in sub_zones
            ],
            "child_distribution_note": (
                "현재 child zone (sub_zones 안 sections) 균등 분배 — "
                "Step 8 region-level ratio ⚠ partial."
            ),
            # Step 8-conn — region/display 후보 (placeholder signals)
            "region_layout_candidates": _region_cands,
            "display_strategy_candidates": _display_cands,
        })
    _write_step_artifact(
        run_dir, 8, "zone_region_ratios",
        data={
            "zone_heights_px_planned": layout_css.get("heights_px"),
            "zone_widths_px_planned": layout_css.get("widths_px"),
            "zone_ratios_planned": layout_css.get("ratios"),
            "zone_col_ratios_planned": layout_css.get("width_ratios"),
            "per_zone_plan": zone_region_plans,
            # Step 8-conn placeholder signals (사람이 한 곳에서 caveat 확인)
            "step8_conn_placeholder_signals": _step8_placeholder_signals,
        },
        step_status="partial",
        pipeline_path_connected=True,
        inputs=["step07_layout.json", "step10_frame_contract.json"],
        outputs=["step08_zone_region_ratios.json", "step08_zone_content_placement.html"],
        note=(
            "계획값 only. 실측값은 Step 14 (visual_check). "
            "zone-level 만 dynamic, region-level (sub_zone 안 sections) 은 균등 분배 (1/1/1). "
            "F29 처럼 비균등 콘텐츠 (transform_table + plain) 는 첫 cell 부족 가능 — Step 8 ⚠ partial. "
            "Step 8-conn (사용자 lock 2026-05-08): per_zone_plan[i] 에 region_layout_candidates + "
            "display_strategy_candidates 추가 (passive 기록). placeholder signals = text-only / "
            "region_count=1 (Step 3/4 부재 종속). 실제 content_object 신호 활성화는 별 axis. "
            "Step 9 application_plan input."
        ),
    )
    # Step 8 HTML — zone + sub_zone + sections 시각 박스 (균등 분배 보임)
    # Step 8-conn — region/display 후보 list 도 zone 별 박스 아래 표시.
    _zone_visuals_8 = ""
    for i, plan in enumerate(zone_region_plans):
        _color = _zone_palette[i % len(_zone_palette)]
        _border = _zone_borders[i % len(_zone_borders)]
        _zone_h = plan['zone_height_px_planned'] or 300
        _sub_zones_html = ""
        for sz in plan['sub_zones_planned']:
            _card = sz['cardinality_strict'] or 1
            _accepts = ', '.join(sz['accepts'] or [])
            # sub_zone 안에 section 박스 cardinality 만큼 균등 분배
            _section_boxes = "".join(
                f'<div style="flex:1;border:1px dashed #94a3b8;background:rgba(255,255,255,0.7);'
                f'padding:6px;display:flex;align-items:center;justify-content:center;'
                f'font-size:12px;color:#475569;">section {k+1} (균등 1/{_card})</div>'
                for k in range(_card)
            )
            _sub_zones_html += (
                f'<div style="flex:1;background:rgba(59,130,246,0.08);border:2px solid #3b82f6;'
                f'padding:8px;display:flex;flex-direction:column;gap:4px;">'
                f'<div style="font-weight:700;font-size:13px;padding-bottom:6px;border-bottom:1px solid #3b82f6;">'
                f'<code>{sz["id"]}</code><br>'
                f'<span style="font-size:11px;font-weight:400;color:#475569;">'
                f'cardinality.strict={_card} | accepts: {_accepts}'
                f'</span>'
                f'</div>'
                f'{_section_boxes}'
                f'</div>'
            )
        # Step 8-conn — region / display strategy 후보 시각.
        _region_pills = " ".join(
            f'<span style="background:#dbeafe;color:#1e40af;padding:2px 10px;border-radius:12px;'
            f'font-size:11px;font-weight:600;margin-right:4px;">'
            f'{rc}{" ★" if k == 0 else ""}</span>'
            for k, rc in enumerate(plan.get("region_layout_candidates") or [])
        )
        _display_pills = " ".join(
            f'<span style="background:#dcfce7;color:#166534;padding:2px 10px;border-radius:12px;'
            f'font-size:11px;font-weight:600;margin-right:4px;">'
            f'{ds}{" ★" if k == 0 else ""}</span>'
            for k, ds in enumerate(plan.get("display_strategy_candidates") or [])
        )
        _zone_visuals_8 += (
            f'<h3>zone--{plan["position"]} ({_zone_h}px planned, '
            f'min_height {plan["min_height_px"]}px, '
            f'frame_cardinality_strict {plan["frame_cardinality_strict"]})</h3>'
            f'<div style="height:{min(_zone_h, 360)}px;background:{_color};border:3px solid {_border};'
            f'display:flex;gap:8px;padding:12px;box-sizing:border-box;margin-bottom:8px;">'
            f'{_sub_zones_html}'
            f'</div>'
            f'<p style="margin-top:0;color:#64748b;font-size:13px;"><em>{plan["child_distribution_note"]}</em></p>'
            f'<div style="background:#f8fafc;border-left:3px solid #94a3b8;padding:8px 12px;margin-bottom:16px;font-size:13px;">'
            f'<div style="margin-bottom:4px;"><strong>region_layout_candidates</strong> (★ default): {_region_pills}</div>'
            f'<div><strong>display_strategy_candidates</strong> (★ default): {_display_pills}</div>'
            f'</div>'
        )
    _write_step_html(
        run_dir, 8, "zone_content_placement",
        title="Zone + Child Zone Placement Plan (pre-render)",
        body_html=(
            f"<p><strong>중요:</strong> 이 페이지는 <em>계획값</em> only. 실제 측정값 (clientHeight / scrollHeight / overflow) 은 "
            f"<code>step14_visual_check.json</code> 에서 봄.</p>"
            f"<p>각 zone 안에 sub_zones 가 columns 로 나열, 각 sub_zone 안 sections 가 cardinality.strict 만큼 균등 row 분배. "
            f"F29 process_column 의 첫 section 이 transform_table (AS-IS/TO-BE 표) 인데 균등 분배로 capacity 부족 → 10px overflow 직접 원인.</p>"
            f'<div style="background:#fef3c7;border-left:3px solid #f59e0b;padding:8px 12px;margin-bottom:16px;font-size:13px;">'
            f'<strong>Step 8-conn placeholder caveat (사용자 lock 2026-05-08):</strong> '
            f'region_layout_candidates / display_strategy_candidates 는 현재 '
            f'<code>region_count=1 / content_type="text_block"</code> placeholder 신호로만 산출. '
            f'Step 3/4 (Content Object 추출 + Internal Composition Planning) 활성화 시 '
            f'실제 content_object 신호로 교체 (별 axis).'
            f'</div>'
            f"{_zone_visuals_8}"
        ),
        step_status="partial",
        inputs=["step07_layout.json", "step10_frame_contract.json"],
        outputs=["step08_zone_region_ratios.json", "step08_zone_content_placement.html"],
    )

    # ─── Step 9 v0: Passive Application Plan (사용자 lock 2026-05-08) ───
    # status.md §2 schema 따라 per-unit application_plan 생성.
    # v0 = passive — Step 6 default 그대로 사용. runtime 결과 무변.
    # invariant 5 가지 (status.md §4) 만족 :
    #   1. len(application_candidates) == len(v4_candidates) per unit
    #   2. application_candidates[i].template_id == v4_candidates[i].template_id (zip 일관)
    #   3. current_default_candidate == v4_candidates[0].template_id (application_status="ok")
    #      또는 null (application_status="no_v4_candidate")
    #   4. len(units) == Step 6 의 plan_composition 결과 (무변)
    #   5. application_status == "ok" iff len(v4_candidates) > 0 iff candidate_status == "ok"

    # IMP-06 blocker-fix (Codex #13 Blocker 3 / #16) — pre-build per-unit
    # plan-aware lookup so Step 9 application_plan can carry position +
    # assignment_source + override-flag fields. Render-record is the canonical
    # plan-derived per-position view (built post-frame_overrides); match by
    # object identity since render_records[i]["unit"] holds the same instance
    # ref as the entry in `units`.
    plan_record_by_unit_id = {}
    if "render_records" in locals() and render_records:
        for rec in render_records:
            u = rec.get("unit")
            if u is None:
                continue
            plan_record_by_unit_id[id(u)] = rec

    application_plan_units = []
    for i, unit in enumerate(units):
        # zone_region_plans 는 unit i 와 1:1 (Step 6 unit → Step 8 zone_plan).
        zone_plan = zone_region_plans[i] if i < len(zone_region_plans) else {}
        selection_trace = v4_fallback_traces.get(unit.source_section_ids[0], {})
        plan_record = plan_record_by_unit_id.get(id(unit))

        # Step 7-A axis 보강 — reject 포함 모든 V4 judgments (frontend UI 가
        # 모든 frame 의 png 를 카드로 보여주기 위함).
        # unit_id = source_section_ids join. parent_merged 는 첫 section 의
        # judgments 사용 (parent V4 entry 가 그 section 에 있으므로).
        # IMP-08 B-3 : forward sub-section V4 aliases (decimal heading_number)
        # when canonical ordinal id misses; U1 default = empty list (no change).
        _first_sid = unit.source_section_ids[0]
        v4_all_for_unit = lookup_v4_all_judgments(
            v4, _first_sid, alias_keys=section_alias_by_id.get(_first_sid)
        )

        # IMP-32 u4 — per-unit application_plan dict assembly extracted into
        # _build_application_plan_unit(...). Per-index/per-id lookups
        # (zone_region_plans[i], v4_fallback_traces.get(...),
        # plan_record_by_unit_id.get(id(unit)), section_alias_by_id,
        # lookup_v4_all_judgments(...)) stay at the call-site.
        application_plan_units.append(
            _build_application_plan_unit(
                unit,
                zone_plan,
                selection_trace,
                plan_record,
                v4_all_for_unit,
                layout_preset,
                layout_candidates_list,
            )
        )

    units_with_no_v4 = [
        u["unit_id"] for u in application_plan_units
        if u["application_status"] == "no_v4_candidate"
    ]

    _write_step_artifact(
        run_dir, 9, "application_plan",
        data={
            "units": application_plan_units,
            "candidate_status_summary": {
                "units_with_no_v4_candidate": units_with_no_v4,
                "units_with_fallback": [
                    u["unit_id"] for u in application_plan_units if u.get("fallback_used")
                ],
            },
            "fallback_policy": comp_debug.get("v4_fallback_summary"),
            # Step 7-A axis : user override trace
            "frame_overrides_applied": frame_overrides_applied,
            "frame_overrides_skipped": frame_overrides_skipped,
            # IMP-06 blocker-fix (Codex #13 Blocker 3 / #16) — surface the
            # section-assignment plan + summary at Step 9 top level so
            # frontend / downstream readers do not have to dive into
            # comp_debug to see override impact.
            "section_assignment_plan": comp_debug.get("section_assignment_plan"),
            "section_assignment_summary": comp_debug.get("section_assignment_summary"),
            "v0_lock_note": (
                "Step 9 v0 passive (사용자 lock 2026-05-08). "
                "Step 6 default 그대로 사용 — runtime 결과 byte-동일. "
                "auto decision / scoring 은 Step 9 v1 (별 axis)."
            ),
        },
        step_status="partial",
        pipeline_path_connected=True,
        inputs=[
            "step05_v4_evidence.json",
            "step06_composition_plan.json",
            "step07_layout.json",
            "step08_zone_region_ratios.json",
        ],
        outputs=["step09_application_plan.json", "step09_application_plan.html"],
        note=(
            "Step 9 v0 passive application_plan trace (사용자 lock 2026-05-08). "
            "V4 후보 + layout / region / display 후보 + V4 label → application_mode "
            "변환을 side-by-side 로 기록. v0 invariant 5 가지 (status.md §4) 만족. "
            "Step 6 의 default 결정 그대로 (current_default_candidate). "
            "auto decision 은 Step 9 v1 (별 axis). region/display 후보는 Step 8-conn "
            "의 placeholder signal 종속 (Step 3/4 부재). "
            "Step 7-A axis (2026-05-08): frame_overrides_applied 가 사용자 LayoutPanel/"
            "FramePanel 선택값을 강제 적용한 trace."
        ),
    )

    # Step 9 v0 HTML — per-unit table + application_mode pill.
    _mode_color = {
        "direct_insert":              ("#dcfce7", "#166534"),  # green
        "same_frame_with_adjustment": ("#dbeafe", "#1e40af"),  # blue
        "layout_or_region_change":    ("#fef3c7", "#92400e"),  # yellow (manual)
        "exclude":                    ("#fee2e2", "#991b1b"),  # red
    }
    _unit_blocks_9 = ""
    for u in application_plan_units:
        _status_badge = (
            f'<span style="background:#dcfce7;color:#166534;padding:2px 8px;border-radius:3px;'
            f'font-size:11px;font-weight:600;margin-left:6px;">application_status: ok</span>'
            if u["application_status"] == "ok" else
            f'<span style="background:#fee2e2;color:#991b1b;padding:2px 8px;border-radius:3px;'
            f'font-size:11px;font-weight:600;margin-left:6px;">application_status: no_v4_candidate</span>'
        )
        _default_html = (
            f'<code>{u["current_default_candidate"]}</code>'
            if u["current_default_candidate"] else '<em>null</em>'
        )
        _fallback_html = (
            f' | <strong>selection_path:</strong> <code>{u.get("selection_path")}</code>'
            f' | <strong>selected_v4_rank:</strong> {u.get("selected_v4_rank")}'
            f' | <strong>fallback_reason:</strong> <code>{u.get("fallback_reason")}</code>'
            if u.get("fallback_used") else
            f' | <strong>selection_path:</strong> <code>{u.get("selection_path")}</code>'
        )
        _layout_pills = " ".join(
            f'<span style="background:#e0e7ff;color:#3730a3;padding:1px 8px;border-radius:10px;'
            f'font-size:11px;margin-right:3px;">{lc}{" ★" if k == 0 else ""}</span>'
            for k, lc in enumerate(u["layout_candidates"])
        )
        _region_pills = " ".join(
            f'<span style="background:#dbeafe;color:#1e40af;padding:1px 8px;border-radius:10px;'
            f'font-size:11px;margin-right:3px;">{rc}{" ★" if k == 0 else ""}</span>'
            for k, rc in enumerate(u["region_layout_candidates"])
        )
        _display_pills = " ".join(
            f'<span style="background:#dcfce7;color:#166534;padding:1px 8px;border-radius:10px;'
            f'font-size:11px;margin-right:3px;">{ds}{" ★" if k == 0 else ""}</span>'
            for k, ds in enumerate(u["display_strategy_candidates"])
        )
        _app_rows = ""
        for k, ac in enumerate(u["application_candidates"]):
            _bg, _fg = _mode_color.get(ac["application_mode"], ("#f1f5f9", "#475569"))
            _is_default = (ac["template_id"] == u["current_default_candidate"])
            _default_mark = (
                ' <span style="background:#fef3c7;color:#92400e;padding:1px 6px;border-radius:3px;'
                'font-size:10px;font-weight:600;">current_default</span>'
                if _is_default else ''
            )
            _app_rows += (
                f'<tr>'
                f'<td style="padding:6px 10px;border-bottom:1px solid #e2e8f0;">'
                f'<code>{ac["template_id"]}</code>{_default_mark}</td>'
                f'<td style="padding:6px 10px;border-bottom:1px solid #e2e8f0;font-size:12px;">'
                f'{ac["v4_label"]}</td>'
                f'<td style="padding:6px 10px;border-bottom:1px solid #e2e8f0;">'
                f'<span style="background:{_bg};color:{_fg};padding:2px 8px;border-radius:3px;'
                f'font-size:11px;font-weight:600;">{ac["application_mode"]}</span></td>'
                f'<td style="padding:6px 10px;border-bottom:1px solid #e2e8f0;font-size:12px;">'
                f'{"✓" if ac["auto_applicable"] else "✗"}</td>'
                f'<td style="padding:6px 10px;border-bottom:1px solid #e2e8f0;font-size:11px;color:#64748b;">'
                f'{ac["delegated_to"] or "—"}</td>'
                f'</tr>'
            )
        _unit_blocks_9 += (
            f'<div style="background:#fff;border:1px solid #cbd5e1;border-radius:6px;padding:16px;margin-bottom:20px;">'
            f'<h3 style="margin-top:0;">unit: <code>{u["unit_id"]}</code> {_status_badge}</h3>'
            f'<p style="margin:4px 0;font-size:13px;color:#475569;">'
            f'<strong>layout_preset (default):</strong> <code>{u["layout_preset"]}</code> | '
            f'<strong>current_default_candidate:</strong> {_default_html}{_fallback_html}</p>'
            f'<p style="margin:4px 0;font-size:13px;"><strong>layout_candidates (★ default):</strong> {_layout_pills}</p>'
            f'<p style="margin:4px 0;font-size:13px;"><strong>region_layout_candidates (★ default, placeholder):</strong> {_region_pills}</p>'
            f'<p style="margin:4px 0;font-size:13px;"><strong>display_strategy_candidates (★ default, placeholder):</strong> {_display_pills}</p>'
            f'<table style="width:100%;border-collapse:collapse;margin-top:10px;font-size:13px;">'
            f'<thead><tr style="background:#f8fafc;">'
            f'<th style="padding:6px 10px;text-align:left;border-bottom:2px solid #cbd5e1;">template_id</th>'
            f'<th style="padding:6px 10px;text-align:left;border-bottom:2px solid #cbd5e1;">v4_label</th>'
            f'<th style="padding:6px 10px;text-align:left;border-bottom:2px solid #cbd5e1;">application_mode</th>'
            f'<th style="padding:6px 10px;text-align:left;border-bottom:2px solid #cbd5e1;">auto_app.</th>'
            f'<th style="padding:6px 10px;text-align:left;border-bottom:2px solid #cbd5e1;">delegated_to</th>'
            f'</tr></thead>'
            f'<tbody>{_app_rows}</tbody>'
            f'</table>'
            f'</div>'
        )

    _summary_block_9 = (
        f'<div style="background:#fef3c7;border-left:3px solid #f59e0b;padding:8px 12px;margin-bottom:16px;font-size:13px;">'
        f'<strong>Step 9 v0 lock (사용자 2026-05-08):</strong> '
        f'passive trace only — Step 6 default 그대로 사용 (runtime 결과 byte-동일). '
        f'auto decision / scoring 은 Step 9 v1 (별 axis). '
        f'region / display 후보는 Step 8-conn placeholder signal (Step 3/4 부재) 종속.'
        f'</div>'
        f'<p><strong>units:</strong> {len(application_plan_units)} | '
        f'<strong>units_with_no_v4_candidate:</strong> '
        f'{len(units_with_no_v4)} ({", ".join(units_with_no_v4) if units_with_no_v4 else "none"})</p>'
    )

    _write_step_html(
        run_dir, 9, "application_plan",
        title="Step 9 v0 — Passive Application Plan",
        body_html=(
            f'{_summary_block_9}'
            f'{_unit_blocks_9}'
        ),
        step_status="partial",
        inputs=[
            "step05_v4_evidence.json",
            "step06_composition_plan.json",
            "step07_layout.json",
            "step08_zone_region_ratios.json",
        ],
        outputs=["step09_application_plan.json", "step09_application_plan.html"],
    )

    # 7. Render single slide
    html = render_slide(slide_title, slide_footer, zones_data, layout_preset, layout_css)
    html = _postprocess_phase_z2_rendered_html(
        html,
        stage0_normalized_assets=stage0_normalized_assets,
        override_image_overrides=override_image_overrides,
        override_slide_css=override_slide_css,
        mdx_source_text=mdx_source_text,
    )

    # IMP-51 (#79) u4 + u7 — stamp user-content imgs with stable id /
    # role attrs, then inject persisted `image_overrides` CSS so the
    # next render re-applies the user-edited geometry.
    #
    # Forward-compat: `stage0_normalized_assets["images"]` is empty in
    # every current Phase Z run (Q1 = A confirmed at Stage 1), so the
    # stamper returns an empty `stamped_image_ids` list and the CSS
    # builder short-circuits to "". The HTML is therefore byte-for-byte
    # identical to the pre-IMP-51 output until Phase Z starts emitting
    # user-content imgs (separate axis, out of scope for #79).
    # 8. Write final.html
    out_path = run_dir / "final.html"
    out_path.write_text(html, encoding="utf-8")
    print(f"  html    : {out_path}")

    # ─── Step 13: Render ───
    _write_step_artifact(
        run_dir, 13, "render",
        data={
            "final_html_path": str(out_path),
            "final_html_size_bytes": out_path.stat().st_size,
            "render_inputs": {
                "slide_title": slide_title,
                "slide_footer": slide_footer,
                "zones_count": len(zones_data),
                "layout_preset": layout_preset,
            },
        },
        step_status="done",
        pipeline_path_connected=True,
        inputs=["step07_layout.json", "step12_slot_payload.json", "templates/phase_z2/slide_base.html", "templates/phase_z2/families/*.html"],
        outputs=["step13_render.json", "step13_draft_render.html", "final.html"],
        note="Jinja2 render 결과 = final.html. step13_draft_render.html 은 final.html 동일 복사 (검토용).",
    )
    # Step 13 HTML — final.html 그대로 복사 (검토용)
    (run_dir / "steps" / "step13_draft_render.html").write_text(html, encoding="utf-8")

    # 9. Selenium check
    print("  visual  : running per-zone overflow check ...")
    overflow = run_overflow_check(out_path)

    # ─── Step 14: Visual Runtime Check (실측값) ───
    _write_step_artifact(
        run_dir, 14, "visual_check",
        data=overflow,
        step_status="partial",
        pipeline_path_connected=True,
        inputs=["step13_render.json", "final.html"],
        outputs=["step14_visual_check.json"],
        note=(
            "Selenium 실측 — clientHeight / scrollHeight / excess_y / frame_slot_metrics. "
            "Step 8 의 계획값과 비교 시 어느 cell 이 overflow 했는지 박힘. "
            "image_aspect_mismatch 검사 추가 (IMP-15 실행-1, issue #45) — image_events[] + fail_reasons. "
            "table 검사 부재 (실행-2 잔류) — Step 14 ⚠ partial (table only)."
        ),
    )

    # ─── IMP-47B u13: Persist validated AI repair proposals to cache ───
    # Saves each applied PARTIAL_OVERRIDES proposal AFTER Step 14 visual
    # check + per IMP-46 dual-gate. ``visual_check_passed`` reads the
    # Selenium overflow result; ``auto_cache`` sourced from Settings
    # (CLI --auto-cache wires settings.ai_fallback_auto_cache at parse
    # time, src/phase_z2_pipeline.py:5631-5633). ``user_approved`` stays
    # False — the pipeline has no UX approval gate; the auto_cache
    # opt-in is the documented bypass per IMP-46 u5. Gate violations
    # surface as ``cache_save_status='gate_blocked:<reason>'`` on the
    # record (cache is a hint, never a hard dependency).
    from src.config import settings as _ai_cache_settings
    _persist_ai_repair_proposals_to_cache(
        ai_repair_records,
        visual_check_passed=bool(overflow.get("passed")),
        user_approved=False,
        auto_cache=bool(_ai_cache_settings.ai_fallback_auto_cache),
    )

    # 10. fit_classifier v0 (A1) — Selenium 결과 → spec §3 category 분류 layer.
    #     *분류만*. action / router / rerender X. behavior 변경 0.
    fit_classification = classify_visual_runtime_check(overflow, debug_zones)

    # ─── Step 15: Fit Classification ───
    _write_step_artifact(
        run_dir, 15, "fit_classification",
        data=fit_classification,
        step_status="done",
        pipeline_path_connected=True,
        inputs=["step14_visual_check.json"],
        outputs=["step15_fit_classification.json"],
        note="A1 — visual_runtime_check 결과를 spec §3 category 로 분류.",
    )

    # 11. overflow_router v0 (A2) — category → proposed_action 매핑 layer.
    #     *매핑까지만*. 실행 / rerender / behavior 변경 X.
    #     classifications 각 entry 에 proposed_action 추가, router_decision summary 반환.
    router_decision = route_fit_classification(fit_classification)
    router_decision["v4_fallback_summary"] = comp_debug.get("v4_fallback_summary")
    router_decision["v4_fallback_selections"] = comp_debug.get("v4_fallback_selections", [])
    router_decision["frame_reselect_fallback_status"] = (
        "pre_render_rank_2_3_fallback_implemented; "
        "post_render visual-fail rerender remains routed through existing action trace"
    )

    # ─── Step 16: Overflow Router ───
    _write_step_artifact(
        run_dir, 16, "router_decision",
        data=router_decision,
        step_status="done",
        pipeline_path_connected=True,
        inputs=["step15_fit_classification.json"],
        outputs=["step16_router_decision.json"],
        note="A2 — category → proposed_action 매핑.",
    )

    # 11.5 zone_ratio_retry action (A3) — A3 locked rules (사용자 잠금) 그대로.
    #      retry budget = 1, slide-base 고정, donor 룰, (b) revert 정책.
    retry_trace = _attempt_zone_ratio_retry(
        run_dir=run_dir,
        out_path=out_path,
        slide_title=slide_title,
        slide_footer=slide_footer,
        zones_data=zones_data,
        debug_zones=debug_zones,
        layout_preset=layout_preset,
        layout_css=layout_css,
        overflow=overflow,
        fit_classification=fit_classification,
        router_decision=router_decision,
        gap_px=GRID_GAP,
        override_zone_geometries=override_zone_geometries,
    )
    # retry 가 *성공* 했으면 overflow / fit_classification / router_decision / debug_zones 를
    # post-retry 상태로 갱신 (slide_status 가 새 상태 반영하도록).
    if retry_trace.get("retry_passed"):
        overflow = retry_trace["post_retry_overflow"]
        debug_zones = retry_trace["post_retry_debug_zones"]
        layout_css = retry_trace["post_retry_layout_css"]
        # post-retry classifier / router 재실행 — 새 overflow 가 통과면 router_active=False
        fit_classification = classify_visual_runtime_check(overflow, debug_zones)
        router_decision = route_fit_classification(fit_classification)
        router_decision["v4_fallback_summary"] = comp_debug.get("v4_fallback_summary")
        router_decision["v4_fallback_selections"] = comp_debug.get("v4_fallback_selections", [])
        router_decision["frame_reselect_fallback_status"] = (
            "pre_render_rank_2_3_fallback_implemented; "
            "post_render visual-fail rerender remains routed through existing action trace"
        )

    # 11.6 retry_failure_classifier + next_action_router (A4 — 분류/매핑만, 실행 X)
    #      retry 실패 시 failure_type 분류 + next_proposed_action 기록 (escalation 후보).
    enrich_retry_trace_with_failure_classification(retry_trace)

    # 11.7 IMP-12 u9 — Step 17 deterministic salvage cascade.
    # Triggered on donor_slack_insufficient / no_donor_candidates: cross_zone_redistribute
    # → glue_compression → font_step_compression (terminal → layout_adjust/frame_reselect).
    _ft = (retry_trace.get("failure_classification") or {}).get("failure_type")
    if _ft in {"donor_slack_insufficient", "no_donor_candidates"}:
        _plan = retry_trace.get("plan") or {}
        _tpos = _plan.get("target_zone_position")
        _tdz = next((dz for dz in debug_zones if dz.get("position") == _tpos), {}) or {}
        _excess = float(_plan.get("target_excess_y") or 0.0)
        # Synthesize FitAnalysis from debug_zones + per-zone overflow so cross_zone_redistribute
        # can compute feasibility against real Phase Z geometry (Phase Q's calculate_fit is
        # not invoked in Phase Z — see comp_debug v4_fallback_summary policy at 2839-2843).
        # Each position becomes a "role"; all share conceptual zone "slide_body" so
        # fit_verifier.redistribute trades shortfalls between them. shortfall_px is signed:
        # scrollHeight - clientHeight > 0 = deficit, < 0 = surplus (matches redistribute()).
        from src.fit_verifier import FitAnalysis, RoleFit
        _zof = {z.get("position"): z for z in (overflow.get("zones") or [])}
        _fa_roles, _fa_containers = {}, {}
        for _dz in debug_zones:
            _pos = _dz.get("position")
            if not _pos:
                continue
            _alloc = float(_dz.get("height_px") or 0.0)
            _zm = _zof.get(_pos) or {}
            _ch = float(_zm.get("clientHeight") or _alloc)
            _sh = float(_zm.get("scrollHeight") or _ch)
            _fa_roles[_pos] = RoleFit(role=_pos, allocated_px=_alloc, shortfall_px=_sh - _ch)
            _fa_containers[_pos] = {"zone": "slide_body", "height_px": int(_alloc)}
        _salvage_trace = _attempt_salvage_chain(
            run_dir=run_dir, out_path=out_path,
            slide_title=slide_title, slide_footer=slide_footer,
            zones_data=zones_data, layout_preset=layout_preset, layout_css=layout_css,
            cascade_inputs={
                "fit_analysis": FitAnalysis(roles=_fa_roles),
                "containers": _fa_containers,
                    "min_margin_px": None,
                    "manual_zone_positions": list((override_zone_geometries or {}).keys()),
                    "excess_px": _excess, "excess_after_glue_px": _excess,
                    "block_count": len((_tdz.get("placement_trace") or {}).get("internal_regions") or []) or 1,
                "zone_position": _tpos or "",
                "current_font_px": float(_tdz.get("font_size_px") or 0.0),
                "available_lines": int(_tdz.get("available_lines") or 0),
                "chars_per_line": int(_tdz.get("chars_per_line") or 0),
            },
            initial_failure_type=_ft, gap_px=GRID_GAP,
        )
        retry_trace.update(_salvage_trace)
        if _salvage_trace.get("salvage_passed"):
            overflow = (_salvage_trace["salvage_steps"][-1].get("post_salvage_overflow")) or overflow
            fit_classification = classify_visual_runtime_check(overflow, debug_zones)
            router_decision = route_fit_classification(fit_classification)
            router_decision["v4_fallback_summary"] = comp_debug.get("v4_fallback_summary")
            router_decision["v4_fallback_selections"] = comp_debug.get("v4_fallback_selections", [])
            router_decision["frame_reselect_fallback_status"] = (
                "pre_render_rank_2_3_fallback_implemented; "
                "post_render visual-fail rerender remains routed through existing action trace"
            )
            # Refresh failure_classification / next_action_proposal so Step 18 / Step 19
            # do not surface the pre-salvage donor_slack_insufficient / no_donor_candidates
            # state. classify_retry_failure short-circuits on salvage_passed=True → both
            # fields become None (no failure to classify, no escalation pending).
            enrich_retry_trace_with_failure_classification(retry_trace)

    # 11.7.1 IMP-88 (#88) u7 — Step 17 image_fit single-pass entry trigger.
    # Activates when router proposes `image_fit` (image_aspect_mismatch
    # classifications, ACTION_BY_CATEGORY row added in u1). Single-pass executor
    # (`_attempt_step17_image_fit_single_pass`): per-image plan/apply via
    # plan_image_fit + apply_image_fit_css → aggregated CSS overlay → single
    # re-render → run_overflow_check. PASS promotes final.html and refreshes
    # Step 17/18/19 state; FAIL records `image_fit` step with failure_reason
    # so failure_router (u2) SALVAGE_FAILURE_TYPE_BY_ACTION classifies it as
    # `image_fit_insufficient` and the §11.7.2 cascade entry block routes
    # onto layout_adjust. image_fit stays OUT of _SALVAGE_FAIL_BY_ACTION
    # (u6 guard) — Step 17 ENTRY single-pass, not a salvage cascade stage.
    if (
        not retry_trace.get("retry_passed")
        and not retry_trace.get("salvage_passed")
        and "image_fit" in set(router_decision.get("proposed_actions_summary") or [])
    ):
        _img_result = _attempt_step17_image_fit_single_pass(
            run_dir=run_dir, out_path=out_path,
            slide_title=slide_title, slide_footer=slide_footer,
            zones_data=zones_data, layout_preset=layout_preset,
            layout_css=layout_css,
            image_events=overflow.get("image_events") or [],
            gap_px=GRID_GAP,
        )
        if _img_result["triggered"]:
            retry_trace.setdefault("salvage_steps", []).append(_img_result["step"])
            retry_trace["salvage_attempted"] = True
            if _img_result["passed"]:
                retry_trace["salvage_passed"] = True
                overflow = _img_result["candidate_overflow"]
                fit_classification = classify_visual_runtime_check(overflow, debug_zones)
                router_decision = route_fit_classification(fit_classification)
                router_decision["v4_fallback_summary"] = comp_debug.get("v4_fallback_summary")
                router_decision["v4_fallback_selections"] = comp_debug.get("v4_fallback_selections", [])
                router_decision["frame_reselect_fallback_status"] = (
                    "pre_render_rank_2_3_fallback_implemented; "
                    "post_render visual-fail rerender remains routed through existing action trace"
                )
                enrich_retry_trace_with_failure_classification(retry_trace)

    # 11.7.2 IMP-88 (#88) u7 — direct entry triggers for layout_adjust /
    # frame_internal_fit_candidate when the donor_slack pathway above did not
    # engage but the router proposes one of these actions (e.g. moderate_overflow
    # / layout_zone_mismatch → layout_adjust; frame_capacity_mismatch →
    # frame_internal_fit_candidate per u1 ACTION_BY_CATEGORY). Re-uses
    # _attempt_salvage_chain with a synthetic initial_failure_type that
    # routes (via failure_router NEXT_ACTION_BY_FAILURE / u2) onto the proposed
    # action, so the cascade tail (frame_reselect → details_popup_escalation)
    # stays consistent with the donor_slack pathway. Also handles the
    # image_fit single-pass FAIL → image_fit_insufficient escalation onto
    # the cascade (u2 row routes image_fit_insufficient → layout_adjust).
    if not retry_trace.get("retry_passed") and not retry_trace.get("salvage_passed"):
        _u7_proposed = set(router_decision.get("proposed_actions_summary") or [])
        _u7_last_step = (retry_trace.get("salvage_steps") or [])
        _u7_image_fit_failed = bool(
            _u7_last_step
            and _u7_last_step[-1].get("action") == "image_fit"
            and _u7_last_step[-1].get("passed") is False
        )
        _u7_initial = None
        if _u7_image_fit_failed:
            _u7_initial = "image_fit_insufficient"
        elif "layout_adjust" in _u7_proposed:
            _u7_initial = "font_step_insufficient"
        elif "frame_internal_fit_candidate" in _u7_proposed:
            _u7_initial = "layout_adjust_insufficient"
        if _u7_initial:
            _u7_cls_list = fit_classification.get("classifications") or []
            _u7_entry_cls = next(
                (c for c in _u7_cls_list
                 if c.get("proposed_action") in {
                     "layout_adjust", "frame_internal_fit_candidate", "image_fit",
                 }),
                {},
            )
            _u7_tpos = _u7_entry_cls.get("zone_position") or ""
            _u7_tdz = next(
                (dz for dz in debug_zones if dz.get("position") == _u7_tpos), {},
            ) or {}
            _u7_zof = {z.get("position"): z for z in (overflow.get("zones") or [])}
            _u7_zm = _u7_zof.get(_u7_tpos) or {}
            _u7_excess = max(
                0.0,
                float(_u7_zm.get("scrollHeight") or 0.0)
                - float(_u7_zm.get("clientHeight") or 0.0),
            )
            from src.fit_verifier import FitAnalysis, RoleFit
            _u7_fa_roles, _u7_fa_containers = {}, {}
            for _u7_dz in debug_zones:
                _u7_pos = _u7_dz.get("position")
                if not _u7_pos:
                    continue
                _u7_alloc = float(_u7_dz.get("height_px") or 0.0)
                _u7_zmi = _u7_zof.get(_u7_pos) or {}
                _u7_ch = float(_u7_zmi.get("clientHeight") or _u7_alloc)
                _u7_sh = float(_u7_zmi.get("scrollHeight") or _u7_ch)
                _u7_fa_roles[_u7_pos] = RoleFit(
                    role=_u7_pos, allocated_px=_u7_alloc,
                    shortfall_px=_u7_sh - _u7_ch,
                )
                _u7_fa_containers[_u7_pos] = {
                    "zone": "slide_body", "height_px": int(_u7_alloc),
                }
            _u7_salvage = _attempt_salvage_chain(
                run_dir=run_dir, out_path=out_path,
                slide_title=slide_title, slide_footer=slide_footer,
                zones_data=zones_data, layout_preset=layout_preset, layout_css=layout_css,
                cascade_inputs={
                    "fit_analysis": FitAnalysis(roles=_u7_fa_roles),
                    "containers": _u7_fa_containers,
                    "min_margin_px": None,
                    "manual_zone_positions": list((override_zone_geometries or {}).keys()),
                    "excess_px": _u7_excess, "excess_after_glue_px": _u7_excess,
                    "block_count": len(
                        (_u7_tdz.get("placement_trace") or {}).get("internal_regions") or []
                    ) or 1,
                    "zone_position": _u7_tpos,
                    "current_font_px": float(_u7_tdz.get("font_size_px") or 0.0),
                    "available_lines": int(_u7_tdz.get("available_lines") or 0),
                    "chars_per_line": int(_u7_tdz.get("chars_per_line") or 0),
                },
                initial_failure_type=_u7_initial, gap_px=GRID_GAP,
            )
            _u7_prior_steps = retry_trace.get("salvage_steps") or []
            _u7_new_steps = _u7_salvage.get("salvage_steps") or []
            retry_trace.update(_u7_salvage)
            retry_trace["salvage_steps"] = _u7_prior_steps + _u7_new_steps
            if _u7_salvage.get("salvage_passed"):
                overflow = (_u7_new_steps[-1].get("post_salvage_overflow")) or overflow
                fit_classification = classify_visual_runtime_check(overflow, debug_zones)
                router_decision = route_fit_classification(fit_classification)
                router_decision["v4_fallback_summary"] = comp_debug.get("v4_fallback_summary")
                router_decision["v4_fallback_selections"] = comp_debug.get("v4_fallback_selections", [])
                router_decision["frame_reselect_fallback_status"] = (
                    "pre_render_rank_2_3_fallback_implemented; "
                    "post_render visual-fail rerender remains routed through existing action trace"
                )
                enrich_retry_trace_with_failure_classification(retry_trace)

    # 11.8 IMP-35 (#64) u5 — Step 17 deterministic POPUP gate executor.
    # Runs after the salvage cascade exits at cascade-terminal action
    # `details_popup_escalation` (router u3 IMPLEMENTED + failure_router u2
    # cascade row). Stamps popup_escalation_plan + idempotent has_popup
    # marker per unit onto retry_trace["popup_gate_records"]. Deterministic
    # gate — no AI call (feedback_ai_isolation_contract); the u4
    # api_gated split-decision hook is a separate cascade-stage record
    # consumed only when a future IMP activates the Anthropic API.
    # Consumer side (composition popup binding / render wiring) lands in
    # u6 / u7. q1 (per-unit), q2 (idempotent via has_popup), q3
    # (deterministic from fit_classification) — see Stage 2 plan.
    # next_proposed_action is the single canonical signal: it is set by
    # enrich_retry_trace_with_failure_classification via failure_router u2
    # (NEXT_ACTION_BY_FAILURE), which routes frame_reselect_insufficient ->
    # details_popup_escalation. This check is independent of whether the
    # salvage chain block ran, so the popup gate fires for any retry path
    # that lands on the cascade-terminal popup action.
    _next_action = (
        retry_trace.get("next_action_proposal") or {}
    ).get("next_proposed_action")
    if _next_action == "details_popup_escalation":
        _popup_cls_by_zone = {
            c.get("zone_position"): c
            for c in (fit_classification.get("classifications") or [])
            if c.get("category") in {
                "structural_major_overflow",
                "tabular_overflow",
            }
        }
        _zone_by_ssids = {
            tuple(z.get("source_section_ids") or []): z.get("position")
            for z in debug_zones
        }

        def _classification_for_unit(u):
            ssids = tuple(getattr(u, "source_section_ids", []) or [])
            zone_pos = _zone_by_ssids.get(ssids)
            return _popup_cls_by_zone.get(zone_pos) if zone_pos else None

        retry_trace["popup_gate_records"] = run_step17_popup_gate(
            units,
            classification_for_unit=_classification_for_unit,
            route_for_label=_imp05_route_hint,
            plan_for_classification=plan_details_popup_escalation,
        )
        retry_trace["popup_gate_executed"] = True
        retry_trace["popup_gate_terminal_action"] = "details_popup_escalation"

    # ─── Step 17: Implemented Action (retry) ───
    _write_step_artifact(
        run_dir, 17, "retry_trace",
        data=retry_trace,
        step_status=(
            "done" if retry_trace.get("retry_passed") or retry_trace.get("salvage_passed")
            else "failed" if retry_trace.get("retry_attempted") and not retry_trace.get("retry_passed")
            else "skipped"
        ),
        pipeline_path_connected=True,
        inputs=["step16_router_decision.json"],
        outputs=["step17_retry_trace.json"],
        note=(
            "A3 — zone_ratio_retry + IMP-12 u8/u9 salvage cascade "
            "(cross_zone_redistribute → glue_compression → font_step_compression). "
            "IMP-88 u6/u7 — salvage cascade extended with layout_adjust + "
            "frame_internal_fit_candidate; image_fit single-pass entry triggered "
            "from router (cascade tail frame_reselect remains PARTIAL pre-render only)."
        ),
    )

    # ─── Step 18: Failure Classification (A4-1) ───
    _write_step_artifact(
        run_dir, 18, "failure_classification",
        data=retry_trace.get("failure_classification") or {},
        step_status="done" if retry_trace.get("failure_classification") else "skipped",
        pipeline_path_connected=True,
        inputs=["step17_retry_trace.json"],
        outputs=["step18_failure_classification.json"],
        note="A4-1 — retry 실패 시 failure_type 분류.",
    )

    # ─── Step 19: Next Action Proposal (A4-2) ───
    _write_step_artifact(
        run_dir, 19, "next_action",
        data=retry_trace.get("next_action_proposal") or {},
        step_status="partial" if retry_trace.get("next_action_proposal") else "skipped",
        pipeline_path_connected=False,
        inputs=["step18_failure_classification.json"],
        outputs=["step19_next_action.json"],
        note="A4-2 — failure_type → next_proposed_action 1-D mapping. 실제 action 자체는 미구현 (impl_status=MISSING).",
    )

    # 12. Slide status — 자동 파이프라인 결과 보고 (review/UI 개념 X)
    slide_status = compute_slide_status(
        sections_for_status, units, comp_debug, overflow,
        adapter_needed_units=adapter_needed_units,
        debug_zones=debug_zones,
    )
    final_html_for_status = out_path.read_text(encoding="utf-8")
    rendered_text_coverage = _compute_rendered_text_coverage(
        slide_title=slide_title,
        slide_footer=slide_footer,
        sections=sections_for_status,
        rendered_html=final_html_for_status,
    )
    slide_status["rendered_text_coverage"] = rendered_text_coverage
    slide_status["text_coverage_passed"] = bool(rendered_text_coverage.get("passed"))
    forbidden_rendered_syntax = _detect_forbidden_rendered_syntax(final_html_for_status)
    slide_status["forbidden_rendered_syntax"] = forbidden_rendered_syntax
    applied_render_consistency = _compute_applied_render_consistency(
        layout_preset=layout_preset,
        rendered_html=final_html_for_status,
        debug_zones=debug_zones,
    )
    slide_status["applied_render_consistency"] = applied_render_consistency
    # issue #15 — density gate (payload 결정론 + 측정 높이, 리포팅 전용)
    density_gate = _compute_density_gate(zones_data, overflow)
    slide_status["density_gate"] = density_gate
    design_readiness = _compute_design_readiness(
        units=units,
        rendered_text_coverage=rendered_text_coverage,
        applied_render_consistency=applied_render_consistency,
        density_gate=density_gate,
    )
    slide_status["design_readiness"] = design_readiness
    # IMP-47B u8 주석 이력 보존 — Surface Step 12 AI repair outcomes through
    # slide_status (아래 ai_repair_status 블록). quality gate downgrade 3종은
    # issue #17 에서 _apply_quality_gate_downgrades 로 추출 (popup 승격 후
    # 재계산 경로에도 동일 적용 — 미적용 시 text 손실이 PASS 로 통과하는
    # 게이트 순서 버그가 있었음: mdx05 실측).
    _apply_quality_gate_downgrades(
        slide_status,
        rendered_text_coverage=rendered_text_coverage,
        forbidden_rendered_syntax=forbidden_rendered_syntax,
        applied_render_consistency=applied_render_consistency,
    )

    presentation_fit = _build_presentation_fit_report(
        overflow=overflow,
        override_zone_geometries=override_zone_geometries,
    )
    slide_status["presentation_fit"] = presentation_fit
    slide_status["technical_pass"] = bool(
        slide_status.get("rendered")
        and slide_status.get("full_mdx_coverage")
        and rendered_text_coverage.get("passed")
        and forbidden_rendered_syntax.get("passed")
        and applied_render_consistency.get("passed")
    )
    slide_status["visual_pass"] = bool(overflow.get("passed"))
    # issue #15 (#98 추천 1) — presentation_ready 에 density 통합: 기계 PASS
    # 인데 사람 눈에 빽빽한 false-positive(MDX02) 차단.
    slide_status["presentation_ready"] = bool(
        slide_status["technical_pass"]
        and slide_status["visual_pass"]
        and presentation_fit.get("passed")
        and density_gate.get("passed", True)
    )
    slide_status["presentation_reselection"] = _build_t28_5c_reselection_trace(
        units=units,
        debug_zones=debug_zones,
        layout_preset=layout_preset,
        router_decision=router_decision,
        presentation_fit=presentation_fit,
        override_zone_geometries=override_zone_geometries,
    )
    t28_5d_popup_result = _attempt_t28_5d_popup_second_pass(
        units=units,
        zones_data=zones_data,
        presentation_reselection=slide_status["presentation_reselection"],
        run_dir=run_dir,
        out_path=out_path,
        slide_title=slide_title,
        slide_footer=slide_footer,
        layout_preset=layout_preset,
        layout_css=layout_css,
        gap_px=GRID_GAP,
        postprocess_html=lambda candidate_html: _postprocess_phase_z2_rendered_html(
            candidate_html,
            stage0_normalized_assets=stage0_normalized_assets,
            override_image_overrides=override_image_overrides,
            override_slide_css=override_slide_css,
            mdx_source_text=mdx_source_text,
        ),
        # issue #16 — salvage 정책 차단 소진 트리거용 (retry_trace 기반)
        retry_trace=retry_trace,
    )
    slide_status["presentation_popup"] = t28_5d_popup_result
    if t28_5d_popup_result.get("promoted"):
        overflow = t28_5d_popup_result.get("post_popup_overflow") or overflow
        slide_status = compute_slide_status(
            sections_for_status, units, comp_debug, overflow,
            adapter_needed_units=adapter_needed_units,
            debug_zones=debug_zones,
        )
        final_html_for_status = out_path.read_text(encoding="utf-8")
        rendered_text_coverage = _compute_rendered_text_coverage(
            slide_title=slide_title,
            slide_footer=slide_footer,
            sections=sections_for_status,
            rendered_html=final_html_for_status,
        )
        forbidden_rendered_syntax = _detect_forbidden_rendered_syntax(final_html_for_status)
        applied_render_consistency = _compute_applied_render_consistency(
            layout_preset=layout_preset,
            rendered_html=final_html_for_status,
            debug_zones=debug_zones,
        )
        # issue #15 — popup 승격 후 재계산 경로에도 density gate 동일 배선
        density_gate = _compute_density_gate(zones_data, overflow)
        design_readiness = _compute_design_readiness(
            units=units,
            rendered_text_coverage=rendered_text_coverage,
            applied_render_consistency=applied_render_consistency,
            density_gate=density_gate,
        )
        presentation_fit = _build_presentation_fit_report(
            overflow=overflow,
            override_zone_geometries=override_zone_geometries,
        )
        slide_status["rendered_text_coverage"] = rendered_text_coverage
        slide_status["text_coverage_passed"] = bool(rendered_text_coverage.get("passed"))
        slide_status["forbidden_rendered_syntax"] = forbidden_rendered_syntax
        slide_status["applied_render_consistency"] = applied_render_consistency
        slide_status["density_gate"] = density_gate
        slide_status["design_readiness"] = design_readiness
        slide_status["presentation_fit"] = presentation_fit
        # issue #17 — 재계산 경로에도 quality gate 강등 적용 (미적용 시
        # text 손실이 overall=PASS 로 통과하던 게이트 순서 버그).
        _apply_quality_gate_downgrades(
            slide_status,
            rendered_text_coverage=rendered_text_coverage,
            forbidden_rendered_syntax=forbidden_rendered_syntax,
            applied_render_consistency=applied_render_consistency,
        )
        slide_status["technical_pass"] = bool(
            slide_status.get("rendered")
            and slide_status.get("full_mdx_coverage")
            and rendered_text_coverage.get("passed")
            and forbidden_rendered_syntax.get("passed")
            and applied_render_consistency.get("passed")
        )
        slide_status["visual_pass"] = bool(overflow.get("passed"))
        slide_status["presentation_ready"] = bool(
            slide_status["technical_pass"]
            and slide_status["visual_pass"]
            and presentation_fit.get("passed")
            and density_gate.get("passed", True)
        )
        slide_status["presentation_reselection"] = _build_t28_5c_reselection_trace(
            units=units,
            debug_zones=debug_zones,
            layout_preset=layout_preset,
            router_decision=router_decision,
            presentation_fit=presentation_fit,
            override_zone_geometries=override_zone_geometries,
        )
        slide_status["presentation_popup"] = t28_5d_popup_result

    slide_status["ai_repair_status"] = _summarize_ai_repair_status(
        ai_repair_records, ai_repair_coverage_invariant,
    )

    # ─── Step 20: Slide Status ───
    _write_step_artifact(
        run_dir, 20, "slide_status",
        data=slide_status,
        step_status="done",
        pipeline_path_connected=True,
        inputs=["step14_visual_check.json", "step17_retry_trace.json", "step19_next_action.json"],
        outputs=["step20_slide_status.json", "step20_final_status.html"],
        note="자동 파이프라인 최종 결과 보고. overall = PASS/RENDERED_WITH_VISUAL_REGRESSION/PARTIAL_COVERAGE 등.",
    )
    # Step 20 HTML — 최종 판정 시각 보고
    _overall = slide_status.get("overall", "?")
    # IMP-87 u3 — route the dashboard CSS class through _final_status_html_class
    # so EMPTY_SHELL_NO_CONTENT renders as "fail" (red) instead of the legacy
    # substring-default "partial" amber. Other enums keep their pre-IMP-87
    # colour (Stage 2 axis A5 lock).
    _ov_class = _final_status_html_class(_overall)
    _vfs = slide_status.get("visual_fail_reasons") or []
    _vfs_html = (
        "<ul>" + "".join(f"<li>{v}</li>" for v in _vfs) + "</ul>"
        if _vfs else "<p>없음</p>"
    )
    _aligned = slide_status.get("aligned_section_ids") or []
    _covered = slide_status.get("covered_section_ids") or []
    _filtered = slide_status.get("filtered_section_ids") or []
    _ai_repair = slide_status.get("ai_repair_status") or {}
    _ai_repair_label = (
        f'{_ai_repair.get("status", "?")} '
        f'(human_review_required={_ai_repair.get("human_review_required", False)})'
    )
    _write_step_html(
        run_dir, 20, "final_status",
        title="Final Slide Status",
        body_html=(
            f'<h2>Overall: <span class="{_ov_class}">{_overall}</span></h2>'
            f'<table>'
            f'<tr><th>rendered</th><td>{slide_status.get("rendered")}</td></tr>'
            f'<tr><th>visual_check_passed</th><td>{slide_status.get("visual_check_passed")}</td></tr>'
            f'<tr><th>full_mdx_coverage</th><td>{slide_status.get("full_mdx_coverage")}</td></tr>'
            f'<tr><th>technical_pass</th><td>{slide_status.get("technical_pass")}</td></tr>'
            f'<tr><th>visual_pass</th><td>{slide_status.get("visual_pass")}</td></tr>'
            f'<tr><th>presentation_ready</th><td>{slide_status.get("presentation_ready")}</td></tr>'
            f'<tr><th>aligned_section_ids</th><td>{_aligned}</td></tr>'
            f'<tr><th>covered_section_ids</th><td>{_covered}</td></tr>'
            f'<tr><th>filtered_section_ids</th><td>{_filtered}</td></tr>'
            f'<tr><th>adapter_needed_count</th><td>{slide_status.get("adapter_needed_count", 0)}</td></tr>'
            f'<tr><th>content_truncated_count</th><td>{slide_status.get("content_truncated_count", 0)}</td></tr>'
            f'<tr><th>ai_repair_status</th><td>{_ai_repair_label}</td></tr>'
            f'</table>'
            f'<h2>Visual Fail Reasons</h2>{_vfs_html}'
            f'<h2>Note</h2><p>{slide_status.get("note", "")}</p>'
        ),
        step_status="done",
        inputs=["step14_visual_check.json", "step17_retry_trace.json"],
        outputs=["step20_slide_status.json", "step20_final_status.html"],
    )

    # 13. Debug.json
    debug_path = write_debug_json(
        run_dir, layout_preset, debug_zones, layout_css, overflow,
        composition_debug=comp_debug,
        slide_status=slide_status,
        fit_classification=fit_classification,
        router_decision=router_decision,
        retry_trace=retry_trace,
        asset_copy_traces=asset_copy_traces,
    )
    print(f"  debug   : {debug_path}")

    # ─── Step 21: Debug Trace ───
    _write_step_artifact(
        run_dir, 21, "debug_index",
        data={
            "debug_json_path": str(debug_path),
            "debug_json_size_bytes": debug_path.stat().st_size,
            "placement_trace_recorded_zones": len(debug_zones),
            "frame_slot_metrics_count": len(
                (overflow or {}).get("frame_slot_metrics")
                or (overflow or {}).get("details", {}).get("frame_slot_metrics", [])
            ),
        },
        step_status="partial",
        pipeline_path_connected=True,
        inputs=[],
        outputs=["step21_debug_index.json", "debug.json"],
        note="placement_trace per-zone + frame_slot_metrics F29 만 기록. region marker partial 미주입 — Step 21 ⚠ partial.",
    )

    # ─── Step 22: 사용자 확인 / Export (future, UI 영역) ───
    _write_step_artifact(
        run_dir, 22, "user_export",
        data={"status": "future", "scope": "UI 영역 — 자동 파이프라인 범위 외"},
        step_status="future",
        pipeline_path_connected=False,
        inputs=[],
        outputs=["step22_user_export.json"],
        note="UI / export 단계. 자동 파이프라인 범위 외 — 사용자 직접 확인 / 다운로드.",
    )

    # 13. Status report
    overall = slide_status["overall"]
    print(f"  status  : {overall}")
    if slide_status["filtered_section_ids"]:
        print(f"            filtered_sections    = {slide_status['filtered_section_ids']}")
    if slide_status["adapter_needed_count"]:
        print(f"            adapter_needed_count = {slide_status['adapter_needed_count']}")
    if slide_status["content_truncated_count"]:
        print(f"            content_truncated    = "
              f"{[(c['position'], c['truncated_count']) for c in slide_status['content_truncated_units']]}")
    if not slide_status["visual_check_passed"]:
        for r in (overflow.get("fail_reasons") or [])[:3]:
            print(f"            visual_fail = {r}")
    # fit_classifier + router 결과 요약
    if not fit_classification["visual_check_passed"]:
        cats = fit_classification["categories_seen"]
        print(f"            fit_categories       = {cats}")
        if router_decision["router_active"]:
            actions = router_decision["proposed_actions_summary"]
            status = router_decision["implementation_status_summary"]
            missing = router_decision["missing_actions_pending_impl"]
            print(f"            proposed_actions     = {actions}")
            print(f"            impl_status_summary  = {status}")
            if missing:
                print(f"            missing_actions      = {missing}  (현재 미구현 → abort)")
    # retry 결과 요약 (A3) + failure classification / next action proposal (A4)
    if retry_trace.get("retry_attempted"):
        print(f"            retry_action         = {retry_trace['retry_action']}")
        print(f"            retry_passed         = {retry_trace['retry_passed']}")
        if not retry_trace["retry_passed"]:
            print(f"            retry_failure        = {retry_trace.get('retry_failure_reason')}")
    fc = retry_trace.get("failure_classification") or {}
    nap = retry_trace.get("next_action_proposal") or {}
    if fc.get("failure_type"):
        print(f"            failure_type         = {fc['failure_type']}")
        if nap.get("next_proposed_action"):
            print(f"            next_proposed_action = {nap['next_proposed_action']} "
                  f"(impl_status={nap.get('next_action_implementation_status')})")

    # 13. Exit 정책 — visual fail 은 abort, partial coverage 는 abort 안 하지만 PASS 도 아님
    # IMP-87 u3 — BLOCKED exit on EMPTY_SHELL_NO_CONTENT precedes the legacy
    # visual_fail / partial_coverage branches (Stage 2 axis A4). A slide whose
    # every selected unit is an IMP-30 u4 empty-shell placeholder carries no
    # MDX content; without this branch a Case B run could pass Selenium
    # overflow checks (nothing to overflow) and silently return overall
    # EMPTY_SHELL_NO_CONTENT without any CLI exit signal, violating
    # feedback_artifact_status_naming.
    if _is_blocked_overall(overall):
        _aligned = slide_status.get("aligned_section_ids") or []
        _empty_ids = slide_status.get("empty_shell_section_ids") or []
        _empty_count = slide_status.get("empty_shell_unit_count", 0)
        _content_count = slide_status.get("content_rendered_unit_count", 0)
        print(
            f"\n[Phase Z-2 IMP-87 u3] BLOCKED @ empty_shell_no_content ({overall})",
            file=sys.stderr,
        )
        print(
            "  reason   : every selected unit is IMP-30 u4 empty-shell placeholder "
            "(no MDX content rendered)",
            file=sys.stderr,
        )
        print(f"  aligned  : {_aligned}", file=sys.stderr)
        print(f"  shell    : {_empty_ids}", file=sys.stderr)
        print(
            f"  units    : empty_shell_unit_count={_empty_count} "
            f"content_rendered_unit_count={_content_count}",
            file=sys.stderr,
        )
        sys.exit(1)

    if not slide_status["visual_check_passed"]:
        err_path = write_overflow_error(run_dir, overflow)
        print(f"\n[Phase Z-2 MVP-1.5b] FAIL @ visual_runtime_check ({overall})", file=sys.stderr)
        for reason in overflow.get("fail_reasons", [overflow.get("error", "unknown")]):
            print(f"  - {reason}", file=sys.stderr)
        print(f"  error   : {err_path}", file=sys.stderr)
        sys.exit(1)

    if not slide_status["full_mdx_coverage"]:
        print(
            f"\n[Phase Z-2 MVP-1.5b] PARTIAL — visual check OK 지만 "
            f"sections {slide_status['filtered_section_ids']} 가 composition planner 에서 "
            f"필터됨 (allowed_statuses 미통과). final.html 은 viable units 만 렌더된 "
            f"partial artifact. full MDX slide 아님."
        )
        return out_path

    print(
        f"\n[Phase Z-2 MVP-1.5b] {overall} — visual check OK + full MDX coverage. "
        f"최종 사용자 브라우저 검증 후 ship 가능."
    )
    return out_path


if __name__ == "__main__":
    import argparse

    parser = argparse.ArgumentParser(
        prog="python -m src.phase_z2_pipeline",
        description="Phase Z-2 MVP-1.5b pipeline (MDX → 1 slide HTML).",
    )
    parser.add_argument("mdx_path", type=Path, help="MDX 파일 경로")
    parser.add_argument(
        "run_id", nargs="?", default=None,
        help="run_id (출력 디렉토리 이름). 없으면 자동 생성 (basename + timestamp).",
    )
    parser.add_argument(
        "--override-layout", dest="override_layout", default=None,
        metavar="PRESET",
        help=(
            "layout_preset 강제 (8 preset 중 하나 — single, horizontal-2, vertical-2, "
            "top-1-bottom-2, top-2-bottom-1, left-1-right-2, left-2-right-1, grid-2x2). "
            "없으면 자동 결정 (count-based v0)."
        ),
    )
    parser.add_argument(
        "--override-frame", dest="override_frames", action="append", default=[],
        metavar="UNIT_ID=TEMPLATE_ID",
        help=(
            "unit_id 의 frame template 강제 변경. UNIT_ID 는 \"+\".join(source_section_ids) "
            "(e.g., 03-1 또는 03-1+03-2). multiple 가능: --override-frame 03-1=foo "
            "--override-frame 03-2=bar"
        ),
    )
    parser.add_argument(
        "--override-zone-geometry", dest="override_zone_geometries", action="append", default=[],
        metavar="ZONE_ID=X,Y,W,H",
        help=(
            "zone position (top/bottom/left/right/...) 의 slide-body 내부 비율 (0~1) "
            "강제. horizontal-2 / vertical-2 만 지원. multiple 가능: "
            "--override-zone-geometry top=0,0,1,0.3 --override-zone-geometry bottom=0,0.3,1,0.7"
        ),
    )
    # IMP-06 (#6) — zone-section assignment override (backend/CLI/composition only;
    # frontend bridge = #38). ZONE_ID = active layout preset position names
    # (single=primary, horizontal-2=top/bottom, grid-2x2=top-left/top-right/...).
    parser.add_argument(
        "--override-section-assignment",
        dest="override_section_assignments",
        action="append",
        default=[],
        metavar="ZONE_ID=section_id[,section_id]",
        help=(
            "zone position 의 section assignment 강제. ZONE_ID = active layout 의 "
            "position name (e.g., top, bottom, left, right, top-left, ...). section_id = "
            "MDX section identifier (e.g., 03-1). multiple sections per zone = comma-separated. "
            "multiple flags: --override-section-assignment top=03-1 "
            "--override-section-assignment bottom=03-2,03-3"
        ),
    )
    # IMP-51 (#79) u5 — image override CLI flag. IMAGE_ID = stable id stamped
    # on user-content `<img>` tags by src/image_id_stamper.py (u4). X,Y,W,H =
    # percent-of-slide coordinates (0–100, slide-absolute), consistent with
    # the typed client `ImageOverride` shape (u3, userOverridesApi.ts) and
    # the persisted `image_overrides` axis (u1, KNOWN_AXES). The render-time
    # CSS injection consuming this mapping lands in u7; u5 is the CLI surface.
    parser.add_argument(
        "--override-image",
        dest="override_image_overrides",
        action="append",
        default=[],
        metavar="IMAGE_ID=X,Y,W,H",
        help=(
            "user-content image 의 slide-absolute geometry 강제. IMAGE_ID = "
            "src/image_id_stamper.py 가 stamp 한 `data-image-id` value "
            "(e.g., img-1a2b3c4d5e). X,Y,W,H = percent-of-slide (0–100, "
            "slide-absolute) — typed client ImageOverride shape 와 일치. "
            "multiple flags: --override-image img-abc=10,15,30,25 "
            "--override-image img-def=50,15,40,40"
        ),
    )
    # IMP-45 (#74) u5 — slide-level CSS override CLI surface. Two mutually
    # exclusive flags carrying the same axis: ``--override-slide-css TEXT``
    # passes inline CSS verbatim; ``--slide-css-file PATH`` reads UTF-8
    # CSS from disk. Both forward into the single ``override_slide_css``
    # kwarg on :func:`run_phase_z2_mvp1` (u4), which already mirrors the
    # marker-wrapped image_id_stamper injection contract at Step 13.
    # Manual mutual-exclusion (not ``add_mutually_exclusive_group``) so the
    # error stderr can name the axis pair explicitly with ``sys.exit(2)``,
    # matching sibling override surfaces (--override-frame /
    # --override-zone-geometry / --override-image).
    parser.add_argument(
        "--override-slide-css",
        dest="override_slide_css",
        default=None,
        metavar="CSS_TEXT",
        help=(
            "slide-level CSS override (inline). value is passed verbatim "
            "to the run_phase_z2_mvp1 override_slide_css kwarg; an "
            "optional outer `<style>` wrapper is allowed because the "
            "injector wraps the payload in its own marker-bracketed "
            "`<style>` block regardless. mutually exclusive with "
            "--slide-css-file."
        ),
    )
    parser.add_argument(
        "--slide-css-file",
        dest="slide_css_file",
        default=None,
        type=Path,
        metavar="PATH",
        help=(
            "slide-level CSS override (file). UTF-8-encoded CSS payload "
            "read from PATH and forwarded to the override_slide_css "
            "kwarg. fail-closed: missing file / non-UTF-8 bytes exit 2 "
            "with stderr message. mutually exclusive with "
            "--override-slide-css."
        ),
    )
    # IMP-46 u5 — auto-cache opt-in. When set, ``cache.save_proposal``
    # bypasses the ``user_approved`` gate only (``visual_check_passed``
    # is never bypassable). Source of truth is
    # ``settings.ai_fallback_auto_cache`` (src/config.py); this flag
    # mutates the setting in-process so downstream callers read the
    # same value through Settings rather than parsing args themselves.
    parser.add_argument(
        "--auto-cache",
        dest="auto_cache",
        action="store_true",
        default=False,
        help=(
            "Allow cache.save_proposal to bypass the user_approved gate "
            "(visual_check_passed remains mandatory). Sets "
            "settings.ai_fallback_auto_cache=True for this run."
        ),
    )
    # IMP-43 (#72) u1 — incremental rerun reuse pointer. Reuse target
    # = Step 0/1/2/5/6 deterministic artifacts from a prior run; Step 7
    # onward re-executes against the new frame overrides. Only frame
    # overrides preserve the reusable subset (Stage 2 boundary lock);
    # layout/geometry/section/image overrides invalidate it and are
    # rejected by the post-merge guard below. Signature threading +
    # snapshot copy/restore land in u5 and u4 respectively; this unit
    # only adds the CLI surface + fail-closed precondition guard.
    parser.add_argument(
        "--reuse-from",
        dest="reuse_from",
        default=None,
        metavar="PREV_RUN_ID",
        help=(
            "Reuse Step 0/1/2/5/6 artifacts from a previous run id "
            "(directory under data/runs/<PREV_RUN_ID>/phase_z2) and resume "
            "execution at Step 7. Only --override-frame is preserved; "
            "--override-layout / --override-zone-geometry / "
            "--override-section-assignment / --override-image invalidate "
            "the reusable boundary and will be rejected."
        ),
    )
    parser.add_argument(
        "--ignore-user-overrides",
        dest="ignore_user_overrides",
        action="store_true",
        default=False,
        help=(
            "Skip data/user_overrides/<mdx-stem>.json fallback for a clean "
            "frontend generate. Explicit CLI override flags still apply."
        ),
    )
    args = parser.parse_args()

    if args.auto_cache:
        from src.config import settings as _settings
        _settings.ai_fallback_auto_cache = True

    overrides_frames: dict[str, str] = {}
    for ov in args.override_frames:
        if "=" not in ov:
            print(
                f"[error] --override-frame must be UNIT_ID=TEMPLATE_ID, got: '{ov}'",
                file=sys.stderr,
            )
            sys.exit(2)
        k, v = ov.split("=", 1)
        overrides_frames[k.strip()] = v.strip()

    overrides_geoms: dict[str, dict] = {}
    for ov in args.override_zone_geometries:
        if "=" not in ov:
            print(f"[error] --override-zone-geometry must be ZONE_ID=X,Y,W,H, got: '{ov}'", file=sys.stderr)
            sys.exit(2)
        zid, vals = ov.split("=", 1)
        parts = vals.split(",")
        if len(parts) != 4:
            print(f"[error] --override-zone-geometry expects 4 floats X,Y,W,H, got: '{vals}'", file=sys.stderr)
            sys.exit(2)
        try:
            x, y, w, h = (float(p) for p in parts)
        except ValueError:
            print(f"[error] --override-zone-geometry floats parse fail: '{vals}'", file=sys.stderr)
            sys.exit(2)
        overrides_geoms[zid.strip()] = {"x": x, "y": y, "w": w, "h": h}

    # IMP-06 — parse --override-section-assignment into dict[str, list[str]].
    # Hard errors per Codex #2/#3 lock : missing `=` / empty ZONE_ID / empty section
    # list / duplicate ZONE_ID / duplicate section across zones (parse-time).
    overrides_section_assignments: dict[str, list[str]] = {}
    _seen_sections_across_zones: dict[str, str] = {}  # section_id -> zone_id (first seen)
    for ov in args.override_section_assignments:
        if "=" not in ov:
            print(
                f"[error] --override-section-assignment must be ZONE_ID=section_id[,section_id], "
                f"got: '{ov}'",
                file=sys.stderr,
            )
            sys.exit(2)
        zid, vals = ov.split("=", 1)
        zid = zid.strip()
        if not zid:
            print(
                f"[error] --override-section-assignment ZONE_ID must be non-empty, got: '{ov}'",
                file=sys.stderr,
            )
            sys.exit(2)
        section_ids = [s.strip() for s in vals.split(",") if s.strip()]
        if not section_ids:
            print(
                f"[error] --override-section-assignment section list must be non-empty, "
                f"got: '{ov}'",
                file=sys.stderr,
            )
            sys.exit(2)
        if zid in overrides_section_assignments:
            print(
                f"[error] --override-section-assignment duplicate ZONE_ID '{zid}' "
                f"(first assignment kept). Provide each zone only once.",
                file=sys.stderr,
            )
            sys.exit(2)
        for sid in section_ids:
            if sid in _seen_sections_across_zones:
                print(
                    f"[error] --override-section-assignment section '{sid}' appears in "
                    f"multiple zones ('{_seen_sections_across_zones[sid]}' and '{zid}'). "
                    "A section may be assigned to at most one zone.",
                    file=sys.stderr,
                )
                sys.exit(2)
            _seen_sections_across_zones[sid] = zid
        overrides_section_assignments[zid] = section_ids

    # IMP-51 (#79) u5 — parse --override-image into dict[str, dict[str, float]].
    # Mirrors --override-zone-geometry parsing pattern: each flag is
    # IMAGE_ID=X,Y,W,H with 4 floats; multiple flags accumulate. Hard errors
    # on missing `=` / wrong float count / non-numeric values / empty IMAGE_ID
    # / duplicate IMAGE_ID. The on-disk schema (u1 KNOWN_AXES) and typed
    # client (u3 ImageOverride) both expect percent-of-slide values in
    # 0–100; the CLI accepts floats without range clamping here so the
    # error remains the user's mistake to read rather than a silent shift.
    overrides_images: dict[str, dict[str, float]] = {}
    for ov in args.override_image_overrides:
        if "=" not in ov:
            print(
                f"[error] --override-image must be IMAGE_ID=X,Y,W,H, got: '{ov}'",
                file=sys.stderr,
            )
            sys.exit(2)
        iid, vals = ov.split("=", 1)
        iid = iid.strip()
        if not iid:
            print(
                f"[error] --override-image IMAGE_ID must be non-empty, got: '{ov}'",
                file=sys.stderr,
            )
            sys.exit(2)
        if iid in overrides_images:
            print(
                f"[error] --override-image duplicate IMAGE_ID '{iid}' "
                f"(first assignment kept). Provide each image only once.",
                file=sys.stderr,
            )
            sys.exit(2)
        parts = vals.split(",")
        if len(parts) != 4:
            print(
                f"[error] --override-image expects 4 floats X,Y,W,H, got: '{vals}'",
                file=sys.stderr,
            )
            sys.exit(2)
        try:
            x, y, w, h = (float(p) for p in parts)
        except ValueError:
            print(
                f"[error] --override-image floats parse fail: '{vals}'",
                file=sys.stderr,
            )
            sys.exit(2)
        overrides_images[iid] = {"x": x, "y": y, "w": w, "h": h}

    # IMP-45 (#74) u5 — resolve slide-level CSS override CLI surface to a
    # single string. Mutually exclusive: both flags set → exit 2. File
    # path read is UTF-8 strict; missing path or non-UTF-8 bytes → exit
    # 2. When neither flag is set, ``override_slide_css`` stays ``None``
    # and Step 13 falls back to the MDX ``slide_overrides.css``
    # frontmatter via ``_resolve_slide_css_from_frontmatter`` (u4).
    if args.override_slide_css is not None and args.slide_css_file is not None:
        print(
            "[error] --override-slide-css and --slide-css-file are mutually "
            "exclusive; pass only one.",
            file=sys.stderr,
        )
        sys.exit(2)
    _final_override_slide_css: Optional[str] = args.override_slide_css
    if args.slide_css_file is not None:
        try:
            _final_override_slide_css = args.slide_css_file.read_text(
                encoding="utf-8"
            )
        except FileNotFoundError:
            print(
                f"[error] --slide-css-file path does not exist: "
                f"{args.slide_css_file}",
                file=sys.stderr,
            )
            sys.exit(2)
        except UnicodeDecodeError as _exc:
            print(
                f"[error] --slide-css-file must be UTF-8 encoded "
                f"({args.slide_css_file}): {_exc}",
                file=sys.stderr,
            )
            sys.exit(2)

    # IMP-56 (#90) u16 — text_overrides + structure_overrides are file-only
    # axes (frontend captures via /api/user-overrides PUT; no CLI flag
    # surface, by design — per-line text edits and per-zone slot reorders /
    # hides are too granular for argparse). Initialize empty here so the
    # user_overrides.json fallback below can fill them, mirroring the
    # ``overrides_images`` (IMP-51 #79 u6) post-CLI / pre-_persisted shape.
    overrides_text: dict[str, dict[str, str]] = {}
    overrides_structure: dict[str, dict[str, list[str]]] = {}

    # IMP-52 (#80) u2 — user_overrides.json persistence fallback.
    # After argparse fully parses CLI flags, fill ONLY the axes the user
    # did NOT pass on the command line. CLI payload always wins over the
    # persisted file (Stage 2 lock: "CLI > file, 결손 축만 채움").
    # MDX stem keys the persistence file; invalid stems / corrupt file
    # degrade gracefully (warning to stderr + no override injected).
    from src.user_overrides_io import (
        InvalidOverrideKey,
        load as _load_user_overrides,
        validate_key as _validate_overrides_key,
    )

    _final_override_layout = args.override_layout
    _ov_key = None
    if args.ignore_user_overrides:
        print(
            "[user_overrides] clean generate: skipping persisted fallback.",
            file=sys.stderr,
        )
    else:
        try:
            _ov_key = _validate_overrides_key(Path(args.mdx_path).stem)
        except InvalidOverrideKey as _exc:
            print(
                f"[user_overrides] warning: cannot derive persistence key from "
                f"mdx_path {args.mdx_path!r}: {_exc}; skipping fallback.",
                file=sys.stderr,
            )
            _ov_key = None
    if _ov_key is not None:
        _persisted = _load_user_overrides(_ov_key)
        # layout — CLI None → fill from file (must be str).
        if _final_override_layout is None:
            _file_layout = _persisted.get("layout")
            if isinstance(_file_layout, str) and _file_layout:
                _final_override_layout = _file_layout
        # frames — CLI empty → fill from file (must be dict[str, str]).
        if not overrides_frames:
            _file_frames = _persisted.get("frames")
            if isinstance(_file_frames, dict):
                overrides_frames = {
                    str(k): str(v)
                    for k, v in _file_frames.items()
                    if isinstance(k, str) and isinstance(v, str)
                }
        # zone_geometries — CLI empty → fill from file (dict[str, dict]).
        if not overrides_geoms:
            _file_geoms = _persisted.get("zone_geometries")
            if isinstance(_file_geoms, dict):
                _accepted: dict[str, dict] = {}
                for _zid, _g in _file_geoms.items():
                    if (
                        isinstance(_zid, str)
                        and isinstance(_g, dict)
                        and all(k in _g for k in ("x", "y", "w", "h"))
                    ):
                        try:
                            _accepted[_zid] = {
                                "x": float(_g["x"]),
                                "y": float(_g["y"]),
                                "w": float(_g["w"]),
                                "h": float(_g["h"]),
                            }
                        except (TypeError, ValueError):
                            continue
                overrides_geoms = _accepted
        # zone_sections — CLI empty AND persisted manual_section_assignment is
        # exactly True → fill from file (dict[str, list[str]]). IMP-55 (#93) u9
        # marker gate (fail-closed) : ``manual_section_assignment`` absent /
        # False / non-bool (string/int/list/dict) all skip the fallback so a
        # stale ``zone_sections`` axis left on disk from a prior drag cannot
        # smuggle ``--override-section-assignment`` into the next run after the
        # user reset intent via layout apply/cancel (u5 / u12 write
        # ``manual_section_assignment: false`` explicitly). CLI
        # ``--override-section-assignment`` payloads remain authoritative
        # (u11 truth-table) — this gate only affects the file→fallback path.
        if (
            not overrides_section_assignments
            and _persisted.get("manual_section_assignment") is True
        ):
            _file_sections = _persisted.get("zone_sections")
            if isinstance(_file_sections, dict):
                _accepted_sec: dict[str, list[str]] = {}
                for _zid, _sec_list in _file_sections.items():
                    if isinstance(_zid, str) and isinstance(_sec_list, list):
                        _sids = [s for s in _sec_list if isinstance(s, str) and s]
                        if _sids:
                            _accepted_sec[_zid] = _sids
                overrides_section_assignments = _accepted_sec
        # image_overrides — CLI empty → fill from file (dict[str, dict]).
        # IMP-51 (#79) u6 — mirrors zone_geometries validation: only accept
        # mappings of {image_id: {x,y,w,h}} with float-coercible values.
        if not overrides_images:
            _file_images = _persisted.get("image_overrides")
            if isinstance(_file_images, dict):
                _accepted_img: dict[str, dict] = {}
                for _iid, _g in _file_images.items():
                    if (
                        isinstance(_iid, str)
                        and _iid
                        and isinstance(_g, dict)
                        and all(k in _g for k in ("x", "y", "w", "h"))
                    ):
                        try:
                            _accepted_img[_iid] = {
                                "x": float(_g["x"]),
                                "y": float(_g["y"]),
                                "w": float(_g["w"]),
                                "h": float(_g["h"]),
                            }
                        except (TypeError, ValueError):
                            continue
                overrides_images = _accepted_img
        # text_overrides — file-only (no CLI flag) → fill from file as
        # dict[zone_id, dict[text_path, value]]. IMP-56 (#90) u16. Inline
        # gate accepts only str-keyed inner dicts; the u4 validator runs
        # again at Step 12 apply time, where malformed inner entries
        # surface as silent per-zone skips in the ``step12_text_overrides``
        # audit (Phase Z PZ-4 "no silent shrink" — count, don't drop).
        if not overrides_text:
            _file_text = _persisted.get("text_overrides")
            if isinstance(_file_text, dict):
                _accepted_text: dict[str, dict[str, str]] = {}
                for _zid, _payload in _file_text.items():
                    if isinstance(_zid, str) and isinstance(_payload, dict):
                        _entries = {
                            str(_k): str(_v)
                            for _k, _v in _payload.items()
                            if isinstance(_k, str) and isinstance(_v, str)
                        }
                        if _entries:
                            _accepted_text[_zid] = _entries
                overrides_text = _accepted_text
        # structure_overrides — file-only → fill from file as dict[zone_id,
        # {slot_order|hidden_slots: list[str]}]. IMP-56 (#90) u16. Inner
        # keys locked to the two allowed names; the u6 validator drops any
        # other key + frame-swap payloads at apply time so the CLI gate
        # only does the list[str] structural coercion. Empty inner dicts
        # are dropped here so ``overrides_structure or None`` collapses to
        # ``None`` on the call site (matches IMP-51 #79 u6 ``or None`` shape).
        if not overrides_structure:
            _file_struct = _persisted.get("structure_overrides")
            if isinstance(_file_struct, dict):
                _accepted_struct: dict[str, dict[str, list[str]]] = {}
                for _zid, _payload in _file_struct.items():
                    if isinstance(_zid, str) and isinstance(_payload, dict):
                        _entries_s: dict[str, list[str]] = {}
                        for _k, _v in _payload.items():
                            if (
                                _k in ("slot_order", "hidden_slots")
                                and isinstance(_v, list)
                            ):
                                _entries_s[_k] = [
                                    s for s in _v if isinstance(s, str)
                                ]
                        if _entries_s:
                            _accepted_struct[_zid] = _entries_s
                overrides_structure = _accepted_struct

    # IMP-43 (#72) u1 — fail-closed reuse_from precondition guard.
    # Placed AFTER the user_overrides.json merge so persisted overrides
    # are evaluated against the same reuse boundary as CLI overrides
    # (Stage 2 lock: "fail-closed guard after user_overrides.json merge
    # and before dispatch"). Reuse target = Step 0/1/2/5/6 deterministic
    # artifacts; only frame overrides preserve that subset. layout /
    # zone_geometry / zone_section / image overrides each invalidate at
    # least one of Step 0/1/2/5/6 and must reject. Frame-only is allowed
    # (no rejected axes → falls through to dispatch). Error stderr names
    # every rejected axis so the user can either drop the rejected axes
    # or rerun without --reuse-from.
    if args.reuse_from is not None:
        _rejected_axes: list[str] = []
        if _final_override_layout is not None:
            _rejected_axes.append("layout")
        if overrides_geoms:
            _rejected_axes.append("zone_geometry")
        if overrides_section_assignments:
            _rejected_axes.append("zone_section")
        if overrides_images:
            _rejected_axes.append("image")
        if _rejected_axes:
            print(
                f"[error] --reuse-from incompatible with override axes: "
                f"{', '.join(_rejected_axes)}. Only --override-frame is "
                f"preserved across Step 0/1/2/5/6 reuse; drop the rejected "
                f"overrides or rerun without --reuse-from.",
                file=sys.stderr,
            )
            sys.exit(2)

    run_phase_z2_mvp1(
        args.mdx_path,
        args.run_id,
        override_layout=_final_override_layout,
        override_frames=overrides_frames or None,
        override_zone_geometries=overrides_geoms or None,
        override_section_assignments=overrides_section_assignments or None,
        override_image_overrides=overrides_images or None,
        override_slide_css=_final_override_slide_css,
        override_text_overrides=overrides_text or None,
        override_structure_overrides=overrides_structure or None,
        reuse_from=args.reuse_from,
    )