head_music 17.1.0 → 17.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ccf6929bc722709c08c2c8dc59589b86dce287ee2d698c087e75aa785140e75a
-  data.tar.gz: 3eb787b72cbb4a298d35cb6006aeb6901cda74b407c2a62ce9e6e98e1ea949b5
+  metadata.gz: d5c0dadcdb3b7bba85e7de810d0d52d960e6bf2b9386b62db9ec201336e084bb
+  data.tar.gz: 33c3b42e6b07ed88649b6fb0c7b42476c9d45edbc18ef0cc458ff8978b876c4c
 SHA512:
-  metadata.gz: 5d78981006e4f26848e304e1413d5b317410142aa361229dbca4703799d144cf196ee3dbec9139a9e35e1b3d77186e0194abee001251f59db8c7e5f4e85e0eff
-  data.tar.gz: 60a2308fd83f8123437d027a7b86aa543767b7b7b9595d08036639cabbf13557cfb57f5f51de7a0b68c1c91742ad29ffb780b4a79162f02becbf610529b1eea7
+  metadata.gz: eb3e9c1f84f2efbf87947a2037b9804cf9e16247be5c180509cb06a9c3c66229513b8cdcc2e10fa1d8f2f7ed952b91de99375e5939de33665aec909331f8f115
+  data.tar.gz: f871c26bf5da1052474f5317d72788df760f994f3264dbebc6ad35e91b91124088378524b46f4fc50721f6b9442453978018f6c012dd40f55926a66dd516539c

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [17.3.0] - 2026-07-19
+
+### Added
+
+- The MusicXML writer emits `<beam>` elements so exported notation renders with correct beaming rather than relying on renderer-side auto-beaming (which mis-groups compound meters). Default beam groups are derived from the meter at render time — the dotted-quarter pulse for compound meters (6/8, 9/8, 12/8), the beat for simple quarter meters, and the whole bar for 3/8 — via a new `HeadMusic::Rudiment::Meter#beam_group_unit`. Grouping resolves at the notated-note level, so a tied chain beams correctly across its own noteheads, and secondary beams (sixteenths and finer) render with begin/continue/end runs plus forward/backward partial-beam hooks.
+- The ABC interpreter captures authored beam grouping from inter-note spacing: adjacent notes beam together and a space breaks the beam, honored verbatim (even across a beat). This is carried on a new tri-state `HeadMusic::Content::Placement#beam_break_before` flag (`nil` = meter default, `true` = break, `false` = join) that overrides the default on output, serializes through `to_h`/`from_h`, and survives an ABC parse → render → parse round trip (the writer suppresses the space within an authored group).
+
+## [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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (17.1.0)
+    head_music (17.3.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/content/composition.rb

@@ -215,7 +215,8 @@ class HeadMusic::Content::Composition
           position = parsed_position(placement_hash["position"], path)
           rhythmic_value = parsed_rhythmic_value(placement_hash["rhythmic_value"], path)
           sounds = parsed_placement_sounds(placement_hash, path)
-          voice.place(position, rhythmic_value, sounds)
+          placement = voice.place(position, rhythmic_value, sounds)
+          placement.beam_break_before = placement_hash["beam_break_before"] if placement_hash.key?("beam_break_before")
         end
       end
     end

data/lib/head_music/content/placement.rb

@@ -7,6 +7,13 @@ class HeadMusic::Content::Placement
 
   attr_reader :voice, :position, :rhythmic_value, :sounds
 
+  # Authored beam grouping relative to the previous placement, set after
+  # construction (the Bar-style side-metadata pattern). Tri-state: nil = use
+  # the meter-derived default, true = force a beam break before this placement,
+  # false = force a beam join to the previous placement. Consumed by the
+  # MusicXML writer, which prefers it over the default grouping.
+  attr_accessor :beam_break_before
+
   delegate :composition, to: :voice
   delegate :spelling, to: :pitch, allow_nil: true
 
@@ -85,11 +92,13 @@ class HeadMusic::Content::Placement
   end
 
   def to_h
-    {
+    hash = {
       "position" => position.to_s,
       "rhythmic_value" => rhythmic_value.to_s,
       "sounds" => sounds.map { |sound| sound_datum(sound) }
     }
+    hash["beam_break_before"] = beam_break_before unless beam_break_before.nil?
+    hash
   end
 
   private

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

@@ -107,19 +107,35 @@ class HeadMusic::Notation::ABC::BodyLexer
     Token.new(type: :voice_change, line: line_number, column: 1, voice_id: voice_id)
   end
 
+  # Music tokens whose whitespace successor breaks a beam group; other
+  # tokens (bar lines, ties, etc.) already interrupt beaming on their own.
+  BEAMABLE_TOKEN_TYPES = [:note, :rest, :chord].freeze
+
   # Returns true when the line ends with a continuation backslash.
   def scan_line(line_text, line_number, tokens)
     scanner = StringScanner.new(line_text)
     until scanner.eos?
-      next if scanner.skip(/[ \t]+/)
+      spaced = scanner.skip(/[ \t]+/)
       break if scanner.skip(/%/)
       return true if scanner.skip(/\\[ \t]*\z/)
+      break if scanner.eos?
 
+      tokens << beam_break_token(scanner, line_number) if spaced && beamable_predecessor?(tokens.last)
       scan_token(scanner, line_number, tokens)
     end
     false
   end
 
+  # A beam break only matters after a music token; whitespace elsewhere
+  # (leading, after a bar line) carries no beaming signal.
+  def beamable_predecessor?(token)
+    !token.nil? && BEAMABLE_TOKEN_TYPES.include?(token.type)
+  end
+
+  def beam_break_token(scanner, line_number)
+    Token.new(type: :beam_break, line: line_number, column: scanner.pos + 1)
+  end
+
   def scan_token(scanner, line_number, tokens)
     column = scanner.pos + 1
 
@@ -128,6 +144,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 +294,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,22 @@ 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, :beam_break) do
+      def initialize(pitches:, length:, scale:, tied_prefix: nil, beam_break: 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,
+        :beam_break_pending, :beam_last_was_note
 
       def initialize(voice, pitch_builder)
         @voice = voice
@@ -148,10 +155,12 @@ 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)
       when :voice_change then handle_voice_change(token)
+      when :beam_break then handle_beam_break(token)
       end
     end
 
@@ -207,19 +216,91 @@ 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)
+      flag = if state.beam_break_pending
+        true
+      else
+        (state.beam_last_was_note ? false : nil)
+      end
+      state.beam_break_pending = false
+      state.beam_last_was_note = true
+      state.pending_note = PendingNote.new(pitches: pitches, length: length, scale: scale, beam_break: flag)
+    end
+
+    # The lexer only emits :beam_break after a music token, so a voice
+    # state already exists; the flag is consumed by the next deferred note.
+    def handle_beam_break(_token)
+      current_state.beam_break_pending = true
+    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,
+        beam_break: pending.beam_break
+      )
+    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)
+      reset_beam_adjacency(state)
       place(state, token.length, nil)
     end
 
+    # After a rest, bar line, volta, or voice change, a following note
+    # must not be marked as beamed to whatever preceded the boundary.
+    def reset_beam_adjacency(state)
+      state.beam_last_was_note = false
+      state.beam_break_pending = false
+    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,7 +316,9 @@ 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)
+      reset_beam_adjacency(state)
       tag_completed_bar(state)
       apply_repeat_flags(state, token.style)
       clear_passes_if_over(state, token.style)
@@ -248,7 +331,9 @@ 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)
+      reset_beam_adjacency(state)
       state.active_passes = token.passes
       state.volta_start_bar = state.entered_bar_number
     end
@@ -257,7 +342,9 @@ 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)
+        reset_beam_adjacency(@current_state)
       end
       @current_state = voice_state(token.voice_id)
     end
@@ -265,6 +352,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 +372,23 @@ module HeadMusic::Notation::ABC
       return unless pending
 
       state.pending_note = nil
-      place(state, pending.length, pending.pitches, scale: pending.scale)
+      placement = state.voice.place(state.voice.next_position, pending_rhythmic_value(pending), pending.pitches)
+      placement.beam_break_before = pending.beam_break
+    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/abc/writer.rb

@@ -115,7 +115,21 @@ module HeadMusic::Notation::ABC
       bar_groups.each_with_index.map do |bar_placements, index|
         # Accidental state must mirror what a re-parse accumulates bar by bar.
         pitch_writer.start_new_bar if index.positive?
-        bar_placements.map { |placement| token(placement, pitch_writer, duration_writer) }.join(" ")
+        tokens = bar_placements.map { |placement| token(placement, pitch_writer, duration_writer) }
+        join_bar_tokens(bar_placements, tokens)
+      end
+    end
+
+    # Suppresses the inter-token space only where the following placement was
+    # authored as beamed to its predecessor (beam_break_before == false).
+    # A true or nil flag keeps the space, so programmatic (nil-flag)
+    # compositions render with today's every-token spacing. Every bar token
+    # (note, rest, or [..] chord) re-lexes unambiguously with no separator, so
+    # dropping the space is safe.
+    def join_bar_tokens(placements, tokens)
+      tokens.each_with_index.reduce(+"") do |line, (token, index)|
+        separator = (index.zero? || placements[index].beam_break_before == false) ? "" : " "
+        line << separator << token
       end
     end
 

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

@@ -0,0 +1,108 @@
+# A namespace for MusicXML-notation rendering helpers
+module HeadMusic::Notation::MusicXML
+  # Computes MusicXML <beam> annotations for the ordered noteheads of one
+  # measure. Pure and side-effect-free: data in, data out. The Writer builds
+  # the Event list and turns the returned Beams into XML.
+  class BeamGrouper
+    # A single <beam number="N">type</beam> annotation.
+    Beam = Struct.new(:number, :type, keyword_init: true)
+
+    # One notehead's beaming inputs.
+    # - levels: beams this notehead carries alone (eighth=1, sixteenth=2, ...);
+    #   a rest or quarter-or-longer note is 0 (unbeamable).
+    # - onset: integer offset from the start of the bar, in MusicXML divisions.
+    # - beam_break_before: tri-state override vs. the previous event
+    #   (nil = meter default, true = force break, false = force join).
+    Event = Struct.new(:levels, :onset, :beam_break_before, keyword_init: true)
+
+    def self.annotate(events, group_unit_divisions)
+      new(events, group_unit_divisions).annotate
+    end
+
+    def initialize(events, group_unit_divisions)
+      @events = events
+      @group_unit_divisions = group_unit_divisions
+    end
+
+    def annotate
+      groups.flat_map { |group| beams_for_group(group) }
+    end
+
+    private
+
+    attr_reader :events, :group_unit_divisions
+
+    # Phase A: segment event indices into groups of consecutive indices.
+    def groups
+      result = []
+      events.each_index do |i|
+        if i.zero? || break_before?(i)
+          result << [i]
+        else
+          result.last << i
+        end
+      end
+      result
+    end
+
+    def break_before?(index)
+      event = events[index]
+      return true if event.levels.zero?
+      return true if events[index - 1].levels.zero?
+      return true if event.beam_break_before == true
+      return false if event.beam_break_before == false
+
+      (event.onset % group_unit_divisions).zero?
+    end
+
+    # Phase B: emit one Array<Beam> per member, parallel to the group's events.
+    def beams_for_group(group)
+      return [[]] if group.size == 1
+
+      member_beams = Array.new(group.size) { [] }
+      max_level = group.map { |i| events[i].levels }.max
+      (1..max_level).each { |level| add_level_beams(group, level, member_beams) }
+      member_beams
+    end
+
+    def add_level_beams(group, level, member_beams)
+      participating(group, level).each do |run|
+        emit_run(run, level, member_beams)
+      end
+    end
+
+    # Maximal runs of consecutive-within-the-group positions whose event has
+    # levels >= level. Positions are indices into `group` (and member_beams).
+    def participating(group, level)
+      runs = []
+      group.each_with_index do |event_index, position|
+        if events[event_index].levels >= level
+          (runs.last && runs.last.last == position - 1) ? runs.last << position : runs << [position]
+        end
+      end
+      runs
+    end
+
+    def emit_run(run, level, member_beams)
+      if run.size == 1
+        position = run.first
+        # A lone member at this level gets a partial beam (hook). It points
+        # backward unless it is the group's first member, which has nothing
+        # to hook back to.
+        member_beams[position] << Beam.new(number: level, type: position.zero? ? "forward hook" : "backward hook")
+        return
+      end
+
+      run.each_with_index do |position, offset|
+        member_beams[position] << Beam.new(number: level, type: run_type(offset, run.size))
+      end
+    end
+
+    def run_type(offset, run_size)
+      return "begin" if offset.zero?
+      return "end" if offset == run_size - 1
+
+      "continue"
+    end
+  end
+end

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

@@ -19,6 +19,17 @@ module HeadMusic::Notation::MusicXML
     # carriage return, even as character references.
     FORBIDDEN_TEXT_CHARACTERS = /[\u0000-\u0008\u000B\u000C\u000E-\u001F]/
 
+    # The number of beams a notehead of each MusicXML <type> carries alone.
+    # Every other type (quarter and longer) and every rest carries none.
+    BEAM_LEVELS_BY_TYPE = {
+      "eighth" => 1,
+      "16th" => 2,
+      "32nd" => 3,
+      "64th" => 4,
+      "128th" => 5,
+      "256th" => 6
+    }.freeze
+
     attr_reader :composition
 
     def initialize(composition)
@@ -120,6 +131,61 @@ module HeadMusic::Notation::MusicXML
       end
     end
 
+    # A Hash keyed by [placement, component_index] holding the Array<Beam>
+    # that BeamGrouper computed for that notehead. Built one bar at a time so
+    # a notehead's onset is its exact integer offset from the bar start.
+    def beam_annotations
+      @beam_annotations ||= {}.tap do |annotations|
+        composition.voices.each do |voice|
+          bar_numbers.each { |bar_number| annotate_bar(voice, bar_number, annotations) }
+        end
+      end
+    end
+
+    def annotate_bar(voice, bar_number, annotations)
+      placements = placements_by_bar(voice)[bar_number]
+      return unless placements
+
+      keys = []
+      events = build_bar_events(placements, keys)
+      beams = BeamGrouper.annotate(events, group_unit_divisions(bar_number))
+      keys.each_with_index { |key, index| annotations[key] = beams[index] }
+    end
+
+    def build_bar_events(placements, keys)
+      onset = 0
+      placements.flat_map do |placement|
+        components_by_placement[placement].each_with_index.map do |component, component_index|
+          event = BeamGrouper::Event.new(
+            levels: beam_levels(placement, component),
+            onset: onset,
+            beam_break_before: component_index.zero? ? placement.beam_break_before : nil
+          )
+          keys << [placement, component_index]
+          onset += component.duration
+          event
+        end
+      end
+    end
+
+    def beam_levels(placement, component)
+      return 0 if placement.rest?
+
+      BEAM_LEVELS_BY_TYPE.fetch(component.type, 0)
+    end
+
+    # The beam-group span in integer divisions for a bar's effective meter.
+    # DurationWriter.single_quarter_fraction returns an exact Rational, so the
+    # product with the integer divisions is integral for every supported meter.
+    def group_unit_divisions(bar_number)
+      fraction = DurationWriter.single_quarter_fraction(effective_meter(bar_number).beam_group_unit) * divisions
+      unless fraction.denominator == 1
+        raise RenderError,
+          "cannot express the beam group unit as an integer duration at #{divisions} divisions per quarter note"
+      end
+      fraction.to_i
+    end
+
     def bar_numbers
       composition.earliest_bar_number..composition.latest_bar_number
     end
@@ -313,9 +379,12 @@ module HeadMusic::Notation::MusicXML
     def note_lines(placement)
       ensure_pitched_sounds(placement)
 
-      components_by_placement[placement].flat_map do |component|
+      components_by_placement[placement].each_with_index.flat_map do |component, component_index|
+        beams = beam_annotations[[placement, component_index]] || []
         note_slots(placement).each_with_index.flat_map do |pitch, index|
-          note_element_lines(placement, component, pitch: pitch, chord: index.positive?)
+          note_element_lines(
+            placement, component, pitch: pitch, chord: index.positive?, beams: index.zero? ? beams : []
+          )
         end
       end
     end
@@ -338,7 +407,7 @@ module HeadMusic::Notation::MusicXML
     # 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)
+    def note_element_lines(placement, component, pitch: nil, chord: false, beams: [])
       [
         "#{INDENT * 3}<note>",
         *(chord ? ["#{INDENT * 4}<chord/>"] : []),
@@ -347,11 +416,16 @@ module HeadMusic::Notation::MusicXML
         *tie_lines(placement, component),
         "#{INDENT * 4}<type>#{component.type}</type>",
         *Array.new(component.dots) { "#{INDENT * 4}<dot/>" },
+        *beam_lines(beams),
         *notation_lines(placement, component),
         "#{INDENT * 3}</note>"
       ]
     end
 
+    def beam_lines(beams)
+      beams.map { |beam| %(#{INDENT * 4}<beam number="#{beam.number}">#{beam.type}</beam>) }
+    end
+
     def pitch_lines(pitch)
       attributes = PitchWriter.attributes(pitch)
       [

data/lib/head_music/rudiment/meter.rb

@@ -99,6 +99,20 @@ class HeadMusic::Rudiment::Meter < HeadMusic::Rudiment::Base
   # for consistency with conversational usage
   alias_method :beat_unit, :beat_value
 
+  # The span of one default beam group for this meter, as a RhythmicValue.
+  # This is a distinct concern from #beat_value: it is the boundary unit used
+  # to decide where beams break.
+  def beam_group_unit
+    @beam_group_unit ||=
+      if compound?
+        beat_value
+      elsif bottom_number >= 8
+        whole_bar_beam_group_unit
+      else
+        HeadMusic::Rudiment::RhythmicValue.new(count_unit)
+      end
+  end
+
   def to_s
     [top_number, bottom_number].join("/")
   end
@@ -119,6 +133,21 @@ class HeadMusic::Rudiment::Meter < HeadMusic::Rudiment::Base
 
   private
 
+  # For simple meters with an eighth-or-shorter denominator (e.g. 2/8, 3/8),
+  # the whole bar is a single beam group. A triple grouping (3/8) is a dotted
+  # value of the half-denominator unit; a duple grouping (2/8) spans the bar.
+  # Asymmetric meters (5/8, 7/16, ...) are out of scope: their bar has no
+  # single power-of-two unit, so the group unit falls back to the count unit
+  # (each count its own group) rather than raising on a nil unit.
+  def whole_bar_beam_group_unit
+    if (top_number % 3).zero?
+      HeadMusic::Rudiment::RhythmicValue.new(HeadMusic::Rudiment::RhythmicUnit.for_denominator_value(bottom_number / 2), dots: 1)
+    else
+      unit = HeadMusic::Rudiment::RhythmicUnit.for_denominator_value(bottom_number / top_number)
+      HeadMusic::Rudiment::RhythmicValue.new(unit || count_unit)
+    end
+  end
+
   def downbeat?(count, tick = 0)
     beat?(tick) && count == 1
   end

data/lib/head_music/version.rb

@@ -1,3 +1,3 @@
 module HeadMusic
-  VERSION = "17.1.0"
+  VERSION = "17.3.0"
 end

data/user-stories/done/abc-notation-beaming.md

@@ -0,0 +1,235 @@
+<!--
+metadata:
+  created_at:   2026-07-19T16:21:53-07:00
+  activated_at: 2026-07-19T18:37:53-07:00
+  planned_at:   2026-07-19T18:09:39-07:00
+  finished_at:  2026-07-19T20:10:12-07:00
+  updated_at:   2026-07-19T20:10:12-07:00
+-->
+
+# Story: ABC Notation Beaming
+
+## Summary
+
+AS a dev
+I WANT to be able to represent beaming in an ABC import
+SO THAT notation I generate from the resulting Composition has beaming.
+
+## Acceptance Criteria
+
+### Default meter-derived beaming (MusicXML output)
+
+- In a simple meter (2/4, 3/4, 4/4), `MusicXML::Writer` emits `<beam>` elements that group consecutive sub-quarter notes by beat (the count unit).
+- In a compound meter (6/8, 9/8, 12/8), beam groups follow the dotted-quarter pulse — three eighths per group — not the individual eighth. (This is the case OSMD's renderer default gets wrong.)
+- Beam elements read `begin` on the first note of a group, `continue` in the middle, and `end` on the last; a lone flagged note in its own group emits no beam.
+- The `number` attribute reflects the beam level (eighth = 1, sixteenth = 2, …), and mixed values within a group (e.g. an eighth followed by two sixteenths) nest the levels correctly.
+- Quarter-or-longer notes and rests terminate the current beam group — no beam spans them.
+- Beam grouping resolves at the notated-note (`Component`) level, so a note that expands into a tied chain still beams correctly across the tie.
+- Beam groups never cross a barline or a beat/pulse-group boundary.
+
+### Authored-group capture from ABC (override)
+
+- The ABC body lexer preserves inter-note spacing as a beam signal instead of silently discarding it (today: `body_lexer.rb:114` skips `/[ \t]+/` with no token).
+- Adjacent note tokens with no separating space import as one beam group; a space breaks the group — matching ABC's beaming convention.
+- When ABC source expresses an explicit grouping, that authored grouping overrides the meter-derived default on output (the "deliberate deviation" case, same default-vs-override shape as ties).
+- A placement with no authored beam signal falls back to the meter-derived default; an explicit signal is honored verbatim.
+
+### ABC export round-trip
+
+- The ABC writer suppresses the inter-placement space *within* an authored beam group and emits a space at group boundaries, so an authored grouping survives parse → write → parse without loss (today `writer.rb:118` joins every placement with a space, breaking every beam).
+
+## Notes
+
+### Why this feature exists
+
+OSMD's renderer-side default beaming can't handle compound meters, which are central to the material here (6/8 now; counterpoint lives in 3/4, 6/4, cut time…). So head_music must emit beams explicitly rather than lean on the renderer. Consumers render with **autoBeam off** — explicit beams are then authoritative and portable (MuseScore and Dorico honor them too).
+
+### How beaming is represented (design recommendation)
+
+Beaming is **not** modeled like ties. Ties fold into a single `RhythmicValue.tied_value` chain (contained within one note); beaming is a *grouping across multiple notes*, so it cannot live inside one `RhythmicValue`. Two representations, matching the default-vs-override shape:
+
+1. **Default beaming — no model state.** `MusicXML::Writer` derives groups on the fly from `Meter#compound?` / `Meter#beat_value` (`meter.rb:90-100`) plus each note's position and type. A programmatically-built Composition, or ABC with no grouping intent, carries nothing extra.
+2. **Authored override — a lightweight per-`Placement` flag.** In ABC a beam break can only fall *between* note tokens (a space), never inside a single note, so a placement-level signal (e.g. `beam_break_before` / "beamed-to-previous", `nil` by default) is sufficient. This mirrors the side-metadata flags `Bar` already carries (`starts_repeat`, `plays_on_passes`) rather than baking state into `RhythmicValue`. Concrete attribute name is a planning decision.
+
+At render: an explicit placement flag is honored (override); `nil` falls back to the meter default. Within a placement that expands to a tied chain, the internal component-to-component beams still follow type-based rules — the flag only governs the boundary *between* placements.
+
+### Code map (from exploration)
+
+- **Meter grouping primitives** — `Meter#compound?` (`top > 3 && top % 3 == 0`), `Meter#beat_value`/`beat_unit` (dotted-quarter for compound, count unit for simple), `Meter#beats_per_bar`: `lib/head_music/rudiment/meter.rb:38-44, 58-64, 90-100`. Edge case: **3/8 reports `simple?`** (fails `top > 3`) — confirm desired grouping.
+- **MusicXML `<beam>` emission** — insert into `note_element_lines` after `<dot>`/`<stem>` and before `<notations>`: `lib/head_music/notation/music_xml/writer.rb:341-353`. A `Component` is one notated notehead (`duration_writer.rb:7, 44-65`); a placement can expand into several via a tied chain, so beams resolve at the Component level in `note_lines` (`writer.rb:313-321`). No `beam` string exists in `lib` today.
+- **ABC lexer capture** — change the discard at `lib/head_music/notation/abc/body_lexer.rb:114`; add token field(s) near `body_lexer.rb:12-25`.
+- **ABC parser** — placement creation at `parser.rb:165-169, 214-221, 343-349` needs to carry the beam signal onto the Placement (compare with how `tie` state threads through `VoiceState`).
+- **Placement model** — no beam attribute today: `lib/head_music/content/placement.rb:5-8`.
+- **ABC export** — space-joining to make conditional: `lib/head_music/notation/abc/writer.rb:112-120`.
+
+### Reference
+
+Follow the tie feature as the architectural template: `user-stories/done/abc-tie-input.md`. Note the key difference — ties collapsed to the input boundary because the render path already existed; beaming has **no existing data path at all** (new model state + MusicXML emission + ABC space-suppression), so it is a larger change.
+
+## Review
+
+_Reviewed 2026-07-19 at commit `cd35e95` (feature), by product-manager (acceptance criteria) and code-reviewer (code quality). Two follow-up fixes were applied after the review and are described below._
+
+### Acceptance criteria
+
+All 12 criteria **✅ met**, each backed by code and a passing test (full suite green, 5938 examples).
+
+**Default meter beaming (MusicXML)**
+
+- ✅ Simple meter groups sub-quarter notes by beat — `meter.rb` `beam_group_unit` + `writer_spec` "eight default-beamed eighths in 4/4".
+- ✅ Compound meter groups by the dotted-quarter pulse (the renderer-fails case) — `writer_spec` "six default-beamed eighths in 6/8" → two 3-groups.
+- ✅ begin/continue/end; lone note emits no beam — `beam_grouper_spec` size-1 group → `[]`.
+- ✅ `number` = beam level; mixed values nest — `writer_spec` dotted-eighth + sixteenth (level-1 end + level-2 backward hook).
+- ✅ Quarter-or-longer notes and rests terminate a group — `writer_spec` quarter/rest break cases.
+- ✅ Resolves at the Component level; beams across a tied chain — `writer_spec` "tied chain of two eighths inside one beat group".
+- ✅ Never crosses a barline or beat/pulse boundary — per-bar annotation + modulo check; pickup-bar test.
+
+**Authored ABC capture (override)**
+
+- ✅ Lexer preserves inter-note spacing as `:beam_break` — `body_lexer_spec`.
+- ✅ Adjacent → one group, space → break — `parser_spec` flag-sequence tests.
+- ✅ Authored grouping overrides the default — `writer_spec` "authored ABC beam grouping in 4/4".
+- ✅ No signal → meter default; explicit honored — `beam_grouper_spec` tri-state tests.
+
+**ABC export round-trip**
+
+- ✅ Space suppressed within a group, kept at boundaries; survives parse→write→parse — `abc/writer_spec` idempotence + `composition_serialization_spec` JSON round-trip.
+
+### Code review findings
+
+- **Medium — asymmetric simple meters crashed `beam_group_unit`** (`meter.rb`): 5/16, 7/16, etc. produced a non-power-of-two unit → `nil` → `DelegationError` instead of a graceful result, violating the "out of scope but must not crash" constraint. **Fixed:** the duple whole-bar branch now falls back to the count unit when `for_denominator_value` returns `nil`; added `meter_spec` rows for 5/16 and 7/8.
+- **Nit — local `groups` shadowed the method `#groups`** (`beam_grouper.rb`). **Fixed:** renamed the accumulator to `result`.
+- Positives noted: `BeamGrouper` is genuinely pure; integer-only onset arithmetic (no Float drift); the component-vs-placement granularity risk is handled correctly (flag only on component 0, onset accumulates per component); `false`-join correctly cannot bridge a rest/quarter; high-quality XML-output assertions.
+
+### Manual verification (not blockers)
+
+- The MusicXML `<beam>` output has **not** been opened in a real notation reader (MuseScore/Finale/Sibelius). The tests assert correct XML structure; a one-time visual eyeball — especially the 6/8 case and hook direction — is worth doing.
+
+### Verdict
+
+Shippable. Both review findings have been fixed; nothing blocks `finish`. Recommend committing the two fixes before finishing.
+
+## Implementation Plan
+
+### Overview
+
+Beaming is emitted at MusicXML render time from a new stateless helper `HeadMusic::Notation::MusicXML::BeamGrouper`, fed a measure's ordered noteheads and the meter's beam-group unit. Default grouping needs zero model state; ABC-authored grouping is captured as a tri-state `beam_break_before` flag on each `Placement` (the `Bar`-style side-metadata pattern) that overrides the default at placement boundaries. Build in two internally-ordered layers that ship together: default render (Steps 1-3), then authored override (Steps 4-7).
+
+**One "confirmed" assumption is corrected here.** The brief said "simple meter → group by beat (count unit)." Grouping 3/8 by its count unit (the eighth) makes every eighth its own group and emits **no** beam — contradicting the confirmed "3/8 → one group of three eighths." The grouping unit is therefore **not** `Meter#beat_value` for eighth/sixteenth-denominator simple meters. Step 1 introduces a distinct `Meter#beam_group_unit` (whole bar for 3/8 and 2/8, the beat for quarter-or-larger simple meters, the dotted-quarter pulse for compound). 3/8 stays `simple?`; only the beam-grouping unit differs.
+
+### Scope
+
+- **v1 (ships together):** default beaming for simple (2/4, 3/4, 4/4, 3/8) and compound (6/8, 9/8, 12/8) meters; eighths and sixteenths with correct primary (level 1) and secondary (level 2) beams **including forward/backward hooks** (dotted-eighth + sixteenth is ubiquitous and cannot be omitted without visibly wrong output); authored override via the per-Placement flag, honored on render and preserved through ABC export round-trip. Layers 1 and 2 must land in one story — the override is only observable as a deviation from the default, so the default must exist to test it.
+- **Deferred, each with a defined behavior:** 32nd-and-finer levels (logic generalizes but assert only to level 2); tuplet beaming (tuplets already unsupported at the ABC boundary); beaming across a barline (MusicXML forbids it; `ensure_notes_within_barlines` enforces it — beam simply breaks at the barline, silently, matching the tie feature's barline behavior); beam-over-rest (rests always break a group in v1); feathered/cross-staff/slope beams (not expressible in ABC).
+
+### Steps
+
+**1. `Meter#beam_group_unit` — the grouping-boundary source (domain rudiment)**
+
+- Add a method returning the beam-group span as a `RhythmicValue`: dotted-quarter for `compound?`; the whole-bar value for eighth/sixteenth-denominator simple meters (3/8, 2/8); the beat (`count_unit`) for quarter-or-larger simple meters. Keep `beat_value`/`beat_unit` untouched — this is a separate concern (where beams break vs. where beats fall).
+- Files: `lib/head_music/rudiment/meter.rb` (new method near `beat_value` :90-100; reuses `compound?` :42-44, `count_unit` :86-88, `top_number`/`bottom_number`).
+- Tests: `spec/head_music/rudiment/meter_spec.rb` — table-driven across 4/4, 3/4, 2/2, **3/8**, 2/8, 6/8, 9/8, 12/8, asserting the group unit (and its tick/division span). This single spec regression-locks the 3/8 decision.
+
+**2. `BeamGrouper` helper — pure, fully unit-testable (default beaming logic)**
+
+- New `HeadMusic::Notation::MusicXML::BeamGrouper`, same shape as `Divisions`/`DurationWriter`/`ClefSelector`. Consumes an ordered list of per-notehead events for one measure plus the group-unit span; returns per-event `<beam>` annotations. No XML strings — return plain structs (mirror `DurationWriter#components` :44-47) so grouping is testable in isolation.
+- Suggested shape:
+  - `Beam = Struct.new(:number, :type, keyword_init: true)`, `type ∈ "begin"|"continue"|"end"|"forward hook"|"backward hook"`.
+  - `Event = Struct.new(:levels, :onset, :beam_break_before, keyword_init: true)` — `levels` = beam count the notehead carries alone (eighth=1, 16th=2, 32nd=3 via a table keyed on `DurationWriter::TYPES_BY_UNIT_NAME` :11-24; `0` for a rest or quarter-or-longer); `onset` = integer offset from bar start **in divisions** (integer, not ticks — avoids Float; see risk note); `beam_break_before` meaningful only on a placement's first component.
+  - `BeamGrouper.for(events, group_unit_divisions) → Array<Array<Beam>>` parallel to `events`.
+- Algorithm — segment then emit:
+  1. Boundary before event `i` when any of: `events[i].levels.zero?` or `events[i-1].levels.zero?` (rests / quarter+ are hard breaks and are singletons); `beam_break_before == true` (force break); `beam_break_before == false` (force join, overrides the default boundary); `nil` → default boundary iff `onset % group_unit_divisions == 0`.
+  2. Per group: size 1 → `[]` (lone-note no-beam case). Else level 1 spans the group (begin/continue/end). For each level `k ≥ 2`: runs of consecutive members with `levels ≥ k` emit begin/continue/end; a level-`k` member isolated between lower-level neighbours is a **hook** — backward if its predecessor is lower (dotted-eighth + 16th), forward if its successor is.
+- Per-level nesting requires independent open/close tracking per level, not one group cursor.
+- Tests: `spec/head_music/notation/music_xml/beam_grouper_spec.rb` — two eighths → begin/end L1; four eighths across two beats (all-nil) → two pairs; eighth + two 16ths → L1 begin/continue/end + L2 begin/end; dotted-eighth + 16th → L2 backward hook; level-0 mid-run splits and gets `[]`; size-1 group → `[]`; `beam_break_before:false` overriding a boundary → single group; `beam_break_before:true` mid-beat → split.
+
+**3. Emit `<beam>` from the Writer, driven by `BeamGrouper` (completes Layer 1)**
+
+- Build a memoized `beam_annotations` hash keyed by `[placement, component_index] → Array<Beam>`. For each voice/bar, iterate `placements_by_bar` (:292-295) in position order and construct the ordered `Event` list:
+  - **Onset must derive from `placement.position` (count/tick), not from the Component** — the Component carries no position. This is what makes anacrusis/pickup bars land on the correct metric grid: a 6/8 pickup eighth on count 6 groups as the bar's last pulse, not as offset 0. Compute the placement's bar-start offset in **divisions** (mirror the exact-integer arithmetic of `whole_measure_duration` :308-310), then accumulate each subsequent tied-chain component's `component.duration` (already integer divisions) onto it.
+  - Walk `components_by_placement[placement]` (:117-121) parallel to the `tied_value` chain. Per component: `levels` from its own `type` (0 if `placement.rest?`); `beam_break_before` = `placement.beam_break_before` on `component_index == 0`, else nil. Internal tied-chain beams thus follow type rules; the flag only governs the boundary between placements.
+  - `group_unit_divisions` from `effective_meter(bar_number).beam_group_unit` (Step 1) converted to divisions.
+  - Call `BeamGrouper.for(...)`; store under `[placement, i]`.
+- `note_lines` (:313-321): change the outer `flat_map` to `each_with_index.flat_map` for `component_index`; look up the annotation; pass `beams:` into `note_element_lines` **only on the lead slot** — `beams: index.zero? ? beams : []` (MusicXML puts `<beam>` on the chord's primary note, never on `<chord/>` members).
+- `note_element_lines` (:341-353): add `beams: []` kwarg; insert `*beam_lines(beams)` **between** the dots line (:349) and `*notation_lines` (:350) — after `<dot>`, before `<notations>`, per the DTD. `beam_lines` maps each `Beam` to `<beam number="N">type</beam>`.
+- Tests: `spec/head_music/notation/music_xml/writer_spec.rb` — 4/4 eight eighths → four two-note groups (assert exact begin/end and that no beam crosses a beat); 6/8 six eighths → exactly two three-note groups (the OSMD-failure case, asserted directly); a quarter/rest between eighths breaks the group and emits no `<beam>`; a chord of eighths carries beams only on the non-`<chord/>` note; a lone eighth emits no `<beam>`; assert exact line placement relative to `<dot>`/`<notations>`.
+
+**4. Per-`Placement` `beam_break_before` flag + override wiring (starts Layer 2)**
+
+- Recommended name/semantics: **`beam_break_before`**, tri-state — `nil` = default/meter-derived (**nil ≠ false**), `true` = force a break here, `false` = force beamed-to-previous. Reserve all three states now: a nil/true-only boolean can add a break but can never join across a default boundary, which is exactly what fully-authoritative ABC needs.
+- Follow the `Bar` side-metadata precedent (`starts_repeat`, `plays_on_passes`, `bar.rb`): add a writable attribute (`attr_accessor :beam_break_before`, default nil) set on the placement **after** construction, rather than threading a new positional/keyword arg through `Voice#place` and `Placement.new`. Placement already mutates via `merge` (:61-69) and `Voice#place` returns the instance, so the parser can set the flag on the returned object — this leaves the `place`/constructor/`merge` contract untouched.
+- In `merge`, the receiver's flag wins (chord members at one position share one beam edge) — pin with a spec.
+- The writer already reads `placement.beam_break_before` in Step 3's event construction; with the attribute defaulting to nil, Steps 1-3 render unchanged until the parser populates it.
+- Files: `lib/head_music/content/placement.rb` (:5-15 attr, `merge` :61-69). Tests: `spec/head_music/content/placement_spec.rb` — default nil; `merge` keeps the first flag; a non-nil flag flows into the Step-3 event and changes the emitted grouping.
+
+**5. ABC lexer — capture inter-note spacing as a `:beam_break` token**
+
+- Emit a standalone `:beam_break` token (mirroring the separate `:tie` token, `scan_tie` :285-290) rather than adding a field to every note/chord/rest `Token` — keeps the `Token` struct (:12-25) and localizes the change. At :114, replace the silent `scanner.skip(/[ \t]+/)` discard with: skip the whitespace, and if it separated two music tokens (`tokens.last` is a note/chord/rest) push `Token.new(type: :beam_break, ...)`. Emitting on any skipped run is harmless; the parser consults it only when a note follows.
+- Files: `lib/head_music/notation/abc/body_lexer.rb:114`. Tests: `spec/head_music/notation/abc/body_lexer_spec.rb` — `"CC"` → two `:note`, no `:beam_break`; `"C C"` → `:note`, `:beam_break`, `:note`; comment/continuation handling (:115-116) unaffected.
+
+**6. ABC parser — thread the signal onto placements (mirror the tie state machine)**
+
+- Extend `VoiceState` (:50-58) with `beam_break_pending` and `beam_last_was_note` accessors (parallels `tie_open`/`tie_line` :52-53). Add `when :beam_break then handle_beam_break(token)` to the dispatch (:152-163); `handle_beam_break` sets `beam_break_pending = true`.
+- In `defer_placement` (:214-221), compute the flag as the note is deferred: `state.beam_break_pending ? true : (state.beam_last_was_note ? false : nil)`; carry it to `flush_pending_note` (:343-349) and set it on the placement returned by `state.voice.place(...)` (the Step-4 setter). Then reset `beam_break_pending = false; beam_last_was_note = true`. For a tie continuation (`tie_onto_pending` :240-249) keep the flag on the head of the fused chain only.
+- Reset adjacency at hard boundaries so a following note is not marked "beamed to previous": `handle_rest` (:260-266), `handle_bar_line` (:292-301), `handle_voice_change` (:315-323) set both `beam_last_was_note = false` and `beam_break_pending = false`. First-of-bar/post-rest notes thus stay nil → meter default.
+- Net: no-space adjacency → `false` (join), space-separated → `true` (break), first-of-run → `nil` (default). This makes ABC input fully authoritative (matching the OSMD-autoBeam-OFF contract), which is the recommended direction for the beat-crossing question below.
+- Files: `lib/head_music/notation/abc/parser.rb`. Tests: `spec/head_music/notation/abc/parser_spec.rb` — `"CCCC"` → flags `[nil,false,false,false]` → one four-note group; `"CC CC"` → `[nil,false,true,false]` → two groups; a rest resets (`"CC z CC"`); tie interaction (`"C-C DD"`).
+
+**7. ABC export — space-suppression for round-trip**
+
+- In `build_bar_strings` (:112-120), replace the literal `" "` join (:118) with a per-adjacency separator: emit `""` before a placement whose `beam_break_before == false` (join), otherwise `" "` (covers `true` and `nil`, preserving today's behavior for unflagged programmatic compositions). Only valid between self-delimiting tokens (notes/chords/rests all re-lex unambiguously).
+- Also add the non-nil flag to `Placement#to_h` (sparsely, mirroring how `Bar` serializes only non-default state) so an ABC → Composition → serialize cycle doesn't silently drop authored beaming.
+- Files: `lib/head_music/notation/abc/writer.rb:118`, `lib/head_music/content/placement.rb` (`to_h`). Tests: `spec/head_music/notation/abc/writer_spec.rb` — `"CCCC"` re-emits without internal spaces; `"CC CC"` re-emits with the group-boundary space; unflagged programmatic composition still emits spaces (no regression); `ABC.parse(writer.to_s)` reproduces the flags (full round-trip).
+
+**8. Edge-case coverage (cross-cutting)**
+
+- Add to `beam_grouper_spec.rb` (pure) and `writer_spec.rb` / ABC `parser_spec.rb` (end-to-end):
+  - **Simple vs compound:** 6/8 → 2 groups of 3; 3/4 → 3 groups of 2; **3/8 → one group of 3** (do not special-case; Step 1 handles it).
+  - **Level 2:** eighth + two 16ths → L2 begin/end; **dotted-eighth + 16th → L2 backward hook**; a lone 16th → no beam; a pair of 16ths → both L1 and L2 begin/end.
+  - **Quarter/rest breaks:** `"CC A2 CC"` and `"CC z CC"` → separate groups; the quarter/rest emit no `<beam>`.
+  - **Tied note beaming across its own components:** a placement whose `tied_value` chain expands to multiple sub-quarter components beams internally by type; the `beam_break_before` flag applies only to `component_index 0`.
+  - **Pickup/incomplete bar:** onset from `position` → a partial bar's notes land on correct pulse boundaries; no beam crosses into the next bar.
+  - **Back-to-back groups:** `"CCCC CCCC"` → adjacent self-contained groups, no `continue` spanning the boundary.
+  - **Authored split below the pulse:** 6/8 `"ab c def"` → `ab` beams, lone `c` no beam, `def` beams — an authored split subdivides inside one dotted-quarter pulse.
+
+### Testing Strategy
+
+Unit-test `BeamGrouper` exhaustively in isolation (data in / data out — the bulk of the correctness lives here, and it mirrors `DurationWriter`'s testable-struct seam). Table-test `Meter#beam_group_unit` separately. Integration-test the `Writer` for exact `<beam>` element placement and levels, and the ABC parse→export round-trip for flag capture and space suppression. Extend existing specs where they exist (`writer_spec.rb`, `body_lexer_spec.rb`, `parser_spec.rb`, ABC `writer_spec.rb`, `placement_spec.rb`, `meter_spec.rb`); add one new `beam_grouper_spec.rb`. Highest-value cases to pin: the 3/8-simple group, level-2 hooks, the rest/quarter break, and the `false`-flag join overriding a default boundary. Prefer building fixtures via `HeadMusic::Notation::ABC.parse` (per project memory). Maintain 90% coverage; run `bundle exec rspec` and `bundle exec rubocop -a` green before finishing.
+
+### Risks & Open Questions
+
+**Ordering / technical risks**
+
+- **Component-vs-Placement granularity (the crux):** the grouper consumes the flattened Component stream, but onsets come from `Placement.position` and only the first component of a placement carries the flag. Reading position off a Component, or letting the `components_by_placement` walk and the `tied_value` chain fall out of sync, misplaces beams — pin with a tied-chain spec.
+- **Integer arithmetic:** do onset/boundary math in **divisions** (integer, via `component.duration` and the divisions form of `beam_group_unit`), not ticks. `RhythmicValue#ticks` returns Floats; staying in divisions avoids `.round` drift and matches `whole_measure_duration` (:308-310). If tuplets are ever supported at the ABC boundary, revisit for Rational arithmetic.
+- **`<beam>` element order** must be after `<dot>` and before `<notations>` (:349-350); misordering yields invalid MusicXML that some readers silently tolerate — assert exact line order.
+- **Chord double-emit:** the `index.zero?` lead-slot guard is essential; a `<beam>` on a `<chord/>` member is malformed.
+- **ABC re-lex ambiguity:** space suppression is safe only between self-delimiting tokens (notes/chords/rests); any future token type inside a beam group needs re-checking.
+
+**Resolved decisions** (confirmed by the human, 2026-07-19)
+
+1. **Authored beam crossing a beat/pulse boundary** — **RESOLVED: honor verbatim.** A no-space ABC run beams as one group even across beats (e.g. `cdef` in 4/4 → a single group spanning beats 1-2). ABC spacing is authoritative, matching the "explicit beams win / OSMD autoBeam OFF" purpose. The Step 6 fully-authoritative parser produces exactly this; the grouper honors `beam_break_before == false` as a join across the default boundary.
+2. **Partial-beam hooks in v1** — **RESOLVED: yes, include hooks.** Dotted-eighth + sixteenth emits an L2 backward hook. The grouper's `type` vocabulary includes `forward hook`/`backward hook` from the start.
+3. **Flag name/polarity** — **RESOLVED: `beam_break_before`**, tri-state (`nil` = meter default, `true` = force break, `false` = force join), a `Bar`-style writable `attr_accessor` on `Placement`.
+4. **Export symmetry** — **RESOLVED: asymmetric, like ties.** ABC export only suppresses/emits spaces where an authored flag is present; nil-flag (programmatic) compositions keep today's every-placement spacing. Pin with a round-trip spec.
+5. **Authored beam across a barline** — **RESOLVED: silent break at the barline.** The barline terminates any beam (MusicXML forbids cross-barline beams; `ensure_notes_within_barlines` enforces it). This intentionally differs from the tie feature's explicit `ParseError` across a barline.
+
+## Learnings
+
+### What went well
+
+- The core design from planning — **default beaming = no model state (computed at render), authored override = one tri-state `Placement` flag** — held through implementation without rework. Deliberately **not** modeling beaming inside `RhythmicValue` (unlike ties) was correct, since beaming spans notes rather than living within one.
+- Making `BeamGrouper` a **pure data-in/data-out helper** put the hardest logic (segmentation, multi-level beams, forward/backward hooks) behind an exhaustive unit spec, isolated from the writer. Most correctness lived there, and testing it in isolation paid off.
+- Implementing one step at a time with a review + spec run between each caught the major design tension the moment it appeared, not at the end.
+
+### What was surprising
+
+- The **"honor verbatim" decision has a non-obvious consequence**: ABC adjacency is always authoritative (implies a join), so pure meter-**default** beaming is only observable on programmatically-built compositions. This surfaced mid-implementation as 5 failing writer tests and forced splitting the tests into a default (programmatic) bucket and an authored (ABC-spacing) bucket. Lesson: when an input format is fully authoritative, you cannot exercise the *default* path through that format.
+- A **"confirmed" assumption was wrong at an edge**: "simple → group by beat" would make 3/8 emit no beams at all. Planning caught it and introduced `Meter#beam_group_unit` distinct from `beat_value`. Validate confirmed rules against odd cases (3/8) during planning, not after.
+- **Lexer/parser signals compose**: a rest is a "beamable predecessor," so `z CC` emits a beam-break and the post-rest note gets `true` rather than `nil`. Harmless (a rest forces a break anyway), but a reminder these signals interact.
+
+### What to do differently
+
+- **Front-load "how is this represented in the model?"** — that question (asked explicitly during the story) is the crux, and answering it early shaped the whole plan. Make it step one.
+- The **asymmetric-meter crash (5/16)** slipped past because "don't crash out of scope" was an instruction with no test; code review caught it. When a method becomes public, add a defensive test for out-of-scope inputs.
+- **Visual verification in a real notation reader (MuseScore/Finale) is still outstanding** — the suite asserts XML structure, not rendered appearance. Worth a one-time eyeball of the 6/8 case and hook direction.

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/index.html

@@ -277,6 +277,14 @@
   ],
   "active": [],
   "done": [
+    {
+      "title": "ABC Notation Beaming",
+      "path": "done/abc-notation-beaming.md"
+    },
+    {
+      "title": "ABC Tie Input",
+      "path": "done/abc-tie-input.md"
+    },
     {
       "title": "MusicXML Chord Rendering",
       "path": "done/musicxml-chord-rendering.md"
@@ -391,15 +399,15 @@
     },
     {
       "title": "Untitled",
-      "path": "done/superclass-for-note.md"
+      "path": "done/expand-playing-techniques.md"
     },
     {
       "title": "Untitled",
-      "path": "done/expand-playing-techniques.md"
+      "path": "done/instrument-variant.md"
     },
     {
       "title": "Untitled",
-      "path": "done/instrument-variant.md"
+      "path": "done/superclass-for-note.md"
     }
   ]
 };

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: head_music
 version: !ruby/object:Gem::Version
-  version: 17.1.0
+  version: 17.3.0
 platform: ruby
 authors:
 - Rob Head
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-19 00:00:00.000000000 Z
+date: 2026-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -247,6 +247,7 @@ files:
 - lib/head_music/notation/abc/writer.rb
 - lib/head_music/notation/instrument_notation.rb
 - lib/head_music/notation/music_xml.rb
+- lib/head_music/notation/music_xml/beam_grouper.rb
 - lib/head_music/notation/music_xml/clef_selector.rb
 - lib/head_music/notation/music_xml/divisions.rb
 - lib/head_music/notation/music_xml/duration_writer.rb
@@ -421,8 +422,10 @@ files:
 - 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-beaming.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