Building the rule registry

Stoney’s job is to produce a current, accurate list of the business rules your API actually enforces — and to keep that list honest as your team ships. This page explains what a business rule is in Stoney’s model, where the rules come from, and how the people who own them (typically a product or engineering lead) shape the registry over time.

There is nothing to install in your code and no schema to author. Stoney reads your repositories through the GitHub App you grant it access to. You never write rule definitions by hand — you approve, dismiss, or edit the ones Stoney pulls out.

What counts as a business rule

A business rule is a statement that must be true about your product, phrased in the language a product manager or CEO would actually use. It is not a description of a route.

Business rule: “Orders must have a positive total, per SALES-412.”

Not a business rule: “POST /api/orders returns 200 when given a valid body.”

That distinction is doing real work. The first sentence can be:

• traced to a specific Jira ticket and an engineer
• enforced as a pre-merge check on every PR
• exported as audit evidence for SOC 2 CC8.1
• owned by a person who gets paged when it breaks

The second sentence is a test. Tests are valuable, but they don’t answer “why does this rule exist?” or “who owns it?” or “which customer commitment does it correspond to?”

Stoney’s registry is for the first kind of sentence. Everything else — checks, alerts, forensic reports — runs on top of it.

Where the rules come from

Stoney looks at three signals together — the same three signals an experienced engineer would consult to answer “what does our API actually do today?”:

1. Your code. The route handlers and the validators they invoke. This is the ground truth of what your API enforces in production.
2. Your pull requests. The history of how each handler became what it is. PR titles, descriptions, and diffs explain the why behind the code.
3. Your Jira tickets. The business authorization for each rule. The ticket is what makes “positive totals” a rule and not just a quirk of the code.

The synthesis produces a draft for every rule it finds. Drafts come with provenance: which file the rule lives in, which PR last touched that file, which ticket authorized it, and the engineer most likely to know about it.

Drafts do not enforce anything. A rule has to be approved by a human before it’s used for pre-merge checks, drift alerts, or compliance evidence. That keeps Stoney from making policy decisions you didn’t make.

A good first review

The first time you open the dashboard after setup, expect to see somewhere between 20 and 40 draft rules grouped by domain. The review usually takes a product or engineering lead about ten minutes.

For each draft, you have three options:

• Approve. The rule is real and you want Stoney to watch it. Approved rules drive pre-merge checks, drift alerts, escalations, and compliance evidence.
• Dismiss. The rule isn’t a rule — it’s an artifact of how your code happens to be written today, or a duplicate of another rule, or a guard that exists for performance reasons rather than business reasons. Dismissed rules are remembered so they don’t come back in future syntheses.
• Edit, then approve. The rule is real but its phrasing is awkward, or its authorizing ticket is wrong. Fix it in the inline editor and approve.

Two heuristics for the first pass:

Would your auditor ask about this rule? If yes, approve. If they wouldn’t care, dismiss.

Could a non-engineer say this rule out loud and have it make sense? If yes, approve. If the rule is in API-speak (“handler returns 200”), edit until it sounds like product-speak.

When rules change (and how Stoney keeps up)

Your codebase moves. New PRs land, new tickets get filed, new handlers go in. Stoney’s job is to keep the registry honest without nagging.

On every PR. The pre-merge rule check runs on every PR opened against a repo Stoney watches. If the change implies a new rule the registry doesn’t yet have, the check surfaces a “new rule implied” finding so reviewers can decide whether to adopt it.

On a schedule. Periodically, Stoney re-runs synthesis to pick up rules the daily PR flow missed. You can also trigger a manual re-run from the dashboard when you’ve done something material — e.g. shipped a big new domain, or just connected Jira for the first time.

When you intervene. Editing a rule’s wording or its authorizing ticket sticks. Future syntheses respect your edits and won’t overwrite them.

Who should own this in your org

The rule registry is most powerful when one person on your team treats it as part of their job, the way someone owns the changelog or the docs. Different orgs put this in different places:

• At a 10-person startup, the CTO or technical co-founder usually owns the registry directly. The cost is ten minutes a week to triage new draft rules.
• At a growth-stage company, an engineering lead or staff engineer typically owns it, with PMs reviewing the rules in their domain.
• At a more mature org, the platform team owns the registry overall, but each product team owns the rules in its own domain.

The wrong person to own this is the on-call rotation. Drift escalation flows through on-call. The registry itself is a curation task — it benefits from one consistent voice.

Common questions

Do I need Jira for this to work? No. Rules still get synthesized from code + PRs alone — you just lose the “authorizing ticket” column. The pre-merge check, drift forensics, and Slack escalation all work without Jira. Linear support is on the roadmap; if you want it sooner, let us know at hello@stoneydev.com.

What if a rule looks wrong? The most common cause is a missing or unspecific product description. Go to Settings → Product description and add one sentence about what your API does, then re-run synthesis. If a particular rule keeps coming back miswired, email founder@stoneydev.com — bad-output examples are the fastest signal we have for tuning the synthesis prompt.

Does Stoney see my source code? Yes, in transit. The synthesis pipeline reads your route handlers via the GitHub API. We do not persist your source. What we store is the derived rule registry, the forensic reports, and the audit log. See Compliance and security for the full data-handling story.

How big a codebase does this work on? From single-repo monoliths up to ~15 services. Past that, contact us — we have customers running multi-repo configurations and can help structure the registry so it stays useful at scale.

Next

Once your registry is approved, the rest of Stoney turns on automatically. The next docs page covers what reviewers see when a PR could break a rule: Pre-merge rule check.