Skip to content
docs
Open the dashboard
Developer docs

Inspect your rules

Developers6 min read

Four commands show what Groundrule knows about a repository without changing anything:

Command Answers
standards Which rules are in effect here, at what severity and stage?
explain <ID> What does this rule require, why, and how do I comply?
doctor Is my setup working?
packs Which bundled packs can I extend?

standards: what’s in effect

Section titled “standards: what’s in effect”
Terminal window
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
 REACT-008   blocker   No secrets in client-exposed environment variables (not applicable here)
                       regex · platform:groundrule:packs/react · enforce
 …
 TS-009      info      Import Node.js built-ins with the node: prefix
                       regex · platform:groundrule:packs/typescript-node · advise

The header counts the standards that are active and apply here, out of all the standards the repository receives. Rules are sorted by severity, then ID. Each takes two lines:

  1. ID, severity, title, and “(not applicable here)” when its languages or frameworks aren’t in this repository, or its status (such as “(deprecated)”) when it isn’t active.
  2. Its checks (regex, files, dependencies, change-set, semgrep), or “agent guidance” when it has none; its paths, when it’s limited to some; where it comes from; and, in a platform repository, its stage.

The source reads:

  • platform:groundrule:packs/<pack>: a pack rule, from your workspace;
  • platform:<workspace>: a rule your workspace wrote;
  • groundrule:packs/<pack> or github:…: a pack in extends (offline);
  • local: a file in .groundrule/standards/.

In a platform repository, standards shows rules at Teach, Advise, and Enforce. Rules at Observe and drafts stay on the platform.

--json

Section titled “--json”
Terminal window
npx @groundrule/cli standards --json

prints an array, one object per standard:

Field Meaning
id, title, severity The standard.
status active, draft, deprecated, or disabled (turned off in overrides).
applies true when it applies to this repository.
checks The check types, such as ["regex"]. Empty for guidance.
paths Path scope, if any.
origin Where it comes from, as above.
stage teach, advise, or enforce. Only in platform repositories.
file Where it’s defined: a path, or its address on the platform.

For example, after a promotion in the dashboard, standards --json shows the rule’s new stage.

explain: one rule in full

Section titled “explain: one rule in full”
Terminal window
npx @groundrule/cli explain DOCKER-001
 DOCKER-001  Run the final image as a non-root user
 warning · requirement · v1 · active


 Requirement
   The final stage of every Dockerfile must switch to a non-root user with a USER instruction (a name or a numeric UID other than 0). Earlier build stages may run as root.


 Why
   A container that runs as root turns any code-execution bug into root inside the container, one kernel or runtime flaw away from root on the host.


 Applies to
   Everything in the repository


 Examples
   ✓ Do
       FROM node:22-alpine
       WORKDIR /app
       COPY --chown=node:node . .
       USER node
       CMD ["node", "server.js"]
   ✕ Don't (No USER instruction, so the process runs as root.)
       FROM node:22-alpine
       COPY . .
       CMD ["node", "server.js"]


 How to fix
   Create an unprivileged user (or use one the base image provides, such as node or nonroot) and add USER <name-or-uid> after the last step that needs root, in the final stage. Prefer a numeric UID so Kubernetes runAsNonRoot can verify it.


 How it's checked
   • regex (deterministic)
   • delivered to coding agents via agents-md, claude-code, cursor


 Exceptions
   None. To request one, add an entry to .groundrule/exceptions.yaml with a reason and expiry.


 Adopting it
   Recommended starting stage: advise
   Expected noise: medium
   Known false positive: Base images that already set a non-root user (distroless :nonroot, Chainguard, some vendor images). Add an explicit USER anyway; it documents intent and costs nothing.
   …


 References
   CWE-250 Execution with Unnecessary Privileges  https://cwe.mitre.org/data/definitions/250.html
   https://docs.docker.com/build/building/best-practices/

The sections, in order (a section is left out when the rule has nothing for it):

Section Contents
Header ID and title; then severity, type, version, status, and owner. A changed severity reads “(overridden from …)”. A rule turned off here says “Disabled in this repository”.
Requirement The rule.
Why Its intent and rationale.
Applies to Paths, exclusions, languages, frameworks, tags, and repositories, or “Everything in the repository”.
Examples Every Do and Don’t example, with notes.
How to fix The remediation.
How it’s checked Each check and its source (deterministic, static analysis, or AI), and the agent files it’s delivered to. “Agent and reviewer guidance only; no automated check.” when there’s none.
Exceptions Who may approve them and for how long, and every exception in .groundrule/exceptions.yaml, active (●) or expired (○).
Adopting it Recommended starting stage, expected noise, and known false positives.
Supports compliance controls Frameworks and controls, such as SOC 2 or OWASP ASVS.
References Links such as CWE and OWASP.
Footer Where the rule is defined, and its source.

IDs aren’t case-sensitive. For an unknown ID, explain suggests close ones with the same prefix: “No standard TS-100. Did you mean TS-001, TS-002, TS-003?” Without a match, it says “Run groundrule standards to list them.” and exits with code 2.

Every finding from check ends with the explain command for its rule.

doctor: check your setup

Section titled “doctor: check your setup”
Terminal window
npx @groundrule/cli doctor
 groundrule doctor


   ✓ Node.js 22.12.0
   ✓ Inside a git repository
   ✓ Connected to Acme Payments on https://app.groundrule.dev
   ✓ Configuration is valid: 79 of 91 standards apply to this repository
   ✓ Evaluator dependencies is ready
   ✓ Evaluator files is ready
   ✓ Evaluator regex is ready
   ✓ Agent instructions are up to date (agents-md, claude-code, cursor)


 Everything looks good.

What it checks:

Check Fails (✕) or warns (!) when
Node.js ✕ older than 22: “Groundrule needs Node.js 22 or newer.”
git ! not a git repository: “groundrule check will audit every file instead of your changes.”
Configuration ✕ .groundrule/config.yaml is missing or has errors, or the rulebook can’t be fetched. The errors are printed above.
Platform Shows the workspace and address, and the registered repository name when there is one.
Standards Counts how many standards apply here. ! when there are configuration warnings, such as an unregistered repository.
Checks One line per check type your rules use. ✕ for an unknown check type. ! when one can’t run here, such as semgrep without Semgrep installed: “Semgrep is not installed. Install it with brew install semgrep or pipx install semgrep.”
Agent files ✕ out of date: names the files and says “Run groundrule sync.”

doctor ends with “Everything looks good.” (exit 0) or “N problem(s) found.” (exit 1). Warnings don’t count as problems.

packs: the bundled packs

Section titled “packs: the bundled packs”
Terminal window
npx @groundrule/cli packs
 Bundled packs · add to extends in .groundrule/config.yaml


   groundrule:packs/agent-hygiene · 10 standards
   How AI coding agents should work in a repository - scoped changes, honest verification, no weakened tests, and no surprises.


   groundrule:packs/docker · 12 standards
   Secure, reproducible, and lean container images built from Dockerfiles.
   …

It lists every pack that ships with the CLI, with its reference, size, and description:

Pack Standards
agent-hygiene 10
docker 12
github-actions 10
go 13
http-api 12
java-spring 16
kubernetes 12
python 16
react 12
security-baseline 20
terraform 12
testing 11
typescript-node 15

Use these references in extends for an offline repository. In a platform repository, packs are adopted in the dashboard instead. More: Packs.

Section titled “Related”