TenantAtlas/specs/275-customer-facing-localization-adoption/plan.md

Implementation Plan: Customer-Facing Localization Adoption v1

Branch: 275-customer-facing-localization-adoption | Date: 2026-05-04 | Spec: /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/spec.md Input: Feature specification from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/scripts/ for helper scripts.

Summary

Complete one bounded customer-facing localization adoption pass over the existing customer review flow. The narrow implementation path is to reuse the repo-real locale precedence and update endpoints in LocaleResolver and LocalizationController, keep the current customer review workspace and released-review detail as the only in-scope read surfaces, fill the remaining EN/DE glossary and helper-copy gaps in the existing localization.review.* catalogs, and preserve current review-pack, proof, entitlement, audit, and machine-artifact behavior unchanged.

This is prep-only work over the foundations from Specs 252, 258, and 260. Filament remains v5 on Livewire v4, provider registration stays unchanged in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/bootstrap/providers.php, global-search behavior remains unchanged, no destructive action is introduced, and no new panel, website-localization lane, export/audit localization lane, or generic locale/plugin framework is planned.

Technical Context

Language/Version: PHP 8.4, Laravel 12
Primary Dependencies: Filament v5, Livewire v4, Laravel translator, existing App\Services\Localization\LocaleResolver, App\Http\Controllers\LocalizationController, current localization.review.* and locale feedback catalogs, CustomerReviewWorkspace, TenantReviewResource, ViewTenantReview, current review-pack and evidence resource paths, shared RBAC and audit helpers
Storage: PostgreSQL via existing users.preferred_locale, existing workspace localization setting, existing tenant_reviews, review_packs, evidence_snapshots, memberships, and audit_logs; translation catalogs in apps/platform/lang/en and apps/platform/lang/de; no new persistence planned
Testing: Pest v4 feature coverage plus one existing browser smoke on the current customer review flow
Validation Lanes: confidence, browser Target Platform: Laravel monolith in apps/platform, existing admin plane (/admin) plus current tenant-scoped review detail reuse (/admin/t/{tenant}/...) Project Type: web application
Performance Goals: keep locale adoption request-local and DB-only, avoid extra remote calls, reuse current eager-loaded review/pack/evidence relations, and leave review-pack artifact generation and download payloads unchanged
Constraints: scope stays on existing EN/DE customer-facing review surfaces only; no new panel/provider/auth plane, no website localization, no export/JSON/audit artifact localization, no generic locale framework, no new global-search behavior, and no new destructive or mutating customer-workspace action
Scale/Scope: one locale foundation reuse path, one customer review workspace page, one released-review detail route in customer-workspace mode, existing review-pack and proof availability messaging, two existing EN/DE catalogs, and focused reuse of the current localization, reviews, tenant-review, and browser test families

Likely Affected Repo Surfaces

• /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Localization/LocaleResolver.php for the existing locale precedence contract reused by the customer-facing review flow.
• /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Http/Controllers/LocalizationController.php and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/routes/web.php for the existing context, override, and personal preference endpoints that already format locale feedback.
• /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php for localized row labels, empty-state copy, helper text, and glossary consistency on the canonical landing surface.
• /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php for the current localized intro and disclosure copy rendered above the workspace table.
• /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/TenantReviewResource.php for localized detail labels, package and proof availability wording, and customer-workspace summary copy already composed from existing review truth.
• /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php for the read-only customer_workspace detail mode and the existing Download governance package dominant action.
• /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Http/Controllers/ReviewPackDownloadController.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/ReviewPackResource.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php as reuse-only supporting seams for invariant pack and payload behavior and explicit proof-access messaging.
• /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/en/localization.php and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/de/localization.php as the canonical glossary assets to complete in place.
• /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Localization/LocalePreferenceFlowTest.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Localization/LocalizedNotificationFormattingTest.php, planned CustomerReviewSurfaceLocalizationTest.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php as the bounded proving path for locale adoption.

Filament v5 / Panel Notes

• Livewire v4.0+ compliance: The slice remains inside existing Filament v5 pages, resources, Blade views, and Livewire-backed request flows. No Livewire v3 behavior or compatibility work is introduced.
• Provider registration location: No provider or panel registration change is planned. Existing provider registration remains in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/bootstrap/providers.php.
• Global search: No new globally searchable resource or search behavior is introduced. Existing review-related search posture remains unchanged by this slice.
• Destructive actions: No destructive action enters scope. The customer-facing review flow stays read-only, and existing destructive or manage actions remain out of scope in customer-workspace mode.
• Asset strategy: No new Filament asset registration or loading strategy is planned. Deployment expectations remain unchanged; if future work ever registers assets elsewhere, the existing cd apps/platform && php artisan filament:assets deploy step still applies.

Localization / Glossary Fit

• Reuse the current localization.review.* keyspace as the single canonical customer-facing glossary rather than creating a second glossary file, terminology registry, or translation plugin framework.
• Treat the current workspace intro and disclosure, workspace table labels, empty states, released-review detail labels, current governance-package action, package and proof availability reasons, next-step guidance, and locale-feedback notifications as the bounded v1 surface inventory.
• Keep provider-specific artifact or report names secondary and already-gated. They may remain in deeper evidence or artifact contexts, but they must not become default customer-facing glossary terms.
• Keep raw JSON, exported review-pack contents, audit action IDs and metadata, signed download semantics, identifiers, and timestamps invariant. Localization applies to chrome, helper copy, notifications, and access-state wording only.
• Use English as the controlled fallback for missing in-scope German lines, and treat raw translation-key leakage on the customer-safe path as a blocker.

RBAC / Isolation Fit

• Workspace membership remains the first isolation boundary through the existing WorkspaceContext and TenantReviewRegisterService::canAccessWorkspace(...) path.
• /admin/reviews/workspace remains the canonical workspace-scoped landing route; /admin/t/{tenant}/reviews/{review} remains the tenant-scoped secondary context route reached through the existing customer_workspace=1 query flag.
• Locale changes must not alter current denial behavior: non-members and out-of-scope tenant or review targets remain 404, while in-scope actors missing record-level review access keep existing 403 behavior.
• Optional supporting access remains capability-gated: current review-pack download keeps the existing REVIEW_PACK_VIEW path, and evidence proof reuse remains secondary and gated by the current evidence capability model.
• No new customer identity plane, no widened download entitlement, and no new role family are introduced.

Data & Invariance Fit

• Existing users.preferred_locale and the existing workspace default-locale setting remain the only persisted locale truth.
• Existing TenantReview, ReviewPack, and EvidenceSnapshot records remain the canonical source of review, package, and proof truth.
• Translation catalogs remain derived presentation assets only; no new persisted glossary inventory, localization projection table, or review-localized artifact copy is created.
• Existing audit rows remain stable machine truth. Locale adoption must not rename action IDs, mutate audit metadata keys or values, or localize stored audit payloads.
• Existing signed review-pack download and evidence detail routes remain the only secondary artifact and proof seams reused by this slice.

UI / Surface Guardrail Plan

• Guardrail scope: changed surfaces
• Native vs custom classification summary: mixed
• Shared-family relevance: locale controls, status messaging, action labels, helper copy, evidence/report viewer chrome, governance-package access labels, and proof-access reasons
• State layers in scope: page, detail, URL-query/session
• Audience modes in scope: customer/read-only, customer-admin, auditor-read-only, operator-MSP
• Decision/diagnostic/raw hierarchy plan: decision-first, diagnostics-second, support-raw-third
• Raw/support gating plan: collapsed and capability-gated on reused detail and proof routes only
• One-primary-action / duplicate-truth control: the workspace keeps Open review as the one dominant row action; released-review detail keeps Download governance package as the one dominant header action in customer-workspace mode; localization should not create parallel summary blocks
• Handling modes by drift class or surface: review-mandatory
• Repository-signal treatment: review-mandatory
• Special surface test profiles: standard-native-filament, shared-detail-family
• Required tests or manual smoke: functional-core, state-contract, bounded-browser-smoke
• Exception path and spread control: none planned; any new locale framework, new customer shell, or localized export or audit artifact becomes exception-required drift
• Active feature PR close-out entry: Smoke Coverage

Shared Pattern & System Fit

• Cross-cutting feature marker: yes
• Systems touched: locale resolution and feedback endpoints, current review localization catalogs, CustomerReviewWorkspace, existing workspace Blade intro, TenantReviewResource, ViewTenantReview, current governance-package download label, proof-access reasons, and localized status and helper copy
• Shared abstractions reused: LocaleResolver, LocalizationController, existing localization.review.* and locale notification and validation strings, existing customer-workspace query flag behavior, current review-pack and evidence truth presenters, and current review and detail RBAC paths
• New abstraction introduced? why?: none planned
• Why the existing abstraction was sufficient or insufficient: the locale foundation, update endpoints, review workspace, and released-review detail are already repo-real and are the correct shared path. What is insufficient today is glossary completion and consistent surface coverage on those existing seams.
• Bounded deviation / spread control: none planned. If a future implementation claims the current keyspace or surfaces are insufficient, it must prove that a narrower in-place catalog or surface update cannot solve the current-release gap.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: no
• Central contract reused: N/A
• Delegated UX behaviors: N/A
• Surface-owned behavior kept local: localized copy only on existing read surfaces and locale feedback responses
• Queued DB-notification policy: N/A
• Terminal notification path: N/A
• Exception path: none

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: yes
• Provider-owned seams: raw provider report or artifact names in already-gated evidence or detail contexts only
• Platform-core seams: customer review, governance package, proof access, next step, review status, evidence, and locale feedback wording
• Neutral platform terms / contracts preserved: customer review, governance package, current review pack, proof access, next step, accepted risk, and customer-safe detail
• Retained provider-specific semantics and why: provider-specific names may remain only when a deeper artifact or evidence surface already exposes them under existing entitlement. They do not become default-visible glossary terms.
• Bounded extraction or follow-up path: none

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• Inventory-first / snapshot truth: PASS. The slice localizes presentation over existing review, pack, and evidence truth only.
• Read/write separation: PASS. The only writes are the already-existing locale override and user preference flows; customer-facing review surfaces remain read-only.
• Graph contract path: PASS. No new Graph call or provider contract work is introduced.
• Deterministic capabilities: PASS. Existing workspace, tenant, and capability seams remain authoritative.
• Workspace and tenant isolation: PASS. Locale changes do not relax current 404 workspace or tenant boundaries.
• RBAC-UX plane separation: PASS. Everything stays in the existing admin plane and current tenant-scoped review routes; no new auth plane is added.
• Destructive confirmation standard: PASS by non-use. No destructive action enters scope.
• Global search safety: PASS. No new searchable resource or search behavior is added.
• OperationRun / Ops-UX: PASS by non-use. No run start, lifecycle, or notification semantics change.
• Data minimization and machine invariance: PASS. Exported review-pack contents, raw JSON, audit payloads, IDs, and other machine artifacts remain unchanged.
• Test governance (TEST-GOV-001): PASS. Proof stays in focused feature coverage plus the existing single browser smoke.
• Proportionality / no premature abstraction: PASS. The narrow path is catalog completion and surface adoption on existing seams, not a new locale or glossary framework.
• Persisted truth (PERSIST-001): PASS. No new table, projection, artifact family, or locale store is planned.
• Behavioral state (STATE-001): PASS. Access and availability labels remain derived presentation over current review-pack and evidence truth; no new persisted state family is added.
• UI semantics / shared pattern first / Filament-native UI: PASS. Existing Filament pages, resources, and the current localization keyspace remain the first reuse path.
• Provider boundary (PROV-001): PASS. Default customer-facing vocabulary stays platform-owned and provider-neutral.
• Filament / Laravel planning contract: PASS. Filament remains v5 on Livewire v4, provider registration remains in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/bootstrap/providers.php, no panel or provider change is planned, no global-search change is planned, and no new assets are expected.

Gate evaluation: PASS.

• The narrow implementation remains defensible if it reuses the current locale contract and current customer review flow instead of creating a second glossary or shell.
• The gate fails if implementation drifts into website localization, export or audit localization, a new panel, provider, or auth plane, or a generic locale/plugin framework.

Post-design re-check: PASS once /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/research.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/data-model.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/quickstart.md, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/contracts/customer-facing-localization-adoption.openapi.yaml are present and the agent-context refresh step is executed.

Test Governance Check

• Test purpose / classification by changed surface: Feature for locale preference and override reuse, localized feedback, customer review workspace and detail copy, and glossary consistency; Browser for one existing end-to-end smoke of the customer review flow
• Affected validation lanes: confidence, browser
• Why this lane mix is the narrowest sufficient proof: the main risk is rendered customer-facing wording and existing access-state continuity on repo-real surfaces, not new backend workflow breadth or a new browser family
• Narrowest proving command(s):
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Localization/LocalePreferenceFlowTest.php tests/Feature/Localization/LocalizedNotificationFormattingTest.php tests/Feature/Localization/CustomerReviewSurfaceLocalizationTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/TenantReview/TenantReviewUiContractTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
• Fixture / helper / factory / seed / context cost risks: low to moderate; reuse existing workspace membership, tenant entitlement, published review, current review-pack, and locale helpers instead of creating a new heavy fixture family
• Expensive defaults or shared helper growth introduced?: no; any new helper should stay explicit and local to the localization or reviews family
• Heavy-family additions, promotions, or visibility changes: none beyond the already-existing single browser smoke
• Surface-class relief / special coverage rule: standard-native-filament relief on the workspace page and shared-detail-family coverage on the customer-workspace review detail
• Closing validation and reviewer handoff: rerun the exact commands above, verify no raw translation keys appear on the in-scope surfaces, verify workspace and detail copy use the same glossary in EN and DE, verify locale changes do not alter current 404 or 403 behavior, and verify download, audit, and machine artifacts stay unlocalized
• Budget / baseline / trend follow-up: none expected beyond contained feature-local assertions
• Review-stop questions: lane fit, hidden fixture growth, glossary drift between workspace and detail, accidental machine-artifact localization, and scope creep into website or framework work
• Escalation path: document-in-feature for contained glossary inventory notes; reject-or-split for any drift into new locale infrastructure or broader localization programs
• Active feature PR close-out entry: Smoke Coverage
• Why no dedicated follow-up spec is needed: this plan is already the bounded adoption follow-through on existing localization and customer-review foundations; broader operator-wide or website localization remains explicitly out of scope
• Test-governance outcome: keep

Review Checklist Status

• Review checklist artifact: checklists/requirements.md
• Review outcome class: acceptable-special-case
• Workflow outcome: keep
• Test-governance outcome: keep
• Escalation rule: if implementation widens into website localization, export or audit localization, a new locale framework, or a new panel or auth plane, flip the workflow outcome to split or reject-or-split before continuing

Rollout & Risk Controls

• Keep the canonical entry surface on the existing customer review workspace and the canonical secondary surface on the existing released-review detail route.
• Inventory the in-scope customer-facing glossary before code changes, then fill EN/DE catalog gaps in place so workspace and detail copy cannot drift independently.
• Treat English fallback and raw-key avoidance as rollout blockers; a missing German string should render approved English, never the raw key.
• Keep current signed review-pack download and evidence detail behavior unchanged. Localize only surrounding labels, tooltips, helper text, and blocked or unavailable reasons.
• Preserve current tenant and workspace filters and customer-workspace launch context when locale changes mid-flow.
• Keep browser validation bounded to the existing smoke harness before considering wider UI rollout or broader localization scope.

Project Structure

Documentation (this feature)

specs/275-customer-facing-localization-adoption/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── customer-facing-localization-adoption.openapi.yaml
└── tasks.md             # Created later by /speckit.tasks, not by this plan step

Source Code (repository root)

apps/platform/
├── app/
│   ├── Filament/
│   │   ├── Pages/Reviews/
│   │   │   └── CustomerReviewWorkspace.php
│   │   └── Resources/
│   │       ├── TenantReviewResource.php
│   │       └── TenantReviewResource/Pages/ViewTenantReview.php
│   ├── Http/
│   │   └── Controllers/
│   │       ├── LocalizationController.php
│   │       └── ReviewPackDownloadController.php
│   ├── Services/
│   │   └── Localization/
│   │       └── LocaleResolver.php
│   └── Support/
│       ├── Audit/
│       └── Auth/
├── lang/
│   ├── en/localization.php
│   └── de/localization.php
├── resources/views/filament/pages/reviews/customer-review-workspace.blade.php
├── routes/web.php
└── tests/
    ├── Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php
    ├── Feature/Localization/
    ├── Feature/Reviews/
    └── Feature/TenantReview/

Structure Decision: Laravel monolith. The future implementation stays inside the existing apps/platform localization, customer-review, review-pack, and proof surfaces, with no new panel or provider location and no new persistence layer.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
None expected at planning time	The plan reuses existing locale, review, and catalog seams instead of introducing new structural machinery	A new glossary framework, locale plugin system, or customer-facing mirror surface would add ownership cost without a new source-of-truth need

Proportionality Review

• Current operator problem: the repo already resolves locale and exposes customer-safe review surfaces, but the customer-facing review flow still contains mixed or incomplete EN or DE wording and uneven glossary coverage across workspace, detail, and access-state messaging.
• Existing structure is insufficient because: the current locale foundation and customer-review productization seams exist, but they do not yet guarantee one completed customer-facing glossary and one bounded surface inventory for language adoption.
• Narrowest correct implementation: reuse LocaleResolver, LocalizationController, current localization.review.* catalogs, current workspace and detail surfaces, and focused localization and review tests to complete the customer-facing EN or DE adoption pass in place.
• Ownership cost created: ongoing maintenance of a bounded EN or DE customer-facing glossary and a small set of feature and browser assertions for those existing surfaces.
• Alternative intentionally rejected: a generic locale or plugin framework, website localization program, export or audit artifact localization pass, or second customer-facing shell was rejected because the current release needs adoption on already-real surfaces, not new infrastructure.
• Release truth: current-release follow-through on existing localization and customer-review foundations

Phase 0 — Research (output: research.md)

See: /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/research.md

Goals:

• Confirm the current locale resolution and feedback seams that must be reused rather than replaced.
• Confirm the bounded customer-facing surface inventory and glossary scope for v1.
• Confirm machine-artifact and audit invariance boundaries.
• Confirm the narrowest proving lane that extends current localization and review tests without opening a broader browser or framework scope.

Phase 1 — Design & Contracts (output: data-model.md, quickstart.md, contracts/)

See:

• /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/data-model.md
• /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/quickstart.md
• /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/contracts/customer-facing-localization-adoption.openapi.yaml

Design outputs capture:

• the existing locale, review, pack, proof, and glossary truth reused by the slice
• the derived localized workspace and detail view models and invariance rules
• the conceptual contract for locale endpoints and reused customer-review surfaces
• the exact validation commands and smoke focus that should remain canonical for this plan package

Proposed Implementation Phases

1. Glossary Inventory & Catalog Gap Audit: enumerate the current in-scope customer-facing keys across workspace, detail, package and proof reasons, and locale feedback; mark any missing or mixed EN and DE lines without widening scope.
2. Workspace Localization Adoption: align the customer review workspace intro, headings, table labels, empty states, and next-step copy with the approved glossary while preserving current tenant filter and row-action behavior.
3. Released-Review Detail Localization Adoption: align ViewTenantReview customer-workspace mode, detail labels, dominant governance-package action label, helper text, and package and proof availability reasons with the same glossary while keeping the surface read-only.
4. Regression Proof & Rollout Guardrails: add or expand the bounded feature test for customer-review surface localization, update the existing workspace and detail assertions as needed, and keep the existing browser smoke as the only browser proof for the slice.