docs + V4 catalog + samples + Phase Q legacy 보존

전체 26 files (20 추가 + 6 수정), 10507 insertions.

Phase Z 문서 :
- docs/architecture/PHASE-Z-CHANGE-LOG.md (신설) — axis-by-axis 의사결정 history
  (newest-on-top). Step 7-A 부터 6 entry 박힘 + 2026-05-08 / 2026-05-08 #2
  (compat 매트릭스 폐기 / 6-B 폐기 / F14 표현 정정 / label gate policy 분리).
- docs/architecture/PHASE-Z-PIPELINE-OVERVIEW.md (수정) — Step 5/6/9 Gap note
  append (구조 무변, append-only). 6-B 폐기 사실 + Refinement F.
- docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md (수정) — snapshot date
  2026-05-08 갱신. §3 핵심 missing item 5 (Step 5/6/9 boundary axis breakdown
  + 폐기 기록). §6 한 줄 갱신 — 다음 axis 후보 A~F.

Project root docs :
- PLAN.md / PROGRESS.md / README.md (수정) — 토큰 체계 / 폴더 구조 / 설계 문서 /
  역할 분리 반영.
- IMPROVEMENT-REDESIGN.md (신설) — Phase Z 설계 핵심 문서.
- PROCESS_OVERVIEW.html (신설) — 파이프라인 개요 시각.
- docs/tasks/* (신설) — Phase Z task 문서.

V4 catalog (Phase Z runtime 필수 의존성) :
- tests/matching/v4_full32_result.yaml (신설, 4888 줄) — V4 매칭 결과 32 frame
  × 10 MDX section. lookup_v4_match() / lookup_v4_candidates() 가 본 파일 read.
  Phase Z runtime 이 *없으면 즉시 abort* — clone 후 즉시 동작 가능 보장.

Samples :
- samples/mdx_batch/04.mdx (신설) — MDX04 기본 sample.
- samples/mdx/04. DX 지연 요인.mdx (신설) — MDX04 원본.

Phase Q legacy 보존 (별 axis "Phase Q audit & salvage" 영역) :
- src/block_matcher_tfidf.py / catalog_blocks.py / frame_extractor.py /
  pipeline_v2.py — Phase Q (옛 파이프라인) src 신규 untracked 파일들.
  Phase Z runtime 와 의존성 0. Phase Q audit axis 에서 검토 예정.
- scripts/eval_block_matcher.py / fetch_all_frame_screenshots.py /
  match_17_units_my_matcher.py / match_mdx_strict.py / match_mdx_to_frames_tfidf.py /
  ocr_augment_texts.py / run_pipeline_v2.py / previews/ — Phase Q 작업 시
  사용한 옛 script. 같이 보존.
- run_mdx03_pipeline.py (수정) — Phase Q 진입점 (no flag) + Phase Z 진입점
  (--phase-z2 flag) 동시 wrapper. Phase Z 만 사용 시 `python -m
  src.phase_z2_pipeline samples/mdx_batch/03.mdx <run_id>` 직접 호출.

비-scope :
- tests/matching/ (v4_full32_result.yaml 외 ~63MB) — V4 진화 history /
  reports / DECK / ATTACH. Phase Q audit axis 에서 검토.
- tests/pipeline/ (~15MB) — pipeline data. Phase Q audit 영역.
- templates/catalog/blocks.yaml — 옛 block catalog. Phase Q audit.
- templates/phase_z2/frames/ — 옛 frame partial 위치. Phase Q audit.

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

README.md

@@ -19,9 +19,12 @@ MDX 입력 → 정규화 → 꼭지 추출(AI) → zone 구분 → BEPs 매칭
 ### 구조
 
 - **slide-base:** 1280×720 슬라이드 프레임. 대목차 + 구분선 + 본문 영역 + 핵심 인사이트(footer)
-- **zone:** 본문 영역 안에서 중목차(##) 기준으로 나뉘는 영역 (top/bottom 등)
-- **블록:** zone 안에 들어가는 디자인 단위. Figma에서 추출한 BEPs 디자인을 HTML/CSS로 변환한 것
-- **catalog:** 블록의 메타 정보 (구조, 슬롯, 매칭 조건)
+- **레이아웃:** slide-body 안의 zone 분배 형태 (Type A/B/B'/B'')
+- **zone:** 레이아웃이 정한 콘텐츠 영역 (top/bottom 등)
+- **프레임 (구 "블록"):** zone 안에 들어가는 디자인 단위. Figma에서 추출한 BEPs 디자인을 HTML/CSS로 변환한 것
+- **catalog:** 프레임의 메타 정보 (구조, 슬롯, 매칭 조건)
+
+> ⚠️ Phase Z (2026-04-28) 부터 "블록" → "프레임" 으로 용어 통일. 기존 코드 (`block_reference.py`, `templates/blocks/`, `BLOCK-RULES.md` 등) 는 점진적 정리.
 
 ### 주요 파일
 
@@ -70,20 +73,32 @@ MDX 입력 → 정규화 → 꼭지 추출(AI) → zone 구분 → BEPs 매칭
 
 ### AS-IS → TO-BE
 
+> ⚠️ 아래 AS-IS / TO-BE 는 Phase Q ~ T 시점의 흐름. **현재 (Phase Z) 흐름은 [`IMPROVEMENT-REDESIGN.md`](IMPROVEMENT-REDESIGN.md)** 참조.
+
 ```
-AS-IS:
+AS-IS (Phase Q ~ T):
   AI가 먼저 꼭지를 추출하고
   → 매칭 블록이 있으면 삽입, 없으면 코드가 1회 고정 렌더
   → 빈 공간이 있어도 그냥 둠
   → 블록마다 font-size, color가 직접 박혀있어서 섞이면 위계 안 맞음
 
-TO-BE:
+TO-BE (Phase Q ~ T):
   중목차 기준으로 zone을 먼저 나누고
   → TF-IDF로 BEPs 매칭 시도
   → 매칭되면 블록 삽입 + 크기 조절 (direct-fit)
   → 안 되면 AI가 꼭지 정리 + 유사 디자인으로 redesign + 반복 조정 (recipe)
   → 빈 공간/overflow를 자동 재분배
   → 모든 블록이 토큰 기반이라 스타일 통일
+
+NEW (Phase Z, 2026-04-28 ~):
+  STAGE 1) MDX 분석 + 레이아웃 매칭 (Type A/B/B'/B'')
+  STAGE 2) Zone 별 텍스트 1차 배치
+  STAGE 3) Zone 별 프레임 매칭 — V1~V4 (완벽/어정쩡/안됨 분기)
+  STAGE 4) 프레임 검토 + 컨테이너 조정 (5차 Fallback)
+  STAGE 5) HTML 조립 (slide-base + Jinja2) + 검증 + 출력
+  ⭐ AI = zone 안 콘텐츠만 / HTML 구조 = 코드 (Jinja2)
+  ⭐ 자유 디자인 금지 — 프레임 DB 참고 필수
+  ⭐ MDX 원문 무손실 보존
 ```
 
 ---
@@ -97,21 +112,33 @@ TO-BE:
 | MDX 01 (Type A, sidebar 구조) | ✅ 완료 (개별) | 미연결 |
 | 토큰 기반 CSS 체계 | - | ✅ 정의 완료, slide-base 적용 |
 | Figma 블록 추출 | - | 진행 중 (`figma_to_html_agent/blocks/`) |
+| **매칭 시스템 (V1~V4)** | - | **✅ 별도 검증 완료** (`tests/`) — TARGET 3/4 |
+| **Phase Z 통합 설계** | - | **✅ 설계 완료** (`IMPROVEMENT-REDESIGN.md`) — 구현 대기 |
 
 ---
 
-## 다음 단계 방향
+## 다음 단계 방향 — Phase Z 매칭 시스템 통합
 
-| 순서 | 단계 | 내용 |
-|------|------|------|
-| 1 | 폴더 구조 정리 | structures/recipes/legacy 분리 |
-| 2 | 기존 블록 점진 전환 | 분류(direct-fit/recipe/rewrite) → 토큰 기반 전환 |
-| 3 | catalog 고도화 | 파일명 중심 → 속성 테이블 기반 매칭 |
-| 4 | 파이프라인 연결 | TF-IDF 매칭 + recipe/composition 경로 |
-| 5 | fit 루프 확장 | 빈 공간 재분배, preview 축약, 자동 조정 반복 |
-| 6 | 시각 품질 검증 | 정렬, 위계, 가독성 검증 강화 |
+상세: [IMPROVEMENT-REDESIGN.md](IMPROVEMENT-REDESIGN.md)
 
-상세: [IMPROVEMENT-PLAN.md](docs/architecture/IMPROVEMENT-PLAN.md)
+| 단계 | 내용 |
+|------|------|
+| Phase Z-1 | 통합 prototype — Stage 1.7 만 V4 로 교체, MDX 03 회귀 |
+| Phase Z-2 | 매칭 + 프리셋 (Type A/B/B'/B'') 통합 |
+| Phase Z-3 | 컨테이너 검증 + 5 차 Fallback |
+| Phase Z-4 | 전체 통합 + 검증 |
+
+**핵심 위계** (Phase Z 정리) :
+```
+slide → slide-base → slide-body → 레이아웃 → Zone → 프레임
+```
+
+**5 단계 새 흐름** :
+1. MDX 분석 + 레이아웃 매칭
+2. Zone 별 텍스트 배치
+3. Zone 별 프레임 매칭 (완벽 / 어정쩡 / 안 됨)
+4. 프레임 검토 + 컨테이너 조정
+5. HTML 조립 + 검증 + 출력
 
 ---
 
@@ -119,6 +146,13 @@ TO-BE:
 
 | 문서 | 내용 |
 |------|------|
-| [IMPROVEMENT-PLAN.md](docs/architecture/IMPROVEMENT-PLAN.md) | 개선 설계 (목표/방향/6단계 계획) |
-| [TOKENS-v1.md](docs/architecture/TOKENS-v1.md) | 토큰 위계 기준표 초안 |
-| [BLOCK-RULES.md](docs/architecture/BLOCK-RULES.md) | 블록 작성 규칙 (에이전트 간 계약서) |
+| [IMPROVEMENT-REDESIGN.md](IMPROVEMENT-REDESIGN.md) | **Phase Z 통합 설계** (위계 / 용어 / 5 단계 흐름) |
+| [docs/architecture/FRAME-INTEGRATION-MAP.md](docs/architecture/FRAME-INTEGRATION-MAP.md) | **32 frame Zone 적용 분류** (`zone_direct/adapt/extract/reference_only`) |
+| [docs/architecture/PHASE-Z-FRAME-STYLE-INVENTORY.md](docs/architecture/PHASE-Z-FRAME-STYLE-INVENTORY.md) | **Frame / Style / Token 인벤토리** (32 frame + 18 token + 6 legacy) |
+| [PROCESS_OVERVIEW.html](PROCESS_OVERVIEW.html) | 임원 보고용 A4 2 페이지 (프로세스 + 구조도) |
+| [tests/PIPELINE.md](tests/PIPELINE.md) | 매칭 시스템 (V1~V4) 통합 정리 |
+| [PROGRESS.md](PROGRESS.md) | 전체 Phase 이력 (Phase 1~T + R' + Z) |
+| [CLAUDE.md](CLAUDE.md) | 프로젝트 규칙 + Phase Z 위계 |
+| [IMPROVEMENT-PLAN.md](docs/architecture/IMPROVEMENT-PLAN.md) | 개선 설계 (이전 Phase Q 까지) |
+| [TOKENS-v1.md](docs/architecture/TOKENS-v1.md) | 토큰 위계 기준표 |
+| [BLOCK-RULES.md](docs/architecture/BLOCK-RULES.md) | 블록 작성 규칙 |