Drift Baselines & Fitness Functions

Overview

Vibgrate uses baselines to track drift over time and fitness functions to enforce quality gates. Together, they enable drift governance at scale.

Key Concept: A baseline is a snapshot of your drift state. Future scans compare against it to detect regression.

Storage Structure

Vibgrate stores scan state under .vibgrate/:

.vibgrate/
├── baseline.json          # Committed - reference snapshot
├── scan_result.json       # Ignored - latest scan output
└── config.ts              # Committed - configuration

File	Purpose	Version Control
`baseline.json`	Reference for drift comparison	✅ Commit
`scan_result.json`	Latest scan output	❌ Ignore
`config.ts`	Scanner configuration	✅ Commit

Baseline Workflow

Step 1: Create Initial Baseline

# On main branch
vg baseline

Output:

✓ Scanning repository...
✓ DriftScore: 67/100
✓ Baseline saved to .vibgrate/baseline.json
→ Commit this file to version control

Step 2: Commit to Version Control

git add .vibgrate/baseline.json
git commit -m "chore: establish drift baseline"

Step 3: Enable CI Gates

vg scan \
  --baseline .vibgrate/baseline.json \
  --drift-budget 40 \
  --drift-worsening 5 \
  --fail-on error

Step 4: Refresh After Upgrades

# After completing upgrade work
vg baseline
git add .vibgrate/baseline.json
git commit -m "chore: refresh baseline after Q1 upgrades"

Fitness Functions

Fitness functions are automated quality gates that enforce drift policies:

Flag	Purpose	Example
`--drift-budget <n>`	Absolute ceiling on drift score	`--drift-budget 40`
`--drift-worsening <n>`	Maximum regression from baseline	`--drift-worsening 5`
`--fail-on <level>`	Fail on finding severity	`--fail-on error`

Gate Combinations

Policy	Flags	When to Use
🟢 Permissive	`--fail-on error`	Early adoption
🟡 Balanced	`--drift-budget 50 --fail-on error`	Standard governance
🔴 Strict	`--drift-budget 30 --drift-worsening 3 --fail-on warn`	Security-critical

Strict Policy Example

vg scan \
  --baseline .vibgrate/baseline.json \
  --drift-budget 30 \
  --drift-worsening 3 \
  --fail-on error

This fails if:

📊 Score exceeds 30 (budget gate)
📉 Drift increased > 3% vs baseline (regression gate)
🚨 Any error-level findings exist

Baseline Refresh Strategies

Strategy	When	Rationale
🗓️ Scheduled	Quarterly	Regular maintenance cycles
🎯 Event-driven	After upgrade PRs	Capture improvements
📊 Threshold	When score improves 10+	Ratchet effect

Tip: Don't refresh too often. Baselines should represent a "known good" state.

Gradual Tightening

Start with lenient gates and tighten over time:

# Month 1: Establish baseline only
vg baseline

# Month 2: Add budget gate
vg scan --drift-budget 60 --fail-on error

# Month 3: Add regression gate
vg scan --drift-budget 50 --drift-worsening 10 --fail-on error

# Month 6: Tighten thresholds
vg scan --drift-budget 40 --drift-worsening 5 --fail-on error

Best Practices

Practice	Rationale
🔄 Commit baseline to version control	Ensures CI consistency
📅 Refresh after upgrade sprints	Captures improvements
📈 Start permissive, tighten gradually	Builds team buy-in
📝 Document baseline refresh decisions	Audit trail

vg baseline — Create baselines
DriftScore — Understanding the scoring
CI Integration — Automated enforcement