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

Feature Specification: Findings Notification Presentation Convergence

Feature Branch: 230-findings-notification-convergence
Created: 2026-04-22
Status: Draft
Input: User description: "Findings Notification Presentation Convergence"

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: Findings notifications now work functionally, but operator-facing database notifications speak through two different presentation paths. FindingEventNotification composes its payload locally, while operation notifications partially rely on an existing shared presentation path. The same interaction class therefore appears with different title/body/action grammar.
• Today's failure: An operator who receives both finding and operation notifications must re-interpret which text is primary, what the action button means, and whether extra context is actionable or diagnostic. On the product side, each new notification-bearing domain is encouraged to ship another local payload shape.
• User-visible improvement: Operators receive finding and operation notifications with one shared structure: a title naming the target object, a primary body summarizing the change, one status emphasis that drives the existing Filament icon treatment, exactly one primary action, consistent deep-link behavior, and optional supporting context that never displaces the next step.
• Smallest enterprise-capable version: Inventory the current operator-facing database notification consumers, define one bounded shared presentation contract for database notification payloads, align finding event notifications and current operation-run notifications to it, and add regression guard coverage.
• Explicit non-goals: No redesign of alert routing or recipient resolution, no notification preference center, no second notification center, no new workflow queue, no full historical sweep of every notification class in the repo, and no generalized notification platform beyond current operator-facing database notifications.
• Permanent complexity imported: One bounded shared database-notification presentation contract, one small shared presenter or builder path for current consumers, focused regression tests, and explicit guardrail notes for future in-scope notification types.
• Why now: Spec 224 just introduced findings notifications, and Constitution XCUT-001 now explicitly blocks silent parallel shared-interaction paths. This is the cheapest moment to converge before more domains copy the local findings pattern.
• Why not local: A finding-only wording tweak would still leave findings and operation notifications on separate payload grammars. The gap is shared interaction drift, not one isolated title string.
• Approval class: Cleanup
• Red flags triggered: One bounded shared presenter or builder path and one multi-consumer convergence slice. This remains acceptable because three real consumers already exist today (FindingEventNotification, OperationRunQueued, OperationRunCompleted) and the feature removes parallel UX language instead of creating a speculative framework.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitat: 2 | Produktnahe: 2 | Wiederverwendung: 2 | Gesamt: 12/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes:
  • Existing Filament database notification surface in admin /admin and tenant /admin/t/{tenant}/... shells
  • /admin/t/{tenant}/findings/{finding} as the finding follow-up destination
  • /admin/operations/{run} as the existing admin-plane operation destination
  • Existing system-panel run detail destination for platform users receiving operation notifications
• Data Ownership:
  • Existing database notification rows remain delivery artifacts only and do not become a second workflow state store.
  • Tenant-owned findings remain the only source of truth for finding notification content, severity, and deep links.
  • Operation runs remain the only source of truth for operation notification content, status or outcome meaning, and deep links.
  • Workspace-owned alert rules and alert deliveries remain outside the change scope except where current Spec 224 behavior must remain intact.
• RBAC:
  • Existing workspace and tenant membership plus findings-view authorization continue to gate finding notification payload visibility and deep links.
  • Existing admin-plane or system-plane run visibility continues to gate operation notification links.
  • Notification presentation must not widen disclosure; payloads and action links only expose records the recipient may already inspect.
  • Non-members and out-of-scope users remain 404; in-scope users missing a required capability remain 403 on protected destinations.

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

• Cross-cutting feature?: yes
• Interaction class(es): notifications, action links
• Systems touched:
  • App\Notifications\Findings\FindingEventNotification
  • App\Notifications\OperationRunQueued
  • App\Notifications\OperationRunCompleted
  • Existing Filament database notification surface
  • Existing finding and operation deep-link helpers
• Existing pattern(s) to extend:
  • Existing operator-facing database notification surface
  • App\Support\OpsUx\OperationUxPresenter::terminalDatabaseNotification()
  • Existing canonical deep-link helpers for findings and operation runs
• Shared contract / presenter / builder / renderer to reuse:
  • Extend the current OperationUxPresenter::terminalDatabaseNotification() path into one bounded shared operator-facing database notification contract reused by FindingEventNotification, OperationRunQueued, and OperationRunCompleted
  • Preserve current deep-link generation through FindingResource::getUrl(...), OperationRunLinks, and SystemOperationRunLinks
• Why the existing shared path is sufficient or insufficient: The existing path is sufficient as a starting anchor because a real shared presenter already exists for terminal operation notifications and stable deep-link helpers already exist. It is insufficient in its current form because queued operation notifications and findings notifications still compose local Filament payloads, so the interaction class does not yet have one explicit shared contract.
• Allowed deviation and why: bounded exception only. Domain-specific supporting context may differ between finding and operation notifications, and platform-user operation links may keep their system-plane destination, but title/body/action structure and primary deep-link behavior must stay aligned.
• Consistency impact: Title/body hierarchy, status semantics with the corresponding existing Filament icon treatment, primary action placement, action-label grammar, optional supporting context rules, and deep-link trust must stay aligned across in-scope notification families.
• Review focus: Reviewers must verify that in-scope operator-facing database notifications extend the shared contract instead of locally calling FilamentNotification::make()->getDatabaseMessage() for primary structure, and that deep-link helpers remain canonical rather than being rebuilt inside notification classes.

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Finding event database notifications	yes	Existing Filament database notification surface plus existing finding notification class	Same operator-facing database notification family as operation notifications	title, body, tone, primary action, supporting context, deep link	no	Existing drawer or shell only; no new notification center
Operation run database notifications	yes	Existing Filament database notification surface plus existing operation notification classes and presenter	Same operator-facing database notification family as findings notifications	title, body, tone, primary action, supporting context, deep link	yes	Existing admin and system drawers remain; only plane-specific destination logic stays exceptional

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Finding event database notifications	Secondary Context Surface	An operator receives a finding update and decides whether to open the finding now	What changed, which finding is affected, tenant context, and exactly one primary action	Full finding detail, evidence, audit trail, and workflow actions after opening the finding	Secondary because the notification points into the real work surface instead of replacing it	Keeps notifications aligned with the existing findings workflow surfaces	Removes re-learning of notification structure between findings and other work updates
Operation run database notifications	Secondary Context Surface	An operator receives run lifecycle feedback and decides whether to open the canonical run view now	What happened to the run, affected context, and exactly one primary action	Full operation detail, reason translation, diagnostics, and history after opening the run	Secondary because the notification is an entry point into the canonical run surface, not the destination itself	Preserves monitoring and operations as the durable work context	Reduces interpretation cost when findings and operations both notify through the same shared drawer

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Finding event database notifications	Utility / System	Notification / drill-in entry point	Open finding	Finding	forbidden	none; one primary action only	none	Existing in-app database notification surface	/admin/t/{tenant}/findings/{finding}	Tenant name, severity, event label, recipient reason	Findings / Finding	Why the operator was notified and what finding needs follow-up	none
Operation run database notifications	Utility / System	Notification / drill-in entry point	Open operation run	Operation run	forbidden	none; one primary action only	none	Existing in-app database notification surface	/admin/operations/{run} for admin-plane users; existing system run detail destination for platform users	Operation label, tenant or workspace context, lifecycle outcome	Operations / Operation run	What happened to the run and which canonical detail surface explains it	Plane-specific detail-route exception because platform users do not use the admin run destination

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Finding event database notifications	Tenant operator or tenant manager	Decide whether to open a finding now because work changed hands, reopened, or aged	Notification entry point	Why am I being notified, and what do I need to open?	Tenant, finding summary, severity, event label, recipient reason, and one action	Full finding evidence, audit trail, and lifecycle history after opening	assignment change, reopen truth, due-state aging	none on the notification itself	Open finding	none
Operation run database notifications	Workspace operator or platform operator	Decide whether to inspect a run now because it queued or reached a terminal state	Notification entry point	What happened to this run, and should I open it now?	Operation label, primary status or outcome summary, context hint, and one action	Full run diagnostics, reason translation, payload context, and history after opening	execution lifecycle, terminal outcome, context scope	none on the notification itself	Open operation	none

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no
• New abstraction?: yes - one bounded shared operator-facing database notification contract over existing finding and operation notification payload builders
• New enum/state/reason family?: no
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: Operators currently receive the same interaction class through different presentation grammars, which weakens trust and makes future notification-bearing work harder to learn.
• Existing structure is insufficient because: One real shared presenter exists, but it only covers terminal operation notifications. Findings notifications and queued operation notifications still compose local payloads, so the product has no explicit shared contract for operator-facing database notifications.
• Narrowest correct implementation: Reuse the existing shared presenter anchor and canonical link helpers, extend that path to the current three real consumers, and stop there.
• Ownership cost: Ongoing maintenance for one small shared contract, a small supporting-context rule set, and regression coverage for payload structure and deep-link safety.
• Alternative intentionally rejected: A full notification platform, preferences center, or domain-by-domain local fixes were rejected because they either import premature infrastructure or leave the parallel-path problem unsolved.
• Release truth: Current-release truth. This is a narrow convergence step for an interaction class that already has multiple real consumers.

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Feature
• Validation lane(s): fast-feedback, confidence
• Why this classification and these lanes are sufficient: The proving burden is operator-visible payload structure and deep-link safety across real notification consumers. Focused feature coverage is enough to prove the shared contract without introducing browser or heavy-governance cost.
• New or expanded test families: Add one shared database notification contract test and extend finding or operation notification payload tests plus deep-link authorization coverage.
• Fixture / helper cost impact: Moderate. Tests need a tenant user, a platform user, findings, operation runs, visible and hidden tenant contexts, and the existing notification helper paths.
• Heavy-family visibility / justification: none
• Special surface test profile: global-context-shell
• Standard-native relief or required special coverage: Ordinary feature coverage is sufficient, plus explicit proof that finding links preserve tenant safety and operation links preserve current admin versus system routing semantics while still sharing one primary payload structure.
• Reviewer handoff: Reviewers must confirm that the shared contract stays bounded to current operator-facing database notifications, that no second local payload grammar survives in the in-scope consumers, and that exactly one primary action remains the only primary affordance on each notification.
• Budget / baseline / trend impact: none
• Escalation needed: none
• Active feature PR close-out entry: Guardrail
• Planned validation commands:
  • 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

User Scenarios & Testing (mandatory)

Story sequencing note: These stories are incremental slices over one shared notification-presentation seam. US1 establishes the converged primary structure, US2 validates preserved route and scope truth on top of that seam, and US3 hardens the seam against future in-scope bypasses.

User Story 1 - Scan Notifications Without Relearning The Surface (Priority: P1)

As a responsible operator, I want finding and operation notifications to use the same primary structure, so I can decide what to open without decoding each domain's private language.

Why this priority: This is the smallest direct operator win. If the shared notification surface still speaks two different grammars, the product keeps adding cognitive load exactly where it should be lower-friction.

Independent Test: Can be fully tested by generating one finding notification and one operation notification, then verifying that both expose the same primary structure: a title naming the target object, a primary body summarizing the change, one status emphasis with the existing Filament icon treatment, exactly one primary action, and optional supporting context that stays secondary.

Acceptance Scenarios:

1. Given a user receives a finding notification and an operation notification, When both are rendered in the same database-notification surface, Then each shows a title naming the target object, a primary body summarizing the change, one status emphasis with the existing Filament icon treatment, and exactly one primary action in the same structural order.
2. Given one notification includes extra supporting context while another does not, When both are rendered, Then the missing supporting context does not collapse the shared primary structure or displace the action.

---

User Story 2 - Trust Notification Actions And Scope Rules (Priority: P1)

As an operator, I want notification actions to open the right record without leaking scope, so I can trust the shortcut instead of treating notifications as decorative text.

Why this priority: Shared presentation only matters if the action affordance remains truthful. A consistent button that opens the wrong place or leaks scope would make the surface less trustworthy, not more.

Dependency Note: This is a follow-on slice after US1 establishes the converged primary structure.

Independent Test: After US1 is in place, this slice can be fully tested by opening finding and operation notification actions as entitled and non-entitled users, then verifying that the correct destination opens and existing 404 versus 403 semantics remain intact.

Acceptance Scenarios:

1. Given an entitled tenant user opens a finding notification action, When the link resolves, Then the existing finding detail page opens.
2. Given a user is not entitled to the tenant behind a finding notification, When that link is opened, Then the system responds with deny-as-not-found behavior and does not reveal tenant or finding details.
3. Given a platform user receives an operation notification, When the action is opened, Then the existing system-plane run destination opens without falling back to tenant assumptions.

---

User Story 3 - Keep Future Work-Update Notifications Familiar (Priority: P2)

As a workspace operator, I want later work-update notifications to keep the same field order and action placement, so the database-notification surface stays predictable as more domains adopt it.

Why this priority: This is the bounded spread-control value of the spec. Without it, every future notification-bearing domain can add a new local grammar and undo the immediate operator benefit.

Dependency Note: This is a follow-on slice after US1 and US2 establish the converged structure and preserved route rules.

Independent Test: After US1 and US2 are in place, this slice can be fully tested by asserting that the in-scope finding and operation consumers already share the same required primary field set and by requiring that same field set for any additional in-scope consumer added during the feature.

Acceptance Scenarios:

1. Given a new or refactored in-scope operator-facing database notification joins the shared surface, When it is delivered, Then it uses the same title, body, action, and deep-link structure rather than inventing a local primary payload grammar.
2. Given findings and operation notifications coexist in the drawer, When an operator compares them, Then the domain nouns differ where needed but field order, action placement, and deep-link affordance remain the same.

Edge Cases

• Finding and operation notifications may require different destination routes; the shared contract must keep one structure without forcing one destination family.
• Platform users may receive operation notifications while findings remain tenant-scoped; the shared contract must not assume tenant context or leak cross-plane details.
• Some notification types may have supporting context while others do not; absent context must not create blank or malformed notification cards.
• Notification classes outside the current bounded scope must keep their current behavior until they are explicitly brought into the shared contract, rather than being partially rewritten ad hoc.

Requirements (mandatory)

Constitution alignment (required): This feature adds no Microsoft Graph calls, no new write workflow, no new queued job, and no new OperationRun type. It changes only how existing operator-facing database notifications compose their payloads and actions.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): The feature introduces one bounded shared presenter or builder path because current-release operator experience already has three real consumers for the same interaction class. It adds no persistence, no new states, and no new taxonomy.

Constitution alignment (XCUT-001): This spec exists to close a documented shared-interaction bypass. It must name the current shared notification path, extend it, and stop silent local payload composition in the in-scope consumers.

Constitution alignment (TEST-GOV-001): The proving burden is payload-structure truth and deep-link safety across current consumers. Focused feature tests are sufficient; no browser or heavy-governance lane is justified.

Constitution alignment (OPS-UX): Existing operation-notification emission rules remain unchanged. This feature may change OperationRunQueued and OperationRunCompleted payload composition only. It must not alter service-owned lifecycle transitions, terminal-notification suppression for system runs, or current canonical run-link behavior.

Constitution alignment (RBAC-UX): The feature spans admin-plane, tenant-context, and system-plane notification consumers, but it does not change authorization rules. Finding notification links must continue to enforce tenant-safe 404 versus 403 semantics. Operation notification links must continue to honor current admin or system-plane entitlement rules. No notification payload may widen visibility beyond the recipient's current scope.

Constitution alignment (UI-FIL-001): Existing Filament database-notification primitives must be reused. No custom notification drawer, custom card markup, or local page-specific notification shell may be introduced.

Constitution alignment (UI-NAMING-001): Operator-facing notification copy must stay domain-first. Findings remain finding notifications with verbs such as assigned, reopened, due soon, or overdue. Operation notifications remain operation or run updates with verbs such as queued and completed. Implementation-first terms such as payload, presenter, fingerprint, or envelope remain secondary.

Constitution alignment (DECIDE-001): Notifications remain secondary context surfaces. They must support one quick open decision and then defer to the existing canonical work surface for real investigation or mutation.

Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / HDR-001): Each in-scope notification card has exactly one primary inspect model and one primary action. Row click is forbidden. There are no destructive actions and no mixed action groups on the notification surface.

Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001): The feature solves a real shared-interaction divergence but must stay shallow. It must not grow a new notification taxonomy or explanation framework. Tests should focus on the business consequence: the operator sees one consistent structure and safe action path.

Functional Requirements

• FR-001: The system MUST define one shared operator-facing database-notification presentation contract for the current in-scope notification families.
• FR-002: The shared contract MUST cover, at minimum, title, body, one status emphasis field with the corresponding existing Filament icon treatment, one primary action label, one primary deep link, and optional supporting context.
• FR-003: FindingEventNotification MUST use the shared contract without changing the delivery semantics, event types, recipient resolution, dedupe, fingerprint logic, or optional external-copy behavior introduced by Spec 224.
• FR-004: OperationRunCompleted MUST continue to use the shared contract for terminal database notifications, preserving existing reason-translation behavior only as secondary supporting context.
• FR-005: OperationRunQueued MUST align to the same shared contract and must no longer remain a divergent local payload shape for the same interaction class.
• FR-006: Every in-scope notification MUST expose exactly one primary action. Supporting context, if present, MUST remain supplementary and MUST NOT displace the action.
• FR-007: Primary action labels MUST remain domain-first and operator-readable. Findings keep Open finding; operation notifications keep the existing operator-readable run-open grammar.
• FR-008: Notification deep links MUST continue to use the existing canonical link helpers and existing destination routes. Notification classes MUST NOT assemble raw routes locally when a canonical helper already exists.
• FR-009: Notification payloads MUST remain delivery artifacts only. The feature MUST NOT introduce a second workflow state store, notification-preference model, or presentation-only persistence layer.
• FR-010: The feature MUST NOT change recipient eligibility, alert-rule routing, alert delivery behavior, or external notification semantics from Spec 224.
• FR-011: The feature MUST NOT change operation-run notification emission policy, queued-notification allow rules, terminal-notification suppression rules, or service ownership of run lifecycle state.
• FR-012: In-scope notification titles and bodies MUST NOT expose raw event keys, reason codes, payload fields, or implementation-first terms as their primary operator language.
• FR-013: The shared contract MUST support the current three real consumers and remain bounded to current operator-facing database notifications. It MUST NOT expand into a universal notification framework in v1.
• FR-014: Contract-level regression coverage MUST prove that findings and operation notifications share the same primary payload structure and that future in-scope consumers cannot silently bypass that structure.
• FR-015: Existing alert rules, alert deliveries, escalation logic, and any future My Work admission rules remain outside this spec unless they are only consuming the already-converged in-app notification presentation.
• FR-016: The existing database-notification surface remains the only collection surface for the in-scope payloads. This feature MUST NOT create a second notification center, a My Work queue, or a dashboard clone.

UI Action Matrix (mandatory when Filament is changed)

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Finding event database notification card	Existing Filament database-notification surface	none	Primary action button only: Open finding	none	none	none	n/a	n/a	No new audit because the card stays read-only	Action Surface Contract satisfied. One inspect model, no redundant View, no destructive action, no custom notification shell.
Operation run database notification card	Existing Filament database-notification surface	none	Primary action button only: existing run-open label	none	none	none	n/a	n/a	No new audit because the card stays read-only	Action Surface Contract satisfied. One inspect model, no redundant View, no destructive action. Approved exception: platform-user cards keep their system-plane destination while sharing the same card structure.

Key Entities (include if feature involves data)

• Operator-facing database notification payload: A derived delivery artifact that carries the visible title, body, status emphasis with the existing Filament icon treatment, primary action, deep link, and optional supporting context shown in the existing notification surface.
• Shared database-notification presentation contract: A bounded cross-cutting contract that standardizes the primary structure for current finding and operation notification payloads.
• Notification consumer family: The current set of real notification classes that present work updates to operators through database notifications.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: In acceptance review, every in-scope finding and operation notification shows the target object, the change summary, one status emphasis with the existing Filament icon treatment, and exactly one primary action before any optional supporting context.
• SC-002: 100% of covered payload tests assert the same primary structure across the in-scope finding and operation notification consumers.
• SC-003: 100% of covered authorization tests preserve existing 404 versus 403 and admin versus system-plane deep-link semantics for the in-scope notification actions.
• SC-004: No in-scope operator-facing database notification ships with a divergent local primary structure at feature completion.