@wji.ai/cli 0.9.1 → 0.9.2

package/skill/short-drama/reference/stage-storyboard.md

@@ -23,7 +23,7 @@ the script and `validate` names the cuts that broke.
 ## Start from the seed
 
 ```bash
-node {baseDir}/scripts/short-drama.mjs seed <project> storyboard --ep 1
+$SD seed <project> storyboard --ep 1
 ```
 
 Three worksheets, all deleted once the segments are written:
@@ -92,6 +92,16 @@ into the prompt.
   notes, the subtitles-off sentence in the prompt's language unless `params.subtitles`, on H3 the
   other person on screen during a line has `lips remain completely closed`, `<d>` holds only the
   line, and in sheets mode every person on screen is bound by `@imageK` inside their own shot.
+- **Reference binding** (gate `ref-binding`) — the picture plan has to survive into the delivery
+  text. Every picture gets **one** legend line saying what it is: a person by age / hair / clothes
+  from the character bible (two people described in the same words is how faces get swapped), the
+  room by its name, a prop by its name. Every picture that is *not* a person also says what may
+  **not** be copied from it (*take only its light ratios, contrast and colour temperature — never
+  its composition or its people*). Every person and every prop is bound by its label again **inside
+  its own shot**, the room is named once per segment (`Every shot stays inside @image1 …`), no
+  connected picture may go unused, and a sheets segment may not carry more pictures than the model
+  takes. Wording patterns and the six roles: `reference/reference-binding.md`; proofread text that
+  is not yet in the project file with `reference/prompt-audit.mjs`.
 - **`params.speechLeadSeconds`** (0.5) is added to the dialogue-fit check: a 4.0 s line needs a
   5 s cut.
 - A prop may carry **`textPolicy { mode: readable | symbolic | blank, text }`** (gate
@@ -152,13 +162,13 @@ preset's banned directions (e.g. `low-key` / `costume-dark`: `frontal` / `ambien
 `sweet-romance` / `costume-idol`: `underlight` / `top`), at least half the cuts with people in a
 segment use its preferred ones, the stop stays within the preset's limit, and a period or costume
 preset refuses a source its era did not have. Stage the person against the source first, then pick the camera side; the
-tables are in `cinematography.md` and the preset's guide.
+tables are in `../../short-drama-core/reference/cinematography.md` and the preset's guide.
 
 **Each segment is cut in its grammar** (`segment.grammar`, else `params.grammar`; see
-`grammar.md`): `action` segments open on a wide, take one move per cut and answer every impact
-(`action.md`); `faceslap` segments show the proof and a cascade of reactions
-(`grammar-faceslap.md`); `comedy` segments set up every punchline and give it laugh room
-(`grammar-comedy.md`). Each grammar adds its line to the prompt (`Action:` / `Payoff:` /
+`../../short-drama-core/reference/grammar.md`): `action` segments open on a wide, take one move per cut and answer every impact
+(`../../short-drama-core/reference/action.md`); `faceslap` segments show the proof and a cascade of reactions
+(`../../short-drama-core/reference/grammar-faceslap.md`); `comedy` segments set up every punchline and give it laugh room
+(`../../short-drama-core/reference/grammar-comedy.md`). Each grammar adds its line to the prompt (`Action:` / `Payoff:` /
 `Comedy:`).
 
 ### Foreground
@@ -205,7 +215,7 @@ default and more than two camera moves per segment is showing off.
 Get the skeleton:
 
 ```bash
-node {baseDir}/scripts/short-drama.mjs prompt <project> segment E01-01
+$SD prompt <project> segment E01-01
 ```
 
 It prints the parts that are derived and gated verbatim — the alignment line, `[Shot k] At
@@ -371,12 +381,6 @@ segment is rejected, retry, then trim — do not go hunting for a forbidden word
 To bisect anyway, use a scratch video node at `-d 2`, 480P: free when rejected, ~30 credits when it
 passes, and sample each fragment several times because one pass proves nothing.
 
-**Last resort: the uncensored twin.** `wan-3.0-ref-uncensored` (MuleRouter, no green-net) takes the
-same prompt and the same 10 images + 5 videos + 5 audios, at ~1.3× the price; note that it bills the
-reference-video seconds as well as the output. Switch a stuck segment to it only with the
-Producer's approval, and only after retry-then-trim has failed. `short-drama.mjs` does not know it
-as a mode, so set it as the node's model directly.
-
 ## Sheets mode — no storyboard images (the default)
 
 `params.references: sheets` drops stage 5's image generation entirely: the video node references
@@ -438,9 +442,10 @@ score. So by default (`params.audioTrack: post`) **the clips carry no music**: t
 says `No music.` (H3 `non_diegetic_music: N/A`, Wan `无配乐`), keeps the dialogue, the ambience and
 the in-picture sfx, and drops every sfx marked `post: true` (stingers, risers, whooshes, impact
 hits — sound design outside the story world). The storyboard still writes `sound.music` (intent and
-cues) and the `post: true` hits: they are the **spotting notes**. When every clip is in, cut the
-episode as in `edit-tools.md` (FilmCraft, or ffmpeg if `filmcraft-cli` is missing; the `.fcproj`
-stays in the project), and score that locked picture as one piece on its timecode:
+cues) and the `post: true` hits: they are the **spotting notes**. When every clip is in, the Operator
+cuts the episode as in `../../short-drama-core/reference/edit-tools.md` (FilmCraft, or ffmpeg if
+`filmcraft-cli` is missing; the `.fcproj` stays in the project), and the Sound Designer scores that
+locked picture as one piece on its timecode:
 
 ```bash
 $SD prompt <project> score E01            # planned spotting sheet: SMPTE rows + ≤120 s Seed Audio sections
@@ -450,7 +455,7 @@ The sheet lays the segments end to end — scene beds (BGE), every line (where t
 segment's music cues at their episode time, the `post` sound design, the sfx already in the clips
 (never doubled) and the hook / turns / 爽点 / cliff as the 起承转合 anchors. It is the *planned*
 timeline: the Sound Designer conforms it to the edit's real cuts
-(`mix-over-video.md`) before any prompt is written. `manifest`
+(`../../short-drama-sound/reference/mix-over-video.md`) before any prompt is written. `manifest`
 then asks for the episode's `wji.assets.edit` and `wji.assets.mix`.
 
 ### Per-segment soundtrack node (`audioTrack: bed` / `full`)
@@ -463,8 +468,8 @@ music goes into the clip prompt too; the prompt is derived — not written — f
 the cut timing:
 
 ```bash
-node {baseDir}/scripts/short-drama.mjs prompt <project> audio E01-05            # bed (default)
-node {baseDir}/scripts/short-drama.mjs prompt <project> audio E01-02 --full     # + the lines, in the @AudioN voices
+$SD prompt <project> audio E01-05            # bed (default)
+$SD prompt <project> audio E01-02 --full     # + the lines, in the @AudioN voices
 ```
 
 ```
@@ -526,14 +531,14 @@ recorded in the episode's `wji.displayNodes` as `"C01:voice"`, exactly like the
 ```bash
 wji fs mkdir <shot folder> E01                                                   # bind --ep 1 wji.shotFolderId
 wji dataset new <shot/E01> "E01-01" -t shot -d "<scene · seconds>"               # bind --ep 1 storyboard.segments.E01-01.wji.datasetId
-node {baseDir}/scripts/short-drama.mjs render <project> segment E01-01 > /tmp/E01-01.md
+$SD render <project> segment E01-01 > /tmp/E01-01.md
 wji fs set <id> --merge content=@/tmp/E01-01.md --merge viewMode=content --merge video_prompt=@/tmp/E01-01-prompt.txt
-node {baseDir}/scripts/short-drama.mjs bind <project> --ep 1 storyboard.segments.E01-01.wji.nodes.keyframes.0 <nodeId>
-node {baseDir}/scripts/short-drama.mjs manifest <project> --ep 1                 # must be clean before the episode is "done"
+$SD bind <project> --ep 1 storyboard.segments.E01-01.wji.nodes.keyframes.0 <nodeId>
+$SD manifest <project> --ep 1                 # must be clean before the episode is "done"
 ```
 
 ## Gates
 
 `segments` · `timing` (durations, the speech lead-in **and** the reference caps) · `cut-content` ·
-`photography` · `video-prompt` · `shot-purpose` · `framing-axis` · `continuity` · `motion` · `sound`
-· `visual-plan` · `text-policy` · `prompt-hygiene` · `audio-track` · `storyboard-advice` (advisory).
+`photography` · `video-prompt` · `shot-purpose` · `boundary-contrast` · `framing-axis` · `continuity` · `motion` · `sound`
+· `visual-plan` · `text-policy` · `prompt-hygiene` · `ref-binding` · `audio-track` · `boundary-contrast-episode` (advisory) · `storyboard-advice` (advisory).

package/skill/short-drama/scripts/selftest.mjs

@@ -15,7 +15,7 @@ import {
   renderSegment, runGates, seedScript, seedStoryboard, seedanceAnchors, slug, timestamp, writeJsonFile,
   wanLegendLine, wanSheetLegendLine, wanShotHeader, segmentReferences, imageReferences, audioReferences, voiceSamplePrompt, voiceSampleSeconds, nonWhitespace,
   speechDirection, cameraPhrase, lightPhrase, idlePhrase, idleSentence, IDLE_MAX_CHARS, eyelinePhrase, eyelineValid, onlyInFramePhrase, overShoulderPhrase, sidesLine, foregroundPhrase, foregroundBand, foregroundForLook, focalOf, LIGHT_DIRECTIONS, identityOf, isEnglish,
-  renderGuideline, renderDialogue, scriptSelfCheck, beatOffsets, turnPoints, parseAge, talkAndAction, normalizeRegister, REGISTERS, REGISTER_ACCENT,
+  renderGuideline, renderDialogue, seedDialogue, applyDialogue, dialogueRefs, DIALOGUE_GUIDES, corpusAge, scriptSelfCheck, beatOffsets, turnPoints, parseAge, talkAndAction, normalizeRegister, REGISTERS, REGISTER_ACCENT,
   cutStart, segmentCharacters, keyScenes, shotTexts, motionSentence, cameraClause, PURPOSE_KINDS, ANGLES, HEIGHTS, NO_SUBTITLES, LIPS_CLOSED,
   audioPrompt, musicOf, cueSeconds, AUDIO_MODEL, AUDIO_MAX_CHARS, AUDIO_MAX_SECONDS, scoreSheet, smpte,
   VIDEO_MODELS, VIDEO_MODES, DEFAULT_PARAMS, videoModel, videoResolutionFor, nearestResolution, segmentPlan, videoReferences,
@@ -262,6 +262,35 @@ const breaks = (gateId, project, episode, needle) => {
   const p5 = clone(PROJECT); p5.props[0].states = [];
   breaks('prop-design', p5, null, 'state');
 }
+{
+  const missing = clone(PROJECT);
+  delete missing.scenes[0].condition;
+  delete missing.scenes[0].conditionReason;
+  breaks('scene-design', missing, null, 'condition must be new, lived-in or worn');
+  const fresh = clone(PROJECT);
+  fresh.scenes[0].condition = 'new';
+  fresh.scenes[0].conditionReason = 'the organisers finished this set this morning';
+  breaks('scene-design', fresh, null, 'condition is new but');
+  const clean = clone(PROJECT);
+  clean.scenes[1].condition = 'new';
+  clean.scenes[1].conditionReason = 'a pavilion built for this episode and struck the next day';
+  const scrub = (text) => String(text || '').replace(/\b(worn|rust|rusty|rusted|faded|chipped|torn|frayed|peeling|stain|stained|stains)\b/gi, 'plain').replace(/殘舊|残旧|生鏽|生锈|褪色|剝落|剥落/g, '');
+  for (const a of clean.scenes[1].anchors) { a.name = scrub(a.name); a.desc = scrub(a.desc); }
+  clean.scenes[1].image.prompt = scrub(clean.scenes[1].image.prompt);
+  clean.scenes[1].image.sheet = scrub(clean.scenes[1].image.sheet);
+  for (const l of clean.scenes[1].lighting) l.prompt = scrub(l.prompt);
+  passes('scene-design', clean, null);
+  const ban = clone(PROJECT);
+  ban.scenes[0].image.negativePrompt += ', brand-new, showroom-clean';
+  breaks('scene-design', ban, null, 'only condition worn may ban');
+  const propMissing = clone(PROJECT);
+  delete propMissing.props[0].conditionReason;
+  breaks('prop-design', propMissing, null, 'conditionReason');
+  const propNew = clone(PROJECT);
+  propNew.props[0].condition = 'new';
+  propNew.props[0].conditionReason = 'a drive the organisers just issued';
+  breaks('prop-design', propNew, null, 'condition is new but');
+}
 
 // ── script gates ────────────────────────────────────────────────────────────
 {
@@ -479,7 +508,8 @@ const breaks = (gateId, project, episode, needle) => {
   const results = runGates(makeContext(PROJECT, { 1: e }));
   const adv = results.find((r) => r.id === 'dialogue-register');
   ok(adv.advisory && adv.failures.length === 0 && adv.warnings.length > 0, 'advisory findings come back as warnings, not failures');
-  ok(results.filter((r) => !r.advisory && r.stage !== 'storyboard').every((r) => !r.failures.length), 'a register note never fails validate (the storyboard is stale on purpose here)');
+  ok(results.filter((r) => !r.advisory && r.stage !== 'storyboard' && r.id !== 'dialogue-review').every((r) => !r.failures.length), 'a register note never fails validate (the storyboard is stale on purpose here)');
+  ok(results.find((r) => r.id === 'dialogue-review').failures.some((m) => m.includes('differs from the reviewed one')), 'an edited line is no longer reviewed — dialogue-review asks for it again');
   const p2 = clone(PROJECT); p2.params.register = '粤语';
   ok(failures('dialogue-register', p2, E01).some((m) => m.includes('书面中文硬转')), 'a 粤语 drama with written-Chinese lines is noted');
   const p3 = clone(PROJECT); p3.params.register = '古装';
@@ -1681,19 +1711,23 @@ const breaks = (gateId, project, episode, needle) => {
   const script = renderScript(PROJECT, E01);
   ok(script.includes('穿雨衣的男人（') && script.includes('VO'), 'script markdown names speakers and VO');
   ok(script.includes('△（0-3秒）') && script.includes('【爽点标记】') && script.includes('【钩子标记】'), 'script markdown is in the 短剧 episode format with derived time marks');
-  ok(script.includes('## 本集功能') && script.includes('## 本集任务') && script.includes('## 创作自检') && script.includes('16/16'), 'script markdown carries the episode design and a full self-check');
+  ok(script.includes('## 本集功能') && script.includes('## 本集任务') && script.includes('## 创作自检') && script.includes('18/18') && script.includes('对白是否已按语体 guide 逐句校对'), 'script markdown carries the episode design and a full self-check');
   const guide = renderGuideline(PROJECT);
   ok(guide.includes('创作指引') && guide.includes('## 9. 本项目绝对要注意的重点') && !guide.includes('{{'), 'guideline markdown is complete with no placeholders');
   ok(guide.includes(PROJECT.outline.brief.logline), 'guideline carries the logline');
-  const dlg = renderDialogue(PROJECT, E01);
+  const blank = clone(E01); delete blank.dialogueReview;
+  const dlg = renderDialogue(PROJECT, blank);
   eq((dlg.match(/^\| [^|]*：/gm) || []).length, 13, 'dialogue worksheet has one row per line');
   ok(dlg.includes('禁用：其实、我觉得'), 'dialogue worksheet carries the speaker\'s speech rules');
+  ok(dlg.includes('lang-zh-cn.md') && dlg.includes('ref.mjs --lang zh-cn list --age elder'), 'dialogue worksheet points each speaker at their guide and corpus query');
+  const filled = renderDialogue(PROJECT, E01);
+  ok(filled.includes('| 修改幅度 | 轻修 |') && filled.includes('（保留）') && filled.includes('## 自检'), 'a filled review renders as the 对白校对 table');
   const c1 = renderCharacter(PROJECT, 'C01');
   ok(c1.includes('## 人物圣经') && c1.includes('### 过去的关键选择') && c1.includes('## 人物关系网') && c1.includes('### 写作备忘'), 'character markdown has the bible sections');
   const out = renderOutline(PROJECT);
   ok(out.includes('## 创作简报') && out.includes('## 全剧结构') && out.includes('## 分集目录'), 'outline markdown has brief, structure and episode index');
   const check = scriptSelfCheck(PROJECT, E01);
-  eq(check.score, 16, 'fixture episode scores 16/16');
+  eq(check.score, 18, 'fixture episode scores 18/18');
   const segMd = renderSegment(PROJECT, E01, 'E01-02');
   ok(segMd.includes('| 00:02.000 |') && segMd.includes('integrated_multimodal_description'), 'segment markdown has cut table and prompt');
   ok(segMd.includes('### SHOT 1 · establish') && segMd.includes('| 唯一动作 |') && segMd.includes('| 视觉依据 |') && segMd.includes('轴线：'), 'segment markdown has the SHOT blocks, the axis and the sound line');
@@ -1701,6 +1735,86 @@ const breaks = (gateId, project, episode, needle) => {
   assert.throws(() => renderCharacter(PROJECT, 'C99'), /no character/, 'render refuses unknown ids');
 }
 
+// ── dialogue review (w-film-dialogue-editor) ────────────────────────────────
+{
+  passes('dialogue-review', PROJECT, E01);
+  ok(GATES.find((g) => g.id === 'dialogue-review').advisory === false, 'dialogue-review blocks');
+  eq(DIALOGUE_GUIDES['粤语'].lang, 'zh-hk', '粤语 reads the zh-hk guide and corpus');
+  eq(DIALOGUE_GUIDES['古装'].corpus, false, '古装 has a guide but no corpus');
+  eq(corpusAge(24), 'young', 'a 24-year-old queries the young band');
+  eq(corpusAge(61), 'elder', 'a 61-year-old queries the elder band');
+  const none = clone(E01); delete none.dialogueReview;
+  breaks('dialogue-review', PROJECT, none, 'seed <project> dialogue');
+  const pOff = clone(PROJECT); pOff.params.dialogueReview = 'off';
+  passes('dialogue-review', pOff, none);
+  const lvl = clone(E01); lvl.dialogueReview.level = '';
+  breaks('dialogue-review', PROJECT, lvl, 'level');
+  const diag = clone(E01); diag.dialogueReview.diagnosis.subtext = '';
+  breaks('dialogue-review', PROJECT, diag, '潜台词核心');
+  const guide = clone(E01); guide.dialogueReview.guides = [];
+  breaks('dialogue-review', PROJECT, guide, 'lang-zh-cn.md');
+  const yue = clone(PROJECT); yue.characters.find((c) => c.id === 'C02').bible.speech.register = '粤语';
+  breaks('dialogue-review', yue, E01, 'lang-zh-hk.md');
+  const miss = clone(E01); miss.dialogueReview.rows.pop();
+  breaks('dialogue-review', PROJECT, miss, 'no review row');
+  const stale = clone(E01); stale.scenes[1].flow[2].line = '又轮到你值夜班。';
+  breaks('dialogue-review', PROJECT, stale, 'differs from the reviewed one');
+  const noIssue = clone(E01); noIssue.dialogueReview.rows[0].issue = '';
+  breaks('dialogue-review', PROJECT, noIssue, 'issue is empty');
+  const noWhy = clone(E01); noWhy.dialogueReview.rows[0].revised = '帮我收着，明天有人拿。'; noWhy.scenes[0].flow[1].line = '帮我收着，明天有人拿。';
+  breaks('dialogue-review', PROJECT, noWhy, 'without a reason');
+  const mood = clone(E01); mood.dialogueReview.rows[0].note = '自然一点';
+  breaks('dialogue-review', PROJECT, mood, 'a mood, not an action');
+  const emo = clone(E01); emo.dialogueReview.rows[1].note = '生气';
+  breaks('dialogue-review', PROJECT, emo, 'a mood, not an action');
+  const check = clone(E01); check.dialogueReview.selfCheck = check.dialogueReview.selfCheck.slice(0, 2);
+  breaks('dialogue-review', PROJECT, check, '自检清单');
+  const checkNo = clone(E01); checkNo.dialogueReview.selfCheck[0] = { item: '读出声', ok: false, note: '' };
+  breaks('dialogue-review', PROJECT, checkNo, 'failed with no note');
+  const ghost = clone(E01); ghost.dialogueReview.rows.push({ scene: 1, beat: 1, speaker: 'C01', original: 'x', issue: 'x', revised: 'x', reason: '', note: '逼' });
+  breaks('dialogue-review', PROJECT, ghost, 'no longer a line');
+
+  // seed keeps filled rows for unchanged lines and opens only the edited one
+  const edited = clone(E01); edited.scenes[1].flow[2].line = '又轮到你值夜班。';
+  const reseeded = seedDialogue(PROJECT, edited, { skillDir: null });
+  eq(reseeded.rows.length, 13, 're-seed keeps one row per line');
+  eq(reseeded.rows.filter((r) => !r.issue).length, 1, 're-seed reopens only the edited line');
+  eq(reseeded.level, '轻修', 're-seed keeps the level and diagnosis');
+  eq(seedDialogue(PROJECT, edited, { skillDir: null, force: true }).rows.filter((r) => !r.issue).length, 13, '--force resets every row');
+  ok(!('refs' in reseeded), 'the stored review carries no machine paths');
+  const refs = dialogueRefs(PROJECT, E01, { skillDir: '/x' });
+  ok(refs.speakers.every((x) => x.guide === '/x/references/lang-zh-cn.md'), 'every speaker gets the zh-cn guide');
+  ok(refs.speakers.find((x) => x.id === 'C02').query.includes('--age elder'), "the sixty-year-old's corpus query is the elder band");
+  ok(!refs.speakers.some((x) => x.id === 'VO'), 'VO is not a speaker with a guide');
+
+  // apply writes revised lines and deliveries back, then the gate is green again
+  const app = clone(E01); app.dialogueReview.rows[0].revised = '帮我收着，明天有人拿。'; app.dialogueReview.rows[0].reason = '更短，一口气说完'; app.dialogueReview.rows[0].delivery = '压着嗓子，塞完就走';
+  breaks('dialogue-review', PROJECT, app, 'differs from the reviewed one');
+  eq(applyDialogue(app), 2, 'apply writes the line and the delivery');
+  eq(app.scenes[0].flow[1].line, '帮我收着，明天有人拿。', 'the revised line is in the script');
+  passes('dialogue-review', PROJECT, app);
+  const bad = clone(E01); bad.dialogueReview.rows[0].revised = '';
+  assert.throws(() => applyDialogue(bad), /revised is empty/, 'apply refuses an empty line'); passed += 1;
+  ok(scriptSelfCheck(PROJECT, none).rows.some((r) => r[0].includes('逐句校对') && r[1] === false), 'the 创作自检 says 否 without a review');
+
+  // seed / apply through the CLI
+  const dir = mkdtempSync(join(tmpdir(), 'sd-dlg-'));
+  try {
+    writeFileSync(join(dir, 'project.json'), JSON.stringify(PROJECT));
+    spawnSync('mkdir', ['-p', join(dir, 'episodes')]);
+    writeFileSync(join(dir, 'episodes/E01.json'), JSON.stringify(none));
+    const engine = join(here, 'short-drama.mjs');
+    const r1 = spawnSync(process.execPath, [engine, 'seed', dir, 'dialogue', '--ep', '1'], { encoding: 'utf8' });
+    eq(r1.status, 0, `seed dialogue runs: ${r1.stderr}`);
+    ok(r1.stdout.includes('13 lines (13 to review)') && r1.stdout.includes('lang-zh-cn.md'), 'seed dialogue prints the guide per speaker');
+    const r2 = spawnSync(process.execPath, [engine, 'apply', dir, 'dialogue', '--ep', '1'], { encoding: 'utf8' });
+    eq(r2.status, 0, `apply dialogue runs: ${r2.stderr}`);
+    ok(r2.stdout.includes('0 change(s)'), 'apply on an untouched review changes nothing');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
 // ── manifest & bind ─────────────────────────────────────────────────────────
 {
   const items = manifest(PROJECT, { 1: E01 });
@@ -2414,10 +2528,41 @@ const breaks = (gateId, project, episode, needle) => {
   eq(slug('E01-01 便利店 / 夜班'), 'e01-01-便利店-夜班', 'slug keeps CJK, drops separators');
 }
 
+// ── ref-binding (参考图绑定) ─────────────────────────────────────────────────
+{
+  // The picture plan has to survive into the delivery text: a legend line that names WHO/WHAT each
+  // picture is, a "not its composition / its people" clause on everything that is not a person, and
+  // the label named again inside every shot that depends on it.
+  const p = clone(PROJECT);
+  p.params.video = 'seedance';
+  p.params.references = 'sheets';
+  p.params.videoDuration = 'auto';
+  const e = clone(E01);
+  const seg = e.storyboard.segments[3];
+  const refs = segmentReferences(p, e, seg).filter((r) => r.kind === 'image');
+  const legend = refs.map((r) => `${r.label} is ${r.use}.`).join('\n');
+  const shots = seg.cuts
+    .map((c, k) => `Shot ${k + 1} (${k}.0\u2013${k + 1}.0 s, medium shot, Static Shot): ${refs.map((r) => r.label).join(' and ')} hold.`)
+    .join('\n');
+  const good = `${legend}\n\n${shots}`;
+  const bound = clone(e);
+  bound.storyboard.segments[3].prompt = good;
+  eq(failures('ref-binding', p, bound).filter((m) => m.startsWith('E01-04')).length, 0, 'ref-binding passes a fully bound prompt');
+  const generic = clone(e);
+  generic.storyboard.segments[3].prompt = good.replace(/@image2 is the character sheet of [^\n]*/, '@image2 is the character sheet of one person in this segment \u2014 match face, hair and clothes exactly.');
+  breaks('ref-binding', p, generic, 'never says WHICH person');
+  const noNegative = clone(e);
+  noNegative.storyboard.segments[3].prompt = good.replace(/@image1 is the environment[^\n]*/, '@image1 is the environment \u2014 match its layout, materials and wear exactly.');
+  breaks('ref-binding', p, noNegative, 'never says what NOT');
+  const unused = clone(e);
+  unused.storyboard.segments[3].prompt = `${legend}\n\n${shots.replaceAll('@image2', 'a person')}`;
+  breaks('ref-binding', p, unused, 'used in no shot');
+}
+
 // ── gate inventory (crew engine) ────────────────────────────────────────────
 {
-  eq(GATES.length, 69, 'gate count');
-  eq(GATES.filter((g) => !g.advisory).length, 63, 'hard gate count');
+  eq(GATES.length, 71, 'gate count');
+  eq(GATES.filter((g) => !g.advisory).length, 65, 'hard gate count');
   eq(GATES.filter((g) => g.advisory).length, 6, 'advisory gate count');
   ok(!GATES.find((g) => g.id === 'boundary-contrast').advisory, 'boundary-contrast is hard');
   ok(GATES.find((g) => g.id === 'boundary-contrast-episode').advisory, 'boundary-contrast-episode is advisory');
@@ -2539,8 +2684,8 @@ const breaks = (gateId, project, episode, needle) => {
   const results = runGates(makeContext(PROJECT, { 1: E01 }));
   const rep = formatGates(results);
   eq(Object.keys(rep).sort().join(','), 'advisory,failed,hard,lines,notes,summary,text', 'formatGates shape');
-  eq(rep.summary, '✓ 63 gate(s) passed, 6 advisory (1 note)', 'fixture summary');
-  eq(rep.failed, 0, 'nothing failed'); eq(rep.hard, 63, 'hard count'); eq(rep.advisory, 6, 'advisory count');
+  eq(rep.summary, '✓ 65 gate(s) passed, 6 advisory (1 note)', 'fixture summary');
+  eq(rep.failed, 0, 'nothing failed'); eq(rep.hard, 65, 'hard count'); eq(rep.advisory, 6, 'advisory count');
   // The fixture now raises one advisory (E01-03 carries the 爽点 and is not cut as faceslap),
   // exactly as it does in the wji-cli copy — advisory lines print, failures still must not.
   eq(rep.lines.filter((l) => l.includes('✗')).length, 0, 'a green run prints no failed gates');