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