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
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• 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).