Skip to content

The CollectionInstrument No. 09

couplingguard

Your git log knows which files break together. Nobody reads it. This does.

The Problem

Two files that always break together ship in the same PR with nobody reviewing both sides. The pairing has been sitting in git log for months — every co-change a data point — but a unified diff can’t show it.

AI coding agents raised the stakes: Copilot, Claude Code, and Cursor routinely land diffs touching 15–30 files, and no human holds the whole change in their head anymore.

The Insight

Raw co-change counts lie for old, busy files. Normalize: co_changes ÷ max(changes_a, changes_b).

The Instrument

couplingguard is a GitHub Action and GitLab CI step that builds a co-change matrix from your history, normalizes each pair to a 0–1 score, and posts a self-editing PR comment — with a score-delta line on every re-push and CODEOWNERS-based reviewer suggestions.

An optional fail threshold turns coupling into a budget CI can enforce. Five lines of YAML, MIT licensed, analysis entirely on your own runner.

Dogfooded on its own repository

$ couplingguard --repo . --dry-run --lookback-days 90

🔍 couplingguard — 6 pairs detected, highest risk: 🔴 1.00

pyproject.toml ↔ skills-lock.json 1.00 🔴 2/2 commits

test_github_poster.py ↔ test_gitlab_poster.py 1.00 🔴 2/2 commits

.gitignore ↔ pyproject.toml 0.67 🟡 2/3 commits

Pairs and scores are the real result of couplingguard’s dogfood test on its own history; --dry-run prints them as the markdown PR comment.

Spec

Score
co_changes ÷ max(changes_a, changes_b) — comparable across repos
Risk bands
🟢 < 0.3 ≤ 🟡 < 0.7 ≤ 🔴
CI
GitHub Action (5 lines) · GitLab CI · optional fail threshold
Quality bar
148 tests · mypy --strict · test matrix Linux/macOS/Windows × Python 3.11–3.13
Lineage
Operationalizes Your Code as a Crime Scene at PR time
Install
PyPI couplingguard · GitHub Marketplace
Quick start
uses: Meru143/couplingguard@v1

The Outcome

couplingguard 0.1.2 shipped to PyPI and the GitHub Marketplace on 28 May 2026. Built as the cheapest backstop in the stack: a comment on every PR that surfaces the files the change should have touched but didn’t — before merge, when the fix is still cheap.