TenantAtlas/specs/312-customer-review-workspace-v1-completion/plan.md

Implementation Plan: Customer Review Workspace v1 Completion

Branch: 312-customer-review-workspace-v1-completion | Date: 2026-05-15 | Spec: specs/312-customer-review-workspace-v1-completion/spec.md Input: Feature specification from specs/312-customer-review-workspace-v1-completion/spec.md

Summary

Productize the existing Customer Review Workspace as a customer-safe, workspace-wide released-review consumption surface. The implementation should use existing review, governance-package, accepted-risk, evidence, and Review Pack truth; present the latest released review prominently; render customer-safe decision summary, accepted risks, evidence basis, pack status, and filter-aware empty states; preserve customer-safe detail/download handoffs; and avoid all shell/sidebar/topbar, RBAC, persistence, OperationRun, provider, billing, AI, asset, and Review Pack generation changes.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52.0 Primary Dependencies: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, Tailwind CSS 4.2.2 through existing app assets only Storage: PostgreSQL; no schema changes Testing: Pest 4 feature tests, existing bounded browser smoke if UI changes Validation Lanes: focused confidence lanes for Reviews, EnvironmentReview, ReviewPack; browser lane if rendered UI changes; Spec 311 regression lane only if forbidden/adjacent files are touched unexpectedly Target Platform: Laravel Sail local development; Dokploy/container deployment unchanged Project Type: Laravel monolith under apps/platform Performance Goals: workspace-scoped and actor-entitled queries only; no raw evidence payload scans; avoid N+1 regressions for latest review and pack relationships Constraints: no new persistence, no new assets, no new package, no shell/sidebar/topbar work, no RBAC/policy changes unless repo-real inconsistency blocks implementation and is documented first Scale/Scope: one existing Filament page/view plus focused tests and minimal localization

UI / Surface Guardrail Plan

• Guardrail scope: changed customer-safe operator/customer-facing surface.
• Native vs custom classification summary: existing Filament page plus existing Blade view composition; no new design system or assets.
• Shared-family relevance: customer-safe review consumption, status messaging, action links, empty states, evidence/report disclosure.
• State layers in scope: page payload, table data, URL query filter, customer-safe detail context. Shell/sidebar/topbar state is explicitly out of scope.
• Audience modes in scope: customer-read-only and MSP operator.
• Decision/diagnostic/raw hierarchy plan: decision-first latest review and decision summary; accepted risks and evidence basis as supporting content; raw/support details hidden or absent.
• Raw/support gating plan: no raw/support data rendered on workspace; existing detail resources remain authoritative.
• One-primary-action / duplicate-truth control: one dominant CTA per current review context: download/open pack when authorized and available, otherwise open review; clear filter in filtered empty state.
• Handling modes by drift class or surface: shell/sidebar/topbar drift is a blocker and must stop implementation; page-local productization is in scope; broad route/query cleanup is follow-up.
• Repository-signal treatment: review-mandatory for UI leakage, /admin/t links, raw IDs as visible labels, and action hierarchy.
• Special surface test profiles: standard-native-filament, shared-detail-family, global-context-shell assertions only.
• Required tests or manual smoke: focused Feature rendered HTML assertions and existing browser smoke if rendered UI changes.
• Exception path and spread control: none expected. Any unavoidable local helper must stay private/page-local and be documented in close-out.
• Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.

Shared Pattern & System Fit

• Cross-cutting feature marker: yes.
• Systems touched: CustomerReviewWorkspace, customer-review-workspace.blade.php, existing review/pack handoff helpers if needed, localization files, focused tests.
• Shared abstractions reused: EnvironmentReviewRegisterService, EnvironmentReview::published(), EnvironmentReviewResource::tenantScopedUrl(), ReviewPackStatus, Capabilities::REVIEW_PACK_VIEW, existing customer_workspace=1 detail context, existing localization structure.
• New abstraction introduced? why?: none planned. Private page helpers are allowed only to shape display payload and keep Blade simple.
• Why the existing abstraction was sufficient or insufficient: Existing query and summary paths already contain required truth; the gap is productized presentation and guard tests.
• Bounded deviation / spread control: no public presenter/DTO/framework for v1; no new summary persistence.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: no.
• Central contract reused: N/A.
• Delegated UX behaviors: unchanged existing Review Pack generation/run behavior.
• Surface-owned behavior kept local: read-only pack availability explanation only.
• Queued DB-notification policy: N/A.
• Terminal notification path: unchanged.
• Exception path: none.

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: no.
• Provider-owned seams: N/A.
• Platform-core seams: review, evidence, decision, and pack consumption over existing TenantPilot governance artifacts.
• Neutral platform terms / contracts preserved: workspace, managed environment, released review, governance decisions, accepted risks, evidence basis, review pack.
• Retained provider-specific semantics and why: only existing review/evidence content may include provider-specific names if already present and customer-safe.
• Bounded extraction or follow-up path: Provider Connection Scope Hardening remains separate.

Constitution Check

• Inventory-first: PASS. Uses existing released-review/evidence snapshots and does not call Graph or inspect external state.
• Read/write separation: PASS. Customer Review Workspace remains read-only. No mutation CTA in customer-safe surface.
• Graph contract path: PASS. No Graph calls.
• Deterministic capabilities: PASS. Existing capabilities/policies remain authoritative.
• RBAC-UX: PASS. No RBAC change; workspace/environment membership and capability semantics remain existing server-side truth.
• Workspace isolation: PASS. Queries must scope to current workspace and actor-entitled managed environments.
• Tenant/environment isolation: PASS. Environment filter must not reveal out-of-scope records.
• Run observability: PASS. No new long-running work or OperationRun semantics.
• Data minimization: PASS. Raw payloads, fingerprints, OperationRun URLs, storage paths, and provider dumps are forbidden in rendered customer-safe HTML.
• Test governance: PASS with focused Feature coverage plus browser smoke when UI changes.
• Proportionality: PASS. No new persisted truth, enum/status family, public abstraction, or UI framework.
• Filament-native UI: PASS if implementation uses existing Filament page/Blade patterns and no new assets/ad-hoc style system.
• Decision-first operating model: PASS. Latest review and decision summary lead; diagnostics/raw data stay absent.
• Audience-aware disclosure: PASS. Customer-safe default hides raw/internal details.

Test Governance Check

• Test purpose / classification by changed surface: Feature tests for workspace rendering, deterministic latest selection, filter behavior, decision summary states, accepted risks, evidence basis, pack status, authorization, links, and leakage. Browser smoke for rendered UI workflow if available.
• Affected validation lanes: confidence, browser if UI changes.
• Why this lane mix is the narrowest sufficient proof: Behavior is primarily server-rendered Filament/Livewire HTML and existing route/link authorization. Focused feature tests can assert payloads, HTML, hrefs, and action absence; one browser smoke covers visual/user workflow risk.
• Narrowest proving command(s): the focused commands listed in spec.md and final validation section below.
• Fixture / helper / factory / seed / context cost risks: released reviews, review packs, evidence snapshots, accepted risks, and workspace/environment membership. Helpers must stay feature-local or existing; no new heavy default setup.
• Expensive defaults or shared helper growth introduced?: no.
• Heavy-family additions, promotions, or visibility changes: no new heavy-governance family; browser smoke uses existing family.
• Surface-class relief / special coverage rule: standard-native-filament plus shared-detail-family; global-context-shell lane only if shell files are touched unexpectedly.
• Closing validation and reviewer handoff: reviewers verify no forbidden files, no leakage, no lifecycle actions, no /admin/t, no raw IDs as visible labels, and no new persistence/assets/RBAC.
• Budget / baseline / trend follow-up: none expected.
• Review-stop questions: lane fit, hidden fixture cost, UI leakage, shell drift, action hierarchy, pack status truth.
• Escalation path: none unless shell/sidebar/topbar or RBAC becomes necessary; then stop and update spec/plan.
• Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
• Why no dedicated follow-up spec is needed: Scope is a bounded productization slice; broader link cleanup, localization, artifact lifecycle, billing, provider hardening, and support handoff remain explicit follow-ups.

Project Structure

Documentation

specs/312-customer-review-workspace-v1-completion/
├── checklists/
│   └── requirements.md
├── spec.md
├── plan.md
└── tasks.md

Source Code Likely Affected Later

apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php
apps/platform/lang/en/localization.php
apps/platform/lang/de/localization.php
apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php
apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php
apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php
apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php
apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php
apps/platform/tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php

Only if repo verification proves handoff cannot be preserved otherwise:

apps/platform/app/Filament/Resources/EnvironmentReviewResource.php
apps/platform/app/Filament/Resources/ReviewPackResource.php
apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php
apps/platform/tests/Feature/ReviewPack/ReviewPackRbacTest.php
apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php

Must Not Change

apps/platform/app/Support/OperateHub/OperateHubShell.php
apps/platform/app/Support/Tenants/TenantPageCategory.php
apps/platform/app/Support/Navigation/NavigationScope.php
apps/platform/app/Support/Navigation/WorkspaceSidebarNavigation.php
apps/platform/app/Policies/*
apps/platform/database/migrations/*
apps/platform/app/Jobs/GenerateReviewPackJob.php
apps/platform/app/Services/ReviewPackService.php

GenerateReviewPackJob and ReviewPackService should generally not change. If a test reveals a display-only field already exists but is unreachable, prefer workspace rendering changes over generation semantics changes.

Structure Decision: Use existing Laravel/Filament structure. Do not create new base folders.

Current Repo Findings

Customer Review Workspace

• CustomerReviewWorkspace exists at apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php.
• It is an undiscovered Filament page with slug reviews/workspace and a Blade view at apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php.
• It already scopes rows through EnvironmentReviewRegisterService::customerWorkspaceTenantQuery().
• It already supports explicit tenant / managed_environment_id query prefiltering as a page-level table filter.
• It already avoids remembered environment default filter.
• It already links to review detail with customer_workspace=1 and source_surface=customer_review_workspace.

Released Review Selection

• Repo-real released status is EnvironmentReviewStatus::Published.
• EnvironmentReview::scopePublished() is available.
• Latest workspace query currently uses published_at desc, generated_at desc, id desc.
• Spec 312 should test that deterministic behavior and only adjust if a global latest section needs a separate query.

Decision Summary

• Spec 308 summary content exists under EnvironmentReview.summary['governance_package']['decision_summary'].
• Existing composer also stores governance_decisions, accepted_risks, and evidence_basis_summary.
• Workspace should consume this truth and not rebuild from raw evidence payloads.

Review Pack Status

• Repo-real ReviewPackStatus values are queued, generating, ready, failed, expired.
• Existing page maps some states as available, partial, blocked, expired, unavailable.
• Spec 312 should refine customer-safe wording without adding persisted states.

Phase 0: Preparation and Guardrails

1. Confirm branch is 312-customer-review-workspace-v1-completion.
2. Confirm working tree has no uncommitted shell/sidebar/topbar or Spec 311 runtime files.
3. Re-read Spec 308 and Spec 311 artifacts before implementation.
4. Inspect any old WIP patch selectively if present; reject shell/sidebar/topbar files.
5. Confirm no migration, model, policy, OperationRun type, asset, or Review Pack generation change is needed before runtime work begins.

Phase 1: Tests First

Add or extend focused tests before implementation:

• workspace-wide behavior with active environment filter
• deterministic latest released review selection
• latest/current review section
• decision summary states: requires awareness, none, unavailable, incomplete
• legacy pre-Spec-308 review/pack fallback
• accepted-risk customer-safe display and redaction/non-leakage
• evidence basis states and no "incomplete means no decisions" confusion
• review-pack states: ready/available, missing, queued/generating, expired, failed/unavailable, evidence incomplete
• pack exists but actor lacks download capability
• filtered empty state vs global no-review state
• lifecycle action absence
• no /admin/t links
• no raw payload/fingerprint/debug/OperationRun/storage/policy leakage
• visible labels avoid raw IDs as customer-facing meaning

Phase 2: Runtime Implementation

Implement the narrowest page changes:

• Build/refine a page payload for the current/latest released review.
• Keep latest selection deterministic and workspace/filter scoped.
• Render latest released review section in existing Blade view.
• Render Decision Summary from existing Spec 308 summary content.
• Render legacy unavailable/incomplete decision summary fallback.
• Render accepted risks only from customer-safe released review truth.
• Render evidence basis state and summary text.
• Render review-pack availability state and one primary CTA.
• Hide download/open URL if actor lacks existing capability/policy.
• Improve global and filtered empty states.
• Add minimal localization keys in existing files.
• Preserve detail handoff query parameters.
• Avoid raw evidence payload display/loading.

Phase 3: Security and Leakage Pass

Verify rendered workspace HTML and hrefs:

• no fingerprints
• no raw evidence JSON
• no provider payload dumps
• no OperationRun URLs
• no storage paths
• no policy internals
• no exception internals
• no internal reason-family labels
• no visible raw IDs as labels/copy
• no /admin/t
• no operator-only lifecycle actions
• no pack mutation actions
• no cross-workspace/environment influence

Phase 4: Validation

Run focused lanes:

cd apps/platform && ./vendor/bin/sail artisan test --compact \
  tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php \
  tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php \
  tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php \
  tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php

cd apps/platform && ./vendor/bin/sail artisan test --compact \
  tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php \
  tests/Feature/EnvironmentReview/EnvironmentReviewCreationTest.php

cd apps/platform && ./vendor/bin/sail artisan test --compact \
  tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php \
  tests/Feature/ReviewPack/ReviewPackDownloadTest.php \
  tests/Feature/ReviewPack/ReviewPackRbacTest.php

Run only if shell/sidebar/topbar-adjacent files are touched unexpectedly:

cd apps/platform && ./vendor/bin/sail artisan test --compact \
  tests/Feature/Filament/PanelNavigationSegregationTest.php \
  tests/Feature/Workspaces/GlobalContextShellContractTest.php \
  tests/Feature/Filament/WorkspaceContextTopbarAndTenantSelectionTest.php

Run because rendered UI changes are expected:

cd apps/platform && ./vendor/bin/sail artisan test --compact \
  tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php

Formatting and diff:

cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
git diff --check

Phase 5: Close-out

Record close-out in this file after implementation:

# Spec 312 Close-out

## Changed Files

## Acceptance Criteria Fulfilled

## Tests Run

## Tests Not Run

## Browser Smoke

## No Migration Confirmation

## No RBAC / Policy Confirmation

## No Asset Confirmation

## No OperationRun Type Confirmation

## No New Persistence / Status Family Confirmation

## No Shell / Sidebar / Topbar Work Confirmation

## No ReviewPack Generation Semantics Change Confirmation

## Leakage Guard Confirmation

## Remaining Gaps

## Follow-up Candidates

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
None expected	N/A	N/A

Spec 312 intentionally avoids new persistence, new abstractions, new enum/status families, new taxonomies, and new frameworks. Any implementation discovery that appears to require one of these must stop and update the spec/plan before code proceeds.

Filament v5 Output Contract For Implementation Close-out

The implementation close-out must state:

1. Livewire v4.0+ compliance: expected unchanged, project currently uses Livewire 4.1.4.
2. Provider registration location: no panel provider change; Laravel 12 providers remain in apps/platform/bootstrap/providers.php.
3. Global search: no globally searchable resource should be added or changed; if a resource is touched unexpectedly, document View/Edit/global-search posture.
4. Destructive actions: no destructive actions introduced; customer-safe workspace must not render lifecycle mutations.
5. Asset strategy: no new assets; deploy filament:assets requirement unchanged.
6. Testing plan/results: record focused Feature lanes, Browser smoke result or reason not run, Pint dirty, and git diff --check.
7. Deployment impact: no env, migration, queue, scheduler, storage, or Review Pack generation semantics change expected.

Spec 312 Close-out

Changed Files

• apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
• apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php
• apps/platform/lang/en/localization.php
• apps/platform/lang/de/localization.php
• apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php
• apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php
• apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php
• specs/312-customer-review-workspace-v1-completion/spec.md
• specs/312-customer-review-workspace-v1-completion/plan.md
• specs/312-customer-review-workspace-v1-completion/tasks.md
• specs/312-customer-review-workspace-v1-completion/checklists/requirements.md

Acceptance Criteria Fulfilled

• Customer Review Workspace remains workspace-wide and keeps environment selection as a page-level filter.
• Latest released review is selected deterministically with repo-real published_at desc, generated_at desc, id desc ordering and rendered before the list.
• Decision Summary is consumed from existing Spec 308 governance package truth with customer-safe none, awareness-required, unavailable, and incomplete/fallback handling.
• Accepted risks render from released-review governance package content without internal owners, approvers, request reasons, or workflow controls.
• Evidence basis renders a customer-safe state without raw evidence payload, snapshot fingerprints, OperationRun URLs, or storage paths.
• Review Pack status maps existing queued, generating, ready, failed, expired, missing, blocked, and evidence-incomplete cases to customer-safe copy.
• Ready Review Packs show a dominant signed download CTA only when the existing actor capability allows it; otherwise the page falls back to open-review or neutral status.
• Filtered empty state distinguishes active-filter no-results from workspace-wide no released reviews and offers the existing clear-filter CTA.
• Rendered customer-safe workspace assertions cover no lifecycle actions, no pack mutation actions, no /admin/t links, and no raw/internal leakage.

Tests Run

• cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php
  Result: passed, 25 tests / 153 assertions.
• cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php tests/Feature/EnvironmentReview/EnvironmentReviewCreationTest.php
  Result: passed, 5 tests / 68 assertions.
• cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php tests/Feature/ReviewPack/ReviewPackDownloadTest.php tests/Feature/ReviewPack/ReviewPackRbacTest.php
  Result: passed, 22 tests / 93 assertions.
• cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php
  Result: passed, 1 test / 48 assertions.
• cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
  Result: passed.
• git diff --check
  Result: passed.

Tests Not Run

• Spec 311 regression lane was not run because no shell/sidebar/topbar/navigation-scope files changed.

Browser Smoke

Passed with the existing Pest browser smoke for the Environment Review detail to Customer Review Workspace handoff and back to read-only customer-safe review detail. The expected visible German copy was updated to the new Spec 312 customer-safe latest-review and Review Pack wording.

No Migration Confirmation

No migrations, tables, columns, models, or schema changes were added.

No RBAC / Policy Confirmation

No RBAC or policy files were changed. Existing Capabilities::REVIEW_PACK_VIEW, environment review visibility, workspace membership, and direct download-route authorization remain authoritative.

No Asset Confirmation

No CSS, JavaScript, image, icon pack, Vite, or Filament asset registration changes were added.

No OperationRun Type Confirmation

No OperationRun type, lifecycle, queue, scheduler, or run-notification behavior was added or changed.

No New Persistence / Status Family Confirmation

No new persisted state, enum/status family, table, column, model, or public taxonomy was introduced. Customer-safe Review Pack states are display-only mappings over existing ReviewPackStatus truth.

No Shell / Sidebar / Topbar Work Confirmation

No changes were made to OperateHubShell, TenantPageCategory, NavigationScope, WorkspaceSidebarNavigation, sidebar composition, topbar context, or route-scope contracts.

No ReviewPack Generation Semantics Change Confirmation

No changes were made to Review Pack generation, regeneration, expire behavior, storage contract, export format, or ReviewPackService generation semantics. The workspace only consumes the existing signed download URL helper for authorized ready packs.

Leakage Guard Confirmation

Focused rendered HTML assertions verify no raw evidence JSON, source fingerprints, raw OperationRun URLs, /admin/t legacy links, internal owner/approver names, internal request reasons, Generate/Regenerate/Expire actions, or lifecycle mutation actions appear in the customer-safe workspace.

Remaining Gaps

None for Spec 312 scope. Broader localization adoption, canonical query cleanup, pre-Spec-308 backfill, artifact lifecycle, billing, provider hardening, and customer approval workflow remain out of scope.

Follow-up Candidates

Use the follow-up list from the spec: Provider Connection Scope Hardening, Canonical Link / Query Cleanup, Product Truth / Docs Drift Cleanup, Review Pack backfill for pre-Spec-308 artifacts, Customer-facing Localization Adoption v1, Artifact Lifecycle & Retention, Commercial Entitlements / Billing-State Maturity, and Customer Approval Workflow.

Filament v5 Output Contract

• Livewire v4.0+ compliance: unchanged; project uses Livewire 4.1.4 and Filament 5.2.1.
• Provider registration location: no panel provider change; Laravel 12 providers remain in apps/platform/bootstrap/providers.php.
• Global search: no globally searchable resource was added or changed.
• Destructive actions: no destructive actions were introduced; customer-safe workspace renders no lifecycle mutations.
• Asset strategy: no new assets; deploy-time filament:assets posture is unchanged.
• Testing coverage: focused Feature lanes, Browser smoke, Pint dirty, and git diff --check passed as recorded above.
• Deployment impact: no env var, migration, queue, scheduler, storage, or Review Pack generation impact.