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

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 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. This script executes unconditionally and performs hard-coded checks without LLM involvement. It reads the assembled graph from intermediate/assembled-graph.json and outputs findings to 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 defines the execution command at lines 87-92:

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.
• 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, 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 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 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. 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.

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