head_music 12.2.0 → 12.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ccf523b5bb7b74f26a5d52696e46d227428c97279c9218642a0fda8277c845a0
-  data.tar.gz: 9dacc76d972594748d14b5fad8e479b551c758c9ef7882f88354a28e62d316b3
+  metadata.gz: 20155b40b92a030588ea4b1c791efcc37c70aa40e5e2008b0d3a282cb72391a1
+  data.tar.gz: e717940c964c2859dcf7181a5ae7997f99cabaf741f6d5ab73dc374977ae2f3f
 SHA512:
-  metadata.gz: be9bb15716c3f20d398bb1ba6f3d1faebe08233c271dd3e451da41f2654d7d3a9b3d6272a551c7f4214c28638962712bbb8b4eda412782c86204fd5a9c1eeb29
-  data.tar.gz: 7285191b3b8be97a2d9cad0f2a650eb7f7e708723047c42d7ea5a80fdc77cc0f303e34727e6d827f40f598d3b735f67353e33b722f4e50877b41214b7d1a6b76
+  metadata.gz: 9b97712e65e7ecb1df4dc400854aedfb1ed9fbf0654fdda348dc72d552c6e3f061eaa1dec9b02034d867c7279fe1ad5a6305dd9724cf4c47f8389463486f1f4b
+  data.tar.gz: c3bd7b7c5bc5ea85790a7e15998eb25f9a32e6a249ffcbea26b4e420fdde5fad236e8e2ebf7a844405414e97a1104792f8ad0aae85862ed11712aa1103794490

data/Gemfile.lock

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

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

@@ -0,0 +1,27 @@
+# Module for style guidelines.
+module HeadMusic::Style::Guidelines; end
+
+# A counterpoint guideline
+class HeadMusic::Style::Guidelines::NoParallelPerfectWithSyncopation < HeadMusic::Style::Annotation
+  MESSAGE = "Avoid parallel perfect consonances between syncopated notes."
+
+  def marks
+    parallel_perfect_syncopation_pairs.map do |pair|
+      HeadMusic::Style::Mark.for_all(pair.flat_map(&:notes))
+    end
+  end
+
+  private
+
+  def parallel_perfect_syncopation_pairs
+    harmonic_intervals.each_cons(2).select do |first, second|
+      first.perfect_consonance?(:two_part_harmony) &&
+        second.perfect_consonance?(:two_part_harmony) &&
+        same_simple_type?(first, second)
+    end
+  end
+
+  def same_simple_type?(first, second)
+    first.simple_number == second.simple_number
+  end
+end

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

@@ -0,0 +1,27 @@
+# Module for style guidelines.
+module HeadMusic::Style::Guidelines; end
+
+# A counterpoint guideline for fourth species counterpoint.
+# For each cantus firmus note, verifies that one or two counterpoint notes
+# are sounding at that position. A note may sustain across the barline
+# (syncopation) rather than starting at the CF note position.
+# Two notes sounding against one CF note is permitted as a "second species break."
+class HeadMusic::Style::Guidelines::OneToOneWithTies < HeadMusic::Style::Annotation
+  MESSAGE = "Place one note per cantus firmus note. Notes may sustain across the barline."
+
+  def marks
+    return unless cantus_firmus&.notes
+    return if cantus_firmus.notes.empty?
+
+    HeadMusic::Style::Mark.for_each(uncovered_cantus_firmus_notes)
+  end
+
+  private
+
+  def uncovered_cantus_firmus_notes
+    cantus_firmus.notes.select do |cf_note|
+      notes_sounding = voice.notes_during(cf_note)
+      notes_sounding.empty? || notes_sounding.length > 2
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# Module for style guidelines.
+module HeadMusic::Style::Guidelines; end
+
+# A counterpoint guideline for fourth species counterpoint.
+# The syncopated texture is occasionally broken: the counterpoint moves on the
+# downbeat instead of sustaining. When this happens, a dissonant off-beat note
+# is permitted only if it is a passing tone. Breaks should be infrequent.
+class HeadMusic::Style::Guidelines::SecondSpeciesBreak < HeadMusic::Style::Guidelines::WeakBeatDissonanceTreatment
+  MESSAGE = "Use only passing tones when breaking the syncopated texture. Breaks should be infrequent."
+
+  MAX_BREAK_RATIO = 0.25
+
+  def marks
+    return [] unless cantus_firmus&.notes&.any?
+
+    dissonance_marks + frequency_marks
+  end
+
+  private
+
+  def dissonance_marks
+    break_bar_off_beat_notes
+      .select { |note| dissonant_with_cantus?(note) }
+      .reject { |note| passing_tone?(note) }
+      .map { |note| HeadMusic::Style::Mark.for(note) }
+  end
+
+  def frequency_marks
+    return [] if total_bars <= 0
+    return [] if break_bars.length <= total_bars * MAX_BREAK_RATIO
+
+    break_bar_notes = break_bars.flat_map { |bar| notes_in_bar(bar) }
+    [HeadMusic::Style::Mark.for_all(break_bar_notes, fitness: HeadMusic::SMALL_PENALTY_FACTOR)]
+  end
+
+  def break_bars
+    @break_bars ||= (first_bar..last_bar).select { |bar| break_bar?(bar) }
+  end
+
+  def break_bar?(bar)
+    downbeats, off_beats = notes_in_bar(bar).partition { |note| downbeat_position?(note.position) }
+    downbeats.any? && off_beats.any?
+  end
+
+  def break_bar_off_beat_notes
+    break_bars.flat_map { |bar| notes_in_bar(bar).reject { |note| downbeat_position?(note.position) } }
+  end
+
+  def notes_in_bar(bar)
+    notes.select { |note| note.position.bar_number == bar }
+  end
+
+  def total_bars
+    last_bar - first_bar + 1
+  end
+
+  def first_bar
+    cantus_firmus.notes.first.position.bar_number
+  end
+
+  def last_bar
+    cantus_firmus.notes.last.position.bar_number
+  end
+end

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

@@ -0,0 +1,65 @@
+# Module for style guidelines.
+module HeadMusic::Style::Guidelines; end
+
+# A counterpoint guideline for fourth species suspension treatment.
+# A suspension has three parts:
+# 1. Preparation: The note is consonant with the current cantus firmus note.
+# 2. Suspension: The cantus firmus moves; the counterpoint sustains, becoming dissonant.
+# 3. Resolution: The counterpoint resolves by step (usually down) to a consonance.
+class HeadMusic::Style::Guidelines::SuspensionTreatment < HeadMusic::Style::Annotation
+  MESSAGE = "Treat suspensions with proper preparation and stepwise resolution."
+
+  def marks
+    return [] unless cantus_firmus&.notes&.any?
+
+    improperly_treated_suspensions.map do |note|
+      HeadMusic::Style::Mark.for(note)
+    end
+  end
+
+  private
+
+  def improperly_treated_suspensions
+    dissonant_suspensions.reject { |note, cf_note| properly_treated?(note, cf_note) }.map(&:first)
+  end
+
+  def dissonant_suspensions
+    cantus_firmus.notes[1..].filter_map do |cf_note|
+      cp_note = voice.note_at(cf_note.position)
+      next unless cp_note && cp_note.position < cf_note.position
+
+      interval = HeadMusic::Analysis::HarmonicInterval.new(cantus_firmus, voice, cf_note.position)
+      next unless interval.notes.length == 2 && interval.dissonance?(:two_part_harmony)
+
+      [cp_note, cf_note]
+    end
+  end
+
+  def properly_treated?(cp_note, cf_note)
+    prepared?(cp_note, cf_note) && resolved?(cp_note, cf_note)
+  end
+
+  def prepared?(cp_note, cf_note)
+    prev_cf = previous_cf_note(cf_note)
+    return false unless prev_cf
+
+    interval = HeadMusic::Analysis::HarmonicInterval.new(cantus_firmus, voice, cp_note.position)
+    interval.notes.length == 2 && interval.consonance?(:two_part_harmony)
+  end
+
+  def resolved?(cp_note, cf_note)
+    next_cp = voice.note_following(cp_note.position)
+    return false unless next_cp
+
+    melodic = HeadMusic::Analysis::MelodicInterval.new(cp_note, next_cp)
+    return false unless melodic.step?
+
+    resolution_interval = HeadMusic::Analysis::HarmonicInterval.new(cantus_firmus, voice, next_cp.position)
+    resolution_interval.notes.length == 2 && resolution_interval.consonance?(:two_part_harmony)
+  end
+
+  def previous_cf_note(cf_note)
+    index = cantus_firmus.notes.index(cf_note)
+    cantus_firmus.notes[index - 1] if index && index > 0
+  end
+end

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

@@ -15,14 +15,7 @@ class HeadMusic::Style::Guidelines::ThirdSpeciesDissonanceTreatment < HeadMusic:
 
   # Neighbor tone: approached by step, left by step in the opposite direction.
   def neighbor_tone?(note)
-    prev = preceding_note(note)
-    foll = following_note(note)
-    return false unless prev && foll
-
-    approach = melodic_interval_between(prev, note)
-    departure = melodic_interval_between(note, foll)
-
-    approach.step? && departure.step? && approach.direction != departure.direction
+    stepwise_figure?(note, same_direction: false)
   end
 
   # Nota cambiata: a five-note figure where note 2 is dissonant,

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

@@ -32,7 +32,7 @@ class HeadMusic::Style::Guidelines::WeakBeatDissonanceTreatment < HeadMusic::Sty
   end
 
   def cantus_firmus_positions
-    @cantus_firmus_positions ||= Set.new(cantus_firmus.notes.map { |n| n.position.to_s })
+    @cantus_firmus_positions ||= Set.new(cantus_firmus.notes.map { |note| note.position.to_s })
   end
 
   def dissonant_with_cantus?(note)
@@ -41,18 +41,26 @@ class HeadMusic::Style::Guidelines::WeakBeatDissonanceTreatment < HeadMusic::Sty
   end
 
   def passing_tone?(note)
-    prev = preceding_note(note)
-    foll = following_note(note)
-    return false unless prev && foll
+    stepwise_figure?(note, same_direction: true)
+  end
 
-    approach = melodic_interval_between(prev, note)
-    departure = melodic_interval_between(note, foll)
+  def stepwise_figure?(note, same_direction:)
+    surrounding = surrounding_notes(note)
+    return false unless surrounding
 
-    approach.step? && departure.step? && approach.direction == departure.direction
+    approach = melodic_interval_between(surrounding.first, note)
+    departure = melodic_interval_between(note, surrounding.last)
+    approach.step? && departure.step? && (approach.direction == departure.direction) == same_direction
+  end
+
+  def surrounding_notes(note)
+    prev = preceding_note(note)
+    foll = following_note(note)
+    [prev, foll] if prev && foll
   end
 
-  def melodic_interval_between(note1, note2)
-    HeadMusic::Analysis::MelodicInterval.new(note1, note2)
+  def melodic_interval_between(first_note, second_note)
+    HeadMusic::Analysis::MelodicInterval.new(first_note, second_note)
   end
 
   def preceding_note(note)

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

@@ -0,0 +1,16 @@
+# Rules for fourth species harmony
+class HeadMusic::Style::Guides::FourthSpeciesHarmony < HeadMusic::Style::Guides::SpeciesHarmony
+  RULESET = [
+    HeadMusic::Style::Guidelines::ApproachPerfectionContrarily,
+    HeadMusic::Style::Guidelines::AvoidCrossingVoices,
+    HeadMusic::Style::Guidelines::AvoidOverlappingVoices,
+    HeadMusic::Style::Guidelines::ConsonantDownbeats,
+    HeadMusic::Style::Guidelines::NoParallelPerfectOnDownbeats,
+    HeadMusic::Style::Guidelines::NoParallelPerfectWithSyncopation,
+    HeadMusic::Style::Guidelines::NoStrongBeatUnisons,
+    HeadMusic::Style::Guidelines::PreferContraryMotion,
+    HeadMusic::Style::Guidelines::PreferImperfect,
+    HeadMusic::Style::Guidelines::SecondSpeciesBreak,
+    HeadMusic::Style::Guidelines::SuspensionTreatment
+  ].freeze
+end

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

@@ -0,0 +1,23 @@
+# Module for guides
+module HeadMusic::Style::Guides; end
+
+# Rules for fourth species melodies
+class HeadMusic::Style::Guides::FourthSpeciesMelody < HeadMusic::Style::Guides::SpeciesMelody
+  RULESET = [
+    HeadMusic::Style::Guidelines::AlwaysMove,
+    HeadMusic::Style::Guidelines::ConsonantClimax,
+    HeadMusic::Style::Guidelines::Diatonic,
+    HeadMusic::Style::Guidelines::EndOnTonic,
+    HeadMusic::Style::Guidelines::NoteFillsFinalBar,
+    HeadMusic::Style::Guidelines::FrequentDirectionChanges,
+    HeadMusic::Style::Guidelines::LimitOctaveLeaps,
+    HeadMusic::Style::Guidelines::MostlyConjunct,
+    HeadMusic::Style::Guidelines::OneToOneWithTies,
+    HeadMusic::Style::Guidelines::PrepareOctaveLeaps,
+    HeadMusic::Style::Guidelines::SingableIntervals,
+    HeadMusic::Style::Guidelines::SingableRange,
+    HeadMusic::Style::Guidelines::StartOnPerfectConsonance,
+    HeadMusic::Style::Guidelines::StepOutOfUnison,
+    HeadMusic::Style::Guidelines::StepUpToFinalNote
+  ].freeze
+end

data/lib/head_music/version.rb

@@ -1,3 +1,3 @@
 module HeadMusic
-  VERSION = "12.2.0"
+  VERSION = "12.3.0"
 end

data/lib/head_music.rb

@@ -176,10 +176,12 @@ require "head_music/style/guidelines/mostly_conjunct"
 require "head_music/style/guidelines/notes_same_length"
 require "head_music/style/guidelines/no_parallel_perfect_across_barline"
 require "head_music/style/guidelines/no_parallel_perfect_on_downbeats"
+require "head_music/style/guidelines/no_parallel_perfect_with_syncopation"
 require "head_music/style/guidelines/no_rests"
 require "head_music/style/guidelines/no_strong_beat_unisons"
 require "head_music/style/guidelines/no_unisons_in_middle"
 require "head_music/style/guidelines/one_to_one"
+require "head_music/style/guidelines/one_to_one_with_ties"
 require "head_music/style/guidelines/prefer_contrary_motion"
 require "head_music/style/guidelines/prefer_imperfect"
 require "head_music/style/guidelines/prepare_octave_leaps"
@@ -194,12 +196,14 @@ require "head_music/style/guidelines/step_down_to_final_note"
 require "head_music/style/guidelines/step_out_of_unison"
 require "head_music/style/guidelines/step_to_final_note"
 require "head_music/style/guidelines/step_up_to_final_note"
+require "head_music/style/guidelines/suspension_treatment"
 require "head_music/style/guidelines/three_per_bar"
 require "head_music/style/guidelines/two_per_bar"
 require "head_music/style/guidelines/up_to_fourteen_notes"
 require "head_music/style/guidelines/weak_beat_dissonance_treatment"
 require "head_music/style/guidelines/third_species_dissonance_treatment"
 require "head_music/style/guidelines/triple_meter_dissonance_treatment"
+require "head_music/style/guidelines/second_species_break"
 
 # style guides
 require "head_music/style/guides/species_melody"
@@ -214,3 +218,5 @@ require "head_music/style/guides/third_species_triple_meter_melody"
 require "head_music/style/guides/third_species_triple_meter_harmony"
 require "head_music/style/guides/third_species_melody"
 require "head_music/style/guides/third_species_harmony"
+require "head_music/style/guides/fourth_species_melody"
+require "head_music/style/guides/fourth_species_harmony"

data/references/fourth-species-counterpoint.md

@@ -0,0 +1,251 @@
+# Fourth-Species Counterpoint: Developer Reference
+
+A concise reference for implementing fourth-species counterpoint guidelines in the `head_music` gem. Covers pedagogical foundations, music theory rules, and architectural mapping.
+
+---
+
+## 1. Historical Context
+
+### Fux (1725)
+
+Johann Joseph Fux's *Gradus ad Parnassum* establishes the species framework that remains canonical. Fourth species introduces the **suspension**: the counterpoint voice ties across the barline, causing the previously consonant pitch to become dissonant against the cantus firmus on the downbeat, then resolving by step downward on the upbeat. Fux treats suspensions as the defining idiom of Renaissance vocal counterpoint.
+
+### Schenker (1910/1922)
+
+Schenker reframes fourth species as a study in **voice-leading prolongation**. The suspension is not merely an ornament but a structural event: the tied note delays (prolongs) the resolution, creating tension that drives forward motion. He emphasizes the three-phase structure (preparation, suspension, resolution) as fundamental to understanding tonal prolongation at all structural levels.
+
+### Contemporary Pedagogy (Salzer & Schachter, Schubert, OMT)
+
+Modern treatments preserve the Fuxian suspension taxonomy while clarifying edge cases: when ties break (the "second species break"), how to handle the final cadence, and the treatment of the 2-3 suspension in the bass. Open Music Theory and Schubert's *Modal Counterpoint* both codify the rule that when the syncopated texture is interrupted, the off-beat note reverts to second-species behavior and may be a dissonant passing tone.
+
+---
+
+## 2. The Syncopated Texture
+
+Fourth species is built on **rhythmic syncopation**: notes begin on the weak beat of one bar and sustain through the downbeat of the next.
+
+In 4/4 or cut time (the typical cantus firmus meter):
+
+```
+Beat:     1         2         3         4
+CF:       o---------                    (whole note)
+CPT:                o---------o---------
+                    ^weak     ^weak
+                    preparation         resolution
+                              ^strong
+                              suspension (may be dissonant)
+```
+
+The **sounding duration** is what matters for analysis. A pitch that begins on beat 3 and sustains through beat 1 of the next bar is sounding on that downbeat regardless of how it is notated. See section 6 on notation.
+
+---
+
+## 3. Suspension Types
+
+Suspensions are named by the interval sequence: **dissonant interval on the downbeat -- resolved interval on the upbeat**.
+
+### Upper Voice Suspensions (counterpoint above cantus firmus)
+
+| Name | Suspension | Resolution | Notes |
+|------|-----------|------------|-------|
+| 7-6  | 7th (dissonant) | 6th | Most common; smooth resolution to imperfect consonance |
+| 4-3  | 4th (dissonant) | 3rd | The 4th is dissonant in two-voice counterpoint |
+| 9-8  | 9th (dissonant) | Octave | Resolves to perfect consonance; use with care |
+| 2-1  | 2nd (dissonant) | Unison | Rare; treated as a form of 9-8 at the octave |
+
+### Lower Voice Suspensions (counterpoint below cantus firmus)
+
+| Name | Suspension | Resolution | Notes |
+|------|-----------|------------|-------|
+| 2-3  | 2nd (dissonant) | 3rd | The "bass suspension"; resolution moves downward by step |
+| 4-5  | 4th (dissonant) | 5th | Less common than 2-3 |
+| 9-10 | 9th (dissonant) | 10th (3rd) | Compound form of 2-3 |
+
+**Key constraint for all suspensions:** The resolution must move **by step downward** (in the resolving voice) from the suspended pitch. Upward resolution is not permitted in strict species counterpoint.
+
+---
+
+## 4. Suspension Structure: Preparation, Suspension, Resolution
+
+Every suspension consists of three phases:
+
+1. **Preparation** -- The pitch to be suspended is heard on a **weak beat** as a **consonance** with the cantus firmus. This establishes the pitch as stable before it becomes dissonant.
+
+2. **Suspension** -- The same pitch is held (or re-articulated as tied) into the **strong beat** (downbeat) of the next bar, where it is now **dissonant** with the cantus firmus.
+
+3. **Resolution** -- On the following **weak beat**, the suspended pitch moves **by step downward** to a consonance.
+
+```
+Phase:    PREPARATION     SUSPENSION     RESOLUTION
+Beat:     weak            strong         weak
+Harmony:  consonant       dissonant      consonant
+Motion:   (arrival)       (sustained)    step down
+```
+
+### Preparation Requirements
+
+- The preparation must be a consonance (not a dissonance, not a rest).
+- The preparation pitch and the suspended pitch are the same pitch -- this is the defining feature of a suspension (vs. an appoggiatura, which arrives unprepared).
+- In head_music terms: the `Placement` on the weak beat must produce a consonant `HarmonicInterval` with the cantus firmus at that position.
+
+### Resolution Requirements
+
+- Resolution is **always** by **step downward** in the voice containing the suspension.
+- Resolution arrives on a **consonance** with the cantus firmus.
+- The cantus firmus does not move during the suspension (it is a whole note): the resolution step belongs to the counterpoint voice alone.
+
+---
+
+## 5. The "Second Species Break"
+
+The syncopated texture is sometimes interrupted -- the tie does not occur and the voice articulates a new pitch on the weak beat without sustaining into the next downbeat. This moment is called a **second species break** (some sources call it a "cambiata" context or simply describe it as reverting to second-species behavior).
+
+**Rule:** When the texture breaks and the off-beat note does not tie into the next downbeat, that off-beat note may be a **dissonant passing tone**, subject to the same conditions as second species:
+- Approached by step.
+- Left by step **in the same direction**.
+- The dissonance falls on the weak beat only.
+
+This is the only context in fourth species where a dissonance may appear without being a suspension. The break allows the voice to redirect melodically when a suspension would produce forbidden parallels or other violations.
+
+**Implementation note:** Detecting a second species break requires knowing whether a `Placement` at a weak beat position ties into the next downbeat. If `placement.next_position` falls on a downbeat and `voice.note_at(next_downbeat)` returns a different pitch (or no pitch), the tie has broken.
+
+---
+
+## 6. Notation-Agnostic Analysis Principle
+
+**Ties are a display concern only.** For analytical purposes, a pitch that sounds continuously from position A to position B is a single sounding event, regardless of how many notated note heads or tie symbols represent it.
+
+These two notations are analytically identical in fourth species:
+
+- A whole note C4 beginning at beat 3 of bar 1, sustained through beat 1 of bar 2.
+- A half note C4 at beat 3 of bar 1, tied to a half note C4 at beat 1 of bar 2.
+
+**Guidelines operate on sounding durations, not on notated note heads.**
+
+In head_music, this principle is already encoded in the data model:
+
+- A `Placement` represents a single sounding event with a `position` (when it starts) and a `rhythmic_value` (how long it lasts).
+- `Placement#next_position` computes when the sound ends: `position + rhythmic_value`.
+- The display layer (ties, beaming, notation symbols) is a separate concern handled by the `HeadMusic::Notation` module.
+
+Analytical guidelines should never count note heads or detect ties in the notated score. Instead, they should query `voice.note_at(position)` for any given position to determine what is sounding.
+
+---
+
+## 7. Mapping to head_music Architecture
+
+### Voice and Placement Model
+
+```
+Voice
+  #placements       -> [Placement, ...]   all sounding events (notes and rests)
+  #notes            -> [Placement, ...]   only pitched placements
+  #note_at(pos)     -> Placement | nil    what is sounding at a given Position
+  #note_preceding(pos) -> Placement | nil the note whose position is before pos
+  #note_following(pos) -> Placement | nil the note whose position is after pos
+
+Placement
+  #position         -> Position           when the event begins
+  #rhythmic_value   -> RhythmicValue      how long it lasts
+  #next_position    -> Position           position + rhythmic_value (when it ends)
+  #pitch            -> Pitch | nil        nil for rests
+  #note?            -> bool
+  #rest?            -> bool
+```
+
+### Position
+
+```
+Position
+  #within_placement?(placement) -> bool   true if self >= placement.position
+                                          AND self < placement.next_position
+  #strong?          -> bool               downbeat (strength >= 80)
+  #weak?            -> bool               not strong
+  #bar_number       -> Integer
+  #count            -> Integer            beat within bar
+```
+
+`Position#within_placement?` is the key predicate for "is this pitch sounding at this moment?" It returns true for any position that falls during the placement's duration -- including the middle of a long note. This is the mechanism that makes sustained notes invisible to position-based queries.
+
+### HarmonicInterval
+
+```
+HarmonicInterval.new(voice1, voice2, position)
+```
+
+Internally calls `voice.note_at(position)` for each voice. Because `note_at` uses `position.within_placement?`, it correctly finds notes that **began earlier and are still sounding**, not only notes that **start at** the given position.
+
+This means `HarmonicInterval` already handles sustained pitches correctly. A suspended note that began on beat 3 and is still sounding on beat 1 of the next bar will be found and evaluated as a harmonic interval at beat 1 without any special casing in the guideline code.
+
+### Identifying Suspension Phases in Guidelines
+
+To analyze a suspension at a given downbeat position:
+
+```ruby
+# The suspended note: sounding at the downbeat but started earlier
+suspended_note = counterpoint_voice.note_at(downbeat_position)
+
+# It is a suspension only if it started before the downbeat
+is_suspension = suspended_note && suspended_note.position < downbeat_position
+
+# Preparation: the same placement, evaluated at the previous weak beat
+# (suspended_note itself IS the preparation placement)
+preparation_harmonic_interval = HarmonicInterval.new(
+  cantus_firmus, counterpoint_voice, suspended_note.position
+)
+
+# Suspension: harmonic interval at the downbeat
+suspension_harmonic_interval = HarmonicInterval.new(
+  cantus_firmus, counterpoint_voice, downbeat_position
+)
+
+# Resolution: the note that follows the sustained note
+resolution_note = counterpoint_voice.note_following(downbeat_position)
+```
+
+### Guidelines: Annotation and Mark
+
+Guidelines inherit from `HeadMusic::Style::Annotation` and override the `marks` method, returning an array of `HeadMusic::Style::Mark` objects.
+
+```ruby
+class MyGuideline < HeadMusic::Style::Annotation
+  MESSAGE = "Description of the rule."
+
+  def marks
+    # Collect placements that violate the rule.
+    # Return Mark objects for each violation.
+    violating_placements.map do |placement|
+      HeadMusic::Style::Mark.for(placement, fitness: 0)
+    end
+  end
+end
+```
+
+`Mark.for(placement)` creates a mark spanning `placement.position` to `placement.next_position`. `Mark.for_all(placements)` creates a single mark spanning a group. `Mark.for_each(placements)` creates one mark per placement.
+
+Fitness of `0` signals a hard violation (forbidden). The default `HeadMusic::PENALTY_FACTOR` is used for soft violations (discouraged but not forbidden).
+
+### Guideline Classification for Fourth Species
+
+**Hard violations (fitness: 0):**
+- Suspension not prepared as a consonance (preparation must be consonant).
+- Suspension resolution not by step downward.
+- Suspension resolution not to a consonance.
+- Dissonance on a downbeat that is not a valid suspension.
+- Off-beat dissonance in a second-species break that is not a passing tone (approached and left by step in same direction).
+
+**Soft penalties (PENALTY_FACTOR):**
+- Failure to use suspensions where they are available (too many direct consonances reduces interest).
+- Resolution to a perfect consonance (prefer imperfect).
+- Parallel perfect consonances on successive downbeats.
+
+---
+
+## 8. Sources
+
+- Fux, J.J. *Gradus ad Parnassum* (1725). Trans. Alfred Mann, *The Study of Counterpoint* (W.W. Norton, 1965).
+- Schenker, H. *Kontrapunkt* (1910/1922). Trans. Rothgeb & Thym (Musicalia Press, 2001).
+- Salzer, F. & Schachter, C. *Counterpoint in Composition* (Columbia UP, 1969).
+- Schubert, P. *Modal Counterpoint: Renaissance Style*, 2nd ed. (Oxford UP, 2008).
+- [Open Music Theory -- Fourth-Species Counterpoint](https://viva.pressbooks.pub/openmusictheory/chapter/fourth-species-counterpoint/)
+- [Puget Sound Music Theory -- Fourth Species](https://musictheory.pugetsound.edu/mt21c/FourthSpecies.html)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: head_music
 version: !ruby/object:Gem::Version
-  version: 12.2.0
+  version: 12.3.0
 platform: ruby
 authors:
 - Rob Head
@@ -291,6 +291,7 @@ files:
 - lib/head_music/style/guidelines/mostly_conjunct.rb
 - lib/head_music/style/guidelines/no_parallel_perfect_across_barline.rb
 - lib/head_music/style/guidelines/no_parallel_perfect_on_downbeats.rb
+- lib/head_music/style/guidelines/no_parallel_perfect_with_syncopation.rb
 - lib/head_music/style/guidelines/no_rests.rb
 - lib/head_music/style/guidelines/no_strong_beat_unisons.rb
 - lib/head_music/style/guidelines/no_unisons_in_middle.rb
@@ -299,10 +300,12 @@ files:
 - lib/head_music/style/guidelines/notes_same_length.rb
 - lib/head_music/style/guidelines/one_per_bar.rb
 - lib/head_music/style/guidelines/one_to_one.rb
+- lib/head_music/style/guidelines/one_to_one_with_ties.rb
 - lib/head_music/style/guidelines/prefer_contrary_motion.rb
 - lib/head_music/style/guidelines/prefer_imperfect.rb
 - lib/head_music/style/guidelines/prepare_octave_leaps.rb
 - lib/head_music/style/guidelines/recover_large_leaps.rb
+- lib/head_music/style/guidelines/second_species_break.rb
 - lib/head_music/style/guidelines/singable_intervals.rb
 - lib/head_music/style/guidelines/singable_range.rb
 - lib/head_music/style/guidelines/single_large_leaps.rb
@@ -312,6 +315,7 @@ files:
 - lib/head_music/style/guidelines/step_out_of_unison.rb
 - lib/head_music/style/guidelines/step_to_final_note.rb
 - lib/head_music/style/guidelines/step_up_to_final_note.rb
+- lib/head_music/style/guidelines/suspension_treatment.rb
 - lib/head_music/style/guidelines/third_species_dissonance_treatment.rb
 - lib/head_music/style/guidelines/three_per_bar.rb
 - lib/head_music/style/guidelines/triple_meter_dissonance_treatment.rb
@@ -320,6 +324,8 @@ files:
 - lib/head_music/style/guidelines/weak_beat_dissonance_treatment.rb
 - lib/head_music/style/guides/first_species_harmony.rb
 - lib/head_music/style/guides/first_species_melody.rb
+- lib/head_music/style/guides/fourth_species_harmony.rb
+- lib/head_music/style/guides/fourth_species_melody.rb
 - lib/head_music/style/guides/fux_cantus_firmus.rb
 - lib/head_music/style/guides/modern_cantus_firmus.rb
 - lib/head_music/style/guides/second_species_harmony.rb
@@ -348,6 +354,7 @@ files:
 - lib/head_music/utilities/case.rb
 - lib/head_music/utilities/hash_key.rb
 - lib/head_music/version.rb
+- references/fourth-species-counterpoint.md
 - references/second-species-counterpoint.md
 - references/third-species-counterpoint.md
 - user_stories/backlog/notation-style.md