C.E.L_Slide_test2/docs/architecture/IMP-04-FRAME-SUITABILITY-MATRIX.md

# IMP-04 Frame Suitability Matrix (32 frames)

> Phase Z runtime catalog 확장 (IMP-04) 의 per-frame 진단 + Phase Z mapping
> proposal. Codex #15337 + #15340 의 추천 *32-frame schema suitability matrix*
> 답. impl 전 prerequisite 자료.
>
> **본 matrix scope** : Phase Z runtime catalog (executable projection) 으로의
> mapping. *matching schema canonical decision* (Codex #15340 의 architectural
> question) 은 별 axis (IMP-05+) 이양 — 본 doc 에 포함 X.
>
> Source-of-truth :
> - V4 evidence : `tests/matching/v4_full32_result.yaml` (32 unique template_ids,
>   320 judgments)
> - per-frame analysis : `figma_to_html_agent/blocks/{frame_id}/analysis.md`
> - per-frame visual : `figma_to_html_agent/blocks/{frame_id}/{index.html,flat.md,assets/}`
>
> Generated : 2026-05-13 / scope-lock = Gitea #4 round 6 (32 frame all-in,
> remaining 28).

---

## §0. Architecture context — 3-layer (Codex #15477 정정)

본 matrix 의 모든 결정은 다음 3-layer 분리 위에 있음 :

| layer | 역할 | 본 matrix 안 위치 |
|---|---|---|
| **V4** | matching basis / design-selection **authority**. keyword / content / structure / intent / frame suitability 평가 + 후보 ranking (use_as_is / light_edit / restructure / reject) | §1 V4 신호 / §3 frame ordering 의 기초 |
| **figma_to_html** | rich source / evidence layer. visual hierarchy / assets / layer structure / geometry / source intent / provenance | §1 resource inventory / §3 per-frame audit |
| **Phase Z** | runtime orchestration / assembly / recovery layer. V4 후보 consume → slide/zone/content flow assemble. fit / 가벼운 repair / resize / artifact / preview / reject routing / popup / AI fallback | §3 mapping proposal / §4 Track A activation |

**핵심** :
- ❌ "Phase Z = matching basis" 는 **잘못된 framing** (자체 round 26 의 자체 정정 사항)
- ✅ "V4 = matching authority. figma_to_html = source evidence. Phase Z = runtime projection" 이 정확한 분리
- IMP-04 의 작업 (catalog 등록 / partial 작성 / runtime activation) 은 Phase Z 영역. 단 *matching legitimacy* 는 V4 에서. *frame metadata* 는 figma_to_html 에서

→ 본 matrix 의 *비교/결정* 은 *3-layer 분리* 전제. 2-layer dichotomy 표현이 잔존하면 *wording fix 대상*.

---

---

## §1. 요약 통계

| axis | count |
|---|---|
| V4 32 unique templates | 32 |
| Active (이미 Phase Z 등록) | 4 |
| Remaining (본 issue 작업 대상) | 28 |
| `analysis.md` 보유 | 32/32 |
| `texts.md` 보유 | 32/32 |
| `index.html` 보유 (visual base) | 20/32 — **12 missing** |
| `flat.md` 보유 | 21/32 — 11 missing |
| `assets/` 디렉토리 보유 | 20/32 |

**Decision 분류** (본 matrix 결과) :

- **ACTIVE** (4) — 이미 Phase Z catalog 활성
- **reusable-now** (16) — `index.html` 보유 → Track A visual activation 가능
- **visual-pending** (12) — `index.html` 부재 → Track B (별도 처리 필요)

**Family 분포** :

| family | count | examples |
|---|---|---|
| cards | 12 | persona-3col, cards-3-category, paired-rows-2x2, quadrant-4, ... |
| table | 5 | table-2col, table-3col, compare-rows, ... |
| compare | 4 | 2col-paired-list, central-split-synthesis, banner-top-2col-bottom, cards-3-compare |
| diagram | 5 | cycle-3way-intersection, quadrilateral-relations, radial-diagram-5, ... |
| list | 3 | list-numbered-4, list-stacked-vertical, 3-column |
| map | 1 | full-page-map-banner |
| composite | 1 | central-5-goals |
| compare (별 grouping) | rest |

**Cardinality 분포** (ideal) :

| ideal | count | comment |
|---|---|---|
| 2 | 5 | compare-2-way (table-2col, banner-top-2col-bottom, etc.) |
| 3 | 11 | cards-3col, cards-3-category, list-3-column, persona-3col, ... |
| 4 | 8 | quadrant-4, paired-rows-2x2, cards-4-grid, ... |
| 5 | 3 | radial-5, central-5-goals, list-stacked-5 |
| 6 | 1 | circular-nodes-6 |
| 1 | 1 | full-page-map-banner |

---

## §2. ACTIVE 4 frames (이미 Phase Z 등록)

> **Fix 1** (Codex #15345 — wording precision) : "ACTIVE" = catalog-registered /
> runtime-active. *resource completeness (A+T+I+F+S 5 자원 보유) 와 별 axis*.
> F13 (`three_parallel_requirements`) 는 ACTIVE 이지만 `assets/` 부재.

| template_id | frame_id | fn | family / layout | builder | partial | resource status (A/T/I/F/S) |
|---|---|---|---|---|---|---|
| `three_parallel_requirements` | 1171281190 | 13 | list / 3-column | `items_with_role` + `pillar_item` | `f13b` (157 lines) | A T I F **−** (assets 부재) |
| `process_product_two_way` | 1171281210 | 29 | compare / banner-top-2col-bottom | `process_product_pair` | `f29b` (294 lines) | A T I F S |
| `bim_issues_quadrant_four` | 1171281193 | 16 | cards / quadrant-4 | `quadrant_flat_slots` + `quadrant_item` | `f16b` (223 lines) | A T I F S |
| `three_persona_benefits` | 1171281191 | 14 | cards / persona-3col | `items_with_role` + `quadrant_item` | `f14b` (110 lines, **refinement 필요** — index.html base 안 씀) | A T I F S |

---

## §3. Remaining 28 frames — Phase Z mapping matrix

각 frame 의 :
- **figma_to_html 자원 status** (`A`=analysis.md, `T`=texts.md, `I`=index.html, `F`=flat.md, `S`=assets/) — `-` = 부재
- **V4 신호** (use_as_is/light_edit/restructure/reject)
- **Phase Z mapping proposal** (source_shape, builder)
- **decision** (reusable-now / visual-pending)

### §3.1 reusable-now (16 frames — `index.html` 보유)

| template_id | fid | fn | family / layout | card (ideal) | slots | V4 (UAI/LE/RS/RJ) | proposed source_shape | proposed builder | decision |
|---|---|---|---|---|---|---|---|---|---|
| `app_sw_package_vs_solution` | 1171281203 | 23 | table / table-2col | 2 | 4 | 0/0/1/9 | top_bullets | new (compare_table_2col) | reusable-now |
| `bigroom_system_components` | 1171281178 | 7 | compare / 2col-paired-list | 2 | 5 | 0/0/0/10 | top_bullets | `process_product_pair` (재사용?) or new | reusable-now |
| `bim_adoption_central_split` | 1171281208 | 27 | compare / central-split-synthesis | 2 | 5 | 0/0/2/8 | top_bullets | new (split-synthesis) | reusable-now |
| `bim_current_problems_paired` | 1171281194 | 17 | cards / paired-rows-2x2 | 4 | 9 | 0/0/1/9 | top_bullets | `quadrant_flat_slots` 변형 or new | reusable-now |
| `bim_dx_comparison_table` | 1171281195 | 18 | table / compare-rows | 2 | 4 | **1**/0/0/9 | top_bullets | new (compare_table_2col) | reusable-now |
| `construction_bim_three_usage` | 1171281182 | 11 | cards / cards-3-category | 3 | 7 | **1**/0/1/8 | top_bullets | `items_with_role` + `quadrant_item` (재사용) | reusable-now |
| `construction_goals_three_circle_intersection` | 1171281189 | 12 | diagram / cycle-3way-intersection | 3 | 5 | **1**/**1**/1/7 | top_bullets | new (cycle-intersect-3) | reusable-now |
| `dx_sw_necessity_three_perspectives` | 1171281198 | 20 | cards / cards-3-header | 3 | 7 | 0/**2**/1/7 | top_bullets | `items_with_role` + `quadrant_item` (재사용) | reusable-now |
| `engn_sw_three_types` | 1171281204 | 24 | table / table-3col | 3 | 5 | 0/**1**/0/9 | h3_subsections | new (compare_table_3col) | reusable-now |
| `info_management_what_how_when` | 1171281179 | 8 | cards / 3-section-framework | 3 | 7 | 0/0/0/10 | top_bullets | `items_with_role` + `quadrant_item` (재사용) | reusable-now |
| `model_specialized_engn_sw` | 1171281202 | 22 | diagram / split-panel-numbered | 3-4 | 5 | 0/0/1/9 | top_bullets | new (split-panel) | reusable-now |
| `overseas_bim_numbered_list` | 1171281174 | 3 | list / list-numbered-4 | 4 | 5 | 0/0/0/10 | top_bullets | `items_with_role` 변형 (numbered) | reusable-now |
| `pre_construction_model_info_stacked` | 1171281180 | 9 | list / list-stacked-vertical | 5 (min 4 max 6) | 3 | 0/0/0/10 | top_bullets | `items_with_role` (재사용, flexible card) | reusable-now |
| `solution_engn_split_diagram` | 1171281201 | 21 | diagram / split-panel-diagram | 4 (min 3 max 5) | 4 | 0/0/3/7 | top_bullets | new (split-panel) | reusable-now |
| `sw_development_cycle_six_nodes` | 1171281172 | 1 | diagram / circular-nodes-6 | 6 | 7 | 0/0/0/10 | top_bullets | new (circular-6) | reusable-now |
| `sw_reality_three_emphasis` | 1171281209 | 28 | cards / title-plus-3-emphasis | 3 | 7 | 0/0/0/10 | top_bullets | `items_with_role` + `quadrant_item` (재사용) | reusable-now |

### §3.2 visual-pending (12 frames — `index.html` 부재)

| template_id | fid | fn | family / layout | card (ideal) | slots | V4 (UAI/LE/RS/RJ) | resource status | decision |
|---|---|---|---|---|---|---|---|---|
| `commercial_sw_four_categories` | 1171281205 | 25 | cards / left-categories-right-logos | 4 | 6 | 0/0/0/10 | A T - - - | visual-pending |
| `compensation_complaint_map` | 1171281177 | 6 | map / full-page-map-banner | 1 | 2 | 0/0/0/10 | A T - - - | visual-pending |
| `compensation_complaint_side_card` | 1171281176 | 5 | cards / side-card-with-list | 3 (min 3 max 5) | 4 | 0/0/0/10 | A T - - - | visual-pending |
| `design_method_distortion_three_col` | 1171281197 | 19 | compare / cards-3-compare | 3 | 7 | 0/0/0/10 | A T - - - | visual-pending |
| `domestic_bim_actor_relations` | 1171281175 | 4 | diagram / quadrilateral-relations | 4 | 6 | 0/0/1/9 | A T - - - | visual-pending |
| `engn_sw_development_domain_knowledge` | 1171281173 | 2 | cards / bullet-cards-4-plus-center | 4 | 7 | 0/0/0/10 | A T - - - | visual-pending |
| `field_effectiveness_five_elements` | 1171281181 | 10 | diagram / radial-diagram-5 | 5 | 6 | 0/0/0/10 | A T - - - | visual-pending |
| `industry_characteristics_three_col` | 1171281212 | 31 | table / table-3col | 3 | 5 | 0/0/0/10 | A T - - - | visual-pending |
| `industry_current_status_three_col` | 1171281211 | 30 | table / table-3col | 3 | 5 | 0/0/0/10 | A T - - - | visual-pending |
| `policy_achievement_five_goals` | 1171281213 | 32 | composite / central-5-goals | 5 | 9 | 0/0/0/10 | A T - - - | visual-pending |
| `policy_goals_plus_execution_requirements` | 1171281192 | 15 | cards / policy-4card-plus-list | 4 | 10 | 0/0/0/10 | A T - - - | visual-pending |
| `sw_dependency_four_problems` | 1171281206 | 26 | cards / cards-4-grid | 4 | 9 | 0/**1**/1/8 | A T - F - | visual-pending (index 부재, flat 있음) |

---

## §4. Track 분리 (matrix 기반)

### Track A — Visual activation (16 reusable-now + 1 active refinement)

> **Fix 4** (Codex #15345 — Track A priority wording) : 본 priority 순서 =
> **execution ordering only. scope filter X**. *all 16 reusable-now frames 활성
> 대상*. V4 신호 약한 11 frame 도 모두 포함. builder family grouping 도 *secondary
> ordering* (Codex 허용 — 단 first refinement 의 calibration 결과 이후, 새 hidden
> filter 화 절대 X).

priority 진행 순서 (자체 추천 — V4 신호 ↑ 우선, builder 재사용 grouping 보조) :

1. **`three_persona_benefits` refinement** (active 1, V4 use_as_is=1) — index.html base 재작성. **first refinement = calibration point**
2. `dx_sw_necessity_three_perspectives` (LE=2 가장 높음, persona builder 재사용 가능)
3. `construction_goals_three_circle_intersection` (UAI=1+LE=1+RS=1, *새 builder cycle-intersect-3*)
4. `construction_bim_three_usage` (UAI=1, persona builder 재사용)
5. `bim_dx_comparison_table` (UAI=1, *새 builder compare_table_2col*)
6. 잔여 11 reusable-now (V4 신호 0 — catalog 확보 목적, builder 재사용 grouping 으로 ordering 가능)

> **Fix 5** (Codex #15345 — review granularity 명시) :
> - **첫 refinement** = Codex review 필수
> - **새 builder pattern** 도입 frame = Codex review 필수
> - **ambiguous mapping** frame = Codex review 필수
> - **shared catalog/builder logic** 영향 frame = Codex review 필수
> - **low-risk repeated** (proven builder, 단순 catalog entry) = small grouped commit 허용 (단 pattern proven 후)
>
> **Fix 6** (자체 catch 1, Codex #15371 — Calibration failure modes) : first
> refinement 의 Codex review 에서 issue 발견 시 escalation path :
> - **F1 — small styling/wording issue** : `index.html`-base approach valid, detail correction 만 필요 → *same-frame follow-up commit* + Codex re-review.
> - **F2 — approach-level problem** : Phase Z geometry/runtime 와 fit 안 됨, raster/CSS/min-height rule 재정의 필요 → *Track A pause* → *approach re-lock round* → retry refinement.
> - **F3 — scope/resource problem** : figma_to_html output 부재 / visual-resource assumption 잘못 → *scope/resource axis reopen* → IMP-04b route 가능, *bulk activation 차단*.
>
> F1/F2/F3 = review escalation guide. *first refinement 차단 gate 아님*. trigger source = 보통 Codex review (Claude self-trigger 도 가능).

> **Fix 7** (Codex #15477 + #15485 — 4-class failure taxonomy as **primary**) :
> F1/F2/F3 는 *Phase Z 중심* 분류 (readiness / fit / scope conflate). Codex
> #15477 의 4-class 가 *V4 authority 보존 + readiness vs matching 분리* 측면에서
> 더 정확 — 본 matrix 의 **primary 기술 분류**.
>
> | # | Codex 4-class | 의미 | 자체 F1/F2/F3 mapping |
> |---|---|---|---|
> | 1 | **adapter/runtime readiness issue** | partial / asset path / slot adapter / contract missing. *V4 ranking 유효*. runtime-not-ready 로 표기 + implementation issue 등록 | F1 의 일부 + F3 의 일부 |
> | 2 | **content-fit issue** | candidate plausible 단 overflow / 가벼운 edit 필요. `runtime_reject` / `fit_failed` / `needs_light_edit` reason 부여 | F1 의 일부 + F2 의 일부 |
> | 3 | **V4 ↔ figma_to_html mapping issue** | candidate metadata / source mapping 잘못. mapping correction issue 등록 | F2 의 일부 |
> | 4 | **popup/secondary content routing case** | main frame 강요 X. popup / secondary content 로 별도 routing 후 그 부분 따로 매칭/디자인 | (자체 prior frame 없음) |
>
> **사용 원칙** :
> - 새 runtime issue 발생 시 — 4-class 로 *primary classify*. F1/F2/F3 는 *secondary review/process severity* 로만.
> - V4 가 *틀린 게 아닌가* 같은 짐작 금지 — 먼저 4-class 분류해서 *V4 vs adapter vs fit vs routing* 분리.
> - 자체 prior history reclassification :
>   - `556b448` (minimum viable persona) — class 1 (adapter readiness)
>   - `2fcd8bb` (strict CSS-only refinement) — class 2 (content/asset policy fit)
>   - `a1c06b7` (MDX02 chain dependency 발견) — class 1 (`construction_goals` catalog 미등록 = adapter readiness). *V4 logic 의 문제 아님*. construction_goals 등록 후 자연 해소
>   - 자체 round 26 "Phase Z = 실행 SoT" framing — wording error (matching authority = V4, *not* Phase Z)

### Track B — visual-pending 12 frames

> **Fix 2** (Codex #15345 — Track B wording 강화) : Track B 는 **exclusion / discard /
> scope reduction 아님**. visual-resource-pending 안 *32-frame scope 보존*. visual-
> resource 확보 *시점* 만 다른 별 axis.
>
> **Fix 3** (Codex #15345 — option (b) guard) : option (b) (minimal CSS) 는 **main
> path X, explicit temporary placeholder 만**. frame 1 사례와 같은 quality failure
> 위험.

option (a/b/c) 결정 필요 (user 확인) :

- **(a)** figma_to_html agent 재실행 → 별 issue (IMP-04b "visual extraction"). 32-frame scope 안.
- **(b)** analysis.md + texts.md 만으로 minimal CSS partial 작성 — **main path X. explicit temporary placeholder 만 허용**. 시각 디테일 손실 인정.
- **(c)** 본 issue 의 *즉시 활성* = 16 frame. 12 frame 은 IMP-04b 별 axis 에서 *visual base 확보 후* 활성. **32-frame scope 보존**.

자체 추천 = **(c)** — 32-frame scope 보존 + Track A 진행 속도 ↑ + Track B 의 visual extraction 작업과 분리.

### Track C — Matching schema canonical decision (Codex #15340)

본 matrix scope 외. IMP-05 또는 별 architectural axis 로 이양. 본 doc 에 권장 사항 surface 만 :

- figma_to_html / matching metadata = canonical matching knowledge source
- Phase Z frame_contracts + partial builders = runtime executable projection
- bridge/mapping layer = explicit conversion

---

## §5. Builder 재사용 vs 새 builder 분석

### §5.1 기존 4 builder

- `items_with_role` (F13) — array of items with `role_order` mapping. `pillar_item` parser uses sub-sections.
- `process_product_pair` (F29) — 2 named columns with sections, `column_with_transform` + `column_plain` parsers.
- `quadrant_flat_slots` (F16) — flat keyed positional slots (`quadrant_N_label` / `quadrant_N_body`).
- `quadrant_item` parser — `{label, body:[{text,indent}]}` flat list.

### §5.2 재사용 가능 (Track A 안 builder 재사용 candidates)

| pattern | example frames | builder | parser |
|---|---|---|---|
| 3 cards parallel (단순 label + body) | persona, dx_sw_necessity, construction_bim_usage, info_mgmt, sw_reality | `items_with_role` | `quadrant_item` (재사용) |
| 4 quadrant flat | bim_current_problems (4 grid), sw_dependency (4 grid — visual-pending) | `quadrant_flat_slots` 변형 (4-card grid) | `quadrant_item` (재사용) |
| numbered list (1..N) | overseas_bim, pre_construction_model_info | `items_with_role` (no role) | `pillar_item` 또는 new |

### §5.3 새 builder 필요

| pattern | example frames | proposed builder |
|---|---|---|
| 2-col compare table | app_sw_package_vs_solution, bim_dx_comparison_table | `compare_table_2col` |
| 3-col compare table | engn_sw_three_types (+ visual-pending: industry_*) | `compare_table_3col` |
| cycle/circle diagram | construction_goals_three_circle_intersection | `cycle_intersect_3` |
| split-panel diagram | model_specialized_engn_sw, solution_engn_split | `split_panel` |
| circular nodes | sw_development_cycle_six_nodes | `circular_nodes_n` |
| paired 2x2 | bim_current_problems_paired | `paired_rows_2x2` |
| central split synthesis | bim_adoption_central_split | `central_split_synthesis` |

→ **새 builder 7+ 필요** (Track A 안). 일부 generic 화 가능성 — *implementation 시 구체화*.

---

## §6. min_height_px derivation method

기존 catalog : F13=230, F29=345, F16 = (no visual_hints — default zone size 사용?)

본 matrix 의 frame 별 `min_height_px` 추정 method :

- `figma_to_html_agent/blocks/{frame_id}/flat.md` 의 *frame 원본 height* × Phase Z slide-body scale = derived min height
- 예 : persona frame_id 1171281191 = 1927 px × (1280/2601) = 1927 × 0.49213 = 949 px (그러나 Phase Z slide-body 는 585 px 한계 — zoom 또는 scale 추가 적용 필요)
- 실제 measurement = impl 시 partial render 후 검증 (smoke harness 가 char count 측정)

→ 각 frame impl 시 *index.html 의 R19 zoom 값* 또는 *flat.md 의 frame 원본 height* 에서 derive. handoff #15321 §4 의 8-step 의 1 단계로 추가.

---

## §7. Resource completeness summary

| status | count | template_ids |
|---|---|---|
| Full (A+T+I+F+S) | 19 | (16 reusable-now 중 15 + active 4 중 4) |
| index 있음, assets 없음 | 1 | `three_parallel_requirements` (F13 active) |
| A+T+F (index 부재) | 1 | `sw_dependency_four_problems` (visual-pending, flat 만 있음) |
| A+T (visual 모두 부재) | 11 | 위 §3.2 의 나머지 11 visual-pending |

→ visual-pending 12 frame 중 1 (`sw_dependency_four_problems`) 은 *flat.md 보유* — 약간 head-start. 나머지 11 은 figma_to_html agent 재실행 필요.

---

## §8. 다음 단계 — user 확인 후 ㄱ

1. 본 matrix 가 *prerequisite 자료* 로 충분한가? 추가 추출 필요 정보?
2. Track B option (a/b/c) 합의 — 자체 추천 = (c) 본 issue 외 분리
3. Track A 진행 순서 — §4.1 의 priority list 합의?
4. Track C (matching schema canonical) IMP-05+ 분리 합의?
5. impl 시 build 순서 — frame 별 sequential commits + Codex per-frame review 또는 batch review?

100% 합의 후 step 6 (Track A 진입 — `three_persona_benefits` refinement 부터) 시작.