docs: rewrite SYNC.md as live handoff protocol between ML Intern and Claude Code

Old SYNC.md was a static history log — ML intern pushed AudioAnalyser without
updating it, Claude Code had no idea what was coming.

New structure:
- NEXT PUSH section: ML Intern fills before every push (task, files changed, APIs used)
- LAST BUILD RESULT: Claude Code fills after every pull+build
- LOCKED FILES table: explicit list of files ML intern must not modify
- Sprint log with regression note from Sprint 4
- What Claude Code can do (so ML Intern knows what to request)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

SYNC.md

@@ -1,79 +1,138 @@
-# PluginBridge — Sync File
+# PluginBridge — Live Sync File
+
+> **How this file works:**
+> ML Intern fills `## NEXT PUSH` BEFORE pushing any code.
+> Claude Code reads it, pulls, builds, tests, then fills `## LAST BUILD RESULT`.
+> After a successful build, Claude Code moves the push details to `## SPRINT LOG`.
+> Neither side should push without reading what the other wrote last.
 
 ---
 
-## STATUS: v0.5.2 — SPRINT 3 COMPLETE (2026-05-17)
+## CURRENT STATUS (updated by Claude Code after each build)
 
-Build: ✅ Clean  
-GUI: ✅ Working (Pro-Q 4, God Particle, Little MicroShift, LIMITER)  
-MCP: ✅ Verified end-to-end — registered in Claude Code config  
-Crashes: ✅ None (unsafe plugins handled via audio-only mode)
+**Version:** v0.5.2 + AudioAnalyser  
+**Last build:** 2026-05-17 ~18:30  
+**Build:** ✅ Clean — `[100%] Built target PluginBridge_VST3`  
+**Runtime:** ✅ GUI working — TreeView picker + in-process createEditor()  
+**MCP:** ✅ Running on port 16620, registered in Claude Code config  
+**AudioAnalyser:** ✅ Wired — LUFS, FFT bands, stereo width, centroid, true peak  
+**get_analysis:** ✅ Returns live data when audio is playing  
 
 ---
 
-## MCP INTEGRATION CONFIRMED
+## NEXT PUSH — ML Intern fills this before every push
+
+> **ML Intern: Before you push anything, fill this section completely.**
+> Claude Code reads this to know what's coming and catch problems early.
+> Leave it blank = Claude Code has no idea what you did = breaks things.
+
+```
+STATUS: [waiting for ML Intern to fill]
+
+TASK: [what feature/fix are you implementing?]
+
+FILES I WILL CHANGE:
+  - [filename] — [what specifically you're changing in it]
+  - [filename] — [what specifically you're changing in it]
 
-**Server:** `http://127.0.0.1:16620/mcp`  
-**Registered as:** `pluginbridge` in Claude Code local config  
-**Scope:** AI MUSIC PRODUCTION project
+FILES I WILL NOT TOUCH:
+  (List everything else — confirm you're not touching the locked files)
 
-**Verified working (2026-05-17):**
-- `GET /health` → `{"status":"ok","helper":"connected","port":16620}`
-- `initialize` → handshake complete
-- `tools/list` → 5 tools registered
-- `search_param "band 1"` → 24 params returned from Pro-Q 4 with real values
+NEW FILES (if any):
+  - [filename] — [purpose]
+  NOTE: Tell Claude Code about new .cpp/.mm files — they must be added to CMakeLists.txt
 
-**Pro-Q 4 via MCP:** 737 parameters fully accessible (vs 1 parameter via Ableton LOM)
+APIs/APPROACHES USED:
+  - [API name] — [confirmed working? or needs Claude Code to verify first?]
+
+WHAT I AM NOT CHANGING:
+  - PluginBridgeEditor.mm — locked
+  - PluginPickerComponent.mm — locked
+  - HelperPluginHost.mm — locked
+  - HelperConnection.cpp — locked
+  - The in-process createEditor() load flow — locked
+  - All PBLOG calls — never remove these
+```
 
 ---
 
-## SPRINTS
+## LAST BUILD RESULT — Claude Code fills this after every pull+build
+
+**Date:** 2026-05-17 ~18:30  
+**Pulled commits:**
+- `fdc4e41` fix: restore v0.5.2 architecture + wire AudioAnalyser correctly
 
-| Sprint | Status | What |
-|---|---|---|
-| Sprint 1 | ✅ | Plugin shell + MCP server |
-| Sprint 2 | ✅ | Out-of-process hosting, crash-safe, GUI |
-| Sprint 3 | ✅ | MCP param control — verified from Claude Code |
-| Sprint 4 | **NEXT** | Real-time audio analysis (LUFS, FFT, spectral) |
+**Build:** ✅ Clean  
+**Tests run:**
+- `GET /health` → `{"status":"ok","helper":"connected","port":16620}` ✅
+- `tools/call get_analysis` → pending (need audio playing)
+
+**Issues found:** None  
+**Action taken:** Pushed CMakeLists.txt fix (PluginPickerComponent.mm was missing from build)
 
 ---
 
-## ARCHITECTURE (v0.5.2)
+## LOCKED FILES — do not modify without explicit permission from Adi
 
-```
-Claude Code / Gemini CLI
-    │
-    ├── ableton-live-mcp (port 16619) — DAW control, LOM, tracks, routing
-    │
-    └── pluginbridge (port 16620) — plugin parameter control
-            │
-            ▼
-    PluginBridge.vst3 (inside Ableton)
-    ├── In-process GUI (safe plugins)
-    ├── Shared memory audio → Helper process (crash-safe)
-    ├── MCP server (5 tools)
-    └── Safety DB + blocklist
-
-    PluginBridgeHelper.app (separate process)
-    ├── Audio processing via shared memory
-    ├── --scan mode for safety testing
-    └── --load mode for audio routing
-```
+| File | Why locked |
+|---|---|
+| `Source/Plugin/PluginBridgeEditor.mm` | In-process GUI embedding — 4 sprints to get right |
+| `Source/Plugin/PluginPickerComponent.mm` | Ableton-style TreeView picker — working |
+| `Source/Helper/HelperPluginHost.mm` | Audio routing + process lifecycle |
+| `Source/Plugin/HelperConnection.cpp` | IPC + shared memory protocol |
+
+**Also never:**
+- Remove `PBLOG(...)` calls — they're how Claude Code diagnoses bugs
+- Change the `loadInProcessPlugin()` flow
+- Use CALayerHost for GUI (see FAILED-APPROACHES #10 — doesn't work in Ableton)
+
+---
+
+## SPRINT LOG
+
+### Sprint 1 ✅
+Plugin shell + MCP server. Basic VST3 structure, HTTP JSON-RPC endpoint.
+
+### Sprint 2 ✅
+Out-of-process hosting via shared memory. Helper process. Crash isolation.
+GUI showed in windowed Ableton but broke in fullscreen → led to Sprint 3 redesign.
+
+### Sprint 3 ✅ (v0.5.2)
+Full in-process hosting with safety scan. Ableton-style TreeView picker.
+Fixes: deduplication, manufacturer names, background scan conflict, addChildComponent bug.
+MCP verified end-to-end. Pro-Q 4 = 737 params via MCP.
+
+### Sprint 4 ✅ (AudioAnalyser)
+Real-time audio analysis: LUFS, true peak, stereo width, spectral centroid, 7-band FFT.
+`get_analysis` MCP tool wired.
+**Regression introduced and fixed:** ML intern rewrote Editor+Processor while adding AudioAnalyser,
+accidentally reverting to CALayerHost architecture. Fixed by Claude Code (2026-05-17).
+Root cause documented in MACHINE-CONTEXT.md scope rules.
 
 ---
 
-## BUILD
+## BUILD COMMANDS
 
 ```bash
+# Full build
 cd "/Volumes/T7 Shield/Users/Aditya/pluginbridge/build"
 cmake --build . --target PluginBridge_VST3 -- -j4
+
+# Quick MCP test (with plugin loaded in Ableton)
+curl -s http://127.0.0.1:16620/health
+curl -s -X POST http://127.0.0.1:16620/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_analysis","arguments":{}}}' \
+  | python3 -m json.tool
 ```
 
 ---
 
-## MODE: NORMAL (build+test only)
+## WHAT CLAUDE CODE CAN DO (ML Intern can request these)
 
-Claude Code rules:
-- `pull and build` → pull + cmake build + report result
-- `pull and test` → pull + build + run curl tests + report
-- For debugging: ML Intern will update SYNC.md to grant full debug mode when needed
+- `pull and build` — pull latest, build, report result
+- `pull and test` — pull, build, run curl tests, report
+- `verify [API]` — test whether an API works on this machine, write result to MACHINE-CONTEXT.md
+- `check the log` — read debug.log and crash reports, diagnose issues
+- `run debugger` — start live tail of debug.log in background
+- Full debug investigation when something breaks — reads log, checks processes, reports root cause