Stage 3 — Expand + Master Plan

Stage 3 — Expand + Master Plan

> Final ranked, dependency-ordered execution plan for LUME creative engine maturation.
> Treat as PRODUCTION SYSTEM. Don't break what ships.
> Output of Evo3 Stage 3, Wave 9 of the LUME chain. 5 panes, 3 reel-critical + 2 parallel.
> Deadline: reel posted by 2026-05-09 EOD.

---

0. Don't-touch list (verbatim, propagate to every Codex pane briefing)

This list is enforced at the git pre-commit layer (P3 ships the hook). Treat any apparent need to violate it as an escalation signal, not a refactor opportunity.

• Wire format magic bytes: `LUME` (0x4C554D45), `LUMD` (0x4C554D44), `LUMF` (0x4C554D46), `LUMM` (0x4C554D4D), `LUMC`. Pinned byte-for-byte by `tests/test_wire_format_golden.py` (memory: Wave 4 Track I).
• 21 Unity component public APIs — additive only, no field renames or signature changes. Surface enumerated in `software/demo/unity/lume_pcloud/ARCHITECTURE.md` (memory: 2026-04-26 commit `e2089c56`).
• K11 NSSM service definitions in `software/demo/launchagents/k11/install-services.ps1`. Runtime Args may be parameter-flagged; service registration block stays as-is.
• Wave 8 commits not-pushed: `da8d1478`, `c5194f92`, `2a6e6b25`, `95387a02`, `8139a931`, `8fb6fe75`. Only Mohamed pushes after Mac4 verification.
• LUMF byte order in `audio_pub.py:send_lumf` — pinned by golden-bytes test.
• MotionMix repo proof-token model (commit `1ea8da7 feat(director): Phase 5a proof token model`) — read it before defining any director event payload; do not redefine its schema.
• Production system constraint — Mohamed runs all destructive operations manually. No Codex pane may `git push`, `launchctl unload && load`, `nssm remove`, or post to social media on Mohamed's behalf.

---

1. Single dependency graph (apps → consumers → wire format on edges)

                                  ┌────────────────────────────────────────────────┐
                                  │   MotionMixApp (iPhone — primary capture)      │
                                  │   ─ Vision body pose @ 30Hz                    │
                                  │   ─ CoreMotion @ 60Hz                          │
                                  │   ─ Echelon Rust FFI → 16D LIM-RPS, 128D vec   │
                                  │   ─ SAN MLX (135K, V5, 5408 pairs, val 0.028)  │
                                  │   ─ AudioEngine.swift (2110 ln, AVF + Rust)    │
                                  └─┬───────────┬──────────┬──────────┬────────────┘
                                    │           │          │          │
              [LUMM 772B :9702]──── │           │          │          └─── [JSON @100Hz]──┐
                            ─── ────┘           │          │                              │
                            │                   │          └─[StrudelWebEngine WK push]   │
                            │                   │                window.sanUpdate({...})  │
                            │                   │                                         │
                            │                   └─[onMixerBuffer PCM tap @86Hz]──┐        │
                            │                                                    │        │
                            │   ┌────────────────────────────────────────────────▼────────▼────────┐
                            │   │   *** P1 — LumfPublisher.swift (NEW, this week) ***               │
                            │   │   Hann FFT (pre-allocated) → 4 EQ bands + 8 MFCC + RMS +          │
                            │   │   centroid + flux onset → 84-byte LUMF                            │
                            │   └────────────────┬─────────────────────────────────────────────────┘
                            │                    │
                            │            [LUMF 84B :9701]
                            │                    │
                            │   ┌────────────────▼─────────────────────────────────────────────────┐
                            │   │   K11 NSSM: LUME-Audio (synthetic, fallback ONLY when             │
                            │   │   MotionMixApp heartbeat > 2s old — runtime --prefer-device flag) │
                            │   └────────────────┬─────────────────────────────────────────────────┘
                            │                    │
                            └────────────────────┴────────┐
                                                          │
                            ┌─────────────────────────────▼───────────────────────────────────────┐
                            │  Unity LUME (Wave 8 shipped) — K11 in pod, Mac4 mirror in P5         │
                            │  ─ LumeUdpReceiver: dispatches LUMM/LUMF/LUMD by magic byte           │
                            │  ─ 21 components (additive only)                                     │
                            │  ─ F2 panel + F12 calibration + auto-wire                            │
                            │  ─ K11 NSSM publishers: LUME-Mocopi (LUMM) / LUME-Audio (LUMF) /      │
                            │    LUME-Depth (LUMD on :9700)                                        │
                            └────────────┬───────────────────────────┬─────────────────────────────┘
                                         │                           │
                                  [VFX render to bar 1920×440]      [OSC out :9050 — 7 channels]
                                         │                           │
                                         │         ┌─────────────────▼─────────────────────────────┐
                                         │         │ *** P4 — OSCService.swift (bridge b) ***       │
                                         │         │   Bind :9050, decode 7 chans, route into       │
                                         │         │   ParamMapper.Extras (additive fields)         │
                                         │         └─────────────────┬─────────────────────────────┘
                                         │                           │
                                         │                  [bouncing/coreMotion/...]
                                         │                           │
                                         │         ┌─────────────────▼─────────────────────────────┐
                                         │         │ *** P4 — SANPipelineBridge.swift (bridge c) ***│
                                         │         │   SAN pattern @30Hz → setSANPattern() with     │
                                         │         │   confidence>0.6 + 750ms debounce + 16-bar     │
                                         │         │   minimum dwell                                 │
                                         │         └─────────────────────────────────────────────────┘
                                         │
                                  ┌──────▼────────────────────────────────┐
                                  │  *** P2 — record-unity-reel.sh ***    │
                                  │   NVENC capture 30s of LUME visual    │
                                  │   → Desktop/lume-reel-recordings/   │
                                  └──────┬────────────────────────────────┘
                                         │
   ┌─────────────────────────────────────▼──────────────────────────────────┐
   │  *** P2 — REEL-001 composite (ShootView ReelBuilderView) ***            │
   │   ─ ShootView stills (24-36 per 3 looks)                                │
   │   ─ MotionMix capture clips (3 × 10-15s)                                │
   │   ─ Unity LUME visual (≥1 shot)                                         │
   │   ─ AudioCaptureWriter WAV (engine-driven) OR Strudel-render fallback   │
   │   ─ ffmpeg transitions: dissolve, wiperight, circlecrop                 │
   │   ─ 9:16 1080×1920, ≤30s, ≤30MB                                         │
   └──────┬──────────────────────────────────────────────────────────────────┘
          │
   ┌──────▼─────────────────────┐
   │  Posted: IG Reels + TikTok │
   │  Deadline: 2026-05-09 EOD  │
   │  (Mohamed posts manually)  │
   └────────────────────────────┘

   Parallel non-blocking tracks:

   ┌─────────────────────────────────────────────────────────────────────────┐
   │ P3 — Wave 8 push readiness                                              │
   │  ─ tests/test_mocopi_synth.py flake fix (widen tolerance)               │
   │  ─ CHANGELOG.md (Waves 1-8)                                             │
   │  ─ MAC4-VERIFICATION-RUNBOOK.md (10-point smoke test)                   │
   │  ─ director-protocol.md (doc-only; impl deferred to Wave 9)             │
   │  ─ Pre-commit don't-touch hook (enforces section 0)                     │
   │  ─ Mohamed runs Mac4 smoke + pushes Mac1 main → origin/main             │
   └─────────────────────────────────────────────────────────────────────────┘

   ┌─────────────────────────────────────────────────────────────────────────┐
   │ P5 — Universal sled CAD + Mac4 launchd                                  │
   │  ─ lume-config.scad MAC_MINI_W/D/H constants                            │
   │  ─ lume-pod.scad pod_compute_sled(box=...) + pod_vents_compute(box=...)│
   │  ─ Mac4 launchd plists (3 services, mirror NSSM)                        │
   │  ─ Camera TCC grants on Mac4                                            │
   │  ─ pyorbbecsdk2 macOS arm64 wheel verification                          │
   │  ─ One test print of Mac mini sled (ASA on Elegoo Max)                  │
   └─────────────────────────────────────────────────────────────────────────┘

Wire format edges (verified from stage0):
- `MotionMix iPhone → Unity` via LUMM (772B, 27 bones, magic 0x4C554D4D, port 9702 — direct fleet path; or via mocopi when activated).
- `MotionMixApp iPhone → Unity` via LUMF (84B, magic 0x4C554D46, port 9701) — NEW PATH from P1.
- `K11 LUME-Depth (Femto Bolt) → Unity` via LUMD (716px raw depth, magic 0x4C554D44, port 9700).
- `Unity → MotionMixApp` via OSC (7 channels, port 9050) — NEW CONSUMER from P4.
- `MotionMixApp → StrudelWebEngine` via WKWebView JS bridge (window.sanUpdate at 10Hz, /san HTTP POST at 2Hz).
- `MotionMix iPhone → MotionMixDirector` via MJPEG (port 8081, existing).

---

2. Music-gen pipeline decision (final)

Per Stage 2 Step 2:

No new ML stack downloads. No MusicGen/AudioCraft/Riffusion/Stable Audio. The chain prompt's framing was misdirected; SAN is the in-house equivalent and outperforms any small open model on the user's actual data because it's been trained on the user's actual data.

First-bridge decision: (a) PCM → LUMF. Independent of HD1, director consolidation, CAD work. Highest reel-artifact value. Same code as P2's audio capture — one pane, two consumers.

---

3. Five Codex panes — final ranked plan

Each pane below has: focus, first task, success criterion, don't-touch list, dependencies, estimated hours, owner, status.

P1 — Bridge (a) PCM → LUMF (REEL-CRITICAL, P0)

• Focus: ship the device-side LUMF publisher so MotionMixApp's deployed audio becomes Unity's reactive audio source.
• Working dir: `Desktop/MotionMixApp/`
• First task: Create `MotionMixApp/Services/LumfPublisher.swift` (~180 lines).
• Use AudioEngine's existing pre-allocated FFT buffers (AudioEngine.swift:116-122 — DO NOT re-allocate).
• 4 EQ bands + 8 MFCC + RMS + centroid + onset-flux per LUMF spec (84 bytes).
• UDP broadcast on `:9701` to Tailscale K11 IP (configurable via `motionmix_lumf_target` UserDefault).
• Heartbeat write to `[home-path] Support/MotionMixApp/lumf-heartbeat.txt` for K11's `--prefer-device` flag.
• Register on AudioEngine's `onMixerBuffer` chain via additive consumer pattern (one-line refactor of AudioEngine's existing single-callback line into a `[MixerBufferConsumer]` array — done in P1's first commit, used by P2 immediately after).
• Second task: Swift golden-bytes test mirroring Python `tests/test_wire_format_golden.py`. `XCTAssertEqual` over 84 hand-built bytes. Cite Python golden as source of truth.
• Third task: Verify on K11 with `lume_packet_inspector.py` — must show LUMF rate ≥58 pkt/s in a 60s window when MotionMixApp is rendering audio.
• Success criterion:
• Swift golden-bytes test passes.
• 60s capture session shows ≥58 LUMF pkt/s on K11's `lume_packet_inspector.py`.
• Unity's F2 panel shows audio reactivity bound to MotionMixApp's actual PCM (visually distinct from synthetic — real audio has natural transient clusters at dance accents).
• K11 NSSM `LUME-Audio` cleanly yields when device heartbeat is < 2s old (ONE PowerShell-script-arg edit, not a service-registration edit).
• Don't-touch list (this pane): LUMF wire format byte order; Unity's LumeAudioFftReceiver public API; K11 NSSM service registration block (only Args on a separate read-from-file path).
• Dependencies: None.
• Estimated hours: 8-10 hours.
• Owner: Codex pane P1.
• Status: PENDING.

P2 — Reel-001 production (REEL-CRITICAL, P0)

• Focus: ship one publishable Reel that drives the engine end-to-end. The artifact that proves the engine is real.
• Working dirs: `Desktop/MotionMix/`, `Desktop/ShootView/`, `Desktop/MotionMixStills/`, `Desktop/lume-commerce/software/demo/`.
• First task: Write `Desktop/MotionMix/REEL-001-PRODUCTION-PLAN.md` (~150 lines). Concept, 3 looks, 3 motion concepts, shotlist, audio capture method, composite spec, platform deliverables (9:16 1080×1920, ≤30s, ≤30MB), brand voice notes, fallback plan.
• Second task: Write `MotionMixApp/Services/AudioCaptureWriter.swift` (~120 lines). Subset of P1's tap pattern — registers on `onMixerBuffer` (uses P1's `[MixerBufferConsumer]` array introduced in P1's first commit). Writes 30s rolling WAV stereo 48k/16-bit to `Application Support/MotionMixApp/audio-captures/`. Triggered from a debug menu in `Views/TransportBar.swift`.
• Third task: Write `software/demo/scripts/record-unity-reel.sh` (~80 lines). Launches Unity batch mode at K11 (or Mac4 once P5 ships), captures 30s LUME visual via NVENC (Windows) or ScreenCaptureKit (macOS), drops to `Desktop/lume-reel-recordings/`. Uses Wave 8's existing publishers; zero Unity changes.
• Fourth task (Day 3-4): Photoshoot. Three looks. iPad LUMM fallback for skeleton during motion clips. ShootView solo capture via RemoteControlView.
• Fifth task (Day 5-6): Composite via ShootView's ReelBuilderView. Audition SAN-driven audio vs Strudel-render fallback; pick best.
• Sixth task (Day 7): Caption + export. Mohamed posts manually.
• Success criterion:
• One Reel posted to Instagram + TikTok by 2026-05-09 EOD.
• Reel uses ShootView stills (≥3 looks).
• Reel uses MotionMix-captured motion clip (≥1).
• Reel uses Unity LUME visual (≥1 shot).
• Reel music is engine-driven (Echelon SAN OR Strudel-render captured via AudioCaptureWriter — both count). Licensed-track fallback flagged as "stretch missed" if invoked.
• ≥1 viewer comment about music or visual within 48h of post.
• Don't-touch list (this pane): ShootView's ReelBuilderView ffmpeg transition list (additive composites only); MotionMixApp public APIs (additive).
• Dependencies: P1 ships the consumer-array refactor; AudioCaptureWriter rides on it.
• Estimated hours: 6 hours scripting + 6 hours photoshoot + 4 hours composite + 1 hour caption/post = 17 hours over 5-7 days.
• Owner: Codex pane P2 (scripts/code) + Mohamed (photoshoot + post).
• Status: PENDING.

P3 — Wave 8 push readiness (REEL-CRITICAL, P0)

- Focus: take the work that's already done across the finish line. Tests pass, docs match reality, Mac4 verifies, Mohamed pushes.
- Working dir: `Desktop/lume-commerce/`, `Desktop/MotionMix/`.
- First task: Fix `software/demo/tests/test_mocopi_synth.py::test_beat_phase_clock_wraps_at_one_beat` flake. Read the failure mode first (memory: "passes alone, 50
- Second task: Write `software/demo/unity/lume_pcloud/CHANGELOG.md` (~80 lines). Summarize Waves 1-8 with commit anchors. Pull from `ARCHITECTURE.md` Wave-by-Wave table.
- Third task: Write `software/demo/unity/lume_pcloud/MAC4-VERIFICATION-RUNBOOK.md` (~120 lines). 10-point smoke test:
1. Tailscale up, K11 reachable.
2. F12 calibration panel opens.
3. F2 panel shows depth + audio reactivity.
4. LUMD packet rate ≥28 Hz at K11 lume_packet_inspector.py.
5. LUMF packet rate ≥58 Hz.
6. LUMM packet rate ≥58 Hz.
7. Auto-wire menu attaches all 21 components.
8. Procedural Tunnel scene loads + runs at ≥30fps.
9. F12 panel persists changes to JSON across Unity restart.
10. OSC out at :9050 publishes 7 channels (verified via `nc -ul 9050` or oscdump).
- Fourth task: Write `Desktop/MotionMix/director-protocol.md` (~120 lines, doc-only — impl deferred to Wave 9). Defines event schema (`session_started`, `cue_advanced`, `model_consent_acknowledged`, `cut_executed`, `proof_token_emitted`) and topic routing (`/director/control`, `/director/execution`, `/director/performer`). Cite `1ea8da7 Phase 5a proof token model` and adopt its schema, do not redefine it.
- Fifth task: Write `software/demo/PRE-COMMIT-DONT-TOUCH.sh` (~100 lines) and install as git pre-commit hook in lume-commerce. Refuses to commit if diff touches LumeUdpReceiver.cs magic-byte constants OR NSSM .ps1 service-registration blocks OR a `git push origin main` while a `WAVE8_NOT_PUSHED` sentinel file exists.
- Sixth task: Mac4 verification — Mohamed runs the runbook end-to-end. Pane P3 awaits results, fixes any failures.
- Seventh task: When Mac4 green, Mohamed pushes Mac1 main → origin/main manually. Pane removes the `WAVE8_NOT_PUSHED` sentinel after the push lands.
- Success criterion:
- `pytest tests/` passes 100/100 across 10 consecutive runs.
- CHANGELOG.md committed.
- MAC4-VERIFICATION-RUNBOOK.md exists and Mac4 has green-checked all 10 points.
- director-protocol.md committed (doc only).
- Pre-commit hook blocks a deliberate test violation (manual unit test).
- Wave 8 commits visible on `origin/main`.
- Don't-touch list (this pane): NSSM service registration; Unity public APIs; the Wave 8 commits themselves (push only, no rewrite).
- Dependencies: None.
- Estimated hours: 6-8 hours over 3-5 days (paced around Mohamed's Mac4 access).
- Owner: Codex pane P3 + Mohamed (runs Mac4, pushes).
- Status: PENDING.

P4 — Bridges (b) + (c) follow-on (PARALLEL, P1)

• Focus: close the audio→visual feedback loop. Not in the reel-critical path, but unlocks Phase B of the music-gen plan.
• Working dir: `Desktop/MotionMixApp/`.
• First task: Bridge (b) — `MotionMixApp/Services/OSCService.swift` extension or revision (verify what's already there before writing).
• Bind UDP `:9050` using Network.framework (mirror LiveStreamServer.swift pattern, stage0 §C.4).
• Decode 7 OSC paths Wave 8 publishes: `/lume/right-hand-vel`, `/lume/left-hand-vel`, `/lume/hip-rotation`, `/lume/foot-differential`, `/lume/body-extension`, `/lume/spread`, `/lume/coherence`.
• Inject into ParamMapper.Extras as new optional Float? fields (`unityRightHandVel`, etc.). Purely additive — existing call sites untouched.
• Second task: Bridge (c) — `MotionMixApp/Services/SANPipelineBridge.swift` (NEW, ~80 lines).
• Hook the SAN pattern output stream (read from existing `SANPipeline` 30Hz output buffer).
• Pull `Pattern` slot when SAN confidence > 0.6.
• Debounce 750ms + 16-bar minimum dwell.
• Call `strudelWebEngine.setSANPattern(_:confidence:)` (new additive method on StrudelWebEngine).
• Third task: Round-trip integration test. Spin Unity in K11 mode → motion captured → OSC published → MotionMixApp ParamMapper.lastFrame.unityCoherence shows non-zero variance over 30s window.
• Success criterion:
• 7 OSC channels arrive in ParamMapper.Extras with non-zero variance during a Unity-driven 30s motion session.
• StrudelWebEngine.webView shows ≥2 pattern replacements via setSANPattern over 120s, separated by ≥16 bars.
• No regression in Strudel pattern playback (existing `play(pattern:)` callsites still work).
• Don't-touch list (this pane): StrudelWebEngine.swift's existing `play()` / `setTempo()` API (additive only); ParamMapper's existing MappedValues struct (additive Extras only).
• Dependencies: Independent at infra level. Recommended to start after P1's `[MixerBufferConsumer]` refactor lands so P4 inherits the additive-pattern.
• Estimated hours: 10-14 hours over 3-5 days.
• Owner: Codex pane P4.
• Status: PENDING.

P5 — Universal sled CAD + Mac4 launchd (PARALLEL, P1)

• Focus: hardware mirror per memory §7b. K11 stays in pod; Mac4 sled is in-flight.
• Working dirs: `Desktop/lume-commerce/hardware/cad/`, `Desktop/lume-commerce/software/demo/launchagents/`.
• First task: `hardware/cad/lume-config.scad` edit. Add `MAC_MINI_W=127`, `MAC_MINI_D=127`, `MAC_MINI_H=50`, `MAC_MINI_FOOT_PITCH=110` (the rubber-foot footprint for clamping). Caliper-verify with physical Mac mini M4 first if accessible; else use iFixit teardown dims documented in commit message.
• Second task: `hardware/cad/lume-pod.scad` refactor.
• `module pod_compute_sled(box="K11")` — conditional bolt patterns.
• `module pod_vents_compute(box="K11", side="floor")` — modes ∈ {bottom_intake, perimeter_intake, top_exhaust, rear_exhaust}.
• Internal cable raceways: dual-path (USB-A K11 + TB4-via-hub Mac mini), both always present.
• Front feedthrough widens by ~+8mm for TB4 bundle.
• Render both STLs: `exports/pod_compute_sled_k11.stl` + `exports/pod_compute_sled_macmini.stl`.
• Third task: `software/demo/launchagents/mac4/` directory.
• `com.lume.audio.plist` (mirrors NSSM `LUME-Audio` Args).
• `com.lume.mocopi.plist` (mirrors NSSM `LUME-Mocopi`).
• `com.lume.depth.plist` (mirrors NSSM `LUME-Depth`).
• `install-mac4.sh` (idempotent bootstrap, follows `synthpub-mac5.plist` pattern).
• Fourth task: `pyorbbecsdk2` macOS arm64 wheel verification: `pip download pyorbbecsdk2 --platform macosx_14_0_arm64`. If wheel missing, document source-build steps in `UNIVERSAL-SLED.md`.
• Fifth task: One test print of Mac mini sled on Elegoo Max + ASA. Validate fit on physical Mac mini M4 (or document missing-hardware blocker).
• Sixth task: Camera TCC grants on Mac4 — manual procedure documented in runbook (Mohamed runs, since TCC requires GUI auth).
• Seventh task: Write `hardware/cad/UNIVERSAL-SLED.md` (~120 lines). Documents both modes, both print queues, swap-test runbook (5 cables, 4 screws, < 5 minutes).
• Success criterion:
• Both STLs render without errors and slice in OrcaSlicer.
• One sled prints successfully (whichever box is bench-accessible).
• Mac4 launchd plists install and bring up 3 services on `:9700/:9701/:9702` with parity packet rates to K11 (within 5
• `UNIVERSAL-SLED.md` contains complete swap-test runbook.
• Tailscale + Codex + Claude Code parity confirmed on Mac4.
• Don't-touch list (this pane): K11 NSSM scripts; pod_top/pod_bottom/pod_vesa_plate (only sled + vent grid change); Wave 8 software paths (this is hardware + launchd only).
• Dependencies: None software-side. Hardware-side: requires bench access to Mac mini M4 for caliper-verify (else iFixit dims).
• Estimated hours: 17-22 hours of focused work, spanning ~3 working days, with 5 hours of unattended print time.
• Owner: Codex pane P5 (CAD + plists) + Mohamed (TCC, print, fit-test).
• Status: PENDING.

Pane registry / coordination protocol (lands in P3)

• `[home-path]` — JSON file lists all 5 panes: id, focus, working dir, current task, last-commit-sha, status. Each pane writes its row at session start and on every commit.
• NUMU events on every commit (already wired via `evo3_hooks.py`).
• Daily `/sync-panes` skill — reads registry + NUMU stream + git logs, emits `Desktop/lume-fleet-state-YYYY-MM-DD.md` (~1 page). Mohamed runs once per evening.
• Pre-commit don't-touch hook (P3 task #5).

---

4. Mac4-vs-K11 final call

Stance: K11 ships verified first (it already is). Mac4 mirror is in-flight via P5 in parallel, NOT blocking the reel.

Universal sled hours estimate (refined from Stage 1's "1-2 days"):
- CAD rewrite: 6-8 hours.
- Mac4 launchd plists: 2-3 hours.
- Camera TCC grants: 1 hour.
- USB hub + wheel verification + cable test: 2 hours.
- One test print: 5 hours print + 1 hour fitting.
- Total: 17-22 hours of focused work = ~3 working days for P5 in parallel with reel ship.

Decision: P5 runs throughout the reel-ship week as background work. Reel does NOT depend on Mac4 sled. If Mac4 sled isn't done by 2026-05-09, that's fine — reel still ships from K11, sled completion slips to Wave 9 closeout.

---

5. Reel production plan (final, executable)

Asset pipeline:
- ShootView stills → `Desktop/MotionMixStills/reel-001/` → `<timestamp>_<deviceModel>_manual_capture.jpg` schema (existing).
- Motion clips → `Desktop/MotionMix/captures/reel-001/` → MOV at 1080p60.
- Audio → `[home-path] Support/MotionMixApp/audio-captures/reel-001/` → WAV 48k/16-bit stereo.
- Unity recording → `Desktop/lume-reel-recordings/reel-001/` → MP4 NVENC h264 1920×440 (will crop to 9:16 in composite).
- Final composite → `Desktop/MotionMix/reel-001-final.mp4` → 1080×1920, ≤30s, ≤30MB.

Caption (draft, brand-voice compliant — no em dashes, no AI-isms, terse):

move in light.

body becomes music. music becomes light. light becomes the room.
the engine is hers.

#diomande #lume #computationalchoreography

Platform: Instagram Reels primary + TikTok cross-post. YouTube Shorts deferred (low priority per Diomande Creative Content Strategy memory).

---

6. Audit — risks the master plan must address

Critical risks

R1 — LUMF wire-format collision (P1 → Unity)
- Failure scenario: LumfPublisher.swift produces 84-byte packets that differ from Python `audio_pub.py:send_lumf` by ≥1 byte. K11 Unity rejects packets silently. Reel records "no audio reactivity" visuals.
- Probability: Medium. Encoding details are subtle (endianness, struct packing, MFCC float order).
- Impact: High — silently degrades the reel's reel-defining feature.
- Mitigation: Swift golden-bytes test (P1 task #2) ports the Python golden assertion byte-for-byte. Hand-builds the expected 84 bytes from spec, asserts equality. Cite Python golden as source of truth.
- Validation: `xcodebuild test -only-testing:LumfPublisherTests/testGoldenBytes` passes.

R2 — :9701 publisher collision (K11 NSSM vs MotionMixApp)
- Failure scenario: K11 NSSM `LUME-Audio` and MotionMixApp both publish on `:9701`. Unity sees interleaved packets, audio reactivity becomes garbled.
- Probability: High if both run by default.
- Impact: High — visible in the reel as glitchy audio reactivity.
- Mitigation: K11 NSSM Args gain `--prefer-device --heartbeat-file C:\lume\heartbeat\device.txt` flag. PowerShell side reads the heartbeat file every loop iteration; if mtime < 2s old, NSSM publisher yields. NSSM service registration block stays untouched (only Args at runtime read).
- Validation: With MotionMixApp running, K11 `lume_packet_inspector.py` shows ONLY MotionMixApp packets (verified by source-distinguishing field — e.g., centroid frequency profile differs between synthetic and real audio).

R3 — Photoshoot logistical fail
- Failure scenario: Mohamed needs a model, location, lighting. Solo shoot via ShootView's RemoteControlView is feasible but adds complexity. iPad LUMM fallback for skeleton must work in shoot conditions.
- Probability: Medium.
- Impact: High — no photoshoot, no reel.
- Mitigation: Day 0 pre-flight checklist (location, lighting, charging, iPad LUMM fallback test). Solo-self-shot is the default plan; model coordination is a stretch.
- Validation: Day 2 EOD — "shoot dry run" produces 1 test still + 1 test motion clip without device/setup failures.

Medium risks

R4 — Reel music sounds bad on listen
- Failure scenario: SAN at val loss 0.028 is good for a model but unproven for "publishable music to a non-trained ear." Posting glitchy music = brand harm.
- Probability: Medium-Low.
- Impact: Medium-High.
- Mitigation: A/B audition (P2 task #5). Render 3 motion clips through SAN, render 3 through Strudel-real fallback. Pick whichever sounds best. Last-resort licensed-track from Rekordbox with documented "stretch missed" flag.
- Validation: Day 5 audio audition — Mohamed listens, picks.

R5 — Wave 8 push reveals real Mac4 bug
- Failure scenario: Flake fix masks a real timing issue. Mac4 runtime fails on a corner case the test was correctly hitting.
- Probability: Low-Medium.
- Impact: Medium — would force a Wave 8.1 patch before push.
- Mitigation: P3 task #1 explicitly demands reading the failure mode before fixing. If real bug: escalate, do not silently widen tolerance.
- Validation: 10-point Mac4 runbook is the verifier; if any point fails, defer push, fix bug.

R6 — Coordination collapse across 5 panes
- Failure scenario: Two panes commit conflicting changes to AudioEngine.swift; merge breaks the audio path mid-week.
- Probability: Low-Medium.
- Impact: Medium-High — could break P1's bridge during P2's photoshoot.
- Mitigation: P1 ships the `[MixerBufferConsumer]` array refactor on Day 1 (single commit). P2 + P4 consume it via additive-only consumer registration. Pre-commit don't-touch hook from P3 catches API violations. Daily `/sync-panes` synth.
- Validation: 5-pane registry shows zero merge conflicts in week.

R7 — Strudel pattern thrash (P4)
- Failure scenario: SAN at 30Hz emits patterns faster than Strudel's WKWebView can parse, leading to dropped patterns or audio glitches.
- Probability: High without mitigation.
- Impact: Medium — degrades P4's deliverable but doesn't gate reel.
- Mitigation: 750ms debounce + confidence > 0.6 gate + 16-bar minimum dwell (P4 design).
- Validation: 120s session shows ≤4 pattern replacements.

Low risks

R8 — pyorbbecsdk2 macOS arm64 wheel lag (P5)
- Mitigation: Pre-flight wheel check; source-build documented as fallback.
- Validation: `pip download` succeeds OR source build documented in UNIVERSAL-SLED.md.

R9 — OpenSCAD render timeouts on complex pod_compute_sled (P5)
- Mitigation: Render incrementally, validate each module independently.
- Validation: Both STLs in `exports/`.

R10 — FirstDate token still exposed in remote URL (stage0 §F.1, security finding)
- Mitigation: Backlog ticket — Mohamed rotates manually. Not in critical path; documented in this plan for visibility.
- Validation: `git -C Desktop/FirstDate remote -v` no longer contains a PAT.

---

7. Expanded specs (key components)

7.1 LumfPublisher.swift (P1)

// MotionMixApp/Services/LumfPublisher.swift (NEW, ~180 lines)
// PRODUCTION SYSTEM — don't break what ships.
// Wire format pinned by software/demo/tests/test_wire_format_golden.py
// Magic: 0x4C554D46. Size: 84 bytes. Port: 9701.

import Foundation
import Network

@MainActor
final class LumfPublisher: MixerBufferConsumer {
    // MARK: Wire format
    private static let MAGIC: UInt32 = 0x4C554D46  // "LUMF"
    private static let PACKET_SIZE = 84

    // MARK: Config
    private let target: NWEndpoint
    private let connection: NWConnection
    private let heartbeatURL: URL

    // MARK: FFT (reuse AudioEngine pre-allocated buffers; do NOT alloc)
    // ... uses audioEngine.fftBuffer, hannWindow (existing per AudioEngine.swift:116-122)

    // MARK: Onset detection
    private var prevSpectrum: [Float] = .init(repeating: 0, count: 128)
    private var fluxEMA: Float = 0.0

    // MARK: Heartbeat
    private var lastHeartbeatWrite: Date = .distantPast

    init(target: String, port: UInt16 = 9701) {
        // ... NWConnection setup, Tailscale-aware target resolution
        // ... heartbeat file at Application Support/MotionMixApp/lumf-heartbeat.txt
    }

    // MARK: MixerBufferConsumer (called from AudioEngine onMixerBuffer)
    func handlePCM(_ buffer: AVAudioPCMBuffer, at time: AVAudioTime) {
        // 1. FFT via existing pre-allocated buffer
        // 2. 4 EQ bands (lo 60-250, mid 250-2k, hi 2k-8k, top 8k+)
        // 3. 8 MFCC (mel-cepstrum)
        // 4. RMS, spectral centroid
        // 5. Onset via spectral flux EMA-rectified
        // 6. Pack into 84 bytes (use Data + withUnsafeMutableBytes; pin endianness little-endian)
        // 7. Send via NWConnection
        // 8. Heartbeat write every 1s
    }

    // MARK: Tests in MotionMixAppTests/LumfPublisherTests.swift
    // testGoldenBytes: hand-build expected 84 bytes, assert equality
    // testFFTReuse: assert no allocation in handlePCM hot path
}

Interaction with AudioEngine.swift (additive edit):

// AudioEngine.swift — existing line 110-112 (refactor day 1):
//   onMixerBuffer = { buffer, time in self.musicAnalysisService.handle(buffer) }
// becomes:
private var mixerConsumers: [MixerBufferConsumer] = []
func registerMixerConsumer(_ c: MixerBufferConsumer) { mixerConsumers.append(c) }
// AVAudioMixerNode tap calls all consumers.
// MusicAnalysisService is registered first (preserves existing behavior).
// LumfPublisher registers second (P1).
// AudioCaptureWriter registers third (P2).

7.2 OSCService extension (P4)

// MotionMixApp/Services/OSCService.swift (extension)
// ADDITIVE ONLY — no existing call site touched.

extension OSCService {
    // Bind :9050 listener using Network.framework UDPListener
    func startUnityOSCConsumer() {
        // ... bind :9050
        // ... decode 7 channels, route into ParamMapper.Extras additive fields
    }
}

// ParamMapper.swift (additive Extras fields):
struct Extras {
    // ... existing fields ...
    var unityRightHandVel: Float? = nil
    var unityLeftHandVel: Float? = nil
    var unityHipRotation: Float? = nil
    var unityFootDifferential: Float? = nil
    var unityBodyExtension: Float? = nil
    var unitySpread: Float? = nil
    var unityCoherence: Float? = nil
}

7.3 SANPipelineBridge (P4)

// MotionMixApp/Services/SANPipelineBridge.swift (NEW, ~80 lines)
@MainActor
final class SANPipelineBridge {
    private weak var sanPipeline: SANPipeline?
    private weak var strudel: StrudelWebEngine?
    private var lastReplaceAt: Date = .distantPast
    private var lastPattern: String = ""
    private var barCount: Int = 0

    func tick() {  // called from AudioEngine 100ms ticker
        guard let pat = sanPipeline?.latestPattern, pat.confidence > 0.6 else { return }
        let now = Date()
        let dwellSec = now.timeIntervalSince(lastReplaceAt)
        // Compute dwell in bars from current bpm
        let barSec = 4.0 * (60.0 / (audioEngine.bpm))
        guard dwellSec > 16 * barSec, dwellSec > 0.75 else { return }
        guard pat.text != lastPattern else { return }
        strudel?.setSANPattern(pat.text, confidence: pat.confidence)
        lastReplaceAt = now
        lastPattern = pat.text
    }
}

// StrudelWebEngine.swift (additive):
extension StrudelWebEngine {
    func setSANPattern(_ pattern: String, confidence: Double) {
        let escaped = pattern.replacingOccurrences(of: "'", with: "\\'")
        webView.evaluateJavaScript("window.sanReplacePattern && window.sanReplacePattern('\(escaped)')", completionHandler: nil)
    }
}

7.4 record-unity-reel.sh (P2)

#!/usr/bin/env bash
# software/demo/scripts/record-unity-reel.sh
# Records 30s of LUME visual via NVENC (Windows K11) or ScreenCaptureKit (macOS Mac4).
# Reuses Wave 8 publishers — zero Unity changes.

set -euo pipefail

DURATION=${1:-30}
OUT_DIR="${HOME}/Desktop/lume-reel-recordings/$(date +%Y%m%d-%H%M%S)"
mkdir -p "$OUT_DIR"

# Detect platform
if [[ "$(uname)" == "Darwin" ]]; then
  # macOS: ScreenCaptureKit via /usr/bin/screencapture or ffmpeg avfoundation
  ffmpeg -y -f avfoundation -framerate 60 -i "1:none" -t "$DURATION" \
    -c:v hevc_videotoolbox -b:v 8M "$OUT_DIR/lume-reel.mp4"
else
  # Windows K11: NVENC via gdigrab
  ffmpeg -y -f gdigrab -framerate 60 -i desktop -t "$DURATION" \
    -c:v h264_nvenc -b:v 8M "$OUT_DIR/lume-reel.mp4"
fi

echo "Reel recording: $OUT_DIR/lume-reel.mp4"

7.5 lume-config.scad additions (P5)

// hardware/cad/lume-config.scad (additive)
// Mac mini M4 (verified iFixit teardown 2024 / caliper-verify if accessible)
MAC_MINI_W = 127;     // mm, top-down width
MAC_MINI_D = 127;     // mm, top-down depth
MAC_MINI_H = 50;      // mm, height
MAC_MINI_FOOT_PITCH = 110;  // mm, rubber foot footprint for clamping

// Vent topology mode constants
VENT_MODE_BOTTOM_INTAKE = "bottom_intake";    // K11
VENT_MODE_PERIMETER_INTAKE = "perimeter_intake"; // Mac mini
VENT_MODE_TOP_EXHAUST = "top_exhaust";        // K11
VENT_MODE_REAR_EXHAUST = "rear_exhaust";      // Mac mini

---

8. Master execution checklist (wave-based, dependency-ordered)

> Status: PENDING (P) / IN-FLIGHT (I) / DONE (D) / BLOCKED (B). `automate: true` flags Pulse-eligible.

Wave A — Day 1 (2026-05-03) — Foundation

• [P] A1: P1 — Refactor `AudioEngine.swift` `onMixerBuffer` to `[MixerBufferConsumer]` array. Single commit. Owner: P1 / automate: true
• [P] A2: P1 — Create `MotionMixApp/Services/LumfPublisher.swift` (~180 lines). Depends on: A1 / Owner: P1 / automate: true
• [P] A3: P1 — Write Swift golden-bytes test mirroring `tests/test_wire_format_golden.py`. Depends on: A2 / Owner: P1 / automate: true
• [P] A4: P2 — Write `Desktop/MotionMix/REEL-001-PRODUCTION-PLAN.md` (~150 lines). Owner: P2 / automate: true
• [P] A5: P2 — Create `MotionMixApp/Services/AudioCaptureWriter.swift`. Depends on: A1 / Owner: P2 / automate: true
• [P] A6: P3 — Investigate `test_mocopi_synth.py::test_beat_phase_clock_wraps_at_one_beat` flake. Determine isolation vs real bug. Owner: P3 / automate: false (judgment call)
• [P] A7: P5 — Edit `hardware/cad/lume-config.scad` to add MAC_MINI constants. Owner: P5 / automate: true

Wave B — Day 2 (2026-05-04) — Verification + Docs

• [P] B1: P1 — Run K11 verification with `lume_packet_inspector.py`. Confirm ≥58 LUMF pkt/s for 60s. Depends on: A2, A3 / Owner: P1 + Mohamed
• [P] B2: P1 — Add `--prefer-device --heartbeat-file` runtime flag to K11 NSSM Args (NOT the service block). Depends on: B1 / Owner: P1 + Mohamed (PowerShell exec)
• [P] B3: P2 — Create `software/demo/scripts/record-unity-reel.sh`. Test on K11 (5s recording). Owner: P2 / automate: true
• [P] B4: P3 — Apply mocopi_synth fix (isolation refactor or escalation). Depends on: A6 / Owner: P3 / automate: true if isolation
• [P] B5: P3 — Write `software/demo/unity/lume_pcloud/CHANGELOG.md`. Owner: P3 / automate: true
• [P] B6: P3 — Write `software/demo/unity/lume_pcloud/MAC4-VERIFICATION-RUNBOOK.md`. Owner: P3 / automate: true
• [P] B7: P4 — Implement OSC :9050 binding in OSCService.swift extension. Owner: P4 / automate: true
• [P] B8: P5 — Refactor `hardware/cad/lume-pod.scad` `pod_compute_sled` and `pod_vents_compute` modules. Render both STLs. Owner: P5 / automate: true

Wave C — Day 3 (2026-05-05) — Photoshoot Day 1

• [P] C1: P3 — Write `Desktop/MotionMix/director-protocol.md` (doc only). Owner: P3 / automate: true
• [P] C2: P3 — Create `software/demo/PRE-COMMIT-DONT-TOUCH.sh`. Install in lume-commerce, MotionMix, MotionMixApp git hooks. Owner: P3 / automate: true
• [P] C3: P3 — Create `[home-path]`. Owner: P3 / automate: true
• [P] C4: PHOTOSHOOT — Look 1. Stills + motion clip + AudioCaptureWriter recording. Owner: Mohamed
• [P] C5: P4 — Verify Wave 8 OSC arrives in ParamMapper.Extras during a Unity-driven 30s motion session. Owner: P4 + Mohamed
• [P] C6: P5 — Create `software/demo/launchagents/mac4/` (3 plists + install-mac4.sh). Owner: P5 / automate: true

Wave D — Day 4 (2026-05-06) — Photoshoot Day 2

• [P] D1: PHOTOSHOOT — Looks 2-3. Owner: Mohamed
• [P] D2: P4 — Implement `MotionMixApp/Services/SANPipelineBridge.swift` + StrudelWebEngine `setSANPattern` additive method. Owner: P4 / automate: true
• [P] D3: P5 — Verify `pyorbbecsdk2` macOS arm64 wheel availability. Document in UNIVERSAL-SLED.md. Owner: P5 + Mohamed
• [P] D4: P5 — Write `hardware/cad/UNIVERSAL-SLED.md`. Owner: P5 / automate: true

Wave E — Day 5 (2026-05-07) — Unity Recording + Audio Audition

• [P] E1: Unity recording session. Run `record-unity-reel.sh` × 3 looks at K11. Owner: Mohamed + P2
• [P] E2: Audio audition. A/B SAN-driven vs Strudel-render. Pick. Owner: Mohamed
• [P] E3: P4 — End-to-end OSC + Strudel test (120s session, ≥2 pattern replacements). Owner: P4 + Mohamed
• [P] E4: P5 — Print test sled (whichever box accessible). Owner: P5 + Mohamed

Wave F — Day 6 (2026-05-08) — Composite + Mac4 Verification

• [P] F1: Composite via ShootView ReelBuilderView. Stills + motion clips + Unity LUME visual + audio = 30s 9:16 1080×1920 ≤30MB. Owner: Mohamed
• [P] F2: Caption draft + brand-voice review. Owner: Mohamed
• [P] F3: P3 — Mac4 verification via 10-point runbook. Owner: Mohamed (runs Mac4)
• [P] F4: P5 — Fit-test the printed sled. Owner: Mohamed

Wave G — Day 7 (2026-05-09) — Ship

• [P] G1: POST REEL to Instagram + TikTok. Owner: Mohamed (manual)
• [P] G2: PUSH WAVE 8. Mac1 main → origin/main. Pre-commit hook removes `WAVE8_NOT_PUSHED` sentinel. Owner: Mohamed (manual)
• [P] G3: 24h monitor for ≥1 viewer comment about music or visual. Owner: Mohamed
• [P] G4: Stage 3 master plan retrospective: write `lume-creative-engine-2026-05-09-retrospective.md` to memory. Owner: Codex

Wave H (Backlog) — Wave 9 work

• Mount HD1, retrain SAN to V6 (Phase C of music-gen plan).
• Director protocol Rust impl: `multicam-server/src/director_bus.rs` + Swift FFI clients.
• Mocopi-pro activation (when mail arrives).
• FirstDate token rotation (security hygiene).
• Bar display caliper-verify (#177).
• Diffusion / training-pipeline triage (memory §4 pane 7, optional).

---

9. Pulse auto-spawn analysis

For tasks with `automate: true`, Pulse can spawn dedicated sessions:

• A1, A2, A3, A4, A5, A7 — Wave A automation candidates. Each is a focused, well-scoped Codex task with verifiable outputs. Recommend dry-run spawn for these on Day 1.
• B3, B5, B6, B7, B8 — Wave B doc + script tasks. Pulse-friendly.
• C1, C2, C3, C6 — Wave C infra. Pulse-friendly.
• D2, D4 — Wave D additive Swift + docs. Pulse-friendly.
• G4 — retrospective. Pulse-friendly.

Tasks NOT recommended for Pulse auto-spawn:
- A6 (judgment call on flake fix vs escalation).
- B1, B2, C4, C5, D1, D3, E1, E2, E3, E4, F1, F2, F3, F4, G1, G2, G3 — require Mohamed's hands or judgment.

# Suggested first Pulse run (DRY-RUN ONLY):
python3 [home-path] pulse-spawn \
  --checklist [home]/Desktop/evo-cube-output/lume-creative-engine-2026-05-02/stage3-expand-master-plan.md \
  --slug lume-creative-engine-2026-05-02 \
  --dry-run true

---

10. Closing notes — production system propagation

Every Codex pane briefing MUST include this header verbatim:

THIS IS A PRODUCTION SYSTEM. Don't break what ships.

Don't-touch:
  - Wave 8 wire format magics (LUME/LUMD/LUMF/LUMM/LUMC) — pinned by golden-bytes tests.
  - 21 Unity component public APIs — additive only.
  - K11 NSSM service registration blocks — runtime Args may be flagged, registration stays.
  - Wave 8 commits not-pushed — Mohamed pushes manually after Mac4 verification.
  - MotionMix repo's Phase 5a proof token model — read it, don't redefine it.

Mohamed runs all destructive ops: git push, launchctl unload && load, nssm remove,
social posts. Codex panes propose; Mohamed disposes.

Verification before declaration. A pane that says "done" includes runtime evidence.

End of master plan.