TenantAtlas/specs/298-managed-environment-terminology-copy-cleanup/plan.md

Implementation Plan: Managed Environment Terminology & Copy Cleanup

Branch: 298-managed-environment-terminology-copy-cleanup | Date: 2026-05-13 | Spec: spec.md
Input: Feature specification from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/298-managed-environment-terminology-copy-cleanup/spec.md

Summary

Spec 298 is a bounded post-cutover terminology and navigation cleanup. The implementation will audit remaining tenant-first copy, update active visible UI/localization/test vocabulary to Workspace and Managed Environment / Environment terminology, clarify forbidden legacy guard literals, update affected browser-smoke selectors, gate environment-owned navigation by the current route/surface, and document allowed provider/internal/historical references. It must not rename the database/model layer or reintroduce legacy tenant routes, panels, helper aliases, or compatibility surfaces.

This plan is preparation only. It does not implement application code.

Technical Context

Language/Version: PHP 8.4.15
Primary Dependencies: Laravel 12.52.0, Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, Laravel Sail 1.52.0
Storage: PostgreSQL through Laravel/Sail for tests; no schema or persistence change planned
Testing: Pest via ./vendor/bin/sail artisan test --compact; targeted Browser tests only if visible smoke anchors are touched
Validation Lanes: Feature/Guards, Feature/Localization, Feature/Workspaces, Feature/ProviderConnections, Feature/RequiredPermissions, Feature/Filament, affected Feature areas, targeted Browser smoke
Target Platform: Laravel Sail local runtime and Gitea-compatible CI runners
Project Type: Laravel web application under apps/platform
Performance Goals: Keep scans and tests focused; no full-suite repair and no browser timeout inflation
Constraints: no /admin/t... restoration, no /admin/tenants... restoration, no TenantPanelProvider, no setTenantPanelContext() alias, no DB/model rename, no new localization architecture, no broad UI polish Scale/Scope: Copy, localization values, test wording, guard descriptions, browser selectors, route-scope-first sidebar gating, and spec-local audit only

Initial Repo Baseline

Preparation scans on 2026-05-13 found:

• Current branch before Spec Kit execution was platform-dev; Spec Kit switched to 298-managed-environment-terminology-copy-cleanup.
• Working tree was clean before creating the package.
• No existing specs/298-* package or matching branch was present.
• Related specs:
  • specs/297-managed-environment-canonical-route-cutover/ is dependency/context and carries completed-task signals; do not rewrite it.
  • specs/286-ui-copy-ia-localization-neutralization/ is adjacent context and carries completed/review signals; do not rewrite it.
  • specs/288-quality-gates-no-legacy-enforcement/ is adjacent guard context and includes explicit legacy guard concepts; do not weaken it.
• Read-only source scan over apps/platform/app, apps/platform/resources, and apps/platform/routes returned no hits for active old route/generator patterns:

rg "filament\.admin\.resources\.tenants|/admin/tenants|/admin/t/|TenantResource::getUrl|TenantDashboard::getUrl|TenantRequiredPermissions::getUrl|setTenantPanelContext|panel:\s*'tenant'|panel:\s*\"tenant\"" apps/platform/app apps/platform/resources apps/platform/routes --glob '!vendor' --glob '!node_modules'

• Read-only copy/test scan found representative hits in:
  • apps/platform/lang/en/localization.php
  • apps/platform/lang/de/localization.php
  • apps/platform/resources/views/filament/pages/monitoring/finding-exceptions-queue.blade.php
  • apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php
  • apps/platform/resources/views/filament/pages/tenant-required-permissions.blade.php
  • apps/platform/app/Services/Tenants/TenantActionPolicySurface.php
  • apps/platform/app/Support/Baselines/BaselineCompareStats.php
  • apps/platform/app/Support/Ui/GovernanceActions/GovernanceActionCatalog.php
  • apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php
  • apps/platform/app/Filament/Pages/Findings/MyFindingsInbox.php
  • apps/platform/app/Filament/Resources/BackupScheduleResource.php
  • apps/platform/app/Filament/Resources/BaselineProfileResource/RelationManagers/BaselineTenantAssignmentsRelationManager.php
  • guard/localization/findings tests
• apps/platform/tests/Pest.php already contains setAdminEnvironmentContext().
• apps/platform/tests/Feature/Guards/Spec288NoLegacyRouteAndHelperGuardTest.php still contains setTenantPanelContext regex literals as forbidden-pattern checks; implementation must make the guard wording unambiguously legacy-forbidden.

The implementation must refresh /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/298-managed-environment-terminology-copy-cleanup/terminology-audit.md with full required scans before application edits.

UI / Surface Guardrail Plan

• Guardrail scope: changed visible copy and validation wording on existing surfaces; no new product workflow.
• Native vs custom classification summary: Existing native Filament/Laravel/Blade surfaces; no custom UI redesign.
• Shared-family relevance: shell/context labels, dashboard copy, action labels, modal headings, empty states, guard tests, browser anchors, localization values.
• State layers in scope: copy/value, page/action label, view text, test helper wording, guard regex descriptions, browser selectors.
• Audience modes in scope: operator-MSP and support-platform. Customer-facing localization may be touched only where targeted strings are already active and in scope.
• Decision/diagnostic/raw hierarchy plan: Preserve existing hierarchy. Replace wrong tenant-first terms; do not move diagnostic/raw content.
• Raw/support gating plan: unchanged.
• One-primary-action / duplicate-truth control: Do not add new actions. If labels change, keep the existing action hierarchy and only update the object noun.
• Handling modes by drift class or surface: fix active UI/test terminology; document provider/internal/historical/regression-guard exceptions; defer DB/model rename and broad historical cleanup.
• Repository-signal treatment: review-mandatory for final scans, guard literals, browser selector changes, localization key/value decisions, and destructive action label changes.
• Special surface test profiles: standard-native-filament, global-context-shell, browser-smoke if browser files change.
• Required tests or manual smoke: focused Feature tests for touched areas; targeted Browser smokes when browser anchors change.
• Exception path and spread control: Every final tenant-related hit must be in terminology-audit.md with category and reason.
• Active feature PR close-out entry: Guardrail / Terminology Cleanup / Smoke Coverage.

Shared Pattern & System Fit

• Cross-cutting feature marker: yes.
• Systems touched: localization arrays, Filament page/resource labels, support copy emitters, Blade views, tests, browser smokes, and guard tests.
• Shared abstractions reused: existing localization keys where safe, ManagedEnvironmentLinks, setAdminEnvironmentContext(), existing data-testid/browser patterns, existing guard-test pattern.
• New abstraction introduced? why?: one small NavigationScope helper is allowed for route-scope-first sidebar gating. It centralizes the existing TenantPageCategory decision and avoids per-resource ad hoc checks against stale Filament::getTenant() state.
• Why the existing abstraction was sufficient or insufficient: Canonical route/helper truth already exists. The remaining issue is copy/test terminology, which can be fixed in place.
• Bounded deviation / spread control: Technical class/model/table names and provider-specific Microsoft/Entra tenant wording remain only with audit documentation.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: no new start/completion/link behavior; possible label/copy updates only.
• Central contract reused: existing OperationRun UX/link contracts if touched.
• Delegated UX behaviors: unchanged.
• Surface-owned behavior kept local: copy only.
• Queued DB-notification policy: N/A.
• Terminal notification path: unchanged.
• Exception path: none.

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: yes, vocabulary only.
• Provider-owned seams: Microsoft tenant ID, Entra tenant ID, Microsoft Graph, Intune, provider permission names, provider payload metadata.
• Platform-core seams: Workspace, Managed Environment, Environment scope, Provider Connection, Operation, Finding, Review, Evidence, Governance.
• Neutral platform terms / contracts preserved: current UI and tests should prefer workspace/environment terms in generic product surfaces.
• Retained provider-specific semantics and why: Microsoft/Entra tenant terms remain when external identity or provider data is the subject.
• Bounded extraction or follow-up path: no provider framework. Follow-up only for structural DB/model rename or broad localization productization.

Constitution Check

GATE: Must pass before runtime implementation and re-check before close-out.

• Inventory-first: no inventory/snapshot truth change.
• Read/write separation: no new write workflow. Touched destructive labels such as restore/remove must keep existing confirmation, authorization, and audit behavior.
• Single Graph contract path: no Graph calls added.
• Deterministic capabilities: no capability resolver change.
• Proportionality / no premature abstraction: copy updates are in place. The route-scope navigation helper is intentionally small, derived from existing route categories, and carries no persisted state.
• No new persisted truth: no migrations, tables, columns, compatibility shims, or dual-read paths.
• Workspace isolation: copy/helper/test changes must not weaken workspace membership checks.
• Tenant/managed-environment isolation: existing environment entitlement checks remain intact.
• RBAC-UX: non-member/out-of-scope remains 404; established member missing capability remains 403.
• Provider boundary: generic platform copy moves away from tenant-first wording; provider tenant terms remain provider-owned.
• Test governance: targeted guard/feature/browser lanes only; no hidden broad suite repair.
• Filament-native UI: Filament remains v5 on Livewire v4; no v3/v4 APIs; no custom UI styling changes.
• Deployment/ops: no asset registration is planned. If assets are unexpectedly registered, deploy notes must include cd apps/platform && php artisan filament:assets.

Filament v5 Output Contract

• Livewire compliance: Filament v5 targets Livewire v4.0+; current app has Livewire 4.1.4.
• Provider registration location: Laravel 12 provider registration remains in apps/platform/bootstrap/providers.php; this spec must not add or restore a panel provider.
• Globally searchable resources: No new searchable resource is planned. Any touched globally searchable resource must retain Edit/View pages or have global search disabled.
• Destructive actions: This spec may relabel existing destructive actions such as restore/remove. They must still execute via ->action(...), require ->requiresConfirmation(), and enforce server-side authorization.
• Asset strategy: No new Filament assets are planned. If implementation unexpectedly registers assets, deployment must include cd apps/platform && php artisan filament:assets.
• Testing plan: Touched Filament pages/resources/actions are covered with Pest/Filament tests; guard tests cover forbidden legacy helper/route wording; browser smokes cover affected anchors.

Test Governance Check

• Test purpose / classification by changed surface: Feature guard tests for terminology and route/runtime regression; Feature/Localization and Feature/Filament tests for labels/copy; Browser only for affected smoke anchors.
• Affected validation lanes: Feature/Guards, Feature/Localization, Feature/Workspaces, Feature/ProviderConnections, Feature/RequiredPermissions, Feature/Filament, affected Feature directories, Browser smoke anchors.
• Why this lane mix is the narrowest sufficient proof: The change is copy/test terminology cleanup with route-regression protection, not a new workflow.
• Narrowest proving command(s):

cd apps/platform
./vendor/bin/sail artisan test --compact tests/Feature/Guards/Spec288NoLegacyRouteAndHelperGuardTest.php
./vendor/bin/sail artisan test --compact tests/Feature/Guards
./vendor/bin/sail artisan test --compact tests/Feature/Localization

• Fixture / helper / factory / seed / context cost risks: Avoid widening setAdminEnvironmentContext() or adding provider/browser setup defaults.
• Expensive defaults or shared helper growth introduced?: none planned.
• Heavy-family additions, promotions, or visibility changes: none planned; targeted browser smokes only when affected.
• Surface-class relief / special coverage rule: Standard-native Filament relief unless a browser-visible context-shell anchor changes.
• Closing validation and reviewer handoff: run final scans, focused guards, affected feature lanes, browser anchors if touched, Pint dirty, and git diff --check.
• Budget / baseline / trend follow-up: none expected.
• Review-stop questions: Did old tenant-first wording remain in active UI? Did a guard literal become ambiguous? Did a browser smoke still click old copy? Did route scans remain clean? Did destructive action relabeling preserve confirmation/authorization?
• Escalation path: document-in-feature for allowed exceptions; follow-up-spec for structural rename/localization beyond scope.
• Active feature PR close-out entry: Guardrail / Terminology Cleanup / Smoke Coverage.
• Why no dedicated follow-up spec is needed: The current work is a bounded cleanup. Structural rename and broad localization remain explicit follow-ups.

Project Structure

Documentation (this feature)

specs/298-managed-environment-terminology-copy-cleanup/
├── spec.md
├── plan.md
├── tasks.md
├── terminology-audit.md
└── checklists/
    └── requirements.md

Source Code (repository root)

Expected touched surfaces during implementation:

apps/platform/lang/
├── en/localization.php
└── de/localization.php

apps/platform/resources/views/
├── filament/partials/context-bar.blade.php
├── filament/pages/**
└── livewire/**

apps/platform/app/
├── Filament/**
├── Support/**
└── Services/**

apps/platform/tests/
├── Pest.php
├── Feature/**
└── Browser/**

Structure Decision: Use existing Laravel/Filament app structure and existing localization/test conventions. Do not create a new base application folder or dependency.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
Spec-local terminology audit	Remaining Tenant references need classification so the implementation does not remove provider/internal/historical truth blindly	Ad hoc final summary would not give reviewers a durable exception map
Cross-cutting copy/test updates	The old vocabulary appears across multiple existing layers	One local label change would leave contradictory product truth
Guard wording update	Legacy helper regex literals remain useful but ambiguous	Removing the regex would weaken Spec 288 protection

Phase 0: Safety Gate

1. Run:

git status --short --branch
git diff --stat
git log -1 --oneline

2. Confirm the implementation branch is 298-managed-environment-terminology-copy-cleanup or an isolated session branch derived from it.
3. Stop if unrelated uncommitted changes exist.
4. Read:

.specify/memory/constitution.md
specs/297-managed-environment-canonical-route-cutover/
specs/288-quality-gates-no-legacy-enforcement/
specs/286-ui-copy-ia-localization-neutralization/

Phase 1: Baseline Scan And Audit

Refresh terminology-audit.md before application edits:

git status --short --branch
git diff --stat

cd apps/platform
./vendor/bin/sail artisan route:list | rg "admin/tenants|admin/t/" && exit 1 || true

rg "filament\.admin\.resources\.tenants|/admin/tenants|/admin/t/|TenantResource::getUrl|TenantDashboard::getUrl|TenantRequiredPermissions::getUrl|setTenantPanelContext|panel:\s*'tenant'|panel:\s*\"tenant\"" app resources routes --glob '!vendor' --glob '!node_modules'

rg "setTenantPanelContext|panel:\s*'tenant'|panel:\s*\"tenant\"" tests --glob '!vendor' --glob '!node_modules'

rg "Tenant dashboard|Tenant detail|Open tenant|Select tenant|Tenant scope|No tenant selected|No active tenants|Remove tenant|Restore tenant|Tenant memberships|tenant blocker" app resources lang tests --glob '!vendor' --glob '!node_modules'

Classify findings as fixed, allowed-provider-term, allowed-internal-model, allowed-historical, allowed-regression-guard, out-of-scope-db-model-rename, or needs-follow-up.

Phase 2: Guard And Test Helper Cleanup

• Keep setAdminEnvironmentContext() as the active helper if repo-real.
• Do not add setTenantPanelContext() alias.
• Update guard test descriptions and failure messages so remaining setTenantPanelContext regex literals clearly forbid a retired helper.
• Update active test names/comments that describe current runtime as tenant panel context.
• Run:

cd apps/platform
./vendor/bin/sail artisan test --compact tests/Feature/Guards/Spec288NoLegacyRouteAndHelperGuardTest.php
./vendor/bin/sail artisan test --compact tests/Feature/Guards

Phase 3: Localization And Visible Copy Cleanup

• Update EN/DE localization values first; rename keys only when usage is fully bounded.
• Replace targeted active UI phrases:
  • Tenant dashboard -> Environment dashboard or Managed environment dashboard
  • Tenant detail / Open tenant detail -> Environment detail / Open environment detail
  • Select tenant -> Select environment
  • Tenant scope -> Environment scope
  • No tenant selected -> No environment selected
  • No active tenants -> No active environments
  • Tenant memberships -> Environment access scopes
  • Remove tenant -> Remove environment
  • Restore tenant -> Restore environment
  • tenant blocker -> environment blocker
• Keep Microsoft/Entra tenant ID wording where provider-specific.
• Preserve existing Filament action hierarchy and destructive-action safeguards.
• Run focused tests for touched areas.

Phase 4: Blade, Filament, Support Copy, And Browser Smokes

• Update context-bar, dashboard, monitoring, baseline compare, required-permissions, backup schedule, support diagnostics, governance action, and policy surface copy as discovered by the audit.
• Prefer stable data-testid selectors for browser smokes if old copy is not a stable product contract.
• Do not increase timeouts without a documented timing cause.
• Run affected browser smokes individually before broader browser anchors.

Phase 5: Final Scans And Proof Pack

Run the final scans from Phase 1 again. Every remaining hit must be absent or documented in terminology-audit.md.

Phase 5A: Navigation Segregation Addendum

The implementation must also close the observed post-cutover navigation leak:

cd apps/platform
./vendor/bin/sail artisan route:list | rg "workspaces/.*/environments|admin/tenants|admin/t|operations|provider-connections|required-permissions"
rg "shouldRegisterNavigation|getNavigationGroup|getNavigationLabel|getNavigationSort|navigation" app/Filament app/Providers resources tests --glob '!vendor' --glob '!node_modules'
rg "Filament::getTenant|Filament::setTenant|WorkspaceContext|ManagedEnvironment|current.*tenant|tenant context|environment context|setAdminEnvironmentContext|SESSION_KEY" app tests --glob '!vendor' --glob '!node_modules'

Implementation direction:

• Reuse TenantPageCategory through a small central helper that answers workspace surface vs environment surface.
• Current route/surface wins over remembered environment, session environment, query hints, or stale Filament::getTenant().
• Keep workspace-owned navigation visible on workspace surfaces.
• Hide environment-owned Resource/Page navigation on workspace surfaces.
• Show environment-owned navigation again on canonical environment routes such as /admin/workspaces/{workspace}/environments/{environment} and child routes.
• Keep retired /admin/t..., /admin/tenants..., and TenantPanelProvider absent.

Focused proof commands:

cd apps/platform
./vendor/bin/sail artisan test --compact tests/Feature/Filament/PanelNavigationSegregationTest.php
./vendor/bin/sail artisan test --compact tests/Feature/Guards/ManagedEnvironmentCanonicalRouteContractTest.php tests/Feature/Guards/NoLegacyTenantPanelRuntimeTest.php
./vendor/bin/sail artisan test --compact tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php

Run proof commands:

cd apps/platform
./vendor/bin/sail artisan test --compact tests/Feature/Guards
./vendor/bin/sail artisan test --compact tests/Feature/Localization
./vendor/bin/sail artisan test --compact tests/Feature/Workspaces
./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections
./vendor/bin/sail artisan test --compact tests/Feature/RequiredPermissions
./vendor/bin/sail artisan test --compact tests/Feature/Filament
./vendor/bin/sail artisan test --compact tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php
./vendor/bin/sail bin pint --dirty --format agent

Then run from the repo root:

git diff --check

Phase 6: Close-Out

• Update terminology-audit.md with final status and allowed references.
• Record the Filament v5 output contract in the implementation summary.
• Final decision must be one of:
  • 298 merge-ready; terminology cleanup complete
  • 298 merge-ready with documented allowed technical tenant references
  • 298 blocked by active legacy tenant copy
  • 298 blocked by runtime legacy regression

Explicit Follow-Ups / Out of Scope

• Database/model rename from Tenant to ManagedEnvironment
• Broad localization v1 or customer-facing localization adoption
• Historical spec/doc rewrite
• New customer review workspace
• Decision inbox or new governance workflow
• New RBAC or provider abstraction
• UI redesign