Drift Baselines & Fitness Functions

What Are Fitness Functions?

In the context of software architecture, a fitness function is an automated check that ensures a system characteristic stays within acceptable bounds. Vibgrate applies this concept to dependency drift: instead of merely reporting your score, it enforces that drift does not exceed defined thresholds.

Drift State Files

Vibgrate stores scan state under .vibgrate/:

Creating a Baseline

vibgrate baseline .

This runs a full scan and saves the result as your reference point.

Drift Budget Gate

The --drift-budget flag sets an absolute maximum acceptable drift score:

vibgrate scan . --drift-budget 40

If the scanned score exceeds 40, the CLI exits with code 2.

Drift Worsening Gate

The --drift-worsening flag sets a relative threshold — how much worse drift can get compared to the baseline:

vibgrate scan . \
  --baseline .vibgrate/baseline.json \
  --drift-worsening 5

If drift has worsened by more than 5% compared to the baseline, the CLI exits with code 2.

Combining Gates

In practice, teams combine both gates with --fail-on for layered protection:

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

This fails the scan if:

• The drift score exceeds 40 (absolute budget)
• Drift has worsened by more than 5% vs baseline (regression detection)
• Any error-level findings are present (severity gate)

Recommended Workflow

1. Create baseline once on main branch:

vibgrate baseline .

1. In CI, run scan with comparison and gates:

vibgrate scan . \
  --baseline .vibgrate/baseline.json \
  --drift-budget 40 \
  --drift-worsening 5

1. When planned upgrades land, refresh baseline:

vibgrate baseline .

This makes drift a formal quality gate, not just reporting.