SuperAPI AI Directory

dym-archify-repository-evidence

Coding & development

View repository

Updated 10-18 01:23

About this skill

Skill: dym-archify-repository-evidence — Architecture diagram tied to real source-code evidence

Why use it: when an architecture diagram must prove it reflects real code, not someone's memory. A node with evidence automatically marks itself SRC n in the viewer and opens the exact file + line range, pinned to a public commit.

What you get: an HTML architecture in which components link back to real files/lines, and a fail-closed gate that refuses to render if the evidence cannot be verified.

Only for architecture. workflow, sequence, dataflow, lifecycle rejects --repo-root with rc 2.

export A=~/.claude/skills/archify

Three things must match at the same time

Read from renderers/shared/repository-evidence.mjs (function verifyRepositoryEvidence, line 87+):

  1. meta.repository.url — must be a public GitHub URL of the form https://github.com/owner/repo. A URL with a different host or a different form → repository-evidence/url-invalid.
  2. meta.repository.revision — must be a full 40-character commit SHA. An abbreviated 7-character one is rejected: repository-evidence/revision-invalid.
  3. --repo-root <path> — must point into the top-level directory of the Git checkout, and its origin must match meta.repository.url. Not top-level → repository-evidence/root-not-top-level (with the correct path to use). Origin mismatch → repository-evidence/origin-mismatch.

Structure of sources[] on each component, taken from schemas/architecture.schema.json: an array of 1–3 elements, each element requiring path (≤240 characters), optional line, end_line (integer ≥1), label (≤48 characters).

Minimal spec that actually ran green

I drafted this example and ran the full loop on the archify repo itself:

REV=$(git -C /path/to/archify rev-parse HEAD)   # phải là SHA 40 ký tự

cat > evidence.architecture.json <<JSON
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Archify CLI — evidence probe",
    "quality_profile": "showcase",
    "repository": {
      "url": "https://github.com/tt-a1i/archify",
      "revision": "$REV"
    }
  },
  "layout": { "mode": "grid" },
  "components": [
    {
      "id": "cli", "type": "backend", "label": "archify CLI", "row": 0, "col": 0,
      "sources": [
        { "path": "archify/bin/archify.mjs", "line": 1, "end_line": 40, "label": "entry" }
      ]
    },
    {
      "id": "renderer", "type": "backend", "label": "Renderer", "row": 0, "col": 1,
      "sources": [
        { "path": "archify/renderers/architecture/render-architecture.mjs", "line": 1, "end_line": 30 }
      ]
    }
  ],
  "connections": [
    { "from": "cli", "to": "renderer", "label": "spawns" }
  ]
}
JSON

node $A/bin/archify.mjs validate architecture evidence.architecture.json \
  --quality showcase --repo-root /path/to/archify

Actual result:

ok architecture /…/evidence.architecture.json (9 artifact checks; composition showcase: 0 errors, 0 warnings)

rc 0.

Two failure paths, verified

Forgetting --repo-root when the spec declares evidence — fail-closed gate, rc 1:

This diagram declares source evidence. Pass --repo-root <repository> so Archify can verify it before rendering.
[repository-evidence/root-required] … Fix: pass --repo-root with the matching local Git checkout.

Using --repo-root with an architecture type other than — usage error, rc 2:

--repo-root is currently supported for architecture diagrams only.

This distinction matters in CI: 1 means your spec is wrong, 2 means your command line is wrong.

Delivering an artifact with evidence

--repo-root is accepted by render, validate, deliver, preview, and compare — always only in architecture mode:

node $A/bin/archify.mjs deliver architecture evidence.architecture.json out/arch.html \
  --quality showcase --repo-root /path/to/archify --json

Discipline when gathering evidence

From references/authoring-contract.md the "Repository evidence" section:

  • Inspect entrypoints, runtime boundaries, data stores, transports, deployment configuration before writing the diagram.
  • Only record evidence you have actually verified. sources[] is a claim, not a comment.
  • Do not infer runtime causal relationships from files being near each other or names being similar. Being in the same folder does not mean they call each other.
  • A regular artifact (not declared sources) still has absolutely no source code attached — the evidence is opt-in, not the default.

Related: profile deployment-ownership

Architecture adds an optional engineering profile for production deployment review. It fails closed: missing a declared owner, missing a region location, missing a dedicated database scope, or missing names of boundary cut points makes validation fail. It is never enabled implicitly and does not inspect running infrastructure.

Enable it only when the user asks for exactly that. Mentioning region/cluster/security boundary in a diagram is not in itself a reason to enable the profile. And once enabled, it must not be removed just to make validation pass — fix the data, or report the diagnosis honestly.