spec: enrollment & autopilot

specs/014-enrollment-autopilot/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: Enrollment & Autopilot
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-01-01
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Assumptions: Restore behavior for enrollment restrictions remains preview-only until a separate product decision explicitly enables it.

specs/014-enrollment-autopilot/spec.md

@@ -0,0 +1,111 @@
+# Feature Specification: Enrollment & Autopilot
+
+**Feature Branch**: `014-enrollment-autopilot`  
+**Created**: 2026-01-01  
+**Status**: Draft  
+**Input**: User description: "Improve enrollment and Autopilot configuration safety by adding readable normalized settings, reliable snapshot capture, and safe restore behavior for enrollment restrictions, enrollment status page, and Autopilot deployment profiles."
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+  
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - Restore Autopilot/ESP safely (Priority: P1)
+
+As an admin, I want to restore Autopilot deployment profiles and the Enrollment Status Page configuration from saved snapshots so I can recover enrollment readiness after changes.
+
+**Why this priority**: Enrollment misconfiguration blocks device onboarding; fast recovery is critical.
+
+**Independent Test**: Can be tested by restoring one Autopilot profile and one Enrollment Status Page item from snapshots into a target tenant and verifying they match the snapshot.
+
+**Acceptance Scenarios**:
+
+1. **Given** a saved Autopilot deployment profile snapshot and a target tenant where the profile is missing, **When** I restore it, **Then** a new profile is created and restore reports success.
+2. **Given** a saved Enrollment Status Page snapshot and a target tenant where the item exists with differences, **When** I restore it, **Then** the configuration is updated to match the snapshot and restore reports success.
+
+---
+
+### User Story 2 - Restore behavior is explicit for high-risk enrollment restrictions (Priority: P2)
+
+As an admin, I want high-risk enrollment restrictions to be handled explicitly (preview-only unless intentionally enabled) so I do not accidentally break enrollment flows.
+
+**Why this priority**: Enrollment restrictions can lock out device onboarding; accidental changes are high impact.
+
+**Independent Test**: Can be tested by attempting restore of an enrollment restriction item and verifying the system does not apply changes when it is configured as preview-only.
+
+**Acceptance Scenarios**:
+
+1. **Given** an enrollment restriction snapshot and the feature is allowed for preview-only, **When** I run restore execution, **Then** the system skips applying changes and records a result indicating preview-only behavior.
+
+---
+
+### User Story 3 - Readable normalized settings (Priority: P3)
+
+As an admin, I want to view readable normalized settings for Autopilot and Enrollment configurations so I can understand what will happen during device onboarding.
+
+**Why this priority**: Enrollment troubleshooting is faster when key settings are visible and consistent.
+
+**Independent Test**: Can be tested by opening a version details page and confirming a stable normalized settings view is present and readable.
+
+**Acceptance Scenarios**:
+
+1. **Given** a saved Autopilot/ESP snapshot, **When** I view the policy version, **Then** I see a normalized settings view that highlights key enrollment-relevant fields.
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+- Autopilot or ESP configuration in the target tenant is missing: system must create or clearly fail with an actionable reason.
+- Restoring Enrollment Status Page items must not silently drop settings; failures must be explicit.
+- Enrollment restrictions remain preview-only unless explicitly enabled by product decision; execution must not apply them by default.
+- Assignments (if present for these types) that cannot be mapped must be reported as manual-required.
+
+## Requirements *(mandatory)*
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST support listing and viewing enrollment and Autopilot configuration items for the supported types.
+- **FR-002**: System MUST capture snapshots for these configuration items that are sufficient for later restore.
+- **FR-003**: System MUST support restore for Autopilot deployment profiles and Enrollment Status Page configuration.
+- **FR-004**: System MUST treat enrollment restrictions as high risk and default them to preview-only behavior unless explicitly enabled.
+- **FR-005**: System MUST present a readable normalized settings view for these configuration items and their versions.
+- **FR-006**: System MUST prevent restore execution if the snapshot type does not match the target item type.
+- **FR-007**: System MUST record audit entries for restore preview and restore execution attempts.
+
+### Key Entities *(include if feature involves data)*
+
+- **Autopilot Deployment Profile**: A configuration object that defines device provisioning behavior during Autopilot.
+- **Enrollment Status Page Configuration**: A configuration object that defines the onboarding status experience during enrollment.
+- **Enrollment Restriction**: A high-risk configuration object that can block or constrain enrollment.
+- **Snapshot**: An immutable capture of a configuration object at a point in time.
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: An admin can complete a restore preview for a single Autopilot/ESP item in under 1 minute.
+- **SC-002**: In a test tenant, restoring Autopilot deployment profiles and Enrollment Status Page results in configurations matching the snapshot for 100% of supported items.
+- **SC-003**: Enrollment restrictions remain non-executable by default (preview-only) with clear status reporting in 100% of attempts.
+- **SC-004**: Normalized settings views for these items are stable and readable (same snapshot yields identical normalized output).