Evidence and impact

Evidence is what your scans say about a rule: which repositories it applies to, which pass, how many findings there are, and where. The impact preview turns that into an answer to the question you actually have: if I move this rule to Enforce, what breaks? This page explains the evidence panel field by field, how drafts are tested, and when evidence updates.

Evidence is read-only, and everyone in the workspace can see it.

Where evidence comes from

Evidence comes from scans. When someone runs this in a repository:

npx @groundrule/cli scan --upload

the CLI runs every catalog rule against the repository, plus your own standards that have a check, drafts included. It runs them in Observe, so it changes nothing and fails nothing. It uploads the results: counts, which rules pass, and short snippets around findings (unless you add --no-snippets). Your source code isn’t uploaded. See Scan repositories.

Each rule’s evidence uses the latest scan of each repository. Evidence updates as soon as a scan is uploaded. To keep it current, scan on a schedule, for example nightly in CI; see Promotions.

Rules without a check can’t be measured. They show “Guidance, no check” in lists.

The evidence panel

Open any rule in Standards. Under the examples, the panel Evidence from your repositories shows:

• a line such as “Latest scan of 2 repositories.”, followed by what is being tested;
• four numbers;
• the impact preview;
• one row per scanned repository.

What is being tested depends on the rule:

Rule	The panel says
A pack rule	“Scans run the catalog version of this rule.”
Your own standard	“Scans test your current version of this rule.”
Your own draft	“Scans test this draft; nothing is in effect yet.”

The four numbers

Number	What it means	Example
Applies in	Repositories where the rule had something to check, out of all scanned repositories	2 of 3
Passing	Repositories with no findings, out of those it applies in	1 of 2
Findings	Total findings across those repositories	4
Files clean	Of all files the rule checked, the share with no findings	98%

A rule “applies” in a repository when its scope matches something there. A React rule doesn’t apply in a Go service, and isn’t counted against it.

The impact preview

The preview shows what would happen if the organization used a given stage. Choose a stage in If the organization used: Observe, Teach, Advise, or Enforce. The current stage is marked “· now”.

You preview	The preview says, for example	Shown as
A stage at which blockers would fail	“1 repository would fail groundrule check”, with “2 blocking findings to fix or except first … 1 already passes.”	Red
Advise, or Enforce for a non-blocker, with findings	“3 findings reported in 1 repository; nothing fails”, with “At Enforce, checks fail only on blockers by default (failOn: blocker). Raise the severity to Blocker to stop merges.”	Amber
Teach	“Agents in 2 repositories get this rule”, with “Written to agent files by groundrule sync. Checks don’t run at Teach.”	Green
Advise or Enforce with no findings	“Passes in all 2 repositories”, with “Safe to turn on: no repository has findings today.”	Green
Observe	“Nothing reaches agents or CI”, with “Scans keep collecting evidence so you can decide later.”	Grey

The preview takes team and repository settings into account. If a team already uses a later stage, the preview keeps it, because teams can only be stricter, and says: “Some teams already use a later stage; the preview keeps theirs, since teams can only be stricter.”

The preview changes nothing. To change the stage, use the rollout panel; see Adopting and tuning rules.

If the rule’s pack isn’t turned on, the panel adds: “Not adopted yet. Turn on its pack to roll it out; this preview shows what would happen.” That means you can judge a pack rule before you turn the pack on.

If a suggestion to move the rule forward exists, it appears above the preview: “Ready for stage” with Move to stage, or “Working toward stage”. See Promotions.

One row per repository

Each scanned repository has a row, sorted by findings, most first:

Part	What it shows
Name and team	The repository, such as acme/checkout-api, and its team if it’s registered under one
Detail	“3 findings in 2 of 140 files”, or “140 files checked”, then the rule’s stage and whether it is on there (“· Advise here”, “· Off here”), and “scanned 2 days ago”
Outcome	Passes, Findings, Guidance, Doesn’t apply, or Couldn’t check
Severity	The rule’s severity in that repository, when it has findings

Select a row with findings to expand it. Each finding shows its file and line, its message, and the snippet, with Open the scan to see the full scan.

Draft rows don’t show a stage, because a draft isn’t in effect anywhere.

No scans yet

Until a repository has been scanned, the panel says “Scan a repository to see whether this rule already passes, and what turning it on would do.” and shows the command to run.

Test a draft against real code

Drafts are where evidence matters most: you can see what a new rule would flag before anyone is affected.

1. Save the standard as a draft, from the editor with Draft (not enforced), or from Describe a rule with Save as draft.

2. Scan one or more repositories: npx @groundrule/cli scan --upload. The scan output counts your rules, including drafts, for example “Your rules 3 with checks (1 draft) · 1 with findings here”.

3. Open the draft’s page and read its evidence.

4. Preview a stage in If you published it at. It starts at Observe, the same as the Publish at default.

5. Fix the rule or the code, then scan again. When the evidence looks right, publish. See Write a standard.

You should see the draft’s findings in each repository row. If the panel still says to scan a repository, the scan wasn’t uploaded: check that the command included --upload and finished with “✓ Uploaded to workspace”.

Evidence in lists

A short version of the evidence appears wherever rules are listed, such as the In your repos column on a pack’s page and on inbox proposals that match a catalog rule:

Label	Meaning
“Passes in 2/2”	No findings in any repository it applies in
“1 finding · 1/2 repos”	Findings in some repositories
“Guidance, no check”	The rule has no check, so scans can’t measure it
“Not in scanned repos”	The rule doesn’t apply in any scanned repository

On a pack’s page, Select rules passing everywhere uses the same evidence to select every rule you could move forward safely. See Packs.

Related

• Promotions: suggestions to move rules forward, based on evidence over time.
• Rollout stages: what each stage does.
• Scan repositories: run and upload scans.