Rollout stages

Every rule in your rulebook has a stage. The stage says how far the rule has been rolled out: whether coding agents are told about it, and whether groundrule check reports or fails on it. This page explains each stage, what fails a check at each combination of stage and severity, and how to move a rule from new to enforced without surprising anyone.

Stage and severity are separate settings:

• Severity says how serious a violation is: blocker, warning, advisory, or info.
• Stage says how far the rule has been rolled out: Observe, Teach, Advise, or Enforce.

The four stages

The stages go from least to most strict. The dashboard shows a one-line hint for each:

Stage	Hint in the dashboard
Observe	“Checked silently; results are only recorded.”
Teach	“Delivered to coding agents; checks run silently.”
Advise	“Findings are shown but never block a merge.”
Enforce	“Findings count at the standard’s severity.”

What each stage does, everywhere a rule can show up:

	Observe	Teach	Advise	Enforce
Agent files (groundrule sync writes AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions)	Left out	Included	Included	Included
MCP server (list_standards for coding agents)	Not listed	Listed as “teach: guidance only”	Listed as “advise: findings warn, never fail”	Listed as “enforce”
groundrule standards	Not listed	Listed, with teach	Listed, with advise	Listed, with enforce
groundrule check (laptop, pre-commit, CI)	Doesn’t run	Doesn’t run	Runs. Findings are reported; blockers are reported as warnings.	Runs. Findings count at the rule’s severity.
Scans (groundrule scan --upload) and evidence	Measured	Measured	Measured	Measured

Scans measure every rule with a check at every stage. They also measure catalog rules whose pack is off, and your own drafts. That is how you can see what a rule would flag before it reaches anyone. See Evidence and impact.

Observe

The rule exists only for evidence. Coding agents aren’t told about it, and checks don’t run it. Scans record its results, so you can see in the dashboard whether your repositories already follow it.

Use Observe for a rule you aren’t sure about yet, such as a new check that might be noisy. No catalog rule starts at Observe.

Teach

The rule is written into every coding agent’s instructions on the next groundrule sync. Agents follow it while they write code. groundrule check doesn’t run it, so nobody gets findings yet.

Teach is where most rules without a check stay: guidance such as “Ask before destructive or irreversible operations” can only be taught. For rules with a check, Teach lets agents learn the rule while scans keep measuring how often code breaks it.

Advise

The rule is taught, and groundrule check runs it. Findings appear in the check output, in the terminal, in CI, and in the Markdown and SARIF reports. Blockers are reported as warnings, so with the default settings an Advise rule never fails a check.

Caution

If a repository or a CI step uses --fail-on warning (or failOn: warning in its config), warnings fail the check, and that includes findings from Advise rules. Keep the default failOn: blocker if Advise should never block a merge.

Enforce

The rule is taught, and groundrule check reports its findings at the rule’s real severity. By default (failOn: blocker), only blockers fail the check. A warning at Enforce is reported but doesn’t fail.

To make a rule stop merges, it needs both: stage Enforce and severity Blocker. The evidence panel says this when you preview Enforce for a warning: “At Enforce, checks fail only on blockers by default (failOn: blocker). Raise the severity to Blocker to stop merges.”

What fails a check

With the default settings, groundrule check fails when a change adds a finding from a rule at Enforce with severity blocker. Every other combination is reported or left out:

Severity	Observe	Teach	Advise	Enforce
Blocker	Not checked	Not checked	Reported as a warning	Fails
Warning	Not checked	Not checked	Reported	Reported
Advisory	Not checked	Not checked	Reported	Reported
Info	Not checked	Not checked	Reported	Reported

With --fail-on warning, warnings fail too: a warning at Enforce, and any blocker or warning at Advise. With --fail-on none, nothing fails. Advisory and info findings never fail a check.

By default, groundrule check looks only at the lines a change touches, so existing code doesn’t fail a new rule. See Check your changes for --all, --base, and the legacy setting.

When a stage change takes effect

Where	When
groundrule check and groundrule standards	On their next run. The CLI fetches your workspace’s rulebook every time.
Agent files	After groundrule sync runs in the repository and the changed files are committed. A CI step with groundrule sync --check fails until they are.
The MCP server	On the coding agent’s next list_standards call
Evidence and the dashboard	At once

The recommended path

1. Start where Groundrule recommends. Each pack rule starts at the stage shown as Starts at in the catalog, based on how noisy its check is. Your own standards start at Enforce when you create them as Active, or at the stage you pick when you publish a draft.
2. Look at the evidence. Scan your repositories with npx @groundrule/cli scan --upload. Each rule’s page shows which repositories pass and what each stage would do.
3. Fix or except what the rule finds while the rule is at Teach or Advise. Agents already follow it, so new code stays clean.
4. Move it forward when it has been clean. When a rule has had no findings for 7 days (14 before Enforce), across at least 2 scans of each repository, the inbox suggests the next stage under Ready to move forward. See Promotions.
5. Raise the severity to Blocker for rules that must stop merges, once they are at Enforce and clean.

You can change a stage at any time in the rule’s rollout panel, or for many pack rules at once on the pack’s page. See Adopting and tuning rules.

Stages for teams and repositories

A team or a repository can use a later stage than the organization, never an earlier one. For example, the Payments team can enforce a rule the organization only teaches. A repository inherits its team’s stage and can move further still.

For a team’s stage to apply, the repository must be registered under that team in Teams & repositories. The CLI finds the repository by its git remote, for example acme/checkout-api. If the repository isn’t registered, groundrule sync, check and standards use the organization’s settings and warn:

! .groundrule/config.yaml  acme/checkout-api isn't registered in acme-payments, so the organization's rules apply. Add it under Teams → Repositories to use its team's settings.

See Teams and owners.

See a rule’s stage from the terminal

groundrule standards lists every rule from your workspace with its stage at the end of the second line:

$ npx @groundrule/cli standards

 Standards · 79 in effect of 91

 AGENT-005   blocker   Never weaken tests or checks to get a green build
                       agent guidance · platform:groundrule:packs/agent-hygiene · teach
 AGENT-010   blocker   No merge conflict markers or merge leftovers
                       regex, files · platform:groundrule:packs/agent-hygiene · enforce
 GHA-004     blocker   Do not check out pull request code in pull_request_target workflows
                       regex · platform:groundrule:packs/github-actions · advise

With --json, each rule has a stage field ("teach", "advise", or "enforce"). Rules at Observe and drafts aren’t listed, because they don’t reach the CLI. Standards defined in the repository itself, in .groundrule/standards/, have no stage: they are always taught and checked at their severity.

groundrule explain <ID> shows a pack rule’s recommended starting stage under Adopting it, for example “Recommended starting stage: advise”.