Skip to main content

Drift Detection

Drift is what happens when local files diverge from the desired state. Workloom detects, classifies, and reports drift so your team catches problems before they become incidents.

Why Drift Matters​

Without drift detection:

  • A developer manually edits a generated file → changes are silently lost on next pull
  • A new package version is published → some repos update, others don't
  • CI has no way to verify that AI configs match what was approved
  • "Works on my machine" becomes "works with my AI config"

With Workloom:

  • wl sync --check in CI catches drift immediately
  • Drift is classified by type so you know exactly what diverged and why
  • Resolution paths are clear for each drift class

The Seven Drift Classes​

Workloom classifies drift into seven distinct types, each with specific exit behavior:

1. Clean​

No drift. Local files match the desired state exactly.

$ wl sync --check
✓ All files match desired state (revision 12)
# Exit code: 0

2. Modified​

A Workloom-managed file was edited locally.

$ wl sync --check
✗ Drift detected:
  modified: CLAUDE.md (local hash differs from desired state)
# Exit code: 1

Resolution: wl restore CLAUDE.md or wl pull --on-conflict keep-local

3. Missing​

A Workloom-managed file was deleted locally.

$ wl sync --check
✗ Drift detected:
  missing: .claude/skills/review/SKILL.md
# Exit code: 1

Resolution: wl restore to recreate missing files

4. Unknown​

A file exists in a Workloom-managed path but isn't tracked in state.

$ wl sync --check
✗ Drift detected:
  unknown: .claude/skills/my-custom/SKILL.md
# Exit code: 1

Resolution: Remove the file, or use wl status to understand the unexpected file

5. Provider Mismatch​

A file was rendered for a provider that's no longer assigned to the target.

$ wl sync --check
✗ Drift detected:
  provider_mismatch: .codex/config.toml (codex not in target providers)
# Exit code: 1

Resolution: Update target providers or remove the orphaned file

6. Policy Drift​

A file's projection policy changed (e.g., from generated_local to approval_required).

$ wl sync --check
✗ Drift detected:
  policy_drift: .claude/hooks/pre-commit.sh (now requires approval)
# Exit code: 1

Resolution: Approve the new policy or remove the file

7. Nested Target Drift​

A file in a nested target conflicts with the parent target's render plan.

$ wl sync --check
✗ Drift detected:
  nested_target: apps/web/CLAUDE.md (conflicts with root target)
# Exit code: 1

Resolution: Review target configuration for overlapping paths

Using Drift Detection in CI​

The most powerful use of drift detection is as a CI gate:

# .github/workflows/drift-check.yml
name: AI Config Compliance
on: [pull_request]

jobs:
  drift-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @workloom/cli
      - run: wl sync --check
        env:
          WL_TOKEN: ${{ secrets.WORKLOOM_CI_TOKEN }}

This ensures:

  • PRs that introduce config drift are flagged
  • The main branch always matches the approved desired state
  • New team members can't accidentally commit manual config changes

Drift vs. Local Modifications​

Not all local changes are problems. Workloom's ownership model distinguishes between:

  • Managed files that drifted (problem → fix or accept)
  • Locally modified files that you intentionally changed (tracked, respected)
  • User-local files that are yours (never touched by Workloom)

wl sync --check reports drift for managed files. Locally modified files are reported separately as informational — they're not drift, they're intentional deviations.