Detecting Architecture Drift

Architecture drift happens when the files on disk no longer match what your verikt.yaml declares. A capability is listed but its files were deleted. A directory was renamed. Someone removed a file during refactoring.

verikt diff detects this — like terraform plan for code structure.

Basic Usage

verikt diff

This reads your verikt.yaml, computes what files should exist based on the declared architecture and capabilities, then checks which ones actually exist on disk.

Example Output

verikt Diff — hexagonal + 4 capabilities
═══════════════════════════════════════════════════════
  ✓ architecture       all files present
  ✓ http-api           all files present
  ✗ redis              2 missing files
    - adapter/redisrepo/connection.go
    - adapter/redisrepo/repository.go
  ✓ docker             all files present

═══════════════════════════════════════════════════════

Summary: 3/4 capabilities fully present | drift score: 0.12

Understanding the Output

Per-Capability Status

Status	Meaning	Action
`✓ ok`	All expected files present	None needed
`✗ partial`	Some files missing	Investigate — was this intentional?
`✗ missing`	All files for this capability are gone	Re-add with `verikt add` or remove from `verikt.yaml`

Drift Score

0.00 — Perfect alignment. What you declared is what exists.
0.01–0.25 — Minor drift. A few files missing, probably intentional.
0.25–0.75 — Significant drift. Architecture is diverging from intent.
0.75–1.00 — Major drift. The declared architecture doesn’t match reality.

Output Formats

Terminal (default)

verikt diff

Human-readable output with checkmarks and colors.

JSON

verikt diff -o json

Machine-readable output for CI pipelines:

{
  "architecture": "hexagonal",
  "capability_diffs": [
    {
      "name": "http-api",
      "status": "ok",
      "expected_files": ["adapter/httphandler/handler.go", "..."],
      "missing_files": []
    }
  ],
  "summary": {
    "total_capabilities": 4,
    "fully_present": 3,
    "drift_score": 0.12
  }
}

Markdown

verikt diff -o markdown

Table format suitable for PR comments or documentation.

Common Workflows

After Refactoring

Run verikt diff after any significant refactoring to catch accidentally deleted files:

# Refactor, then check
verikt diff

In CI

Add drift detection to your CI pipeline:

# Fail if any drift is detected
verikt diff -o json | jq -e '.summary.drift_score == 0'

Fixing Drift

When drift is detected, you have two options:

Re-add the missing files — use verikt add to regenerate them:
Terminal window
```
verikt add redis
```
Update the declaration — if the drift is intentional, remove the capability from verikt.yaml