#!/usr/bin/env python3
"""plan_coherence.py — do the numbers in this plan actually agree with each other?

EVERY BUG THIS CHECKS FOR WAS FOUND BY A HUMAN WATCHING THE OUTPUT, hours after the
renders were paid for. They are all the same shape: two numbers that must match, that
nothing compared, in artifacts that each looked perfectly correct on their own.

  the film covered 26% of the song       a 32s window on a 112s track. Every gate green.
                                         "How long is the song and how many clips?"
  an 8s voice slice drove a 20s window   the windows were re-planned; the voice slices
                                         were cached by path and kept their old length.
                                         The last twelve seconds had nothing to sync to.
  a 12s library ceiling rejected 14s     index_library refuses clips longer than a
  clips                                  window. 12 was right at 8s windows. At 14s it
                                         rejects the film's OWN renders and the library
                                         comes back empty — hours after the last render.
  B-roll shorter than the cut            the assembler steps a pool clip's in-point and
                                         reserves 0.2s, so a lane that renders everything
                                         at one length cannot fill its own cuts.

None of these is subtle once stated. All of them are invisible while you are inside one
artifact at a time, which is exactly why the check belongs here — before spend, looking
at all of them at once.

Usage:
  plan_coherence.py --plan build/plan.json [--song <mp3|hook.wav>] [--broll <dir>]
                    [--vocal-map …] [--broll-plan …] [--vocal-brief …] [--json]

Checks 11-14 (2026-08-22): #11 every voice slice correlates >= 0.95 with the song at
its planned offset (a stale cached slice from an earlier plan does not); #12 the vocal
map and the brief mark the same windows shot-led; #13 a solo span in a `both` window
does not direct "their mouths"; #14 a no-voice window's prompt carries no rap/sing verb.
Check 15 (2026-09-01): a single-performer window carries no line in the OTHER voice —
a window that straddles the handover puts his face (and, under vocal-swap, his voice)
on her line.

Exit 0 coherent · 4 the numbers disagree · 2 unreadable input
"""
from __future__ import annotations

import argparse
import json
import os as _os, sys as _sys
_sys.path.insert(0, _os.path.dirname(_os.path.abspath(__file__)))   # a script loaded by path (tests) still finds its siblings
import raplib  # noqa: E402
import os
import re
import subprocess
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from make_plan import max_clip_for  # noqa: E402  (the route caps live there)
from check_sync import best_offset, envelope  # noqa: E402  (#11: is the slice THIS audio?)

FPS_TOLERANCE_S = 0.15     # a 14s request lands at 14.08s; that is the provider, not a bug
BROLL_MARGIN_S = 0.2       # emitBroll reserves 0.05s in + 0.15s tail
MIN_SONG_COVERAGE = 0.6
MIN_COVERABLE_S = 1.0      # mirrors cover_mouthing --min-cover: shorter is not a cutaway
MAX_SILENT_HEAD_S = 3.0    # a synced slice may open on at most this much silence
EDGE_INSET_S = 0.08          # skip the mute's own fade at each end (see slice_matches_window)
SLICE_MATCH_MIN = 0.95     # #11: a slice cut from THIS window correlates ~1.00 with the song
GAP_SECTION_MIN_S = 0.9    # #3: a hole this long is a B-roll section; shorter has no filler
TAIL_TRIM_TOL_S = 0.25     # #3: a plan may stop this far short of the hook (check_master: 6 frames)
MAX_PAD_S = 1.8            # #12: render minus sung, at most: 0.5 s head + 0.3 s tail + up to 1.0 s of
                           # make_plan's whole-second CEIL (roundingMode "ceil-with-margin"). 1.3 budgeted
                           # round-to-nearest, which the planner never did: a 9 s render for 7.66 s of
                           # singing (pad 1.34) was refused on film #3 (2026-09-03), and three bridge
                           # lines on film #2 were refused for the same half second and patched only
                           # for short lines. The gate now states the planner's own rule.


def plan_constants(plan: dict) -> dict:
    """The constants the plan was built with (make_plan.plan_constants). THE GATE NEVER
    READS THE ENVIRONMENT: it once did, and disagreed with the producer by the half
    second between round-up and round-to-nearest (2026-09-02). A plan from before this
    field is judged with make_plan's own defaults, and says so."""
    c = dict(plan.get("constants") or {})
    if not c:
        print("plan_coherence: the plan carries no constants (built before 2026-09-02) — judging "
              "with make_plan's defaults; re-run the plan stage to record them", file=sys.stderr)
    return {
        "shortLineRate": float(c.get("shortLineRate", 1.2)),
        "minSungS": float(c.get("minSungS", 6.0)),
        "minClip": float(c.get("minClip", 4.0)),
        "maxClip": (float(c["maxClip"]) if c.get("maxClip") is not None else None),
        "headPadS": float(c.get("headPadS", 0.5)),
        "tailPadS": float(c.get("tailPadS", 0.3)),
        "audioMode": str(c.get("audioMode") or "record"),
    }
MIN_PORTRAIT_PX = 500      # #13: identity reference width, at least


def image_width(path: str) -> int | None:
    """Pixel width of an image, or None when it cannot be read (an unreadable reference is
    #2's problem, not this check's)."""
    try:
        from PIL import Image
        with Image.open(path) as im:
            return int(im.size[0])
    except Exception:                     # noqa: BLE001
        return None
# #14: a no-voice window's prompt may not direct a performance. These phrases are the
# ones that SAY there is none — stripped before the verb search. "rap MV" is the
# genre label every prompt opens with ("A character rap MV set in…"), not a verb.
# THE PLURAL IS THE DUET'S FORM. make_plan writes "he does not sing" for a solo window
# and "they DO not sing" for a `both` one — and this list only knew the singular, so the
# very sentence that declares a silent window silent was what #14 refused. Every duet
# film's silent both-windows were unpassable (Baby Ram & Sita, 2026-08-31; New Era was
# solo and never hit it).
_NO_SING_PHRASES = re.compile(
    r"do(?:es)? not sing|do(?:es)? not rap|no singing|not singing|never mouth|"
    r"rap MV|rap music video", re.I)
_PERFORM_VERB = re.compile(r"\b(rap|raps|rapping|sing|sings|singing)\b", re.I)
_DIRECTION_RE = re.compile(r"only where words are sung: (.*?)\. Never mouth", re.S)
# "the male voice" / "the female voice", or a performer NAMED ("Veeru's voice") on a
# letter-tagged sheet (make_plan --performer-names)
_SOLO_VOICE_RE = re.compile(r"\b(?:the (?:male|female) voice|[A-Z][\w-]*'s voice)\b")



def seconds(path: str) -> float:
    r = subprocess.run(["ffprobe", "-v", "error", "-show_entries", "format=duration",
                        "-of", "csv=p=0", path], capture_output=True, text=True)
    try:
        return float(r.stdout.strip())
    except ValueError:
        return 0.0


def slice_matches_window(song: str, voice_ref: str, start: float, seconds: float,
                         mute_head: float = 0.0, mute_tail: float = 0.0) -> float:
    """#11: correlate the voice slice against the song AT ITS PLANNED OFFSET.

    A slice cut from this window correlates ~1.00; one left over from an earlier plan
    (the cache was keyed on path + duration, so a re-plan kept the old audio) reads
    near 0 — live proof: voice/w08.mp4 measured 1.00 at 94.5s and -0.04 at its planned
    81.84s. Every sync gate downstream then judged the render against the wrong bar."""
    # A slice whose head is deliberately silent (make_plan muteHeadSec — no vocal
    # before this face's first word) is compared from the first word on.
    m = max(0.0, float(mute_head or 0.0))
    end = float(mute_tail) if mute_tail and float(mute_tail) > m else seconds
    # DO NOT COMPARE THE MUTE'S OWN FADE. The slice is silenced outside this face's
    # words with a short ramp; the song has no such ramp, so the first and last frames
    # of the compared span disagree by construction. On a 4s span that dragged a
    # PERFECT slice to 0.9478 and refused the plan (baby-nimbooda w10, 2026-09-03) —
    # inset by 80ms and the same slice reads 1.0000. The check's power is untouched:
    # a slice cut from the wrong offset still reads ~0 in its interior, which is the
    # failure this exists to catch (w08 read 1.00 at its old 94.5s, -0.04 at its
    # planned 81.84s). A span too short to give the inset room is compared whole,
    # exactly as before.
    c, _ = slice_offset_against_window(song, voice_ref, start, seconds, mute_head, mute_tail)
    return c


def slice_offset_against_window(song: str, voice_ref: str, start: float, seconds: float,
                                mute_head: float = 0.0, mute_tail: float = 0.0) -> tuple[float, int]:
    """(correlation, offset in ms) for the slice against the song at its planned offset.

    THE ONE IMPLEMENTATION. preflight_higgs.slice_badge measured the same thing with
    its own copy of this arithmetic, so fixing the fade here left the contract page
    still warning "slice does not match the song" about a slice this file had just
    passed (baby-nimbooda w10, 2026-09-03). A second copy of a check drifts from it
    exactly the way a second route around one does.
    """
    m = max(0.0, float(mute_head or 0.0))
    end = float(mute_tail) if mute_tail and float(mute_tail) > m else float(seconds)
    span = end - m
    inset = EDGE_INSET_S if span > 4 * EDGE_INSET_S else 0.0
    return best_offset(envelope(song, max(0.0, float(start)) + m + inset, span - 2 * inset),
                       envelope(voice_ref, m + inset, span - 2 * inset))


def solo_span_says_their_mouths(prompt: str) -> list[str]:
    """#13: in a `both` window, a span sung by ONE voice must not direct BOTH mouths.

    Returns the offending spans. The direction is the per-window script make_plan
    writes between "only where words are sung:" and ". Never mouth"; spans are
    "; "-separated, and a span that names "the male voice"/"the female voice" is a
    solo — "their mouths shape" there tells the other performer to mouth a line that
    is not theirs."""
    m = _DIRECTION_RE.search(prompt)
    if not m:
        return []
    return [sp.strip() for sp in m.group(1).split(";")
            if _SOLO_VOICE_RE.search(sp) and "their mouths" in sp]


# #16: a sheet line the brief could not place, whose neighbours leave at least this much
# room for it, would render as a closed mouth (or B-roll) over singing. UNHEARD was a log
# line while 25 s of a film shipped that way (Baby Ram & Sita, 2026-09-01/02); the gate
# refused only holes SHORTER than 0.9 s — the bigger the gap, the surer it was you meant it.
UNHEARD_GAP_MIN_S = 3.0


def unheard_gaps(brief: dict) -> list[tuple[int, str, float, float]]:
    """Unplaced sheet lines with room for them: (index, text, gapStart, gapEnd) where the
    gap is from the previous placed line's end to the next placed line's start. Pure."""
    lines = brief.get("lines") or []
    out = []
    for i, ln in enumerate(lines):
        if ln.get("start") is not None or ln.get("adlib"):
            continue
        prev_end = max((float(l.get("end") or l["start"]) for l in lines[:i] if l.get("start") is not None), default=0.0)
        nxt = next((float(l["start"]) for l in lines[i + 1:] if l.get("start") is not None), None)
        if nxt is None:
            continue                    # past the last placed line: the outro, judged by the hook gate
        if nxt - prev_end >= UNHEARD_GAP_MIN_S:
            out.append((i, str(ln.get("text") or ""), round(prev_end, 2), round(nxt, 2)))
    return out


def silent_spans(spec: str) -> list[tuple[float, float]]:
    """SILENT_SPANS="A-B,C-D": film seconds the operator declares instrumental."""
    out = []
    for part in (spec or "").replace(";", ",").split(","):
        part = part.strip()
        if not part:
            continue
        a, _, b = part.partition("-")
        try:
            out.append((float(a), float(b)))
        except ValueError:
            continue
    return out


# #15: the other performer's line inside a single-performer window, at least this long.
# Shorter is the mute-edge fragment of a neighbour line (the slice is muted there).
FOREIGN_LINE_MIN_S = 1.0


def foreign_lines(plan: dict, job: dict) -> list[tuple[str, float, float, str]]:
    """#15: lines sung by the OTHER voice inside a performer-a or -b window that is
    itself a SUNG window, as (who, absStart, absEnd, text). One definition with the
    swap (vocal_swap.other_voice_lines). A window with no voice reference — make_plan's
    designed `otherVoice` shot, "lips closed, the voice on the track belongs to the other
    performer" — carries the other voice ON PURPOSE and is not a straddle (review
    finding, 2026-09-02). line_windows cuts a window at every change of voice;
    make_plan's short-line merge once rejoined the boy's 5 s line to the girl's line that
    followed it, and his face sang hers for 4.6 s (Baby Ram & Sita w04, 2026-09-01)."""
    if not job.get("voiceRef") or job.get("otherVoice") or job.get("synced") is False:
        return []
    from vocal_swap import other_voice_lines
    return [(other, a0, a1, text) for a0, a1, other, text in
            other_voice_lines(plan, job, min_s=FOREIGN_LINE_MIN_S, partials=False)]


def performance_verbs_in_silent_prompt(prompt: str) -> list[str]:
    """#14: a no-voice window's prompt must not tell the performer to rap or sing."""
    stripped = _NO_SING_PHRASES.sub(" ", prompt)
    return [m.group(0) for m in _PERFORM_VERB.finditer(stripped)]


def check(plan: dict, song: str | None, broll_dir: str | None,
          vocal_map: str | None = None, broll_plan: str | None = None,
          vocal_brief: str | None = None) -> list[str]:
    bad: list[str] = []
    # 16. AN UNHEARD LINE WITH ROOM FOR IT IS A REFUSAL, NOT A LOG LINE — checked before
    #     anything that needs jobs, so an empty or half-built plan still refuses.
    if vocal_brief and os.path.isfile(vocal_brief):
        declared = silent_spans(os.environ.get("SILENT_SPANS", ""))
        for idx, text, g0, g1 in unheard_gaps(json.load(open(vocal_brief, encoding="utf-8"))):
            if any(a <= g0 + 0.05 and b >= g1 - 0.05 for a, b in declared):
                continue
            bad.append(f"sheet line {idx} \"{text[:44]}\" was not heard, and the song has {g1 - g0:.1f} s "
                       f"({g0:.2f}-{g1:.2f}s) between the lines around it — a closed mouth or a cutaway "
                       f"would ship there over singing. Map with another ear (stem-words.json) or, if the "
                       f"song really is instrumental there, declare it: SILENT_SPANS=\"{g0:.2f}-{g1:.2f}\"")
    jobs = plan.get("jobs") or []
    if not jobs:
        return ["the plan has no jobs at all"]

    route = plan.get("route", "")
    # 18. A PLACED LINE SINGS UNDER A VOICE (film3 item 10). Every second of a placed
    #     line lies inside a window that carries a voice — or the other performer's by
    #     design (a listening face). A line in a hole, or under a no-voice window that is
    #     nobody's, is a face mouthing nothing or a cutaway carrying singing: the review
    #     built this and found 7 s on film #2's corrected plan before any render.
    if vocal_brief and os.path.isfile(vocal_brief):
        voiced = []
        for j in jobs:
            s0 = float(j.get("startSec") or 0) + float(j.get("trimStartSec") or 0)
            e0 = float(j.get("startSec") or 0) + float(j.get("seconds") or 0) - float(j.get("tailSec") or 0)
            if j.get("voiceRef") or j.get("otherVoice") or j.get("chantDance"):
                voiced.append((s0, e0))      # chantDance: the record sings over a dance shot, by design
        blines = (json.load(open(vocal_brief, encoding="utf-8")).get("lines") or [])
        for hit in raplib.singing_over_nothing(blines, voiced):
            bad.append(f"the line \u201c{hit['text'][:40]}\u201d sings {hit['start']:.1f}-{hit['end']:.1f}s but "
                       f"{hit['from']:.1f}-{hit['to']:.1f}s ({hit['seconds']:.1f}s) has no voiced window under it — "
                       f"a face would mouth nothing, or a cutaway would carry singing; re-run the plan stage "
                       f"(or place the line)")

    # 17. THE PLAN'S INPUTS HAVE NOT MOVED UNDER IT. The brief and the windows are iterated
    #     three times in one stage and nothing pinned the fixed point (review A4); a plan
    #     built from a brief that has since changed is a plan for another film.
    for name, rec in (plan.get("inputs") or {}).items():
        if rec.get("sha256") and os.path.isfile(rec.get("path", "")) and raplib.sha256_file(rec["path"]) != rec["sha256"]:
            bad.append(f"the {name} the plan was built from has changed since ({os.path.basename(rec['path'])}) "
                       f"— re-run the plan stage; a plan for the old {name} is a plan for another film")
    k = plan_constants(plan)
    cap = k["maxClip"] if k["maxClip"] else max_clip_for(route, synced=any(j.get("voiceRef") for j in jobs))

    # 12. THE RENDER IS AS LONG AS THE SINGING. A clip longer than its sung span comes
    #     back sung slower by that ratio (New Era, 2026-08-30: every window 1.24-2.27x
    #     padded, every window 1.24-1.8x slow; the one at 1.02 sang on speed). One second
    #     of slack is the most the whole-second round-up can honestly need.
    for j in jobs:
        if not j.get("voiceRef") or j.get("synced") is False or j.get("sungSec") is None:
            continue
        pad = float(j.get("seconds") or 0) - float(j["sungSec"])
        # A lone short line carries make_plan's stretch margin (SHORT_LINE_RATE) on purpose,
        # and make_plan rounds that render UP to a whole second (ceil), where MAX_PAD_S
        # budgets round-to-nearest: half a second more is the ceil's, not slack. Three
        # bridge lines (4.4 s, 4.7 s, 2.2 s sung) were refused for exactly that half second
        # (Baby Ram & Sita re-plan, 2026-09-02). A render at MIN_CLIP is the floor, not
        # padding: a 2 s line cannot render shorter than 4 s.
        allowed = MAX_PAD_S + (float(j["sungSec"]) * (k["shortLineRate"] - 1.0) + 0.5 if j.get("shortLineMargin") else 0.0)
        if float(j.get("seconds") or 0) <= k["minClip"] + 1e-6:
            allowed = max(allowed, k["minClip"] - float(j["sungSec"]))
        if pad > allowed + 1e-6:
            bad.append(f"{j['id']}: {float(j['seconds']):g}s render for {float(j['sungSec']):.2f}s of "
                       f"singing — {pad:.2f}s of padding (max {MAX_PAD_S:g}s); the model spreads the "
                       f"performance across the clip and sings it slow. Re-plan with sung-length windows")

    # 13. THE IDENTITY REFERENCE IS BIG ENOUGH TO HOLD A FACE. A 231 px banner crop gave
    #     the model three different men across one film (New Era, 2026-08-30).
    for ref in sorted({j.get("identityRef") for j in jobs if j.get("identityRef")}):
        w = image_width(ref)
        if w is not None and w < MIN_PORTRAIT_PX:
            bad.append(f"identity reference {os.path.basename(ref)} is {w}px wide — under "
                       f"{MIN_PORTRAIT_PX}px the model cannot hold the face across shots. Use a "
                       f"full-size frame or a character sheet built from one")


    # 1. every window is renderable on THIS route.
    for j in jobs:
        dur = float(j.get("seconds") or plan.get("seconds") or 0)
        if dur > cap:
            bad.append(f"{j['id']}: {dur:g}s exceeds the {cap}s cap for {route!r}"
                       + (" with a voice reference attached" if j.get("voiceRef") else ""))

    # 2. THE VOICE SLICE IS THE LIP-SYNC DRIVER. A slice shorter than its window leaves
    #    the tail with nothing to sync to, and the model mouths silence or invents.
    for j in jobs:
        ref = j.get("voiceRef")
        if not ref:
            continue
        if not os.path.isfile(ref):
            bad.append(f"{j['id']}: voiceRef missing on disk: {ref}")
            continue
        want = float(j.get("seconds") or 0)
        got = seconds(ref)
        if abs(got - want) > FPS_TOLERANCE_S:
            bad.append(f"{j['id']}: the voice slice is {got:.2f}s but the window is "
                       f"{want:g}s — {abs(got - want):.1f}s of it would have no vocal "
                       f"to lip-sync to. Re-run the plan stage to rebuild the slices.")

    # 3. the windows actually cover the film, with no hole between them — EXCEPT a
    #    gap of a second or more after a window's last word, which is a POOL SECTION:
    #    sung-length renders (2026-08-31) leave the instrumental between lines to
    #    B-roll on purpose (select_cut turns the hole into a shot-led section). A hole
    #    shorter than that is still a defect: nothing can fill it but a held frame.
    #    Measured the way select_cut tiles — from a window's COVERED end (tail slack
    #    excluded) to the next window's start — through raplib.plan_holes, so this gate
    #    and the cut never disagree about where a hole is (the first version counted
    #    the tail as picture and passed holes the cut then refused, 2026-09-02).
    for h in raplib.plan_holes(plan, min_s=0.0):
        hole = float(h["seconds"])
        if h.get("outro"):
            if TAIL_TRIM_TOL_S < hole < GAP_SECTION_MIN_S:
                bad.append(f"{h['after']} ends at {h['start']:.2f}s but the hook runs to {h['end']:.2f}s — "
                           f"{hole:.2f}s of the film has no picture (under {GAP_SECTION_MIN_S:g}s, too short "
                           f"for a cutaway; make_plan absorbs a remainder that short into the last render)")
        elif 0.05 < hole < GAP_SECTION_MIN_S:
            bad.append(f"{h['after']} ends at {h['start']:.2f}s but the next window starts at "
                       f"{h['end']:.2f}s — {hole:.2f}s of the film has no picture (under "
                       f"{GAP_SECTION_MIN_S:g}s, too short for a cutaway)")

    # 4. the film covers the SONG. The one the operator caught by ear.
    if song and os.path.isfile(song):
        song_len = seconds(song)
        film_end = max(float(j.get("startSec") or 0) + float(j.get("seconds") or 0)
                       for j in jobs)
        if song_len > 0:
            covered = min(film_end, song_len) / song_len
            if covered < MIN_SONG_COVERAGE:
                bad.append(f"the film is {film_end:.0f}s of a {song_len:.0f}s song "
                           f"({covered:.0%}) — {song_len - film_end:.0f}s would be "
                           f"discarded. Set HOOK_FULL_TRACK=1, or pass --short-ok to "
                           f"pick_hook to record that a window is what you meant.")

    # 5. pool footage must OUTLAST the cut it fills, or the assembler throws at plan
    #    time naming a clip but not a fix.
    #
    #    ONLY when the pool can actually be drawn from. The assembler pulls pool
    #    footage solely for windows WITHOUT a pinned performer — a window with no
    #    voiceRef, or one the vocal map demoted to shot-led. On a film where every
    #    window is a pinned performer the pool exists only for `cover` composites
    #    (which read from the clip's own start and need no margin), and this check
    #    fired a false alarm on exactly that film: 14.08s cutaways flagged as unable
    #    to fill cuts that would never be cut. A gate that cries wolf on the happy
    #    path is one people learn to click through.
    vm_doc = (json.load(open(vocal_map, encoding="utf-8"))
              if vocal_map and os.path.isfile(vocal_map) else {})
    pool_drawable = (any(not j.get("voiceRef") for j in jobs)
                     or any(w.get("shotLed") for w in vm_doc.get("windows") or []))
    if pool_drawable and broll_dir and os.path.isdir(broll_dir):
        longest = max(float(j.get("seconds") or 0) for j in jobs)
        need = longest + 1.0 + BROLL_MARGIN_S      # cut_len is ceil(longest)+1
        pool = [f for f in sorted(os.listdir(broll_dir)) if f.endswith(".mp4")]
        usable = [f for f in pool if seconds(os.path.join(broll_dir, f)) >= need]
        if pool and not usable:
            bad.append(f"none of the {len(pool)} B-roll clip(s) reaches {need:.1f}s, so "
                       f"none can fill a cut. Render B-roll longer than the windows.")

    # 6. A MOUTHING STRETCH WITH NOTHING TO CUT AWAY TO. The vocal map knows where the
    #    song stops singing; `cover` can only fix those seconds if B-roll exists by the
    #    time the renders finish. This check used to be nothing at all — an empty pool
    #    PASSED — and the operator watched a man mouth through thirteen seconds of
    #    instrumental outro that every other gate had approved. The B-roll was then
    #    authored by hand, hours after delivery. Fail HERE, before the render slot is
    #    spent, while planning a cutaway still costs nothing.
    if vm_doc:
        stretches = [g for g in (vm_doc.get("silentStretches") or [])
                     if float(g.get("seconds") or 0) >= MIN_COVERABLE_S]
        broll_planned = broll_plan and os.path.isfile(broll_plan)
        broll_rendered = bool(broll_dir and os.path.isdir(broll_dir)
                              and any(f.endswith(".mp4") for f in os.listdir(broll_dir)))
        if stretches and not broll_planned and not broll_rendered:
            total = sum(float(g["seconds"]) for g in stretches)
            bad.append(f"the song has {len(stretches)} vocal-free stretch(es) "
                       f"({total:.1f}s of mouthing if left uncovered) and NO B-roll is "
                       f"planned or rendered. Run make_broll_plan.py (the broll-plan "
                       f"stage) — a performer mouthing over an instrumental cannot be "
                       f"fixed by any re-render.")

    #    6b. ... and the pool must hold the FOOTAGE the cut will use: one fresh slice per
    #    gap section (select_cut.fill_gaps). Sized from the plan's own holes, against the
    #    B-roll plan's jobs — six 16 s cutaways for seven sections passed here and failed
    #    at select_cut after every render had landed (the duet fixture, 2026-09-02).
    if broll_plan and os.path.isfile(broll_plan):
        holes = raplib.plan_holes(plan, cap=max_clip_for(plan.get("route", ""), synced=False))
        bp = raplib.read_json(broll_plan) or {}
        planned = [float(j.get("seconds") or 0) for j in (bp.get("jobs") or [])]
        have, clip_max = sum(planned), max(planned, default=0.0)
        need_s = sum(float(h["seconds"]) + 0.2 for h in holes)
        longest = max((float(h["seconds"]) for h in holes), default=0.0)
        if holes and have < need_s:
            bad.append(f"the cut opens {len(holes)} instrumental section(s) ({need_s:.1f}s with slice "
                       f"margins) but the B-roll plan holds {have:.1f}s of cutaway — re-run the "
                       f"broll-plan stage (make_broll_plan sizes the pool from the plan's holes)")
        elif holes and longest + 0.2 > clip_max:
            # summed seconds are not enough: each section takes ONE slice of ONE clip
            bad.append(f"the longest instrumental section is {longest:.1f}s but the longest planned "
                       f"cutaway is {clip_max:.1f}s — no clip can fill it. Re-run the broll-plan stage")

    # 7-10. THE PROMPT MUST SAY WHAT THE AUDIO DOES (2026-08-22, six draws wasted).
    #    Prompts are composed per STYLE; a mostly-instrumental window was told to rap
    #    for 13 seconds and the model invented the vocal, four draws running. With a
    #    vocal brief on disk these are refusals, not advice:
    #    7. a window whose slice sings NO words must not carry a voice reference;
    #    8. a synced window must not open on a long silence — the model starts singing
    #       anyway, and every draw lands late (w00: +400, +725, +1325, +1875ms);
    #    9. every voice-carrying window's prompt must carry ITS OWN per-window vocal
    #       direction (the brief's lines), never the generic style sentence;
    #   10. a synced window should START on a sung line (a slice that opens mid-phrase
    #       asks the mouth to open on nothing) — advisory unless the head is silent.
    if vocal_brief and os.path.isfile(vocal_brief):
        bdoc = json.load(open(vocal_brief, encoding="utf-8"))
        brief = {w["id"]: w for w in bdoc.get("windows", [])}
        for j in jobs:
            b = brief.get(j["id"])
            if not b:
                bad.append(f"{j['id']}: no entry in the vocal brief — re-run vocal_brief.py "
                           f"after make_plan (the brief must describe THESE windows)")
                continue
            voiced = bool(j.get("voiceRef"))
            if voiced and not b["spans"]:
                bad.append(f"{j['id']}: carries a voice reference but its slice sings NO "
                           f"words — send it without a voice (shot-led), the mouth has "
                           f"nothing to follow")
            head = b["silences"][0]["end"] if b["silences"] and b["silences"][0]["start"] == 0 else 0.0
            if voiced and head >= MAX_SILENT_HEAD_S:
                bad.append(f"{j['id']}: synced, but its slice opens on {head:.1f}s of "
                           f"silence (limit {MAX_SILENT_HEAD_S:g}s) — the model will start "
                           f"singing anyway and land late on every draw. Re-cut the window "
                           f"to start on a sung line, or send it shot-led.")
            if voiced and "lip-sync to it EXACTLY and only where words are sung" not in j.get("prompt", ""):
                bad.append(f"{j['id']}: the prompt carries the generic style sentence, not "
                           f"this window's vocal direction — re-run make_plan with "
                           f"--vocal-brief")
            # 15. THE FACE MUST BE THE SINGER. A solo window whose performer is one
            #     gender while the track's voice in it is the other puts her face on his
            #     line (w03 on the first couple film: the sheet said "Both", the take was
            #     his). The brief's `who` comes from the track's pitch when a song is given.
            if voiced and j.get("performer") in ("a", "b"):
                prons = [x.strip() for x in (plan.get("pronouns") or "he").split("|")]
                pron = prons[1 if j["performer"] == "b" else 0] if len(prons) > (1 if j["performer"] == "b" else 0) else "he"
                face = {"he": "male", "she": "female"}.get(pron)
                if any(sp.get("who") in ("a", "b") for sp in b["spans"]):
                    face = j["performer"]        # a letter-tagged sheet: the performer IS the voice
                # A both/duet line is THIS face's to sing (same rule as make_plan):
                # counting only solo spans let 0.8 s of her verse in w04's tail slack
                # outweigh his 4 s hook line and refuse a correct plan (2026-08-23).
                sung = [sp for sp in b["spans"] if sp.get("who") in ("male", "female", "both", "duet", "lead", "a", "b")
                        and not sp.get("partialHead") and not sp.get("partialTail")]
                if face and sung:
                    other = sum(sp["end"] - sp["start"] for sp in sung
                                if sp["who"] in ("male", "female", "a", "b") and sp["who"] != face)
                    mine = sum(sp["end"] - sp["start"] for sp in sung
                               if sp["who"] == face or sp["who"] in ("both", "duet", "lead"))
                    if other > mine:
                        # the planner should have sent this as a non-singing shot (no voice)
                        bad.append(f"{j['id']}: the face is {face} (performer {j['performer']}) but the "
                                   f"track's voice here is mostly the other performer's ({other:.1f}s vs "
                                   f"{mine:.1f}s) and the window still carries a voice reference — re-run "
                                   f"make_plan with --vocal-brief (it sends such a window as a non-singing "
                                   f"shot), give the window to the singer, or make it a both-window")
            if not voiced and "<<<audio_1>>>" in j.get("prompt", ""):
                bad.append(f"{j['id']}: no voice reference, yet the prompt cites "
                           f"<<<audio_1>>> — an uncited/unattached media pair is a "
                           f"submit-time error")

    # 11. THE SLICE IS THIS WINDOW'S AUDIO. Check #2 compares lengths; a slice of the
    #     right length cut from the WRONG offset passes it. build_voice cached by path
    #     + duration, so a re-plan with new windows kept the old audio (w08: 1.00 at
    #     94.5s, -0.04 at its planned 81.84s) and every render was synced to the wrong
    #     bar. Correlate the slice against the song where the plan says it sits.
    #     ... against the slice's SOURCE: the plan records what the slices were cut from
    #     (`voiceWav` — hook.wav for VOICE_SOURCE=mix, the vocal stem for `stem`). A stem
    #     slice correlated against the mix reads low for the bed, not for a wrong offset.
    plan_src = plan.get("voiceWav") if plan.get("voiceWav") and os.path.isfile(plan["voiceWav"]) else song
    if plan_src and os.path.isfile(plan_src):
        for j in jobs:
            ref = j.get("voiceRef")
            if not ref or not os.path.isfile(ref):
                continue                      # #2 already refused a missing slice
            # a job may name its own source (an A/B plan mixes stem and mix arms)
            slice_src = j["voiceWav"] if j.get("voiceWav") and os.path.isfile(j["voiceWav"]) else plan_src
            start = float(j.get("startSec") or 0)
            secs = float(j.get("seconds") or 0)
            if secs <= 0:
                continue
            c = slice_matches_window(slice_src, ref, max(0.0, start), secs, float(j.get("muteHeadSec") or 0.0),
                                     float(j.get("muteTailSec") or 0.0))
            if c < SLICE_MATCH_MIN:
                bad.append(f"{j['id']}: voice slice is not this window's audio — rebuild "
                           f"(stale cache): it correlates {c:.2f} with {os.path.basename(slice_src)} at "
                           f"{start:.2f}s (need >= {SLICE_MATCH_MIN})")

    # 12. THE MAP AND THE BRIEF AGREE ON WHICH WINDOWS ARE SHOT-LED. select_cut reads
    #     the map; make_plan read the brief. Two answers = a window pinned with a
    #     performer that was rendered without a voice, or the reverse.
    if vm_doc and vocal_brief and os.path.isfile(vocal_brief):
        bdoc = json.load(open(vocal_brief, encoding="utf-8"))
        brief_mode = {w["id"]: w.get("mode") for w in bdoc.get("windows", [])}
        for w in vm_doc.get("windows") or []:
            wid = w.get("id")
            if wid not in brief_mode:
                continue
            if bool(w.get("shotLed")) != (brief_mode[wid] == "shot-led"):
                bad.append(f"the vocal map and the brief disagree on {wid}: map shotLed="
                           f"{bool(w.get('shotLed'))}, brief mode={brief_mode[wid]!r} — "
                           f"re-run vocal_map with --brief so both read the same lines")

    # 13-14. THE DIRECTION MUST NAME THE RIGHT MOUTH. In a `both` window a solo line
    #     that says "their mouths shape" has the other performer mouthing words that
    #     are not theirs; a window sent with NO voice must not be told to rap or sing
    #     at all (w01 was: "raps short clipped phrases" over a silent slice).
    for j in jobs:
        prompt = j.get("prompt", "")
        if j.get("performer") == "both":
            for sp in solo_span_says_their_mouths(prompt):
                bad.append(f"{j['id']}: a solo span in a `both` window directs BOTH "
                           f"mouths — \"{sp[:90]}\" — only the named voice's mouth "
                           f"shapes the words; the other stays closed")
        if not j.get("voiceRef"):
            verbs = performance_verbs_in_silent_prompt(prompt)
            if verbs:
                bad.append(f"{j['id']}: no voice reference, but the prompt still directs "
                           f"a performance ({', '.join(sorted(set(verbs)))}) — with no "
                           f"audio the model invents one; say how they MOVE, lips closed")
        for other, a0, a1, text in foreign_lines(plan, j):
            bad.append(f"{j['id']}: performer {j.get('performer')} but the {other} line "
                       f"\"{text[:48]}\" ({a1 - a0:.1f} s at {a0:.2f}-{a1:.2f}s) is inside the "
                       f"window — it straddles the performer handover, so this face (and under "
                       f"vocal-swap this voice) would sing the other performer's line. Cut the "
                       f"window at {a0:.2f}s: line_windows does; a short-line merge must not rejoin it")
    # 19-21. THE SHOT REFERENCES ARE WHAT THE PLAN SAYS THEY ARE (shot_refs.py / make_plan
    #     --shot-refs). A keyframe that is not on disk, not 1280x720, or refused by the media
    #     gate; a donor whose length is not the window's or that carries audio; a prompt that
    #     took the keyframe but not the rewrite — each ships a plausible wrong take.
    refs_doc = None
    refs_rec = (plan.get("inputs") or {}).get("shotRefs") or {}
    if refs_rec.get("path") and os.path.isfile(refs_rec["path"]):
        try:
            refs_doc = json.load(open(refs_rec["path"], encoding="utf-8"))
        except (OSError, ValueError):
            refs_doc = None
    for j in jobs:
        sr = j.get("shotRef")
        if not sr or not j.get("voiceRef"):
            continue
        wrec = ((refs_doc or {}).get("windows") or {}).get(j["id"], {})
        kf = j.get("identityRef") or ""
        if not os.path.isfile(kf):
            bad.append(f"{j['id']}: shot-ref keyframe missing on disk: {kf}")
        else:
            try:
                from PIL import Image
                with Image.open(kf) as im:
                    size = im.size
            except Exception:                                    # noqa: BLE001
                size = None
            if size != (1280, 720):
                bad.append(f"{j['id']}: shot-ref keyframe is {size}, not 1280x720 — normalise it (shot_refs.py does)")
        g = (wrec.get("gate") or {}).get("keyframe")
        if g and not g.get("ok"):
            bad.append(f"{j['id']}: the keyframe was REFUSED by the media gate ({g.get('reason') or g.get('status')}) — regenerate it")
        prompt = j.get("prompt", "")
        for needle in ("@IMG_1", "@IMG_2", "first frame of this shot"):
            if needle not in prompt:
                bad.append(f"{j['id']}: a shot-ref window's prompt lacks {needle!r} — apply_shot_refs did not land")
        if j.get("motionRef"):
            mr = j["motionRef"]
            if not os.path.isfile(mr):
                bad.append(f"{j['id']}: motion donor missing on disk: {mr}")
            else:
                pr = subprocess.run(["ffprobe", "-v", "error", "-show_entries", "stream=codec_type:format=duration",
                                     "-of", "json", mr], capture_output=True, text=True)
                try:
                    info = json.loads(pr.stdout)
                except ValueError:
                    info = {}
                dur = float((info.get("format") or {}).get("duration") or 0)
                if abs(dur - float(j.get("seconds") or 0)) > 0.25:
                    bad.append(f"{j['id']}: motion donor is {dur:.2f}s, the window renders {j.get('seconds')}s — "
                               "the donor must be cut to the window (shot_refs.py --donor)")
                if any(st.get("codec_type") == "audio" for st in info.get("streams", [])) and not wrec.get("donorAudio"):
                    bad.append(f"{j['id']}: motion donor carries an AUDIO stream — it must be mute (the voice is the clock)")
            gd = (wrec.get("gate") or {}).get("donor")
            if gd and not gd.get("ok"):
                bad.append(f"{j['id']}: the motion donor was REFUSED by the media gate ({gd.get('reason') or gd.get('status')})")
            if "@video1" not in prompt and "<<<video_1>>>" not in prompt:
                bad.append(f"{j['id']}: carries a motion donor but the prompt never cites @video1")
    return bad


def main() -> None:
    ap = argparse.ArgumentParser()
    ap.add_argument("--plan", required=True)
    ap.add_argument("--song", default="")
    ap.add_argument("--broll", default="")
    ap.add_argument("--vocal-map", default="", help="check #6: gaps need cutaways")
    ap.add_argument("--broll-plan", default="", help="the plan that satisfies check #6")
    ap.add_argument("--vocal-brief", default="", help="checks #7-10: prompts follow the audio")
    ap.add_argument("--json", action="store_true")
    args = ap.parse_args()

    if not os.path.isfile(args.plan):
        print(f"plan_coherence: no plan at {args.plan}", file=sys.stderr)
        raise SystemExit(2)
    plan = json.load(open(args.plan, encoding="utf-8"))
    bad = check(plan, args.song or None, args.broll or None,
            args.vocal_map or None, args.broll_plan or None, args.vocal_brief or None)

    jobs = plan.get("jobs") or []
    summary = {"windows": len(jobs), "route": plan.get("route"),
               "seconds": sorted({float(j.get("seconds") or 0) for j in jobs}),
               "problems": bad}
    if args.json:
        print(json.dumps(summary, indent=2))
    if not bad:
        if not args.json:
            print(f"plan_coherence: {len(jobs)} window(s) — the numbers agree")
        return
    print(f"plan_coherence: REFUSED — {len(bad)} disagreement(s) between numbers that "
          f"must match:", file=sys.stderr)
    for b in bad:
        print(f"  * {b}", file=sys.stderr)
    print("\n  Each of these has shipped a finished, plausible, WRONG film before. Fix "
          "them here,\n  not after the renders.", file=sys.stderr)
    raise SystemExit(4)


if __name__ == "__main__":
    main()
