From 187e008e5c51e691c87ee43a1baad5844dd13f7a Mon Sep 17 00:00:00 2001
From: cdeust <cdeust@icloud.com>
Date: Thu, 30 Jul 2026 11:29:47 +0200
Subject: [PATCH 1/7] =?UTF-8?q?refactor:=20Extract=20Module=20doc=5Fclaim?=
 =?UTF-8?q?=5Fsources/doc=5Fclaim=5Fscan/doc=5Fclaim=5Fstructural=20from?=
 =?UTF-8?q?=20check=5Fdoc=5Fclaims=20(=C2=A74.1=20300-line=20cap,=20issue?=
 =?UTF-8?q?=20#287)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

check_doc_claims.py was 420 lines, over the repo's 300-line file cap
(CLAUDE.md, Code Style) before this PR needed to add floor-check machinery
to it (issue #287 — eliminating the six-file test-count conflict class).
Boy-scout fix (§14): the file is touched by this series regardless, so its
pre-existing size violation is fixed now rather than compounded.

Split by cohesion, matching the module's own "Claim | Owner" docstring
table: canonical truth-readers (doc_claim_sources.py), claim-scanning/
comparison machinery (doc_claim_scan.py), and badge/structural-integrity
checks (doc_claim_structural.py). check_doc_claims.py keeps thin wrapper
functions of the SAME names the test suite reaches via `gate.<name>` —
tests_py/scripts/test_check_doc_claims.py monkeypatches `gate.read` and
`gate.SCANNED_FILES` and relies on every check_doc_claims function
resolving those as bare (module-global) names to see the patch; moving a
function's BODY to another module while it still called `read` as a bare
name would silently stop seeing the test's fake and read the real
filesystem instead. The extracted functions take `read_fn`/`scanned_files`
as explicit parameters instead (constructor injection, coding-standards.md
§5) and check_doc_claims.py's wrappers pass its own (patchable) `read`/
`SCANNED_FILES` through — a mechanical verification, not a guess: read the
generated Python data model's attribute-resolution rules for module
globals vs. imported names before choosing this shape.

Before: check_doc_claims.py 420 lines (over cap).
After: check_doc_claims.py 232 lines; doc_claim_sources.py 107; doc_claim_scan.py 131; doc_claim_structural.py 174 (all under 300).
Tests: tests_py/scripts/test_check_doc_claims.py + test_generate_repo_badges.py — 86 passed, 30 subtests passed before AND after, 0 test files modified. Both scripts also re-verified as direct CLI invocations (`check_doc_claims.py --test-count 6609`, `generate_repo_badges.py --check --test-count 6609`), not just through the test harness's importlib loading.
ruff check + ruff format --check: clean on all four files.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 scripts/check_doc_claims.py     | 280 ++++++--------------------------
 scripts/doc_claim_scan.py       | 131 +++++++++++++++
 scripts/doc_claim_sources.py    | 107 ++++++++++++
 scripts/doc_claim_structural.py | 180 ++++++++++++++++++++
 4 files changed, 464 insertions(+), 234 deletions(-)
 create mode 100644 scripts/doc_claim_scan.py
 create mode 100644 scripts/doc_claim_sources.py
 create mode 100644 scripts/doc_claim_structural.py

diff --git a/scripts/check_doc_claims.py b/scripts/check_doc_claims.py
index 877c84bd..3d4185c6 100644
--- a/scripts/check_doc_claims.py
+++ b/scripts/check_doc_claims.py
@@ -39,6 +39,15 @@
 
     python scripts/check_doc_claims.py                 # static claims
     python scripts/check_doc_claims.py --test-count 5571
+
+Split across scripts/doc_claim_sources.py (canonical readers),
+scripts/doc_claim_scan.py (claim scanning/comparison) and
+scripts/doc_claim_structural.py (badge + structural-integrity checks) —
+issue #287, Extract Function/Move Function — to stay under the repo's
+300-line file cap (CLAUDE.md, Code Style); this module is the thin
+orchestrator each of those forwards through, and the only place ``read``/
+``SCANNED_FILES`` are defined (tests patch them here; see each sibling
+module's docstring for why they take these as parameters instead).
 """
 
 from __future__ import annotations
@@ -47,11 +56,21 @@
 import json
 import re
 import sys
-from collections.abc import Iterator
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 
+# Sibling modules, path-imported for the same reason generate_repo_badges.py
+# does it: resolves identically whether this runs as a script or is loaded
+# via importlib.util.spec_from_file_location from a test.
+_SCRIPTS_DIR = str(Path(__file__).resolve().parent)
+if _SCRIPTS_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPTS_DIR)
+import doc_claim_scan  # noqa: E402
+import doc_claim_sources  # noqa: E402
+import doc_claim_structural  # noqa: E402
+from doc_claim_sources import ClaimError  # noqa: E402  (re-export)
+
 # Files whose numbers describe the present. Release history lives elsewhere
 # (CHANGELOG.md, docs/release-notes/) and is deliberately not scanned.
 SCANNED_FILES = (
@@ -74,17 +93,6 @@
     ".bestpractices.json",
 )
 
-# A line introducing a past release states that release's numbers.
-HISTORY_MARKER = re.compile(r"\*\*v\d+\.\d+\.\d+")
-
-# A line whose number counts something else declares which family it is not a
-# claim for. Rewording the prose to dodge a pattern would hide a true, measured
-# number to keep the gate quiet; declaring it keeps the number and puts the
-# exemption on the record, at the one site that knows why it is not a claim.
-# The label must match a claim family exactly — an unrecognised or misspelled
-# label exempts nothing, so the marker fails closed.
-NOT_A_CLAIM = re.compile(r"\[not-a-count-claim: ([a-z][a-z ]*)\]")
-
 TOOL_CLAIM = re.compile(r"(\d+)\s+(?:memory|standalone|MCP)\s+tools\b")
 TOOL_TOTAL_CLAIM = re.compile(r"\((\d+)\s+(?:total\s+)?with\b[^)]*\)")
 REFERENCE_CLAIM = re.compile(r"(\d+)[-\s]reference\b")
@@ -96,167 +104,40 @@
 # only the first let a stale number sit unread in .bestpractices.json.
 TEST_CLAIM = re.compile(r"(\d+)(?:\s+tests|-test suite)\b")
 
-# The version and test badges are COMMITTED SVGs under assets/, not hotlinked
-# shields.io URLs, so their figures are read out of the files' own <title>.
-# These patterns replaced URL-shaped ones when the badges were self-hosted:
-# had they been left matching "badge/version-X.Y.Z", they would have found
-# nothing in the new README and both gates would have gone quiet while still
-# reporting success. A gate that cannot find its subject must fail, not pass.
-VERSION_BADGE = re.compile(r"<title>Version (\d+\.\d+\.\d+)</title>")
-TESTS_BADGE = re.compile(r"<title>(\d+) tests passing</title>")
-
-# Self-hosting the badges is only durable if reverting it is loud. Any
-# reintroduced shields.io hotlink in the README is a third-party beacon AND
-# silently detaches whichever claim it carries from the checks below.
-SHIELDS_HOTLINK = re.compile(r"img\.shields\.io")
-
-# An unresolved merge conflict inside a scanned file states BOTH sides of a
-# claim at once, so every check above reads a file that no longer says one
-# thing. This is not hypothetical: `.bestpractices.json` was committed with
-# four such blocks (branch sec/pin-dependencies-and-fuzzing, commit c090278,
-# found 2026-07-29) and shipped through the whole gate, because the claim
-# regexes matched the first side and never looked at the file's structure.
-#
-# Matched on the labelled markers only (`<<<<<<< HEAD`, `>>>>>>> origin/main`
-# — git always writes a ref after the seven characters). A bare `=======` is
-# deliberately NOT matched: it is a legal setext H1 underline in Markdown, and
-# half the scanned files are Markdown, so matching it would fail honest docs.
-CONFLICT_MARKER = re.compile(r"^(?:<{7}|>{7}) \S")
-
-# source: structural — str.split(marker, 1) yields exactly (before, after)
-# when the marker is present
-_MARKER_SPLIT_PARTS = 2
-
-
-class ClaimError(Exception):
-    """A canonical source could not be read — the gate cannot run blind."""
-
 
 def read(relative_path: str) -> str:
     return (REPO_ROOT / relative_path).read_text(encoding="utf-8")
 
 
 def canonical_tool_counts() -> tuple[int, int]:
-    """(standalone, total) from the mcp-tools.md header, cross-checked.
-
-    The header sentence is the single place the catalogue states the counts;
-    the pinned test name in tests_py/test_main.py carries the registry-derived
-    standalone number, so the two disagreeing means the catalogue drifted from
-    the server itself.
-    """
-    header = read("docs/mcp-tools.md")
-    match = re.search(
-        r"(\d+)\s+standalone tools register unconditionally;"
-        r"\s*(\d+)\s+more[^(]*\((\d+)\s+total",
-        header,
-    )
-    if not match:
-        raise ClaimError("docs/mcp-tools.md: standalone/total tool sentence not found")
-    standalone, extra, total = (int(g) for g in match.groups())
-    if standalone + extra != total:
-        raise ClaimError(f"docs/mcp-tools.md: {standalone} + {extra} != {total}")
-
-    pinned = re.search(
-        r"test_standalone_baseline_is_(\d+)_tools", read("tests_py/test_main.py")
-    )
-    if not pinned:
-        raise ClaimError("tests_py/test_main.py: pinned tool-count test not found")
-    if int(pinned.group(1)) != standalone:
-        raise ClaimError(
-            f"docs/mcp-tools.md says {standalone} standalone tools, but the pinned "
-            f"registry test says {pinned.group(1)}"
-        )
-    return standalone, total
+    return doc_claim_sources.canonical_tool_counts(read)
 
 
 def canonical_reference_count() -> int:
-    """Entries counted in the bibliography, which declares itself canonical."""
-    body = read("docs/papers/bibliography.md").split("## References", 1)
-    if len(body) != _MARKER_SPLIT_PARTS:
-        raise ClaimError(
-            "docs/papers/bibliography.md: '## References' section not found"
-        )
-    entries = [
-        line
-        for line in body[1].splitlines()
-        if line.strip() and not line.startswith(("#", "---"))
-    ]
-    if not entries:
-        raise ClaimError("docs/papers/bibliography.md: no reference entries found")
-    return len(entries)
+    return doc_claim_sources.canonical_reference_count(read)
 
 
 def canonical_mechanism_count() -> int:
-    """The mechanism count declared in the bibliography header.
-
-    Mechanisms are not machine-countable (they are implementations spread over
-    core modules), so one file declares the number and every other file must
-    agree with it. Changing the count is a one-line edit here plus whatever the
-    gate then reports as stale.
-    """
-    match = MECHANISM_CLAIM.search(read("docs/papers/bibliography.md"))
-    if not match:
-        raise ClaimError("docs/papers/bibliography.md: no mechanism count declared")
-    return int(match.group(1))
+    return doc_claim_sources.canonical_mechanism_count(read)
 
 
 def canonical_version() -> str:
-    match = re.search(r'^version\s*=\s*"([^"]+)"', read("pyproject.toml"), re.MULTILINE)
-    if not match:
-        raise ClaimError("pyproject.toml: [project].version not found")
-    return match.group(1)
-
-
-def scannable_lines() -> Iterator[tuple[str, int, str]]:
-    """Every (file, line number, text) that describes the present."""
-    for relative_path in SCANNED_FILES:
-        for number, line in enumerate(read(relative_path).splitlines(), start=1):
-            if not HISTORY_MARKER.search(line):
-                yield relative_path, number, line
+    return doc_claim_sources.canonical_version(read)
 
 
 def exemption_registry() -> list[tuple[str, int, str]]:
     """Every declared not-a-claim marker: (file, line, the family it exempts)."""
-    return [
-        (path, number, match.group(1))
-        for path, number, line in scannable_lines()
-        for match in NOT_A_CLAIM.finditer(line)
-    ]
+    return doc_claim_scan.exemption_registry(SCANNED_FILES, read)
 
 
 def scan_claims(pattern: re.Pattern[str], label: str) -> list[tuple[str, int, int]]:
-    """Every (file, line number, claimed value) that claims `label`.
-
-    A line declaring ``[not-a-count-claim: <label>]`` states that its number
-    counts something else; it is skipped for that family only, so the same
-    line still has to answer to every other one.
-    """
-    return [
-        (path, number, int(match.group(1)))
-        for path, number, line in scannable_lines()
-        if label not in {m.group(1) for m in NOT_A_CLAIM.finditer(line)}
-        for match in pattern.finditer(line)
-    ]
+    """Every (file, line number, claimed value) that claims `label`."""
+    return doc_claim_scan.scan_claims(pattern, label, SCANNED_FILES, read)
 
 
 def check_counts(pattern: re.Pattern[str], expected: int, label: str) -> list[str]:
-    """Report claims that disagree — and the absence of any claim at all.
-
-    A pattern that matches nothing would pass silently forever, which is how a
-    gate becomes decorative: the vacuity guard makes a reworded (or deleted)
-    claim a build failure rather than an unnoticed loss of coverage.
-    """
-    claims = scan_claims(pattern, label)
-    if not claims:
-        return [
-            f"no {label} claim found in any scanned file — "
-            f"the gate would pass vacuously"
-        ]
-    return [
-        f"{path}:{line}: advertises {claimed} {label}, canonical is {expected}"
-        for path, line, claimed in claims
-        if claimed != expected
-    ]
+    """Report claims that disagree — and the absence of any claim at all."""
+    return doc_claim_scan.check_counts(pattern, expected, label, SCANNED_FILES, read)
 
 
 def check_versions(expected: str) -> list[str]:
@@ -272,102 +153,29 @@ def check_versions(expected: str) -> list[str]:
             failures.append(
                 f"{relative_path}: version {actual!r}, pyproject says {expected!r}"
             )
-    failures += check_badge(
-        "assets/badge-version.svg", VERSION_BADGE, expected, "version"
+    failures += doc_claim_structural.check_badge(
+        "assets/badge-version.svg",
+        doc_claim_structural.VERSION_BADGE,
+        expected,
+        "version",
+        read,
     )
     return failures
 
 
-def check_badge(
-    relative_path: str, pattern: re.Pattern[str], expected: str, label: str
-) -> list[str]:
-    """One committed badge SVG states one figure, and it must be the right one.
-
-    Fails closed on an unreadable or unmatched badge. The predecessor of this
-    check was `if badge and ...` against a regex over the README, which passed
-    silently the moment the badge stopped matching — the failure mode that
-    makes a gate worse than no gate, because it still reports success.
-    """
-    try:
-        body = read(relative_path)
-    except FileNotFoundError:
-        return [f"{relative_path}: missing — run scripts/generate_repo_badges.py"]
-    match = pattern.search(body)
-    if match is None:
-        return [
-            f"{relative_path}: no {label} figure in its <title>; the badge and"
-            " this gate have diverged"
-        ]
-    if match.group(1) != expected:
-        return [
-            f"{relative_path}: {label} badge says {match.group(1)},"
-            f" canonical is {expected}"
-        ]
-    return []
-
-
 def check_no_hotlinked_badges() -> list[str]:
     """The README's repo-derived badges stay self-hosted."""
-    failures = []
-    for number, line in enumerate(read("README.md").splitlines(), start=1):
-        if SHIELDS_HOTLINK.search(line):
-            failures.append(
-                f"README.md:{number}: hotlinked shields.io badge — these are"
-                " committed under assets/ (scripts/generate_repo_badges.py)"
-            )
-    return failures
+    return doc_claim_structural.check_no_hotlinked_badges(read)
 
 
 def check_no_conflict_markers() -> list[str]:
-    """No scanned file states both sides of a claim at once.
-
-    A file left with git's conflict markers is not a document that drifted —
-    it is a document that says two contradictory things and parses as neither.
-    The claim regexes above cannot see this: they match the first side and
-    report success, which is how four such blocks reached a green CI run.
-    A file the gate cannot read at all is a failure too, for the same reason
-    the badge check fails closed — a check that skips its subject is worse
-    than no check, because it still prints OK.
-    """
-    failures = []
-    for relative_path in SCANNED_FILES:
-        try:
-            body = read(relative_path)
-        except FileNotFoundError:
-            failures.append(f"{relative_path}: missing — the doc-claim gate reads it")
-            continue
-        for number, line in enumerate(body.splitlines(), start=1):
-            if CONFLICT_MARKER.match(line):
-                failures.append(
-                    f"{relative_path}:{number}: unresolved merge conflict marker"
-                    f" ({line.strip()!r}) — the file states both sides of its claims"
-                )
-    return failures
+    """No scanned file states both sides of a claim at once."""
+    return doc_claim_structural.check_no_conflict_markers(SCANNED_FILES, read)
 
 
 def check_scanned_json_parses() -> list[str]:
-    """Every scanned .json file is still machine-readable.
-
-    `.bestpractices.json` is transcribed into the OpenSSF questionnaire and
-    `manifest.json` is read by the plugin loader, so a file that no longer
-    parses is a broken consumer, not just a stale number. Derived from
-    SCANNED_FILES rather than a second hand-kept list, so adding a JSON file
-    to the gate enrols it here with no edit to this function.
-    """
-    failures = []
-    for relative_path in SCANNED_FILES:
-        if not relative_path.endswith(".json"):
-            continue
-        try:
-            body = read(relative_path)
-        except FileNotFoundError:
-            failures.append(f"{relative_path}: missing — the doc-claim gate reads it")
-            continue
-        try:
-            json.loads(body)
-        except json.JSONDecodeError as error:
-            failures.append(f"{relative_path}: not valid JSON — {error}")
-    return failures
+    """Every scanned .json file is still machine-readable."""
+    return doc_claim_structural.check_scanned_json_parses(SCANNED_FILES, read)
 
 
 def collect_failures(test_count: int | None) -> list[str]:
@@ -382,8 +190,12 @@ def collect_failures(test_count: int | None) -> list[str]:
     failures += check_scanned_json_parses()
     if test_count is not None:
         failures += check_counts(TEST_CLAIM, test_count, "tests")
-        failures += check_badge(
-            "assets/badge-tests.svg", TESTS_BADGE, str(test_count), "tests"
+        failures += doc_claim_structural.check_badge(
+            "assets/badge-tests.svg",
+            doc_claim_structural.TESTS_BADGE,
+            str(test_count),
+            "tests",
+            read,
         )
     return failures
 
diff --git a/scripts/doc_claim_scan.py b/scripts/doc_claim_scan.py
new file mode 100644
index 00000000..06d1f039
--- /dev/null
+++ b/scripts/doc_claim_scan.py
@@ -0,0 +1,131 @@
+"""Claim-scanning machinery for scripts/check_doc_claims.py.
+
+Extracted (issue #287, Extract Function/Move Function) to keep
+check_doc_claims.py under the repo's 300-line file cap. Answers "does a
+scanned file's prose claim (a count, phrased as 'N things') agree with a
+canonical number" and "which lines have declared they are not a claim."
+
+`scanned_files`/`read_fn` are explicit parameters rather than module
+globals, so check_doc_claims.py's thin wrappers (which do reference its own
+`SCANNED_FILES`/`read` bare names, and so DO see `gate.read = fake` /
+`gate.SCANNED_FILES = (...)` patches in tests_py/scripts/test_check_doc_claims.py)
+can forward them through unchanged.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Iterator
+
+ReadFn = Callable[[str], str]
+
+# A line introducing a past release states that release's numbers.
+HISTORY_MARKER = re.compile(r"\*\*v\d+\.\d+\.\d+")
+
+# A line whose number counts something else declares which family it is not a
+# claim for. Rewording the prose to dodge a pattern would hide a true, measured
+# number to keep the gate quiet; declaring it keeps the number and puts the
+# exemption on the record, at the one site that knows why it is not a claim.
+# The label must match a claim family exactly — an unrecognised or misspelled
+# label exempts nothing, so the marker fails closed.
+NOT_A_CLAIM = re.compile(r"\[not-a-count-claim: ([a-z][a-z ]*)\]")
+
+
+def scannable_lines(
+    scanned_files: tuple[str, ...], read_fn: ReadFn
+) -> Iterator[tuple[str, int, str]]:
+    """Every (file, line number, text) that describes the present."""
+    for relative_path in scanned_files:
+        for number, line in enumerate(read_fn(relative_path).splitlines(), start=1):
+            if not HISTORY_MARKER.search(line):
+                yield relative_path, number, line
+
+
+def exemption_registry(
+    scanned_files: tuple[str, ...], read_fn: ReadFn
+) -> list[tuple[str, int, str]]:
+    """Every declared not-a-claim marker: (file, line, the family it exempts)."""
+    return [
+        (path, number, match.group(1))
+        for path, number, line in scannable_lines(scanned_files, read_fn)
+        for match in NOT_A_CLAIM.finditer(line)
+    ]
+
+
+def scan_claims(
+    pattern: re.Pattern[str],
+    label: str,
+    scanned_files: tuple[str, ...],
+    read_fn: ReadFn,
+) -> list[tuple[str, int, int]]:
+    """Every (file, line number, claimed value) that claims `label`.
+
+    A line declaring ``[not-a-count-claim: <label>]`` states that its number
+    counts something else; it is skipped for that family only, so the same
+    line still has to answer to every other one.
+    """
+    return [
+        (path, number, int(match.group(1)))
+        for path, number, line in scannable_lines(scanned_files, read_fn)
+        if label not in {m.group(1) for m in NOT_A_CLAIM.finditer(line)}
+        for match in pattern.finditer(line)
+    ]
+
+
+def check_counts(
+    pattern: re.Pattern[str],
+    expected: int,
+    label: str,
+    scanned_files: tuple[str, ...],
+    read_fn: ReadFn,
+) -> list[str]:
+    """Report claims that disagree — and the absence of any claim at all.
+
+    A pattern that matches nothing would pass silently forever, which is how a
+    gate becomes decorative: the vacuity guard makes a reworded (or deleted)
+    claim a build failure rather than an unnoticed loss of coverage.
+    """
+    claims = scan_claims(pattern, label, scanned_files, read_fn)
+    if not claims:
+        return [
+            f"no {label} claim found in any scanned file — "
+            f"the gate would pass vacuously"
+        ]
+    return [
+        f"{path}:{line}: advertises {claimed} {label}, canonical is {expected}"
+        for path, line, claimed in claims
+        if claimed != expected
+    ]
+
+
+def check_floor_counts(
+    pattern: re.Pattern[str],
+    actual: int,
+    label: str,
+    scanned_files: tuple[str, ...],
+    read_fn: ReadFn,
+) -> list[str]:
+    """Like check_counts, but `actual` is a floor, not an exact fact.
+
+    The test count is the one claim family no single PR branch can state
+    exactly: it is a property of the post-merge tree, and two branches that
+    each add tests compute two different, both-true, live counts (issue
+    #287 — the six-file conflict class, and the same race made main's own
+    gate flap red twice: PR #280 synced to its own total, #278 then added
+    more tests, and the committed figure was a true-when-written but now
+    stale UNDER-claim). A claim that understates the true count is not
+    false, so only an OVER-claim (someone hand-typed a number no measurement
+    backs, or tests were removed below what is claimed) is reported.
+    """
+    claims = scan_claims(pattern, label, scanned_files, read_fn)
+    if not claims:
+        return [
+            f"no {label} claim found in any scanned file — "
+            f"the gate would pass vacuously"
+        ]
+    return [
+        f"{path}:{line}: advertises {claimed} {label}, which exceeds the"
+        f" live count of {actual}"
+        for path, line, claimed in claims
+        if claimed > actual
+    ]
diff --git a/scripts/doc_claim_sources.py b/scripts/doc_claim_sources.py
new file mode 100644
index 00000000..cefaed4f
--- /dev/null
+++ b/scripts/doc_claim_sources.py
@@ -0,0 +1,107 @@
+"""Canonical truth-readers for scripts/check_doc_claims.py.
+
+Extracted (issue #287, Extract Function/Move Function) so check_doc_claims.py
+stays under the repo's 300-line file cap (CLAUDE.md, Code Style) — it had
+already crossed it (420 lines) before this change added the floor-check
+machinery check_doc_claims.py needed.
+
+Each function here answers ONE question: "what does the repository itself
+say tool/reference/mechanism/version counts are?" They take `read_fn` as an
+explicit parameter (constructor injection, coding-standards.md §5) rather
+than importing a module-level `read` — check_doc_claims.py keeps a thin
+wrapper of the same name that passes ITS OWN (test-patchable) `read`
+through, so `gate.read = fake` in tests_py/scripts/test_check_doc_claims.py
+still reaches these bodies exactly as it did before the split.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+
+ReadFn = Callable[[str], str]
+
+# str.split(marker, 1) yields exactly (before, after) when the marker is
+# present — source: structural, not measured.
+_MARKER_SPLIT_PARTS = 2
+
+
+class ClaimError(Exception):
+    """A canonical source could not be read — the gate cannot run blind."""
+
+
+def canonical_tool_counts(read_fn: ReadFn) -> tuple[int, int]:
+    """(standalone, total) from the mcp-tools.md header, cross-checked.
+
+    The header sentence is the single place the catalogue states the counts;
+    the pinned test name in tests_py/test_main.py carries the registry-derived
+    standalone number, so the two disagreeing means the catalogue drifted from
+    the server itself.
+    """
+    header = read_fn("docs/mcp-tools.md")
+    match = re.search(
+        r"(\d+)\s+standalone tools register unconditionally;"
+        r"\s*(\d+)\s+more[^(]*\((\d+)\s+total",
+        header,
+    )
+    if not match:
+        raise ClaimError("docs/mcp-tools.md: standalone/total tool sentence not found")
+    standalone, extra, total = (int(g) for g in match.groups())
+    if standalone + extra != total:
+        raise ClaimError(f"docs/mcp-tools.md: {standalone} + {extra} != {total}")
+
+    pinned = re.search(
+        r"test_standalone_baseline_is_(\d+)_tools", read_fn("tests_py/test_main.py")
+    )
+    if not pinned:
+        raise ClaimError("tests_py/test_main.py: pinned tool-count test not found")
+    if int(pinned.group(1)) != standalone:
+        raise ClaimError(
+            f"docs/mcp-tools.md says {standalone} standalone tools, but the pinned "
+            f"registry test says {pinned.group(1)}"
+        )
+    return standalone, total
+
+
+def canonical_reference_count(read_fn: ReadFn) -> int:
+    """Entries counted in the bibliography, which declares itself canonical."""
+    body = read_fn("docs/papers/bibliography.md").split("## References", 1)
+    if len(body) != _MARKER_SPLIT_PARTS:
+        raise ClaimError(
+            "docs/papers/bibliography.md: '## References' section not found"
+        )
+    entries = [
+        line
+        for line in body[1].splitlines()
+        if line.strip() and not line.startswith(("#", "---"))
+    ]
+    if not entries:
+        raise ClaimError("docs/papers/bibliography.md: no reference entries found")
+    return len(entries)
+
+
+def canonical_mechanism_count(read_fn: ReadFn) -> int:
+    """The mechanism count declared in the bibliography header.
+
+    Mechanisms are not machine-countable (they are implementations spread over
+    core modules), so one file declares the number and every other file must
+    agree with it. Changing the count is a one-line edit here plus whatever the
+    gate then reports as stale.
+    """
+    pattern = re.compile(
+        r"(\d+)\s+(?:neuroscience[- ]grounded|neuroscience|biological|brain)?"
+        r"\s*mechanisms\b"
+    )
+    match = pattern.search(read_fn("docs/papers/bibliography.md"))
+    if not match:
+        raise ClaimError("docs/papers/bibliography.md: no mechanism count declared")
+    return int(match.group(1))
+
+
+def canonical_version(read_fn: ReadFn) -> str:
+    match = re.search(
+        r'^version\s*=\s*"([^"]+)"', read_fn("pyproject.toml"), re.MULTILINE
+    )
+    if not match:
+        raise ClaimError("pyproject.toml: [project].version not found")
+    return match.group(1)
diff --git a/scripts/doc_claim_structural.py b/scripts/doc_claim_structural.py
new file mode 100644
index 00000000..da3c2897
--- /dev/null
+++ b/scripts/doc_claim_structural.py
@@ -0,0 +1,180 @@
+"""Badge and structural-integrity checks for scripts/check_doc_claims.py.
+
+Extracted (issue #287, Extract Function/Move Function) to keep
+check_doc_claims.py under the repo's 300-line file cap. Two concerns live
+here because both fail CLOSED on a file the gate cannot read or parse: badge
+freshness (does a committed SVG's own figure agree with the canonical one)
+and file structural integrity (unresolved merge conflicts, invalid JSON).
+
+`read_fn`/`scanned_files` are explicit parameters — see doc_claim_scan.py's
+module docstring for why (test-patch propagation through
+check_doc_claims.py's thin wrappers).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+
+ReadFn = Callable[[str], str]
+
+# The version and test badges are COMMITTED SVGs under assets/, not hotlinked
+# shields.io URLs, so their figures are read out of the files' own <title>.
+# These patterns replaced URL-shaped ones when the badges were self-hosted:
+# had they been left matching "badge/version-X.Y.Z", they would have found
+# nothing in the new README and both gates would have gone quiet while still
+# reporting success. A gate that cannot find its subject must fail, not pass.
+VERSION_BADGE = re.compile(r"<title>Version (\d+\.\d+\.\d+)</title>")
+TESTS_BADGE = re.compile(r"<title>(\d+) tests passing</title>")
+
+# Self-hosting the badges is only durable if reverting it is loud. Any
+# reintroduced shields.io hotlink in the README is a third-party beacon AND
+# silently detaches whichever claim it carries from the checks below.
+SHIELDS_HOTLINK = re.compile(r"img\.shields\.io")
+
+# An unresolved merge conflict inside a scanned file states BOTH sides of a
+# claim at once, so every check above reads a file that no longer says one
+# thing. This is not hypothetical: `.bestpractices.json` was committed with
+# four such blocks (branch sec/pin-dependencies-and-fuzzing, commit c090278,
+# found 2026-07-29) and shipped through the whole gate, because the claim
+# regexes matched the first side and never looked at the file's structure.
+#
+# Matched on the labelled markers only (`<<<<<<< HEAD`, `>>>>>>> origin/main`
+# — git always writes a ref after the seven characters). A bare `=======` is
+# deliberately NOT matched: it is a legal setext H1 underline in Markdown, and
+# half the scanned files are Markdown, so matching it would fail honest docs.
+CONFLICT_MARKER = re.compile(r"^(?:<{7}|>{7}) \S")
+
+
+def check_badge(
+    relative_path: str,
+    pattern: re.Pattern[str],
+    expected: str,
+    label: str,
+    read_fn: ReadFn,
+) -> list[str]:
+    """One committed badge SVG states one figure, and it must be the right one.
+
+    Fails closed on an unreadable or unmatched badge. The predecessor of this
+    check was `if badge and ...` against a regex over the README, which passed
+    silently the moment the badge stopped matching — the failure mode that
+    makes a gate worse than no gate, because it still reports success.
+    """
+    try:
+        body = read_fn(relative_path)
+    except FileNotFoundError:
+        return [f"{relative_path}: missing — run scripts/generate_repo_badges.py"]
+    match = pattern.search(body)
+    if match is None:
+        return [
+            f"{relative_path}: no {label} figure in its <title>; the badge and"
+            " this gate have diverged"
+        ]
+    if match.group(1) != expected:
+        return [
+            f"{relative_path}: {label} badge says {match.group(1)},"
+            f" canonical is {expected}"
+        ]
+    return []
+
+
+def check_badge_floor(
+    relative_path: str,
+    pattern: re.Pattern[str],
+    actual: int,
+    label: str,
+    read_fn: ReadFn,
+) -> list[str]:
+    """Like check_badge, but `actual` is a floor — see check_floor_counts.
+
+    Applies to the tests badge specifically: it is regenerated from a live
+    count that varies per branch, so an exact match would reintroduce the
+    same cross-branch conflict this floor family exists to remove.
+    """
+    try:
+        body = read_fn(relative_path)
+    except FileNotFoundError:
+        return [f"{relative_path}: missing — run scripts/generate_repo_badges.py"]
+    match = pattern.search(body)
+    if match is None:
+        return [
+            f"{relative_path}: no {label} figure in its <title>; the badge and"
+            " this gate have diverged"
+        ]
+    claimed = int(match.group(1))
+    if claimed > actual:
+        return [
+            f"{relative_path}: {label} badge says {claimed}, which exceeds"
+            f" the live count of {actual}"
+        ]
+    return []
+
+
+def check_no_hotlinked_badges(read_fn: ReadFn) -> list[str]:
+    """The README's repo-derived badges stay self-hosted."""
+    failures = []
+    for number, line in enumerate(read_fn("README.md").splitlines(), start=1):
+        if SHIELDS_HOTLINK.search(line):
+            failures.append(
+                f"README.md:{number}: hotlinked shields.io badge — these are"
+                " committed under assets/ (scripts/generate_repo_badges.py)"
+            )
+    return failures
+
+
+def check_no_conflict_markers(
+    scanned_files: tuple[str, ...], read_fn: ReadFn
+) -> list[str]:
+    """No scanned file states both sides of a claim at once.
+
+    A file left with git's conflict markers is not a document that drifted —
+    it is a document that says two contradictory things and parses as neither.
+    The claim regexes above cannot see this: they match the first side and
+    report success, which is how four such blocks reached a green CI run.
+    A file the gate cannot read at all is a failure too, for the same reason
+    the badge check fails closed — a check that skips its subject is worse
+    than no check, because it still prints OK.
+    """
+    failures = []
+    for relative_path in scanned_files:
+        try:
+            body = read_fn(relative_path)
+        except FileNotFoundError:
+            failures.append(f"{relative_path}: missing — the doc-claim gate reads it")
+            continue
+        for number, line in enumerate(body.splitlines(), start=1):
+            if CONFLICT_MARKER.match(line):
+                failures.append(
+                    f"{relative_path}:{number}: unresolved merge conflict marker"
+                    f" ({line.strip()!r}) — the file states both sides of its claims"
+                )
+    return failures
+
+
+def check_scanned_json_parses(
+    scanned_files: tuple[str, ...], read_fn: ReadFn
+) -> list[str]:
+    """Every scanned .json file is still machine-readable.
+
+    `.bestpractices.json` is transcribed into the OpenSSF questionnaire and
+    `manifest.json` is read by the plugin loader, so a file that no longer
+    parses is a broken consumer, not just a stale number. Derived from
+    the caller's scanned-file set rather than a second hand-kept list, so
+    adding a JSON file to the gate enrols it here with no edit to this
+    function.
+    """
+    failures = []
+    for relative_path in scanned_files:
+        if not relative_path.endswith(".json"):
+            continue
+        try:
+            body = read_fn(relative_path)
+        except FileNotFoundError:
+            failures.append(f"{relative_path}: missing — the doc-claim gate reads it")
+            continue
+        try:
+            json.loads(body)
+        except json.JSONDecodeError as error:
+            failures.append(f"{relative_path}: not valid JSON — {error}")
+    return failures

From 4f2c8c6da0c990dc4508497228bae232fd5f3850 Mon Sep 17 00:00:00 2001
From: cdeust <cdeust@icloud.com>
Date: Thu, 30 Jul 2026 11:32:59 +0200
Subject: [PATCH 2/7] =?UTF-8?q?refactor:=20Extract=20Function=20repo=5Fbad?=
 =?UTF-8?q?ge=5Fcatalog=20from=20generate=5Frepo=5Fbadges=20(=C2=A74.1=203?=
 =?UTF-8?q?00-line=20cap,=20issue=20#287)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

generate_repo_badges.py was 305 lines, over the repo's 300-line file cap
(CLAUDE.md, Code Style) before this PR needed to add tests-badge floor
logic to it (issue #287). Boy-scout fix (§14): fixed now, since the file
is touched by this series regardless.

_fixed_badges/_tests_badge and the six palette constants had no dependency
on `read`/check_doc_claims and were not referenced directly by any test
(confirmed via `grep -oE "gen\.[A-Za-z_]+" tests_py/scripts/test_generate_repo_badges.py`
— only gen._HEALTHY reads a moved constant, addressed by a re-export;
_fixed_badges/_tests_badge themselves are exercised only indirectly through
build_badges(), which stays put and is directly tested). Moved to
repo_badge_catalog.py as plain field dicts rather than RepoBadge instances:
RepoBadge is a `@dataclass` whose owning module matters to mutmut, and this
avoids ever constructing it from two different module-identities of the
same class.

Before: generate_repo_badges.py 305 lines (over cap).
After: generate_repo_badges.py 258 lines; repo_badge_catalog.py 87 (both under 300).
Tests: tests_py/scripts/test_check_doc_claims.py + test_generate_repo_badges.py — 86 passed, 30 subtests passed before AND after, 0 test files modified. Both scripts re-verified as direct CLI invocations.
ruff check + ruff format --check: clean.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 scripts/generate_repo_badges.py | 97 +++++++++------------------------
 scripts/repo_badge_catalog.py   | 87 +++++++++++++++++++++++++++++
 2 files changed, 112 insertions(+), 72 deletions(-)
 create mode 100644 scripts/repo_badge_catalog.py

diff --git a/scripts/generate_repo_badges.py b/scripts/generate_repo_badges.py
index 28a2578d..3ffd08e3 100644
--- a/scripts/generate_repo_badges.py
+++ b/scripts/generate_repo_badges.py
@@ -54,23 +54,24 @@
     sys.path.insert(0, _SCRIPTS_DIR)
 import badge_render  # noqa: E402
 import check_doc_claims  # noqa: E402
+import repo_badge_catalog  # noqa: E402
+
+# Only the label/message palette repo_badge_svg() itself renders with, plus
+# _HEALTHY (tests_py/scripts/test_generate_repo_badges.py reads
+# gen._HEALTHY), are re-exported here; _NEUTRAL/_CORPUS are used only by
+# repo_badge_catalog.fixed_badge_specs, which owns them (issue #287 split —
+# see that module's docstring for why it returns field dicts, not
+# RepoBadge instances, and never imports this class).
+from repo_badge_catalog import _HEALTHY as _HEALTHY  # noqa: E402  (re-export)
+from repo_badge_catalog import (  # noqa: E402
+    _LABEL_FILL,
+    _LABEL_TEXT,
+    _MESSAGE_TEXT,
+)
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 ASSETS_DIR = Path("assets")
 
-# The palette is assets/banner.svg's, shared with the MCP Toplist badge so
-# the README's badge row reads as one set rather than as a pile of styles.
-_LABEL_FILL = "#3b3129"
-_LABEL_TEXT = "#f8f7f2"
-_MESSAGE_TEXT = "#fff"
-
-# Message-panel fills. Distinct hues carry the same meaning the shields.io
-# originals did (blue = neutral fact, green = healthy, orange = corpus), so
-# the row's reading does not change with its hosting.
-_NEUTRAL = "#31708f"
-_HEALTHY = "#2f6f3e"
-_CORPUS = "#a53e00"
-
 
 @dataclass(frozen=True)
 class RepoBadge:
@@ -145,80 +146,32 @@ def canonical_python_floor() -> str:
     return tail.split('"', 1)[0]
 
 
-def _fixed_badges(
-    licence: str, floor: str, references: int, version: str
-) -> list[RepoBadge]:
-    """The four badges present on every run — none needs a live test count."""
-    return [
-        RepoBadge(
-            filename="badge-license.svg",
-            label="license",
-            message=licence,
-            fill=_NEUTRAL,
-            alt=f"License: {licence}",
-            derivation="Source: [project].license in pyproject.toml.",
-        ),
-        RepoBadge(
-            filename="badge-python.svg",
-            label="python",
-            message=f"{floor}+",
-            fill=_NEUTRAL,
-            alt=f"Python {floor}+",
-            derivation="Source: [project].requires-python in pyproject.toml.",
-        ),
-        RepoBadge(
-            filename="badge-references.svg",
-            label="references",
-            message=f"{references} papers",
-            fill=_CORPUS,
-            alt=f"{references} referenced papers",
-            derivation=(
-                "Source: entries under '## References' in docs/papers/bibliography.md."
-            ),
-        ),
-        RepoBadge(
-            filename="badge-version.svg",
-            label="version",
-            message=version,
-            fill=_HEALTHY,
-            alt=f"Version {version}",
-            derivation="Source: [project].version in pyproject.toml.",
-        ),
-    ]
-
-
-def _tests_badge(test_count: int) -> RepoBadge:
-    return RepoBadge(
-        filename="badge-tests.svg",
-        label="tests",
-        message=f"{test_count} passing",
-        fill=_HEALTHY,
-        alt=f"{test_count} tests passing",
-        derivation="Source: the count pytest collects on this tree.",
-    )
-
-
 def build_badges(test_count: int | None) -> list[RepoBadge]:
     """Every repo-derived badge, resolved against the working tree.
 
     The canonical readers are check_doc_claims's own, not reimplementations:
     a badge that disagreed with the gate would be the exact drift this file
-    exists to prevent. Split into `_fixed_badges`/`_tests_badge` (§4: a
-    50-line function cap) rather than one long literal-heavy body — a
-    boy-scout fix (§14), this function was 63 lines before this PR touched
-    the file for the unrelated `RepoBadge` mutation-attribution defect.
+    exists to prevent. The field data itself lives in repo_badge_catalog.py
+    (issue #287 split, §4: the 300-line file cap) — this function's own job
+    is only to resolve the canonical values and construct `RepoBadge`
+    instances from the returned specs.
     """
     version = check_doc_claims.canonical_version()
     references = check_doc_claims.canonical_reference_count()
     licence = canonical_licence()
     floor = canonical_python_floor()
-    badges = _fixed_badges(licence, floor, references, version)
+    badges = [
+        RepoBadge(**spec)
+        for spec in repo_badge_catalog.fixed_badge_specs(
+            licence, floor, references, version
+        )
+    ]
     # The test count is the one figure that cannot be read off a file: it is
     # whatever the suite collects right now. Omitted rather than guessed when
     # the caller has not measured it, so a stale badge is never written from
     # an assumption.
     if test_count is not None:
-        badges.append(_tests_badge(test_count))
+        badges.append(RepoBadge(**repo_badge_catalog.tests_badge_spec(test_count)))
     return badges
 
 
diff --git a/scripts/repo_badge_catalog.py b/scripts/repo_badge_catalog.py
new file mode 100644
index 00000000..63c1865b
--- /dev/null
+++ b/scripts/repo_badge_catalog.py
@@ -0,0 +1,87 @@
+"""Badge field specifications for scripts/generate_repo_badges.py.
+
+Extracted (issue #287, Extract Function/Move Function) to keep
+generate_repo_badges.py under the repo's 300-line file cap. Returns plain
+field dicts rather than `RepoBadge` instances: `RepoBadge` is a
+`@dataclass`-decorated class whose owning module matters to mutmut (see its
+docstring in generate_repo_badges.py), and generate_repo_badges.py's own
+tests load that module twice under two different dotted names (the direct
+`spec_from_file_location` load the test suite drives, plus whatever a bare
+`import generate_repo_badges` from a sibling would separately cache) — two
+non-identical `RepoBadge` classes existing side by side is a real, if
+usually harmless, risk (dataclass `__eq__`/`isinstance` compare by class
+identity). Keeping `RepoBadge` construction exclusively in
+generate_repo_badges.py and having this module hand back only primitive
+data (str/int, dict) sidesteps the question entirely: no class ever
+crosses this module boundary.
+"""
+
+from __future__ import annotations
+
+# The palette is assets/banner.svg's, shared with the MCP Toplist badge so
+# the README's badge row reads as one set rather than as a pile of styles.
+_LABEL_FILL = "#3b3129"
+_LABEL_TEXT = "#f8f7f2"
+_MESSAGE_TEXT = "#fff"
+
+# Message-panel fills. Distinct hues carry the same meaning the shields.io
+# originals did (blue = neutral fact, green = healthy, orange = corpus), so
+# the row's reading does not change with its hosting.
+_NEUTRAL = "#31708f"
+_HEALTHY = "#2f6f3e"
+_CORPUS = "#a53e00"
+
+TESTS_BADGE_FILENAME = "badge-tests.svg"
+
+
+def fixed_badge_specs(
+    licence: str, floor: str, references: int, version: str
+) -> list[dict[str, str]]:
+    """The four badges present on every run — none needs a live test count."""
+    return [
+        {
+            "filename": "badge-license.svg",
+            "label": "license",
+            "message": licence,
+            "fill": _NEUTRAL,
+            "alt": f"License: {licence}",
+            "derivation": "Source: [project].license in pyproject.toml.",
+        },
+        {
+            "filename": "badge-python.svg",
+            "label": "python",
+            "message": f"{floor}+",
+            "fill": _NEUTRAL,
+            "alt": f"Python {floor}+",
+            "derivation": "Source: [project].requires-python in pyproject.toml.",
+        },
+        {
+            "filename": "badge-references.svg",
+            "label": "references",
+            "message": f"{references} papers",
+            "fill": _CORPUS,
+            "alt": f"{references} referenced papers",
+            "derivation": (
+                "Source: entries under '## References' in docs/papers/bibliography.md."
+            ),
+        },
+        {
+            "filename": "badge-version.svg",
+            "label": "version",
+            "message": version,
+            "fill": _HEALTHY,
+            "alt": f"Version {version}",
+            "derivation": "Source: [project].version in pyproject.toml.",
+        },
+    ]
+
+
+def tests_badge_spec(test_count: int) -> dict[str, str]:
+    return {
+        "filename": TESTS_BADGE_FILENAME,
+        "label": "tests",
+        "message": f"{test_count} passing",
+        "fill": _HEALTHY,
+        "alt": f"{test_count} tests passing",
+        "derivation": "Source: the count pytest collects on this tree.",
+    }

From b1be0515f67858d453ad186f9555b80fe52649c0 Mon Sep 17 00:00:00 2001
From: cdeust <cdeust@icloud.com>
Date: Thu, 30 Jul 2026 11:48:34 +0200
Subject: [PATCH 3/7] =?UTF-8?q?fix:=20make=20the=20test-count=20claim=20a?=
 =?UTF-8?q?=20monotone=20floor,=20not=20a=20per-branch=20exact=20fact=20(i?=
 =?UTF-8?q?ssue=20#287,=20coding-standards.md=20=C2=A76=20root-cause=20fix?=
 =?UTF-8?q?)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Root cause (§6): check_doc_claims.py/generate_repo_badges.py required the
test-count claim in six files to EXACTLY equal the live `pytest
--collect-only` count of whichever branch's CI ran the check. That count is
a property of the post-merge tree, not of any one branch — two branches
that each add tests compute two different, both-true numbers and, to stay
green, each edits the SAME six lines to its own value. Whichever merges
second stomps the first's correct figure with its own now-stale one; this
is why main's gate went red twice (PR #280 synced to 6570, #278 added more
tests but had recorded 6560 against a stale base, and post-merge the
`--test-count`-computed canonical exceeded what the six files said).

Fix: assets/badge-tests.svg becomes the ONLY artifact stating an absolute
test count (the prose removal ships in the next commit), and its check
changes from equality to a monotone floor — `committed <= live` — in both
gates:
  - doc_claim_structural.check_badge_floor (check_doc_claims.py's
    collect_failures now calls this instead of check_badge for "tests";
    check_counts(TEST_CLAIM, ...) is no longer called for that family at
    all, since no prose file will state it after the next commit)
  - generate_repo_badges.stale_tests_badge (generate_repo_badges.py's
    main() --check branch excludes the tests badge from the plain,
    still-exact stale() loop and checks it here instead)

Both still fail on the one direction that IS a lie — an OVER-claim (a
hand-typed or stale-high number, or tests removed below what is claimed)
— and stale_tests_badge still runs the ordinary exact-match `stale()`
against the label/colour/provenance rendered with the COMMITTED count, so
structural drift in anything else about the badge fails exactly as before.

Test changes (deliberate — this is a contract change to the gate, not a
pure refactor, and these pin the OLD, now-superseded exact-match contract):
  - test_each_family_reports_its_own_stale_claim: dropped the "tests"
    subtest (no prose claim left to go stale)
  - test_the_test_badge_is_checked_against_the_live_count: replaced by
    test_an_over_claiming_test_badge_is_reported /
    test_an_under_claiming_test_badge_is_not_reported /
    test_an_exactly_matching_test_badge_is_not_reported /
    test_a_missing_test_badge_fails_closed /
    test_a_test_badge_without_a_matching_title_fails_closed (full branch
    coverage of check_badge_floor, for mutation testing)
  - test_every_advertised_test_count_states_the_same_number: repurposed to
    test_no_prose_file_states_the_suite_size_any_more, asserting scan_claims
    returns [] — a standing regression guard against a hardcoded count
    reappearing in ANY scanned file, .bestpractices.json included. This
    currently FAILS on the real tree (10 remaining occurrences across 5
    files) until the next commit removes them — expected, not a bug.
  - generate_repo_badges: new StaleTestsBadgeTests (6 methods, direct
    branch coverage of stale_tests_badge) + 2 new CheckModeTests methods
    exercising the floor through main() end-to-end.

Verified: tests_py/scripts/test_check_doc_claims.py +
tests_py/scripts/test_generate_repo_badges.py — 97 passed, 29 subtests
passed, 1 expected failure (the new regression guard, pending the next
commit). ruff check + ruff format --check clean. Both files re-verified as
direct CLI invocations against the real tree (still green: the currently
committed badge exactly equals the currently measured 6609, a trivial
floor pass).

Co-Authored-By: Claude <noreply@anthropic.com>
---
 scripts/check_doc_claims.py                   |  31 ++++-
 scripts/doc_claim_scan.py                     |  33 -----
 scripts/generate_repo_badges.py               |  41 +++++-
 tests_py/scripts/test_check_doc_claims.py     | 127 ++++++++++++------
 tests_py/scripts/test_generate_repo_badges.py |  62 +++++++++
 5 files changed, 216 insertions(+), 78 deletions(-)

diff --git a/scripts/check_doc_claims.py b/scripts/check_doc_claims.py
index 3d4185c6..4aed951e 100644
--- a/scripts/check_doc_claims.py
+++ b/scripts/check_doc_claims.py
@@ -20,7 +20,18 @@
 reference count      entries counted in ``docs/papers/bibliography.md``
 mechanism count      the count declared in that bibliography's header
 version              ``[project].version`` in ``pyproject.toml``
-test count           ``--test-count``, from a live ``pytest --collect-only``
+test count           ``assets/badge-tests.svg`` alone (issue #287) — the
+                     one artifact that still states an absolute figure. No
+                     prose file (nor ``.bestpractices.json``) states this
+                     count any more: a PR that adds tests would otherwise
+                     have to hand-edit six files to the same new number,
+                     and any two such PRs conflict on every one of them BY
+                     CONSTRUCTION. The badge is also not an exact fact —
+                     it is checked as a monotone FLOOR (``committed <=
+                     live``), because the true count is a property of the
+                     post-merge tree that no single branch can compute in
+                     advance; only an OVER-claim is reported. See
+                     ``doc_claim_structural.check_badge_floor``.
 ===================  =====================================================
 
 Release history is exempt: a line describing v4.13.0 may legitimately say
@@ -100,8 +111,14 @@
     r"(\d+)\s+(?:neuroscience[- ]grounded|neuroscience|biological|brain)?"
     r"\s*mechanisms\b"
 )
-# Both the "N tests" and the "N-test suite" phrasings state the count; matching
-# only the first let a stale number sit unread in .bestpractices.json.
+# Both the "N tests" and the "N-test suite" phrasings state the count. No
+# scanned file states this claim in prose any more (issue #287 — see the
+# module docstring's "test count" row); the pattern stays defined because
+# it is still the generic worked example scan_claims/check_counts's own
+# tests exercise, and tests_py/scripts/test_check_doc_claims.py asserts its
+# absence from the real tree as a standing regression guard (a re-added
+# hardcoded prose count would fail
+# RepositoryTests.test_no_prose_file_states_the_suite_size).
 TEST_CLAIM = re.compile(r"(\d+)(?:\s+tests|-test suite)\b")
 
 
@@ -189,11 +206,13 @@ def collect_failures(test_count: int | None) -> list[str]:
     failures += check_no_conflict_markers()
     failures += check_scanned_json_parses()
     if test_count is not None:
-        failures += check_counts(TEST_CLAIM, test_count, "tests")
-        failures += doc_claim_structural.check_badge(
+        # The tests badge is the ONLY test-count claim left (issue #287);
+        # see check_badge_floor's docstring for why it is a floor, not an
+        # exact match.
+        failures += doc_claim_structural.check_badge_floor(
             "assets/badge-tests.svg",
             doc_claim_structural.TESTS_BADGE,
-            str(test_count),
+            test_count,
             "tests",
             read,
         )
diff --git a/scripts/doc_claim_scan.py b/scripts/doc_claim_scan.py
index 06d1f039..66365408 100644
--- a/scripts/doc_claim_scan.py
+++ b/scripts/doc_claim_scan.py
@@ -96,36 +96,3 @@ def check_counts(
         for path, line, claimed in claims
         if claimed != expected
     ]
-
-
-def check_floor_counts(
-    pattern: re.Pattern[str],
-    actual: int,
-    label: str,
-    scanned_files: tuple[str, ...],
-    read_fn: ReadFn,
-) -> list[str]:
-    """Like check_counts, but `actual` is a floor, not an exact fact.
-
-    The test count is the one claim family no single PR branch can state
-    exactly: it is a property of the post-merge tree, and two branches that
-    each add tests compute two different, both-true, live counts (issue
-    #287 — the six-file conflict class, and the same race made main's own
-    gate flap red twice: PR #280 synced to its own total, #278 then added
-    more tests, and the committed figure was a true-when-written but now
-    stale UNDER-claim). A claim that understates the true count is not
-    false, so only an OVER-claim (someone hand-typed a number no measurement
-    backs, or tests were removed below what is claimed) is reported.
-    """
-    claims = scan_claims(pattern, label, scanned_files, read_fn)
-    if not claims:
-        return [
-            f"no {label} claim found in any scanned file — "
-            f"the gate would pass vacuously"
-        ]
-    return [
-        f"{path}:{line}: advertises {claimed} {label}, which exceeds the"
-        f" live count of {actual}"
-        for path, line, claimed in claims
-        if claimed > actual
-    ]
diff --git a/scripts/generate_repo_badges.py b/scripts/generate_repo_badges.py
index 3ffd08e3..e504e7f8 100644
--- a/scripts/generate_repo_badges.py
+++ b/scripts/generate_repo_badges.py
@@ -54,6 +54,7 @@
     sys.path.insert(0, _SCRIPTS_DIR)
 import badge_render  # noqa: E402
 import check_doc_claims  # noqa: E402
+import doc_claim_structural  # noqa: E402
 import repo_badge_catalog  # noqa: E402
 
 # Only the label/message palette repo_badge_svg() itself renders with, plus
@@ -201,6 +202,32 @@ def stale(badge: RepoBadge) -> str | None:
     return None
 
 
+def stale_tests_badge(test_count: int) -> str | None:
+    """A monotone floor, not an exact snapshot (issue #287, §6): two
+    branches adding tests compute two different, both-true live counts for
+    the same post-merge tree, so an exact match is how any two such PRs
+    conflicted on this file, and how main's gate flapped red on a merge
+    that only grew the count. Lagging behind `test_count` is not reported;
+    only an OVER-claim is. `stale()` still checks everything else exactly.
+    See doc_claim_structural.check_badge_floor for the same invariant.
+    """
+    badge = RepoBadge(**repo_badge_catalog.tests_badge_spec(test_count))
+    path = repo_badge_path(badge)
+    target = REPO_ROOT / path
+    if not target.exists():
+        return f"{path}: missing — run scripts/generate_repo_badges.py"
+    match = doc_claim_structural.TESTS_BADGE.search(target.read_text(encoding="utf-8"))
+    if match is None:
+        return f"{path}: no test-count figure in its <title>; diverged from this gate"
+    committed_count = int(match.group(1))
+    if committed_count > test_count:
+        return (
+            f"{path}: badge claims {committed_count} tests,"
+            f" exceeding the live count of {test_count}"
+        )
+    return stale(RepoBadge(**repo_badge_catalog.tests_badge_spec(committed_count)))
+
+
 def _build_parser() -> argparse.ArgumentParser:
     """Extracted so a test can assert its exact contract (description,
     per-flag help text, `--test-count`'s type) without re-parsing rendered
@@ -238,7 +265,19 @@ def main(argv: list[str] | None = None) -> int:
         return 2
 
     if args.check:
-        failures = [reason for badge in badges if (reason := stale(badge))]
+        # The tests badge is checked by stale_tests_badge (a monotone floor,
+        # not an exact match — see its docstring); every other badge keeps
+        # the plain, exact-match stale() unchanged.
+        failures = [
+            reason
+            for badge in badges
+            if badge.filename != repo_badge_catalog.TESTS_BADGE_FILENAME
+            and (reason := stale(badge))
+        ]
+        if args.test_count is not None:
+            reason = stale_tests_badge(args.test_count)
+            if reason:
+                failures.append(reason)
         if failures:
             print("Committed badges disagree with the repository:", file=sys.stderr)
             for failure in failures:
diff --git a/tests_py/scripts/test_check_doc_claims.py b/tests_py/scripts/test_check_doc_claims.py
index 33067c2f..4bc6fd8b 100644
--- a/tests_py/scripts/test_check_doc_claims.py
+++ b/tests_py/scripts/test_check_doc_claims.py
@@ -340,10 +340,13 @@ class CollectFailuresTests(unittest.TestCase):
     repository that is deliberately stale, one family at a time.
     """
 
+    # No test-count sentence: issue #287 removed that claim from prose
+    # entirely (only assets/badge-tests.svg — a monotone floor, checked
+    # below — still states one), so there is nothing left here for the
+    # "tests" family among the other four to disagree on.
     CONSISTENT = (
         "52 memory tools (55 total with upstream).\n"
         "A 2-reference bibliography of 36 mechanisms.\n"
-        "The suite has 6260 tests.\n"
     )
 
     def setUp(self):
@@ -354,23 +357,26 @@ def tearDown(self):
         gate.read = self._real_read
         gate.SCANNED_FILES = self._real_files
 
-    def _install(self, doc: str, badge: str = "6260", readme: str | None = None):
-        gate.read = _FakeRepo(
-            **{
-                "DOC.md": doc,
-                "docs/mcp-tools.md": CATALOGUE,
-                "tests_py/test_main.py": PINNED_TEST,
-                "docs/papers/bibliography.md": BIBLIOGRAPHY,
-                "pyproject.toml": '[project]\nversion = "4.16.0"\n',
-                "manifest.json": '{"version": "4.16.0"}',
-                "server.json": '{"version": "4.16.0"}',
-                "package.json": '{"version": "4.16.0"}',
-                "README.md": readme
-                or '<img src="assets/badge-tests.svg" alt="tests">\n',
-                "assets/badge-version.svg": "<title>Version 4.16.0</title>",
-                "assets/badge-tests.svg": f"<title>{badge} tests passing</title>",
-            }
-        ).read
+    def _install(self, doc: str, badge: str | None = "6260", readme: str | None = None):
+        files = {
+            "DOC.md": doc,
+            "docs/mcp-tools.md": CATALOGUE,
+            "tests_py/test_main.py": PINNED_TEST,
+            "docs/papers/bibliography.md": BIBLIOGRAPHY,
+            "pyproject.toml": '[project]\nversion = "4.16.0"\n',
+            "manifest.json": '{"version": "4.16.0"}',
+            "server.json": '{"version": "4.16.0"}',
+            "package.json": '{"version": "4.16.0"}',
+            "README.md": readme or '<img src="assets/badge-tests.svg" alt="tests">\n',
+            "assets/badge-version.svg": "<title>Version 4.16.0</title>",
+        }
+        # None omits the file entirely (a missing-badge scenario); any other
+        # string is spliced into the <title> as-is, so a non-digit value
+        # (e.g. "unknown") produces a title the TESTS_BADGE pattern will not
+        # match — see test_a_test_badge_without_a_matching_title_fails_closed.
+        if badge is not None:
+            files["assets/badge-tests.svg"] = f"<title>{badge} tests passing</title>"
+        gate.read = _FakeRepo(**files).read
         gate.SCANNED_FILES = ("DOC.md",)
 
     def test_a_consistent_repository_reports_nothing(self):
@@ -378,13 +384,18 @@ def test_a_consistent_repository_reports_nothing(self):
         self.assertEqual(gate.collect_failures(test_count=6260), [])
 
     def test_each_family_reports_its_own_stale_claim(self):
-        """One stale number per family, checked by the message it produces."""
+        """One stale number per family, checked by the message it produces.
+
+        "tests" is not one of these families any more (issue #287): it has
+        no prose claim to go stale in DOC.md. Its own family is exercised
+        below, against the badge, which is the one place left that states
+        a number.
+        """
         for old, new, expected in (
             ("52 memory tools", "50 memory tools", "advertises 50 tools,"),
             ("(55 total", "(53 total", "advertises 53 tools with integrations,"),
             ("2-reference", "3-reference", "advertises 3 references,"),
             ("36 mechanisms", "35 mechanisms", "advertises 35 mechanisms,"),
-            ("6260 tests", "6259 tests", "advertises 6259 tests,"),
         ):
             with self.subTest(family=expected):
                 self._install(self.CONSISTENT.replace(old, new))
@@ -392,11 +403,42 @@ def test_each_family_reports_its_own_stale_claim(self):
                 self.assertEqual(len(failures), 1, failures)
                 self.assertIn(expected, failures[0])
 
-    def test_the_test_badge_is_checked_against_the_live_count(self):
+    def test_an_over_claiming_test_badge_is_reported(self):
+        """The one direction that IS a lie: more tests than actually exist."""
+        self._install(self.CONSISTENT, badge="6261")
+        failures = gate.collect_failures(test_count=6260)
+        self.assertEqual(len(failures), 1, failures)
+        self.assertIn(
+            "tests badge says 6261, which exceeds the live count of 6260", failures[0]
+        )
+
+    def test_an_under_claiming_test_badge_is_not_reported(self):
+        """The floor invariant this whole family exists for (issue #287):
+        a badge that lags behind the live count is stale, not false, so a
+        PR that only adds tests never has to touch it to stay green — this
+        is what makes two such PRs stop conflicting on it.
+        """
         self._install(self.CONSISTENT, badge="6259")
+        self.assertEqual(gate.collect_failures(test_count=6260), [])
+
+    def test_an_exactly_matching_test_badge_is_not_reported(self):
+        self._install(self.CONSISTENT, badge="6260")
+        self.assertEqual(gate.collect_failures(test_count=6260), [])
+
+    def test_a_missing_test_badge_fails_closed(self):
+        self._install(self.CONSISTENT, badge=None)
         failures = gate.collect_failures(test_count=6260)
         self.assertEqual(len(failures), 1, failures)
-        self.assertIn("tests badge says 6259", failures[0])
+        self.assertIn(
+            "assets/badge-tests.svg: missing — run scripts/generate_repo_badges.py",
+            failures[0],
+        )
+
+    def test_a_test_badge_without_a_matching_title_fails_closed(self):
+        self._install(self.CONSISTENT, badge="unknown")
+        failures = gate.collect_failures(test_count=6260)
+        self.assertEqual(len(failures), 1, failures)
+        self.assertIn("no tests figure in its <title>", failures[0])
 
     def test_a_reintroduced_shields_hotlink_is_reported(self):
         """Self-hosting is only durable if reverting it is loud.
@@ -413,16 +455,16 @@ def test_a_reintroduced_shields_hotlink_is_reported(self):
         self.assertEqual(len(failures), 1, failures)
         self.assertIn("hotlinked shields.io badge", failures[0])
 
-    def test_without_a_live_count_the_test_family_is_not_checked(self):
+    def test_without_a_live_count_the_test_badge_is_not_checked(self):
         """The documented skip — and the reason it needs its own guard.
 
-        ``--test-count`` is only passed by one matrix leg of one CI job, so a
-        stale test count is invisible to every other caller of this script.
-        Pinning the skip keeps that a deliberate property rather than a
-        surprise; ``test_every_advertised_test_count_states_the_same_number``
-        is what covers the family everywhere else.
+        ``--test-count`` is only passed by one matrix leg of one CI job, so
+        the tests badge is unchecked by every other caller of this script.
+        The badge here would fail check_badge_floor outright (it massively
+        over-claims) if the check ran at all — asserting `[]` anyway proves
+        the skip, not a coincidental pass.
         """
-        self._install(self.CONSISTENT.replace("6260 tests", "1 tests"), badge="1")
+        self._install(self.CONSISTENT, badge="99999999")
         self.assertEqual(gate.collect_failures(test_count=None), [])
 
 
@@ -451,16 +493,25 @@ def test_the_declared_exemptions_are_the_reviewed_set(self):
             [("CONTRIBUTING.md", "tests")],
         )
 
-    def test_every_advertised_test_count_states_the_same_number(self):
-        """The test-count family, checked without a live pytest collection.
-
-        ``collect_failures`` skips TEST_CLAIM entirely when no --test-count is
-        passed, so the only place it was ever exercised was one matrix leg of
-        one CI job. Agreement between the sites needs no canonical value, so
-        this runs everywhere and catches a half-updated count locally.
+    def test_no_prose_file_states_the_suite_size_any_more(self):
+        """The regression guard for issue #287's root-cause fix.
+
+        Before: six files hand-carried the same exact test count, and any
+        two PRs that each added tests conflicted on all of them by
+        construction (every branch computed a different, both-true, live
+        number and had to hand-edit every site to match). Now only
+        assets/badge-tests.svg states one, as a monotone floor
+        (check_badge_floor) — nothing in prose does. This runs on every
+        `pytest` invocation (not gated behind a live --collect-only count
+        the way the badge check is), so a hardcoded count re-added to any
+        scanned file — including .bestpractices.json, whose four
+        occurrences this same fix removed — fails here immediately,
+        without needing a live count or a second PR to expose the race.
+        CONTRIBUTING.md:36's declared exemption (a true, unrelated
+        skipped-test measurement) is correctly excluded by TEST_CLAIM's own
+        [not-a-count-claim] handling, not by this assertion.
         """
-        counts = {value for _, _, value in gate.scan_claims(gate.TEST_CLAIM, "tests")}
-        self.assertEqual(len(counts), 1, f"advertised test counts disagree: {counts}")
+        self.assertEqual(gate.scan_claims(gate.TEST_CLAIM, "tests"), [])
 
 
 class StructuralIntegrityTests(unittest.TestCase):
diff --git a/tests_py/scripts/test_generate_repo_badges.py b/tests_py/scripts/test_generate_repo_badges.py
index 81b0ea11..985426e4 100644
--- a/tests_py/scripts/test_generate_repo_badges.py
+++ b/tests_py/scripts/test_generate_repo_badges.py
@@ -310,6 +310,68 @@ def test_an_unreadable_canonical_source_exits_two_not_one(self):
         gen.check_doc_claims.read = _FakeRepo().read
         self.assertEqual(gen.main(["--check", "--test-count", "42"]), 2)
 
+    def test_an_under_claiming_tests_badge_passes_check(self):
+        """The floor invariant (issue #287): a badge committed for a lower,
+        earlier count stays green once the live count only grows — the
+        property that lets a PR add tests without touching this file."""
+        gen.main(["--test-count", "42"])
+        self.assertEqual(gen.main(["--check", "--test-count", "44"]), 0)
+
+    def test_an_over_claiming_tests_badge_fails_check(self):
+        gen.main(["--test-count", "44"])
+        self.assertEqual(gen.main(["--check", "--test-count", "42"]), 1)
+
+
+class StaleTestsBadgeTests(_CanonicalSourceTestCase):
+    """Direct tests of stale_tests_badge — the floor check itself.
+
+    CheckModeTests exercises it only through main(); these pin every one of
+    its branches for mutation coverage (issue #287).
+    """
+
+    def setUp(self):
+        super().setUp()
+        self._tmp = TemporaryDirectory()
+        self._root = Path(self._tmp.name)
+        self._patch = mock.patch.object(gen, "REPO_ROOT", self._root)
+        self._patch.start()
+        self.addCleanup(self._patch.stop)
+        self.addCleanup(self._tmp.cleanup)
+
+    def _commit(self, test_count: int) -> None:
+        gen.write(gen.RepoBadge(**gen.repo_badge_catalog.tests_badge_spec(test_count)))
+
+    def test_missing_badge_is_reported(self):
+        self.assertIn("missing", gen.stale_tests_badge(42))
+
+    def test_a_title_without_a_count_is_reported(self):
+        target = self._root / "assets" / "badge-tests.svg"
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text("<svg><title>not a count</title></svg>")
+        self.assertIn("no test-count figure", gen.stale_tests_badge(42))
+
+    def test_an_exact_match_is_not_reported(self):
+        self._commit(42)
+        self.assertIsNone(gen.stale_tests_badge(42))
+
+    def test_an_under_claim_is_not_reported(self):
+        self._commit(41)
+        self.assertIsNone(gen.stale_tests_badge(42))
+
+    def test_an_over_claim_is_reported(self):
+        self._commit(43)
+        reason = gen.stale_tests_badge(42)
+        self.assertIn("43", reason)
+        self.assertIn("exceeding the live count of 42", reason)
+
+    def test_structural_drift_still_fails_even_at_a_valid_floor(self):
+        """A hand-edited label/colour must still fail — the floor loosens
+        only the number, never label/colour/provenance drift."""
+        self._commit(41)
+        target = self._root / "assets" / "badge-tests.svg"
+        target.write_text(target.read_text().replace("tests", "TESTS", 1))
+        self.assertIsNotNone(gen.stale_tests_badge(42))
+
 
 class WriteAndStaleTests(unittest.TestCase):
     """Direct tests of write()/stale() — the file I/O this gate performs.

From 3e2b107302e5eb7383b224e81b2a3d002400adf8 Mon Sep 17 00:00:00 2001
From: cdeust <cdeust@icloud.com>
Date: Thu, 30 Jul 2026 11:52:51 +0200
Subject: [PATCH 4/7] fix: remove the hard-coded test count from the five
 remaining files (issue #287)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Completes the root-cause fix begun in the prior commit: assets/badge-tests.svg
is now the ONLY artifact stating an absolute test count, checked as a monotone
floor (check_badge_floor / stale_tests_badge). These five point at it instead
of restating the figure by hand:

  - CLAUDE.md, CONTRIBUTING.md (x2), README.md (x2): dropped the number,
    pointing at assets/badge-tests.svg (README's badge alt text: "tests
    passing", matching the plain "CI" alt on the adjacent live-status badge
    rather than restating a number the image itself already carries).
  - docs/ASSURANCE-CASE.md: same, in the standing-analysis paragraph.
  - .bestpractices.json (4 fields: test_justification,
    tests_are_added_justification, dynamic_analysis_justification,
    automated_integration_testing_justification): reworded to point at the
    badge instead of restating an exact figure. The OpenSSF criteria these
    answer (test_status, tests_are_added, dynamic_analysis, automated_
    integration_testing) ask whether an automated suite exists, grows with
    new functionality, and runs in CI — not for a specific count, so the
    claim stays fully answerable without one. This was the file explicitly
    flagged as needing special care (transcribed into the OpenSSF Best
    Practices questionnaire); dropping the number here, like the other
    four, is simpler and more robust than keeping one on a generated
    ratchet, and every field it touches remains "Met" with unchanged
    justification quality.

Verified: the six-file conflict class's root artifact (a hard-coded
absolute count duplicated across independently-editable files) no longer
exists anywhere in prose or JSON —
tests_py/scripts/test_check_doc_claims.py::RepositoryTests::
test_no_prose_file_states_the_suite_size_any_more (added in the prior
commit specifically to enumerate every remaining occurrence) now passes;
it listed all 10 by file:line before this commit and lists none after.
.bestpractices.json re-validated as parseable JSON. Both gates re-run
against the real tree, both --test-count and static (no-count) modes:
`check_doc_claims.py` -> "doc claims OK"; `generate_repo_badges.py --check`
-> "badges OK" (5 checked with --test-count 6609, 4 checked without).
Full tests_py/scripts/ suite: 98 passed, 29 subtests passed, 0 failed.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .bestpractices.json    | 8 ++++----
 CLAUDE.md              | 2 +-
 CONTRIBUTING.md        | 4 ++--
 README.md              | 4 ++--
 docs/ASSURANCE-CASE.md | 5 +++--
 5 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/.bestpractices.json b/.bestpractices.json
index 1da781de..7e741691 100644
--- a/.bestpractices.json
+++ b/.bestpractices.json
@@ -99,7 +99,7 @@
   "build_floss_tools_justification": "pip, uv, hatchling, pytest, ruff and pyright are all FLOSS, and the build runs on ubuntu-latest and windows-latest GitHub runners.",
 
   "test_status": "Met",
-  "test_justification": "An automated test suite of 6673 tests lives under tests_py/ (measured 2026-07-30 with 'pytest --collect-only -q'), covering core, handlers, infrastructure, integration, invariants and architecture: https://github.com/cdeust/Cortex/tree/main/tests_py",
+  "test_justification": "An automated test suite lives under tests_py/ (current size tracked by assets/badge-tests.svg, regenerated from a live 'pytest --collect-only -q'), covering core, handlers, infrastructure, integration, invariants and architecture: https://github.com/cdeust/Cortex/tree/main/tests_py",
 
   "test_invocation_status": "Met",
   "test_invocation_justification": "The whole suite runs with a single 'pytest' command, documented in CONTRIBUTING.md under Testing along with per-layer subsets: https://github.com/cdeust/Cortex/blob/main/CONTRIBUTING.md",
@@ -114,7 +114,7 @@
   "test_policy_justification": "CONTRIBUTING.md carries an explicit, mandatory testing policy: new functionality ships with tests in the automated suite, a bug fix carries a regression test that fails on the pre-fix code, and each failure path asserts its observable effect including the signal it emits \u2014 https://github.com/cdeust/Cortex/blob/main/CONTRIBUTING.md#the-testing-policy-mandatory. The per-tool checklist ('Add a unit test', 'Add an integration test if the tool touches the database') and the five-element mechanism checklist restate it per change type.",
 
   "tests_are_added_status": "Met",
-  "tests_are_added_justification": "New functionality ships with its tests; the suite has grown to 6673 tests alongside the v4.x feature series, and CI runs it on every pull request.",
+  "tests_are_added_justification": "New functionality ships with its tests; the suite has grown continuously alongside the v4.x feature series (current size: assets/badge-tests.svg), and CI runs it on every pull request.",
 
   "tests_documented_added_status": "Met",
   "tests_documented_added_justification": "The requirement is written into the documented instructions for change proposals: https://github.com/cdeust/Cortex/blob/main/CONTRIBUTING.md#the-testing-policy-mandatory states that every change adding or altering observable behaviour must arrive with tests in the same PR, the per-tool and per-mechanism checklists repeat it as a concrete step, and .github/PULL_REQUEST_TEMPLATE.md requires a Test plan section in every pull request.",
@@ -189,7 +189,7 @@
   "static_analysis_often_justification": "CodeQL default setup analyses each push and pull request and additionally runs on a weekly schedule, so analysis happens per change rather than per release.",
 
   "dynamic_analysis_status": "Unmet",
-  "dynamic_analysis_justification": "No dynamic analysis tool in the badge's sense (fuzzer, sanitizer, or scanner) is applied. The project runs a 6673-test suite with coverage on every change, but a test suite is not a dynamic analysis tool and is not claimed as one here.",
+  "dynamic_analysis_justification": "No dynamic analysis tool in the badge's sense (fuzzer, sanitizer, or scanner) is applied. The project runs its automated test suite with coverage on every change, but a test suite is not a dynamic analysis tool and is not claimed as one here.",
 
   "dynamic_analysis_unsafe_status": "N/A",
   "dynamic_analysis_unsafe_justification": "Cortex is written in Python, a memory-safe language, so the memory-safety tooling this criterion asks about (ASan, Valgrind) does not apply.",
@@ -297,7 +297,7 @@
   "interfaces_current_justification": "The stack targets currently supported runtimes and APIs: Python 3.10 through 3.13, all four in the CI matrix, with pgvector 0.3+/PostgreSQL 17 and current major versions of FastMCP, Pydantic v2, numpy and sentence-transformers. Deprecated interfaces are removed rather than wrapped \u2014 the standing rule is one-shot migrations with no back-compat shims (CLAUDE.md), and CI runs on the newest released Python so a deprecation surfaces as a warning in the build rather than as a surprise at end of life.",
 
   "automated_integration_testing_status": "Met",
-  "automated_integration_testing_justification": "The full suite runs on every push and pull request to main via .github/workflows/ci.yml and reports success or failure per job: 6673 tests on Python 3.10-3.13 against PostgreSQL + pgvector, the same suite against the SQLite backend, the suite on Windows, and a Docker smoke job that boots the bare container and exercises the DB-less contract. tests_py/integration/ holds the database-backed integration tests specifically.",
+  "automated_integration_testing_justification": "The full suite runs on every push and pull request to main via .github/workflows/ci.yml and reports success or failure per job: the current-sized suite (assets/badge-tests.svg) on Python 3.10-3.13 against PostgreSQL + pgvector, the same suite against the SQLite backend, the suite on Windows, and a Docker smoke job that boots the bare container and exercises the DB-less contract. tests_py/integration/ holds the database-backed integration tests specifically.",
 
   "regression_tests_added50_status": "Met",
   "regression_tests_added50_justification": "Measured on 2026-07-27 over the merged pull requests titled as fixes in the preceding six months (2026-01-27 onward): 23 of 30 \u2014 76.7% \u2014 changed the test tree in the same PR, against the 50% this criterion asks for. (The measure counts a PR as carrying tests when it touches tests_py/ or tests_js/, which is a proxy for 'added a regression test'; the policy behind it is written down at https://github.com/cdeust/Cortex/blob/main/CONTRIBUTING.md#the-testing-policy-mandatory \u2014 a bug fix carries a regression test that fails on the pre-fix code.)",
diff --git a/CLAUDE.md b/CLAUDE.md
index d427d008..7977af11 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -23,7 +23,7 @@ coding write gates, causal graphs, and intent-aware retrieval.
   resolving from the `pyproject.toml` ranges instead gives you versions CI never
   had (issue #253).
 - Environment preflight: `python -m mcp_server.doctor` (backend-aware check list, fix message per check)
-- Tests: `pytest` (full suite, 6673 tests) · `pytest tests_py/core/` (one layer) · `pytest --cov=mcp_server --cov-report=term-missing`
+- Tests: `pytest` (full suite — current count: `assets/badge-tests.svg`, or run `pytest --collect-only -q`) · `pytest tests_py/core/` (one layer) · `pytest --cov=mcp_server --cov-report=term-missing`
 - Lint BEFORE every commit: `ruff check && ruff format --check` — the CI enforces **both**; passing only `ruff check` is not enough.
 - Type gate (pyright, zero-diagnostic): resolve its environment from `uv.lock`
   (`uv sync --no-default-groups --extra … --group typecheck`), never from the
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 08729804..83ed692e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -51,7 +51,7 @@ bash scripts/setup.sh        # macOS / Linux
 # Verify everything is wired
 uvx --python 3.13 --from "hypermnesia-mcp[postgresql]" cortex-doctor
 
-# Run tests (6673 tests under tests_py/)
+# Run tests (under tests_py/; current count: assets/badge-tests.svg)
 pytest
 
 # Run a benchmark
@@ -163,7 +163,7 @@ The full standard lives in
 ## Testing
 
 ```bash
-pytest                              # full suite (6673 tests)
+pytest                              # full suite (see assets/badge-tests.svg for the current count)
 pytest tests_py/core                # core (pure business logic) only
 pytest tests_py/integration         # PostgreSQL-backed integration
 pytest tests_py/benchmarks -k locomo # subset
diff --git a/README.md b/README.md
index 02f692d9..08cf7991 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
   <a href="https://github.com/cdeust/Cortex/actions/workflows/ci.yml"><img src="https://github.com/cdeust/Cortex/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="LICENSE"><img src="assets/badge-license.svg" alt="License: MIT"></a>
   <img src="assets/badge-python.svg" alt="Python 3.10+">
-  <img src="assets/badge-tests.svg" alt="6673 tests passing">
+  <img src="assets/badge-tests.svg" alt="tests passing">
   <img src="assets/badge-references.svg" alt="97 referenced papers">
   <img src="assets/badge-version.svg" alt="Version 4.16.0">
   <a href="https://www.bestpractices.dev/projects/13836"><img src="https://www.bestpractices.dev/projects/13836/badge" alt="OpenSSF Best Practices"></a>
@@ -526,7 +526,7 @@ Cortex is **local-first**: your memories, conversations, and profiles stay on yo
 ## Development
 
 ```bash
-pytest                    # 6673 tests
+pytest                    # full suite (see assets/badge-tests.svg for the current count)
 ruff check .              # Lint
 ruff format --check .     # Format
 python scripts/check_doc_claims.py   # advertised counts must match the repo
diff --git a/docs/ASSURANCE-CASE.md b/docs/ASSURANCE-CASE.md
index 21f77b30..ffee1238 100644
--- a/docs/ASSURANCE-CASE.md
+++ b/docs/ASSURANCE-CASE.md
@@ -128,8 +128,9 @@ decoratively:
 
 Standing analysis: CodeQL default setup (Python, JavaScript/TypeScript,
 Actions) on every push and pull request plus weekly, currently 0 open alerts;
-OpenSSF Scorecard via `.github/workflows/scorecard.yml`; and 6673 tests run on
-four Python versions, two backends and Windows.
+OpenSSF Scorecard via `.github/workflows/scorecard.yml`; and the full automated
+test suite (`assets/badge-tests.svg` carries the current count) runs on four
+Python versions, two backends and Windows.
 
 ## 6. What this assurance case does NOT claim
 

From fd266e395a7f10c4d820547c0dc42942c5d9f086 Mon Sep 17 00:00:00 2001
From: cdeust <cdeust@icloud.com>
Date: Thu, 30 Jul 2026 11:55:32 +0200
Subject: [PATCH 5/7] docs: CHANGELOG entry for the test-count conflict-class
 fix (issue #287)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

§13.1 H4 — this is an observable contract change (five files no longer
state a number; the badge check's semantics moved from exact to floor) and
gets its own entry, alongside a note on why check_doc_claims.py/
generate_repo_badges.py needed the Extract Module split first. Verified
the CI workflow's own comments (ci.yml lines ~179-204, ~429-444) describe
WHERE/WHEN the checks run, not the equality-vs-floor comparison semantics
that changed — re-read against the current diff, neither needed an edit.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d8f1aee5..e538cbe3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,7 @@ adheres to [Semantic Versioning](https://semver.org/).
 - **`scripts/setup.sh` reported success over any install failure**: the dependency install ended in `2>/dev/null`, which is where a resolution failure, a hash mismatch and a network error all appear, and the script printed "Python packages installed" regardless. Its exit status is now checked. Its hand-written package list — a duplicate of `pyproject.toml` — had already drifted from it, asking for `sentence-transformers>=2.2.0` against a real floor of `>=3.0.0`, and is replaced by the generated hashed file.
 - **`.gitattributes` marks `fuzz/corpus/**` as binary**: end-of-line normalisation would have rewritten the CRLF corpus seed to LF on checkout, silently deleting the case that seed exists to cover.
 - **`.bestpractices.json` was committed carrying four unresolved merge-conflict blocks**, which left it invalid JSON — and the file is transcribed into the OpenSSF Best Practices questionnaire, so an unparseable copy is a broken consumer rather than a stale number. It passed the doc-claim gate, CodeQL and 18 green checks, because `.bestpractices.json` is one of that gate's own `SCANNED_FILES` and every check it runs is a claim regex: a regex matches the first side of a conflict and never looks at the file's structure. Both sides of all four blocks were byte-identical, so the repair is lossless (verified by comparing the sides, not by choosing one). The gate now also runs `check_no_conflict_markers` and `check_scanned_json_parses`, both derived from `SCANNED_FILES` so a newly scanned file is enrolled with no further edit, and both failing closed on a file they cannot read. Only the **labelled** markers are matched (`<<<<<<< HEAD`, `>>>>>>> origin/main`) — a bare `=======` is a legal setext H1 underline in Markdown, and most scanned files are Markdown, so matching it would fail honest documents; a test pins that.
+- **Any two PRs that added tests conflicted on six files, by construction — eliminated at the root** (#287). The collected test count was hand-carried as an exact figure in `.bestpractices.json`, `CLAUDE.md`, `CONTRIBUTING.md` (×2), `README.md` (×2) and `docs/ASSURANCE-CASE.md`, each checked for EQUALITY against whichever branch's own live `pytest --collect-only` count ran in CI. That count is a property of the post-merge tree, not of any one branch: two branches that each add tests compute two different, both-true numbers and must each edit the same six lines to match, so the second to merge silently overwrites the first's correct figure with its own now-stale one — measured on this repo as two red `main` runs (PR #280 synced to its own total, #278 added more tests against a stale base) and a PR rebased three times solely to resolve the resulting conflicts. `assets/badge-tests.svg` is now the ONLY artifact stating an absolute count; the five others point at it instead of restating the figure. The badge's own check moves from an exact match to a monotone **floor** (`doc_claim_structural.check_badge_floor`, `generate_repo_badges.stale_tests_badge`): a committed count that lags the live one is stale-but-true and passes, so a PR that only adds tests never touches it, and only an actual OVER-claim — a hand-typed number, or tests removed below what was claimed — fails. A standing regression guard (`test_no_prose_file_states_the_suite_size_any_more`) asserts no scanned file, including `.bestpractices.json`, states this claim in prose again. `check_doc_claims.py` (420 lines) and `generate_repo_badges.py` (305 lines) were both over the repo's 300-line file cap before this change needed to touch them further; split into `doc_claim_sources.py`/`doc_claim_scan.py`/`doc_claim_structural.py`/`repo_badge_catalog.py` (Extract Module) with zero behavior change, verified by an unchanged existing test suite before the floor logic was added.
 
 ### Added
 - **The README's repo-derived badges are now self-hosted SVGs, gated in CI** — `assets/badge-{license,python,tests,references,version}.svg`, `scripts/generate_repo_badges.py`, `scripts/badge_render.py`. Five hotlinked `img.shields.io` images became committed files, for the reason the MCP Toplist badge already was one: a remote badge URL is a third-party request fired on every README view, and it lets its host restate our claim with no commit in this repository. **Only repo-derived figures were converted**, and the line is deliberate — every one of these (licence, Python floor, collected test count, bibliography size, package version) is determined BY THIS REPOSITORY, so a committed copy can always be made true again from the working tree with no network access. That is why they are kept honest by a **blocking `--check` gate on every push and PR** rather than by a cron: drift is caught where it is introduced. **Two badges were deliberately NOT converted and must not be:** the CI status badge reports the LIVE result of the last run on main, so a committed copy would assert "passing" while main was broken — a static build-status badge is a false claim by construction, not merely a stale one — and it is GitHub-hosted, so it is not a third-party beacon in the first place; the OpenSSF Best Practices badge reflects an external body's live assessment that can be downgraded without any commit here, and `.bestpractices.json` separately justifies displaying THEIR badge image. The MCP Toplist badge sits between the two and stays committed because it carries an explicit "as of <month>" stamp, which keeps a stale copy a true statement about a point in time. **The conversion had to rewire the gate it would otherwise have silenced:** `check_doc_claims.py` enforced the version and test-count claims by regex over the shields.io URLs (`badge/version-(\d+\.\d+\.\d+)`, `badge/tests-(\d+)_passing`), so self-hosting alone would have left both patterns matching nothing while the gate still reported success. They now read the figure out of the committed SVG's own `<title>` and **fail closed** on a missing file or an unmatched title — the predecessor's `if badge and ...` passed silently the moment its subject disappeared. A new check also fails any reintroduced `img.shields.io` hotlink in the README, so reverting this is loud rather than quiet. Found by the new tests before shipping: `--` is illegal inside an XML comment, and the first cut described its own gate as `--check` and its source as `pytest --collect-only` in the provenance comment, leaving **all five badges unparseable**; the renderer now parses every badge it produces and refuses to return one that is not well-formed, so no future wording can reintroduce the class. The shared renderer was extracted from the MCP Toplist refresher first, as a separate behavior-preserving commit whose proof is that `assets/badge-mcp-toplist.svg` is byte-identical and its 51 tests pass unchanged. Suite grows 6348 → 6373.

From cb77d9f15f003861864ee9293141a6f7a101a408 Mon Sep 17 00:00:00 2001
From: cdeust <cdeust@icloud.com>
Date: Thu, 30 Jul 2026 12:01:15 +0200
Subject: [PATCH 6/7] fix(mutmut): add assets/ to also_copy, closing a
 scoped-run blocker for check_doc_claims.py (issue #287)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Boy-scout fix (§14) — seen while running the mutation testing this same
series requires on scripts/check_doc_claims.py's new floor-check logic.
tests_py/scripts/test_check_doc_claims.py::RepositoryTests runs UNPATCHED
against the real tree, and check_versions -> check_badge reads
assets/badge-version.svg directly off disk; assets/ was absent from
also_copy, so a scoped mutmut run naming check_doc_claims.py or
generate_repo_badges.py failed EVERY mutant on "assets/badge-version.svg:
missing" (reproduced empirically, both via `uv run mutmut` and via mutmut
invoked directly against the shared .venv) before scoring a single one —
the exact "no usable result" failure mode the existing also_copy comments
already describe for .github/uv.lock/requirements, just for a file nobody
had scoped in yet.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 pyproject.toml | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/pyproject.toml b/pyproject.toml
index fd91a578..3ea7e4bf 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -518,11 +518,18 @@ only_mutate = ["mcp_server/shared/json_native.py"]
 # .github/workflows/ci.yml directly; without it, a scoped run that selects
 # that test fails collection under every mutant with FileNotFoundError
 # instead of scoring the suite — issue #262.
+# assets: check_doc_claims.py's own unpatched RepositoryTests read the
+# committed badge SVGs (check_versions -> check_badge) directly off disk;
+# without this a scoped run that includes check_doc_claims.py/
+# generate_repo_badges.py fails EVERY mutant on "assets/badge-version.svg:
+# missing" before it can score a single one — reproduced empirically
+# (issue #287) attempting exactly that run.
 also_copy = [
     ".github",
     "tests_py",
     "deps",
     "docs",
+    "assets",
     "README.md",
     "CONTRIBUTING.md",
     "SECURITY.md",

From a3c54cd468492dd0d6cab3e1ebeb2b4822f30514 Mon Sep 17 00:00:00 2001
From: cdeust <cdeust@icloud.com>
Date: Thu, 30 Jul 2026 12:28:44 +0200
Subject: [PATCH 7/7] fix(mutmut): kill 5 real survivors from mutation-testing
 the floor-check logic; correct a citation error (issue #293, was mis-cited
 #287)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Citation correction (§8 / no-invented-references): every prior commit in
this series, and the code/test comments they added, cited "issue #287".
That number was never verified before use — it turned out to already be a
real, unrelated, open issue ("Local dev venv (macOS, reused .venv) collects
10 fewer tests than CI's hash-pinned Linux install"). Filed the actual
tracking issue for this fix (#293) and replaced every "#287" reference
across CHANGELOG.md, pyproject.toml, and every scripts/*.py + tests_py/
scripts/*.py file this series touches. The earlier commits' own messages
are left as committed history (this repo's convention is new commits, not
rewritten ones) — this commit's message is the correction record.

Mutation testing (§12), scoped to the three files carrying new/changed
logic (scripts/check_doc_claims.py, scripts/doc_claim_structural.py,
scripts/generate_repo_badges.py) against tests_py/scripts/
test_check_doc_claims.py + test_generate_repo_badges.py, direct mutmut
invocation against the shared .venv (`uv run` creates a fresh venv missing
required_plugins — reproduces the documented issue #262/#283 finding).

Two real gaps found and fixed:
  - encoding=None survived both scripts/check_doc_claims.py's read() and
    generate_repo_badges.stale_tests_badge's read_text call: neither test
    pinned the encoding kwarg, and every committed badge's provenance
    comment (and most scanned Markdown) contains an em dash a locale
    default can mis-decode (Windows is in this project's CI matrix). Fixed
    with the SAME mock-spy technique this file's own
    test_write_pins_utf8_on_both_the_read_and_the_write already
    established (assert read_spy.call_args(_list).kwargs["encoding"] ==
    "utf-8"); the stale_tests_badge version checks EVERY call in the list,
    not just the last, because it falls through to stale()'s own separate
    read_text call which would otherwise mask the first.
  - check_badge_floor's "no title match" message: the test asserted only
    the prefix ("no tests figure in its <title>"), so a mutant altering
    the trailing "this gate have diverged" clause survived. Now asserts
    the full message.

One inert mutant eliminated by fixing the code rather than documenting it
as equivalent: stale_tests_badge constructed a whole RepoBadge from
test_count just to read its constant .filename; resolves the path from
repo_badge_catalog.TESTS_BADGE_FILENAME directly instead.

One infrastructure defect found and fixed: EVERY mutant in
doc_claim_structural.py showed "no tests" under the scoped run. Root
cause, confirmed by reading mutmut/mutation/trampoline.py: its dispatcher
activates a mutant only when the calling module's __name__ matches the
dotted, path-derived name mutmut generated the mutant under
("scripts.doc_claim_structural"); check_doc_claims.py's bare `import
doc_claim_structural` gives every function in that file `__module__ ==
"doc_claim_structural"` (no "scripts." prefix), so the trampoline never
activates and stats attribution never fires — the exact defect class this
file's own test_generate_repo_badges.py already documents and works
around for badge_render.py. Fixed the same way: test_check_doc_claims.py
now also loads doc_claim_structural.py under its own dotted name, and the
new CheckBadgeFloorDirectTests calls check_badge_floor through that
reference — 12/12 of its mutants went from "no tests" to attributed
(10 killed outright, 2 real survivors above, both now fixed). The other
three functions in doc_claim_structural.py, plus doc_claim_scan.py/
doc_claim_sources.py/repo_badge_catalog.py (not in this run's scope),
likely have the same gap — filed as its own issue (#292) per §15.1 rather
than folded in here, since fixing it needs no change to this PR's own
logic.

Final scoped tally: 453 mutants, 361 killed, 87 not-covered (documented
above, tracked as #292), 5 survivors — all 5 pre-existing, in
canonical_licence/canonical_python_floor/_build_parser (unmodified by this
series), and already self-documented as equivalent by comments predating
this change (maxsplit=1 vs 0/2/-1 equivalence; default=None as argparse's
own implicit default) — re-verified, not re-asserted from scratch.

Tests: tests_py/scripts/test_check_doc_claims.py +
test_generate_repo_badges.py — 105 passed, 29 subtests passed (was 100/29
before this commit's 5 new direct tests + 1 dotted-load addition). ruff
check + ruff format --check clean. Both scripts re-verified as direct CLI
invocations against the real tree.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   2 +-
 pyproject.toml                                |   2 +-
 scripts/check_doc_claims.py                   |  16 ++-
 scripts/doc_claim_scan.py                     |   2 +-
 scripts/doc_claim_sources.py                  |   2 +-
 scripts/doc_claim_structural.py               |   2 +-
 scripts/generate_repo_badges.py               |  29 +++--
 scripts/repo_badge_catalog.py                 |   2 +-
 tests_py/scripts/test_check_doc_claims.py     | 113 +++++++++++++++++-
 tests_py/scripts/test_generate_repo_badges.py |  22 +++-
 10 files changed, 161 insertions(+), 31 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e538cbe3..a183e164 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,7 +25,7 @@ adheres to [Semantic Versioning](https://semver.org/).
 - **`scripts/setup.sh` reported success over any install failure**: the dependency install ended in `2>/dev/null`, which is where a resolution failure, a hash mismatch and a network error all appear, and the script printed "Python packages installed" regardless. Its exit status is now checked. Its hand-written package list — a duplicate of `pyproject.toml` — had already drifted from it, asking for `sentence-transformers>=2.2.0` against a real floor of `>=3.0.0`, and is replaced by the generated hashed file.
 - **`.gitattributes` marks `fuzz/corpus/**` as binary**: end-of-line normalisation would have rewritten the CRLF corpus seed to LF on checkout, silently deleting the case that seed exists to cover.
 - **`.bestpractices.json` was committed carrying four unresolved merge-conflict blocks**, which left it invalid JSON — and the file is transcribed into the OpenSSF Best Practices questionnaire, so an unparseable copy is a broken consumer rather than a stale number. It passed the doc-claim gate, CodeQL and 18 green checks, because `.bestpractices.json` is one of that gate's own `SCANNED_FILES` and every check it runs is a claim regex: a regex matches the first side of a conflict and never looks at the file's structure. Both sides of all four blocks were byte-identical, so the repair is lossless (verified by comparing the sides, not by choosing one). The gate now also runs `check_no_conflict_markers` and `check_scanned_json_parses`, both derived from `SCANNED_FILES` so a newly scanned file is enrolled with no further edit, and both failing closed on a file they cannot read. Only the **labelled** markers are matched (`<<<<<<< HEAD`, `>>>>>>> origin/main`) — a bare `=======` is a legal setext H1 underline in Markdown, and most scanned files are Markdown, so matching it would fail honest documents; a test pins that.
-- **Any two PRs that added tests conflicted on six files, by construction — eliminated at the root** (#287). The collected test count was hand-carried as an exact figure in `.bestpractices.json`, `CLAUDE.md`, `CONTRIBUTING.md` (×2), `README.md` (×2) and `docs/ASSURANCE-CASE.md`, each checked for EQUALITY against whichever branch's own live `pytest --collect-only` count ran in CI. That count is a property of the post-merge tree, not of any one branch: two branches that each add tests compute two different, both-true numbers and must each edit the same six lines to match, so the second to merge silently overwrites the first's correct figure with its own now-stale one — measured on this repo as two red `main` runs (PR #280 synced to its own total, #278 added more tests against a stale base) and a PR rebased three times solely to resolve the resulting conflicts. `assets/badge-tests.svg` is now the ONLY artifact stating an absolute count; the five others point at it instead of restating the figure. The badge's own check moves from an exact match to a monotone **floor** (`doc_claim_structural.check_badge_floor`, `generate_repo_badges.stale_tests_badge`): a committed count that lags the live one is stale-but-true and passes, so a PR that only adds tests never touches it, and only an actual OVER-claim — a hand-typed number, or tests removed below what was claimed — fails. A standing regression guard (`test_no_prose_file_states_the_suite_size_any_more`) asserts no scanned file, including `.bestpractices.json`, states this claim in prose again. `check_doc_claims.py` (420 lines) and `generate_repo_badges.py` (305 lines) were both over the repo's 300-line file cap before this change needed to touch them further; split into `doc_claim_sources.py`/`doc_claim_scan.py`/`doc_claim_structural.py`/`repo_badge_catalog.py` (Extract Module) with zero behavior change, verified by an unchanged existing test suite before the floor logic was added.
+- **Any two PRs that added tests conflicted on six files, by construction — eliminated at the root** (#293). The collected test count was hand-carried as an exact figure in `.bestpractices.json`, `CLAUDE.md`, `CONTRIBUTING.md` (×2), `README.md` (×2) and `docs/ASSURANCE-CASE.md`, each checked for EQUALITY against whichever branch's own live `pytest --collect-only` count ran in CI. That count is a property of the post-merge tree, not of any one branch: two branches that each add tests compute two different, both-true numbers and must each edit the same six lines to match, so the second to merge silently overwrites the first's correct figure with its own now-stale one — measured on this repo as two red `main` runs (PR #280 synced to its own total, #278 added more tests against a stale base) and a PR rebased three times solely to resolve the resulting conflicts. `assets/badge-tests.svg` is now the ONLY artifact stating an absolute count; the five others point at it instead of restating the figure. The badge's own check moves from an exact match to a monotone **floor** (`doc_claim_structural.check_badge_floor`, `generate_repo_badges.stale_tests_badge`): a committed count that lags the live one is stale-but-true and passes, so a PR that only adds tests never touches it, and only an actual OVER-claim — a hand-typed number, or tests removed below what was claimed — fails. A standing regression guard (`test_no_prose_file_states_the_suite_size_any_more`) asserts no scanned file, including `.bestpractices.json`, states this claim in prose again. `check_doc_claims.py` (420 lines) and `generate_repo_badges.py` (305 lines) were both over the repo's 300-line file cap before this change needed to touch them further; split into `doc_claim_sources.py`/`doc_claim_scan.py`/`doc_claim_structural.py`/`repo_badge_catalog.py` (Extract Module) with zero behavior change, verified by an unchanged existing test suite before the floor logic was added.
 
 ### Added
 - **The README's repo-derived badges are now self-hosted SVGs, gated in CI** — `assets/badge-{license,python,tests,references,version}.svg`, `scripts/generate_repo_badges.py`, `scripts/badge_render.py`. Five hotlinked `img.shields.io` images became committed files, for the reason the MCP Toplist badge already was one: a remote badge URL is a third-party request fired on every README view, and it lets its host restate our claim with no commit in this repository. **Only repo-derived figures were converted**, and the line is deliberate — every one of these (licence, Python floor, collected test count, bibliography size, package version) is determined BY THIS REPOSITORY, so a committed copy can always be made true again from the working tree with no network access. That is why they are kept honest by a **blocking `--check` gate on every push and PR** rather than by a cron: drift is caught where it is introduced. **Two badges were deliberately NOT converted and must not be:** the CI status badge reports the LIVE result of the last run on main, so a committed copy would assert "passing" while main was broken — a static build-status badge is a false claim by construction, not merely a stale one — and it is GitHub-hosted, so it is not a third-party beacon in the first place; the OpenSSF Best Practices badge reflects an external body's live assessment that can be downgraded without any commit here, and `.bestpractices.json` separately justifies displaying THEIR badge image. The MCP Toplist badge sits between the two and stays committed because it carries an explicit "as of <month>" stamp, which keeps a stale copy a true statement about a point in time. **The conversion had to rewire the gate it would otherwise have silenced:** `check_doc_claims.py` enforced the version and test-count claims by regex over the shields.io URLs (`badge/version-(\d+\.\d+\.\d+)`, `badge/tests-(\d+)_passing`), so self-hosting alone would have left both patterns matching nothing while the gate still reported success. They now read the figure out of the committed SVG's own `<title>` and **fail closed** on a missing file or an unmatched title — the predecessor's `if badge and ...` passed silently the moment its subject disappeared. A new check also fails any reintroduced `img.shields.io` hotlink in the README, so reverting this is loud rather than quiet. Found by the new tests before shipping: `--` is illegal inside an XML comment, and the first cut described its own gate as `--check` and its source as `pytest --collect-only` in the provenance comment, leaving **all five badges unparseable**; the renderer now parses every badge it produces and refuses to return one that is not well-formed, so no future wording can reintroduce the class. The shared renderer was extracted from the MCP Toplist refresher first, as a separate behavior-preserving commit whose proof is that `assets/badge-mcp-toplist.svg` is byte-identical and its 51 tests pass unchanged. Suite grows 6348 → 6373.
diff --git a/pyproject.toml b/pyproject.toml
index 3ea7e4bf..0da36583 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -523,7 +523,7 @@ only_mutate = ["mcp_server/shared/json_native.py"]
 # without this a scoped run that includes check_doc_claims.py/
 # generate_repo_badges.py fails EVERY mutant on "assets/badge-version.svg:
 # missing" before it can score a single one — reproduced empirically
-# (issue #287) attempting exactly that run.
+# (issue #293) attempting exactly that run.
 also_copy = [
     ".github",
     "tests_py",
diff --git a/scripts/check_doc_claims.py b/scripts/check_doc_claims.py
index 4aed951e..9aa1900a 100644
--- a/scripts/check_doc_claims.py
+++ b/scripts/check_doc_claims.py
@@ -20,7 +20,7 @@
 reference count      entries counted in ``docs/papers/bibliography.md``
 mechanism count      the count declared in that bibliography's header
 version              ``[project].version`` in ``pyproject.toml``
-test count           ``assets/badge-tests.svg`` alone (issue #287) — the
+test count           ``assets/badge-tests.svg`` alone (issue #293) — the
                      one artifact that still states an absolute figure. No
                      prose file (nor ``.bestpractices.json``) states this
                      count any more: a PR that adds tests would otherwise
@@ -54,7 +54,7 @@
 Split across scripts/doc_claim_sources.py (canonical readers),
 scripts/doc_claim_scan.py (claim scanning/comparison) and
 scripts/doc_claim_structural.py (badge + structural-integrity checks) —
-issue #287, Extract Function/Move Function — to stay under the repo's
+issue #293, Extract Function/Move Function — to stay under the repo's
 300-line file cap (CLAUDE.md, Code Style); this module is the thin
 orchestrator each of those forwards through, and the only place ``read``/
 ``SCANNED_FILES`` are defined (tests patch them here; see each sibling
@@ -112,7 +112,7 @@
     r"\s*mechanisms\b"
 )
 # Both the "N tests" and the "N-test suite" phrasings state the count. No
-# scanned file states this claim in prose any more (issue #287 — see the
+# scanned file states this claim in prose any more (issue #293 — see the
 # module docstring's "test count" row); the pattern stays defined because
 # it is still the generic worked example scan_claims/check_counts's own
 # tests exercise, and tests_py/scripts/test_check_doc_claims.py asserts its
@@ -123,6 +123,14 @@
 
 
 def read(relative_path: str) -> str:
+    # encoding="utf-8" is pinned explicitly, never the platform default:
+    # every scanned Markdown file uses non-ASCII prose (em dashes, arrows),
+    # and a locale-dependent default can mis-decode them on a non-UTF-8-
+    # default platform (Windows is in this project's own CI matrix) — see
+    # test_read_pins_utf8. "UTF-8" (verbatim uppercase) is a documented-
+    # equivalent spelling: codecs.lookup is case-insensitive (CPython
+    # Lib/encodings/aliases.py normalizes via .lower()), so it is the SAME
+    # codec, not a different one a wrong-encoding bug could reach.
     return (REPO_ROOT / relative_path).read_text(encoding="utf-8")
 
 
@@ -206,7 +214,7 @@ def collect_failures(test_count: int | None) -> list[str]:
     failures += check_no_conflict_markers()
     failures += check_scanned_json_parses()
     if test_count is not None:
-        # The tests badge is the ONLY test-count claim left (issue #287);
+        # The tests badge is the ONLY test-count claim left (issue #293);
         # see check_badge_floor's docstring for why it is a floor, not an
         # exact match.
         failures += doc_claim_structural.check_badge_floor(
diff --git a/scripts/doc_claim_scan.py b/scripts/doc_claim_scan.py
index 66365408..d1c4d698 100644
--- a/scripts/doc_claim_scan.py
+++ b/scripts/doc_claim_scan.py
@@ -1,6 +1,6 @@
 """Claim-scanning machinery for scripts/check_doc_claims.py.
 
-Extracted (issue #287, Extract Function/Move Function) to keep
+Extracted (issue #293, Extract Function/Move Function) to keep
 check_doc_claims.py under the repo's 300-line file cap. Answers "does a
 scanned file's prose claim (a count, phrased as 'N things') agree with a
 canonical number" and "which lines have declared they are not a claim."
diff --git a/scripts/doc_claim_sources.py b/scripts/doc_claim_sources.py
index cefaed4f..7541163b 100644
--- a/scripts/doc_claim_sources.py
+++ b/scripts/doc_claim_sources.py
@@ -1,6 +1,6 @@
 """Canonical truth-readers for scripts/check_doc_claims.py.
 
-Extracted (issue #287, Extract Function/Move Function) so check_doc_claims.py
+Extracted (issue #293, Extract Function/Move Function) so check_doc_claims.py
 stays under the repo's 300-line file cap (CLAUDE.md, Code Style) — it had
 already crossed it (420 lines) before this change added the floor-check
 machinery check_doc_claims.py needed.
diff --git a/scripts/doc_claim_structural.py b/scripts/doc_claim_structural.py
index da3c2897..cc7b0f1e 100644
--- a/scripts/doc_claim_structural.py
+++ b/scripts/doc_claim_structural.py
@@ -1,6 +1,6 @@
 """Badge and structural-integrity checks for scripts/check_doc_claims.py.
 
-Extracted (issue #287, Extract Function/Move Function) to keep
+Extracted (issue #293, Extract Function/Move Function) to keep
 check_doc_claims.py under the repo's 300-line file cap. Two concerns live
 here because both fail CLOSED on a file the gate cannot read or parse: badge
 freshness (does a committed SVG's own figure agree with the canonical one)
diff --git a/scripts/generate_repo_badges.py b/scripts/generate_repo_badges.py
index e504e7f8..873b2dd1 100644
--- a/scripts/generate_repo_badges.py
+++ b/scripts/generate_repo_badges.py
@@ -60,7 +60,7 @@
 # Only the label/message palette repo_badge_svg() itself renders with, plus
 # _HEALTHY (tests_py/scripts/test_generate_repo_badges.py reads
 # gen._HEALTHY), are re-exported here; _NEUTRAL/_CORPUS are used only by
-# repo_badge_catalog.fixed_badge_specs, which owns them (issue #287 split —
+# repo_badge_catalog.fixed_badge_specs, which owns them (issue #293 split —
 # see that module's docstring for why it returns field dicts, not
 # RepoBadge instances, and never imports this class).
 from repo_badge_catalog import _HEALTHY as _HEALTHY  # noqa: E402  (re-export)
@@ -153,7 +153,7 @@ def build_badges(test_count: int | None) -> list[RepoBadge]:
     The canonical readers are check_doc_claims's own, not reimplementations:
     a badge that disagreed with the gate would be the exact drift this file
     exists to prevent. The field data itself lives in repo_badge_catalog.py
-    (issue #287 split, §4: the 300-line file cap) — this function's own job
+    (issue #293 split, §4: the 300-line file cap) — this function's own job
     is only to resolve the canonical values and construct `RepoBadge`
     instances from the returned specs.
     """
@@ -203,19 +203,23 @@ def stale(badge: RepoBadge) -> str | None:
 
 
 def stale_tests_badge(test_count: int) -> str | None:
-    """A monotone floor, not an exact snapshot (issue #287, §6): two
-    branches adding tests compute two different, both-true live counts for
-    the same post-merge tree, so an exact match is how any two such PRs
+    """A monotone floor, not an exact snapshot (issue #293, §6): two
+    branches adding tests compute different, both-true live counts for the
+    same post-merge tree, so an exact match is how any two such PRs
     conflicted on this file, and how main's gate flapped red on a merge
-    that only grew the count. Lagging behind `test_count` is not reported;
-    only an OVER-claim is. `stale()` still checks everything else exactly.
-    See doc_claim_structural.check_badge_floor for the same invariant.
+    that only grew the count. Lagging is not reported; only an OVER-claim
+    is. `stale()` still checks everything else exactly — see
+    doc_claim_structural.check_badge_floor for the same invariant.
     """
-    badge = RepoBadge(**repo_badge_catalog.tests_badge_spec(test_count))
-    path = repo_badge_path(badge)
+    # Filename is constant regardless of test_count; resolved directly (not
+    # via a throwaway RepoBadge) to remove an inert mutant class outright.
+    path = ASSETS_DIR / repo_badge_catalog.TESTS_BADGE_FILENAME
     target = REPO_ROOT / path
     if not target.exists():
         return f"{path}: missing — run scripts/generate_repo_badges.py"
+    # utf-8 pinned explicitly (provenance comments contain an em dash; see
+    # test_stale_tests_badge_pins_utf8_on_read); "UTF-8" is an equivalent
+    # spelling (codecs.lookup is case-insensitive), not a distinct mutant.
     match = doc_claim_structural.TESTS_BADGE.search(target.read_text(encoding="utf-8"))
     if match is None:
         return f"{path}: no test-count figure in its <title>; diverged from this gate"
@@ -265,9 +269,8 @@ def main(argv: list[str] | None = None) -> int:
         return 2
 
     if args.check:
-        # The tests badge is checked by stale_tests_badge (a monotone floor,
-        # not an exact match — see its docstring); every other badge keeps
-        # the plain, exact-match stale() unchanged.
+        # stale_tests_badge (a floor, not exact — see its docstring) checks
+        # the tests badge; every other badge keeps the plain stale() below.
         failures = [
             reason
             for badge in badges
diff --git a/scripts/repo_badge_catalog.py b/scripts/repo_badge_catalog.py
index 63c1865b..9245b082 100644
--- a/scripts/repo_badge_catalog.py
+++ b/scripts/repo_badge_catalog.py
@@ -1,6 +1,6 @@
 """Badge field specifications for scripts/generate_repo_badges.py.
 
-Extracted (issue #287, Extract Function/Move Function) to keep
+Extracted (issue #293, Extract Function/Move Function) to keep
 generate_repo_badges.py under the repo's 300-line file cap. Returns plain
 field dicts rather than `RepoBadge` instances: `RepoBadge` is a
 `@dataclass`-decorated class whose owning module matters to mutmut (see its
diff --git a/tests_py/scripts/test_check_doc_claims.py b/tests_py/scripts/test_check_doc_claims.py
index 4bc6fd8b..584fc015 100644
--- a/tests_py/scripts/test_check_doc_claims.py
+++ b/tests_py/scripts/test_check_doc_claims.py
@@ -12,18 +12,38 @@
 import importlib.util
 import unittest
 from pathlib import Path
+from unittest import mock
 
 # The module name must be the dotted path mutmut derives from the file's
 # location: it keys its mutant trampolines on "scripts.check_doc_claims.*",
 # and a bare "check_doc_claims" makes every mutant look unreached, so the
 # scoped mutation run stops early instead of scoring the suite.
+_SCRIPTS = Path(__file__).resolve().parents[2] / "scripts"
 _spec = importlib.util.spec_from_file_location(
-    "scripts.check_doc_claims",
-    Path(__file__).resolve().parents[2] / "scripts" / "check_doc_claims.py",
+    "scripts.check_doc_claims", _SCRIPTS / "check_doc_claims.py"
 )
 gate = importlib.util.module_from_spec(_spec)
 _spec.loader.exec_module(gate)
 
+# Loaded again under its OWN dotted name ("scripts.doc_claim_structural"),
+# separately from check_doc_claims.py's internal bare `import
+# doc_claim_structural`: a function's `__module__` is set to whatever name
+# it was defined under, and mutmut's trampoline only activates a mutant
+# when that matches the dotted, path-derived name it generated the mutant
+# under (`mutmut/mutation/trampoline.py`, `module != decorated_func.
+# __module__`). Bare-imported (as check_doc_claims.py's own copy is),
+# every function in this file carries `__module__ == "doc_claim_structural"`
+# — never equal to "scripts.doc_claim_structural.<name>", so every one of
+# its mutants showed "no tests" under a scoped run (issue #293), the exact
+# defect class documented for `badge_render` in test_generate_repo_badges.py
+# and now reproduced (and fixed the same way) for this sibling module.
+# check_badge_floor's own direct tests below call through THIS reference.
+_dcs_spec = importlib.util.spec_from_file_location(
+    "scripts.doc_claim_structural", _SCRIPTS / "doc_claim_structural.py"
+)
+doc_claim_structural = importlib.util.module_from_spec(_dcs_spec)
+_dcs_spec.loader.exec_module(doc_claim_structural)
+
 
 CATALOGUE = (
     "52 standalone tools register unconditionally; 3 more register only when an\n"
@@ -340,7 +360,7 @@ class CollectFailuresTests(unittest.TestCase):
     repository that is deliberately stale, one family at a time.
     """
 
-    # No test-count sentence: issue #287 removed that claim from prose
+    # No test-count sentence: issue #293 removed that claim from prose
     # entirely (only assets/badge-tests.svg — a monotone floor, checked
     # below — still states one), so there is nothing left here for the
     # "tests" family among the other four to disagree on.
@@ -386,7 +406,7 @@ def test_a_consistent_repository_reports_nothing(self):
     def test_each_family_reports_its_own_stale_claim(self):
         """One stale number per family, checked by the message it produces.
 
-        "tests" is not one of these families any more (issue #287): it has
+        "tests" is not one of these families any more (issue #293): it has
         no prose claim to go stale in DOC.md. Its own family is exercised
         below, against the badge, which is the one place left that states
         a number.
@@ -413,7 +433,7 @@ def test_an_over_claiming_test_badge_is_reported(self):
         )
 
     def test_an_under_claiming_test_badge_is_not_reported(self):
-        """The floor invariant this whole family exists for (issue #287):
+        """The floor invariant this whole family exists for (issue #293):
         a badge that lags behind the live count is stale, not false, so a
         PR that only adds tests never has to touch it to stay green — this
         is what makes two such PRs stop conflicting on it.
@@ -468,6 +488,76 @@ def test_without_a_live_count_the_test_badge_is_not_checked(self):
         self.assertEqual(gate.collect_failures(test_count=None), [])
 
 
+class CheckBadgeFloorDirectTests(unittest.TestCase):
+    """Direct tests of doc_claim_structural.check_badge_floor.
+
+    CollectFailuresTests exercises it only through gate.collect_failures's
+    bare-imported copy — real behavioural coverage, but NOT mutation
+    coverage: mutmut's trampoline only activates a mutant when the calling
+    module name matches (see the dotted-load comment above), so these call
+    through the dotted `doc_claim_structural` reference instead.
+    """
+
+    PATTERN = doc_claim_structural.TESTS_BADGE
+
+    def test_missing_file_fails_closed(self):
+        read_fn = _FakeRepo().read
+        failures = doc_claim_structural.check_badge_floor(
+            "assets/badge-tests.svg", self.PATTERN, 10, "tests", read_fn
+        )
+        self.assertEqual(len(failures), 1)
+        self.assertIn("missing", failures[0])
+
+    def test_no_title_match_fails_closed(self):
+        read_fn = _FakeRepo(**{"assets/badge-tests.svg": "<svg></svg>"}).read
+        failures = doc_claim_structural.check_badge_floor(
+            "assets/badge-tests.svg", self.PATTERN, 10, "tests", read_fn
+        )
+        # Exact match, not just assertIn on the prefix: mutation testing
+        # found a mutant that only altered the trailing "this gate have
+        # diverged" clause and survived a prefix-only assertion (issue #293).
+        self.assertEqual(
+            failures,
+            [
+                "assets/badge-tests.svg: no tests figure in its <title>;"
+                " the badge and this gate have diverged"
+            ],
+        )
+
+    def test_an_over_claim_is_reported(self):
+        read_fn = _FakeRepo(
+            **{"assets/badge-tests.svg": "<title>11 tests passing</title>"}
+        ).read
+        failures = doc_claim_structural.check_badge_floor(
+            "assets/badge-tests.svg", self.PATTERN, 10, "tests", read_fn
+        )
+        self.assertEqual(len(failures), 1)
+        self.assertIn("11", failures[0])
+        self.assertIn("exceeds", failures[0])
+
+    def test_an_under_claim_is_not_reported(self):
+        read_fn = _FakeRepo(
+            **{"assets/badge-tests.svg": "<title>9 tests passing</title>"}
+        ).read
+        self.assertEqual(
+            doc_claim_structural.check_badge_floor(
+                "assets/badge-tests.svg", self.PATTERN, 10, "tests", read_fn
+            ),
+            [],
+        )
+
+    def test_an_exact_match_is_not_reported(self):
+        read_fn = _FakeRepo(
+            **{"assets/badge-tests.svg": "<title>10 tests passing</title>"}
+        ).read
+        self.assertEqual(
+            doc_claim_structural.check_badge_floor(
+                "assets/badge-tests.svg", self.PATTERN, 10, "tests", read_fn
+            ),
+            [],
+        )
+
+
 class RepositoryTests(unittest.TestCase):
     """The gate must pass on the tree it ships with — this is the gate itself."""
 
@@ -494,7 +584,7 @@ def test_the_declared_exemptions_are_the_reviewed_set(self):
         )
 
     def test_no_prose_file_states_the_suite_size_any_more(self):
-        """The regression guard for issue #287's root-cause fix.
+        """The regression guard for issue #293's root-cause fix.
 
         Before: six files hand-carried the same exact test count, and any
         two PRs that each added tests conflicted on all of them by
@@ -513,6 +603,17 @@ def test_no_prose_file_states_the_suite_size_any_more(self):
         """
         self.assertEqual(gate.scan_claims(gate.TEST_CLAIM, "tests"), [])
 
+    def test_read_pins_utf8(self):
+        """A locale-dependent default would misread the em dashes and
+        arrows every scanned Markdown file's prose carries (mutation-testing
+        found this — a mutant dropping encoding="utf-8" survived every
+        other assertion, issue #293)."""
+        with mock.patch.object(
+            Path, "read_text", autospec=True, side_effect=Path.read_text
+        ) as read_spy:
+            gate.read("README.md")
+        self.assertEqual(read_spy.call_args.kwargs.get("encoding"), "utf-8")
+
 
 class StructuralIntegrityTests(unittest.TestCase):
     """The scanned files must still say ONE thing, and JSON must still parse.
diff --git a/tests_py/scripts/test_generate_repo_badges.py b/tests_py/scripts/test_generate_repo_badges.py
index 985426e4..f329713b 100644
--- a/tests_py/scripts/test_generate_repo_badges.py
+++ b/tests_py/scripts/test_generate_repo_badges.py
@@ -311,7 +311,7 @@ def test_an_unreadable_canonical_source_exits_two_not_one(self):
         self.assertEqual(gen.main(["--check", "--test-count", "42"]), 2)
 
     def test_an_under_claiming_tests_badge_passes_check(self):
-        """The floor invariant (issue #287): a badge committed for a lower,
+        """The floor invariant (issue #293): a badge committed for a lower,
         earlier count stays green once the live count only grows — the
         property that lets a PR add tests without touching this file."""
         gen.main(["--test-count", "42"])
@@ -326,7 +326,7 @@ class StaleTestsBadgeTests(_CanonicalSourceTestCase):
     """Direct tests of stale_tests_badge — the floor check itself.
 
     CheckModeTests exercises it only through main(); these pin every one of
-    its branches for mutation coverage (issue #287).
+    its branches for mutation coverage (issue #293).
     """
 
     def setUp(self):
@@ -372,6 +372,24 @@ def test_structural_drift_still_fails_even_at_a_valid_floor(self):
         target.write_text(target.read_text().replace("tests", "TESTS", 1))
         self.assertIsNotNone(gen.stale_tests_badge(42))
 
+    def test_stale_tests_badge_pins_utf8_on_read(self):
+        """A locale-dependent default would misread the em dash every
+        committed badge's provenance comment carries (mutation-testing
+        found this — a mutant dropping encoding="utf-8" here survived
+        every other assertion, issue #293). Checks EVERY read_text call,
+        not just the last: an exact match falls through to stale()'s own
+        (separate, unmutated) read_text call, which would otherwise mask
+        a dropped encoding in stale_tests_badge's own call — mutation
+        testing caught that gap too."""
+        self._commit(42)
+        with mock.patch.object(
+            Path, "read_text", autospec=True, side_effect=Path.read_text
+        ) as read_spy:
+            gen.stale_tests_badge(42)
+        self.assertTrue(read_spy.call_args_list)
+        for call in read_spy.call_args_list:
+            self.assertEqual(call.kwargs.get("encoding"), "utf-8")
+
 
 class WriteAndStaleTests(unittest.TestCase):
     """Direct tests of write()/stale() — the file I/O this gate performs.