---

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/`

- plan.md: [specs/110-ops-ux-enforcement/plan.md](specs/110-ops-ux-enforcement/plan.md)
- spec.md: [specs/110-ops-ux-enforcement/spec.md](specs/110-ops-ux-enforcement/spec.md)
- research.md: [specs/110-ops-ux-enforcement/research.md](specs/110-ops-ux-enforcement/research.md)
- data-model.md: [specs/110-ops-ux-enforcement/data-model.md](specs/110-ops-ux-enforcement/data-model.md)
- contracts/: [specs/110-ops-ux-enforcement/contracts/](specs/110-ops-ux-enforcement/contracts/)

**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.

- [X] 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”.

- [X] T002 Update queued notification defaults in app/Services/OperationRunService.php (dispatchOrFail + enqueue helpers default emitQueuedNotification=false)
- [X] 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)

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

### Implementation

- [X] T006 [US1] Refactor terminal transition in app/Services/Inventory/InventorySyncService.php to use OperationRunService::updateRun()
- [X] T007 [US1] Refactor terminal transition in app/Jobs/ApplyBackupScheduleRetentionJob.php to use OperationRunService::updateRun()
- [X] 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)

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

### Implementation (Jobs)

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

### Implementation (Start surfaces / Filament)

- [X] T016 [P] [US2] Replace queued DB notification with toast-only queued feedback in app/Filament/Resources/PolicyResource.php (remove sendToDatabase for queued ops)
- [X] T017 [P] [US2] Replace queued DB notification with toast-only queued feedback in app/Filament/Resources/BackupScheduleResource.php (remove sendToDatabase for queued ops)
- [X] T018 [P] [US2] Replace queued DB notification with toast-only queued feedback in app/Filament/Resources/TenantResource.php (remove sendToDatabase for queued ops)
- [X] T019 [P] [US2] Replace queued DB notification with toast-only queued feedback in app/Filament/Resources/PolicyVersionResource.php (remove sendToDatabase for queued ops)
- [X] 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)

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

### Implementation

- [X] T021 [US3] Remove legacy notification invocation in app/Jobs/ExecuteRestoreRunJob.php
- [X] 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

- [X] 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)
- [X] 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)
- [X] 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(...)`.

- [X] T026 [P] [US5] Add OperationUxPresenter::alreadyQueuedToast(...) helper in app/Support/OpsUx/OperationUxPresenter.php
- [X] 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).

- [X] T028 [P] Update quickstart commands/paths if needed in specs/110-ops-ux-enforcement/quickstart.md
- [X] T032 Run focused Ops-UX regression pack (including `tests/Feature/OpsUx/Regression/*`) and confirm green (SC-006 / DoD)
- [X] T033 Run constitution guard tests (`tests/Feature/OpsUx/Constitution/*`) and verify actionable failure output on synthetic violation + green on clean codebase (SC-005)
- [X] T034 Run full test suite (or CI-equivalent command used by this repo) and confirm green (DoD)
- [X] 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.

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

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

## Parallel Execution Examples

### US1 (tests + implementation)

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

### US2 (jobs + start surfaces)

```bash
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)

```bash
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
