Phase 4's merge predicate, plus a housekeeping pass that found six documents lying about the tree

[SuperInstance]

Two things: the merge predicate, and a documentation audit that turned up more
than expected.

A conflict between two agents is decidable

from plainsong.notation.merge import merge

result = merge(base, mine, theirs)
result.ok           # False only when both sides wrote the same bar differently
result.conflicts    # [section 1, melody, bar 1] -- a coordinate, not a diff hunk

An edit occupies a set of (section, row, bar) cells, and two edits conflict
exactly when those sets intersect.

What the matrix actually bought was not what the plan claimed.
Row-disjointness — two agents on @bass and Melody: — is something a
file-per-voice layout already has, and plainsong-mcp already had it. What only
a coordinate per bar can decide is that two edits to the same row don't
overlap: bars 1–4 against bars 5–8 of one melody. That is the case the lock was
actually serialising.

Three rules, each mutated and confirmed to turn the suite red:

• Bars numbered the way the arranger counts them — a repeated row continues,
  so two Melody: rows are bars 0–3, not 0–1 twice. (fails 1 test)
• A removal is a change — otherwise a deleted row reads as no edit and the
  other side's work is resurrected. (fails 2)
• The base is required — without it an untouched copy cannot be told from a
  deliberate revert. (fails 6)

plainsong-mcp's _FileLock is deliberately untouched: that is live
concurrency control in another repository and wants its own diff plus a test
that runs two writers, not one that reasons about them. The plan says "the
predicate is done; the ensemble is not" rather than rounding up.

A third-party MCP client has now connected

The caveat that had stood since the server was written — "never had a real MCP
client connect to it" — is closed by doing it. Driven with the official mcp
Python SDK 2.0.0 over stdio: initialize returns plainsong 1.1.0 on protocol
2025-06-18; 27 tools, 9 resources, 2 prompts enumerate; compile_score
round-trips inline notation; a resource reads back; a call missing a required
argument returns isError: true.

One finding recorded rather than fixed. Notation the compiler cannot read
returns isError: false with the failure in the content (error: no sections found). The tool ran; the music did not compile. Defensible under the
specification, which reserves isError for execution failures — but it means an
agent client must read the diagnostics rather than the flag, which is exactly the
"success is not evidence" trap AGENTS.md warns about, served over the wire.
Changing isError semantics is a decision about the protocol surface, not a
tidy-up, so it is written down and left for you.

The housekeeping found six documents disagreeing with the tree

• Two rename leftovers. examples/plainsong-4-tap-closing-time.song and
  docs/traditions/03-the-tap-songbook.md still carried tap. Renamed. The
  songbook's own hits on that string — jarabe tapatío, patapan, tapestry —
  are song titles and were left alone.
• The README claimed nine complete examples. There are eight.
• SHIPPING.md said 527 tests and 6,333 sources. It is 667 and 6,340 — and
  that document opens by saying every claim in it was checked against the
  working tree, so stale numbers make it lie about itself specifically.
• It still listed the four-note chord cap as open — "D9 sounds like
  D7" — which 1.0.1 fixed. That is the second document found carrying
  that same stale claim; the first was the 1.0.0 changelog.
• Its browser-demo claim was the pre-fix one, describing note counts as the
  guard. Counting is precisely what failed to notice . and - being read as
  rests.
• chart and merge appeared in no reference doc. Now in CLAUDE.md,
  AGENTS.md and docs/architecture.md — which had also grown two lists of the
  same three projections, now one.

The fingerprint is keyed on path, so the rename required re-recording its
baseline. Proved inert the way earlier renames were: the note-hash multiset
across all 6,321 files is b850e4729399e7e5068a13c0 before and after. Not
one note moved, only a path.

Verification

• 667 tests, 7 specs, ruff clean, 6340 file(s) checked, 6321 file(s) compile exactly as recorded.
• Every relative link and image across 35 documents resolves.
• All 24 subcommands the documentation names exist, and the 18 that operate
  on a file were run end to end.
• The demo differential agrees on all eight cases — the check CI cannot run.
• A wheel was built and exercised from outside the source tree, including the
  three new modules.
• No TODO/FIXME/XXX/HACK in the package; no tracked build artifacts.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PBAjxy7cD6DzJ72NX8TJEc