TenantAtlas/specs/317-legacy-tenant-environment-context-cleanup/spec.md

Feature Specification: Legacy Tenant / Environment Context Cleanup

Feature Branch: 317-legacy-tenant-environment-context-cleanup Created: 2026-05-16 Status: Draft Input: User supplied Spec 317 draft for hard-cut cleanup of legacy Tenant platform-context names, aliases, helpers, routes, UI copy, tests, and current docs after Specs 314-316.

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

• Problem: Specs 314-316 stabilized Workspace hub entry, explicit environment_id filtering, and clear-filter reset behavior, but old Tenant-era platform context names and fallback paths still exist in code, tests, routes, helper APIs, UI copy, and docs.
• Today's failure: Future work can accidentally treat tenant, tenant_id, tenant_scope, managed_environment_id, remembered Tenant state, or Filament::getTenant() as valid Workspace hub Environment context, reintroducing hidden scope mismatch after the runtime lifecycle was fixed.
• User-visible improvement: Operators see Workspace and Environment terminology where the product means Managed Environment, Workspace hubs only accept environment_id as an explicit filter, and provider-boundary Tenant language remains clearly limited to Microsoft/Entra/provider identity.
• Smallest enterprise-capable version: Inventory and classify remaining Tenant occurrences, create an allowlist for provider-boundary usage, remove or rename active platform-context leftovers, add static/runtime/browser guards, and update only current product-truth docs/spec artifacts.
• Explicit non-goals: No UI redesign, no new product feature, no new Environment CTA coverage beyond Specs 315/316, no broad cosmetic DB rename, no compatibility redirects, no dual-param support, no migrations unless repo analysis proves a schema name is active wrong platform-context truth, and no rewriting completed historical specs.
• Permanent complexity imported: Two spec-local cleanup artifacts, one or more guard tests, renamed helpers/classes where repo truth requires it, and browser smoke evidence. No new persisted entity, enum/status family, queue, provider framework, Graph contract, or runtime compatibility layer is introduced.
• Why now: Specs 314-316 intentionally deferred broad naming/alias cleanup to Spec 317. The runtime contract is now stable enough to remove the old mental model without mixing cleanup with filter lifecycle fixes.
• Why not local: The legacy risk crosses navigation, Filament support helpers, Workspace hub pages, provider links, tests, route assumptions, session helpers, UI copy, and docs. A page-local fix would leave future drift paths open.
• Approval class: Cleanup.
• Red flags triggered: Many surfaces touched and static guard coverage. Defense: this removes existing dangerous compatibility/naming residue instead of adding a framework; provider-boundary Tenant terminology is explicitly preserved through an allowlist.
• Score: Value: 2 | Urgency: 2 | Scope: 2 | Complexity: 1 | Product proximity: 2 | Reuse: 2 | Total: 11/12
• Decision: approve.

Spec Scope Fields (mandatory)

• Scope: canonical-view.
• Primary Routes: Workspace hub routes and Environment-owned routes under the admin panel, including Workspace Overview, Environment Dashboard, Operations, Governance Inbox, Decision Register, Finding Exceptions Queue, Provider Connections, Evidence, Reviews, Customer Reviews, Provider Readiness, and Required Permissions.
• Data Ownership: No new data ownership model. Workspace remains the primary platform context. Managed Environment remains the secondary operational context. Provider Tenant remains provider-boundary identity only. Existing managed_environment_id DB columns remain unless implementation proves a schema name is active wrong platform-context truth.
• RBAC: Existing workspace membership, environment entitlement, page/resource policies, capabilities, and deny-as-not-found behavior remain authoritative. Cleanup must not weaken RBAC or use UI visibility as authorization.

For canonical-view specs:

• Default filter behavior when tenant-context is active: Workspace hubs must remain workspace-wide unless a valid canonical environment_id query parameter is present. Legacy Tenant query params, Filament tenant state, remembered Tenant/Environment state, and table filters must not create Workspace hub Environment context.
• Explicit entitlement checks preventing cross-tenant leakage: Any valid environment_id filter must resolve a ManagedEnvironment inside the selected Workspace for the current actor. Provider external tenant IDs, Entra tenant IDs, slugs, remembered state, Filament::getTenant(), and old tenant aliases are not valid filter sources.

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes.
• Interaction class(es): navigation context, URL/query contracts, Environment filter chips, helper APIs, route helpers, UI copy, session/table state guardrails, static guard tests, docs/product terminology.
• Systems touched: WorkspaceHubRegistry, WorkspaceHubEnvironmentFilter, WorkspaceHubFilterStateResetter, WorkspaceSidebarNavigation, ManagedEnvironmentLinks, OperationRunLinks, WorkspaceContext, OperateHubShell, CanonicalAdminTenantFilterState, TenantPageCategory, WorkspaceScopedTenantRoutes, Filament pages/resources/clusters, active Blade views, admin routes, tests, and current docs/spec truth.
• Existing pattern(s) to extend: Specs 314-316 Workspace hub registry/filter/reset contracts, existing Filament/Livewire page tests, existing browser smoke tests for Workspace hub context, existing route guards, and existing guard-test conventions under apps/platform/tests/Feature/Guards.
• Shared contract / presenter / builder / renderer to reuse: Reuse current Workspace hub registry/filter/reset helpers where they remain correctly named and scoped. Rename or replace Tenant-named helpers/classes only when they model Environment or Workspace hub platform context. Do not keep deprecated aliases.
• Why the existing shared path is sufficient or insufficient: The runtime path is now sufficient for canonical behavior, but old names and alias entry points remain structurally unsafe. Cleanup must remove those old seams rather than adding another resolver layer.
• Allowed deviation and why: Provider-boundary code may keep Tenant terminology where it clearly means Microsoft/Entra/provider identity. Historical completed specs may remain unchanged as history unless they are used as current product truth.
• Consistency impact: Workspace, Environment, and Provider Tenant vocabulary must align across URL keys, helper names, tests, UI labels, docs, and browser-visible state.
• Review focus: Verify no legacy alias support remains for Workspace hub Environment filtering, no deprecated helper aliases survive, provider-boundary Tenant terms are allowlisted, and completed historical specs are not rewritten.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: no start/completion behavior. Link helpers may be inspected or renamed only where old Tenant context naming leaks into Workspace hub URLs.
• Shared OperationRun UX contract/layer reused: Existing OperationRunLinks remains the relevant link helper if touched.
• Delegated start/completion UX behaviors: N/A.
• Local surface-owned behavior that remains: Existing operation start/completion/notification/progress behavior remains unchanged.
• Queued DB-notification policy: N/A.
• Terminal notification path: N/A.
• Exception required?: none.

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: yes.
• Boundary classification: mixed. Platform-core Workspace/Environment context must be cleaned. Provider-owned Microsoft/Entra Tenant identity must be preserved.
• Seams affected: query keys, route/helper names, Filament tenant usage in Workspace hubs, provider connection context links, provider identity labels, tests, UI copy, docs/spec current truth, and static guard allowlists.
• Neutral platform terms preserved or introduced: Workspace, Managed Environment, Environment, Provider Connection, Provider Scope, Workspace hub, Environment filter, All environments, environment_id.
• Provider-specific semantics retained and why: provider_tenant_id, external_tenant_id, microsoft_tenant_id, entra_tenant_id, azure_tenant_id, tenantId in Microsoft payloads, OAuth authority tenant segments, and Microsoft/Entra Tenant display copy remain valid at provider boundaries.
• Why this does not deepen provider coupling accidentally: The allowlist limits Tenant terminology to provider identity and historical archived docs, while platform-context code uses Workspace/Environment terms.
• Follow-up path: Spec 318 adds durable browser regression/no-drift coverage. It must not be implemented inside Spec 317.

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
Workspace Overview	yes	Existing Filament/Blade surface	navigation, scope copy	visible copy, generated links	no	Must not say Tenant when it means Environment
Environment Dashboard	yes	Existing Filament page/widgets	Environment CTAs, provider readiness	visible copy, generated links	no	Provider-specific Tenant copy allowed only in provider detail context
Operations	yes	Existing Filament page/table	Workspace hub	URL/query, page state, copy, tests	no	Must use only environment_id for Environment filter
Governance Inbox	yes	Existing Filament page/list	governance queue	URL/query, page state, copy, tests	no	Remove old Tenant aliases/state language
Decision Register	yes	Existing Filament page/list	decision register	URL/query, page state, copy, tests	no	Clean Workspace hub remains valid
Finding Exceptions Queue	yes	Existing Filament page/table	exception queue	URL/query, table state, copy, tests	no	Old tenant state cannot be valid Environment filter
Provider Connections	yes	Existing Filament resource/table	provider registry	provider identity labels, Environment filter links	no	Distinguish Environment from Provider Tenant ID
Evidence	yes	Existing Filament page/resource	evidence viewer	copy, filters, links, tests	no	Workspace hub vocabulary must be clean
Reviews / Customer Reviews	yes	Existing Filament pages/resources	review workspace	copy, filters, links, tests	no	tenantPrefilterUrl() is disallowed
Provider Readiness / Required Permissions	yes	Existing Environment/provider surfaces	provider readiness	copy, labels	no	Microsoft Tenant wording allowed only when provider-owned
Historical specs/docs	no active UI	Spec/doc artifacts	current truth vs history	documentation	no	Do not rewrite completed history unless it states current product truth

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

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 hub with optional Environment filter	Secondary Context	Decide whether listed rows are workspace-wide or intentionally narrowed to one Environment	Workspace context, optional Environment chip, clean copy, canonical URL	Existing row/detail diagnostics	Scope truth is prerequisite for every hub decision	Completes 314-316 lifecycle by removing legacy context drift	Removes need to infer whether Tenant means Environment or provider identity
Provider detail/readiness surfaces	Secondary Context	Understand provider identity without confusing it with platform Environment context	Environment scope plus provider-specific Tenant ID where relevant	Provider raw diagnostics where already available	Provider Tenant is evidence, not platform context	Keeps provider boundary explicit	Prevents wrong operational scope assumptions

Audience-Aware Disclosure (mandatory when operator-facing surfaces are changed)

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/Environment UI copy	operator-MSP, support-platform, customer-read-only where existing surfaces apply	Workspace and Environment terms only for platform context	Existing diagnostics	Existing support/raw sections	Inspect rows or clear/apply Environment filter	Raw provider IDs unless already shown by provider detail	Tenant appears only where provider-owned and labelled as Microsoft/Entra/provider

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

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 hubs	List / Table / Bulk	Existing hub/list/queue/register	Inspect item or clear Environment filter	Existing inspect pattern	existing	Existing placement	Existing placement; no destructive changes	existing admin hub routes	existing	Workspace-wide or Environment chip	Existing page nouns	Whether the hub is workspace-wide or Environment-filtered	none
Provider readiness/details	Detail / Related Context	Provider diagnostics	Verify provider connection/readiness	Existing detail pattern	existing	Existing placement	Existing placement; no destructive changes	existing	existing	Workspace + Environment + provider identity	Provider Connection / Required Permissions	Provider Tenant terms are provider-boundary only	none

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

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
Active Workspace hub surfaces	TenantPilot operator	Trust the current data scope before inspecting or acting	Existing list/table/page	Am I looking at all Workspace data or one Environment?	Workspace label, optional Environment filter, clean Environment terminology	Existing page diagnostics	Existing page-specific dimensions only	TenantPilot navigation/filter state only	Inspect rows, clear/apply filter	None added or changed

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no.
• New persisted entity/table/artifact?: no database/persistent domain entity. Two spec-local implementation artifacts are required: legacy-inventory.md and tenant-usage-allowlist.md.
• New abstraction?: no new generic framework planned. Existing Tenant-named helpers/classes may be renamed or replaced with narrower responsibility names if repo analysis confirms they model platform Environment/Workspace context.
• New enum/state/reason family?: no.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: Legacy Tenant platform-context language can mislead operators and future code into treating Environment filters as hidden Tenant context.
• Existing structure is insufficient because: Specs 314-316 fixed runtime behavior but intentionally left old names and aliases for this cleanup. Leaving them in place preserves a known reintroduction path.
• Narrowest correct implementation: Inventory, allowlist, remove/rename/quarantine confirmed platform-context leftovers, add guard tests, update current docs/copy, and stop before durable browser infrastructure.
• Ownership cost: Static guard maintenance, explicit provider-boundary allowlist updates, review attention for broad rename diffs, and focused browser smoke.
• Alternative intentionally rejected: Keeping deprecated aliases or compatibility readers would violate the hard cutover policy; broad DB renames for provider-boundary fields are unnecessary churn.
• Release truth: Current-release cleanup before production data exists.

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, dual-read behavior, compatibility redirects, and compatibility-specific tests are out of scope. Canonical replacement is required. No old URL or query alias support should remain for platform Workspace hub Environment filtering.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Feature/Unit guard tests for static legacy detection, route/link/query contracts, helper renames, and Workspace hub alias rejection; Browser smoke for active UI copy and generated links on critical surfaces.
• Validation lane(s): fast-feedback for static/unit/feature guards, confidence for Filament/Livewire page/resource behavior, browser for focused active UI verification.
• Why this classification and these lanes are sufficient: The risk is structural drift plus visible UI terminology. Static/feature tests prevent reintroduction; browser smoke proves active pages no longer display platform Tenant context.
• New or expanded test families: Spec 317 legacy platform-context guard tests, Workspace hub legacy query alias tests, route guard tests, helper/API rename tests, UI copy guard, and focused browser smoke.
• Fixture / helper cost impact: Existing Workspace, ManagedEnvironment, membership/capability, provider connection, evidence/review/finding/operation factories may be reused. Static guards should avoid broad database setup. Any full-context helpers must stay opt-in.
• Heavy-family visibility / justification: Browser coverage is explicit and limited to required surfaces because UI copy and generated links are browser-visible truth. Durable no-drift coverage remains Spec 318.
• Special surface test profile: global-context-shell, standard-native-filament, provider-boundary-copy.
• Standard-native relief or required special coverage: Existing native Filament tests cover page/resource behavior; browser smoke covers rendered vocabulary and link/query output.
• Reviewer handoff: Reviewers must inspect legacy-inventory.md, tenant-usage-allowlist.md, static guard allowlist entries, renamed helper/class list, removed legacy query handlers, and browser results.
• Budget / baseline / trend impact: Static guards may scan many files but should remain bounded to relevant app/resources/routes/tests/current docs paths. Any material runtime cost must be documented.
• Escalation needed: follow-up-spec only for durable browser infrastructure (Spec 318) or if implementation discovers a schema rename too broad for this cleanup.
• Active feature PR close-out entry: Guardrail and Smoke Coverage.
• Planned validation commands: Focused Pest filters for Spec 317 guard/contract tests, existing Spec 314/315/316 regression tests, cd apps/platform && ./vendor/bin/sail artisan test if scope warrants, browser smoke for required pages, cd apps/platform && ./vendor/bin/sail pint --test or equivalent Pint check for touched PHP files, and git diff --check.

User Scenarios & Testing (mandatory)

User Story 1 - Inventory and classify legacy Tenant usage before cleanup (Priority: P1)

An implementer inventories remaining Tenant terminology and classifies each relevant occurrence before broad cleanup starts.

Why this priority: Provider-boundary Tenant terminology must be preserved, while platform-context Tenant terminology must be removed. A naive grep cleanup would break valid provider identity code.

Independent Test: Review legacy-inventory.md and tenant-usage-allowlist.md; every relevant occurrence is classified with an action and no high-risk ambiguous occurrence remains.

Acceptance Scenarios:

1. Given a Tenant occurrence is found in a provider identity class, When the inventory is reviewed, Then it is classified as provider-boundary or renamed only if it leaks into platform context.
2. Given a Tenant occurrence is found in a Workspace hub helper, When the inventory is reviewed, Then it is classified as remove, rename, or quarantine with a concrete action.

---

User Story 2 - Workspace hubs accept only canonical Environment filters (Priority: P1)

An operator or stale URL attempts to use legacy Tenant query aliases on Workspace hubs. The page must ignore or normalize them without applying an Environment filter.

Why this priority: This prevents the old hidden Tenant context model from returning after Specs 314-316.

Independent Test: Open critical Workspace hubs with tenant, tenant_id, managed_environment_id, tenant_scope, environment, and tableFilters without environment_id; assert no Environment chip appears and no Environment filter is applied. Open with valid environment_id; assert canonical filtering still works.

Acceptance Scenarios:

1. Given Operations is opened with ?tenant=123, When the page renders, Then no Environment chip is shown and rows are not scoped by that parameter.
2. Given Provider Connections is opened with valid ?environment_id={Environment A}, When the page renders, Then the existing Spec 315/316 visible filter behavior still works.

---

User Story 3 - Legacy helper/class names are removed or renamed without aliases (Priority: P1)

A developer working on Workspace/Environment context should see current domain names and no deprecated Tenant aliases for Environment behavior.

Why this priority: Old helper names are the main reintroduction path for legacy context.

Independent Test: Static guard/tests assert old helper names such as tenantPrefilterUrl, platform-context TenantPageCategory, WorkspaceScopedTenantRoutes, and CanonicalAdminTenantFilterState are gone, renamed, or explicitly quarantined with reason.

Acceptance Scenarios:

1. Given code tries to call tenantPrefilterUrl(), When tests/static guards run, Then the call is rejected and the canonical Environment helper is used instead.
2. Given CanonicalAdminTenantFilterState remains after implementation, When the inventory is reviewed, Then it is quarantined with a bounded reason or renamed to match current responsibility.

---

User Story 4 - Active UI uses Environment, not Tenant, for platform context (Priority: P1)

An operator uses Workspace and Environment surfaces without seeing Tenant language where the product means Managed Environment.

Why this priority: Visible vocabulary is part of scope safety and enterprise trust.

Independent Test: Browser or rendered-view checks cover Workspace Overview, Environment Dashboard, Operations, Governance Inbox, Decision Register, Finding Exceptions Queue, Provider Connections, Evidence, Reviews, Customer Reviews, Provider Readiness, and Required Permissions.

Acceptance Scenarios:

1. Given Workspace Overview lists active Environment-related navigation, When the page renders, Then the copy says Environment/Managed Environment and not Tenant unless provider-boundary context is explicit.
2. Given Provider Connection details show a Microsoft tenant ID, When the page renders, Then the label makes it clear that it is a provider/Microsoft Tenant value, not TenantPilot platform context.

---

User Story 5 - Routes, tests, and current docs prevent legacy context drift (Priority: P2)

Developers and reviewers should have guardrails that block /admin/t, Tenant Panel assumptions, and stale docs/spec candidate language from becoming current truth again.

Why this priority: Cleanup must be durable enough for future specs, while full browser no-drift infrastructure remains Spec 318.

Independent Test: Route guard confirms no active /admin/t panel routes or TenantPanelProvider registration; docs/spec updates remove current product-truth Tenant platform context; historical specs are left untouched or marked historical.

Acceptance Scenarios:

1. Given admin routes are listed, When the route guard runs, Then no active /admin/t route is present.
2. Given docs/product/spec-candidates.md is reviewed, When current product truth is read, Then it no longer describes Tenant as TenantPilot platform context for Workspace hubs.

Requirements (mandatory)

Functional Requirements

• FR-001: Implementation MUST create and maintain specs/317-legacy-tenant-environment-context-cleanup/legacy-inventory.md before broad cleanup edits.
• FR-002: legacy-inventory.md MUST classify relevant Tenant occurrences as remove, rename_to_environment, rename_to_provider_tenant, allowed_provider_boundary, allowed_historical_archived_doc, dead_code_candidate, needs_product_decision, or out_of_scope.
• FR-003: Implementation MUST create and maintain specs/317-legacy-tenant-environment-context-cleanup/tenant-usage-allowlist.md.
• FR-004: The allowlist MUST explicitly preserve provider-boundary Tenant usage such as Microsoft tenant, Entra tenant, provider tenant ID, external tenant ID, Graph tenant ID, OAuth tenant segment, and tenantId in provider payloads.
• FR-005: Workspace hubs MUST NOT treat tenant, tenant_id, managed_environment_id, tenant_scope, environment, or tableFilters as valid Environment filter sources.
• FR-006: Workspace hubs MUST accept only environment_id for explicit Environment filtering.
• FR-007: Generated Workspace hub links MUST NOT emit tenant, tenant_id, managed_environment_id, tenant_scope, environment, or tableFilters as Environment filter keys.
• FR-008: Environment-owned CTAs to Workspace hubs MUST continue to emit canonical environment_id where Spec 315/316 already support it.
• FR-009: tenantPrefilterUrl() MUST be removed or renamed to an Environment-named helper with no deprecated alias.
• FR-010: Platform-context helper properties and variables such as tenantId, tenantLabel, tenantFilter, and tenantScope MUST be renamed when they represent Managed Environment behavior.
• FR-011: TenantPageCategory, WorkspaceScopedTenantRoutes, CanonicalAdminTenantFilterState, EnsureFilamentTenantSelected, and any TenantPanelProvider reference MUST be renamed, removed, or explicitly quarantined based on actual responsibility.
• FR-012: No deprecated helper/class aliases may remain for compatibility.
• FR-013: Workspace hubs MUST NOT use Filament::getTenant() or getTenant() as data scope, default Environment, authorization fallback, shell context, or URL parameter source.
• FR-014: Workspace hubs MUST NOT use lastTenantId, remembered Tenant state, or session Tenant state as data scope, authorization scope, Environment fallback, or URL source.
• FR-015: lastEnvironmentId, if it remains, MUST be named and used only as switcher/convenience memory and MUST NOT affect Workspace hub filters, URLs, data queries, authorization, or shell context.
• FR-016: Active platform UI MUST use Workspace/Environment terminology when it means TenantPilot platform context.
• FR-017: Provider-specific UI MAY say Microsoft Tenant, Entra Tenant, or Provider Tenant ID only when clearly provider-owned.
• FR-018: No active /admin/t route or Tenant Panel provider registration may remain.
• FR-019: Workspace hub clean URLs MUST remain workspace-scoped and must not require Tenant route context.
• FR-020: Static guard tests MUST distinguish allowed provider-boundary Tenant usage from disallowed platform-context Tenant usage.
• FR-021: Guard tests MUST fail if legacy Tenant query aliases become valid Workspace hub Environment filters again.
• FR-022: Guard tests MUST fail if Filament::getTenant() or remembered Tenant fallback is used for Workspace hub scope.
• FR-023: Route guard tests MUST fail if active /admin/t routes or TenantPanelProvider registration return.
• FR-024: UI copy tests or browser smoke MUST cover required active Workspace/Environment surfaces.
• FR-025: Current docs/spec candidate artifacts MUST use Workspace/Environment terminology for current product truth and must not describe Tenant as platform context.
• FR-026: Completed historical specs MUST NOT be rewritten unless they are actively used as current product truth; otherwise leave them as history or mark the current-truth replacement.
• FR-027: No migration may be added unless repo analysis proves a schema name is actively part of the wrong platform-context contract and the rename is safe, bounded, and tested.
• FR-028: Provider-boundary columns such as provider_tenant_id, external_tenant_id, microsoft_tenant_id, entra_tenant_id, and provider payload tenantId MUST NOT be renamed for cosmetic reasons.
• FR-029: Existing Specs 314, 315, and 316 regression behavior MUST remain green.
• FR-030: No backwards compatibility layer, compatibility redirect, alias reader, dual-param support, or transitional adapter may be introduced.

Non-Functional Requirements

• NFR-001: Cleanup must be direct and bounded; do not introduce a generic context framework.
• NFR-002: Static scanning must be maintainable through an allowlist and must not block valid provider-boundary Tenant terminology.
• NFR-003: Browser verification must be focused on required active surfaces and must not implement Spec 318's durable no-drift suite.
• NFR-004: All Runtime changes must preserve Laravel 12, Filament v5.2.1, Livewire v4.1.4, and Pest v4 conventions.
• NFR-005: No Graph calls, queue semantics, destructive actions, or audit behavior may change except where a renamed helper/link affects existing tests.

Key Entities / Concepts

• Workspace: Primary TenantPilot platform context and data boundary.
• Managed Environment / Environment: Secondary operational context inside a Workspace and explicit filter target through environment_id.
• Provider Tenant: External provider identity, such as Microsoft/Entra/Graph tenant. Valid only at provider boundaries.
• Workspace Hub: Workspace-owned/canonical admin surface that may optionally accept an explicit Environment filter.
• Legacy Tenant Platform Context: Disallowed old model where Tenant acts as Workspace hub, shell, sidebar, Environment filter, or TenantPilot data-boundary context.

Edge Cases

• Provider Connection pages that display provider tenant IDs must keep provider-specific labels while not using those IDs as Workspace hub filters.
• Historical tests/specs may contain Tenant language as preserved history; guard allowlists must not require rewriting completed implementation evidence.
• managed_environment_id is a valid internal DB relationship in many models but not a public Workspace hub CTA filter key.
• Filament::getTenant() may be valid on truly Environment-scoped pages, but not as Workspace hub scope.
• Some legacy names may remain quarantined for a bounded reason if renaming would exceed this spec; each quarantine requires inventory entry, reason, risk, and follow-up.

Out of Scope

• UI redesign or new product workflows.
• Adding Environment CTA support to pages excluded from Specs 315/316.
• Retrofitting Audit Log, Alerts, Reports, or Support Requests unless required by cleanup discovery.
• Removing provider-specific Microsoft/Entra Tenant concepts.
• Broad database renames for cosmetic reasons.
• Compatibility redirects or legacy URL support.
• Durable browser regression infrastructure owned by Spec 318.
• Rewriting completed specs as if they were current preparation artifacts.

Success Criteria (mandatory)

• SC-001: legacy-inventory.md exists and classifies all relevant high-risk Tenant occurrences.
• SC-002: tenant-usage-allowlist.md exists and documents provider-boundary Tenant usage.
• SC-003: Critical Workspace hubs ignore legacy Tenant aliases and accept only environment_id as explicit Environment filter.
• SC-004: Active UI surfaces use Environment terminology where they mean Managed Environment.
• SC-005: Provider-boundary Tenant wording remains only where clearly provider-owned.
• SC-006: No active /admin/t route or TenantPanelProvider registration remains.
• SC-007: Old helper/class aliases are removed, renamed, or explicitly quarantined without compatibility aliases.
• SC-008: Static guard, route guard, helper/API guard, UI copy guard, and Spec 314-316 regression tests pass.
• SC-009: Focused browser verification confirms no active platform UI says Tenant when it means Environment, and generated links do not emit legacy query aliases.
• SC-010: No backwards compatibility layer was introduced and no provider-boundary Tenant concepts were incorrectly removed.

Assumptions

• There is no production data or external contract requiring legacy Tenant platform-context compatibility.
• Specs 313-316 are completed historical context and should not be rewritten.
• The default expectation is no migrations.
• The user-provided Spec 317 is the selected candidate and supersedes roadmap numbering notes that mention a different Spec 317 topic.
• Implementation may discover a small number of names that need quarantine rather than immediate rename; each requires explicit documentation.

Open Questions

None blocking preparation. Any needs_product_decision inventory classification during implementation must stop that specific cleanup item or move it to a follow-up instead of guessing.