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.

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

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

• 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
• 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

• T006 [US1] Update resources/views/filament/partials/context-bar.blade.php to route Switch workspace to ChooseWorkspace::getUrl(panel: 'admin').'?choose=1'
• 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 ⚠️

• 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
• 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

• 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 ⚠️

• T010 [P] [US3] Extend tests/Feature/Workspaces/EnsureWorkspaceSelectedMiddlewareTest.php to keep ?choose=1 forced-chooser behavior covered for intentional workspace switching
• 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

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

• 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
• 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
• 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

# 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

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