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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 4.4.1
+Version: 4.4.2
 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.2**.
 
 > ## **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.2
   with:
     config: maintainability-agent.json
     changed-only: main...HEAD

{maintainability_agent-4.4.1 → maintainability_agent-4.4.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 **4.4.1**.
+Version **4.4.2**.
 
 > ## **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.2
   with:
     config: maintainability-agent.json
     changed-only: main...HEAD

{maintainability_agent-4.4.1 → maintainability_agent-4.4.2/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.2
 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.2**.
 
 > ## **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.2
   with:
     config: maintainability-agent.json
     changed-only: main...HEAD

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

@@ -104,6 +104,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 +223,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,6 +336,7 @@ 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
@@ -405,6 +408,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.2}/src/maintainability_audit/__init__.py

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

{maintainability_agent-4.4.1 → maintainability_agent-4.4.2}/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.2/src/maintainability_audit/_self_update.py

@@ -0,0 +1,126 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+import plistlib
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import _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}).")
+    _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. "
+                        "Restart the MCP server to use it (/mcp in Claude Code).")
+
+
+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.2}/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.2/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}"

maintainability_agent-4.4.2/tests/test_local_gate.py

@@ -0,0 +1,187 @@
+# Written by the Claude Sonnet test seat (Codex at its usage limit); Codex reviews.
+# His decision 2026-10-15: macOS is verified by an enforced local gate, not a CI runner.
+"""The enforced local gate that is the macOS evidence.
+
+`verify-macos` was removed from CI so each test runs once, on Linux. The
+claim that macOS works now rests on a git pre-push hook that runs the
+full suite on the maintainer's Mac. These tests pin the gate script, the
+installer, and the contributor docs that point at them.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+GATE = ROOT / "tools" / "local-gate.sh"
+INSTALLER = ROOT / "tools" / "install-local-gate.sh"
+
+
+def _logical_lines(path: Path) -> list[str]:
+    """Script lines with backslash continuations joined, comments dropped."""
+    text = path.read_text(encoding="utf-8").replace("\\\n", " ")
+    return [
+        " ".join(line.split()) for line in text.splitlines()
+        if line.strip() and not line.lstrip().startswith("#")
+    ]
+
+
+def _git(cwd: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *args], cwd=cwd, capture_output=True, text=True, check=False)
+
+
+def _temp_repo(tmp_path: Path) -> Path:
+    repo = tmp_path / "repo"
+    (repo / "tools").mkdir(parents=True)
+    assert _git(repo, "init", "-q").returncode == 0
+    for script in (GATE, INSTALLER):
+        target = repo / "tools" / script.name
+        shutil.copy(script, target)
+        target.chmod(0o755)
+    return repo
+
+
+def _install(repo: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["bash", str(repo / "tools" / "install-local-gate.sh")],
+        cwd=repo, capture_output=True, text=True, check=False)
+
+
+# -- 1. the gate script ---------------------------------------------------
+
+def test_the_gate_script_exists_and_is_executable() -> None:
+    assert GATE.is_file(), "tools/local-gate.sh does not exist"
+    assert os.access(GATE, os.X_OK), "tools/local-gate.sh is not executable"
+
+
+def test_the_gate_fails_fast() -> None:
+    lines = _logical_lines(GATE)
+    assert "set -euo pipefail" in lines
+
+
+def test_the_gate_runs_from_the_repository_root() -> None:
+    text = GATE.read_text(encoding="utf-8")
+    assert re.search(r"^\s*cd\s.*\.\.", text, re.MULTILINE), (
+        "the gate must cd to the directory above its own location")
+    assert "BASH_SOURCE" in text or "$0" in text
+
+
+def test_the_gate_lints_then_runs_the_whole_suite_with_coverage_floor() -> None:
+    lines = _logical_lines(GATE)
+    lint = [i for i, line in enumerate(lines) if line == "python3 -m ruff check src tests tools"]
+    suite = [i for i, line in enumerate(lines)
+             if re.search(r"python3 -m pytest\b", line)]
+    assert lint, f"no `python3 -m ruff check src tests tools` line: {lines}"
+    assert suite, f"no `python3 -m pytest` line: {lines}"
+    assert lint[0] < suite[0], "lint must run before the suite"
+    command = lines[suite[0]]
+    assert re.search(r"-n auto\b", command)
+    # Measure this tree by path. An installed copy of the package elsewhere on
+    # the machine (pip install --user) must never be measured: a package-name
+    # source counts both copies and reports a false low percentage.
+    tokens = command.split()
+    assert "--cov=src/maintainability_audit" in tokens
+    assert "--cov=maintainability_audit" not in tokens, (
+        "the gate must measure src/maintainability_audit by path, not by package name")
+    assert "--cov-fail-under=92" in command
+    assert not re.search(r"tests/\S+\.py", command), (
+        "the gate must run the whole suite, not named files")
+
+
+# -- 2. the installer -----------------------------------------------------
+
+def test_the_installer_exists_and_is_executable() -> None:
+    assert INSTALLER.is_file(), "tools/install-local-gate.sh does not exist"
+    assert os.access(INSTALLER, os.X_OK)
+
+
+def test_the_installer_resolves_the_hooks_dir_through_git() -> None:
+    """`--git-common-dir`/hooks is the repository's own hooks folder in every
+    worktree. `--git-path hooks` follows a global core.hooksPath to a shared
+    dispatcher, which the installer must never write into; that dispatcher
+    runs `$(git rev-parse --git-common-dir)/hooks/<name>` itself."""
+    text = INSTALLER.read_text(encoding="utf-8")
+    assert "git rev-parse --git-common-dir" in text
+    assert "--git-path hooks" not in text
+
+
+def test_the_installer_writes_an_executable_pre_push_hook(tmp_path: Path) -> None:
+    repo = _temp_repo(tmp_path)
+    result = _install(repo)
+    assert result.returncode == 0, result.stderr
+    hook = repo / ".git" / "hooks" / "pre-push"
+    assert hook.is_file()
+    assert os.access(hook, os.X_OK)
+    assert "tools/local-gate.sh" in hook.read_text(encoding="utf-8")
+
+
+def test_the_installer_is_idempotent(tmp_path: Path) -> None:
+    repo = _temp_repo(tmp_path)
+    assert _install(repo).returncode == 0
+    hook = repo / ".git" / "hooks" / "pre-push"
+    first = hook.read_bytes()
+    again = _install(repo)
+    assert again.returncode == 0, again.stderr
+    assert hook.read_bytes() == first
+
+
+def test_the_installer_will_not_overwrite_a_foreign_hook(tmp_path: Path) -> None:
+    repo = _temp_repo(tmp_path)
+    hooks = repo / ".git" / "hooks"
+    hooks.mkdir(exist_ok=True)
+    hook = hooks / "pre-push"
+    hook.write_text("#!/bin/sh\necho mine\n", encoding="utf-8")
+    hook.chmod(0o755)
+    before = hook.read_bytes()
+    result = _install(repo)
+    assert result.returncode != 0
+    assert hook.read_bytes() == before
+
+
+def test_the_installed_hook_blocks_a_push_when_the_gate_fails(tmp_path: Path) -> None:
+    repo = _temp_repo(tmp_path)
+    assert _install(repo).returncode == 0
+    # Replace the copied gate with one that fails: the hook must propagate.
+    gate = repo / "tools" / "local-gate.sh"
+    gate.write_text("#!/usr/bin/env bash\nexit 7\n", encoding="utf-8")
+    gate.chmod(0o755)
+    hook = repo / ".git" / "hooks" / "pre-push"
+    result = subprocess.run(
+        [str(hook), "origin", "file:///nowhere"], cwd=repo, input="",
+        capture_output=True, text=True, check=False)
+    assert result.returncode != 0
+
+
+def test_the_installed_hook_passes_when_the_gate_passes(tmp_path: Path) -> None:
+    repo = _temp_repo(tmp_path)
+    assert _install(repo).returncode == 0
+    gate = repo / "tools" / "local-gate.sh"
+    gate.write_text("#!/usr/bin/env bash\nexit 0\n", encoding="utf-8")
+    gate.chmod(0o755)
+    hook = repo / ".git" / "hooks" / "pre-push"
+    result = subprocess.run(
+        [str(hook), "origin", "file:///nowhere"], cwd=repo, input="",
+        capture_output=True, text=True, check=False)
+    assert result.returncode == 0, result.stderr
+
+
+# -- 3. the contributor docs ---------------------------------------------
+
+def test_contributing_tells_contributors_to_install_the_gate() -> None:
+    text = (ROOT / "CONTRIBUTING.md").read_text(encoding="utf-8")
+    assert "tools/install-local-gate.sh" in text
+
+
+def test_contributing_says_the_pre_push_gate_verifies_macos() -> None:
+    text = (ROOT / "CONTRIBUTING.md").read_text(encoding="utf-8").lower()
+    assert "pre-push" in text
+    assert "macos" in text
+    assert any(
+        "pre-push" in para.lower() and "macos" in para.lower()
+        for para in text.split("\n\n")
+    ), "the pre-push gate and macOS must be stated together"

{maintainability_agent-4.4.1 → maintainability_agent-4.4.2}/tests/test_operator_named_reads.py

@@ -146,6 +146,8 @@ WRITES_A_FILE = {
     "--comment-output", "--prompt-output", "--attestation-output",
     "--agent-instructions-output", "--hostile-prompt-output",
     "--instructions-output-dir", "--skills-dir", "--target-path",
+    # The home --install-updater writes its launch agent into (D230).
+    "--home",
 }
 NOT_AN_OPERATOR_PATH = {
     # A revspec, not a file.
@@ -160,6 +162,7 @@ NOT_AN_OPERATOR_PATH = {
     "--fail-on-gate", "--fail-on-new", "--fail-on-out-of-scope",
     "--fail-on-regression", "--force-skill", "--format", "--help",
     "--init-agent-standards", "--install-precommit-hook", "--install-skill",
+    "--update", "--install-updater", "--no-launchctl",
     "--record-history", "--staged", "--target", "--transformation",
     "--version", "--work",
 }