maintainability-agent 4.4.1__tar.gz → 4.4.3__tar.gz

{maintainability_agent-4.4.1/src/maintainability_agent.egg-info → maintainability_agent-4.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 4.4.1
+Version: 4.4.3
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -47,7 +47,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 **4.4.1**.
+Version **4.4.3**.
 
 > ## **Calibrated against 201 mature open-source repositories in fifteen languages.**
 >
@@ -488,7 +488,8 @@ and is now the dominant failure in the probe, which is why the count moved. The
 bounded, symlink-refusing write works through a *file descriptor*, so a validated
 path cannot be swapped for a symlink before the write lands — Windows has no
 equivalent and the portable rewrite is the hole. **An unsupported platform never
-buys green by weakening the supported ones.**
+buys green by weakening the supported ones.** Windows is not run in CI at all
+(Decision 18); a Windows user who hits a problem can open an issue or a pull request.
 
 ## Invokable skill / slash command
 
@@ -501,7 +502,11 @@ Copilot Chat:
 maintainability-agent --install-skill        # writes ~/.claude/skills
 ```
 
-Re-run it after every upgrade — a drifted skill teaches agents a dead workflow,
+`maintainability-agent --update` upgrades the install to the newest release —
+never a downgrade — re-syncs the skill, and says when the MCP server needs a
+restart; `maintainability-agent --install-updater` runs it hourly (macOS launch
+agent). Run `--install-skill` by hand after any other upgrade — a drifted skill
+teaches agents a dead workflow,
 so a differing installed copy is refused with the list of differences. Per-host
 install destinations, and `--init-agent-standards` for always-on guidance
 instead of an invokable skill:
@@ -512,7 +517,7 @@ instead of an invokable skill:
 This repo ships `action.yml`, usable as a composite action:
 
 ```yaml
-- uses: marshallguillory86/maintainability-agent@v4.4.1
+- uses: marshallguillory86/maintainability-agent@v4.4.3
   with:
     config: maintainability-agent.json
     changed-only: main...HEAD

{maintainability_agent-4.4.1 → maintainability_agent-4.4.3}/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 **4.4.1**.
+Version **4.4.3**.
 
 > ## **Calibrated against 201 mature open-source repositories in fifteen languages.**
 >
@@ -446,7 +446,8 @@ and is now the dominant failure in the probe, which is why the count moved. The
 bounded, symlink-refusing write works through a *file descriptor*, so a validated
 path cannot be swapped for a symlink before the write lands — Windows has no
 equivalent and the portable rewrite is the hole. **An unsupported platform never
-buys green by weakening the supported ones.**
+buys green by weakening the supported ones.** Windows is not run in CI at all
+(Decision 18); a Windows user who hits a problem can open an issue or a pull request.
 
 ## Invokable skill / slash command
 
@@ -459,7 +460,11 @@ Copilot Chat:
 maintainability-agent --install-skill        # writes ~/.claude/skills
 ```
 
-Re-run it after every upgrade — a drifted skill teaches agents a dead workflow,
+`maintainability-agent --update` upgrades the install to the newest release —
+never a downgrade — re-syncs the skill, and says when the MCP server needs a
+restart; `maintainability-agent --install-updater` runs it hourly (macOS launch
+agent). Run `--install-skill` by hand after any other upgrade — a drifted skill
+teaches agents a dead workflow,
 so a differing installed copy is refused with the list of differences. Per-host
 install destinations, and `--init-agent-standards` for always-on guidance
 instead of an invokable skill:
@@ -470,7 +475,7 @@ instead of an invokable skill:
 This repo ships `action.yml`, usable as a composite action:
 
 ```yaml
-- uses: marshallguillory86/maintainability-agent@v4.4.1
+- uses: marshallguillory86/maintainability-agent@v4.4.3
   with:
     config: maintainability-agent.json
     changed-only: main...HEAD

{maintainability_agent-4.4.1 → maintainability_agent-4.4.3/src/maintainability_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 4.4.1
+Version: 4.4.3
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -47,7 +47,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 **4.4.1**.
+Version **4.4.3**.
 
 > ## **Calibrated against 201 mature open-source repositories in fifteen languages.**
 >
@@ -488,7 +488,8 @@ and is now the dominant failure in the probe, which is why the count moved. The
 bounded, symlink-refusing write works through a *file descriptor*, so a validated
 path cannot be swapped for a symlink before the write lands — Windows has no
 equivalent and the portable rewrite is the hole. **An unsupported platform never
-buys green by weakening the supported ones.**
+buys green by weakening the supported ones.** Windows is not run in CI at all
+(Decision 18); a Windows user who hits a problem can open an issue or a pull request.
 
 ## Invokable skill / slash command
 
@@ -501,7 +502,11 @@ Copilot Chat:
 maintainability-agent --install-skill        # writes ~/.claude/skills
 ```
 
-Re-run it after every upgrade — a drifted skill teaches agents a dead workflow,
+`maintainability-agent --update` upgrades the install to the newest release —
+never a downgrade — re-syncs the skill, and says when the MCP server needs a
+restart; `maintainability-agent --install-updater` runs it hourly (macOS launch
+agent). Run `--install-skill` by hand after any other upgrade — a drifted skill
+teaches agents a dead workflow,
 so a differing installed copy is refused with the list of differences. Per-host
 install destinations, and `--init-agent-standards` for always-on guidance
 instead of an invokable skill:
@@ -512,7 +517,7 @@ instead of an invokable skill:
 This repo ships `action.yml`, usable as a composite action:
 
 ```yaml
-- uses: marshallguillory86/maintainability-agent@v4.4.1
+- uses: marshallguillory86/maintainability-agent@v4.4.3
   with:
     config: maintainability-agent.json
     changed-only: main...HEAD

{maintainability_agent-4.4.1 → maintainability_agent-4.4.3}/src/maintainability_agent.egg-info/SOURCES.txt

@@ -63,6 +63,7 @@ src/maintainability_audit/_mcp_gate.py
 src/maintainability_audit/_mcp_grants.py
 src/maintainability_audit/_mcp_refusals.py
 src/maintainability_audit/_mcp_resources.py
+src/maintainability_audit/_mcp_servers.py
 src/maintainability_audit/_mcp_setup.py
 src/maintainability_audit/_metric_adapters.py
 src/maintainability_audit/_metrics_types.py
@@ -104,6 +105,7 @@ src/maintainability_audit/_second_source.py
 src/maintainability_audit/_security_delegate.py
 src/maintainability_audit/_security_work_order.py
 src/maintainability_audit/_selection.py
+src/maintainability_audit/_self_update.py
 src/maintainability_audit/_semantic.py
 src/maintainability_audit/_semantic_policy.py
 src/maintainability_audit/_semantic_ts.py
@@ -222,6 +224,7 @@ tests/test_checkstyle_catalog.py
 tests/test_child_sandbox.py
 tests/test_ci_history_recipe.py
 tests/test_ci_installs_the_analyzer_pool.py
+tests/test_ci_runs_once.py
 tests/test_claimed_languages.py
 tests/test_clean_sees_the_weakened_oracle.py
 tests/test_cli.py
@@ -334,11 +337,13 @@ tests/test_kotlin_metrics.py
 tests/test_language_coverage.py
 tests/test_language_support_honesty.py
 tests/test_list_tools_publishes_the_answer_path.py
+tests/test_local_gate.py
 tests/test_maintenance_signals.py
 tests/test_mcp_baseline_payload.py
 tests/test_mcp_format_contract.py
 tests/test_mcp_history.py
 tests/test_mcp_server.py
+tests/test_mcp_servers.py
 tests/test_mcp_start_failure_names_what_is_installed.py
 tests/test_migration_1_0.py
 tests/test_missing_security_scanners_are_named_before_the_run.py
@@ -405,6 +410,7 @@ tests/test_security_findings_keep_their_handoff.py
 tests/test_security_pillar_asserts_a_scanner_set.py
 tests/test_security_pillar_runs_and_shows.py
 tests/test_selection_covers_every_parsed_language.py
+tests/test_self_update.py
 tests/test_semantic_findings_stay_inside_the_audited_files.py
 tests/test_semantic_policy.py
 tests/test_setup_answers_are_the_same_setup.py

{maintainability_agent-4.4.1 → maintainability_agent-4.4.3}/src/maintainability_audit/__init__.py

@@ -1,3 +1,3 @@
 """Maintainability Audit CI."""
 
-__version__ = "4.4.1"
+__version__ = "4.4.3"

{maintainability_agent-4.4.1 → maintainability_agent-4.4.3}/src/maintainability_audit/_arguments.py

@@ -212,6 +212,24 @@ def _add_setup_actions(parser: argparse.ArgumentParser) -> None:
              "own without asking, because that is an upgrade. Honours "
              "core.hooksPath.",
     )
+    parser.add_argument(
+        "--update", action="store_true",
+        help="Upgrade this install to the newest release (never a downgrade), "
+             "re-sync the skill, and say when the MCP server needs a restart.",
+    )
+    parser.add_argument(
+        "--install-updater", action="store_true",
+        help="Write the hourly launch agent that runs --update (macOS), "
+             "replacing the legacy one.",
+    )
+    parser.add_argument(
+        "--home", default=None, metavar="DIR",
+        help="With --install-updater: the home directory to write into (default: ~).",
+    )
+    parser.add_argument(
+        "--no-launchctl", action="store_true",
+        help="With --install-updater: write the agent without loading it.",
+    )
     parser.add_argument(
         "--skills-dir", default=None, metavar="DIR",
         help="Where --install-skill writes (default: ~/.claude/skills).",

maintainability_agent-4.4.3/src/maintainability_audit/_mcp_servers.py

@@ -0,0 +1,107 @@
+"""Which MCP servers are running which version, so ``--update`` can stop stale ones.
+
+A stdio MCP server holds the code it loaded at spawn. After an upgrade it
+keeps serving the old version until it stops, and its host starts the new
+one on the next call. 4.4.2 told the operator to run ``/mcp``, which in the
+VS Code panel only lists servers (D232). Now each server records its pid and
+version here, marks itself busy while an audit runs, and ``--update`` stops
+the stale ones that are idle. A busy server is left alone; the next hourly
+update stops it.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import _runner
+
+
+@dataclass(frozen=True)
+class Stopped:
+    stopped: tuple[int, ...] = ()
+    busy: tuple[int, ...] = ()
+    gone: tuple[int, ...] = ()
+
+
+def _servers(home: Path) -> Path:
+    return home / ".local" / "share" / "maintainability-agent" / "servers"
+
+
+def register(home: Path, pid: int, version: str) -> Path:
+    folder = _servers(home)
+    folder.mkdir(parents=True, exist_ok=True)
+    record = folder / f"{pid}.json"
+    record.write_text(json.dumps({"pid": pid, "version": version}) + "\n", encoding="utf-8")
+    return record
+
+
+def unregister(home: Path, pid: int) -> None:
+    (_servers(home) / f"{pid}.json").unlink(missing_ok=True)
+
+
+@contextmanager
+def busy(home: Path, pid: int) -> Iterator[None]:
+    folder = _servers(home)
+    folder.mkdir(parents=True, exist_ok=True)
+    marker = folder / f"{pid}.busy"
+    marker.touch()
+    try:
+        yield
+    finally:
+        marker.unlink(missing_ok=True)
+
+
+def _alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def _is_server(pid: int) -> bool:
+    """The pid is still an MA MCP server, not a reused pid of something else."""
+    result = _runner.run("mcp-servers", _runner.Invocation(argv=("ps", "-o", "command=", "-p", str(pid))),
+                         timeout_seconds=10)
+    command = result.stdout or ""
+    return "maintainability" in command and "mcp" in command
+
+
+def stop_stale(home: Path, installed: str, *,
+               alive: Callable[[int], bool] = _alive,
+               is_server: Callable[[int], bool] = _is_server,
+               kill: Callable[[int, int], None] = os.kill) -> Stopped:
+    folder = _servers(home)
+    stopped: list[int] = []
+    held: list[int] = []
+    gone: list[int] = []
+    for record in sorted(folder.glob("*.json")) if folder.is_dir() else []:
+        try:
+            data = json.loads(record.read_text(encoding="utf-8"))
+            pid, version = int(data["pid"]), str(data["version"])
+        except (OSError, ValueError, KeyError, TypeError):
+            record.unlink(missing_ok=True)
+            continue
+        if version == installed:
+            continue
+        if not alive(pid):
+            record.unlink(missing_ok=True)
+            gone.append(pid)
+        elif (folder / f"{pid}.busy").exists():
+            held.append(pid)
+        elif not is_server(pid):
+            record.unlink(missing_ok=True)
+            gone.append(pid)
+        else:
+            kill(pid, signal.SIGTERM)
+            record.unlink(missing_ok=True)
+            stopped.append(pid)
+    return Stopped(tuple(stopped), tuple(held), tuple(gone))

maintainability_agent-4.4.3/src/maintainability_audit/_self_update.py

@@ -0,0 +1,141 @@
+"""Keep the local install current: ``--update`` and ``--install-updater``.
+
+The updater used to be an untracked script beside the venv, run by a launch
+agent. It trusted PyPI's ``info.version``, which lags a release, and on
+2026-09-22 it *downgraded* 3.7.29 to 3.7.19; it never re-synced the skill the
+README says to sync after every upgrade; and nothing tested it (D230).
+
+Now it is a product command. The installer resolves the version — ``pip
+install --upgrade`` picks the highest release the index lists and never moves
+backwards — so this module holds no HTTP client and reads no release feed
+(P1: analysis touches no network; updating is an operator action, like tool
+acquisition). Every child process goes through ``_runner.run`` (rule 7). A
+version that comes back lower than before is reported, never accepted
+silently; a higher one re-syncs the skill and records that the MCP server,
+which holds the code it loaded at spawn, needs a restart; stale servers
+that are not mid-audit are stopped so their host restarts them (D232).
+"""
+
+from __future__ import annotations
+
+import plistlib
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import _mcp_servers, _runner
+
+PACKAGE = "maintainability-agent"
+#: The launch agent, named for the product and the component (reverse DNS of
+#: the project's home), replacing the personal-prefix label it had before.
+LABEL = "io.github.marshallguillory86.maintainability-agent.update"
+LEGACY_LABEL = "com.marshallguillory.maintainability-agent-update"
+_VERSION_CODE = f"import importlib.metadata as m; print(m.version({PACKAGE!r}))"
+
+
+@dataclass(frozen=True)
+class UpdateResult:
+    before: str
+    after: str
+    skill_synced: bool
+    restart_needed: bool
+    error: str | None
+    message: str
+
+
+def _key(version: str) -> tuple:
+    """Release ordering for plain ``N.N.N`` versions; a suffix sorts before
+    the release it precedes (``4.4.1rc1`` < ``4.4.1``)."""
+    parts = []
+    for piece in version.strip().split("."):
+        number = re.match(r"\d+", piece)
+        parts.append((int(number.group()) if number else 0, 1 if number and number.end() == len(piece) else 0))
+    return tuple(parts)
+
+
+def _state_dir(home: Path) -> Path:
+    return home / ".local" / "share" / "maintainability-agent"
+
+
+def _run(argv: list[str]) -> _runner.ToolResult:
+    return _runner.run("self-update", _runner.Invocation(argv=tuple(argv)), timeout_seconds=600)
+
+
+def _installed(python: str) -> str:
+    return (_run([python, "-c", _VERSION_CODE]).stdout or "").strip()
+
+
+def update(python: str, uv: str | None, home: Path) -> UpdateResult:
+    before = _installed(python)
+    if uv:
+        argv = [uv, "pip", "install", "--python", python, "--upgrade", PACKAGE]
+    else:
+        argv = [python, "-m", "pip", "install", "--upgrade", PACKAGE]
+    installed = _run(argv)
+    after = _installed(python)
+    if not installed.usable:
+        return UpdateResult(before, after, False, False, f"install failed: {installed.detail}",
+                            f"Update failed; still on {before}.")
+    if _key(after) < _key(before):
+        return UpdateResult(before, after, False, False,
+                            f"version went down from {before} to {after}",
+                            f"Refused: the install moved {before} to {after}, a downgrade.")
+    if _key(after) == _key(before):
+        return UpdateResult(before, after, False, False, None,
+                            f"Already up to date ({after}).{_servers_note(home, after)}")
+    _run([python, "-m", "maintainability_audit", "--install-skill"])
+    state = _state_dir(home)
+    state.mkdir(parents=True, exist_ok=True)
+    (state / ".pending-restart").write_text(after + "\n", encoding="utf-8")
+    return UpdateResult(before, after, True, True, None,
+                        f"Updated {before} -> {after}; skill re-synced.{_servers_note(home, after)}")
+
+
+def _servers_note(home: Path, installed: str) -> str:
+    """Stop the MCP servers still on an older version (D232) and say so.
+    A host starts a stopped stdio server again on its next call."""
+    result = _mcp_servers.stop_stale(home, installed)
+    note = ""
+    if result.stopped:
+        note += (f" Stopped {len(result.stopped)} MCP server(s) on an older version;"
+                 f" the host starts {installed} on its next call.")
+    if result.busy:
+        note += (f" {len(result.busy)} busy with an audit kept running;"
+                 " the next update stops it.")
+    return note
+
+
+def update_action() -> int:
+    result = update(sys.executable, _runner.locate("uv"), Path.home())
+    print(result.message, file=sys.stderr if result.error else sys.stdout)
+    return 1 if result.error else 0
+
+
+def install_updater(home: Path, *, launchctl: bool = True) -> int:
+    """Write the hourly launch agent that runs ``--update``; remove the
+    legacy one so two updaters never run."""
+    agents = home / "Library" / "LaunchAgents"
+    agents.mkdir(parents=True, exist_ok=True)
+    legacy = agents / f"{LEGACY_LABEL}.plist"
+    if legacy.exists():
+        if launchctl:
+            _run(["launchctl", "unload", str(legacy)])
+        legacy.unlink()
+    state = _state_dir(home)
+    state.mkdir(parents=True, exist_ok=True)
+    plist = agents / f"{LABEL}.plist"
+    plist.write_bytes(plistlib.dumps({
+        "Label": LABEL,
+        "ProgramArguments": [sys.executable, "-m", "maintainability_audit", "--update"],
+        "StartInterval": 3600,
+        "RunAtLoad": True,
+        "ProcessType": "Background",
+        "LowPriorityIO": True,
+        "StandardOutPath": str(state / "update.out.log"),
+        "StandardErrorPath": str(state / "update.err.log"),
+    }))
+    if launchctl:
+        _run(["launchctl", "load", str(plist)])
+    print(f"installed {plist}")
+    return 0

{maintainability_agent-4.4.1 → maintainability_agent-4.4.3}/src/maintainability_audit/cli.py

@@ -393,6 +393,15 @@ def _action_before_config(
     """
     if args.install_skill:
         return _install_skill_action(args)
+    if args.update:
+        from ._self_update import update_action
+
+        return update_action()
+    if args.install_updater:
+        from ._self_update import install_updater
+
+        home = Path(args.home).expanduser() if args.home else Path.home()
+        return install_updater(home, launchctl=not args.no_launchctl)
     if args.install_precommit_hook:
         from ._precommit_install import install_precommit_hook
 

{maintainability_agent-4.4.1 → maintainability_agent-4.4.3}/src/maintainability_audit/mcp_server.py

@@ -16,9 +16,11 @@ string, or invokes a shell.
 from __future__ import annotations
 
 import argparse
+import os
 from pathlib import Path
 from typing import Any
 
+from . import _mcp_servers
 from ._catalog import PolicyError as PolicyError
 
 # Redundant aliases on purpose: every name the split moved to
@@ -263,21 +265,23 @@ def _run_audit_tool(ledger, tool_error, repository_root, config_path, changed_on
     """
     try:
         _apply_call_consents(ledger, repository_root, setup, grant, setup_answers)
-        return audit_repository(
-            repository_root,
-            config_path,
-            changed_only,
-            run_analyzers,
-            format,
-            record_history,
-            baseline_path,
-            write_baseline,
-            include_prompt,
-            # Interactive door never assumes go (D27); CLI default is "run".
-            action=action,
-            roots=ledger.current(),
-            output_path=output_path,
-        )
+        # Busy while auditing: `--update` never stops a server mid-audit (D232).
+        with _mcp_servers.busy(Path.home(), os.getpid()):
+            return audit_repository(
+                repository_root,
+                config_path,
+                changed_only,
+                run_analyzers,
+                format,
+                record_history,
+                baseline_path,
+                write_baseline,
+                include_prompt,
+                # Interactive door never assumes go (D27); CLI default is "run".
+                action=action,
+                roots=ledger.current(),
+                output_path=output_path,
+            )
     except ANTICIPATED_REFUSALS as refusal:
         raise tool_error(str(refusal)) from refusal
 
@@ -548,7 +552,12 @@ def _parser() -> argparse.ArgumentParser:
 
 def main(argv: list[str] | None = None) -> int:
     args = _parser().parse_args(argv)
-    create_server(roots=allowed_roots(tuple(args.allow_root))).run("stdio")
+    # Recorded so `--update` can stop this server once it is stale (D232).
+    _mcp_servers.register(Path.home(), os.getpid(), VERSION)
+    try:
+        create_server(roots=allowed_roots(tuple(args.allow_root))).run("stdio")
+    finally:
+        _mcp_servers.unregister(Path.home(), os.getpid())
     return 0
 
 

maintainability_agent-4.4.3/tests/test_ci_runs_once.py

@@ -0,0 +1,98 @@
+"""Written by the Claude Sonnet test seat (Codex at its usage limit); Codex reviews.
+
+His words: 'The CI is ridiculously unacceptable'. The evidence: Quality Gates
+ran twice per PR (push on every branch plus pull_request), MA audited itself
+twice (maintainability.yml plus the Quality Gates audit job), a Windows probe
+failed every run while blocking nothing, and Sonar ran on every PR.
+
+The required checks must still run on every pull_request, or merges deadlock;
+that guard lives in test_workflow_supply_chain.py.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from _workflow_text import jobs, triggers
+
+WORKFLOWS = Path(__file__).resolve().parents[1] / ".github" / "workflows"
+
+
+def test_quality_gates_push_is_limited_to_main_so_a_pr_runs_once() -> None:
+    """No push trigger at all (his pipeline lint: a merge never re-runs
+    tests), or one limited to main."""
+    push = triggers("quality-gates.yml").get("push")
+    if push is None:
+        return
+    body = " ".join(s.strip() for s in push)
+    assert re.search(r"branches:\s*\[\s*main\s*\]", body) or (
+        "branches:" in body and re.search(r"-\s*main\b", body)
+    ), f"push must be absent or restricted to branches: [main]; got {body!r}"
+
+
+def test_maintainability_workflow_does_not_audit_every_pull_request_again() -> None:
+    assert "pull_request" not in triggers("maintainability.yml")
+
+
+def test_no_windows_job_runs_at_all() -> None:
+    """Decision 18 (his words: "just turn this shit off"): Windows is not
+    tested in CI; Windows users report problems as issues or PRs."""
+    assert "probe-windows" not in jobs("quality-gates.yml")
+    for path in WORKFLOWS.glob("*.yml"):
+        assert "windows-" not in path.read_text(encoding="utf-8"), path.name
+
+
+def test_sonar_does_not_run_on_pull_requests() -> None:
+    condition = jobs("quality-gates.yml")["sonar"]["if"]
+    assert condition, "sonar needs an `if:`"
+    assert "pull_request" not in condition
+
+
+def _runs_on_pull_request(condition: str) -> bool:
+    """True when an `if:` leaves the job running on pull_request."""
+    if not condition:
+        return True
+    if "!= 'pull_request'" in condition:
+        return False
+    return "pull_request" in condition or "!= 'push'" in condition
+
+
+def _job_bodies(workflow: str) -> dict[str, str]:
+    """Job id -> the job's raw text, so a test can read `runs-on` and steps."""
+    from _workflow_text import _code_lines, _sub_blocks, _top_block
+
+    blocks = _sub_blocks(_top_block(_code_lines(workflow), "jobs"), 2)
+    return {job_id: "\n".join(body) for job_id, body in blocks.items()}
+
+
+def test_no_macos_job_runs_in_ci() -> None:
+    """His decision (2026-10-15, option 1): each test runs once, on Linux
+    `verify`. macOS is covered by the local gate on his Mac."""
+    assert "verify-macos" not in jobs("quality-gates.yml")
+    for path in WORKFLOWS.glob("*.yml"):
+        for job_id, job in jobs(path.name).items():
+            assert "macos" not in job["name"].lower(), f"{path.name}:{job_id} name"
+        for job_id, body in _job_bodies(path.name).items():
+            runs_on = re.findall(r"^\s*runs-on:\s*(.*)$", body, flags=re.M)
+            assert not any("macos" in value.lower() for value in runs_on), (
+                f"{path.name}:{job_id} runs on macOS"
+            )
+
+
+def test_verify_does_not_run_on_a_merge_to_main() -> None:
+    """Tests run once, on the pull request; a push to main does not rerun them."""
+    condition = jobs("quality-gates.yml")["verify"]["if"]
+    assert condition, "verify needs an `if:` that excludes push"
+    assert "github.event_name != 'push'" in condition, condition
+
+
+def test_exactly_one_job_runs_the_test_suite_on_pull_requests() -> None:
+    bodies = _job_bodies("quality-gates.yml")
+    conditions = jobs("quality-gates.yml")
+    runners = [
+        job_id
+        for job_id, body in bodies.items()
+        if "pytest" in body and _runs_on_pull_request(conditions[job_id]["if"])
+    ]
+    assert runners == ["verify"], f"jobs running pytest on pull_request: {runners}"