# 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.