21 KiB
Tasks: Operations Lifecycle Alignment & Cross-Surface Truth Consistency
Input: Design documents from /specs/178-ops-truth-alignment/
Prerequisites: plan.md, spec.md, research.md, data-model.md, quickstart.md, contracts/operations-truth-alignment.openapi.yaml
Tests: Tests are REQUIRED for this feature. Use Pest coverage in tests/Feature/Filament/DashboardKpisWidgetTest.php, tests/Feature/Filament/NeedsAttentionWidgetTest.php, tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php, tests/Feature/Filament/WorkspaceOverviewOperationsTest.php, tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php, tests/Feature/Monitoring/MonitoringOperationsTest.php, tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php, tests/Feature/Monitoring/OperationsDbOnlyRenderTest.php, tests/Feature/Monitoring/OperationsDbOnlyTest.php, tests/Feature/Monitoring/OperationsTenantScopeTest.php, tests/Feature/Notifications/OperationRunNotificationTest.php, tests/Feature/System/Spec114/CanonicalRunDetailTest.php, tests/Feature/System/Spec114/OpsFailuresViewTest.php, tests/Feature/System/Spec114/OpsStuckViewTest.php, tests/Feature/System/Spec114/OpsTriageActionsTest.php, tests/Feature/Guards/ActionSurfaceContractTest.php, and tests/Feature/RunAuthorizationTenantIsolationTest.php.
Operations: This feature does not create a new OperationRun type or change lifecycle ownership. Tasks must keep OperationRun as the only canonical truth, keep active awareness on existing progress and monitoring surfaces, preserve exactly-once terminal notification behavior via app/Notifications/OperationRunCompleted.php, and avoid any new queued/running database notifications.
RBAC: Existing admin-plane and system-plane authorization remains authoritative. Tasks must preserve tenant-safe /admin/operations filter continuity, maintain 404 for non-member/non-entitled scope access, maintain 403 for in-scope capability failures where applicable, and avoid any cross-plane leakage.
Operator Surfaces: Tenant dashboard attention and recency, workspace attention and recency, BulkOperationProgress, /admin/operations, /admin/operations/{run}, /system/ops/runs, /system/ops/failures, /system/ops/stuck, and /system/ops/runs/{run} must stay operator-first and expose lifecycle/problem-class truth by default.
Filament UI Action Surfaces: This feature changes summary, registry, and detail surfaces only. No new destructive actions, no empty action groups, and no redundant inspect affordances are introduced. Row-click/detail ownership and CTA semantics must remain aligned with the existing Action Surface Contract.
Filament UI UX-001: No new create/edit/view CRUD pages are introduced. Existing widgets, monitoring pages, and system pages keep their current layout while stale/reconciled emphasis is hardened inside current summary and decision-zone structures.
Badges: Existing centralized status, outcome, and freshness semantics remain authoritative. Do not introduce page-local badge mappings.
Organization: Tasks are grouped by user story so each story can be implemented and verified as an independent increment.
Phase 1: Setup
Purpose: Lock the implementation targets to the generated design artifacts and current runtime seams before editing behavior.
- T001 Reconfirm the aligned surface contract and verification pack in
specs/178-ops-truth-alignment/contracts/operations-truth-alignment.openapi.yamlandspecs/178-ops-truth-alignment/quickstart.mdbefore touching runtime files. - T002 Inspect the current lifecycle-truth touchpoints in
app/Models/OperationRun.php,app/Support/OpsUx/OperationUxPresenter.php,app/Support/OpsUx/ActiveRuns.php,app/Support/OperationRunLinks.php,app/Livewire/BulkOperationProgress.php,app/Filament/Pages/Monitoring/Operations.php,app/Filament/Pages/Operations/TenantlessOperationRunViewer.php,app/Filament/System/Pages/Ops/Runs.php,app/Filament/System/Pages/Ops/Failures.php,app/Filament/System/Pages/Ops/Stuck.php, andapp/Filament/System/Pages/Ops/ViewRun.phpso every story maps to an existing seam.
Phase 2: Foundational
Purpose: Establish the shared truth-derivation, filter-state, and guard baselines that every story depends on.
⚠️ CRITICAL: No user story work should be considered complete until these shared seams are in place.
- T003 Update the shared cross-surface regression baseline in
tests/Feature/Monitoring/MonitoringOperationsTest.phpandtests/Feature/Monitoring/OperationsDashboardDrillthroughTest.phpso stale-active versus terminal-follow-up continuity can be asserted before story-specific rendering changes. - T004 [P] Update guard and authorization baseline coverage in
tests/Feature/Guards/ActionSurfaceContractTest.phpandtests/Feature/RunAuthorizationTenantIsolationTest.phpso tenant-safe filter continuity, inspect semantics, and404versus403expectations are locked before surface edits. - T005 [P] Implement the shared derived problem-class and stale-lineage helpers in
app/Models/OperationRun.php,app/Support/OpsUx/OperationUxPresenter.php, andapp/Support/OpsUx/ActiveRuns.php. - T006 [P] Implement canonical problem-class drill-through and filter-state support in
app/Support/OperationRunLinks.phpandapp/Filament/Pages/Monitoring/Operations.php.
Checkpoint: The shared truth contract, canonical drill-through state, and guard expectations are ready for story work.
Phase 3: User Story 1 - Recover The Same Truth From Every Entry Point (Priority: P1) 🎯 MVP
Goal: Make tenant, workspace, canonical admin, and system monitoring surfaces classify the same run with the same problem class and drill-through framing.
Independent Test: Seed fresh active, likely stale, reconciled-failed, and terminal-problem runs, then verify tenant/workspace summaries, /admin/operations, /admin/operations/{run}, /system/ops/failures, and /system/ops/stuck all surface the same lifecycle story and matching destinations.
Tests for User Story 1
- T007 [P] [US1] Add tenant/workspace summary bucket and row-truth assertions in
tests/Feature/Filament/DashboardKpisWidgetTest.php,tests/Feature/Filament/NeedsAttentionWidgetTest.php,tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php, andtests/Feature/Filament/WorkspaceOverviewOperationsTest.php. - T008 [P] [US1] Add admin/system list truth-alignment assertions for stale lineage and problem-class filters in
tests/Feature/Monitoring/OperationsDbOnlyTest.php,tests/Feature/Monitoring/OperationsTenantScopeTest.php,tests/Feature/System/Spec114/OpsFailuresViewTest.php, andtests/Feature/System/Spec114/OpsStuckViewTest.php.
Implementation for User Story 1
- T009 [P] [US1] Split tenant terminal-follow-up versus active-stale attention buckets in
app/Filament/Widgets/Dashboard/DashboardKpis.phpandapp/Filament/Widgets/Dashboard/NeedsAttention.php. - T010 [P] [US1] Render problem-class-aware recent-operation rows on the tenant dashboard in
app/Filament/Widgets/Dashboard/RecentOperations.php. - T011 [P] [US1] Mirror the same bucket and row truth on workspace surfaces in
app/Support/Workspaces/WorkspaceOverviewBuilder.php,app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php, andapp/Filament/Widgets/Workspace/WorkspaceRecentOperations.php. - T012 [US1] Align canonical admin and system monitoring list surfaces around the shared problem-class contract in
app/Filament/Pages/Monitoring/Operations.php,app/Filament/System/Pages/Ops/Runs.php,app/Filament/System/Pages/Ops/Failures.php, andapp/Filament/System/Pages/Ops/Stuck.php. - T013 [US1] Run focused US1 verification from
specs/178-ops-truth-alignment/quickstart.mdagainst the Filament, monitoring, and system test files updated in T007 and T008.
Checkpoint: Cross-surface list and summary entry points now tell the same stale, reconciled, and terminal truth.
Phase 4: User Story 2 - Trust Live Progress Without Waiting For A New Event (Priority: P1)
Goal: Make local progress and recency surfaces converge on canonical truth within one polling cycle even when no new enqueue event is emitted.
Independent Test: Keep BulkOperationProgress open while a run changes from active to terminal or reconciled without a new enqueue event, then verify the overlay stops treating it as active and recent-operation rows refresh to the new truth.
Tests for User Story 2
- T014 [P] [US2] Add active-only polling and no-new-enqueue convergence assertions in
tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php. - T015 [P] [US2] Add recent-operations freshness-update assertions for tenant/workspace surfaces in
tests/Feature/Filament/RecentOperationsSummaryWidgetTest.phpandtests/Feature/Filament/WorkspaceOverviewOperationsTest.php.
Implementation for User Story 2
- T016 [US2] Implement conditional polling, active-only snapshots, and terminal/reconciled removal in
app/Livewire/BulkOperationProgress.phpandresources/views/livewire/bulk-operation-progress.blade.php. - T017 [US2] Tighten active-run polling gates and visibility decisions for local progress in
app/Support/OpsUx/ActiveRuns.phpandapp/Models/OperationRun.php. - T018 [US2] Re-render tenant/workspace recent-operation freshness after canonical truth changes in
app/Filament/Widgets/Dashboard/RecentOperations.php,app/Support/Workspaces/WorkspaceOverviewBuilder.php, andapp/Filament/Widgets/Workspace/WorkspaceRecentOperations.php. - T019 [US2] Run focused US2 verification from
specs/178-ops-truth-alignment/quickstart.mdagainsttests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php,tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php, andtests/Feature/Filament/WorkspaceOverviewOperationsTest.php.
Checkpoint: Local progress and recency surfaces no longer show false activity after canonical truth changes.
Phase 5: User Story 3 - Decide What To Do From The Canonical Detail Surface (Priority: P2)
Goal: Make the canonical decision zone explain current lifecycle truth, reconciliation state, and primary next step before artifact-deep diagnostics.
Independent Test: Open stale, reconciled, partial, failed, and healthy active runs and verify the primary decision zone answers whether the run is still active, whether reconciliation already happened, and what to do next without relying on secondary diagnostics.
Tests for User Story 3
- T020 [P] [US3] Add canonical admin detail decision-zone assertions for stale, reconciled, terminal, and artifact-rich runs in
tests/Feature/Monitoring/OperationsDbOnlyRenderTest.phpandtests/Feature/Monitoring/MonitoringOperationsTest.php. - T021 [P] [US3] Add system detail decision-zone priority assertions, including artifact-rich run behavior and stale-lineage triage context, in
tests/Feature/System/Spec114/CanonicalRunDetailTest.phpandtests/Feature/System/Spec114/OpsTriageActionsTest.php.
Implementation for User Story 3
- T022 [US3] Elevate stale/reconciled lifecycle truth and next-step guidance in the canonical admin detail composition in
app/Filament/Pages/Operations/TenantlessOperationRunViewer.phpandapp/Support/OpsUx/OperationUxPresenter.php. - T023 [US3] Surface the same decision-zone contract on the system detail page in
app/Filament/System/Pages/Ops/ViewRun.phpandresources/views/filament/system/pages/ops/view-run.blade.php. - T024 [US3] Align detail copy so lifecycle truth stays above artifact-deep diagnostics in
app/Support/OpsUx/OperationUxPresenter.php,app/Filament/Pages/Operations/TenantlessOperationRunViewer.php, andapp/Filament/System/Pages/Ops/ViewRun.php. - T025 [US3] Run focused US3 verification from
specs/178-ops-truth-alignment/quickstart.mdagainsttests/Feature/Monitoring/OperationsDbOnlyRenderTest.php,tests/Feature/Monitoring/MonitoringOperationsTest.php,tests/Feature/System/Spec114/CanonicalRunDetailTest.php, andtests/Feature/System/Spec114/OpsTriageActionsTest.php.
Checkpoint: Canonical detail surfaces answer the operator's first lifecycle question before any deep diagnostics.
Phase 6: User Story 4 - Preserve Problem-Class Continuity In System And Notification Entry Points (Priority: P3)
Goal: Keep notifications and platform entry points visibly aligned with the same problem class that initiated navigation.
Independent Test: Enter the flow from dashboard/workspace attention, recent operations, and notifications, then verify the destination preserves the same problem class, stale lineage, and authorization-safe context on arrival.
Tests for User Story 4
- T026 [P] [US4] Add notification problem-class wording and linked-destination continuity assertions in
tests/Feature/Notifications/OperationRunNotificationTest.phpandtests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php. - T027 [P] [US4] Add reconciled stale-lineage visibility and plane-safe navigation assertions in
tests/Feature/System/Spec114/OpsFailuresViewTest.php,tests/Feature/System/Spec114/OpsStuckViewTest.php, andtests/Feature/RunAuthorizationTenantIsolationTest.php.
Implementation for User Story 4
- T028 [US4] Preserve problem-class wording and stale-lineage cues in
app/Notifications/OperationRunCompleted.phpandapp/Support/OpsUx/OperationUxPresenter.php. - T029 [US4] Preserve tenant-safe problem-class landing state from dashboard/workspace/notification entry points in
app/Support/OperationRunLinks.phpandapp/Filament/Pages/Monitoring/Operations.php. - T030 [US4] Make reconciled stale lineage visible across platform entry surfaces in
app/Filament/System/Pages/Ops/Runs.php,app/Filament/System/Pages/Ops/Failures.php,app/Filament/System/Pages/Ops/Stuck.php, andapp/Filament/System/Pages/Ops/ViewRun.php. - T031 [US4] Run focused US4 verification from
specs/178-ops-truth-alignment/quickstart.mdagainsttests/Feature/Notifications/OperationRunNotificationTest.php,tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php,tests/Feature/System/Spec114/OpsFailuresViewTest.php,tests/Feature/System/Spec114/OpsStuckViewTest.php, andtests/Feature/RunAuthorizationTenantIsolationTest.php.
Checkpoint: Notifications and system/admin entry points preserve the same problem-class story through to their destinations.
Phase 7: Polish & Cross-Cutting Concerns
Purpose: Finish shared copy alignment, formatting, and final verification across all stories.
- T032 [P] Align remaining operator-facing truth labels and helper copy in
app/Filament/Widgets/Dashboard/DashboardKpis.php,app/Filament/Widgets/Dashboard/NeedsAttention.php,app/Filament/Widgets/Dashboard/RecentOperations.php,app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php,app/Filament/Widgets/Workspace/WorkspaceRecentOperations.php,app/Filament/Pages/Monitoring/Operations.php,app/Filament/Pages/Operations/TenantlessOperationRunViewer.php,app/Filament/System/Pages/Ops/ViewRun.php,app/Notifications/OperationRunCompleted.php, andresources/views/filament/system/pages/ops/view-run.blade.php. - T033 Run formatting with
vendor/bin/sail bin pint --dirty --format agentfor the runtime and test files touched by Spec 178 usingspecs/178-ops-truth-alignment/quickstart.md. - T034 Run the full focused verification pack in
specs/178-ops-truth-alignment/quickstart.mdagainst the Filament, OpsUx, Monitoring, System, Notification, Guard, and authorization tests touched by this feature. - T035 Validate the final behavior against
specs/178-ops-truth-alignment/contracts/operations-truth-alignment.openapi.yamlandspecs/178-ops-truth-alignment/quickstart.mdbefore handoff. - T036 Run the timed 10-second operator-comprehension smoke check from
specs/178-ops-truth-alignment/spec.mdandspecs/178-ops-truth-alignment/quickstart.mdacross tenant, workspace, admin, and system entry surfaces before handoff.
Dependencies & Execution Order
Phase Dependencies
- Setup (Phase 1): No dependencies.
- Foundational (Phase 2): Depends on Setup and establishes the shared truth/guard baseline.
- User Story 1 (Phase 3): Depends on Foundational.
- User Story 2 (Phase 4): Depends on Foundational.
- User Story 3 (Phase 5): Depends on Foundational.
- User Story 4 (Phase 6): Depends on Foundational and should follow User Story 1 so destination problem-class framing already exists.
- Polish (Phase 7): Depends on the desired user stories being complete.
User Story Dependencies
- US1 (P1): Can start immediately after Phase 2 and is the recommended MVP.
- US2 (P1): Can start after Phase 2 and remains independently testable, though it reuses the same shared problem-class helpers as US1.
- US3 (P2): Can start after Phase 2 because it focuses on detail-surface emphasis rather than summary routing.
- US4 (P3): Should start after US1 and US3 stabilize the visible destination framing used by notifications and platform entry points.
Within Each User Story
- Add or update story-specific tests first and make them fail for the intended behavior.
- Apply runtime source changes next.
- Run the smallest focused verification pack before moving to another story.
Parallel Opportunities
T004,T005, andT006can run in parallel afterT003establishes the shared monitoring baseline.T007andT008can run in parallel for User Story 1.T009,T010, andT011can run in parallel for User Story 1 once the foundational helpers land.T014andT015can run in parallel for User Story 2.T016andT017can run in parallel for User Story 2 because they touch the Livewire surface versus shared polling helpers.T020andT021can run in parallel for User Story 3.T022andT023can run in parallel for User Story 3.T026andT027can run in parallel for User Story 4.T028,T029, andT030can run in parallel for User Story 4 once the tests are in place.
Parallel Example: User Story 1
Task: "T007 tests/Feature/Filament/DashboardKpisWidgetTest.php, tests/Feature/Filament/NeedsAttentionWidgetTest.php, tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php, tests/Feature/Filament/WorkspaceOverviewOperationsTest.php"
Task: "T008 tests/Feature/Monitoring/OperationsDbOnlyTest.php, tests/Feature/Monitoring/OperationsTenantScopeTest.php, tests/Feature/System/Spec114/OpsFailuresViewTest.php, tests/Feature/System/Spec114/OpsStuckViewTest.php"
Task: "T009 app/Filament/Widgets/Dashboard/DashboardKpis.php and app/Filament/Widgets/Dashboard/NeedsAttention.php"
Parallel Example: User Story 2
Task: "T014 tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php"
Task: "T015 tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php and tests/Feature/Filament/WorkspaceOverviewOperationsTest.php"
Task: "T016 app/Livewire/BulkOperationProgress.php and resources/views/livewire/bulk-operation-progress.blade.php"
Parallel Example: User Story 3
Task: "T020 tests/Feature/Monitoring/OperationsDbOnlyRenderTest.php and tests/Feature/Monitoring/MonitoringOperationsTest.php"
Task: "T021 tests/Feature/System/Spec114/CanonicalRunDetailTest.php and tests/Feature/System/Spec114/OpsTriageActionsTest.php"
Task: "T023 app/Filament/System/Pages/Ops/ViewRun.php and resources/views/filament/system/pages/ops/view-run.blade.php"
Parallel Example: User Story 4
Task: "T026 tests/Feature/Notifications/OperationRunNotificationTest.php and tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php"
Task: "T027 tests/Feature/System/Spec114/OpsFailuresViewTest.php, tests/Feature/System/Spec114/OpsStuckViewTest.php, and tests/Feature/RunAuthorizationTenantIsolationTest.php"
Task: "T028 app/Notifications/OperationRunCompleted.php and app/Support/OpsUx/OperationUxPresenter.php"
Implementation Strategy
MVP First (User Story 1 Only)
- Complete Phase 1: Setup.
- Complete Phase 2: Foundational.
- Complete Phase 3: User Story 1.
- Validate the cross-surface truth-alignment slice with the focused US1 verification run before touching local progress or detail emphasis.
Incremental Delivery
- Finish Setup + Foundational to lock shared truth derivation, canonical filter state, and guard expectations.
- Deliver User Story 1 for summary/list truth alignment.
- Deliver User Story 2 for local progress freshness and active-only convergence.
- Deliver User Story 3 for canonical decision-zone hardening.
- Deliver User Story 4 for notification/system entry-point continuity.
- Finish with Phase 7 polish, formatting, full focused verification, and the timed operator-comprehension smoke check.
Parallel Team Strategy
- One engineer can take the Foundational shared helper work while another updates the shared guard/monitoring baseline tests.
- After Phase 2:
- Engineer A can take US1 summary and monitoring alignment.
- Engineer B can take US2 local progress and recency freshness.
- Engineer C can prepare US3 decision-zone tests.
- US4 should land after destination framing is stable, then Phase 7 closes the feature with shared verification.
Notes
[P]tasks touch different files or are safe concurrent work once their dependencies are met.[US1],[US2],[US3], and[US4]map directly to the user stories inspec.md.- The suggested MVP scope is Phase 1 through Phase 3.
- This plan intentionally avoids schema changes, provider-registration changes, new assets, new destructive actions, and any second lifecycle model.