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

Implementation Plan: 098 — Settings Slices v1 (Backup + Drift + Operations)

Branch: 098-settings-slices-v1-backup-drift-ops | Date: 2026-02-16 | Spec: specs/098-settings-slices-v1-backup-drift-ops/spec.md Input: Feature specification from specs/098-settings-slices-v1-backup-drift-ops/spec.md

Summary

Extend the existing Settings Foundation to expose five additional workspace-level keys on the Workspace Settings page, with strict validation, per-setting reset-to-default (confirmed), and audit logging per key changed.

Apply those settings to three behavior paths:

• Backup retention: enforce a workspace-configurable retention default and a workspace-configurable retention floor (effective values clamped up to the floor).
• Drift severities: allow workspace-configurable finding_type → severity mapping (default medium, values normalized).
• Operations: allow workspace-configurable operation run retention days for pruning and store a “stuck run threshold” value (storage only; no new auto-remediation behavior).

Technical Context

Language/Version: PHP 8.4 (Laravel 12) Primary Dependencies: Filament v5, Livewire v4, Laravel Sail Storage: PostgreSQL (Sail local) Testing: Pest v4 (PHPUnit 12 runner) Target Platform: Web app (Filament admin panel) Project Type: Laravel monolith (Filament pages + services + jobs) Performance Goals: Settings resolution should remain request-local cached (no repeated DB reads per key within a request). Constraints:

• DB-only rendering for settings UI (no Graph calls as a render side-effect)
• Strict workspace isolation (non-member 404)
• Capability-gated mutations (member without capability 403)
• Destructive-like resets require confirmation
• Audit each successful mutation; multi-key save produces one audit entry per key changed

Baselines to Preserve (When Unset)

These are the “no settings configured” behaviors that must remain unchanged and covered by regression tests.

Record the baseline values explicitly so “no change” remains mechanically verifiable over time:

• Backup retention default:
  • When a schedule has no retention_keep_last, the job resolves backup.retention_keep_last_default and falls back to 30 if unresolved/non-numeric.
  • Current clamp behavior: values < 1 are clamped up to 1.
  • Source: app/Jobs/ApplyBackupScheduleRetentionJob.php.
  • Current system default: backup.retention_keep_last_default is 30 in app/Support/Settings/SettingsRegistry.php.
• Drift default severity:
  • Drift findings currently default to Finding::SEVERITY_MEDIUM.
  • Source: app/Services/Drift/DriftFindingGenerator.php.
• Operation run pruning:
  • Prune job default retention is 90 days (new PruneOldOperationRunsJob() with default constructor argument).
  • Source: app/Jobs/PruneOldOperationRunsJob.php and schedule in routes/console.php.
• “Stuck run threshold”:
  • No baseline behavior exists today; for this feature it remains storage-only (must not introduce auto-remediation).

Constitution Check

GATE: Must pass before implementation. Re-check after design/edits.

• DB-only rendering: PASS (Workspace Settings UI is DB-only).
• Graph contract path: PASS (no Graph calls introduced).
• RBAC-UX semantics: PASS-BY-DESIGN (non-member 404; member missing capability 403; server-side still authoritative).
• Destructive-like confirmation: PASS-BY-DESIGN (per-setting reset actions must require confirmation).
• Auditability: PASS-BY-DESIGN (settings writes are audited per key).
• Filament Action Surface Contract: PASS (page-level action surface is explicitly declared in spec via UI Action Matrix).

Project Structure

Documentation (this feature)

specs/098-settings-slices-v1-backup-drift-ops/
├── plan.md
├── spec.md
├── tasks.md
└── checklists/
    └── requirements.md

Source Code (repository root)

app/
├── Filament/Pages/Settings/WorkspaceSettings.php
├── Jobs/
│   ├── ApplyBackupScheduleRetentionJob.php
│   └── PruneOldOperationRunsJob.php
├── Models/Finding.php
├── Services/Drift/DriftFindingGenerator.php
└── Support/
    ├── Badges/Domains/FindingSeverityBadge.php
    └── Settings/SettingsRegistry.php

routes/console.php

tests/Feature/
├── BackupScheduling/BackupScheduleLifecycleTest.php
├── Drift/DriftPolicySnapshotDriftDetectionTest.php
├── Scheduling/PruneOldOperationRunsScheduleTest.php
└── SettingsFoundation/
    ├── WorkspaceSettingsManageTest.php
    ├── WorkspaceSettingsViewOnlyTest.php
    └── WorkspaceSettingsNonMemberNotFoundTest.php

Structure Decision: Use existing Laravel structure only. No new top-level directories.

Plan Phases

Phase 0 — Align the Registry + UI primitives (shared)

• Ensure Settings registry rules match the spec (notably the backup max bounds).
• Refactor the Workspace Settings page to support:
  • Per-setting reset actions (no global reset)
  • Unset inputs with helper text showing the effective/default value
  • Save semantics that can “unset” (delete override) for a single key
• Update the existing SettingsFoundation tests to reflect the new UX primitives.

Phase 1 — US1 Backup slice (MVP)

• Add backup.retention_min_floor to the registry and UI.
• Apply floor clamping in the retention job to both schedule overrides and workspace defaults.
• Add/extend BackupScheduling + SettingsFoundation tests to cover both baseline behavior and clamping.

Phase 2 — US2 Drift slice

• Add drift.severity_mapping to the registry and UI with strict JSON shape validation.
• Normalize severity values to lowercase on save; reject unsupported severities.
• Apply mapping in drift finding generation with default medium fallback.
• Add drift tests for default + mapped severity, and settings validation tests.

Phase 3 — US3 Operations slice

• Add operations keys to the registry and UI.
• Wire pruning job to use the configured retention days when set (baseline otherwise).
• Ensure “stuck threshold” is stored only (no new behavior in this feature).
• Add pruning job/schedule tests and settings persistence tests.

Phase 4 — Format + focused regression

• Run Pint for touched files.
• Run the focused test set for SettingsFoundation + BackupScheduling + Drift + Scheduling.

Complexity Tracking

No constitution violations are required for this feature.