spec/024-additional-intune-types (#28)

specs for additional intune types

Co-authored-by: Ahmed Darrazi <ahmeddarrazi@adsmac.local>
Reviewed-on: #28

specs/024-terms-and-conditions/checklists/requirements.md

@@ -0,0 +1,15 @@
+# Requirements Checklist (024)
+
+**Created**: 2026-01-04  
+**Feature**: [spec.md](../spec.md)
+
+- [ ] `termsAndConditions` exists in `config/tenantpilot.php` with correct category/risk/restore mode.
+- [ ] Graph contract exists in `config/graph_contracts.php` (resource, type family, assignments CRUD paths).
+- [ ] Sync lists and stores T&C in inventory.
+- [ ] Snapshot capture stores full payload + assignments.
+- [ ] Restore preview shows correct mode and warnings.
+- [ ] Restore execution applies only patchable properties and writes audit logs.
+- [ ] Normalized settings view is readable for admins.
+- [ ] Pest tests cover sync + snapshot + restore preview + execution.
+- [ ] Pint run (`./vendor/bin/pint --dirty`) on touched files.
+

specs/024-terms-and-conditions/plan.md

@@ -0,0 +1,23 @@
+# Plan: Terms & Conditions (Enrollment Experience) (024)
+
+**Branch**: `feat/024-terms-and-conditions`  
+**Date**: 2026-01-04  
+**Input**: [spec.md](./spec.md)
+
+## Approach
+1. Confirm Graph contract details for Terms & Conditions:
+   - resource path: `deviceManagement/termsAndConditions`
+   - `@odata.type` values and patchable fields
+   - assignments endpoints: `/deviceManagement/termsAndConditions/{id}/assignments` (CRUD)
+2. Add `termsAndConditions` to `config/tenantpilot.php` (category “Enrollment Experience”, risk, restore mode).
+3. Add contract entry to `config/graph_contracts.php`:
+   - resource, type family, create/update methods
+   - assignments list/create/update/delete paths (no `/assign` action here)
+4. Ensure policy sync, snapshot capture, and restore use the config/contract-driven paths (minimal special casing).
+5. Add a normalizer for readable UI output and ensure diff output is stable.
+6. Add targeted Pest coverage (sync + snapshot + preview + execution).
+
+## Decisions / Notes
+- **Restore mode**: default `enabled` (risk: medium-high) with strict preview/confirmation and audit logging.
+- **Assignments**: use assignment CRUD paths (POST to `/assignments`) rather than `/assign`.
+

specs/024-terms-and-conditions/spec.md

@@ -0,0 +1,51 @@
+# Feature Specification: Terms & Conditions (Enrollment Experience) (024)
+
+**Feature Branch**: `feat/024-terms-and-conditions`  
+**Created**: 2026-01-04  
+**Status**: Draft  
+**Priority**: P1
+
+## Context
+Terms & Conditions (T&C) are part of the **Enrollment Experience**. During tenant rebuilds / recovery they are frequently missed, but can be required for compliant onboarding.
+
+## User Scenarios & Testing
+
+### User Story 1 — Inventory + readable view (Priority: P1)
+As an admin, I can see Terms & Conditions policies in the Policies inventory and view their configuration in a readable way.
+
+**Acceptance Scenarios**
+1. Given a tenant with T&C configured, when I sync policies, then T&C items appear with type `termsAndConditions`.
+2. Given a T&C policy, when I open its detail page, then I see a normalized settings view (not only raw JSON).
+
+### User Story 2 — Snapshot capture + versioning (Priority: P1)
+As an admin, I can capture versions and backups of Terms & Conditions so I can diff and roll back safely.
+
+**Acceptance Scenarios**
+1. Given a T&C policy, when I capture a snapshot, then the full Graph payload is stored immutably (JSONB).
+2. Given two versions, when I view a diff, then changes are human-readable and structured.
+
+### User Story 3 — Restore preview + execution (Priority: P2)
+As an admin, I can restore Terms & Conditions (with assignments) from a snapshot with a safe preview, audit logging, and defensive checks.
+
+**Acceptance Scenarios**
+1. Given a backup item of type `termsAndConditions`, when I run restore preview, then it shows create/update + restore mode and warnings.
+2. Given restore execution, when Graph rejects non-patchable fields, then TenantPilot strips them (contract-driven) and retries safely.
+
+## Requirements
+
+### Functional Requirements
+- **FR-001**: Add policy type `termsAndConditions` backed by Graph `deviceManagement/termsAndConditions`.
+- **FR-002**: Capture full payload snapshots and include assignments.
+- **FR-003**: Restore supports create/update (contract-driven sanitization) and assignment apply.
+- **FR-004**: Normalized settings view exists for key fields (displayName, description, title, body, acceptance statement, etc.).
+- **FR-005**: Add Pest tests for sync + snapshot + restore preview + restore execution.
+
+### Non-Functional Requirements
+- **NFR-001**: All writes require explicit confirmation and create audit logs.
+- **NFR-002**: Tenant isolation applies end-to-end (no cross-tenant leakage).
+
+## Success Criteria
+- **SC-001**: T&C appears in inventory and backups.
+- **SC-002**: Restore preview is actionable and safe.
+- **SC-003**: Restore execution works with assignments (where Graph allows).
+

specs/024-terms-and-conditions/tasks.md

@@ -0,0 +1,33 @@
+# Tasks: Terms & Conditions (Enrollment Experience) (024)
+
+**Branch**: `feat/024-terms-and-conditions`  
+**Date**: 2026-01-04  
+**Input**: [spec.md](./spec.md), [plan.md](./plan.md)
+
+## Phase 1: Setup
+- [x] T001 Create spec/plan/tasks and checklist.
+
+## Phase 2: Research & Design
+- [ ] T002 Confirm Graph resource, `@odata.type`, patchable vs read-only fields.
+- [ ] T003 Confirm assignments endpoints and payload shapes for create/update/delete.
+- [ ] T004 Decide restore mode (`enabled` vs `preview-only`) and risk classification.
+
+## Phase 3: Tests (TDD)
+- [ ] T005 Add sync test for `termsAndConditions`.
+- [ ] T006 Add snapshot capture test (payload + assignments).
+- [ ] T007 Add restore preview test (restore_mode + action).
+- [ ] T008 Add restore execution test (sanitization + assignment apply).
+- [ ] T009 Add normalized display test for key fields.
+
+## Phase 4: Implementation
+- [ ] T010 Add `termsAndConditions` to `config/tenantpilot.php`.
+- [ ] T011 Add Graph contract entry in `config/graph_contracts.php` (resource + assignment CRUD paths).
+- [ ] T012 Ensure `PolicySyncService` imports these policies correctly.
+- [ ] T013 Ensure `PolicySnapshotService` captures full payload and assignments.
+- [ ] T014 Ensure `RestoreService` applies create/update and assignments (contract-driven).
+- [ ] T015 Add `TermsAndConditionsNormalizer` and register it.
+
+## Phase 5: Verification
+- [ ] T016 Run targeted tests.
+- [ ] T017 Run Pint (`./vendor/bin/pint --dirty`).
+

specs/025-policy-sets/checklists/requirements.md

@@ -0,0 +1,13 @@
+# Requirements Checklist (025)
+
+**Created**: 2026-01-04  
+**Feature**: [spec.md](../spec.md)
+
+- [ ] `policySet` exists in `config/tenantpilot.php` (category, endpoint, restore mode, risk).
+- [ ] Graph contract exists in `config/graph_contracts.php` (resource, items hydration, assignments paths).
+- [ ] Sync lists and stores Policy Sets in inventory.
+- [ ] Snapshot capture includes Policy Set items and assignments.
+- [ ] Restore preview produces a linking report and blocks unsafe execution.
+- [ ] Normalized settings view is readable (items + assignments).
+- [ ] Pest tests cover sync + snapshot + preview.
+

specs/025-policy-sets/plan.md

@@ -0,0 +1,27 @@
+# Plan: Policy Sets (Intune native bundling) (025)
+
+**Branch**: `feat/025-policy-sets`  
+**Date**: 2026-01-04  
+**Input**: [spec.md](./spec.md)
+
+## Approach
+1. Confirm Graph API surface:
+   - resource: `deviceAppManagement/policySets`
+   - item model + subresource path (`/policySets/{id}/items`)
+   - assignments subresource (`/policySets/{id}/assignments`)
+2. Add `policySet` to `config/tenantpilot.php` (category “Apps/MAM”, risk, restore mode).
+3. Add contract entry in `config/graph_contracts.php`:
+   - resource + type family
+   - member hydration strategy for items (subresource)
+   - assignments CRUD paths (if supported)
+4. Extend snapshot capture to hydrate `items` (and assignments).
+5. Implement restore preview “linking report”:
+   - identify referenced object IDs inside items
+   - attempt mapping by (type, displayName, externalId) where possible
+   - surface missing dependencies and block execution by default
+6. Add targeted Pest tests for sync + snapshot hydration + preview report.
+
+## Decisions / Notes
+- **Restore mode**: default `preview-only` until a robust cross-tenant linking/mapping strategy exists.
+- Policy Sets are not “settings restore”; they are primarily a **relationship/linking** restore step.
+

specs/025-policy-sets/spec.md

@@ -0,0 +1,51 @@
+# Feature Specification: Policy Sets (Intune native bundling) (025)
+
+**Feature Branch**: `feat/025-policy-sets`  
+**Created**: 2026-01-04  
+**Status**: Draft  
+**Priority**: P1
+
+## Context
+Policy Sets are an Intune-native way to bundle multiple policies/apps into a deployable set. For tenants that rely on Policy Sets, “Tenant-as-Code” is incomplete without at least inventory + backup and a restore preview that highlights missing links.
+
+## User Scenarios & Testing
+
+### User Story 1 — Inventory + view Policy Sets (Priority: P1)
+As an admin, I can see Policy Sets and inspect their composition (items) and assignments.
+
+**Acceptance Scenarios**
+1. Given a tenant uses Policy Sets, when I sync policies, then Policy Sets appear as type `policySet`.
+2. Given a Policy Set, when I view details, then I see a readable list of included items and assignments.
+
+### User Story 2 — Backup + version history (Priority: P1)
+As an admin, I can capture immutable snapshots of Policy Sets (including items) and diff versions.
+
+**Acceptance Scenarios**
+1. Given a Policy Set, when I add it to a backup set, then the snapshot includes items and assignments (as supported by Graph).
+2. Given two versions, diffs highlight changed items and assignment targets.
+
+### User Story 3 — Restore preview (linking) (Priority: P1)
+As an admin, I can run a restore preview that explains which Policy Set items can be linked in the target tenant and which are missing.
+
+**Acceptance Scenarios**
+1. Given a Policy Set snapshot referencing policies/apps by ID, when I run preview, then TenantPilot reports missing vs resolvable items.
+2. Given missing referenced objects, preview warns and blocks execution unless resolved.
+
+## Requirements
+
+### Functional Requirements
+- **FR-001**: Add policy type `policySet` backed by Graph `deviceAppManagement/policySets`.
+- **FR-002**: Capture Policy Set payload + `items` subresource (and assignments if applicable).
+- **FR-003**: Restore preview MUST validate referenced IDs and provide a linking report.
+- **FR-004**: Restore execution is allowed only when all referenced items can be mapped safely (or stays preview-only initially).
+- **FR-005**: Add Pest tests for sync + snapshot + preview linking report.
+
+### Non-Functional Requirements
+- **NFR-001**: No destructive writes without explicit confirmation and audit logs.
+- **NFR-002**: Linking errors must be actionable (show which item is missing and why).
+
+## Success Criteria
+- **SC-001**: Policy Sets are visible and backed up.
+- **SC-002**: Preview makes missing dependencies obvious.
+- **SC-003**: If enabled, execution links only safe, mapped items.
+

specs/025-policy-sets/tasks.md

@@ -0,0 +1,31 @@
+# Tasks: Policy Sets (Intune native bundling) (025)
+
+**Branch**: `feat/025-policy-sets`  
+**Date**: 2026-01-04  
+**Input**: [spec.md](./spec.md), [plan.md](./plan.md)
+
+## Phase 1: Setup
+- [x] T001 Create spec/plan/tasks and checklist.
+
+## Phase 2: Research & Design
+- [ ] T002 Confirm Graph resource + `@odata.type` for Policy Sets.
+- [ ] T003 Confirm item subresource shape (`/items`) and how referenced objects are represented.
+- [ ] T004 Confirm assignment endpoints (`/assignments`) and payload shape.
+- [ ] T005 Define restore preview “linking report” rules and execution gating.
+
+## Phase 3: Tests (TDD)
+- [ ] T006 Add sync test importing Policy Sets.
+- [ ] T007 Add snapshot test capturing items (and assignments).
+- [ ] T008 Add restore preview test showing linking report (missing vs resolvable).
+
+## Phase 4: Implementation
+- [ ] T009 Add `policySet` to `config/tenantpilot.php`.
+- [ ] T010 Add contract entry in `config/graph_contracts.php` (resource + item hydration + assignments).
+- [ ] T011 Implement snapshot hydration for `items` and assignment capture.
+- [ ] T012 Implement restore preview linking report and safe gating.
+- [ ] T013 Add a normalizer for readable UI output (items summary + assignment summary).
+
+## Phase 5: Verification
+- [ ] T014 Run targeted tests.
+- [ ] T015 Run Pint (`./vendor/bin/pint --dirty`).
+

specs/026-custom-compliance-scripts/checklists/requirements.md

@@ -0,0 +1,14 @@
+# Requirements Checklist (026)
+
+**Created**: 2026-01-04  
+**Feature**: [spec.md](../spec.md)
+
+- [ ] `deviceComplianceScript` exists in `config/tenantpilot.php` (category, endpoint, restore mode, risk).
+- [ ] Graph contract exists in `config/graph_contracts.php` (resource, type family, assignments paths).
+- [ ] Sync lists and stores compliance scripts in inventory.
+- [ ] Snapshot capture stores full payload + assignments.
+- [ ] Restore preview is available and respects restore mode.
+- [ ] Restore execution applies only patchable fields and re-encodes script content correctly.
+- [ ] Normalized settings view is readable and safe.
+- [ ] Pest tests cover sync + snapshot + preview + execution.
+

specs/026-custom-compliance-scripts/plan.md

@@ -0,0 +1,25 @@
+# Plan: Custom Compliance Scripts (Windows) (026)
+
+**Branch**: `feat/026-custom-compliance-scripts`  
+**Date**: 2026-01-04  
+**Input**: [spec.md](./spec.md)
+
+## Approach
+1. Confirm Graph contract details:
+   - resource: `deviceManagement/deviceComplianceScripts` (beta)
+   - patchable fields vs read-only fields
+   - assignment pattern: `/deviceComplianceScripts/{id}/assign` and `/assignments`
+2. Add `deviceComplianceScript` to `config/tenantpilot.php` (category “Compliance”, risk, restore mode).
+3. Add contract entry to `config/graph_contracts.php` (resource + assignment endpoints + scope tags support).
+4. Implement snapshot capture:
+   - ensure `detectionScriptContent` is preserved and treated like other scripts (safe display, encode/decode where needed)
+5. Implement restore:
+   - sanitize payload via contract
+   - ensure `detectionScriptContent` is encoded as expected by Graph
+   - apply assignments via assign action
+6. Add normalizer and targeted tests.
+
+## Decisions / Notes
+- **Restore mode**: default `enabled` (risk: medium-high) because tenant recovery often depends on these scripts.
+- Use the existing script content display rules (`TENANTPILOT_SHOW_SCRIPT_CONTENT`, max chars).
+

specs/026-custom-compliance-scripts/spec.md

@@ -0,0 +1,52 @@
+# Feature Specification: Custom Compliance Scripts (Windows) (026)
+
+**Feature Branch**: `feat/026-custom-compliance-scripts`  
+**Created**: 2026-01-04  
+**Status**: Draft  
+**Priority**: P1
+
+## Context
+Windows Custom Compliance is widely used. Without `deviceComplianceScripts`, backup/restore for compliance posture is incomplete. Restore must include assignments.
+
+## User Scenarios & Testing
+
+### User Story 1 — Inventory + view compliance scripts (Priority: P1)
+As an admin, I can see Custom Compliance Scripts in inventory and view their script/config in a readable way.
+
+**Acceptance Scenarios**
+1. Given device compliance scripts exist, sync shows them as type `deviceComplianceScript`.
+2. Detail view shows key settings (runAsAccount, enforceSignatureCheck, runAs32Bit) and script content (safe display rules).
+
+### User Story 2 — Backup + versioning (Priority: P1)
+As an admin, I can capture versions/backups of compliance scripts so I can diff changes.
+
+**Acceptance Scenarios**
+1. Snapshot capture stores the full payload including `detectionScriptContent`.
+2. Diff highlights script changes and operational flags.
+
+### User Story 3 — Restore preview + execution (Priority: P1)
+As an admin, I can restore a compliance script and its assignments defensively.
+
+**Acceptance Scenarios**
+1. Preview shows create/update + restore mode and warnings.
+2. Execution strips read-only fields and re-encodes script content correctly.
+3. Assignments are applied via Graph assign action.
+
+## Requirements
+
+### Functional Requirements
+- **FR-001**: Add policy type `deviceComplianceScript` backed by Graph `deviceManagement/deviceComplianceScripts` (beta).
+- **FR-002**: Snapshot stores full payload (including `detectionScriptContent`) and assignments.
+- **FR-003**: Restore supports create/update with contract-driven sanitization.
+- **FR-004**: Restore applies assignments (`/assign`) and records audit logs.
+- **FR-005**: Add normalized display support for key fields and script content (with safety limits).
+- **FR-006**: Add Pest tests for sync + snapshot + preview + execution.
+
+### Non-Functional Requirements
+- **NFR-001**: Script content must never be logged; UI display must be bounded (config-driven).
+- **NFR-002**: Preview-only fallback when Graph returns unexpected shapes or missing contracts.
+
+## Success Criteria
+- **SC-001**: Custom compliance scripts appear in inventory and backups.
+- **SC-002**: Restore execution works and assignments are applied.
+

specs/026-custom-compliance-scripts/tasks.md

@@ -0,0 +1,33 @@
+# Tasks: Custom Compliance Scripts (Windows) (026)
+
+**Branch**: `feat/026-custom-compliance-scripts`  
+**Date**: 2026-01-04  
+**Input**: [spec.md](./spec.md), [plan.md](./plan.md)
+
+## Phase 1: Setup
+- [x] T001 Create spec/plan/tasks and checklist.
+
+## Phase 2: Research & Design
+- [ ] T002 Confirm Graph resource + `@odata.type` and required permissions.
+- [ ] T003 Confirm patchable fields and define `update_strip_keys` / `update_whitelist`.
+- [ ] T004 Confirm assignments endpoints (`/assignments`, `/assign`) and body shape.
+- [ ] T005 Decide restore mode + risk classification.
+
+## Phase 3: Tests (TDD)
+- [ ] T006 Add sync test for `deviceComplianceScript`.
+- [ ] T007 Add snapshot/version capture test (incl. `detectionScriptContent`).
+- [ ] T008 Add restore preview test (restore_mode + action).
+- [ ] T009 Add restore execution test (sanitization + assignment apply).
+- [ ] T010 Add normalized display test for key fields.
+
+## Phase 4: Implementation
+- [ ] T011 Add `deviceComplianceScript` to `config/tenantpilot.php`.
+- [ ] T012 Add Graph contract entry in `config/graph_contracts.php`.
+- [ ] T013 Implement snapshot capture handling (script content preservation rules).
+- [ ] T014 Implement restore apply support (contract-driven sanitization + assignments).
+- [ ] T015 Add `DeviceComplianceScriptNormalizer` and register it.
+
+## Phase 5: Verification
+- [ ] T016 Run targeted tests.
+- [ ] T017 Run Pint (`./vendor/bin/pint --dirty`).
+

specs/027-enrollment-config-subtypes/checklists/requirements.md

@@ -0,0 +1,13 @@
+# Requirements Checklist (027)
+
+**Created**: 2026-01-04  
+**Feature**: [spec.md](../spec.md)
+
+- [ ] New enrollment config subtypes exist in `config/tenantpilot.php`.
+- [ ] Graph contracts exist with correct type families.
+- [ ] Sync classifies each subtype correctly (no collapsing into `enrollmentRestriction`).
+- [ ] Snapshot capture stores full payloads.
+- [ ] Restore preview works and defaults to preview-only.
+- [ ] Normalized view is readable for admins.
+- [ ] Pest tests cover sync + snapshot + preview.
+

specs/027-enrollment-config-subtypes/plan.md

@@ -0,0 +1,21 @@
+# Plan: Enrollment Configuration Subtypes (027)
+
+**Branch**: `feat/027-enrollment-config-subtypes`  
+**Date**: 2026-01-04  
+**Input**: [spec.md](./spec.md)
+
+## Approach
+1. Confirm Graph details and type-family values for each subtype (`@odata.type`).
+2. Add new types to `config/tenantpilot.php` (category “Enrollment Experience”, risk, restore mode).
+3. Add contracts to `config/graph_contracts.php`:
+   - resource `deviceManagement/deviceEnrollmentConfigurations`
+   - type families per subtype
+   - assignments endpoints (if supported) or mark as unsupported
+4. Update `PolicySyncService` enrollment classification logic to route each item to the correct subtype.
+5. Ensure snapshot capture can fetch these items without special casing.
+6. Implement restore preview entries; keep execution preview-only until validated.
+7. Add targeted Pest tests.
+
+## Decisions / Notes
+- All enrollment configuration subtypes should default to `preview-only` restore initially due to enrollment impact risk.
+

specs/027-enrollment-config-subtypes/spec.md

@@ -0,0 +1,46 @@
+# Feature Specification: Enrollment Configuration Subtypes (027)
+
+**Feature Branch**: `feat/027-enrollment-config-subtypes`  
+**Created**: 2026-01-04  
+**Status**: Draft  
+**Priority**: P1
+
+## Context
+TenantPilot already covers ESP and Enrollment Restrictions, but there are additional subtypes in the same `deviceEnrollmentConfigurations` collection that are often forgotten:
+- Enrollment Limit (`deviceEnrollmentLimitConfiguration`)
+- Platform Restrictions (`deviceEnrollmentPlatformRestrictionsConfiguration`)
+- Enrollment Notifications (`deviceEnrollmentNotificationConfiguration`, beta)
+
+## User Scenarios & Testing
+
+### User Story 1 — Inventory shows each subtype separately (Priority: P1)
+As an admin, I can sync enrollment configurations and see each subtype as its own policy type.
+
+**Acceptance Scenarios**
+1. Given enrollment limit configurations exist, sync shows type `deviceEnrollmentLimitConfiguration`.
+2. Given platform restriction configurations exist, sync shows type `deviceEnrollmentPlatformRestrictionsConfiguration`.
+3. Given enrollment notifications exist, sync shows type `deviceEnrollmentNotificationConfiguration`.
+
+### User Story 2 — Backup + restore preview (Priority: P1)
+As an admin, I can back up and preview-restore these enrollment configurations safely.
+
+**Acceptance Scenarios**
+1. Backup captures full payloads for each subtype.
+2. Restore preview lists create/update actions and shows preview-only warnings for enrollment-risky configs.
+
+## Requirements
+
+### Functional Requirements
+- **FR-001**: Add three new policy types backed by `deviceManagement/deviceEnrollmentConfigurations`:
+  - `deviceEnrollmentLimitConfiguration`
+  - `deviceEnrollmentPlatformRestrictionsConfiguration`
+  - `deviceEnrollmentNotificationConfiguration`
+- **FR-002**: Update classification so these do not collapse into `enrollmentRestriction`.
+- **FR-003**: Snapshot capture stores full payload and assignments (where supported).
+- **FR-004**: Restore preview is supported; execution is conservative (likely preview-only initially).
+- **FR-005**: Add Pest tests for sync + snapshot + preview.
+
+## Success Criteria
+- **SC-001**: Enrollment configuration subtypes are visible and correctly classified.
+- **SC-002**: Backups include these objects, and preview explains safe restore behavior.
+

specs/027-enrollment-config-subtypes/tasks.md

@@ -0,0 +1,28 @@
+# Tasks: Enrollment Configuration Subtypes (027)
+
+**Branch**: `feat/027-enrollment-config-subtypes`  
+**Date**: 2026-01-04  
+**Input**: [spec.md](./spec.md), [plan.md](./plan.md)
+
+## Phase 1: Setup
+- [x] T001 Create spec/plan/tasks and checklist.
+
+## Phase 2: Research & Design
+- [ ] T002 Confirm `@odata.type` for each subtype and whether Graph supports assignments.
+- [ ] T003 Decide restore modes and risk levels.
+
+## Phase 3: Tests (TDD)
+- [ ] T004 Add sync tests ensuring each subtype is classified correctly.
+- [ ] T005 Add snapshot capture test for at least one subtype.
+- [ ] T006 Add restore preview test ensuring preview-only behavior.
+
+## Phase 4: Implementation
+- [ ] T007 Add new types to `config/tenantpilot.php`.
+- [ ] T008 Add contracts in `config/graph_contracts.php` (resource + type families).
+- [ ] T009 Update `PolicySyncService` enrollment classification logic.
+- [ ] T010 Add normalizer for readable UI output (key fields per subtype).
+
+## Phase 5: Verification
+- [ ] T011 Run targeted tests.
+- [ ] T012 Run Pint (`./vendor/bin/pint --dirty`).
+

specs/028-device-categories/checklists/requirements.md

@@ -0,0 +1,11 @@
+# Requirements Checklist (028)
+
+**Created**: 2026-01-04  
+**Feature**: [spec.md](../spec.md)
+
+- [ ] `deviceCategory` exists in `config/tenantpilot.php` under `foundation_types`.
+- [ ] Graph contract exists in `config/graph_contracts.php` for device categories.
+- [ ] Backup sets include device categories as foundation items.
+- [ ] Restore recreates missing categories idempotently and writes audit logs.
+- [ ] Pest tests cover foundation snapshot + restore.
+

specs/028-device-categories/plan.md

@@ -0,0 +1,21 @@
+# Plan: Device Categories (Enrollment/Organization) (028)
+
+**Branch**: `feat/028-device-categories`  
+**Date**: 2026-01-04  
+**Input**: [spec.md](./spec.md)
+
+## Approach
+1. Confirm Graph endpoints and patchable fields:
+   - list: `GET /deviceManagement/deviceCategories`
+   - create/update/delete supported
+2. Add `deviceCategory` to `config/tenantpilot.php` under `foundation_types` (risk low, restore enabled).
+3. Add contract entry in `config/graph_contracts.php` for foundations (resource + create/update methods).
+4. Extend `FoundationSnapshotService` to fetch categories (list + per-item payload).
+5. Extend `FoundationMappingService` and restore flow:
+   - match by `displayName`
+   - create missing
+6. Add targeted Pest tests for foundation capture + restore.
+
+## Decisions / Notes
+- This is modeled as a **foundation type** (captured automatically with backup sets), not a Policy inventory type.
+

specs/028-device-categories/spec.md

@@ -0,0 +1,30 @@
+# Feature Specification: Device Categories (Enrollment/Organization) (028)
+
+**Feature Branch**: `feat/028-device-categories`  
+**Created**: 2026-01-04  
+**Status**: Draft  
+**Priority**: P2
+
+## Context
+Device Categories are not a “policy”, but they are frequently needed for tenant rebuilds and enrollment flows.
+
+## User Scenarios & Testing
+
+### User Story 1 — Backup + restore Device Categories (Priority: P1)
+As an admin, when I create a backup set, Device Categories are captured as a foundation object and can be restored safely.
+
+**Acceptance Scenarios**
+1. Given device categories exist, when I create a backup, then categories are included as foundation items.
+2. Given a target tenant is missing categories, when I restore, then categories are recreated (idempotent by display name).
+
+## Requirements
+
+### Functional Requirements
+- **FR-001**: Add foundation type `deviceCategory` backed by `deviceManagement/deviceCategories`.
+- **FR-002**: Backup captures all categories with minimal metadata.
+- **FR-003**: Restore recreates categories idempotently (match by displayName) and records audit logs.
+- **FR-004**: Add targeted tests for foundation snapshot + restore.
+
+## Success Criteria
+- **SC-001**: Device Categories are present in backups and can be recreated.
+

specs/028-device-categories/tasks.md

@@ -0,0 +1,27 @@
+# Tasks: Device Categories (Enrollment/Organization) (028)
+
+**Branch**: `feat/028-device-categories`  
+**Date**: 2026-01-04  
+**Input**: [spec.md](./spec.md), [plan.md](./plan.md)
+
+## Phase 1: Setup
+- [x] T001 Create spec/plan/tasks and checklist.
+
+## Phase 2: Research & Design
+- [ ] T002 Confirm Graph resource + patchability for `deviceCategories`.
+- [ ] T003 Decide mapping rules (by displayName) and restore idempotency behavior.
+
+## Phase 3: Tests (TDD)
+- [ ] T004 Add foundation snapshot test for `deviceCategory`.
+- [ ] T005 Add foundation restore test (create missing + idempotent behavior).
+
+## Phase 4: Implementation
+- [ ] T006 Add `deviceCategory` to `config/tenantpilot.php` foundation types.
+- [ ] T007 Add contract entry in `config/graph_contracts.php`.
+- [ ] T008 Implement foundation snapshot fetch for device categories.
+- [ ] T009 Implement foundation restore mapping + apply.
+
+## Phase 5: Verification
+- [ ] T010 Run targeted tests.
+- [ ] T011 Run Pint (`./vendor/bin/pint --dirty`).
+

specs/029-wip-policies/checklists/requirements.md

@@ -0,0 +1,14 @@
+# Requirements Checklist (029)
+
+**Created**: 2026-01-04  
+**Feature**: [spec.md](../spec.md)
+
+- [ ] `windowsInformationProtectionPolicy` and `mdmWindowsInformationProtectionPolicy` exist in `config/tenantpilot.php`.
+- [ ] Graph contracts exist with correct resources/type families/assignment endpoints.
+- [ ] Sync lists and stores both WIP types separately.
+- [ ] Snapshot capture stores full payload + assignments.
+- [ ] Restore preview explains gating and risks.
+- [ ] If enabled, restore execution uses derived endpoints and sanitizes payloads.
+- [ ] Normalized view is readable for admins.
+- [ ] Pest tests cover sync + snapshot + preview (and execution if enabled).
+

specs/029-wip-policies/plan.md

@@ -0,0 +1,23 @@
+# Plan: Windows Information Protection (WIP) Policies (029)
+
+**Branch**: `feat/029-wip-policies`  
+**Date**: 2026-01-04  
+**Input**: [spec.md](./spec.md)
+
+## Approach
+1. Confirm Graph behavior:
+   - endpoints for both WIP collections
+   - assignment endpoints (list + assign/create shape)
+   - patchable/read-only fields and required permissions
+2. Add new types to `config/tenantpilot.php` (category “Apps/MAM”, platform windows, restore mode/risk).
+3. Add graph contracts in `config/graph_contracts.php`:
+   - resource paths
+   - type families
+   - assignment endpoints
+4. Ensure restore uses the derived entity set endpoint (do not PATCH generic `managedAppPolicies/{id}` when Graph requires derived resources).
+5. Add a normalizer for readable UI output.
+6. Add targeted Pest coverage.
+
+## Decisions / Notes
+- **Restore mode**: default `preview-only` until endpoint + assignment behavior is confirmed with tests and real tenants.
+

specs/029-wip-policies/spec.md

@@ -0,0 +1,41 @@
+# Feature Specification: Windows Information Protection (WIP) Policies (029)
+
+**Feature Branch**: `feat/029-wip-policies`  
+**Created**: 2026-01-04  
+**Status**: Draft  
+**Priority**: P2
+
+## Context
+Some tenants rely on WIP (MAM/WIP). These policies live under `deviceAppManagement` and should be treated as first-class objects for backup/restore.
+
+## User Scenarios & Testing
+
+### User Story 1 — Inventory shows WIP policies separately (Priority: P1)
+As an admin, I can see WIP policies as their own types (not mixed into generic MAM policies).
+
+**Acceptance Scenarios**
+1. Sync lists WIP policies from Graph and stores them as `windowsInformationProtectionPolicy`.
+2. Sync lists MDM WIP policies and stores them as `mdmWindowsInformationProtectionPolicy`.
+
+### User Story 2 — Backup + restore (Priority: P2)
+As an admin, I can back up and restore WIP policies with assignments safely.
+
+**Acceptance Scenarios**
+1. Snapshot capture stores the full policy payload and assignments.
+2. Restore execution uses the correct derived entity set endpoint for create/update.
+
+## Requirements
+
+### Functional Requirements
+- **FR-001**: Add policy types:
+  - `windowsInformationProtectionPolicy` → `deviceAppManagement/windowsInformationProtectionPolicies`
+  - `mdmWindowsInformationProtectionPolicy` → `deviceAppManagement/mdmWindowsInformationProtectionPolicies`
+- **FR-002**: Capture full payload + assignments.
+- **FR-003**: Restore supports create/update with contract-driven sanitization and assignment apply.
+- **FR-004**: Add normalized display for key WIP fields (protected apps/identities, enforcement level, exemptions, etc.).
+- **FR-005**: Add Pest tests for sync + snapshot + restore preview/execution.
+
+## Success Criteria
+- **SC-001**: WIP policies appear and can be backed up.
+- **SC-002**: Restore preview/execution uses correct endpoints and is auditable.
+

specs/029-wip-policies/tasks.md

@@ -0,0 +1,32 @@
+# Tasks: Windows Information Protection (WIP) Policies (029)
+
+**Branch**: `feat/029-wip-policies`  
+**Date**: 2026-01-04  
+**Input**: [spec.md](./spec.md), [plan.md](./plan.md)
+
+## Phase 1: Setup
+- [x] T001 Create spec/plan/tasks and checklist.
+
+## Phase 2: Research & Design
+- [ ] T002 Confirm Graph endpoints for WIP and MDM WIP policy collections.
+- [ ] T003 Confirm assignment endpoints and body shape.
+- [ ] T004 Confirm patchable fields and define sanitization rules.
+- [ ] T005 Decide restore mode and risk classification.
+
+## Phase 3: Tests (TDD)
+- [ ] T006 Add sync test importing both WIP types.
+- [ ] T007 Add snapshot capture test (payload + assignments).
+- [ ] T008 Add restore preview test (preview-only gating).
+- [ ] T009 Add restore execution test using derived endpoints (if enabled).
+
+## Phase 4: Implementation
+- [ ] T010 Add types to `config/tenantpilot.php`.
+- [ ] T011 Add contracts in `config/graph_contracts.php`.
+- [ ] T012 Update sync classification so WIP types are not treated as generic appProtectionPolicy.
+- [ ] T013 Update restore/apply paths if Graph requires derived resources.
+- [ ] T014 Add normalizer for readable settings.
+
+## Phase 5: Verification
+- [ ] T015 Run targeted tests.
+- [ ] T016 Run Pint (`./vendor/bin/pint --dirty`).
+

specs/030-intune-rbac-backup/checklists/requirements.md

@@ -0,0 +1,12 @@
+# Requirements Checklist (030)
+
+**Created**: 2026-01-04  
+**Feature**: [spec.md](../spec.md)
+
+- [ ] RBAC types are defined (policy or foundation) with `preview-only` restore.
+- [ ] Graph contracts exist for role definitions/assignments.
+- [ ] Inventory/backup capture works and is tenant-scoped.
+- [ ] Restore preview shows dependency report and blocks unsafe execution.
+- [ ] Audit logs exist for preview and any execution attempts.
+- [ ] Pest tests cover inventory + backup + preview.
+

specs/030-intune-rbac-backup/plan.md

@@ -0,0 +1,24 @@
+# Plan: Intune RBAC Backup (Role Definitions + Assignments) (030)
+
+**Branch**: `feat/030-intune-rbac-backup`  
+**Date**: 2026-01-04  
+**Input**: [spec.md](./spec.md)
+
+## Approach
+1. Confirm Graph API details for RBAC:
+   - `deviceManagement/roleDefinitions`
+   - `deviceManagement/roleAssignments`
+   - required permissions, paging, and any known restrictions
+2. Decide modeling:
+   - policy types (in Policy inventory) vs foundation types (backup-only)
+3. Add config/contract entries with restore mode `preview-only`.
+4. Implement snapshot capture with careful sanitization (no secrets, no tokens).
+5. Implement restore preview dependency checks:
+   - groups referenced by assignments
+   - scope tags / scope members
+6. Add targeted tests for inventory + backup + preview.
+
+## Decisions / Notes
+- Default to `preview-only` for execution due to high blast radius.
+- Prefer mapping by stable identifiers (roleDefinition roleKey/displayName) and treat ambiguity as a block.
+

specs/030-intune-rbac-backup/spec.md

@@ -0,0 +1,51 @@
+# Feature Specification: Intune RBAC Backup (Role Definitions + Assignments) (030)
+
+**Feature Branch**: `feat/030-intune-rbac-backup`  
+**Created**: 2026-01-04  
+**Status**: Draft  
+**Priority**: P3 (Optional)
+
+## Context
+For a “complete tenant restore”, RBAC matters. However, RBAC restore is risky and must be **safe-by-default** (preview-only, strong warnings, explicit confirmation, audit logging).
+
+This feature focuses on:
+- Inventory + backup/version of RBAC objects
+- Restore preview and validation
+- Execution only if/when safety gates and mapping are robust
+
+## User Scenarios & Testing
+
+### User Story 1 — Inventory + backup RBAC objects (Priority: P1)
+As an admin, I can inventory and back up role definitions and role assignments.
+
+**Acceptance Scenarios**
+1. Sync lists role definitions as `roleDefinition`.
+2. Sync lists role assignments as `roleAssignment`.
+3. Backup captures full payloads and references (scope tags, members, scopes).
+
+### User Story 2 — Restore preview + safety gates (Priority: P1)
+As an admin, I can run a restore preview that clearly explains what would change and blocks unsafe execution.
+
+**Acceptance Scenarios**
+1. Preview warns on built-in roles vs custom roles and blocks unsafe cases.
+2. Preview validates referenced groups/scope tags and reports missing dependencies.
+
+## Requirements
+
+### Functional Requirements
+- **FR-001**: Add policy (or foundation) types:
+  - `roleDefinition` → `deviceManagement/roleDefinitions`
+  - `roleAssignment` → `deviceManagement/roleAssignments`
+- **FR-002**: Snapshot capture stores full payloads; assignments capture includes references.
+- **FR-003**: Restore preview includes a dependency report (missing groups/tags/scopes).
+- **FR-004**: Restore execution defaults to `preview-only` until safety gates are implemented.
+- **FR-005**: Add targeted Pest tests for inventory + backup + preview dependency report.
+
+### Non-Functional Requirements
+- **NFR-001**: Never auto-grant permissions/scopes; no “self-heal” background jobs.
+- **NFR-002**: All operations are tenant-scoped and audited.
+
+## Success Criteria
+- **SC-001**: RBAC objects are visible and captured in backups.
+- **SC-002**: Preview makes restore risk and missing dependencies explicit.
+

specs/030-intune-rbac-backup/tasks.md

@@ -0,0 +1,29 @@
+# Tasks: Intune RBAC Backup (Role Definitions + Assignments) (030)
+
+**Branch**: `feat/030-intune-rbac-backup`  
+**Date**: 2026-01-04  
+**Input**: [spec.md](./spec.md), [plan.md](./plan.md)
+
+## Phase 1: Setup
+- [x] T001 Create spec/plan/tasks and checklist.
+
+## Phase 2: Research & Design
+- [ ] T002 Confirm Graph endpoints, permissions, and payload shape for role definitions/assignments.
+- [ ] T003 Decide whether RBAC objects are policy types or foundation types.
+- [ ] T004 Define preview dependency report rules and what blocks execution.
+
+## Phase 3: Tests (TDD)
+- [ ] T005 Add sync test importing RBAC objects (if modeled as policy types).
+- [ ] T006 Add backup snapshot test for role definitions/assignments.
+- [ ] T007 Add restore preview test that reports missing dependencies and blocks execution.
+
+## Phase 4: Implementation
+- [ ] T008 Add RBAC types to `config/tenantpilot.php` (restore mode preview-only).
+- [ ] T009 Add graph contracts in `config/graph_contracts.php`.
+- [ ] T010 Implement snapshot capture and safe normalized display.
+- [ ] T011 Implement restore preview dependency report.
+
+## Phase 5: Verification
+- [ ] T012 Run targeted tests.
+- [ ] T013 Run Pint (`./vendor/bin/pint --dirty`).
+