TenantAtlas/specs/199-global-context-shell-contract/quickstart.md

Quickstart: Global Context Shell Contract

Goal

Implement Spec 199 by making workspace and tenant shell context resolve from one request-scoped contract, then verify that switch, select, clear, restore, and invalid-context flows all produce the same truth the shell displays.

Prerequisites

1. Start the app stack:

   cd apps/platform && ./vendor/bin/sail up -d
   

2. Confirm the working branch:

   git branch --show-current
   

3. Keep the current scope of work bounded to the existing Laravel and Filament monolith under apps/platform.

Recommended Implementation Order

1. Canonicalize resolution first

   • Align WorkspaceContext and OperateHubShell so they can produce one resolved shell contract.
   • Make remembered context restore-only and remove any equal-ranking shell truth outside the resolved contract.

2. Align explicit mutation flows second

   • Update SwitchWorkspaceController, SelectTenantController, ClearTenantContextController, and WorkspaceRedirectResolver to consume the same contract rules.
   • Keep safe intended-URL behavior via WorkspaceIntendedUrl.

3. Convert shell surfaces third

   • Update context-bar.blade.php and any panel concern or middleware consumer to render only the resolved contract.
   • Preserve tenantless workspace behavior on routes that support it.

4. Close with regression coverage

   • Extend current unit and feature seams before adding any new test family.
   • Use browser testing only if a client-only shell behavior appears that feature tests cannot observe.

Context Source Inventory Owner

Keep the canonical source inventory in specs/199-global-context-shell-contract/data-model.md under Context Source Inventory. Any new source or fallback seam added during implementation must be recorded there before tasks are considered complete.

Documented Recovery Destinations

• Missing or unrecoverable workspace truth goes to /admin/choose-workspace.
• Generic workspace-safe recovery with no trustworthy prior route goes to admin.operations.index.
• Tenant-scoped evidence cleanup goes to admin.evidence.overview.
• Tenant-bound cleanup with a valid workspace goes to admin.workspace.managed-tenants.index.
• Tenant-bound cleanup with no recoverable workspace goes to admin.home.
• Tenantless-capable workspace routes and canonical workspace record viewers stay on their current route when entitlement remains valid.

Explicit Page-Category Exceptions

• /admin/choose-workspace is the explicit workspace_chooser_exception route.
• Tenant-scoped evidence paths under /admin/evidence/... except /admin/evidence/overview are explicit tenant_scoped_evidence routes for recovery purposes.

Documented Workspace Switch Destinations

• A safe intended /admin... URL wins when it is still valid.
• Workspaces with zero selectable tenants land on admin.workspace.managed-tenants.index.
• Workspaces with multiple selectable tenants land on /admin/choose-tenant.
• Workspaces with exactly one selectable tenant land on the tenant dashboard route under /admin/t/{external_id}.

Focused Validation Commands

Run the narrowest commands that prove the contract:

cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/OperateHub/OperateHubShellResolutionTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Workspaces/WorkspaceContextRememberedTenantTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceContextTopbarAndTenantSelectionTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceContextRecoveryDisplayTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces/SelectTenantControllerTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces/ChooseTenantPageTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces/ChooseWorkspacePageTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces/ChooseWorkspaceRedirectsToChooseTenantTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces/EnsureWorkspaceSelectedMiddlewareTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces/SwitchWorkspaceControllerTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces/SwitchWorkspaceRedirectsToTenantRegistrationWhenNoTenantsTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces/WorkspaceRedirectResolverTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces/GlobalContextShellContractTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces/WorkspacesResourceIsTenantlessTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Spec085/OperationsIndexHeaderTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/AdminGlobalSearchContextSafetyTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantRBAC/TenantSwitcherScopeTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsDbOnlyRenderTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsActionsEnqueueRunTest.php

If new focused tests are added for Spec 199, run them directly as well. The two Monitoring commands above are the non-functional proof that the shell-anchor workspace surfaces remain DB-only and do not enqueue work while rendering.

Formatting

Before closing the feature work:

cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Manual Smoke Checklist

Use a simple 3-second timer for each first-look shell scan on the in-scope entry paths so the SC-001 review stays measurable.

1. Workspace-scoped tenantless entry

• Enter /admin/operations with a valid workspace and no active tenant.
• Confirm the shell shows the workspace name and No tenant selected or the approved tenantless wording.
• Confirm no stale tenant label appears.

2. Explicit tenant selection

• Select a valid active tenant from the shared shell surface.
• Confirm the destination route and shell both show the same tenant.
• Confirm the tenant belongs to the active workspace only.

3. Tenant clear from a workspace-scoped page

• Clear tenant context while on /admin/operations or another workspace-scoped page.
• Confirm the shell becomes tenantless and the page remains valid.

4. Tenant clear from a tenant-bound page

• Clear tenant context while on a tenant-bound route.
• Confirm the request does not leave the user in a half-valid tenant-bound route.
• Confirm the redirect lands in admin.workspace.managed-tenants.index for the current workspace, or admin.home when no workspace truth remains.

4a. Tenant clear from a tenant-scoped evidence path

• Clear tenant context while on a tenant-scoped evidence path under /admin/evidence/....
• Confirm the redirect lands on admin.evidence.overview and no stale tenant label remains in the shell.

4b. Tenant clear from a canonical workspace record viewer

• Clear tenant context while on /admin/operations/{run}.
• Confirm the request stays on admin.operations.view when entitlement remains valid and does not widen into a different route unnecessarily.

5. Invalid remembered tenant

• Seed a remembered tenant that is inaccessible, missing, or incompatible.
• Confirm the remembered tenant is cleared automatically and does not reappear in the shell.

6. Workspace switch with stale tenant context

• Switch from one workspace to another where the prior tenant is not valid.
• Confirm the shell clears tenant context or replaces it only after validation in the new workspace.

7. Workspace-independent chooser route

• Enter the workspace chooser flow without an active workspace.
• Confirm the route remains available as an explicit exception and is not treated as a generic missing-workspace failure.

8. Admin versus tenant panel parity

• Resolve the same valid tenant scenario through /admin and /admin/t/{external_id}.
• Confirm the shared shell displays the same active truth and does not expose a competing panel-owned context label.

Done Signal

Spec 199 is implementation-ready when:

• one resolved shell contract governs display and route behavior,
• switch, select, clear, restore, and invalid recovery follow one shared rule set,
• the shared shell renders only the resolved truth,
• targeted unit and feature tests pass,
• timed manual smoke checks confirm tenantless and tenant-scoped behavior are both explicit and understandable.