# Tasks: Queued Execution Reauthorization and Scope Continuity **Input**: Design documents from `/specs/149-queued-execution-reauthorization/` **Prerequisites**: `plan.md` (required), `spec.md` (required for user stories), `research.md`, `data-model.md`, `contracts/`, `quickstart.md` **Tests**: Runtime behavior changes in this repo require Pest coverage. This feature changes queued execution semantics, authorization continuity, Monitoring outcomes, and audit behavior, so tests are required for every user story. **Operations**: This feature reuses existing `OperationRun` records and queued work. Tasks below enforce the Ops-UX 3-surface contract, keep `OperationRun.status` and `OperationRun.outcome` service-owned via `OperationRunService`, preserve initiator-only terminal notifications, and keep blocked execution observable through canonical Monitoring routes. **RBAC**: This feature changes authorization continuity in the admin `/admin` plane and tenant-context admin surfaces. Tasks below preserve `404` for non-members or non-entitled actors, `403` for in-scope capability denial, and canonical capability-registry usage with no raw role-string checks. **UI Naming**: Blocked execution copy, run-detail text, and audit prose must keep using consistent operator-facing vocabulary such as `blocked`, `failed`, `queued`, and `View run`. **Filament UI Action Surfaces**: This feature changes backend trust semantics behind existing Filament start actions and Monitoring pages. No new action family is introduced; existing action surfaces stay intact while run outcomes and detail explanations become more precise. **Filament UI UX-001**: This feature is not a layout redesign. Existing Monitoring and start surfaces keep their current layouts. **Badges**: Blocked-versus-failed outcome rendering must continue to use centralized operation badge semantics. **Contract Artifacts**: `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/149-queued-execution-reauthorization/contracts/execution-legitimacy.schema.json` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/149-queued-execution-reauthorization/contracts/no-external-api-changes.md` are internal design contracts for the execution-legitimacy boundary and route stability, not requirements to add new public HTTP endpoints. **Organization**: Tasks are grouped by user story so each story can be implemented and tested independently. ## Phase 1: Setup (Shared Infrastructure) **Purpose**: Prepare regression targets and representative execution paths for the queued-execution hardening work. - [X] T001 [P] Create or extend the execution-core regression targets in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Operations/QueuedExecutionLegitimacyGateTest.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/QueuedExecutionMiddlewareOrderingTest.php - [X] T002 [P] Create or extend provider and inventory execution-regression targets in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Verification/ProviderExecutionReauthorizationTest.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/RunInventorySyncExecutionReauthorizationTest.php - [X] T003 [P] Create or extend restore and system-run regression targets in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/ExecuteRestoreRunExecutionReauthorizationTest.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/SystemRunBlockedExecutionNotificationTest.php - [X] T004 [P] Create or extend bulk and retry-path regression targets in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/BulkOperationExecutionReauthorizationTest.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/QueuedExecutionRetryReauthorizationTest.php --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Build the shared execution-legitimacy boundary that all user stories depend on. **⚠️ CRITICAL**: No user story work should begin until this phase is complete. - [X] T005 Create the execution-legitimacy support types in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Operations/ExecutionAuthorityMode.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Operations/ExecutionDenialClass.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Operations/ExecutionDenialReasonCode.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Operations/QueuedExecutionContext.php, and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Operations/QueuedExecutionLegitimacyDecision.php - [X] T006 Implement the canonical execution gate, including the system-authority allowlist and initial retryability mapping, in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/Operations/QueuedExecutionLegitimacyGate.php and bind any required dependencies in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Providers/AppServiceProvider.php - [X] T007 Refactor queue entry ordering in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Jobs/Middleware/TrackOperationRun.php and add /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Jobs/Middleware/EnsureQueuedExecutionLegitimate.php so legitimacy is evaluated before a run is marked `running` - [X] T008 [P] Extend blocked execution lifecycle handling in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/OperationRunService.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Badges/Domains/OperationRunOutcomeBadge.php to preserve centralized blocked-versus-failed semantics - [X] T009 [P] Add foundational unit and middleware coverage for legitimacy ordering, system-authority allowlisting, and retryability mapping in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Operations/QueuedExecutionLegitimacyGateTest.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/QueuedExecutionMiddlewareOrderingTest.php **Checkpoint**: Foundation ready. The repo has one shared execution-legitimacy boundary, and user stories can now adopt it independently. --- ## Phase 3: User Story 1 - Stop Invalid Queued Mutations Before They Start (Priority: P1) 🎯 MVP **Goal**: Ensure queued tenant-affecting work is refused before side effects when capability, scope, or tenant operability drift after dispatch. **Independent Test**: Queue representative tenant-affecting operations, change capability or tenant operability before the worker starts, and verify the jobs are blocked before any mutation work begins. ### Tests for User Story 1 - [X] T010 [P] [US1] Add actor-bound capability-loss, tenant-scope-loss, and still-legitimate allowed-path coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Verification/ProviderExecutionReauthorizationTest.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/RunInventorySyncExecutionReauthorizationTest.php - [X] T011 [P] [US1] Add tenant-non-operable, write-gate denial, and still-legitimate restore allowed-path coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/ExecuteRestoreRunExecutionReauthorizationTest.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/QueuedExecutionMiddlewareOrderingTest.php ### Implementation for User Story 1 - [X] T012 [US1] Attach execution-authority and required-capability metadata at enqueue time in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/Providers/ProviderOperationStartGate.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/Verification/StartVerification.php, and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Operations/OperationRunCapabilityResolver.php - [X] T013 [US1] Adopt the shared execution gate in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Jobs/ProviderConnectionHealthCheckJob.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Jobs/RunInventorySyncJob.php so actor-bound queued work blocks before side effects - [X] T014 [US1] Adopt the shared execution gate in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Jobs/ExecuteRestoreRunJob.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Jobs/RestoreAssignmentsJob.php so write jobs fail closed on scope, capability, and operability drift - [X] T015 [US1] Normalize job-side legitimacy hooks for queued starts and retries in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Jobs/Middleware/EnsureQueuedExecutionLegitimate.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/Operations/QueuedExecutionLegitimacyGate.php **Checkpoint**: User Story 1 is complete when representative queued jobs refuse invalid execution before any tenant-affecting side effects occur. --- ## Phase 4: User Story 2 - Understand Why A Queued Operation Was Refused (Priority: P1) **Goal**: Make blocked execution visible as an intentional policy refusal in Monitoring, audit, and terminal feedback instead of an indistinct runtime failure. **Independent Test**: Force execution-time blocking for user-initiated and initiator-null runs and verify Monitoring, audit, and notification behavior clearly identify blocked execution. ### Tests for User Story 2 - [X] T016 [P] [US2] Add blocked outcome presentation, reason-code, and normalized summary-count coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/OperationRunBlockedExecutionPresentationTest.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/TenantlessOperationRunViewerTest.php - [X] T017 [P] [US2] Add initiator-null notification, audit regression, and direct-access 404-versus-403 coverage for both /admin/operations and /admin/operations/{run} in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/SystemRunBlockedExecutionNotificationTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/QueuedExecutionAuditTrailTest.php, and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/TenantlessOperationRunViewerTest.php ### Implementation for User Story 2 - [X] T018 [US2] Extend terminal blocked-execution handling in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/OperationRunService.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Notifications/OperationRunCompleted.php so user-initiated runs keep canonical terminal feedback without ad-hoc denial notifications - [X] T019 [US2] Surface blocked execution reasons in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/pages/operations/tenantless-operation-run-viewer.blade.php - [X] T020 [US2] Normalize blocked execution audit, Monitoring copy, and summary-count-safe payload handling in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/OperationRunService.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Badges/Domains/OperationRunOutcomeBadge.php **Checkpoint**: User Story 2 is complete when blocked execution is clearly visible as policy refusal rather than generic failure across Monitoring, audit, and terminal feedback. --- ## Phase 5: User Story 3 - Enforce One Trust Contract Across Queued Job Families (Priority: P2) **Goal**: Apply one reusable execution-legitimacy contract across representative job families and retry paths instead of local one-off checks. **Independent Test**: Apply the same allowed-path and blocked-path scenarios to provider, restore, inventory, bulk, and system-authority jobs and confirm they all follow the same legitimacy and observability semantics. ### Tests for User Story 3 - [X] T021 [P] [US3] Add bulk orchestrator and retry-path contract coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/BulkOperationExecutionReauthorizationTest.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/QueuedExecutionRetryReauthorizationTest.php - [X] T022 [P] [US3] Add cross-family contract-matrix, allowed-path, and metadata-storage coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/QueuedExecutionContractMatrixTest.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Operations/QueuedExecutionLegitimacyGateTest.php ### Implementation for User Story 3 - [X] T023 [US3] Refactor the bulk execution abstractions to consume the shared legitimacy gate in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Jobs/Operations/BulkOperationOrchestratorJob.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Jobs/Operations/BulkOperationWorkerJob.php - [X] T024 [US3] Apply the shared contract to additional provider and sync families in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Jobs/ProviderInventorySyncJob.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Jobs/ProviderComplianceSnapshotJob.php, and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Jobs/SyncPoliciesJob.php - [X] T025 [US3] Apply the system-authority execution path, canonical allowlist policy source, and schema-free metadata persistence contract to scheduled runs in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Jobs/RunBackupScheduleJob.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/Operations/QueuedExecutionLegitimacyGate.php **Checkpoint**: User Story 3 is complete when representative queued job families and retries all use the same legitimacy contract and blocked outcome semantics. --- ## Phase 6: Polish & Cross-Cutting Concerns **Purpose**: Finalize contract artifacts, formatting, focused validation, and manual verification across all stories. - [X] T026 [P] Align the internal execution contract artifacts in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/149-queued-execution-reauthorization/contracts/execution-legitimacy.schema.json and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/149-queued-execution-reauthorization/contracts/no-external-api-changes.md with the final implementation decisions - [X] T027 Run the focused Pest suites from /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/149-queued-execution-reauthorization/quickstart.md covering /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Operations/QueuedExecutionLegitimacyGateTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/QueuedExecutionMiddlewareOrderingTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Verification/ProviderExecutionReauthorizationTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/RunInventorySyncExecutionReauthorizationTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/ExecuteRestoreRunExecutionReauthorizationTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/SystemRunBlockedExecutionNotificationTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/BulkOperationExecutionReauthorizationTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/QueuedExecutionRetryReauthorizationTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/QueuedExecutionContractMatrixTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/OperationRunBlockedExecutionPresentationTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/QueuedExecutionAuditTrailTest.php, and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/TenantlessOperationRunViewerTest.php - [X] T028 Run formatting for touched files with `vendor/bin/sail bin pint --dirty --format agent` - [X] T029 [P] Validate the manual smoke checklist in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/149-queued-execution-reauthorization/quickstart.md against /admin/operations and representative queued start surfaces in the admin panel --- ## Dependencies & Execution Order ### Phase Dependencies - **Phase 1: Setup** has no dependencies and can start immediately. - **Phase 2: Foundational** depends on Phase 1 and blocks all user story work. - **Phase 3: User Story 1** depends on Phase 2 and delivers the MVP. - **Phase 4: User Story 2** depends on Phase 2 and is best delivered after User Story 1 because it reuses the same blocked-execution contract. - **Phase 5: User Story 3** depends on Phase 2 and benefits from the core legitimacy gate and blocked outcome semantics from User Stories 1 and 2. - **Phase 6: Polish** depends on all desired user stories being complete. ### User Story Dependencies - **User Story 1 (P1)** can start immediately after the foundational phase and is the MVP slice. - **User Story 2 (P1)** can start after the foundational phase but should follow User Story 1 so blocked execution already exists as a real runtime path. - **User Story 3 (P2)** depends on the foundational phase and builds on the contract established in User Stories 1 and 2. ### Within Each User Story - Write or extend tests first and confirm they fail before implementation. - Shared support-layer changes land before job-family adoption. - Job-family adoption should precede Monitoring copy and manual validation updates. - Story-level regression coverage should pass before moving to the next priority story. ### Parallel Opportunities - `T001`, `T002`, `T003`, and `T004` can run in parallel because they prepare separate regression targets. - `T008` and `T009` can run in parallel after `T005`, `T006`, and `T007` define the shared contract and middleware ordering. - `T010` and `T011` can run in parallel within User Story 1. - `T016` and `T017` can run in parallel within User Story 2. - `T021` and `T022` can run in parallel within User Story 3. - `T026` and `T029` can run in parallel after implementation is complete. --- ## Parallel Example: User Story 1 ```bash # Run the P1 regression additions together: Task: "Add actor-bound capability-loss and tenant-scope-loss coverage in tests/Feature/Verification/ProviderExecutionReauthorizationTest.php and tests/Feature/Operations/RunInventorySyncExecutionReauthorizationTest.php" Task: "Add tenant-non-operable, write-gate denial-reason, and still-legitimate restore allowed-path coverage in tests/Feature/Operations/ExecuteRestoreRunExecutionReauthorizationTest.php and tests/Feature/Operations/QueuedExecutionMiddlewareOrderingTest.php" ``` ## Parallel Example: User Story 2 ```bash # Split Monitoring-detail and initiator-null coverage: Task: "Add blocked outcome presentation, reason-code, and normalized summary-count coverage in tests/Feature/Operations/OperationRunBlockedExecutionPresentationTest.php and tests/Feature/Operations/TenantlessOperationRunViewerTest.php" Task: "Add initiator-null notification, audit regression, and direct-access 404-versus-403 coverage for both /admin/operations and /admin/operations/{run} in tests/Feature/Operations/SystemRunBlockedExecutionNotificationTest.php, tests/Feature/Operations/QueuedExecutionAuditTrailTest.php, and tests/Feature/Operations/TenantlessOperationRunViewerTest.php" ``` ## Parallel Example: User Story 3 ```bash # Split bulk/retry and cross-family contract validation: Task: "Add bulk orchestrator and retry-path contract coverage in tests/Feature/Operations/BulkOperationExecutionReauthorizationTest.php and tests/Feature/Operations/QueuedExecutionRetryReauthorizationTest.php" Task: "Add cross-family contract-matrix coverage in tests/Feature/Operations/QueuedExecutionContractMatrixTest.php and tests/Unit/Operations/QueuedExecutionLegitimacyGateTest.php" ``` --- ## Implementation Strategy ### MVP First 1. Complete Phase 1: Setup. 2. Complete Phase 2: Foundational. 3. Complete Phase 3: User Story 1. 4. **Stop and validate** that representative queued jobs now fail closed before side effects when legitimacy drifts. ### Incremental Delivery 1. Deliver User Story 1 to establish the runtime safety boundary. 2. Deliver User Story 2 to make blocked execution intelligible in Monitoring, audit, and terminal feedback. 3. Deliver User Story 3 to propagate the same contract across representative job families and retries. 4. Finish with Phase 6 regression, formatting, and manual validation. ### Team Strategy 1. One engineer owns the shared support-layer and middleware work in `app/Support/Operations`, `app/Services/Operations`, and `app/Jobs/Middleware`. 2. A second engineer can prepare the provider, inventory, and restore regression coverage in parallel once the shared contract shape is clear. 3. Bulk and scheduled-run adoption can proceed as a separate stream after the foundational contract lands. --- ## Notes - `[P]` tasks touch separate files and can be executed in parallel. - Each user story remains independently testable after the foundational phase. - This feature does not add schema changes, public HTTP routes, Graph contract-registry entries, new assets, or new Filament panels. - Keep blocked execution represented as a canonical run outcome, not as a silent skip or a generic failure placeholder.