P1.LOC.003 — Dependency graph coupling is bounded¶

Field	Value
Principle	P1 (Locality)
Severity	`info`
Evidence	`medium`
Stability	`experimental`

What it checks¶

Using the dependency graph collector, measures the maximum transitive reach of any package. A package that can transitively reach more than 10 other packages is "context-expensive" — an agent modifying it must understand many neighbors.

Also emits a coupling_max_reach metric for trend tracking.

Why it matters¶

Locality means an agent can understand a change from a narrow slice. When one package transitively reaches 20+ others, a change in that package could affect any of them. The agent's context window fills up, and its confidence in the safety of changes drops.

When to care¶

Care when the most-coupled package keeps growing over time (trend).
Care less for utility packages that are widely imported but rarely changed (e.g., internal/model/). These are read-heavy, not write-heavy.

How to fix¶

Split high-reach packages into smaller modules with narrower interfaces. Extract shared types into a dedicated package. Use interfaces at module boundaries.

Suppressing this rule¶

ignore:
  - rule: P1.LOC.003
    reason: "model package is intentionally central"
    expires: 2027-01-01

History¶

0.3.x — introduced at stability: experimental.