Skip to main content

​
How drift works

From a local checkout, driftless context get --diff matches changed files against workspace topics using their explicit paths and glob anchors. With --mark, matching reviewed topics are marked drifted with a human-readable reason. For example, if local work changes src/auth/guard.ts and src/auth/service.ts, the auth-flow topic anchored to src/auth/** can become:
Drifted: local changes touch src/auth/guard.ts and src/auth/service.ts.

​
Explicit local drift

The CLI reports drift from your local checkout:
--mark is opt-in and explicit. Plain --diff only displays, so work-in-progress never flips team state unless you ask. It’s idempotent (already-drifted topics are left alone).

​
A nudge, not an alarm

Drift is a nudge, not an error: “the code under this topic moved, worth a look.” It tolerates false positives by design: trust the code, and only update the topic if the change actually altered how the area works. A deleted anchor file produces a distinct nudge: “anchored file deleted: re-anchor or archive this topic.”

​
Lifecycle

When a topic goes drifted:
  1. driftless sync surfaces persisted drift to every team member
  2. An agent or human reviews the change
  3. If the context still holds, add it to knowledge (--status reviewed) to make it fresh again
  4. If no repo claims the topic anymore, it becomes orphaned

​
Checking for drift

Only an explicit local context get --diff --mark call. Plain --diff retrieves matching context without changing workspace state.
Yes. Run driftless context get --diff --mark from the relevant checkout. Update the topic when its durable explanation changed; otherwise confirm that it is still current.
Local pattern validation catches missing anchors when you write from the CLI. context doctor also flags a zombie, an anchor pointing at nothing. Fix the patterns or archive the topic.