loopgate 0.1.0__py3-none-any.whl

harness/ralph.sh

@@ -0,0 +1,34 @@
+#!/bin/sh
+# Ralph: hand docs/PROMPT.md to a fresh-context agent and loop. The repo is the only memory.
+# Keep Ralph Dumb: start the worker, give it the prompt, print a line, repeat. Nothing else.
+# Setup (deps + git hooks) is `harness install`. The gate runs from the git hooks on commit.
+# Want logs? Redirect this script: `harness/ralph.sh ... > run.log 2>&1`.
+#
+# Usage:
+#   harness/ralph.sh [max_iterations] [max_minutes_per_iteration] <agent command...>
+#  e.g.
+#   harness/ralph.sh 10 20 claude -p --permission-mode acceptEdits
+#   harness/ralph.sh 10 20 codex exec --json --sandbox workspace-write -
+#
+# ****      Motto: Keep Ralph Dumb.      ****
+set -eu
+
+# Mark loop commits so the gate (run by the git hooks) applies containment to the worker.
+export RALPH_LOOP=1
+
+MAX_ITERATIONS=$1
+MAX_MINUTES=$2
+TIMEOUT=$TIMEOUT
+shift 2
+
+i=1
+while [ "$i" -le "$MAX_ITERATIONS" ]; do
+    printf '{"type":"ralph","iteration":%s,"max_iterations":%s,"max_minutes":%s,"timestamp":"%s"}\n' \
+    "$i" "$MAX_ITERATIONS" "$MAX_MINUTES" "$(date '+%Y-%m-%dT%H:%M')"
+
+    printf '%s\n\nRALPH_ITERATION=%s/%s\n' "$RALPH_PROMPT" "$i" "$MAX_ITERATIONS" \
+        | "$TIMEOUT" "$((MAX_MINUTES * 60))" "$@"
+    i=$((i + 1))
+done
+
+printf '{"type":"ralph","completed":%s,"max_minutes":%s,"timestamp":"%s"}\n' "$((i - 1))" "$MAX_MINUTES" "$(date '+%Y-%m-%dT%H:%M')"

harness/temp.pyproject.toml

@@ -0,0 +1,407 @@
+[project]
+name = "loopgate"
+requires-python = ">=3.10"
+version = "0.1.0"
+[project.scripts]
+harness = "harness.cli:main" # creates the executable `harness`
+[build-system]
+requires = ["hatchling>=1.32"]
+build-backend = "hatchling.build" # allows `harness` commands, runs the executable
+[dependency-groups]
+dev = [
+    "complexipy",
+    "coverage",
+    "hypothesis",
+    "mutmut",
+    "pip-audit",
+    "pylint",
+    "pyright",
+    "pytest",
+    "pytest-cov",
+    "pytest-xdist",
+    "ruff",
+    "semgrep",
+    "tomlkit",
+    "typer"
+]
+# ==============================================================================
+# Harness Configuration — single source of truth for agents and every check.
+# harness/gate.py parses [tool.harness] once at import into the constants it uses.
+# CI runs `harness gate`, so it uses the same commands.
+# Humans own this file (it is agent-forbidden below).
+# ==============================================================================
+[tool.harness]
+[tool.harness.settings]
+behavior = "fail"  # "fail" or "warn": change to "warn" if your project has too many blocking failures to start
+languages = ["py"]
+error_diff_lines = 500  # 400 ~90th percentile of pull requests, 200 LOC generally ok
+
+# argv preset per agent for `harness run <agent>`
+[tool.harness.agents]
+claude = [
+    "claude",
+    "--model", "opus",
+    "--permission-mode", "auto",
+    # "--bare" # for one-shot minimal run: skips MCP, hooks, plugins, CLAUDE.md, reduced startup, and sets
+    # CLAUDE_CODE_SIMPLE + uses CLAUDE_CODE_OAUTH_TOKEN (ANTHROPIC_API_KEY billed), no .claude log
+    "--no-session-persistence",  # no-save session data good for disposable auto tasks
+    "--output-format", "stream-json",
+    "--verbose", "-p",
+]
+codex = [
+    # env -u clears the CODEX_* session/thread ids so a child agent never binds to the parent conversation
+    "env", "-u", "CODEX_THREAD_ID", "-u", "CODEX_CONVERSATION_ID", "-u", "CODEX_SESSION_ID",
+    "codex",
+    "exec",
+    "--model", "gpt-5.5",
+    "--json",
+    "--sandbox", "danger-full-access", "-",
+]
+agy = [
+    "agy",
+    "--model", "gemini-3.5-flash-low",
+    "--dangerously-skip-permissions",
+    "--add-dir", ".",
+    "--log-file", "{log_path}",
+    "--prompt", "-"
+]
+copilot = [
+    "copilot",
+    "--model=auto",  # if paid: https://docs.github.com/en/copilot/reference/ai-models/supported-models
+    "--output-format", "json", "--stream", "on",
+    "--allow-all", "--no-ask-user",
+]
+# EXAMPLE OF WHAT Javascript checks might be
+#
+# [tool.harness.preflight]
+# checks = ["npm", "--prefix", "harness/js-scaffold", "run", "preflight"]
+# [tool.harness.gate]
+# checks = ["npm", "--prefix", "harness/js-scaffold", "run", "gate"]
+#
+# EXAMPLE OF WHAT Ruby checks might be
+#
+# [tool.harness.rb.preflight]
+# checks = ["bundle", "exec", "rubocop"]
+# [tool.harness.rb.gate]
+# checks = ["bundle", "exec", "rspec"]
+
+[tool.harness.preflight]
+ruff_lint = ["ruff", "check", "--no-cache", "--show-fixes", "."]
+pylint = ["pylint", "."]  # second tool in category can just be named the tool
+ruff_format = ["ruff", "format", "--no-cache", "--check"]
+complexity = ["complexipy", ".", "--suggest-refactors"]
+
+[tool.harness.gate]
+audit = ["pip-audit"] # or audit = ["uv", "audit", "--preview-features", "audit"]
+security = [
+    "semgrep", "scan",
+    "--error",  # exit nonzero on findings so the gate blocks the commit, not just reports
+    "--config", "auto",
+    "--config", "p/secrets",
+    "--exclude-rule", "yaml.github-actions.security.github-actions-mutable-action-tag.github-actions-mutable-action-tag",
+    ".",
+]
+types = ["pyright", "--outputjson"]
+test = ["pytest", "-p", "no:cacheprovider", "-n", "auto", "--cov", "--cov-report=term-missing", "--cov-fail-under=100", "--durations=5"]
+
+[tool.harness.FORBIDDEN]
+DIRS = ["harness/", ".githooks/", ".github/", ".git/", "preferences/", "tests/preferences/", "mutation", "tests/mutation/"]
+FILES = [
+    "agents.md",
+    "docs/prompt.md",
+    "docs/plan.md",  # delete/comment line if you want agents to manage the core plan
+    # tooling/config files that would weaken checks:
+    "tox.ini",
+    "setup.cfg",
+    "pytest.ini",
+    ".pytest.ini",
+    "pytest.toml",
+    ".pytest.toml",
+    ".coveragerc",
+    ".coveragerc.toml",
+    "ruff.toml",
+    ".ruff.toml",
+    ".flake8",
+    "pylintrc",
+    ".pylintrc",
+    "pylintrc.toml",
+    ".pylintrc.toml",
+    "pyrightconfig.json",
+    "mypy.ini",
+    ".mypy.ini",
+    "ty.toml",
+    "pyrefly.toml",
+    ".pyrefly.toml",
+    "complexipy.toml",
+    ".complexipy.toml",
+    "radon.cfg",
+    ".semgrepignore",
+    "semgrep.yml",
+    "semgrep.yaml",
+    ".semgrep.yml",
+    ".semgrep.yaml",
+    "semgrep.config.yml",
+    "semgrep.config.yaml",
+    ".bandit",
+    "sonar-project.properties",
+    ".snyk",
+    ".gitmodules",
+    ".gitattributes",
+    "pyproject.toml",  # agents will claim inability to add dependencies with this forbidden
+    "requirements.txt",
+    "uv.lock",  # if *.lock remains, agents will leave it uncommitted if file changes
+    "poetry.lock"
+]
+PATTERNS = [
+    "# noqa",
+    "# flake8",
+    "type: ignore",
+    "type:ignore",
+    "no_type_check",
+    "pyright: ignore",
+    "from typing import any",
+    "from typing import cast",
+    "from typing import no_type_check",
+    "mypy: ignore",
+    "ty: ignore",
+    "pyrefly: ignore",
+    "pragma: no cover",
+    "eslint-disable",
+    "ts-ignore",
+    "ts-nocheck",
+    "ts-expect-error",
+    "--no-verify",
+    "hookspath",
+    "pytest.mark.skip",
+    "fail_under",
+    "cov-fail-under",
+    "# pylint:",
+    "pytest.skip",
+    "pytest.mark.xfail",
+    "pytest.mark.skipif",
+    "nosemgrep",
+    "# nosec",
+    "ruff: noqa",
+    "ruff: disable",
+    "ruff: ignore",
+    "fmt: off",
+    "fmt: skip",
+    "yapf: disable",
+    "complexipy: ignore",
+    "pragma: no mutate"
+]
+
+# ==============================================================================
+# Pyright Configuration
+# ==============================================================================
+[tool.pyright]
+typeCheckingMode = "standard"      # Pyright's has: "strict", "standard", "basic"
+reportAssertAlwaysTrue = "error"   # Catch asserts that are always true.
+reportUnusedImport = "none"        # Handled by Ruff F401
+reportUnusedVariable = "none"      # Handled by Ruff F841
+verboseOutput = true               # JSON report output when Pyright is run
+include = ["."]                    # Type-check shipped code plus repository preferences.
+exclude = ["scratchpad", "mutants", "**/node_modules", "**/__pycache__", ".venv", "**/.*"]
+
+# ==============================================================================
+# Test Configuration
+# ==============================================================================
+[tool.pytest.ini_options]
+minversion = "9.0"
+addopts = ["-ra"]                   # Print useful short reasons for outcomes
+testpaths = ["tests"]
+pythonpath = ["."]                  # Repo root: tests import root packages by full dotted path
+
+# ==============================================================================
+# Test Coverage Configuration
+# ==============================================================================
+[tool.coverage]
+run.source = ["src", "preferences", "mutation"] # ADD EVERY DIRECTORY THAT SHIPS CODE TO ENSURE 100% COVERAGE
+report.show_missing = true         # Show exact missed lines when coverage fails
+report.skip_covered = false        # Keep fully covered files visible in reports
+report.fail_under = 100            # Block merges unless all shipped code is covered
+skip_covered = false               # Same behavior for older coverage config readers
+
+# ==============================================================================
+# Hypothesis Property Tests Configuration
+# ==============================================================================
+[tool.hypothesis]
+max_examples = 50    # Generate 50 random test cases per property test (default 100)
+deadline = 500       # Fails tests if an individual example takes longer than 500ms
+derandomize = true   # false default seeds random, uncovers more bugs. True = deterministic runs
+
+# ==============================================================================
+# Mutmut (Mutation Testing) Configuration
+# ==============================================================================
+[tool.mutmut]
+max-children = 2
+source_paths = ["preferences", "src"]  # what to mutate
+also_copy = ["preferences", "mutation", ".githooks"]  # not mutated paths, copied for imports
+
+# ==============================================================================
+# Cognitive Complexity Complexipy Configuration
+# ==============================================================================
+[tool.complexipy]
+paths = ["src", "preferences", "mutation"]
+exclude = ["**/tests/**"]    # Test code can be more branching and example-heavy than production code
+max-complexity-allowed = 15  # Cognitive complexity cap catches nested, hard-to-read flow (default 15)
+no-ignore = false            # Disallow `# complexipy: ignore`, fix complexity instead of suppressing it
+report-ignored = true        # List every file:line with a suppressive ignore comment
+failed = true                # Show only functions over the threshold so gate output stays actionable
+sort = "asc"                 # Sort results in ascending order
+quiet = false                # Suppress output
+ignore-complexity = false    # Don't exit with error on max-complexity-allowed threshold breach
+
+# ==============================================================================
+# Pylint Configuration
+# ==============================================================================
+[tool.pylint]
+main.load-plugins = ["pylint.extensions.docparams"]
+main.ignore = [
+    ".git",
+    ".venv",
+    "__pycache__",
+    "migrations",
+    "build",
+    "dist",
+    "scratchpad",
+    "tests",
+    "**/tests/**",
+    ".worktrees",
+    "worktrees",
+    "mutants",
+    ".tox",
+    "tox",
+    "harness"
+]
+format.max-line-length = 120         # Keep Pylint line accounting aligned with Ruff E501
+format.max-module-lines = 750        # Enable Pylint C0302 because Ruff has no equivalent, includes docstrings
+parameter_documentation.accept-no-param-doc = false  # Require Args docs when Pylint docparams sees params
+reports.reports = "yes"              # Print detailed Pylint reports so humans see why score changed
+reports.score = true                 # Keep Pylint's score visible as a coarse trend signal
+"messages control".enable = ["F", "I", "R0022", "missing-param-doc"]  # Show fatal/info, stale options, param docs
+design.max-attributes = 10           # Max instance attributes (variables) allowed in a class
+
+# ==============================================================================
+# Unified Ruff Configuration
+# ==============================================================================
+[tool.ruff]
+target-version = "py310"
+preview = true                     # Enable newer Ruff rules before they are fully stable
+line-length = 120                   # Keep code readable without forcing narrow wrapping
+force-exclude = true                # Respect excluded paths even when they are passed directly
+exclude = [
+    "*.md",
+    ".git",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "scratchpad",
+    "node_modules",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".uv",
+    "**/.pylint_bits/**",          # Stops Ruff from fighting Pylint's internal cache
+    "harness"   # changes to ruff rules should not trigger non-project harness code
+]
+[tool.ruff.format]
+quote-style = "double"  # Quote style for strings ("single" or "double")
+indent-style = "space"  # Indent style ("space" or "tab")
+docstring-code-format = true  # How to format code blocks embedded in docstrings
+[tool.ruff.lint]
+fixable = ["ALL"]
+unfixable = []                    # Allow Ruff to auto-fix what it can
+mccabe.max-complexity = 15        # Prevent structural bloat, path-count limit for functions, ruff default=10
+pycodestyle.max-doc-length = 120  # Enforce W505 for comments and docstrings
+pycodestyle.ignore-overlong-task-comments = true  # Let TODO-style tracker lines exceed max doc length
+pydocstyle.convention = "google"  # Interpret Args/Returns/Raises sections as Google-style docstrings
+pydoclint.ignore-one-line-docstrings = true       # Allow obvious one-line docstrings light
+select = [
+    "A",       # flake8-builtins (prevents shadowing Python builtins)
+    "ARG",     # flake8-unused-arguments (dead params and fake extension points)
+    "ASYNC",   # flake8-async (catches blocks/misuse in async frameworks)
+    "B",       # flake8-bugbear (catches common backend design flaws)
+    "BLE",     # flake8-blind-except (blocks quiet 'except Exception: pass')
+    "C",       # C-prefixed rules, including mccabe and comprehensions
+    "C4",      # flake8-comprehensions (.e.g unnecessary list comprehensions)
+    "C90",     # Enables McCabe cyclomatic complexity checks
+    "COM",     # flake8-commas. Trailing comma added.
+    "D102",    # No missing docstring in public method
+    "D103",    # No missing docstring in public function
+    "D202",    # No blank line between a function docstring and the function body
+    "D300",    # Use """ triple quotes for docstrings """
+    "D417",    # No missing arg description in docstring for {definition}: {name}
+    "D419",    # No empty docstrings
+    "DOC",     # Global. Validates parameter & return documentation
+    "DOC102",  # Redundancy of "DOC". Documented parameter {id} must be in the function's signature
+    "DOC201",  # Redundancy of "DOC". Structured docstrings must include Returns when code returns.
+    "DOC501",  # Redundancy of "DOC". Raised exception {id} missing from docstring
+    "DTZ",     # flake8-datetimez (forbid naive datetime usage)
+    "E",       # pycodestyle: Catches objective syntax rule violations
+    "EM",      # flake8-errmsg (keep exception messages clean and reusable)
+    "ERA",     # Catches commented-out code bloat
+    "F",       # Pyflakes (unused imports, undefined variables)
+    "FLY",     # Converts .format() and % string into modern f-string
+    "FURB",    # Modern simplifications, some loop/set mutation patterns
+    "G",       # flake8-logging-format (safe logging format conventions)
+    "I",       # isort (clean, predictable import sorting)
+    "ISC",     # flake8-implicit-str-concat, Catch missing commas in lists
+    "LOG",     # flake8-logging (logging misuse and avoidable root logger use)
+    "N",       # Enable pep8-naming rules globally
+    "PERF",    # Avoids inefficient loop/allocation patterns
+    "PGH",     # pygrep-hooks (blanket suppression hygiene) Bans generic # noqa or # type: ignore
+    "PIE",     # flake8-pie, removes unnecessary code constructs
+    "PLC",     # Pylint convention rules
+    "PLE",     # Pylint error rules
+    "PLR",     # Pylint Refactor (controls complexity and argument bloat)
+    "PLW",     # Pylint warning rules
+    "PT",      # flake8-pytest-style (idiomatic pytest without docstring noise) e.g. pytest.raise not try/except
+    "PTH",     # flake8-use-pathlib (prefer Path over error-prone os/path string handling)
+    "PYI",     # Prevents bad practices in files that handle interfaces/architecture
+    "RET",     # Cleaner return flow, fewer lazy else chains.
+    "RSE",     # flake8-raise (clean raise statements)
+    "RUF",     # Ruff-specific rules
+    "S",       # flake8-bandit (security checks: SQLi, hardcoded credentials)
+    "SIM",     # flake8-simplify (prefer simpler control flow and syntax)
+    "SLF001",  # No start with single underscore outside defining module
+    "T10",     # flake8-debugger (forbid breakpoint/debugger calls)
+    "T20",     # flake8-print (forbids print statements; forces logging)
+    "TID",     # flake8-tidy-imports (forces clean absolute imports)
+    "TRY",     # tryceratops (exception handling hygiene)
+    "UP",      # Modern Python idioms
+    "W",       # Catches stylistic choices that harm readability
+]
+ignore = [
+    "COM812",   # Let Ruff format own trailing commas to avoid formatter conflicts, missing-trailing-comma
+    "PLR2004",  # Allow 'magic values" (unnamed numbers), start-process-with-partial-path
+    "S607",     # Allow resolving git/uv from PATH, start-process-with-partial-path
+    "RUF201"    # Do not complain no string rule-codes-in-selectors (too new since v.0.15.22)
+]
+[tool.ruff.lint.pylint]      # Prevent unreadable complexity and code
+max-nested-blocks = 5        # Stop indentation madness
+max-positional-args = 5      # Max total params, prevents big initializers, limits positional params can pass
+max-args = 5                 # Prevents big initializers, Limits all named parameters in function def (* uncounted)
+max-public-methods = 20      # Cap public methods per class
+max-statements = 50          # Cap executable statements per function/method
+max-branches = 12            # Cap branching paths per function/method; long if/elif chains are banned
+max-returns = 6              # Cap return exits per function/method
+max-locals = 15              # Cap local variable sprawl per function/method
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"  # Enforce absolute imports
+# banned-api."typing.cast".msg = "Do not use cast(); fix the type at the boundary instead."   EXAMPLE
+# banned-api."re".msg = "Regex is slow. Use Python built-in string manipulation operations."  EXAMPLE
+
+[tool.ruff.lint.per-file-ignores]
+"**/__init__.py" = ["D104"]  # __init__.py Package marker files not required to have package docstrings
+"**/tests/**/*.py" = [
+    "D100",   # Test modules do not need noisy docstrings, undocumented-public-module
+    "D101",   # Test classes do not need noisy docstrings, undocumented-public-class
+    "D102",   # Test helper methods do not need noisy docstrings, undocumented-public-method
+    "D103",   # Test functions describe behavior through test names, undocumented-public-function
+    "D104",   # Test package boundaries do not need package docstrings, undocumented-public-package
+    "DOC201", # Tests explain behavior through assertions,  docstring-missing-returns
+    "S101",   # Allow 'assert' statements (needed for pytest)
+    "PLR0915",  # Tests may need larger setup functions
+]

harness/tests/mutation/mutmut-cicd-stats.json

@@ -0,0 +1,11 @@
+{
+  "killed": 132,
+  "survived": 0,
+  "total": 133,
+  "no_tests": 0,
+  "skipped": 0,
+  "suspicious": 0,
+  "timeout": 1,
+  "check_was_interrupted_by_user": 0,
+  "segfault": 0
+}

harness/tests/mutation/test_check_mutmut.py

@@ -0,0 +1,135 @@
+"""Tests for the mutmut CI report checker."""
+
+from __future__ import annotations
+
+import json
+import runpy
+from pathlib import Path
+
+import pytest
+from click import unstyle
+
+from mutation import check_mutmut
+from mutation.check_mutmut import MINIMUM_MUTATION_SCORE, analyze_mutmut_report_passed
+
+
+def test_module_output_from_mutation_directory_is_exact(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The standalone module finds the repository report and exits without a traceback."""
+    module_dir = tmp_path / "mutation"
+    module_dir.mkdir()
+    checker = Path(__file__).parents[2] / "mutation" / "check_mutmut.py"
+    report = tmp_path / "mutants" / "mutmut-cicd-stats.json"
+    report.parent.mkdir()
+    report.write_text(
+        json.dumps({"killed": 1, "survived": 1, "total": 2, "skipped": 0, "timeout": 0}), encoding="utf-8"
+    )
+
+    monkeypatch.chdir(tmp_path)
+    with pytest.raises(SystemExit) as exc_info:
+        runpy.run_path(str(checker), run_name="__main__")
+
+    assert exc_info.value.code == 1
+    output = " ".join(unstyle(capsys.readouterr().out).split())
+    leading_rule, title, results = output.partition("MUTMUT MUTATION RESULTS")
+    assert title == "MUTMUT MUTATION RESULTS"
+    assert not leading_rule.strip("─ ")
+    assert results.strip("─ ") == ("killed 1 survived 1 total 2 skipped 0 timeout 0 Mutation Score: 50.0")
+
+    monkeypatch.chdir(module_dir)
+    monkeypatch.setattr(check_mutmut, "__file__", str(module_dir / "check_mutmut.py"))
+    assert check_mutmut.update_mutation_score() == pytest.approx(50.0)
+    badge = json.loads((tmp_path / "mutation-score.json").read_text(encoding="utf-8"))
+    assert badge["message"] == "50.0%"
+
+
+def test_report_with_timeout_passes_and_renders(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A timeout counts as detected and remains visible in the report."""
+    report = tmp_path / "mutants" / "mutmut-cicd-stats.json"
+    report.parent.mkdir()
+    report.write_text(Path(__file__).with_name("mutmut-cicd-stats.json").read_text(encoding="utf-8"), encoding="utf-8")
+
+    checker = Path(__file__).parents[2] / "mutation" / "check_mutmut.py"
+    monkeypatch.chdir(tmp_path)
+    runpy.run_path(str(checker), run_name="__main__")
+
+    output = " ".join(unstyle(capsys.readouterr().out).split())
+    assert "MUTMUT MUTATION RESULTS" in output
+    assert "timeout 1" in output
+    assert "Mutation Score: 100.0" in output
+    assert json.loads((tmp_path / "mutation-score.json").read_text(encoding="utf-8")) == {
+        "schemaVersion": 1,
+        "label": "mutation",
+        "message": "100.0%",
+        "color": "#177445",
+    }
+
+
+def test_report_checker_entry_point_exits_zero_and_prints_score(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The script entry point reads the default report path and exposes pass/fail through the process exit."""
+    report = tmp_path / "mutants" / "mutmut-cicd-stats.json"
+    report.parent.mkdir()
+    report.write_text(Path(__file__).with_name("mutmut-cicd-stats.json").read_text(encoding="utf-8"), encoding="utf-8")
+
+    checker = Path(__file__).parents[2] / "mutation" / "check_mutmut.py"
+    monkeypatch.chdir(tmp_path)
+    runpy.run_path(str(checker), run_name="__main__")
+
+    output = " ".join(unstyle(capsys.readouterr().out).split())
+    assert "MUTMUT MUTATION RESULTS" in output
+    assert "Mutation Score: 100.0" in output
+
+
+def test_report_enforces_threshold(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    """Mutation scores at or above the minimum pass, while lower scores fail."""
+    data = json.loads(Path(__file__).with_name("mutmut-cicd-stats.json").read_text(encoding="utf-8"))
+    data["survived"] = 1
+    data["total"] += 1
+    report = tmp_path / "mutmut-cicd-stats.json"
+    report.write_text(json.dumps(data), encoding="utf-8")
+    mutation_score = analyze_mutmut_report_passed(str(report))
+    assert MINIMUM_MUTATION_SCORE <= mutation_score < 100.0
+
+    passing_report = {"killed": MINIMUM_MUTATION_SCORE, "timeout": 0, "total": 100, "skipped": 0}
+    report.write_text(json.dumps(passing_report), encoding="utf-8")
+    assert analyze_mutmut_report_passed(str(report)) == pytest.approx(MINIMUM_MUTATION_SCORE)
+
+    failing_score = MINIMUM_MUTATION_SCORE - 1
+    report.write_text(json.dumps({"killed": failing_score, "timeout": 0, "total": 100, "skipped": 0}), encoding="utf-8")
+    assert analyze_mutmut_report_passed(str(report)) == pytest.approx(failing_score)
+    output = " ".join(unstyle(capsys.readouterr().out).split())
+    assert f"Mutation Score: {failing_score}" in output
+
+
+def test_entry_point_fails_below_threshold(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """The script entry point exits 1 when the score is below the minimum."""
+    report = tmp_path / "mutants" / "mutmut-cicd-stats.json"
+    report.parent.mkdir()
+    report.write_text(json.dumps({"killed": 0, "timeout": 0, "total": 1, "skipped": 0}), encoding="utf-8")
+
+    checker = Path(__file__).parents[2] / "mutation" / "check_mutmut.py"
+    monkeypatch.chdir(tmp_path)
+    with pytest.raises(SystemExit) as exc_info:
+        runpy.run_path(str(checker), run_name="__main__")
+
+    assert exc_info.value.code == 1
+
+
+def test_missing_report_returns_zero(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    """A missing export reports the error and returns a zero score."""
+    assert analyze_mutmut_report_passed(str(tmp_path / "missing.json")) == pytest.approx(0.0)
+    assert "Mutmut report not" in capsys.readouterr().out
+
+
+def test_malformed_report_fails(tmp_path: Path) -> None:
+    """Malformed JSON is reported as malformed JSON."""
+    report = tmp_path / "mutmut-cicd-stats.json"
+    report.write_text("{", encoding="utf-8")
+
+    with pytest.raises(json.JSONDecodeError):
+        analyze_mutmut_report_passed(str(report))