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

# Feature Specification: Spec 344 - Customer Review Workspace Density & Audience Mode Polish

**Feature Branch**: `344-customer-review-workspace-density-audience-polish`  
**Created**: 2026-06-01  
**Status**: Draft  
**Type**: Productization / UX hierarchy / MSP operator workflow polish  
**Runtime posture**: UI/productization polish only. Preserve Spec 343 acknowledgement behavior and Customer Review Workspace semantics. Do not introduce new domain models, persisted truth, or status families unless repo truth proves a minimal derived view state is unavoidable (derived-only, not persisted).  
**Input**: User-provided Spec 344 draft (Codex attachment `pasted-text.txt`) + repo truth from Specs 337, 342, 343 + current `CustomerReviewWorkspace` UI.

## Spec Candidate Check *(mandatory — SPEC-GATE-001)*

- **Problem**: The Customer Review Workspace (UI-038) is now functionally strong (Specs 342–343), but visually dense. Operator decision state, customer-safe sharing state, acknowledgement state, evidence path, review pack state, accepted-risk state, disclosure rules, diagnostics, and package index compete at equal weight.
- **Today's failure**: An operator must scan too many regions before answering the first questions: “Is this review shareable?”, “What action is required now?”, “Is anything risky or blocking?”, “Where is the evidence/proof path?”, “What details can I inspect if needed?”
- **User-visible improvement**: The first screen becomes scan-first and decision-first: one Operator Summary zone with shareability + acknowledgement + primary next action + risk/findings signal, and a clear Supporting Details layer for proof/diagnostics/index.
- **Smallest enterprise-capable version**: Refactor only the existing `/admin/reviews/workspace` layout and hierarchy. Preserve all existing truth sources and actions; change ordering, grouping, and repetition only.
- **Explicit non-goals**: No new customer portal, no new persisted view state, no new domain model, no new review pack format, no new evidence generation, no new accepted-risk lifecycle semantics, no new OperationRun types, no new navigation/shell redesign, no localization project, no “legal sign-off” semantics.
- **Permanent complexity imported**: Targeted UI refactor on one page + small presenter extraction only if needed to prevent duplicated logic, plus focused Feature/Livewire tests and one bounded Browser smoke + screenshots. No migrations, no packages, no new global UI framework.
- **Why now**: Spec 343 added acknowledgement and tightened accepted-risk visibility; the page is v1-usable but now too dense for daily MSP/operator workflows. Productization polish improves operator velocity and reduces false calmness by making the next action unavoidable.
- **Why not local**: Small cosmetic changes cannot fix the decision hierarchy problem; this must be an intentional “Operator Summary first” re-layout to prevent drift and duplicated truth across cards.
- **Approval class**: Workflow Compression.
- **Red flags triggered**: Customer-safe strategic surface changes and risk of “false calmness” if hierarchy is wrong. Defense: preserve truth sources and semantics; keep diagnostics/proof as supporting details; require browser screenshots + targeted tests.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 1 | **Gesamt: 10/12**
- **Decision**: approve.

## Candidate Source And Completed-Spec Guardrail

- **Candidate source**: Directly user-provided as “Spec 344 — Customer Review Workspace Density & Audience Mode Polish” as the next slice after Spec 343.
- **Completed-spec check**: No `specs/344-*` package existed before this prep. Related Specs 337, 342, and 343 contain completed-task, validation, and/or close-out signals and are treated as historical context only (do not rewrite or normalize them).
- **Roadmap alignment**: Stays inside the “Customer Review Workspace v1 completion / productization” lane by improving operator decision hierarchy and customer-safe disclosure without creating a parallel customer portal.
- **Close alternatives deferred**:
  - Decision-based Governance Inbox follow-through (separate strategic workflow surface; defer to keep this slice UI-only on UI-038).
  - Customer-facing localization adoption (needs stable hierarchy first).
  - Provider readiness / monitoring maturity (unrelated).
  - External support desk / PSA handoff (unrelated).

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace hub (existing strategic surface UI-038) with page-level `environment_id` filter.
- **Primary Routes**:
  - `/admin/reviews/workspace` (Customer Review Workspace)
- **Data Ownership**: no new persistence; no migrations.
- **RBAC**:
  - Preserve existing membership + capability gates for view and for acknowledgement write (Spec 343).
  - Diagnostics remain capability-gated (`support_diagnostics.view`).

## UI Surface Impact *(mandatory — UI-COV-001)*

- [ ] No UI surface impact
- [x] Existing page changed
- [ ] New page/route added
- [ ] Navigation changed
- [ ] Filament panel/provider surface changed
- [ ] New modal/drawer/wizard/action added
- [x] New table/form/state added
- [x] Customer-facing surface changed
- [ ] Dangerous action changed
- [x] Status/evidence/review presentation changed
- [x] Workspace/environment context presentation changed

## UI/Productization Coverage *(mandatory)*

- **Route/page/surface**: `/admin/reviews/workspace` (`apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php` + `apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php`)
- **Current page archetype**: `docs/ui-ux-enterprise-audit/route-inventory.md` → UI-038 (Strategic Surface, repo-verified)
- **Design depth**: Strategic Surface (operator/MSP surface that produces customer-safe output)
- **Repo-truth level**: repo-verified surface; no new truth sources
- **Existing pattern reused**: Spec 342 decision-first hierarchy + Spec 343 acknowledgement card/action + existing customer-safe disclosure + existing evidence/proof layout primitives
- **New pattern required**: none; only regrouping and de-duplication + one explicit “Operator Summary” layer marker
- **Screenshot required**: yes (`specs/344-customer-review-workspace-density-audience-polish/artifacts/screenshots/`)
- **Customer-safe review required**: yes (copy + disclosure + prevent false “ready/available” duplication)
- **Dangerous-action review required**: no (no new destructive/high-impact actions; acknowledgement remains confirmed + capability-gated per Spec 343)
- **Coverage artifacts**: decide post-diff whether `docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md` needs an update; route inventory entry should remain stable.

## Cross-Cutting / Shared Pattern Reuse *(mandatory)*

- **Cross-cutting feature?**: yes.
- **Interaction classes**: status messaging, action hierarchy, proof/evidence disclosure, diagnostics collapse, accepted-risk summary.
- **Shared paths reused**:
  - Existing customer-safe disclosure language and copy discipline from Specs 342–343 (no legal/compliance certification wording).
  - Existing badge/status primitives (no ad-hoc “ready/available” duplication).
  - Existing acknowledgement action semantics from Spec 343 (capability + confirmation + audit).
- **Deviations**: none intended. If a new presenter/state helper is introduced to reduce duplicated UI logic, it must remain page-local and derived-only.

## OperationRun UX Impact *(mandatory)*

N/A - no OperationRun creation/completion/dedupe semantics are introduced or changed in this slice.

## Provider Boundary / Platform Core Check *(mandatory)*

N/A - no provider/platform shared boundary is changed.

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: no.
- **New persisted entity/table/artifact?**: no.
- **New abstraction?**: no new framework. Optional: extract a page-local derived “summary view state” helper only if it reduces duplicated truth and keeps copy/status consistent.
- **New enum/status family?**: no. All displayed states remain derived from existing review/pack/evidence/acknowledgement/accepted-risk truth.
- **Alternative intentionally rejected**: audience-mode toggle framework, separate customer portal page, new review readiness engine, new accepted-risk workflow surface.

## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*

- **Test purpose / classification**: Feature/Livewire for action visibility + RBAC + disclosure defaults; Browser for scan-first hierarchy and “acknowledgement is visible before supporting details” on a strategic surface.
- **Validation lane(s)**: confidence + browser.
- **Planned validation commands** (later implementation):
  - `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec343CustomerReviewAttestationAcceptedRiskTest.php --compact`
  - `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec343CustomerReviewAttestationAcceptedRiskSmokeTest.php --compact`
  - `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec344CustomerReviewWorkspaceDensityTest.php --compact`
  - `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec344CustomerReviewWorkspaceDensitySmokeTest.php --compact`
  - `cd apps/platform && ./vendor/bin/sail pint --dirty`
  - `git diff --check`

## User Scenarios & Testing *(mandatory)*

### User Story 1 — Understand the main decision quickly (Priority: P1)

An MSP/operator opens Customer Review Workspace and immediately sees shareability status, acknowledgement status, and the one primary next action without scanning multiple equal-weight cards.

**Independent proof**: browser smoke + screenshots showing the Operator Summary zone in realistic fixtures.

### User Story 2 — Acknowledgement appears before supporting details (Priority: P1)

If acknowledgement is required, it appears in the primary decision area (or directly beneath it) and never below secondary proof/flow sections.

**Independent proof**: Livewire test asserts acknowledgement action is present and visible in the Operator Summary; browser smoke confirms hierarchy.

### User Story 3 — Supporting details remain available but secondary (Priority: P2)

Evidence path, review pack state, accepted-risk detail lists, disclosure rules, diagnostics, and the package index remain accessible but are visually secondary and/or progressively disclosed.

**Independent proof**: browser smoke shows details as secondary/collapsed; Livewire test confirms diagnostics remain capability-gated.

## Functional Requirements

- **FR-001**: The page must have two clear layers:
  1) **Operator Summary** (decision + acknowledgement + risks/findings + primary next action)
  2) **Supporting Details** (proof/evidence path + pack state + accepted risks + diagnostics + index)
- **FR-002**: Acknowledgement must appear in (1) when required.
- **FR-003**: Repetitive “ready/available/no action needed” blocks must be reduced, grouped, or demoted so they do not compete with the true pending action.
- **FR-004**: Accepted-risk and findings signals must not be duplicated in multiple equal-weight regions without distinct purpose.
- **FR-005**: Diagnostics remain collapsed/secondary by default and capability-gated.
- **FR-006**: Environment filter remains a local page filter and stays visible; no new “topbar-as-filter” guidance is introduced.

## Non-Functional Requirements

- Page render remains DB-only: no Graph/provider calls during UI render.
- Preserve Filament v5 + Livewire v4.0+ compliance.
- Keep panel provider registration unchanged in `apps/platform/bootstrap/providers.php`.
- Avoid new frontend assets; if any asset registration becomes necessary, document `php artisan filament:assets`.

## Out Of Scope

- No new portal routes, no audience-mode toggle framework, no new persisted preferences.
- No new review readiness engine, no new accepted-risk workflow surface, no lifecycle or taxonomy rewrite.
- No changes to acknowledgement semantics introduced by Spec 343 (capability/confirmation/audit behavior stays intact).

## Acceptance Criteria

- [ ] AC-001 Operator Summary answers (in order): shareability, acknowledgement, primary next action, blockers/risks, and latest review context.
- [ ] AC-002 If acknowledgement is required, the action is visible before supporting details (no scroll needed).
- [ ] AC-003 Duplicate “ready/available/no action needed” cards are reduced or grouped so the pending action stands out.
- [ ] AC-004 Evidence path remains visible but secondary; diagnostics remain collapsed/secondary.
- [ ] AC-005 Environment filter remains visible and local; the page does not imply global context.
- [ ] AC-006 Spec 343 acknowledgement behavior is preserved end-to-end.
- [ ] AC-007 Tests pass (targeted Spec 343 + Spec 344 feature + browser lanes).

## Success Criteria

- An operator can answer “what do I do now?” within a few seconds on first load.
- Customer-safe claims remain truthful and do not become “green noise”.
- Supporting proof paths remain accessible without competing as primary decision content.

## Assumptions

- The current strategic surface remains `UI-038 /admin/reviews/workspace` and uses the existing page class + Blade view.
- Spec 343 acknowledgement is already repo-real and covered by targeted tests.
- No additional backend truth is needed to improve hierarchy (UI-only slice).

## Open Questions

- OQ-001: Should the “Supporting Details” layer be purely collapsed-by-default, or should it remain visible but visually demoted? (Decision belongs to implementation with screenshots; either is acceptable if diagnostics remain secondary.)

## Spec Artifacts *(required for this package)*

- `specs/344-customer-review-workspace-density-audience-polish/spec.md`
- `specs/344-customer-review-workspace-density-audience-polish/plan.md`
- `specs/344-customer-review-workspace-density-audience-polish/tasks.md`
- `specs/344-customer-review-workspace-density-audience-polish/checklists/requirements.md`
- `specs/344-customer-review-workspace-density-audience-polish/artifacts/screenshots/`

## Follow-Up Spec Candidates

- Decision-based Governance Inbox follow-through (separate surface; keep numbering flexible).
- Customer Review External Portal v1 (separate customer-facing surface, not the operator workspace).
- Customer Review Mode Toggle (only if one page cannot serve operator vs customer-summary needs).
- Review Package Index productization (timeline/history focus).
- Accepted Risk lifecycle detail surface (only if accepted-risk records need their own workflow).