head_music 17.0.0 → 17.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 032e67bcfe59e2efb864f17ebce9fd7e5134c216c5274f96ef7f9cae1d45442a
-  data.tar.gz: fa73331c0868598885695e1fffc53e76824f1498549f82ac68d2c98276a887fc
+  metadata.gz: afa3afecdb9f3baef8bc34bb645805cd7defbd206e388a2a156d1f4f80516656
+  data.tar.gz: b858239c696ef22b759d4a96f033588cf871b83254538c991c8fdff67565a179
 SHA512:
-  metadata.gz: 363dde634782a8bf79e53bd62ac376515611711d839deb4258088ec197dd6f3f5e199321c8d347c66b42756a7872511a4b680c022a1106fcb3c4b0ba88513a88
-  data.tar.gz: 37eb0b6df32586566a21603549df3fbbdfa01858b1ec66da3af0c76d3a8a7d276cd939a987ba36990b359c6bebca20f713c137935d095f3ee2debb9130d29c8f
+  metadata.gz: b3c54b4663df784f5382fd992500df795cf69e985501596d592bf7ffe5c0a7887ecc81ad36e76cbebf9a0e30597607ef2db629c3e8946e128043f9f5aa012976
+  data.tar.gz: d5f6c002b3f4522dcdf2f3741ecacd933ea3bb2c33ee7a438ca8a649eb57b2e8d68053a6a8a0a616f17d1e3087b733dccf1d384a0ae6c27084854474c528deea

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [17.2.0] - 2026-07-19
+
+### Added
+
+- The ABC interpreter reads explicit ties (`-`) between notes. `E3-E2` fuses into one sounding note whose rhythmic value carries the authored split (`dotted quarter tied to quarter`), overriding the resolver's greedy decomposition, and tie chains (`C2-C2-C2`) nest into a single value. A tie between notes of different pitches, a dangling tie, or a tie to a rest raises `ParseError`; a tie across a barline raises `ParseError` ("Ties across barlines are not yet supported") pending a future release.
+
+## [17.1.0] - 2026-07-18
+
+### Changed
+
+- The MusicXML writer renders chord placements as stacked notes rather than raising `RenderError`: a chord emits one `<note>` per pitched sound, ordered low to high, with `<chord/>` on all but the lowest note, all sharing the placement's rhythmic value. Tied chords emit a full chord stack per tie-link. The writer still raises `RenderError` for placements containing unpitched sounds (percussion rendering lands in a future release).
+
 ## [17.0.0] - 2026-07-18
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (17.0.0)
+    head_music (17.2.0)
       activesupport (>= 7.0, < 10)
       humanize (~> 2.0)
       i18n (~> 1.8)
@@ -88,7 +88,7 @@ GEM
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
     ice_nine (0.11.2)
-    json (2.13.1)
+    json (2.21.1)
     kramdown (2.5.1)
       rexml (>= 3.3.9)
     language_server-protocol (3.17.0.5)

data/lib/head_music/notation/abc/body_lexer.rb

@@ -128,6 +128,7 @@ class HeadMusic::Notation::ABC::BodyLexer
     return if scan_bracket(scanner, line_number, column, tokens)
     return if scan_note(scanner, line_number, column, tokens)
     return if scan_rest(scanner, line_number, column, tokens)
+    return if scan_tie(scanner, line_number, column, tokens)
     return if scan_broken_rhythm(scanner, line_number, column, tokens)
     return if scan_unsupported(scanner, line_number, column, tokens)
 
@@ -277,13 +278,24 @@ class HeadMusic::Notation::ABC::BodyLexer
     true
   end
 
+  # A tie (a hyphen following a note or chord) joins it to the next
+  # note of the same pitch; the parser fuses the two into one sounding
+  # value. Ties inside a bracket chord still surface as unsupported via
+  # the chord fallback.
+  def scan_tie(scanner, line_number, column, tokens)
+    return false unless scanner.scan("-")
+
+    tokens << Token.new(type: :tie, line: line_number, column: column)
+    true
+  end
+
   # Recognizable ABC we deliberately don't handle: grace notes,
-  # decorations, tuplets, slurs, ties, and special rests.
+  # decorations, tuplets, slurs, and special rests.
   def scan_unsupported(scanner, line_number, column, tokens)
     lexeme =
       scanner.scan(/\{[^}]*\}/) || scanner.scan(/\{[^}]*/) ||
       scanner.scan(/![^!]*!/) || scanner.scan(/![^!]*/) ||
-      scanner.scan(/\(\d/) || scanner.scan(/[()\-~.]/) ||
+      scanner.scan(/\(\d/) || scanner.scan(/[()~.]/) ||
       scanner.scan(/Z\d*/) || scanner.scan(%r{x[\d/]*})
     return false unless lexeme
 

data/lib/head_music/notation/abc/parser.rb

@@ -36,15 +36,21 @@ module HeadMusic::Notation::ABC
 
     # A note or chord whose placement is deferred until we know whether
     # a broken-rhythm mark follows it. The pitches are computed eagerly
-    # so bar-line accidental resets cannot corrupt them.
-    PendingNote = Data.define(:pitches, :length, :scale)
+    # so bar-line accidental resets cannot corrupt them. `tied_prefix`,
+    # when present, is the already-built rhythmic value of everything
+    # tied ahead of this note; its own value is appended at flush time.
+    PendingNote = Data.define(:pitches, :length, :scale, :tied_prefix) do
+      def initialize(pitches:, length:, scale:, tied_prefix: nil)
+        super
+      end
+    end
 
     # Per-voice interpretation state. Accidentals, the deferred note,
     # and volta tracking are all independent between voices.
     class VoiceState
       attr_reader :voice, :pitch_builder
       attr_accessor :pending_note, :awaiting_scale, :broken_line,
-        :active_passes, :volta_start_bar
+        :active_passes, :volta_start_bar, :tie_open, :tie_line
 
       def initialize(voice, pitch_builder)
         @voice = voice
@@ -148,6 +154,7 @@ module HeadMusic::Notation::ABC
       when :note then handle_note(token)
       when :chord then handle_chord(token)
       when :rest then handle_rest(token)
+      when :tie then handle_tie(token)
       when :broken_rhythm then handle_broken_rhythm(token)
       when :bar_line then handle_bar_line(token)
       when :volta then handle_volta(token)
@@ -207,19 +214,69 @@ module HeadMusic::Notation::ABC
     def defer_placement(state, pitches, length, inner_scale = Rational(1))
       scale = (state.awaiting_scale || Rational(1)) * inner_scale
       state.awaiting_scale = nil
+      return tie_onto_pending(state, pitches, length, scale) if state.tie_open
+
       flush_pending_note(state)
       state.pending_note = PendingNote.new(pitches: pitches, length: length, scale: scale)
     end
 
+    # A tie (`-`) after a note or chord fuses it to the next note of the
+    # same pitch. The left note stays pending; the tie is only closed once
+    # its right note arrives.
+    def handle_tie(token)
+      state = current_state
+      if state.awaiting_scale || state.pending_note.nil?
+        raise ParseError.new(
+          "A tie must follow a note", line_number: token.line, snippet: "-"
+        )
+      end
+      state.tie_open = true
+      state.tie_line = token.line
+    end
+
+    # Closes an open tie: the pending note becomes the new note's tied
+    # prefix, so the pair (and any longer chain) resolves to a single
+    # placement whose rhythmic value carries the author's chosen split.
+    def tie_onto_pending(state, pitches, length, scale)
+      pending = state.pending_note
+      ensure_tie_pitches_match(state, pending, pitches)
+      prefix = pending_rhythmic_value(pending)
+      state.tie_open = false
+      state.tie_line = nil
+      state.pending_note = PendingNote.new(
+        pitches: pitches, length: length, scale: scale, tied_prefix: prefix
+      )
+    end
+
+    def ensure_tie_pitches_match(state, pending, pitches)
+      return if pending.pitches.sort == pitches.sort
+
+      raise ParseError.new(
+        "A tie must connect two notes of the same pitch",
+        line_number: state.tie_line, snippet: "-"
+      )
+    end
+
     def handle_rest(token)
       ensure_not_awaiting_note(token)
       state = current_state
+      reject_open_tie(state, token.line, "A tie must be followed by a note")
       flush_pending_note(state)
       place(state, token.length, nil)
     end
 
+    # A tie left open by a non-note terminator can never close, so each
+    # terminator rejects it. A bar line gets its own message: an author
+    # tie across a barline is a real, but not-yet-supported, request.
+    def reject_open_tie(state, line, message)
+      return unless state&.tie_open
+
+      raise ParseError.new(message, line_number: line || state.tie_line, snippet: "-")
+    end
+
     def handle_broken_rhythm(token)
       state = current_state
+      reject_open_tie(state, token.line, "A tie must be followed by a note")
       if state.awaiting_scale || state.pending_note.nil?
         raise ParseError.new(
           "Broken rhythm must appear between two notes",
@@ -235,6 +292,7 @@ module HeadMusic::Notation::ABC
     def handle_bar_line(token)
       ensure_not_awaiting_note(token)
       state = current_state
+      reject_open_tie(state, token.line, "Ties across barlines are not yet supported")
       flush_pending_note(state)
       tag_completed_bar(state)
       apply_repeat_flags(state, token.style)
@@ -248,6 +306,7 @@ module HeadMusic::Notation::ABC
         raise ParseError.new("Volta has no passes", line_number: token.line)
       end
       state = current_state
+      reject_open_tie(state, token.line, "A tie must be followed by a note")
       flush_pending_note(state)
       state.active_passes = token.passes
       state.volta_start_bar = state.entered_bar_number
@@ -257,6 +316,7 @@ module HeadMusic::Notation::ABC
       # Guarded so a leading V: line doesn't force a default voice into existence.
       if @current_state
         ensure_not_awaiting_note(token, state: @current_state)
+        reject_open_tie(@current_state, token.line, "A tie must be followed by a note")
         flush_pending_note(@current_state)
       end
       @current_state = voice_state(token.voice_id)
@@ -265,6 +325,7 @@ module HeadMusic::Notation::ABC
     def finish
       @voice_states.each_value do |state|
         ensure_not_awaiting_note(nil, state: state)
+        reject_open_tie(state, nil, "A tie must be followed by a note")
         flush_pending_note(state)
         tag_completed_bar(state)
       end
@@ -284,7 +345,22 @@ module HeadMusic::Notation::ABC
       return unless pending
 
       state.pending_note = nil
-      place(state, pending.length, pending.pitches, scale: pending.scale)
+      state.voice.place(state.voice.next_position, pending_rhythmic_value(pending), pending.pitches)
+    end
+
+    # A pending note's own value, with any tied prefix appended ahead of
+    # it so the whole tie chain renders as one sounding note.
+    def pending_rhythmic_value(pending)
+      own = duration_resolver.rhythmic_value(pending.length, scale: pending.scale)
+      pending.tied_prefix ? append_tied(pending.tied_prefix, own) : own
+    end
+
+    # Attaches `tail` at the deep end of `head`'s tied chain, rebuilding
+    # each link (RhythmicValue exposes no setter) so a chain like
+    # "half tied to eighth" gains a further "tied to quarter".
+    def append_tied(head, tail)
+      inner = head.tied_value ? append_tied(head.tied_value, tail) : tail
+      HeadMusic::Rudiment::RhythmicValue.new(head.unit, dots: head.dots, tied_value: inner)
     end
 
     def place(state, length, pitches, scale: Rational(1))

data/lib/head_music/notation/music_xml/writer.rb

@@ -312,13 +312,21 @@ module HeadMusic::Notation::MusicXML
 
     def note_lines(placement)
       ensure_pitched_sounds(placement)
-      raise RenderError, "chords are not yet supported by the MusicXML writer" if placement.chord?
 
       components_by_placement[placement].flat_map do |component|
-        component_lines(placement, component)
+        note_slots(placement).each_with_index.flat_map do |pitch, index|
+          note_element_lines(placement, component, pitch: pitch, chord: index.positive?)
+        end
       end
     end
 
+    # A rest emits one empty slot; a sounded placement emits its pitches low to
+    # high, so the lowest note leads and the rest carry <chord/>. ensure_pitched_sounds
+    # has already rejected any unpitched sound, so pitches covers every sound here.
+    def note_slots(placement)
+      placement.rest? ? [nil] : placement.pitches.sort
+    end
+
     def ensure_pitched_sounds(placement)
       unpitched = placement.sounds.find { |sound| !sound.pitched? }
       return unless unpitched
@@ -327,10 +335,14 @@ module HeadMusic::Notation::MusicXML
         "percussion rendering is not yet supported"
     end
 
-    def component_lines(placement, component)
+    # A chord note carries <chord/> as its first child, before <pitch>, marking
+    # it as sounding with the preceding note; the lead note (and every single
+    # note and rest) omits it, so this path stays byte-identical for those.
+    def note_element_lines(placement, component, pitch: nil, chord: false)
       [
         "#{INDENT * 3}<note>",
-        *(placement.pitched? ? pitch_lines(placement.pitch) : ["#{INDENT * 4}<rest/>"]),
+        *(chord ? ["#{INDENT * 4}<chord/>"] : []),
+        *(pitch ? pitch_lines(pitch) : ["#{INDENT * 4}<rest/>"]),
         "#{INDENT * 4}<duration>#{component.duration}</duration>",
         *tie_lines(placement, component),
         "#{INDENT * 4}<type>#{component.type}</type>",

data/lib/head_music/version.rb

@@ -1,3 +1,3 @@
 module HeadMusic
-  VERSION = "17.0.0"
+  VERSION = "17.2.0"
 end

data/user-stories/done/abc-tie-input.md

@@ -0,0 +1,195 @@
+<!--
+metadata:
+  created_at:   2026-07-19T11:46:34-07:00
+  activated_at: 2026-07-19T11:52:42-07:00
+  planned_at:   2026-07-19T11:57:00-07:00
+  finished_at:  2026-07-19T15:56:20-07:00
+  updated_at:   2026-07-19T15:56:20-07:00
+-->
+
+# Story: ABC Tie Input
+
+## Summary
+
+AS a developer authoring music with the ABC interpreter
+
+I WANT to write explicit ties (`-`) between notes
+
+SO THAT I can control how a sustained duration is engraved — including durations that span a barline — instead of accepting the interpreter's automatic decomposition
+
+## Background
+
+The [ABC Notation interpreter](../done/abc-notation-interpreter.md) reads ABC text into a `HeadMusic::Content::Composition` via `HeadMusic::Notation::ABC.parse`. It handles pitches, durations, chords, broken rhythm, and voltas — but it **deliberately rejects the tie character `-`**. `BodyLexer#scan_unsupported` folds `-` into an `:unsupported` token (character class `/[()\-~.]/`, whose comment reads "Recognizable ABC we deliberately don't handle: grace notes, decorations, tuplets, slurs, **ties**, and special rests"), and `Parser#reject_unsupported_tokens` then raises `UnsupportedFeatureError`.
+
+Ties are already *modeled* everywhere except at the input boundary:
+
+- `HeadMusic::Rudiment::RhythmicValue` carries a `tied_value`, and its string form round-trips "half tied to eighth".
+- `ABC::DurationResolver#build_rhythmic_value` already emits tied chains, decomposing any non-dotted-expressible duration by **greedily peeling the largest dotted head each pass**. So `E5` (five eighths under `L:1/8`) always becomes **half tied to eighth** (4 + 1) — the resolver never chooses 3 + 2.
+- The ABC exporter's `DurationWriter` already **collapses** a tied chain back into a single multiplier ("A tied chain collapses to one multiplier, round-tripping tokens like `A5`").
+
+The gap is authoring. Because the split is derived greedily and can't be overridden, an author cannot ask for a **dotted quarter tied to a quarter** (3 + 2) rather than **half tied to an eighth** (4 + 1), and — more fundamentally — cannot tie a note *across a barline*, which is the primary reason ties exist in ABC.
+
+This surfaced concretely in bardtheory's "Three Blind Mice" seed. In `6/8` with `L:1/8`, measure 8 is `E5 G` — a sustained E leading to a pickup G. The author wants that E engraved as a dotted quarter tied to a quarter; the interpreter can only produce half-tied-to-eighth, and `E3-E2 G` fails to parse.
+
+The [Notation Module epic](../epics/notation-module.md) already lists this as planned work: "Future: … ties …" and "Ties (connecting same pitches across bars)."
+
+## Example
+
+```
+X:1
+T:Tie examples
+M:6/8
+L:1/8
+K:C
+% Author-chosen split: dotted quarter tied to a quarter, then a pickup G
+E3-E2 G |
+% Tie across a barline: the C sustains from bar 1 into bar 2
+C6 | C3-C3 |]
+```
+
+```ruby
+composition = HeadMusic::Notation::ABC.parse(abc)
+# The E in bar 1 is a single sounding note whose RhythmicValue is
+# "dotted quarter tied to quarter" — the authored split, not 4 + 1.
+# The tied C sustains across the barline as one note.
+```
+
+## Acceptance Criteria
+
+- The lexer recognizes `-` immediately following a note (or chord) as a **tie token** rather than an unsupported feature; `-` in any other position still surfaces the existing clear error.
+- A tie between two **same-pitch** notes parses into a single sounding note whose `RhythmicValue` is the authored head tied to the authored tail: `E3-E2` → *dotted quarter tied to quarter* (3 + 2), overriding the greedy resolver rather than re-decomposing to 4 + 1.
+- Tie **chains** parse: `E2-E2-E2` yields a single note with a nested tied value spanning the whole duration.
+- A tie **across a barline** joins the last note of a measure to the first note of the next measure of the same pitch, producing one sustained note that spans the bar line. **(Deferred to a follow-up — see the Implementation Plan's scope decision. v1 detects an author tie that would cross a barline and raises a clear `ParseError`, "Ties across barlines are not yet supported," rather than joining the notes.)**
+- A tie between **different pitches** is not a tie in ABC (that notation is a slur). It raises a `ParseError` with line number and snippet — or is classified as an unsupported slur — but never silently produces a wrong pitch. (Pick one behavior and document it.)
+- The resulting model renders correctly through `to_musicxml`: tied notes emit MusicXML `<tie>` / `<tied>` so playback and engraving treat them as one sustained pitch, not two re-articulated notes.
+- Decide and document the **ABC export** behavior for authored ties: whether `DurationWriter` preserves the authored split on round-trip or continues collapsing tied chains to a single multiplier (today it collapses, so `E3-E2` would re-export as `E5`). Round-trip specs assert whichever behavior is chosen.
+- Specs cover: an author-chosen intra-measure split, a tie across a barline, a multi-note tie chain, a mismatched-pitch tie (error/slur path), and a MusicXML render asserting the `<tied>` elements.
+
+## Notes
+
+**Touch points (for planning, not prescriptive):**
+
+- `ABC::BodyLexer` — remove `-` from `scan_unsupported`; add a `scan_tie` producing a `:tie` token. Keep the "unterminated / dangling tie" cases as clear `ParseError`s.
+- `ABC::Parser` — when a `:tie` token joins two adjacent note placements, merge them into one placement whose `RhythmicValue` uses the authored head with the tail as its `tied_value`, bypassing `DurationResolver`'s greedy split for the tied span. Cross-barline ties are the hard part: a single note must span two measures' placement bookkeeping.
+- `ABC::DurationResolver` — unchanged for un-tied durations; explicit ties should *supply* the split rather than derive it.
+- `Notation::MusicXML::Writer` / `DurationWriter` — verify tied `RhythmicValue`s already emit `<tie type="start"/stop">` and `<tied>`; the greedy resolver produces tied chains today, so this path may already work and just need coverage.
+- `ABC::DurationWriter` (export) — the round-trip decision above lives here.
+
+**Scope boundaries (candidates for follow-up, not v1):**
+
+- Ties inside or between chords (`[CEG]-[CEG]`).
+- Slurs `( … )`, which share the `-`-adjacent lexer neighborhood but are a distinct musical construct.
+- Preserving an authored split through ABC *export* if that proves to conflict with the exporter's canonical-form goal.
+
+Related: [ABC Notation interpreter](../done/abc-notation-interpreter.md), [ABC Chord Input](../done/abc-chord-input.md), [ABC Notation Export](../done/abc-notation-export.md), [Notation Module epic](../epics/notation-module.md).
+
+## Implementation Plan
+
+### Scope decision
+
+This story ships **intra-note (within-bar) author-controlled ties** and reuses the existing tie-rendering pipeline end to end. The MusicXML writer already turns a `RhythmicValue` with a `tied_value` chain into multiple `<note>` elements carrying `<tie>`/`<tied>` (`MusicXML::DurationWriter#components`, `Writer#tie_lines`/`#notation_lines`). So the only gap is the ABC **input** boundary: letting the parser build a placement whose `RhythmicValue` is the author's chosen head-plus-tail instead of the resolver's greedy split.
+
+**Cross-barline ties are deferred.** A single placement cannot span a bar — the MusicXML writer's `ensure_notes_within_barlines` rejects that outright, and representing a tie *between two placements* would require a new concept in the Voice/Placement model plus writer changes. This story instead detects an author tie that would cross a barline (a `-` immediately before a bar line) and raises a clear, specific `ParseError` at parse time. Tracked as a follow-up in Scope Boundaries.
+
+### Step 1 — Lexer: emit a `:tie` token (`abc/body_lexer.rb`)
+
+- Add `scan_tie` to the `scan_token` chain, placed **before** `scan_unsupported`: match a single `-` and push `Token.new(type: :tie, line:, column:)`.
+- Remove `-` from `scan_unsupported`'s character class (`/[()\-~.]/` → `/[()~.]/`) so slurs `()`, staccato `.`, and roll `~` stay unsupported while `-` no longer does.
+- `-` inside volta ranges (`VOLTA_DIGITS_PATTERN`, `[…]`/trailing-volta paths) is unaffected — those are scanned in their own branches before the note stream reaches `scan_tie`.
+
+### Step 2 — Parser: combine tied notes into one placement (`abc/parser.rb`)
+
+- Extend `VoiceState` with a `tie_open` flag (+ a `tie_line` for error reporting).
+- Extend `PendingNote` with a `tied_prefix:` field (default `nil`) — a pre-built `RhythmicValue` holding everything tied *before* this note's own `(length, scale)`.
+- `handle_tie(token)`: require a `pending_note` and not `awaiting_scale`; otherwise raise `ParseError` ("A tie must follow a note" / broken-rhythm conflict). Set `state.tie_open = true`, record the line. Do **not** flush the pending note.
+- In `handle_note`/`handle_chord`: when `state.tie_open` is set, don't defer normally. Instead:
+  - Validate the new pitches equal the pending pitches (set equality). Mismatch → `ParseError` "A tie must connect two notes of the same pitch" with line/snippet (this is the ABC slur case).
+  - Build the head chain: `head = append_tied(pending.tied_prefix, resolve(pending))` where `resolve` = `duration_resolver.rhythmic_value(pending.length, scale: pending.scale)` and `append_tied(prefix, tail)` returns `tail` when `prefix` is nil, else a copy of `prefix` whose deepest `tied_value` is `tail` (recursive rebuild via `RhythmicValue.new(unit, dots:, tied_value:)`, since `RhythmicValue` has no setters).
+  - Set the new `pending_note` to the incoming note with `tied_prefix: head`; clear `tie_open`. Keeping it pending preserves broken-rhythm deferral and lets `E2-E2-E2` chains accumulate.
+- `flush_pending_note`/`place`: when `pending.tied_prefix` is present, place `append_tied(pending.tied_prefix, resolve(pending))` as the single placement's value; otherwise unchanged.
+- Guard the non-note terminators so an open tie fails fast and specifically:
+  - `handle_bar_line` while `tie_open` → `ParseError` "Ties across barlines are not yet supported" (the deferred case).
+  - `handle_rest` / `handle_volta` / `handle_voice_change` while `tie_open` → `ParseError` "A tie must connect two notes of the same pitch" (a tie to a non-note).
+  - `finish` while `tie_open` → `ParseError` "Tie has no following note" (dangling tie at end of tune).
+- `handle` gains a `when :tie then handle_tie(token)` branch.
+
+### Step 3 — Verify the render path is already correct
+
+No writer changes expected. Confirm by test that a parsed `E3-E2` produces a placement whose `rhythmic_value.to_s == "dotted quarter tied to quarter"` and that `to_musicxml` emits `<tie type="start"/>` + `<tied type="start"/>` on the first note and the `stop` pair on the second. If a gap surfaces, fix it in `MusicXML::Writer`, but the existing greedy-resolver output already exercises this path.
+
+### Step 4 — Specs
+
+- **Lexer** (`spec/.../abc/body_lexer_spec.rb`): `-` lexes as a `:tie` token; `()`, `.`, `~` still lex as `:unsupported`.
+- **Parser** (`spec/.../abc/parser_spec.rb` or the interpreter spec): author split `E3-E2` → one note, `RhythmicValue` "dotted quarter tied to quarter" (assert it differs from the greedy `E5` → "half tied to eighth"); a chain `C2-C2-C2`; mismatched pitch `E3-D2` raises the same-pitch `ParseError`; cross-barline `E3-|E3` raises "not yet supported"; dangling `E3-` at end raises; tie with no preceding note (`-E3`) raises.
+- **Round-trip / MusicXML** (`spec/.../music_xml_spec.rb` or the ABC interpreter → MusicXML spec): parsing the Three-Blind-Mice-style measure and rendering asserts the `<tied>` start/stop elements.
+- Follow existing spec structure/naming in `spec/head_music/notation/abc/`.
+
+### Step 5 — Docs & housekeeping
+
+- Update the `scan_unsupported` comment (currently lists "ties" among deliberately-unhandled constructs) to reflect that ties are now handled on input.
+- If a README/CHANGELOG enumerates supported ABC features, add ties (input, within-bar).
+- Run `bundle exec rspec` and `bundle exec standardrb`/`rubocop` (whichever the repo uses) to green before finishing.
+
+### Files touched
+
+- `lib/head_music/notation/abc/body_lexer.rb` — `scan_tie`, unsupported char-class edit, comment.
+- `lib/head_music/notation/abc/parser.rb` — `:tie` handling, `PendingNote`/`VoiceState` extension, `append_tied`, terminator guards.
+- `spec/head_music/notation/abc/*` and the MusicXML spec — new coverage.
+- Possibly `CHANGELOG`/README if they enumerate ABC feature support.
+
+### Scope Boundaries (Not in v1)
+
+- **Cross-barline ties** (`E3-|E3`) — needs a tie-between-placements concept in the Voice/Placement model and MusicXML writer; raises a clear "not yet supported" error for now.
+- **Ties on/between chords** (`[CEG]-[CEG]`) — the pitch-set-equality guard would admit identical chords, but this path is not a v1 target and gets at most light coverage; document as follow-up.
+- **Slurs** (`( … )`) — distinct construct, remains unsupported.
+- **ABC export of authored ties** — the exporter still collapses tied chains to a single multiplier (`E3-E2` → `E5`); preserving an authored split on export is out of scope. Export round-trip specs assert the current collapsing behavior.
+
+## Review
+
+_Reviewed 2026-07-19 at commit `8323de5` (implementation in `93023bb`, committed to `main` — no `story/abc-tie-input` branch was cut). All 236 examples in the ABC lexer/parser and MusicXML writer specs pass; the full suite still needs to be run to confirm nothing else regressed._
+
+### Acceptance criteria
+
+- ✅ **Lexer tie token; `-` elsewhere still errors.** `scan_tie` is inserted before `scan_unsupported` and emits a `:tie` token (`body_lexer.rb:285-290`); `-` was removed from the unsupported char class (`body_lexer.rb:298`). A leading tie is rejected in the parser ("A tie must follow a note", `parser.rb:226-235`). Note: a stray `-` with nothing else to match now yields the generic "Unexpected character" error rather than the old `UnsupportedFeatureError "-"` — arguably clearer, but a behavior change.
+- ✅ **Authored split preserved, overrides greedy resolver.** `tie_onto_pending` + `append_tied` build the nested `RhythmicValue` from the authored lengths (`parser.rb:240-363`). `parser_spec.rb:295-306` asserts `E3-E2` → `"dotted quarter tied to quarter"` and contrasts it against the greedy `"half tied to eighth"`.
+- ✅ **Tie chains nest into one value.** `append_tied` recurses; `C2-C2-C2` → `"quarter tied to quarter tied to quarter"` (`parser_spec.rb:308-311`).
+- ❌ **Cross-barline spanning tie — consciously deferred.** Not implemented; `handle_bar_line` raises "Ties across barlines are not yet supported" (`parser.rb:294`). The deferral is clean, documented in code/CHANGELOG/commit, and tested (`parser_spec.rb:323-326`). The original criterion is not met by design — this was scoped out in the plan. _Follow-up: the story's AC text has now been annotated to record the deferral._
+- ✅ **Different-pitch tie raises, never silent.** `ensure_tie_pitches_match` raises "A tie must connect two notes of the same pitch" (`parser.rb:251-258`); `E3-D2` tested (`parser_spec.rb:318-321`). Behavior (raise, not slur) is documented in the CHANGELOG.
+- ✅ **MusicXML `<tie>`/`<tied>` render.** No writer change needed — reuses the existing tied-`RhythmicValue` path. `writer_spec.rb:363-380` asserts note types `quarter quarter eighth`, a dot on note 1, and `tied` start/stop counts `[1,0,0]`/`[0,1,0]`.
+- ✅ **ABC export round-trip decided/documented/asserted.** Behavior is decided (collapse to one multiplier: `E3-E2` → `E5`) and documented in the story's Scope Boundaries. _Follow-up: a round-trip spec was added (`writer_spec.rb`, "with an authored tie collapsing to a single multiplier") asserting that parsing `E3-E2 G` and re-exporting yields `E5 G` — pinning the intentional asymmetry between input (preserves the authored split) and export (collapses it)._
+- ✅ **Five required spec cases present** (intra-measure split, cross-barline [asserts the deferral error], chain, mismatched pitch, MusicXML `<tied>`), plus bonus error-path coverage (dangling tie, no-preceding-note, tie-to-rest, whole-bar simple-meter tie).
+
+### Code review findings
+
+1. **(Should-fix, confirmed bug) `handle_broken_rhythm` does not reject an open tie — silent wrong output.** `parser.rb:277-289`. Every other terminator calls `reject_open_tie`, but this one was overlooked; its guard checks only `awaiting_scale`/`pending_note.nil?`. Verified: `A->A` parses **without error** into a bogus "dotted eighth tied to sixteenth" (both the tie and the broken-rhythm ×3/2·×1/2 scaling applied at once) instead of raising like `A-z` or `A-|` do. Fix: add `reject_open_tie(state, token.line, "A tie must be followed by a note")` at the top of `handle_broken_rhythm`, with a spec for `A->A` / `A-<A`.
+2. **(Nice-to-have) Pitch match mixes two comparison semantics.** `parser.rb:252` — `pending.pitches.sort == pitches.sort`. `sort` orders by `Pitch#<=>` (MIDI number; enharmonics tie), then array `==` compares by `Pitch#==` (spelling). They disagree on enharmonics, so `^C-_D` is rejected as "same pitch" mismatch — defensible, but worth a one-line "why" comment.
+3. **(Nice-to-have) Bar-line tie message can mislead.** `parser.rb:294` — `E3-|]` (dangling tie at a section end) reports "Ties across barlines are not yet supported" though nothing crosses a barline. Minor; the terminator can't distinguish the two cases and the message is right for the tested `E3-|E3`.
+
+### Test coverage gaps
+
+- **Tie + broken rhythm** (`A->A`) — the untested path behind finding #1.
+- **Successful chord-to-chord tie** — the lexer tokenizes `[CEG]-c`, but no parser spec fuses a chord tie into one placement.
+- **Open tie across a voice change** (`parser.rb:318`) and **across a volta** (`parser.rb:308`) — both `reject_open_tie` branches are unexercised.
+
+### Blocks `finish`?
+
+Nothing outstanding. **Finding #1** (the `A->A` silent-miscompute) has been fixed: `handle_broken_rhythm` now calls `reject_open_tie` and `A->A`/`A-<A` raise a clear `ParseError`, with a covering spec. The two follow-up items called out under criteria 4 and 7 have also been addressed — the export round-trip spec was added and the deferred cross-barline AC was annotated. The remaining nice-to-haves (pitch-comparison comment, bar-line message wording, chord-to-chord / voice-change / volta coverage) are non-blocking.
+
+## Learnings
+
+**What went well**
+
+- The plan's central bet held: because the greedy resolver already emits tied chains, the entire tie *rendering* path (`RhythmicValue.tied_value` → MusicXML `<tie>`/`<tied>`) already existed. No writer changes were needed, so the work collapsed to the input boundary (lexer + parser) and stayed small.
+- The "keep the left note pending, close the tie when its right note arrives" state machine composed cleanly with the existing broken-rhythm deferral and gave tie chains (`E2-E2-E2`) for free.
+
+**What was surprising**
+
+- The `reject_open_tie` guard had to be called by *every* non-note terminator, and `handle_broken_rhythm` was the one that got missed — the review caught a genuine silent miscompute (`A->A` applied both the tie and the broken-rhythm scaling with no error).
+- Cross-barline ties — the primary real-world reason ties exist in ABC — had to be deferred, because a single `Placement` cannot span a bar (`ensure_notes_within_barlines`). The feature the story most wanted is the one v1 does not ship.
+- The input/export asymmetry (input preserves an authored split; export collapses it to one multiplier) is intentional but was easy to overlook until a spec pinned it.
+
+**What to do differently next time**
+
+- When introducing a cross-cutting guard that "every terminator must call," write one spec per guard branch — the missing terminator failed silently precisely because it had no test.
+- Annotate a deferred acceptance criterion in the AC text at *plan* time, not review time, so the backlog never overstates what shipped.
+- Cut a `story/<name>` branch. Work went straight onto `main` (acceptable for this rebase-flow repo, but the review/finish tooling assumes a story branch and had to diff commit ranges instead).

data/user-stories/done/musicxml-chord-rendering.md

@@ -0,0 +1,191 @@
+<!--
+metadata:
+  created_at:   2026-07-17T12:54:19-07:00
+  activated_at: 2026-07-18T20:22:35-07:00
+  planned_at:   2026-07-18T20:30:54-07:00
+  finished_at:  2026-07-18T20:44:44-07:00
+  updated_at:   2026-07-18T20:44:44-07:00
+-->
+
+# Story: MusicXML Chord Rendering
+
+## Summary
+
+AS a developer using HeadMusic
+
+I WANT `Composition#to_musicxml` to render chord placements as stacked notes
+
+SO THAT block chords display on one staff in MusicXML-consuming renderers (OSMD, MuseScore, etc.)
+
+## Background
+
+The content model represents a chord as a single `Placement` holding two or more pitched sounds (see the Chord Placement Model and Sound Model stories): one position, one rhythmic value, many sounds. `Placement#sounds` (a frozen array) is the source of truth — each sound is a `Rudiment::Pitch` or a `Rudiment::UnpitchedSound` — with `Placement#pitches` as the derived pitched subset and `chord?` true when there are two or more pitched sounds. Because a chord is one placement, `Voice#first_gap` contiguity works by construction — no special grouping is needed. The MusicXML writer, however, currently guards against chords: it raises when it encounters a placement where `chord?` is true, because it only knows how to emit the single derived `placement.pitch` (the highest pitch) and would otherwise silently render the top note alone. It never emits the `<chord/>` element, which is how MusicXML marks a note as sounding simultaneously with the previous note. (The writer's separate `RenderError` guard for placements containing unpitched sounds is out of scope here — it remains until a dedicated percussion-rendering story.)
+
+This story is a prerequisite for BardTheory's staff-notation-view story, which renders compositions via `to_musicxml` → OSMD and requires block chords on the treble staff. The complementary input half is [ABC Chord Input](abc-chord-input.md) — that story gets chords *into* the model; this one gets them *out* to notation.
+
+## Scope
+
+- Replace the writer's chord guard with real rendering: a chord placement emits one `<note>` element per *pitched* sound, first note plain, each subsequent note carrying `<chord/>`, per the MusicXML 4.0 convention. All notes share the placement's rhythmic value.
+- Emit chord notes in a deterministic order (low to high) regardless of the insertion order of the placement's `sounds`.
+- Leave the writer's `RenderError` guard for unpitched sounds in place — any placement containing an unpitched sound still raises until a percussion-rendering story lands.
+- Chords spanning voices are *not* merged — each voice remains its own part; only the pitched sounds of a single placement form a chord.
+
+## Example
+
+```ruby
+composition = HeadMusic::Content::Composition.new(name: "Chorale", key_signature: "C major", meter: "4/4")
+voice = composition.add_voice(role: "Treble")
+voice.place("1:1", :half, %w[C4 E4 G4])
+voice.place("1:3", :half, %w[D4 F4 A4])
+
+xml = composition.to_musicxml
+# E4 and G4 <note> elements at beat 1 each contain <chord/>; OSMD renders two stacked triads
+```
+
+## Acceptance Criteria
+
+- A chord placement emits one `<note>` per pitched sound as a MusicXML chord (`<chord/>` on all but the first note), replacing the writer's raise-on-chord guard
+- A composition mixing chords and single notes renders with correct measure durations
+- Chord notes emit low to high
+- The writer's `RenderError` guard for unpitched sounds is unchanged
+- Existing single-line compositions render byte-identically to before (no regression)
+- Output validates against the MusicXML 4.0 schema (matching the writer's existing spec approach)
+- Rubocop and all specs pass
+
+## Implementation Plan
+
+### Overview
+
+Replace the writer's raise-on-chord guard with a single parametrized note-builder that emits one `<note>` per pitched sound of a placement — the lowest note plain, each higher note carrying `<chord/>` — sorted low→high, sharing the placement's rhythmic value. The single-note and rest paths collapse to the same builder so existing output stays byte-identical. The change is confined to `lib/head_music/notation/music_xml/writer.rb` and its spec.
+
+### Steps
+
+1. **Remove the chord guard and restructure `note_lines`** — `lib/head_music/notation/music_xml/writer.rb:313`
+   - Delete the `raise RenderError ... "chords are not yet supported"` line (`:315`). Keep `ensure_pitched_sounds` first — it still raises for any unpitched sound, so every non-rest placement reaching the builder is fully pitched (this is what makes the unpitched-sound guard AC hold unchanged).
+   - Nest the loops **components outer, pitches inner** so each tied rhythmic segment emits a complete, contiguous chord block. This ordering is load-bearing: pitches-outer would break `<chord/>` adjacency and produce invalid MusicXML.
+
+   ```ruby
+   def note_lines(placement)
+     ensure_pitched_sounds(placement)
+
+     components_by_placement[placement].flat_map do |component|
+       note_slots(placement).each_with_index.flat_map do |pitch, index|
+         note_element_lines(placement, component, pitch: pitch, chord: index.positive?)
+       end
+     end
+   end
+
+   # ensure_pitched_sounds has rejected any unpitched sound, so a sounded
+   # placement's pitches are all its sounds; a rest emits one empty slot.
+   def note_slots(placement)
+     placement.rest? ? [nil] : placement.pitches.sort
+   end
+   ```
+
+   - `placement.pitches.sort` yields low→high (Pitch is `Comparable`); this is the explicit sort the ordering AC requires — `pitches` is otherwise insertion-ordered. `index.positive?` puts `<chord/>` on all but the lowest note. For a single-pitch placement this is a one-element array at index 0 (`chord: false`), and `pitches.sort.first == placement.pitch` for length 1, preserving today's output exactly.
+
+2. **Parametrize the note builder (rename `component_lines` → `note_element_lines`)** — `writer.rb:330`
+   - One builder serves single note, rest, and chord — no second code path to drift.
+
+   ```ruby
+   def note_element_lines(placement, component, pitch: nil, chord: false)
+     [
+       "#{INDENT * 3}<note>",
+       *(chord ? ["#{INDENT * 4}<chord/>"] : []),
+       *(pitch ? pitch_lines(pitch) : ["#{INDENT * 4}<rest/>"]),
+       "#{INDENT * 4}<duration>#{component.duration}</duration>",
+       *tie_lines(placement, component),
+       "#{INDENT * 4}<type>#{component.type}</type>",
+       *Array.new(component.dots) { "#{INDENT * 4}<dot/>" },
+       *notation_lines(placement, component),
+       "#{INDENT * 3}</note>"
+     ]
+   end
+   ```
+
+   - Byte-identical guarantees: `<chord/>` sits at `INDENT * 4`, first child after `<note>` and **before** `<pitch>` (MusicXML schema requires this order — the one correctness detail that must be right); the `chord ? [...] : []` splat contributes zero lines when false. The rest branch now keys off the passed `pitch:` arg (nil → `<rest/>`) instead of `placement.pitched?`; equivalent because `note_slots` only yields nil for a rest.
+   - `tie_lines`/`notation_lines` are unchanged and already per-component + rest-guarded, so each note in a chord (and each tied link) carries its own correctly-matched tie — no chord-specific tie work needed.
+
+3. **Rewrite the two chord specs; add coverage** — `spec/head_music/notation/music_xml/writer_spec.rb`
+   - **Flip** the two "raises the chord render error" contexts (`:465-479` three-pitch, `:481-495` two-pitch) from raise-assertions to rendering assertions — they currently pin the removed behavior and will otherwise fail.
+   - See Testing Strategy for the exact cases.
+
+4. **Run the checks**
+
+   ```
+   bundle exec rspec spec/head_music/notation/music_xml/writer_spec.rb
+   bundle exec rubocop -a
+   bundle exec rake
+   ```
+
+### Design & Notation-Output Considerations
+
+- **`<chord/>` before `<pitch>`, per subsequent note** is the single highest-risk detail — both OSMD and MuseScore mis-parse a `<chord/>` that follows `<pitch>`. The builder above places it correctly.
+- **Iterate `placement.pitches`, never reuse `placement.pitch`** (which is `pitches.max`, the top note only). Reusing it would print the top pitch on every chord note — the most likely refactor bug.
+- **Low→high order is cosmetic to renderers** (both sort internally) but is the right choice: deterministic, diff-stable, and the conventional bass-up reading order. It must come from the explicit `.sort`, not insertion order.
+- **`<stem>`/`<voice>`/`<staff>` omission is fine for v1** single-voice, single-staff block chords, consistent with how single notes already render (the writer emits none today). Consumers default absent voice/staff to 1, and `<chord/>` alone binds the stack. The boundary where `<voice>` stops being optional is multi-voice-per-staff — out of scope, tracked below.
+- **Clusters/seconds (C4+D4) and shared-letter accidentals (C4+C#4) are the renderer's job** — each note carries its own `<alter>`; OSMD/MuseScore handle notehead offset and accidental columns automatically. No writer work for v1.
+
+### Accessibility / Semantic Fidelity
+
+Traditional WCAG/keyboard/ARIA do not apply (this emits a string, not a UI). The surface is MusicXML semantic fidelity for Braille-music and MusicXML-reading assistive tools:
+
+- **`<chord/>` on notes sharing a rhythmic value IS the canonical encoding** these tools recognize — a lead `<note>` followed by `<chord/>` siblings with no intervening `<backup>`/`<forward>`. No richer encoding needed.
+- **Low→high ordering gives a predictable reading order**, matching Braille music's bass-relative interval convention. Reinforces the explicit-sort requirement.
+- **No semantic loss**: each tone keeps full absolute `<pitch>` (step/alter/octave); sharing one `<duration>`/`<type>` is spec-required, not a loss.
+
+### Testing Strategy
+
+"Validates against the MusicXML 4.0 schema" is satisfied here by the repo's actual approach — there is **no** XSD/DTD tooling; do not add a Nokogiri XSD dependency. Verification is: REXML well-formedness via `parse_musicxml` (`spec/support/music_xml_helpers.rb`), XPath structural assertions, and the byte-for-byte golden-document test. (See the AC note: treat "schema validation" as these concrete facts.)
+
+In `spec/head_music/notation/music_xml/writer_spec.rb`, using the existing helpers (`parse_musicxml`, `xpath_count`, `xpath_texts`):
+
+- **Three-pitch chord** `voice.place("1:1", :half, %w[C4 E4 G4])`: `//note` count == 3 for the measure; `xpath_count(document, "//note/chord")` == 2; the lowest note (C4) has no `<chord/>`; all three share `<duration>`.
+- **Insertion-order independence**: place `%w[G4 C4 E4]` and assert `xpath_texts(document, "//note/pitch/step")` == `%w[C E G]` (low→high regardless of input order).
+- **`<chord/>` element ordering** (child-order, invisible to count-only XPath): assert against the rendered `to_s` that `<chord/>` precedes `<pitch>` — cleanest via a **golden-document fixture** with a chord measure (extend the existing golden test at `:173`, the only mechanism in the suite that catches child-ordering regressions), or a targeted string `include`.
+- **Two-pitch boundary**: rewrite the `:481` context to assert emission, pinning `chord?`-true-at-exactly-2.
+- **Mixed chords + single notes measure**: `place("1:1", :half, %w[C4 E4 G4]); place("1:3", :half, "D5")` — assert per-note durations and correct note count (measure-duration AC; confirms only the lead note advances the cursor).
+- **Tied chord** (if kept in v1 — see Open Questions): a chord with a tied rhythmic value → each tie-link emits a full chord stack with `<chord/>` on the upper notes and ties on every note.
+- **Keep green** the unpitched (`:497`) and mixed pitched+unpitched (`:513`) percussion-raise contexts, and the single-line regression contexts (`SPEED_THE_PLOUGH` at `:22`, the golden document at `:173`) — these are the no-regression / byte-identical guard.
+
+### Risks & Open Questions
+
+- **Tied-chord handling in v1 — recommended IN, needs sign-off.** A chord with a tied rhythmic value is reachable through the public `Voice#place` API (`components_by_placement` expands it into multiple tie-link components). The components-outer/pitches-inner nesting handles it correctly with **zero extra code**, and every pitch legitimately shares the link's tie flags. Recommendation: ship the natural handling. The alternative is an explicit `RenderError` guarded by `components_by_placement[placement].length > 1 && placement.chord?` plus a deferral note — but do **not** leave it to silently drop ties. This plan assumes full tied-chord rendering.
+- **Byte-identical regression** is the primary technical risk; mitigated by the empty-splat for `chord: false` and by `pitches.sort.first == placement.pitch` for length-1 placements. The existing exact-structure and golden-document specs catch any drift.
+- **Duplicate/enharmonic pitches**: `Placement` already dedups exact duplicates via `sounds.uniq`, so an exact unison cannot reach the writer — no writer-side dedup needed. Two distinct spellings at the same height (C#4 + Db4) are a legitimate diminished-second cluster and correctly emit as two notes; order between them is undefined but harmless.
+- **Multi-voice-per-staff** is the concrete future trigger where omitting `<voice>`/`<staff>` stops being acceptable. Out of scope for v1; track for the multi-voice story.
+
+## Review
+
+_Reviewed 2026-07-18 at commit `0f1f090` (product-manager + code-reviewer agents). Full suite: 5842 examples, 0 failures, 99.76% line coverage; rubocop 0 offenses._
+
+### Acceptance criteria
+
+- ✅ **Chord emits one `<note>` per pitched sound, `<chord/>` on all but the first, guard removed** — `writer.rb` `note_lines`/`note_element_lines`; specs assert 3 notes, 2 `<chord/>`, none on `note[1]`. No raise-on-chord path remains.
+- ✅ **Mixing chords and single notes → correct measure durations** — "measure mixing a chord and a single note" spec: steps `C E G D`, 2 `<chord/>`, durations `2 2 2 2`. Only the lead C4 and D5 advance the cursor → full 4/4 bar.
+- ✅ **Chord notes emit low to high** — `note_slots` returns `placement.pitches.sort`; the "placed high to low" spec (`%w[G4 C4 E4]` → `%w[C E G]`) proves the sort, not coincidental input order.
+- ✅ **Unpitched-sound guard unchanged** — `ensure_pitched_sounds` runs first and raises on the first non-pitched sound; the mixed pitched+unpitched spec confirms it still fires with the same message.
+- ✅ **Single-line output byte-identical** — single note → one slot, `chord: false`, `<chord/>` line omitted; the golden-document test pins the full single-line document byte-for-byte.
+- ✅ **Validates against MusicXML 4.0 schema (repo's approach)** — every chord spec parses via REXML + XPath; the golden-string "exact note markup" spec pins `<chord/>`-before-`<pitch>` child order (which count-based XPath cannot see). Caveat, story-acknowledged: no XSD/DTD validator exists in the repo; "schema-valid" is structural, not tool-verified.
+- ✅ **Rubocop and all specs pass** — verified; tied-chord case also covered (6 notes / 4 `<chord/>`, 3 tie-starts / 3 tie-stops).
+
+### Code review findings
+
+**Verdict: clean — no blocking or should-fix issues.** Correctness verified on `<chord/>` placement/order, low→high sort, byte-identical single-note/rest paths, tied-chord loop nesting (index resets per tie-link), and guard interaction (no silent empty-slot path). Both new comments explain "why" and earn their place.
+
+Nits (non-blocking, no action taken):
+
+- `note_slots` re-sorts pitches once per tie-link (N times for an N-link tied chord). Negligible; hoisting would churn the diff.
+- Enharmonic/duplicate pitches at the same height (C4 + B♯3) render as two chord notes — arguably correct MusicXML, untested. Add a spec only if the domain cares.
+- Minor coverage: "correct measure durations" is proven indirectly (duration list + `<chord/>` count) rather than by an explicit sum-to-bar-length assertion. Low risk.
+- `note_slots` naming is slightly abstract; the comment carries the meaning.
+
+**Nothing blocks `finish`.**
+
+## Learnings
+
+- **Planning earned its keep on two judgment calls.** It surfaced the tied-chord decision as an explicit sign-off point rather than a silent implementation choice, and it reconciled the "validates against the MusicXML 4.0 schema" AC against the repo's *actual* verification approach (REXML well-formedness + XPath + a byte-for-byte golden document). That stopped us from adding an unneeded XSD/Nokogiri dependency to satisfy a criterion the existing tooling already covers.
+- **The one surprise was a stale spec outside the writer's own file.** `composition_serialization_spec.rb` still pinned the old raise-on-chord behavior. The single-file spec run was green; only the full `bundle exec rake` suite caught it. Takeaway: when removing a guard or changing an error contract, grep the whole codebase for tests asserting the old behavior before assuming the change is done — don't trust a scoped run.
+- **Tied chords cost zero extra code.** The components-outer / pitches-inner loop nesting composed cleanly with the model's existing expansion of a tied rhythmic value into per-link components; each link just emits a fresh full chord stack. Shipping the natural handling (rather than a guard-and-defer) was the low-risk call.
+- **Child order is invisible to count-based XPath.** Asserting `<chord/>` precedes `<pitch>` needed a golden-string test; the structural XPath count/text assertions could confirm *how many* chord elements existed but never *where* they sat in the note. Reach for a string/golden assertion whenever element ordering is the property under test.
+- **Byte-identical regression was the real risk, and it was cheap to neutralize.** The empty-when-false splat for the `<chord/>` line plus `pitches.sort.first == placement.pitch` for length-1 placements kept single-note output identical, and the pre-existing golden document guarded it — no new machinery required.

data/user-stories/index.html

@@ -254,10 +254,6 @@
     // one-liner preserved across regenerations (see /stories board).
     const stories = {
   "backlog": [
-    {
-      "title": "MusicXML Chord Rendering",
-      "path": "backlog/musicxml-chord-rendering.md"
-    },
     {
       "title": "LilyPond Export",
       "path": "backlog/lilypond-export.md"
@@ -266,10 +262,6 @@
       "title": "LilyPond Interpreter",
       "path": "backlog/lilypond-interpreter.md"
     },
-    {
-      "title": "Organizing Content",
-      "path": "backlog/organizing-content.md"
-    },
     {
       "title": "Sixteenth-Century (Renaissance) Style Guides",
       "path": "backlog/sixteenth-century-style.md"
@@ -277,10 +269,22 @@
     {
       "title": "Split Counterpoint Species Guides by Pedagogical Author",
       "path": "backlog/split-counterpoint-species-by-author.md"
+    },
+    {
+      "title": "Untitled",
+      "path": "backlog/organizing-content.md"
     }
   ],
   "active": [],
   "done": [
+    {
+      "title": "ABC Tie Input",
+      "path": "done/abc-tie-input.md"
+    },
+    {
+      "title": "MusicXML Chord Rendering",
+      "path": "done/musicxml-chord-rendering.md"
+    },
     {
       "title": "ABC Chord Input",
       "path": "done/abc-chord-input.md"
@@ -390,16 +394,16 @@
       "path": "done/sonority-identification.md"
     },
     {
-      "title": "expand-playing-techniques",
-      "path": "done/expand-playing-techniques.md"
+      "title": "Untitled",
+      "path": "done/superclass-for-note.md"
     },
     {
-      "title": "instrument-variant",
-      "path": "done/instrument-variant.md"
+      "title": "Untitled",
+      "path": "done/expand-playing-techniques.md"
     },
     {
-      "title": "superclass-for-note",
-      "path": "done/superclass-for-note.md"
+      "title": "Untitled",
+      "path": "done/instrument-variant.md"
     }
   ]
 };

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: head_music
 version: !ruby/object:Gem::Version
-  version: 17.0.0
+  version: 17.2.0
 platform: ruby
 authors:
 - Rob Head
@@ -417,13 +417,13 @@ files:
 - user-stories/_template.md
 - user-stories/backlog/lilypond-export.md
 - user-stories/backlog/lilypond-interpreter.md
-- user-stories/backlog/musicxml-chord-rendering.md
 - user-stories/backlog/organizing-content.md
 - user-stories/backlog/sixteenth-century-style.md
 - user-stories/backlog/split-counterpoint-species-by-author.md
 - user-stories/done/abc-chord-input.md
 - user-stories/done/abc-notation-export.md
 - user-stories/done/abc-notation-interpreter.md
+- user-stories/done/abc-tie-input.md
 - user-stories/done/chord-placement-model.md
 - user-stories/done/composition-serialization.md
 - user-stories/done/configurable-large-leap-recovery.md
@@ -443,6 +443,7 @@ files:
 - user-stories/done/move-staff-mapping-to-notation.md
 - user-stories/done/move-staff-position-to-notation.md
 - user-stories/done/music-xml-export.md
+- user-stories/done/musicxml-chord-rendering.md
 - user-stories/done/notation-module-foundation.md
 - user-stories/done/notation-style.md
 - user-stories/done/percussion_set.md

data/user-stories/backlog/musicxml-chord-rendering.md

@@ -1,57 +0,0 @@
-<!--
-metadata:
-  created_at:   2026-07-17T12:54:19-07:00
-  activated_at:
-  planned_at:
-  finished_at:
-  updated_at:   2026-07-18T16:03:28-07:00
--->
-
-# Story: MusicXML Chord Rendering
-
-## Summary
-
-AS a developer using HeadMusic
-
-I WANT `Composition#to_musicxml` to render chord placements as stacked notes
-
-SO THAT block chords display on one staff in MusicXML-consuming renderers (OSMD, MuseScore, etc.)
-
-## Background
-
-The content model represents a chord as a single `Placement` holding two or more pitched sounds (see the Chord Placement Model and Sound Model stories): one position, one rhythmic value, many sounds. `Placement#sounds` (a frozen array) is the source of truth — each sound is a `Rudiment::Pitch` or a `Rudiment::UnpitchedSound` — with `Placement#pitches` as the derived pitched subset and `chord?` true when there are two or more pitched sounds. Because a chord is one placement, `Voice#first_gap` contiguity works by construction — no special grouping is needed. The MusicXML writer, however, currently guards against chords: it raises when it encounters a placement where `chord?` is true, because it only knows how to emit the single derived `placement.pitch` (the highest pitch) and would otherwise silently render the top note alone. It never emits the `<chord/>` element, which is how MusicXML marks a note as sounding simultaneously with the previous note. (The writer's separate `RenderError` guard for placements containing unpitched sounds is out of scope here — it remains until a dedicated percussion-rendering story.)
-
-This story is a prerequisite for BardTheory's staff-notation-view story, which renders compositions via `to_musicxml` → OSMD and requires block chords on the treble staff. The complementary input half is [ABC Chord Input](abc-chord-input.md) — that story gets chords *into* the model; this one gets them *out* to notation.
-
-## Scope
-
-- Replace the writer's chord guard with real rendering: a chord placement emits one `<note>` element per *pitched* sound, first note plain, each subsequent note carrying `<chord/>`, per the MusicXML 4.0 convention. All notes share the placement's rhythmic value.
-- Emit chord notes in a deterministic order (low to high) regardless of the insertion order of the placement's `sounds`.
-- Leave the writer's `RenderError` guard for unpitched sounds in place — any placement containing an unpitched sound still raises until a percussion-rendering story lands.
-- Chords spanning voices are *not* merged — each voice remains its own part; only the pitched sounds of a single placement form a chord.
-
-## Example
-
-```ruby
-composition = HeadMusic::Content::Composition.new(name: "Chorale", key_signature: "C major", meter: "4/4")
-voice = composition.add_voice(role: "Treble")
-voice.place("1:1", :half, %w[C4 E4 G4])
-voice.place("1:3", :half, %w[D4 F4 A4])
-
-xml = composition.to_musicxml
-# E4 and G4 <note> elements at beat 1 each contain <chord/>; OSMD renders two stacked triads
-```
-
-## Acceptance Criteria
-
-- A chord placement emits one `<note>` per pitched sound as a MusicXML chord (`<chord/>` on all but the first note), replacing the writer's raise-on-chord guard
-- A composition mixing chords and single notes renders with correct measure durations
-- Chord notes emit low to high
-- The writer's `RenderError` guard for unpitched sounds is unchanged
-- Existing single-line compositions render byte-identically to before (no regression)
-- Output validates against the MusicXML 4.0 schema (matching the writer's existing spec approach)
-- Rubocop and all specs pass
-
-## Implementation Plan
-
-[to be filled in by /stories plan]