# 04 — Development Roadmap

This roadmap turns the research findings into practical work for TheRoad-I1.

## Guiding Principles

1. Structured SOT before prompt prose.
2. Closed-world enum/ID validation in code; semantic judgment by structured producer output.
3. No silent fallback for required contract fields.
4. Every durable memory shape gets schema/version/config hash discipline.
5. Generated-image observations must feed future memory.
6. Do not make RenderPromptCard a global memory container.

## Phase 0 — Finish Current Semantic Debt Waves

Finish Area #2 W1-W9 before adding a new memory layer.

Why:

- `shot_staging v13` introduces the right structured fields.
- Legacy `gaze_target` readers still exist in state variant, scene reference, semantic router, and shot visibility paths.
- A memory bank built before this cleanup would encode the old overload.

Completion signal:

- `gaze_target` legacy reads are gone except `gaze_target_id`.
- `IMMOBILIZED_GAZE`, `STATE_DESCRIPTIONS`, `_STATE_VARIANT_GAZE_VALUES` are removed or migrated.
- v13 prompt/schema is the active producer.
- residue gates distinguish `gaze_target_id` from legacy `gaze_target`.

## Phase 1 — Add StoryWorldMemory Read Model

Introduce a durable typed memory read model. Start read-only; do not immediately let it drive generation.

Suggested shape:

```mermaid
erDiagram
  STORY_MEMORY_ITEM {
    string id
    string project_id
    string episode_id
    int scene_index
    int shot_index
    string memory_type
    string entity_id
    string short_id
    string state_key
    string summary
    string image_asset_id
    string source_step
    int schema_version
    string confidence
  }

  IMAGE_ASSET ||--o{ STORY_MEMORY_ITEM : source_image
  ENTITY_CANON ||--o{ STORY_MEMORY_ITEM : entity
```

Memory types:

- `character_appearance_state`
- `location_anchor`
- `prop_state`
- `previous_frame_summary`
- `background_layout`
- `generated_observation`

Implementation direction:

- Add a service, not a prompt first: `backend/app/services/story_memory_service.py`.
- Write from existing checkpoints and generated image rows initially.
- Store provenance, not just free text.
- Do not let scene_detail consume it until the shape is proven stable.

## Phase 2 — Add Post-Generation Memory Update

After scene image generation, add a conservative observed-state record. Do not start by trusting a VLM evaluator as truth. The first implementation should be contract/provenance based and should only record facts already known from structured pipeline outputs plus generated asset metadata. A VLM can later propose observations, but those proposals must be low-trust and never overwrite memory automatically.

Initial inputs:

- RenderPromptCard,
- scene_detail t2i_prompt,
- visible_entities,
- references attached,
- existing memory items,
- generated ImageAsset metadata.

Initial outputs:

- selected reference usage record,
- intended character/background/prop state record,
- generated asset provenance,
- memory update candidates marked `source=contract_intent`.

Optional later inputs:

- generated image,
- advisory model observation.

Optional later outputs:

- `source=model_observation` candidates with confidence and manual-review status.

```mermaid
sequenceDiagram
  participant Gen as Image generation
  participant Eval as Observer
  participant Card as RenderPromptCard
  participant Mem as StoryWorldMemory

  Gen->>Eval: generated asset metadata
  Card->>Eval: expected contract
  Mem->>Eval: prior memory
  Eval->>Mem: observed-state update
  Eval->>Gen: pass/fail diagnostics
```

Guardrails:

- No model observer is allowed to rewrite contracts.
- Model observations, if introduced later, can only propose memory updates.
- Store observer prompt version/model when model observations are used.
- Include `unknown` / `not_verified` rather than forcing a visual judgment.

## Phase 3 — Memory-Guided Reference Retrieval

Upgrade `scene_reference_service` to retrieve memory-backed anchors.

Current service already handles reference image maps and previous-shot background refs. Add a retrieval policy:

| Need | Retrieval source |
|---|---|
| same character, same appearance state | `character_appearance_state` memory |
| revisited location | `location_anchor` memory |
| prop persists or changes | `prop_state` memory |
| exact shot continuation | previous frame / `previous_frame_summary` |
| atmospheric reference | location/style memory, not layout copy |

Start with read-only logging:

- Which memory item would have been selected?
- Which current ref was selected?
- Did they match?

Only after that, let memory drive `required_refs`.

## Phase 4 — SceneContinuityPlan

Add a scene-level plan that bridges global memory and shot cards.

Responsibilities:

- cluster shots by location identity,
- identify recurring background anchors,
- track prop state transitions,
- identify character appearance-state changes,
- mark future-conditioned requirements.

Do not place this inside `scene_detail`. This should run before shot-level prompt construction.

```mermaid
flowchart TD
  Script[Shot list + scene text]
  Prior[StoryWorldMemory]
  Plan[SceneContinuityPlan]
  Staging[shot_staging]
  RPC[RenderPromptCard]

  Script --> Plan
  Prior --> Plan
  Plan --> Staging
  Plan --> RPC
```

## Phase 5 — Candidate QA Selection

CANVAS uses QA selection, but TheRoad-I1 should not treat this as reliable enough for autonomous closure. Candidate QA should be optional, expensive-mode only, and advisory. It can help choose among candidates, but it must not replace contract checks, provenance checks, or human review for high-risk cases.

Candidate QA dimensions:

- prompt alignment,
- character identity,
- character state,
- background continuity,
- prop presence/state,
- frame spatial contract,
- forbidden reference leakage,
- single-camera moment.

Output:

- candidate score,
- failure reasons,
- selected image ID,
- rejected image IDs,
- memory update confidence.

## Phase 6 — Benchmark Pack

Create a local `ContinuityBench` for this project.

Minimum set:

1. recurring location after several scenes,
2. prop moved/removed and later referenced,
3. character outfit/state changes,
4. close framing with exact previous-shot zoom,
5. background reference skipped due to close framing,
6. multi-character gaze/visibility case,
7. state variant character ref case.

Each case should include:

- input script segment,
- expected structured checkpoints,
- generated images,
- advisory review notes,
- human audit notes.

## Practical Ordering

```mermaid
gantt
  title Suggested Direction After Area #2
  dateFormat  YYYY-MM-DD
  section Cleanup
  Finish Area #2 W1-W9           :a1, 2026-05-17, 5d
  section Memory Foundation
  StoryWorldMemory read model     :b1, after a1, 4d
  Post-generation observer        :b2, after b1, 5d
  section Retrieval
  Memory retrieval dry-run        :c1, after b2, 4d
  Memory-backed refs gated        :c2, after c1, 4d
  section Evaluation
  ContinuityBench local pack      :d1, after b2, 6d
  Candidate QA selection          :d2, after d1, 5d
```

## Risks And Controls

| Risk | Control |
|---|---|
| Memory layer becomes another prompt prose dump | typed schema, versioning, short IDs, source provenance |
| Model observer invents facts | observed/proposed/finalized states separated; model output advisory only |
| Reference retrieval silently falls back | AppError or explicit not_applicable state |
| RenderPromptCard grows too large | keep global/scene memory outside card |
| Prompt contamination returns through examples | active prompt residue gates and synthetic placeholders only |
| Candidate QA cost explodes | feature flag and candidate count cap |

## Work Items To Open Later

1. `StoryWorldMemory` schema/design spec.
2. Post-generation observed-state record spec.
3. Memory-backed `scene_reference_service` retrieval dry-run.
4. ContinuityBench case schema.
5. Candidate QA selector spec.
6. Prompt pack hygiene sweep for remaining body-part/noun-list examples not owned by current active areas.