merge: agent session work

specs/007-device-config-compliance/plan.md

@@ -0,0 +1,79 @@
+# Implementation Plan: Device Configuration and Compliance Coverage
+
+**Branch**: `007-device-config-compliance` | **Date**: 2025-12-26 | **Spec**: ./spec.md
+**Input**: Feature specification from `/specs/007-device-config-compliance/spec.md`
+
+## Summary
+
+Expand backup and restore coverage for device configuration, compliance, scripts, and update rings. This plan focuses on policy type coverage, assignment capture, and safe restore behavior using existing foundation mappings and assignment logic.
+
+Phase outputs:
+- Phase 0 research: n/a (no new research artifact yet)
+- Phase 1 design: n/a (no new data model artifact yet)
+
+## Technical Context
+
+**Language/Version**: PHP 8.4 (Laravel 12)  
+**Primary Dependencies**: Laravel 12, Filament v4, Livewire v3, Microsoft Graph (custom client abstraction)  
+**Storage**: PostgreSQL (JSONB payload storage for snapshots)  
+**Testing**: Pest v4 + PHPUnit 12  
+**Target Platform**: Docker/Sail locally; container deploy via Dokploy  
+**Project Type**: Web application (Laravel backend + Filament admin UI)  
+**Performance Goals**: Restore preview for 100 selected items in under 2 minutes  
+**Constraints**: Restore must be defensive (no deletions); assignments only applied with valid mapping; audit logs required  
+**Scale/Scope**: Tenants with mixed configuration and compliance policies, including scripts and update rings
+
+## Constitution Check
+
+The constitution at `.specify/memory/constitution.md` is currently an unfilled template. For this feature, adopt the repo rules as gates:
+
+- Sail-first local dev/test commands.
+- Spec gate: code changes must be accompanied by `specs/007-device-config-compliance/` updates.
+- Tests required for behavior changes (Pest).
+- Restore safety: never delete; skip unsafe assignments; record reasons.
+- Auditability: backup and restore outcomes are logged per tenant.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/007-device-config-compliance/
+├── spec.md
+├── plan.md
+└── tasks.md
+```
+
+### Source Code (expected touch points)
+
+```text
+app/
+├── Filament/
+│   └── Resources/
+├── Models/
+│   ├── BackupItem.php
+│   ├── Policy.php
+│   └── PolicyVersion.php
+├── Services/
+│   ├── Graph/
+│   └── Intune/
+└── Jobs/
+
+config/
+├── graph_contracts.php
+├── intune_permissions.php
+└── tenantpilot.php
+
+tests/
+├── Feature/
+└── Unit/
+```
+
+**Structure Decision**: Extend existing services (PolicySnapshotService, PolicyCaptureOrchestrator, RestoreService) and Filament resources, adding only targeted helpers where needed.
+
+## Complexity Tracking
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| n/a | n/a | n/a |
+

specs/007-device-config-compliance/spec.md

@@ -0,0 +1,78 @@
+# Feature Specification: Device Configuration and Compliance Coverage
+
+**Feature Branch**: `007-device-config-compliance`  
+**Created**: 2025-12-26  
+**Status**: Draft  
+**Input**: Workload list for Intune backup and restore coverage (MVP vs full scope).
+
+## Program Scope Reference (MVP vs Full)
+
+### MVP Scope (Phase 1)
+- Device configuration and compliance: administrative templates; settings catalog policies; device configurations (including custom OMA-URI); device compliance policies; assignments.
+- Scripts and remediations: PowerShell scripts (Windows); macOS shell scripts (where supported); proactive remediations and assignments.
+- Enrollment and Autopilot: Autopilot deployment profiles and assignments; Enrollment Status Page (ESP) if used.
+- Update management (Windows): software update rings and assignments.
+- Endpoint security: endpoint security configurations (antivirus, firewall, disk encryption, EDR, ASR, account protection) and assignments.
+- Tenant administration foundations: assignment filters; scope tags; notification message templates.
+
+### Full Scope (Phase 2+)
+- Compliance actions and notifications: actions for noncompliance; compliance notifications and templates.
+- Apps and app management: client apps; app protection policies; app configuration policies; assignments; supersedence metadata.
+- Enrollment: enrollment restrictions; enrollment notifications; terms and conditions; ADE tokens and profiles.
+- Update management: feature update policies; quality update policies; driver update policies; expedite/hotpatch policies.
+- Endpoint security: security baselines (Windows security baseline, Microsoft Defender, Microsoft Edge); endpoint privilege management policies.
+- Tenant administration: device cleanup rules; RBAC roles and role assignments.
+- Connectors and tokens (metadata-only): APNs; VPP tokens; managed Google Play; certificate connectors; remote help settings.
+
+## Overview
+Expand backup and restore coverage for device configuration and compliance workloads, including scripts and remediations. This feature focuses on policy types that are already core to DR and rollback, and builds on existing foundations and assignment mapping capabilities.
+
+## User Scenarios and Testing (mandatory)
+
+### User Story 1 - Backup and Restore Core Configuration Policies (Priority: P1)
+As an admin, I want to back up and restore device configuration and compliance policies with their assignments and scope tags, so that a restore reproduces targeting accurately.
+
+**Independent Test**: Select at least one settings catalog policy, one device configuration policy (including an OMA-URI policy), and one device compliance policy. Create a backup with assignments and scope tags enabled. Restore into a tenant with different group IDs and verify assignments are mapped or skipped with clear reasons.
+
+**Acceptance Scenarios**:
+1. Given policies with assignments and scope tags, when a backup is captured, then assignments and scope tag metadata are stored alongside the snapshot.
+2. Given a restore run with group mapping, when policies are restored, then assignments are applied using mapped group IDs and assignment filters.
+3. Given missing mappings, when restore executes, then assignments are skipped and a human readable reason is recorded.
+
+### User Story 2 - Compliance Actions and Notifications (Priority: P2)
+As an admin, I want actions for noncompliance and compliance notification templates to be captured and restored, so that compliance workflows remain intact after restore.
+
+**Independent Test**: Create a compliance policy with scheduled actions and a notification template. Capture a backup including foundations. Restore into a tenant without that template and verify the template is created and referenced correctly.
+
+**Acceptance Scenarios**:
+1. Given a compliance policy referencing a notification template, when restore executes, then the template is restored first and the policy references the mapped template ID.
+2. Given a missing template and no mapping, when restore executes, then the policy is restored without that action and a skip reason is recorded.
+
+### User Story 3 - Scripts and Remediations (Priority: P3)
+As an admin, I want scripts and remediations to be captured and restored with assignments, so that endpoint automation is preserved.
+
+**Independent Test**: Capture a PowerShell script and a proactive remediation with assignments. Restore into a test tenant and verify assignments are applied safely.
+
+**Acceptance Scenarios**:
+1. Given a script policy with assignments, when restore executes, then the script is recreated or updated and assignments are applied.
+2. Given a remediation with missing assignment filter mapping, when restore executes, then the assignment is skipped and the remediation is still restored.
+
+## Requirements (mandatory)
+
+### Functional Requirements
+- **FR-007.1**: System MUST support backup and restore for administrative templates, settings catalog policies, device configurations (including OMA-URI), and device compliance policies.
+- **FR-007.2**: System MUST capture assignments and scope tags when the backup flags are enabled, using the existing capture orchestrator.
+- **FR-007.3**: System MUST handle compliance actions and notification templates by restoring templates first and mapping references in policies.
+- **FR-007.4**: System MUST restore scripts and remediations with assignments, applying foundation mappings and group mappings where available.
+- **FR-007.5**: System MUST keep Conditional Access restore preview-only until identity dependency mapping is supported.
+- **FR-007.6**: System MUST record audit logs for backup and restore actions, including skipped assignments and template mapping outcomes.
+
+### Non-Goals
+- No support for app workloads in this feature (tracked separately).
+- No connector or token restore (metadata-only handled in a later phase).
+
+## Success Criteria (mandatory)
+- **SC-007.1**: For a backup containing at least 10 mixed configuration/compliance items, restore completes with 100% of items in Applied, Partial, or Skipped with reason (no silent failures).
+- **SC-007.2**: At least 95% of assignments in a mixed restore are either applied successfully or explicitly skipped with a recorded reason.
+- **SC-007.3**: Restore preview for 100 selected items completes in under 2 minutes in a typical admin environment.
+

specs/007-device-config-compliance/tasks.md

@@ -0,0 +1,74 @@
+# Tasks: Device Configuration and Compliance Coverage (007)
+
+**Branch**: `feat/007-device-config-compliance` | **Date**: 2025-12-26  
+**Input**: [spec.md](./spec.md), [plan.md](./plan.md)
+
+## Task Format
+
+- **Checkbox**: `- [ ]` for incomplete, `- [x]` for complete
+- **Task ID**: Sequential T001, T002, T003...
+- **[P] marker**: Task can run in parallel (different files, no blocking dependencies)
+- **[Story] label**: User story tag (US1, US2, US3...)
+- **File path**: Always include exact file path in description
+
+## Phase 1: Policy Types, Contracts, Permissions
+
+**Purpose**: Add missing device configuration, compliance, scripts, and update ring types with Graph contract coverage.
+
+- [ ] T001 [P] Expand policy type registry for device configuration, compliance, scripts, and update rings in `config/tenantpilot.php` (labels, categories, restore mode, risk).
+- [ ] T002 [P] Add/update Graph contracts and assignment endpoints for new policy types in `config/graph_contracts.php`.
+- [ ] T003 [P] Verify and extend permissions for the new workloads in `config/intune_permissions.php`.
+- [ ] T004 Update type metadata helpers and filters in `app/Filament/Resources/PolicyResource.php` and `app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php`.
+
+**Checkpoint**: New policy types are recognized across UI metadata and Graph contract registry.
+
+---
+
+## Phase 2: Snapshot Capture and Metadata
+
+**Purpose**: Ensure snapshots, assignments, and scope tags are captured for the new workloads.
+
+- [ ] T005 Update `app/Services/Intune/PolicySnapshotService.php` to fetch and hydrate the new policy types correctly (filters, select fields).
+- [ ] T006 Extend `app/Services/Intune/PolicyCaptureOrchestrator.php` to capture assignments and scope tags for the new types with existing resolvers.
+- [ ] T007 Update `app/Services/Intune/BackupService.php` to capture snapshots for the new types and propagate warnings.
+- [ ] T008 Add or extend normalization support in `app/Services/Intune/PolicyNormalizer.php` for the new policy types.
+
+**Checkpoint**: Backups include snapshots and metadata for configuration/compliance policies.
+
+---
+
+## Phase 3: Restore Logic and Mapping
+
+**Purpose**: Restore new policy types safely using assignment and foundation mappings.
+
+- [ ] T009 Update `app/Services/Intune/RestoreService.php` to restore the new policy types using Graph contracts.
+- [ ] T010 Extend `app/Services/AssignmentRestoreService.php` for assignment endpoints of the new types.
+- [ ] T011 Ensure compliance notification templates are restored and referenced via mapping in `app/Services/Intune/RestoreService.php`.
+- [ ] T012 Add audit coverage for compliance action mapping outcomes in `app/Services/Intune/AuditLogger.php`.
+
+**Checkpoint**: Restore applies policies and assignments or skips with clear reasons.
+
+---
+
+## Phase 4: Admin UX
+
+**Purpose**: Surface restore and compliance details clearly in the UI.
+
+- [ ] T013 Update `resources/views/filament/infolists/entries/restore-preview.blade.php` to surface compliance action/template warnings.
+- [ ] T014 Update `resources/views/filament/infolists/entries/restore-results.blade.php` to show compliance action mapping outcomes and skip reasons.
+
+**Checkpoint**: Admins can see compliance related mapping results in preview and results.
+
+---
+
+## Phase 5: Tests and Verification
+
+**Purpose**: Cover new workloads with Pest tests and verify formatting.
+
+- [ ] T015 Add unit tests for snapshot and normalization coverage in `tests/Unit/PolicySnapshotServiceTest.php` and `tests/Unit/PolicyNormalizerTest.php`.
+- [ ] T016 Add feature tests for backup and restore flows in `tests/Feature/Filament/RestorePreviewTest.php` and `tests/Feature/Filament/RestoreExecutionTest.php`.
+- [ ] T017 Run tests: `./vendor/bin/sail artisan test tests/Unit/PolicySnapshotServiceTest.php tests/Unit/PolicyNormalizerTest.php tests/Feature/Filament/RestorePreviewTest.php tests/Feature/Filament/RestoreExecutionTest.php`
+- [ ] T018 Run Pint: `./vendor/bin/pint --dirty`
+
+**Checkpoint**: Tests pass and formatting is clean.
+

specs/008-apps-app-management/plan.md

@@ -0,0 +1,79 @@
+# Implementation Plan: Apps and App Management Coverage
+
+**Branch**: `008-apps-app-management` | **Date**: 2025-12-26 | **Spec**: ./spec.md
+**Input**: Feature specification from `/specs/008-apps-app-management/spec.md`
+
+## Summary
+
+Introduce backup and restore coverage for app workloads: client apps (metadata-only), app protection policies, and app configuration policies. The plan emphasizes safe restore with clear dependency handling and assignment mapping, without binary uploads.
+
+Phase outputs:
+- Phase 0 research: n/a (no new research artifact yet)
+- Phase 1 design: n/a (no new data model artifact yet)
+
+## Technical Context
+
+**Language/Version**: PHP 8.4 (Laravel 12)  
+**Primary Dependencies**: Laravel 12, Filament v4, Livewire v3, Microsoft Graph (custom client abstraction)  
+**Storage**: PostgreSQL (JSONB payload storage for snapshots)  
+**Testing**: Pest v4 + PHPUnit 12  
+**Target Platform**: Docker/Sail locally; container deploy via Dokploy  
+**Project Type**: Web application (Laravel backend + Filament admin UI)  
+**Performance Goals**: Preview and restore for 50 app items in under 2 minutes  
+**Constraints**: No binary upload; restore must be preview-only when dependencies are missing; audit logs required  
+**Scale/Scope**: Mixed app portfolios with assignments and app dependency chains
+
+## Constitution Check
+
+The constitution at `.specify/memory/constitution.md` is currently an unfilled template. For this feature, adopt the repo rules as gates:
+
+- Sail-first local dev/test commands.
+- Spec gate: code changes must be accompanied by `specs/008-apps-app-management/` updates.
+- Tests required for behavior changes (Pest).
+- Restore safety: metadata-only for apps, no deletions, skip unsafe assignments.
+- Auditability: backup and restore outcomes are logged per tenant.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/008-apps-app-management/
+├── spec.md
+├── plan.md
+└── tasks.md
+```
+
+### Source Code (expected touch points)
+
+```text
+app/
+├── Filament/
+│   └── Resources/
+├── Models/
+│   ├── BackupItem.php
+│   ├── Policy.php
+│   └── PolicyVersion.php
+├── Services/
+│   ├── Graph/
+│   └── Intune/
+└── Jobs/
+
+config/
+├── graph_contracts.php
+├── intune_permissions.php
+└── tenantpilot.php
+
+tests/
+├── Feature/
+└── Unit/
+```
+
+**Structure Decision**: Extend existing policy snapshot and restore services with app-specific helpers where needed, keeping metadata-only operations.
+
+## Complexity Tracking
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| n/a | n/a | n/a |
+

specs/008-apps-app-management/spec.md

@@ -0,0 +1,59 @@
+# Feature Specification: Apps and App Management Coverage
+
+**Feature Branch**: `008-apps-app-management`  
+**Created**: 2025-12-26  
+**Status**: Draft  
+**Input**: Workload list for Intune backup and restore coverage (apps and assignments).
+
+## Overview
+Expand backup and restore to application workloads, including client apps, app protection policies, and app configuration policies. This feature focuses on safe restore with clear mapping and avoids destructive changes or binary re-uploads.
+
+## User Scenarios and Testing (mandatory)
+
+### User Story 1 - App Protection Policies (Priority: P1)
+As an admin, I want to back up and restore app protection policies with their assignments, so that MAM configurations can be recovered safely.
+
+**Independent Test**: Capture an app protection policy with assignments. Restore into a tenant with different group IDs and verify assignments are mapped or skipped with reasons.
+
+**Acceptance Scenarios**:
+1. Given a policy with assignments, when restore executes, then assignments are applied using group mapping.
+2. Given unresolved group mapping, when restore executes, then assignments are skipped with a human readable reason.
+
+### User Story 2 - App Configuration Policies (Priority: P2)
+As an admin, I want to back up and restore app configuration policies for managed devices and managed apps, so that app settings are preserved.
+
+**Independent Test**: Capture at least one managed device app configuration and one managed app configuration with assignments. Restore into a test tenant and verify the policy payload and assignments are applied.
+
+**Acceptance Scenarios**:
+1. Given a managed device app configuration policy, when restore executes, then the policy is created or updated and assignments are applied safely.
+2. Given a managed app configuration policy referencing a missing app, when restore executes, then the policy is skipped with a clear reason.
+
+### User Story 3 - Client Apps (Priority: P3)
+As an admin, I want to back up and restore client app metadata and assignments, so that app deployments can be re-created without re-uploading binaries.
+
+**Independent Test**: Capture a mix of Win32 and Store apps with assignments. Restore into a test tenant and verify metadata and assignments are recreated or updated.
+
+**Acceptance Scenarios**:
+1. Given a client app with assignments, when restore executes, then assignments are applied using group mapping and assignment filter mapping.
+2. Given a client app that cannot be matched in the target tenant, when restore executes, then the app is created if metadata-only create is supported, or skipped with a reason.
+
+## Requirements (mandatory)
+
+### Functional Requirements
+- **FR-008.1**: System MUST support backup and restore for client apps as metadata-only (no binary upload).
+- **FR-008.2**: System MUST support backup and restore for app protection policies with assignments.
+- **FR-008.3**: System MUST support backup and restore for app configuration policies (managed devices and managed apps) with assignments.
+- **FR-008.4**: System MUST apply assignments using existing group mapping and foundation mapping (assignment filters).
+- **FR-008.5**: System MUST capture and restore app dependency metadata (supersedence) where supported, ensuring base apps are restored before dependents.
+- **FR-008.6**: System MUST provide preview-only mode for app restores with clear warnings for missing dependencies.
+- **FR-008.7**: System MUST record audit logs for app backup and restore actions, including skipped items and dependency failures.
+
+### Non-Goals
+- No binary content upload or packaging (Win32, Store, LOB) in this feature.
+- No token or connector re-creation (VPP, managed Google Play); metadata-only handling only.
+
+## Success Criteria (mandatory)
+- **SC-008.1**: Restoring a set of 20 mixed app objects results in 100% of items in Applied, Partial, or Skipped with reason (no silent failures).
+- **SC-008.2**: At least 95% of app assignments are applied successfully or explicitly skipped with a clear reason.
+- **SC-008.3**: Preview mode for app restores completes in under 2 minutes for 50 selected items.
+

specs/008-apps-app-management/tasks.md

@@ -0,0 +1,74 @@
+# Tasks: Apps and App Management Coverage (008)
+
+**Branch**: `feat/008-apps-app-management` | **Date**: 2025-12-26  
+**Input**: [spec.md](./spec.md), [plan.md](./plan.md)
+
+## Task Format
+
+- **Checkbox**: `- [ ]` for incomplete, `- [x]` for complete
+- **Task ID**: Sequential T001, T002, T003...
+- **[P] marker**: Task can run in parallel (different files, no blocking dependencies)
+- **[Story] label**: User story tag (US1, US2, US3...)
+- **File path**: Always include exact file path in description
+
+## Phase 1: Policy Types, Contracts, Permissions
+
+**Purpose**: Add app workload types and Graph contract coverage for app endpoints and assignments.
+
+- [ ] T001 [P] Expand app policy type registry in `config/tenantpilot.php` (client apps, app protection policies, app configuration policies).
+- [ ] T002 [P] Add/update Graph contracts and assignment endpoints for app workloads in `config/graph_contracts.php`.
+- [ ] T003 [P] Verify and extend permissions for app workloads in `config/intune_permissions.php`.
+- [ ] T004 Update type metadata helpers and filters in `app/Filament/Resources/PolicyResource.php` and `app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php`.
+
+**Checkpoint**: App workload types are discoverable and contract-backed.
+
+---
+
+## Phase 2: Snapshot Capture (Metadata-Only)
+
+**Purpose**: Capture app metadata without binary payloads and include assignments.
+
+- [ ] T005 Update `app/Services/Intune/PolicySnapshotService.php` to fetch app workloads and sanitize payloads.
+- [ ] T006 Add metadata-only sanitization in `app/Services/Graph/GraphContractRegistry.php` for app payloads (strip binary/content fields).
+- [ ] T007 Extend `app/Services/Intune/PolicyCaptureOrchestrator.php` to capture app assignments where supported.
+- [ ] T008 Update `app/Services/Intune/BackupService.php` to store app metadata-only snapshots and warnings.
+
+**Checkpoint**: App backups capture metadata and assignments safely.
+
+---
+
+## Phase 3: Restore Logic and Dependencies
+
+**Purpose**: Restore apps in metadata-only mode with dependency ordering and safe assignment application.
+
+- [ ] T009 Update `app/Services/Intune/RestoreService.php` to restore app workloads using metadata-only payloads.
+- [ ] T010 Extend `app/Services/AssignmentRestoreService.php` to apply app assignments with group and filter mapping.
+- [ ] T011 Add dependency ordering for app supersedence in `app/Services/Intune/AppDependencyPlanner.php`.
+- [ ] T012 Add preview-only warnings for unresolved app dependencies in `resources/views/filament/infolists/entries/restore-preview.blade.php`.
+
+**Checkpoint**: App restore handles dependencies and assignment mapping safely.
+
+---
+
+## Phase 4: Admin UX
+
+**Purpose**: Surface app restore constraints and metadata-only status in the UI.
+
+- [ ] T013 Update `resources/views/filament/infolists/entries/restore-results.blade.php` to show metadata-only and dependency warnings.
+- [ ] T014 Update restore item selection descriptions in `app/Filament/Resources/RestoreRunResource.php` for app workloads.
+
+**Checkpoint**: Admins see clear metadata-only and dependency warnings.
+
+---
+
+## Phase 5: Tests and Verification
+
+**Purpose**: Cover app workloads with Pest tests and verify formatting.
+
+- [ ] T015 Add unit tests for app payload sanitization in `tests/Unit/GraphContractRegistryTest.php`.
+- [ ] T016 Add feature tests for app backup and restore in `tests/Feature/Filament/RestorePreviewTest.php` and `tests/Feature/Filament/RestoreExecutionTest.php`.
+- [ ] T017 Run tests: `./vendor/bin/sail artisan test tests/Unit/GraphContractRegistryTest.php tests/Feature/Filament/RestorePreviewTest.php tests/Feature/Filament/RestoreExecutionTest.php`
+- [ ] T018 Run Pint: `./vendor/bin/pint --dirty`
+
+**Checkpoint**: Tests pass and formatting is clean.
+