backbeat: add module sources

TEMPO-RECOMMENDATIONS.md

@@ -0,0 +1,125 @@
+# BACKBEAT Tempo Recommendations
+
+## Why Slower Beats Make Sense for Distributed Systems
+
+Unlike musical BPM (120+ beats per minute), distributed task coordination works better with much slower tempos. Here's why:
+
+### Recommended Tempo Ranges
+
+**Development & Testing: 1-2 BPM**
+- 1 BPM = 60-second beats (1 minute per beat)
+- 2 BPM = 30-second beats (30 seconds per beat)  
+- Perfect for debugging and observing system behavior
+- Plenty of time to see what agents are doing within each beat
+
+**Production: 5-12 BPM**  
+- 5 BPM = 12-second beats
+- 12 BPM = 5-second beats
+- Good balance between responsiveness and coordination overhead
+- Reasonable for most distributed task processing
+
+**High-Frequency (Special Cases): 30-60 BPM**
+- 30 BPM = 2-second beats  
+- 60 BPM = 1-second beats
+- Only for very short-duration tasks
+- High coordination overhead
+
+### Window Sizing Examples
+
+With **2 BPM (30-second beats)** and **4 beats per window**:
+- Each window = 2 minutes
+- Downbeats every 2 minutes for secret rotation, rollups, reviews
+- Agents report status every 30 seconds
+- Reasonable time for meaningful work between status updates
+
+With **12 BPM (5-second beats)** and **8 beats per window**:
+- Each window = 40 seconds  
+- Downbeats every 40 seconds
+- Agents report every 5 seconds
+- More responsive but higher coordination overhead
+
+### Why Not 120+ BPM?
+
+**120 BPM = 500ms beats** - This is far too fast because:
+- Agents would report status twice per second
+- No time for meaningful work between beats
+- Network latency (50-100ms) becomes significant fraction of beat time
+- High coordination overhead drowns out actual work
+- Human operators can't observe or debug system behavior
+
+### Beat Budget Examples
+
+With **2 BPM (30-second beats)**:
+- `withBeatBudget(4, task)` = 2-minute timeout
+- `withBeatBudget(10, task)` = 5-minute timeout
+- Natural timeout periods that make sense for real tasks
+
+With **120 BPM (0.5-second beats)**:
+- `withBeatBudget(10, task)` = 5-second timeout  
+- Most meaningful tasks would need budget of 100+ beats
+- Defeats the purpose of beat-based timeouts
+
+## BACKBEAT Default Settings
+
+**Current Defaults (Updated):**
+- Pulse service: `1 BPM` (60-second beats)
+- Window size: `8 beats` = 4 minutes per window
+- Min BPM: `1` (60-second beats for debugging)
+- Max BPM: `24` (2.5-second beats for high-frequency systems)
+
+**Configuration Examples:**
+
+```bash
+# Development - very slow for debugging
+./pulse -bpm 1 -bar 4    # 60s beats, 4min windows
+
+# Production - balanced 
+./pulse -bpm 5 -bar 6    # 12s beats, 72s windows
+
+# High-frequency - only if needed
+./pulse -bpm 24 -bar 10  # ~2.5s beats, 25s windows
+```
+
+## Integration with CHORUS Agents
+
+When CHORUS agents become BACKBEAT-aware, they'll report status on each beat:
+
+**With 2 BPM (30s beats):**
+```
+T+0s:   Agent starts task, reports "executing", 10 beats remaining
+T+30s:  Beat 1 - reports "executing", 9 beats remaining, 20% progress
+T+60s:  Beat 2 - reports "executing", 8 beats remaining, 40% progress
+T+90s:  Beat 3 - reports "review", 0 beats remaining, 100% progress
+T+120s: Downbeat - window closes, reverb generates BarReport
+```
+
+**With 120 BPM (0.5s beats) - NOT RECOMMENDED:**
+```
+T+0.0s: Agent starts task, reports "executing", 600 beats remaining  
+T+0.5s: Beat 1 - barely any progress to report
+T+1.0s: Beat 2 - still barely any progress
+... (598 more rapid-fire status updates)
+T+300s: Finally done, but coordination overhead was massive
+```
+
+## Performance Impact
+
+**Slower beats (1-12 BPM):**
+- ✅ Meaningful status updates
+- ✅ Human-observable behavior  
+- ✅ Reasonable coordination overhead
+- ✅ Network jitter tolerance
+- ✅ Debugging friendly
+
+**Faster beats (60+ BPM):**
+- ❌ Status spam with little information
+- ❌ High coordination overhead
+- ❌ Network jitter becomes significant
+- ❌ Impossible to debug or observe
+- ❌ Most real tasks need huge beat budgets
+
+## Conclusion
+
+BACKBEAT is designed for **distributed task coordination**, not musical timing. Slower beats (1-12 BPM) provide the right balance of coordination and efficiency for real distributed work.
+
+The updated defaults (2 BPM, 8 beats/window) give a solid foundation that works well for both development and production use cases.