Scans, the inbox, and when to switch a rule on
Enforcing a rule without evidence is a guess. A scan replaces the guess: it drives the whole road once before you switch the camera on, and tells you how many cars would be fined today.
What a scan is
Section titled “What a scan is”scan runs every rule in the catalog against the repository and enforces nothing. It sorts the rules that apply into three piles:
| Pile | Meaning | What you can do |
|---|---|---|
| Already pass | The check ran and found nothing | Switch on at Enforce; nobody is affected today |
| With findings | The check found something, with file and line | Fix first, or enforce later |
| Guidance only | No check exists | Teach it; nothing can scan for it |
It also finds what the repository already says: hand-written agent instructions, lint settings, CODEOWNERS, and the architecture the code already keeps. With --upload, all of it goes to the workspace as proposals.
Why “passing” means “safe to enforce”
Section titled “Why “passing” means “safe to enforce””Enforce means a pull request that breaks the rule fails its check. Two cases:
The rule is passing. JAVA-002, no System.out.println, and the scan found none in 16 files. Switch on Enforce. Nobody’s open pull request fails, because there is nothing to fail. Next week someone adds a println in a new commit; their pull request goes red at that line, they use the logger, it goes green. The camera only fines new violations.
The rule has findings. Imagine the scan had found println in six files. Switch on Enforce anyway, and tomorrow a developer fixing a typo in one of those files fails their pull request on a line they never wrote. Multiply by six files and the team’s first week with the rule is red checks and annoyance. The right order is the reverse: Advise first, clean up the six files, then Enforce once the scan shows it passing.
The scan tells you which case you are in before you decide.
The inbox
Section titled “The inbox”The review inbox has two halves.
Proposals are rules found written down somewhere: an instruction in a hand-written AGENTS.md, a lint setting, an imported document, a rule proposed by an agent through MCP, a review comment reviewers keep repeating. Accept, edit or reject each. Accepting does the real thing: a new standard, an adopted rule, an owner. Agent files that sync wrote are recognised and not proposed back.
Ready to move forward is the promotion engine. It watches your scan history and suggests when a rule can go up a stage. The policy is on the panel: clean everywhere for 7 days to reach Advise, 14 days to reach Enforce, with at least 2 scans per repository. Underneath:
- Almost there lists rules on their way, with what is missing: “Clean in 2 repositories so far; needs 2 scans in every repository.” The bar is progress toward the waiting period. Move to Enforce skips the wait; Not now hides the suggestion.
- Needs attention lists rules that were clean and have new findings. Example:
JAVA-003, “Controllers must not use repositories directly, 2 new findings in 1 repository that were clean before.” A rule that has started failing leaves the promotion queue until someone looks.
Keep the evidence fresh
Section titled “Keep the evidence fresh”Suggestions appear only if scans keep arriving. A nightly scan --upload in CI, with the same token as the check, is enough. Each rule’s page then shows what it finds across repositories, and in two weeks the first suggestions arrive on their own.
The order that avoids a red week
Section titled “The order that avoids a red week”- Scan. Read the three piles.
- Accept the proposals you agree with; they start at Teach.
- Move passing rules to Advise, or straight to Enforce for the ones that matter most, such as secrets.
- Fix the findings on the rules you care about, then let the inbox tell you when they are clean.
- Promote on the suggestion, not on a hunch.