TenantAtlas/specs/268-operationrun-activity-feedback/plan.md

Implementation Plan: OperationRun Activity Feedback v1

Branch: 268-operationrun-activity-feedback | Date: 2026-05-03 | Spec: spec.md Input: Feature specification from /specs/268-operationrun-activity-feedback/spec.md

Summary

This plan prepares one bounded Ops-UX slice over the repo's existing OperationRun truth. The implementation path is to refactor the current tenant-shell activity widget so it becomes non-obstructive, honest about active progress, and capable of showing a brief terminal-success or unresolved terminal follow-up handoff in the same surface, then record the durable shell guardrail in docs/ui/tenantpilot-enterprise-ui-standards.md. The slice must stay on current OperationRun truth, current start toasts, current Operations drill-through pages, and current badge/link helpers with no new persistence, no new lifecycle, no new notification policy, no new active-awareness host surface, and no tray/inbox expansion.

Filament remains on Livewire v4, no panel-provider registration changes are required (apps/platform/bootstrap/providers.php remains authoritative), no globally searchable resource is added, and no asset registration change is expected.

Inherited Baseline / Explicit Delta

Inherited baseline

• OperationRun already provides the execution-truth model and current tenant/workspace scoping.
• OperationUxPresenter, OperationStatusNormalizer, OperationRunLinks, and OperationRunUrl already provide truthful run guidance, badge semantics, and canonical links.
• BulkOperationProgress plus the current poller already provide tenant-shell activity surfacing, albeit in an obstructive floating form.
• OperationRunLinkContractGuardTest and the current Ops-UX Feature tests already enforce parts of the link and host-surface contract.

Explicit delta in this plan

• narrow the current BulkOperationProgress shell contract to one bounded activity surface and end its obstructive overlay behavior
• keep progress treatment honest and constitution-safe, including no fake active progress after terminal transition
• add a brief terminal-success handoff and unresolved terminal follow-up visibility on the same surface
• add browser-session hide/dismiss/acknowledge behavior without introducing persistence
• update docs/ui/tenantpilot-enterprise-ui-standards.md with the durable shell activity-feedback guardrail

Technical Context

Language/Version: PHP 8.4, Laravel 12, Filament v5, Livewire v4
Primary Dependencies: current Ops-UX support classes, native Filament widgets/Blade, current badge infrastructure, Pest v4
Storage: PostgreSQL via existing operation_runs; browser-session state only for allowed collapse behavior; no new DB storage
Testing: Pest Feature coverage plus one required browser smoke
Validation Lanes: fast-feedback, confidence, browser Target Platform: existing Laravel monolith in apps/platform, admin/operator plane only
Project Type: Web application (Laravel monolith with Filament)
Performance Goals: bounded shell/start-surface rendering, no new query families beyond current run reads, no duplicate polling loops, and max-three item presentation on the shell host
Constraints: no new persistence, no new lifecycle/state family, no new notification policy, no tray v2, and no panel/provider/asset changes
Scale/Scope: one current host surface, one standards update, one browser-session calmness rule

Likely Affected Repo Surfaces

• 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/OperationRunLinks.php
• apps/platform/app/Support/OpsUx/ActiveRuns.php
• 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/app/Filament/Pages/Monitoring/Operations.php (inherited tenant-prefilter precedence seam)
• apps/platform/public/js/tenantpilot/ops-ux-progress-widget-poller.js
• apps/platform/tests/Feature/OpsUx/...
• apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php
• apps/platform/tests/Feature/Monitoring/MonitoringPageStateContractTest.php (inherited state-contract coverage)
• apps/platform/tests/Browser/OpsUx/...
• docs/ui/tenantpilot-enterprise-ui-standards.md

UI / Filament & Livewire Fit

• Keep the changed shell host Filament-native. It may remain a Livewire shell entrypoint, but the refactor should stay local to the existing shell component and views instead of introducing a second host surface.
• The shell host stays decision-first. It shows at most three visible items, one dominant View operation action per item, one canonical overflow path, and only the minimum run state needed for the next operator decision.
• Monitoring collection/detail pages remain diagnostics-first drill-through targets. The shell must not re-state their evidence-heavy content.
• Browser-session hide/dismiss/acknowledge stays local to the current browser session and does not create a server-side acknowledgement model.
• Keep custom markup narrow and standards-aligned. Avoid page-local progress bar colors, host-specific card systems, fake percentages, or percentage text.
• No new asset registration, panel configuration, or provider registration change is planned.

RBAC / Policy Fit

• Existing OperationRun policies remain the first and only visibility gate.
• The tenant shell host derives rows only after tenant context and policy filtering.
• The shell overflow path must preserve the selected tenant as the initial tenant_id contextual prefilter on the canonical Operations page; restored session filters may narrow inside that tenant scope but must not broaden beyond it.
• Tenant/admin plane behavior stays unchanged: no cross-plane expansion and no new authorization surface.
• No new mutation or retry action is introduced, so current confirmation/authorization behavior stays on existing start surfaces and run detail pages.

Audit / Logging Fit

• Existing queued toasts and terminal DB notifications remain authoritative and unchanged.
• Existing run audit/Monitoring behavior remains the only audit trail. No new page-view audit stream is introduced.
• Because the slice changes presentation only, OperationRun.status / OperationRun.outcome ownership remains service-owned and unchanged.

Data & Query Fit

• The shell host continues to derive rows from current-tenant OperationRun truth, limits visible presentation to three items, and uses overflow navigation for the rest.
• Determinate progress must derive from truthful run-owned counts only while the run is active. If a run becomes terminal, the shell switches to terminal-success or terminal-follow-up semantics instead of reusing the active progress UI.
• Hide, dismiss, and acknowledge state remain browser-session scoped and must not be persisted in the database or on the run record.

UI / Surface Guardrail Plan

• Guardrail scope: changed surfaces
• Native vs custom classification summary: native Filament plus a bounded local shell refactor
• Shared-family relevance: Ops UX start feedback, canonical run links
• State layers in scope: shell, page, browser-session
• Audience modes in scope: operator-MSP
• Decision/diagnostic/raw hierarchy plan: decision-first on the shell host, diagnostics-first on Operations collection/detail
• Raw/support gating plan: raw/support evidence stays on the existing diagnostics surfaces only
• One-primary-action / duplicate-truth control: each shell item keeps one dominant View operation action, overflow navigation stays collection-only, the tertiary affordance is lifecycle-sensitive, and the shell does not duplicate detail-surface diagnostics
• Handling modes by drift class or surface: review-mandatory
• Repository-signal treatment: review-mandatory
• Special surface test profiles: global-context-shell
• Required tests: functional-core, state-contract, named-browser-smoke
• Exception path and spread control: none planned; any attempt to add host-specific run-state cards or persisted hide semantics resolves as reject-or-split
• Active feature PR close-out entry: Guardrail / Smoke Coverage

Shared Pattern & System Fit

• Cross-cutting feature marker: yes
• Systems touched: current shell hint, canonical run links, current run guidance, current activity poller, UI standards
• Shared abstractions reused: OperationUxPresenter, OperationStatusNormalizer, OperationRunLinks, OperationRunUrl, ActiveRuns, OpsUxBrowserEvents, current badge infrastructure
• New abstraction introduced? why?: none planned by default; keep the change local to the existing shell component unless a tiny helper is strictly needed for readability
• Why the existing abstraction was sufficient or insufficient: the repo already owns truthful state and links; the missing piece is a constitution-aligned shell contract, not a new framework
• Bounded deviation / spread control: do not create a multi-profile registry, strategy system, or separate persisted activity model

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes, for start-surface follow-through, terminal handoff, and drill-through links only
• Central contract reused: current Ops-UX start contract via OperationUxPresenter, OperationRunLinks, OperationRunUrl, and OpsUxBrowserEvents
• Delegated UX behaviors: queued toast wording, canonical view/collection links, current browser-event dispatch, and existing terminal DB notifications remain delegated to the shared contract
• Surface-owned behavior kept local: bounded shell layout, brief terminal-success/follow-up visibility, and browser-session hide/dismiss/acknowledge only
• Queued DB-notification policy: N/A - unchanged
• Terminal notification path: unchanged central lifecycle mechanism
• Exception path: none

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: no
• Provider-owned seams: N/A
• Platform-core seams: existing OperationRun truth, links, and operator vocabulary only
• Neutral platform terms / contracts preserved: Operation, View operation, Show all operations, queued, running, active
• Retained provider-specific semantics and why: none
• Bounded extraction or follow-up path: none

Constitution Check

GATE: Must pass before implementation begins and again before merge.

• Inventory-first: PASS. The slice is fully derived from existing OperationRun truth.
• Read/write separation: PASS. No new write path or retry surface is introduced.
• Graph contract path: PASS. No Graph/provider interaction is added.
• Deterministic capabilities: PASS. Existing OperationRun policies remain authoritative.
• RBAC-UX: PASS. No plane expansion; tenant/admin visibility stays on current guards and deny-as-not-found semantics.
• Run observability: PASS. Existing start contract, terminal notifications, and Monitoring ownership remain unchanged while the shell adds only a bounded terminal handoff.
• Ops-UX lifecycle: PASS. No change to service-owned status/outcome transitions or summary_counts semantics.
• Data minimization: PASS. Hosts stay compact and do not surface raw evidence by default.
• Test governance: PASS. Proof stays bounded to Feature plus one named browser smoke for the overlap contract.
• Proportionality / no premature abstraction: PASS. The default implementation stays local to the existing shell host and standards doc.
• Persisted truth / behavioral state: PASS. No new table, no new lifecycle, no new persisted hide/dismiss/acknowledge state.
• Shared pattern first / UI semantics / Filament-native UI: PASS. Existing helpers and badge semantics stay central, and the shell host moves closer to the existing Ops-UX contract.
• Provider boundary: PASS. No provider/platform seam changes.
• Filament/Laravel panel safety: PASS. Filament v5 stays on Livewire v4, provider registration remains in apps/platform/bootstrap/providers.php, and no new assets are planned.

Gate evaluation: PASS.

Test Governance Check

• Test purpose / classification by changed surface: Feature for shell behavior; one required browser smoke for the overlap/non-obstruction contract
• Affected validation lanes: fast-feedback, confidence, browser
• Why this lane mix is the narrowest sufficient proof: Feature coverage proves real tenant context, active plus bounded terminal visibility, links, lifecycle-sensitive tertiary copy, and progress rules on the current shell host; browser proof is reserved for the one contract that depends on real clickability/layout
• Narrowest proving command(s):
  • 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
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/OpsUx/OperationActivityFeedbackSmokeTest.php
• Fixture / helper / factory / seed / context cost risks: moderate; reuse current operation-run factories and tenant helpers instead of introducing new provider-heavy defaults or persistence fixtures
• Expensive defaults or shared helper growth introduced?: no
• Heavy-family additions, promotions, or visibility changes: none
• Surface-class relief / special coverage rule: global-context-shell
• Closing validation and reviewer handoff: reviewers should rerun the focused commands above, then manually verify that the shell hint no longer covers row-level actions on a page with active runs. They should also review the standards-doc update for canonical link/progress rules.
• Budget / baseline / trend follow-up: none expected beyond a small feature-local increase
• Review-stop questions: did the shell stay bounded, did terminal success/follow-up remain truthful, did it remain non-obstructive, did any raw route strings reappear, and did hide/dismiss/acknowledge stay browser-session-only?
• Escalation path: reject-or-split for any persisted hide model, activity center expansion, or notification-policy change
• Active feature PR close-out entry: Guardrail / Smoke Coverage
• Why no dedicated follow-up spec is needed: this package already carries the standards-doc guardrail for the chosen v1 slice; larger tray/lifecycle topics remain explicit follow-up specs rather than hidden work here.

Project Structure

Documentation (this feature)

specs/268-operationrun-activity-feedback/
├── spec.md
├── plan.md
├── tasks.md
└── checklists/
    └── requirements.md

This preparation package intentionally stays on the core artifacts plus the readiness checklist. The repo already contains the relevant Ops-UX truth, current host surfaces, and adjacent tests, so no extra research, data-model, or contract package is required for a bounded implementation handoff.

Source Code (expected implementation surfaces)

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
apps/platform/tests/Feature/OpsUx/...
apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php
apps/platform/tests/Browser/OpsUx/...
docs/ui/tenantpilot-enterprise-ui-standards.md

Structure Decision: keep the implementation local to the existing Ops-UX Livewire shell seams. Do not introduce a new multi-host activity framework in this slice.

Data / Migration Implications

• No migration or new table is planned.
• No new persisted user preference is allowed.
• No new cache layer, backfill, or asset/deploy step should be required for v1.

Rollout Considerations

• Filament remains v5 on Livewire v4. No panel-provider change is required, and provider registration remains in apps/platform/bootstrap/providers.php.
• No global search change is required because the slice changes widgets/shell feedback, not resources.
• No destructive action is added. Existing start/retry surfaces remain the only mutation owners.
• No new asset registration is expected.

Risk Controls

• Reject any implementation that introduces a new OperationRun lifecycle, persisted hide model, or persistent acknowledgement workflow.
• Reject any implementation that widens the slice into tray v2, notification policy changes, or any new host-surface migration beyond the current global active-ops shell widget.
• Reject any implementation that keeps or reintroduces a fixed overlay that covers page actions.
• Reject any implementation that uses fake progress percentages, percentage text, terminal runs in the shell, or raw route strings.

Implementation Phases

Phase 0 - Confirm Current Ops-UX Truth

• Verify the current shell host, current link helpers, and current overlap/regression tests.

Phase 1 - Encode The Shell Activity Contract

• Keep the shell query and rendering derived from current OperationRun truth only.
• Keep active, terminal-success, and terminal-follow-up semantics bounded to the same shell host.

Phase 2 - Migrate The Shell Hint

• End the obstructive floating-overlay behavior while keeping bounded polling.

Phase 3 - Record The Guardrail And Calmness Rules

• Update the UI standards doc with canonical link, bounded terminal-success/follow-up scope, progress, and hide/dismiss/acknowledge rules.

Phase 4 - Harden Browser-Session Calmness And Validation

• Add browser-session hide/dismiss/acknowledge only for allowed informational items.
• Run the focused test suite and browser smoke.

Proportionality Review

• Current operator problem: the repo has truthful run-state helpers, but the current shell hint is obstructive and does not encode the active-only, honest-progress contract clearly.
• Existing structure is insufficient because: the current shell implementation leaves key Ops-UX rules implicit and therefore easy to regress even if the underlying run truth is correct.
• Narrowest correct implementation: refactor the existing shell component and views locally, keep the query active-only, add browser-session calmness, and update the standards doc.
• Ownership cost created: one browser-session calmness rule and focused test/doc updates.
• Alternative intentionally rejected: a shell-only CSS adjustment was rejected because it would not encode the active-only and honest-progress rules or leave a durable guardrail for future work.
• Release truth: current-release truth. The repo already owns the active-ops widget and the Ops-UX constitution; this slice aligns the current shell to that truth.