# Quickstart: Decision-Based Governance Inbox v1

**Date**: 2026-04-28  
**Feature**: [spec.md](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:

```bash
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.