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](/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/298-managed-environment-terminology-copy-cleanup/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:

```bash
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)**:

```bash
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)

```text
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:

```text
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:

```bash
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:

```text
.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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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