Coherence Score

Coherence Score

A single number (0-100) that measures governance health. It answers: "How well does this repo know why it was built this way?"

Source: actions/COHERENCE_SCORE_SPEC.md, coherence/telemetry/

---

Formula

score = dlr_coverage_pts + assumption_currency_pts + drift_health_pts + why_retrieval_pts

graph LR
    subgraph Score["Coherence Score (0-100)"]
        direction TB
        D[DLR Coverage<br/>25 pts]
        A[Assumption Currency<br/>25 pts]
        DR[Drift Health<br/>25 pts]
        W[Why Retrieval<br/>25 pts]
    end

    MP[Major PRs<br/>with DLR] --> D
    AY[assumptions.yaml<br/>active + unexpired] --> A
    OD[Open drift<br/>signals] --> DR
    MT[Median time to<br/>answer 'why?'] --> W

    Score --> E{Score?}
    E -->|"90-100"| G[Excellent]
    E -->|"70-89"| B[Good]
    E -->|"50-69"| Y[Needs Attention]
    E -->|"0-49"| R[Critical]

    style G fill:#27ae60,color:#fff
    style B fill:#2980b9,color:#fff
    style Y fill:#f39c12,color:#000
    style R fill:#c0392b,color:#fff

Loading

---

Components

DLR Coverage (25 pts)

coverage = major_prs_with_dlr / total_major_prs

If no major PRs exist, score is 25 (no obligation).

Assumption Currency (25 pts)

currency = active_unexpired / total_active

Assumptions with status: retired or validated are excluded.

Drift Health (25 pts)

drift_health = max(0, 25 - open_drift_count * 5)

Each open drift signal costs 5 points. 5+ open = 0 pts.

Why Retrieval (25 pts)

why_retrieval = max(0, 25 - round(median_seconds / 4))

Measures how fast a new person can find "why was this built this way?" Target: 60 seconds.

---

Interpretation

Score	Rating	Action
90-100	Excellent	Maintain current practices
70-89	Good	Address expired assumptions or open drifts
50-69	Needs Attention	Review DLR coverage, schedule drift triage
0-49	Critical	Governance infrastructure needs immediate investment

---

Automation (v0.2.0+)

Workflow: .github/workflows/coherence-score.yml

• Schedule: Monday 9:00 UTC (weekly), plus manual trigger via workflow_dispatch
• What it does:
  1. Reads assumptions.yaml — counts active/expired
  2. Scans coherence/drift/DRIFT-*.md — counts open signals
  3. Queries GitHub API — counts major PRs with DLR links (last 90 days)
  4. Preserves existing why_retrieval value (manual input)
  5. Writes updated coherence/telemetry/coherence_score.json
  6. Commits + pushes if changed
• Dashboard: Creates/updates a pinned issue titled "Coherence Dashboard" with score breakdown and action items

---

See Also

• IntelOps — assumption currency feeds into the score
• ReOps — DLR coverage feeds into the score
• DriftOps — open drifts reduce the score