Sort differential rules most-specific-first, dropping the ordering rule

expected_changes.toml's rules were tried in file order, so a rule
narrowed by name_regex had to be written above every rule narrowed
only by fields -- an invariant the file could only defend in prose,
and one it had already lost once (the fix(#271) CJK rule was dead on
arrival at the end of the file, its diffs claimed and mislabelled by
fields-only fix(suffix-routing)).

compare.py now sorts the rules into two tiers before matching, stably,
so rules within a tier keep the order they were written in. That makes
the ordering rule structural, and the three places that documented it
by hand -- the toml header, the #271 rule's own "FIRST on purpose"
paragraph, and the README's ordering section -- collapse to one line
each.

No exit-code change: sorting cannot change WHICH rules match, only
which of several matching rules wins the label. The run is unchanged
against the current corpora (654 names, 18 intentional diffs, 0
unexplained, exit 0) -- with one fields-only rule in the file and the
one specific rule that competes with it already written above it, the
sort is a no-op today. Verified it is not a no-op in general: with the
#271 rule moved to the end of the file, '毛泽东' classifies as
suffix-routing unsorted and as fix(#271) sorted.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: derek73

tools/differential/README.md

@@ -116,14 +116,10 @@ matches only if the observed diff fields are a subset of this list).
 Keep both as tight as the actual diff allows -- a loose rule can mask
 a real regression.
 
-Rules are tried in file order and the first match wins, so a rule
-narrowed by `name_regex` has to sit **above** any rule narrowed only
-by `fields`. The `fields`-only rules are broad by construction: a
-`fields = ["first", "last", "suffix"]` rule claims every diff confined
-to those three columns, whatever the name looked like. Adding the
-`fix(#271)` CJK rule at the end of the file was enough to make it dead
-on arrival -- `fix(suffix-routing)` claimed all of its diffs first, and
-labelled them as something else.
+Rules are sorted most-specific-first before matching -- a `name_regex`
+rule outranks a `fields`-only one (which is broad by construction)
+wherever both match -- so file order does not decide which rule claims
+a diff.
 
 Some entries in the seed list are for behavior families that this
 particular corpus (pre-M12 v1 test strings) happens not to contain any

tools/differential/compare.py

@@ -62,6 +62,11 @@ def main() -> int:
     rules = tomllib.loads(
         (HERE / "expected_changes.toml").read_text()).get("change", [])
     validate_rules(rules)
+    # Most-specific-first: a name_regex rule outranks a fields-only rule
+    # wherever both match, so file order stops being load-bearing. The
+    # sort is stable, so rules within a tier keep the order they were
+    # written in.
+    rules.sort(key=lambda r: not isinstance(r.get("name_regex"), str))
     # A glob that matches nothing must not read as "everything passed".
     # Comparing zero names would print 0 unexplained and exit 0 -- the
     # harness's own stated nightmare (see validate_rules), and a

tools/differential/expected_changes.toml

@@ -3,10 +3,8 @@
 # S5). Rules are seeded from docs/superpowers/plans/notes-m12-diffs.md
 # and the `classification="fix(...)"` rows in tests/v2/cases.py; keep
 # each entry's `name_regex`/`fields` as tight as the diff allows.
-# ORDER MATTERS: classify() takes the FIRST matching rule, so a rule
-# narrowed by `name_regex` must sit ahead of any rule narrowed only by
-# `fields`, or the broad one silently claims its diffs under the wrong
-# label. See the #271 entry immediately below for a case that did.
+# File order is not load-bearing: compare.py sorts `name_regex` rules
+# ahead of `fields`-only ones before matching.
 
 [[change]]
 issue = "fix(#271) native-script CJK: family-first order + hangul segmentation"
@@ -23,14 +21,6 @@ issue = "fix(#271) native-script CJK: family-first order + hangul segmentation"
 # tests/v2/test_regex_sync.py, which fails if the two disagree -- if
 # one ever does.
 #
-# FIRST on purpose, and this position is load-bearing. classify()
-# returns the first matching rule, and 'fix(suffix-routing)' below
-# declares no name_regex at all -- so with this rule anywhere after it,
-# every CJK diff was classified as a suffix-routing change instead
-# (verified: all four names of a synthetic CJK corpus landed there).
-# The label would have been wrong and this rule dead. A rule narrowed
-# by name_regex belongs ahead of every rule narrowed only by `fields`.
-#
 # Expected to match nothing against the current corpora, which contain
 # no CJK at all: build_issues_corpus.py requires an internal space, and
 # unspaced names are the shape this classifies. Kept for the reason the