Phase 0/1 Execution Plan

Phase 0 - Contract And Entry Gates

Phase 0은 code behavior를 크게 바꾸지 않는 준비 단계다. 새 enum, 새 schema, 새 prompt-pack을 만들지 않는다. 대신 용어와 테스트 계약을 고정한다.

Phase 0 Deliverables

1. Short design note in this HTML folder is sufficient. No production code required.
2. Test names and fixtures are defined before code edits.
3. Use live checkpoint/project artifacts for reproduction. Do not use local SQLite as active evidence.
4. Decision log: Phase 1 only changes policy reconciliation, not shot selection, shot staging prompt, or scene_detail prompt.

Phase 1 - Deterministic Reconciliation

Phase 1 introduces one shared detector and one consumer in build_render_prompt_card(). It is intentionally smaller than a full C10 structured-state migration.

Detector Contract

detect_offscreen_referenced_subjects(
    visible_ids,
    camera_direction,
    character_angles,
    id_to_name,
    pov_character,
) -> dict[subject_id, reason]

Emit subject_id only when:
1. subject_id is a visible character candidate;
2. character_angles is non-empty;
3. subject canonical name is not represented in character_angles;
4. subject is not pov_character;
5. camera_direction has an OFFSCREEN_RE match;
6. do not use gaze_direction_kind == "off_screen" as a signal.

Optional confidence:
- subject canonical name appears near the OFFSCREEN_RE match -> confidence="named"
- no local name match but structural absence + off-screen camera direction holds -> confidence="structural"

Preferred Placement

The policy override should live inside backend/app/core/steps/render_prompt_card.py::build_render_prompt_card, between:

raw_srp_items = filter_subject_reference_policy_to_visible(...)
# new reconciliation here
policy_map = normalize_subject_reference_policy_items(...)

This placement ensures the same card is used by LLM prompt construction, downstream validation, asset requirement derivation, and verify/recompute paths.

Name Map Threading

build_render_prompt_card() currently receives visible_entities IDs and staging, but it does not receive name_by_short_id. The detector cannot reliably resolve character_angles[].character or pov_character without that map. Therefore W2 is not just a local helper insertion; it must add deterministic card-input threading.

Alternative B is to run the detector at each caller and pass only a precomputed ID set into the builder. This is rejected for Phase 1 because missing one call path would silently disable reconciliation in that path.

Override Rule

Provenance

Minimal provenance should be included without expanding schema: use the injected/overridden policy item's reason field, for example:

reason = "screen_presence_reconciliation: visible candidate absent from character_angles, non-POV, camera_direction off-screen reference"

A new top-level card field such as presence_conflict_resolution is useful for future UI, but it changes card hash shape and should wait unless Phase 1 tests explicitly cover verify/recompute stability.

TDD Plan

Implementation Waves

W0 - Read-only Pin

1. Pin current S15 fixture from checkpoint, including shot_director, shot_staging, and failing validator payload.
2. Confirm no local SQLite dependency in the evidence path.
3. Enumerate all build_render_prompt_card call paths and prove each one can receive the same name_by_short_id source.
4. Confirm import direction: render_prompt_card may import from shot_visibility without circular import.
5. Check current scene_detail system/card wording for generic_descriptor_allowed and canonical-name prohibition.
6. List broad regression suites touching shot_visibility, render_prompt_card, visible_entities_validator, and scene_detail.

W1 - Detector Helper

1. Add shared helper in backend/app/modules/pipeline/shot_visibility.py.
2. Refactor common in-frame membership extraction if helpful, but avoid broad cleanup.
3. Use structural absence + non-empty character_angles + non-POV + OFFSCREEN_RE as hard gates.
4. Record name proximity only as confidence/provenance.
5. Do not modify existing blocking detect_offscreen_drift_structured behavior yet.

W2 - RenderPromptCard Consumer And Name Map Threading

1. Add name_by_short_id to build_render_prompt_card() and to the card input helper path.
2. Thread ctx.name_by_short_id through producer, verify, dual-source recompute, and reuse paths via _collect_card_inputs().
3. Add policy reconciliation helper near the subject policy normalization code.
4. Inject/override only the target subject policy items.
5. Keep malformed policy items fail-fast; do not silently swallow invalid structures.
6. Verify that build_asset_requirements sees the reconciled policy_map.
7. Verify that producer and verify recompute use identical name_by_short_id inputs.

W3 - E2E Re-run

1. Resume or force only the minimal affected analysis steps required by step invalidation rules.
2. Confirm S15_Shot5 no longer fails base_id_missing.
3. Confirm no new Source 2 canonical-name violation for C01.
4. Confirm image phase is not started until analysis is clean, unless explicitly requested.

Risk Controls

Exit Criteria

• S15_Shot5 completes without base_id_missing.
• No regression in render prompt card hash recompute tests.
• Producer, verify, user-edited reuse, and dual-source recompute paths all pass the same name map into card building.
• No new required-ref mismatch for downgraded subject.
• No broader scene_detail contract regression in targeted suite.
• One full resume of the affected project reaches the next planned gate cleanly.