| name | reconciliation |
| description | Detect drift between arkive/architecture.json and the actual codebase. |
| trigger | User says "check drift", "reconcile", "is the architecture up to date", or when returning to a project after a break. |
Reconciliation — Drift Detection
When to Use
- When returning to a project after a break
- When multiple developers or AI agents have made changes
- When you suspect the architecture doc is out of date
- Periodically as a health check
How to Reconcile
Option A: Via CLI (recommended)
Run: npx @ericjdz/arkive reconcile
This scans package.json and source imports under src/, then reports mismatches against arkive/architecture.json.
Option B: Via MCP tool
Call the check_drift tool. It returns the same report as the CLI command.
Option C: Manual scan
If neither CLI nor MCP is available:
- Read
arkive/architecture.json
- Check these files for ground truth:
package.json / requirements.txt / go.mod → actual dependencies vs stack
- Import statements across source files → actual connections vs
connections
- For each mismatch, note:
- What the doc says vs what the code shows
- Severity: Critical (service missing), Warning (dependency mismatch), Info (minor drift)
Current scanner limitations: The automated scanner checks package.json dependencies and src/ import statements. It does NOT currently scan Docker, nginx, env files, or infrastructure configs. For those, do a manual review.
After Reconciliation
Update arkive/architecture.json to reflect reality. MUST append a history entry:
{
"timestamp": "ISO 8601 now",
"action": "reconciliation",
"summary": "Reconciled arkive/architecture.json with codebase — fixed N mismatches"
}
MUST NOT
- Do NOT silently fix drift without reporting what changed
- Do NOT remove entries from arkive/architecture.json without verifying they are truly gone from the codebase