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 tab, 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.

Drift banner on the Codebase tab

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 12.1: drift isn't just "some files changed", it's "these specific features may now be inaccurate."

Clearing drift

The banner includes a prompt that asks your agent to update the stale features, user stories, and acceptance criteria the report flags, then re-submit the code map. Re-submitting the map replaces the anchor and its stored drift, so the banner clears itself once your specs and code are back in agreement.

💡 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). One re-submit is the whole reset — you never have to dismiss the banner by hand.
  • 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