Core Concepts
Conflict Detection
When multiple agents or team members write knowledge simultaneously, contradictions are inevitable. Spiral catches them automatically — before they corrupt your knowledge graph.
What Spiral catches
Contradictions
Two facts say conflicting things about the same topic. For example, one agent records "Auth uses JWT" while another records "Auth uses session cookies." Spiral detects semantic similarity between facts — even when they use different words and different keys.
Stale References
A fact depends on something that was deleted or superseded. For example, a feature references an API endpoint that was removed last week. Spiral flags the dependency so you can update or remove the stale reference.
Lock Conflicts
Two agents are editing the same area of the knowledge graph simultaneously. Spiral uses soft locks to prevent concurrent modifications and notifies both parties.
Constraint Violations
A change breaks a project constraint. For example, adding a 5th team member when the project has a "max 4 developers" constraint, or adding a feature that pushes scope beyond the agreed timeline.
Real-time notifications
Conflicts are delivered in real-time. When a conflict is detected, it appears immediately in:
- Your IDE — via the MCP tools (
list_conflicts_v1) - The Dashboard — conflict panel with details and resolution options
- The CLI —
spiral conflicts
Resolving conflicts
Every conflict can be resolved through any of these paths:
CRITICAL Contradiction: decision.auth_strategy
Fact A: "Using JWT for auth"
Fact B: "Using session cookies for auth"
$ spiral conflicts resolve <id> --keep A
Agents can also resolve conflicts directly via the resolve_conflict_v1 MCP tool, or you can resolve them in the Dashboard.
Severity levels
| Severity | Meaning |
|---|---|
| Critical | Direct contradiction — must resolve before proceeding |
| Warning | Potential issue — should review (e.g. dependency changed) |
| Info | Informational — no immediate action needed |