@speclip/pi-talking-head 0.1.4 → 0.1.6

package/README.md

@@ -107,14 +107,16 @@ talking_head_broll_plan {
 }
 ```
 
-规划结果同时返回 `continuityPlanReceipt`，把当前项目 revision、A-roll、规划后的 B-roll 区间和跳点审阅结果绑定在一起。后续 `talking_head_apply` 会重新计算并核对它，不能跳过规划或把已经衔接的区间手动缩短。
+规划结果同时返回 `plan.coverage` 和 `continuityPlanReceipt`。`plan.coverage` 会列出 B-roll/A-roll 时长、B-roll 占比、最长连续 B-roll 和审阅提醒；凭证则把当前项目 revision、A-roll、规划后的 B-roll 区间和跳点审阅结果绑定在一起。后续 `talking_head_apply` 会重新计算并核对，不能跳过规划或把已经衔接的区间手动缩短。
 
 规划结果处理两类问题：
 
 - **B-roll 闪屏**：两个 B-roll 之间只露出不超过 500ms 的 A-roll 时，`plan.needs` 会把前一个需求延长到后一个需求的起点。后续分别选段后，两段 B-roll 会直接交接，不再闪回 A-roll。
-- **气口剪辑跳转**：A-roll 相邻片段的源时间不连续时，会生成 `jumpCuts`。工具检查建议遮盖区间是否已被 B-roll 连续覆盖；未覆盖项标为 `needs-broll`，Agent 应结合口播语义补充 `purpose: "mask-cut"` 的需求，再重新规划。
+- **气口剪辑跳转**：A-roll 相邻片段的源时间不连续时会生成 `jumpCuts`。未覆盖项标为 `review`，只表示 Agent 需要查看实际画面。只有确认跳点视觉上突兀时才能添加 `purpose: "mask-cut"`，保存工作区内的审阅图片或视频，并提交 `visualReview: { decision: "mask-with-broll", reviewedJumpCutOutputMs, artifactPath }`；规划器会计算文件哈希并绑定到 v2 凭证，应用时再次校验。否则继续保留 A-roll。
+- **时长与覆盖审阅**：B-roll 时长由完整口播语义和说话节奏决定，不能用固定三秒规则，也不能在一句话没有表达完时提前结束。总覆盖超过 50% 或连续覆盖超过 8000ms 会生成 warning，但不会硬性拒绝合理的长演示；Agent 应删除纯装饰画面，或把同一语义段落组织成不同角度、景别和素材组成的镜头组。
+- **避免重复**：最终应用会拒绝同一素材的源时间段发生任何重叠，避免重复出现相同画面；应改用不同角度、不同素材或同一素材中的其他非重叠有效时刻。
 
-规划只提供时间轴证据，不会假定每个剪辑点都必须加 B-roll。是否遮盖仍需结合实际画面判断。
+规划只提供时间轴证据，不会假定每个剪辑点都必须加 B-roll。语义匹配、完整表达和实际画面审阅始终优先于覆盖率数字。
 
 ### 4. 文件名优先筛选 B-roll
 
@@ -203,7 +205,7 @@ review { path: "out/launch-final.mp4" }
 | --- | --- |
 | `talking_head_create` | 从视频和词级转录建立 revision 1，分析句子、语气词、重复和停顿并生成默认 EDL |
 | `talking_head_get` | 读取指定 revision，分页返回整句与编辑候选，可选导出 pi-media EDL |
-| `talking_head_broll_plan` | 衔接相邻 B-roll、识别 A-roll 跳点并报告尚未遮盖的剪辑区间 |
+| `talking_head_broll_plan` | 按 A-roll 优先预算规划 B-roll、衔接相邻片段并报告待审阅跳点 |
 | `talking_head_broll_match` | 只用文件名和目录名匹配本地 B-roll，返回受限 shortlist 与视觉升级建议 |
 | `talking_head_broll_select` | 用 pi-media 联络表 manifest 验证具体源时间段并生成 placement |
 | `talking_head_apply` | 写入新的不可变口播 revision，并返回 pi-media EDL |

package/extensions/talking-head/index.ts

@@ -1,5 +1,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { open } from "node:fs/promises";
+import { extname } from "node:path";
 import { Type } from "typebox";
+import type { BrollNeed } from "../../src/contracts.ts";
 import { matchWorkspaceBrollAssets, selectBrollWindow } from "../../src/broll.ts";
 import { createBrollContinuityPlanReceipt, planBrollContinuity } from "../../src/continuity.ts";
 import { toMediaTimelineOperation } from "../../src/edl.ts";
@@ -11,6 +14,7 @@ import {
 	getAnalysis,
 	getTalkingHeadProject,
 } from "../../src/project.ts";
+import { resolveExistingWorkspaceFile, snapshotFile } from "../../src/workspace.ts";
 
 function result(details: unknown) {
 	return {
@@ -50,23 +54,115 @@ const brollPlacement = Type.Object({
 	}, { additionalProperties: false }),
 }, { additionalProperties: false });
 
-const brollNeed = Type.Object({
+const brollNeedFields = {
 	id: stableId,
 	outputStartMs: Type.Number({ minimum: 0 }),
 	outputEndMs: Type.Number({ exclusiveMinimum: 0 }),
 	speechText: Type.String({ minLength: 1, maxLength: 2_000 }),
+	searchTerms: Type.Array(Type.String({ minLength: 1, maxLength: 100 }), { minItems: 1, maxItems: 20 }),
+	reason: Type.String({ minLength: 1, maxLength: 1_000 }),
+};
+
+const semanticBrollNeed = Type.Object({
+	...brollNeedFields,
 	purpose: Type.Union([
 		Type.Literal("demonstrate"),
 		Type.Literal("explain"),
 		Type.Literal("evidence"),
 		Type.Literal("establish"),
 		Type.Literal("transition"),
-		Type.Literal("mask-cut"),
 	]),
-	searchTerms: Type.Array(Type.String({ minLength: 1, maxLength: 100 }), { minItems: 1, maxItems: 20 }),
-	reason: Type.String({ minLength: 1, maxLength: 1_000 }),
 }, { additionalProperties: false });
 
+const maskCutReviewFields = {
+	decision: Type.Literal("mask-with-broll"),
+	reviewedJumpCutOutputMs: Type.Number({ minimum: 0 }),
+	artifactPath: Type.String({ minLength: 1, description: "Workspace-relative image or video reviewed at this A-roll jump." }),
+};
+
+const maskCutBrollNeedInput = Type.Object({
+	...brollNeedFields,
+	purpose: Type.Literal("mask-cut"),
+	visualReview: Type.Object(maskCutReviewFields, { additionalProperties: false }),
+}, { additionalProperties: false });
+
+const maskCutBrollNeed = Type.Object({
+	...brollNeedFields,
+	purpose: Type.Literal("mask-cut"),
+	visualReview: Type.Object({
+		...maskCutReviewFields,
+		artifactSha256: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+	}, { additionalProperties: false }),
+}, { additionalProperties: false });
+
+const brollNeedInput = Type.Union([semanticBrollNeed, maskCutBrollNeedInput]);
+const brollNeed = Type.Union([
+	semanticBrollNeed,
+	maskCutBrollNeed,
+]);
+
+const visualReviewArtifactExtensions = new Set([
+	".png", ".jpg", ".jpeg", ".webp", ".avif", ".mp4", ".mov", ".m4v", ".webm", ".mkv",
+]);
+
+function hasVisualMediaSignature(bytes: Buffer): boolean {
+	const startsWith = (signature: number[]) => signature.every((byte, index) => bytes[index] === byte);
+	const ascii = (start: number, value: string) => bytes.subarray(start, start + value.length).toString("ascii") === value;
+	return startsWith([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+		|| startsWith([0xff, 0xd8, 0xff])
+		|| (ascii(0, "RIFF") && ascii(8, "WEBP"))
+		|| ascii(4, "ftyp")
+		|| startsWith([0x1a, 0x45, 0xdf, 0xa3]);
+}
+
+async function assertVisualReviewArtifactBytes(cwd: string, artifactPath: string, signal?: AbortSignal): Promise<void> {
+	signal?.throwIfAborted();
+	const absolutePath = await resolveExistingWorkspaceFile(cwd, artifactPath);
+	const handle = await open(absolutePath, "r");
+	try {
+		const bytes = Buffer.alloc(16);
+		const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
+		if (!hasVisualMediaSignature(bytes.subarray(0, bytesRead))) {
+			throw new Error("visual review artifact must contain recognizable image or video bytes");
+		}
+	} finally {
+		await handle.close();
+	}
+}
+
+async function bindVisualReviewArtifacts(
+	cwd: string,
+	needs: BrollNeed[],
+	signal?: AbortSignal,
+): Promise<BrollNeed[]> {
+	const verifiedNeeds: BrollNeed[] = [];
+	for (const need of needs) {
+		signal?.throwIfAborted();
+		if (need.purpose !== "mask-cut") {
+			verifiedNeeds.push(structuredClone(need));
+			continue;
+		}
+		if (!visualReviewArtifactExtensions.has(extname(need.visualReview.artifactPath).toLowerCase())) {
+			throw new Error(`B-roll mask-cut need ${need.id} visual review artifact must be an image or video`);
+		}
+		try {
+			await assertVisualReviewArtifactBytes(cwd, need.visualReview.artifactPath, signal);
+		} catch (error) {
+			throw new Error(`B-roll mask-cut need ${need.id} ${(error as Error).message}`);
+		}
+		const artifact = await snapshotFile(cwd, need.visualReview.artifactPath, signal);
+		verifiedNeeds.push({
+			...structuredClone(need),
+			visualReview: {
+				...structuredClone(need.visualReview),
+				artifactPath: artifact.path,
+				artifactSha256: artifact.sha256,
+			},
+		});
+	}
+	return verifiedNeeds;
+}
+
 const arollJumpCut = Type.Object({
 	fromSegmentId: stableId,
 	toSegmentId: stableId,
@@ -75,26 +171,65 @@ const arollJumpCut = Type.Object({
 	suggestedOutputStartMs: Type.Number({ minimum: 0 }),
 	suggestedOutputEndMs: Type.Number({ minimum: 0 }),
 	coveredByNeedIds: Type.Array(stableId, { maxItems: 500 }),
-	status: Type.Union([Type.Literal("covered"), Type.Literal("needs-broll")]),
+	status: Type.Union([
+		Type.Literal("covered"),
+		Type.Literal("review"),
+		Type.Literal("needs-broll", { description: "Legacy v0.1.5 receipt value; new plans emit review." }),
+	]),
 }, { additionalProperties: false });
 
-const continuityPlanReceipt = Type.Object({
-	schemaVersion: Type.Literal(1),
+const continuityPlanReceiptBase = {
 	projectId: stableId,
 	revision: Type.Integer({ minimum: 1 }),
 	arollSha256: Type.String({ pattern: "^[a-f0-9]{64}$" }),
 	shortGapMs: Type.Integer({ minimum: 0, maximum: 2_000 }),
 	cutCoverBeforeMs: Type.Integer({ minimum: 0, maximum: 2_000 }),
 	cutCoverAfterMs: Type.Integer({ minimum: 0, maximum: 2_000 }),
+	jumpCuts: Type.Array(arollJumpCut, { maxItems: 999 }),
+	planSha256: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+};
+
+const continuityPlanReceiptV1 = Type.Object({
+	...continuityPlanReceiptBase,
+	schemaVersion: Type.Literal(1),
 	needs: Type.Array(Type.Object({
 		id: stableId,
 		outputStartMs: Type.Number({ minimum: 0 }),
 		outputEndMs: Type.Number({ exclusiveMinimum: 0 }),
 	}, { additionalProperties: false }), { maxItems: 500 }),
-	jumpCuts: Type.Array(arollJumpCut, { maxItems: 999 }),
-	planSha256: Type.String({ pattern: "^[a-f0-9]{64}$" }),
 }, { additionalProperties: false });
 
+const continuityPlanReceiptV2 = Type.Object({
+	...continuityPlanReceiptBase,
+	schemaVersion: Type.Literal(2),
+	needs: Type.Array(Type.Union([
+		Type.Object({
+			id: stableId,
+			outputStartMs: Type.Number({ minimum: 0 }),
+			outputEndMs: Type.Number({ exclusiveMinimum: 0 }),
+			purpose: Type.Union([
+				Type.Literal("demonstrate"),
+				Type.Literal("explain"),
+				Type.Literal("evidence"),
+				Type.Literal("establish"),
+				Type.Literal("transition"),
+			]),
+		}, { additionalProperties: false }),
+		Type.Object({
+			id: stableId,
+			outputStartMs: Type.Number({ minimum: 0 }),
+			outputEndMs: Type.Number({ exclusiveMinimum: 0 }),
+			purpose: Type.Literal("mask-cut"),
+			visualReview: Type.Object({
+				...maskCutReviewFields,
+				artifactSha256: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+			}, { additionalProperties: false }),
+		}, { additionalProperties: false }),
+	]), { maxItems: 500 }),
+}, { additionalProperties: false });
+
+const continuityPlanReceipt = Type.Union([continuityPlanReceiptV1, continuityPlanReceiptV2]);
+
 export default function talkingHead(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "talking_head_create",
@@ -200,20 +335,25 @@ export default function talkingHead(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "talking_head_broll_plan",
 		label: "Plan B-roll visual continuity",
-		description: "Plan B-roll windows before asset matching. Bridges brief A-roll flashes between neighboring B-roll needs and reports A-roll source jump cuts that still need a mask-cut B-roll.",
+		description: "Plan meaning- and rhythm-led B-roll windows after A-roll is stable. Coverage above 50% or a continuous run above 8 seconds produces review warnings rather than fixed rejection. Brief A-roll flashes are bridged, while uncovered source jumps are reported only for picture review.",
 		parameters: Type.Object({
 			projectId: stableId,
 			revision: Type.Optional(Type.Integer({ minimum: 1 })),
 			aroll: Type.Array(arollSegment, { minItems: 1, maxItems: 1_000 }),
-			needs: Type.Array(brollNeed, { maxItems: 500 }),
+			needs: Type.Array(brollNeedInput, { maxItems: 500 }),
 			cutCoverBeforeMs: Type.Optional(Type.Integer({ minimum: 0, maximum: 2_000, default: 250 })),
 			cutCoverAfterMs: Type.Optional(Type.Integer({ minimum: 0, maximum: 2_000, default: 500 })),
 		}, { additionalProperties: false }),
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			const { snapshot } = await getTalkingHeadProject(ctx.cwd, params.projectId, params.revision);
+			const needs = await bindVisualReviewArtifacts(
+				ctx.cwd,
+				params.needs as BrollNeed[],
+				signal,
+			);
 			const plan = planBrollContinuity({
 				aroll: params.aroll,
-				needs: params.needs,
+				needs,
 				...(params.cutCoverBeforeMs === undefined ? {} : { cutCoverBeforeMs: params.cutCoverBeforeMs }),
 				...(params.cutCoverAfterMs === undefined ? {} : { cutCoverAfterMs: params.cutCoverAfterMs }),
 			});
@@ -227,9 +367,9 @@ export default function talkingHead(pi: ExtensionAPI): void {
 					params.aroll,
 					plan,
 				),
-				nextStep: plan.jumpCuts.some((cut) => cut.status === "needs-broll")
-					? "Create purpose=mask-cut needs for uncovered jump cuts, then run this planner again before asset matching."
-					: "Use plan.needs for B-roll asset matching and source-window selection.",
+				nextStep: plan.jumpCuts.some((cut) => cut.status === "review")
+					? "Review the actual picture at every status=review jump. Keep A-roll unless the cut is visibly objectionable; purpose=mask-cut requires visualReview with that exact output timestamp. Then resolve any plan.coverage warnings before matching assets."
+					: "Resolve any plan.coverage warnings, then use plan.needs for B-roll asset matching and source-window selection.",
 			});
 		},
 	});
@@ -308,7 +448,7 @@ export default function talkingHead(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "talking_head_apply",
 		label: "Apply talking-head timeline",
-		description: "Create a new immutable talking-head revision from word-boundary A-roll ranges and optional B-roll placements. B-roll requires the matching continuity plan receipt; brief A-roll flashes, unplanned ranges, and overlapping B-roll are rejected. Returns a generic pi-media timeline operation ready for edit_apply.",
+		description: "Create a new immutable talking-head revision from word-boundary A-roll ranges and optional B-roll placements. B-roll requires the matching continuity plan receipt; unplanned ranges, repeated source windows, brief A-roll flashes, and overlaps are rejected. Coverage and continuous-run concerns remain visible as editorial warnings. Returns a generic pi-media timeline operation ready for edit_apply.",
 		parameters: Type.Object({
 			projectId: stableId,
 			expectedRevision: Type.Integer({ minimum: 1 }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclip/pi-talking-head",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Pause-aware talking-head editing and B-roll planning for Pi, exported as generic pi-media EDLs",
   "type": "module",
   "license": "MIT",

package/prompts/edit-talking-head.md

@@ -2,6 +2,6 @@
 description: Tighten a talking-head video without destroying natural speech rhythm
 ---
 
-Use the `talking-head-edit` skill to review full-sentence context, word-level pauses, filler words, adjacent repetitions, and low-confidence delivery cues; stabilize A-roll, plan B-roll continuity to bridge brief A-roll flashes and mask objectionable jump cuts, match B-roll by filename before escalating through paged contact-sheet batches, validate the selected manifest-backed source window, and export a generic pi-media EDL for this request: $@
+Use the `talking-head-edit` skill to review full-sentence context, word-level pauses, filler words, adjacent repetitions, and low-confidence delivery cues; stabilize A-roll, let each complete spoken idea determine its B-roll duration, treat high coverage and long runs as review warnings rather than fixed limits, bridge brief A-roll flashes, mask only picture-reviewed objectionable jump cuts, avoid repeated source windows, match B-roll by filename before escalating through paged contact-sheet batches, validate the selected manifest-backed source window, and export a generic pi-media EDL for this request: $@
 
 Show the proposed rhythm before writing a new revision. Never overwrite the source or an existing render.

package/skills/talking-head-edit/SKILL.md

@@ -12,16 +12,16 @@ Use `pi-speech` for word evidence, this package for editorial decisions, and `pi
 3. Inspect bounded `talking_head_get` pages. Review the full sentence context, filler candidates, and repetition candidates together with pauses. Treat `safe` and every recommendation as evidence, not an instruction. Preserve pauses that carry emphasis, emotion, topic boundaries, or a deliberate breath.
 4. Never delete a filler token automatically. Decide whether `啊`, `额`, `嗯`, or a repeated token is a false start, a discourse marker, or intentional emphasis from its sentence context. A text-only delivery cue is low-confidence evidence; review audio and picture before relying on emotion or performance intent.
 5. Before changing the revision, summarize the proposed rhythm: what words and gaps will be removed, which pauses or fillers will remain, and why. Get the user's approval unless they explicitly delegated editorial judgment.
-6. Stabilize A-roll before B-roll. For every B-roll window, record the output range, complete spoken text, one purpose (`demonstrate`, `explain`, `evidence`, `establish`, `transition`, or `mask-cut`), 1-20 concise search terms, and a concrete reason.
-7. Call `talking_head_broll_plan` with the final proposed A-roll and all semantic B-roll needs before matching assets. Keep its `continuityPlanReceipt` unchanged. Use the returned `plan.needs`: it extends the previous B-roll across A-roll gaps of 500ms or less so neighboring B-roll clips hand off directly. Review every reported A-roll jump cut. Add a `purpose: mask-cut` need over each visually objectionable uncovered cut, using the suggested output range, then rerun the plan. Do not create meaningless B-roll solely because a cut exists; picture review remains the editorial gate.
+6. Stabilize A-roll before B-roll. A-roll carries the primary message; B-roll must show or clarify the object, action, place, comparison, or evidence being spoken about. For every window, record the complete spoken idea in `speechText`, choose one purpose (`demonstrate`, `explain`, `evidence`, `establish`, `transition`, or `mask-cut`), add 1-20 concise search terms, and explain what visual information it contributes. Let the spoken idea determine the window length; never use a fixed three-second rule or end B-roll before the thought finishes.
+7. Call `talking_head_broll_plan` with the stable A-roll and all semantic B-roll needs before matching assets. Keep its `continuityPlanReceipt` unchanged. Use `plan.needs` and inspect `plan.coverage`. Coverage above 50% and a continuous run above 8000ms are review signals, not fixed limits: remove decorative windows, but retain a longer demonstration when it remains useful for the complete spoken idea. The planner extends the previous B-roll across A-roll gaps of 500ms or less so neighboring clips hand off directly. A jump with `status: review` only asks for picture review. Keep A-roll by default; create `purpose: mask-cut` only after the actual picture is visibly objectionable. Save the reviewed image or video inside the workspace and submit `visualReview: { decision: "mask-with-broll", reviewedJumpCutOutputMs, artifactPath }`; the planner binds its hash into the v2 receipt and apply rejects changed evidence.
 8. Call `talking_head_broll_match` before generating contact sheets. Follow its bounded result:
    - `filename-direct`: probe and visually inspect only the selected asset to choose its source window. Do not call `media_contact_sheet` for unselected assets.
    - `filename-shortlist`: inspect only the returned shortlist and stop as soon as one asset satisfies the need. If none does and `nextCandidateOffset` is non-null, request that next page; do not repeat the first batch.
    - `visual-fallback`: use low-cost contact sheets on the bounded shortlist because filenames supplied no useful evidence. Exhaust that batch before requesting a non-null `nextCandidateOffset`.
    - If the scan is truncated, do not paginate it: narrow the asset directory and rescan so the candidate inventory is stable.
-9. After selecting one asset, call `media_probe`, then use `media_contact_sheet` only as densely as timing requires: one high-density pass for a short ambiguous clip, medium for a normal clip, or low over a long clip followed by high density over the narrowed range. Read `contact_sheet_manifest.json` timestamps instead of guessing times from the PNG. Verify a continuous source window at least as long as the planned output window, preferably with 500ms handles on both sides.
-10. Call `talking_head_broll_select` with each planned need, selected asset, manifest path, exact source start, and the manifest timestamps actually reviewed. Use its complete returned `placement`, including `selectionReceipt`; do not shorten bridged output ranges or hand-author selection fields.
-11. Call `talking_head_apply` using the same planned A-roll, every validated B-roll placement, and the unchanged `continuityPlanReceipt`. The tool rejects unplanned ranges, B-roll overlaps, and A-roll flashes of 500ms or less. Every B-roll window must have a concrete visual purpose in `reason`; keep `audio: keep-primary`.
+9. After selecting one asset, call `media_probe`, then use `media_contact_sheet` only as densely as timing requires: one high-density pass for a short ambiguous clip, medium for a normal clip, or low over a long clip followed by high density over the narrowed range. Read `contact_sheet_manifest.json` timestamps instead of guessing times from the PNG. Verify a continuous source window at least as long as the complete planned spoken idea, preferably with 500ms handles on both sides. If it is too short, choose a longer source window or another asset instead of cutting the idea short.
+10. Build a shot group when one spoken idea benefits from several views: use different angles, scales, assets, or source moments and let neighboring planned windows hand off directly. Call `talking_head_broll_select` for each need with the selected asset, manifest path, exact source start, and reviewed manifest timestamps. Use its complete returned `placement`, including `selectionReceipt`; do not shorten bridged output ranges or hand-author selection fields.
+11. Call `talking_head_apply` using the same planned A-roll, every validated B-roll placement, and the unchanged `continuityPlanReceipt`. The tool rejects unplanned ranges, any overlap between source windows from the same asset, output overlaps, and A-roll flashes of 500ms or less; coverage concerns are persisted as review warnings. Every B-roll window must have a concrete visual purpose in `reason`; keep `audio: keep-primary`.
 12. Create/read a `pi-media` project for the same source. Pass the returned `mediaOperation` unchanged to `edit_apply`, then `render` the exact new revision and call `review`.
 
 Never overwrite source media or outputs. If a revision conflict occurs, re-read both projects and reconcile intent. If the source, transcript, or B-roll hash changed, stop and ask whether to create a new project rather than silently adopting new bytes.

package/skills/talking-head-edit/references/cut-craft.md

@@ -23,7 +23,9 @@
 - Start with filename and directory metadata. Generate contact sheets only for the selected asset, a bounded ambiguous shortlist, or a bounded fallback batch whose names carry no meaning.
 - For a long selected asset, locate a broad range cheaply and then generate a denser contact sheet only for that range. Use manifest timestamps, not visual timestamp transcription.
 - Ensure the selected source window covers the complete spoken beat. Prefer extra source handles so a later timing adjustment does not require rescanning.
+- Let meaning and delivery rhythm set the duration. Coverage above 50% or one run above eight seconds deserves review, but is not automatically wrong when a long demonstration remains informative.
+- For one semantic beat, prefer a shot group of different angles, scales, assets, or source moments over repeating an identical clip.
 - If neighboring B-roll windows expose 500ms or less of A-roll, plan a direct handoff by extending the previous B-roll need before source-window selection. Do not let a few frames of A-roll flash between overlays.
-- Cover visible jump cuts when appropriate, but do not hide continuity errors that change meaning.
+- Treat every uncovered jump cut as a picture-review candidate, not a request for B-roll. Add a mask-cut only after confirming the actual jump is objectionable, recording its output timestamp, and binding the reviewed workspace image or video into the continuity receipt.
 - Keep the primary voice track. B-roll audio replacement is outside the current contract.
 - Record the search query and editorial reason so a later agent can replace the asset without guessing intent.

package/src/continuity.ts

@@ -5,10 +5,15 @@ import type {
 	BrollContinuityBridge,
 	BrollContinuityPlan,
 	BrollContinuityPlanReceipt,
+	BrollContinuityPlanReceiptV2,
+	BrollCoverageSummary,
 	BrollNeed,
 } from "./contracts.ts";
 import { timelineDuration } from "./transcript.ts";
 
+export const HIGH_BROLL_COVERAGE_REVIEW_RATIO = 0.5;
+export const LONG_CONTINUOUS_BROLL_REVIEW_MS = 8_000;
+
 export interface PlanBrollContinuityInput {
 	aroll: ArollSegment[];
 	needs: BrollNeed[];
@@ -105,6 +110,83 @@ export function findOverlappingBrollWindows(windows: BrollOutputWindow[]): Overl
 	return overlaps;
 }
 
+export function summarizeBrollCoverage(
+	windows: BrollOutputWindow[],
+	outputDurationMs: number,
+): BrollCoverageSummary {
+	if (!Number.isFinite(outputDurationMs) || outputDurationMs <= 0) {
+		throw new Error("outputDurationMs must be a positive finite number");
+	}
+	for (const window of windows) {
+		if (!Number.isFinite(window.outputStartMs) || !Number.isFinite(window.outputEndMs)
+			|| window.outputStartMs < 0 || window.outputEndMs <= window.outputStartMs
+			|| window.outputEndMs > outputDurationMs) {
+			throw new Error(`Invalid B-roll coverage window: ${window.id}`);
+		}
+	}
+	const sorted = [...windows].sort((left, right) => (
+		left.outputStartMs - right.outputStartMs
+		|| left.outputEndMs - right.outputEndMs
+		|| (left.id < right.id ? -1 : left.id > right.id ? 1 : 0)
+	));
+	let brollDurationMs = 0;
+	let longestContinuousBrollMs = 0;
+	let runStartMs: number | undefined;
+	let runEndMs: number | undefined;
+	for (const window of sorted) {
+		if (runStartMs === undefined || runEndMs === undefined) {
+			runStartMs = window.outputStartMs;
+			runEndMs = window.outputEndMs;
+			continue;
+		}
+		if (window.outputStartMs <= runEndMs) {
+			runEndMs = Math.max(runEndMs, window.outputEndMs);
+			continue;
+		}
+		const durationMs = runEndMs - runStartMs;
+		brollDurationMs += durationMs;
+		longestContinuousBrollMs = Math.max(longestContinuousBrollMs, durationMs);
+		runStartMs = window.outputStartMs;
+		runEndMs = window.outputEndMs;
+	}
+	if (runStartMs !== undefined && runEndMs !== undefined) {
+		const durationMs = runEndMs - runStartMs;
+		brollDurationMs += durationMs;
+		longestContinuousBrollMs = Math.max(longestContinuousBrollMs, durationMs);
+	}
+	const exactBrollCoverageRatio = brollDurationMs / outputDurationMs;
+	const brollCoverageRatio = Math.round(exactBrollCoverageRatio * 10_000) / 10_000;
+	const warnings: BrollCoverageSummary["warnings"] = [];
+	if (exactBrollCoverageRatio > HIGH_BROLL_COVERAGE_REVIEW_RATIO) {
+		const percent = ((brollDurationMs / outputDurationMs) * 100).toFixed(1);
+		warnings.push({
+			code: "high-total-coverage",
+			message: `B-roll covers ${percent}% of the output; review whether every window supports a complete spoken idea and keep A-roll whenever the picture adds no information.`,
+		});
+	}
+	if (longestContinuousBrollMs > LONG_CONTINUOUS_BROLL_REVIEW_MS) {
+		warnings.push({
+			code: "long-continuous-run",
+			message: `One continuous B-roll run lasts ${longestContinuousBrollMs}ms; confirm that its source window remains useful for the full spoken idea or split it into a varied shot group.`,
+		});
+	}
+	return {
+		brollDurationMs,
+		arollDurationMs: outputDurationMs - brollDurationMs,
+		brollCoverageRatio,
+		longestContinuousBrollMs,
+		limits: {
+			maxBrollCoverageRatio: HIGH_BROLL_COVERAGE_REVIEW_RATIO,
+			maxContinuousBrollMs: LONG_CONTINUOUS_BROLL_REVIEW_MS,
+		},
+		reviewThresholds: {
+			highBrollCoverageRatio: HIGH_BROLL_COVERAGE_REVIEW_RATIO,
+			longContinuousBrollMs: LONG_CONTINUOUS_BROLL_REVIEW_MS,
+		},
+		warnings,
+	};
+}
+
 function validateSegments(aroll: ArollSegment[]): void {
 	if (aroll.length === 0 || aroll.length > 1_000) throw new Error("A-roll must contain 1-1000 segments");
 	const ids = new Set<string>();
@@ -118,10 +200,24 @@ function validateSegments(aroll: ArollSegment[]): void {
 	}
 }
 
-function validateNeeds(needs: BrollNeed[], outputDurationMs: number): void {
+function arollJumpCutOutputTimes(aroll: ArollSegment[]): Set<number> {
+	const outputTimes = new Set<number>();
+	let outputTimeMs = 0;
+	for (let index = 0; index < aroll.length - 1; index += 1) {
+		const current = aroll[index]!;
+		const next = aroll[index + 1]!;
+		outputTimeMs += current.sourceEndMs - current.sourceStartMs;
+		if (next.sourceStartMs !== current.sourceEndMs) outputTimes.add(outputTimeMs);
+	}
+	return outputTimes;
+}
+
+function validateNeeds(needs: BrollNeed[], outputDurationMs: number, aroll: ArollSegment[]): void {
 	if (needs.length > 500) throw new Error("B-roll plan must contain at most 500 needs");
 	const ids = new Set<string>();
+	const jumpCutOutputTimes = arollJumpCutOutputTimes(aroll);
 	for (const need of needs) {
+		const unexpectedVisualReview = (need as { visualReview?: unknown }).visualReview;
 		if (ids.has(need.id)) throw new Error(`Duplicate B-roll need ID: ${need.id}`);
 		ids.add(need.id);
 		if (!Number.isFinite(need.outputStartMs) || !Number.isFinite(need.outputEndMs)
@@ -129,6 +225,27 @@ function validateNeeds(needs: BrollNeed[], outputDurationMs: number): void {
 			|| need.outputEndMs > outputDurationMs) {
 			throw new Error(`Invalid B-roll need output range: ${need.id}`);
 		}
+		if (!need.speechText.trim()) throw new Error(`B-roll need ${need.id} must name the complete spoken idea it supports`);
+		if (!need.reason.trim()) throw new Error(`B-roll need ${need.id} must explain why the picture adds information`);
+		if (need.purpose === "mask-cut") {
+			if (need.visualReview?.decision !== "mask-with-broll"
+				|| !Number.isFinite(need.visualReview.reviewedJumpCutOutputMs)) {
+				throw new Error(`B-roll mask-cut need ${need.id} requires visualReview evidence for an objectionable A-roll jump`);
+			}
+			const reviewedOutputMs = need.visualReview.reviewedJumpCutOutputMs;
+			if (!jumpCutOutputTimes.has(reviewedOutputMs)) {
+				throw new Error(`B-roll mask-cut need ${need.id} visualReview does not identify an A-roll source jump`);
+			}
+			if (reviewedOutputMs <= need.outputStartMs || reviewedOutputMs >= need.outputEndMs) {
+				throw new Error(`B-roll mask-cut need ${need.id} must span the reviewed A-roll jump`);
+			}
+			if (!need.visualReview.artifactPath.trim()
+				|| !/^[a-f0-9]{64}$/.test(need.visualReview.artifactSha256 ?? "")) {
+				throw new Error(`B-roll mask-cut need ${need.id} requires a verified visual review artifact`);
+			}
+		} else if (unexpectedVisualReview !== undefined) {
+			throw new Error(`B-roll visualReview is only valid for purpose=mask-cut: ${need.id}`);
+		}
 	}
 	const overlap = findOverlappingBrollWindows(needs)[0];
 	if (overlap) throw new Error(`B-roll needs ${overlap.underBrollId} and ${overlap.overBrollId} overlap; z-order is not supported`);
@@ -222,7 +339,7 @@ export function analyzeArollJumpCuts(
 			suggestedOutputStartMs,
 			suggestedOutputEndMs,
 			coveredByNeedIds: coverage.needIds,
-			status: coverage.covered ? "covered" : "needs-broll",
+			status: coverage.covered ? "covered" : "review",
 		});
 	}
 	return jumpCuts;
@@ -231,7 +348,7 @@ export function analyzeArollJumpCuts(
 export function planBrollContinuity(input: PlanBrollContinuityInput): BrollContinuityPlan {
 	validateSegments(input.aroll);
 	const outputDurationMs = timelineDuration(input.aroll);
-	validateNeeds(input.needs, outputDurationMs);
+	validateNeeds(input.needs, outputDurationMs, input.aroll);
 	const shortGapMs = boundedMilliseconds(input.shortGapMs, 500, "shortGapMs", 2_000);
 	const cutCoverBeforeMs = boundedMilliseconds(input.cutCoverBeforeMs, 250, "cutCoverBeforeMs", 2_000);
 	const cutCoverAfterMs = boundedMilliseconds(input.cutCoverAfterMs, 500, "cutCoverAfterMs", 2_000);
@@ -239,6 +356,7 @@ export function planBrollContinuity(input: PlanBrollContinuityInput): BrollConti
 		throw new Error("cutCoverBeforeMs and cutCoverAfterMs cannot both be zero");
 	}
 	const bridged = bridgeShortGaps(input.needs, shortGapMs);
+	const coverage = summarizeBrollCoverage(bridged.needs, outputDurationMs);
 	return {
 		outputDurationMs,
 		shortGapMs,
@@ -246,6 +364,7 @@ export function planBrollContinuity(input: PlanBrollContinuityInput): BrollConti
 		cutCoverAfterMs,
 		needs: bridged.needs,
 		bridges: bridged.bridges,
+		coverage,
 		jumpCuts: analyzeArollJumpCuts(
 			input.aroll,
 			bridged.needs,
@@ -256,7 +375,9 @@ export function planBrollContinuity(input: PlanBrollContinuityInput): BrollConti
 	};
 }
 
-function planReceiptPayload(receipt: Omit<BrollContinuityPlanReceipt, "planSha256">): string {
+type BrollContinuityPlanReceiptPayload = Omit<BrollContinuityPlanReceipt, "planSha256">;
+
+function planReceiptPayload(receipt: BrollContinuityPlanReceiptPayload): string {
 	return canonicalJson(receipt);
 }
 
@@ -279,7 +400,11 @@ function arollSha256(aroll: ArollSegment[]): string {
 	return sha256(canonicalJson(aroll));
 }
 
-function plannedRanges(needs: BrollNeed[]): BrollContinuityPlanReceipt["needs"] {
+function plannedRanges(needs: Array<Pick<BrollNeed, "id" | "outputStartMs" | "outputEndMs">>): Array<{
+	id: string;
+	outputStartMs: number;
+	outputEndMs: number;
+}> {
 	return needs.map((need) => ({
 		id: need.id,
 		outputStartMs: need.outputStartMs,
@@ -287,21 +412,51 @@ function plannedRanges(needs: BrollNeed[]): BrollContinuityPlanReceipt["needs"]
 	}));
 }
 
+function plannedNeedsV2(needs: BrollNeed[]): BrollContinuityPlanReceiptV2["needs"] {
+	return needs.map((need) => {
+		const range = {
+			id: need.id,
+			outputStartMs: need.outputStartMs,
+			outputEndMs: need.outputEndMs,
+		};
+		if (need.purpose !== "mask-cut") return { ...range, purpose: need.purpose };
+		const artifactSha256 = need.visualReview.artifactSha256;
+		if (artifactSha256 === undefined) {
+			throw new Error(`B-roll mask-cut need ${need.id} requires a verified visual review artifact`);
+		}
+		return {
+			...range,
+			purpose: "mask-cut",
+			visualReview: {
+				...structuredClone(need.visualReview),
+				artifactSha256,
+			},
+		};
+	});
+}
+
+export function normalizeArollJumpCutStatuses(jumpCuts: ArollJumpCut[]): ArollJumpCut[] {
+	return jumpCuts.map((jumpCut) => ({
+		...jumpCut,
+		status: jumpCut.status === "needs-broll" ? "review" : jumpCut.status,
+	}));
+}
+
 export function createBrollContinuityPlanReceipt(
 	projectId: string,
 	revision: number,
 	aroll: ArollSegment[],
 	plan: BrollContinuityPlan,
-): BrollContinuityPlanReceipt {
-	const payload: Omit<BrollContinuityPlanReceipt, "planSha256"> = {
-		schemaVersion: 1,
+): BrollContinuityPlanReceiptV2 {
+	const payload: Omit<BrollContinuityPlanReceiptV2, "planSha256"> = {
+		schemaVersion: 2,
 		projectId,
 		revision,
 		arollSha256: arollSha256(aroll),
 		shortGapMs: plan.shortGapMs,
 		cutCoverBeforeMs: plan.cutCoverBeforeMs,
 		cutCoverAfterMs: plan.cutCoverAfterMs,
-		needs: plannedRanges(plan.needs),
+		needs: plannedNeedsV2(plan.needs),
 		jumpCuts: structuredClone(plan.jumpCuts),
 	};
 	return { ...payload, planSha256: sha256(planReceiptPayload(payload)) };
@@ -314,7 +469,8 @@ export function verifyBrollContinuityPlanReceipt(
 	placements: BrollOutputWindow[],
 	receipt: BrollContinuityPlanReceipt,
 ): void {
-	if (receipt.schemaVersion !== 1 || receipt.projectId !== projectId || receipt.revision !== revision) {
+	if ((receipt.schemaVersion !== 1 && receipt.schemaVersion !== 2)
+		|| receipt.projectId !== projectId || receipt.revision !== revision) {
 		throw new Error("B-roll continuity receipt does not match the current project revision");
 	}
 	if (receipt.arollSha256 !== arollSha256(aroll)) {
@@ -324,13 +480,20 @@ export function verifyBrollContinuityPlanReceipt(
 	if (planSha256 !== sha256(planReceiptPayload(payload))) {
 		throw new Error("B-roll continuity receipt hash is invalid");
 	}
-	const dummyNeeds: BrollNeed[] = receipt.needs.map((need) => ({
-		...need,
-		speechText: "continuity receipt",
-		purpose: "mask-cut",
-		searchTerms: ["continuity"],
-		reason: "continuity receipt verification",
-	}));
+	const dummyNeeds: BrollNeed[] = receipt.schemaVersion === 1
+		? receipt.needs.map((need) => ({
+				...need,
+				speechText: "continuity receipt",
+				purpose: "demonstrate",
+				searchTerms: ["continuity"],
+				reason: "continuity receipt verification",
+			}))
+		: receipt.needs.map((need) => ({
+				...need,
+				speechText: "continuity receipt",
+				searchTerms: ["continuity"],
+				reason: "continuity receipt verification",
+			}));
 	const recomputed = planBrollContinuity({
 		aroll,
 		needs: dummyNeeds,
@@ -338,8 +501,11 @@ export function verifyBrollContinuityPlanReceipt(
 		cutCoverBeforeMs: receipt.cutCoverBeforeMs,
 		cutCoverAfterMs: receipt.cutCoverAfterMs,
 	});
-	if (canonicalJson(plannedRanges(recomputed.needs)) !== canonicalJson(receipt.needs)
-		|| canonicalJson(recomputed.jumpCuts) !== canonicalJson(receipt.jumpCuts)) {
+	const recomputedNeeds = receipt.schemaVersion === 1
+		? plannedRanges(recomputed.needs)
+		: plannedNeedsV2(recomputed.needs);
+	if (canonicalJson(recomputedNeeds) !== canonicalJson(receipt.needs)
+		|| canonicalJson(normalizeArollJumpCutStatuses(recomputed.jumpCuts)) !== canonicalJson(normalizeArollJumpCutStatuses(receipt.jumpCuts))) {
 		throw new Error("B-roll continuity receipt does not match the recomputed plan");
 	}
 	const actualRanges = [...placements].sort((left, right) => (
@@ -349,7 +515,7 @@ export function verifyBrollContinuityPlanReceipt(
 		outputStartMs: placement.outputStartMs,
 		outputEndMs: placement.outputEndMs,
 	}));
-	if (canonicalJson(actualRanges) !== canonicalJson(receipt.needs)) {
+	if (canonicalJson(actualRanges) !== canonicalJson(plannedRanges(receipt.needs))) {
 		throw new Error("B-roll placements do not match the planned ranges");
 	}
 }

package/src/contracts.ts

@@ -121,16 +121,32 @@ export type BrollPlacementInput = Omit<
 
 export type BrollPurpose = "demonstrate" | "explain" | "evidence" | "establish" | "transition" | "mask-cut";
 
-export interface BrollNeed {
+export interface BrollVisualReview {
+	decision: "mask-with-broll";
+	reviewedJumpCutOutputMs: number;
+	artifactPath: string;
+	artifactSha256?: string;
+}
+
+interface BrollNeedBase {
 	id: string;
 	outputStartMs: number;
 	outputEndMs: number;
 	speechText: string;
-	purpose: BrollPurpose;
 	searchTerms: string[];
 	reason: string;
 }
 
+export type BrollNeed =
+	| BrollNeedBase & {
+		purpose: Exclude<BrollPurpose, "mask-cut">;
+		visualReview?: never;
+	}
+	| BrollNeedBase & {
+		purpose: "mask-cut";
+		visualReview: BrollVisualReview;
+	};
+
 export interface BrollAssetCandidate {
 	assetPath: string;
 	fileName: string;
@@ -182,7 +198,27 @@ export interface ArollJumpCut {
 	suggestedOutputStartMs: number;
 	suggestedOutputEndMs: number;
 	coveredByNeedIds: string[];
-	status: "covered" | "needs-broll";
+	status: "covered" | "review" | "needs-broll";
+}
+
+export interface BrollCoverageSummary {
+	brollDurationMs: number;
+	arollDurationMs: number;
+	brollCoverageRatio: number;
+	longestContinuousBrollMs: number;
+	/** @deprecated Compatibility alias for v0.1.5 clients; these values are review thresholds, not hard limits. */
+	limits: {
+		maxBrollCoverageRatio: number;
+		maxContinuousBrollMs: number;
+	};
+	reviewThresholds?: {
+		highBrollCoverageRatio: number;
+		longContinuousBrollMs: number;
+	};
+	warnings?: Array<{
+		code: "high-total-coverage" | "long-continuous-run";
+		message: string;
+	}>;
 }
 
 export interface BrollContinuityPlan {
@@ -193,21 +229,39 @@ export interface BrollContinuityPlan {
 	needs: BrollNeed[];
 	bridges: BrollContinuityBridge[];
 	jumpCuts: ArollJumpCut[];
+	coverage: BrollCoverageSummary;
 }
 
-export interface BrollContinuityPlanReceipt {
-	schemaVersion: 1;
+interface BrollContinuityPlanReceiptBase {
 	projectId: string;
 	revision: number;
 	arollSha256: string;
 	shortGapMs: number;
 	cutCoverBeforeMs: number;
 	cutCoverAfterMs: number;
-	needs: Array<{ id: string; outputStartMs: number; outputEndMs: number }>;
 	jumpCuts: ArollJumpCut[];
 	planSha256: string;
 }
 
+export interface BrollContinuityPlanReceiptV1 extends BrollContinuityPlanReceiptBase {
+	schemaVersion: 1;
+	needs: Array<{ id: string; outputStartMs: number; outputEndMs: number }>;
+}
+
+export interface BrollContinuityPlanReceiptV2 extends BrollContinuityPlanReceiptBase {
+	schemaVersion: 2;
+	needs: Array<({
+		id: string;
+		outputStartMs: number;
+		outputEndMs: number;
+	} & (
+		| { purpose: Exclude<BrollPurpose, "mask-cut">; visualReview?: never }
+		| { purpose: "mask-cut"; visualReview: BrollVisualReview & { artifactSha256: string } }
+	))>;
+}
+
+export type BrollContinuityPlanReceipt = BrollContinuityPlanReceiptV1 | BrollContinuityPlanReceiptV2;
+
 export interface TranscriptAnalysis {
 	schemaVersion: 2;
 	text: string;
@@ -244,7 +298,7 @@ export interface TalkingHeadProject {
 }
 
 export interface TalkingHeadSnapshot {
-	schemaVersion: 1;
+	schemaVersion: 1 | 2;
 	projectId: string;
 	revision: number;
 	parentRevision: number | null;
@@ -254,6 +308,7 @@ export interface TalkingHeadSnapshot {
 	broll: BrollPlacement[];
 	continuityPlanReceipt?: BrollContinuityPlanReceipt;
 	jumpCuts?: ArollJumpCut[];
+	brollCoverage?: BrollCoverageSummary;
 	outputDurationMs: number;
 }
 

package/src/project.ts

@@ -22,6 +22,8 @@ import {
 	analyzeArollJumpCuts,
 	findOverlappingBrollWindows,
 	findShortArollFlashGaps,
+	normalizeArollJumpCutStatuses,
+	summarizeBrollCoverage,
 	verifyBrollContinuityPlanReceipt,
 } from "./continuity.ts";
 import { analyzeTranscript, DEFAULT_POLICY, timelineDuration } from "./transcript.ts";
@@ -82,6 +84,39 @@ function uniqueIds(values: Array<{ id: string }>, label: string): void {
 	}
 }
 
+function assertDistinctBrollSourceWindows(broll: BrollPlacementInput[]): void {
+	for (let leftIndex = 0; leftIndex < broll.length; leftIndex += 1) {
+		const left = broll[leftIndex]!;
+		const leftEndMs = left.assetStartMs + (left.outputEndMs - left.outputStartMs);
+		for (let rightIndex = leftIndex + 1; rightIndex < broll.length; rightIndex += 1) {
+			const right = broll[rightIndex]!;
+			if (left.selectionReceipt.assetSha256 !== right.selectionReceipt.assetSha256) continue;
+			const rightEndMs = right.assetStartMs + (right.outputEndMs - right.outputStartMs);
+			if (left.assetStartMs === right.assetStartMs && leftEndMs === rightEndMs) {
+				throw new Error(`B-roll placement ${right.id} reuses the same B-roll source window as ${left.id}; select a different source moment or angle`);
+			}
+			if (Math.max(left.assetStartMs, right.assetStartMs) < Math.min(leftEndMs, rightEndMs)) {
+				throw new Error(`B-roll placement ${right.id} overlaps the B-roll source window used by ${left.id}; select non-repeating frames`);
+			}
+		}
+	}
+}
+
+async function assertVisualReviewArtifactsUnchanged(
+	cwd: string,
+	receipt: BrollContinuityPlanReceipt,
+	signal?: AbortSignal,
+): Promise<void> {
+	if (receipt.schemaVersion !== 2) return;
+	for (const need of receipt.needs) {
+		if (!need.visualReview) continue;
+		const artifact = await snapshotFile(cwd, need.visualReview.artifactPath, signal);
+		if (artifact.sha256 !== need.visualReview.artifactSha256) {
+			throw new Error(`B-roll visual review artifact changed after continuity planning: ${need.visualReview.artifactPath}`);
+		}
+	}
+}
+
 async function validateTimeline(
 	cwd: string,
 	aroll: ArollSegment[],
@@ -90,7 +125,12 @@ async function validateTimeline(
 	revision: number,
 	continuityPlanReceipt: BrollContinuityPlanReceipt | undefined,
 	signal?: AbortSignal,
-): Promise<{ outputDurationMs: number; broll: BrollPlacement[]; jumpCuts: ReturnType<typeof analyzeArollJumpCuts> }> {
+): Promise<{
+	outputDurationMs: number;
+	broll: BrollPlacement[];
+	brollCoverage: ReturnType<typeof summarizeBrollCoverage>;
+	jumpCuts: ReturnType<typeof analyzeArollJumpCuts>;
+}> {
 	if (aroll.length === 0 || aroll.length > 1_000) throw new Error("A-roll must contain 1-1000 segments");
 	uniqueIds(aroll, "A-roll segment");
 	for (const segment of aroll) {
@@ -124,11 +164,14 @@ async function validateTimeline(
 	if (flashGap) {
 		throw new Error(`B-roll placements ${flashGap.fromBrollId} and ${flashGap.toBrollId} leave a brief ${flashGap.durationMs}ms A-roll flash; run talking_head_broll_plan and reselect the bridged window`);
 	}
+	assertDistinctBrollSourceWindows(broll);
+	const brollCoverage = summarizeBrollCoverage(broll, outputDurationMs);
 	if (broll.length > 0 && !continuityPlanReceipt) {
 		throw new Error("B-roll continuityPlanReceipt is required; run talking_head_broll_plan first");
 	}
 	if (continuityPlanReceipt) {
 		verifyBrollContinuityPlanReceipt(projectId, revision, aroll, broll, continuityPlanReceipt);
+		await assertVisualReviewArtifactsUnchanged(cwd, continuityPlanReceipt, signal);
 	}
 	const normalizedBroll: BrollPlacement[] = [];
 	for (const placement of broll) {
@@ -144,8 +187,9 @@ async function validateTimeline(
 	return {
 		outputDurationMs,
 		broll: normalizedBroll,
+		brollCoverage,
 		jumpCuts: continuityPlanReceipt
-			? structuredClone(continuityPlanReceipt.jumpCuts)
+			? normalizeArollJumpCutStatuses(continuityPlanReceipt.jumpCuts)
 			: analyzeArollJumpCuts(aroll, broll, outputDurationMs, 250, 500),
 	};
 }
@@ -206,7 +250,7 @@ export async function createTalkingHeadProject(cwd: string, input: CreateTalking
 		updatedAt: now,
 	};
 	const snapshot: TalkingHeadSnapshot = {
-		schemaVersion: 1,
+		schemaVersion: 2,
 		projectId: input.projectId,
 		revision: 1,
 		parentRevision: null,
@@ -214,6 +258,7 @@ export async function createTalkingHeadProject(cwd: string, input: CreateTalking
 		policy,
 		aroll: analysis.segments,
 		broll: [],
+		brollCoverage: summarizeBrollCoverage([], analysis.outputDurationMs),
 		jumpCuts: analyzeArollJumpCuts(analysis.segments, [], analysis.outputDurationMs, 250, 500),
 		outputDurationMs: analysis.outputDurationMs,
 	};
@@ -250,7 +295,8 @@ export async function getTalkingHeadProject(cwd: string, projectId: string, revi
 		join(directory, "snapshots", `${selectedRevision}.json`),
 		`talking-head snapshot ${projectId}@${selectedRevision}`,
 	);
-	if (snapshot.schemaVersion !== 1 || snapshot.projectId !== projectId || snapshot.revision !== selectedRevision) {
+	if ((snapshot.schemaVersion !== 1 && snapshot.schemaVersion !== 2)
+		|| snapshot.projectId !== projectId || snapshot.revision !== selectedRevision) {
 		throw new Error(`Invalid talking-head snapshot: ${projectId}@${selectedRevision}`);
 	}
 	return { project, snapshot };
@@ -294,7 +340,7 @@ export async function applyTimeline(cwd: string, input: ApplyTimelineInput, sign
 		const revision = project.currentRevision + 1;
 		const now = new Date().toISOString();
 		const snapshot: TalkingHeadSnapshot = {
-			schemaVersion: 1,
+			schemaVersion: 2,
 			projectId: input.projectId,
 			revision,
 			parentRevision: current.revision,
@@ -302,6 +348,7 @@ export async function applyTimeline(cwd: string, input: ApplyTimelineInput, sign
 			policy: current.policy,
 			aroll: structuredClone(input.aroll),
 			broll: validated.broll,
+			brollCoverage: validated.brollCoverage,
 			jumpCuts: validated.jumpCuts,
 			...(input.continuityPlanReceipt === undefined
 				? {}