# Feature Specification: Workspace / Environment Surface Scope Contract

**Feature Branch**: `311-workspace-environment-surface-scope-contract`
**Created**: 2026-05-15
**Status**: Draft
**Input**: User decision: split former mixed 311 work so 311 delivers the global workspace/environment navigation-scope contract and 312 delivers Customer Review Workspace v1 completion.

## Spec Candidate Check *(mandatory - SPEC-GATE-001)*

- **Problem**: Workspace-wide admin surfaces can inherit global or remembered environment context, causing topbar/sidebar/breadcrumb to imply an environment-bound route while the page is actually workspace-wide with an environment filter.
- **Today's failure**: Customer Review Workspace can show `workspace > environment` in the shell and an active environment table filter at the same time. The same pattern can recur in Operations, Decision Register, Governance Inbox, Evidence Overview, Audit Log, Provider Connections, and Alerts if scope is solved page-by-page.
- **User-visible improvement**: Operators can distinguish route context from data filters: workspace-wide pages keep workspace navigation, and environment filters remain page-level controls.
- **Smallest enterprise-capable version**: A central route-taxonomy contract plus focused tests for representative workspace-wide, environment-bound, and legacy tenant-owned surfaces.
- **Explicit non-goals**: No Customer Review Workspace product completion, Review Pack changes, RBAC changes, migrations, new tables, broad navigation rebuild, billing, localization, artifact lifecycle, PSA, or AI work.
- **Permanent complexity imported**: One narrow route-category classification for explicit workspace-wide admin surfaces.
- **Why now**: Continuing Customer Review Workspace v1 would otherwise encode a shell/sidebar exception into one page and repeat the bug on the next workspace hub.
- **Why not local**: A local CRW fix would not protect Decision Register, Governance Inbox, Audit Log, Provider Connections, Alerts, or future workspace-wide hubs.
- **Approval class**: Core Enterprise.
- **Red flags triggered**: Cross-cutting taxonomy/classification. Covered by proportionality review below.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12**
- **Decision**: approve.

## Spec Scope Fields *(mandatory)*

- **Scope**: platform admin shell, route taxonomy, topbar/sidebar scope, and page-level environment filter defaults.
- **Primary Routes**: `/admin/workspaces/{workspace}/operations`, `/admin/reviews/workspace`, `/admin/reviews`, `/admin/governance/decisions`, `/admin/governance/inbox`, `/admin/evidence/overview`, `/admin/audit-log`, `/admin/provider-connections`, `/admin/alerts`, `/admin/workspaces/{workspace}/overview`, and `/admin/workspaces/{workspace}/environments/{environment}/...`.
- **Data Ownership**: No ownership model changes. Workspace-wide surfaces aggregate workspace-authorized data; environment-bound routes remain canonical environment context.
- **RBAC**: No RBAC capability changes. Existing server-side authorization remains the security boundary.

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: Explicit workspace-wide surfaces must not default their page filter from Filament tenant or remembered tenant context. Query parameters may set page-level filters when the page already supports that filter.
- **Explicit entitlement checks preventing cross-tenant leakage**: Existing workspace and environment entitlement checks continue to apply. UI shell scope is not authorization.

## Cross-Cutting / Shared Pattern Reuse *(mandatory)*

- **Cross-cutting feature?**: yes, admin shell and navigation scope.
- **Interaction class(es)**: topbar context, sidebar registration, page-level filters, header KPI/list widgets.
- **Systems touched**: `TenantPageCategory`, `TenantInteractionLane`, `OperateHubShell`, Operations KPI, Alert Delivery list/KPI, Provider Connection filter default, Review Register, Customer Review Workspace, and focused tests.
- **Existing pattern(s) to extend**: existing `TenantPageCategory`, `NavigationScope`, `OperateHubShell`, and `CanonicalAdminTenantFilterState`.
- **Shared contract / presenter / builder / renderer to reuse**: reuse route taxonomy and shell context resolution; no new service or registry.
- **Why the existing shared path is sufficient or insufficient**: Existing taxonomy distinguishes tenant-bound and workspace-scoped routes but did not distinguish explicit workspace-wide hubs from legacy tenant-owned admin lists.
- **Allowed deviation and why**: Add one route-category case for explicit workspace-wide surfaces. This is narrower than a new contract registry.
- **Consistency impact**: Query parameters must not alter navigation scope. Page filters must stay visible as filters.
- **Review focus**: Verify no per-page hardcoded shell exception and no `?tenant` sidebar magic.

## OperationRun UX Impact *(mandatory)*

- **Touches OperationRun start/completion/link UX?**: Operations list and KPI shell/filter behavior only.
- **Shared OperationRun UX contract/layer reused**: Existing Operations page and `OperationRunLinks` remain canonical.
- **Delegated start/completion UX behaviors**: unchanged.
- **Local surface-owned behavior that remains**: Operations table query and tabs remain page-owned.
- **Queued DB-notification policy**: unchanged.
- **Terminal notification path**: unchanged.
- **Exception required?**: none.

## Provider Boundary / Platform Core Check *(mandatory)*

- **Shared provider/platform boundary touched?**: yes, provider-neutral admin surface terminology.
- **Boundary classification**: platform-core shell/navigation.
- **Seams affected**: provider connections and alerts as workspace-owned/provider-level surfaces.
- **Neutral platform terms preserved or introduced**: Use workspace, environment, provider connection, target scope.
- **Provider-specific semantics retained and why**: Microsoft/Intune resource pages outside the explicit workspace-wide surface set retain current tenant-owned behavior until their route cutover is separately specified.
- **Why this does not deepen provider coupling accidentally**: Route-scope classification is platform-owned and provider-neutral.
- **Follow-up path**: remaining legacy tenant-owned direct admin lists stay covered by existing route-audit specs, not by this minimal 311 branch.

## UI / Surface Guardrail Impact *(mandatory)*

| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---:|---|---|---|---:|---|
| Admin shell topbar/sidebar scope | yes | Filament/native hooks | global shell/navigation | route category, shell context | no | No styling or asset changes |
| Operations / Review / Governance / Audit / Alerts filters | yes | Filament tables/widgets | workspace-wide filters | table filter defaults | no | Existing filters remain |
| Environment-bound canonical routes | no behavioral expansion | Filament resources/pages | canonical environment context | route category only | no | Must remain environment-bound |

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: no new persisted truth. Route path remains the source of route scope.
- **New persisted entity/table/artifact?**: no.
- **New abstraction?**: no new service. One enum category is added to an existing taxonomy.
- **New enum/state/reason family?**: yes, `WorkspaceWideSurface` in the existing `TenantPageCategory`.
- **New cross-domain UI framework/taxonomy?**: no framework. Narrow taxonomy hardening only.
- **Current operator problem**: The shell can show an environment context while the page is workspace-wide and separately filtered.
- **Existing structure is insufficient because**: `WorkspaceScoped` covers both explicit workspace hubs and legacy tenant-owned admin lists, so forcing all of it tenantless breaks legacy data surfaces while not forcing any of it leaves CRW/Alerts/Audit ambiguous.
- **Narrowest correct implementation**: Classify only explicit workspace-wide surface routes centrally and make `OperateHubShell` tenantless for that category.
- **Ownership cost**: Future workspace-wide surfaces must be added to the taxonomy and tests.
- **Alternative intentionally rejected**: Hardcoding `/admin/reviews/workspace` in `OperateHubShell`, switching sidebar based on `?tenant`, or broad-rebuilding all navigation.
- **Release truth**: Current-release platform shell behavior.

### Compatibility posture

Pre-production compatibility allows route taxonomy hardening without migration shims. Legacy tenant-owned direct admin lists are not rewritten in this slice.

## Global Admin Surface Scope Contract

1. Route scope determines sidebar, topbar, and breadcrumb.
2. Query parameters such as `tenant`, `environment`, `managed_environment_id`, and `tenant_scope` never change navigation scope.
3. Workspace-wide pages remain workspace-wide even when an environment filter is active.
4. Environment-bound navigation is allowed only on canonical `/admin/workspaces/{workspace}/environments/{environment}/...` routes.
5. Topbar must reflect route scope.
6. Page-level filters must appear as filters, not global context.
7. Remembered or last selected environment must not auto-bind workspace-wide hubs.
8. Workspace-wide pages need explicit all-environments or filtered-by-environment semantics.
9. Environment-owned detail links should use canonical environment-bound URLs when the detail is environment context.
10. Filtered empty states must mention active filters.
11. Direct URL and RBAC remain server-side protected; UI context is not authorization.
12. No sidebar magic based on `?tenant`.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Workspace-wide shell stays workspace-wide (Priority: P1)

As an operator on a workspace hub, I want the topbar/sidebar to stay at workspace scope even when I arrive with an environment query filter.

**Independent Test**: Visit representative workspace-wide routes with `tenant` or `managed_environment_id` query parameters and assert no environment shell scope appears.

### User Story 2 - Environment-bound routes keep environment context (Priority: P1)

As an operator on a canonical environment route, I want the shell to show the selected environment and environment navigation.

**Independent Test**: Visit `/admin/workspaces/{workspace}/environments/{environment}/...` and assert environment route classification remains environment-bound.

### User Story 3 - Legacy tenant-owned lists do not regress (Priority: P1)

As an operator using legacy tenant-owned admin lists, I want existing data scoping to remain intact until those surfaces are explicitly cut over.

**Independent Test**: Existing tenant-owned resource parity tests still pass while explicit workspace-wide surfaces use the new shell contract.

## Anti-Patterns To Avoid

- `?tenant` switches sidebar.
- Global selected environment on workspace-wide hubs.
- Double semantics: topbar environment plus table environment filter.
- Customer-safe detail forced onto a workspace-only route.
- New per-page shell exceptions.