W21B Wave 1 Implementation Brief
배경 먼저 개선하기 위한 첫 구현 wave. 목표는 chain background plate의 톤과 순도를 회복하고, 이후 visual review에 필요한 reference lineage를 남기는 것이다.
요약
이번 wave는 코드를 크게 넓히지 않는다. background_prompt v8을 만들고, 기존 chain background render가 어떤 reference를 실제로 썼는지 write-only diagnostic으로 남긴다. 장면 PNG의 시네마틱 톤, 외부 plate 추가, 샷 커버리지, 시신 연속성, 동물 reference 포맷 분리는 이번 wave의 통과 조건이 아니다.
시각 품질 판정은 사용자와 Codex가 chain background PNG before/after를 직접 보고 결정한다. grep 토큰 카운트나 LLM/VLM semantic gate는 이번 wave에 넣지 않는다.
1. Scope Decision: W21D-small
기본 결정: W21D-small, 즉 entity-type-aware reference contract는 이번 wave에서 바로 끼우지 않는다. 먼저 dry-run으로 affected files와 코드 이동량을 확인한다. 아래 조건을 만족할 때만 같은 wave의 별도 commit으로 포함한다.
| 옵션 | 포함 조건 | 이번 brief의 기본값 |
|---|---|---|
| W21D-small 포함 | prompt_service 또는 reference role wording 수준의 작은 분기이며, schema 변경이 없고, producer cascade가 없고, 대략 100 LoC 이하로 닫힐 때. |
dry-run 후 가능하면 별도 commit으로 포함 |
| W21D-small 분리 | entity extractor prompt pack, reference image generation 포맷, role enum producer, scene reference consumer를 함께 건드려야 할 때. | 이 경우 W21D 별도 wave |
이 판단은 구현 시작 전에 Claude가 코드 구조를 다시 확인한 뒤 Codex와 의논해서 확정한다. 로트와일러가 사람처럼 철창을 짚는 문제는 중요하지만, 이번 wave의 핵심은 BG plate이므로 scope가 커지면 분리한다.
2. Non-goals
- scene shot PNG의 global cinematic tone 개선. 이번 wave의 톤 평가는 chain_bg plate만 대상으로 한다.
surface_role, exterior plate, transition plate 생성. 이는 W21B-wave-2에서 다룬다.same_physical_space_view/related_style_new_spacerouter와 layout lock. 이는 W21B-wave-3이다.- director coverage, establishing shot 자동 추가, shot sequencing. 이는 W21A0이다.
- scene_state_timeline, previous shot continuity, 시신/사진/자세 연속성. 이는 후속 continuity wave이다.
- entity description raw concat 전면 차단. W21D-small이 작으면 포함 가능하지만, 큰 변경이면 별도 wave로 분리한다.
- LLM/VLM semantic gate 추가. 이번 wave는 prompt contract와 visual review만 사용한다.
- fresh project full E2E. 이번 wave는 기존 W20E7 project에서 BG render만 재실행한다.
3. Implementation Touchpoints
| 영역 | 대상 | 변경 방향 |
|---|---|---|
| Prompt v8 | prompts/_base/background_prompt/8.20260528HHMM/ |
v7을 복제해서 BG cinematic tone과 BG-only purity contract를 재작성한다. v7은 보존한다. |
| Prompt selector | backend/app/modules/pipeline/background_prompt.py |
PROMPT_VERSION_MAP에 "8"을 추가한다. v6/v7 selector는 유지한다. |
| Settings | backend/app/core/config.py |
background_prompt_version Literal에 "8"을 추가한다. 기본값 변경은 하지 않는다. |
| Step version | backend/app/core/steps/background_prompt_step.py, backend/app/core/step_manifest.py |
출력 schema를 바꾸지 않으면 SCHEMA_VERSION은 유지한다. prompt version은 config hash로 이미 반영된다. 출력 shape를 바꾸게 되면 schema와 manifest를 같이 올린다. |
| Audit metadata | backend/app/core/steps/background_render_step.py |
실제로 첨부된 floor plan / prior BG reference lineage를 write-only diagnostic으로 저장한다. reference 선택 로직은 바꾸지 않는다. |
| Optional D-small | backend/app/services/prompt_service.py 등 |
dry-run 결과가 작을 때만 animal/prop reference wording을 human passport-style에서 분리한다. 크면 별도 wave. |
4. Prompt v8 Patch Range
4.1 Cinematic BG Tone
v7의 anti-stylization checklist는 "luxury showroom drift"를 막기 위해 만들어졌지만, review.pdf의 사람이 직접 만든 비교 prompt와 반대로 documentary-flat 결과를 유도한다. v8에서는 금지 대상을 재정의한다.
| 항목 | v8 방향 |
|---|---|
| 허용 | cinematic photoreal background plate, restrained film grain, desaturated genre color, natural anamorphic lens behavior, Korean occult / crime-thriller realism 같은 장르 톤. 단 특정 작품명을 production logic에 하드코딩하지 않는다. |
| 차단 | CGI, concept art, illustration, luxury showroom, glossy architectural visualization, stock-photo perfection, over-designed studio set. |
| 주의 | scene shot의 lens/camera grammar는 이번 wave의 acceptance가 아니다. v8은 chain_bg plate의 미학만 다룬다. |
4.2 BG-only Purity
BG plate는 빈 공간과 고정된 환경을 굽는 레이어다. 인물, 손, 팔, 얼굴, 시신, 사건 순간의 혈흔, 사진을 만지는 행위, 현재 shot의 action state는 scene layer 또는 I2I layer에서 처리한다.
scene_segments_block를 장면 본문 verbatim으로 넣는 구조를 유지하지 않는다. 새 LLM summarizer를 추가하지 않고, 기존 structured inputs에서 필요한 정보만 넘긴다.- v8 user prompt는
base_markers, clean overlay, persistent fixture, fixed furniture, visual world rules, applies-to-shot identifiers 같은 구조화된 정보 중심으로 구성한다. - transient overlay marker는 "반드시 prose로 번역"하지 않는다. plate에 영구적으로 남을 surface condition이 아니라면 BG prompt에서 빼거나 future staging clearance로만 사용한다.
subject_position_directive는 BG prompt 출력에서 제거한다. 필요하면 사람을 둘 빈 공간을 남기는subject_clearance_directive로만 표현한다.- negative phrasing에 의존하지 않는다. "사람이 없다"를 길게 쓰면 이미지 모델이 사람 토큰을 주워 그릴 수 있다. 그릴 것을 positive constraint로 쓴다.
4.3 Output Schema
이번 wave는 가능한 한 background_prompt output shape를 유지한다. t2i_prompt, ref_guide, shot_guides, objects_owned_by_background, spec, group_id의 구조를 바꾸지 않는 것이 기본이다. schema 변경이 필요해지면 그 순간 별도 판단을 위해 멈춘다.
5. B4 Audit: Write-only Lineage
강한 제한: 이 wave의 audit 변경은 read/write diagnostic만 허용한다. 기존 reference 선택, planner output, adapter mode, image generation path의 behavior는 바꾸지 않는다.
목표는 "이 BG가 어떤 reference를 실제로 첨부해서 생성됐는가"를 canary review 시점에 역추적 가능하게 하는 것이다.
background_render_step가 이미 결정한fp_path와prior_bg_paths를 기준으로 attached reference lineage를 기록한다.- 가능하면 실제
ImageAsset.id를 resolve해서ImageAsset.reference_image_ids에 저장한다. resolve가 불안정하면 checkpoint diagnostic에fp:<fp_id>,bg:<bg_id>같은 stable label을 남기고 DB 필드는 무리하게 채우지 않는다. - 이미지 선택 순서, 첨부 path, provider 호출 인자는 변경하지 않는다.
- audit 필드가 비어도 render는 실패시키지 않는다. audit 실패는 warning diagnostic으로만 남긴다.
6. Canary Plan
선택: fresh project가 아니라 W20E7 project의 BG render 재실행만 한다. 비용과 변수를 줄이고, prompt v8의 효과만 본다.
| 항목 | 값 |
|---|---|
| Project | 4f948193-6809-4ae3-a3c6-2ca4e8af1c1a (금월도 E2E W20E7 20260527 2120) |
| Episode | dc70c0b3-5c09-4664-8c0f-9cac38c0c6ca |
| Execution unit | background_prompt force 후 background_render force. 정확한 endpoint는 실행 직전 route 확인 후 사용한다. |
| Image budget | 기본 제안 image_call_cap=20. 실제 이미지 API 호출 전 사용자/Codex 승인을 다시 받는다. |
| Fresh E2E | 이번 wave에서는 하지 않는다. 누적 wave가 닫힌 뒤 별도 평가로 미룬다. |
7. Visual Acceptance
이 절만 wave 통과/실패 판단에 사용한다. deterministic sanity check 통과는 품질 통과가 아니다.
- 대상은 새로 렌더된
chain_bgplate PNG다. scene PNG는 평가하지 않는다. - L05 옥탑방 내부 plate에서 손, 팔, 얼굴, 시신, 현재 사건 순간의 혈흔이나 사진 행동이 BG로 굳어 보이면 실패다.
- 공간 자체가 빈 방 / 고정 가구 / 낡은 표면 / 창문 / 벽 / 바닥 / 조명 중심으로 읽혀야 한다.
- cinematic photoreal tone은 살아야 한다. documentary-flat, product-photo, showroom, CGI, concept-art 느낌이면 실패다.
- 평가는 사용자와 Codex의 before/after visual review로만 한다. grep 토큰 카운트, literal keyword check, LLM/VLM semantic 판정은 이번 wave acceptance가 아니다.
8. Deterministic Sanity Check
| 체크 | 목적 |
|---|---|
| prompt pack load | background_prompt v8 selector가 pack을 정확히 찾는지 확인. |
| settings literal | BACKGROUND_PROMPT_VERSION=8이 config validation을 통과하는지 확인. |
| schema sync | 출력 shape를 바꾸지 않았으면 schema bump가 없어야 한다. 바꿨다면 step과 manifest가 같이 올라야 한다. |
| audit write shape | reference audit이 list/dict shape로 안정적으로 저장되는지만 확인. reference 선택 효과는 검증하지 않는다. |
git diff --check |
whitespace와 patch hygiene 확인. |
broad/full pytest는 실행하지 않는다. focused deterministic tests만 사용한다.
9. Sub-steps and Commit Units
권고는 단일 PR, 분리 commit이다. 구현 중 scope가 커지면 commit을 더 쪼개거나 별도 wave로 분리한다.
| Commit | 내용 | 조건 |
|---|---|---|
| 1 | BG prompt v8 + selector/config wiring + focused deterministic test | 필수 |
| 2 | Reference lineage audit write-only metadata + focused test | 필수. behavior 변경 금지 |
| 3 | W21D-small entity-type-aware reference wording | dry-run에서 작고 고립된 변경으로 확인될 때만 포함 |
10. Stop Conditions
- W21D-small이 schema, producer cascade, reference image generation format까지 건드려야 하면 이번 wave에서 분리한다.
- prompt v8이 output schema 변경을 요구하면 Codex와 다시 의논한다.
- image API 호출이 필요한 canary 단계에서는 cap과 비용 승인을 다시 받는다.
- route/env/config drift로 기존 W20E7 checkpoint가 막히면 force 범위를 넓히기 전에 원인을 보고한다.
- visual acceptance가 실패하면 semantic gate를 추가하지 말고 prompt v8을 좁게 수정한 뒤 다시 비교한다.
11. Handoff Request to Claude
Claude는 이 문서를 읽은 뒤 바로 큰 코드 변경을 시작하지 않는다. 먼저 dry-run으로 affected files를 확인하고, W21D-small 포함 여부와 patch 단위를 Codex와 의논한다. 그 다음 승인된 범위에서 W21B-wave-1 구현에 들어간다.
첫 보고 형식: "W21B-wave-1 dry-run 결과: touchpoints, W21D-small 포함/분리 판단, 예상 commit 단위, canary 실행 전 필요한 승인". 이후 Codex 응답을 받고 코드 patch를 시작한다.