@speclip/pi-talking-head 0.1.2 → 0.1.4

package/README.md

@@ -71,33 +71,111 @@ talking_head_get {
 
 只有调用这个工具时才会把这些证据放进当前会话上下文；安装 package 不会把整份转录常驻注入上下文。
 
-### 3. 写入人工确认后的时间线
+### 3. 先规划 B-roll 视觉连续性
+
+在查找素材前，把最终 A-roll 和所有 B-roll 需求交给连续性规划工具：
+
+```js
+talking_head_broll_plan {
+  projectId: "launch-video",
+  aroll: [
+    { id: "hook", sourceStartMs: 50, sourceEndMs: 4120 },
+    { id: "answer", sourceStartMs: 4860, sourceEndMs: 13200 }
+  ],
+  needs: [
+    {
+      id: "product-a",
+      outputStartMs: 1000,
+      outputEndMs: 3000,
+      speechText: "第一步打开设置",
+      purpose: "demonstrate",
+      searchTerms: ["设置", "打开"],
+      reason: "展示第一步"
+    },
+    {
+      id: "product-b",
+      outputStartMs: 3300,
+      outputEndMs: 5200,
+      speechText: "第二步选择设备",
+      purpose: "demonstrate",
+      searchTerms: ["设备", "选择"],
+      reason: "展示第二步"
+    }
+  ],
+  cutCoverBeforeMs: 250,
+  cutCoverAfterMs: 500
+}
+```
+
+规划结果同时返回 `continuityPlanReceipt`，把当前项目 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"` 的需求，再重新规划。
+
+规划只提供时间轴证据，不会假定每个剪辑点都必须加 B-roll。是否遮盖仍需结合实际画面判断。
+
+### 4. 文件名优先筛选 B-roll
+
+使用 `plan.needs` 中已经调整过的完整区间，再扫描指定素材目录：
+
+```js
+talking_head_broll_match {
+  projectId: "launch-video",
+  assetDirectory: "assets/broll",
+  recursive: true,
+  maxFiles: 1000,
+  maxEntries: 20000,
+  maxDepth: 12,
+  maxCandidates: 5,
+  candidateOffset: 0,
+  need: plan.needs[0]
+}
+```
+
+该工具只读取目录项和文件名，不解码、不探测、不哈希视频。它最多返回限定数量的候选，并给出三种结果：
+
+- `filename-direct`：一个文件名唯一且明确命中，只检查这一条素材。
+- `filename-shortlist`：多个名字可能匹配，只检查返回的 shortlist。
+- `visual-fallback`：文件名没有有效语义，再对限定 shortlist 使用低成本联络表。
+
+扫描同时受 `maxFiles`、`maxEntries` 和 `maxDepth` 约束并支持取消。完整扫描时，若当前 shortlist 都不合格，可使用非空的 `nextCandidateOffset` 读取下一批。结果一旦截断，工具不会声称唯一命中，也不会返回可复用的分页游标；此时应缩小素材目录后重扫，避免文件系统枚举顺序造成候选漂移。
+
+确定素材后才调用 `media_probe` 和 `media_contact_sheet`。长素材先低密度定位大致范围，再只对候选范围高密度抽帧；必须使用 `contact_sheet_manifest.json` 的真实时间戳，不能从 PNG 猜时间。找到连续可用且覆盖完整成片窗口的片段后，验证并生成 placement：
+
+```js
+talking_head_broll_select {
+  projectId: "launch-video",
+  need: { /* 与 match 时相同 */ },
+  assetPath: "assets/broll/mouse-demo.mp4",
+  manifestPath: "analysis/mouse-demo/contact_sheet_manifest.json",
+  selectedStartMs: 12400,
+  evidenceTimestampsMs: [12400, 13900, 15400],
+  fit: "cover"
+}
+```
+
+该工具会验证素材 SHA-256、manifest 分析范围、起始帧和覆盖片段尾部的证据时间戳，返回可直接交给 `talking_head_apply` 的完整 placement。placement 内含选择凭证；不要手写或删除其中字段。
+
+### 5. 写入人工确认后的时间线
 
 ```js
 talking_head_apply {
   projectId: "launch-video",
   expectedRevision: 1,
-  arroll: [
+  aroll: [
     { id: "hook", sourceStartMs: 50, sourceEndMs: 4120 },
     { id: "answer", sourceStartMs: 4860, sourceEndMs: 13200 }
   ],
-  broll: [{
-    id: "product-demo",
-    assetPath: "assets/product-demo.mp4",
-    outputStartMs: 5200,
-    outputEndMs: 7900,
-    assetStartMs: 0,
-    fit: "cover",
-    audio: "keep-primary",
-    query: "产品界面操作特写",
-    reason: "具体展示口播中提到的三步操作"
-  }]
+  broll: [selectionA.placement, selectionB.placement],
+  continuityPlanReceipt
 }
 ```
 
-B-roll 使用成片时间轴定位，永远保留主口播音轨。工具会固定素材字节数和 SHA-256，素材被替换后拒绝导出 EDL。
+B-roll 使用成片时间轴定位，`assetStartMs` 来自联络表 manifest，并永远保留主口播音轨。`talking_head_apply` 会重新校验连续性规划凭证、选段凭证、素材与 manifest 的 SHA-256；规划区间或时间点被手改、素材被替换都会拒绝写入新修订。若两个 B-roll 之间仍存在不超过 500ms 的 A-roll，也会拒绝写入并要求重新规划。当前不支持 B-roll 相互重叠，因为未定义 z-order。
 
-### 4. 交给 pi-media 渲染
+### 6. 交给 pi-media 渲染
 
 先用同一个源文件创建 `pi-media` 项目，再把上一步的 `mediaOperation` 原样传入：
 
@@ -125,8 +203,11 @@ 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_match` | 只用文件名和目录名匹配本地 B-roll，返回受限 shortlist 与视觉升级建议 |
+| `talking_head_broll_select` | 用 pi-media 联络表 manifest 验证具体源时间段并生成 placement |
 | `talking_head_apply` | 写入新的不可变口播 revision，并返回 pi-media EDL |
 
 ## 当前边界
 
-当前版本不负责语音转录、声学情绪识别、素材搜索、字幕、画面理解或渲染。它提供整句文本与时间轴层面的编辑证据；需要依赖真实语气、呼吸或表演意图的决定，必须由 Agent 结合原音频和画面复核。B-roll 的搜索与视觉匹配最终仍写入同一份 `broll` 数据并由 `pi-media` 渲染。
+当前版本不负责语音转录、声学情绪识别、联网素材搜索、字幕、画面理解或渲染。它提供整句文本、时间轴和本地素材名称层面的编辑证据；需要依赖真实语气、呼吸、表演意图或画面内容的决定，必须由 Agent 结合原音频、联络表和画面复核。最终 B-roll 仍写入同一份 `broll` 数据并由 `pi-media` 渲染。

package/extensions/talking-head/index.ts

@@ -1,5 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { matchWorkspaceBrollAssets, selectBrollWindow } from "../../src/broll.ts";
+import { createBrollContinuityPlanReceipt, planBrollContinuity } from "../../src/continuity.ts";
 import { toMediaTimelineOperation } from "../../src/edl.ts";
 import {
 	applyTimeline,
@@ -22,7 +24,7 @@ const stableId = Type.String({
 	pattern: "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$",
 });
 
-const arrollSegment = Type.Object({
+const arollSegment = Type.Object({
 	id: stableId,
 	sourceStartMs: Type.Number({ minimum: 0 }),
 	sourceEndMs: Type.Number({ exclusiveMinimum: 0 }),
@@ -33,11 +35,64 @@ const brollPlacement = Type.Object({
 	assetPath: Type.String({ description: "Workspace-relative B-roll video path." }),
 	outputStartMs: Type.Number({ minimum: 0 }),
 	outputEndMs: Type.Number({ exclusiveMinimum: 0 }),
-	assetStartMs: Type.Optional(Type.Number({ minimum: 0 })),
+	assetStartMs: Type.Number({ minimum: 0, description: "Required manifest-backed source timestamp selected from the B-roll asset." }),
 	fit: Type.Union([Type.Literal("cover"), Type.Literal("contain")]),
 	audio: Type.Literal("keep-primary", { description: "B-roll never replaces the talking-head audio." }),
 	query: Type.Optional(Type.String({ maxLength: 500 })),
 	reason: Type.Optional(Type.String({ maxLength: 1_000 })),
+	selectionReceipt: Type.Object({
+		assetBytes: Type.Integer({ minimum: 0 }),
+		assetSha256: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+		manifestPath: Type.String({ minLength: 1 }),
+		manifestSha256: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+		selectedEndMs: Type.Number({ minimum: 0 }),
+		evidenceTimestampsMs: Type.Array(Type.Number({ minimum: 0 }), { minItems: 1, maxItems: 100 }),
+	}, { additionalProperties: false }),
+}, { additionalProperties: false });
+
+const brollNeed = Type.Object({
+	id: stableId,
+	outputStartMs: Type.Number({ minimum: 0 }),
+	outputEndMs: Type.Number({ exclusiveMinimum: 0 }),
+	speechText: Type.String({ minLength: 1, maxLength: 2_000 }),
+	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 arollJumpCut = Type.Object({
+	fromSegmentId: stableId,
+	toSegmentId: stableId,
+	outputTimeMs: Type.Number({ minimum: 0 }),
+	sourceDeltaMs: Type.Number(),
+	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")]),
+}, { additionalProperties: false });
+
+const continuityPlanReceipt = Type.Object({
+	schemaVersion: Type.Literal(1),
+	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 }),
+	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 });
 
 export default function talkingHead(pi: ExtensionAPI): void {
@@ -53,7 +108,7 @@ export default function talkingHead(pi: ExtensionAPI): void {
 			headPaddingMs: Type.Optional(Type.Number({ minimum: 30, maximum: 200 })),
 			tailPaddingMs: Type.Optional(Type.Number({ minimum: 30, maximum: 200 })),
 		}, { additionalProperties: false }),
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			const policy = {
 				...(params.cutThresholdMs === undefined ? {} : { cutThresholdMs: params.cutThresholdMs }),
 				...(params.headPaddingMs === undefined ? {} : { headPaddingMs: params.headPaddingMs }),
@@ -142,19 +197,128 @@ 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.",
+		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 }),
+			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) {
+			const { snapshot } = await getTalkingHeadProject(ctx.cwd, params.projectId, params.revision);
+			const plan = planBrollContinuity({
+				aroll: params.aroll,
+				needs: params.needs,
+				...(params.cutCoverBeforeMs === undefined ? {} : { cutCoverBeforeMs: params.cutCoverBeforeMs }),
+				...(params.cutCoverAfterMs === undefined ? {} : { cutCoverAfterMs: params.cutCoverAfterMs }),
+			});
+			return result({
+				projectId: params.projectId,
+				revision: snapshot.revision,
+				plan,
+				continuityPlanReceipt: createBrollContinuityPlanReceipt(
+					params.projectId,
+					snapshot.revision,
+					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.",
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "talking_head_broll_match",
+		label: "Match local B-roll assets",
+		description: "Filename-first B-roll matching for one approved output window. Scans only directory metadata, returns a bounded shortlist, and tells the Agent whether to inspect one selected asset, inspect an ambiguous shortlist, or fall back to low-cost visual screening. It never decodes, probes, or hashes video contents.",
+		parameters: Type.Object({
+			projectId: stableId,
+			revision: Type.Optional(Type.Integer({ minimum: 1 })),
+			assetDirectory: Type.String({ minLength: 1, description: "Workspace-relative directory containing candidate B-roll videos." }),
+			recursive: Type.Optional(Type.Boolean()),
+			maxFiles: Type.Optional(Type.Integer({ minimum: 1, maximum: 5_000 })),
+			maxEntries: Type.Optional(Type.Integer({ minimum: 1, maximum: 100_000 })),
+			maxDepth: Type.Optional(Type.Integer({ minimum: 0, maximum: 50 })),
+			maxCandidates: Type.Optional(Type.Integer({ minimum: 1, maximum: 20 })),
+			candidateOffset: Type.Optional(Type.Integer({ minimum: 0 })),
+			need: brollNeed,
+		}, { additionalProperties: false }),
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const { snapshot } = await getTalkingHeadProject(ctx.cwd, params.projectId, params.revision);
+			if (params.need.outputEndMs > snapshot.outputDurationMs) {
+				throw new Error(`B-roll need ${params.need.id} exceeds output duration ${snapshot.outputDurationMs}ms`);
+			}
+			const match = await matchWorkspaceBrollAssets(ctx.cwd, {
+				assetDirectory: params.assetDirectory,
+				...(params.recursive === undefined ? {} : { recursive: params.recursive }),
+				...(params.maxFiles === undefined ? {} : { maxFiles: params.maxFiles }),
+				...(params.maxEntries === undefined ? {} : { maxEntries: params.maxEntries }),
+				...(params.maxDepth === undefined ? {} : { maxDepth: params.maxDepth }),
+				...(params.maxCandidates === undefined ? {} : { maxCandidates: params.maxCandidates }),
+				...(params.candidateOffset === undefined ? {} : { candidateOffset: params.candidateOffset }),
+				need: params.need,
+				...(signal === undefined ? {} : { signal }),
+			});
+			return result({
+				projectId: params.projectId,
+				revision: snapshot.revision,
+				match,
+				...(match.truncated ? { warning: `The bounded scan stopped after ${match.scannedEntryCount} entries and ${match.scannedFileCount} video filenames; filename-direct is disabled until the asset directory is narrowed or fully scanned.` } : {}),
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "talking_head_broll_select",
+		label: "Select B-roll source window",
+		description: "Validate one exact B-roll source window against a pi-media contact_sheet_manifest.json. Verifies the selected asset hash, analyzed range, and manifest-backed evidence timestamps, then returns a placement ready for talking_head_apply.",
+		parameters: Type.Object({
+			projectId: stableId,
+			revision: Type.Optional(Type.Integer({ minimum: 1 })),
+			need: brollNeed,
+			assetPath: Type.String({ minLength: 1 }),
+			manifestPath: Type.String({ minLength: 1 }),
+			selectedStartMs: Type.Number({ minimum: 0 }),
+			evidenceTimestampsMs: Type.Array(Type.Number({ minimum: 0 }), { minItems: 1, maxItems: 100 }),
+			fit: Type.Union([Type.Literal("cover"), Type.Literal("contain")]),
+		}, { additionalProperties: false }),
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const { snapshot } = await getTalkingHeadProject(ctx.cwd, params.projectId, params.revision);
+			if (params.need.outputEndMs > snapshot.outputDurationMs) {
+				throw new Error(`B-roll need ${params.need.id} exceeds output duration ${snapshot.outputDurationMs}ms`);
+			}
+			return result({
+				projectId: params.projectId,
+				revision: snapshot.revision,
+				selection: await selectBrollWindow(ctx.cwd, {
+					...params,
+					...(signal === undefined ? {} : { signal }),
+				}),
+			});
+		},
+	});
+
 	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. 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; brief A-roll flashes, unplanned ranges, and overlapping B-roll are rejected. Returns a generic pi-media timeline operation ready for edit_apply.",
 		parameters: Type.Object({
 			projectId: stableId,
 			expectedRevision: Type.Integer({ minimum: 1 }),
-			aroll: Type.Array(arrollSegment, { minItems: 1, maxItems: 1_000 }),
+			aroll: Type.Array(arollSegment, { minItems: 1, maxItems: 1_000 }),
 			broll: Type.Array(brollPlacement, { maxItems: 500 }),
+			continuityPlanReceipt: Type.Optional(continuityPlanReceipt),
 		}, { additionalProperties: false }),
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			const current = await getTalkingHeadProject(ctx.cwd, params.projectId);
-			const snapshot = await applyTimeline(ctx.cwd, params);
+			const snapshot = await applyTimeline(ctx.cwd, params, signal);
 			return result({
 				projectId: params.projectId,
 				snapshot,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclip/pi-talking-head",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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; propose a conservative cut strategy, optionally place justified B-roll, 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, 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: $@
 
 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,8 +12,17 @@ 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. Call `talking_head_apply` using exact word-boundary A-roll ranges. Every B-roll window must have a concrete visual purpose in `reason`; keep `audio: keep-primary`.
-7. 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`.
+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.
+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`.
+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

@@ -19,6 +19,11 @@
 
 - Place B-roll on the output timeline after A-roll cuts have stabilized.
 - Use it to show the object, action, place, comparison, or evidence currently being discussed—not as random decoration.
+- Treat a filename match as asset-level evidence, never as proof that a particular source window is usable. Inspect continuous motion before selecting `assetStartMs`.
+- 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.
+- 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.
 - 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.