TenantAtlas/specs/258-customer-review-productization/quickstart.md

Quickstart — Customer Review Workspace Productization v1

Preconditions

• Docker is running and the Sail stack for apps/platform is available.
• The feature remains inside the existing Laravel monolith and existing admin plane.
• The canonical entry surface already exists at /admin/reviews/workspace; this slice productizes it instead of adding a new shell.
• No new persistence, no review publishing engine, no remediation flow, no new identity plane, and no heavy new asset strategy are part of this work.

Intended Implementation Order

1. Review the current workspace page, Blade intro, and feature/browser tests so the productization pass stays inside the existing reviews family.
2. Tighten the workspace page wording, disclosure order, and explicit access/absence/unavailable states using the existing localization namespace in ../../apps/platform/lang/en/localization.php and ../../apps/platform/lang/de/localization.php.
3. Tighten the released-review detail flow in ../../apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php under the existing customer_workspace context flag so it remains read-only and customer-safe.
4. Reuse the current TenantReview.summary, FindingException, ArtifactTruthPresenter, review-pack, and evidence seams to improve accountability/proof framing without creating a new presenter or persistence layer.
5. Align secondary proof and pack affordances so the workspace still has one dominant next action and optional proof paths show explicit unavailable or expired states when blocked.
6. Reuse the shared audit pipeline for workspace access, review access, proof access, and pack download moments, adding only bounded action IDs if the current registry does not already cover the required events.
7. Expand the focused tests/Feature/Reviews/* family and keep the existing browser smoke as the only browser proof for this slice.
8. Run the targeted tests and Pint after implementation.

Targeted Validation Commands (after implementation)

• export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php
• export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Reviews/CustomerReviewWorkspaceNavigationContextTest.php tests/Feature/TenantReview/TenantReviewUiContractTest.php tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/ReviewPack/ReviewPackDownloadTest.php tests/Feature/ReviewPack/ReviewPackResourceTest.php tests/Feature/Evidence/EvidenceSnapshotResourceTest.php tests/Feature/Evidence/EvidenceSnapshotAuditLogTest.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

Planned Smoke Checklist (after implementation)

1. Sign in to /admin as a readonly-capable actor with workspace scope and open /admin/reviews/workspace.
2. Confirm the page stays calm and customer-safe: current governance record first, no mutation actions, and explicit absence/unavailable states where appropriate.
3. Launch the workspace from an existing released review or related context and confirm tenant prefilter and customer-safe drilldown continuity still hold.
4. Open the released review and confirm the detail stays read-only, highlights findings/accepted-risk/accountability/proof clearly, and does not expose publish/refresh/create-next/regenerate/archive controls.
5. Use the pack action for a tenant with a current pack and confirm the existing signed download path still works; for tenants without a current or still-valid pack, confirm the UI shows a truthful unavailable or expired state instead of a generation action.
6. Follow an optional proof path and confirm the route is capability-gated, auditable when required, and explicit when proof is unavailable or redacted.
7. Attempt an explicit out-of-scope tenant target and confirm the result remains not found without leaking tenant presence.

Notes

• Filament v5 already runs on Livewire v4 in this repo.
• Panel providers remain registered through ../../apps/platform/bootstrap/providers.php; this slice does not add or move providers.
• No new globally searchable resource or search scope is part of this productization pass.
• No destructive action belongs on the workspace surface or the customer-workspace drilldown. If implementation accidentally exposes one, it must stay out of scope and use confirmation.
• No new registered asset bundle is expected. If future implementation unexpectedly registers a Filament asset, deployment still requires cd apps/platform && php artisan filament:assets.
• This remains a customer-safe consumption/productization slice only. Review creation, publication, regeneration, remediation, and broader portal behavior stay outside this spec.

Implementation Close-Out

• Completed: 2026-04-30
• Targeted feature checks: PASS
• Browser smoke: PASS, covering /admin/reviews/workspace, released-review row visibility, customer-safe pack/proof labels, workspace-to-detail handoff, and released-governance-record detail text.
• Formatting: PASS via Pint dirty-file run.
• Audit result: used bounded additive action IDs only for the confirmed gaps (customer_review_workspace.opened, evidence_snapshot.opened); reused existing tenant-review open and review-pack download audit events with source_surface=customer_review_workspace.
• Global-search result: unchanged; this implementation added no global-search surface.
• Assets / deploy result: unchanged; no new Filament assets were registered.