ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
a146b14208
TenantAtlas/specs/268-operationrun-activity-feedback/tasks.md
ahmido 867bd92370 Automated: 268-operationrun-activity-feedback — commit & PR (#324) 
Automated commit and PR created by agent. Branch: 268-operationrun-activity-feedback-session-1777896580

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #324
2026-05-04 12:17:15 +00:00

15 KiB
Raw Blame History

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