SuperAPI AI Directory

dym-archify-compare-architecture-delta

Coding & development

View repository

Updated 10-18 01:25

About this skill

Skill: dym-archify-compare-architecture-delta — Compare two architecture versions (Architecture Delta)

Why use it: design review and PR review. Instead of making readers compare two diagrams by eye, Archify compares two validated architecture sources and generates a Before / Delta / After page with a machine-readable receipt.

What you get: a self-contained HTML delta file and a sidecar *.receipt.json listing exactly what was added, removed, changed, moved — no inference.

Only supports architecture.

export A=~/.claude/skills/archify

Run

node $A/bin/archify.mjs compare architecture base.json head.json out/delta.html --json

Actually run with two bundled examples:

node $A/bin/archify.mjs compare architecture \
  $A/examples/checkout-platform.base.architecture.json \
  $A/examples/checkout-platform.head.architecture.json \
  out/delta.html --json

rc 0. Generated two files:

delta.html          1.9M
delta.receipt.json  5.2K

The receipt sidecar is by default placed next to the HTML, with the same base name. Change the location with --receipt:

node $A/bin/archify.mjs compare architecture base.json head.json out/delta.html \
  --receipt out/delta-receipt.json --json

Other flags are the same as the rest of the CLI: --quality standard|showcase, and --repo-root <path> when both sources declare code evidence (see 04).

Reading the receipt

The actual top-level keys (observed directly on delta.receipt.json generated):

schemaVersion  ok  command  type  comparatorVersion  canonicalVersion
completeness   proofLevel   base   head   summary   changes
identity       view         limitations   artifact   validation

base and head each side carries title, rawSha256, semanticSha256, bytes. The two hash types are intentionally separate: rawSha256 changes when bytes change (including formatting-only changes), semanticSha256 changes only when meaning changes.

summary actual from the run on:

{
  "components":  { "added": 1, "changed": 1, "evidenceChanged": 0, "removed": 1, "moved": 1 },
  "connections": { "added": 1, "changed": 2, "removed": 1, "rerouted": 1 },
  "boundaries":  { "added": 0, "changed": 2, "removed": 0, "geometryChanged": 0 },
  "presentationChanged": true,
  "provenanceChanged": false
}

identity states clearly what counts as "the same thing" between the two versions:

{
  "components":  "components[].id",
  "connections": "connections[].id (required)",
  "boundaries":  "boundaries[].kind + boundaries[].label (derived)"
}

Practical consequence: if you change the id of a component, the delta will read as delete one, add one, not rename. Keep id stable across revisions if you want the delta to be meaningful. And connections[].id is required for comparing edges — a source that doesn't assign ids to edges can't compare edges properly.

Limitations — quoted verbatim from the receipt

"Authored Architecture IR only; no runtime impact, causality, risk, or mergeability is inferred."
"Boundary identity is conservatively derived from kind + label."

completeness: "complete", proofLevel: "authored". In other words: this is a delta over the events you declared, not impact analysis. This page must not be used to claim "this change is safe to merge" or "low risk". It says what changed in the declaration, period.

Attach to PR review

Run between main and the branch, when the architecture source is in the repo:

git show main:docs/architecture.json > /tmp/base.json
node $A/bin/archify.mjs compare architecture \
  /tmp/base.json docs/architecture.json \
  /tmp/delta.html --json > /tmp/delta-summary.json

Then attach /tmp/delta.html to the PR, or quote summary from /tmp/delta-summary.json into the description. See 08-ci-diagram-gate.md for the gate finalization.

In the viewer, readers select a declared change, or run a bounded Review pass just to look. The viewer does not infer impact, risk, or merge safety.