TenantAtlas/specs/230-findings-notification-convergence/quickstart.md

Quickstart: Findings Notification Presentation Convergence

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, one tenant operator, one platform user, one finding notification trigger, and one queued plus one completed operation run.

3. Remember that the feature changes only the existing Filament database-notification drawer. No new page or panel is expected during validation.

4. Filament database-notification polling is intentionally conservative in this repo, so reload or reopen the 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/Notifications/SharedDatabaseNotificationContractTest.php tests/Feature/Notifications/OperationRunNotificationTest.php tests/Feature/Notifications/FindingNotificationLinkTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingsNotificationEventTest.php tests/Feature/Findings/FindingsNotificationRoutingTest.php tests/Feature/OpsUx/Constitution/LegacyNotificationGuardTest.php

Manual Validation Flow

1. Compare finding and operation notifications in the same drawer

1. Trigger one finding notification using an existing Spec 224 event.
2. Trigger one queued operation notification and one completed operation notification.
3. Reload the shell and open the database-notification drawer.
4. Confirm all three cards show the same primary structure order:
   • title naming the target object
   • primary body summarizing the change
   • one status emphasis with the existing Filament icon treatment
   • exactly one primary action
   • optional supporting context beneath the primary body

2. Validate finding notification semantics remain unchanged

1. Open the finding notification card.
2. Confirm the action label remains Open finding.
3. Confirm the action opens the existing tenant finding detail page.
4. Confirm recipient-reason language and finding severity remain visible only as supporting context or metadata, not as a replacement for the primary title or body.

3. Validate queued and completed operation notification semantics remain unchanged

1. Open the queued run notification card.
2. Confirm it still communicates the queued state and opens the existing run destination for that notifiable context.
3. Open the completed run notification card.
4. Confirm terminal summary, failure guidance, and reason translation remain present as supporting context when applicable.

4. Validate tenant-plane and system-plane route truth

1. Open a finding notification as an entitled tenant user and confirm the tenant detail route opens.
2. Open an operation notification as a workspace operator and confirm the current admin or tenantless run destination opens.
3. Open an operation notification as a platform user and confirm the action resolves to /system/ops/runs/{run}.
4. Confirm no shared presentation change causes the wrong route family to appear.

5. Validate authorization behavior did not change

1. Create a finding notification for an entitled tenant user.
2. Remove that user’s tenant visibility or capability.
3. Open the finding notification link and confirm the existing 404 versus 403 semantics remain authoritative.
4. Repeat the same check for an operation notification where route visibility changes by plane or entitlement.

6. Validate no second shell or asset change appeared

1. Confirm the existing Filament notification drawer remains the only collection surface.
2. Confirm no custom notification page, custom card shell, or new asset bundle appears.
3. Confirm the feature does not require any new deploy step beyond the existing Filament assets pipeline.

7. Validate the FR-015 boundary stayed intact

1. Confirm no alert-rule routing, alert delivery, or escalation behavior changed as part of this feature.
2. Confirm no My Work queue, admission rule, or dashboard clone was introduced.
3. Confirm the only changed surface is the existing in-app database notification presentation for the in-scope consumers.

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 cd apps/platform && php artisan filament:assets step remains sufficient.