Skip to content
Open the dashboard
Documentation

Exceptions that expire: letting a rule be broken without turning it off

Engineering leadsDevelopersSecurity6 min read

The first time a standard blocks a change that was correct, someone will propose turning the rule off. Do not. The right tool is an exception: a committed record that says this rule does not apply to these files, for this reason, approved by this person, until this date. The rule stays on for everyone else, the break is visible instead of silent, and the exception ends on its own.

  • It applies to every file, not the one that needed it.
  • It is invisible: six months later nobody remembers why the rule is off, or that it was ever on.
  • It is permanent by default. Nothing prompts anyone to turn it back on.
  • It is unauditable. A reviewer asking “which rules were in effect on this repository in Q3?” gets a wrong answer.

An override that changes a rule’s severity has the same problems in milder form. Reserve overrides for a rule that is wrong for the repository as a whole, and use exceptions for the places where a correct rule does not apply.

In Groundrule an exception is an entry in .groundrule/exceptions.yaml, committed with the code:

apiVersion: groundrule.dev/v1alpha1
kind: ExceptionList
exceptions:
- id: EX-1042
rule: SEC-001
paths: ["src/legacy/refund/**"]
reason: Legacy refund flow; moves to the gateway in the payments rewrite.
approvedBy: team:payments
expires: "2026-12-31"
Field Required What it does
rule Yes The standard it applies to
paths Yes The files it covers, as globs. Nothing outside them is affected
reason Yes Why the code is right to break the rule. Shown by check, standards and explain
approvedBy No A person or team. Shown in the compliance report
expires Yes The last day it applies, UTC. There are no permanent exceptions

Findings the exception hides are still produced; they are marked suppressed with the exception’s ID in the JSON and SARIF output, so a reviewer can see what was excused and why. The Markdown summary counts them. Overrides and exceptions has every detail, including how a standard can forbid exceptions to itself.

The day after expires, the exception stops applying and the rule fires again on those files. groundrule check says so:

! .groundrule/exceptions.yaml EX-1042 for SEC-001 expired on 2026-12-31 and no longer applies.

Two honest outcomes: the code was fixed, so delete the entry; or it was not, so agree a new date with the approver and change expires. Either way someone looks at it, which is the point.

A connected workspace lists every exception that hid a finding in the period, soonest expiry first: the rule, the expiry date with Expired when it has passed, who approved it, and how many findings it hid in how many runs. The same table is in the CSV an auditor receives. See Compliance report.

This is the difference between “we have standards” and “we can show which standards were in effect, where they did not apply, who said so, and until when”.