mxl-agent 0.1.0__tar.gz

mxl_agent-0.1.0/.claude/skills/mxl-agent/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: mxl-agent
+description: Inspect, edit, and validate MusicXML and compressed MXL scores using the local mxl-agent engine. Use for .mxl, .musicxml, or .xml score files, chord-symbol edits, note-pitch edits, transposition, score summaries/measure inspection, MusicXML schema/temporal validation, or exporting an edited score to a new file. Not for general MIDI, audio, DAW, or PDF-only tasks that never touch a MusicXML file.
+compatibility: Requires the mxl-agent CLI in this project (invoked via `uv run mxl-agent`, or on PATH). No network access. MuseScore (`musescore` command) and Verovio (`render`/`playback`) are optional, each unavailable if `doctor` reports it missing.
+allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/mxl-agent.sh *)
+---
+
+# mxl-agent
+
+A deterministic local engine for MusicXML/MXL scores. It owns all XML structure, arithmetic, and
+file I/O. You interpret the user's musical intent and choose typed operations; you never write or
+edit MusicXML by hand.
+
+## Hard rules
+
+- **Never** read a whole score file into your context (no `cat`, no opening it as a text file).
+  Every command below returns a small, bounded JSON summary instead.
+- **Never** author or emit a MusicXML document, or an XML fragment reconstructing one, as your own
+  text output.
+- **Never** overwrite the user's original file. `export` always writes a new path.
+- Only call `${CLAUDE_SKILL_DIR}/scripts/mxl-agent.sh <command> ...`. Do not invoke `mxl-agent`,
+  `uv`, or `python` directly, and do not construct shell strings around the wrapper's arguments.
+- If a selection could match more than one thing (see "Ambiguity" below), stop and ask, or narrow
+  the selection. Do not guess and apply anyway.
+
+## Workflow for an editing request
+
+1. **Open** the score into a session (`session open`) if you don't already have a `session_id`
+   for it in this conversation. Reuse the same session for follow-up edits instead of reopening.
+2. **Inspect** only the region you need (`inspect summary`, then `inspect measures` or
+   `inspect events` narrowed to the relevant part/measures). Use the returned `event_id` values
+   in later steps rather than re-deriving positions yourself.
+3. **Plan** (`plan`) the operation first. Read `changed[].before`/`after` and `warnings`. If
+   `changed` is empty, has more than one entry when the user asked for one thing, or the command
+   fails with an ambiguity error, stop and clarify with the user rather than applying.
+4. **Apply** (`apply`) only once the plan matches what the user asked for. Use the exact same
+   operation JSON you planned with.
+5. **Validate** (`validate`) after applying. If `status` is `"failed"`, report the issues; do not
+   silently continue.
+6. **Export** (`export --output <new-path>`) to a new file when the user wants a saved result.
+   Never pass the original input path as `--output`.
+7. Summarize what changed in plain language (part, measure, before -> after) using the `plan`/
+   `apply` result. Do not paste raw XML.
+
+For a read-only question ("what's the form of this tune", "what chords are in bars 9-16"), stop
+after inspecting -- do not plan or apply anything.
+
+`undo` reverts the session's current revision to its parent, one step. Offer it if the user asks
+to revert an edit.
+
+## Commands
+
+All commands take `--json` (always pass it) and `--workspace-root <path>` (omit it to use the
+default `.mxl-agent/workspaces` under the current project). Full parameter/error reference:
+`references/command-catalog.md`.
+
+```bash
+mxl-agent.sh session open <path-to-score> [--score SELECTOR] --json
+mxl-agent.sh session status <session_id> --json
+mxl-agent.sh session checkout <session_id> (--revision N | --checkpoint NAME) --json
+mxl-agent.sh session revisions <session_id> --json
+mxl-agent.sh create lead-sheet --spec '<lead sheet spec JSON>' --json
+mxl-agent.sh create from-midi <midi-path> [--quantization NAME] [--beats N] [--fifths N] --json
+mxl-agent.sh chord-chart parse --text '<chord chart text>' [--beats N] [--beat-type N] --json
+mxl-agent.sh voice chord --symbol '<chord symbol>' --ranges '<voice ranges JSON>' [--profile classical|jazz] --json
+mxl-agent.sh voice arrange --symbol '<chord symbol>' --instruments '<names JSON array>' [--profile classical|jazz] --json
+mxl-agent.sh reharmonize check <session_id> --plan '<reharmonization plan JSON>' [--profile classical|jazz] --json
+mxl-agent.sh accompany bass --spans '<chord spans JSON>' --range '<voice range JSON>' --json
+mxl-agent.sh accompany guide-tones --spans '<chord spans JSON>' --range '<voice range JSON>' [--role ROLE ...] --json
+mxl-agent.sh accompany comping --spans '<chord spans JSON>' --ranges '<voice ranges JSON>' --pulse '<n/d>' --json
+
+mxl-agent.sh inspect summary <session_id> --json
+mxl-agent.sh inspect parts <session_id> --json
+mxl-agent.sh inspect measures <session_id> [--part-id P1] [--limit N] [--cursor C] --json
+mxl-agent.sh inspect events <session_id> --part-id P1 [--limit N] [--cursor C] --json
+
+mxl-agent.sh plan <session_id> --operation '<operation JSON>' --json
+mxl-agent.sh apply <session_id> --operation '<operation JSON>' --json
+mxl-agent.sh inverse <session_id> --operation '<operation JSON>' --json
+mxl-agent.sh plan-patch <session_id> --patch '<patch JSON>' --json
+mxl-agent.sh apply-patch <session_id> --patch '<patch JSON>' --json
+mxl-agent.sh merge <session_id> --revision-a N --revision-b N --json
+mxl-agent.sh analyze <session_id> --analysis NAME [--selection '<JSON>'] --json
+mxl-agent.sh lint <session_id> [--selection '<JSON>'] --json
+mxl-agent.sh repair <session_id> --fix <fix_id> --json
+mxl-agent.sh repair-plan <session_id> --fix <fix_id> [--fix <fix_id> ...] --json
+mxl-agent.sh repair-apply <session_id> --fix <fix_id> [--fix <fix_id> ...] --json
+mxl-agent.sh undo <session_id> --json
+mxl-agent.sh redo <session_id> --json
+mxl-agent.sh checkpoint create <session_id> --name NAME [--revision N] --json
+mxl-agent.sh checkpoint list <session_id> --json
+mxl-agent.sh validate <session_id> [--revision N] --json
+mxl-agent.sh compat-check <session_id> --target-version 3.1|4.0 [--revision N] --json
+mxl-agent.sh diff <session_id> --json
+mxl-agent.sh semantic-diff <session_id> [--from-revision N] [--to-revision N] --json
+mxl-agent.sh log <session_id> --json
+mxl-agent.sh export <session_id> --output <new-path> --json
+mxl-agent.sh render <session_id> --output <new-svg-path> [--page N] [--revision N] --json
+mxl-agent.sh playback <session_id> --output <new-midi-path> [--revision N] --json
+mxl-agent.sh musescore check <session_id> [--revision N] --json
+mxl-agent.sh musescore export <session_id> --output <path> --format pdf|png|mid|wav|musicxml|mxl [--revision N] --json
+mxl-agent.sh mei export <session_id> --output <path> [--revision N] --json
+mxl-agent.sh mei render <mei-path> --output <svg-path> [--page N] --json
+mxl-agent.sh selection current <session_id> --json
+```
+
+Every result is one JSON object on stdout: `{"ok": true, ...}` or, on an expected failure,
+`{"ok": false, "error": {"code": ..., "message": ...}}` with a non-zero exit code -- never a raw
+traceback. Treat any non-zero exit as "the operation did not happen."
+
+## Generating a new score
+
+Two-stage rule: propose a compact typed plan, never author or paste MusicXML. Full shapes:
+`references/command-catalog.md`. `create from-midi` is the exception (MIDI in, not JSON) and is
+explicitly lossy -- read its `report` before trusting the result.
+
+- `create lead-sheet --spec '<JSON>'` builds a brand-new single-part score (metadata, meter, key,
+  measures of melody/rests and harmony) and opens it as a new session, exactly like
+  `session open`. Doesn't pad short measures itself -- run `lint`/`repair` on the result.
+- `chord-chart parse --text '<chart>'` turns a small text dialect (bars on `|`, whitespace-
+  separated chords, `%` repeats the previous bar) into the `{"offset_q", "symbol"}` list `create
+  lead-sheet`'s `measures[].harmony` expects. Session-independent.
+- `voice chord --symbol '<chord>' --ranges '<JSON>'` voices a chord across ordered voice ranges
+  (pitch pairs or instrument names) -- real chord tones only (tensions under `--profile jazz`), no
+  crossing, doubling avoided until forced; raises `VOICING_UNSATISFIABLE` naming the first
+  unplaceable voice. `voice arrange --symbol '<chord>' --instruments '<names JSON>'` is the same
+  engine for a named ensemble, also reporting each instrument's transposed written pitch.
+  Session-independent.
+- `reharmonize check <session_id> --plan '<JSON>'` validates a reharmonization plan you propose
+  (frozen measures, target positions, candidate chords, optional rationale) -- never invents a
+  chord itself. Reports structural `issues` plus an informational `melody_compatibility` per
+  candidate (not pass/fail). Read-only.
+- `accompany bass`/`guide-tones` materialize one note per `--spans` entry (ordered
+  `{measure_ordinal, offset_q, duration_q, symbol}`), the nearest chord-tone role to the previous
+  note, within one `--range`. `accompany comping` reuses `voice chord`'s engine to stab a full
+  voicing every `--pulse`. All raise `ACCOMPANIMENT_UNSATISFIABLE` naming the failing span.
+  Session-independent.
+
+## Candidate branches
+
+`undo`/`checkout` then a *different* `apply` creates a real branch -- revision numbers are never
+reused (Slice 7.4). To generate/compare alternatives without disturbing the current session:
+`checkout` to the shared starting revision, `apply` each candidate as its own branch, `session
+revisions` to list them, `semantic-diff --from-revision --to-revision` to compare, and
+`validate`/`render`/`playback --revision N` to audition one without moving `current_revision`.
+Accept = `checkout` to that revision; discard = do nothing.
+
+## Operations (for `plan`/`apply --operation`)
+
+The operation envelope's shape and every operation's `selection`/`parameters` fields are in
+`references/selectors.md`. Currently implemented operations:
+
+- `replace_harmony` -- change one existing chord symbol.
+- `insert_harmony` -- add a chord symbol where none exists yet at that offset.
+- `delete_harmony` -- remove one existing chord symbol.
+- `replace_note_pitch` -- change one note's pitch (written, or sounding pitch for transposing
+  instruments).
+- `respell_pitch` -- enharmonic respelling of one note (same sound, different spelling), explicit
+  or key-aware.
+- `transpose_notes` -- transpose every note a selection resolves to by a fixed number of
+  semitones.
+- `insert_note` -- insert a note or rest at an exact onset in an existing voice (append after its
+  current content, or fill a matching rest).
+- `delete_note` -- delete one note, rest, or grace note, either outright or replaced with an
+  equal-duration rest to conserve the voice's total duration.
+- `change_duration` -- change one note or rest's duration, rejecting a change that would desync
+  another voice unless explicitly told to compensate for it.
+- `split_note` -- split one note or rest into two, tied together with correct start/stop pairing
+  if pitched.
+- `merge_tied_notes` -- merge a whole tie chain into one note, when it's entirely within one
+  measure.
+- `create_tuplet` -- convert a consecutive run of notes/rests into a tuplet (time-modification +
+  bracket notation).
+- `move_note` -- move one note/rest to a different staff and/or voice, conserving durations on
+  both ends.
+- `copy_notes` -- copy a consecutive note/rest range to a destination voice, literally or
+  transposed (a "sequence").
+- `set_attributes` -- change key/time/clef/transpose starting at one measure; reports sounding
+  consequences of a transposition change.
+- `set_lyric` / `delete_lyric` -- set or remove a lyric verse (text, syllabic, elision, extend)
+  on one note.
+- `insert_direction` / `delete_direction` -- add or remove a words/dynamics/metronome/segno/coda
+  marking at an exact offset; the `sound` playback attributes stay separate from what's printed.
+- `add_notation` / `remove_notation` -- add or remove an articulation, ornament, or technical
+  mark on one note (idempotent).
+- `set_notehead` -- change one note's notehead shape.
+- `start_slur` / `stop_slur` -- open/close a slur, auto-allocating/pairing its number and
+  validating the stop follows the start.
+- `insert_measure` / `delete_measure` / `duplicate_measure` / `renumber_measures` -- whole-score
+  structural edits, always applied to every part at once to keep them in sync.
+- `set_barline` -- set or clear one measure's left/right barline: style, a repeat sign
+  (forward/backward, optional play count), and/or a first/second-ending bracket. No
+  `bar_style`/`repeat`/`ending` given clears it back to default.
+- `rename_part` -- change one part's printed name and/or abbreviation in the part-list.
+- `set_metadata` -- change score-wide title/movement/creator/rights/source metadata.
+- `set_measure_layout` -- force/forbid a system or page break at one measure, and/or set its
+  printed width.
+- `set_measures_per_system` -- deterministic helper: system breaks exactly periodic (every N
+  measures) over a range, all parts at once.
+- `remove_dangling_tie` / `pad_short_measure` -- safe automatic repairs for a `lint` finding (see
+  below); always take a `fix_id` from `lint`'s output rather than hand-built parameters.
+
+Chord-symbol vocabulary, spelling policies, and written-vs-sounding pitch are covered in
+`references/musical-semantics.md`.
+
+## Analysis (for `analyze`)
+
+Read-only, never mutates -- no `plan`/`apply` two-step needed. Full parameter/result reference:
+`references/command-catalog.md`.
+
+- `active_key` -- the explicit key signature (fifths, mode) in effect at each address the
+  selection resolves to. Locally inferred keys (for passages with no explicit signature) aren't
+  implemented yet.
+- `scale_degree` -- key-relative scale degree (1-7, mode-aware) and chromatic alteration for each
+  selected note. Needs an event-granular selection (one note, or a note range) -- narrow with
+  staff/voice/offset or `event_ids` rather than a bare measure selection; same requirement below
+  wherever "event-granular" is mentioned.
+- `chord_tone` -- classifies each selected note against the chord symbol active at its onset:
+  chord tone (with a role), available tension (jazz profile only), non-chord-tone, or unresolved
+  (no harmony/ambiguous polychord/Roman-numeral harmony). Event-granular. Never guesses an
+  unrelated chord -- only classifies against a chord symbol the score already has.
+- `roman_numeral` -- Roman-numeral (`"V7"`, `"bVI"`) or Nashville-number (`"5m7"`, `"b6"`) label
+  for the chord symbol active at each address, relative to the active key. Flags (but doesn't
+  further classify) chromatic/borrowed chords via `is_diatonic`. Flexible measure-or-event
+  granularity, like `active_key`.
+- `harmonic_rhythm` -- the ordered sequence of chord-symbol changes in a part, each with its
+  exact onset and (same-measure only) duration.
+- `cadence_candidate` -- bare root-motion cadence pattern matches (authentic/plagal/half/
+  deceptive) between consecutive chord pairs -- candidates, not judgments; more matches than real
+  cadences is normal since it can't see phrase position or meter.
+- `non_chord_tone` -- for an already-classified non-chord tone (see `chord_tone`), which figure it
+  resembles (passing, neighbor, suspension, anticipation, appoggiatura, pedal, unknown) from its
+  melodic approach/departure alone, no metric reasoning. Event-granular.
+- `voice_leading` -- common tones and guide-tone (3rd/7th) motion between consecutive chord pairs.
+  Tendency-tone resolution, parallel 5ths/8ves, spacing, and voice crossing aren't implemented yet.
+- `playability` -- checks each note's written/sounding pitch against a named instrument's typical
+  range (`parameters.instrument`, e.g. `"violin"`, `"clarinet_bb"` -- a small curated set, not a
+  full orchestration reference). Event-granular.
+- `note_density` -- notes per quarter note in each resolved measure (same flexible granularity
+  as `active_key`).
+- `syncopation` -- whether each selected note starts off the beat and sustains past the next
+  beat boundary. Motives, polyphony, and doubling aren't implemented yet.
+
+## Lint and repair
+
+`lint` scans the score (or the selection you narrow it to) for a small, stable catalog of
+findings, each with a `finding_id`, `severity`, location, human-readable `message`, and
+`fixable`/`fix_id`:
+
+- `dangling-tie` (error, always fixable) -- a `<tie type="start">` never closed, or a
+  `<tie type="stop">` with no matching prior start.
+- `measure-too-short` (warning, always fixable) -- a single-voice measure short of its active
+  time signature's expected length. A pickup measure or a measure with more than one voice is
+  never flagged.
+- `voice-duration-mismatch` (warning, **not** fixable) -- two voices in the same measure disagree
+  on total duration; report it, don't repair it, since which voice is wrong isn't decidable from
+  the mismatch alone.
+
+For a fixable finding, pass its exact `fix_id` to `repair --fix` -- never hand-construct it.
+`repair` applies through the same typed, footprint-guarded machinery as `plan`/`apply`, producing
+a normal revision `undo` can revert.
+
+To fix several findings together, repeat `--fix` on `repair-plan`/`repair-apply` instead of
+calling `repair` per finding. `repair-plan` dry-runs the group (writes nothing), reporting
+`PATCH_CONFLICT` if two fixes are incompatible. `repair-apply` commits the group atomically, but
+each fix still gets its own revision/`log` entry, so `undo` reverts one at a time.
+
+## Rendering
+
+`render` produces a static SVG page, `playback` a MIDI file -- neither changes the score. Both
+need Verovio (`VEROVIO_UNAVAILABLE` if `doctor` reports it missing). Only whole-score output
+(`render --page N`, default `1`) -- no selection-level rendering yet.
+
+`musescore check`/`export` (a second, independent optional integration) run an open/import
+diagnostic, or export to PDF/PNG/MIDI/WAV/MusicXML, through a real MuseScore CLI --
+`MUSESCORE_UNAVAILABLE` if `doctor` finds none. Its output is diagnostic/export-only, never
+written back into a session.
+
+`mei export`/`render` (through Verovio) convert to MEI or render a standalone MEI file to SVG --
+interoperability only, never an editable input.
+
+If the user has the local viewer (`preview`) open and clicks a note there, `selection current`
+returns `{"addresses": [...]}` -- the fully resolved locator(s) they last selected (`part_id`,
+`measure_ordinal`, `event_id`, etc.), or `{"addresses": []}` if nothing's been selected yet.
+Build a `--selection` from it as `{"event_ids": [<address.event_id>, ...]}`. Only note-level
+clicks are supported (a chord or measure click resolves to whichever note element was actually
+clicked).
+
+## Ambiguity
+
+If a selection resolves to zero or more than one target when the user meant exactly one, the
+operation raises a structured `*_AMBIGUOUS` or `*_NOT_FOUND` error (or, for note-range
+operations, `plan` legitimately returns multiple `changed` entries -- that's normal for a
+*range*, not an error). When it's an error: narrow the selection (add a measure/voice/staff/
+offset, or use an `event_id` from a prior `inspect` call) or ask the user which one they meant.
+Never retry with a broader selection hoping it "just picks one" -- it won't; ambiguity blocks
+mutation by design.
+
+## Safety and preservation
+
+- The original file is never touched. `session open` copies it into an immutable workspace.
+- Every `apply` is mutation-guarded: an operation that changes anything outside its declared
+  footprint is rejected before it's ever written.
+- `apply` always creates a new revision; `undo` is always available for the most recent one.
+- MusicXML 3.1 and 4.0 both supported: `validate` auto-selects the matching schema; `compat-check
+  --target-version` cross-validates against the other version.
+- An `.mxl` with more than one score ("opus") needs `--score` on `session open`;
+  `MULTIPLE_SCORE_ROOTS_AMBIGUOUS` lists the available paths/indices.
+- Full invariants: `references/preservation-and-safety.md`.

mxl_agent-0.1.0/.claude/skills/mxl-agent/evals/evals.json

@@ -0,0 +1,168 @@
+{
+  "schema_version": "1.0",
+  "skill": "mxl-agent",
+  "note": "Structured eval cases per Section 18.1/14.6. Trigger and workflow cases are evaluated by a clean-context Claude Code eval run (not by this repo's deterministic test suite). The end-to-end command sequences below are also covered directly, deterministically, by tests/unit/test_cli_commands.py and tests/unit/test_skill_wrapper.py, which check the tooling those transcripts depend on actually works.",
+
+  "should_trigger": [
+    {
+      "id": "trigger-open-and-transpose",
+      "prompt": "Open chart.mxl and transpose the melody up a whole step.",
+      "expect_skill_used": true
+    },
+    {
+      "id": "trigger-chord-edit",
+      "prompt": "In bars.musicxml, change the chord at measure 3 to Dm7.",
+      "expect_skill_used": true
+    },
+    {
+      "id": "trigger-inspect-only",
+      "prompt": "What key is this piece in? It's in song.musicxml.",
+      "expect_skill_used": true
+    },
+    {
+      "id": "trigger-mxl-mention",
+      "prompt": "Can you validate this .mxl file for me?",
+      "expect_skill_used": true
+    },
+    {
+      "id": "trigger-note-pitch",
+      "prompt": "The second note in measure 5 of lead.musicxml should be an F sharp, not F natural.",
+      "expect_skill_used": true
+    }
+  ],
+
+  "should_not_trigger": [
+    {
+      "id": "no-trigger-daw-mixing",
+      "prompt": "How do I set up a sidechain compressor in my DAW?",
+      "expect_skill_used": false
+    },
+    {
+      "id": "no-trigger-pdf-only",
+      "prompt": "Extract the text from this PDF scan of sheet music.",
+      "expect_skill_used": false
+    },
+    {
+      "id": "no-trigger-plain-midi",
+      "prompt": "Play this MIDI file and tell me what instrument sound 12 is in General MIDI.",
+      "expect_skill_used": false
+    },
+    {
+      "id": "no-trigger-generic-xml",
+      "prompt": "Validate this config.xml against our internal schema.",
+      "expect_skill_used": false
+    },
+    {
+      "id": "no-trigger-theory-only",
+      "prompt": "What's the difference between a Lydian and Ionian mode?",
+      "expect_skill_used": false
+    }
+  ],
+
+  "workflow_adherence": [
+    {
+      "id": "workflow-dry-run-before-apply",
+      "description": "For any edit request, the transcript must show a `plan` call before the matching `apply` call with the same operation JSON.",
+      "assertion": "sequence contains plan(op) immediately or shortly before apply(op) with equal operation/selection/parameters"
+    },
+    {
+      "id": "workflow-inspect-before-edit",
+      "description": "Before constructing a selection by measure/voice/offset, the transcript shows an `inspect summary` or `inspect measures`/`inspect events` call establishing that address -- not a guessed measure_ordinal.",
+      "assertion": "an inspect_* call for the relevant part/measure precedes the first plan/apply call"
+    },
+    {
+      "id": "workflow-validate-after-apply",
+      "description": "After the final `apply` of a session, a `validate` call appears before reporting success to the user.",
+      "assertion": "validate(session_id) appears after the last apply(session_id) and before the final assistant summary"
+    },
+    {
+      "id": "workflow-no-raw-xml",
+      "description": "No tool call or assistant message contains a `<score-partwise` or `<score-timewise` opening tag, or any multi-element MusicXML fragment reconstructed by the model.",
+      "assertion": "absence check across the full transcript"
+    },
+    {
+      "id": "workflow-ambiguity-stops",
+      "description": "When `plan` returns a `*_AMBIGUOUS` error, the assistant does not retry with a broader/different selection hoping for a single match -- it asks the user or narrows using data already inspected.",
+      "assertion": "no plan/apply retry with a materially different selection immediately following an *_AMBIGUOUS error, without an intervening clarification"
+    }
+  ],
+
+  "output_correctness": [
+    {
+      "id": "correctness-chord-edit-e2e",
+      "description": "End-to-end: one chord-symbol edit.",
+      "fixture": "fixtures/chord_symbols.musicxml",
+      "steps": [
+        "session open fixtures/chord_symbols.musicxml",
+        "inspect summary <session_id>",
+        "inspect measures <session_id> --part-id P1",
+        "plan <session_id> --operation '{\"operation\":\"replace_harmony\",\"selection\":{\"part_ids\":[\"P1\"],\"measure_ordinals\":[0]},\"parameters\":{\"symbol\":\"Cm7\"},...}'",
+        "apply <session_id> --operation '<same operation>'",
+        "validate <session_id>",
+        "export <session_id> --output <new path>"
+      ],
+      "assert": [
+        "plan.changed[0].before == 'Cmaj7'",
+        "plan.changed[0].after == 'Cm7'",
+        "apply.revision_after == apply.revision_before + 1",
+        "validate.status == 'passed'",
+        "exported file reopens and contains a Cm7 harmony at part P1 measure 0"
+      ],
+      "deterministic_test": "tests/unit/test_operation_replace_harmony.py, tests/unit/test_cli_commands.py::test_plan_then_apply_then_validate_then_export_then_undo"
+    },
+    {
+      "id": "correctness-transpose-e2e",
+      "description": "End-to-end: transpose a note range up a whole step and verify both written and sounding pitch.",
+      "fixture": "fixtures/divisions_change.musicxml",
+      "steps": [
+        "session open fixtures/divisions_change.musicxml",
+        "inspect events <session_id> --part-id P1",
+        "plan <session_id> --operation '{\"operation\":\"transpose_notes\",\"selection\":{\"part_ids\":[\"P1\"],\"measure_ordinals\":[0]},\"parameters\":{\"semitones\":2},...}'",
+        "apply <session_id> --operation '<same operation>'",
+        "validate <session_id>"
+      ],
+      "assert": [
+        "every changed note's written step/octave shifted up a whole step",
+        "unselected measure(s) are byte-for-byte unchanged (diff.changed_measures excludes them)",
+        "validate.status == 'passed'"
+      ],
+      "deterministic_test": "tests/unit/test_operation_transpose_notes.py"
+    }
+  ],
+
+  "efficiency": [
+    {
+      "id": "efficiency-token-bound",
+      "description": "For the chord-edit and transpose scenarios above, total tool-result bytes returned to the model context should stay under a few KB per call (Section 19.1's 32 KiB/200-item caps), and no call should return a full document.",
+      "measurement": "sum of stdout bytes across all mxl-agent.sh invocations in the transcript"
+    },
+    {
+      "id": "efficiency-no-redundant-open",
+      "description": "The same score is not reopened into a new session mid-conversation when an open session_id for it is already known.",
+      "measurement": "count of session_open calls per distinct input path within one conversation"
+    }
+  ],
+
+  "safety": [
+    {
+      "id": "safety-malformed-archive-fixture",
+      "description": "session open on a hostile/malformed .mxl (zip-slip, encrypted entry, compression bomb) must fail with a structured ZIP_* error and must not mutate anything or crash the wrapper.",
+      "deterministic_test": "tests/security/test_mxl_safety.py, tests/security/test_zip_safety.py"
+    },
+    {
+      "id": "safety-ambiguous-selector-no-mutation",
+      "description": "plan/apply on an ambiguous selection must not write any revision.",
+      "deterministic_test": "tests/unit/test_operation_replace_harmony.py::test_ambiguous_target_without_offset_raises, tests/unit/test_transaction.py"
+    },
+    {
+      "id": "safety-stale-revision-rejected",
+      "description": "apply with a stale base_revision must fail with REVISION_CONFLICT and must not overwrite the newer revision.",
+      "deterministic_test": "tests/unit/test_transaction.py::test_stale_base_revision_raises_revision_conflict"
+    },
+    {
+      "id": "safety-wrapper-rejects-unknown-command",
+      "description": "The wrapper script refuses any first argument outside its allowlist, without forwarding it to a shell.",
+      "deterministic_test": "tests/unit/test_skill_wrapper.py"
+    }
+  ]
+}

mxl_agent-0.1.0/.claude/skills/mxl-agent/evals/fixtures/chord_symbols.musicxml

@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<score-partwise version="4.0">
+  <part-list>
+    <score-part id="P1">
+      <part-name>Lead Sheet</part-name>
+    </score-part>
+  </part-list>
+  <part id="P1">
+    <measure number="1">
+      <attributes>
+        <divisions>1</divisions>
+        <key>
+          <fifths>0</fifths>
+        </key>
+        <time>
+          <beats>4</beats>
+          <beat-type>4</beat-type>
+        </time>
+        <clef>
+          <sign>G</sign>
+          <line>2</line>
+        </clef>
+      </attributes>
+      <harmony>
+        <root>
+          <root-step>C</root-step>
+        </root>
+        <kind text="maj7">major-seventh</kind>
+      </harmony>
+      <note>
+        <pitch>
+          <step>C</step>
+          <octave>4</octave>
+        </pitch>
+        <duration>4</duration>
+        <type>whole</type>
+      </note>
+    </measure>
+    <measure number="2">
+      <harmony>
+        <root>
+          <root-step>D</root-step>
+        </root>
+        <kind text="m7">minor-seventh</kind>
+      </harmony>
+      <note>
+        <pitch>
+          <step>D</step>
+          <octave>4</octave>
+        </pitch>
+        <duration>2</duration>
+        <type>half</type>
+      </note>
+      <harmony>
+        <root>
+          <root-step>G</root-step>
+        </root>
+        <kind text="7">dominant</kind>
+      </harmony>
+      <note>
+        <pitch>
+          <step>G</step>
+          <octave>4</octave>
+        </pitch>
+        <duration>2</duration>
+        <type>half</type>
+      </note>
+    </measure>
+  </part>
+</score-partwise>

mxl_agent-0.1.0/.claude/skills/mxl-agent/evals/fixtures/divisions_change.musicxml

@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<score-partwise version="4.0">
+  <part-list>
+    <score-part id="P1">
+      <part-name>Music</part-name>
+    </score-part>
+  </part-list>
+  <part id="P1">
+    <measure number="1">
+      <attributes>
+        <divisions>1</divisions>
+        <key>
+          <fifths>0</fifths>
+        </key>
+        <time>
+          <beats>4</beats>
+          <beat-type>4</beat-type>
+        </time>
+        <clef>
+          <sign>G</sign>
+          <line>2</line>
+        </clef>
+      </attributes>
+      <note>
+        <pitch>
+          <step>C</step>
+          <octave>4</octave>
+        </pitch>
+        <duration>1</duration>
+        <type>quarter</type>
+      </note>
+      <note>
+        <pitch>
+          <step>D</step>
+          <octave>4</octave>
+        </pitch>
+        <duration>3</duration>
+        <type>half</type>
+        <dot/>
+      </note>
+    </measure>
+    <measure number="2">
+      <attributes>
+        <divisions>2</divisions>
+      </attributes>
+      <note>
+        <rest/>
+        <duration>8</duration>
+        <type>whole</type>
+      </note>
+    </measure>
+  </part>
+</score-partwise>