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

> Learn how the graph-reviewer agent validates knowledge graph completeness and integrity using a Node.js script to enforce schema, referential integrity, and uniqueness, ensuring high-quality data.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-28

---

**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`](https://github.com/Egonex-AI/Understand-Anything/blob/main//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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/tmp/ua-review-results.json). It strips the internal `scriptCompleted` flag and writes the final assessment to [`.understand-anything/intermediate/review.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ua-graph-validate.ts):

```typescript
// 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:

```bash
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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/intermediate/review.json), with intermediate results stored in [`.understand-anything/tmp/ua-review-results.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main//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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/skills/understand/graph-reviewer-prompt.md), and unit tests exercising the validation logic reside in [`tests/skill/understand/test_merge_batch_graphs.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/tests/skill/understand/test_merge_batch_graphs.py).