TenantAtlas/specs/250-decision-governance-inbox/research.md

Research: Decision-Based Governance Inbox v1

Date: 2026-04-28
Feature: spec.md

Decision Summary

The repo already contains the underlying governance attention signals. The missing product slice is not another source page or another workflow state, but one bounded decision-first page that composes the existing source seams into a calm workspace starting point.

Key Decisions

1. Use section-based composition, not a generic task engine

• Decision: Build the inbox as one read-only Filament page with bounded family sections and preview entries.
• Why: A polymorphic table or persisted inbox-item model would import a second workflow truth before the first read-only operator surface is proven.
• Repo truth: Findings, operations, alerts, and review follow-up already have their own truthful pages and models.

2. Reuse findings queue semantics directly

• Decision: The assigned-findings and intake sections should reuse the inclusion and urgency rules already owned by MyFindingsInbox and FindingsIntakeQueue.
• Why: Those pages already codify open-status filtering, tenant entitlement, urgency ordering, and calm empty states.
• Source seams:
  • apps/platform/app/Filament/Pages/Findings/MyFindingsInbox.php
  • apps/platform/app/Filament/Pages/Findings/FindingsIntakeQueue.php

3. Use stale or terminal-follow-up operations as the operations-family signal

• Decision: The operations section should derive from the same stale or follow-up attention rules already exposed on the canonical Operations page.
• Why: The repo already has a canonical operations monitoring surface and run-detail route; the inbox should route into it instead of inventing a second operations diagnostic layer.
• Source seams:
  • apps/platform/app/Filament/Pages/Monitoring/Operations.php
  • apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
  • apps/platform/app/Support/OperationRunLinks.php

4. Keep the alert-family slice narrow: failed alert deliveries, not alert-rule config

• Decision: The alerts section should surface delivery failures or similar operator-attention alert outcomes, not alert-rule configuration.
• Why: Delivery failure is the actionable alerting gap that belongs in an attention inbox. Alert-rule editing stays a configuration workflow on its existing surfaces.
• Source seams:
  • apps/platform/app/Filament/Pages/Monitoring/Alerts.php
  • apps/platform/app/Filament/Resources/AlertDeliveryResource.php
  • apps/platform/app/Models/AlertDelivery.php

5. Use triage-review follow-up as the review-family signal

• Decision: The review section should derive from TenantTriageReview states such as follow_up_needed and changed-since-review semantics.
• Why: The repo already distinguishes review follow-up from the underlying review artifact; the inbox should reuse that distinction rather than invent a second attention reason model.
• Source seams:
  • apps/platform/app/Services/PortfolioTriage/TenantTriageReviewService.php
  • apps/platform/app/Models/TenantTriageReview.php
  • apps/platform/app/Filament/Resources/TenantReviewResource.php

6. Preserve navigation continuity through shared context helpers

• Decision: Every section and preview entry should use existing navigation helpers for back links and canonical destinations.
• Why: The inbox only reduces attention load if it preserves return context instead of opening detached utility flows.
• Source seams:
  • apps/platform/app/Support/Navigation/CanonicalNavigationContext.php
  • apps/platform/app/Support/Navigation/RelatedNavigationResolver.php
  • apps/platform/app/Support/OperateHub/OperateHubShell.php

7. Keep the inbox read-only in v1

• Decision: No claim, snooze, acknowledge, assign, or triage mutations are introduced on the inbox page.
• Why: Those mutations already belong to source surfaces and would force the inbox to become a second workflow owner.
• Result: The inbox remains a decision hub, not an execution surface.

Access Model Decision

• Workspace membership remains the first gate.
• The page only needs to exist for actors who can already see at least one family.
• Rows and counts must stay family-specific:
  • findings sections require Capabilities::TENANT_FINDINGS_VIEW
  • review follow-up requires Capabilities::TENANT_REVIEW_VIEW
  • alert-family sections require Capabilities::ALERTS_VIEW
  • source mutations remain on source pages with their existing capabilities
• Explicit out-of-scope tenant_id inputs return 404.

Rejected Alternatives

Rejected: persisted inbox-item table

• Reason: adds durable workflow truth, migration cost, audit burden, and new lifecycle semantics before the read-only composition page is proven.

Rejected: generic cross-domain work-item abstraction

• Reason: over-generalizes five concrete families into a second vocabulary and invites a platform-level task framework that current-release truth does not require.

Rejected: extend one existing page instead of adding a canonical inbox

• Reason: no single existing page can truthfully host all five families without becoming the wrong domain owner.

Implications For Implementation

• Prefer one bounded Support/GovernanceInbox/ seam only if page-local composition becomes unreadable.
• Keep source-family labels close to existing UI copy to avoid a second UX language.
• Keep empty states honest:
  • tenant-prefilter-hidden attention -> Clear tenant filter
  • globally calm -> one neutral workspace return CTA
• Do not add page-level audit noise for mere page views.

Planning Outcome

The smallest viable implementation slice is one new read-only workspace page that reuses existing source-page queries, existing navigation helpers, and existing capability semantics. No new persistence or mutation lane is justified.