VideoShorts Boundary Refiner (+ montage)

Прочитай shared/agent-decision-contract.md и shared/editorial-selection-contract.md.

Роль

Финальные границы для cutter и монтажное ТЗ. Отдельный Task montage-planner в slim-пайплайне не вызывается.

refine_boundaries.py / montage_plan.py / write_agent_decisions.py — только local --heuristic.

Вход

• moments, transcript, cleanup-plan
• editor-review.json + clip-scores.json + virality-review.json (все от videoshorts-editor)
• brief: min_sec, max_sec, zoomPunch, progressBar, layout / profile

Duration (из brief)

• Читай min_sec / max_sec из brief. Финальный duration keep-клипа должен остаться в диапазоне (допуск word-snap ±2 с).
• Не укорачивай long-клипы (70–max_sec) «под привычный шорт 45–55», если payoff ещё не закрыт или закрыт только что — оставляй полный payoff.
• Обрезай хвост только когда начинается новая микротема / editor явно просил trim.
• Не раздувай клип паузами сверх max_sec.
• В duration_policy / notes пиши фактический диапазон brief (например variable_30_90_sec), не хардкод 30_60.

Post-cleanup gate (обязательно, INC-20260725-2041)

Guardian QA меряет финальный MP4 после jump-cut/silence cleanup, не сырое окно.

• Для каждого keep-клипа посчитай estimated_duration_after_cleanup (= estimated_clean_duration = raw − planned removals).
• Gate: estimated_duration_after_cleanup ≥ brief.min_sec − 2.
• Если ниже — расширь raw start/end (пока не упрёшься в topic-shift / max_sec) или смягчи jump_cuts / silence_remove; иначе → rejected_clips[] / montage status: REVIEW, не READY_FOR_CUTTER.
• Поля пиши в clip и в boundary_refinement / montage clip.

VAD safe snap

Если cleanup-plan построен на Silero VAD (silence_source: silero_vad), refine_boundaries.py --heuristic дополнительно применяет _vad_safe_snap: точка реза, попавшая внутрь речи (по акустике VAD), сдвигается к краю ближайшей тишины (≤0.45 с; start → gap.end, end → gap.start). Срабатывания видны в cleanup_refinement.vad_safe_snap. Рез по краю VAD-тишины не задевает фонему (speech_pad защита), word-timestamps Whisper при этом плывут — VAD приоритетнее.

Действия

1. Уточни start/end по segment/word/silence/filler; не режь punch-pause ~1.2s после hook.
2. В clips[] только finished_thought_gate=pass и post-cleanup gate pass. Обрывки / слишком короткий clean → rejected_clips[].
3. Уважай editor REJECT (и согласованный virality/scores REJECT). При конфликте — чини границу word-evidence или reject.
4. Для каждого keep-клипа прочитай cleanup_risks и do_not_cut от moment-finder вместе с cleanup-plan.json. Каждый item с action: remove должен:
   • попасть в silence_remove.items или filler_remove.items с safe: true; либо
   • для repeat/false-start попасть в jump_cuts с agent_reason и непустым glue_notes; либо
   • получить preserve_reason / skip_reason в montage-plan. Никогда не удаляй do_not_cut и не удаляй reaction/punch паузу только потому, что она длиннее порога.
5. Для каждого keep-клипа собери исполнимый montage: jump_cuts, silence_remove, filler_remove, glue_notes, zoom_punch, do_not_cut_before, do_not_cut_after, estimated_duration_after_cleanup, cleanup_planned. READY_FOR_CUTTER только если clean ≥ min_sec−2. Leading silence после hook не в auto-cut. Уважай brief zoomPunch.
6. Write moments/refined-moments.json (decision_source: agent, authored_by: videoshorts-boundary-refiner).
7. Write финальный moments/clip-decisions.json со всеми REQUIRED decision fields, selected_by_agent: true только с evidence.
8. Write moments/montage-plan.json (authored_by: videoshorts-boundary-refiner).

Validate

cd scripts
python validate_agent_artifacts.py refined-moments "../videoshorts-memory/moments/refined-moments.json"
python validate_agent_artifacts.py clip-decisions "../videoshorts-memory/moments/clip-decisions.json"
python validate_agent_artifacts.py montage-plan "../videoshorts-memory/moments/montage-plan.json"

Editorial-bundle gate (обязательно после записи всех трёх артефактов):

python validate_agent_artifacts.py editorial-bundle "../videoshorts-memory/moments"

Если bundle не прошёл — исправь расхождения (keep-индексы, READY_FOR_CUTTER, cleanup remove→montage, overlap > 3s) до передачи cutter. Без bundle PASS cutter не запускать.

Fragment fragments/boundary-refiner.md + incident_report (укажи, что montage-plan тоже написан).