Add built-in answer tones and automatic multiple-choice progression

docs/FEEDBACK_TESTING.md

@@ -0,0 +1,67 @@
+# Built-in sound and automatic multiple-choice feedback
+
+Tested in installed VCC Plus 3.5.0 build 41 with its bundled CMOC toolchain,
+using the public MCP interface and isolated 512 KB MC6809 workers.
+
+- Correct answers use a rising pair of BASIC SOUND tones; incorrect answers
+  use a lower falling pair. Both quiz modes use the built-in audio output.
+  No Speech/Sound, Orchestra-90 or other sound cartridge is required.
+- SOUND executes at normal CPU speed, then restores the faster graphics clock.
+- Multiple choice displays correctness and the correct capital, plays its tone,
+  waits 90 video ticks (1.5 seconds), then advances without a continue key.
+- Typed answers retain Space-to-continue. A near spelling still offers retry
+  or reveal before any result tone or point is awarded.
+
+## Passed checks
+
+- Full 50-question multiple-choice run: all states once, numbering 1–50,
+  unique choices and state highlighting, expected 42/50 (84%), review, replay,
+  and BASIC exit. No Space or Enter was sent to advance any question.
+- An answer key was held across the timeout into Question 2 and for a further
+  600 fields. The next question remained unanswered until release/new input.
+- Full 50-question typed run: expected 47/50 (94%), two spelling corrections,
+  casing, aliases, repeated spaces, transpositions, Backspace, long input,
+  wrong capitals, reveal, review and exit. Feedback remained on Question 1
+  after 300 additional idle fields, confirming typed mode still waits for Space.
+- Release smoke test: correct and incorrect feedback, a readable pause,
+  automatic advancement to Questions 2 and 3, expected score, and title Quit.
+- Test, Debug and Release builds succeeded without compiler diagnostics.
+- Host logic/geometry tests and byte-identical asset regeneration passed.
+
+## Sound verification and limitation
+
+The linked CMOC SOUND wrapper calls Color BASIC at $A951. Framebuffer receipts
+sampled the emulated PC at $A98C/$A98D during correct and incorrect playback,
+confirming execution of the built-in ROM tone path. The public MCP tools do not
+export audio samples, so no recording or listening test is claimed. A reusable
+VCC enhancement would add field-aligned PCM/WAV capture to disposable playtests
+so pitch, duration and silence can be checked without extra cartridges.
+
+## Files and build details
+
+Project headers are now quiz.h, ui.h and map_data.h beside main.c. VCC's build
+snapshot omitted the nested include directory; root headers build and share
+correctly through the documented interface. Make rules and asset generation
+use the same layout. Explicit header dependencies replace CMOC dependency files
+that could retain expired snapshot paths. Host tests now use a temporary executable
+outside the shared checkout. Both a normal and an incremental native build passed
+and produced byte-identical copies of the tested Release binary. No emulator or
+compiler patch was needed.
+
+Full PNG captures are in build/evidence/feedback/test and
+build/evidence/feedback/release. Complete raw receipts and captures are preserved
+in build/evidence/feedback-test.zip and feedback-release.zip. The original
+captures remain directly viewable and their full raw evidence is preserved in
+build/evidence/baseline.zip. Archives prevent generated JSON receipts from
+unnecessarily expanding the assistant's project-sharing scope. Curated receipts
+are in docs/evidence/feedback-*.json.
+
+The Release build is `789DA457-9E69-4746-A833-801EC9F019DA`; artifact
+`55C22401-B69A-40A4-9C04-C00281007402`. Code/static storage ends at `$7600`,
+below the `$7800` limit, with the separate 2 KiB stack budget unchanged.
+
+- build/CAPITAL.bin SHA-256: `6e9fd266f3ea0987430e173bf421ab0d8f2a3e9e0359c048050dfeadcf8bfe02`
+- build/CAPITAL.dsk SHA-256: `d9464356aadaa53b2f8e74aa7b50ba8f96f900950747408ddfa077a2867c3b4f`
+
+The previous generated binary/disk are preserved in build/previous. All guest
+playtests report zero disk writes and used disposable copies of their disks.