wip: phase_z2 evidence 파이프라인 + matching 실험(phase2~26) + 프론트 trace 패널 진행분 스냅샷

- src: phase_z2 composition/mapper/pipeline/placement_planner/retry, ai_fallback(prompts/schema/validate), mdx_text_atoms 신규
- Front: PipelineTracePanel 신규, FramePanel/SlideCanvas/Home/designAgentApi 등 갱신 + 테스트 4종 추가
- templates/phase_z2: catalog(component_expansion_registry, node_slot_mapping 신규), frames, families, slide_base 갱신
- tests/matching: phase2~26 매칭 실험 스크립트·리포트·온톨로지 전체 (미커밋 진행분)
- tests: b4_v4 evidence, task5~28.5 시리즈, regression(imp95 baseline) 등 신규 테스트 대량 추가
- docs/reference: MDX 구조 인벤토리, MDX→Frame 구조 계약 문서
- scripts: mdx 계약/parity/coverage/viewport 체크, gitea comment, run sync 유틸
- .gitignore: tmp*.json, chromedriver, .orchestrator, *.pkl, Front_test* 등 임시/스냅샷 제외

미완성 작업의 보존용 스냅샷 커밋 (2026-07-02)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tests/matching/phase3.py

@@ -0,0 +1,134 @@
+"""Phase 3: 9개 방법 × 17 유닛 매트릭스 (의미 매칭 5개 family 비교)
+- 키워드 (3): TF-IDF, Char n-gram, Kiwi+BM25
+- 구조 (1): 구조 메타데이터
+- 의미 (5): SBERT / KoSimCSE / E5 / Cross-encoder / Word-avg
+"""
+import sys
+import json
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from common import load_figma_texts
+from extract_units import extract_units
+from methods import (
+    method_tfidf, method_char_ngram, method_kiwi_bm25,
+    method_structural,
+    method_sbert_sentence,
+    method_kosimcse, method_e5, method_cross_encoder, method_wordavg,
+)
+
+ROOT = Path(r"d:\ad-hoc\kei\design_agent")
+PREVIEW_DIR = ROOT / "data" / "figma_previews"
+
+UNIT_ORDER = [
+    ("MDX01-intro", "중목차 앞 본문"),
+    ("MDX01-intro-details", "팝업"),
+    ("MDX01-1", "중목차"),
+    ("MDX01-2", "중목차"),
+    ("MDX01-2-image", "이미지"),
+    ("MDX01-2-details", "팝업+표"),
+    ("MDX02-1", "중목차"),
+    ("MDX02-1-image", "이미지"),
+    ("MDX02-2", "중목차(컨테이너)"),
+    ("MDX02-2.1", "소목차"),
+    ("MDX02-2.2", "소목차"),
+    ("MDX02-2.2-table", "표"),
+    ("MDX03-1", "중목차"),
+    ("MDX03-2", "중목차(컨테이너)"),
+    ("MDX03-2.1", "소목차"),
+    ("MDX03-2.1-table", "표"),
+    ("MDX03-2.2", "소목차"),
+]
+
+
+def fmt_score(score, method_name):
+    # 모두 [0,1] 범위이므로 % 표기
+    return f"{score * 100:.0f}%"
+
+
+def main():
+    units = extract_units()
+    figma = load_figma_texts()
+
+    with open(PREVIEW_DIR / "index.json", encoding="utf-8") as f:
+        idx_data = json.load(f)
+    frame_to_short = {info["frame_id"]: sid for sid, info in idx_data.items()}
+
+    methods_def = [
+        ("TF-IDF", method_tfidf),
+        ("Char-ngram", method_char_ngram),
+        ("Kiwi+BM25", method_kiwi_bm25),
+        ("Structural", method_structural),
+        ("SBERT", method_sbert_sentence),
+        ("KoSimCSE", method_kosimcse),
+        ("E5", method_e5),
+        ("Cross-encoder", method_cross_encoder),
+        ("Word-avg", method_wordavg),
+    ]
+
+    print("[Phase 3] 9개 방법 × 17 유닛 실행 시작...")
+    results = {}
+    for i, (uid, unit_text) in enumerate(units.items(), 1):
+        print(f"  [{i}/{len(units)}] {uid}")
+        results[uid] = {}
+        for mname, fn in methods_def:
+            if not unit_text.strip():
+                results[uid][mname] = []
+                continue
+            try:
+                ranked = fn(unit_text, figma)
+                results[uid][mname] = ranked[:3]
+            except Exception as e:
+                print(f"    ERROR {mname}: {e}")
+                results[uid][mname] = []
+
+    # 리포트
+    png_rel = "../../data/figma_previews/"
+    lines = []
+    lines.append("# Phase 3 — 9개 방법 매트릭스 (의미 매칭 5개 family 비교)")
+    lines.append("")
+    lines.append("3 카테고리: **키워드 (3) + 구조 (1) + 의미 (5 family)**")
+    lines.append("")
+    lines.append("### 의미 매칭 5 family")
+    lines.append("- **SBERT** (jhgan/ko-sroberta-multitask) — NLI+STS 학습, 한국어 기본")
+    lines.append("- **KoSimCSE** (BM-K/KoSimCSE-roberta-multitask) — 대조학습 기반 sentence embedding")
+    lines.append("- **E5** (intfloat/multilingual-e5-base) — 다국어 retrieval, query/passage 비대칭 prefix")
+    lines.append("- **Cross-encoder** (Dongjin-kr/ko-reranker) — 임베딩 X, 질의-문서 쌍 직접 채점")
+    lines.append("- **Word-avg** — 단어 임베딩 평균 (FastText 계열 baseline)")
+    lines.append("")
+
+    for i, (uid, kind) in enumerate(UNIT_ORDER, 1):
+        lines.append(f"---")
+        lines.append("")
+        lines.append(f"## {i}. {uid} ({kind})")
+        lines.append("")
+        lines.append("| 방법 | 1순위 | 2순위 | 3순위 |")
+        lines.append("|------|-------|-------|-------|")
+        for mname, _ in methods_def:
+            cells = [mname]
+            top3 = results[uid].get(mname, [])
+            if not top3:
+                cells += ["-", "-", "-"]
+            else:
+                for fid, score in top3:
+                    short = frame_to_short.get(str(fid), "?")
+                    info = idx_data.get(short, {})
+                    png_file = info.get("png", "")
+                    title = info.get("title_text", "").strip().replace("\n", " ") or ""
+                    if len(title) > 15:
+                        title = title[:15] + "…"
+                    cell = f"![{short}]({png_rel}{png_file})<br>**{short}** ({fmt_score(score, mname)})<br>{title}"
+                    cells.append(cell)
+                while len(cells) < 4:
+                    cells.append("-")
+            lines.append("| " + " | ".join(cells) + " |")
+        lines.append("")
+
+    out_path = Path(__file__).parent / "MATRIX_PHASE3.md"
+    out_path.write_text("\n".join(lines), encoding="utf-8")
+    print(f"\n완료: {out_path}")
+
+
+if __name__ == "__main__":
+    main()