ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
9e435ea91f
TenantAtlas/specs/358-operationrun-queue-truth-foundation/tasks.md
ahmido 2a12729dc5 feat: implement operation run queue truth foundation (spec 358) (#429) 
Implements platform feature branch `358-operationrun-queue-truth-foundation`.

Target branch: `platform-dev`.

Follow-up integration path after merge:

`platform-dev` -> `dev`.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #429
2026-06-06 12:03:11 +00:00

15 KiB
Raw Blame History

Tasks: OperationRun Queue Truth Foundation

Input: specs/358-operationrun-queue-truth-foundation/spec.md, plan.md, and checklists/requirements.md
Prerequisites: spec.md and plan.md
Tests: REQUIRED (Pest). Keep proof bounded to one unit family plus focused monitoring/detail feature tests.
Operations: No new OperationRun type, no new queue family, no new notification path, no new reconciliation command, and no new persisted lifecycle state.
RBAC: Reuse current workspace and managed-environment authorization rules; presentation must never reveal unauthorized runs.
Shared Pattern Reuse: Reuse OperationRunProgressContract, RunDurationInsights, OperationUxPresenter, OperationRunFreshnessState, and existing monitoring renderers. Do not introduce a new adapter registry or queue-health framework.
Filament / Panel Guardrails: Filament remains v5 on Livewire v4. Provider registration stays in apps/platform/bootstrap/providers.php. No new panel, route family, or asset strategy is allowed.
Organization: Tasks are grouped by user story so the generic derivation, surface retrofit, and follow-up guardrails remain independently reviewable.

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 no hidden browser or heavy-governance proof is introduced.
  • Shared helpers, fixtures, and context defaults stay cheap by default.
  • Planned validation commands cover the change without widening into unrelated lanes.
  • The declared monitoring/detail surface test profile is explicit.
  • Any material budget, baseline, or escalation note is recorded in the active feature close-out.

Phase 1: Setup (Shared Truth Inventory)

Purpose: confirm the current contradiction and the exact shared helper boundaries before runtime edits begin.

  • T001 Review specs/358-operationrun-queue-truth-foundation/spec.md, plan.md, checklists/requirements.md, .specify/memory/constitution.md, docs/ai-coding-rules.md, specs/149-queued-execution-reauthorization/spec.md, specs/160-operation-lifecycle-guarantees/spec.md, specs/233-stale-run-visibility/spec.md, specs/268-operationrun-activity-feedback/spec.md, specs/270-operationrun-progress-contract/spec.md, and specs/272-operationrun-phase-composite-progress/spec.md together so the implementation stays on current repo truth.
  • T002 [P] Confirm the current generic derivation seams in apps/platform/app/Support/OpsUx/OperationRunProgressContract.php, apps/platform/app/Support/OpsUx/RunDurationInsights.php, apps/platform/app/Support/OpsUx/OperationUxPresenter.php, and apps/platform/app/Support/Operations/OperationRunFreshnessState.php.
  • T003 [P] Confirm the current render seams in apps/platform/resources/views/livewire/bulk-operation-progress.blade.php, apps/platform/app/Filament/Pages/Monitoring/Operations.php, apps/platform/resources/views/filament/pages/monitoring/operations.blade.php, apps/platform/app/Filament/Resources/OperationRunResource.php as the shared table/detail seam, and apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php.
  • T004 [P] Confirm the focused proof owners in apps/platform/tests/Unit/Support/OpsUx/OperationRunProgressContractTest.php, apps/platform/tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php, apps/platform/tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php, apps/platform/tests/Feature/MonitoringOperationsTest.php, apps/platform/tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php, apps/platform/tests/Feature/Monitoring/MonitoringOperationsTest.php, apps/platform/tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php, and apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php.

Phase 2: Foundational (Blocking Queue-Truth Contract)

Purpose: settle one generic queue-truth contract before any individual surface is updated.

Critical: No user-story runtime work should begin until this phase is complete.

  • T005 [P] Add or extend failing unit coverage in apps/platform/tests/Unit/Support/OpsUx/OperationRunProgressContractTest.php for fresh queued, stale queued, fresh running, stale running, determinate-progress stale running, unsupported lifecycle, and reconciled-terminal cases.
  • T006 [P] Add or extend focused feature coverage in apps/platform/tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php, apps/platform/tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php, and apps/platform/tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php proving that stale-active runs do not mix stale attention with ordinary queue/progress reassurance.
  • T007 Freeze the canonical derivation boundary in apps/platform/app/Support/OpsUx/OperationRunProgressContract.php, apps/platform/app/Support/OpsUx/RunDurationInsights.php, apps/platform/app/Support/OpsUx/OperationUxPresenter.php, and apps/platform/app/Support/Operations/OperationRunFreshnessState.php without introducing new persisted state or a new registry.

Checkpoint: Generic queue truth is derived from one aligned helper path before shell/list/detail surfaces are edited.

Phase 3: User Story 1 - See honest queued and stale truth on active monitoring surfaces (Priority: P1)

Goal: shell and list surfaces no longer mix stale-active attention with calm queue or progress reassurance.

Independent Test: seed fresh and stale queued/running runs, render the shell hint and operations list, and verify that only fresh active work keeps calm queue/progress copy.

Tests for User Story 1

  • T008 [P] [US1] Extend apps/platform/tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php and apps/platform/tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php for stale queued, stale running, and determinate-progress stale-running shell cases.
  • T009 [P] [US1] Extend apps/platform/tests/Feature/Monitoring/MonitoringOperationsTest.php and apps/platform/tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php for operations-list row truth and lifecycle-attention alignment.

Implementation for User Story 1

  • T010 [US1] Align generic progress and queue guidance in apps/platform/app/Support/OpsUx/OperationRunProgressContract.php, apps/platform/app/Support/OpsUx/RunDurationInsights.php, and apps/platform/app/Support/OpsUx/OperationUxPresenter.php so stale-active work no longer presents ordinary queue/progress reassurance.
  • T011 [US1] Update apps/platform/resources/views/livewire/bulk-operation-progress.blade.php so the shell activity hint consumes the aligned generic queue truth without local contradictory fallback copy.
  • T012 [US1] Update apps/platform/app/Filament/Pages/Monitoring/Operations.php and apps/platform/app/Filament/Resources/OperationRunResource.php only as needed so the route-backed operations hub plus the shared table/detail summaries expose the same generic queue truth.

Checkpoint: User Story 1 is independently functional when stale-active work reads honestly on shell and list surfaces.

Phase 4: User Story 2 - Keep canonical run detail aligned with generic queue truth (Priority: P1)

Goal: canonical run detail confirms the same lifecycle meaning before deeper diagnostics render.

Independent Test: open canonical detail for fresh, stale, and reconciled runs and verify that top-level lifecycle guidance matches shell/list semantics.

Tests for User Story 2

  • T013 [P] [US2] Extend apps/platform/tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php and apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php for fresh, stale, and reconciled-terminal top-summary behavior.
  • T014 [P] [US2] Extend apps/platform/tests/Feature/Monitoring/MonitoringOperationsTest.php for compact-to-detail continuity where the same run is opened from the list after stale-active presentation.

Implementation for User Story 2

  • T015 [US2] Update apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php so lifecycle banners and detail guidance reflect the aligned generic queue truth before raw diagnostics.
  • T016 [US2] Update apps/platform/app/Support/OpsUx/OperationUxPresenter.php and any touched OperationRunResource summary helpers so canonical detail and resource detail stay aligned.

Checkpoint: User Story 2 is independently functional when canonical detail confirms, rather than contradicts, generic queue truth.

Phase 5: User Story 3 - Keep proof-backed reconciliation separate from generic queue truth (Priority: P2)

Goal: generic stale wording stays cautious, while existing scheduled/adapter reconciliation remains authoritative for terminal truth.

Independent Test: compare stale active runs and already-reconciled terminal runs to verify that cautious generic wording and existing reconciled semantics both survive.

Tests for User Story 3

  • T017 [P] [US3] Extend unit or feature coverage, including apps/platform/tests/Feature/MonitoringOperationsTest.php where the operations aggregate wording is already asserted, so stale active runs without strong legitimacy evidence do not claim orphaned or domain-complete truth while existing scheduled/adapter-reconciled terminal runs keep their terminal semantics.
  • T018 [P] [US3] Extend apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php or the nearest focused monitoring suite for reconciled-terminal detail language regression protection.

Implementation for User Story 3

  • T019 [US3] Tighten cautious stale-active wording in apps/platform/app/Support/OpsUx/RunDurationInsights.php and apps/platform/app/Support/OpsUx/OperationUxPresenter.php so the generic path says only what current lifecycle truth can prove.
  • T020 [US3] Confirm apps/platform/app/Console/Commands/TenantpilotReconcileOperationRuns.php and apps/platform/app/Console/Commands/OpsReconcileAdapterRuns.php need no runtime change and document that no command-layer change was required.

Checkpoint: User Story 3 is independently functional when generic stale wording stays cautious and existing terminal reconciliation remains intact.

Phase 6: Polish & Cross-Cutting Validation

Purpose: validate the bounded slice, stop drift, and hand off a clean implementation path.

  • T021 [P] Refresh specs/358-operationrun-queue-truth-foundation/spec.md, plan.md, and checklists/requirements.md only if implementation proves a thinner or broader touched-file boundary.
  • T022 [P] Run cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/OpsUx/OperationRunProgressContractTest.php.
  • T023 [P] Run cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php tests/Feature/MonitoringOperationsTest.php tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php tests/Feature/Monitoring/MonitoringOperationsTest.php tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php tests/Feature/Operations/TenantlessOperationRunViewerTest.php.
  • T024 [P] Run cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent for touched platform files.
  • T025 [P] Run git diff --check.
  • T026 [P] Record the final queue-truth wording, proof boundaries, and any retained cautious-language decisions in the active feature close-out entry Guardrail / Smoke Coverage.

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): no dependencies
  • Foundational (Phase 2): depends on Setup and blocks all story work
  • US1 (Phase 3): depends on Foundational completion
  • US2 (Phase 4): depends on Foundational completion and is easiest after US1 settles the shared wording
  • US3 (Phase 5): depends on US1 and US2 because it confirms the final generic truth boundary
  • Polish (Phase 6): depends on all desired user stories

Parallel Opportunities

  • T002, T003, and T004 can run in parallel.
  • T005 and T006 can run in parallel after the current contradiction is confirmed.
  • T008 and T009 can run in parallel.
  • T013 and T014 can run in parallel.
  • T022, T023, T024, and T025 can run in parallel after implementation is stable.

Implementation Strategy

  1. Freeze the shared queue-truth derivation first.
  2. Ship US1 to remove the stale-vs-queue contradiction on shell/list surfaces.
  3. Ship US2 so canonical detail confirms the same truth.
  4. Ship US3 to protect the narrow boundary against overclaiming or framework creep.
  5. Finish with the focused validation commands and close-out notes.

Guardrail / Smoke Coverage

  • Final queue-truth wording keeps stale-active guidance at Past the lifecycle window. Review worker health and logs before retrying. and removes competing calm queue/progress copy from shell, list, and top-level detail surfaces.
  • Proof boundary remains shared-first: OperationRunProgressContract owns stale-active progress truth, OperationUxPresenter owns aligned lifecycle/detail guidance, and the shell/list/detail surfaces consume those shared seams instead of local fallback wording.
  • Browser smoke path used the real local route GET /admin/local/smoke-login and verified /admin/workspaces/38/operations followed by the primary Open operation drilldown to /admin/workspaces/38/operations/82.
  • Browser smoke confirmed stale wording is visible on both hub and detail, while Waiting for worker., Progress details pending., and 4 / 10 processed (40%) do not appear as primary stale-active guidance.
  • No runtime change was required in apps/platform/app/Filament/Pages/Monitoring/Operations.php, apps/platform/app/Filament/Resources/OperationRunResource.php, apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php, apps/platform/app/Console/Commands/TenantpilotReconcileOperationRuns.php, or apps/platform/app/Console/Commands/OpsReconcileAdapterRuns.php; the existing shared seams consumed the contract/presenter updates directly.
  • Validation evidence:
    • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/OpsUx/OperationRunProgressContractTest.php
    • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php
    • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/MonitoringOperationsTest.php tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php tests/Feature/Monitoring/MonitoringOperationsTest.php
    • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php tests/Feature/Operations/TenantlessOperationRunViewerTest.php
    • cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
    • git diff --check