ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/298-managed-environment-terminology-copy-cleanup/tasks.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

17 KiB
Raw Permalink Blame History

description
Task list for Managed Environment Terminology & Copy Cleanup

Tasks: Managed Environment Terminology & Copy Cleanup

Input: Design documents from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/298-managed-environment-terminology-copy-cleanup/
Prerequisites: spec.md, plan.md, terminology-audit.md, checklists/requirements.md

Tests: Required (Pest) for guard/test/localization/copy changes. Browser smoke is required only if visible browser anchors/selectors are touched.
Operations: No new OperationRun behavior. Existing operation links and copy must keep the shared OperationRun UX contract if touched.
RBAC: No authorization model change. Existing 404/403 semantics, capability checks, and destructive action authorization must remain intact.
Filament / Panel Guardrails: Filament remains v5 on Livewire v4. Provider registration remains in apps/platform/bootstrap/providers.php. No new panel. No asset-strategy change unless explicitly documented.
Review Outcome: preparation-ready
Workflow Outcome: keep
Test-governance Outcome: keep

Test Governance Checklist

  • Lane assignment is named and is the narrowest sufficient proof for each changed behavior.
  • New or changed tests stay in the smallest honest family; browser/heavy-governance additions are explicit.
  • Shared helpers, factories, seeds, fixtures, provider setup, workspace context, session state, and capability defaults stay cheap by default.
  • Planned validation commands cover terminology, route guard, helper, and browser-anchor changes without pulling in unrelated lane cost.
  • The declared surface test profile or standard-native-filament relief is explicit.
  • Any material runtime, budget, baseline, trend, or escalation note is recorded in the active spec close-out.

Phase 1: Safety Gate And Baseline Audit

Purpose: Start from a clean branch and record repo truth before runtime edits.

  • T001 Run git status --short --branch, git diff --stat, and git log -1 --oneline in /Users/ahmeddarrazi/Documents/projects/wt-plattform; stop if unrelated uncommitted changes are present.
  • T002 Confirm the implementation branch is 298-managed-environment-terminology-copy-cleanup or an isolated session branch derived from it.
  • T003 Review /Users/ahmeddarrazi/Documents/projects/wt-plattform/.specify/memory/constitution.md, this spec package, and related Specs 286, 288, and 297 as context only.
  • T004 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan route:list | rg "admin/tenants|admin/t/" && exit 1 || true.
  • T005 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/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'.
  • T006 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && rg "setTenantPanelContext|panel:\\s*'tenant'|panel:\\s*\\\"tenant\\\"" tests --glob '!vendor' --glob '!node_modules'.
  • T007 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/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'.
  • T008 Update /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/298-managed-environment-terminology-copy-cleanup/terminology-audit.md with every initial finding before editing application code.
  • T009 Confirm the scope boundary remains explicit: no DB/model rename, no migration rewrite, no old route restoration, no helper alias, no broad localization architecture, and no UI redesign.

Phase 2: Guard And Test Helper Terminology

Goal: Make current test vocabulary match admin environment context while retaining explicit retired-helper guards.

  • T010 [P] Inspect /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Pest.php and confirm setAdminEnvironmentContext() is the active helper and setTenantPanelContext() is absent.
  • T011 [P] Inspect /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Guards/Spec288NoLegacyRouteAndHelperGuardTest.php for setTenantPanelContext forbidden-pattern literals.
  • T012 Update Spec 288 guard test names, comments, and failure messages so any remaining setTenantPanelContext regex literal clearly forbids reintroducing the retired tenant panel context helper.
  • T013 Update active test names/comments that describe current runtime setup as tenant panel, tenant panel context, panel tenant, or equivalent legacy wording.
  • T014 Ensure no compatibility alias named setTenantPanelContext() is introduced.
  • T015 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/Spec288NoLegacyRouteAndHelperGuardTest.php.
  • T016 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards.

Phase 3: Localization Values

Goal: Make EN/DE values output environment-first product language.

  • T017 [P] Audit /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/en/localization.php for targeted tenant-first values.
  • T018 [P] Audit /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/de/localization.php for targeted tenant-first values.
  • T019 Update EN shell/dashboard/support/customer-visible values so active generic UI says environment or managed environment instead of tenant-first wording.
  • T020 Update DE shell/dashboard/support/customer-visible values with equivalent environment wording.
  • T021 Keep existing localization keys if renaming them would broaden scope; update visible values first.
  • T022 If any key is renamed, update all usages and tests in the same phase.
  • T023 Update localization tests under /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Localization and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Guards that assert old copy.
  • T024 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Localization.

Phase 4: Active UI Copy In App And Views

Goal: Replace targeted tenant-first visible copy in active Filament, Blade, support, and service surfaces.

  • T025 [P] Audit /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/resources/views/filament/partials/context-bar.blade.php and other active context-bar/shell views for visible Tenant scope, No tenant selected, and Open tenant wording.
  • T026 [P] Audit /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/resources/views/filament/pages/monitoring/finding-exceptions-queue.blade.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/resources/views/filament/pages/tenant-required-permissions.blade.php.
  • T027 [P] Audit /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/Findings/MyFindingsInbox.php, and relevant app/Filament/** surfaces for targeted labels/actions/headings.
  • T028 [P] Audit /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/** and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/** for emitted visible copy such as Restore tenant, No tenant selected, and tenant blocker.
  • T029 Replace active visible Open tenant detail, Open tenant compare, and similar labels with Open environment ... wording unless the target is provider-specific Microsoft tenant detail.
  • T030 Replace active visible Tenant scope, Select tenant, No tenant selected, and No active tenants with environment wording.
  • T031 Replace active visible Remove tenant, Restore tenant, and Tenant memberships with environment/access-scope wording while preserving destructive action confirmation and authorization.
  • T032 Replace active visible tenant blocker or similar dashboard/readiness phrasing with environment wording.
  • T033 Preserve provider-specific phrases such as Microsoft tenant ID and Entra tenant ID when the external provider is the subject.
  • T034 Update affected Feature/Filament tests to assert current copy or stable semantics.

Phase 5: Browser Smoke Selectors

Goal: Keep browser smoke tests stable after copy changes.

  • T035 [P] Audit /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php.
  • T036 [P] Audit /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php.
  • T037 [P] Audit /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Browser/Spec192RecordPageHeaderDisciplineSmokeTest.php and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Browser/Dashboard/TenantDashboardProductizationSmokeTest.php if copy changes affect them.
  • T038 Prefer stable data-testid selectors for changed click targets when copy is not the product contract.
  • T039 If adding a new data-testid, keep it narrowly scoped to the existing element and avoid layout/style changes.
  • T040 Do not increase browser timeouts unless a real timing cause is identified and documented.
  • T041 Run each affected browser test individually before the final browser anchor command.

Phase 6: Audit Exceptions And Final Scans

Goal: Ensure every remaining tenant reference is intentional and documented.

  • T042 Run the final route scan: cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan route:list | rg "admin/tenants|admin/t/" && exit 1 || true.
  • T043 Run the final source scan from T005 and ensure it is clean or documented with explicit allowed technical exceptions.
  • T044 Run the final test-helper scan from T006 and ensure only explicit forbidden-legacy guard literals remain.
  • T045 Run the final copy scan from T007 and ensure every remaining hit is absent or documented.
  • T046 Update /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/298-managed-environment-terminology-copy-cleanup/terminology-audit.md with categories for every remaining hit: fixed, allowed-provider-term, allowed-internal-model, allowed-historical, allowed-regression-guard, out-of-scope-db-model-rename, or needs-follow-up.
  • T047 Confirm no active runtime route, provider, compatibility alias, or global-search route regression from Spec 297 was reintroduced.

Phase 7: Proof Pack And Formatting

Goal: Prove focused lanes remain green.

Close-out note: The full Filament feature lane was rerun after formatting and the terminology fixes. It completed with one order-sensitive failure in tests/Feature/Filament/GovernanceArtifacts/GovernanceArtifactEnvironmentContextTest.php where ReviewPackResource::executeGeneration() did not create a ReviewPack during the full suite; the same test file passed immediately when run alone. No changed implementation file participates in that governance artifact generation path, so this is recorded as residual non-terminology test-order risk rather than an in-scope Spec 298 finding.

  • T048 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards.
  • T049 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Localization.
  • T050 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces.
  • T051 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections.
  • T052 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/RequiredPermissions.
  • T053 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament.
  • T054 If browser files or visible browser anchors changed, run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php plus any touched browser file.
  • T055 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail bin pint --dirty --format agent.
  • T056 Run git diff --check from /Users/ahmeddarrazi/Documents/projects/wt-plattform.

Phase 8: Close-Out Summary

Goal: Finish with a reviewer-ready proof summary and decision.

  • T057 Confirm the Filament v5 output contract in the final implementation summary: Livewire v4.0+ compliance, provider registration in bootstrap/providers.php, global-search handling, destructive action confirmation/authorization, asset strategy, and testing plan.
  • T058 Record commands run and results in the final implementation summary.
  • T059 Record fixed terminology groups with before/after examples.
  • T060 Record remaining allowed references and reasons from terminology-audit.md.
  • T061 Choose one final decision string: 298 merge-ready; terminology cleanup complete, 298 merge-ready with documented allowed technical tenant references, 298 blocked by active legacy tenant copy, or 298 blocked by runtime legacy regression.

Phase 9: Navigation Segregation Addendum

Goal: Prevent stale environment/session context from making Workspace Overview show environment-owned primary navigation.

  • T062 Run the navigation and context baseline scans from plan.md Phase 5A and record the current leak path in terminology-audit.md.
  • T063 Add or reuse one central route-scope helper that distinguishes workspace surfaces from environment surfaces with current route scope taking precedence over session and Filament::getTenant() state.
  • T064 Update the Admin panel navigation override so workspace surfaces render workspace-owned navigation even when a stale environment is remembered or selected.
  • T065 Gate environment-owned Resource/Page navigation so Policies, Policy Versions, Backup Schedules, Backup Sets, Restore Runs, Findings, Baselines, Baseline Snapshots, Baseline Compare, Evidence, Risk exceptions, Stored reports, Review Packs, and Reviews do not register on Workspace Overview.
  • T066 Keep repo-real workspace-owned navigation visible on workspace surfaces: Overview, Operations, Alerts, Audit Log, Governance inbox, Customer reviews, Manage workspaces, Integrations, and Settings where authorized. Do not invent workspace aggregate routes for Stored reports or Review Packs under this cleanup spec.
  • T067 Update focused navigation guard tests for Workspace Overview with stale Filament tenant, canonical environment route visibility, and retired /admin/t... and /admin/tenants... route absence.
  • T068 Run cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/PanelNavigationSegregationTest.php.
  • T069 Run affected legacy/canonical guard tests and targeted browser smoke anchors only; do not run a raw full suite.

Dependencies & Execution Order

  • Phase 1 blocks all runtime edits.
  • Phase 2 can run in parallel with Phase 3 after Phase 1 completes.
  • Phase 4 depends on the audit from Phase 1 and may proceed alongside localization updates if file ownership stays clear.
  • Phase 5 depends on knowing whether copy changes touched browser-visible anchors.
  • Phase 6 must run after all copy/test updates.
  • Phase 7 and Phase 8 close the proof loop.

Parallel Execution Examples

  • T010 and T017 can run in parallel because test-helper inspection and localization inspection touch different files.
  • T025, T026, T027, and T028 can run in parallel because they audit different UI/code surfaces.
  • T035 and T036 can run in parallel because the browser smoke files are independent.

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 or decision inbox
  • New RBAC or provider abstraction
  • UI redesign
  • Reactivation of /admin/t..., /admin/tenants..., TenantPanelProvider, or setTenantPanelContext()