Phase 11: Complete and verify the minimal music-making workflow

docs/BUILD.md

@@ -232,3 +232,10 @@ Clang static analysis of all core sources. These need installed development
 tools; the allocation guard uses a GNU-compatible linker. See
 [RELIABILITY.md](RELIABILITY.md) for ownership, audit findings,
 full verification commands and remaining limits.
+
+## Phase 11 workflow acceptance
+
+`make test-workflow` requires FLTK/JACK development files, Xvfb and an existing
+JACK-compatible server. It does not start/configure the server or connect
+physical devices. See [WORKFLOW.md](WORKFLOW.md) for the full GUI composition
+acceptance sequence and transport semantics.

docs/GUI.md

@@ -25,7 +25,8 @@ data is owned by opaque C objects, manipulated only through the C API. All backe
 from an audio callback. No server is started and no audio ports are connected
 by the GUI. The initially empty graph produces silence.
 
-- **Play / F5:** start the engine. **Stop / F8:** deactivate it. **Space:** toggle.
+- **Play / F5:** start the engine. **Stop / F8:** deactivate it. **Pause / F7:** hold playback. **Space:** toggle Play/Stop.
+  **To start / Home:** stop and seek to zero. Pause/Home are disabled while recording.
   These advance/pause the sample-counted playhead; imported audio clips play through their graph source.
 - **Reconnect / F6:** close the old client and open a fresh stopped client.
   Use this after server loss or sample-rate changes. A failed close preserves
@@ -177,3 +178,18 @@ remove, and change First tick to navigate. Ctrl+Z, Ctrl+Shift+Z and Ctrl+Y undo
 and redo up to 32 project edits; New/Open resets history. M/S and arrow keys
 provide mixer shortcuts. See MIXER.md for exact controls, history rollback,
 stereo port routing, automation semantics and prototype limits.
+
+## Phase 11 minimal composition workflow
+
+[WORKFLOW.md](WORKFLOW.md) walks through creating, arranging, saving, closing,
+reopening and playing MIDI/audio with the GUI. New/Open select Sequencer;
+Ctrl+3 still opens the modular graph. Stop retains its established position-hold
+behavior and finalizes recording; explicit Pause retains position without
+finalizing a take (and is refused during recording). Home stops and returns to
+zero. Failed candidate installation now refreshes the actual backend state
+even when the previous document is retained.
+
+`make test-workflow` uses a live JACK-compatible backend and Xvfb, with exact
+stereo render comparisons across destruction/recreation of the GUI and live
+playhead/meter/transport checks. `test-gui` covers stop/seek failure and recording
+guards. No project files need manual editing for this workflow.

docs/ROADMAP.md

@@ -166,6 +166,17 @@ within the documented contracts.
 - Common operations do not require manual project-file edits.
 - Transport and GUI state remain consistent during normal playback and error conditions.
 
+Implemented: explicit Pause/F7 and To start/Home controls, position-preserving
+Stop compatibility, recording guards, sequencer selection on New/Open, first-use
+composition/routing guidance, and GUI status refresh after failed installation.
+A real GUI/backend workflow test creates MIDI and audio, arranges/routes, saves,
+closes/destroys the window, reopens in a fresh window, compares exact stereo
+rendering and stable clip/routing metadata, then plays/seeks/pauses/resumes,
+continues editing with undo/redo and saves/reopens again. Mock failure tests and
+live JACK/GUI/software MIDI tests pass. See WORKFLOW.md for instructions,
+transport semantics, test commands and limits. External playback routing remains
+explicit; physical-device listening and endurance remain unqualified.
+
 ## Phase 12 — Audio Quality and Transport Correctness
 
 **Goal:** Make timing and audio output predictable and musically reliable.

docs/WORKFLOW.md

@@ -0,0 +1,98 @@
+# Make and reopen a small project
+
+The default workspace is Sequencer. New and Open return to this workspace;
+Mixer and Modular Graph remain available with Ctrl+2 and Ctrl+3. Start with an
+empty project at 120 BPM, 4/4. Clips default to one bar and piano-roll notes use
+velocity 100; no notes or test oscillators are inserted automatically.
+
+## Create music
+
+1. Start your existing JACK-compatible server, launch `xtc`, and check that audio
+   says ready/stopped. If disconnected, start the server and use Reconnect/F6.
+2. Click Add track, then Add MIDI clip. Click Piano roll (Ctrl+4) and click the
+   grid to draw notes. Drag notes to move them or their right edges to resize.
+   Close the piano-roll window to return to the arrangement.
+3. Drag the clip body to arrange it; drag its edges to trim. Edits snap to
+   sixteenth notes. Add further tracks/clips as needed. Add region creates a
+   **silent placeholder**, rather than audio or MIDI.
+4. Optionally use File/Import WAV (Ctrl+I). The file is placed at the current
+   cursor on the selected track; without a selected track an Audio track is
+   created. Keep the WAV available at its stored path.
+5. MIDI creation supplies an instrument-to-output route, and audio import
+   supplies an audio-to-output route for a new project. No graph editing or
+   project-file editing is required. Ctrl+3 shows these routes if you want to
+   inspect or change them. Existing custom routes are respected; see MIDI.md
+   and AUDIO_FILES.md for routing limits.
+6. In your existing JACK routing tool, connect xtc's `output` and `output_right`
+   ports to left/right playback inputs. Press Play/F5. Mixer/Ctrl+2 shows output
+   meters and track gain/pan/mute/solo. If meters move but nothing is audible,
+   check external playback routing and device levels. xtc does not connect
+   physical ports automatically or start/configure the server.
+
+## Transport
+
+| Command | Behavior |
+| --- | --- |
+| Play / F5 | Prepare the current arrangement and resume at the retained sample position. Already playing is a no-op. |
+| Pause / F7 | Deactivate playback and hold the sample position. Play resumes from there. Disabled during recording. |
+| Stop / F8 | Hold the sample position, preserving the established Stop behavior. During recording, finalize and add the take. |
+| Space | Toggle Play/Stop; while recording it finishes the take. |
+| To start / Home | Stop and seek to sample zero; remain stopped until Play. Disabled during recording. Also resets an offline cursor. |
+| Click timeline ruler | Seek on the sixteenth-note grid while stopped; during playback the seek is refused. |
+| New / Open / Reconnect | Stop and reset the position. New/Open show Sequencer; Reconnect leaves the document intact. |
+
+The backend sample count drives the playhead; its display refreshes every 100 ms.
+Pause/Stop retain the exact sample position even though the ruler displays ticks.
+Arrangement, note and mixer edits stop playback; graph edits can be adopted live.
+A failed stop leaves playback running and the controls reflect that. A failed
+return-to-start seek does not set the cursor to zero. If candidate project
+preparation fails after stopping/seeking, the old document stays loaded and the
+GUI refreshes to its actual stopped position (which may be zero). A parse failure
+occurs before installation and leaves playback alone.
+
+## Save, close and continue
+
+Use File/Save (Ctrl+S), choose a `.xtc` path and retain external WAV files. The
+unsaved title marker clears on success. File/Save As confirms overwrites.
+Close the window, launch xtc again and use File/Open (Ctrl+O), or run
+`xtc /path/to/song.xtc`. The arrangement, stable IDs, routing, notes, mixing and
+automation are restored; the transport starts stopped at zero. Continue drawing,
+importing or moving clips, use Ctrl+Z/Ctrl+Shift+Z for undo/redo, and save again.
+
+New/Open/Quit ask before discarding unsaved edits. They are refused while
+recording: use Stop to finalize the take, then save. Missing media stays silent
+with a warning naming the first bad path; select its clip and use File/Relink
+selected audio. Failed file operations retain the document and show an error;
+check the path, format and permissions. Server loss or rate changes require
+Reconnect; this resets position, so seek again before resuming.
+
+## Repeatable acceptance test
+
+With installed FLTK/JACK development files, Xvfb and an already running
+JACK-compatible server:
+
+```sh
+make all test gui test-gui test-workflow test-gui-jack test-jack-midi
+```
+
+`test-workflow` drives real GUI commands and timeline gestures under Xvfb. It
+creates a track, draws two notes, arranges the MIDI clip two beats later, imports
+a generated WAV and verifies both automatic source routes. It saves and closes,
+destroys the first window, reopens in a fresh window and compares the complete
+stereo offline render exactly (including silence, imported audio and notes).
+It checks stable clip IDs/positions and graph counts, seeks through the ruler,
+plays on the real backend, observes nonzero stereo output meters and advancing
+playhead, pauses/resumes, stops, returns to start, edits/undoes/redoes, saves and
+reopens again. It uses temporary files only and cleans them on success.
+
+`test-gui` injects stop/seek/prepare failures to verify controls, position and
+retained document state, plus recording guards. `test-gui-jack` exercises live
+graph changes, recording and restart/close; `test-jack-midi` checks software
+loopback output. The Phase 11 tests also pass ASan/UBSan with the existing
+fontconfig-only GUI leak suppression, and the GUI/mock suite builds/runs without
+JACK support. Core tests use no GUI leak suppression.
+
+These checks cover a minimal composition workflow, not physical listening or
+endurance qualification. No new dependency, project-format change, plugin host,
+MIDI capture, tempo editor, loop playback, device-routing GUI, or persisted editor
+layout was introduced. See GUI.md, MIDI.md, MIXER.md and LINUX.md for details.