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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.