head_music 8.3.0 → 11.0.0

data/user_stories/done/instrument-variant.md

@@ -0,0 +1,65 @@
+## Instrument Variant Refactoring
+
+### Background
+The current architecture conflates instrument catalog data with specific instrument instances. We need to separate these concerns to better represent how instruments are actually used in musical scores.
+
+### Hierarchy
+The refactored hierarchy will provide three levels of abstraction:
+- **InstrumentFamily** (existing): Broad category like "saxophone" or "trumpet"
+- **InstrumentType** (renamed from Instrument): Catalog entry with all possible variants (e.g., "trumpet" which can be in Bb, C, D, Eb)
+- **Instrument** (new): Specific instance with selected variant (e.g., "Trumpet in C")
+
+### User Stories
+
+**STORY 1: Rename Instrument to InstrumentType**
+AS a developer
+WHEN I want to access instrument catalog data
+I WANT to use InstrumentType.get("trumpet")
+SO THAT it's clear I'm getting a type definition, not a specific instrument instance
+
+**STORY 2: Create new Instrument class for specific variants**
+AS a developer
+WHEN I need a specific instrument for a score
+I WANT to call Instrument.get("trumpet_in_c") or Instrument.get("trumpet", "in_c")
+SO THAT I get a specific, usable instrument instance with proper transposition
+
+**STORY 3: Instrument instances are sortable**
+AS a developer
+WHEN I have multiple Instrument instances in a score
+I WANT them to sort properly by orchestral order and transposition
+SO THAT "Trumpet in Eb" appears before "Trumpet in C" in the score
+
+**STORY 4: Clear API for common use cases**
+AS a developer
+WHEN I create an Instrument without specifying a variant
+I WANT to get the default variant automatically
+SO THAT Instrument.get("clarinet") returns a Bb clarinet (the default)
+
+**STORY 5: Instrument provides unified interface**
+AS a developer
+WHEN I have an Instrument instance
+I WANT to access properties like name, transposition, clefs, and pitch_designation
+SO THAT I don't need to navigate between instrument type and variant objects
+
+### Implementation Notes
+
+1. The Instrument class should:
+   - Wrap both an InstrumentType and a specific Variant
+   - Generate appropriate display names (e.g., "Clarinet in A")
+   - Provide methods for transposition, clefs, staff schemes
+   - Be directly usable in scores and parts
+
+2. Factory methods should support:
+   - `Instrument.get("trumpet_in_c")` - parse variant from name
+   - `Instrument.get("trumpet", "in_c")` - explicit variant
+   - `Instrument.get("trumpet")` - use default variant
+
+3. ScoreOrder should work with Instrument instances directly
+
+### Migration Path
+
+1. Rename existing Instrument class to InstrumentType
+2. Update all references to use InstrumentType where appropriate
+3. Create new Instrument class for variant instances
+4. Update ScoreOrder to work with new Instrument instances
+5. Update documentation and tests

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

data/user_stories/done/move-staff-mapping-to-notation.md

@@ -0,0 +1,158 @@
+# Move StaffMapping to Notation Module
+
+AS a developer
+
+I WANT StaffMapping in the HeadMusic::Notation module
+
+SO THAT percussion notation mapping logic lives with visual notation concerns rather than instrument properties
+
+## Background
+
+`StaffMapping` maps percussion instruments (and playing techniques) to specific positions on a staff. For example, in a standard drum kit staff:
+- Bass drum → space below staff
+- Snare drum → space 2
+- Hi-hat → space 4
+- Ride cymbal → top line
+
+This is purely about visual notation - where on the staff each drum appears - not about the acoustic properties of the instruments themselves. The drum's sound (pitch range, timbre) is an instrument property, but where it appears on a staff is a notation convention.
+
+Currently located in `HeadMusic::Instruments`, this class should move to `HeadMusic::Notation` to properly separate visual layout concerns from instrument acoustics.
+
+## Scenario: Mapping drums to staff positions
+
+Given a drum kit with a snare drum
+
+When I need to notate the snare on a staff
+
+Then StaffMapping tells me it appears on space 2
+
+And I can use that position for rendering
+
+## Scenario: Getting all mappings for an instrument
+
+Given a drum kit instrument
+
+When I access its staff mapping
+
+Then I get all the drum-to-position mappings for that kit
+
+And each mapping includes the instrument, playing technique, and staff position
+
+## Scenario: Supporting different percussion notation schemes
+
+Given different percussion instruments use different staff conventions
+
+When I create a StaffMapping for a specific scheme (e.g., "standard drum kit")
+
+Then instruments are mapped to their conventional positions for that notation style
+
+## Technical Notes
+
+### Current State
+
+**Location:** `lib/head_music/instruments/staff_mapping.rb`
+**Class:** `HeadMusic::Instruments::StaffMapping`
+**Tests:** `spec/head_music/instruments/staff_mapping_spec.rb`
+**Used by:**
+- `lib/head_music/instruments/staff.rb`
+- `lib/head_music/instruments/staff_scheme.rb`
+- Percussion instrument configurations
+
+### Proposed Changes
+
+1. **Move file:**
+   - From: `lib/head_music/instruments/staff_mapping.rb`
+   - To: `lib/head_music/notation/staff_mapping.rb`
+
+2. **Update class definition:**
+   ```ruby
+   # lib/head_music/notation/staff_mapping.rb
+   module HeadMusic::Notation; end
+
+   class HeadMusic::Notation::StaffMapping
+     attr_reader :instrument, :playing_technique, :staff_position
+
+     def initialize(instrument:, playing_technique: nil, staff_position:)
+       @instrument = instrument
+       @playing_technique = playing_technique
+       @staff_position = HeadMusic::Notation::StaffPosition.new(staff_position)
+     end
+
+     # ... rest of class unchanged
+   end
+   ```
+
+3. **Move spec file:**
+   - From: `spec/head_music/instruments/staff_mapping_spec.rb`
+   - To: `spec/head_music/notation/staff_mapping_spec.rb`
+
+4. **Update spec:**
+   ```ruby
+   describe HeadMusic::Notation::StaffMapping do
+     # All tests remain unchanged except the describe statement
+   ```
+
+5. **Update references:**
+   - `lib/head_music/instruments/staff.rb` - Update StaffMapping references
+   - `lib/head_music/instruments/staff_scheme.rb` - Update StaffMapping references
+   - Instrument YAML files if they reference the class directly
+
+6. **Update loading:**
+   ```ruby
+   # lib/head_music/notation.rb
+   module HeadMusic::Notation; end
+
+   require "head_music/notation/staff_position"
+   require "head_music/notation/musical_symbol"
+   require "head_music/notation/staff_mapping"
+   ```
+
+### Files to Update
+
+- Move: `lib/head_music/instruments/staff_mapping.rb` → `lib/head_music/notation/staff_mapping.rb`
+- Move: `spec/head_music/instruments/staff_mapping_spec.rb` → `spec/head_music/notation/staff_mapping_spec.rb`
+- Update: `lib/head_music/notation.rb` (add require)
+- Update: `lib/head_music/instruments/staff.rb` (update references)
+- Update: `lib/head_music/instruments/staff_scheme.rb` (update references)
+- Remove: `lib/head_music/instruments.rb` require for staff_mapping
+
+### Dependencies
+
+This story depends on `StaffPosition` already being in the Notation module, since `StaffMapping` uses `StaffPosition`. Recommended to complete the "Move StaffPosition to Notation" story first.
+
+## Acceptance Criteria
+
+- [ ] `HeadMusic::Notation::StaffMapping` class exists
+- [ ] Original file `lib/head_music/instruments/staff_mapping.rb` removed
+- [ ] Spec file at `spec/head_music/notation/staff_mapping_spec.rb`
+- [ ] All existing StaffMapping tests pass
+- [ ] StaffMapping correctly references `Notation::StaffPosition`
+- [ ] References in `Instruments::Staff` updated and working
+- [ ] References in `Instruments::StaffScheme` updated and working
+- [ ] `lib/head_music/notation.rb` requires staff_mapping
+- [ ] `lib/head_music/instruments.rb` no longer requires staff_mapping
+- [ ] All percussion instrument tests still 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. Verify `StaffPosition` is already in `HeadMusic::Notation`
+2. Create `lib/head_music/notation/staff_mapping.rb` with updated module path
+3. Update StaffPosition reference to use `Notation::StaffPosition`
+4. Copy rest of class implementation unchanged
+5. Create `spec/head_music/notation/staff_mapping_spec.rb`
+6. Update describe statement in spec
+7. Update `lib/head_music/notation.rb` to require staff_mapping
+8. Update references in `lib/head_music/instruments/staff.rb`
+9. Update references in `lib/head_music/instruments/staff_scheme.rb`
+10. Remove require from `lib/head_music/instruments.rb`
+11. Run tests: `bundle exec rspec spec/head_music/notation/staff_mapping_spec.rb`
+12. Run tests: `bundle exec rspec spec/head_music/instruments/staff_spec.rb`
+13. Run tests: `bundle exec rspec spec/head_music/instruments/staff_scheme_spec.rb`
+14. Run percussion-related tests
+15. Run full test suite: `bundle exec rspec`
+16. Run linter: `bundle exec rubocop -a`
+17. Delete original files after verifying everything works
+18. Verify 90%+ coverage maintained

data/user_stories/done/move-staff-position-to-notation.md

@@ -0,0 +1,141 @@
+# Move StaffPosition to Notation Module
+
+AS a developer
+
+I WANT StaffPosition in the HeadMusic::Notation module
+
+SO THAT staff positioning logic lives with other visual notation concerns rather than instrument properties
+
+## Background
+
+`StaffPosition` represents positions on a 5-line musical staff (lines, spaces, and ledger lines). It's a pure visual notation concept with no connection to instrument acoustical properties.
+
+Currently located in `HeadMusic::Instruments`, it has a TODO comment (line 5) suggesting it should move to a HeadMusic::Notation module.
+
+The class:
+- Maps integer indices to staff positions (even = lines, odd = spaces)
+- Handles positions within the staff (0-8) and ledger lines above/below
+- Provides named positions ("bottom line", "middle line", "top line", etc.)
+- Has comprehensive test coverage (264 lines of tests)
+
+This move resolves the TODO and establishes StaffPosition as the first concrete class in the Notation module.
+
+## Scenario: Accessing staff positions for rendering
+
+Given I need to position a note on a musical staff
+
+When I use `HeadMusic::Notation::StaffPosition.new(4)`
+
+Then I get the middle line staff position
+
+And I can query whether it's a line or space
+
+And I can get its display name
+
+## Scenario: Using named staff positions
+
+Given I need to reference a specific staff position
+
+When I use `HeadMusic::Notation::StaffPosition.name_to_index("top line")`
+
+Then I get the index 8
+
+And I can create a StaffPosition from that index
+
+## Scenario: Handling ledger lines
+
+Given I need a position above or below the standard staff
+
+When I create `HeadMusic::Notation::StaffPosition.new(10)`
+
+Then I get "ledger line above staff"
+
+And when I create `HeadMusic::Notation::StaffPosition.new(-2)`
+
+Then I get "ledger line below staff"
+
+## Technical Notes
+
+### Current State
+
+**Location:** `lib/head_music/instruments/staff_position.rb`
+**Class:** `HeadMusic::Instruments::StaffPosition`
+**Tests:** `spec/head_music/instruments/staff_position_spec.rb` (264 lines)
+**Dependencies:** Used by `Clef` for pitch-to-staff mapping
+
+### Proposed Changes
+
+1. **Move file:**
+   - From: `lib/head_music/instruments/staff_position.rb`
+   - To: `lib/head_music/notation/staff_position.rb`
+
+2. **Update class definition:**
+   ```ruby
+   # lib/head_music/notation/staff_position.rb
+   module HeadMusic::Notation; end
+
+   class HeadMusic::Notation::StaffPosition
+     # Remove TODO comment about moving to Notation module
+     # ... rest of class unchanged
+   ```
+
+3. **Move spec file:**
+   - From: `spec/head_music/instruments/staff_position_spec.rb`
+   - To: `spec/head_music/notation/staff_position_spec.rb`
+
+4. **Update spec:**
+   ```ruby
+   describe HeadMusic::Notation::StaffPosition do
+     # All tests remain unchanged except the describe statement
+   ```
+
+5. **Update references:**
+   - `lib/head_music/rudiment/clef.rb` - Update StaffPosition references
+   - `lib/head_music/notation.rb` - Add require for staff_position
+
+6. **Update loading:**
+   ```ruby
+   # lib/head_music/notation.rb
+   module HeadMusic::Notation; end
+
+   require "head_music/notation/staff_position"
+   ```
+
+### Files to Update
+
+- Move: `lib/head_music/instruments/staff_position.rb` → `lib/head_music/notation/staff_position.rb`
+- Move: `spec/head_music/instruments/staff_position_spec.rb` → `spec/head_music/notation/staff_position_spec.rb`
+- Update: `lib/head_music/notation.rb` (add require)
+- Update: `lib/head_music/rudiment/clef.rb` (update references)
+- Remove: `lib/head_music/instruments.rb` require for staff_position
+- Update: CLAUDE.md (note StaffPosition location)
+
+## Acceptance Criteria
+
+- [ ] `HeadMusic::Notation::StaffPosition` class exists
+- [ ] Original file `lib/head_music/instruments/staff_position.rb` removed
+- [ ] Spec file at `spec/head_music/notation/staff_position_spec.rb`
+- [ ] All 264 lines of existing tests pass unchanged (except describe statement)
+- [ ] TODO comment removed from class
+- [ ] All references in `Clef` updated and working
+- [ ] `lib/head_music/notation.rb` requires staff_position
+- [ ] `lib/head_music/instruments.rb` no longer requires staff_position
+- [ ] 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/staff_position.rb` with updated module path
+2. Copy class implementation, removing TODO comment
+3. Create `spec/head_music/notation/staff_position_spec.rb`
+4. Update describe statement in spec
+5. Update `lib/head_music/notation.rb` to require staff_position
+6. Update references in `lib/head_music/rudiment/clef.rb`
+7. Remove require from `lib/head_music/instruments.rb`
+8. Run tests: `bundle exec rspec spec/head_music/notation/staff_position_spec.rb`
+9. Run tests: `bundle exec rspec spec/head_music/rudiment/clef_spec.rb`
+10. Run full test suite: `bundle exec rspec`
+11. Run linter: `bundle exec rubocop -a`
+12. Delete original files after verifying everything works
+13. Verify 90%+ coverage maintained

data/user_stories/done/notation-module-foundation.md

@@ -0,0 +1,102 @@
+# Notation Module Foundation
+
+AS a developer
+
+I WANT a dedicated HeadMusic::Notation module structure
+
+SO THAT I have a clear, organized place for notation-related features separate from music theory, instrument properties, and musical content
+
+## Background
+
+The HeadMusic gem currently organizes code into four main modules:
+- **Rudiment** - Abstract music theory concepts (pitch, interval, scale, chord)
+- **Instruments** - Instrument properties (range, transposition, families)
+- **Content** - Musical compositions and temporal organization
+- **Analysis** - Music analysis tools
+
+However, there's no dedicated module for visual notation or representational concerns. Notation-related code is scattered across Instruments and Rudiment, making it unclear where notation features should live.
+
+A TODO comment in `lib/head_music/instruments/staff_position.rb:5` suggests creating a HeadMusic::Notation module. Before moving any classes, we need the foundational infrastructure in place.
+
+## Scenario: Loading the notation module
+
+Given the HeadMusic gem is loaded
+
+When I require 'head_music'
+
+Then the HeadMusic::Notation module should be available
+
+And it should not break any existing functionality
+
+## Scenario: Documenting module boundaries
+
+Given a developer wants to add notation features
+
+When they consult CLAUDE.md
+
+Then they should see clear guidance on what belongs in Notation vs Rudiment vs Instruments vs Content
+
+## Technical Notes
+
+### Module Boundaries
+
+**HeadMusic::Notation** (visual representation):
+- Staff positions, lines, spaces, ledger lines
+- Musical symbols (ASCII, Unicode, HTML entities)
+- Clef placement and rendering
+- Notehead shapes, stems, flags, beams
+- Accidental placement rules
+- Future: ties, slurs, articulations, dynamics
+
+**HeadMusic::Rudiment** (music theory):
+- Abstract concepts: pitch, interval, scale, chord
+- Duration concepts (without visual representation)
+- Keys, meters (as musical concepts)
+
+**HeadMusic::Instruments** (instrument properties):
+- Instrument families and classification
+- Pitch ranges and transposition
+- Playing techniques
+- Score ordering
+
+**HeadMusic::Content** (musical content):
+- Compositions, voices, bars
+- Notes in context (pitch + duration + placement)
+- Temporal organization
+
+### Implementation
+
+Create minimal module infrastructure:
+
+**File: `lib/head_music/notation.rb`**
+```ruby
+# A module for visual music notation
+module HeadMusic::Notation; end
+
+# Load notation classes
+# (Initially empty - classes will be added in subsequent stories)
+```
+
+**Update: `lib/head_music.rb`**
+```ruby
+# Add after Content module loading:
+require "head_music/notation"
+```
+
+**Update: `CLAUDE.md`**
+Add section documenting the Notation module and its boundaries.
+
+## Acceptance Criteria
+
+- [ ] `lib/head_music/notation/` directory exists
+- [ ] `lib/head_music/notation.rb` file exists and defines module
+- [ ] `lib/head_music.rb` requires the notation module
+- [ ] `HeadMusic::Notation` module is accessible after requiring 'head_music'
+- [ ] All existing tests pass without modification
+- [ ] Maintains 90%+ test coverage
+- [ ] CLAUDE.md updated with Notation module boundaries
+- [ ] No existing functionality broken
+
+## Implementation Notes
+
+This is pure infrastructure - no classes are moved or created yet. This provides the foundation for subsequent stories that will move StaffPosition, MusicalSymbol, and StaffMapping into the Notation module.