mergeproof 0.2.0__py3-none-any.whl

mergeproof/__init__.py

@@ -0,0 +1,32 @@
+"""Evidence gates for pull requests.
+
+A policy file declares what a change must prove before it merges. The same
+policy is enforced in CI, explained to contributors and coding agents, and
+served over MCP.
+"""
+
+from mergeproof.checks.base import Check
+from mergeproof.context import ChangedFile, CheckRun, Comment, Context
+from mergeproof.policy import Policy, PolicyError, Requirement, Rule, Severity
+from mergeproof.report import Outcome, Report, Status
+from mergeproof.verifiers.base import Verifier
+
+__version__ = "0.2.0"  # x-release-please-version
+
+__all__ = [
+    "ChangedFile",
+    "Check",
+    "CheckRun",
+    "Comment",
+    "Context",
+    "Outcome",
+    "Policy",
+    "PolicyError",
+    "Report",
+    "Requirement",
+    "Rule",
+    "Severity",
+    "Status",
+    "Verifier",
+    "__version__",
+]

mergeproof/__main__.py

@@ -0,0 +1,4 @@
+from mergeproof.cli import main
+
+if __name__ == "__main__":
+    main()

mergeproof/checks/__init__.py

@@ -0,0 +1,4 @@
+from mergeproof.checks.base import Check
+from mergeproof.checks.registry import Registry, load_registry
+
+__all__ = ["Check", "Registry", "load_registry"]

mergeproof/checks/agent_verdict.py

@@ -0,0 +1,88 @@
+"""A structured verdict posted by an automated reviewer.
+
+LLM reviewers are welcome as witnesses, not as the gate. They post a fenced
+``verdict`` block; this check reads it, restricts who may post it, binds it
+to the head commit, and turns it into an ordinary requirement next to the
+deterministic ones::
+
+    ```verdict
+    check: trace-review
+    verdict: pass
+    head: b3ca7be
+    confidence: 0.9
+    summary: the after-run shows the corrected output; the before-run does not.
+    ```
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from mergeproof import evidence
+from mergeproof.checks.base import Check, fail, ok, pending
+from mergeproof.context import Context
+from mergeproof.report import Outcome
+
+
+class AgentVerdict(Check):
+    id = "agent.verdict"
+    description = "An allowed automated reviewer posted a verdict block for the named check."
+    needs_github = True
+
+    class Params(BaseModel):
+        model_config = ConfigDict(extra="forbid")
+
+        name: str = Field(description="Value of `check:` inside the verdict block")
+        authors: list[str] = Field(
+            default_factory=list, description="Logins allowed to post it, e.g. github-actions[bot]"
+        )
+        bind_to_head: bool = True
+        min_confidence: float = Field(default=0.0, ge=0.0, le=1.0)
+        block: str = "verdict"
+
+    def run(self, ctx: Context, params: Params, files: list[str]) -> Outcome:
+        if not ctx.online:
+            return pending(f"the `{params.name}` verdict is only visible in GitHub mode")
+        latest: dict[str, Any] | None = None
+        latest_at = ""
+        rejected: list[str] = []
+        for comment in ctx.comments:
+            block = evidence.parse(comment.body, params.block)
+            if not block.found or block.get("check") != params.name:
+                continue
+            if params.authors and comment.author not in params.authors:
+                rejected.append(f"{comment.author}: not an allowed verdict author")
+                continue
+            head = str(block.get("head", ""))[:7]
+            if params.bind_to_head and ctx.head_short and head != ctx.head_short:
+                rejected.append(
+                    f"{comment.author}: verdict is for {head or 'an unknown commit'}, head is {ctx.head_short}"
+                )
+                continue
+            if comment.created_at >= latest_at:
+                latest, latest_at = block.data, comment.created_at
+        if latest is None:
+            return pending(f"no `{params.name}` verdict for {ctx.head_short or 'this commit'}", details=rejected)
+        verdict = str(latest.get("verdict", "")).lower()
+        confidence = float(latest.get("confidence") or 1.0)
+        summary = str(latest.get("summary", "")).strip()
+        if verdict != "pass":
+            return fail(
+                f"verdict {verdict or 'missing'}: {summary}", data=latest, fix="Address the findings and push again."
+            )
+        if confidence < params.min_confidence:
+            return pending(
+                f"passed with confidence {confidence:.2f}, below {params.min_confidence:.2f}: {summary}", data=latest
+            )
+        return ok(f"verdict pass ({confidence:.2f}): {summary}", data=latest)
+
+    def explain(self, params: Params) -> str:
+        who = ", ".join(f"`{a}`" for a in params.authors) or "an automated reviewer"
+        text = f"{who} posts a ```{params.block} block with `check: {params.name}` and `verdict: pass`"
+        if params.bind_to_head:
+            text += " for the current head sha"
+        if params.min_confidence:
+            text += f" with confidence of at least {params.min_confidence}"
+        return text + "."

mergeproof/checks/base.py

@@ -0,0 +1,71 @@
+"""Base class for checks.
+
+A check answers one question about a pull request. It declares its
+parameters as a pydantic model, runs against a :class:`Context`, and returns
+an :class:`Outcome`. Third-party checks register under the
+``mergeproof.checks`` entry-point group.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, ClassVar
+
+from pydantic import BaseModel, ConfigDict
+
+from mergeproof.context import Context
+from mergeproof.report import Outcome, Status
+
+
+class Check(ABC):
+    id: ClassVar[str]
+    description: ClassVar[str] = ""
+    needs_github: ClassVar[bool] = False
+
+    class Params(BaseModel):
+        model_config = ConfigDict(extra="forbid")
+
+    def parse_params(self, raw: dict[str, Any]) -> BaseModel:
+        return self.Params(**raw)
+
+    @abstractmethod
+    def run(self, ctx: Context, params: Any, files: list[str]) -> Outcome:
+        """*files* are the changed paths that made the enclosing rule apply."""
+
+    def explain(self, params: Any) -> str:
+        """One sentence a contributor or agent can act on."""
+        return self.description
+
+    def evidence_template(self, params: Any) -> dict[str, Any]:
+        """Keys this check expects in the evidence block, with placeholder values."""
+        return {}
+
+
+def ok(summary: str, **kw: Any) -> Outcome:
+    return Outcome(status=Status.PASS, summary=summary, **kw)
+
+
+def fail(summary: str, fix: str | None = None, **kw: Any) -> Outcome:
+    return Outcome(status=Status.FAIL, summary=summary, fix=fix, **kw)
+
+
+def warn(summary: str, fix: str | None = None, **kw: Any) -> Outcome:
+    return Outcome(status=Status.WARN, summary=summary, fix=fix, **kw)
+
+
+def pending(summary: str, fix: str | None = None, **kw: Any) -> Outcome:
+    return Outcome(status=Status.PENDING, summary=summary, fix=fix, **kw)
+
+
+def skip(summary: str, **kw: Any) -> Outcome:
+    return Outcome(status=Status.SKIP, summary=summary, **kw)
+
+
+def error(summary: str, **kw: Any) -> Outcome:
+    return Outcome(status=Status.ERROR, summary=summary, **kw)
+
+
+def plural(count: int, noun: str, plural_form: str | None = None) -> str:
+    """``plural(1, "run")`` is ``"1 run"``; ``plural(3, "run")`` is ``"3 runs"``."""
+    word = noun if count == 1 else (plural_form or noun + "s")
+    return f"{count} {word}"

mergeproof/checks/body.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from mergeproof.checks.base import Check, fail, ok
+from mergeproof.context import Context
+from mergeproof.report import Outcome
+
+
+class Body(Check):
+    id = "pr.body"
+    description = "The PR description has the required sections, matches a regex, or meets a minimum length."
+
+    class Params(BaseModel):
+        model_config = ConfigDict(extra="forbid")
+
+        sections: list[str] = Field(default_factory=list, description="Markdown headings that must exist")
+        matches: str | None = None
+        min_length: int = 0
+
+    def run(self, ctx: Context, params: Params, files: list[str]) -> Outcome:
+        body = ctx.body or ""
+        problems = [
+            f"missing section `## {section}`"
+            for section in params.sections
+            if not re.search(rf"^#{{1,6}}\s*{re.escape(section)}\b", body, re.I | re.M)
+        ]
+        if params.matches and not re.search(params.matches, body, re.S):
+            problems.append(f"description does not match `{params.matches}`")
+        if len(body.strip()) < params.min_length:
+            problems.append(f"description shorter than {params.min_length} characters")
+        if problems:
+            return fail("; ".join(problems), fix=self.explain(params))
+        return ok("description ok")
+
+    def explain(self, params: Params) -> str:
+        parts = []
+        if params.sections:
+            parts.append("sections " + ", ".join(f"`## {s}`" for s in params.sections))
+        if params.matches:
+            parts.append(f"text matching `{params.matches}`")
+        if params.min_length:
+            parts.append(f"at least {params.min_length} characters")
+        return "A PR description with " + "; ".join(parts) + "."

mergeproof/checks/ci_job.py

@@ -0,0 +1,74 @@
+"""A named check run on the head commit succeeded.
+
+A commit can carry several check runs with the same name: re-runs, and runs a
+concurrency group cancelled when a newer push arrived. Only the newest run per
+name says anything about the commit, so that is the one that counts.
+"""
+
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from mergeproof.checks.base import Check, fail, ok, pending, plural
+from mergeproof.context import CheckRun, Context
+from mergeproof.report import Outcome
+
+
+def newest_per_name(runs: list[CheckRun]) -> list[CheckRun]:
+    latest: dict[str, CheckRun] = {}
+    for run in runs:
+        current = latest.get(run.name)
+        if current is None or run.started_at > current.started_at:
+            latest[run.name] = run
+    return list(latest.values())
+
+
+class CiJobPassed(Check):
+    id = "ci.job_passed"
+    description = "A GitHub check run on the head commit completed successfully."
+    needs_github = True
+
+    class Params(BaseModel):
+        model_config = ConfigDict(extra="forbid")
+
+        name: str = Field(description="Check run name, or a regex when `regex` is true")
+        regex: bool = False
+        min_matches: int = Field(default=1, description="How many matching runs must succeed")
+        missing: str = Field(default="pending", pattern="^(pending|fail)$", description="Status when no run exists yet")
+
+    def run(self, ctx: Context, params: Params, files: list[str]) -> Outcome:
+        if not ctx.online:
+            return pending(f"CI status for `{params.name}` is only visible in GitHub mode")
+        if params.regex:
+            wanted = re.compile(params.name)
+            runs = [r for r in ctx.check_runs if wanted.search(r.name)]
+        else:
+            runs = [r for r in ctx.check_runs if r.name == params.name]
+        runs = newest_per_name(runs)
+        if not runs:
+            message = (
+                f"no check run matching `{params.name}` yet"
+                if params.regex
+                else f"no check run named `{params.name}` yet"
+            )
+            return fail(message) if params.missing == "fail" else pending(message)
+        failed = [r for r in runs if r.status == "completed" and r.conclusion not in ("success", "skipped", "neutral")]
+        running = [r for r in runs if r.status != "completed"]
+        succeeded = [r for r in runs if r.status == "completed" and r.conclusion == "success"]
+        if failed:
+            return fail(
+                f"{plural(len(failed), 'run')} failed",
+                details=[f"{r.name}: {r.conclusion}" + (f" {r.url}" if r.url else "") for r in failed],
+                fix="Make the job green; the gate re-evaluates on the next run.",
+            )
+        if running:
+            return pending(f"{plural(len(running), 'run')} still in progress", details=[r.name for r in running])
+        if len(succeeded) < params.min_matches:
+            return fail(f"{plural(len(succeeded), 'successful run')}, need {params.min_matches}")
+        return ok(f"{plural(len(succeeded), 'run')} succeeded", details=[r.name for r in succeeded][:10])
+
+    def explain(self, params: Params) -> str:
+        how = "matching" if params.regex else "named"
+        return f"CI check run {how} `{params.name}` is green on the head commit."

mergeproof/checks/evidence_field.py

@@ -0,0 +1,81 @@
+"""A key in the evidence block is present and has an acceptable value."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from mergeproof.checks.base import Check, fail, ok
+from mergeproof.context import Context
+from mergeproof.report import Outcome
+
+
+class EvidenceField(Check):
+    id = "evidence.field"
+    description = "A field in the PR's evidence block is present and valid."
+
+    class Params(BaseModel):
+        model_config = ConfigDict(extra="forbid")
+
+        key: str = Field(description="Dotted path inside the evidence block, e.g. `environment` or `image.tag`")
+        equals: Any | None = None
+        one_of: list[Any] | None = None
+        matches: str | None = Field(default=None, description="Regex a string value must match")
+        min_items: int | None = Field(default=None, description="Minimum length for a list value")
+        example: Any | None = Field(default=None, description="Placeholder shown in the evidence template")
+        block: str = "evidence"
+
+    def run(self, ctx: Context, params: Params, files: list[str]) -> Outcome:
+        ev = ctx.evidence(params.block)
+        if ev.errors:
+            return fail("evidence block could not be parsed", details=ev.errors, fix=self.fix(params))
+        if not ev.has(params.key):
+            why = f"no `{params.block}` block in the PR description" if not ev.found else f"`{params.key}` is missing"
+            return fail(why, fix=self.fix(params))
+        value = ev.get(params.key)
+        if params.equals is not None and value != params.equals:
+            return fail(f"`{params.key}` is {value!r}, expected {params.equals!r}", fix=self.fix(params))
+        if params.one_of is not None and value not in params.one_of:
+            return fail(f"`{params.key}` is {value!r}, expected one of {params.one_of}", fix=self.fix(params))
+        if params.matches is not None and (not isinstance(value, str) or not re.search(params.matches, value)):
+            return fail(f"`{params.key}` does not match `{params.matches}`", fix=self.fix(params))
+        if params.min_items is not None and (not isinstance(value, list) or len(value) < params.min_items):
+            return fail(f"`{params.key}` needs at least {params.min_items} item(s)", fix=self.fix(params))
+        shown = value if isinstance(value, str | int | float | bool) else f"{type(value).__name__}[{len(value)}]"
+        return ok(f"`{params.key}` = {shown}")
+
+    def fix(self, params: Params) -> str:
+        return f"Add `{params.key}` to the `{params.block}` block in the PR description. {self.explain(params)}"
+
+    def explain(self, params: Params) -> str:
+        wants = [f"`{params.key}` present"]
+        if params.equals is not None:
+            wants.append(f"equal to `{params.equals}`")
+        if params.one_of:
+            wants.append("one of " + ", ".join(f"`{v}`" for v in params.one_of))
+        if params.matches:
+            wants.append(f"matching `{params.matches}`")
+        if params.min_items:
+            wants.append(f"with at least {params.min_items} item(s)")
+        return " and ".join(wants) + "."
+
+    def evidence_template(self, params: Params) -> dict[str, Any]:
+        if params.example is not None:
+            leaf: Any = params.example
+        elif params.equals is not None:
+            leaf = params.equals
+        elif params.one_of:
+            leaf = params.one_of[0]
+        elif params.min_items:
+            leaf = ["<item>"]
+        else:
+            leaf = "<value>"
+        template: dict[str, Any] = {}
+        node = template
+        *parents, last = params.key.split(".")
+        for part in parents:
+            node = node.setdefault(part, {})
+        node[last] = leaf
+        return template

mergeproof/checks/evidence_links.py

@@ -0,0 +1,128 @@
+"""Before/after link pairs proving a behaviour change on a live system.
+
+The links can point anywhere: a tracing backend, a dashboard, a CI run, a
+screenshot bucket. ``pattern`` decides what counts as a valid link and may
+capture named groups; ``verify`` names a verifier that resolves each link.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from mergeproof.checks.base import Check, error, fail, ok, plural
+from mergeproof.context import Context
+from mergeproof.report import Outcome
+from mergeproof.verifiers import UnknownVerifier, Verifier, load_verifier
+
+ANY_URL = r"^https?://\S+$"
+
+
+class EvidenceLinks(Check):
+    id = "evidence.links"
+    description = "The evidence block lists before/after link pairs, optionally verified against their source."
+
+    class Params(BaseModel):
+        model_config = ConfigDict(extra="forbid")
+
+        key: str = "links"
+        min_pairs: int = 1
+        pattern: str = Field(
+            default=ANY_URL, description="Regex a link must match; named groups are passed to the verifier"
+        )
+        require_before: bool = True
+        distinct: bool = Field(default=True, description="`before` and `after` must differ")
+        verify: str | None = Field(default=None, description="Verifier name: `http` or one provided by a plugin")
+        verify_options: dict[str, Any] = Field(default_factory=dict)
+        example: str = Field(default="https://<host>/<path-to-run>", description="Placeholder in the evidence template")
+        block: str = "evidence"
+
+    verifier: Verifier | None = None
+
+    def run(self, ctx: Context, params: Params, files: list[str]) -> Outcome:
+        ev = ctx.evidence(params.block)
+        if ev.errors:
+            return fail("evidence block could not be parsed", details=ev.errors, fix=self.fix(params))
+        items = ev.get(params.key)
+        if not isinstance(items, list) or not items:
+            return fail(f"no `{params.key}` list in the evidence block", fix=self.fix(params))
+
+        regex = re.compile(params.pattern)
+        problems: list[str] = []
+        pairs: list[dict[str, str]] = []
+        for index, item in enumerate(items, 1):
+            if not isinstance(item, dict):
+                problems.append(f"item {index}: expected a mapping with `before` and `after`")
+                continue
+            pair: dict[str, str] = {}
+            for side in ("before", "after"):
+                url = item.get(side)
+                if not url:
+                    if side == "after" or params.require_before:
+                        problems.append(f"item {index}: missing `{side}`")
+                    continue
+                if not regex.match(str(url)):
+                    problems.append(f"item {index}: `{side}` does not look like an accepted link")
+                    continue
+                pair[side] = str(url)
+            if params.distinct and pair.get("before") and pair.get("before") == pair.get("after"):
+                problems.append(f"item {index}: `before` and `after` are the same link")
+            if "after" in pair and ("before" in pair or not params.require_before):
+                pairs.append(pair)
+        if problems:
+            return fail(f"{plural(len(problems), 'problem')} in `{params.key}`", details=problems, fix=self.fix(params))
+        if len(pairs) < params.min_pairs:
+            return fail(f"{plural(len(pairs), 'valid pair')}, need {params.min_pairs}", fix=self.fix(params))
+
+        if params.verify:
+            unresolved = self.verify_pairs(pairs, regex, params)
+            if unresolved is None:
+                return error(f"verifier {params.verify!r} is not available or failed")
+            if unresolved:
+                return fail("link(s) could not be verified", details=unresolved, fix=self.fix(params))
+            return ok(f"{plural(len(pairs), 'before/after pair')}, all verified", data={"pairs": pairs})
+        return ok(plural(len(pairs), "before/after pair"), data={"pairs": pairs})
+
+    def verify_pairs(self, pairs: list[dict[str, str]], regex: re.Pattern[str], params: Params) -> list[str] | None:
+        """Return the links that did not resolve, or None when the verifier itself is unusable."""
+        verifier = self.verifier
+        if verifier is None:
+            try:
+                verifier = load_verifier(params.verify or "", params.verify_options)
+            except (UnknownVerifier, TypeError, ValueError):
+                return None
+        unresolved: list[str] = []
+        for pair in pairs:
+            for side, url in pair.items():
+                match = regex.match(url)
+                assert match is not None
+                try:
+                    found = verifier.verify(url, match)
+                except Exception as exc:
+                    unresolved.append(f"{side}: {type(exc).__name__} while verifying {url}")
+                    continue
+                if not found:
+                    unresolved.append(f"{side}: not found at {url}")
+        return unresolved
+
+    def fix(self, params: Params) -> str:
+        return (
+            "Capture a link showing the behaviour before the change and one after it; "
+            f"list them as `before`/`after` pairs under `{params.key}` in the evidence block."
+        )
+
+    def explain(self, params: Params) -> str:
+        text = f"At least {params.min_pairs} `before`/`after` link pair(s) under `{params.key}` in the evidence block"
+        if params.pattern != ANY_URL:
+            text += f", each matching `{params.pattern}`"
+        if params.verify:
+            text += f"; links are verified with `{params.verify}`"
+        return text + "."
+
+    def evidence_template(self, params: Params) -> dict[str, Any]:
+        pair = {"before": params.example, "after": params.example}
+        if not params.require_before:
+            pair = {"after": params.example}
+        return {params.key: [{"what": "<what was exercised>", **pair}]}

mergeproof/checks/files.py

@@ -0,0 +1,47 @@
+"""Which files a change must, may, or must not touch."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from mergeproof import patterns
+from mergeproof.checks.base import Check, fail, ok
+from mergeproof.context import Context
+from mergeproof.report import Outcome
+
+
+class FilesChanged(Check):
+    id = "files.changed"
+    description = "The set of changed files satisfies any_of / all_of / none_of globs."
+
+    class Params(BaseModel):
+        model_config = ConfigDict(extra="forbid")
+
+        any_of: list[str] = Field(default_factory=list, description="At least one changed file matches")
+        all_of: list[str] = Field(default_factory=list, description="Every glob matches at least one changed file")
+        none_of: list[str] = Field(default_factory=list, description="No changed file matches")
+
+    def run(self, ctx: Context, params: Params, files: list[str]) -> Outcome:
+        paths = [f.path for f in ctx.files]
+        problems: list[str] = []
+        if params.any_of and not any(patterns.matches_any(params.any_of, p) for p in paths):
+            problems.append("expected a change to " + " or ".join(params.any_of))
+        for glob in params.all_of:
+            if not any(patterns.match(glob, p) for p in paths):
+                problems.append(f"expected a change to {glob}")
+        forbidden = [p for p in paths if patterns.matches_any(params.none_of, p)]
+        if forbidden:
+            problems.append("must not change " + ", ".join(forbidden[:5]))
+        if problems:
+            return fail("; ".join(problems), fix=self.explain(params))
+        return ok("changed files satisfy the rule")
+
+    def explain(self, params: Params) -> str:
+        parts = []
+        if params.any_of:
+            parts.append("change at least one of " + ", ".join(f"`{g}`" for g in params.any_of))
+        if params.all_of:
+            parts.append("change " + " and ".join(f"`{g}`" for g in params.all_of))
+        if params.none_of:
+            parts.append("leave " + ", ".join(f"`{g}`" for g in params.none_of) + " untouched")
+        return "; ".join(parts).capitalize() + "."

mergeproof/checks/human_verified.py

@@ -0,0 +1,65 @@
+"""A human other than the author attests to having checked the evidence.
+
+Agents can write tests and paste links; the one thing they must not do is
+approve their own evidence. By default the attestation is bound to the head
+commit so that a later push invalidates it.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from mergeproof.checks.base import Check, ok, pending
+from mergeproof.context import Context
+from mergeproof.report import Outcome
+
+
+class HumanVerified(Check):
+    id = "review.human_verified"
+    description = "A reviewer other than the author posted the verification phrase after checking the evidence."
+    needs_github = True
+
+    class Params(BaseModel):
+        model_config = ConfigDict(extra="forbid")
+
+        phrase: str = "/verified"
+        allowed_users: list[str] = Field(default_factory=list, description="Empty means any non-author human")
+        exclude_author: bool = True
+        bind_to_head: bool = Field(default=True, description="The comment must contain the 7-character head sha")
+        require_review_state: str | None = Field(default=None, description="For example APPROVED")
+
+    def run(self, ctx: Context, params: Params, files: list[str]) -> Outcome:
+        if not ctx.online:
+            return pending("reviewer verification is only visible in GitHub mode")
+        expected = f"{params.phrase} {ctx.head_short}".strip() if params.bind_to_head else params.phrase
+        rejected: list[str] = []
+        for comment in ctx.comments:
+            if params.phrase not in comment.body:
+                continue
+            if comment.is_bot:
+                rejected.append(f"{comment.author}: bots cannot verify")
+            elif params.exclude_author and comment.author == ctx.author:
+                rejected.append(f"{comment.author}: the author cannot self-verify")
+            elif params.allowed_users and comment.author not in params.allowed_users:
+                rejected.append(f"{comment.author}: not an allowed verifier")
+            elif params.bind_to_head and ctx.head_short and ctx.head_short not in comment.body:
+                rejected.append(f"{comment.author}: verified an older commit, needs `{expected}`")
+            elif params.require_review_state and comment.state != params.require_review_state:
+                rejected.append(f"{comment.author}: must be a {params.require_review_state} review")
+            else:
+                return ok(
+                    f"verified by @{comment.author}",
+                    details=[comment.url] if comment.url else [],
+                    data={"by": comment.author, "at": comment.created_at},
+                )
+        return pending(f"waiting for a reviewer to post `{expected}`", details=rejected, fix=self.explain(params))
+
+    def explain(self, params: Params) -> str:
+        who = (
+            ("one of " + ", ".join(f"@{u}" for u in params.allowed_users))
+            if params.allowed_users
+            else "a reviewer other than the author"
+        )
+        tail = " followed by the 7-character head sha" if params.bind_to_head else ""
+        state = f" as an {params.require_review_state} review" if params.require_review_state else ""
+        return f"After checking the evidence, {who} comments `{params.phrase}`{tail}{state}."