TenantAtlas/specs/147-tenant-selector-remembered-context-enforcement/quickstart.md

Quickstart: Tenant Selector and Remembered Context Enforcement

Goal

Implement Spec 147 so tenant selection, remembered tenant context, and route legitimacy follow one workspace-first model across the header selector, choose-tenant page, workspace switching, tenant-bound routes, and canonical workspace record viewers.

Implementation Steps

1. Consolidate remembered tenant validation in app/Support/Workspaces/WorkspaceContext.php.

   • Add or refine shared methods that return only validated remembered tenant context.
   • Ensure stale values clear deterministically for workspace mismatch, missing tenant, entitlement loss, and selector-ineligible lifecycle.

2. Converge selector membership on app/Services/Tenants/TenantOperabilityService.php.

   • Remove or simplify any custom header-selector queries that can diverge from ChooseTenant.
   • Keep active-lane semantics aligned across the header context bar, choose-tenant page, and SelectTenantController.

3. Refine shell resolution in app/Support/OperateHub/OperateHubShell.php.

   • Prefer route-authoritative tenants on tenant-bound pages.
   • Prefer validated remembered tenant only for workspace-level active-lane convenience.
   • Preserve canonical page legitimacy when selected tenant differs or is absent.

4. Update in-scope UI surfaces.

   • Header context bar: show only eligible active-lane tenants and keep “clear tenant scope” behavior workspace-safe.
   • Choose-tenant page: preserve the same active-lane meaning and empty-state framing.
   • Managed-tenant administration: keep onboarding and archived tenants discoverable and keep /admin/tenants usable without selected tenant state.
   • Tenant-bound and canonical pages: keep mismatch informational and non-blocking.

5. Audit workspace-context global search.

   • Ensure no-selected-tenant workspace context does not use remembered tenant state to surface tenant-owned results or hints.

6. Add regression coverage.

   • Unit tests for remembered-context invalidation and shell resolution.
   • Feature tests for selector membership, managed-tenant discoverability, workspace switching, no-selected-tenant workspace behavior, global-search safety, tenant-bound mismatch, and canonical run mismatch.

7. Review affected list surfaces against docs/product/standards/list-surface-review-checklist.md.

   • Validate that /admin/tenants and /admin/operations still satisfy the established list-surface standards while selector semantics and no-context fallback are hardened.

8. Validate render and query safety.

   • Confirm the focused regression suite covers the shell, choose-tenant page, tenant detail, and canonical operations viewer without introducing material query-count regressions.

Suggested Test Commands

Run focused tests through Sail:

vendor/bin/sail artisan test --compact tests/Unit
vendor/bin/sail artisan test --compact tests/Feature/Operations
vendor/bin/sail artisan test --compact tests/Feature/Filament
vendor/bin/sail artisan test --compact tests/Feature/Rbac

Format changed files:

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

Manual Verification Checklist

1. Select an active tenant from the header selector and confirm the tenant dashboard or active-lane flow resolves normally.
2. Confirm onboarding and archived tenants do not appear in the header selector or choose-tenant page.
3. Switch workspaces and confirm the previous workspace's remembered tenant does not remain active in the new workspace.
4. Clear tenant scope and confirm /admin and /admin/operations remain usable with no selected tenant.
5. Confirm /admin/tenants remains usable with no selected tenant and still exposes onboarding or archived records through the intended management surfaces.
6. Open /admin/tenants/{tenant} for an authorized onboarding or archived tenant and confirm the page remains valid.
7. Verify workspace-context global search with no selected tenant does not reveal tenant-owned results because of remembered tenant state.
8. Open /admin/operations/{run} with mismatched or empty selected tenant context and confirm the canonical page still renders with non-blocking mismatch framing.
9. Review /admin/tenants and /admin/operations against docs/product/standards/list-surface-review-checklist.md and confirm inspection, empty-state, and filter behavior remain compliant.
10. Confirm the focused regression suite or local instrumentation shows no material query-count regression on the shell, choose-tenant page, tenant detail, and canonical operations viewer flows.