---

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.

- [ ] 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 no call sites opt into queued DB notifications in app/Services/OperationRunService.php (remove/forbid emitQueuedNotification:true usage)

**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 ->update([...]) containing status/outcome; 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**: Keep docs and developer workflow aligned with final test locations.

- [ ] T028 [P] Update quickstart commands/paths if needed in specs/110-ops-ux-enforcement/quickstart.md

---

## 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