TenantAtlas/specs/280-workspace-tenancy-environment-routing/spec.md

# Feature Specification: Filament Workspace Tenancy & Environment Routing Cutover

**Feature Branch**: `280-workspace-tenancy-environment-routing`  
**Created**: 2026-05-07  
**Status**: Ready  
**Input**: User description: "Work only in /Users/ahmeddarrazi/Documents/projects/wt-plattform on branch 280-workspace-tenancy-environment-routing. Update only spec-prep artifacts, no application code. Fill /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/280-workspace-tenancy-environment-routing/spec.md as the implementation-ready spec for candidate `280 - Filament Workspace Tenancy & Environment Routing Cutover` from docs/product/spec-candidates.md and docs/product/roadmap.md."

## Spec Candidate Check

- **Problem**: TenantPilot's operator runtime is still split between the workspace-scoped admin panel under `/admin` and the temporary ManagedEnvironment-scoped Filament panel under `/admin/t`. That leaves the public route contract, breadcrumbs, chooser flow, middleware, and deep-link builders behind the core model cutover completed in Spec `279`.
- **Today's failure**: Verified repo seams such as `TenantPanelProvider`, `ChooseTenant`, `WorkspaceRedirectResolver`, `EnsureWorkspaceSelected`, `EnsureFilamentTenantSelected`, `TenantPageCategory`, `OperationRunLinks`, and many `panel: 'tenant'` links still route operators into `/admin/t/{environment}` or `/admin/tenants/{environment}`. Operators move from a workspace surface into a second panel with a different route language, while current operations remain canonical at workspace scope. The product therefore still communicates two different truths about where environment work actually lives.
- **User-visible improvement**: Operators get one workspace-first admin runtime: workspace dashboard, workspace-scoped environment chooser, managed-environment dashboard, workspace-scoped operations hub, and breadcrumbs that consistently read `Workspace -> Managed Environment -> domain page`.
- **Smallest enterprise-capable version**: Collapse the temporary `/admin/t` panel into the existing `/admin` admin panel, configure `Workspace` as the only Filament tenant, move environment pages under `/admin/workspaces/{workspace}/environments/{environment}`, make `/admin/workspaces/{workspace}/operations` the canonical operations route, reuse the existing workspace and environment dashboard builders, and remove the old route families without adding aliases or compatibility redirects.
- **Explicit non-goals**: No provider extraction, no governance-artifact retargeting, no provider-neutral capability registry, no provider-neutral artifact taxonomy, no RBAC redesign, no UI copy neutralization beyond route/breadcrumb/context truth needed by this slice, no quality-gate pack beyond feature-local routing/tenancy proof, no customer-portal cutover, no second Filament tenancy at the environment level, and no compatibility routes or dual-panel end state.
- **Permanent complexity imported**: One admin-panel tenancy flip from temporary environment-panel ownership to workspace tenancy, one canonical workspace-first environment route family, one route/breadcrumb/current-context contract update across chooser and deep-link seams, and focused feature/browser plus guard coverage. No new persistence, enum family, abstraction layer, or asset system is introduced.
- **Why now**: Spec `279` already changed the core managed-target noun to `ManagedEnvironment`, and the verified controlling seam still shows the old shell in `TenantPanelProvider` with `path('admin/t')` and `tenant(ManagedEnvironment::class, slugAttribute: 'slug')`. Until `280` closes that shell, every later reserved cutover slice (`281`-`287`) sits on an intentionally temporary panel and route contract.
- **Why not local**: This is not one page or one redirect. The temporary shell is encoded in provider registration, chooser flow, middleware, route categorization, current-context resolution, dashboard links, operations links, and resource URLs. A local fix would create the same hidden compatibility layer that the candidate and constitution reject.
- **Approval class**: Core Enterprise
- **Red flags triggered**: Many touched operator surfaces and a foundation-sounding cutover. Defense: the slice explicitly reuses existing workspace and environment dashboard builders, removes a temporary panel instead of adding framework machinery, forbids compatibility routes, and defers the remaining provider/artifact/RBAC/copy/quality follow-up to reserved Specs `281`-`287`.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12**
- **Decision**: approve

## Spec Scope Fields

- **Scope**: workspace
- **Primary Routes**:
  - `/admin` remains the operator entrypoint only and resolves to workspace chooser or the currently selected workspace dashboard; it is not a second canonical environment dashboard route
  - `/admin/workspaces/{workspace}` becomes the canonical workspace dashboard route for the active workspace
  - `/admin/workspaces/{workspace}/environments` becomes the canonical workspace-scoped environment chooser route
  - `/admin/workspaces/{workspace}/environments/{environment}` becomes the canonical managed-environment dashboard route
  - `/admin/workspaces/{workspace}/environments/{environment}/{domain...}` becomes the canonical family for environment-scoped resources, diagnostics, and detail pages that today resolve through `panel: 'tenant'` or `/admin/tenants/{environment}`
  - `/admin/workspaces/{workspace}/operations` and `/admin/workspaces/{workspace}/operations/{run}` become the canonical operations collection/detail routes
  - `/admin/w/{workspace}/managed-tenants`, `/admin/operations`, and `/admin/operations/{run}` are removed rather than retained as redirects, aliases, or hidden fallback readers
  - `/admin/t/{environment}` and `/admin/tenants/{environment}/required-permissions` are removed rather than retained as aliases
- **Data Ownership**:
  - `Workspace` remains the workspace-owned root context and becomes the only Filament tenant for operator admin routing
  - `ManagedEnvironment` remains the managed target nested inside a workspace and is resolved from workspace-first route parameters and current-context helpers, not from a second Filament tenant registration
  - no table ownership, artifact ownership, provider-profile ownership, or RBAC ownership changes are introduced in this slice
- **RBAC**:
  - workspace membership remains the first isolation boundary
  - managed-environment access remains the second isolation boundary
  - wrong-workspace or wrong-environment access remains `404`
  - in-scope actors missing capability remain `403`
  - no new role family, capability family, or authorization plane is introduced

Canonical-view handling for workspace-scoped monitoring surfaces:

- **Default filter behavior when tenant-context is active**: when an operator enters a workspace-scoped canonical view from a managed-environment dashboard or environment-scoped page, the canonical view opens prefiltered to that `managed_environment_id` inside the current workspace; widening to all environments remains explicit.
- **Explicit entitlement checks preventing cross-tenant leakage**: route-bound `{workspace}` and `{environment}` values must match each other and the current actor's entitlements. Explicit environment query hints outside the current workspace or outside the actor's membership resolve as `404`, while stale remembered filters are discarded instead of leaking or cross-loading another environment.

## Cross-Cutting / Shared Pattern Reuse

- **Cross-cutting feature?**: yes
- **Interaction class(es)**: navigation entry points, context selection, dashboard signals, breadcrumbs, page context bars, workspace-to-environment drillthroughs, operations deep links, and route builders
- **Systems touched**: `AdminPanelProvider`, `TenantPanelProvider`, `ChooseWorkspace`, `ChooseTenant`, `WorkspaceOverview`, `TenantDashboard`, `Monitoring\Operations`, `WorkspaceRedirectResolver`, `EnsureWorkspaceSelected`, `EnsureFilamentTenantSelected`, `ResolvesPanelTenantContext`, `TenantPageCategory`, `WorkspaceOverviewBuilder`, `TenantDashboardSummaryBuilder`, `OperationRunLinks`, and `RelatedNavigationResolver`
- **Existing pattern(s) to extend**: the existing `/admin` workspace panel, current workspace chooser flow, current `WorkspaceOverview` dashboard signals, current `TenantDashboard` environment signals, and the current tenant-safe operations link builders
- **Shared contract / presenter / builder / renderer to reuse**: `WorkspaceOverviewBuilder`, `TenantDashboardSummaryBuilder`, `WorkspaceContext`, `WorkspaceRedirectResolver`, `OperationRunLinks`, `RelatedNavigationResolver`, and the existing Filament page/resource action-surface contracts
- **Why the existing shared path is sufficient or insufficient**: these shared seams already own the user-facing signals and links that the final routing contract needs. What is insufficient today is not the dashboard or monitoring content itself, but the temporary second-panel route ownership and the mixed `/admin/t` versus `/admin/tenants` public path language.
- **Allowed deviation and why**: none. This slice removes the temporary panel and route family instead of introducing another exception.
- **Consistency impact**: workspace chooser, environment chooser, dashboard links, operations links, breadcrumbs, context bar signals, and page-level deep links must all speak the same workspace-first route language and the same `Workspace -> Managed Environment -> domain page` hierarchy.
- **Review focus**: reviewers must verify that `WorkspaceOverview` and `TenantDashboard` are reused rather than replaced, that `OperationRunLinks` and related builders stop emitting `panel: 'tenant'` or `/admin/t` URLs, and that no second route language or compatibility redirect remains.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: yes, link semantics only
- **Shared OperationRun UX contract/layer reused**: `OperationRunLinks`, `RelatedNavigationResolver`, the existing `Monitoring\Operations` page, and the existing canonical navigation context helpers
- **Delegated start/completion UX behaviors**: workspace-safe route resolution for operations index/detail, workspace-to-environment back-link context, and environment-prefiltered operations drillthrough via `managed_environment_id`; no new toast, queue, dedupe, terminal-notification, or artifact-link behavior is introduced
- **Local surface-owned behavior that remains**: environment dashboards and environment-scoped pages only supply the filter context and back-navigation label for the existing operations surface
- **Queued DB-notification policy**: `N/A`
- **Terminal notification path**: `N/A`
- **Exception required?**: none

## Provider Boundary / Platform Core Check

- **Shared provider/platform boundary touched?**: yes
- **Boundary classification**: mixed
- **Seams affected**: panel tenancy, route nouns, chooser wording, page-category classification, breadcrumb context, current-context resolution, and deep-link builders that still encode temporary environment-panel ownership
- **Neutral platform terms preserved or introduced**: `workspace`, `managed environment`, `environment`, `operations`, `findings`, `backup sets`, `evidence`, and `required permissions`
- **Provider-specific semantics retained and why**: provider-owned Microsoft terms may remain in untouched provider copy, metadata, or class names such as `TenantResource` until Specs `281` and `286` handle provider extraction and copy neutralization. This slice only requires that routing, breadcrumbs, panel tenancy, chooser labels, and context signals touched by the cutover become workspace/environment truthful.
- **Why this does not deepen provider coupling accidentally**: the slice removes a provider-shaped public shell instead of entrenching it. `Workspace` becomes the Filament tenant, `ManagedEnvironment` remains nested context, and no provider-profile fields or Microsoft-specific routing semantics are added to the platform-core route contract.
- **Follow-up path**: Spec `281` for provider-profile extraction, Spec `282` for artifact retargeting, Spec `285` for workspace-first RBAC scope follow-through, Spec `286` for copy neutralization, and Spec `287` for explicit no-legacy enforcement

## UI / Surface Guardrail Impact

| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Workspace dashboard under the canonical workspace route | yes | Native Filament page plus shared dashboard builders | navigation, dashboard signals, body CTA links | page, URL, summary state | no | Reuses `WorkspaceOverview` and `WorkspaceOverviewBuilder` rather than introducing a second workspace summary surface |
| Workspace-scoped environment chooser | yes | Native Filament simple page | context selection, navigation entry point | page, URL, remembered context | no | Reuses the existing chooser flow instead of adding a second environment selector |
| Managed-environment dashboard under the workspace-first route | yes | Native Filament dashboard plus shared widgets/builders | dashboard signals, header actions, page CTAs | page, URL, detail state | no | Reuses `TenantDashboard` and its current widget/action family; routing and breadcrumbs change, not the signal source |
| Workspace operations hub under `/admin/workspaces/{workspace}/operations` | yes | Native Filament monitoring page | operations links, back links, filter context | page, table, URL/query | no | Reuses the existing operations surface and moves only the public route ownership/context contract |
| Environment-scoped page family migrated off `/admin/t` and `/admin/tenants/{environment}` | yes | Native Filament resources/pages | navigation, breadcrumbs, current-context shell | page, detail, URL/query | no | Local action contracts stay intact; this slice changes route ownership and breadcrumb shell only |

## Decision-First Surface Role

| Surface | Decision Role | Human-in-the-loop Moment | Immediately Visible for First Decision | On-Demand Detail / Evidence | Why This Is Primary or Why Not | Workflow Alignment | Attention-load Reduction |
|---|---|---|---|---|---|---|---|
| Workspace dashboard under the canonical workspace route | Primary Decision Surface | Operator scans one workspace to decide which environment or workflow needs attention next | workspace-wide signal counts, attention items, recent operations, and quick actions | deeper environment detail remains one click away on the environment dashboard or operations hub | Primary because it is the workspace landing surface after workspace selection | Follows workspace-first operating flow instead of dropping straight into one environment panel | Removes the current panel split and makes workspace scope explicit before environment work begins |
| Workspace-scoped environment chooser | Primary Decision Surface | Operator chooses the managed environment they intend to act in | environment identity, lifecycle posture, and current workspace context | deeper environment diagnostics stay on the environment dashboard | Primary because environment selection is the next explicit decision after workspace selection | Keeps selection inside the same workspace panel instead of jumping into a second panel | Removes the cognitive break between workspace selection and environment work |
| Managed-environment dashboard under the workspace-first route | Secondary Context Surface | Operator confirms the chosen environment and decides which domain page to open next | environment posture, chips, recommended action, and dashboard signals | raw/support detail stays where it already belongs on downstream pages | Secondary because it is an environment workbench, not the workspace-wide landing decision surface | Aligns with today's dashboard-driven environment workflow, but under truthful workspace-first routing | Reduces wrong-environment actions by keeping workspace and environment context visible together |
| Workspace operations hub under `/admin/workspaces/{workspace}/operations` | Primary Decision Surface | Operator reviews queued and completed operations for one workspace, optionally narrowed to one environment | current workspace, active environment filter if present, operation status/outcome, and canonical back link | deeper run detail stays on the run viewer | Primary because operations already serve as the canonical monitoring surface | Preserves the existing monitoring workflow while removing the need to infer environment context from a second panel | Reduces duplicate monitoring entry points and keeps widening/narrowing explicit |
| Environment-scoped page family migrated off `/admin/t` and `/admin/tenants/{environment}` | Secondary Context Surface | Operator performs the chosen domain task inside one managed environment | breadcrumb/context shell plus the existing page-local operational truth | existing diagnostics remain page-local and unchanged | Secondary because the decision is made on dashboard or operations surfaces; these pages carry the work forward | Preserves each page's current workflow contract while making its scope truthful in navigation | Removes path-language drift without creating new page-local decision systems |

## Audience-Aware Disclosure

| Surface | Audience Modes In Scope | Decision-First Default-Visible Content | Operator Diagnostics | Support / Raw Evidence | One Dominant Next Action | Hidden / Gated By Default | Duplicate-Truth Prevention |
|---|---|---|---|---|---|---|---|
| Workspace dashboard under the canonical workspace route | operator-MSP, support-platform | workspace-wide attention, recent operations, and one next-action entry point | per-environment follow-up remains secondary | raw evidence stays on downstream pages | `Open environment` or `Open operations` depending on the top signal | raw evidence and low-level diagnostics remain downstream | workspace summary stays at workspace level and does not restate environment dashboards |
| Workspace-scoped environment chooser | operator-MSP, support-platform | current workspace plus selectable managed environments | lifecycle posture only | provider/raw detail hidden | `Open environment` | provider-specific raw metadata | chooser states selection truth once, then hands off to the environment dashboard |
| Managed-environment dashboard under the workspace-first route | operator-MSP, support-platform | environment summary, posture, and recommended next action | page-local diagnostics, support request detail, and additional widgets | raw evidence stays on dedicated downstream surfaces | primary follow-up action | support/raw evidence remains downstream and capability-gated where already required | dashboard shows the environment summary once and uses links for deeper evidence instead of repeating it |
| Workspace operations hub under `/admin/workspaces/{workspace}/operations` | operator-MSP, support-platform | workspace scope, optional environment filter, and operation follow-up state | run-level diagnostics remain on the run viewer | raw payloads remain on detail pages or related evidence surfaces | `Open operation` or `Back to environment` | low-level run evidence stays in detail | the hub states scope once and uses detail pages for deep evidence |
| Environment-scoped page family migrated off `/admin/t` and `/admin/tenants/{environment}` | operator-MSP, support-platform | breadcrumb scope plus each page's existing core truth | existing diagnostics stay on the page | support/raw evidence remains unchanged and page-local | the page's existing primary action | unrelated raw/support detail remains gated as today | the new shell adds context instead of duplicating page-local summaries |

## UI/UX Surface Classification

| Surface | Action Surface Class | Surface Type | Likely Next Operator Action | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type / Justification |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Workspace dashboard under the canonical workspace route | Dashboard / Context / Summary | Workspace landing dashboard | Open one environment or the operations hub | body CTA cards and quick actions | forbidden | body-level quick actions only | none | `/admin/workspaces/{workspace}` | `/admin/workspaces/{workspace}` | active workspace | Workspace | workspace-wide attention and recent operations | none |
| Workspace-scoped environment chooser | Selector / Context / Entry | Workspace environment selector | Open the intended managed environment | environment card/button | allowed | workspace switch remains secondary | none | `/admin/workspaces/{workspace}/environments` | `/admin/workspaces/{workspace}/environments/{environment}` | active workspace plus environment identity | Managed Environment | selectable environment identity and posture | none |
| Managed-environment dashboard under the workspace-first route | Dashboard / Detail / Workflow hub | Environment dashboard | Follow the recommended domain action | dashboard CTA from widget or header action | forbidden | grouped header secondary actions plus body links | none introduced by this slice | `/admin/workspaces/{workspace}/environments` | `/admin/workspaces/{workspace}/environments/{environment}` | active workspace and active managed environment | Managed Environment | environment posture, next action, and dashboard signals | none |
| Workspace operations hub under `/admin/workspaces/{workspace}/operations` | List / Table / Monitoring | Workspace monitoring hub | Inspect a run or widen/narrow environment scope | clickable row to run detail | required | header back-link and filter actions | none | `/admin/workspaces/{workspace}/operations` | `/admin/workspaces/{workspace}/operations/{run}` | active workspace and optional managed-environment filter | Operations / Operation | current scope, run state, and follow-up truth | none |
| Environment-scoped page family migrated off `/admin/t` and `/admin/tenants/{environment}` | List / Detail / Resource family | Workspace-first environment resources and diagnostics | Continue the chosen domain workflow | preserve each surface's current inspect model | preserve current contract | preserve current contract | preserve current contract | `/admin/workspaces/{workspace}/environments/{environment}/{domain}` | `/admin/workspaces/{workspace}/environments/{environment}/{domain}/{record?}` | breadcrumb `Workspace -> Managed Environment -> page` | Existing domain noun | active workspace/environment context plus each page's existing truth | none |

## Operator Surface Contract

| Surface | Primary Persona | Decision / Operator Action Supported | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|---|
| Workspace dashboard under the canonical workspace route | Workspace operator | Decide which environment or workspace-wide workflow needs attention first | Dashboard | What in this workspace needs my attention next? | workspace-wide attention, recent operations, quick actions | deeper environment evidence stays downstream | workspace attention, run activity, recovery posture | none | Open environment, Open operations | none |
| Workspace-scoped environment chooser | Workspace operator | Decide which managed environment to enter | Context-selection page | Which managed environment am I about to work in? | environment identity, posture, workspace context | deeper diagnostics remain on the dashboard | lifecycle posture, access posture | none | Open environment | none |
| Managed-environment dashboard under the workspace-first route | Environment operator | Decide which environment-scoped page to open next | Dashboard | What in this environment needs action now? | posture, dashboard chips, recommended action, summary widgets | support diagnostics and deeper evidence remain downstream | environment posture, readiness, attention state | existing page-local semantics only | Primary follow-up, More, Request support | none added by this slice |
| Workspace operations hub under `/admin/workspaces/{workspace}/operations` | Monitoring operator | Review runs across the workspace or one environment | Monitoring table/detail | Which operations need follow-up, and for which environment? | current scope, optional environment filter, run status/outcome, back link | run detail, evidence, and related links remain secondary | execution status, outcome, scope | read-only | Open operation, Back to environment, Show all environments | none |
| Environment-scoped page family migrated off `/admin/t` and `/admin/tenants/{environment}` | Environment operator | Perform the selected domain workflow in one environment | Resource/detail family | Am I acting in the correct workspace and managed environment? | breadcrumb scope and existing page truth | page-local diagnostics unchanged | preserve current domain-specific status families | preserve current page-local mutation semantics | preserve current page-local primary action | preserve current page-local dangerous actions |

## Proportionality Review

- **New source of truth?**: no
- **New persisted entity/table/artifact?**: no
- **New abstraction?**: no
- **New enum/state/reason family?**: no
- **New cross-domain UI framework/taxonomy?**: no
- **Current operator problem**: the operator runtime still communicates two conflicting truths: workspace-wide work begins on `/admin`, but environment work still lives on a temporary `/admin/t` panel and a second `/admin/tenants/{environment}` route family.
- **Existing structure is insufficient because**: the current structure requires special-casing `/admin/t` and `/admin/tenants` in provider setup, middleware, route categorization, chooser flow, and deep-link builders. As long as that split remains, later provider/artifact/RBAC cutovers would be forced to build on a known temporary shell.
- **Narrowest correct implementation**: reuse the current admin panel, workspace dashboard, environment dashboard, chooser flow, and operations surface, and change only the tenancy and public route ownership needed to remove the temporary shell.
- **Ownership cost**: route and deep-link retargeting across chooser, middleware, builders, breadcrumbs, and tests; removal of one panel provider from the operator runtime; and focused browser/feature coverage to keep the route contract honest.
- **Alternative intentionally rejected**: leaving the `/admin/t` panel in place with redirects, keeping `/admin/tenants/{environment}` as a second route family, or adding nested/dual Filament tenancy. Those options preserve the temporary shell instead of closing it.
- **Release truth**: current-release truth; this slice removes temporary runtime structure rather than preparing future framework flexibility

### Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, redirect shims, dual-panel ownership, dual-context restore paths, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

## Testing / Lane / Runtime Impact

- **Test purpose / classification**: Feature, Browser
- **Validation lane(s)**: fast-feedback, confidence, browser
- **Why this classification and these lanes are sufficient**: this slice changes panel tenancy, public routes, chooser flow, breadcrumbs, deep-link builders, and workspace/environment authorization semantics. Feature tests prove route ownership, filter context, and deny-as-not-found behavior; one narrow browser smoke proves the chooser-to-dashboard-to-operations flow still works end to end on the surviving admin panel.
- **New or expanded test families**: one workspace-tenancy/routing feature family, one environment-routing/breadcrumb feature family, one operations canonical-context feature family, one legacy-route-removal or grep/guard family, and one narrow browser smoke for the workspace-to-environment flow
- **Fixture / helper cost impact**: moderate. Tests must seed a workspace plus managed environments and reuse existing workspace/member/environment context helpers. The slice should not introduce new default-heavy fixtures, providers, or session helpers beyond what current workspace and managed-environment tests already require.
- **Heavy-family visibility / justification**: one browser smoke only. No new heavy-governance or broad browser family is justified.
- **Special surface test profile**: standard-native-filament, global-context-shell, monitoring-state-page
- **Standard-native relief or required special coverage**: standard feature coverage is sufficient for provider registration, tenancy switch, route removal, and breadcrumb semantics. One browser smoke is required because the cutover changes the live operator entry flow across chooser, dashboard, and operations surfaces.
- **Reviewer handoff**: reviewers must verify that `AdminPanelProvider` becomes the only operator panel, any provider-registration change remains in `apps/platform/bootstrap/providers.php`, `TenantPanelProvider` and `/admin/t` cease to own public operator routing, `ChooseTenant` and `WorkspaceRedirectResolver` stop emitting `panel: 'tenant'` destinations, `OperationRunLinks` and related navigation open the workspace operations hub with explicit environment filters, `TenantPageCategory` and the two middleware seams no longer treat `/admin/t` or `/admin/tenants/{environment}` as active route languages, `WorkspaceOverview` and `TenantDashboard` are reused rather than replaced, `WorkspaceResource` and `TenantResource` keep valid view/edit search destinations or disable search if that contract cannot be kept, destructive actions touched by the route move still require confirmation and server authorization, Livewire remains v4, and no new asset registration/deploy step appears.
- **Budget / baseline / trend impact**: moderate feature-local increase only
- **Escalation needed**: none
- **Active feature PR close-out entry**: Guardrail
- **Planned validation commands**:
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Feature/Workspace/WorkspaceFilamentTenancyCutoverTest.php tests/Feature/ManagedEnvironment/WorkspaceFirstEnvironmentRoutingTest.php tests/Feature/Monitoring/WorkspaceOperationsEnvironmentContextTest.php tests/Feature/Navigation/WorkspaceEnvironmentBreadcrumbsTest.php tests/Feature/Guards/LegacyAdminTenantRouteRemovalGuardTest.php)`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Browser/Spec280WorkspaceTenancyEnvironmentRoutingSmokeTest.php)`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail bin pint --dirty --format agent)`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && rg -n --fixed-strings '/admin/t/' "$REPO_ROOT/apps/platform/app" "$REPO_ROOT/apps/platform/tests" "$REPO_ROOT/apps/platform/routes" "$REPO_ROOT/apps/platform/bootstrap"`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && rg -n --fixed-strings '/admin/tenants/' "$REPO_ROOT/apps/platform/app" "$REPO_ROOT/apps/platform/tests" "$REPO_ROOT/apps/platform/routes" "$REPO_ROOT/apps/platform/bootstrap"`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && rg -n --fixed-strings '/admin/w/' "$REPO_ROOT/apps/platform/app" "$REPO_ROOT/apps/platform/tests" "$REPO_ROOT/apps/platform/routes" "$REPO_ROOT/apps/platform/bootstrap"`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && rg -n --fixed-strings '/admin/operations' "$REPO_ROOT/apps/platform/app" "$REPO_ROOT/apps/platform/tests" "$REPO_ROOT/apps/platform/routes" "$REPO_ROOT/apps/platform/bootstrap"`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && rg -n --fixed-strings "panel: 'tenant'" "$REPO_ROOT/apps/platform/app" "$REPO_ROOT/apps/platform/tests" "$REPO_ROOT/apps/platform/routes" "$REPO_ROOT/apps/platform/bootstrap"`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && rg -n --fixed-strings 'TenantPanelProvider::class' "$REPO_ROOT/apps/platform/bootstrap/providers.php"`

## Scope Boundaries *(required for this slice)*

### In Scope

- make `Workspace` the only Filament tenant for the operator admin runtime
- collapse the operator-facing `/admin/t` panel into the existing `/admin` admin panel
- remove the public `/admin/t/{environment}` route family with no compatibility alias
- remove the public `/admin/tenants/{environment}/required-permissions` family in favor of the workspace-first environment route family
- introduce the canonical workspace-first environment route family rooted at `/admin/workspaces/{workspace}/environments/{environment}`
- reuse `WorkspaceOverview` as the workspace dashboard and `TenantDashboard` as the managed-environment dashboard under the new route ownership
- make `/admin/workspaces/{workspace}/operations` the canonical operations route and thread environment pages into it through explicit filters and back-navigation context
- retarget chooser flow, middleware, route categorization, deep-link builders, breadcrumbs, and page-level context signals to the new route contract
- ensure touched globally searchable resources preserve a valid view/edit destination or are disabled from global search in the same slice

### Non-Goals

- provider connection, provider scope, or Microsoft profile extraction owned by Spec `281`
- governance artifact retargeting to `ManagedEnvironment` owned by Spec `282`
- provider capability registry or provider-neutral artifact taxonomy owned by Specs `283` and `284`
- workspace-first RBAC redesign or capability-family changes owned by Spec `285`
- UI copy, IA, and localization neutralization beyond the route/breadcrumb/context truth needed here, owned by Spec `286`
- cutover quality-gate pack work beyond the routing/tenancy slice proof needed here, owned by Spec `287`
- customer portal, website, package-engine, or guided-operations work
- compatibility routes, aliases, redirects that preserve `/admin/t`, dual panel ownership, dual-read/dual-write route logic, or hidden absorption of later reserved specs

## Assumptions

- Spec `279` already completed the core `ManagedEnvironment` cutover and remains prerequisite context only.
- `AdminPanelProvider` remains the long-lived operator panel under `/admin`, and removing `TenantPanelProvider` from operator routing is acceptable in this pre-production environment.
- The current workspace and environment dashboards already provide the operator signal content needed for the final route contract; `280` relocates and rekeys them instead of redesigning their signal models.
- Internal class names or untouched provider copy may still use `tenant` until later reserved slices, but routing, breadcrumbs, chooser labels, and operator-facing context signals touched by this slice must be workspace/environment truthful.

## Risks

- Hidden `/admin/t` or `panel: 'tenant'` references in builders, widgets, or tests could leave a partial second route language behind after the cutover.
- Operations deep links and back links could lose environment scope or workspace safety if they are retargeted page by page instead of through the shared link builders.
- Collapsing panel ownership could break current context bootstrap if middleware and route categorization are not updated together.
- The slice could sprawl into copy cleanup or RBAC redesign if reviewers do not hold the scope boundary against Specs `285` and `286`.

## Candidate Selection Gate Summary

- **Selected candidate**: `280 - Filament Workspace Tenancy & Environment Routing Cutover`
- **Source locations**:
  - `docs/product/spec-candidates.md` under the reserved workspace-first / provider-neutral cutover pack
  - `docs/product/roadmap.md` under the same reserved cutover ordering and sequencing note
- **Why selected now**: Spec `279` already changed the core managed-target noun, and the verified controlling seam still shows the temporary panel shell in `TenantPanelProvider`. `280` is the second reserved slot and closes that temporary public routing/tenancy contract before later provider and artifact follow-up work begins.
- **Why close alternatives were deferred**:
  - `281` belongs to provider connection/profile extraction, not to route collapse
  - `282` belongs to artifact retargeting, not to public route ownership
  - `283` and `284` belong to provider-neutral packaging follow-through, not to the immediate shell removal
  - `285`, `286`, and `287` are explicit follow-up guardrail slices for RBAC, copy, and no-legacy enforcement
  - the already-existing mid-260/270 packages remain context only and are not the target of this reserved cutover slot
- **Smallest viable implementation slice**: one surviving workspace-tenanted admin panel, one canonical workspace-first environment route family, one canonical workspace operations route family, and one bounded set of chooser/middleware/link/breadcrumb updates with no aliases
- **Documented deviation from raw candidate wording**: `add a workspace dashboard` and `add a managed-environment dashboard` are satisfied by re-homing the existing `WorkspaceOverview` and `TenantDashboard` surfaces under their final route ownership rather than creating new summary systems.

## Completed-Spec Guardrail Result

- `specs/265-decision-register-approval/` already exists with `Status: Ready for implementation` and remains separate context only
- `specs/267-artifact-lifecycle-retention/` already exists with `Status: Ready for implementation` and remains separate context only
- `specs/274-billing-subscription-truth/` already exists with `Status: Ready for implementation` and remains separate context only
- `specs/275-customer-facing-localization-adoption/` already exists with `Status: Draft` and remains separate context only
- `specs/276-support-access-governance/` already exists with `Status: Ready for implementation` and remains a separate prepared package
- `specs/277-stored-reports-surface/` already exists with `Status: Ready for implementation` and remains a separate prepared package
- `specs/278-cross-domain-indicator-audit/` already exists with `Status: Implemented docs-only audit artifact; ready for manual review` and remains separate historical context only
- `specs/279-workspace-managed-environment-core/` already exists with `Status: Ready with approved feature-local exception`, carries implementation-close-out history in `tasks.md`, and is prerequisite context only for this package

## Deferred Adjacent Candidates

- `281 - Provider Connection, Provider Scope & Microsoft Profile Extraction`
- `282 - Governance Artifact Retargeting to ManagedEnvironment`
- `283 - Provider Capability Registry v1`
- `284 - Provider-neutral Artifact Source Taxonomy v1`
- `285 - Workspace-first RBAC & Environment Access Scoping`
- `286 - UI Copy, IA & Localization Neutralization`
- `287 - Cutover Quality Gates & No-Legacy Enforcement`

## User Scenarios & Testing

### User Story 1 - Enter an environment without leaving the workspace admin panel (Priority: P1)

As an operator, I want to choose a workspace and then open one managed environment inside the same admin panel so I never have to cross into a second panel or learn a second route language just to work on that environment.

**Why this priority**: this is the core cutover outcome. If the chooser still lands on `/admin/t`, the temporary shell remains active and the candidate is not complete.

**Independent Test**: select a workspace, open the environment chooser, choose one managed environment, and confirm the destination is the canonical workspace-first environment dashboard rather than `/admin/t`.

**Acceptance Scenarios**:

1. **Given** an operator has selected a workspace, **When** they choose a managed environment, **Then** they land on `/admin/workspaces/{workspace}/environments/{environment}` inside the surviving admin panel.
2. **Given** an operator enters a workspace/environment URL where the environment belongs to a different workspace or is not accessible, **When** the route resolves, **Then** the app returns `404` and reveals no environment data.

---

### User Story 2 - Move from environment work into workspace operations with explicit scope (Priority: P1)

As an operator, I want environment dashboards and environment pages to open the workspace operations hub with an explicit environment filter so operations stay workspace-canonical without losing the narrower environment context I came from.

**Why this priority**: the candidate explicitly requires `/admin/workspaces/{workspace}/operations` to be canonical and environment pages to link into it via filters.

**Independent Test**: open one environment dashboard or environment page, follow its operations link, and confirm the workspace operations hub opens with the correct environment filter and return context.

**Acceptance Scenarios**:

1. **Given** an operator is on one managed-environment dashboard, **When** they open operations, **Then** the destination is `/admin/workspaces/{workspace}/operations` with that environment's filter active.
2. **Given** the operations hub is filtered to one environment, **When** the operator chooses to widen scope, **Then** the route stays workspace-canonical and the environment filter clears explicitly rather than switching panels.

---

### User Story 3 - Read workspace-wide and environment-scoped signals on the correct surfaces (Priority: P2)

As an operator, I want the workspace dashboard to summarize workspace-wide signals and the managed-environment dashboard to summarize one environment's signals so I can decide at the right scope without reconstructing context from mixed pages.

**Why this priority**: the candidate requires both dashboards, and reusing the current builders is the narrowest honest way to deliver them.

**Independent Test**: open a workspace dashboard and an environment dashboard for the same workspace, then verify the workspace view aggregates workspace-wide signals while the environment view remains scoped to one environment and shows the full breadcrumb hierarchy.

**Acceptance Scenarios**:

1. **Given** a workspace has multiple accessible environments, **When** the operator opens the workspace dashboard, **Then** it shows workspace-wide signals and recent operations rather than one environment's dashboard state.
2. **Given** the operator opens one managed-environment dashboard, **When** the page renders, **Then** the breadcrumb and context shell show `Workspace -> Managed Environment -> page` and the signals remain scoped to that one environment.

---

### User Story 4 - Keep search and authorization truthful after the route cutover (Priority: P3)

As an operator, I want globally searchable resources and direct URLs to open truthful destinations or disappear from search altogether so the route migration does not leave broken search results or unsafe hints behind.

**Why this priority**: `WorkspaceResource` and `TenantResource` are already search-eligible by repo truth, and route changes can quietly break that contract if the spec does not pin it down.

**Independent Test**: open touched global-search results and direct URLs for workspace and managed-environment surfaces, then confirm that authorized results open valid destinations and unauthorized paths remain not found.

**Acceptance Scenarios**:

1. **Given** a touched searchable resource remains globally searchable, **When** an operator opens a search result, **Then** the destination is a valid page under the canonical workspace-first route family.
2. **Given** a touched searchable surface cannot preserve a valid view or edit destination after the route move, **When** the cutover ships, **Then** that surface no longer appears in global search.

### Edge Cases

- A direct request to `/admin/t/{environment}`, `/admin/tenants/{environment}/required-permissions`, `/admin/w/{workspace}/managed-tenants`, `/admin/operations`, or `/admin/operations/{run}` must fail as not found rather than redirecting, aliasing, or silently restoring the old path family.
- If a remembered environment belongs to a different workspace than the newly selected workspace, the environment context must clear before the operator is shown any environment-bound page.
- Archived or otherwise non-selectable managed environments must not appear in the workspace-scoped chooser or resolve through the new route family.
- Explicit environment filters on workspace-canonical pages must reject inaccessible environments as `404`; stale remembered filters may be discarded, but explicit hostile hints may not quietly widen scope.
- Any touched globally searchable resource without an intact view/edit destination under the new route contract must be disabled from global search in the same implementation slice.

## Requirements

**Constitution alignment (required):** This slice changes routing, Filament tenancy, chooser flow, navigation, and deep-link behavior. It does not introduce Microsoft Graph calls, a new `OperationRun` lifecycle, or new persistence.

**Constitution alignment (XCUT-001 / PROV-001 / UI-FIL-001):** The slice must reuse the existing shared workspace dashboard, managed-environment dashboard, chooser flow, operations hub, and deep-link builders. No second panel, second route language, or local dashboard framework may appear.

**Constitution alignment (RBAC-UX):** Workspace membership stays the first boundary and managed-environment access stays the second boundary. Non-members remain `404`, in-scope capability denials remain `403`, and any touched destructive actions continue to require confirmation and server-side authorization.

**Constitution alignment (TEST-GOV-001):** Proof stays bounded to feature coverage, one narrow browser smoke, and explicit route/URL guard checks. No heavy-governance family is introduced.

### Functional Requirements

- **FR-001**: The operator admin runtime MUST configure `Workspace` as the only Filament tenant after this cutover.
- **FR-002**: The system MUST stop using `ManagedEnvironment` as a Filament tenant and MUST remove the public `/admin/t/{environment}` route family rather than retaining it as a redirect, alias, or hidden fallback.
- **FR-003**: The surviving `/admin` admin panel MUST own the canonical workspace-first environment route family rooted at `/admin/workspaces/{workspace}/environments/{environment}`.
- **FR-004**: The admin entrypoint `/admin` MUST resolve to workspace selection or the current workspace dashboard only; it MUST NOT remain a second canonical environment dashboard route.
- **FR-005**: The system MUST reuse the existing workspace overview surface as the canonical workspace dashboard and the existing managed-environment dashboard surface as the canonical environment dashboard, rather than creating replacement dashboard systems.
- **FR-006**: The workspace-scoped chooser flow MUST open the new canonical environment dashboard route and MUST clear stale cross-workspace environment context before resolving any environment-bound page.
- **FR-007**: The workspace dashboard, environment dashboard, and all environment-scoped pages touched by this slice MUST present navigation and breadcrumbs in the order `Workspace -> Managed Environment -> domain page`.
- **FR-008**: `/admin/workspaces/{workspace}/operations` MUST be the canonical public operations collection route for the active workspace.
- **FR-009**: Environment dashboards and environment-scoped pages MUST open the workspace operations hub through explicit filter/query context, not through environment-panel ownership.
- **FR-010**: The operations detail route MUST remain inside the workspace route family so run detail does not depend on the removed `/admin/t` shell.
- **FR-011**: Route builders, deep links, and related-navigation helpers that currently emit `panel: 'tenant'`, `/admin/t`, or `/admin/tenants/{environment}` URLs MUST emit only the new canonical workspace-first routes.
- **FR-012**: `TenantPageCategory`, `EnsureWorkspaceSelected`, `EnsureFilamentTenantSelected`, `ResolvesPanelTenantContext`, and related current-context seams MUST treat the workspace-first environment family as the only active environment-bound route language.
- **FR-013**: The slice MUST preserve the current `WorkspaceOverviewBuilder` and `TenantDashboardSummaryBuilder` ownership of workspace-wide and environment-scoped summary signals.
- **FR-014**: Any touched globally searchable resource MUST preserve a valid view or edit destination under the new route contract or be disabled from global search in the same slice.
- **FR-015**: `WorkspaceResource` and `TenantResource` MUST remain globally searchable only if their view/edit destinations stay valid under the cutover route ownership.
- **FR-016**: The slice MUST NOT introduce compatibility routes, aliases, dual-panel ownership, dual route readers, hidden `/admin/t` absorption, or spillover into reserved Specs `281`-`287`.
- **FR-017**: The legacy chooser route `/admin/w/{workspace}/managed-tenants` MUST be removed rather than preserved as a redirect, alias, or hidden fallback reader.
- **FR-018**: The legacy operations routes `/admin/operations` and `/admin/operations/{run}` MUST be removed in favor of `/admin/workspaces/{workspace}/operations` and `/admin/workspaces/{workspace}/operations/{run}` with no redirects, aliases, or dual-route ownership.

### Authorization and Safety Requirements

- **AR-001**: Workspace membership MUST remain the first access boundary for `/admin/workspaces/{workspace}/...` routes.
- **AR-002**: Managed-environment access MUST remain the second access boundary for `/admin/workspaces/{workspace}/environments/{environment}/...` routes.
- **AR-003**: A mismatched `{workspace}` and `{environment}` pair MUST resolve as `404` even if the actor has access to one of them individually.
- **AR-004**: Workspace-canonical pages that accept explicit environment filters MUST reject inaccessible environment hints as `404` and must not silently widen scope.
- **AR-005**: Any destructive action touched while retargeting dashboard or page links MUST remain server-authorized and require confirmation.

### Non-Functional Requirements

- **NFR-001**: Filament remains v5 on Livewire v4.
- **NFR-002**: Provider registration remains in `apps/platform/bootstrap/providers.php`; if `TenantPanelProvider` is removed from operator routing, no registration is moved to `bootstrap/app.php`.
- **NFR-003**: Existing admin theme and asset registration remain unchanged; the slice introduces no new asset pipeline or deployment step beyond the current Filament asset practice.
- **NFR-004**: The cutover must preserve Action Surface Contract, UI-FIL-001, and UX-001 expectations for touched Filament pages/resources without introducing ad hoc Blade/Tailwind design systems or redundant inspect actions.
- **NFR-005**: The route cutover must stay reviewable as one bounded slice and must not silently absorb provider extraction, artifact retargeting, RBAC redesign, copy neutralization, or quality-gate work reserved for later specs.

## 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 |
|---|---|---|---|---|---|---|---|---|---|---|
| Workspace dashboard | `WorkspaceOverview` under `/admin/workspaces/{workspace}` | none | body CTA cards and quick actions only | none | none | existing workspace zero-state CTA family only | none | `N/A` | no new audit behavior | Reuses `WorkspaceOverviewBuilder`; action-surface exemptions remain intact |
| Workspace-scoped environment chooser | chooser surface under `/admin/workspaces/{workspace}/environments` | none | environment card/button opens the environment dashboard | none | none | workspace switch or no-access guidance only | none | `N/A` | no new audit behavior required by this slice | Reuses the existing chooser pattern; selection must not jump into a second panel |
| Managed-environment dashboard | `TenantDashboard` under `/admin/workspaces/{workspace}/environments/{environment}` | `Primary follow-up`, `More`, `Request support`, `Open support diagnostics` | `N/A` | none | none | existing dashboard empty-state behavior only | same as header actions | `N/A` | existing support-request audit behavior only | Action hierarchy and support flows stay intact; route and breadcrumb ownership change only |
| Workspace operations hub | `Monitoring\Operations` under `/admin/workspaces/{workspace}/operations` | `Scope operations`, `Back to ...`, `Show all environments` | clickable row to run detail | none | none | existing operations empty-state only | existing run-viewer contract only | `N/A` | no new audit behavior | Filter and back-link context replace environment-panel routing; no new bulk or destructive actions |

All other environment-scoped resources and diagnostic pages that today live under `panel: 'tenant'` or `/admin/tenants/{environment}` keep their current local action contracts. This slice changes their route ownership and breadcrumb shell only and must not introduce new redundant View actions, placeholder action groups, or new destructive actions.

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

- **Workspace**: the operator's primary admin context and the only Filament tenant after this cutover; owns the canonical workspace dashboard, environment chooser, and workspace operations hub.
- **Managed Environment**: the environment-scoped managed target inside one workspace; owns the canonical environment dashboard route and remains the nested context for environment-scoped pages and explicit environment filters.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: All touched operator entry and drillthrough flows open workspace-first environment URLs, and no operator-visible `/admin/t/` link remains on touched admin surfaces.
- **SC-002**: An operator can go from workspace selection to one managed-environment dashboard and then into the workspace operations hub with preserved scope in three interactions or fewer.
- **SC-003**: All touched environment-scoped pages present breadcrumb/context order `Workspace -> Managed Environment -> page`, and direct wrong-workspace or wrong-environment access reveals no data.
- **SC-004**: Touched globally searchable resources either open a valid destination on first attempt under the new route family or no longer appear in global search.