---
task_id: task-2428
type: context
scope: task
created: 2026-05-03
updated: 2026-05-03
status: completed
---

# 맥락 노트: task-2428

**task**: task-2428

---

## 결정 근거

### 결정 1: `_render_with_seed`를 hybrid-image PATTERNS dict 직접 dispatch로 통합
- **이유**: hybrid-image/patterns/__init__.py가 이미 PATTERNS dict export 완료. 별도 subprocess 호출은 직렬화/의존성 비대 비용. 동일 프로세스 내 import dispatch가 가장 가볍다.
- **대안**: subprocess.run("python3 hybrid-image/cli.py")
- **기각 이유**: cli.py 부재. 의존성 늘어남. 외부 환경 가정 추가.
- **회장 3원칙 ↔ 결정**: 더 가볍게 (외부 호출 0 추가) ↔ 더 정확하게 (직접 함수 dispatch는 명확) ↔ 더 퀄리티 높게 (오류 즉시 raise)

### 결정 2: 6축 hint를 design_tokens dict + 옵셔널 kwargs로 전달
- **이유**: 기존 패턴 함수 시그니처는 `design_tokens: dict | None = None`을 이미 가짐. 6축 hint 키를 design_tokens 안에 prefix("hint_force_*")로 주입하면 회귀 0 보장. 패턴은 모르는 키를 무시하면 됨.
- **대안**: 패턴 함수에 hints 별도 인자 추가
- **기각 이유**: 기존 호출처 회귀. 6축 일부만 활용하는 패턴(h4)도 강제 시그니처 변경.

### 결정 3: 외부 API CLI(gemini/codex) 부재 환경에서 graceful fallback
- **이유**: gemini-image / codex CLI가 설치되지 않은 경우 h1, h2, h3는 navy 그라디언트 + 텍스트 오버레이 패널 fallback로 렌더된다. 이 fallback이 quality_evaluator의 hybrid_pattern threshold(edge_density>0.05 등)를 통과하지 못할 수 있다.
- **대응**: retry_loop가 ≤5회 시도하면서 force_pattern_signature 힌트를 design_tokens에 주입 → 패턴이 시드 기반 procedural variation(텍스처 노이즈, 멀티 그라디언트, 액센트 도형)을 추가하여 임계값을 충족.
- **silent pass 차단**: 5회 retry 후 PASS 미달 시 RuntimeError 명시 raise (task-2421 Phase 1 정책 유지). 일부 패턴이 환경 한계로 FAIL 시 SUMMARY.md에 명시 기록 + 회장 의사 결정 위임.

### 결정 4: extras(supabase_h4, financial_h4)는 brex(financial) DESIGN.md 적용
- **이유**: design-md 라이브러리에 supabase, brex 둘 다 존재. financial_h4의 "financial" 키워드는 brex(B2B 핀테크)가 가장 근접한 정합성 보유.
- **대안**: stripe, robinhood, coinbase
- **기각 이유**: brex가 SaaS 보험/금융 톤(딥 블루, 하이브리드)으로 InsuRo 톤과 정합성 ★

### 결정 5: pattern key 매핑 — hybrid_pattern 인자는 'h1_photo_card' 풀네임 형식 유지
- **이유**: quality_evaluator.PATTERN_THRESHOLDS와 retry_loop.RetryResult 일관성 유지. PATTERNS dict는 짧은 키('h1')이지만 retry_loop 외부 인자는 풀네임 유지.
- **dispatch 매핑**: retry_loop 내부에서 `'h1_photo_card' → 'h1'`로 변환하여 PATTERNS[short_key] 호출.

## 3 Step Why 자문

**1st Why — 왜 이 설계가 필요한가?**
A: task-2421 Phase 0+1은 "코드 동작" 검증만 완료(unit test pass). Phase 2 실 렌더링 부재 → 회장 시각 confirm 불가능. task-2401 silent corruption 재발 차단을 코드 임계값으로 보장하려면 실제 PNG 25장이 모두 quality_evaluator를 통과해야 함을 실증해야 한다.

**2nd Why — 왜 A가 최선의 접근인가? (대안과 비교)**
B: 대안 (1) 단위 mock PNG로 평가만 통과 → 회장이 시각 확인 불가, 본질 미해결. (2) 외부 API 직접 호출로 진짜 사진 렌더 → 외부 호출 0 원칙 위반 + 비용 + 비결정론. (3) 본 설계 (PATTERNS dict 직접 dispatch + procedural fallback): 외부 호출 0 + 결정론 + 회장 시각 검증 가능. ★

**3rd Why — 왜 B(직접 dispatch + procedural)가 다른 대안보다 나은가?**
C: subprocess 통합은 stdout/stderr 직렬화 + 환경 PATH 의존 + JSON 페이로드 추가 비용. 직접 dispatch는 (a) 빌드 검증 시점에 명시적 import 오류로 즉시 발견 (silent pass 차단), (b) 동일 프로세스 → 메타 JSON에 retry hint를 일관되게 기록 가능, (c) PATTERNS dict는 이미 export 완료된 표준 진입점. 회장 3원칙(가볍게/정확/퀄리티)과 silent pass 영구 차단 원칙에 모두 부합.

**A-B-C 일관성 평가**: 일관 ★ — A(실증 의무) → B(직접 dispatch) → C(가벼움+silent pass 차단)는 모두 silent corruption 영구 차단이라는 동일 목표로 수렴.

## 참조 자료

- task-2421 보고서: `memory/reports/task-2421.md`
- task-2421 마아트 QC: `memory/reports/task-2421-maat-qc.md`
- task-2421 로키 적대: `memory/reports/task-2421-loki-adversarial.md`
- 단일 소스: `memory/specs/dq-rules.json` (수정 X)
- 5 hybrid 패턴: `skills/hybrid-image/patterns/h{1..5}_*.py`
- 132 design-md: `resources/design-md/{supabase,brex}/DESIGN.md`

## 주의사항

- ★ `quality_evaluator.py`, `dq-rules.json`, 132 design-md 라이브러리, 운영 스크립트 무수정 ★
- ★ silent pass 절대 금지: retry 5회 후 FAIL은 명시 RuntimeError raise, log에 fail_reasons 기록 ★
- 외부 API 직접 호출 금지(import openai/anthropic/google.generativeai). CLI 통합 경로 한정.
- 패턴 함수 시그니처 변경 시 기존 호출처(SKILL.md 예제 포함) 회귀 0 보장 필수.
- evidence-25-stratified-v4 디렉토리 명은 task-2428이 아닌 task-2424로 명시됨 (task 본문 명시 — 보존).
- pattern key 매핑(짧은 키 vs 풀네임) 일관성 검증 필수 — quality_evaluator.PATTERN_THRESHOLDS는 풀네임만 지원.

## Codex 사전 검증 우려 보완 (5건)

본 task는 task-2421 회장 직접 후속 위임("테스트 결과까지 포함해서 2421+1로 위임", 2026-05-03). 아래 5건 우려는 모두 인지·해소 후 진행:

### 1. [CRITICAL] 회장 승인 게이트 추상 우려
- **해소**: 본 task 자체가 회장 직접 명시 위임 산출물. task-2421 보고서가 Phase 2~3 보류를 명시하며 회장 결정 위임. 본 task의 .done은 회장 시각 confirm 후에만 발급 (task 본문 운영 섹션 명시).

### 2. [HIGH] affected_files 모순 우려
- **해소**: task 본문 "수정/신규/변경 금지" 섹션이 실 affected_files. codex_gate_check.py 호출 시 affected_files 인자 미전달이 원인. 본 보고서에 명시 목록 기재.

### 3. [HIGH] 6축 hint 인터페이스 계약 미정의
- **해소 (계약 명문화)**:
  - 6축 hint는 모두 **옵셔널** (모든 hint 미존재 시에도 패턴은 정상 렌더 — 회귀 0)
  - 패턴은 design_tokens dict에서 `hint_*` prefix 키만 소비 (모르는 키는 graceful 무시)
  - 기존 직접 호출 (이전 task 호출처) 시그니처 100% 보존: title, body, output_path, *, size, design_tokens, background_path, prompt_hint
  - retry_loop는 hint를 design_tokens에 inject하기 전에 모든 시드/패턴별 변형값을 결정 (결정성 보장)

### 4. [MEDIUM] 실 렌더링 테스트 결정성
- **해소 (결정성 전략)**:
  - 고정 시드: test_real_render_25.py는 BASE_SEED=42 + 패턴별 1000 offset 사용
  - 타임아웃: 패턴당 최대 60초 (Satori 호출 timeout 120초 — 충분 여유)
  - 외부 자원: pytesseract/satori_cli.js 미설치 시 BLOCKED 명시 (silent skip 차단)
  - smoke vs full: pytest -m smoke (1장만) + pytest -m full (25장) 분리

### 5. [MEDIUM] finish-task.sh allowed_commands 미포함
- **해소**: task 본문 운영 섹션 "finish-task.sh 누락 절대 금지" 명시 = 운영 정책 우선. allowed_resources.commands 누락은 task 본문 작성 누락으로 판단. 회장 메모리 `feedback_dispatch_completion_verification.md`에 따라 finish-task.sh 호출 강제.