# Phase Z Roadmap

**문서 성격**: 앞으로의 진행 순서 + 큰 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).

> **현재 당장 할 일은 개발 진행이 아니라, 보고와 피드백을 위한 `PROCESS_OVERVIEW.html` 프로토타입을 먼저 만드는 것이다.**

---

## 1. 현재 위치

- MDX03 정상 경로 통과 (PASS)
- Phase Z 22 단계 파이프라인 일반화 진행 중
- 보고용 프로토타입을 먼저 작성 예정

### 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` 에 보존
- `final.html` / `preview.png` 생성
- Step 14 시각 점검 통과 / Step 20 상태 통과
- F29 missing asset bug 수정 완료
- missing image count = 0 / full MDX coverage = true

---

## 2. 이번 session 에서 닫힌 작업

이번 session 에서 closed 된 axis 목록:

- Step 5 보완 — V4 rank-1 → non-reject 최대 6 개 후보 list
- Step 6-A — `CompositionUnit` 에 `v4_candidates` 필드 추가 (additive, logic 무변)
- Step 7-conn — `select_layout_candidates` artifact 연결
- Step 8-conn — region / display candidates artifact 연결 (placeholder)
- 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)

각 axis 상세 의사결정 / 폐기 / lock 은 [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md) 참조.

---

## 3. 현재 22 단계 진행 수준

> 아래 수치는 MDX03 정상 경로 기준의 *추정 진행률*이다.
> 22 단계별 공식 상태는 [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md) 를 *single source of truth* 로 한다.

| Step | 단계 | 추정 % |
|---|---|---|
| 0 | 사전 준비 / 카탈로그 / 컨트랙트 | 65% |
| 1 | MDX 업로드 | 100% |
| 2 | MDX 정규화 | 65% |
| 3 | Content Object 추출 | 45% |
| 4 | Internal Composition Planning | 40% |
| 5 | V4 매칭 후보 추출 | 85% |
| 6 | 구성 계획 | 80% |
| 7 | 슬라이드 레이아웃 계획 | 85% |
| 8 | Zone / Region 비율 계획 | 75% |
| 9 | 적용 계획 (`application_plan`) | 70% |
| 10 | 프레임 컨트랙트 확인 | 65% |
| 11 | 슬롯 매핑 | 45% |
| 12 | 슬롯 데이터 생성 | 85% |
| 13 | HTML 렌더 | 85% |
| 14 | 시각 점검 | 70% |
| 15 | 문제 분류 | 80% |
| 16 | 재시도 라우터 | 85% |
| 17 | 조치 실행 | 40% |
| 18 | 실패 분류 | 85% |
| 19 | 다음 조치 제안 | 60% |
| 20 | 슬라이드 상태 결정 | 95% |
| 21 | 디버그 / 추적 기록 | 45% |
| 22 | 사용자 확인 / 내보내기 | 10% |

전체 요약:
- MDX03 정상 경로 = 완료
- 22 단계 일반화 = 약 **65~70%**
- 제품형 전체 = 중간 단계

---

## 4. 큰 로드맵

```
1. 22 단계 파이프라인 안정화 (현재)
2. Phase Q 재검토 후 Phase Z 반영 (audit & salvage)
3. AI 보정 / 재구성 단계 (AI Repair / Restructure)
4. DB / 카탈로그 정리
5. 프론트엔드 연결
6. HTML 수정 기능 추가
7. 프레임 지속 업데이트
```

자세한 단계별 설명은 [`README.md`](../../README.md) §4 참조. 샘플 MDX (03 / 04 / 01 / 02) 는 *로드맵 단계 X* — *22 단계 보완용 검증 재료*.

---

## 5. 우선순위

```
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 결과 시각적으로 보여줌
- 미구현 영역 명확히 표시
- 향후 front / AI / DB / editor 방향에 대한 피드백 수집

---

## 7. Pipeline 복귀 후 Todo

보고 / 피드백 수집 후 22 단계 안정화 작업 재개. 우선순위 후보:

- **MDX04 검증** — `samples/mdx_batch/04.mdx` fresh run → status / rank-1 frame / 미연결 여부 확인
- **시각 점검 확장** (Step 14 보강) — 누락 이미지 / 표 잘림 / 비율 어긋남 / 빈 공간 검사
- **프레임 어댑터 확장** — Figma / V4 에는 있지만 Phase Z 에 미연결인 frame 의 contract / partial / builder 추가
- **MDX 정규화 보강** (Step 2 / 3 / 4) — Content Object 추출 + Internal Composition Planning 활성화
- **Step 21 디버그 추적 보강** — schema 채우기 (현재 빈 상태)
- **MDX01 / 02 검증** — 다른 sample 로 일반화 확장

이 후 단계 = 큰 로드맵의 §2 ~ §7 (Phase Q audit → AI repair → DB → 프론트 → HTML 수정 → frame 지속).

---

## 8. 문서 역할 분담

| 문서 | 역할 | 갱신 빈도 |
|---|---|---|
| [`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) | 22 단계별 현재 상태의 single source of truth | 자주 |
| [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md) | 의사결정 변경 이력 (axis 단위, 시간 순) | 작업 단위 |
| **`PHASE-Z-ROADMAP.md`** (본 문서) | **앞으로의 진행 순서 / 큰 axis / 우선순위** | **자주** |
| `PROCESS_OVERVIEW.html` | 보고 / 피드백용 시각 프로토타입 | 보고 시점 |

각 문서가 자기 역할만 하면 drift / 중복 / outdated 방지.