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/CURRENT_STATUS.md

@@ -0,0 +1,156 @@
+# 현재 상황 정리 (2026-04-24)
+
+MDX ↔ Figma frame 매칭. V1 완료, V2/V3/V4 는 아직 실행 전. 착수 전에 4가지만 확정하면 됨.
+
+---
+
+## 1. 현재 상태
+
+### 끝난 것
+- **V1 (키워드 baseline)** — 실행 완료
+  - 결과 YAML: [mdx_matching_result.yaml](mdx_matching_result.yaml)
+  - 리포트: [MDX_MATCHING_REPORT.html](MDX_MATCHING_REPORT.html)
+  - TARGET 4 전부 1위 일치 (01-2→18 / 02-2.2→14 / 03-1→13 / 03-2→29)
+  - Holdout 3 blind 결과 산출 (01-1→1 / 02-1→12 / 02-2.1→11)
+
+### 안 끝난 것
+- **V2 / V3 / V4** — 코드도 없고 실행도 안 됨. 지금까지는 설계/계획 단계
+- 옛 Phase 22~25 리포트(2026-04-22)는 옛 키워드 체계 기반 — 현재 V1~V4 비교 기준으로는 **사용하지 않음**. 과거 실험 기록 / 참고 자산으로 유지
+
+### 이미 확정된 것
+- Figma 구조 축은 기존 `structure_ontology.yaml` `templates_v1` 재사용 (새 AI 패스 없음)
+- V4 판정 라벨은 `use_as_is / light_edit / restructure / reject` (코드 실체 그대로)
+- 핵심 리포트 3개 고정 — `KEYWORD_INVENTORY` / `FRAME_KEYWORD_REVIEW` / `MDX_MATCHING_REPORT`
+- V1~V4 비교는 신규 HTML 금지 — `MDX_MATCHING_REPORT` 내부 섹션으로 통합
+
+### Holdout 5원칙 (잠금)
+1. TARGET 4 고정 (ANSWER_MAP 변경 금지)
+2. 기준 잠금 (전처리 / anchor / V1 가중치 변경 금지)
+3. Blind 실행 (01-1 / 02-1 / 02-2.1 expected frame 사전 미기재)
+4. Post-hoc 해석만
+5. Generalization-only (per-section 튜닝 금지)
+
+---
+
+## 2. 지금 확정해야 하는 것 (4개)
+
+V2/V3/V4 착수 **직전** 결정사항만 추림.
+
+### 2.1 옵션 A / B / C — 어떻게 돌릴지
+
+| | 내용 | 특징 |
+|---|---|---|
+| **A** | `keyword_base.yaml` 을 V1 corpus 기반으로 재생성 후 phase23~25 원본 그대로 실행 | 키워드 축이 V1 과 수학적으로 동일. 빌드 스크립트 1회 작업 필요 |
+| **B** | 옛 `keyword_base.yaml` 그대로 phase23~25 실행 | 즉시 실행. 하지만 V1 과 키워드 축 불일치 — V1⊂V2 아님 |
+| **C** | V1 결과를 baseline 으로 주입하고 의미/구조/판정 축을 Top-K rerank 로 얹음 | V1 후보 집합 위에서 V2/V3 재정렬, V4 판정 — V1 baseline 일관성 보장. 신규 스크립트 3개 |
+
+→ **권장: C**
+
+### 2.2 Top-K 의 K 값
+
+V1 에서 몇 위까지를 V2 후보로 넘길지. **Holdout 성적은 근거로 사용하지 않음** — 설계는 원칙 기반.
+- **K=3**: 엄격. rerank 축의 의미가 약해짐 (V1 이 사실상 단독 결정)
+- **K=5**: V1 필터 역할을 유지하면서 rerank 후보 폭을 확보하는 절충안
+- **K=8**: 느슨. V1 baseline filter 의미가 약해질 수 있음
+
+→ **권장: K=5**
+
+### 2.3 V3 구조 호환도 테이블
+
+- 기존 `_COMPAT` ([phase_common.py:221-299](phase_common.py)) 재사용
+- 또는 재설계
+
+→ **권장: 기존 재사용** (검증된 값 + 재설계 범위 불명확)
+
+### 2.4 V4 판정 threshold
+
+[template_fit.py:397-400](template_fit.py) 의 `0.90 / 0.75 / 0.60` 기본값 유지 여부.
+
+→ **권장: 기본값 유지** (Holdout 5원칙 #2 "기준 잠금" 과 정합)
+
+---
+
+## 3. 버전별 정의 (확정 전제)
+
+- **V1**: 키워드 3-layer 점수 (`0.30 × standalone + 0.50 × group + 0.20 × related`). 32 frame 전체 랭킹. **완료**
+- **V2**: V1 Top-K 를 **의미 유사도(ko-sroberta)** 로 재정렬. 모델 `jhgan/ko-sroberta-multitask`, MDX summary = title + 첫 문단 + slot labels
+- **V3**: V2 후보를 **MDX 구조(코드) × Figma 구조(기존 `templates_v1`)** 비교로 재정렬
+- **V4**: V3 후보를 template-fit-v1 로 **판정** — `use_as_is` / `light_edit` / `restructure` / `reject`
+
+V4 는 점수 랭킹이 아니라 **판정 라벨** 을 출력. 같은 1위라도 `reject` 면 실제 사용 불가.
+
+---
+
+## 4. 권장안 한 줄 요약
+
+**옵션 C + K=5 + `_COMPAT` 재사용 + threshold 기본값** 으로 확정 → V2 스크립트부터 착수.
+
+이 4개 모두 "예" 면 V2 작성 들어감. 하나라도 다르게 가고 싶으면 그것만 지정.
+
+---
+
+## 5. 착수 순서 (확정 후)
+
+1. `pipeline_08_v2_semantic_rerank.py` — V1 Top-5 × ko-sroberta rerank
+2. `pipeline_08_v3_structure_rerank.py` — MDX 구조 × Figma 구조 rerank (`_COMPAT` 기반)
+3. `pipeline_08_v4_template_fit_judgment.py` — template-fit-v1 판정 라벨
+4. TARGET 4 + Holdout 3 동일 입력으로 V1~V4 4회 실행 (lock_snapshot 동일)
+5. 결과를 [MDX_MATCHING_REPORT.html](MDX_MATCHING_REPORT.html) 내부 V1~V4 비교 섹션으로 통합
+
+---
+
+## 6. 핵심 산출물 (현재 존재하는 것만)
+
+| 파일 | 용도 |
+|---|---|
+| [pipeline_01_extract_nodes.py](pipeline_01_extract_nodes.py) | Figma `texts.md` + MDX 섹션 추출 |
+| [pipeline_04_normalize.py](pipeline_04_normalize.py) | Kiwi + user_dict + PRE_COLLAPSE + 필터 |
+| [keyword_normalizer.py](keyword_normalizer.py) | 공통 정규화 모듈 |
+| [pipeline_07_auto_anchor_candidates.py](pipeline_07_auto_anchor_candidates.py) | 3-layer anchor 결정론적 생성 |
+| [pipeline_06_2_mdx_matching.py](pipeline_06_2_mdx_matching.py) | V1 keyword matching |
+| [normalized_text_tokens.yaml](normalized_text_tokens.yaml) | 정규화 corpus (unique 1713) |
+| [auto_anchor_candidates.yaml](auto_anchor_candidates.yaml) | 3-layer anchor + provenance |
+| [mdx_matching_result.yaml](mdx_matching_result.yaml) | V1 결과 + lock_snapshot |
+
+### 기존 자산 (V2~V4 에서 재활용 대상)
+
+| 파일 | 용도 | V2~V4 역할 |
+|---|---|---|
+| [embeddings.py](embeddings.py) | ko-sroberta 로더 | V2 semantic rerank |
+| [detect_mdx.py](detect_mdx.py) | MDX 구조/summary 추출 (코드) | V2 summary + V3 MDX 구조 |
+| [phase_common.py](phase_common.py) `_COMPAT` | 구조 호환도 테이블 | V3 rerank |
+| [template_fit.py](template_fit.py) | template-fit-v1 판정 엔진 | V4 판정 |
+| [structure_ontology.yaml](structure_ontology.yaml) `templates_v1` | 32 frame AI 구조화 | V3 Figma 구조 입력 (고정 재사용) |
+
+---
+
+## 7. 규칙 (스스로 상기)
+
+- 결과물을 고치지 말고 프로세스를 고친다
+- 하드코딩 금지 (anchor / 점수 / blob)
+- **핵심 리포트 3개 고정 덮어쓰기** — `KEYWORD_INVENTORY` / `FRAME_KEYWORD_REVIEW` / `MDX_MATCHING_REPORT`
+- V1~V4 비교는 `MDX_MATCHING_REPORT` 안에 섹션으로 (신규 HTML 금지)
+- AI curator bias 재발 금지 — 통계/근거 없는 키워드 묶음 만들지 않기
+- `anchor_sets_input.yaml` 수동 재편집 금지 (Step 7 자동 산출 사용)
+- V2~V4 구현 시 **`template_fit.py` 라벨을 바꾸지 말 것** — `use_as_is / light_edit / restructure / reject` 그대로
+
+---
+
+## 8. 변경 이력
+
+- 2026-04-24 초판 — V1 완료 + V2~V4 재실행 계획 (가중합 표현)
+- 2026-04-24 교정 1 — 리포트 3개 정의 교정, `MATCHING_COMPARISON.html` 폐기, V2~V4 를 캐스케이드 rerank / 판정 으로 재정의
+- 2026-04-24 교정 2 — V4 라벨을 코드 실체(`template_fit.py`) 기준 `use_as_is / light_edit / restructure / reject` 로 통일, Figma 구조 입력은 `templates_v1` 고정 재사용으로 확정
+- 2026-04-24 교정 3 (현재):
+  1. Holdout 을 K 값 설계 근거처럼 읽히던 §2.2 문장 제거 — Holdout 5원칙 #4/#5 준수
+  2. "V1 ⊂ V2 ⊂ V3 ⊂ V4 집합 포함 보장" 표현 완화 — V4 는 판정이라 출력 타입이 다름
+  3. 옛 Phase 22~25 "폐기 대상" → "현재 비교 기준 미사용 / 참고 자산 유지"
+
+## 9. 지금 유지할 핵심 원칙
+
+- 키워드는 고정 baseline
+- 내용 / 구조 / 적용 가능성은 baseline 을 대체하지 않고 **그 위에 붙는 보강 신호**
+- MDX 구조는 코드가 파악
+- Figma 구조는 AI 가 파악한 결과(`templates_v1`) 를 고정 재사용
+- **Holdout 은 설계 보정이 아니라 일반화 검증용**
+- V4 는 점수 경쟁이 아니라 실제 사용 가능성 판정