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.