C.E.L_Slide_test2/tests/matching/CURRENT_STATUS.md

# 현재 상황 정리 (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 는 점수 경쟁이 아니라 실제 사용 가능성 판정


---

## 10. 2026-07-02 재검증 (GitHub issue #4)

- `v4_full32_result.yaml` (2026-04-29 생성) 기준 **TARGET 4/4**:
  - 01-2→F18 (use_as_is 0.946) / 02-2.2→F14 (use_as_is 0.939) / 03-1→F13 (0.927) / 03-2→F29 (0.920)
- 02-2.2 "정답 F14 가 rank 7 / reject" 기록은 **V3 Top-5 한정 평가본(구 v4_template_fit_r2_result.yaml) 기준** — full32 평가 + anchor 재라벨링 반영 후 해소.
- Holdout all-reject (02-2.1 usable=0, 04-1 usable=0) 는 C1 catalog gap — Emergency P2/P3 의 ai_adaptation / generic_fallback 경로가 런타임에서 처리 (issue #9 검증 완료).