TenantAtlas/specs/149-queued-execution-reauthorization/tasks.md

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