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

# Feature Specification: Workspace Switch Semantic Fix

**Feature Branch**: `121-workspace-switch-fix`  
**Created**: 2026-03-07  
**Status**: Draft  
**Input**: User description: "Separate workspace switching from workspace management in the context bar so the Switch workspace action always routes to the canonical workspace chooser instead of the workspace CRUD index. Keep workspace switching as a context-bar-only affordance rather than a user-menu shortcut."

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace
- **Primary Routes**: authenticated admin and tenant-panel context bar workspace switch entry; workspace chooser flow at `/admin/choose-workspace`; workspace management page at `/admin/workspaces`
- **Data Ownership**: workspace-owned context selection only; no new workspace records or workspace management data changes
- **RBAC**: authenticated users continue to switch only among workspaces they already belong to; workspace management remains behind its existing administrative capabilities with no visibility or permission expansion

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Direct workspace switching (Priority: P1)

As a user with access to multiple workspaces, I can choose “Switch workspace” from the context bar and land on the workspace chooser instead of a management table.

**Why this priority**: This is the core product expectation and the highest-visibility confusion point for multi-workspace usage.

**Independent Test**: Can be fully tested by opening the context bar, activating “Switch workspace,” and confirming the chooser experience appears without exposing CRUD-oriented management UI.

**Acceptance Scenarios**:

1. **Given** a signed-in user with access to multiple workspaces, **When** the user selects “Switch workspace” from the context bar, **Then** the user is taken directly to the workspace chooser flow.
2. **Given** a signed-in user who opens the chooser from the context bar, **When** the chooser loads, **Then** the user sees the existing workspace selection experience rather than a workspace management list.
3. **Given** a signed-in user with access to multiple workspaces, **When** the user opens the top-right user menu, **Then** no separate `Switch workspace` shortcut is shown there.

---

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

As an administrator, I can still reach workspace management through its dedicated administrative destination without mixing it into the context-switching action.

**Why this priority**: The product must preserve the distinction between operational context switching and administrative CRUD management.

**Independent Test**: Can be fully tested by confirming the context bar action changes destination while the existing workspace management entry remains reachable and unchanged.

**Acceptance Scenarios**:

1. **Given** an administrator with workspace management access, **When** the administrator uses the dedicated management navigation path at `/admin/workspaces`, **Then** the administrator still reaches the workspace management experience.
2. **Given** an administrator using the context bar, **When** the administrator selects “Switch workspace,” **Then** the action does not open workspace management.

---

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

As a user, I experience consistent navigation after switching intent is corrected, with no loops, broken breadcrumbs, or dead-end routes.

**Why this priority**: The change is small but high-visibility, so surrounding navigation must remain coherent to avoid replacing one confusion point with another.

**Independent Test**: Can be fully tested by following the switch path and the management path separately and confirming both destinations remain stable and understandable.

**Acceptance Scenarios**:

1. **Given** a user who arrives at the chooser from the context bar, **When** the user navigates within the chooser flow, **Then** page title, breadcrumbs, and back-navigation remain consistent with workspace selection intent.
2. **Given** a user who previously used workspace management, **When** the user accesses it through the existing administrative path, **Then** the management route continues to behave as before.

### Edge Cases

- What happens when a user has access to only one workspace but the switch entry is still shown in the context bar? The action should still resolve to the chooser flow rather than rerouting to management.
- How does the system handle a user whose active workspace becomes unavailable between rendering the context bar and clicking the switch action? The user should still be routed to the chooser, where existing entitlement handling determines the next safe state.
- What happens if a user lacks workspace management capability? The context-switching entry must still work without revealing or implying management access.
- How does the system handle stale bookmarks to workspace management? Existing management links remain valid and separate from switching intent.
- What happens if a user looks for workspace switching in the top-right user menu? The product should not duplicate the affordance there; the context bar remains the single canonical switch surface.

## Requirements *(mandatory)*

### Constitution Alignment Notes

- This feature introduces no Microsoft Graph calls, no queued or scheduled work, and no write-oriented operational workflows, so contract registry, audit-run orchestration, and `OperationRun` requirements are unchanged.
- This feature does not introduce new authorization rules. It preserves the current workspace membership and capability model while correcting navigation semantics.
- No status badge semantics change.
- The Filament action surface change is a navigation-only context bar action. The Action Surface Contract is satisfied because the action is non-destructive, capability-aware behavior is preserved, and no mutation path is added.
- UX-001 remains satisfied for the affected surface because workspace switching continues to use a dedicated chooser experience, while workspace management remains a distinct administrative destination.

### Functional Requirements

- **FR-001**: The system MUST route the context-bar “Switch workspace” action to the canonical workspace chooser URL (`/admin/choose-workspace?choose=1`).
- **FR-002**: The system MUST preserve the workspace chooser as the primary and explicit experience for changing active workspace context, and MUST NOT route switching intent to workspace CRUD/management surfaces.
- **FR-003**: The system MUST keep workspace management available through its existing dedicated administrative destination at `/admin/workspaces`.
- **FR-004**: The system MUST preserve existing visibility and permission rules for workspace management.
- **FR-005**: The system MUST keep navigation and breadcrumb behavior coherent after the destination change.
- **FR-006**: The system MUST preserve current capability-aware handling for users who can switch workspaces but cannot manage workspaces.
- **FR-007**: The system MUST expose workspace switching through the context bar only, and MUST NOT register a duplicate `Switch workspace` shortcut in the Filament user menu.

## UI Action Matrix *(mandatory when Filament is changed)*

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Context bar workspace switcher | Global admin and tenant-panel context bar | None | Not applicable | `Switch workspace` (navigation only) | None | None | Not applicable | Not applicable | No | Navigation-only action. Destination changes to the chooser flow. No destructive behavior, no mutation, and no authorization expansion. |
| User menu workspace shortcut | Top-right user menu | None | Not applicable | None | None | None | Not applicable | Not applicable | No | Explicitly absent by design. Workspace switching remains anchored in the context bar to preserve context-vs-account semantics. |
| Workspace management navigation | Existing admin navigation destination | Existing actions unchanged | Existing management affordances unchanged | Existing actions unchanged | Existing actions unchanged | Existing empty-state behavior unchanged | Existing actions unchanged | Existing save/cancel behavior unchanged | Unchanged | Included for separation-of-concerns verification only; this feature does not change management behavior. |

### Key Entities *(include if feature involves data)*

- **Active Workspace Context**: The current workspace the user is operating in, which determines the semantic purpose of the switch action.
- **Workspace Chooser Experience**: The dedicated selection flow users rely on to change active workspace context safely and intentionally.
- **Workspace Management Experience**: The separate administrative surface for creating, editing, and reviewing workspaces.

## Assumptions

- The existing workspace chooser remains the canonical destination for context switching.
- The existing workspace management destination remains available at `/admin/workspaces` and does not need redesign as part of this feature.
- Current membership and capability checks already distinguish between switching accessible workspaces and managing workspace records.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: In validation, 100% of context-bar “Switch workspace” activations land on the workspace chooser rather than a management table.
- **SC-002**: A multi-workspace user can begin a workspace switch in one click from the context bar without encountering CRUD management controls.
- **SC-003**: Administrative users retain an unchanged path to workspace management during regression testing.
- **SC-004**: Manual QA confirms no broken links, redirect loops, or breadcrumb confusion across the switch and management paths.
- **SC-005**: Validation confirms the top-right user menu does not expose a separate `Switch workspace` shortcut.