# Feature Specification: Governance Subject Taxonomy and Baseline Scope V2

**Feature Branch**: `202-governance-subject-taxonomy`  
**Created**: 2026-04-13  
**Status**: Draft  
**Input**: User description: "Spec 202 — Governance Subject Taxonomy & Baseline Scope V2"

## Spec Candidate Check *(mandatory — SPEC-GATE-001)*

- **Problem**: Baseline scope still communicates governed subjects primarily as Intune-flavored policy-type lists plus an unnamed foundation list, so the platform lacks a durable, platform-safe language for what a baseline actually governs.
- **Today's failure**: Existing Intune baseline workflows work, but the current scope model forces later compare, evidence, and future-domain work to infer meaning from legacy `policy_types` and `foundation_types` lists. That keeps platform-core semantics narrower than the product already claims.
- **User-visible improvement**: Operators keep an Intune-first baseline workflow, but the underlying scope becomes explicit, deterministic, and auditable. Baseline summaries can explain what is governed without raw JSON or implicit Intune assumptions, and unsupported selections are rejected before capture or compare starts.
- **Smallest enterprise-capable version**: Introduce one authoritative governance subject taxonomy contract, one versioned Baseline Scope V2 shape, deterministic legacy normalization, save-forward persistence for new or updated baselines, and only the minimal baseline-surface changes needed to keep the scope understandable.
- **Explicit non-goals**: No second governance domain, no broad repo-wide `policy_type` rename, no compare-engine rewrite, no plugin framework, no multi-domain baseline UI redesign, and no forced migration of Intune-owned adapter models into generic platform models.
- **Permanent complexity imported**: One platform taxonomy registry, one Baseline Scope V2 contract, one legacy normalization path, one optional maintenance backfill path, clarified platform-versus-Intune vocabulary, and focused regression coverage.
- **Why now**: Spec 203 depends on a clear input contract for governed subjects. Without this layer, compare-strategy extraction would either preserve hidden Intune leakage or introduce a vague abstraction without stable vocabulary.
- **Why not local**: A local wrapper around `policy_types` and `foundation_types` would hide the symptom on one surface but would not give the platform a durable answer to what a governed subject is or how future domains participate.
- **Approval class**: Core Enterprise
- **Red flags triggered**: New source-of-truth risk and cross-domain taxonomy risk. Defense: the taxonomy stays deliberately minimal, keeps Intune-owned internals in place, avoids a generic plugin system, and exists to solve a current contract problem rather than speculative future breadth.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12**
- **Decision**: approve

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace
- **Primary Routes**:
  - `/admin/baseline-profiles`
  - `/admin/baseline-profiles/create`
  - `/admin/baseline-profiles/{record}`
  - `/admin/baseline-profiles/{record}/edit`
  - `/admin/t/{tenant}/baseline-compare`
  - Existing baseline capture and baseline compare operation drilldowns reached from the baseline profile detail and tenant compare flows
- **Data Ownership**:
  - Workspace-owned baseline profiles remain workspace-owned. New and updated profile scope data becomes canonical V2 while legacy scope remains tolerated only at ingestion boundaries during rollout.
  - Tenant assignment override scope remains tolerated at ingestion boundaries and normalized on read for this release; this spec does not require rewrite of existing `baseline_tenant_assignments.override_scope_jsonb` rows.
  - Tenant-owned baseline snapshots, compare runs, findings, and related evidence remain tenant-owned and keep their existing domain ownership and lifecycle.
  - No new table or persisted domain entity is introduced. The change is a contract and normalization upgrade inside existing baseline scope storage.
- **RBAC**:
  - Existing workspace baseline view and manage capabilities continue to govern baseline profile list, create, edit, view, and any baseline start actions launched from those surfaces.
  - Existing tenant membership and tenant compare capabilities continue to govern `/admin/t/{tenant}/baseline-compare` and downstream tenant-owned compare details.
  - This spec changes selection semantics and validation, not authorization boundaries. Non-members remain `404`, entitled members without the required capability remain `403`, and no new destructive operator action is introduced.

## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)*

| Surface | Decision Role | Human-in-the-loop Moment | Immediately Visible for First Decision | On-Demand Detail / Evidence | Why This Is Primary or Why Not | Workflow Alignment | Attention-load Reduction |
|---|---|---|---|---|---|---|---|
| Baseline profile create and edit | Secondary Context Surface | Define which governed subject families belong in the baseline before any tenant capture or compare starts | Domain-safe scope summary, active subject groups, support readiness, and invalid-selection feedback | Detailed subject descriptions, inactive-type reasons, and future-domain support notes | Not primary because it supports later baseline operations rather than serving as the final governance-decision surface | Follows baseline definition workflow before capture or compare | Prevents operators from reconstructing hidden policy-versus-foundation semantics by hand |
| Baseline profile detail | Secondary Context Surface | Verify what the baseline governs before launching capture or compare | Canonical scope summary by domain and subject class, baseline status, and operation readiness | Full subject-type list, legacy-normalization detail, and downstream drilldowns | Not primary because it prepares operator action rather than being the compare result surface itself | Follows the baseline lifecycle from definition to capture and compare | Makes governed-scope truth visible in one place without raw JSON or adapter-only vocabulary |

## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*

| Surface | Action Surface Class | Surface Type | Likely Next Operator Action | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type / Justification |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Baseline profile create and edit | Config / Form | Workspace configuration form | Save an updated baseline definition | Form page itself | not applicable | Cancel, back navigation, and explanatory help remain secondary to the form body and scope summary | none | `/admin/baseline-profiles` | `/admin/baseline-profiles/{record}/edit` | Workspace context, normalized scope summary, supported subject count | Baseline profile / baseline scope | Which governed subject families the baseline includes and whether they are eligible for capture or compare | none |
| Baseline profile detail | Detail / Workflow hub | Workspace configuration detail | Verify scope and then start capture or compare | Explicit view page | not applicable | Related navigation to snapshots and compare matrix stays contextual; scope breakdown lives in detail sections rather than the action lane | none | `/admin/baseline-profiles` | `/admin/baseline-profiles/{record}` | Workspace context, domain and subject-class summary, assignment context | Baseline profile / baseline scope | Canonical governed-subject summary and current readiness for baseline operations | none |

## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*

| Surface | Primary Persona | Decision / Operator Action Supported | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|---|
| Baseline profile create and edit | Workspace baseline manager | Define or revise what the baseline governs | Configuration form | What subject families will this baseline govern, and are they supported for the intended baseline workflow? | Canonical scope summary, selected subject families, capture and compare readiness, validation failures | Legacy-normalization explanation, inactive-type details, and future-domain notes | readiness, support eligibility | `TenantPilot only` | Save baseline profile, Cancel | none |
| Baseline profile detail | Workspace baseline manager | Verify scope before starting baseline capture or compare | Configuration detail and workflow hub | What does this baseline govern right now, and is it safe to start the next operation? | Domain and subject-class summary, baseline status, current assignment context, capture and compare readiness | Full subject-type breakdown, normalization lineage, and downstream run details | lifecycle, support eligibility, scope completeness | `TenantPilot only` for profile changes, `simulation only` or existing run scope for compare or capture actions | Existing capture baseline and compare actions, contextual navigation to compare matrix | none |

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: yes
- **New persisted entity/table/artifact?**: no
- **New abstraction?**: yes
- **New enum/state/reason family?**: yes
- **New cross-domain UI framework/taxonomy?**: yes
- **Current operator problem**: Baseline scope still hides its actual meaning inside Intune-shaped lists. Operators can use the current screens, but the platform cannot explain or validate governed subjects without leaking adapter assumptions into capture, compare, and future expansion work.
- **Existing structure is insufficient because**: `policy_types` and `foundation_types` lists do not express domain ownership, subject class, operation support, or future domain participation. Any downstream consumer must already know Intune-only semantics to interpret them correctly.
- **Narrowest correct implementation**: Introduce only `domain_key`, `subject_class`, `subject_type_keys`, and optional `filters` in a versioned scope contract, backed by one authoritative taxonomy registry and a deterministic legacy-normalization path. Keep current Intune-first screens, existing baseline models, and existing compare architecture in place.
- **Ownership cost**: Ongoing review of taxonomy entries, normalization logic maintenance, careful rollout coverage for save-forward behavior, documentation of platform versus Intune boundaries, and regression tests for validation and no-regression baseline flows.
- **Alternative intentionally rejected**: A broad rename of `policy_type` usage or a generalized plugin framework was rejected because both would import churn and abstract machinery before the platform vocabulary is proven by real use.
- **Release truth**: current-release contract correction with deliberate preparation for follow-up compare extraction

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Keep existing Intune baselines usable (Priority: P1)

As a workspace baseline manager, I want existing Intune-only baseline profiles to keep loading, saving, capturing, and comparing so that the new taxonomy contract does not interrupt current production workflows.

**Why this priority**: The spec only succeeds if current baseline operations remain intact. Platform vocabulary work that regresses the existing Intune path is not shippable.

**Independent Test**: Open a legacy Intune baseline profile, verify its scope renders understandably, save it, then launch baseline capture and compare and confirm the behavior remains unchanged.

**Acceptance Scenarios**:

1. **Given** a baseline profile stored in the legacy `policy_types` and `foundation_types` shape, **When** the profile detail or edit page loads, **Then** the system shows the effective governed scope through the normalized contract without requiring manual migration.
2. **Given** a legacy Intune-only baseline profile, **When** the operator saves the profile, **Then** the stored scope is written forward in canonical V2 form without changing the effective governed subject set.
3. **Given** a legacy Intune-only baseline profile, **When** the operator starts baseline capture or baseline compare, **Then** the resulting operation uses normalized scope semantics and preserves the current Intune behavior.

---

### User Story 2 - Define a baseline with explicit governed-subject semantics (Priority: P1)

As a workspace baseline manager, I want baseline scope selection to describe governed subject families explicitly so the platform can validate and summarize the baseline without relying on hidden Intune-only assumptions.

**Why this priority**: This is the core product change. Without an explicit governed-subject contract, compare and evidence work cannot generalize safely.

**Independent Test**: Create a new baseline profile through the existing baseline form and confirm the resulting stored scope is canonical V2 with explicit domain and subject-class semantics.

**Acceptance Scenarios**:

1. **Given** a new baseline profile is being created, **When** the operator selects supported Intune subject families, **Then** the system stores the baseline scope as versioned V2 entries rather than raw legacy lists.
2. **Given** the baseline detail page renders after save, **When** the operator reviews the summary, **Then** the scope is explained through explicit domain and subject-class language rather than an unnamed split between policy types and foundation types.

---

### User Story 3 - Reject unsupported combinations before work starts (Priority: P2)

As an operator starting baseline capture or compare, I want unsupported or invalid subject selections to fail early so I do not launch a run with ambiguous or impossible scope.

**Why this priority**: The value of a taxonomy contract is not just naming. It must prevent invalid or misleading operation starts.

**Independent Test**: Attempt to save or execute baseline scope selections that contain an unknown domain, invalid class, inactive type, or unsupported capture or compare combination and verify the operation is blocked clearly before any run starts.

**Acceptance Scenarios**:

1. **Given** a scope entry includes an unknown or inactive subject type, **When** the operator saves the baseline profile, **Then** validation fails with a deterministic error explaining the invalid selection.
2. **Given** a scope contains a subject type that can be listed but not compared, **When** the operator starts compare, **Then** the action is blocked before the run is created and the operator sees a clear reason.

---

### User Story 4 - Roll out progressively without forced migration churn (Priority: P3)

As a maintainer, I want legacy scope storage to remain readable during rollout and optionally backfillable later so the product can adopt the new contract without an all-at-once migration event.

**Why this priority**: The chosen rollout strategy deliberately trades immediate cleanup for lower production risk.

**Independent Test**: Keep a mixed dataset of legacy and V2 baseline profiles, verify both remain usable, then run the optional cleanup path and confirm legacy rows can be rewritten without changing meaning.

**Acceptance Scenarios**:

1. **Given** some baseline profiles still store legacy scope, **When** those profiles are read, **Then** they are normalized transparently and remain fully usable.
2. **Given** the optional cleanup path is executed after rollout confidence exists, **When** remaining legacy rows are backfilled, **Then** their effective governed subject set is preserved exactly.
3. **Given** the optional cleanup path is invoked without explicit write confirmation, **When** the maintainer runs it in preview mode, **Then** the command reports candidate rewrites without mutating persisted scope rows or silently bypassing audit expectations for committed writes.

### Edge Cases

- A stored scope mixes legacy fields and V2 fields in the same payload.
- A legacy payload omits one legacy key or omits both legacy keys entirely.
- Two V2 entries collapse to the same domain, subject class, and subject type set after normalization.
- A legacy profile contains a subject type that no longer exists or is no longer active.
- A subject type is valid for capture but not valid for compare, or vice versa.
- `filters` are present in V2 but contain values the current domain does not yet support.
- A future domain is registered but inactive and should remain hidden from operator selection while historic data stays inspectable.
- Duplicate subject type keys appear within the same entry or across repeated entries.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature does not introduce a new Microsoft Graph path, a new baseline run type, or a new write workflow beyond the existing baseline profile save and baseline capture or compare starts. It does change the subject-selection contract consumed by baseline capture and compare, so the taxonomy registry, validation rules, tenant isolation, operation-start gating, and tests must be explicit.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** This feature intentionally introduces a new internal contract and a narrow taxonomy vocabulary because the current product already needs a stable way to describe governed subjects. A smaller wrapper around legacy arrays would preserve the semantic leak. No new table or universal plugin framework is justified, and no generic platform model replacement is part of this spec.

**Constitution alignment (OPS-UX):** Existing `baseline_capture` and `baseline_compare` runs remain the operational truth. This spec does not add a new `OperationRun` type, does not change service ownership of run state, and does not alter summary-count semantics. It does require the normalized scope used for those operations to be deterministically inspectable in logs, debug output, or test assertions so the operation input is auditable.

**Constitution alignment (RBAC-UX):** The feature spans workspace baseline surfaces under `/admin` and tenant compare surfaces under `/admin/t/{tenant}/...` but does not change authorization boundaries. Non-members remain `404`, entitled members lacking capability remain `403`, and any save or operation start continues to enforce server-side authorization. Validation failures for invalid scope selections are business-validation outcomes, not scope-leak exceptions.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable. No authentication handshake behavior changes.

**Constitution alignment (BADGE-001):** This feature does not introduce a new status or badge vocabulary. Existing centralized badge semantics remain unchanged.

**Constitution alignment (UI-FIL-001):** The touched baseline surfaces continue to use native Filament forms, sections, infolists, and existing resource actions. Raw V2 JSON remains hidden from operators. Scope summaries should be rendered through existing UI primitives and labels rather than a new local taxonomy widget system.

**Constitution alignment (UI-NAMING-001):** Operator-facing wording stays Intune-first where the currently supported subject families are truly Intune-owned, but platform-safe surfaces such as summaries, admin diagnostics, or validation messages must use domain-safe terms like governed subject, domain, and subject class where that language clarifies meaning.

**Constitution alignment (DECIDE-001):** The affected surfaces are secondary context surfaces, not primary decision queues. Their job is to make governed-scope truth visible before capture or compare starts. Domain and subject-class summaries must be default-visible, while deeper taxonomy detail stays on demand.

**Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001):** Baseline profile create and edit remain form-first resource surfaces, and baseline profile detail remains the workflow hub for existing capture and compare actions. The introduction of normalized scope semantics must not create competing header actions or move current workflow actions out of their established, capability-gated locations.

**Constitution alignment (ACTSURF-001 - action hierarchy):** This feature does not add a new action hierarchy. Existing capture and compare actions remain where they are, while the new scope summary lives in the page body or detail sections as contextual truth rather than peer action chrome.

**Constitution alignment (OPSURF-001):** Default-visible baseline content must stay operator-first. Scope summaries should explain governed-subject breadth and readiness without exposing raw arrays or adapter-only terminology. Detailed normalization lineage or future-domain notes remain secondary.

**Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001):** The feature introduces one canonical scope contract and one taxonomy registry but does not add a second presenter stack or semantic overlay. Direct mapping from canonical scope to summary is preferred, and tests must focus on validation, normalization, and operation behavior rather than thin wrappers alone.

**Constitution alignment (Filament Action Surfaces):** The Action Surface Contract remains satisfied. Each touched baseline surface keeps one primary inspect or open model, no redundant View action is introduced, no empty action groups are added, and no new destructive action is introduced. The UI Action Matrix below records the affected surfaces.

**Constitution alignment (UX-001 — Layout & Information Architecture):** Existing baseline create and edit layouts remain sectioned forms, and baseline detail remains a structured detail page. The scope upgrade must not regress search, sort, empty-state, or form-layout expectations on the current baseline resource.

### Functional Requirements

- **FR-202-001 Governance taxonomy registry**: The platform MUST maintain one authoritative internal registry for governed subject metadata that includes, at minimum, `domain_key`, `subject_class`, `subject_type_key`, `label`, `description`, `capture_supported`, `compare_supported`, `inventory_supported`, and `active`.
- **FR-202-002 Domain and class validation**: The taxonomy registry MUST define which subject classes are valid within each governance domain and which subject type keys belong to each valid domain and class combination.
- **FR-202-003 Intune mapping**: Current Intune baseline-selectable subject families MUST be represented in the taxonomy as explicit Intune-owned subject types under the Intune domain and the policy subject class.
- **FR-202-004 Foundation mapping**: Current baseline foundation selections MUST be represented as explicit taxonomy entries under a named platform domain and subject class rather than as an unnamed second category in scope.
- **FR-202-005 Canonical Baseline Scope V2 shape**: The canonical baseline scope contract for new or normalized profiles MUST be versioned and include one or more scope entries containing `domain_key`, `subject_class`, a non-empty `subject_type_keys` list, and optional `filters`.
- **FR-202-006 Legacy normalization**: The system MUST accept legacy baseline scope shaped as `policy_types` and `foundation_types` only at ingestion boundaries, normalize an omitted legacy bucket the same as its empty-list default when the other bucket is present, reject payloads where both legacy buckets are absent, and deterministically normalize valid legacy input into canonical V2.
- **FR-202-007 Mixed-input rejection**: The system MUST reject scope payloads that mix legacy fields and V2 fields or otherwise remain ambiguous after normalization.
- **FR-202-008 Save-forward persistence**: Any newly created baseline profile and any updated baseline profile MUST persist canonical V2 scope rather than writing legacy scope lists.
- **FR-202-009 Duplicate handling**: Duplicate entries and duplicate subject type keys MUST be merged or rejected consistently, and that behavior MUST be deterministic and testable.
- **FR-202-010 Unknown or inactive selection rejection**: Unknown domains, invalid subject classes, unknown subject type keys, inactive subject type keys, and cross-domain mismatches MUST fail validation with a clear operator-facing reason.
- **FR-202-011 Operation eligibility gating**: Baseline capture and baseline compare initiation MUST reject subject types that are not supported for the intended operation before a run is created.
- **FR-202-012 Capture path normalization**: Baseline capture entrypoints touched by this spec MUST consume normalized V2 scope through the shared contract rather than reading raw legacy arrays.
- **FR-202-013 Compare path normalization**: Baseline compare entrypoints touched by this spec MUST consume normalized V2 scope through the shared contract rather than reading raw legacy arrays.
- **FR-202-014 Auditable canonical scope**: The effective normalized scope used for capture or compare MUST be recoverable through deterministic logs, debug output, or test assertions without reconstructing ambiguous legacy arrays.
- **FR-202-015 Intune no-regression**: Existing Intune-only baseline profiles MUST continue to load, display, save, capture, and compare without manual intervention or behavior regression.
- **FR-202-016 UI honesty**: Operator-facing baseline surfaces MUST not expose raw V2 JSON and MUST not imply that inactive or unsupported future domains are ready for normal use.
- **FR-202-017 Platform boundary protection**: No new platform-core API introduced by this spec may require callers to already think in raw Intune-only `policy_type` semantics.
- **FR-202-018 Optional filters contract**: `filters` MAY be present in V2 entries, but they MUST remain optional and empty by default for current Intune behavior unless a domain explicitly supports them.
- **FR-202-019 Rollout strategy**: Rollout MUST use tolerant read plus save-forward behavior for `baseline_profiles.scope_jsonb` rather than forcing an eager rewrite of all existing baseline scope rows, and compare assignment overrides may remain tolerant-read only in this release.
- **FR-202-020 Optional cleanup path**: The platform MAY provide a one-time maintenance backfill path for `baseline_profiles.scope_jsonb` that previews candidate rewrites by default, requires explicit write confirmation before mutating rows, writes audit logs for committed rewrites, and rewrites remaining legacy profile scope rows to canonical V2 without changing their effective meaning.
- **FR-202-021 Future-domain plausibility**: The resulting V2 contract MUST be broad enough to describe at least one plausible non-Intune governance domain shape without forcing it into `policy_type` language.

## UI Action Matrix *(mandatory when Filament is changed)*

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Baseline profiles list | `apps/platform/app/Filament/Resources/BaselineProfileResource.php`, `apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ListBaselineProfiles.php` | Existing create action remains the primary list header action | Existing record-open flow remains the inspect path | Existing safe list actions only | Existing grouped bulk actions only | Existing create CTA remains | n/a | n/a | Existing create and update audit semantics remain unchanged | No hierarchy change required; this spec changes scope semantics, not list action placement |
| Baseline profile create and edit | `apps/platform/app/Filament/Resources/BaselineProfileResource.php`, `apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/CreateBaselineProfile.php`, `apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/EditBaselineProfile.php` | No new header action; save and cancel remain form-local | Form page itself | none | none | n/a | n/a | Save and Cancel remain the only primary form controls | Existing baseline profile create and update audit entries remain | Scope selector and normalized summary live inside form sections; raw V2 JSON stays hidden |
| Baseline profile view | `apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php` | Existing view-page actions remain, with scope summary added as contextual detail instead of action chrome | Explicit view page remains the inspect flow; related compare matrix navigation stays contextual but is not materially changed by this spec | none beyond existing safe shortcuts | none | n/a | Existing capture and compare actions remain state-sensitive and capability-gated | n/a | Existing capture and compare run and audit semantics remain | Action Surface Contract stays satisfied; no new destructive action and no exemption needed |

### Key Entities *(include if feature involves data)*

- **Governance Taxonomy Entry**: The authoritative description of one selectable governed subject type, including its domain, subject class, operator label, descriptive metadata, and support flags for capture, compare, and inventory.
- **Baseline Scope V2**: The canonical versioned baseline scope structure that describes one or more governed-scope entries for a baseline profile.
- **Scope Entry**: One Baseline Scope V2 selector containing a domain, a subject class, a non-empty set of subject type keys, and optional filters for future domain-specific narrowing.
- **Baseline Profile Scope Summary**: The operator-visible explanation of what a baseline profile governs after legacy normalization and canonical V2 validation have been applied.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: In automated regression coverage, 100% of legacy Intune-only baseline profiles used by the tests load, save, capture, and compare without manual data repair.
- **SC-002**: In automated persistence coverage, 100% of newly created or updated baseline profiles store canonical V2 scope and do not write legacy `policy_types` or `foundation_types` lists.
- **SC-003**: Invalid domain, subject-class, subject-type, inactive-type, and operation-support mismatches are rejected before baseline capture or compare starts in every scenario covered by the spec tests.
- **SC-004**: The default-visible baseline scope summary on the touched baseline surfaces explains governed-subject breadth through domain and subject-class language without exposing raw JSON.
- **SC-005**: Product review can model at least one plausible non-Intune governance domain with the same V2 vocabulary without introducing synthetic `policy_type` terminology or changing current Intune-owned models.

## Rollout Strategy

### Phase 1 - Introduce taxonomy and normalization

- Add the governance taxonomy registry.
- Add the Baseline Scope V2 contract and deterministic legacy normalization.
- Keep current Intune baseline flows operational.

### Phase 2 - Save forward

- New baseline profiles always write canonical V2 scope.
- Any saved existing baseline profile writes canonical V2 scope.

### Phase 3 - Optional cleanup

- Provide an optional maintenance path to preview and then backfill remaining legacy baseline profile scope rows with explicit write confirmation and audit logging.
- Keep compare assignment overrides on tolerant-read normalization only in this release.
- Run cleanup only after rollout confidence is established.

## Non-Goals

- Implementing a second governance domain
- Replacing the current compare engine architecture
- Renaming all existing `policy_type` usage across the repo
- Redesigning the baseline UI as a multi-domain experience
- Refactoring `Policy`, `PolicyVersion`, `BackupItem`, or current Intune adapter models into generic platform models
- Introducing a generic plugin or discovery framework for future governance domains

## Assumptions

- Intune remains the only operator-facing governance domain during the initial rollout of this spec.
- Existing baseline capture and compare actions, audit entries, and run-observability flows are already correct and will be preserved.
- The current baseline scope storage can carry canonical V2 JSON without requiring a new table or a broad schema redesign.
- Future-domain rollout can remain hidden until the taxonomy marks those subject types active and supported.

## Dependencies

- Existing baseline profile resource and baseline profile detail workflow
- Existing baseline capture and baseline compare services and jobs
- Existing tenant compare landing and compare matrix surfaces
- Existing baseline-related audit and operation-run flows

## Risks

- The taxonomy could grow into a speculative universal framework if more fields or behaviors are added before a second real domain exists.
- Hidden Intune assumptions could survive behind V2 if downstream capture or compare code still bypasses normalized scope.
- Operator-facing summaries could overclaim future-domain readiness if inactive taxonomy entries are shown too early.
- Cleanup pressure could trigger premature renaming of Intune-owned adapter concepts before the platform vocabulary stabilizes.

## Review Questions

- Does the resulting scope contract clearly distinguish platform vocabulary from Intune-owned vocabulary?
- Can a reviewer explain what a baseline governs without relying on `policy_types` and `foundation_types` lore?
- Do invalid or unsupported selections fail before a run starts rather than surfacing as downstream surprises?
- Does the rollout preserve current Intune baseline behavior without forcing an all-at-once migration?
- Is the taxonomy deliberately minimal, or has it already started to drift into a plugin system or generic framework?

## Definition of Done

This feature is complete when:

- the codebase has one authoritative governance subject taxonomy contract,
- Baseline Scope V2 is the canonical contract for new and updated baseline profiles,
- legacy scope storage is accepted only at ingestion boundaries and normalized deterministically,
- touched baseline capture and compare entrypoints consume normalized scope,
- existing Intune baseline workflows continue to work without manual intervention,
- baseline surfaces summarize governed scope without raw JSON or implicit Intune-only vocabulary,
- tests prove validation, save-forward behavior, optional cleanup safety, and no-regression Intune behavior,
- and platform-core scope APIs no longer require callers to think in raw Intune-only `policy_type` terms.
