P1.LOC.004 — Commits touch a bounded number of files¶
| Field | Value |
|---|---|
| Principle | P1 (Locality) |
| Severity | info |
| Evidence | sampled |
| Stability | experimental |
What it checks¶
Using git history, computes the median number of files changed per commit. Repos where a typical commit touches more than 8 files have poor change isolation — agents must hold wide context for routine changes.
Why it matters¶
When most commits touch many files across many directories, it signals that the codebase has high coupling at the change level. Agents making a small feature change may need to modify files scattered across the tree, increasing the risk of unintended side effects.
When to care¶
- Care when the trend is increasing (commits getting wider over time).
- Care less during active refactors that intentionally touch many files.
How to fix¶
Refactor to reduce cross-cutting changes. Ensure each commit stays within a narrow vertical slice. Use interfaces and adapters to decouple modules.
History¶
- 0.3.x — introduced at
stability: experimental.