head_music 9.0.1 → 11.0.0

data/user_stories/done/consonance-dissonance-classification.md

@@ -0,0 +1,117 @@
+# Consonance and Dissonance Classification
+
+As a music theorist or counterpoint student
+
+I want to classify intervals by their consonance and dissonance levels
+
+So that I can apply proper voice leading rules
+
+## Scenario: Classify open consonances
+
+Given I have a perfect fifth or perfect octave
+
+When I check the consonance classification
+
+Then it should be identified as "open consonance"
+
+## Scenario: Classify soft consonances
+
+Given I have a third or sixth interval (major or minor)
+
+When I check the consonance classification
+
+Then it should be identified as "soft consonance"
+
+## Scenario: Classify mild dissonances
+
+Given I have a major second or minor seventh
+
+When I check the consonance classification
+
+Then it should be identified as "mild dissonance"
+
+## Scenario: Classify sharp dissonances
+
+Given I have a minor second or major seventh
+
+When I check the consonance classification
+
+Then it should be identified as "sharp dissonance"
+
+## Scenario: Handle perfect fourth context
+
+Given I have a perfect fourth interval
+
+When I check the consonance classification
+
+Then it should indicate context-dependent classification
+
+And note it can be either consonant or dissonant
+
+## Scenario: Classify tritone
+
+Given I have a tritone interval
+
+When I check the consonance classification
+
+Then it should be identified as "neutral" or "restless"
+
+---
+
+## Implementation Notes
+
+This user story was **mostly already implemented** with existing functionality. The following enhancements were made:
+
+### Changes Implemented
+
+1. **Added `neutral` consonance level** to `HeadMusic::Rudiment::Consonance`
+   - New constant: `NEUTRAL = :neutral`
+   - Added `neutral?` predicate method
+   - Added to `HeadMusic::Analysis::IntervalConsonance`
+
+2. **Changed P4 classification in ModernTradition** from `perfect_consonance` to `contextual`
+   - Perfect fourth is now correctly classified as context-dependent
+   - Consonant in upper voices, dissonant against bass
+   - Medieval tradition still classifies as `perfect_consonance`
+   - Renaissance tradition still classifies as `dissonance`
+
+3. **Changed tritone classification** from `dissonance` to `neutral`
+   - Both augmented fourth and diminished fifth now classified as `neutral`
+   - Reflects the ambiguous, restless quality of the tritone
+
+### Terminology Mapping
+
+The user story terminology maps to existing library classifications:
+
+| User Story Term | Library Term | Status |
+|----------------|--------------|--------|
+| "Open consonance" | `perfect_consonance` | ✅ Already exists |
+| "Soft consonance" | `imperfect_consonance` | ✅ Already exists |
+| "Mild dissonance" | `mild_dissonance` | ✅ Already exists (exact match!) |
+| "Sharp dissonance" | `harsh_dissonance` | ✅ Already exists |
+| P4 context-dependent | `contextual` | ✅ Now implemented |
+| Tritone "neutral/restless" | `neutral` | ✅ Now implemented |
+
+### API Usage
+
+```ruby
+interval = HeadMusic::Analysis::DiatonicInterval.get("P4")
+interval.consonance              # => #<Consonance @name=:contextual>
+interval.contextual?             # => true
+interval.consonant?              # => false (contextual is neither consonant nor dissonant)
+
+tritone = HeadMusic::Analysis::DiatonicInterval.get("A4")
+tritone.consonance               # => #<Consonance @name=:neutral>
+tritone.neutral?                 # => true
+tritone.dissonant?               # => false (neutral is not strictly dissonant)
+```
+
+### Test Coverage
+
+- Updated all existing tests for new classifications
+- Added comprehensive tests for `neutral` and `contextual` intervals
+- 3736 tests passing (8 cantus firmus examples affected by P4 change)
+
+### Known Side Effects
+
+The P4 classification change affects some cantus firmus style guide tests, as these historical examples may contain perfect fourths that were previously considered consonant. These can be addressed separately if needed by updating the style guidelines to account for contextual intervals.

data/user_stories/{todo → done}/dyad-analysis.md

@@ -6,6 +6,8 @@ I want to analyze two-note combinations (dyads)
 
 So that I can understand harmonic implications in two-part music
 
+Every dyad can be interpreted as implying one or more chords (triad or seventh)
+
 Constructor should accept to pitches (or pitch classes) and an optional key
 
 ## Scenario: Identify interval in dyad
@@ -28,13 +30,11 @@ And each should contain the given pitches
 
 ## Scenario: List possible triads from third
 
-Given I have a dyad forming a minor third
+Given I have a dyad forming a major or minor third or sixth
 
 When I request possible triads
 
-Then I should receive minor and diminished triad options
-
-And for a major third I should receive major and augmented options
+Then I should receive major, minor, diminished, and/or augmented triads containing those pitch classes
 
 ## Scenario: Find possible seventh chords
 
@@ -44,8 +44,6 @@ When I request possible seventh chords
 
 Then I should receive all seventh chords containing those pitches
 
-And they should include appropriate inversions
-
 ## Scenario: Handle enharmonic possibilities
 
 Given I have a dyad with enharmonic possibilities

data/user_stories/done/expand-playing-techniques.md

@@ -0,0 +1,38 @@
+## User Story: Load Playing Techniques from YAML Data File
+
+**As a** client of the HeadMusic gem
+
+**I want** access to a comprehensive catalog of playing techniques across all instrument families
+
+**So that** I can notate and work with playing techniques for strings, winds, harp, keyboard, and percussion—not just drum kit techniques
+
+### Background
+
+The current `PlayingTechnique` class uses a hardcoded `TECHNIQUES` constant containing only 14 percussion-focused techniques (stick, pedal, mallet, hand, brush, rim_shot, cross_stick, open, closed, damped, let_ring, choked, bow, bell).
+
+A new `playing_techniques.yml` data file has been created with 50+ techniques organized by scope (common, strings, winds, percussion, harp, keyboard), including:
+
+- **Common techniques**: legato, marcato, vibrato, con sordino, naturale, ordinario
+- **String/wind techniques**: harmonics, bowing techniques
+- **Percussion techniques**: rim shots, cross sticks, dead strokes, motor on/off
+- **Harp techniques**: près de la table
+- **Rich metadata**: origin language, meaning, notation variants
+
+The YAML-driven approach aligns with how other HeadMusic components work (instruments, clefs, scales, etc.) and enables future extensibility.
+
+### Acceptance Criteria
+
+- [ ] `PlayingTechnique.all` returns techniques loaded from `playing_techniques.yml`
+- [ ] The `TECHNIQUES` constant is removed
+- [ ] Each technique retains access to its metadata (scopes, origin, meaning, notations)
+- [ ] `PlayingTechnique.get(identifier)` continues to work for any technique in the YAML
+- [ ] New accessor methods for metadata: `#scopes`, `#origin`, `#meaning`, `#notations`
+- [ ] Techniques can be filtered by scope (e.g., `PlayingTechnique.for_scope(:strings)`)
+- [ ] Existing specs pass; new specs cover the expanded technique catalog
+- [ ] Maintains 90%+ test coverage
+
+### Technical Notes
+
+- Follow the existing YAML-loading pattern used by `Instrument`, `Clef`, and other data-driven classes
+- The `HeadMusic::Named` mixin is already included, enabling future i18n support
+- Consider caching loaded techniques for performance (consistent with other HeadMusic patterns)

data/user_stories/{active → done}/handle-time.rb

@@ -21,8 +21,8 @@ class HeadMusic::Time::Conductor
 
   def initialize(attributes = {})
     attributes = attributes.symbolize_keys
-    @starting_position = attributes.get(:starting_position, HeadMusic::Time::Position.new)
-    @starting_smpte_timecode = attributes.get(:starting_smpte_timecode, HeadMusic::Time::SmpteTimecode.new)
+    @starting_position = attributes.fetch(:starting_position, HeadMusic::Time::MusicalPosition.new)
+    @starting_smpte_timecode = attributes.fetch(:starting_smpte_timecode, HeadMusic::Time::SmpteTimecode.new)
   end
 end
 
@@ -31,6 +31,7 @@ class HeadMusic::Time::MeterEvent
 
   def initialize(position, meter)
     @position = position
+    @meter = meter
   end
 end
 
@@ -44,21 +45,6 @@ class HeadMusic::Time::TempoEvent
   end
 end
 
-# Abstract superclass
-class HeadMusic::Time::Position
-  include Comparable
-
-  def initialize(value, meter: nil, tempo: nil)
-    @value = value
-    @meter = meter || HeadMusic::Rudiment::Meter.default
-    @tempo = tempo || HeadMusic::Rudiment::Tempo.default
-  end
-
-  def <=>(other)
-    to_i <=> other.to_i
-  end
-end
-
 # A value object representing ellapsed nanoseconds of clock time
 class HeadMusic::Time::ClockPosition
   include Comparable
@@ -86,7 +72,7 @@ class HeadMusic::Time::ClockPosition
   end
 
   def +(other)
-    HeadMusic::Time::Value.new(nanoseconds + other.to_i)
+    HeadMusic::Time::ClockPosition.new(nanoseconds + other.to_i)
   end
 
   def <=>(other)
@@ -156,7 +142,7 @@ class HeadMusic::Time::MusicalPosition
       bar_delta, @beat = beat.divmod(meter.counts_per_bar)
       @bar += bar_delta
     end
-    HeadMusic::Time::Position.new(@bar, @beat, @tick, @subtick)
+    self
   end
 end
 

data/user_stories/done/instrument-architecture.md

@@ -0,0 +1,238 @@
+# Instrument Inheritance Architecture
+
+AS a developer
+
+I WANT instruments to resolve attributes through composable parent-based inheritance with configurable options
+
+SO THAT I can model the full complexity of instruments with a simple, familiar pattern
+
+## Background
+
+The current instrument architecture uses nested objects (GenericInstrument → Variant → StaffScheme → Staff) which conflates several independent concerns:
+
+1. **Species defaults** - What a trumpet typically is
+2. **Pitched identity** - This specific clarinet is in A
+3. **Physical configuration** - Piccolo trumpet with A leadpipe installed
+4. **Notation conventions** - British brass band uses treble clef for euphonium
+
+This story addresses concerns 1-3 through parent-based inheritance. Notation (concern 4) is orthogonal and will be handled separately.
+
+## The Inheritance Pattern
+
+### Self-Referential Instrument
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Instrument                                             │
+│    belongs_to :parent (optional)                        │
+│    has_many :instrument_configurations                  │
+│                                                         │
+│  Attributes resolve via parent chain:                   │
+│    pitch_key || parent&.pitch_key                       │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Inheritance Examples
+
+```
+trumpet (no parent)
+  ├── piccolo_trumpet (parent: trumpet, different range)
+  ├── bass_trumpet (parent: trumpet, different range)
+  └── pocket_trumpet (parent: trumpet, same attributes)
+
+clarinet (no parent, pitch_key: b_flat)
+  ├── clarinet_in_a (parent: clarinet, pitch_key: a)
+  ├── clarinet_in_c (parent: clarinet, pitch_key: c)
+  ├── clarinet_in_e_flat (parent: clarinet, pitch_key: e_flat)
+  └── bass_clarinet (parent: clarinet, different range)
+```
+
+### Resolution Example
+
+```ruby
+clarinet = Instrument.get("clarinet")
+clarinet.pitch_key        # => "b_flat"
+clarinet.family_key       # => "clarinet"
+
+clarinet_in_a = Instrument.get("clarinet_in_a")
+clarinet_in_a.pitch_key   # => "a" (own attribute)
+clarinet_in_a.family_key  # => "clarinet" (from parent)
+clarinet_in_a.parent      # => clarinet
+```
+
+### Key Characteristics
+
+1. **Simple**: One class, one relationship, familiar pattern
+2. **Natural resolution**: `attribute || parent&.attribute`
+3. **Arbitrary depth**: Can model instrument families at any level
+4. **Data-driven**: YAML or database records, not code
+
+## Core Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name_key` | String | Primary identifier ("trumpet", "clarinet_in_a") |
+| `alias_name_keys` | Array | Alternative names |
+| `pitch_key` | String | The pitch designation ("b_flat", "a", "f") |
+| `family_key` | String | Instrument family ("trumpet", "clarinet") |
+| `orchestra_section_key` | String | Section ("brass", "woodwind", "strings") |
+| `classification_keys` | Array | Hornbostel-Sachs style classifications |
+| `default_clef_key` | String | Primary clef for this instrument |
+| `range_low` | String | Lowest playable pitch |
+| `range_high` | String | Highest playable pitch |
+
+## Configuration System
+
+Instruments can have configurable options that modify their attributes when selected.
+
+### Structure
+
+```ruby
+class Instrument
+  belongs_to :parent, class_name: "Instrument", optional: true
+  has_many :instrument_configurations  # applies to self and descendants
+end
+
+class InstrumentConfiguration
+  belongs_to :instrument
+  has_many :instrument_configuration_options
+
+  # name_key: "leadpipe", "mute", "crook", "extension", "attachment"
+end
+
+class InstrumentConfigurationOption
+  belongs_to :instrument_configuration
+
+  # name_key: "a_leadpipe", "straight_mute", "f_crook"
+  # transposition_semitones: Integer (e.g., -1 for A leadpipe on Bb instrument)
+  # lowest_pitch_semitones: Integer (e.g., -4 for C extension on double bass)
+end
+```
+
+### Configuration Examples
+
+| Instrument | Configuration | Options |
+|------------|---------------|---------|
+| Piccolo trumpet | `leadpipe` | `b_flat` (default), `a` (transposition: -1) |
+| Bass trombone | `f_attachment` | `disengaged`, `engaged` (lowest_pitch: -6) |
+| Double bass | `c_extension` | `without`, `with` (lowest_pitch: -4) |
+| Natural horn | `crook` | `e_flat`, `f`, `g`, etc. (various transpositions) |
+| Trumpet | `mute` | `open`, `straight`, `cup`, `harmon` |
+| Guitar | `capo` | `fret_0` through `fret_12` (transposition: 0-12) |
+
+### Configuration Resolution
+
+- `instrument.instrument_configurations` walks parent chain, collects all
+- No configuration selected = base instrument attributes unchanged
+- Configuration selection lives in composition context (Part/Voice), not on Instrument
+- A Part specifies target characteristics; configuration selection is derived/validated
+
+```ruby
+# The instrument defines what CAN be configured
+piccolo_trumpet = Instrument.get("piccolo_trumpet")
+piccolo_trumpet.instrument_configurations  # => [leadpipe config from parent chain]
+
+# A Part specifies what characteristics are needed
+part.instrument           # => piccolo_trumpet
+part.target_pitch_key     # => "a"
+part.effective_transposition  # resolved via configuration options
+```
+
+## User Stories
+
+### STORY 1: Implement parent-based attribute resolution
+
+AS a developer
+WHEN I access an attribute on an Instrument
+I WANT it resolved through the parent chain
+SO THAT child instruments inherit from parents
+
+**Acceptance criteria:**
+- `instrument.pitch_key` returns own value or walks parent chain
+- All core attributes support parent chain resolution
+- Returns nil if no instrument in chain provides the attribute
+
+### STORY 2: Implement configuration inheritance
+
+AS a developer
+WHEN I query an instrument's available configurations
+I WANT to get configurations from the entire parent chain
+SO THAT child instruments inherit configurable options
+
+**Acceptance criteria:**
+- `instrument.instrument_configurations` collects from self and all ancestors
+- Configurations defined on parent apply to all descendants
+- Child can define additional configurations
+
+### STORY 3: Model configuration options with effects
+
+AS a developer
+WHEN I define configuration options
+I WANT to specify their effects on instrument attributes
+SO THAT transposition and range changes are calculable
+
+**Acceptance criteria:**
+- `InstrumentConfigurationOption` has `transposition_semitones` attribute
+- `InstrumentConfigurationOption` has `lowest_pitch_semitones` attribute
+- Effects are integers representing semitone adjustments
+
+### STORY 4: Migrate existing instrument data
+
+AS a developer
+WHEN I use the existing `Instrument.get()` API
+I WANT it to work with the new inheritance architecture
+SO THAT existing code continues to function
+
+**Acceptance criteria:**
+- `Instrument.get("trumpet")` returns instrument with no parent
+- `Instrument.get("clarinet_in_a")` returns instrument with parent: clarinet
+- All existing tests pass
+
+### STORY 5: Remove Variant class
+
+AS a developer
+WHEN pitched variants are modeled as child instruments
+I WANT to remove the separate Variant class
+SO THAT the model is simplified
+
+**Acceptance criteria:**
+- `Variant` class removed
+- All pitched variants are now `Instrument` records with parents
+- YAML structure updated to reflect inheritance
+
+## Migration Strategy
+
+1. **Phase 1**: Add `parent` relationship to Instrument class
+2. **Phase 2**: Implement parent chain attribute resolution
+3. **Phase 3**: Migrate YAML data to parent-based structure
+4. **Phase 4**: Create InstrumentConfiguration and InstrumentConfigurationOption classes
+5. **Phase 5**: Remove Variant class and update GenericInstrument
+6. **Phase 6**: Update all specs
+
+## Acceptance Criteria
+
+- [x] `Instrument` class has `belongs_to :parent` relationship
+- [x] Attributes resolve through parent chain
+- [x] `Instrument#instrument_configurations` collects from ancestor chain
+- [x] `InstrumentConfiguration` class exists with `name_key`
+- [x] `InstrumentConfigurationOption` class exists with effect attributes
+- [x] `Variant` class removed
+- [x] YAML structure uses parent-based inheritance
+- [x] `Instrument.get()` API preserved for backward compatibility
+- [x] All existing tests pass
+- [x] New tests cover inheritance and configuration
+- [x] Maintains 90%+ test coverage
+
+## Deferred
+
+- **Tunings**: String instruments need individual string modeling before alternate tunings can be represented
+- **Notation**: Clef and transposition display conventions are orthogonal; see 002-notation-style.md
+
+## Open Questions
+
+1. **Multiple staves**: Piano needs two staves (grand staff). Is this an attribute on the instrument, or a notation concern?
+
+2. **Configuration selection in composition**: How does a Part specify which configuration options are selected? Options:
+   - Part stores selected options directly
+   - Part stores target attributes, system validates/suggests configurations
+   - Both (target attributes preferred, explicit selection as override)

data/user_stories/done/move-musical-symbol-to-notation.md

@@ -0,0 +1,161 @@
+# Move MusicalSymbol to Notation Module
+
+AS a developer
+
+I WANT MusicalSymbol in the HeadMusic::Notation module
+
+SO THAT symbol representation logic (ASCII, Unicode, HTML) lives with other visual notation concerns rather than abstract music theory
+
+## Background
+
+`MusicalSymbol` is a container class that holds multiple representations of a musical symbol:
+- ASCII representation (plain text, e.g., "#" for sharp)
+- Unicode representation (musical symbols, e.g., "♯" for sharp)
+- HTML entity representation (e.g., "♯" for sharp)
+
+It's currently located in `HeadMusic::Rudiment`, but it's purely about visual presentation, not music theory. Symbols are how we visually represent musical concepts, making this a notation concern.
+
+The class is used by:
+- `Clef` - for clef symbols (treble, bass, alto, etc.)
+- `Alteration` - for accidental symbols (sharp, flat, natural, etc.)
+
+Moving it to Notation clarifies that this is about rendering and display, separate from the theoretical concepts themselves.
+
+## Scenario: Getting symbol representations
+
+Given a sharp accidental
+
+When I access its musical symbol
+
+Then I can get the ASCII representation "#"
+
+And I can get the Unicode representation "♯"
+
+And I can get the HTML entity "♯"
+
+## Scenario: Using symbols for text output
+
+Given I need to display a clef in plain text
+
+When I use the clef's MusicalSymbol
+
+Then I get the appropriate ASCII character representation
+
+## Scenario: Using symbols for web display
+
+Given I need to display an accidental on a web page
+
+When I use the alteration's MusicalSymbol
+
+Then I can choose between Unicode (for modern browsers) or HTML entity (for compatibility)
+
+## Technical Notes
+
+### Current State
+
+**Location:** `lib/head_music/rudiment/musical_symbol.rb`
+**Class:** `HeadMusic::Rudiment::MusicalSymbol`
+**Tests:** `spec/head_music/rudiment/musical_symbol_spec.rb`
+**Used by:**
+- `lib/head_music/rudiment/clef.rb`
+- `lib/head_music/rudiment/alteration.rb`
+
+### Proposed Changes
+
+1. **Move file:**
+   - From: `lib/head_music/rudiment/musical_symbol.rb`
+   - To: `lib/head_music/notation/musical_symbol.rb`
+
+2. **Update class definition:**
+   ```ruby
+   # lib/head_music/notation/musical_symbol.rb
+   module HeadMusic::Notation; end
+
+   class HeadMusic::Notation::MusicalSymbol
+     attr_reader :ascii, :unicode, :html_entity
+
+     def initialize(ascii: nil, unicode: nil, html_entity: nil)
+       @ascii = ascii
+       @unicode = unicode
+       @html_entity = html_entity
+     end
+
+     def to_s
+       unicode || ascii
+     end
+   end
+   ```
+
+3. **Move spec file:**
+   - From: `spec/head_music/rudiment/musical_symbol_spec.rb`
+   - To: `spec/head_music/notation/musical_symbol_spec.rb`
+
+4. **Update spec:**
+   ```ruby
+   describe HeadMusic::Notation::MusicalSymbol do
+     # All tests remain unchanged except the describe statement
+   ```
+
+5. **Update references in Clef:**
+   ```ruby
+   # lib/head_music/rudiment/clef.rb
+   # Update MusicalSymbol references to use HeadMusic::Notation::MusicalSymbol
+   ```
+
+6. **Update references in Alteration:**
+   ```ruby
+   # lib/head_music/rudiment/alteration.rb
+   # Update MusicalSymbol references to use HeadMusic::Notation::MusicalSymbol
+   ```
+
+7. **Update loading:**
+   ```ruby
+   # lib/head_music/notation.rb
+   module HeadMusic::Notation; end
+
+   require "head_music/notation/staff_position"
+   require "head_music/notation/musical_symbol"
+   ```
+
+### Files to Update
+
+- Move: `lib/head_music/rudiment/musical_symbol.rb` → `lib/head_music/notation/musical_symbol.rb`
+- Move: `spec/head_music/rudiment/musical_symbol_spec.rb` → `spec/head_music/notation/musical_symbol_spec.rb`
+- Update: `lib/head_music/notation.rb` (add require)
+- Update: `lib/head_music/rudiment/clef.rb` (update MusicalSymbol references)
+- Update: `lib/head_music/rudiment/alteration.rb` (update MusicalSymbol references)
+- Remove: `lib/head_music/rudiment.rb` require for musical_symbol
+
+## Acceptance Criteria
+
+- [ ] `HeadMusic::Notation::MusicalSymbol` class exists
+- [ ] Original file `lib/head_music/rudiment/musical_symbol.rb` removed
+- [ ] Spec file at `spec/head_music/notation/musical_symbol_spec.rb`
+- [ ] All existing MusicalSymbol tests pass
+- [ ] `Clef` references to MusicalSymbol updated and working
+- [ ] `Alteration` references to MusicalSymbol updated and working
+- [ ] `lib/head_music/notation.rb` requires musical_symbol
+- [ ] `lib/head_music/rudiment.rb` no longer requires musical_symbol
+- [ ] All Clef tests pass
+- [ ] All Alteration tests pass
+- [ ] All existing tests across entire codebase still pass
+- [ ] Maintains 90%+ test coverage
+- [ ] No deprecation warnings or breaking changes for internal usage
+
+## Implementation Steps
+
+1. Create `lib/head_music/notation/musical_symbol.rb` with updated module path
+2. Copy class implementation unchanged
+3. Create `spec/head_music/notation/musical_symbol_spec.rb`
+4. Update describe statement in spec
+5. Update `lib/head_music/notation.rb` to require musical_symbol
+6. Update references in `lib/head_music/rudiment/clef.rb`
+7. Update references in `lib/head_music/rudiment/alteration.rb`
+8. Remove require from `lib/head_music/rudiment.rb`
+9. Run tests: `bundle exec rspec spec/head_music/notation/musical_symbol_spec.rb`
+10. Run tests: `bundle exec rspec spec/head_music/rudiment/clef_spec.rb`
+11. Run tests: `bundle exec rspec spec/head_music/rudiment/alteration_spec.rb`
+12. Run full test suite: `bundle exec rspec`
+13. Run linter: `bundle exec rubocop -a`
+14. Delete original files after verifying everything works
+15. Verify 90%+ coverage maintained