ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
603d509b8f
TenantAtlas/specs/233-stale-run-visibility/tasks.md
ahmido 6fdd45fb02
Some checks failed
Main Confidence / confidence (push) Failing after 53s
Details
feat: surface stale active operation runs (#269) 
## Summary
- keep stale active operation runs visible in the tenant progress overlay and polling state
- align tenant and canonical operation surfaces around the shared stale-active presentation contract
- add Spec 233 artifacts and clean the promoted-candidate backlog entries

## Validation
- browser smoke: `/admin/t/18000000-0000-4000-8000-000000000180` -> stale dashboard CTA -> `/admin/operations?tenant_id=7&activeTab=active_stale_attention&problemClass=active_stale_attention` -> `/admin/operations/15`
- verified healthy vs likely-stale tenant cards, canonical stale list row, and canonical run detail consistency

## Notes
- local smoke fixture seeded with one fresh and one stale running `baseline_compare` operation for browser validation
- Pest suite was not re-run in this session before opening this PR

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #269
2026-04-23 15:10:06 +00:00

22 KiB
Raw Blame History

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

  • Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
  • New or changed tests stay in the smallest honest family, and any heavy-governance or browser addition is explicit.
  • Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
  • Planned validation commands cover the change without pulling in unrelated lane cost.
  • The declared surface test profile or standard-native-filament relief is explicit.
  • 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.

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

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

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

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

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

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

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

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

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

# 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

# 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

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