Module coordination_needs 

coordination-needs analysis — per-file coordination overhead signal.

Three complementary metrics quantify how much human coordination a file demands:

• Fragmentation F = 1 − Σ k_norm² (HHI complement): the probability that two randomly chosen knowledge-weighted commits to the file were made by different people. Zero when one author holds all knowledge; near 1 when knowledge is evenly split across many authors. Computed from the decayed knowledge shares produced by materialize_knowledge_shares. Note: authors counts active-window contributors (≥1 commit in the trailing window), while fragmentation is computed over all knowledge holders (including historical contributors whose knowledge has partially decayed), because the HHI sum reflects cumulative knowledge distribution, not just current activity.

• Interleave I = switches / (n_commits − 1): the fraction of chronologically adjacent commit pairs touching the file where the author switches. A value near 1 means nearly every commit is by a different person than the previous one — classic ping-pong ownership churn. Zero when fewer than 2 commits exist for the file (stable or untouched).

• Co-change entropy H'_a: file a’s contribution to the co-change graph’s structural entropy (co-change graph entropy, EASE 2025, arXiv 2504.18511). Only commits touching ≤30 files are included (large “shotgun” commits bloat every file’s degree without reflecting real coupling). p'_k = deg(k) / (2|E|) is the probability that a random edge-endpoint is node k; H'(S) = −Σ p'_k · ln(p'_k) is the global entropy; H'_a = p'_a · H'(S) is the per-file contribution. Log base is ln (natural); the paper leaves the base unspecified and ranks are invariant to base choice. Files with no co-change edges receive H'_a = 0.0 and are still emitted (they appear in the path-aggregated result).

Tier classification (for triage prioritisation):

• single: authors <= 1 — either exactly one active-window contributor, or zero (a dormant file with no commits in the trailing window at all, whatever its historical author count) — no current coordination activity, so no coordination need right now.
• low: fragmentation < 0.25 — one author dominates, others are minor.
• medium: fragmentation ∈ [0.25, 0.50) OR interleave < 0.50.
• high: fragmentation ≥ 0.50 AND interleave ≥ 0.50 — strong signal.

health_band joins the file’s current composite code-health band (red / yellow / green) from run_code_health_scoped. Coordination overhead in a red-band file is the highest-leverage refactoring signal: ownership fragmentation and structural debt.

Future note: cochange_entropy would make a natural additional Kamei JIT-SDP feature column (structural coupling load per change), but the Kamei table is ingest-shaped and cannot be extended at analysis time.

Structs

CoordinationNeedsRow

Per-file coordination-needs row.

Functions

run_coordination_needs

Compute coordination-needs metrics for every path that appears in the trailing opts.window_days window.