head_music 14.0.0 → 15.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed605ba621e60e4222568efe6071c86daace2bbf21c6c577b7ccfda1fb67f769
-  data.tar.gz: b4a0f23c074d7d5bca6eb849a4e01ba099631c87d7cef89e3fd130c294a20803
+  metadata.gz: 7c29fa7f976d16091512b8bdc9eb8befcb4766c4bb70d387a67991e9b9897a5c
+  data.tar.gz: b43c0fed22c3ed7c79a7a0195847740ba7b3bea608a24921893a329f0c66ba7f
 SHA512:
-  metadata.gz: 888d95ec1fab0517520899150d8caf794f7ec4edc7fa19e19d370d761d4541287712d207beb4b6f6772e0da62615258607c8ce5dbfb93d9311d5e32c692bbbc8
-  data.tar.gz: 759c97ee1504589dfbd6f91c2ac2bad6aa685ce70cf413ffc76eea2bdd4864fc6598b56d742d5e34d5f3ac528f88548830ca502ef7f866d034b0a349c5cf7e8f
+  metadata.gz: 47d395cc1709167182e0810c7383120395e927629a2e5e5076e197bdacfd377445546a842a032fecabd9865f62e878f969fec301535758072b45db229c80e8e4
+  data.tar.gz: '0950f0d5a6a2b830a1733d8d0a7d19eb9fcb87815e25d3e562dc6aa94bc95c16a2d7710ca31890e23d1dcc07fc64247030565741d2edf38da6cb177f7e091fb9'

data/CHANGELOG.md

@@ -7,6 +7,21 @@ 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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (14.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

@@ -8,19 +8,25 @@ class HeadMusic::Style::Guidelines::Contoured < HeadMusic::Style::Annotation
 
   TREND_REVERSAL_SEMITONES = 3 # a trend reversal must exceed a whole step
 
-  def self.with(contour_key)
+  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)
+    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)
+    HeadMusic::Style::Mark.for_all(notes, fitness: HeadMusic::GOLDEN_RATIO_INVERSE**2)
   end
 
   def message

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

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

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

@@ -1,7 +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 = [
-    *HeadMusic::Style::Guides::DiatonicMelody::RULESET,
-    HeadMusic::Style::Guidelines::Contoured.with(:ascending)
-  ].freeze
+  RULESET = contour_ruleset(:ascending, minimum_melodic_intervals: 1)
 end

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

@@ -1,7 +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 = [
-    *HeadMusic::Style::Guides::DiatonicMelody::RULESET,
-    HeadMusic::Style::Guidelines::Contoured.with(:descending)
-  ].freeze
+  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

@@ -1,7 +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 = [
-    *HeadMusic::Style::Guides::DiatonicMelody::RULESET,
-    HeadMusic::Style::Guidelines::Contoured.with(:static)
-  ].freeze
+  RULESET = contour_ruleset(:static)
 end

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

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

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

@@ -1,7 +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 = [
-    *HeadMusic::Style::Guides::DiatonicMelody::RULESET,
-    HeadMusic::Style::Guidelines::Contoured.with(:wave)
-  ].freeze
+  RULESET = contour_ruleset(:wave, minimum_melodic_intervals: 2)
 end

data/lib/head_music/version.rb

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

data/lib/head_music.rb

@@ -154,6 +154,7 @@ 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"

data/user-stories/done/scoring-architecture.md

@@ -0,0 +1,352 @@
+<!--
+metadata:
+  created_at:   2026-07-06T09:06:45-07:00
+  activated_at: 2026-07-06T09:14:45-07:00
+  planned_at:   2026-07-06T09:35:50-07:00
+  finished_at:  2026-07-06T12:20:54-07:00
+  updated_at:   2026-07-06T12:20:54-07:00
+-->
+
+# Story: Rework Style Analysis Scoring as a Weighted Rubric
+
+## Summary
+
+AS a curriculum author scoring student exercises (in the sibling `bardtheory` project)
+
+I WANT the `Style::Analysis` fitness score to behave like a graded rubric — where the rules that define an exercise dominate the grade, and the score does not swing with the length of the line
+
+SO THAT an otherwise-perfect melody that ignores the assigned brief (e.g. the wrong contour for a contour guide) earns a low grade, and two proportionally-equal submissions of different lengths earn the same grade
+
+## Background
+
+The scalar returned by `HeadMusic::Style::Analysis#fitness` is being adopted by the `bardtheory` curriculum as the **grade on a learning exercise**. That semantic — a grade, not an aesthetic judgment — is what drives every decision below.
+
+Two problems surfaced in the melody contour guides, and they turn out to be **orthogonal**:
+
+1. **Single-rule failures are diluted.** A melody that satisfies every rule except the assigned contour scores ~96%. Measured empirically on a 5-note descending line analyzed under `ArchContourMelody`: overall fitness `0.9607`, with the only failing annotation being `Contoured` at `0.618`.
+
+2. **Scores are volatile with line length.** Rules that emit one penalty mark per offending note compound multiplicatively, so a proportionally-equal violation costs far more on a long line than a short one.
+
+### Why #1 happens
+
+`Analysis#fitness` is an **unweighted geometric mean** over every rule in the guide's `RULESET`:
+
+```ruby
+# lib/head_music/style/analysis.rb:25
+fitness_scores.reduce(:*)**(1.0 / fitness_scores.length)
+```
+
+`ArchContourMelody` has 12 rules. One failing rule at the golden penalty (`PENALTY_FACTOR = GOLDEN_RATIO_INVERSE ≈ 0.618`) is diluted by the `1/12` exponent:
+
+```
+0.618 ^ (1/12) = 0.9607
+```
+
+The contour is not ignored — it is one binary rule competing with eleven others, and the geometric mean's exponent compresses any single failure toward 1.0.
+
+A related, arguably worse defect of the same exponent: **a rule's failure is diluted by however many other rules happen to sit in the guide.** Wrong contour scores `0.618^(1/12) = 0.96` in a 12-rule guide but `0.618^(1/8) = 0.94` in an 8-rule guide. Adding an unrelated rule to a guide makes every existing rule more forgiving.
+
+### Why #2 happens
+
+An annotation's fitness is the **product** of its marks' fitnesses (`annotation.rb:59`), and guidelines built with `Mark.for_each` emit one mark per offending note. A rule broken on 2 notes scores `0.618² = 0.38`; the same 20%-violation rate on a 30-note line breaks ~6 notes and scores `0.618⁶ = 0.056`. Same proportional badness, wildly different score, purely because the line is longer. Note that `Contoured` itself is length-invariant (it emits a single `Mark.for_all`), which confirms the two problems are independent.
+
+## Target behavior
+
+- An otherwise-perfect melody with the **wrong contour** for its guide should grade **under 70%** — ideally **exactly 61.8%** (`GOLDEN_RATIO_INVERSE`).
+- Two submissions with the **same proportional adherence** but different lengths should grade the **same** (within the tolerance of genuinely length-dependent musical facts, e.g. contour minimum-length guards).
+
+## Design decisions (agreed)
+
+These were settled during design discussion; they are the spec, not open questions.
+
+- **Aggregator: weighted _arithmetic_ mean at the top level**, replacing the geometric mean. Weights are rubric point values. Rationale: the score is a *grade*, and grades are additive point rubrics. A weighted arithmetic mean expresses "contour is worth N points of the exercise" directly and legibly, and — critically for a teaching tool — produces a grade breakdown a student can be shown ("you lost 38 of your 100 points on contour"). The geometric mean's floor for a single dominant failure is its own penalty value (`≈61.8%`), which is unreachable-from-below and requires absurd weights (~30–100× everything else) to approach; the arithmetic mean hits any target with legible weights.
+
+- **Golden-ratio rubric split (Design B).** Using the identity `φ⁻¹ + φ⁻² = 1` (`0.618 + 0.382 = 1`): weight the defining rule (contour) at `φ⁻¹ ≈ 61.8%` of the rubric and everything else at `φ⁻² ≈ 38.2%`, and have the contour rule score `φ⁻² = 0.382` (not zero) on failure. A wrong contour on an otherwise-perfect line then scores `0.618·0.382 + 0.382·1 = 0.618` — exactly the golden target. This keeps the golden penalty *inside* the rule (0.382 is itself a golden value) and makes "not a zero" true at both the rule and overall level. The contour weight is a **configurable default** (defaults to `φ⁻¹`), overridable per guide — the golden value is the chosen default, not a hardcoded constraint.
+
+- **Rate-normalize each rule's fitness** so a rule reports a *rate* of adherence, not a *count* of violations. This makes each rule's score length-invariant at the source, which (with fixed weights) makes the overall grade length-invariant by construction. This is the fix for problem #2 and is independent of the aggregator choice.
+
+- **Weights live at guideline-default + guide-level override.** A guideline declares a sensible default weight (its intrinsic importance); a guide's `RULESET` entry may override it for that context (via the existing `Annotation.with(...)` composition mechanism). This honors "the same rule matters differently in different guides" (contour dominates a contour guide) without re-encoding shared judgments in every ruleset and letting them drift.
+
+- **Keep the golden multiplicative penalty _inside_ each rule.** `Mark#fitness`, `PENALTY_FACTOR`, and per-mark composition stay as-is at the rule level. Only the **top-level** fuser in `Analysis#fitness` changes from geometric to weighted-arithmetic. The multiplicative world is preserved where it already lives.
+
+- **Contour is not a gate.** A wrong-contour line is not disqualified (0%); a student who wrote a musically excellent line that missed the brief demonstrated real skill and should grade ~61.8%, not zero. Under Design B "not a zero" holds even at the rule level (the contour rule bottoms out at `φ⁻²`, not 0). Contour is the highest-weighted *rubric* line item — a quality judgment, not a qualification.
+
+- **Gate tier (qualification to be assessed).** Separate from quality, some rules answer "is there a gradable attempt here at all?" — their failure means *nothing to assess*, not *assessed poorly*. These compose **multiplicatively in front of the rubric**:
+
+  ```
+  fitness = ∏(gate fitnesses) × weighted_arithmetic_mean(rubric rules)
+  ```
+
+  This restores the hard-zero for genuinely disqualifying failures (an empty line → 0) that the arithmetic mean would otherwise delete — *without* zeroing quality failures like contour. Verified regression this fixes: an empty melody under the plain weighted mean scores **0.9653** (every rule vacuously passes at 1.0 except the lone low-weight `MinimumNotes`), where it must be 0. Gates are **graded multipliers**, not binary: an empty line → `MinimumNotes` = 0 → ×0; a line 4-of-5 notes → ×0.8 (mild haircut); a sufficient line → ×1 (no effect). Gates are pulled **out** of the rubric mean (no double-count), so rubric peer weights are computed over the non-gate rules.
+
+- **Gate set (v1): sufficiency thresholds only.** `MinimumNotes`, and a new `MinimumMelodicIntervals` where appropriate — both check "is there enough of an attempt to grade?", never quality. Gate-ness is a **per-guide option** (`SomeRule.with(gate: true)`, defaulting per-guideline), applied "when appropriate" — a rule may gate in one guide and be absent or rubric in another. Broader gate candidates are deferred to a follow-up audit.
+
+- **Soft floor for broken (but real) work.** For a submission that *passes the gates* (a real attempt) but scores badly on the rubric, the arithmetic mean deliberately stops failures from cascading to zero: it floors around 0.4–0.5, not near 0, because rate-normalized rules bottom out near `φ⁻¹` and the mean averages them. This is the intended consequence of grade semantics (partial credit) — a real-but-flawed attempt is not a literal 0%, while a non-attempt (gate failure) still is.
+
+## Acceptance Criteria
+
+- `Analysis#fitness` computes `∏(gate fitnesses) × weighted_arithmetic_mean(rubric rules)` — gates multiply in front; rubric rules are a weight-normalized arithmetic mean.
+- Annotations expose a `weight` (per-guideline default, overridable via `Annotation.with(...)`) and a `gate?` predicate (per-guideline default, overridable via `.with(gate: …)`). Both defaults are configurable, not hardcoded magic numbers.
+- Gates are pulled out of the rubric mean; rubric peer weights are computed over the non-gate rules so the contour share stays exactly `φ⁻¹`.
+- In the contour guides, the `Contoured` rule carries weight `φ⁻¹` of the rubric (≈61.8%) by default; the remaining rubric rules split `φ⁻²` (≈38.2%). On a wrong contour the contour rule scores `φ⁻²` (0.382), not zero.
+- An otherwise-perfect melody with the wrong contour grades at 61.8% (± rounding); definitely under 70%.
+- Rule fitnesses are rate-normalized: two lines with the same proportional violation rate but different lengths produce the same rule fitness (and the same overall grade).
+- A wrong contour is **not** a zero, at either the rule level (`φ⁻²`) or the overall grade (~0.618).
+- **A non-attempt is a zero.** An empty line (and, where a `MinimumMelodicIntervals` gate applies, a line without enough melodic motion) grades 0 via the gate multiplier. A line just short of a sufficiency threshold takes a proportional haircut (e.g. 4-of-5 notes → ×0.8), not a cliff.
+- `MinimumNotes` is a gate (graded multiplier); a `MinimumMelodicIntervals` gate exists and is wired into guides where appropriate.
+- `adherent?` means every rule is adherent (a fully-correct submission still grades 1.0).
+- Existing guide specs are updated to the new scoring; a perfect submission remains 1.0; a real-but-fully-broken submission (passing the gates) grades ~0.4–0.5 (soft floor, intended); a non-attempt grades 0.
+
+## Scenario: Wrong contour grades in the low 60s
+
+Given an otherwise well-formed diatonic melody whose shape does not match the assigned contour
+
+When it is analyzed under a contour guide (e.g. `ArchContourMelody`)
+
+Then the overall fitness is 61.8% (± rounding), and in all cases under 70%
+
+And the failing `Contoured` annotation is the dominant contributor to the lost credit
+
+## Scenario: Grade is length-invariant
+
+Given two melodies that violate the same rule at the same proportional rate (e.g. 20% of notes), one short and one long
+
+When each is analyzed under the same guide
+
+Then both receive the same fitness for that rule, and the same overall grade
+
+## Scenario: A rule's weight is contextual to the guide
+
+Given a guideline that is defining in one guide and incidental in another
+
+When the same guideline appears in two different `RULESET`s with different weights
+
+Then each guide grades that rule according to its own weight, without changing the guideline class
+
+## Scenario: A wrong contour is not a zero
+
+Given a musically excellent melody with the wrong contour
+
+When it is analyzed under a contour guide
+
+Then the grade is low-but-nonzero (≈61.8%), reflecting the quality of the line while penalizing the missed brief
+
+## Scenario: A perfect submission still grades 100%
+
+Given a melody that satisfies every rule in its guide
+
+When it is analyzed
+
+Then `fitness` is 1.0 and `adherent?` is true
+
+## Scenario: A non-attempt grades zero (gate)
+
+Given an empty voice (no notes), or — where a `MinimumMelodicIntervals` gate applies — a line with insufficient melodic motion
+
+When it is analyzed under a guide whose sufficiency rule is a gate
+
+Then the gate fitness is 0, the gate multiplier drives the overall grade to 0
+
+And this holds regardless of how many other rules vacuously pass
+
+## Scenario: Falling just short of a sufficiency threshold takes a haircut, not a cliff
+
+Given a melody with 4 notes under a guide requiring a minimum of 5 (`MinimumNotes.with(5, gate: true)`)
+
+When it is analyzed
+
+Then the gate contributes a graded multiplier (`4/5 = 0.8`), scaling the rubric grade down proportionally rather than to zero
+
+## Open questions (resolved during planning)
+
+- **Contour arrangement → resolved: Design B.** Contour weight defaults to `φ⁻¹` (≈61.8%); the contour rule scores `φ⁻²` (0.382) on failure. Both land the wrong-contour case on exactly 61.8% while keeping "not a zero" true at the rule level. (Design A — weight `φ⁻²`, rule → 0 — was rejected because it forces a raw zero and contradicts "golden penalty inside the rule.")
+- **Literal constants vs. configurable → resolved: configurable, defaulting to golden.** The contour weight is a per-guideline default that happens to default to `φ⁻¹`; guides may override it. The golden value is the chosen default, not a hardcoded constraint.
+- **Broken-line floor → resolved: accept the soft floor.** A real (gate-passing) but fully-broken melody grades ~0.4–0.5, not near 0. This is the intended consequence of the arithmetic mean and grade semantics.
+- **Gate tier → resolved: needed, and narrow.** A qualification-to-be-assessed tier multiplies in front of the rubric (`∏ gate × rubric`). Gates are graded multipliers, not binary. The v1 gate set is sufficiency-only — `MinimumNotes` plus a new `MinimumMelodicIntervals` — wired per guide "when appropriate." Contour is explicitly *not* a gate (it is a rubric quality item). This restores correct 0-for-non-attempt behavior that the arithmetic mean would otherwise lose (empty line was scoring 0.9653).
+- **Opportunities denominator → default `notes.length` where a rule scales with length; genuinely rule-specific otherwise.** For this story only `diatonic` and `maximum_notes` (the length-scaling rules that appear in contour guides) override `fitness_denominator`; the other `for_each` rules are deferred to a bounded follow-up.
+- **Defining rule in non-contour guides → deferred.** Non-contour guides stay flat (all weights default to 1.0) for this story; promoting a defining rule (e.g. `Diatonic` in strict species) is a follow-up.
+- **Structured grade-breakdown object for `bardtheory` → deferred.** The weighted terms make it cheap to add later (likely a small `Rubric` object); out of scope for v1, which delivers only the scalar.
+- **Migration blast radius → measured.** ~81 spec files under `spec/head_music/style/` reference `fitness`/`adherent`/`messages`; most assertions are range-based and survive. See the migration step in the plan.
+
+## Notes
+
+- Empirical baseline reproduced during design: a 5-note C-major descending line (`G4 F4 E4 D4 C4`) under `ArchContourMelody` → `fitness 0.9607`, 12 annotations, only `Contoured` failing at `0.618`.
+- Relevant files: `lib/head_music/style/analysis.rb`, `lib/head_music/style/annotation.rb`, `lib/head_music/style/mark.rb`, `lib/head_music/style/guidelines/contoured.rb`, `lib/head_music/style/guides/*contour_melody.rb`, `lib/head_music.rb` (golden constants).
+
+## Implementation Plan
+
+### Overview
+
+Convert `HeadMusic::Style::Analysis#fitness` to `∏(gate fitnesses) × weight-normalized arithmetic mean of the rubric rules`; give `Annotation` a per-guideline default `weight` and a `gate?` predicate, both overridable through the existing `Annotation.with(...)` / `Configured` factory; and make length-scaling rules report an **adherence rate** via an overridable `fitness_denominator`. Contour guides weight `Contoured` at `φ⁻¹` (0.618, a configurable default) with rubric peers sharing `φ⁻²` (0.382); the contour rule fails to `φ⁻²` (0.382, not zero). `MinimumNotes` (and a new `MinimumMelodicIntervals`, where appropriate) become gates. Behavioral change only — no data model, persistence, or migrations.
+
+**Crux resolved (Design B):** wrong-contour on an otherwise-perfect line = `0.618·0.382 + 0.382·1.0 = 0.618` exactly (gates pass, ×1). Perfect = `1.0`. Empty line = `0` (gate ×0). The contour rule bottoms out at `φ⁻²`, so "not a zero" holds at the rule and overall level; a non-attempt is still 0 via the gate.
+
+**Gate regression this fixes (verified):** without the gate tier, an empty melody scores **0.9653** under the plain weighted mean — every rule vacuously passes at 1.0 except the lone low-weight `MinimumNotes` at 0. The old geometric mean hid this (one 0 zeros the product); the arithmetic mean deletes that implicit gate, so the gate tier is mandatory, not optional.
+
+### Steps
+
+1. **Characterization test first — lock the baseline before changing anything.**
+   - Assert the *current* `Analysis.new(ArchContourMelody, voice).fitness` for a 5-note descending line ≈ `0.9607`. Run green, then update/remove after the change lands (documents the reproduced baseline).
+   - Files: `spec/head_music/style/guides/arch_contour_melody_spec.rb`
+
+2. **Add `weight` and `gate?` to `Annotation`.**
+   - Add `DEFAULT_WEIGHT = 1.0` and `def self.default_weight = DEFAULT_WEIGHT` (subclasses override).
+   - Add `def weight = options.fetch(:weight, self.class.default_weight)` (reads the existing protected `options`, `annotation.rb:92`). Do **not** add a parallel options hash — `weight`/`gate` share the `@options` bag with domain config like `contour:`.
+   - Add `def self.default_gate? = false` and `def gate? = options.fetch(:gate, self.class.default_gate?)`, so gate-ness is a per-guideline default overridable per guide (`SomeRule.with(gate: true)`).
+   - `Annotation.with(**options)` (line 33) already accepts arbitrary keys, so `SomeGuideline.with(weight: w, gate: true)` works for bare classes unchanged.
+   - Add `Configured#with(**more)` → `Configured.new(guideline_class, options.merge(more))` so an already-configured entry (e.g. `MinimumNotes.with(5)`) can take a weight/gate override without dropping prior options. `Configured#new(voice)` already splats `**options`, so `:weight`/`:gate` flow through automatically.
+   - Files: `lib/head_music/style/annotation.rb`
+
+3. **Fix `Contoured.with` signature and set its golden default weight + penalty.**
+   - Change `self.with(contour_key)` → `self.with(contour_key, **options)`, calling `super(contour: contour, **options)` (the positional-only signature is why `weight:` can't currently reach this rule).
+   - Add `def self.default_weight = HeadMusic::GOLDEN_RATIO_INVERSE` (φ⁻¹ ≈ 0.618). Prefer a named constant (e.g. `DEFAULT_WEIGHT = HeadMusic::GOLDEN_RATIO_INVERSE`) so the default is legible and overridable.
+   - Files: `lib/head_music/style/guidelines/contoured.rb`
+
+4. **Contour rule fails to `φ⁻²`, not zero (the crux, Design B).**
+   - Change `Mark.for_all(notes)` → `Mark.for_all(notes, fitness: HeadMusic::GOLDEN_RATIO_INVERSE**2)` (0.382), using the same explicit-`fitness:` mechanism 6 guidelines already use. `Mark#fitness`, `PENALTY_FACTOR`, and per-mark composition are untouched at the framework level; the golden penalty stays inside the rule.
+   - Files: `lib/head_music/style/guidelines/contoured.rb`
+
+5. **Rate-normalize `Annotation#fitness` via an overridable denominator — NOT a blanket nth-root.**
+   - A global geometric mean over `marks.length` is a no-op for `for_all` rules (1 mark) and *double-penalizes* the 6 rules that already hand-roll a rate (`PENALTY_FACTOR**exponent`). Give the *rule* ownership of its opportunity count:
+     ```ruby
+     def fitness
+       mark_fitnesses = [marks].flatten.compact.map(&:fitness)
+       return 1.0 if mark_fitnesses.empty?
+       mark_fitnesses.reduce(1, :*)**(1.0 / fitness_denominator)
+     end
+
+     def fitness_denominator = 1
+     ```
+   - Default `1` leaves every `for_all` gestalt rule (Contoured, MostlyConjunct, …) and the 6 custom-`fitness:` rules **exactly as today**. Override `fitness_denominator` only on rules whose penalty genuinely scales with line length → `PENALTY^(k/n)`, length-invariant for a fixed rate `k/n`. Guard so the denominator is never `< 1`.
+   - Files: `lib/head_music/style/annotation.rb`
+
+6. **Override `fitness_denominator` on the two length-scaling rules in contour guides — defer the rest.**
+   - The 10 `for_each` guidelines: `diatonic`, `maximum_notes`, `no_rests`, `no_rests_after_note`, `notes_same_length`, `one_to_one`, `one_to_one_with_ties`, `consonant_climax`, `singable_range`, `avoid_overlapping_voices`. For this story override only the two that scale with length **and** appear in contour guides:
+     - `diatonic.rb`: `def fitness_denominator = notes.length` (out-of-key notes / total — clean rate demonstrator).
+     - `maximum_notes.rb`: `def fitness_denominator = notes.length` (overage notes / total).
+   - Leave harmony-only `for_each` rules and all `for_all` rules for a bounded follow-up. `consonant_climax`/`singable_range`/`avoid_overlapping_voices` already emit 1–2 marks with severity in an explicit `fitness:` and are already near length-invariant — do not touch.
+   - Files: `lib/head_music/style/guidelines/diatonic.rb`, `lib/head_music/style/guidelines/maximum_notes.rb`
+
+7. **Rewrite `Analysis#fitness` as gate-multiplier × weighted arithmetic mean, and harden `adherent?`.**
+   ```ruby
+   def fitness
+     return 1.0 if annotations.empty?
+     @fitness ||= gate_factor * rubric_fitness
+   end
+
+   def adherent?
+     annotations.all?(&:adherent?)
+   end
+
+   private
+
+   def gate_factor
+     gates.map(&:fitness).reduce(1, :*)   # multiplicative, graded (0 disqualifies)
+   end
+
+   def rubric_fitness
+     rubric = annotations.reject(&:gate?)
+     total_weight = rubric.sum(&:weight)
+     return 1.0 if rubric.empty? || total_weight.zero?
+     rubric.sum { |a| a.weight * a.fitness } / total_weight
+   end
+
+   def gates
+     annotations.select(&:gate?)
+   end
+   ```
+   - Gates multiply in front; the rubric is the weight-normalized arithmetic mean of the **non-gate** rules. `all?(&:adherent?)` (gates + rubric) is order-independent and decouples "is it perfect?" from float summation. `@fitness ||=` is safe (`0.0` is truthy). Empty-annotations, no-rubric-rules, and all-zero-weight edges short-circuit sensibly.
+   - Verified landings under this formula: empty line → `0`; wrong-contour otherwise-perfect → `0.618`; perfect → `1.0`.
+   - Files: `lib/head_music/style/analysis.rb`
+
+8. **Designate the sufficiency gates.**
+   - Make `MinimumNotes` a gate by default: `def self.default_gate? = true`. Its existing `marks` already returns fitness `0` (empty) or `notes.length / minimum` (short) — exactly the graded multiplier we want; no change to its scoring logic.
+   - Add a new `MinimumMelodicIntervals` guideline mirroring `MinimumNotes` (`.with(n)`, `default_gate? = true`), counting melodic intervals (`melodic_intervals` / adjacent note-pairs) against a minimum, with the same graded-deficiency mark (`count / minimum`, `0` when none). This is a sufficiency check ("enough melodic motion to assess"), distinct from `always_move` (which flags each static pair as a quality issue).
+   - Wire gates per guide "when appropriate" — `MinimumNotes` is already in `DiatonicMelody`/CF rulesets, so it becomes a gate there automatically; add `MinimumMelodicIntervals.with(n)` only to guides that need it. Do **not** blanket-add it.
+   - Because gates are pulled out of the rubric mean (step 7), `MinimumNotes` no longer contributes a rubric weight — so the contour weighting in step 9 must divide `φ⁻²` across the **non-gate** peers only.
+   - Files: `lib/head_music/style/guidelines/minimum_notes.rb`, new `lib/head_music/style/guidelines/minimum_melodic_intervals.rb` (+ `require` in `lib/head_music.rb`), spec for the new guideline.
+
+9. **Weight the six contour guide RULESETs over the non-gate (rubric) peers (Design B).**
+   ```ruby
+   PEERS = HeadMusic::Style::Guides::DiatonicMelody::RULESET
+   RUBRIC_PEERS = PEERS.reject { |rule| gate_rule?(rule) } # exclude MinimumNotes gate
+   PEER_WEIGHT = (HeadMusic::GOLDEN_RATIO_INVERSE**2) / RUBRIC_PEERS.length
+   RULESET = [
+     *PEERS.map { |rule| gate_rule?(rule) ? rule : rule.with(weight: PEER_WEIGHT) },
+     HeadMusic::Style::Guidelines::Contoured.with(:arch) # weight defaults to φ⁻¹
+   ].freeze
+   ```
+   - `DiatonicMelody::RULESET` has **11 peers** (verified); `MinimumNotes` is now a gate, leaving **10 rubric peers** → `PEER_WEIGHT = φ⁻²/10`. Rubric peers share `φ⁻²` total; `Contoured` carries `φ⁻¹`. Because `φ⁻¹+φ⁻²=1` the weighted mean lands on `0.618` for a wrong contour with gates passing. (Determining `gate_rule?` at ruleset-build time: expose a class-level gate check, or filter on the guideline class — the gate default lives on the class, `MinimumNotes.default_gate? == true`.)
+   - `.map` returns a new array, so the shared `DiatonicMelody::RULESET` is not mutated. `rule.with(weight:)` works for both bare classes (→ `Annotation.with`) and already-`Configured` entries (→ new `Configured#with` merge). `Contoured.with(:arch, weight: …)` can override per guide if ever desired.
+   - Files: `lib/head_music/style/guides/{arch,valley,wave,ascending,descending,static}_contour_melody.rb`
+
+10. **Regenerate spec expectations, then `bundle exec rubocop -a` and `bundle exec rspec`.** (Migration detail below.)
+
+### Testing Strategy
+
+- **Characterization baseline** (step 1): capture `0.9607` before the change; update after.
+- **The five story scenarios**, in `spec/head_music/style/guides/*_contour_melody_spec.rb` (create if missing):
+  1. Otherwise-perfect line, wrong contour → `be_within(1e-6).of(HeadMusic::GOLDEN_RATIO_INVERSE)` **and** `be < 0.70`.
+  2. Length-invariance → two melodies (prefer `HeadMusic::Notation::ABC.parse` per project memory) with the same proportional Diatonic violation rate at different lengths → equal overall fitness.
+  3. Perfect submission → `eq 1.0`, `adherent?` true.
+  4. Real-but-fully-broken (passes gates) → `be_between(0.3, 0.55)` (soft floor: substantially below perfect, not near 0).
+  5. Contextual weight override → `Klass.with(weight: 2.0).new(voice).weight == 2.0`; default reads `default_weight`; `MinimumNotes.with(5).with(weight: 0.1)` still enforces minimum 5.
+  6. Non-attempt (gate) → empty voice → `fitness == 0` and `adherent?` false; assert the empty-line regression (would be ~0.9653 without gates) is now 0.
+  7. Sufficiency haircut → 4-of-5 notes under `MinimumNotes.with(5, gate: true)` → gate multiplier 0.8, overall = `0.8 × rubric` (not 0, not full).
+- **Gate specs**: `MinimumNotes#gate?` true by default and overridable (`.with(5, gate: false)`); new `MinimumMelodicIntervals` gate — sufficient motion → adherent, too little → graded deficiency, none → 0.
+- **Rule-level rate spec** on `Diatonic`: 1-of-5 and 2-of-10 out-of-key → both `PENALTY^0.2`.
+- **Rule-level penalty spec** on `Contoured`: a wrong-contour line → annotation fitness `eq HeadMusic::GOLDEN_RATIO_INVERSE**2` (0.382).
+- **Exact-`eq` assertions that must change:**
+  - `spec/head_music/style/guidelines/contoured_spec.rb` (the `eq PENALTY_FACTOR` rule-level cases) → change to `eq HeadMusic::GOLDEN_RATIO_INVERSE**2` (Contoured now fails to 0.382).
+  - `spec/head_music/style/guidelines/diatonic_spec.rb`, `maximum_notes_spec.rb`: single-violation `eq PENALTY_FACTOR` cases → recompute to `PENALTY^(1/n)` per fixture.
+- **Assertions that must stay green (do not edit):** the many `eq PENALTY_FACTOR` / `eq SMALL_PENALTY_FACTOR` assertions in `for_all` guideline specs (large_leaps, singable_intervals, suspension_treatment, etc.) are unaffected (denominator 1). `analysis_spec.rb` adherent cases (`eq 1.0`) should still pass — verify.
+- **Migration of the ~81 spec files:** most assertions are range-based (`be_between`, `be <`) and survive. Process: (1) `grep -rn "its(:fitness)\|\.fitness).to\|adherent" spec/head_music/style/` and classify each as range (spot-check), exact-on-`for_all` (unaffected), exact-on-Contoured/overridden-`for_each` (regenerate), or guide-level (regenerate); (2) write a throwaway script in the scratchpad that instantiates each affected guide/fixture and prints the actual new fitness — source expected constants from it rather than hand-computing; do **not** check it in; (3) batch edits by guide, running `bundle exec rspec spec/head_music/style/guides` and `.../guidelines` per directory to localize failures.
+
+### Risks & Sequencing
+
+- **Land order to keep the suite green:** steps 2 → 3 → 4 → 5 → 7 (framework: weight + gate + gate-multiplier fitness + rate hook + Contoured penalty) as one coherent change, then 6 (rate overrides), then 8 (designate gates + `MinimumMelodicIntervals`), then 9 (contour weights over rubric peers), then 10 (spec migration). Run the full suite after 7 and again after 9.
+- **[Resolved by the gate tier] Veto-to-zero semantics.** The old geometric mean zeroed the whole grade on any single `0`-fitness rule; the arithmetic mean would delete that (empty line → 0.9653). The gate tier restores it *for sufficiency rules only* (`MinimumNotes`, `MinimumMelodicIntervals`). **Audit remaining `fitness: 0` paths** to confirm none *other* than sufficiency needs veto power — grep the guidelines for `fitness: 0`; if a non-sufficiency rule genuinely must disqualify, mark it a gate too. Do not assume the two known gates are exhaustive.
+- **[bardtheory coordination — highest] Every grade shifts numerically.** Breaking change for the downstream consumer. Repo is at 14.0.0 → bump **major** and document the fitness-scale change (and the new 0-for-non-attempt behavior) in the changelog. Any consumer pinning expected fitness values will break.
+- **Global aggregator change.** `Analysis#fitness` is global, so *every* guide moves from geometric to gate-multiplier × weighted-arithmetic mean (non-contour rubric rules default to weight 1.0 → equal-weight arithmetic mean). Direction is the same but magnitudes differ across all 26 guides — the ~81 specs are the safety net; do not skip a full-suite run.
+- **Gate-ness at ruleset-build time.** Step 9 needs to know which RULESET entries are gates *before* instances exist, to compute rubric peer weight. Keep the gate default on the guideline class (`self.default_gate?`) so a class/`Configured` entry can be classified without a voice. A per-entry `.with(gate: true)` override that flips a normally-rubric rule to a gate in one guide would not be visible to that build-time filter — if that case ever arises, compute peer weights from the `Configured` options, not just the class.
+- **Edge cases to add explicitly:** empty melody (→ 0), single-note melody, a line with all-repeated notes (0 melodic motion — the `MinimumMelodicIntervals` case), and a guide where multiple rubric rules fail simultaneously (confirm graceful degradation, not collapse).
+- **Process note:** the product-manager specialist stalled during planning and returned no output; scope/edge-case items were reasoned directly and folded in. Treat the scope boundary and deferred items (grade-breakdown object, non-contour defining rules, remaining `for_each` rate overrides) as recommendations to confirm, not vetted PM decisions.
+
+## Review
+
+Reviewed 2026-07-06 at commit `041590e` (diff vs merge-base `15399a4` with `main`; working tree clean, all changes committed and pushed). Reviewers: product-manager (acceptance criteria) and code-reviewer (quality/conventions) agents. Full style suite at review time: 1038 examples, 0 failures; full suite 5206 examples, 0 failures.
+
+### Acceptance criteria
+
+- ✅ **Gate × weighted-mean aggregator** — `analysis.rb:25-51`: `fitness = gate_factor * rubric_fitness`; gates multiply in front, rubric is the weight-normalized arithmetic mean of non-gate annotations. Empty-annotations, empty-rubric, and zero-total-weight edges guarded.
+- ✅ **`weight` / `gate?` with configurable defaults** — `annotation.rb`: `DEFAULT_WEIGHT`/`default_weight`, `default_gate?`, instance readers via the options bag; `Configured#with` merges without dropping prior options. Spec'd both directions (defaults and overrides).
+- ✅ **Gates excluded from rubric weights** — `diatonic_melody.rb` `contour_ruleset` partitions by `default_gate?`; arch spec asserts exactly 10 rubric peers at φ⁻²/10 and no mutation of the shared `RULESET`.
+- ✅ **Contoured at φ⁻¹, fails to φ⁻²** — `contoured.rb`: `DEFAULT_WEIGHT = GOLDEN_RATIO_INVERSE`, failure marks carry `fitness: GOLDEN_RATIO_INVERSE**2`; six contoured_spec failure cases updated to `eq φ⁻²`.
+- ✅ **Wrong contour grades 61.8%, under 70%** — measured `0.6180339887498949` (φ⁻¹ to float epsilon); spec asserts `be_within(1e-6)` and `be < 0.70`, plus Contoured as dominant lost-credit contributor.
+- ✅ **Rate normalization** — `fitness_denominator` hook (default 1, clamped ≥ 1); `Diatonic` and `MaximumNotes` override with `notes.length`. Rule-level invariance spec'd (1-of-5 ≡ 2-of-10) and guide-level (8 vs 16 notes, equal grade within 1e-6). Other `for_each` rules deferred per the story's resolved scope.
+- ✅ **Wrong contour not a zero** — rule level φ⁻² and overall ≈0.618, both asserted.
+- ✅ **Non-attempt is a zero; near-miss is a haircut** — empty voice → `fitness eq 0.0`; all-repeated line → motion gate 0; 4-of-5 notes → overall = 0.8 × rubric mean (within 1e-9), not a cliff.
+- ✅ **Gates wired** — `MinimumNotes.default_gate?` true (scoring unchanged); new `MinimumMelodicIntervals` (counts moving, non-unison intervals) gated into arch/valley/wave (min 2) and ascending/descending (min 1); static deliberately omits it (all-repeated line is legitimate static) with an explaining comment.
+- ✅ **`adherent?` = all rules adherent** — `analysis.rb:31-33`; spec'd both directions; perfect submission still `fitness eq 1.0` and adherent.
+- ✅ **Spec migration** — all six contour guide specs updated; perfect = 1.0; gate-passing broken line grades 0.4918 within the asserted (0.3, 0.55) soft floor; non-attempt 0. Breaking-change bookkeeping done: version 15.0.0, CHANGELOG entry with downstream-recalibration warning.
+
+### Code review findings
+
+No blockers, no should-fix items. The math was verified exact (golden identity holds to float epsilon; peer weight computed dynamically so the identity survives peer-count changes), `@fitness ||=` memoization of `0.0` is safe (floats are truthy), `weight:`/`gate:` cannot collide with any existing domain option key, and load order for the new guideline is correct. Nits (optional follow-ups):
+
+1. **[Fixed post-review]** Inline `gate:`/`weight:` keywords were unsupported on the positional `.with` factories — the scenario prose writes `MinimumNotes.with(5, gate: true)`, but `MinimumNotes`/`MaximumNotes`/`MinimumMelodicIntervals` had positional-only `.with(n)`; overrides only worked via chaining. Fixed by adding a `**options` passthrough to all three factories (matching `Contoured.with`), with inline-override specs on each. Suite re-run green (5209 examples, 0 failures).
+2. **`Configured#default_gate?` naming** — returns the *effective* gate flag (honors per-entry `gate:` override), not strictly the class default; the comment explains the intent, so readability-only.
+3. Empty `## [Unreleased]` section sits above `[15.0.0]` in CHANGELOG.md — keepachangelog-conventional, harmless.
+
+### Verdict
+
+Nothing blocks `finish`. Deferred items (grade-breakdown object, non-contour defining rules, remaining `for_each` rate overrides, broader gate audit) remain open by design.
+
+## Learnings
+
+- **Settling design decisions in the story paid off.** Every open question (aggregator choice, Design B, gate tier, soft floor, denominator scope) was resolved before implementation, so four implementation agents executed the plan with essentially zero deviation or rework. The one plan estimate that was wrong (interim characterization value 0.9485) was wrong for an interesting reason — Contoured's `default_weight` took effect the moment it was defined, before any guide wiring — and the plan's "verify empirically, trust the measurement" instruction absorbed it without drama.
+- **Empirical anchors beat hand-computed expectations.** The characterization-test-first step, the pre-verified regression number (empty line → 0.9653 under a plain weighted mean), and the instruction to source spec constants from actual runs kept every numeric assertion honest. The golden identity landed exact: wrong-contour fitness measured φ⁻¹ to 1e-15.
+- **The migration blast radius was ~20× smaller than feared.** ~81 spec files referenced fitness; only 4 examples actually broke, because most existing assertions were range-based (`be_between`, `be <`). Range assertions on emergent scores are the resilient choice; exact `eq` belongs only on identity-level values (rule penalties, perfect = 1.0).
+- **Changing an aggregator deletes implicit behavior — hunt for it.** The geometric mean's product gave every zero-fitness rule silent veto power; the arithmetic mean deleted that. Identifying the regression *before* coding (empty line would grade 0.9653) is what produced the gate tier, the story's most important architectural addition.
+- **Documented syntax must be executable.** The review caught that the story prose wrote `MinimumNotes.with(5, gate: true)` while the factories were positional-only. With a downstream consumer (`bardtheory`) likely to copy examples verbatim, aligning signatures with prose was worth the immediate follow-up fix.
+- **Process**: parallel agents on disjoint file sets (rate overrides ∥ gate guideline) worked cleanly; the framework-first land order kept the suite nearly green throughout. The product-manager stall during planning was successfully compensated by folding scope reasoning into the plan directly.

data/user-stories/index.html

@@ -258,10 +258,6 @@
       "title": "LilyPond Interpreter",
       "path": "backlog/lilypond-interpreter.md"
     },
-    {
-      "title": "Organizing Content",
-      "path": "backlog/organizing-content.md"
-    },
     {
       "title": "Sixteenth-Century (Renaissance) Style Guides",
       "path": "backlog/sixteenth-century-style.md"
@@ -269,10 +265,18 @@
     {
       "title": "Split Counterpoint Species Guides by Pedagogical Author",
       "path": "backlog/split-counterpoint-species-by-author.md"
+    },
+    {
+      "title": "organizing-content",
+      "path": "backlog/organizing-content.md"
     }
   ],
   "active": [],
   "done": [
+    {
+      "title": "Rework Style Analysis Scoring as a Weighted Rubric",
+      "path": "done/scoring-architecture.md"
+    },
     {
       "title": "Melody Contour Guides",
       "path": "done/melody-contour-guides.md"
@@ -313,18 +317,10 @@
       "title": "Instrument Inheritance Architecture",
       "path": "done/instrument-architecture.md"
     },
-    {
-      "title": "Instrument Variant Refactoring",
-      "path": "done/instrument-variant.md"
-    },
     {
       "title": "Instruments can have strings with pitches",
       "path": "done/string-pitches.md"
     },
-    {
-      "title": "Load Playing Techniques from YAML Data File",
-      "path": "done/expand-playing-techniques.md"
-    },
     {
       "title": "Move MusicalSymbol to Notation Module",
       "path": "done/move-musical-symbol-to-notation.md"
@@ -362,7 +358,15 @@
       "path": "done/sonority-identification.md"
     },
     {
-      "title": "Superclass for Note",
+      "title": "expand-playing-techniques",
+      "path": "done/expand-playing-techniques.md"
+    },
+    {
+      "title": "instrument-variant",
+      "path": "done/instrument-variant.md"
+    },
+    {
+      "title": "superclass-for-note",
       "path": "done/superclass-for-note.md"
     }
   ]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: head_music
 version: !ruby/object:Gem::Version
-  version: 14.0.0
+  version: 15.0.0
 platform: ruby
 authors:
 - Rob Head
@@ -305,6 +305,7 @@ files:
 - lib/head_music/style/guidelines/large_leaps.rb
 - lib/head_music/style/guidelines/limit_octave_leaps.rb
 - lib/head_music/style/guidelines/maximum_notes.rb
+- lib/head_music/style/guidelines/minimum_melodic_intervals.rb
 - lib/head_music/style/guidelines/minimum_notes.rb
 - lib/head_music/style/guidelines/mixed_rhythmic_values.rb
 - lib/head_music/style/guidelines/moderate_direction_changes.rb
@@ -414,6 +415,7 @@ files:
 - user-stories/done/notation-style.md
 - user-stories/done/percussion_set.md
 - user-stories/done/pitch-class-set-analysis.md
+- user-stories/done/scoring-architecture.md
 - user-stories/done/sonority-identification.md
 - user-stories/done/string-pitches.md
 - user-stories/done/superclass-for-note.md