VibeMap Logo

Drift detection

On this page

Drift detection

VibeMap flags when your code has moved on from the spec it was grounded in, and points you at exactly what to re-sync. · Optional

Use this once you have a confirmed code map and you keep shipping code. As your repo changes, the spec that was generated from an earlier snapshot slowly falls out of date. Drift detection tells you which files changed, which features are affected, and hands your agent a prompt to bring both back in line.

How drift is detected

Drift is measured against the commit SHA anchored on your code map — VibeMap never watches your repo on its own. You (or your agent) run a sync check:

  1. On the Codebase page, the drift banner includes a ready-made prompt. Copy it into your IDE agent.
  2. The agent reads the map's anchor commit via vibemap_get_code_map, runs git diff --name-only <commitSha>..HEAD (plus any untracked files), and calls vibemap_sync_changes with the changed paths and the current HEAD SHA.
  3. VibeMap cross-references those changed files against the map's nodes and your feature provenance, and stores a drift report.

Reading the drift report

When drift exists, the status chip turns amber — "Drifted — N files changed" — and a banner appears above the map:

  • Files changed since the last sync, shown as <base sha> → <head sha>.
  • Affected units — map nodes whose files were touched (these are ringed amber on the diagram).
  • Affected features — features linked to those nodes, rendered as chips that link straight to the Features page.
  • Unmapped changes — changed files that don't correspond to any node (new areas the map doesn't cover yet), listed up to a cap so the banner stays readable.

This is the value of the feature links from Codebase sync & code map: drift isn't just "some files changed", it's "these specific features may now be inaccurate."

Each drifted feature also shows up as a finding — a warning on that feature, in the same list as your coverage gaps and staleness, on the Prepare for Dev page. So drift follows you to the place where you decide the spec is ready to build, instead of living only on a banner you might not visit.

Clearing drift

Drift is persistent. It does not expire, and a fresh sync check will not clear it: each sync is a new observation, and a run that happened to touch fewer files says nothing about whether the earlier drift was ever reconciled — so affected units and features accumulate onto the stored report. Re-submitting the code map doesn't clear it either; the report is carried across onto the new map.

The one thing that clears drift is an explicit resolve, and only after you've actually reconciled the spec:

  1. Work through the report — update the stale features, user stories, and acceptance criteria it flags. The banner's ready-made prompt asks your agent to do exactly this.
  2. Re-submit the code map so the anchor commit matches your current HEAD.
  3. Resolve the units you fixed. This is a deliberate acknowledgement rather than a button: PATCH /api/mcp/code-map with action: "resolve_drift" and the ids of the nodes you reconciled — something your agent or a script can do at the end of the pass. Those nodes drop out of the report, and any feature whose last drifted node was resolved drops out with them. When nothing is left, the banner goes away.

💡 Tip: Run a sync check after each meaningful merge, or before a planning session — it's the cheapest way to keep the spec trustworthy rather than letting it rot silently.

⚡ Power-user hints

  • Drift is stored on the code map (there's no separate history to manage), which means it survives everything except a resolve. Treat the banner as a to-do list, not a notification.
  • Unmapped changes are a hint that your architecture grew: when you see a lot of them, it's time to have your agent build a fresh map rather than patch the old one.
  • Because the check is a plain git diff your agent already has the tools for, you can bundle it into a routine ("before every sprint, run a VibeMap drift check on this repo").

↔ The traditional way

Normally, keeping documentation, tickets, and a spec in sync with a moving codebase is a manual, thankless chore — so it doesn't happen, and the spec quietly becomes fiction. Drift detection turns that into a diff-driven signal: it tells you the exact files and features that have moved, so the update is targeted instead of a full rewrite.

What's next