dym-archify-repository-evidence

Skill: dym-archify-repository-evidence — Sơ đồ architecture gắn bằng chứng mã nguồn thật

Vì sao dùng: khi sơ đồ kiến trúc phải chứng minh được nó phản ánh mã thật, không phải trí nhớ của ai đó. Node có bằng chứng tự đánh dấu SRC n trong viewer và mở đúng file + khoảng dòng, ghim vào một commit công khai.

Kết quả nhận được: một HTML architecture trong đó các thành phần dẫn ngược về file/dòng thật, và một cổng fail-closed từ chối render nếu bằng chứng không kiểm chứng được.

Chỉ dành cho architecture. workflow, sequence, dataflow, lifecycle từ chối --repo-root với rc 2.

export A=~/.claude/skills/archify

Ba thứ phải khớp cùng lúc

Đọc từ renderers/shared/repository-evidence.mjs (hàm verifyRepositoryEvidence, dòng 87+):

1. meta.repository.url — phải là URL GitHub công khai dạng https://github.com/owner/repo. URL khác host hoặc khác dạng → repository-evidence/url-invalid.
2. meta.repository.revision — phải là SHA commit đủ 40 ký tự. Rút gọn 7 ký tự bị từ chối: repository-evidence/revision-invalid.
3. --repo-root <path> — phải trỏ vào thư mục top-level của Git checkout, và origin của nó phải khớp meta.repository.url. Không phải top-level → repository-evidence/root-not-top-level (kèm đúng đường dẫn nên dùng). Origin lệch → repository-evidence/origin-mismatch.

Cấu trúc sources[] trên mỗi component, lấy từ schemas/architecture.schema.json: mảng 1–3 phần tử, mỗi phần tử bắt buộc path (≤240 ký tự), tuỳ chọn line, end_line (số nguyên ≥1), label (≤48 ký tự).

Spec tối thiểu đã chạy xanh thật

Ví dụ này tôi đã soạn và chạy trọn vòng trên chính repo archify:

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