# Implementation Plan: Findings Notification Presentation Convergence

**Branch**: `230-findings-notification-convergence` | **Date**: 2026-04-22 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/230-findings-notification-convergence/spec.md`
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/230-findings-notification-convergence/spec.md`

**Note**: This plan keeps the work inside the existing Filament database-notification drawer, the current `notifications` table payload shape, the existing operation-link helpers, and the current `OperationUxPresenter` seam. The intended implementation converges the three in-scope operator-facing database notification consumers on one bounded shared presentation contract. It does not add a table, a notification center, a new panel, a preference system, a new asset family, or new notification-routing semantics.

## Summary

Extend the existing `OperationUxPresenter::terminalDatabaseNotification()` seam into one bounded operator-facing database-notification presentation contract, then align `FindingEventNotification`, `OperationRunQueued`, and `OperationRunCompleted` to that shared structure while preserving their existing deep-link sources, delivery semantics, and domain-specific metadata. Keep the existing Filament database-notification surface, keep the current admin-plane and system-plane run destinations, and add focused regression coverage that proves one primary structure, one status emphasis with the existing Filament icon treatment, one primary action, unchanged authorization behavior, and the preserved FR-015 out-of-scope boundary across the in-scope consumers.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12, Filament v5, Livewire v4, Blade  
**Primary Dependencies**: Laravel database notifications, Filament notifications and actions, `App\Support\OpsUx\OperationUxPresenter`, `App\Notifications\Findings\FindingEventNotification`, `App\Notifications\OperationRunQueued`, `App\Notifications\OperationRunCompleted`, `FindingResource`, `OperationRunLinks`, `SystemOperationRunLinks`, `ReasonPresenter`  
**Storage**: PostgreSQL via the existing `notifications` table and existing `findings` plus `operation_runs` truth; no schema changes planned  
**Testing**: Pest v4 feature tests with notification-payload assertions and route-authorization coverage  
**Validation Lanes**: fast-feedback, confidence
**Target Platform**: Dockerized Laravel web application via Sail locally and Linux containers in deployment  
**Project Type**: Laravel monolith inside the `wt-plattform` monorepo  
**Performance Goals**: Keep notification payload composition request-local, avoid extra N+1 lookups for titles or links, and preserve current drawer rendering without new polling or asset work  
**Constraints**: No schema migration, no new notification center, no new preference model, no new `OperationRun` type or emit point, no change to current queued or terminal run-notification semantics, no global-search changes, and no destructive action paths  
**Scale/Scope**: Three existing notification consumers, one existing shared presenter seam, three existing deep-link helpers, and six focused feature or guard suites

## UI / Surface Guardrail Plan

- **Guardrail scope**: changed surfaces
- **Native vs custom classification summary**: native Filament database-notification drawer and existing detail destinations only
- **Shared-family relevance**: operator-facing database notifications, action links
- **State layers in scope**: shell, detail
- **Handling modes by drift class or surface**: review-mandatory
- **Repository-signal treatment**: review-mandatory
- **Special surface test profiles**: global-context-shell, standard-native-filament
- **Required tests or manual smoke**: functional-core, state-contract
- **Exception path and spread control**: one named exception only; platform-user operation notifications keep their existing system-panel destination while sharing the same card structure and primary action grammar
- **Active feature PR close-out entry**: Guardrail

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes
- **Systems touched**: `FindingEventNotification`, `OperationRunQueued`, `OperationRunCompleted`, `OperationUxPresenter`, `FindingResource`, `OperationRunLinks`, `SystemOperationRunLinks`, the existing Filament database-notification surface
- **Shared abstractions reused**: `OperationUxPresenter::terminalDatabaseNotification()`, `FindingResource::getUrl(...)`, `OperationRunLinks`, `SystemOperationRunLinks`
- **New abstraction introduced? why?**: one bounded shared operator-facing database-notification presentation contract, needed because three real consumers already exist and two still bypass the only shared presenter anchor
- **Why the existing abstraction was sufficient or insufficient**: the current `OperationUxPresenter` seam is sufficient as the starting anchor because it already owns the terminal run-notification grammar. It is insufficient as-is because findings and queued run notifications still build local Filament payloads, which leaves the shared interaction family without one explicit contract.
- **Bounded deviation / spread control**: domain-specific metadata stays namespaced and secondary, and platform-user operation links keep their existing system-panel route. No other divergence from the shared primary structure is allowed in the in-scope consumers.

## Constitution Check

*GATE: Passed before Phase 0 research. Re-check after Phase 1 design.*

| Principle | Pre-Research | Post-Design | Notes |
|-----------|--------------|-------------|-------|
| Shared pattern first (XCUT-001) | PASS | PASS | The plan extends the existing `OperationUxPresenter` seam rather than creating a second local notification grammar or a framework |
| Proportionality / no premature abstraction | PASS | PASS | One bounded shared contract is justified by three real consumers; no registry, factory, or universal notification platform is introduced |
| RBAC-UX / tenant isolation | PASS | PASS | Finding links remain tenant-scoped and operation links keep current admin-plane or system-plane resolution; `404` versus `403` behavior remains unchanged |
| Ops-UX scope discipline | PASS | PASS | The feature does not add new `OperationRun` notifications or emit points; it only converges payload composition for the already-existing queued and terminal notification consumers |
| Filament-native UI / action-surface contract | PASS | PASS | Existing Filament database notifications remain the only shell, each card keeps exactly one primary action, and no destructive action is introduced |
| Livewire v4.0+ / Filament v5 compliance | PASS | PASS | The feature stays within the current Filament v5 and Livewire v4 notification primitives |
| Provider registration / global search / assets | PASS | PASS | Provider registration remains in `apps/platform/bootstrap/providers.php`; no globally searchable resource changes; no new assets, and the existing deploy step `cd apps/platform && php artisan filament:assets` remains sufficient |
| Test governance (TEST-GOV-001) | PASS | PASS | Focused feature and guard coverage prove payload convergence and route safety without browser or heavy-governance expansion |

## Test Governance Check

- **Test purpose / classification by changed surface**: `Feature` for notification presentation convergence, deep-link safety, and guardrail enforcement across the in-scope consumers
- **Affected validation lanes**: `fast-feedback`, `confidence`
- **Why this lane mix is the narrowest sufficient proof**: The risk is shared operator-facing payload drift and route-safety regression, not browser rendering or background orchestration. Focused feature suites plus one guard test prove the contract with minimal cost.
- **Narrowest proving command(s)**:
  - `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`
- **Fixture / helper / factory / seed / context cost risks**: Moderate. Tests need a tenant user, a platform user, a tenant, findings with existing event payloads, operation runs in queued and terminal states, and existing authorization helpers for tenant and system planes.
- **Expensive defaults or shared helper growth introduced?**: no; any shared notification assertion helper should stay local to notification-contract tests and reuse existing factories and route helpers
- **Heavy-family additions, promotions, or visibility changes**: none
- **Surface-class relief / special coverage rule**: `global-context-shell` for drawer payloads that open tenant and system detail pages, with `standard-native-filament` relief because the shell itself remains native Filament
- **Closing validation and reviewer handoff**: Reviewers should rely on the commands above and verify that the in-scope consumers now share the same primary title, body, status with the corresponding existing Filament icon treatment, and action structure; that `reason_translation` and `finding_event` metadata stay secondary; that the platform-user run destination remains `/system/ops/runs/{run}`; that alert delivery, escalation, and `My Work` admission behavior remain untouched; and that no in-scope class still builds its primary payload through a fully local `FilamentNotification::make()->getDatabaseMessage()` path.
- **Budget / baseline / trend follow-up**: none
- **Review-stop questions**: Did the implementation introduce a framework beyond one bounded shared contract? Did any in-scope consumer change its delivery semantics or action target instead of only its presentation path? Did the work widen payload disclosure or flatten plane-specific route rules? Did alert delivery, escalation, or `My Work` admission behavior change? Did a new asset, polling, or custom notification shell appear?
- **Escalation path**: document-in-feature unless convergence pressure expands beyond the current three consumers or requires new persistence, in which case split or follow up with a dedicated spec
- **Active feature PR close-out entry**: Guardrail
- **Why no dedicated follow-up spec is needed**: This feature closes one current-release drift seam across three real consumers without introducing broader notification-platform scope.

## Project Structure

### Documentation (this feature)

```text
specs/230-findings-notification-convergence/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── findings-notification-convergence.logical.openapi.yaml
├── checklists/
│   └── requirements.md
└── tasks.md
```

### Source Code (repository root)

```text
apps/platform/
├── app/
│   ├── Filament/
│   │   ├── Resources/
│   │   │   └── FindingResource.php
│   │   └── System/
│   │       └── Pages/
│   │           └── Ops/
│   │               └── ViewRun.php
│   ├── Notifications/
│   │   ├── Findings/
│   │   │   └── FindingEventNotification.php
│   │   ├── OperationRunCompleted.php
│   │   └── OperationRunQueued.php
│   └── Support/
│       ├── OperationRunLinks.php
│       ├── OpsUx/
│       │   └── OperationUxPresenter.php
│       └── System/
│           └── SystemOperationRunLinks.php
└── tests/
    └── Feature/
        ├── Findings/
        │   ├── FindingsNotificationEventTest.php
        │   └── FindingsNotificationRoutingTest.php
        ├── Notifications/
        │   ├── FindingNotificationLinkTest.php
        │   ├── OperationRunNotificationTest.php
        │   └── SharedDatabaseNotificationContractTest.php
        └── OpsUx/
            └── Constitution/
                └── LegacyNotificationGuardTest.php
```

**Structure Decision**: Standard Laravel monolith. The feature stays inside existing notification classes, presenter helpers, and Pest feature suites. No new base directory, no new panel, and no new persisted model are required.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| One bounded shared database-notification presentation contract | Three real consumers already exist and two still bypass the only shared presenter anchor | Separate local edits would preserve parallel primary grammars and keep the interaction family drifting |

## Proportionality Review

- **Current operator problem**: Operators see finding and operation notifications through different primary structures even though both are the same secondary context surface.
- **Existing structure is insufficient because**: `OperationUxPresenter` currently covers only terminal operation notifications, while findings and queued operation notifications still compose their payloads locally.
- **Narrowest correct implementation**: Extend the existing presenter seam into one bounded database-notification contract, align the current three real consumers, and stop there.
- **Ownership cost created**: One shared presentation seam, small contract-level assertions, and maintenance of the domain-specific secondary metadata boundaries.
- **Alternative intentionally rejected**: A universal notification platform, a new notification page, or consumer-by-consumer local tweaks. These either add premature infrastructure or fail to solve the shared-interaction drift.
- **Release truth**: Current-release truth. This is a convergence change for already-existing operator-facing notifications.

## Phase 0 Research

Research outcomes are captured in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/230-findings-notification-convergence/research.md`.

Key decisions:

- Reuse `OperationUxPresenter` as the shared anchor and extend it rather than creating a new notification framework.
- Standardize the primary title, body, status, and action structure only; keep domain-specific metadata such as `finding_event` and `reason_translation` secondary and namespaced.
- Preserve deep-link truth through `FindingResource::getUrl(...)`, `OperationRunLinks`, and `SystemOperationRunLinks` rather than rebuilding routes in notification classes.
- Keep the existing Filament database-notification drawer, existing `notifications` table payload storage, and current deploy asset strategy unchanged.
- Prove convergence through focused feature and guard tests instead of browser coverage, including an explicit guard on the FR-015 out-of-scope boundary.

## Phase 1 Design

Design artifacts are created under `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/230-findings-notification-convergence/`:

- `research.md`: design decisions and rejected alternatives for the shared presentation seam
- `data-model.md`: existing notification truth plus the derived shared presentation contract and consumer input shapes
- `contracts/findings-notification-convergence.logical.openapi.yaml`: internal logical contract for shared database-notification presentation and the preserved destination routes
- `quickstart.md`: focused implementation and review workflow

Design decisions:

- No schema migration is required; the feature only changes derived payload composition in the existing `notifications` table.
- The canonical shared seam is an extension of the existing `OperationUxPresenter` path, not a new registry or interface family.
- In-scope consumers retain one primary action and keep their current deep-link authority: tenant finding view, admin operation view, or system operation view.
- Domain-specific metadata remains secondary and opt-in: findings keep `finding_event`, completed runs keep `reason_translation` and diagnostic fields, and queued runs keep only the minimal supporting context they already need.
- Existing delivery semantics from Spec 224 and current operation notification behavior remain unchanged.

## Phase 1 Agent Context Update

Run:

- `.specify/scripts/bash/update-agent-context.sh copilot`

## Constitution Check — Post-Design Re-evaluation

- PASS - the design stays inside current notification and presenter seams with no new persistence, no Graph work, no new capability family, and no new frontend assets.
- PASS - Livewire v4.0+ and Filament v5 constraints remain satisfied, provider registration stays in `apps/platform/bootstrap/providers.php`, no globally searchable resource behavior changes, no destructive action is introduced, and the existing deploy step `cd apps/platform && php artisan filament:assets` remains unchanged.

## Implementation Strategy

### Phase A - Define the shared database-notification presentation seam on the existing presenter anchor

**Goal**: Establish one bounded shared primary payload structure without creating a new framework.

| Step | File | Change |
|------|------|--------|
| A.1 | `apps/platform/app/Support/OpsUx/OperationUxPresenter.php` | Add one shared operator-facing database-notification builder path that standardizes title, body, status with the existing Filament icon treatment, one primary action, and optional supporting lines for the in-scope consumers |
| A.2 | `apps/platform/app/Support/OpsUx/OperationUxPresenter.php` | Preserve the current terminal run-specific presentation logic by feeding it into the shared builder rather than bypassing it |
| A.3 | `apps/platform/app/Support/OpsUx/OperationUxPresenter.php` | Keep any extraction bounded to the existing namespace and avoid registries, factories, or a universal notification taxonomy |

### Phase B - Align findings notifications to the shared contract

**Goal**: Remove the local primary payload grammar from `FindingEventNotification` while preserving Spec 224 delivery and metadata semantics.

| Step | File | Change |
|------|------|--------|
| B.1 | `apps/platform/app/Notifications/Findings/FindingEventNotification.php` | Replace the local `FilamentNotification::make()` primary payload build with the shared presentation seam |
| B.2 | `apps/platform/app/Notifications/Findings/FindingEventNotification.php` | Preserve `FindingResource::getUrl('view', ...)` as the action target and keep `finding_event` metadata keys unchanged |
| B.3 | `apps/platform/app/Notifications/Findings/FindingEventNotification.php` | Keep recipient-reason language secondary and subordinate to the shared primary body structure |

### Phase C - Align queued and terminal operation notifications to the same contract

**Goal**: Keep current operation notification semantics while eliminating the second local primary payload grammar.

| Step | File | Change |
|------|------|--------|
| C.1 | `apps/platform/app/Notifications/OperationRunQueued.php` | Replace local payload composition with the shared contract while preserving current queued copy and current link-resolution rules |
| C.2 | `apps/platform/app/Notifications/OperationRunCompleted.php` | Keep terminal presentation, summary lines, and reason-translation metadata, but route the primary card structure through the same shared contract |
| C.3 | `apps/platform/app/Support/OperationRunLinks.php` and `apps/platform/app/Support/System/SystemOperationRunLinks.php` | Verify canonical action labels and plane-specific route generation remain authoritative, and apply only minimal normalization if the shared contract needs a common label accessor |

### Phase D - Preserve route and scope truth across tenant and system destinations

**Goal**: Ensure shared presentation does not flatten or widen current access rules.

| Step | File | Change |
|------|------|--------|
| D.1 | `apps/platform/app/Notifications/Findings/FindingEventNotification.php` | Preserve tenant-panel finding detail routing and current `404` versus `403` behavior |
| D.2 | `apps/platform/app/Notifications/OperationRunQueued.php` and `apps/platform/app/Notifications/OperationRunCompleted.php` | Preserve current admin-plane, tenantless, and platform-user system-plane route selection |
| D.3 | Existing Filament notification shell | Keep the existing database-notification drawer as the only collection surface; do not add polling, a new page, or a second notification center |

### Phase E - Lock the shared contract with focused regression coverage

**Goal**: Make future local bypasses of the shared primary structure visible in CI.

| Step | File | Change |
|------|------|--------|
| E.1 | `apps/platform/tests/Feature/Notifications/SharedDatabaseNotificationContractTest.php` | Add direct contract-level assertions for the shared primary structure, including shared status-to-icon treatment, across findings, queued runs, and completed runs |
| E.2 | `apps/platform/tests/Feature/Notifications/OperationRunNotificationTest.php` | Update queued and terminal operation notification tests to assert shared structure plus preserved route, status, and metadata behavior |
| E.3 | `apps/platform/tests/Feature/Notifications/FindingNotificationLinkTest.php` | Update finding notification tests to assert shared structure, shared status semantics, and unchanged tenant-safe action behavior |
| E.4 | `apps/platform/tests/Feature/Findings/FindingsNotificationEventTest.php` and `apps/platform/tests/Feature/Findings/FindingsNotificationRoutingTest.php` | Keep Spec 224 event and recipient semantics protected while the presentation path changes underneath them |
| E.5 | `apps/platform/tests/Feature/OpsUx/Constitution/LegacyNotificationGuardTest.php` | Extend the guard so future in-scope notification consumers cannot silently bypass the shared primary presentation seam and so alert delivery, escalation, and `My Work` admission behavior stay outside this spec |

### Phase F - Validate formatting and the narrow proving set

**Goal**: Close the feature with the smallest executable proof set.

| Step | File | Change |
|------|------|--------|
| F.1 | `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` | Normalize style for touched PHP files |
| F.2 | `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Notifications/SharedDatabaseNotificationContractTest.php tests/Feature/Notifications/OperationRunNotificationTest.php tests/Feature/Notifications/FindingNotificationLinkTest.php` | Prove the shared contract and preserved destination semantics |
| F.3 | `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` | Prove no regression in Spec 224 behavior, no reintroduction of local notification bypasses, and no accidental expansion into alert or `My Work` behavior |