Merge Gate Checks

Two mechanical checks on whether a change can actually be MAINTAINED by someone other than its author.

THE PAIN, MEASURED. r/cscareerquestions, 508 points: "Two years into AI coding tools the actual harm isn't job displacement, it's that mid-level engineers can no longer explain what they built to the person who has to maintain it." r/ExperiencedDevs, 296 points and 251 comments: "What do you do when a developer submits AI generated code they clearly don't understand?"

WHAT THIS DOES NOT DO, and the boundary is the product. It does NOT judge whether an author understands their code. That is unmeasurable, and two of the four checks originally proposed were CUT for exactly that reason — both required deciding whether a human's stated reason was adequate, which no regex fixes. Only the mechanical pair survived.

CHECK B — THE SNAPSHOT REVIEW GATE, and it is the stronger of the two. A snapshot test regenerated whenever it fails asserts nothing at all: it stays green forever and reports success the whole time. This check passes only when a snapshot API is used, the .snap file is git-tracked, AND the runner is in its enforced mode.

THE DETAIL THAT DECIDES WHETHER IT IS SAFE TO RUN: the "disabled" branch keys off the PRESENCE of override flags (-u, --update, --update-snapshot, --updateSnapshot, --ci=false), never the ABSENCE of an explicit --ci flag. Most CI providers set CI=true automatically, so keying on absence would FAIL correctly-configured pipelines — a false accusation about someone's repository, which is the worst error this package could make. Measured against vitest 4.1.7's own installed CLI.

CHECK A — ISSUE-REFERENCE PRESENCE, and it is honestly the weaker one. It returns PASS/FAIL only when the repository has ITSELF declared a convention, and SKIP when none exists. It never invents a universal rule about how commits should reference issues. Its justification rests on structural analogy to commitlint's references-empty rule rather than on a built-and-run artifact the way Check B does, and the README says so.

VERIFIED: 57 tests, plus evidence/measure.mjs which runs real vitest invocations across five configurations and checks 16 assertions — 16 pass, 0 fail.

DELIVERY: free, signed download of a hash-verified tarball, immediately.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function checkIssueReference(commitMessage: string, convention: IssueReferenceConvention | null): IssueReferenceVerdict;
  export function checkIssueReferences(commitMessages: readonly string[], convention: IssueReferenceConvention | null): IssueReferenceVerdict;
  export function classifyAssertions(sourceText: string): AssertionClassification;
  export function checkSnapshotReviewGate(input: SnapshotGateInput): SnapshotGateVerdict;

  export type IssueReferenceStatus = "PASS" | "FAIL" | "SKIP";
  export type SnapshotGateStatus = "PASS" | "FAIL" | "NOT_APPLICABLE";