graph-integrity-validator

name	graph-integrity-validator
description	Validates the agent graph for orphaned references and broken links. Runs automatically before any swarm execution.
version	1.0.0

Graph Integrity Validator

Purpose: Automatically detect and prevent broken references in the agent system, ensuring 100% sync with knowledge and abilities.

Core Principle

Every reference in the system MUST have a corresponding source file. This is the "Backlink Rule" – a reference implies an obligation to maintain the target.

---

Automated Validation Rules

Rule 1: Node-to-Skill Validation

Every node in agents.graph.json with a skillPath MUST have:

• A corresponding directory at that path
• A SKILL.md file inside that directory

// Pseudo-code for validation
for (const node of graph.nodes) {
  if (node.skillPath && !existsSync(join('.agent', node.skillPath, 'SKILL.md'))) {
    throw new GraphIntegrityError(`Orphaned Node: ${node.id} references missing skill at ${node.skillPath}`);
  }
}

Rule 2: Edge-to-Node Validation

Every edge in agents.graph.json MUST have:

• A from node that exists in graph.nodes
• A to node that exists in graph.nodes

const nodeIds = new Set(graph.nodes.map(n => n.id));
for (const edge of graph.edges) {
  if (!nodeIds.has(edge.from)) throw new GraphIntegrityError(`Dangling Edge: 'from' node "${edge.from}" does not exist.`);
  if (!nodeIds.has(edge.to)) throw new GraphIntegrityError(`Dangling Edge: 'to' node "${edge.to}" does not exist.`);
}

Rule 3: Team-Member Validation

Every TeamNode with memberIds MUST have:

• All member IDs corresponding to existing nodes in graph.nodes

for (const node of graph.nodes.filter(n => n.type === 'team')) {
  for (const memberId of node.memberIds) {
    if (!nodeIds.has(memberId)) {
      throw new GraphIntegrityError(`Team "${node.id}" has orphaned member: "${memberId}"`);
    }
  }
}

---

Self-Healing Protocol

When a violation is detected, the system should:

1. LOG the error to .agent/memory/integrity-violations.log
2. WARN the user via console output
3. BLOCK the swarm execution until resolved
4. SUGGEST a fix (e.g., "Remove node 'lint-and-validate' or create skill at .agent/skills/lint-and-validate")

---

Backlink System (Bidirectional References)

To prevent orphaned references, we implement a Backlink Registry.

Implementation

1. On Skill Creation: When a new skill is created, the system automatically adds its ID to agents.graph.json if not present.
2. On Skill Deletion: Before a skill directory is deleted, the system scans for all references to it and removes them.

Backlink Registry File: .agent/memory/backlinks.json

{
  "lint-and-validate": {
    "referencedBy": [
      ".agent/graph/agents.graph.json#edges[382]",
      ".agent/skills/clean-code/SKILL.md#line:161"
    ]
  }
}

This file is auto-generated by a pre-commit hook or bootstrap script.

---

Integration with Bootstrap

The bootstrap.ts script MUST run this validator as its first step.

// In bootstrap.ts
import { validateGraphIntegrity } from './validators/graph-integrity.js';

async function main() {
  console.log('🔗 Validating Agent Graph Integrity...');
  const violations = await validateGraphIntegrity();

  if (violations.length > 0) {
    console.error(`❌ ${violations.length} integrity violations found. Aborting.`);
    violations.forEach(v => console.error(`  - ${v}`));
    process.exit(1);
  }

  console.log('✅ Graph Integrity: OK');
  // ... rest of bootstrap
}

---

Learning from Errors: The "Post-Mortem" Protocol

When an integrity error is discovered, the system should:

1. Record the error in .agent/memory/lessons_learned.json
2. Categorize the error (e.g., orphaned-reference, type-mismatch, missing-import)
3. Create a preventative rule in .agent/rules/LEARNED_RULES.md

Example Lesson Entry

{
  "id": "lesson-20260207-001",
  "errorType": "orphaned-reference",
  "description": "Node 'lint-and-validate' existed in graph but skill directory was deleted.",
  "rootCause": "Manual deletion of skill folder without updating graph.json.",
  "fix": "Removed orphaned node and edge from agents.graph.json.",
  "preventativeRule": "Always use the `delete-skill.ts` script to remove skills. It handles backlink cleanup."
}