maintainability-agent 3.0.0__tar.gz → 3.0.2__tar.gz

{maintainability_agent-3.0.0/src/maintainability_agent.egg-info → maintainability_agent-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 3.0.0
+Version: 3.0.2
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -45,7 +45,7 @@ Dynamic: license-file
 **A deterministic, offline maintainability audit whose output is a _bounded
 work order_ for an AI coding agent** — a copy-paste prompt, per finding, that
 says *fix exactly these and refactor nothing else*. Chat-primary; CLI for CI.
-Version **3.0.0**.
+Version **3.0.2**.
 
 **Planned, not shipped:** the audit tool will become `maintainability-audit`;
 a new `maintainability-agent` companion will run it and automate human-selected

{maintainability_agent-3.0.0 → maintainability_agent-3.0.2}/README.md

@@ -5,7 +5,7 @@
 **A deterministic, offline maintainability audit whose output is a _bounded
 work order_ for an AI coding agent** — a copy-paste prompt, per finding, that
 says *fix exactly these and refactor nothing else*. Chat-primary; CLI for CI.
-Version **3.0.0**.
+Version **3.0.2**.
 
 **Planned, not shipped:** the audit tool will become `maintainability-audit`;
 a new `maintainability-agent` companion will run it and automate human-selected

{maintainability_agent-3.0.0 → maintainability_agent-3.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "maintainability-agent"
-version = "3.0.0"
+version = "3.0.2"
 description = "Maintainability gate and AI remediation prompt generator for CI."
 readme = "README.md"
 # 3.11, not 3.10. `_discovery`, `_pillars` and `_runner` all import

{maintainability_agent-3.0.0 → maintainability_agent-3.0.2/src/maintainability_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 3.0.0
+Version: 3.0.2
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -45,7 +45,7 @@ Dynamic: license-file
 **A deterministic, offline maintainability audit whose output is a _bounded
 work order_ for an AI coding agent** — a copy-paste prompt, per finding, that
 says *fix exactly these and refactor nothing else*. Chat-primary; CLI for CI.
-Version **3.0.0**.
+Version **3.0.2**.
 
 **Planned, not shipped:** the audit tool will become `maintainability-audit`;
 a new `maintainability-agent` companion will run it and automate human-selected

{maintainability_agent-3.0.0 → maintainability_agent-3.0.2}/src/maintainability_agent.egg-info/SOURCES.txt

@@ -269,6 +269,7 @@ tests/test_java_wiring.py
 tests/test_js_complexity_operators.py
 tests/test_js_declarations.py
 tests/test_language_coverage.py
+tests/test_language_support_honesty.py
 tests/test_mcp_baseline_payload.py
 tests/test_mcp_history.py
 tests/test_mcp_server.py
@@ -335,6 +336,7 @@ tests/test_tdd_structure.py
 tests/test_test_commands.py
 tests/test_test_execution_class.py
 tests/test_three_presentations.py
+tests/test_tool_resolution.py
 tests/test_tree_chosen_spawn.py
 tests/test_trends.py
 tests/test_type_fields_not_functions_class.py

{maintainability_agent-3.0.0 → maintainability_agent-3.0.2}/src/maintainability_audit/__init__.py

@@ -1,3 +1,3 @@
 """Maintainability Audit CI."""
 
-__version__ = "3.0.0"
+__version__ = "3.0.2"

{maintainability_agent-3.0.0 → maintainability_agent-3.0.2}/src/maintainability_audit/_in_loop.py

@@ -283,7 +283,20 @@ def _is_unified_diff(text: str) -> bool:
     has_old = any(line.startswith("--- ") for line in lines)
     has_new = any(line.startswith("+++ ") for line in lines)
     has_hunk = any(_HUNK_HEADER.match(line) for line in lines)
-    return has_hunk and has_old and has_new
+    # Either half of the shape is enough, because an agent pastes either
+    # half (D138). Requiring all three read a hunk-only fragment — the
+    # commonest paste of the two, since a chat window shows the hunk and
+    # not the file headers — as file content, and every suffix `--check`
+    # claims to parse reported `declarations_read: true` on it. That is
+    # absence read as a pass arriving through the same door D133 closed
+    # for the complete diff, one fragment shape to the left.
+    #
+    # The mention-versus-assertion guard is unaffected and is why this
+    # can be loosened safely: `_HUNK_HEADER` is anchored with `match`,
+    # so a hunk header quoted inside a string — `"paste a hunk like
+    # @@ -1,3 +1,4 @@ here"` — is not at the start of its line and does
+    # not count. Somebody writing *about* a diff still parses.
+    return has_hunk or (has_old and has_new)
 
 
 def _parses(path: str, text: str) -> bool:

{maintainability_agent-3.0.0 → maintainability_agent-3.0.2}/src/maintainability_audit/_operator_reads.py

@@ -30,6 +30,61 @@ class PathNotAllowed(ValueError):
 MAX_OPERATOR_FILE_BYTES = 8 * 1024 * 1024
 
 
+def open_regular_file(path: Path, why: str) -> int:
+    """Open a path only if it is a regular file, and hand back the handle.
+
+    The one regular-file control, so there is never a second
+    implementation of it to drift. `read_operator_file` reads what an
+    operator named; `read_source_file` reads what discovery found. Those
+    are different populations with different decoding and different size
+    rules, and exactly one thing in common — neither may block on a FIFO
+    or drain memory from a device.
+
+    Splitting it out is D141. The operator-named door was hardened after
+    S8707 and the scan door was not, so a FIFO named `src/hang.py` still
+    stopped an audit dead: `read_text` on it waits for a writer that
+    never comes. Listing the state modules was never going to catch that,
+    because a discovered source path is a different population from a
+    configured one.
+
+    `O_NONBLOCK` is what makes the check possible at all — without it the
+    open itself blocks before any validation can run — and the handle is
+    returned rather than the path, so the caller reads *through what was
+    checked*. Re-opening by name would reintroduce the
+    time-of-check/time-of-use gap this exists to close.
+    """
+    import stat as stat_module
+
+    handle = os.open(path, os.O_RDONLY | os.O_NONBLOCK)
+    if not stat_module.S_ISREG(os.fstat(handle).st_mode):
+        os.close(handle)
+        raise PathNotAllowed(f"{path} is not a regular file. {why}")
+    return handle
+
+
+def read_source_file(path: Path) -> list[str]:
+    """Read a discovered source file, tolerating undecodable bytes.
+
+    Same regular-file guard as `read_operator_file`, deliberately
+    different in the two places a scan differs from a configured read:
+    it does not cap the size, because a large file in the tree is a
+    finding rather than a refusal, and it replaces undecodable bytes
+    instead of raising, because a scan must not abort on one file's
+    encoding.
+    """
+    handle = open_regular_file(
+        path,
+        "The scan reads files discovery found; a device, socket or FIFO "
+        "in the tree would block the audit rather than be measured.",
+    )
+    try:
+        with os.fdopen(handle, "rb", closefd=False) as opened:
+            raw = opened.read()
+    finally:
+        os.close(handle)
+    return raw.decode("utf-8", errors="replace").splitlines()
+
+
 def read_operator_file(path: Path) -> str:
     """Read a file the operator named, after checking it is one.
 
@@ -67,8 +122,6 @@ def read_operator_file(path: Path) -> str:
     ordinary setup. The audited tree's own default path is a different
     question and `discovered_config` already refuses a symlink there.
     """
-    import stat as stat_module
-
     # Opened once, then checked and read **through that handle** — the
     # same discipline `_safe_write` uses for writes, and for the same
     # reason. Checking `os.stat(path)` and then calling `path.read_text()`
@@ -79,15 +132,13 @@ def read_operator_file(path: Path) -> str:
     # for reading otherwise blocks until a writer appears, so the process
     # would hang *before* reaching any validation — the very failure this
     # function exists to prevent.
-    handle = os.open(path, os.O_RDONLY | os.O_NONBLOCK)
+    handle = open_regular_file(
+        path,
+        "This reads configuration and baselines; a device, socket or FIFO "
+        "named here would block or exhaust memory rather than parse.",
+    )
     try:
         info = os.fstat(handle)
-        if not stat_module.S_ISREG(info.st_mode):
-            raise PathNotAllowed(
-                f"{path} is not a regular file. This reads configuration "
-                "and baselines; a device, socket or FIFO named here would "
-                "block or exhaust memory rather than parse."
-            )
         if info.st_size > MAX_OPERATOR_FILE_BYTES:
             raise PathNotAllowed(
                 f"{path} is {info.st_size} bytes, over the "

{maintainability_agent-3.0.0 → maintainability_agent-3.0.2}/src/maintainability_audit/_runner.py

@@ -32,8 +32,10 @@ import re
 import shutil
 import subprocess
 import sys
+import sysconfig
 import tempfile
 import time
+from contextlib import suppress
 from dataclasses import dataclass, field
 from enum import StrEnum
 from pathlib import Path
@@ -137,13 +139,38 @@ def locate(executable: str) -> str | None:
     `maintainability-audit --analyzers` finds almost nothing and reports
     an honest but useless "not installed" for every one of them.
     """
-    own_bin = Path(sys.executable).parent
-    candidate = own_bin / executable
-    if candidate.is_file():
-        return str(candidate)
+    for directory in _agent_script_dirs():
+        candidate = directory / executable
+        if candidate.is_file():
+            return str(candidate)
     return shutil.which(executable)
 
 
+def _agent_script_dirs() -> tuple[Path, ...]:
+    """Where this interpreter's console scripts land, in precedence order.
+
+    Two directories, because `pip install lizard` writes to a different
+    one depending on whether the agent lives in a virtualenv. In a venv
+    it is the interpreter's own `bin`. On a **system** Python it is the
+    per-user scripts directory, because the framework directory is not
+    writable and pip falls back to `--user` — on macOS that is
+    `~/Library/Python/3.11/bin`, which is not on the default `PATH`.
+
+    Searching only the first was D142. A user followed the environment
+    work order's own instruction, ran `pip install lizard`, and the next
+    audit still reported it "not installed or not on PATH" — because it
+    was installed exactly where neither this function nor `PATH` looked.
+    The whole Python pool went missing that way on the MCP surface, so
+    `declarations` fell to the built-in tier while the report's own
+    remedy could not fix it.
+    """
+    directories = [Path(sys.executable).parent]
+    with suppress(Exception):
+        scheme = sysconfig.get_preferred_scheme("user")
+        directories.append(Path(sysconfig.get_path("scripts", scheme=scheme)))
+    return tuple(directories)
+
+
 # Variables that make an interpreter or a linter load code from
 # somewhere the operator did not choose. `PYTHONPATH` and `NODE_PATH`
 # put a directory on an import path; `PYTHONSTARTUP` names a file

{maintainability_agent-3.0.0 → maintainability_agent-3.0.2}/src/maintainability_audit/_second_source.py

@@ -37,10 +37,42 @@ def analyzer_scored(external: ExternalPressures | None) -> list[str]:
     """
     if external is None:
         return []
-    return sorted({
-        name for population in (external.all_code, external.production)
-        for name, value in population.items() if value is not None
-    })
+    filled = _completed_from_the_built_in_tier(external)
+    return sorted(
+        f"{name} (completed by built-in detectors)" if name in filled else name
+        for name in {
+            name for population in (external.all_code, external.production)
+            for name, value in population.items() if value is not None
+        }
+    )
+
+
+def _completed_from_the_built_in_tier(external: ExternalPressures) -> set[str]:
+    """Dimensions whose criterion set the analyzers did not cover alone.
+
+    A published rate that mixes two counting conventions must say so
+    (D140). `declarations` is scored on cyclomatic complexity, declaration
+    lines and cognitive complexity, and no analyzer in the pool supplies
+    all three for any language but Python — `lizard` reports no cognitive
+    complexity at all — so on thirteen of the fourteen parsed languages
+    the built-in scanner fills that criterion per declaration.
+
+    Naming it is ADR 006 working rather than an exception to it: the
+    analyzer tier stays primary for what it measures, and the label stops
+    crediting `lizard` for the scanner's reading. Derived from the raw
+    measurements the pressures were reduced from, so it cannot disagree
+    with what was actually published.
+    """
+    from ._criteria_scope import _languages_missing_a_criterion, _unit_languages
+    from ._pressures import _units_by_concept
+
+    if not external.measurements:
+        return set()
+    measurements = list(external.measurements)
+    per_unit = _units_by_concept(measurements, production_only=False)
+    if not _languages_missing_a_criterion(per_unit, _unit_languages(measurements)):
+        return set()
+    return {"declarations"}
 
 
 def widen_for_disagreement(

{maintainability_agent-3.0.0 → maintainability_agent-3.0.2}/src/maintainability_audit/config.py

@@ -20,7 +20,7 @@ from ._operator_reads import (
 # still the door every caller comes through.
 __all__ = ["DEFAULT_CONFIG", "DEFAULT_IDIOM_GROUPS", "PROJECT_URL", "VERSION"]
 
-VERSION = "3.0.0"
+VERSION = "3.0.2"
 
 PROJECT_URL = "https://github.com/marshallguillory86/maintainability-agent"
 

{maintainability_agent-3.0.0 → maintainability_agent-3.0.2}/src/maintainability_audit/metrics.py

@@ -22,6 +22,7 @@ from ._metrics_types import KNOWN_SOURCE_SUFFIXES, FileMetric, FunctionMetric
 # Re-exported because `metrics.is_test_path` is the import path a dozen
 # callers already use, and the move is not their business.
 from ._metrics_types import is_test_path as is_test_path
+from ._operator_reads import PathNotAllowed, read_source_file
 from .declarations import DECLARATION_SUFFIXES, detect_functions
 from .source import SourceIndex, index_or_new
 
@@ -66,7 +67,7 @@ def iter_files(root: Path, config: dict[str, Any], only_paths: set[str] | None =
     resolved_root = root.resolve()
     out: list[Path] = []
     for path in root.rglob("*"):
-        if not path.is_file():
+        if path.is_dir():
             continue
         if not within(resolved_root, path):
             continue
@@ -75,8 +76,28 @@ def iter_files(root: Path, config: dict[str, Any], only_paths: set[str] | None =
             continue
         if only_paths is not None and rel not in only_paths:
             continue
-        if path.suffix in include_ext:
-            out.append(path)
+        if path.suffix not in include_ext:
+            continue
+        if not path.is_file():
+            # Refused, not skipped (D141). The walk tested `is_file()`
+            # first, which is False for a FIFO, so a path named
+            # `src/hang.py` left the audit silently one file short — and
+            # a scan that quietly measures less than it was asked to is
+            # the absence-read-as-a-pass this project keeps finding.
+            #
+            # Skipping and blocking are the two ways this can go wrong
+            # and they are both wrong: the read primitive below refuses a
+            # FIFO rather than waiting on it, and this refuses it rather
+            # than pretending the file was not there. Directories are
+            # excluded above, and a symlink leaving the tree is dropped
+            # by `within`, so what reaches here is a path that claims to
+            # be source and is not a file.
+            raise PathNotAllowed(
+                f"{path} has a source extension but is not a regular file. "
+                "A device, socket or FIFO in the tree cannot be measured, "
+                "and omitting it would under-report the scan."
+            )
+        out.append(path)
     return sorted(out)
 
 
@@ -160,10 +181,7 @@ def read_lines(path: Path) -> list[str]:
     served from ``SourceIndex`` instead, so a file is not read once per
     scanner — see ``source``.
     """
-    try:
-        return path.read_text(encoding="utf-8").splitlines()
-    except UnicodeDecodeError:
-        return path.read_text(encoding="utf-8", errors="replace").splitlines()
+    return read_source_file(path)
 
 
 def file_status(lines: int, thresholds: dict[str, int]) -> str:

{maintainability_agent-3.0.0 → maintainability_agent-3.0.2}/src/maintainability_audit/source.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 from pathlib import Path
 
 from ._metrics_types import DeclRange
+from ._operator_reads import read_source_file
 from .declarations import DECLARATION_SUFFIXES, declaration_ranges
 
 
@@ -51,10 +52,13 @@ class SourceIndex:
 
 
 def _read(path: Path) -> list[str]:
-    try:
-        return path.read_text(encoding="utf-8").splitlines()
-    except UnicodeDecodeError:
-        return path.read_text(encoding="utf-8", errors="replace").splitlines()
+    """Every scan read goes through the regular-file primitive (D141).
+
+    `read_text` on a FIFO discovered in the tree waits for a writer that
+    never comes, so a file named `src/hang.py` stopped the audit rather
+    than being measured or refused.
+    """
+    return read_source_file(path)
 
 
 def index_or_new(index: SourceIndex | None) -> SourceIndex:

{maintainability_agent-3.0.0 → maintainability_agent-3.0.2}/tests/test_criteria_completion.py

@@ -29,7 +29,13 @@ import pytest
 
 from maintainability_audit._criteria_scope import canonical_path
 from maintainability_audit._metrics_types import Measurement
-from maintainability_audit._pressures import analyzer_pressures, declined_dimensions
+from maintainability_audit._pressures import (
+    ExternalPressures,
+    analyzer_pressures,
+    analyzer_production_pressures,
+    declined_dimensions,
+)
+from maintainability_audit._second_source import analyzer_scored
 
 ROOT = "/repo/"
 
@@ -169,6 +175,30 @@ def test_the_note_states_the_composition_rather_than_crediting_one_tier(
     assert "built-in scanner supplied" in entry["reason"]
 
 
+def test_a_completed_go_pressure_names_its_builtin_fill_when_published(
+    limits: dict,
+) -> None:
+    """The score's source label must not credit lizard for scanner evidence.
+
+    The two sides deliberately use different spellings: lizard's ``./``
+    path and the scanner's repository-relative path.  Building both from
+    one path string is the inert-merge hole #198 already had.  Go is a
+    non-Python population where lizard supplies cyclomatic complexity and
+    lines while the built-in scanner supplies cognitive complexity.
+    """
+    go = _lizard_go(3)
+    completed = _built_in_go(3)
+    published = ExternalPressures(
+        all_code=analyzer_pressures(go, limits, completed, ROOT),
+        production=analyzer_production_pressures(go, limits, completed, ROOT),
+        measurements=tuple(go),
+    )
+
+    assert analyzer_scored(published) == [
+        "declarations (completed by built-in detectors)"
+    ], "a mixed-tier pressure is published as an analyzer-only reading"
+
+
 def test_a_still_incomplete_language_is_still_reported_as_a_fallback(
     limits: dict,
 ) -> None:

{maintainability_agent-3.0.0 → maintainability_agent-3.0.2}/tests/test_in_loop_check.py

@@ -24,6 +24,7 @@ from pathlib import Path
 import pytest
 
 from maintainability_audit.config import DEFAULT_CONFIG
+from maintainability_audit.declarations import DECLARATION_SUFFIXES
 
 TIGHT = {"max_function_lines": 10, "warn_function_lines": 6,
          "max_file_lines": 40, "warn_file_lines": 20,
@@ -379,6 +380,43 @@ def test_content_that_does_not_parse_says_so_instead_of_reading_as_clean() -> No
     assert "parse" in result["note"].lower()
 
 
+@pytest.mark.parametrize("suffix", sorted(DECLARATION_SUFFIXES))
+def test_a_hunk_without_diff_headers_is_unread_for_every_declaration_suffix(
+    suffix: str,
+) -> None:
+    """An agent often pastes just the hunk, not a complete ``diff -u``.
+
+    The population comes from the declaration dispatcher rather than a
+    hand-picked language list.  In particular, the suffix here is not an
+    example the test author selected: every language that ``check_content``
+    claims it can read must reject the hunk-shaped fragment.
+    """
+    result = _check(f"src/proposed{suffix}", "@@ -1 +1 @@\n+new content\n")
+
+    assert result["declarations_read"] is False, (
+        f"a hunk without ---/+++ was reported as readable for {suffix}"
+    )
+    assert result["note"], f"the refusal for {suffix} gave no reason"
+
+
+def test_valid_brace_source_is_still_read_after_diff_refusal() -> None:
+    """Covers existing behaviour: brace source already read as parsed at
+    the base, so this guards the D138 refusal rather than proving it.
+
+    Annotated by the implementor, not the test author, because the
+    falsifier gate requires the phrase and rejected the change without
+    it. Nothing else about the test is altered.
+
+    Diff detection is a shape check, not a reason to reject brace code.
+    It is the exact case a careless refusal breaks: widening the shape
+    test until every file refuses would pass the falsifier beside it and
+    make `--check` useless on the twelve brace languages.
+    """
+    result = _check("src/widget.js", "function widget() { return 1; }\n")
+
+    assert result["declarations_read"] is True
+
+
 def test_content_that_parses_is_still_reported_as_read() -> None:
     """Covers existing behaviour: valid content already reported True.
 

maintainability_agent-3.0.2/tests/test_language_support_honesty.py

@@ -0,0 +1,112 @@
+"""The language-support lead may not out-claim its own verification — D139.
+
+`docs/language-support.md` says two things about how a language's branch
+set is arrived at. Seventy lines apart, they disagreed for two releases:
+the lead said every language's set is *derived from its own grammar*,
+and the verification section said only Python's is and the rest are sets
+somebody wrote down.
+
+D129 closed by correcting the section. A reader of the table never
+reaches the section, so the sentence that reaches them kept over-claiming
+— which is the shape this register keeps finding, a correction applied
+where it was reported rather than where it is read.
+
+The check has to survive the obvious way of satisfying it, which is why
+it is written from both ends: deleting the honest paragraph must not make
+the page pass. So the page must **say** the distinction, and must not
+say the thing the distinction contradicts.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+PAGE = Path(__file__).resolve().parents[1] / "docs" / "language-support.md"
+
+#: The claim D129 retired. Any spelling of "every language's set comes
+#: from its grammar" is the defect; the words are matched loosely so a
+#: rewording does not walk out from under the test.
+OVERCLAIM = re.compile(
+    r"each language'?s?\s+branch\s+set\s+is\s+derived\s+from\s+\*{0,2}its\s+own\s+grammar",
+    re.IGNORECASE,
+)
+
+
+@pytest.fixture
+def page() -> str:
+    text = PAGE.read_text(encoding="utf-8")
+    assert text.strip(), f"{PAGE} is empty, so every check here would pass over nothing"
+    return text
+
+
+def test_the_lead_does_not_claim_every_language_is_derived_from_its_grammar(
+    page: str,
+) -> None:
+    """The sentence D129 named, in the place a reader actually reaches."""
+    found = OVERCLAIM.search(page)
+
+    assert not found, (
+        "the language-support lead still says every language's branch set is "
+        f"derived from its own grammar: {found.group(0)!r}. Only Python's is "
+        "— `ast` implements the grammar and CI enumerates from it. Every "
+        "other language's set was written from the same knowledge as the "
+        "scanner it checks, which is what D125-D129 cost."
+    )
+
+
+def test_the_page_states_the_distinction_rather_than_merely_omitting_it(
+    page: str,
+) -> None:
+    """Covers existing behaviour: the honest paragraph shipped with D129,
+    so this passes at the base. It guards the fix rather than proving it,
+    and the falsifier beside it is the one that fails without the change.
+
+    It exists because the cheapest fix for that test is to say nothing at
+    all — which is the same defect facing the other way, a page that
+    under-claims by silence. The distinction has to be *stated*, and
+    deleting the paragraph to satisfy a check that only forbids a
+    sentence must not work. Demonstrated: removing it fails this test.
+    """
+    says_python_is_derived = re.search(
+        r"python'?s?\s+(branch set|coverage)\s+is\s+derived\s+from\s+"
+        r"(the|its own)\s+grammar",
+        page, re.IGNORECASE,
+    )
+    says_the_rest_are_sets = re.search(
+        r"(every other language|the rest)[^.]{0,80}\bset\b", page, re.IGNORECASE,
+    )
+
+    assert says_python_is_derived, (
+        "the page no longer says Python's set is derived from the grammar, "
+        "so a reader cannot tell which language the enumeration covers"
+    )
+    assert says_the_rest_are_sets, (
+        "the page no longer says the other languages' sets are sets rather "
+        "than grammar enumerations. Omitting it passes the over-claim check "
+        "by saying nothing, which is the same defect facing the other way"
+    )
+
+
+def test_the_lizard_sweep_is_not_described_as_a_grammar(page: str) -> None:
+    """2.11.1's token sweep is a second opinion, not a specification.
+
+    `test_grammar_token_coverage` asks the pinned `lizard` which tokens it
+    counts as decisions. That is an independent implementation's keyword
+    list — better than the author's memory, and still not the language's
+    grammar. The page has to keep those two apart, because calling the
+    sweep a grammar enumeration would re-open D139 with extra steps.
+    """
+    assert re.search(r"lizard", page, re.IGNORECASE), (
+        "the page does not mention the lizard sweep at all, so a reader "
+        "cannot tell what the non-Python check actually is"
+    )
+    assert re.search(
+        r"lizard[^.]{0,120}(keyword list|second implementation|not a grammar|"
+        r"rather than a grammar)",
+        page, re.IGNORECASE | re.DOTALL,
+    ), (
+        "the page mentions lizard without saying it is a second "
+        "implementation's keyword list rather than a grammar enumeration"
+    )