TenantAtlas/specs/203-baseline-compare-strategy/quickstart.md

Quickstart: Baseline Compare Engine Strategy Extraction

Goal

Extract the current Intune-shaped compare processing behind one explicit compare strategy while preserving the existing baseline compare run lifecycle, finding lifecycle, trust semantics, and operator-facing compare story.

Prerequisites

1. Work on branch 203-baseline-compare-strategy.
2. Ensure the platform containers are available:

cd apps/platform && ./vendor/bin/sail up -d

3. Keep Spec 202's canonical scope contract available because strategy selection depends on Baseline Scope V2.

Recommended Implementation Order

1. Lock the current compare behavior with focused regression tests

Run the existing compare-focused suite before extracting anything:

cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineComparePreconditionsTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareFindingsTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareGapClassificationTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareRbacRoleDefinitionsTest.php

Add any missing tests for unsupported scope, mixed-strategy scope, and current Intune compare classification parity before moving major compare logic.

2. Introduce the compare strategy contract and selection result

Add the narrow compare-support namespace under app/Support/Baselines/Compare/ with:

• compare strategy contract
• strategy capability registry
• strategy selection result
• compare subject result contract

Keep these objects internal and derived. Do not add a new table or new OperationRun type.

3. Wire strategy validation into compare start surfaces

Update BaselineCompareService so both:

• tenant compare start
• workspace compare-matrix fan-out compare

resolve one compatible strategy family from canonical scope before any run is enqueued.

Unsupported or mixed-scope requests should fail clearly before subject work begins.

4. Extract the current Intune compare implementation behind IntuneCompareStrategy

Move the current Intune-shaped subject-processing logic out of the core path in CompareBaselineToTenantJob, including:

• policy-type-specific normalizer selection
• section or evidence shaping that assumes Intune policy structure
• special-case subject handling such as RBAC role-definition compare rules
• strategy-owned subject projection metadata

Keep generic helpers such as CurrentStateHashResolver, DriftHasher, and finding lifecycle orchestration reusable by the job.

5. Feed existing finding and summary writers from the new result contract

Replace raw per-subject drift arrays with the structured compare-subject result contract where orchestration needs:

• summary aggregation
• finding write or update
• diagnostics persistence
• operator-safe degraded or failed state explanation

Do not create a new compare-result table.

6. Harden existing compare surfaces

Update the existing compare launch and review surfaces so they remain truthful for:

• unsupported scope
• mixed-strategy scope
• incomplete evidence
• ambiguous identity
• strategy failure

This work should stay within the existing baseline profile detail, compare matrix, tenant compare landing, and canonical run-detail surfaces.

Focused Verification

Run the most relevant suites after each phase:

cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineComparePreconditionsTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareExecutionGuardTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareFindingsTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareMatrixCompareAllActionTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareRbacRoleDefinitionsTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareMatrixPageTest.php

If the compare landing or matrix messaging changes materially, keep existing browser smoke coverage green as a final confidence pass.

Final Validation

1. Run formatting:

cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

2. Re-run the focused compare test pack.
3. Confirm that unsupported or mixed-scope compare requests fail before enqueue.
4. Confirm that the current Intune compare path still produces the same operator-visible finding, summary, and trust outcomes.