head_music 20.0.0 → 21.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8a5d592c5994e59585e09db272d554d2aefcef0f337287ee0fd0206cbab498c
-  data.tar.gz: '0964c0d8e7ec6a753886ab34131705daacb51eefffc79f48d281ca6663099a4d'
+  metadata.gz: 3adeb7e3fa4f5422977916729f285e9ebb50309409927b25b284dbbb35d2932d
+  data.tar.gz: 78f4b8b6922142b56e185cc23da551576ba3ffd375d51eb6aa34f3382e30530f
 SHA512:
-  metadata.gz: dafb4e6534d8985a4563a650e141f61d652b40a76e7adf2d3ce7d8820ce5f41038dc1754f893b18756a2f30192813b8e752899656b6abab5bc5dd073a732abad
-  data.tar.gz: cdd300bd23ca8bbe011f7712385d7b7d80cebb99eae61281bc24049c01f535069116eff46a46fe296acf0c846f3a7e4a36d59562d5c03cb29a4ed4c7d5930ede
+  metadata.gz: 444f66354a57746f2c9acf747462bf3f2396f76b8b9c7fe16d4c2bc93020bbe178349f437d7135141e587ffb9fef09c57bdf6a9145159b47a88af908960b608b
+  data.tar.gz: 4c38611fa5aea3b2530310dc33644ab29af9c81c523eb37e39fe94298d79c71ee982791e1278c449cd4d91c99623e21f1a2f3c9f4882e648c8b1783f6ff94a7c

data/.github/workflows/ci.yml

@@ -6,14 +6,39 @@ on:
   pull_request:
     branches: [ main ]
 
+permissions:
+  contents: read
+
+# A rebase flow means force-pushes are routine; without this, each one leaves
+# the superseded run burning minutes alongside its replacement.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   test:
+    name: test (ruby ${{ matrix.ruby-version }}, activesupport ${{ matrix.activesupport-version || 'latest' }})
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ['3.3', '3.4']
-        activesupport-version: ['7.2', '8.0']
+        # The corners of the supported range rather than a full cross product.
+        # An empty activesupport-version installs from the lockfile, covering
+        # the newest release the gemspec allows; ActiveSupport 7.2 is not
+        # paired with Ruby 4.0, which it predates.
+        include:
+          - ruby-version: '3.3'
+            activesupport-version: '7.2'
+          - ruby-version: '3.3'
+            activesupport-version: ''
+            coverage: true
+          - ruby-version: '3.4'
+            activesupport-version: '7.2'
+          - ruby-version: '3.4'
+            activesupport-version: '8.0'
+          - ruby-version: '4.0'
+            activesupport-version: ''
 
     steps:
     - uses: actions/checkout@v7
@@ -24,31 +49,90 @@ jobs:
         ruby-version: ${{ matrix.ruby-version }}
         bundler-cache: false
 
-    - name: Install dependencies with ActiveSupport ${{ matrix.activesupport-version }}
+    - name: Install dependencies with ActiveSupport ${{ matrix.activesupport-version || 'latest' }}
+      env:
+        ACTIVESUPPORT_VERSION: ${{ matrix.activesupport-version }}
       run: |
         bundle config set --local path vendor/bundle
-        ACTIVESUPPORT_VERSION="${{ matrix.activesupport-version }}" bundle install
+        bundle install
 
     - name: Run tests
       run: bundle exec rspec
 
     - name: Upload coverage to Codecov
-      if: matrix.ruby-version == '3.3' && matrix.activesupport-version == '8.0'
+      if: matrix.coverage
       uses: codecov/codecov-action@v7
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
         fail_ci_if_error: false
         verbose: true
 
+  # Months of warning about upcoming Ruby releases, without a red check that
+  # blocks a merge.
+  test-ruby-head:
+    name: test (ruby-head, advisory)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    continue-on-error: true
+    env:
+      # Bundler otherwise switches to the lockfile's BUNDLED WITH, and 2.7.2
+      # raises "uninitialized constant Pathname::SEPARATOR_PAT" on a Ruby this
+      # new. A bundler bug is not the breakage this job exists to find.
+      BUNDLE_VERSION: system
+    steps:
+    - uses: actions/checkout@v7
+
+    - name: Set up Ruby head
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: head
+        bundler: latest
+        bundler-cache: false
+
+    - name: Install dependencies
+      run: |
+        bundle config set --local path vendor/bundle
+        bundle install
+
+    - name: Run tests
+      run: bundle exec rspec
+
+  # The LilyPond specs treat the real binary as an oracle and skip when none is
+  # installed, so without this job nothing proves the rendered documents
+  # actually compile. Runs the whole suite because SimpleCov's minimum applies
+  # to any rspec invocation.
+  test-lilypond:
+    name: test (with the lilypond toolchain)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+    - uses: actions/checkout@v7
+
+    - name: Install LilyPond
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y lilypond
+        lilypond --version
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: .ruby-version
+        bundler-cache: true
+
+    - name: Run tests
+      run: bundle exec rspec
+
   lint:
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
     - uses: actions/checkout@v7
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.3.0'
+        ruby-version: .ruby-version
         bundler-cache: true
 
     - name: Run RuboCop
@@ -56,13 +140,14 @@ jobs:
 
   build:
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
     - uses: actions/checkout@v7
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.3.0'
+        ruby-version: .ruby-version
         bundler-cache: true
 
     - name: Build gem
@@ -71,4 +156,4 @@ jobs:
     - name: Check gem
       run: |
         gem install *.gem
-        gem specification *.gem
+        gem specification *.gem

data/.github/workflows/release.yml

@@ -8,6 +8,7 @@ on:
 jobs:
   release:
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     permissions:
       contents: write
       id-token: write
@@ -18,7 +19,7 @@ jobs:
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.3.0'
+        ruby-version: .ruby-version
         bundler-cache: true
 
     - name: Run tests
@@ -38,12 +39,12 @@ jobs:
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+    # Trusted publishing: RubyGems exchanges this job's OIDC token for a
+    # 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.
+    - name: Configure RubyGems credentials
+      uses: rubygems/configure-rubygems-credentials@v2
+
     - name: Publish to RubyGems
-      run: |
-        mkdir -p $HOME/.gem
-        touch $HOME/.gem/credentials
-        chmod 0600 $HOME/.gem/credentials
-        printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-        gem push *.gem
-      env:
-        GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+      run: gem push *.gem

data/.github/workflows/security.yml

@@ -10,9 +10,17 @@ on:
     - cron: '0 9 * * *'
   workflow_dispatch:
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   security:
     runs-on: ubuntu-latest
+    timeout-minutes: 5
 
     steps:
     - uses: actions/checkout@v7
@@ -20,14 +28,8 @@ jobs:
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.3.0'
+        ruby-version: .ruby-version
         bundler-cache: true
 
-    - name: Install bundler-audit
-      run: gem install bundler-audit
-
     - name: Run bundler-audit
-      run: bundle-audit check --update
-
-    - name: Run RuboCop Security
-      run: bundle exec rubocop --only Security
+      run: bundle exec bundle-audit check --update

data/.rubocop.yml

@@ -15,6 +15,14 @@ AllCops:
     - vendor/**/*
   TargetRubyVersion: 3.3.0
 
+# Off in standard's config, so the lint job missed them; the security
+# workflow's "--only Security" pass was the only thing covering them.
+Security/IoMethods:
+  Enabled: true
+
+Security/MarshalLoad:
+  Enabled: true
+
 RSpec:
   Enabled: true
 

data/CHANGELOG.md

@@ -5,6 +5,119 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [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.
+
+### Added
+
+- **LilyPond import.** `HeadMusic::Notation::LilyPond.parse(string)` reads a LilyPond document, or a bare music expression, into a `Content::Composition`: absolute and `\relative` pitches with `is`/`es` accidentals and Dutch contractions, durations with dots and carry-over, rests and whole-bar rests, chords, intra-bar ties, `\key`, `\time` (including mid-piece changes), `\clef`, bar checks, `\header` title and composer, and `\new Staff` / `\new Voice` contexts with `instrumentName` as the voice role. Everything the LilyPond writer emits reads back, so `parse(render(composition))` reproduces the music. `\version`, `\layout`, and `\midi` blocks are skipped whole, as are the header fields the reader does not use, so the Scheme in an everyday engraving preamble costs nothing. A bar-check mismatch raises `LilyPond::ParseError`; constructs outside the subset raise `LilyPond::UnsupportedFeatureError` rather than being skipped.
+- `HeadMusic::Notation::DottedDuration.rhythmic_value_for(fraction)`, the inverse of `dotted_unit_fraction`, shared by the ABC and LilyPond readers.
+
+### Changed
+
+- **Placing a note no longer costs time linear in the voice's length.** `Content::Voice#place` scanned its placements from the front twice — once for a placement already at the position, once for the insertion point — so filling a long voice was quadratic in its length. Both are now binary searches over the position order the list already keeps. Reading a 28KB LilyPond score went from 76 seconds to under 9; the remaining time is in `Content::Position` arithmetic rather than here.
+
 ## [20.0.0] - 2026-08-30
 
 The [style assessment model](https://github.com/roberthead/head_music/tree/main/user-stories/epics/style-assessment-model.md) epic, released together. Five stories reshaped how a guide is declared, how it grades, what it says, and what a consumer asks for — so the breaking changes below are one migration rather than five. Two notation stories ride along: LilyPond export, and note values named in each reader's own language.
@@ -716,7 +829,9 @@ 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.0.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
 [18.0.0]: https://github.com/roberthead/head_music/compare/v17.5.0...v18.0.0
@@ -764,4 +879,4 @@ For changes in versions prior to 0.28.0, please refer to the git history.
 [2.0.0]: https://github.com/roberthead/head_music/compare/v1.0.0...v2.0.0
 [1.0.0]: https://github.com/roberthead/head_music/compare/v0.29.0...v1.0.0
 [0.29.0]: https://github.com/roberthead/head_music/compare/v0.28.0...v0.29.0
-[0.28.0]: https://github.com/roberthead/head_music/releases/tag/v0.28.0
+[0.28.0]: https://github.com/roberthead/head_music/releases/tag/v0.28.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

@@ -5,10 +5,11 @@ ruby ">= 3.3.0"
 # Specify your gem's dependencies in head_music.gemspec
 gemspec
 
-# Allow CI to test against specific ActiveSupport versions
-if ENV["ACTIVESUPPORT_VERSION"]
-  gem "activesupport", "~> #{ENV["ACTIVESUPPORT_VERSION"]}.0"
-end
+# Allow CI to test against specific ActiveSupport versions. An unset or empty
+# value leaves the gemspec range alone -- empty is truthy in Ruby, so a matrix
+# cell that sets the key to "" would otherwise resolve against "~> .0".
+activesupport_version = ENV["ACTIVESUPPORT_VERSION"].to_s
+gem "activesupport", "~> #{activesupport_version}.0" unless activesupport_version.empty?
 
 gem "standard", require: false
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (20.0.0)
+    head_music (21.0.0)
       activesupport (>= 7.0, < 10)
       humanize (>= 2, < 4)
       i18n (~> 1.8)
@@ -216,7 +216,7 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
-  bundler-audit
+  bundler-audit (~> 0.9, >= 0)
   head_music!
   kramdown
   rake (~> 13.0)
@@ -228,10 +228,10 @@ DEPENDENCIES
   rubycritic
   simplecov (< 1.1)
   standard
-  yard
+  yard (~> 0.9, >= 0)
 
 RUBY VERSION
-   ruby 3.3.0p0
+  ruby 3.3.0p0
 
 BUNDLED WITH
-   2.4.12
+  4.0.20

data/README.md

@@ -14,6 +14,7 @@ The **head_music** Ruby gem provides a toolkit for working with Western music th
 - **Style Analysis**: Rules for species counterpoint and voice leading
 - **Internationalization**: Support for multiple languages (English, French, German, Italian, Russian, Spanish)
 - **Instrument Modeling**: Extensive database of musical instruments with ranges and properties
+- **Notation Formats**: Read ABC and LilyPond into compositions; write compositions as ABC, LilyPond, and MusicXML
 
 ## Installation
 
@@ -50,8 +51,21 @@ puts scale.pitches.map(&:to_s)  # => ["C4", "D4", "E4", "F4", "G4", "A4", "B4"]
 pitches = %w[C4 E4 G4].map { |p| HeadMusic::Rudiment::Pitch.get(p) }
 chord = HeadMusic::Analysis::PitchSet.new(pitches)
 puts chord.major_triad?  # => true
+
+# Import a LilyPond excerpt as a composition
+composition = HeadMusic::Notation::LilyPond.parse(<<~'LILY')
+  \relative c' {
+    \key g \major
+    \time 4/4
+    g8 a b c d c b g |
+  }
+LILY
+puts composition.voices.first.pitches.map(&:to_s)  # => ["G3", "A3", "B3", "C4", "D4", "C4", "B3", "G3"]
+puts composition.to_lilypond                        # => a complete LilyPond document
 ```
 
+The LilyPond reader covers absolute and `\relative` pitches, durations and dots, rests and whole-bar rests, chords, intra-bar ties, `\key`, `\time`, `\clef`, bar checks, `\header` title and composer, and `\new Staff` / `\new Voice` contexts. Constructs outside that subset (tuplets, lyrics, variables, articulations, and so on) raise an `UnsupportedFeatureError` rather than being skipped.
+
 ## Style Analysis
 
 Look up a style guide by key and analyze a voice against it. `Style::Guide.get` returns `nil` for an

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