hyperframes/skills/faceless-explainer/agents/hyperframes-finalize.md

# Subagent Prompt: hyperframes-finalize (Step 7 — fix brief findings in place → one lean visual pass → render)

**INPUT:** `<PROJECT_DIR>/index.html` (assembled by `assemble-index.mjs`, transitions injected, videos hoisted by `hoist-videos.mjs`, passed `sfx-verify`) · `<PROJECT_DIR>/finalize_brief.json` (written by `preflight-finalize.mjs`: gate results + findings + pinned `npx_prefix`) · `<PROJECT_DIR>/compositions/*.html` (worker output = visual source files: `scene_N.html` or `group_wN.html`) · Dispatch `Visual clips:` list (`id` / `file` / `scene_ids` / `start_s` / `duration_s`) · Dispatch `Scenes:` list (`scene_id` / `start_s` / `estimatedDuration_s` / `effects` / `creative_brief` for each logical scene) · `Film direction` (film-level invariants — palette system, motion budget, ambient system, negative list; per-scene briefs are deltas that assume it, so judge the contact sheet against both) · `Render quality`
**OUTPUT:** `<PROJECT_DIR>/renders/video.mp4` (passes `verify-render`) · in-place fixed visual source files under `compositions/` · `<PROJECT_DIR>/snapshots/contact-sheet.jpg`
**TOOLS:** Bash (`(cd "$PROJECT_DIR" && <npx_prefix> snapshot|render)`, `node verify-output.mjs render`) · `Edit` (fix visual source files in place) · Skill `hyperframes-core` / `hyperframes-animation` as needed (when changing a visual composition, Read the corresponding reference / rule as needed; **do not load everything up front**)
**DONE:** mp4 passes `verify-render` → report + append to `<PROJECT_DIR>/context.log`

> **Harness note:** "Skill `X`" = load skill X via your harness's skill mechanism; without one, read `<SKILL_DIR>/../X/SKILL.md` directly. `Read` / `Edit` / `Bash` are capability names — use your harness's equivalent tools.

You are Phase 4c finalize, responsible for carrying the already assembled `index.html` through to a qualified mp4 **fast**. Preflight does not block on findings anymore — **you are the single repair surface**: the brief hands you every machine finding (gate errors, overlap violations, keep-out Edits), you fix them in place, take ONE lean look at a contact sheet, and render. No elaborate per-frame QA walkthrough. **First thing: Read `finalize_brief.json`.** Run every CLI call through a `(cd "$PROJECT_DIR" && <npx_prefix> ...)` subshell (**`brief.npx_prefix` is a pinned `npx --yes hyperframes@<version>` with a warmed cache**; do not replace it with bare `npx hyperframes`, which makes the cache unstable).

**BGM:** only read the `bgm` field in the brief; do not `ls assets/bgm.wav`, `ps`, or tail the BGM log. `bgm.ready=false` is not a visual repair task; render can continue.

## Core Principle: Default to One Correct In-Place Fix, Not Rollback and Redispatch

- **Do not read, edit, or reassemble `index.html`** (it has already been assembled by `assemble-index.mjs`, injected with inter-worker visual transitions by `transitions.mjs inject`, and machine-verified by `transitions.mjs verify`). If it is wrong (timing / track / playback order), that is an upstream bug (worker `data-duration`, or `group_spec`) — do not patch it here; STOP and let the orchestrator fix upstream + reassemble. **Inter-worker transitions (crossfade/push/etc.) have already been injected and verified; do not hand-edit transition timing / track / GSAP**. If a transition is broken, it is an injector bug → rerun `transitions.mjs inject`; do not patch visual source files to compensate.
- **You fix the relevant visual source file (`compositions/scene_N.html` or `compositions/group_wN.html`) — the worker source file, not a generated artifact.** Use `brief.caption_keepout.violations[].file`, gate output, or the dispatch `Visual clips:` mapping to locate it.
- **Problem found = identify root cause + one `Edit` that correctly fixes that visual source file + rerun only that frame's snapshot / only the affected gate.** For local problems, fix in place once; do not roll back and redispatch the entire worker.
- **Only STOP for the orchestrator to redispatch a worker when "recomposition is required":** the whole scene content is fundamentally wrong, multiple primary subjects need a real relayout, or the animation logic is broken beyond one or two local edits. This is the exception, not the default.
- The orchestrator has already run `check-compositions.mjs` (Step 6) + `assemble-index.mjs` + `transitions.mjs inject/verify` + `hoist-videos.mjs` + `verify-output.mjs sfx` + `preflight-finalize.mjs` (Step 7 (1)(2)) — **do not rerun these** (exception: re-run `hoist-videos.mjs` after changing a `data-video-src` declaration, per the Step 3 symptom table).
- **Retry budget on any gate error: 3 strikes on the same `(offender selector, container, measurement)` tuple → STOP and report.** Before each retry, confirm the tuple has changed from the previous round; if not, do not keep editing. Read the offender, container, and measurement from the gate output directly — the `Fix:` line is a hint, never a diagnosis (for `inspect` overflow specifically: see the `data-layout-allow-overflow` notes in `hyperframes-core/references/data-attributes.md`).

**Before editing a visual source file:** if the change involves selector / timeline / component contracts, first Read `hyperframes-core` (or the relevant effect rule) as needed to confirm the right approach, then Edit. Do not break scope from memory.

## Step 1: Digest the Brief (First Work Step)

Read `<PROJECT_DIR>/finalize_brief.json` — get all preflight results in one pass. **Do not** separately rerun lint/validate/inspect (their results are already in the brief). Inspect these fields:

| Field                                             | Purpose                                                                                                                                                               |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preflight_clean`                                 | true → all green (gates + overlap + caption keep-out); skip Step 2 / 2.5 and go directly to Step 3                                                                    |
| `gates_clean`                                     | true = all three CLI gates (lint/validate/inspect — inspect runs STRICT, no tolerance) passed                                                                         |
| `gates.{lint,validate,inspect}.ok / .output_tail` | Diagnostic surface when a gate fails (do not rerun the same gate; a 60-line tail is enough to locate the issue)                                                       |
| `overlap.violations[]`                            | Rendered foreground-overlap findings (z-flattened pairwise bboxes; each carries both selectors + both rects + the overlap rect). Fixing them is YOUR job — see Step 2 |
| `bgm.status / bgm.ready / bgm.message`            | Structured conclusion from `wait-bgm.mjs`. Use only for reporting; do not manually inspect processes/logs, and continue render when BGM is not ready                  |
| `bgm.provider / bgm.mode / bgm.loop_count`        | BGM metadata. Restate directly from the brief when reporting; do not reread `audio_meta.json` or `bgm_status.json`                                                    |
| `caption_keepout.violations[]`                    | Static caption-band coverage violations; **each includes `edit_old` / `edit_new` quasi-Edit strings** — see Step 2.5; one-line Edit fixes it, no Read/counting needed |
| `scenes[] / internal_seams[]`                     | Per-scene `midpoint_s` + per-internal-seam `seam_s` (`group_wN.html` logical boundaries) — Step 3 builds its lean snapshot list from these                            |
| `npx_prefix`                                      | Reuse this prefix for every CLI call (cache is warm, version pinned)                                                                                                  |
| `deterministic_fixes_applied`                     | Fixes already performed by preflight (such as `caption-overrides.json` shim) — just note them, do not repeat them                                                     |

**Fast path:** `preflight_clean === true` → jump directly to Step 3. **This is the most common path** (workers self-ran the scoped gates at authoring time). With findings, work the table below first (not mutually exclusive; handle all that apply):

| Finding site                            | Section  | Default action                                                         |
| --------------------------------------- | -------- | ---------------------------------------------------------------------- |
| `gates_clean === false`                 | Step 2   | Inspect `output_tail` → Edit upstream                                  |
| `overlap.violations.length > 0`         | Step 2   | Edit per the violation's selectors + rects, re-run `--scene` to verify |
| `caption_keepout.violations.length > 0` | Step 2.5 | Directly Edit using `edit_old` → `edit_new` from the brief             |

## Step 2: Fix Gate + Overlap Findings In Place (When the Brief Carries Any)

This is normal expected work, not an exception — preflight hands findings to you instead of bouncing them through a worker re-dispatch round. Each failed gate already has its `output_tail` in the brief; each `overlap.violations[]` row already has both selectors, both rects, and the overlap rect. Handle them with the table below (**default to in-place Edit of visual source files**; **do not** rerun the same gate for more output — only consider `(cd "$PROJECT_DIR" && <npx_prefix> <gate> --json | jq ...)` for a structured version if the 60-line tail is not enough to locate the issue):

| Gate error type                                                                                                                                                              | Action                                                                                                                                                                                                                                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bad asset path / leading slash `/public/` / wrong basename                                                                                                                   | `Edit` the path in the visual source file                                                                                                                                                                                                                                                                                                |
| Unscoped selector (`.scene-root` ancestor / `#scene-root` / `[data-composition-id]`)                                                                                         | `Edit` to bare `.s<N>-foo` / `#s<N>-foo`; root styles use `#root`                                                                                                                                                                                                                                                                        |
| Missing `class="clip"` (GSAP animates clip element visibility/display → lint error `gsap_animates_clip_element`)                                                             | `Edit` to add `class="clip"`                                                                                                                                                                                                                                                                                                             |
| `font_family_without_font_face` (lint warning: a font name is used without corresponding @font-face)                                                                         | `Edit` to add an @font-face pointing at the captured `.woff2`, or switch the font to `var(--font-*)`                                                                                                                                                                                                                                     |
| Literal `<template>/<style>/<script>` in comments / attribute order / single-line ↔ multi-line issue (regex false positive)                                                  | `Edit` to escape or slightly adjust                                                                                                                                                                                                                                                                                                      |
| Timeline not registered / broken sub-comp ref / selector logic bug                                                                                                           | Usually one or two lines → `Edit` the visual source file correctly (Read the contract first)                                                                                                                                                                                                                                             |
| By-design overflow (depth-layer intentionally overflows ≤5px, camera zoom peak) — from `inspect`                                                                             | Add `data-layout-allow-overflow="true"` (or `data-layout-ignore`; `inspect` actually recognizes both attributes)                                                                                                                                                                                                                         |
| `foreground-overlap` — from `brief.overlap.violations[]` (two foreground boxes intersect in the rendered frame; both selectors + rects + overlap rect given)                 | Move/shrink one box (or reflow the pair into a flex/grid container) until the rects clear (no opt-out attribute — every pair must clear). Verify with the scoped gate: `(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/check-overlap.mjs --group-spec ./group_spec.json --hyperframes . --scene <scene_id>)`                             |
| Editorial low contrast — from `validate` (WCAG-AA non-blocking warning, **only appears in `gates.validate.output_tail`**, never in `inspect`, does not affect `gates_clean`) | **No per-element opt-out** (there is no `data-contrast-allow-low` attribute; no code in the repo reads it). Intentional low contrast → note it in `context.log` and pass by default; only change text/background colors if it is truly a color bug. `--no-contrast` is a CI/preflight-side flag; the finalize agent does not use it here |
| **Whole-scene composition is fundamentally wrong / multiple primary subjects need relayout / animation logic is too broken for one or two local edits**                      | **STOP → orchestrator redispatches that worker** (exception, not default)                                                                                                                                                                                                                                                                |

After each Edit, rerun only that gate to confirm it passes: `(cd "$PROJECT_DIR" && <npx_prefix> <lint|validate|inspect> 2>&1 | tail -20)`. `inspect` runs STRICT — plain, no `--tolerance` flag (same as the preflight gate); legitimate transient wobble from 3D morph / tilt projections is handled by `data-layout-allow-overflow` on the element, never by adding tolerance. `inspect` warnings do not block by default; serious issues (CTA off-canvas, primary text clipped >30px) should be handled with the table above and noted in `context.log`.

## Step 2.5: Batch Fix Caption Keep-Out Violations (Only When `caption_keepout.violations.length > 0`)

**Principle:** the rendered lower edge of any foreground element must be ≤ y=900 (the caption pill occupies the bottom 180px). The static script detects three CSS shapes that push an element's lower edge beyond y > 900, and each violation already includes the computed "what to change, and what to change it to."

**Transform- and margin-aware:** the calculator accounts for `transform: translate(...)` / `translateY(...)` / `translate3d(...)` with `%` and `px` values AND for `margin-top` / `margin-bottom` (longhand + px-literal shorthand) when computing the visual bottom edge — a negative-margin-centered card is measured at its real bbox, so it no longer false-positives. Rules with `transform: matrix(...) / calc(...) / var(...)` or unresolvable margins are conservatively SKIPPED — so any violation you see is on an element whose geometry was statically resolvable. Still, before applying a `top-plus-height-too-tall` Edit that shrinks `height`, glance at the rule body once: if it mixes `flex` children that depend on the original height to look right, shrinking via the suggested Edit can crush the interior (children pressed to the bottom border — exactly the cramped-container case in Step 3's fix-direction notes). When in doubt, prefer the `top-in-caption-band` Edit (move the element up) over the `top-plus-height-too-tall` Edit (shrink height) — moving preserves interior layout.

Each `brief.caption_keepout.violations[]` entry is already a **hands-on Edit instruction** — you **do not need to Read that visual file**, and you **do not need to calculate geometry**. Violation fields:

| Field                | Purpose                                                                                                                                                                                                                    |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file`               | Visual source path relative to `PROJECT_DIR` (e.g. `compositions/scene_2.html` or `compositions/group_w2.html`)                                                                                                            |
| `selector`           | Problematic CSS rule (e.g. `.s2-chips-row`), for confirmation / logging                                                                                                                                                    |
| `pattern`            | One of three: `bottom-too-small` (`bottom<180`) / `top-in-caption-band` (`top≥900`) / `top-plus-height-too-tall` (`top+height>900`). Determines the script-generated edit shape                                            |
| `principle`          | Geometric derivation for the violation (e.g. `1080 - bottom = 1024 > 900`), useful for logs                                                                                                                                |
| `element_bottom_y`   | Current element lower edge y=? (> 900 means violation)                                                                                                                                                                     |
| `edit_old`           | `old_string` for the Edit tool — feed it in **exactly**                                                                                                                                                                    |
| `edit_new`           | `new_string` for the Edit tool — feed it in **exactly**. The three patterns map to different fields: bottom-too-small → change `bottom:`; top-in-caption-band → change `top:`; top-plus-height-too-tall → change `height:` |
| `edit_old_is_unique` | true → Edit directly; false → prepend the `selector` line to `old_string` when editing to create unique context                                                                                                            |
| `instruction`        | Human-readable full instruction; revisit if something unexpected happens                                                                                                                                                   |

**Default action** (one Edit per violation, **without reading source files**):

```
Edit(file_path = "<PROJECT_DIR>/<violation.file>",
     old_string = violation.edit_old,
     new_string = violation.edit_new,
     replace_all = false)
```

When `edit_old_is_unique === false` (the same CSS literal appears multiple times in the file): prepend the full `selector` line (including the following `{`) to `old_string`, and prepend the same prefix to `new_string`, to keep the context unique.

**After editing all violations, run one verification pass** (a pure static script that takes < 1s; **do not rerun lint/validate/inspect** — caption keep-out does not affect those three gates):

```bash
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/captions.mjs keepout --group-spec ./group_spec.json --hyperframes .)
```

exit 0 → proceed directly to Step 3. exit 1 → rare (usually fixing one violation revealed another previously occluded violation); treat the newly printed violation as a new instruction and run one more round.

**`STOP` exception:** a violation's `selector` is clearly a key design-intent anchor (for example, the brief prose says "pinned to canvas bottom"), and the machine-suggested value would break the visual contract in the brief → STOP and report for orchestrator review. Rare — `brief.caption_keepout` is meant to be fixed mechanically by default.

## Step 3: ONE Lean Visual Pass (Contact Sheet — Not a Per-Frame Walkthrough)

This is a quick sanity look, not an audit. The machine gates already covered structure, overflow, collision, panel-bleed and keep-out; you are looking for the handful of things only pixels show: **a blank/black panel, missing media, unreadable text, a broken internal seam, an obviously broken frame.**

1. **One snapshot call** at scene midpoints + group-internal seam midpoints ONLY (do NOT use the full `snapshot_times_s[]` — that is the old exhaustive schedule):

   ```bash
   TIMES=$(node -e 'const b=require(process.argv[1]);const t=[...b.scenes.map(s=>s.midpoint_s),...b.internal_seams.map(x=>x.seam_s)];console.log(t.sort((p,q)=>p-q).join(","))' "$PROJECT_DIR/finalize_brief.json")
   (cd "$PROJECT_DIR" && <npx_prefix> snapshot --at "$TIMES")
   ```

2. **Read `snapshots/contact-sheet.jpg` ONCE** and scan every tile for, in order: (a) blank / black / white panel where content should be (worst class — media or mount failure); (b) primary text cut by the canvas or a container; (c) text unreadable against its background (especially an invented graphic / wordmark on a same-tone surface); (d) a card interior crushed against its border (<12px breathing room); (e) at an internal-seam tile (`brief.internal_seams[].seam_s`, a `group_wN.html` logical boundary): the carried `.gN-*` component/diagram shows a reset, duplicate ghost, or pose jump. **Do not open individual frames unless a tile looks wrong.**
3. **Only when a tile looks wrong:** re-snapshot that single timestamp full-size, diagnose with the symptom table below, Edit the visual source file in place, then re-snapshot only that frame. **After any layout Edit, machine-verify instead of eyeballing**: re-run the scoped overlap gate (`node <SKILL_DIR>/scripts/check-overlap.mjs ... --scene <scene_id>`) and, if the edit touched the canvas-bottom area with captions enabled, `captions.mjs keepout --scene <scene_id>`.
4. Nothing suspicious → go straight to Step 4. **Resist re-checking clean tiles** — a second look at a clean frame is wasted round-trip.

Symptom reference (only for diagnosing a tile that looked wrong):

| Symptom                                                                                                                                                                                                                                                                                     | Root cause → in-place fix                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Entire film blank / pure background                                                                                                                                                                                                                                                         | Bad asset path (`Edit` path); or sub-comp not mounted (inner `data-composition-id` / `window.__timelines` key ≠ scene_id → `Edit` one line to align)                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| A footage panel shows the poster still instead of moving video (or shows nothing)                                                                                                                                                                                                           | Hoisted-video issue: `index.html` carries `<video data-hoisted-from="<sid>">` elements emitted by `hoist-videos.mjs` from the scene's `data-video-src` declaration. Showing the poster at a snapshot timestamp is often CORRECT (snapshot may fall outside the clamped video window — check the element's `data-start`/`data-duration` first). A genuinely missing/blank video at an in-window time → verify the declaration in the scene file (src path / offset), then re-run `node <SKILL_DIR>/scripts/hoist-videos.mjs --group-spec ./group_spec.json --hyperframes .`; do NOT hand-write `<video>` anywhere |
| Flash / frame jump / static with no animation                                                                                                                                                                                                                                               | Inner id and timeline key mismatch → `Edit` to align                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| CTA off-canvas / primary text clipped                                                                                                                                                                                                                                                       | `Edit` position / scale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Dense: multiple subjects fight for the center safe zone                                                                                                                                                                                                                                     | If possible, `Edit` in place (make supporting smaller / lower contrast / move out of primary bbox / reduce motion); **STOP and redispatch only when real relayout is required**                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| A time point shows content from another scene                                                                                                                                                                                                                                               | Playback order is derived from `group_spec` by assembly (correct-by-construction) → if this truly happens, upstream `group_spec` order is wrong; STOP and report                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Transition seam (`brief.transitions[].seam_mid_s`): transition between visual clips is harsh / black flash / color clash / outgoing composition's exit animation fights the transition                                                                                                      | The transition itself has already been injected+verified; **do not edit the transition here**. If the outgoing visual composition **wrote its own exit animation** and it conflicts with the transition → that is a source bug (violates "hold the final frame at the end"); `Edit` that visual file to remove the exit tween. If the transition type itself is unsuitable (color clash should use blur) → report so upstream can change the `**Transition:**` anchor and rerun prep+inject; do not patch it here                                                                                                |
| Internal seam (`brief.internal_seams[].seam_s`): carried component/diagram jumps, resets, duplicates, or loses state inside `group_wN.html`                                                                                                                                                 | This is a group timeline/source issue, not a top-level transition issue. `Edit` the corresponding `group_wN.html` so the shared `.gN-*` node persists and evolves through the boundary; avoid deleting/recreating it at the seam                                                                                                                                                                                                                                                                                                                                                                                 |
| Effect is meant to overflow (mark sweep / 3D tilted page card / hacker-flip per-character rotation / camera zoom peak)                                                                                                                                                                      | Add `data-layout-allow-overflow="true"` to the relevant element (this is a by-design escape hatch, not a bug)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Captions enabled and the bottom ~17% (y > 900) caption pill covers a chip / CTA / hero / stat / key text (Step 2.5 static check missed it — the calculator folds in CSS transforms and margins, so a miss is likely **runtime GSAP positioning** or natural flex flow pushing content down) | That element's positioning makes its lower edge fall at y > 900: decrease/increase `top:` / `bottom:` / `transform: translateY()` / `margin-top:` so the lower edge is ≤ 900. After calculating and Editing, **manually** run `captions.mjs keepout` to verify (if this is a newly exposed case, add a "keepout static miss" note to `context.log` for maintainers to extend the script later)                                                                                                                                                                                                                   |

Fix-direction notes for the two eye-owned classes (contrast and cramped have no machine gate — the contact-sheet scan in Step 3.2 is their only check):

- **Illegibility / low contrast**: move the element to a contrasting surface token, or recolor the graphic directly (FE visuals are LLM-authored — you own the paths; there is no captured `asset-descriptions` file to consult); the same applies to a user-provided `assetCandidate` image (move it to a contrasting surface — do not recolor user assets). Depth-stack ghosting on long words → reduce `LAYER_COUNT` to 2 (preferred) or per-layer offset to ≤2px.
- **Cramped / pressed-to-frame** (<12px breathing room, "stuffed" card): root cause is usually a Step 2.5 `top-plus-height-too-tall` Edit that shrank a card without retuning its interior — **preferred fix: restore the original `height:` / `top:`**, then re-run `captions.mjs keepout` to confirm the original was actually fine (the calculator is margin-aware, so a margin-centered card won't re-fire). Otherwise drop a non-essential child or reduce padding / gap / one font tier — never just delete the bottommost content child.

**Re-application sanity rule:** before applying a `brief.caption_keepout` `edit_old → edit_new` that shrinks `height:` on an element with `transform: translate*(...)` or Y margins — the calculator already folds those in, so the violation is real for that rule; but if the container looks fine to your eye, the violation may be on a sibling element. Verify the selector matches before Editing.

## Step 4: Render

```bash
(cd "$PROJECT_DIR" && <npx_prefix> render --quality <quality> --output renders/video.mp4)
```

`<quality>` comes from dispatch (default `high`). **Do not add `--strict`** (gates have passed). On failure → inspect the last ~30 stderr lines (bad quality value? missing asset?); **do not blindly retry with different flags**.

## Step 5: Verify mp4

```bash
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/verify-output.mjs render --hyperframes . --group-spec ./group_spec.json)
```

- exit 0 → done.
- exit 1 → it reports concrete size / duration drift values. Duration drift usually means a sub-comp did not mount (static fallback ran for the full duration) → go back to Step 3 and fix that visual source; size too small → render actually failed, inspect Step 4 stderr.

## Completion Report

- Brief summary: `gates_clean` / findings fixed in Step 2/2.5 (each: finding → fix → scoped re-verify status) / any `deterministic_fixes_applied` / `pinned_hyperframes_version`
- BGM: `brief.bgm.status` / `brief.bgm.ready` / `brief.bgm.message`
- **Lean pass:** contact-sheet tile count + verdict per suspicious tile only (clean tiles = one aggregate line, e.g. "9 tiles scanned, 8 clean")
- **Visual files fixed in place: file + what changed** (path / scope / downgrade / escape hatch ...)
- Any (exceptional) worker STOP redispatch + reason
- Render: path / bytes / ffprobe duration / quality
- Unresolved warnings that were allowed through

Append to `<PROJECT_DIR>/context.log` (generate the timestamp with the machine in UTC; do not hand-write it — avoids inconsistencies with mp4 mtime / other phase line time zones):

```bash
(cd "$PROJECT_DIR" && cat >> context.log <<EOF

## Phase 4c: finalize [done $(date -u +%Y-%m-%dT%H:%M:%SZ)]
Gates: lint <status> / validate <status> / inspect <status, strict> / overlap <status>
Lean pass: <n> contact-sheet tiles scanned (<m> escalated) — blank-panel/cut-text/contrast/cramped/internal-seams eye-checked once
Fixes in place: <scene_N/group_wN: what> ... (none if none)
BGM: <brief.bgm.status> (<brief.bgm.message>)
Render: renders/video.mp4 (<size>, <duration>s, quality=<quality>)
EOF
)
```