TenantAtlas/specs/168-tenant-governance-aggregate-contract/quickstart.md

Quickstart: Tenant Governance Aggregate Contract

Goal

Validate that one derived tenant-governance aggregate now drives the shared summary posture across the tenant dashboard, the tenant governance banner, and the Baseline Compare landing without adding persistence or reintroducing local findings-count ownership.

Prerequisites

1. Start Sail.
2. Ensure a tenant exists with an assigned baseline profile and a consumable snapshot.
3. Seed compare-run scenarios for: no result yet, compare in progress, compare failed, trustworthy no-drift, stale no-drift, overdue findings without new drift, and lapsed governance without new drift.
4. Ensure the current user is a tenant member with access to the tenant dashboard and Baseline Compare landing.

Implementation Validation Order

1. Run low-level compare and aggregate coverage

vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareStatsTest.php
vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareSummaryAssessmentTest.php
vendor/bin/sail artisan test --compact --filter=TenantGovernanceAggregate

Expected outcome:

• Existing compare truth still resolves the same availability and posture states.
• The new aggregate contract maps those states into one stable summary object without introducing a second query-backed truth path.

2. Run focused cross-surface parity coverage

vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/NeedsAttentionWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareNowWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareCoverageBannerTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareLandingAdminTenantParityTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareLandingDuplicateNamesBannerTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareLandingRbacLabelsTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareLandingWhyNoFindingsTest.php

Expected outcome:

• NeedsAttention, BaselineCompareNow, BaselineCompareCoverageBanner, and the landing summary agree on posture family, headline, and next-action intent for the same tenant state.
• A tenant with zero visible drift but overdue or unhealthy governance still renders as action-needed on every covered surface.
• The landing keeps Compare now confirmation and capability gating unchanged, and diagnostics remain clearly secondary to the shared summary posture.

3. Run request-local reuse and guard coverage

vendor/bin/sail artisan test --compact --filter=TenantGovernanceAggregateMemoization
vendor/bin/sail artisan test --compact tests/Feature/Guards/DerivedStateConsumerAdoptionGuardTest.php

Expected outcome:

• One request stores one governance aggregate per tenant scope.
• Covered surfaces do not fall back to widget-local ad hoc caches or repeated local findings queries.

4. Format touched implementation files

vendor/bin/sail bin pint --dirty --format agent

Expected outcome:

• All touched implementation files conform to the repo’s Pint rules.

Manual Smoke Check

1. Open /admin/t/{tenant} for a tenant with lapsed governance and no new drift findings.
2. Confirm the dashboard Needs Attention widget and Baseline Governance card both show action-needed posture.
3. Open /admin/t/{tenant}/baseline-compare-landing and confirm the landing summary agrees with the dashboard posture while still showing deeper diagnostics below.
4. Use a tenant with a trustworthy no-drift result and confirm the banner hides, the dashboard falls back to healthy checks, and the landing summary presents the same all-clear posture.
5. Use a tenant with a queued or running compare and confirm dashboard, banner, and landing all present progress-aware follow-up instead of stale “all clear” messaging.
6. Switch from one tenant to another and confirm the second tenant does not reuse the first tenant’s summary posture.

Non-Goals For This Slice

• No database migration.
• No new Graph call or provider-contract work.
• No new assets or Filament panel registration change.
• No new mutation surface beyond the existing Compare now action, which remains unchanged.