Merge master into meter-speed-2026, trim docs, fix slow paths

.agents/memory/MEMORY.md

@@ -6,3 +6,9 @@ Project-shared agent memory for music21. One file per fact; see frontmatter for
 - [sortedcontainers for streams](sortedcontainers-for-streams.md) — tried twice to make streams always-sorted via SortedList; abandoned, too slow for tiny streams
 - [Stream subclass generic defaults](stream-subclass-generic-defaults.md) — how `inherit-generics` should work once PEP 696 default type params land; maybe add typing_extensions
 - [BFS-flatten-iterator](bfs-flatten-iterator.md) — lazy breadth-first flatten is writable (maybe for tree first), but must not reuse the flat/flatten name tied to offsetInHierarchy
+- [Docs: audience separation](docs-audience-separation.md) — maintenance notes and private-method references go in code comments, never public docstrings
+- [Docs: no untaken paths](docs-no-untaken-paths.md) — docstrings state what the code does, never contrast with rejected designs
+- [Issue #1349 romanNumeral direction](issue-1349-romanNumeral-direction.md) — raised-^6/^7 fix landed; CAUTIONARY default kept; items 2+4 open with pablopupo/Malcolm
+- [Meter immutability re-apply](meter-immutability-reapply.md) — meter-speed is too stale to merge; re-apply FrozenDuration + immutable MeterTerminal + tuple NumDenom fresh on master
+- [Helpers public by default](helpers-public-by-default.md) — reusable theory helpers go public + documented (search first); inline one-caller helpers that would cost runtime
+- [MuseScore PNG path](musescore-png-path.md) — MuseScore renders notebook/.png/.pdf notation for everyone; users pick their own app for show(); music21 finds MuseScore itself

.agents/memory/docs-audience-separation.md

@@ -0,0 +1,20 @@
+---
+name: docs-audience-separation
+description: Public docstrings are for library users; maintenance notes and private-symbol references go in code comments
+metadata:
+  type: feedback
+---
+
+Never put maintenance notes ("change one and check the others", refactoring
+caveats, cross-references between internal implementations) in music21 public
+docstrings, and never reference private (underscore) methods from public
+docstrings. Put that material in `#` code comments instead.
+
+**Why:** docstrings render into the published docs and serve library *users*;
+comments serve *maintainers*. Myke: "there are different users with different
+roles." A user reading the API docs should never see internal plumbing they
+cannot call.
+
+**How to apply:** before finishing a doc pass, scan new docstring text for
+underscore-prefixed names and maintainer-facing advice; relocate to a comment
+just below the docstring. Related style rule: [[docs-no-untaken-paths]].

.agents/memory/docs-no-untaken-paths.md

@@ -0,0 +1,21 @@
+---
+name: docs-no-untaken-paths
+description: Docstrings and doctests describe what the code does, never the designs it avoided
+metadata:
+  type: feedback
+---
+
+When writing docstrings and doctests for music21, do not spend words (or
+doctest lines) explaining what the code *doesn't* do or contrasting with
+rejected alternatives — e.g. cut "not literally 'mod 7', which would make it
+0" from a description that already states the value is always 1-7. Myke: "we
+don't spend doctest time reinforcing paths we didn't take."
+
+**Why:** every sentence in a docstring is maintained forever and read by users
+who never saw the alternative; contrast-with-the-wrong-design is
+reviewer-facing noise, like comments justifying a change.
+
+**How to apply:** state the positive contract with examples of real values. If
+a name is misleading (like `GenericInterval.mod7`, which actually returns
+simple-interval values 1-7), document the actual behavior — don't argue with
+the name in prose. Related style rule: [[docs-audience-separation]].

.agents/memory/helpers-public-by-default.md

@@ -0,0 +1,25 @@
+---
+name: helpers-public-by-default
+description: Reusable music-theory helpers go public with docs and examples; but a one-caller helper that would cost runtime gets inlined
+metadata:
+  type: feedback
+---
+
+When a new helper computes something a user could reuse, make it a public, documented
+function with doctest examples, not `_private`. Before writing it, search the codebase
+(scale, key, chord, interval, pitch, roman) for something that already does it or
+nearly does, and build on that.
+
+But be smart about runtime: never rebuild an expensive object per item. A
+`scale.MajorScale` costs ~80 us to build and ~110 us per degree lookup. If a helper has
+one caller and standing alone would force per-call setup or awkward context parameters,
+inline it and hoist the setup out of the loop.
+
+**Why:** the point of music21 is giving people helpful tools for music theory, but a
+slow public helper in a hot path is worse than none. (Myke, 2026-09-29: a public
+`chordDegreeFromPitch` that built a MajorScale per pitch and took a `chordDegrees`
+collection was inlined into `chordSymbolFigureFromChord` with the scale built once.)
+
+**How to apply:** default to public for genuinely reusable theory tools; inline when
+there is one caller and the standalone signature would be slow or contrived.
+Related: [[docs-audience-separation]].

.agents/memory/issue-1349-romanNumeral-direction.md

@@ -0,0 +1,40 @@
+---
+name: issue-1349-romanNumeral-direction
+description: Status and direction for RomanNumeral.romanNumeral vs romanNumeralFromChord (GitHub issues #1349 and #1249)
+metadata:
+  type: project
+---
+
+As of 2026-07-06 (branch `fix-1349-raised-67`): the core raised-^6/^7 bug in
+GitHub issue #1349 is FIXED — `correctRNAlterationForMinor` gained a
+keyword-only `chordHasMajorThird` argument so major-quality chords on raised
+^6/^7 in minor keep their sharp (figure `#VI`, `.romanNumeral` `'#VI'`), and
+the tsvConverter `localKeyAsRn` workaround was removed. (Naming settled after
+two rounds: name the parameter for the chord-level fact it carries, not for
+its consequence like "uppercaseNumeral" — the numeral doesn't exist yet when
+the function runs.) Myke decided NOT to
+flip the `romanNumeralFromChord` default from CAUTIONARY to QUALITY (the 2022
+idea in the issue) for now. Still open, to discuss with contributor pablopupo
+and Malcolm Sailor on the issue: (2) adding `sixthMinor`/`seventhMinor`
+parameters to `romanNumeralFromChord` and possibly flipping its default, and
+(4) issue #1249 (secondary-numeral `#vii` prefixing).
+
+**Why:** `.romanNumeral` is the *semantic* root-degree token (alteration
+relative to the key's natural scale, read from `frontAlterationAccidental`),
+while `.figure` is notational. `harmonicFunction.romanToFunction` and the
+tsvConverter DCML export depend on the semantic reading, so the property
+should never be deprecated. Known remaining wart: seventh chords on raised
+^6/^7 in minor still don't round-trip their figures (e.g. `#VIb753` reparses
+with G-flat) — the CAUTIONARY generation convention computes inversion figures
+against an "altered key" while parsing measures against the original scale,
+and the mismatch differs per degree.
+
+**How to apply:** when returning to items 2+4, the minor-^6/^7 accidental
+convention lives in three places that must stay in sync (see the maintenance
+comment in `correctRNAlterationForMinor`). The same session renamed
+`FigureTuple.aboveBass` to `degFromRefPitch` and `ChordFigureTuple` to
+`PitchFigureTuple`, and replaced `figureTupleSolo` with the classmethod
+constructor `FigureTuple.fromPitchAndReference(pitchObj, keyObj, refPitch)`
+(old name kept as a deprecated v11→v12 alias). Myke is not all-in on
+classmethod constructors in general, but preferred one here over a
+module-level function whose name read as the verb "figure".

.agents/memory/meter-immutability-reapply.md

@@ -0,0 +1,34 @@
+---
+name: meter-immutability-reapply
+description: Plan to re-apply the meter-speed immutability rewrite fresh on master instead of merging the stale branch
+metadata:
+  type: project
+---
+
+The `origin/meter-speed` branch (16 commits, Oct 2022) is a two-part meter rewrite:
+
+1. **Representation change** — meter's internal form goes from strings (`'1/4'`,
+   `f'1/{d}'`) to tuples: `NumDenom = tuple[int, int]` (i.e. `(1, 4)`), with
+   `NumDenomTuple` / `MeterOptions` aliases in `meter/tools.py`.
+2. **Immutability** — `MeterTerminal` / `MeterSequence` become slotted and
+   immutable (`SlottedObjectMixin` / `common.FrozenObject`, `FrozenDuration`,
+   `_durationFromNumeratorDenominator` cached with `lru_cache`). Immutable meter
+   terminals can be shared/cached with no defensive copies.
+
+**Why not just merge master in (decided 2026-06-30):** the branch is 879 commits
+behind. Merging `master` produced deep *semantic* conflicts — 31 hunks in
+`meter/core.py`, 8 in `meter/tools.py` — because master independently evolved the
+*string-based, mutable* code for a year+ (added typing like `-> None`, a `weight`
+property, parse fast-paths, and a public→private rename `addTerminal` →
+`_addTerminal`). Almost every hunk is two different implementations of the same
+method, and the str→tuple change ripples into callers. Resolving that merge would
+mean finishing+rebasing the rewrite through hundreds of collisions — not worth it.
+
+**How to apply:** treat `origin/meter-speed` as a *reference*, not a mergeable
+branch. Start a clean branch off current `master` and re-apply only the wanted
+pieces as a fresh, reviewable change: `FrozenDuration`, slotted/immutable
+`MeterTerminal` & `MeterSequence`, and the tuple `NumDenom` internal
+representation. Note `common.FrozenObject` is **already in master** (typed for
+3.12+), so only the meter-specific immutability needs porting. Validate against the
+full `music21/meter` test suite and fix downstream callers. Keep `origin/meter-speed`
+until the re-apply lands; delete it afterward.

.agents/memory/musescore-png-path.md

@@ -0,0 +1,38 @@
+---
+name: musescore-png-path
+description: MuseScore is needed even by Dorico/Sibelius users -- musescoreDirectPNGPath renders notation in notebooks and .png/.pdf; musicxmlPath stays the user's own app
+metadata:
+  type: project
+---
+
+Two separate settings:
+
+- `musicxmlPath`: the app `.show()` opens outside a notebook. Docs encourage users to
+  pick their regular notation program (Dorico, Sibelius, MuseScore, Finale).
+- `musescoreDirectPNGPath`: the MuseScore program music21 runs in the background
+  (`converter/museScore.py: runThroughMuseScore`) to turn MusicXML into images. Used by
+  `.show()` in Jupyter (default format `ipython.musicxml.png`) and by
+  `write('musicxml.png')` / `write('musicxml.pdf')`. A value starting with `/skip` turns
+  rendering off (documentation tests show a 1-pixel image instead).
+
+**Why MuseScore is special:** it is the only notation program music21 can run from the
+command line to render images, so anyone who wants notation in a notebook needs it
+installed, even if they never open it.
+
+**How the path gets set (v11, #1980 and #2099; none of this is in 10.x):**
+
+- `converter.museScore.findMuseScore()` finds MuseScore 3 or newer in the usual places:
+  Applications on Mac, Program Files on Windows, the PATH on Linux.
+- The Configuration Assistant sets `musescoreDirectPNGPath` to the chosen reader if it is
+  MuseScore (the program inside a Mac `.app`), otherwise to any MuseScore it finds,
+  unless the current setting already exists.
+- When rendering, `getOrFindMuseScoreDirectPNGPath()` looks for MuseScore if the setting
+  is missing or points nowhere, saves what it finds, or raises with the musescore.org link.
+- Defaults in `environment.py`: MuseScore 4's install location on Mac and Windows;
+  `/usr/bin/mscore3` on Linux, where MuseScore 4 has no standard location.
+
+Myke renders with MuseScore 3 because it is much faster than 4 -- an advanced tip not
+yet in the docs.
+
+**How to apply:** install docs tell users to install MuseScore for notation in the
+browser, then choose their favorite program in the assistant.

.agents/skills/bump-version/SKILL.md

@@ -35,36 +35,47 @@ uv run pytest --doctest-modules music21/base.py music21/_version.py
 
 ## When to bump
 
-- **Parsing-format / parser changes (most common reason).** Any change to how a
-  format is read or written — musicxml, abc, MIDI, noteworthy/NWC, humdrum,
-  etc. — should bump the version, even a refactor, because the version is baked
-  into the **pickled-stream cache** (cached parsed files). Bumping invalidates
-  stale pickles so users don't get results from the old parser. This is the rule
-  in AGENTS.md ("Changes to parsing formats … need to update the patch version").
-- **New feature** → bump (see digit rules below); mark it in docstrings with
-  `* New in vX: …`.
-- **Bug fix** → bump the patch; if it changes public behavior, mark
-  `* Changed in vX: …`.
-- **Pure internal refactor with no behavioral/pickle impact** → usually no bump.
+One thing depends on the number changing: the **pickled-stream cache**. The
+version is part of the cache key, so a bump invalidates stale pickles
+everywhere. If nobody is holding a wrong cached parse, don't bump — the commit
+is the record.
+
+- **Parser or parsing-format change → always bump**, even a pure refactor:
+  someone is holding a pickle parsed by the old code. musicxml, abc, MIDI,
+  noteworthy/NWC, humdrum, and the rest.
+- **Anything else → no bump**: a new feature, a fix that makes code do what it
+  already claimed, an internal refactor, a test-only or docs-only change.
+
+"It's a bug fix" is not by itself a reason. A musicxml importer that now reads a
+tag it used to drop bumps, because cached parses are wrong. A scale analysis
+method that changed its return format does not.
+
+A `New in` / `Changed in` marker is **not** a reason to bump. Those markers name
+a major version, at most a minor one — never a patch, never a `bN` beta — and
+moving those digits is a release decision only a human makes. Write the marker
+for the version the change will land in and leave `_version.py` alone.
 
 ## Which part to change
 
 music21 follows semver-ish rules (see the `_version.py` docstring for the full
 rationale):
 
-- **MAJOR (X)** — breaks old features. Rare.
+- **MAJOR (X)** — breaks old features. Rare. A human decides this.
 - **MINOR (Y)** — new features. **Even Y = alpha/beta, odd Y = release.**
   `X.0` (e.g. `11.0`) are development releases that can still change until `X.1`.
-- **PATCH (Z)** — bug fixes and parsing/pickle-invalidating changes.
+  A human decides this too; an agent changes only the patch or the beta suffix.
+- **PATCH (Z)** — parsing/pickle-invalidating changes and other fixes that
+  meet the bar above.
 - **beta suffix (`bN`)** — successive pre-release builds of the same
   `MAJOR.MINOR.PATCH`. To cut another beta without otherwise changing the
   number, increment it: `11.0.0b1` → `11.0.0b2`. (This is what a
   parser change during a `…b1` cycle does.)
 
 ## `Changed in` / `New in` docstring markers
 
-When a bump accompanies a public-interface change, annotate the affected
-method/class docstring:
+Annotate a changed public interface in the affected method/class docstring.
+This is independent of bumping — a marker is documentation, not a version
+change:
 - `* Changed in vX: one-line explanation.`
 - `* New in vX: one-line explanation.`