ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
548a37c888
TenantAtlas/specs/298-managed-environment-terminology-copy-cleanup/terminology-audit.md
ahmido 5722c4f051 feat: clean up managed environment terminology copy (#353) 
## Summary
- replace tenant-first operator copy with environment and managed environment terminology across Filament pages, resources, services, Blade views, and localization
- align baseline compare, findings, governance, monitoring, backup schedule, and required-permissions surfaces with the managed-environment vocabulary
- update guard, feature, and browser smoke coverage and add the Spec 298 audit artifacts documenting allowed provider, internal, and regression-guard tenant references

## Validation
- cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards
- cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Localization
- cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces
- cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections
- cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/RequiredPermissions
- cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php tests/Browser/Dashboard/TenantDashboardProductizationSmokeTest.php
- cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

## Notes
- Filament remains on Livewire v4.
- No panel provider or asset-strategy changes are included in this branch.
- Existing destructive actions retain their confirmation and authorization behavior.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #353
2026-05-13 09:34:08 +00:00

120 lines
17 KiB
Markdown
Raw Blame History

# Terminology Audit: Managed Environment Terminology & Copy Cleanup
**Feature**: `298-managed-environment-terminology-copy-cleanup`
**Created**: 2026-05-13
**Status**: Implemented close-out. Final scans refreshed on 2026-05-13.
## Categories
| Category | Meaning |
|---|---|
| `fixed` | The implementation replaced or removed the old tenant-first wording. |
| `allowed-provider-term` | The term describes external Microsoft/Entra provider truth, such as Microsoft tenant ID. |
| `allowed-internal-model` | The term is an internal model/class/table/column name and DB/model rename is out of scope. |
| `allowed-historical` | The term appears in historical specs/docs/audit history that this spec does not rewrite. |
| `allowed-regression-guard` | The term is kept only as a forbidden legacy pattern in a guard test. |
| `out-of-scope-db-model-rename` | The term requires a structural DB/model rename outside Spec 298. |
| `needs-follow-up` | The term is real drift but cannot be safely fixed inside Spec 298. |
## Implementation Baseline Scan
Read-only implementation scans were refreshed on 2026-05-13 before application edits.
| Command | Result | Decision |
|---|---|---|
| `git status --short --branch && git diff --stat && git log -1 --oneline` | Active branch is `298-managed-environment-terminology-copy-cleanup`; only the active spec package was untracked before audit edit; base commit `3ec582a1 feat: retire legacy tenant route surfaces (#352)`. | Safe to continue because the untracked files are the active prepared spec artifacts. |
| `cd apps/platform && ./vendor/bin/sail artisan route:list \| rg "admin/tenants\|admin/t/" && exit 1 \|\| true` | No output; no active route-list matches for retired route families. | Route baseline clean. |
| `cd apps/platform && 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'` | No output; no active runtime source matches in `app`, `resources`, or `routes`. | Source baseline clean. |
| `cd apps/platform && rg "setTenantPanelContext\|panel:\\s*'tenant'\|panel:\\s*\\\"tenant\\\"" tests --glob '!vendor' --glob '!node_modules'` | Five `setTenantPanelContext` regex literals remain in `tests/Feature/Guards/Spec288NoLegacyRouteAndHelperGuardTest.php`. | Allowed only as regression-guard literals after wording clarification. |
| `cd apps/platform && 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'` | Targeted active copy/test hits listed below. | In-scope cleanup targets except provider/internal/historical references. |
### Baseline Findings To Fix
| Pattern | File | Category | Decision | Reason |
|---|---|---|---|---|
| `Tenant scope`, `Select tenant`, `No tenant selected`, `No active tenants`, `Tenant dashboard`, `tenant blocker` | `apps/platform/lang/en/localization.php` | fixed | planned | Active localization values should output environment-first wording. Existing keys may remain if key rename is risky. |
| German tenant-first equivalents for context/dashboard copy | `apps/platform/lang/de/localization.php` | fixed | planned | Active DE localization values should output environment-first wording. |
| `Open tenant detail` | `apps/platform/resources/views/filament/pages/monitoring/finding-exceptions-queue.blade.php` | fixed | planned | Active view copy should say `Open environment detail` unless provider-specific. |
| `Open tenant compare` | `apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php` | fixed | planned | Baseline compare is an environment-context action after cutover. |
| `No tenant selected.` | `apps/platform/resources/views/filament/pages/tenant-required-permissions.blade.php` | fixed | planned | Required permissions page should describe missing environment context. |
| `Restore tenant` | `apps/platform/app/Services/Tenants/TenantActionPolicySurface.php` | fixed | planned | Visible operator copy should say restore environment while preserving confirmation/authorization. |
| `Restore tenant` | `apps/platform/app/Support/Ui/GovernanceActions/GovernanceActionCatalog.php` | fixed | planned | Governance action copy should say restore environment while preserving confirmation/authorization. |
| `Open tenant detail` | `apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php` | fixed | planned | Active action label should use environment wording. |
| `Open tenant findings` | `apps/platform/app/Filament/Pages/Findings/MyFindingsInbox.php`, `apps/platform/tests/Feature/Findings/MyWorkInboxTest.php` | fixed | planned | Active action label should use environment wording if it targets environment-scoped findings. |
| `No tenant selected` | `apps/platform/app/Filament/Resources/BackupScheduleResource.php` | fixed | planned | Backup schedule context copy should use environment wording. |
| `Remove tenant assignment` | `apps/platform/app/Filament/Resources/BaselineProfileResource/RelationManagers/BaselineTenantAssignmentsRelationManager.php` | fixed | planned | Visible destructive label should use environment assignment wording while preserving confirmation/authorization. |
| `No tenant selected.` | `apps/platform/app/Support/Baselines/BaselineCompareStats.php` | fixed | planned | Empty compare state should use environment context wording. |
| Old-copy assertions | `apps/platform/tests/Feature/Localization/EnvironmentContextTerminologyTest.php`, `apps/platform/tests/Feature/Guards/EnvironmentCopyNeutralizationGuardTest.php` | fixed | planned | Tests should assert current environment vocabulary and forbid retired product copy. |
| `setTenantPanelContext` regex literals | `apps/platform/tests/Feature/Guards/Spec288NoLegacyRouteAndHelperGuardTest.php` | allowed-regression-guard | clarify | May remain only as explicit forbidden legacy pattern. Test names/messages must not suggest a current helper. |
## Final Audit
| Pattern | File | Category | Decision | Reason |
|---|---|---|---|---|
| Retired route families `/admin/tenants` and `/admin/t/` | `apps/platform` route list | fixed | clean | Final route scan returned no matches. |
| Retired tenant panel route/helper patterns from T005 | `apps/platform/app`, `apps/platform/resources`, `apps/platform/routes` | fixed | clean | Final source scan returned no matches for retired route names, helper names, tenant panel provider usage, or tenant-panel route generation. |
| `setTenantPanelContext` | `apps/platform/tests/Feature/Guards/Spec288NoLegacyRouteAndHelperGuardTest.php` | allowed-regression-guard | keep | Remaining hits are forbidden-pattern regex literals and a clarified failure message preventing reintroduction of the retired helper. |
| `Tenant scope`, `Select tenant`, `No tenant selected`, `No active tenants`, `Tenant dashboard`, `tenant blocker` | `apps/platform/lang/en/localization.php`, `apps/platform/lang/de/localization.php`, context/support tests | fixed | complete | Active localization values now use environment/managed-environment wording. Existing key names remain where key renames would broaden scope. |
| Finding queue and governance inbox tenant-first labels | `apps/platform/app/Filament/Pages/**`, `apps/platform/resources/views/filament/pages/**`, related tests | fixed | complete | Active visible labels now say environment detail, environment findings, environment filter, or environment scope as appropriate. |
| Baseline compare tenant-first labels and empty states | `apps/platform/app/Filament/Pages/BaselineCompareMatrix.php`, `apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php`, `apps/platform/app/Support/Baselines/**`, `apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php`, related tests | fixed | complete | Visible compare labels now say assigned environments, visible assigned environments, and multi-environment scan. Internal action IDs and model names remain unchanged. |
| Destructive governance/environment action copy | `apps/platform/app/Services/Tenants/TenantActionPolicySurface.php`, `apps/platform/app/Support/Ui/GovernanceActions/GovernanceActionCatalog.php`, `apps/platform/app/Filament/Resources/BaselineProfileResource/RelationManagers/BaselineTenantAssignmentsRelationManager.php` | fixed | complete | Visible copy now says restore/archive/remove environment assignment while existing `->action(...)`, `->requiresConfirmation()`, and authorization surfaces remain intact. |
| Old product-copy strings in copy scan | `apps/platform/tests/Feature/Localization/EnvironmentContextTerminologyTest.php`, `apps/platform/tests/Feature/Guards/EnvironmentCopyNeutralizationGuardTest.php` | allowed-regression-guard | keep | Final copy scan hits are forbidden strings used only by regression guards/assertions to ensure active UI does not reintroduce them. |
| Microsoft tenant / Entra tenant identifiers | Provider/auth/Graph-facing code and tests | allowed-provider-term | keep | These terms describe external Microsoft provider concepts and are not product context labels. |
| `Tenant`, `tenant_id`, `tenantRouteKey`, `TenantResource`, tenant review model/resource names | Models, resources, relations, fixtures, historical test names | allowed-internal-model | keep | DB/model/resource rename is explicitly out of scope for Spec 298. Runtime routes were not restored. |
| Historical specs, archived decision context, and prior spec names | `specs/**`, `.specify/**`, historical tests where applicable | allowed-historical | keep | This cleanup does not rewrite historical records or prior spec names. |
## Navigation Segregation Addendum
The workspace/environment sidebar leak was confirmed as a route/context-gating issue: the admin middleware previously switched back to full Filament navigation whenever `Filament::getTenant()` was filled, even when the current route was Workspace Overview. Spec 298 now treats the current route/surface as the navigation source of truth.
| Entry | Workspace nav | Environment nav | Reason |
|---|---:|---:|---|
| Overview | yes | yes | Workspace landing remains the stable return point. |
| Operations | yes | yes | Workspace-scoped operations can optionally filter by environment. |
| Alerts | yes | yes | Workspace monitoring remains portfolio-oriented. |
| Audit Log | yes | yes | Workspace monitoring remains portfolio-oriented. |
| Governance inbox | yes | yes | Existing workspace-level governance triage surface. |
| Customer reviews | yes | yes | Existing workspace-level review workspace. |
| Manage workspaces | yes | yes | Workspace administration entry point. |
| Integrations | yes | yes | Existing provider-connection workspace route. |
| Settings | yes | yes | Existing workspace settings route, capability-gated. |
| Policies / Policy Versions / Inventory Items | no | yes | Tenant-owned inventory routes live under canonical environment routes. |
| Backup Schedules / Backup Sets / Restore Runs | no | yes | Backup/restore records are tenant-owned environment routes. |
| Findings / Risk exceptions / Evidence | no | yes | Governance artifacts are environment-owned records. |
| Baselines / Baseline Snapshots / Baseline Compare | no | yes | Main navigation is hidden on Workspace Overview and restored on environment surfaces; profile URLs remain workspace-owned until broader IA changes. |
| Stored reports / Review Packs / Reviews | no | yes | Current repo routes are environment-owned; no workspace aggregate route was invented under this cleanup spec. |
Implementation files:
- `apps/platform/app/Support/Navigation/NavigationScope.php`: central route-scope helper, including Livewire update referer handling.
- `apps/platform/app/Support/Middleware/EnsureFilamentTenantSelected.php`: admin sidebar now uses `NavigationScope::isEnvironmentSurface()` instead of stale `Filament::getTenant()` to decide full environment navigation.
- Environment-owned Filament resources/pages now call `NavigationScope::shouldRegisterEnvironmentNavigation()` from `shouldRegisterNavigation()`.
- `apps/platform/tests/Feature/Filament/PanelNavigationSegregationTest.php`: covers workspace overview with stale Filament tenant, environment route visibility, and retired `/admin/t...` plus `/admin/tenants...` absence.
## Final Verification Evidence
| Command | Result |
|---|---|
| `cd apps/platform && ./vendor/bin/sail artisan route:list \| rg "workspaces/.*/environments\|admin/tenants\|admin/t\|operations\|provider-connections\|required-permissions"` | Confirmed canonical workspace/environment routes; no retired route family restored. |
| `cd apps/platform && rg "shouldRegisterNavigation|getNavigationGroup|getNavigationLabel|getNavigationSort|navigation" app/Filament app/Providers resources tests --glob '!vendor' --glob '!node_modules'` | Confirmed navigation registration surfaces and updated route-scope gating. |
| `cd apps/platform && rg "Filament::getTenant|Filament::setTenant|WorkspaceContext|ManagedEnvironment|current.*tenant|tenant context|environment context|setAdminEnvironmentContext|SESSION_KEY" app tests --glob '!vendor' --glob '!node_modules'` | Confirmed context seams; navigation decision no longer relies on stale selected environment alone. |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/PanelNavigationSegregationTest.php` | Passed: 21 tests, 59 assertions after navigation addendum. |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/GovernanceArtifacts/GovernanceArtifactAdminPanelRegistrationTest.php` | Passed: 4 tests, 48 assertions. |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineProfileWorkspaceOwnershipTest.php` | Passed: 2 tests, 9 assertions. |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/Spec288NoLegacyRouteAndHelperGuardTest.php tests/Feature/Guards/ManagedEnvironmentCanonicalRouteContractTest.php tests/Feature/Guards/NoLegacyTenantPanelRuntimeTest.php tests/Feature/Filament/WorkspaceContextTopbarAndTenantSelectionTest.php tests/Feature/Filament/WorkspaceOverviewArrivalContextTest.php` | Passed: 11 tests, 97 assertions. |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewNavigationTest.php tests/Feature/Filament/WorkspaceOverviewArrivalContextTest.php tests/Feature/Filament/WorkspaceContextTopbarAndTenantSelectionTest.php` | Passed: 6 tests, 52 assertions. |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php` | Passed: 2 tests, 29 assertions. |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards` | Passed: 265 tests, 4705 assertions. |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Localization` | Passed: 16 tests, 95 assertions after updating stale German auth copy expectation. |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces` | Passed: 96 tests, 276 assertions. |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections` | Passed: 78 tests, 588 assertions. |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/RequiredPermissions` | Passed: 21 tests, 82 assertions. |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament` | Rerun after formatting completed with 764 passed, 5 skipped, 1 failed. The failure was an order-sensitive `ReviewPack` creation assertion in `GovernanceArtifactEnvironmentContextTest`, outside changed terminology code. |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/GovernanceArtifacts/GovernanceArtifactEnvironmentContextTest.php` | Passed: 5 tests, 12 assertions immediately after the full-suite failure. |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php tests/Browser/Dashboard/TenantDashboardProductizationSmokeTest.php` | Passed: 6 tests, 105 assertions. |
| `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` | Passed. |
## Residual Risk
The only remaining validation issue is the order-sensitive full Filament lane failure documented above. It does not touch the Spec 298 terminology files and passes in isolation, so it is not treated as an in-scope terminology finding. It should be tracked separately if full-suite determinism is required before merge.
Reference in New Issue View Git Blame Copy Permalink