# 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: ```bash cd apps/platform && ./vendor/bin/sail up -d ``` 2. Confirm the working branch: ```bash 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: ```bash 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: ```bash 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.