Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.driftless.icu/llms.txt

Use this file to discover all available pages before exploring further.

​
How staleness works

When a push arrives on a tracked branch, the API matches changed files against all workspace topics. Any topic whose anchored files or patterns overlap with the changed files gets marked stale 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:
Stale: 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 list
driftless branches remove staging
Feature branches are not tracked by default. This prevents noise because most feature work is in progress and does not represent settled architecture. Staleness is reserved for branches where changes signal durable context shifts.

​
Structural staleness

Beyond simple file matching, Driftless detects structural changes:
  • Deleted endpoint files - An endpoint that was extracted in a previous scan no longer exists
  • Removed guards - A guard that was protecting an endpoint has been removed
  • Deleted services - A service class no longer exists in the codebase
  • Module restructuring - Files moved between modules
These structural signals are more informative than file-level diffs because they describe what changed architecturally, not just which files were touched.

​
Lifecycle

stale -> agent reviews -> driftless context update topic --status reviewed -> unstale
stale -> no repo claims it -> orphaned
When a topic goes stale:
  1. driftless sync surfaces it to every team member
  2. An agent or human reviews the change
  3. If the context still holds, mark it reviewed to unstale it
  4. If no repo claims the topic anymore, it becomes orphaned
driftless context update auth-flow --status reviewed

​
Checking for staleness

driftless sync                         # shows stale topics and what changed
driftless context doctor               # full health audit across all topics
driftless context get --diff            # staleness for current local (uncommitted) changes
Only pushes to tracked branches. PRs do not trigger staleness; they trigger PR observation instead (sticky context comments listing relevant topics). This distinction keeps staleness 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. Use driftless context update <slug> --stale --reason "...". This is useful when you review a topic and notice it’s outdated even though the file patterns haven’t been pushed yet.
The scanner detects missing files during the next scan and reports them as structural staleness. The topic stays stale until someone either updates its anchors or confirms the context is no longer relevant (at which point it can be orphaned or deleted).