P4

docs/voice-acceptance.md

@@ -0,0 +1,29 @@
+# Phase 4 voice acceptance
+
+Run `npm run voice-doctor` in the target GNOME session. Set
+`JARVIS_WAKE_COMMAND` to the local openWakeWord or sherpa-onnx bridge command.
+The command receives raw 16 kHz mono PCM on stdin and emits one detected phrase
+per line on stdout; the daemon passes it through `ProcessWakeEngine`. No cloud
+wake service is supported.
+
+The capture and playback nodes are both named `Jarvis`, so they can be routed
+in Helvum or qpwgraph. The loop gates capture while TTS is active and for 400ms
+after playback. Runtime counters are available from the `VoiceLoop.metrics`
+snapshot: wake accepts, rejected utterances, feedback drops, utterances, and
+replies.
+
+Acceptance cases:
+
+1. Hold push-to-talk, say a question, release, and verify one final transcript.
+2. Say the configured wake phrase, pause, and verify `ARMED → LISTENING →
+   THINKING → SPEAKING → LISTENING`.
+3. Play a 20-second reply beside the microphone and verify `feedbackDrops`
+   increases while no new transcript is submitted.
+4. Say `cancel`, `go to sleep`, `repeat that`, `take the wheel`, or `look at my
+   screen` and verify the fast path handles the command before the harness.
+5. Use D-Bus `Ask()` while the microphone is unavailable to exercise typed
+   fallback.
+
+Wake false accepts and false rejects should be measured over 50 utterances in
+quiet, music, and kitchen-noise conditions and recorded outside the default
+privacy log; raw audio is never written by the daemon.