Archify Diagnostic Output Format: Complete JSON Receipt Schema for `validate` and `deliver` Commands

Archify's validate and deliver commands output a deterministic JSON receipt to STDOUT when invoked with the --json flag, containing operation status, diagnostic entries, and optional composition data.

The tt-a1i/archify codebase implements a machine-first design for its command-line interface. Both validation and delivery workflows produce structured receipts that CI pipelines, agents, and external tools can parse without fragile text scraping. This article breaks down the exact schema, field semantics, and parsing patterns found in the source.

JSON Receipt Structure

The diagnostic output format for both commands follows a single JSON object written exclusively to STDOUT. No other content contaminates the output stream.

Top-Level Fields

Field	Type	Presence	Description
ok	boolean	Required	Operation success indicator. true when all checks pass.
checksPassed	number	Required	Count of checks that satisfied constraints.
checkCount	number	Required	Total checks executed during the operation.
diagnostics	Array<Diagnostic>	Required	Diagnostic entries; empty array when ok is true.
composition	object	Optional	Deterministic layout or graph representation from validation.
engineeringProfile	string	Optional	Profile tag, e.g., "deployment-ownership". Added by deliver.
version	string	Required	Archify version that generated the receipt.
source	object	Optional	Input metadata including ref, path, and related identifiers.

Diagnostic Object Schema

Each entry in the diagnostics array contains:

• code (string): Machine-readable identifier like "workflow/column-capacity"
• message (string): Human-readable problem description
• subject (object): Target reference with id, type, path properties
• evidence (object, optional): Concrete data such as geometry, obstacle IDs, or segment indices
• severity (string, optional): One of "error", "warning", "info"
• supportedFixes (Array<string>, optional): Auto-fix suggestions

Exit Behavior and Stream Handling

Commands always exit non-zero on failure, but the JSON receipt prints to STDOUT regardless. Error stack traces route to STDERR exclusively. This separation guarantees parseable output even during runtime failures.

# Commands that fail still produce valid JSON on STDOUT

archify validate broken.json --json > receipt.json 2>errors.log
echo $?  # Non-zero exit code

jq . receipt.json  # Still valid and parseable

Practical Usage Examples

Validating a Workflow

# Generate validation receipt

archify validate workflow ./configs/pipeline.json --json > receipt.json

# Extract diagnostic count for CI gates

jq '.diagnostics | length' receipt.json

# Fail pipeline on any errors

jq -e '.ok' receipt.json > /dev/null || exit 1

Delivery with Profile Tag

# Deliver architecture diagram with JSON receipt

archify deliver architecture diagram.json \
  --repo-root ./my-repo \
  --json > delivery.json

# Inspect added engineering profile

jq '.engineeringProfile' delivery.json

Sample Receipt Output

{
  "ok": true,
  "checksPassed": 1,
  "checkCount": 1,
  "diagnostics": [],
  "composition": {
    "nodes": [],
    "edges": []
  },
  "version": "2.14.0"
}

Source Code Evidence

The implementation in archify/bin/archify.mjs handles CLI argument parsing and receipt serialization. Test coverage in archify/test/repair-receipt.test.mjs validates the schema through assertions on receipt(validated).diagnostics, receipt.ok, and receipt.checksPassed according to lines 67-73.

Documentation in docs/research-next-stability-delight-slice-2026-07-23.md (lines 86-108) explicitly contracts the output: archify validate … --json returns an object containing checks, diagnostics, and composition. The same document (lines 119-124) confirms deliver --json preserves this structure while appending engineeringProfile.

Additional validation logic appears in archify/test/workflow-semantic-contract.test.mjs, demonstrating how diagnostics accumulate and serialize during semantic analysis.

Parsing Patterns for Automation

Scripts consuming Archify receipts should follow these patterns:

1. Parse unconditionally — JSON.parse() stdout without checking exit code first
2. Gate on ok field — Boolean success indicator is authoritative
3. Iterate diagnostics — Process severity levels for reporting granularity
4. Version-check — Compare version against known-compatible releases

// Node.js example: robust receipt processing
import { execSync } from 'node:child_process';

function validateWorkflow(path) {
  const result = execSync(
    `archify validate workflow ${path} --json`,
    { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] }
  );
  
  const receipt = JSON.parse(result);
  
  return {
    success: receipt.ok,
    failures: receipt.diagnostics.filter(d => d.severity === 'error'),
    composition: receipt.composition
  };
}

Summary

• Archify's diagnostic output format is a single JSON object written to STDOUT when --json is specified
• Both validate and deliver commands share the core schema; deliver adds optional engineeringProfile
• The ok boolean and diagnostics array provide machine-actionable operation status
• Exit codes indicate success/failure but do not affect JSON validity on STDOUT
• Source implementation resides in archify/bin/archify.mjs with test coverage in archify/test/repair-receipt.test.mjs

Frequently Asked Questions

What happens if validation passes with no issues?

The diagnostics array is empty ([]), ok is true, and checksPassed equals checkCount. The receipt still contains all required fields including version and optional composition data.

Can I rely on JSON output when the command crashes?

Yes. Archify guarantees valid JSON on STDOUT even for non-zero exits. Error details and stack traces route to STDERR, keeping STDOUT parseable for pipeline resilience.

How does the deliver receipt differ from validate?

The deliver command outputs the same base schema with an additional optional field: engineeringProfile. This string tag indicates the deployment ownership profile applied during delivery, as documented in the research notes for archify deliver … --json.

Which Archify version introduced this JSON receipt format?

The source references in docs/research-next-stability-delight-slice-2026-07-23.md and test files indicate this format is stable in version 2.14.0. The version field in receipts enables consumers to detect schema evolution.

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