Skip to content
Open the dashboard
Documentation

Rules: severity and stage

5 min read

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 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 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 itpick a stage and a severity; read what a change that breaks the rule gets
stage · how far it is rolled out
severity · how serious a break is
agent filesListed in AGENTS.md; the agent follows it.
groundrule checkReported as a warning. The run passes.
pull requestGreen, with the finding in the summary.
Visible, not blocking. The usual place for a rule on its way to Enforce.

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.

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.

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.