TenantAtlas/specs/190-baseline-compare-matrix/quickstart.md

Quickstart: Workspace Baseline Compare Matrix V1

Goal

Implement one workspace-scoped baseline compare matrix that lets an operator inspect visible assigned tenants against one baseline reference, trigger compare execution across the visible assigned set, and drill into existing tenant compare or finding surfaces without introducing a new persisted cross-tenant compare artifact.

Implementation Sequence

1. Add the new workspace matrix page and baseline entry action.

   • Add a new workspace Filament page for /admin/baseline-profiles/{record}/compare-matrix.
   • Add Open compare matrix to the existing baseline profile detail header.
   • Keep the page scoped to one selected baseline profile and one explicit reference snapshot.

2. Build the live aggregation layer over existing truth.

   • Create a narrow matrix builder under the existing baseline-support namespace.
   • Use BaselineSnapshotTruthResolver and BaselineSnapshotItem for the reference axis.
   • Use latest relevant baseline_compare runs plus their context['baseline_compare'] payload for freshness, coverage, and trust.
   • Use compare-created findings for technical difference severity and drilldown targets.
   • Keep the matrix derived only; do not add persistence.

3. Add compare-all fan-out without a workspace umbrella run.

   • Extend the baseline compare start path so the matrix and baseline detail can iterate visible assigned tenants and call the existing tenant compare start logic.
   • Keep confirmation, queued toast behavior, and run observability aligned with existing OperationRun semantics.
   • Report partial success, already queued, and blocked starts honestly from the underlying per-tenant results.

4. Bind filtering, subject focus, and drilldown continuity.

   • Add policy-type, state, and severity filters.
   • Add tenant and subject sorting.
   • Reuse CanonicalNavigationContext, RelatedNavigationResolver, and existing destination routes for tenant, finding, and run drilldowns.
   • Preserve a clear return path to the matrix.

5. Add regression coverage.

   • Cover live aggregation, compare-all, stale/no-result/ambiguous truth, visible-set RBAC filtering, and drilldown continuity.
   • Add one browser smoke test to prove the interactive matrix surface renders and performs the core operator flow.

Suggested Test Files

• apps/platform/tests/Feature/Baselines/BaselineCompareMatrixBuilderTest.php
• apps/platform/tests/Feature/Baselines/BaselineCompareMatrixCompareAllActionTest.php
• apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php
• apps/platform/tests/Feature/Rbac/BaselineCompareMatrixAuthorizationTest.php
• apps/platform/tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php
• apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php

Existing Suites To Extend Or Keep Green

• apps/platform/tests/Feature/Baselines/BaselineCompareStatsTest.php
• apps/platform/tests/Feature/Baselines/BaselineCompareFindingsTest.php
• apps/platform/tests/Feature/Baselines/BaselineProfileAuthorizationTest.php
• apps/platform/tests/Feature/Filament/WorkspaceOverview* suites that currently consume baseline attention summaries
• apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php

Minimum Verification Commands

Run all commands through Sail from apps/platform.

cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareMatrixBuilderTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareMatrixCompareAllActionTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareMatrixPageTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/BaselineCompareMatrixAuthorizationTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareStatsTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareFindingsTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Manual Acceptance Checklist

1. Open a baseline profile with a usable reference snapshot and verify Open compare matrix lands on the new workspace matrix page.
2. Confirm the page shows the selected baseline profile, reference snapshot, visible assigned tenant count, and truthful per-tenant and per-subject summaries.
3. Filter the matrix by policy type and by state and confirm the visible rows, columns, and counts update without implying hidden tenants.
4. Open a differing, missing, or ambiguous cell and confirm the drilldown reaches an existing tenant compare or finding surface with a clear return path.
5. Trigger Compare assigned tenants and confirm the modal describes simulation only, the launch fans out to visible assigned tenants only, and partial success is visible.
6. Verify a tenant with no prior compare reads as Not compared, not healthy.
7. Verify a tenant with stale compare truth reads as stale and does not look current.
8. Verify a user with partial tenant visibility sees only allowed tenants and no hidden-tenant aggregate counts.

Deployment Notes

• No new database migration is expected.
• No new assets are planned; normal Filament asset publishing behavior remains unchanged.
• Compare assigned tenants reuses existing tenant compare runs only, so no new queue worker topology or deployment artifact is required.