How Archify's `deliver` Command Handles Failures: A Complete Guide to Safe, Atomic Delivery

Archify's deliver command uses atomic candidate-then-commit logic with non-zero exits on failure, ensuring corrupted artifacts never overwrite good ones and always returning machine-readable diagnostic receipts for automated repair.

The deliver command is Archify's final hand-off step that transforms a validated JSON specification into a self-contained HTML artifact. According to the source code in tt-a1i/archify, its failure handling prioritizes safety, determinism, and auditability above all else. This guide breaks down the exact mechanism, exit behaviors, and repair workflow implemented in bin/archify.mjs and documented across SKILL.md and README.md.

The Delivery Pipeline: Render, Validate, Then Commit

Archify's deliver command follows a strict three-phase pipeline designed to prevent partial or corrupted outputs:

Phase 1: Candidate Generation

First, deliver writes a candidate HTML file to a temporary location. This provisional artifact is not visible to downstream consumers.

Phase 2: Full Validation Suite

The candidate then undergoes Archify's complete artifact validation: schema checks, layout verification, composition analysis, and more. As documented in SKILL.md – Delivery section, every check must pass before the command proceeds.

Phase 3: Atomic Replacement

Only upon full validation success does the candidate atomically replace the existing target file. This eliminates race conditions where a reader might observe a partially written file.

Failure Behavior: Non-Zero Exits with Preserved Output

When any validation check fails, deliver behaves predictably:

Behavior	Implementation
Exit status	Non-zero exit code
Output preservation	Previous good HTML remains completely untouched
Receipt emission	Structured JSON receipt still printed (with --json)

This guarantee is explicit in [README.md lines 99-102](https://github.com/tt-a1i/archify/blob/main/README.md#L99): "On failure, validate --json and deliver --json emit one JSON object" — and that object's ok field is false.

The atomic design means you can safely rerun deliver repeatedly without risk of corrupting working artifacts.

The Failure Receipt: Machine-Readable Diagnostics

Archify transforms failures from opaque errors into structured, actionable data. The JSON receipt contains a diagnostics[] array where each entry specifies:

• code — Machine-parseable rule identifier (e.g., "layout/overlap", "artifact/missing")
• subject — The specific element requiring change
• evidence — Measured data supporting the diagnosis
• supportedFixes — Repair strategies applicable to this failure

Example Failure Receipt

{
  "ok": false,
  "diagnostics": [
    {
      "code": "layout/overlap",
      "subject": "relationship-12",
      "evidence": { "overlapArea": 42 },
      "supportedFixes": ["moveLabel", "spreadPorts"]
    },
    { "code": "artifact/missing", "subject": "output", "message": "no bytes produced" }
  ],
  "error": "validation failed"
}

This structure enables fully automated repair pipelines: extract subject, apply one of the supportedFixes, and re-run deliver.

Successful Delivery Receipt

When validation passes, the receipt confirms integrity with cryptographic hashes and byte counts:

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

{
  "ok": true,
  "specification": { "sha256": "a1b2c3…", "bytes": 1234 },
  "artifact": { "sha256": "d4e5f6…", "bytes": 56789 },
  "validation": { "compositionStatus": "pass" }
}

Both success and failure paths emit valid JSON, making deliver safe for shell scripts and CI/CD systems.

The Repair Loop: Focused Correction Strategy

Archify's failure handling extends beyond single invocations. Per [SKILL.md](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md#L35), the documentation prescribes a disciplined repair loop:

1. Change only the diagnosed subject — No scattershot edits
2. Re-run validate or deliver — Measure progress objectively
3. Continue while error count reaches a new minimum
4. Stop and report truthfully if two consecutive rounds fail to reduce errors

This bounded, evidence-driven approach prevents infinite fix attempts and ensures transparent handling of unresolvable issues.

Critical Pitfall: Avoid visual-check on Failed Paths

The documentation explicitly warns: "A failed delivery preserves any previous output, so do not run visual-check on that path". Because the previous good artifact remains in place, visual-check would misleadingly validate stale content rather than the failed candidate.

Key Source Files and Test Coverage

File	Purpose
archify/bin/archify.mjs	CLI entry point implementing candidate writing, validation orchestration, and atomic replacement
archify/SKILL.md	Canonical delivery contract definition
archify/references/delivery-contract.md	Complete JSON receipt schema
archify/test/delivery-contract.test.mjs	Unit tests asserting success/failure behaviors and output preservation
README.md (lines ~99–102)	User-facing summary of failure guarantees

The test file delivery-contract.test.mjs specifically verifies that failed deliveries leave previous output intact — this is not merely documented behavior but tested contract.

Summary

• Atomic delivery — Candidate validated before any existing file is touched
• Non-zero exit on any validation failure with zero output clobbering
• Structured receipts via --json for both success and failure cases
• Diagnostic-rich failures with code, subject, evidence, and supportedFixes
• Documented repair loop for systematic, bounded error resolution
• Explicit warning against visual-check on paths with failed deliveries

Archify's deliver command treats failure as a first-class scenario rather than an afterthought, enabling safe automation and reliable CI/CD integration.

Frequently Asked Questions

What exit code does deliver return on failure?

deliver exits with a non-zero status code. Per the source in bin/archify.mjs and documentation in README.md, any validation failure triggers this exit regardless of whether --json is used. The specific code may vary by failure type, but all non-zero values indicate unsuccessful delivery.

Does a failed deliver ever corrupt my existing HTML file?

No. The atomic candidate-then-commit design ensures the previous good artifact remains completely untouched. As demonstrated in delivery-contract.test.mjs, the candidate is written to a separate location and only replaces the target after full validation passes. Failed runs leave the filesystem state unchanged except for temporary candidate cleanup.

How do I programmatically respond to deliver failures?

Use the --json flag and parse the emitted receipt. Check the ok boolean field: when false, iterate through diagnostics[] to extract each subject and its supportedFixes. This structure enables automated repair loops without parsing human-readable error messages. The receipt format is fully specified in references/delivery-contract.md.

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