# What Information Is Included in Archify's Diagnostic Output?

> Explore Archify's diagnostic output. Understand the structured JSON receipt, including codes, messages, locations, evidence, and supported fixes for errors. Improve your workflow now.

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

---

**Archify returns a structured JSON receipt containing a `diagnostics` array where each object specifies a namespaced `code`, human-readable `message`, pinpointed `subject` location, structured `evidence` values, and actionable `supportedFixes` for every validation or compilation error.**

Whenever a workflow validation or compilation fails, the `tt-a1i/archify` repository's CLI emits a machine-readable diagnostic report instead of plain text errors. Understanding what information is included in Archify's diagnostic output allows developers to programmatically parse failures, automate remediation, and integrate with CI/CD pipelines without fragile string matching.

## JSON Receipt Structure

When running commands with the `--json` flag (e.g., `archify deliver … --json`), Archify returns a top-level receipt object. This wrapper contains metadata about the command execution and the array of issues found.

The receipt always includes:

- **`ok`**: Boolean indicating success or failure.
- **`stage`**: String identifying the pipeline phase (e.g., `"validation"`, `"compilation"`).
- **`diagnostics`**: An array of diagnostic objects. On success, this is an empty array `[]`.

## Core Diagnostic Fields

Each object in the `diagnostics` array follows a stable contract designed for programmatic consumption. According to the `archify/test/workflow-semantic-contract.test.mjs` test suite, every diagnostic must include the following fields:

### `code` – Namespaced Identifier

A short, machine-readable string that classifies the problem type. Codes follow a namespace prefix pattern such as `workflow/column-capacity` or `workflow/unexpected-terminal`, enabling automated rule matching and suppression.

### `message` – Human-Readable Description

A string containing explanatory text suitable for display in terminals, IDEs, or web interfaces. This provides immediate context for developers without requiring lookup tables.

### `subject` – Problem Location

An object pinpointing the exact workflow element triggering the diagnostic. Depending on the error type, it may contain:

- **`node`**: The workflow node name (e.g., `"resume"`).
- **`edge`**: The edge identifier (e.g., `"ab"`).
- **`from`** / **`to`**: Source and destination node names for edge-related issues.
- **`route`**: The routing label that caused a conflict.
- **`path`**: A JSON-Pointer path inside the workflow definition.

### `evidence` – Triggering Values

Structured data providing the concrete values that violated a rule. For example, column capacity diagnostics include `capacity` and `used` counts, allowing tools to display precise numeric evidence without re-calculating values.

### `supportedFixes` – Remediation Commands

An array of suggested remediation actions. These may include CLI command fragments (e.g., `"migrate this workflow to schema_version 2"`) or conceptual instructions (e.g., `"increase column 3 width"`) that automated agents can apply or suggest to users.

### Optional Metadata Fields

Diagnostics may also include:

- **`severity`**: The seriousness level (`error`, `warning`, etc.), used by the CLI to determine exit codes.
- **`suppresses`**: An array of diagnostic codes that this finding supersedes, allowing high-priority issues to hide lower-priority noise.

## Example Diagnostic Output

The following JSON demonstrates a typical failure receipt from Archify, as validated in `archify/test/workflow-compiler.test.mjs`:

```json
{
  "ok": false,
  "stage": "validation",
  "diagnostics": [
    {
      "code": "workflow/column-capacity",
      "message": "Column capacity exceeded",
      "subject": {
        "edge": "ab",
        "from": "a",
        "to": "b",
        "fromCol": 1,
        "toCol": 2
      },
      "evidence": {
        "capacity": 3,
        "used": 4
      },
      "supportedFixes": [
        "migrate this workflow to schema_version 2",
        "increase column 3 width"
      ],
      "suppresses": [],
      "severity": "error"
    }
  ]
}

```

## Consuming Diagnostics Programmatically

The stable JSON structure enables automation scripts to process failures without parsing unstructured text. The following examples demonstrate patterns found in the repository's test suites.

### Inspecting Errors in Node.js

This script captures diagnostic output and extracts specific fields:

```javascript
import { execSync } from "child_process";

const raw = execSync("archify deliver my-workflow.json --json", { encoding: "utf8" });
const receipt = JSON.parse(raw);

if (!receipt.ok) {
  receipt.diagnostics.forEach(d => {
    console.log(`🔧 ${d.code}: ${d.message}`);
    console.log(`   → Subject: ${JSON.stringify(d.subject)}`);
    console.log(`   → Suggested fixes: ${d.supportedFixes.join(", ")}`);
  });
}

```

### Applying Automated Fixes

Using the `supportedFixes` array to programmatically repair workflows:

```javascript
import { execSync } from "child_process";

function applyFirstFix(workflowPath) {
  const out = execSync(`archify deliver ${workflowPath} --json`, { encoding: "utf8" });
  const receipt = JSON.parse(out);
  if (receipt.ok) return;

  const fix = receipt.diagnostics[0].supportedFixes[0];
  // Assume the fix is a CLI-friendly command fragment
  execSync(`archify ${fix} ${workflowPath}`);
}

```

## Source Code and Contract Validation

The diagnostic contract is enforced and documented across several key files in the `tt-a1i/archify` repository:

- **`archify/test/workflow-semantic-contract.test.mjs`**: Unit tests asserting the required shape of diagnostics, including mandatory fields like `code`, `subject`, and `supportedFixes`.
- **`archify/test/workflow-compiler.test.mjs`**: Validates compiler-specific diagnostic emission for scenarios such as column-capacity violations and routing conflicts.
- **`archify/test/workflow-migration.test.mjs`**: Demonstrates how migration-related diagnostics populate the `supportedFixes` array with specific migration instructions.
- **[`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md)**: Documentation describing the JSON receipt format and best practices for agent consumption.

## Summary

- Archify returns a structured JSON receipt with a `diagnostics` array for every command when using the `--json` flag.
- Each diagnostic includes a stable set of fields: `code`, `message`, `subject`, `evidence`, and `supportedFixes`.
- Optional fields `severity` and `suppresses` provide additional metadata for filtering and prioritization.
- The contract is tested in `workflow-semantic-contract.test.mjs` and documented in [`authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/authoring-cookbook.md).
- This structured output enables automated remediation, IDE integration, and reliable CI/CD processing without fragile text parsing.

## Frequently Asked Questions

### Does Archify output diagnostics on successful commands?

Yes, but the array is empty. When a command succeeds, the receipt contains `"ok": true` and `"diagnostics": []`, maintaining a consistent response shape for parsers and avoiding null checks.

### What information does the `subject` field contain?

The `subject` object pinpoints the exact workflow element causing the issue. It may specify `node` names, `edge` identifiers, `from`/`to` endpoints, `route` labels, or JSON-Pointer `path` values depending on the diagnostic type, as implemented in `archify/test/workflow-semantic-contract.test.mjs`.

### How can I automatically fix issues reported by Archify?

Inspect the `supportedFixes` array in each diagnostic object. This array contains suggested remediation commands or instructions that resolve the specific problem. Scripts can execute these suggestions or present them to users for confirmation, as demonstrated in `archify/test/workflow-migration.test.mjs`.

### Where is the diagnostic output format documented?

The canonical documentation resides in [`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md) within the `tt-a1i/archify` repository. The test suite in `archify/test/workflow-semantic-contract.test.mjs` serves as the executable specification that guarantees field stability across versions.