drift

Drift

drift binds markdown docs to code and lints for staleness.

Why this matters for agents

When you change code without updating the docs that describe it, those docs become stale. Stale docs get loaded as context in future sessions and produce wrong code based on wrong descriptions. This compounds — each session that trusts a stale doc makes things worse. drift makes the anchor explicit and enforceable so this feedback loop breaks.

Relink gate

drift link refuses to restamp a stale anchor without explicit review. When a target's signature has drifted, drift link prints both sides — the doc section (spec) and the current code — then exits 1.

This means you cannot blindly relink. You must review the doc prose and confirm it is still accurate. Use:

drift link docs/auth.md --doc-is-still-accurate

After you change code

Find which docs reference the files you touched:

drift refs src/auth/login.ts

Or check all docs at once:

drift check

If a doc is stale because of your change:

1. Run drift link <doc-path> — it will print the doc section and current code side by side, then refuse
2. Read both sides to understand what's out of sync
3. Update the doc's prose to reflect what you changed
4. Run drift link <doc-path> --doc-is-still-accurate — succeeds now that you've reviewed
5. Verify: drift check

Do not skip this. Leaving a doc stale is worse than leaving it unwritten.

After you change a doc

Refresh all anchors in the doc to snapshot current state:

drift link docs/my-doc.md

This updates provenance on all bindings in drift.lock for that doc, including inline @./ references.