PR Governance Checks
Every pull request on a governed repository triggers an SGD governance check. The check appears as a GitHub Check Run — the same mechanism your team already uses for CI, linting, and tests. No new tools to learn, no new tabs to open.
SGD currently runs two checks on every PR:
How it works
Check 1: Spec Traceability
This check answers a simple question: does this PR relate to a known specification?
What it looks for
The check scans the PR title, description, and commit messages for spec reference patterns:
| Pattern | Example |
|---|---|
Refs: SPEC-ID | Refs: PAY-REFUND-001 |
Spec: SPEC-ID | Spec: AUTH-SSO-001 |
[SPEC-ID] | [PAY-REFUND-001] |
What happens when a reference is found
- SGD looks up the spec ID in the capability model
- If the spec exists, the check passes and the PR is automatically linked to the spec in the governance dashboard
- If the spec ID does not exist (typo, deleted spec, wrong format), the check fails with a clear message explaining which ID was not found
What happens when no reference is found
The check issues a warning, not a failure. The PR description is annotated with a suggestion:
"No specification reference found. If this PR implements a feature, consider adding
Refs: SPEC-IDto the description. Learn more"
This keeps the check informative without blocking bug fixes, dependency updates, or quick improvements that genuinely do not need a spec.
Configurable strictness
By default, missing spec references produce a warning. If your team wants to enforce traceability on every PR, you can configure the check to fail when no spec reference is found. This is set per-repository or per-capability in the SGD dashboard.
Check 2: Design System Compliance
This check applies to PRs that modify .tsx or .jsx files. It evaluates changed files against your organisation's design system rules.
What it checks
| Rule type | Example check |
|---|---|
| Canonical component | PR uses <Button> from @acme/ui instead of a custom button |
| Banned pattern | PR does not use inline style= in component files |
| Required token | PR uses var(--color-primary) instead of hardcoded #2563eb |
Rules are defined at the organisation level and can be scoped to specific capabilities or repositories. See Design System Enforcement for the full rule specification.
How violations appear
Design system violations appear as inline annotations on the PR diff — the same format as ESLint or CodeQL findings. Each annotation includes:
- The rule that was violated (e.g., "Use canonical
<DataTable>component") - Why it matters (e.g., "Custom table implementations diverge from the design system and increase maintenance cost")
- How to fix it (e.g., "Import
DataTablefrom@acme/ui— component docs")
Severity levels
| Severity | Default behaviour | When to use |
|---|---|---|
| Error | Blocks merge | Banned patterns, security-sensitive UI rules |
| Warning | Annotates, does not block | Non-canonical component usage, missing tokens |
| Info | Annotates only | Suggestions, upcoming deprecations |
Check results in practice
Here is what your team sees on a typical PR:
Scenario 1 — Everything passes:
SGD Governance: All checks passed. Spec
PAY-REFUND-001linked. No design system violations.
Scenario 2 — Warning, no blocker:
SGD Governance: Warning. No spec reference found. 1 design system suggestion (non-canonical
<Modal>— consider@acme/ui/Dialog).
Scenario 3 — Failure:
SGD Governance: Failed. Banned pattern detected: inline
style=insrc/components/PaymentForm.tsx:42. Referenced specPAY-REFND-001does not exist (did you meanPAY-REFUND-001?).
Feeds into coherence scoring
Every PR check result feeds into the repository's coherence score. Repositories where PRs consistently pass governance checks score higher on the spec coverage and design system dimensions. Over time, this creates a measurable trend that shows whether governance is improving.
Progressive, not punitive
SGD governance checks are designed to guide, not gatekeep. The defaults are deliberately lenient:
- Missing spec references produce warnings, not failures
- Design system suggestions are informational by default
- Only explicitly banned patterns block a merge
Teams tighten the rules as they mature. A team that adopted SGD last week should not have the same strictness as a team that has been using it for six months. Configure the thresholds that match your team's readiness, and raise them over time.
Warn by default. Block when configured.