From cbb24bd034f2dbb9dfc88d658dd248c25fda47e6 Mon Sep 17 00:00:00 2001
From: cxw <cxw1987@gmail.com>
Date: Wed, 12 Aug 2026 01:43:26 +0800
Subject: [PATCH] =?UTF-8?q?docs(skills):=20plan/assemble=20craft=20?=
 =?UTF-8?q?=E2=80=94=20validator-true=20prose,=20the=20signature-safe=20en?=
 =?UTF-8?q?velope,=20and=20coverage=20as=20QA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sync of the plan/edit/assemble refinements from Orkas release_1.6.5
(9378b315a, e2a2797f3, 33904ce59, f9cd7a16d, 13c145d6a, 3b9451d78,
fb1cd2991, 8a94dc1c0 context), prompt-only, re-mapped onto the ovs
pack:

- stage-plan: edit_strategy is four non-empty string ARRAYS at the plan
  top level with a closed decision-signal set (the validator already
  enforced E_EDIT_STRATEGY_BOUNDARY/E_EDIT_STRATEGY_SIGNAL; the prose
  never said so); target_sec is a DURATION and windows must not overlap
  (E_NARRATION_WINDOWS_OVERLAP, landed in #15); a temporal anchor signs
  the consumed interval; flagged risks resolve at the Production plan
  confirmation (both stray "direction confirmation" pointers fixed);
  full-frame overlays are a plan-shape problem (the guard landed in
  #14); silent beats are reserved, not speech budget; Gate B is two
  turns — present the validator's own summary verbatim, never twice,
  and "an unapproved plan after the user answered means you owe the
  transition, not another confirmation".
- stage-edit: the array-shape rule with its error code; may_change must
  name every authorized change class; delivery locators move into the
  reserved `_runtime` envelope — the old instruction to write top-level
  `draft`/`video` keys invalidated the Gate B signature on success,
  because unknown top-level plan fields are approval-bearing by
  gate-control's own rule (approval.ts reserves `_runtime`/`_catalog`).
- stage-assemble: the real trim flags (`--start/--end/--out`); only
  compose segments need frame evidence (media segments are captured by
  their produced_path); the overlay-opaque refusal is a re-plan, not a
  retry; the coverage report is QA — coverageRatio only says how far
  the LAST line reached, a half-silent track can still score 0.95;
  never speed up speech or pad with filler; skip a caption line that
  repeats visible on-screen copy; delivery QA holds every route to the
  same bar, including hand-written ffmpeg; `_runtime` write-back rule.
- orchestration: the plan.json record points at `_runtime.render.*`
  instead of a top-level `draft` key; narration fit revises OVER only.

Verified: full OVS_E2E=1 suite 275/276; content tests pin the error
codes, the envelope rule, the 0.95 trap, and the two-turn Gate B.

Prompt audit: every added clause states behavior the code actually has
(validator codes from #15, the overlay guard from #14, the reserved
envelope in approval.ts) or fixes prose that contradicted it (top-level
draft/video keys, "direction confirmation" pointers, over/under fit);
no clause duplicates gate-control authorization or #19's checkpoint
craft; the trim command was verified against the CLI definition.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VL7mRpmEphLAbcH7YmABnV
---
 packages/skills/orchestration/SKILL.md      |  4 ++--
 packages/skills/stage-assemble/SKILL.md     | 14 +++++++-----
 packages/skills/stage-edit/SKILL.md         |  4 ++--
 packages/skills/stage-plan/SKILL.md         | 16 ++++++-------
 packages/skills/test/skills-content.test.ts | 25 +++++++++++++++++++++
 5 files changed, 45 insertions(+), 18 deletions(-)

diff --git a/packages/skills/orchestration/SKILL.md b/packages/skills/orchestration/SKILL.md
index 51dd74c..ce4d669 100644
--- a/packages/skills/orchestration/SKILL.md
+++ b/packages/skills/orchestration/SKILL.md
@@ -45,7 +45,7 @@ For COMPOSE or AUTO compose segments, also apply `frontend-design` before writin
 
 ## 2.6 Narration voice
 
-When the piece has voiceover, run `ovs speech-capabilities` and copy its executable route/model/voice/format into the Gate B plan together with the BCP-47 video language and a natural speed. Do not invent a voice id. Before Gate B, run `ovs narration fit --text ... --target ...`; revise over/under text internally before any paid synthesis. After `ovs speak`, probe the produced audio and run the same fit with `--measured`; retime scenes from the measured duration without silently shortening the approved target. If no TTS provider is configured, tell the user and explicitly choose silent delivery or wait for configuration.
+When the piece has voiceover, run `ovs speech-capabilities` and copy its executable route/model/voice/format into the Gate B plan together with the BCP-47 video language and a natural speed. Do not invent a voice id. Before Gate B, run `ovs narration fit --text ... --target ...`; revise OVER-budget text internally before any paid synthesis — a read that finishes early is an accepted delivery, so pad or extend only when the trailing silence is not the ending you intended. After `ovs speak`, probe the produced audio and run the same fit with `--measured`; retime scenes from the measured duration without silently shortening the approved target. If no TTS provider is configured, tell the user and explicitly choose silent delivery or wait for configuration.
 
 TALKING-HEAD note: if a GENERATE clip already returned lip-synced built-in speech, THAT is the voice — do NOT synthesize a narration over it (a fresh TTS track desyncs from the mouth). Use `ovs speak` only for a silent clip, or for COMPOSE / EDIT / off-screen voiceover.
 
@@ -92,7 +92,7 @@ Ingest every supplied clip from evidence (probe + transcribe/OCR-or-frame-readin
 
 ## plan.json as the editable record (all lines) — keep follow-up edits cheap
 
-Once a draft exists, keep `project/plan.json` faithful so a later tweak only re-touches one piece (never the whole video): (1) every produced segment carries its real output under `produced_path` + `status:"done"`; (2) narration is `tracks.narration` whose lines each carry their own `produced_path`, so one line can be re-voiced alone; (3) captions are DATA in `tracks.captions.lines` ({text, start_sec, target_sec}) — NOT burned into the picture — so a typo is a one-line edit re-burned at assemble; (4) set top-level `"draft": "render/draft.mp4"`.
+Once a draft exists, keep `project/plan.json` faithful so a later tweak only re-touches one piece (never the whole video): (1) every produced segment carries its real output under `produced_path` + `status:"done"`; (2) narration is `tracks.narration` whose lines each carry their own `produced_path`, so one line can be re-voiced alone; (3) captions are DATA in `tracks.captions.lines` ({text, start_sec, target_sec}) — NOT burned into the picture — so a typo is a one-line edit re-burned at assemble; (4) record delivery outputs under the reserved `_runtime` envelope (`"_runtime": {"render": {"draft": "render/draft.mp4"}}`), never as a new top-level key — unknown top-level plan fields are approval-bearing, so a root `draft` key would invalidate the recorded Gate B approval.
 
 **Local follow-up edits — make the minimal targeted change; never redo the whole video.** Once a `plan.json` is present and the user asks to change ONE local thing (a segment's narration / caption / text, a trim, volume / speed, a single shot swap), edit ONLY the matching entry in `plan.json` and re-produce ONLY what it touched (`ovs speak` for that one line, `ovs draft` for that one compose segment, or `ovs edit` for that one cut), then re-assemble. Do NOT re-author the whole EDL and DO NOT regenerate a segment whose `status` is `done` that the user did not touch. Fall back to a full re-plan only when the request genuinely restructures the timeline.
 
diff --git a/packages/skills/stage-assemble/SKILL.md b/packages/skills/stage-assemble/SKILL.md
index e203010..832c532 100644
--- a/packages/skills/stage-assemble/SKILL.md
+++ b/packages/skills/stage-assemble/SKILL.md
@@ -11,22 +11,24 @@ How to execute a validated `project/plan.json` into one finished file. By the ti
 
 Iterate segments in `order`. For each, produce its `produced_path` according to `source`, then write that path + `status:"done"` back into the segment so a resume never re-produces it:
 
-- **edit** → `stage-edit`: `ovs edit trim` the `input_id` to `[in_sec, out_sec]` → `project/cuts/<id>.mp4`.
+- **edit** → `stage-edit`: `ovs edit trim` the `input_id` to `[in_sec, out_sec]` → `project/cuts/<id>.mp4`. Those are the EDL's field names, not flags — the command is `ovs edit trim <input> --start <in_sec> --end <out_sec> --out project/cuts/<id>.mp4`.
 - **compose** → `stage-compose`: build a small visual-only manifest-owned composition for `spec.kind` (title card, lower-third, stat card, captions) under `project/compositions/<id>/` → run `ovs draft project/compositions/<id> --out project/parts/<id>.mp4 --quality draft --report project/reports/<id>-compose-report.json`. This keeps compose segments on the same manifest/source/check/video-QA path as standalone COMPOSE while still letting the assembler own narration and loudness.
 - **generate** → `stage-generate` (+ `stage-consistency` for recurring characters): only AFTER gate C. `ovs video`/`ovs image` → `project/assets/<id>.mp4`. For `operation:"edit"`, pass the exact original reference video and obey top-level `references` plus `edit_strategy`; never widen it into regeneration. A failed/unknown paid attempt is not an automatic retry. Preserve completed siblings and require a new output path for any later authorized attempt.
 - **provided** → use `spec.asset_id` as-is (probe it first; conform aspect/fps if needed).
 
 Billable `generate` segments must not run before gate C has confirmed the count from `cost_estimate`. Produce cheap/free segments (edit, compose, provided) freely.
 
+Only `compose` segments need snapshot/frame QA evidence, because their artifact is HTML. An `edit`/`generate`/`provided` segment is captured by its own `produced_path` file the moment that file exists — never run a composition QA phase on one, and never treat it as unfinished work because it has no frame evidence.
+
 ## Step 2 — Assemble in ffmpeg tiers (the default path)
 
 Assemble deterministically, bottom-up. This tiered order is the default; it is predictable and cheap, and keeps each clip's real audio intact:
 
 1. **Primary track** — `ovs edit concat` the primary-layer `produced_path`s in `order` → `project/render/primary.mp4`. Conform aspect/fps on the way in if sources differ.
-2. **Overlays / bg** — for each overlay/bg segment, `ovs edit overlay` its part onto the primary over the window of the segment named in `over` (title cards, lower-thirds, logos). Composed layers are VISUAL-ONLY — they must not carry their own narration audio. **This includes a compose segment that IS the primary track (a full-video composition): render it SILENT — do not put a narration `<audio>` in its `index.html`. The assembler owns narration (tier 3), so a composition that bakes it in would mean narration is added TWICE (the "two voices" defect).**
-3. **Narration — added EXACTLY ONCE, here.** If active, require the Gate-B-signed `tracks.narration.synthesis` profile. Run `ovs narration fit` for each timed line before `ovs speak`; shorten over-budget text in the plan without changing the approved meaning. Synthesize with the exact signed voice/model/format/speed, probe the result, rerun measured fit, and write each line's `produced_path`. If measured timing misses, revise once using the suggested unit budget rather than repeatedly billing or forcing speed. Add all produced lines in ONE `ovs edit mix` call at their `start_sec`. The default existing-audio rejection catches compose segments that accidentally baked narration; re-render those SILENT. Check coverage, and disclose any intentional silent tail at Gate D. Preserve a generated talking head's built-in lip-synced audio instead of adding a second voice.
+2. **Overlays / bg** — for each overlay/bg segment, `ovs edit overlay` its part onto the primary over the window of the segment named in `over` (lower-thirds, logo boxes). An overlay must be SMALLER than the frame: composed parts render as opaque video with no alpha channel, and `ovs edit overlay` refuses a full-frame opaque layer because it would replace the footage under it, not composite over it. That refusal is a plan-shape problem, not a retry — never work around it with re-encoding, resizing tricks, or a hand-written ffmpeg graph; re-plan the beat as a composed `primary` segment with no footage underneath. Composed layers are VISUAL-ONLY — they must not carry their own narration audio. **This includes a compose segment that IS the primary track (a full-video composition): render it SILENT — do not put a narration `<audio>` in its `index.html`. The assembler owns narration (tier 3), so a composition that bakes it in would mean narration is added TWICE (the "two voices" defect).**
+3. **Narration — added EXACTLY ONCE, here.** If active, require the Gate-B-signed `tracks.narration.synthesis` profile. Run `ovs narration fit` for each timed line before `ovs speak`; shorten over-budget text in the plan without changing the approved meaning. Synthesize with the exact signed voice/model/format/speed, probe the result, rerun measured fit, and write each line's `produced_path`. If measured timing misses, revise once using the suggested unit budget rather than repeatedly billing or forcing speed. Add all produced lines in ONE `ovs edit mix` call at their `start_sec`. The default existing-audio rejection catches compose segments that accidentally baked narration; re-render those SILENT. READ the coverage report as QA, not decoration: `coverageRatio` only says how far the LAST line reached — a half-silent track can still score 0.95 on it. Judge `voicedRatio` and `interiorGaps` for dead air, and treat `overlapped` as broken audio (two lines speaking at once). Never raise the speech speed to fit and never pad the script with filler words; re-time the lines inside their windows, shorten over-long beats, or add the planned music bed. Disclose any intentional silent tail at Gate D. Preserve a generated talking head's built-in lip-synced audio instead of adding a second voice.
 4. **Music** — add `tracks.music` ducked under narration by the planned amount.
-5. **Captions** — turn `tracks.captions.lines` (`{text, start_sec, target_sec}`) into a `.srt`, then `ovs edit burnsubs`. Captions are DATA in the plan — burned ONLY here at assemble — so a later typo fix is a one-line edit re-burned, never a re-render of the picture. If `burnsubs` fails because the runtime ffmpeg lacks subtitle filter support, stop and report that blocker; do not hand-write a fallback ffmpeg graph, PNG subtitle overlay, or drawtext pipeline.
+5. **Captions** — turn `tracks.captions.lines` (`{text, start_sec, target_sec}`) into a `.srt`, then `ovs edit burnsubs`. Captions are DATA in the plan — burned ONLY here at assemble — so a later typo fix is a one-line edit re-burned, never a re-render of the picture. Skip a caption line whose text merely repeats that scene's visible on-screen copy — burning the same sentence twice on one frame reads as a defect. If `burnsubs` fails because the runtime ffmpeg lacks subtitle filter support, stop and report that blocker; do not hand-write a fallback ffmpeg graph, PNG subtitle overlay, or drawtext pipeline.
 6. **Loudness** — run `ovs edit normalize-loudness project/render/draft.mp4 --out project/render/video.mp4`. It normalizes to the `video-craft` §7 targets (~−14 LUFS integrated, true-peak ≤ ~−1 dBTP) and returns measured loudness; use `ovs edit loudness` only for diagnosis without writing an output.
 
 Apply the plan's `style_kit` for cohesion: composed layers (titles/captions/cards) use its `palette` + `fonts`. A single `lut` graded across all clips is what unifies tonally mixed sources — until a grade op is available, keep mixed sources close at capture/trim and lean on the shared palette + consistent captions for cohesion rather than promising a uniform grade.
@@ -52,7 +54,7 @@ For a partial child failure or later revision, reset only the affected child and
 
 ## Step 4 — QA report, then gate D
 
-Before showing the draft, run the QA pass and write `project/render_report.json` with these sections:
+Before showing the draft, run the QA pass and write `project/render_report.json`. It judges the delivered ARTIFACT against the approved plan — length, canvas, narration placement measured from real speech, loudness, declared captions — so every route to the file meets the same bar, including a hand-written ffmpeg assembly. Sections:
 
 - **technical_probe** — `ovs edit probe` the draft/final (real duration / resolution / fps / audio present); confirm it matches the plan's aspect + total.
 - **promise_preservation** — `ovs plan promise-check project/plan.json --probe-produced`. At gate D this probes each primary segment's `produced_path` and computes the REAL primary-track motion ratio vs. `motion_min_ratio` plus the `source_required` invariant; missing/unreadable produced media or a fail means **"slideshow / promise broken" — do not deliver**. Send it back (below). Do not eyeball this; let the numbers decide.
@@ -77,7 +79,7 @@ Bound repetition, not recovery: allow at most **2** send-back rounds for the sam
 ## Rules
 
 - Walk the approved plan; if assembly reveals the plan is wrong, surface it and re-gate — do not silently re-plan.
-- Write `produced_path` + `status` back per segment as you go (resumability + the QA pass depend on it).
+- Write `produced_path` + `status` back per segment as you go (resumability + the QA pass depend on it), and record delivery outputs under the reserved `_runtime` envelope (`_runtime.render.draft` / `_runtime.render.final_path`), never as new top-level plan keys — unknown top-level fields are approval-bearing and would invalidate the Gate B signature. Skipping the write-back is what makes an already-delivered video look never-started on resume.
 - One output file is the deliverable; `cuts/` and `parts/` are intermediates.
 - **Narration is added exactly ONCE — in the mix tier, never baked into a compose render.** Compose segments (including a full-video composition used as the primary track) render SILENT (no narration `<audio>`); the assembler mixes narration via `ovs edit mix` with `segments` placed per line. The mix's default `--on-existing-audio reject` enforces this — a "base already has audio" mix rejection is the signal a segment wrongly baked audio in; re-render it silent, then re-mix.
 - **No ad-hoc ffmpeg fallbacks for captions.** Caption burn-in is a low-freedom operation owned by `ovs edit burnsubs`; a failed burnsubs call is a tool/runtime blocker, not permission to invent a custom subtitles/drawtext/PNG-overlay command.
diff --git a/packages/skills/stage-edit/SKILL.md b/packages/skills/stage-edit/SKILL.md
index 0e10531..b2cd07e 100644
--- a/packages/skills/stage-edit/SKILL.md
+++ b/packages/skills/stage-edit/SKILL.md
@@ -18,7 +18,7 @@ How to intelligently edit **real user-supplied footage** while keeping source an
 
 ## Intelligent Edit Contract
 
-Write `project/plan.json#edit_strategy` whenever OVS decides what to change rather than merely executing user-provided timecodes. Declare its `mode` (`deterministic`, `semantic`, or `mixed`), exact objectives, only the evidence signals actually used, and non-empty, non-overlapping `preserve`/`may_change`.
+Write `project/plan.json#edit_strategy` whenever OVS decides what to change rather than merely executing user-provided timecodes. Declare its `mode` (`deterministic`, `semantic`, or `mixed`), exact objectives, only the evidence signals actually used, and non-empty, non-overlapping `preserve`/`may_change`. All four list fields are non-empty ARRAYS of strings — one entry per item, never a single sentence; `objectives` is the one most often written as prose, and the validator rejects a bare string with `E_EDIT_STRATEGY_BOUNDARY`. `may_change` must name every class of change the user authorized: omitting one silently narrows the plan's declared authority below what they asked for.
 
 Declare every source/reference in top-level `references` with media type, reproduce/edit/guide intent and basis, roles, required state, preservation boundary, target segments, and video temporal anchors. A semantic video edit is `source:"generate"`, `media_kind:"video"`, `operation:"edit"` with its original in `reference_video_paths` or `reference_video_urls`; it remains owned by EDIT and counts as billable.
 
@@ -65,7 +65,7 @@ When the user wants highlights / clips "about X" or a localized version, transcr
    - `delivery_promise:{ type:"source_led", source_required:true }`; set `aspect` from the SOURCE's real probed dimensions (a landscape source is `16:9`, not the portrait default).
    Each narration line stays its own entry, so a later edit can re-voice ONE line without touching the rest.
 3. **Generate each beat FROM the plan, then record its `produced_path`.** Run `ovs narration fit --text ... --target ...` before TTS and shorten until it fits naturally. Run `ovs speak` per line, save the audio under `project/assets/narration/line-XX.*`, probe the measured duration, then run `ovs narration fit --measured ...` and retime/shorten any miss before writing `produced_path`. Never speed up past the approved natural profile or let a line run long/short. Coverage must span ~0→clip-end, not stop at the halfway mark.
-4. **Assemble with `ovs edit` — keep the picture untouched.** Place the narration lines at their `start_sec` in ONE `ovs edit mix` call via `segments` JSON (one entry per line — that is HOW per-line `start_sec` alignment happens), then use `ovs edit normalize-loudness` for the deliverable. Burn captions from `tracks.captions.lines` (.srt → `ovs edit burnsubs`) if present. The source footage usually already HAS audio, so `mix` rejects by default — choose `--on-existing-audio mix` to keep the original sound under the voiceover, or `--on-existing-audio replace` to drop it. Write each line's `produced_path` + `status` and the top-level `draft` / `video` paths back to plan.json so the record matches the result. Never pre-bake one big narration file — that destroys per-line separability.
+4. **Assemble with `ovs edit` — keep the picture untouched.** Place the narration lines at their `start_sec` in ONE `ovs edit mix` call via `segments` JSON (one entry per line — that is HOW per-line `start_sec` alignment happens), then use `ovs edit normalize-loudness` for the deliverable. Burn captions from `tracks.captions.lines` (.srt → `ovs edit burnsubs`) if present. The source footage usually already HAS audio, so `mix` rejects by default — choose `--on-existing-audio mix` to keep the original sound under the voiceover, or `--on-existing-audio replace` to drop it. Write each line's `produced_path` + `status` back to plan.json, and record the delivery under the reserved `_runtime` envelope (`"_runtime": {"render": {"draft": "render/draft.mp4", "final_path": "render/video.mp4"}}`) — never as new TOP-LEVEL keys: unknown top-level fields are approval-bearing, so a root `draft`/`video` key invalidates the Gate B signature the moment the render lands. `_runtime` and `produced_path` are runtime locators excluded from the signed plan identity. Never pre-bake one big narration file — that destroys per-line separability.
 5. **Self-check before presenting:** `project/plan.json` validates (`ovs plan validate project/plan.json`); every narration line has a `produced_path` and a window matching its OCR/transcript/frame-read text; mix returned a coverage report with no surprising uncovered tail or overshoot; `project/render/video.mp4` exists. Then tell the user the draft is ready and they can ask for follow-up tweaks (re-voice a line, fix a caption) and you'll change only that.
 
 When the clip has NO spoken audio, or its meaning lives in ON-SCREEN TEXT (a screen-recording, a slideshow, a captioned montage), transcription returns nothing — the content is in the pixels, not the audio. An empty audio track does NOT mean an empty screen. Read what is on screen instead of guessing, in this strict order (cost-first):
diff --git a/packages/skills/stage-plan/SKILL.md b/packages/skills/stage-plan/SKILL.md
index 04239dd..2ba7bc9 100644
--- a/packages/skills/stage-plan/SKILL.md
+++ b/packages/skills/stage-plan/SKILL.md
@@ -21,7 +21,7 @@ You cannot plan against material you have not looked at. For EVERY supplied clip
 3. Record what each input is good for in `project/ingest.json`: `{input_id, duration, has_audio, content_summary, quality_risks:[...], usable_for:[...], planning_implications:[...]}`. This is the factual basis the plan cites — segments reference `input_id`s from here. Rules:
    - **`content_summary` is specific and from observation:** "45 s of interview, no b-roll, mono audio" — never "user provided footage". An entry is only "reviewed" if a real probe/transcript/OCR actually ran; never claim you looked at a clip you did not.
    - **Usability heuristics:** video > 10 s → hero footage; > 3 s → b-roll; has speech → dialogue source; audio-only → narration/music source, production must supply the visuals; image-only → motion must come from animation or generation.
-   - **Quality risks to flag:** width < 720 / height < 480 (will look soft), clip < 3 s (limited use), mono audio, a still where the brief wants motion. A flagged risk the plan ignores is a planning bug — resolve it during direction confirmation.
+   - **Quality risks to flag:** width < 720 / height < 480 (will look soft), clip < 3 s (limited use), mono audio, a still where the brief wants motion. A flagged risk the plan ignores is a planning bug — surface and resolve it at the Production plan confirmation.
 
 For every supplied image/video that constrains the result, lock its requested relationship as `reproduce`, `edit`, or `guide`. Record roles, protected attributes, allowed changes, and target segments. Video reproduction/editing or motion/timing guidance requires source-time-to-target-segment anchors.
 
@@ -34,23 +34,23 @@ Pick ONE `delivery_promise.type` and make the whole plan keep it:
 - **compose_led** — designed HTML is the spine (explainer / data); footage/generation are accents.
 - **hybrid** — a deliberate mix (e.g. source hero + composed framing + generated opener).
 
-Set `motion_min_ratio` to the minimum share of runtime that must be real footage/generated motion rather than composed HTML. For `compose_led`, use exactly `0`; HTML animation quality is enforced by composition motion QA instead of this source-mix ratio. If you cannot hit a nonzero promise from the available material, say so during direction confirmation instead of quietly shipping a slideshow. If `source_required` is true, at least one PRIMARY segment must be real footage (`source: edit | provided`) and the supplied footage must play in the rendered timeline, not merely appear as a still reference frame.
+Set `motion_min_ratio` to the minimum share of runtime that must be real footage/generated motion rather than composed HTML. For `compose_led`, use exactly `0`; HTML animation quality is enforced by composition motion QA instead of this source-mix ratio. If you cannot hit a nonzero promise from the available material, say so at the Production plan confirmation instead of quietly shipping a slideshow. If `source_required` is true, at least one PRIMARY segment must be real footage (`source: edit | provided`) and the supplied footage must play in the rendered timeline, not merely appear as a still reference frame.
 
 ## Step 3 — Decompose into a cross-modal EDL
 
 Write `project/plan.json`. Every segment declares HOW it is produced (`source`) and WHERE it sits (`layer`):
 
 - `source`: **edit** (trim a real clip — needs `input_id` + `in_sec`/`out_sec`), **generate** (needs `prompt` + explicit `media_kind`; billable; video also signs `generation_duration_sec`, `ratio`, `resolution`, `generate_audio`, and any `reference_image_urls`; for recurring subjects also set `characters`, `refs`, and `variation_type`), **compose** (designed HTML — needs a `kind`), **provided** (needs `asset_id` and explicit `kind: video|image`; still images never count as real motion/source footage).
-- `layer`: **primary** (the main timeline), **overlay** (sits over a primary via `over: <segment id>` — captions, lower-thirds, title cards), **bg** (behind).
+- `layer`: **primary** (the main timeline), **overlay** (sits over a primary via `over: <segment id>` — captions, lower-thirds, logo boxes), **bg** (behind). An overlay composited onto real footage must be SMALLER than the frame: composed overlays render as opaque video without an alpha channel, so a full-frame overlay replaces every pixel and deletes the footage under it — `ovs edit overlay` refuses that. Keep overlays to edge elements, or make the full-frame beat a composed `primary` segment with no footage underneath.
 - `role`: MUST be exactly one of hook / body / proof / cta / transition — the schema rejects any other value (`E_SEG_ROLE`) and the plan fails validation. Narrative BEAT names from the arc ("payoff", "establishing", "climax", ...) are NOT roles: map a payoff / closing / CTA beat to `cta`, an establishing / evidence beat to `proof`. Front-load the hook.
 
-Top-level `references` is mandatory for every edit/provided source and generation reference. Each entry uses `{id,media_type,source,intent,intent_basis,roles,required,preserve,may_change,target_segment_ids,temporal_anchors?}`. Omit the field when no references exist; never emit an empty array. Roles are exactly `content|identity|composition|structure|style|motion|timing|audio`. User requirements win; otherwise `guide`/`inferred` is safe. Preserve and may-change must not overlap.
+Top-level `references` is mandatory for every edit/provided source and generation reference. Each entry uses `{id,media_type,source,intent,intent_basis,roles,required,preserve,may_change,target_segment_ids,temporal_anchors?}`. Omit the field when no references exist; never emit an empty array. Roles are exactly `content|identity|composition|structure|style|motion|timing|audio`. User requirements win; otherwise `guide`/`inferred` is safe. Preserve and may-change must not overlap. A temporal anchor signs the CONSUMED interval: a bounded 3s-7s child signs 3-7, while a full-duration edit of a 12s source signs 0-12; `may_change` separately limits the actual pixel change.
 
-When OVS intelligently selects or transforms content, add `edit_strategy` with `{mode,objectives,decision_signals,preserve,may_change}`. Use `deterministic` for evidence-driven cuts, `semantic` for AI pixel edits, and `mixed` for both. A semantic video edit stays an EDIT/AUTO workflow but is a billable `source:"generate"` video segment with `operation:"edit"` and at least one declared original in `reference_video_paths` or `reference_video_urls`. It requires `semantic_model`, a matching top-level edit reference and temporal anchor, and inclusion in the paid-generation count.
+When OVS intelligently selects or transforms content, add `edit_strategy` with `{mode,objectives,decision_signals,preserve,may_change}` at the plan TOP LEVEL, as a sibling of `segments` — never inside a segment. `mode` is a string and the other four are non-empty string ARRAYS, one entry per item: a bare sentence in `objectives` is rejected as `E_EDIT_STRATEGY_BOUNDARY`, and `decision_signals` is a closed set the validator names on rejection (`E_EDIT_STRATEGY_SIGNAL`), never free-text findings. Use `deterministic` for evidence-driven cuts, `semantic` for AI pixel edits, and `mixed` for both. A semantic video edit stays an EDIT/AUTO workflow but is a billable `source:"generate"` video segment with `operation:"edit"` and at least one declared original in `reference_video_paths` or `reference_video_urls`. It requires `semantic_model`, a matching top-level edit reference and temporal anchor, and inclusion in the paid-generation count.
 
-`tracks` is required even when the project has no audio or captions; use `{}` for the empty case. Tracks are separate from the visual timeline. For narration, run `ovs speech-capabilities` and sign its executable route/model/voice/format together with the BCP-47 video language and speed under `tracks.narration.synthesis`; raw `voice` is legacy recovery only. Timed lines are `{text,start_sec,target_sec}` and each receives a `produced_path`. Music is path + ducking. Captions stay editable DATA under `tracks.captions.lines`. Put the exact number of generate segments in `cost_estimate.billable_generations`; a mismatch is a validation error because paid-generation confirmation reviews that count.
+`tracks` is required even when the project has no audio or captions; use `{}` for the empty case. Tracks are separate from the visual timeline. For narration, run `ovs speech-capabilities` and sign its executable route/model/voice/format together with the BCP-47 video language and speed under `tracks.narration.synthesis`; raw `voice` is legacy recovery only. Timed lines are `{text,start_sec,target_sec}` and each receives a `produced_path`. `target_sec` is the line's DURATION, never its end time, and windows must not overlap — the validator rejects `E_NARRATION_WINDOWS_OVERLAP`, because overlapping windows mix as two voices speaking at once. Music is path + ducking. Captions stay editable DATA under `tracks.captions.lines`. Put the exact number of generate segments in `cost_estimate.billable_generations`; a mismatch is a validation error because paid-generation confirmation reviews that count.
 
-Fit narration in the plan before any TTS call: use natural cadence (about 2.2-2.7 English words/sec or 4-5 Chinese chars/sec), shorten over-budget lines here, and do not rely on repeated synthesis to discover timing.
+Fit narration in the plan before any TTS call: use natural cadence (about 2.2-2.7 English words/sec or 4-5 Chinese chars/sec), shorten over-budget lines here, and do not rely on repeated synthesis to discover timing. Reserve explicitly silent opening/ending beats at their designed length and fit speech to the remaining time — silent windows are not speech budget. When measured speech plus reserved silence exceeds the target, prefer letting the timeline grow over truncating speech or dropping a silent beat; after one automatic timing revision, stop and give the user the real choices (revise again, or proceed keeping the complete current audio).
 
 **Author plan.json in EXACTLY this shape (copy the field names — `ovs plan validate` rejects any other shape):**
 
@@ -101,7 +101,7 @@ Plan to the craft bar (`video-craft`): a hook in the first seconds, one idea per
 
 1. `ovs plan validate` on `project/plan.json`. Fix EVERY error before going further — errors mean the plan cannot be executed or it breaks its own promise (e.g. `source_required` but no source segment). Reconsider warnings.
 2. `ovs plan promise-check` on the PLAN, before producing anything. It computes the planned motion ratio vs. the promise — a fail means the plan is already a slideshow / breaks its promise. Fixing the plan now is free; re-assembling later is not. Rebalance durations or convert a static beat to footage until it passes (gate D re-checks against the real cut).
-3. `ovs plan summarize` → present that timeline for **production plan confirmation**, including the exact narrator and generation settings. After the user's reply, run `ovs gate transition`; do not infer approval or request it again for an unchanged already-approved plan.
+3. A passing `ovs plan validate` already returns the plan summary — present that host-rendered summary VERBATIM in the user's language for **production plan confirmation** (a locked-facts line plus the per-segment timeline with its copy is the minimum; never a hand-written abstract), including the exact narrator and generation settings, invite changes in one line, and end the turn. Gate B is two turns, not a state to re-check: in the NEXT turn the user's reply is the decision — run `ovs gate transition`. Never present the same plan's summary twice, and never ask for approval of a plan you have not shown; an unapproved plan after the user already answered means you owe the transition, not another confirmation.
 
 ## Director judgment (end-to-end planning)
 
diff --git a/packages/skills/test/skills-content.test.ts b/packages/skills/test/skills-content.test.ts
index 3fc4ad9..ed901e6 100644
--- a/packages/skills/test/skills-content.test.ts
+++ b/packages/skills/test/skills-content.test.ts
@@ -170,4 +170,29 @@ describe('skill pack content', () => {
     expect(plan).toContain('`edit_strategy`');
     expect(plan).toContain('Top-level `references`');
   });
+
+  it('keeps the plan/assemble contracts aligned with the validator and the signature envelope', () => {
+    const plan = skill('stage-plan');
+    const edit = skill('stage-edit');
+    const assemble = skill('stage-assemble');
+    const orchestration = skill('orchestration');
+    // The prose states what the validator actually enforces.
+    expect(plan).toContain('E_EDIT_STRATEGY_BOUNDARY');
+    expect(plan).toContain('E_NARRATION_WINDOWS_OVERLAP');
+    expect(plan).toContain("DURATION, never its end time");
+    expect(edit).toContain('E_EDIT_STRATEGY_BOUNDARY');
+    // Delivery locators live in the reserved envelope, not new top-level keys.
+    for (const body of [edit, assemble, orchestration]) {
+      expect(body).toContain('_runtime');
+    }
+    expect(edit).not.toContain('top-level `draft` / `video`');
+    // The coverage report is QA, and the trap is named.
+    expect(assemble).toContain('a half-silent track can still score 0.95');
+    expect(assemble).toContain('never pad the script with filler words');
+    // Full-frame opaque overlays are a plan-shape problem in both skills.
+    expect(plan).toContain('SMALLER than the frame');
+    expect(assemble).toContain('SMALLER than the frame');
+    // Gate B is two turns and the summary is the host's rendering.
+    expect(plan).toContain('owe the transition, not another confirmation');
+  });
 });