ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
0de0494426
TenantAtlas/specs/110-ops-ux-enforcement/tasks.md
Ahmed Darrazi 0de0494426 feat(ops-ux): enterprise start/dedup standard
2026-02-24 10:15:34 +01:00

11 KiB
Raw Blame History

description
Executable task list for Ops-UX Enforcement & Cleanup

Tasks: Ops-UX Enforcement & Cleanup (Enterprise Standard Rollout)

Input: Design documents from /specs/110-ops-ux-enforcement/

Tests: REQUIRED (Pest) — both guard tests and focused regressions.

Phase 1: Setup (Shared Test Infrastructure)

Purpose: Create minimal shared helpers for guard tests and keep failure output consistent.

  • T001 [P] Add source scanning helper in tests/Support/OpsUx/SourceFileScanner.php

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Cross-cutting invariants that must be true before user story work can be considered “done”.

  • T002 Update queued notification defaults in app/Services/OperationRunService.php (dispatchOrFail + enqueue helpers default emitQueuedNotification=false)
  • T003 Confirm repo-wide call sites do not opt into queued DB notifications (remove/forbid emitQueuedNotification: true usages in app/**)

Checkpoint: No queued/running DB notifications can be emitted by default.

Phase 3: User Story 1 — No Silent Completions (Priority: P1) 🎯 MVP

Goal: Terminal transitions always go through OperationRunService, producing exactly one terminal OperationRunCompleted notification for initiators.

Independent Test: Inventory sync + retention flow transitions to terminal and persists exactly one OperationRunCompleted notification for the initiator; system runs persist none.

Tests (write first)

  • T004 [P] [US1] Add inventory sync terminal notification regression test in tests/Feature/OpsUx/Regression/InventorySyncTerminalNotificationTest.php
  • T005 [P] [US1] Add retention terminal notification regression test in tests/Feature/OpsUx/Regression/BackupRetentionTerminalNotificationTest.php

Implementation

  • T006 [US1] Refactor terminal transition in app/Services/Inventory/InventorySyncService.php to use OperationRunService::updateRun()
  • T007 [US1] Refactor terminal transition in app/Jobs/ApplyBackupScheduleRetentionJob.php to use OperationRunService::updateRun()
  • T008 [US1] Refactor OperationRun status/outcome update in app/Console/Commands/TenantpilotBackfillWorkspaceIds.php to use OperationRunService::updateRun() (initiator may be null)

Checkpoint: US1 regressions pass, with no silent completions.

Phase 4: User Story 2 — No Notification Spam (Priority: P1)

Goal: Remove job-level queued/completion DB notifications and eliminate queued DB notifications from start surfaces.

Independent Test: Backup schedule run + representative bulk flow complete with exactly one terminal OperationRunCompleted and zero queued/running DB notifications.

Tests (write first)

  • T009 [P] [US2] Add backup schedule run notification regression test in tests/Feature/OpsUx/Regression/BackupScheduleRunNotificationTest.php
  • T010 [P] [US2] Add bulk job “abort/circuit-break” regression test in tests/Feature/OpsUx/Regression/BulkJobCircuitBreakerTest.php

Implementation (Jobs)

  • T011 [P] [US2] Remove queued + custom finished DB notifications in app/Jobs/RunBackupScheduleJob.php
  • T012 [P] [US2] Remove completion/abort sendToDatabase branches in app/Jobs/BulkPolicyExportJob.php
  • T013 [P] [US2] Remove completion/abort sendToDatabase branches in app/Jobs/BulkRestoreRunForceDeleteJob.php
  • T029 [P] [US2] Remove completion/abort sendToDatabase branches in app/Jobs/BulkRestoreRunRestoreJob.php
  • T030 [P] [US2] Remove completion/abort sendToDatabase branches in app/Jobs/BulkPolicyUnignoreJob.php
  • T014 [P] [US2] Remove custom completion/failure DB notifications in app/Jobs/AddPoliciesToBackupSetJob.php
  • T015 [P] [US2] Remove custom completion/failure DB notifications in app/Jobs/RemovePoliciesFromBackupSetJob.php

Implementation (Start surfaces / Filament)

  • T016 [P] [US2] Replace queued DB notification with toast-only queued feedback in app/Filament/Resources/PolicyResource.php (remove sendToDatabase for queued ops)
  • T017 [P] [US2] Replace queued DB notification with toast-only queued feedback in app/Filament/Resources/BackupScheduleResource.php (remove sendToDatabase for queued ops)
  • T018 [P] [US2] Replace queued DB notification with toast-only queued feedback in app/Filament/Resources/TenantResource.php (remove sendToDatabase for queued ops)
  • T019 [P] [US2] Replace queued DB notification with toast-only queued feedback in app/Filament/Resources/PolicyVersionResource.php (remove sendToDatabase for queued ops)
  • T031 [P] [US2] Replace queued DB notification with toast-only queued feedback in app/Filament/Resources/EntraGroupResource/Pages/ListEntraGroups.php (remove sendToDatabase for queued ops)

Checkpoint: US2 regressions pass and notifications remain terminal-only.

Phase 5: User Story 3 — Legacy Notification Removed (Priority: P1)

Goal: Remove the out-of-system RunStatusChangedNotification and rely exclusively on canonical terminal OperationRunCompleted.

Independent Test: Restore run completion produces exactly one OperationRunCompleted notification and there are zero references to RunStatusChangedNotification in app/ and tests/.

Tests (write first)

  • T020 [P] [US3] Add restore run terminal notification regression test in tests/Feature/OpsUx/Regression/RestoreRunTerminalNotificationTest.php

Implementation

  • T021 [US3] Remove legacy notification invocation in app/Jobs/ExecuteRestoreRunJob.php
  • T022 [US3] Delete legacy notification class app/Notifications/RunStatusChangedNotification.php

Checkpoint: US3 regression passes; no legacy notification remains.

Phase 6: User Story 4 — Regression Guards Enforce the Constitution (Priority: P1)

Goal: CI guard tests fail fast when forbidden patterns reappear.

Independent Test: Guards fail with actionable output on a synthetic violation and pass on a clean codebase.

Guard tests

  • T023 [P] [US4] Implement Guard A in tests/Feature/OpsUx/Constitution/DirectStatusTransitionGuardTest.php (scan app/** for forbidden status/outcome transitions: ->update([...]) arrays, direct ->status/->outcome assignments, and query/bulk updates; exclude app/Services/OperationRunService.php; print snippet)
  • T024 [P] [US4] Implement Guard B in tests/Feature/OpsUx/Constitution/JobDbNotificationGuardTest.php (scan app/** for OperationRun signal + DB notify emission; allowlist app/Services/OperationRunService.php and app/Notifications/OperationRunCompleted.php)
  • T025 [P] [US4] Implement Guard C in tests/Feature/OpsUx/Constitution/LegacyNotificationGuardTest.php (scan app/** and tests/** for RunStatusChangedNotification)

Checkpoint: Guard tests pass green and provide clear failure output.

Phase 7: User Story 5 — Canonical "Already Queued" Toast (Priority: P2)

Goal: Dedup “already queued” messaging is canonical and consistent.

Independent Test: Trigger dedup path and confirm toast uses OperationUxPresenter::alreadyQueuedToast(...).

  • T026 [P] [US5] Add OperationUxPresenter::alreadyQueuedToast(...) helper in app/Support/OpsUx/OperationUxPresenter.php
  • T027 [US5] Migrate dedup toast to canonical helper in app/Livewire/BackupSetPolicyPickerTable.php

Phase 8: Polish & Cross-Cutting Concerns

Purpose: Final documentation alignment plus execution validation (guards, regressions, full suite, formatting).

  • T028 [P] Update quickstart commands/paths if needed in specs/110-ops-ux-enforcement/quickstart.md
  • T032 Run focused Ops-UX regression pack (including tests/Feature/OpsUx/Regression/*) and confirm green (SC-006 / DoD)
  • T033 Run constitution guard tests (tests/Feature/OpsUx/Constitution/*) and verify actionable failure output on synthetic violation + green on clean codebase (SC-005)
  • T034 Run full test suite (or CI-equivalent command used by this repo) and confirm green (DoD)
  • T035 [P] Run Pint for touched files via Sail (./vendor/bin/sail bin pint --dirty) and confirm clean (DoD)

Phase 9: Follow-up — Repo-wide Start/Dedup Toast Standardization

Purpose: Ensure all remaining Filament start/dedup surfaces use canonical Ops-UX toasts and trigger immediate progress refresh.

  • T036 Standardize tenant verification start/dedup toasts + progress refresh (Tenant list row, tenant view header, verification widget)
  • T037 Standardize review pack generation widget to canonical queued/already queued toasts + view-run action
  • T038 Ensure admin roles scan creates/dedupes OperationRun at enqueue time + canonical toasts + progress refresh
  • T039 Standardize backup set removal dedupe notifications to canonical already queued toast + progress refresh
  • T040 Standardize restore run idempotency “already queued” to canonical already queued toast (with view-run when available)
  • T041 Standardize policy bulk delete queued/dedup toast to canonical queued/already queued + progress refresh
  • T042 Standardize onboarding wizard verification + bootstrap start/dedup toasts + progress refresh

Dependencies & Execution Order

User Story Completion Order

  • US1 → US2 → US3 → US4 → US5

Rationale:

  • US1–US3 remove known violations so the guard suite (US4) can pass on a clean codebase.
  • US5 is optional polish and can land after enforcement is stable.

Dependency Graph

Phase 1 (Setup) ─┬─> Phase 2 (Foundational) ─┬─> US1 ─┬─> US2 ─┬─> US3 ─┬─> US4 ─┬─> US5
                 │                           │        │        │        │        └─> Polish
                 └───────────────────────────┴────────┴────────┴────────┴───────────────

Parallel Execution Examples

US1 (tests + implementation)

T004: tests/Feature/OpsUx/Regression/InventorySyncTerminalNotificationTest.php
T005: tests/Feature/OpsUx/Regression/BackupRetentionTerminalNotificationTest.php

US2 (jobs + start surfaces)

T011: app/Jobs/RunBackupScheduleJob.php
T012: app/Jobs/BulkPolicyExportJob.php
T013: app/Jobs/BulkRestoreRunForceDeleteJob.php
T014: app/Jobs/AddPoliciesToBackupSetJob.php
T015: app/Jobs/RemovePoliciesFromBackupSetJob.php
T016–T019: app/Filament/Resources/*Resource.php

US4 (guards)

T023: tests/Feature/OpsUx/Constitution/DirectStatusTransitionGuardTest.php
T024: tests/Feature/OpsUx/Constitution/JobDbNotificationGuardTest.php
T025: tests/Feature/OpsUx/Constitution/LegacyNotificationGuardTest.php

Implementation Strategy

MVP Scope (recommended)

  • Foundational (Phase 2) + US1 only.

This yields the highest-value guarantee quickly: “no silent completions” and exactly-once terminal notifications for the most critical flows.

Incremental Delivery

  1. Foundational → US1 → validate
  2. US2 → validate
  3. US3 → validate
  4. US4 guards → enforce
  5. US5 polish