@lemoncat7/dsh-partner 2.4.2 → 2.7.0

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

@@ -0,0 +1,181 @@
+# Sound & Dialogue Plan Template (Mode H)
+
+Load this file when you are at Step 11 (sound and dialogue plan) or the user asked for Mode H.
+Sound craft — what a bed does, how audio leads a cut, lip-sync and VO technique, what music is
+for — is owned by [sound and dialogue](../references/sound-and-dialogue.md). Cut points and pacing
+math are owned by [editing and assembly](../references/editing-and-assembly.md). Asset naming is
+owned by [continuity bible](../references/continuity-bible.md). This file owns the spreadsheet you
+hand to whoever builds the mix.
+
+The worked example inherits its sound direction from [director book](director-book-template.md)
+and its shot timings from [shot plan](shot-plan-template.md): project `Under the Door` (`UTD`),
+scene 7, 22s, five shots — a courier hesitates outside a Republican-era Shanghai apartment door,
+slides an envelope under it, and leaves.
+
+## The five layers
+
+Every shot gets an entry in all five layers, even when the entry is `none`. A blank you never
+decided is a hole in the mix; a `none` you decided is a choice, and the difference is visible on
+the page.
+
+| Layer | Code | Cut to picture? |
+|---|---|---|
+| Room tone（房间底噪） | RT | No — continuous |
+| Ambience（环境声） | AMB | No — continuous |
+| Foley（拟音） | FOL | Yes — frame-accurate |
+| Spot FX（效果音） | SFX | Yes — frame-accurate |
+| Music（音乐） | MUS | No — to named beats on its own bar grid, never to a picture cut |
+
+What each layer is, and the level range each one sits in, belong to
+[sound and dialogue](../references/sound-and-dialogue.md) and are deliberately not repeated here —
+two copies of a level table is how a mixer ends up 10 dB off. One thing worth carrying across
+while you fill the sheet: every level in the skill is dB relative to dialogue at 0, the programme
+is anchored once at delivery rather than per layer, and in a scene with no dialogue the 0 is
+notional — the level dialogue would have occupied — so the ranges do not move.
+
+One classification rule this sheet does enforce, because it is the cell people get wrong: anything
+continuous is RT or AMB whatever object makes it, and only discrete designed events are SFX. A
+filament hum belongs in room tone, not in a spot-FX cue that never stops.
+
+## The continuous-bed rule
+
+Room tone and ambience run as one unbroken pair of tracks across the whole scene, laid before any
+other layer and never cut at a picture edit. Only foley, spot FX, and music are cut to picture.
+
+This matters more in AI video than in live action: generated clips each carry their own invented
+audio and no two agree about the room, so splicing them produces an audible tone change at every
+edit — the aural version of a seam (F15, F18). The fix is procedural, not creative:
+
+1. Mute or discard every generated audio track. Treat generated audio as a timing reference only.
+2. Lay one room-tone track for the full scene duration plus 1s of handle at each end.
+3. Lay one ambience track the same way. Change it only when the *space* changes, and then
+   cross-fade over 0.5–1.0s, never on a hard cut.
+4. Build foley and spot FX on top, cut to frame.
+5. Place music last, against beats you can name.
+
+When the picture does cut to a different room, the bed changes — by cross-fade, and that change is
+itself a story event you should be able to justify in one sentence.
+
+## Per-shot five-layer table
+
+Columns follow the Mode H notation in [sound and dialogue](../references/sound-and-dialogue.md):
+`Space` names the shot size and any source not in the camera's room — `same room` when there is none — so the perspective moves with the coverage instead of sitting flat across every size. The four cases and their level, filter and reverb offsets are owned by [sound and dialogue](../references/sound-and-dialogue.md). `@t` is time from that shot's first frame, never program time. Absolute program timecodes live in
+one place only, [edit timeline template](edit-timeline-template.md), so a re-time changes one
+document instead of two. Write `none` in a cell you decided against; leave nothing blank.
+
+| Shot | In–Out | Space | RT | AMB | FOL | SFX | MUS | Dialogue/VO | Silence |
+|---|---|---|---|---|---|---|---|---|---|
+| `SHnn` |  |  |  |  |  |  |  |  |  |
+
+Filled — `UTD_SC07`. The book's sound direction is explicit: no score anywhere in this scene, and
+the paper scraping tile is the loudest thing in it. There is no dialogue here, so 0 is notional and
+every level below is read off the bands in
+[sound and dialogue](../references/sound-and-dialogue.md) — the paper cue sits at the top of the
+spot-FX band rather than being promoted to 0, which keeps this sheet legible next to a scene that
+does have dialogue in it.
+
+| Shot | In–Out | Space | RT | AMB | FOL | SFX | MUS | Dialogue/VO | Silence |
+|---|---|---|---|---|---|---|---|---|---|
+| `SH01` | 0:00–0:04 | WS, stairwell — same room; street is outside heard from inside | Stairwell tone with the filament bulb's hum baked into it, 0.8s reverb tail, continuous, −34 | Street two floors down, distant, no traffic detail, −28 | Cloth shoes on tile, three crossing steps @0.4 / @1.1 / @1.7, the last one short; satchel canvas shift on the stop | none — the hum is continuous, so it belongs in RT and never gets its own cue | none — no score in this scene | none | none |
+| `SH02` | 0:04–0:09 | MCU, landing — same room; radio is through a closed door | bed continues | Radio behind the door comes up @0.6 to −18, mid-band only, no intelligible words | Padded-jacket rustle as the arm rises @0.8; one swallow, close, @2.4; jacket settle @4.2 | none | none | none | none |
+| `SH03` | 0:09–0:12 | CU, landing — same room; radio and chair are through a closed door | bed continues | Radio holds; street ducks 2 dB | none — deliberate | Chair scrape behind the door @1.5, the first hard sound in the scene | none | none | The book's 1.5s of near-silence, @0.0–@1.5. Not digital silence: the bed stays under, everything else out |
+| `SH04` | 0:12–0:18 | MS low, landing — same room; radio through the door, gap line at 20cm | bed continues | Radio holds, unchanged | Knees and heels on tile @0.2; two fingers on wood @5.4 | Paper scraping tile @2.0–@4.6 at −6, the top of the spot-FX band and the loudest cue in the scene, alone in its band | none | none | none |
+| `SH05` | 0:18–0:22 | WS, stairwell — same room; radio recedes through the door as he goes | bed continues; tone tail runs 1.0s past picture | Radio and street unchanged — nothing acknowledges that he left | Two backing steps, then four descending, each 2 dB quieter, gone by @3.0 | none | none | none | none |
+
+Reading it: the bed never breaks; only foley and spot FX respect the cuts; the radio enters on
+`SH02` and never leaves, so the room behind the door stays occupied for the rest of the scene.
+`SH03` carries the scene's turn in its Silence cell and has an empty foley line on purpose — which
+is the reason the column exists. A blank there would have read as an oversight and someone would
+have filled it with footsteps.
+
+## Music brief
+
+One block per cue, in the field set owned by
+[sound and dialogue](../references/sound-and-dialogue.md) — brief the function, never the genre.
+When the scene has no score, still write the block: the decision is worth recording, and a written
+`none` is the only thing that stops someone adding a cue in the mix six weeks later.
+
+```text
+CUE M0  "no cue"
+FUNCTION: none. The book scores this scene with a radio the courier cannot control
+IN:       n/a
+OUT:      n/a
+TEMPO:    n/a
+INSTR:    n/a
+SHAPE:    n/a
+NOT:      no cue at any level anywhere in SC07, including under the exit and the end tail
+ENFORCED: no music track exists in the timeline; every generated clip's audio is muted at import
+```
+
+The diegetic radio is briefed as a source element, not a cue. It belongs to ambience in the layer
+table and to the location in the continuity bible, but it needs a brief of its own because someone
+has to make or license it, and because it is the only thing in the scene an era error can reach:
+
+```text
+SOURCE SRC-radio  "behind door 3F"
+FUNCTION: keep the room he will not enter occupied, from SH02 to the end
+PLACEMENT: heard through a closed dark-stained door — low-pass around 900 Hz, 0.8s stairwell tail
+IN:       SH02 @0.6
+OUT:      runs past picture; leaves with the room-tone tail
+ERA:      1937 Shanghai broadcast idiom; small band, no synthesis, no modern kit
+LEVEL:    -18, ducking 2 dB while the paper cue runs
+NOT:      never intelligible in any language; never lands on a cut; never changes program at the
+          chair scrape; never resolves when he leaves
+```
+
+Two habits behind those blocks. Name the function before the instrumentation, because a function
+survives a change of composer and "solo cello" does not. And fill `NOT:` every time — most bad cues
+fail by doing too much, and the exclusion is the only line that stops them.
+
+## Dialogue & VO sheet
+
+Speaking rates, the VO density ceiling, and the clip-length formula are owned by
+[sound and dialogue](../references/sound-and-dialogue.md). Two of its numbers do all the work in
+this column, and they are not the same number:
+
+- **On camera**, the clip has to hold more than the words: `clip = 0.6s pre-roll + line ÷ rate +
+  0.8s hold`, then add 2.5s of handle to the generation — a dialogue take is character performance
+  and pays the full rate, and the handle budget is owned by
+  [editing and assembly](../references/editing-and-assembly.md). A line that merely fits the clip
+  length does not fit the clip.
+- **Voice-over** is laid in the mix, so it budgets the speech only — but it is capped by picture,
+  not by rate: about 1.3 words per second of shot, roughly half dialogue density.
+
+Estimates are for planning. Measure the recorded take before locking picture.
+
+| ID | Shot | Speaker | On/Off | Lang | Line | Delivery | Count | Est. dur | Decision |
+|---|---|---|---|---|---|---|---|---|---|
+| D1 | `SHnn` |  |  |  |  |  |  |  |  |
+
+Filled — `UTD_SC07` and the head of the next scene:
+
+| ID | Shot | Speaker | On/Off | Lang | Line | Delivery | Count | Est. dur | Decision |
+|---|---|---|---|---|---|---|---|---|---|
+| A1 | `SH02`–`SH05` | Radio behind door | Off | — | non-verbal, no intelligible words | Muffled, mid-band | — | 18.0s | Not dialogue. Never treat as a line; no lip-sync risk; must not become intelligible in the mix |
+| V1 | `SH05` | Courier | VO | EN | "I told myself it was kindness." | Slow, weighted | 6 words | 3.0s speech | **Cut.** 6 words over a 4s shot is 1.5 words/s, over the VO ceiling — but that is not why it goes. At any length it explains the shot's only job. The aftermath is the argument; a VO turns it into a caption |
+| D2 | `SC08_SH01` | Woman, 50s | On camera | 中文 | 「他没有敲门。」 | Slow, flat, reading aloud | 5 spoken chars | 2.8s clip | Keep. 5 ÷ 3.5 = 1.4s of speech, plus 0.6s pre-roll and 0.8s hold = 2.8s inside a 4s clip; generate at 6.5s, because a performance take pays the 2.5s handle and a first/last-frame pair cannot buy it back — the drift is between the pinned frames. Lip-sync required: generate speech, or shoot mute and lay VO |
+
+Three decisions that sheet forces now instead of during the mix. A1 is not a line, so nobody
+records it and no model is asked to lip-sync it. V1 dies on the page rather than after someone
+records it, and the arithmetic is the cheap part of that call — count the spoken units before you
+argue about the words. Note what is *not* counted in D2: the full-width period is a spoken pause,
+not a character, and counting punctuation is the standard way a Chinese line comes back 20% over
+its budget. D2 is also the project's only lip-sync shot, so it is the only place F15 can occur;
+budget the retries there and nowhere else.
+
+## Handoff checklist
+
+- [ ] Room tone and ambience exist as single continuous files, scene length plus 1s handles,
+      named `PROJ_SCnn_vNN_amb.wav` — version before role, per the continuity bible's grammar.
+- [ ] Every generated clip's native audio is muted or deleted, not merely lowered.
+- [ ] Every foley entry names the material, not just the object — "cloth shoes on tile".
+- [ ] Every spot FX has an `@t` from its own shot's first frame, not just a shot number.
+- [ ] The Silence column is filled on every row, including `none`, and nothing over 1s is held at
+      true digital zero — the bed stays under it.
+- [ ] The music block exists even when the answer is "no score", and says who enforces it.
+- [ ] Every dialogue line has an estimated duration and an explicit lip-sync decision.
+- [ ] Any on-camera line fits pre-roll plus speech plus hold inside its clip — not just the speech.
+- [ ] Every on-camera line is ordered at clip length plus the 2.5s performance handle, not at clip
+      length.
+- [ ] Total dialogue and cue durations checked against the cut length in
+      [edit timeline template](edit-timeline-template.md).

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

@@ -0,0 +1,305 @@
+# Video Motion Prompt Template (Mode F)
+
+Load this file when you are at Step 10 (AI video prompt construction) or the user asked for Mode
+F — finished prompts to paste into a generator. The four prompt shapes and their slot orders,
+which slots a given model actually reads, and what its UI controls instead of text are owned by
+[AI video tool adapters](../references/ai-video-tool-adapters.md). Word choice, word budgets,
+banned words, the negative library and the cut order for an over-long prompt are owned by the
+[prompt lexicon](../references/prompt-lexicon.md). This file owns the fill-in forms and the
+per-prompt self-check.
+
+Every worked example inherits from [director book](director-book-template.md) and
+[shot plan](shot-plan-template.md), and animates the stills built in
+[keyframe prompt template](keyframe-prompt-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.
+
+## Token economy
+
+The slot order below is S1 in [AI video tool adapters](../references/ai-video-tool-adapters.md),
+which owns the four shapes and their slot lists; the word budgets — for image-to-video, roughly
+40–80 words — the reasons the order matters, and the cut order for an over-long prompt are owned by
+the [prompt lexicon](../references/prompt-lexicon.md). What this table adds is how that budget
+divides and when a slot disappears entirely. `Slot` is position in the prompt, not importance: the
+action and the end state are the two things the lexicon says never to cut.
+
+| Slot | Content | Share of the budget | Cut it entirely when… |
+|---|---|---|---|
+| 1 | Camera behavior — one move, one speed, or `locked` | 10–15% | The tool has a camera-motion UI; set it there, not in text |
+| 2 | Subject start state, only what the input frame already shows | 10% | Text-to-video: there is no input frame to anchor to |
+| 3 | One primary action, with its pace and direction | 32% | Never |
+| 4 | One environmental response | 10% | The scene has no movable element |
+| 5 | Explicit end state | 15% | Never |
+| 6 | Continuity lock — the book's invariants compressed to one clause | 10% | The clip is under 2s and locked |
+| 7 | Exclusions — two or three risk classes | 8% | The tool has a real negative field; put them there instead |
+
+Pace belongs inside slot 3 and does not get a slot of its own. A bare pace word floating between
+the lock and the exclusions attaches itself to the nearest verb, which is as often the camera as
+the subject — say "lowers slowly to his thigh over about two seconds", not "slow motion".
+
+Slots 1–5 come to roughly 80% of an image-to-video prompt. If most of the prompt
+re-describes what the input image already proves, you are paying tokens for nothing and diluting
+the action. Each filled example below carries its word count — check yours against them, not
+against how thorough the prompt feels.
+
+## Slot dictionary
+
+| Bracket | Put in it | Never put in it |
+|---|---|---|
+| `[camera]` | One named move plus a speed and a distance, or `locked` | A second move; a move the tool controls by slider; "dynamic camera" |
+| `[start state]` | A static, checkable body position that matches the input frame | New wardrobe, new props, a new location |
+| `[action]` | One transitive verb, its object, a speed, a direction | Interior states: realizes, remembers, feels, struggles, hesitates |
+| `[environment]` | One movable element: a shadow, cloth, dust, a light line, breath | A second character; a second action by the subject |
+| `[end state]` | A pose or composition you could photograph as a still | "and then he leaves and it fades" — that is two shots |
+| `[invariants]` | The book's `ID_`, `LOCK_`, `LIGHT_` strings, compressed to one clause | A full re-description of the input image |
+| `[negatives]` | The 2–4 risks specific to this shot, plus only those `NEG_BASE` classes this framing can actually produce, to a combined ceiling of about six — the dilution rule is owned by [prompt lexicon](../references/prompt-lexicon.md) | A wall of negatives copied from another shot; a category ("no modern objects") rather than named instances |
+| `[sound]` | Only if the model generates audio: the source, not an adjective | Anything the sound plan owns; see Mode H |
+
+Where the tool has a separate negative field, put the whole of `NEG_BASE` in it — it costs nothing
+there. Inline negatives are the ones that have to fight the positive prompt for attention, so
+inline only what this framing can actually produce: "no extra people" earns its place in a landing
+wide, not in an extreme close-up of a 4cm gap.
+
+## Template 1 — image-to-video, single shot
+
+```text
+[Camera]. Starting from the input image, [subject] is [start state], then [one primary action
+with speed and direction]. [Environment element] [moves how]. End with [explicit end state].
+Maintain [invariants]. Avoid [negatives].
+```
+
+Filled — `UTD_SC07_SH02`, 5s, from `UTD_SC07_SH02_v03_kf-first.png`. The input frame has the hand
+down, because that is where shot 01 left it; the raised knuckles are what this clip has to produce:
+
+```text
+Locked camera. His right hand rises until the knuckles stop 3cm short of the wood, holds about one
+second, then lowers slowly to his thigh over about two seconds. The knuckles never touch the door.
+His breath shows once against the cold rim behind him. End with the hand at his thigh, still facing
+the door, the envelope still up at chest in his left hand. Same face, cap, jacket and satchel side;
+same bulb camera-left. Avoid: the hand touching the door, knocking, the door opening, a second
+person, rendered text.
+```
+
+91 words, just over the lexicon's 40–80 band, and two of them are the whole shot: `3cm short` and
+`never touch`. If the tool truncates, the breath clause goes first. There is also no separate
+start-state clause, because the action names the limb the frame already shows at rest — slot 2
+earns its tokens only when the input frame leaves it ambiguous which part of the body moves. What
+is *not* in it is the rest of the identity string and the whole room; the input frame proves both,
+and re-describing them is the most common way a prompt starves its own action.
+
+中文变体 / Chinese-UI variant, same shot:
+
+```text
+固定镜头。他的右手抬起，指节停在距门板3厘米处，停约1秒，再用约2秒缓慢放下到大腿旁。
+指节始终不碰到门。他的呼吸在身后的冷调轮廓光上出现一次。结尾停在：右手垂在大腿旁，
+仍正对着门，信封仍举在左手胸前。保持同一张脸、帽子、棉袄、左肩挎带；灯泡仍在镜头左侧。
+避免：手碰到门、敲门、门被打开、出现第二个人、画面出现文字。
+```
+
+## Template 2 — first frame + last frame
+
+Use when the change has a designed endpoint, and always for the scene's highest-risk shot. The
+two frames must be one action apart; if you cannot describe the bridge in a single clause, split
+the shot.
+
+```text
+Use the first image as the opening frame and the second image as the closing frame. The shot
+travels from [first-frame state] to [last-frame state] through [one continuous action].
+Camera [one move with distance and duration, or locked]. Motion is [pace word].
+Preserve [invariants]. No [negatives].
+```
+
+A pair prompt should be *shorter* than a single-frame one, not longer: both ends are already
+photographs, so the text pays only for the bridge between them. Describing the two stills back to
+the tool is the classic way to waste a keyframe pair.
+
+It is also the one generation you order at cut length rather than at cut length plus a handle:
+both ends are pinned by approved stills, so there is no ramp-in to discard and no drift-out to
+trim. That is the single licensed exception to the handle rule in
+[editing and assembly](../references/editing-and-assembly.md), and it does not extend to a
+dialogue take built as a pair — the performance happens between the two frames, which is exactly
+where the drift is.
+
+Filled — `UTD_SC07_SH04`, 6s, the scene's one moving shot and its highest-failure clip:
+
+```text
+Use the first image as the opening frame and the second image as the closing frame. Between them,
+one continuous feed-and-push: the envelope slides under the door, then two fingers push it the last
+few centimetres until the fingertips meet the wood, with no stall between the two halves. Camera
+dollies in 25cm over the full six seconds, one direction, no reverse, no reframe. Preserve the same
+courier, satchel on the left shoulder, the door chip at frame-right, the bulb camera-left. No third
+hand, no bending or tearing of the paper, no envelope visible at the end.
+```
+
+97 words, and the last sentence is three negatives — correct here and nowhere else in this scene.
+This is the plan's one `Red` shot, and each of the three names a failure it has already been graded
+as likely to produce.
+
+## Template 3 — text-to-video
+
+No input frame, so you pay for description. Everything a keyframe would have proven now has to be
+written, and identity is the part that will not hold from words alone — expect more retries per
+usable second, and prefer this mode for plates, inserts, and shots with no face.
+
+```text
+[Format, aspect, stock/finish]. [Subject with concrete identity and wardrobe]. [Location, era,
+time of day]. [One primary action with speed and direction]. [Shot size, angle, camera move].
+[Named light source, side, ratio]. [Composition and depth]. [Sound if supported]. [Negatives].
+```
+
+Filled — `UTD_SC07_SH03`, 3s, the one shot in the scene with no face in it, which is exactly why it
+can survive text-to-video:
+
+```text
+16:9, 35mm film stock, fine grain, low saturation. The 4cm gap under a dark-stained apartment
+door, worn red floor tile, dark-green wainscot above; a third-floor landing in 1937 Shanghai,
+winter. No figure except the toe of one cloth shoe at the bottom edge, motionless. A shadow
+crosses the warm light line under the door from inside, right to left, over about two seconds, and
+the line is unbroken again. Extreme close-up, head-on, camera 15cm off the floor, 85mm, locked.
+The only light in frame is the spill from the room behind the door; the near side of frame is
+three stops under. No rendered text or numerals, no watermark, no second foot, the door never
+opens.
+```
+
+116 words, inside the lexicon's 60–120 text-to-video band. Read against Template 1 it shows where
+the extra 25 went: format, era, materials, and light source — every line the input frame would
+otherwise have supplied for free.
+
+## Template 4 — multi-shot / timestamped
+
+Only for models that honor timestamps. Put the invariants once in the `Overall` line, never
+inside each shot: per-shot repetition eats tokens and invites contradiction. Note that a
+timestamped block gives up per-shot control of duration and cut point, so use it for previs or a
+social cutdown, not for the deliverable when the shot plan has named cut frames.
+
+```text
+Overall: [era, location, palette, stock, identity keywords, continuity rules].
+[00:00-00:0X] Shot 1: [size/angle]. [one action]. Camera [move]. Sound: [source].
+[00:0X-00:0Y] Shot 2: [size/angle]. [one action]. Camera [move]. Sound: [source].
+[00:0Y-00:0Z] Shot 3: [size/angle]. [one action]. Camera [move]. Sound: [source].
+```
+
+Filled — `UTD_SC07` as a 12s three-shot previs block:
+
+```text
+Overall: third-floor landing of a 1937 Shanghai lilong apartment block, peeling dark-green
+wainscot to waist height, cracked cream plaster, worn red floor tile, dark-stained door with a
+chipped lower-left corner, a stairwell window at the head of the stairs opposite the door. One
+bare filament bulb hanging over the stairhead, warm and hard, 5:1 lit side to shadow side; a thin
+warm line spills from
+the 4cm gap under the door. Low saturation, high contrast in the lower third; the envelope is the
+only pure white. One character only: 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; wool cap pushed back, canvas satchel on the left shoulder. Same face and wardrobe in every
+shot. No rendered text or numerals, no rubber soles, no wristwatch, the
+door never opens.
+[00:00-00:04] Shot 1: wide, high 15 degrees, 35mm. He climbs into frame, crosses the landing in
+three steps and stops squared to the door 60cm out, envelope up at chest. Camera locked. Sound:
+cloth shoes on tile, stairwell reverb.
+[00:04-00:09] Shot 2: medium close-up, eye level, 50mm, bulb camera-left raking his face. He
+raises his right hand, the knuckles stop 3cm short of the wood, he swallows, the hand lowers to
+his thigh. Camera locked. Sound: a muffled radio behind the door, no intelligible words.
+[00:09-00:12] Shot 3: extreme close-up, head-on, camera 15cm off the floor, 85mm, on the 4cm gap
+and its warm light line; the bulb is out of frame here and the line is the only light. A shadow
+crosses the line from inside, right to left, and the line is unbroken again. Camera locked. Sound:
+a chair scrapes behind the door.
+```
+
+Note what moved into the shot lines: camera height in cm, and the key direction. Heights go in cm
+so a reader never parses them as a second focal length, and key direction is camera-relative, so it
+is false the moment a setup changes — it cannot live in the `Overall` block with the invariants.
+
+## Template 5 — continuation / extend
+
+For tools that extend a clip from its final frame. An extend continues one shot; it cannot cross a
+cut, because the new footage inherits the old framing, and asking it to change setup produces a
+morph rather than an edit. If the next thing on the timeline is a different size, angle or camera
+height, that is a new generation, not an extension. The extend model also sees the tail of the
+video and not your original prompt, so restate the invariants and start from the **observed** last
+frame, not the one you intended.
+
+```text
+Continue from the final frame of the previous clip. [Subject] is [observed end state, described
+as a still]. Now [the single next action, with speed and direction]. Camera [same behavior as
+before, or explicitly: camera behavior changes to X]. Preserve [invariants]. Do not restart, do
+not reset the pose, do not cut. Avoid [negatives].
+```
+
+Filled — `UTD_SC07_SH05`, extending its own first 3s. The EWS was generated up to the moment he
+leaves frame; the extension is the hold that the shot exists for. Same setup, same lens, same
+camera height — which is what makes it an extension and not a second shot:
+
+```text
+Continue from the final frame of the previous clip. The landing is empty; he has just dropped out
+of frame at the bottom of the stairs. Over about one second a shadow crosses the warm line under
+the door from inside, right to left, and the line is unbroken again. Camera stays locked exactly as
+before; it does not pan down after him. Preserve the worn red tile, the door chip, the bulb
+camera-left, and the grain. Do not restart, do not reset, do not cut. Avoid: the door opening, a
+figure re-entering frame, the warm line going dark.
+```
+
+99 words, and an extension always runs longer than the shot it continues, because it pays for two
+things a fresh generation does not: a description of what the observed last frame contains, and the
+do-not-restart clause. Everything else should come out. The identity string, for one, is absent on
+purpose — there is no person in this extension, so `ID_COURIER` would be dead tokens at best and an
+invitation to put him back in frame at worst. Preserve what is still in the picture: here the room,
+the light and the texture.
+
+## Template 6 — dialogue shot
+
+Only for models that generate speech. Label speakers by a visual attribute, never by a pronoun
+and never by a name the model cannot see. Keep each line inside the clip's speakable budget —
+roughly 2.5 English words or 4.5 Chinese characters per second, and the clip must also carry
+pre-roll before the first word and a hold after the last. Rates and the clip-length formula are
+owned by [sound and dialogue](../references/sound-and-dialogue.md); the sheet that records the
+per-line decision is [sound plan template](sound-plan-template.md).
+
+```text
+[Camera]. [Shot size on the speaker]. [Speaker A: visual label, vocal register, volume]:
+"[line]". [A's visible behavior while speaking — mouth, breath, gaze, hands].
+[Then Speaker B: visual label, vocal register]: "[line]". [B's visible behavior].
+Lip movement must match the spoken line. Preserve [invariants]. Avoid [negatives].
+```
+
+Filled — a shot from the following scene, where the letter is finally read aloud:
+
+```text
+Locked camera, medium close-up, eye level, 50mm, on a woman in her fifties seated at a table by a
+window. Woman in a dark quilted jacket, grey hair pinned back, reading aloud from a single sheet,
+voice low and even, no tremor: 「他没有敲门。」 Her eyes stay on the page, her jaw moves only as
+far as the words require, her free hand flat on the table. No other voice is heard. Lip movement
+must match the spoken line and stops the moment the line ends. Preserve the same face, the quilted
+jacket, the window light from camera-left, the 1937 interior. Avoid: a second speaker, the camera
+pushing in, subtitles burned into the frame, the paper changing shape.
+```
+
+Scene 7 itself has no speech at all — the book's sound direction allows only a muffled radio with
+no intelligible words — which is why this example had to come from the scene after it. When a scene
+is written that way, do not let a speech-capable model fill the silence. Any prompt that puts a
+face in speaking range gets `no speech, no lip movement` in its negatives; the `SH02` prompt above
+does not need it only because the shot never opens his mouth.
+
+## Per-prompt self-check
+
+Run on every prompt before you send it. Five questions, and the failure each one prevents.
+
+- [ ] **One action.** Count the objectives, not the verbs. One gesture with a named stop is one
+  action — rise, stop 3cm short, lower is a single aborted knock, and a swallow or a breath inside
+  it is texture. Two objectives is two clips. (Guards F4.)
+- [ ] **One camera move.** Count camera verbs. More than one, or a move plus "dynamic"? Cut to
+  one, or lock it. Check it against the book's move budget. (Guards F6.)
+- [ ] **Explicit end state.** Could you photograph the last sentence as a still? If not, rewrite
+  it as a pose or a composition. (Guards F5.)
+- [ ] **Invariants present.** The `ID_`, `LOCK_`, and `LIGHT_` strings, compressed but not
+  reworded, plus the scene's checkable anchor. (Guards F1, F7, F8, F12.)
+- [ ] **Negatives matched to real risk.** Name the condition in this shot that makes each one
+  plausible — including the `NEG_BASE` classes, which you select from rather than paste whole.
+  Cannot name it? Delete it. About six classes is the ceiling: every unearned negative dilutes
+  the ones that matter, and a category ("no modern objects") dilutes without ever resolving into
+  anything the model can withhold. (Guards F8, F9, F11.)
+
+Two more that cost nothing: no adjective is doing work a noun could do better, and nothing in the
+prompt merely re-describes the input image. Symptom-to-cause lookup for anything that comes back
+wrong is in [failure modes](../references/failure-modes.md); scoring and gating are in
+[qc checklist](qc-checklist.md).

package/resources/skills/cinematic-director/upstream/evals/run.md

@@ -0,0 +1,69 @@
+# Running the Evals
+
+[evals.json](evals.json) is a behaviour contract, not a suite that executes itself. Each case is a prompt plus assertions checkable from the response text alone. Running it means generating responses, then grading them.
+
+## Run one case by hand
+
+1. Open a fresh session with the skill installed and nothing else in context. A carried-over conversation is the largest source of false passes.
+2. Paste the case's `prompt` verbatim. Add nothing — no "use the cinematic-director skill", no format hint, no reminder of the mode.
+3. Save the whole response, preamble included, then grade the assertions in order against that text.
+
+One case per session. Two cases in one session lets the second inherit the first's shot plan.
+
+## Run the suite with a grading agent
+
+Generate one response per case in `evals.json` first, then grade. Generating and grading in one session leaks the assertions into the answer. Send this once per case, with nothing else in context:
+
+```text
+You are grading one response against a fixed list of assertions. You have no other job.
+
+CASE PROMPT:
+<the case's prompt field, verbatim>
+
+RESPONSE:
+<the full response text>
+
+ASSERTIONS:
+1. <assertion 1>  ...  n. <assertion n>
+
+For each assertion output exactly one line:
+  <n>. PASS|FAIL — <quoted span from the response, or why nothing satisfies it>
+
+Judge only what is written in RESPONSE. Do not infer intent, do not credit a near
+miss, and do not reward good work the assertion did not ask for. An assertion naming
+a number, a unit, or a verbatim clause fails unless that number, unit, or clause
+appears in the text. Output no summary and no advice.
+```
+
+## What counts as a pass
+
+| Assertion shape | Passes when |
+|---|---|
+| Names a number or range — "in mm", "sums to 20 seconds", "0-18" | The number is present and inside the range. Arithmetic that does not close is a fail. |
+| Names a verbatim artifact — "repeated verbatim across all four prompts" | The string appears identically in every place the assertion names. |
+| Forbids something — "no segment line contains an emotion word" | Zero instances anywhere in the response. One instance is a fail. |
+| Names a structure — "look, what-is-seen, reaction" | Every named part is present and identifiable. Partial structure is a fail. |
+| Names proportion — "no director's book appears" | Judge the delivered sections, not the word count. |
+
+A case passes only when every one of its assertions passes. Assertions are the unit of diagnosis; cases are the unit of the score.
+
+## The pass bar
+
+- **Ship bar: 92% of cases** — 52 of the 57 in the suite today. Below that, do not tag a release.
+- **Hard-fail set, which must pass whatever the total:** `symptom-only-no-artifact`, `one-line-ask-one-deliverable`, `multi-shot-timestamped-sequence`, and every case carrying a copyright-safety assertion. These guard guardrails, not craft.
+- Re-run a failing case twice before editing the skill. Three runs distinguish model variance from a real hole; one failure does not.
+
+## The `loads` field
+
+`loads` is **advisory and is not graded**. Response text does not reliably state which files were opened, and an assertion that demanded it would be an assertion about hidden reasoning — which this suite forbids. Two ways to check it when it matters: read the harness's tool log for the run and diff the opened paths against `loads`; or, with no log, treat `loads` as a claim about the routing table in [../SKILL.md](../SKILL.md) and verify the table instead of the response. CI checks that every `loads` path exists on disk. It cannot check that a response used it.
+
+## Adding a case
+
+1. Give it a unique lowercase hyphenated id naming the behaviour under test, not the scene.
+2. Carry exactly the six fields — `id`, `mode`, `loads`, `prompt`, `expected_output`, `assertions`. The validator rejects extras and missing ones.
+3. Write 5-6 assertions, each checkable from the response text by a reader who has not opened SKILL.md.
+4. Assert nothing SKILL.md does not specify. Where the skill forbids something, assert the forbidden thing is absent — never assert behaviour the skill rules out.
+5. A new director overlay needs exactly one case proving the lens changed camera, palette, pacing, or sound, plus the copyright-safety assertion. See [../CONTRIBUTING.md](../CONTRIBUTING.md).
+6. Run `python3 -c "import json;json.load(open('evals/evals.json'))"` before pushing; the `evals` workflow runs the full validation.
+
+Worked example — assertion 4 of `multi-shot-timestamped-sequence`, "no segment line contains an emotion word". Scan the three segment lines only, not the global block or the prose around them. `[00:03-00:06] Close on her hand taking the envelope, camera locked.` carries none, and neither do the other two: PASS. Had it read `she takes the envelope nervously`, that one instance fails the assertion outright — no credit for the two clean segments.