semver classifier flags breaking_changes on a reorder-only diff despite its own 'no semantic change' summary

Summary

While researching Build With Muse Episode 07 (Semantic Diff), found a real inconsistency in classify_delta() (muse/core/semver_classifier.py): a commit that purely reorders two top-level functions within a file — no symbol added, removed, or modified — gets classified with sem_ver_bump: "minor" and a non-empty breaking_changes list, despite the diff's own ops entry explicitly summarizing itself as no semantic change.

Reproduction

1. Commit a file with two functions, e.g.:

   def helper_a(x): return x
   def helper_b(x): return x * 2
   

2. Commit again with just the two functions' order swapped (no other edits).
3. muse diff HEAD~1 HEAD correctly reports zero symbol-level changes:

   M  extra.py
   
   1 modified file
   

4. But muse read-commit HEAD --json | jq '.structured_delta' shows:

   {
     "ops": [
       {
         "op": "replace",
         "address": "extra.py",
         "old_summary": "extra.py (before)",
         "new_summary": "extra.py (reformatted — no semantic change)"
       }
     ],
     "summary": "1 modified file",
     "sem_ver_bump": "minor",
     "breaking_changes": ["extra.py"]
   }
   

The op's own new_summary says "no semantic change" in plain English, yet the same delta is classified as a breaking, minor-version-bump change one field over.

Hypothesis (not confirmed)

diff()'s fallback path for a file where nothing at the symbol level changed (a pure reorder) apparently produces a top-level replace op keyed by the whole file address ("extra.py") rather than a patch op with an empty child_ops list. classify_delta()'s _classify_replace() branch then treats a file-level replace op the same way it would treat replacing an actual symbol — defaulting to breaking/minor — with no way to distinguish "the file's bytes changed but I found zero semantic content changes" from an actual content replacement it couldn't otherwise interpret.

Ask

1. Confirm whether this fallback path is intentional conservatism (file-level replace with no visibility into content = assume worst case) or a genuine gap.
2. If intentional: the new_summary text is misleading and should not claim "no semantic change" while the classification says otherwise — pick one honest story.
3. If a gap: either emit a patch op with empty child_ops (matching the pattern used elsewhere, e.g. real rename/move ops) instead of a file-level replace, or teach _classify_replace to recognize this specific no-op-content case and classify it as none.
4. Add a regression test: reorder-only diff must have sem_ver_bump == "none" and breaking_changes == [].

Priority

Not urgent — deliberately not chasing this down mid-recording. Circle back once the Build With Muse Season 1 season is wrapped; this doesn't block any episode script since Episode 07 already avoided making any semver claim about this specific case.

Related

• Episode 07 script (presentations/build-with-muse/episode-07/semantic-diff.md) — documents choosing not to use this detail on screen, and this ticket, in its own production notes.

Source

Found by Claude Sonnet 5 while researching Episode 07, 2026-09-12.