What Information Is Included in Archify's Diagnostic Output?

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:

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

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:

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

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