WIP on main: 1f7579c Phase W + V' 완료: before→filled→after 파이프라인 + 조립 로직 수정

PHASE-X.md

@@ -1,39 +1,189 @@
-# Phase X: 콘텐츠 기반 레이아웃 판단 프로세스
+# Phase X: 템플릿 기반 동적 레이아웃
+
+> 작성일: 2026-04-06
+> 상태: 계획 수립
+
+---
 
 ## 배경
 
-현재 파이프라인은 Kei의 role 태그(`reference`, `flow` 등)로 레이아웃 preset을 **먼저 고정**한 뒤, 그 안에서만 크기를 조정한다. 콘텐츠의 양이나 특성과 무관하게 구조가 결정되므로, 다른 MDX가 들어오면 커버되지 않는다.
+현재 파이프라인은 모든 MDX를 "배경/본심/첨부/결론" 4칸에 억지로 끼워넣는다.
+배경이 없는 콘텐츠도 배경을 만들어내고, 3분할이 적절한 콘텐츠도 2분할로 넣는다.
+Kei가 내용을 잘못 파악한 게 아니라, **"4칸을 채워라"는 지시가 잘못**된 것이다.
 
-## 현재 프로세스 (문제)
+## 핵심 아이디어
+
+**미리 정의된 레이아웃 템플릿 중 Kei가 콘텐츠에 맞는 것을 선택한다.**
+
+- Kei가 자유롭게 구조를 만드는 것이 아님 (불안정)
+- 옵션을 주고 고르게 함 (안정적)
+- 하드코딩 아님 — 어떤 MDX가 와도 적절한 템플릿이 선택됨
+
+## 고정 영역
+
+모든 템플릿 공통:
+- **상단**: 슬라이드 제목 헤더 (항상 존재)
+- **하단**: 결론 footer (항상 존재)
+- **중간**: 템플릿에 따라 달라지는 영역
+
+## 중간 영역 템플릿 옵션
+
+### A. body + sidebar
+```
+┌──────────┬─────┐
+│ 본심1    │참조  │
+│ 본심2    │     │
+└──────────┴─────┘
+```
+적합: 참조자료(용어 정의 등)가 별도로 있는 콘텐츠
+예시: 01번 MDX (DX/BIM 용어 정립)
+
+### B. 상단 wide + 하단 2분할
+```
+┌─────────────────┐
+│ 강조/핵심        │
+├────────┬────────┤
+│ 항목1  │ 항목2   │
+└────────┴────────┘
+```
+적합: 핵심 1개 + 두 가지 측면 비교/설명
+예시: 03번 MDX (필수요건 + 과정혁신/결과변화)
+
+### C. 상단 wide + 하단 3분할
+```
+┌─────────────────┐
+│ 강조/핵심        │
+├─────┬─────┬─────┤
+│항목1│항목2│항목3 │
+└─────┴─────┴─────┘
+```
+적합: 핵심 1개 + 세 가지 항목 병렬
+예시: 02번 MDX (궁극적 목표 + 발주처/설계사/시공사)
+
+### D. 2분할 (좌우 대등)
+```
+┌────────┬────────┐
+│ 항목1  │ 항목2   │
+│        │        │
+└────────┴────────┘
+```
+적합: 두 가지 비교/대비
+
+### E. 단일 전체
+```
+┌─────────────────┐
+│                 │
+│ 본심 (전체)      │
+│                 │
+└─────────────────┘
+```
+적합: 하나의 흐름, 분할 불필요
+
+### F. 상단 wide + 하단 2분할 + 보조 sidebar
+```
+┌─────────────┬───┐
+│ 강조/핵심   │참조│
+├──────┬──────┤   │
+│항목1 │항목2 │   │
+└──────┴──────┴───┘
+```
+적합: B + sidebar 조합
+
+---
+
+## 프로세스
 
 ```
-Kei role 태그 → select_preset() → 레이아웃 고정 → 그 안에서 weight 배분
+1. Kei가 MDX 원본을 읽고 내용 분석
+   → 핵심 메시지, 콘텐츠 구조 파악
+
+2. Kei가 꼭지를 나눔 (개수와 역할명 자유)
+   → "핵심목표 1개, 주체별 기대효과 3개, 결론 1개"
+   → 역할명: 고정 4칸 아님. 콘텐츠에 맞는 이름 사용
+
+3. Kei가 템플릿 선택
+   → "꼭지 구조를 보니 C템플릿이 맞다"
+   → 옵션 A~F 중 하나
+
+4. Kei가 각 영역에 꼭지 배정 + weight
+   → 상단: 핵심목표(0.3)
+   → 하단좌: 발주처(0.2), 하단중: 설계사(0.2), 하단우: 시공사(0.2)
+   → footer: 결론(0.1)
+
+5. 파이프라인이 템플릿대로 컨테이너 생성 → BEFORE
+
+6. 콘텐츠 채움 → 측정 → 재배분 → FILLED → AFTER
+
+7. 조립 → code_assembled / final
 ```
 
-- `reference` 있으면 → `sidebar-right` (무조건)
-- 콘텐츠 양/특성 기반 판단 없음
-- 레이아웃이 콘텐츠에 맞는지 검증 없음
+---
 
-## 목표 프로세스
+## 작업 리스트
 
-```
-1. BEFORE: 100% 공간을 weight 비율로 세로 배정 (레이아웃 판단 없음)
-2. FILLED: 콘텐츠 채움
-3. 판단1: 측정 → 레이아웃 결정 ("이 역할은 옆으로 빼는 게 낫다" 등)
-4. 판단2: 결정된 레이아웃에서 크기 재배분
-5. AFTER: 최종 레이아웃 + 크기
-```
+### X-1: 템플릿 정의
+- 옵션 A~F의 구체적 컨테이너 구조 정의
+- 각 옵션의 zone 이름, 비율 계산 공식, 좌표 계산 로직
+- `src/design_director.py`에 `LAYOUT_TEMPLATES` 정의
+- 하드코딩 아님: 템플릿은 구조만 정의, 크기는 weight와 슬라이드 크기에서 동적 계산
 
-- 레이아웃 구조(body/sidebar 등)가 preset이 아니라 **측정 후 판단의 결과**
-- 어떤 MDX가 와도 콘텐츠에 맞는 최적 레이아웃이 동적으로 결정됨
+### X-2: Kei 프롬프트 수정
+- `KEI_PROMPT`에 템플릿 A~F 옵션 제시
+- Kei가 콘텐츠를 보고 `layout: "C"` 선택
+- page_structure의 역할명이 자유 (배경/본심 고정 아님)
+- 각 역할에 zone 배정 (상단/하단좌/하단우 등)
+- 하드코딩 아님: Kei가 콘텐츠마다 다른 선택을 함
 
-## 관련 코드
+### X-3: space_allocator 템플릿 기반 컨테이너 생성
+- 선택된 템플릿에 따라 컨테이너 좌표/크기 생성
+- weight 비율로 각 영역 크기 결정
+- `select_preset()` → `build_layout_from_template()`
+- 하드코딩 아님: 템플릿 구조 + weight + 슬라이드 크기로 동적 계산
 
-- `src/design_director.py`: `LAYOUT_PRESETS`, `select_preset()`
-- `src/pipeline.py`: Stage 1.5a에서 preset 선택
-- `src/kei_client.py`: Stage 1A에서 role 태그 부여
-- `src/space_allocator.py`: zone 기반 컨테이너 배분
+### X-4: block_assembler / assemble_stage2 동적 역할
+- `["배경", "본심", "첨부", "결론"]` 고정 루프 → `page_structure.keys()` 동적 루프
+- 좌표 계산은 X-3에서 생성한 컨테이너 정보 사용
+- 색상/폰트: 역할 수에 맞게 동적 배분
+- 하드코딩 아님: 역할 수가 3개든 5개든 동작
 
-## 상태
+### X-5: 나머지 파일 동적화
+- step_visualizer: before/after 시각화에서 동적 역할 루프
+- fit_verifier: 4역할 고정 → 동적 역할
+- html_generator: Sonnet에게 동적 영역 수만큼 생성 요청
+- renderer: 동적 grid-template 생성
+- 하드코딩 아님: 모두 ctx.containers.keys() 기반
 
-Phase W (before→filled→after 파이프라인) 완료 후 착수.
+### X-6: 검증
+- 01번 MDX → A템플릿 → 기존과 동일하거나 더 나은 결과
+- 02번 MDX → C템플릿 → 상단 강조 + 하단 3분할
+- 03번 MDX → B템플릿 → 상단 요건 + 하단 2분할
+- 텍스트가 컨테이너 안에 있음
+- 공란 최소
+- 01번이 깨지면 롤백
+
+---
+
+## 주의사항
+
+- 하드코딩 절대 금지: 특정 MDX에만 동작하는 코드 없음
+- 01번 보호: Phase X 전에 git commit 완료 (1f7579c). 깨지면 롤백
+- 점진적 진행: X-1 → X-2 후 Kei 응답 확인 → X-3~X-5 순차 진행
+- 각 단계마다 검증
+
+---
+
+## 관련 코드 (고정 역할 참조 현황)
+
+| 파일 | 참조 수 | 수정 범위 |
+|------|---------|----------|
+| src/html_generator.py | 54건 | X-5 |
+| src/step_visualizer.py | 32건 | X-5 |
+| src/space_allocator.py | 26건 | X-3 |
+| scripts/assemble_stage2.py | 26건 | X-4 |
+| src/kei_client.py | 18건 | X-2 |
+| src/block_assembler.py | 17건 | X-4 |
+| src/fit_verifier.py | 16건 | X-5 |
+| src/pipeline.py | 15건 | X-3~X-5 |
+| src/renderer.py | 7건 | X-5 |
+| src/pipeline_context.py | 4건 | 필요 시 |
+| **합계** | **215건** | |