The output contract
Every finding begins with a machine-readable prefix: a severity and a permanent rule id. This is the part that turns review comments into metrics.
Redline/BLOCKER [core/query-string-concatenation]: user-supplied `name` is concatenated into the SQL string, so a crafted value changes the query. Use a parameterised query: db.Query("SELECT id FROM users WHERE name = $1", name)
Then one or two sentences: why it breaks, and the concrete fix. No preamble, no praise, no restating the diff. One finding per comment. If nothing qualifies, post nothing.
Severities
| Severity | Meaning |
|---|---|
| BLOCKER | Must not merge. Security exposure, data loss, crash, silent corruption, or a contract break for live consumers. |
| HIGH | Merge is a deliberate trade-off. A reviewer must acknowledge it explicitly. |
| SUGGESTION | Optional. The author may dismiss it without justification. |
No invented severities, and no upgrading a SUGGESTION to HIGH to get attention — severity inflation is itself measured noise.
Rule ids
Every rule carries a permanent <stack>/<slug> id — core/hardcoded-secrets, javascript/floating-promises, react/effect-derived-state. Findings must cite the id of the rule they apply, exactly as written.
- Ids are stable across wording changes and aggregated per rule — that's how the org learns which rules earn their place and which only generate noise.
core/uncataloguedis reserved for a real finding no rule covers. A rising count there is how a missing rule gets discovered.- A finding without a valid id cannot be measured and is treated as untagged — untagged counts appear in telemetry.
Noise control
AI review dies by nitpick spam, so every standard ships an explicit “What NOT to flag” section: formatting a linter already enforces, existing patterns a PR merely touches, alternative libraries, naming preferences, repeats of the same issue. If you cannot describe the input that breaks it, it is not a finding.
The contract is enforced, not aspirational: scripts/validate.mjs parses the contract example printed in the standard itself, and fails the build if the docs and the parser ever drift apart.