Fold SPEC/maven/ROADMAP into DESIGN.md and drop the stale session logs

15 root markdown files, ~4,900 lines against ~33,000 lines of Go, with at least
three pairs contradicting each other. When five documents describe the
architecture, the code becomes the only trustworthy one — which defeats the
point of having them. That drift is why the resident-model question had four
incompatible answers.

SPEC.md, maven.md and ROADMAP.md are deduped into DESIGN.md rather than
concatenated, with a "Superseded" section carrying eight retired decisions and
what replaced each: classifier-owns-the-route (the cascade is still the live
path, but as a stopgap, not a design to extend), faster-whisper/vosk/silero,
the small-model phrasing claim, sqlcipher, the Kotlin/Spring sketches,
obsidian->chroma, script deployment, and FloorEnrollment. Superseded material
is kept and marked rather than deleted, so it cannot read as current.

SESSION-05/06-07-2026.md and PLANS.md are removed outright — git history holds
them, and both were verified tracked before deletion.

Go doc comments citing the deleted files are repointed to the equivalent
DESIGN.md sections. Several asserted designs that were already retired, so the
claims are corrected and not just relinked: stt.go named faster-whisper as
production (it is whisper.cpp), tts.go named silero (it is piper), intent.go
still described the classifier as owning the route, and stale vosk/chroma
vocabulary is replaced. ECOSYSTEM-SPEC.md references are deliberately
untouched — that is a different document, and a naive grep for SPEC.md matches
it.

Root markdown drops from 4,880 to ~3,700 lines. The review's ~1,500 target is
not reachable while keeping the files it also said to keep — those alone are
2,553 lines — so trimming further needs a separate decision on
MAVEN_ECOSYSTEM_ARCHITECTURE.md and PROGRESS.md.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X5JApcrCRVGmqrxnhynSik

internal/auth/tier.go

@@ -1,7 +1,7 @@
 // Package auth is maven's authority layer — the 4-layer cascade and the
 // "surface caps authority" invariant.
 //
-// Spec contract (from maven.md § auth):
+// Spec contract (from DESIGN.md § Auth):
 //
 //	a cascade, not a pick-one — each layer answers a different question:
 //

internal/delivery/channel.go

@@ -1,6 +1,6 @@
 // Package delivery is maven's channel-routing + dispatch layer.
 //
-// Spec contract (from maven.md § delivery / channel routing):
+// Spec contract (from DESIGN.md § Delivery / channel routing):
 //
 //   - routing = f(severity, presence). presence decides REACHABILITY; severity
 //     decides INSISTENCE. need both.

internal/router/intent.go

@@ -1,17 +1,24 @@
 // Package router is maven's reactive path — the cascade that turns a free-form
 // utterance into a deterministic Decision.
 //
-// Spec contract (from maven.md § reactive path — router):
+// Spec contract (from DESIGN.md § Reactive path — routing):
 //
-//   - routing is a DECISION, and every decision in maven stays deterministic.
-//     a classifier owns the route; the SLM stays in its phrasing lane. same
-//     boundary as "rules decide, llm phrases," extended to the reactive path.
-//   - a CASCADE, not classifier-vs-deterministic — layers:
+//   - the TARGET design is LLM-as-router: the resident model (Qwen3-1.7B)
+//     emits GBNF-constrained structured JSON for the route, and the same
+//     model phrases replies; the embedder is a RAG hint, not a routing gate.
+//     the classifier/embedder cascade below is the committed default today,
+//     but it is an interim stopgap (DESIGN.md § Superseded, "classifier-owns-
+//     the-route") and the known cause of weak RU query handling — not a
+//     design to extend.
+//   - a CASCADE, not one decider — layers:
 //     stage 0 — exact match (regex/grammar). wake-word + known command
 //     grammar. "maven, restart nginx" hits the allowlist directly,
-//     skips the classifier. lowest latency — the vosk command path.
-//     stage 1 — intent classifier. embed utterance, nearest-centroid over
-//     labeled intents. one forward pass, ~30ms cpu, similarity score.
+//     skips the classifier. lowest latency — the client-side wake-word/
+//     command-grammar path (cmd/mavwaked).
+//     stage 1 — route decision. the resident model (target), else the
+//     nearest-centroid classifier over embedded labeled intents (today's
+//     stopgap: one forward pass, ~30ms cpu, similarity score). any LLM
+//     error falls through to the classifier so a turn never breaks.
 //     stage 2 — slot extraction, per intent. classification gives *what kind*,
 //     not *the args*. reminders need a datetime, acts need fn+params.
 //     stage 3 — confidence gate. below threshold → clarify, don't guess.
@@ -28,14 +35,15 @@ package router
 
 import "time"
 
-// Intent — the six save-where labels from the spec's routing table. The
+// Intent — the seven save-where labels from DESIGN.md's routing table. The
 // discriminator is "does the loop evaluate a predicate against it?":
 //
 //   - act:      command now, not stored (function call into the allowlist)
 //   - reminder: has a fire-time → reminders table (sqlite). bypasses the gate
 //   - fact:     structured state the loop reasons over → facts (sqlite)
-//   - note:     recall/preference, no predicate touches it → chroma
-//   - query:    answer, don't store → slm reads sqlite or chroma (RAG)
+//   - note:     recall/preference, no predicate touches it → semantic store
+//   - query:    answer, don't store → the resident model reads sqlite or the
+//     semantic store (RAG)
 //   - chat:     conversational, no store side-effect — LLM replies from
 //     dialogue history + general knowledge
 //

internal/stt/stt.go

@@ -9,23 +9,22 @@
 //     audio bytes for a tiny bit of variation per utterance; the *content*
 //     of the audio doesn't matter, only the wire shape round-trips.
 //
-//   - Remote: dials a worker module process at a unix socket (cmd/mavsttd
-//     today; a faster-whisper / vosk-backed process when models land). The
-//     swap is one constructor change at the daemon seam; the boundary is the
-//     same.
+//   - Remote: dials a worker module process at a unix socket (cmd/mavsttd,
+//     whisper.cpp-backed). The swap is one constructor change at the daemon
+//     seam; the boundary is the same.
 //
 // The Daemon picks the implementation from config. With no models on disk,
 // it wires Stub (the audio path is "live" end to end, the transcribe step
 // returns a canned string the router + action path operate on); with a
 // worker socket configured, it wires Remote.
 //
-// Per spec (maven.md § stt/tts): faster-whisper small/int8 is the production
-// stt; vosk-ru runs on the client (wake-word + stage-0 grammar), not here.
-// The server-side stt module is the heavy multilingual path; vosk's
-// stage-0 grammar hits the router directly via the client's stage-0 surface
-// and never crosses this seam — that path is post-MVP (the client doesn't
-// exist yet). Today's Remote + Stub both return plain text the router
-// classifies.
+// Per DESIGN.md § Voice pipeline (STT / TTS): whisper.cpp (CGo, Vulkan) in
+// cmd/mavsttd is the production stt — the older faster-whisper/vosk picks are
+// retired (DESIGN.md § Superseded, "named STT/TTS model picks"). The
+// server-side stt module is the heavy multilingual path; the client's
+// wake-word + stage-0 command grammar (cmd/mavwaked) hits the router directly
+// and never crosses this seam. Today's Remote + Stub both return plain text
+// the router classifies.
 package stt
 
 import (

internal/tool/tool.go

@@ -2,7 +2,7 @@
 // store's allowlist, and drafts 'proposed' scaffolds for acts that aren't on
 // it yet.
 //
-// Boundary discipline (maven.md "tool registration — drafting is suggest,
+// Boundary discipline (DESIGN.md § "Tool registration — drafting is suggest,
 // enabling is act"):
 //
 //   - The store is the allowlist. Only status='enabled' rows run. A verb not
@@ -16,7 +16,8 @@
 //   - Destructive tools don't run on first hearing: Exec returns ErrNeedsConfirm
 //     and the handler runs a confirm turn ("выполнить X? да/нет"); only a
 //     confirmed re-Exec runs them. A gate assumes a fully-formed action, which
-//     an enabled+matched act is (maven.md "confirmation is not one mechanism").
+//     an enabled+matched act is (DESIGN.md § "Confirmation is not one
+//     mechanism").
 package tool
 
 import (

internal/tts/tts.go

@@ -5,12 +5,12 @@
 // PCM, headerless per the audio package; the voice sink + reference client
 // wrap it in a WAV at the disk edge.
 //
-// Per spec (maven.md § stt/tts): silero (ru-native) is the production tts,
-// piper (ru) is the safe floor. Both are CPU-only on the ryzen box; both
-// ship as separate worker module processes (cmd/mavttsd today with the
-// Stub handler; production swaps in onnxruntime / espeak-ng in the same
-// main, no tts-package change). The daemon wires one — Remote pointing at
-// the worker socket if configured, Stub otherwise.
+// Per DESIGN.md § Voice pipeline (STT / TTS): piper is the production tts
+// (subprocess + espeak-ng, CPU-only on the ryzen box, driven by cmd/mavttsd);
+// the older silero pick is retired (DESIGN.md § Superseded, "named STT/TTS
+// model picks"). A different voice is a model-file swap, not a code change.
+// The daemon wires one impl — Remote pointing at the worker socket if
+// configured, Stub otherwise.
 //
 // The Stub returns a short deterministic tone (a 200ms mid-frequency sine
 // burst) so the voice loop round-trips end-to-end without a model. The