neuro-cube: Instructions file for Claude Code

Neuro-Cube — Neuro-Adaptive 3D Rubik's Cube Simulator

Project Overview

A 3D Rubik's Cube simulator (Panda3D) driven by EEG focus signals (BrainFlow). The user selects a face with the keyboard; sustained mental focus triggers the move. A mock mode allows full development without EEG hardware.

Status: Feature-complete and tested (cube, renderer, retention hook, MCP bridge). Remaining: real-hardware threshold calibration, polish (camera orbit, prime-move UX).

Architecture (non-negotiable threading contract)

BrainFlowPoller (daemon thread)      CubeState (lock-guarded)         App/Renderer (main thread)
  poll EEG → filter → focus metric    magiccube + threading.Lock       Panda3D task, once per frame
  └─ event_queue.put(NeuralEvent) ─▶  execute_move() validates+mutates └─ event_queue.get_nowait()
                                      └─ update_queue.put(snapshot) ─▶    drain update_queue → animate

Rules — violating any of these reintroduces race conditions:

1. One-way queues only. The neural thread communicates exclusively through event_queue (a queue.Queue). It never imports Panda3D, never touches CubeState, never calls into the View.
2. CubeState is the single source of truth. Every cube mutation goes through CubeState.execute_move(), which validates notation and mutates magiccube under threading.Lock. Consumers only ever see immutable StateEvent snapshots from update_queue — never the live cube object.
3. The render loop never blocks. All queue reads on the main thread are get_nowait() drained until queue.Empty. No .get(), no .join(), no sleeps in any Panda3D task.
4. queue.Queue, not asyncio.Queue. Panda3D's task manager is not an asyncio loop, and asyncio.Queue is not thread-safe for foreign-thread producers.
5. Animation is serialized. _is_animating flag + _pending_moves deque in the renderer; a Sequence's Func callback clears the flag. Never start a second face rotation while one is playing.