diff --git a/docs/architecture/PHASE-Z-IMPLEMENTATION-ISSUE-BACKLOG.md b/docs/architecture/PHASE-Z-IMPLEMENTATION-ISSUE-BACKLOG.md new file mode 100644 index 0000000..b65140b --- /dev/null +++ b/docs/architecture/PHASE-Z-IMPLEMENTATION-ISSUE-BACKLOG.md @@ -0,0 +1,134 @@ +# Phase Z Implementation Issue Backlog + +본 문서는 [`PHASE-Q-INSIGHT-TO-22STEP-MAP.md`](PHASE-Q-INSIGHT-TO-22STEP-MAP.md) 의 *insight → 22-step 매핑* 을 기반으로 implementation 단위 issue list 를 정리한 backlog. 박기 → review loop → 격파 cycle 진입 전 prereq lock. + +## review loop workflow + +각 issue 별 sequence: + +1. preview chat draft +2. Codex 1차 review (comment) +3. Claude 재검토 (comment) +4. Codex 재검증 (comment) +5. 100% 합의 → `scope-locked` → `ready-for-implementation` +6. Claude Code 구현 +7. Codex 검증 (diff scope / 22-step invariant / 하지 말 것 위반 / commit/push 상태) +8. issue close + comment 결과 기록 (commit hash / 검증 결과 / follow-up) +9. 다음 issue + +운영 thread = **Gitea Issues** (sanity check pending — 활성 여부 별 GO 확인). + +## labels (8) + +`needs-codex-review` / `needs-claude-review` / `scope-locked` / `ready-for-implementation` / `implemented` / `verified` / `blocked` / `closed` + +## dependency convention + +모든 dependency cell 은 다음 3 형식으로 표기: + +- `none` — 다른 issue 와 dependency 없음 +- `hard link: IMP-XX (이유)` — 선행 issue 박힘 후 진행 필수 +- `soft link: IMP-XX (이유)` — 참고 또는 의미 ↑ 관계, 독립 진행 가능 + +## schema note + +§1 / §2 / §3 = 9 column (`related step` + `dependency`). §4 cleanup = 9 column (`related module` + `trigger axis`). cleanup 은 module-level + axis 활성 시점 trigger 라 schema 변형 (semantics 분리 의도). + +`§0` 9 Archive marker 인 G1 / H4 / H5 / I5 / J1 / J2 / K1 / K2 / L1 = 구현 대상 X — 본 backlog 안 implementation issue 화 X. 단 issue 생성 시 review loop 안 [`PHASE-Q-INSIGHT-TO-22STEP-MAP.md`](PHASE-Q-INSIGHT-TO-22STEP-MAP.md) §0 cross-ref 명시. + +--- + +## §1 22-step map implementation issues (11 — INSIGHT-MAP §2 source) + +| ID | title | related step | source | priority | scope | guardrail / validation | dependency | status | +|---|---|---|---|---|---|---|---|---| +| IMP-01 | A-6 Zone DOM 좌표 export | Step 14, 21 | §2 A-6 Salvage | ↑ high (small) | `_MEASURE_SCRIPT` JS extension `getBoundingClientRect()` + artifact field 추가 | AI/Kei/V4/frame 선택 변경 X / DOM bbox trace / 기존 debug.json schema 보존 (additive) | none | pending | +| IMP-02 | A-1 Stage 0 normalize chained adapter | Step 2 | §2 A-1 Salvage chained | ↑ high (medium) | `normalize_mdx_content` + `extract_major_sections` + `extract_conclusion_text` chained adapter + dual-write | AI/Kei normalize 회귀 X / step02 sections / sub_sections trace 설명 가능 | none | pending | +| IMP-03 | A-1 popup/image/table trace | Step 3 | §2 A-1 chained 보강 | medium | normalized popups / images / tables → ContentObject 변환 (B1 v0 보강) | AI/Kei content extraction 회귀 X / popup/image/table 추출 trace 설명 가능 | hard link: IMP-02 (Stage 0 normalize output 의 popup/image/table list 의존) | pending | +| IMP-04 | A-2 Catalog 확장 | Step 0, 9 | §2 A-2 새로 만들기 (핵심 unblocker) | medium (large) | `frame_contracts.yaml` + frame_partials 32 frame 등록/확장 | Phase R' frame catalog 회귀 X / V4 logic 변경 X / catalog 확장 후 PASS/FAIL 변화와 frame 선택 trace 설명 가능 | none | pending | +| IMP-05 | A-5 V4 fallback | Step 9, 16, 17, 20 | §2 A-5 새로 만들기 | medium | Step 9 / Step 16 router 확장 (rank-1 fail 시 rank-2/3 fallback) + step20 status semantics | `calculate_fit` 통째 Migrate X (dual path 위험) / 신설 status (`PASS_WITH_FALLBACK` 등) 일관성 / frame 변경 허용 trace 설명 | hard link: IMP-04 (catalog 확장 후 fallback path 의미 있음) | pending | +| IMP-06 | B-1 Zone-section override | Step 6 + input Step 1, 22 | §2 B-1 새로 만들기 (backend path) | medium | CLI 인자 + composition planner override path 신설 | Kei composition / Phase R' frame 보조 회귀 X / override 적용 시 composition_unit schema 정합 + trace | soft link: IMP-04 (frame 후보 ↑ 시 override 의미 ↑) | pending | +| IMP-07 | B-2 Edited HTML → MDX reverse path | Step 22 + Step 1, 2 | §2 B-2 새로 만들기 (backend path) | medium | frontend edited HTML → backend → MDX 변환 → pipeline 재진입 (글벗 `html_to_slide_mdx` 참조) | AI/Kei reverse 회귀 X / 재진입 후 step02 정합 + visual_check 통과 | hard link: IMP-02 (A-1 normalize schema 와 reverse path schema 정합 필요) | pending | +| IMP-08 | B-3 Sub-section drag drop | Step 3 | §2 B-3 새로 만들기 (backend schema) | ↓ low | Phase Z `section_id` schema 확장 (sub_sections 단위 매핑) | AI/Kei schema 회귀 X / backward compatible / step03 trace | hard link: IMP-02 (A-1 normalize sub_sections schema 의존) | pending | +| IMP-09 | B-4 다른 layout zone-geometry | Step 8 | §2 B-4 새로 만들기 (backend layout) | ↓ low | `build_layout_css` 분기 확장 (top-1-bottom-2 / left-1-right-2 / grid-2x2 등) | Kei `build_containers_type_b` 회귀 X / step08 trace | none | pending | +| IMP-10 | D-1 filtered_section_reasons UI | Step 20, 22 | §2 D-1 frontend 신규 | ↓ low | frontend UI — backend artifact read-only 표시 | AI/Kei UI 회귀 X / backend artifact read-only | none | pending | +| IMP-11 | D-2 Frame min_height 표시 | Step 22 | §2 D-2 새로 만들기 (frontend hint + catalog 참조) | ↓ low | frontend UI — frame contract `min_height_px` read-only + resize hint | AI/Kei UI 회귀 X / catalog 참조 + resize limit | none | pending | + +--- + +## §2 Separate axis registry issues (9 — INSIGHT-MAP §3 source) + +| ID | title | related step | source | priority | scope | guardrail / validation | dependency | status | +|---|---|---|---|---|---|---|---|---| +| IMP-12 | Step 16/17 retry 정밀화 | Step 16, 17 | §3 group B (Salvage deterministic) | medium | `redistribute` + glue + font compression — Step 16 router action 신설 + Step 17 action 실행 | AI fallback X / Kei retry loop (H5) 회귀 X / status semantics 일관 | soft link: IMP-05 (Step 16 router 영역 공유, 병렬 가능) | pending | +| IMP-13 | A-3 frame preview 일관성 | Step 0, 14, 21 | §3 Salvage 후보 | ↓ low | `capture_slide_screenshot` Salvage — preview.png 자동 생성 path | Phase R' reference path 회귀 X / preview artifact trace | soft link: IMP-04 (catalog frame_partial 확장 시 의미 ↑) | pending | +| IMP-14 | A-4 slide-base iframe mode | Step 13 | §3 새로 만들기 | ↓ low | `slide-base.html` conditional CSS (embedded vs standalone) | Claude / Phase R' HTML generation 회귀 X / Jinja2 deterministic | none | pending | +| IMP-15 | Step 14 visual_check 보강 | Step 14, 21 | §3 H1 Reference Only | medium | image_aspect_mismatch / tabular_overflow 검사 추가 | AI/Kei classification 회귀 X / deterministic 검사 + trace | soft link: IMP-01 (Step 14 측정/trace layer 공유) | pending | +| IMP-16 | B-2 verification 보조 axis | Step 1, 2, 14, 21, 22 | §3 H3 Reference Only | ↓ low | B-2 reverse path 의 verification 보조. main reverse path 는 IMP-07, 본 issue 는 text/visual/trace 검증 layer | AI/Kei verification 회귀 X / utility deterministic | hard link: IMP-07 (B-2 main 활성 시점 의미) | pending | +| **IMP-17** | **AI repair fallback infra** (**carve-out — normal path 밖**) | Step 12, 16, 17 | §3 G3 | (별 axis priority — pending) | `httpx` + SSE streaming + retry + JSON parse pattern reference — light_edit / restructure proposal | **normal path AI 호출 0 — 본 axis = fallback only, normal path 와 분리 설계** / Kei persona 단절 (Phase Q 자산과 단절) | soft link: IMP-04 + IMP-05 (catalog 확장 + V4 fallback 활성 시 의미) | pending | +| IMP-18 | I3 SVG 좌표 보강 | Step 0, 9 | §3 Reference Only | ↓ low | `renderer._preprocess_svg_data` 패턴 reference — frame_partials SVG 좌표 사전 박힘 | Phase R' (renderer.py) 회귀 X | soft link: IMP-04 (frame_partials 등록 후 의미 ↑) | pending | +| IMP-19 | I4 zone 비중 분배 | Step 8 | §3 Reference Only | ↓ low | `renderer._group_blocks_by_area` 패턴 reference — zone-level ratio 분배 | Phase O 컨테이너 회귀 X / 직접 통합 X | soft link: IMP-09 (zone 비중 분배 영역 공유) | pending | +| IMP-20 | H2 frame contract validation | Step 10 | §3 Reference Only | ↓ low | `content_verifier.verify_structure` pattern reference — Phase Z frame contract 검증 pattern | Phase Q `REQUIRED_PATTERNS` 값 회귀 X / Phase Z 자체 pattern dict 설계 | soft link: IMP-04 (확장 catalog 적용 시 검증 범위 확대) | pending | + +--- + +## §3 audit §1 mapping correction issues (5 — INSIGHT-MAP §4 source) + +| ID | title | related layer | source | priority | scope | guardrail / validation | dependency | status | +|---|---|---|---|---|---|---|---|---| +| IMP-21 | G2 — audit §1 lens B-1/B-2 column 정정 | audit §1 lens (B-1, B-2) | §4 G2 (§2.6 catch) | ↓ low (doc-only) | content_editor 매핑 부정확 정정 | audit doc §1 표 정정만 / cross-ref 정합 | none | pending | +| IMP-22 | I6 — audit §1 lens A-3/A-4 column 정정 (renderer) | audit §1 lens (A-3, A-4) | §4 I6 (§2.8 catch) | ↓ low (doc-only) | renderer 매핑 정확도 정정 | audit doc §1 표 정정만 / cross-ref 정합 | none | pending | +| IMP-23 | J5 — audit §1 lens A-3/A-4 column 정정 (html_generator) | audit §1 lens (A-3, A-4) | §4 J5 (§2.9 catch) | ↓ low (doc-only) | html_generator Selenium import 부재 + slide-base 호출 부재 정정 | audit doc §1 표 정정만 / cross-ref 정합 | hard link: IMP-22 (같은 audit §1 lens row 정정 — 박기 순서 의존) | pending | +| IMP-24 | K6 — audit §1 lens A-2 column 정정 | audit §1 lens (A-2) | §4 K6 (§2.10 catch) | ↓ low (doc-only) | block_reference/block_selector 간접 매핑 정정 | audit doc §1 표 정정만 / cross-ref 정합 | none | pending | +| IMP-25 | L5 — audit §1 lens B-1 column 정정 | audit §1 lens (B-1) | §4 L5 (§2.11 catch) | ↓ low (doc-only) | pipeline orchestration entry 간접 매핑 정정 | audit doc §1 표 정정만 / cross-ref 정합 | none | pending | + +--- + +## §4 cleanup issues (3 — INSIGHT-MAP §5 source) + +| ID | title | related module | source | priority | scope | guardrail / validation | trigger axis | status | +|---|---|---|---|---|---|---|---|---| +| IMP-26 | J3 — html_generator utility 중복 cleanup | §2.9 html_generator | §5 J3 | ↓ low (future) | `normalize_mdx` / `_slice_mdx_sections` / `_get_definitions` / `_get_conclusion` 중복 제거 (vs §2.1/§2.2 SoT) | Phase R' 영역 — 코드 제거만 | Phase R' cleanup axis 활성 시 | pending | +| IMP-27 | K5 — catalog 로드 + `_get_block_by_id` 중복 cleanup | §2.10 + §2.8 (3 module) | §5 K5 | ↓ low (future) | block_reference / block_selector / renderer 의 catalog 로드 중복 제거 | Phase R' 영역 또는 Phase Z catalog 확장 axis | Phase Z catalog 확장 axis 활성 시 (soft link: IMP-04) | pending | +| IMP-28 | L4 — `_parse_json` 중복 cleanup | §2.11 + §2.6 + §2.9 (3 module) | §5 L4 | ↓ low (future) | pipeline / content_editor / html_generator 의 `_parse_json` 중복 제거 | Phase R' 영역 또는 Phase Z utility 통합 axis | Phase R' cleanup 또는 Phase Z utility 통합 axis 활성 시 | pending | + +--- + +## §5 frontend matching insight — source pending + +| status | content | +|---|---| +| **pending source** | Frontend matching insight 는 source pending 상태 — 실제 implementation issue 미열기. 출처가 확정되기 전까지 본 backlog 에 implementation issue row 추가 X. 출처 확정 후 별 axis 에서 INSIGHT-MAP §2 row + §3 registry + 본 backlog issue 통합 보강 | + +--- + +## Gitea Issues sanity check (pending) + +- `gitea.hmac.kr/Kyeongmin/C.E.L_Slide_test2` 의 Issues tab 활성 여부 = **확인 필요** (사용자 허락 후 별 GO — web fetch 또는 API) +- 활성 시 = 본 backlog 박기 후 §1 / §2 / §3 / §4 sub-section 별 issue 생성 (4 단계 분해) +- 비활성 시 = 사용자 lock 별 axis (GitHub Issues 또는 repo 문서만 운영) + +--- + +## 진행 흐름 + +``` +[A frame — 본 doc] [B frame — Gitea Issues] +backlog doc 박기 (본 turn) + ↓ +commit / push 별 GO + ↓ +Gitea Issues 활성 sanity check 별 GO ─┐ + ↓ + §1 11 issue 생성 (preview + 박기 별 GO) + ↓ + §2 9 issue 생성 (preview + 박기 별 GO) + ↓ + §3 5 issue 생성 (preview + 박기 별 GO) + ↓ + §4 3 issue 생성 (preview + 박기 별 GO) + ↓ + 각 issue review loop 운영 + (Codex 1차 → Claude 재검토 → Codex 재검증 + → 100% 합의 → 구현 → 검증 → close) +``` diff --git a/docs/architecture/PHASE-Z-ROADMAP.md b/docs/architecture/PHASE-Z-ROADMAP.md index a83e5ab..d2d5930 100644 --- a/docs/architecture/PHASE-Z-ROADMAP.md +++ b/docs/architecture/PHASE-Z-ROADMAP.md @@ -278,6 +278,7 @@ frontend (`design_agent_front/design-agent`) 와 backend phase_z2 의 연결 axi | **`PHASE-Z-ROADMAP.md`** (본 문서) | **앞으로의 진행 순서 / 큰 axis / 우선순위** | **자주** | | [`PHASE-Q-AUDIT.md`](PHASE-Q-AUDIT.md) | Phase Q 모듈의 Keep / Migrate / Reference / Delete 결정 + Salvage Plan + ROADMAP §7-B 우선순위 재정렬의 input | audit 진행 중 (모듈별로 1 turn) | | [`PHASE-Q-INSIGHT-TO-22STEP-MAP.md`](PHASE-Q-INSIGHT-TO-22STEP-MAP.md) | audit insight + frontend matching insight(source pending) → 22-step pipeline 매핑 + implementation 전 prereq lock | implementation axis 활성 시 | +| [`PHASE-Z-IMPLEMENTATION-ISSUE-BACKLOG.md`](PHASE-Z-IMPLEMENTATION-ISSUE-BACKLOG.md) | implementation 단위 issue list — 22-step map / 별 axis registry / mapping correction / cleanup / frontend pending 통합 backlog | issue cycle 활성 시 | | `PROCESS_OVERVIEW.html` | 보고 / 피드백용 시각 프로토타입 | 보고 시점 | 각 문서가 자기 역할만 하면 drift / 중복 / outdated 방지.