# How to Interpret Archify Validation Failure Diagnostics: A Complete Guide

> Learn to interpret Archify validation failure diagnostics. Understand what broke, where, and available automated fixes with this complete guide for the tt-a1i/archify repository.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-17

---

**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:

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

```

This produces output structured like the following:

```json
{
  "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:

```js
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`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md).

## Critical Sources in the Repository

These files define the diagnostic contracts and validation logic:

- **[`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md)** — AJV schema validation error format that underlies first-stage diagnostics
- **[`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md)** — Overall validation-and-delivery receipt structure
- **[`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md)** — Stable diagnostic fields (`code`, `subject`, `evidence`, `supportedFixes`) and agent consumption patterns
- **[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md) for precise field meanings, and edit the source diagram directly before revalidation.