Rules: severity and stage
Every rule has two settings that are often confused. Severity is about the rule: how bad is it when the rule is broken? Stage is about your rollout: how far have you switched the rule on? Think of severity as the fine printed on a speed sign, and stage as whether the camera is off, warning only, or issuing fines.
Severity: how serious a break is
Section titled “Severity: how serious a break is”Severity is written into the rule and rarely changes.
| Severity | Meaning | Example |
|---|---|---|
| Blocker | Must never land | A password in a configuration file (JAVA-008) |
| Warning | Should be fixed, does not block by itself | System.out.println instead of the logger (JAVA-002) |
| Advisory | A suggestion | Prefer java.time over Date (JAVA-012) |
| Info | A note | Import built-ins with the node: prefix (TS-009) |
Stage: how far it is switched on
Section titled “Stage: how far it is switched on”Stage is your decision, in the workspace, and it moves over time.
| Stage | What happens |
|---|---|
| Observe | Checked silently by scans; agents are not told. For a rule you are unsure about. |
| Teach | Written into the agent files. Agents follow it; nothing is checked. Where guidance-only rules stay. |
| Advise | Taught, and checked. Findings are shown everywhere but never fail a check. |
| Enforce | Taught, and checked at the rule’s real severity. A blocker now fails. |
Rules in a repository that uses only the CLI have no stage: they are always taught and checked at their severity.
Try the two together
Section titled “Try the two together”One example, both dials
Section titled “One example, both dials”Take JAVA-008, “No literal secrets in Spring configuration files”, severity Blocker. Someone commits password: hunter2 in application.yml.
- At Advise: the check prints the finding, labelled as a warning, with the file and line. The run passes, CI is green, the agent’s stop hook mentions it and lets the agent finish. Visible, not blocking.
- At Enforce: the same finding prints in red as a blocker. The run fails, CI is red, the stop hook sends the finding back to the agent, which must fix the line before it can stop.
Same rule, same line. The only thing that changed is the stage.
Now take JAVA-002, “Log with the logging framework”, severity Warning, and move it to Enforce. Someone adds System.out.println. The check prints a warning, and the run still passes. A warning never fails a check, at any stage, because checks fail only on blockers by default.
The one combination that stops a merge
Section titled “The one combination that stops a merge”Enforce and Blocker. Everything else informs, warns or teaches. When you preview Enforce on a warning rule, the dashboard says so: raise the severity to Blocker to stop merges.
Passing, findings, guidance
Section titled “Passing, findings, guidance”A scan or a check sorts every rule into one of three results:
- Passing. The rule has a check, the check ran over your files, and found nothing. A statement about your code today.
- With findings. The check found something. Each finding is a rule, a file and a line.
- Guidance. The rule has no check. Agents read it in
AGENTS.md; nothing scans for it.
“Passing” is why the dashboard can say a rule is safe to enforce: switching it to Enforce cannot fail anyone, because there is nothing in the code to fail. The next page on evidence explains that in full.