Drift detection

Solo developer? You can skip this page. Drift detection is for teams using lockfiles and team mode.

Drift detection helps teams keep .aligntrue/lock.json in sync with the rules and config it represents. It reports when rules or team config changed after the lockfile was generated.

Overview

Drift detection checks if the current bundle_hash matches the lockfile. The bundle hash covers:

All team-scoped rules (.aligntrue/rules/*.md excluding scope: personal)
Team config (.aligntrue/config.team.yaml)

If the hash differs, drift has occurred.

Key benefits:

Catch rule changes before they silently diverge from the lockfile
CI/CD integration with --gates flag
Simple: one hash, one check

Usage

Basic drift check


# Show drift (human-readable)
aligntrue drift
 
# Output:
# Drift detection report
# ======================
# Mode: team
#
# LOCKFILE DRIFT:
#   _bundle
#     Rules or team config have changed since last lockfile generation
#     Suggestion: Run: aligntrue sync (to regenerate lockfile)
#
# Lockfile: .aligntrue/lock.json
# Findings: 1

CI integration


# Exit non-zero if drift detected
aligntrue drift --gates
 
# Exit codes:
# 0 = No drift (or drift without --gates)
# 1 = Not in team mode
# 2 = Drift detected when --gates is set

JSON output


# Machine-readable output
aligntrue drift --json
 
# Output:
# {
#   "mode": "team",
#   "has_drift": true,
#   "lockfile_path": ".aligntrue/lock.json",
#   "findings": [
#     {
#       "category": "lockfile",
#       "ruleId": "_bundle",
#       "description": "Rules or team config have changed since last lockfile generation",
#       "suggestion": "Run: aligntrue sync (to regenerate lockfile)",
#       "lockfile_hash": "sha256:...",
#       "expected_hash": "sha256:..."
#     }
#   ],
#   "summary": {
#     "total": 1,
#     "by_category": {
#       "lockfile": 1
#     }
#   }
# }

SARIF output


# For CI tools that support SARIF
aligntrue drift --sarif

CI/CD examples

GitHub Actions


name: Drift Check
 
on: [pull_request]
 
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
 
      - name: Install dependencies
        run: npm ci
 
      - name: Check for drift
        run: npx aligntrue drift --gates

GitLab CI


drift-check:
  stage: test
  script:
    - npm ci
    - npx aligntrue drift --gates
  only:
    - merge_requests

Common fixes

Lockfile drift detected

Cause: Rules or team config changed since lockfile was generated.

Fix:


# Regenerate the lockfile
aligntrue sync
 
# Commit the updated lockfile
git add .aligntrue/lock.json
git commit -m "chore: Update lockfile"

No lockfile found

Cause: Team mode enabled but lockfile not generated yet.