docs: add Phase Q insight to 22-step map

- Add docs/architecture/PHASE-Q-INSIGHT-TO-22STEP-MAP.md as
  implementation prereq lock (audit + frontend matching insight
  → 22-step pipeline mapping + Archive guardrail)
- Sections: §0 Purpose/Boundary (9 Archive markers) /
  §1 SoT Read Result / §2 22-step status & improvement map
  (23 rows × 7 columns, Block A/B/C subsections) /
  §3 Separate Axis Registry (9 axes) /
  §4 audit §1 Mapping Correction Candidates (5 catches) /
  §5 Cleanup Candidates (3) /
  §6 Frontend Matching Insight — Source Pending
- Register the new doc in PHASE-Z-ROADMAP.md §8 (frontend
  matching insight marked as source pending)

docs/architecture/PHASE-Q-INSIGHT-TO-22STEP-MAP.md

@@ -0,0 +1,158 @@
+# Phase Q Insight → 22-step Pipeline Map
+
+본 문서는 Phase Q audit / Frontend matching session / 발굴 issue 의 **insight + 회귀 금지선** 을 Phase Z 22-step pipeline 의 어느 step 에 반영할지 매핑한 implementation 전 prereq lock. 코드 작업 진입 전 본 doc 의 lock 통과 필수.
+
+---
+
+## §0 Purpose / Boundary
+
+**목적**: 22-step 안 어디에 어떤 insight 를 반영할지, 그리고 무엇을 반영하지 않을지 함께 잠그는 implementation 전 지도.
+
+**핵심 회귀 금지 4 항목**:
+1. Step 11/12 에서 Kei slot fill 로 돌아가지 않는다.
+2. Step 13 에서 Claude / Phase R' HTML generation 으로 돌아가지 않는다.
+3. Step 9 에서 Phase R' reference path 로 frame 선택을 보조하지 않는다.
+4. Step 1~22 전체를 legacy pipeline.py master flow 로 대체하지 않는다.
+
+### Archive marker 통합 inventory (9)
+
+| marker | 출처 | 회귀 risk step | 위반 invariant |
+|---|---|---|---|
+| G1 content_editor Kei AI direct slot-fill | §2.6 | Step 11, 12 | AI 격리 contract / Kei persona 단절 |
+| H4 Kei artifact 검출 (`verify_no_forbidden_content`) | §2.7 | Step 12 | Kei persona 단절 |
+| H5 Kei AI generation retry loop (`generate_with_retry`) | §2.7 | Step 12, 17 | Kei persona 단절 |
+| I5 `render_slide_from_html` (Phase R') | §2.8 | Step 13 | Phase R' 폐기 / HTML 구조 결정 AI 생성 금지 |
+| J1 `html_generator` (Phase R' core) | §2.9 | Step 13 | Phase R' 폐기 |
+| J2 §2.8 + §2.9 Phase R' archive 공동 core | §2.8 + §2.9 | Step 13 | Phase R' 폐기 |
+| K1 `block_reference` high-level (Phase R' reference path) | §2.10 | Step 9 | Phase R' reference path 회귀 금지 |
+| K2 `block_selector.format_candidates_for_prompt` (Kei prompt formatter) | §2.10 | Step 9, 11 | Kei persona 단절 |
+| L1 `pipeline.py` (Phase Q+R'+T master orchestrator) | §2.11 | Step 1~22 전체 | AI 격리 contract / Phase Q+R'+T 폐기 |
+
+---
+
+## §1 SoT Read Result
+
+**핵심 fact 3**:
+- **Step 21 = backend trace** (Debug / Trace 기록, `debug.json` artifact)
+- **Step 22 = frontend / export** (UI, 현재 범위 외)
+- **A-6 Zone 좌표 export = Step 14 (JS extension `_MEASURE_SCRIPT`+`getBoundingClientRect()`) + Step 21 (`zone_geometries_px` artifact 기록)** — 두 step 걸침
+
+**22 Step status snapshot** ([`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md) §2 채택):
+
+| Block | Step | 이름 | Status |
+|---|---|---|---|
+| — | 0 | 사전 준비 | ⚠ partial |
+| A | 1 | MDX 업로드 | ✅ |
+| A | 2 | MDX 정규화 | ⚠ partial |
+| A | 3 | Content Object 추출 | ⚠ partial (B1 v0 dormant) |
+| A | 4 | Section Internal Composition Planning | ⚠ partial (B2 v0 dormant) |
+| A | 5 | Matching Evidence 생성 | ⚠ partial (rank-1 only) |
+| A | 6 | Composition Planning | ⚠ partial |
+| A | 7 | Slide-Level Layout Planning | ⚠ partial (count-based) |
+| A | 8 | Zone + Region Ratio Planning | ⚠ partial (zone-level horizontal-2 만 dynamic) |
+| A | 9 | Region-Level Frame / Display Selection | ⚠ partial (B4) |
+| A | 10 | Frame Contract 확인 | ⚠ partial (B3) |
+| A | 11 | Content Unit → Region → Frame Slot Mapping | ⚠ partial (B4 v0 dormant) |
+| A | 12 | Slot Payload 생성 | ✅ (deterministic) |
+| B | 13 | Render | ✅ |
+| C | 14 | Selenium Visual Runtime Check | ⚠ partial (text/structural만) |
+| C | 15 | Fit Classification | ✅ |
+| C | 16 | Overflow Router | ✅ |
+| C | 17 | Implemented Action 실행 | ⚠ partial (zone_ratio_retry only) |
+| C | 18 | Failure Classification | ✅ |
+| C | 19 | Next Action Proposal | ⚠ partial (1-D mapping) |
+| C | 20 | Slide Status 결정 | ✅ |
+| C | 21 | Debug / Trace 기록 | ⚠ partial |
+| C | 22 | 사용자 확인 / Export | ⚠ future |
+
+---
+
+## §2 22-step status/improvement map
+
+### §2-A. Block A — PRE-RENDER PLANNING (Step 0~12)
+
+| Step N. 이름 | 현재 상태 | 매핑된 보강 | 구현할 것 | 이후 개선 방향 | 하지 말 것 | 검증 기준 |
+|---|---|---|---|---|---|---|
+| Step 0. 사전 준비 | ⚠ partial | A-2 Catalog 확장 → 새로 만들기 / I3 SVG 좌표 보강 → 별 axis | frame_contracts.yaml + frame_partials 32 frame 등록/확장 (A-2) | A-2 catalog 구축 axis → §3 registry / I3 SVG axis → §3 registry | Phase R' frame catalog 회귀 금지 (§0) | catalog 확장 후 PASS/FAIL 변화와 frame 선택 trace 설명 가능 |
+| Step 1. MDX 업로드 | ✅ | 매핑된 보강 없음 | 현 상태 유지 — 별 axis 활성 시 재검토 | 현재 axis 없음 | legacy pipeline.py master flow 회귀 금지 (§0) | CLI entry 결정론적 |
+| Step 2. MDX 정규화 | ⚠ partial | A-1 Stage 0 normalize → Salvage chained | `normalize_mdx_content` + `extract_major_sections` + `extract_conclusion_text` chained adapter + dual-write 검증 | A-1 통합 axis → §3 registry | AI / Kei normalize 회귀 금지 (§0) | step02 sections / sub_sections trace 설명 가능 |
+| Step 3. Content Object 추출 | ⚠ partial (B1 v0 dormant) | A-1 popup/image/table trace → Salvage chained | normalized 의 popups / images / tables → ContentObject 변환 (B1 v0 보강) | A-1 통합 axis → §3 registry / B-3 신설 axis → §3 registry | AI / Kei content extraction 회귀 금지 (§0) | ContentObject schema 정합 + popup/image/table 추출 trace 설명 가능 |
+| Step 4. Section Internal Composition Planning | ⚠ partial (B2 v0 dormant) | 매핑된 보강 없음 | 현 상태 유지 — 별 axis 활성 시 재검토 | 현재 axis 없음 | AI / Kei composition planning 회귀 금지 (§0) | composition_decision (whole / group / split) trace 정합 |
+| Step 5. Matching Evidence 생성 | ⚠ partial (rank-1 only) | 매핑된 보강 없음 (Phase Z lock — non-reject max-6 후보 list already 박힘) | 현 상태 유지 — 별 axis 활성 시 재검토 | 현재 axis 없음 | AI / Kei matching 회귀 금지 (§0) | V4 evidence top-k schema 정합 |
+| Step 6. Composition Planning | ⚠ partial | B-1 Zone-section override → 새로 만들기 (backend path) | CLI 인자 + composition planner 의 자동 결정 override path 신설 | B-1 신설 axis → §3 registry (input: Step 1/22, apply: Step 6) | Kei composition / Phase R' frame 보조 회귀 금지 (§0) | override 적용 시 composition_unit schema 정합 + trace 설명 가능 |
+| Step 7. Slide-Level Layout Planning | ⚠ partial (count-based, 7-A + 7-B already 박힘) | 매핑된 보강 없음 | 현 상태 유지 — 별 axis 활성 시 재검토 | 현재 axis 없음 | AI / Kei layout 선택 회귀 금지 (§0) | layout preset 결정론적 + trace 설명 가능 |
+| Step 8. Zone + Region Ratio Planning | ⚠ partial (zone-level horizontal-2 만 dynamic) | B-4 다른 layout zone-geometry → 새로 만들기 / I4 zone 비중 분배 → 별 axis | `build_layout_css` 분기 확장 (top-1-bottom-2 / left-1-right-2 / grid-2x2 등) | B-4 보강 axis → §3 registry / I4 zone 비중 분배 axis → §3 registry | Kei `build_containers_type_b` (page_structure) 회귀 금지 (§0) | zone-level ratio 변경 시 step08 trace 설명 가능 |
+| Step 9. Region-Level Frame / Display Selection | ⚠ partial (B4 frame_selection cover) | A-2 Catalog 확장 → 새로 만들기 / A-5 V4 fallback → 새로 만들기 / A-3 Frame preview → Salvage 후보 (axis 활성 시) | V4 catalog 32 등록 (A-2) + rank-1 fail 시 rank-2/3 fallback path (A-5) | A-2 catalog 구축 axis → §3 registry / A-5 V4 fallback axis → §3 registry / A-3 axis → §3 registry / Phase R' reference path cleanup → §5 cleanup | **Phase R' reference path frame 선택 보조 흐름 금지 (§0)** / Kei prompt formatter (K2) 회귀 금지 (§0) | frame 변경 허용, step09 trace 설명 가능 / frame contract 매칭 정합 |
+| Step 10. Frame Contract 확인 | ⚠ partial (B3 accepted_content_types + sub_zones already 박힘) | H2 frame contract validation → 별 axis / I3 SVG 좌표 보강 → 별 axis | 현 상태 유지 — 별 axis 활성 시 재검토 | H2 frame contract validation axis → §3 registry / I3 SVG axis → §3 registry / density envelope 별 axis | AI / Kei contract validation 회귀 금지 (§0) | contract field 정합 (accepted_content_types / sub_zones / capacity / visual_hints) |
+| Step 11. Content Unit → Region → Frame Slot Mapping | ⚠ partial (B4 v0 dormant) | 매핑된 보강 없음 | 현 상태 유지 — 별 axis 활성 시 재검토 | 현재 axis 없음 | **Kei slot fill 금지 (§0) / Phase R' reference path 회귀 금지 (§0)** | deterministic placement_trace + region marker 정합 |
+| Step 12. Slot Payload 생성 | ✅ (deterministic) | 매핑된 보강 없음 | 현 상태 유지 — 별 axis 활성 시 재검토 | AI repair fallback infra axis → §3 registry (normal path 밖) | **Kei slot fill 금지 (§0) / Kei artifact 검출 / Kei AI generation retry 회귀 금지 (§0)** | deterministic payload schema 정합 / AI 호출 0 |
+
+### §2-B. Block B — RENDER (Step 13)
+
+| Step N. 이름 | 현재 상태 | 매핑된 보강 | 구현할 것 | 이후 개선 방향 | 하지 말 것 | 검증 기준 |
+|---|---|---|---|---|---|---|
+| Step 13. Render | ✅ | 매핑된 보강 없음 | 현 상태 유지 — 별 axis 활성 시 재검토 | A-4 slide-base iframe mode axis → §3 registry / A-3 frame preview axis → §3 registry | **Claude / Phase R' HTML generation 금지 (§0) / `render_slide_from_html` (I5) 회귀 금지 (§0)** | Jinja2 deterministic rendering / final.html schema 정합 / AI 호출 0 |
+
+### §2-C. Block C — POST-RENDER TELEMETRY / EXCEPTION HANDLING (Step 14~22)
+
+| Step N. 이름 | 현재 상태 | 매핑된 보강 | 구현할 것 | 이후 개선 방향 | 하지 말 것 | 검증 기준 |
+|---|---|---|---|---|---|---|
+| Step 14. Selenium Visual Runtime Check | ⚠ partial (text/structural만, image/table 부재) | A-6 Zone 좌표 export → Salvage (JS extension) / Step 14 visual_check 보강 → 별 axis | `_MEASURE_SCRIPT` 의 JS 에 `getBoundingClientRect()` 추가 (A-6) + image_aspect_mismatch / tabular_overflow 검사 추가 (H1) | A-6 JS 보강 axis → §3 registry / Step 14 visual_check 보강 axis → §3 registry / B-2 verification 보조 axis → §3 registry | frontend boundingClientRect 단독 SoT 금지 | DOM bbox / overflow 측정 trace 가능 |
+| Step 15. Fit Classification | ✅ | 매핑된 보강 없음 | 현 상태 유지 — 별 axis 활성 시 재검토 | 현재 axis 없음 | AI / Kei classification 회귀 금지 (§0) | classification enum 정합 + trace 설명 가능 |
+| Step 16. Overflow Router | ✅ | A-5 V4 fallback (router 확장) → 새로 만들기 / Step 16/17 retry 정밀화 → Salvage 별 axis | V4 fallback router 확장 (A-5) + zone_ratio_retry 실 구현 보강 (`redistribute`) + glue_compression action 신설 + font_size_retry action 신설 | Step 16/17 retry axis → §3 registry / A-5 V4 fallback axis → §3 registry | AI / Kei retry 회귀 금지 (§0) / Kei retry loop (H5) 회귀 금지 (§0) | deterministic retry action 결과 / status semantics 일관 |
+| Step 17. Implemented Action 실행 | ⚠ partial (zone_ratio_retry only) | Step 16/17 retry 정밀화 → Salvage 별 axis / A-5 V4 fallback (action 실행) → 새로 만들기 | glue / font compression 실 구현 + V4 fallback action 실행 + details_popup_escalation 등 missing actions | Step 16/17 retry axis → §3 registry / A-5 V4 fallback axis → §3 registry | AI retry / Kei retry loop 회귀 금지 (§0) | retry action 결과와 status semantics 설명 가능 / final.html overflow 0 후 PASS |
+| Step 18. Failure Classification | ✅ | 매핑된 보강 없음 | 현 상태 유지 — 별 axis 활성 시 재검토 | 현재 axis 없음 | AI failure analysis 회귀 금지 (§0) | failure_type enum 정합 |
+| Step 19. Next Action Proposal | ⚠ partial (1-D mapping) | 매핑된 보강 없음 | 현 상태 유지 — 별 axis 활성 시 재검토 | 현재 axis 없음 (severity-aware 2-D mapping 별 axis) | AI proposal 회귀 금지 (§0) | next action proposal schema 정합 |
+| Step 20. Slide Status 결정 | ✅ | A-5 V4 fallback (status semantics) → 새로 만들기 / D-1 filtered_section_reasons artifact source → frontend 신규 | 신설 status (예: `PASS_WITH_FALLBACK`) semantics 정합 (A-5) + filtered_section_reasons artifact source 정합 (D-1) | A-5 V4 fallback axis → §3 registry / D-1 frontend axis → §3 registry / D-2 frontend axis → §3 registry | AI status 판단 회귀 금지 (§0) / 특정 MDX / frame 고정 금지 (§4 머리글 guardrail) | PASS/FAIL + coverage + trace 설명 가능 |
+| Step 21. Debug / Trace 기록 | ⚠ partial | A-6 `zone_geometries_px` artifact → Salvage (Step 14 + Step 21 걸침) / Step 14 visual_check 보강 → 별 axis (region/content_object trace) | `zone_geometries_px` artifact `debug.json` 기록 (A-6) + content_object / section_layout_signature / sub_zone mapping / region-level telemetry 기록 보강 | A-6 JS 보강 axis → §3 registry / Step 14 visual_check 보강 axis → §3 registry / B-2 verification 보조 axis → §3 registry | AI / Kei trace 회귀 금지 (§0) | debug.json schema 정합 + region/content_object trace 설명 가능 |
+| Step 22. 사용자 확인 / Export | ⚠ future (UI, 현 범위 외) | D-1 filtered_section_reasons UI → frontend 신규 / D-2 Frame min_height 표시 → frontend 신규 (catalog 참조) / B-1 override 입력 UI → frontend / B-2 Edited HTML → MDX UI → frontend | frontend UI 신규 — filtered_section_reasons 표시 (D-1) + min_height resize hint (D-2) + override input UI (B-1) + edited HTML reverse path entry (B-2) | D-1 frontend axis → §3 registry / D-2 frontend axis → §3 registry / B-1 신설 axis → §3 registry / B-2 신설 axis → §3 registry | AI / Kei UI 회귀 금지 (§0) | D-1/D-2 는 backend artifact read-only 표시, B-1/B-2 는 backend 입력 / 재실행 path 와 정합 |
+
+---
+
+## §3 Separate Axis Registry
+
+9 axis — §2 의 *이후 개선 방향* cross-ref 의 1:1 매핑 대상. 모든 axis 는 현 시점 *pending* (axis 활성 X) :
+
+| axis | 관련 step | source | status | normal path 여부 |
+|---|---|---|---|---|
+| Step 16/17 retry 정밀화 | Step 16, 17 | §2.4 `redistribute` + §2.5 glue + §2.5 font compression (group B) | pending | yes (deterministic) |
+| A-3 frame preview 일관성 | Step 0, 14, 21 | §2.3 `capture_slide_screenshot` (I1 reference) | pending | yes (UI/backend) |
+| A-4 slide-base iframe mode | Step 13 | §2.8 I2 (renderer.py slide-base 사용 호출 지점) | pending | yes (UI/backend) |
+| Step 14 visual_check 보강 | Step 14, 21 | §2.7 H1 (`content_verifier` utilities Reference Only) | pending | yes (deterministic) |
+| B-2 verification 보조 | Step 1, 2, 14, 21, 22 | §2.7 H3 (text 추출 / 정규화 / 비교 utility) | pending | yes (UI/backend) |
+| AI repair fallback infra | Step 12, 16, 17 | §2.6 G3 (`httpx` + SSE streaming + retry + JSON parse pattern) | pending | no (AI fallback only) |
+| I3 SVG 좌표 보강 | Step 0, 9 | §2.8 I3 (`renderer._preprocess_svg_data`) | pending | yes (deterministic) |
+| I4 zone 비중 분배 | Step 8 | §2.8 I4 (`renderer._group_blocks_by_area`) | pending | yes (deterministic) |
+| H2 frame contract validation | Step 10 | §2.7 H2 (`content_verifier.verify_structure` pattern) | pending | yes (deterministic) |
+
+---
+
+## §4 audit §1 Mapping Correction Candidates
+
+5 catch — [`PHASE-Q-AUDIT.md`](PHASE-Q-AUDIT.md) §1 lens 표의 매핑 정확도. 본 정정 작업은 **별 axis** (본 doc 박기와 분리):
+
+| catch ID | 출처 | audit §1 lens 정정 대상 | 근거 |
+|---|---|---|---|
+| G2 | §2.6 `content_editor` | B-1 / B-2 column 매핑 부정확 | content_editor.py 가 audit §1 lens B-1 / B-2 후보 파일로 listed. 단 *실제 매핑 X* — B-1 zone-section override = `pipeline.py` / composition planner 영역 / B-2 HTML→MDX 역변환 = 글벗 `html_to_slide_mdx`. content_editor 는 *block 안 slot 채우기* — B-1/B-2 와 영역 다름 |
+| I6 | §2.8 `renderer` | A-3 / A-4 매핑 정확도 | renderer.py 가 audit §1 lens A-3 (Frame preview) / A-4 (slide-base iframe) 후보로 listed. A-3 main = preview.png 자동 생성 — renderer.py 의 Selenium 캡처 흔적은 *render path 자료*, main 매핑은 §2.3 slide_measurer. A-4 = slide-base 사용 호출 지점 있으나 *embedded/standalone conditional CSS 분기* 구현 부재 |
+| J5 | §2.9 `html_generator` | A-3 / A-4 매핑 정확도 | audit §1 부연 "selenium 캡처 흔적 추정" *부정확* — html_generator 에 Selenium import 부재. A-4 = html_generator 가 area HTML 만 반환 (slide-base 호출 부재) — audit §1 부연 부정확 |
+| K6 | §2.10 `block_reference` + `block_selector` | A-2 매핑 정확도 | audit §1 lens A-2 (Catalog 확장) 후보로 listed — *간접* (catalog 로딩 / block 검색 패턴 reference 정도). A-2 main = `frame_contracts.yaml` + `frame_partials` 등록/확장 (Phase Q catalog ≠ Phase Z catalog schema) |
+| L5 | §2.11 `pipeline` + `pipeline_context` | B-1 매핑 정확도 | audit §1 lens B-1 (Zone-section override) 후보로 listed — *간접 surface* (pipeline orchestration entry, page_structure 생성 흐름 보유). *direct composition planner / zone-section assignment override implementation* 영역과 다름 |
+
+---
+
+## §5 Cleanup Candidates
+
+3 candidate — utility / 코드 중복 정리 별 axis (Phase R' cleanup 또는 Phase Z utility 통합 axis 활성 시):
+
+| candidate ID | 출처 | cleanup 대상 | trigger axis |
+|---|---|---|---|
+| J3 | §2.9 `html_generator` | utility 중복 — `normalize_mdx` / `_slice_mdx_sections` / `_get_definitions` / `_get_conclusion` (vs §2.1 / §2.2 SoT) | Phase R' cleanup axis 활성 시 |
+| K5 | §2.10 `block_reference` + `block_selector` + §2.8 `renderer` | catalog 로드 + `_get_block_by_id` 중복 (3 module) | Phase R' cleanup 또는 Phase Z catalog 확장 axis 활성 시 |
+| L4 | §2.11 `pipeline` + §2.6 `content_editor` + §2.9 `html_generator` | `_parse_json` 중복 (3 module) | Phase R' cleanup 또는 Phase Z utility 통합 axis 활성 시 |
+
+---
+
+## §6 Frontend Matching Insight — Source Pending
+
+Frontend matching insight 는 source pending 상태다. 출처가 확정되기 전까지 본 §2 22-step map 에는 반영하지 않는다. 출처 확정 후 별도 axis 에서 §2 row 와 §3 registry 를 보강한다.

docs/architecture/PHASE-Z-ROADMAP.md

@@ -277,6 +277,7 @@ frontend (`design_agent_front/design-agent`) 와 backend phase_z2 의 연결 axi
 | [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md) | 의사결정 변경 이력 (axis 단위, 시간 순) | 작업 단위 |
 | **`PHASE-Z-ROADMAP.md`** (본 문서) | **앞으로의 진행 순서 / 큰 axis / 우선순위** | **자주** |
 | [`PHASE-Q-AUDIT.md`](PHASE-Q-AUDIT.md) | Phase Q 모듈의 Keep / Migrate / Reference / Delete 결정 + Salvage Plan + ROADMAP §7-B 우선순위 재정렬의 input | audit 진행 중 (모듈별로 1 turn) |
+| [`PHASE-Q-INSIGHT-TO-22STEP-MAP.md`](PHASE-Q-INSIGHT-TO-22STEP-MAP.md) | audit insight + frontend matching insight(source pending) → 22-step pipeline 매핑 + implementation 전 prereq lock | implementation axis 활성 시 |
 | `PROCESS_OVERVIEW.html` | 보고 / 피드백용 시각 프로토타입 | 보고 시점 |
 
 각 문서가 자기 역할만 하면 drift / 중복 / outdated 방지.