# How Graph-Reviewer Validates Completeness and Referential Integrity in Egonex-AI Understand Anything

> Discover how graph-reviewer in Egonex-AI Understand Anything validates completeness and referential integrity using a Node.js script and optional LLM review. Learn more now!

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

---

**The graph-reviewer agent enforces completeness and referential integrity through a deterministic Node.js validation script that checks schema compliance, verifies all edges point to existing nodes, ensures layers and tours reference valid nodes, and confirms file-level entities appear in at least one layer, optionally augmented by an LLM review when the `--review` flag is provided.**

The **graph-reviewer** agent in the Egonex-AI Understand Anything repository serves as the final quality gate for the knowledge graph pipeline. Before the assembled graph proceeds to downstream processing, this agent executes a rigorous validation routine defined in [`understand-anything-plugin/agents/graph-reviewer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/graph-reviewer.md) to catch dangling references, schema violations, and coverage gaps.

## The Two-Stage Validation Architecture

The agent operates through a hybrid approach that prioritizes deterministic correctness over probabilistic interpretation.

### Stage 1: Inline Deterministic Validation (Always Executed)

The core validation logic resides in a Node.js script named `ua-inline-validate.cjs`, embedded directly within the agent definition at lines 19-85 of [`graph-reviewer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/graph-reviewer.md). This script executes unconditionally and performs hard-coded checks without LLM involvement. It reads the assembled graph from [`intermediate/assembled-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/intermediate/assembled-graph.json) and outputs findings to [`intermediate/review.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/intermediate/review.json).

### Stage 2: Optional LLM-Driven Review (--review Flag)

When users provide the `--review` flag, the orchestrator dispatches the graph-reviewer as an LLM sub-agent (lines 98-104 of the skill definition). This phase first runs the deterministic script, then adds human-style judgment on the findings. The LLM never replaces the script-based checks; it only contextualizes the results to approve or reject the graph based on the severity of issues discovered.

## Core Validation Checks in ua-inline-validate.cjs

The inline validator implements six critical categories of checks to ensure graph integrity.

### Schema Sanity and Structure Verification

The script validates that `graph.nodes` and `graph.edges` are arrays and that each node contains required fields: `id`, `type`, `name`, `summary`, and `tags`. Similarly, every edge must include `source` and `target` properties. These checks ensure the minimal structural shape required for downstream processing.

### Referential Integrity Enforcement

The validator maintains a set of valid node IDs and verifies that all references resolve to existing entities:

- **Edge validation**: For each edge in `graph.edges`, the script confirms that `e.source` and `e.target` exist in the node ID set (lines 44-45). Missing references trigger critical errors appended to the `issues` array.
- **Layer validation**: Each ID in `layer.nodeIds` must reference an existing node (line 54).
- **Tour step validation**: Each entry in `step.nodeIds` must resolve to a valid node (line 64).

These checks prevent dangling pointers that would break navigation or graph traversal.

### Completeness and Coverage Validation

Completeness ensures the graph fully represents the codebase structure. The validator specifically checks that **file-level nodes** (types such as `file` or `config`) appear in at least one layer. Lines 59-61 of the script iterate through file nodes and verify membership in the `assigned` map, pushing errors to the `issues` array if any file node lacks layer assignment.

### Uniqueness and Orphan Detection

The script detects duplicate node IDs at line 39, ensuring a deterministic namespace with no collisions. It also identifies **orphan nodes**—nodes with no incident edges—at line 72, though these are logged as warnings rather than critical errors, allowing isolated entities to pass with notice.

### Statistical Aggregation

For diagnostic purposes, the script collects counts of total nodes, edges, layers, and tour steps, plus per-type tallies (lines 74-80). This metadata provides a quick sanity snapshot in the final report.

## Execution Flow and Output Format

Understanding how the orchestrator invokes the validator helps integrate the graph-reviewer into custom pipelines.

### How the Orchestrator Invokes the Validator

The skill file at [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md) defines the execution command at lines 87-92:

```bash
node $PROJECT_ROOT/.understand-anything/tmp/ua-inline-validate.cjs \
  "$PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json" \
  "$PROJECT_ROOT/.understand-anything/intermediate/review.json"

```

The script writes a JSON object containing the `issues` and `warnings` arrays to the specified output path.

### Interpreting review.json Results

The orchestrator determines approval based on the `issues` array length. An empty `issues` array results in graph approval and progression to Phase 7. Non-empty `issues` cause rejection, with warnings displayed for non-critical observations like orphan nodes or generic summaries.

## Summary

- **The graph-reviewer** agent validates graphs through a deterministic Node.js script (`ua-inline-validate.cjs`) defined in [`understand-anything-plugin/agents/graph-reviewer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/graph-reviewer.md).
- **Referential integrity** is enforced by verifying that all edge sources/targets, layer node IDs, and tour step references point to existing nodes.
- **Completeness** is ensured by requiring file-level nodes to appear in at least one layer and validating that the graph contains all required structural elements.
- **Validation results** are written to [`intermediate/review.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/intermediate/review.json), with critical errors in the `issues` array and non-critical observations in `warnings`.
- **LLM review** is optional (triggered by `--review`) and augments but does not replace the deterministic script validation.

## Frequently Asked Questions

### What is the difference between issues and warnings in graph-reviewer?

**Issues** represent critical failures that block graph approval, such as missing node references, duplicate IDs, or schema violations. **Warnings** flag non-critical concerns like orphan nodes (nodes with no edges) or file nodes not assigned to layers, which may indicate incomplete analysis but do not prevent graph usage.

### Can the graph-reviewer validation run without LLM involvement?

Yes. By default, the graph-reviewer runs only the deterministic Node.js script (`ua-inline-validate.cjs`) embedded in the agent definition. The LLM-driven review phase executes only when the user explicitly provides the `--review` flag, making the agent suitable for automated CI/CD pipelines requiring deterministic, reproducible validation.

### Which file contains the actual validation logic for the graph-reviewer?

The validation logic is embedded in [`understand-anything-plugin/agents/graph-reviewer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/graph-reviewer.md) at lines 19-85. This inline script is written to `ua-inline-validate.cjs` at runtime and executed by the orchestrator. The skill definition in [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md) defines how the script is invoked and how results are interpreted.

### What happens if the graph-reviewer finds referential integrity errors?

If the deterministic script detects edges pointing to non-existent nodes, layer references to missing nodes, or other integrity violations, it appends these to the `issues` array in [`review.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/review.json). The orchestrator treats any non-empty `issues` array as a rejection criterion, preventing the graph from proceeding to Phase 7 and surfacing the specific reference errors for correction.