| name | check-project-drift |
| description | Five drift checks for detecting where the codebase has outpaced documentation — knowledge map integrity, spec.md vs xtask parity, exec-plan lifecycle drift, stale active plans, ADR coverage gaps. Preloaded by drift-detector. |
| user-invocable | false |
Run all four checks in order. Report everything — do not fix.
Check 1 — Knowledge map integrity (CLAUDE.md)
Extract every file path from CLAUDE.md's knowledge map. Verify each exists:
test -e {path} && echo "OK {path}" || echo "MISSING {path}"
Also scan for undocumented additions:
.md files in docs/ not listed in the map- New
xtask/src/ subcommand files not reflected in spec.md or CLAUDE.md
Labels: MISSING (referenced but gone), UNDOCUMENTED (exists, not in map).
Check 2 — spec.md vs xtask parity
Subcommands from source:
grep -r "\"check-\|\"gen-\|\"audit-\|\"verify-" xtask/src/ 2>/dev/null | grep -oE '"[a-z][a-z-]+"' | sort -u
Subcommands from spec.md:
grep -oE 'cargo xtask [a-z][a-z-]+' spec.md | awk '{print $3}' | sort -u
Labels: UNDOCUMENTED (in source, missing from spec.md), PHANTOM (in spec.md, gone from source).
Check 3 — Exec-plan lifecycle drift
Plans should flow proposed/ → active/ → completed/. Each transition can drift:
3a. Proposed plans where work has already started (should be active/)
For each file in docs/exec-plans/proposed/:
- Extract the slug (filename without
.md)
- Check git log for activity referencing the slug or its keywords:
git log --oneline --since="60 days ago" | grep -iE "{slug-keywords}"
- Check whether files the plan says to create now exist
- Check whether a branch matching the slug exists or was recently merged
Label: LIKELY_ACTIVE (with evidence — commit SHAs, file paths).
3b. Active plans where work appears done (should be completed/)
For each file in docs/exec-plans/active/:
- Extract the target files, crates, or features it describes
- Check if the work looks already complete:
- Files the plan says to create already exist with non-stub content
- The described problem is already solved in the codebase
- Commit messages contain "closes", "completes", or the plan's slug
- Check for stale references — paths in the plan that no longer exist
Labels: LIKELY_DONE (with evidence), STALE_REFS (references paths that no longer exist).
3c. Long-stalled proposed plans
Flag plans in proposed/ older than 90 days with no matching git activity. These should either be moved to active/, abandoned (annotated with Status: abandoned), or restated.
Label: STALLED (age + no activity).
Check 4 — ADR coverage gaps
Read docs/design-docs/index.md. Then check whether major framework choices and architectural patterns have a corresponding ADR:
grep -l "axum\|rmcp\|tokio\|figment\|utoipa" docs/design-docs/*.md 2>/dev/null
Look for:
- Significant dependencies in
spec.md § Framework Choices with no ADR
- Core patterns (two-tier errors, action+params contract, single-port topology) with no recorded rationale
Label: NO_ADR.
Output format
=== Check 1: Knowledge Map ===
MISSING docs/sessions/README.md (referenced in CLAUDE.md, file gone)
UNDOCUMENTED docs/research/2025-03-cve.md (exists, not in knowledge map)
=== Check 2: spec.md vs xtask ===
UNDOCUMENTED check-msrv (in source, not in spec.md)
PHANTOM check-old-lint (in spec.md, not in source)
=== Check 3: Exec-plan lifecycle ===
LIKELY_ACTIVE proposed/2026-04-15-cache-layer.md (3 commits matching "cache-layer", target file crates/core/src/cache.rs exists)
LIKELY_DONE active/2025-01-15-auth-flow.md (auth middleware exists at crates/app/src/api/auth/)
STALE_REFS active/2025-02-20-mcp-tools.md (references crates/mcp/ which doesn't exist)
STALLED proposed/2025-09-01-search-ui.md (94 days old, no git activity matching slug)
=== Check 4: ADR Coverage ===
NO_ADR axum (framework choice, no ADR in design-docs/)
NO_ADR action+params contract (core pattern, no ADR found)
=== Summary ===
{n} knowledge map issues, {n} xtask parity issues, {n} stale plans, {n} ADR gaps
