| name | sheaf-cohomology-multiagent-debug |
| version | 0.1.0 |
| description | Diagnose multi-agent coordination failures using sheaf cohomology as a structural telemetry primitive. When agents cannot reach consensus despite diffusion, the cause is often topological: restriction maps on one or more edges are mutually inconsistent, creating a cycle-level obstruction that no amount of additional messaging can dissolve. H¹(G,F) ≠ 0 is the formal certificate of this obstruction — it identifies which cycles contain irreconcilable disagreements, letting you debug the sheaf (the communication structure) rather than the swarm (the agents). This skill provides the conceptual framework, a concrete implementation pattern, and decision criteria for when cohomology is the right diagnostic vs. when simpler tools suffice.
|
| author | soma-windags-graft |
| tags | ["sheaf-cohomology","multi-agent","coordination","consensus","topology","diagnostics","active-inference","soma"] |
| pairs-with | [] |
| license | Apache-2.0 |
| allowed-tools | Read,Write,Edit,Glob,Grep |
| metadata | {"provenance":{"kind":"imported","source":"workgroup-ai / windags skill library (rehomed 2026-07-04)"}} |
Sheaf Cohomology as Multi-Agent Coordination Telemetry
When to Use
- Agents have been running diffusion / gossip / opinion-update dynamics for many steps and residual disagreement persists despite apparent convergence — you suspect the disagreement is structural, not transient.
- You have a cycle in the agent communication graph and at least one edge where two agents project their private state through different restriction maps into a shared discourse space (i.e., they literally interpret the shared variable differently).
- A new agent or communication channel was added and coordination degraded; you need to know whether the topology change introduced a cohomological obstruction.
NOT for:
- Debugging transient disagreement that resolves if you wait longer — that is a convergence-rate problem, diagnosed by the sheaf Fiedler value λ₂(L_F), not by cohomology.
- Keyword-based or heuristic detection of "conflict" in agent messages — this skill requires algebraically specified stalks and restriction maps, not free-text analysis.
- Systems where agents do not share an explicit algebraic state space (e.g., purely language-model ensembles with no vector stalks) — cohomology is not applicable without a defined linear structure.
Core Concepts
Cellular sheaf F on graph G = (V, E): An assignment of a finite-dimensional real vector space F(v) (the stalk) to each vertex, a space F(e) to each edge, and a linear restriction map F_{v ▹ e}: F(v) → F(e) for each incidence pair. Stalks encode private agent state; restriction maps encode how each agent projects state into the shared discourse on that edge.
Coboundary operator δ: C⁰(G;F) → C¹(G;F): The fundamental disagreement measurement. For edge e = (u, v):
(δx)_e = F_{v ▹ e}(x_v) - F_{u ▹ e}(x_u)
δx = 0 on every edge iff x is a global section — all agents are perfectly consistent after projection. The coboundary operator encodes the difference in what each agent contributes to the shared discourse on each link.
H⁰(G;F) = ker(δ): The space of global sections — assignments where every adjacent pair is consistent after restriction. dim(H⁰) counts the number of independent consensus modes. H⁰ = {0} means no consensus is topologically reachable from any initial condition. H⁰ is what sheaf diffusion converges toward; ker(L_F) = H⁰.
H¹(G;F) = Z¹ / im(δ): The obstruction group. Z¹ = ker(d₁: C¹ → C²); for graphs with no 2-simplices, Z¹ = C¹ = all of edge-stalk space. im(δ) is the set of edge discrepancies that can be explained by some choice of vertex data. H¹ is the quotient — edge discrepancy patterns that cannot be explained by any vertex assignment.
