TenantAtlas/specs/277-stored-reports-surface/quickstart.md

Quickstart: Stored Reports Surface v1

Date: 2026-05-06
Branch: 277-stored-reports-surface

This quickstart is the intended reviewer flow after implementation. It stays bounded to tenant-scoped stored-report browsing, detail inspection, family-aware authorization, and the canonical widget drilldown.

Prerequisites

1. Start the local platform stack.
   • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail up -d
2. Ensure one tenant has:
   • one current permission_posture stored report
   • one current entra.admin_roles stored report
   • one historical entra.admin_roles stored report
3. Ensure one actor can view both report families in the tenant, one actor can view only Entra admin roles, and one actor is not a tenant member.
4. Keep AdminRolesSummaryWidget available on the tenant overview page so the canonical drilldown can be verified.

Scenario 1: Browse the tenant stored-reports register

1. Open /admin/t/{tenant}/stored-reports as an entitled actor.
2. Confirm the register shows only visible report families for the active tenant.
3. Confirm the current row for each visible family shows:
   • report family
   • current versus historical truth
   • measured time
   • concise family summary
4. Reveal history.
5. Confirm historical rows stay readable and clearly distinct from the current row.
6. Filter by one family and search by family label or stored-report reference.

Scenario 2: Inspect a current permission-posture report

1. Open the current permission-posture row from the register.
2. Confirm the detail page shows stored-report identity, lifecycle truth, retention truth, measured time, and the integrity anchor when present before any raw payload.
3. Confirm the page shows the bounded permission-posture summary:
   • posture score
   • required count
   • granted count
   • missing or at-risk permission context
4. Confirm raw payload remains collapsed and secondary.

Scenario 3: Inspect a historical Entra admin-roles report

1. Open a historical Entra admin-roles row.
2. Confirm the detail page clearly states that the row is retained history and not the current report.
3. Confirm the page shows the bounded Entra admin-roles summary:
   • roles total
   • assignments total
   • high-privilege assignment count
   • highest-risk assignment context
4. Confirm the page exposes Open current report as the one dominant next action.

Scenario 4: Verify family-aware authorization and deny semantics

1. Sign in as the actor who can view only Entra admin roles.
2. Confirm the register does not show permission-posture rows or a permission-posture family filter.
3. Attempt to open a permission-posture stored-report detail route directly.
4. Confirm the response is 403 after tenant membership is established.
5. Sign in as the non-member actor and attempt to open the register or a detail route.
6. Confirm the response is 404 and no stored-report presence leaks.

Scenario 5: Follow the canonical widget drilldown

1. Open the tenant overview page that renders AdminRolesSummaryWidget.
2. Confirm the widget exposes a report link only when the actor can view Entra admin roles.
3. Follow the link.
4. Confirm the app opens the canonical stored-report detail route for the current tenant and current Entra admin-roles report.
5. Confirm no additional evidence, review, or review-pack pseudo-view was introduced as part of this slice.

Targeted Validation Commands

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/StoredReports/StoredReportResourceTest.php tests/Feature/StoredReports/StoredReportEntitlementEnforcementTest.php

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/StoredReports/StoredReportDetailPresentationTest.php tests/Feature/EntraAdminRoles/AdminRolesSummaryWidgetTest.php

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Out of Scope Confirmations

While validating this slice, confirm that implementation does not add or imply:

• report generation, rerun, or scheduling from the stored-report surface
• raw JSON download or export from the stored-report surface
• cross-tenant or workspace-wide stored-report browsing
• global-search exposure for stored reports
• a generic report registry or analytics console
• new local report cards or pseudo-view links on evidence or review pages when no repo-real launch affordance already exists