Epic 2: plan for holding five minutes

Written after watching the output rather than after building it. Records what
was measured — the cut metronome, the frozen palette, the 39% of the library
that either churns without developing or barely moves, the constant
kind-to-family table, five or six distinct images per track — and turns it
into five workstreams with gates and a sequence.

Also records what NOT to touch: the production-design layer measures as
strong as parameter variation, so the unifying mechanism is working and is
explicitly out of scope.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

flow-state/EPIC-2.md

@@ -0,0 +1,186 @@
+# Epic 2 — from texture generator to something worth watching
+
+PLAN.md took this from nothing to a deterministic engine with a 42-scene library, a
+production-design layer, and an editor. Epic 2 is the answer to a different question, asked
+after watching the result rather than after building it:
+
+> Is it varied enough per track? Interesting enough to hold five minutes? Pleasant enough to
+> watch for long? Is there a unifying factor? Are we reusing the same visuals between tracks?
+> Are the visuals active enough?
+
+The honest answers were: partly, no, mixed, yes, yes, and no in both directions. This document
+is what those answers turn into.
+
+---
+
+## 1. What was measured
+
+Everything below is a number off the real system, not an impression. The measurements are
+reproducible from the check harness and several have become gates (§4).
+
+**Shot rhythm is a metronome.** A five-minute track at 90 BPM gets sixteen shots of 19.3,
+18.7, 18.7, 18.7 … 18.7, 19.3 seconds. At 124 BPM it is 15.5/15.5/13.6 repeating. `planShots`
+picks a bar count *once per section* and then divides the section evenly, so every cut inside
+a section lands on the same pulse. Over five minutes that is the most fatiguing edit rhythm
+available.
+
+**The palette is frozen for the whole track.** One `look.palette`, pushed to every layer of
+every section for the entire runtime. Colour is the strongest perceptual variable the system
+has and it never moves.
+
+**39% of the library does not develop.** Rendering every scene at generated parameters and
+comparing frames 0.5 s / 5 s / 30 s / 2 min apart, normalised for brightness:
+
+| behaviour | count | examples (0.5 s → 2 min) |
+|---|---|---|
+| churn — changes as much in half a second as in two minutes | 11 | Curl Flow 0.81 → 0.75, Moiré Grid 1.42 → 1.40, Circuit Bloom 2.86 → 2.83 |
+| nearly static | 5 | Pylon Grid 0.15 at 2 min, Dust Chamber 0.39, Salt Flat 0.64 |
+| genuinely evolving | ~25 | Flora 0.29 → 3.25, Silk Ribbon 0.26 → 2.68, Slow Orb 0.09 → 1.21 |
+
+Churn is the more interesting failure. Those scenes are violently animated and read as
+*static*, because motion without structure is texture: the eye adapts in about two seconds and
+then there is nothing left to find. "Active enough" fails at both ends of the range.
+
+**The most-cast scenes are among the least developing.** Across twelve tracks, four scenes
+appeared in ten to twelve of them — Dust Chamber, Slow Orb, Salt Flat, Eclipse Field — and two
+of those are in the nearly-static bucket. Twenty-nine of forty-two scenes appeared in none of
+the twelve.
+
+**Every track makes the same genre decisions.** `FAMILY_BY_KIND` is a module constant: an
+intro is always minimal/flow/organic, a drop always geometric/glitch/structural, and intro and
+outro are literally the same list. Cross-track sameness is baked into a table.
+
+**A five-minute track shows five or six distinct images.**
+
+**The production-design layer works and is not in scope for this epic.** Changing only the
+personality moves the image 0.846; changing only the parameters 0.882; changing only the
+palette 0.467. The unifying mechanism is as strong as the variation mechanism. Leave it alone.
+
+---
+
+## 2. The diagnosis
+
+Two separate problems, and it matters that they are separate:
+
+**The system has no arc longer than fifteen seconds.** It has a per-frame arc (reactivity), a
+per-shot arc (cuts), and a per-section arc (drift), and then it stops. Nothing is built to pay
+off at minute four. Held attention over five minutes is a property of *structure over
+minutes*, and there is currently no mechanism that operates on that timescale.
+
+**Every scene is the same shot.** A locked-off, full-frame, abstract texture. There is no
+scale, no framing, no composition — no wide against close, no negative space, no subject the
+eye can track across a cut. Music-video attention is held by framing changes at least as much
+as by content changes, and the vocabulary for that does not exist here at all.
+
+The first is a set of bugs in disguise. The second is a ceiling.
+
+---
+
+## 3. The work
+
+Five workstreams, ordered by impact per unit of effort. Each is independently shippable and
+independently valuable; nothing here is a prerequisite for anything below it except where
+noted.
+
+### 3.1 Break the cut metronome
+
+Shot lengths must vary *within* a section. The target is a phrase shape rather than a pulse: a
+long hold, two quick ones, a long hold. Cuts still land on downbeats and still respect the
+floor and ceiling — this changes where the cuts are, not the rules they obey.
+
+The mechanism is a per-section **rhythm pattern**: a small set of bar-length sequences (`[8,
+8, 4, 4, 16]` and friends) chosen by seed and energy, walked in order and repeated as needed,
+instead of one bar count divided evenly. A section then reads as edited rather than as
+metered.
+
+Two things to preserve, both load-bearing and both easy to break here: cuts must stay on
+phrase lines, and `MIN_SHOT_SECONDS` / `MAX_SHOT_SECONDS` remain hard.
+
+### 3.2 A per-track director
+
+`FAMILY_BY_KIND` becomes one of several mappings, chosen per track at look-generation time.
+Each mapping is a coherent point of view about what a song looks like — one that answers a
+drop with geometry, one that answers it with glitch, one that stays organic throughout, one
+that treats the intro as structural rather than minimal.
+
+This is a small change that directly attacks the largest source of cross-track sameness, and
+it makes the twenty-nine unused scenes reachable without touching the library or the casting
+weights.
+
+### 3.3 Let the palette move
+
+Per-section colour movement, driven by the arc that already exists: a hue rotation, a
+saturation shift, or a scheme change into a drop. The track keeps one identity — the movement
+is *from* the track's palette, not a replacement for it — so this does not fight §3.5 of
+PLAN.md or the personality layer.
+
+Constraint: the contrast floor the Phase 3 palette gate enforces has to hold at every point in
+the movement, not just at the endpoints.
+
+### 3.4 Give the churn scenes a slow axis
+
+Each of the eleven needs at least one parameter on a multi-minute ramp, so that the frame at
+three minutes is not the frame at thirty seconds. This is per-scene work and it is mechanical,
+but it is the only thing that fixes the specific failure of "animated and yet static".
+
+The five nearly-static scenes get the opposite treatment, and Phase 7's movement gate already
+describes what "enough" means.
+
+### 3.5 A framing layer
+
+The one that raises the ceiling rather than the floor. A shared zoom / crop / scale envelope
+sitting above the scenes, so the same image can be played as a wide and as a close, and so a
+cut can change the framing without changing the subject.
+
+This is deliberately last: it is the largest change, it interacts with resolution
+independence (§1 of PLAN.md) and with the feedback buffer, and the four items above will have
+changed what it needs to do.
+
+---
+
+## 4. Validation
+
+The rule from PLAN.md §11 stands: variety is a property of a population, not of one render, so
+every gate here samples many tracks and asks about a spread.
+
+| workstream | gate |
+|---|---|
+| 3.1 rhythm | Within one section, shot lengths must have real spread (no section where every shot is within a few percent of the mean). Cuts still land on downbeats; floor and ceiling still hold. |
+| 3.2 director | Across a population, the same section kind must draw from more than one family set. Every scene in the library must be reachable by some director. No director may leave a kind with too few scenes to build a roster from. |
+| 3.3 palette | Contrast floor holds at every sampled point of the movement, not just the endpoints. Colour actually moves across a track — measurably, not decoratively. |
+| 3.4 slow axis | Every scene's two-minute frame distance must exceed its half-second distance by a real margin. This is the churn number from §1, promoted to a gate. |
+| 3.5 framing | Resolution independence survives (the existing dual-resolution diff). Framing changes are visible. Determinism holds. |
+
+Two failure modes are worth naming in advance, because both have already happened once in this
+project's history:
+
+- **A gate that measures the wrong thing.** The Phase 3 look-space check was propped up by
+  grain until grain was removed. Any new gate here should be sanity-checked by deliberately
+  breaking the thing it is supposed to catch.
+- **A change that a gate rewards and a viewer does not.** Cut variety that is *random* rather
+  than *phrased* would pass 3.1's gate and look worse. The gates are necessary and not
+  sufficient; the end-to-end watch stays the real test.
+
+---
+
+## 5. Sequencing
+
+1. **3.1 rhythm** — biggest felt change, smallest diff, no dependencies.
+2. **3.2 director** — small, orthogonal, attacks cross-track sameness directly.
+3. **3.3 palette** — medium, touches the arc driver.
+4. **3.4 slow axis** — large but mechanical, eleven-plus scenes, one at a time.
+5. **3.5 framing** — largest, and best attempted once the other four have landed.
+
+Each ships as its own commit with its gate green.
+
+---
+
+## 6. What this epic does not do
+
+- **It does not touch the personality layer.** Measured, it works.
+- **It does not grow the library.** Twenty-nine scenes are currently unreachable; making them
+  reachable (3.2) is worth more than adding a forty-third.
+- **It does not add audio analysis.** Every mechanism here is driven by features that already
+  exist in the FeatureTrack.
+- **It does not relax determinism.** Every rule in PLAN.md §1 still applies, and the seek /
+  export / repeat gates are non-negotiable.