# Tasks: Operation Run Active-State Visibility & Stale Escalation **Input**: Design documents from `/specs/233-stale-run-visibility/` **Prerequisites**: `plan.md` (required), `spec.md` (required for user stories), `research.md`, `data-model.md`, `contracts/operation-run-active-state-visibility.logical.openapi.yaml`, `quickstart.md` **Tests**: Required. This feature changes runtime behavior across tenant progress surfaces, tenant dashboard summaries, workspace summaries, and canonical monitoring detail, so Pest coverage must be added or updated in `apps/platform/tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php`, `apps/platform/tests/Feature/OpsUx/ProgressWidgetFiltersTest.php`, `apps/platform/tests/Feature/OpsUx/ProgressWidgetOverflowTest.php`, `apps/platform/tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`, `apps/platform/tests/Feature/Filament/DashboardKpisWidgetTest.php`, `apps/platform/tests/Feature/Filament/NeedsAttentionWidgetTest.php`, `apps/platform/tests/Feature/Filament/WorkspaceOverviewOperationsTest.php`, `apps/platform/tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php`, `apps/platform/tests/Feature/Monitoring/MonitoringOperationsTest.php`, `apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php`, `apps/platform/tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`, `apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php`, `apps/platform/tests/Feature/RunAuthorizationTenantIsolationTest.php`, and `apps/platform/tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php`. **Operations**: No new `OperationRun` is introduced. Existing lifecycle truth, reconciliation, toast/progress/terminal notification behavior, and service-owned status/outcome transitions must remain unchanged. **RBAC**: The feature stays in the admin plane (`/admin` and `/admin/t/{tenant}/...`). It must preserve current tenant-entitlement and workspace-entitlement behavior, including non-member `404`, in-scope capability denial semantics, and tenant-safe summaries with no cross-tenant leakage. **UI / Surface Guardrails**: The changed surfaces are native Filament widgets/resources/pages plus one existing Livewire progress component. The feature keeps `monitoring-state-page` coverage for canonical monitoring surfaces, uses `standard-native-filament` relief elsewhere, and remains `review-mandatory` because multiple existing operator surfaces must converge on the same truth. **Filament UI Action Surfaces**: `RecentOperationsSummary`, tenant dashboard widgets, `OperationRunResource`, and `TenantlessOperationRunViewer` keep their existing inspect/open model. No new header, row, bulk, retry, cancel, or destructive actions are introduced. **Badges**: Status-like semantics must stay on `BadgeCatalog` / `BadgeRenderer` and existing shared `OperationRun` presenter paths. No page-local stale badge mapping is allowed. **Organization**: Tasks are grouped by user story so each slice is independently implementable and testable. Recommended delivery order is `US1 -> US2 -> US3` because tenant-surface honesty is the most urgent gap, canonical list scanability builds on the same truth, and detail-surface confirmation should close last against the final compact-surface semantics. ## Test Governance Checklist - [X] Lane assignment is named and is the narrowest sufficient proof for the changed behavior. - [X] New or changed tests stay in the smallest honest family, and any heavy-governance or browser addition is explicit. - [X] Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented. - [X] Planned validation commands cover the change without pulling in unrelated lane cost. - [X] The declared surface test profile or `standard-native-filament` relief is explicit. - [X] Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR. ## Phase 1: Setup (Shared Surface Scaffolding) **Purpose**: Prepare the focused regression surfaces that will prove fresh-versus-stale semantics before runtime files are edited. - [X] T001 [P] Extend stale-versus-fresh progress-overlay scaffolding in `apps/platform/tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php`, `apps/platform/tests/Feature/OpsUx/ProgressWidgetFiltersTest.php`, and `apps/platform/tests/Feature/OpsUx/ProgressWidgetOverflowTest.php` - [X] T002 [P] Extend tenant dashboard and tenant-summary semantics scaffolding in `apps/platform/tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`, `apps/platform/tests/Feature/Filament/DashboardKpisWidgetTest.php`, `apps/platform/tests/Feature/Filament/NeedsAttentionWidgetTest.php`, and `apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php` - [X] T003 [P] Extend workspace monitoring and visibility-safety scaffolding in `apps/platform/tests/Feature/Filament/WorkspaceOverviewOperationsTest.php`, `apps/platform/tests/Feature/Monitoring/MonitoringOperationsTest.php`, `apps/platform/tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php`, `apps/platform/tests/Feature/RunAuthorizationTenantIsolationTest.php`, and `apps/platform/tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php` - [X] T004 [P] Extend canonical detail and drill-through continuity scaffolding in `apps/platform/tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php` and `apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php` **Checkpoint**: Focused tenant, workspace, and canonical test surfaces are ready to fail on stale-hidden regressions before implementation begins. --- ## Phase 2: Foundational (Blocking Truth And Shared Contract) **Purpose**: Stabilize the one freshness-to-surface contract before any individual surface is changed. **Critical**: No user story work should begin until this phase is complete. - [X] T005 Freeze the canonical stale/fresh truth inputs and any needed thin derived adapter boundaries in `apps/platform/app/Models/OperationRun.php`, `apps/platform/app/Support/Operations/OperationRunFreshnessState.php`, `apps/platform/app/Support/OpsUx/OperationUxPresenter.php`, and `apps/platform/app/Support/OpsUx/ActiveRuns.php` - [X] T006 [P] Refresh the feature contract artifacts in `specs/233-stale-run-visibility/contracts/operation-run-active-state-visibility.logical.openapi.yaml` and `specs/233-stale-run-visibility/quickstart.md` so implementation and review language stay aligned with the finalized shared truth path **Checkpoint**: The feature has one agreed freshness/problem-class/presenter contract and the docs match that contract before surface-by-surface retrofits begin. --- ## Phase 3: User Story 1 - See unhealthy tenant activity without opening monitoring first (Priority: P1) 🎯 MVP **Goal**: Tenant-scoped dashboard and progress surfaces distinguish healthy active work from late or likely stuck work without inventing a second stale heuristic. **Independent Test**: Seed fresh and stale tenant-visible queued/running runs, render tenant dashboard and progress surfaces, and verify that healthy work stays calm while stale-active work remains visible and elevated until the run becomes terminal. ### Tests for User Story 1 - [X] T007 [P] [US1] Add fresh-versus-stale tenant progress assertions, including polling continuity while only stale-active runs remain, in `apps/platform/tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php`, `apps/platform/tests/Feature/OpsUx/ProgressWidgetFiltersTest.php`, and `apps/platform/tests/Feature/OpsUx/ProgressWidgetOverflowTest.php` - [X] T008 [P] [US1] Add tenant summary and tenant dashboard copy/assertion coverage for calm-versus-elevated active work in `apps/platform/tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`, `apps/platform/tests/Feature/Filament/DashboardKpisWidgetTest.php`, `apps/platform/tests/Feature/Filament/NeedsAttentionWidgetTest.php`, and `apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php` ### Implementation for User Story 1 - [X] T009 [P] [US1] Update stale-active visibility and polling semantics in `apps/platform/app/Support/OpsUx/ActiveRuns.php`, `apps/platform/app/Livewire/BulkOperationProgress.php`, `apps/platform/resources/views/livewire/bulk-operation-progress.blade.php`, and `apps/platform/resources/views/livewire/bulk-operation-progress-wrapper.blade.php` - [X] T010 [P] [US1] Align tenant activity summaries with the shared presenter/badge truth in `apps/platform/app/Filament/Widgets/Tenant/RecentOperationsSummary.php`, `apps/platform/resources/views/filament/widgets/tenant/recent-operations-summary.blade.php`, `apps/platform/app/Filament/Widgets/Dashboard/DashboardKpis.php`, and `apps/platform/app/Filament/Widgets/Dashboard/NeedsAttention.php` - [X] T011 [US1] Tighten tenant-surface copy and density handling in `apps/platform/app/Support/OpsUx/OperationUxPresenter.php` and any touched shared badge mappings in `apps/platform/app/Support/Badges/Domains/OperationRunStatusBadge.php` without adding a second semantic framework - [X] T012 [US1] Run the US1 tenant-surface verification flow from `specs/233-stale-run-visibility/quickstart.md` **Checkpoint**: User Story 1 is independently functional and tenant operators can see unhealthy active work before opening canonical monitoring. --- ## Phase 4: User Story 2 - Scan problematic active runs in the canonical operations list (Priority: P1) **Goal**: Workspace monitoring rows and workspace recent-operation summaries make problematic active runs obvious at scan time without falsely escalating fresh work. **Independent Test**: Seed a mixed slice of fresh and stale active runs across visible tenants, open workspace summaries and `/admin/operations`, and verify that stale-active rows are immediately distinguishable while fresh active rows remain calm. ### Tests for User Story 2 - [X] T013 [P] [US2] Add workspace summary, recency, and visibility-safety assertions for fresh-versus-stale active work in `apps/platform/tests/Feature/Filament/WorkspaceOverviewOperationsTest.php`, `apps/platform/tests/Feature/Monitoring/MonitoringOperationsTest.php`, `apps/platform/tests/Feature/RunAuthorizationTenantIsolationTest.php`, and `apps/platform/tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php` - [X] T014 [P] [US2] Add canonical operations-list assertions for row-level stale-active scanability and tenant-prefilter continuity in `apps/platform/tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php` and `apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php` ### Implementation for User Story 2 - [X] T015 [P] [US2] Align workspace summary payloads and view rendering in `apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php`, `apps/platform/app/Filament/Widgets/Workspace/WorkspaceRecentOperations.php`, and `apps/platform/resources/views/filament/widgets/workspace/workspace-recent-operations.blade.php` - [X] T016 [P] [US2] Tighten canonical list scanability and stale-active row semantics in `apps/platform/app/Filament/Widgets/Dashboard/RecentOperations.php` and `apps/platform/app/Filament/Resources/OperationRunResource.php` - [X] T017 [US2] Reconcile any remaining stale-active badge/copy differences across workspace and canonical list surfaces in `apps/platform/app/Support/OpsUx/OperationUxPresenter.php` and `apps/platform/app/Support/Badges/Domains/OperationRunStatusBadge.php` - [X] T018 [US2] Run the US2 workspace-list verification flow from `specs/233-stale-run-visibility/quickstart.md` **Checkpoint**: User Story 2 is independently functional and workspace operators can scan the canonical monitoring list for unhealthy active work without opening every row. --- ## Phase 5: User Story 3 - Keep compact surfaces aligned with canonical run detail (Priority: P2) **Goal**: Canonical run detail confirms the same active-state meaning that compact tenant and workspace surfaces already communicate, including terminal transitions and stale lineage. **Independent Test**: Navigate from compact tenant/workspace surfaces into canonical run detail for fresh, stale, and reconciled-terminal runs, then verify that the top summary preserves the same meaning before deeper diagnostics render. ### Tests for User Story 3 - [X] T019 [P] [US3] Add canonical detail summary and stale-lineage assertions in `apps/platform/tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php` and `apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php` - [X] T020 [P] [US3] Add refresh-boundary and terminal-transition consistency assertions spanning compact-to-detail flows in `apps/platform/tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php` and `apps/platform/tests/Feature/Monitoring/MonitoringOperationsTest.php` ### Implementation for User Story 3 - [X] T021 [P] [US3] Align canonical detail summary copy and decision-zone truth in `apps/platform/app/Filament/Resources/OperationRunResource.php` and `apps/platform/app/Support/OpsUx/OperationUxPresenter.php` - [X] T022 [US3] Align tenantless canonical viewer summary behavior and drill-through continuity in `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php` and any touched related monitoring helpers under `apps/platform/app/Support/OperationRunLinks.php` - [X] T023 [US3] Run the US3 compact-to-detail verification flow from `specs/233-stale-run-visibility/quickstart.md` **Checkpoint**: User Story 3 is independently functional and canonical run detail confirms, rather than contradicts, the compact active-state meaning. --- ## Phase 6: Polish & Cross-Cutting Concerns **Purpose**: Finalize documentation, formatting, and focused validation for the whole feature without widening scope. - [X] T024 [P] Refresh `specs/233-stale-run-visibility/plan.md`, `specs/233-stale-run-visibility/research.md`, and `specs/233-stale-run-visibility/data-model.md` if implementation proves a thinner shared contract or adjusts touched file scope - [X] T025 Run formatting on touched application and test files with `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` - [X] T026 Run the focused Pest suite from `specs/233-stale-run-visibility/quickstart.md` against `apps/platform/tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php`, `apps/platform/tests/Feature/OpsUx/ProgressWidgetFiltersTest.php`, `apps/platform/tests/Feature/OpsUx/ProgressWidgetOverflowTest.php`, `apps/platform/tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`, `apps/platform/tests/Feature/Filament/DashboardKpisWidgetTest.php`, `apps/platform/tests/Feature/Filament/NeedsAttentionWidgetTest.php`, `apps/platform/tests/Feature/Filament/WorkspaceOverviewOperationsTest.php`, `apps/platform/tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php`, `apps/platform/tests/Feature/Monitoring/MonitoringOperationsTest.php`, `apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php`, `apps/platform/tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`, `apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php`, `apps/platform/tests/Feature/RunAuthorizationTenantIsolationTest.php`, and `apps/platform/tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php` - [X] T027 Record the finalized affected surfaces, any retained density-specific copy decisions, and the `document-in-feature` test-governance disposition in `specs/233-stale-run-visibility/plan.md` --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: No dependencies; can start immediately. - **Foundational (Phase 2)**: Depends on Setup completion and blocks all user story work. - **User Story 1 (Phase 3)**: Depends on Foundational completion and is the recommended first implementation increment. - **User Story 2 (Phase 4)**: Depends on Foundational completion and can begin after the shared truth contract is stable. - **User Story 3 (Phase 5)**: Depends on User Stories 1 and 2 because canonical detail should be aligned against the final compact-surface semantics. - **Polish (Phase 6)**: Depends on all desired user stories being complete. ### User Story Dependencies - **US1 (P1)**: Starts immediately after Foundational and delivers the highest-value tenant-surface honesty fix. - **US2 (P1)**: Can begin after Foundational, but is easiest to complete after US1 settles the compact stale-active vocabulary. - **US3 (P2)**: Starts after US1 and US2 stabilize because canonical detail should confirm the final compact-surface contract, not compete with an in-progress one. ### Within Each User Story - Story tests should be written and fail before the corresponding implementation tasks are considered complete. - Shared files such as `apps/platform/app/Support/OpsUx/OperationUxPresenter.php`, `apps/platform/app/Support/OpsUx/ActiveRuns.php`, and `apps/platform/app/Filament/Resources/OperationRunResource.php` should be edited sequentially even when surrounding tasks are otherwise parallelizable. - Each story's verification task should complete before moving to the next priority slice when working sequentially. ### Parallel Opportunities - **Setup**: `T001`, `T002`, `T003`, and `T004` can run in parallel. - **Foundational**: `T006` can run in parallel with the tail end of `T005` once the shared contract is clear. - **US1 tests**: `T007` and `T008` can run in parallel. - **US1 implementation**: `T009` and `T010` can run in parallel; `T011` should follow once the touched surface outputs are visible. - **US2 tests**: `T013` and `T014` can run in parallel. - **US2 implementation**: `T015` and `T016` can run in parallel; `T017` should follow once both summary and canonical list semantics are visible. - **US3 tests**: `T019` and `T020` can run in parallel. - **Polish**: `T024` can run in parallel with `T025` after runtime implementation is stable. --- ## Parallel Example: User Story 1 ```bash # Run tenant-surface test work in parallel: T007 apps/platform/tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php, apps/platform/tests/Feature/OpsUx/ProgressWidgetFiltersTest.php, apps/platform/tests/Feature/OpsUx/ProgressWidgetOverflowTest.php T008 apps/platform/tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php, apps/platform/tests/Feature/Filament/DashboardKpisWidgetTest.php, apps/platform/tests/Feature/Filament/NeedsAttentionWidgetTest.php, apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php # Then split the non-overlapping implementation work: T009 apps/platform/app/Support/OpsUx/ActiveRuns.php, apps/platform/app/Livewire/BulkOperationProgress.php, apps/platform/resources/views/livewire/bulk-operation-progress.blade.php, apps/platform/resources/views/livewire/bulk-operation-progress-wrapper.blade.php T010 apps/platform/app/Filament/Widgets/Tenant/RecentOperationsSummary.php, apps/platform/resources/views/filament/widgets/tenant/recent-operations-summary.blade.php, apps/platform/app/Filament/Widgets/Dashboard/DashboardKpis.php, apps/platform/app/Filament/Widgets/Dashboard/NeedsAttention.php ``` --- ## Parallel Example: User Story 2 ```bash # Run workspace-summary, visibility-safety, and canonical-list assertions in parallel: T013 apps/platform/tests/Feature/Filament/WorkspaceOverviewOperationsTest.php, apps/platform/tests/Feature/Monitoring/MonitoringOperationsTest.php, apps/platform/tests/Feature/RunAuthorizationTenantIsolationTest.php, and apps/platform/tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php T014 apps/platform/tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php and apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php ``` --- ## Parallel Example: User Story 3 ```bash # Run canonical-detail and transition-consistency assertions in parallel: T019 apps/platform/tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php and apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php T020 apps/platform/tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php and apps/platform/tests/Feature/Monitoring/MonitoringOperationsTest.php ``` --- ## Implementation Strategy ### First Implementation Increment (User Story 1 Only) 1. Complete Phase 1: Setup. 2. Complete Phase 2: Foundational. 3. Complete Phase 3: User Story 1. 4. Validate the feature with `T012` before widening the slice. ### Incremental Delivery 1. Stabilize the shared freshness/problem-class contract and docs. 2. Ship US1 to fix the tenant-surface blind spot and stale-hidden progress behavior. 3. Ship US2 to make workspace summaries and the canonical list scanable. 4. Ship US3 to ensure canonical detail confirms the same meaning after drill-through. 5. Finish with formatting, focused tests, and close-out notes. ### Parallel Team Strategy With multiple developers: 1. One contributor can own Ops UX progress visibility while another extends tenant dashboard/widget assertions. 2. After Phase 2, one contributor can update workspace summary builders while another adjusts canonical list/detail semantics. 3. Keep `OperationUxPresenter.php`, `ActiveRuns.php`, and `OperationRunResource.php` serialized because they anchor the shared truth and surface contract. --- ## Notes - `[P]` marks tasks that can run in parallel once prerequisites are satisfied and touched files do not overlap. - `[US1]`, `[US2]`, and `[US3]` map directly to the feature specification user stories. - The first working increment is Phase 1 through Phase 3, but the feature-complete approved scope remains Phase 1 through Phase 5 because canonical list and detail alignment are part of the accepted problem statement. - All tasks above use exact repository paths and keep the work bounded to the existing admin-plane monitoring and progress surfaces.