program-context-protocol 0.12.4__py3-none-any.whl

pcp/control_audit.py

@@ -0,0 +1,159 @@
+"""Control-catalog self-audit -- PCP applying its own philosophy to its own
+catalog, not just to projects PCP builds. Real gap named in the 2026-07-21
+self-evaluation: 33 CTRL checks accumulated with no pruning discipline to
+match the modularity/token-discipline philosophy PCP preaches everywhere
+else. Pure aggregation over `.pcp/controls.yaml` + `.pcp/telemetry.jsonl`,
+no LLM, same posture as coverage_audit.py/architecture_justification.py --
+surfaces a signal, never auto-prunes, never blocks.
+
+Deliberately narrow: detects the ONE thing checkable without judgment --
+a control declared in the catalog that has never once produced a real
+finding across its recorded history (a `zero-findings` candidate for
+human review: retire, merge into a related check, or leave as intentional
+belt-and-suspenders coverage). Does NOT attempt automated mechanism-overlap
+detection (e.g. "these three are all presence checks") -- that's a
+judgment call a human should make reading the rendered report, not
+something worth a fuzzy heuristic that could be wrong in either direction.
+"""
+
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+# Below this many recorded runs, "zero findings" isn't a real signal yet --
+# a brand-new control with 2 runs and no findings just hasn't been tested,
+# not proven unnecessary.
+MIN_RUNS_FOR_SIGNAL = 20
+
+
+def _load_controls(pcp_dir: Path) -> list[dict]:
+    path = pcp_dir / "controls.yaml"
+    if not path.exists():
+        return []
+    try:
+        data = yaml.safe_load(path.read_text()) or {}
+    except yaml.YAMLError:
+        return []
+    return data.get("controls", []) or []
+
+
+def build_control_audit(pcp_dir: Path) -> dict:
+    """Returns {control_id: {name, total_runs, findings, rate, layer,
+    enforcement, signal}}. `signal` is one of: "insufficient-data" (below
+    MIN_RUNS_FOR_SIGNAL), "never-fired" (>= MIN_RUNS_FOR_SIGNAL runs, zero
+    findings -- retire/merge candidate), "active" (has fired at least
+    once)."""
+    from pcp import telemetry
+
+    controls = _load_controls(pcp_dir)
+    records = telemetry.load(pcp_dir)
+
+    runs_by_control = defaultdict(int)
+    findings_by_control = defaultdict(int)
+    for r in records:
+        cid = r.get("control_id")
+        if not cid:
+            continue
+        runs_by_control[cid] += 1
+        if r.get("result") == "block" or (r.get("error_count") or 0) > 0:
+            findings_by_control[cid] += 1
+
+    out = {}
+    for c in controls:
+        cid = c["id"]
+        total = runs_by_control.get(cid, 0)
+        findings = findings_by_control.get(cid, 0)
+        if total < MIN_RUNS_FOR_SIGNAL:
+            signal = "insufficient-data"
+        elif findings == 0:
+            signal = "never-fired"
+        else:
+            signal = "active"
+        out[cid] = {
+            "name": c.get("name", ""), "layer": c.get("layer", ""),
+            "enforcement": c.get("enforcement", ""),
+            "total_runs": total, "findings": findings,
+            "rate": round(findings / total, 3) if total else None,
+            "signal": signal,
+        }
+    return out
+
+
+def render_markdown(audit: dict) -> str:
+    lines = [
+        "# Control Catalog Audit",
+        "",
+        "AUTO-GENERATED by `pcp control-audit`. Never edit -- regenerate instead.",
+        "",
+        "Pure aggregation over `.pcp/controls.yaml` + `.pcp/telemetry.jsonl`, no LLM. "
+        f"A control needs at least {MIN_RUNS_FOR_SIGNAL} recorded runs before "
+        "'never-fired' becomes a real signal rather than just untested.",
+        "",
+        "## Never-fired (retire/merge review candidates)",
+        "",
+    ]
+    never_fired = {k: v for k, v in audit.items() if v["signal"] == "never-fired"}
+    if not never_fired:
+        lines.append("None -- every control with enough recorded runs has fired at least once.")
+    else:
+        lines.append("| Control | Name | Layer | Runs |")
+        lines.append("|---|---|---|---|")
+        for cid, v in sorted(never_fired.items()):
+            lines.append(f"| {cid} | {v['name']} | {v['layer']} | {v['total_runs']} |")
+    lines.append("")
+
+    lines.append("## Full catalog")
+    lines.append("")
+    lines.append("| Control | Name | Layer | Enforcement | Runs | Findings | Rate | Signal |")
+    lines.append("|---|---|---|---|---|---|---|---|")
+    for cid, v in sorted(audit.items()):
+        rate = f"{v['rate']:.0%}" if v["rate"] is not None else "—"
+        lines.append(
+            f"| {cid} | {v['name']} | {v['layer']} | {v['enforcement']} | "
+            f"{v['total_runs']} | {v['findings']} | {rate} | {v['signal']} |"
+        )
+    return "\n".join(lines) + "\n"
+
+
+def write_control_audit(pcp_dir: Path) -> dict:
+    audit = build_control_audit(pcp_dir)
+    (pcp_dir / "control_audit.md").write_text(render_markdown(audit))
+    return audit
+
+
+def sync_catalog(pcp_dir: Path) -> list[str]:
+    """Additive-only merge of the CURRENT package's control catalog into a
+    project's existing controls.yaml. Real gap found 2026-07-22 auditing
+    Project O: `controls.yaml` is scaffolded once at `pcp init` and
+    never refreshed as the `pcp` package adds new controls over time -- one
+    project had 23 distinct control_ids firing in telemetry.jsonl against a
+    10-entry catalog, invisible to `pcp control-audit`/`pcp provenance`
+    entirely. `pcp init --force` would fix this but also blindly overwrites
+    objective.md/architecture.md/every other scaffolded file in the same
+    pass -- far too destructive just to refresh a catalog. This only ever
+    APPENDS entries whose id isn't already present; never rewrites, reorders,
+    or removes an existing entry (a project may have hand-edited descriptions
+    or removed a control deliberately -- this must not silently undo that).
+    Returns the list of newly-added control ids; [] if the project's catalog
+    is already current or has no controls.yaml at all (use `pcp init` to
+    create one from scratch instead)."""
+    from pcp.commands.init import CONTROLS_TEMPLATE
+
+    path = pcp_dir / "controls.yaml"
+    if not path.exists():
+        return []
+
+    template_controls = (yaml.safe_load(CONTROLS_TEMPLATE) or {}).get("controls", [])
+    existing = _load_controls(pcp_dir)
+    existing_ids = {c["id"] for c in existing}
+
+    added = [c for c in template_controls if c["id"] not in existing_ids]
+    if not added:
+        return []
+
+    data = yaml.safe_load(path.read_text()) or {}
+    data["controls"] = existing + added
+    path.write_text(yaml.dump(data, default_flow_style=False, sort_keys=False))
+    return [c["id"] for c in added]

pcp/coupling.py

@@ -0,0 +1,178 @@
+"""Deterministic coupling analysis — replaces the LLM-judged coupling_score.
+
+Coupling, unlike coverage ("does the plan cover the objective" — genuinely
+semantic), is graph math: circular deps, dependency counts, and god modules
+are all mechanically computable from each module's declared 'dependencies'
+field. No LLM needed, no non-determinism, no cost, no flakiness.
+
+The scoring formula here is the exact one PCP's own validate-strategy prompt
+already specified — it was already fully deterministic, just being computed
+by an LLM instead of code. Community detection (graphify, if installed) is
+optional enrichment layered on top: it surfaces informal coupling — modules
+that cluster together beyond their declared dependencies — it does not feed
+the numeric coupling_score itself.
+"""
+
+import networkx as nx
+
+DEP_PENALTY = 0.1
+CYCLE_PENALTY = 0.2
+GOD_MODULE_PENALTY = 0.15
+GOD_MODULE_THRESHOLD = 3
+
+
+def _hub_modules(G: nx.DiGraph) -> set[str]:
+    """Modules more than half the other modules depend on — shared
+    infrastructure (a 'core' or 'utils' module), not harmful coupling.
+    Same reasoning graphify's own cluster() has an exclude_hubs_percentile
+    for: a widely-depended-on utility module skews naive graph metrics."""
+    n = G.number_of_nodes()
+    if n < 3:
+        return set()
+    threshold = n / 2
+    return {node for node, indeg in G.in_degree() if indeg > threshold}
+
+
+def build_dependency_graph(modules: dict[str, dict]) -> nx.DiGraph:
+    """modules: {module_name: spec_dict}. Edge A->B means A depends on B.
+    Dependencies pointing outside this module set are ignored (external/
+    already-built, not something this graph can score)."""
+    G = nx.DiGraph()
+    for name in modules:
+        G.add_node(name)
+    for name, spec in modules.items():
+        for dep in (spec.get("dependencies") or []):
+            if dep in modules and dep != name:
+                G.add_edge(name, dep)
+    return G
+
+
+def compute_coupling(G: nx.DiGraph) -> dict:
+    """Returns {coupling_score, coupling_violations, direct_dependencies,
+    circular_dependencies, god_modules, hub_modules} — same shape
+    validate-strategy's LLM prompt used to return, now computed directly.
+
+    Edges into a hub module (shared infrastructure) don't count against the
+    direct-dependency penalty — depending on a genuine shared kernel isn't
+    the harmful coupling this score is meant to catch. Cycles and god-modules
+    still count regardless of hub status: a cycle through 'core', or a module
+    with too many outgoing deps, is still a real structural problem."""
+    hubs = _hub_modules(G)
+    scored_edges = [(a, b) for a, b in G.edges if b not in hubs]
+    direct_deps = len(scored_edges)
+    cycles = [c for c in nx.simple_cycles(G) if len(c) > 1]
+    god_modules = [n for n in G.nodes if G.out_degree(n) > GOD_MODULE_THRESHOLD]
+
+    score = 1.0 - DEP_PENALTY * direct_deps - CYCLE_PENALTY * len(cycles) - GOD_MODULE_PENALTY * len(god_modules)
+    score = max(0.0, min(1.0, score))
+
+    violations = []
+    for cycle in cycles:
+        path = " -> ".join(cycle + [cycle[0]])
+        violations.append({
+            "type": "circular", "modules": cycle,
+            "description": f"Circular dependency: {path}",
+            "fix": "Break the cycle — extract a shared interface or invert one dependency.",
+        })
+    for n in god_modules:
+        deps = sorted(G.successors(n))
+        violations.append({
+            "type": "god_module", "modules": [n],
+            "description": f"'{n}' depends on {len(deps)} other modules: {', '.join(deps)}",
+            "fix": "Split into smaller modules or reduce dependencies.",
+        })
+    for a, b in sorted(scored_edges):
+        violations.append({
+            "type": "direct_dependency", "modules": [a, b],
+            "description": f"'{a}' directly depends on '{b}'",
+            "fix": "Confirm this is core infrastructure, not incidental coupling.",
+        })
+
+    return {
+        "coupling_score": round(score, 2),
+        "coupling_violations": violations,
+        "direct_dependencies": direct_deps,
+        "circular_dependencies": len(cycles),
+        "god_modules": god_modules,
+        "hub_modules": sorted(hubs),
+    }
+
+
+def compute_communities(G: nx.DiGraph) -> dict:
+    """Optional enrichment via graphify's community detection (Leiden/Louvain).
+    Advisory only — surfaces modules that cluster together, doesn't affect
+    coupling_score. Returns {"available": False} if graphify isn't installed."""
+    try:
+        from graphify.cluster import cluster, score_all
+    except ImportError:
+        return {"available": False}
+    if G.number_of_nodes() < 2:
+        return {"available": True, "communities": {}, "cohesion": {}}
+    communities = cluster(G)
+    cohesion = score_all(G, communities)
+    multi_node = {cid: nodes for cid, nodes in communities.items() if len(nodes) > 1}
+    return {"available": True, "communities": multi_node, "cohesion": {cid: cohesion[cid] for cid in multi_node}}
+
+
+def compute_change_coupling(project_root, modules: dict[str, dict], max_commits: int = 200) -> list[dict]:
+    """Git-history co-change analysis (CodeScene behavioral-analysis reference
+    pattern, 2026-07-17) — a second, independent coupling signal. Files that
+    change together over time reveal coupling a static import graph
+    structurally cannot see (implicit contracts, config coupling, copy-paste).
+    Deterministic (rung 1), zero LLM.
+
+    Maps commits to modules via each module's declared criterion `target`
+    files. Flags module pairs that co-change in >=50% of the less-active
+    module's commits (min 5 co-changes) AND have no declared dependency in
+    either direction — "hidden coupling", advisory only, never feeds
+    coupling_score.
+    """
+    import subprocess
+    from collections import defaultdict
+    from pathlib import Path as _P
+
+    module_files: dict[str, set] = {}
+    declared: set = set()
+    for name, m in modules.items():
+        targets = set()
+        for c in (m.get("acceptance") or {}).get("criteria", []):
+            if c.get("target"):
+                targets.add(c["target"].replace("\\", "/"))
+        module_files[name] = targets
+        for dep in (m.get("spec") or {}).get("dependencies", []) or []:
+            declared.add((name, dep))
+            declared.add((dep, name))
+
+    result = subprocess.run(
+        ["git", "log", f"-{max_commits}", "--name-only", "--pretty=format:@@COMMIT@@"],
+        capture_output=True, text=True, cwd=project_root,
+    )
+    if result.returncode != 0:
+        return []
+
+    commit_counts: dict[str, int] = defaultdict(int)
+    pair_counts: dict[tuple, int] = defaultdict(int)
+    for chunk in result.stdout.split("@@COMMIT@@"):
+        files = {f.strip().replace("\\", "/") for f in chunk.splitlines() if f.strip()}
+        if not files:
+            continue
+        touched = sorted(n for n, targets in module_files.items() if targets & files)
+        for n in touched:
+            commit_counts[n] += 1
+        for i in range(len(touched)):
+            for j in range(i + 1, len(touched)):
+                pair_counts[(touched[i], touched[j])] += 1
+
+    hidden = []
+    for (a, b), count in sorted(pair_counts.items()):
+        if count < 5 or (a, b) in declared:
+            continue
+        denom = min(commit_counts[a], commit_counts[b])
+        ratio = count / denom if denom else 0.0
+        if ratio >= 0.5:
+            hidden.append({
+                "modules": [a, b], "co_changes": count,
+                "ratio": round(ratio, 2),
+                "note": "co-change without declared dependency — possible hidden coupling",
+            })
+    return hidden

pcp/coverage_audit.py

@@ -0,0 +1,77 @@
+"""Coverage-score audit trail — mitigates Goodhart risk on validate-strategy's
+LLM-judged coverage_score. Unlike coupling_score (see coupling.py), coverage
+can't be made deterministic — "does this cover the objective" is genuinely
+semantic. What CAN be deterministic: catching internal inconsistency (a high
+score reported alongside real open gaps) and drift (the same inputs producing
+a meaningfully different score run to run). Both are surfaced, never silently
+corrected — same append-only audit-trail posture as decision_log.py/telemetry.py.
+"""
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+# A score this high alongside any open gap is internally inconsistent —
+# gaps are the real gate, the number shouldn't read as "basically done".
+INCONSISTENCY_THRESHOLD = 0.85
+
+# Score delta on unchanged objective/modules worth flagging as possible
+# LLM non-determinism rather than a real coverage change.
+DRIFT_THRESHOLD = 0.15
+
+
+def _hash_inputs(objective: str, modules: dict) -> str:
+    material = objective + "".join(f"{k}:{v}" for k, v in sorted(modules.items()))
+    return hashlib.sha256(material.encode()).hexdigest()[:12]
+
+
+def load(pcp_dir: Path) -> list[dict]:
+    path = Path(pcp_dir) / "coverage_audit.jsonl"
+    if not path.exists():
+        return []
+    records = []
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            records.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return records
+
+
+def record(pcp_dir: Path, coverage_score: float, gaps: list, objective: str, modules: dict) -> list[str]:
+    """Appends one entry to .pcp/coverage_audit.jsonl. Returns any findings
+    (inconsistency/drift) for the caller to surface — never raises, never
+    silently corrects the score itself."""
+    path = Path(pcp_dir) / "coverage_audit.jsonl"
+    inputs_hash = _hash_inputs(objective, modules)
+    findings: list[str] = []
+
+    if gaps and coverage_score >= INCONSISTENCY_THRESHOLD:
+        findings.append(
+            f"coverage_score reported {coverage_score:.0%} despite {len(gaps)} open gap(s) — "
+            "internally inconsistent, treat the score with skepticism (the gaps are the real gate)."
+        )
+
+    prior = load(pcp_dir)
+    same_input_runs = [r for r in prior if r.get("inputs_hash") == inputs_hash]
+    if same_input_runs:
+        last = same_input_runs[-1]
+        delta = abs(coverage_score - last["coverage_score"])
+        if delta >= DRIFT_THRESHOLD:
+            findings.append(
+                f"coverage_score drifted {last['coverage_score']:.0%} -> {coverage_score:.0%} "
+                "on an unchanged objective/module set — possible LLM non-determinism, not a real coverage change."
+            )
+
+    entry = {
+        "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "coverage_score": coverage_score, "gap_count": len(gaps), "inputs_hash": inputs_hash,
+        "findings": findings,
+    }
+    with open(path, "a") as f:
+        f.write(json.dumps(entry) + "\n")
+    return findings

pcp/decision_log.py

@@ -0,0 +1,134 @@
+"""Technical decision log — distilled from session/build-loop conversation.
+
+Distinct from telemetry.jsonl (build-cycle QA/cost events) — this is the
+*technical input* half of conversational drift capture (see capture.py for
+the classifier and its business-logic counterpart, brd_items.yaml). Append-only
+JSONL, one record per distilled technical decision/rationale. Auto-appended by
+`pcp capture`. Never edit.
+"""
+
+import json
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+from pcp.evidence_chain import chain_entry
+
+
+def record(pcp_dir: Path, **fields) -> None:
+    """Append one JSONL record to .pcp/decision_log.jsonl.
+
+    Suggested fields: source ("session:<id>"|"build:<module>:<criterion_id>"),
+    session_id, category (freeform, e.g. "library-choice"|"architecture"|"workaround"),
+    summary, evidence (quoted excerpt), module, criterion_id.
+    """
+    fields = {"timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), **fields}
+    path = Path(pcp_dir) / "decision_log.jsonl"
+    entry = chain_entry(_last_entry_hash(path), fields)
+    with open(path, "a") as f:
+        f.write(json.dumps(entry) + "\n")
+
+
+def _last_entry_hash(path: Path) -> str | None:
+    if not path.exists():
+        return None
+    last_line = None
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if line:
+            last_line = line
+    if not last_line:
+        return None
+    try:
+        return json.loads(last_line).get("entry_hash")
+    except json.JSONDecodeError:
+        return None
+
+
+def load(pcp_dir: Path) -> list[dict]:
+    path = Path(pcp_dir) / "decision_log.jsonl"
+    if not path.exists():
+        return []
+    records = []
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            records.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return records
+
+
+def select_relevant(pcp_dir: Path, module: str, limit: int | None = None,
+                    max_chars: int | None = None) -> list[dict]:
+    """Deterministic selection of decisions worth injecting into a build
+    agent's prompt (no LLM — rung 1). This closes the loop this file's own
+    docstring promised ("intended to feed future build-loop context") but
+    that never got built: records went in, nothing ever came out, so
+    criterion agent #14 re-discovered what agent #3 already learned.
+
+    Priority: this module's own decisions first (module field or
+    build:<module>: source), newest first; then module-less project-wide
+    decisions, newest first. Other modules' decisions are never injected —
+    cross-module context is what architecture.md is for.
+
+    Bounded twice (count and chars) — prompt injection must never become
+    its own token-discipline violation. PCP_BUILD_MAX_DECISIONS (default 6),
+    PCP_BUILD_DECISIONS_MAX_CHARS (default 2500)."""
+    import os
+    limit = limit if limit is not None else int(os.environ.get("PCP_BUILD_MAX_DECISIONS", "6"))
+    max_chars = max_chars if max_chars is not None else int(os.environ.get("PCP_BUILD_DECISIONS_MAX_CHARS", "2500"))
+    if limit <= 0:
+        return []
+
+    records = load(pcp_dir)
+    module_prefix = f"build:{module}:"
+
+    def _is_module_match(r: dict) -> bool:
+        return r.get("module") == module or str(r.get("source", "")).startswith(module_prefix)
+
+    def _ts(r: dict) -> str:
+        return r.get("timestamp", "")
+
+    matched = sorted([r for r in records if _is_module_match(r) and r.get("summary")], key=_ts, reverse=True)
+    global_ = sorted(
+        [r for r in records if not _is_module_match(r) and not r.get("module") and r.get("summary")],
+        key=_ts, reverse=True,
+    )
+
+    selected, used_chars = [], 0
+    for r in matched + global_:
+        if len(selected) >= limit:
+            break
+        line_len = len(_render_line(r))
+        if used_chars + line_len > max_chars:
+            continue
+        selected.append(r)
+        used_chars += line_len
+    return selected
+
+
+def _render_line(r: dict) -> str:
+    category = r.get("category") or "decision"
+    summary = str(r.get("summary", "")).strip()
+    return f"- [{category}] {summary}"
+
+
+def format_for_prompt(pcp_dir: Path, module: str) -> list[str]:
+    """Rendered lines for _build_agent_prompt. Empty list when there's nothing
+    to inject (or PCP_BUILD_INJECT_DECISIONS=0) — caller skips the section."""
+    import os
+    if os.environ.get("PCP_BUILD_INJECT_DECISIONS", "1") in ("0", "false", "no"):
+        return []
+    return [_render_line(r) for r in select_relevant(pcp_dir, module)]
+
+
+def aggregate(records: list[dict]) -> dict:
+    """Roll up decisions per category. Shared by `pcp telemetry`-style reporting
+    and the pcp.md 'Technical Decisions' section."""
+    by_category = defaultdict(list)
+    for r in records:
+        by_category[r.get("category") or "uncategorized"].append(r)
+    return {"by_category": by_category, "records": records}

pcp/discovery/clusters.py

@@ -0,0 +1,124 @@
+"""Cluster detection: find natural module boundaries from dependency graph.
+
+Algorithm: Union-Find on bidirectional edges, then group by top-level directory.
+Directory grouping is the primary signal — import graph refines it.
+Files with no cluster affinity (shared utils, config) → 'shared' pseudo-cluster.
+"""
+
+from collections import defaultdict
+from pathlib import Path
+
+
+class _UnionFind:
+    def __init__(self, nodes):
+        self.parent = {n: n for n in nodes}
+        self.rank = {n: 0 for n in nodes}
+
+    def find(self, x):
+        while self.parent[x] != x:
+            self.parent[x] = self.parent[self.parent[x]]
+            x = self.parent[x]
+        return x
+
+    def union(self, a, b):
+        ra, rb = self.find(a), self.find(b)
+        if ra == rb:
+            return
+        if self.rank[ra] < self.rank[rb]:
+            ra, rb = rb, ra
+        self.parent[rb] = ra
+        if self.rank[ra] == self.rank[rb]:
+            self.rank[ra] += 1
+
+
+def _top_dir(file_key: str) -> str:
+    parts = file_key.split("/")
+    if len(parts) == 1:
+        return "__root__"
+    # skip 'src/' prefix as it's not a domain
+    if parts[0] in ("src", "lib", "app", "pkg") and len(parts) > 2:
+        return parts[1]
+    return parts[0]
+
+
+def detect_clusters(
+    graph: dict[str, set[str]],
+    files: list[Path],
+    root: Path,
+) -> dict[str, list[str]]:
+    """
+    Returns {cluster_name: [file_key, ...]}
+
+    Strategy:
+    1. Primary grouping: top-level directory (or src/<dir>)
+    2. Refinement: if two directories are heavily cross-coupled (>50% of edges
+       cross between them), merge into one cluster
+    3. Root-level files with no dir affinity → 'shared'
+    """
+    file_keys = [str(f.relative_to(root)) for f in files]
+
+    # Step 1: group by top-level dir
+    dir_groups: dict[str, list[str]] = defaultdict(list)
+    for key in file_keys:
+        dir_groups[_top_dir(key)].append(key)
+
+    # Step 2: count cross-dir edges
+    cross: dict[tuple[str, str], int] = defaultdict(int)
+    internal: dict[str, int] = defaultdict(int)
+
+    for src, targets in graph.items():
+        src_dir = _top_dir(src)
+        for tgt in targets:
+            tgt_dir = _top_dir(tgt)
+            if src_dir == tgt_dir:
+                internal[src_dir] += 1
+            else:
+                key = tuple(sorted([src_dir, tgt_dir]))
+                cross[key] += 1
+
+    # Step 3: merge dirs where cross-edges > internal edges of both (tight coupling)
+    uf = _UnionFind(list(dir_groups.keys()))
+    for (a, b), cross_count in cross.items():
+        total_a = internal[a] + cross_count
+        total_b = internal[b] + cross_count
+        if total_a == 0 or total_b == 0:
+            continue
+        # merge if cross traffic is dominant in either direction
+        if cross_count / total_a > 0.6 or cross_count / total_b > 0.6:
+            uf.union(a, b)
+
+    # Step 4: build final clusters
+    clusters: dict[str, list[str]] = defaultdict(list)
+    for dir_name, file_list in dir_groups.items():
+        cluster_root = uf.find(dir_name)
+        # name: use the most specific dir in the merged group
+        cluster_name = cluster_root if cluster_root != "__root__" else "shared"
+        clusters[cluster_name].extend(file_list)
+
+    # rename __root__ entries
+    if "__root__" in clusters:
+        clusters["shared"].extend(clusters.pop("__root__"))
+
+    return dict(clusters)
+
+
+def compute_coupling_matrix(
+    graph: dict[str, set[str]],
+    clusters: dict[str, list[str]],
+) -> dict[tuple[str, str], int]:
+    """Count cross-cluster edges. High count = coupling violation."""
+    file_to_cluster = {}
+    for cluster, files in clusters.items():
+        for f in files:
+            file_to_cluster[f] = cluster
+
+    cross_edges: dict[tuple[str, str], int] = defaultdict(int)
+    for src, targets in graph.items():
+        src_cluster = file_to_cluster.get(src)
+        for tgt in targets:
+            tgt_cluster = file_to_cluster.get(tgt)
+            if src_cluster and tgt_cluster and src_cluster != tgt_cluster:
+                key = (src_cluster, tgt_cluster)
+                cross_edges[key] += 1
+
+    return dict(cross_edges)