@oh-story/dsh 0.1.0

package/lib/drama/skills/short-drama-storyboard/references/shot-craft.md

@@ -0,0 +1,192 @@
+# 镜头设计方法
+
+## 规则分级
+
+- `structural_invariant`：可以直接检查的结构要求，例如每段原文都有处理结果、引用可以解析；格式错误可以阻断。
+- `reviewed_invariant`：必须守住、但要结合证据判断的内容要求，例如镜头没有改写剧本动作。
+- `craft_default`：通常有效的起步方法；有明确的戏剧理由时可以调整。
+- `taste_option`：创作者或视觉方向已经接受的风格选择，不能仅因不同于示例就判错。
+
+## 目录
+
+1. [先落实原文，再追求画面](#先落实原文再追求画面)
+2. [镜头目的](#镜头目的)
+3. [场面调度与地理](#场面调度与地理)
+4. [景别与摄影机动机](#景别与摄影机动机)
+5. [时长与切镜](#时长与切镜)
+6. [常见问题](#常见问题)
+7. [审查问题](#审查问题)
+
+## 先落实原文，再追求画面
+
+`SHT-01` 要求每个与制作有关的剧本段都有明确处理：由镜头落实、有理由地省略，或因
+新的观众体验而有意重复。
+
+先把剧本段与镜头对应起来，再设计镜头。原文落实表是责任清单，不是“一段一镜”公式。
+连续表演和空间关系能守住原意时，几段原文可以合在一镜；揭示、反应、证据细节或空间
+变化很重要时，一段原文也可以由几镜承担。
+
+已接受的原文落实表要保存完整的 `shot_refs`，不能只写裸镜头 ID。文件的 `sources` 为每个
+上游快照声明一次负责人与准确文件，每条引用再用 `src` 指向这条声明并
+写上 `record_id`，这样才能知道审查的是哪一版。同一文件内部的关系可以用 `*_ids`；
+跨文件关系必须用 `*_refs`，以便来源改变后发现过期引用。
+
+重复拍同一段内容，只有在第二次带来新的观众体验时才成立，例如新增反应、矛盾、
+此前保留的证据或对前镜的新理解；不能因为第一次对应关系被忘了就重复。
+
+### 动作落实表
+
+**`SHT-08 · reviewed_invariant`**： 每个有权威来源的动作只有一个主要落实镜头；其他
+镜头若再次涉及该动作，必须增加反应、细节或对原信息的新理解。
+
+原文落实数量只能证明“某段原文被引用”，不能证明动作没有提前、重复或遗漏。对转手、
+开门、受伤、揭面、拿出证物等动作，另记：
+
+| 来源动作 | 主要落实镜头 | 动作前事实 | 动作后事实 | 其他镜头的作用 |
+|---|---|---|---|---|
+| 右手从衣内取令牌 | SHOT-02 | 令牌在衣内 | 右手持令牌 | SHOT-03 只展示纹样和接收者反应 |
+
+- 只有主要落实镜头可以把状态从动作前改成动作后。
+- 前一镜的结束状态不得在没有来源动作时提前变成动作后状态。
+- 后一镜已经从动作后状态开始时，运动规格不得再完整表演一次该动作。
+- 其他镜头要写清自己负责细节、反应还是重新解释，不能成为第二个主要落实镜头。
+
+## 镜头目的
+
+`SHT-02` 要求镜头守住来源原意，并说明观众或人物在本镜结束时发生了什么变化。
+只有漂亮画面、没有戏剧职责的镜头，不能通过内容审查。
+
+按以下顺序设计：
+
+1. 找出来源中的关键动作：行动、台词、发现、拒绝、转手或揭示。
+2. 说明观众或人物因此发生什么变化。
+3. 决定本镜主要从谁的体验组织画面。
+4. 确定开始和结束时必须看见什么。
+5. 最后才选择景别、摄影机行为和切镜点。
+
+镜头可以负责建立空间、让观众站到某个人物一边、展示证据、暂缓信息、转移权力、
+表现反应，或让后果无法回避。“中景展示人物说话”不算足够的镜头目的。
+
+### 观众可见性 (`SHT-12`)
+
+构图同时决定观众此刻能知道什么。每个事实单独建立一条 `audience_visibility`：绑定准确
+的 `source_ref`，选择 `show_now` 或 `withhold_now`，写明可见或可听的载体，并分别写出
+揭示条件、保护方法和理由。同一镜中的不同事实可以在不同时间放出。
+
+背影、只露腿部的入场、门缝、前景遮挡、延迟对焦，以及**逆光成剪影或压暗到只剩轮廓**，
+都可以用于保护剧本保留的揭示。用光保护时不改光源身份与方向，只声明人物落在明区还是
+暗区，并把该选择写进本镜排除项防止后续漂移——否则人物正面入场却要求不给身份时，
+本环节没有合法写法，执行端会直接给一张清晰正脸。
+如果它们提前暴露身份或证据，就是失败。反过来，本镜若负责展示证据或听者的关键反应，
+就不能为了画面好看而遮住其载体。神秘感不是默认加分项；审查者同时核对剧本允许展示
+什么，以及本镜必须交代什么。
+
+## 场面调度与地理
+
+把场景写成可以行动的空间：
+
+- 入口、出口和固定锚点。
+- 前景、中景、后景区域。
+- 谁能看见或接近什么。
+- 人物面向与视线关系。
+- 轴线工作侧和屏幕运动方向。
+- 双手、道具归属和转手路径。
+
+场面调度表现人物策略。靠近可以施压或寻求结盟；转身可以拒绝；占住出口可以控制；
+碰触证据可以暴露知情。不要只为增加运动而让人物无理由走动。
+
+跨轴本身不是错误；没有动机又让空间难以理解才是问题。跨轴时可以使用中性过渡镜头、
+人物在同一镜内穿轴、有意制造主观错乱，或重新建立空间。
+
+画面文字必须服从资产负责人确定的文字政策。镜头和关键帧通过 `text_treatment_refs`
+指向准确政策字段，可以决定文字是否可见、大小、角度和对焦，但不能静默编造文案，
+也不能改写 `exact_readable`、`graphic_only`、`no_readable_text` 或待定状态。候选预览只能
+引用候选政策，并且不能直接交付。
+
+## 景别与摄影机动机
+
+`SHT-04` 要求景别或摄影机行为因注意、压力、观众立场、揭示或节奏变化而改变，
+不能为了装饰每一拍而变化。
+
+- **远景**：交代地理、人物与环境的力量对比，或让人物被空间吞掉；信息靠轮廓、方位和
+  距离读出，不要指望这一档承担表情。
+- **全景**：建立空间、孤立感、群体权力或同时发生的后果。
+- **中景**：表现互动、手势、双人策略和清楚的调度。
+- **中近景**：对话距离的双人，或仍然保留手部的单人：比中景少一层环境，比近景多留出
+  调度余地；一场停在工作景别时的对切多数落在这一档。
+- **近景**：表现决定、证据、被藏住的反应或无法撤回的认识。
+- **特写**：把一张脸、一只手或一处伤单独提出来，让某个反应、破绽或细微动作成为本镜
+  唯一事实；代价是暂时切掉空间参照，用它就要接受观众此刻读不到周围发生了什么。
+- **大特写**：只留眼睛、嘴、指节或物件上的一处细节；用于观众必须看清、而近景会淹没的
+  单一证据或生理反应。它切掉的信息最多，因此要有明确的“非看不可”理由。
+- **细节镜头**：展示已经建立意义的关键物件或动作。
+
+近景和特写是中文分镜里最常用的两档，不是留给高潮的稀缺资源；同样，大特写也不是被
+禁止的景别。要防的是**把景别当情绪音量旋钮**：情绪词一升级就换更紧的景别，本镜到底
+要观众读到什么反而没人回答。判断标准始终是必须被读到的信息存在于哪个尺度——证据在
+指节上就给大特写，后果在两人距离上就不该切近。
+
+只有注意或关系发生变化时才改变景别和角度。场面声音变大，不等于镜头必须从全景一路
+推到大特写。反过来，一旦决定切镜，新镜就要在景别、角度或人物关系里至少改变一项；
+相邻两镜完全同景别、同角度、同关系时，这次切镜没有职责，应当改变收放或并回一镜。
+
+一个时间段内选择一套连贯的摄影机行为：
+
+- 固定机位用于观察、紧张、仪式或受困。
+- 摇镜或俯仰用于揭示信息或转移注意。
+- 前移或后移用于改变亲近、压力或人物认识。
+- 跟拍用于人物移动本身带有策略意义的场面。
+- 环绕用于关系或空间在原地被重新评估：绕过去才看得到的另一面、被围住的处境、
+  两人相对位置在不移动的情况下改变意义；没有这层理由时它只是装饰性运动。
+- 升降（摇臂）用于高度本身携带意义：升起交出全局或结局，落下把观众接进人物所在的
+  高度；不为“开场要大气”而升降。
+- 手持用于创作者已经接受的身体不稳或现场感。
+
+没有明确切换时，不要在同一时间段同时要求固定和移动。
+
+## 时长与切镜
+
+### 短镜头的动作量 (`SHT-03`)
+
+作为 `craft_default`，可以先从一个主要动作开始，再保留让观众读懂后果所需的反应。
+只有连续表演、空间、时长和镜头目的都仍然清楚时才合并更多内容。这是起步方法，
+不是固定动作数量检查。
+
+时长要给动作、表演、对白和反应留出可读空间。明确的对白长度和计时动作可以作为证据；
+一般动作量是否过多，应由审查者结合本镜判断，不能用通用的每秒字数阻断。
+
+在变化处切镜：新信息、新目光、新决定、新空间关系、新威胁、新证据或节奏变化。
+不要只为换角度而重复同一个动作。给反应留下足够时间，让观众读懂后果。
+
+## 视觉方向选择 (`SHT-07`)
+
+焦段语言、节奏、固定机位、手持或形式化调度属于 `taste_option`，读取创作者已接受的
+视觉方向。审查它是否服务本镜，不强制所有项目使用同一套风格。
+
+## 相连边界 (`CON-01`)
+
+本镜已接受的结束边界必须与下一镜已接受的开始边界一致；若不一致，负责产物必须声明
+修订或过渡。不得用摄影机描述掩盖边界冲突。
+
+## 常见问题
+
+- 镜头表只是改写剧本句子，没有说明观众怎样观看或获得什么变化。
+- 用匿名“人物”代替准确的已接受资产。
+- 一镜跨越地点或时间，却没有蒙太奇或省略依据。
+- 保留了对白，却删掉承担后果的反应。
+- 人物或道具在切镜后无原因换位。
+- 每句情绪台词都变成大特写（问题在“情绪升级=景别收紧”的条件反射，不在大特写本身）。
+- 相邻两镜同景别、同角度、同关系，切了等于没切。
+- 摄影机指令冲突，或运动没有注意变化的理由。
+- 套话式布光替代真实空间锚点。
+- 把外部批量制作单位误当成剪辑镜头本身。
+
+## 审查问题
+
+- 本镜落实、省略或重复了哪些剧本段？
+- 本镜结束时改变了什么？
+- 为什么选择这个景别和摄影机行为？
+- 每个人物能否在当前空间中合理站立、看见和移动？
+- 是否绑定了准确的造型、观察视角、道具状态、双手状态和文字政策？
+- 结束边界是否为下一镜提供清楚的开始状态？
+- 删除或合并本镜，会不会丢失故事意义？

package/lib/drama/skills/short-drama-storyboard/references/shot-revision-identity.md

@@ -0,0 +1,29 @@
+# 镜头修订与稳定身份
+
+镜头 ID 表示同一个编辑/导演决定的连续身份，不等于列表位置，也不等于外部制作任务编号。
+修订时先判断镜头的叙事职责是否仍是同一个，再决定保留、创建或 retire。
+
+## 身份规则
+
+- **重排**：只改变顺序，镜头目的与边界职责不变时保留原 ID；刷新依赖顺序与相邻边界。
+- **插入**：新增一个独立注意或戏剧职责时创建新 ID；不要给后续所有镜头重新编号。
+- **内容修订**：同一镜头目的下调整构图、blocking 或边界，保留 ID 并重新发布。
+- **拆分**：原镜头被两个或更多独立职责取代时，retire 旧 ID，为每个新镜头创建新 ID；记录
+  `revision_lineage`，不把旧 ID 偷给其中一个子镜头。
+- **合并**：多个旧镜头被一个新决定取代时，retire 全部旧 ID，创建新 ID，并记录来源集合。
+- **恢复**：retire 的 ID 不复用于无关镜头；需要恢复同一职责时用 lineage 显式说明。
+
+普通新镜只需要稳定 `shot_id`；没有 predecessor 或 retired IDs 时省略 `revision_lineage`，
+不保存 `mode: new` 和空数组来重复本段规则。
+拆分、合并或恢复旧职责时，从
+[`revision-lineage.fragment.json`](../assets/revision-lineage.fragment.json) 插入统一结构；同一 shot 文件
+内的前身与 retired 关系使用稳定 ID，不伪造指向本文件自身的引用。
+
+## 每次拆分、合并或重排后的对账
+
+重新核对 coverage 的每条 `shot_refs`、场次视觉计划投影、关键帧、motion、容器成员、相邻
+start/end boundary、总时长与审查记录。旧 ID 保留在 lineage / retire 记录中用于解释历史，
+不能继续被 active coverage 或交付容器引用。
+
+脚本可以检查引用、集合和算术；“是否仍是同一个导演决定”由 agent 根据镜头目的、信息变化、
+表演所有权和边界职责判断，不能用文本相似度或数组位置硬判。

package/lib/drama/skills/short-drama-storyboard/references/stage-contract.md

@@ -0,0 +1,110 @@
+# 分镜阶段契约
+
+## 目录
+
+- [独立运行与项目集成](#独立运行与项目集成)
+- [所有权边界](#所有权边界)
+- [制作形态需要什么](#制作形态需要什么)
+- [参考媒体与补拍](#参考媒体与补拍)
+- [本阶段规则](#本阶段规则)
+
+本文件是本技能的自包含契约：预检、所有权、形态输入与规则表都在这里，
+不需要读取其他技能的文件。
+
+## 独立运行与项目集成
+
+本技能可以单独安装并运行；下面几条说明项目工具存在时怎样集成。
+
+1. **读取直接输入**：只读取用户明确提供或当前任务实际需要的文件，不批量加载整个项目。
+2. **可选项目集成**：若存在 `short-drama.json` 且 core 项目工具可用，可以运行
+   `python3 <core>/scripts/project_tool.py status <project>`，使用返回的目录布局和语言设置；
+   core 不可用时，直接基于已提供输入产出本阶段文件。
+3. **可选发布生命周期**：项目工具可用时，用 `publish` 原子发布并用 `--input <path>`
+   声明直接输入；`accept`、`review` 与 `package` 继续承担确认、复核与交付。
+4. **保持职责分离**：创作者确认、内容修订和复核是不同动作；reviewer 提修改要求，负责人改文件。
+
+## 所有权边界
+
+- **本阶段拥有**：可选 coverage audition 与场次视觉计划、覆盖处置、镜头目的、镜头时长、
+  绑定、起止边界；关键帧的注意焦点、构图、机位/镜头与冻结站位。渲染出的关键帧提示词是缓存。
+- **本阶段继承**：剧本的信息权限与原文要求；资产的身份与变体绑定。
+- **本阶段不越权**：不用风格词改写人物状态，不新建资产身份，不改写剧本事实。镜头边界
+  拥有起止位置、姿态、目光、双手、持物与可见连续性；关键帧只投影这些事实，永不覆盖它们。
+
+## 制作形态需要什么
+
+视觉风格不是贴在提示词前面的标签。创作者已接受的视觉方向与制作形态由项目层决定并传入，
+**本技能不加载形态卡，也不自行选择形态**；本节只说明本阶段需要形态回答什么、以及拿到
+答案后投影成哪些字段。
+
+形态决定属于 `craft_default`：创作者说明理由即可覆盖。形态不能创造新的
+`structural_invariant`，也不能改写身份、地理、持物归属与可读文字政策。审查者不得单凭
+形态偏好阻断交付。
+
+不要用“加一句风格前缀”处理形态差异。前缀只改变检索标签；形态改变的是**必须出现和
+可以省略的字段**，只有后者会被执行，也只有后者能被审查。
+
+本阶段要向形态决定问：**注意力、层次、遮挡、可动层与冻结边界**在本形态下怎么表达。
+
+运动预算的默认值随形态改变：实拍默认全动作，要写的是限制；三维默认可全动作，但摄影机
+是最贵的一层；限动画与水墨默认保持姿态，要写的是**哪一层例外**；Q 版默认一镜一因果。
+省掉这一判断的后果可预测：默认保持姿态的形态会被写成全员飘动，默认全动作的形态会被
+写成一串没有接触点的动作词。
+
+本阶段新增：注意力、层次、遮挡、可动层与冻结边界。
+
+## 参考媒体与补拍
+
+- **参考图能决定什么要逐张写明**：每张参考的用途、可以照搬什么、不可以照搬什么。身份参考
+  不自动决定构图；构图、尺度或效果参考不自动带入图中人物、服装、文字、道具与故事状态。
+- **像素主张需要证据**：关于参考图上可见内容（尤其文字、水印、标牌、界面）的断言，必须
+  来自创作者/参考图权利人的可核对说明，或运行环境获授权后形成的输入参考观察记录，并绑定
+  被检查的字节。两者都没有时保持 `unverified`，负面提示词不能代替证据。
+- **观众揭示时机**：某一事实何时可被观众看到，由已接受的可见性决定绑定其来源、载体、
+  权限、触发与保护方式。构图既不能提前泄露该事实，也不能遮掉本环节必须传达的载体。
+- **母版、补拍与替代**：补拍默认只补充、不替代母版。普通母版不增加版本范围字段；只有
+  补拍/替代版才声明 `pickup | alternate`，用同一文件内稳定的记录 ID 说明母版与补充关系，并把每项原文要求对应到当前字段或说明
+  去向。只有下游审查结论才能批准替代，不得回写形成循环引用。
+
+## 本阶段规则
+
+### `SHT`
+
+| ID | Class | Knowledge |
+|---|---|---|
+| SHT-01 | structural_invariant | Every production-relevant screenplay block has a coverage disposition. |
+| SHT-02 | reviewed_invariant | Each shot has a dramatic/viewing purpose and preserves its source meaning. |
+| SHT-03 | craft_default | Keep a short shot focused on the smallest action/reaction unit that carries its purpose; combine or split it according to performance, information, and continuity rather than a fixed count. |
+| SHT-04 | craft_default | Change framing/camera because attention, pressure, alignment, reveal, or rhythm changes. |
+| SHT-05 | structural_invariant | A keyframe projects one accepted shot boundary and exact asset variants. |
+| SHT-06 | reviewed_invariant | A keyframe is one freezeable instant, not an ordered action chain. |
+| SHT-07 | taste_option | Lens vocabulary, tempo, and locked/handheld/formal style follow visual direction. |
+| SHT-08 | reviewed_invariant | Each authoritative source action is realized once; repeated coverage adds reaction/detail/recontextualization rather than replaying it. |
+| SHT-09 | reviewed_invariant | Exact Location/View orientation and visible anchors match the camera side used by the shot. |
+| SHT-10 | reviewed_invariant | Rendered keyframe prose contains only facts from the boundary that keyframe declares. A start frame carries no state first created by the shot's motion or end; an end frame carries no state already spent before it. Neither frame borrows the other's facts. |
+| SHT-11 | craft_default | When information changes another person's power, relationship, knowledge, or choice, preserve that reception visibly; shot count, framing, and duration follow the consequence and project profile. |
+| SHT-12 | reviewed_invariant | Each audience-visibility fact binds its exact source, carrier, permission, trigger, and protection method; framing neither reveals that fact early nor hides the carrier this shot must communicate. |
+| SHT-13 | reviewed_invariant | Multi-character blocking projects sourced, directed relationships into compatible positions, gaze, distance, and action lines for the current boundary. |
+| SHT-14 | reviewed_invariant | A contested moving object preserves ownership, trajectory, direction, time/round state, and end location across cuts unless an authorized ellipsis says otherwise. |
+| SHT-15 | reviewed_invariant | When the creator has declared delivery-surface overlay regions with their permanence and source, what a shot must be read for—face and gaze, readable evidence text, the decisive hand action—does not sit only inside those regions, and shots bind the declared version. An undeclared surface leaves the rule inactive: record it as unresolved and do not restage against a guessed region. |
+| SHT-16 | structural_invariant | Coverage carries an episode duration total that is the arithmetic sum of its shots' accepted `duration_seconds`; every shot the coverage lists either contributes a number or is named in `unresolved_durations`, so no shot leaves the total silently. When the project declares a target per episode, the record binds that field and states the signed delta; the delta is reported to the creator and never blocks on its own. |
+| SHT-17 | structural_invariant | A keyframe declares which boundary it freezes and binds that shot's matching boundary field. An end keyframe is a projection of `end_boundary`, never a second end-state authority, and per-shot keyframe count stays open: one start frame by default, an end frame only when the delivery workflow consumes it. Handing over a start/end pair delegates the motion between them to interpolation, so an action the shot exists for cannot rest on that gap alone. |
+| SHT-18 | craft_default | For a scene where directing choice materially changes audience knowledge, alignment, spatial pressure, performance ownership, or the landing, an accepted scene visual plan may bridge project direction and shots; it binds exact screenplay blocks, direction/profile, Location/View and relevant asset states, ordinary scenes skip it, and it never owns screenplay facts or shot boundaries. |
+| SHT-19 | reviewed_invariant | When a coverage audition is used, its approaches genuinely differ by knowledge timing, alignment, performance space, strongest image, landing, losses, or production fit; it uses no fixed option, grid, framing, or shot-count formula, and an independent creator acceptance record names the exact audition record and an existing selected approach before the formal plan or shots. |
+| SHT-20 | reviewed_invariant | Shot revision identity follows directing responsibility rather than array position or text similarity: reorder preserves IDs, insertion creates one, split/merge retires replaced IDs and creates successors, and active coverage plus downstream refs are reconciled before delivery. |
+| SHT-21 | reviewed_invariant | A keyframe's delivery text carries only what will be filmed: record and rule IDs, lifecycle status words, hashes, field paths, reference filenames, craft notes, and run-on negative lists stay in the spec fields. Two keyframes in one episode whose delivery text differs only by their identifiers are a template, not two frames. The suite runs no mechanical check; the reviewer cites the text against this rule. Same obligation as `VID-22` in the video-prompts stage. |
+
+### `CON`
+
+| ID | Class | Knowledge |
+|---|---|---|
+| CON-01 | structural_invariant | Linked end and next start states match or have an explicit owner revision. |
+| CON-02 | reviewed_invariant | Knowledge, injury, ownership, weather, light, or physical state does not teleport/regress without story cause. |
+| CON-03 | craft_default | Track downstream-relevant deltas, not the whole 设定集 in every shot. |
+| CON-04 | structural_invariant | A delta records before, after, cause/source, effective range, and affected bindings. |
+| CON-05 | taste_option | Declared montage, ellipsis, dream, or subjective imagery may intentionally break ordinary continuity. |
+| CON-06 | structural_invariant | A delta's affected refs cover all existing consumers; future consumers remain locators until materialized. |
+
+规则分级由高到低：`structural_invariant`（结构缺陷，阻断）、
+`reviewed_invariant`（需证据判断）、`craft_default`（常用做法，可覆盖）、
+`taste_option`（创作者选择，不作缺陷）。创作者已接受的事实优先于本表。

package/lib/drama/skills/short-drama-storyboard/scripts/selftest.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""Offline self-test for storyboard bookkeeping checks."""
+
+from __future__ import annotations
+
+import copy
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from storyboard_check import (
+    check_boundary_entries,
+    check_episode_duration,
+    check_keyframe_boundaries,
+    check_screenplay_coverage,
+)
+
+MINIMUM_PYTHON = (3, 9)
+if sys.version_info < MINIMUM_PYTHON:
+    raise SystemExit("selftest.py requires Python 3.9 or newer")
+
+
+def require(condition: bool, message: str) -> None:
+    if not condition:
+        raise AssertionError(message)
+
+
+def codes(findings: list[dict[str, Any]]) -> set[Any]:
+    return {item["code"] for item in findings}
+
+
+SHOT: dict[str, Any] = {
+    "shot_id": "SHOT-001",
+    "duration_seconds": 5,
+    "start_boundary": "closed door",
+    "end_boundary": "open door",
+}
+BOUNDED_SHOT: dict[str, Any] = {
+    "shot_id": "SHOT-002",
+    "duration_seconds": 5,
+    "start_boundary": {
+        "positions": ["站在柜台东侧（与上一镜相同）"],
+        "facing": ["面向门口"],
+    },
+    "end_boundary": {"positions": ["退到门内一步"], "facing": ["面向柜台"]},
+}
+SHOTS_SOURCE: dict[str, Any] = {
+    "owner": "short-drama-storyboard",
+    "artifact": "剧集/EP001/storyboard/shots.jsonl",
+    "hash": "a" * 64,
+}
+COVERAGE: dict[str, Any] = {
+    "sources": {"shots": SHOTS_SOURCE},
+    "dispositions": [{"shot_refs": [{"src": "shots", "record_id": "SHOT-001"}]}],
+    "episode_duration": {
+        "counted_shot_ids": ["SHOT-001"],
+        "unresolved_durations": [],
+        "shot_seconds_total": 5,
+        "delta_seconds": 0,
+        "disposition": "within_creator_tolerance",
+    },
+}
+KEYFRAME_SOURCES: dict[str, Any] = {"shots": SHOTS_SOURCE}
+KEYFRAME: dict[str, Any] = {
+    "keyframe_id": "KF-001-END",
+    "boundary_role": "end",
+    "boundary_ref": {"src": "shots", "record_id": "SHOT-001", "field": "/end_boundary"},
+}
+# A reference may also carry its whole snapshot inline instead of naming a
+# sources key; the checker resolves both to the same upstream binding.
+EXPANDED_COVERAGE: dict[str, Any] = {
+    "dispositions": [
+        {"shot_refs": [{**SHOTS_SOURCE, "record_id": "SHOT-001", "authority": "accepted"}]}
+    ],
+    "episode_duration": COVERAGE["episode_duration"],
+}
+EXPANDED_KEYFRAME: dict[str, Any] = {
+    "keyframe_id": "KF-001-END",
+    "boundary_role": "end",
+    "boundary_ref": {**SHOTS_SOURCE, "record_id": "SHOT-001", "field": "/end_boundary"},
+}
+
+
+def test_screenplay_coverage_flags_gaps_and_double_claims() -> None:
+    """Every screenplay block must be claimed by exactly one shot.
+
+    Shots bind to the screenplay through the index, so coverage is measured in
+    block IDs. Measuring it in prose lines instead reported every line of a
+    correctly covered episode as unfilmed.
+    """
+    with tempfile.TemporaryDirectory() as directory:
+        index = Path(directory) / "screenplay-index.jsonl"
+        index.write_text(
+            '{"record_type":"block","block_id":"BLK-A"}\n'
+            '{"record_type":"block","block_id":"BLK-B"}\n'
+            '{"record_type":"block","block_id":"BLK-C"}\n',
+            encoding="utf-8",
+        )
+        sources = {
+            "screenplay-index": {
+                "owner": "short-drama-write",
+                "artifact": "剧集/EP001/screenplay-index.jsonl",
+            }
+        }
+        shots = [
+            {"shot_id": "SH001", "source_refs": [{"src": "screenplay-index", "record_id": "BLK-A"}]},
+            {"shot_id": "SH002", "source_refs": [{"src": "screenplay-index", "record_id": "BLK-B"}]},
+            {"shot_id": "SH003", "source_refs": [{"src": "screenplay-index", "record_id": "BLK-B"}]},
+            {"shot_id": "SH004", "source_refs": [{"src": "screenplay-index", "record_id": "BLK-Z"}]},
+        ]
+        found = {f["code"] for f in check_screenplay_coverage(shots, sources, index)}
+    require("SHT01_BLOCK_UNCLAIMED" in found, "an unfilmed block must be reported")
+    require("SHT01_BLOCK_CLAIMED_TWICE" in found, "a doubly claimed block must be reported")
+    require(
+        "SHT01_BLOCK_NOT_IN_SCREENPLAY" in found,
+        "a shot claiming an absent block must be reported",
+    )
+
+
+def test_screenplay_coverage_is_skipped_when_not_supplied() -> None:
+    require(check_screenplay_coverage([], {}, None) == [], "no index means no claim")
+
+
+def main() -> int:
+    require(check_episode_duration(COVERAGE, [SHOT], 5) == [], "valid duration")
+    require(
+        check_keyframe_boundaries([KEYFRAME], [SHOT], KEYFRAME_SOURCES) == [],
+        "valid boundary",
+    )
+    require(check_episode_duration(EXPANDED_COVERAGE, [SHOT], 5) == [], "expanded duration")
+    require(
+        check_keyframe_boundaries([EXPANDED_KEYFRAME], [SHOT], {}) == [],
+        "expanded boundary",
+    )
+
+    wrong_total = copy.deepcopy(COVERAGE)
+    wrong_total["episode_duration"]["shot_seconds_total"] = 4
+    require(
+        "SHT16_TOTAL_IS_NOT_THE_SUM" in codes(check_episode_duration(wrong_total, [SHOT], 5)),
+        "wrong duration total was not detected",
+    )
+
+    wrong_boundary = copy.deepcopy(KEYFRAME)
+    wrong_boundary["boundary_ref"]["field"] = "/start_boundary"
+    require(
+        "SHT17_BOUNDARY_REF_DISAGREES_WITH_ROLE"
+        in codes(check_keyframe_boundaries([wrong_boundary], [SHOT], KEYFRAME_SOURCES)),
+        "wrong keyframe boundary was not detected",
+    )
+
+    undeclared = copy.deepcopy(COVERAGE)
+    undeclared["sources"] = {}
+    require(
+        "REF_SRC_IS_NOT_DECLARED" in codes(check_episode_duration(undeclared, [SHOT], 5)),
+        "a src without a sources entry was not detected",
+    )
+    require(
+        "REF_SRC_IS_NOT_DECLARED"
+        in codes(check_keyframe_boundaries([KEYFRAME], [SHOT], {})),
+        "a keyframe src without a sources entry was not detected",
+    )
+
+    unbound = copy.deepcopy(COVERAGE)
+    unbound["dispositions"][0]["shot_refs"] = [{"record_id": "SHOT-001"}]
+    require(
+        "REF_HAS_NO_UPSTREAM_BINDING" in codes(check_episode_duration(unbound, [SHOT], 5)),
+        "a reference binding no snapshot was not detected",
+    )
+
+    # A boundary entry that only says "same as before" reads as written but tells
+    # the next stage nothing; an absolute fact that mentions the previous shot in
+    # passing is fine and must not be flagged.
+    require(check_boundary_entries([BOUNDED_SHOT]) == [], "absolute boundary entries")
+    relative = copy.deepcopy(BOUNDED_SHOT)
+    relative["end_boundary"]["positions"] = ["（位置不变）"]
+    require(
+        "SHT05_BOUNDARY_ENTRY_IS_A_BACK_REFERENCE"
+        in codes(check_boundary_entries([relative])),
+        "a boundary entry that only points back was not detected",
+    )
+
+    test_screenplay_coverage_flags_gaps_and_double_claims()
+    test_screenplay_coverage_is_skipped_when_not_supplied()
+
+    print("13 self-tests passed")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())