PHASE-Z-ROADMAP refactor — Codex 검토 안 + Step 22 정정

§1 상단에 lock phrase blockquote 추가:
  "현재 당장 할 일은 개발 진행이 아니라, 보고와 피드백을 위한
   PROCESS_OVERVIEW.html 프로토타입을 먼저 만드는 것이다."

§2 — 토픽별 6 영역 → axis 명 list (Step 5 보완 / 6-A / 7-conn /
     8-conn / Step 9 v0 / cleanup-1 / F29 / README / push 완료).
     CHANGE-LOG reference 로 추적성 확보.
§3 — Step 22 추정 % 20% → 10% (UI 미시작 정합).
     caveat 강화 (STATUS-BOARD 가 single source of truth 명시).
§4 — 큰 로드맵 7 단계 한 블록.
§5 — 우선순위 3 줄 분리 (1. 프로토타입 / 2. 보고 / 3. 복귀).
§6 — 보고용 프로토타입 계획 (포함 내용 / 목적) 별도 섹션.
§7 — Pipeline 복귀 후 Todo (MDX04 / 시각 점검 확장 / 어댑터 /
     MDX 정규화 / Step 21 / MDX01 02 검증) 별도 섹션.
§8 — 문서 역할 분담 표 (README / OVERVIEW / STATUS-BOARD /
     CHANGE-LOG / ROADMAP / PROCESS_OVERVIEW 6 문서).

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

docs/architecture/PHASE-Z-ROADMAP.md

@@ -1,100 +1,54 @@
-# Phase Z 진행 현황 및 향후 Todo
+# Phase Z Roadmap
 
-**문서 성격**: 진행 계획 + 당장 할 일 + 세부 todo. *자주 갱신*.
+**문서 성격**: 앞으로의 진행 순서 + 큰 axis + 우선순위. *자주 갱신*.
 **작성일**: 2026-05-08
-**역할 분담**: 본 문서는 *진행 계획*. 정확한 단계별 상태는 [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md), 결정 변경 이력은 [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md), 22 단계 도면은 [`PHASE-Z-PIPELINE-OVERVIEW.md`](PHASE-Z-PIPELINE-OVERVIEW.md).
+**문서 역할 분담**: 본 문서는 *진행 계획*. 정확한 단계별 상태는 [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md), 결정 변경 이력은 [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md), 22 단계 도면은 [`PHASE-Z-PIPELINE-OVERVIEW.md`](PHASE-Z-PIPELINE-OVERVIEW.md).
+
+> **현재 당장 할 일은 개발 진행이 아니라, 보고와 피드백을 위한 `PROCESS_OVERVIEW.html` 프로토타입을 먼저 만드는 것이다.**
 
 ---
 
 ## 1. 현재 위치
 
-Design Agent 는 MDX 문서를 입력받아 프레젠테이션 슬라이드 HTML 로 자동 변환하는 Phase Z 파이프라인을 구축 중. 현재까지는 MDX03 을 기준으로 22 단계 파이프라인의 정상 경로를 검증함.
+- MDX03 정상 경로 통과 (PASS)
+- Phase Z 22 단계 파이프라인 일반화 진행 중
+- 보고용 프로토타입을 먼저 작성 예정
 
-### 1.1 MDX03 현재 결과
+### MDX03 결과 요약
 
 - V4 rank-1 frame 적용 완료
   - `03-1 → F13 / three_parallel_requirements` (그대로 사용 가능, 0.927)
   - `03-2 → F29 / process_product_two_way` (그대로 사용 가능, 0.920)
-- rank 2~6 후보는 Step 9 의 `application_plan` 에 보존 (향후 사용자 선택용)
+- rank 2~6 후보 Step 9 `application_plan` 에 보존
 - `final.html` / `preview.png` 생성
-- Step 14 시각 점검 통과 (visual_check_passed = true)
+- Step 14 시각 점검 통과 / Step 20 상태 통과
-- Step 20 슬라이드 상태 통과 (overall = PASS)
 - F29 missing asset bug 수정 완료
-- missing image count = 0
+- missing image count = 0 / full MDX coverage = true
-- full MDX coverage = true
-
-```
-MDX03 기준 자동 슬라이드 생성 정상 경로 통과
-다만 전체 22 단계 파이프라인은 일반화 단계이며, MDX01 / 02 / 04 등으로 검증을 확장해야 한다.
-```
 
 ---
 
-## 2. 지금까지 완료한 주요 작업
+## 2. 이번 session 에서 닫힌 작업
 
-### 2.1 Slide base / spacing / typography 정리
+이번 session 에서 closed 된 axis 목록:
 
-- slide canvas: 1280×720
+- Step 5 보완 — V4 rank-1 → non-reject 최대 6 개 후보 list
-- title / divider / body / footer 위치 정리
+- Step 6-A — `CompositionUnit` 에 `v4_candidates` 필드 추가 (additive, logic 무변)
-- body height: 585
+- Step 7-conn — `select_layout_candidates` artifact 연결
-- grid gap: 14
+- Step 8-conn — region / display candidates artifact 연결 (placeholder)
-- 5-layer typography 위계 정리 (대 16px / 소 12px / 콘텐츠 10px / ...)
+- Step 9 v0 — passive `application_plan` artifact (V4 후보 적용 계획 trace)
+- cleanup-1 — stale 주석 (`pipeline 호출처 X`) 정정
+- F29 visual fidelity 정정 — missing SVG → CSS gradient 재현
+- README 통합 갱신 — 한글 / 22-step Mermaid / 로드맵 Mermaid
+- push 완료 — origin (GitHub) + slide2 (Gitea)
 
-### 2.2 Layout 카탈로그 정리
+각 axis 상세 의사결정 / 폐기 / lock 은 [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md) 참조.
-
-코드 dict 에 박혀 있던 layout 을 사람이 보고 수정할 수 있는 yaml 카탈로그로 분리.
-
-- `templates/phase_z2/layouts/layouts.yaml` (8 개 preset)
-- `templates/phase_z2/layouts/layouts_preview.html`
-- 추가 함수: `select_layout_candidates(unit_count)`
-
-8 개 layout: `single` / `horizontal-2` / `vertical-2` / `top-1-bottom-2` / `top-2-bottom-1` / `left-1-right-2` / `left-2-right-1` / `grid-2x2`
-
-### 2.3 Region / Internal Region 카탈로그 정리
-
-zone 안의 콘텐츠 배치 단위 (Internal Region) + 콘텐츠 표시 정책 (display strategy) 을 분리.
-
-- `templates/phase_z2/regions/region_layouts.yaml` (6 개)
-- `templates/phase_z2/regions/display_strategies.yaml` (4 개)
-- `templates/phase_z2/regions/regions_preview.html`
-
-핵심 원칙:
-- **region_layout** = zone 내부 구조
-- **display_strategy** = 콘텐츠 처리 정책
-- `dropped` 는 decorative 요소에만 허용
-- text / table / image / details 는 dropped 절대 금지
-
-### 2.4 V4 후보 보존
-
-기존: V4 rank-1 만 파이프라인에 들어옴 → rank 2~6 사라짐.
-현재:
-- rank-1 은 렌더에 사용 (정책 무변)
-- non-reject 최대 6 개 후보 보존
-- Step 9 의 application_plan 에 모든 후보 기록
-
-### 2.5 Step 9 application_plan v0
-
-Step 9 를 *frame 재평가* 가 아니라 *V4 후보를 어떻게 적용할지 번역* 으로 재정의.
-
-V4 라벨 → 적용 방식 변환:
-- `그대로 사용` → 바로 삽입
-- `가벼운 편집` → 같은 프레임에 약간 조정
-- `재구성` → 레이아웃 / Region 변경 (자동 X, 사람 확인)
-- `거절` → 제외
-
-### 2.6 F29 시각 fidelity 정정
-
-F29 partial 이 *존재하지 않는* SVG asset 3 개를 참조하던 문제 수정.
-
-- 수정 전: `header_left_bg.svg` / `header_right_bg.svg` / `body_bg.svg` 참조 (모두 없음)
-- 수정 후: 원본 Figma HTML 처럼 CSS gradient 로 재현
-- missing image 0 확인
 
 ---
 
 ## 3. 현재 22 단계 진행 수준
 
-> ⚠️ 아래 % 는 *추정치*. 정확한 ✅ / ⚠ / ❌ 상태는 [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md) 가 단일 출처.
+> 아래 수치는 MDX03 정상 경로 기준의 *추정 진행률*이다.
+> 22 단계별 공식 상태는 [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md) 를 *single source of truth* 로 한다.
 
 | Step | 단계 | 추정 % |
 |---|---|---|
@@ -107,7 +61,7 @@ F29 partial 이 *존재하지 않는* SVG asset 3 개를 참조하던 문제 수
 | 6 | 구성 계획 | 80% |
 | 7 | 슬라이드 레이아웃 계획 | 85% |
 | 8 | Zone / Region 비율 계획 | 75% |
-| 9 | 적용 계획 (application_plan) | 70% |
+| 9 | 적용 계획 (`application_plan`) | 70% |
 | 10 | 프레임 컨트랙트 확인 | 65% |
 | 11 | 슬롯 매핑 | 45% |
 | 12 | 슬롯 데이터 생성 | 85% |
@@ -120,7 +74,7 @@ F29 partial 이 *존재하지 않는* SVG asset 3 개를 참조하던 문제 수
 | 19 | 다음 조치 제안 | 60% |
 | 20 | 슬라이드 상태 결정 | 95% |
 | 21 | 디버그 / 추적 기록 | 45% |
-| 22 | 사용자 확인 / 내보내기 | 20% |
+| 22 | 사용자 확인 / 내보내기 | 10% |
 
 전체 요약:
 - MDX03 정상 경로 = 완료
@@ -129,173 +83,78 @@ F29 partial 이 *존재하지 않는* SVG asset 3 개를 참조하던 문제 수
 
 ---
 
-## 4. 앞으로의 큰 로드맵
+## 4. 큰 로드맵
-
-전체 방향은 다음 순서로 간다 (자세한 단계별 설명은 [`README.md`](../../README.md) §4 참조):
 
 ```
 1. 22 단계 파이프라인 안정화 (현재)
-2. Phase Q 재검토 후 Phase Z 반영
+2. Phase Q 재검토 후 Phase Z 반영 (audit & salvage)
-3. AI 보정 / 재구성 단계
+3. AI 보정 / 재구성 단계 (AI Repair / Restructure)
 4. DB / 카탈로그 정리
 5. 프론트엔드 연결
 6. HTML 수정 기능 추가
 7. 프레임 지속 업데이트
 ```
 
-샘플 MDX (03 / 04 / 01 / 02) 는 *로드맵 단계 X* — *22 단계 보완용 검증 재료*.
+자세한 단계별 설명은 [`README.md`](../../README.md) §4 참조. 샘플 MDX (03 / 04 / 01 / 02) 는 *로드맵 단계 X* — *22 단계 보완용 검증 재료*.
 
 ---
 
-## 5. 세부 Todo
+## 5. 우선순위
 
-### 5.1 보고용 프로토타입 작성 — 우선 진행
+```
+1. 보고용 HTML 프로토타입 작성        ← 지금 당장 할 일
+2. 보고 / 피드백 수집
+3. Phase Z 파이프라인 작업 복귀 (22 단계 정리 계속)
+```
 
-현재 가장 먼저 할 일은 *실제 개발 진행이 아니라*, 보고와 피드백을 위한 프로토타입 작성.
+---
+
+## 6. 보고용 프로토타입 계획
+
+**파일**: `PROCESS_OVERVIEW.html` (기존 갱신) 또는 `PHASE_Z_REPORT_PROTOTYPE.html` (신규).
+
+**포함할 내용**:
+- 프로젝트 개요
+- MDX03 실제 결과 (`preview.png` / `final.html` / PASS status)
+- 22 단계 파이프라인 타임라인
+- V4 rank 후보 예시 (1~6 위)
+- Layout / Region / Frame 설명
+- Step 9 `application_plan` 예시
+- 아직 미구현인 기능 (HTML 수정 / 이미지 크기 조정 / AI 보정 / DB / 프론트 에디터)
+- 향후 로드맵 (큰 7 단계)
 
 **목적**:
-- 현재 파이프라인이 어떤 구조인지 설명
+- 현재 파이프라인 구조 설명
-- MDX03 결과를 시각적으로 보여줌
+- MDX03 결과 시각적으로 보여줌
-- 22 단계 흐름 설명
+- 미구현 영역 명확히 표시
-- layout / region / frame / application_plan 개념 설명
-- 아직 미구현인 부분 명확히 표시
 - 향후 front / AI / DB / editor 방향에 대한 피드백 수집
 
-**보고용 프로토타입에 포함할 내용**:
+---
-- 프로젝트 개요
-- MDX03 실제 결과 (preview.png / final.html / PASS status)
-- 22 단계 파이프라인 타임라인
-- V4 rank 후보 예시
-- Layout / Region / Frame 설명
-- Step 9 application_plan 예시
-- 아직 미구현인 기능 (HTML 수정 / 이미지 크기 조정 / AI 보정 / DB / 프론트 에디터)
-- 향후 로드맵
 
-**프로토타입 후보 파일**:
+## 7. Pipeline 복귀 후 Todo
-- `PROCESS_OVERVIEW.html` (기존 파일 갱신)
-- 또는 `PHASE_Z_REPORT_PROTOTYPE.html` (신규)
 
-### 5.2 22 단계 파이프라인 정리 (보고 이후 복귀)
+보고 / 피드백 수집 후 22 단계 안정화 작업 재개. 우선순위 후보:
 
-주요 작업:
+- **MDX04 검증** — `samples/mdx_batch/04.mdx` fresh run → status / rank-1 frame / 미연결 여부 확인
-- 프레임 ↔ Phase Z 연결 구조 정리 (V4 frame 후보 → Phase Z 렌더 경로 연결 확장)
+- **시각 점검 확장** (Step 14 보강) — 누락 이미지 / 표 잘림 / 비율 어긋남 / 빈 공간 검사
-- 시각 점검 범위 확장 (누락 이미지 / 표 잘림 / 비율 어긋남 / 빈 공간 검사)
+- **프레임 어댑터 확장** — Figma / V4 에는 있지만 Phase Z 에 미연결인 frame 의 contract / partial / builder 추가
-- MDX 정규화 / 정리 방식 보완 (Step 2 / 3 / 4)
+- **MDX 정규화 보강** (Step 2 / 3 / 4) — Content Object 추출 + Internal Composition Planning 활성화
-- MDX 01 / 02 / 04 검증을 통한 예외 케이스 보완
+- **Step 21 디버그 추적 보강** — schema 채우기 (현재 빈 상태)
-- Step 21 디버그 추적 보강
+- **MDX01 / 02 검증** — 다른 sample 로 일반화 확장
 
-### 5.3 Phase Q 재검토 및 반영
+이 후 단계 = 큰 로드맵의 §2 ~ §7 (Phase Q audit → AI repair → DB → 프론트 → HTML 수정 → frame 지속).
-
-기존 `src/` 안 옛 25 개 모듈 검토.
-
-분류 기준:
-- **keep as-is** — 다른 곳에서 사용 중
-- **migrate to Phase Z** — 도메인 가치 있음, Phase Z 로 이식
-- **reference only** — 학습 자료로만 보존
-- **delete** — 완전 obsolete
-
-검토 후보 (도메인 가치 추정):
-- `slide_measurer.py` — Selenium 측정 정밀도 (현재 Phase Z 보다 정교할 가능성)
-- `space_allocator.py` — zone 분배 로직
-- `content_editor.py` — AI 콘텐츠 편집 (fallback path 영역)
-- `content_verifier.py` — 콘텐츠 검증
-- `fit_verifier.py` — fit 평가 (Phase Z router 와 다른 시각)
-- `block_reference.py` — block reference 시스템
-
-### 5.4 AI 보정 / 재구성 단계
-
-대상 케이스:
-- V4 점수가 낮은 경우
-- 후보가 모두 거절인 경우
-- 가벼운 편집 필요
-- 재구성 필요
-- 오버플로우 반복
-- 그대로 frame 에 넣기 어려운 경우
-
-원칙:
-- MDX 원문 보존
-- AI 는 *삭제가 아니라* 재구성 / slot 재배치 / popup 전환 제안
-- 자동 적용 가능 여부와 사람 확인 필요 여부를 추적에 기록
-
-### 5.5 DB / 카탈로그 정리
-
-현재는 파일 기반. 향후 DB 화 대상:
-- 프레임 카탈로그 / 컨트랙트
-- 레이아웃 카탈로그
-- region / display 카탈로그
-- V4 결과
-- 실행 이력
-- 단계별 산출물
-- 사용자 변경 이력
-- 선택 이력 (어떤 후보를 골랐는지)
-
-### 5.6 프론트엔드 연결
-
-프론트 위치: `D:\ad-hoc\kei\design_agent_front\design-agent`
-
-초기 목표는 *editor 가 아니라 read-only viewer*.
-
-1 차로 보여줄 것:
-- 실행 목록
-- preview.png / final.html
-- 22 단계 타임라인
-- V4 1~6 위 후보
-- 레이아웃 / Region / 적용 계획
-- 시각 점검 결과
-- 최종 상태
-
-### 5.7 HTML 수정 기능
-
-프론트 연결 이후 editor 기능 추가.
-
-기능:
-- 텍스트 수정
-- 이미지 크기 / 위치 조정
-- 프레임 후보 변경 (V4 1 위 외 다른 위 선택)
-- 레이아웃 / Region 조정
-- 팝업 / 자세히보기 선택
-- 내보내기
-
-원칙:
-- `final.html` 직접 영구 수정 X
-- `user_overrides.json` 형태로 저장
-- MDX 원문 보존
-
-### 5.8 프레임 지속 업데이트
-
-Figma 와 V4 에는 있으나 Phase Z 런타임에 연결되지 않은 프레임을 계속 어댑터로 연결.
-
-프레임 하나당 필요한 작업:
-1. `templates/phase_z2/catalog/frame_contracts.yaml` (컨트랙트 entry)
-2. `templates/phase_z2/families/{template_id}.html` (Phase Z 런타임 partial)
-3. `src/phase_z2_mapper.py` (PAYLOAD_BUILDERS / ITEM_PARSERS entry)
-4. fresh run 검증
 
 ---
 
-## 6. 당장 실행 순서
+## 8. 문서 역할 분담
-
-```
-1. 보고용 프로토타입 작성        ← 지금 당장 할 일
-2. 보고 / 피드백 수집
-3. Phase Z 파이프라인 작업 복귀
-4. 22 단계 정리 계속
-5. 이후 Phase Q 검토 → AI → DB → 프론트 → 에디터 순서로 확장
-```
-
----
-
-## 7. 문서 역할 분담
-
-본 프로젝트의 문서들은 다음과 같이 책임이 분리됨:
 
 | 문서 | 역할 | 갱신 빈도 |
 |---|---|---|
-| [`README.md`](../../README.md) | 프로젝트 개요 + 22 단계 / 로드맵 / 운영 원칙 | 가끔 (큰 방향 변경 시) |
+| [`README.md`](../../README.md) | 외부 / 내부 공유용 프로젝트 개요 | 가끔 (큰 방향 변경 시) |
 | [`PHASE-Z-PIPELINE-OVERVIEW.md`](PHASE-Z-PIPELINE-OVERVIEW.md) | 22 단계 도면 (구조 잠금) | 거의 안 바뀜 |
-| [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md) | 각 단계의 정확한 상태 (✅ / ⚠ / ❌) | 자주 |
+| [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md) | 22 단계별 현재 상태의 single source of truth | 자주 |
-| [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md) | 결정 변경 이력 (axis 단위, 시간 순) | 작업 단위 |
+| [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md) | 의사결정 변경 이력 (axis 단위, 시간 순) | 작업 단위 |
-| **`PHASE-Z-ROADMAP.md`** (본 문서) | **진행 계획 + 당장 할 일 + 세부 todo** | **자주** |
+| **`PHASE-Z-ROADMAP.md`** (본 문서) | **앞으로의 진행 순서 / 큰 axis / 우선순위** | **자주** |
-| `PROCESS_OVERVIEW.html` (또는 `PHASE_Z_REPORT_PROTOTYPE.html`) | 보고용 시각 자료 | 보고 시점 |
+| `PROCESS_OVERVIEW.html` | 보고 / 피드백용 시각 프로토타입 | 보고 시점 |
 
 각 문서가 자기 역할만 하면 drift / 중복 / outdated 방지.