interface:
  display_name: "短剧审查"
  short_description: "审查短剧故事、资产、连续性、分镜与提示词并给出证据"
  default_prompt: "使用 $short-drama-review 对短剧项目产物做独立、带证据的校验与审查。"

{
  "sources": {
    "motion-specs-alternate": {
      "owner": "short-drama-video-prompts",
      "artifact": "剧集/EP001/storyboard/motion-specs.jsonl"
    },
    "motion-specs-master": {
      "owner": "short-drama-video-prompts",
      "artifact": "剧集/EP001/storyboard/motion-specs.jsonl"
    },
    "shots": {
      "owner": "short-drama-storyboard",
      "artifact": "剧集/EP001/storyboard/shots.jsonl"
    }
  },
  "example_only": true,
  "decision_id": "SUPERSESSION-EXAMPLE",
  "alternate_ref": {
    "src": "motion-specs-alternate",
    "record_id": "MOTION-ALTERNATE",
    "authority": "candidate"
  },
  "master_ref": {
    "src": "motion-specs-master",
    "record_id": "MOTION-MASTER",
    "authority": "accepted"
  },
  "checked_obligations": [
    {
      "source_ref": {
        "src": "shots",
        "record_id": "SHOT-EXAMPLE",
        "field": "/end_boundary",
        "authority": "accepted"
      },
      "result": "covered | missing | changed",
      "evidence": "<指出 alternate 中的对应字段>"
    }
  ],
  "decision": "approve_supersession | reject_supersession",
  "rationale": "<覆盖、对白、揭示、连续性和项目要求的复核结论>"
}

{
  "sources": {
    "screenplay": {
      "owner": "short-drama-write",
      "artifact": "剧集/EP001/screenplay.md"
    },
    "findings": {
      "owner": "short-drama-review",
      "artifact": "审查/findings.jsonl"
    }
  },
  "review_id": "REVIEW-EXAMPLE",
  "scope": [
    "story_script"
  ],
  "reviewed_artifacts": [
    {
      "src": "screenplay"
    }
  ],
  "findings_ref": {
    "src": "findings"
  },
  "review_method": "uninvolved_reviewer | self_check",
  "reviewer": "<honest reviewer label>",
  "structural_validation": "not_run",
  "verdict": "PROVISIONAL",
  "blocking_findings": [],
  "open_blocker_count": 0,
  "notes": [],
  "supersession_decisions": []
}

{
  "sources": {
    "screenplay": {
      "owner": "short-drama-write",
      "artifact": "screenplay.md"
    },
    "findings": {
      "owner": "short-drama-review",
      "artifact": "minimal-findings.jsonl"
    }
  },
  "review_id": "REVIEW-SC001",
  "scope": [
    "story_script"
  ],
  "reviewed_artifacts": [
    {
      "src": "screenplay"
    }
  ],
  "findings_ref": {
    "src": "findings"
  },
  "review_method": "self_check",
  "reviewer": "standalone example self-check",
  "structural_validation": "passed",
  "verdict": "REVISE",
  "blocking_findings": [
    "FIND-SC001-TURN"
  ],
  "open_blocker_count": 1,
  "notes": [],
  "supersession_decisions": []
}

# 去模板感：诊断、修订与误报

“像模板”不是稳定 finding。先定位重复机制如何伤害当前故事，再把修订交给 owner。

## 目录

- [诊断四层](#1-诊断四层)
- [修订不是换同义词](#2-修订不是换同义词)
- [误报反例](#3-误报反例)
- [Finding 示例](#4-finding-示例)
- [分级](#5-分级)

## 1. 诊断四层

1. **因果重复**：每轮都靠陌生人带来答案、巧合救场、对手自曝。
2. **策略重复**：所有人物都用质问—否认—提高音量，没有各自筹码。
3. **表达重复或过度工整**：动作总是“攥拳/眼神一冷”，每句对白都跟同构微动作，
   或 prompt 总以泛化质量词开头。
4. **镜头重复**：每句台词 close-up + push，camera 不随 attention/关系变化。

只有能引用至少两个位置并说明损失，才发重复 finding。单次使用类型惯例不是模板罪证。

表达层还要检查三种不靠逐字重复也会产生模板感的情况：

- **过度解释**：动作、证据或台词已经表达人物选择，后面又补一句意义说明、心理翻译或
  道德总结，夺走观众推断空间；
- **过度收口**：每场都用总结句、金句或完整结论封死余波，下一场只能重新制造压力；
- **过度工整**：每轮台词都配相同长度的微表情/手部动作，每场都以同构对仗或反问落点，
  人物和场面失去自己的节奏。
- **信息密度均匀**：每一拍携带的新信息量几乎相同，于是没有一件事像"事件"。这与过度
  工整不同——那讲的是形式对称，这讲的是**疏密**：一场戏里本该有几拍是白给的、有一拍
  是砸下来的。单看每一拍都合格，所以逐拍检查抓不到它；要把一场戏的各拍并排看信息量。
- **代价即时结清**：本集造成的代价全部在本集内还完，于是什么都不积累。这是过度收口的
  跨集版本。查法很具体——把本集造成的代价与它实际落地的集号列出来，若全部落在同一集，
  就是这个病；短剧靠未结清的债务把观众带到下一集。

这不是禁词表。Reviewer 仍要引用当前作品中至少两个位置，说明被重复解释、封死或抹平的
具体意义；有意的仪式、喜剧节拍、人物口癖、方言和创作者选择继续按下文反例处理。

## 2. 修订不是换同义词

### 因果

弱：主管再次嘲笑她。她拿出另一份证据，所有人震惊。

诊断：证据无需选择便出现；第二轮只把第一轮“拿证据打脸”再演一次。

给 write owner 的目标：保留公开施压与主角掌握证据；让主角必须在“马上公开”与“先保护
会被顶罪者”之间作不可兼得的选择，并让选择产生下轮压力。不要在 finding 里代写完整台词。

### 对话

弱：

~~~text
A：你在骗我。
B：我没有骗你。
A：你就是在骗我。
~~~

若 B 手里有纸袋，A 手里有钥匙，可要求每轮改变筹码：A 用钥匙证明到访；B 用“拆袋即选边”
重定义信任；A 选择拿走钥匙但不拆袋。沉默和物件完成第三轮，不必更响。

### Prompt

弱：“高级、电影感、精致、超清的神秘盒子。”

Finding 应指出缺少哪个 accepted identity/scale/material/state/text policy。修订目标是补这些
识别事实，不是禁用“高级”一词。

### 镜头

三个连续台词都 extreme close + push。先问每句 attention：第一轮是双方关系，可留 two-shot；
第二轮证物被推过桌面，attention 落到手/边界；第三轮对方不碰证物，reaction 可由手和负空间
完成。不是为了“景别多样化”，而是每个 cut 有不同 viewing purpose。

## 3. 误报反例

以下不能仅凭表面重复判模板：

- 仪式场景刻意重复同一句/同构图，第二次因持有人改变而意义反转；
- 喜剧 running gag 重复动作，但每次让新人物付出不同代价；
- 审讯保持 locked two-shot，以拒绝剪切制造压迫；
- 类型短剧多集使用相同片头结构，这是 accepted format；
- 人物因创伤反复做同一动作，作品正在表现停滞而非遗漏变化。

Reviewer 必须说明：重复是否是 creator choice、第二次新增了什么、若保留会伤害什么。
不确定时记 note/question，不是 REVISE。

## 4. Finding 示例

~~~markdown
## Major · REV-003 · 连续两集用同一种自曝完成揭示
- 位置：剧本.md / EP002-SC003；剧本.md / EP003-SC002
- 证据：两场都由主管主动说出隐藏事实，主角没有选择。
- 影响：主角策略不参与揭示，连续两集的回报来自对手自曝。
- 修订结果：保留两项事实，但让至少一项揭示由主角有代价的策略触发。
- Owner：short-drama-write
- 规则：SCR-04 · craft_default
~~~

位置只使用文件名、标题 ID、行号或必要短引文。不要复制上游快照，也不要为审查另建记录 ID。

## 5. 分级

- structural_invariant：finding 的位置、严重程度、owner 与结论明确且可复核。
- reviewed_invariant：下游没有改写 source meaning；需证据判断。
- craft_default：避免无意义的因果/策略/表达/镜头重复；可由创作者说明覆盖。
- taste_option：类型惯例、仪式重复、running gag、固定镜头风格本身不阻断。

# 制作质量检查：各环节怎么审、返工怎么防

## 目录

- [阻断分级](#一先分清什么问题必须阻断)
- [返工原因](#二跨环节常见返工原因)
- [改写回归](#三指令优先级与改写回归rev-09)
- [证据问题](#四各环节证据问题)
- [生产纪律](#五生产纪律)
- [审查问题](#六审查问题怎么写)

来自对完整生产链返工原因的定性案例阅读，示例均为合成改写。审查方法见
[review-method.md](review-method.md)。本文展开 `REV-08` 与 `REV-09`：检查具体
必须保留的内容是否还在，而不是用样本规模、固定数量或所谓命中率证明质量。

**每个环节都会成为下一环节的输入。审查必须指出丢失了哪项故事意义、状态、原文内容
或制作要求，以及应由哪个技能修复。**

## 一、先分清什么问题必须阻断

- `structural_invariant`：可见引用、明确时长、同一区间摄影机指令冲突、已声明
  起点/终点不一致等可以直接证明的问题；本地检查可以阻断。
- `reviewed_invariant`：剧情意义是否丢失、人物反应是否承接后果、动作是否可执行、
  指令是否被改写；审查者引用资料给 `REVISE`。
- `craft_default`：常用镜头、密度、布光、提示词组织方式；只能给警告，并允许
  创作者说明理由覆盖。
- `taste_option`：气质、镜头偏好、节奏风格与表现强度；不得单独成为质量缺陷。

不要把“和示例不一样”写成审查问题。先说明违反了哪个已确认事实，或会造成什么
下游损失。

## 二、跨环节常见返工原因

### 1. 覆盖丢失

剧本中的动作、台词、反应、可读文字或转场在分镜/提示词中消失，或一个缩短后的
重试提示词只保留漂亮画面，却不再完成同一叙事职责。

检查：

- 是否能从剧本的每个制作相关段落直接追到承担它的镜头或声音；
- 每个有明确来源的动作是否只实现一次；
- 关键结果落地后，观众是否能看到受影响者的反应或后果；
- 重新编组前后，原文段落、镜头目的、起点/终点与声音引用是否仍相同。

### 2. 表演只有标签

“震惊、愤怒、电影感”没有触发、处理、选择与落点，删掉台词后只剩静态姿势。
修复不是堆更多同义词，而是把故事变化落成注视对象、手部选择、重心、停顿、距离、
呼吸或道具处理。

### 3. 空间与状态漂移

人物位置、朝向、手、持物、伤势、造型、时间、天气或光线在相邻镜之间无原因变化。
先核对负责环节的起止边界和资产版本；若剧情确实需要变化，向对应技能
请求状态或镜头修改，不在提示词里偷偷补故事。

选择性环境变换还要核对 `VID-11`：触发、准确目标范围、结束几何/状态与保持项
是否同时存在；相邻但非目标的人物、道具、文字承载面和空间锚点是否保持原位置、数量与
状态。只写“门消失”“地面折叠”而不写留下什么及什么必须不变，属于无法确认能否执行的问题。

### 4. 文本与声音边界混乱

- `exact-readable` 道具文字与全局 `no-text` 同时出现；
- `no-text` 或 `exact-readable` 镜头绑定了带冲突标牌、界面、号码、水印或字幕的参考图，
  却只追加负面词，没有裁切、清理、遮罩、替换或退回参考图负责方；
- 身份、构图、尺度或效果参考没有说明可参考内容和不可照搬内容，导致它把图中
  没有来源的人物、服装、文字、道具或事件带入当前提示词；
- VO/OS 被写成角色对口型说话；
- 提示词新增来源没有的台词、音乐、爆炸或环境事件；
- 角色名/资产引用进入台词内文；
- 音效、环境底噪与对白方向没有来源或相互遮蔽。

目标模型画音同轨时（`VID-23`），检查声音内容、时序、发声边界是否符合来源，
总结是否错误地引入不存在的声音层。无对白镜也应交代需要的底声或静默。
H3 无非画内配乐时，`non_diegetic_music: N/A` 是有效的空形式。

按实际遗漏、矛盾与影响报告问题，不因出现 `No dialogue` 或第二个否定句判错，
不把 H3 的小样本表现套到所有同轨模型上。相关证据指向同一个问题时合并报告。

### 5. 负面补丁淹没动作

为防止模型缺陷叠加大量禁令，真正的起点、动作、表演与终点被挤成几句。
只保留目标模型已确认需要的条件规则；把故事与连续性要求留在权威规格，不在
每次失败后永久增加一条全局禁令。

### 6. 版本和执行状态冒充内容权威

同一集、镜头或提示词可能保留多个历史版本。审查前先读取当前 creator-visible 文档，并按文件名、
标题 ID 和文中明确写出的母版/替代关系判断当前版本；文件更新时间、编号大小、默认展示项或最近一次
执行状态只能帮助定位，不能替代创作者当前决定。下游仍引用旧标题时，即使内容看似合理也要报告
版本引用过期，而不是把旧稿重新解释成现行要求。

生成或处理任务的技术状态只说明某次执行结束到哪一步，不证明语义质量。任何状态为成功的
历史记录都必须写明当时准确的提示词标题、资产/镜头引用与配置；审查仍比较这些文字是否
覆盖当前创作者可见文档。没有看过媒体时，不得从技术状态、重试次数或结果地址声称画面、
表演、文字和连续性已经正确。

## 三、指令优先级与改写回归（REV-09）

同一提示词可能同时接收故事、分镜、项目风格和目标模型约束。按以下顺序处理：

1. **已确认的故事事实与对白/文字内容**：不能被视觉偏好改写；
2. **已确认的镜头覆盖、目的、起点、终点与时长**：运动规格只能实现，不能
   重定边界；
3. **已确认的资产身份/版本与连续性变化**：绑定正确状态；
4. **创作者已确认的视觉方向和制作配置**：规定摄影、节奏、声音
   与文本策略，但不能覆盖前三项；
5. **目标模型条件**：只处理表达与已知能力边界；无法实现上层要求时报告内容丢失，
   不能静默删除；
6. **装饰性偏好**：镜头花样、泛质量词和未选择的建议最先让位。

若两条同级的已确认规则明确冲突，阻断并交回各负责技能或创作者决定；不要用“最高
优先级”措辞覆盖另一条事实。

### 每次重写或重编组后的回归表

| 义务 | 来源证据 | 改写前实现 | 改写后实现 | 结果 |
|---|---|---|---|---|
| 原文覆盖 | 段落/覆盖引用 | 【填写】 | 【填写】 | 保留/丢失/改变 |
| 镜头目的 | 镜头引用 | 【填写】 | 【填写】 | 保留/丢失/改变 |
| 起点/终点/时长 | 边界引用 | 【填写】 | 【填写】 | 一致/冲突 |
| 资产/连续性 | 绑定/变化引用 | 【填写】 | 【填写】 | 一致/漂移 |
| 对白/文字/声音 | 准确引用 | 【填写】 | 【填写】 | 一致/新增/遗漏 |
| 项目配置 | 创作者决定引用 | 【填写】 | 【填写】 | 遵守/例外/冲突 |

同一剧本重新拆分或压缩提示词时，要额外比较镜头覆盖、每镜目的、总时长与镜头分组、
角色/造型等资产绑定，以及必须照抄的台词、文件名、命令或屏显文字。提示词变短
可能只是删掉重复描述，不自动证明内容更准确；若剧本没变而资产版本或必须照抄的文字
变了，必须有单独的上游变更依据。

**`reviewed_invariant · REV-09`**：正确引用了角色、场景和物品，只能证明绑定存在，
不能证明提示词覆盖了原动作、反应、台词与已确认的项目指令。审查者必须比较
改写前后必须保留的内容。

缩短修改若形成补拍或替代版，必须在 `视频提示词.md` 中标明版本类型、同一文件内的母版或补充
`MOTION-...` 标题，并把每项原文要求对应到当前版本或说明去向。普通母版不为“没有版本关系”制造
占位账目。补拍默认不替代母版；替代版只能提出替代请求，最终由审查结论直接指名保留哪一个标题，
不能让两个版本互相声明对方才是当前版本。若有内容丢失，再由
分镜或视频提示词技能决定保留其他镜头、拆镜、延长、删减或请求上游修改。

## 四、各环节证据问题

### 剧本

- 当前目标、阻碍、选择和局部结果能否在场上看见？
- 升级是否改变权力、信息、关系、资源、物理状态或代价，而非重复加大音量？
- 集尾钩子是否由本集已落地结果造成？
- 前史是否只通过当前需要的行为、证据、关系摩擦或有策略的对白进入？
- 对白策略、声音与信息权限是否区分人物？

### 资产与图片提示词

- Lookdev 人物、地点和高压力测试帧是否投影同一组可观察视觉规则？`role: style` 是否只控制
  声明的色彩、材质、阴影、景深或密度，而没有接管身份、地理、剧情状态或道具文字？
- 每项细节是否服务识别、复用、状态、功能或连续性？
- 身份与造型、地点与观察方向、道具与状态是否分开？
- 白底/方位/产品板是否写入了只属于具体镜头的情绪、构图或光线？
- `exact/graphic/no-text` 文字政策是否与提示词一致？
- 输入参考图的可见文字也符合该政策吗？不符合时是否记录了检查和处理方法，而不是指望
  `no-text` 删除参考像素？
- 每张参考图的 `role`、可参考内容与不可照搬内容是否明确？构图、尺度或效果参考有没有
  改写本来不该由它决定的身份、内容、文字或状态？
- 像素、文字、水印或裁切检查是否有准确的观察记录；没有时是否明确写“未观察”，
  而不是从文件引用或负面词推断已经看过输入参考图？
- 定点修改是否写准确目标、`changes` 与 `preserve_set`？
- 同一地点在同一时间/天气 state 下的各观察方向板，主光来源、冷暖主次、光比方向与实际
  灯具开关是否对齐（`IMG-10`）？不一致时是否有已记录的成因与对应 delta？逐板单独看
  都成立不能作为通过依据，必须并排比同组板。

### 分镜与关键帧

- 关键场次若用了场次视觉计划，开场与结束的观众立场、空间压力、摄影节奏、反应落点和声音
  运动是否共同完成同一转向？普通场景没有计划不构成缺陷。
- Coverage audition 是否比较了真正不同的信息时机、观看位置、表演所有权和最终画面，并绑定
  创作者选择？固定宫格、方案数或景别比例不能当通过条件。
- 每个镜头为什么独立存在，改变了什么注意、压力、信息或观看位置？
- 建立镜头、反应镜、插入镜头或重新解释前镜的镜头是否有职责，而不是凑数量？
- 关键帧是否只有一个可冻结时刻？每张关键帧是否声明了它冻结的是哪一端，并绑定该镜头
  对应的边界字段（`SHT-17`）？**尾帧是 `end_boundary` 的投影，不是第二个终点权威**——
  尾帧与镜头终点不一致时，缺陷记在尾帧上。首帧是否只写 start 事实、尾帧是否只写 end
  事实，两张有没有互相借用？**关键帧数量不是检查项**：默认一张首帧，只在交付工作流真的
  消费尾帧时才有第二张，缺尾帧本身不是缺陷。
- 本镜交出首尾帧时，中间是否有必须被观众看到的动作只靠插值兑现？若有，是该拆镜或把该
  动作移到某一端，而不是在运动规格里多写一句描述。
- 每个已经设计好的镜头是否先独立成立，再进入生成单元编组？
- 裁切、遮挡、背影或画外处理是否遵守 `audience_visibility`：既不提前泄露，也不
  遮掉本镜必须传达的证据或接收反应？
- 覆盖记录里的本集时长总和是否等于各镜头已接受时长的算术和（`SHT-16`）？覆盖列出的
  每个镜头是否要么进了总和、要么显式挂在 `unresolved_durations` 里？**镜头无声地不进
  总和才是缺陷；时长未定并显式挂起不是。** 项目声明了每集目标时长时，是否绑定该字段并
  写出带符号差值与处置？**差值本身不写成阻断项**——目标时长是创作者的计划而非质量门槛，
  只在账目算错、有镜头漏掉或处置缺失时提缺陷。
- 交付面遮挡区是否已声明（`SHT-15`）？**未声明时本规则不生效**：确认它被记为未解决即可，
  不要因此提缺陷，也不要用通用安全框代替声明。已声明时才检查：本镜必须被读到的内容
  （脸与眼神、证据上的可读文字、决定性手部动作）是否只落在这些区域里？镜头是否绑定了
  该声明的具体版本？声明改版后受影响镜头是否重新核对过？

缺少制作输入时只阻断它所支持的交付判断，不阻断文本候选预览，也不把整个镜头笼统判死：

- 缺逐字台词：只阻断具体时长、台词表演与口型可行性，不能自编台词补洞；
- 只有签名职责、没有正式签名字形：只阻断该承载面的 `readable` 文字投产；若已接受文字政策
  允许 `postproduction`，仅预留承载区可以继续，不能臆造笔迹；
- 没有创作者声明的播放面遮挡区：只阻断播放面避让核验与整体 `delivery-ready`，画面候选照常
  预览，不能拿通用安全框代替。

这些状态证明的是输入和文本准备度，不证明媒体结果质量；只有全部适用范围都为 `ready`，
才可声称整体 `delivery-ready`。输入补齐后只重审受影响范围。
若镜头写着空白承载区却让人物认出该签名/文字，直接报告语义矛盾；不能用“后期再加”倒推
当前帧已经具备角色接收和观众阅读所需的证据。

### 视频提示词

- 多人物镜头中，真正承担变化的人是否用所需的 receive、mask/visible leak、choice、landing
  体现立场差异，且表演信号在当前景别可读？没有变化的旁观者是否没有被迫填写 arc，
  `attention_handoffs[]` 是否只记录真实注意交接？
- 第一动作是否能从已确认的关键帧/起点接起？
- 有序动作能否在镜头时长内保住故事动作、表演、对白与落点？
- 摄影机是否由注意、压力或揭示驱动，并且区间不冲突？
- 环境/声音是否有已确认的依据？
- 选择性折叠、消失、替换或复原是否声明目标范围、结束几何和 `preserve_set`，且没有
  连带改变非目标人物/道具/文字/空间锚点？
- 结束报告是否逐项等于分镜规定的连续性终点？
- 交付容器里装了几个已接受镜头？容器时长是否正好等于这些镜头已接受时长之和（`VID-13`）？
  多镜容器的成员是否来源顺序连续、共享同一条绑定链、不跨场次，且每个成员仍能单独审查？
- 空间或被摄主体的跳变是否只落在成员镜头边界上？落在某个成员的计时段内部即为段内藏切；
  容器时长与成员之和不符另记一条算术缺陷，两者不合并成同一条 finding。
- 把本集各容器的成员展开取并集，与覆盖记录的本集镜头集合对账（`VID-15`）：有没有镜头
  出现在两个容器里，或者既没进容器也没作为散镜交付？**逐个容器都正确不能代替这次全集
  对账**——重复计入和无人认领这两种错误在单容器视角下都看不见。容器侧的总时长是否与
  `SHT-16` 的镜头侧总时长相等？
- 配乐意图是否写成了相对相邻镜的进入/退出/让路，而不是各镜独立描述一段音乐？相邻镜的
  标注能否接上（`VID-14`）？**提示词或规格文本**是否要求单镜自带配乐床，或与"配乐归
  时间线层"的已接受方案冲突？成品里究竟有没有烧进音轨**不能由本环节判断**——只有已授权的
  文字观察记录报告了该问题时才据此写 finding，否则保持 `unverified`，不从文本推断混音结果。
- 参考帧已有的外观是否被无谓重复，反而增加漂移？
- 补拍版或替代版是否把每项原文要求分别对应到运动字段或说明去向，并写明
  母版或补充运动记录 ID；若请求替代母版，下游审查结论是否完成覆盖与连续性复核？

## 五、生产纪律

1. **先核对原文覆盖，再选择密度**：镜头数量从意义、动作边界和反应职责推导，不从
   固定拍镜比倒推。
2. **从动作量反推时长**：必须保留的动作、对白与落点放不下时，删减、
   拆镜或请求修改；不靠加快所有动作硬塞。
3. **每组交付只使用一套明确配置**：不要混用两套模型条件或相反的服装/
   光影托管策略。
4. **文本策略双重核对**：提示词约束与资产文字政策都要一致；后处理能力不能
   为矛盾提示词开脱。
5. **定点修改一次改一个意图**：同时显式冻结不变项，记录该修改影响哪些下游。
6. **重试按被拒的那一项路由**：每次重投先写清这次改了什么。拒绝原因指向某项输入时，
   先改那一项再投——指向台词或提示词文字就改写该句，指向参考图就换图或修掉图上被拒
   的部分，指向音频就重录或换音源。被拒的台词改写成同样完成这一拍的另一种说法，
   不是把这一拍删掉。只有拒绝原因不落在任何具体输入上时，原样重投才算一次合理尝试，
   同一输入连续原样重投不超过两次，之后改内容或退回负责环节。审查问题写在该改的那项
   输入上。每次记录失败、改动与 `preserve_set`。
7. **长范围先建连续性记录和检查点**：可一次做完整原文覆盖，但接受、审查与回滚仍按
   创作者能理解的阶段进行。
8. **视频提示词阶段发现故事问题就退回负责环节**：不让提示词用新台词、动作或状态替剧本补洞。

## 六、审查问题怎么写

合格的审查问题：

> `SHOT-014` 的原文段落要求听者在指控后把钥匙交回，当前运动说明只覆盖说话
> 人并以其特写结束；这删除了关系权力转移，也使下一镜“钥匙已在桌上”的起点
> 无来源。由分镜技能补反应或交接镜头，或由剧本技能明确删除转手；不要只在
> 运动说明末尾发明钥匙落桌。

不合格的审查问题：

> 镜头太少、不够电影感、没有按参考比例、AI 味重。

`REV-08` 和 `REV-09` 都要求产物引用、具体资料、影响、修改要求、负责技能、
严重程度与状态。固定字数、镜头数、比例和示例相似度只能帮助提问，不能替代
上述证据。

# 项目级试跑与生产反馈校准

校准只消费创作者提供或授权形成的**文字观察记录**，用来改进当前项目的提示词与镜头设计。
本技能不提交任务、不下载或生成媒体，也不从“任务成功”、结果地址或文件存在推断内容质量。

## 先分清两种观察

- `input_reference`：输入参考图上可见的身份、文字、水印、裁切或地理事实；它只支持参考准入。
- `generated_result`：某个准确提示词/规格版本、参考槽位集合和制作配置下的结果观察；它可以支持
  项目内校准，但不能自动变成跨项目、跨配置或跨制作方式的定律。

两种记录都要写明被观察的媒体、观察方法、准确的文档标题引用、观察区域/时间段、限制与观察者。
生成结果还要写明对应提示词或镜头标题、参考图顺序、制作形态/配置和结论适用范围。审查只读取
项目提供的记录，不在公开运行时找数据。记录仍可使用只代表这份有界观察可复核，不表示创作内容
已接受或质量通过；证据被撤回、媒体已经换过或来源无法复核时，不沿用它做校准，并写明失效原因。

实际项目记录可以由创作者放在受保护的 `原始资料/生产观察.md`，也可以直接在当前请求中提供；它不属于
五份单集创作文档，也不进入文本交付包。

## 选择有内容代表性的试跑

不随机抽样，也不规定固定数量。按项目实际风险选互相有差异的代表：身份近景与全身、双人潜台词、
多人同框、手部/道具接触、可读文字、大动作/复杂路径、高难度光影、首尾帧接续，以及最重要的
lookdev 风格帧。选择理由必须对应本项目，不因别处高频而加入。

## 从观察到诊断

逐条区分：

1. **直接观察**：被授权观察者实际看见或听见什么；
2. **文本定位**：哪个 prompt/spec/shot 字段可能参与；
3. **替代解释**：参考本身、景别、动作竞争、配置或观察盲区是否也可能造成结果；
4. **有界结论**：只在当前项目与准确版本条件下，哪种写法更可读或更稳定；
5. **修订路由**：身份/地理回 assets，构图/镜头边界回 storyboard，图片规格回 image-prompts，
   动作/表演/摄影/声音实现回 video-prompts。

没有授权观察时只写“文字风险”，**不声称看见**脸部漂移、表演失败、光影吞锚点或剪辑问题。

## 诊断之后先定处置，再谈修订

拿到诊断不等于要重做。先在五种处置里选一种，再决定要不要进入修订；顺序反了就会把最贵的
一种当成默认：

| 处置 | 什么时候选 | 本环节要做什么 |
|---|---|---|
| 保留 | 镜头目的已达成，剩余瑕疵不影响信息、连续性与观众理解 | 不改文字；把已知瑕疵记进观察，不伪装成通过 |
| 后期处理 | 缺陷落在文字层、混音、调色、修剪或少量边缘帧上 | 不改提示词；交接给对应责任方并记录归属 |
| 局部编辑 | 构图、时机与表演都对，只有一层错 | 只写该层的修改项与保持项，不重写整条提示词 |
| 重新提交 | 文字经核对没有缺陷，失败看起来随机 | 有上限的尝试，不是修复手段 |
| 改写 | 同一缺陷在多次结果中重复出现 | 回到诊断指出的那一层改结构：拆镜、减并发、换实现路径 |

两条判据把它们分开：

1. **缺陷是否落在文字能控制的范围内**。 落在文字之外的（渲染瑕疵、编码、少数边缘帧）不该
   由提示词承担；改提示词只会引入新变量，还会让下一次结果更难归因。
2. **同一缺陷是否已经复现过**。 第一次出现可能是随机，重复出现说明结构有问题。此时继续
   重新提交，是在为同一个错误反复付费，而每次都不产生新信息。

**不要用增加形容词的方式回应重复缺陷**。 在同一条提示词上叠加“高质量、避免变形、保持一致”
一类词，既没有改变任何可执行事实，又让下一次失败失去可比性：文本变了，但没人说得清变的是
哪一条约束。若诊断指向结构，就改结构。

处置要写进观察或审查记录，说明选了哪一种、依据是上面哪一条。不写处置直接给修订，等于默认
所有缺陷都该由提示词修——这通常是最贵的假设，也是把“抽卡”当成方法的起点。

只有选择了局部编辑或改写、且缩小了原文要求范围时，才建立补拍或替代版；它们的记账方式见
[阶段契约](stage-contract.md) 的参考媒体与补拍一节。

## 单变量有界修订

每次只改变当前诊断需要的变量；必须联动的变量一起说明。修订 finding 至少包含准确目标 refs、
诊断、`change_set`、`preserve_set`、联动理由、预期可观察变化和仍未知内容。保留剧本原文覆盖、角色
身份、镜头目的、信息权限和终点义务。同一失败不能靠重复提交完全相同的提示词解决。

例：远景里细小眉部标记不可读，不把“所有远景都改特写”提升成规则；本项目可改用轮廓与服装结构
承担远景识别，同时让近景继续保留眉部细节。三人同时独立动作导致注意中心混乱时，先保留一个主要
动作，让其他人用立场不同的延迟反应；这仍是当前 scene/shot/config 的候选诊断。

## 复核与边界

修改后让创作者确认当前版本；后续明确请求复审时，只重新读取受影响范围。观察只证明记录里直接写明的
现象，不证明市场表现、普遍模型能力或最终成片质量。私有观察保留在项目/维护者边界，公共 reference
只能通过 de-copy、反例、盲测和独立 promotion 流程吸收可迁移机制。

# Evidence-Based Review Method

## Rule classification

- `structural_invariant`: objectively checkable integrity; validators may block it.
- `reviewed_invariant`: semantic integrity that needs cited evidence.
- `craft_default`: a recommended method that may change for a stated reason.
- `taste_option`: a creator choice that remains non-blocking.

## Governing know-how

- `REV-01` — Run mechanical checks before spending attention on taste.
- `REV-02` — Every finding names a bounded target, evidence, impact, required outcome, owner and severity.
- `REV-03` — A semantic-invention finding pairs the authoritative fact with the conflicting downstream fact.
- `REV-04` — Prefer a reviewer who did not author the version; disclose self-review and keep owner editing separate.
- `REV-05` — Diagnose repeated/generic mechanisms at exact locations rather than applying an “AI-ish” label.
- `REV-06` — Alternative preferences remain notes unless the current choice violates an accepted constraint.
- `REV-07` — An end-to-end drafting request does not imply creator acceptance.

## Review scope

Start from the current creator-visible files and the constraints the creator has explicitly chosen. Prefer an
uninvolved reviewer or isolated context when available; otherwise perform an honest self-check and say so in the
review Markdown. A reviewer label is disclosure, not authenticated identity.

If a target changes during review, reread that target before recording the verdict. Do not recursively invalidate
unrelated findings.

## Mechanical before taste

Mechanical examples:

- missing or duplicate Markdown IDs, broken links or unresolved references;
- unknown asset variants or contradictory camera flags;
- explicit segments not matching their declared duration;
- readable text conflicting with the accepted text policy;
- a stage document silently taking over facts owned by another document;
- delivery containing private or unapproved material.

Semantic examples:

- downstream action changes story meaning;
- a scene has no opposition or turn;
- a keyframe implies several moments;
- action load crowds out performance;
- escalation repeats the same mechanism;
- a prompt preserves the wrong identity.

## Finding anatomy

A useful finding contains:

1. stable diagnostic/rule ID when one exists;
2. project-relative file plus heading ID, line number or shot when useful;
3. bounded quotation or conflicting facts;
4. audience, continuity or production impact;
5. required outcome and preserve set, not ghostwritten replacement prose;
6. owner, severity and open/closed status.

“The dialogue is weak” is invalid. A finding should identify the exact exchange, say what fails to change, and tell
the write owner what outcome must be restored.

The review Markdown cites the current file name, heading ID, line number or a necessary short quotation directly.
It does not copy upstream snapshots, invent record IDs or create another version of the source material.

## Cross-layer synthesis

Trace important moves end to end: story fact, asset decision, shot boundary, keyframe, motion and next-shot state.
Resolve upstream meaning first; do not polish prompt wording when the shot or asset binding is wrong.

## Revision and re-review

Group duplicate findings and route them to the owning skill. A revision request states the target outcome, preserve
set and review scope to rerun. On a later explicit re-review request, read the current version, confirm the finding is addressed, check the
preserve set and close or retain each affected finding. A different reviewer is useful but not mechanically required.

## Anti-template review

Do not use a banned-word list. Look for repeated mechanisms, interchangeable character voices, abstract intensity
without playable behavior, generic quality adjectives burying identity, automatic reaction close-ups and decorative
camera movement. Cite location and impact while preserving deliberate genre rhythm.

# Assets And Asset-Image Prompt Rubric

## Occurrence and decision

- Does every extracted occurrence point to a source block?
- Is it production-relevant rather than every noun in the screenplay?
- Is the decision explicit: reuse, new identity, new variant, or unresolved?
- Were pronouns, aliases, groups, memories, portraits, and screen content handled
  without guessing?

## Identity versus variant

### Character / Look

Identity: stable face/body/hair anchors, distinguishing marks, voice/behavioral
identity. Look: wardrobe, makeup, hair arrangement, injury, dirt/wetness, disguise,
age/weathering state, validity range.

Fail when a costume change creates a new person or incompatible Looks mix in one
prompt without story reason.

Relationship labels may guide current blocking, gaze, and social presentation,
but they do not prove beauty, ugliness, body type, skin tone, or facial morality.
Fail when protagonist/antagonist status silently invents those identity traits;
creator-approved idealization or deliberate counter-casting remains a taste choice.

### Voice direction (optional, `AST-07`–`AST-12`)

Only reviewed when `视觉设定.md` records a voice direction. Timbre is carried by a
named reference recording, not by prose: identity is the reference plus the
creator's current pronunciation choices, and the text alongside it exists to
select or judge a voice, never to stand in for one.

Fail when:

- a project has no reference and a paragraph of adjectives is standing in for
  identity — the voice section must say `待选型` instead;
- a binding omits what it controls and what it must not, or lets the take's
  emotion, the recording space (reverb, mic distance) or background noise into
  identity (`AST-08`);
- a claim about what is audible in a reference has no creator description and no
  authorized listening observation, yet is written as established fact (`AST-09`);
- one proper noun appears with two accepted spellings anywhere in `视觉设定.md`
  (`AST-10`) — this one is structural and blocks;
- two characters designed together are bound to confusable references and no
  distinguishing trait names the nearest neighbour (`AST-11`);
- a selection criterion is an emotion word, carries no counter-example, or the
  list has grown past a handful (`AST-12`);
- reference audio bytes, a provider parameter, a model name, a task field or a
  URL appear in `视觉设定.md` or the delivery package.

### Location / View

Identity: architecture, layout, entrances, zones, anchors, materials, navigation.
View: camera-facing orientation/zone, time/weather/light state, visible anchors.

Fail when each camera angle becomes a new unrelated location or geography changes
silently between scene and plate.

Views of one Location sharing a time/weather state must also share key-light source,
warm/cool priority, contrast direction, and practical on/off state (`IMG-10`). Compare
the group side by side—each plate reading well alone is not evidence. Fail when an
unrecorded difference would read as two times or two rooms once the plates are
intercut; orientation-driven back/front lighting and occlusion shadows are expected
and need only a stated source.

### Prop / State

Identity: scale, shape, material, function, moving parts, marks, text policy.
State: owner/hand/location, open/closed, clean/damaged/wet/bloodied, contents,
validity.

Fail when a prop teleports, changes scale/material, or readable evidence is erased.

## Prompt recipe review

All prompt types need purpose, exact binding, identifying facts, current variant,
composition, background, lighting, text policy, constraints, and exclusions. Then
apply type-specific criteria:

- Does each media reference declare one purpose, the facts it may copy,
  the facts it must not import, and a pixel/text admission decision?
- If a reference is composition-, scale-, or effect-only, did the prompt avoid
  borrowing its identity, wardrobe, content, text, count, or story state?

- **Character sheet:** one identity and coherent Look; useful reference views;
  neutral enough background/light to recognize anchors; no story action chain.
- **Location plate:** navigable geography, orientation, fixed anchors, material,
  palette, light direction, atmosphere; normally empty of cast.
- **Prop plate:** scale cue, shape, materials, wear, function/moving parts, current
  state, viewing angle, isolation, text policy.
- **Edit delta:** exact target and region, changes, preserve set, expected
  continuity impact; no unrelated regeneration.

## Prompt quality failures

- quality/style boilerplate appears before or instead of identity/geography/scale;
- prompt copies the whole 设定集 rather than the needed variant;
- character description mixes immutable anchors with accidental pose;
- location prose is rich but cannot orient entrances/zones;
- one character or prop is assigned to mutually exclusive positions, hands, or
  relationship lines in the same frozen instant;
- prop has no scale or text state;
- negative constraints contradict the required visible fact;
- edit request says “make better” without target/change/preserve;
- `图片提示词.md` contradicts the current identity, state or text policy in `视觉设定.md`;
- private URL, source ID, provider task field, or operator complaint leaks in.
- “use the whole reference” does not say what may or may not be copied.

Prompt prose elegance is secondary to recognition, reuse, continuity, and clear
control of the current operation.

# 原著分析审查表

## 目录

- [审查对象](#审查对象)
- [先跑结构校验](#先跑结构校验)
- [抽样声明](#抽样声明)
- [事实可溯源](#事实可溯源)
- [功能提取质量](#功能提取质量)
- [归并质量](#归并质量)
- [改编判定与候选集](#改编判定与候选集)
- [不属于本表](#不属于本表)

## 审查对象

`项目开发/source-analysis/` 下由 `$short-drama-novel-analyze` 发布的分析层：
`_index.json`、`triage.md`、`chapters/*.md`、`story-units.md`、`rhythm-and-emotion.md`、
`characters.md`、`world.md`、`adaptation-value.md`、`episode-candidates.jsonl`。

规则编号引用该技能的 `NVA` 表。审查结论按 `NVA-xx` 定位，不自造编号。

## 先跑结构校验

在读内容之前跑可证明的检查，命中即为 `structural_invariant` 缺陷：

```bash
python3 {novel-analyze 技能目录}/scripts/novel_index.py verify \
  项目开发/source-analysis/_index.json 输入/{原文文件}
python3 {novel-analyze 技能目录}/scripts/novel_index.py coverage \
  项目开发/source-analysis/_index.json 项目开发/source-analysis/chapters
```

- `verify` 不通过（`NVA-01`）：索引与原文已经对不上，其后每一条引用都指向错误位置。
  这一条独立阻断，不必继续读内容。
- `coverage` 的 `missing` 非空而聚合产物已存在（`NVA-03`）：聚合建立在缺章之上。
- `unmatched_files` 非空：有文件名写歪，既不算覆盖也不算缺章，指出具体文件名。
- `_index.json` 的 `problems` 非空却仍进入了后续阶段：分析建立在一份自己报错的索引上。
- `ignored_heading_units` 与 `chapter_unit` 不合理（例如一本 `第N章` 分章的书选中了 `节`）：
  切片单位判错，章表整体不可信。

## 抽样声明

`triage.md` 属于抽样产物（`NVA-05`）。逐条核对：

- 第一行是否写出覆盖率与样本章号；
- 三类判定比例的分母是否写明是抽样章数，而不是全书章数；
- 是否出现了抽样之外章节的事实断言；
- 是否越权产出了 `episode-candidates.jsonl` 的条目。

抽样结论本身对不对**不是本表的判断对象**——它是假设。要判断的是它有没有把自己写成结论。

## 事实可溯源

`NVA-02`、`NVA-07`。聚合产物离原文两跳，这里是分析层最容易出错的地方：模型会用
世界知识和「合理性」把原文没给的字段补成一个看起来坐实的事实。

抽查 `characters.md`、`world.md`、`adaptation-value.md` 里的硬事实——等级、数值、
距离、势力数量、谁对谁说了什么、某人出现在哪几章——逐条回查它引用的白描或原文：

- 回查命中：通过；
- 回查不到，且写成了确定事实：`reviewed_invariant` 缺陷，要求改写为「原文未明确」或删除；
- 回查不到，但已写「原文未明确」：通过。

同时检查跨指代串用：坐骑的等级被安到骑手头上、A 的台词记成 B 的、相邻章的统计数字互换。

## 功能提取质量

`NVA-06`。抽查若干章 `chapters/ch-<N>-extract.md`：

- 概要是否回答了「谁的处境、认知或筹码变了」，而不是缩写剧情；
- 情节点的白描是否是可观察事实——出现「通过对话得知」「展现了实力」「感到愤怒」
  这类叙事框架词或心理断言的，是把结论写在了证据位上；
- 每条情节点是否回答了改变了什么（权力/信息/关系/暴露/资源/时间/代价至少一项）；
- 载体记录是否存在且填了通道栏——缺了它，`needs_carrier` 判定就没有原始依据。

## 归并质量

`NVA-08`。检查 `characters.md`：

- 是否有描述性称谓（「红衣女子」）或头衔（「护卫队长」）触发了合并——这两类永不合并；
- 绰号合并是否给出了可指出的同指证据，而不是「读起来像同一个人」；
- 合并后是否保住了戏剧作用、知识范围、关系位置与因果桥梁；名字变少不是合并质量的证据；
- 每条是否带 `unresolved` 与来源引用。

`story-units.md` 的阈值自检（归属置信、覆盖率、重叠率）是否跑过、结果是否写出。
重叠率超线而没有复核说明的，指出具体是哪两个单元。

## 改编判定与候选集

`NVA-09`、`NVA-10`。

- 三类判定是否逐单元落定，`needs_carrier` 是否逐个写了原载体、新载体、保住了什么、
  改变或失去了什么——「改变或失去」写「无」的，是没写完；
- 是否有 `prose_only` 被改写成 `needs_carrier` 而新载体需要旁白才成立；
- 候选集是否按局部戏剧结果与精确交接切，而不是按章号或字数平均切；
- 每条候选是否能回答四问（进入认知、兑现了哪部分承诺、出去压力、下一集继承什么）；
  一条承诺都不兑现的候选集要指出来；
- 相邻候选的出去状态与进入认知是否对得上；
- `prose_only`、被跳过的章、散落清单是否出现在交接摘要里；
- `adaptation-value.md` 开头是否有快评回填对照。

## 不属于本表

- **改编方案本身**：从哪里开篇、保留哪条线、合并哪些人物是创作者与
  `$short-drama-develop` 的决定（`NVA-12`），审查可以提出风险，不得据此阻断交付。
- **原著写得好不好**：本表不评价原作质量。
- **剧本、资产、提示词、分镜**：走各自的审查表。
- **集数对不对**：分析层只给量级，集数不在这里判。

# Story And Script Rubric

## 目录

- [Promise](#story-promise-and-engine)
- [Episode](#episode-shape)
- [Entry and serial memory](#entry-character-and-serial-memory)
- [Scene](#scene-test)
- [Action](#action-and-production-meaning)
- [Dialogue](#dialogue)
- [Findings](#common-findings)

## Story promise and engine

- Can the creator state protagonist, pursuit, costly opposition, and recurring
  audience payoff without relying on a genre label?
- Can the conflict produce varied pressure, or does every episode repeat the same
  misunderstanding, humiliation, rescue, or reveal?
- Does escalation change power, knowledge, relationship, exposure, cost, or time?
- Do setups/payoffs and episode handoffs resolve to explicit records?

## Episode shape

- What pressure is active at the opening?
- What does the protagonist want now, and what resists it?
- Which choice/action causes the directional turn?
- If the episode frames that turn as a consequential choice, what live value does each
  executable direction protect, and what cost is newly caused by the action (`SCR-13`)?
  If it is an ordinary decision or single-path pursuit, leave this test inactive rather
  than manufacturing a dilemma.
- Conditional does not mean cursory: when the episode itself foregrounds a choice,
  evidence carrier, deadline, or rule, does resistance, action, and consequence dramatize
  it, rather than merely naming it in dialogue?
- Could a viewer identify those stakes from the screenplay alone, without access to
  the upstream brief or episode card?
- Do explicit brief facts, must/forbid constraints, genre contract, and required exit state
  outrank craft defaults, or did the screenplay invent precision, records, resources,
  procedures, relationships, or mechanisms merely to display a rule?
- When a choice cost or deadline is essential, was it perceptible before the decision,
  or invented at decision time by a convenient new condition?
- What part of the promised experience is delivered before the outgoing hook?
- What exact state enters the next episode?
- Before the outgoing hook, what local dramatic result has already landed?
- Which behavior, relationship history, line, silence, spatial choice, or object makes the
  protagonist's private reason legible? Do not require a recurring object when another
  carrier already does the work.
- Does the ending fulfill the episode's viewing contract through consequence, relationship,
  irony, afterimage, atmosphere, or intentional openness? A new external event is optional.
- If the ending declares a path closed or a consequence irreversible, do later beats
  accidentally contradict that claim without presenting an intentional new change?
- Whose choice caused that result (`STY-13`)? If it arrived by outside force, cite the
  protagonist's earlier action that made it arrive now, and what they did with it.
  A protagonist who only endures until rescue is this episode's audience, not its lead.

A capacity estimate (`STY-16`) is informational, never a blocking finding. If a
planned episode's shot/duration magnitude is far from the project's own accepted
ratios, note it as an advisory observation with the sampled basis, and leave the
resolution to the creator. Never derive a word, line, or shot quota from it, and
never compare against another project's numbers.

When the premise grants foreknowledge or externally authorized ability (`STY-17`), keep
two layers apart and cite each from its own place:

- **Contract layer** (creator-accepted, in the story engine): is the device contract
  accepted before the device first takes effect, recording scope, failure conditions,
  cost, and whether the device's own declarations are reliable?
- **Disclosure layer** (per episode, in the information-permission field): what do the
  characters and the audience know right now?

Never report partial disclosure as a defect. An audience that does not yet know every
boundary is the normal case, and late-discovered limits are often the intended suspense.
What is reportable:

- A later device ability or exemption that traces to no contract clause—cite the episode
  and the missing clause. This is retroactive widening whether or not it was announced
  in-fiction.
- A disclosed rule violated later, unless the contract marks the device as unreliable
  and the setup is traceable.
- Strip the device out—does the episode still contain a choice? If not, cite what
  resistance was removed and never replaced.
- What did the opposition learn once the device was in play?
- For foreknowledge: does the information degrade as the timeline diverges, or does the
  author keep inventing reasons to weaken the protagonist? Is the audience's permission
  level held constant across episodes?
- For authorized ability: is the cost visible and landed on something the protagonist
  cares about? Does the device offer options, or decide for them?
- If the device uses an on-screen readable carrier, is the `exact-readable` obligation
  stated instead of coexisting with a global no-text policy?

## Entry, character, and serial memory

- What prior-world fact does the writer need in order to predict present choices?
  Which visible evidence does the audience need now, and which backstory is
  correctly withheld?
- Why is this the useful entry window? Would an earlier start become setup work,
  or a later start remove a consequential choice?
- For each claimed character change, where are the pressure test, choice or
  retreat, local result, cost, and changed visible strategy (`STY-12`)?
- Do world truth, character beliefs, and audience knowledge remain separate?
- For each evidence carrier, what claim does it directly support, and which identity,
  cause, motive, or mechanism remains an unresolved inference (`STY-15`)?
- When a major belief change hinges on contested evidence, is the response limited to
  what was proved, or does the story intentionally preserve/delay uncertainty (`SCR-14`)?
  Leave this test inactive for uncontested facts, comic misunderstanding, subjective
  narration, or clues whose ambiguity is the intended effect.
- When contested evidence is a primary episode engine, does at least one visible state
  change alter which explanations remain live or alter the next action, rather than
  leaving every increment to verbal report? Photographing, bagging, numbering, or logging
  is not a dramatic turn by itself. Once the required inference changes, does testing stop
  unless another live counter-explanation would genuinely change the next action?
- If a proof claim depends on continuity such as connection, sealing, position, time, or
  lack of contact, did preceding action preserve that exact property? A continuity label
  may carry forward a shown state; it cannot prove that an unseen event or contact never occurred.
- Does active serial memory preserve character/relationship state, information
  permissions, setup debt, rhythm direction, and the exact physical handoff?
- Do external pressure and emotional load rise, fall, or diverge for a reason?
  A breathing scene should process a consequence rather than suspend the story.

Do not require a fixed hook type, beat count, reversal, climax timestamp, or
dialogue quota.

## Scene test

For a scene organized around active pursuit or conflict, ask:

1. Why must it exist?
2. Whose agenda organizes it?
3. What force opposes that agenda?
4. What traceable fact, leverage change, cost, authority, or choice makes the prior
   strategy fail? An opponent merely becoming silent or leaving is not enough.
5. What exit state pressures the next scene?

A quiet scene can pass when pressure and change are legible. Atmospheric, ritual,
montage, transition, and consequence-processing scenes may instead justify their
function through a necessary change in knowledge, relationship, pressure, rhythm,
or production state; do not invent an opponent or strategy failure merely to make
them fit this checklist. A loud scene can fail when nothing changes.

## Action and production meaning

- Are internal states expressed through playable behavior, evidence, or deliberate
  VO/OS?
- Are actions spatially coherent and consequential?
- Are exact on-screen text, prop text, SFX, VO/OS, and transitions tagged?
- Does prose avoid camera/prompt boilerplate while retaining production-critical
  facts?
- Do supporting characters who receive substantial dramatic emphasis have a goal, judgment,
  or strategy of their own? Incidental, transactional, choral, and environmental roles need
  not all alter the main plot.
- Does a central participant who supplies the main leverage, opposition, or cost remain
  strategically present through the turn and response, rather than becoming a passive prop
  once the protagonist acts?
- If that participant's leverage disappears, what already-established action, spatial fact,
  authority, relationship, or choice made it disappear? Do not infer neutralization merely
  from the protagonist completing one step.
- When a literal precise deadline is foregrounded and audience-auditable, does its action
  chain fit, or does the screenplay make compression, changed method, changed objective,
  or failure legible (`SCR-16`)? Qualitative urgency must not be upgraded into invented
  minutes, timestamps, notifications, or records. Do not apply a real-time test to montage,
  ellipsis, subjective time, or declared stylization.
- When the brief defines a limited number of attempts, turns, breaths, beats, or other units,
  does each unit end with its required visible state (`SCR-17`)? Labels, counts, requests,
  authorization, preparation, and cleanup after the boundary do not substitute for completion;
  an intentional failure or partial result may count when it is legible at that boundary.
- When exact timestamps share one literal continuity, are they mutually consistent?
- When the current date is necessary to a conclusion, is it supported by a current source?
- Does a compressed process retain only the steps that change strategy, relationship,
  risk, or result, instead of listing interchangeable operations?
- When multiple carriers repeat one pressure or fact, does each add rhythm, viewpoint,
  irony, misdirection, or consequence? If not, which one is redundant?
- Does a solution use established resources and still confront the core obstacle, rather
  than erase it with a newly invented convenience?
- Even when a resource is established, does it change the problem without conveniently
  performing the character's hardest dramatic work for them?
- Does an outside response increase or transform pressure in a way grounded in the work's
  established world, rather than suddenly forgiving, rewarding, or rescuing the character
  to make the ending easy?
- After a mechanism becomes visually clear, does dialogue change the relationship or
  narrow the claim instead of explaining the same mechanism again?
- When the brief gives a target duration but the project has no pacing rates, has the
  writer still performed a real-time read/action pass and removed obviously excessive
  repeated verification, date exposition, or equivalent closing beats?

## Dialogue

- What does each speaker want from the other now?
- What is withheld, reframed, threatened, bargained, accused, or proven?
- Does the line respond to the prior move and alter the next?
- Are voices distinct by worldview, status, relationship, vocabulary, and rhythm?
- Does exposition enter through conflict/evidence/consequence rather than a
  neutral information dump?
- When a long speech is split, does the inserted action change the speaker's tactic
  and give downstream a sourced cut point, rather than pad with a glance or a pause
  (`SCR-09`)? When a long speech carries no internal turn, was it shortened instead
  of split?

Silence, interruption, slang, narration, and sentence length are creator options,
not universal scoring ratios.

## Replaceable realization (`SCR-10`)

Only for beats the creator marked. **An unmarked beat leaves this section
inactive**: do not raise a finding for the absence of a mark, do not guess which
beats need one, and never rate a depiction against a standard this suite does not
carry — it carries none, and predicts no outcome.

On a marked beat:

- Is the dramatic function written as *who is proven or changed*, rather than an
  emotion word? A function stated as "高潮" cannot be used to judge equivalence.
- Does the fallback deliver that same function — same person affected, cost still
  paid, `payoff_refs` and the next episode's entry state still satisfied?
- Does the fallback need a setup the script has not established? Then it is a
  rewrite, not a fallback.
- Is "delete the scene" being offered as the fallback? Deletion removes the
  function itself; the only acceptable variant is an explicit handover naming
  which existing beat now carries it and what that beat must absorb.
- Is the fallback concrete enough to become scene action, or is it "酌情处理"?

Report pre-emptive sanding as a finding in its own right when the current
depiction was already weakened to avoid a risk nobody stated: the loss is certain,
the benefit is not, and the mark exists precisely so the strong version can stay.

## Common findings

- genre label substituted for a dramatic promise;
- alternatives differ only in wording;
- coincidence carries a major turn with no prepared cause;
- scene repeats known information and leaves state unchanged;
- cliffhanger withholds all payoff;
- episode pauses an unfinished action without producing a local result (`STY-13`);
- first episode dumps the backstory reservoir instead of selecting an active entry;
- a declared character arc has no pressure test, choice, cost, or changed strategy;
- serial summary omits an information permission or unpaid setup obligation;
- generic emotion adjectives replace visible performance;
- every character explains the plot in the same voice;
- downstream production requirement was never marked in screenplay truth.
- a redundant `[连续性]` tag repeats an exit state already explicit in the final action;
- a story-critical ending state appears without a prior transition;
- the script uses atmosphere, silence, or a black frame to avoid landing a result the episode
  promised, rather than as an intentional ending form;
- a beat is sold as a consequential choice after one direction has already become valueless
  or impossible (`SCR-13`);
- contested evidence produces a broader conclusion than the evidence or intentionally
  incomplete verification supports (`SCR-14`);
- a claimed proof relies on a continuity property the preceding action already destroyed,
  or on a continuity label asserting an unseen negative event;
- a local payoff erases its established residue or replaces meaning with a slogan (`SCR-15`);
- a cost framed as central pressure automatically resets at success, leaving no material
  effect on ability, body, resource, relationship, or next action;
- a central participant supplies the opening leverage or cost but becomes a passive prop
  through the decisive action;
- the core opposing force disappears only because its holder becomes silent, stops acting,
  or leaves, without a traceable loss of leverage, accepted cost, or changed strategy;
- a literal, audience-auditable deadline succeeds only through unexplained speed, or
  qualitative urgency is upgraded into invented precise timing (`SCR-16`);
- a limited unit is counted before its required state completes, with the completion moved
  outside the boundary (`SCR-17`);
- a newly invented resource, permission, or ability removes the central obstacle;
- a limited result is renamed as a broader success or truth than the scene demonstrated;
- repeated carriers restate one pressure without adding viewpoint, rhythm, irony, or consequence;
- a second same-direction decision, closing line, or maxim merely translates a change,
  punchline, or metaphor that the preceding action already completed;
- post-result action unintentionally contradicts a consequence the screenplay called irreversible.

# Storyboard, Keyframe, And Motion Rubric

## 目录

- [Coverage](#coverage-and-meaning)
- [Shot](#shot-purpose-and-geography)
- [Keyframe](#frozen-keyframe)
- [Motion](#motion)
- [Continuity](#cross-shot-continuity)
- [Findings](#common-findings)
- [Production risks and authorized observations](#production-risk-and-authorized-observation-checklist-rev-08)

## Coverage and meaning

- Does every production-relevant block have a disposition?
- Are omissions/repeats explained?
- Does each shot preserve the source action, dialogue, information, and reaction?
- Has downstream work invented or deleted a story fact?

## Shot purpose and geography

- For a high-value scene with an accepted coverage audition: did the approaches
  genuinely differ — in knowledge timing, audience alignment, performance space,
  strongest image, landing, losses, or production fit?
- Does the formal plan bind the approach the creator selected, rather than the first draft?
- When a scene visual plan was used: do its start/end audience positions, spatial
  pressure, camera rhythm, reaction landing, and sound movement carry **one** dramatic turn?
- Does that plan stay clear of owning shot boundaries? (Ordinary scenes need no plan
  merely to satisfy a form.)
- What changes for audience or character by the shot end?
- Why is this a new shot?
- Do framing and camera behavior serve attention, alignment, pressure, reveal, or
  rhythm rather than decorate the prose?
- Are Location/View, axis, screen direction, eyelines, entrances, positions,
  hands, and props coherent?
- Are exact asset variants bound?
- Does the shot expose every fact it must carry while protecting
  facts the source withholds until a later action or cut?
- Do crop, occlusion, focus, back view, and offscreen space serve that information
  permission rather than accidentally reveal or conceal it?

## Frozen keyframe

- Can all described facts exist in one still instant?
- Does it project the start state written for this shot?
- Are focal hierarchy, composition, camera/lens, geography, pose/gaze/hands/prop,
  expression, and light legible?
- Does it avoid ordered actions, performance arcs, camera moves, or transforming
  environments?
- Read the finished keyframe text, not the shot's intent: is every visible character,
  place, and prop whose identity, Look, or geography must stay recognizable listed in
  this shot's `视觉依据` (`SHT-22`)? A second body that entered the composition while the
  frame was being written is the usual miss.
- Does each declared 控制 scope stay inside what this frame can carry, and is nothing
  bound merely because it was bound in the previous shot (`SHT-24`)?
- When real reference images are bound, does every `REF-...` slot declare a 用途, so the
  shot says which start frame and which identity/geography/prop pictures it sends
  (`SHT-25`, `VID-24`)?
- Is anything the frames need kept consistent across shots — a carried prop, a garment —
  absent from `视觉设定.md` entirely, so it can appear in no shot's basis at all? The
  mechanical check cannot see this: an entry that does not exist cannot be reported missing.

## Motion

- Does it start from the accepted frame/boundary?
- Are subject actions ordered and small enough to preserve intended performance?
- Does performance change express the story move rather than stack synonyms?
- In multi-character motion: do the actors who actually change have distinct,
  readable triggers, choices, leaks, or landings — as this shot needs, not one
  identical arc per actor?
- Is attention handed off only where it truly transfers, rather than for
  synchronized reaction?
- Does any text-readiness claim cite the current creator-visible inputs and a real blocking gap?
- Does it avoid any claim about generated media quality or create a second readiness truth?
- Is camera behavior coherent and motivated?
- Are environment motion, dialogue, SFX, and audio included only when relevant?
- Does the described end match the storyboard's written end state without rewriting the next shot?
- When a reference frame carries appearance/composition, does motion prose avoid
  dumping the full visual 设定集?
- Does every claim about text-bearing reference pixels cite a creator/reference-owner
  description or an authorized input-reference observation? Without that evidence,
  is admission still `unverified` instead of pretending a negative prompt solved it?
- For any selective transform, are the accepted trigger, exact target scope,
  end geometry/state, and preserve set explicit? Do non-target people, props,
  text surfaces, and spatial anchors keep their required position, count, and state?
- Does each media reference state its exact purpose, what may be copied, and what
  must not be copied, rather than treating all visible pixels as authority?

For a copyable body (`VID-22`, `VID-23`), check that actions and sound match the
source and that the timeline accounts for the intended ambience or silence.
A summary must not introduce a layer absent from the shot. H3's
`non_diegetic_music: N/A` is a valid empty music layer.

Report a concrete contradiction, omission or ambiguity. A negative clause is
not a defect by itself; do not impose a clause count or assume that negation
causes the model to generate the excluded content. Keep model-specific
observations scoped to their tested model and execution path.

For a pickup or alternate, ask these separately:

- Does the pickup/alternate name its master by visible `MOTION-...` heading?
- Is every source obligation assigned to the master, this version, another named version or a requested storyboard revision?
- Are the changed items and the items that must remain unchanged explicit?
- Is replacement only requested here? The review Markdown decides whether the master remains primary or the alternate replaces it.

For music, ask these separately (`VID-14`):

- Is intent written as a relative entry/exit/duck against neighbouring shots,
  rather than an independent cue per shot?
- Do adjacent annotations actually join?
- Does the text ask for a per-shot music bed against an accepted timeline-layer plan?
- Whether a rendered clip carries a baked-in track is **not decidable here**. Cite it
  only from an authorized text observation record; otherwise keep it `unverified`
  and never infer a mix result from prose.

Explicit timing that does not sum exactly to its shot's accepted duration—over or
under—is a structural error. Untimed overload is a
reviewed feasibility question: cite which action/performance/story beat would be
lost, not a universal verbs-per-second formula.

Container arithmetic is a separate structural check (`VID-13`). Count the accepted
shots a delivery container carries, then confirm its duration equals the sum of
their accepted durations. For a multi-shot container, confirm the members are
contiguous in source order, share one geography/asset binding chain, do not cross a
scene boundary, and each remains independently reviewable. A space or subject jump
belongs on a member boundary; the same jump inside a member's timed segment is a
hidden cut. Report an arithmetic mismatch and a hidden cut as two findings, not one.

- Is the axis recorded as two named anchors, a stated working side, and a per-character
  screen position — rather than a placeholder?
- In a shot-reverse-shot pair, are the two screen directions complementary?
- Bare left/right always means **screen** left/right. Where a subject's own side is
  meant, does the text name the subject?

## Cross-shot continuity

Trace Look, injury, dirt/wetness, emotion/knowledge, position/facing/gaze, hands,
held prop, prop owner/state, location/time/weather/light, axis, and screen
direction. Distinguish unexplained contradiction from declared montage,
ellipsis, dream, or deliberate disorientation.

## Common findings

- beautiful shot with no dramatic purpose;
- dialogue covered but consequential reaction absent;
- anonymous asset or wrong variant;
- cross-location/time action hidden in one ordinary shot;
- keyframe contains “first/then/finally”;
- locked camera also pans or pushes in the same interval;
- motion invents a grab, injury, transfer, relationship change, or line;
- a selective transform removes, copies, or reshapes a non-target person, prop,
  text surface, or spatial anchor because its preserve set was unspecified;
- end pose/prop state disagrees with next start;
- every emotional beat uses the same close-up/push template;
- provider batching is mistaken for editorial shot structure.
- a narrowed pickup silently replaces the master and drops dialogue, reaction,
  reveal, end-state, or creator-directive obligations.

## Production-risk and authorized-observation checklist (REV-08)

本套件不查看媒体。先把下列项目当作文字风险，引用准确的 prompt/spec 说明为什么会造成
执行歧义或违背已接受约束；只有创作者提供了授权的文字观察记录时，才能称为已观察缺陷，
并把该记录作为外部证据引用。没有观察记录时保持结果未知，不从任务成功、结果地址或提示词
存在推断成片质量。

需要项目校准时，先区分输入参考与生成结果。后一种观察只有在绑定准确的提示词/镜头标题、参考顺序、
制作形态/配置、观察方法和限制时才可引用；finding 同时给出最小修改项与保持项，并保持结论只在该项目
和版本条件下有效。

短剧生产中需要防范的文字风险或获授权观察包括：

- on-screen text or subtitle residue despite a declared no-text constraint;
- a text-bearing reference admitted under no-text or exact-readable policy
  without an allowed surface or a crop, clean, mask, or replace decision;
- background music implied where the audio boundary allows sound effects only;
- wardrobe or look drift against the bound reference (re-describing clothes the
  reference already fixes invites drift — flag redundant appearance prose);
- 180° axis violation or eyeline mismatch across consecutive shots without a
  declared transition;
- lip-sync mismatch: dialogue bound to the wrong character, inner monologue
  written as mouthed speech, or extra lines the source dialogue never contained;
- explicit segment timings that do not sum exactly to the shot duration, in either direction;
- emotion-intensity mismatch between stated level and described performance
  (a declared 9/10 rage performed as mild irritation, or the reverse).

# 审查阶段契约

本阶段只拥有审查结论与修订要求，不改写 owner 来源。需要落盘时使用创作者可读 Markdown，引用当前
文件名、标题 ID、行号或短引文；不建立 JSON/JSONL、来源快照、哈希或接受状态。

审查可以由独立 reviewer 或明确标注的自检完成。媒体不可见时保持未知；外部生产仍需要自己的显式确认。

## 本阶段规则

### `REV`

| ID | Class | Knowledge |
|---|---|---|
| REV-01 | structural_invariant | Run mechanical checks before spending creative review attention. |
| REV-02 | structural_invariant | A finding names a visible file and heading/shot/prompt ID, and includes evidence, impact, required fix, owner, severity and status. |
| REV-03 | reviewed_invariant | Semantic invention cites the source fact and conflicting downstream fact. |
| REV-04 | craft_default | Prefer a reviewer who did not author the current targets; disclose self-review, and keep reviewer findings separate from owner edits. |
| REV-05 | craft_default | Diagnose repeated structure or generic language with location and impact; do not label output merely "AI-ish". |
| REV-06 | taste_option | Alternatives remain notes unless they violate an accepted creator constraint. |
| REV-07 | structural_invariant | An end-to-end drafting request cannot impersonate creator acceptance; preview chains remain provisional and undeliverable. |
| REV-08 | craft_default | When authorized text notes report production defects, trace text/subtitle residue, music-boundary violations, wardrobe drift, axis breaks, or lip-sync mismatch to the exact prompt/spec text and keep unobserved outcomes unknown. |
| REV-09 | reviewed_invariant | After prompt revision or repackaging, recheck source coverage and every applicable accepted directive; correct asset bindings alone do not prove compliance. |
| REV-10 | reviewed_invariant | A project-calibration finding distinguishes input-reference from generated-result observation, binds the exact project, the prompt/spec records it observed, stable reference slots, production configuration, method and limits, and—when its disposition calls for a change (see REV-11)—proposes the smallest owner-routed one with a preserve set; it does not generalize across projects or infer quality from task state. |
| REV-11 | reviewed_invariant | A calibration finding carries `disposition` (keep, post_production, targeted_edit, resubmit, rewrite) and `disposition_rationale` before any revision text, justified by whether the defect is text-controllable and whether it has already recurred. Dispositions that call for no change leave `required_change` empty rather than inventing one. Resubmitting identical text and appending quality adjectives are not repairs; a recurring defect routes to a structural change instead. Findings outside project calibration use `not_applicable`. |

规则分级由高到低：`structural_invariant`（结构缺陷，阻断）、
`reviewed_invariant`（需证据判断）、`craft_default`（常用做法，可覆盖）、
`taste_option`（创作者选择，不作缺陷）。创作者已接受的事实优先于本表。

#!/usr/bin/env python3
"""Validate standalone review findings and their verdict summary."""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path
from typing import Any, NamedTuple

MINIMUM_PYTHON = (3, 9)
if sys.version_info < MINIMUM_PYTHON:
    raise SystemExit("review_check.py requires Python 3.9 or newer")

SKILL_ROOT = Path(__file__).resolve().parents[1]
HASH_RE = re.compile(r"[0-9a-f]{64}")
SEVERITIES = {"fatal", "error", "warning", "note"}
STATUSES = {"open", "closed"}
VERDICTS = {"APPROVE", "APPROVE_WITH_NOTES", "REVISE", "PROVISIONAL"}
DISPOSITIONS = {"keep", "post_production", "targeted_edit", "resubmit", "rewrite", "not_applicable"}


class ValidationError(ValueError):
    pass


# ---------------------------------------------------------------------------
# REFERENCE RESOLVER
#
# A file declares each upstream snapshot once, and every reference names the
# declared snapshot plus the record. This skill carries its own copy so it stays
# runnable after copying only this directory; do not import it from elsewhere.
# ---------------------------------------------------------------------------

SOURCES_RECORD_TYPE = "sources"
SOURCES_SCHEMA_VERSION = "1.0.0"


class ResolvedRef(NamedTuple):
    """An upstream reference with its snapshot resolved."""

    owner: str
    artifact: str
    record_id: str | None
    field: str | None
    authority: str | None


class RefFinding(NamedTuple):
    """A structural defect in a reference object."""

    code: str
    location: str
    detail: str


def load_sources(document: Any) -> dict[str, dict[str, Any]]:
    """Return the ``sources`` declaration of a parsed file, or ``{}`` if absent.

    Accepts a parsed ``.json`` document (a dict) or the parsed record list of a
    ``.jsonl`` file, whose declaration lives on the first record.
    """
    if isinstance(document, list):
        document = document[0] if document else None
    if not isinstance(document, dict):
        return {}
    declared = document.get("sources")
    if not isinstance(declared, dict):
        return {}
    return {key: value for key, value in declared.items() if isinstance(value, dict)}


def resolve_ref(
    ref: Any, sources: dict[str, dict[str, Any]], location: str
) -> tuple[ResolvedRef | None, RefFinding | None]:
    """Resolve a reference object written in either the compact or expanded form."""
    if not isinstance(ref, dict):
        return None, RefFinding("REF_IS_NOT_AN_OBJECT", location, f"got {type(ref).__name__}")
    src = ref.get("src")
    if isinstance(src, str):
        entry = sources.get(src)
        if entry is None:
            return None, RefFinding(
                "REF_SRC_IS_NOT_DECLARED", location, f"src {src!r} has no sources entry"
            )
        owner, artifact = entry.get("owner"), entry.get("artifact")
        if not (isinstance(owner, str) and isinstance(artifact, str)):
            return None, RefFinding(
                "SOURCE_ENTRY_IS_INCOMPLETE", location, f"sources[{src!r}] needs owner/artifact"
            )
    elif all(isinstance(ref.get(key), str) for key in ("owner", "artifact")):
        owner, artifact = ref["owner"], ref["artifact"]
    else:
        return None, RefFinding(
            "REF_HAS_NO_UPSTREAM_BINDING", location, "needs src, or owner+artifact"
        )
    optional = {
        key: ref[key] for key in ("record_id", "field", "authority") if isinstance(ref.get(key), str)
    }
    return (
        ResolvedRef(
        owner,
        artifact,
            optional.get("record_id"),
            optional.get("field"),
            optional.get("authority"),
        ),
        None,
    )


# ---------------------------------------------------------------------------
# END REFERENCE RESOLVER
# ---------------------------------------------------------------------------


def split_sources(
    records: list[dict[str, Any]],
) -> tuple[dict[str, dict[str, Any]], list[dict[str, Any]]]:
    """Separate a leading ``sources`` header record from the payload records."""
    first = records[0] if records else None
    if isinstance(first, dict) and first.get("record_type") == SOURCES_RECORD_TYPE:
        return load_sources(first), records[1:]
    return {}, records


def resolve_input(value: str | Path) -> Path:
    path = Path(value).expanduser()
    if path.exists() or path.is_absolute():
        return path
    return SKILL_ROOT / path


def load_jsonl(value: str | Path) -> list[dict[str, Any]]:
    path = resolve_input(value)
    records: list[dict[str, Any]] = []
    for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
        if not line.strip():
            continue
        try:
            record = json.loads(line)
        except json.JSONDecodeError as exc:
            raise ValidationError(f"{path}:{number}: invalid JSON") from exc
        if not isinstance(record, dict):
            raise ValidationError(f"{path}:{number}: record must be an object")
        records.append(record)
    return records


def load_object(value: str | Path) -> dict[str, Any]:
    path = resolve_input(value)
    try:
        document = json.loads(path.read_text(encoding="utf-8"))
    except json.JSONDecodeError as exc:
        raise ValidationError(f"{path}: invalid JSON") from exc
    if not isinstance(document, dict):
        raise ValidationError(f"{path}: verdict must be an object")
    return document


def text(record: dict[str, Any], key: str, label: str, *, empty_ok: bool = False) -> str:
    value = record.get(key)
    if not isinstance(value, str) or (not empty_ok and not value.strip()):
        qualifier = "text" if empty_ok else "non-empty text"
        raise ValidationError(f"{label}: {key} must be {qualifier}")
    return value


def validate_ref(
    value: Any,
    label: str,
    sources: dict[str, dict[str, Any]],
    *,
    record_optional: bool = False,
) -> None:
    resolved, defect = resolve_ref(value, sources, label)
    if resolved is None:
        detail = f"{defect.code}: {defect.detail}" if defect is not None else "unresolvable reference"
        raise ValidationError(f"{label}: {detail}")
    for key, field_value in (("owner", resolved.owner), ("artifact", resolved.artifact)):
        if not field_value.strip():
            raise ValidationError(f"{label}: {key} must be non-empty text")
    if not record_optional and not resolved.record_id and not resolved.field:
        raise ValidationError(f"{label}: record_id or field is required")


def validate_findings(records: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
    sources, findings = split_sources(records)
    indexed: dict[str, dict[str, Any]] = {}
    for index, finding in enumerate(findings, 1):
        label = f"finding[{index}]"
        finding_id = text(finding, "finding_id", label)
        if finding_id in indexed:
            raise ValidationError(f"{label}: duplicate finding_id {finding_id}")
        indexed[finding_id] = finding
        for key in (
            "diagnostic_code",
            "scope",
            "classification",
            "enforcer",
            "evidence",
            "impact",
            "disposition_rationale",
            "owner_skill",
        ):
            text(finding, key, label)
        text(finding, "required_change", label, empty_ok=True)
        if finding.get("severity") not in SEVERITIES:
            raise ValidationError(f"{label}: invalid severity")
        if finding.get("status") not in STATUSES:
            raise ValidationError(f"{label}: invalid status")
        disposition = finding.get("disposition")
        if disposition not in DISPOSITIONS:
            raise ValidationError(
                f"{label}: invalid disposition {disposition!r}; "
                f"use one of {', '.join(sorted(DISPOSITIONS))}"
            )
        # A finding that blocks delivery has to say what to do about it,
        # whatever its disposition. REV-11 exempts dispositions that call for no
        # change, and routes every non-calibration finding to `not_applicable`
        # -- which is one of the exempt three. So the common case was exempt,
        # and an open `fatal` that told its owner nothing was stamped valid.
        # REV-02 requires the fix; this is where that requirement lands.
        if (
            finding.get("status") == "open"
            and finding.get("severity") in {"fatal", "error"}
            and not str(finding.get("required_change") or "").strip()
        ):
            raise ValidationError(
                f"{label}: an open {finding.get('severity')} finding blocks "
                f"delivery and must state its required change"
            )
        if disposition in {"targeted_edit", "resubmit", "rewrite"} and not finding["required_change"].strip():
            raise ValidationError(f"{label}: disposition requires required_change")
        refs = finding.get("evidence_refs")
        if not isinstance(refs, list) or not refs:
            raise ValidationError(f"{label}: evidence_refs must be a non-empty list")
        for ref_index, ref in enumerate(refs, 1):
            validate_ref(ref, f"{label}.evidence_refs[{ref_index}]", sources)
        validate_ref(finding.get("target_ref"), f"{label}.target_ref", sources)
    return indexed


def validate_records(records: list[dict[str, Any]], verdict: dict[str, Any]) -> dict[str, Any]:
    indexed = validate_findings(records)
    _, findings = split_sources(records)
    verdict_sources = load_sources(verdict)
    text(verdict, "review_id", "verdict")
    scopes = verdict.get("scope")
    if not isinstance(scopes, list) or not scopes or any(not isinstance(item, str) or not item for item in scopes):
        raise ValidationError("verdict: scope must be a non-empty text list")
    artifacts = verdict.get("reviewed_artifacts")
    if not isinstance(artifacts, list) or not artifacts:
        raise ValidationError("verdict: reviewed_artifacts must be non-empty")
    for index, artifact in enumerate(artifacts, 1):
        validate_ref(
            artifact,
            f"verdict.reviewed_artifacts[{index}]",
            verdict_sources,
            record_optional=True,
        )
    validate_ref(
        verdict.get("findings_ref"), "verdict.findings_ref", verdict_sources, record_optional=True
    )
    if verdict.get("review_method") not in {"uninvolved_reviewer", "self_check"}:
        raise ValidationError("verdict: review_method must be uninvolved_reviewer or self_check")
    text(verdict, "reviewer", "verdict")
    if verdict.get("verdict") not in VERDICTS:
        raise ValidationError("verdict: invalid verdict")

    blockers = sorted(
        finding_id
        for finding_id, finding in indexed.items()
        if finding["status"] == "open" and finding["severity"] in {"fatal", "error"}
    )
    declared = verdict.get("blocking_findings")
    if not isinstance(declared, list) or sorted(declared) != blockers:
        raise ValidationError("verdict: blocking_findings must equal the open fatal/error findings")
    if verdict.get("open_blocker_count") != len(blockers):
        raise ValidationError("verdict: open_blocker_count does not match blocking_findings")
    decision = verdict["verdict"]
    if blockers and decision != "REVISE":
        raise ValidationError("verdict: open blockers require REVISE")
    if not blockers and decision == "REVISE":
        raise ValidationError("verdict: REVISE requires an open blocker")

    return {
        "status": "valid",
        "findings": len(findings),
        "open_blockers": len(blockers),
        "verdict": decision,
        # `evidence_declaration`: each evidence reference names a snapshot the
        # findings file declares. The records it points at live in artifacts
        # this checker never opens.
        "checks": [
            "finding_shape",
            "evidence_declaration",
            "blocker_count",
            "verdict_consistency",
        ],
    }


def validate_files(findings: str | Path, verdict: str | Path) -> dict[str, Any]:
    return validate_records(load_jsonl(findings), load_object(verdict))


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--findings", required=True)
    parser.add_argument("--verdict", required=True)
    args = parser.parse_args()
    try:
        result = validate_files(args.findings, args.verdict)
    except (OSError, ValidationError) as exc:
        print(f"review check failed: {exc}", file=sys.stderr)
        return 2
    print(json.dumps(result, ensure_ascii=True, indent=2))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""Offline self-test for the standalone review checker."""

from __future__ import annotations

import copy
import sys

from review_check import SKILL_ROOT, ValidationError, load_jsonl, load_object, validate_records

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 fail(findings: list[dict], verdict: dict, marker: str) -> None:
    try:
        validate_records(findings, verdict)
    except ValidationError as exc:
        require(marker in str(exc), f"expected {marker!r}, got {exc!s}")
    else:
        raise AssertionError(f"expected failure containing {marker!r}")


def expand(records: list[dict], verdict: dict) -> tuple[list[dict], dict]:
    """Rewrite the fixture into the expanded reference form.

    Projects written before the ``sources`` declaration carry that form on disk,
    so the checker keeps resolving it.
    """
    sources = records[0]["sources"]
    expanded_findings = [copy.deepcopy(record) for record in records[1:]]
    for finding in expanded_findings:
        for ref in [*finding["evidence_refs"], finding["target_ref"]]:
            ref.update(sources[ref.pop("src")])
    expanded_verdict = copy.deepcopy(verdict)
    verdict_sources = expanded_verdict.pop("sources")
    for ref in [*expanded_verdict["reviewed_artifacts"], expanded_verdict["findings_ref"]]:
        ref.update(verdict_sources[ref.pop("src")])
    return expanded_findings, expanded_verdict


def main() -> int:
    findings = load_jsonl(SKILL_ROOT / "examples/minimal-findings.jsonl")
    verdict = load_object(SKILL_ROOT / "examples/minimal-verdict.json")
    result = validate_records(findings, verdict)
    require(
        result["open_blockers"] == 1 and result["verdict"] == "REVISE",
        "valid fixture verdict",
    )
    require(result["findings"] == 1, "the sources header is not counted as a finding")

    expanded_findings, expanded_verdict = expand(findings, verdict)
    expanded = validate_records(expanded_findings, expanded_verdict)
    require(expanded == result, "expanded references validate to the same result")

    undeclared = copy.deepcopy(findings)
    undeclared[1]["target_ref"] = {"src": "unknown-source", "record_id": "SC001"}
    fail(undeclared, verdict, "REF_SRC_IS_NOT_DECLARED")

    unbound = copy.deepcopy(findings)
    unbound[1]["evidence_refs"][0] = {"role": "source", "record_id": "SC001-A01"}
    fail(unbound, verdict, "REF_HAS_NO_UPSTREAM_BINDING")

    wrong_count = copy.deepcopy(verdict)
    wrong_count["open_blocker_count"] = 0
    fail(findings, wrong_count, "open_blocker_count")

    false_approval = copy.deepcopy(verdict)
    false_approval["verdict"] = "APPROVE"
    fail(findings, false_approval, "open blockers require REVISE")

    broken_finding = copy.deepcopy(findings)
    broken_finding[1]["evidence_refs"] = []
    fail(broken_finding, verdict, "evidence_refs")

    print("8 self-tests passed")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())