How to Add Git-Verified Source Evidence to Archify Diagrams

Add a source block with repository URL, commit SHA, file path, and line range to any node in your Archify JSON IR, then render with --repo-root to generate verified, clickable source badges in the output HTML.

Archify diagrams can link directly to the exact lines of code that justify each architectural element. This source evidence feature binds nodes to specific Git commits, enabling readers to verify claims by clicking through to GitHub. The verification is enforced by the renderer in archify/renderers/shared/repository-evidence.mjs and the CLI entry point at archify/bin/archify.mjs.

Mark Nodes with Source Evidence in the JSON IR

Every node in an Archify diagram accepts an optional source object that defines the Git-backed evidence. Add this object to nodes you want to prove.

The source schema requires:

Field	Description
repo	Full HTTPS URL of the GitHub repository
revision	Exact 40-character commit SHA
path	File path relative to repository root
line	Starting line number (1-indexed)
endLine	Ending line number (inclusive)

Example node with source evidence:

{
  "id": "router",
  "label": "CLI router",
  "kind": "service",
  "source": {
    "repo": "https://github.com/mco-org/mco",
    "revision": "9f1a1cf1afdc04d7b5406782b40dfec76d9bc798",
    "path": "runtime/cli.py",
    "line": 1945,
    "endLine": 1945
  }
}

Archify recognizes this structure through the architectural contract defined in archify/renderers/shared/repository-evidence.mjs. The presence of a source block signals that this node carries verifiable provenance.

Enable Git Verification During Rendering

Source evidence is validated only when you supply a local repository. Pass --repo-root <path> to the render or deliver commands.

Render with Verification

# Clone and enter the referenced repository

git clone https://github.com/tt-a1i/archify.git
cd archify

# Render with repo root for Git verification

node archify/bin/archify.mjs render \
  examples/web-app.json \
  /tmp/web-app.html \
  --repo-root $(pwd) \
  --quality showcase

The CLI performs four checks in archify/renderers/shared/repository-evidence.mjs:

1. Commit existence — The revision SHA must exist in the local Git data
2. File-path sanity — path must resolve to a readable file inside the repo
3. Line range validity — line and endLine must not exceed file length
4. Link generation — Constructs deterministic GitHub permalink

If any check fails, the renderer aborts with:

Rendered source evidence receipt is incomplete.

This error originates at line 742 of archify/bin/archify.mjs and prevents unverified or fabricated evidence from reaching the output.

Deliver with Atomic Replacement

The deliver sub-command enforces verification before replacing artifacts:

node archify/bin/archify.mjs deliver \
  examples/web-app.json \
  docs/gallery/artifacts/web-app.architecture.html \
  --repo-root $(pwd) \
  --open \
  --json

The delivery pipeline requires a passing receipt. Only then does the new artifact atomically replace the previous version.

Consume Evidence in the Generated Viewer

Verified diagrams render clickable source badges on evidence-backed nodes. Clicking opens the exact GitHub URL built from the source block:

https://github.com/mco-org/mco/blob/9f1a1cf…/runtime/cli.py#L1945

The hidden evidence data is stored in HTML elements with class semantic-passport-evidence. These appear throughout the generated output, including examples/web-app.html in the repository.

Complete Working Example

This JSON IR defines a database node linked to storage implementation lines:

{
  "nodes": [
    {
      "id": "db",
      "label": "Postgres",
      "kind": "database",
      "source": {
        "repo": "https://github.com/tt-a1i/archify",
        "revision": "a73047b27e3b423fc8ab6ebd1ac84fd4ecb2e782",
        "path": "archify/src/storage.js",
        "line": 42,
        "endLine": 48
      }
    }
  ]
}

Render and verify:

node archify/bin/archify.mjs render diagram.json output.html --repo-root . --quality showcase

A receipt JSON confirms successful verification. The output HTML contains a verified source badge for the database node.

Key Implementation Files

File	Purpose
archify/renderers/shared/repository-evidence.mjs	Git verification logic and receipt generation
archify/bin/archify.mjs	CLI parsing of --repo-root and error handling at line 742
archify/SKILL.md	Formal source schema contract
examples/web-app.html	Example output with semantic-passport-evidence elements
docs/research-repo-evidence-passport-2026-07-23.md	Design rationale for the passport concept

Summary

• Add source objects to nodes in your Archify JSON IR with repo, revision, path, line, and endLine
• Pass --repo-root when rendering or delivering to enable Git verification against local repository data
• Verification fails fast if commits, files, or line ranges are invalid, blocking unproven claims
• Delivered artifacts contain clickable source badges that open exact GitHub permalinks

Frequently Asked Questions

What happens if the commit SHA in my source block doesn't exist locally?

The renderer aborts with "Rendered source evidence receipt is incomplete." This error from archify/bin/archify.mjs line 742 prevents generation of unverified output. Fetch the missing commit into your local repository and retry.

Can I use source evidence with private GitHub repositories?

Yes. The repo URL can point to any accessible Git remote. Viewers clicking source badges need read access to the repository. Archify itself only validates that the commit exists locally; it does not check GitHub permissions during rendering.

Does Archify support evidence from multiple repositories in one diagram?

Yes. Each node's source block specifies its own repo URL. You can reference commits from distinct repositories across different nodes. Each source block is verified independently against the supplied --repo-root, which must contain all referenced histories.

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