Cubase-MCP-GAJ3T.MusicGen.R.../prompts/step_3.md

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.