docs: split spec 03 into 03-01 brain-harness + 03-02 ducking [spec 03-01]

[wine-fall]

What

Defines and splits spec 03 (music-provider, milestone L1 "radio feel") into two single-purpose sub-specs, and locks a master-level decision about the brain.

• specs/03-01-brain-harness.md — the general brain-harness seam (turn the isolated brain into a tool/skill-using agent, preserving local-env isolation). First capability: habit-based, Claude-driven music search & recommendation (MusicProvider impl; yt-dlp default, musicdl optional) + Director talk↔music scheduling. Music plays sequentially via the existing player.
• specs/03-02-ducking.md — a source-agnostic mixing audio engine (ffmpeg→PCM + numpy) that replaces the afplay AudioPlayer, with gain-envelope ducking; a typed interjection ducks the music instead of hard-stopping it.
• DESIGN.md — §3.2 locks "the brain is a harnessed agent, not a one-shot LLM call"; §5 records musicdl / NetEase / Spotify-librespot as optional user-installed gray providers (never shipped); §9.4/§10 do the split + reorder (harness first) and mark spec 02 code-implemented.
• contracts.py — realign spec references to 03-01/03-02.

Build order: 01 → 03-01 (harness + music) → 03-02 (ducking); both are L1, both depend only on 01 (03-02 also integrates 03-01).

AI coding brief

• Original request: discuss the scope of spec 03 and how to build it. Why: spec 02 is done and spec 03 (making the radio feel like radio — music + ducking) had no spec yet.
• Manual interventions / human feedback:
  • Ducking is a core feature and must be owned by some spec — not deferred into limbo.
  • Music search must be fully Claude-driven (tools/skills/context), not deterministic yt-dlp heuristics.
  • The brain is a complete, harnessed agent, not a crippled LLM call: isolation from the local Claude env is mandatory, but it still uses murmur's own tools/skills and can be steered by conversation.
  • Rejected swapping Claude for nousresearch/hermes-agent (model would hurt the soul now; harness would cede control of the custom radio loop).
  • Do the harness first, ducking second.
  • Don't name it "music agent" — the harness is general; music is just its first capability.
  • Treat musicdl (and other gray sources) as optional, not the default.
• Retro (prompt-to-ship-faster): stating "brain = full harnessed agent, not a neutered LLM call, isolated but tool-capable" up front would have skipped a couple of scoping rounds; and naming the two axes early (audio-engine vs agent-harness) would have led to the split sooner.

🤖 Generated with Claude Code