Design Agent / C.E.L Slide Automation

1. 프로젝트 개요

MDX 문서를 입력받아 1280×720 프레젠테이션 슬라이드 HTML 로 자동 변환하는 파이프라인.

• 입력: MDX (텍스트 + 표 + bullets + JSX block + details + image)
• 변환: V4 frame matching → Phase Z render pipeline
• 출력: final.html (단일 슬라이드) + step artifact (의사결정 trace)
• 최종 목표: pipeline + AI repair + DB/catalog + frontend editor 가 연결된 제품형 시스템

원천 디자인 = Figma BEPs frame (32 frame) → figma_to_html_agent/blocks/ 에 HTML/CSS 변환물 누적. V4 catalog (tests/matching/v4_full32_result.yaml) 가 MDX section ↔ frame 매칭 점수/label 산출. Phase Z 가 V4 결과를 받아 render-able slide 로 번역.

---

2. 전체 실행 구조 (22-step pipeline)

flowchart TD
    Input([MDX Input])
    Input --> S1_2["Step 1-2<br/>MDX Upload & Normalize"]
    S1_2 --> S3_4["Step 3-4<br/>Content Object &<br/>Internal Composition Planning"]
    S3_4 --> S5["Step 5<br/>V4 Frame Evidence<br/><sub>rank 1 + non-reject max-6</sub>"]
    S5 --> S6["Step 6<br/>Composition Planning"]
    S6 --> S7["Step 7<br/>Layout Candidates<br/><sub>8 preset vocabulary</sub>"]
    S7 --> S8["Step 8<br/>Zone / Internal Region /<br/>Display Strategy"]
    S8 --> S9["Step 9<br/>Application Plan<br/><sub>V4 후보 → 적용 방식 번역</sub>"]
    S9 --> S10_12["Step 10-12<br/>Frame Contract / Slot Mapping / Payload"]
    S10_12 --> S13["Step 13<br/>Render final.html<br/><sub>Jinja2 + frame partial</sub>"]
    S13 --> S14["Step 14<br/>Visual Runtime Check<br/><sub>Selenium</sub>"]
    S14 --> Visual{"Visual OK?"}
    Visual -->|Yes| S20["Step 20<br/>PASS / Slide Status"]
    Visual -->|No| S15_19["Step 15-19<br/>Fit Classification / Router /<br/>Retry / Next Action"]
    S15_19 --> Repair{"Repair 방식?"}
    Repair -->|Deterministic<br/>zone_ratio / popup / layout_adjust| S13
    Repair -->|AI Required<br/>restructure / low score / overflow 반복| AI["AI Repair / Restructure Layer<br/><sub>(향후 axis)</sub>"]
    AI --> S13
    S20 --> S21_22["Step 21-22<br/>Debug / Trace / Export / Front 연결"]

    classDef stage fill:#e7f5ff,stroke:#1971c2,color:#000
    classDef render fill:#fff3cd,stroke:#f59f00,color:#000
    classDef telemetry fill:#f3f0ff,stroke:#7048e8,color:#000
    classDef decision fill:#ffd8a8,stroke:#d9480f,color:#000
    classDef future fill:#f8f9fa,stroke:#868e96,color:#000,stroke-dasharray: 5 5

    class S1_2,S3_4,S5,S6,S7,S8,S9,S10_12 stage
    class S13 render
    class S14,S15_19,S20,S21_22 telemetry
    class Visual,Repair decision
    class AI future

Block 구분 : Block A (PRE-RENDER PLANNING, Step 0~12) · Block B (RENDER, Step 13) · Block C (POST-RENDER TELEMETRY / EXCEPTION HANDLING, Step 14~22). 진짜 fit policy 의 자리 = Block A. C block 은 exception 처리 layer.

텍스트 list (모든 22 step) :

Block A — PRE-RENDER PLANNING (Step 0~12)
  Step 0   precondition (catalog / contract / V4 / template / asset)
  Step 1   MDX 업로드
  Step 2   MDX 정규화 (frontmatter / heading tree / footer)
  Step 3   Content Object 추출 (text_block / table / image / details / ...)
  Step 4   Section Internal Composition Planning (whole / group / split)
  Step 5   V4 Matching Evidence (non-reject max-6 후보 list)
  Step 6   Composition Planning (composition unit 결정)
  Step 7   Slide-Level Layout Planning (8 preset vocabulary)
  Step 8   Zone + Internal Region Ratio Planning
  Step 9   Region-Level Frame / Display Selection (application_plan)
  Step 10  Frame Contract 확인
  Step 11  Content → Internal Region → Frame Slot Mapping
  Step 12  Slot Payload 생성

Block B — RENDER (Step 13)
  Step 13  Render (Jinja2 + frame partial → final.html)

Block C — POST-RENDER TELEMETRY / EXCEPTION HANDLING (Step 14~22)
  Step 14  Selenium Visual Runtime Check
  Step 15  Fit Classification
  Step 16  Overflow Router
  Step 17  Implemented Action 실행 (zone_ratio_retry / details_popup_escalation / ...)
  Step 18  Failure Classification
  Step 19  Next Action Proposal
  Step 20  Slide Status 결정 (PASS / RENDERED_WITH_VISUAL_REGRESSION / ...)
  Step 21  Debug / Trace 기록
  Step 22  사용자 확인 / Export

각 step 의 ✅ / ⚠ / ❌ 정확한 상태는 STATUS-BOARD.md 가 single source of truth.

위계 (Slide → Frame Slot):

Slide → Zone → Internal Region → Frame → Frame Slot → Content

22-step 도면 lock = docs/architecture/PHASE-Z-PIPELINE-OVERVIEW.md 현재 snapshot = docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md axis history = docs/architecture/PHASE-Z-CHANGE-LOG.md

---

3. 현재 완료 수준

3.1 MDX03 정상 경로 (PASS)

overall                : PASS
visual_check_passed    : true
full_mdx_coverage      : true
adapter_needed_count   : 0
content_truncated_count: 0
units                  : 03-1 → F13 (use_as_is, 0.927)
                         03-2 → F29 (use_as_is, 0.920)

3.2 22-step 진행 수준

상세는 STATUS-BOARD.md 의 표 참조. 큰 그림:

• ✅ implemented: Step 1 / 12 / 13 / 15 / 16 / 18 / 20
• ⚠ partial: Step 0 / 2 / 5 / 6 / 7 / 8 / 9 / 10 / 14 / 17 / 19 / 21
• ❌ missing 또는 future: Step 3 (content_object) / 4 (internal composition) / 11 (slot mapping) / 22 (UI)

→ 22-step 일반화 진행 수준 ≈ 65~70%. MDX03 정상 경로는 닫힘. 일반화 (다른 MDX / edge case / fallback path / UI) 는 진행 중.

3.3 박힌 axis (시간 순)

이번 session 박힌 주요 axis:

• Step 7-A / 7-B: layout catalog yaml + select_layout_candidates(unit_count) (catalog axis)
• Step 8-A / 8-B-1 / 8-B-2: region_layouts.yaml + display_strategies.yaml + 후보 함수
• Step 5 보완: V4 rank-1 → non-reject max-6 후보 list
• Step 6-A: CompositionUnit 에 v4_candidates 필드 (additive, logic 무변)
• Step 7-conn / 8-conn: catalog 후보 함수 → runtime artifact 연결 (passive 기록)
• Step 9 v0: passive application_plan artifact (V4 후보 + layout/region/display 통합 trace)
• F29 visual fidelity fix: missing SVG 3 개 → CSS gradient 재현 (figma 원본 R8 룰 따라)
• cleanup-1: stale 주석 정정 (pipeline 호출처 X → 호출처 박힘)

3.4 폐기된 안 (history 보존)

CHANGE-LOG 에 박힘:

• compat 매트릭스 안 (Step 9 초기 안) — V4 cardinality 재계산 위험으로 폐기
• 6-B (frame ownership transfer) — misframed axis. V4 가 frame 선택, Step 6 은 전사, Step 9 는 번역. "Step 6 의 frame 채택 책임 이전" = 허구.

3.5 검증 / 실험 repo 성격

본 repo 는 제품형 시스템 까지의 진행 과정에서 검증 재료 로 다음 sample 사용:

• samples/mdx_batch/03.mdx — 기준 sample (MDX03 정상 경로 lock)
• samples/mdx_batch/04.mdx — MDX04 검증 예정
• samples/mdx/01. ...mdx / 02. ...mdx — 향후 검증

샘플 MDX 는 로드맵 단계 가 아니라 22-step pipeline 보완을 위한 검증 재료.

---

4. 향후 로드맵

flowchart LR
    R1["1. 22-step Pipeline<br/>Stabilization<br/><sub>frame 연결 / visual check 보강 /<br/>MDX 정리 / 01·02·04 검증</sub>"]
    R2["2. Phase Q Audit & Salvage<br/><sub>옛 25 모듈 검토 → Z 이식</sub>"]
    R3["3. AI Repair /<br/>Restructure Layer<br/><sub>low score / reject /<br/>restructure / overflow</sub>"]
    R4["4. DB / Catalog<br/>Integration<br/><sub>frame / V4 / runs / overrides</sub>"]
    R5["5. Frontend Connection<br/><sub>run / timeline /<br/>rank 후보 / plan</sub>"]
    R6["6. HTML Editing /<br/>User Overrides<br/><sub>user_overrides.json</sub>"]
    R7["7. Continuous Frame<br/>Adapter Updates<br/><sub>Figma → Phase Z adapter</sub>"]

    R1 --> R2 --> R3 --> R4 --> R5 --> R6 --> R7

    classDef current fill:#fff3cd,stroke:#f59f00,color:#000
    classDef future fill:#f3f0ff,stroke:#7048e8,color:#000
    classDef later fill:#f8f9fa,stroke:#868e96,color:#000,stroke-dasharray: 5 5

    class R1 current
    class R2,R3 future
    class R4,R5,R6,R7 later

현재 위치 : 단계 (1) 22-step Pipeline Stabilization. MDX03 정상 경로 닫힘 / 일반화 진행 중.

단계별 상세

1. 22-step 파이프라인 정리 (현재)
   ├ frame ↔ Phase Z 연결 구조 정리 (= V4 frame 후보 → Phase Z render path 연결 확장)
   │  · F14 / F11 / F18 등 미연결 frame 의 contract / partial / builder adapter
   │  · Figma 새 디자인 X / V4 새 매칭 X — 이미 두 layer 에 있는 frame 의 adapter
   ├ visual check 범위 정리 (Step 14 보강)
   │  · missing image / table clipping / image aspect mismatch / underfilled zone
   ├ MDX 정규화 / 정리 방법 적용 (Step 2 / 3 / 4)
   └ MDX 01 / 02 / 04 검증을 통해 보완 (edge case 발견 + pipeline 일반화)

2. Phase Q 재검토 후 Phase Z 반영
   ├ src/ 안 옛 25 모듈 audit (slide_measurer, space_allocator, content_editor 등)
   ├ 살릴 기능 식별 → Phase Z 로 이식
   └ tests/matching/ 의 V4 진화 history / DECK / ATTACH 자료도 같이 검토

3. AI 적용 관련 프로세스 정립 및 적용
   ├ low score / all reject / light_edit / restructure / overflow 반복 케이스
   ├ AI repair / restructure / popup / layout adjust
   ├ MDX 원문 보존 lock (AI 가 원문 삭제 / 요약 / 재작성 X)
   └ 연결 step: Step 9 / 12 / 17 / 19 / 21

4. DB / Catalog 정리
   ├ frame catalog / contracts
   ├ V4 results
   ├ run history / step artifacts
   ├ user overrides
   └ 선택 이력 (rank-N 사용자 선택 trace)

5. Front 연결
   ├ run 목록 / preview.png / final.html
   ├ 22-step timeline (각 step artifact 시각)
   ├ V4 rank 1~6 후보 표시 + 사용자 선택
   ├ layout / region / application_plan 표시
   └ visual check / retry / failure / next action 결과

6. HTML 수정 기능 추가
   ├ 텍스트 수정
   ├ 이미지 크기 / 위치 조정
   ├ frame 후보 변경 (rank-N 선택)
   ├ layout / region 조정
   └ user_overrides.json 저장 (final.html 직접 수정 X — MDX 원문 보존 정합)

7. 이후 frame 지속 업데이트
   ├ Figma → HTML 변환 추가 (figma_to_html_agent)
   ├ Phase Z adapter 연결 (1 의 frame ↔ Phase Z 연결 axis 와 같은 결)
   ├ contract / partial / builder 추가
   └ V4 catalog 와 runtime 동기화

→ MDX03 / 04 / 01 / 02 검증은 (1) 22-step 정리 안의 수단 — 별 단계 X.

---

5. 운영 기준

5.1 절대 lock

• MDX 원문 무손실 보존 — AI 가 normal path 에서 MDX 원문을 재작성 / 삭제 / 요약 X. 원문은 본문 preview 또는 details/popup 에 반드시 보존.
• 자유 디자인 금지 — Figma frame DB / catalog / frame contract 기반으로만 디자인 결정. AI 가 frame / layout / 새 디자인 패턴 생성 X.
• 그릇 변경 원칙 — 콘텐츠가 안 맞을 때 콘텐츠를 줄이지 않음. 그릇 (layout / zone / region / frame / display strategy) 을 변경. 공통 CSS / padding / tolerance 임의 축소 금지.
• dropped 절대 룰 — text_block / table / image / details 는 dropped 절대 X (catalog forbidden_for lock). decorative_element 만 dropped 가능.

5.2 V4 ↔ Phase Z 책임 분담

• V4 = frame 선택 (점수 + label: use_as_is / light_edit / restructure / reject)
• Step 5 (Phase Z) = V4 후보 list 추출 (non-reject max-6, raw 32 entry 영속)
• Step 6 = composition unit 결정 (어느 section 묶음 = 1 zone unit). 현재 V4 rank-1 default 전사
• Step 9 v0 = V4 후보 → application_plan 번역 (V4 axis 재계산 X)
  • use_as_is → direct_insert
  • light_edit → same_frame_with_adjustment
  • restructure → layout_or_region_change (auto_applicable=False, human_review delegate)
  • reject → exclude

5.3 렌더 정책

• 현재 렌더 = V4 rank-1 (Step 6 default)
• rank 2~6 보존 = Step 9 application_plan + Step 5 evidence 에 trace. 향후 frontend 에서 사용자 선택 가능.
• final.html 직접 수정 X — frontend 에서 변경 시 user_overrides.json 으로 누적 (원문 보존 정합).

---

Repository Mirrors

본 프로젝트는 두 repository 에서 mirror 로 관리됨:

• GitHub : https://github.com/keimin86/design_agent
• Gitea : https://gitea.hmac.kr/Kyeongmin/C.E.L_Slide_test2

두 저장소의 README 와 코드 base 는 동일하게 유지 (push 시 둘 다 fast-forward).

---

참고 문서

문서	역할
CLAUDE.md	프로젝트 규칙 + Phase Z 위계
PHASE-Z-PIPELINE-OVERVIEW.md	22-step 도면 (구조 lock)
PHASE-Z-PIPELINE-STATUS-BOARD.md	현재 snapshot (✅ / ⚠ / ❌)
PHASE-Z-CHANGE-LOG.md	axis-by-axis 의사결정 history
PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md	content_object + Internal Region + Frame Slot SPEC
PHASE-Z-FIT-CLASSIFIER-ROUTER-SPEC.md	Step 14~19 telemetry layer SPEC
IMPROVEMENT-REDESIGN.md	Phase Z 통합 설계 핵심
PROCESS_OVERVIEW.html	임원 보고용 A4 2 페이지 (프로세스 + 구조도)
PROGRESS.md	전체 Phase 이력 (Phase 1~T + R' + Z)