xtc/docs/ROADMAP.md

# Roadmap

## Phase 0 — Baseline
Inspect repository/toolchain, verify Makefile and minimal executable, document
dependencies. No system changes without permission.

Baseline implementation: headless startup/shutdown executable, core tests,
separate debug build, optional FLTK shell build, and header dependencies.
See [BUILD.md](BUILD.md) for toolchain, commands, licensing and limitations.

## Phase 1 — C core and offline processing
Graph data structures, validation, cycle detection, topological ordering,
preallocated buffers, test oscillator, gain and offline render tests.

Implemented: mono ports, transactional cycle rejection, independent compiled
plans, precomputed input routing, oscillator/gain/meter/output, deterministic
variable-block tests and lifecycle/error coverage. See AUDIO_ENGINE.md for API
limits and compatibility behavior.

## Phase 2 — Real-time backend
Choose and implement a Linux backend. Document callback semantics, start/stop,
device errors, shutdown, and safe graph publication.

Implemented: optional JACK-compatible mono backend, explicit audio port routing,
format/xrun/loss status, start/stop/reopen, and bounded pending/retired plan
handoff using lock-free atomics. Hardware-independent failure/concurrency tests
and a 30-second software-loopback run pass. See decision 0004 and AUDIO_ENGINE.md.
Physical hardware playback/endurance and live server-loss recovery remain
unverified; GUI engine controls are implemented in Phase 3.

## Phase 3 — FLTK shell
Main window, transport controls, view switching, backend status, clean startup
and shutdown through the C API.

Implemented: dark FLTK shell, Play/Stop/Reconnect, view/menu shortcuts, backend
state/format/xrun/process status, persistent command errors, timer-based refresh
and retirement collection, and callback-safe close/retry. Mock-backend GUI tests
and live GUI/JACK start/stop/reconnect/close tests pass under Xvfb. Sequencer,
mixer and project-file actions remain placeholders; initial graph is silent. See GUI.md.

## Phase 4 — Modular editor
Draw nodes/ports/edges; create, move and connect nodes; reject invalid edges;
safely submit edits to the C core.

Implemented: scrollable node/port/wire canvas; add/select/move/delete nodes;
drag connections, select/delete wires, and show invalid-edit feedback. C owns
stable IDs, read-only snapshots and transactional edits. Exact accepted graph
snapshots are submitted to the backend; prepared/queued/active state is exposed
through revision acknowledgements. Core/render, GUI rollback, mouse smoke and
live adoption tests pass. See GUI.md and AUDIO_ENGINE.md. Preset parameters,
mono-only processing, fixed canvas and no persistence/undo/zoom remain limits.

## Phase 5 — Project and sequencer
Versioned persistence, stable IDs, tracks, clips, timeline, selection, zoom,
scrolling, and transport synchronization.

Implemented: bounded version-1 project persistence with transactional loads and
temporary-file/fsync/rename saves; stable track/clip/node IDs; silent regions;
track and region creation/deletion, selection, move/trim, timeline zoom/scroll;
sample-counted playhead, pause/resume and stopped seek. Project/graph arrangement
roundtrips, malformed-input, GUI rollback/gesture and live transport tests pass.
See PROJECT_FORMAT.md and GUI.md. Constant tempo/4/4, silent metadata regions,
no undo, asset playback, MIDI or persisted GUI layout are explicit limits.

## Phase 6 — Audio clips and recording
Audio import/playback, recording through bounded buffers, missing-asset
handling, no file I/O in callbacks.

Implemented: bounded PCM16/24/32 and float32 WAV import (mono/stereo downmix),
preloaded overlap-summed clip plans with linear rate conversion, and an audio
source node using ordinary graph routing. A lock-free SPSC ring transfers JACK
input to a control-thread WAV writer; Stop finalizes and adds successful takes.
Version 2 metadata stores external asset references and reads v1. Missing assets
remain silent with reporting and manual relinking. Core, callback, GUI and live
software record/save/reopen/play acceptance tests pass. See AUDIO_FILES.md for
memory/format limits, overflow recovery and deferred physical-device validation.
No new dependency or callback I/O was introduced.

## Phase 7 — MIDI and instrument
MIDI input/events/clips, simple internal instrument, note-off/panic handling,
then a basic piano roll.

Implemented: bounded source-relative note events with stable IDs; sample-offset
JACK MIDI input; a velocity-scaled sine instrument and separate graph source;
panic, note-off, stop and seek handling; and a piano roll for drawing, moving,
resizing and deleting notes. Version 3 saves notes and reads v1/v2 projects.
Core, fault-injection, GUI and live software MIDI/save/reopen/play tests pass.
Acceptance uses drawn notes; MIDI recording and SMF import are deferred.
See MIDI.md for capacities, immediate note-off, routing and hardware limits.

## Phase 8 — Mixer and editing
Gain/pan, meters, mute/solo, automation, undo/redo, keyboard workflow.

Implemented: selectable per-track channel strips with gain/pan and mute/solo;
stereo graph/JACK output and output peak meters; editable gain/pan automation
lanes with sample interpolation; bounded 32-edit C snapshot undo/redo and mixer
keyboard controls. Format v4 persists mixing/automation and reads v1–v3.
Core, GUI rollback/gesture/history and live stereo software playback tests pass.
See MIXER.md for routing, mono compatibility, pan law, history behavior and limits.
Track inserts/sends, live fader adoption, MIDI capture, per-track meters and
advanced automation remain deferred. No project-file editing is needed for the
implemented composition/mixing workflow.

## Phase 9 — Extensibility and release
Native node API, evaluate plugin hosting, licensing review, packaging,
installation tests, performance and recovery tests.

Implemented: versioned native C processor lifecycle and graph source/effect API,
explicit instrument-buffer integration, example and error/retirement tests;
external-hosting evaluation (deferred); dependency/license review; deterministic
source/release targets; core/GUI staged install/uninstall and installed C/C++
consumer tests; headless version/help/metadata validation; offline performance
and process-crash/write-failure recovery tests. Source format stays v4, reading
v1–v3. See NATIVE_API.md, RELEASING.md, LINUX.md, LICENSES.md, PERFORMANCE.md and
RECOVERY.md. Native graphs remain session-only, with unsupported saves preserving
files. No stable binary plugin ABI, external host, system package, autosave or
physical-device/endurance qualification is claimed.

## Phase 10 — Engine Correctness and Reliability

**Goal:** Verify that the existing implementation behaves correctly under realistic workloads before adding more features.

### Tasks

- Audit graph compilation, topological ordering, port compatibility, and cycle detection.
- Test graph replacement while audio is running, including safe reclamation of old processing graphs.
- Verify that audio-thread operations are bounded and non-blocking.
- Test repeated initialization, start/stop cycles, device failures, shutdown, and partial initialization.
- Run AddressSanitizer, UndefinedBehaviorSanitizer, leak checks, and static analysis where available.
- Add regression tests for every bug discovered.
- Document known limitations and thread ownership for shared resources.

### Acceptance criteria

- Reproducible tests cover engine lifecycle, graph changes, error handling, and DSP output.
- No known critical real-time safety defects remain.
- Resource ownership and cleanup behavior are documented.

Implemented: graph/DSP and ownership audit; stereo source-alias correction with
exact-output regression tests; maximum-size reverse-order graph/cycle rollback;
allocation-failure sweeps and callback allocation/free guards; 2000 concurrent
native-plan replacements with control-thread destruction and balanced lifetimes;
repeatable ASan/UBSan/leak and Clang static-analysis targets. Core, no-JACK,
GUI/mock/live JACK, recovery and TSan publication/recorder tests pass. See
RELIABILITY.md for ownership, synchronization, bounded-work analysis, commands
and evidence. Physical-device/endurance validation and trusted native callback
behavior remain explicit limits; no critical realtime safety defect is known
within the documented contracts.

## Phase 11 — Complete Minimal Music-Making Workflow

**Goal:** Ensure a user can create, save, reopen, and play a small musical project without manually editing project files.

### Tasks

- Verify project creation, track creation, clip arrangement, routing, and transport as one integrated workflow.
- Ensure play, pause, stop, seek, and return-to-start behavior are consistent.
- Save, close, reopen, and continue editing projects.
- Provide useful defaults and actionable error messages.
- Keep the sequencer as the default workspace, with the modular graph available when needed.
- Test that GUI state and engine state remain synchronized.

### Acceptance criteria

- A user can create and reopen a small project and reproduce the same arrangement and routing.
- 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.

### Tasks

- Define precise behavior for tempo and meter changes.
- Verify conversion between musical positions and sample positions without accumulated timing drift.
- Test clips and events that cross processing-block boundaries.
- Prevent clicks at clip boundaries and during playback start/stop where appropriate.
- Implement gain ramps and parameter smoothing where abrupt changes could create artifacts.
- Test silence, clipping, denormal values, channel layouts, and unusual supported buffer sizes.
- Document latency reporting and identify whether latency compensation is required by the current architecture.
- Add deterministic tests for sample-accurate event scheduling where supported.

### Acceptance criteria

- Automated tests verify timing conversions and expected sample output.
- Tests cover events and clips at block boundaries and tempo changes.
- Listening tests cover transitions, start/stop behavior, and representative projects.
- Known limitations involving latency and synchronization are documented.

Implemented: documented constant-tempo/fixed-4/4 snapshot policy; absolute timing
and sample-offset regression matrix; configurable audio/scheduled-note boundary
fades; single-owner gain ramps; GUI 5 ms start and asynchronous Pause/Stop fades
with control-thread acknowledgement/deactivation; finite/subnormal output policy;
exact endpoint, block-size, stereo, overload and failure/retry tests. Latency and
synchronization limits are documented in AUDIO_QUALITY.md. Normal/no-JACK,
sanitizer/static-analysis, TSan, GUI/workflow/live JACK and install checks pass.
`make quality-preview` generates matched listening WAVs. Human listening and
physical-device acceptance remain pending; immediate safety/recording/seek paths
and live graph swaps may still click. No tempo/meter map, latency compensation,
limiter or project-format change is claimed.

## Phase 13 — Recording and Recovery

**Goal:** Protect recorded material and handle recording failures predictably.

### Tasks

- Test long recordings and recording-buffer saturation.
- Handle disk-full conditions, write errors, interrupted recording, and unavailable destinations.
- Keep file I/O outside the real-time audio callback.
- Define and implement recovery or clear reporting for incomplete recordings.
- Make recording destinations and supported file formats explicit.
- Protect existing files from accidental overwrites.
- Test reopening projects when media files are missing, incomplete, or inaccessible.
- Ensure shutdown and project closure do not silently discard pending recorded data.

### Acceptance criteria

- Recording failures are reported clearly and do not cause unsafe audio-thread behavior.
- Valid recorded material is preserved whenever possible.
- Incomplete recordings and missing media are detected and explained.
- Recording and recovery behavior is covered by automated or repeatable integration tests.

Implemented: no-clobber recording destinations and race-safe publication;
explicit opt-in replacement API; retained failed temporaries and recovery-path
reporting; streaming `xtc-check --recover-recording TEMP NEW.wav` salvage;
quiescent destructor draining and exceptional-shutdown reporting. Virtual
30-minute recording, saturation/concurrency, destination races, disk-write
failure/prefix recovery, killed writers and missing/incomplete media tests pass.
See AUDIO_FILES.md and RECOVERY.md. Physical endurance, power-loss guarantees
and playback of assets above the existing preload limit remain unqualified.

## Phase 14 — Native Plugin, Instrument, and Effect Architecture

**Goal:** Provide a stable internal extension interface before hosting external plugins.

### Tasks

- Finalize the native C node API, including initialization, processing, reset, and destruction.
- Define parameter metadata, defaults, valid ranges, and automation behavior.
- Specify audio channel layouts and MIDI/event handling.
- Define node state serialization and restoration requirements.
- Establish rules for node creation, failure, reconfiguration, and destruction.
- Ensure the GUI uses documented public APIs rather than internal engine structures.
- Provide a small example instrument and effect implemented against the public interface.
- Document ABI/API compatibility expectations for native extensions.

### Acceptance criteria

- A developer can implement a small native instrument or effect using documented interfaces.
- Invalid parameters, unsupported layouts, and failed initialization are handled safely.
- Node state can be saved and restored where required.
- No C++ or FLTK types leak into the public C API.

Implemented: ABI 2 parameter-only C processor lifecycle with copied descriptors,
metadata/default/range validation, sample-offset parameter/MIDI ordering,
transactional portable configuration restoration, and public gain/instrument
examples. Lifecycle, invalid input, event ordering, in-place output, reset,
callback failure and state compatibility tests pass. See NATIVE_API.md. ABI 1
graph compatibility is retained; native graph persistence and opaque plugin
state are explicitly outside this parameter-only interface.

## Phase 15 — External Plugin Hosting

**Goal:** Add external plugin support only after the internal node lifecycle is reliable.

### Tasks

- Evaluate candidate plugin formats for licensing, dependencies, maintenance, and Linux support.
- Record the selected format and rationale in an architecture decision document.
- Implement plugin discovery and loading outside the real-time callback.
- Map plugin audio ports, parameters, MIDI/events, and channel layouts to the engine's node model.
- Support plugin state save/load and clear reporting for missing or incompatible plugins.
- Test plugins with different channel counts, parameter sets, and processing requirements.
- Define how plugin failures are reported and how the engine recovers.
- Document crash-isolation limitations; an in-process plugin must not be assumed safe merely because the host is safe.

### Acceptance criteria

- A small, documented set of compatible third-party plugins can be loaded, connected, saved, reopened, and played.
- Missing or incompatible plugins do not silently corrupt the project.
- Plugin loading and destruction do not occur in the real-time callback.
- The chosen format's dependencies and licensing are documented.

Implemented: bounded LADSPA 1.1 C host with explicit file/index discovery,
control-thread loading/lifecycle, mono source/effect graph mapping, independent
stereo instances, metadata/range checks and v5 identity/control persistence.
Public-API GUI load/configure commands support ordinary routing/save/reopen and
undo. Fixture/error/retirement/GUI tests and installed amp/inverter/sine acceptance
pass. See decision 0009, PLUGIN_HOSTING.md and LICENSES.md. MIDI, true multichannel
layouts, opaque state, editors, latency compensation and crash isolation are
unsupported; plugin realtime behavior and physical listening are unqualified.

## Phase 16 — Automation and Expressive Control

**Goal:** Make automation and MIDI control reliable, sample-timed, and usable.

### Tasks

- Support automation for common parameters such as volume, pan, instrument parameters, and effect parameters.
- Define interpolation modes and behavior at clip boundaries.
- Evaluate automation at the correct time and sample offsets for each processing block.
- Smooth parameter changes where needed to avoid zipper noise or audio artifacts.
- Add MIDI controller mapping where appropriate.
- Handle note-off, panic, seek, stop, project teardown, and device disconnect correctly.
- Define deterministic ordering for MIDI and automation events that occur at the same sample position.
- Test overlapping notes, repeated note-ons, and interrupted playback.

### Acceptance criteria

- Automation and MIDI control reproduce consistent results across repeated playback and project reloads.
- Held notes are released safely on stop, panic, seek, and relevant failure paths.
- Event ordering and interpolation behavior are documented and tested.

Implemented: persisted sample-evaluated LADSPA parameter lanes with linear/step
modes, range/discrete validation and public GUI editing; absolute automation
position through seek and plan handoff; fixed live CC7/10/64 mappings with volume/
pan ramps, sustain/retrigger safety, and exact block-partition regressions.
Existing track Gain/Pan lanes cover audio and scheduled instrument volume.
Format v6 migrates v1–v5. See CONTROL.md. MIDI capture/learn, pitch bend, new
instrument timbres and physical listening remain outside the supported scope.

## Phase 17 — Editing Workflow, Undo/Redo, and Usability

**Goal:** Make common editing tasks efficient and protect users from accidental changes.

### Tasks

- Make common operations undoable, including create, delete, move, trim, duplicate, and connect.
- Define undo behavior for recording and destructive operations.
- Add consistent keyboard shortcuts and context menus for frequently used actions.
- Implement predictable snapping, grid settings, zoom, scrolling, and selection behavior.
- Improve clip labels, track organization, and visual feedback.
- Make destructive actions difficult to trigger accidentally.
- Keep the GUI responsive while audio is running.
- Ensure undo/redo updates project state and the active engine graph consistently.
- Test keyboard focus and accessibility of essential controls where practical.

### Acceptance criteria

- Common editing workflows can be completed without unnecessary dialogs or manual workarounds.
- Undo/redo restores the intended project state and corresponding engine state.
- GUI operations do not block the real-time audio thread.
- Interaction behavior is documented and covered by relevant tests.

Implemented: transactional full-source clip duplication, clip/track names,
track ordering, configurable timeline snap, Ctrl+D/F2/Alt+arrow commands and a
context menu; kind/name clip labels and focus regressions. Snapshot/GUI tests
verify duplicate/rename/order undo/redo, source-note retention, capacity rollback
and existing graph/backend history behavior. Recording undo removes references,
never media. See WORKFLOW.md. Background loading, persisted UI layout and broad
screen-reader/accessibility qualification remain explicit limits.

## Phase 18 — Project Format, Compatibility, and Portability

**Goal:** Keep project files valid, recoverable, and maintainable over time.

### Tasks

- Version the project format and implement explicit migration logic when the format changes.
- Validate project data before constructing engine objects from it.
- Handle malformed files, unknown node types, missing assets, and unavailable plugins.
- Define project-folder behavior and reliable media path handling.
- Make saving robust against interrupted writes, for example by writing a temporary file and replacing the destination safely where supported.
- Test save/load round trips and migration from every format version that is supported.
- Keep the format documented and preferably human-inspectable.
- Avoid silently discarding unknown data during load/save unless the format policy explicitly requires it.

### Acceptance criteria

- Supported older projects load correctly or produce clear, actionable compatibility errors.
- Malformed project files do not crash the application or trigger unsafe allocations.
- Missing media and plugins are reported clearly.
- Save/load round trips and format migrations have automated tests.

Implemented: v7 folder-relative media persistence with absolute runtime references,
transactional resolution independent of launch cwd, Save As identity preservation,
and parent-directory fsync after atomic publication. Checked-in v1–v6 migrations
(including missing plugins), moved-folder exact playback, missing-media retention,
truncation/mutation and unknown-record/error tests pass. See PROJECT_FORMAT.md.
No media is copied/deleted automatically; absolute external/plugin dependencies,
path bounds, post-rename sync errors and physical power-loss limits are explicit.

## Phase 19 — Performance, Scalability, and Stress Testing

**Goal:** Measure performance and establish predictable behavior as projects grow.

### Tasks

- Create repeatable benchmarks for increasing node counts and audio channel counts.
- Measure processing time at supported sample rates and block sizes.
- Profile graph compilation separately from real-time audio processing.
- Identify unnecessary buffer copies, allocations, and redundant processing.
- Test large arrangements, many clips, automation events, and active meters.
- Define bounded processing limits and meaningful overload diagnostics.
- Test under CPU pressure and during frequent GUI redraws.
- Optimize only after profiling identifies a meaningful bottleneck.
- Record baseline benchmark results so regressions can be detected.

### Acceptance criteria

- Performance targets and test conditions are documented.
- Repeatable benchmarks cover representative small and large projects.
- Overload behavior is defined and does not cause unbounded work in the callback.
- Significant performance regressions can be detected through repeatable tests.

Implemented: 24-case node/channel/rate/block matrix with separate compilation
and warmed process timings, recorded machine/compiler baseline and opt-in
regression budgets; maximum track/clip/note/automation/meter capacity checks and
publication/GUI tests under CPU contention. Measurements justified skipping
unused live-controller processing; exact output tests remain passing. See
PERFORMANCE.md and performance-baseline.json for results, thresholds and overload
policy. Arbitrary plugin costs and physical realtime/endurance are unqualified.

## Phase 20 — Release Engineering, Packaging, and Maintenance

**Goal:** Make the application straightforward to build, install, use, diagnose, and maintain.

### Tasks

- Provide reproducible release builds and clean build instructions.
- Add Makefile targets for building, testing, installing, and uninstalling.
- Package the application and required resources for the initial supported Linux target.
- Review licenses and attribution for direct and bundled dependencies.
- Document supported audio backends, required system packages, and configuration.
- Add useful crash and error diagnostics without compromising real-time processing.
- Test fresh installations, upgrades, missing dependencies, and removal.
- Publish a basic user manual, developer documentation, and a known-limitations list.
- Define a release checklist and a policy for handling regressions and project-format compatibility.

### Acceptance criteria

- A person other than the primary developer can build or install the application using the documented steps.
- The installed application can complete the supported core workflow.
- Installation and removal are tested on the initial target environment.
- Dependencies, licensing, limitations, and troubleshooting steps are documented.
- A release can be reproduced from a clean checkout with recorded build instructions.

Implemented: normalized Linux binary/development archives with SHA-256/file/
ELF-dependency manifests, headless compiled-feature diagnostics, repeat-install
upgrade/repair and installed C/C++ save/reopen/render checks. Existing deterministic
source/release, no-dependency, sanitizer, staged uninstall and GUI/live tests are
retained. USER_MANUAL.md, KNOWN_LIMITATIONS.md and MAINTENANCE.md consolidate setup,
operation, licensing/diagnostics, release and regression policy. No public release
or distro registration is performed. Independent human installation/usability,
physical-device/endurance and listening acceptance remain pending and must be
completed before claiming production qualification.

## Phase 21 — Advanced MIDI and Composition

### Goal
Make MIDI composition expressive and efficient without turning the application into an unnecessarily complicated notation editor.

### Tasks
- Improve piano-roll editing for note creation, selection, movement, resizing, and deletion.
- Support configurable snap and grid resolution, including triplets where practical.
- Add velocity editing and editing for supported MIDI note properties.
- Support MIDI channel and note-range filtering where appropriate.
- Improve quantization, transposition, duplication, and pattern repetition.
- Ensure MIDI event ordering is deterministic, especially when note-off and note-on events share a timestamp.
- Define handling for overlapping notes, repeated notes, and malformed MIDI events.
- Add regression tests for MIDI editing and playback scheduling.

### Acceptance criteria
- Common MIDI editing tasks can be completed without manually editing project files.
- Editing preserves unrelated notes and event properties.
- MIDI scheduling remains deterministic at buffer boundaries and under transport changes.
- MIDI operations are covered by automated tests.

Implemented: transactional C filtered note transforms, nearest-grid quantization,
velocity/channel edits, transposition, bounded fresh-ID repetition and deletion;
piano-roll Notes menu, keyboard commands, configurable straight/triplet grids,
channel/pitch filtering and filtered-set selection. Existing mouse move/resize
and project undo/redo remain supported. Core and GUI regression tests demonstrate
property/other-clip preservation, rollback, undo/redo, adjacent/overlapping notes,
equal-offset caller ordering, exact block partitions and seek chase. See MIDI.md.
No format change, MIDI capture, SMF import, lasso selection or piano-roll zoom;
physical-device and listening validation remain pending.

Acceptance evidence:
- [x] Menu/keyboard/mouse commands edit notes without project-file editing.
- [x] Filtered batch tests preserve unmatched notes and unrelated properties.
- [x] Exact scheduling tests cover buffer boundaries and transport seeks.
- [x] Core composition and GUI undo/redo regressions exercise these operations.

## Phase 22 — Audio Clip Editing and Utility Operations

### Goal
Provide focused, non-destructive audio editing tools for arranging and preparing recorded or imported material.

### Tasks
- Support moving, trimming, splitting, duplicating, and deleting audio clips.
- Define clip-boundary behavior, including fades and source offsets.
- Add non-destructive clip gain and basic fade-in/fade-out controls.
- Support time-stretching and pitch-shifting only after selecting a suitable implementation and quality target; otherwise document them as future work.
- Ensure edits do not unexpectedly modify source audio files.
- Add waveform display caching that never blocks the audio thread.
- Test edits at project boundaries, source-file boundaries, and very short clip lengths.
- Document which operations are destructive and non-destructive.

### Acceptance criteria
- Basic clip editing is predictable and undoable.
- Source files remain unchanged unless a documented destructive operation is explicitly invoked.
- Clip boundaries do not produce unintended clicks from invalid offsets or discontinuities.
- Editing and waveform generation never perform blocking work in the real-time audio callback.

Implemented: transactional audio/silent-clip splitting with stable IDs and source
offsets; persisted linear clip gain and explicit in/out fades in v8 (v1–v7 migrate
to unity/no explicit fades); undoable sequencer menu/context/keyboard controls;
immutable bounded source-peak summaries shared across clips and drawn from
cached memory. Existing move/trim/duplicate/delete remain supported; very short
clip hit testing now matches drawing. See AUDIO_FILES.md and PROJECT_FORMAT.md.
Stretch/pitch processing and crossfades remain future work; waveform loading is
synchronous on the control thread, and physical listening remains pending.

Acceptance evidence:
- [x] Core/GUI regressions cover split/duplicate/delete and snapshot undo.
- [x] Exact byte comparison verifies source files survive all metadata edits.
- [x] Boundary tests cover invalid offsets, short tails, one-frame media, explicit
      fade endpoints, gain, block partitions, seeks and capacity rollback.
- [x] Waveform construction stays on control-thread paths; redraw reads cached
      peaks and audio rendering retains immutable/preloaded callback storage.

## Phase 23 — Modular Workflow and Routing Refinement

### Goal
Preserve the modular spirit of the application while making complex projects understandable and manageable.

### Tasks
- Refine graph and routing views so signal paths are easy to inspect.
- Make connections, disconnections, and invalid routing states clear.
- Provide useful names and visual distinctions for tracks, instruments, effects, buses, and I/O ports.
- Support track grouping or folders if the project model can represent them cleanly.
- Add routing presets or reusable track templates only if they do not complicate the core model.
- Define behavior for cycles and feedback paths; reject unsupported cycles explicitly.
- Make graph changes transactional so failed edits do not leave partially updated routing.
- Add tests for graph changes while playback is running.

### Acceptance criteria
- Users can inspect and understand a project's signal path.
- Invalid graph edits fail safely and leave the previous valid graph intact.
- Graph updates follow the documented real-time synchronization strategy.
- GUI routing concepts map cleanly to the public C engine API.

Implemented: cached public C routing analysis (edge counts, longest-path levels,
output reachability and external-input fallback); directional/highlighted wires,
role colors/labels, no-output badges, selection inspection and keyboard navigation;
scrollable signal-flow auto-layout and non-overlapping initial placement. Atomic
unity-gain wire insertion is one undoable C edit using existing node persistence.
Core and mock/live GUI tests cover rollback, complete plan adoption, cycles,
disconnect/restore and undo/redo. See ROUTING.md. Flat tracks/shared audio/MIDI
sources do not yet represent folders or per-track routing templates; these
conditional tasks are deferred. No format change, feedback processing, latency
compensation or physical listening qualification is claimed.

Acceptance evidence:
- [x] Direction/role labels, layout and public routing diagnostics expose paths.
- [x] Invalid/capacity/backend-failed commands retain the previous graph/plan.
- [x] Live JACK graph tests verify complete block-boundary plan adoption.
- [x] GUI routing analysis and edits use public C APIs; callback ownership is unchanged.

## Phase 24 — Mixing and Mastering Essentials

### Goal
Provide the essential mixing controls needed to finish a small or medium-sized project.

### Tasks
- Complete track and bus gain, pan, mute, solo, and metering behavior.
- Define how solo states affect buses, sends, and sidechains.
- Add peak meters with clear units and documented ballistics.
- Add master-bus monitoring and clipping indicators.
- Support routing to buses and auxiliary sends if the graph model supports them.
- Make gain staging explicit and avoid hidden or surprising level changes.
- Document meter tap points and whether values are pre-fader, post-fader, or post-effects.
- Test mute, solo, pan, gain, and routing interactions.

### Acceptance criteria
- [x] Mixer controls behave consistently across tracks, buses, and master output.
- [x] Meter readings correspond to documented signal points and units.
- [x] Solo and mute behavior is covered by automated tests.
- [x] No mixer operation introduces allocations, locks, or other prohibited work in the audio callback.

Implemented: one-level stereo mix buses with routing, shared gain/pan automation,
inclusive solo and mute precedence; coherent audio/MIDI track and bus peaks;
interval master peaks, dBFS ballistics and sticky clipping; v9 persistence reading
v1–v8. See MIXER.md for exact taps, gain staging and callback scratch bounds.
Independent per-track aux sends/sidechains and per-bus graph effects remain
conditional/deferred because graph sources still expose shared mixes.

Validation: warning-enabled core/GUI builds and unit/integration tests, bus and
backend fault tests, GUI plugin/workflow tests, software JACK GUI/audio/MIDI,
allocation-failure/callback-allocation guard, static analysis, installation and
package relocation, optional-dependency-free build, and core/GUI ASan+UBSan.
The live MIDI connection test required one retry after a JACK connection failure;
its full playback assertions passed on retry. GUI leak checks use the existing
fontconfig suppression; core checks are unsuppressed. Physical hardware,
human listening and extended high-density endurance remain unverified.

## Phase 25 — Plugin and Instrument Usability

### Goal
Make instruments and effects practical to use, manage, and diagnose in real projects.

### Tasks
- Improve plugin discovery, insertion, removal, replacement, and ordering.
- Show useful plugin identity and status information, including load failures.
- Define parameter metadata, ranges, defaults, units, and formatting.
- Support parameter reset and safe default values.
- Preserve plugin state across save/load where the plugin API supports it.
- Define behavior when a saved plugin is missing or incompatible.
- Manage plugin UI lifetime separately from engine object lifetime.
- Add tests for plugin lifecycle, state restoration, and failure paths.
- Document plugin API versioning and compatibility expectations.

### Acceptance criteria
- [x] Users can identify and manage loaded instruments and effects without editing configuration files.
- [x] Missing or incompatible plugins produce actionable diagnostics and do not silently corrupt projects.
- [x] Plugin state restoration is tested for supported plugin types.
- [x] The engine remains safe if plugin initialization or processing fails, within the documented failure model.

Implemented for the supported LADSPA 1.1 mono effects/audio sources: explicit
module descriptor browser, copied identity and control metadata, generic parameter
editor with validated Apply/Cancel and defaults reset, compatible-layout
replacement preserving node ID/wires, and atomic effect insertion on a selected
wire. Graph connections define order and existing deletion removes incident
wires. Edits integrate with undo/redo and compile before adoption. State uses
existing v9 parameter/automation records; missing/incompatible plugins retain the
current document and report recovery guidance. Native processor ABI 2 remains
unchanged. See PLUGIN_HOSTING.md and RECOVERY.md.

Validation: warning-enabled core/GUI builds; full unit/integration suite;
fixture and installed amp/inverter/sine plugin tests; actual chooser/editor GUI
tests; reset/cancel, insertion, replacement, removal and undo; layout/init/missing
module rollback; exact persisted rendering and noncommutative processing order;
callback allocation/module-lifetime guards, reliability and static analysis;
software JACK GUI/audio/MIDI and workflow; dependency-free build; installation
and package relocation; ASan/UBSan including generic-dialog lifetimes (existing
fontconfig leak suppression for GUI/system font allocations).

Qualification remains the documented in-process failure model: LADSPA cannot
signal run failure or contain crashes/hangs. No external editor, opaque state,
MIDI-capable plugin instrument, recursive scanner or new format was added.
Physical listening and arbitrary third-party plugin/endurance qualification
remain pending.

## Phase 26 — Automation and Control Mapping

### Goal
Enable repeatable changes to mix and instrument parameters over time, with clear timing and ownership rules.

### Tasks
- Define a common parameter identity and metadata model.
- Support automation lanes for a carefully selected set of parameters.
- Define interpolation modes and behavior at clip boundaries.
- Specify how automation interacts with live parameter changes and MIDI control.
- Add control mapping for selected external MIDI controllers if feasible.
- Schedule automation deterministically without allocating memory in the audio callback.
- Define behavior when a target parameter or plugin is missing.
- Test automation at buffer boundaries, during seeks, and across loop points.
- Document precedence rules for automation, controller input, and direct user changes.

### Acceptance criteria
- [x] Supported parameters can be automated and saved in a project.
- [x] Playback produces deterministic automation values for a given project and transport position.
- [x] Missing targets fail safely and are reported to the user.
- [x] Automation processing meets the engine's real-time safety requirements.

Implemented: common stable owner/parameter keys and copied metadata for
track/bus gain/pan, LADSPA input controls and live sine controller targets;
validated common static/lane edit APIs; per-point linear/hold mixer automation;
per-channel saved volume/pan/sustain CC bindings with explicit disable and reserved
panic controllers. GUI adds Interpolation and Audio/MIDI controller mapping;
edits participate in undo/redo. Project v10 reads v1–v9 with linear/default-map
migration. CONTROL.md documents target identity, clip boundaries, precedence,
missing-target handling, controller ramps and real-time ownership.

Validation: warning-enabled core/GUI builds and full tests; common metadata,
missing owner/port/module failures and retained state; exact step/ramp endpoints,
low-rate collisions, odd blocks, seeks and explicit backward wraps; default/
remapped/disabled/unmapped CCs and stereo pan, immutable maps after preparation;
GUI map/interpolation/save/Open/undo/redo and invalid-edit rollback; v1–v9
migration, v10 exact persistence and malformed records; fixture/installed plugin
tests, callback-allocation guards, reliability/static analysis, performance and
capacity tests; software JACK GUI/audio/MIDI and workflow; dependency-free build,
installation/package relocation, core/GUI ASan+UBSan (existing fontconfig leak
suppression only for GUI/system font allocations).

No loop transport, MIDI learn/capture, write/touch/latch modes, arbitrary MIDI
mapping to arranged faders/plugins, timbre parameter for the built-in sine or
opaque-plugin seek restoration is claimed. Live MIDI targets have reset-default
metadata and controller bindings, not timeline lanes. Physical controllers,
listening and extended third-party-plugin endurance remain unverified.

## Phase 27 — Editing Workflow, Undo/Redo, and Usability

### Goal
Make common editing actions quick, discoverable, and safe to reverse.

### Tasks
- Audit user-visible editing operations for undo/redo support.
- Implement command-based edits with explicit ownership and rollback behavior.
- Group related low-level changes into one meaningful undo step.
- Define undo behavior for operations affecting engine state or external files.
- Improve keyboard shortcuts, selection behavior, focus handling, and context menus.
- Use confirmation only for genuinely destructive or difficult-to-reverse actions.
- Provide clear feedback for long-running operations and failures.
- Add GUI tests or reproducible manual test procedures for critical workflows.
- Keep presentation logic out of the core C engine.

### Acceptance criteria
- [x] Documented editing operations have predictable undo/redo behavior.
- [x] Undo and redo restore the project model and relevant engine state consistently.
- [x] Failed operations do not leave partial changes behind.
- [x] Common tasks can be completed using documented keyboard and mouse interactions.

Implemented: operation-by-operation audit in EDITING.md; reserved history storage
before GUI command mutation/candidate publication, followed by allocation-free
snapshot capture; recording start creates no empty history entry and each
completed take is one undoable reference edit; unavailable main-menu history
steps disabled; surviving editor selections and open piano-roll context retained
on undo; piano-roll history shortcuts/context menu and pointer-targeted graph
context menus; input focus guards and synchronous busy feedback. Existing C
graph/batch note commands and snapshot history remain the model boundary; FLTK
presentation stays in C++. No project format change (v10 retained).

Validation: warning-enabled core/GUI builds and full tests; interposed allocation
failure for each history reservation and capture with all allocations disabled;
GUI history-reservation failure retains document, engine submission count and
redo; completed-take undo grouping retains WAV; selection/context-target tests;
existing grouped gestures/batches, candidate/backend rollback and save/reopen;
workflow/software JACK GUI integration, reliability/callback guards, Clang static
analysis, core/GUI ASan+UBSan, optional-dependency-free build, installation and
package relocation. GUI sanitizer runs retain the existing fontconfig-only leak
suppression. EDITING.md supplies a reproducible native manual procedure for
popup dismissal, text focus, large synchronous operations and recorded takes.

Native manual popup/focus/large-file usability checks, broad accessibility and
physical-device listening/endurance remain pending. History remains bounded and
session-only; selection/layout history, arbitrary command grouping, background
loading and destructive source-media editing are not supplied. Preparation
failure can stop/reset transport while retaining the old document/history.

## Phase 28 — Project Format, Compatibility, and Portability

### Goal
Make project files robust, diagnosable, and maintainable across application versions and supported systems.

### Tasks
- Version the project format and document its compatibility policy.
- Validate project input before applying it to the live engine.
- Handle missing media, plugins, and external dependencies with clear diagnostics.
- Define relative-path, absolute-path, and media-relocation behavior.
- Add safe migration routines for supported older versions.
- Preserve unknown optional fields where practical, or document when they cannot be preserved.
- Test malformed files, truncated files, oversized input, and invalid values.
- Make saves atomic where the platform permits, using a temporary file and replacement strategy.
- Document portability limits, including plugin and audio-backend dependencies.

### Acceptance criteria
- Invalid project files are rejected safely without partially replacing the current project.
- Save failures do not silently destroy the previous valid project file.
- Version incompatibilities and missing dependencies are clearly reported.
- Supported project versions have migration and regression tests.

### Implementation status
Completed: version-10 compatibility policy and v1–v10 fixture migration;
transactional diagnostic loading in the core and GUI; metadata-only dependency
inspection with explicit availability limits; relocation and unknown-field
policies; bounded-input and deterministic pre/post-rename save-failure coverage.
No format bump was needed. Linux/POSIX, plugin ABI/path and audio-backend limits
are documented in PROJECT_FORMAT.md and RECOVERY.md.

Validation: full core/GUI/plugin/JACK/workflow/recording/recovery tests, static
analysis, staged installation and binary packaging; minimal no-JACK/no-LADSPA
build and tests; ASan/UBSan core, reliability and recovery tests.

## Phase 29 — Performance, Scalability, and Stress Testing

### Goal
Establish measurable performance expectations and verify that larger projects remain stable.

### Tasks
- Define representative test projects and target buffer sizes.
- Measure audio callback duration, deadline misses, CPU use, memory use, and graph rebuild costs.
- Test projects with increasing numbers of tracks, graph nodes, connections, MIDI events, and automation points.
- Test long playback sessions and repeated start, stop, seek, and loop operations.
- Stress-test device changes, plugin failures, missing media, and project reloads.
- Use profiling to identify bottlenecks before introducing optimizations.
- Verify that the real-time callback does not allocate, block on mutexes, perform file I/O, or wait on GUI work.
- Document expected limits and known performance bottlenecks.
- Add sanitizers and static analysis to regular development builds where supported.

### Acceptance criteria
- Performance is measured against documented test cases, not subjective impressions alone.
- Stress tests can run repeatedly and produce reproducible results.
- No known real-time safety violation remains in the engine's own callback path.
- Performance regressions can be detected by repeatable tests or benchmark reports.

### Implementation status
Implemented with the existing graph/capacity/fault infrastructure plus Phase 29
project scaling matrices, CPU/RSS/deadline metrics, checked-in reports, virtual
endurance, repeated reload/device/plugin fault suites, wider host callback guards
and a combined development/sanitizer/static-analysis target. See PERFORMANCE.md
for exact workloads, profiling evidence and qualification limits.

Validation: normal core/GUI/JACK/plugin/recovery/recording suites, three-round
CPU-contention stress, 2.282-hour virtual playback, minimal build, ASan/UBSan,
static analysis and benchmark-gate regression tests passed. Project timing
comparison passed. Graph comparisons detect shared-host variation (including a
16-node mono/31-frame alert in a longer run); the prior baseline is retained and
this limitation is recorded rather than suppressing the gate. Hardware and
wall-clock endurance remain unqualified.

## Phase 30 — Release Engineering, Packaging, and Maintenance

### Goal
Turn the application into a maintainable release that users can build, install, run, and troubleshoot.

### Tasks
- Define supported operating systems, compiler versions, and audio backends.
- Document build dependencies and provide clear build and test commands.
- Add install and uninstall targets that respect `PREFIX` and standard directory variables.
- Provide appropriate package metadata and desktop integration where relevant.
- Verify installation paths for binaries, libraries, headers, resources, documentation, and example projects.
- Add version reporting and a concise diagnostic mode where useful.
- Prepare release notes, known limitations, and upgrade guidance.
- Test clean builds from a fresh checkout and installation into a staging directory.
- Define a release checklist covering tests, warnings, packaging, and project compatibility.
- Document how users can report reproducible bugs and how maintainers should triage them.

### Acceptance criteria
- A clean checkout can be built and tested using documented commands.
- Installation works with a configurable prefix and does not overwrite unrelated user files.
- The release includes documentation, known limitations, and a reproducible version identifier.
- The project has a repeatable process for preparing and validating releases.

### Implementation status
Completed: configurable standard install directories with one shared owned-file
inventory, staged file/symlink safety checks, installed metadata-only MIDI example
and all performance resources, source SHA-256 sidecars, release notes, upgrades,
support matrix and maintenance/triage guidance. Existing version/diagnostic modes,
desktop metadata and normalized source/binary packaging are retained.

Acceptance verified with warning-enabled core/GUI builds and tests; default and
custom-layout staged install/repair/uninstall with C/C++ consumers; minimal
no-JACK/no-FLTK/no-LADSPA build; two clean source-export release builds with
byte-identical binaries and repacks; and binary manifest/hash/relocation checks.
No public release, tag, version bump or system install is performed. Physical
qualification and the Phase 29 graph timing alert remain documented limitations.

## Phase 31 — CLAP, VST2 and VST3 Plugin Loading

### Goal
Load trusted Linux CLAP, VST2 and VST3 audio effects through the graph and GUI,
with explicit lifecycle, format compatibility and realtime ownership contracts.

### Tasks
- Review and pin redistributable ABI headers and license notices; keep C99 adapters.
- Add explicit format probing and compatible mono float32 effect initialization.
- Integrate processing, immutable plans, retirement and failure rollback.
- Share module entry lifetimes across overlapping instances; defer main-thread callbacks.
- Add format/stable identity metadata with v11 migration and missing-module retention.
- Generalize the GUI browser, insertion/replacement and identity presentation.
- Test original fixtures for all three ABIs, partial failure cleanup, callback safety,
  save/reopen, missing dependencies and GUI lifecycle.
- Document the initial default-configuration effect subset and unsupported extensions.

### Acceptance criteria
- Compatible fixtures for all three formats render exact expected audio in graphs.
- Failed loading/identity/layout/initialization retains the current project/plan.
- Loading and reclamation remain off the audio callback, with bounded host processing.
- Project files preserve identity and missing references without executing plugins.
- Core/GUI builds, regressions, sanitizers and release installation checks pass.

### Implementation status
Implemented in C99 with pinned permissive ABI headers, shared entry lifetimes,
CLAP main-thread scheduling, graph/GUI integration and v11 plugin identity.
Normal/minimal builds, core and GUI plugin fixtures, live JACK/workflow,
ASan/UBSan core and GUI checks, static analysis, staged installation and
source/binary release checks pass. Tests include activation/start/process and
restart errors, rejected layouts/identities, missing modules and retirement.
GUI leak checking retains only the existing Fontconfig suppression; core checks
use none. Only original ABI fixtures are qualified; arbitrary third-party plugins
and physical audio remain unverified. See PLUGIN_HOSTING.md and decision 0010.

The initial subset excludes instruments/events, editable modern parameters,
opaque state/custom editors, true stereo/multichannel and latency compensation.
These require separate future work; they are not claimed as implemented by loading.

---

## Phase 32 — MIDI Track Plugin Instruments

### Goal
Play CLAP, VST2 and VST3 synthesizer/instrument plugins from MIDI clips and live MIDI.

### Tasks and acceptance criteria
- [x] Discover and initialize compatible zero-input, mono float32, zero-latency instruments.
- [x] Bind independent instances to tracks; preserve built-in sine for unassigned tracks.
- [x] Deliver sample-offset notes and bounded event queues without callback allocations.
- [x] Apply track/bus mixing and provide an explicit saved live-MIDI target.
- [x] Handle discontinuity note chase, panic, teardown and failed preparation.
- [x] Save bindings in v12; migrate v1–v11 and retain missing module references.
- [x] Add GUI load/clear/live-target commands with undo and candidate preparation.
- [x] Test original fixtures for all three formats and document the supported subset.

### Implementation status
Implemented with track-owned prepared instances and 256-frame processing chunks.
Only original ABI fixtures are qualified; arbitrary third-party instruments and
physical MIDI/audio hardware remain unverified. Mono/default configuration only;
no custom editors, opaque state or modern parameter automation. Native-note CLAP
and VST3 carry notes only; CLAP MIDI and VST2 also receive live controllers.
Seeking retriggers held scheduled notes with fresh envelopes; plugin release tails
can remain after note-off/panic. See PLUGIN_HOSTING.md and decision 0011.

Validation: normal/minimal core and GUI builds, core/instrument/GUI fixtures,
JACK/workflow, reliability, ASan/UBSan core and GUI, static analysis, staged
installation, reproducible source releases and relocatable binary packages pass.

---

## Phase 33 — Flat Modern DAW Workspace

### Goal
Give xtc a clear, modern DAW presentation for creating tracks and arranging
music, with simple flat controls and no 3D styling or proprietary assets.

### Tasks and acceptance criteria
- [x] Introduce one shared dark palette, typography, flat controls and focus/selection accents.
- [x] Make track creation, import, instrument loading and MIDI editing visible in a persistent sidebar.
- [x] Create/select MIDI tracks with clips and audio tracks transactionally, with undo and failure rollback.
- [x] Organize transport, musical position/BPM, main editors, inspector and status in a resizable workspace.
- [x] Draw colored track headers, clear clip selection, bar/beat grids and actual MIDI note previews.
- [x] Preserve existing editing, mixer/automation, graph, plugin, recording and keyboard behavior.
- [x] Add an original multi-track example and document the workflow and retained limitations.
- [x] Verify GUI actions, minimum/large layouts, core regressions and release packaging.

### Implementation status
Implemented in the FLTK GUI without new dependencies, engine changes or a project
format change. Default workspace 1280 × 800; supported minimum 1220 × 720.
Track creation is a single undoable prepared-model edit. The transport and
sidebar inspector are read-only displays; existing editors retain their controls.
Original four-track example visually checked; GUI tests cover creation,
selection, rollback, undo/reopen and minimum/large window sizes. This phase
modernizes presentation and workflow; it does not claim commercial-DAW feature
parity or add docking, scanning or mixer channel-strip functionality.
See WORKSPACE.md for the workflow, tests and limits.

---

## Phase 34 — Grid, Clip Editing and Track Instrument Controls

### Goal
Expose common DAW editing actions directly in the flat workspace: selectable
snap, MIDI clip double-click, individual note velocity and track instruments.

### Tasks and acceptance criteria
- [x] Draw bar/beat/subdivision grid lines and expose a sequencer Snap dropdown.
- [x] Offer Off, straight, triplet, half-note and bar divisions; synchronize the existing snap menu.
- [x] Snap clip moves and both trim edges to absolute grid positions, including off-grid clips.
- [x] Open the selected MIDI clip's piano roll on left-button double-click without moving it.
- [x] Add a fixed velocity lane and selected-note slider with 1..127 validation and one undo step per edit.
- [x] Keep coincident chord notes individually editable and preserve timing/pitch/channel.
- [x] Add a dropdown to every non-bus track for built-in sine, project instruments and explicit plugin loading.
- [x] Preserve track identity through reorder, undo, clear and project reload; retain candidate failure rollback.
- [x] Keep controls flat, retain current project format and verify builds, GUI regressions and releases.

### Implementation status
Implemented in the C++ GUI over existing C model APIs. Snap preferences are
session UI state; note velocity and track instruments already persist in v12.
The project instrument list is built from existing assignments, with Load plugin
for other trusted binaries; automatic disk scanning is not introduced.
At low zoom the visual grid coarsens for readability while snap remains exact to
the selected tick division. Off uses pointer/model tick precision. MIDI velocity
is a performance value, not a per-note dB gain stage; third-party instrument
patches control its audible response. See WORKSPACE.md and MIDI.md.

---

## Phase 35 — Application Preferences and Sequencer Looping

### Goal
Persist application preferences in `~/.xtc.conf` and provide selectable sequencer loops.

### Tasks and acceptance criteria
- [x] Add a flat, tabbed Edit / Preferences dialog with Apply and Close.
- [x] Validate and atomically save all preference tabs as a private INI file; load at startup.
- [x] Expose audio, interface, editing, new-project, plugin-path and transport settings.
- [x] List plugin files from configurable CLAP, VST2, VST3 and LADSPA search paths without executing modules.
- [x] Select a snapped loop range by Shift-dragging the ruler or entering tick bounds.
- [x] Toggle looping and split audio processing at exact sample boundaries.
- [x] Preserve real-time constraints and reject recording with looping enabled.
- [x] Verify persistence, invalid input, GUI Apply/reload, backend wraps and existing regressions.

### Implementation status
Implemented without dependencies or a project format change. Application settings
are saved only with Apply; audio connection options take effect on Reconnect and
project defaults on New. Existing projects retain their musical data. Loop ranges
are global preferences, not project data. Enabled loops require at least 64 samples.
See [PREFERENCES.md](PREFERENCES.md) for configuration, workflow and limitations.

---

## Phase 36 — Studio Mixer Overview

### Goal
Show every track and bus as a studio-style channel strip with direct level,
pan, routing and metering controls in the flat workspace.

### Tasks and acceptance criteria
- [x] Replace the single-track control panel with a horizontally scrolling bank of all tracks and buses.
- [x] Provide vertical dB faders, flat pan knobs, mute/solo switches and output routing per strip.
- [x] Show simultaneous stereo track/bus meters and keep the master output monitor visible while scrolling.
- [x] Retain selected-track gain/pan automation, interpolation, keyboard control and Add bus.
- [x] Preserve stable track identity, undo/redo, persistence and failure rollback across strip edits.
- [x] Verify empty/full sessions, reorder/remove, minimum/large layouts and independent meters.
- [x] Refresh the view screenshots and document mixer controls and metering limits.
- [x] Build and run GUI/core, live JACK, sanitizer and release checks.

### Implementation status
Implemented in the C++ FLTK GUI using the existing C mixer and backend snapshot
APIs. No audio callback, project format or dependency changes. The fixed master
strip monitors graph output; it does not introduce a separate master gain stage.
Faders edit static gain and do not chase automation. See [MIXER.md](MIXER.md)
and the updated [screenshots](../screenshots/README.md).

---

## Phase 37 — Workspace Navigation and Direct Editing

### Goal
Reduce menu hunting and make the workspace useful for everyday project editing
with a direct transport, track inspector and searchable commands.

### Tasks and acceptance criteria
- [x] Add Ctrl+P command search with filtering, keyboard navigation, Enter and Escape.
- [x] Expose active menu actions through existing callbacks, without duplicating command implementations.
- [x] Make project BPM editable from the transport with validation, undo and failed-preparation rollback.
- [x] Replace the passive sidebar with a context-aware gain/pan/mute/solo inspector.
- [x] Preserve unfinished numeric input across timer refreshes and avoid no-op history edits.
- [x] Add a session summary, Fit song and optional Follow playhead navigation.
- [x] Persist Follow playhead through the existing Preferences / Apply workflow.
- [x] Test command selection/cancellation, inspector edits, tempo rollback/undo and navigation.
- [x] Refresh all screenshots, including a command-palette view, and document the workflow.

### Implementation status
Implemented over the existing C model, history and backend APIs, with no new
dependencies or project format change. Tempo edits stop and rewind transport;
track/clip and piano selections survive. Fit song uses the supported 24..384
pixels-per-beat zoom levels; very long projects still require scrolling.
The inspector targets the selected mixer channel in Mixer and the arrangement
track in other views. Command search lists active menu actions; it is not a
plugin scanner or a key-binding editor. See WORKSPACE.md.

### Future usability work
Dockable editor panels, arrangement multiselection, independent track inserts,
resizable pinned track headers and customizable shortcuts remain future work.
They require separate model/layout designs and acceptance tests.

---

## Phase 38 — Internal instruments and effects

### Tasks and acceptance criteria

- [x] Add always-available Soft Keys and Sub Bass MIDI instrument presets.
- [x] Add Delay and Reverb with bounded controls and effect automation.
- [x] Integrate track selection, graph wire insertion, undo and saved projects.
- [x] Preserve older projects; reserve format 13 internal device identities.
- [x] Verify DSP tails, block partition consistency, note release/panic and persistence.
- [x] Refresh application screenshots and add internal device editor views.

### Implementation status

Implemented for the bounded initial device set. Audited 2026-11-05 against
`src/plugin/builtin.c`, the shared plugin host, track instrument selector,
graph commands and v13 persistence. Soft Keys and Sub Bass are fixed 32-voice
presets; Delay and Reverb each expose three bounded, automatable controls.
Preparation owns buffer allocation; processing uses preallocated storage.
Internal devices use virtual identities rather than loading external modules;
the reader retains v1–v12 compatibility. Actual device control screenshots are
listed in [screenshots/README.md](../screenshots/README.md).

`tests/unit/test_builtin.c` covers both effect tails and block partitions, dry
mix, invalid feedback, both instruments' release/panic, mix automation and a
keys/delay project round trip. Shared GUI tests cover instrument selection,
history and plugin editing, but do not constitute a dedicated end-to-end matrix
for all four internal devices. Additional qualification is tracked in Phase 40.

Missing extensions: editable instrument parameters/presets, pitch bend, sample
instruments, click-free/tempo-synced delay, stereo reverb/diffusion, explicit seek
history policy and automatic tail rendering. These are planned in Phases 41–44;
they are not part of the checked initial subset. See
[BUILTIN_DEVICES.md](BUILTIN_DEVICES.md) for controls and explicit limitations.

---

## Phase 39 — Detachable transport and mixer

### Tasks and acceptance criteria

- [x] Float/dock the existing transport and mixer without duplicating state.
- [x] Keep BPM and loop settings in the shared transport controls.
- [x] Recover arrangement space and retain resizable mixer channels.
- [x] Support close-to-dock, Dock all, floating playback shortcuts and safe shutdown.
- [x] Exercise lifecycle, settings and resizing in GUI tests and capture floating views.

### Implementation status

Implemented for the transport and mixer. Audited 2026-11-05 against
`src/gui/main_window.cpp` and `tests/integration/test_gui.cpp`. Detaching
reparents the existing widgets on the GUI thread; BPM, loop settings and mixer
state remain shared. Docking restores ownership and arrangement space, and the
destructor docks panels before destroying their windows. Tests exercise repeated
detach/dock, close-to-dock, shared BPM/loop state, floating playback shortcuts,
main/floating resizing and failed/successful shutdown. Floating screenshots are
listed in [screenshots/README.md](../screenshots/README.md).

Layout and window positions are session-only. The floating transport requires
1220 pixels of width; mixer minimum size is 600 × 420. Other editors cannot be
detached, and general dock layouts are absent. Persistence, compact transport
and additional panels are tracked in Phases 45–46. See
[WORKSPACE.md](WORKSPACE.md) for usage and limits.

### Audit validation (Phases 38–39)

Warning-enabled `make BUILD_DIR=build/roadmap-audit all gui test` passed,
including `test-builtins`. Sequential GUI runs with the same build passed:
`test-gui`, `test-gui-instruments`, `test-gui-modern-plugins` and
`test-gui-plugins`. The initial parallel GUI invocation reported passing test
assertions but failed Xvfb cleanup; sequential reruns exited successfully.
Historical sanitizer/live-JACK evidence in WORKSPACE.md is separate from this
audit; sanitizers, live JACK and physical listening were not rerun here.

---

## Phase 40 — Internal Device Acceptance Coverage

### Goal
Close the dedicated validation gaps in the initial Phase 38 device set.

### Tasks and acceptance criteria
- [x] Exercise all four internal devices through GUI selection/addition, wire insertion where applicable, control editing, undo/redo and save/reopen.
- [x] Round-trip both instruments and both effects, including automated controls, and compare rendered output.
- [x] Verify older-format migration alongside v13 identities and reject malformed internal identities transactionally.
- [x] Test sustain, repeated notes, voice exhaustion, seek/stop/panic and instrument block partition consistency.
- [x] Cover preparation/allocation failures and callback allocation/free guards for internal devices.
- [x] Document repeatable manual listening checks for both presets and representative effect settings.

### Implementation status
Implemented: dedicated all-device GUI/history/persistence tests, exact persisted
render comparisons, malformed-identity rollback, voice/transport regressions and
allocation-failure/callback guards. Warning-enabled core tests, reliability, GUI
and listening-preview generation pass. See BUILTIN_DEVICES.md for repeatable
manual checks; human listening and physical hardware remain unverified.

---

## Phase 41 — Editable Internal Instruments and Presets

### Goal
Extend the fixed Soft Keys/Sub Bass presets into editable instruments.

### Tasks and acceptance criteria
- [x] Define bounded oscillator, envelope and filter controls with metadata and defaults that preserve existing preset sounds.
- [x] Provide instrument parameter editing, automation and reusable preset save/load through public C APIs.
- [x] Support channel pitch bend with a documented range and sustain/note lifecycle behavior.
- [x] Persist parameters and presets with explicit version migration, undo and failed-preparation rollback.
- [x] Verify sample timing, block partition consistency, bounds, aliasing behavior and callback safety.

### Implementation status
Implemented: five bounded oscillator/envelope/filter/bend controls, absolute-time
automation, instrument editor and reusable preset C APIs/GUI commands. Format 14
persists bindings and reads v1–v13, preserving legacy default sounds. Core,
reliability and GUI tests pass, including preset/migration, exact partition and
pitch-bend offset regressions. See BUILTIN_DEVICES.md and PROJECT_FORMAT.md.

---

## Phase 42 — Internal Sample Instrument

### Goal
Provide sample-based sounds beyond the current oscillator presets.

### Tasks and acceptance criteria
- [ ] Define supported sample formats, mapping, looping, envelopes, voice limits and memory budgets.
- [ ] Load/prepare samples outside callbacks and expose an instrument editor with undo.
- [ ] Persist sample references and mappings with missing-media reporting and relinking.
- [ ] Provide original or appropriately licensed example sounds and document their licenses.
- [ ] Test playback rate conversion, boundaries, voice release, missing assets and project reload.

### Implementation status
Planned. Phase 38 supplies no sample instrument or sample library.

---

## Phase 43 — Smooth Delay and Stereo Reverb

### Goal
Address the documented sound-design and transition limits of the basic effects.

### Tasks and acceptance criteria
- [ ] Smooth or crossfade delay-time changes and define automation behavior without abrupt read-head jumps.
- [ ] Add tempo-synced delay divisions with deterministic tempo/seek behavior.
- [ ] Add true stereo processing and reverb diffusion/room controls rather than independent mono instances alone.
- [ ] Preserve old projects' effect identities, parameters and sound, or provide an explicit compatibility mode.
- [ ] Test stability at parameter extremes, stereo response, automation partitions and transition artifacts; document listening results.

### Implementation status
Planned. Delay time can click; reverb uses four damped mono combs without a room
model or stereo diffusion. Current decay is a feedback coefficient, not seconds.

---

## Phase 44 — Effect History and Tail Rendering

### Goal
Make discontinuities and effect tails explicit in playback and export.

### Tasks and acceptance criteria
- [ ] Define retained/reset effect history for seek, stop, loop wrap and project/plan replacement.
- [ ] Implement the chosen history policy without callback allocation or unsafe state sharing.
- [ ] Add bounded automatic or user-configurable tail rendering after the arrangement/export endpoint.
- [ ] Expose tail limits and cancellation, including silent input and non-decaying/high-feedback cases.
- [ ] Test seek/loop reproducibility and complete delay/reverb tails across processing block sizes.

### Implementation status
Planned. Seeks currently retain effect history; tails need continued rendering
and do not automatically extend playback/export.

---

## Phase 45 — Persistent Panel Layouts and Compact Transport

### Goal
Retain useful floating layouts across sessions and support narrower displays.

### Tasks and acceptance criteria
- [ ] Persist docked/floating state and panel geometry through the application preferences workflow.
- [ ] Restore layouts safely when monitors or display sizes change; keep all panels reachable.
- [ ] Provide a compact/responsive floating transport while retaining BPM, loop and playback controls.
- [ ] Preserve close-to-dock, Dock all, shortcuts, editing focus protection and safe shutdown.
- [ ] Test restart, invalid settings, off-screen geometry, narrow sizes and repeated dock/resize cycles.

### Implementation status
Planned. Phase 39 starts docked each session and its transport minimum is 1220 pixels.

---

## Phase 46 — Additional Dockable Editors

### Goal
Extend Phase 39's two-panel arrangement to a general editor workspace.

### Tasks and acceptance criteria
- [ ] Define supported dock locations and layout ownership for sequencer, piano roll and modular graph panels.
- [ ] Detach/dock each supported editor without duplicating project, selection or history state.
- [ ] Support resizable pinned track headers and preserve editing coordinates, scrolling and focus after reparenting.
- [ ] Integrate with Phase 45 layout persistence and provide a safe reset-layout action.
- [ ] Verify minimum/large layouts, cross-panel editing, repeated reparenting and shutdown/error paths.

### Implementation status
Planned. Phase 39 only detaches transport and mixer; broader docking and
resizable pinned headers from Phase 37 remain outstanding. These follow-up
phases cover gaps found in Phases 38–39 and their documented limitations;
unrelated outstanding features in earlier phases retain their existing status.

---

## Recommended Execution Order

Reorder the phases when the audit reveals a blocking dependency. Do not mark a phase complete merely because code exists: its acceptance criteria must be demonstrated by builds, tests, or documented manual verification.

## Definition of Done for Each Phase

A phase is complete only when:

- The project builds with warnings enabled.
- Relevant automated tests pass, and manual tests are documented where automation is impractical.
- Error paths, resource ownership, and thread boundaries have been reviewed.
- Real-time audio constraints remain satisfied.
- Documentation is updated alongside API or behavior changes.
- No unrelated functionality was silently removed.
- Untested behavior and known limitations are reported honestly.
- The phase's acceptance criteria are explicitly checked off.

Do not skip phases without documenting why and preserving acceptance criteria.