# BK399 Video Quality Closure - Implementation Plan (R1) ## Scope Make a final video review fail closed when it has no usable audio, omits an explicit creative treatment contract, or is audited with an incomplete media probe. The existing renderer remains delegated; this lane does not create media, publish, or alter an existing approved film. ## Design Decision Introduce a renderer-neutral final-audit record and validate it through `sdtk-marketing video project audit --file `. The record binds a rendered file SHA, complete technical/video readings, audio readings, declared silence, and a creative-plan summary. A valid audit is required before a project can move to `REVIEW_READY`; an owner decision remains the only way to reach `FILM_ACCEPTED`. The package will ship a reference `ffmpeg` audit script for operators. It is an optional delegate for measurement, not a hidden package dependency: the command fails closed when the supplied audit is missing required readings. ## Ordered Tasks | # | Task | Modules | Verification | Rollback / containment | |---|---|---|---|---| | 1 | Add failing unit tests for final audit validation: usable audio, loudness, silence, complete motion probe, and creative declarations. | `scripts/video-project.test.js` | Targeted test fails for each new rule. | Tests only; no runtime change. | | 2 | Extend the project data model with a `creative` artifact and final-audit schema. Require shot-level `motion_treatment`, `product_on_screen`, and `text_only`; require a project-level audio plan. | `src/lib/video-project.js`, fixtures | Targeted tests pass; legacy project behavior remains valid before final audit. | Schema is additive; projects without an audit remain `DRAFT`. | | 3 | Add final-audit validation and persistence command. Enforce one usable audio stream unless `intentional_silence` is owner-declared; enforce LUFS, true-peak, and silence budget; reject absent MAFD/frozen/edge/luma readings. | `src/commands/video-project.js`, `src/lib/store.js` | CLI tests cover pass, silent AAC, missing stream, out-of-range loudness, undeclared silence, and missing probe field. | Audit is written only after validation; failed input records nothing. | | 4 | Upgrade storyboard diagnostics so final planning treats missing treatment declarations and repeated adjacent treatment/transition classes as errors; retain advisory diagnostics for non-final exploration. | `src/lib/video-diagnostics.js`, command tests | JSON result differentiates error vs advisory; legitimate non-final diagnostics remain usable. | Only final audit consumes blocking diagnostics. | | 5 | Ship an operator reference audit script plus documented JSON contract and runbook. The script reports stream counts, LUFS, true peak, silence intervals, video probe values, and SHA without secret input. | `scripts/reference-video-audit.sh`, docs, package files | Run against deterministic good/bad local fixtures; inspect no secrets are emitted. | Operators may use another compatible probe command. | | 6 | Integrate `video project render --stage final` with a declared audit command/result, so a completed render is not reported review-ready until the final audit passes. | `src/commands/video-project.js`, tests | Final render dry-run shows audit step; failing audit does not advance or record review state. | `animatic` and `rough` remain unblocked by final-only audit. | | 7 | Run package suite, CLI smoke tests, documentation review, and a focused code review. | all changed modules | Fresh test and shell evidence. | No npm publish, deployment, or Episode 1 rerender in this lane. | ## Critical Paths | Path | Expected result | |---|---| | Happy | Complete creative plan + compatible final audit -> audit persists -> project becomes `REVIEW_READY` -> owner may record review. | | Missing | Missing audio/motion/creative field or missing final-audit file -> command fails; no state change. | | Intentional silence | Only valid when audio plan explicitly declares it and owner reference is present; no accidental silent film passes. | | Error | Invalid JSON, wrong project ID, SHA mismatch, bad media metric, or delegate failure -> no audit/publish/review record. | ## Acceptance Criteria - A silent AAC MP4 with a nominal audio stream fails. - A video with no audio stream fails unless a declared owner-approved intentional-silence contract exists. - Audio must have integrated loudness in `-18..-14 LUFS`, true peak at or below `-1 dBTP`, and no undeclared silence longer than `1.5s`. - A final audit missing `median_mafd`, `frozen_ratio`, `edge_density`, or `luma` fails instead of being reported as skipped. - Each final storyboard shot has `motion_treatment`, `product_on_screen`, and `text_only`; adjacent treatment/transition repetition is visible and blocking under final audit. - `FILM_ACCEPTED` remains an explicit owner-only review decision. - Existing 0.11.0 campaign, asset, and social tests remain green. ## Assumptions | # | Assumption | Verified | Risk if wrong | |---|---|---|---| | A1 | `ffmpeg`/`ffprobe` are present where the operator invokes the reference audit script. | Yes, on this box. | Medium | | A2 | The current delegate model may accept an external JSON audit rather than hard-wiring a media runtime into Node. | Yes, current rendering/probing is delegated. | Low | | A3 | `-18..-14 LUFS` fits English caption-led product films with music/SFX and no voice. | No; proposed policy. | Medium | | A4 | Existing video projects can remain `DRAFT` until a new final audit is explicitly added. | Yes, finite project states already include `DRAFT` and `REVIEW_READY`. | Low | ## Out of Scope - Re-rendering or altering Episode 1. - Voiceover generation, music/SFX procurement, publishing, deployment, or npm release. - Claiming automated creative quality; owner picture lock remains required. ## Verification Checklist - [ ] New regression tests first fail for every new fail-closed rule. - [ ] Targeted and full `npm test` pass. - [ ] CLI smoke validates a good audit and rejects a silent/partial audit. - [ ] Reference audit script has a documented, secret-free output contract. - [ ] `git diff --check` and focused code review pass.