# Quickstart: Governance Subject Taxonomy and Baseline Scope V2

## Goal

Turn baseline scope into a platform-capable governance-subject contract without breaking the current Intune baseline workflow. New and updated baseline profiles should persist canonical V2 scope, legacy profiles should still work, and capture or compare starts should consume normalized effective scope.

## Implementation Sequence

1. Add the governance taxonomy registry.
   - Introduce platform-facing domain and subject-class vocabulary.
   - Compose current `supported_policy_types`, `foundation_types`, and support metadata into one baseline-selection registry.
   - Mark only active and currently supported subject types as operator-selectable.

2. Upgrade scope normalization to canonical V2.
   - Evolve the current `BaselineScope` entrypoint to parse legacy and V2 inputs.
   - Normalize legacy arrays into explicit V2 entries.
   - Reject mixed or ambiguous payloads and handle duplicate entries deterministically.

3. Wire save-forward persistence into baseline profile flows.
   - Keep the current Intune-first selectors in the Filament form.
   - Persist canonical V2 into `scope_jsonb` on create and edit.
   - Render a normalized scope summary on touched baseline surfaces without showing raw JSON.

4. Route capture and compare through normalized effective scope.
   - Derive the effective scope from the profile scope and compare assignment override when present.
   - Enforce capture or compare support gating before enqueuing runs.
   - Write canonical effective scope into `OperationRun.context` for audit and debugging.

5. Add optional cleanup and regression coverage.
   - Implement a maintenance command that previews remaining legacy baseline profile scope rows by default, requires explicit write confirmation for committed rewrites, and writes audit entries when it mutates profile scope rows.
   - Keep compare assignment overrides on tolerant-read normalization only in this slice.
   - Extend unit, feature, and Filament coverage for normalization, validation, save-forward behavior, start-surface behavior, operation-truth continuity, authorization continuity, and no-regression Intune operation paths.

## Suggested Test Files

- `apps/platform/tests/Unit/Baselines/BaselineScopeTest.php`
- `apps/platform/tests/Unit/Baselines/GovernanceSubjectTaxonomyRegistryTest.php`
- `apps/platform/tests/Unit/Baselines/InventoryMetaContractTest.php`
- `apps/platform/tests/Feature/Baselines/BaselineCaptureTest.php`
- `apps/platform/tests/Feature/Baselines/BaselineComparePreconditionsTest.php`
- `apps/platform/tests/Feature/Baselines/BaselineScopeBackfillCommandTest.php`
- `apps/platform/tests/Feature/Baselines/BaselineProfileAuthorizationTest.php`
- `apps/platform/tests/Feature/Filament/BaselineProfileFoundationScopeTest.php`
- `apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php`
- `apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php`
- `apps/platform/tests/Feature/Filament/BaselineProfileScopeV2PersistenceTest.php`
- `apps/platform/tests/Feature/Filament/BaselineActionAuthorizationTest.php`
- `apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`

## Required Verification Commands

Run all commands through Sail from `apps/platform`.

```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Baselines/BaselineScopeTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Baselines/GovernanceSubjectTaxonomyRegistryTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Baselines/InventoryMetaContractTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCaptureTest.php
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/BaselineScopeBackfillCommandTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineProfileAuthorizationTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineProfileFoundationScopeTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.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/BaselineProfileScopeV2PersistenceTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineActionAuthorizationTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
```

## Manual Acceptance Checklist

1. Open a legacy baseline profile and confirm the scope renders understandably without manual migration.
2. Save that profile and confirm the persisted `scope_jsonb` is rewritten in canonical V2 form.
3. Create a new baseline profile using the current Intune-first selector UI and confirm the saved scope is V2.
4. Attempt to save an invalid domain, class, or inactive subject type and confirm the save is rejected clearly.
5. Start baseline capture from a valid profile and confirm the run stores canonical effective scope.
6. Start baseline compare from a valid profile and confirm the run stores canonical effective scope.
7. Attempt to start capture or compare with an unsupported subject type and confirm the action is blocked before run creation.
8. Run the optional backfill command in preview mode and confirm candidate baseline profile rewrites are reported without mutating rows.
9. Execute the backfill command with explicit write confirmation and confirm semantic equivalence plus audit logging for committed profile-scope rewrites.
10. Confirm compare assignment overrides still normalize correctly without requiring rewrite in this release.
11. Verify inactive or future-domain subject types are not presented as ready-for-use operator options.

## Deployment Notes

- No schema migration is expected.
- No new asset registration is expected.
- No new queue topology is expected because capture and compare continue to use the existing operation types and jobs.
- If the optional backfill command is shipped, it should run only after rollout confidence is established, should be treated as maintenance rather than a deploy prerequisite, and applies only to baseline profile scope rows in this release.