feat: plan composition phases and persist named arrangement markers

docs/COMPOSITION_WORKFLOWS.md

@@ -0,0 +1,8 @@
+# Arrangement and composition workflows
+
+All mutations run on the control thread through the existing stop, history and
+prepared-plan workflow. No new dependencies are required.
+
+## Phase 58 — Persistent Arrangement Markers
+
+Edit/Markers/Set at cursor adds or renames a marker; Remove at cursor removes the exact tick key. Markers draw names and vertical guides in the arrangement and survive project save/load and undo. Up to 128 markers are supported. Names may overlap visually when markers are close; markers do not change playback by themselves.

docs/PROJECT_FORMAT.md

@@ -1,4 +1,4 @@
-# Project format v15 (reads v1–v14)
+# Project format v16 (reads v1–v15)
 
 Phases 5–31 use a bounded text format implemented in C99 without a parser library.
 The extension is `.xtc`. File operations run exclusively on the control thread.
@@ -418,3 +418,11 @@ Missing/invalid samples remain references and become reported silence during
 preparation. Controls describe root key, whole-file loop, attack, release and
 gain. Earlier projects have empty sample paths. Rebuild public API consumers
 for the additional copied `sample_path` field in `xtc_plugin_spec`.
+
+## Version 16: arrangement markers
+
+After `LIVE_INSTRUMENT` and before `END`, version 16 writes `MARKERS count`
+followed by `MARKER tick hex_name` records. Count is 0..128; ticks must be strictly
+increasing and at most MAX_TICK. Names use the existing bounded UTF-8 hex encoding.
+Versions 1–15 migrate to an empty marker list. Older builds reject version 16.
+Markers are copied by snapshots and history; the tick is their stable key.

docs/ROADMAP.md

@@ -1491,6 +1491,171 @@ remain unqualified.
 
 ---
 
+## Phase 58 — Persistent Arrangement Markers
+
+### Goal
+Store up to 128 named, tick-keyed markers with versioned migration, undoable GUI editing and ruler display.
+
+### Tasks and acceptance criteria
+- [x] Implement bounded C99 model/control APIs and accessible GUI commands.
+- [x] Preserve transactional errors, history, compatibility and callback safety.
+- [x] Verify the feature with automated model/GUI tests and document limitations.
+
+### Implementation status
+Implemented: sorted tick-keyed markers, bounded UTF-8 names, undoable GUI editing and ruler display. Format 16 appends marker records and reads versions 1–15. Core, legacy migration, malformed-load rollback and focused GUI history/docking tests pass.
+
+---
+
+## Phase 59 — Section Navigation and Looping
+
+### Goal
+Navigate previous/next markers and loop the section between a marker and its successor or the song end.
+
+### Tasks and acceptance criteria
+- [ ] Implement bounded C99 model/control APIs and accessible GUI commands.
+- [ ] Preserve transactional errors, history, compatibility and callback safety.
+- [ ] Verify the feature with automated model/GUI tests and document limitations.
+
+### Implementation status
+Planned.
+
+---
+
+## Phase 60 — Ripple Time Editing
+
+### Goal
+Insert or remove bounded timeline ranges atomically, shifting clips, markers and automation; reject clips crossing edit boundaries explicitly.
+
+### Tasks and acceptance criteria
+- [ ] Implement bounded C99 model/control APIs and accessible GUI commands.
+- [ ] Preserve transactional errors, history, compatibility and callback safety.
+- [ ] Verify the feature with automated model/GUI tests and document limitations.
+
+### Implementation status
+Planned.
+
+---
+
+## Phase 61 — Complete Track Duplication
+
+### Goal
+Duplicate a non-bus track with fresh IDs, clips, notes, mixer controls, routing, instrument settings and track automation in one transaction.
+
+### Tasks and acceptance criteria
+- [ ] Implement bounded C99 model/control APIs and accessible GUI commands.
+- [ ] Preserve transactional errors, history, compatibility and callback safety.
+- [ ] Verify the feature with automated model/GUI tests and document limitations.
+
+### Implementation status
+Planned.
+
+---
+
+## Phase 62 — Nondestructive MIDI Clip Splitting
+
+### Goal
+Split trimmed MIDI clips at the cursor while sharing source-relative note content and preserving exact rendered boundaries.
+
+### Tasks and acceptance criteria
+- [ ] Implement bounded C99 model/control APIs and accessible GUI commands.
+- [ ] Preserve transactional errors, history, compatibility and callback safety.
+- [ ] Verify the feature with automated model/GUI tests and document limitations.
+
+### Implementation status
+Planned.
+
+---
+
+## Phase 63 — MIDI Clip Consolidation
+
+### Goal
+Merge selected MIDI clips on one track into a fresh source, retaining audible notes and gaps with explicit boundary clipping and rollback.
+
+### Tasks and acceptance criteria
+- [ ] Implement bounded C99 model/control APIs and accessible GUI commands.
+- [ ] Preserve transactional errors, history, compatibility and callback safety.
+- [ ] Verify the feature with automated model/GUI tests and document limitations.
+
+### Implementation status
+Planned.
+
+---
+
+## Phase 64 — Deterministic MIDI Humanization
+
+### Goal
+Apply seeded timing and velocity variation to MIDI clip sources with reproducible results, bounds checks and undo.
+
+### Tasks and acceptance criteria
+- [ ] Implement bounded C99 model/control APIs and accessible GUI commands.
+- [ ] Preserve transactional errors, history, compatibility and callback safety.
+- [ ] Verify the feature with automated model/GUI tests and document limitations.
+
+### Implementation status
+Planned.
+
+---
+
+## Phase 65 — Chord Construction
+
+### Goal
+Generate bounded custom chord intervals from source notes with fresh IDs, preserved articulation and transactional pitch/capacity checks.
+
+### Tasks and acceptance criteria
+- [ ] Implement bounded C99 model/control APIs and accessible GUI commands.
+- [ ] Preserve transactional errors, history, compatibility and callback safety.
+- [ ] Verify the feature with automated model/GUI tests and document limitations.
+
+### Implementation status
+Planned.
+
+---
+
+## Phase 66 — Offline Arpeggio Generation
+
+### Goal
+Convert source note chords into bounded ascending/descending stepped patterns with gate controls, deterministic ordering and undo.
+
+### Tasks and acceptance criteria
+- [ ] Implement bounded C99 model/control APIs and accessible GUI commands.
+- [ ] Preserve transactional errors, history, compatibility and callback safety.
+- [ ] Verify the feature with automated model/GUI tests and document limitations.
+
+### Implementation status
+Planned.
+
+---
+
+## Phase 67 — Audio Peak Normalization
+
+### Goal
+Analyze the audible source slice outside callbacks and adjust nondestructive clip gain to a requested sample-peak target; validate silence, missing media and gain limits.
+
+### Tasks and acceptance criteria
+- [ ] Implement bounded C99 model/control APIs and accessible GUI commands.
+- [ ] Preserve transactional errors, history, compatibility and callback safety.
+- [ ] Verify the feature with automated model/GUI tests and document limitations.
+
+### Implementation status
+Planned.
+
+---
+
+## Phase 68 — Portable Project Collection
+
+### Goal
+Collect referenced audio and sampler media into a new self-contained project folder, deduplicate references, preserve original files and reject existing destinations or unsupported references safely.
+
+### Tasks and acceptance criteria
+- [ ] Implement bounded C99 model/control APIs and accessible GUI commands.
+- [ ] Preserve transactional errors, history, compatibility and callback safety.
+- [ ] Verify the feature with automated model/GUI tests and document limitations.
+
+### Implementation status
+Planned.
+
+---
+
 ## 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.