212 lines
11 KiB
Markdown
212 lines
11 KiB
Markdown
# Step 3: Implement the composition model and deterministic text planner
|
|
|
|
## Objective and prerequisites
|
|
|
|
Step 2 has been reviewed and accepted: the .NET 10 stdio MCP lifecycle works,
|
|
the production tool registry is empty, and all 130 tests pass.
|
|
|
|
Read [the approved plan](plan.md), [the Step 2 report](report_2.md), and existing
|
|
code before editing. Implement only the instrument-neutral composition model,
|
|
validation, documented bounded English grammar, and deterministic basic pattern
|
|
planning. This step does not require proprietary mappings.
|
|
|
|
Do not implement production profiles, keyswitch/CC event generation, MIDI/native
|
|
writers, public generation tools, publication, audio, network calls or an LLM.
|
|
Do not alter orchestrator prompts/plan, create later prompts, commit or delegate.
|
|
|
|
## Files to create or modify
|
|
|
|
```text
|
|
src\GAJ3T.MusicGen.RiffGrooveBuilder.Core\
|
|
Composition\BeatFraction.cs
|
|
Composition\Composition.cs
|
|
Composition\TrackPlan.cs
|
|
Composition\MusicalNote.cs
|
|
Composition\DrumHit.cs
|
|
Composition\CompositionDiagnostic.cs
|
|
Composition\CompositionPlanningResult.cs
|
|
Composition\CompositionValidator.cs
|
|
Composition\DescriptionParser.cs
|
|
Composition\CompositionPlanner.cs
|
|
tests\GAJ3T.MusicGen.RiffGrooveBuilder.UnitTests\
|
|
Composition\BeatFractionTests.cs
|
|
Composition\CompositionValidatorTests.cs
|
|
Composition\DescriptionParserTests.cs
|
|
Composition\CompositionPlannerTests.cs
|
|
tests\GAJ3T.MusicGen.RiffGrooveBuilder.IntegrationTests\
|
|
GAJ3T.MusicGen.RiffGrooveBuilder.IntegrationTests.csproj
|
|
Composition\CompositionPipelineTests.cs
|
|
docs\text-description-contract.md
|
|
README.md
|
|
prompts\report_3.md
|
|
```
|
|
|
|
Small directly related typed enums/value objects/helpers may have their own
|
|
files if clearer. Avoid public interfaces or abstractions with no actual use.
|
|
IntegrationTests may add a Core project reference for in-process full-pipeline
|
|
tests; refresh generated locks when required. No new package is needed.
|
|
|
|
## Design and implementation details
|
|
|
|
### Model and timing
|
|
|
|
- Core remains independent of DryWetMIDI and vendor schemas.
|
|
- Model tempo, time signature, key/root/mode, bar count, selected role tracks
|
|
and notes/hits. Use typed roles (`lead`, `bass`, `drums`), articulations and
|
|
drum voices, not unchecked magic strings.
|
|
- Pitched notes hold absolute MIDI pitch and musical velocity/duration.
|
|
Drum hits hold logical voices (kick, snare, closed hi-hat), not guessed SD3
|
|
note numbers. Articulations remain intentions, not vendor switch values.
|
|
- Beat positions/durations are exact fractions of a quarter note. Implement
|
|
normalized immutable rational arithmetic with checked integer operations,
|
|
comparison, and exact conversion to 960 PPQ ticks. Reject nonpositive
|
|
denominators, negative starts and nonpositive durations.
|
|
- A bar is `numerator * 4 / denominator` quarter notes. Validate time signature
|
|
fields and exact tick representability. Human "beat 1" in a meter refers to
|
|
the denominator-note beat; document and test this explicitly.
|
|
- Keep track planning independent of production profile verification. Planned
|
|
pitches/velocities are musical choices, not evidence of plugin playability.
|
|
Vendor ranges, profiles, channels and switch-state validation belong to Step 4.
|
|
- Validate MIDI numeric ranges, positive finite/representable SMF tempo,
|
|
bar bounds, selected roles, note/hit duration and complete musical extent.
|
|
Validate arithmetic/resource bounds before allocating large note lists.
|
|
- Diagnostics identify a stable code, field/phrase when applicable, and an
|
|
actionable message. Invalid input cannot return a successful empty composition.
|
|
Failure results have no usable partial composition.
|
|
|
|
### Document the grammar before implementing it
|
|
|
|
The initial vocabulary is deliberately bounded; do not claim arbitrary English
|
|
understanding. Write the text contract first, then make parser/tests match it.
|
|
|
|
Required supported concepts:
|
|
|
|
- Bar count, integer BPM, meter, and key/root (major or minor).
|
|
- Role clauses for lead/guitar, bass, and drums.
|
|
- Repeated root-note quarter/eighth/sixteenth-note lead or bass patterns and
|
|
sustained root notes (one full-bar note per bar).
|
|
- Canonical sustain and palm-mute articulation intentions, binding modifiers
|
|
to the relevant role, not every track. Actual support remains profile-gated.
|
|
- Drum placement on explicit numbered beats and closed hi-hat subdivisions.
|
|
- Representative documented paraphrases such as `120 BPM` / `120 bpm`,
|
|
`4 bars` / `four bars`, `palm-muted` / `palm mute`, and `lead guitar` / `lead`.
|
|
Support ordinary whitespace/case/punctuation variation without deleting or
|
|
ignoring meaningful unknown text.
|
|
|
|
The exact acceptance description from the plan must work:
|
|
|
|
> Generate 4 bars at 120 BPM in E minor, 4/4: palm-muted eighth-note lead guitar,
|
|
> sustained root-note bass, kick on beats 1 and 3, snare on beats 2 and 4, and
|
|
> closed hi-hat eighth notes.
|
|
|
|
For that example, with zero lead-in at this planning stage:
|
|
|
|
- Four bars of 4/4 span exactly 16 quarter notes / 15,360 ticks.
|
|
- Lead: 32 eighth notes; starts every 480 ticks; duration 480 ticks; root E
|
|
and palm-mute intention. Bass: four sustained notes, each 3,840 ticks.
|
|
- Kick: eight hits at beats 1/3; snare: eight at beats 2/4; closed hi-hat:
|
|
32 eighth-note hits. All start positions repeat on exact bar boundaries.
|
|
- Do not infer drum MIDI pitches or keyswitch values.
|
|
|
|
Document deterministic defaults, used only when a setting is omitted:
|
|
120 BPM, 4 bars, 4/4, E minor; lead root in MIDI octave 4 (C4=60), bass root in
|
|
octave 2 (C2=36), velocity 96, sustain articulation unless explicitly changed.
|
|
Thus E is MIDI 64 for lead and 40 for bass; these are composition defaults,
|
|
not product mappings. Permit root names/accidentals within the documented
|
|
key grammar and test enharmonic normalization.
|
|
|
|
If no role is mentioned, default to all three. When a role/part is explicitly
|
|
mentioned, generate only explicitly selected roles (drum part clauses select
|
|
drums). For omitted role patterns, default to root eighth-note lead,
|
|
full-bar sustained bass, and the documented 4/4 kick-1/3, snare-2/4, eighth-note
|
|
closed-hi-hat pattern.
|
|
|
|
Do not silently apply a 4/4 drum default to another meter. For non-4/4 drum
|
|
requests, require explicit valid drum part placement/subdivision if no
|
|
documented meter-aware default exists. Any omitted defaulted parts/settings
|
|
must be visible in `DefaultsApplied`; explicitly selecting a drum subset must
|
|
not silently add omitted parts.
|
|
|
|
Record every applied default with its value. Reject contradictions, malformed
|
|
numbers, duplicate conflicting settings, invalid beat positions, unsupported
|
|
articulations/patterns and unconsumed meaningful instructions. Genre labels,
|
|
chord progressions, tuning instructions, arbitrary melodies, dynamics outside
|
|
the supported grammar, and unknown text are not excuses for guessed behavior.
|
|
|
|
For resource safety, choose and document a single internal generated-event
|
|
limit, estimate counts using checked arithmetic before expanding patterns,
|
|
and return a specific diagnostic when exceeded. Do not add public resource
|
|
configuration or silently truncate. Keep this limit generous enough for
|
|
ordinary multi-bar descriptions and test its precise boundary.
|
|
|
|
### Planning behavior
|
|
|
|
- Parser output and the final model must preserve explicitly supplied settings.
|
|
Explicit modifiers apply only to their intended clause/role.
|
|
- Keep parsing/planning failures explicit. Catch only expected parsing,
|
|
representability and checked-arithmetic errors at an appropriate boundary;
|
|
do not convert arbitrary exceptions into apparently successful defaults.
|
|
- Identical text and options produce structurally identical compositions.
|
|
- No randomization, humanization, audio analysis or external semantic service.
|
|
- Preserve currently working MCP behavior. The production tool registry stays
|
|
empty until Step 8; do not wire a premature generation tool.
|
|
|
|
## Required tests
|
|
|
|
### Unit tests
|
|
|
|
1. Rational normalization/arithmetic/comparison, exact tick conversion, zero/
|
|
invalid denominators, negative positions, fractional unrepresentability and
|
|
checked overflow.
|
|
2. Full acceptance example with exact values, counts, starts, durations,
|
|
articulation intentions, defaults and musical extent.
|
|
3. Paraphrases, case/whitespace/punctuation, key accidentals/enharmonics,
|
|
explicit role selection and omitted-setting defaults.
|
|
4. Pattern subdivisions and sustained notes without drift across many bars.
|
|
5. Time-signature quarter-note math and denominator-beat placement in at least
|
|
one non-4/4 meter; invalid/nonrepresentable meters and beats rejected.
|
|
6. Contradictory settings/clauses, malformed numeric text, unsupported/leftover
|
|
meaningful words, unknown articulations and invalid requests.
|
|
7. Numeric pitch/velocity/duration bounds and tempo/SMF representability.
|
|
8. Exact resource limit and just-over-limit rejection before expensive expansion.
|
|
9. Deterministic repeated calls and no shared mutable collection state between
|
|
independent composition results.
|
|
|
|
### Integration tests
|
|
|
|
Call the real Core parser -> planner -> validator pipeline in-process using the
|
|
documented full description. Inspect all three tracks and exact musical timing.
|
|
Also cover selected-role output, a documented non-4/4 description, and failures
|
|
that yield actionable diagnostics with no partial successful composition.
|
|
Retain the real-process MCP/scaffold integration tests; do not mistake the
|
|
in-process composition check for the final public MCP generation integration.
|
|
|
|
## Validation and exit criteria
|
|
|
|
Use targeted composition tests during development, then:
|
|
|
|
```powershell
|
|
dotnet build .\GAJ3T.MusicGen.RiffGrooveBuilder.slnx -c Release --no-restore
|
|
dotnet test .\GAJ3T.MusicGen.RiffGrooveBuilder.slnx -c Release --no-build
|
|
dotnet restore .\GAJ3T.MusicGen.RiffGrooveBuilder.slnx --locked-mode
|
|
```
|
|
|
|
Restore after any project-manifest change before validating. Installed SDK:
|
|
`C:\Program Files\dotnet\dotnet.exe`; editor test discovery was unavailable,
|
|
so CLI execution is the known fallback.
|
|
|
|
Exit: supported descriptions deterministically produce validated multi-role
|
|
compositions with exact timing, rejected text is not silently ignored, tests
|
|
all pass, docs match behavior, and production mappings/writers/tools remain
|
|
unimplemented rather than fabricated.
|
|
|
|
## Mandatory worker report
|
|
|
|
When complete, write your end-of-step report to ./prompts/report_3.md including: what was implemented, test results (pass/fail with details), any issues encountered, and whether you're ready for the next step
|
|
|
|
Entire report: exactly one plain triple-backtick fence, with no outside prose.
|
|
Include changed files, grammar/default decisions and limits, exact commands and
|
|
exit codes, test counts, unrun checks and reasons, issues and readiness.
|
|
Explicitly note that accepting Step 3 does not satisfy Step 4's real production
|
|
mapping evidence gate. Stop after the report.
|