head_music 19.0.0 → 20.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7462797fd33041d3ab9fea4cf10cfaf329213d6f96d3f3b9cbb4f6a73dfd2890
-  data.tar.gz: 01c4cff6e9f609ce9543be019c340b3c7a01c21928e7248345d5a50364d85705
+  metadata.gz: b3714d51858bd368308d14a5f12544e6f4fb9dbecf0f0eacc1ad795c5e4b3d1e
+  data.tar.gz: 99345ffa2b44dfbdc27836b7b7350a38af1665770a74490f52e22bd1a0aa3602
 SHA512:
-  metadata.gz: c14082d1dc7e8405227b46be83e803b3037808c817200e8cadf18ead15dda70f17248d92a2c370d52f92eb9ea4241aa7dad07869e016979edc301c9d30f077aa
-  data.tar.gz: '06868ca14c8cca41f22c395cb04d84a6291492471cf034a9efd69afc4a822951cd2fc9ad4d2c7b4a94ed7d68b8bd70a8003090092b96291733ad1378f48c3d19'
+  metadata.gz: d95aa74479fe498564dc7e1bc5427660b9687e286a31a4b5cbbb1c0a274bebe9413ae18e2176dbbf38c351e4b1517275d5bf8dce590642c88c2301ea83f038b6
+  data.tar.gz: 4446808775faf30ef42dceca7de10248a88d8c8265ab4faa3c11589bd6ddb7dd60ff9c10ce2cb34a68f9e039061bc3633484e01b2002f649bb3f885bd5d7e968

data/.github/dependabot.yml

@@ -37,6 +37,10 @@ updates:
         update-types: ["version-update:semver-major"]
       - dependency-name: "i18n"
         update-types: ["version-update:semver-major"]
+      # simplecov 1.1.x is a SyntaxError on Ruby 3.3 (see the Gemfile comment).
+      # Dependabot rewrites a Gemfile constraint to get past it, so hold it here.
+      - dependency-name: "simplecov"
+        versions: [">= 1.1"]
 
   # Enable version updates for GitHub Actions
   - package-ecosystem: "github-actions"

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

@@ -7,14 +7,172 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.
+
+**Migrating from 19.0.0**, in the order a consumer will hit them:
+
+1. `Style::Analysis` is `Style::GuideAssessment`; `Guide#analyze(voice)` is `#assess(voice)`; `Analysis#annotations` is `GuideAssessment#guide_item_assessments`. `Style::Annotation` is `Style::Guideline`, and `Annotation::Configured` is `Style::GuideItem`.
+2. Ask for a species rather than pairing its halves: `Guide.get("first_species")` returns a composite that grades melody and harmony together and combines them geometrically. The seven composite keys are new; the two `combined_first_second_third_species_*` keys are now `first_three_species_*`.
+3. Grades move. Re-tiering weighs what a guide teaches above the craft it inherits, so any stored fitness from 19.0.0 is not comparable to one from 20.0.0. Regrade rather than migrate.
+4. Guideline strings are i18n templates. A consumer reading `MESSAGE` constants reads `GuideItemAssessment#message` instead.
+
+### Added
+
+- **Composite guides.** A species is a melody guide and a harmony guide, and a student submits one line to be judged by both. `Style::Guide.get("first_species")` now answers with a `Guides::CompositeGuide` over the two, and six siblings do the same: `second_species`, `third_species`, `third_species_triple_meter`, `fourth_species`, `fifth_species`, and `first_three_species`. `Guide.all` grows 23 → 30. Which two guides make up a species, and how their grades combine, is counterpoint pedagogy; it belongs here rather than in each consuming application.
+
+  A composite **composes grades, not items**. Merging its members' item lists cannot even be built — both members gate on `MinimumNotes.with(3)`, `GuideItem` equality is by value, and `Base.reject_duplicates` refuses the union — and would undo the tier budgets besides, putting nineteen primaries into one φ⁻¹ budget. The two levels grade by different arithmetic on purpose: rules inside a rubric trade off by weight, while a melody grade and a harmony grade must both hold.
+
+- `Style::CompositeAssessment`, which a composite returns from `assess(voice)`. Its `fitness` is the **geometric mean** of its members' grades, so a perfect melody against a half-graded harmony reads 0.707 rather than 0.75, and either half at zero takes the whole grade to zero. `assessments` holds one `GuideAssessment` per member, and `fitness_by_category` splits the grade into the melody and harmony halves a consumer wants to show separately.
+
+  When any member is unassessable the composite is too, and it grades on its members' **gate factors alone** — `GuideAssessment`'s own rule with the nouns raised: one member failing a precondition means the composite has not earned a grade on the other members either.
+
+- `GuideAssessment#assessments`, answering `[self]`, so a consumer walks a leaf assessment and a composite one the same way without asking which it holds. `GuideAssessment#fitness_by_category` answers the same shape, as one group of one.
+
+- `GuideAssessment#gate_factor` is public, and returns a `Float` for a gate-less guide rather than the Integer `1` it used to compute internally. A composite reads it when a member is unassessable.
+
+- `composite?` and `categories` on every guide. A composite spans its members' categories rather than claiming one, so its `category` is `nil` and a consumer grouping the registry by category gains a `nil` bucket; `categories` is what answers for it. A leaf answers `[category]`.
+
+- The rubric gains a second axis, orthogonal to tier: **strength**. Within a tier, a `:strong` guideline weighs twice a `:weak` one, normalized by that tier's own total. `Guideline.strength` declares it — `strength :weak, because: "…"`, where the reason is required for `:weak` and refused for `:strong` — and it defaults to `:strong`, so the axis is inert until a guideline opts in. An all-strong rubric grades bit-identically to one with no strength axis at all.
+
+  Unlike tier, strength is a property of the guideline rather than of the list it was declared in: a preference is a preference in every guide that names it. It is never inherited by a subclass, because `WeakBeatDissonanceTreatment` bases two treatments that are the taught rule of their own guides. An item may override it — `Guideline.with(strength: :weak)` — for the tradition-dependent case, where `ApproachPerfectionContrarily` is prohibited in Fux and merely cautioned later.
+
+  Eight guidelines are classified `:weak`: `FrequentDirectionChanges`, `LargeLeaps`, `LimitOctaveLeaps`, `ModerateDirectionChanges`, `MostlyConjunct`, `PreferContraryMotion`, `PreferImperfect`, and `PrepareOctaveLeaps`.
+
+- `GuideItem#strength` and `GuideItemAssessment#strength`. The assessment's is keyword-defaulted from the item rather than required, so existing direct-construction sites keep working, and validated there as well, since it is a seam a caller can reach without going through `GuideItem`; it is stamped rather than delegated so that re-classifying a guideline later cannot silently rewrite a persisted grade.
+
+- `HeadMusic::Style::Guidelines::SetAgainstAnotherVoice` — the definitional precondition of a harmony guide: counterpoint is a relationship between voices, and a voice alone has no harmony to assess.
+
+- `HeadMusic::Style::Template` — renders every customer-facing string in the style module, and refuses the four ways I18n fails quietly: a template rendered with no values keeps its `%{}` without raising, a value named for a reserved key hijacks the lookup, a missing key resolves to "Translation missing: …", and a word passed as `count` silently selects a plural. Every render passes `raise: true` and is checked for a surviving interpolation.
+
+  `Template.verify!` runs at load over the whole registry — twenty-three guide instructions, and every template the sixty-seven guide items can render, including the violation branches a guideline chooses between — so a missing entry stops `require` rather than reaching a student. It runs in English deliberately: a host application's locale must not decide whether the gem loads.
+
+  Where a locale has no plural data, `Template.pluralize` falls back to Ruby rather than raising, and records the key it fell back for.
+
+- British spellings for the five style strings that have them — `neighbour`, `metre`, and a bar rather than a measure. `en_GB` sits mid-chain, so German, French, Italian and Russian pick these up on the way to `en`. Note that any pluralized `en_GB` entry must carry the complete set of forms: I18n stops at a plural hash that is present but incomplete rather than continuing past it, so a partial one would raise for those four languages and never for a British reader.
+
+- **Note values in each language.** German, Spanish, French, Italian and Russian name note values as their own teachers do — *Viertel*, *negra*, *noire*, *semiminima*, *четвертная* — rather than inheriting British words on the way to `en`. No single English serves all four inheritors: the vocabulary splits into fractional, mensural-Latin, and shape families, and French *croche* is the **eighth** where its cognate *crotchet* is the quarter, so borrowed English actively misleads. The words, their derivation rules, plural behaviour, and the sources that disagree live in `references/note-values-by-language.md`.
+
+  The vocabulary itself lives under `head_music.rudiments`, beside the `rhythmic_unit` label already there, in three groups of eleven units each — `maxima` down to `hundred_twenty_eighth`: `rhythmic_units` (the bare unit, pluralizable, counted by `note_count_per_bar`), `note_values`, and `rest_values`. The three do not share a shape everywhere — a British note value drops the noun (*a crotchet*, not *a crotchet note*) while a British rest keeps it, and a French or Spanish rest names the concept (*soupir*, *silencio de negra*) rather than compounding the note value. Every locale also translates the words "note" and "rest" themselves. `Style::Template` gains a `scope:` keyword so style sentences borrow the rudiment vocabulary through the same seam that guards plural fallback and unfilled interpolations.
+
+- **LilyPond export.** `HeadMusic::Content::Composition#to_lilypond` renders a composition as a complete LilyPond document string, delegating to `HeadMusic::Notation::LilyPond.render(composition, **options)` — the outward complement of the inward `Notation::<Format>.parse` interpreters, in the same facade-plus-helpers shape as the ABC and MusicXML writers. The document carries a `\version` line, a `\header` with the composition's title and composer, and a `\score` with one staff per voice in absolute pitch mode — key signature, meter, and a clef chosen per voice, with mid-piece `\key` and `\time` changes emitted at the bar where they occur, one line per bar with a trailing bar check.
+
+  Whole-composition problems raise `Notation::LilyPond::RenderError` before any assembly — a voiceless composition, positional gaps, notes crossing barlines, a voice that ends mid-bar, unpitched sounds, and unmappable keys, durations, or alterations — so a returned string is always a complete document. Generated fixtures compile under the LilyPond CLI in the specs.
+
+- `Rudiment::RhythmicValue#tied_chain` — the value and every link tied after it, in order, so a writer walks a chain of tied values the same way it walks a chain of one.
+
+### Changed
+
+- **Breaking.** `GuideAssessment.new` raises `ArgumentError` when handed a composite guide, naming `guide.assess(voice)` as the seam that grades it correctly. Flattening a composite's items into one rubric would return a plausible number computed by the wrong arithmetic.
+
+- **Breaking.** Four renames, freeing the word "combined", which named mixed rhythm on two guides and would have named a guide composed of members as well:
+
+  | Was | Is |
+  | --- | --- |
+  | `Guides::CombinedFirstSecondThirdSpeciesMelody` | `Guides::FirstThreeSpeciesMelody` |
+  | `Guides::CombinedFirstSecondThirdSpeciesHarmony` | `Guides::FirstThreeSpeciesHarmony` |
+  | `Guidelines::AllowedRhythmicValuesForCombined123` | `Guidelines::AllowWholeHalfQuarterNotes` |
+  | `Guidelines::AllowedRhythmicValuesForFifthSpecies` | `Guidelines::AllowFifthSpeciesRhythmicValues` |
+
+  The registry keys `combined_first_second_third_species_melody` and `..._harmony` become `first_three_species_melody` and `first_three_species_harmony`, and the locale keys move with them. The two guideline names take different shapes deliberately: the first three species allow a set small enough to say in a name, and fifth species allows that set plus eighths and ties under conditions the guideline itself decides.
+
+- No existing guide's grade changes. Measured across the whole corpus — 3266 rows, 142 voices × 23 guides — every row is identical before and after.
+
+- **Breaking.** `GuideItem#initialize` takes `strength:` as a keyword, so its configuration hash must now be passed explicitly — `GuideItem.new(SomeGuideline, {minimum: 3})` rather than `GuideItem.new(SomeGuideline, minimum: 3)`. `Guideline.with(minimum: 3)` is unaffected and remains the ordinary way to build one.
+
+- **Breaking.** A guide that declares no `primary_items` raises `ArgumentError`, naming the guide and what it did declare. A guide that is all background has no subject, and grading it 1.0 in silence is the same "nothing to find fault in" confusion the gates fixed. Gate-only guides fall to the same check, deliberately. Every registered guide already declared a primary, so this closes a door rather than fixing a break.
+
+- **Breaking.** The seven species harmony guides demote `SpeciesHarmony::HARMONIC_CORE`, `DIMINUTION_HARMONIC_CORE`, and `NoParallelPerfectWithSyncopation` to `secondary_items`, mirroring the melodic demotion. A harmony guide now weighs the dissonance treatment it teaches above the two-part craft every harmony guide shares. `SecondSpeciesHarmony` gave 9/10 of its grade to rules it did not write and now gives φ⁻¹ to `WeakBeatDissonanceTreatment` alone; a fixture failing that rule moves 0.824 → 0.698, and a parallel octave costs about half what it did.
+
+  Each guide declares its tiers outright — `primary_items` for what it teaches, `secondary_items` splatting the shared craft constants — so the tier of every item is readable at the call site, and the specs hold the guides to the policy that a shared-core member stays background. `FirstThreeSpeciesHarmony` gains the diminution core it was missing — it covers two diminution species — and is the only guide anywhere whose set of guidelines changed.
+
+- **`NoParallelPerfectOnDownbeats` is a taught rule in first species harmony**, not inherited background — the one exception to the demotion above. It sits in the primary tier of `Guides::FirstSpeciesHarmony` alone, weighing 0.2060 beside `NoUnisonsInMiddle` and `OneToOne` at 0.2060 each, rather than the 0.0637 the shared harmonic core would give it; no other guide is affected.
+
+  A species guide is normally about the dissonance treatment its rhythm makes possible, and two-part craft is background. First species has no dissonance treatment, and its other two primaries are rhythm-and-texture bookkeeping — so note-against-note consonance handling is what the species teaches. Promoting the same rule in the six guides that *do* teach a dissonance treatment would weigh it as heavily as their subject, and would *raise* the grade of a submission already failing that subject by halving the weight it forgoes.
+
+  The exception is registered in `Guides::SpeciesHarmony::HARMONIC_CRAFT_PROMOTIONS`, and the specs hold every other harmony guide to the policy. A cantus firmus doubled an octave above itself grades 0.6674 where the shared-core weighting would read 0.8300, while Fux chapter one figure 5 as published still grades exactly 1.0.
+
+- `MostlyConjunct` marks each skip and leap at the ordinary penalty rather than `SMALL_PENALTY_FACTOR`, and says it is soft with `strength :weak` instead. The two say different things: a mark's fitness compounds into the item's own grade, so it set both how bad one instance was and how fast the item collapsed on repeats. Six leaps now grade 0.056 rather than 0.236. `SMALL_PENALTY_FACTOR` is unchanged and still used by `SecondSpeciesBreak`, which holds two severities inside one guideline.
+
+- **Breaking.** A guide declares its guidelines in three tiers rather than one flat `RULESET`, and the tier decides how much each one counts. `gate_items` are preconditions whose fitness multiplies the grade; `primary_items` are what the guide teaches and share φ⁻¹ of the rubric; `secondary_items` are background it inherits and share φ⁻². `Guides::Base.ruleset` and every `::RULESET` constant are removed — read `guide_items`, or one tier at a time.
+
+  Tier is the list an entry is declared in rather than a property of the entry, because the shared cores are shared objects: `SpeciesMelody::MELODIC_CORE` is splatted into six guides, and `ContourMelody` treats as background exactly what `DiatonicMelody` teaches. Guides whose tiers depend on configuration override `items_by_tier` with a keyword signature, as `ContourMelody` does.
+
+- **Breaking.** `Style::Annotation::Configured` becomes `Style::GuideItem`: a guideline paired with the configuration one guide gives it, with `guideline` and `config` readers and value equality. It no longer answers `#new(voice)`, `#with`, or `#default_gate?`.
+
+- **Breaking.** `Style::Analysis` becomes `Style::GuideAssessment`, and `#annotations` becomes `#guide_item_assessments`, which returns frozen `Style::GuideItemAssessment` values rather than live guideline instances. Each carries `tier`, `fitness`, `marks`, `message`, and the `guide_item` it came from.
+
+- **Breaking.** `guide.analyze(voice)` is replaced by `guide.assess(voice)`, which returns a `GuideAssessment`, and `guide.assess_items(voice)`, which returns the assessments it grades. `Style::Guide.get` and `GuideAssessment.new` both duck-check `assess_items`: guidelines and guide items answer `assess` too, with different arguments.
+
+- **Breaking.** Per-entry `weight` and `gate` are removed, along with `Guideline#weight`, `#gate?`, `.default_weight`, `.default_gate?`, `Contoured::DEFAULT_WEIGHT`, `MinimumThreshold.default_gate?`, and `ContourMelody::PEER_WEIGHT_BUDGET`. Tier replaces both. Whether a rule gates is the guide's editorial choice, not a property of the guideline — the same threshold can be a low gate in one guide and a stylistic minimum in another.
+
+- **Breaking.** `Guideline.new` is private. A guideline instance is the analysis context, not a result; `Guideline.assess` is the seam, and what comes back is a `GuideItemAssessment`.
+
+- **Breaking.** Every guide now declares a precondition, and failing one stops the assessment rather than scaling it. A voice that cannot be assessed reports `GuideAssessment#assessable? == false`, grades the product of its gates, and yields only gate assessments — the rubric is not computed. Previously a failed precondition multiplied a fully-computed rubric, so a four-note cantus firmus had its climax and leaps halved for being short.
+
+  `assess_items` therefore returns a variable-length list. A consumer upserting rows keyed by guide item must not read a missing row as a rule that was deleted.
+
+- **Breaking.** Grades change outside the degenerate range, deliberately. Three sources, with every affected row recorded in the story's grade table:
+
+  | Change | Effect |
+  | --- | --- |
+  | The seven species harmony guides gain `SetAgainstAnotherVoice` and a three-note minimum | They raised `NoMethodError` for a voice with no companion, at every length. They grade it now. |
+  | The seven species melody guides gain a three-note minimum | Each graded an empty voice 1.000 — no fault found, because there was nothing to find fault in. |
+  | `FuxCantusFirmus`, `SalzerSchachterCantusFirmus` and `DiatonicMelody` split their note minimum | A three-note gate asks whether this is a melody; the eight- or five-note prescription stays a rubric item, matching `MaximumNotes`, which always was one. A four-note cantus firmus moves from 0.500 unassessable to 0.969 assessable. |
+  | The species guides demote the shared melodic cores to `secondary_items` | A guide weighs its own rhythmic rules above the craft it inherits. A valid first-species line scored 0.883 against `ThirdSpeciesMelody` and now scores 0.561. |
+
+  Grading was byte-identical to 19.0.0 through the guide-item refactor above; these are the deliberate corrections that followed it. The string changes below do not affect it.
+
+- **Breaking.** Guideline strings move out of the classes and into the locale files. Every `MESSAGE` constant is removed. A guideline is addressed by the snake_case of its class name, so a new one needs no declaration — only entries under `head_music.style.guidelines.<key>`:
+
+  | Key | Reads |
+  | --- | --- |
+  | `name` | a short label, e.g. "Minimum of eight notes" |
+  | `instruction` | what to do |
+  | `violations.default` | what to do differently |
+
+  All three are templates. `GuideItem` renders them for its own configuration — `#name`, `#instruction`, `#violation_preview` — so the same guideline reads "at least three notes" in a gate and "at least eight" in a rubric. A guideline configured per guide supplies its interpolations from `self.template_values(config)`; a guide that wants a variant of the sentence names it with `violation_key:`, as `FuxCantusFirmus` does for `LargeLeaps`. A guideline that chooses between variants during the analysis itself declares them all with `.violation_keys`, as `ConsonantClimax` does for a climax dissonant with the tonic.
+
+  All fifty-five guidelines carry a `name` and an `instruction`. The name labels the rule — "No voice crossing", "Leap recovery" — and the instruction says what to write, where the violation says what to do differently: "Keep your line on its own side of the other voice" against "Avoid crossing voices". Both are a first draft, as the guide instructions are.
+
+  A rendered name is upcased on its first letter. A name may lead with an interpolation — `"%{contour} contour"` — whose value stays lowercase for the violation sentence that embeds it mid-clause, so "Arch contour" and "Write a melody with the arch contour" come from one locale value.
+
+  Both stay optional. A guideline with no `name` reads its class key as a sentence, and one with no `instruction` falls back to the violation, which is already phrased imperatively — so a guideline added before anyone writes it either one still reads. Until now that fallback was every guideline's only name: forty-six of the fifty-six in the registry rendered "Avoid crossing voices" or "Triple meter dissonance treatment" out of the class key, identically in every language, and the American spelling in that second one could not be regionalized because it never passed through a locale file at all.
+
+  The `message:` option that `SingableIntervals` and `LargeLeaps` accepted is removed with them: it passed an English sentence through the config hash, which is the thing this change exists to stop. A guide item declared with `message:` raises `ArgumentError` naming `violation_key:` rather than ignoring the key, since an unrecognized option would otherwise ride along in `config` and be dropped at render — a custom sentence vanishing with no error.
+
+  `GuideItemAssessment#message` is now `nil` for an adherent item rather than the message it would have printed. Read `GuideItem#violation_preview` for the sentence in the abstract.
+
+  `GuideItemAssessment#name`, and `#to_s` with it, answer the item's rendered name — "Minimum of eight notes" — rather than the guideline's class path. A consumer building a results list holds assessments rather than items, so that is where a rubric gets its labels.
+
+- **Breaking.** Guides gain `#instruction` — what a guide asks a student to write, as distinct from how it grades what they wrote — and their names move under `head_music.style.guides.<key>.name` from the flat `<key>`. The twenty-three instructions are a first draft.
+
+- **Breaking.** `Notation::MusicXML::ClefSelector` is now `Notation::ClefSelector`, and the old name no longer resolves. Choosing a clef for a voice's tessitura is format-independent, and the LilyPond writer reads it alongside the MusicXML one. The shared preflight checks the two writers agree on — contiguous placements, notes within barlines — move to `Notation::PreflightChecks` the same way.
+
+## [19.0.0] - 2026-08-07
+
 ### Added
 
 - `HeadMusic::Style::Guide` — a lookup facade over every style guide in the gem. `Guide.get("first_species_harmony")` resolves a key to a guide; an unknown key returns `nil` rather than raising, so a consumer can ask about a guide the gem does not have. `Guide.get!` raises `KeyError` instead, and `Guide.known?`, `.all`, `.keys`, and `.key_for` round out the surface. Keys are stable strings suitable for storing in a database. The registry holds twenty-three:
 
   | Category | Keys |
   | --- | --- |
-  | `:melody` | `fux_cantus_firmus`, `salzer_schachter_cantus_firmus`, `diatonic_melody`, `first_species_melody`, `second_species_melody`, `third_species_melody`, `third_species_triple_meter_melody`, `fourth_species_melody`, `combined_first_second_third_species_melody`, `fifth_species_melody`, `arch_contour_melody`, `ascending_contour_melody`, `descending_contour_melody`, `static_contour_melody`, `valley_contour_melody`, `wave_contour_melody` |
-  | `:harmony` | `first_species_harmony`, `second_species_harmony`, `third_species_harmony`, `third_species_triple_meter_harmony`, `fourth_species_harmony`, `combined_first_second_third_species_harmony`, `fifth_species_harmony` |
+  | `:melody` | `fux_cantus_firmus`, `salzer_schachter_cantus_firmus`, `diatonic_melody`, `first_species_melody`, `second_species_melody`, `third_species_melody`, `third_species_triple_meter_melody`, `fourth_species_melody`, `first_three_species_melody`, `fifth_species_melody`, `arch_contour_melody`, `ascending_contour_melody`, `descending_contour_melody`, `static_contour_melody`, `valley_contour_melody`, `wave_contour_melody` |
+  | `:harmony` | `first_species_harmony`, `second_species_harmony`, `third_species_harmony`, `third_species_triple_meter_harmony`, `fourth_species_harmony`, `first_three_species_harmony`, `fifth_species_harmony` |
 
 - Guides now carry identity: `.key` (snake_case of the class name), `.category` (`:melody` or `:harmony`, derived from the `SpeciesMelody`/`SpeciesHarmony` ancestry), and `.display_name` (localizable, with a computed English default). Consumers no longer need to hand-maintain a map of guide constants to categories.
 - `HeadMusic::Style::Guides::Configured` — the guide-layer twin of `Annotation::Configured`. It pairs a guide class with options and answers `analyze(voice)`, so it drops into `Style::Analysis` wherever a guide class was expected. `Guides::Base.with(**options)` returns one, and `#with` layers further options without dropping earlier ones.
@@ -573,7 +731,34 @@ 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/v8.2.0...HEAD
+[Unreleased]: https://github.com/roberthead/head_music/compare/v20.1.0...HEAD
+[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
+[17.5.0]: https://github.com/roberthead/head_music/compare/v17.3.0...v17.5.0
+[17.3.0]: https://github.com/roberthead/head_music/compare/v17.2.0...v17.3.0
+[17.2.0]: https://github.com/roberthead/head_music/compare/v17.1.0...v17.2.0
+[17.1.0]: https://github.com/roberthead/head_music/compare/v17.0.0...v17.1.0
+[17.0.0]: https://github.com/roberthead/head_music/compare/v15.2.0...v17.0.0
+[15.2.0]: https://github.com/roberthead/head_music/compare/v15.0.0...v15.2.0
+[15.0.0]: https://github.com/roberthead/head_music/compare/v14.0.0...v15.0.0
+[14.0.0]: https://github.com/roberthead/head_music/compare/v13.0.0...v14.0.0
+[13.0.0]: https://github.com/roberthead/head_music/compare/v12.6.0...v13.0.0
+[12.6.0]: https://github.com/roberthead/head_music/compare/v12.5.0...v12.6.0
+[12.5.0]: https://github.com/roberthead/head_music/compare/v12.4.0...v12.5.0
+[12.4.0]: https://github.com/roberthead/head_music/compare/v12.3.0...v12.4.0
+[12.3.0]: https://github.com/roberthead/head_music/compare/v12.2.0...v12.3.0
+[12.2.0]: https://github.com/roberthead/head_music/compare/v12.1.0...v12.2.0
+[12.1.0]: https://github.com/roberthead/head_music/compare/v12.0.1...v12.1.0
+[12.0.1]: https://github.com/roberthead/head_music/compare/v12.0.0...v12.0.1
+[12.0.0]: https://github.com/roberthead/head_music/compare/v11.8.0...v12.0.0
+[11.8.0]: https://github.com/roberthead/head_music/compare/v11.7.0...v11.8.0
+[11.7.0]: https://github.com/roberthead/head_music/compare/v11.6.1...v11.7.0
+[11.6.1]: https://github.com/roberthead/head_music/compare/v11.6.0...v11.6.1
+[11.6.0]: https://github.com/roberthead/head_music/compare/v11.5.1...v11.6.0
+[11.0.0]: https://github.com/roberthead/head_music/compare/v9.1.0...v11.0.0
+[9.0.0]: https://github.com/roberthead/head_music/compare/v8.4.0...v9.0.0
 [8.2.0]: https://github.com/roberthead/head_music/compare/v8.1.1...v8.2.0
 [8.1.1]: https://github.com/roberthead/head_music/compare/v8.1.0...v8.1.1
 [8.1.0]: https://github.com/roberthead/head_music/compare/v8.0.2...v8.1.0
@@ -595,4 +780,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

@@ -114,7 +114,7 @@ The codebase follows a domain-driven design with clear module boundaries:
 7. **HeadMusic::Style** - Composition rules and guidelines
   - Counterpoint rules (species counterpoint guides)
   - Voice leading guidelines
-  - Style analysis and annotations
+  - Style analysis and guidelines
   - Historical traditions (medieval, renaissance, modern)
 
 8. **HeadMusic::Utilities** - Shared helpers

data/Gemfile

@@ -5,18 +5,23 @@ 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
 
 group :test do
-  gem "rubocop", require: false
+  # rubocop is not listed directly: standard pins it (~> 1.88.0) and must
+  # lead. Listing it here let Dependabot bump it past standard, which the
+  # resolver "fixed" by downgrading standard 1.56 -> 1.35.
   gem "rubocop-rspec", require: false
   gem "rubocop-rake", require: false
-  gem "simplecov", require: false
+  # simplecov 1.1.x forwards an anonymous block inside a block, which is a
+  # syntax error on Ruby 3.3. Unpin once upstream drops that or we drop 3.3.
+  gem "simplecov", "< 1.1", require: false
 end
 
 group :development do

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (19.0.0)
+    head_music (20.1.0)
       activesupport (>= 7.0, < 10)
       humanize (>= 2, < 4)
       i18n (~> 1.8)
@@ -9,7 +9,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (8.1.3)
+    activesupport (8.1.3.1)
       base64
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
@@ -207,7 +207,7 @@ GEM
       coercible (~> 1.0)
       descendants_tracker (~> 0.0, >= 0.0.3)
     yard (0.9.45)
-    zeitwerk (2.8.2)
+    zeitwerk (2.8.3)
 
 PLATFORMS
   arm64-darwin-22
@@ -216,23 +216,22 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
-  bundler-audit
+  bundler-audit (~> 0.9, >= 0)
   head_music!
   kramdown
   rake (~> 13.0)
   rexml (~> 3.4)
   rspec (~> 3.0)
   rspec-its (~> 2.0)
-  rubocop
   rubocop-rake
   rubocop-rspec
   rubycritic
-  simplecov
+  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