How Archify Handles Errors and Diagnostics During Validation and Delivery

Archify treats validation and delivery as deterministic stages that always emit a machine-readable JSON receipt containing precise diagnostics and repairable fixes, ensuring no stack traces reach stdout and every failure is actionable.

When building automated workflows with tt-a1i/archify, understanding the error handling architecture is critical for CI/CD integration. Archify implements a fail-closed strategy where both validation and delivery operations produce structured JSON receipts that serve as the single source of truth for pipeline status. This deterministic approach eliminates ambiguous exit states and provides automated agents with the exact context needed to self-heal issues.

The Validation Stage and Structured Error Reporting

When you invoke archify.mjs validate … --json, the CLI executes a rigorous multi-phase inspection that guarantees machine-parseable output regardless of success or failure.

JSON Schema Validation and Geometry Checks

According to the source code in bin/archify.mjs, the validation process first parses the input JSON against the appropriate schema (such as archify/schemas/workflow.schema.json). It then executes a series of deterministic geometry and composition checks including duplicate ID detection, edge-crossing validation, label clearance analysis, and container-border run verification. If any check fails, the command immediately exits with a non-zero status while suppressing all Node stack traces from stdout.

The Receipt Contract

As documented in SKILL.md (lines 73-81), every validation operation returns a single JSON object containing three critical fields:

• ok: A boolean indicating overall success
• stage: A string identifying the failing phase (e.g., "validate")
• diagnostics: An array of structured error objects, each containing:
  • subject: The affected element identifier (e.g., "relationship[12]")
  • message: A human-readable description of the issue
  • supportedFixes: An array of actionable repair strategies

The delivery contract in references/delivery-contract.md (lines 57-80) mandates that this receipt format remain consistent across both validation and delivery commands, ensuring downstream tooling can rely on a stable API contract.

# Run validation and capture structured diagnostics

node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json \
  --quality showcase --json

{
  "ok": false,
  "stage": "validate",
  "diagnostics": [
    {
      "subject": "relationship[12]",
      "message": "duplicate ID 'order'",
      "supportedFixes": ["renameId", "remove"]
    }
  ]
}

The Delivery Stage and Diagnostic Aggregation

After successful validation, the deliver command extends the error handling pattern to encompass rendering and asset management while maintaining the same JSON receipt contract.

Rendering Pipeline and Final Checks

When executing archify.mjs deliver … --json, the CLI runs the renderer followed by a final HTML checker. During this process, it captures delivery-specific issues such as missing PNG assets, broken hyperlinks, or template rendering failures. The implementation in bin/archify.mjs (lines 267-333) constructs a comprehensive receipt that preserves the full audit trail.

Merged Receipt Structure

The delivery receipt contains both the original validation results and any new delivery-specific diagnostics. This merged structure ensures that the entire pipeline remains auditable through a single JSON payload, as required by the delivery contract. If validation had previously failed, those diagnostics are included alongside any new rendering issues, providing complete context for failure analysis.

# Execute delivery; failures still return valid JSON receipts

node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json \
  out.html --quality showcase --json

{
  "ok": false,
  "stage": "deliver",
  "validation": { "ok": true },
  "diagnostics": [
    {
      "subject": "artifact[3]",
      "message": "missing PNG asset",
      "supportedFixes": ["addAsset"]
    }
  ]
}

Error Handling Policy and Repair Workflows

Archify enforces three strict policies that govern how errors propagate through the system.

Deterministic JSON Reporting

Deterministic reporting guarantees that every failure is represented by a structured JSON object and that a non-zero exit code is never reported as success. Per SKILL.md, stack traces and debugging information are either forwarded to stderr or omitted entirely, ensuring that stdout contains only parseable data. This design allows automated agents to trust the JSON receipt as the sole source of truth for pipeline state.

The Repair Loop with supportedFixes

Each diagnostic entry includes a supportedFixes array that enables automated repair workflows. The docs/authoring-cookbook.md (lines 65-68) documents this pattern, advising agents to "repair the named subject and use the listed supportedFixes before trying another change." This creates a tight feedback loop where validation failures can trigger automatic remediation scripts that apply the suggested fixes and re-run the validation step until the receipt returns "ok": true.

Zero-Install Reproducibility

Archify guarantees that validation, rendering, and diagnostics execute without external dependencies beyond Node.js ≥ 18. This zero-install guarantee ensures that the same receipt can be reproduced on any compliant environment, making the tool suitable for air-gapped CI systems and automated agent workflows where reproducible evidence is essential.

Summary

• Machine-readable receipts: Both validate --json and deliver --json emit structured JSON objects containing ok, stage, and diagnostics fields, as implemented in bin/archify.mjs.
• Fail-closed architecture: Non-zero exit codes always correlate with "ok": false, and stdout never contains unstructured stack traces.
• Repairable diagnostics: Every error includes supportedFixes enabling automated remediation loops documented in authoring-cookbook.md.
• Audit trail preservation: Delivery receipts merge validation and rendering diagnostics into a single payload for complete pipeline traceability.
• Reproducible execution: Error handling requires zero external dependencies, functioning identically across Node ≥ 18 environments.

Frequently Asked Questions

What format does Archify use for error reporting?

Archify emits a structured JSON receipt containing an ok boolean, a stage string identifying the operation phase, and a diagnostics array. Each diagnostic object specifies the affected subject, a human-readable message, and an array of supportedFixes for automated repair.

How does Archify prevent noisy stack traces from breaking automation?

The CLI implementation in bin/archify.mjs explicitly suppresses Node stack traces from stdout, routing them to stderr only when debugging is enabled. This ensures that automated parsers can always expect valid JSON on standard output, even when the process exits with a non-zero status code.

Can delivery operations report errors from earlier validation stages?

Yes. The delivery receipt format defined in references/delivery-contract.md includes both a validation object containing earlier results and a top-level diagnostics array for delivery-specific issues. This merged structure provides complete visibility into failures occurring at any pipeline stage.

How do automated agents repair Archify validation failures?

Agents inspect the supportedFixes array within each diagnostic entry to determine available remediation strategies. According to SKILL.md and authoring-cookbook.md, agents should apply the listed fixes to the named subject and re-run the validation command, creating an iterative repair loop until all diagnostics are resolved.

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