head_music 13.0.0 → 15.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef07dfecedad63290f5f352704f96967dff09ba5bc305adf04b25c033bf580fb
-  data.tar.gz: fd20210a40bd733fada3307f6b9b772bd317168132443d164aa417a0d2c490bd
+  metadata.gz: 7c29fa7f976d16091512b8bdc9eb8befcb4766c4bb70d387a67991e9b9897a5c
+  data.tar.gz: b43c0fed22c3ed7c79a7a0195847740ba7b3bea608a24921893a329f0c66ba7f
 SHA512:
-  metadata.gz: cee6694acb9303262ac645153f47462d5e6870e62853bc800d00e731dc0fc5321c00d2e75109c6805a1c2ba0d1b62ddbfdc8196bd445d52062097fd05c24d9eb
-  data.tar.gz: 8ee30bdeaf48faf0f43411352763c6d67ec3f5919c707054bcdee4ab07514936d09c335a03fa031e7df59479c597aeb4c165765b8c6de5210d9d45edd5639e3a
+  metadata.gz: 47d395cc1709167182e0810c7383120395e927629a2e5e5076e197bdacfd377445546a842a032fecabd9865f62e878f969fec301535758072b45db229c80e8e4
+  data.tar.gz: '0950f0d5a6a2b830a1733d8d0a7d19eb9fcb87815e25d3e562dc6aa94bc95c16a2d7710ca31890e23d1dcc07fc64247030565741d2edf38da6cb177f7e091fb9'

data/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [15.0.0] - 2026-07-06
+
+### Added
+
+- `HeadMusic::Style::Guidelines::MinimumMelodicIntervals` — a sufficiency gate on the number of moving melodic intervals, so a line that never (or barely) moves reads as a non-attempt rather than a flawed melody (`MinimumMelodicIntervals.with(2)`). The contour guides use it; `StaticContourMelody` omits it so a repeated single pitch remains a legitimate static contour.
+- `weight:` and `gate:` options on `Annotation.with` — any ruleset entry can now carry a rubric weight or be marked as a gate, and `Configured#with` layers options so presets compose (e.g. `MinimumNotes.with(5).with(gate: true)`)
+
+### Changed
+
+- **Breaking:** `Analysis#fitness` is now a gated weighted rubric instead of an unweighted geometric mean: the product of the gate fitnesses multiplies a weighted arithmetic mean of the remaining (rubric) rules. Every fitness value shifts numerically; downstream consumers that compare grades against stored thresholds must recalibrate.
+- Non-attempts now grade zero: sufficiency guidelines (`MinimumNotes`, `MinimumMelodicIntervals`) act as graded gate multipliers, so an empty or insufficient line scales the whole grade down to 0 instead of averaging against the other rules.
+- Contour guides weight `Contoured` at the inverse golden ratio (φ⁻¹ ≈ 0.618) with their ten rubric peers sharing φ⁻² evenly, so a wrong-contour but otherwise perfect line grades exactly ~0.618 (`HeadMusic::GOLDEN_RATIO_INVERSE`)
+- `Diatonic` and `MaximumNotes` are rate-normalized (fitness raised to 1/note-count), so grades are length-invariant: the same violation rate scores the same in an eight-note line as in a sixteen-note line
+- Broken-but-real work now lands on a deliberate soft floor (roughly 0.3–0.55): rate-normalized rules bottom out near φ⁻¹ and the arithmetic mean averages them, so a gate-passing melody that breaks most of the rubric grades substantially below perfect without collapsing toward the gated zero of a non-attempt
+
+## [14.0.0] - 2026-07-05
+
+### Added
+
+- `HeadMusic::Style::Guidelines::Contoured` — configurable guideline judging a melody against a chosen contour (`Contoured.with(:arch)` and five other keys: `ascending`, `descending`, `valley`, `wave`, `static`). Predicates are trend-based rather than strictly monotonic; a wrong contour receives a single mark spanning the melody. Unknown contour keys raise `ArgumentError` at guide-definition time.
+- Six contour guides subclassing `Guides::DiatonicMelody`, each appending the configured `Contoured` guideline to the inherited ruleset: `ArchContourMelody`, `AscendingContourMelody`, `DescendingContourMelody`, `StaticContourMelody`, `ValleyContourMelody`, `WaveContourMelody`
+- Contour judgments deliberately complement `ConsonantClimax`: an arch requires only an interior climax pitch level, leaving climax uniqueness and consonance to the existing guideline
+
 ## [13.0.0] - 2026-07-05
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (13.0.0)
+    head_music (15.0.0)
       activesupport (>= 7.0, < 10)
       humanize (~> 2.0)
       i18n (~> 1.8)

data/lib/head_music/style/analysis.rb

@@ -19,19 +19,34 @@ class HeadMusic::Style::Analysis
     @annotations ||= @guide.analyze(voice)
   end
 
+  # The grade: sufficiency gates multiply against a weighted average of the
+  # rubric rules, so an insufficient exercise scales the whole grade down
+  # while ordinary rules trade off against each other by weight.
   def fitness
     return 1.0 if annotations.empty?
 
-    @fitness ||= fitness_scores.reduce(:*)**(1.0 / fitness_scores.length)
+    @fitness ||= gate_factor * rubric_fitness
   end
 
   def adherent?
-    fitness == 1
+    annotations.all?(&:adherent?)
   end
 
   private
 
-  def fitness_scores
-    @fitness_scores ||= annotations.map(&:fitness)
+  def gate_factor
+    gates.map(&:fitness).reduce(1, :*)
+  end
+
+  def rubric_fitness
+    rubric = annotations.reject(&:gate?)
+    total_weight = rubric.sum(&:weight)
+    return 1.0 if rubric.empty? || total_weight.zero?
+
+    rubric.sum { |annotation| annotation.weight * annotation.fitness } / total_weight
+  end
+
+  def gates
+    annotations.select(&:gate?)
   end
 end

data/lib/head_music/style/annotation.rb

@@ -2,6 +2,8 @@
 class HeadMusic::Style::Annotation
   MESSAGE = "Write music."
 
+  DEFAULT_WEIGHT = 1.0
+
   attr_reader :voice
 
   delegate(
@@ -34,6 +36,14 @@ class HeadMusic::Style::Annotation
     Configured.new(self, options)
   end
 
+  def self.default_weight
+    DEFAULT_WEIGHT
+  end
+
+  def self.default_gate?
+    false
+  end
+
   # A RULESET entry pairing a guideline class with configuration. Quacks like a
   # class to the analyze loop by responding to #new(voice).
   class Configured
@@ -48,6 +58,19 @@ class HeadMusic::Style::Annotation
       guideline_class.new(voice, **options)
     end
 
+    # Layers additional options onto an already-configured entry, e.g.
+    # MinimumNotes.with(5).with(gate: true), without dropping prior options.
+    def with(**more)
+      Configured.new(guideline_class, options.merge(more))
+    end
+
+    # Mirrors the class-level predicate so build-time RULESET filters can
+    # classify any entry (bare class or configured) uniformly. A per-entry
+    # gate: option takes precedence over the guideline class's default.
+    def default_gate?
+      options.fetch(:gate, guideline_class.default_gate?)
+    end
+
     def name
       guideline_class.name
     end
@@ -56,13 +79,24 @@ class HeadMusic::Style::Annotation
   end
 
   def fitness
-    [marks].flatten.compact.map(&:fitness).reduce(1, :*)
+    mark_fitnesses = [marks].flatten.compact.map(&:fitness)
+    return 1.0 if mark_fitnesses.empty?
+
+    mark_fitnesses.reduce(1, :*)**(1.0 / [fitness_denominator, 1].max)
   end
 
   def adherent?
     fitness == 1
   end
 
+  def weight
+    options.fetch(:weight, self.class.default_weight)
+  end
+
+  def gate?
+    options.fetch(:gate, self.class.default_gate?)
+  end
+
   def has_notes?
     !!first_note
   end
@@ -91,6 +125,13 @@ class HeadMusic::Style::Annotation
 
   attr_reader :options
 
+  # Normalization rate for the product of mark fitnesses. Subclasses override
+  # (e.g. with an opportunity count) to score by violation rate rather than
+  # raw violation count. The default of 1 preserves the raw product.
+  def fitness_denominator
+    1
+  end
+
   def voices
     @voices ||= voice.composition.voices
   end

data/lib/head_music/style/guidelines/contoured.rb

@@ -0,0 +1,140 @@
+# Module for style guidelines.
+module HeadMusic::Style::Guidelines; end
+
+# Flags a melody without the configured contour
+# Configure the contour with the factory, e.g. Contoured.with(:arch).
+class HeadMusic::Style::Guidelines::Contoured < HeadMusic::Style::Annotation
+  CONTOURS = %i[ascending descending arch valley wave static].freeze
+
+  TREND_REVERSAL_SEMITONES = 3 # a trend reversal must exceed a whole step
+
+  DEFAULT_WEIGHT = HeadMusic::GOLDEN_RATIO_INVERSE
+
+  def self.with(contour_key, **options)
+    contour = contour_key.to_s.downcase.to_sym
+    unless CONTOURS.include?(contour)
+      raise ArgumentError, "Contour must be one of: #{CONTOURS.join(", ")} (got #{contour_key.inspect})"
+    end
+
+    super(contour: contour, **options)
+  end
+
+  def self.default_weight
+    DEFAULT_WEIGHT
+  end
+
+  def marks
+    return if notes.empty? || matches_contour?
+
+    HeadMusic::Style::Mark.for_all(notes, fitness: HeadMusic::GOLDEN_RATIO_INVERSE**2)
+  end
+
+  def message
+    "Write a melody with the #{contour} contour."
+  end
+
+  private
+
+  # Validated again here because Contoured.new(voice, contour: :bogus) bypasses .with.
+  def contour
+    @contour ||= begin
+      key = options.fetch(:contour)
+      contour = key.to_s.downcase.to_sym
+      unless CONTOURS.include?(contour)
+        raise ArgumentError, "Contour must be one of: #{CONTOURS.join(", ")} (got #{key.inspect})"
+      end
+
+      contour
+    end
+  end
+
+  def matches_contour?
+    send("#{contour}?")
+  end
+
+  def ascending?
+    first_note.pitch == lowest_pitch && last_note.pitch == highest_pitch
+  end
+
+  def descending?
+    first_note.pitch == highest_pitch && last_note.pitch == lowest_pitch
+  end
+
+  # The climax is by definition the maximum, so "net rise before, net fall after"
+  # is equivalent to both endpoints sitting below the climax pitch.
+  # Climax uniqueness and consonance remain ConsonantClimax's job.
+  def arch?
+    notes.length >= 3 && first_note.pitch < highest_pitch && last_note.pitch < highest_pitch
+  end
+
+  def valley?
+    notes.length >= 3 && first_note.pitch > lowest_pitch && last_note.pitch > lowest_pitch
+  end
+
+  def wave?
+    trend_directions.length >= 3
+  end
+
+  def static?
+    range <= HeadMusic::Analysis::DiatonicInterval.get(:major_third) && !directional_endpoints?
+  end
+
+  # The highest_pitch > lowest_pitch guard is load-bearing: without it, an
+  # all-same-pitch melody (first == lowest and last == highest simultaneously)
+  # would absurdly fail static.
+  def directional_endpoints?
+    highest_pitch > lowest_pitch &&
+      ((first_note.pitch == lowest_pitch && last_note.pitch == highest_pitch) ||
+        (first_note.pitch == highest_pitch && last_note.pitch == lowest_pitch))
+  end
+
+  def pitch_numbers
+    @pitch_numbers ||= notes.map { |note| note.pitch.midi_note_number }
+  end
+
+  # Zigzag walk: a trend reversal is confirmed only when the melody retraces at
+  # least TREND_REVERSAL_SEMITONES from the running extreme of the current trend,
+  # so stepwise neighbor-note undulation never registers as a trend change.
+  def trend_directions
+    @trend_directions ||= begin
+      directions = []
+      direction = nil
+      high = low = pitch_numbers.first
+      extreme = nil
+      pitch_numbers.drop(1).each do |number|
+        case direction
+        when nil # no trend confirmed yet
+          if number - low >= TREND_REVERSAL_SEMITONES
+            direction = :ascending
+            extreme = number
+            directions << direction
+          elsif high - number >= TREND_REVERSAL_SEMITONES
+            direction = :descending
+            extreme = number
+            directions << direction
+          else
+            high = [high, number].max
+            low = [low, number].min
+          end
+        when :ascending
+          if number > extreme
+            extreme = number
+          elsif extreme - number >= TREND_REVERSAL_SEMITONES
+            direction = :descending
+            extreme = number
+            directions << direction
+          end
+        when :descending
+          if number < extreme
+            extreme = number
+          elsif number - extreme >= TREND_REVERSAL_SEMITONES
+            direction = :ascending
+            extreme = number
+            directions << direction
+          end
+        end
+      end
+      directions
+    end
+  end
+end

data/lib/head_music/style/guidelines/diatonic.rb

@@ -9,6 +9,14 @@ class HeadMusic::Style::Guidelines::Diatonic < HeadMusic::Style::Annotation
     HeadMusic::Style::Mark.for_each(notes_not_in_key_excluding_penultimate_leading_tone)
   end
 
+  protected
+
+  # Score by the rate of out-of-key notes rather than the raw count,
+  # so fitness is invariant to melody length.
+  def fitness_denominator
+    notes.length
+  end
+
   private
 
   def notes_not_in_key_excluding_penultimate_leading_tone

data/lib/head_music/style/guidelines/maximum_notes.rb

@@ -4,8 +4,8 @@ module HeadMusic::Style::Guidelines; end
 # Flags a melody with more than the allowed number of notes.
 # Configure the threshold with the factory, e.g. MaximumNotes.with(14).
 class HeadMusic::Style::Guidelines::MaximumNotes < HeadMusic::Style::Annotation
-  def self.with(maximum)
-    super(maximum: maximum)
+  def self.with(maximum, **options)
+    super(maximum: maximum, **options)
   end
 
   def marks
@@ -16,6 +16,14 @@ class HeadMusic::Style::Guidelines::MaximumNotes < HeadMusic::Style::Annotation
     "Write up to #{maximum.humanize} notes."
   end
 
+  protected
+
+  # Score by the rate of overage notes rather than the raw count,
+  # so fitness is invariant to melody length.
+  def fitness_denominator
+    notes.length
+  end
+
   private
 
   def maximum

data/lib/head_music/style/guidelines/minimum_melodic_intervals.rb

@@ -0,0 +1,55 @@
+# Module for style guidelines.
+module HeadMusic::Style::Guidelines; end
+
+# Flags a melody with fewer than the required number of moving melodic intervals.
+# Repeated-note pairs don't count as motion, so an all-repeated-note line gates to 0.
+# Configure the threshold with the factory, e.g. MinimumMelodicIntervals.with(2).
+class HeadMusic::Style::Guidelines::MinimumMelodicIntervals < HeadMusic::Style::Annotation
+  def self.with(minimum, **options)
+    super(minimum: minimum, **options)
+  end
+
+  def self.default_gate?
+    true
+  end
+
+  def marks
+    return no_motion_mark if moving_intervals.empty?
+
+    deficiency_mark
+  end
+
+  def message
+    "Write at least #{minimum.humanize} melodic intervals."
+  end
+
+  private
+
+  def minimum
+    options.fetch(:minimum)
+  end
+
+  def moving_intervals
+    melodic_intervals.select(&:moving?)
+  end
+
+  def no_motion_mark
+    return no_placements_mark if placements.empty?
+
+    HeadMusic::Style::Mark.for_all(placements, fitness: 0)
+  end
+
+  def no_placements_mark
+    HeadMusic::Style::Mark.new(
+      HeadMusic::Content::Position.new(composition, "1:1"),
+      HeadMusic::Content::Position.new(composition, "2:1"),
+      fitness: 0
+    )
+  end
+
+  def deficiency_mark
+    return unless moving_intervals.length < minimum
+
+    HeadMusic::Style::Mark.for_all(placements, fitness: moving_intervals.length.to_f / minimum)
+  end
+end

data/lib/head_music/style/guidelines/minimum_notes.rb

@@ -4,8 +4,12 @@ module HeadMusic::Style::Guidelines; end
 # Flags a melody with fewer than the required number of notes.
 # Configure the threshold with the factory, e.g. MinimumNotes.with(8).
 class HeadMusic::Style::Guidelines::MinimumNotes < HeadMusic::Style::Annotation
-  def self.with(minimum)
-    super(minimum: minimum)
+  def self.with(minimum, **options)
+    super(minimum: minimum, **options)
+  end
+
+  def self.default_gate?
+    true
   end
 
   def marks

data/lib/head_music/style/guides/arch_contour_melody.rb

@@ -0,0 +1,4 @@
+# A free diatonic melody with an arch contour (interior climax).
+class HeadMusic::Style::Guides::ArchContourMelody < HeadMusic::Style::Guides::DiatonicMelody
+  RULESET = contour_ruleset(:arch, minimum_melodic_intervals: 2)
+end

data/lib/head_music/style/guides/ascending_contour_melody.rb

@@ -0,0 +1,4 @@
+# A free diatonic melody with an ascending contour (departs its floor, arrives at its ceiling).
+class HeadMusic::Style::Guides::AscendingContourMelody < HeadMusic::Style::Guides::DiatonicMelody
+  RULESET = contour_ruleset(:ascending, minimum_melodic_intervals: 1)
+end

data/lib/head_music/style/guides/descending_contour_melody.rb

@@ -0,0 +1,4 @@
+# A free diatonic melody with a descending contour (departs its ceiling, arrives at its floor).
+class HeadMusic::Style::Guides::DescendingContourMelody < HeadMusic::Style::Guides::DiatonicMelody
+  RULESET = contour_ruleset(:descending, minimum_melodic_intervals: 1)
+end

data/lib/head_music/style/guides/diatonic_melody.rb

@@ -18,4 +18,28 @@ class HeadMusic::Style::Guides::DiatonicMelody < HeadMusic::Style::Guides::Speci
     HeadMusic::Style::Guidelines::MinimumNotes.with(5),
     HeadMusic::Style::Guidelines::MaximumNotes.with(32)
   ].freeze
+
+  # The non-gate peers of a contour guide share phi^-2 of rubric weight, so
+  # that with Contoured at its default weight of phi^-1 (and phi^-1 + phi^-2
+  # = 1), a wrong contour on an otherwise perfect line grades exactly phi^-1.
+  CONTOUR_PEER_WEIGHT_BUDGET = HeadMusic::GOLDEN_RATIO_INVERSE**2
+
+  # Builds a contour guide's ruleset from this guide's rules: gate entries
+  # pass through unchanged, non-gate peers split the peer weight budget
+  # evenly, and the contour guideline is appended at its own default weight.
+  # An optional motion gate excludes non-attempts (nil omits it, so a static
+  # contour can legitimately repeat a single pitch).
+  def self.contour_ruleset(contour_key, minimum_melodic_intervals: nil)
+    gates, peers = RULESET.partition(&:default_gate?)
+    peer_weight = CONTOUR_PEER_WEIGHT_BUDGET / peers.length
+    motion_gate =
+      minimum_melodic_intervals &&
+      HeadMusic::Style::Guidelines::MinimumMelodicIntervals.with(minimum_melodic_intervals)
+    [
+      *gates,
+      motion_gate,
+      *peers.map { |rule| rule.with(weight: peer_weight) },
+      HeadMusic::Style::Guidelines::Contoured.with(contour_key)
+    ].compact.freeze
+  end
 end

data/lib/head_music/style/guides/static_contour_melody.rb

@@ -0,0 +1,5 @@
+# A free diatonic melody with a static contour (narrow range, non-directional endpoints).
+# No motion gate: an all-repeated-note line is a legitimate static contour.
+class HeadMusic::Style::Guides::StaticContourMelody < HeadMusic::Style::Guides::DiatonicMelody
+  RULESET = contour_ruleset(:static)
+end

data/lib/head_music/style/guides/valley_contour_melody.rb

@@ -0,0 +1,4 @@
+# A free diatonic melody with a valley contour (interior nadir).
+class HeadMusic::Style::Guides::ValleyContourMelody < HeadMusic::Style::Guides::DiatonicMelody
+  RULESET = contour_ruleset(:valley, minimum_melodic_intervals: 2)
+end

data/lib/head_music/style/guides/wave_contour_melody.rb

@@ -0,0 +1,4 @@
+# A free diatonic melody with a wave contour (repeated undulation at the trend level).
+class HeadMusic::Style::Guides::WaveContourMelody < HeadMusic::Style::Guides::DiatonicMelody
+  RULESET = contour_ruleset(:wave, minimum_melodic_intervals: 2)
+end

data/lib/head_music/version.rb

@@ -1,3 +1,3 @@
 module HeadMusic
-  VERSION = "13.0.0"
+  VERSION = "15.0.0"
 end

data/lib/head_music.rb

@@ -154,11 +154,13 @@ require "head_music/style/mark"
 # style guidelines
 require "head_music/style/guidelines/always_move"
 require "head_music/style/guidelines/approach_perfection_contrarily"
+require "head_music/style/guidelines/minimum_melodic_intervals"
 require "head_music/style/guidelines/minimum_notes"
 require "head_music/style/guidelines/avoid_crossing_voices"
 require "head_music/style/guidelines/avoid_overlapping_voices"
 require "head_music/style/guidelines/consonant_climax"
 require "head_music/style/guidelines/consonant_downbeats"
+require "head_music/style/guidelines/contoured"
 require "head_music/style/guidelines/diatonic"
 require "head_music/style/guidelines/direction_changes"
 require "head_music/style/guidelines/end_on_perfect_consonance"
@@ -219,6 +221,12 @@ require "head_music/style/guides/fux_cantus_firmus"
 require "head_music/style/guides/salzer_schachter_cantus_firmus"
 require "head_music/style/guides/first_species_melody"
 require "head_music/style/guides/diatonic_melody"
+require "head_music/style/guides/arch_contour_melody"
+require "head_music/style/guides/ascending_contour_melody"
+require "head_music/style/guides/descending_contour_melody"
+require "head_music/style/guides/static_contour_melody"
+require "head_music/style/guides/valley_contour_melody"
+require "head_music/style/guides/wave_contour_melody"
 require "head_music/style/guides/species_harmony"
 require "head_music/style/guides/first_species_harmony"
 require "head_music/style/guides/second_species_melody"