@oh-story/dsh 0.1.11 → 0.1.13

package/lib/video-recap/skills/video-recap/references/data-schema.md

@@ -80,11 +80,15 @@
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "sentence_anchors": [
     {
       "time": 5.809,
-      "confidence": "high",
+      "confidence": "low",
+      "boundary_use": "unverified",
+      "timing_bound_seconds": 9.778,
+      "timing_basis": "asr_window",
+      "alignment_error": 0.012,
       "text_tail": "带你重走詹姆斯的二十一年。",
       "pause_start": 5.222,
       "pause_end": 5.809
@@ -93,26 +97,43 @@
 }
 ```
 
+ASR 时间只到窗口级，句末位置只能在窗口内估计。`timing_bound_seconds` 是停顿到窗口两端的较远距离，
+即句末真实位置的最坏误差；`confidence` 取它与 `alignment_error` 的较大值（≤0.6 high，≤1.2 medium，否则 low）。
+`boundary_use` 决定下游用不用：`verified`（high/medium）、`unverified`（窗口太粗但吸附误差 ≤1.2s，仍作门禁锚点，
+brief 里标 `unverified ±N s`）、`none`（不用）。缺 `boundary_use` 的锚点来自 schema 1 的旧估计器：high/medium 视为 `unverified`、其余为 `none`；
+理解阶段发现 `schema_version` 不是 2 时：有 `audio.wav` 就重新生成本文件；没有（素材库恢复）就按 `asr_result.json`
+原地重标（锚点时间不变，记 `upgraded_from_schema: 1`），重标不了就保持原样。剪后输出时钟的
+`speech_boundary_anchors_output.json` 里 `time` / `pause_start` / `pause_end` / `expected_time` 都是输出时钟，原片值在 `source_*` 字段。
+
 当 `overlaps_speech=true` 且旁白不是从 0 秒冷开场时，`narration` lint 要求 `start`
-贴近 `high`/`medium` 锚点。否则在 TTS 前用 `interrupts_source_sentence` 阻断，并返回
-`suggested_start` 与 `source_text_tail` 给 Agent 调整。常规块使用
-`source_entry_policy: "sentence_boundary"`；原声语句完整性没有抢断 override。最后一个可靠
-锚点之后又进入已声明的原声讲话区时，`suggested_start` 可为 `null`，Agent 必须移动、缩短或删除该旁白块。
+贴近 `boundary_use` 不为 `none` 的锚点。入口是否落在原声讲话里，与 cut 门禁用同一条语气词规则：只有语气词的 ASR 窗口（"啊！"、"Hi."）不算讲话，只在紧挨真实对白的一侧保留 1 秒；文本为空或只有空白的 ASR 行只是时间证据，不算讲话也不留保护；有 `asr_clean.json` 时三处都以它为准，否则读 `asr_result.json`；assemble 的入口检查同样如此。否则在 TTS 前用 `interrupts_source_sentence` 阻断，并返回
+`suggested_start` / `suggested_end` 与 `source_text_tail` 给 Agent 调整：建议的是入点前后
+`max_shift_seconds`（10 秒）内离入点最近的锚点，整块按原时长平移过去后仍在前后两块之间（不越过相邻块），
+既不与其他块重叠、也不与它们相接（间隔须大于 0.15 秒，否则就成了首尾相连的交接）；前一块也收到建议时，
+同时避开它原来和建议的时间窗。cut 模式下平移后仍在该块所属片段内，cut_output 下不超过 `--output-duration`
+（full 模式不检查视频结尾）。距离相同时取后面的。常规块使用
+`source_entry_policy: "sentence_boundary"`；原声语句完整性没有抢断 override。范围内没有这样的锚点时
+`suggested_start` 为 `null`，Agent 必须移动、缩短或删除该旁白块。
 
 剪辑模式第二阶段会另外生成 `speech_boundary_anchors_output.json`，把锚点、ASR 语音区间和
-安静窗口映射到剪后 OUTPUT 时间轴，避免拿原片时间检查剪后旁白：
+安静窗口映射到剪后 OUTPUT 时间轴，避免拿原片时间检查剪后旁白。输出时钟上的值不越出所属片段：比片段入/出点早/晚不超过
+0.05 秒、又没有别的片段播放的锚点钉在该段的入点或出点上（换算后落在 `[0, 成片时长]` 之外的直接丢掉），`source_time` 仍是实测的原片时间：
 
 ```json
 {
   "schema_version": 2,
   "timeline": "cut_output",
+  "clip_plan_identity": {"size": 4970, "mtime_ns": 1790949817370765842},
   "sentence_anchors": [{"time": 4.0, "pause_start": 3.8, "confidence": "high"}],
   "speech_spans": [{"start": 0.0, "end": 3.8}],
   "quiet_windows": [{"start": 3.8, "end": 4.1}]
 }
 ```
 
-该文件必须不早于当前 `clip_plan_validated.json`（按修改时间判断）。缺失、过期或畸形的
+`clip_plan_identity` 是写入时 `clip_plan_validated.json` 的 `{size, mtime_ns}`：video-script
+校验要求它与当前文件相等，assemble 要求本文件不早于 `clip_plan_validated.json`。video-cut
+对同一剪辑计划重跑（续跑时复用 `edited_source.mp4`）不会重写内容未变的 `clip_plan_validated.json`，
+所以第二遍写下的证据在第三遍续跑时仍然有效；`clip_plan.json` 被重新保存后则必然重写。缺失、过期或畸形的
 output 证据一律 fail closed，不能回退到原片时钟或信任 Agent 写入的
 `overlaps_speech=false`。多来源剪辑的每条映射记录还保留 `source_id` 和原片起止时间。
 
@@ -140,6 +161,8 @@ output 证据一律 fail closed，不能回退到原片时钟或信任 Agent 写
 ]
 ```
 
+cut 第二轮（已有 `edited_source.mp4`）时本文件与 `asr_writing_chunks.json` 都在 OUTPUT 时间轴上：被拆到多个片段的场景 `scene_id` 写作 `"3.1"`（0 起的原场景号加片段序号）；VLM 文字里落在场景原片区间内的时间改写成输出时间，落在被剪掉部分的写 `[cut-away moment]`；只被剪进一部分的 ASR 窗口文字换成 `[partial ASR window: only part of it is in the cut, text withheld]`。`scene_id` 一律 0 起，brief 里给人看的场景号从 1 数。
+
 ## narration.json
 
 Agent 撰写的解说词。full 模式下使用原视频时间；**orchestrated cut 模式（`video-recap --edit-mode cut`）下，第二次暂停时已经先剪出 `edited_source.mp4`，因此 `narration.json` 必须直接使用剪后成片的 OUTPUT 时间轴（0..成片总时长）；不存在原视频时间→输出时间的旁白映射产物：
@@ -152,7 +175,7 @@ Agent 撰写的解说词。full 模式下使用原视频时间；**orchestrated
 
 ## narration_lint.json
 
-`--step script` 或续跑验证 `narration.json` 时生成的预检结果。它检查写稿、时间安全和解说覆盖。`metrics` 为 full 模式下的诊断指标（cut 模式为空对象），不是要求命中某个旁白比例的创作配额；低覆盖 warning 应回到 `visual_audio_board.json` 检查是否为有意的原声/沉默选择。
+续跑校验 `narration.json` 时生成的预检结果。它检查写稿、时间安全和解说覆盖。`metrics` 为 full 模式下的诊断指标（cut 模式为空对象），不是要求命中某个旁白比例的创作配额；低覆盖 warning 应回到 `visual_audio_board.json` 检查是否为有意的原声/沉默选择。
 
 ```json
 {
@@ -168,7 +191,8 @@ Agent 撰写的解说词。full 模式下使用原视频时间；**orchestrated
     "original_block_count": 4
   },
   "errors": [
-    {"level": "error", "index": 2, "code": "time_overlap", "message": "Segment overlaps the previous narration segment"}
+    {"level": "error", "index": 2, "code": "time_overlap", "message": "Segment overlaps the previous narration segment"},
+    {"level": "error", "index": 5, "code": "over_budget", "budget_chars": 28, "limit_chars": 35, "actual_chars": 42, "over_chars": 7, "tts_overhead_seconds": 0.45}
   ],
   "warnings": [
     {"level": "warning", "index": 0, "code": "over_budget", "budget_chars": 28, "actual_chars": 42}
@@ -176,7 +200,9 @@ Agent 撰写的解说词。full 模式下使用原视频时间；**orchestrated
 }
 ```
 
-常见 code：`invalid_time`、`empty_narration`、`time_overlap`、`outside_clip_plan`、`over_budget`、`incomplete_sentence`、`slot_too_short`、`under_narrated`、`over_narrated`、`fragmented_beats`、`no_original_blocks`。
+推荐字数 `budget_chars` 先从时间窗扣掉 `tts_overhead_seconds`（约 0.45 秒，每块一次 TTS 合成自带的首尾静音）再折算，所以比 brief 里每个窗口标的字数少一两个字。full 模式下字数超过推荐字数 1.25 倍（`limit_chars`）的段是 `over_budget` error（校验不会替 Agent 截短）；略超实际朗读时长但未过硬上限、以及 cut_output 的超预算仍是 warning。段落必须按 `start` 排序，否则报 `out_of_order` error。
+
+常见 code：`invalid_time`、`out_of_order`、`empty_narration`、`time_overlap`、`outside_clip_plan`、`over_budget`、`incomplete_sentence`、`slot_too_short`、`under_narrated`、`over_narrated`、`fragmented_beats`、`no_original_blocks`。
 
 ## recap_story_plan.json / visual_audio_board.json（Agent 创作工作产物）
 
@@ -217,42 +243,24 @@ CLI 不以它们作为渲染硬门禁，也不新增解析服务；建议型解
 }
 ```
 
-## deslop_qc_requirements.json（工具/brief 生成的运行契约）
-
-`deslop_qc_requirements.json` 是 tool/brief generated run contract：工具或 brief 生成本次运行的 QC 要求，供 `deslop_qc` 读取，不由 Agent 手写。字段为 `schema_version` 与 `style_card_required`。
+## narration_lint.json 的 deslop_qc（CLI 生成，报告型 QC）
 
-`style_card_required` 默认 `false`（advisory）：缺少 `style_card.json` 只是 warning，不阻断出片。将来的 opt-in 运行可把它设为 `true`，让 `style_card.json` 成为硬性要求——`deslop_qc` 只读这个字段判断缺少 `style_card.json` 是否是 blocker，不扫描 `agent_narration_brief.md` 的 prompt wording 来推断。如果 requirements 文件缺失或损坏，按 legacy/migration advisory 处理，不作为 hard failure。
-
-该契约不改变 `--style`：`--style` 仍是 freeform verbatim guidance，不增加固定风格档位。它也不改变 `deslop_qc` 边界：仍然是 report-only，不是 AIGC detector，不自动改写。
-
-最小示例：
-
-```json
-{
-  "schema_version": 1,
-  "style_card_required": false
-}
-```
-
-## deslop_qc.json（CLI 生成，报告型 QC）
-
-`deslop_qc.json` 由本地 deterministic scanner 生成，Agent 不手写。它只是 report-only QC：不是 AIGC detector，不判断文本是不是 AI 写的，不会自动改写。修改仍由 Agent/人工根据报告回到 `narration.json`、`style_card.json` 或字幕源里处理。
+`narration_lint.json` 的 `deslop_qc` 字段由本地 deterministic scanner 生成，Agent 不手写；不再单独写 `deslop_qc.json`。它只是 report-only QC：不是 AIGC detector，不判断文本是不是 AI 写的，不会自动改写。修改仍由 Agent/人工根据报告回到 `narration.json`、`style_card.json` 或字幕源里处理。
 
 报告分两层：
 
-- `blockers`：客观阻断项，会并入 `narration_lint.json` 的 error，例如 requirements 要求但缺少/损坏 `style_card.json`、破折号、占位符泄漏。
-- `advisories`：建议项，只提示可读性/口语化风险，例如模板化“不是……而是……”转折、套话密度、抽象总结词、解释链、比喻标记、过长段落；它们不自动阻断，也不自动改写。
+- `blockers`：客观阻断项，会并入 `narration_lint.json` 的 error，例如破折号、占位符泄漏。
+- `advisories`：建议项，只提示可读性/口语化风险，例如缺少或空的 `style_card.json`、模板化“不是……而是……”转折、套话密度、抽象总结词、解释链、比喻标记、过长段落；它们不自动阻断，也不自动改写。
 
 ```json
 {
   "ok": false,
   "contract": "Local readability/QC report only: this is not an AIGC detector, does not claim AI-generation accuracy, and never rewrites text. Corrections remain human/agent rewrite work.",
   "scanner": "deslop_qc.py",
-  "style_card_required": true,
   "blocker_count": 1,
   "advisory_count": 1,
   "blockers": [
-    {"severity": "blocker", "code": "missing_style_card", "source": "style_card", "index": null, "message": "style_card.json is required by this expression/packaging run but is missing"}
+    {"severity": "blocker", "code": "em_dash", "source": "narration", "index": 3, "message": "破折号（—/——）不得出现在 narration/original_subtitles 中"}
   ],
   "advisories": [
     {"severity": "advisory", "code": "cliche_density", "source": "narration", "index": null, "message": "套话/高频抽象词偏密，建议换成具体行动、选择和后果"}
@@ -326,6 +334,7 @@ CLI 校验 `clip_plan.json` 后写出，额外包含输出时间轴：
       "output_start": 0.0,
       "output_end": 26.0,
       "duration": 26.0,
+      "frame_count": 650,
       "reason": "b01 | hook | knowledge: unknown→threat | POV=主角 | 保留倾听反应 | 入点=问题已问出 | 出点=沉默落地"
     }
   ],
@@ -335,9 +344,30 @@ CLI 校验 `clip_plan.json` 后写出，额外包含输出时间轴：
 ```
 
 `qc.boundary_status.sentence_checks` 逐项记录每个片段 start/end 是 `safe`、`unchecked`
-还是 `blocking`。理解阶段已有 ASR 讲话时间时，任何未落到源头/源尾、可靠句末/静音窗，且
-不是同源无损连续连接的边界都会写入 `qc.blocking[].code=unsafe_clip_sentence_boundary`。
-切镜吸附先执行，句末吸附最后执行，保证视觉边界不会覆盖声音安全边界。
+还是 `blocking`（落在 `unverified` 句末锚点上的边界为 `safe`，`reason` 记 `unverified_sentence_boundary`）。理解阶段已有 ASR 讲话时间时，任何未落到源头/源尾、句末锚点/静音窗，且
+不是同源无损连续连接（计划里相邻、`clip_id` 连续的同源片段）的边界都会写入 `qc.blocking[].code=unsafe_clip_sentence_boundary`。
+被阻断的边界额外带 `nearest_safe`，给出前后 5 秒内最近的安全边界（原片秒，已是帧对齐后的落点、复核后仍安全；重跑时切镜吸附不会再把它拉回讲话内，见下文），没有则为 `null`：
+
+```json
+{"clip_id": 0, "edge": "start", "time": 3.0, "status": "blocking", "reason": "inside_detected_speech",
+ "nearest_safe": {"before": {"time": 0.0, "reason": "source_start", "delta": -3.0},
+                  "after": {"time": 4.8, "reason": "sentence_or_quiet_boundary", "delta": 1.8}}}
+```
+
+切镜吸附先执行，句末吸附随后执行，保证视觉边界不会覆盖声音安全边界；附近没有停顿窗、句末吸附修不回来时，被切镜吸附移进讲话的边界若原位置能过门禁，就撤回原位置（不与其他片段重叠时），`qc.boundary_status.shot_snaps` 对应项记 `end_action`/`start_action: "reverted_unsafe"`、`rejected_end`/`rejected_start`（被撤回的切点）与 `end_revert_reason`/`start_revert_reason`；最后把入点对齐到源帧网格、
+时长对齐到整数输出帧（只移动不到一帧，优先选门禁仍判为安全、仍在停顿内的一侧，也不会因此丢掉必保证据的边缘；两侧同样安全时选不跨过切镜扫描到的原片硬切的一侧，入点落在切点上或之后、出点落在切点上或之前，不闪一帧另一个镜头），
+门禁检查对齐后的边界。每段的 `frame_count` 是它渲染的帧数，`edited_source.mp4` 因此是恒定帧率；
+对齐前后的时间写在 `qc.boundary_status.frame_snaps`，汇总写在 `qc.frame_grid`：
+
+```json
+{"output_frame_rate": "25", "frame_count": 650, "duration": 26.0,
+ "sources": [{"source_id": null, "path": "/abs/source.mp4", "frame_rate": "25/1",
+              "video_start_offset": 0.0, "start_snapped": true}]}
+```
+
+单源时 `output_frame_rate` 沿用源的 `r_frame_rate`（隔行素材报场频、或可变帧率素材的标称帧率高出 `avg_frame_rate` 1.5 倍以上时，按实际帧率取），多源时是画布帧率（NTSC 写成 `30000/1001`）。
+`output_start/end` 与 `total_duration` 按累计 `frame_count` 计算，与渲染的帧时间一致。
+`start_snapped: false` 表示该源帧率未知（`0/0` 或大于 120），入点不动，时长仍对齐到整数输出帧。
 
 多视频 validated clip 会额外保留来源字段，供 pass2 brief、timeline 和剪映导出追溯原素材：
 
@@ -353,6 +383,7 @@ CLI 校验 `clip_plan.json` 后写出，额外包含输出时间轴：
       "output_start": 0.0,
       "output_end": 26.0,
       "duration": 26.0,
+      "frame_count": 780,
       "reason": "b01 | hook | knowledge: unknown→threat | POV=主角 | 保留倾听反应 | 入点=问题已问出 | 出点=沉默落地"
     }
   ]
@@ -374,8 +405,12 @@ CLI 校验 `clip_plan.json` 后写出，额外包含输出时间轴：
     artifacts/asr_clean.json       # 启用 --consolidate-asr 时保留，恢复后 brief/review 优先使用
     artifacts/vlm_analysis.json
     artifacts/understanding_index.json
+    artifacts/consolidation.status.json  # 恢复后 brief-only 仍能提示 consolidate 失败/缺索引
 ```
 
+`asr_timing_evidence.json` 不入库：它按 `{size, mtime_ns}` 绑定 `asr_result.json` 与 `audio.wav`，
+恢复时前者被脱敏重写、后者不复制，恢复出的副本只会被判为 `MISSING_OR_STALE`。
+
 `materials_index.jsonl` 每次保存追加一行，字段包括 `schema_version`, `event`, `material_id`, `source_name`, `source_path`, `source_video_identity`, `summary`, `tags`, `material_dir`, `updated_at`；`material.json` 另外记录分析 `settings` 字典与每个产物的 `bytes`。当前权威状态始终以 `materials/<material_id>/material.json` 为准。MVP 只承诺 `grep -R "关键词" <library>` 这类文件检索；没有 DB、embedding 或语义搜索。
 
 保存时会对凭证形态（`tp-`/`sk-`/`gh*_`/`AKIA`/JWT 与 `KEY=VALUE` 赋值）和凭证命名的 JSON key 做脱敏，但这只是**尽力而为**的兜底，不是保证：陌生格式的密钥仍可能漏过。请从源头避免把密钥写进分析产物——key 从环境变量/`.env` 读取，不需要落进 scenes/ASR/VLM/summary 等 JSON。
@@ -427,28 +462,20 @@ CLI 校验 `clip_plan.json` 后写出，额外包含输出时间轴：
 
 ## narration_review.json
 
-解说评审阶段输出 LLM-as-judge 结果。旧字段 `verdict/summary/findings` 仍然有效；新增一份 **advisory** 的内容效果 scorecard 与改稿清单。**scorecard 不改变 verdict、也不作硬门禁**——硬门禁仍是 `findings` 里的 error（事实矛盾/残句）经 `--require-narration-review` 严格模式拦截。`verdict` 词表为 `PASS|REVISE|FAIL`，`OK` 作为旧值的兼容别名。
+解说评审阶段输出 LLM-as-judge 结果，只有 `verdict` / `summary` / `findings` 三项内容字段，外加运行记录 `evidence_contract`（时间轴、时钟、选中的证据区间、分块数、警告）；有警告时另有顶层 `warnings`，分块评审时另有 `chunked_review` 计数，评审输出无法解析时另有 `parse_error` / `raw`。硬门禁是 `findings` 里的 error（事实矛盾/残句）经 `--require-narration-review` 严格模式拦截；`verdict` 只是建议信号，词表为 `PASS|REVISE|FAIL`，模型偶尔返回的 `OK` 按 `PASS` 记录。
 
 ```json
 {
-  "verdict": "PASS|REVISE|FAIL|OK",
+  "verdict": "PASS|REVISE|FAIL",
   "summary": "总体判断",
-  "scorecard": {
-    "promise_match": 4, "hook_3s": 4, "first_15s_delivery": 4, "spine_clarity": 4,
-    "stakes_escalation": 4, "information_gain": 4, "spoken_language": 4, "sentence_brevity": 4,
-    "tts_pacing": 4, "grounding": 4, "original_audio_use": 4, "subtitle_readability": 4
-  },
-  "hook_candidates_review": [{"candidate": "首句", "type": "suspense", "score": 4, "keep": true}],
-  "retention_risk_points": [{"time": "00:28", "risk": "信息重复可能掉人", "fix": "删掉复述画面的句子"}],
-  "highest_return_edits": ["最值得先改的一件事"],
-  "information_gain_notes": [{"segment": 0, "label": "motive|...|visual_restatement", "note": "证据/改法"}],
-  "spoken_language_rewrites": [{"segment": 0, "original": "原句", "rewrite": "口语改写", "why": "为什么更适合听"}],
-  "grounding_assertions": [{"segment": 0, "assertion": "人物/关系/因果断言", "source": "visual|asr|research|user_context|unsupported", "risk": "谨慎说明"}],
-  "findings": [{"segment": 0, "severity": "warning", "category": "weak_hook", "issue": "问题", "fix": "改法"}]
+  "findings": [{"segment": 0, "severity": "warning", "category": "weak_hook", "issue": "问题", "fix": "改法"}],
+  "evidence_contract": {"schema_version": 1, "timeline": "source", "clock": "source", "selected_ranges": [], "chunk_count": 1, "warnings": []}
 }
 ```
 
-> 若 `work_dir` 提供了 `packaging_plan.json` / `recap_story_plan.json` / `visual_audio_board.json`（可选、Agent 撰写），review 会把它们并入评估上下文；缺失时 review 仅基于解说与画面/对白证据评分，行为不受影响。
+> 若 `work_dir` 提供了 `packaging_plan.json` / `recap_story_plan.json` / `visual_audio_board.json` / `style_card.json`（可选、Agent 撰写），review 会把它们并入评审上下文；缺失时 review 仅基于解说与画面/对白证据评审，行为不受影响。
+
+`cut_output` 解说评审按 `source_id` 映射 `multi_source_manifest.json` 指向的逐源 VLM/ASR，避免项目根目录没有单一 ASR 文件时产生空证据。
 
 ## tts_meta.json（partial 失败可见性）
 
@@ -497,17 +524,29 @@ full / cut 流程（含本地采用路径）合成完成后，video-recap 在 `w
 
 组装后，`assembly_manifest.json.audio_segments[]` 另外记录 `fit_status`、`truncated`、
 `truncate_reason`、`placed_audio_duration`、`placed_audio_path`、`source_duck_end`、
-`source_restore_at` 与 `source_handoff_status`。组装阶段从不按时间裁旁白尾音：放不下时用
+`source_restore_at`、`source_handoff_status`、`source_entry_status` 与 `written_start`。组装阶段从不按时间裁旁白尾音：放不下时用
 `no_safe_fit` 阻断。`placed_audio_path` 是实际写入 canonical `narration.wav` 的完整逐段 PCM；
 `timeline.json`/剪映必须引用它而不是更长的加速前文件。素材时长与序列化后的时间线段长不一致时，
-`assembly_qc.json` 用 `timeline_audio_mismatch` 阻断。原声恢复在 `pause_start` 前保持压低，
-只在实测停顿内渐强，并于 `source_restore_at` 完成，避免渐强提前泄露上一句尾音。
-
-## dub_lint.json / dub_review.json
-
-Dub 模式下，`dub_script.json` 在 voiceclone **之前**先经过 deterministic lint，把明显不可发布的脚本挡在昂贵的克隆 TTS 之前。空译文、相邻行重叠、时间越界、`room < 0.4s` 等 **error** 会 `verdict=FAIL` 并阻断 render；`fast_speech`、`trim_risk` 等是 warning，不阻断。
-
-每行 voiceclone 原始 WAV 会把中文台词、模型/提示等合成设置和参考音频信息写入相邻的 `*.wav.meta.json`。台词与设置完全相等且 WAV 可读取时，dub render 直接复用并在 `dub_manifest.json.lines[].tts_cache` 记录 `hit`；台词、参考音频、模型或提示变化都会重新合成。
+`assembly_qc.json` 用 `timeline_audio_mismatch` 阻断。旁白结束后原声最多再压低 3 秒，等这段时间内的
+第一个句末锚点：压到它的 `pause_start`（`source_duck_end`），只在实测停顿内渐强，并于 `source_restore_at`
+完成，避免渐强提前泄露上一句尾音。`source_handoff_status` 取值：`sentence_boundary`（已验证锚点）、
+`sentence_boundary_unverified`（锚点为 `unverified`，含 schema 1 旧锚点）、`held_to_timeline_end`（3 秒内无锚点且离片尾
+不足 3 秒，压到片尾）、`bounded_release`（3 秒内无锚点，在旁白结束处以 `duck_fade_seconds` 渐强回满，不阻断）、
+`anchors_unavailable`（原声有讲话但没有可用锚点，阻断）、`no_source_speech`；入口状态在 `source_entry_status`
+（`sentence_boundary` / `sentence_boundary_unverified` / `quiet_source` / `non_dialogue_source` / `unverified` /
+`unsafe_entry` / `anchors_unavailable` / `paragraph_tightened`）。每个压低段只给首块记入口状态：`quiet_source` 是入口落在
+实测安静或没有讲话的地方，`non_dialogue_source` 是入口落在只有语气词（尖叫、"Hi."）的讲话窗口里，两者都不阻断。
+段落内与上一块作者留白不超过 1.6 秒的后续块会紧接上一块实际结尾 0.35 秒后播放，最多比写的 `start` 提前 1.2 秒；
+旁白校验只检查过写的 `start`，所以提前的这一段不进入原声对白（ASR 对白区间减去实测安静窗口），有对白时最多提前到
+最后一段对白结束处。真的提前了的块记 `paragraph_tightened`，`written_start` 是写的 `start`（未提前的块为 `null`）；
+这样的块若因间隔超过 `duck_bridge_seconds` 成为新压低段的首块，入口状态改记该段在实际起点上的入口判定，`written_start` 保留。
+每次压低延续 = `source_restore_at - actual_place_end`，最大值写在 `assembly_qc.json` 的 `summary.max_source_duck_hold_seconds`，只作信息、不阻断。
+
+## dub_lint.json
+
+Dub 模式下，`dub_script.json` 在 voiceclone **之前**先经过 deterministic lint，把明显不可发布的脚本挡在昂贵的克隆 TTS 之前。空译文、相邻行重叠、时间越界、`room < 0.4s` 等 **error** 会 `verdict=FAIL` 并阻断 render；`fast_speech`、`trim_risk`（有效字数 ≥ 7 字/秒；`dub_brief.md` 要求的目标约 5 字/秒）等是 warning，不阻断。
+
+每行 voiceclone 原始 WAV 会把中文台词、模型/提示等合成设置和参考音频信息写入相邻的 `*.wav.meta.json`。台词与设置完全相等且 WAV 可读取时，dub render 直接复用并在 `dub_manifest.json.lines[].tts_cache` 记录 `hit`；台词、参考音频、模型或提示变化都会重新合成。时长远超读完台词所需（`TTS_MIN_SPEECH_RATE`）的克隆音频视为幻读：按 `TTS_RETRIES` 重试、不写 `.meta.json`，用尽则 render 失败，最后一次被拒的音频留在 `dub_tts/line_NNN_raw.rejected.wav`；旧缓存里的这类 WAV 会重新合成。
 
 ```json
 {
@@ -520,26 +559,44 @@ Dub 模式下，`dub_script.json` 在 voiceclone **之前**先经过 determinist
 }
 ```
 
-`dub_review.json` 是脚本级 review scaffold（确定性派生自 lint，语义忠实/语气仍需 agent/人工判断）：
+> dub 渲染阶段在克隆前写 `dub_lint.json`，lint 非 PASS 即中止；dub 只有 `--edit-mode dub` 驱动的准备 / 渲染两个阶段，没有单独的手动 lint / review 入口。
+> 最终 `dub_<name>.mp4` 显式输出 48 kHz AAC；不能沿用 `loudnorm` 内部的 96 kHz 分析采样率。
+## final_qc.json
+
+渲染后 `recap.py` 写 `final_qc.json`；`scripts/final_qc.py --work-dir <dir>` 也可对已有 work_dir 单独重写。它只对最终 mp4 做本地确定性检查，每条 finding 都是阻断项：
 
 ```json
 {
-  "schema_version": 1,
-  "verdict": "PASS|REVISE|FAIL",
-  "checks": {"faithful_to_source": "needs_agent_review", "spoken_chinese": "PASS", "speaker_tone": "needs_agent_review", "timing_fit": "PASS", "platform_fit": "needs_agent_review"},
-  "highest_return_edits": [],
-  "coverage": {"transcript_windows": 8, "script_lines": 12}
+  "schema_version": 2,
+  "artifact": "final_qc.json",
+  "ok": false,
+  "blocker_count": 1,
+  "finding_count": 1,
+  "findings": [{"code": "missing_fps", "message": "final output probe metadata is missing a positive finite video fps",
+                "blocking": true, "evidence": {"fps": null, "video_stream": {"codec_type": "video", "codec_name": "h264"}},
+                "next_action": "rerender_final_output_with_valid_fps"}],
+  "metadata": {
+    "work_dir": "/abs/work", "final_output": {"path": "/abs/out/recap_x.mp4", "exists": true, "bytes": 1048576},
+    "artifacts": {"assembly_qc.json": {"path": "assembly_qc.json", "exists": true, "bytes": 512,
+                  "summary": {"schema_version": 1, "verdict": "PASS", "blocking": false, "blocking_codes": []}}},
+    "probe": {"streams": [{"codec_type": "video", "codec_name": "h264", "width": 1920, "height": 1080, "avg_frame_rate": "30/1"}],
+              "format": {"format_name": "mov,mp4,m4a,3gp,3g2,mj2", "duration": "61.2"}},
+    "probe_error": null,
+    "warnings": [],
+    "auto_repair": false
+  }
 }
 ```
 
-> CLI：`dub.py --stage lint|review`（无需 video）、`dub.py --print-schema` 打印以上全部 dub artifact 契约；`--stage render` 会在克隆前自动写 `dub_lint.json` / `dub_review.json`，lint 非 PASS 即中止。
-> 最终 `dub_<name>.mp4` 显式输出 48 kHz AAC；不能沿用 `loudnorm` 内部的 96 kHz 分析采样率。
-## shift-left QC artifacts
+阻断码：`missing_final_output`、`empty_final_output`、`probe_failed`（ffprobe 不可用或失败）、`missing_video_stream`、`missing_duration` / `invalid_duration`、`missing_codec`、`missing_fps` / `invalid_fps`，以及尾部 2 秒解码失败的 `undecodable_stream`。`next_action` 是可直接执行的修复提示。`ok` 为 `true` 当且仅当 `blocker_count` 为 0；`--require-final-qc` 只读这两个字段，dashboard 另外读 finding 的 `code` / `message` / `blocking`。
 
-`preflight_qc.json`、`final_qc.json`、`golden_eval.json`、`mimo_qc.json` 共用最小 QC 契约；stage 仅允许 `pre_cut` / `post_cut` / `pre_tts` / `post_tts` / `pre_assemble` / `post_render` / `golden`，其中 `mimo_qc.json` 是 artifact 而不是 stage。详见 `shift-left-qc-schema.md`。
+`metadata.artifacts` 汇总 `assembly_manifest.json`、`assembly_qc.json`、`visual_qc.json` 的 `schema_version` / `verdict` / `blocking` / `blocking_codes`（不可解析时为 `{"invalid": true}`），只作记录、不转成 final_qc 的阻断项：assembly/visual QC 阻断时 video-assemble 已经非零退出，流程到不了 final_qc。`metadata.probe` 只保留检查用到的流与容器字段（codec、宽高、帧率、时长、采样率等），不保存 `tags` / `disposition` / 文件名，因此从原片带过来的容器标签（如 comment、purl 里的 URL）不会写进报告。
 
-`recap.py` 可通过 `--mimo-qc pre-assemble|post-render|both`（默认 `off`）在组装前和/或成片后写 `mimo_qc.json`。每个 stage 最多一次 live request；报告的 `metadata.cache_input`（证据文件的 kind/bytes/mtime_ns、模型、提示与抽帧元数据）与本次完全相等时复用上次结果，`--mimo-qc-refresh` 可刷新。`post_render` 最多临时抽取 6 张、最长边 768px 的 JPEG；base64 只进入请求，不写进 artifact。多 stage 报告聚合在 `metadata.stages`，状态为 `completed` / `cached` / `unavailable` / `failed`，任何状态都不阻断、也不自动修复。关闭功能会清理旧 `mimo_qc.json`，避免陈旧建议被误认为本轮结果。
+`metadata.warnings` 照抄 `visual_qc.json` 的 `warnings`：不阻断、不计入 `blocker_count`，但 Agent 交付时必须转告用户。目前只有一种：默认烧录字幕而 ffmpeg 缺 libass 时降级为外挂字幕，
 
-QC 证据把 `source_asr` 与 `generated_subtitles` 分开：前者只用于源事实/原声时序，后者是本轮旁白派生字幕，不能反过来充当事实证据。多视频项目从 `multi_source_manifest.json` 指向的逐源 work dir 汇集 ASR；`cut_output` 解说评审同样按 `source_id` 映射逐源 VLM/ASR，避免项目根目录没有单一 ASR 文件时产生空证据。
+```json
+{"code": "subtitle_burn_degraded", "reason": "ffmpeg_missing_libass", "delivered": "sidecar_srt",
+ "mask_dropped": false, "message": "…", "next_action": "…"}
+```
 
-渲染后，`recap.py` 先更新 `preflight_qc.json` 的 `post_render` stage，再运行可选 MiMo 提示，最后写 `final_qc.json` 和 `golden_eval.json`。`final_qc.json` 汇总最终 mp4、`assembly_manifest.json`、`assembly_qc.json`、`visual_qc.json`、`preflight_qc.json`、`mimo_qc.json` 的本地元数据；缺失/空成片、ffprobe 不可用或失败、以及 assembly/visual QC 的客观 blocker 会进入 deterministic blockers。MiMo 和其他 non-deterministic finding 永远不能成为 blocker；客观佐证必须由 deterministic producer 另发 finding。`golden_eval.json` 默认要求 `final_qc.json.ok=true`，也可用 golden fixture 做简单的时长、codec 和必需 artifact 断言。所有 QC metadata/evidence 写入前都经过 `qc_contract.redact_secrets`：secret-looking key/value 会被替换，URL userinfo/query/fragment 会被移除，仅保留必要 host/path 诊断信息。
+这时成片里没有字幕，字幕在成片旁的同名 `.srt`（路径见 `assembly_manifest.json` 的 `subtitle_sidecar`）；`mask_dropped` 为 `true` 表示原本会画的原字幕遮罩也一并关掉了。`final_qc.py` 打印的摘要 `final_qc.warnings` 列出这些 code，`recap.py` 完成时打印一行警告和外挂字幕路径。

package/lib/video-recap/skills/video-recap/references/resource-library.md

@@ -91,6 +91,7 @@ python3 scripts/library.py --library-dir <library> show <id|id@vN>
   `0 <= y_top < y_bot <= canvas.height`。
 - `packaging` 需要非空 `params.layers`，每层有唯一 `name`、`image` 引用与画布内的整数 `rect {x, y, width, height}`；
   可选 `params.safe_rect`。
+- `production_reference` 见下一节。
 - `status` ∈ `draft` / `adopted` / `retired`。`adopted` 必须有 `adoption.date`（YYYY-MM-DD）、`by`、`statement`（用户原话）
   与 `scope`。可选 `adoption.resources` 记录采用时所用资源文件的身份：
 
@@ -101,6 +102,20 @@ python3 scripts/library.py --library-dir <library> show <id|id@vN>
   之后文件的大小或修改时间变化，`check` 给出 `changed_since_adoption` 警告：重新采用，或出一个新版本。
   修改时间是本机事实，把库拷到另一台机器会让所有快照都显示为已变化。
 
+### 参考模板 `production_reference`
+
+把 video-reference 导出的 `production_reference.json`（只含方法与数值，不含原片事实）登记成可版本化、需采纳的模板：
+
+1. `mkdir -p templates/production_reference/<id>/v1`，把导出物原样复制进去，文件名保持 `production_reference.json`。
+2. 写 `template.json`：`params` 恰好是 `{"reference": {"path": "production_reference.json"}}`；`canvas` 从导出物复制，仅作信息，
+   绑定时不核对画布。
+3. 写 `samples/<id>/sample.json` 指向原成片，`demonstrates` / `not_reusable` 写人看的摘要；含事实的完整拆解不进库。
+4. `library.py check`：导出物的 `schema` 必须是 `video-reference.production.v1`，`methods` 非空且每条有合法 `dimension` 与 `rule`，
+   任何层级出现 `source_facts`、`labels`、`evidence`、`entities`、`statement`、`from`、`path` 键都报错（与参考技能导出时的复扫同一组键）。
+5. 用户确认后把 `status` 改为 `adopted` 并用用户原话写 `adoption`。之后要改内容就出 `v2`，不改已采纳的版本。
+
+库仍然只读，登记与采纳都是手工编辑。
+
 ## 样片 `sample.json`
 
 ```json
@@ -138,10 +153,11 @@ python3 scripts/library.py --library-dir <library> show <id|id@vN>
 | `subtitle_style` | `SUBTITLE_PLAY_RES_X/Y` = 模板画布，`SUBTITLE_FONT_SIZE` ← `size_px`，`SUBTITLE_OUTLINE` ← `outline_px`，`SUBTITLE_SHADOW` ← `shadow_px`，`SUBTITLE_PRIMARY_COLOR` / `SUBTITLE_OUTLINE_COLOR`（ASS `&HAABBGGRR`），`SUBTITLE_MAX_CHARS` / `SUBTITLE_MAX_LINES`；`band` → 底对齐 `SUBTITLE_ALIGNMENT=2` 且 `SUBTITLE_MARGIN_V` = 画布高 − `y_bot`；`font.family` → `SUBTITLE_FONT_NAME`，字体资源 → 再加 `SUBTITLE_FONT_FILE` |
 | `voice` | provider → `--tts-provider`；MiMo 预置音色 → `--mimo-tts-voice`，参考音频 → `--voice-ref`；Fish Audio → `FISH_TTS_REFERENCE_ID`；index-tts → `INDEX_TTS_VOICE` |
 | `bgm` | `BGM_PATH` ← 该资源的第一个文件 |
+| `production_reference` | 第一次暂停前写出 `work_dir/production_reference.json`：导出物原样加 `written_by` 与 `template {id, version}`，仅写稿 Agent 阅读，没有脚本读取；不核对画布。该位置已有不是 `--project` 写的文件时：与导出物相同则原样保留（暂停提示照常），不同则停止；解除绑定后删掉自己写的副本，调用方自己放的文件不动 |
 | `packaging` | 合成前写出 `work_dir/packaging_layers.json`：每个图层的图片资源第一个文件 + `rect`，由 video-assemble 叠加到成片并写进 `timeline.json` 的 image 轨 |
 
 - 你已经显式设置的参数或环境变量与绑定不一致时，运行在开始前停止并指出是哪一项，不会静默覆盖。
-- 合成前核对模板画布与实际成片画布；不一致即停止——换画幅要用另一个模板。
+- 合成前核对字幕与包装模板的画布与实际成片画布；不一致即停止——换画幅要用另一个模板。
 - 参考音频的 `consent.status` 为 `denied` 时拒绝绑定；dub 模式与本地采用三件套不接受 `--project`。
 - 续跑命令只带 `--project`，不重复写出由绑定得到的值，改了绑定后续跑会按新绑定解析。