head_music 21.0.0 → 22.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3adeb7e3fa4f5422977916729f285e9ebb50309409927b25b284dbbb35d2932d
-  data.tar.gz: 78f4b8b6922142b56e185cc23da551576ba3ffd375d51eb6aa34f3382e30530f
+  metadata.gz: 4f716235926455127be636b1b1c2c575a4ce7f0f4b41f7952620dfda908a8671
+  data.tar.gz: 378c4749d7fbcc0ac7168f086cae549126d4fd8e648e5703d4311a2a9b63f5ad
 SHA512:
-  metadata.gz: 444f66354a57746f2c9acf747462bf3f2396f76b8b9c7fe16d4c2bc93020bbe178349f437d7135141e587ffb9fef09c57bdf6a9145159b47a88af908960b608b
-  data.tar.gz: 4c38611fa5aea3b2530310dc33644ab29af9c81c523eb37e39fe94298d79c71ee982791e1278c449cd4d91c99623e21f1a2f3c9f4882e648c8b1783f6ff94a7c
+  metadata.gz: 433e4a30ce9a523d69e194b37b72f3cc5499c91d6e3605c1c901ed63ad9d2c308ae9c891876eb0cb9beef288450cc59287fbabb63e0c3115a160e8d111d032ad
+  data.tar.gz: 925aa64aabc77e319868ab18d71964bea6ee1aae5a02477a827283b9ce01c13eb1203b1d0ff87ae361f41c41bbc02965446acc77caa1f6a1c451fe227a718806

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

@@ -0,0 +1,93 @@
+---
+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.
+- `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
+`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/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/.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,119 @@ 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.
+
+**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.

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.0.0)
+    head_music (22.0.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

@@ -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/cantus_firmus/example.rb

@@ -2,7 +2,6 @@ module HeadMusic
   module Content
     module CantusFirmus
       # Sample cantus firmus examples from various pedagogical sources.
-      # These are traditional melodies used for teaching counterpoint.
       class Example
         EXAMPLES_DATA = YAML.load_file(File.expand_path("examples.yml", __dir__)).freeze
 
@@ -52,20 +51,12 @@ module HeadMusic
           pitches.length
         end
 
-        # Realize the example as a standalone flow: one part, no player, one
-        # voice, one note per bar.
-        #
         # An example is a catalog datum -- a pitch list with a mode and a
         # citation -- not content, so rhythm and meter are the realization's
         # choice rather than the datum's, and are parameters.
-        #
-        # The example's tonal center and mode land on the flow's opening key
-        # signature with no loss: the mode is carried by the tonal context, not
-        # inferred from the signature, which is what lets an example in
-        # E phrygian and one in D dorian share a signature of zero without
-        # collapsing into each other.
         def to_flow(rhythmic_value: :whole, meter: "4/4")
           flow = HeadMusic::Content::Flow.new(name: to_s, key_signature: key_signature_name, meter: meter)
+          flow.source = source
           voice = flow.add_voice(role: "cantus firmus")
           pitches.each_with_index { |pitch, index| voice.place("#{index + 1}:1", rhythmic_value, pitch) }
           flow