head_music 21.1.0 → 22.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eadecb642354dfc4c70cf00303a0c1c27513fdd38b13d8bc81fe9c8e7fd3214b
-  data.tar.gz: b534a1e194b0bd6ba4dae42433e92091812e434ec0fddb03c7617e47147207ab
+  metadata.gz: 4f716235926455127be636b1b1c2c575a4ce7f0f4b41f7952620dfda908a8671
+  data.tar.gz: 378c4749d7fbcc0ac7168f086cae549126d4fd8e648e5703d4311a2a9b63f5ad
 SHA512:
-  metadata.gz: aa22ebc311f8ebe62590e99f90f0d65d639b250626f9668520cd604e0f2fec4c1ea7af4d9b944a19585c52ea1b941906f12d2910888e0a4005a7f582936547ec
-  data.tar.gz: fde9ba8d894229bc349c861b24a0e56108f2a718526b67465c7b8631c9401a8d243196d4f632d1ebce890726c718b4371d2110fcc4e80eef39747d7ec1e610a1
+  metadata.gz: 433e4a30ce9a523d69e194b37b72f3cc5499c91d6e3605c1c901ed63ad9d2c308ae9c891876eb0cb9beef288450cc59287fbabb63e0c3115a160e8d111d032ad
+  data.tar.gz: 925aa64aabc77e319868ab18d71964bea6ee1aae5a02477a827283b9ce01c13eb1203b1d0ff87ae361f41c41bbc02965446acc77caa1f6a1c451fe227a718806

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

@@ -82,9 +82,10 @@ rubygems.org/gems/head_music/trusted_publishers, with repository
 
 - `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.
+  assume it passed.
+- `curl -s https://rubygems.org/api/v1/versions/head_music/latest.json`
+  reports the new version. `gem search -r` lags behind the API by minutes,
+  so do not read a stale result there as a failed publish.
 - `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

data/.github/workflows/ci.yml

@@ -57,6 +57,8 @@ jobs:
         bundle install
 
     - name: Run tests
+      env:
+        COVERAGE: ${{ matrix.coverage && 'true' || '' }}
       run: bundle exec rspec
 
     - name: Upload coverage to Codecov
@@ -99,8 +101,8 @@ jobs:
 
   # 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.
+  # actually compile. Only the specs that call the binary run here; the test
+  # job covers the rest.
   test-lilypond:
     name: test (with the lilypond toolchain)
     runs-on: ubuntu-latest
@@ -121,7 +123,7 @@ jobs:
         bundler-cache: true
 
     - name: Run tests
-      run: bundle exec rspec
+      run: bundle exec rspec spec/head_music/notation/lily_pond_round_trip_spec.rb spec/head_music/notation/lily_pond
 
   lint:
     runs-on: ubuntu-latest

data/CHANGELOG.md

@@ -7,6 +7,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [22.0.0] - 2026-09-24
+
+Four counterpoint stories, [Require the Species Rhythm](https://github.com/roberthead/head_music/tree/main/user-stories/done/require-the-species-rhythm.md), [Embellish Fifth Species Suspensions](https://github.com/roberthead/head_music/tree/main/user-stories/done/embellish-fifth-species-suspensions.md), [Grade Every Fux Fifth-Species Figure](https://github.com/roberthead/head_music/tree/main/user-stories/done/grade-every-fux-fifth-species-figure.md), and [Fifth Species Guide Improvements](https://github.com/roberthead/head_music/tree/main/user-stories/done/fifth-species-guide-improvements.md). Every species guide now insists on the rhythm its species teaches, fifth species accepts the decorated suspensions Fux allows and requires the mixture that defines it, and every two-voice fifth-species figure in Gradus is graded and pinned. Fux's lines are graded as evidence, not as an oracle: where one of them outruns a rule that every other source keeps, the mark stands and is recorded as his liberty. Two grades move, both in the direction the pedagogy says they should, and the count guidelines now grade the solo and cantus-firmus lines they had passed on nothing; everything else is additive, including ties across bar lines in ABC.
+
+Grading is also faster: the pinned corpus grades in about half the time, with no grade moving for it.
+
+**This is a major release**, because two public classes are removed. A consumer that names neither and stores no schema-3 documents upgrades by upgrading.
+
+**Migrating from 21.1.0**, in the order a consumer will hit them:
+
+1. **`Style::Guidelines::MixedRhythmicValues` is gone.** A custom guide that names it raises `NameError` on load. `MixSpeciesTextures` replaces it in `FifthSpeciesMelody` and judges runs of one texture rather than counting distinct durations, so it is a successor rather than a rename.
+
+2. **`Content::Flow.from_v3_h` is gone, as 21.0.0 announced.** A schema-3 document must be read with head_music 21.x and saved again before upgrading; `Flow.from_h` rejects one with an error saying so. Schema-4 documents are unaffected.
+
+3. **Some grades move.** The rule changes under Added and Changed regrade existing lines: the fourth- and fifth-species guides most, and `Diatonic`, `StepOutOfUnison`, `AlwaysMove`, and the count guidelines in places. Stored fitness from 21.x is not comparable for the guides they touch.
+
+4. **`Pitch#name` and `Spelling#name` return frozen strings.** Code that modifies the returned name in place raises `FrozenError`; `dup` it first.
+
+### Added
+
+- **`Style::Guidelines::MixSpeciesTextures`, strong and primary in `FifthSpeciesMelody` in place of `MixedRhythmicValues`.** Fifth species is the free mixture of the other four, and Salzer and Schachter allow "two, or at most, two-and-a-half measures of a single note value" (*Counterpoint in Composition*, pp. 101-102). Each bar from the voice's first to the one before its last is classified by the texture it shows: a note that fills the bar, halves, quarters and eighth pairs, or a ligature entered by tie. Every bar of a run of more than two bars in one texture is marked, configurable through `maximum_run:`. A bar that mixes textures is florid and an empty bar is left to the rest rules; either ends a run. It is strong although a proportion usually makes a guideline weak, because one texture running on decides whether a line is fifth species at all. All twelve Fux fifth-species counterpoints are adherent. Fux's fourth-species figure 73 falls from 0.929 to 0.827 on the `fifth_species` composite, its eight ligature bars marked in two runs on either side of an untied bar; his second- and third-species figures fall to 0.815 and 0.796, and every first-species counterpoint to between 0.59 and 0.63, and the species diagonal spec now asserts that every other species grades 0.85 or below there. In the pinned corpus, 175 rows move, all on `fifth_species_melody` and the `fifth_species` composite: every one-texture voice falls, including every cantus firmus, every first-species counterpoint, the solo and against-empty lines, and the cantus voices of the species fixtures; the triple-meter cantus counts too, since a dotted whole that fills its bar is the whole-note texture. Two three-bar solo lines rise on the melody guide and lose their one message on both guides, because two body bars cannot hold an over-long run, where the old rule marked any line with fewer than three durations. No other message or item count moves, and no harmony grade moves.
+
+- **`Style::Guidelines::PreferLongBeforeShort`, secondary and weak in `FifthSpeciesMelody`.** A bar that opens with two quarters and closes with a longer note that does not tie forward is marked: Salzer and Schachter call that note "a static point" that "blocks the flow from the two quarters rather than channeling it into the following measure" (*Counterpoint in Composition*, p. 103), and Fux marks the shape N.B. in figure 88 bar 5 and offers figure 89 as better. A longer note that ties over the bar line is exempt, as is a bar entered by a tie. It is weak because Fux calls the alternative better rather than calling his own line wrong. Figure 88a is the only voice marked and falls from 1.000 to 0.995 on `fifth_species_melody` and to 0.997 on the `fifth_species` composite. The new item adds one to the item count of every gated row of those two guides, 250 in the pinned corpus; 176 of them rise by at most 0.005 because the secondary tier's weight is shared among one more item, and 72 move in item count only.
+
+- **Every two-voice fifth-species figure of Gradus as a spec fixture.** Figures 83 through 88 in Mann's numbering join figure 82 in `spec/spec_helper.rb`: each of the six modes once with the counterpoint above the cantus firmus and once below, read from the scan and confirmed against the kern transcriptions in MarkGotham/species, except figure 87's upper counterpoint, which has no kern and is read from the scan alone. The kern drops the tie from bar 11 into bar 12 of figure 86a at a system break; the fixture follows the scan. `species_abc` takes an ABC key and draws the cantus firmus from `FUX_CANTUS_FIRMUS_ABC`, so a species fixture can sit on any of Fux's six cantus firmi. The pinned corpus gains 660 rows and moves none. Every new counterpoint clears both primary items of `FifthSpeciesHarmony` except figure 85b, whose suspension from bar 1 resolves as an eighth on beat 2 of bar 2 and has moved on by beat 3. No source but Fux sanctions that shape, so `EmbellishedSuspensionTreatment` keeps marking it, a spec context pins the mark, and the species diagonal spec excludes that one cell by name through a map of liberties rather than by loosening the comparison. It grades 0.916 on the `fifth_species` composite; the other eleven grade between 0.953 and 1.000.
+
+- **`Style::Guidelines::SustainAcrossBarlines`, primary in `FourthSpeciesMelody`.** A bar is sustained when the note sounding at its downbeat began before it, so a whole note placed on beat three and a half tied to a half count the same. A quarter of the middle bars may break the syncopation, as Fux allows where no ligature will fit; past that, every bar entered without a ligature is marked. It is judged over the voice's own bars rather than the cantus firmus's, so a solo line is held to it too. `OneToOneWithTies` stays beside it: that rule bounds how many notes sound against each cantus note, and a plain first-species line passed it, which is why a first-species line graded 0.988 on the fourth-species composite.
+
+- **`Style::Guidelines::EmbellishedSuspensionTreatment`, primary in `FifthSpeciesHarmony` in place of `SuspensionTreatment`.** Fifth species lets the space between a suspension and its resolution be decorated. The resolution is still the note sounding halfway through the bar, on its second strong beat: a descending step from the suspended pitch and consonant there, whether attacked on that beat or anticipated on beat two and held. That accepts all five shapes the fifth-species reference describes — the anticipated resolution, the anticipated resolution with an eighth-note lower neighbor, the escape tone, the consonant leap, and Fux's delayed resolution — and still marks an unprepared suspension, one left by leap, one resolving upward, one first resolving on beat four, one held through the bar, and an anticipation abandoned on beat three. What is attacked between the suspension and that beat is `FloridDissonanceTreatment`'s to judge, so a dissonant leapt-to quarter is marked once, not twice. The slot presupposes a suspension over a downbeat whose cantus note lasts to that beat; a cantus note attacked off the downbeat or gone before it, and a meter with no second strong beat, get the strict rule. Fourth species keeps `SuspensionTreatment` unchanged.
+
+- **Ties across bar lines in ABC.** `Notation::ABC.parse` now carries a tie over a bar line into one placement whose rhythmic value keeps the authored split, where it used to raise "Ties across barlines are not yet supported"; the tie carries its accidental across the line, so `^D2-|D2` is one D-sharp. A tied note is kept pending across a volta bracket as well. The writer does the inverse: a placement that sounds across a bar line is written as one note per bar, tied, so a flow of fourth-species ligatures writes back as valid ABC and re-parses to the same placements. In-bar tie chains still collapse to one multiplier on output.
+
+- **Fux's diminution species as spec fixtures.** `spec/spec_helper.rb` carries Mann's figures 33, 55, 73, and 82 — second, third, fourth, and fifth species above the D dorian cantus firmus — checked against the scan and against the kern transcriptions in MarkGotham/species, plus a constructed triple-meter third-species line labeled as such. They join the pinned corpus, and a new species diagonal spec asserts that every species composite and melody guide grades its own species' fixture at least as high as any other species' fixture.
+
+### Changed
+
+- **`Diatonic` accepts the accidentals the modes require.** Salzer and Schachter (*Counterpoint in Composition*, pp. 9-10 and 20) name four, and the guideline now exempts exactly those: a raised seventh that steps up to the tonic anywhere in the line, which subsumes the old exemption for a sharpened penultimate note; a raised sixth that steps up to a raised seventh; the lowered fourth in lydian; and the lowered sixth in dorian or lowered third in mixolydian, approached from above and left downward. Phrygian gets no B-flat. Every Fux fifth-species counterpoint now clears `Diatonic`: figure 82's B-flat in `d c _B G`, figure 86a's mid-line F-sharp, and the five lydian B-flats of 85a and 85b. The same exemption clears the descending B-flat of Fux's fourth-species figure 73 and two of the five B-flats in his third-species figure 55; the other three are not in descent and stay marked, as do the F-sharps of the cantus firmus written with chromatic notes added. In the pinned corpus, those six counterpoints rise under the 23 guides that carry `Diatonic`, 138 rows, by at most 0.002 on a species composite, where `Diatonic` is secondary; no row falls.
+
+- **`StepOutOfUnison` exempts the opening note and a unison tied over the bar line.** Salzer and Schachter permit a unison "if tied over or followed by stepwise motion" (*Counterpoint in Composition*, p. 106), and the opening unison belongs to the rules for beginnings (p. 40). The rule stays in every moving species, which is where they state it. Fux's figures 83 and 86b, whose opening unisons are left by leap, now clear it; the interior unisons left by leap in figures 82 (twice), 84a, 85a, and 86a keep their marks as his liberties, pinned by name in the spec. In the pinned corpus, 120 rows rise, ten voices under the twelve guides that carry the rule: those two counterpoints, the cantus firmus of figures 83, 86b, and 87a, of Fux's third-species figure, and of two first-species figures, each of which opens in unison with its counterpoint, and the two against-cantus lines. No row falls.
+
+- **`AlwaysMove` accepts the anticipated resolution.** A quarter on beat 2 that repeats as the beat-3 resolution of a suspension held from the previous bar, the shape Salzer and Schachter name "anticipation of tone of resolution" (*Counterpoint in Composition*, p. 104), is no longer marked as a repeated note, whether or not the resolution ties forward. A repeated half, a repeated quarter with no suspension before it, and a quarter approached from below stay marked, so figure 85b keeps its mark in bar 9. Fux's figures 86a, 87 upper, 87a, and 88b lose their one `AlwaysMove` mark and rise under every guide that grades a counterpoint with it, 56 rows in the pinned corpus, each one message fewer; nothing else moves.
+
+- **`NoteCountPerBar` judges the voice's own bars.** `OnePerBar`, `TwoPerBar`, `ThreePerBar`, and `FourPerBar` borrowed the companion voice's note list to decide which bars to inspect, so a voice with no companion passed on nothing, a bar was charged once per companion note when the companion was florid, and an empty bar's mark landed on the companion's note. They now judge the bars between the voice's own first and last notes, as `SustainAcrossBarlines` does, mark an empty bar as a span with no placements, and leave an empty voice to the minimum-notes gate. In the pinned corpus, 362 rows move, all under the first- through third-species guides: solo lines and lines against an empty companion are now marked; every cantus firmus graded on its own, whose companion voice is empty, is now marked by the second- and third-species count rules; the cantus voices of the species fixtures rise by a few thousandths where a florid companion had charged them once per note; and a counterpoint shorter than its cantus firmus is no longer charged for bars it never wrote. No harmony grade moves, and no counterpoint that runs the length of its cantus firmus moves.
+
+- **A first-species line now grades materially lower against fourth species.** Across the ten valid Fux first-species fixtures, `fourth_species_melody` falls from 0.986 to between 0.68 and 0.71 and the `fourth_species` composite from 0.988 to between 0.80 and 0.84, while Fux's own fourth-species line grades 0.999 on the melody guide. Second, third, triple-meter, and fifth species already discounted a first-species line by a quarter through their melody primaries and are unchanged. The harmony guides deliberately do not check rhythm; `SpeciesHarmony` records that the melody guide's primary tier is where the species' rhythm is required.
+
+- **Fux's fifth-species example now grades as fifth species.** Figure 82 rises from 0.819 to 0.937 on `fifth_species_harmony` and from 0.891 to 0.953 on the `fifth_species` composite, above his fourth-species line's 0.929 there, because its bar 9 suspension, resolved through an interposed consonant third, is no longer marked. No other corpus grade moves.
+
+- **`FloridDissonanceTreatment`'s strings no longer promise to prepare and resolve tied suspensions.** The guideline judges each note at its attack, so a held-over suspension never reached it and the branch that claimed to handle one was unreachable; the branch is deleted and the English and British sentences now end at "on a weak beat". No grade changes.
+
+- **Guide grading allocates about a quarter as many objects.** Positions compare field by field rather than through arrays; pitch and spelling names, a pitch's natural, a letter name's pitch class, and a diatonic interval's quality are memoized; pitch classes and chromatic intervals looked up by number skip name parsing; rhythmic unit names are indexed once rather than normalized on every parse; and `AvoidCrossingVoices` finds the predominant orientation once per assessment. Grading the pinned corpus falls from about 18.5 to 9.4 seconds, and no grade moves. `Pitch#name` and `Spelling#name` now return frozen strings.
+
+- **`Flow`, `Voice`, `Position`, and `Placement` inspect as one line.** Each shows its class and `to_s`, as in `#<HeadMusic::Content::Placement eighth F♯4 at 2:2:240>`. The default printed the whole composition, since every placement reaches its voice and every voice its flow: two melodic note pairs from a seven-note voice inspected to two megabytes, in irb, in failure messages, and in RSpec's generated example descriptions.
+
+### Removed
+
+- **`Content::Flow.from_v3_h` and `Content::Flow::V3HashDeserializer`,** as 21.0.0 announced. A schema-3 document is read with `Flow.from_v3_h` in head_music 21.x and saved again; `Flow.from_h` still rejects one with an error saying so.
+
+- **`Style::Guidelines::MixedRhythmicValues`.** It asked only for three distinct durations and placed one mark when a line had fewer, which is why Fux's fourth-species line graded within 0.024 of his fifth-species line on the `fifth_species` composite. `MixSpeciesTextures` replaces it; no other guide used it.
+
+### Fixed
+
+- **ABC repeat and volta tagging for a note that outlasts its bar.** The parser counted completed bars from where the last note started, so a note longer than its bar, or one now tied across the line, shifted every following repeat flag by a bar. Bars are counted from where the last note ends.
+
+- **`AvoidCrossingVoices` marks the bars that leave the predominant orientation.** It deduplicated the voices' orientations before counting them, so the orientation heard first always won, and a counterpoint that opened below the cantus firmus and then stayed above it had its in-order bars marked as the crossings. The most common orientation now wins, and a tie still goes to the one heard first. No row of the pinned corpus moves: every crossing voice in it opens in its predominant orientation.
+
 ## [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.

data/CLAUDE.md

@@ -10,16 +10,18 @@ HeadMusic is a Ruby gem for Western music theory. It provides a comprehensive to
 
 ### Essential Commands
 
-`rake -T` lists the custom tasks. Two distinctions it does not make obvious:
+`rake -T` lists the custom tasks.
 
 ```bash
-bundle exec rake     # tests WITH coverage (the default task)
-bundle exec rspec    # tests WITHOUT coverage
+bundle exec rake validate  # tests with coverage, linting, security audit, code quality
+bundle exec rake           # tests WITH coverage (the default task, same as `rake spec`)
+bundle exec rspec          # tests WITHOUT coverage, so a single file can run on its own
+bundle exec rake coverage  # opens the last coverage report
 ```
 
 ### Git Etiquette
 
-**IMPORTANT: Do not make a commit unless I explicitly ask you to.** Wait for explicit instruction before running `git commit`.
+Commit when your judgment says the work is ready: a coherent, tested change, with one cause per commit where the work calls for it. You do not need to wait to be asked. Pushing, merging, and rewriting published history still wait for my go-ahead.
 
 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.
 
@@ -39,7 +41,7 @@ Do not use an assignment inside a condition.
 
 ### Testing
 
-Tests are written in RSpec and located in the `/spec` directory, mirroring the `/lib` structure. The project requires 90% code coverage minimum.
+Tests are written in RSpec and located in the `/spec` directory, mirroring the `/lib` structure. The project requires 90% code coverage minimum. Coverage is opt-in: `rake spec` sets `COVERAGE=true`, and `spec_helper.rb` starts SimpleCov only then.
 
 ## Architecture
 

data/Gemfile.lock

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

data/Rakefile

@@ -2,7 +2,8 @@ require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "standard/rake"
 
-RSpec::Core::RakeTask.new(:spec)
+# The block runs when the task does, just before rspec is launched.
+RSpec::Core::RakeTask.new(:spec) { ENV["COVERAGE"] = "true" }
 
 begin
   require "yard"
@@ -71,7 +72,7 @@ namespace :style do
   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}"
+    sh({"COVERAGE" => nil}, "bundle exec ruby bin/guide_grade_corpus.rb #{path}")
     puts "Wrote #{path}"
   end
 end

data/bin/guide_grade_corpus.rb

@@ -13,26 +13,12 @@
 # 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
-# way out, so a later `bundle exec rake` measures against the baseline it had.
 
 require "json"
 
 ROOT = File.expand_path("..", __dir__)
 $LOAD_PATH.unshift File.join(ROOT, "lib"), File.join(ROOT, "spec")
 
-COVERAGE_BASELINE = File.join(ROOT, "coverage", ".last_run.json")
-SAVED_BASELINE = File.exist?(COVERAGE_BASELINE) ? File.read(COVERAGE_BASELINE) : nil
-at_exit do
-  if SAVED_BASELINE
-    File.write(COVERAGE_BASELINE, SAVED_BASELINE)
-  elsif File.exist?(COVERAGE_BASELINE)
-    File.delete(COVERAGE_BASELINE)
-  end
-end
-
 require "head_music"
 require "flow_context"
 require "spec_helper"

data/lib/head_music/analysis/circle.rb

@@ -44,14 +44,7 @@ class HeadMusic::Analysis::Circle < HeadMusic::Analysis::IntervalCycle
   end
 
   def pitches_down
-    @pitches_down ||= [starting_pitch].tap do |list|
-      loop do
-        next_pitch = folded_down(list.last)
-        break if next_pitch.pitch_class == starting_pitch.pitch_class
-
-        list << next_pitch
-      end
-    end
+    @pitches_down ||= cycle_of_pitches { |pitch| folded_down(pitch) }
   end
 
   private

data/lib/head_music/analysis/diatonic_interval.rb

@@ -89,7 +89,7 @@ class HeadMusic::Analysis::DiatonicInterval
   end
 
   def quality
-    HeadMusic::Rudiment::Quality.get(quality_name)
+    @quality ||= HeadMusic::Rudiment::Quality.get(quality_name)
   end
 
   def inversion

data/lib/head_music/analysis/interval_cycle.rb

@@ -39,9 +39,14 @@ class HeadMusic::Analysis::IntervalCycle
   protected
 
   def pitches_up
-    @pitches_up ||= [starting_pitch].tap do |list|
+    @pitches_up ||= cycle_of_pitches { |pitch| folded_up(pitch) }
+  end
+
+  # Steps from the starting pitch until the cycle returns to its pitch class.
+  def cycle_of_pitches
+    [starting_pitch].tap do |list|
       loop do
-        next_pitch = folded_up(list.last)
+        next_pitch = yield(list.last)
         break if next_pitch.pitch_class == starting_pitch.pitch_class
 
         list << next_pitch

data/lib/head_music/analysis/motion.rb

@@ -24,20 +24,15 @@ class HeadMusic::Analysis::Motion
   end
 
   def parallel?
-    upper_melodic_interval.moving? &&
-      upper_melodic_interval.direction == lower_melodic_interval.direction &&
-      upper_melodic_interval.steps == lower_melodic_interval.steps
+    upper_melodic_interval.moving? && same_direction? && same_steps?
   end
 
   def similar?
-    upper_melodic_interval.direction == lower_melodic_interval.direction &&
-      upper_melodic_interval.steps != lower_melodic_interval.steps
+    same_direction? && !same_steps?
   end
 
   def contrary?
-    upper_melodic_interval.moving? &&
-      lower_melodic_interval.moving? &&
-      upper_melodic_interval.direction != lower_melodic_interval.direction
+    upper_melodic_interval.moving? && lower_melodic_interval.moving? && !same_direction?
   end
 
   def notes
@@ -51,19 +46,27 @@ class HeadMusic::Analysis::Motion
   end
 
   def to_s
-    return "repetition of a #{second_harmonic_interval}" unless contrapuntal_motion != :repetition
+    return "repetition of a #{second_harmonic_interval}" if contrapuntal_motion == :repetition
 
     "#{contrapuntal_motion} motion from a #{first_harmonic_interval} to a #{second_harmonic_interval}"
   end
 
   private
 
+  def same_direction?
+    upper_melodic_interval.direction == lower_melodic_interval.direction
+  end
+
+  def same_steps?
+    upper_melodic_interval.steps == lower_melodic_interval.steps
+  end
+
   def upper_melodic_interval
-    HeadMusic::Analysis::MelodicInterval.new(upper_notes.first, upper_notes.last)
+    @upper_melodic_interval ||= HeadMusic::Analysis::MelodicInterval.new(*upper_notes)
   end
 
   def lower_melodic_interval
-    HeadMusic::Analysis::MelodicInterval.new(lower_notes.first, lower_notes.last)
+    @lower_melodic_interval ||= HeadMusic::Analysis::MelodicInterval.new(*lower_notes)
   end
 
   def upper_notes

data/lib/head_music/analysis/sonority.rb

@@ -37,25 +37,15 @@ class HeadMusic::Analysis::Sonority
   # @param inversion [Integer] the inversion number (default: 0 for root position)
   # @return [Sonority, nil] the sonority object, or nil if identifier not found
   def self.get(identifier, root: DEFAULT_ROOT, inversion: 0)
-    identifier = identifier.to_sym
-    return nil unless SONORITIES.key?(identifier)
+    interval_shorthands = SONORITIES[identifier.to_sym]
+    return nil unless interval_shorthands
 
     root_pitch = HeadMusic::Rudiment::Pitch.get(root)
-    interval_shorthands = SONORITIES[identifier]
-
-    # Build pitches: root + intervals above root
     pitches = [root_pitch] + interval_shorthands.map do |shorthand|
-      interval = HeadMusic::Analysis::DiatonicInterval.get(shorthand)
-      interval.above(root_pitch)
+      HeadMusic::Analysis::DiatonicInterval.get(shorthand).above(root_pitch)
     end
-
     pitch_collection = HeadMusic::Analysis::PitchCollection.new(pitches)
-
-    # Apply inversions if requested
-    inversion.times do
-      pitch_collection = pitch_collection.invert
-    end
-
+    inversion.times { pitch_collection = pitch_collection.invert }
     new(pitch_collection)
   end
 
@@ -83,28 +73,22 @@ class HeadMusic::Analysis::Sonority
   def identifier
     return @identifier if defined?(@identifier)
 
-    @identifier = SONORITIES.keys.detect do |key|
-      inversions.map do |inversion|
-        inversion.diatonic_intervals_above_bass_pitch.map(&:shorthand)
-      end.include?(SONORITIES[key])
-    end
+    @identifier = SONORITIES.keys.detect { |key| inversion_shorthands.include?(SONORITIES[key]) }
   end
 
   def inversion
-    @inversion ||= inversions.index do |inversion|
-      SONORITIES[identifier] == inversion.diatonic_intervals_above_bass_pitch.map(&:shorthand)
-    end
+    @inversion ||= inversion_shorthands.index(SONORITIES[identifier])
   end
 
   def inversions
-    @inversions ||= begin
-      inversion = reduction
-      inversions = []
-      inversion.pitches.length.times do |_i|
-        inversions << inversion
-        inversion = inversion.uninvert
-      end
-      inversions
+    @inversions ||= reduction.pitches.each_with_object([]) do |_pitch, list|
+      list << (list.last&.uninvert || reduction)
+    end
+  end
+
+  def inversion_shorthands
+    @inversion_shorthands ||= inversions.map do |inversion|
+      inversion.diatonic_intervals_above_bass_pitch.map(&:shorthand)
     end
   end
 

data/lib/head_music/content/credits.rb

@@ -5,6 +5,7 @@ module HeadMusic::Content; end
 # single place the level constraint is enforced.
 class HeadMusic::Content::Credits
   include Enumerable
+  include HeadMusic::ValueEquality
 
   LEVELS = HeadMusic::Content::Role::LEVELS
 
@@ -14,6 +15,8 @@ class HeadMusic::Content::Credits
 
   attr_reader :level, :credits
 
+  value_equality :level, :credits
+
   def initialize(level, credits = [])
     @level = level&.to_sym
     raise ArgumentError, "unknown credit level: #{level.inspect}" unless LEVELS.include?(@level)
@@ -51,15 +54,6 @@ class HeadMusic::Content::Credits
     credits.map(&:to_h)
   end
 
-  def ==(other)
-    other.is_a?(self.class) && level == other.level && credits == other.credits
-  end
-  alias_method :eql?, :==
-
-  def hash
-    [self.class, level, credits].hash
-  end
-
   private
 
   def ensure_credit(credit)

data/lib/head_music/content/flow/hash_deserializer.rb

@@ -9,11 +9,11 @@ class HeadMusic::Content::Flow
 
     private
 
-    # A v3 document is told where 20.1.0 still reads it, rather than merely
-    # rejected, because that reader still ships.
+    # No recipe migrates v3 in place, so a v3 document is told which release
+    # still reads it rather than merely rejected.
     def unsupported_version_message(version)
       message = super
-      message += "; read it with Flow.from_v3_h, which is retained in 21.x and removed in 22.0.0" if version == 3
+      message += "; read it with Flow.from_v3_h in head_music 21.x and save it again" if version == 3
       message
     end
 

data/lib/head_music/content/flow.rb

@@ -23,12 +23,6 @@ class HeadMusic::Content::Flow
     HashDeserializer.new(hash).flow
   end
 
-  # Retained read-only through 21.x so that persisted v3 data can be migrated
-  # by reading and re-saving. Removed in 22.0.0.
-  def self.from_v3_h(hash)
-    V3HashDeserializer.new(hash).flow
-  end
-
   def self.from_json(json)
     from_h(JSON.parse(json))
   end
@@ -145,7 +139,13 @@ class HeadMusic::Content::Flow
   end
 
   def to_s
-    "#{name} — #{voices.count} #{(voices.count == 1) ? "voice" : "voices"}"
+    "#{name} — #{voices.count} #{"voice".pluralize(voices.count)}"
+  end
+
+  # The default would print the whole composition, since every placement
+  # reaches its voice and every voice its flow.
+  def inspect
+    "#<#{self.class.name} #{self}>"
   end
 
   def to_abc(**options)

data/lib/head_music/content/layout.rb

@@ -18,13 +18,18 @@ class HeadMusic::Content::Layout
     hash = hash.transform_keys(&:to_s)
     {
       kind: (hash["kind"] || :custom).to_sym,
-      flows: hash["flows"] && Array(hash["flows"]).map { |index| project.flows[index] },
-      players: hash["players"] && Array(hash["players"]).map { |index| project.players[index] },
+      flows: members_at(hash["flows"], project.flows),
+      players: members_at(hash["players"], project.players),
       concert_pitch: hash.fetch("concert_pitch", true),
       title_override: hash["title_override"]
     }
   end
 
+  def self.members_at(indexes, collection)
+    indexes && Array(indexes).map { |index| collection[index] }
+  end
+  private_class_method :members_at
+
   def initialize(project:, kind: :custom, flows: nil, players: nil, concert_pitch: true, title_override: nil)
     ensure_known_kind!(kind)
 
@@ -68,11 +73,12 @@ class HeadMusic::Content::Layout
     Realization.new(self, flow).flow
   end
 
+  # A selection holds only the project's players, never nil, so a part with no
+  # player is kept only when nothing is selected.
+  #
   # @api private for Layout::Realization
   def selects?(part)
-    return true if selected_players.nil?
-
-    !part.player.nil? && selected_players.include?(part.player)
+    selected_players.nil? || selected_players.include?(part.player)
   end
 
   # Which of the flow's parts survive the selection, by index, in the order they
@@ -95,9 +101,9 @@ class HeadMusic::Content::Layout
   # rendered; each tune carries its own T:.
   def to_abc
     ensure_something_to_render!
-    rendered_flows.each_with_index
-      .map { |flow, index| HeadMusic::Notation::ABC.render(realize(flow), reference_number: index + 1, transposed: transposed?) }
-      .join("\n")
+    rendered_flows.map.with_index(1) do |flow, number|
+      HeadMusic::Notation::ABC.render(realize(flow), reference_number: number, transposed: transposed?)
+    end.join("\n")
   end
 
   # A single flow renders exactly as the flow would on its own; several render
@@ -105,15 +111,16 @@ class HeadMusic::Content::Layout
   def to_lilypond
     ensure_something_to_render!
     realized = rendered_flows.map { |flow| realize(flow) }
-    return HeadMusic::Notation::LilyPond.render(realized.first, transposed: transposed?, arranger: arranger) if realized.one?
+    return HeadMusic::Notation::LilyPond.render(realized.first, **rendering_options) if realized.one?
 
-    HeadMusic::Notation::LilyPond::BookWriter.new(realized, title: title, transposed: transposed?, arranger: arranger).to_s
+    HeadMusic::Notation::LilyPond::BookWriter.new(realized, title: title, **rendering_options).to_s
   end
 
   def to_musicxml
-    if rendered_flows.length > 1
+    count = rendered_flows.length
+    if count > 1
       raise HeadMusic::Notation::RenderError,
-        "MusicXML holds one flow per document and this layout renders #{rendered_flows.length}; use #to_musicxml_documents"
+        "MusicXML holds one flow per document and this layout renders #{count}; use #to_musicxml_documents"
     end
 
     to_musicxml_documents.first
@@ -121,8 +128,8 @@ class HeadMusic::Content::Layout
 
   def to_musicxml_documents
     ensure_something_to_render!
-    rendered_flows.each_with_index.map do |flow, index|
-      HeadMusic::Notation::MusicXML.render(realize(flow), **musicxml_options(index))
+    rendered_flows.map.with_index(1) do |flow, number|
+      HeadMusic::Notation::MusicXML.render(realize(flow), **musicxml_options(number))
     end
   end
 
@@ -138,7 +145,7 @@ class HeadMusic::Content::Layout
   end
 
   def to_s
-    "#{title} — #{kind} layout of #{rendered_flows.length} #{(rendered_flows.length == 1) ? "flow" : "flows"}"
+    "#{title} — #{kind} layout of #{rendered_flows.length} #{"flow".pluralize(rendered_flows.length)}"
   end
 
   private
@@ -167,10 +174,14 @@ class HeadMusic::Content::Layout
 
   # A document standing alone names only itself, which is what keeps a one-flow
   # layout byte-identical to the flow's own output.
-  def musicxml_options(index)
-    return {transposed: transposed?, arranger: arranger} if single_flow?
+  def musicxml_options(movement_number)
+    return rendering_options if single_flow?
+
+    rendering_options.merge(work_title: title, movement_number: movement_number)
+  end
 
-    {work_title: title, movement_number: index + 1, transposed: transposed?, arranger: arranger}
+  def rendering_options
+    {transposed: transposed?, arranger: arranger}
   end
 
   # The project's arrangers, joined as the composer is: this version's credit,
@@ -187,8 +198,8 @@ class HeadMusic::Content::Layout
   end
 
   def shared_work_title
-    works = flows.map(&:work)
-    works.first&.title if works.uniq.length == 1
+    works = flows.map(&:work).uniq
+    works.first&.title if works.size == 1
   end
 
   # Positions, not objects: a player and a flow are identified in a document

data/lib/head_music/content/part.rb

@@ -81,7 +81,7 @@ class HeadMusic::Content::Part
   end
 
   def to_s
-    [player&.name, "#{voices.length} #{(voices.length == 1) ? "voice" : "voices"}"].compact.join(": ")
+    [player&.name, "#{voices.length} #{"voice".pluralize(voices.length)}"].compact.join(": ")
   end
 
   # Sparse: a part with no instrument and no authored staves serializes as its

data/lib/head_music/content/placement.rb

@@ -119,6 +119,10 @@ class HeadMusic::Content::Placement
     "#{rhythmic_value} #{sounds.any? ? sounds.map { |sound| sound_label(sound) }.join(" ") : "rest"} at #{position}"
   end
 
+  def inspect
+    "#<#{self.class.name} #{self}>"
+  end
+
   def to_h
     hash = {
       "position" => position.to_s,