Glossary
Every term Groundrule uses, in alphabetical order, with a one- or two-sentence definition and a link to where it’s covered in full. How Groundrule works shows how the main ideas fit together.
Adopt: To take a catalog standard into your rulebook, usually by turning its pack on, and then tune it: turn it off with a reason, or change its stage, severity, or wording. Adopted rules keep receiving updates from the pack. See Adopting rules.
Advise: The third stage. The rule is in agent instructions, and checks show its findings but never fail. See Rollout stages.
Advisory: The second-lowest severity, between info and warning.
Agent file: An instruction file a coding agent reads before it writes code: AGENTS.md, CLAUDE.md, Cursor rules in .cursor/rules/, or Copilot instructions in .github/copilot-instructions.md. groundrule sync writes your rules into them and leaves what you wrote yourself alone. See Agent instruction files.
Agent guidance: How the dashboard labels a standard that has no check: it reaches coding agents as instructions, but nothing verifies it mechanically. The opposite of Deterministic. See Guidance.
AI draft: A standard or proposal written by AI, labelled “AI draft” with a confidence. It’s a suggestion until a person saves, accepts, or rejects it; AI never changes the rulebook by itself. See AI and your data.
API token: A secret that lets the CLI, CI, or a coding agent reach your workspace without a browser. It always reads the rulebook, and can also upload scans and propose rules. It acts as the person who created it. See API tokens.
Blocker: The highest severity. At the Enforce stage, a blocker’s findings fail groundrule check by default.
Catalog: Every standard Groundrule maintains, across all packs: 13 packs and 171 standards today, each with examples, references, compliance mappings, and a noise rating. See The catalog.
Category: A topic a standard belongs to, such as API design, CI, or Code quality. Categories group the inbox and decide who owns a proposal.
Check: A machine test attached to a standard, run by groundrule check on your code: for example, a regular expression that must not match, files that must exist, or dependencies that must not be added. Checks are deterministic: the same code always gives the same result, with no AI involved. See Checks.
Citation: Where a proposal came from: the file and line of an agent file, the heading and paragraph (or page) of a document, or the link to a pull-request comment. Every imported proposal carries one. See Import documents.
Confidence: How sure AI is about something it wrote, shown as a percentage, such as “AI draft · 87% confident”. Low-confidence findings from documents arrive marked “Note”.
Deterministic: How the dashboard labels a standard that has at least one check. See also Agent guidance.
Draft: A standard that’s saved but not yet published. Drafts aren’t in agent files and don’t fail checks, but scans test them, so you can see their evidence before publishing at a stage. See Write a standard.
Enforce: The fourth and last stage. Findings count at the rule’s severity, so with the default settings, blockers fail the check. See Rollout stages.
Evaluator: The engine that runs a check. The built-in evaluators are regex, files, dependencies, change-set, and semgrep. An llm evaluator is accepted in the format but does nothing yet. See Checks.
Evidence: What scans show about a rule in your repositories: where it applies, which repositories pass, how many findings there are, and what a later stage would flag. See Evidence.
Exception: A time-boxed permission, recorded in a repository’s .groundrule/exceptions.yaml, for code that a rule shouldn’t apply to. Each has an ID such as EX-1042, the standard, the paths, a reason, and an expiry date. See Overrides and exceptions.
Finding: One place where a check found a violation, with the file, line, and a suggested fix.
Guidance: A rule’s wording and examples, written into the instructions coding agents read. Every standard is guidance. Some are also checks. guidance is also one of the standard types.
Inbox: The Review inbox: where proposals wait for someone to accept, edit, or reject them, grouped by category and routed to owners. See The review inbox.
Info: The lowest severity.
MCP: The Model Context Protocol, an open standard that lets coding agents call tools. npx @groundrule/cli mcp runs a server with two tools: list_standards and propose_rule. See The MCP server.
Member: A person in a workspace. Every member has one role. See Members and roles.
Noise rating: How often a catalog rule flags code that is actually fine: “Low noise”, “Medium noise”, or “High noise”. Low-noise rules are safe to start at a later stage.
Observe: The first stage. Checks run silently and results are only recorded; the rule isn’t in agent instructions.
Organization: The broadest scope. A rule’s organization setting is the default for every repository. In the CLI’s configuration, the workspace is called the organization (--org).
Override: A change to a pack rule. On the platform, it’s made in the rule’s rollout panel for the organization, a team, or a repository. In an offline repository, it’s written under overrides in .groundrule/config.yaml. See Overrides and exceptions.
Owner: The person or team responsible for a category of standards. Proposals in that category are assigned to them. Owners are set under Teams → Category owners. See Teams and owners.
Pack: A maintained set of standards on one topic, such as security-baseline, typescript-node, or docker. You turn a pack on to adopt its standards. See Packs.
Promotion: Moving a rule to its next stage once it has been clean long enough: no findings for 7 days (14 before Enforce), across at least 2 scans per repository. The inbox suggests promotions under Ready to move forward. See Promotions.
Proposal: Anything that might become a rule, waiting in the inbox. There are three kinds:
- Instruction: a rule found in an agent file or document, proposed by a developer or coding agent, or sent from a pull-request comment. Accepting it creates a standard, or records that an existing standard covers it.
- Tool setting: a lint or compiler setting, such as an ESLint rule, that maps to a catalog standard. Accepting it adopts that standard.
- Ownership: a CODEOWNERS entry. Accepting it assigns a team as a category’s owner.
See The review inbox.
Repository: The narrowest scope, for one repository. repository is also one of the standard types.
Role: What a member can do in a workspace: Admin, Platform admin, Standard owner, Security reviewer, Manager, Developer, or Viewer. See Roles and permissions.
Rulebook: Everything in effect for your workspace: the packs you adopted with your changes, plus your own standards. One rulebook serves every repository, coding agent, and check.
Scan: groundrule scan: a run of every catalog rule against a repository, at Observe, that changes nothing. It also finds the rules the repository already has. --upload sends the results to your workspace. See Scan repositories.
Scope: Two meanings:
- Where a rule’s settings apply: organization, team, or repository. A team or repository can be stricter than the organization, never looser.
- What a rule covers: the file paths, languages, and frameworks in a standard’s
scope.
Severity: How serious a violation is. From lowest to highest: info, advisory, warning, blocker.
Snippet: The short piece of code around a finding that a scan uploads. --no-snippets leaves them out. See What we store.
Stage: How far a rule is rolled out: Observe, Teach, Advise, Enforce. Separate from severity. See Rollout stages.
Standard: One engineering rule, written for both people and coding agents, with an ID, a requirement, a severity, a type, a scope, examples, and optional checks. Stored as YAML in the open rule format.
Teach: The second stage. The rule is in agent instructions; its checks run silently.
Team: A group of people and the repositories they own. A team’s rule settings apply in its repositories. See Teams and owners.
Type: What kind of rule a standard is:
| Type | Shown as | For a rule that… |
|---|---|---|
guidance |
Guidance | Advises, without a hard requirement |
requirement |
Requirement | Says what must be done |
prohibition |
Prohibition | Says what must not be done |
invariant |
Invariant | Describes something that must always be true |
approved-tech |
Approved tech | Names technology to use |
forbidden-tech |
Forbidden tech | Names technology not to use |
process |
Process | Describes how work is done |
repository |
Repository | Concerns the repository’s files and layout |
agent-instruction |
Agent instruction | Tells coding agents how to behave |
Version: Each save of your own standard creates a new version (v1, v2, …), with an optional “What changed?” note. Packs have versions too; an admin or platform admin can mark a new pack version as reviewed.
Warning: The second-highest severity. Warnings don’t fail checks unless the configuration’s failOn is set to warning.
Workspace: Your organization’s home in Groundrule, at app.groundrule.dev/<url-name>. It holds the rulebook, members, teams, and settings. See Workspace settings.