Pre-merge rule check

The pre-merge rule check is the feature that puts Stoney into your team’s daily workflow. Every time a pull request is opened, updated, or reopened on a repo Stoney watches, Stoney compares the diff against your approved rules and posts an inline GitHub Check that reviewers see next to the code.

This is the wedge. It turns “the rules our API enforces” from a retrospective list into a live guardrail that catches violations before they merge — without slowing reviews down or asking developers to write any new tests, annotations, or YAML.

What reviewers actually see

When a PR opens, a GitHub Check named Stoney · Rule Check appears alongside your other CI checks. Within about ten seconds it resolves to one of three states:

Findings come in three kinds:

• Rule broken — the diff would cause an approved rule to stop being enforced. Example: a guard clause that backs the “positive totals” rule is being removed.
• Rule contradicted — the diff introduces behavior that conflicts with an existing rule. Example: changing a rate limit to a value that disagrees with the documented limit.
• New rule implied — the diff looks like it introduces a new rule the registry doesn’t yet have. Surface only, never blocking. Useful for keeping the registry honest as the product evolves.

What a finding looks like in the review

Reviewers see findings rendered inline in the GitHub Files Changed tab, not buried in a separate UI. A real example:

🚫 Orders can now be created with negative totals

Rule broken — Orders must have positive totals · app/api/orders/route.ts:47

This PR removes the total > 0 guard in the POST handler. Rule SALES-412 requires orders to have positive totals; without this guard, the rule can no longer be enforced.

Suggestion: restore the guard, or update the rule in the Stoney dashboard if this change is intentional.

Every finding includes the rule’s name, the file and line it affects, a plain-English explanation of why the change conflicts with the rule, and (when available) a suggested fix. The reviewer doesn’t need to read documentation to evaluate the finding — the context is in the comment.

Why developers don’t learn to ignore it

The single most common way a check like this dies is by producing false positives. If Stoney cries wolf, developers stop reading the annotations — and once they stop reading, the registry stops mattering.

To keep findings credible, the analyzer is conservative on purpose. It will not flag:

• Refactors, renames, or type tightening
• Formatting, prettier, or lint-only changes
• Comment-only changes
• Changes in adjacent code that don’t touch the rule’s actual execution path
• Behavior that depends on feature flags or environment differences the analyzer can’t verify from the diff

The rule of thumb we hold ourselves to: every finding should be something a senior engineer would nod at on review. If you ever see a finding that fails that test, dismiss it from the rule’s detail page — that signal goes back into the model.

How this fits into a normal review flow

Stoney’s pre-merge check is designed to live alongside, not replace, your existing review process. The intended flow:

1. Author opens a PR.
2. The Stoney check runs alongside your other CI. It usually finishes before a human starts reading.
3. If Stoney finds something, the inline annotation is visible in the Files Changed tab. The reviewer reads the annotation as part of the normal review, the same way they’d read a comment from a colleague.
4. Author either fixes the issue, updates the rule in the Stoney dashboard, or (rarely) marks the finding as a false positive.

The check is non-blocking by default. We don’t require Stoney to be green before merge unless you explicitly mark it as a required check in GitHub branch protection — we’d rather your team adopt Stoney because the findings are useful than because they’re mandatory.

Teams that have had Stoney running for a while often do mark it required, but only after a month or two when they’ve built confidence in the findings. We recommend the same.

When the check is most valuable

The pre-merge check earns its keep in three situations:

During a refactor. Big refactors are the highest-risk type of change — the diff is large, the reviewer is fatigued, and the implicit rules the code enforces are easy to lose. Stoney flags the rule violations specifically, so reviewers don’t have to mentally simulate every code path.

On PRs from new team members. A new hire doesn’t yet know which lines in your codebase are load-bearing rules. The pre-merge check makes that knowledge available at review time — the new hire learns the rule alongside the reviewer.

When AI-generated code lands. AI assistants are confident and verbose. A PR that looks reasonable can quietly remove a rule the AI didn’t know about. Stoney’s job is to know about it.

What the check costs your team

Stoney’s pre-merge analysis is cheap by design. There is:

• Nothing to install in your repository (no GitHub Actions YAML, no secrets, no workflow)
• No new test suite to maintain
• No additional CI minutes consumed on your side — the analysis happens on Stoney’s infrastructure

Annotations land within about ten seconds of a PR opening, well before a human is ready to review. From the team’s perspective, “turning on Stoney” means “new annotations show up in code review.” Nothing else changes.

Plan tier behavior

If your org exceeds its monthly analysis cap on a heavy month, the check pauses gracefully — it still posts a neutral GitHub Check explaining the cap was reached, so reviewers know why they aren’t seeing annotations. The next billing cycle resets it.

Reviewing check history

Every analysis is stored, including its verdict and the full list of findings. Admins can browse historical analyses on the Compliance dashboard; the PR-check table is part of CC8.1 change-management evidence and is exported with the rest of the SOC 2 bundle.

When an auditor asks “show me an example of how you catch unintended changes to API behavior,” a Stoney PR check with a real rule-broken finding is exactly the kind of artifact they’re looking for.

Next

When a rule does break in production despite the pre-merge check — usually because a change landed before the rule was added, or a runtime input bypassed a static guard — Drift forensics takes over.