ahmido
2a12729dc5
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
161 lines
15 KiB
Markdown
161 lines
15 KiB
Markdown
# 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
|
|
|
|
- [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 no hidden browser or heavy-governance proof is introduced.
|
|
- [x] Shared helpers, fixtures, and context defaults stay cheap by default.
|
|
- [x] Planned validation commands cover the change without widening into unrelated lanes.
|
|
- [x] The declared monitoring/detail surface test profile is explicit.
|
|
- [x] 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.
|
|
|
|
- [x] 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.
|
|
- [x] 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`.
|
|
- [x] 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`.
|
|
- [x] 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.
|
|
|
|
- [x] 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.
|
|
- [x] 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.
|
|
- [x] 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
|
|
|
|
- [x] 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.
|
|
- [x] 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
|
|
|
|
- [x] 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.
|
|
- [x] 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.
|
|
- [x] 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
|
|
|
|
- [x] 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.
|
|
- [x] 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
|
|
|
|
- [x] 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.
|
|
- [x] 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
|
|
|
|
- [x] 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.
|
|
- [x] 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
|
|
|
|
- [x] 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.
|
|
- [x] 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.
|
|
|
|
- [x] 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.
|
|
- [x] T022 [P] Run `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/OpsUx/OperationRunProgressContractTest.php`.
|
|
- [x] 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`.
|
|
- [x] T024 [P] Run `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` for touched platform files.
|
|
- [x] T025 [P] Run `git diff --check`.
|
|
- [x] 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`
|