# Phase I: 전수 정합성 복구 + 10가지 런타임 문제 해결 — 실행 상세

> 전수 검토에서 발견된 프롬프트 자기모순, 문서-코드 불일치, 코드 안전망 부족을 해결.
> 원칙: 하드코딩 금지. 범용 해결. 회귀 금지. persona_agent 수정 0건.

---

## 문제 진단 총괄

### 전수 검토에서 발견된 근본 원인

**실제 블록 수: 38개** (문서는 46개로 표기)
삭제된 8개: card-text-grid, quote-left-border, conclusion-accent-bar, details-block, layer-diagram, timeline-vertical, timeline-horizontal, pyramid-hierarchy

이 8개가 삭제되었지만 프롬프트, catalog, INDEX.md, README.md에 여전히 참조되고 있음.
→ AI가 존재하지 않는 블록을 선택 → 부적절한 강제 교체 → 빈 블록, 잘못된 배치

---

## 패턴 A: 프롬프트 자기모순 (문제 2, 7)

### I-1: STEP_B_PROMPT purpose 가이드에서 미존재 블록 제거

**현재 문제:**
```python
# design_director.py 264~271행
"- 근거사례 → quote-left-border, card-text-grid"     ← 둘 다 미존재!
"- 용어정의 → card-text-grid"                        ← 미존재!
"- 구조시각화 → venn-diagram, layer-diagram"          ← layer-diagram 미존재!
```

허용 목록에는 없는데 purpose 가이드에서 적극 추천 → **프롬프트 자기모순** → Sonnet이 미존재 블록 선택

**수정:**
```
- 근거사례 → quote-big-mark (출처 포함), card-icon-desc (항목 나열)
- 용어정의 → card-icon-desc (정의+출처), card-numbered (순서 있으면)
- 구조시각화 → venn-diagram (단독 배치)
```

**수정 파일:** src/design_director.py (STEP_B_PROMPT)

---

### I-2: catalog.yaml의 not_for/when에서 미존재 블록 참조 제거

**현재 문제:**
- circle-gradient not_for: "topic-header" → 실제 이름은 topic-left-right/topic-center/topic-numbered
- circle-gradient not_for: "conclusion-accent-bar" → 미존재. 실제는 banner-gradient
- process-horizontal not_for: "timeline" → 미존재. 실제 없음 (삭제됨)

**수정:** catalog.yaml 전체에서 미존재 블록 참조를 실존 블록으로 교체

**수정 파일:** templates/catalog.yaml

---

### I-3: 미등록 블록 교체를 purpose 기반으로 변경

**현재 문제:**
```python
# design_director.py 574행
block["type"] = "callout-solution"  # 모든 미등록 블록을 일괄 교체
```

결론 꼭지의 미등록 블록도 callout-solution으로 교체 → 의미적으로 부적절

**수정:** purpose 기반 교체 맵
```python
PURPOSE_FALLBACK = {
    "문제제기": "callout-warning",
    "근거사례": "quote-big-mark",
    "핵심전달": "comparison-2col",
    "용어정의": "card-icon-desc",
    "결론강조": "banner-gradient",
    "구조시각화": "card-icon-desc",
}
# 미등록 블록 거부 시: block의 purpose를 보고 적절한 대체 블록 선택
fallback_type = PURPOSE_FALLBACK.get(block.get("purpose", ""), "callout-solution")
```

**수정 파일:** src/design_director.py

---

## 패턴 B: 슬롯 의미 정보 미전달 (문제 3, 5, 9, 10)

### I-4: BLOCK_SLOTS에 slot_desc 추가

**현재 문제:**
편집자가 슬롯 이름만 받고 의미를 모름:
- source에 출처가 아닌 꼭지 제목을 넣음 (문제 3)
- text/sub_text 순서를 뒤집음 (문제 5)
- rows[][] 배열 구조를 채우지 못함 (문제 9)
- cards[] 배열 구조를 채우지 못함 (문제 10)

**수정:** BLOCK_SLOTS에 slot_desc 필드 추가
```python
"quote-big-mark": {
    "required": ["quote_text"],
    "optional": ["source"],
    "slot_desc": {
        "quote_text": "인용할 본문 텍스트",
        "source": "출처 (예: 국토교통부, 2024). 꼭지 제목이 아님!",
    },
},
"banner-gradient": {
    "required": ["text"],
    "optional": ["sub_text"],
    "slot_desc": {
        "text": "핵심 결론 한 줄 (굵은 대형 텍스트. 가장 중요한 메시지)",
        "sub_text": "부연 설명 (작은 보조 텍스트. text보다 덜 중요)",
    },
},
"compare-2col-split": {
    "required": ["left_title", "right_title", "rows"],
    "optional": [],
    "slot_desc": {
        "left_title": "왼쪽 열 헤더",
        "right_title": "오른쪽 열 헤더",
        "rows": "비교 행 배열. 각 행: {criteria: '비교 기준', left: '왼쪽 내용', right: '오른쪽 내용'}. 최소 3행.",
    },
},
```

**수정 범위:** 38개 블록 모두에 slot_desc 추가 (가장 큰 작업)

### I-5: 편집자 프롬프트에 slot_desc 전달

**현재:** content_editor.py 87~88행
```python
f"  필수 슬롯: {slots.get('required', [])}\n"
f"  선택 슬롯: {slots.get('optional', [])}"
```

**수정:**
```python
f"  필수 슬롯: {slots.get('required', [])}\n"
f"  선택 슬롯: {slots.get('optional', [])}\n"
# slot_desc가 있으면 각 슬롯의 의미 전달
slot_desc = slots.get("slot_desc", {})
if slot_desc:
    desc_lines = [f"    {k}: {v}" for k, v in slot_desc.items()]
    req_text += "\n  슬롯 설명:\n" + "\n".join(desc_lines)
```

**수정 파일:** src/content_editor.py, src/design_director.py (BLOCK_SLOTS)

---

## 패턴 C: 코드 안전망 부족 (문제 1, 4, 6, 8)

### I-6: 제목 유사도 검증 (문제 1)

**현재:** 프롬프트에 "달라야 한다"고 지시했지만 코드 검증 없음

**수정:** pipeline.py 또는 design_director.py에서 `analysis["title"]`과 `analysis["topics"][0]["title"]` 비교
```python
from difflib import SequenceMatcher
title = analysis.get("title", "")
first_topic_title = analysis.get("topics", [{}])[0].get("title", "")
similarity = SequenceMatcher(None, title, first_topic_title).ratio()
if similarity > 0.7:
    # 첫 꼭지 제목을 purpose 기반으로 변경
    first_topic = analysis["topics"][0]
    purpose = first_topic.get("purpose", "문제제기")
    first_topic["title"] = f"{purpose}: {first_topic.get('summary', '')[:30]}"
    logger.warning(f"[제목 중복 교정] 유사도 {similarity:.0%} → 첫 꼭지 제목 변경")
```

**수정 파일:** src/pipeline.py

### I-7: compare-pill-pair 단독 사용 금지 (문제 4)

**현재:** compare-pill-pair가 비교 내용 없이 라벨만 표시

**수정:** _validate_height_budget() 안에서 compare-pill-pair가 해당 zone에서 유일한 "비교" 블록이면 경고
```python
# compare-pill-pair는 비교 테이블의 헤더로만 사용
# 같은 zone에 compare-2col-split, compare-3col-badge, comparison-2col이 없으면 부적절
COMPARISON_BLOCKS = {"compare-2col-split", "compare-3col-badge", "comparison-2col"}
for area, area_blocks in zone_blocks.items():
    types = {b.get("type") for b in area_blocks}
    if "compare-pill-pair" in types and not types & COMPARISON_BLOCKS:
        # pill-pair를 comparison-2col로 교체
        for block in area_blocks:
            if block.get("type") == "compare-pill-pair":
                block["type"] = "comparison-2col"
                logger.warning(f"[pill-pair 단독 금지] compare-pill-pair → comparison-2col")
```

**수정 파일:** src/design_director.py

### I-8: 대형 테이블 → detail_target 자동 설정 (문제 6)

**현재:** 원본의 12행 비교표가 detail_target으로 잡히지 않음

**수정:** pipeline.py에서 1단계-B 완료 후
```python
for table in analysis.get("tables", []):
    if table.get("rows", 0) >= 5 and not table.get("fits_single_page", True):
        for topic in analysis.get("topics", []):
            if topic.get("id") == table.get("topic_id"):
                if not topic.get("detail_target"):
                    topic["detail_target"] = True
                    logger.info(f"대형 테이블 → detail_target 자동: topic {topic['id']}")
```

**수정 파일:** src/pipeline.py

### I-9: DOWNGRADE_MAP 확장 + 다단계 교체 (문제 8)

**현재:** body 높이 600px > 490px인데 medium 블록 교체 대상 없음

**수정:**
1. medium → compact 교체 맵 추가
2. 교체 임계치 `>= 250` → `>= 150`으로 낮춤
3. 1회 교체 후에도 초과이면 다음 블록도 교체 (현재는 break)

```python
DOWNGRADE_MAP = {
    # 기존 large/xlarge → medium/compact
    "venn-diagram": "card-icon-desc",
    "card-step-vertical": "card-numbered",
    ...
    # 추가: medium → compact
    "quote-big-mark": "divider-text",
    "comparison-2col": "compare-pill-pair",  # 주의: I-7 규칙과 함께 적용
    "process-horizontal": "flow-arrow-horizontal",
    "dark-bullet-list": "highlight-strip",
    "card-icon-desc": "highlight-strip",
}
```

**수정 파일:** src/design_director.py

---

## 문서 동기화

### I-10: INDEX.md 동기화 (38개 실제 현황)

미존재 8개 블록 항목 제거: card-text-grid, quote-left-border, conclusion-accent-bar, details-block, layer-diagram, timeline-vertical, timeline-horizontal, pyramid-hierarchy

**수정 파일:** templates/blocks/INDEX.md

### I-11: README.md 동기화

- "46개 + _legacy 13개" → "38개"
- Sonnet fallback 표기 제거 (Phase G에서 제거됨)
- 블록 트리 구조에서 미존재 블록 제거
- 각 카테고리 개수 수정: cards 9, visuals 6, emphasis 10

**수정 파일:** README.md

### I-12: BLOCK_SLOTS 주석 수정

- "visuals/ (10개)" → "visuals/ (6개)"
- "emphasis/ (12개)" → "emphasis/ (10개)"

**수정 파일:** src/design_director.py (주석만)

### I-13: 데드 코드 정리

- `_call_anthropic_direct()` 함수 제거 (kei_client.py) — G-2에서 호출 제거했지만 함수 자체는 잔존

**수정 파일:** src/kei_client.py

---

## 수정 파일 총괄

| 파일 | 항목 | 변경 성격 |
|------|------|----------|
| `src/design_director.py` | I-1, I-3, I-7, I-9, I-12 | purpose 가이드 교체 + 교체 맵 개선 + pill-pair 검증 + DOWNGRADE 확장 + 주석 |
| `src/design_director.py` (BLOCK_SLOTS) | I-4 | 38개 블록에 slot_desc 추가 |
| `src/content_editor.py` | I-5 | 편집자에게 slot_desc 전달 |
| `src/pipeline.py` | I-6, I-8 | 제목 유사도 + detail_target 자동 |
| `src/kei_client.py` | I-13 | 데드 코드 제거 |
| `templates/catalog.yaml` | I-2 | not_for 미존재 블록 참조 교체 |
| `templates/blocks/INDEX.md` | I-10 | 미존재 블록 제거 |
| `README.md` | I-11 | 블록 수 + fallback + 트리 구조 동기화 |

---

## 검증 체크리스트

- [ ] I-1: STEP_B_PROMPT의 purpose 가이드에 미존재 블록 0건
- [ ] I-2: catalog.yaml의 not_for/when에 미존재 블록 참조 0건
- [ ] I-3: 미등록 블록 교체가 purpose 기반으로 동작
- [ ] I-4: BLOCK_SLOTS 38개 블록 모두에 slot_desc 존재
- [ ] I-5: 편집자 프롬프트에 슬롯 설명 포함
- [ ] I-6: 제목 유사도 70% 이상 시 자동 교정
- [ ] I-7: compare-pill-pair 단독 사용 시 comparison-2col로 교체
- [ ] I-8: 5행 이상 테이블 → detail_target 자동 true
- [ ] I-9: body 높이 초과 시 medium 블록도 교체 가능
- [ ] I-10: INDEX.md에 미존재 블록 0건
- [ ] I-11: README.md 블록 수 38개, Sonnet fallback 표기 없음
- [ ] I-12: BLOCK_SLOTS 주석이 실제 개수와 일치
- [ ] I-13: _call_anthropic_direct() 함수 없음

---

## 수정 이력

| 날짜 | 내용 |
|------|------|
| 2026-03-26 | 초안. 전수 정합성 검토 기반 13개 항목. 3패턴(프롬프트 모순 + 슬롯 의미 + 코드 안전망) 분류. |