1.0.1: the setting 1.0.0 documented but never read, the MCP seam, a recovered melody, and a demo that agrees with the compiler

[SuperInstance]

plainsong 1.0.0 is on PyPI, cut from master. This is everything master did
not have when that happened, and it bumps the version to 1.0.1.

1.0.0 took away a rendering and shipped no way back

This is the one I would want reviewed first, because it is a fault in the
released version rather than in a branch.

1.0.0 changed how chords naming more than four notes sound. The change is right
and was arrived at by measurement — a player thinning a voicing drops the fifth
first and the root second, so taking the bottom four does exactly the wrong
thing, and D9 had been rendering as D7. But it shipped with no way out:
docs/voicing.md told readers to set render.voicing, ArrangeOptions carried
the field, and nothing in the codebase read it from configuration. The setting
existed everywhere except where it mattered.

This repository's own rule is that a change to how existing notation sounds goes
behind a setting. It is now real:

[core]
voicing = "stack"      # the pre-1.0.0 rendering, exactly

• PLAINSONG_CORE_VOICING does it for a single run.
• It sits in [core] beside bar_fill because it decides which notes exist,
  so it changes the MIDI and not merely the audio. render.voicing is still
  honoured — that spelling was published, and ignoring it in silence is the
  same fault being fixed.
• A value that is not a strategy now reports. It previously fell through to
  the default without a word, which is indistinguishable from being obeyed.

Both new guards were removed and the suite confirmed red before restoring them.
The corpus fingerprint is unchanged: 6,321 files compile to exactly the music
they did, which is the point — the default does not move.

And the changelog was worse than the code

1.0.0 shipped a section headed "Known, recorded rather than fixed" explaining
that D9 sounds like D7 — in the same release as the commit that fixed it.
Readers were told the opposite of what the software does, and were not told
the thing they needed: seventy-two files in the bundled corpus render
differently than they used to. That section now says what happened, including
the breaking-change notice it owed.

The dialect detector was deleting a melody

detect_dialect only examined lines beginning with |. The relative dialect
names its harmony first — I | 1 . 3 | 5 . . | — so in a file written that way
it saw no relative evidence at all and fell through to absolute. Every scale
degree then became a token nothing could read.

Measured on the one file here written that way: 0 lines start with a pipe, 14
have a roman numeral in front of one. It compiled to 42 notes with 51
warnings. It is 111 notes with none.

The near-miss is the part worth keeping. An agent asked to clear those warnings
read the bare digits as generation artefacts and replaced all 51 with rests. The
note count held at 42, every test passed, the fingerprint moved by exactly the
one file it should have, and the warnings went to zero — a clean bill of health
for an edit that deleted a tune. A warning that a parser cannot read something
is evidence about the parser at least as often as about the file.

Warnings across all sources: 85 → 3. What remains is honest — two sections
whose header disagrees with their rows, and one file in examples/edge-cases/,
a directory whose job is holding malformed input.

The demo had fallen behind the compiler

The browser demo is the front door, and its chord parser was a table of 18
enumerated qualities while Python moved to an open grammar. Twelve ordinary
symbols worked in the CLI and failed silently in the browser, CM7 among them.
It also carried the same slice(0,4) truncation.

tests/test_demo.py sailed past all of it, because it pinned note counts for
four presets and said nothing about vocabulary. It now compares the two
implementations directly — core aliases, seventh-implied spellings, alt
tables, degree table, every core. Verified in real headless Chromium: presets
match, and the voicing agrees note for note (C13 → E Bb D A on both sides).

The MCP seam, cut where the names fall

plainsong/mcp/ and the sibling repo were ~2,900 duplicated lines with 109
already drifted. Not one thing forked twice — four pieces of technology
wearing one name. features.py is 300 lines of per-bar musical analysis with
nothing protocol-shaped in it; it now sits beside notation/ and perform/.
protocol.py was byte-identical. 490 lines stopped existing in duplicate.

tools.py was assessed and deliberately left — it reached into the ensemble
module seventeen times through a relative import, so sharing it would have
silently bound the sibling's tool surface to this repo's stale ensemble.py.
That is now fixed by injection, and the fix was one line: all seventeen uses
live inside register()'s body as closures, so the implicit binding existed at
exactly one point. Proved with a test that registers against a fake ensemble
module and checks every call routes through it.

The two audiences with no front door

The README assumed a reader who already knew what this was. It now opens with
three doors — you read music but not code, you write code but not music, you are
an agent — and lists every example piece with what each one demonstrates, which
was previously discoverable only by listing a directory.

AGENTS.md is new, and its longest section is a catalogue of mistakes,
because those are the reusable part. Every one was made by an agent working on
this repository: success is not evidence (the compiler turns what it cannot read
into a rest and reports ok); a warning about the parser is not a warning about
the file; never re-record a fingerprint baseline to make CI green; do not
find-and-replace on a word ("Symphony No. 5 in C minor" became "…in Cm"
across 193 files that way); verify from somewhere neutral, because the working
directory is on sys.path.

Also

• Chord roots rejoined to their qualities. | Gb maj7 . . . | was two
  tokens where one was meant — losing the quality and making the bar five
  tokens wide. Six files, nineteen chords, fixed by rule rather than by list.
• N.C. reads as a rest. It already compiled to silence; it just complained
  while doing it.
• The audio path people should use leads. The built-in synthesiser is mono
  and it is the first thing anyone hears; fluidsynth is now documented where a
  reader meets it, in docs/audio.md, with every config key read from the code
  rather than guessed.
• Seventeen filenames the rename missed. Contents were clean, links
  resolved, tests passed — the old name only showed when you listed a directory.
• proposals/02-the-voyage.md, a plan whose two research phases are
  answered and whose remaining unknowns are marked as unknowns.

Verification

597 tests, 7 specs, ok 6334 file(s) checked, 3 warning(s), ruff clean, and
6321 file(s) compile exactly as recorded.

Every change that could alter what notation compiles to was checked against the
fingerprint before re-recording it, never after. The two renames were proved
inert by comparing the multiset of note hashes across all 6,321 files — identical
both times, only paths moved.

What this unblocks

plainsong-mcp pins the compiler by git URL because 1.0.0 predates
plainsong.features. Merging this and releasing 1.0.1 makes that pin a version
specifier, which is the only line in that repository that has to change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PBAjxy7cD6DzJ72NX8TJEc