# BK399 Video Quality Closure R2 - Implementation Plan

## Scope

R2 closes the quality gaps found while producing BK399 Episode 1 before any
social publisher payload may be prepared. It remains renderer-neutral and does
not render, inspect media with an LLM, upload, publish, or change an accepted
film.

R2 adds four linked contracts:

1. `voiceover_music_sfx` for public product explainers. The plan must bind the
   voice file SHA-256, script, timing, and provenance and include at least one
   voiceover cue. Existing `music_and_sfx` and owner-declared
   `intentional_silence` remain valid for their explicit use cases.
2. A SHA-bound `visual-review.json`. It contains entry and representative
   frames for every storyboard shot, hashes each frame, and records an
   owner-attested checklist for product visibility, text/UI separation, safe
   area, frame fit, and mobile framing. The kit validates evidence and
   completeness; it deliberately does not claim to infer visual quality.
3. A SHA- and creative-plan-bound `quality-exception.json`. It may waive only
   `motion-gate-failed` for one exact render and must state an owner reference,
   reason, and single-render scope. Audio, content, probe, and visual-review
   failures are never waivable.
4. Publisher eligibility. `video social publish-prepare` must revalidate the
   current project, accepted-film bytes, final audit, visual review, and any
   exception before it writes a publisher payload. Copy source and candidate
   generation remain available before this final publication boundary.

## Design Decisions

| Decision | Choice | Rationale |
|---|---|---|
| Visual verification | SHA-bound owner review, not model vision | Generic renderer layouts do not expose reliable geometry. A model-derived pass would be non-deterministic and could falsely certify overlap or framing. |
| Voice policy | Explicit `voiceover_music_sfx` mode | Product explainers require narration by default without forcing narration onto every ambient brand film. |
| Quality waivers | Motion only, single render | R7 proved an owner may accept a walkthrough despite motion metrics. Missing audio, dark/empty content, or missing review evidence must remain fail-closed. |
| Publish boundary | `publish-prepare` and publish revalidation | The owner can develop and review social copy before the film is publishable; no upload-ready payload exists until all quality evidence is current. |

## Ordered Tasks

| # | Task | Modules | Verification | Rollback / containment |
|---|---|---|---|---|
| 1 | Add failing contract tests for voiceover, visual review, motion-only exception, and publisher eligibility. | `scripts/video-project.test.js`, `scripts/social-copy.test.js` | New assertions fail before source changes. | Tests only. |
| 2 | Extend validator and ledger schemas for visual review and quality exception. | `src/lib/video-project.js`, `src/lib/store.js` | Valid records pass; malformed paths, hashes, coverage, or exception scope fail. | Additive records; no existing ledger is migrated. |
| 3 | Add attended record commands and bind owner review to an audited, visually accepted render. | `src/commands/video-project.js` | Audit cannot advance without required evidence; review cannot accept a different SHA. | Failed validation writes no record. |
| 4 | Enforce voiceover evidence and motion exception policy in final audit validation. | `src/lib/video-project.js`, tests | Voiceover mode rejects missing source/script/timing/provenance/cue; exception cannot waive any non-motion rule. | Existing audio modes remain valid. |
| 5 | Make publisher prepare and publish revalidate eligibility. | `src/lib/social-copy.js`, `src/commands/video-social.js`, tests | Missing audit/review/exception binding blocks before a publisher record or adapter call. | Source/candidate/selection flows remain read-only and unblocked. |
| 6 | Document contracts and run full package tests plus focused CLI smoke. | `docs/VIDEO_PROJECT_WORKFLOW.md`, package tests | Test suite green; smoke shows blocked and allowed paths. | No npm publish, deploy, media render, or platform action. |

## Critical Paths

| Path | Expected result |
|---|---|
| Public explainer | Voiceover plan + complete audit + visual review + owner acceptance -> eligible for publisher prepare. |
| Ambient film | `music_and_sfx` remains valid, provided all other audit and visual requirements pass. |
| Motion exception | Exact render and creative SHA match; only media motion findings are waived; audit records exception binding. |
| Missing visual review | Final owner acceptance and publisher prepare fail closed. |
| Stale payload | Publisher prepare and publish revalidate current eligibility; no upload-ready payload is written on drift. |

## Assumptions

| # | Assumption | Verified | Risk if wrong |
|---|---|---|---|
| A1 | Publisher bridge is merged before R2 because R2 must hook `publish-prepare`. | Yes, R2 branch is based on the bridge commit. | Low |
| A2 | Operators can retain review frames at their recorded paths until the owner review is complete. | Yes, existing review workflow already retains local files. | Medium |
| A3 | Public product explainers are explicitly authored with `voiceover_music_sfx`; no automatic genre inference is needed. | Yes, this is a declared creative mode. | Low |

## Out Of Scope

- Modifying, re-rendering, auditing, or publishing Episode 1.
- Automatic visual analysis or LLM judgment of screenshots.
- Voice generation, audio procurement, deploy, npm release, or platform upload.

## Verification Checklist

- [x] New tests fail before production changes.
- [x] Voiceover contract rejects incomplete evidence.
- [x] Visual review requires two hashed frames per storyboard shot and a matching final render SHA.
- [x] Only a matching motion exception can permit a failed motion audit.
- [x] Accepted review and publisher prepare reject missing or stale audit/visual evidence.
- [x] `npm test`, focused CLI smoke, and `git diff --check` pass.