Skip to main content

​
How drift works

When a push arrives on a tracked branch, the API matches changed files against all workspace topics using glob pattern intersection. Any topic whose anchored patterns overlap with the changed files gets marked drifted with a human-readable reason. For example, if a push to main changes src/auth/guard.ts and src/auth/service.ts, the auth-flow topic anchored to src/auth/** becomes:
Drifted: 3 files changed in commit abc1234: src/auth/guard.ts, src/auth/service.ts, src/auth/dto/login.dto.ts

​
Tracked branches

The default branch is always tracked. Additional branches can be added: 
driftless branches add staging
driftless branches add release/*
driftless branches
driftless branches rm staging
Feature branches are not tracked by default. This prevents noise because most feature work is in progress and does not represent settled architecture. Drift is reserved for branches where changes signal durable context shifts.

​
Second drift source: local git (no GitHub App)

Drift normally comes from push webhooks, so a team without the GitHub App installed gets no signal. To close that gap, the CLI can report drift from your local checkout: 
driftless context get --diff          # show topics matching local changes (display only)
driftless context get --diff --mark   # …and flag those topics drifted on Cloud
--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

drifted → agent reviews → driftless context update topic --status reviewed → fresh again
drifted → no repo claims it → orphaned
When a topic goes drifted:
  1. driftless sync surfaces it 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
driftless context update auth-flow --status reviewed

​
Checking for drift

driftless sync                         # shows drifted topics and what changed
driftless context doctor               # full health audit across all topics
driftless context get --diff            # drift for current local (uncommitted) changes
Only pushes to tracked branches. PRs do not trigger drift; they trigger PR observation instead (the match is recorded, and the Auditor, if configured, reviews and comments only when it has a finding). This distinction keeps drift meaningful: a push to main or staging means the code has actually changed, while a PR is still under review and may not merge.
Yes. Run driftless context update <slug> --status draft to mark it for review, or update the content and set --status reviewed to clear drift. You can also let the next push naturally trigger a drift check.
The topic becomes drifted on the next push. If the glob patterns no longer match any file in the repo, context doctor flags it as a zombie, an anchor pointing at nothing. Fix the patterns or archive the topic.