JamBuddy/docs/design/jam-roulette.md

Jam Roulette — design spec (task D-62)

Thesis: one button, two clicks, a jam. "Jam roulette" in the controls bar opens a genre menu (the 10 KB styles + Surprise me); picking one instantly rolls a random key + an interesting KB progression and seeds the exact state live detection already writes — lockedKey, detectedProgression, and a committed-shape progressionVoteRef — so the loop strip, the voicing rail, the licks strip, and the related-progressions card all populate exactly as if the loop had been detected. Musicians read the screen and start playing; the L-31 commit layer then treats the seed like any committed loop: agreeing detections confirm it, a genuinely different loop replaces it after REPLACE_VOTES, and New Song clears it. No new parallel state — the seed is a writer into the existing machine, not a second machine.

User ask (verbatim, sprint goal 2026-07-11): "one button that would be a random chord progression selection. a button up top 'jam roulette' and then select a genre (like we have jazz, blues rock etc) and then have a random key chosen and an interesting progression show up as a loop in the screen. it would fill in the loop section and a 4 bar progression or something so that everyone can see the key and the chords to be played with different voicing so they can start playing… then musicians can start playing and it continues from it"

Dependency note: L-60 is dep-blocked on C-50 (one-screen close-out). This spec is written against docs/design/one-screen.md's target layout (controls bar per §1.1, slim loop strip per §1.2, the two-column dashboard), which L-50 is building concurrently. Everything here that names the controls bar or the strip means the post-L-50 versions; the seed mechanism (§3) is layout-independent and verified against App.jsx as it stands today (~b753b58).

Standing principles honoured: reuse, don't duplicate; nothing shown twice; scroll > click; tokens only, no raw hex; the 🚨 App.jsx audio contract (callbacks / ref-sync / AudioCapture untouched).

---

1. UX flow

1.1 The button

• Where: right end of the controls bar, in the global-chrome cluster next to one-screen §1.1's ⛶ Jam view toggle ("a button up top" — the controls bar is the app's persistent top chrome; the header row stays reserved for Settings / New Song / Start).
• What: 🎲 Jam roulette — same button language as the existing controls: px-3 py-1 rounded-lg border border-border text-sm text-gray-200 hover:border-gray-500 focus-visible:ring-2 focus-visible:ring-accent transition-colors. While a seed is active (unconfirmed, §1.3) the button carries the seeded accent: border-accent/40 text-accent bg-accent/10 + aria-pressed="true" — same active treatment as the locked-key pill.
• Keyboard: real <button>, Tab-reachable, Enter/Space opens the menu.

1.2 The genre menu

Click → an anchored popover (not a page takeover; the jam never leaves the screen): absolute panel under the button, bg-panel border border-border rounded-xl shadow-lg p-1 z-20, one column of <button> rows (w-full text-left px-3 py-1.5 rounded-lg text-sm text-gray-200 hover:bg-accent/10 focus-visible:ring-2 focus-visible:ring-accent):

1. ✨ Surprise me — first row, divider under it (border-b border-border) — uniform pick over the 10 styles, then §2 as normal.
2. The 10 KB styles, straight from the registry: Object.entries(kb).map(([id, s]) => s.meta.label) — never a hard-coded list; an 11th style appears here for free.
3. When a seed is active, row 0 becomes ⟳ Re-roll — {styleLabel} (same style, fresh key + progression, honouring §2's no-repeat memory) and ✨ Surprise me moves to row 1.

Escape / click-outside / picking a row closes it. Focus returns to the button. Picking a genre seeds instantly — two clicks from cold to a full jam dashboard. No confirmation step: re-rolling is cheaper than confirming.

1.3 The seeded indicator — honest provenance

The dashboard must not pretend the roulette loop was heard. Until live detection confirms it, the slim loop strip's loop row swaps its chrome:

• The ♻ glyph becomes 🎲; the → loop tail becomes an amber provenance chip: rolled · {styleLabel} · {progression.name} · {Σbars} bars — play it! (text-amber-400 text-xs — amber is the app's established secondary accent, the rn colour; no new token). Σbars comes from the KB bars array — this is where "a 4 bar progression" is made visible.
• The loop chips themselves render identically to a detected loop (same chip anatomy, chord + rn) — the chords are real instructions, only the provenance differs.
• The moment the commit layer confirms the seed (§3.4 — first agreeing live detection), the indicator flips to the normal ♻ … → loop with no other visual change: the honest signal that "the band is now playing what was rolled". If a different loop replaces the seed, the indicator vanishes with the seed (the new loop is detection-owned).

Empty-state note: pre-first-note the history slot still shows "Start listening…" — correct and honest (nothing has been heard); the key chip shows the rolled key immediately (it's a real lockedKey, rendered with the 🔒 pill in the controls bar too, mode dropdown and unlock included — the rolled key is a first-class key lock, not a special display).

1.4 Flow summary

Cold start: 🎲 → genre → the dashboard fills (key chip + locked-key pill, loop chips with rn, voicing rail with every station's shapes/voicings, licks strip aimed at station 0, related progressions) → band reads, plays → playhead lights on the first committed loop chord → detection confirms after ~2 cycles → 🎲 indicator becomes ♻ → the jam continues under pure live detection. Mid-session: 🎲 acts as New Song + seed (§3.6) — one gesture, clean slate, new card.

---

2. Randomization rules

All randomness lives in the seed function (plain Math.random(); no audio contact). Inputs: the KB registry only.

2.1 Key

• Root: uniform over the 12 pitch classes, spelled from NOTES (sharp spellings) — mandatory, not stylistic: matchChordFromChroma names every committed chord via noteName(r) with preferFlat=false (theory.js:112, 445 — the live naming path), so only sharp spellings string-match detection later (§3.3).
• Mode: taken directly from the rolled progression's mode field — verified: every KB progression encodes mode, vocabulary major | minor | dorian | mixolydian (grep across all 10 progressions.js), all four already present in the key-lock mode dropdown and SCALES. No inference, no default needed.
• Confidence: 1 (the applyLock convention).
• Session memory: don't repeat the previous roll's root (re-draw once).

2.2 Progression pool ("interesting" AND seedable)

Per style, from kb[style].progressions, each entry realized + collapsed per §3.2 first. Pool membership = the hard bounds ∩ the round-trip invariant — a progression only rolls if the machine can genuinely confirm it:

• Hard length bounds: collapsed length must be 2–8.
  • < 2 — unrepresentable as a detected loop (detectRepeatingProgression min pattern length 2). Today this excludes nothing: even funk-one-chord collapses to two names (X7, Xsus4 — its ['dom7','dom7','sus4','dom7'] qualities survive collapse because a quality change on the same root is a different name; wrap-dedupe then drops the trailing X7). The rule stays as future-proofing for a true single-name vamp, and the code comment must say so honestly.
  • > 8 — the detector's candidate loop only sweeps lengths 2–8 (theory.js:627). A longer seed is not merely unconfirmable: as the band plays it, in-window fragments of it become the only detectable structure and replace the seed after REPLACE_VOTES = 3 — the card self-destructs into a sub-loop. Excludes today: jazz-blues (collapsed 10), blues-quickchange (9), bossa-blue (10).
• Round-trip invariant (the real gate) — the protocol is load-bearing: a progression passes iff, with the 32-commit window filled with repetitions of its seeded canonical form (steady state) and truncated at every partial-cycle offset (0…len−1 commits past a cycle boundary), the real detectRepeatingProgression returns exactly that form at all offsets. Steady-state-plus-all-offsets is the honest protocol because a jam is sampled mid-cycle, not at cycle boundaries — and a naive "feed 2 clean cycles" protocol gets both failure modes wrong: it spuriously fails all 8 two-name vamps (2 cycles × 2 names = 4 commits, under theory.js:609's history ≥ 6 gate — a ramp artifact, not a steady-state failure), and it passes blues-8bar, whose 7-name form actually fails at exactly 1 of its 7 phase offsets (4 cycles + 4 extra commits → the detector prefers the [C7, G7] alternation). Round-trip is empirical, not constructional — the detector's recency×occurrence scoring can prefer an internal alternation over the full form at some phase. The invariant is precomputed over the whole registry (lazy module-level memo on first roulette open — key-independent per §3.3.3, so one sweep in C covers all keys; an 11th style or new progression joins the pool automatically) and pinned by the L-60 commit-1 smoke sweep (same protocol verbatim — §3.4 flag 2).
• Honest numbers today (Critic gate ran the real matcher + detector under the protocol above): 4/56 fail — the 3 over-length forms plus blues-8bar's phase-offset failure — so the expected pool is 52/56, pinned exactly by the smoke sweep. (Pre-fix-(a), 10/56 additionally returned NO MATCH for their own collapsed form and country-145 matched a different progression — §3.3.1; all return to the pool with the fix, since matching post-fix is constructional, §3.3.4.)
• Weight = levelW × lenW (over pool members only):
  • levelW: level === 'intermediate' → 2; foundation/untagged → 1 (the D-20 rule: untagged counts foundation). "Interesting" = intermediate leans in, foundations still roll.
  • lenW: collapsed length 3–7 → 2 (the "4-bar-ish" sweet spot — note a collapsed 12-bar blues is 7 names, so the genre's staple stays strong); 2 and 8 → 1.
• No-repeat memory: rouletteMemoryRef (plain useRef([]) in App — UI-state ref, never read by audio code) keeps the last 6 rolled progression ids; they're excluded from the pool. If exclusion leaves the pool empty (small styles — several have 5 entries), fall back to excluding only the immediately previous id. The ref survives New Song deliberately (variety across songs is the point) and dies with the session.
• Weighted draw; push id to memory.

---

3. The seed mechanism — spec'd against the real App state

3.1 What the seed writes (exhaustive)

rollJam(styleId) — a plain function in App.jsx, sibling of quickLock/newSong:

1. newSong()                                 // §3.6 — the clean-slate rule
2. const info = { root: NOTES[rolledPc], mode: prog.mode, confidence: 1 }
   setLockedKey(info)
   effectiveKeyRef.current = info            // the quickLock precedent —
   chordVotesRef.current = []                // detection uses the key NOW
3. const loop = seedableLoop(prog, rolledPc) // §3.2 — realize→collapse→canonicalize
4. setDetectedProgression(loop)
5. progressionVoteRef.current = {
     committedKey: loop.join(','),           // the committed shape, L-31's own
     candidateKey: null,
     candidateCount: 0,
     seeded: true,                           // §3.4 — the one flag L-60 adds
   }
   progressionMissRef.current = 0            // (newSong already did; explicit)
6. setSeedInfo({ styleLabel, name, bars })   // §3.5 — display provenance
7. rouletteMemoryRef bookkeeping (§2.2)

Nothing else. Never touched: handleNote / handleChroma / handleOnset / handleWaveform, AudioCapture and its props, noteHistoryRef, keyVotesRef, chromaRingRef, the loop engine. The seed is display state + the two progression refs the L-31 effect already owns — exactly the audio contract boundary the L-60 ledger row grep-gates.

Synergy worth stating: handleChroma bails while effectiveKeyRef.current is null — a cold session normally can't commit chords until key detection locks. The seed provides the key up front, so the very first chroma frames can commit chords, and the diatonic bonus in matchChordFromChroma is already biased toward the rolled key. The roulette makes detection faster, not just decorated.

3.2 Realizing the loop — seedableLoop(progression, keyRootPc)

The chord names must be byte-identical to what detection would commit when the band plays the progression, or the commit layer treats the seed as a rival forever. Three steps, each forced by a verified code path:

1. Realize (the JamGuide stationVoicings formula, JamGuide.jsx:262-273): per station rootPc = (keyRootPc + degrees[i]) % 12, name = NOTES[rootPc] + (CHORD_TYPES[qualities[i]]?.suffix ?? ''). Sharp spellings only (§2.1).
2. Collapse consecutive duplicate names, then if first === last drop the last — mirrors detectRepeatingProgression's collapse of back-to-back commits (theory.js:611-615) plus the cyclic wrap (in the live stream the loop's tail flows into its head; setChordHistory also dedupes consecutive identical commits, App.jsx:363). E.g. blues-12bar degrees [0,0,0,0,5,5,0,0,7,5,0,7] → 7 names [I,IV,I,V,IV,I,V] realized; funk-one-chord keeps its quality changes (same root, different suffix ≠ duplicate → [X7, Xsus4]). Name-collapse is provably key-independent (§3.3.3) — the collapsed shape is a property of the progression, which is what makes fix (a) (§3.3.2) computable once, key-free.
3. Canonicalize rotation with theory.js's own rule — lexicographically smallest rotation compared via join('\0') (canonicalize, theory.js:579-586, currently private). detectRepeatingProgression returns its canonical rotation; the agreement branch compares exact join(',') strings, so the seed must store the same rotation or confirmation is unreachable (§3.4 flag 2).

Where it lives: seedableLoop exported from src/lib/match.js (loop-identity is that file's mandate; it already imports theory.js read-only; L-51 is adding adjacent exports there and L-60 runs after C-50, so no lock overlap). For step 3 it needs canonicalize: preferred — additive export keyword on theory.js's canonicalize (one-word diff; shared-file lock, flag to Maestro at L-60 promotion; smoke's loop-fixtures.mjs already byte-checks a replica of this function, so a second in-app replica would triple the drift surface). Fallback if Maestro won't open theory.js: replica in match.js with a drift comment + smoke guard, the loop-fixtures precedent.

Display note: the banner shows the seeded loop in this canonical rotation — identical to how any live-detected loop displays today; the JamGuide rail re-rotates to canonical KB order via match.rotation regardless, so the learning surface always reads in textbook order (ii first in a ii–V–I).

3.3 Matching + round-trip — constructional after fix (a)

3.3.1 The bug fix (a) exists for (Critic gate, real matcher run)

buildLoopIndex (match.js:126-141) indexes each progression's raw, uncollapsed degrees — but the seeded loop (and the live commit stream, which dedupes back-to-back chords) is the collapsed form, a different sequence length whenever a progression repeats a chord across adjacent slots or across the wrap. The gate ran the real matcher: 10/56 progressions return NO MATCH for their own collapsed form — jazz-blues, blues-12bar, blues-quickchange, blues-8bar, blues-minor, bossa-blue, funk-one-chord, country-folk-axis, gospel-iv-passing-dim, gospel-tonicized-amen — and country-145 is worse: its raw 8-shape matches a different progression. Rolling blues would produce a populated banner and an empty JamGuide. This is also a pre-existing live-detection bug the roulette work surfaces: a band playing a real 12-bar blues today commits the collapsed stream and gets an empty JamGuide — fix (a) repairs both at once.

3.3.2 Fix (a) — collapsed-form indexing (Maestro-directed, mandatory)

buildLoopIndex additionally indexes each progression's collapsed form:

• Collapse rule (key-free): dedupe adjacent stations whose (degree, suffix) pairs are equal, where suffix = CHORD_TYPES[quality]?.suffix ?? '' (compare suffixes, not raw quality tokens — two out-of-vocab qualities both fall back to '' and produce equal names, so a token comparison would under-collapse); then wrap-dedupe: if the last pair equals the first, drop the last (one check suffices post-collapse — only the boundary pair can merge).
• What's indexed: canonicalDegrees(collapsedDegrees) → an entry whose progression is the collapsed projection of the authored one: { ...progression, degrees, qualities, rn (first-of-run), bars (summed per run), sourceIndex } where sourceIndex[i] = the first raw station index of collapsed station i. Same id/name/level/mode/songs/tip.
• Only when it differs: entries are added only where the collapsed shape ≠ the raw shape — 45/56 index once, 11 twice. The full census (gate, raw → collapsed): jazz-blues 12→10, blues-12bar 12→7, blues-quickchange 12→9, blues-8bar 8→7, blues-minor 12→5, bossa-blue 16→10, funk-one-chord 4→2, country-145 8→4, country-folk-axis 8→7, gospel-iv-passing-dim 4→3, gospel-tonicized-amen 5→4.
• The true compatibility invariant (stated exactly): collapsed entries are appended after all raw entries, so matchLoopToProgression's strict-> disambiguation keeps every previously-matching input's winner on ties — but append order never engages on a strict score win, and one real case exists: for input shape [0,5,0,7] with maj/maj/maj/dom7 qualities (e.g. [C, F, C, G7]), country-145's collapsed form scores 4×100−4 and strictly beats the incumbent country-bluegrass-cycle (3×100−4 — its quality set lacks dom7). Gate-verified registry-wide (raw + collapsed × 3 keys): this is the only winner change, and it is an improvement — the progression actually being played now self-attributes (pure-triad [C,F,C,G] input still ties and keeps bluegrass-cycle). So: behaviour-preserving except where a collapsed entry strictly dominates the disambiguation score, enumerated: country-145, desired direction. Previously-NO_MATCH collapsed streams now match; that is the point.
• Rotation: for a collapsed-form hit, rotationToCanonicalOrder runs against the collapsed degrees — equal lengths by construction. (Today's length-mismatch guard, match.js:208, silently returns 0, which is exactly what would break the playhead if the raw progression were returned instead.)

Downstream, JamGuide renders the projection's stations naturally — a 12-bar renders 7 stations, one per distinct change (the right glance-rail answer: duplicate consecutive bars add no voicing information; the strip's loop chips carry position). The one alignment consumers need: every authored-play lookup must remap through sourceIndex — otherwise a collapsed match reads the first N raw play entries against the wrong stations. There are four raw-indexed lookups, not two:

• guitar shape path, JamGuide.jsx:280, and piano recipe path, :288 — both inside the stationVoicings memo: play.chords[prog.sourceIndex?.[i] ?? i];
• bass, inside BassGuideRows: play?.chords?.[i]?.pattern (:530) and …?.note (:533). Mechanism chosen: the stationVoicings memo attaches a per-station sourceIndex field (stations[i].sourceIndex = prog.sourceIndex?.[i] ?? i), and the two bass lines read play?.chords?.[st.sourceIndex ?? i] — BassGuideRows already receives the stations, so no new prop; the heard-live path's synthetic station has no sourceIndex and the ?? i fallback keeps it exact.

Blues ships guitar, piano and bass cells, and its bass pack covers four collapse-affected progressions (blues-12bar/quickchange/8bar/ minor), two of them pool members (blues-12bar 7, blues-minor 5) — so the bass remap is load-bearing for the roulette itself, not just for live detection. Four bounded lines + the one field attachment; JamGuide.jsx joins L-60's lock (§5).

3.3.3 Key-independence proof (why the index can be built key-free)

Realized names are Nᵢ = NOTES[(k + dᵢ) mod 12] + suffix(qᵢ) for key root k. Adjacent names are equal ⇔ their roots are equal AND their suffixes are equal. Roots: (k + dᵢ) ≡ (k + dⱼ) (mod 12) ⇔ dᵢ ≡ dⱼ (mod 12) — k cancels, and KB degrees live in 0–11, so this is plain dᵢ = dⱼ. Suffixes: the 14 CHORD_TYPES suffixes are pairwise distinct (verified by inspection, theory.js:41-55), so equal suffixes ⇔ the same suffix class — identical quality for in-vocab tokens, the shared '' fallback for out-of-vocab ones (hence §3.3.2 compares suffixes). Therefore name-collapse ≡ (degree, suffix)-pair collapse in every key: buildLoopIndex computes the collapsed shape once with no key in hand, and seedableLoop's per-key name collapse always produces that same shape. The same argument makes the §2.2 round-trip invariant key-independent: the detector consumes only the name stream's equality structure, which is key-invariant; the lexicographic rotation choice may differ per key, but seed and detector canonicalize identically over identical names, so agreement of the two outputs is preserved — one sweep in C covers all 12 keys.

3.3.4 What is constructional vs what stays empirical

• Matching is constructional post-fix-(a): every rolled loop is some progression's collapsed canonical shape, and fix (a) indexes exactly those — matchLoopToProgression cannot miss. (It may attribute to a same-shape sibling — the §4 quirk, now including within-style cases like country-145-collapsed ≡ country-bluegrass-cycle.)
• Detector round-trip stays empirical — hence §2.2's precomputed registry-wide invariant (steady-state window, all partial-cycle offsets) as the pool gate: today 4/56 fail — 3 over-length + blues-8bar's 1-of-7-offsets self-competition; expected pool 52/56, pinned by smoke. Worked example of a passer: rolled jazz-251-major in A → seeded [Bm7, E7, Amaj7] (canonical rotation) → band plays it → detection commits the same sharp names from the same CHORD_TYPES suffixes → after 2 cycles (6 commits, clearing the history ≥ 6 gate) the detector returns the identical canonical form at every subsequent commit, whatever the phase → agreement branch fires. ✓

3.3.5 Honest limit — qualities detection can't name

MATCH_CHORD_TYPES (theory.js:59-61) is a subset — KB qualities dim7 and min6 (7 progression slots across the KB, counted) can never be committed by detection under those exact names (it will hear dim / m7-ish). For such rolls the seed displays the authored chord, and once the band plays, detection consistently returns the as-heard loop → the REPLACE_VOTES branch swaps in reality after 3 commits. That is the machine working as designed — the card yields to what's actually played, and the re-match still lands on the same KB progression (degree shape unchanged, quality is only a tie-breaker). Same story if the band plays triads where the KB says sevenths. Not a bug; documented behaviour.

3.4 The L-31 commit-layer interplay — branch by branch

The effect (App.jsx:181-213) runs once per chord commit ([chordHistory] deps — seeding itself triggers exactly one run via newSong's setChordHistory([]), landing in the null branch at miss 1). With a seeded vote {committedKey: S, candidateKey: null, candidateCount: 0, seeded: true}:

Branch	Seeded behaviour	Verdict
Agreement (vote.committedKey === key)	Refreshes the loop, drops rivals — L-60 adds: vote.seeded = false + setSeedInfo(null). The seed is now a normal committed loop; every subsequent rule applies verbatim	works, 2-line addition
Rival counting (candidateKey bookkeeping)	A transient sub-cycle detection during ramp-up (real: a 7-name collapsed 12-bar contains [I,IV] twice before the full form recurs) starts a candidate; committedKey survives the rebuild — but the rebuild literal at line 207 drops seeded	🚩 flag 3 below
Replacement (candidateCount ≥ REPLACE_VOTES=3)	A genuinely different, consistently-detected loop replaces the seed; new vote is detection-owned (no seeded) — L-60 adds setSeedInfo(null) here	correct as-is: rolled cards must yield to a real band playing something else
Null branch / miss counter (NULL_CLEAR=6)	Kills EVERY seed during ramp-up — no length survives. L-31's "fills never null" reasoning assumed the loop is in the history window — a seeded loop isn't yet. Exact timeline: the seed's own effect run (via newSong's history reset) is miss 1; commits 1–5 take the counter to 6 → the card is wiped at commit 5. But the earliest any detection can land is commit 6 — detectRepeatingProgression hard-gates raw history < 6 (theory.js:609), so even a 2-name loop cannot confirm before then, and a loop of length len needs ~2·len commits besides. Unguarded, every seed dies exactly one commit before the earliest possible confirmation — the guard is mandatory for every pool member, not a long-loop nicety	🚩 flag 1 — the critical fix

Flags for L-60 (each a 1-line change inside the effect — the one licensed edit in that block):

1. Null-clear guard: if (progressionMissRef.current >= NULL_CLEAR && !progressionVoteRef.current?.seeded) { …clear… }. Semantics: a seeded card is an instruction, not an observation — it stays until confirmed (then normal rules resume), replaced by a consistently-detected different loop, re-rolled, or New Song. A band that noodles structurelessly under a seeded card keeps the card — intended: it's what they were asked to play.
2. Rotation equality is constructional (§3.2/§3.3) — no branch change, but if seedableLoop skipped canonicalization the agreement branch would be unreachable and the seed would churn-replace with itself (rotated) at commit 3. L-60's smoke-visible invariant is §2.2's registry-wide sweep, protocol verbatim: for each of the 56 progressions, fill the 32-commit window with repetitions of the seeded canonical form (steady state) and truncate at every partial-cycle offset (0…len−1 commits past a cycle boundary); the progression passes only if detectRepeatingProgression returns exactly the seeded canonical form at ALL offsets. Expected: 52 passers pinned; the 4 named failures (jazz-blues, blues-quickchange, bossa-blue, blues-8bar) asserted as excluded from the pool. (A naive 2-clean-cycles feed is wrong in both directions — §2.2.)
3. Preserve seeded across candidate rebuilds: line 207 becomes { committedKey, candidateKey: key, candidateCount: 1, seeded: vote?.seeded ?? false } — otherwise one transient ghost sub-cycle strips the flag and flag 1's guard dies with it, resurrecting the ramp-up kill through the side door.

Nothing else in the effect treats a seed differently — COMMIT_VOTES never applies (a committed key exists), and progressionMissRef.current = 0 on any detection keeps the counter honest once structure appears.

3.5 The provenance flag — machine truth vs display echo

Two readers need "seeded, unconfirmed": the effect (guard, flag 1) and the banner/button (indicator, §1.3). The effect reads vote.seeded — its own ref, already in hand, mutation-safe. The display cannot read a ref reactively, so App gains one small UI-state: const [seedInfo, setSeedInfo] = useState(null) — { styleLabel, name, bars } | null, passed to ProgressionBanner as a presentational prop (and read by the roulette button for its active state + re-roll row). This is provenance metadata that exists nowhere else (style label, progression name, bar count) — not a duplicate of detectedProgression. Invariant, enforced at every transition: seedInfo !== null ⇔ progressionVoteRef.current?.seeded === true. Sync points: set together in rollJam; cleared together in the agreement branch, the replacement branch, and newSong (one added line — setSeedInfo(null)).

3.6 New Song & mid-session rolls

newSong() (App.jsx:216-241) already clears the whole seed surface: progressionVoteRef.current = null, progressionMissRef.current = 0, setDetectedProgression(null), setLockedKey(null), setChordHistory([]) — verified line by line; L-60 adds only setSeedInfo(null). The seed clears naturally. ✓

Mid-session rule: roulette = New Song + seed (rollJam step 1). Without it, a 32-commit history still containing the old loop keeps re-detecting it and would replace the fresh seed within 3 commits even after the band switches — the stale window poisons the handoff. newSong() is the already-tested full reset (history, votes, key, BPM); seeding onto that clean slate makes ramp-up §3.4's only story. The banner history emptying is honest ("new song" is literally what the button did), and the loop-station audio is untouched (newSong never touched it).

---

4. What fills in — every consumer, verified

The seed sets lockedKey (→ effectiveKey) + detectedProgression (+ the vote ref). Consumers and their honest pre-first-note state (chordHistory empty, currentChord undefined):

Surface	Consumes	Seeded behaviour
Slim loop strip — key chip	keyInfo (= effectiveKey)	Rolled key + mode render immediately
Slim loop strip — loop chips	detectedProgression, findLoopPosition(chordHistory, loop)	All chips render (chord + rn via the rolled key). findLoopPosition returns −1 on empty history (match.js:75 guard) → no chip highlighted — correct: nobody is anywhere yet. 🎲 indicator per §1.3
Strip — history row	chordHistory	"Start listening…" — honest
JamGuide match	matchLoopToProgression(loop, kbIndex)	Matched by construction — after §3.3.2's fix (a) (mandatory L-60 scope): the seeded loop is the progression's collapsed canonical shape, which fix (a) indexes. Without the fix, 10/56 rolls (all of blues among them) would show a populated banner and an empty JamGuide — and the same fix repairs today's live-detection miss for real 12-bar streams. Header shows the progression name + "in {key}"
Voicing rail (GlanceRail / BassGuideRows)	stationVoicings (match + keyRoot), activeIndex = canonicalPos	Every station's shapes/voicings render in canonical KB order — for collapse-affected matches, the collapsed projection's stations (a 12-bar renders 7, one per distinct change) with plays remapped via sourceIndex (§3.3.2). canonicalPos guard (JamGuide.jsx:220-225) → −1 → no "now" row — the rail shows the whole map unhighlighted
Licks strip	activeStyle (= match.style), contextStation	Populates; contextStation falls back to station 0 when canonicalPos is −1 (JamGuide.jsx:341-344, existing comment says exactly this) — licks aim at the progression's first chord until the playhead exists
Related progressions (L-51)	{ loop, keyInfo, onChordClick }	Populates for free — it computes its own match from the loop
Instrument view	keyInfo, currentChord	Scale + pentatonic tiers light in the rolled key; no chord-tone tier until the first commit (currentChord undefined) — honest
ChordDetailModal	tap any chip	Works — chips pass real chord names
Chord detection itself	effectiveKeyRef	Enabled immediately by the seeded key (§3.1 synergy)

The pre-first-note playhead, stated plainly: there is none — no strip chip glows, no rail row is "now", and that is the design: a playhead claims knowledge of where the band is, and the app doesn't have it yet. It lights on the first committed chord whose name appears in the loop (findLoopPosition walks back from the last commit; a first chord outside the loop keeps it unlit). The 🎲 chip carries the "we're starting" affordance until then.

Style-attribution quirk (documented, accepted): same-shape progressions exist across styles (rock-axis / reggae-nwnc / pop-axis all [0,7,9,5]), and fix (a) adds within-style aliases (country-145-collapsed ≡ country-bluegrass-cycle). matchLoopToProgression disambiguates by quality overlap then length; ties fall to entry order (raw before collapsed, §3.3.2 — incumbents keep winning on ties), and the one strict-win exception is country-145's collapsed form over bluegrass-cycle for dom7-V input — the desired direction (§3.3.2's true invariant). So rolling pop → Axis may render the rail/licks attributed to rock. The chords, key, rn, and voicings are identical; only the style label and lick flavour differ. Re-judged against Maestro's belt-and-braces offer: with fix (a) mandatory, matching is constructional and a seeded styleHint would correct only the label/lick flavour — cosmetic, not load-bearing. Declined for v1 (it would plumb a new prop through JamGuide for no structural gain); noted for Maestro as a user-pulled follow-up if anyone notices.

---

5. L-60 scope — exact files, bounded commits

The audio-contract boundary (grep-gated, restated): the seed touches display state (lockedKey, detectedProgression, seedInfo, chordHistory via newSong) + the progression refs (progressionVoteRef, progressionMissRef) + UI refs (rouletteMemoryRef, effectiveKeyRef per the quickLock precedent) — never handleNote/handleChroma/handleOnset/handleWaveform, their ref-sync effects, or any AudioCapture prop.

Files:

1. src/lib/theory.js — additive only: export keyword on canonicalize (shared file — flag lock to Maestro at promotion; Professor+Critic co-review per PROTOCOL §3; fallback per §3.2).
2. src/lib/match.js — the sprint's real engineering weight, all additive:
   • seedableLoop(progression, keyRootPc) → string[] | null (realize → collapse+wrap-dedupe → canonicalize; null for collapsed length < 2);
   • fix (a) per §3.3.2: buildLoopIndex collapsed-form entries (collapsed projection with sourceIndex, appended after raw entries)
     • matchLoopToProgression collapsed-hit rotation against collapsed degrees. Behaviour-preserving except the one enumerated strict win (§3.3.2 true invariant: country-145, desired direction); previously-NO_MATCH collapsed streams now match — this also fixes the pre-existing live 12-bar miss;
   • the round-trip pool sweep helper (lazy module-level memo, §2.2). After C-50, no lock overlap with L-51's exports.
3. src/App.jsx — rollJam(styleId) + seedInfo state + rouletteMemoryRef; the roulette button + popover menu in the controls bar; the three 1-line commit-layer edits (§3.4 flags 1 & 3 + the two setSeedInfo(null) clears); one line in newSong.
4. src/components/ProgressionBanner.jsx — presentational seedInfo prop: 🎲 glyph + amber provenance chip on the loop row (§1.3).
5. src/components/JamGuide.jsx — four bounded lines + one field (§3.3.2): guitar-shape and piano-recipe lookups remap through prog.sourceIndex?.[i] ?? i (JamGuide.jsx:280, :288); stationVoicings attaches stations[i].sourceIndex; BassGuideRows' two raw-indexed lookups (pattern :530, note :533) read play?.chords?.[st.sourceIndex ?? i] — no new prop, heard-live falls back via ?? i. Re-lock at promotion — JamGuide is one-screen-locked until C-50, which L-60 already depends on.

Suggested commits (green at each):

1. theory.js export + match.js (seedableLoop + fix (a)) + the JamGuide sourceIndex remaps (all four paths incl. bass) + the smoke sweep: the §2.2 round-trip invariant over all 56 progressions under the steady-state/all-offsets protocol (§3.4 flag 2 verbatim; expected 52 passers pinned; the 4 named failures asserted excluded) plus a live-stream fixture proving a clean 12-bar history now matches (the pre-existing bug, pinned fixed).
2. App.jsx commit-layer guard lines + rollJam + state/refs (mechanism live, invokable from a temporary plain button if needed).
3. The controls-bar button + menu + banner indicator (the visible feature).

Out of L-60 scope: GlanceRail/VoicingBrowser (untouched — they render whatever stations JamGuide hands them), JamGuide beyond the four remap lines

• field, KB content, theory beyond the one export, audio, and the styleHint disambiguation (declined, §4).

---

6. Rejected alternatives

Rejected A — fake chordHistory injection (seed by pushing 2 synthetic cycles into history so the detector "discovers" the roll naturally). Seductive — zero commit-layer changes — and dishonest at every surface: the banner history strip shows eight chords nobody played; findLoopPosition immediately lights a playhead asserting the band is mid-loop before a note sounds; the L-31 cadence reasoning (thresholds are per real chord commit) silently breaks; and the first real commits interleave with the fake tail, producing corrupted-rep flapping (the exact pathology C-30/L-31 spent a sprint taming). The seed must write conclusions, not forge evidence.

Rejected B — a separate seededProgression state rendered when detectedProgression is null. Duplicates the loop's identity across two states with a priority rule; every consumer (strip, JamGuide, RelatedProgressions, future ones) must learn the fallback or silently miss the seed; and the detection handoff becomes a hard visual swap between two objects instead of the vote ref's smooth confirm/replace. The standing principle exists for exactly this: one loop, one state, one machine.

Rejected C — display-only overlay ("ghost card") that never enters the state machine, cleared on first detection. Honest-looking, but the screen's surfaces don't populate from a ghost: the rail, licks, and related progressions all key off detectedProgression — an overlay would either leave them empty (failing "so that everyone can see the chords with different voicings") or need Rejected B's plumbing anyway. Also loses the §3.1 synergy (no lockedKey → chord detection stays gated on key detection).

Rejected D — neutralize the ramp-up with a miss-counter credit (progressionMissRef.current = -(2·len + 4) at seed time) instead of the seeded flag. One line, no flag — but the credit is a magic number that burns in real time: a band that chats for eight commits' worth of noodling before starting spends it on nothing and the card still dies mid-ramp-up; and it leaves no way for the agreement branch to know confirmation happened (the indicator can't flip). The flag has clean semantics; the credit has arithmetic luck.

---

7. Flags for Maestro

• theory.js shared-file lock (additive export on canonicalize) — L-60 promotion must note it; Professor co-review per PROTOCOL §3.
• L-60 lock list per §5 (App.jsx + ProgressionBanner.jsx + match.js + theory.js + JamGuide.jsx, four remap lines + one station field) — supersedes the ledger row's "App.jsx (+ per D-62)".
• Fix (a) repairs a pre-existing LIVE bug (§3.3.1: real 12-bar/8-bar streams — 10 progressions match nothing in JamGuide today, and country-145 misattributes; 11 collapse-affected total, §3.3.2 census). Worth a line in the PR body / Herald's changelog: users get it even if they never touch the roulette.
• styleHint disambiguation — re-judged and declined for v1 (§4: cosmetic post-fix-(a)); user-pulled follow-up only.
• Smoke round-trip sweep (§5 commit 1, all 56 progressions + the live 12-bar fixture) — if Critic prefers it C-owned, it slots into C-61's sweep instead.
• No new tokens, no new colours (amber + accent are established), no dependencies, no KB/audio changes anywhere in this design.