# Seed 품질 2R — LLM 3종 프롬프트 변형 저작 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** outdoor_structure_seed 의 seed 생성을 "동일 프롬프트 3롤"에서 "LLM(Sol)이 3종 프롬프트 변형 저작(1=시나리오 원어 기반, 2·3=상이 접근) → 각 1롤 생성 → Gemini VLM 블라인드 판정 선정"으로 교체하고, 프롬프트 실측 진단 4건(①규모 서술 전무 ②개구부 정합 판정 축 부재 ③THE LOCATION=씬 헤딩 원문 ④시나리오 원어 질감 소실)을 반영한다.

**Architecture:** 신규 프롬프트 팩 `seed_prompt_variants` v1(저작 계약+judge/critique conformance addendum) + 신규 결정론 모듈 `seed_prompt_variants.py`(스키마/검증/조립) + `multiroll_select.run_multiroll_select` 의 backward-compatible `roll_prompts` 확장(라벨별 상이 프롬프트, 지문·record 포함) + `outdoor_structure_seed_step` 배선(플래그 default OFF, ON 시만 config_hash 스탬프). siteplan·이후 파이프(스케치/스틸)는 무변경(사용자 확정: 나머지 파이프 그대로).

**Tech Stack:** 기존 관례 그대로 — call_structured(LiteLLM router, Sol alias `"gpt"`), multiroll 공통 파이프(nb2 gen + gemini-pro 판정), prompt_loader 버전 팩, pytest 결정론 유닛.

## Global Constraints

- 절대 하드코딩·하드 프롬프팅 금지: 규모(매스·층수·상대 규모)는 **LLM이 시나리오 원문+건물 유형+지역 전형 위임으로 저작** — '3층' 등 수치를 코드/팩에 넣지 않는다. 시나리오 고유명사 금지(범용 계약만).
- LLM 입력 원문 절대 자르지 않기 — 관련 씬 시나리오 전문 그대로 전달.
- 프롬프트 팩=신규 버전 디렉토리(`1.202607161810`), 덮어쓰기 금지. 기존 structure_seed v4 팩의 seed_head/no_people 은 재사용(불변절은 코드 조립 — LLM 저작이 안전 계약을 떨어뜨릴 수 없게).
- 플래그 `structure_seed_variants_enabled` default OFF — OFF 시 전 경로 byte-identical(config_hash 무스탬프, 기존 지문 불변).
- TDD 는 결정론 영역만(스키마/검증/조립/지문). LLM/VLM 완성도=실측+육안.
- 글자/substring 의미 판단 금지 — validate 는 구조 검증만(개수/공백/pairwise 동일성).
- 스크립트 실행=backend cwd + `/Users/manta/Documents/Projects/TheRoad-I1/backend/.venv/bin/python` 절대경로.
- 커밋=태스크 단위. Codex 리뷰는 구현 완료 후(의견은 하순위·비판 수용).
- 판정 VLM=gemini-pro 단독(GPT VLM 제외 — 사용자 확정), 저작 LLM=Sol(`"gpt"` alias), 이미지=nb2.

## 진단→반영 매핑 (스펙 커버리지)

| 진단 | 반영 위치 |
|---|---|
| ① 규모 서술 전무 | author_sys: MASS & SCALE 절 — 시나리오 원문 수용량 근거+건물 유형+지역 전형 위임 저작, 근거 없는 정확 수치 발명 금지 |
| ② 개구부 정합 축 부재 | author 출력 `conformance_brief_en`(공유 불변 사실) + judge/critique addendum(brief 위반=미학보다 선행 감점·결함) |
| ③ THE LOCATION 조악 | author 출력 `location_line_en` — 씬 헤딩 포맷 재현 금지, 변형 모드에서 raw heading 주입 제거 |
| ④ 원어 질감 소실 | variant 1=원어 인용(evidence_ko)→시각 사실 변환 계약 |

---

### Task 1: 프롬프트 팩 `seed_prompt_variants` v1 + 결정론 모듈

**Files:**
- Create: `prompts/_base/seed_prompt_variants/1.202607161810/author_sys.md`
- Create: `prompts/_base/seed_prompt_variants/1.202607161810/judge_addendum.md`
- Create: `prompts/_base/seed_prompt_variants/1.202607161810/critique_addendum.md`
- Create: `backend/app/modules/pipeline/seed_prompt_variants.py`
- Test: `backend/tests/unit/test_seed_prompt_variants.py`

**Interfaces (Produces):**
- `resolve_variants_pack_version(version: str) -> str` (unknown → ValueError)
- `AUTHOR_MODEL = "gpt"`, `VARIANTS_PACK_MODULE = "seed_prompt_variants"`
- `build_author_schema(count: int) -> dict` — variants 정확히 count개, variant_id enum v1..vN
- `build_author_user_content(*, scene_indices, scene_texts, scene_headings, structure_desc, interior_note_en, exterior_note_en, world_anchor, excluded_transient_en, count) -> str` — 시나리오 전문 무절단
- `validate_variant_output(data: dict, count: int) -> list[str]` — 위반 목록(빈 리스트=통과)
- `assemble_variant_roll_prompts(*, data, labels, world_anchor, excluded_transient_en, seed_pack_version) -> dict[str, str]` — 라벨→전체 프롬프트(head+seed_head+변형 본문+THE LOCATION+EXCLUDED+no_people)
- `build_conformance_prompt(*, data, excluded_transient_en) -> str` — judge/critique 공용 브리프
- `load_variant_addendums(version) -> dict` — {judge_addendum, critique_addendum}

- [x] Step 1: 실패 테스트 작성(스키마 count/검증 위반 케이스/조립 불변절 포함/원문 무절단/scenario-neutral 팩 검사)
- [x] Step 2: 팩 3파일+모듈 구현 → 테스트 PASS
- [x] Step 3: 커밋 `feat(seed-2r): seed_prompt_variants 팩 v1+결정론 모듈`

### Task 2: multiroll_select `roll_prompts` 확장 (backward compatible)

**Files:**
- Modify: `backend/app/modules/pipeline/multiroll_select.py` (`run_multiroll_select`, `_critique_and_fix`)
- Modify: `backend/app/modules/pipeline/multiroll_gemini.py` (`make_gemini_judge_fn` prompt_header 옵션)
- Test: `backend/tests/unit/test_multiroll_select.py` (추가)

**Interfaces:**
- `run_multiroll_select(..., roll_prompts: Optional[Mapping[str, str]] = None)` — 제공 시: gen=라벨별 프롬프트, judge/critique 의 `prompt`=공유 브리프, critique 프롬프트=`roll_prompts[selected] + "\n\n" + prompt`, 지문에 roll_prompts 포함, record["roll_prompts"] persist. 라벨 집합 불일치=ValueError. 미제공=기존 동작·지문 byte-identical.
- `make_gemini_judge_fn(..., prompt_header: str = "THE PROMPT (all candidates were generated from this):")`

- [x] Step 1: 실패 테스트(라벨별 gen 프롬프트/지문 변화·기존 호출 지문 불변 잠금/critique 프롬프트 합성/record persist/라벨 불일치 ValueError)
- [x] Step 2: 구현 → 전체 유닛 PASS
- [x] Step 3: 커밋 `feat(seed-2r): multiroll roll_prompts 변형 롤 지원`

### Task 3: 플래그 + outdoor_structure_seed_step 배선

**Files:**
- Modify: `backend/app/core/config.py` (`structure_seed_variants_enabled: bool = False`)
- Modify: `backend/app/core/steps/outdoor_structure_seed_step.py` (`_config_hash` ON시 스탬프, `_execute` 변형 분기, author 호출 헬퍼 `_author_seed_variants` — validate 실패 1회 재시도 후 그룹 failed 격리)
- Test: `backend/tests/core/test_outdoor_structure_seed_step.py` (추가)

**동작:** ON 시 gid별 — lane scene_indices 의 씬 원문 전문 수집 → Sol 저작(call_structured, `{"seed_variant_author": {"model": "gpt"}}`) → validate → assemble+brief → run_multiroll_select(prompt=brief, roll_prompts=...) with judge_sys/critique_sys += addendum, prompt_header 교체 → asset prompt_used=선정 변형 전체 프롬프트, results 에 author 산출(variants/evidence/brief) 감사 기록. raw 씬 헤딩 THE LOCATION 주입은 변형 모드에서 제거(③). OFF=기존 경로 그대로.

- [x] Step 1: 실패 테스트(config_hash OFF 불변/ON 스탬프, 변형 분기 계약)
- [x] Step 2: 구현 → core+unit PASS
- [x] Step 3: 커밋 `feat(seed-2r): structure_seed 변형 저작 배선(flag OFF)`

### Task 4: Codex 리뷰 → 반영

- [x] 완료 — 리뷰 사이클 4회: 1차 NEEDS_REVISION 5건(judge film-still 충돌/3종 미고정/물리 모델 hash/무교정 재시도/record 미영속)→반영 1ca817f7, 3차 NEEDS_REVISION 2건(sidecar가 force·모델 변경 우회/roll_count 스탬프)→반영 6a73901a, 4차 APPROVED

### Task 5: rooftop 표적 재생성(실측) + 갤러리

- [x] 완료(2026-07-16 19시) — force 재생성 2그룹 실패 0(구본=.bak_seed_2r 백업), 둘 다 v1(원어 기반) 선정, 규모 서술 브리프 저작 실증. 갤러리=http://192.168.35.42:8901/seed_2r_gallery.html **사용자 육안 대기**. 잔여=육안 합의 후 하류(레인2 스케치·스틸) 재생성(lane 지문에 seed 바이트 포함=자동 전파)

## Codex 사전 의견 처리 노트 (참고만 — 채택 여부 재론 금지)

자체 분석과 겹치는 것만 반영: 공유 불변 brief(=진단② 해법으로 독립 도출), 원어 인용→시각 사실 변환(evidence_ko), 전형 위임(사용자 지시 자체), 저작 산출 영속(리포 표준). 미채택: 후보 전원 hard violation 시 재저작 루프(v1 범위 밖 — critique/fix 게이트 존치로 갈음, 후속 여지), unchanged_facts/variation_intent/confidence 구조 필드(과설계 — approach_ko+brief 로 충분), 창문 수 건물 전체/면별 구분 계약(judge addendum 은 '근거 없는 증식 금지' generic 문구로만 — 세분 계약은 실측 후).