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

Quickstart: Decision-Based Governance Inbox v1

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

Purpose

This quickstart captures the smallest intended implementation and validation path for the governance inbox slice. It is preparation-only guidance for later implementation work.

Planned Implementation Shape

1. Add one native Filament page at /admin/governance/inbox.
2. Compose five bounded source families from existing repo truth:
   • assigned findings
   • findings intake
   • stale or terminal-follow-up operations
   • alert-delivery failures
   • review follow-up
3. Keep the page read-only and route every action into an existing source surface.
4. Keep tenant and family filters query-safe and workspace-safe.

Planned Validation Commands

Run the minimum proving commands once implementation exists:

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/GovernanceInbox/GovernanceInboxSectionBuilderTest.php
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Governance/GovernanceInboxPageTest.php
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Governance/GovernanceInboxAuthorizationTest.php
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Governance/GovernanceInboxNavigationContextTest.php
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Manual Review Checklist For Later Implementation

• Open /admin/governance/inbox as a workspace operator with at least two visible signal families.
• Verify the page stays read-only and does not offer claim, snooze, acknowledge, assign, or triage mutation controls.
• Verify a tenant-scoped launch prefilters the page to the current tenant.
• Verify explicit out-of-scope tenant_id query input returns 404.
• Verify each visible section opens an existing source surface and preserves a back-link or source context.

Guardrails To Preserve

• No new persisted inbox-item table.
• No generic cross-domain task engine.
• No browser-only validation requirement by default.
• No raw-support or debug detail rendered on the inbox page.

Close-Out Target For Later Implementation

Record the final outcome in Guardrail / Exception / Smoke Coverage once implementation happens, including:

• whether a bounded Support/GovernanceInbox/ seam was actually needed
• whether all source CTAs stayed on existing canonical surfaces
• whether any contained drift resolved as document-in-feature
• the final proof outcome from the focused unit and feature validation commands

Guardrail / Exception / Smoke Coverage

• Guardrail result: PASS. The implemented slice stayed on the existing Filament v5 / Livewire v4 admin plane, kept provider registration untouched in apps/platform/bootstrap/providers.php, introduced no destructive inbox action, and added no new registered asset bundle.
• Bounded seam result: document-in-feature. The final implementation required apps/platform/app/Support/GovernanceInbox/GovernanceInboxSectionBuilder.php as a derived page-scoped assembler because the current source pages did not expose a reusable cross-family API.
• Source-surface result: PASS. All dominant section CTAs and preview-entry links stayed on existing findings, operations, alerts, and review surfaces; no inbox-local mutation lane or detail shell was added.
• Focused proof result: export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/GovernanceInbox/GovernanceInboxSectionBuilderTest.php tests/Feature/Governance/GovernanceInboxAuthorizationTest.php tests/Feature/Governance/GovernanceInboxPageTest.php tests/Feature/Governance/GovernanceInboxNavigationContextTest.php passed with 10 passed (53 assertions).
• Formatting result: export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent passed.
• Smoke result: PASS. Manual integrated-browser smoke confirmed /admin/governance/inbox loads in workspace context, the operations CTA navigates to the canonical monitoring route with return context, and the explicit back link returns to the inbox.