TenantAtlas/specs/121-workspace-switch-fix/tasks.md

# Tasks: Workspace Switch Semantic Fix

**Input**: Design documents from `/specs/121-workspace-switch-fix/`
**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/routes.md, quickstart.md

**Tests**: Tests are REQUIRED for this runtime behavior change. Use Pest feature tests via Sail.
**Operations**: No `OperationRun` work is required for this feature.
**RBAC**: No authorization model changes are planned; tasks must preserve existing workspace membership and capability behavior.
**Filament UI Action Surfaces**: The affected surface is a topbar navigation link; no new CRUD action surface is introduced, and the top-right user menu must not duplicate workspace switching.
**Filament UI UX-001**: No Create/Edit/View layout changes are required; preserve existing chooser and management screens.

**Organization**: Tasks are grouped by user story so each story remains independently testable.

## Phase 1: Setup (Shared Context)

**Purpose**: Align implementation with the existing chooser contract before touching code.

- [X] T001 [P] Review the canonical switch-route contract in specs/121-workspace-switch-fix/contracts/routes.md and specs/121-workspace-switch-fix/research.md
- [X] T002 [P] Inspect the current broken target in resources/views/filament/partials/context-bar.blade.php and the existing canonical switch pattern in app/Providers/Filament/AdminPanelProvider.php

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Confirm shared workspace-switch semantics that all stories depend on.

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

- [X] T003 Confirm forced-chooser and post-selection redirect semantics in app/Http/Middleware/EnsureWorkspaceSelected.php, app/Filament/Pages/ChooseWorkspace.php, app/Support/Workspaces/WorkspaceIntendedUrl.php, and app/Support/Workspaces/WorkspaceRedirectResolver.php

**Checkpoint**: Canonical chooser semantics are confirmed and user-story implementation can begin.

---

## Phase 3: User Story 1 - Direct workspace switching (Priority: P1) 🎯 MVP

**Goal**: Make the context-bar `Switch workspace` action always open the canonical chooser instead of workspace management.

**Independent Test**: Open a real admin page with the context bar and verify that `Switch workspace` points to the chooser URL with forced-chooser semantics, not to `/admin/workspaces`.

### Tests for User Story 1 ⚠️

> **NOTE**: Add or update these tests first and ensure they fail before implementation.

- [X] T004 [P] [US1] Extend tests/Feature/Monitoring/HeaderContextBarTest.php to assert the rendered `Switch workspace` link targets `/admin/choose-workspace?choose=1` and does not target `/admin/workspaces`
- [X] T005 [P] [US1] Update tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php to assert the top-right user menu does not expose a `Switch workspace` shortcut, even when multiple workspaces exist

### Implementation for User Story 1

- [X] T006 [US1] Update resources/views/filament/partials/context-bar.blade.php to route `Switch workspace` to `ChooseWorkspace::getUrl(panel: 'admin').'?choose=1'`
- [X] T016 [US1] Remove the duplicate `Switch workspace` user-menu action from app/Providers/Filament/AdminPanelProvider.php so the context bar is the only switch surface

**Checkpoint**: User Story 1 should now be independently functional and verifiable from the rendered admin topbar.

---

## Phase 4: User Story 2 - Preserve administrative separation (Priority: P2)

**Goal**: Keep workspace management reachable through its dedicated admin path without mixing it into the context-switching action.

**Independent Test**: Verify the chooser and admin navigation still expose `Manage workspaces` through `/admin/workspaces` while `Switch workspace` remains chooser-only.

### Tests for User Story 2 ⚠️

- [X] T007 [P] [US2] Extend tests/Feature/Workspaces/ChooseWorkspacePageTest.php to confirm authorized users still see `Manage workspaces`, unauthorized roles still do not, and the chooser management affordance continues to resolve to `/admin/workspaces`
- [X] T008 [P] [US2] Extend tests/Feature/Workspaces/WorkspaceNavigationHubTest.php to confirm navigation separation remains `Switch workspace` in the topbar only while `Manage workspaces` remains the dedicated admin navigation path to `/admin/workspaces`

### Implementation for User Story 2

- [X] T009 [US2] If T007 or T008 expose drift, update resources/views/filament/pages/choose-workspace.blade.php and/or app/Filament/Resources/Workspaces/WorkspaceResource.php so every `Manage workspaces` affordance still resolves to `/admin/workspaces` and remains separate from chooser-only switching

**Checkpoint**: User Story 2 should now prove that switching and management remain semantically distinct.

---

## Phase 5: User Story 3 - Maintain navigational coherence (Priority: P3)

**Goal**: Preserve existing chooser and redirect behavior so the semantic fix does not introduce loops or breadcrumb/navigation regressions.

**Independent Test**: Enter the chooser through the context-switch path and confirm existing forced-chooser and post-selection routing behavior remains intact.

### Tests for User Story 3 ⚠️

- [X] T010 [P] [US3] Extend tests/Feature/Workspaces/EnsureWorkspaceSelectedMiddlewareTest.php to keep `?choose=1` forced-chooser behavior covered for intentional workspace switching
- [X] T011 [P] [US3] Extend tests/Feature/Workspaces/ChooseWorkspaceRedirectsToChooseTenantTest.php to confirm chooser post-selection routing remains unchanged after the context-bar fix

### Implementation for User Story 3

- [X] T012 [US3] If T010 or T011 expose a regression, update app/Filament/Pages/ChooseWorkspace.php and/or app/Support/Workspaces/WorkspaceRedirectResolver.php so forced-chooser semantics and post-selection branching remain unchanged

**Checkpoint**: User Story 3 should confirm the fix changes only entry semantics, not downstream chooser behavior.

---

## Phase 6: Polish & Cross-Cutting Concerns

**Purpose**: Final verification and formatting for the complete change.

- [X] T013 Perform manual QA for `/admin/choose-workspace?choose=1` and `/admin/workspaces`, confirming page title, breadcrumbs, back-navigation, link targets, and absence of a user-menu switch shortcut remain coherent across switching and management flows
- [X] T014 Run focused Pest coverage with `vendor/bin/sail artisan test --compact` for tests/Feature/Monitoring/HeaderContextBarTest.php, tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php, tests/Feature/Workspaces/ChooseWorkspacePageTest.php, tests/Feature/Workspaces/WorkspaceNavigationHubTest.php, tests/Feature/Workspaces/EnsureWorkspaceSelectedMiddlewareTest.php, and tests/Feature/Workspaces/ChooseWorkspaceRedirectsToChooseTenantTest.php
- [X] T015 Run `vendor/bin/sail bin pint --dirty --format agent`

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: No dependencies; can start immediately.
- **Foundational (Phase 2)**: Depends on Setup completion; blocks all user stories.
- **User Story 1 (Phase 3)**: Depends on Foundational completion; this is the MVP.
- **User Story 2 (Phase 4)**: Depends on Foundational completion; can run after or in parallel with User Story 3 once User Story 1 direction is clear.
- **User Story 3 (Phase 5)**: Depends on Foundational completion; can run after or in parallel with User Story 2.
- **Polish (Phase 6)**: Depends on completion of the desired user stories.

### User Story Dependencies

- **US1**: No dependency on other stories; delivers the primary fix.
- **US2**: Depends only on the shared chooser/management contract, not on US3.
- **US3**: Depends only on the shared chooser contract, not on US2.

### Within Each User Story

- Tests should be updated first and observed failing before implementation.
- Implementation follows only after the story-specific regression tests are in place.
- Each story should remain independently testable when complete.

### Parallel Opportunities

- T001 and T002 can run in parallel.
- T004 and T005 can run in parallel.
- T007 and T008 can run in parallel.
- T010 and T011 can run in parallel.
- After Phase 2, US2 and US3 can proceed in parallel if staffed separately.

---

## Parallel Example: User Story 1

```bash
# Launch both regression updates for the switching contract together:
Task: "Extend tests/Feature/Monitoring/HeaderContextBarTest.php to assert the rendered Switch workspace link targets /admin/choose-workspace?choose=1 and does not target /admin/workspaces"
Task: "Update tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php to assert the top-right user menu does not expose a Switch workspace shortcut"
```

---

## Parallel Example: User Story 2

```bash
# Launch management-separation regression coverage together:
Task: "Extend tests/Feature/Workspaces/ChooseWorkspacePageTest.php to confirm authorized users still see Manage workspaces on the chooser and unauthorized roles still do not"
Task: "Extend tests/Feature/Workspaces/WorkspaceNavigationHubTest.php to confirm navigation separation remains Switch workspace in the topbar only and Manage workspaces in admin navigation"
```

---

## 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 the rendered topbar switch target
5. Stop and review before broader regression work if needed

### Incremental Delivery

1. Ship the chooser-target fix in US1
2. Add management-separation regression protection in US2
3. Add chooser-flow coherence regression protection in US3
4. Finish with focused tests and formatting

### Parallel Team Strategy

With multiple contributors:

1. One contributor updates the context-bar and topbar regression tests (US1)
2. One contributor hardens management-separation regressions (US2)
3. One contributor hardens chooser-flow regressions (US3)
4. Recombine for focused Sail test execution and Pint

---

## Notes

- [P] tasks touch different files and can be executed in parallel.
- User story labels map each task to the corresponding spec story.
- No migrations, no new routes, and no new dependencies are expected.
- Preserve existing chooser redirect behavior unless a failing regression test proves otherwise.