JamBuddy/docs/agents/LEDGER.md

Ensemble Ledger — Live Task Board

The shared queue all agents read and write. Lifecycle and rules: PROTOCOL.md. Roster + cadence weights: ROSTER.md.

Status: backlog → ready → claimed → in-review → done / returned Lock: a task's files column is its lock — no two claimed/in-review tasks may overlap files.

---

Active sprint: sprint-jam-guide (branch: sprint-jam-guide)

Emphasis this sprint: ship the Jam Guide MVP (put the 8 guitar style packs on screen, synced to live detection) + reframe the repo as a learning platform. Weights this sprint: Luthier 3, Muse 3 (design-heavy), Professor 2, Herald 2, Critic gate.

Design-first gate (user directive 2026-06-14): Muse explored three distinct concepts; user chose "Roadmap" (improv-first highway) on 2026-06-15. Implementation tasks below are re-planned to build Roadmap. Concept doc: docs/design/jam-guide-concept-c.md. Stage/Playbook (-a/-b) kept as reference for future modes.

Roadmap build shape: a horizontal timeline panel — stations (= loop chords) carry guide-tone lanes (3rd/7th), a solo-scale label, and voice-leading rails (7→3) between stations; a playhead + beat grid track loop position; the chosen voicing is a secondary thumbnail per station; tap a station → guide tones on the fretboard. Needs derived theory (guideTones, voiceLeadingPairs, default soloScale) — Luthier owns those.

id	title	domain	status	depends-on	files (lock)	definition of done
M-01	Cut sprint-jam-guide branch; seed sprint	maestro	done	—	(branch)	branch cut, ledger header set
D-00a	Viz concept A — "Stage"	design	done	—	docs/design/jam-guide-concept-a.md	delivered; reference for future collapsed/glance mode
D-00b	Viz concept B — "Playbook"	design	done	—	docs/design/jam-guide-concept-b.md	delivered; reference for future study mode
D-00c	Viz concept C — "Roadmap"	design	done	—	docs/design/jam-guide-concept-c.md	delivered; CHOSEN
D-SEL	User selects a concept	maestro	done	D-00a, D-00b, D-00c	docs/agents/LEDGER.md	Roadmap chosen 2026-06-15; tasks re-planned below
L-01	Shared matcher: extract/author findLoopPosition (which chord index the loop is on) + rotation-invariant degree-relative loop→progression-id matcher into src/lib/match.js; refactor ProgressionBanner.jsx to use it	engineering	done	M-01	src/lib/match.js, src/components/ProgressionBanner.jsx	matcher maps detected loop → style progression id (rotation-invariant) AND returns current position index for the playhead; banner still works; build green — VERIFY: npm run build green; banner renders identically (findLoopPosition now imported from match.js); matchLoopToProgression rotation-invariant + quality tie-break (smoke: ii–V–I & its rotation → jazz-251-major rot 0/2; minor 251 → jazz-251-minor; chromatic → no match)
L-01b	Derived theory for Roadmap: add guideTones(chordRoot,quality) (3rd & 7th pcs), voiceLeadingPairs(chordA,chordB) (7→3 / nearest-tone rails), and default soloScale(quality,mode) (Mixo/dom7, Dorian/m7, Ionian/maj7…) to theory.js — additive exports only	engineering	done	M-01	src/lib/theory.js	pure functions, unit-sane (ii–V–I in C → C→B, F→E rails); reuses existing getChordTones; build green; no existing export changed
L-02	JamGuide.jsx panel shell: mounts last in App.jsx, reads kb/index.js, instrument+style tabs from registry, collapsed header → ~70vh; receives live loop + position props	engineering	done	L-01	src/components/JamGuide.jsx, src/App.jsx	panel renders, tabs from KB, matched progression or fallback; build green
D-01	RoadmapTrack.jsx — the heart: horizontal stations (loop chords) with guide-tone lanes (3rd/7th dots), solo-scale label, voice-leading rails between stations, playhead + beat grid, lookahead highlight on the next station	design	done	L-01, L-01b	src/components/RoadmapTrack.jsx	renders a real ii–V–I & a 12-bar blues from KB; lanes computed from guideTones/voiceLeadingPairs/soloScale; design tokens; AA contrast
D-01b	ChordDiagram.jsx — secondary per-station voicing thumbnail (movable rootStr+offsets, open frets+onlyRoot), key-aware fret placement, tap-to-enlarge	design	done	L-01	src/components/ChordDiagram.jsx	renders any KB guitar shape in any key; chord-tone colour tier; compact thumbnail + enlarged states
D-02	Roadmap assembly & live polish in JamGuide.jsx: place RoadmapTrack + thumbnails, animate playhead against BPM/onset, narrow-viewport reflow, tap-station → fretboard guide tones	design	done	L-02, D-01, D-01b	src/components/JamGuide.jsx (assembly/styling), tailwind.config.js	playhead tracks position; reflows on narrow; keyboard-reachable; AA contrast
P-01	Gospel guitar KB cell	content	done	—	src/data/kb/gospel/**, src/data/kb/index.js	5 progressions × 2 plays, validator green (run /kb-expand)
P-02	Pop guitar KB cell	content	ready	P-01	src/data/kb/pop/**, src/data/kb/index.js	5 progressions × 2 plays, validator green
H-01	README reframe: lead with the learning-platform vision (detect → guide → learn), screenshot/gif placeholder, link GOAL.md + docs/agents/	community	done	—	README.md	README states the dual vision; links resolve
H-02	CONTRIBUTING.md + issue templates: the data-contract path so a musician can PR a style without coding (point at src/data/kb/SCHEMA.md)	community	ready	H-01	CONTRIBUTING.md, .github/ISSUE_TEMPLATE/**	a non-coder can follow "add a style"; /kb-expand documented as the assisted path
C-01	Smoke-test harness: a scripts/smoke.mjs that imports kb/index.js + runs the matcher on sample loops, wired alongside validate-kb.mjs	quality	ready	L-01	scripts/smoke.mjs	catches a broken matcher/registry before merge; documented in PROTOCOL gate

Critic (C-) reviews every L-/D-/P-/H- task as it reaches in-review — those reviews are the gate, not separate ledger rows, except where new test infra is itself the deliverable (e.g. C-01).

GATE 2026-06-15 (Critic) · L-01 PASS — build green, validator green (8 styles/40 progs/80 plays). findLoopPosition extracted byte-identical (verified by diff, no semantic change). matchLoopToProgression verified rotation-invariant with quality tie-break: [Dm7,G7,Cmaj7]→jazz-251-major rot 0; rotation [G7,Cmaj7,Dm7]→ rot 2; [Dm7b5,G7,Cm7]→jazz-251-minor (tie-break works); chromatic→clean {matched:false}. rotation index correctly points at the loop slot aligning with KB degrees[0]. match.js holds only matching/position logic + a small local chord-root parser (theory.js exposes no pc helper — acceptable). Note (non-blocking): banner refactor also adds onChordClick click affordances — beyond a pure extract but already wired to setSelectedChord/ChordDetailModal in App.jsx and behaviour-preserving for findLoopPosition. Minor: match.js uses extensionless import … from './theory' (works under Vite; matches existing education.js convention). GATE 2026-06-15 (Critic) · L-01b PASS — build green. theory.js diff is purely additive (zero - lines; no existing export touched). Verified by running the real functions: ii–V–I in C → Dm7→G7 = C→B (−1) and G7→Cmaj7 = F→E (−1) rails (plus intentional 0-semitone common-tone rails). guideTones triad fallback flags hasSeventh:false and uses the 5th. soloScale defaults sane: dom7→mixolydian, min7→dorian, maj7→major(ionian), half_dim→locrian, dom7/minor→phrygian-dominant. Functions are pure and reuse CHORD_TYPES/SCALES. GATE 2026-06-15 (Critic) · L-02 PASS — build green; validator green (8 styles/40 progs/80 plays). 🚨 Audio contract INTACT: git diff HEAD -- src/App.jsx is +10 lines, zero deletions — only the import JamGuide line and the <JamGuide …/> mount (placed last, after the tuner block). handleNote/handleChroma/handleOnset lines do not appear anywhere in the diff; no useCallback dep, ref-sync useEffect, or AudioCapture prop was touched. Black-screen/infinite-restart risk avoided. All 5 props passed (detectedProgression, effectiveKey, chordHistory, bpm, currentChord) exist in App scope. Tabs derive from the KB registry (instrument availability from style.instruments keys, style labels from meta.label); matched-progression vs. dashed-fallback both render. Disabled instrument tabs marked "soon" with disabled + title. GATE 2026-06-15 (Critic) · D-01 PASS — RoadmapTrack renders from props only (pure/presentational). Verified against the real KB: guide-tone honesty confirmed by running guideTones — C-major triad returns hasSeventh:false, secondary anchor = the 5th (pc 7), and the Station labels it "5th" not "7th" (seventhKind gate at line 113). The headline rail picks voiceLeadingPairs(...)[0] = the 7→3: Dm7→G7 ⇒ C→B (−1), G7→Cmaj7 ⇒ F→E (−1). BeatGrid station-start indexing is canonical-order-consistent with the stations array; playhead pct clamps at 0 when position=-1. Tokens used; aria-current, role=progressbar + aria-valuetext, focus rings present. Malformed/empty progression → graceful "no loop to map" card, no crash. GATE 2026-06-15 (Critic) · D-01b PASS — ChordDiagram movable base-fret formula verified independently: E-shape A7 → fret 5 ✓ (rootStr 6, rootPc 9: ((9−4)%12)=5); A-shape C → fret 3 ✓; open-string root → octave barre (12), a sane degradation. Root-tone coloured in accent tier (isRoot → #a855f7), non-root dots light-gray (AA on dark board). Both thumb/full sizes; full adds finger numbers + label. Undefined/unplaceable shape (root > fret 15 or !shape) → graceful "—" placeholder, no crash — covers the empty-thumbnail path. Open vs movable forms both handled. GATE 2026-06-15 (Critic) · P-01 PASS — validator green: ✓ KB valid — 9 style(s), 45 progressions, 90 plays (gospel now included); npm run build green (gospel imported by kb/index.js, 87 modules, built in 5.65s). Schema: 5 progressions × 2 plays = 10 plays, all ids gospel--prefixed, rn/qualities/bars all length-consistent with degrees, qualities all in CHORD_TYPES (min7/dom7/maj7/maj/add9/sus4/dim7). No duplicate id across all 45. Registered in index.js mirroring the other 8 styles (no broken import). Voicings hand-verified (independent pc computation matching the validator's): SHELL_6.maj7 → {0,11,4}=R-7-3 ✓; SUS4_5 → {0,5,7}=R-4-5 ✓; DIM7_5 → {0,6,9,3}=R-♭5-𝄫7-♭3 symmetric ✓; ADD9_6 → {0,2,4,7} full add9 (9th present) ✓; MIN9_5 → {0,2,3,7,10} full min9 ✓ — confirms the validator genuinely exercises these shapes via checkGuitarShape. Theory sound: backdoor ♭VII7=pc10 rises a whole step to I; #iv°7=pc6 passing chord; 6-2-5-1 + plagal IV-I Amen tag; cascading cycle-of-dominants all correctly spelled. Authenticity honest: attributions hedged appropriately ("traditional gospel turnaround", "reharmonized", "Every Praise … vamp feel", "e.g. Tenderly bars 5-7" as a back-door reference) — no claim that a specific recording uses an exact voicing; no music-theory error in any tip (Dorian-over-min7, Mixo-over-dom7, sus-non-resolution advice all correct). Non-blocking nit: a few shape comments list tones in interval order, not low-to-high string order (e.g. MAJ9_6 "R–3–7–9" sounds R-9-3-7) — labeling nicety, all tones present and correctly spelled; not a defect. GATE 2026-06-15 (Critic) · H-01 PASS — every relative link resolves on disk: GOAL.md, CLAUDE.md, src/data/kb/SCHEMA.md, src/data/kb/jazz/ (dir), docs/agents/ + ROSTER/PROTOCOL/LEDGER all exist; CONTRIBUTING.md is correctly referenced as "coming (tracked as task H-02)" and does NOT exist on disk — honest, not a dead live-link. Every command real: electron:dev, dev, electron:build:win|mac|linux all in package.json; scripts/validate-kb.mjs exists. No frontend/ path remains; build output dir stated as release/ matches electron-builder directories.output: "release". git clone URL whattheflat/whattheflat.git matches actual origin. Honesty verified: gospel described as "landing next" (not shipped, still in-review at review time); Piano/bass packs, Progression Builder, detection-powered drills all under In progress, not today; Roadmap Jam Guide listed as working-today (true — D-02 passed, MVP live). Leads with detect → guide → level up; links GOAL.md + docs/agents/. No overstatement found. GATE 2026-06-15 (Critic) · D-02 PASS — the load-bearing integration is correct. Independent rotation check: canonicalPos = ((position − rotation) % n + n) % n translates a findLoopPosition index (which is into the detected loop) into the KB-canonical station RoadmapTrack/stationVoicings render. Worked a rotated [ii V I VI] of KB [I VI ii V] (rotation=2, n=4): playhead@detected-idx1(V)→canonical 3(V), @2(I)→0(I), @3(VI)→1(VI), @0(ii)→2(ii) — NOW lands on the chord actually playing. ✓ rootPc parity confirmed: thumbnail rootPc and RoadmapTrack station root are byte-identical (((keyRoot+deg)%12)+12)%12, and keyInfo.root (a note name, e.g. detectKey→"F#") is converted once via chordRootPC → pc, guarded >=0. stationVoicings chords[i] aligns 1:1 with degrees[i] (canonical). Auto-scroll is prop-driven off position (no rAF on the audio thread). Reflows (flex-wrap/sm:flex-nowrap), keyboard-reachable, AA contrast. NO_MATCH path → dashed fallback, never empty/crash. Non-blocking deferral: the DoD's "tap-station → fretboard guide tones" cross-link and tailwind.config.js edit were not delivered — the implementation cross-links via an inline enlarged ChordDiagram instead (flagged in-code as deferred). Panel is fully functional without it; recommend Maestro file the fretboard cross-link as a phase-2 follow-up.

---

Backlog (future sprints)

• Jam Guide phase 2: MiniPiano.jsx + piano recipe resolver (unblocks piano packs); bass pattern renderer.
• Content: piano packs (jazz → gospel → neo-soul first), then bass packs (blues → jazz → funk first) — see docs/kb-backlog.md.
• Jam Guide phase-2 follow-up (D-03, Luthier+Muse): tap a Roadmap station → highlight that chord's guide tones on the main Fretboard (deferred from D-02: needs selected-station state lifted into App.jsx without disturbing the audio-callback ref contract). Build-green + audio-contract gate required.
• Learning features (Professor + Luthier): drills tab seeded from docs/learn-curriculum.md; target-note highlighting; ear-training quiz on own chord history; pocket report from the onset pipeline.
• Progression Builder (GOAL G3): key-relative palette, drag-reorder, Nashville-number toggle, voicing alternatives.
• Platform (Herald): GitHub Pages docs site; "you're playing the Creep progression" engagement hook; contributor leaderboard for styles added.

---

Iteration log

(Maestro appends one line per completed iteration: <date> · <task ids done> · <next>.)

• 2026-06-14 · done: M-01 · in-review (awaiting user pick): D-00a/b/c viz concepts · next: D-SEL (user chooses) → then L-01/D-01/D-02 implement chosen concept
• 2026-06-15 · done: D-00a/b/c, D-SEL (Roadmap chosen), L-01 (match.js + banner refactor), L-01b (guideTones/voiceLeadingPairs/soloScale) — Critic PASS both · next: L-02 (JamGuide shell) → D-01 (RoadmapTrack) ‖ D-01b (ChordDiagram)
• 2026-06-15 · done: L-02 (JamGuide shell + App mount), D-01 (RoadmapTrack), D-01b (ChordDiagram), D-02 (assembly + playhead rotation + thumbnails) — Critic PASS all 4, audio contract intact (App.jsx +10/−0) · Roadmap Jam Guide MVP is live & builds green · next: D-03 (fretboard cross-link, backlog) ‖ P-01 (gospel content) ‖ H-01 (README reframe)
• 2026-06-15 · done: P-01 (gospel guitar pack — 5 progs × 2 plays, validator 9 styles/45/90), H-01 (README reframed as learning platform, stale frontend/ paths fixed) — Critic PASS both · next ready: P-02 (pop pack) ‖ H-02 (CONTRIBUTING) ‖ C-01 (smoke harness) ‖ D-03 (fretboard cross-link)