docs + V4 catalog + samples + Phase Q legacy 보존

전체 26 files (20 추가 + 6 수정), 10507 insertions. Phase Z 문서 : - docs/architecture/PHASE-Z-CHANGE-LOG.md (신설) — axis-by-axis 의사결정 history (newest-on-top). Step 7-A 부터 6 entry 박힘 + 2026-05-08 / 2026-05-08 #2 (compat 매트릭스 폐기 / 6-B 폐기 / F14 표현 정정 / label gate policy 분리). - docs/architecture/PHASE-Z-PIPELINE-OVERVIEW.md (수정) — Step 5/6/9 Gap note append (구조 무변, append-only). 6-B 폐기 사실 + Refinement F. - docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md (수정) — snapshot date 2026-05-08 갱신. §3 핵심 missing item 5 (Step 5/6/9 boundary axis breakdown + 폐기 기록). §6 한 줄 갱신 — 다음 axis 후보 A~F. Project root docs : - PLAN.md / PROGRESS.md / README.md (수정) — 토큰 체계 / 폴더 구조 / 설계 문서 / 역할 분리 반영. - IMPROVEMENT-REDESIGN.md (신설) — Phase Z 설계 핵심 문서. - PROCESS_OVERVIEW.html (신설) — 파이프라인 개요 시각. - docs/tasks/* (신설) — Phase Z task 문서. V4 catalog (Phase Z runtime 필수 의존성) : - tests/matching/v4_full32_result.yaml (신설, 4888 줄) — V4 매칭 결과 32 frame × 10 MDX section. lookup_v4_match() / lookup_v4_candidates() 가 본 파일 read. Phase Z runtime 이 *없으면 즉시 abort* — clone 후 즉시 동작 가능 보장. Samples : - samples/mdx_batch/04.mdx (신설) — MDX04 기본 sample. - samples/mdx/04. DX 지연 요인.mdx (신설) — MDX04 원본. Phase Q legacy 보존 (별 axis "Phase Q audit & salvage" 영역) : - src/block_matcher_tfidf.py / catalog_blocks.py / frame_extractor.py / pipeline_v2.py — Phase Q (옛 파이프라인) src 신규 untracked 파일들. Phase Z runtime 와 의존성 0. Phase Q audit axis 에서 검토 예정. - scripts/eval_block_matcher.py / fetch_all_frame_screenshots.py / match_17_units_my_matcher.py / match_mdx_strict.py / match_mdx_to_frames_tfidf.py / ocr_augment_texts.py / run_pipeline_v2.py / previews/ — Phase Q 작업 시 사용한 옛 script. 같이 보존. - run_mdx03_pipeline.py (수정) — Phase Q 진입점 (no flag) + Phase Z 진입점 (--phase-z2 flag) 동시 wrapper. Phase Z 만 사용 시 `python -m src.phase_z2_pipeline samples/mdx_batch/03.mdx <run_id>` 직접 호출. 비-scope : - tests/matching/ (v4_full32_result.yaml 외 ~63MB) — V4 진화 history / reports / DECK / ATTACH. Phase Q audit axis 에서 검토. - tests/pipeline/ (~15MB) — pipeline data. Phase Q audit 영역. - templates/catalog/blocks.yaml — 옛 block catalog. Phase Q audit. - templates/phase_z2/frames/ — 옛 frame partial 위치. Phase Q audit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-08 09:47:58 +09:00
parent ec83405770
commit 85c680f02a
26 changed files with 10507 additions and 46 deletions
--- a/docs/architecture/PHASE-Z-CHANGE-LOG.md
+++ b/docs/architecture/PHASE-Z-CHANGE-LOG.md
@@ -0,0 +1,226 @@
+# Phase Z — change log
+
+**역할** : axis-by-axis 의사결정 / reframe / 폐기 / lock 의 *history* 기록.
+
+**관련 문서** :
+- [`PHASE-Z-PIPELINE-OVERVIEW.md`](PHASE-Z-PIPELINE-OVERVIEW.md) — 22-step 도면 (구조 lock)
+- [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md) — 현재 snapshot (자주 갱신)
+- 본 문서 = 누적 history (newest-on-top, append-only)
+
+**본 문서의 목적** :
+- "왜 이 안을 폐기했는지" / "왜 이 axis 로 쪼갰는지" 의 회귀 시 trace
+- STATUS-BOARD 가 *현재* 라면 본 문서는 *과거*
+- entry 단위 = 한 axis (한 결정 단위)
+
+**format** :
+
+```
+## YYYY-MM-DD — Step X-Y / axis 이름
+
+scope:
+  - 무엇이 추가 / 변경 / 폐기됐나
+
+lock:
+  - 사용자 결정 lock
+
+why:
+  - 의사결정 근거 / 회귀 방지 사실
+
+next axis:
+  - 이어지는 다음 axis
+```
+
+---
+
+## 2026-05-08 #2 — axis naming / scope 정정 (6-B 폐기 + F14 표현 정정 + label gate policy 분리)
+
+scope:
+- **6-B (frame ownership transfer) 폐기** — misframed axis.
+- **"F14 / F11 / F18 frame contract 등록" 표현 폐기** — `V4 frame 후보 → Phase Z render path 연결 확장` 으로 rename.
+- **label gate policy 재검토 = 별 axis 로 분리** (= 6-B 안에 숨어 있던 진짜 content).
+- forex/status.md §0 Refinement F + §3 진행 순서 + §5 갱신.
+- `PHASE-Z-PIPELINE-STATUS-BOARD.md` §3 item 5 + §6 갱신.
+- `PHASE-Z-PIPELINE-OVERVIEW.md` Step 6 Gap note 정정.
+
+lock:
+
+[6-B 폐기]
+- V4 = frame 선택 (점수 + label).
+- Step 6 = V4 rank-1 을 default 로 *전사* (선택 X, 전사).
+- Step 9 = V4 후보를 application_plan 으로 *번역* (재선택 X, 번역).
+- 따라서 "Step 6 의 frame 채택 책임을 Step 9 로 이전" = *허구* (Step 6 이 그런 책임을 원래부터 안 가짐).
+
+[F14 표현 정정 — 3 layer 분리 lock]
+- Figma → HTML 변환 (`figma_to_html_agent/blocks/`) = 32 frame 모두 끝 (이미 layer).
+- V4 catalog (`tests/matching/v4_full32_result.yaml`) = 32 frame 매칭 끝 (이미 layer).
+- Phase Z render path = F13 / F29 / F16 만 연결 — 나머지 미연결 (작업 layer).
+- 작업 = adapter 박기 (contract + partial + builder + fresh run 검증). *Figma 새 디자인 X / V4 새 매칭 X*.
+- frame 당 4 가지 entry :
+  1. `templates/phase_z2/catalog/frame_contracts.yaml` — contract entry.
+  2. `templates/phase_z2/families/{template_id}.html` — Phase Z runtime partial. *`figma_to_html_agent/blocks/{frame_id}/index.html` source 와 별도 layer* — slot/payload 받게 변형.
+  3. `src/phase_z2_mapper.py` — PAYLOAD_BUILDERS / ITEM_PARSERS entry.
+  4. fresh run 검증.
+
+[label gate policy 분리]
+- 현재 Step 6 의 `MVP1_ALLOWED_STATUSES = {matched_zone, adapt_matched_zone}` binary gate.
+- restructure / reject label = 자동 drop (현재).
+- 정책 question = restructure 도 unit 으로 살려둘지 / Step 9 v0 4-mode 해석으로 대체할지.
+- 자체 가치는 Step 17 / 19 fallback 또는 Step 9 v1 활성화 후 발현 — 단독 axis 가치 X.
+- 현 시점 = 별 axis 로 *명시* 만 (구현 axis X).
+
+why:
+- mental model 정정 = layer 책임을 정확히 박기.
+- 6-B 와 F14 표현 모두 layer 가 잘못 그려졌었음 — 같은 종류의 정정.
+- label gate 는 6-B 안에 숨어 있던 *진짜 axis* — 분리해서 추적성 확보.
+- compat 매트릭스 폐기 (2026-05-08 #1 entry) 와 같은 패턴 — *misframed axis 는 폐기 + history 박힘*.
+
+next axis (별 axis 후보 list):
+- (A) V4 frame 후보 → Phase Z render path 연결 확장 (F14 / F11 / F18 등 미연결 frame adapter)
+- (B) Step 17 details_popup_escalation 구현
+- (C) Step 4 unit_count 산출 logic
+- (D) Step 3 / 4 render path 활성화 (Layer A activation)
+- (E) label gate policy 재검토 (= 6-B 의 진짜 content 였던 것)
+- (F) Step 9 v1 scoring + auto decision
+
+---
+
+## 2026-05-08 — Step 5/6/9 boundary reframe
+
+scope:
+- Step 9 의 *"compat 매트릭스" 안 폐기* (region × frame slot count 표) — V4 cardinality 재계산 위험.
+- Step 9 = **application_plan** 으로 reframe — V4 후보 + layout/region/display 통합 *적용 계획* (V4 axis 재계산 X).
+- Step 5/6/7/8/9 boundary 재정리 — 진행 순서 lock = `5 → 6-A → 7-conn → 8-conn → 6-B → 9`.
+- Step 6 = `6-A` (additive, logic 무변) + `6-B` (logic 변화) 두 axis 로 분리.
+
+lock:
+- V4 점수 재계산 X — V4 의 anchor / cardinality / relation / slot / content 산식은 Step 5 에서 끝남.
+- V4 후보 삭제 X — Step 5 = non-reject max-6 후보 list (raw 32 entry 는 `tests/matching/v4_full32_result.yaml` 영속).
+- V4 label 존중 — Step 9 = label (use_as_is / light_edit / restructure / reject) → application_mode (direct_insert / same_frame_with_adjustment / layout_or_region_change / exclude) 변환.
+- 진행 순서 = 5 → 6-A → 7-conn → 8-conn → 6-B → 9 (risk 분산: 6-B 를 9 신설 직전으로 미룸).
+
+why:
+- V4 confidence 산식 (`tests/matching/template_fit.py`) 의 5 axis 가 이미 frame 자체 적합도 평가. compat 매트릭스 = 동일 axis 재계산 → 폐기 결정.
+- V4 가 *못* 보는 영역 = layout / zone / region / display / contract — 이게 Step 9 의 진짜 영역.
+- Step 6 가 V4 rank-1 즉시 frame 채택 + layout 일부 결정해버려서 Step 9 가 받을 candidate list 없음 → Step 5 (rank-1 → top-N) + Step 6 (frame 채택 빼기) 선행 reframe 필요.
+- 6-A / 6-B 분리 이유 = 6-A 는 schema 확장 (안전), 6-B 는 selection logic 변경 (위험). 함께 하면 위험 누적.
+
+next axis:
+- Step 5 보완 = `lookup_v4_candidates()` 추가 (non-reject max-6) + `step05_v4_evidence.json` schema 확장 (`v4_candidates` list + `candidate_status`).
+- backward compat 유지 = `lookup_v4_match()` (rank-1) 보존, Step 6 호출처 무변.
+
+---
+
+## 2026-05-07 — Step 8-B-2 / display strategy candidate function
+
+scope:
+- `select_display_strategy_candidates(content_type, long_text, large_table, fits_in_region)` 함수 추가.
+- `load_display_strategies()` + `DISPLAY_STRATEGIES` 모듈 변수 + `_KNOWN_CONTENT_TYPES` frozenset.
+- catalog (`templates/phase_z2/regions/display_strategies.yaml`) 의 `applies_to` / `forbidden_for` 직독 기반 hard filter.
+
+lock:
+- `text_block / table / image / details` → `dropped` 절대 X (catalog `forbidden_for` 박혀 있음 — 원문 무손실).
+- hard filter = catalog `applies_to` / `forbidden_for` 직독 (hardcoding X).
+- escalate signal (`long_text` / `large_table` / `fits_in_region == False`) → `inline_preview_with_details` 우선.
+- decorative_element 의 dropped 는 `inline_full` 후순위 (공간 부족 신호 전에는 일단 보여주기).
+- unknown content_type → `ValueError` (catalog scope 위반).
+
+why:
+- 8-A catalog 위에 candidate 함수 추가 = passive piece 패턴 (7-A/B + 8-A 와 일관).
+- 원문 무손실 lock 의 코드 enforcement.
+- Step 9 application_plan 의 display_strategy axis input.
+
+next axis:
+- Step 9 진입 시도 (compat 매트릭스 안) → 폐기 → boundary reframe (2026-05-08 entry 참조).
+
+---
+
+## 2026-05-07 — Step 8-B-1 / region layout candidate function
+
+scope:
+- `load_region_layouts()` + `REGION_LAYOUTS` 모듈 변수.
+- `select_region_layout_candidates(region_count, ..., ratio_asymmetric, ...)` 함수 추가 — SPEC §2.5 sequential first-match decision tree.
+- 6 entry catalog 와 1:1 일치 (catalog 직독, hardcoding X).
+
+lock:
+- `region_count < 1 or > 4` → `ValueError` (SPEC §2.5 vocabulary scope).
+- `region-vertical-stack` 만 `default_fallback: true` (SPEC 박힘).
+- `ratio_asymmetric` 게이트 = `region-main-support` 의 catalog `candidate_when` 과 1:1 일치 (initial 누락 → Codex 검출 → 박힘).
+- `region_count == 1` → `[region-single]` only (fallback X).
+
+why:
+- SPEC §2.5 결정 트리 6 entry 의 코드 enforcement.
+- catalog 와 함수 1:1 일치 (drift 방지) — 초기 ratio_asymmetric 시그니처 누락 발견 후 정정.
+- Step 9 application_plan 의 region axis input.
+
+next axis:
+- Step 8-B-2 (display strategy candidate function).
+
+---
+
+## 2026-05-07 — Step 8-A / regions catalog (region + display)
+
+scope:
+- `templates/phase_z2/regions/region_layouts.yaml` 신설 — SPEC §2.5 6 entry (region-single / vertical-stack / horizontal-split / main-support / preview-details / grid-2x2).
+- `templates/phase_z2/regions/display_strategies.yaml` 신설 — 4 entry (inline_full / inline_preview_with_details / details_only / dropped).
+- `templates/phase_z2/regions/regions_preview.html` 신설 — 6 region card + 4 display strategy card 시각 검증.
+
+lock:
+- **axis 분리** : region (structure) ≠ display (policy). 두 catalog 는 직교 — 같은 region 이 다른 display strategy 와 결합 가능.
+- **single source of truth** : `preserves_original` 은 display_strategies 의 책임 (region_layouts 에서 제거 — 사용자 검토 후 박힘).
+- `detail_trigger.placement: top-right` (사용자 lock — 본문 흐름 방해 X / 보조 동작 위치 / popup 진입 일관 위치).
+- `dropped` 의 `applies_to: [decorative_element]` only / `forbidden_for: [text_block, table, image, details]` (사용자 절대 룰 — 원문 무손실).
+- `inline_preview_with_details` / `details_only` 의 `preserves_original: true` (popup 안 원문 보존).
+
+why:
+- region 구조 vocabulary 와 display 정책 vocabulary 가 다른 axis. 한 catalog 에 합치면 단일 enum 필드로 표현 안 됨.
+- 사용자 절대 lock (text/table/image/details 절대 dropped X) 의 catalog enforcement.
+- 자유 디자인 금지 lock 과 정합 — preview HTML 에서 사람이 두 axis 시각 검증 가능.
+
+next axis:
+- Step 8-B-1 / 8-B-2 (각 catalog 의 candidate function).
+
+---
+
+## 2026-05-07 — Step 7-B / layout candidate function
+
+scope:
+- `select_layout_candidates(unit_count)` 함수 추가 — `templates/phase_z2/layouts/layouts.yaml` catalog 직독 + `unit_count` 매칭.
+- 출력 정렬 = `default_selection: true` 우선 + catalog 순서.
+
+lock:
+- 입력 = `unit_count` (Step 4 의 placement unit count = section_count + lead_orphan promotion).
+- `default_selection: true` 인 entry 가 list 의 첫 위치.
+- `unit_count` 매칭 entry 0 개면 빈 list (ValueError X — Step 9 가 fallback path 처리).
+
+why:
+- 명명 정정 = `section_count` → `unit_count` (lead_orphan promotion 후 의미 정확).
+- Step 9 application_plan 의 layout axis input (V4 후보 + layout 후보 통합 평가).
+- single-decision (`select_layout_preset`) 은 backward compat 으로 유지 — runtime 호출처는 default 만 사용.
+
+next axis:
+- Step 8-A (regions catalog).
+
+---
+
+## 2026-05-07 — Step 7-A / layout catalog 분리
+
+scope:
+- `templates/phase_z2/layouts/layouts.yaml` 신설 — 8 preset (single / horizontal-2 / vertical-2 / top-1-bottom-2 / top-2-bottom-1 / left-1-right-2 / left-2-right-1 / grid-2x2).
+- `templates/phase_z2/layouts/layouts_preview.html` 신설 — 8 preset 시각 검증.
+- `load_layout_presets()` 함수 추가 — catalog → 기존 `LAYOUT_PRESETS` 와 동일 dict shape 반환.
+- `src/phase_z2_composition.py` 의 hardcoded `LAYOUT_PRESETS` dict → catalog 이전 (logic 무변, backward compat).
+
+lock:
+- **필드 정정** = 단일 `status` enum (implemented / defined) → 두 직교 axis 필드로 분리:
+  - `render_ready: bool` — layout 의 grid 정의 + 검증된 렌더 path 존재 여부
+  - `default_selection: bool` — `select_layout_preset()` 의 default 픽 여부 (Step 7-B / 9 의 single-decision 영역)
+- `candidate_when` 필드 추가 — Step 7-B / Step 9 input (현재 single-decision logic 은 무시 — inert).
+- backward compat 유지 = `load_layout_presets()` 이 같은 dict shape 반환 → `LAYOUT_PRESETS` 사용처 무변.
+
+why:
+- 사용자 절대 lock = "모든 catalog data 는 yaml/HTML 에서 사람이 보고 modify 가능" — hardcoded dict 위반.
+- `status` 단일 enum 은 *render 가능성* 과 *default 선택* 두 axis 를 합쳐서 모호 — render_ready / default_selection 분리 (사용자 검토 후 박힘).
+- 모든 기존 8 preset 의 logic 은 무변 — runtime 결과 동일 (regression 0).
+
+next axis:
+- Step 7-B (layout candidate function).
--- a/docs/architecture/PHASE-Z-PIPELINE-OVERVIEW.md
+++ b/docs/architecture/PHASE-Z-PIPELINE-OVERVIEW.md
@@ -211,6 +211,7 @@ inline preview = 원문의 *일부* 만 빌려 보여주는 것. 원문은 detai
 - **Status** : ⚠ partial
 - **Code 위치** : `lookup_v4_match()` in `phase_z2_pipeline.py`
 - **Gap** : 현재 *rank-1 만* 반환. top-k 사용 안 됨. sibling group 후보도 없음.
+- **Note (사용자 잠금 2026-05-08)** : Step 5 axis = *non-reject max-6 후보 list* 로 보완 (rank-1 → top-N). raw 32 entry 는 `v4_full32_result.yaml` 영속, `step05_v4_evidence.json` = 정제 list. `lookup_v4_match()` 유지 (Step 6 backward compat). Step 9 application_plan input.

 #### Step 6. Composition Planning
 어떤 MDX 덩어리를 하나의 *slide-level zone unit* 으로 볼지 결정. child 따로 / sibling 묶기 / parent 단위.
@@ -219,6 +220,8 @@ inline preview = 원문의 *일부* 만 빌려 보여주는 것. 원문은 detai
 - **Status** : ⚠ partial
 - **Code 위치** : `src/phase_z2_composition.py` (`plan_composition`, `parent_merged_inferred`, `capacity_fit` integration)
 - **Gap** : section_layout_signature / content_object 구조 input 부재 (step 3, 4 가 없어서). frame compatibility 도 rank-1 매칭만 활용.
+- **Note (사용자 잠금 2026-05-08)** : Step 6 = *6-A 박힘*. **6-A** (additive, logic 무변) = `CompositionUnit` 에 `v4_candidates: list[V4Match]` 필드 추가, 기존 단일 frame 필드는 `candidates[0]` 호환 유지 (✓ 박힘).
+- **Note (사용자 잠금 2026-05-08 #2)** : **6-B (frame ownership transfer) 폐기 = misframed axis**. 정정된 mental model = *V4 가 frame 선택, Step 6 은 V4 rank-1 을 default 로 전사, Step 9 는 V4 후보를 application_plan 으로 번역*. Step 6 은 frame 채택 책임을 *원래부터 안 가짐* — 따라서 "Step 6 frame 채택 책임 → Step 9 이전" = 허구. 6-B 의 *실제 가능한 코드 변화* = MVP1_ALLOWED_STATUSES binary gate 위치 결정 → 이건 별 axis (label gate policy 재검토). 자세한 사유 = `PHASE-Z-CHANGE-LOG.md` 2026-05-08 #2 entry.

 #### Step 7. Slide-Level Layout Planning
 composition unit 개수와 성격을 보고 slide 전체 layout 선택. *기존 Type A/B/B'/B'' 의 후속 — 8-vocabulary 로 명시화*.
@@ -255,6 +258,7 @@ composition unit 개수와 성격을 보고 slide 전체 layout 선택. *기존
 - **Status** : ⚠ partial — *step 5 와 분리되지 않음 + region-level 미구현 (zone 단위 만)*
 - **Code 위치** : `plan_composition()` 이 V4 rank-1 즉시 선택 (step 5 와 conflate, zone 단위)
 - **Gap** : top-k 활용 / composition 제약 반영한 final 단계가 없음. *region-level 매칭 부재* (현재 zone 단위만). restructure label 은 현재 *filter* (선택 X). MVP1_ALLOWED_STATUSES = {matched_zone, adapt_matched_zone} 만 통과.
+- **Note (사용자 잠금 2026-05-08)** : Step 9 = **application_plan reframe**. V4 후보 (Step 5) + layout 후보 (Step 7-B) + region/display 후보 (Step 8-B-1/2) 통합 적용 계획. *V4 axis 재계산 X* — V4 의 anchor / cardinality / relation / slot / content 산식은 Step 5 에서 끝남. Step 9 = V4 label (use_as_is / light_edit / restructure / reject) → application_mode (direct_insert / same_frame_with_adjustment / layout_or_region_change / exclude) 변환 + layout/region/display 통합. 폐기 안 = "compat 매트릭스" (region × frame slot count) — V4 cardinality 재계산 위험 (PHASE-Z-CHANGE-LOG.md 2026-05-08 entry 참조).

 #### Step 10. Frame Contract 확인
 선택된 frame 의 contract 읽어서 accepted_content_types / slots / sub_zones / cardinality / capacity / visual_hints / density envelope / asset 확인.
--- a/docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md
+++ b/docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md
@@ -1,6 +1,6 @@
 # Phase Z — pipeline status board

-**Snapshot date** : 2026-05-04 (B1~B5 + trace-only runtime 연결 closure 반영 — Layer A telemetry first activation)
+**Snapshot date** : 2026-05-08 (Step 7-A/B + 8-A/B-1/B-2 catalog/candidate fn axis closure / Step 5-6-9 boundary reframe lock)
 **역할** : 현재 위치표 / grading snapshot. *지도 본문* 은 [`PHASE-Z-PIPELINE-OVERVIEW.md`](PHASE-Z-PIPELINE-OVERVIEW.md).

 | 문서 | 역할 | 변동 |
@@ -43,8 +43,8 @@ Step 0 은 본체가 아닌 *준비 조건*. Step 1 (MDX 업로드) 부터가 ru
 | A | 4 | Section Internal Composition Planning | ⚠ partial (B2 v0 dormant module + trace-only runtime 호출, render path 미연결) |
 | 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 + Internal Region Ratio Planning | ⚠ partial (zone-level horizontal-2 만 dynamic, region-level 은 B2 안 partial) |
+| A | 7 | Slide-Level Layout Planning | ⚠ partial (count-based / 7-A catalog + 7-B candidate fn 추가, runtime 호출처 X) |
+| A | 8 | Zone + Internal Region Ratio Planning | ⚠ partial (zone-level horizontal-2 만 dynamic / 8-A region+display catalog + 8-B-1/2 candidate fn 추가, runtime 호출처 X / region-level 은 B2 안 partial) |
 | A | 9 | Region-Level Frame / Display Selection | ⚠ partial (B4 가 catalog cover + declaration order 로 frame 선택 분담 / V4 evidence 미통합 / Step 5 와 conflate 잔존) |
 | A | 10 | Frame Contract 확인 | ⚠ partial (B3 의 accepted_content_types + sub_zones 선언 추가 — B4 만 읽음, mapper 미읽음 / density envelope 별 axis) |
 | A | 11 | Content Unit / Child Group → Internal Region → Frame Slot Mapping | ⚠ partial (B4 v0 dormant 2-stage + region 1:1 sub_zone + narrowest first + trace-only runtime 호출, render path 미연결) |
@@ -94,6 +94,20 @@ Step 0 은 본체가 아닌 *준비 조건*. Step 1 (MDX 업로드) 부터가 ru
   - tabular_overflow / image_aspect_mismatch 검사 부재 (Step 14)
   - layout_adjust / frame_reselect / details_popup_escalation / image_fit /
     frame_internal_fit_candidate (Step 17 missing actions) 미구현
+
+5. Step 5 / 6 / 9 boundary axis breakdown (2026-05-08 lock + 2026-05-08 #2 정정)
+   - Step 5 = rank-1 only → non-reject max-6 후보 list 로 보완 (✓ 박힘)
+   - Step 6-A = CompositionUnit v4_candidates 필드 additive (✓ 박힘)
+   - Step 7-conn / Step 8-conn = layout / region / display candidates artifact 연결 (✓ 박힘, Step 8 placeholder signals)
+   - Step 9 v0 = passive application_plan artifact (✓ 박힘 — V4 후보 + layout/region/display
+     통합 적용 계획, V4 axis 재계산 X)
+   - 폐기된 안 (2 가지) :
+     · "compat 매트릭스" (region × frame slot count) — V4 cardinality 재계산 위험
+       (CHANGE-LOG.md 2026-05-08 entry 참조)
+     · "6-B (frame ownership transfer)" — misframed axis. V4 가 frame 선택, Step 6 은
+       전사, Step 9 는 번역. Step 6 의 frame 채택 책임 = 허구 (CHANGE-LOG.md
+       2026-05-08 #2 entry 참조). 6-B 의 진짜 content (label gate policy) 는 별 axis.
+   - 닫힌 axis = 5 / 6-A / 7-conn / 8-conn / Step 9 v0
 ```

 **Cross-cutting Layer A — 진전 단계 정리** :
@@ -147,7 +161,7 @@ Step 0 (사전 준비) 의 Figma → HTML 변환은 *precondition phase 의 작

 ## 6. 현재 병목 (한 줄)

-> 현재 Phase Z 의 *Layer A pre-render planning* (Step 3 / 4 / 11) 은 본 session 작업으로 ❌ → ⚠ partial 전이 (B1/B2/B4 dormant module + trace-only runtime 호출). *Layer A telemetry 의 first activation* — debug.json 의 placement_trace per-zone + frame_slot_metrics F29 partial 기록. 단 **render path 활성화는 미완** : B4 PlacementPlan 이 mapper output 을 *대체하지 않고* trace-only / region-id / content_unit_id marker 가 partial template 에 *미주입* / B4 frame_selection 이 V4 evidence *미통합*. 핵심 다음 axis = **(B5 후속) render path 의 placement_trace 활용 + region marker runtime activation + V4 통합**. *runtime contract-registered / verified frame set 이 text-frame 중심* 한계는 잔존 (frame inventory audit / refinement 별 axis).
+> 현재 Phase Z 의 *Layer A pre-render planning* (Step 3 / 4 / 11) 은 본 session 작업으로 ❌ → ⚠ partial 전이 (B1/B2/B4 dormant module + trace-only runtime 호출). *Layer A telemetry 의 first activation* — debug.json 의 placement_trace per-zone + frame_slot_metrics F29 partial 기록. 단 **render path 활성화는 미완** : B4 PlacementPlan 이 mapper output 을 *대체하지 않고* trace-only / region-id / content_unit_id marker 가 partial template 에 *미주입* / B4 frame_selection 이 V4 evidence *미통합*. **Step 5/6/9 boundary axis breakdown 닫힘** (Step 5 / 6-A / 7-conn / 8-conn / Step 9 v0 박힘 — passive application_plan artifact). 6-B (frame ownership transfer) = misframed axis 폐기 (CHANGE-LOG.md 2026-05-08 #2). 핵심 다음 axis 후보 (별 axis lock) = **(A) V4 frame 후보 → Phase Z render path 연결 확장 (F14/F11/F18 등 미연결 frame adapter — contract + partial + builder, *figma 새 디자인 X / V4 새 매칭 X*)**, **(B) Step 17 details_popup_escalation**, **(C) Step 4 unit_count 산출**, **(D) Step 3/4 render path 활성화 (Layer A activation)**, **(E) label gate policy 재검토 (= 6-B 의 진짜 content 였던 것)**, **(F) Step 9 v1 scoring + auto decision**. *runtime contract-registered / verified frame set 이 text-frame 중심* 한계는 (A) 가 직접 푸는 axis.

 ---

--- a/docs/tasks/EXTRACT-ALL-TEXTS.md
+++ b/docs/tasks/EXTRACT-ALL-TEXTS.md
@@ -0,0 +1,77 @@
+# 요청: Figma 전체 프레임 texts.md 추출
+
+## 목표
+
+Figma 파일의 **모든 프레임**에서 texts.md를 추출한다.
+HTML, CSS, 이미지 등은 불필요. **텍스트만** 추출.
+
+## Figma 파일
+
+- URL: https://www.figma.com/design/9S6LsQyO6zlRxtiqZccOUM/Untitled?node-id=29-373&t=DjVfH90i8r4YiiM6-1
+
+## 이미 완료된 프레임 (14개)
+
+아래 프레임들은 이미 texts.md가 있으므로 **건너뛴다**.
+
+```
+1171281172, 1171281178, 1171281180, 1171281189,
+1171281190, 1171281191, 1171281193, 1171281194,
+1171281195, 1171281201, 1171281202, 1171281203,
+1171281204, 1171281208
+```
+
+## 작업 내용
+
+1. Figma 파일에서 **최상위 프레임 전체 목록** 조회
+2. 이미 완료된 14개를 제외한 **나머지 프레임들**에 대해
+3. 각 프레임별로 `figma_to_html_agent/blocks/{frame_id}/texts.md` 생성
+
+## texts.md 포맷
+
+기존과 동일한 구조:
+
+```markdown
+# Frame {frame_id} — 텍스트 (TF-IDF 매칭용)
+
+> 프레임 안의 모든 텍스트를 빠짐없이 추출.
+
+## 타이틀
+프레임의 메인 제목
+
+## 서브헤더 (있으면)
+서브 제목
+
+## 열1: 라벨 (열 구조인 경우)
+### 소제목
+텍스트 내용
+
+## 행1 (행 구조인 경우)
+라벨
+본문 텍스트
+
+## 결론 (있으면)
+결론 텍스트
+```
+
+### 핵심 규칙
+
+- 프레임 안의 **모든 텍스트 노드**를 빠짐없이 추출
+- 위치/크기 기준으로 **타이틀/서브/본문** 구분
+- 큰 텍스트(상단) → 타이틀
+- 중간 텍스트 → 서브헤더/라벨
+- 작은 텍스트(본문) → body
+- 열/행 구조가 보이면 `## 열1`, `## 행1` 등으로 구분
+- MCP `get_metadata` + `get_design_context`로 텍스트 전수 대조
+
+## 저장 위치
+
+```
+figma_to_html_agent/blocks/{frame_id}/texts.md
+```
+
+프레임 폴더가 없으면 새로 생성.
+
+## 용도
+
+이 texts.md는 나중에 **MDX 중목차/소목차와 TF-IDF 매칭**할 때 사용됩니다.
+그래서 텍스트가 빠지면 매칭이 안 되므로, **빠짐없이** 추출하는 것이 중요합니다.