# 06. Practical Roadmap

이 문서는 이상적인 재설계가 아니라, 현재 레포를 크게 흔들지 않고 prompt I/O 계약을 강화하는 현실적인 순서를 제안한다.

## 전제

현재 구조의 큰 방향은 유지한다.

- raw scenario에서 바로 final shot을 묻지 않는다.
- shot 후보를 많이 만들고, validator와 selection으로 줄인다.
- entity/outlook/background/continuity를 분리한다.
- scene_detail은 최종 prompt compiler 역할을 한다.
- 참조 이미지는 scene image보다 먼저 만든다.

따라서 도입 목표는 "새 pipeline"이 아니라 "현재 pipeline 결과를 더 검증 가능한 카드로 묶는 것"이다.

## Phase 0. 문서/계약 고정

목표: 구현 전에 용어와 소유권을 고정한다.

결과물:

- `ShotCandidateCard`
- `ShotSelectionCard`
- `ContinuityCard`
- `BackgroundCard`
- `RenderPromptCard`
- `AssetReadinessCard`

이 단계에서는 코드를 바꾸지 않아도 된다. 기존 checkpoint가 어느 card에 대응하는지만 mapping한다.

## Phase 1. Read-only card compiler

목표: 기존 checkpoint를 읽어 `creative_contract/manifest.json`을 생성한다.

동작:

```mermaid
flowchart LR
    A[Existing checkpoints] --> B[Read-only Card Compiler]
    B --> C[creative_contract manifest]
    C --> D[Validation report]
```

입력:

- `shot_validator/manifest.json`
- `shot_selection/manifest.json`
- `scene_consistency/manifest.json`
- `background_render/manifest.json`
- `scene_detail/manifest.json`
- `entity_t2i/manifest.json`
- `outlook_phase3/manifest.json`

출력:

```text
projects/{pid}/checkpoints/episodes/{eid}/creative_contract/
  manifest.json
  cards/**/*.json
  validation_report.json
```

중요:

- 기존 step output을 바꾸지 않는다.
- scene_image_pipeline도 아직 바꾸지 않는다.
- 먼저 report로 문제를 잡는다.

## Phase 2. Semantic validators 추가

목표: strict JSON schema로 못 잡는 의미 오류를 잡는다.

우선순위 높은 validator:

| Validator | 잡는 문제 |
|---|---|
| `selected_shot_subset` | background/continuity/render가 selected 외 shot 참조 |
| `visible_entity_subset` | scene_detail이 shot_director 밖 entity 추가 |
| `id_policy_consistency` | C##/C##O## 정책 충돌 |
| `continuity_framing_overlap` | 전신 fixed element와 body-part fixed element 동시 적용 |
| `background_dependency_graph` | bg/fp dependency cycle, missing id |
| `asset_path_readiness` | DB row/path/file 존재 불일치 |
| `close_framing_reference_policy` | close-up인데 reference image 사용 지시 |

출력 예:

```json
{
  "status": "partial",
  "expected_render_prompts": 288,
  "valid_render_prompts": 271,
  "blocked": [
    {
      "shot_key": "S12_Shot4_var_1",
      "reason": "missing background ImageAsset"
    }
  ]
}
```

## Phase 3. Prompt schema description 정합성 수정 계획

목표: prompt와 schema가 서로 다른 말을 하지 않게 한다.

가장 먼저 볼 것:

- `scene_detail` system prompt는 C##O## 사용을 요구한다.
- `scene_detail` schema description은 bare C##만 사용하라고 말한다.

이 상태는 strict JSON이어도 LLM에게 상충 지시를 준다. 해결 방식은 둘 중 하나를 선택해야 한다.

권장:

```text
scene_detail output t2i_prompt uses C##O## for visible real people with outfit binding.
outfit_assignments repeats the same binding for DB/UI sync.
Body-part closeups, printed/mirror/TV/reflection people use common nouns only.
```

즉 schema description을 system prompt와 맞춘다.

## Phase 4. Asset readiness preflight를 image phase 앞에 둔다

목표: "프롬프트는 맞는데 참조 이미지가 없어서 생성 실패"를 image API 호출 전에 차단한다.

위치:

```text
scene_detail
  -> t2i_review
  -> asset_readiness_preflight
  -> scene_image_pipeline
```

검증:

- C##O##에 해당하는 composite 또는 fallback refs 존재
- P## prop ref 존재
- chain_bg/background ref 존재
- file_path normalize 가능
- disk file 존재
- DB ImageAsset row 존재

정책:

- required ref 누락이면 `completed`가 아니라 `partial` 또는 `blocked`.
- text-only fallback은 명시적으로 허용된 경우만.
- silent except 금지.

## Phase 5. scene_detail을 compiler로 좁힌다

목표: scene_detail이 "새로 해석"하지 않고 upstream card를 조립하게 한다.

현재 scene_detail prompt에는 많은 실패 대응 규칙이 들어 있다. 이 규칙을 모두 없애자는 뜻이 아니다. upstream card가 명확해지면 scene_detail은 다음에 집중할 수 있다.

- selected shot 순간 유지
- visible entity subset 유지
- continuity element 통합
- background binding 사용
- C##/C##O## policy 적용
- T2I prompt syntax 출력

scene_detail이 하지 말아야 할 것:

- 새로운 인물 발견
- 새로운 prop 추가
- background state 재설계
- body pose 임의 변경
- 선택되지 않은 shot을 끌어오기

## Phase 6. UI/HITL card override

목표: 사람이 "샷/연속성/배경/프롬프트"를 직접 수정해도 재분석에 사라지지 않게 한다.

우선 UI 노출 후보:

- selected shot on/off
- continuity fixed element text
- dead/sleep/injury pose
- background state label
- background binding override
- render strategy direct/simplify/partial/reframe
- final prompt edit

저장:

```text
creative_contract/overrides/{override_id}.json
```

재실행:

- base card 재생성
- override 재적용
- conflict가 있으면 human review

## Phase 7. DB 승격

목표: episode를 넘어 재사용해야 하는 것만 DB로 올린다.

승격 후보:

- approved character canon
- approved character reference image
- approved outfit/outlook
- recurring location floor plan/background
- project-level visual world rules

DB로 올리지 않아도 되는 것:

- 모든 beat
- 모든 shot candidate
- 실패한 prompt variation
- asset readiness report
- temporary LLM uncertainty

## 평가 방법

### Golden episode set

작은 representative episode 2~3개를 고정한다.

포함해야 할 케이스:

- 같은 인물이 여러 의상 착용
- dead/sleep/injury fixed state
- 같은 실내 공간의 여러 shot
- close-up/body-part shot
- printed/TV/mirror/reflection person
- prop이 story-critical한 scene
- background state 변화

### Metrics

| Metric | 설명 |
|---|---|
| selected coverage | 사람이 중요하다고 본 shot이 selection에 포함됐는가 |
| continuity adherence | fixed state가 모든 관련 shot에 유지됐는가 |
| ref readiness | image generation 전 required ref가 모두 존재했는가 |
| prompt ID correctness | C##/C##O##/P##/[L##] 정책 위반률 |
| background consistency | 같은 bg_id를 쓰는 shot에서 공간이 유지됐는가 |
| retry rate | validation/rewrite로 인한 재시도 비율 |
| silent failure count | step completed인데 DB/asset 누락인 경우 |

### Evaluation flow

```mermaid
flowchart TD
    A[Run existing pipeline] --> B[Compile cards]
    B --> C[Run validators]
    C --> D{Report clean?}
    D -->|yes| E[Run image generation]
    D -->|no| F[Block or partial]
    E --> G[Visual LVM review]
    G --> H[Human spot check]
```

## 현실적인 1차 목표

가장 먼저 할 일은 새 prompt를 대량으로 갈아엎는 것이 아니다.

1. 현재 checkpoint를 card로 읽는 read-only report 생성
2. scene_detail ID policy 충돌 정리
3. asset readiness preflight 추가
4. selected shot subset/background applies_to_shots 검증
5. continuity fixed element overlap 검증

이 5개만 해도 "프롬프트가 이상해서 실패"와 "asset/path/DB가 없어서 실패"를 분리해서 볼 수 있다.

## 최종 방향

```text
LLM prompts produce cards.
Code validates cards.
Image generation consumes only validated cards.
Human edits override cards, not raw prompt fragments.
DB stores approved canon and assets, not every transient thought.
```