docs: add pipeline audit for legacy execution flow

- Classify pipeline.py as Archive-heavy with Salvage Candidate 0 - Record Phase Q/R'/T execution flow as outside Phase Z normal path - Mark deterministic pipeline utilities as Reference Only - Mark pipeline_context.py schema and lifecycle methods as Reference Only - Surface §1 B-1 as indirect surface, not direct composition planner - Add §5-1 dated entry for 2026-05-12 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 12:28:38 +09:00
parent 8b88757ade
commit b172c1b9f4
1 changed files with 130 additions and 3 deletions
--- a/docs/architecture/PHASE-Q-AUDIT.md
+++ b/docs/architecture/PHASE-Q-AUDIT.md
@@ -1096,7 +1096,135 @@ K6. (factual note) — §1 audit lens 의 A-2 매핑 정확도: *간접* (catalo

 > ⚠ **본 §2.10 audit 판정은 Phase Z normal path 기준의 후보 분류이며, `block_reference.py` / `block_selector.py` 는 §3 Salvage 적용 대상이 없다 (Salvage Candidate 0).** §0-A 의 10 원칙 + §0-0 의 분류 기준 + §0-B Audit 범위 lock + AI 격리 invariant 모두 따름. Reference Only 자산 (deterministic utility / matching helper / Phase Q-2 filtering / 상수) 은 별 axis 활성 시 *참고 여부만 별도 판단*. **block_reference 의 high-level entries (3 자산) = Phase R' archive 영역의 reference 제공 layer (§2.8 / §2.9 와 같은 Phase R' core 그룹). block_selector 의 `format_candidates_for_prompt` = Kei flow integration utility (Archive)**.

-### 2.11 (마지막) `pipeline.py` / `pipeline_context.py` — *후속 turn*
+### 2.11 `pipeline.py` / `pipeline_context.py` (마지막)
+
+#### 역할
+
+§2 audit 의 *마지막 모듈* — Phase Q normal pipeline 의 **master orchestrator** 영역.
+
+- **`pipeline.py`** (2096 lines): "Phase T: 11-Stage 파이프라인" — Stage 0 (MDX 표준화) ~ Stage 5 (서빙) orchestration. `generate_slide` (Phase T 현재) + `generate_slide_legacy` (Phase S 보존). Kei API + Claude Sonnet + Opus Vision 모두 호출
+- **`pipeline_context.py`** (340 lines): "Phase T-0: 파이프라인 누적 컨텍스트 객체" — 12 Pydantic BaseModel + StageFailure + build_retry_feedback + create_context
+
+**핵심 — pipeline.py 가 §2.1 ~ §2.10 모든 audit 모듈을 import / consume**:
+
+- §2.1 `mdx_normalizer` (Stage 0)
+- §2.2 `section_parser` (Stage 1A 후속)
+- §2.3 `slide_measurer` (Stage 4 측정)
+- §2.4 `fit_verifier` (Stage 1.5b retry)
+- §2.5 `space_allocator` (Stage 1.5a container)
+- §2.6 `content_editor.fill_content` (legacy Stage 3 slot fill)
+- §2.7 `content_verifier.generate_with_retry` (Stage 4 검증 retry loop)
+- §2.8 `renderer.render_slide_from_html` (Phase R' helper)
+- §2.9 `html_generator` (transitively via §2.7 content_verifier)
+- §2.10 `block_reference.select_and_generate_references` (Stage 1.7 entry) + `block_reference._match_by_tags` / `_load_catalog` (line 228 direct)
+
+→ **pipeline.py = Phase Q + Phase R' + Phase T 의 *central orchestrator***. Phase Z 22-step normal path 와 *abstraction 완전 다름* (Phase Z = 결정론적 mapper, Phase Q/T = 11-stage AI orchestration).
+
+핵심 함수 (pipeline.py):
+
+- `run_stage` (line 52): 공통 stage 실행 패턴 (transform / validate / update / snapshot)
+- `generate_slide` (line 120): Phase T 11-Stage main entry
+- `_retry_kei` (line 1518): Kei API retry helper (P0 무한 루프 방지)
+- `_save_step` (line 1551): step output JSON 저장
+- `generate_slide_legacy` (line 1563): Phase S 보존 pipeline
+- `_adjust_design` (line 1767): Kei AI 기반 design 조정
+- `_review_balance` (line 1869): Kei AI 기반 balance 검토
+- `_apply_adjustments` (line 1940): Kei judgment 기반 adjustments 적용
+- `_build_overflow_context` (line 2012): overflow context dict 빌더
+- `_convert_kei_judgment` (line 2044): Kei judgment → 내부 format 변환
+- `_parse_json` (line 2082): Claude/Kei response JSON 파싱 (§2.6 / §2.9 와 중복 implementation)
+
+핵심 자산 (pipeline_context.py):
+
+- 12 Pydantic BaseModel: `PopupItem`, `NormalizedContent`, `Topic`, `PageStructure`, `Analysis`, `TextBudget`, `DesignBudget`, `ContainerInfo`, `FontHierarchy`, `BlockReference`, `StageError`, `PipelineContext`
+- `PipelineContext` BaseModel + lifecycle methods (예: `save_snapshot` / `log_error` / `get_run_dir` / `get_role_content` 등)
+- `StageFailure` (Exception)
+- `build_retry_feedback`, `create_context` (functions)
+
+#### 관련 §7-B 항목
+
+**§1 §2 audit list**: `pipeline.py` (B-1), `pipeline_context.py` (audit list 직접 매핑 없음)
+
+| §7-B | 직간접 | 영향 |
+|---|---|---|
+| **B-1** Zone-section assignment override | (간접 surface) | pipeline.py 가 orchestration entry — Stage Y 에서 page_structure 생성 흐름 보유. 단 *실제 composition planner / zone-section assignment override implementation* 영역과는 다름. *direct implementation* 아님 |
+
+#### 현재 Phase Z 와 겹치는 영역
+
+| Phase Q `pipeline.py` / `pipeline_context.py` | Phase Z (현재) | 비교 |
+|---|---|---|
+| `generate_slide` (Phase T 11-Stage main) | Phase Z = `phase_z2_pipeline` 22-step 결정론적 mapper | **abstraction 완전 다름**. Phase Q = AI orchestration (Kei + Claude + Opus). Phase Z = 결정론적 mapper. *fundamentally 다른 path* |
+| `generate_slide_legacy` (Phase S 보존) | (Phase Z 폐기) | 더 오래된 AI orchestration |
+| `run_stage` (common stage executor) | Phase Z 자체 stage runner | abstraction 다름 (transform/validate/update/snapshot pattern은 generic 단 PipelineContext schema 특화) |
+| `_retry_kei` / `_adjust_design` / `_review_balance` / `_apply_adjustments` / `_convert_kei_judgment` | (Phase Z normal path 미존재 — AI 격리) | Kei AI 호출 기반 — Phase Z 본체 외 |
+| `_save_step` / `_build_overflow_context` | Phase Z 자체 step artifact 저장 path / overflow context | abstraction 다름 (PipelineContext 기반) |
+| `_parse_json` (line 2082) | (Phase Z 미존재 — AI 응답 parsing 영역) | §2.6 content_editor + §2.9 html_generator 와 중복 implementation |
+| `pipeline_context.py` 12 BaseModel + `PipelineContext` lifecycle methods | Phase Z 자체 artifact schema | **abstraction 완전 다름**. Pydantic schema 자체는 deterministic 단 Phase T schema 특화 |
+
+#### 재사용 가능성
+
+**pipeline.py**:
+
+| 자산 | 분류 | 근거 |
+|---|---|---|
+| `run_stage` (common stage executor) | **Reference Only** | transform/validate/update/snapshot pattern. Phase Z 자체 stage runner 있음. 직접 통합 X 단 *generic execution pattern* reference 가능 |
+| `generate_slide` (Phase T 11-Stage main) | **Archive Candidate** | **Phase Q+R'+T master orchestrator**. Kei + Claude + Opus AI orchestration. Phase Z 22-step normal path 와 abstraction 완전 다름 |
+| `_retry_kei` | **Archive Candidate** | Kei AI 호출 retry 인프라 |
+| `_save_step` | **Reference Only** | step output JSON 저장 utility. Phase Z 자체 artifact saving path |
+| `generate_slide_legacy` (Phase S 보존) | **Archive Candidate** | 더 오래된 Phase S AI orchestration |
+| `_adjust_design` | **Archive Candidate** | Kei AI 기반 design 조정 |
+| `_review_balance` | **Archive Candidate** | Kei AI 기반 balance 검토 |
+| `_apply_adjustments` | **Archive Candidate** | Kei judgment 기반 adjustments 적용 |
+| `_build_overflow_context` | **Reference Only** | overflow context dict 빌더. Phase Z 자체 overflow context 있음 |
+| `_convert_kei_judgment` | **Archive Candidate** | Kei judgment 변환 — Kei flow 의존 |
+| `_parse_json` | **Reference Only** | JSON parsing utility (§2.6 / §2.9 와 중복 implementation). Phase Z 직접 활성 axis 부재 |
+
+**pipeline_context.py**:
+
+| 자산 | 분류 | 근거 |
+|---|---|---|
+| `PopupItem` / `NormalizedContent` / `Topic` / `PageStructure` / `Analysis` / `TextBudget` / `DesignBudget` / `ContainerInfo` / `FontHierarchy` / `BlockReference` / `StageError` (11 BaseModel) | **Reference Only** | Phase T pipeline schema. Pydantic BaseModel. Phase Z 도 자체 artifact schema (별 schema, abstraction 다름) — 직접 통합 X. *schema 설계 패턴* reference 가능 |
+| `PipelineContext` BaseModel + lifecycle methods (`save_snapshot` / `log_error` / `get_run_dir` / `get_role_content` 등) | **Reference Only** | Phase T pipeline 의 aggregate context + lifecycle methods. Phase Z 도 자체 status board / artifact path 있음. 직접 통합 X 단 *aggregate context 설계 패턴* reference 가능 |
+| `StageFailure` (Exception) | **Reference Only** | stage failure 표현. Phase Z 도 자체 status board / failure recording. 직접 통합 X |
+| `build_retry_feedback` | **Reference Only** | retry feedback message builder. Phase Z 자체 retry context 있음 |
+| `create_context` | **Reference Only** | context factory. Phase T schema 특화 |
+
+#### audit 판정
+
+**Mixed (Archive heavy — Phase Q+R'+T master orchestrator + utility Reference Only + Phase T schema framework Reference Only)**.
+
+`pipeline.py` 는 *Phase Q / Phase R' / Phase T 의 master orchestrator* — §2.1 ~ §2.10 모든 audit 모듈을 import / consume. *Phase Z 22-step normal path 와 abstraction 완전 다름* (결정론적 mapper vs AI orchestration). Main orchestration 함수 (`generate_slide` / `generate_slide_legacy` / `_retry_kei` / `_adjust_design` / `_review_balance` / `_apply_adjustments` / `_convert_kei_judgment`) = **Archive Candidate**. Utility 함수 (`run_stage` / `_save_step` / `_build_overflow_context` / `_parse_json`) = **Reference Only**.
+
+`pipeline_context.py` 는 *Phase T pipeline 의 schema framework* — Pydantic BaseModel + `PipelineContext` lifecycle methods. Phase Z 도 자체 artifact schema 있음 (abstraction 다름) — 직접 통합 X 단 *schema 설계 패턴* reference 가능. 전체 **Reference Only**.
+
+- **§3 Salvage 적용 대상: 없음** (Salvage Candidate 0)
+- 별도 surface:
+  - §1 audit lens 의 B-1 매핑은 *간접 surface* — pipeline.py 가 orchestration entry (Stage Y page_structure 생성 흐름 보유). 단 *실제 composition planner / zone-section assignment override* 와는 다름. *direct implementation* 아님
+  - **pipeline.py = Phase Q+R'+T master orchestrator** (§2.1~§2.10 모든 audit 모듈 consume). Phase Z 본체 와는 *fundamentally 다른 abstraction path*
+  - 누적 §1 매핑 정정 weight (§2.6 + §2.8 + §2.9 + §2.10 + §2.11) — §1 정정 별 axis trigger 충분
+  - utility 중복 (`_parse_json` 등) cleanup 별 axis 후보
+
+#### 후속 참고 사항 (본 audit 밖 surface)
+
+L1. (Archive marker — 핵심) — **pipeline.py = Phase Q+R'+T master orchestrator**. 11-Stage AI orchestration (Kei + Claude + Opus). Main orchestration 함수 (`generate_slide` / `generate_slide_legacy` / `_retry_kei` / `_adjust_design` / `_review_balance` / `_apply_adjustments` / `_convert_kei_judgment`) 모두 Archive Candidate. CLAUDE.md 의 AI 격리 invariant + Phase Z 22-step normal path 와 abstraction 완전 다름. §3 검토 대상 외.
+
+L2. (별 axis 후보 — utility reference) — pipeline.py 의 deterministic utility (`run_stage` / `_save_step` / `_build_overflow_context` / `_parse_json`) 는 Reference Only. Phase Z 자체 stage runner / artifact saving / overflow context 있어 직접 통합 X 단 *generic pattern* reference 가능.
+
+L3. (별 axis 후보 — schema framework reference) — pipeline_context.py 의 Pydantic BaseModel framework + `PipelineContext` lifecycle methods (`save_snapshot` / `log_error` / `get_run_dir` / `get_role_content` 등) 는 Reference Only. Phase T schema 특화 단 *aggregate context + lifecycle 설계 패턴* reference 가능. Phase Z 도 자체 artifact schema 있음 — 직접 통합 X.
+
+L4. (cleanup 별 axis 후보) — `_parse_json` utility 가 pipeline.py + §2.6 content_editor + §2.9 html_generator 3 module 에 중복 implementation. Phase R' cleanup 또는 Phase Z utility 통합 axis 활성 시 *중복 제거 별도 판단*. 누적 cleanup 별 axis (§2.10 의 catalog 로드 + `_get_block_by_id` 중복과 같은 패턴).
+
+L5. (factual note — §1 매핑 누적) — §1 audit lens 의 B-1 매핑 정확도:
+- pipeline.py: *간접 surface* — orchestration entry 로 page_structure 생성 흐름 보유. 단 *실제 composition planner / zone-section assignment override* 와는 다름. *direct implementation* 아님
+- 누적 §1 매핑 정정 weight: §2.6 (B-1/B-2 content_editor) + §2.8 (A-3/A-4 renderer) + §2.9 (A-3/A-4 html_generator) + §2.10 (A-2 block_ref/selector) + §2.11 (B-1 pipeline) — §1 정정 별 axis 의 trigger 충분
+
+#### Salvage Plan 검토 대상 dual-write 기준 (§3 에서 재확정)
+
+- **Salvage Candidate**: 없음
+- **Reference Only** 자산 (utility + pipeline_context schema framework): §0-A 원칙 10 따라 활성 axis 결정 = *별 axis* (Phase Z stage runner 확장 / artifact saving 보강 / Pydantic schema 패턴 reference 등). 활성 시 그 axis 의 SoT 따라 adapter / dual-write 기준 별도 결정. 본 §2.11 audit 단계의 dual-write 기준 적용 X
+- **Archive Candidate** (Phase Q+R'+T master orchestration): §3 검토 대상 외
+
+> ⚠ **본 §2.11 audit 판정은 Phase Z normal path 기준의 후보 분류이며, `pipeline.py` 는 §3 Salvage 적용 대상이 없다 (Salvage Candidate 0).** §0-A 의 10 원칙 + §0-0 의 분류 기준 + §0-B Audit 범위 lock + AI 격리 invariant 모두 따름. Reference Only 자산 (deterministic utility + Phase T schema framework) 은 별 axis 활성 시 *참고 여부만 별도 판단* (직접 통합 X). **`pipeline.py` = Phase Q+R'+T master orchestrator (§2.1~§2.10 consume) — Phase Z 22-step normal path 와 abstraction 완전 다름**.

 ---

@@ -1178,8 +1306,7 @@ audit 결과 → 어느 항목이:
 | 2026-05-12 | §2.8 renderer.py audit | 완료 — Mixed (Reference Only + Archive Candidate). **`render_slide_from_html` (Phase R') = Archive (CLAUDE.md 명시 폐기 — AI 가 HTML 구조 직접 생성 금지)**. Salvage Candidate 0. 나머지 Jinja2 rendering utility / catalog 로드 / template resolution = Reference Only (Phase Q schema 특화, abstraction 다름). §3 적용 대상 없음. 별도 surface: §1 A-3 간접 / A-4 영향면 있으나 conditional CSS 분기 구현 부재, I1~I4 구현/보강 axis 후보, I5 Phase R' Archive marker, I6 §1 매핑 정확도 factual note |
 | 2026-05-12 | §2.9 html_generator.py audit | 완료 — Mixed (Archive heavy — Phase R' core). **`html_generator.py` = Phase R' (AI HTML 직접 생성) main implementation (CLAUDE.md 명시 폐기)**. Salvage Candidate 0. AI HTML generation path (`generate_slide_html` / `_call_claude` / `regenerate_area` / `build_area_prompt` / Phase T supplement / `_LEGACY_*` prompts) = Archive Candidate. deterministic helpers (`normalize_mdx` / `_slice_mdx_sections` / `_get_definitions` / `_get_conclusion` / `_calc_indent` / `_replace_img_placeholder` 등) = Reference Only (§2.1 / §2.2 에 더 직접적인 SoT 후보 존재). §3 적용 대상 없음. 별도 surface: §1 A-3/A-4 매핑 부정확, J1 Phase R' core Archive marker, J2 §2.8 연결, J3 utility 중복 cleanup axis, J4 general helper reference axis, J5 §1 매핑 factual note |
 | 2026-05-12 | §2.10 block_reference.py / block_selector.py audit | 완료 — Mixed (Reference Only heavy + 일부 high-level Phase R' / Kei prompt entries Archive). Salvage Candidate 0. block_reference utilities (`_get_jinja_env` / `_load_catalog` / `_get_block_by_id` / `_match_visual_type` / `_match_by_tags` / `VISUAL_TYPE_KEYWORDS`) + block_selector utilities + filtering (`load_catalog` / `_get_block_by_id` / `select_block_candidates` / `select_fallback_candidates` / 상수) = Reference Only. **block_reference high-level entries (`select_reference_block` / `generate_design_reference` / `select_and_generate_references`) = Phase R' reference path Archive (§2.8 / §2.9 와 같은 Phase R' core 그룹)**. block_selector `format_candidates_for_prompt` = Kei prompt formatter Archive (`kei_client.py` used). §3 적용 대상 없음. 별도 surface: §1 A-2 매핑 간접, K1 Phase R' reference path Archive marker, K2 Kei prompt formatter Archive marker, K3 block_selector legacy unused + dual path, K4 deterministic utilities reference axis, K5 catalog/_get_block_by_id 중복 cleanup axis, K6 §1 매핑 factual note |
-| (last) | §2.11 pipeline.py / pipeline_context.py | (대기) |
-| (last) | §2.11 pipeline.py / pipeline_context.py | (대기) |
+| 2026-05-12 | §2.11 pipeline.py / pipeline_context.py audit (마지막) | 완료 — Mixed (Archive heavy — Phase Q+R'+T master orchestrator + utility Reference Only). **pipeline.py = Phase T 11-Stage AI orchestration main implementation (Phase Q+R'+T 모듈 모두 consume)**. Salvage Candidate 0. Main orchestration (`generate_slide` / `generate_slide_legacy` / `_retry_kei` / `_adjust_design` / `_review_balance` / `_apply_adjustments` / `_convert_kei_judgment`) = Archive. utility (`run_stage` / `_save_step` / `_build_overflow_context` / `_parse_json`) = Reference Only. pipeline_context.py = Reference Only (Pydantic schema + PipelineContext lifecycle methods). §3 적용 대상 없음. 별도 surface: §1 B-1 매핑 간접 (pipeline orchestration entry, direct composition planner 아님), 누적 §1 매핑 정정 axis weight ↑, utility 중복 (_parse_json 등) cleanup axis, L1 master orchestrator Archive marker, L2~L3 utility/schema reference axis, L4 cleanup axis, L5 §1 factual note |
 | (then) | §3 Salvage Plan | (대기) |
 | (then) | §4 우선순위 재정렬 → ROADMAP 갱신 | (대기) |