TenantAtlas/specs/344-customer-review-workspace-density-audience-polish/plan.md

Implementation Plan: Spec 344 - Customer Review Workspace Density & Audience Mode Polish

Branch: 344-customer-review-workspace-density-audience-polish | Date: 2026-06-01 | Spec: specs/344-customer-review-workspace-density-audience-polish/spec.md
Input: User-provided Spec 344 draft (Codex attachment pasted-text.txt) + repo truth from Specs 337, 342, 343.

Summary

Improve the Customer Review Workspace (UI-038) as a daily MSP/operator surface by reducing density and restoring decision hierarchy:

1. Operator Summary first: shareability + acknowledgement + primary next action + risk/findings signal.
2. Supporting details second: evidence/proof path + review pack state + accepted risks + diagnostics + package index.

This slice is UI/productization polish only:

• preserve all semantics from Specs 342–343
• no new persistence or status families
• no new routes or navigation changes
• no Graph/provider calls during render

Technical Context

• Language/Version: PHP 8.4.15, Laravel 12.x.
• UI: Filament v5 + Livewire v4 (no Livewire v3 APIs).
• Panel providers: remain registered in apps/platform/bootstrap/providers.php (no changes expected).
• Storage: PostgreSQL (no migrations expected).
• Testing: Pest Feature/Livewire tests + one bounded Pest Browser smoke test for this strategic surface.
• Assets: no new global assets expected; prefer Filament primitives and Tailwind utilities already in the stack.

UI / Surface Guardrail Plan

• Guardrail scope: material change to an existing strategic customer-safe review surface (UI-038).
• Primary surface:
  • apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
  • apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php
• New/changed surface elements:
  • explicit “Operator Summary” zone (layout + grouping)
  • reordering so acknowledgement sits inside the primary decision area when required
  • de-duplication and compression of “ready/available/no action needed” signals
• Disclosure defaults: diagnostics remain collapsed/secondary and capability-gated (support_diagnostics.view).
• One primary next action: preserve exactly one dominant next action in the Operator Summary; demote secondary navigation/inspect links.
• UI audit artifacts: decide post-diff whether docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md needs updating; route inventory entry (UI-038) should remain stable.

Repo-Truth-First Execution Rule

Before any refactor, confirm the current runtime surface inventory:

• which cards/sections exist today and what they mean (no invented semantics)
• where acknowledgement, accepted-risk, evidence path, review pack status, disclosure rules, and diagnostics currently render
• which sections are redundant “green noise” vs required evidence/proof state

Implementation Phases

Phase 1 — Baseline Inventory + Before/After Proof

• Capture baseline screenshots for the current hierarchy (pre-change).
• Record a short inventory note in the PR description (later), not as a new framework or test snapshot.

Phase 2 — Layout/Hiearchy Refactor (UI-only)

• Implement the two-layer structure: Operator Summary vs Supporting Details.
• Move acknowledgement into the Operator Summary hierarchy when required.
• Group or demote readiness-only cards so they do not compete with the pending action.
• Preserve environment filter semantics and visibility (local page filter, not global context).
• Preserve customer-safe wording and avoid “legal/compliance certification” phrasing.

Phase 3 — Preserve Spec 343 Semantics

• Acknowledgement remains:
  • capability-gated
  • confirmation-gated
  • auditable
  • behavior-identical (only placement changes)

Phase 4 — Tests (Pest)

• Keep Spec 343 tests passing; update only assertions that intentionally depend on hierarchy markers.
• Add Spec 344 Feature/Livewire tests focusing on:
  • Operator Summary markers exist
  • acknowledgement action visibility in the primary zone when required
  • diagnostics remain capability-gated and collapsed/secondary
  • environment filter remains visible and page-local
• Add one Spec 344 Browser smoke to prove scan-first hierarchy + screenshots.

Phase 5 — UI Coverage Artifacts (post-diff decision)

• If the layout materially changes what the UI-006 page report describes, update:
  • docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md
• Otherwise record a concise “no update needed” note in the active feature PR close-out entry.

Deployment / Ops Impact

• Env vars: none.
• Migrations: none expected.
• Queues/scheduler: none.
• Storage/volumes: none.
• Filament assets: not expected; if any registered assets are introduced, include cd apps/platform && php artisan filament:assets in deployment/release steps.