kyeongmin
85c680f02a
전체 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>
227 lines
12 KiB
Markdown
227 lines
12 KiB
Markdown
# 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).
|