Drift, Baselines & History

What ArchPilot records over time

• Minimal validation snapshots
• Architecture score and readiness trends
• Drift events between runs
• Baseline comparison results
• History views that summarize whether architecture is improving or regressing

Why this matters

Architecture drift detection is most useful when it is not purely anecdotal. History and baselines give teams a concrete way to discuss whether architecture is actually becoming healthier or just producing different findings.

That is valuable for local validation, CI architecture validation, and organization governance when you later add ArchPilot Cloud.

A practical baseline workflow

1. Run validation until the current state is acceptable enough to use as a reference point.
2. Create or refresh a baseline for the current architecture state.
3. Compare later validation runs against that baseline to spot regressions.
4. Use the local history view to see whether the architecture trend is improving, stable, or declining.

Structural architecture baseline

The structural baseline is used for architecture drift checking. `archpilot baseline create`, `archpilot baseline update`, and `archpilot baseline check` work with `.archpilot/baseline/architecture-baseline.json`.

That artifact captures structural architecture state from the architecture map: modules, dependency edges, cycles, and orphan-module structure. `archpilot baseline check` also writes `.archpilot/reports/architecture-drift.json` when it can compare the current map to the baseline.

The generated pull-request workflow runs `archpilot baseline check` only after architecture validation succeeds. A missing or invalid structural baseline is treated as setup guidance by the generated workflow instead of automatically failing otherwise successful validation.

• Default drift policy is warn.
• The workflow_dispatch drift policy can be set to fail when detected structural drift should block.
• You do not need to create a structural baseline before introducing ArchPilot CI; create it when the team is ready to track accepted architecture drift.

Governance baseline

The governance baseline is separate from structural PR drift checking. `archpilot baseline refresh` captures the current full validation summary into `.archpilot/baseline/baseline.json` after validation has produced `.archpilot/reports/architecture-summary.json`.

This baseline supports governance/history comparison: health, readiness, finding counts, remaining violations, finding deltas, and change-risk context across validation runs.

Use the structural baseline for PR architecture drift. Use the governance baseline when you want accepted validation state for governance trend and regression comparison.