176 lines
15 KiB
Markdown
176 lines
15 KiB
Markdown
---
|
|
description: "Task list for OperationRun Activity Feedback v1"
|
|
---
|
|
|
|
# Tasks: OperationRun Activity Feedback v1
|
|
|
|
**Input**: Design documents from `specs/268-operationrun-activity-feedback/`
|
|
**Prerequisites**: `specs/268-operationrun-activity-feedback/spec.md`, `specs/268-operationrun-activity-feedback/plan.md`, `specs/268-operationrun-activity-feedback/checklists/requirements.md`
|
|
|
|
**Tests**: REQUIRED (Pest). Keep proof bounded to Feature coverage for the current tenant shell host plus one named browser smoke for the non-obstructive shell contract.
|
|
**Operations**: No new `OperationRun` type, no new queue family, no DB-notification policy change, and no new lifecycle/status ownership. Existing queued toasts, terminal notifications, `run-enqueued` browser events, `OperationRunLinks`, and Operations collection/detail pages remain authoritative.
|
|
**RBAC**: Reuse current `OperationRun` policies and tenant context guards. No tenantless leakage from tenant surfaces; the shell hint stays inert when no selected tenant or `viewAny` capability exists.
|
|
**Shared Pattern Reuse**: Reuse `OperationUxPresenter`, `OperationStatusNormalizer`, `OperationRunLinks`, `OperationRunUrl`, `ActiveRuns`, `OpsUxBrowserEvents`, current badge semantics, `BulkOperationProgress`, and `docs/ui/tenantpilot-enterprise-ui-standards.md`. Do not create a second lifecycle, a second run-severity model, a persistent acknowledgement model, or a new host-surface activity framework.
|
|
**Filament / Panel Guardrails**: Filament remains v5 on Livewire v4. Provider registration remains unchanged in `apps/platform/bootstrap/providers.php`. No new panel, resource, or asset strategy is allowed. The tenant-panel `BODY_END` render hook may change implementation, but it must stop covering primary actions and must stay active-only.
|
|
**Organization**: Tasks are grouped by user story so the shell contract, the honest-progress rules, and the browser-session calmness rules remain independently reviewable.
|
|
|
|
## Test Governance Notes
|
|
|
|
- Lane mix stays Feature plus one named browser smoke for overlap/non-obstruction proof.
|
|
- Prefer extending `BulkOperationProgressDbOnlyTest`, `ProgressWidgetOverflowTest`, `ActivityFeedbackSurfaceTest`, and `OperationRunLinkContractGuardTest` before adding broader families.
|
|
- Browser proof is required for the non-obstructive shell contract and must stay explicit in naming.
|
|
- Validation commands must stay file-scoped and run through Sail.
|
|
|
|
## Phase 1: Setup (Shared Context)
|
|
|
|
**Purpose**: confirm the bounded slice, the current Ops-UX truth, and the shell-only guardrail before runtime edits begin.
|
|
|
|
- [ ] T001 Review `specs/268-operationrun-activity-feedback/spec.md`, `specs/268-operationrun-activity-feedback/plan.md`, `specs/268-operationrun-activity-feedback/checklists/requirements.md`, `docs/product/spec-candidates.md`, `docs/product/roadmap.md`, `docs/ui/tenantpilot-enterprise-ui-standards.md`, and `.specify/memory/constitution.md` together so the slice stays on repo-real Ops-UX truth and the manual-promotion guardrail remains explicit.
|
|
- [ ] T002 [P] Confirm the current shared seams in `apps/platform/app/Support/OpsUx/OperationUxPresenter.php`, `apps/platform/app/Support/OpsUx/OperationStatusNormalizer.php`, `apps/platform/app/Support/OpsUx/OperationRunUrl.php`, `apps/platform/app/Support/OpsUx/ActiveRuns.php`, `apps/platform/app/Support/OpsUx/OpsUxBrowserEvents.php`, and `apps/platform/app/Support/OperationRunLinks.php`.
|
|
- [ ] T003 [P] Confirm the current shell host and overlap seam in `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`, `apps/platform/app/Providers/Filament/TenantPanelProvider.php`, `apps/platform/public/js/tenantpilot/ops-ux-progress-widget-poller.js`, and the inherited tenant-prefilter precedence seam in `apps/platform/app/Filament/Pages/Monitoring/Operations.php`.
|
|
- [ ] T004 [P] Confirm current proof and guard coverage in `apps/platform/tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php`, `apps/platform/tests/Feature/OpsUx/ProgressWidgetOverflowTest.php`, `apps/platform/tests/Feature/Monitoring/MonitoringPageStateContractTest.php`, and `apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php`, then record the missing shell-surface proof seam that T005 will introduce through `apps/platform/tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php`.
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: settle the shell contract and proof owners before runtime edits widen.
|
|
|
|
**Critical**: no user-story runtime work should begin until this phase is complete.
|
|
|
|
- [ ] T005 [P] Create or extend failing Feature coverage in `apps/platform/tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php` for hidden tenant/no-capability suppression, canonical overflow navigation with `tenant_id` prefilter precedence over restored session state, terminal-success/follow-up visibility, lifecycle-sensitive tertiary copy, and browser-session hide/dismiss/acknowledge rules.
|
|
- [ ] T006 [P] Extend `apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php` only as needed so the shell continues to use canonical helper families rather than raw route strings.
|
|
- [ ] T007 [P] Add a named browser smoke in `apps/platform/tests/Browser/OpsUx/OperationActivityFeedbackSmokeTest.php` for the non-obstructive shell-hint contract on a row-action-heavy page.
|
|
|
|
**Checkpoint**: the active-only shell contract, link rules, and browser-smoke proof owner are settled before implementation begins.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - See Calm Active-Operations Feedback After Starting Work (Priority: P1)
|
|
|
|
**Goal**: give tenant-scoped start surfaces one calm, truthful active-ops hint that never covers primary actions.
|
|
|
|
**Independent Test**: create queued/running runs, open a tenant-scoped start surface, and verify the shell hint shows at most three active items, one canonical `View operation` link per item, an honest overflow path, and no action obstruction.
|
|
|
|
### Tests for User Story 1
|
|
|
|
- [ ] T008 [P] [US1] Extend `apps/platform/tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php` for hidden/no-capability suppression, active-only visibility, and top-three item limits.
|
|
- [ ] T009 [P] [US1] Extend `apps/platform/tests/Feature/OpsUx/ProgressWidgetOverflowTest.php` for the new visible-item limit and overflow link behavior when more than three active runs exist.
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [ ] T010 [US1] Refactor `apps/platform/app/Livewire/BulkOperationProgress.php` so the shell host queries only queued/running runs and keeps the active-awareness contract local to the existing component.
|
|
- [ ] T011 [US1] Refactor `apps/platform/resources/views/livewire/bulk-operation-progress.blade.php` and `apps/platform/resources/views/livewire/bulk-operation-progress-wrapper.blade.php` to enforce the new visible-item limit, one dominant `View operation` action per item, and non-obstructive shell placement.
|
|
- [ ] T012 [US1] Update `apps/platform/app/Providers/Filament/TenantPanelProvider.php` and `apps/platform/public/js/tenantpilot/ops-ux-progress-widget-poller.js` only as needed to preserve bounded polling and shell lifecycle behavior without reintroducing overlap or duplicate polling loops.
|
|
|
|
**Checkpoint**: User Story 1 is independently functional when the shell shows active operations calmly and without overlap.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Keep The Feedback Loop Honest Across Terminal Transitions (Priority: P1)
|
|
|
|
**Goal**: keep the shell honest when runs become terminal, with a bounded success confirmation and unresolved follow-up visibility in the same surface.
|
|
|
|
**Independent Test**: seed queued/running runs alongside just-completed successful runs and terminal follow-up runs, open a tenant-scoped start surface, and verify the shell keeps recent success visible briefly, keeps unresolved follow-up visible, and never shows fake active progress after completion.
|
|
|
|
### Tests for User Story 2
|
|
|
|
- [ ] T013 [P] [US2] Extend `apps/platform/tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php` for recent terminal-success visibility, terminal follow-up persistence, indeterminate fallback when counts are invalid, the absence of fake active progress after completion, and the at-most-one concise next-step cue rule.
|
|
- [ ] T014 [P] [US2] Extend `apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php` only if needed so shell and overflow links stay on canonical helper families after the refactor.
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [ ] T015 [US2] Ensure `apps/platform/app/Livewire/BulkOperationProgress.php`, `apps/platform/app/Support/OpsUx/ActiveRuns.php`, and the shell views preserve canonical `View operation` / `Show all operations` navigation while adding bounded terminal-success and terminal-follow-up visibility without breaking the inherited tenant-prefilter precedence contract in `apps/platform/app/Filament/Pages/Monitoring/Operations.php`.
|
|
- [ ] T016 [US2] Implement honest progress treatment in the shell: determinate only with valid numeric counts while active, clamped to `0-100`, and never showing fake active progress after terminal transition.
|
|
|
|
**Checkpoint**: User Story 2 is independently functional when the shell closes the feedback loop without inventing a second lifecycle surface.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Keep Hide / Dismiss / Acknowledge Browser-Session Only (Priority: P1)
|
|
|
|
**Goal**: support calmness for queued/running, successful, and unresolved terminal hints without creating an acknowledgement system or server-side preference store.
|
|
|
|
**Independent Test**: use the lifecycle-sensitive tertiary affordance during a browser session, navigate within that session, and verify active items use `Hide activity`, successful terminal items use `Dismiss` or `Close`, unresolved terminal items use `Acknowledge`, and the choice remains local to that browser session.
|
|
|
|
### Tests for User Story 3
|
|
|
|
- [ ] T017 [P] [US3] Extend `apps/platform/tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php` for lifecycle-sensitive tertiary labels, browser-session hide/dismiss/acknowledge persistence, and re-open-on-enqueue behavior.
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [ ] T018 [US3] Add browser-session hide/dismiss/acknowledge behavior to the shell host using a bounded browser-session store only; do not persist state in the database or on the `OperationRun` itself.
|
|
- [ ] T019 [US3] Update `docs/ui/tenantpilot-enterprise-ui-standards.md` with the shell activity-feedback pattern, including canonical links, bounded terminal-success/follow-up scope, tenant-prefiltered overflow navigation, progressbar eligibility, item limits, lifecycle-sensitive tertiary actions, hide/dismiss/acknowledge boundaries, and anti-patterns such as overlays that cover actions or fake percentages.
|
|
- [ ] T020 [US3] Review the resulting implementation to confirm it introduces no second run lifecycle, no new notification policy, no new host-surface activity family, and no database-backed acknowledgement or hide/dismiss model.
|
|
|
|
**Checkpoint**: User Story 3 is independently functional when browser-session calmness stays local and the standards doc records the durable guardrail.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Validation
|
|
|
|
**Purpose**: validate the bounded slice, stop drift, and hand off a clean implementation path.
|
|
|
|
- [ ] T021 [P] Run `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php tests/Feature/OpsUx/ProgressWidgetOverflowTest.php tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php tests/Feature/Guards/OperationRunLinkContractGuardTest.php`.
|
|
- [ ] T022 [P] Run `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/OpsUx/OperationActivityFeedbackSmokeTest.php`.
|
|
- [ ] T023 [P] Run `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` for touched platform files.
|
|
- [ ] T024 [P] Review touched code against `docs/ui/tenantpilot-enterprise-ui-standards.md` and confirm the shell remains decision-first, diagnostics-light, Filament-native, limited to one dominant `View operation` action per item, and bounded to at most one concise next-step cue plus the approved terminal-success/follow-up handoff.
|
|
- [ ] T025 [P] Review touched code to confirm Filament stays on Livewire v4, provider registration remains unchanged in `apps/platform/bootstrap/providers.php`, no new assets were registered, and no new `OperationRun` lifecycle or notification path was introduced.
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Phase 1 (Setup)**: no dependencies; start immediately.
|
|
- **Phase 2 (Foundational)**: depends on Phase 1 and blocks user-story work.
|
|
- **Phase 3 (US1)**: depends on Phase 2 and establishes the active shell contract.
|
|
- **Phase 4 (US2)**: depends on Phase 2 and should ship with US1 so the shell is both calm and closes the feedback loop honestly.
|
|
- **Phase 5 (US3)**: depends on Phase 2 and hardens lifecycle-sensitive calmness/guardrail behavior after the shell contract exists.
|
|
- **Phase 6 (Polish)**: depends on all desired user stories being complete.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **US1 (P1)**: independently testable after Phase 2 and delivers the direct product fix for the overlap seam.
|
|
- **US2 (P1)**: independently testable after Phase 2 and should ship with US1 so the shell aligns with the Ops-UX constitution rather than only moving around visually.
|
|
- **US3 (P1)**: independently testable after Phase 2 and is still required for package completion because lifecycle-sensitive browser-session calmness and the standards-doc guardrail are part of the approved scope.
|
|
|
|
### Within Each User Story
|
|
|
|
- Write the listed Pest coverage first and make it fail for the intended gap.
|
|
- Land shell-host runtime changes before widening browser-session calmness behavior.
|
|
- Re-run the narrowest affected validation command after each story checkpoint before moving on.
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### Suggested MVP Scope
|
|
|
|
- MVP = **US1 + US2 + US3 together**. The manual-promotion target is only complete when the shell is non-obstructive, constitution-safe, closes the terminal feedback loop, and carries the browser-session calmness plus standards-doc guardrail required by the approved scope.
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Complete Phase 1 and Phase 2.
|
|
2. Deliver US1.
|
|
3. Deliver US2 on top of the shell refactor.
|
|
4. Add US3 calmness/standards hardening.
|
|
5. Finish with focused validation and the named browser smoke.
|
|
|
|
### Team Strategy
|
|
|
|
1. Settle the shell contract and browser proof owner first.
|
|
2. Parallelize Feature coverage updates while keeping the browser smoke isolated and explicit.
|
|
3. Serialize merges around `BulkOperationProgress` and the tenant-panel render hook so shell behavior stays coherent.
|
|
|
|
---
|
|
|
|
## Deferred Follow-Ups / Non-Goals
|
|
|
|
- Host-widget operation-state migration beyond the current global active-ops shell widget
|
|
- Polling and UI calmness standard beyond this slice
|
|
- Notification/activity lifecycle standardization beyond the existing start contract
|
|
- Any permanent shell or dashboard inbox treatment for terminal/follow-up operation states beyond the bounded handoff defined here
|
|
- Activity center / tray v2
|
|
- Reviewed / investigated semantics for failed or blocked runs |