How the Graph-Reviewer Agent Validates Knowledge Graph Completeness and Integrity

The graph-reviewer agent validates knowledge graph completeness and integrity through a deterministic Node.js validation script that enforces schema compliance, referential integrity, layer coverage, and uniqueness constraints, rejecting any graph containing critical issues while allowing quality warnings to pass.

In the Egonex-AI/Understand-Anything repository, the graph-reviewer agent serves as the final quality gate in the /understand pipeline. According to the specifications in /understand-anything-plugin/agents/graph-reviewer.md, this agent ensures that every assembled KnowledgeGraph is structurally sound, internally consistent, and sufficiently populated before reaching the dashboard or downstream analysis tools.

Two-Phase Validation Architecture

The validation process operates through two distinct phases to guarantee reproducible, deterministic results.

Phase 1 – Deterministic Validation Script

The agent generates a Node.js script (with Python fallback) that reads the assembled KnowledgeGraph JSON from .understand-anything/knowledge-graph.json. This script performs exhaustive checks and outputs a structured report containing three top-level arrays: issues for critical violations, warnings for non-critical observations, and stats for quantitative metrics including node counts, edge types, and layer breakdowns. The script always exits with code 0 unless it crashes, ensuring that validation failures are captured explicitly in the JSON output rather than through process exit codes.

Phase 2 – Decision Rendering

After script execution, the agent reads the intermediate results from .understand-anything/tmp/ua-review-results.json. It strips the internal scriptCompleted flag and writes the final assessment to .understand-anything/intermediate/review.json. The graph receives approval only when the issues array is empty; any number of warnings is acceptable and does not block approval.

Critical Integrity Checks

The deterministic script enforces five categories of critical validations that trigger automatic rejection when violated.

Schema Validation

Every node must contain required fields with correct types: id (string), type, name, summary, tags (array), and complexity. Edges require source, target, type, direction, and weight properties. Missing required fields or type mismatches generate critical issues that prevent approval.

Referential Integrity

All edge source and target IDs must resolve to existing node IDs in the graph. Additionally, every entry in layers[].nodeIds and every nodeId referenced in tour.steps must point to valid nodes. Any dangling pointer results in immediate rejection.

Completeness Requirements

The graph must contain at least one node, one edge, one layer, and one tour step. While the completeness of layers and tour steps generates warnings for domain graphs, these elements are critical requirements for standard repository graphs.

Layer Coverage and Uniqueness

Every file-level node—types including file, config, document, and service—must appear in exactly one layer's nodeIds array, and empty nodeIds arrays are prohibited. The script also verifies that all node IDs are globally unique within the graph.

Quality Assurance Warnings

Beyond critical checks, the script identifies quality concerns that preserve approval status but highlight potential improvements.

Tour Validation

Tour steps must have sequential order values starting at 1 with no duplicates. Each step must reference at least one node, and the total step count should fall between 5 and 15. Violations of these constraints generate warnings rather than critical issues.

Node Quality Heuristics

The script detects empty or generic summaries, self-referencing edges where source equals target, and orphan nodes lacking any incident edges. For non-code nodes—such as document, service, pipeline, table, schema, domain, or flow—the script verifies that at least one expected edge type exists (e.g., a document node should have an outgoing documents edge).

Prefix Consistency

Node types must align with their ID prefixes. For example, a node with type: "config" must have an ID starting with config:. Mismatches between the type declaration and the ID prefix generate warnings.

Implementation and Script Structure

The validation script is generated dynamically by the agent and executed against the knowledge graph JSON. Below is an excerpt from the generated ua-graph-validate.ts:

// ua-graph-validate.ts – generated by the graph-reviewer agent
import fs from "node:fs";

const [graphPath, outPath] = process.argv.slice(2);
const graph = JSON.parse(fs.readFileSync(graphPath, "utf-8"));

const report = {
  scriptCompleted: true,
  issues: [] as string[],
  warnings: [] as string[],
  stats: {
    totalNodes: graph.nodes.length,
    totalEdges: graph.edges.length,
    totalLayers: graph.layers?.length ?? 0,
    tourSteps: graph.tour?.steps?.length ?? 0,
    nodeTypes: {} as Record<string, number>,
    edgeTypes: {} as Record<string, number>,
  },
};

/* ---- Schema validation (critical) ---- */
for (const n of graph.nodes) {
  if (!n.id || typeof n.id !== "string") report.issues.push(`Node missing id`);
  // …additional field checks…
}

/* ---- Referential integrity (critical) ---- */
const nodeIds = new Set(graph.nodes.map((n) => n.id));
for (const e of graph.edges) {
  if (!nodeIds.has(e.source))
    report.issues.push(`Edge ${e.type} source '${e.source}' does not exist`);
  if (!nodeIds.has(e.target))
    report.issues.push(`Edge ${e.type} target '${e.target}' does not exist`);
}

/* ---- Additional checks omitted for brevity … ---- */

fs.writeFileSync(outPath, JSON.stringify(report, null, 2));
process.exit(0);

The agent invokes this script via command line:

node $PROJECT_ROOT/.understand-anything/tmp/ua-graph-validate.js \
  "$PROJECT_ROOT/.understand-anything/knowledge-graph.json" \
  "$PROJECT_ROOT/.understand-anything/tmp/ua-review-results.json"

After execution, the agent inspects ua-review-results.json to determine approval status based on the presence of critical issues.

Summary

• The graph-reviewer agent employs a two-phase deterministic validation process to ensure knowledge graph integrity in the Understand-Anything pipeline.
• Critical checks include schema validation, referential integrity, completeness requirements, layer coverage, and global uniqueness constraints.
• Quality warnings cover tour sequencing, node summary quality, self-referencing edges, and ID prefix inconsistencies without blocking approval.
• Validation reports are written to .understand-anything/intermediate/review.json, with final approval contingent on an empty issues array regardless of warning count.

Frequently Asked Questions

What file path does the graph-reviewer agent use for the knowledge graph input?

The agent reads the assembled graph from $PROJECT_ROOT/.understand-anything/knowledge-graph.json and writes the final validation report to .understand-anything/intermediate/review.json, with intermediate results stored in .understand-anything/tmp/ua-review-results.json.

Can a knowledge graph pass review with warnings?

Yes. According to the validation logic in agents/graph-reviewer.md, the agent approves graphs containing any number of warnings as long as the issues array remains empty. Only critical violations in schema compliance, referential integrity, or completeness trigger rejection.

What constitutes a critical issue versus a warning?

Critical issues include missing required fields, dangling references in edges or layers, empty graphs (no nodes/edges), duplicate node IDs, and file-level nodes not assigned to exactly one layer. Warnings include non-sequential tour steps, empty node summaries, self-referencing edges, orphan nodes without connections, and prefix inconsistencies between node type and ID.

Where is the graph-reviewer agent specification documented?

The complete validation workflow and deterministic check definitions are documented in /understand-anything-plugin/agents/graph-reviewer.md. Additional prompt templates for optional LLM-backed review modes are available in skills/understand/graph-reviewer-prompt.md, and unit tests exercising the validation logic reside in tests/skill/understand/test_merge_batch_graphs.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}