> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trybrein.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Drift Detection

> How Driftless detects when code has changed relative to team context.

## 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:

```bash theme={"theme":"github-light"}
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 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

```bash theme={"theme":"github-light"}
driftless context update auth-flow --status reviewed
```

## Checking for drift

```bash theme={"theme":"github-light"}
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
```

<AccordionGroup>
  <Accordion title="What triggers drift?">
    Only an explicit local `context get --diff --mark` call. Plain `--diff` retrieves matching context without changing workspace state.
  </Accordion>

  <Accordion title="Can I manually mark a topic as drifted?">
    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.
  </Accordion>

  <Accordion title="What happens if a topic's anchored files are deleted?">
    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.
  </Accordion>
</AccordionGroup>