Header typos, the PyPI page, and a release that can be re-run

[SuperInstance]

A fresh agent installed 1.2.0 from PyPI and typed the mistakes a beginner makes.
It found two real things, and the release pipeline had a third.

Header typos were swallowed in silence

key: Zz | tempo: banana | time: 3-4

compiled happily — C major, 100 bpm, 4/4 — and said nothing. Not on
compile, not on check, and not on info --verbose, which documents itself as
showing every diagnostic.

Each still falls back to a default, which is right: a typo in a header should not
cost you the piece. Falling back without saying so is the same fault as Xm9
compiling to a silent bar.

warning: tempo 'banana' is not a number; using 100
warning: time '3-4' is not a metre; using 4/4
warning: key 'Zz' is not a key; sounding in C major

The key warning names the sounding key rather than the text, because the
unreadable text is kept for display — a chart would print Zz over music in C,
so "using Zz major" would have been no help.

The parsers do not raise on nonsense, so this could not be done by catching an
exception. theory.KEY_RE and Meter.readable name each rule once and serve
both the parse and the question "will parsing work", rather than a second copy of
each pattern drifting from the first.

It found a real one immediately. The bundled Hungarian Rhapsody carries
time: 2/4 (Lassan) then 4/4 (Friska) — a human annotation the metre field
cannot express, silently becoming 4/4. The file is left alone (changing the metre
would change the music) and the warning now says what was ignored.

The README is the PyPI page, and its links did not work there

pyproject.toml sets readme = "README.md", so that file is the project page.
Forty-four relative links and one relative image resolved on GitHub and 404'd
on PyPI — where a pip install user reads them. The page told people to read a
dozen documents none of which they could reach, and to compile examples/… files
the wheel does not ship.

All absolute now; images through raw.githubusercontent.com, because a blob
URL serves HTML rather than an image. The examples section says where the
examples actually are, and points pip users at the bundled library, which is
shipped.

tests/test_readme_links.py buys back what absolute links lose: every URL into
this repository is mapped to a path and checked to exist, images may not use
blob, and the version the README claims must match the tree — it said
"Version 1.0" while PyPI shipped 1.2.0.

A release that can be re-run

Three releases in a row are tags with no GitHub Release: each publish step
failed, and the release-notes job depends on it. Worse, it was a dead end —
without skip-existing, a release whose files reached PyPI another way can never
be re-run, because the upload aborts on "file already exists".

skip-existing: true fixes that, and docs/releasing.md now records both traps
that cost real time today: tagging the commit before the version bump merged
(which the workflow's tag check caught, correctly), and what skip-existing
guards, so nobody removes it as noise.

Also

CLAUDE.md now records the measured drift between plainsong/mcp/ and the
sibling: 240 lines across seven of eight files. Most is mechanical, but the
DNS-rebinding guard existed here and not in the published sibling — fixed
separately in plainsong-mcp#2. The ensemble= injection machinery here is
documented as unused, since the sibling never imports this tools.py.

Verification

671 tests, 7 specs, ruff clean, 6339 file(s) checked, 6321 file(s) compile exactly as recorded.

One process note worth keeping: my first attempt at the changelog entry was a
str.replace on ## Unreleased, which no longer exists since 1.2.0 was cut. It
matched nothing and wrote the file unchanged — a silent no-op of exactly the kind
this PR is about. Caught because git status did not list the file. The second
attempt asserts its anchor.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PBAjxy7cD6DzJ72NX8TJEc