ci: gate the stated RomM minimum against the enforced one (#1568)

The README badge, the requirements list and the trap note in `CLAUDE.md`
each restate the minimum RomM version. The number that actually matters
is `Plugin._MIN_REQUIRED_VERSION` in `main.py` — the floor
`test_connection()` rejects servers against, below which the plugin is
inert. Three restatements are three chances to forget one, and a badge
promising a version the code does not enforce is worse than no badge.

## How

`scripts/check_romm_min_version.py` reads the constant out of `main.py`
with `ast` rather than importing it, which would need Decky's runtime
present, and compares it against each claim. `--fix` rewrites them. It
runs in the `lint` job and in `mise run gate`, and it is listed in the
invariant register.

Bumping the floor stays a one-line change to `main.py`; CI enforces the
rest.

## Why not a live badge

Shields cannot read Python, so a genuinely dynamic badge would mean
moving the floor into a machine-readable file. The obvious candidate is
`package.json`, which is already read at runtime — but by an adapter
that falls back to a default when the file is missing or malformed. That
fallback is right for a version string and wrong for a gate: it would
either lock everyone out or let old servers through.

The value only ever changes by editing this repository, so a live fetch
adds an external dependency and a failure mode without removing any
drift the gate does not already catch.

## Scope

ADRs are excluded. They record the floor as it stood when each decision
was taken, and rewriting them would falsify the record.

Verified by temporarily setting the constant to `5.1.2`: all three sites
were reported, `--fix` corrected them, and the check went green.

docs: N/A — tooling only; the invariant register in `CLAUDE.md` gains
the new gate's entry.

Author: danielcopper

.github/workflows/ci.yml

@@ -163,6 +163,9 @@ jobs:
 
       - name: Check local markdown links resolve (file + anchor)
         run: python scripts/check_markdown_links.py
+
+      - name: Check stated RomM minimum matches the enforced one
+        run: python scripts/check_romm_min_version.py
       # The compiled gavel core ships in the plugin zip and has no source in
       # this repo — a silently swapped binary must fail CI. Verify the vendored
       # .so against its checksum (bumped only by a deliberate native/README.md

CLAUDE.md

@@ -147,6 +147,8 @@ Format: **invariant** — tier — enforced by.
   `scripts/check_lock_sync.py`
 - **Every local markdown link in tracked docs resolves (file target + heading/attr-list anchor)** — check —
   `scripts/check_markdown_links.py`
+- **Every stated RomM minimum version matches the enforced `Plugin._MIN_REQUIRED_VERSION`** — check —
+  `scripts/check_romm_min_version.py` (ADRs excluded: frozen history)
 - **Server-supplied path components pass `safe_join` (`lib/path_safety.py`)** — test + prompt-only — traversal tests per
   path builder; new call sites are prompt-only
 - **No sentinel objects on the wire — explicit JSON-representable tagged values only** — prompt-only — mechanize with

mise.toml

@@ -61,6 +61,7 @@ run = [
     "python scripts/check_sync_lifecycle_owner.py",
     "python scripts/check_lock_sync.py",
     "python scripts/check_markdown_links.py",
+    "python scripts/check_romm_min_version.py",
     "cd py_modules/native && sha256sum -c libgavel-x86_64-linux.so.sha256",
     "cd defaults && sha256sum -c bios_registry.json.sha256",
 ]

scripts/check_romm_min_version.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""Keep every stated RomM minimum version equal to the one the plugin enforces.
+
+``Plugin._MIN_REQUIRED_VERSION`` in ``main.py`` is the single source of truth:
+it is the floor ``test_connection()`` rejects servers against, so the plugin is
+inert below it. Several places restate that number for humans — a badge, the
+requirements list, the trap note in CLAUDE.md — and a restated number drifts.
+
+The constant is read with ``ast`` rather than by importing ``main``, which would
+need Decky's runtime present.
+
+Frozen history is deliberately out of scope: ADRs record the floor as it stood
+when the decision was taken and must not be rewritten.
+
+Usage:
+    python scripts/check_romm_min_version.py            # report drift, exit 1
+    python scripts/check_romm_min_version.py --fix      # rewrite the claims
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import pathlib
+import re
+import sys
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+SOURCE = ROOT / "main.py"
+CONSTANT = "_MIN_REQUIRED_VERSION"
+
+# Each claim site: file, a regex with the version as group 1, and a label.
+# The regexes are deliberately narrow — a loose one would rewrite unrelated
+# version numbers.
+CLAIMS = [
+    (
+        "README.md",
+        re.compile(r"(?<=badge/RomM-%E2%89%A5%20)(\d+\.\d+\.\d+)(?=-)"),
+        "readme badge",
+    ),
+    (
+        "README.md",
+        re.compile(r"(?<=\*\*version )(\d+\.\d+\.\d+)(?= or newer\*\*)"),
+        "readme requirements",
+    ),
+    (
+        "CLAUDE.md",
+        re.compile(r"(?<=Requires RomM >= )(\d+\.\d+\.\d+)"),
+        "claude.md trap note",
+    ),
+]
+
+
+def enforced_version() -> str:
+    """The floor as ``main.py`` states it, e.g. ``4.9.0``."""
+    tree = ast.parse(SOURCE.read_text(encoding="utf-8"), filename=str(SOURCE))
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Assign):
+            continue
+        names = [t.id for t in node.targets if isinstance(t, ast.Name)]
+        if CONSTANT not in names:
+            continue
+        value = ast.literal_eval(node.value)
+        if not isinstance(value, tuple) or not all(isinstance(p, int) for p in value):
+            raise SystemExit(f"{CONSTANT} is not a tuple of ints: {value!r}")
+        return ".".join(str(p) for p in value)
+    raise SystemExit(f"{CONSTANT} not found in {SOURCE.name}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--fix", action="store_true", help="rewrite the claims instead of reporting")
+    args = parser.parse_args()
+
+    expected = enforced_version()
+    drift: list[str] = []
+    fixed: list[str] = []
+
+    for filename, pattern, label in CLAIMS:
+        path = ROOT / filename
+        text = path.read_text(encoding="utf-8")
+        found = pattern.findall(text)
+        if not found:
+            drift.append(f"{filename}: no RomM version found for the {label}")
+            continue
+        wrong = [v for v in found if v != expected]
+        if not wrong:
+            continue
+        if args.fix:
+            path.write_text(pattern.sub(expected, text), encoding="utf-8")
+            fixed.append(f"{filename}: {label} {', '.join(wrong)} -> {expected}")
+        else:
+            drift.append(f"{filename}: {label} says {', '.join(wrong)}, {SOURCE.name} enforces {expected}")
+
+    for line in fixed:
+        print(f"fixed {line}")
+    if drift:
+        print(
+            f"ERROR: the stated RomM minimum has drifted from {SOURCE.name}'s {CONSTANT} ({expected}):",
+            file=sys.stderr,
+        )
+        for line in drift:
+            print(f"  {line}", file=sys.stderr)
+        print(
+            "\nRun: python scripts/check_romm_min_version.py --fix",
+            file=sys.stderr,
+        )
+        return 1
+    if not fixed:
+        print(f"OK: every stated RomM minimum matches {CONSTANT} ({expected})")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())