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