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.

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

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

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

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

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

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

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

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

• 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
• 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
• T028 Run formatting for touched files with vendor/bin/sail bin pint --dirty --format agent
• 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

# 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

# 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

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