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 항목:

Step 11/12 에서 Kei slot fill 로 돌아가지 않는다.
Step 13 에서 Claude / Phase R' HTML generation 으로 돌아가지 않는다.
Step 9 에서 Phase R' reference path 로 frame 선택을 보조하지 않는다.
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 §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)
IMP-17 AI repair fallback infra (carve-out — see `IMP-17-CARVE-OUT.md`)	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)
IMP-19 I4 zone 비중 분배 (reference — see `IMP-19-ZONE-RATIO-REFERENCE.md`)	Step 8	§2.8 I4 (`renderer._group_blocks_by_area`)	pending	yes (deterministic)
IMP-20 H2 frame contract validation (reference — see `IMP-20-FRAME-CONTRACT-VALIDATION-REFERENCE.md`)	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 §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 를 보강한다.

18 KiB Raw Blame History