Archify Source Evidence Limits and Git Verification: A Complete Technical Guide

Archify embeds cryptographically signed source evidence into architecture diagrams, but only for the architecture renderer—other diagram types deliberately omit evidence to keep artifacts lightweight, with Git verification linking every SRC n node to exact commit-level file ranges.

Archify is an agent skill that transforms free-form codebase descriptions into deterministic, interactive system maps. When you need diagrams backed by actual source code, understanding how Archify limits source evidence and implements Git verification is essential for trustworthy documentation. This guide examines the specific constraints and verification mechanisms as implemented in the tt-a1i/archify repository.

How Source Evidence Works in Archify

Evidence Is Opt-In by Design

Source evidence in Archify is not automatic. Only architecture diagrams can request evidence embedding; workflow, sequence, dataflow, and lifecycle renderers deliberately skip this step to minimize artifact size. This limitation is enforced in archify/bin/archify.mjs at lines 40–44, where the assertEvidenceType function validates that evidence requests apply only to compatible diagram types.

When evidence is enabled, Archify injects a JSON script block into the generated HTML:

<script id="archify-source-evidence-data" type="application/json">
{
  "verified": true,
  "repository": { "url": "https://github.com/tt-a1i/archify" },
  "revision": "9f1a1cf...",
  "referenceCount": 12
}
</script>

The reference count indicates how many diagram nodes carry SRC n markers tied to specific file locations.

Enabling Source Evidence

Two paths activate evidence embedding:

1. Explicit flag: --repo-root <path> passed to render or preview commands
2. Deliver command: archify deliver automatically attaches evidence when validation succeeds

# Render with manual evidence request

archify render architecture spec.json output.html --repo-root .

# Deliver with automatic evidence (recommended)

archify deliver architecture spec.json output.html --repo-root . --open

Git Verification: Linking Nodes to Source Commits

How SRC Markers Become Clickable Links

Every node marked with SRC n in your architecture specification resolves to a Git-verified URL at render time. The transformation follows this pattern:

https://github.com/<owner>/<repo>/blob/<revision>/<path>#L<start>-L<end>

The sourceEvidenceFromArtifact function in archify/bin/archify.mjs (lines 41–50) parses the embedded evidence JSON and validates its shape. If verified is not true or required fields are missing, it throws an error before any rendering proceeds.

Evidence Generation Pipeline

The actual <script> tag generation happens in archify/renderers/shared/repository-evidence.mjs. This module:

• Extracts the repository URL from the runtime context
• Captures the exact Git commit SHA (not branch names)
• Computes the reference count by scanning nodes for SRC markers

This ensures immutable provenance—even if the repository changes later, the diagram links to the precise commit it was generated from.

Cryptographic Integrity

Archify creates a SHA-256 receipt for every delivered artifact. The hash covers both the HTML content and the evidence block. Any manual modification to the artifact without regenerating the receipt breaks verification, making tampering detectable.

The receipt creation logic resides in archify/bin/archify.mjs at lines 29–38, as part of the atomic commandDeliver workflow.

Evidence in Delta Comparisons

When comparing two architecture versions, Archify preserves verification status across the comparison. The archify/delta/architecture-delta.mjs module propagates:

• baseVerified: whether the base revision had valid source evidence
• headVerified: whether the head revision had valid source evidence

These flags appear in the three-panel delta view (Base ↔ Head ↔ Delta) at lines 88–90 of archify/bin/archify.mjs, ensuring that change analysis never loses provenance information.

# Compare two versions, preserving all evidence flags

archify compare architecture \
  checkout-platform.base.architecture.json \
  checkout-platform.head.architecture.json \
  architecture-delta.html --quality showcase

Renderer-Specific Evidence Exclusions

Diagram Type	Evidence Support	Reason
architecture	✅ Full support	Complex systems benefit from source linking
workflow	❌ Excluded	Linear process flows rarely need file-level evidence
sequence	❌ Excluded	Temporal diagrams focus on interaction, not implementation
dataflow	❌ Excluded	Data movement patterns are abstracted from code locations
lifecycle	❌ Excluded	State transitions are conceptual, not file-specific

This exclusion matrix is hardcoded in the renderer selection logic of archify/bin/archify.mjs. Attempting to request evidence for unsupported types triggers assertEvidenceType to exit with an error.

Validating Evidence at Runtime

The archify doctor command performs environment checks including evidence system health. It validates that:

• Required validators exist in archify/renderers/shared/generated-validators.mjs
• Example files with SRC markers parse correctly
• The Node.js version supports all cryptographic operations

Run this before troubleshooting evidence issues:

archify doctor

Summary

• Source evidence is architecture-only by design; other diagram types explicitly exclude it for performance
• Git verification links SRC n nodes to immutable commit URLs, not floating branch references
• Evidence requires --repo-root or deliver to activate; the render command alone skips it
• SHA-256 receipts provide cryptographic integrity detection for tampered artifacts
• Delta comparisons preserve baseVerified and headVerified flags across three-panel views

Frequently Asked Questions

Why can't I add source evidence to workflow or sequence diagrams?

Archify deliberately restricts evidence to architecture diagrams because they represent structural code relationships where file-level provenance matters. Workflow and sequence diagrams model temporal behavior and interactions—concepts abstracted from specific implementation locations. The assertEvidenceType function in archify/bin/archify.mjs enforces this architectural boundary to keep renderers focused and artifacts compact.

How does Archify prevent evidence tampering after delivery?

Every delivered artifact includes a SHA-256 receipt generated from the combined HTML and evidence JSON. The receipt is computed atomically in commandDeliver (lines 29–38) only after all validators pass. Since the hash covers the evidence block itself, any post-delivery modification breaks verification without access to the original signing context.

What happens if I click a Git-verified node in an old diagram?

The navigation URL includes the exact commit SHA captured at generation time, not a branch name. Even if the repository has evolved, you'll view the file at the precise revision referenced when the diagram was created. This immutability guarantee is why Archify captures the SHA in repository-evidence.mjs rather than resolving symbolic references.

Can I compare two diagrams with different evidence states?

Yes. The compare command handles mixed verification states through baseVerified and headVerified flags propagated by architecture-delta.mjs. The delta view clearly indicates which revision had source backing, letting you evaluate changes even when one diagram lacks evidence—common when comparing a legacy baseline against a newly-instrumented head revision.

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