Edittimeline

Run the full Resolve timeline editing pipeline in order. Each step runs to completion before the next begins, and every step is bracketed by `audit_step.py snapshot` (before) + `audit_step.py audit` (after) so that any unexpected change is caught immediately instead of compounding through downstream steps.

Arguments: $ARGUMENTS (pass --dry-run to preview the battles step without modifying the timeline)

All commands MUST be run from C:\Programming\resolve-mcp (every command uses `cd /d` prefix).

---

## Step-level audit (read this first)

Every step `N` is wrapped:

1. cmd.exe /c "cd /d C:\Programming\resolve-mcp && .venv\Scripts\python.exe scripts\audit_step.py snapshot --step "
2. <the step's actual command(s)>
3. cmd.exe /c "cd /d C:\Programming\resolve-mcp && .venv\Scripts\python.exe scripts\audit_step.py audit --step "

If the audit exits with a non-zero code: STOP. Read `_data/audits/<step_id>_report.json` and surface the violations + regressions to the user. Do not proceed to the next step until the user has decided how to handle them (re-run the step, accept the deviation, or abort).

When the audit passes, it automatically exports a Resolve-native `.drt` checkpoint to `_data/drt-checkpoints/` and records that path in the report's `drt_checkpoint` field. This is mandatory for any API-built or API-modified section; if the checkpoint export fails, the audit fails and the pipeline stops. Use the DRT as the durable Resolve-native recovery point for that step.

Scope declarations for every step live in `scripts/audit_scopes.py`. The audit checks two things:
- **Diff vs scope** — the changes actually observed must fall within the step's declared `allowed_changes`. Any other change is a violation.
- **Preservation** — entries in `must_preserve` (e.g., Green battle-end markers, Magenta carousel marker, A2 clip continuity) survive the step. A lost marker that was placed by a prior step is flagged as a *regression*.

Steps that create a new timeline (1d, 4, 6f) switch the audit into "derived expectations" mode (V1 clip count delta, source pool preserved, new TL name contains expected suffix, A2-A5 empty on the new TL when required).

---

## Pipeline ordering principle

**Cuts come first.** Applying cut candidates produces a NEW timeline (`(cuts: all)`) from FCPXML and discards anything that lives only on the old timeline (markers, audio placements, V2 overlays, color grades). Only operations whose state is portable — source-time decisions cached in JSON — survive a cut step. So the order is:

1. Operations that produce **portable JSON state** (transcript, battle source-time decisions, cut analysis)
2. **Apply cuts → new `(cuts: all)` timeline**
3. **Build edit timeline → new `(cuts: all) (edit)` timeline** (intro/outro, also a new TL)
4. Operations that produce **timeline-resident state** (markers, V2 carousel, A2 audio, Fairlight)

Re-running cut analysis later in the workflow would force redoing everything in categories 3–4. Putting cuts up front means we only commit timeline-resident operations to the final edit basis.

**Reorganization vs the previous pipeline:**
- The old Step 1 (clear A2-A5 on the original timeline) has been removed — that timeline is replaced twice (battle-gaps, cuts: all) and Step 4 already drops the auto-editor's linked audio refs. The clear was a no-op.
- The old Step 7 (mark A1 gaps on `(cuts: all)`) has been moved to Step 7 below — AFTER the edit timeline is built — so its ruler markers survive on the timeline of record.
- The old Step 13d ↔ 13e have been inverted: battle audio now lands on A2 BEFORE the between-battle BGM chain. The BGM chain then derives battle ranges from existing A2 clip boundaries (via `place_battle_bgm.py --respect-existing-a2`, on by default), eliminating the overlap risk that came from BGM and battle audio fighting over the same frames.
- The old defensive `clear_audio_tracks` of A2-A5 (was Step 13prep) has been removed. The Step 6 audit declares "A2-A5 must be empty on the new edit timeline" — if they aren't, the audit fails and the user investigates rather than silently nuking content.

---

## Pipeline order

### Step 0 — Session-log marker preflight

Run this before any transcript, battle-detection, or FCPXML rewrite work:

cmd.exe /c "cd /d C:\Programming\resolve-mcp && .venv\Scripts\python.exe scripts\preflight_session_markers.py"

This writes `transcripts\session-markers-preflight.json`.

Read the JSON before continuing:

- If `should_embed_session_markers=true`, the project has an RBYNewLayout
  session log. Treat those markers as canonical from the start of the pipeline.
  Do not infer RBY battle markers from transcript guesses when the preflight has
  mapped session-log markers to source media. Preserve/remap those markers
  through every FCPXML-derived timeline, and use timeline `* Battle Start`
  markers as canonical for Gen 1 leader intro placement.
- If `should_embed_session_markers=false`, continue with the normal transcript
  battle-detection flow below.
- If source media is split into multiple part files, use `markers_by_media` from
  the preflight to know which part(s) receive valid session markers. Do not
  collapse separate part files into a single combined MP4 just to simplify
  marker mapping.
- If the report says a session log exists but marker replay or source-media
  mapping failed, stop and surface the report. Do not continue until the user
  decides whether to proceed without embedded markers.

### Step 0b — Dialogue audio sanity check for split Gen 1 sources

Before re-running auto-editor or transcription on split source files, identify
the dialogue audio track deliberately:

cmd.exe /c "cd /d C:\Programming\resolve-mcp && .venv\Scripts\python.exe scripts\detect_dialogue_audio.py --video "<part-file>.mp4" --out _data\dialogue-audio-.json --fail-weak"

The expected dialogue track is mostly quiet except when the streamer speaks,
and Whisper should