head_music 20.1.0 → 21.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3714d51858bd368308d14a5f12544e6f4fb9dbecf0f0eacc1ad795c5e4b3d1e
-  data.tar.gz: 99345ffa2b44dfbdc27836b7b7350a38af1665770a74490f52e22bd1a0aa3602
+  metadata.gz: eadecb642354dfc4c70cf00303a0c1c27513fdd38b13d8bc81fe9c8e7fd3214b
+  data.tar.gz: b534a1e194b0bd6ba4dae42433e92091812e434ec0fddb03c7617e47147207ab
 SHA512:
-  metadata.gz: d95aa74479fe498564dc7e1bc5427660b9687e286a31a4b5cbbb1c0a274bebe9413ae18e2176dbbf38c351e4b1517275d5bf8dce590642c88c2301ea83f038b6
-  data.tar.gz: 4446808775faf30ef42dceca7de10248a88d8c8265ab4faa3c11589bd6ddb7dd60ff9c10ce2cb34a68f9e039061bc3633484e01b2002f649bb3f885bd5d7e968
+  metadata.gz: aa22ebc311f8ebe62590e99f90f0d65d639b250626f9668520cd604e0f2fec4c1ea7af4d9b944a19585c52ea1b941906f12d2910888e0a4005a7f582936547ec
+  data.tar.gz: fde9ba8d894229bc349c861b24a0e56108f2a718526b67465c7b8631c9401a8d243196d4f632d1ebce890726c718b4371d2110fcc4e80eef39747d7ec1e610a1

data/.claude/skills/release/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: release
+description: Prepare and publish a head_music release. Verifies the previous version actually shipped, settles the bump with the user, moves Unreleased into a dated CHANGELOG section, bumps version.rb and Gemfile.lock, runs the suite, writes the release commit, and stops before tagging and publishing. Use when the user asks to release, cut a version, bump the version, or publish the gem.
+---
+
+# Release
+
+The version bump and the release are one transaction. The bump commit is the
+release commit, and a version that is bumped but never tagged and pushed is a
+defect, not an intermediate state. This skill prepares everything, then stops
+before the irreversible step.
+
+## 1. Preflight
+
+Run these before touching anything. Stop and report if any fails.
+
+- On `main`, clean working tree, up to date with `origin/main`.
+- The previous version shipped. Compare `lib/head_music/version.rb` with
+  `gem search -r -a head_music`. If the version file is already ahead of
+  RubyGems and its CHANGELOG section carries a date, a bump was committed but
+  never published. Say so. The fix is usually to fold the new entries into
+  that section and release it, not to bump again.
+- The `## [Unreleased]` section of `CHANGELOG.md` has entries. If it is
+  empty, there is nothing to release.
+- `bundle exec rake` passes with coverage and `bundle exec rubocop` is clean.
+
+## 2. Choose the bump
+
+Read the Unreleased subsections and put the choice to the user. Do not decide
+alone when a Changed or Removed subsection is present. The project's
+convention so far:
+
+- Additive only (Added, and Fixed): minor.
+- Behavior changes with no signature change, such as a grading rule that
+  regrades existing melodies: minor, called out in the release intro.
+- A removed class or method, a serialization schema bump, or a document that
+  needs migration: major. 21.0.0 is the model.
+- Fixes only: patch.
+
+## 3. Prepare
+
+- In `CHANGELOG.md`, rename `## [Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD`
+  with today's date, and insert a fresh empty `## [Unreleased]` above it with
+  blank lines around both headings. Subsections stay in Keep a Changelog
+  order: Added, Changed, Deprecated, Removed, Fixed, Security.
+- For a minor or major release, open the section with a short intro
+  paragraph the way 21.0.0 and 21.1.0 do: what the release is for, and a bold
+  sentence naming the bump and what a consumer must do to upgrade.
+- Set `VERSION` in `lib/head_music/version.rb`.
+- Run `bundle install` so `Gemfile.lock` records the new version.
+- Run `bundle exec rake` and `bundle exec rubocop` again.
+- Show the user the diff: CHANGELOG, version file, lockfile, nothing else.
+
+## 4. Commit and push
+
+Only when the user asks. Subject is `Release X.Y.Z`. Add a body only when the
+number needs explaining, such as why a release is major or which behavior
+changed. Push `main`.
+
+## 5. Tag
+
+Stop here. Do not tag without the user's explicit go in this conversation.
+Pushing the tag starts the publish, and a published version cannot be
+withdrawn.
+
+```bash
+bundle exec rake release:source_control_push
+```
+
+This creates the annotated tag `vX.Y.Z` and pushes it. It does not push the
+gem. The tag push triggers `.github/workflows/release.yml`, which runs the
+suite and linter, builds the gem, creates the GitHub Release, and publishes to
+RubyGems through trusted publishing. Do not run plain `rake release`: its gem
+push would race the workflow's, and one of them would be rejected as a
+re-push.
+
+Prerequisite, once: the workflow must be registered as a trusted publisher at
+rubygems.org/gems/head_music/trusted_publishers, with repository
+`roberthead/head_music` and workflow file `release.yml`.
+
+## 6. Verify
+
+- `gh run watch` on the run that the tag started, or
+  `gh run list --workflow=release.yml --limit 1`. Report its status. Do not
+  assume it passed. The workflow failed on every run before 2026-09-10, first
+  on a denied API key and then on an action version that did not exist.
+- `gem search -r head_music` lists the new version.
+- `gh release view vX.Y.Z` shows the GitHub Release with the gem attached.
+
+If the workflow fails after the tag is pushed, the fallback is
+`bundle exec rake release:rubygem_push`, which needs a RubyGems one-time
+password and so is the user's to run with the `!` prefix.

data/.github/workflows/release.yml

@@ -43,8 +43,10 @@ jobs:
     # short-lived credential, so there is no API key to store or rotate.
     # Requires head_music to have this workflow registered as a trusted
     # publisher at rubygems.org/gems/head_music/trusted_publishers.
+    # The action publishes full version tags only, no v2 alias, so it is
+    # pinned to a release.
     - name: Configure RubyGems credentials
-      uses: rubygems/configure-rubygems-credentials@v2
+      uses: rubygems/configure-rubygems-credentials@v2.1.0
 
     - name: Publish to RubyGems
       run: gem push *.gem

data/CHANGELOG.md

@@ -7,6 +7,151 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [21.1.0] - 2026-09-10
+
+The [organizing content](https://github.com/roberthead/head_music/tree/main/user-stories/epics/organizing-content.md) epic's second story. 21.0.0 separated the document from the music; this separates the music from what it *is* and from how it is *shown*. A flow may now cite a `Work` — the piece, with its catalog number and its people — while a project credits whoever made *this version* of it, so Bach is credited for the work and Segovia for the arrangement. A `Layout` is a view of a project: which flows, which players, concert or written pitch, under what title. Two layouts over one project — a transposed score and a flute part book — are two documents from one body of music.
+
+**This is a minor release.** Everything below is additive: no public method changes signature or return type, `Flow#composer` is still a `String` or nil, `Flow.new`'s keywords are only extended, every writer's new option defaults to what it did before, and `Flow#to_abc`, `#to_lilypond`, and `#to_musicxml` are byte-identical for every flow that existed in 21.0.0. The serialization schema stays at 4 (see the last entry). The one behavioral change is the contour grading under Changed, which alters no signature but does regrade some melodies. A consumer upgrades by upgrading.
+
+### Added
+
+- **`HeadMusic::Content::Work`, with `Person`, `Credit`, `Credits`, and `Role`.** A work is the catalog identity of a composition — a title, a catalog number, a year, and its people — independent of any one notated version of it. A `Flow` may cite one, or cite none, and flows in one project may cite different works: a sonata is one project whose four flows cite one work, a fake book is one project whose eighty flows cite eighty, and a counterpoint exercise cites none. Putting the identity on the project instead would have made the model lie in exactly the cases this gem is most used for.
+
+  **Credits are constrained by the level they attach to**, so the model cannot record a publisher as having composed the music:
+
+  | Level | Roles |
+  |---|---|
+  | `Work` | composer, songwriter, lyricist, librettist |
+  | `Project` | arranger, transcriber, orchestrator, reconstructor |
+  | `Publication` | author, editor, engraver, publisher |
+
+  `Credits.new(level)` is the single place that constraint is enforced — `credits.add(person, :arranger)` on a work raises `ArgumentError` naming both levels — and `Credit` itself is level-agnostic. `Role` is `Named` and translated like the rest of the gem's vocabulary, but unlike a rudiment getter an unrecognized identifier raises rather than minting a role: the twelve are the whole vocabulary. `Person` is one identity rather than one spelling of a name, requiring a full name, with an optional sort name and independently optional birth and death years; `Work`, `Person`, `Credit`, and `Credits` are all frozen values, so two flows citing the same work hold two equal objects and `project.works` deduplicates them.
+
+- **`Flow#work` and `Flow#source`, and `Project#credits`.** `Flow#composer` now answers the cited work's composer and falls back to the authored string, which is what the ABC `C:` and LilyPond `composer =` readers fill with text like "Trad." or "arr. J. Smith" — not a person, and never minting a work. A work with no composer credit falls through to the string too, so a lyricist-only work still prints the name it was authored with, and `Flow#to_h` writes the derived string, so **every existing document renders exactly as it did**. `origin` stays a plain string: ABC's `O:` is geographic provenance, which nothing at the work level holds. `Project#add_credit(person, role)` records this version's people.
+
+- **`HeadMusic::Content::Publication`**, the edition a flow cites as its `source` — the book, treatise, or score, with its own credits, distinct from the work it publishes. `CantusFirmus::Source` is now a `Publication` carrying a catalog key: `Source.get`, `.all`, `.keys`, `#publication_name`, `#publication_edition`, `#author_names`, `#abbreviation`, and `#notes` are all unchanged, and their specs pass unedited. `Example#to_flow` cites its source on the flow it builds, so the citation is a fact about the music rather than only about the catalog, and a serialized source round-trips through its key back into the catalog entry itself. `author` joins the publication-level roles because these sources are treatises, whose people are authors rather than editors.
+
+- **`HeadMusic::Content::Layout`.** A layout selects flows and players (`nil` means all of them), renders in concert or written pitch, and titles the document with `title_override` — which changes what is displayed without touching `work.title` or `flow.name`. A selected flow that no selected player has a part in is skipped rather than rendered empty: a flute part book has two movements, not a silent third. A layout refuses a flow or player its project does not hold, so a stray selection fails when it is made rather than serializing as an absence, and `add_layout(kind: :score)` answers a `Score`, so every layout reads back as the class it was written as.
+
+  ```ruby
+  score = project.add_score(ensemble_type: :orchestral, concert_pitch: false)
+  book  = project.add_layout(kind: :part, players: [flutist], title_override: "Flute")
+  ```
+
+  Each format renders a document of the shape that format has for a book: `#to_abc` writes a tune book, one numbered `X:` per flow separated by a blank line, which `ABC.parse_book` reads back; `#to_lilypond` writes one document with one `\header` and one `\score` per flow, each headed with its movement's own `piece`, via the new `LilyPond::BookWriter`; and because MusicXML holds one flow per document, `#to_musicxml_documents` answers one string per flow and `#to_musicxml` raises for more than one, naming the plural method. Rendering goes through a realized flow rather than through writer options, so the writers, both render plans, and both preflights know nothing about selection — and an all-flows, all-players, concert-pitch layout of one flow renders byte-identically to that flow's own output, in all three formats.
+
+- **`HeadMusic::Content::Score`,** the layout that shows the players together. `#ordered_players` is a permutation of the layout's players in the ensemble's conventional order, and `#player_groups` splits them into the sections a score brackets. Neither is the score's own knowledge: `Instruments::ScoreOrder` already carried it per ensemble type and now exposes `#position_of(instrument)`, `#section_key_of(instrument)`, and `#group(instruments)`, sharing one section index with `#order` so ordering and grouping cannot disagree. Ties keep authored order, so two clarinets stay first and second, and a chair with an unknown instrument or none at all sorts last under a `nil` section key rather than disappearing. `ensemble_type` must be a `ScoreOrder` key or nil, which is authored order.
+
+- **Transposition to written pitch.** A transposed layout renders each part at the pitch its player reads. The move is spelled rather than counted — the semitones decompose into a diatonic interval plus whole octaves — so a clarinet's sounding D is a written E and never an F♭, and a key signature moves by moving its tonic spelling and keeping its scale type rather than by arithmetic on fifths.
+
+  **Each part gets its own written key**, so a mixed ensemble renders as one document: a transposed score of flute, B♭ clarinet, and horn in F carries three key signatures, and a part that picks up an A clarinet at bar 9 gains a key change there that no other part sees. The written key is derived at render time by `Notation::RenderPlan`, whose `#first_measure_key` and `#measure_key_changes` now take the part; it is a rendering fact, not content, so it reaches no model field and no schema key. MusicXML gains `<transpose>` after `<clef>`, LilyPond a `\transposition` per staff, and ABC writes the written key into `K:`. Concert pitch means sounding pitch for every part, octave transposers included. A written key needing more than seven sharps or flats raises `RenderError` naming the enharmonic to write the part in instead, rather than failing midway through assembly.
+
+- **Writer options, each defaulting to prior behavior**: `transposed:` on `ABC.render`, `LilyPond.render`, and `MusicXML.render`; `work_title:` and `movement_number:` on `MusicXML.render`, which emit `<movement-title>` and `<movement-number>` only when a document names a whole this flow is one movement of; and `arranger:` on `LilyPond.render` and `MusicXML.render`, which emit `arranger = "..."` and `<creator type="arranger">`. A `Layout` fills the last of these from `project.credits`, which is what makes the story's arranger visible on the page; `Flow#to_*` passes none of them, so its output is unchanged. ABC has no arranger field and no book title, so a multi-tune layout's title is not rendered there.
+
+- **Optional document keys**: `"work"` and `"source"` on a flow, `"credits"` and `"layouts"` on a project, all absent-means-none. **The schema stays 4.** The rule, now written into `references/content-schema.md`: a rename or a container restructure bumps the schema version, because an old reader would read such a document *wrongly*; a new optional key does not, because the readers look up the keys they know and never enumerate the hash. A 21.0.0 reader accepts a 21.1.0 document and ignores what it has no home for — and `"composer"` still carries the derived name, so even that loss does not reach the page. Bumping to 5 would only have made 21.0.0 reject documents it reads perfectly well.
+
+### Changed
+
+- **`Style::Guidelines::Contoured` judges arch and valley by the whole line.** An arch is now a melody whose trend directions are exactly ascending then descending, one rise past the reversal threshold and one fall, and a valley is the mirror. Before, an interior climax alone made an arch, so a line that rose a third, plunged a sixth, and climbed back passed arch, valley, and wave at once. Arch, valley, and wave are now mutually exclusive. Neighbor-note motion stays under the threshold, so an arch with a passing dip on the way up, or a 7-1 step at the close, still reads as an arch. **Some melodies previously graded as arch or valley now grade as wave, or as no contour at all**: in the pinned corpus, 47 of the 63 voices that passed `arch_contour_melody` and 23 of the 26 that passed `valley_contour_melody` now fail it. Nearly all of those are published cantus firmi and first-species lines that rise and fall more than once and now read as waves; a few that climb without a real reversal read as ascending only. `ascending`, `descending`, `static`, and `wave` are unchanged, as are the registered contour guides and their gates.
+
+## [21.0.0] - 2026-09-06
+
+The [organizing content](https://github.com/roberthead/head_music/tree/main/user-stories/epics/organizing-content.md) epic's first story. `Content::Composition` was the document, the movement, the timeline, and the credits at once, and its `Voice` was a bare melodic line with no instrument, no staff, and no performer — a shape adequate for two-voice species counterpoint and for almost nothing else. Content is now `Project` → `Flow` → `Part` → `Voice` → `Placement`, and a voice can cross between the staves of its part.
+
+This is a breaking release. `Composition` is removed rather than deprecated, and the serialization schema goes to 4.
+
+**Migrating from 20.1.0**, in the order a consumer will hit them:
+
+1. **`HeadMusic::Content::Composition` is `HeadMusic::Content::Flow`.** The constant is gone, not aliased. `Flow.new` takes the same keyword arguments, and `#add_voice`, `#voices`, `#bars`, `#to_h`, `#to_abc`, `#to_lilypond`, and `#to_musicxml` all behave as they did, so most call sites need only the constant renamed. `#add_voice` now mints a `Part` per voice behind the scenes; every document this gem produced before still renders byte-identically.
+
+2. **`LilyPond.parse` and `ABC.parse` return a `Flow`.** So do `ABC::BookParser#flows` (was `#compositions`) and `LilyPond::FlowBuilder` (was `CompositionBuilder`). These changed return type five days after the LilyPond reader shipped in 20.1.0; they are named individually here because a reader scanning for "Composition" will not otherwise notice that `parse` moved.
+
+3. **Persisted schema-3 documents need one read-and-re-save.** `Flow.from_h` rejects a v3 hash with an error naming `Flow.from_v3_h`, which is retained read-only for this reason and removed in 22.0.0. The previous bumps shipped a key-rename recipe — v2 to v3 was "rename each placement's `pitches` key to `sounds`", doable in SQL against a jsonb column — but v3 to v4 restructures the container, so no equivalent recipe can be written. **20.1.0 is the last version that reads v3 directly.**
+
+4. **`HeadMusic::Content::Staff` is a different class under the same name.** The 20.x `Content::Staff` was dead code, referenced by nothing but its own spec, and has been deleted; the constant is now the instance-layer staff described below. The new one takes only keyword arguments, so `Content::Staff.new(:bass_clef)` raises `ArgumentError` rather than quietly reading the clef as something else — but the readers changed too: `#default_clef` is `#clef` (and answers `nil` where none was authored, rather than falling back to treble), and `#instrument` is `#instruments_staff`, which references the catalog staff instead of an instrument.
+
+5. **`Time::MusicalPosition#beat` is `#count`**, and `FIRST_BEAT` is `FIRST_COUNT`. `Meter` already distinguished the two — 6/8 has two beats and six counts — so a position was misnamed against the gem's own vocabulary.
+
+6. **Grades do not move.** Every guide assesses every voice of the pinned corpus to the fitness it produced before the refactor began, which is asserted rather than assumed. Stored fitness from 20.x remains comparable.
+
+### Added
+
+- **`HeadMusic::Content::Project`, `Flow`, `Part`, and `Player`.** A `Project` is the document: players and flows. A `Flow` is a continuous span of music owning its own timeline — a movement, a song, a cue, an exercise. A `Player` is a chair in the project ("Flute 1", "Piano"); a `Part` is that chair's music within one flow. Pairing them that way is what makes "the flute plays in movements 1 and 3" expressible without a nullable join — there is simply no `Part` for that player in movement 2 — and what makes an instrument change *within* a part honest, since conceptually it is still the same player.
+
+  **Containment is total; context is optional.** A voice is always in a part, always in a flow, so `voice.part.staff_system_at(bar)` never needs a nil check. What is optional is the upward reference: `Flow#project` and `Part#player` may be absent. A flow with no project is how a chunk of music lives outside a document — a cantus firmus, a scale, a parsed snippet — and it renders to ABC, LilyPond, and MusicXML with no project at all. `Project#add_flow` adopts such a flow, minting a player for each part that has none.
+
+- **Voices orthogonal to staves.** A voice belongs to a part and *has* a staff at any given moment, so a piano voice can start in the bass staff and cross into the treble without leaving its part:
+
+  ```ruby
+  left_hand.cross_to(treble_staff, from: 5)
+  left_hand.cross_to(bass_staff, from: 9)
+  left_hand.staff_at(6)   # => the treble staff
+  left_hand.staff_at(9)   # => back to the bass staff
+  ```
+
+  A crossing is one event, not a span: a left hand that rises for four bars and comes back down is two crossings, each authored where it happens, and a single cross-staff note is a crossing and, a bar later, another. There is no note-level special case, and nothing to overlap.
+
+  MusicXML renders the part as one `<score-part>` with `<staves>`, a numbered `<clef>` per staff, `<voice>` per voice separated by `<backup>`, and `<staff>` per note. LilyPond renders a `\new PianoStaff` (or `\new StaffGroup` for a bracket) with one named `\new Staff` per staff and `\change Staff` at the span boundaries. Both elements are omitted for a one-voice, one-staff part, so existing output is unchanged.
+
+- **`HeadMusic::Content::Staff` and `StaffSystem`** — the instance layer. A content staff has a line count, a clef map, and an optional reference to an `Instruments::Staff` for percussion mapping; the catalog class already owns the position-to-instrument mappings, so the instance layer references rather than re-implements it. A `StaffSystem` is an ordered set of staves with a brace, a bracket, or neither; `StaffSystem.grand_staff` and `.single_staff` are the two shapes almost everything uses.
+
+- **`HeadMusic::Time::EventMap`** — an ordered list of `(position, value)` events answering what is in force at a position. Everything that changes partway through a flow is this shape, and it is now written once: meter, tempo, and key signature on `Flow::Timeline`; instrument and staff system on `Part`; clef on `Staff`; staff assignment on `Voice`. Lookup is a binary search over tuples computed at insert. `#change_at` answers whether a change *starts* at a position, as distinct from what is in force there, which is what a writer needs in order to decide whether to print a signature.
+
+- **`HeadMusic::Time::KeySignatureEvent`**, carrying a signature as fifths and, optionally, the interpretation of it. Neither derives the other. A signature underdetermines its interpretation — two sharps is D major, B minor, E dorian, or A mixolydian — and an interpretation does not fix its signature either, because the two legitimately diverge: C dorian written in cantus mollis takes the parallel minor's three flats and naturalizes the sixth.
+
+  Fifths rather than a `KeySignature` because a `KeySignature` cannot be built from a bare signature: `KeySignature.get("3 flats")` raises, so naming three flats means naming an interpretation of it, after which the stored tonic and quality are wrong whenever the interpretation disagrees. Fifths is also exactly what MusicXML stores.
+
+- **`HeadMusic::Rudiment::Key.for_fifths(n)`** — the conventional reading of a signature that carries no interpretation of its own, for the two consumers that cannot proceed without a tonic: LilyPond's `\key`, and the `Diatonic` guideline. Signatures themselves are unbounded, since a theoretical key such as G♯ major counts each double accidental twice and reaches eight; the table stops at ±7, because past that there is no conventional major key to name. So past ±7 a `tonal_context` is required, and `change_key_signature` raises at authoring time rather than leaving every reader that needs a tonic to raise later.
+
+- **`HeadMusic::Content::CantusFirmus::Example#to_flow(rhythmic_value:, meter:)`.** An example was a catalog datum — a pitch list with a mode and a citation — that nothing in the gem turned into music. It now realizes as a standalone flow with one part, no player, and one note per bar. Rhythm and meter are the realization's choice rather than the datum's, so they are parameters.
+
+- **`Project#to_h` / `.from_h` / `#to_json` / `.from_json`**, and `Flow.from_v3_h`. Schema 4 round-trips players, flows, parts, voices, staff assignments, instrument changes, staff systems and their changes, clef changes, tempo and tempo changes, subtick-precise positions, and repeat structure, and round-trips a standalone flow as its own document. A tempo serializes as `{"beat_value", "beats_per_minute"}` rather than as a `"quarter = 72"` string, because `Tempo.get` reads the number by stripping non-digits and would turn 72.5 into 725.
+- **`Flow.new(tempo:)`, `Flow#tempo`, and `Flow#change_tempo`**, alongside the meter and key signature equivalents. A tempo change allocates its bar the way a meter change does, and accepts a `Tempo`, a tempo name, or a `"quarter = 96"` string.
+- **`Flow#remove_meter_change`, `#remove_key_signature_change`, and `#remove_tempo_change`** un-author a change, answering the removed value. 20.x cleared a change by passing `nil` to `change_*`; that now raises an `ArgumentError` naming the remover, rather than reaching a rudiment getter that would raise something unrelated.
+
+- `Flow#position`, `Content::Position#subtick`, `Voice#assign_staff`, `Part#instrument_at` / `#staff_system_at` / `#instruments`, `Player#instruments` / `#primary_instrument` (derived from the parts, so they cannot drift from the instrument changes authored on them).
+
+### Changed
+
+- **Schema version 4.** `Flow#to_h` carries a `timeline` (opening meter and key signature, plus the changes to each) and `parts` (each with its instrument, instrument changes, staff system, and voices). Key and meter changes are no longer serialized per bar; a bar's own state is its repeat structure.
+
+- **`Content::Bar` keeps only what is bar-shaped** — barlines, repeat structure, volta brackets. Its `#key_signature` and `#meter` are now derived reads of the change *authored in that bar*, and the writers `#key_signature=` and `#meter=` are gone; use `Flow#change_key_signature` and `#change_meter`. The bar had been carrying these in parallel with `Time::MeterMap` doing the same job properly and unused by `Content`.
+
+- **`Clef.get(:tenor_clef)` is the C clef on the fourth line**, as in every theory text. It had been an alias of `vocal_tenor_clef`, the octave-down G clef of vocal scores, which won the lookup by appearing first in the catalog; that clef keeps its own name and its `tenor_g_clef` alias. `tenor_c_clef` still names the C clef too.
+- **Meter and key signature changes take a bar number, and reject anything else.** Both are bar-aligned by definition, so `flow.change_meter("2:3", "3/4")` raises rather than rounding into a bar.
+
+- **`Content::Position` wraps a `Time::MusicalPosition`.** It gains a subtick, and is normalized once at construction and then frozen — it is a sort key that `Voice#place` binary-searches over, and a mutable sort key is a wrong-note bug that raises nothing. `#eql?` and `#hash` are defined on the component tuple alongside `#<=>`; the flow deliberately takes no part in comparison, preserving the behavior `Voice#placement_at` has always guarded with. `#values` is removed in favor of `#to_a`, which now has four components. `#code` emits a subtick only when there is one, so the everyday `"bar:count:tick"` form is unchanged.
+
+- **`Notation::RenderPlan#key_value` receives a key signature event** rather than a key signature, because the two formats want different things from it. `MusicXML::KeyMapper.mode` now takes a tonal context and returns `nil` where there is none, and the writer omits `<mode>` rather than inventing a major. LilyPond renders what is printed at the clef: the interpretation where it agrees with the signature, so a D dorian flow still prints `\key d \dorian`, and the signature where they diverge, so cantus mollis prints `\key c \minor`.
+
+- **`Notation::ClefSelector` is demoted to a fallback.** When a staff has an authored clef the writers use it; the selector infers one from a voice's pitch range only for a part whose staves were never authored — an ABC import, a bare counterpoint exercise. The fallback stays in the writers rather than moving onto `Staff`, because it reads a *voice's* range and a staff has no back-reference to one.
+
+- `Time::PPQN` is an alias of `Rudiment::Rhythm::PPQN` rather than a second literal 960.
+
+### Removed
+
+- `HeadMusic::Content::Composition`, and the dead `HeadMusic::Content::Staff` (see migration note 4).
+- `HeadMusic::Time::EventMapSupport`, superseded by `Time::EventMap`.
+- `Time::MusicalPosition#to_total_subticks` and its `#to_i` alias, `TempoMap#normalize_position`, and `TempoMap#meter=` — all of which existed to support the comparator fixed below.
+
+### Fixed
+
+- **`Time::MusicalPosition#normalize!` destroyed the last count of every bar.** `RadixCarry#carry` used `divmod`, which is correct for the 0-indexed tick and subtick and wrong for the 1-indexed count: in 3/4, `1:3:0:0` normalized to the invalid `2:0:0:0`, and so did `1:4:0:0` in 4/4 and `1:6:0:0` in 6/8. A 1-indexed component is now shifted into 0-indexed space and back.
+
+- **`Time::MusicalPosition#<=>` was not a total order across a meter change.** It converted both positions to elapsed subticks through a single stored meter, assuming every prior bar had it, so a position in bar 4 of 4/4 compared *greater* than one in bar 5 of 7/8. Positions now compare their component tuple lexically, which needs no meter at all.
+
+  Both bugs were latent in 20.x only because `Time` was unused by `Content`. They are on the path every note travels now.
+
+- **A `Content::Position` rolled across a meter change kept the origin bar's count unit.** The tick carry ran under the meter of the bar the position started in, so a quarter after `1:4:480` in 4/4 landed in a 6/8 bar spelled `2:1:480`, where the same instant is `2:2:000`; the two compared unequal, so a placement rolled into the bar and one authored there did not merge. A position is now carried again under the destination bar's meter until it lands in a bar it was carried under.
+
+- **MusicXML `<backup>` rewound a whole measure regardless of what the preceding voice wrote.** In a multi-voice part whose earlier voice ended mid-bar, the cursor went negative -- invalid MusicXML, with no error. It now rewinds by the duration actually written. Whole-measure filler rests also carry `<voice>` and `<staff>`, where before a reader stacked them onto voice 1 of staff 1 and left a grand staff's bass staff empty.
+
+- **Every clef the gem knows renders to LilyPond** by its LilyPond name -- alto, tenor, soprano, mezzosoprano, baritone, varbaritone, french, subbass, percussion, and the quoted octave clefs `"treble_8"` and `"treble^8"` -- where an authored clef other than bass had rendered as treble.
+
+- **A part with no voices renders**, in both writers, as a staff of whole-measure rests under its clef, key, and time, so a tacet chair keeps its line in the score. LilyPond had dropped the part; MusicXML had raised `NoMethodError`.
+
+- **A one-staff part holding several voices renders in LilyPond as one staff** with a `\new Voice` per voice in parallel, named for its part, as MusicXML already rendered it. It had rendered as one staff per voice.
+
 ## [20.1.0] - 2026-09-05
 
 The other half of the LilyPond export released in 20.0.0. A document written by the writer, or by hand, now reads back into a composition, so `parse(render(composition))` reproduces the music. Nothing in 20.0.0 changed shape; a consumer upgrades by upgrading.
@@ -731,7 +876,8 @@ note = HeadMusic::Rudiment::Note.get("F#4 dotted-quarter")
 
 For changes in versions prior to 0.28.0, please refer to the git history.
 
-[Unreleased]: https://github.com/roberthead/head_music/compare/v20.1.0...HEAD
+[Unreleased]: https://github.com/roberthead/head_music/compare/v21.0.0...HEAD
+[21.0.0]: https://github.com/roberthead/head_music/compare/v20.1.0...v21.0.0
 [20.1.0]: https://github.com/roberthead/head_music/compare/v20.0.0...v20.1.0
 [20.0.0]: https://github.com/roberthead/head_music/compare/v19.0.0...v20.0.0
 [19.0.0]: https://github.com/roberthead/head_music/compare/v18.0.0...v19.0.0

data/CLAUDE.md

@@ -10,42 +10,18 @@ HeadMusic is a Ruby gem for Western music theory. It provides a comprehensive to
 
 ### Essential Commands
 
-```bash
-# Install dependencies
-bin/setup
-
-# Run tests with coverage
-bundle exec rake
-
-# Run tests without coverage
-bundle exec rspec
-
-# Run a specific test file
-bundle exec rspec spec/head_music/rudiments/pitch_spec.rb
-
-# Run linting
-bundle exec rubocop
-
-# Run all validation checks (tests, linting, security)
-bundle exec rake validate
-
-# Open interactive console with gem loaded
-bin/console
-# or
-bundle exec rake console
+`rake -T` lists the custom tasks. Two distinctions it does not make obvious:
 
-# Generate documentation
-bundle exec rake doc
-
-# Check documentation coverage
-bundle exec rake doc_stats
+```bash
+bundle exec rake     # tests WITH coverage (the default task)
+bundle exec rspec    # tests WITHOUT coverage
 ```
 
 ### Git Etiquette
 
 **IMPORTANT: Do not make a commit unless I explicitly ask you to.** Wait for explicit instruction before running `git commit`.
 
-When composing git commit messages, follow best-practices. However, do not mention yourself (claude) or list yourself as a co-author.
+When composing git commit messages, follow best-practices. Describe the change itself — do not narrate the assistant's process in the message body. Attribution trailers (`Co-Authored-By`, `Claude-Session`) are added when the session's attribution setting asks for them.
 
 This project uses a rebase flow and `main` as the mainline branch.
 
@@ -130,9 +106,7 @@ The codebase follows a domain-driven design with clear module boundaries:
 
 ### Entry Points
 
-- Main file: `lib/head_music.rb`
-- Module loading order is important and defined in the main file
-- Constants like GOLDEN_RATIO are defined at the top level
+Module loading order matters and is defined in `lib/head_music.rb`.
 
 ## Important Implementation Details
 
@@ -186,22 +160,6 @@ This project deliberately deprioritizes formal documentation in favor of clear,
 - Prefer delegation over inheritance
 - Always run `bundle exec rubocop -a` after editing ruby code
 
-## Common Development Tasks
-
-### Adding a New Musical Concept
-
-1. Create the class in the appropriate module
-2. Include `HeadMusic::Named` if it needs internationalization
-3. Add factory method `.get()` if appropriate
-4. Create corresponding spec file
-5. Add translations to locale files if using Named
-
-### Modifying Existing Classes
-
-1. Check for dependent classes that might be affected
-2. Run tests for the specific module: `bundle exec rspec spec/head_music/[module_name]`
-3. Ensure translations are updated if names change
-
 ## Reference Documents
 
 Domain reference materials live in `references/`.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (20.1.0)
+    head_music (21.1.0)
       activesupport (>= 7.0, < 10)
       humanize (>= 2, < 4)
       i18n (~> 1.8)

data/README.md

@@ -194,21 +194,7 @@ bundle exec rake doc
 
 ### Releasing a New Version
 
-1. Update the version number in `lib/head_music/version.rb`
-2. Commit the version change: `git commit -am "Bump version to X.Y.Z"`
-3. Push to main: `git push origin main`
-4. Release the gem:
-
-```bash
-bundle exec rake release
-```
-
-This will:
-- Build the gem
-- Create and push a git tag (e.g., `vX.Y.Z`)
-- Push the gem to RubyGems
-
-The git tag push also triggers a GitHub Actions workflow that creates a GitHub Release with auto-generated release notes.
+The release checklist lives in [`.claude/skills/release/SKILL.md`](.claude/skills/release/SKILL.md). Run `/release` in Claude Code, or follow it by hand. In short: move the Unreleased changelog entries under a dated heading, bump `lib/head_music/version.rb`, refresh `Gemfile.lock`, commit as `Release X.Y.Z`, and then `bundle exec rake release:source_control_push` tags the release. The tag push runs the release workflow, which publishes the gem to RubyGems and creates the GitHub Release.
 
 ## Contributing
 

data/Rakefile

@@ -67,4 +67,11 @@ namespace :style do
     File.write(path, snapshot.to_yaml)
     puts "Wrote #{snapshot.values.sum(&:size)} strings to #{path}"
   end
+
+  desc "Regenerate the pinned corpus grading (spec/fixtures/style/corpus_fitness.json)"
+  task :snapshot_corpus_fitness do
+    path = File.expand_path("spec/fixtures/style/corpus_fitness.json", __dir__)
+    sh "bundle exec ruby bin/guide_grade_corpus.rb #{path}"
+    puts "Wrote #{path}"
+  end
 end

data/bin/guide_grade_corpus.rb

@@ -4,15 +4,15 @@
 #
 #   bundle exec ruby bin/guide_grade_corpus.rb out.json
 #
-# Written to run UNMODIFIED on both sides of a grading change. At the merge-base
-# `assessable?` does not exist and the harmony guides raise on a solo voice, so
-# the one is asked for conditionally and the other is recorded as a value rather
-# than being allowed to stop the run. Everything else is common to both trees.
+# Written to run on both sides of a grading change: the corpus and the grading
+# live in spec/support/guide_grading.rb, and this script is only the file-writing
+# wrapper around them. `rake style:snapshot_corpus_fitness` writes the pinned
+# snapshot; this script exists for capturing a second one to diff against it.
 #
-# The invariant that sentence protects is that each column is the same
-# measurement made again -- not that the file is never edited. When a change
-# needs a seam this script does not yet have, the edit lands BEFORE both
-# captures and is proven a no-op by diffing a capture from either side of it.
+# The invariant is that each column is the same measurement made again -- not
+# that the file is never edited. When a change needs a seam this script does not
+# yet have, the edit lands BEFORE both captures and is proven a no-op by diffing
+# a capture from either side of it.
 #
 # Loading the fixture exercises means loading spec_helper, which starts
 # SimpleCov and rewrites coverage/.last_run.json. That file is restored on the
@@ -34,91 +34,13 @@ at_exit do
 end
 
 require "head_music"
-require "composition_context"
+require "flow_context"
 require "spec_helper"
 
-LADDER = %w[D4 F4 E4 G4 F4 A4 G4 F4].freeze
-REPEATED = Array.new(8, "E4").freeze
-CANTUS = %w[D4 F4 E4 D4 G4 F4 E4 D4].freeze
+rows = GuideGrading.rows
 
-def composition(key: "D dorian")
-  HeadMusic::Content::Composition.new(name: "corpus", key_signature: key)
-end
-
-def place(voice, pitches)
-  pitches.each_with_index { |pitch, bar| voice.place("#{bar + 1}:1", :whole, pitch) }
-  voice
-end
-
-# A voice alone in its composition: no companion, so the harmony guides have
-# nothing to be set against.
-def solo(pitches)
-  place(composition.add_voice(role: :counterpoint), pitches)
-end
-
-# A counterpoint voice with a companion, which may itself be empty.
-def accompanied(pitches, companion_pitches)
-  comp = composition
-  place(comp.add_voice(role: "Cantus Firmus"), companion_pitches)
-  place(comp.add_voice(role: :counterpoint), pitches)
-end
-
-def corpus
-  entries = []
-  (0..8).each { |n| entries << ["solo-ascending-#{n}", solo(LADDER.first(n))] }
-  (0..8).each { |n| entries << ["solo-repeated-#{n}", solo(REPEATED.first(n))] }
-  [0, 1, 2, 4, 8].each { |n| entries << ["against-empty-#{n}", accompanied(LADDER.first(n), [])] }
-  [0, 1, 2, 4, 8].each { |n| entries << ["against-cantus-#{n}", accompanied(LADDER.first(n), CANTUS)] }
-
-  %w[
-    fux_cantus_firmus_examples clendinning_cantus_firmus_examples
-    schoenberg_cantus_firmus_examples davis_and_lybbert_cantus_firmus_examples
-    fux_cantus_firmus_examples_with_errors fux_first_species_examples
-    clendinning_first_species_examples davis_and_lybbert_first_species_examples
-    doubled_octave_examples
-  ].each do |source|
-    Array(send(source)).each_with_index do |context, index|
-      context.composition.voices.each_with_index do |voice, position|
-        entries << ["#{source}-#{index}-v#{position}", voice]
-      end
-    end
-  end
-  entries
-end
-
-def grade(guide, voice)
-  # Through the guide, not GuideAssessment.new: a composite guide grades its
-  # members separately and refuses that constructor, and the rescue below would
-  # have recorded the refusal as a per-row error while the run still exited 0.
-  # Identical for every leaf guide -- Guides::Base.assess and Configured#assess
-  # are both GuideAssessment.new(self, voice) -- so this edit was made before
-  # either capture was taken and proven a byte-identical no-op on the before
-  # tree.
-  assessment = guide.assess(voice)
-  items = assessment.guide_item_assessments
-  {
-    fitness: assessment.fitness.round(12),
-    adherent: assessment.adherent?,
-    message_count: assessment.messages.length,
-    item_count: items.length,
-    assessable: assessment.assessable?,
-    failed_gates: items.select { |item| item.gate? && !item.adherent? }.map { |item| item.guideline.name.split("::").last }.sort
-  }
-rescue => error
-  {fitness: nil, adherent: nil, message_count: nil, item_count: nil, assessable: nil,
-   failed_gates: [], error: error.class.name}
-end
-
-rows = corpus.flat_map do |label, voice|
-  HeadMusic::Style::Guide::ALL.map do |guide|
-    {
-      corpus: label,
-      notes: voice.notes.length,
-      guide: HeadMusic::Style::Guide.key_for(guide)
-    }.merge(grade(guide, voice))
-  end
-end
-
-File.write(ARGV.fetch(0), JSON.pretty_generate(rows))
-warn "rows=#{rows.length} corpus=#{corpus.length} guides=#{HeadMusic::Style::Guide::ALL.length} " \
+# One row per line: valid JSON, but a third the size of a pretty-printed dump
+# and diffable a row at a time, which is how the snapshot is read.
+File.write(ARGV.fetch(0), "[\n#{rows.map { |row| JSON.generate(row) }.join(",\n")}\n]\n")
+warn "rows=#{rows.length} guides=#{HeadMusic::Style::Guide::ALL.length} " \
      "errors=#{rows.count { |row| row[:error] }}"

data/bin/guide_grade_table.rb

@@ -167,7 +167,7 @@ def composite_members(capture)
 end
 
 # Only assessable rows carry information. Every solo entry and every cantus
-# firmus fixture is a single-voice composition, so its harmony member gates out
+# firmus fixture is a single-voice flow, so its harmony member gates out
 # and the composite reads 0.000 by construction.
 def composite_rows(capture)
   members = composite_members(capture)

data/lib/head_music/analysis/harmonic_interval.rb

@@ -8,7 +8,7 @@ class HeadMusic::Analysis::HarmonicInterval
   def initialize(voice1, voice2, position)
     @voice1 = voice1
     @voice2 = voice2
-    @position = position.is_a?(String) ? HeadMusic::Content::Position.new(voice1.composition, position) : position
+    @position = position.is_a?(String) ? HeadMusic::Content::Position.new(voice1.flow, position) : position
   end
 
   def diatonic_interval

data/lib/head_music/content/bar.rb

@@ -1,28 +1,30 @@
 # A module for musical content
 module HeadMusic::Content; end
 
-# Representation of a bar in a composition
+# Representation of a bar in a flow
 # Encapsulates meter and key signature changes
 # and repeat structure (repeat barlines and volta brackets) as content semantics
 class HeadMusic::Content::Bar
-  attr_reader :composition, :ends_repeat_after_num_plays, :plays_on_passes, :key_signature, :meter
+  attr_reader :flow, :number, :ends_repeat_after_num_plays, :plays_on_passes
   attr_writer :starts_repeat
 
-  def initialize(composition, key_signature: nil, meter: nil)
-    @composition = composition
-    self.key_signature = key_signature
-    self.meter = meter
+  def initialize(flow, number: HeadMusic::Time::MusicalPosition::DEFAULT_FIRST_BAR)
+    @flow = flow
+    @number = number
     @starts_repeat = false
     @ends_repeat_after_num_plays = nil
     @plays_on_passes = nil
   end
 
-  def key_signature=(value)
-    @key_signature = value ? HeadMusic::Rudiment::KeySignature.get(value) : nil
+  # The key signature and meter a bar reports are the changes authored here,
+  # read from the flow's timeline rather than stored -- nil where nothing was
+  # authored, which is what a writer reads to decide whether to print one.
+  def key_signature
+    flow.timeline.key_signature_change_at(number)&.key_signature
   end
 
-  def meter=(value)
-    @meter = value ? HeadMusic::Rudiment::Meter.get(value) : nil
+  def meter
+    flow.timeline.meter_change_at(number)
   end
 
   def starts_repeat?
@@ -56,12 +58,11 @@ class HeadMusic::Content::Bar
   end
 
   # Sparse serialization: only non-default state, so a default bar is {}.
-  # KeySignature serializes via #name ("F♯ minor") because #to_s ("3 sharps")
-  # cannot be parsed back by KeySignature.get.
+  #
+  # Key and meter changes are not here: they belong to the flow's timeline, and
+  # a bar merely reports the ones authored in it.
   def to_h
     hash = {}
-    hash["key_signature"] = key_signature.name if key_signature
-    hash["meter"] = meter.to_s if meter
     hash["starts_repeat"] = true if starts_repeat?
     hash["ends_repeat_after_num_plays"] = ends_repeat_after_num_plays if ends_repeat?
     hash["plays_on_passes"] = plays_on_passes.dup if plays_on_passes