KyeongminandClaude Fable 5
4d7c401779
Multi-MDX Regression (IMP-91) / multi-mdx-regression (push) Failing after 9m49s
- tests/integration/scripts/regenerate_snapshots.py: 스냅샷 일괄 재생성 도구 - 통합 스냅샷 9종 갱신, 회귀/유닛 테스트 7건 보강 - ISSUE_DRAFTS_2026-07-02.md: 7/2 전수 검토 이슈 초안 보존 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
210 lines
11 KiB
Markdown
210 lines
11 KiB
Markdown
# 이슈 초안 — 2026-07-02 스냅샷(b836e79) 전수 검토 결과
|
||
|
||
> 검토 범위: PLAN/PROGRESS/emergency.md 등 계획 문서, tests/matching 진단 리포트,
|
||
> b836e79 커밋 코드 diff, figma_to_html_agent(미통합) 전체.
|
||
> 목표: ① Figma→HTML 변환이 정확히 되고 ② 그 HTML에 콘텐츠 내용·의미가 반영되어 정리되는 상태.
|
||
|
||
---
|
||
|
||
## 그룹 A — Figma→HTML 변환 정확도
|
||
|
||
### A-1. figma_to_html_agent를 메인 repo로 통합 (유실 위험 제거)
|
||
|
||
**배경**
|
||
- Figma→HTML 변환기 본체(MCP 추출 + 수학 변환 + 검증 프로세스 문서 PROCESS.md/MATH.md/RULES.md)가 `Front_test_v515/figma_to_html_agent/`에만 존재하며, 이 디렉토리는 gitignore 처리되어 **어디에도 백업이 없음**.
|
||
- 메인 repo에는 사본 스크립트(`scripts/figma_to_html.py`)와 메타데이터만 있음.
|
||
- 32개 frame 변환 산출물(blocks/{frame_id}/index.html, texts.md, flat.md)도 같은 위치에 미보존 상태.
|
||
|
||
**작업**
|
||
1. `figma_to_html_agent/`를 repo 최상위로 이동 (문서 + blocks + scripts).
|
||
2. `scripts/figma_to_html.py` 중복 제거, gradient_math.py import 경로 정리.
|
||
3. MCP(Figma Desktop Dev Mode) 의존성·.mcp.json 샘플 문서화.
|
||
4. .gitignore에서 해당 경로 제외 확인 후 커밋.
|
||
|
||
**완료 조건**: 변환기 전체가 origin/main에 push되어 로컬 디스크 유실 시에도 복구 가능.
|
||
|
||
---
|
||
|
||
### A-2. 잔여 Figma frame 프로모션 완료 (8/32 → 32/32)
|
||
|
||
**배경**
|
||
- Figma frame 32개 중 **promoted(본체 편입) 8개**, static(1:1 변환만) 6개+, 나머지는 staged 미작성.
|
||
- placement_planner에 "contract-only 템플릿 skip" 로직(`b4_partial_missing_skip`, IMP-95 u6)이 있다는 것은 contract는 있으나 partial HTML이 없는 frame이 존재한다는 뜻 — 매칭이 맞아도 렌더링 불가.
|
||
|
||
**작업**
|
||
1. frame_contracts.yaml 기준 32개 frame의 상태 매트릭스 작성 (contract 유무 / partial HTML 유무 / promoted 여부).
|
||
2. static 6개(process-products-2col, scene-with-numbered-list-4, framework-3section-label-body, bordered-3paragraphs, cards-3-category-bim-diagram, dx-banner-3perspective)부터 staged → promoted 진행.
|
||
3. partial 없는 contract-only frame 목록을 문서화하고 순차 해소.
|
||
|
||
**완료 조건**: V4가 선택한 어떤 frame도 "partial 없음"으로 skip되지 않음.
|
||
|
||
---
|
||
|
||
### A-3. Figma 원본 추적성(provenance) 강화
|
||
|
||
**배경**
|
||
- promoted 블록은 Jinja2 파라미터화 과정에서 Figma 원본 좌표·구조 추적성이 손실됨. 현재 provenance 테스트(test_imp49_partial_figma_provenance.py)는 **색상 literal만** 비교.
|
||
- `get_screenshot` 결과(Figma 원본 PNG)가 캐시되지 않아 사후 육안 비교 기준이 없음.
|
||
|
||
**작업**
|
||
1. blocks/{frame_id}/에 Figma 원본 스크린샷 캐시 저장 (fetch_figma_screenshots.py 활용).
|
||
2. promoted 블록마다 source frame_id를 frame_contracts.yaml에 정식 필드로 기록.
|
||
3. provenance 테스트를 색상 외 구조(슬롯 수, 주요 영역 배치)까지 확장.
|
||
|
||
**완료 조건**: 임의의 promoted 블록에서 "원본 Figma frame → HTML 요소" 대응을 문서·테스트로 확인 가능.
|
||
|
||
---
|
||
|
||
## 그룹 B — 콘텐츠 의미 → HTML 반영 (매칭 품질)
|
||
|
||
### B-1. 02-2.2 매칭 실패 교정 — TARGET 4/4 달성
|
||
|
||
**배경**
|
||
- V4 종합 판정 TARGET 3/4 (75%). 실패 케이스 02-2.2: 정답 Frame 14가 V4 순위 7위, 모든 후보 reject.
|
||
- 근본 원인: Frame 14의 anchor_sets 키워드가 MDX 02-2.2 본문과 거의 안 겹침 (tests/PIPELINE.md:230-232).
|
||
- 문서상 예상 공수 1~2일 — 가장 빠르게 정확도를 올릴 수 있는 지점.
|
||
|
||
**작업**
|
||
1. Frame 14 anchor_sets 재라벨링 + 도메인 키워드 보강.
|
||
2. holdout(02-2.1 등)으로 과적합 여부 교차 확인.
|
||
|
||
**완료 조건**: TARGET 4/4, holdout 정확도 하락 없음.
|
||
|
||
---
|
||
|
||
### B-2. MDX 콘텐츠 성격·시각 의도 분류를 키워드 사전 → LLM 판정으로 대체
|
||
|
||
**배경**
|
||
- V3 구조 매칭의 "콘텐츠 성격(12 카테고리)·시각 의도(9 카테고리)"가 키워드 사전 매칭이라 오분류 발생 (예: 01-2가 policy_requirements로 오분류). tests/PROGRESS.md 약점 #2·#3, 예상 공수 3~5일.
|
||
- 일반 표현을 못 잡는 구조적 한계 — 새 MDX가 들어올수록 사전 유지비 증가.
|
||
|
||
**작업**
|
||
1. 분류 프롬프트 설계 + 기존 4 TARGET/holdout으로 정확도 비교 (사전 vs LLM vs 하이브리드).
|
||
2. 비용 고려해 "사전 1차 + 저신뢰 시 LLM" 하이브리드 우선 검토.
|
||
3. 판정 근거를 pipeline_trace에 기록해 사후 검증 가능하게.
|
||
|
||
**완료 조건**: 01-2 오분류 해소 + TARGET/holdout 분류 정확도 리포트 갱신.
|
||
|
||
---
|
||
|
||
### B-3. V4 스코어링 재조정 — ablation 결과 반영
|
||
|
||
**배경**
|
||
- ablation으로 확인된 사실: slot 축(가중 0.15)은 frame 선별에 무영향(Top-1 7/7 동일), cardinality는 axis(0.20)+slot.within(0.075)로 같은 신호가 중복 가중됨 (tests/PROGRESS.md 약점 #5·#6, V4_SLOT_ABLATION.md).
|
||
|
||
**작업**
|
||
1. slot 축을 frame 선별 가중에서 제거하고 label 게이트 역할로만 유지.
|
||
2. cardinality 중복 가중 해소 후 가중치 재정규화.
|
||
3. TARGET/holdout 재실행으로 회귀 없음 확인.
|
||
|
||
**완료 조건**: 재조정된 가중치로 TARGET ≥ 기존, confidence 분포 문서화.
|
||
|
||
---
|
||
|
||
### B-4. 슬롯 의미 매핑 계약(T25) 실제 배선 + 컴포넌트 확장(T23) 커버리지
|
||
|
||
**배경**
|
||
- "BIM → col_a_label" 같은 편집 슬롯 의미 매핑 부재가 약점 #4로 기록됨.
|
||
- 이번 스냅샷에서 node_slot_mapping.yaml(11 node × 9 slot 매트릭스)이 **정의됐으나 runtime에서 읽는 배선 미확인** (주석: "T25 will wire builders/mappers to validate").
|
||
- component_expansion_registry.yaml은 DxEffect 1개 entry뿐이고 status: planned. persona role label도 "DxEffect" 하드코딩 (src/phase_z2_pipeline.py L281-284).
|
||
- AI schema hints도 three_parallel_requirements 1개 frame만 정의 (L216-241).
|
||
|
||
**작업**
|
||
1. mapper/builder가 node_slot_mapping.yaml을 실제로 로드·검증하도록 배선 (T25).
|
||
2. DxEffect expansion end-to-end 테스트 후 status: planned 해제.
|
||
3. AI schema hints를 주요 frame(three_persona_benefits, quadrant 등)으로 확장.
|
||
4. component_name 하드코딩 제거.
|
||
|
||
**완료 조건**: node→slot 매핑 위반이 파이프라인에서 검출되고, DxEffect 외 컴포넌트 1개 이상 추가 등록.
|
||
|
||
---
|
||
|
||
### B-5. 표 전체 행 추출 + 이미지 frame 매칭 (약점 #7·#8)
|
||
|
||
**배경**
|
||
- 4행 표에서 첫 행만 본문으로 추출, 나머지 행 무시 (DECK 정직성 점검에서 발견).
|
||
- 그림/이미지 frame은 본문 텍스트 패턴만 분석해 매칭이 약함.
|
||
|
||
**작업**
|
||
1. `_extract_markdown_table` 및 관련 파서가 전 행을 atom으로 보존하도록 수정, check_phase_z2_render_text_coverage.py로 검증.
|
||
2. image_ref node type의 매칭 신호 설계 (alt 텍스트, 주변 문맥).
|
||
|
||
**완료 조건**: 표 포함 MDX의 render_text_coverage에서 missing 행 0.
|
||
|
||
---
|
||
|
||
## 그룹 C — 파이프라인 신뢰성 (empty shell 제거·배선 완성)
|
||
|
||
### C-1. Emergency P2~P5 완수 — empty shell 완전 제거
|
||
|
||
**배경**
|
||
- mdx 01~05 rescue 세션(emergency.md): root cause 3개(C1 catalog gap all-reject / C2 section key mismatch / C3 V4 source 누락) 식별 후 **P1 진단만 완료, P2~P5 미실행**.
|
||
- 정책은 이미 확정됨: reject → `ai_adaptation_required` status, empty_shell terminal 제거, generic_fallback은 기존 catalog 활용.
|
||
|
||
**작업** (emergency.md의 priority 순서 그대로)
|
||
1. P2: V4 후보 보존 + 3-status 분류 (auto_renderable / ai_adaptation_required / blocked_runtime).
|
||
2. P2.5: Section key alignment (child → parent pool merge universal policy).
|
||
3. P3: empty_shell terminal 제거 + generic_fallback mandatory. — generic fallback frame(three_parallel_requirements, 1171281190 하드코딩)이 모든 MDX 타입을 커버하는지 검증 포함.
|
||
4. P4: AI fallback 호출 trace 검증.
|
||
5. P5: Frontend candidate panel status surface.
|
||
|
||
**완료 조건**: mdx 01~05 전부 empty shell 없이 슬라이드 출력.
|
||
|
||
---
|
||
|
||
### C-2. V4 evidence 경로(PHASE_Z_B4_V4_EVIDENCE) end-to-end 배선
|
||
|
||
**배경**
|
||
- `_select_frame_v4_aware()`(placement_planner L180-285)와 selection_trace 필드까지 구현됐으나:
|
||
- env flag 기본 OFF에 call site에서 v4_candidates 전달 여부 미확인
|
||
- Step 11 trace 직렬화 wiring은 "u4 out of scope"로 명시적 미구현
|
||
- `partial_exists()` callback의 실제 호출처 없음
|
||
|
||
**작업**
|
||
1. plan_placement() 호출부에 v4_candidates 전달 + flag ON 경로 통합 테스트.
|
||
2. Step 11에서 selection_trace JSON 직렬화·응답 포함.
|
||
3. flag ON/OFF SHA parity 회귀 테스트(기존 test_b4_v4_evidence_off_sha_parity.py) 통과 유지.
|
||
|
||
**완료 조건**: flag ON 실행에서 V4 rank 기반 frame 선택이 trace로 확인되고, OFF 시 기존 출력과 SHA 동일.
|
||
|
||
---
|
||
|
||
### C-3. pipeline_trace / ai_trace 백엔드-프론트 계약 검증
|
||
|
||
**배경**
|
||
- 프론트 PipelineTracePanel(신규 216줄)이 `RunMeta.pipeline_trace`, `ai_trace` 스키마(sections/units/zones, skip_reasons 등)를 기대하지만, **백엔드가 이 JSON을 실제 생성·응답에 포함하는지 미확인**.
|
||
- `ignoreUserOverrides` 플래그, `coverage_state`, `rationale.ai_adaptation_required` 등 신규 필드도 동일.
|
||
|
||
**작업**
|
||
1. 백엔드 응답과 프론트 타입(designAgentApi.ts) 필드 대조표 작성.
|
||
2. 누락 필드는 백엔드에서 생성 추가, 계약 테스트(스키마 검증) 1본 작성.
|
||
|
||
**완료 조건**: 실제 run에서 PipelineTracePanel이 전 섹션 상태를 표시.
|
||
|
||
---
|
||
|
||
### C-4. SlideCanvas.tsx 한글 주석 인코딩 손상 복구 (소형)
|
||
|
||
**배경**
|
||
- Front/client/src/components/SlideCanvas.tsx L1~80 부근 한글 주석이 깨진 채 커밋됨 ("?ㅼ젣", "?쒖떆" — CP949↔UTF-8 오변환 패턴). 기능 코드는 정상.
|
||
|
||
**작업**: 깨진 주석 복원(git 히스토리의 정상 버전 참조) 후 UTF-8로 재저장. 에디터/훅에 인코딩 고정 설정 검토.
|
||
|
||
**완료 조건**: 파일 전체 UTF-8 정상, diff에 주석 복원만 포함.
|
||
|
||
---
|
||
|
||
## 제안 우선순위 (의존 관계 기준)
|
||
|
||
| 순위 | 이슈 | 이유 |
|
||
|---|---|---|
|
||
| 1 | A-1 (변환기 통합) | 백업 없는 유실 위험 — 즉시 |
|
||
| 2 | C-1 (Emergency P2~P5) | 진행 중 작업, 정책 확정 상태 |
|
||
| 3 | B-1 (02-2.2 교정) | 1~2일로 TARGET 4/4 |
|
||
| 4 | C-2 (V4 evidence 배선) | 이미 절반 구현된 코드 완성 |
|
||
| 5 | C-3 (trace 계약) + C-4 (인코딩) | 프론트 검증 기반 확보 |
|
||
| 6 | B-4 (슬롯 매핑 배선) | "의미 반영" 목표의 핵심 |
|
||
| 7 | A-2 (frame 32개 완성) | 매칭 성공해도 렌더 불가인 갭 해소 |
|
||
| 8 | B-2, B-3 (분류 LLM화, V4 재조정) | 정확도 상한 돌파 |
|
||
| 9 | B-5 (표/이미지), A-3 (추적성) | 커버리지·품질 보강 |
|