feat(IMP-15): 실행-1 — Step 14 image_aspect_mismatch detection

Issue: #45 (IMP-15 실행-1, image axis only). Adds Selenium-based <img> aspect ratio measurement to Step 14 run_overflow_check + numeric tolerance gate. Tolerance lives as module-scope constant so tests can import it. src/phase_z2_pipeline.py (+73/-2): - L131-L135 IMAGE_ASPECT_DELTA_TOL = 0.05 (module scope, importable) - L2216-L2261 JS payload extension: image_events[] per <img> (src, zone_position via closest('.zone') with 'unknown' fallback, zone_template_id, natural/rendered w+h+ratio, delta, slide-rel bbox) - L2262 run_overflow_check return extended with image_events - L2302-L2320 Python aggregation: abs(delta) > TOL ⇒ fail_reasons append 'image aspect mismatch in zone--<pos>: natural=<n> rendered=<r> delta=<+d> (template=<tid>, tol=0.05, src=<src>)'. Null-delta entries (image not loaded) are skipped — no false positive. Branch placed AFTER existing non-image branches; ordering & strings for slide/slide-body/zone/clipped_inner unchanged. - L4425-L4429 Step 14 note: image half closed, table half deferred to 실행-2. tests/phase_z2/test_phase_z2_step14_image_check.py (+196, new): - 3-tier chromedriver resolver mirroring pipeline (PROJECT_ROOT/ chromedriver{,.exe} → PATH → Selenium Manager probe). - pytestmark: skip when chromedriver unresolvable AND PHASE_Z_REQUIRE_SELENIUM != '1'; xfail(strict=True) opt-in when =='1'. - Fixture A: 200×100 img rendered 200×100 → aspect_delta < 0.05, passed. - Fixture B: 200×100 intrinsic forced to 200×200 → delta > 0.30, fail_reason present. - Fixture C: <img> with no .zone ancestor → zone_position == 'unknown'. Verification (Stage 4 PASS, Claude + Codex independent): - pytest -q tests/phase_z2/test_phase_z2_step14_image_check.py → 3 passed - PHASE_Z_REQUIRE_SELENIUM=1 same suite → 3 passed (strict opt-in) - pytest -q tests/phase_z2 → 90 passed (no regression) - pytest -q --ignore=tests/matching → 174 passed Scope-locked: no slide_base.html / catalog / classifier / debug.json / spec-doc changes. table_events (실행-2), visual_check_passed flip (실행-3), debug.json image_events surfacing + PHASE-Z spec doc row (실행-4) remain queued as separate IMP-15 child execution issues. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
feat(IMP-14): A-4 — slide_base embedded vs standalone mode contract
2026-05-18 18:01:28 +09:00 · 2026-05-18 07:21:31 +09:00 · 2026-05-18 06:25:05 +09:00 · 2026-05-18 02:07:22 +09:00 · 2026-05-17 22:29:17 +09:00 · 2026-05-17 19:43:13 +09:00
54 changed files with 4292 additions and 188 deletions
@@ -186,6 +186,12 @@ export default function SlideCanvas({
  // 슬라이드 박스 표시 조건 — final.html 있거나 pendingLayout 모드.
  const showSlideBox = (finalHtmlUrl || isPendingLayout) && !isPipelineRunning;

+  // IMP-14 (Step 13 A-4) — backend slide_base.html 가 embedded vs standalone CSS
+  // contract 를 `?embedded=1` query 로 소유. 기존 query string 보존하면서 flag 만 추가.
+  const embeddedSrc = finalHtmlUrl
+    ? `${finalHtmlUrl}${finalHtmlUrl.includes("?") ? "&" : "?"}embedded=1`
+    : undefined;
+
  // wrapper 는 scaled 크기를 가지므로 layout 상 fit. 안의 슬라이드는 1280×720 으로
  // top-left origin scale 후 wrapper 안에 정확히 맞춤.
  const W_SCALED = SLIDE_W * scale;
@@ -283,37 +289,21 @@ export default function SlideCanvas({
          >
            <iframe
              ref={iframeRef}
-              src={finalHtmlUrl}
+              src={embeddedSrc}
              title="Phase Z 렌더 결과"
              className="w-full h-full border-0 block"
              scrolling="no"
              sandbox="allow-same-origin"
              style={{ pointerEvents: isEditMode ? "auto" : "none" }}
              onLoad={(e) => {
-                // final.html 은 standalone 표시용으로 body 에 padding / flex center /
-                // min-height: 100vh 가 있어서, iframe 안에서는 슬라이드가 잘림.
-                // .slide (1280×720) 만 보이도록 reset CSS 를 contentDocument 에 주입.
+                // IMP-14 (Step 13 A-4) — embedded vs standalone CSS reset 은 backend
+                // slide_base.html 가 `?embedded=1` query 로 소유. frontend 가 더 이상
+                // reset CSS 를 contentDocument 에 inject 하지 않음. embedded query 가
+                // backend auto-mode detection script 를 trigger 해서 html.embedded
+                // class 를 붙이고 standalone-only body 규칙을 reset.
                try {
                  const doc = (e.currentTarget as HTMLIFrameElement).contentDocument;
                  if (!doc) return;
-                  const style = doc.createElement("style");
-                  style.textContent = `
-                    html, body {
-                      margin: 0 !important;
-                      padding: 0 !important;
-                      min-height: 0 !important;
-                      height: 720px !important;
-                      width: 1280px !important;
-                      background: transparent !important;
-                      display: block !important;
-                      overflow: hidden !important;
-                    }
-                    .slide {
-                      box-shadow: none !important;
-                      margin: 0 !important;
-                    }
-                  `;
-                  doc.head.appendChild(style);

                  // 2026-05-14 — slide-level override CSS (catalog/template 무변).
                  // Home 이 mdx 별 default visual 보완 (bullet 간격 / zone 비율 등) 지정.
@@ -612,6 +602,28 @@ export default function SlideCanvas({
              : null;
            const previewUrl = previewCandidate?.thumbnailUrl ?? null;

+            // IMP-11 u4: active frame lookup — distinct axis from preview.
+            // preview is shown only when override differs from default; active is
+            // always defined as override-if-present-else-default. Used by u5 to
+            // compare the active frame's catalog min_height_px against zone height.
+            const activeFrameId = overrideFrameId ?? defaultFrameId;
+            const activeCandidate = activeFrameId
+              ? region?.frame_candidates?.find((c) => c.id === activeFrameId)
+              : undefined;
+
+            // IMP-11 u5: catalog min_height_px violation hint. height is already
+            // a fraction of SLIDE_H (1280x720 logical px coordinate space), so
+            // logical px = height * SLIDE_H. measuredSlideBody.h is intentionally
+            // not re-multiplied (double-apply would shrink the comparison value).
+            // Hint is pendingLayout-only; resize clamp (minSize=0.05) is unchanged.
+            const zoneHeightPx = isPendingLayout ? height * SLIDE_H : null;
+            const minHeightPx = activeCandidate?.minHeightPx ?? null;
+            const belowMinHeight =
+              isPendingLayout &&
+              minHeightPx != null &&
+              zoneHeightPx != null &&
+              zoneHeightPx < minHeightPx;
+
            return (
              <div
                key={zone.id}
@@ -695,6 +707,18 @@ export default function SlideCanvas({
                  </>
                )}

+                {/* IMP-11 u5: red border + 'min H Npx' badge when zone height
+                    is below the active frame's catalog min_height_px. Visual
+                    hint only, no clamp/resize behavior change. */}
+                {belowMinHeight && minHeightPx != null && (
+                  <>
+                    <div className="absolute inset-0 pointer-events-none border-2 border-red-500" />
+                    <span className="absolute bottom-1 right-1 text-[9px] font-black uppercase tracking-tighter px-1.5 py-0.5 rounded bg-red-500 text-white shadow pointer-events-none">
+                      min H {minHeightPx}px
+                    </span>
+                  </>
+                )}
+
                {/* zone 라벨 — 좌상단. 주 라벨 = section ids (S1, S1+S2),
                    부 라벨 = backend zone position (top, bottom, primary). */}
                <div className="absolute top-1 left-1 flex items-center gap-1 pointer-events-none">
@@ -527,6 +527,31 @@ export default function Home() {
              >
                {runMeta.status}
              </span>
+              {runMeta.filtered_section_ids.length > 0 && (
+                <details className="relative">
+                  <summary className="text-[10px] font-bold px-1.5 py-0.5 bg-amber-100 text-amber-700 rounded uppercase tracking-wider cursor-pointer list-none">
+                    Filtered: {runMeta.filtered_section_ids.length}
+                  </summary>
+                  <div className="absolute top-full mt-1 left-0 z-50 bg-white border border-slate-200 rounded shadow-lg p-3 w-96 max-h-96 overflow-y-auto">
+                    {runMeta.filtered_section_reasons.map((r, i) => (
+                      <div key={i} className="mb-2 pb-2 border-b border-slate-100 last:border-0 last:mb-0 last:pb-0 text-[11px]">
+                        <div className="font-mono text-slate-700">{r.section_ids.join(", ")}</div>
+                        <div className="text-slate-500">selection_state: <span className="font-mono">{r.selection_state}</span></div>
+                        {r.merge_type && <div className="text-slate-500">merge_type: <span className="font-mono">{r.merge_type}</span></div>}
+                        {r.template_id && <div className="text-slate-500">template_id: <span className="font-mono">{r.template_id}</span></div>}
+                        {r.v4_label && <div className="text-slate-500">v4_label: <span className="font-mono">{r.v4_label}</span></div>}
+                        {r.phase_z_status && <div className="text-slate-500">phase_z_status: <span className="font-mono">{r.phase_z_status}</span></div>}
+                        {r.score !== null && <div className="text-slate-500">score: <span className="font-mono">{r.score}</span></div>}
+                        {r.source && <div className="text-slate-500">source: <span className="font-mono">{r.source}</span></div>}
+                        {r.position && <div className="text-slate-500">position: <span className="font-mono">{r.position}</span></div>}
+                        <ul className="mt-1 list-disc list-inside text-slate-600">
+                          {r.filter_reasons.map((reason, j) => <li key={j} className="font-mono">{reason}</li>)}
+                        </ul>
+                      </div>
+                    ))}
+                  </div>
+                </details>
+              )}
            </>
          )}
        </div>
@@ -207,6 +207,22 @@ export async function exportSlidePlan(slidePlan: SlidePlan, userSelection: any):
 //   step20_slide_status.json       → 최종 상태 (PASS / RENDERED_WITH_VISUAL_REGRESSION / ...)
 // ─────────────────────────────────────────────────────────────────────────────

+// IMP-10 D-1 : verbatim mirror of step20_slide_status.json.data.filtered_section_reasons[]
+// schema (src/phase_z2_pipeline.py:2217-2278). `source` / `position` only present on
+// the override-uncovered additive variant. Strings rendered verbatim — no enum redefinition.
+export interface FilteredSectionReason {
+  section_ids: string[];
+  merge_type: string | null;
+  template_id: string | null;
+  v4_label: string | null;
+  phase_z_status: string | null;
+  score: number | null;
+  selection_state: string;
+  filter_reasons: string[];
+  source?: string;
+  position?: string | null;
+}
+
 export interface RunMeta {
  run_id: string;
  mdx_path: string;
@@ -214,6 +230,8 @@ export interface RunMeta {
  status: "PASS" | "RENDERED_WITH_VISUAL_REGRESSION" | "PARTIAL_COVERAGE" | "ABORTED" | string;
  visual_check_passed: boolean;
  full_mdx_coverage: boolean;
+  filtered_section_ids: string[];                       // step20 filtered_section_ids
+  filtered_section_reasons: FilteredSectionReason[];    // step20 filtered_section_reasons
  preview_url: string;     // /data/runs/{runId}/preview.png
  final_html_url: string;  // /data/runs/{runId}/final.html
  layout_candidates: string[]; // step07 layout_candidates list
@@ -393,6 +411,8 @@ export async function loadRun(runId: string): Promise<LoadRunResult> {
    status: slideStatus.data?.overall ?? "UNKNOWN",
    visual_check_passed: slideStatus.data?.visual_check_passed ?? false,
    full_mdx_coverage: slideStatus.data?.full_mdx_coverage ?? false,
+    filtered_section_ids: slideStatus.data?.filtered_section_ids ?? [],
+    filtered_section_reasons: slideStatus.data?.filtered_section_reasons ?? [],
    preview_url: `${base}/preview.png`,
    final_html_url: `${base}/final.html`,
    layout_candidates: layout.data?.layout_candidates ?? [],
@@ -507,6 +527,10 @@ export async function loadRun(runId: string): Promise<LoadRunResult> {
        // backend step09 의 catalog_registered (frame_contracts.yaml 등록 여부).
        // v4_all_judgments 에만 있음. v4_candidates fallback 시 undefined.
        catalogRegistered: c.catalog_registered,
+        // backend step09 의 min_height_px (frame_contracts.yaml visual_hints.min_height_px).
+        // logical 1280x720 px 좌표계. contract 미등록 또는 visual_hints 부재 시 undefined.
+        // v4_all_judgments 에만 있음. v4_candidates fallback 시 undefined (graceful).
+        minHeightPx: c.min_height_px ?? undefined,
      }));

    const displayStrategy = (
@@ -127,6 +127,10 @@ export interface FrameCandidate {
  /** backend frame_contracts.yaml 에 catalog 등록 여부. false 면 사용자가 override
   *  시도해도 Step 7-A 가 skip (render path 미연결). UI 회색 + "render path 미적용" 표시. */
  catalogRegistered?: boolean;
+  /** IMP-11 D-2 — frame contract visual_hints.min_height_px (logical 1280x720 px).
+   *  Source = templates/phase_z2/catalog/frame_contracts.yaml visual_hints.min_height_px.
+   *  Undefined when contract unregistered or visual_hints absent (frontend tolerates undefined). */
+  minHeightPx?: number;
 }

 // ─────────────────────────────────────────────────────────────────────────────
@@ -0,0 +1,189 @@
+"""IMP-13 build-time preview.png renderer for figma_to_html_agent/blocks/<frame_id> (u1-u6)."""
+from __future__ import annotations
+import argparse, hashlib, json, sys
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_BLOCKS_DIR = REPO_ROOT / "figma_to_html_agent" / "blocks"
+DEFAULT_MANIFEST = DEFAULT_BLOCKS_DIR / "_preview_manifest.json"
+
+
+@dataclass(frozen=True)
+class FrameRow:
+    frame_id: str
+    block_dir: Path
+    index_html_path: Path
+    preview_png_path: Path
+    has_index: bool
+    has_preview: bool
+
+
+def discover(blocks_dir: Path) -> List[FrameRow]:
+    if not blocks_dir.is_dir():
+        return []
+    rows: List[FrameRow] = []
+    for entry in sorted(blocks_dir.iterdir()):
+        if not entry.is_dir():
+            continue
+        idx, png = entry / "index.html", entry / "preview.png"
+        rows.append(FrameRow(entry.name, entry, idx, png, idx.is_file(), png.is_file()))
+    return rows
+
+
+def _build_driver() -> Any:
+    """Headless Chrome driver. Mirrors the run_overflow_check chromedriver-candidate + headless options pattern.
+    Inline per Stage 2 (no shared module). Per-frame window-size is set by the caller (u3), not here."""
+    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")
+    candidates = [REPO_ROOT / "chromedriver", REPO_ROOT / "chromedriver.exe"]
+    last_err: Exception | None = None
+    for path in candidates:
+        if path.is_file():
+            try:
+                return webdriver.Chrome(service=Service(str(path)), options=options)
+            except Exception as exc:  # noqa: BLE001 — propagate via aggregated error
+                last_err = exc
+    try:
+        return webdriver.Chrome(options=options)
+    except Exception as exc:  # noqa: BLE001
+        raise RuntimeError(f"selenium init failed: {last_err or exc}") from exc
+
+
+def render_one(driver: Any, row: FrameRow) -> tuple[int, int, Path]:
+    """Render row.index_html_path -> row.preview_png_path via WebElement screenshot. Returns (w, h, path) or raises.
+    Driver is injected (caller owns lifecycle). .slide bbox drives window-size; no hardcoded slide dimensions."""
+    if not row.has_index:
+        raise FileNotFoundError(f"missing index.html: {row.index_html_path}")
+    from selenium.webdriver.common.by import By
+    driver.get(row.index_html_path.resolve().as_uri())
+    driver.set_script_timeout(15)
+    driver.execute_async_script(
+        "const cb=arguments[arguments.length-1];"
+        "(document.fonts&&document.fonts.ready?document.fonts.ready:Promise.resolve()).then(()=>cb(true));"
+    )
+    rect = driver.execute_script(
+        "const el=document.querySelector('.slide');"
+        "if(!el)return null;"
+        "const r=el.getBoundingClientRect();"
+        "return [Math.round(r.width), Math.round(r.height)];"
+    )
+    if not rect:
+        raise RuntimeError(f".slide not found in {row.index_html_path}")
+    w, h = int(rect[0]), int(rect[1])
+    driver.set_window_size(w, h)
+    el = driver.find_element(By.CSS_SELECTOR, ".slide")
+    row.preview_png_path.write_bytes(el.screenshot_as_png)
+    return w, h, row.preview_png_path
+
+
+def _sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def is_unchanged(row: FrameRow, last_entry: Optional[Dict[str, Any]]) -> bool:
+    """Stale-detect short-circuit: True iff preview.png mtime >= index.html mtime AND sha256 matches last_entry.
+    Returns False when prior entry is absent, preview.png is missing, preview is older than index, or hash differs."""
+    if last_entry is None or not row.has_index or not row.has_preview:
+        return False
+    try:
+        idx_mtime = row.index_html_path.stat().st_mtime
+        png_mtime = row.preview_png_path.stat().st_mtime
+    except OSError:
+        return False
+    if png_mtime < idx_mtime:
+        return False
+    recorded = last_entry.get("index_sha256")
+    if not recorded:
+        return False
+    return _sha256_file(row.index_html_path) == recorded
+
+
+def categorize(rows: List[FrameRow]) -> Dict[str, List[FrameRow]]:
+    """Bucket discover() rows so nothing is silently skipped (Stage 2 guardrail).
+    renderable = has_index (eligible for render or skipped_unchanged decision in u6).
+    missing_index_html = no index.html (catalog gap; IMP-04 follow-up).
+    orphan = preview.png exists without index.html (subset of missing_index_html; stale artifact to flag).
+    Buckets are intentionally non-disjoint: orphan is a subset of missing_index_html,
+    matching the Stage 2 evidence counts (renderable=20, missing_index_html=13, orphan=1)."""
+    renderable = [r for r in rows if r.has_index]
+    missing = [r for r in rows if not r.has_index]
+    orphan = [r for r in missing if r.has_preview]
+    return {"renderable": renderable, "missing_index_html": missing, "orphan": orphan}
+
+
+def _load_manifest(path: Path) -> Dict[str, Any]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _render_entry(row: FrameRow, w: int, h: int) -> Dict[str, Any]:
+    return {"status": "rendered", "index_sha256": _sha256_file(row.index_html_path),
+            "index_mtime": row.index_html_path.stat().st_mtime,
+            "preview_mtime": row.preview_png_path.stat().st_mtime,
+            "viewport": {"w": w, "h": h}}
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="generate_frame_previews", description="IMP-13 build-time preview.png renderer.")
+    p.add_argument("--blocks-dir", type=Path, default=DEFAULT_BLOCKS_DIR)
+    p.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST)
+    p.add_argument("--dry-run", action="store_true")
+    args = p.parse_args(list(argv) if argv is not None else None)
+    rows = discover(args.blocks_dir)
+    if args.dry_run:
+        wi = sum(1 for r in rows if r.has_index)
+        wp = sum(1 for r in rows if r.has_preview)
+        print(f"discovered: total={len(rows)} with_index_html={wi} with_preview_png={wp}")
+        return 0
+    prev_frames = _load_manifest(args.manifest).get("frames") or {}
+    buckets = categorize(rows)
+    frames: Dict[str, Dict[str, Any]] = {}
+    counts = {"rendered": 0, "skipped_unchanged": 0, "error": 0}
+    driver = None
+    try:
+        for r in buckets["renderable"]:
+            last = prev_frames.get(r.frame_id) if isinstance(prev_frames, dict) else None
+            if is_unchanged(r, last):
+                frames[r.frame_id] = {**last, "status": "skipped_unchanged"}
+                counts["skipped_unchanged"] += 1
+                continue
+            if driver is None:
+                driver = _build_driver()
+            try:
+                w, h, _ = render_one(driver, r)
+                frames[r.frame_id] = _render_entry(r, w, h)
+                counts["rendered"] += 1
+            except Exception as exc:  # noqa: BLE001
+                frames[r.frame_id] = {"status": "error", "error": str(exc)}
+                counts["error"] += 1
+    finally:
+        if driver is not None:
+            try: driver.quit()
+            except Exception: pass
+    orphan_ids = {r.frame_id for r in buckets["orphan"]}
+    for r in buckets["missing_index_html"]:
+        frames[r.frame_id] = {"status": "orphan" if r.frame_id in orphan_ids else "missing_index_html", "has_preview": r.has_preview}
+    summary = {"total": len(rows), "renderable": len(buckets["renderable"]), "missing_index_html": len(buckets["missing_index_html"]), "orphan": len(buckets["orphan"]), **counts}
+    payload = {"schema": 1, "generated_at": datetime.now(timezone.utc).isoformat(), "blocks_dir": str(args.blocks_dir), "summary": summary, "frames": frames}
+    args.manifest.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+    print(f"coverage: total={summary['total']} renderable={summary['renderable']} rendered={counts['rendered']} skipped_unchanged={counts['skipped_unchanged']} missing_index_html={summary['missing_index_html']} orphan={summary['orphan']} error={counts['error']}")
+    return 1 if counts["error"] else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -701,12 +701,6 @@ def select_composition_units(candidates, allowed_statuses: set[str]) -> list[Com
        selected.append(c)
        covered.update(c.source_section_ids)

-    # 2026-05-14 — MDX 자연 순서 (section_id 오름차순) 로 재정렬.
-    # 사용자 룰 (CLAUDE.md "정보 계층: 위 → 아래") + 04-1/04-2 score 차이로 인한
-    # zone 거꾸로 배치 catch. score 는 viable selection 에만, position 은 MDX 순서.
-    # source_section_ids 첫 element 기준 lexicographic sort — "04-1" < "04-2" < "04-2.1" < "04-2.2".
-    selected.sort(key=lambda c: c.source_section_ids[0] if c.source_section_ids else "")
-
    return selected


@@ -7,20 +7,29 @@ A3 (zone_ratio_retry) 의 결과 (retry_trace) 를 받아 :
 본 module 은 ***분류 + 매핑까지만***. layout_adjust / frame_reselect / details_popup
 실행 X. retry_trace 에 `failure_classification` + `next_action_proposal` 두 필드 추가.

-**잠근 매핑** (사용자 잠금 — 2026-04-29) :
+**잠근 매핑** (사용자 잠금 — 2026-05-17, IMP-12 u3 cascade) :

-| failure_type              | next_proposed_action |
+| failure_type                            | next_proposed_action      |
 |---|---|
-| donor_slack_insufficient  | layout_adjust         |
-| no_donor_candidates       | layout_adjust         |
-| rerender_still_fails      | frame_reselect        |
-| not_attempted             | none                  |
+| donor_slack_insufficient                | cross_zone_redistribute    |
+| no_donor_candidates                     | cross_zone_redistribute    |
+| cross_zone_redistribute_insufficient    | glue_compression           |
+| glue_absorption_insufficient            | font_step_compression      |
+| font_step_insufficient                  | layout_adjust              |
+| rerender_still_fails                    | frame_reselect             |
+| not_attempted                           | none                       |

-**escalation 단계 hierarchy** (이번 기본 매핑이 따르는 원칙) :
+**escalation 단계 hierarchy** (Step 17 deterministic salvage cascade → layout/frame) :
 ```
-layout_adjust              (가장 가벼움 — zone 배치만 변경)
+cross_zone_redistribute    (fit_verifier.redistribute — role-height adjustment)
  ↓ 그래도 안 되면
-frame_reselect             (중간 — frame 자체 변경)
+glue_compression           (SPACING_GLUE envelope, frame-scoped)
+  ↓ 그래도 안 되면
+font_step_compression      (FONT_SIZE_STEPS, zone-scoped)
+  ↓ 그래도 안 되면
+layout_adjust              (zone topology 변경)
+  ↓ 그래도 안 되면
+frame_reselect             (V4 top-k 의 다른 frame)
  ↓ 그래도 안 되면
 details_popup_escalation   (가장 invasive — content popup, 마지막 resort)
 ```
@@ -53,26 +62,65 @@ FAILURE_TYPE_DESCRIPTIONS: dict[str, str] = {
        "redistribution 실행 + rerender 까지 했는데도 visual_check 실패. "
        "현재 frame/zone 조합이 content 와 맞지 않음"
    ),
+    "cross_zone_redistribute_insufficient": (
+        "cross_zone_redistribute salvage step failed — fit_verifier.redistribute "
+        "could not find a feasible role-height adjustment within the frame envelope"
+    ),
+    "glue_absorption_insufficient": (
+        "glue_compression salvage step failed — frame envelope cannot absorb "
+        "remaining overflow via SPACING_GLUE overrides (no global spacing shrink)"
+    ),
+    "font_step_insufficient": (
+        "font_step_compression salvage step failed — FONT_SIZE_STEPS exhausted "
+        "down to the floor without resolving overflow (or text_metrics missing)"
+    ),
+}
+
+
+# ─── §A4-1b salvage_steps[-1].action → failure_type table ──────────
+# u2 (IMP-12): _attempt_salvage_chain (u8) writes per-step records into
+# retry_trace["salvage_steps"] with {action, passed, failure_reason}. classifier
+# inspects salvage_steps[-1] so u3 can route 3 new types onto the cascade.
+
+SALVAGE_FAILURE_TYPE_BY_ACTION: dict[str, str] = {
+    "cross_zone_redistribute": "cross_zone_redistribute_insufficient",
+    "glue_compression":        "glue_absorption_insufficient",
+    "font_step_compression":   "font_step_insufficient",
 }


 # ─── §A4-2 next_action mapping (사용자 잠금) ──────────────────────

 NEXT_ACTION_BY_FAILURE: dict[str, str] = {
-    "donor_slack_insufficient": "layout_adjust",
-    "no_donor_candidates":      "layout_adjust",
-    "rerender_still_fails":     "frame_reselect",
-    "not_attempted":            "none",
+    "donor_slack_insufficient":             "cross_zone_redistribute",
+    "no_donor_candidates":                  "cross_zone_redistribute",
+    "cross_zone_redistribute_insufficient": "glue_compression",
+    "glue_absorption_insufficient":         "font_step_compression",
+    "font_step_insufficient":               "layout_adjust",
+    "rerender_still_fails":                 "frame_reselect",
+    "not_attempted":                        "none",
 }

 NEXT_ACTION_RATIONALE: dict[str, str] = {
    "donor_slack_insufficient": (
-        "현재 layout 안 redistribution 끝남 → 다른 layout topology 검토 "
-        "(layout_adjust). frame 자체는 아직 의심 대상 X"
+        "primary donor slack 한도 도달 → cross_zone_redistribute 로 sibling zone "
+        "전체 role-height 재분배 (fit_verifier.redistribute). layout 변경은 cascade 끝"
    ),
    "no_donor_candidates": (
-        "donor 자체 없거나 모두 막힘 → layout topology 부터 재구성하여 "
-        "sibling/space 다시 만들어 보는 게 우선 (layout_adjust). frame 변경은 그 다음"
+        "단일 donor 후보 없음 → cross_zone_redistribute 로 role-height 전체 "
+        "재할당 시도 (fit_verifier.redistribute). layout 변경은 cascade 끝"
+    ),
+    "cross_zone_redistribute_insufficient": (
+        "role-height 재분배도 frame envelope 못 맞춤 → glue_compression "
+        "(SPACING_GLUE frame-scoped) 으로 frame 내부 여백 축소"
+    ),
+    "glue_absorption_insufficient": (
+        "frame 여백 envelope 도 부족 → font_step_compression "
+        "(FONT_SIZE_STEPS zone-scoped) 으로 폰트 한 단계 축소"
+    ),
+    "font_step_insufficient": (
+        "deterministic salvage cascade 모두 소진 → layout_adjust 로 zone "
+        "topology 부터 재구성. frame_reselect 는 그 다음 단계"
    ),
    "rerender_still_fails": (
        "redistribution + rerender 까지 했는데도 visual fail → 현재 "
@@ -85,10 +133,19 @@ NEXT_ACTION_RATIONALE: dict[str, str] = {
 }

 # 본 매핑이 가리키는 next action 들의 *현재 코드* 구현 상태
+# IMP-12 u7 (2026-05-18): 3 cascade salvage actions registered as IMPLEMENTED.
+# plan/apply pairs live in phase_z2_retry (u4/u5/u6); pipeline orchestrator wiring
+# (_attempt_salvage_chain) lands in u8/u9. router-level mapping is decoupled from
+# orchestrator wiring on purpose so route_retry_failure → impl_status reflects
+# the deterministic surface availability, not whether a given pipeline run has
+# already invoked it.
 NEXT_ACTION_IMPLEMENTATION_STATUS: dict[str, str] = {
-    "layout_adjust":   "MISSING",
-    "frame_reselect":  "MISSING",
-    "none":            "n/a",
+    "cross_zone_redistribute": "IMPLEMENTED",  # u4 plan_cross_zone_redistribute + apply_cross_zone_redistribute_css
+    "glue_compression":        "IMPLEMENTED",  # u5 plan_glue_compression + apply_glue_compression_css
+    "font_step_compression":   "IMPLEMENTED",  # u6 plan_font_step_compression + apply_font_step_compression_css
+    "layout_adjust":           "MISSING",
+    "frame_reselect":          "MISSING",
+    "none":                    "n/a",
 }


@@ -106,6 +163,29 @@ def classify_retry_failure(retry_trace: dict) -> Optional[dict]:
    if retry_trace.get("retry_passed"):
        return None

+    # case 0.5 : salvage chain 자체 성공 — failure 없음 (u8/u9 wiring)
+    if retry_trace.get("salvage_passed"):
+        return None
+
+    # case 0.7 : salvage chain attempted and ended in a salvage-level failure.
+    # zone_ratio_retry 가 먼저 실패한 뒤 _attempt_salvage_chain 이 가동된 path —
+    # 마지막 salvage step 의 action 으로 failure_type 을 분류한다. u3 가 routing.
+    salvage_steps = retry_trace.get("salvage_steps") or []
+    if salvage_steps:
+        last = salvage_steps[-1] or {}
+        if not last.get("passed"):
+            action = (last.get("action") or "").lower()
+            ftype = SALVAGE_FAILURE_TYPE_BY_ACTION.get(action)
+            if ftype is not None:
+                reason = last.get("failure_reason") or ""
+                return {
+                    "failure_type": ftype,
+                    "classification_rule": (
+                        f"salvage_steps[-1].action == {action!r} "
+                        f"AND passed=False. raw failure_reason: {reason!r}"
+                    ),
+                }
+
    # case 1 : retry 시도 자체 안 됨 (router_active=False 또는 다른 action)
    if not retry_trace.get("retry_attempted"):
        return {
@@ -204,7 +284,7 @@ def route_retry_failure(failure_type: str) -> dict:
        "next_action_implementation_status": NEXT_ACTION_IMPLEMENTATION_STATUS.get(
            next_action, "unknown"
        ),
-        "mapping_source": "A4 NEXT_ACTION_BY_FAILURE (사용자 잠금 2026-04-29)",
+        "mapping_source": "A4 NEXT_ACTION_BY_FAILURE (사용자 잠금 2026-05-17, IMP-12 u3 cascade)",
    }


@@ -162,35 +162,55 @@ def plan_zone_ratio_retry(
            ),
        }

-    # A3 minimal : single primary donor (multi-donor 는 future)
-    primary_donor = donor_candidates[0]
-    if primary_donor["slack"] < target_added_px:
+    # IMP-12 u1 : multi-donor greedy aggregation (slack-desc 순서대로 합산)
+    aggregate_slack_available = sum(d["slack"] for d in donor_candidates)
+    if aggregate_slack_available < target_added_px:
        return {
            **base_plan,
            "feasible": False,
-            "donor_zone_position": primary_donor["position"],
-            "donor_max_slack": primary_donor["slack"],
+            "donor_zone_position": donor_candidates[0]["position"],
+            "donor_max_slack": donor_candidates[0]["slack"],
            "donor_reduced_px": 0,
+            "donors_used": [],
+            "aggregate_slack_used": 0,
+            "aggregate_slack_available": aggregate_slack_available,
            "zones_after": dict(zones_before),
            "failure_reason": (
-                f"primary donor '{primary_donor['position']}' slack {primary_donor['slack']}px "
-                f"< target_added_px {target_added_px}px (excess_y {target_excess_y} + "
-                f"safety_margin {safety_margin_px}). multi-donor aggregation is future axis."
+                f"primary donor '{donor_candidates[0]['position']}' slack "
+                f"{donor_candidates[0]['slack']}px (aggregate "
+                f"{aggregate_slack_available}px across {len(donor_candidates)} "
+                f"candidate(s)) < target_added_px {target_added_px}px "
+                f"(excess_y {target_excess_y} + safety_margin {safety_margin_px})."
            ),
        }

-    # feasible
+    # feasible — greedy aggregation: 각 donor 에서 필요한 만큼만 차감
    zones_after = dict(zones_before)
    zones_after[target_zone_position] = zones_before[target_zone_position] + target_added_px
-    zones_after[primary_donor["position"]] = (
-        zones_before[primary_donor["position"]] - target_added_px
-    )
+    donors_used: list[dict] = []
+    remaining = target_added_px
+    for donor in donor_candidates:
+        if remaining <= 0:
+            break
+        take = min(donor["slack"], remaining)
+        zones_after[donor["position"]] = zones_before[donor["position"]] - take
+        donors_used.append({
+            "position": donor["position"],
+            "reduced_px": take,
+            "slack_before": donor["slack"],
+            "slack_after": donor["slack"] - take,
+        })
+        remaining -= take

+    primary_donor = donors_used[0]
    return {
        **base_plan,
        "feasible": True,
        "donor_zone_position": primary_donor["position"],
-        "donor_reduced_px": target_added_px,
+        "donor_reduced_px": primary_donor["reduced_px"],
+        "donors_used": donors_used,
+        "aggregate_slack_used": target_added_px,
+        "aggregate_slack_available": aggregate_slack_available,
        "zones_after": zones_after,
    }

@@ -213,3 +233,177 @@ def apply_retry_to_layout_css(layout_css: dict, plan: dict, zones_data: list[dic
    new_layout_css["raw_zone_layout"] = (layout_css.get("raw_zone_layout") or {}).copy()
    new_layout_css["raw_zone_layout"]["retry_applied"] = True
    return new_layout_css
+
+
+# ──────────────────────────────────────
+# IMP-12 u4 : cross_zone_redistribute (Step 17 salvage cascade — stage 1)
+# Wraps src.fit_verifier.redistribute in the Step-17 plan signature so the
+# failure-router cascade (donor_slack_insufficient → cross_zone_redistribute)
+# can drive it deterministically. Plan-only — no rerender / no final.html
+# mutation. Side-effect-free (operates on deepcopy of fit_analysis).
+# ──────────────────────────────────────
+
+
+def plan_cross_zone_redistribute(
+    *,
+    fit_analysis,
+    containers: dict,
+    min_margin_px: float | None = None,
+) -> dict:
+    """Cross-zone (intra-zone role-to-role) redistribute plan.
+
+    Plan-only — no rerender / no final.html mutation. Side-effect-free
+    (operates on deepcopy of fit_analysis).
+    """
+    from copy import deepcopy
+    from src.fit_verifier import redistribute as _fv_redistribute
+
+    role_heights_before = {
+        role: float(rf.allocated_px) for role, rf in (fit_analysis.roles or {}).items()
+    }
+    base_plan = {
+        "action": "cross_zone_redistribute",
+        "role_heights_before": role_heights_before,
+    }
+    if not role_heights_before:
+        return {**base_plan, "feasible": False, "role_heights_after": {},
+                "can_redistribute": False,
+                "failure_reason": "no roles in fit_analysis — cannot redistribute."}
+
+    result = _fv_redistribute(deepcopy(fit_analysis), containers, min_margin_px=min_margin_px)
+    redistribution = dict(result.redistribution or {})
+    can_redistribute = bool(result.can_redistribute)
+
+    if not can_redistribute or not redistribution:
+        return {
+            **base_plan,
+            "feasible": False,
+            "role_heights_after": redistribution or dict(role_heights_before),
+            "can_redistribute": can_redistribute,
+            "failure_reason": (
+                "fit_verifier.redistribute can_redistribute=False — single-role zone(s) "
+                "or surplus insufficient to cover deficit within envelope."
+            ),
+        }
+    return {**base_plan, "feasible": True, "role_heights_after": redistribution,
+            "can_redistribute": True}
+
+
+def apply_cross_zone_redistribute_css(plan: dict) -> str:
+    """Emit scoped role-height CSS overrides — [data-role="<role>"] only.
+
+    Honors feedback_phase_z_spacing_direction: no :root / body / .slide / .zone selectors.
+    """
+    if not plan.get("feasible"):
+        return ""
+    role_heights_after = plan.get("role_heights_after") or {}
+    role_heights_before = plan.get("role_heights_before") or {}
+    rules: list[str] = []
+    for role, new_height in role_heights_after.items():
+        before = role_heights_before.get(role)
+        if before is None or abs(float(before) - float(new_height)) < 0.5:
+            continue
+        new_h_int = int(round(float(new_height)))
+        rules.append(
+            f'[data-role="{role}"] {{ height: {new_h_int}px; min-height: {new_h_int}px; }}'
+        )
+    return "\n".join(rules)
+
+
+# IMP-12 u5 : glue_compression — Step 17 salvage cascade (stage 2).
+# Wraps space_allocator.compute_glue_css_overrides in the Step-17 plan signature.
+# Frame-scoped: overrides emitted only under [data-zone-position="<pos>"]
+# (feedback_phase_z_spacing_direction — no :root/body/.slide/.zone mutation).
+
+
+def plan_glue_compression(
+    *, excess_px: float, block_count: int, zone_position: str,
+) -> dict:
+    """Glue compression plan (frame-scoped). feasible only when envelope absorbs excess."""
+    from src.space_allocator import (
+        calculate_glue_absorption, compute_glue_css_overrides,
+    )
+    base = {"action": "glue_compression", "zone_position": zone_position,
+            "excess_px": float(excess_px), "block_count": int(block_count)}
+    if excess_px <= 0:
+        return {**base, "feasible": False, "overrides": {}, "absorption_max_px": 0.0,
+                "failure_reason": "excess_px <= 0 — no compression needed."}
+    absorption_max = float(calculate_glue_absorption(block_count))
+    overrides = compute_glue_css_overrides(excess_px, block_count) or {}
+    if excess_px > absorption_max:
+        return {**base, "feasible": False, "overrides": overrides,
+                "absorption_max_px": absorption_max,
+                "failure_reason": (
+                    f"glue envelope insufficient — excess_px {excess_px:.1f} > "
+                    f"max absorption {absorption_max:.1f}px "
+                    f"(block_count={block_count}, SPACING_GLUE shrink budget)."
+                )}
+    return {**base, "feasible": True, "overrides": overrides,
+            "absorption_max_px": absorption_max}
+
+
+def apply_glue_compression_css(plan: dict) -> str:
+    """Emit zone-scoped glue CSS — wrapped in [data-zone-position="<pos>"] only."""
+    if not plan.get("feasible"):
+        return ""
+    zone_position = plan.get("zone_position")
+    overrides = plan.get("overrides") or {}
+    if not zone_position or not overrides:
+        return ""
+    var_lines = "\n".join(f"  {k}: {v};" for k, v in overrides.items())
+    return f'[data-zone-position="{zone_position}"] {{\n{var_lines}\n}}'
+
+
+# IMP-12 u6 : font_step_compression — Step 17 salvage cascade (stage 3).
+# Wraps space_allocator.find_fitting_font_size in the Step-17 plan signature.
+# Zone-scoped: only [data-zone-position="<pos>"] (no :root/body/.slide/.zone).
+
+
+def plan_font_step_compression(
+    *, current_font_px: float, excess_after_glue_px: float,
+    available_lines: int, chars_per_line: int, zone_position: str,
+) -> dict:
+    """Font-step compression plan (zone-scoped). feasible only when FONT_SIZE_STEPS
+    contains a size whose line-height savings cover excess_after_glue_px. Missing
+    text_metrics yields feasible=False (cascade routes onward to layout_adjust)."""
+    from src.space_allocator import FONT_SIZE_STEPS, find_fitting_font_size
+    floor = float(FONT_SIZE_STEPS[-1])
+    base = {"action": "font_step_compression", "zone_position": zone_position,
+            "current_font_px": float(current_font_px),
+            "excess_after_glue_px": float(excess_after_glue_px),
+            "available_lines": int(available_lines or 0),
+            "chars_per_line": int(chars_per_line or 0),
+            "font_floor_px": floor}
+    if excess_after_glue_px <= 0:
+        return {**base, "feasible": False, "target_font_px": None,
+                "failure_reason": "excess_after_glue_px <= 0 — no font compression needed."}
+    if not available_lines or available_lines <= 0 or not chars_per_line or chars_per_line <= 0:
+        return {**base, "feasible": False, "target_font_px": None,
+                "failure_reason": "text_metrics missing — available_lines/chars_per_line required."}
+    if current_font_px <= floor:
+        return {**base, "feasible": False, "target_font_px": None,
+                "failure_reason": (
+                    f"current_font_px {current_font_px:.1f} already at FONT_SIZE_STEPS floor {floor:.1f}px.")}
+    target = find_fitting_font_size(
+        current_font_px=float(current_font_px),
+        excess_after_glue_px=float(excess_after_glue_px),
+        available_lines=int(available_lines), chars_per_line=int(chars_per_line))
+    if target is None:
+        return {**base, "feasible": False, "target_font_px": None,
+                "failure_reason": (
+                    f"font_step floor — {floor:.1f}px cannot absorb "
+                    f"excess_after_glue_px={excess_after_glue_px:.1f}px "
+                    f"(available_lines={available_lines}, FONT_SIZE_STEPS exhausted).")}
+    return {**base, "feasible": True, "target_font_px": float(target)}
+
+
+def apply_font_step_compression_css(plan: dict) -> str:
+    """Emit zone-scoped font-size CSS — [data-zone-position="<pos>"] only."""
+    if not plan.get("feasible"):
+        return ""
+    zone_position = plan.get("zone_position")
+    target_font_px = plan.get("target_font_px")
+    if not zone_position or target_font_px is None:
+        return ""
+    return (f'[data-zone-position="{zone_position}"] {{\n'
+            f"  font-size: {float(target_font_px):.1f}px;\n}}")
@@ -56,7 +56,7 @@ ACTION_RATIONALE: dict[str, str] = {
        "위 매핑 모두 미적용 — 마지막 fallback (현재 코드는 sys.exit 으로 abort)",
 }

-# 각 action 의 *현재 코드* 구현 상태 (2026-04-29 기준)
+# 각 action 의 *현재 코드* 구현 상태 (2026-04-29 기준; IMP-12 u7 cascade 2026-05-18)
 # A2 단계에서 이 매핑이 *어디까지 자동 처리되고 어디서 막히는지* trace 확보용
 ACTION_IMPLEMENTATION_STATUS: dict[str, str] = {
    "zone_ratio_retry":          "IMPLEMENTED",  # A3 (2026-04-29) phase_z2_retry.plan_zone_ratio_retry + pipeline orchestration
@@ -65,6 +65,12 @@ ACTION_IMPLEMENTATION_STATUS: dict[str, str] = {
    "frame_reselect":            "PARTIAL",      # IMP-05 pre-render rank-2/3 fallback implemented; post-render rerender trace-only
    "adapter_needed":            "PARTIAL",      # composition v0.1.1 의 mapper FitError catch
    "abort":                     "IMPLEMENTED",  # sys.exit(1) — pipeline 의 현재 default
+    # IMP-12 u7 (2026-05-18): cascade-only salvage actions (no ACTION_BY_CATEGORY row;
+    # surfaced via NEXT_ACTION_BY_FAILURE in phase_z2_failure_router). plan/apply pairs
+    # implemented in phase_z2_retry; pipeline orchestrator wiring lands in u8/u9.
+    "cross_zone_redistribute":   "IMPLEMENTED",  # u4 phase_z2_retry.plan_cross_zone_redistribute + apply_cross_zone_redistribute_css
+    "glue_compression":          "IMPLEMENTED",  # u5 phase_z2_retry.plan_glue_compression + apply_glue_compression_css
+    "font_step_compression":     "IMPLEMENTED",  # u6 phase_z2_retry.plan_font_step_compression + apply_font_step_compression_css
 }


@@ -1,11 +1,23 @@
 <!-- Phase Z-2 MVP-1.5b — single slide + Type B layout (top/bottom zones).
     원래 Phase Z 설계 복귀: MDX 1 = slide 1, layout preset = zone 분할, frame-derived block ⊂ zone. -->
 <!DOCTYPE html>
-<html lang="ko">
+<html lang="ko"{% if embedded_mode == "embedded" %} class="embedded"{% endif %}>
 <head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=1280">
  <title>{{ slide_title }}</title>
+  {% if embedded_mode == "auto" %}
+  <script>
+  (function(){
+    try {
+      var params = new URLSearchParams(window.location.search);
+      if (params.get('embedded') === '1' || window.self !== window.top) {
+        document.documentElement.classList.add('embedded');
+      }
+    } catch (e) {}
+  })();
+  </script>
+  {% endif %}
  <style>
    /* ── existing tokens (inlined) ── */
    {{ token_css | safe }}
@@ -20,6 +32,19 @@
      padding: 20px 0;
    }

+    /* ── IMP-14 A-4: embedded mode reset (iframe consumer) ──
+         standalone-only body centering/min-height/padding undone so the .slide
+         (1280×720) sits at origin without vertical shift or clipping. */
+    html.embedded body {
+      background: transparent;
+      display: block;
+      min-height: 0;
+      padding: 0;
+    }
+    html.embedded .slide {
+      box-shadow: none;
+    }
+
    /* ── 16:9 슬라이드 (single, 1280×720) ── */
    .slide {
      width: 1280px; height: 720px;
@@ -0,0 +1,43 @@
+input:
+  layout_preset: grid-2x2
+  zones_data:
+  - position: top-left
+    template_id: MOCK_top-left
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: top-right
+    template_id: MOCK_top-right
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: bottom-left
+    template_id: MOCK_bottom-left
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: bottom-right
+    template_id: MOCK_bottom-right
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  override_zone_geometries: null
+expected_layout_css:
+  areas: '"top-left top-right" "bottom-left bottom-right"'
+  cols: 583px 583px
+  rows: 286px 285px
+  heights_px:
+  - 286
+  - 285
+  widths_px:
+  - 583
+  - 583
+  ratios:
+  - 0.489
+  - 0.487
+  width_ratios:
+  - 0.494
+  - 0.494
+  computation: 2d_dynamic_aggregated
+  dynamic_rows: true
+  dynamic_cols: true
@@ -0,0 +1,63 @@
+input:
+  layout_preset: grid-2x2
+  zones_data:
+  - position: top-left
+    template_id: MOCK_top-left
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: top-right
+    template_id: MOCK_top-right
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: bottom-left
+    template_id: MOCK_bottom-left
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: bottom-right
+    template_id: MOCK_bottom-right
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  override_zone_geometries:
+    top-left:
+      x: 0
+      y: 0
+      w: 0.55
+      h: 0.4
+    top-right:
+      x: 0.55
+      y: 0
+      w: 0.45
+      h: 0.4
+    bottom-left:
+      x: 0
+      y: 0.4
+      w: 0.55
+      h: 0.6
+    bottom-right:
+      x: 0.55
+      y: 0.4
+      w: 0.45
+      h: 0.6
+expected_layout_css:
+  areas: '"top-left top-right" "bottom-left bottom-right"'
+  cols: 641px 525px
+  rows: 228px 343px
+  heights_px:
+  - 228
+  - 343
+  widths_px:
+  - 641
+  - 525
+  ratios:
+  - 0.4
+  - 0.6
+  width_ratios:
+  - 0.55
+  - 0.45
+  computation: user_override_geometry
+  dynamic_rows: true
+  dynamic_cols: true
@@ -0,0 +1,31 @@
+input:
+  layout_preset: horizontal-2
+  zones_data:
+  - position: top
+    template_id: MOCK_top
+    content_weight:
+      score: 0.5
+    min_height_px: 200
+  - position: bottom
+    template_id: MOCK_bottom
+    content_weight:
+      score: 0.5
+    min_height_px: 200
+  override_zone_geometries: null
+expected_layout_css:
+  areas: '"top" "bottom"'
+  cols: 1fr
+  rows: 286px 285px
+  heights_px:
+  - 286
+  - 285
+  widths_px:
+  - 1180
+  ratios:
+  - 0.489
+  - 0.487
+  width_ratios:
+  - 1.0
+  computation: min_height_first + content_weight_distribution
+  dynamic_rows: true
+  dynamic_cols: false
@@ -0,0 +1,41 @@
+input:
+  layout_preset: horizontal-2
+  zones_data:
+  - position: top
+    template_id: MOCK_top
+    content_weight:
+      score: 0.5
+    min_height_px: 200
+  - position: bottom
+    template_id: MOCK_bottom
+    content_weight:
+      score: 0.5
+    min_height_px: 200
+  override_zone_geometries:
+    top:
+      x: 0
+      y: 0
+      w: 1.0
+      h: 0.3
+    bottom:
+      x: 0
+      y: 0.3
+      w: 1.0
+      h: 0.7
+expected_layout_css:
+  areas: '"top" "bottom"'
+  cols: 1fr
+  rows: 176px 410px
+  heights_px:
+  - 176
+  - 410
+  widths_px:
+  - 1180
+  ratios:
+  - 0.3
+  - 0.7
+  width_ratios:
+  - 1.0
+  computation: user_override_geometry
+  dynamic_rows: true
+  dynamic_cols: false
@@ -0,0 +1,31 @@
+input:
+  layout_preset: horizontal-2
+  zones_data:
+  - position: top
+    template_id: MOCK_top
+    content_weight:
+      score: 0.8
+    min_height_px: 200
+  - position: bottom
+    template_id: MOCK_bottom
+    content_weight:
+      score: 0.2
+    min_height_px: 150
+  override_zone_geometries: null
+expected_layout_css:
+  areas: '"top" "bottom"'
+  cols: 1fr
+  rows: 377px 194px
+  heights_px:
+  - 377
+  - 194
+  widths_px:
+  - 1180
+  ratios:
+  - 0.644
+  - 0.332
+  width_ratios:
+  - 1.0
+  computation: min_height_first + content_weight_distribution
+  dynamic_rows: true
+  dynamic_cols: false
@@ -0,0 +1,38 @@
+input:
+  layout_preset: left-1-right-2
+  zones_data:
+  - position: left
+    template_id: MOCK_left
+    content_weight:
+      score: 0.5
+    min_height_px: 200
+  - position: right-top
+    template_id: MOCK_right-top
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: right-bottom
+    template_id: MOCK_right-bottom
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  override_zone_geometries: null
+expected_layout_css:
+  areas: '"left right-top" "left right-bottom"'
+  cols: 777px 389px
+  rows: 286px 285px
+  heights_px:
+  - 286
+  - 285
+  widths_px:
+  - 777
+  - 389
+  ratios:
+  - 0.489
+  - 0.487
+  width_ratios:
+  - 0.658
+  - 0.33
+  computation: 2d_dynamic_aggregated
+  dynamic_rows: true
+  dynamic_cols: true
@@ -0,0 +1,53 @@
+input:
+  layout_preset: left-1-right-2
+  zones_data:
+  - position: left
+    template_id: MOCK_left
+    content_weight:
+      score: 0.5
+    min_height_px: 200
+  - position: right-top
+    template_id: MOCK_right-top
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: right-bottom
+    template_id: MOCK_right-bottom
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  override_zone_geometries:
+    left:
+      x: 0
+      y: 0
+      w: 0.4
+      h: 1.0
+    right-top:
+      x: 0.4
+      y: 0
+      w: 0.6
+      h: 0.5
+    right-bottom:
+      x: 0.4
+      y: 0.5
+      w: 0.6
+      h: 0.5
+expected_layout_css:
+  areas: '"left right-top" "left right-bottom"'
+  cols: 466px 700px
+  rows: 286px 285px
+  heights_px:
+  - 286
+  - 285
+  widths_px:
+  - 466
+  - 700
+  ratios:
+  - 0.5
+  - 0.5
+  width_ratios:
+  - 0.4
+  - 0.6
+  computation: user_override_geometry
+  dynamic_rows: true
+  dynamic_cols: true
@@ -0,0 +1,38 @@
+input:
+  layout_preset: left-2-right-1
+  zones_data:
+  - position: left-top
+    template_id: MOCK_left-top
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: left-bottom
+    template_id: MOCK_left-bottom
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: right
+    template_id: MOCK_right
+    content_weight:
+      score: 0.5
+    min_height_px: 200
+  override_zone_geometries: null
+expected_layout_css:
+  areas: '"left-top right" "left-bottom right"'
+  cols: 389px 777px
+  rows: 286px 285px
+  heights_px:
+  - 286
+  - 285
+  widths_px:
+  - 389
+  - 777
+  ratios:
+  - 0.489
+  - 0.487
+  width_ratios:
+  - 0.33
+  - 0.658
+  computation: 2d_dynamic_aggregated
+  dynamic_rows: true
+  dynamic_cols: true
@@ -0,0 +1,53 @@
+input:
+  layout_preset: left-2-right-1
+  zones_data:
+  - position: left-top
+    template_id: MOCK_left-top
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: left-bottom
+    template_id: MOCK_left-bottom
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: right
+    template_id: MOCK_right
+    content_weight:
+      score: 0.5
+    min_height_px: 200
+  override_zone_geometries:
+    left-top:
+      x: 0
+      y: 0
+      w: 0.35
+      h: 0.6
+    left-bottom:
+      x: 0
+      y: 0.6
+      w: 0.35
+      h: 0.4
+    right:
+      x: 0.35
+      y: 0
+      w: 0.65
+      h: 1.0
+expected_layout_css:
+  areas: '"left-top right" "left-bottom right"'
+  cols: 408px 758px
+  rows: 343px 228px
+  heights_px:
+  - 343
+  - 228
+  widths_px:
+  - 408
+  - 758
+  ratios:
+  - 0.6
+  - 0.4
+  width_ratios:
+  - 0.35
+  - 0.65
+  computation: user_override_geometry
+  dynamic_rows: true
+  dynamic_cols: true
@@ -0,0 +1,38 @@
+input:
+  layout_preset: top-1-bottom-2
+  zones_data:
+  - position: top
+    template_id: MOCK_top
+    content_weight:
+      score: 0.5
+    min_height_px: 200
+  - position: bottom-left
+    template_id: MOCK_bottom-left
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: bottom-right
+    template_id: MOCK_bottom-right
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  override_zone_geometries: null
+expected_layout_css:
+  areas: '"top top" "bottom-left bottom-right"'
+  cols: 583px 583px
+  rows: 314px 257px
+  heights_px:
+  - 314
+  - 257
+  widths_px:
+  - 583
+  - 583
+  ratios:
+  - 0.537
+  - 0.439
+  width_ratios:
+  - 0.494
+  - 0.494
+  computation: 2d_dynamic_aggregated
+  dynamic_rows: true
+  dynamic_cols: true
@@ -0,0 +1,53 @@
+input:
+  layout_preset: top-1-bottom-2
+  zones_data:
+  - position: top
+    template_id: MOCK_top
+    content_weight:
+      score: 0.5
+    min_height_px: 200
+  - position: bottom-left
+    template_id: MOCK_bottom-left
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: bottom-right
+    template_id: MOCK_bottom-right
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  override_zone_geometries:
+    top:
+      x: 0
+      y: 0
+      w: 1.0
+      h: 0.3
+    bottom-left:
+      x: 0
+      y: 0.3
+      w: 0.5
+      h: 0.7
+    bottom-right:
+      x: 0.5
+      y: 0.3
+      w: 0.5
+      h: 0.7
+expected_layout_css:
+  areas: '"top top" "bottom-left bottom-right"'
+  cols: 583px 583px
+  rows: 171px 400px
+  heights_px:
+  - 171
+  - 400
+  widths_px:
+  - 583
+  - 583
+  ratios:
+  - 0.3
+  - 0.7
+  width_ratios:
+  - 0.5
+  - 0.5
+  computation: user_override_geometry
+  dynamic_rows: true
+  dynamic_cols: true
@@ -0,0 +1,38 @@
+input:
+  layout_preset: top-2-bottom-1
+  zones_data:
+  - position: top-left
+    template_id: MOCK_top-left
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: top-right
+    template_id: MOCK_top-right
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: bottom
+    template_id: MOCK_bottom
+    content_weight:
+      score: 0.5
+    min_height_px: 200
+  override_zone_geometries: null
+expected_layout_css:
+  areas: '"top-left top-right" "bottom bottom"'
+  cols: 583px 583px
+  rows: 257px 314px
+  heights_px:
+  - 257
+  - 314
+  widths_px:
+  - 583
+  - 583
+  ratios:
+  - 0.439
+  - 0.537
+  width_ratios:
+  - 0.494
+  - 0.494
+  computation: 2d_dynamic_aggregated
+  dynamic_rows: true
+  dynamic_cols: true
@@ -0,0 +1,53 @@
+input:
+  layout_preset: top-2-bottom-1
+  zones_data:
+  - position: top-left
+    template_id: MOCK_top-left
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: top-right
+    template_id: MOCK_top-right
+    content_weight:
+      score: 0.25
+    min_height_px: 200
+  - position: bottom
+    template_id: MOCK_bottom
+    content_weight:
+      score: 0.5
+    min_height_px: 200
+  override_zone_geometries:
+    top-left:
+      x: 0
+      y: 0
+      w: 0.6
+      h: 0.4
+    top-right:
+      x: 0.6
+      y: 0
+      w: 0.4
+      h: 0.4
+    bottom:
+      x: 0
+      y: 0.4
+      w: 1.0
+      h: 0.6
+expected_layout_css:
+  areas: '"top-left top-right" "bottom bottom"'
+  cols: 700px 466px
+  rows: 228px 343px
+  heights_px:
+  - 228
+  - 343
+  widths_px:
+  - 700
+  - 466
+  ratios:
+  - 0.4
+  - 0.6
+  width_ratios:
+  - 0.6
+  - 0.4
+  computation: user_override_geometry
+  dynamic_rows: true
+  dynamic_cols: true
@@ -0,0 +1,31 @@
+input:
+  layout_preset: vertical-2
+  zones_data:
+  - position: left
+    template_id: MOCK_left
+    content_weight:
+      score: 0.5
+    min_height_px: 200
+  - position: right
+    template_id: MOCK_right
+    content_weight:
+      score: 0.5
+    min_height_px: 200
+  override_zone_geometries: null
+expected_layout_css:
+  areas: '"left right"'
+  cols: 583px 583px
+  rows: 1fr
+  heights_px:
+  - 585
+  widths_px:
+  - 583
+  - 583
+  ratios:
+  - 1.0
+  width_ratios:
+  - 0.494
+  - 0.494
+  computation: content_weight_distribution_cols
+  dynamic_rows: false
+  dynamic_cols: true
@@ -0,0 +1,41 @@
+input:
+  layout_preset: vertical-2
+  zones_data:
+  - position: left
+    template_id: MOCK_left
+    content_weight:
+      score: 0.5
+    min_height_px: 200
+  - position: right
+    template_id: MOCK_right
+    content_weight:
+      score: 0.5
+    min_height_px: 200
+  override_zone_geometries:
+    left:
+      x: 0
+      y: 0
+      w: 0.4
+      h: 1.0
+    right:
+      x: 0.4
+      y: 0
+      w: 0.6
+      h: 1.0
+expected_layout_css:
+  areas: '"left right"'
+  cols: 40.0fr 60.0fr
+  rows: 1fr
+  heights_px:
+  - 585
+  widths_px:
+  - 466
+  - 700
+  ratios:
+  - 1.0
+  width_ratios:
+  - 0.4
+  - 0.6
+  computation: user_override_geometry
+  dynamic_rows: false
+  dynamic_cols: true
@@ -0,0 +1,31 @@
+input:
+  layout_preset: vertical-2
+  zones_data:
+  - position: left
+    template_id: MOCK_left
+    content_weight:
+      score: 0.7
+    min_height_px: 200
+  - position: right
+    template_id: MOCK_right
+    content_weight:
+      score: 0.3
+    min_height_px: 200
+  override_zone_geometries: null
+expected_layout_css:
+  areas: '"left right"'
+  cols: 816px 350px
+  rows: 1fr
+  heights_px:
+  - 585
+  widths_px:
+  - 816
+  - 350
+  ratios:
+  - 1.0
+  width_ratios:
+  - 0.692
+  - 0.297
+  computation: content_weight_distribution_cols
+  dynamic_rows: false
+  dynamic_cols: true
@@ -0,0 +1,24 @@
+case_id: grid-2x2_dynamic_2d
+description: |
+  grid-2x2 (2x2 topology) is promoted to 2-D dynamic in IMP-09 PR 2.
+  Row-axis retry MUST be skipped by the gate with the
+  "dynamic_cols (2-D topology)" reason.
+input_layout_css:
+  areas: '"top-left top-right" "bottom-left bottom-right"'
+  cols: 583px 583px
+  rows: 286px 285px
+  heights_px: [286, 285]
+  widths_px: [583, 583]
+  ratios: [0.489, 0.487]
+  width_ratios: [0.494, 0.494]
+  dynamic_rows: true
+  dynamic_cols: true
+router_decision:
+  router_active: true
+  proposed_actions_summary: [zone_ratio_retry]
+expected_gate:
+  retry_attempted: false
+  retry_skipped_reason_contains:
+    - "dynamic_cols"
+    - "2-D"
+    - "IMP-09"
@@ -0,0 +1,24 @@
+case_id: horizontal2_dynamic_rows
+description: |
+  horizontal-2 layout with dynamic_rows=True must pass the IMP-09 retry
+  gate. The base trace should record retry_attempted=True (legacy
+  plan/rerender path continues). retry_skipped_reason MUST NOT contain
+  either of the IMP-09 gate skip strings.
+input_layout_css:
+  areas: '"top" "bottom"'
+  cols: 1fr
+  rows: 333px 238px
+  heights_px: [333, 238]
+  widths_px: [1180]
+  ratios: [0.569, 0.407]
+  width_ratios: [1.0]
+  dynamic_rows: true
+  dynamic_cols: false
+router_decision:
+  router_active: true
+  proposed_actions_summary: [zone_ratio_retry]
+expected_gate:
+  retry_attempted: true
+  retry_skipped_reason_excludes:
+    - "dynamic_cols"
+    - "fr_default_from_preset"
@@ -0,0 +1,24 @@
+case_id: left-1-right-2_dynamic_2d
+description: |
+  left-1-right-2 (side-T-left topology) is promoted to 2-D dynamic in
+  IMP-09 PR 2. Row-axis retry MUST be skipped by the gate with the
+  "dynamic_cols (2-D topology)" reason.
+input_layout_css:
+  areas: '"left right-top" "left right-bottom"'
+  cols: 777px 389px
+  rows: 286px 285px
+  heights_px: [286, 285]
+  widths_px: [777, 389]
+  ratios: [0.489, 0.487]
+  width_ratios: [0.658, 0.33]
+  dynamic_rows: true
+  dynamic_cols: true
+router_decision:
+  router_active: true
+  proposed_actions_summary: [zone_ratio_retry]
+expected_gate:
+  retry_attempted: false
+  retry_skipped_reason_contains:
+    - "dynamic_cols"
+    - "2-D"
+    - "IMP-09"
@@ -0,0 +1,24 @@
+case_id: left-2-right-1_dynamic_2d
+description: |
+  left-2-right-1 (side-T-right topology) is promoted to 2-D dynamic in
+  IMP-09 PR 2. Row-axis retry MUST be skipped by the gate with the
+  "dynamic_cols (2-D topology)" reason.
+input_layout_css:
+  areas: '"left-top right" "left-bottom right"'
+  cols: 389px 777px
+  rows: 286px 285px
+  heights_px: [286, 285]
+  widths_px: [389, 777]
+  ratios: [0.489, 0.487]
+  width_ratios: [0.33, 0.658]
+  dynamic_rows: true
+  dynamic_cols: true
+router_decision:
+  router_active: true
+  proposed_actions_summary: [zone_ratio_retry]
+expected_gate:
+  retry_attempted: false
+  retry_skipped_reason_contains:
+    - "dynamic_cols"
+    - "2-D"
+    - "IMP-09"
@@ -0,0 +1,23 @@
+case_id: single_fr_default
+description: |
+  Any layout that fell through to fr_default_from_preset (single,
+  T-shape, 2x2 in PR 1) has neither dynamic_rows nor dynamic_cols.
+  Row-axis retry is a no-op and must be skipped by the IMP-09 gate
+  with a fr_default_from_preset skip reason.
+input_layout_css:
+  areas: '"top top" "bottom-left bottom-right"'
+  cols: 1fr 1fr
+  rows: 1fr 1fr
+  heights_px: [285, 286]
+  widths_px: [583, 583]
+  ratios: [0.487, 0.489]
+  width_ratios: [0.494, 0.494]
+  dynamic_rows: false
+  dynamic_cols: false
+router_decision:
+  router_active: true
+  proposed_actions_summary: [zone_ratio_retry]
+expected_gate:
+  retry_attempted: false
+  retry_skipped_reason_contains:
+    - "fr_default_from_preset"
@@ -0,0 +1,26 @@
+case_id: top-1-bottom-2_dynamic_2d
+description: |
+  top-1-bottom-2 (T topology) is promoted to 2-D dynamic in IMP-09
+  PR 2 (dynamic_rows=True, dynamic_cols=True). Row-axis retry MUST be
+  skipped by the IMP-09 gate with the "dynamic_cols (2-D topology)"
+  skip reason, because row-only redistribution cannot reconcile both
+  axes simultaneously.
+input_layout_css:
+  areas: '"top top" "bottom-left bottom-right"'
+  cols: 583px 583px
+  rows: 314px 257px
+  heights_px: [314, 257]
+  widths_px: [583, 583]
+  ratios: [0.537, 0.439]
+  width_ratios: [0.494, 0.494]
+  dynamic_rows: true
+  dynamic_cols: true
+router_decision:
+  router_active: true
+  proposed_actions_summary: [zone_ratio_retry]
+expected_gate:
+  retry_attempted: false
+  retry_skipped_reason_contains:
+    - "dynamic_cols"
+    - "2-D"
+    - "IMP-09"
@@ -0,0 +1,24 @@
+case_id: top-2-bottom-1_dynamic_2d
+description: |
+  top-2-bottom-1 (inverted-T topology) is promoted to 2-D dynamic in
+  IMP-09 PR 2. Row-axis retry MUST be skipped by the gate with the
+  "dynamic_cols (2-D topology)" reason.
+input_layout_css:
+  areas: '"top-left top-right" "bottom bottom"'
+  cols: 583px 583px
+  rows: 257px 314px
+  heights_px: [257, 314]
+  widths_px: [583, 583]
+  ratios: [0.439, 0.537]
+  width_ratios: [0.494, 0.494]
+  dynamic_rows: true
+  dynamic_cols: true
+router_decision:
+  router_active: true
+  proposed_actions_summary: [zone_ratio_retry]
+expected_gate:
+  retry_attempted: false
+  retry_skipped_reason_contains:
+    - "dynamic_cols"
+    - "2-D"
+    - "IMP-09"
@@ -0,0 +1,24 @@
+case_id: vertical2_dynamic_cols
+description: |
+  vertical-2 layout with dynamic_cols=True must be skipped by the
+  IMP-09 retry gate before plan/rerender, because the existing
+  apply_retry_to_layout_css mutates only row-axis fields and would
+  produce a misleading trace if it ran on a column-dynamic layout.
+input_layout_css:
+  areas: '"left right"'
+  cols: 583px 583px
+  rows: 1fr
+  heights_px: [585]
+  widths_px: [583, 583]
+  ratios: [1.0]
+  width_ratios: [0.494, 0.494]
+  dynamic_rows: false
+  dynamic_cols: true
+router_decision:
+  router_active: true
+  proposed_actions_summary: [zone_ratio_retry]
+expected_gate:
+  retry_attempted: false
+  retry_skipped_reason_contains:
+    - "dynamic_cols"
+    - "IMP-09"
@@ -0,0 +1,158 @@
+"""IMP-09 PR 1 — build_layout_css contract tests.
+
+Verifies horizontal-2 byte-identity for the legacy grid strings
+(areas / cols / rows) and that every return path now carries the new
+length-locked col-axis keys (widths_px / width_ratios / dynamic_cols).
+"""
+from __future__ import annotations
+
+import pytest
+
+from src.phase_z2_pipeline import (
+    GRID_GAP,
+    SLIDE_BODY_HEIGHT,
+    SLIDE_BODY_WIDTH,
+    build_layout_css,
+)
+
+
+def _zone(position: str, score: float, min_h: int = 100) -> dict:
+    return {
+        "position": position,
+        "template_id": f"MOCK_{position}",
+        "content_weight": {"score": score},
+        "min_height_px": min_h,
+    }
+
+
+# ────────────────────── new-key contract ──────────────────────
+
+
+NEW_KEYS = {"widths_px", "width_ratios", "dynamic_cols"}
+
+
+def test_all_presets_carry_new_col_axis_keys():
+    """Every PR 1 return path must include widths_px / width_ratios /
+    dynamic_cols, and heights_px / widths_px must be length-locked to
+    the catalog grid (R rows, C cols)."""
+    cases = [
+        ("single", [_zone("primary", 1.0)]),
+        ("horizontal-2", [_zone("top", 0.6), _zone("bottom", 0.4)]),
+        ("vertical-2", [_zone("left", 0.5), _zone("right", 0.5)]),
+        ("top-1-bottom-2", [
+            _zone("top", 0.5),
+            _zone("bottom-left", 0.25),
+            _zone("bottom-right", 0.25),
+        ]),
+        ("grid-2x2", [
+            _zone("top-left", 0.25),
+            _zone("top-right", 0.25),
+            _zone("bottom-left", 0.25),
+            _zone("bottom-right", 0.25),
+        ]),
+    ]
+    for preset, zones in cases:
+        result = build_layout_css(preset, zones)
+        missing = NEW_KEYS - set(result)
+        assert not missing, f"{preset} missing new keys: {missing}"
+        # heights_px / widths_px never empty in PR 1 (length-locked).
+        assert len(result["heights_px"]) > 0, f"{preset} empty heights_px"
+        assert len(result["widths_px"]) > 0, f"{preset} empty widths_px"
+
+
+# ────────────────────── horizontal-2 byte-identity ──────────────────────
+
+
+def test_horizontal_2_grid_strings_match_legacy():
+    zones = [_zone("top", 0.6), _zone("bottom", 0.4)]
+    result = build_layout_css("horizontal-2", zones)
+
+    # Legacy contract: areas / cols / rows strings preserved.
+    assert result["areas"] == '"top" "bottom"'
+    assert result["cols"] == "1fr"
+    assert result["rows"].count("px") == 2
+
+    # heights_px sum to body height; ratios consistent.
+    assert sum(result["heights_px"]) == SLIDE_BODY_HEIGHT - GRID_GAP
+    assert result["dynamic_rows"] is True
+    assert result["dynamic_cols"] is False
+
+    # New col-axis defaults: full body width, ratio 1.0.
+    assert result["widths_px"] == [SLIDE_BODY_WIDTH]
+    assert result["width_ratios"] == [1.0]
+
+
+def test_horizontal_2_override_preserves_rows():
+    zones = [_zone("top", 0.6), _zone("bottom", 0.4)]
+    override = {
+        "top": {"x": 0, "y": 0, "w": 1.0, "h": 0.3},
+        "bottom": {"x": 0, "y": 0.3, "w": 1.0, "h": 0.7},
+    }
+    result = build_layout_css(
+        "horizontal-2", zones, override_zone_geometries=override
+    )
+    assert result["computation"] == "user_override_geometry"
+    assert result["dynamic_rows"] is True
+    assert result["dynamic_cols"] is False
+    assert result["heights_px"][0] < result["heights_px"][1]
+    assert result["widths_px"] == [SLIDE_BODY_WIDTH]
+    # Override ratio target.
+    assert result["ratios"] == [0.3, 0.7]
+
+
+# ────────────────────── vertical-2 new dynamic ──────────────────────
+
+
+def test_vertical_2_normal_produces_dynamic_cols():
+    zones = [_zone("left", 0.7), _zone("right", 0.3)]
+    result = build_layout_css("vertical-2", zones)
+    assert result["dynamic_rows"] is False
+    assert result["dynamic_cols"] is True
+    # cols string is px-based (no fr).
+    assert "fr" not in result["cols"]
+    assert result["cols"].count("px") == 2
+    # Heights span full body in a single row.
+    assert result["heights_px"] == [SLIDE_BODY_HEIGHT]
+    # Widths reflect 70/30 weight split.
+    assert result["widths_px"][0] > result["widths_px"][1]
+
+
+def test_vertical_2_override_keeps_fr_cols_legacy():
+    """PR 1 v-2 override path keeps legacy fr-string cols but now
+    populates widths_px in pixels for downstream consumers."""
+    zones = [_zone("left", 0.5), _zone("right", 0.5)]
+    override = {
+        "left": {"x": 0, "y": 0, "w": 0.4, "h": 1.0},
+        "right": {"x": 0.4, "y": 0, "w": 0.6, "h": 1.0},
+    }
+    result = build_layout_css(
+        "vertical-2", zones, override_zone_geometries=override
+    )
+    assert result["computation"] == "user_override_geometry"
+    assert "fr" in result["cols"]
+    assert result["dynamic_cols"] is True
+    assert result["dynamic_rows"] is False
+    # widths_px now populated.
+    assert len(result["widths_px"]) == 2
+    assert sum(result["widths_px"]) == SLIDE_BODY_WIDTH - GRID_GAP
+    assert result["width_ratios"] == [0.4, 0.6]
+
+
+# ────────────────────── 2-D dynamic dispatch (PR 2) ──────────────────────
+
+
+def test_top_1_bottom_2_dynamic_2d_populates_geometry():
+    """T-shape (top-1-bottom-2) is dispatched through the 2-D dynamic
+    builder in PR 2: heights_px / widths_px length-locked to grid
+    R=2, C=2 with both dynamic flags True."""
+    zones = [
+        _zone("top", 0.5),
+        _zone("bottom-left", 0.25),
+        _zone("bottom-right", 0.25),
+    ]
+    result = build_layout_css("top-1-bottom-2", zones)
+    assert result["computation"] == "2d_dynamic_aggregated"
+    assert result["dynamic_rows"] is True
+    assert result["dynamic_cols"] is True
+    assert len(result["heights_px"]) == 2   # R rows
+    assert len(result["widths_px"]) == 2    # C cols
@@ -0,0 +1,101 @@
+"""IMP-09 PR 1 — _compute_per_zone_geometry tests (1-D paths).
+
+Verifies the unified per-zone geometry aggregator on horizontal-2 and
+vertical-2 (the two 1-D presets active in PR 1). 2-D spanning zone
+cases (T / 2x2) are exercised in PR 2.
+
+The helper aggregates grid-track sizes into per-zone dimensions and
+must produce length-locked outputs:
+  - layout_css["heights_px"] length == R (parsed css_areas rows)
+  - layout_css["widths_px"]  length == C (parsed css_areas cols)
+"""
+from __future__ import annotations
+
+import pytest
+
+from src.phase_z2_pipeline import (
+    GRID_GAP,
+    SLIDE_BODY_HEIGHT,
+    SLIDE_BODY_WIDTH,
+    _compute_per_zone_geometry,
+    build_layout_css,
+)
+
+
+def _zone(position: str, score: float) -> dict:
+    return {
+        "position": position,
+        "template_id": f"MOCK_{position}",
+        "content_weight": {"score": score},
+        "min_height_px": 100,
+    }
+
+
+def test_horizontal_2_per_zone_widths_match_slide_body():
+    zones = [_zone("top", 0.6), _zone("bottom", 0.4)]
+    layout_css = build_layout_css("horizontal-2", zones)
+    debug_zones = [{"position": "top"}, {"position": "bottom"}]
+    per_zone = _compute_per_zone_geometry(layout_css, debug_zones, GRID_GAP)
+
+    # Both zones share the single column => width == SLIDE_BODY_WIDTH.
+    assert per_zone[0]["zone_width_px"] == SLIDE_BODY_WIDTH
+    assert per_zone[1]["zone_width_px"] == SLIDE_BODY_WIDTH
+    # Heights mirror layout_css.heights_px.
+    assert per_zone[0]["zone_height_px"] == layout_css["heights_px"][0]
+    assert per_zone[1]["zone_height_px"] == layout_css["heights_px"][1]
+
+
+def test_vertical_2_per_zone_heights_match_slide_body():
+    zones = [_zone("left", 0.5), _zone("right", 0.5)]
+    layout_css = build_layout_css("vertical-2", zones)
+    debug_zones = [{"position": "left"}, {"position": "right"}]
+    per_zone = _compute_per_zone_geometry(layout_css, debug_zones, GRID_GAP)
+
+    # Both zones share the single row => height == SLIDE_BODY_HEIGHT.
+    assert per_zone[0]["zone_height_px"] == SLIDE_BODY_HEIGHT
+    assert per_zone[1]["zone_height_px"] == SLIDE_BODY_HEIGHT
+    # Widths mirror layout_css.widths_px.
+    assert per_zone[0]["zone_width_px"] == layout_css["widths_px"][0]
+    assert per_zone[1]["zone_width_px"] == layout_css["widths_px"][1]
+
+
+def test_heights_px_length_mismatch_raises():
+    layout_css = {
+        "areas": '"top" "bottom"',
+        "heights_px": [300],          # wrong length, expected 2
+        "widths_px": [SLIDE_BODY_WIDTH],
+    }
+    with pytest.raises(ValueError, match="heights_px length"):
+        _compute_per_zone_geometry(
+            layout_css, [{"position": "top"}], GRID_GAP
+        )
+
+
+def test_widths_px_length_mismatch_raises():
+    layout_css = {
+        "areas": '"left right"',
+        "heights_px": [SLIDE_BODY_HEIGHT],
+        "widths_px": [600],            # wrong length, expected 2
+    }
+    with pytest.raises(ValueError, match="widths_px length"):
+        _compute_per_zone_geometry(
+            layout_css, [{"position": "left"}], GRID_GAP
+        )
+
+
+def test_unknown_position_raises():
+    zones = [_zone("top", 0.5), _zone("bottom", 0.5)]
+    layout_css = build_layout_css("horizontal-2", zones)
+    debug_zones = [{"position": "ghost"}]
+    with pytest.raises(ValueError, match="not present in css_areas"):
+        _compute_per_zone_geometry(layout_css, debug_zones, GRID_GAP)
+
+
+def test_fr_default_single_returns_full_body():
+    # 'single' is the fr_default sink in PR 1; widths_px / heights_px
+    # must still be populated (length 1 each).
+    layout_css = build_layout_css("single", [_zone("primary", 1.0)])
+    debug_zones = [{"position": "primary"}]
+    per_zone = _compute_per_zone_geometry(layout_css, debug_zones, GRID_GAP)
+    assert per_zone[0]["zone_height_px"] == SLIDE_BODY_HEIGHT
+    assert per_zone[0]["zone_width_px"] == SLIDE_BODY_WIDTH
@@ -0,0 +1,76 @@
+"""IMP-09 PR 1 — compute_zone_layout_cols tests.
+
+Column-axis weight-only solver. Mirrors compute_zone_layout for rows.
+No min_width_px contract exists in frame_contracts.yaml (verified
+during Stage 2), so column distribution is purely content_weight.
+"""
+from __future__ import annotations
+
+from src.phase_z2_pipeline import (
+    GRID_GAP,
+    SLIDE_BODY_WIDTH,
+    compute_zone_layout_cols,
+)
+
+
+def _zone(position: str, score: float) -> dict:
+    return {
+        "position": position,
+        "template_id": f"MOCK_{position}",
+        "content_weight": {"score": score},
+    }
+
+
+def test_empty_zones_returns_empty_result():
+    result = compute_zone_layout_cols([])
+    assert result["widths_px"] == []
+    assert result["width_ratios"] == []
+
+
+def test_two_equal_zones_split_evenly():
+    zones = [_zone("left", 0.5), _zone("right", 0.5)]
+    result = compute_zone_layout_cols(zones)
+    available = SLIDE_BODY_WIDTH - GRID_GAP  # one gap between two zones
+    assert sum(result["widths_px"]) == available
+    assert result["widths_px"][0] == result["widths_px"][1]
+    assert result["computation"] == "content_weight_distribution_cols"
+
+
+def test_asymmetric_weights_distribute_by_ratio():
+    zones = [_zone("left", 0.8), _zone("right", 0.2)]
+    result = compute_zone_layout_cols(zones)
+    available = SLIDE_BODY_WIDTH - GRID_GAP
+    assert sum(result["widths_px"]) == available
+    # left should be ~4x right
+    assert result["widths_px"][0] > result["widths_px"][1] * 3
+
+
+def test_zero_weight_guard_equal_split():
+    zones = [_zone("left", 0.0), _zone("right", 0.0)]
+    result = compute_zone_layout_cols(zones)
+    available = SLIDE_BODY_WIDTH - GRID_GAP
+    assert sum(result["widths_px"]) == available
+    assert result["widths_px"][0] == result["widths_px"][1]
+    # weight_shares fallback to equal share.
+    assert result["weight_shares"] == [0.5, 0.5]
+
+
+def test_integer_rounding_absorbed_by_last_zone():
+    # Three zones with weights that don't divide evenly.
+    zones = [
+        _zone("a", 0.333333),
+        _zone("b", 0.333333),
+        _zone("c", 0.333334),
+    ]
+    result = compute_zone_layout_cols(zones)
+    available = SLIDE_BODY_WIDTH - 2 * GRID_GAP
+    assert sum(result["widths_px"]) == available
+
+
+def test_width_ratios_match_total_width():
+    zones = [_zone("left", 0.6), _zone("right", 0.4)]
+    result = compute_zone_layout_cols(zones)
+    # width_ratios should be widths_px / SLIDE_BODY_WIDTH (not / available)
+    assert abs(
+        result["width_ratios"][0] - result["widths_px"][0] / SLIDE_BODY_WIDTH
+    ) < 1e-3
@@ -0,0 +1,100 @@
+"""IMP-09 PR 1 — fixture-driven regression checks.
+
+Loads the YAML snapshots under tests/phase_z2/fixtures/ and exercises
+build_layout_css + _attempt_zone_ratio_retry against them. Any drift
+in IMP-09 output forces a fixture refresh, which is the lock surface
+called out in Stage 3 round 4 §5.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+import yaml
+
+from src.phase_z2_pipeline import _attempt_zone_ratio_retry, build_layout_css
+
+
+FIXTURES_DIR = Path(__file__).parent / "fixtures"
+
+
+def _load_yaml(path: Path) -> dict:
+    with path.open(encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+# ──────────────────────── build_layout_css fixtures ────────────────────────
+
+
+_BUILD_DIR = FIXTURES_DIR / "build_layout_css"
+_BUILD_FIXTURES = sorted(_BUILD_DIR.glob("*.yaml")) if _BUILD_DIR.exists() else []
+
+
+@pytest.mark.parametrize(
+    "fixture_path",
+    _BUILD_FIXTURES,
+    ids=[p.stem for p in _BUILD_FIXTURES],
+)
+def test_build_layout_css_matches_fixture(fixture_path: Path):
+    payload = _load_yaml(fixture_path)
+    inp = payload["input"]
+    expected = payload["expected_layout_css"]
+
+    result = build_layout_css(
+        inp["layout_preset"],
+        inp["zones_data"],
+        override_zone_geometries=inp.get("override_zone_geometries"),
+    )
+    # raw_zone_layout is intentionally not snapshotted (contains
+    # solver internals); compare the rest.
+    actual = {k: v for k, v in result.items() if k != "raw_zone_layout"}
+    assert actual == expected, (
+        f"layout_css drift in fixture {fixture_path.name}:\n"
+        f"  expected={expected}\n  actual={actual}"
+    )
+
+
+# ────────────────────────── retry_gate fixtures ──────────────────────────
+
+
+_RETRY_DIR = FIXTURES_DIR / "retry_gate"
+_RETRY_FIXTURES = sorted(_RETRY_DIR.glob("*.yaml")) if _RETRY_DIR.exists() else []
+
+
+@pytest.mark.parametrize(
+    "fixture_path",
+    _RETRY_FIXTURES,
+    ids=[p.stem for p in _RETRY_FIXTURES],
+)
+def test_retry_gate_matches_fixture(fixture_path: Path, tmp_path: Path):
+    payload = _load_yaml(fixture_path)
+    layout_css = payload["input_layout_css"]
+    router_decision = payload["router_decision"]
+    expected = payload["expected_gate"]
+
+    trace = _attempt_zone_ratio_retry(
+        run_dir=tmp_path,
+        out_path=tmp_path / "final.html",
+        slide_title="fixture",
+        slide_footer=None,
+        zones_data=[],
+        debug_zones=[],
+        layout_preset="fixture",
+        layout_css=layout_css,
+        overflow={},
+        fit_classification={},
+        router_decision=router_decision,
+        gap_px=14,
+    )
+
+    assert trace["retry_attempted"] == expected["retry_attempted"]
+    skip_reason = trace.get("retry_skipped_reason")
+    for needle in expected.get("retry_skipped_reason_contains", []):
+        assert skip_reason is not None and needle in skip_reason, (
+            f"expected {needle!r} in retry_skipped_reason, got {skip_reason!r}"
+        )
+    for forbidden in expected.get("retry_skipped_reason_excludes", []):
+        if skip_reason is not None:
+            assert forbidden not in skip_reason, (
+                f"forbidden {forbidden!r} found in retry_skipped_reason {skip_reason!r}"
+            )
@@ -0,0 +1,71 @@
+"""IMP-09 PR 1 — _parse_css_areas strict validation tests.
+
+Covers the four ValueError cases declared in the Stage 3 round 4 lock
+(plan §2-D): empty input, no quoted rows, empty row tokens, and
+non-rectangular grids. Also exercises positive parsing on all 8
+catalog presets so any future catalog drift in row/col counts is
+caught here.
+"""
+from __future__ import annotations
+
+import pytest
+
+from src.phase_z2_pipeline import _parse_css_areas
+
+
+def test_parse_empty_string_raises():
+    with pytest.raises(ValueError, match="no quoted row strings"):
+        _parse_css_areas("")
+
+
+def test_parse_no_quotes_raises():
+    with pytest.raises(ValueError, match="no quoted row strings"):
+        _parse_css_areas("top top bottom-left bottom-right")
+
+
+def test_parse_empty_row_raises():
+    # Whitespace-only quoted row -> tokens list is empty.
+    with pytest.raises(ValueError, match="empty row"):
+        _parse_css_areas('"   "')
+
+
+def test_parse_non_rectangular_raises():
+    # First row has 1 token, second row has 2 tokens.
+    with pytest.raises(ValueError, match="non-rectangular"):
+        _parse_css_areas('"top" "bottom-left bottom-right"')
+
+
+def test_parse_single_zone():
+    rows, seen = _parse_css_areas('"primary"')
+    assert rows == [["primary"]]
+    assert seen == ["primary"]
+
+
+def test_parse_horizontal_2():
+    rows, seen = _parse_css_areas('"top" "bottom"')
+    assert rows == [["top"], ["bottom"]]
+    assert seen == ["top", "bottom"]
+
+
+def test_parse_vertical_2():
+    rows, seen = _parse_css_areas('"left right"')
+    assert rows == [["left", "right"]]
+    assert seen == ["left", "right"]
+
+
+def test_parse_top_1_bottom_2_span():
+    rows, seen = _parse_css_areas('"top top" "bottom-left bottom-right"')
+    assert rows == [["top", "top"], ["bottom-left", "bottom-right"]]
+    # 'top' should appear once in seen even though it occupies two cells.
+    assert seen == ["top", "bottom-left", "bottom-right"]
+
+
+def test_parse_grid_2x2_four_zones():
+    rows, seen = _parse_css_areas(
+        '"top-left top-right" "bottom-left bottom-right"'
+    )
+    assert rows == [
+        ["top-left", "top-right"],
+        ["bottom-left", "bottom-right"],
+    ]
+    assert seen == ["top-left", "top-right", "bottom-left", "bottom-right"]
@@ -0,0 +1,49 @@
+"""IMP-09 PR 1 — _parse_fr_string tests.
+
+Catalog presets only use `1fr` / `1fr 1fr` specs (verified
+templates/phase_z2/layouts/layouts.yaml). The helper must reject
+non-fr tokens and round to integer pixel sizes summing to `total`.
+"""
+from __future__ import annotations
+
+import pytest
+
+from src.phase_z2_pipeline import _parse_fr_string
+
+
+def test_single_fr_returns_full_total():
+    assert _parse_fr_string("1fr", 585) == [585]
+
+
+def test_two_equal_fr_splits_evenly():
+    result = _parse_fr_string("1fr 1fr", 1180)
+    assert result == [590, 590]
+    assert sum(result) == 1180
+
+
+def test_unequal_fr_distributes_by_ratio():
+    result = _parse_fr_string("2fr 1fr", 300)
+    assert sum(result) == 300
+    assert result[0] > result[1]
+
+
+def test_rounding_absorbed_by_last_track():
+    # 1fr 1fr 1fr / total=100 -> 33,33,33 + diff 1 absorbed by last.
+    result = _parse_fr_string("1fr 1fr 1fr", 100)
+    assert sum(result) == 100
+    assert result == [33, 33, 34]
+
+
+def test_non_fr_token_raises():
+    with pytest.raises(ValueError, match="non-fr token"):
+        _parse_fr_string("200px 1fr", 1000)
+
+
+def test_empty_spec_raises():
+    with pytest.raises(ValueError, match="empty spec"):
+        _parse_fr_string("", 1000)
+
+
+def test_zero_fr_raises():
+    with pytest.raises(ValueError, match="total fr"):
+        _parse_fr_string("0fr 0fr", 1000)
@@ -0,0 +1,89 @@
+"""IMP-12 u11 — plan_cross_zone_redistribute tests.
+
+Stage 2 contract (unit u11):
+  - multi-role zone feasible (deficit role + surplus role in the same zone)
+  - single-role zone infeasible reason (no peer to donate surplus)
+
+u4 wraps fit_verifier.redistribute() in the Step-17 plan signature; feasibility
+depends on whether deficit roles can be covered by surplus roles within the
+same container.zone group (see src/fit_verifier.py:496-590). The plan exposes
+role_heights_before / role_heights_after and surfaces the
+'can_redistribute=False — single-role zone(s)' substring when redistribution
+is impossible. The apply helper must scope output to [data-role=...] only
+(feedback_phase_z_spacing_direction — no :root / body / .slide / .zone).
+"""
+from __future__ import annotations
+
+from src.fit_verifier import FitAnalysis, RoleFit
+from src.phase_z2_retry import (
+    apply_cross_zone_redistribute_css,
+    plan_cross_zone_redistribute,
+)
+
+
+def _fit(roles: dict[str, tuple[float, float]]) -> FitAnalysis:
+    """roles dict = {role: (allocated_px, shortfall_px)}.
+
+    Sign convention matches fit_verifier.redistribute: shortfall_px > 0 = deficit,
+    shortfall_px < 0 = surplus (usable = abs(shortfall) - min_margin_px).
+    """
+    return FitAnalysis(
+        roles={
+            name: RoleFit(role=name, allocated_px=alloc, shortfall_px=short)
+            for name, (alloc, short) in roles.items()
+        }
+    )
+
+
+def test_multi_role_zone_feasible():
+    """Two roles in the same zone — deficit covered by surplus → feasible."""
+    fit = _fit({"top": (200.0, 30.0), "bottom_l": (300.0, -50.0)})
+    containers = {
+        "top": {"zone": "slide_body", "height_px": 200},
+        "bottom_l": {"zone": "slide_body", "height_px": 300},
+    }
+    plan = plan_cross_zone_redistribute(
+        fit_analysis=fit, containers=containers, min_margin_px=10.0,
+    )
+    assert plan["action"] == "cross_zone_redistribute"
+    assert plan["feasible"] is True
+    assert plan["can_redistribute"] is True
+    assert plan["role_heights_before"] == {"top": 200.0, "bottom_l": 300.0}
+    after = plan["role_heights_after"]
+    # deficit (30) shifts top up, surplus (50-margin=40) shifts bottom_l down by 30.
+    assert after["top"] > 200.0
+    assert after["bottom_l"] < 300.0
+    assert abs((after["top"] - 200.0) - (300.0 - after["bottom_l"])) < 1.0
+    css = apply_cross_zone_redistribute_css(plan)
+    assert '[data-role="top"]' in css
+    assert '[data-role="bottom_l"]' in css
+    # Scope lock — no global rules emitted.
+    for forbidden in (":root", "body", ".slide", ".zone"):
+        assert forbidden not in css
+
+
+def test_single_role_zone_infeasible_reason():
+    """Lone role in a zone has no peer to donate surplus → infeasible."""
+    fit = _fit({"top": (200.0, 30.0)})
+    containers = {"top": {"zone": "slide_body", "height_px": 200}}
+    plan = plan_cross_zone_redistribute(
+        fit_analysis=fit, containers=containers, min_margin_px=10.0,
+    )
+    assert plan["feasible"] is False
+    assert plan["can_redistribute"] is False
+    reason = plan["failure_reason"]
+    assert "single-role zone" in reason
+    assert "can_redistribute=False" in reason
+    # apply emits nothing when infeasible.
+    assert apply_cross_zone_redistribute_css(plan) == ""
+
+
+def test_empty_fit_analysis_infeasible():
+    """No roles at all → defensive infeasible (cannot redistribute nothing)."""
+    plan = plan_cross_zone_redistribute(
+        fit_analysis=FitAnalysis(roles={}), containers={}, min_margin_px=10.0,
+    )
+    assert plan["feasible"] is False
+    assert plan["role_heights_before"] == {}
+    assert "no roles" in plan["failure_reason"]
+    assert apply_cross_zone_redistribute_css(plan) == ""
@@ -0,0 +1,119 @@
+"""IMP-12 u14 — failure_router cascade tests.
+
+Stage 2 contract (unit u14):
+  - donor_slack_insufficient → cross_zone_redistribute (impl=IMPLEMENTED)
+  - 3 new failure types (cross_zone_redistribute_insufficient,
+    glue_absorption_insufficient, font_step_insufficient) all route to
+    expected next actions per the locked NEXT_ACTION_BY_FAILURE table
+  - rerender_still_fails preserved → frame_reselect
+
+u2 (classifier) inspects retry_trace["salvage_steps"][-1] for the 3 new
+salvage failure types via SALVAGE_FAILURE_TYPE_BY_ACTION; u3 wires those
+failure types onto the deterministic cascade in NEXT_ACTION_BY_FAILURE.
+u7 records the cascade actions as IMPLEMENTED in NEXT_ACTION_IMPLEMENTATION_STATUS.
+"""
+from __future__ import annotations
+
+from src.phase_z2_failure_router import (
+    NEXT_ACTION_BY_FAILURE,
+    NEXT_ACTION_IMPLEMENTATION_STATUS,
+    classify_retry_failure,
+    enrich_retry_trace_with_failure_classification,
+    route_retry_failure,
+)
+
+
+def test_donor_slack_insufficient_routes_to_cross_zone_redistribute_implemented():
+    """Stage 1 root cause — primary donor slack insufficient classifies as
+    donor_slack_insufficient and routes onto the deterministic salvage cascade
+    starting with cross_zone_redistribute (IMPLEMENTED per u7)."""
+    trace = {
+        "retry_attempted": True,
+        "retry_passed": False,
+        "plan": {
+            "feasible": False,
+            "failure_reason": (
+                "primary donor 'bottom' slack 15px (aggregate 25px from 2 donor(s)) "
+                "< target_added_px 70px"
+            ),
+        },
+    }
+    fc = classify_retry_failure(trace)
+    assert fc is not None
+    assert fc["failure_type"] == "donor_slack_insufficient"
+
+    nr = route_retry_failure("donor_slack_insufficient")
+    assert nr["next_proposed_action"] == "cross_zone_redistribute"
+    assert nr["next_action_implementation_status"] == "IMPLEMENTED"
+
+    # enrichment composes both fields onto the trace
+    enrich_retry_trace_with_failure_classification(trace)
+    assert trace["failure_classification"]["failure_type"] == "donor_slack_insufficient"
+    assert trace["next_action_proposal"]["next_proposed_action"] == "cross_zone_redistribute"
+
+
+def test_no_donor_candidates_routes_to_cross_zone_redistribute_implemented():
+    """no_donor_candidates is the second cascade entry — also onto
+    cross_zone_redistribute per the locked mapping."""
+    trace = {
+        "retry_attempted": True,
+        "retry_passed": False,
+        "plan": {"feasible": False, "failure_reason": "no donor candidates"},
+    }
+    fc = classify_retry_failure(trace)
+    assert fc["failure_type"] == "no_donor_candidates"
+    nr = route_retry_failure("no_donor_candidates")
+    assert nr["next_proposed_action"] == "cross_zone_redistribute"
+    assert nr["next_action_implementation_status"] == "IMPLEMENTED"
+
+
+def test_three_new_salvage_failure_types_route_to_expected_cascade_actions():
+    """u2 classifier inspects salvage_steps[-1]. u3 routes the 3 new failure
+    types through the deterministic cascade: cross_zone → glue → font_step →
+    layout_adjust. Verifies the locked NEXT_ACTION_BY_FAILURE table directly
+    and via the classifier path."""
+    # Direct mapping (u3 lock)
+    assert NEXT_ACTION_BY_FAILURE["cross_zone_redistribute_insufficient"] == "glue_compression"
+    assert NEXT_ACTION_BY_FAILURE["glue_absorption_insufficient"] == "font_step_compression"
+    assert NEXT_ACTION_BY_FAILURE["font_step_insufficient"] == "layout_adjust"
+
+    # Implementation status (u7): 2 cascade entries IMPLEMENTED, layout_adjust MISSING
+    assert NEXT_ACTION_IMPLEMENTATION_STATUS["glue_compression"] == "IMPLEMENTED"
+    assert NEXT_ACTION_IMPLEMENTATION_STATUS["font_step_compression"] == "IMPLEMENTED"
+    assert NEXT_ACTION_IMPLEMENTATION_STATUS["layout_adjust"] == "MISSING"
+
+    # Classifier path via salvage_steps[-1].action → failure_type → next action
+    cases = [
+        ("cross_zone_redistribute", "cross_zone_redistribute_insufficient", "glue_compression"),
+        ("glue_compression",        "glue_absorption_insufficient",         "font_step_compression"),
+        ("font_step_compression",   "font_step_insufficient",               "layout_adjust"),
+    ]
+    for action, expected_ftype, expected_next in cases:
+        trace = {
+            "retry_attempted": True,
+            "retry_passed": False,
+            "salvage_passed": False,
+            "salvage_steps": [
+                {"action": action, "passed": False, "failure_reason": "salvage failed"}
+            ],
+        }
+        fc = classify_retry_failure(trace)
+        assert fc is not None, f"classifier returned None for action={action}"
+        assert fc["failure_type"] == expected_ftype
+        nr = route_retry_failure(fc["failure_type"])
+        assert nr["next_proposed_action"] == expected_next
+
+
+def test_rerender_still_fails_preserved_routes_to_frame_reselect():
+    """Pre-cascade behavior preserved: when plan was feasible and rerender ran
+    but visual still failed, classifier emits rerender_still_fails → frame_reselect."""
+    trace = {
+        "retry_attempted": True,
+        "retry_passed": False,
+        "plan": {"feasible": True},
+        "rerender_attempted": True,
+    }
+    fc = classify_retry_failure(trace)
+    assert fc["failure_type"] == "rerender_still_fails"
+    nr = route_retry_failure("rerender_still_fails")
+    assert nr["next_proposed_action"] == "frame_reselect"
@@ -0,0 +1,77 @@
+"""IMP-12 u13 — plan_font_step_compression tests.
+
+Stage 2 contract (unit u13):
+  - feasible case (15.2 → 13 closes excess)
+  - infeasible (8px floor — FONT_SIZE_STEPS exhausted)
+  - text_metrics missing → defensive infeasible reason
+
+u6 wraps space_allocator.find_fitting_font_size in the Step-17 plan signature.
+Height savings per candidate font_size (Korean 1.6 line-height):
+    height_saved = (current_font_px * 1.6 - font_size * 1.6) * available_lines
+
+Scope lock per feedback_phase_z_spacing_direction:
+  - apply_font_step_compression_css emits ONLY [data-zone-position="<pos>"] rule.
+  - No :root / body / .slide / .zone selectors permitted.
+"""
+
+from src.phase_z2_retry import (
+    apply_font_step_compression_css,
+    plan_font_step_compression,
+)
+
+
+def test_feasible_15_2_to_13_closes_excess() -> None:
+    """current=15.2, excess=20, lines=10 → 14.0 saves 19.2 (insufficient);
+    13.0 saves 35.2 (>=20) → target_font_px=13.0. Emitted CSS scope-locked."""
+    plan = plan_font_step_compression(
+        current_font_px=15.2, excess_after_glue_px=20.0,
+        available_lines=10, chars_per_line=40, zone_position="bottom_l",
+    )
+    assert plan["action"] == "font_step_compression"
+    assert plan["zone_position"] == "bottom_l"
+    assert plan["current_font_px"] == 15.2
+    assert plan["excess_after_glue_px"] == 20.0
+    assert plan["available_lines"] == 10
+    assert plan["chars_per_line"] == 40
+    assert plan["font_floor_px"] == 8.0
+    assert plan["feasible"] is True
+    assert plan["target_font_px"] == 13.0
+    assert "failure_reason" not in plan
+
+    css = apply_font_step_compression_css(plan)
+    assert '[data-zone-position="bottom_l"]' in css
+    assert "font-size: 13.0px" in css
+    for forbidden in (":root", "body ", ".slide", ".zone"):
+        assert forbidden not in css, f"scope-lock violation: {forbidden!r} in css"
+
+
+def test_infeasible_font_floor_exhausted() -> None:
+    """current=15.2, excess=200, lines=10 — even 8.0px floor saves only 115.2,
+    so FONT_SIZE_STEPS is exhausted → feasible=False, classifier-matching reason."""
+    plan = plan_font_step_compression(
+        current_font_px=15.2, excess_after_glue_px=200.0,
+        available_lines=10, chars_per_line=40, zone_position="top",
+    )
+    assert plan["feasible"] is False
+    assert plan["target_font_px"] is None
+    assert plan["font_floor_px"] == 8.0
+    reason = plan["failure_reason"]
+    assert "font_step floor" in reason
+    assert "8.0px" in reason
+    assert "200.0px" in reason
+    assert "FONT_SIZE_STEPS exhausted" in reason
+    assert apply_font_step_compression_css(plan) == ""
+
+
+def test_text_metrics_missing_defensive_infeasible() -> None:
+    """available_lines=0 → guard fires before find_fitting_font_size;
+    failure_reason carries the text_metrics missing substring (classifier-friendly)."""
+    plan = plan_font_step_compression(
+        current_font_px=15.2, excess_after_glue_px=40.0,
+        available_lines=0, chars_per_line=40, zone_position="bottom_r",
+    )
+    assert plan["feasible"] is False
+    assert plan["target_font_px"] is None
+    assert "text_metrics missing" in plan["failure_reason"]
+    assert "available_lines/chars_per_line required" in plan["failure_reason"]
+    assert apply_font_step_compression_css(plan) == ""
@@ -0,0 +1,87 @@
+"""IMP-12 u12 — plan_glue_compression tests.
+
+Stage 2 contract (unit u12):
+  - feasible case asserts emitted CSS contains [data-zone-position=...]
+    selector and NO global :root / body / .slide rule (scope lock)
+  - insufficient case feasible=False with envelope reason
+
+u5 wraps space_allocator.calculate_glue_absorption + compute_glue_css_overrides
+in the Step-17 plan signature. Glue envelope per block_count (SPACING_GLUE):
+  absorption_max = block_gap.shrink * (block_count-1)        # 12 * (n-1)
+                 + inner_gap.shrink * block_count             # 8 * n
+                 + title_gap.shrink * block_count             # 4 * n
+                 + container_padding.shrink * 2               # 8 * 2
+
+  block_count=3 → 12*2 + 8*3 + 4*3 + 8*2 = 24+24+12+16 = 76 px
+  block_count=1 → 12*0 + 8*1 + 4*1 + 8*2 = 0+8+4+16   = 28 px
+
+CSS must be wrapped under [data-zone-position="<pos>"] only
+(feedback_phase_z_spacing_direction — no :root/body/.slide/.zone mutation).
+"""
+from __future__ import annotations
+
+from src.phase_z2_retry import (
+    apply_glue_compression_css,
+    plan_glue_compression,
+)
+
+
+def test_feasible_case_emits_zone_scoped_css():
+    """excess (40px) <= absorption_max (76px @ block_count=3) → feasible.
+
+    Emitted CSS must wrap overrides in [data-zone-position=...] selector and
+    contain none of the global selectors banned by feedback_phase_z_spacing_direction.
+    """
+    plan = plan_glue_compression(
+        excess_px=40.0, block_count=3, zone_position="bottom_l",
+    )
+    assert plan["action"] == "glue_compression"
+    assert plan["zone_position"] == "bottom_l"
+    assert plan["feasible"] is True
+    assert plan["excess_px"] == 40.0
+    assert plan["block_count"] == 3
+    assert plan["absorption_max_px"] == 76.0
+    overrides = plan["overrides"]
+    assert overrides, "feasible plan must return non-empty overrides"
+    for key in ("--spacing-block", "--spacing-inner", "--container-padding"):
+        assert key in overrides, f"missing override key {key}"
+
+    css = apply_glue_compression_css(plan)
+    assert '[data-zone-position="bottom_l"]' in css
+    assert "--spacing-block:" in css
+    assert "--spacing-inner:" in css
+    assert "--container-padding:" in css
+    # Scope lock — no global rules permitted.
+    for forbidden in (":root", "body ", ".slide", ".zone"):
+        assert forbidden not in css, f"forbidden selector {forbidden!r} leaked into glue CSS"
+
+
+def test_insufficient_envelope_feasible_false_with_reason():
+    """excess (80px) > absorption_max (28px @ block_count=1) → infeasible.
+
+    failure_reason must surface the envelope shortage so the cascade router
+    (NEXT_ACTION_BY_FAILURE) can route onward to font_step_compression.
+    """
+    plan = plan_glue_compression(
+        excess_px=80.0, block_count=1, zone_position="top",
+    )
+    assert plan["feasible"] is False
+    assert plan["absorption_max_px"] == 28.0
+    reason = plan["failure_reason"]
+    assert "glue envelope insufficient" in reason
+    assert "excess_px 80" in reason
+    assert "max absorption 28" in reason
+    # apply emits nothing when infeasible — no accidental CSS mutation on revert path.
+    assert apply_glue_compression_css(plan) == ""
+
+
+def test_excess_non_positive_no_compression_needed():
+    """excess_px <= 0 → defensive infeasible (no compression required)."""
+    plan = plan_glue_compression(
+        excess_px=0.0, block_count=3, zone_position="bottom_r",
+    )
+    assert plan["feasible"] is False
+    assert plan["overrides"] == {}
+    assert plan["absorption_max_px"] == 0.0
+    assert "no compression needed" in plan["failure_reason"]
+    assert apply_glue_compression_css(plan) == ""
@@ -0,0 +1,147 @@
+"""IMP-12 u10 — plan_zone_ratio_retry multi-donor aggregation tests.
+
+Stage 2 contract (unit u10):
+  - single-donor sufficient (regression — backward compat preserved)
+  - single insufficient + 2nd sufficient (multi-donor PASS path)
+  - aggregate insufficient (multi-donor FAIL path)
+
+u1 extended plan_zone_ratio_retry from a single primary donor to greedy
+slack-desc aggregation across all eligible sibling zones. The plan dict
+now carries donors_used / aggregate_slack_used / aggregate_slack_available
+while preserving donor_zone_position + donor_reduced_px for the failure
+classifier substrings (router still keys off primary donor name).
+"""
+from __future__ import annotations
+
+from src.phase_z2_retry import plan_zone_ratio_retry
+
+
+_ROUTER_ACTIVE = {"router_active": True}
+
+
+def _classification(target_pos: str, excess_y: float) -> dict:
+    return {
+        "classifications": [
+            {
+                "proposed_action": "zone_ratio_retry",
+                "zone_position": target_pos,
+                "inputs": {"excess_y": excess_y},
+            }
+        ]
+    }
+
+
+def _zone(position: str, height_px: int, min_height_px: int,
+          fit_status: str | None = "ok") -> dict:
+    return {
+        "position": position,
+        "height_px": height_px,
+        "min_height_px": min_height_px,
+        "composition_rationale": {
+            "capacity_fit": {"fit_status": fit_status},
+        },
+    }
+
+
+def _overflow_clean(donor_positions: list[str]) -> dict:
+    return {
+        "zones": [
+            {"position": p, "overflowed": False, "clipped_inner": False}
+            for p in donor_positions
+        ]
+    }
+
+
+def test_single_donor_sufficient_regression():
+    """One donor with abundant slack. Plan must remain feasible and the
+    legacy donor_zone_position / donor_reduced_px fields must reflect the
+    primary donor (router classifier substring stability)."""
+    debug_zones = [
+        _zone("top", height_px=200, min_height_px=180),
+        _zone("bottom", height_px=400, min_height_px=200),  # slack=200
+    ]
+    plan = plan_zone_ratio_retry(
+        debug_zones=debug_zones,
+        overflow=_overflow_clean(["bottom"]),
+        fit_classification=_classification("top", excess_y=20.0),
+        router_decision=_ROUTER_ACTIVE,
+    )
+    assert plan is not None
+    assert plan["feasible"] is True
+    # target_added_px = ceil(20) + DEFAULT_SAFETY_MARGIN_PX(4) = 24
+    assert plan["target_added_px"] == 24
+    assert plan["donor_zone_position"] == "bottom"
+    assert plan["donor_reduced_px"] == 24
+    assert plan["donors_used"] == [
+        {"position": "bottom", "reduced_px": 24,
+         "slack_before": 200, "slack_after": 176}
+    ]
+    assert plan["aggregate_slack_used"] == 24
+    assert plan["aggregate_slack_available"] == 200
+    assert plan["zones_after"]["top"] == 224
+    assert plan["zones_after"]["bottom"] == 376
+
+
+def test_multi_donor_pass_primary_insufficient_secondary_covers():
+    """Primary donor alone has insufficient slack but primary + secondary
+    aggregate covers target_added_px. Multi-donor greedy aggregation must
+    split the deficit across both donors in slack-desc order."""
+    debug_zones = [
+        _zone("top", height_px=300, min_height_px=200),
+        _zone("middle", height_px=250, min_height_px=200),   # slack=50
+        _zone("bottom", height_px=240, min_height_px=200),   # slack=40
+    ]
+    plan = plan_zone_ratio_retry(
+        debug_zones=debug_zones,
+        overflow=_overflow_clean(["middle", "bottom"]),
+        fit_classification=_classification("top", excess_y=66.0),
+        router_decision=_ROUTER_ACTIVE,
+    )
+    # target_added_px = ceil(66)+4 = 70.  Primary (middle, slack=50) alone
+    # cannot cover, but middle(50)+bottom(40)=90 >= 70.
+    assert plan["feasible"] is True
+    assert plan["target_added_px"] == 70
+    assert plan["aggregate_slack_available"] == 90
+    assert plan["aggregate_slack_used"] == 70
+    assert plan["donor_zone_position"] == "middle"   # primary
+    assert plan["donor_reduced_px"] == 50            # primary takes its full slack
+    assert [d["position"] for d in plan["donors_used"]] == ["middle", "bottom"]
+    assert plan["donors_used"][0]["reduced_px"] == 50
+    assert plan["donors_used"][1]["reduced_px"] == 20  # remainder
+    assert plan["zones_after"]["top"] == 370
+    assert plan["zones_after"]["middle"] == 200
+    assert plan["zones_after"]["bottom"] == 220
+
+
+def test_multi_donor_fail_aggregate_insufficient():
+    """All donors combined still cannot cover target_added_px. Plan must
+    be feasible=False with primary-donor substring preserved so the
+    failure_router classifier still routes through donor_slack_insufficient."""
+    debug_zones = [
+        _zone("top", height_px=300, min_height_px=200),
+        _zone("middle", height_px=210, min_height_px=200),   # slack=10
+        _zone("bottom", height_px=215, min_height_px=200),   # slack=15
+    ]
+    plan = plan_zone_ratio_retry(
+        debug_zones=debug_zones,
+        overflow=_overflow_clean(["middle", "bottom"]),
+        fit_classification=_classification("top", excess_y=66.0),
+        router_decision=_ROUTER_ACTIVE,
+    )
+    # target_added_px=70, aggregate=25 → fail
+    assert plan["feasible"] is False
+    assert plan["aggregate_slack_available"] == 25
+    assert plan["aggregate_slack_used"] == 0
+    assert plan["donors_used"] == []
+    # Primary = highest-slack donor = bottom (15)
+    assert plan["donor_zone_position"] == "bottom"
+    assert plan["donor_max_slack"] == 15
+    # Classifier substring stability: "donor", "slack", and "<" still present
+    reason = plan["failure_reason"]
+    assert "donor" in reason
+    assert "slack" in reason
+    assert "<" in reason
+    # zones unchanged on fail (revert-friendly)
+    assert plan["zones_after"]["top"] == 300
+    assert plan["zones_after"]["middle"] == 210
+    assert plan["zones_after"]["bottom"] == 215
@@ -0,0 +1,196 @@
+"""IMP-15 실행-1 (Gitea issue #45) — Step 14 image_aspect_mismatch detection.
+
+Tests Selenium-driven `<img>` aspect measurement added to ``run_overflow_check``:
+
+* Fixture A — 200×100 image rendered at 200×100 → ``abs(delta) < tol``, no fail
+  reason, ``passed=True``.
+* Fixture B — 200×100 image forced to render 200×200 → ``abs(delta) > 0.30``,
+  fail reason includes ``image aspect mismatch in zone--primary:``,
+  ``passed=False``.
+* Fixture C — ``<img>`` with no ``.zone`` ancestor (attached directly under
+  ``.slide``) → event reports ``zone_position == "unknown"``.
+
+Chromedriver resolution mirrors the pipeline's order
+(``PROJECT_ROOT/chromedriver{,.exe}`` → PATH fallback). When no driver is
+resolvable the suite skips by default; under ``PHASE_Z_REQUIRE_SELENIUM=1`` the
+tests are marked ``xfail(strict=True)`` so CI cannot silently lose coverage.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+import pytest
+
+from src.phase_z2_pipeline import (
+    IMAGE_ASPECT_DELTA_TOL,
+    PROJECT_ROOT,
+    run_overflow_check,
+)
+
+PIL_Image = pytest.importorskip("PIL.Image", reason="Pillow required for fixture PNGs")
+
+
+# ─── chromedriver skip / xfail guard ─────────────────────────────────
+
+def _selenium_manager_resolvable() -> bool:
+    """Probe ``webdriver.Chrome(options=...)`` — pipeline's third tier.
+
+    ``src/phase_z2_pipeline.py`` (run_overflow_check) tries
+    ``PROJECT_ROOT/chromedriver{,.exe}`` first, then falls back to
+    ``webdriver.Chrome(options=options)`` which delegates to Selenium Manager
+    for driver auto-resolution.  The test resolver must mirror that fallback
+    or PHASE_Z_REQUIRE_SELENIUM=1 produces spurious strict-XPASS failures on
+    machines where Selenium Manager can satisfy the pipeline at runtime.
+    """
+    try:
+        from selenium import webdriver
+        from selenium.webdriver.chrome.options import Options as _Opts
+    except Exception:
+        return False
+    opts = _Opts()
+    opts.add_argument("--headless=new")
+    opts.add_argument("--no-sandbox")
+    opts.add_argument("--disable-dev-shm-usage")
+    try:
+        drv = webdriver.Chrome(options=opts)
+    except Exception:
+        return False
+    try:
+        drv.quit()
+    except Exception:
+        pass
+    return True
+
+
+def _chromedriver_resolvable() -> bool:
+    """Mirror pipeline order: PROJECT_ROOT/chromedriver{,.exe} → PATH → Selenium Manager."""
+    for candidate in (PROJECT_ROOT / "chromedriver", PROJECT_ROOT / "chromedriver.exe"):
+        if candidate.is_file():
+            return True
+    if shutil.which("chromedriver") or shutil.which("chromedriver.exe"):
+        return True
+    return _selenium_manager_resolvable()
+
+
+_REQUIRE_SELENIUM = os.environ.get("PHASE_Z_REQUIRE_SELENIUM") == "1"
+_DRIVER_AVAILABLE = _chromedriver_resolvable()
+
+if not _DRIVER_AVAILABLE:
+    if _REQUIRE_SELENIUM:
+        pytestmark = pytest.mark.xfail(
+            strict=True,
+            reason="PHASE_Z_REQUIRE_SELENIUM=1 but chromedriver is unresolvable",
+        )
+    else:
+        pytestmark = pytest.mark.skip(
+            reason=(
+                "chromedriver unresolvable (PROJECT_ROOT/chromedriver{,.exe} + PATH + Selenium Manager); "
+                "set PHASE_Z_REQUIRE_SELENIUM=1 to make this a hard failure"
+            ),
+        )
+
+
+# ─── HTML / PNG fixture helpers ──────────────────────────────────────
+
+_SLIDE_CSS = """
+html, body { margin: 0; padding: 0; }
+.slide { width: 1280px; height: 720px; position: relative; box-sizing: border-box; }
+.zone { display: block; }
+"""
+
+
+def _write_png(path: Path, width: int, height: int, colour=(120, 160, 200)) -> Path:
+    img = PIL_Image.new("RGB", (width, height), colour)
+    img.save(path, format="PNG")
+    return path
+
+
+def _write_slide_html(tmp_path: Path, body_inner: str, name: str = "slide.html") -> Path:
+    html = (
+        "<!doctype html><html><head><meta charset='utf-8'>"
+        f"<style>{_SLIDE_CSS}</style></head><body>"
+        '<div class="slide" data-page="1">'
+        f"{body_inner}"
+        "</div></body></html>"
+    )
+    path = tmp_path / name
+    path.write_text(html, encoding="utf-8")
+    return path
+
+
+def _find_event(events, src_basename: str) -> dict:
+    for ev in events:
+        if Path(ev.get("src", "")).name == src_basename:
+            return ev
+    raise AssertionError(f"image_events missing entry for {src_basename}; got {events}")
+
+
+# ─── tests ───────────────────────────────────────────────────────────
+
+def test_image_no_distortion(tmp_path: Path) -> None:
+    """Fixture A — 200×100 image rendered at native 200×100. delta ≈ 0."""
+    png = _write_png(tmp_path / "ok.png", 200, 100)
+    body = (
+        '<div class="zone" data-zone-position="primary" data-template-id="t_ok">'
+        f'<img src="{png.name}" style="width:200px;height:100px;display:block">'
+        "</div>"
+    )
+    html_path = _write_slide_html(tmp_path, body, name="ok.html")
+    result = run_overflow_check(html_path)
+
+    assert "error" not in result, result
+    assert result.get("image_events"), "image_events must be populated"
+
+    ev = _find_event(result["image_events"], png.name)
+    assert ev["zone_position"] == "primary"
+    assert ev["natural_w"] == 200 and ev["natural_h"] == 100
+    assert ev["rendered_w"] == 200 and ev["rendered_h"] == 100
+    assert ev["delta"] is not None and abs(ev["delta"]) < IMAGE_ASPECT_DELTA_TOL
+
+    image_fails = [r for r in result.get("fail_reasons", []) if r.startswith("image aspect mismatch")]
+    assert image_fails == [], f"unexpected image fail_reasons: {image_fails}"
+    assert result["passed"] is True, result.get("fail_reasons")
+
+
+def test_image_forced_distortion(tmp_path: Path) -> None:
+    """Fixture B — 200×100 image forced to 200×200. delta > 0.30, fail emitted."""
+    png = _write_png(tmp_path / "bad.png", 200, 100, colour=(200, 80, 80))
+    body = (
+        '<div class="zone" data-zone-position="primary" data-template-id="t_bad">'
+        f'<img src="{png.name}" style="width:200px;height:200px;display:block">'
+        "</div>"
+    )
+    html_path = _write_slide_html(tmp_path, body, name="bad.html")
+    result = run_overflow_check(html_path)
+
+    assert "error" not in result, result
+    ev = _find_event(result["image_events"], png.name)
+    assert ev["natural_w"] == 200 and ev["natural_h"] == 100
+    assert ev["rendered_w"] == 200 and ev["rendered_h"] == 200
+    assert ev["delta"] is not None and abs(ev["delta"]) > 0.30
+
+    image_fails = [r for r in result.get("fail_reasons", []) if r.startswith("image aspect mismatch")]
+    assert len(image_fails) == 1, f"expected one image fail_reason, got: {image_fails}"
+    msg = image_fails[0]
+    assert msg.startswith("image aspect mismatch in zone--primary:"), msg
+    assert "natural=2.000" in msg and "rendered=1.000" in msg
+    assert f"src={png.name}" in msg or png.name in msg
+    assert result["passed"] is False
+
+
+def test_image_no_zone_ancestor(tmp_path: Path) -> None:
+    """Fixture C — <img> attached directly under .slide → zone_position == 'unknown'."""
+    png = _write_png(tmp_path / "loose.png", 200, 100, colour=(80, 200, 120))
+    body = f'<img src="{png.name}" style="width:200px;height:100px;display:block">'
+    html_path = _write_slide_html(tmp_path, body, name="loose.html")
+    result = run_overflow_check(html_path)
+
+    assert "error" not in result, result
+    ev = _find_event(result["image_events"], png.name)
+    assert ev["zone_position"] == "unknown"
+    assert ev["natural_w"] == 200 and ev["natural_h"] == 100
+    assert ev["delta"] is not None and abs(ev["delta"]) < IMAGE_ASPECT_DELTA_TOL
+    image_fails = [r for r in result.get("fail_reasons", []) if r.startswith("image aspect mismatch")]
+    assert image_fails == []
@@ -0,0 +1,248 @@
+"""IMP-12 u15 — End-to-end test of `_attempt_salvage_chain` (Step 17 deterministic salvage cascade).
+
+Three Stage 2 cases against `src.phase_z2_pipeline._attempt_salvage_chain`:
+  (a) zone_ratio fail + cross_zone pass  → final.html promoted, salvage_passed=True
+  (b) cross_zone fail + glue pass        → 2nd cascade step promoted, salvage_passed=True
+  (c) all 3 fail                          → (b)-revert preserved, original final.html intact, salvage_passed=False
+
+`render_slide` and `run_overflow_check` are monkey-patched so the test stays deterministic
+(no Selenium / Jinja2 template files). The patches only stand in for the rendering / overflow
+oracles — the planners (`plan_cross_zone_redistribute`, `plan_glue_compression`,
+`plan_font_step_compression`) and the cascade router (`route_retry_failure` /
+`SALVAGE_FAIL_BY_ACTION`) all run unmocked.
+"""
+from __future__ import annotations
+
+import shutil
+import tempfile
+from pathlib import Path
+
+import pytest
+
+import src.phase_z2_pipeline as _pz_pipeline
+from src.fit_verifier import FitAnalysis, RoleFit
+from src.phase_z2_pipeline import _attempt_salvage_chain
+
+
+_PROJECT_ROOT = _pz_pipeline.PROJECT_ROOT
+
+
+@pytest.fixture
+def project_tmp(tmp_path_factory):
+    """Temp dir under PROJECT_ROOT so _attempt_salvage_chain can call
+    candidate_path.relative_to(PROJECT_ROOT) without ValueError on a
+    cross-drive system tmp path (pytest's default tmp_path is under
+    %LOCALAPPDATA% on Windows, which lives on a different drive from
+    the project root in this repo)."""
+    base = _PROJECT_ROOT / ".orchestrator" / "tmp"
+    base.mkdir(parents=True, exist_ok=True)
+    d = Path(tempfile.mkdtemp(prefix="u15_salvage_", dir=str(base)))
+    try:
+        yield d
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+_LAYOUT_CSS_GATE_PASS = {
+    "areas": '"top" "bottom"',
+    "cols": "1fr",
+    "rows": "1fr 1fr",
+    "heights_px": [300, 290],
+    "widths_px": [1180],
+    "ratios": [0.508, 0.491],
+    "width_ratios": [1.0],
+    "dynamic_rows": True,
+    "dynamic_cols": False,
+}
+
+
+def _patch_render(monkeypatch):
+    """Stub render_slide → deterministic HTML envelope so the cascade does not
+    need real Jinja2 templates. Returns a counter so tests can assert how many
+    times it was invoked (one per CSS-feasible cascade step)."""
+    counter = {"n": 0}
+
+    def _stub(slide_title, slide_footer, zones_data, layout_preset, layout_css, gap_px=14):
+        counter["n"] += 1
+        return (
+            f"<html><head><meta charset='utf-8'></head>"
+            f"<body><div data-slide-title='{slide_title}'></div></body></html>"
+        )
+
+    monkeypatch.setattr(_pz_pipeline, "render_slide", _stub)
+    return counter
+
+
+def _kwargs(*, run_dir: Path, out_path: Path, cascade_inputs: dict,
+            initial_failure_type: str = "donor_slack_insufficient") -> dict:
+    return {
+        "run_dir": run_dir,
+        "out_path": out_path,
+        "slide_title": "u15-test",
+        "slide_footer": None,
+        "zones_data": [],
+        "layout_preset": "horizontal-2",
+        "layout_css": _LAYOUT_CSS_GATE_PASS,
+        "cascade_inputs": cascade_inputs,
+        "initial_failure_type": initial_failure_type,
+        "gap_px": 14,
+    }
+
+
+def test_case_a_cross_zone_passes_final_html_promoted(project_tmp, monkeypatch):
+    """(a) cross_zone_redistribute is feasible + run_overflow_check returns
+    passed=True → out_path overwritten with the cross_zone candidate HTML and
+    salvage_passed=True after the very first cascade iteration."""
+    out_path = project_tmp / "final.html"
+    out_path.write_text("ORIGINAL_BEFORE_SALVAGE", encoding="utf-8")
+
+    # Multi-role same-zone FitAnalysis: top +30 deficit, bottom_l -50 surplus.
+    fit_analysis = FitAnalysis(roles={
+        "top": RoleFit(role="top", allocated_px=200, shortfall_px=30.0),
+        "bottom_l": RoleFit(role="bottom_l", allocated_px=300, shortfall_px=-50.0),
+    })
+    containers = {
+        "top": {"zone": "slide_body", "height_px": 200},
+        "bottom_l": {"zone": "slide_body", "height_px": 300},
+    }
+    cascade_inputs = {
+        "fit_analysis": fit_analysis,
+        "containers": containers,
+        "min_margin_px": 10,
+        "excess_px": 30.0, "excess_after_glue_px": 30.0,
+        "block_count": 3, "zone_position": "top",
+        "current_font_px": 15.2, "available_lines": 10, "chars_per_line": 40,
+    }
+
+    _patch_render(monkeypatch)
+    monkeypatch.setattr(
+        _pz_pipeline, "run_overflow_check",
+        lambda p: {"passed": True, "fail_reasons": []},
+    )
+
+    trace = _attempt_salvage_chain(
+        **_kwargs(run_dir=project_tmp, out_path=out_path, cascade_inputs=cascade_inputs),
+    )
+
+    assert trace["salvage_attempted"] is True
+    assert trace["salvage_passed"] is True
+    assert len(trace["salvage_steps"]) == 1
+    step0 = trace["salvage_steps"][0]
+    assert step0["action"] == "cross_zone_redistribute"
+    assert step0["passed"] is True
+    assert step0["plan"]["feasible"] is True
+    assert step0["css_override"] and '[data-role=' in step0["css_override"]
+    # out_path was overwritten with the salvage candidate.
+    promoted = out_path.read_text(encoding="utf-8")
+    assert "ORIGINAL_BEFORE_SALVAGE" not in promoted
+    assert "u15-test" in promoted
+
+
+def test_case_b_cross_zone_fails_glue_passes_second_promoted(project_tmp, monkeypatch):
+    """(b) cross_zone is infeasible (single-role zone) → glue_compression CSS
+    emitted + run_overflow_check passes → out_path overwritten with the glue
+    candidate (2nd cascade step). salvage_passed=True; salvage_steps[0]
+    records the infeasible cross_zone attempt."""
+    out_path = project_tmp / "final.html"
+    out_path.write_text("ORIGINAL_BEFORE_SALVAGE", encoding="utf-8")
+
+    # Single-role zone → fit_verifier.redistribute returns can_redistribute=False
+    # (peer required, none present).
+    fit_analysis = FitAnalysis(roles={
+        "top": RoleFit(role="top", allocated_px=200, shortfall_px=30.0),
+    })
+    containers = {"top": {"zone": "slide_body", "height_px": 200}}
+    # Glue envelope at block_count=3 = 12*(3-1)+8*3+4*3+8*2 = 76 px → 40 px is feasible.
+    cascade_inputs = {
+        "fit_analysis": fit_analysis,
+        "containers": containers,
+        "min_margin_px": 10,
+        "excess_px": 40.0, "excess_after_glue_px": 40.0,
+        "block_count": 3, "zone_position": "bottom_l",
+        "current_font_px": 15.2, "available_lines": 10, "chars_per_line": 40,
+    }
+
+    render_counter = _patch_render(monkeypatch)
+    # cross_zone is infeasible → no CSS → no rerender / no overflow call. Glue is
+    # feasible → exactly one rerender + overflow call → return passed=True.
+    monkeypatch.setattr(
+        _pz_pipeline, "run_overflow_check",
+        lambda p: {"passed": True, "fail_reasons": []},
+    )
+
+    trace = _attempt_salvage_chain(
+        **_kwargs(run_dir=project_tmp, out_path=out_path, cascade_inputs=cascade_inputs),
+    )
+
+    assert trace["salvage_attempted"] is True
+    assert trace["salvage_passed"] is True
+    assert len(trace["salvage_steps"]) == 2
+
+    s0 = trace["salvage_steps"][0]
+    assert s0["action"] == "cross_zone_redistribute"
+    assert s0["passed"] is False
+    assert s0["plan"]["feasible"] is False
+    assert s0["css_override"] is None
+    assert "single-role zone" in (s0["plan"].get("failure_reason") or "")
+
+    s1 = trace["salvage_steps"][1]
+    assert s1["action"] == "glue_compression"
+    assert s1["passed"] is True
+    assert s1["plan"]["feasible"] is True
+    assert s1["css_override"] and '[data-zone-position="bottom_l"]' in s1["css_override"]
+    # render_slide was invoked exactly once (only the glue branch emitted CSS).
+    assert render_counter["n"] == 1
+    # out_path was overwritten with the glue candidate.
+    promoted = out_path.read_text(encoding="utf-8")
+    assert "ORIGINAL_BEFORE_SALVAGE" not in promoted
+
+
+def test_case_c_all_three_fail_revert_preserved(project_tmp, monkeypatch):
+    """(c) All three cascade actions are infeasible (no CSS emitted by any
+    planner) → run_overflow_check is never invoked, salvage_passed=False,
+    salvage_steps has three failed entries, and out_path is unchanged
+    (original final.html intact — (b)-revert preserved)."""
+    out_path = project_tmp / "final.html"
+    out_path.write_text("ORIGINAL_BEFORE_SALVAGE", encoding="utf-8")
+
+    cascade_inputs = {
+        # cross_zone: fit_analysis missing → plan returns feasible=False with reason
+        # `cascade_inputs.fit_analysis missing` (see _attempt_salvage_chain branch).
+        "fit_analysis": None,
+        "containers": {},
+        "min_margin_px": 10,
+        # glue: excess_px (200) > envelope max at block_count=1 (28) → infeasible.
+        "excess_px": 200.0, "excess_after_glue_px": 200.0,
+        "block_count": 1, "zone_position": "top",
+        # font_step: current_font_px=15.2 cannot absorb 200px even at 8px floor
+        # → find_fitting_font_size returns None → feasible=False.
+        "current_font_px": 15.2, "available_lines": 10, "chars_per_line": 40,
+    }
+
+    render_counter = _patch_render(monkeypatch)
+    # Guard: if run_overflow_check is ever called, the test fails loudly.
+    def _must_not_call(_p):  # pragma: no cover — intentional sentinel
+        raise AssertionError("run_overflow_check must not run when no CSS is emitted")
+    monkeypatch.setattr(_pz_pipeline, "run_overflow_check", _must_not_call)
+
+    trace = _attempt_salvage_chain(
+        **_kwargs(run_dir=project_tmp, out_path=out_path, cascade_inputs=cascade_inputs),
+    )
+
+    assert trace["salvage_attempted"] is True
+    assert trace["salvage_passed"] is False
+    assert len(trace["salvage_steps"]) == 3
+    actions = [s["action"] for s in trace["salvage_steps"]]
+    assert actions == [
+        "cross_zone_redistribute",
+        "glue_compression",
+        "font_step_compression",
+    ]
+    for step in trace["salvage_steps"]:
+        assert step["passed"] is False
+        assert step["css_override"] is None
+        assert step["failure_reason"]
+    # No CSS emitted anywhere → no render_slide calls either.
+    assert render_counter["n"] == 0
+    # (b) revert: out_path is untouched.
+    assert out_path.read_text(encoding="utf-8") == "ORIGINAL_BEFORE_SALVAGE"
@@ -0,0 +1,129 @@
+"""IMP-09 PR 1 — retry gate tests (_attempt_zone_ratio_retry early exit).
+
+Stage 3 round 4 lock §2-A: row-axis retry must skip when layout has
+dynamic_cols=True (2-D topology) OR dynamic_rows=False (fr_default
+sink). The horizontal-2 path (dynamic_rows=True, dynamic_cols=False)
+must still proceed through the gate.
+
+These tests exercise the gate by routing the request through
+_attempt_zone_ratio_retry with router_active=True + proposed
+zone_ratio_retry — but with layout_css fields that should trip the
+gate. We confirm the early skip by asserting retry_attempted==False
+and retry_skipped_reason content.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from src.phase_z2_pipeline import _attempt_zone_ratio_retry
+
+
+_ROUTER_ACTIVE = {
+    "router_active": True,
+    "proposed_actions_summary": ["zone_ratio_retry"],
+}
+
+
+def _dummy_kwargs(layout_css: dict, tmp_path: Path) -> dict:
+    """All params required by _attempt_zone_ratio_retry. Only
+    `layout_css` and `router_decision` matter pre-gate."""
+    return {
+        "run_dir": tmp_path,
+        "out_path": tmp_path / "final.html",
+        "slide_title": "test",
+        "slide_footer": None,
+        "zones_data": [],
+        "debug_zones": [],
+        "layout_preset": "horizontal-2",
+        "layout_css": layout_css,
+        "overflow": {},
+        "fit_classification": {},
+        "router_decision": _ROUTER_ACTIVE,
+        "gap_px": 14,
+    }
+
+
+def test_vertical_2_dynamic_cols_skips_retry(tmp_path):
+    layout_css = {
+        "areas": '"left right"',
+        "cols": "583px 583px",
+        "rows": "1fr",
+        "heights_px": [585],
+        "widths_px": [583, 583],
+        "ratios": [1.0],
+        "width_ratios": [0.494, 0.494],
+        "dynamic_rows": False,
+        "dynamic_cols": True,
+    }
+    trace = _attempt_zone_ratio_retry(**_dummy_kwargs(layout_css, tmp_path))
+    assert trace["retry_attempted"] is False
+    assert "dynamic_cols" in trace["retry_skipped_reason"]
+    assert "IMP-09" in trace["retry_skipped_reason"]
+
+
+def test_fr_default_sink_skips_retry(tmp_path):
+    # PR 1 single / T-shape / 2x2 fall through to fr_default and must
+    # not enter row-only retry plan.
+    layout_css = {
+        "areas": '"top top" "bottom-left bottom-right"',
+        "cols": "1fr 1fr",
+        "rows": "1fr 1fr",
+        "heights_px": [285, 286],
+        "widths_px": [583, 583],
+        "ratios": [0.487, 0.489],
+        "width_ratios": [0.494, 0.494],
+        "dynamic_rows": False,
+        "dynamic_cols": False,
+    }
+    trace = _attempt_zone_ratio_retry(**_dummy_kwargs(layout_css, tmp_path))
+    assert trace["retry_attempted"] is False
+    assert "fr_default_from_preset" in trace["retry_skipped_reason"]
+
+
+def test_horizontal_2_dynamic_rows_passes_gate(tmp_path):
+    """horizontal-2 with dynamic_rows=True must pass the gate. The
+    test does not need plan_zone_ratio_retry to succeed; it only
+    asserts the gate did not early-skip with one of the new
+    skip reasons."""
+    layout_css = {
+        "areas": '"top" "bottom"',
+        "cols": "1fr",
+        "rows": "333px 238px",
+        "heights_px": [333, 238],
+        "widths_px": [1180],
+        "ratios": [0.569, 0.407],
+        "width_ratios": [1.0],
+        "dynamic_rows": True,
+        "dynamic_cols": False,
+    }
+    # plan_zone_ratio_retry will return None because debug_zones is
+    # empty, so retry_attempted=True but plan==None.
+    trace = _attempt_zone_ratio_retry(**_dummy_kwargs(layout_css, tmp_path))
+    assert trace["retry_attempted"] is True
+    # The gate was passed; skip reason (if any) is the legacy
+    # plan-failure reason, not the new gate reasons.
+    skip_reason = trace.get("retry_skipped_reason")
+    if skip_reason is not None:
+        assert "dynamic_cols" not in skip_reason
+        assert "fr_default_from_preset" not in skip_reason
+
+
+def test_router_inactive_skips_before_gate(tmp_path):
+    """When router_active=False, the early skip happens before the
+    new IMP-09 gate. Verify the existing behavior is unchanged."""
+    layout_css = {
+        "areas": '"left right"',
+        "dynamic_rows": False,
+        "dynamic_cols": True,
+        "heights_px": [585],
+        "widths_px": [583, 583],
+        "ratios": [1.0],
+        "width_ratios": [0.5, 0.5],
+    }
+    kwargs = _dummy_kwargs(layout_css, tmp_path)
+    kwargs["router_decision"] = {"router_active": False}
+    trace = _attempt_zone_ratio_retry(**kwargs)
+    assert trace["retry_attempted"] is False
+    assert "router_active=False" in trace["retry_skipped_reason"]
@@ -0,0 +1,69 @@
+"""IMP-14 A-4 — slide_base.html embedded_mode contract tests.
+
+Asserts the three-valued enum (auto / embedded / standalone) round-trips
+through render_slide -> slide_base.html, that the additive html.embedded
+CSS reset and the auto-mode detection <script> are emitted under the
+correct modes, that the invalid-mode guard raises ValueError, and that
+Jinja2 rendering is byte-deterministic across calls.
+"""
+from __future__ import annotations
+
+import pytest
+
+from src.phase_z2_pipeline import render_slide
+
+
+def _zone() -> dict:
+    return {"position": "primary", "template_id": "__empty__", "slot_payload": {}}
+
+
+def _layout_css() -> dict:
+    return {"areas": '"primary"', "cols": "1fr", "rows": "1fr"}
+
+
+def _render(embedded_mode: str = "auto") -> str:
+    return render_slide(
+        slide_title="t",
+        slide_footer=None,
+        zones_data=[_zone()],
+        layout_preset="single",
+        layout_css=_layout_css(),
+        gap_px=14,
+        embedded_mode=embedded_mode,
+    )
+
+
+def test_auto_script_present():
+    html = _render("auto")
+    assert "params.get('embedded')" in html
+    assert "window.self !== window.top" in html
+    assert "classList.add('embedded')" in html
+
+
+def test_css_rules_present():
+    html = _render("auto")
+    assert "html.embedded body" in html
+    assert "html.embedded .slide" in html
+
+
+def test_embedded_mode_explicit():
+    html = _render("embedded")
+    assert '<html lang="ko" class="embedded">' in html
+    assert "params.get('embedded')" not in html
+
+
+def test_standalone_mode_explicit():
+    html = _render("standalone")
+    assert '<html lang="ko">' in html
+    assert 'class="embedded"' not in html.split("</head>")[0]
+    assert "params.get('embedded')" not in html
+
+
+def test_deterministic():
+    assert _render("embedded") == _render("embedded")
+    assert _render("auto") == _render("auto")
+
+
+def test_invalid_mode_raises():
+    with pytest.raises(ValueError, match="invalid embedded_mode"):
+        _render("bogus")
@@ -0,0 +1,50 @@
+"""IMP-13 u7 smoke — discovery, source invariants, dry-run, idempotency, manifest schema."""
+from __future__ import annotations
+import json, os, re, sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SCRIPT_PATH = REPO_ROOT / "scripts" / "generate_frame_previews.py"
+sys.path.insert(0, str(SCRIPT_PATH.parent))
+import generate_frame_previews as gfp  # noqa: E402
+
+def _fixture(root: Path) -> Path:
+    blocks = root / "blocks"
+    (blocks / "FRAME_A").mkdir(parents=True)
+    (blocks / "FRAME_A" / "index.html").write_text("<html><body class=slide></body></html>", encoding="utf-8")
+    (blocks / "FRAME_A" / "preview.png").write_bytes(b"\x89PNG\r\n\x1a\n")
+    (blocks / "FRAME_B").mkdir()
+    (blocks / "ORPHAN").mkdir()
+    (blocks / "ORPHAN" / "preview.png").write_bytes(b"x")
+    return blocks
+
+def test_discover_counts(tmp_path: Path) -> None:
+    rows = gfp.discover(_fixture(tmp_path))
+    assert [r.frame_id for r in rows] == ["FRAME_A", "FRAME_B", "ORPHAN"]
+    assert sum(r.has_index for r in rows) == 1 and sum(r.has_preview for r in rows) == 2
+
+def test_source_invariants() -> None:
+    src = SCRIPT_PATH.read_text(encoding="utf-8")
+    for t in ("anthropic", "openai", "jinja", "phase_z2", "slide_measurer"): assert t not in src, t
+    for lit in ("1280", "720", "1400", "900"): assert not re.search(rf"(?<!\d){lit}(?!\d)", src), lit
+
+def test_dry_run_prints_counts(tmp_path: Path, capsys) -> None:
+    rc = gfp.main(["--blocks-dir", str(_fixture(tmp_path)), "--manifest", str(tmp_path / "m.json"), "--dry-run"])
+    assert rc == 0 and "discovered: total=3 with_index_html=1 with_preview_png=2" in capsys.readouterr().out
+
+def test_idempotency_unchanged(tmp_path: Path) -> None:
+    row = gfp.discover(_fixture(tmp_path))[0]
+    mt = row.index_html_path.stat().st_mtime
+    os.utime(row.preview_png_path, (mt + 1, mt + 1))
+    sha = gfp._sha256_file(row.index_html_path)
+    assert gfp.is_unchanged(row, {"index_sha256": sha}) is True
+    assert gfp.is_unchanged(row, {"index_sha256": "x"}) is False
+    assert gfp.is_unchanged(row, None) is False
+
+def test_manifest_schema(tmp_path: Path) -> None:
+    blocks = tmp_path / "blocks"; (blocks / "F").mkdir(parents=True); (blocks / "F" / "preview.png").write_bytes(b"x")
+    mf = tmp_path / "m.json"
+    assert gfp.main(["--blocks-dir", str(blocks), "--manifest", str(mf)]) == 0
+    data = json.loads(mf.read_text(encoding="utf-8"))
+    assert set(data) >= {"schema", "generated_at", "blocks_dir", "summary", "frames"} and data["schema"] == 1
+    assert set(data["summary"]) >= {"total", "renderable", "missing_index_html", "orphan", "rendered", "skipped_unchanged", "error"} and data["summary"]["orphan"] == 1 and data["frames"]["F"]["status"] == "orphan"
@@ -0,0 +1,169 @@
+"""IMP-11 D-2 (u1) — Step 9 v4_all_judgments[] min_height_px field tests.
+
+u1 contract:
+  Each v4_all_judgments[] entry MUST expose `min_height_px` sourced from
+  catalog `frame_contracts[template_id].visual_hints.min_height_px`
+  (logical 1280×720 px), with `None` fallback when contract is unregistered.
+  A single `get_contract(c.template_id)` lookup binds both
+  `catalog_registered` and `min_height_px` (no double-lookup cost).
+
+Production code = inline list builder in `run_phase_z2_mvp1`
+(`src/phase_z2_pipeline.py`, near v4_all_for_unit loop). These tests follow
+the same source-string + catalog-shape guard pattern as the existing
+`test_step9_production_emits_candidate_evidence_and_alias` in
+`tests/test_phase_z2_v4_fallback.py`, kept until a helper is extracted.
+"""
+from __future__ import annotations
+
+import inspect
+
+from src import phase_z2_pipeline
+from phase_z2_mapper import get_contract, load_frame_contracts
+
+
+# ─── Case 1 : u1 production-source guard ────────────────────────────────────
+
+
+def test_v4_all_judgments_emits_min_height_px_with_none_fallback():
+    """Source guard — single get_contract bound to `_contract`, then both
+    `catalog_registered` and `min_height_px` derived from that binding.
+    `min_height_px` uses the `(_contract or {})` chain so unregistered
+    contracts propagate `None` (frontend tolerates undefined).
+    """
+    source = inspect.getsource(phase_z2_pipeline)
+
+    # u1 marker present (locates the builder)
+    assert "IMP-11 D-2 (u1)" in source
+
+    # Single get_contract lookup bound to local var
+    assert "_contract = get_contract(c.template_id)" in source
+
+    # catalog_registered reuses the local binding (no second lookup)
+    assert '"catalog_registered": _contract is not None' in source
+
+    # min_height_px source = visual_hints chain; None when contract is None
+    assert (
+        '"min_height_px": (_contract or {})'
+        '.get("visual_hints", {})'
+        '.get("min_height_px")'
+    ) in source
+
+    # v4_all_judgments wires the new builder list
+    assert '"v4_all_judgments": v4_all_judgments_list' in source
+
+
+# ─── Case 2 : additive guarantee — existing 7 fields preserved ──────────────
+
+
+def test_v4_all_judgments_preserves_existing_fields():
+    """u1 is additive only — the existing 7 keys must remain in the per-entry
+    dict alongside the new `min_height_px`.
+    """
+    source = inspect.getsource(phase_z2_pipeline)
+
+    builder_start = source.find("IMP-11 D-2 (u1)")
+    assert builder_start != -1
+    builder_end = source.find("application_plan_units.append", builder_start)
+    assert builder_end != -1
+    builder = source[builder_start:builder_end]
+
+    for field in (
+        '"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',
+        '"catalog_registered": _contract is not None',
+        '"min_height_px":',
+    ):
+        assert field in builder, f"missing field in u1 builder: {field!r}"
+
+
+# ─── Case 3 : catalog reality — visual_hints.min_height_px shape is real ────
+
+
+def test_catalog_visual_hints_min_height_px_path_is_real():
+    """The source-string guard depends on the actual catalog shape having
+    `visual_hints.min_height_px` as a positive int on registered contracts
+    whose `visual_hints` block declares it. Verify against the real
+    `frame_contracts.yaml` so a future catalog schema change cannot silently
+    invalidate the `.get("visual_hints", {}).get("min_height_px")` chain.
+    """
+    load_frame_contracts()
+
+    # Real registered template_ids that ship with visual_hints.min_height_px
+    # (verified via load_frame_contracts() — see frame_contracts.yaml).
+    sample_template_ids = (
+        "three_parallel_requirements",
+        "process_product_two_way",
+        "construction_goals_three_circle_intersection",
+        "bim_dx_comparison_table",
+    )
+
+    found = 0
+    for tid in sample_template_ids:
+        contract = get_contract(tid)
+        if contract is None:
+            continue  # tolerate catalog rename — at least one must remain
+        # The exact .get chain used by the u1 builder
+        min_h = (contract or {}).get("visual_hints", {}).get("min_height_px")
+        assert isinstance(min_h, int), (
+            f"{tid}: visual_hints.min_height_px must be int, "
+            f"got {type(min_h).__name__}={min_h!r}"
+        )
+        assert min_h > 0, f"{tid}: min_height_px must be positive, got {min_h}"
+        found += 1
+
+    assert found > 0, (
+        "no sample registered contract present — catalog audit drift; "
+        "update sample_template_ids to match current frame_contracts.yaml"
+    )
+
+
+def test_registered_contract_without_min_height_px_propagates_none():
+    """Registered contract whose `visual_hints` block omits `min_height_px`
+    (or sets it to `null`) must also propagate `None` through the u1 chain.
+    Real example in current catalog: `bim_issues_quadrant_four`.
+    """
+    load_frame_contracts()
+
+    tid = "bim_issues_quadrant_four"
+    contract = get_contract(tid)
+    if contract is None:
+        import pytest  # noqa: PLC0415  — runtime skip only when catalog drifts
+        pytest.skip(f"sample template {tid!r} no longer registered")
+
+    # Exact chain used by u1 builder
+    min_h = (contract or {}).get("visual_hints", {}).get("min_height_px")
+    assert min_h is None, (
+        f"{tid}: expected None when visual_hints.min_height_px is absent/null, "
+        f"got {min_h!r} — chain semantics changed"
+    )
+    # catalog_registered must still be True (additive, independent of value)
+    assert (contract is not None) is True
+
+
+# ─── Case 4 : None propagation for unregistered template_id ─────────────────
+
+
+def test_unregistered_template_id_propagates_none():
+    """When `get_contract(template_id)` returns `None`, the u1 chain
+    `(_contract or {}).get("visual_hints", {}).get("min_height_px")` must
+    yield `None` (frontend tolerates undefined; no KeyError).
+    """
+    load_frame_contracts()
+
+    # Synthetic template_id guaranteed not to be in the catalog
+    unregistered = "MOCK_template_unregistered_for_u1_test"
+    assert get_contract(unregistered) is None, (
+        "test precondition broken — synthetic template_id leaked into catalog"
+    )
+
+    # Replicate the u1 chain exactly
+    _contract = get_contract(unregistered)
+    min_height = (_contract or {}).get("visual_hints", {}).get("min_height_px")
+    catalog_registered = _contract is not None
+
+    assert min_height is None
+    assert catalog_registered is False
@@ -111,9 +111,9 @@ def test_mdx_section_default_construction_preserves_4_positional_callers():


 def test_align_passthrough_when_v4_key_exact_match():
-    # Section already aligned to V4 key (no H3 sub-sections, no override
-    # target): aligner keeps it untouched. Parent-level V4 evidence
-    # flows via exact-match lookup.
+    # Section already aligned to V4 key (no override target): aligner
+    # keeps it untouched. Parent-level V4 evidence flows via exact-match
+    # lookup.
    sections = [_section("04-1", 1, "1. Top", "body")]
    v4 = {"mdx_sections": {"04-1": {"judgments_full32": []}}}
    out = align_sections_to_v4_granularity(sections, v4)
Author	SHA1	Message	Date
KyeongminandClaude Opus 4.7	e9b3d2e9c0	feat(IMP-15): 실행-1 — Step 14 image_aspect_mismatch detection Issue: #45 (IMP-15 실행-1, image axis only). Adds Selenium-based <img> aspect ratio measurement to Step 14 run_overflow_check + numeric tolerance gate. Tolerance lives as module-scope constant so tests can import it. src/phase_z2_pipeline.py (+73/-2): - L131-L135 IMAGE_ASPECT_DELTA_TOL = 0.05 (module scope, importable) - L2216-L2261 JS payload extension: image_events[] per <img> (src, zone_position via closest('.zone') with 'unknown' fallback, zone_template_id, natural/rendered w+h+ratio, delta, slide-rel bbox) - L2262 run_overflow_check return extended with image_events - L2302-L2320 Python aggregation: abs(delta) > TOL ⇒ fail_reasons append 'image aspect mismatch in zone--<pos>: natural=<n> rendered=<r> delta=<+d> (template=<tid>, tol=0.05, src=<src>)'. Null-delta entries (image not loaded) are skipped — no false positive. Branch placed AFTER existing non-image branches; ordering & strings for slide/slide-body/zone/clipped_inner unchanged. - L4425-L4429 Step 14 note: image half closed, table half deferred to 실행-2. tests/phase_z2/test_phase_z2_step14_image_check.py (+196, new): - 3-tier chromedriver resolver mirroring pipeline (PROJECT_ROOT/ chromedriver{,.exe} → PATH → Selenium Manager probe). - pytestmark: skip when chromedriver unresolvable AND PHASE_Z_REQUIRE_SELENIUM != '1'; xfail(strict=True) opt-in when =='1'. - Fixture A: 200×100 img rendered 200×100 → aspect_delta < 0.05, passed. - Fixture B: 200×100 intrinsic forced to 200×200 → delta > 0.30, fail_reason present. - Fixture C: <img> with no .zone ancestor → zone_position == 'unknown'. Verification (Stage 4 PASS, Claude + Codex independent): - pytest -q tests/phase_z2/test_phase_z2_step14_image_check.py → 3 passed - PHASE_Z_REQUIRE_SELENIUM=1 same suite → 3 passed (strict opt-in) - pytest -q tests/phase_z2 → 90 passed (no regression) - pytest -q --ignore=tests/matching → 174 passed Scope-locked: no slide_base.html / catalog / classifier / debug.json / spec-doc changes. table_events (실행-2), visual_check_passed flip (실행-3), debug.json image_events surfacing + PHASE-Z spec doc row (실행-4) remain queued as separate IMP-15 child execution issues. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-18 18:01:28 +09:00
Kyeongmin	7a52cebfaa	feat(IMP-14): A-4 — slide_base embedded vs standalone mode contract Step 13 owns iframe-vs-standalone CSS contract in slide_base.html via 3-valued embedded_mode enum (auto / embedded / standalone). Removes SlideCanvas.tsx runtime CSS injection workaround; frontend now passes ?embedded=1 query so auto-mode script attaches html.embedded class and scopes the standalone body centering/min-height/padding reset. - templates/phase_z2/slide_base.html: conditional html.embedded class + CSP-safe auto-mode <script> + additive html.embedded body/.slide rules - src/phase_z2_pipeline.py: render_slide gains keyword-only embedded_mode ("auto" default) + ValueError guard; 3 existing call sites unchanged - Front/client/src/components/SlideCanvas.tsx: derive embeddedSrc with ?embedded=1 (query-preserving), drop reset CSS injection block - tests/phase_z2/test_slide_base_embedded_mode.py: 6 cases — auto script, CSS rules, embedded/standalone explicit modes, byte-determinism, invalid-mode guard	2026-05-18 07:21:31 +09:00
KyeongminandClaude Opus 4.7	7d5639ad72	feat(IMP-13): A-3 — build-time frame preview generator (capture_slide_screenshot salvage) scripts/generate_frame_previews.py iterates figma_to_html_agent/blocks/{frame_id}/index.html, renders preview.png via Selenium headless (capture_slide_screenshot pattern reuse), and writes _preview_manifest.json (schema v1) with idempotent stale-detect (mtime+sha256). Build-time only — no runtime pipeline integration, no AI calls, no MDX/Jinja regen. Stage 2 baseline (commit `56619a0`): total=33, renderable=20, missing_index_html=13, orphan=1 (1171281192). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-18 06:25:05 +09:00
KyeongminandClaude Opus 4.7	56619a0239	feat(IMP-12): Step 16/17 retry refinement — multi-donor + 3-stage salvage cascade Extend Step 17 deterministic action surface so donor_slack_insufficient no longer abort-terminates at zone_ratio_retry. AI is NOT invoked on the normal salvage path. Source changes (4 files, scope-locked): - src/phase_z2_retry.py — plan_zone_ratio_retry: single-primary-donor → multi-donor greedy aggregation (donors_used / aggregate_slack_used / aggregate_slack_available); new plan/apply pairs: cross_zone_redistribute (wraps fit_verifier.redistribute, data-role scoped CSS), glue_compression (wraps space_allocator.compute_glue_css_overrides, data-zone-position scoped), font_step_compression (wraps find_fitting_font_size, zone-scoped, defensive feasible=False on missing text_metrics). - src/phase_z2_failure_router.py — classifier inspects salvage_steps[-1] via SALVAGE_FAILURE_TYPE_BY_ACTION; NEXT_ACTION_BY_FAILURE rewired into donor_slack_insufficient/no_donor_candidates → cross_zone_redistribute → glue → font_step → layout_adjust; 3 IMPLEMENTED salvage status rows added. - src/phase_z2_router.py — ACTION_IMPLEMENTATION_STATUS registers 3 new salvage actions as IMPLEMENTED; ACTION_BY_CATEGORY untouched (cascade-only labels). - src/phase_z2_pipeline.py — new _attempt_salvage_chain() iterates router next_proposed_action with retry_budget=1 per action; honors IMP-09 dynamic_cols / fr_default gate; preserves (b)-revert on all-fail; wires Step 17 telemetry (salvage_steps / salvage_passed). Tests (6 new pytest modules): - test_phase_z2_retry_multi_donor.py — single sufficient (regression), 1st insufficient + 2nd sufficient (multi-donor PASS), aggregate insufficient FAIL. - test_phase_z2_cross_zone_redistribute.py — multi-role zone feasible, single-role zone short-circuits infeasible. - test_phase_z2_glue_compression.py — feasible asserts emitted CSS contains [data-zone-position=...] selector and NO global :root/body/.slide rule. - test_phase_z2_font_step_compression.py — 15.2 → 13 closes excess; 8px floor; missing text_metrics → defensive infeasible reason. - test_phase_z2_failure_router_cascade.py — donor_slack_insufficient → cross_zone (impl=IMPLEMENTED); 3 new failure types → expected next actions; rerender_still_fails preserves frame_reselect terminus. - test_phase_z2_step17_salvage_chain.py — end-to-end (a) cross_zone PASS promotes final.html, (b) cross_zone FAIL + glue PASS promotes 2nd candidate, (c) all-3 FAIL preserves original final.html (revert). Guardrails preserved: - AI calls: 0 on normal path (feedback_ai_isolation_contract) - Spacing direction: no shrink-common-margin; resolve via donor/glue/font-step within frame envelope (feedback_phase_z_spacing_direction) - All CSS overrides scoped to [data-role=...] or [data-zone-position=...] - IMP-09 dynamic_cols / fr_default gate honored in cascade - (b)-revert preserved if all 3 salvage actions fail Refs: gitea#12 IMP-12 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-18 02:07:22 +09:00
KyeongminandClaude Opus 4.7	a79bd8bc43	feat(IMP-11): D-2 — frame min_height_px hint (backend → UI) Step 9 v4_all_judgments[] now exposes per-candidate min_height_px from catalog frame_contracts.visual_hints.min_height_px (None when contract unregistered). SlideCanvas pendingLayout zones render a red ring + 'min H Npx' badge when zone height falls below the active frame's threshold. Visual hint only; resize clamp (minSize=0.05) unchanged. 5 axes (single commit per Stage 5 plan): - u1 backend: src/phase_z2_pipeline.py — Step 9 builder adds min_height_px via single get_contract(c.template_id) lookup; reuses _contract for catalog_registered (no double-lookup). - u2 type: Front/client/src/types/designAgent.ts — FrameCandidate gains optional minHeightPx?: number. - u3 mapper: Front/client/src/services/designAgentApi.ts — maps snake-case min_height_px → camelCase minHeightPx on v4_all_judgments path; v4_candidates fallback remains undefined (graceful). - u4 active-frame lookup: Front/client/src/components/SlideCanvas.tsx — activeFrameId = overrideFrameId ?? defaultFrameId; activeCandidate via region.frame_candidates.find. - u5 hint render: Front/client/src/components/SlideCanvas.tsx — zoneHeightPx = height * SLIDE_H (logical px, no double-apply); compare against activeCandidate.minHeightPx in pendingLayout mode only; red border + badge when below. Tests: 5/5 pass in tests/test_phase_z2_step9_v4_all_judgments_min_height.py (source-string + catalog-shape guards + None propagation, registered and unregistered template_ids). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-17 22:29:17 +09:00
KyeongminandClaude Opus 4.7	0fb168befc	feat(IMP-10): D-1 — filtered_section_reasons UI (read-only) Surface step20_slide_status.json.data.filtered_section_reasons in the frontend Home header. Verbatim mirror of backend payload — no enum redefinition, no translation, no auto-classification. Units: - u1: FilteredSectionReason interface mirroring src/phase_z2_pipeline.py :2217-2278 (10 fields incl. override-uncovered source/position variant). - u2: RunMeta extension + loadRun() mapping with ?? [] back-compat defaults. - u3: Header badge + <details> disclosure adjacent to existing status badge; hidden when filtered_section_ids.length === 0; renders all 10 schema fields + filter_reasons[] verbatim. Scope: - Frontend-only, read-only. No backend / sync script / Kei·AI panel changes. Files: Front/client/src/services/designAgentApi.ts (+20), Front/client/src/pages/Home.tsx (+25). Refs: gitea issue #10 (IMP-10 D-1 filtered_section_reasons UI) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-17 19:43:13 +09:00
KyeongminandClaude Opus 4.7	1fb973297f	feat(IMP-09): PR 2 — 2-D dynamic dispatch for 5 preset families Stage 3 lock implementation: extend build_layout_css dispatch beyond the horizontal-2 / vertical-2 1-D dynamic paths. T / inverted-T / side-T-left / side-T-right / 2x2 now flow through a 2-D track solver instead of the fr_default sink, with length-locked heights_px (R) + widths_px (C) on every return path (default and override). PR 2 scope (u1~u5): - u1: _aggregate_zone_signals_per_track — per-row + per-col virtual zones via max(weight) + max(min_height_px) of single-span zones, falling back to all-span when a track has none. - u2: _build_grid_dynamic_2d default builder — feeds virtual zones into compute_zone_layout + compute_zone_layout_cols; emits computation="2d_dynamic_aggregated", dynamic_rows=True, dynamic_cols=True. - u3: _override_to_grid_tracks override builder — single-span aggregation (max h per row, max w per col), normalize, multiply by avail_h/avail_w, last-element diff absorb; emits computation="user_override_geometry"; falls back to u2 when total_h or total_w == 0. - u4: build_layout_css dispatcher wiring — topology in {T, inverted-T, side-T-left, side-T-right, 2x2} routes to _build_grid_dynamic_2d (default) or _override_to_grid_tracks (override); legacy [override-warning] stderr removed for the 5 presets; step08 trace gains a 2-D-aware print line that fires before the dynamic_rows / dynamic_cols branches. - u5: PR 1 lock test test_top_1_bottom_2_fr_default_populates_geometry renamed to test_top_1_bottom_2_dynamic_2d_populates_geometry and flipped to PR 2 reality (computation="2d_dynamic_aggregated", dynamic_rows=True, dynamic_cols=True). Fixtures: 10 build_layout_css (5 presets × {default, override}) + 5 retry_gate *_dynamic_2d.yaml locking the retry gate skip reason "dynamic_cols (2-D topology) ... IMP-09 lock" for the 5 presets. Tests: python -m pytest -q tests = 104 passed (Stage 2 baseline 10 RED → GREEN, 0 regressions). Kei archive (build_containers_type_b / page_structure) untouched — rg "build_containers_type_b\|page_structure" src/phase_z2_pipeline.py returns 0 hits. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-17 18:51:23 +09:00
KyeongminandClaude Opus 4.7	201099e53b	feat(IMP-09): PR 1 — col-axis solver + per-zone geometry mapper + retry gate Stage 3 round 4 lock implementation: extend build_layout_css beyond the horizontal-2-only dynamic path. Every layout_css return now carries length-locked col-axis keys (widths_px, width_ratios, dynamic_cols) matching the parsed css_areas grid (R rows, C cols), so 2-D layouts (T / 2x2 in PR 2) and the unified _compute_per_zone_geometry mapper can plug in without further contract churn. PR 1 scope: - _parse_css_areas + _parse_fr_string + _compute_per_zone_geometry (unified — 1-D and 2-D from the same code path) - compute_zone_layout_cols (vertical-2 weight-only solver) - _build_fr_default / _build_rows_dynamic / _build_cols_dynamic (populate widths_px/heights_px on every return path) - build_layout_css override branch keeps the warn-and-fallthrough legacy for unsupported presets (PR 2 promotes to strict raise) - retry gate in _attempt_zone_ratio_retry skips when dynamic_cols=True or dynamic_rows=False, with explicit retry_skipped_reason - Step 8 artifact gains zone_widths_px_planned / zone_col_ratios_planned (top-level) + zone_width_px_planned / zone_col_ratio_planned (per-zone) - debug_zones width injection via _compute_per_zone_geometry (replaces the legacy row-only zip) Tests: tests/phase_z2/ — 47 new cases (parse / fr-string / cols solver / per-zone geometry / build_layout_css contract / retry gate + 6 build_layout_css YAML fixtures + 3 retry_gate fixtures). Verification: python -m pytest -q tests = 89 passed (was 42). horizontal-2 grid CSS strings (areas/cols/rows) byte-identical to legacy; only additive col-axis keys are introduced. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-16 12:03:23 +09:00
KyeongminandClaude Opus 4.7	8f6cffc2a7	fix(IMP-08): Stage 5 R2 — aligner force-drill on sub-id override targets Codex #1 (Stage 5) reproduced a smoke regression on the actual checkout : when V4 carries the parent exact key (e.g., `04-2`) AND the drag/drop override targets a sub-id (`primary=04-2-sub-1`), the aligner kept the parent at parent granularity and emit `['04-1', '04-2']`, so the override flag failed with `unknown section_id(s) ['04-2-sub-1']`. Fix : `align_sections_to_v4_granularity` gains an optional `override_target_section_ids` keyword. From each canonical `${parent}-sub-N` target it derives the parent id and adds it to a `force_drill_parents` set. Sections in that set are drilled into sub-sections regardless of whether V4 carries the parent exact key. Top-level override targets (no derived parent) do not trigger force-drill, so backward-compat is preserved for parent-granularity overrides. The call site in `run_phase_z2_mvp1` collects sub-ids from `override_section_assignments` and forwards them to the aligner. Generalization (RULE 0) : - Trigger is the override schema (`X-sub-N`), not a specific MDX / section / frame id. Applies to all 32-frame MDX uniformly. - Decision is deterministic on the override target shape, independent of V4 yaml content. - Default (no override) path is unchanged byte-for-byte. Side fixes (forward-only RULE 1 cleanup, no history rewrite) : - `align_sections_to_v4_granularity` docstring rewritten in English (overwrites the Korean docstring committed in `5191aca`). - Step 9 diagnostic comment quoted-string rewritten in English (overwrites `"V4 entry 없음"` committed in `a422d72`). Tests : 3 new cases in `test_phase_z2_subsection_schema.py` — `test_align_parent_v4_exact_keeps_section_when_no_override_targets_sub` (backward-compat axis), `test_align_force_drills_when_override_targets_sub_id_with_parent_in_v4` (blocker regression), `test_align_top_level_override_target_does_not_force_drill_other_sections` (force-drill scope guard). Pytest scope-qualified result : `test_phase_z2_subsection_schema.py` + `_section_assignment_override.py` + `_v4_fallback.py` = 40 / 40 PASS. Smoke (axis = sub-id override -> aligner -> assignment plan, both V4 yaml shapes) : - HEAD V4 yaml (`04-1`, `04-2.1`, `04-2.2` only) : `--override-section-assignment primary=04-2-sub-1` -> `aligned_section_ids=['04-1', '04-2-sub-1', '04-2-sub-2']`, `plan[0].assignment_source='cli_override'`, `plan[0].source_section_ids=['04-2-sub-1']`. - V4 yaml with `04-2` exact key (Codex's stress case) : identical aligned output and identical assignment plan. Downstream `composition_planner` abort (`phase_z_status_not_allowed:extract_matched_zone`) is IMP-05 territory, unchanged in both shapes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-16 02:28:46 +09:00