# 03 — Gap Analysis

This analysis compares the current TheRoad-I1 system with the direction suggested by CANVAS, StoryMem, VideoMemory, OneStory, Story2Board, and ViStoryBench.

## Summary Table

| Capability | Current TheRoad-I1 state | Gap | Priority |
|---|---|---|---|
| Structured shot contract | Strong: RenderPromptCard and v25 scene_detail prompt | Needs higher-level memory interface | High |
| Character identity refs | Strong base: short IDs, outlooks, subject_reference_policy | Needs long-range appearance-state timeline | High |
| Background continuity | Strong per-shot refs and provenance checks | Needs reusable location anchor memory across non-consecutive scenes | High |
| Prop state continuity | Partial: render_contracts, keep_elements, scene refs | Needs explicit prop state transitions and evaluator | High |
| State/gaze separation | In progress: v13 schema and W1 helper | Need finish W3-W9 consumer migration | High |
| Post-generation memory update | Weak | Need VLM observed-state summary after each generated image | High |
| Candidate verification | Partial validators | Need CANVAS-style targeted continuity QA | Medium |
| Benchmarking | Unit/integration/residue gates | Need storyboard continuity benchmark set | Medium |
| Dynamic visual memory | Raw refs/history exist | Need compact visual memory index/retrieval policy | Medium |
| Prompt contamination control | Strong policy, active migrations | Need systematic prompt-pack hygiene docs and gates | Ongoing |

## Gap 1 — World State Is Distributed, Not First-Class

Current state is distributed across:

- `EntityCanon` and entity metadata,
- outlook refs,
- background prompt/render outputs,
- `shot_staging`,
- `scene_consistency`,
- `RenderPromptCard`,
- `scene_reference_service`,
- generated `ImageAsset` rows,
- prompt-pack rules.

This works for local invariants, but it makes long-range questions hard:

- Has this location appeared before?
- Which exact background anchor should be reused?
- Is this prop present, moved, hidden, destroyed, or absent?
- Which character appearance state is active in this shot?
- Did the generated image actually satisfy the intended state?

CANVAS solves this by explicitly modeling characters, locations, and object states. TheRoad-I1 should add a first-class memory layer rather than inferring the answer from multiple checkpoints.

## Gap 2 — RenderPromptCard Is Overloaded Risk If Used As Memory

RenderPromptCard is excellent for the shot-level prompt contract. It should stay that way.

Risk:

```mermaid
flowchart LR
  GlobalFacts[Global story facts]
  SceneFacts[Scene continuity]
  ShotFacts[Shot contract]
  RPC[RenderPromptCard]
  GlobalFacts --> RPC
  SceneFacts --> RPC
  ShotFacts --> RPC
  RPC --> Overload[Overloaded card / hard to version / hard to audit]
```

Better:

```mermaid
flowchart LR
  GlobalFacts[StoryWorldMemory]
  SceneFacts[SceneContinuityPlan]
  ShotFacts[RenderPromptCard]
  GlobalFacts --> SceneFacts
  SceneFacts --> ShotFacts
```

The card should consume selected memory facts. It should not store the entire world state.

## Gap 3 — Reference Retrieval Is Strong But Memory Selection Is Not Yet Global

`scene_reference_service.py` already has valuable mechanisms:

- image indexing,
- ID-to-image rewriting,
- previous-shot background reference construction,
- ref_usage branching,
- source provenance validation,
- state variant lookup.

What is missing is a retrieval policy that asks a global memory bank:

- Which character anchor is canonical for this appearance state?
- Which location anchor best represents this recurring location?
- Which prior frame is useful for camera/spatial continuity?
- Which prop visual reference reflects the current prop state?
- Which reference is forbidden because the current story state changed?

## Gap 4 — Prompt Hygiene Is Treated As Cleanup, Not As Architecture

The current work on Area #1 and Area #2 is not just cleanup. It is an architectural migration:

- semantic decision by LLM producer,
- closed-world enum/ID validation by code,
- no semantic regex or noun-list inference,
- fail-fast if required structured fields are missing,
- active prompt residue gates.

This should become the default design rule for future memory and evaluation work.

## Gap 5 — Evaluation Is Not Yet Storyboard-Level

The repo has tests and validators, but the research suggests a broader evaluation stack:

```mermaid
flowchart TD
  Unit[Unit tests<br/>schema/helper]
  Contract[Contract tests<br/>RenderPromptCard / manifest]
  Prompt[Prompt residue gates]
  Image[VLM image QA]
  Story[Storyboard continuity benchmark]

  Unit --> Contract
  Contract --> Prompt
  Prompt --> Image
  Image --> Story
```

Current tests mostly cover the first three layers. The next step is automated image continuity QA and curated long-range storyboards.

## Gap 6 — Dynamic Memory Needs Provenance Before Embeddings

It is tempting to add CLIP/VAE embeddings first. That would be premature unless each memory item has:

- source step,
- source image asset ID,
- scene/shot index,
- entity IDs,
- memory type,
- schema version,
- confidence/evaluator output,
- invalidation policy.

CANVAS and StoryMem show that memory helps, but TheRoad-I1's existing lessons show that silent fallback and provenance drift are more dangerous than missing memory.

## Gap 7 — State/Gaze Is One Example Of A Larger Pattern

Area #2 separates gaze direction, target identity, and subject state. The same pattern should be checked for:

- visibility vs identity vs reference requirements,
- prop presence vs prop state vs prop visual reference,
- location identity vs background image vs camera viewpoint,
- framing scale vs body-part/sub-region prompt wording,
- memory/ref usage vs exact image-source provenance.

Each overloaded field should be split into structured axes before it becomes a downstream rule source.

## Highest-Risk Current Areas

1. **Legacy state/gaze consumers**  
   Current code still has `gaze_target` reads in state variant and semantic contract paths until Area #2 later waves land.

2. **Scene_detail prompt legacy prose**  
   v25 correctly states card priority, but still contains legacy compatibility prose. This is acceptable only if residue gates and card fields keep winning.

3. **Reference/memory ambiguity**  
   `scene_reference_service` can build references, but the selection policy is still more local than CANVAS-style global continuity memory.

4. **Post-generation truth gap**  
   The system can ask for continuity, but it needs stronger memory update from the generated image itself.

## What Success Should Look Like

After the next architecture phase:

- Each shot has a RenderPromptCard.
- Each scene has a SceneContinuityPlan.
- Each episode has a StoryWorldMemory.
- Each generated image produces observed-state metadata.
- Each memory update has source provenance and schema version.
- Each candidate image can be rejected for concrete continuity failures.
- Prompt packs mostly describe how to consume structured contracts, not infer semantics from prose.