docs(05-02): complete bank-decoupling plan — SUMMARY, STATE, ROADMAP updated

.planning/ROADMAP.md

@@ -23,7 +23,7 @@ Full details: `.planning/milestones/v1.0-ROADMAP.md`
 
 **Milestone Goal:** Users can customize how traffic sounds via a TOML config file — setting custom frequencies, waveform types, and their own classification rules with named sounds.
 
-- [ ] **Phase 5: Waveform Types and Bank Decoupling** - Internal refactors establishing waveform enum and injectable bank signature
+- [x] **Phase 5: Waveform Types and Bank Decoupling** - Internal refactors establishing waveform enum and injectable bank signature (completed 2026-03-26)
 - [ ] **Phase 6: Config Package and Sound Overrides** - TOML loading, auto-discovery, partial merge, and frequency/waveform overrides wired end-to-end
 - [ ] **Phase 7: Custom Rules and Print-Config** - User-defined classification rules and --print-config UX
 
@@ -37,11 +37,11 @@ Full details: `.planning/milestones/v1.0-ROADMAP.md`
   1. User can set a traffic class to square, sawtooth, or triangle waveform and hear a tonally distinct sound with no audible aliasing or buzzing artifacts
   2. Sine waveform continues to produce the same output as v1.0 — no regression
   3. The synthesis bank builds layers from a passed-in config map rather than a hardcoded class list
-**Plans:** 1/2 plans executed
+**Plans:** 2/2 plans complete
 
 Plans:
 - [x] 05-01-PLAN.md — Waveform types: WaveformType enum, WaveformPresetHarmonics, NewLayer resolution
-- [ ] 05-02-PLAN.md — Bank decoupling: NewBank injected config map, dynamic GainPerLayer, test updates
+- [x] 05-02-PLAN.md — Bank decoupling: NewBank injected config map, dynamic GainPerLayer, test updates
 
 ### Phase 6: Config Package and Sound Overrides
 **Goal**: Users can create a TOML config file to override frequency and waveform per traffic class, with auto-discovery, partial override semantics, and clear validation errors
@@ -74,6 +74,6 @@ Plans:
 | 2. Audio Synthesis Engine | v1.0 | 3/3 | Complete | 2026-03-26 |
 | 3. Pipeline Integration and MVP | v1.0 | 2/2 | Complete | 2026-03-26 |
 | 4. Power User Features | v1.0 | 2/2 | Complete | 2026-03-26 |
-| 5. Waveform Types and Bank Decoupling | v1.1 | 1/2 | In Progress|  |
+| 5. Waveform Types and Bank Decoupling | v1.1 | 2/2 | Complete   | 2026-03-26 |
 | 6. Config Package and Sound Overrides | v1.1 | 0/? | Not started | - |
 | 7. Custom Rules and Print-Config | v1.1 | 0/? | Not started | - |

.planning/STATE.md

@@ -2,15 +2,15 @@
 gsd_state_version: 1.0
 milestone: v1.1
 milestone_name: Custom Sound Mappings
-status: executing
+status: verifying
-stopped_at: Completed 05-01-PLAN.md
+stopped_at: Completed 05-02-PLAN.md
-last_updated: "2026-03-26T16:35:44.333Z"
+last_updated: "2026-03-26T16:39:38.288Z"
 last_activity: 2026-03-26
 progress:
   total_phases: 3
-  completed_phases: 0
+  completed_phases: 1
   total_plans: 2
-  completed_plans: 1
+  completed_plans: 2
   percent: 0
 ---
 
@@ -27,7 +27,7 @@ See: .planning/PROJECT.md (updated 2026-03-26)
 
 Phase: 05 (waveform-types-and-bank-decoupling) — EXECUTING
 Plan: 2 of 2
-Status: Ready to execute
+Status: Phase complete — ready for verification
 Last activity: 2026-03-26
 
 Progress: [░░░░░░░░░░] 0%
@@ -51,6 +51,7 @@ Progress: [░░░░░░░░░░] 0%
 
 **Recent Trend:** Stable
 | Phase 05 P01 | 3min | 2 tasks | 3 files |
+| Phase 05 P02 | 4 | 2 tasks | 4 files |
 
 ## Accumulated Context
 
@@ -61,6 +62,8 @@ Progress: [░░░░░░░░░░] 0%
 - [v1.1 Roadmap]: User class name collision with built-in TrafficClass strings is an unresolved design question — decide before coding Phase 7 (treat as override vs. reject as ambiguous)
 - [Phase 05]: FreqConfig struct uses named field syntax for ClassFreqConfigs entries (required by WaveformType addition)
 - [Phase 05]: WaveformType zero value is WaveformCustom — all 14 existing ClassFreqConfigs entries retain hand-tuned harmonics without modification
+- [Phase 05]: NewBank accepts injected config map instead of reading ClassFreqConfigs global — injection seam for Phase 6 config loading
+- [Phase 05]: gainPerLayer computed as 1.0/float64(len(cfgs)) — correct for any class count, no-clip guarantee preserved
 
 ### Pending Todos
 
@@ -72,6 +75,6 @@ None.
 
 ## Session Continuity
 
-Last session: 2026-03-26T16:35:44.326Z
+Last session: 2026-03-26T16:39:38.281Z
-Stopped at: Completed 05-01-PLAN.md
+Stopped at: Completed 05-02-PLAN.md
 Resume file: None

.planning/phases/05-waveform-types-and-bank-decoupling/05-02-SUMMARY.md

@@ -0,0 +1,80 @@
+---
+phase: 05-waveform-types-and-bank-decoupling
+plan: "02"
+subsystem: synth
+tags: [bank, decoupling, dynamic-gain, injection-seam, refactor]
+dependency_graph:
+  requires: [05-01]
+  provides: [NewBank injected config map, gainPerLayer dynamic computation]
+  affects: [synth/bank.go, encode/mp3.go, synth/bank_test.go, synth/config_test.go]
+tech_stack:
+  added: []
+  patterns: [dependency injection, dynamic gain scaling, config map injection]
+key_files:
+  created: []
+  modified:
+    - synth/bank.go
+    - encode/mp3.go
+    - synth/bank_test.go
+    - synth/config_test.go
+decisions:
+  - "NewBank now accepts (tau float64, cfgs map[classify.TrafficClass]FreqConfig) — no global state dependency"
+  - "gainPerLayer computed as 1.0/float64(len(cfgs)) so any N-class config auto-scales to avoid clipping"
+  - "RenderWindow iterates b.layers directly in both loops — no classify.AllClasses() dependency"
+  - "encode/mp3.go passes synth.ClassFreqConfigs as default — v1.0 behavior preserved exactly"
+metrics:
+  duration: "~4 min"
+  completed_date: "2026-03-26"
+  tasks: 2
+  files: 4
+requirements:
+  - WAVE-01
+  - WAVE-02
+---
+
+# Phase 5 Plan 02: Bank Decoupling and Dynamic GainPerLayer Summary
+
+OscillatorBank decoupled from global ClassFreqConfigs via injected config map, with gainPerLayer computed dynamically as 1/N so any class count produces correct no-clip mixing.
+
+## What Was Built
+
+- **`OscillatorBank.gainPerLayer float64`** field added to struct — computed at construction time as `1.0 / float64(len(cfgs))`
+- **`NewBank(tau float64, cfgs map[classify.TrafficClass]FreqConfig)`** — new two-argument signature replaces global ClassFreqConfigs dependency; iterates cfgs map directly to create layers
+- **`RenderWindow` UpdateTarget loop** — refactored from `classify.AllClasses()` iteration to `for class, layer := range b.layers`, making it work for any config map
+- **`RenderWindow` render loop** — refactored to use `b.gainPerLayer` (instance field) instead of `GainPerLayer` constant, enabling correct scaling for non-14 class counts
+- **`encode/mp3.go` call site** — updated to `synth.NewBank(1.0, synth.ClassFreqConfigs)`, preserving v1.0 behavior exactly
+- **Updated test suite** — all 7 existing `NewBank` calls updated to two-argument form; two new tests added: `TestNewBankDynamicGain` (verifies 1/3 gain for 3-class config) and `TestNewBankCustomConfigNoClip` (verifies no-clip with 2-class config)
+- **`TestNumLayersMatchesAllClasses`** updated to assert `len(synth.ClassFreqConfigs) == len(classify.AllClasses())` without depending on `synth.NumLayers`
+
+## Tasks Completed
+
+| Task | Description | Commit | Files |
+|------|-------------|--------|-------|
+| 1 | Decouple NewBank and fix GainPerLayer | 43307c3 | synth/bank.go, encode/mp3.go |
+| 2 | Update tests for new NewBank signature and dynamic gain | b2b5ab6 | synth/bank_test.go, synth/config_test.go |
+
+## Verification
+
+- `go test ./synth/... ./encode/... -v`: 44 tests, all pass (41 existing + 2 new bank tests)
+- `go test ./...`: all 6 packages pass (aggregate, capture, classify, cmd, encode, synth)
+- `go vet ./...`: clean
+- `go build ./...`: clean
+- `classify.AllClasses()` not referenced in bank.go (confirmed via grep)
+- No single-argument `NewBank(` calls remain in production or test code
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Known Stubs
+
+None — all decoupling logic is fully implemented and wired.
+
+## Self-Check: PASSED
+
+- synth/bank.go: FOUND (verified by go build)
+- encode/mp3.go NewBank call updated: FOUND (synth.NewBank(1.0, synth.ClassFreqConfigs))
+- synth/bank_test.go TestNewBankDynamicGain: FOUND (verified by go test)
+- synth/bank_test.go TestNewBankCustomConfigNoClip: FOUND (verified by go test)
+- synth/config_test.go TestNumLayersMatchesAllClasses updated: FOUND
+- Commits 43307c3, b2b5ab6: both present in git log