How to Interpret Archify Validation Failure Diagnostics: A Complete Guide

Archify validation failure diagnostics are deterministic, machine-readable JSON objects that tell you exactly what broke, where it occurred, and which automated fixes are available.

Every diagram processed by the tt-a1i/archify toolchain undergoes strict validation against a JSON IR schema and runtime rules. When validation fails, the CLI returns a structured diagnostic format designed for programmatic consumption—not ambiguous logs. This guide explains how to decode these diagnostics and apply fixes efficiently.

Understanding the Validation Response Structure

The archify CLI returns a single JSON object with two top-level fields:

• validation — A human-readable summary string (e.g., "9/9 showcase, 0 errors, 0 warnings")
• diagnostics[] — An ordered array of failure entries, each following a stable contract

Even on successful validation, diagnostics[] is present as an empty array. This additive design guarantees consistent parsing across all outcomes.

Core Diagnostic Fields Explained

Each entry in diagnostics[] contains these key properties:

Field	Purpose
code	Stable rule identifier (e.g., DUPLICATE_ID, OVERLAP, UNKNOWN_BOUNDARY)
severity	error, warning, or info — determines if delivery is blocked
subject	JSON-Pointer to the offending element, annotated with id or label
evidence	Machine-readable measurement triggering the rule
supportedFixes	Repair actions the Skill can apply automatically
labelAt, labelDx, labelDy	Optional geometry hints for precise label placement

The format is tied to schema_version: 1 and maintains backward compatibility—new codes may be added, but existing codes never change.

Running Validation and Inspecting Diagnostics

Execute validation with JSON output using the CLI:

node bin/archify.mjs validate architecture diagram.json --json

This produces output structured like the following:

{
  "validation": "5/9 showcase, 4 errors, 0 warnings",
  "diagnostics": [
    {
      "code": "DUPLICATE_ID",
      "severity": "error",
      "subject": "/components/4 (id: \"frontend\")",
      "evidence": "id \"frontend\" already used by /components/1",
      "supportedFixes": ["renameId"]
    },
    {
      "code": "OVERLAP",
      "severity": "error",
      "subject": "/components/2",
      "evidence": "overlap with /components/3: 12px",
      "supportedFixes": ["moveNode"],
      "labelAt": { "x": 240, "y": 180 }
    }
  ]
}

The subject field uses JSON-Pointer syntax (/components/3) combined with contextual identifiers, making manual or automated location straightforward.

Applying Fixes from Supported Repairs

The supportedFixes array lists automated repair strategies. Common values include:

• renameId — Generate a unique identifier for duplicate ID conflicts
• moveNode — Resolve geometric overlaps by repositioning elements
• addLabelAt — Insert missing labels at specified coordinates

For programmatic repair loops, consume diagnostics as shown in this pseudocode:

const result = await validate('architecture', 'diagram.json', { json: true });

for (const diagnostic of result.diagnostics) {
  if (diagnostic.supportedFixes.includes('renameId')) {
    diagram = renameId(diagram, diagnostic.subject, makeUniqueId());
  }
}

await writeFile('diagram.json', diagram);
await validate('architecture', 'diagram.json', { json: true }); // second round

The Archify Skill enforces a maximum of two repair rounds, as documented in archify/SKILL.md.

Critical Sources in the Repository

These files define the diagnostic contracts and validation logic:

• archify/schemas/README.md — AJV schema validation error format that underlies first-stage diagnostics
• archify/references/delivery-contract.md — Overall validation-and-delivery receipt structure
• archify/references/authoring-contract.md — Stable diagnostic fields (code, subject, evidence, supportedFixes) and agent consumption patterns
• archify/SKILL.md — Practical guidance for automated repair loops and the two-round limit

Reference these documents together to resolve any validation failure completely.

Common Diagnostic Codes and Meanings

Code	Typical Cause	Primary Fix
DUPLICATE_ID	Same identifier used for multiple components	renameId
OVERLAP	Geometric collision between nodes	moveNode
UNKNOWN_BOUNDARY	Reference to non-existent boundary element	manual correction

Always prioritize error severity diagnostics over warning or info — only zero errors permits delivery.

Summary

• Archify validation failure diagnostics are deterministic JSON objects, not free-form logs
• Each diagnostic specifies code, severity, subject, evidence, and supportedFixes
• The CLI outputs consistent structure via node bin/archify.mjs validate <type> diagram.json --json
• Automated repair loops should respect the two-round maximum enforced by the Skill
• The JSON receipt—not exit codes—is the authoritative validation status source

Frequently Asked Questions

What does the subject field format mean?

The subject field combines a JSON-Pointer path with a contextual identifier in parentheses. For example, /components/4 (id: "frontend") points to the fifth element in the components array and notes its current ID. This dual format supports both programmatic traversal and human readability.

Can I rely on diagnostic codes for long-term automation?

Yes. The schema_version: 1 contract guarantees additive changes only—existing code values remain stable across releases. New validation rules introduce new codes without modifying existing ones, making diagnostics safe for persistent automation scripts.

Why is diagnostics[] empty on successful validation?

The empty array maintains response structure consistency. Your parsing logic can unconditionally iterate diagnostics[] without conditional checks for field existence, simplifying both CLI wrappers and CI integrations.

What happens if fixes don't resolve all diagnostics after two rounds?

The Archify Skill enforces a hard limit of two repair rounds. Persistent failures require manual intervention—examine the remaining diagnostics[] entries, consult archify/references/authoring-contract.md for precise field meanings, and edit the source diagram directly before revalidation.

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