@lemoncat7/dsh-partner 2.5.0 → 2.7.1

package/resources/skills/cinematic-director/upstream/assets/keyframe-prompt-template.md

@@ -0,0 +1,334 @@
+# Keyframe Prompt Template (Mode E)
+
+Load this file when you are at Step 8 (keyframe strategy) or the user asked for Mode E — first
+frames, last frames, storyboard panels, character sheets, or location plates. The nine-slot order
+and the reasoning behind it are owned by
+[image model adapters](../references/image-model-adapters.md) §3, together with model control
+surfaces and consistency tooling. Word choice, banned words, and the negative library are owned by
+the [prompt lexicon](../references/prompt-lexicon.md). Asset ids and seed tracking are owned by
+[continuity bible](../references/continuity-bible.md). This file owns the fill-in forms.
+
+Build keyframes only after the rules exist. Every worked example below inherits from
+[director book](director-book-template.md) and [shot plan](shot-plan-template.md): project
+`Under the Door` (`UTD`), scene 7, 22s, 16:9, five shots — a courier hesitates outside a
+Republican-era Shanghai apartment door, slides an envelope under it, and leaves.
+
+## Slot dictionary
+
+Nine slots, then a constraints tail. Fill in this order; image-model-adapters §3 explains why the
+order is not cosmetic.
+
+| # | Slot | Must contain | Must never contain |
+|---|---|---|---|
+| 1 | Shot id | `PROJ_SCnn_SHnn` plus the frame role: `kf-first`, `kf-last`, `panel`, `sheet`, `plate` | Beat name, emotion, story explanation |
+| 2 | Size, angle, lens | Shot size, camera height in cm or m, angle in degrees, focal length in mm | Camera *movement* — a still does not move; a height written in mm, which reads as a second focal length |
+| 3 | Identity string | The book's frozen invariant, verbatim, word for word | A paraphrase, an emotion, an attractiveness word, "same as before" |
+| 4 | Pose implying action | Limb positions, hand shape, eyeline target, distances in cm | Intent verbs: hesitating, wondering, deciding |
+| 5 | Wardrobe & props | Every garment and carried object with material, closure, and which side | Style labels: "period clothing", "vintage look" |
+| 6 | Location & era | The book's location invariant, verbatim, then which setup within it and where the door plane and the window fall for *this* camera | Genre words: "noir", "period drama" |
+| 7 | Light source & direction | The book's light invariant, verbatim — it is world space: source, height, ratio, what stays under — then one sentence giving this setup's camera-relative key direction, copied from the shot plan's `Light dir` cell | Mood words: "moody", "dramatic lighting"; a camera-relative direction rewritten *into* the invariant |
+| 8 | Composition | Placement in frame, headroom, which plane sits under, depth layers. At 9:16 or 1:1, also the band of frame height the story-critical content occupies — see the vertical safe zones in [cinematic language](../references/cinematic-language.md), which are per-platform and must be checked, not remembered | A rule name with no placement attached; a safe-zone percentage quoted from memory |
+| 9 | Texture / medium | Stock or medium, grain, halation, palette in plain color words | "8K", "masterpiece", "hyperrealistic"; a bare millimetre number slot 2 could read as a second lens — write `35mm film stock`, never `35mm` alone |
+| — | Constraints | Aspect ratio, then the book's `NEG_BASE` plus this frame's own risks | A boilerplate wall carried over from a different shot |
+
+## Working with the book's invariant strings
+
+The director's book publishes four strings. Three of them — `ID_COURIER`, `LOCK_LANDING`,
+`LIGHT_INVARIANT` — fill slots 3, 6 and 7 verbatim. Copy them; do not improve them. One re-worded
+adjective is a different person, a different room, or a different lamp. `NEG_BASE` fills the
+constraints tail and is the one string you select from rather than paste whole, for the reason
+given under it.
+
+```text
+ID_COURIER: a 19-year-old Chinese man with a narrow jaw, deep-set eyes under a low brow, a
+2 cm scar through the left eyebrow, black hair clipped short and shaved high at the neck, in
+a grey padded cotton jacket buttoned to the throat with one bone button missing at the collar
+
+LOCK_LANDING: third-floor landing of a 1937 Shanghai lilong apartment block, peeling dark-green
+wainscot to waist height, cracked cream plaster above, worn red floor tile, dark-stained door
+with a brass knob and a chipped lower-left corner, a stairwell window at the head of the stairs
+opposite the door
+
+LIGHT_INVARIANT: a single bare filament bulb hanging over the stairhead, warm, hard, above head
+height, 5:1 lit side to shadow side with no fill but plaster bounce; cold daylight from the
+stairwell window behind him, rimming his back and cap and never reaching his shadow side; the
+door face stays well under; the only light on the door is a thin warm line spilling from the 4cm
+gap beneath it
+
+NEG_BASE: no rendered text, signage or numerals; no watermark; no lever handles, plastic, rubber
+soles, wristwatch or printed logos; no extra people; no face or costume change; the door never
+opens
+```
+
+`NEG_BASE` names instances and never categories: "no modern objects" is a category no generator
+can resolve into things, and it is the mechanism behind F8. The era class therefore lists the
+objects the book's `must avoid` line already named. Six classes is the working size — small
+enough to paste whole into a tool's negative field, and small enough that a prompt carrying it
+inline plus this frame's own risks still lands near the lexicon's budget rather than at a wall.
+
+None of them contains `camera-left` or `frame-right`, and that is deliberate: one string is pasted
+into a setup and into its reverse, where those words flip. Camera-relative direction is per-setup
+and comes from the shot plan's `Light dir` and `Frame content` cells — paste the invariant, then
+add one sentence for this camera. In this scene every setup sits on one side of the line, so the
+bulb reads high camera-left 45°, the door plane sits camera-right, and the window is behind him at
+camera-left rear; write that sentence in each prompt, never back into the string.
+
+Note what `ID_COURIER` does: it is face structure first and ends on exactly one wardrobe anchor,
+the jacket with its missing collar button, so its tail reaches into slot 5. Everything else the
+character wears — the cap, the satchel — stays in slot 5 and never migrates back into the string.
+Split the anchor off the moment the project has a second fitting or a costume change; otherwise a
+wardrobe edit in reel two silently rewrites the face. When you split, keep the face half under the
+same name and add a fitting string (`FIT_COURIER`), and record both in the continuity bible.
+
+`ID_COURIER` carries its own checkable landmark, the scar through the left eyebrow — that is what
+proves identity. The scene needs a second anchor that is not on the actor at all, because half the
+shots do not hold his face. The book bans rendered numerals, so the door number cannot be it: use
+the **chip in the door's lower-left corner** and the **unbroken warm line under the door**. Both
+survive at every shot size in this scene, and either one missing is provable drift.
+
+## Template — first frame
+
+```text
+[PROJ_SCnn_SHnn kf-first]. [Size, angle, camera height, ##mm].
+[ID string verbatim]. [Static pose: limbs, hand shape, distances in cm], eyes on [target].
+[Prop and its state]. [LOCK string verbatim]; [which setup within it, and where the key planes
+fall for this camera]. [LIGHT string verbatim]. In this setup [camera-relative key direction].
+[Placement, headroom, which plane sits under, depth layers].
+[Stock, grain, palette]. The pose must read as [action] about to begin.
+[Aspect]. [NEG_BASE + this frame's own risks].
+```
+
+The first frame of a shot is the previous shot's end state, not a moment plucked from the middle of
+the gesture. Shot 01 ends squared to the door with the envelope at chest and both arms down, so
+that is where `SH02` starts; the raised knuckles are something the video prompt has to produce.
+
+Filled — `UTD_SC07_SH02_v03_kf-first`, the hand that cannot knock:
+
+```text
+UTD_SC07_SH02 kf-first. Medium close-up, eye level, camera at 1.6m, 50mm. A 19-year-old Chinese man
+with a narrow jaw, deep-set eyes under a low brow, a 2 cm scar through the left eyebrow, black hair
+clipped short and shaved high at the neck, in a grey padded cotton jacket buttoned to the throat
+with one bone button missing at the collar. He stands squared to the door 60cm out, both arms down,
+the right hand at his thigh with the fingers half closed and the knuckle scrape showing, his weight
+settled forward toward the door; eyes level on the door face. A wool cap pushed back off his
+forehead, a canvas satchel strap across his chest on the left shoulder, and a cream envelope, white
+face out, held up at chest height in his left hand. Third-floor landing of a 1937 Shanghai lilong
+apartment block, peeling dark-green wainscot to waist height, cracked cream plaster above, worn red
+floor tile, dark-stained door with a brass knob and a chipped lower-left corner, a stairwell window
+at the head of the stairs opposite the door; door-side setup, the door plane camera-right, the
+window behind him at camera-left rear. A single bare filament bulb hanging over the stairhead,
+warm, hard, above head height, 5:1 lit side to shadow side with no fill but plaster bounce; cold
+daylight from the stairwell window behind him, rimming his back and cap and never reaching his
+shadow side; the door face stays well under; the only light on the door is a thin warm line
+spilling from the 4cm gap beneath it. In this setup the bulb reads high camera-left at 45 degrees
+and rakes the side of his face. His head and near shoulder occupy frame-left, the dark door plane
+fills frame-right, envelope edge low-left, the cold rim along the back of his cap. 35mm film stock,
+fine grain, low saturation, high contrast in the lower third, dull green and cracked cream against
+worn red, the envelope the only pure white. The pose must read as a knock about to begin. 16:9. No
+rendered text, signage or numerals; no watermark; no wristwatch, no rubber soles, no printed logos;
+no face or costume change; the brass number plate defocused or out of frame; the right hand still
+down and not touching the wood.
+```
+
+Six classes in the tail, and note that it is not `NEG_BASE` pasted whole. Two base classes were
+dropped because this framing cannot produce them — an MCU on one man has no room for an extra
+person, and "the door never opens" is a motion constraint that means nothing to a still — and the
+era class was pruned to the three instances that could actually appear at this size. Two of the
+frame's own risks took the space. Where the model exposes a negative field, put all six `NEG_BASE`
+classes in it and keep only those two frame-specific lines inline.
+
+## Template — last frame
+
+The last frame is the first frame plus one completed change. Reuse slots 2, 3, 5, 6, 7, 9 word
+for word; edit only slot 4 and, if the body moved, slot 8. Derive it from the approved first
+frame rather than generating it fresh — see image-model-adapters §6.
+
+Not every shot earns a pair. `SH02` starts with the hand down and ends with the hand down, so its
+two frames would be near-identical and the tool would have nothing to travel through; that shot is
+image-to-video from one frame. Build a pair when the end state is a different photograph.
+
+```text
+[PROJ_SCnn_SHnn kf-last]. [Slot 2 line, identical]. [ID string verbatim].
+He has completed [action]; now [new static pose]. [Prop in its new state].
+[LOCK string, identical]. [LIGHT string, identical]. [New placement if the body moved].
+[Slot 9 line, identical]. Same face, same wardrobe, same room, same lamp, same lens as kf-first.
+[Aspect]. [Constraints].
+```
+
+Filled — `UTD_SC07_SH04_v06_kf-last`, the irreversible delivery:
+
+```text
+UTD_SC07_SH04 kf-last. Medium shot, low, camera 40cm off the floor, tilted up 10 degrees, 35mm. A
+19-year-old Chinese man with a narrow jaw, deep-set eyes under a low brow, a 2 cm scar through the
+left eyebrow, black hair clipped short and shaved high at the neck, in a grey padded cotton jacket
+buttoned to the throat with one bone button missing at the collar. He has completed feeding the
+envelope under the door; now he is still crouched on his heels with the first two fingers of his
+right hand flat against the wood just above the gap, the knuckle scrape up, both hands otherwise
+empty and open, forearms resting on his knees. The same wool cap pushed back off his forehead and
+the canvas satchel strap across his chest on the left shoulder. No envelope is visible anywhere in
+frame. Third-floor landing of a 1937 Shanghai lilong apartment block, peeling dark-green wainscot
+to waist height, cracked cream plaster above, worn red floor tile, dark-stained door with a brass
+knob and a chipped lower-left corner, a stairwell window at the head of the stairs opposite the
+door; door-side low setup, the door plane camera-right. A single bare filament bulb hanging over
+the stairhead, warm, hard, above head height, 5:1 lit side to shadow side with no fill but plaster
+bounce; cold daylight from the stairwell window behind him, rimming his back and cap and never
+reaching his shadow side; the door face stays well under; the only light on the door is a thin warm
+line spilling from the 4cm gap beneath it. In this setup the bulb reads high camera-left and sits
+on his back and cap; the gap line underlights his hands from 20cm; his face two stops down. He is
+crouched frame-left, the door plane fills the right two-thirds with the chipped lower-left corner
+visible in it, the warm line under the door unbroken again and running the full width. 35mm film
+stock, fine grain, low saturation, warmest and lowest frame of the scene, dull green and cracked
+cream against worn red. Same face, same wardrobe, same room, same lamp, same lens as kf-first.
+16:9. No rendered text, signage or numerals; no watermark; no wristwatch, no rubber soles, no
+printed logos; no face or costume change; no envelope still visible; no third hand.
+```
+
+Its `kf-first` is that block with one substitution, which is what "one action apart" means in
+practice: slot 4 becomes *crouched on his heels, the envelope pinched flat between the thumbs and
+first fingers of both hands, its leading edge touching the 4cm gap, no part of it yet through*, and
+the closing line becomes *the warm line under the door broken by the envelope*. Slots 2, 3, 5, 6,
+7, 9 are copied, not retyped.
+
+## Template — storyboard panel
+
+A panel is not a pose. It must carry one of five jobs — a motion about to begin, a motion just
+completed, a reveal, a power relation, or a story clue — and if it carries none of them, delete the
+shot row rather than draw the panel. The jobs, and the physical devices that make a still imply
+motion, are in image-model-adapters §7.
+
+```text
+[PROJ_SCnn_SHnn panel]. [Size, angle, ##mm]. [Who and where, one clause each].
+The panel shows [about-to / just-completed / reveal / power / clue] — specifically
+[the visible evidence]. [Light source and where the shadow falls]. [Placement].
+Loose graphite storyboard line drawing, grey wash for shadow, no color. [Aspect]. [Exclusions].
+```
+
+Filled — `UTD_SC07_SH05 panel`, the aftermath:
+
+```text
+UTD_SC07_SH05 panel. Extreme wide shot, high +15 degrees from the half-landing, 35mm. The empty
+landing; the courier already out of frame at the bottom of the stairs; the closed door small at
+frame-right. The panel shows a motion just completed — specifically the unbroken warm line under
+the door with a shadow entering it from inside, and no one on the landing to see it. The bulb
+high camera-left throws a hard rail shadow across the tile toward camera. The door occupies the
+right quarter; two-thirds of the frame is empty tile and plaster. Loose graphite storyboard line
+drawing, grey wash for shadow, no color. 16:9. No text, no arrows, no panel border, no figure.
+```
+
+## Template — character sheet
+
+Generate once, before any shot keyframe. Everything downstream inherits from it. If the model
+drifts between panels on one canvas, generate views separately and compose the sheet yourself —
+image-model-adapters §4.
+
+```text
+[PROJ_CHAR-slug_vNN ref-face | ref-body]. [Views, evenly spaced, named left to right].
+[ID string verbatim]. Neutral expression, relaxed shoulders, arms at sides.
+Flat frontal light, 5600K, about 1:1 lit side to shadow side so neither side reads as the shadow
+side, no rim. Plain mid-grey seamless background.
+No lens distortion; subject occupies 80% of frame height. [Aspect]. [Exclusions].
+```
+
+The reference sheet is the one image that must carry no lighting opinion. A ratio as steep as 2:1
+already picks a shadow side, and every shot generated from the sheet inherits that decision as if
+it were bone structure.
+
+Filled — `UTD_CHAR-courier_v01_ref-body`:
+
+```text
+UTD_CHAR-courier_v01 ref-body. Four views of the same person, evenly spaced left to right: front,
+three-quarter left, full profile left, full body front. A 19-year-old Chinese man with a narrow
+jaw, deep-set eyes under a low brow, a 2 cm scar through the left eyebrow, black hair clipped short
+and shaved high at the neck, in a grey padded cotton jacket buttoned to the throat with one bone
+button missing at the collar. Thin, narrow-shouldered under the jacket. Wool cap pushed back off
+his forehead, canvas satchel strap across his chest on the left shoulder. Neutral expression,
+relaxed shoulders, arms at sides, gaze to camera; right hand turned so the knuckle scrape is
+visible. Cloth shoes with worn welts. Flat frontal light, 5600K, about 1:1 lit
+side to shadow side so neither side reads as the shadow side, no rim. Plain mid-grey seamless
+background. No
+lens distortion; subject occupies 80% of frame height. 1:1. No props except the satchel. No text,
+no labels, no watermark, no extra people, no wristwatch, no rubber soles.
+```
+
+Crop the three-quarter head as the reference for MCU and CU; use the full body for wides — a head
+crop makes the model guess the build, and this character is specifically thin.
+
+## Template — location plate
+
+An empty plate with no actor. It fixes architecture, lamp position, and tile direction so every
+shot in the location inherits the same room instead of re-inventing it.
+
+```text
+[PROJ_LOC-slug_vNN plate-wide]. No people. [Size, camera height, angle, ##mm].
+[LOCK string verbatim]. [LIGHT string verbatim, naming which source is dominant].
+[Foreground / mid / background layers]. [Texture line]. [Aspect].
+Empty room, no figures, no animals, no text. [Era exclusions].
+```
+
+Filled — `UTD_LOC-landing_v01_plate-wide`:
+
+```text
+UTD_LOC-landing_v01 plate-wide. No people. Wide shot, high +15 degrees from the half-landing,
+35mm — the scene's widest permitted lens. Third-floor landing of a 1937 Shanghai lilong apartment
+block, peeling dark-green wainscot to waist height, cracked cream plaster above, worn red floor
+tile, dark-stained door with a brass knob and a chipped lower-left corner, a stairwell window at
+the head of the stairs opposite the door. A single bare filament bulb hanging over the stairhead,
+warm, hard, above head height, dominant, 5:1 lit side to shadow side with no fill but plaster
+bounce; cold daylight from
+the stairwell window, a rim only and never a fill; the door face stays well under; a thin warm line
+spills from the 4cm gap beneath the door. In this setup the bulb reads high camera-left at 45
+degrees and the window shaft rakes in from the back of frame. Foreground: painted iron stair rail
+frame-left. Mid: red tile and the door at frame-right. Background: the window shaft, dust visible
+in it. 35mm film stock, fine grain, low saturation, high contrast in the lower third. 16:9.
+Empty room, no figures, no animals, no text. No lever handles, no plastic, no conduit wiring, no
+glass in the door, no printed logos, no rendered numerals on the door.
+```
+
+One clause of `LIGHT_INVARIANT` is edited here and only here: the window is described as a rim
+rather than "rimming his back and cap", because on an empty plate that phrase has no referent. That
+is the single permitted deviation, it applies to the plate alone, and the full string goes back in
+verbatim the moment a figure is in frame.
+
+Generate this plate and shot 03's ECU first: they are the cheapest images in the scene, they settle
+the palette, and where the tool exposes a reference-image or seed slot they are what the rest of
+the scene binds to.
+
+## Pre-video keyframe QC gate
+
+Run before spending video credits. Every box here is free to fix now and can only be fixed by
+regenerating the still later — video never repairs a keyframe error, it animates it. This is the
+tick-box form of the reasoned gate in image-model-adapters §9; the scored form is Gate 1 in
+[qc-checklist.md](qc-checklist.md).
+
+- [ ] The book's three descriptive invariants — `ID_`, `LOCK_`, `LIGHT_` — appear verbatim, not
+      paraphrased, in every frame, the empty location plate's single documented edit aside.
+- [ ] No camera-relative direction has been written back into an invariant string; every
+      `camera-left` / `frame-right` in the prompt sits in a per-setup sentence of its own.
+- [ ] No emotion or attractiveness word sits in slot 3; expression is physical, in slot 4.
+- [ ] The scene's checkable anchor (here: the door chip and the unbroken warm line) is visible
+      and correct at this shot size.
+- [ ] The `kf-first` pose is the previous shot's end state, not a moment from mid-gesture.
+- [ ] `kf-first` and `kf-last` of the same shot share slots 2, 3, 5, 6, 7, 9 word for word.
+- [ ] The gap between first and last frame is one action, not two.
+- [ ] The pose implies a direction of motion; it is not a symmetrical resting pose.
+- [ ] Hands are visible and countable, or deliberately cropped out of frame.
+- [ ] No numerals, signage, or text appear — the number plate is defocused or out of frame.
+- [ ] Era check: nothing in frame post-dates the stated year, against the book's `must avoid`.
+- [ ] Focal length is inside the book's kit; nothing wider than 35mm in this scene.
+- [ ] Apparent perspective matches the stated focal length — no wide-angle nose or bowed room
+      edges on a 50mm or longer frame, no flattened planes on a 35mm. Video cannot repair this.
+- [ ] The key direction matches this row's `Light dir` cell in the shot plan, and the ratio matches
+      the invariant.
+- [ ] Aspect matches delivery; you are not planning to crop later.
+- [ ] If 9:16 or 1:1 — faces, the hands doing the action, and anything that will be burned in
+      sit inside the frame-height band the vertical safe zones leave clear, per
+      [cinematic language](../references/cinematic-language.md). Check the current per-platform
+      numbers against the platform's spec; do not quote them from memory, and do not assume the
+      16:9 headroom habit survived the crop.
+- [ ] Exclusions are the `NEG_BASE` classes this framing can actually produce, plus this frame's
+      own risks — around six classes total, nothing inherited blindly, and no category among them.
+- [ ] Filename follows `PROJ_SCnn_SHnn_vNN_role.ext` and the asset is in the seed and reference
+      registry — `seed: null` where the tool exposes none.
+
+Anything that fails maps to an F-code in [failure modes](../references/failure-modes.md); report
+it using the block at the end of [qc-checklist.md](qc-checklist.md).

package/resources/skills/cinematic-director/upstream/assets/qc-checklist.md

@@ -0,0 +1,153 @@
+# QC & Repair Checklist (Mode J)
+
+Load this file when you are at Step 13 (QC and repair loop) or the user says a generation is
+wrong. Diagnosis depth — the symptom, cause, and fix behind every F-code below — is owned by
+[failure modes](../references/failure-modes.md). Retry budgets, version naming, and the approval
+log are owned by [production workflow](../references/production-workflow.md). This file owns the
+three gates, the score, and the report format.
+
+Three gates, in order. PRE runs on the plan and keyframes before you spend credits, POST runs per
+clip, SEQUENCE runs on the assembled cut. Only the PRE gate's failures are free to fix: a planning
+error caught there costs an edit, and the same error caught after generation costs every clip built
+on it.
+
+Worked examples use project `Under the Door` (`UTD`), scene 7, the five-shot scene planned in
+[beat sheet](beat-sheet-template.md), [director book](director-book-template.md), and
+[shot plan](shot-plan-template.md).
+
+## Gate 1 — PRE-GENERATION
+
+| # | Weight | Category | Check |
+|---|---|---|---|
+| P1 | 20 | Story function | Every shot names a beat id and the job it does for that beat. A shot whose function is "it looks good" is deleted, not scored |
+| P2 | 15 | Blocking & camera logic | Start, motion, end written for each shot; one dominant move at most; the move is inside the book's move budget and is motivated by what the audience must newly see |
+| P3 | 25 | Keyframe integrity | The tick-box gate at the end of [keyframe prompt template](keyframe-prompt-template.md) passes: invariant strings verbatim, `kf-first` and `kf-last` sharing slots 2, 3, 5, 6, 7, 9, the checkable anchor visible at this shot size, hands visible or deliberately cropped, apparent perspective matching the stated focal length, no rendered text |
+| P4 | 20 | Prompt hygiene | The five-question self-check in [video prompt template](video-prompt-template.md) passes on every prompt: one action, one camera move, explicit end state, invariants present, negatives matched to real risk. Clip length sits inside the duration strategy owned by [ai video tool adapters](../references/ai-video-tool-adapters.md) — 3–5s for a face-carrying shot, 3–4s for fine hand work, 8–12s only where no legible face is in frame |
+| P5 | 20 | Continuity setup | End state of shot N equals start state of shot N+1; era, props, and light state declared and consistent; seeds and reference assets recorded in the registry |
+
+Score each 0–5, then `weighted = Σ (score ÷ 5 × weight)`.
+
+- Threshold to generate: **80 / 100**. Below that you are buying rework.
+- 90 and above: generate the whole scene. 80–89: generate, and expect one retry on the weakest
+  shot. 70–79: fix the failing row first — it is cheaper than a retry. Below 70: the problem is
+  the plan, and no number of generations will find it for you.
+
+## Gate 2 — POST-GENERATION, per clip
+
+Watch each clip four times: once at speed for the whole, once at 0.25× for hands and face, once
+with the sound off, once with the sound only. The last two are not padding — picture errors hide
+under plausible audio, and audio errors hide under picture you have already accepted.
+
+| # | Weight | Category | Check | F-codes |
+|---|---|---|---|---|
+| G1 | 25 | Identity & wardrobe | Face, build, hair, the checkable anchor, and every garment hold from the first frame to the last | F1, F16 |
+| G2 | 20 | Action & end state | The requested action happened, once, and the clip ends on the pose you specified; the clip is an event, not a still frame drifting under a camera move | F2, F4, F5 |
+| G3 | 20 | Motion, anatomy, physics | Limbs and fingers stay countable; weight, contact, and gravity read correctly; speed matches life | F3, F10, F13, F14 |
+| G4 | 10 | Camera behavior | One move, the one you asked for, at the distance you asked for; no unrequested drift or zoom | F6, F17 |
+| G5 | 15 | Frame integrity | No extra people or objects; nothing that was in frame at the head of the clip has gone missing or come back changed at the tail; no rendered text or watermark; no morphing background | F9, F11, F19 |
+| G6 | 10 | Look consistency | Lighting direction, level, color temperature, and grain hold across the clip | F12, F16 |
+
+- **80–100**: use as-is.
+- **65–79**: usable if an edit-side fix exists — trim the bad frames, crop in, regrade, or cover
+  the moment with a cut. Log the fix in the timeline note, not just in your head.
+- **Below 65**: regenerate. Change exactly one thing per retry, or you will not learn which change
+  worked.
+
+Worked example — `UTD_SC07_SH04_v05_clip.mp4`, the irreversible delivery, generated as plain
+image-to-video from the first frame alone:
+
+```text
+G1 identity   5/5 × 25 = 25.0   narrow jaw, deep-set eyes under the low brow, and the 2 cm
+                                left-eyebrow scar all hold; so does the missing collar button
+G2 action     4/5 × 20 = 16.0   envelope goes under, but the two-finger push starts before
+                                the feed completes, so the end state arrives 14f early
+G3 motion     2/5 × 20 =  8.0   right hand shows a sixth finger from 0:03.6 to 0:04.1
+G4 camera     5/5 × 10 = 10.0   25cm dolly-in, one direction, no reverse
+G5 frame      5/5 × 15 = 15.0   clean; door chip present throughout
+G6 look       4/5 × 10 =  8.0   gap line brightens about 1/3 stop over the clip
+                        -------
+                          82.0   -> but G3 is a blocker (F10, visible hand). Regenerate.
+```
+
+That is the point of keeping blockers separate from the score. At 82 the rubric alone would pass
+this clip; the hand disqualifies it regardless. `v06` fixed both flagged rows with one change —
+re-generating as first/last-frame, with the last frame showing empty hands and two fingertips on
+wood, which is what the shot plan's generation note asked for in the first place. It scored 91.
+Had `v06` also failed, the next step was the shot plan's stated contingency: split into `04a`
+crouch-and-feed and `04b` two-fingers-pushing, and re-time the scene.
+
+## Gate 3 — SEQUENCE
+
+Only meaningful on the assembled cut. These failures are invisible clip by clip. Rows are `Q`-prefixed
+because `S` belongs to the four prompt shapes in
+[ai video tool adapters](../references/ai-video-tool-adapters.md); a `Q` in a QC note is always a
+sequence row.
+
+| # | Weight | Category | Check | F-codes |
+|---|---|---|---|---|
+| Q1 | 25 | Splice continuity | Identity, wardrobe, prop state, and light state hold across every splice; end state of shot N matches start state of N+1 | F1, F7, F19 |
+| Q2 | 20 | Rhythm | ASL matches the scene's subject; no shot outstays its information; the cut has a shape rather than a constant pulse | — |
+| Q3 | 15 | Geography & direction | The 180° line is respected or deliberately broken; eyelines match; direction of travel is consistent | F7, F17 |
+| Q4 | 15 | Look uniformity | One grade pass across all clips; no clip is brighter, warmer, or grainier than its neighbours | F12, F16 |
+| Q5 | 15 | Sound | One continuous bed under the whole scene; no tone change at any picture cut; lip movement matches any spoken line | F15, F18 |
+| Q6 | 10 | Story delivered | A viewer who has not read the script understands what happened and what it cost | — |
+
+Threshold to deliver: **85 / 100**. The sequence gate is stricter than the clip gate because
+sequence errors are the ones an audience actually notices — nobody watches a clip in isolation.
+
+## Blockers — must fix regardless of score
+
+A clip or cut carrying any of these does not ship, even at 95.
+
+- An identity break a viewer can name: a different face, a vanished anchor, a changed garment (F1).
+- The requested action did not happen, or a different action happened (F4).
+- An extra person, hand, or animal in frame (F9).
+- A prop the story depends on vanishes mid-clip, or reappears as a different object (F19).
+- Rendered text, signage, subtitles, or a watermark (F11).
+- Anachronism in a period scene, against the book's `must avoid` list (F8).
+- An anatomy failure on a visible hand or face: extra fingers, fused limbs, a face that liquefies
+  mid-shot (F10).
+- A continuity contradiction across a cut that a second viewing exposes (F7).
+- Audio contradicting picture: lips that do not match the line, room tone that changes at a
+  splice (F15, F18).
+- Anything the user or the book listed explicitly under `must avoid` or `never`.
+
+Everything else is negotiable against schedule. These are not.
+
+## From a failed row to a repair
+
+This file scores; it does not diagnose. Take the F-codes attached to whichever row failed and go to
+[failure modes](../references/failure-modes.md), which is the sole owner of the F1–F19 taxonomy — the
+symptom in the user's own words, the ranked causes with their mechanism, the cost-ordered fixes, and a
+before/after prompt pair for every code. If the user described a symptom rather than a failed row,
+start at that file's symptom-to-code quick index and read only the one code it returns; if they
+described several, run its triage tree once per symptom and collect every code before reading any fix.
+
+Do not restate the taxonomy here. A second copy drifts within a version or two, and a repair note that
+quotes a drifted row is exactly the untraceable diagnosis the codes exist to prevent.
+
+## How to report a failure
+
+Paste this block. Filled, it gets a diagnosis in one pass. Unfilled, it still gets one — the
+diagnosis is simply given against stated assumptions, with the branches that would change it marked,
+because the skill answers on inference rather than interrogating you. The block is the shortcut, not
+the toll gate.
+
+```text
+CLIP: <asset filename with version, e.g. UTD_SC07_SH04_v05_clip.mp4>
+SHOT: <shot id, size, angle, lens, intended duration>
+TOOL: <model or platform, and mode: text-to-video / image-to-video / first+last frame / extend>
+INPUTS: <which keyframes, references, and seeds were used>
+PROMPT: <the exact prompt text, unedited>
+NEGATIVES: <exactly what you passed>
+EXPECTED: <one sentence>
+HAPPENED: <one sentence, plus the timecode of the first bad frame, e.g. "sixth finger at 0:03.6">
+GATE 2 SCORE: <per-category scores, if you ran them>
+ALREADY TRIED: <each retry, and the single thing changed in it>
+CONSTRAINTS: <credits left, deadline, whether the keyframe may be regenerated>
+```
+
+Two fields do most of the work. The timecode of the first bad frame separates a prompt problem
+from a duration problem: a failure at 0:00 is the prompt or the reference, a failure at 0:03 of a
+4s clip is almost always length. And `ALREADY TRIED` stops a diagnosis from proposing a retry that
+has already failed — which is, in practice, the most common way credits get spent twice.

package/resources/skills/cinematic-director/upstream/assets/shot-plan-template.md

@@ -0,0 +1,95 @@
+# Shot Plan Template
+
+Load this file when you are at Step 7 (shot list and coverage) or the user asked for Mode D — a shot list, 分镜表, storyboard table, or "give me the shots".
+
+Build rows only after the beats exist ([beat sheet](beat-sheet-template.md)) and the rules exist ([director book](director-book-template.md)). A shot plan written before those two is a list of pictures.
+
+## Shot table
+
+| # | Sec | Beat / function | Loc | Frame content | Blocking start → move → end | Size / Angle | Lens | Move | Light dir | Light / atmos | Continuity anchors | Risk | Transition | Gen note |
+|---:|---:|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| 01 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
+| 02 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
+
+## Field dictionary
+
+| Column | Must contain | Good | Bad |
+|---|---|---|---|
+| `#` | Story-order number, zero-padded, stable for the life of the project | `04`, later split into `04a` / `04b` | `Shot 4 (was 3)` |
+| `Sec` | In and out inside the scene, plus duration | `0:12–0:18 (6s)` | `about six seconds` |
+| `Beat / function` | The beat id from the beat sheet, plus the job this shot does for it | `B4 · irreversible delivery` | `emotional moment` |
+| `Loc` | The continuity-bible location id, plus which setup within it | `loc_landing / door side, low` | `hallway` |
+| `Frame content` | What a storyboard artist would draw: subject placement plus the two or three set and prop elements that must be in frame | `head and near shoulder frame-left, dark door plane fills frame-right, envelope edge low-left` | `he stands at the door` |
+| `Blocking start → move → end` | Three states, the last one named explicitly | `starts squared to the door → right hand rises, knuckles stop 3cm short → ends hand down at his thigh, still facing the door` | `he hesitates to knock` |
+| `Size / Angle` | One size off the ladder plus an angle in degrees or a named height. Give camera heights in cm so nothing here can be misread as a focal length | `MCU, eye level` / `MS, low, camera 40cm off the floor, tilted up 10°` | `medium-ish, dramatic angle` |
+| `Lens` | Focal length in mm (full-frame equivalent) and, when not obvious, the reason | `85mm — compresses the gap and keeps the corridor out of the background` | `telephoto` |
+| `Move` | Exactly one named move with distance and duration, or `locked` | `slow dolly-in, 25cm over 6s` | `slight push with a bit of drift` |
+| `Light dir` | Key direction relative to *this* camera, height, the named practical motivating it, the ratio written lit side : shadow side as the book records it, and what the fill actually is. Call a source behind the subject a rim, not a fill — a fill opens the shadow side and must sit near the lens axis to do it | `key: bulb, high camera-left 45°, 5:1, fill is plaster bounce only; window is a cold rim from upstage` | `moody side light` |
+| `Light / atmos` | What the light does in this frame that it did not do in the last one — contrast, atmosphere, which plane is held under | `door face 1.5 stops under; dust in the window shaft; breath visible` | `dark and cold` |
+| `Continuity anchors` | The named items that must match adjacent shots: identity, costume, prop state, light state | `scar through the left eyebrow, cap pushed back, satchel on left shoulder, envelope white face out, knuckle scrape right hand, warm line under door unbroken` | `same character and setting` |
+| `Risk` | The band — `Green` / `Amber` / `Red` — read off the difficulty rubric in [production workflow](../references/production-workflow.md), plus the six dimension scores in the rubric's own order and the one that drove the band | `Red 12 (3/1/1/2/3/2) — interaction 3, and it trips the contact override` | `might be tricky` |
+| `Transition` | How you leave the shot, and on which frame | `hard cut the frame the fingertips touch wood` | `cut to next` |
+| `Gen note` | The one thing the generator will get wrong, the instruction that prevents it, and the split plan if it still fails | `say "his knuckles stop short and never touch the door"; negative: knocking, hand on door. If it knocks anyway, drop to 3s.` | `use a good prompt, high quality` |
+
+## Risk legend
+
+Risk is a generation budget, not commentary. Score the six dimensions and read the band — Green, Amber, Red — off the difficulty rubric in [production workflow](../references/production-workflow.md), which also owns the retry budgets and the stop rules. Copy the band and the six scores into this column, in the rubric's order — Action / People / Camera / Duration / Interaction / Continuity — with the dimension that drove the band, and do not invent a second scale here; a plan that grades on its own private words cannot be budgeted against the retry table.
+
+In the worked example below the bands read 01 Green, 02 Amber, 03 Green, 04 Red, 05 Green. Shot 04 scores 12 — action 3, people 1, camera 1, duration 2, interaction 3, continuity 2 — and it also trips the contact override, because the envelope passes between his hand and the door and the rubric counts a prop passing between a subject and a fixed feature as contact. The override is the useful half of that reading: a 3-on-interaction plus 3-on-anything pair does not come down with a better prompt, only with the split already written into its Gen note.
+
+One Red in five is a plan. Three Reds in five is a wish — go back to Step 5 and lower the ambition, or split those shots on paper now rather than after a day of failed generations.
+
+## Worked example
+
+Project `Under the Door`, scene 7 — 22s, 16:9, 5 shots, ASL 4.4s. Beats `B1`–`B5` from [beat sheet](beat-sheet-template.md); lens kit, key direction and invariant strings from [director book](director-book-template.md).
+
+| # | Sec | Beat / function | Loc | Frame content | Blocking start → move → end | Size / Angle | Lens | Move | Light dir | Light / atmos | Continuity anchors | Risk | Transition | Gen note |
+|---:|---:|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| 01 | 0:00–0:04 (4s) | B1 · locate the errand | loc_landing / stairhead side | stair rail foreground frame-left, empty landing, cracked plaster filling the top third, door at frame-right, cold window shaft raking in from the back | starts off-frame below on the stairs → climbs into frame, three steps across the landing → ends squared to the door 60cm out, envelope up at chest, motionless | WS, high +15° from the half-landing | 35mm — holds him and the whole door in one frame | locked | key: stairhead bulb, high camera-left 45°, 5:1, fill is plaster bounce only; the window is a cold rim from upstage, not a fill | door face 1.5 stops under; dust in the window shaft; breath faintly visible | cap pushed back, grey padded jacket, satchel on left shoulder, envelope white face out, chipped lower-left door corner, warm line under door unbroken | Green 5 — one walking figure carrying a prop, locked camera | hard cut the frame he stops | I2V from keyframe, 4s. State the end state ("he stops walking and stands still facing the door") or he is as likely to be walked straight past it. One motion only — do not also animate the window light. |
+| 02 | 0:04–0:09 (5s) | B2 · the hand that cannot knock | loc_landing / door side | his head and near shoulder frame-left, dark door plane fills frame-right, envelope edge low-left | starts squared to the door, envelope in his left hand → right hand rises, knuckles stop 3cm short of the wood, held 1s → ends hand down at his thigh, still facing the door, envelope still up | MCU, eye level | 50mm — his single coverage, keeps the door plane readable behind him | locked | key: bulb, high camera-left 45°, rakes the side of his face; the window is behind him, so it rims his back and cap from camera-left rear and never opens the shadow side | door stays dark, nothing on it; 5:1; breath visible against the cold rim | the scar through his left eyebrow legible at this size; same cap, jacket, satchel and envelope; knuckle scrape on the right hand | Amber 7 (2/1/0/1/2/1) — a hand approaching a surface without contact is a classic completion error | hard cut as the hand reaches his thigh | Say "his knuckles stop short of the door and never touch it"; negative: knocking, hand touching door. Keep a hold-and-abort gesture near 5s: past that the clip has runway left over and tends to fill it with a second, unwanted gesture. |
+| 03 | 0:09–0:12 (3s) | B3 · the person inside becomes real | loc_landing / floor level at the door | the 4cm gap under the door, the warm light line, worn red tile, his boot toe at the bottom frame edge | starts on an unbroken warm line → a shadow crosses it from inside, right to left, as the radio comes up → ends with the line unbroken again but the room now audibly occupied | ECU, head-on, camera 15cm off the floor — the scene's one frontal frame | 85mm — compresses the gap and keeps the corridor out of the background | locked | only source in frame is the spill from inside, behind the door; his side of frame is 3 stops down | highest contrast in the scene; the light line is the sole highlight | tile pattern and grout direction, gap height, worn welt on the boot | Green 2 — no face, no hands, one moving shadow | hard cut as the shadow clears frame | Simplest shot here: generate it first and, where the tool exposes a reference-image or seed slot, use it as the palette reference for the rest. Animate the shadow only; state "the camera does not move and the door does not open." |
+| 04 | 0:12–0:18 (6s) | B4 · irreversible delivery | loc_landing / door side, low | low three-quarter on him crouched frame-left, door plane filling the right two-thirds, envelope entering the gap | starts crouched on his heels, envelope pinched in both hands at the gap → he feeds it under, then pushes with two fingers until his fingertips touch the wood → ends fingertips on the door, hands empty, still crouched | MS, low, camera 40cm off the floor, tilted up 10° | 35mm — the only lens that fits the crouch and the door plane together | slow dolly-in, 25cm over 6s — the scene's one moving shot | key: bulb still on his back and cap from camera-left; the gap line underlights his hands from 20cm; his face 2 stops down | warmest and lowest frame of the scene; the light line is briefly blocked by the envelope, then unbroken | envelope white face out until it disappears, two fingers of the right hand, knuckle scrape, door chip visible frame-right | Red 12 (3/1/1/2/3/2) — action 3 and interaction 3: the envelope passes between his hand and the door, which is contact with a fixed feature, so the contact override fires whatever the total says | hard cut the frame the fingertips touch wood | Highest-failure shot in the scene. Where the tool exposes a first/last-frame pair, use it, with the last frame showing empty hands and fingertips on wood. The split is already decided: 04a MS crouch and feed (4s) and 04b ECU two fingers pushing (3s), then re-time the scene. |
+
+Shot 05 (B5, aftermath, 4s) is left out of the table for length and reads: EWS, 35mm, high +15°, locked — shot 01's setup with the camera backed up the flight to the half-landing, since the lens does not change and the size has to come from distance. He backs two steps, turns and drops out of frame down the stairs; hold on the empty landing until a shadow crosses the light line from inside. Risk `Green 4`. Cut on the shadow.
+
+Check the plan against itself: 4+5+3+6+4 = 22s over 5 shots = ASL 4.4s, inside the book's 4–5s target. Size ladder reads WS(2) → MCU(4) → ECU(6) → MS(3) → EWS(1) — every adjacent pair differs by at least two steps, and 01/05 repeat one setup deliberately as a bookend. One moving shot out of five, on the commitment beat, as the book allows.
+
+## Compact variant
+
+Use these three columns when the user wants a short answer, a chat-width table, or a first pass before committing to the full plan. Everything technical collapses into the Frame cell; the story stays legible.
+
+| # | Frame | Action → end state |
+|---:|---|---|
+| 01 | WS · 35mm · high +15° · locked · 4s | He climbs into the landing, crosses it in three steps — ends squared to the door 60cm out, envelope at chest, motionless. |
+| 02 | MCU · 50mm · eye level · locked · 5s | His right hand rises and stops 3cm short of the wood — ends hand down at his thigh, still facing the door. |
+| 03 | ECU · 85mm · head-on, 15cm off the floor · locked · 3s | A shadow crosses the warm line under the door — ends on the line unbroken, the room now audibly occupied. |
+| 04 | MS · 35mm · low · dolly-in 25cm · 6s | Crouched, he feeds the envelope under and pushes with two fingers — ends fingertips on wood, hands empty. |
+| 05 | EWS · 35mm · high +15° · locked · 4s | He backs off, turns and drops down the stairs — ends on the empty landing as a shadow crosses the light line. |
+
+## Coverage check
+
+Read the plan column-wise before you read it row-wise. Each of these catches a different class of error.
+
+- Every beat has at least one shot. The turn beat may have two or three; no other beat may have more shots than the turn beat.
+- Every shot has exactly one job. Two jobs means two shots, or one shot re-blocked so the second job disappears.
+- Read the Frame content column alone, top to bottom. It should tell the story without the other columns. If it reads as five variations on one picture, you have angles, not coverage.
+- Read the Blocking column alone. Each end state should be the next row's start state — or the cut is doing work nobody has accounted for, and you should say what. The example has exactly one gap: 02 ends standing and 04 starts crouched. Shot 03 is what covers the crouch, and that is half of why it exists; if you cut it, you owe the audience the move.
+- Count the moving shots against the book's move budget. Over budget means the moves have stopped meaning anything.
+- Track screen direction down the page. In the example the courier faces camera-right at the door in every row; the first row that reverses that owes the audience a neutral shot or a cutaway.
+- Confirm the scene has an entry the audience can orient in and an exit they can leave on. A scene that starts on an insert and ends on an insert has no geography.
+
+Each row hands Step 8 (keyframes) its Frame content, Size, Lens, Light dir and Continuity anchors, and hands Step 10 (video prompts) its Blocking, Move, end state and Gen note. If a cell is empty, the downstream prompt will invent something in its place.
+
+## Rules
+
+- Shot numbers follow story order, not production order, and stay stable. Splitting a shot yields `04a` / `04b`; it never renumbers `05`.
+- Beat and story function must be explicit. If that cell is empty, the shot probably should not exist.
+- Blocking must contain a start and an end state, and **every shot must name its end state** in words a generator can be held to. "He hesitates" is not an end state; "hand down at his thigh, still facing the door" is. Staging geometry and blocking notation live in [blocking and staging](../references/blocking-and-staging.md); this column records the result, not the reasoning.
+- Every shot needs one dominant camera move or none — never two. If the shot needs a move and then a reframe, it is two shots.
+- Size change at a cut is conditional on angle change, and the condition is the one in [cinematic language](../references/cinematic-language.md): stay on the same axis and you owe two size steps, because one step on the same axis reads as a stutter rather than a cut; change the angle by 30° or more and one step is enough. A deliberate match — a true match cut, or a repeated setup used as a bookend — is exempt from both. Count the rungs on the ladder that file owns.
+- Lens and distance-to-subject stay matched across a shot-reverse-shot pair, and the only sanctioned break is the deliberate power imbalance — that rule is owned by [cinematic language](../references/cinematic-language.md). Record the choice and its reason in the `Lens` cell; do not grant yourself a second exception here.
+- Light direction may not change between shots of the same moment unless a source in the world changed. That is what the Light dir column is for — scan it down the page and any unexplained flip is a continuity error you can catch before generating.
+- Continuity anchors name specific items — face, costume, prop state, light state. Copy them from [continuity bible](../references/continuity-bible.md); do not invent them per row.
+- Do not cross the line or break screen direction between rows. Coverage geometry lives in [cinematic language](../references/cinematic-language.md).
+- Seconds must reconcile with the beat sheet's estimates and the book's target ASL. If the three disagree, fix the document that is wrong rather than adjusting the arithmetic.
+- Grade Risk before writing a single prompt, and split the `Red` rows on paper. Symptom-to-fix repair for shots that fail anyway is in [failure modes](../references/failure-modes.md).