audit-visual

audit-visual — visual-only quality gate

Fresh-context agent. Receives ONLY the video frames (audio stripped). Checks what a VIEWER would see, ignoring what they'd hear.

How to run

python3 ${CLAUDE_PLUGIN_ROOT}/skills/audit-visual/scripts/check.py \
    --clip 20_DELIVER/v1/clip.mp4 \
    --project 10_WORK/clips/<Slug> \
    --out 10_WORK/audit_visual.json

ALWAYS pass --project (the clip's work dir) — it reads the real cut seams so the within-shot pan gate fires hard. Without it, seams are self-detected (loose) and panning only warns. Optional: --contact-sheet to generate a visual grid for manual review.

What it checks

1. CROP STABILITY — the authoritative check (background phase-correlation)

The defect a viewer sees is the CROP WINDOW jumping, not the subject moving. The crop is rigid: if it jumps, the static background moves with it. So the gate phase-correlates the static top band of the frame (top 22%) and reads the clip's REAL cut boundaries from the render pipeline (10_WORK/stages/cut/<hash>.meta.json via _shared/clip_meta.py) — same-angle jump cuts are content seams, never "tracking failures". Without metadata, seams are self-detected from frame-diff spikes.

• Within a shot: vertical crop step ≥1.2% of height, step-confirmed (neighbors stay shifted) = FAIL. Unconfirmed transients are reported, not failed.
• Across seams: the Y-axis must hold (Y-lock / global-Y). Background dY ≥1.5% across a cut = FAIL, ≥0.9% = WARN. X may legitimately re-center. (Known-good seams measure 0.0–0.08% dY; one accepted outlier at 0.73%.)
• Zoom exemption: punch-in zooms read as band motion but are intentional — a zoom is detected (left/right band halves move horizontally in opposite directions) and exempted, counted in zoom_moves_within_shots / zoom_seams.
• Horizontal PAN within a shot = FAIL (2026-06-12, Guest159 regression): >8% within-shot horizontal crop drift (when seams are known via --project, bg static) = the frame is FOLLOWING the subject instead of holding — the "terrible keyframe" defect. Fix = reframe with --lock-x (auto-on for the podcast preset). Small dx for true re-centering at a content cut is exempt; in self-detected (loose) mode it warns rather than fails.
• OVER-ZOOM = FAIL (2026-06-12): face AREA >20% of frame = head cropped / too tight. A chest-up podcast/talking-head reframe sits ~8-14% (measured: known-good L3 clips 7.9-8.2%; the over-zoom batch 20.7-23.5%). 16-20% = warn. Cause = applying source-intel's zoom (1.4-2.2) on already-chest-up footage; fix = --preset podcast (zoom 1.0) from the 4K master.
• Moving-content footage (handheld, b-roll) is detected via baseline band motion and the stability checks are skipped with a note rather than false-failing.