spec: scripts management

specs/013-scripts-management/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: Scripts Management
+
+**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: Supported script policy types are already discoverable in the product, and restore/assignments follow existing system patterns.

specs/013-scripts-management/spec.md

@@ -0,0 +1,112 @@
+# Feature Specification: Scripts Management
+
+**Feature Branch**: `013-scripts-management`  
+**Created**: 2026-01-01  
+**Status**: Draft  
+**Input**: User description: "Add end-to-end support for management scripts (Windows PowerShell scripts, macOS shell scripts, and proactive remediations) including readable normalized settings, backup snapshots, and safe restore with assignments."
+
+## 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 a script safely (Priority: P1)
+
+As an admin, I want to restore a script policy from a saved snapshot so I can recover from accidental or unwanted changes.
+
+**Why this priority**: Restoring known-good configuration is the core safety value of the product.
+
+**Independent Test**: Can be fully tested by restoring one script policy into a tenant where the script is missing or changed, and verifying the script and its assignments match the snapshot.
+
+**Acceptance Scenarios**:
+
+1. **Given** a saved script snapshot and a target tenant where the script does not exist, **When** I run restore for that item, **Then** the system creates a new script policy from the snapshot and reports success.
+2. **Given** a saved script snapshot and a target tenant where the script exists with differences, **When** I run restore for that item, **Then** the system updates the existing script policy to match the snapshot and reports success.
+3. **Given** a saved script snapshot with assignments, **When** I run restore, **Then** the system applies the assignments using the snapshot data and reports assignment outcomes.
+
+---
+
+### User Story 2 - Readable script configuration (Priority: P2)
+
+As an admin, I want to view a readable, normalized representation of a script policy so I can understand what it does and compare versions reliably.
+
+**Why this priority**: If admins cannot quickly understand changes, version history and restore become risky and slow.
+
+**Independent Test**: Can be tested by opening a script policy version page and confirming that normalized settings display key fields consistently across versions.
+
+**Acceptance Scenarios**:
+
+1. **Given** a script policy version, **When** I open the policy version details, **Then** I see a normalized settings view that is stable (same input yields same output ordering/shape).
+2. **Given** two versions of the same script policy with changes, **When** I view their normalized settings, **Then** the differences are visible without reading raw JSON.
+
+---
+
+### User Story 3 - Reliable backup capture (Priority: P3)
+
+As an admin, I want backups/version snapshots of script policies to be captured reliably so I can restore later with confidence.
+
+**Why this priority**: Restore is only as good as the snapshot quality.
+
+**Independent Test**: Can be tested by capturing a snapshot of each script policy type and validating it contains the expected configuration fields for that policy.
+
+**Acceptance Scenarios**:
+
+1. **Given** an existing script policy, **When** I capture a snapshot/backup, **Then** the saved snapshot contains the complete configuration needed to restore the script policy.
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+- Restoring a snapshot whose policy type does not match the target item (type mismatch) must fail clearly without making changes.
+- Restoring when the snapshot contains fields that are not accepted by the target environment must result in a clear failure reason and no partial silent data loss.
+- Assignments referencing groups or foundations that cannot be mapped must be reported as manual-required for those assignments.
+- Script policies with very large or complex configuration should still render a readable normalized settings view (with safe truncation if needed).
+
+## 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 script policies for the supported script policy types.
+- **FR-002**: System MUST allow capturing a snapshot of a script policy that is sufficient to restore the policy later.
+- **FR-003**: System MUST allow restoring a script policy from a snapshot in a safe manner (create when missing; update when present).
+- **FR-004**: System MUST support restoring assignments for script policies using the assignments saved with the snapshot.
+- **FR-005**: System MUST present a readable normalized settings view for script policies and script policy versions.
+- **FR-006**: System MUST prevent execution of restore if the snapshot policy type does not match the restore item type.
+- **FR-007**: System MUST record an audit trail for restore preview and restore execution attempts.
+
+### Key Entities *(include if feature involves data)*
+
+- **Script Policy**: A configuration object representing a management script (platform-specific variants), identified by a stable external identifier and a display name.
+- **Script Policy Snapshot**: An immutable capture of a script policy’s configuration at a point in time, used for diffing and restore.
+- **Script Assignment**: A target association that applies a script policy to a defined scope (e.g., groups/filters), stored with the snapshot and restored with mapping when needed.
+
+## 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 script policy in under 1 minute.
+- **SC-002**: In a test tenant, restoring a script policy results in the target script policy and assignments matching the snapshot for 100% of supported script policy types.
+- **SC-003**: Normalized settings for a script policy are readable and stable: repeated views of the same snapshot produce identical normalized output.
+- **SC-004**: Restore failures provide a clear reason (actionable message) in 100% of failure cases.