fix(decomposer): granularity-qualified cycle findings with real edge evidence

Review of the v0.1.0 self-decomposition found the cycle findings citing
fabricated evidence: the rendered "cycle path" was the alphabetically
sorted SCC joined with arrows, asserting import edges that do not exist,
graded certain/error on a self-declared probable module model.

- Compute cycles at file AND directory granularity. File-level cycles are
  error/certain with inducing file edges attached; directory-level cycles
  become an explicitly labeled directory_aggregation_cycle gate at
  warning/probable (confidence capped at the module model's), citing every
  real module edge with weights plus sample file edges.
- New granularity_divergence finding when the file graph is a DAG but
  directory cycles exist, so DAG-vs-cycles disagreements between pipeline
  artifacts surface as findings instead of passing silently.
- shared_kernel independence check now catches sibling-package imports
  (was top-level-only, missing the real shared_kernel -> inspection edge
  that pyproject's import-linter contract exempts via ignore_imports).
- Bidirectional-coupling violations cite file edges in both directions.
- Interface fallback honors its documented contract: file basenames only
  when no symbol xrefs cross in (was mixing filenames with symbols).
- test_gap gate restricted to TESTABLE_LANGUAGES, dropping docker/proto
  false positives while keeping domain/ports and ui/views signal.
- Report: bundle provenance line (path, run_manifest sha256, generated_at,
  extensions), unique part ids in tables, domain overlays out of the parts
  inventory, gate example subjects, {a <-> b} cycle groups in build order,
  full column legend and ABox confidence-vocabulary mapping.
- model/parts: operational + documentation part kinds from a parallel
  session's work on parts.py; included to keep the committed tree coherent.

10 new regression tests (test_cycle_findings.py) plus 7 report-contract
assertions in the smoke suite; full suite 95 passed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Pedro Anisio Silva

decomposer/architecture.py

@@ -12,11 +12,12 @@
 
 from .evidence import EvidenceGraph
 from .model import Architecture, Confidence, Hypothesis, Violation
-from .parts import ModuleGraph, ROOT
+from .parts import ModuleGraph, ROOT, file_edges_between
 
 
 def detect_architecture(
-    ev: EvidenceGraph, mg: ModuleGraph, module_cycles: list[list[str]]
+    ev: EvidenceGraph, mg: ModuleGraph,
+    module_cycles: list[list[str]], file_cycles: list[list[str]],
 ) -> Architecture:
     top_segments = {_top(m) for m in mg.modules() if m != ROOT}
     all_segments = {seg for m in mg.modules() for seg in PurePosixPath(m).parts}
@@ -79,7 +80,7 @@ def detect_architecture(
     # ── choose dominant style ───────────────────────────────────────────────
     style, style_conf = _dominant(labels)
 
-    violations = _violations(ev, mg, module_cycles)
+    violations = _violations(ev, mg, module_cycles, file_cycles)
     return Architecture(
         style=style, confidence=style_conf,
         evidence=_dedupe(evidence), violations=violations, hypotheses=hypotheses,
@@ -103,45 +104,78 @@ def _dominant(labels: list[tuple[str, Confidence]]) -> tuple[str, Confidence]:
 
 
 def _violations(
-    ev: EvidenceGraph, mg: ModuleGraph, module_cycles: list[list[str]]
+    ev: EvidenceGraph, mg: ModuleGraph,
+    module_cycles: list[list[str]], file_cycles: list[list[str]],
 ) -> list[Violation]:
     out: list[Violation] = []
 
-    for cyc in module_cycles:
+    # File-level cycles are extractor-graph facts: CERTAIN, with the edges named.
+    for cyc in file_cycles:
+        members = set(cyc)
+        edges = sorted(
+            f"{a} -> {b}"
+            for a in cyc for b in ev.imports_out.get(a, []) if b in members
+        )
         out.append(Violation(
             kind="circular_dependency",
-            description=f"Import cycle across {len(cyc)} modules: {' -> '.join(cyc)} -> {cyc[0]}.",
-            confidence=Confidence.CERTAIN, subjects=[f"module:{m}" for m in cyc],
+            description=(f"File-level import cycle among {len(cyc)} files: "
+                         + "; ".join(edges) + "."),
+            confidence=Confidence.CERTAIN, subjects=sorted(cyc),
+        ))
+
+    # Directory-level cycles exist only under the module==directory aggregation
+    # (a `probable` model), so the finding inherits that confidence and cites
+    # the real inducing edges instead of a chain through the sorted SCC.
+    for cyc in module_cycles:
+        members = set(cyc)
+        edge_strs = [
+            f"{a} -> {b} (x{w})" for (a, b), w in sorted(mg.edge_weight.items())
+            if a in members and b in members
+        ]
+        out.append(Violation(
+            kind="directory_aggregation_cycle",
+            description=(
+                f"{len(cyc)} directories are mutually reachable under "
+                f"directory aggregation (file-level graph "
+                f"{'is acyclic' if not file_cycles else 'also has cycles'}). "
+                f"Inducing edges: " + "; ".join(edge_strs) + "."),
+            confidence=Confidence.PROBABLE, subjects=[f"module:{m}" for m in cyc],
         ))
 
-    # Shared-kernel independence: a kernel package should not import outward into
-    # sibling feature packages. Any such edge is a graph fact (CERTAIN) and a
-    # recognized anti-pattern; the repo's own import-linter encodes the same rule.
+    # Shared-kernel independence: a kernel package should not import outward —
+    # not into sibling feature packages, not into its parent package. The cited
+    # file edges are graph facts (CERTAIN); this mirrors the import-linter
+    # "forbidden" contract shape (source: kernel, forbidden: everything outside).
     for m in mg.modules():
         segs = set(PurePosixPath(m).parts)
         if not (segs & {"shared_kernel", "kernel"}):
             continue
-        kernel_top = _top(m)
         outward = [d for d in mg.adjacency.get(m, [])
-                   if _top(d) != kernel_top]
+                   if not (d == m or d.startswith(m + "/"))]
         if outward:
+            edges = [e for d in outward for e in file_edges_between(ev, mg, m, d)]
             out.append(Violation(
                 kind="shared_kernel_not_independent",
                 description=(f"Shared-kernel module `{m}` imports outward into "
-                             f"{outward}, coupling the kernel to feature packages."),
+                             f"{outward}, coupling the kernel to the packages "
+                             f"it should serve. File edges: " + "; ".join(edges) + "."),
                 confidence=Confidence.CERTAIN,
                 subjects=[f"module:{m}"] + [f"module:{d}" for d in outward],
             ))
 
-    # Bidirectional module coupling (two-way import between packages).
+    # Bidirectional module coupling (two-way import between directories) —
+    # phrased on the directory model, hence PROBABLE, with file edges cited.
     seen: set[frozenset[str]] = set()
-    for (a, b) in mg.edge_weight:
+    for (a, b) in sorted(mg.edge_weight):
         if (b, a) in mg.edge_weight and frozenset({a, b}) not in seen:
             seen.add(frozenset({a, b}))
+            fwd = file_edges_between(ev, mg, a, b, limit=2)
+            rev = file_edges_between(ev, mg, b, a, limit=2)
             out.append(Violation(
                 kind="bidirectional_coupling",
-                description=f"Modules `{a}` and `{b}` import each other.",
-                confidence=Confidence.CERTAIN,
+                description=(f"Directories `{a}` and `{b}` import each other. "
+                             f"File edges: " + "; ".join(fwd + rev) + "."),
+                confidence=Confidence.PROBABLE,
                 subjects=[f"module:{a}", f"module:{b}"],
             ))
     return out

decomposer/decompose.py

@@ -33,15 +33,19 @@ def decompose(bundle_dir: str | Path) -> Decomposition:
 
     module_names = [m for m in mg.modules() if _has_code(ev, mg, m)]
     module_cycles = _cycles(module_names, mg.adjacency)
+    # Cycles at file granularity too: directory aggregation both manufactures
+    # cycles (parent/child re-exports) and hides them, so topology claims are
+    # only honest when both granularities are computed and reported.
+    file_cycles = _cycles([f["path"] for f in ev.files], ev.imports_out)
     cycle_modules = {m for cyc in module_cycles for m in cyc}
 
     module_parts = build_module_parts(ev, mg, cycle_modules)
     cross_parts = build_cross_cutting_parts(ev, mg)
     parts = module_parts + cross_parts
 
     relationships = _relationships(ev, mg)
-    architecture = detect_architecture(ev, mg, module_cycles)
-    gates = run_gates(ev, mg, module_cycles)
+    architecture = detect_architecture(ev, mg, module_cycles, file_cycles)
+    gates = run_gates(ev, mg, module_cycles, file_cycles)
 
     module_part_ids = {p.id for p in module_parts}
     order_layers = _build_order(module_names, mg.adjacency)
@@ -51,8 +55,8 @@ def decompose(bundle_dir: str | Path) -> Decomposition:
     ]
     build_order = [layer for layer in build_order if layer]
 
-    repository = _repository_header(ev, parts, module_cycles)
-    provenance = _provenance(ev, mg, parts, gates)
+    repository = _repository_header(ev, parts, module_cycles, file_cycles)
+    provenance = _provenance(ev, mg, parts, gates, module_cycles)
 
     return Decomposition(
         repository=repository,
@@ -129,7 +133,8 @@ def _relationships(ev: EvidenceGraph, mg: ModuleGraph) -> list[Relationship]:
 
 
 def _repository_header(
-    ev: EvidenceGraph, parts: list[Part], module_cycles: list[list[str]]
+    ev: EvidenceGraph, parts: list[Part],
+    module_cycles: list[list[str]], file_cycles: list[list[str]],
 ) -> dict:
     m = ev.manifest
     purpose, purpose_conf = _purpose(ev)
@@ -149,6 +154,7 @@ def _repository_header(
         "files": (m.get("counts") or {}).get("files"),
         "n_parts": len(parts),
         "n_module_cycles": len(module_cycles),
+        "n_file_cycles": len(file_cycles),
     }
 
 
@@ -169,12 +175,19 @@ def _purpose(ev: EvidenceGraph) -> tuple[str, Confidence]:
     return ("Not determinable from bundle evidence.", Confidence.UNKNOWN)
 
 
-def _provenance(ev: EvidenceGraph, mg: ModuleGraph, parts, gates) -> dict:
+def _provenance(
+    ev: EvidenceGraph, mg: ModuleGraph, parts, gates,
+    module_cycles: list[list[str]],
+) -> dict:
     from collections import Counter
     kinds = Counter(p.kind for p in parts)
     return {
         "tool": TOOL_ID,
         "bundle_dir": str(ev.bundle_dir),
+        "run_manifest_sha256": ev.manifest_sha256,
+        "bundle_generated_at": ev.manifest.get("generated_at"),
+        "bundle_extensions": sorted((ev.manifest.get("extensions") or {}).keys()),
+        "module_cycles": [list(c) for c in module_cycles],
         "evidence_basis": (
             "Structural parts, dependencies, coupling metrics (Ca/Ce, Martin "
             "instability), cycles and build order are mechanically derived from "

decomposer/evidence.py

@@ -17,6 +17,7 @@
 """
 from __future__ import annotations
 
+import hashlib
 import json
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -52,6 +53,7 @@ class EvidenceGraph:
     schema_purposes: dict[str, dict[str, Any]]     # path -> {text, model, ...}  (LLM, unverified)
     phases: dict[str, list[str]]                   # path -> phase local names
     rust_items: list[dict[str, Any]] = field(default_factory=list)
+    manifest_sha256: str = ""                      # run identity for provenance
 
     # ── convenience accessors ────────────────────────────────────────────────
     def code_files(self) -> list[dict[str, Any]]:
@@ -102,9 +104,21 @@ def load_evidence(bundle_dir: str | Path) -> EvidenceGraph:
         schema_purposes=b.enrichment_schema_purpose,
         phases=phases,
         rust_items=b.rust_items,
+        manifest_sha256=_manifest_sha256(bundle_dir),
     )
 
 
+def _manifest_sha256(bundle_dir: Path) -> str:
+    """Hash of run_manifest.json — the bundle's run identity. Decomposition
+    consumers need it to tell apart bundles built from the same commit with
+    different plugin sets (concepts present vs. absent, etc.)."""
+    manifest = bundle_dir / "run_manifest.json"
+    try:
+        return hashlib.sha256(manifest.read_bytes()).hexdigest()
+    except OSError:
+        return ""
+
+
 def _load_bundle(bundle_dir: Path):
     """Import seam. Kept in its own function so the ``frontend`` dependency has a
     single, replaceable call site (see module docstring)."""

decomposer/model.py

@@ -56,7 +56,7 @@ def weakest(cls, *values: "Confidence") -> "Confidence":
 PART_KINDS = frozenset({
     "file", "module", "package", "application", "service", "library",
     "external_dependency", "entrypoint", "domain", "data_schema",
-    "generated_artifact",
+    "generated_artifact", "operational", "documentation",
 })
 ROLES = frozenset({
     "core", "supporting", "infrastructure", "adapter", "test", "generated",

decomposer/parts.py

@@ -120,16 +120,20 @@ def _compute_interfaces(ev: EvidenceGraph, mg: ModuleGraph) -> None:
         if sym and sym != "<file>":
             iface.setdefault(dm, set()).add(sym)
 
-    # Fallback: files imported across the module boundary are public surface.
+    # Fallback: files imported across the module boundary are public surface —
+    # only for modules with NO symbol-level xrefs crossing in, so a module's
+    # interface list is either symbols or file basenames, never a mix.
+    fallback: dict[str, set[str]] = {}
     for src, targets in ev.imports_out.items():
         sm = mg.module_of_file.get(src)
         for dst in targets:
             dm = mg.module_of_file.get(dst)
             if dm and sm != dm:
-                iface.setdefault(dm, set()).add(PurePosixPath(dst).name)
+                fallback.setdefault(dm, set()).add(PurePosixPath(dst).name)
 
     for m in mg.files_of_module:
-        mg.interfaces[m] = sorted(iface.get(m, set()))[:40]
+        surface = iface.get(m) or fallback.get(m, set())
+        mg.interfaces[m] = sorted(surface)[:40]
         mg.xref_in[m] = xin.get(m, 0)
         mg.xref_out[m] = xout.get(m, 0)
 
@@ -229,6 +233,8 @@ def build_cross_cutting_parts(ev: EvidenceGraph, mg: ModuleGraph) -> list[Part]:
     parts.extend(_domain_parts(ev))
     parts.extend(_data_schema_parts(ev, mg))
     parts.extend(_generated_parts(ev, mg))
+    parts.extend(_operational_parts(ev))
+    parts.extend(_documentation_part(ev))
     return parts
 
 
@@ -442,7 +448,91 @@ def _generated_parts(ev: EvidenceGraph, mg: ModuleGraph) -> list[Part]:
     return parts
 
 
+# Operational categories, keyed by the extractor's *certain* file-type facts.
+# Each category becomes one ``operational`` part so build/CI/deploy/runtime-env
+# concerns are first-class parts even when their files live outside any
+# code-bearing module (e.g. a root Dockerfile).
+_OPERATIONAL_CATEGORIES: list[tuple[str, frozenset[str], str]] = [
+    ("build_system", frozenset({"build_script"}),
+     "Build orchestration (make/gradle/cmake-style entry tasks)."),
+    ("dependency_management", frozenset({"dependency_manifest", "lockfile"}),
+     "Dependency declaration and version pinning."),
+    ("ci_cd", frozenset({"ci_cd"}),
+     "Continuous integration / delivery pipeline definitions."),
+    ("deployment", frozenset({"container"}),
+     "Container / deployment topology definitions."),
+    ("runtime_configuration", frozenset({"configuration", "environment"}),
+     "Runtime and tooling configuration, environment variables."),
+]
+
+
+def _operational_parts(ev: EvidenceGraph) -> list[Part]:
+    parts: list[Part] = []
+    for name, types, responsibility in _OPERATIONAL_CATEGORIES:
+        files = sorted(f["path"] for f in ev.files if f.get("type") in types)
+        if not files:
+            continue
+        parts.append(Part(
+            id=f"ops:{name}", name=name, kind="operational",
+            layer="operational",
+            responsibility=responsibility,
+            responsibility_confidence=Confidence.STRONG,
+            evidence=Evidence(
+                files=files,
+                signals=[f"{len(files)} file(s) of type {sorted(types)}"],
+            ),
+            classification=Classification(
+                role="infrastructure", role_confidence=Confidence.CERTAIN,
+                reusability="internal", risk="low",
+            ),
+            metrics={"n_files": len(files), "file_types": sorted(types)},
+            overall_confidence=Confidence.CERTAIN,
+        ))
+    return parts
+
+
+def _documentation_part(ev: EvidenceGraph) -> list[Part]:
+    files = sorted(f["path"] for f in ev.files if f.get("type") == "documentation")
+    if not files:
+        return []
+    return [Part(
+        id="docs:documentation", name="documentation", kind="documentation",
+        layer="operational",
+        responsibility="Project documentation (READMEs, guides, specs).",
+        responsibility_confidence=Confidence.CERTAIN,
+        evidence=Evidence(
+            files=files,
+            signals=[f"{len(files)} documentation file(s)"],
+        ),
+        classification=Classification(
+            role="supporting", role_confidence=Confidence.CERTAIN,
+            reusability="internal", risk="low",
+        ),
+        metrics={"n_files": len(files)},
+        overall_confidence=Confidence.CERTAIN,
+    )]
+
+
 # ── helpers ───────────────────────────────────────────────────────────────────
+def file_edges_between(
+    ev: EvidenceGraph, mg: ModuleGraph, src_mod: str, dst_mod: str, limit: int = 3,
+) -> list[str]:
+    """The file-level import edges inducing the aggregated ``src_mod -> dst_mod``
+    module edge, as ``"src.py -> dst.py"`` strings. This is the evidence every
+    cycle/coupling finding must cite: module-level claims are only as good as
+    the file edges underneath them."""
+    out: list[str] = []
+    for src in sorted(ev.imports_out):
+        if mg.module_of_file.get(src) != src_mod:
+            continue
+        for dst in sorted(ev.imports_out[src]):
+            if mg.module_of_file.get(dst) == dst_mod:
+                out.append(f"{src} -> {dst}")
+                if len(out) >= limit:
+                    return out
+    return out
+
+
 def _subtree_files(ev: EvidenceGraph, root: str) -> list[str]:
     prefix = "" if root == ROOT else root + "/"
     return [f["path"] for f in ev.files