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.