restructure

docs/rivet/implementation.md

@@ -0,0 +1,54 @@
+# Rivet 0.2 implementation plan
+
+## Musical intent
+Develop a producer's own motif through audible choices about recognition, space,
+contrast, and return. Offer three distinct compositional proposals rather than
+three randomly shifted versions. Emotional interpretation stays with the producer.
+
+## Engine
+- Keep an exact opening quotation. Build subsequent two-bar sections as statement,
+  answer, departure, and return (four-bar phrases use statement and return).
+- Add tasks Develop, Answer, Make space, and Return. Generate a deterministic pool
+  using rhythmic displacement, fragmentation, call/response, sparse subtraction,
+  a later register peak, changed endings, and harmonic returns; remove duplicates
+  and choose three candidates by task fit and musical distance. Return fewer if
+  locks make three distinct outcomes impossible.
+- Preserve groove and contour independently. Per-note locks protect pitch, rhythm,
+  or every attribute. Locked events survive subtraction; rhythm locks keep exact
+  timing and duration. Global constraints and locks take precedence over transforms.
+- Optional harmony consists of bounded time regions with pitch-class masks and
+  bass pitch. Accept polyphonic MIDI without claiming chord-root detection. Also
+  provide editable per-bar chord progressions. Guide metrically strong notes and
+  ending targets using the actual harmony at that time. Open endings prefer an
+  available scale tone outside the ending chord; closed endings use chord tones.
+- Candidate generation changes note count, spacing, duration, and articulation
+  when constraints allow. Preserve recognizable fragments; avoid overlaps and
+  clipping MIDI values. Keep generated notes within two-bar section boundaries so
+  sections can be combined safely.
+
+## Producer workflow
+Import motif -> choose identity/locks -> optionally import or enter harmony ->
+choose task -> audition alternatives -> pin two-bar sections -> export combined
+MIDI or accept a complete candidate. Retain accepted work during regeneration.
+Pins survive changes to task and seed, and clear when source or phrase length
+changes. Pinned material overrides regenerated sections. Reject unsafe seams
+rather than silently truncate a sustained note.
+
+## Audition
+Keep the internal voice and add a MIDI output mode. Preview is explicitly started,
+optionally loops, and switches pending selections at the next two-bar boundary or
+current clip end. Stop, replacement, mode changes, reset, and state restoration
+release emitted notes. Host transport start never auto-starts audition. All clips,
+queues, scheduling, and MIDI event emission remain bounded and allocation-free
+on the audio thread. Validate FL Studio routing manually; retain MIDI file export
+as the reliable commit path. Native OS MIDI drag-out is outside this release.
+
+## Compatibility and verification
+Write state version 2; migrate version-1 JSON and host fields with serde defaults,
+retain legacy strategy names for old candidates, and keep the persisted host field
+identifier. New controls/harmony/pins/audition choices persist. Test timing, locks,
+contour, harmonic targets, candidate diversity, section composition, migration,
+loop boundaries, sample-accurate note events, queued switches, and RT allocation.
+Run existing core/ABI tests and Clippy, render the updated editor, and package
+Windows CLAP plus Linux CLAP/standalone. Do not claim Devath-derived algorithms or
+FL Studio validation without direct evidence.