Coherence Scoring
Every repository in SGD gets a coherence score — a single number from 0 to 100 that measures how consistently the repository follows your organisation's defined standards. The score combines 12 dimensions, each weighted to reflect its importance.
Think of it as a credit score for your repositories. One number, backed by detailed breakdowns, that tells you where things stand and where to focus.
The 12 dimensions
| # | Dimension | Weight | What it measures |
|---|---|---|---|
| 1 | Compliance | 10% | Passes on GitHub-native security checks (branch protection, Dependabot, secret scanning) |
| 2 | Pattern Drift | 10% | Deviation from the assigned golden path template (file structure, configs, dependencies) |
| 3 | CI/CD | 10% | Pipeline health — build success rate, deployment frequency, pipeline configuration |
| 4 | Documentation | 10% | Presence and quality of README, ADRs, runbooks, API docs |
| 5 | Infrastructure | 5% | IaC coverage, environment parity, resource tagging |
| 6 | Observability | 5% | Logging, monitoring, alerting, and tracing configuration |
| 7 | Security | 10% | Dependency vulnerabilities, secret management, authentication patterns |
| 8 | Freshness | 5% | Dependency age, last meaningful commit, stale branch count |
| 9 | AI Readiness | 5% | Presence of CLAUDE.md, copilot config, agent-friendly documentation |
| 10 | Spec Coverage | 15% | Percentage of recent PRs linked to feature specifications |
| 11 | Design System | 10% | Compliance with canonical components, design tokens, and banned patterns |
| 12 | DAG Completeness | 5% | Coverage of the repository in the impact analysis graph (edges, specs, API contracts) |
Why these weights?
The weights reflect a balanced view of repository governance. Spec coverage carries the highest weight (15%) because traceability is the foundation of specification-governed development — without it, the other dimensions are disconnected improvements. Security and compliance are weighted at 10% each because they represent non-negotiable organisational requirements. Lighter dimensions like freshness and DAG completeness are important signals but are not as directly actionable.
Weights are configurable
These are the default weights. Your organisation can adjust them in the SGD dashboard to reflect your priorities. If security is paramount, increase its weight. If AI readiness is not relevant yet, reduce it.
Score thresholds
| Score | Rating | What it means |
|---|---|---|
| 90 - 100 | Excellent | Fully governed, minimal drift, high traceability. Exemplar repository. |
| 70 - 89 | Good | Well-governed with minor gaps. Typical target for mature teams. |
| 50 - 69 | Needs Attention | Notable gaps in governance. Some dimensions require active work. |
| 30 - 49 | Poor | Significant governance gaps across multiple dimensions. Remediation needed. |
| 0 - 29 | Critical | Minimal governance in place. Usually legacy or abandoned repositories. |
Thresholds apply at the repository level and the capability level (average of all repos in the capability). The dashboard shows both.
Score calculation
Each dimension produces a sub-score from 0 to 100. The coherence score is the weighted average:
coherence_score = sum(dimension_score[i] * weight[i]) for i in 1..12For example, a repository with:
- Compliance: 95, Pattern Drift: 80, CI/CD: 70, Documentation: 60
- Infrastructure: 50, Observability: 40, Security: 85, Freshness: 90
- AI Readiness: 30, Spec Coverage: 75, Design System: 65, DAG Completeness: 45
Gets a coherence score of:
(95 * 0.10) + (80 * 0.10) + (70 * 0.10) + (60 * 0.10) +
(50 * 0.05) + (40 * 0.05) + (85 * 0.10) + (90 * 0.05) +
(30 * 0.05) + (75 * 0.15) + (65 * 0.10) + (45 * 0.05)
= 9.5 + 8.0 + 7.0 + 6.0 + 2.5 + 2.0 + 8.5 + 4.5 + 1.5 + 11.25 + 6.5 + 2.25
= 69.5 → Needs AttentionGraceful degradation
Not every organisation will have every dimension configured from day one. A team that just installed SGD and has not yet defined a capability model should not see a score of zero because spec coverage and DAG completeness are undefined.
SGD handles this with weight redistribution:
How it works
When a dimension cannot be evaluated (e.g., no design system rules defined, no capability model created), its weight is redistributed proportionally across the remaining dimensions.
| Scenario | Unavailable dimensions | Redistributed weights |
|---|---|---|
| Just installed — No capability model, no design system, no specs | Spec Coverage, Design System, DAG Completeness | Remaining 9 dimensions share the extra 30%, each scaled proportionally |
| Compliance only — GitHub security features, no golden path | Pattern Drift, Infrastructure, Observability, AI Readiness | Remaining 8 dimensions absorb the extra 25% |
| Full governance | None | All 12 dimensions at default weights |
The key principle
A repository's coherence score is never zero because of missing configuration. A repo that passes all available checks should score well, even if your organisation has not yet configured every governance dimension. As you enable more dimensions, the score becomes more comprehensive — but it is always meaningful.
Why this matters
Without graceful degradation, teams would see artificially low scores on day one and lose trust in the metric. The score should reflect how well the repository follows the standards that exist, not penalise the team for standards that have not been defined yet.
Score trends
The coherence score is recorded as a snapshot at regular intervals (daily, or after significant events like PR merges). The dashboard shows:
- Current score for each repository and capability
- 7-day / 30-day / 90-day trends — improving, stable, or worsening
- Dimension breakdown — which dimensions are pulling the score up or down
- Peer comparison — how this repository compares to others in the same capability
Trends are more important than absolute numbers. A repository at 55 and trending upward is in better shape than one at 75 and trending down.
Using scores effectively
For tech leads
Sort repositories by coherence score within your capability. Focus remediation effort on the lowest-scoring repos with the highest-weighted failing dimensions. A repository scoring 45 on security (10% weight) is a better use of time than one scoring 45 on freshness (5% weight).
For architects
Compare coherence scores across capabilities to identify systemic issues. If every repo in the Payments capability scores low on observability, the fix is probably a golden path template update, not individual repo work.
For leadership
Track the capability-level average over time. This is the metric that shows whether governance investment is paying off. Rising averages mean the organisation is becoming more consistent. Falling averages are an early warning.