@@ -15,6 +15,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `pyproject.toml`; a source checkout that is not installed reports
   `0.0.0+unknown` rather than lying.
 
+- **`modscan detect` says when the ranking is a tie.** The detector breaks equal
+  scores on module name, so a band of equally-scored candidates is ordered
+  alphabetically — and a reader taking the top ten off a band of eighteen was
+  reading the alphabet without being told. `detect` now prints how many
+  candidates share the score at the cutoff and how many of them are shown, and
+  `--json` carries `tied_with` per point for consumers that cannot read the
+  prose. Nothing about the ranking changed; it just stopped presenting a tie as
+  an ordering. The same disclosure was added to the benchmark's own numbers.
+
 ### Fixed
 
 - **`@overload` stubs no longer report a symbol several times.** `typing.overload`
 
@@ -179,6 +179,20 @@ Point it at an installed package to see it work immediately:
 modscan detect "$(python -c 'import os,click;print(os.path.dirname(click.__file__))')" --limit 5
 ```
 
+**Read the tie note before you read the ranking.** Equal scores are broken by
+module name, so when many candidates share a score the order among them is
+alphabetical rather than evidence-based. `detect` says so when the list you asked
+for cuts through such a band:
+
+> **18 candidates score exactly 1.00, and this list shows 12 of them.** The 6
+> left out are not ranked lower — ties are broken by module name, so the cut
+> through this band is alphabetical, not evidence-based.
+
+`--json` carries the same fact as `tied_with` on each point. This is a real
+property of the ranking, not a disclaimer: see
+[`benchmarks/README.md`](benchmarks/README.md) for how much of the benchmark's
+own headline the alphabet turned out to own.
+
 ### Security lens (`modscan-audit`)
 
 The same seams a plugin system exposes are also where untrusted code can enter. A
 
@@ -88,6 +88,10 @@ Honest reading, not cherry-picked:
 - The **Plugin registration points** section shows how markdown discovers plugins
   (`entry_points`, plus `import_module`/`find_spec` loader sites), reported apart
   from the implement-this ranking rather than flooding it.
+- The note under the header is the honest part: **eighteen candidates tie at
+  1.00 and the run shows twelve**, so the six left out were cut by module name,
+  not by evidence. Without that line the twelve rows read as a ranking. They are
+  a band with an alphabetical cut through it.
 
 Reproduce it (free):
 
 
@@ -2,20 +2,22 @@
 
 12 candidate(s), ranked by moddability. No LLM was used — this is the static ranking only.
 
+**18 candidates score exactly 1.00, and this list shows 12 of them.** The 6 left out are not ranked lower — ties are broken by module name, so the cut through this band is alphabetical, not evidence-based. Widen `--limit` to see the whole band.
+
 | # | Extension point | Category | Score | Why |
 |---|---|---|---|---|
-| 1 | `markdown.extensions.abbr:AbbrExtension` | subclass | 1.00 | public class; name ends in 'Extension' — role type; subclasses a 'Extension' role type |
-| 2 | `markdown.extensions.admonition:AdmonitionExtension` | subclass | 1.00 | public class; name ends in 'Extension' — role type; subclasses a 'Extension' role type |
-| 3 | `markdown.extensions.attr_list:AttrListExtension` | subclass | 1.00 | public class; name ends in 'Extension' — role type; subclasses a 'Extension' role type |
-| 4 | `markdown.extensions.codehilite:CodeHiliteExtension` | subclass | 1.00 | public class; name ends in 'Extension' — role type; subclasses a 'Extension' role type |
-| 5 | `markdown.extensions.def_list:DefListExtension` | subclass | 1.00 | public class; name ends in 'Extension' — role type; subclasses a 'Extension' role type |
-| 6 | `markdown.extensions.extra:ExtraExtension` | subclass | 1.00 | public class; name ends in 'Extension' — role type; subclasses a 'Extension' role type |
-| 7 | `markdown.extensions.fenced_code:FencedCodeExtension` | subclass | 1.00 | public class; name ends in 'Extension' — role type; subclasses a 'Extension' role type |
-| 8 | `markdown.extensions.footnotes:FootnoteExtension` | subclass | 1.00 | public class; name ends in 'Extension' — role type; subclasses a 'Extension' role type |
-| 9 | `markdown.extensions.legacy_attrs:LegacyAttrExtension` | subclass | 1.00 | public class; name ends in 'Extension' — role type; subclasses a 'Extension' role type |
-| 10 | `markdown.extensions.legacy_em:LegacyEmExtension` | subclass | 1.00 | public class; name ends in 'Extension' — role type; subclasses a 'Extension' role type |
-| 11 | `markdown.extensions.md_in_html:MarkdownInHtmlExtension` | subclass | 1.00 | public class; name ends in 'Extension' — role type; subclasses a 'Extension' role type |
-| 12 | `markdown.extensions.meta:MetaExtension` | subclass | 1.00 | public class; name ends in 'Extension' — role type; subclasses a 'Extension' role type |
+| 1 | `markdown.extensions.abbr:AbbrExtension` | subclass | 1.00 | [MS-MOD-PUBLIC] public class; [MS-MOD-CLASSROLE] name ends in 'Extension' — role type; [MS-MOD-BASEROLE] subclasses a 'Extension' role type |
+| 2 | `markdown.extensions.admonition:AdmonitionExtension` | subclass | 1.00 | [MS-MOD-PUBLIC] public class; [MS-MOD-CLASSROLE] name ends in 'Extension' — role type; [MS-MOD-BASEROLE] subclasses a 'Extension' role type |
+| 3 | `markdown.extensions.attr_list:AttrListExtension` | subclass | 1.00 | [MS-MOD-PUBLIC] public class; [MS-MOD-CLASSROLE] name ends in 'Extension' — role type; [MS-MOD-BASEROLE] subclasses a 'Extension' role type |
+| 4 | `markdown.extensions.codehilite:CodeHiliteExtension` | subclass | 1.00 | [MS-MOD-PUBLIC] public class; [MS-MOD-CLASSROLE] name ends in 'Extension' — role type; [MS-MOD-BASEROLE] subclasses a 'Extension' role type |
+| 5 | `markdown.extensions.def_list:DefListExtension` | subclass | 1.00 | [MS-MOD-PUBLIC] public class; [MS-MOD-CLASSROLE] name ends in 'Extension' — role type; [MS-MOD-BASEROLE] subclasses a 'Extension' role type |
+| 6 | `markdown.extensions.extra:ExtraExtension` | subclass | 1.00 | [MS-MOD-PUBLIC] public class; [MS-MOD-CLASSROLE] name ends in 'Extension' — role type; [MS-MOD-BASEROLE] subclasses a 'Extension' role type |
+| 7 | `markdown.extensions.fenced_code:FencedCodeExtension` | subclass | 1.00 | [MS-MOD-PUBLIC] public class; [MS-MOD-CLASSROLE] name ends in 'Extension' — role type; [MS-MOD-BASEROLE] subclasses a 'Extension' role type |
+| 8 | `markdown.extensions.footnotes:FootnoteExtension` | subclass | 1.00 | [MS-MOD-PUBLIC] public class; [MS-MOD-CLASSROLE] name ends in 'Extension' — role type; [MS-MOD-BASEROLE] subclasses a 'Extension' role type |
+| 9 | `markdown.extensions.legacy_attrs:LegacyAttrExtension` | subclass | 1.00 | [MS-MOD-PUBLIC] public class; [MS-MOD-CLASSROLE] name ends in 'Extension' — role type; [MS-MOD-BASEROLE] subclasses a 'Extension' role type |
+| 10 | `markdown.extensions.legacy_em:LegacyEmExtension` | subclass | 1.00 | [MS-MOD-PUBLIC] public class; [MS-MOD-CLASSROLE] name ends in 'Extension' — role type; [MS-MOD-BASEROLE] subclasses a 'Extension' role type |
+| 11 | `markdown.extensions.md_in_html:MarkdownInHtmlExtension` | subclass | 1.00 | [MS-MOD-PUBLIC] public class; [MS-MOD-CLASSROLE] name ends in 'Extension' — role type; [MS-MOD-BASEROLE] subclasses a 'Extension' role type |
+| 12 | `markdown.extensions.meta:MetaExtension` | subclass | 1.00 | [MS-MOD-PUBLIC] public class; [MS-MOD-CLASSROLE] name ends in 'Extension' — role type; [MS-MOD-BASEROLE] subclasses a 'Extension' role type |
 
 ## Plugin registration points
 
 
@@ -233,15 +233,74 @@ def _split_detect_points(points: list) -> tuple[list, list]:
     return implement, registration
 
 
+def _tied_counts(points: list) -> list[int]:
+    """How many *other* points share each point's score, positionally.
+
+    The detector breaks score ties on (module, lineno) — alphabetically. So a
+    point's printed position inside a tied band reflects its name, not the
+    evidence for it, and a reader taking "the top ten" off a band of eighteen is
+    reading the alphabet. Counting the band is what lets the output say so.
+    """
+    per_score: dict[float, int] = {}
+    for point in points:
+        per_score[point.score] = per_score.get(point.score, 0) + 1
+    return [per_score[p.score] - 1 for p in points]
+
+
+def _tie_note(points: list, shown: int) -> str | None:
+    """One line telling the reader which part of this ranking is the alphabet.
+
+    ``points`` is the full ranked list, ``shown`` how many of it are displayed —
+    the band has to be measured before ``--limit`` cuts it, or the note would
+    describe the truncated list rather than the ranking.
+    """
+    if not points or shown <= 0:
+        return None
+    cutoff = points[min(shown, len(points)) - 1].score
+    band = sum(1 for p in points if p.score == cutoff)
+    if band < 2:
+        return None
+    above = sum(1 for p in points if p.score > cutoff)
+    in_view = min(shown, len(points)) - above
+    if band > in_view:
+        return (
+            f"**{band} candidates score exactly {cutoff:.2f}, and this list shows "
+            f"{in_view} of them.** The {band - in_view} left out are not ranked lower — "
+            "ties are broken by module name, so the cut through this band is "
+            "alphabetical, not evidence-based. Widen `--limit` to see the whole band."
+        )
+    return (
+        f"**The last {band} entries score exactly {cutoff:.2f}.** Ties are broken by "
+        "module name, so their order among themselves is alphabetical, not "
+        "evidence-based."
+    )
+
+
 def _point_module(seam, root: str, label: str | None) -> str:
     """Module qualname for output, or a clean fallback for a root-package symbol
     (empty qualname): the label if set, else the scan root's basename — never the
     absolute path, which would leak a local or CI filesystem layout into ids."""
     return seam.module or label or os.path.basename(os.path.normpath(root))
 
 
+def _detect_json_entry(point, tied_with: int, root: str, label: str | None) -> dict:
+    return {
+        "id": f"{_point_module(point.seam, root, label)}:{point.seam.name}",
+        "module": point.seam.module or None,
+        "category": point.category,
+        "score": round(point.score, 4),
+        "tied_with": tied_with,
+        "kind": point.seam.kind,
+        "signals": list(point.signals),
+    }
+
+
 def _render_detect_markdown(
-    implement: list, registration: list, root: str, label: str | None = None
+    implement: list,
+    registration: list,
+    root: str,
+    label: str | None = None,
+    tie_note: str | None = None,
 ) -> str:
     # Root-package symbols have an empty qualname; _point_module keeps their ids
     # clean (label, else the root basename) instead of leaking the scan path.
@@ -252,6 +311,10 @@ def _render_detect_markdown(
         f"{len(implement)} candidate(s), ranked by moddability. No LLM was used — "
         "this is the static ranking only.",
         "",
+    ]
+    if tie_note:
+        lines += [tie_note, ""]
+    lines += [
         "| # | Extension point | Category | Score | Why |",
         "|---|---|---|---|---|",
     ]
@@ -321,31 +384,39 @@ def _main_detect(argv: list[str]) -> int:
     codebase = get_language_parser(args.language).parse_codebase(args.root)
     points = detect_extension_points(build_graph(codebase), min_score=args.min_score)
     implement, registration = _split_detect_points(points)
+    # Ties are measured on the FULL ranked list: --limit is exactly the cut that
+    # can fall inside a band, so a note computed after truncation would describe
+    # the wrong thing.
+    tied = _tied_counts(implement)
+    shown = len(implement) if args.limit is None else min(args.limit, len(implement))
+    tie_note = _tie_note(implement, shown)
     # --limit caps the ranked implement-this list; registration points are a
     # small deduplicated set, always shown in full.
     if args.limit is not None:
         implement = implement[: args.limit]
+        tied = tied[: args.limit]
 
     # Signal strings contain an em-dash; a Windows cp1252 console would raise
     # UnicodeEncodeError printing them. Emit UTF-8 regardless of console locale.
     if hasattr(sys.stdout, "reconfigure"):
         sys.stdout.reconfigure(encoding="utf-8")
 
     if args.json:
+        # tied_with is the prose note's machine-readable twin: a consumer that
+        # ranks or truncates this payload needs to know a score is shared, and
+        # cannot read the Markdown warning. Registration points are a
+        # deduplicated set rather than a ranking, so they carry 0.
         payload = [
-            {
-                "id": f"{_point_module(p.seam, args.root, args.label)}:{p.seam.name}",
-                "module": p.seam.module or None,
-                "category": p.category,
-                "score": round(p.score, 4),
-                "kind": p.seam.kind,
-                "signals": list(p.signals),
-            }
-            for p in implement + registration
+            _detect_json_entry(p, n, args.root, args.label)
+            for p, n in list(zip(implement, tied)) + [(r, 0) for r in registration]
         ]
         print(json.dumps(payload, indent=2))
     else:
-        print(_render_detect_markdown(implement, registration, args.root, args.label))
+        print(
+            _render_detect_markdown(
+                implement, registration, args.root, args.label, tie_note
+            )
+        )
     return 0
 
 
 
@@ -341,6 +341,85 @@ def test_detect_separates_and_dedups_registration_points() -> None:
             _cleanup(pkg)
 
 
+class _FakePoint:
+    """Only the attributes the tie helpers read."""
+
+    def __init__(self, score: float) -> None:
+        self.score = score
+
+
+def test_tied_counts_report_the_band_not_the_position() -> None:
+    from modscan.cli import _tied_counts
+
+    points = [_FakePoint(s) for s in (1.0, 1.0, 1.0, 0.8, 0.1)]
+    assert _tied_counts(points) == [2, 2, 2, 0, 0]
+
+
+def test_tie_note_warns_when_the_limit_cuts_through_a_band() -> None:
+    """JUnit's shape: 18 tied at 1.00, a reader takes the top 10 and sees 4 of 7."""
+    from modscan.cli import _tie_note
+
+    points = [_FakePoint(1.0) for _ in range(18)] + [_FakePoint(0.7) for _ in range(5)]
+    note = _tie_note(points, shown=10)
+    assert note is not None
+    assert "18 candidates score exactly 1.00" in note
+    assert "shows 10 of them" in note
+    assert "alphabetical" in note, "the reader must be told what decided the cut"
+
+
+def test_tie_note_reports_a_fully_shown_band_without_crying_truncation() -> None:
+    from modscan.cli import _tie_note
+
+    points = [_FakePoint(1.0) for _ in range(3)]
+    note = _tie_note(points, shown=3)
+    assert note is not None
+    assert "last 3 entries" in note
+    assert "left out" not in note, "nothing was cut — do not claim it was"
+
+
+def test_tie_note_is_silent_when_the_cutoff_is_unambiguous() -> None:
+    """No note is better than a note nobody needs — this one must not become noise."""
+    from modscan.cli import _tie_note
+
+    points = [_FakePoint(s) for s in (1.0, 0.9, 0.8)]
+    assert _tie_note(points, shown=2) is None
+    assert _tie_note([], shown=10) is None
+    assert _tie_note(points, shown=0) is None
+
+
+def test_detect_json_carries_tied_with() -> None:
+    """The prose note's machine-readable twin: a JSON consumer cannot read Markdown."""
+    import io
+    import json as _json
+    from contextlib import redirect_stdout
+
+    pkg = "clities"
+    with tempfile.TemporaryDirectory() as root:
+        d = os.path.join(root, pkg)
+        os.makedirs(d)
+        open(os.path.join(d, "__init__.py"), "w").close()
+        # two classes that score identically, and one that does not
+        with open(os.path.join(d, "api.py"), "w", encoding="utf-8") as fh:
+            fh.write(
+                "class AlphaHandler:\n    pass\n"
+                "class BetaHandler:\n    pass\n"
+                "class Plain:\n    pass\n"
+            )
+        try:
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                assert main(["detect", root, "--json"]) == 0
+            payload = _json.loads(buf.getvalue())
+            by_name = {e["id"].rsplit(":", 1)[-1]: e for e in payload}
+
+            assert by_name["AlphaHandler"]["score"] == by_name["BetaHandler"]["score"]
+            assert by_name["AlphaHandler"]["tied_with"] == 1
+            assert by_name["BetaHandler"]["tied_with"] == 1
+            assert by_name["Plain"]["tied_with"] == 0, "a unique score is tied with nothing"
+        finally:
+            _cleanup(pkg)
+
+
 def test_version_flag_prints_and_exits_zero() -> None:
     """`--version` reports the installed version and exits 0.
 
@@ -385,4 +464,9 @@ def test_version_flag_prints_and_exits_zero() -> None:
     test_consecutive_runs_are_independent()
     test_no_validate_examples_skips_preflight()
     test_version_flag_prints_and_exits_zero()
+    test_tied_counts_report_the_band_not_the_position()
+    test_tie_note_warns_when_the_limit_cuts_through_a_band()
+    test_tie_note_reports_a_fully_shown_band_without_crying_truncation()
+    test_tie_note_is_silent_when_the_cutoff_is_unambiguous()
+    test_detect_json_carries_tied_with()
     print("OK: cli self-check passed")