Scene composition is the gate, not word counts

The skill exists so the LLM writes/rewrites each scene one at a time
with full attention on making it a complete scene composition — not so
it can hit a word target.

Prompts: the word-budget craft bullets are replaced by an 8-element
composition checklist (subject anchor, style anchor, continuity anchor,
blocking, camera, performance, physical texture, exit state) in both the
scene-writer PROMPT B (new SCENE COMPOSITION section) and the single-pass
prompt. Chase the elements, never a number; padding is as much a failure
as a thin one-liner.

Validator: hard word bands (<10s: 150-200, >=10s: 200-300) removed from
plan and fragment checks. Replaced by a thin-scene floor (100/120 words)
that only trips lazy output, plus a new continuity-anchor check — chained
fragments must open inside the previous end_state. No target band, no
upper limit; output lines say so.

SKILL.md/README: goal, Step 2, craft rules, table rows, and example
outputs updated to match. Suite, --check, chained fragment checks all
green.
This commit is contained in:
Z User 2026-10-29 19:13:27 +00:00
parent 83cc5145bf
commit f5575fa678
5 changed files with 128 additions and 66 deletions

View File

@ -11,11 +11,14 @@ H3 context loop into one continuous multi-clip video, so pasting one `plan.json`
queuing once is all the rendering takes. queuing once is all the rendering takes.
Instead of asking the LLM to emit that whole JSON in one turn, the gate is agent-shaped: Instead of asking the LLM to emit that whole JSON in one turn, the gate is agent-shaped:
one outline turn, then **the LLM writes each scene one at a time** — a single turn fully one outline turn, then **the LLM writes each scene one at a time** — a single turn that
focused on that scene's action, camera, audio, and continuity — and the scripts **put it exists purely to compose that scene from every element a good scene needs (subject,
all together at the end** into the same plan JSON the single-pass prompt would have style, continuity, blocking, camera, performance, texture, sound, exit state) — and the
produced, validated before it ever reaches the node. Long stories stop drifting, and any scripts **put it all together at the end** into the same plan JSON the single-pass
single scene can be regenerated without touching the rest. prompt would have produced, validated before it ever reaches the node. The point is
compositional attention, not word counts: the validator checks structure and trips only
a thin-scene floor, so any scene can be rewritten until its elements are right, then
re-merged without touching the rest.
### Files ### Files
@ -26,7 +29,7 @@ single scene can be regenerated without touching the rest.
| `h3_plan_assembler_system_prompt.md` | Stage 3 LLM merge prompt — only when you cannot run scripts | | `h3_plan_assembler_system_prompt.md` | Stage 3 LLM merge prompt — only when you cannot run scripts |
| `h3_plan_json_system_prompt.md` | Single-pass variant (whole plan in one turn) — fastest for 2–4 scene stories | | `h3_plan_json_system_prompt.md` | Single-pass variant (whole plan in one turn) — fastest for 2–4 scene stories |
| `build_plan.py` | Deterministic Stage 3 merger — puts all the scenes together at the end: strips `_handoff`, injects `"prompt_prefix": [""]` + defaults, validates everything before writing `plan.json` | | `build_plan.py` | Deterministic Stage 3 merger — puts all the scenes together at the end: strips `_handoff`, injects `"prompt_prefix": [""]` + defaults, validates everything before writing `plan.json` |
| `verify_plan_rules.py` | Node-replica validator (final plans *and* per-turn fragments) with an embedded test suite | | `verify_plan_rules.py` | Node-replica validator (final plans *and* per-turn fragments): structure, handoff truth, continuity, thin-scene floor — no word band — with an embedded test suite |
| `count_prompt_tokens.py` | o200k token counter for the prompt fences (needs `pip install tiktoken`) | | `count_prompt_tokens.py` | o200k token counter for the prompt fences (needs `pip install tiktoken`) |
| `h3_agent_workflow_examples/` | Worked 3-scene greenhouse-courier run: `outline.json` → `scene_01..03.json` → `plan.json` | | `h3_agent_workflow_examples/` | Worked 3-scene greenhouse-courier run: `outline.json` → `scene_01..03.json` → `plan.json` |
@ -51,7 +54,7 @@ PREVIOUS HANDOFF: <paste the previous scene's "_handoff" object — or: This is
Save each reply as `scene_NN.json` (zero-padded). Each fragment carries the native H3 Save each reply as `scene_NN.json` (zero-padded). Each fragment carries the native H3
three-line prompt (`integrated_multimodal_description: [Shot 1] …` / `overall_soundscape: …` three-line prompt (`integrated_multimodal_description: [Shot 1] …` / `overall_soundscape: …`
/ `non_diegetic_music: …`), the duration-tiered word budget, and a truthful `_handoff` / `non_diegetic_music: …`), the full scene composition, and a truthful `_handoff`
object for the next turn. Optional gate after each turn: object for the next turn. Optional gate after each turn:
```sh ```sh
@ -123,8 +126,9 @@ durations, and dialogue so later scenes cannot drift:
} }
``` ```
**4. The agent writes each scene one at a time** — one file per turn, fully focused on **4. The agent composes each scene one at a time** — one file per turn, each turn
that scene, validating it before moving to the next: given over to making that one scene a complete composition, validating it before
moving to the next:
```sh ```sh
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_01.json --index 1 --total 3 .venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_01.json --index 1 --total 3
@ -133,8 +137,8 @@ that scene, validating it before moving to the next:
``` ```
Each fragment carries the three-line H3 prompt and a truthful `_handoff`. Scene 3 Each fragment carries the three-line H3 prompt and a truthful `_handoff`. Scene 3
(description elided — the real file carries ~237 words of action, camera, wardrobe, and (description elided — the real file carries the full blocking, camera work, wardrobe
lighting detail): behavior, and lighting detail):
```json ```json
{ {
@ -167,6 +171,8 @@ Merged plan:
shot 2 id='greenhouse_aisle' raw=362 delivered=340 steps=20 shot 2 id='greenhouse_aisle' raw=362 delivered=340 steps=20
shot 3 id='greenhouse_delivery' raw=362 delivered=340 steps=20 shot 3 id='greenhouse_delivery' raw=362 delivered=340 steps=20
total delivered: 1042 frames = 43.42s total delivered: 1042 frames = 43.42s
H3 section structure: all shots have the 3 sections in canonical order
description lengths: ['221w @ 15s', '219w @ 15s', '237w @ 15s'] | composition elements are the gate - no word band
wrote plan.json - paste its full contents into plan_json_input wrote plan.json - paste its full contents into plan_json_input
``` ```
@ -197,7 +203,7 @@ Smoke test with the shipped examples:
```sh ```sh
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check h3-plan-gate/h3_agent_workflow_examples/plan.json .venv\Scripts\python.exe h3-plan-gate/build_plan.py --check h3-plan-gate/h3_agent_workflow_examples/plan.json
# expect: PLAN OK — 1042 delivered frames = 43.42s # expect: PLAN OK with "total delivered: 1042 frames = 43.42s"
``` ```
### Wiring the result ### Wiring the result

View File

@ -10,8 +10,9 @@ description: Turn a story idea into a validated plan_json_input JSON for the Min
# H3 Plan Gate — agent procedure # H3 Plan Gate — agent procedure
Goal: produce `plan.json`, the JSON pasted into the Production Plan node's `plan_json_input`, Goal: produce `plan.json`, the JSON pasted into the Production Plan node's `plan_json_input`,
by writing an outline and then one scene file at a time — each turn fully focused on that by writing an outline and then one scene file at a time — each turn exists so that ONE
one scene — validating every file with the bundled scripts, and putting all the scenes scene can be composed from every element of a good scene composition, never to fill a
word count — validating every file with the bundled scripts, and putting all the scenes
together at the end with `build_plan.py`. Never deliver a plan that did not pass `--check`. together at the end with `build_plan.py`. Never deliver a plan that did not pass `--check`.
## Paths and Python (read first — these exact forms prevent most errors) ## Paths and Python (read first — these exact forms prevent most errors)
@ -34,7 +35,7 @@ together at the end with `build_plan.py`. Never deliver a plan that did not pass
``` ```
Expect the suite to pass and the second command to print Expect the suite to pass and the second command to print
`PLAN OK` with `1042 delivered frames = 43.42s`. `PLAN OK` with `total delivered: 1042 frames = 43.42s`.
## Step 1 — Outline ## Step 1 — Outline
@ -63,12 +64,16 @@ never renamed later. Durations whole seconds 2–15, prefer 5–15. Copy the use
speech EXACTLY into the right scene's `dialogue` array; if the story has no quoted speech, speech EXACTLY into the right scene's `dialogue` array; if the story has no quoted speech,
every `dialogue` array stays `[]`. Only the last scene's beat may come to rest. every `dialogue` array stays `[]`. Only the last scene's beat may come to rest.
## Step 2 — Scenes, one file at a time ## Step 2 — Compose the scenes one at a time
Before writing scene 1, read the PROMPT B section of the same file. Then, in story order: Before writing scene 1, read the PROMPT B section of the same file — its SCENE
write ONE scene file, validate it, fix it until it passes, and only then move to the next COMPOSITION checklist (subject anchor, style anchor, continuity anchor, blocking,
scene. Since you wrote the previous file yourself, open it and reuse its `_handoff` as the camera, performance, physical texture, exit state) is what each turn is for. Then, in
opening state of the next scene. story order: compose ONE scene file, validate it, fix it until it passes, and only then
move to the next scene. Since you wrote the previous file yourself, open it and reuse
its `_handoff` as the opening state of the next scene. Rewrite a scene as many times
as it takes for every element to be present and concrete — the validator has no word
band, only a thin-scene floor, so never pad and never summarize.
```sh ```sh
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_01.json --index 1 --total 5 .venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_01.json --index 1 --total 5
@ -128,10 +133,13 @@ and sampler latent or the video can come out square.
`integrated_multimodal_description:` / `overall_soundscape:` / `non_diegetic_music:`. `integrated_multimodal_description:` / `overall_soundscape:` / `non_diegetic_music:`.
- The description line is self-sufficient: re-state `<Subject 1>`, the full wardrobe, and - The description line is self-sufficient: re-state `<Subject 1>`, the full wardrobe, and
the visual style in EVERY scene — nothing is shared between scenes or from a prefix. the visual style in EVERY scene — nothing is shared between scenes or from a prefix.
- Word budget for the description line: scenes under 10 s aim for ~175 words (never below - Scene composition, not word count: the description line must carry every element —
150); scenes of 10 s or longer carry 200–300. Spend them on blocking, camera path and subject anchor (`<Subject 1>` and wardrobe restated), style anchor, continuity anchor
speed, expression beats, body mechanics, wardrobe behavior, weather on skin and fabric, (opens inside the previous end_state), blocking, one camera idea, performance beats,
lighting, and the exact mid-action end point. physical texture (wardrobe behavior, weather on skin and fabric, lighting), and a
concrete mid-action exit state. Never pad to a length and never hand in a thin
one-liner — a scene with every element is long enough on its own. The validator only
trips a thin-scene floor (about 100 words); there is no target band.
- Open by continuing the previous `_handoff` end_state ("Continue the same stride", - Open by continuing the previous `_handoff` end_state ("Continue the same stride",
"without resetting the motion", "keep the incoming camera direction"); scene 1 sets the "without resetting the motion", "keep the incoming camera direction"); scene 1 sets the
opening. End mid-action except the final scene. No camera cuts inside a scene. opening. End mid-action except the final scene. No camera cuts inside a scene.

View File

@ -121,14 +121,23 @@ Shots are flat. A shot never contains a nested object.
2. Describe this scene's new action concretely: blocking, camera move, emotion, physics. 2. Describe this scene's new action concretely: blocking, camera move, emotion, physics.
3. End mid-action or on a movement still in progress so the next scene can continue it. 3. End mid-action or on a movement still in progress so the next scene can continue it.
Only the final scene may resolve and come to rest. Only the final scene may resolve and come to rest.
- The integrated_multimodal_description line must fill the scene's duration. Keep it - Compose every scene from the same eight elements, and never chase a word count —
within 150-300 words, tiered by scene length: scenes under 10 seconds aim for about chase the elements. A description that genuinely carries them comes out long enough
175 words; scenes of 10 seconds or longer carry 200 to 300 words. Spend the words on on its own; padding to a number is as much a failure as a thin one-liner:
concrete detail: full blocking (who moves where, which hand does what), camera path 1. SUBJECT ANCHOR — <Subject 1> restated: identity, wardrobe head to toe, hair, build.
and speed, facial-expression beats, body mechanics, wardrobe behavior, weather and 2. STYLE ANCHOR — the one consistent look: medium, lighting quality, palette.
surfaces on skin and fabric, lighting on faces, and the exact mid-action point where 3. CONTINUITY ANCHOR — open inside the previous scene's end state (scene 1 sets the
the scene ends. Thin one-line scenes are a failure; vague summary sentences are opening) and name what carries over: the stride, the camera direction, the light,
filler. the weather.
4. BLOCKING — the new action as concrete staging: who moves where, which hand does
what, at what pace, handling which object.
5. CAMERA — one clear camera idea per scene: shot size, height, path, speed, and what
it holds in frame. No cuts inside a scene.
6. PERFORMANCE — facial-expression beats and body mechanics timed to the action.
7. PHYSICAL TEXTURE — wardrobe behavior, weather and surfaces on skin and fabric,
weight, momentum, lighting on faces.
8. EXIT STATE — the exact mid-action point where the scene ends (only the final scene
may come to rest), concrete enough that the next scene opens from it.
- Never compress a change into a stated outcome. A line like "<Subject 1> is now an 18 - Never compress a change into a stated outcome. A line like "<Subject 1> is now an 18
year old man" is FORBIDDEN. Show the change as a continuous on-screen progression in year old man" is FORBIDDEN. Show the change as a continuous on-screen progression in
the same take — for an age change: wrinkles smoothing, jaw and cheekbones softening, the same take — for an age change: wrinkles smoothing, jaw and cheekbones softening,
@ -278,10 +287,11 @@ Correct reply:
7. Scene 1 sets an opening; every later scene continues the previous final action; every 7. Scene 1 sets an opening; every later scene continues the previous final action; every
scene except the last ends mid-action. Every description line is self-sufficient: it scene except the last ends mid-action. Every description line is self-sufficient: it
re-states who <Subject 1> is, wardrobe, and visual style, because the prefix is empty. re-states who <Subject 1> is, wardrobe, and visual style, because the prefix is empty.
8. Every integrated_multimodal_description line stays within its duration's word 8. Every description line carries every element of a scene composition — subject,
budget — under 10 s: about 175 words (never below 150); 10 s or longer: 200-300 — style, continuity, blocking, camera, performance, texture, exit state — and no
and no change anywhere is stated as a bare outcome like "is now"; every change anywhere is stated as a bare outcome like "is now"; every transformation is
transformation is shown as a continuous on-screen progression. shown as a continuous on-screen progression. Length is a side effect of the
elements, never a target.
9. Every shot's prompt array has exactly three lines in this order: 9. Every shot's prompt array has exactly three lines in this order:
integrated_multimodal_description: [Shot 1] ... / overall_soundscape: ... / integrated_multimodal_description: [Shot 1] ... / overall_soundscape: ... /
non_diegetic_music: ... non_diegetic_music: ...

View File

@ -6,7 +6,7 @@ same contract as the single-pass prompt, split into an agent workflow.
**Verified against:** commit `43afeff` — `chain_nodes.py` (`_normalize_plan`, `_h3_frame_length`, **Verified against:** commit `43afeff` — `chain_nodes.py` (`_normalize_plan`, `_h3_frame_length`,
`_safe_name`, `MAX_SHOTS`), `web/h3_prompt_schema_core.mjs` (`H3_BASE_SECTIONS`), and the same `_safe_name`, `MAX_SHOTS`), `web/h3_prompt_schema_core.mjs` (`H3_BASE_SECTIONS`), and the same
dialogue/word-budget rules as `h3_plan_json_system_prompt.md`. dialogue and scene-composition rules as `h3_plan_json_system_prompt.md`.
--- ---
@ -29,10 +29,12 @@ PREVIOUS HANDOFF: <paste the previous scene's "_handoff" object — or: This is
``` ```
**Why this split works better for long stories:** each turn only carries one scene's **Why this split works better for long stories:** each turn only carries one scene's
crafting load; the outline freezes ids, durations, dialogue distribution, and cast so compositional load — every element of one good scene gets the model's full attention
sequential turns cannot drift; and the `_handoff` chain gives every scene a truthful instead of competing with a word count across ten scenes; the outline freezes ids,
starting state. You can also hand-edit `outline.json` between Stage 1 and Stage 2 — durations, dialogue distribution, and cast so sequential turns cannot drift; and the
the scene agents will follow the edited skeleton. `_handoff` chain gives every scene a truthful starting state. You can also hand-edit
`outline.json` between Stage 1 and Stage 2 — the scene agents will follow the edited
skeleton.
**Assembly (Stage 3):** the reliable path is the deterministic merger — **Assembly (Stage 3):** the reliable path is the deterministic merger —
`python scripts/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json`. `python scripts/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json`.
@ -211,15 +213,34 @@ identity and style from the story alone; without a handoff you are scene 1.
- End your description mid-action, on a movement still in progress, so the next scene - End your description mid-action, on a movement still in progress, so the next scene
can continue it. Only the final outline scene may resolve and come to rest. can continue it. Only the final outline scene may resolve and come to rest.
# SCENE COMPOSITION (why you write one scene per turn)
Your whole turn exists so this ONE scene can be composed with full attention. Build the
integrated_multimodal_description line from every element below; a scene missing an
element is a failed scene. Do not chase a word count — chase the elements. A
description that genuinely carries them comes out long enough on its own; padding to
a number is as much a failure as a thin one-liner.
1. SUBJECT ANCHOR — <Subject 1> restated: identity, wardrobe head to toe, hair,
build. Nothing is shared between scenes or from a prefix.
2. STYLE ANCHOR — the one consistent look: medium, lighting quality, palette.
3. CONTINUITY ANCHOR — open inside the previous end_state (scene 1 instead
establishes place, light, and the first action). Name what carries over: the
stride, the camera direction, the light, the weather.
4. BLOCKING — the new action as concrete staging: who moves where, which hand
does what, at what pace, handling which object.
5. CAMERA — one clear camera idea: shot size, height, path, speed, and what it
holds in frame. No cuts inside the scene.
6. PERFORMANCE — facial-expression beats and body mechanics timed to the action.
7. PHYSICAL TEXTURE — wardrobe behavior, weather and surfaces on skin and fabric,
weight, momentum, lighting on faces.
8. EXIT STATE — the exact mid-action point where the scene ends (only the final
outline scene may come to rest), concrete enough that the next scene opens
from it.
The sound picture is its own element and lives in the overall_soundscape line (AUDIO
below); dialogue lives inside the description line (DIALOGUE below).
# PROMPT CRAFT # PROMPT CRAFT
- The integrated_multimodal_description line must fill the scene's duration. Keep it
within 150-300 words, tiered by scene length: scenes under 10 seconds aim for about
175 words; scenes of 10 seconds or longer carry 200 to 300 words. Spend the words on
concrete detail: full blocking (who moves where, which hand does what), camera path
and speed, facial-expression beats, body mechanics, wardrobe behavior, weather and
surfaces on skin and fabric, lighting on faces, and the exact mid-action point where
the scene ends. Thin one-line scenes are a failure; vague summary sentences are
filler.
- Never compress a change into a stated outcome. A line like "<Subject 1> is now an 18 - Never compress a change into a stated outcome. A line like "<Subject 1> is now an 18
year old man" is FORBIDDEN. Show the change as a continuous on-screen progression in year old man" is FORBIDDEN. Show the change as a continuous on-screen progression in
the same take — for an age change: wrinkles smoothing, jaw and cheekbones softening, the same take — for an age change: wrinkles smoothing, jaw and cheekbones softening,
@ -372,10 +393,11 @@ Correct reply:
and the visual style. and the visual style.
5. The description opens by continuing the PREVIOUS HANDOFF's end_state (scene 1 sets 5. The description opens by continuing the PREVIOUS HANDOFF's end_state (scene 1 sets
the opening instead) and ends mid-action — except the final outline scene. the opening instead) and ends mid-action — except the final outline scene.
6. The description line stays within its duration's word budget — under 10 s: about 175 6. The description line carries every element of a scene composition — subject anchor,
words (never below 150); 10 s or longer: 200-300 — and no change anywhere is stated style anchor, continuity anchor, blocking, camera, performance, physical texture,
as a bare outcome like "is now"; every transformation is shown as a continuous exit state — and no change anywhere is stated as a bare outcome like "is now";
on-screen progression. every transformation is shown as a continuous on-screen progression. Length is a
side effect of the elements, never a target.
7. overall_soundscape continues the previous soundscape ("the same ... continues") and 7. overall_soundscape continues the previous soundscape ("the same ... continues") and
matches the picture; non_diegetic_music: is N/A unless the user asked for a score. matches the picture; non_diegetic_music: is N/A unless the user asked for a score.
8. There is no <d> span anywhere unless this scene's outline row or the story gave 8. There is no <d> span anywhere unless this scene's outline row or the story gave
@ -417,5 +439,5 @@ Correct reply:
workflow for long stories, per-scene iteration, or regenerating single scenes. workflow for long stories, per-scene iteration, or regenerating single scenes.
- **Validation without assembly:** `python scripts/verify_plan_rules.py fragment - **Validation without assembly:** `python scripts/verify_plan_rules.py fragment
scene_02.json --index 2 --prev scene_01.json` checks one fragment against all rules scene_02.json --index 2 --prev scene_01.json` checks one fragment against all rules
(structure, word budget, handoff truthfulness, soundscape continuity, dialogue (structure, composition floor, handoff truthfulness, soundscape and description
mirror). continuity, dialogue mirror).

View File

@ -27,6 +27,13 @@ DIALOGUE_SPAN_RE = re.compile(r"<d>(.*?)</d>")
MARKER_RE = re.compile(r"^\[[^\]]+\]\s*") MARKER_RE = re.compile(r"^\[[^\]]+\]\s*")
CONTINUITY_RE = re.compile(r"\b(same\b|continu|still\b)", re.I) CONTINUITY_RE = re.compile(r"\b(same\b|continu|still\b)", re.I)
# The gate is a composition gate, not a word counter: there is no target band and
# no upper limit. The floor only trips on lazy output that could not possibly carry
# the elements of a scene composition (subject, wardrobe, style, continuity,
# blocking, camera, performance, texture, sound, exit state).
THIN_FLOOR_SHORT = 100 # description words, scenes under 10 s
THIN_FLOOR_LONG = 120 # description words, scenes of 10 s or longer
def load_json_text(text, label=""): def load_json_text(text, label=""):
"""json.loads tolerant of a surrounding markdown fence (LLM output).""" """json.loads tolerant of a surrounding markdown fence (LLM output)."""
@ -180,9 +187,11 @@ def check_h3_sections(plan):
f"shot {idx}: description line must re-state <Subject 1> (prefix is empty)" f"shot {idx}: description line must re-state <Subject 1> (prefix is empty)"
dur = float(shot.get("duration_seconds", dur = float(shot.get("duration_seconds",
plan.get("defaults", {}).get("duration_seconds", 15))) plan.get("defaults", {}).get("duration_seconds", 15)))
lo, hi = (200, 300) if dur >= 10 else (150, 200) floor = THIN_FLOOR_LONG if dur >= 10 else THIN_FLOOR_SHORT
assert lo <= wc <= hi, \ assert wc >= floor, \
f"shot {idx}: {wc} words outside {lo}-{hi} budget for a {dur:g}s scene" (f"shot {idx}: description is only {wc} words - too thin to carry the "
f"elements of a scene composition (subject, wardrobe, style, continuity, "
f"blocking, camera, performance, texture, sound, exit state)")
assert " is now " not in lines[0].lower(), \ assert " is now " not in lines[0].lower(), \
f"shot {idx}: change stated as bare outcome instead of shown progression" f"shot {idx}: change stated as bare outcome instead of shown progression"
assert "<d>" not in lines[1] and "</d>" not in lines[1], \ assert "<d>" not in lines[1] and "</d>" not in lines[1], \
@ -191,10 +200,11 @@ def check_h3_sections(plan):
assert re.search(r"silently with mouth", lines[0]), \ assert re.search(r"silently with mouth", lines[0]), \
f"shot {idx}: dialogue span lacks a mouth-state cue" f"shot {idx}: dialogue span lacks a mouth-state cue"
print(" H3 section structure: all shots have the 3 sections in canonical order") print(" H3 section structure: all shots have the 3 sections in canonical order")
print(" description word budget:", print(" description lengths:",
[(f"{len(s['prompt'][0].split())}w @ " [(f"{len(s['prompt'][0].split())}w @ "
f"{s.get('duration_seconds', plan.get('defaults', {}).get('duration_seconds', 15))}s") f"{s.get('duration_seconds', plan.get('defaults', {}).get('duration_seconds', 15))}s")
for s in plan["shots"]], "| <10s: 150-200, >=10s: 200-300") for s in plan["shots"]],
"| composition elements are the gate - no word band")
return True return True
@ -253,10 +263,12 @@ def validate_fragment(obj, index=1, total=None, prev_handoff=None, expect=None):
raise ValueError(f"{where}: line 3 must start with 'non_diegetic_music:'") raise ValueError(f"{where}: line 3 must start with 'non_diegetic_music:'")
wc = len(desc.split()) wc = len(desc.split())
lo, hi = (200, 300) if dur >= 10 else (150, 200) floor = THIN_FLOOR_LONG if dur >= 10 else THIN_FLOOR_SHORT
if not lo <= wc <= hi: if wc < floor:
raise ValueError(f"{where}: description is {wc} words, outside {lo}-{hi} " raise ValueError(f"{where}: description is only {wc} words - too thin to carry "
f"for a {dur:g}s scene") f"the elements of a scene composition (subject, wardrobe, "
f"style, continuity, blocking, camera, performance, texture, "
f"sound, exit state)")
if "<Subject 1>" not in desc: if "<Subject 1>" not in desc:
raise ValueError(f"{where}: description must re-state <Subject 1> (prefix is empty)") raise ValueError(f"{where}: description must re-state <Subject 1> (prefix is empty)")
if " is now " in desc.lower(): if " is now " in desc.lower():
@ -295,6 +307,10 @@ def validate_fragment(obj, index=1, total=None, prev_handoff=None, expect=None):
if prev_line and not CONTINUITY_RE.search(ssc): if prev_line and not CONTINUITY_RE.search(ssc):
raise ValueError(f"{where}: soundscape does not continue the previous audio " raise ValueError(f"{where}: soundscape does not continue the previous audio "
f"bed (say 'the same ... continues')") f"bed (say 'the same ... continues')")
if prev_line and not CONTINUITY_RE.search(desc):
raise ValueError(f"{where}: description does not open inside the previous "
f"end_state (use a continuity cue: 'Continue the same ...', "
f"'without resetting the motion')")
if expect is not None: if expect is not None:
if expect.get("id") not in (None, shot_id): if expect.get("id") not in (None, shot_id):
raise ValueError(f"{where}: outline says id {expect.get('id')!r}, " raise ValueError(f"{where}: outline says id {expect.get('id')!r}, "
@ -314,7 +330,7 @@ def validate_fragment(obj, index=1, total=None, prev_handoff=None, expect=None):
raise ValueError(f"{where}: seed out of range") raise ValueError(f"{where}: seed out of range")
print(f" {where} id={shot_id!r} dur={dur:g}s raw={raw_frames} frames " print(f" {where} id={shot_id!r} dur={dur:g}s raw={raw_frames} frames "
f"words={wc} (band {lo}-{hi}) handoff ok" f"words={wc} handoff ok"
+ (f" dialogue={len(spans)}" if spans else "")) + (f" dialogue={len(spans)}" if spans else ""))
return handoff return handoff
@ -411,7 +427,7 @@ def run_fragment_suite():
cases = [ cases = [
("missing _handoff", {k: v for k, v in NURSE_OK.items() if k != "_handoff"}, {}), ("missing _handoff", {k: v for k, v in NURSE_OK.items() if k != "_handoff"}, {}),
("duration outside 2-15", _short_fragment(duration_seconds=20), {}), ("duration outside 2-15", _short_fragment(duration_seconds=20), {}),
("description far under word budget", ("description too thin to compose the scene",
_short_fragment(prompt=["integrated_multimodal_description: [Shot 1] " _short_fragment(prompt=["integrated_multimodal_description: [Shot 1] "
"<Subject 1> walks on. End mid-stride.", "<Subject 1> walks on. End mid-stride.",
NURSE_OK["prompt"][1], "non_diegetic_music: N/A"]), {}), NURSE_OK["prompt"][1], "non_diegetic_music: N/A"]), {}),