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

> Master Archify source evidence limits and Git verification. Learn how signed evidence links architecture diagrams to Git commits, ensuring code integrity. Full technical guide.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-17

---

**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:

```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

```bash

# 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.

```bash

# 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:

```bash
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.