TenantAtlas/specs/098-settings-slices-v1-backup-drift-ops/spec.md

Feature Specification: 098 — Settings Slices v1 (Backup + Drift + Operations)

Feature Branch: 098-settings-slices-v1-backup-drift-ops
Created: 2026-02-16
Status: Draft
Input: Workspace-level settings slices for Backup, Drift severity mapping, and Operations retention/thresholds with safe defaults.

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes: Workspace Settings screen (admin UI)
• Data Ownership: workspace-owned settings values (key/value) + audit log entries for setting changes
• RBAC: workspace membership required; view vs manage capability-gated; deny-as-not-found for non-members

Clarifications

Session 2026-02-16

• Q: Which “Reset to default” scope do you want on the Workspace Settings UI? → A: Per-setting reset (each key individually).
• Q: When an admin clicks “Save” and multiple settings change at once, how should audit logging behave? → A: One audit log entry per key changed.
• Q: Should we enforce a validation constraint between backup.retention_keep_last_default and backup.retention_min_floor? → A: Allow any values; effective retention is always clamped to backup.retention_min_floor.
• Q: For settings that are currently unset (so the system uses defaults), how should the UI present them? → A: Leave input unset, show helper text with the default/effective value.
• Q: In drift.severity_mapping, should severity values be case-sensitive? → A: Case-insensitive; normalize to lowercase on save.

User Scenarios & Testing (mandatory)

User Story 1 - Configure backup retention defaults (Priority: P1)

As a workspace admin, I want to configure workspace-wide defaults for backup retention so that enterprise workspaces can tune policy without code/config changes.

Why this priority: Backup retention is a common enterprise requirement and impacts storage cost and governance.

Independent Test: Can be tested by setting/unsetting workspace settings and verifying backup retention behavior remains unchanged by default and changes deterministically when configured.

Acceptance Scenarios:

1. Given no workspace settings exist for backup retention, When a backup retention decision is made, Then behavior matches the current baseline (no change).
2. Given a workspace default retention value is configured, When a backup retention decision is made without a more specific override, Then the configured default is used.
3. Given a retention “floor” value is configured, When any calculated retention value is below the floor, Then the effective retention is clamped up to the floor.
4. Given a per-schedule override is configured, When that override is below the configured floor, Then the override is clamped up to the floor.

---

User Story 2 - Configure drift severity mapping (Priority: P2)

As a workspace admin, I want to map drift finding types to severities so that findings align with enterprise risk posture and triage practices.

Why this priority: Severity directly affects how teams triage drift; a one-size-fits-all default is too rigid for enterprise.

Independent Test: Can be tested by saving a mapping, generating findings for mapped/unmapped types, and verifying severities are assigned correctly.

Acceptance Scenarios:

1. Given no drift severity mapping exists, When a drift finding is produced, Then its severity defaults to “medium”.
2. Given a mapping exists for a specific finding type, When a drift finding with that type is produced, Then the mapped severity is applied.
3. Given a mapping contains an unknown/unsupported severity value, When an admin attempts to save it, Then the save is rejected and no invalid values are persisted.

---

User Story 3 - Configure operations retention and stuck threshold (Priority: P3)

As a workspace admin, I want to configure retention for operations/run records and store a “stuck run” threshold so that data lifecycle and operational heuristics are workspace-tunable.

Why this priority: Retention policies and operational thresholds vary widely between organizations and audit requirements.

Independent Test: Can be tested by saving retention/threshold settings and verifying the retention cutoff used by pruning changes accordingly while no new automatic actions occur.

Acceptance Scenarios:

1. Given no operations retention setting exists, When operations/run pruning is executed, Then the cutoff matches the current baseline (no change).
2. Given an operations retention setting exists, When pruning is executed, Then the cutoff is derived from the configured retention days.
3. Given a stuck threshold is configured, When the Workspace Settings screen is re-opened, Then the configured value is shown exactly as saved.
4. Given a stuck threshold is configured, When operations/run behavior is observed, Then no automatic remediation or auto-handling is performed in this feature scope.

Edge Cases

• Attempting to save invalid numeric ranges (too low/high) is rejected and does not persist.
• Attempting to save invalid JSON (malformed) for drift mapping is rejected.
• Attempting to save drift mapping with non-string keys is rejected.
• Two admins editing settings concurrently results in deterministic persisted state (last write wins) and both attempts are auditable.
• A user without manage capability can view settings (read-only) but cannot submit changes.
• A non-member cannot discover the Workspace Settings screen or any values (deny-as-not-found).

Requirements (mandatory)

Constitution alignment (required): This feature MUST remain DB-only for screen rendering and MUST NOT introduce Microsoft Graph calls as part of rendering or saving these settings. Any setting mutation MUST be auditable.

Dependencies & Assumptions

• This feature depends on an existing workspace settings foundation that provides: workspace-scoped storage, consistent defaults, centralized validation, RBAC capability enforcement, and audit logging for changes.
• No tenant-specific override UI is included in v1; only workspace-wide configuration is in scope.
• The default values for all settings keys match the current baseline behavior at the time this feature ships.

Constitution alignment (RBAC-UX):

• Authorization planes involved: workspace-scoped admin UI.
• Non-member / not entitled to workspace scope → 404 (deny-as-not-found).
• Member but missing manage capability → 403 on mutation attempts; UI remains read-only.

Constitution alignment (OPS/observability): This feature does not introduce a new long-running operation type; it changes which configuration values are used by existing behavior. All admin-initiated mutations MUST produce audit log entries.

Functional Requirements

• FR-001: System MUST support workspace-level configuration for the following setting keys:
  • backup.retention_keep_last_default
  • backup.retention_min_floor
  • drift.severity_mapping
  • operations.operation_run_retention_days
  • operations.stuck_run_threshold_minutes
• FR-002: System MUST preserve existing behavior when none of the above settings are configured (defaults MUST match the current baseline).
• FR-003: System MUST validate and reject invalid setting values, ensuring no invalid configuration is silently persisted.
• FR-004: Workspace Settings UI MUST present the above keys grouped into three sections (Backup, Drift, Operations) and MUST be fully functional without any external API calls.
• FR-004a: For any setting key that is currently unset, the UI MUST keep the input in an “unset” state and MUST display helper text indicating the default (currently effective) value.
• FR-005: Users with view capability MUST be able to view current effective settings but MUST NOT be able to change them.
• FR-006: Users with manage capability MUST be able to change settings and reset individual settings back to defaults.
• FR-007: Resetting a setting to default MUST be a confirmed (destructive-like) action.
• FR-008: System MUST write audit log entries for each settings update and reset-to-default event including: workspace identity, actor identity, setting key, old value, new value, and timestamp.
• FR-008a: When a single save operation changes multiple keys, the system MUST write one audit log entry per key changed.

Backup slice requirements

• FR-009: backup.retention_keep_last_default MUST be an integer between 1 and 365.
• FR-010: backup.retention_min_floor MUST be an integer between 1 and 365.
• FR-011: Effective backup retention MUST never be lower than backup.retention_min_floor (applies to defaults and any more specific overrides).
• FR-011a: The system MUST NOT reject configuration solely because backup.retention_min_floor exceeds backup.retention_keep_last_default; instead, the effective retention MUST be clamped to the floor.

Drift slice requirements

• FR-012: drift.severity_mapping MUST be a JSON object mapping finding_type (string) → severity.
• FR-013: Allowed severity values MUST be limited to: low, medium, high, critical.
• FR-013a: Severity values MUST be accepted case-insensitively and normalized to lowercase when persisted.
• FR-014: If a finding type has no mapping entry, severity MUST default to medium.

Operations slice requirements

• FR-015: operations.operation_run_retention_days MUST be an integer between 7 and 3650.
• FR-016: Pruning of operations/run records MUST use the configured retention days when set; otherwise it MUST behave as the baseline.
• FR-017: operations.stuck_run_threshold_minutes MUST be an integer between 0 and 10080.
• FR-018: operations.stuck_run_threshold_minutes MUST be a stored configuration value only; it MUST NOT introduce auto-remediation or auto-handling behavior in this feature scope.

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
Page	Workspace Settings (admin UI)	Save; Reset setting to default (per-setting, confirmed)	N/A	N/A	N/A	N/A	N/A	Save + Cancel	Yes	View capability: read-only fields; Manage capability: editable + submit; Non-member: 404

Key Entities (include if feature involves data)

• Workspace Setting: A workspace-owned key/value configuration item with validation rules and a default.
• Audit Log Entry: An immutable record of a settings update or reset-to-default event.
• Drift Finding Type: A classification string used to identify the type of drift finding for severity mapping.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: When no settings are configured for these keys, backup retention behavior, drift severity behavior, and operations pruning behavior match the baseline in automated regression tests.
• SC-002: An authorized workspace admin can update each of the 5 settings and observe the new effective value reflected in the Workspace Settings screen immediately after save.
• SC-003: 100% of settings updates and reset-to-default actions produce an audit log entry with key, old value, and new value.
• SC-004: Invalid configuration attempts (out-of-range numbers, invalid JSON, unsupported severities) are rejected and do not change persisted settings.