head_music 9.0.1 → 11.1.0

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.

data/user_stories/done/percussion_set.md

@@ -0,0 +1,260 @@
+# Percussion Set Staff
+
+As a composer or arranger
+
+I want to create percussion set or drum kit parts in a score
+
+So that I can notate multiple unpitched percussion instruments on a single staff
+
+## Background
+
+Individual percussion instruments (timpani, snare_drum, bass_drum, etc.) already exist in the codebase and use the `neutral_clef` (also known as percussion_clef). However, there's no way to represent a **percussion set** or **drum kit** where multiple unpitched instruments are notated on a single staff with each instrument assigned to a specific line or space.
+
+This is distinct from a clef. The `neutral_clef` already exists in `HeadMusic::Rudiment::Clef`. What's needed is:
+1. A new instrument definition for percussion sets (e.g., `drum_kit`, `percussion_set`)
+2. A staff scheme that uses the `neutral_clef`
+3. A percussion mapping system that defines which instruments appear on which staff lines/spaces
+
+## Scenario: Create a standard drum kit staff
+
+Given I am composing a piece with drum kit
+
+When I create a drum_kit instrument
+
+Then it should use the neutral_clef
+
+And it should have a default percussion mapping for standard drum kit instruments
+
+## Scenario: Map percussion instruments to staff positions
+
+Given I have a drum_kit instrument
+
+When I request the percussion mapping
+
+Then I should see which line or space each percussion instrument occupies
+
+Examples:
+- Crash cymbal → line 5
+- Hi-hat → line 4 (or space above)
+- Snare drum → line 3 (center line)
+- Bass drum → line 1 (or space below)
+- Floor tom → line 2
+
+## Scenario: Create custom percussion set configurations
+
+Given I want to notate a non-standard percussion ensemble
+
+When I define a custom percussion_set
+
+Then I should be able to specify which percussion instruments map to which staff positions
+
+And the system should use the neutral_clef for the staff
+
+## Technical Notes
+
+### Architecture
+
+A percussion set is:
+- **NOT a clef** - it uses the existing `neutral_clef`
+- **An instrument** with a special staff scheme configuration
+- **A mapping system** that assigns percussion instruments to staff positions
+
+### Proposed Implementation
+
+Add to `lib/head_music/instruments/instruments.yml`:
+
+```yaml
+drum_kit:
+  family_key: percussion_set
+  variants:
+    default:
+      staff_schemes:
+        default:
+          - clef: neutral_clef
+            percussion_mapping:
+              line_5: crash_cymbal
+              space_4: ride_cymbal
+              line_4: hi_hat
+              space_3: high_tom
+              line_3: snare_drum
+              space_2: mid_tom
+              line_2: floor_tom
+              space_1: bass_drum
+              line_1: bass_drum
+
+percussion_set:
+  family_key: percussion_set
+  variants:
+    default:
+      staff_schemes:
+        default:
+          - clef: neutral_clef
+```
+
+### New Concepts to Implement
+
+1. **Percussion mapping attribute** on `HeadMusic::Instruments::Staff`
+2. **Percussion family or category** to identify instruments as unpitched/percussion
+3. **Position resolution** to determine which line/space a percussion instrument should use
+
+### Related Components
+
+- `HeadMusic::Rudiment::Clef` - neutral_clef already exists (line 115-128 in clefs.yml)
+- `HeadMusic::Instruments::Staff` - would need to handle percussion_mapping attribute
+- `HeadMusic::Instruments::StaffScheme` - provides the staff configuration
+- Individual percussion instruments (timpani, snare_drum, etc.) already exist
+
+## Acceptance Criteria
+
+- Can create a drum_kit instrument
+- drum_kit uses neutral_clef by default
+- Can query which percussion instrument is assigned to each staff position
+- Can create custom percussion_set configurations with custom mappings
+- Maintains 90%+ test coverage
+- Follows existing HeadMusic patterns (factory methods, YAML data-driven)
+
+## Implementation Plan
+
+### Design Decisions
+
+Based on research and discussion:
+
+1. **Naming**: Use `instrument_mapping` (not `percussion_mapping`) for flexibility
+2. **Mapping Format**: Use instrument keys (strings/symbols), not objects
+3. **Validation**:
+   - Mapped instruments must exist
+   - No requirement that they be percussion instruments
+   - Valid positions: `line_0` through `line_6`, `space_0` through `space_5`
+4. **Flexibility**: Mappings are immutable (YAML-defined only) for now
+5. **Stem Direction**: Rendering concern, not part of infrastructure
+6. **Composite Instruments**: No special type needed - just regular instruments with `instrument_mapping`
+7. **Family**: Use `drum_kit` family (not generic `percussion_set`)
+
+### Standard Drum Kit Notation Mapping
+
+Research shows there is no single universal standard, but most common convention:
+
+```yaml
+instrument_mapping:
+  space_0: hi_hat_pedal        # below staff
+  line_1: bass_drum
+  line_2: floor_tom
+  line_3: snare_drum            # middle line - most consistent
+  line_4: mid_tom
+  space_4: high_tom
+  line_5: ride_cymbal
+  space_5: hi_hat               # above staff
+  line_6: crash_cymbal          # first ledger line above
+```
+
+### Implementation Steps
+
+#### 1. Add New Instrument Families
+To `lib/head_music/instruments/instrument_families.yml`:
+- `tom_tom` family
+- `hi_hat` family
+- `drum_kit` family
+
+#### 2. Add New Individual Instruments
+To `lib/head_music/instruments/instruments.yml`:
+- `hi_hat` (family: hi_hat)
+- `hi_hat_pedal` (family: hi_hat)
+- `crash_cymbal` (family: cymbal)
+- `ride_cymbal` (family: cymbal)
+- `high_tom` (family: tom_tom)
+- `mid_tom` (family: tom_tom)
+- `floor_tom` (family: tom_tom)
+
+Each with:
+- Appropriate aliases
+- `family_key` reference
+- Single `default` variant
+- `neutral_clef` staff scheme
+
+#### 3. Add Composite Instrument
+To `lib/head_music/instruments/instruments.yml`:
+- `drum_kit` (alias: `drum_set`) with standard instrument_mapping
+
+#### 4. Enhance Staff Class
+To `lib/head_music/instruments/staff.rb`:
+- Add `instrument_mapping` attribute (hash)
+- Add `#instrument_for_position(position_key)` method
+- Add `#position_for_instrument(instrument_name)` method
+- Add `#components` method (derives instruments from mapping)
+- Handle parsing `instrument_mapping` from YAML
+- Validate:
+  - Position keys match pattern (line_0-6, space_0-5)
+  - Referenced instruments exist
+
+#### 5. Tests
+- Specs for all new instrument families
+- Specs for all new individual instruments
+- Specs for `Staff#instrument_mapping` functionality
+- Specs for `drum_kit` composite instrument
+- Maintain 90%+ code coverage
+
+---
+
+## Refactoring Notes (Post-Implementation)
+
+After the initial implementation, the design was refactored to better model playing techniques as a first-class concept rather than treating them as separate instruments.
+
+### Key Changes:
+
+1. **Introduced `PlayingTechnique` class**
+   - Playing techniques (pedal, stick, mallet, etc.) are now modeled as objects
+   - Includes `HeadMusic::Named` for potential future i18n support
+   - Common techniques defined: stick, pedal, mallet, hand, brush, rim_shot, cross_stick, open, closed, etc.
+
+2. **Created `StaffMapping` class** (replaces simple hash-based approach)
+   - Represents the mapping of an instrument + optional playing technique to a staff position
+   - Uses `StaffPosition` with index-based positions (even = lines, odd = spaces)
+   - Attributes: `staff_position`, `instrument_key`, `playing_technique_key`
+   - Methods: `#instrument`, `#playing_technique`, `#position_index`, `#to_s`
+
+3. **Removed `hi_hat_pedal` as separate instrument**
+   - Hi-hat pedal is now correctly modeled as a playing technique of the hi-hat instrument
+   - The hi-hat appears at two positions in drum_kit mapping:
+     - Position -1 (space below staff): hi_hat with pedal technique
+     - Position 9 (space above staff): hi_hat with stick technique
+
+4. **Updated `Staff` class API**
+   - `#mappings` → returns array of `StaffMapping` objects
+   - `#mapping_for_position(index)` → get full mapping at position
+   - `#instrument_for_position(index)` → get instrument at position
+   - `#positions_for_instrument(key)` → returns all positions (handles multiple mappings)
+   - `#components` → returns unique instruments
+
+5. **Changed YAML format** from hash to array:
+   ```yaml
+   # Old format:
+   instrument_mapping:
+     line_3: snare_drum
+     space_5: hi_hat
+
+   # New format:
+   mappings:
+     - staff_position: 4        # index 4 = line 3
+       instrument: snare_drum
+     - staff_position: 9        # index 9 = space above staff
+       instrument: hi_hat
+       playing_technique: stick
+   ```
+
+6. **Added comprehensive YARD documentation**
+   - All new classes and public methods documented
+   - Examples provided for common use cases
+
+### Benefits of Refactoring:
+
+- **Semantic clarity**: Hi-hat pedal is a technique, not an instrument
+- **Extensibility**: Easy to add new playing techniques (bow techniques for strings, breath techniques for winds, etc.)
+- **Flexibility**: Instruments can appear at multiple positions with different techniques
+- **Type safety**: StaffPosition validates position indices, StaffMapping provides structured access
+
+### Test Results:
+
+- **1040 examples, 0 failures** ✅
+- **91.54% line coverage, 84.44% branch coverage** ✅
+- All existing functionality preserved
+- New tests verify multiple technique mappings