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

# Tasks: Global Context Shell Contract

**Input**: Design documents from `/specs/199-global-context-shell-contract/`
**Prerequisites**: `plan.md` (required), `spec.md` (required for user stories), `research.md`, `data-model.md`, `contracts/`, `quickstart.md`

**Tests**: Tests are REQUIRED for this feature because it changes runtime shell resolution, session-backed workspace and tenant context behavior, redirect and recovery rules, shared Filament shell rendering, and authorization-sensitive scope fallbacks in a Laravel/Pest codebase.
**Operations**: This feature does not create a new `OperationRun`, background workflow, or audit-only DB mutation path. The work is limited to request-scoped shell context resolution, redirects, and shared shell rendering.
**RBAC**: Existing workspace membership, tenant entitlement, and 404 vs 403 semantics remain authoritative. Tasks must preserve deny-as-not-found for non-members or non-entitled scope, keep capability failures server-side after scope is established, and keep global search tenant-safe under the canonical shell contract.
**Operator Surfaces**: The shared `context-bar` shell surface and the shell recovery state remain secondary context surfaces. Tasks must keep them operator-first, truthful, and free of competing widget-owned scope state.
**Filament UI Action Surfaces**: No new destructive actions, Resources, or alternate shell widgets are introduced. `Switch workspace`, `Select tenant`, `Clear tenant context`, and recovery actions remain the only in-scope operator actions.
**Filament UI UX-001**: No new create, edit, or view page layout work is introduced. The feature is limited to shared shell rendering, route behavior, and context recovery.
**Badges**: No new badge language or badge mapping is introduced.

**Organization**: Tasks are grouped by user story so each story can be implemented and verified as an independent increment.

## Test Governance Checklist

- Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
- New or changed tests stay in the smallest honest family, and any heavy-governance or browser addition is explicit.
- Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
- Planned validation commands cover the change without pulling in unrelated lane cost.
- Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR.

## Phase 1: Setup (Shell Contract Regression Scaffolding)

**Purpose**: Create the focused regression files, source-inventory baseline, and verification baseline needed to implement Spec 199 safely.

- [X] T001 Create shell-contract regression scaffolding in `apps/platform/tests/Unit/Support/OperateHub/OperateHubShellResolutionTest.php`, `apps/platform/tests/Feature/Workspaces/GlobalContextShellContractTest.php`, and `apps/platform/tests/Feature/Filament/WorkspaceContextRecoveryDisplayTest.php`
- [X] T002 [P] Create mutation-flow regression scaffolding in `apps/platform/tests/Feature/Workspaces/SwitchWorkspaceControllerTest.php` and extend `apps/platform/tests/Feature/Workspaces/SelectTenantControllerTest.php`
- [X] T003 [P] Confirm lane assignment, source-inventory ownership, performance-proof commands, and timed manual smoke coverage in `specs/199-global-context-shell-contract/plan.md`, `specs/199-global-context-shell-contract/data-model.md`, and `specs/199-global-context-shell-contract/quickstart.md`

---

## Phase 2: Foundational (Blocking Canonical Resolver Seams)

**Purpose**: Put the canonical shell-resolution seams in place before any story-level behavior is changed.

**CRITICAL**: No user story work should begin until this phase is complete.

- [X] T004 Implement canonical resolved shell-context precedence and recovery metadata in `apps/platform/app/Support/OperateHub/OperateHubShell.php`
- [X] T005 [P] Align session-backed workspace, remembered-tenant, and safe intended-url helpers with restore-only semantics in `apps/platform/app/Support/Workspaces/WorkspaceContext.php` and `apps/platform/app/Support/Workspaces/WorkspaceIntendedUrl.php`
- [X] T006 [P] Route admin-panel tenant consumption through the canonical shell contract in `apps/platform/app/Filament/Concerns/ResolvesPanelTenantContext.php`
- [X] T007 Update unit coverage for route-first, Filament-tenant, remembered-tenant, tenantless, and invalid remembered-context branches in `apps/platform/tests/Unit/Support/OperateHub/OperateHubShellResolutionTest.php` and `apps/platform/tests/Unit/Support/Workspaces/WorkspaceContextRememberedTenantTest.php`

**Checkpoint**: The shared shell resolver, storage semantics, and panel-consumption seam exist, so story work can proceed independently.

---

## Phase 3: User Story 1 - See The True Current Scope (Priority: P1)

**Goal**: Make every shared shell surface display the same truthful workspace and tenant state the request is actually using.

**Independent Test**: Open workspace-scoped and tenant-bound entry paths with tenant-scoped and tenantless states, then verify the shared shell displays the same resolved truth the page is operating under.

### Tests for User Story 1

- [X] T008 [P] [US1] Extend shared-shell truth display and no-hidden-page-state coverage for tenant-scoped and tenantless routes in `apps/platform/tests/Feature/Filament/WorkspaceContextTopbarAndTenantSelectionTest.php` and `apps/platform/tests/Feature/Spec085/OperationsIndexHeaderTest.php`
- [X] T009 [P] [US1] Add recovery-shell display assertions for missing workspace, missing tenant, and explicit tenantless states in `apps/platform/tests/Feature/Filament/WorkspaceContextRecoveryDisplayTest.php`

### Implementation for User Story 1

- [X] T010 [US1] Reduce the shared shell to a consumer-only resolved-context display and keep page-local filters, tabs, and inspect state out of the shell contract in `apps/platform/resources/views/filament/partials/context-bar.blade.php`
- [X] T011 [US1] Keep both panels rendering the same shared shell contract in `apps/platform/app/Providers/Filament/AdminPanelProvider.php` and `apps/platform/app/Providers/Filament/TenantPanelProvider.php`
- [X] T012 [US1] Run focused US1 verification against `apps/platform/tests/Feature/Filament/WorkspaceContextTopbarAndTenantSelectionTest.php`, `apps/platform/tests/Feature/Filament/WorkspaceContextRecoveryDisplayTest.php`, and `apps/platform/tests/Feature/Spec085/OperationsIndexHeaderTest.php`

**Checkpoint**: Shared shell surfaces now show one truthful scope model instead of competing display logic.

---

## Phase 4: User Story 2 - Switch Workspace Without Stale Tenant Truth (Priority: P1)

**Goal**: Make workspace switching deterministically re-evaluate tenant compatibility, fallback, and redirect behavior.

**Independent Test**: Start from a valid workspace and tenant, switch to compatible and incompatible target workspaces, and verify the resulting tenant state, redirect destination, and authorization behavior.

### Tests for User Story 2

- [X] T013 [P] [US2] Add switch regression coverage for compatible, incompatible, archived, and non-member target workspaces in `apps/platform/tests/Feature/Workspaces/SwitchWorkspaceControllerTest.php`, `apps/platform/tests/Feature/Workspaces/WorkspaceRedirectResolverTest.php`, and `apps/platform/tests/Feature/Workspaces/SwitchWorkspaceRedirectsToTenantRegistrationWhenNoTenantsTest.php`
- [X] T014 [P] [US2] Extend positive and negative workspace-switch affordance coverage in `apps/platform/tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php` and `apps/platform/tests/Feature/Workspaces/ChooseWorkspaceRedirectsToChooseTenantTest.php`

### Implementation for User Story 2

- [X] T015 [US2] Make workspace switching re-evaluate tenant compatibility and clear incompatible tenant state in `apps/platform/app/Http/Controllers/SwitchWorkspaceController.php` and `apps/platform/app/Support/Workspaces/WorkspaceContext.php`
- [X] T016 [US2] Canonicalize post-switch destination rules and safe intended-url consumption in `apps/platform/app/Support/Workspaces/WorkspaceRedirectResolver.php` and `apps/platform/app/Support/Workspaces/WorkspaceIntendedUrl.php`
- [X] T017 [US2] Run focused US2 verification against `apps/platform/tests/Feature/Workspaces/SwitchWorkspaceControllerTest.php`, `apps/platform/tests/Feature/Workspaces/WorkspaceRedirectResolverTest.php`, `apps/platform/tests/Feature/Workspaces/SwitchWorkspaceRedirectsToTenantRegistrationWhenNoTenantsTest.php`, `apps/platform/tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php`, and `apps/platform/tests/Feature/Workspaces/ChooseWorkspaceRedirectsToChooseTenantTest.php`

**Checkpoint**: Workspace switching can no longer carry stale tenant truth into the next workspace or route.

---

## Phase 5: User Story 3 - Select Or Clear Tenant Intentionally (Priority: P1)

**Goal**: Make explicit tenant selection and tenant clear flows behave like deterministic scope decisions instead of partial-local heuristics.

**Independent Test**: Select a tenant from the shared shell, clear tenant context from a workspace page, and clear it from a tenant-bound route to verify predictable scope and redirect outcomes.

### Tests for User Story 3

- [X] T018 [P] [US3] Extend explicit tenant-selection coverage for happy-path, non-operable, wrong-workspace, and unauthorized tenant requests in `apps/platform/tests/Feature/Workspaces/SelectTenantControllerTest.php` and `apps/platform/tests/Feature/Filament/WorkspaceContextTopbarAndTenantSelectionTest.php`
- [X] T019 [P] [US3] Extend clear-tenant route-compatibility coverage for workspace-scoped, tenant-bound, tenant-scoped evidence, and canonical workspace record viewer pages in `apps/platform/tests/Feature/Spec085/OperationsIndexHeaderTest.php`, `apps/platform/tests/Feature/Workspaces/ChooseTenantPageTest.php`, and `apps/platform/tests/Feature/Workspaces/GlobalContextShellContractTest.php`

### Implementation for User Story 3

- [X] T020 [US3] Align explicit tenant selection with the canonical shell contract, selector-operability rules, and remembered-context rules in `apps/platform/app/Http/Controllers/SelectTenantController.php` and `apps/platform/app/Support/OperateHub/OperateHubShell.php`
- [X] T021 [US3] Standardize clear-tenant recovery outcomes (same-route tenantless workspace state, `admin.operations.index`, `admin.evidence.overview`, `admin.workspace.managed-tenants.index`, `admin.operations.view`, `admin.home`) and route compatibility in `apps/platform/app/Http/Controllers/ClearTenantContextController.php` and `apps/platform/app/Support/Tenants/TenantPageCategory.php`
- [X] T022 [US3] Keep shell action labels and tenantless wording aligned to the approved vocabulary in `apps/platform/resources/views/filament/partials/context-bar.blade.php`
- [X] T023 [US3] Run focused US3 verification against `apps/platform/tests/Feature/Workspaces/SelectTenantControllerTest.php`, `apps/platform/tests/Feature/Spec085/OperationsIndexHeaderTest.php`, `apps/platform/tests/Feature/Workspaces/ChooseTenantPageTest.php`, and `apps/platform/tests/Feature/Workspaces/GlobalContextShellContractTest.php`

**Checkpoint**: Tenant selection and clear behavior now act as explicit scope changes with stable wording and recovery.

---

## Phase 6: User Story 4 - Reject Invalid Or Stale Context Cleanly (Priority: P1)

**Goal**: Make invalid route, query, and remembered context fail cleanly without leaving stale scope visible or widening access.

**Independent Test**: Enter the shell with invalid route, query-hint, and remembered context combinations, then verify the request falls back to a valid scope or 404 path with no stale shell truth left behind.

### Tests for User Story 4

- [X] T024 [P] [US4] Add valid and invalid query-hint coverage plus stale remembered-context coverage in `apps/platform/tests/Feature/Workspaces/GlobalContextShellContractTest.php` and `apps/platform/tests/Unit/Support/Workspaces/WorkspaceContextRememberedTenantTest.php`
- [X] T025 [P] [US4] Extend tenant-required fallback, workspace-required recovery, and explicit chooser-route exception coverage in `apps/platform/tests/Feature/Workspaces/ChooseTenantPageTest.php`, `apps/platform/tests/Feature/Workspaces/ChooseWorkspacePageTest.php`, and `apps/platform/tests/Feature/Workspaces/EnsureWorkspaceSelectedMiddlewareTest.php`

### Implementation for User Story 4

- [X] T026 [US4] Replace ad hoc tenant-selection heuristics with canonical invalid-context checks in `apps/platform/app/Support/Middleware/EnsureFilamentTenantSelected.php`
- [X] T027 [US4] Tighten page-category classification and invalid-context fallback mapping, including the explicit workspace-independent chooser-route exception, in `apps/platform/app/Support/Tenants/TenantPageCategory.php` and `apps/platform/app/Support/OperateHub/OperateHubShell.php`
- [X] T028 [US4] Preserve deny-as-not-found, forbidden, and no-stale-scope recovery semantics across `/admin` and `/admin/t/{external_id}` in `apps/platform/app/Support/Middleware/EnsureFilamentTenantSelected.php`, `apps/platform/app/Http/Controllers/ClearTenantContextController.php`, and `apps/platform/tests/Feature/Workspaces/GlobalContextShellContractTest.php`
- [X] T029 [US4] Run focused US4 verification against `apps/platform/tests/Feature/Workspaces/GlobalContextShellContractTest.php`, `apps/platform/tests/Feature/Workspaces/ChooseTenantPageTest.php`, `apps/platform/tests/Feature/Workspaces/ChooseWorkspacePageTest.php`, `apps/platform/tests/Feature/Workspaces/EnsureWorkspaceSelectedMiddlewareTest.php`, and `apps/platform/tests/Unit/Support/Workspaces/WorkspaceContextRememberedTenantTest.php`

**Checkpoint**: Invalid or stale context now recovers explicitly and never survives as a false active scope.

---

## Phase 7: User Story 5 - Keep Shared Shell Logic Consistent Across Panels (Priority: P2)

**Goal**: Keep admin and tenant panel entry paths, supporting panel state, and global search safety aligned to the same shell contract.

**Independent Test**: Resolve the same entitled workspace and tenant through admin and tenant panel entry paths, then verify both panels show the same active truth and preserve tenant-safe search behavior.

### Tests for User Story 5

- [X] T030 [P] [US5] Add admin-versus-tenant panel parity coverage for the same entitled workspace and tenant scenario in `apps/platform/tests/Feature/Filament/WorkspaceContextTopbarAndTenantSelectionTest.php` and `apps/platform/tests/Feature/Workspaces/WorkspacesResourceIsTenantlessTest.php`
- [X] T031 [P] [US5] Extend global-search context-safety coverage so tenant-owned results stay scoped under the canonical shell contract in `apps/platform/tests/Feature/Rbac/AdminGlobalSearchContextSafetyTest.php`, `apps/platform/tests/Feature/TenantRBAC/TenantSwitcherScopeTest.php`, and `apps/platform/tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php`

### Implementation for User Story 5

- [X] T032 [US5] Keep panel-specific context sources subordinate to the canonical shell contract in `apps/platform/app/Filament/Concerns/ResolvesPanelTenantContext.php`, `apps/platform/app/Providers/Filament/AdminPanelProvider.php`, and `apps/platform/app/Providers/Filament/TenantPanelProvider.php`
- [X] T033 [US5] Preserve tenant-safe global search scoping while the shell contract is consolidated in `apps/platform/app/Filament/Concerns/ScopesGlobalSearchToTenant.php`, `apps/platform/app/Filament/Resources/TenantResource.php`, and `apps/platform/app/Filament/Resources/PolicyResource.php`
- [X] T034 [US5] Run focused US5 verification against `apps/platform/tests/Feature/Filament/WorkspaceContextTopbarAndTenantSelectionTest.php`, `apps/platform/tests/Feature/Workspaces/WorkspacesResourceIsTenantlessTest.php`, `apps/platform/tests/Feature/Rbac/AdminGlobalSearchContextSafetyTest.php`, `apps/platform/tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php`, and `apps/platform/tests/Feature/TenantRBAC/TenantSwitcherScopeTest.php`

**Checkpoint**: Shared shell logic, panel state, and search safety remain aligned across admin and tenant entry paths.

---

## Phase 8: Polish & Cross-Cutting Concerns

**Purpose**: Finish validation, documentation parity, non-functional render proof, and operator smoke coverage across all stories.

- [X] T035 [P] Reconcile final source inventory, source hierarchy, recovery vocabulary, fallback matrix, and verification commands in `specs/199-global-context-shell-contract/plan.md`, `specs/199-global-context-shell-contract/research.md`, `specs/199-global-context-shell-contract/data-model.md`, `specs/199-global-context-shell-contract/contracts/global-context-shell.logical.openapi.yaml`, and `specs/199-global-context-shell-contract/quickstart.md`
- [X] T036 [P] Run the focused Pest validation pack from `specs/199-global-context-shell-contract/quickstart.md`, including DB-only render and no-enqueue shell proof
- [X] T037 Run formatting with `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
- [X] T038 [P] Execute the timed 3-second manual smoke checklist from `specs/199-global-context-shell-contract/quickstart.md` for tenantless entry, workspace switch, tenant select, tenant clear, evidence fallback, canonical workspace record viewer fallback, invalid remembered tenant, explicit chooser-route exception handling, and panel parity

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: Starts immediately and creates the focused regression scaffolding and verification baseline.
- **Foundational (Phase 2)**: Depends on Setup and blocks all story work until the canonical resolver seams are in place.
- **User Stories (Phase 3+)**: All depend on Foundational completion.
- **Polish (Phase 8)**: Depends on the desired user stories being complete.

### User Story Dependencies

- **US1**: Depends only on the foundational resolver seam and is the recommended MVP slice.
- **US2**: Depends on the foundational seam and can proceed independently of US1 once canonical workspace and tenant precedence exist.
- **US3**: Depends on the foundational seam and can proceed independently of US1 and US2, though it benefits from the shared shell display already being consumer-only.
- **US4**: Depends on the foundational seam and should land after the invalid-context matrix is stable, but it does not require US2 or US3 to be complete.
- **US5**: Depends on the foundational seam and benefits from at least one earlier story landing first so panel parity and search safety are verified against the implemented contract.

### Within Each User Story

- Story tests should be written before or alongside implementation and should fail before the story is considered complete.
- Resolver and storage seam updates must land before controller, middleware, or shell display changes are considered finished.
- Authorization-sensitive regressions must stay in Unit or Feature lanes only; no browser family should be added for this feature.
- Each story-level verification task should run after the story's implementation tasks are complete.

### Parallel Opportunities

- `T001`, `T002`, and `T003` can run in parallel during Setup.
- `T005` and `T006` can run in parallel during Foundational work.
- `T008` and `T009` can run in parallel for User Story 1.
- `T013` and `T014` can run in parallel for User Story 2.
- `T018` and `T019` can run in parallel for User Story 3.
- `T024` and `T025` can run in parallel for User Story 4.
- `T030` and `T031` can run in parallel for User Story 5.
- `T035`, `T036`, and `T038` can run in parallel after implementation is complete.

---

## Parallel Example: User Story 1

```bash
# User Story 1 tests in parallel:
Task: "T008 Extend shared-shell truth display and no-hidden-page-state coverage in apps/platform/tests/Feature/Filament/WorkspaceContextTopbarAndTenantSelectionTest.php and apps/platform/tests/Feature/Spec085/OperationsIndexHeaderTest.php"
Task: "T009 Add recovery-shell display assertions in apps/platform/tests/Feature/Filament/WorkspaceContextRecoveryDisplayTest.php"

# Then land the shared shell implementation:
Task: "T010 Reduce the shared shell to a consumer-only resolved-context display and keep page-local filters, tabs, and inspect state out of the shell contract in apps/platform/resources/views/filament/partials/context-bar.blade.php"
Task: "T011 Keep both panels rendering the same shared shell contract in apps/platform/app/Providers/Filament/AdminPanelProvider.php and apps/platform/app/Providers/Filament/TenantPanelProvider.php"
```

## Parallel Example: User Story 2

```bash
# User Story 2 tests in parallel:
Task: "T013 Add switch regression coverage in apps/platform/tests/Feature/Workspaces/SwitchWorkspaceControllerTest.php, apps/platform/tests/Feature/Workspaces/WorkspaceRedirectResolverTest.php, and apps/platform/tests/Feature/Workspaces/SwitchWorkspaceRedirectsToTenantRegistrationWhenNoTenantsTest.php"
Task: "T014 Extend workspace-switch affordance coverage in apps/platform/tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php and apps/platform/tests/Feature/Workspaces/ChooseWorkspaceRedirectsToChooseTenantTest.php"

# Then land controller and redirect behavior:
Task: "T015 Make workspace switching re-evaluate tenant compatibility in apps/platform/app/Http/Controllers/SwitchWorkspaceController.php and apps/platform/app/Support/Workspaces/WorkspaceContext.php"
Task: "T016 Canonicalize post-switch destination rules in apps/platform/app/Support/Workspaces/WorkspaceRedirectResolver.php and apps/platform/app/Support/Workspaces/WorkspaceIntendedUrl.php"
```

## Parallel Example: User Story 3

```bash
# User Story 3 tests in parallel:
Task: "T018 Extend explicit tenant-selection coverage in apps/platform/tests/Feature/Workspaces/SelectTenantControllerTest.php and apps/platform/tests/Feature/Filament/WorkspaceContextTopbarAndTenantSelectionTest.php"
Task: "T019 Extend clear-tenant route-compatibility coverage in apps/platform/tests/Feature/Spec085/OperationsIndexHeaderTest.php and apps/platform/tests/Feature/Workspaces/ChooseTenantPageTest.php"

# Then land explicit scope-mutation behavior:
Task: "T020 Align explicit tenant selection with the canonical shell contract in apps/platform/app/Http/Controllers/SelectTenantController.php and apps/platform/app/Support/OperateHub/OperateHubShell.php"
Task: "T021 Standardize clear-tenant recovery destinations in apps/platform/app/Http/Controllers/ClearTenantContextController.php and apps/platform/app/Support/Tenants/TenantPageCategory.php"
```

## Parallel Example: User Story 4

```bash
# User Story 4 tests in parallel:
Task: "T024 Add invalid route, query-hint, and stale remembered-context coverage in apps/platform/tests/Feature/Workspaces/GlobalContextShellContractTest.php and apps/platform/tests/Unit/Support/Workspaces/WorkspaceContextRememberedTenantTest.php"
Task: "T025 Extend tenant-required fallback, workspace-required recovery, and explicit chooser-route exception coverage in apps/platform/tests/Feature/Workspaces/ChooseTenantPageTest.php, apps/platform/tests/Feature/Workspaces/ChooseWorkspacePageTest.php, and apps/platform/tests/Feature/Workspaces/EnsureWorkspaceSelectedMiddlewareTest.php"

# Then land middleware and fallback behavior:
Task: "T026 Replace ad hoc tenant-selection heuristics in apps/platform/app/Support/Middleware/EnsureFilamentTenantSelected.php"
Task: "T027 Tighten page-category classification and invalid-context fallback mapping, including the explicit workspace-independent chooser-route exception, in apps/platform/app/Support/Tenants/TenantPageCategory.php and apps/platform/app/Support/OperateHub/OperateHubShell.php"
```

## Parallel Example: User Story 5

```bash
# User Story 5 tests in parallel:
Task: "T030 Add admin-versus-tenant panel parity coverage in apps/platform/tests/Feature/Filament/WorkspaceContextTopbarAndTenantSelectionTest.php and apps/platform/tests/Feature/Workspaces/WorkspacesResourceIsTenantlessTest.php"
Task: "T031 Extend global-search context-safety coverage in apps/platform/tests/Feature/Rbac/AdminGlobalSearchContextSafetyTest.php, apps/platform/tests/Feature/TenantRBAC/TenantSwitcherScopeTest.php, and apps/platform/tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php"

# Then land panel-parity and search-scope behavior:
Task: "T032 Keep panel-specific context sources subordinate to the canonical shell contract in apps/platform/app/Filament/Concerns/ResolvesPanelTenantContext.php, apps/platform/app/Providers/Filament/AdminPanelProvider.php, and apps/platform/app/Providers/Filament/TenantPanelProvider.php"
Task: "T033 Preserve tenant-safe global search scoping in apps/platform/app/Filament/Concerns/ScopesGlobalSearchToTenant.php, apps/platform/app/Filament/Resources/TenantResource.php, and apps/platform/app/Filament/Resources/PolicyResource.php"
```

---

## Implementation Strategy

### MVP First (User Story 1 Only)

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. Validate that the shared shell shows one truthful tenant-scoped and tenantless model before moving on.

### Incremental Delivery

1. Establish the canonical shell resolver and storage semantics.
2. Deliver truthful shared-shell display as the MVP.
3. Add deterministic workspace switching.
4. Add deterministic tenant select and clear flows.
5. Harden invalid-context recovery.
6. Close with cross-panel parity, search safety, and final validation.

### Parallel Team Strategy

1. One developer can land Setup plus Foundational resolver seams.
2. After Foundational work is complete, one developer can take US1 or US2 while another works on US3 or US4 because the primary file overlap is limited.
3. US5 should land after at least one earlier story so panel parity and global-search safety verify the real implemented contract.

---

## Notes

- `[P]` tasks are limited to work on different files or isolated test files with no incomplete dependency overlap.
- `[US1]` through `[US5]` map directly to the user stories in `spec.md`.
- The suggested MVP scope is Phase 1 through Phase 3 only.
- This task list preserves Filament v5 and Livewire v4 compliance, keeps provider registration unchanged in `bootstrap/providers.php`, keeps destructive-action rules unchanged because no destructive record action is introduced, and preserves existing tenant-safe global search behavior while the shell contract is consolidated.