From 1fedd4d0a0264e954b40e89323509cbbe07340c1 Mon Sep 17 00:00:00 2001 From: kyeongmin Date: Tue, 12 May 2026 08:51:20 +0900 Subject: [PATCH] docs: add content_verifier audit (Mixed Reference Only + Archive) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Classify content_verifier.py as Mixed (Reference Only + Archive Candidate) - Mark deterministic utilities (text extraction, Korean normalization, verification logic) as Reference Only — Phase Z normal path direct slot absent - Mark Kei artifact detection (verify_no_forbidden_content + FORBIDDEN_KEI_MEMOS) and Kei AI generation retry loop (generate_with_retry) as Archive Candidate - Clarify L4 Selenium / L5 Opus vision are header documentation only (no implementation in this file) - Record no §3 Salvage application target (Salvage Candidate 0) - Surface §1 B-2 mapping as indirect; H1-H3 reference axis candidates, H4-H5 Archive markers, H6 L4/L5 factual note - Add §5-1 dated entry for 2026-05-12 Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/architecture/PHASE-Q-AUDIT.md | 96 +++++++++++++++++++++++++++++- 1 file changed, 94 insertions(+), 2 deletions(-) diff --git a/docs/architecture/PHASE-Q-AUDIT.md b/docs/architecture/PHASE-Q-AUDIT.md index e3fe14b..73f461e 100644 --- a/docs/architecture/PHASE-Q-AUDIT.md +++ b/docs/architecture/PHASE-Q-AUDIT.md @@ -686,7 +686,98 @@ G3. (별 axis 후보, 본 audit 외) — AI repair fallback (Phase Z step12 ligh > ⚠ **본 §2.6 audit 판정은 Phase Z normal path 기준의 후보 분류이며, `content_editor.py` 자산은 현재 §3 Salvage Plan 대상 외로 둔다.** §0-A 의 10 원칙 + §0-0 의 분류 기준 + §0-B Audit 범위 lock + AI 격리 invariant 모두 따름. **AI repair fallback 의 평가 여부는 본 audit 밖 — 별도 axis 활성 시 새 기준으로 재검토**. -### 2.7 `content_verifier.py` — *후속 turn* +### 2.7 `content_verifier.py` + +#### 역할 + +Phase Q normal pipeline 의 verification step. 헤더는 5-layer 검증을 선언하지만, **이 파일의 실제 구현은 L1 텍스트 보존 / L2 금지 콘텐츠 / L3 구조 검증 + Kei HTML generation retry loop 중심**이다. L4 Selenium overflow / L5 Opus vision 은 헤더 주석상 *계획 또는 외부 layer (`slide_measurer.py` / `kei_client.py` reuse)* 로 언급되지만, **본 파일에서 직접 구현되지는 않음**. + +678 lines, 12 함수 + 2 classes (`VerificationResult`, `_TextExtractor`). + +핵심 함수: + +- `VerificationResult` (dataclass), `_TextExtractor` / `extract_text_from_html`: HTML text 추출 +- `normalize_for_comparison` + `_PARTICLES` + `_ENDING_NORMALIZE`: 한국어 정규화 (조사 stripping + 개조식 → 서술형 변환) +- `extract_keywords` / `strip_meta_lines` / `split_into_sentences`: 텍스트 처리 utility +- `verify_text_preservation` (L1) + `detect_invented_text`: 텍스트 보존 / 발명 텍스트 검증 +- `verify_no_forbidden_content` (L2) + `FORBIDDEN_KEI_MEMOS` + `FORBIDDEN_LABELS_IN_KEYMSG`: Kei prompt leak / label 검출 +- `verify_structure` (L3) + `REQUIRED_PATTERNS`: per-area CSS/HTML 필수 패턴 + 폰트 위계 검사 +- `verify_area` / `verify_all_areas`: orchestrator (L1+L2+L3 합성) +- `generate_with_retry` (async): full retry loop — `html_generator.generate_slide_html` (Kei AI) + `html_validator.validate_and_clean_html` + `verify_all_areas` + +import 으로 본 file 직접 호출: `html_generator` + `html_validator`. `slide_measurer` / `kei_client` import X. + +#### 관련 §7-B 항목 + +| §7-B | 직간접 | 영향 | +|---|---|---| +| (없음) — main role 매핑 | (해당 없음) | content_verifier 의 main role 은 *Kei AI 생성 HTML 의 정확도 verification* (forward direction post-check). §1 audit lens 의 직접 매핑 항목 없음 | +| **B-2** Edited HTML → MDX 역변환 (§1 §2 audit list 매핑) | (간접) | §1 §2 audit list 에 "B-2 후속" 으로 listed. main role 과 직접 매핑 X — *B-2 axis 활성 시 verification 보조* 의 간접 정도 (§2.6 만큼 부정확하지는 않음) | + +#### 현재 Phase Z 와 겹치는 영역 + +| Phase Q `content_verifier` | Phase Z (현재) | 비교 | +|---|---|---| +| `verify_text_preservation` (L1) | (Phase Z normal path 미존재) | Phase Z mapper *by construction* 텍스트 보존 (Step 11 slot_mapping). L1 검증 활성 axis 부재 | +| `verify_no_forbidden_content` (L2) | (Phase Z normal path 미존재) | Phase Z 본체 Kei AI 호출 X → Kei prompt leak 가능성 부재 | +| `verify_structure` (L3) + `REQUIRED_PATTERNS` | (Phase Z normal path 일부 — frame contract validation 영역) | Phase Q `REQUIRED_PATTERNS` = body_bg/core/sidebar/footer Phase Q area. Phase Z = unit/zone/preset/frame contract — **abstraction 다름** | +| Layer 4 Selenium overflow (헤더 언급) | Phase Z Step 14 `visual_check` | §2.3 `slide_measurer` 영역 — 본 파일 직접 구현 부재 | +| Layer 5 Opus vision (헤더 언급) | (Phase Z normal path 미존재 — AI 격리 invariant) | AI 호출. AI repair fallback 영역 (본 audit 외, L3 lock) — 본 파일 직접 구현 부재 | +| utility 함수들 | (Phase Z 미존재) | 결정론적 + AI 무관 + 일반 utility. Phase Z normal path *직접 빈칸 채움 X* — 별 axis 활성 시 참고 가능 | +| `generate_with_retry` | (Phase Z normal path 미존재) | html_generator (Kei AI) generation retry loop | + +#### 재사용 가능성 + +| 자산 | 분류 | 근거 | +|---|---|---| +| `VerificationResult` (dataclass) | **Reference Only** | 결과 구조 참고. Phase Z artifact/status 구조와 직접 통합은 별도 판단 | +| `_TextExtractor` / `extract_text_from_html` | **Reference Only** | HTML text extraction utility. B-2 / verification 보강 별 axis 활성 시 참고 | +| `normalize_for_comparison` + `_PARTICLES` + `_ENDING_NORMALIZE` | **Reference Only** | 한국어 비교 정규화 utility. Phase Z normal path 직접 slot 없음 | +| `extract_keywords` | **Reference Only** | keyword 비교 utility. Phase Z path 활성 axis 부재 | +| `strip_meta_lines` | **Reference Only** | AI/Kei meta 제거 성격 — normal path 직접 대상 X | +| `split_into_sentences` | **Reference Only** | 일반 utility. 참고 가능 | +| `verify_text_preservation` (L1) | **Reference Only** | 결정론적이나 Phase Z mapper *by construction* 텍스트 보존. 검증 보강 별 axis 참고 | +| `detect_invented_text` | **Reference Only** | AI 생성 결과 검증 성격. normal path 직접 대상 X | +| `verify_structure` (L3) | **Reference Only** | CSS pattern 검사 방식 참고 | +| `REQUIRED_PATTERNS` (constant) | **Reference Only** | 구조 참고. 값은 Phase Q area abstraction — Phase Z 다름 | +| `verify_area` / `verify_all_areas` | **Reference Only** | orchestrator pattern 참고. 직접 통합 X | +| `verify_no_forbidden_content` + `FORBIDDEN_KEI_MEMOS` + `FORBIDDEN_LABELS_IN_KEYMSG` | **Archive Candidate** | Kei prompt leak / label 검출. Phase Z normal path 에 Kei 없음 | +| `generate_with_retry` (async) | **Archive Candidate** | html_generator (Kei AI) generation retry loop. Phase Z normal path 미존재 | + +#### audit 판정 + +**Mixed (Reference Only + Archive Candidate)**. + +`content_verifier.py` 는 결정론적 검증 utility 가 많지만, *Phase Z normal path 의 직접 Salvage 후보 (특정 빈칸 채움) 는 없다*. 대부분은 future verification / visual_check 보강 / B-2 검증 별 axis 활성 시 참고 가능한 **Reference Only** 이며, Kei artifact 검출과 AI generation retry loop 는 **Archive Candidate** 다. **L4 Selenium / L5 Opus vision 은 헤더 documentation only — 본 파일 구현 없음**. + +- §3 Salvage 적용 대상: **없음** (Salvage Candidate 0). Reference Only 자산은 future verification / visual_check / B-2 검증 별 axis 활성 시 *참고 여부만 별도 판단* (직접 통합 X) +- 별도 surface: + - §1 audit lens 의 "B-2 후속" 매핑은 *간접* — main role 은 Kei AI 생성 HTML verification (forward direction) + - L4/L5 implementation 부재 — header documentation 과 실 구현 분리 + - Reference Only 자산의 활성 axis 결정 = 별 axis (visual_check 보강 / B-2 검증 / future verification axis) + - AI repair fallback 의 Layer 5 (Opus vision) reuse 여부 = 본 audit 밖 + +#### 후속 참고 사항 (본 audit 밖 surface) + +H1. (별 axis 후보) — Phase Z visual_check (Step 14) 보강 axis 활성 시, content_verifier 의 *generic utilities* (text 추출 / 정규화 / sentence split / keyword 추출 / `VerificationResult`) 가 **Reference Only 참고 후보**. *직접 통합 X* — adapter / dual-write 검증은 별 axis 활성 시 새 기준으로 결정. + +H2. (별 axis 후보) — Phase Z frame contract validation 별 axis 활성 시 `verify_structure` 패턴 (CSS pattern 검사 + 폰트 위계 검사) 이 Reference Only 참고. 단 `REQUIRED_PATTERNS` 값은 Phase Q area 특화 → Phase Z 자체 pattern dict 설계 필요. + +H3. (별 axis 후보) — B-2 (Edited HTML → MDX 역변환) axis 활성 시 utility 함수 (text 추출 / 정규화 / 비교) 가 verification 보조로 Reference Only 참고 가능. 직접 통합 X. main role 매핑은 *간접*. + +H4. (Archive marker) — `verify_no_forbidden_content` + `FORBIDDEN_KEI_MEMOS` 등 Kei artifact 검출 자산은 Archive Candidate. Phase Z 본체에 Kei AI 호출 없음. §3 검토 대상 외. + +H5. (Archive marker) — `generate_with_retry` 는 Kei AI generation retry loop. Phase Z 본체 미존재. AI repair fallback axis 활성 시도 retry loop 자체 설계는 별 axis. §3 검토 대상 외. + +H6. (factual note) — 헤더의 L4 (Selenium) / L5 (Opus vision) layer 는 *문서적 계획*. 본 파일의 실 구현은 L1~L3 + retry loop. L4 는 §2.3 `slide_measurer.py` 영역 / L5 는 AI repair fallback axis (본 audit 외). + +#### Salvage Plan 검토 대상 dual-write 기준 (§3 에서 재확정) + +- **Salvage Candidate**: 없음 +- **Reference Only** 자산: §0-A 원칙 10 따라 활성 axis 결정 = *별 axis*. 활성 시 그 axis 의 SoT 따라 adapter / dual-write 기준 별도 결정. 본 §2.7 audit 단계의 dual-write 기준 적용 X. +- **Archive Candidate** 자산: §3 검토 대상 외. + +> ⚠ **본 §2.7 audit 판정은 Phase Z normal path 기준의 후보 분류이며, `content_verifier.py` 는 §3 Salvage 적용 대상이 없다 (Salvage Candidate 0).** §0-A 의 10 원칙 + §0-0 의 분류 기준 + §0-B Audit 범위 lock + AI 격리 invariant 모두 따름. Reference Only 자산은 future verification / visual_check 보강 / B-2 검증 별 axis 활성 시 *참고 여부만 별도 판단* (직접 통합 X). **L4 Selenium / L5 Opus vision 은 본 파일 구현 부재 — header documentation only**. ### 2.8 `renderer.py` — *후속 turn* @@ -772,7 +863,8 @@ audit 결과 → 어느 항목이: | 2026-05-11 | 정정 pass 2 계획 확정 | 대기 — B-1~B-5 결정 적용. sub-axis a~g 로 진행. 실행은 다음 turn | | 2026-05-11 | 정정 pass 2 본체 실행 (2-c hygiene fix 2 + 2-d / 2-e / 2-f / 2-g) | 완료 — L1~L4 boundary lock 반영. §0-B Audit 범위 lock 추가, §2.5 F-3 함수별 재분류 반영 (`calculate_design_budget` / `calculate_char_budget` / `calculate_budgets_for_candidates` / `calculate_trim_chars` → Reference Only), §3 / §4 legacy 용어 정리, §5-1 인라인 재분류 태그 5 entry append, 13 pattern context-aware grep 검증 수행. 산출 추가: `PHASE-Q-AUDIT-PASS-2-EXECUTION-PLAN.md`, `memory/feedback_scope_qualified_verification.md` | | 2026-05-12 | §2.6 content_editor.py audit | 완료 — Archive Candidate (module-level). Kei AI direct slot-fill flow. §3 검토 대상 외. 별도 surface: §1 B-1/B-2 매핑 부정확 (G2 별 axis), AI repair fallback infra reference 여부 별 axis (G3) | -| ... | §2.10 까지 1 모듈씩 | (대기) | +| 2026-05-12 | §2.7 content_verifier.py audit | 완료 — Mixed (Reference Only + Archive Candidate). Salvage Candidate 0. utility 다수 결정론적이나 Phase Z normal path 직접 빈칸 채움 부재 → Reference Only. Kei artifact 검출 + Kei AI generation retry loop = Archive. L4 Selenium / L5 Opus vision = 본 파일 구현 부재 (header documentation only). §3 적용 대상 없음. 별도 surface: §1 B-2 후속 매핑 간접, H1~H3 reference axis 후보, H4~H5 Archive marker, H6 L4/L5 factual note | +| ... | §2.8~§2.10 까지 1 모듈씩 | (대기) | | (last) | §2.11 pipeline.py / pipeline_context.py | (대기) | | (then) | §3 Salvage Plan | (대기) | | (then) | §4 우선순위 재정렬 → ROADMAP 갱신 | (대기) |