전체 파이프라인 — 개발자 상세도

기획서 업로드 시점에 ``planning_doc_analysis_service`` 가 project-level
    checkpoint 를 미리 만들어둠. 본 step 은 episode 분석 cascade 호환을 위해
    유지되지만, project-level 결과가 있으면 그대로 mirror 하고 LLM 재호출은
    하지 않음.

설계 = docs/superpowers/specs/2026-08-08-scene-segmentation-rule-authoring-design.md

    ## 무엇이 달라졌나 (2026-08-08)

    전에도 LLM 이 정규식을 만들었지만 **후보를 하나만 받고 검증이 평균 길이
    하나**였다. 그래서 "개수는 맞는데 경계가 틀린" 규칙이 그대로 통과했다 —
    22개 대본 실측에서 그런 결함을 넷 찾았고, 넷 다 숫자만 봐서는 안 드러났다.

    지금은 후보를 2~3개 받아 기계 계약(C1~C7)으로 재고, 통과한 후보끼리 **경계가
    갈린 자리를 양쪽 다** 되돌려주고 다시 쓰게 한다. 한쪽만 보면 정답을 통째로
    포함하는 넓은 규칙이 조용히 이긴다(재현함).

    ★상한을 다 쓰고도 차이가 남으면 성공으로 두지 않는다. 코드가 이미 아는
    차이를 남긴 채 확정하면 대본 전체가 밀린 채 하류로 내려간다.

입력:
        - text_cleanup 체크포인트 (정리된 텍스트)
        - episode_summary 체크포인트 (에피소드 요약)

    출력:
        - rules: 시각적 규칙 목록
        - era: 시대 배경
        - region: 지역/국가 배경

scene_segmentation 결과(오프셋)를 받아 fulltext를 슬라이스하여
    각 segment에 text 필드를 추가한다.
    이후 downstream 스텝은 seg["text"]만 사용하고 fulltext 로딩 불필요.

입력:
        - scene_save 체크포인트 (segments)
        - text_cleanup 체크포인트 (정리된 텍스트)
        - episode_summary 체크포인트 (에피소드 요약)
        - visual_world_rules 체크포인트 (시각적 규칙)

    출력:
        - scene_summaries: [{scene_index, scene_summary}, ...]

씬 텍스트에서 인물 리스트를 1회 호출로 추출.
    beat_extract, shot_extract에서 이 리스트를 참조하여 인물명을 제한한다.

entity_merge 결과에서 같은 대상의 변형 쌍을 식별하고
    시각적 유사성 여부를 판단하여 RelationFact에 기록.

scene_director의 씬 레벨 VE를 shot 단위로 세분화하고,
    변형 캐릭터의 전환 시점을 확정한다.

Spec D1: building group clustering + chain_bg/prev_shot_ref classification — single LLM call.

흐름:
  1. shot_validator/shot_selection/entity_merge/entity_detail/visual_world_rules 로드
  2. shot_count(loc_id별 출현 횟수) 집계
  3. _build_locations_from_entities — entity_merge.locations + entity_detail.kind/summary
     를 flat list로 만듦 (pre-grouping 없음 — LLM이 cluster 결정)
  4. build_classify_user_prompt → run_background_classify (3회 retry)

체크포인트 data:
  data.building_groups[] = [{group_id, members[], anchor_loc, kind, rationale}]

각 chain_bg group에 대해 LLM 1회 호출 → master plan 산출. 그룹간 ThreadPool 병렬.
prev_shot_ref 그룹은 skip.

흐름:
  1. background_classify + scene_save + shot_validator + shot_selection +
     visual_world_rules 체크포인트 로드
  2. classify의 chain_bg group만 추려 그룹별 LLM 호출 (ThreadPool 병렬)
  3. prev_shot_ref 그룹은 plan=null로 기록 (호출 X)

체크포인트 data:
  data.plans = {group_id: {status, plan | error}}

각 group plan의 floor_plans[]에 대해 LLM 1회씩 t2i prompt 생성.
도면 간에는 depends_on_fp DAG가 있으므로 level 병렬 가능 (대부분 single level).

floor_plan_prompt 결과 + master plan의 depends_on_fp를 따라 PNG 생성.
level 병렬 (compute_dag_levels).

Phase 7 ImageAsset UPSERT (Phase 5 패턴 미러):
  - asset_type='floor_plan'
  - entity_id = primary_loc_id의 EntityCanon.id
  - variant_index = primary_loc_id 단위 0-base counter (sorted fp_id)
  - variant_label = 'v00'/'v01'... (counter 기반)
  - variant_type = fp_id (UPSERT 매치 키, 재실행 idempotent 보장)
  - is_primary = 1 (counter 0일 때만), 0 (그 외)
  - file_path = projects_root 기준 relative
  - prompt_used = t2i_prompt
  - generation_model = 'gpt-image-2'

도면간 depends_on_fp DAG는 거의 single-level이지만 generic helper로 안전 처리.

opt-in (default OFF) producer of a per-fp **simplified floor-plan sidecar PNG** —
a SPARSE CV-readable PARTITION DIAGRAM (thick enclosing walls, an unnumbered
geometry skeleton, only 8-10 essential numbered markers) that the background
renderer reads as an I2I anchor far better than the dense, colored, text-labelled
detailed floor plan.

Winning design (L05 canary, gallery 8815 — user visual gate; supersedes the v0
ref-edit and the first sparse pass):
  1. **gpt-5.5 frequency-aware selection** — from the floor_plan_prompt
     ``numbered_elements`` plus a per-element ``camera_use_count`` (aggregated from
     ``camera_recommendations`` = how many shot cameras frame each element), the
     model picks 8-10 ESSENTIAL numbered markers (a high-frequency element such as
     a repeatedly-framed TV/curtain is protected from being dropped) + an
     UNNUMBERED geometry skeleton (rooms/walls/doors/windows), and writes a SHORT
     ``room_schematic_prompt`` with explicit marker-placement constraints (every
     circle inside the building outline, door/window markers on their wall, one
     circle per number). A long prompt renders badly; few markers render cleanly.
  2. **gpt-image-2** PURE text-to-image — NO reference image (a reference
     leaks/duplicates marker numbers; the v0 ref-edit produced "11" twice).
     ``best_of_n`` draws are rendered; the primary sidecar is the FIRST successful
     draw, and every draw is persisted for the visual gate. (Render model =
     gpt-image-2 per the 2026-06-01 user visual gate: on the same prompt it honours
     "one circle per number" far better than Nano Banana 2, which duplicated
     markers on repeated office furniture; the residual STRUCTURE issues are an
     upstream floor_plan_prompt skeleton problem shared by both models.)

The DETAILED ``floor_plan_render`` PNG is left untouched — it stays the
``shot_projection_card`` / edge-judge substrate, so the W21B-w5 partition SOT is
never disturbed (STEP5-B boundary lock). This step only ADDS a sidecar; the
consumer (``background_render._apply_light_fp_sidecar``) swaps the FP anchor PNG to
the light sidecar when it rendered, and otherwise falls back to the detailed FP
(default behaviour, byte-identical when OFF).

Pipeline order **21.56** — after ``floor_plan_prompt`` (21.5x, source of
``numbered_elements`` + ``camera_recommendations``) and ``floor_plan_render``, and
before ``floor_plan_overlay_payload`` (21.57).

Per fp_id (status ``ok`` in the floor_plan_prompt checkpoint):
  1. Aggregate ``camera_use_count`` from ``camera_recommendations``.
  2. Build the freq-aware selection bundle → one gpt-5.5 call → validate the
     STRUCTURAL skeleton (rooms drawn, no state overlay essential, prompt present).
  3. Render ``best_of_n`` NB2 text-to-image draws; persist them; primary = first ok.
  4. Persist provenance (essential/skeleton numbers, diagnostics, draws).
  5. A selection/render miss / missing data / unsafe id falls back to the detailed
     FP for that fp ONLY — never a step failure (optional sidecar).

Validation is STRUCTURAL + render-status only (Codex lock): geometry fidelity (no
duplicate / floating markers) and best-of-N quality are a VISUAL gate + optional
later OCR/VLM diagnostic, NOT a deterministic hard gate (avoids an expensive
false-negative-prone gate that would fall back to the cluttered detailed FP).

Gates (all must be true, else ``not_applicable`` with byte-stable empty data):
  - ``settings.background_mode`` ∈ {"on", "floor_plan_anchored"}.
  - ``settings.floor_plan_light_sidecar_enabled`` = True.
  - ``settings.floor_plan_prompt_version`` ∈ {"6", "7"}.

``floor_plan_prompt`` (v6) + ``background_master_plan`` checkpoint 만 consume.
LLM / image / VLM API call 0, DB / ImageAsset write 0.

Gates:
  - ``settings.background_mode`` ∉ {"on","floor_plan_anchored"} → not_applicable.
  - ``settings.floor_plan_prompt_version`` != "6" → not_applicable. default v5
    path 는 use/ignore arrays 가 v5 schema 에 없어 의미 없음. v5 callers
    그대로 회귀 0.

체크포인트 data shape:
  ``data.overlays`` = ``{bg_id: per-bg payload}``, build_overlay_payload 출력
  그대로. 실패 시 ``data.error`` 가 set 되고 ``failed_count=1``, ``data.overlays``
  는 빈 dict.

Consumes:
  - ``floor_plan_prompt`` (v6) — numbered_elements + base_layer_decision.
  - ``floor_plan_render`` — png_path per fp (best-effort).
  - ``background_master_plan`` — backgrounds[] DAG per fp.
  - ``floor_plan_overlay_payload`` — per-bg overlay payload.

Gates (opt-in, default OFF):
  - ``settings.background_mode`` ∉ {"on","floor_plan_anchored"} → not_applicable.
  - ``settings.base_location_dossier_enabled`` != True → not_applicable.
  - ``settings.floor_plan_prompt_version`` != "6" → not_applicable.
    v5 path does not carry base_layer_decision, so a dossier built off
    v5 markers would lose the partition contract.

Checkpoint data shape:
  ``data.dossiers`` = ``{fp_id: dossier_dict}`` (build_dossiers output).
  Failure path emits ``data.error`` (truncated str) and an empty
  ``data.dossiers``.

LLM / image / VLM API call 0, DB / ImageAsset write 0.

opt-in (default OFF) producer for the geometry-readback bridge between
W20A (base_location_dossier) and W20B (shot-aware LLM planner).

Per fp_id present in the dossier checkpoint, the step:
  - Builds a synthetic_fixture readback (W20A2 default — no real VLM).
  - Computes geometry candidates (camera cells, look-at cells,
    direction vectors, view cone records, visible units/openings
    candidates, wall/door diagnostics).
  - Renders a review HTML overlay and writes it under the checkpoint
    directory.

Gates (all must be true):
  - ``settings.background_mode`` ∈ {"on", "floor_plan_anchored"}.
  - ``settings.floor_plan_geometry_readback_enabled`` = True.
  - ``settings.base_location_dossier_enabled`` = True.
  - ``settings.floor_plan_prompt_version`` = "6".

Anything else → ``not_applicable`` with byte-stable empty payload.

LLM / image / VLM API call 0, DB / ImageAsset write 0. The HTML file is
the only sidecar artifact; manifest.json carries summaries + the file's
relative path under the checkpoint dir.

재개 재사용 (2026-08-19 사용자 지시) — 실제 VLM 제공자를 켜면 이 단계는
도면 하나마다 모델을 부르고 **답이 매번 조금씩 다르다**. 그런데 도면 몇
개가 늘 실패해서 스텝이 `partial` 로 남고, `partial` 은 재개마다 다시
불린다. 다시 불릴 때 성공한 도면까지 전부 다시 읽으니 기하 값이 바뀌고,
그 도면을 쓰는 장면이 「재료가 낡았다」로 판정돼 그림이 다시 만들어졌다
(08-19 저녁 한 바퀴에 66장). 그래서 **직전 체크포인트에서 성공한 도면은
그대로 쓰고 실패한 것만 다시 읽는다.** 재사용 조건은 셋 다 만족일 때만
이다 — ①이 스텝의 config_hash 가 같다 ②그 도면의 입력(dossier)이 1비트도
안 바뀌었다 ③산출 HTML 파일이 실재한다. `mode="force"` 는 재사용하지
않는다(force 의 뜻이 "처음부터 다시"이므로).

opt-in (default OFF) producer of the marker-SEMANTIC fidelity gate.

Per fp_id present in the base-location dossier checkpoint, the step:
  - Computes a marker-SEMANTIC readback — does the image content drawn
    at each base marker match the expected object class / label? With
    the real-provider selector OFF (default) it uses the synthetic
    fixture (deterministic placeholder verdicts, NO real VLM call).
  - Computes a fail-closed gate (pass / needs_fix / needs_review /
    synthetic_unverified).
  - Records per-fp readback + gate in the manifest.

Gates (all must be true):
  - ``settings.background_mode`` ∈ {"on", "floor_plan_anchored"}.
  - ``settings.floor_plan_semantic_readback_enabled`` = True.
  - ``settings.base_location_dossier_enabled`` = True.
  - ``settings.floor_plan_prompt_version`` ∈ {"6", "7"} (v7 is the
    fidelity pack; v7 is schema-compatible with v6 — Rule 11 wording
    only — so both are accepted).

Anything else → ``not_applicable`` with a byte-stable empty payload.

This is a SEPARATE gate from the W20A2 geometry readback (marker
number/cell/base-kind). LLM / image / VLM API call is 0 unless the
real-provider selector is explicitly flipped (or a mock provider is
injected in tests). DB / ImageAsset write 0.

opt-in (default OFF) producer of the per-shot projection card — the
common shot-observation SOT that BG (``background_prompt`` vNext, C4) and
the final shot t2i (``scene_detail`` vNext, C5) both consume so they
follow the same contract (design brief §3; wiring brief §3).

Per ``(bg_id, shot_id)`` target (one card per shot in the background's
``applies_to_shots``; anchor / plate grouping is deferred to the plan
vNext, C3) the step:
  - Assembles the marker inventory + union registry from the overlay
    payload (base ∪ transient ∪ ignored), and the source_hashes
    provenance from the upstream checkpoints.
  - Computes a projection-card VLM output. With the real-provider
    selector OFF (default) it uses the synthetic fixture — a
    non-authoritative placeholder that NEVER auto-passes the gate, NO
    real VLM call.
  - Builds the card envelope and runs the v0 deterministic gate
    (pass / needs_review / blocked).
  - Records per-card envelope + validation in the manifest.

Gates (all must be true):
  - ``settings.background_mode`` ∈ {"on", "floor_plan_anchored"}.
  - ``settings.shot_projection_card_enabled`` = True.
  - ``settings.base_location_dossier_enabled`` = True.

Anything else → ``not_applicable`` with a byte-stable empty payload.

The semantic readback (W21B-wave-4) is an OPTIONAL gate, not a hard dep:
when its checkpoint is present the per-fp ``gate_state`` is carried into
the card; otherwise the card records ``semantic_gate_state=not_available``
and the gate does not treat semantic as a hard precondition (design brief
§10 decision 1). LLM / image / VLM API call is 0 unless the real-provider
selector is explicitly flipped (or a mock provider is injected in tests).
DB / ImageAsset write 0.

opt-in (default OFF) producer of the per-fp ``space_partition_plan`` — the
LLM SOT for which background plates share a physical space (same zone), which
anchors each plate, the render action per bg, and the bounded reference tree.
This REPLACES the dwelling-level ``same_physical_space_view`` reference source
that incorrectly chained cross-zone plates (an enclosed bathroom inheriting an
open living-room's plate within a multi-zone dwelling).

Pipeline order **21.594** — after ``shot_projection_card`` (21.593, whose
visible_items seed the judge) and before ``shot_aware_bg_render_plan`` (21.595,
the consumer that mirrors render_action / ref_tree_parents).

Per fp_id the step:
  1. Reads the ``base_location_dossier`` checkpoint (the candidate-edge inputs:
     ``base_marker_inventory`` structural units + ``per_bg_render_facts_by_bg_id``
     camera-target floors). Geometry presence is a hard precondition (consistency
     with the substrate the FP geometry validated).
  2. Builds the deterministic candidate edges (``build_candidate_edges`` — IDF
     ubiquity discount + hub isolation; a diagnostic floor, NEVER the final SOT).
  3. Adjudicates each borderline candidate with the pass-2 edge judge — a single
     text LLM call over the two bgs' projection-card ``visible_items`` (no VLM
     re-call). With the real-provider selector OFF (default) the provider is None
     and every edge is recorded ``skipped`` (provider_disabled): no strong edge
     forms, so each bg keeps its own plate. R3 precondition: an edge is judged
     only when BOTH bgs have a real, passed, non-synthetic card with visible
     items; otherwise it is ``skipped`` (never a same-space strong parent).
  4. Assembles the ``space_partition_plan`` (``build_space_partition_plan`` —
     anchor-centered constrained clustering, transitive closure forbidden, hub
     never bridges, R2 strong-parent gate at conf >= 0.75 with non-empty
     distinctive features).

Cost caps (Codex lock ⑤): a per-fp edge cap and a global LLM-call cap bound the
judge spend. When a cap is hit the remaining edges are recorded ``skipped`` with
the cap reason — never silently dropped, never auto-merged.

Gates (all must be true, else ``not_applicable`` with a byte-stable empty data):
  - ``settings.background_mode`` ∈ {"on", "floor_plan_anchored"}.
  - ``settings.bg_space_partition_enabled`` = True.
  - ``settings.base_location_dossier_enabled`` = True.

LLM call count is 0 unless the real-provider selector is flipped (or a mock
provider is injected in tests). Image / DB / ImageAsset write 0.

opt-in (default OFF) producer of a per-dwelling **zone map** that bypasses the
edge-judge (``bg_space_partition``), which cannot group same-dwelling bgs framed
from different camera angles. For each interior dwelling (bgs grouped by their
floor-plan fp_id) the step:

  1. assembles a per-bg structural description (priority: shot_projection_card
     plate prose → freshness-verified background_prompt t2i → master-plan
     catalog labels; dossier structural facts attached as enrichment when
     present);
  2. (real provider) distils the base-set rooms (gpt-5.5), writes a clean B&W
     2D floor-plan prompt (gpt-5.5), renders it (gpt-image-2 text-to-image — a
     NEW clean plan, the distorted ``floor_plan_render`` PNG is NOT reused),
     then a gpt-5.5 VISION call maps each bg to its plan zone + grid focus;
  3. deterministically joins that into the zone-map contract (zones + bg/shot
     zone assignments), draws a SEPARATE annotated FP (shot-number overlay,
     ``must_not_be_used_for_render``) for mapping verification only, and
     records a diagnostic comparison against the edge-judge grouping.

The CLEAN render ref and the ANNOTATED (numbered) ref are kept strictly apart
so no downstream i2i anchor can grab the numbered image (number-leak guard).
This step does NOT yet feed any renderer — it only produces + validates the
contract (Phase 1); the background_render zone-1-plate wiring is Phase 2.

Gates (all true, else ``not_applicable`` with byte-stable empty data):
  - ``settings.background_mode`` ∈ {"on", "floor_plan_anchored"}.
  - ``settings.dwelling_zone_map_enabled`` = True.
  - ``settings.floor_plan_prompt_version`` ∈ {"6", "7"}.

When enabled but ``dwelling_zone_map_real_provider_enabled`` is False, every
dwelling gets the non-authoritative synthetic fixture (no LLM/VLM/image call) —
the plumbing path. A per-dwelling provider failure falls back to synthetic for
that dwelling only (never a step failure).

opt-in (default OFF) producer for the dwelling-scoped reference graph
+ per-bg camera/reference decisions. Consumes ``base_location_dossier``
(W20A), ``floor_plan_geometry_readback`` (W20A2),
``floor_plan_overlay_payload`` (W19B-1), ``background_master_plan``,
and ``shot_staging``.

Gates (all must be true → run; any false → not_applicable):
  - ``settings.background_mode`` ∈ {"on", "floor_plan_anchored"}
  - ``settings.shot_aware_bg_render_plan_enabled`` = True
  - ``settings.base_location_dossier_enabled`` = True
  - ``settings.floor_plan_geometry_readback_enabled`` = True
  - ``settings.floor_plan_prompt_version`` = "6"

The step does NOT call any external LLM by default.
``build_render_plan_for_fp(llm_provider=None)`` returns a structurally-
empty plan with diagnostics, so an enable-only flag flip in production
still costs 0 external API calls.

A real LLM smoke is gated on a future wave behind explicit user/Codex
approval. To run a mock/dry smoke, inject an llm_provider via
``set_llm_provider_for_testing``.

No image / VLM / DB / ImageAsset write. Output is checkpoint-only.

각 master plan의 backgrounds[]에 대해 LLM 1회씩 t2i prompt 생성.
depends_on_bg DAG로 level 병렬화. (이 step은 prompt만 — PNG는 T14 background_render).

Phase 8 v2: ``floor_plan_prompt`` 체크포인트(``data.floor_plans[fp_id]``)에서
``numbered_elements`` + ``camera_recommendations`` 를 로드해 bg_id 기준 flat
매핑을 만들고, ``build_bg_user_prompt`` 에 inject한다. 매핑 키는 master_plan
의 ``backgrounds[].depends_on_fp[0]`` 으로 fp_id 를 결정 (master_plan
invariant 4: 같은 sub_location 은 같은 fp).

2026-07-19 사용자 확정: 샷별 개별 판정 대신 에피소드 전체를 조망하는 LLM
계획으로 '배경 참조 vs 앞쪽 샷(prev) 참조'를 구분 지휘. 스틸 소비 시 이
계획이 shot_ref_classify prev 판정의 상위 권위(부재=기존 판정 fail-safe).
flag ``background_share_plan_enabled`` default OFF — OFF=no-op(불변).

force 모드: 기존 이미지 삭제 안 함. 새 이미지 추가 생성 (is_primary 이동).
resume 모드: 미완성분만 이어서 생성.

force 모드: 기존 이미지 삭제 안 함. 새 이미지 추가 생성 (is_primary 이동).
resume 모드: 미완성분만 이어서 생성.

force 모드: 기존 이미지 삭제 안 함. 새 이미지 추가 생성 (is_primary 이동).
resume 모드: 미완성분만 이어서 생성.

각 master plan background를 gpt-image-2로 PNG 생성. ``depends_on_bg`` DAG →
``compute_dag_levels`` 로 level 분할 후 level 내부는 ThreadPool 병렬.

출력 shape는 Phase 5 ``chain_bg_render`` 와 호환:
``data.groups[bg_id].{status, location_id, png_path, t2i_prompt,
shot_guides, shot_ids, parent_id, ref_used, ...}``.
이렇게 해야 Phase 6 ``scene_context_loader._load_chain_bg_guide_by_shot``
가 변경 없이 동작.

Phase 7 ImageAsset UPSERT (Phase 5 chain_bg 패턴 미러):
  - asset_type='chain_bg'
  - entity_id = loc_id의 EntityCanon.id
  - variant_index = loc_id 단위 1+ counter (sorted bg_id, gen_order). v00은
    floor_plan(primary)에 예약.
  - variant_label = state_label
  - variant_type = bg_id (UPSERT 매치 키, 재실행 idempotent 보장)
  - is_primary = 0 (chain_bg는 항상 0; v00 floor_plan만 1)
  - t2i_guide = shot_guides[]를 newline join (Phase 6 scene_detail consumer 가
    이를 prepend하여 chain_bg PNG 가구 위치 가이드를 scene t2i에 주입)
  - file_path = projects_root 기준 relative

force 모드: 기존 이미지 삭제 안 함. 새 이미지 추가 생성 (is_primary 이동).
resume 모드: 미완성분만 이어서 생성.