TenantAtlas/specs/119-baseline-drift-engine/quickstart.md

Quickstart — Spec 119 (Drift Golden Master Cutover)

Prereqs

• Run the app via Sail.

Local setup

• Start containers: vendor/bin/sail up -d
• Run migrations: vendor/bin/sail artisan migrate

How to exercise the feature (manual)

1) Ensure baseline prerequisites exist

• Ensure the tenant has a recent successful Inventory Sync.
• Ensure a Baseline Profile is assigned and has an active Baseline Snapshot.
• If you just deleted or renamed a duplicate policy in Intune, run Inventory Sync again before capturing a new Baseline Snapshot; capture now scopes subjects to the latest completed sync.

2) Run Baseline Compare (drift entry point)

• Navigate to the Drift entry point (Baseline Compare landing):
  • GET /admin/t/{tenant}/baseline-compare-landing
• Trigger “Compare Now” (queued operation).
• Expected:
  • An OperationRun of type baseline_compare is created/updated and visible in Monitoring → Operations.
  • Drift findings are created/updated with source = baseline.compare.

2a) Trigger a guaranteed compliance-policy drift

• Pick an in-scope compliance policy that is already present in the active Baseline Snapshot.
• Change either a core compliance setting or an action under Intune “Actions for noncompliance” (for example: gracePeriodHours, removing retire, or changing the notification template).
• Run Inventory Sync, then run Baseline Compare (full content).
• Expected:
  • A different_version drift finding is created when the canonical compliance payload changed.
  • Reordering the same noncompliance actions or Graph-only ID churn does not create a finding.

3) Validate diff UX behavior

• Open a drift finding in the tenant Findings UI:
  • GET /admin/t/{tenant}/findings/{record}
• Expected:
  • evidence_jsonb.summary.kind is present (one of: policy_snapshot, policy_assignments, policy_scope_tags).
  • For different_version, if both baseline.policy_version_id and current.policy_version_id exist: the appropriate diff view renders.
  • For missing_policy, if baseline.policy_version_id exists: the diff renders against an empty current side.
  • For unexpected_policy, if current.policy_version_id exists: the diff renders against an empty baseline side.
  • If the required reference(s) for the change type are missing: the UI shows an explicit “diff unavailable” explanation.

3a) Validate no-drift full-content compare behavior

• If you run a full-content Baseline Compare immediately after capturing a matching baseline snapshot, the run should resolve current content evidence without creating drift findings.
• Expected:
  • baseline_compare.reason_code = no_drift_detected
  • no missing_current evidence gaps caused solely by reused identical compare-purpose policy_versions

4) Validate legacy drift removal (hard cut)

• Expected post-cutover:
  • No Drift landing page that triggers “Generate drift” exists.
  • No operation run type catalog labels, widgets, or alerts reference legacy drift generation.

5) Validate legacy dataset cleanup

• After deploying the cleanup migration:
  • Legacy drift findings where source is null or not baseline.compare are deleted.
  • Baseline Compare drift findings remain intact.

Tests (Pest)

• Run focused suites once implemented:
  • vendor/bin/sail artisan test --compact --filter=Drift
  • vendor/bin/sail artisan test --compact --filter=BaselineCompare
  • Or run specific files under /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Drift/ and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Baselines/.