TenantAtlas/specs/224-findings-notifications-escalation/quickstart.md

Quickstart: Findings Notifications & Escalation v1

Prerequisites

1. Start the local platform stack.

   cd apps/platform && ./vendor/bin/sail up -d
   

2. Work with a workspace that has at least one tenant, two tenant users, and existing findings data.

3. Ensure you can create or edit alert rules and inspect alert deliveries in the admin panel.

4. Remember that Filament database notification polling is intentionally disabled in this repo, so reload the page or reopen the notification drawer after each trigger when validating manually.

Automated Validation

Run formatting and the narrowest proving suites for this feature:

cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingsNotificationEventTest.php tests/Feature/Findings/FindingsNotificationRoutingTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Alerts/FindingsAlertRuleIntegrationTest.php tests/Feature/Alerts/SlaDueAlertTest.php tests/Feature/Notifications/FindingNotificationLinkTest.php

Manual Validation Flow

1. Confirm alert-rule event types are available

1. Open the admin panel alert-rule create or edit form.
2. Verify the event selector contains:
   • Finding assigned
   • Finding reopened
   • Finding due soon
   • Finding overdue
3. Save a rule that targets one of the new event types and confirm the Alert deliveries viewer can filter and label it correctly.

1b. Validate admin alert-surface RBAC semantics

1. As a workspace member with ALERTS_VIEW but without ALERTS_MANAGE, confirm the existing alert-rule and alert-delivery read surfaces open successfully while alert-rule mutation stays forbidden.
2. As an in-scope workspace member without ALERTS_VIEW, confirm the existing alert-rule and alert-delivery view surfaces return 403.
3. As a non-member or wrong-workspace user, confirm the existing alert-rule and alert-delivery surfaces return 404.

2. Validate direct assignment notification

1. Start with an open finding that has no assignee or a different assignee.
2. Assign the finding to a new entitled operator.
3. Reload the shell and open the database notification drawer.
4. Confirm the new assignee receives exactly one notification with:
   • the finding vocabulary
   • an explanation that the finding was assigned to them
   • one Open finding action
5. Confirm owner-only changes, assignee clears, and no-op saves emit no assignment notification.

3. Validate automatic reopen notification

1. Start with a terminal finding that still has an assignee or owner.
2. Trigger the existing system path that reopens the finding through recurring detection.
3. Reload the shell and confirm one Finding reopened notification reaches the current assignee, or the current owner if no assignee exists.
4. Confirm manual reopen remains silent in v1.

4. Validate due-soon and overdue direct delivery

1. Prepare two open findings:

   • one with due_at inside the next 24 hours
   • one with due_at already in the past

2. Run the existing alert-evaluation command for the target workspace.

   cd apps/platform && ./vendor/bin/sail artisan tenantpilot:alerts:dispatch --workspace=<workspace-id>
   

3. Reload the notification drawer.

4. Confirm:

   • due soon goes to the current assignee, else the current owner
   • overdue goes to the current owner, else the current assignee
   • if owner and assignee are the same user, only one direct notification is created

5. Run the same command again without changing due_at or reopening the finding and confirm no duplicate due-soon or overdue direct notification is created for the current cycle.

6. Recalculate the due cycle through the existing lifecycle contract, then rerun evaluation and confirm one fresh due notification can emit for the new cycle.

5. Validate optional external copies through existing alert rules

1. Enable an alert rule for one of the new finding event types with a real destination.
2. Trigger the corresponding event again.
3. Confirm the direct responsible-user notification still appears.
4. Confirm one or more Alert deliveries rows are created only when a matching enabled rule exists.
5. Confirm the existing tenant-level aggregate sla_due alert behavior remains unchanged.

6. Validate entitlement-safe deep links

1. Create a direct finding notification for an entitled recipient.
2. Remove that user’s tenant membership or findings-view capability.
3. Open the notification action URL.
4. Confirm the existing route behavior remains authoritative:
   • hidden tenant or record paths stay 404
   • in-scope but unauthorized access stays 403
5. Confirm the notification title and body never broaden disclosure beyond the existing finding summary vocabulary.

Reviewer Notes

• The feature is Livewire v4.0+ compatible and stays on existing Filament v5 primitives.
• Provider registration remains unchanged in apps/platform/bootstrap/providers.php.
• No globally searchable resource behavior changes in this feature.
• No new destructive action is introduced, so no new confirmation flow is required.
• Asset strategy is unchanged: no new panel or shared assets, and the existing deploy filament:assets step remains sufficient.