TenantAtlas/specs/326-customer-review-workspace-v1-productization/spec.md

Feature Specification: Spec 326 - Customer Review Workspace v1 Productization

Feature Branch: 326-customer-review-workspace-v1-productization Created: 2026-05-18 Status: Implemented Type: Runtime UI productization / customer-safe review consumption / decision-first surface Runtime posture: Narrow runtime UI implementation. Repo-based. No invented backend foundation. Input: User-provided full Spec 326 draft, corrected from an earlier Pattern Library assumption.

Dependencies And Historical Context

Depends on:

• Spec 312 - Customer Review Workspace v1 Completion, treated as completed/historical runtime foundation and not rewritten.
• Spec 314 - Workspace Hub Navigation Context Contract.
• Spec 315 - Environment CTA Explicit Filter Contract.
• Spec 316 - Workspace Hub Clear Filter Contract.
• Spec 317 - Legacy Tenant / Environment Context Cleanup.
• Spec 318 - Admin Surface Scope & Shell Context Audit.
• Spec 319 - Environment-Owned Surface Routing & Shell Context Contract.
• Spec 320 - Workspace-Owned Analysis Surface Registration & Shell Cutover.
• Spec 321 - Alerts / Audit Log Environment Filter Contract Decision.
• Spec 322 - Browser No-Drift Regression Guard.
• Spec 325 - Screenshot-Anchored Strategic Target Images.

Repo truth adjustment: the user draft intentionally starts from Spec 325 target direction, but the repository already has Spec 312 and runtime Customer Review Workspace work. Spec 326 must build on that existing page and tests instead of restating it as greenfield. Spec 325 premium references are visual calibration only; they are not runtime truth for metrics, actions, states, RBAC, audit, OperationRun, workspace/environment scope, evidence, or review-pack behavior.

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: Customer Review Workspace is repo-real and already customer-safe in places, but it still needs a v1 productization pass that makes readiness, evidence path, review-pack state, accepted risks, follow-ups, and hidden diagnostics feel like one polished customer-safe review workspace.
• Today's failure: A reviewer can see current review and review-pack facts, but the first viewport may still read as an admin list plus panels rather than a decision-first answer to "Is this ready to share, what needs attention, and what proof backs it?" Spec 325 target visuals are not yet implemented as a repo-truth-bounded runtime surface.
• User-visible improvement: Customer reviewers, auditors, account managers, and MSP operators get a polished, read-first workspace surface that clearly separates readiness, evidence, accepted risks, review-pack availability, follow-ups, and diagnostics.
• Smallest enterprise-capable version: Productize only CustomerReviewWorkspace and its existing Blade view, using existing models/services/policies and optional ?environment_id= filter. Add no portal, migrations, new backend engines, new domain states, new packages, or new external sharing.
• Explicit non-goals: No external customer portal, external auth, invitation links, email delivery, PSA handoff, new review engine, new evidence backend, new review-pack backend, AI summarization, billing/entitlement rebuild, broad review-page redesign, Governance Inbox redesign, Evidence Overview redesign, Operations Hub redesign, migrations, packages, env vars, queues, scheduler, storage, or deployment asset changes unless repo analysis proves a narrow exception.
• Permanent complexity imported: Feature-local page composition, feature tests, browser smoke coverage, and a repo-truth map. No new persisted truth, public abstraction, enum/status family, cross-domain UI framework, or backend service foundation.
• Why now: Spec 325 produced screenshot-anchored target direction for strategic surfaces; Customer Review Workspace is the first high-value runtime productization lane and the clearest sellability surface. Specs 314-322 stabilized workspace/environment context contracts.
• Why not local: A label-only patch would not solve the first-read review consumption problem. A portal or framework would overbuild. The narrow correct slice is a repo-truth-bounded productization pass on the existing workspace page.
• Approval class: Workflow Compression.
• Red flags triggered: Cross-surface customer-safe review presentation and visual productization. Defense: scope is bounded to one existing page, existing truth sources, existing policies, existing routes, and explicit no-new-backend constraints.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 12/12
• Decision: approve.

Candidate Source And Completed-Spec Guardrail

• Candidate source: Direct user-provided manual promotion for Spec 326, aligned with the P1 Customer Review Workspace v1 Completion lane in docs/product/spec-candidates.md and the Customer Review Workspace target brief from Spec 325.
• Completed-spec check: No specs/326-* package existed before generation. Related Specs 312 and 314-325 contain completed/historical preparation or implementation signals and must remain unchanged by this preparation.
• Close alternatives deferred: Governance Inbox Decision-First Workbench, Operations Hub Decision-First Workbench, Evidence/Audit disclosure, Environment Dashboard/Baseline Compare, and Restore Safety Workflow productization are follow-up specs 327-331, not hidden scope.
• Smallest viable implementation slice: Existing Customer Review Workspace only, including layout, derived display payloads, RBAC-aware actions, environment filter behavior, hidden diagnostics, and targeted tests/browser smoke.

Spec Scope Fields (mandatory)

• Scope: workspace canonical-view customer-safe review consumption hub, optionally filtered by canonical environment_id.
• Primary Routes:
  • Existing route: /admin/reviews/workspace.
  • Existing page class: apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php.
  • Existing view: apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php.
• Data Ownership:
  • Review truth: EnvironmentReview, EnvironmentReviewStatus::Published, published_at, summary, current_export_review_pack_id.
  • Evidence truth: EvidenceSnapshot, EvidenceSnapshotItem, review summary evidence/completeness fields.
  • Review Pack truth: ReviewPack, ReviewPackStatus, file path/disk, expiry, ReviewPackService download URL.
  • Accepted risk truth: FindingException / review governance-package accepted-risk summary.
  • Finding/follow-up truth: Finding, FindingException, review decision-summary entries where repo-supported.
  • Execution proof: existing OperationRun relations only as secondary proof links when already present and authorized.
  • Audit truth: AuditLog and existing WorkspaceAuditLogger page-open event.
• RBAC:
  • Workspace membership required.
  • Managed-environment entitlement required where environment data is rendered.
  • Existing capabilities and policies remain authoritative for review, evidence, review-pack, accepted-risk, findings, export/download, and diagnostics visibility.
  • Non-member or cross-workspace environment access remains deny-as-not-found.
  • Member with missing capability receives existing policy semantics; unauthorized actions must be hidden or unavailable without leaking sensitive details.

For canonical-view specs:

• Default filter behavior when tenant-context is active: Clean /admin/reviews/workspace remains workspace-wide and must not inherit remembered environment context, Filament tenant context, session table filters, or legacy query aliases.
• Explicit entitlement checks preventing cross-tenant leakage: ?environment_id= must resolve through the current workspace and actor entitlement; cross-workspace or inaccessible IDs return 404/no-access.

UI Surface Impact (mandatory - UI-COV-001)

Does this spec add, remove, rename, or materially change any reachable UI surface?

• 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 when UI Surface Impact is not "No UI surface impact"; otherwise write N/A - no reachable UI surface impact plus rationale)

• Route/page/surface: /admin/reviews/workspace, CustomerReviewWorkspace, customer review workspace Blade view.
• Current or new page archetype: Customer Workspace / Strategic Surface, matching docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md.
• Design depth: Strategic Surface.
• Repo-truth level: repo-verified page and foundational models; individual target visual elements must be classified in repo-truth-map.md.
• Existing pattern reused: Filament Page, Filament Sections, Filament table, badges, existing workspace hub environment filter chip, existing review-pack download route, existing page report and target brief.
• New pattern required: no new runtime pattern framework; page-local composition only.
• Screenshot required: yes, browser smoke screenshots under specs/326-customer-review-workspace-v1-productization/artifacts/screenshots/.
• Page audit required: no new full audit unless implementation materially changes the route inventory; update coverage registry or record checked no-impact for docs if the implementation remains on the same route.
• Customer-safe review required: yes. Raw diagnostics and internal metadata are hidden by default.
• Dangerous-action review required: no new dangerous action; verify no destructive/generation/regeneration/publish actions are introduced on the customer-safe default surface.
• Coverage files updated or explicitly not needed:
  • docs/ui-ux-enterprise-audit/route-inventory.md
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md
  • docs/ui-ux-enterprise-audit/page-reports/...
  • docs/ui-ux-enterprise-audit/strategic-surfaces.md
  • docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
  • docs/ui-ux-enterprise-audit/unresolved-pages.md
  • N/A - no reachable UI surface impact
• Coverage decision for implementation: implementation must either update the UI coverage registry for the material surface change or document in this spec's close-out why the existing UI-006 report and Spec 325 target artifacts remain sufficient.
• Implementation close-out coverage decision: no separate UI coverage registry update is required for Spec 326. The reachable route, navigation entry, panel/provider registration, page archetype, and strategic-surface identity remain the existing UI-006 Customer Review Workspace surface. Spec 326 changes the runtime composition on that route and records proof in this active spec package, repo-truth-map.md, tests, and screenshot artifacts; Spec 325 remains visual calibration, not runtime truth.

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes.
• Interaction class(es): customer-safe review consumption, readiness/status messaging, action links, evidence/report viewers, review-pack state, accepted-risk summaries, diagnostics disclosure.
• Systems touched: CustomerReviewWorkspace, customer-review-workspace.blade.php, EnvironmentReviewRegisterService, ReviewPackService, WorkspaceHubEnvironmentFilter, WorkspaceHubFilterStateResetter, existing review/evidence/pack/exception resources and policies.
• Existing pattern(s) to extend: existing Customer Review Workspace payload helpers, workspace hub filter chip partial, ArtifactTruthPresenter where already used, ReviewPackStatus, EnvironmentReviewStatus, EvidenceSnapshotStatus, FindingException status/validity truth, existing localization structure, existing audit logger.
• Shared contract / presenter / builder / renderer to reuse: reuse existing services and enums; do not introduce a new customer-review presenter framework unless implementation proves the current page-local helpers cannot stay bounded.
• Why the existing shared path is sufficient or insufficient: Existing paths provide truth and authorization, but current composition still needs decision-first hierarchy and customer-safe disclosure polish. A page-local derived payload is sufficient for v1.
• Allowed deviation and why: bounded page-local layout/view helper changes are allowed. New shared UI/status frameworks are not allowed.
• Consistency impact: Labels, badges, actions, and links must stay aligned with existing review, evidence, review-pack, and operation vocabulary. No alternate status taxonomy may become product truth.
• Review focus: Verify no fake metrics, no false green, no raw diagnostics by default, no unauthorized actions, no shell-scope regression, and no duplicate local semantics replacing existing truth.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: secondary link semantics only if repo-supported; no new OperationRun creation, queueing, completion, dedupe, or lifecycle behavior.
• Shared OperationRun UX contract/layer reused: existing operation links/support surfaces only; if an operation proof link is shown, it must use existing OperationRunLinks or existing resource routes and authorization.
• Delegated start/completion UX behaviors: N/A - no operation start.
• Local surface-owned behavior that remains: show proof availability/unavailability in the evidence path only.
• Queued DB-notification policy: N/A.
• Terminal notification path: unchanged.
• Exception required?: none.

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: no new provider seam; page consumes existing TenantPilot review/evidence truth.
• Boundary classification: platform-core customer review consumption over existing tenant-managed environment artifacts.
• Seams affected: display of review, evidence, review-pack, accepted-risk, finding/follow-up, and operation proof links.
• Neutral platform terms preserved or introduced: workspace, environment filter, customer review, readiness, evidence path, review pack, accepted risk, decision trail, operation proof.
• Provider-specific semantics retained and why: existing Intune/Microsoft terms may appear only inside already customer-safe review/evidence content. Do not surface raw provider IDs, Graph payloads, tenant aliases, or provider diagnostics by default.
• Why this does not deepen provider coupling accidentally: no Graph calls, no provider connection changes, no provider taxonomy changes, and no new persisted provider-shaped terms.
• Follow-up path: provider-readiness and environment-dashboard productization remain separate target lanes.

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Customer Review Workspace page	yes	Native Filament page plus existing Blade composition	customer-safe review, evidence/report, review-pack, status messaging	page, URL-query, table state	no	Existing route only
Header / scope area	yes	Filament section / Blade	workspace/environment context presentation	page, URL-query	no	Must keep Workspace shell ownership
Main decision card	yes	Filament section/cards/badges	status/readiness messaging	page payload	no	Derived labels only, no new persisted state
Evidence path / review-pack / accepted-risk panels	yes	Filament sections/cards/badges	evidence/report viewer, artifact delivery	page payload	no	Raw diagnostics hidden
Customer-safe findings/follow-ups	yes	Filament table/list/card pattern	decision/finding follow-up	page payload	no	Use existing decision summary/finding exception truth where repo-supported
Diagnostics disclosure	yes	collapsed/progressive disclosure only	support/raw detail	page payload/action visibility	no	Authorized and collapsed by default

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Customer Review Workspace	Primary Decision Surface for customer-safe review consumption	Reviewer decides whether a review can be shared or needs follow-up	readiness state, reason, impact, evidence freshness, accepted-risk state, review-pack availability, one next action	review detail, evidence snapshot, review pack, decision trail, operation proof, diagnostics	Primary because it is the customer-safe hub	Review consumption, not raw admin operations	Removes cross-page reconstruction
Evidence path panel	Tertiary Evidence / Diagnostics	Reviewer checks proof path after the primary decision	evidence snapshot, review pack, decision trail, accepted-risk records, operation proof availability	raw/support details only behind disclosure and authorization	Secondary proof area, not primary decision	Evidence-first review trust	Separates proof from payloads
Review-pack panel	Secondary Context / Artifact delivery	Reviewer decides whether export/share artifact is usable	pack state, last generated, snapshot used, export availability	operation proof if already linked	Artifact owner remains existing pack truth	Export-aware review consumption	Avoids guessing artifact readiness

Audience-Aware Disclosure (mandatory when operator-facing surfaces are changed)

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Customer Review Workspace	customer-read-only, MSP operator, auditor/account manager	readiness, reason, impact, evidence freshness, review-pack state, accepted-risk summary, safe follow-ups	collapsed and secondary if present	raw payloads, provider diagnostics, fingerprints, internal exception traces, raw OperationRun payloads	open/download review pack when ready; otherwise open review or follow the repo-real next action	raw diagnostics, generation/publish/destructive actions, internal metadata	main card states status once; panels add proof/source
Diagnostics disclosure	operator/support only where authorized	unavailable/collapsed indicator only	run metadata, export artifact detail, raw metadata if authorized	raw/support details behind explicit disclosure	view proof or close disclosure	default hidden	no diagnostic text in default decision card

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Customer Review Workspace	Workbench / Review Workspace	Customer-safe decision-first hub	Open/download review pack or open review	Explicit primary CTA	no fake row-click	right-side/contextual panels and neutral links	none	/admin/reviews/workspace	existing review/evidence/pack routes	workspace plus optional environment chip	Customer reviews	readiness, evidence, review pack, accepted risks, follow-ups	none
Evidence path panel	Detail / Evidence	Inspect proof path	contextual proof links only when authorized	explicit links	N/A	panel body	none	same page	existing evidence/operation routes if available	source/proof labels	Evidence path	available/unavailable/stale/requires refresh	none
Diagnostics disclosure	Diagnostics / Support Raw	Inspect internal proof after explicit open	disclosure component	N/A	collapsed area	none	same page	existing operation/report routes if available	authorized-only label	Diagnostics	collapsed status only	none

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Customer Review Workspace	Customer reviewer / auditor / MSP operator	Consume review and decide share/follow-up readiness	Workspace review hub	Is this review ready to share, what needs attention, and what evidence backs it?	readiness state, reason, impact, evidence freshness, accepted risks, review-pack state, follow-ups, scope	raw metadata, raw payloads, internal exception traces, operation diagnostics	review readiness, evidence freshness, accepted-risk review, export/share readiness, follow-up priority	read-only by default	open/download pack, open review, review accepted risks/evidence where existing and authorized, clear filter	none introduced

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no.
• New persisted entity/table/artifact?: no. repo-truth-map.md is a preparation artifact, not runtime truth.
• New abstraction?: no public abstraction. Page-local private helpers are allowed only when they reduce Blade complexity.
• New enum/state/reason family?: no domain state. Display states must be derived from existing EnvironmentReviewStatus, EnvironmentReviewCompletenessState, ReviewPackStatus, EvidenceSnapshotStatus, FindingException state/validity, and existing summary payloads.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: The customer-safe workspace needs a decision-first runtime surface that consumes existing truth without making false readiness or export claims.
• Existing structure is insufficient because: Current page foundations do not fully match Spec 325's premium, right-side proof/detail direction and must classify each visible element as repo-backed or unavailable.
• Narrowest correct implementation: Refactor the existing page layout and derived payloads, bind to existing sources, hide diagnostics, and add targeted tests/browser smoke.
• Ownership cost: Feature-local layout/payload tests and browser smoke. No durable backend model or new framework cost.
• Alternative intentionally rejected: new portal, new review-pack engine, new evidence backend, new readiness status machine, broad design-system implementation, or cross-surface pattern library.
• Release truth: current-release runtime UI productization over existing review/evidence/review-pack foundations.

Compatibility posture

This feature assumes pre-production runtime posture. Backward compatibility, historical aliases, migration shims, dual-write logic, and legacy customer portal routes are out of scope. Existing legacy query aliases (tenant, tenant_id, managed_environment_id, environment, tenant_scope, tableFilters) must not be supported for Customer Review Workspace filtering.

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

• Test purpose / classification: Feature, Filament/Livewire, Browser. Existing related Unit coverage may remain unchanged unless implementation touches pure helpers.
• Validation lane(s): confidence plus browser for critical customer-safe UI/scope smoke.
• Why this classification and these lanes are sufficient: The change is a user-facing Filament/Livewire page productization with RBAC, scope, and disclosure behavior. Feature tests prove data/scope/action rules; browser smoke proves shell/filter/reload/disclosure layout behavior.
• New or expanded test families: tests/Feature/Reviews/* additions and tests/Browser/Spec326CustomerReviewWorkspaceProductizationSmokeTest.php.
• Fixture / helper cost impact: reuse existing review/evidence/pack/finding helpers in tests/Pest.php; do not widen expensive defaults.
• Heavy-family visibility / justification: browser addition is explicit and named for Spec 326.
• Special surface test profile: global-context-shell plus customer-safe disclosure.
• Standard-native relief or required special coverage: special coverage required for environment filter, clear/reload, diagnostics default-hidden, and browser screenshot artifacts.
• Reviewer handoff: confirm hidden raw diagnostics, RBAC action hiding, no false green, workspace-wide clean entry, canonical filter, clear filter, and cross-workspace guard.
• Budget / baseline / trend impact: no expected material lane-cost shift beyond one targeted browser smoke.
• Escalation needed: document-in-feature if browser coverage becomes too expensive or requires fixture broadening.
• Active feature PR close-out entry: Smoke Coverage.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Reviews tests/Feature/Navigation/WorkspaceHubEnvironmentFilterContractTest.php tests/Feature/Navigation/WorkspaceHubClearFilterContractTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Browser/Spec326CustomerReviewWorkspaceProductizationSmokeTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test --filter='CustomerReviewWorkspace|WorkspaceHub|EnvironmentFilter|ClearFilter|LegacyTenant|Spec322' --compact
  • cd apps/platform && ./vendor/bin/sail pint --dirty
  • git diff --check

Summary

Productize the existing Customer Review Workspace into a customer-safe, decision-first review consumption surface.

The page must answer:

Is this review ready to share, what needs attention, and what evidence backs it?

It must be customer-safe, read-only by default, decision-first, evidence-backed, review-pack aware, accepted-risk aware, scope-clear, export-aware, and diagnostics-secondary.

This spec must not create a public/external customer portal. It improves the existing workspace-scoped Customer Review Workspace surface.

Product Context

TenantPilot is a governance-of-record platform. Its core value is turning tenant state, drift, reviews, evidence, accepted risks, and operation outcomes into understandable decisions and proof. Customer Review Workspace is a key sellability surface because it lets MSPs and customers consume review outcomes without navigating raw OperationRuns, logs, technical tables, or internal operator pages.

Spec 325 target direction calibrates the experience toward a premium enterprise shell, decision card first, visible evidence path, right-side detail/decision panel, customer-safe copy, raw diagnostics hidden by default, and a dense but calm product surface. Spec 325 images are not proof of real metrics/actions/states.

Problem Statement

The current Customer Review Workspace is repo-real and already has strong foundations, but v1 productization remains incomplete until the default experience clearly frames readiness, evidence freshness, review-pack state, accepted risks, follow-ups, scope, and diagnostics disclosure.

Likely current gaps to verify during implementation:

• Review status may be visible but not framed as readiness with reason and impact.
• Evidence freshness/path may exist but not be first-class.
• Review Pack state may be present but not productized as export/share readiness.
• Accepted risks may be summarized but not with expiring/expired/pending/customer-safe follow-up clarity where repo-supported.
• Findings/follow-ups may still require interpretation from decision-summary or finding exception sources.
• Default content may not clearly separate customer-safe content from internal diagnostics.
• Scope between workspace-wide and environment-filtered view must remain explicit.
• Raw diagnostics must stay collapsed/secondary by default.
• No generic "Healthy", "Ready", "Complete", or green success state may be shown unless repo-backed proof supports it.

Product Decision

Customer Review Workspace v1 is a workspace-scoped customer-safe review consumption hub.

It may be filtered by Environment only through:

?environment_id={id}

When filtered:

• shell remains Workspace-only
• a visible Environment filter chip appears
• clear filter returns to the clean workspace-wide Customer Review Workspace

It is not an Environment-owned page, not a public customer portal, not a raw review admin table, and not a full GRC tool.

Follow-up Premium Layout Alignment (2026-05-18)

Spec 326 remains the active implementation scope. The follow-up alignment sharpens the existing runtime UI against the Spec 325 premium target direction without creating a new spec or backend surface.

The implementation must:

• keep /admin/reviews/workspace as the only route in scope;
• replace the verbose intro with a compact customer-safe review package header;
• remove platform-context tenant wording from the Customer Review Workspace runtime copy;
• render a dense main/aside workbench layout, with the main column owning the review decision and the aside owning evidence, review-pack, accepted-risk, and disclosure proof;
• keep one dominant primary action in the main decision card;
• keep diagnostics collapsed and raw/support detail hidden by default;
• keep the existing table as secondary Review package index context;
• avoid migrations, models, packages, assets, auth/portal expansion, shell/sidebar changes, new metrics, false green claims, or new product features.

This follow-up does not change backend truth, RBAC semantics, OperationRun semantics, audit semantics, storage, queues, env vars, or deployment assets.

Hard Rules

Repo Truth

Every visible runtime element must be classified in repo-truth-map.md as one of:

• repo-verified
• foundation-real
• derived from existing model
• empty state / unavailable
• deferred future capability

Do not show a live metric/action unless a real repo source exists.

Customer Safety

Default view must not expose raw diagnostic payloads, provider secrets, internal exception traces, raw OperationRun payloads, internal-only remediation details, debug metadata, or unfiltered tenant/provider IDs.

Evidence First, But Not Raw First

Evidence must be visible as proof path:

• Evidence snapshot
• Review pack
• Decision trail
• Accepted risk record
• OperationRun proof
• Export artifact

Raw internals stay secondary.

No False Green

Do not show generic "Healthy", "Ready", "Complete", or green success states unless repo-backed state proves it. Preferred labels include "Ready to share", "Needs evidence refresh", "Review pack unavailable", "Accepted risk review needed", "No active review", "Evidence unavailable", "Export not ready", and "Follow-up required".

Workspace/Environment Contract

Preserve Specs 314-322:

• clean sidebar/global entry is workspace-wide
• Environment CTA entry uses ?environment_id=
• visible chip when filtered
• clear filter is reload/session/table-safe
• no tenant aliases
• no remembered Environment shell
• no active Environment shell ownership

User Scenarios & Testing (mandatory)

User Story 1 - See review readiness first (Priority: P1)

As a customer reviewer or MSP operator, I want the first viewport to answer whether the review is ready to share so I can decide what needs attention without reading a raw table.

Why this priority: This is the core productization value.

Independent Test: Render Customer Review Workspace with repo-backed published review states and assert the main decision card shows readiness, reason, impact, and one next action without raw diagnostics.

Acceptance Scenarios:

1. Given a published review with a usable review pack and complete evidence basis, When the workspace renders, Then the main decision card states readiness only if repo-backed proof supports it.
2. Given stale/incomplete/missing evidence or missing pack truth, When the workspace renders, Then the main decision card shows follow-up or unavailable state instead of false success.
3. Given no active/published review, When the workspace renders, Then the page shows no active review/no released review state and no fake readiness.

User Story 2 - Follow the evidence path without raw internals (Priority: P1)

As an auditor or customer reviewer, I want to see which evidence, review pack, decision trail, accepted risk records, and operation proof support the review so I can trust the conclusion.

Why this priority: Evidence-backed trust is TenantPilot's governance-of-record value.

Independent Test: Seed reviews with evidence snapshots, review packs, accepted risks, and operation relations where possible; assert proof path labels and links are shown only when authorized and raw payloads stay hidden.

Acceptance Scenarios:

1. Given evidence snapshot and review pack relations exist, When the page renders, Then evidence path and review pack sections show availability, freshness/staleness where repo-supported, and source links where authorized.
2. Given proof is unavailable or unsupported, When the page renders, Then the section shows explicit unavailable/not applicable state.
3. Given raw metadata or diagnostic payload exists in stored summaries, When the default page renders, Then raw internals are absent.

User Story 3 - Understand accepted risks and follow-ups customer-safely (Priority: P1)

As a customer reviewer, I want accepted-risk and follow-up summaries in plain language so I know which decisions require attention without internal approval details.

Why this priority: Accepted risks are customer accountability records and must not be buried or overshared.

Independent Test: Seed current, expiring, expired, pending, and missing accepted-risk/follow-up situations where repo-supported; assert counts/states/customer-safe rows and absence of internal owner/debug details by default.

Acceptance Scenarios:

1. Given accepted risks in the released review scope, When the workspace renders, Then it shows count/state/summary/customer-safe review need.
2. Given expiring/expired/pending accepted risks where repo-supported, When the workspace renders, Then they are called out without internal debug details.
3. Given findings/follow-ups exist, When the workspace renders, Then rows show title, priority/severity if available, owner/due if available, proof state, and next action.

User Story 4 - Preserve workspace and environment scope contracts (Priority: P1)

As an MSP operator, I want clean workspace entry and explicit environment-filtered entry to behave predictably so I do not misread the review scope.

Why this priority: Context leakage would make the customer-safe page unsafe.

Independent Test: Use clean URL, ?environment_id=, clear filter, reload, legacy alias, and cross-workspace environment scenarios.

Acceptance Scenarios:

1. Given clean /admin/reviews/workspace, When the page loads, Then it is workspace-wide with no environment chip and no remembered environment shell.
2. Given /admin/reviews/workspace?environment_id={id}, When the page loads, Then shell remains workspace-owned, data is filtered where supported, and chip/clear filter are visible.
3. Given legacy alias query keys or tableFilters, When the page loads, Then they do not create filter state.
4. Given a cross-workspace environment ID, When the page loads, Then it returns safe no-access/404.

User Story 5 - Keep diagnostics secondary (Priority: P2)

As a support-capable operator, I want diagnostics available only after explicit disclosure so customer reviewers are not exposed to raw operational internals by default.

Why this priority: Customer safety and support utility both matter, but default view must remain safe.

Independent Test: Render default page and diagnostics disclosure paths; assert raw terms are absent by default and capability-gated/collapsed if implemented.

Acceptance Scenarios:

1. Given diagnostics exist, When the page renders, Then diagnostics are collapsed or secondary by default.
2. Given user lacks diagnostic capability, When the page renders, Then diagnostic links/content are hidden or unavailable without sensitive leakage.
3. Given authorized operator opens diagnostics, When details appear, Then they remain secondary and avoid secrets/raw provider payloads.

Functional Requirements (mandatory)

• FR-001: The page MUST keep the existing canonical route /admin/reviews/workspace.
• FR-002: The page MUST show header/scope context: Customer Review Workspace, workspace, workspace-wide vs environment filter, and review mode/customer-safe.
• FR-003: The page MUST show a main decision card asking "Is this review ready to share?" or equivalent stable copy.
• FR-004: The main decision card MUST show status, reason, impact, and one primary next action.
• FR-005: The page MUST show readiness dimensions for readiness, evidence, and accepted risk or repo-verified equivalent dimensions.
• FR-006: The page MUST show an evidence path panel/area covering evidence snapshot, review pack, decision trail, accepted risk records, OperationRun proof, and export artifact where repo-supported.
• FR-007: The page MUST show review pack status, last generated where available, evidence snapshot used where available, export availability, staleness/freshness where repo-supported, and authorized open/download action where available.
• FR-008: The page MUST show accepted-risk counts and states where repo-supported: total, expiring soon, expired, pending approval, and requiring review.
• FR-009: The page MUST show customer-safe findings/follow-ups where repo-supported, including title, priority/severity, owner/due if available, evidence/proof state, and next action.
• FR-010: The page MUST hide raw diagnostics by default.
• FR-011: The page MUST not expose provider secrets, raw provider payloads, raw OperationRun payloads, internal exception traces, debug metadata, or unfiltered provider/tenant IDs by default.
• FR-012: The page MUST classify each visible element in repo-truth-map.md before runtime implementation changes.
• FR-013: The page MUST use existing models/services/policies and derived labels instead of inventing backend truth.
• FR-014: The page MUST not add migrations unless implementation proves a minimal UI-supporting field is absolutely required and the spec is updated first.
• FR-015: The page MUST use environment_id as the only canonical environment filter query key.
• FR-016: The page MUST reject or neutralize legacy filter aliases: tenant, tenant_id, managed_environment_id, environment, tenant_scope, and tableFilters.
• FR-017: The page MUST return safe no-access/404 for cross-workspace or unauthorized environment filters.
• FR-018: The clear-filter action MUST return to the clean workspace-wide URL and remain safe across reload/back/forward behavior.
• FR-019: The page MUST preserve existing RBAC/capability checks for review, evidence, review pack/export, accepted risks, findings, operation proof, and diagnostics.
• FR-020: Unauthorized actions MUST be hidden or unavailable according to product convention and must not leak sensitive existence details.
• FR-021: The page MUST not introduce destructive or customer-impacting mutation actions into the customer-safe default view.
• FR-022: Any destructive/high-impact action later added by implementation MUST use Action::make(...)->action(...), ->requiresConfirmation(), server-side authorization, audit, and tests; current expected implementation adds none.
• FR-023: The page MUST remain Filament v5 and Livewire v4.0+ compliant.
• FR-024: Panel provider registration MUST remain in apps/platform/bootstrap/providers.php; this spec must not modify panel provider registration unless implementation proves a route registration defect.
• FR-025: Globally searchable resources touched by this spec MUST either have View/Edit pages and safe search contracts or keep global search disabled; current related resources are disabled.
• FR-026: The page MUST not register new heavy assets. If any Filament asset registration is introduced, deployment must include cd apps/platform && php artisan filament:assets; expected outcome is no new assets.

Non-Functional Requirements

• NFR-001: Default view must be readable in Filament light mode and dark mode.
• NFR-002: No Graph calls may occur during UI render.
• NFR-003: Query cost must remain bounded to existing persisted data and scoped workspace/environment queries.
• NFR-004: The implementation must avoid CSS-heavy one-off design systems and prefer native Filament sections/cards/badges/grids.
• NFR-005: The page must remain responsive enough for the Filament admin shell.
• NFR-006: Empty/unavailable states must be honest and explicit.
• NFR-007: No raw diagnostics/screenshots/test artifacts may contain secrets.

UX Requirements

• Header/scope area shows workspace-wide vs filtered context.
• Main decision card comes before tables and diagnostics.
• Right-side or secondary evidence/detail panel exists.
• Readiness, evidence, accepted risk, review pack, and follow-up content are scan-first.
• One dominant next action is visible.
• Diagnostic/internal details are collapsed/secondary.
• Tables are not the only default experience.
• Copy is customer-safe and avoids internal admin jargon where possible.
• No green/success cue is used without repo-backed proof.

Capability / RBAC Requirements

Implementation must verify existing capabilities or policy methods for:

• view customer reviews
• view reviews
• view evidence
• view review packs / exports
• view accepted risks
• view findings
• generate review pack if action exists
• refresh evidence if action exists
• export/download review pack if action exists
• view operation run proof if link exists
• view internal diagnostics

No unauthorized action may be shown as executable.

Data Source Discovery Requirements

Before runtime changes, create and maintain:

specs/326-customer-review-workspace-v1-productization/repo-truth-map.md

The map must cover:

• Tenant Reviews / Environment Reviews
• Customer Review Workspace page state
• Evidence Snapshots
• Review Packs / exports
• Accepted Risks / Risk Exceptions
• Findings / Finding Exceptions
• Stored Reports / Export Artifacts
• OperationRuns
• Workspace entitlements/capabilities
• Audit log

Each entry must include UI element, source model/service/page, status source, authorization/capability, workspace/environment scope, OperationRun/audit link, fallback/empty state, and classification.

Assumptions

• Spec 312 work is present and can be refined; it must not be rewritten as if it never happened.
• Existing helpers in tests/Pest.php can create review/evidence/pack scenarios for targeted tests.
• Existing ReviewPack, EnvironmentReview, EvidenceSnapshot, and FindingException models are sufficient for v1.
• No migration is expected.
• No package or env var is expected.

Risks

• The page may already contain customer-safe summary logic, so implementation must avoid broad rewrites and focus on gaps against Spec 325 target direction.
• Accepted-risk/follow-up counts may not all be available as direct repo truth; unavailable/empty states must be honest.
• Diagnostics disclosure could leak raw payloads if implemented too eagerly.
• Browser smoke may require stable fixtures and must not broaden browser lane cost beyond the named Spec 326 test.

Open Questions

No product decision blocks implementation. Implementation must resolve repo-truth details in repo-truth-map.md and update this spec/plan before continuing if a requested visible element cannot be sourced safely.

Acceptance Criteria

Productization

• Customer Review Workspace has decision-first layout.
• Main readiness question is visible.
• Review readiness is visible.
• Evidence freshness/path is visible.
• Review Pack status is visible.
• Accepted Risk summary is visible.
• Customer-safe findings/follow-ups are visible or explicitly unavailable.
• One primary next action is clear.
• Diagnostics are secondary/collapsed.

Customer Safety

• Raw diagnostics are hidden by default.
• Provider secrets are not visible.
• Internal exception/debug text is not visible.
• Customer-facing copy avoids internal admin jargon.
• Empty/unavailable states are honest.
• No false green success state.

Evidence / Review Pack

• Evidence path is visible.
• Evidence snapshot availability is shown.
• Review pack availability is shown.
• Review pack freshness/staleness is shown where repo-supported.
• Export/open actions respect RBAC.
• OperationRun proof is linked where repo-supported and authorized.

Scope

• Clean URL is workspace-wide.
• Shell is Workspace-only.
• Environment filter uses environment_id.
• Visible Environment chip appears when filtered.
• Clear filter works.
• Reload after clear is safe.
• Legacy aliases do not create filter state.
• Cross-workspace Environment is rejected.

RBAC

• Unauthorized user cannot access protected data.
• Unauthorized actions are hidden/disabled.
• Diagnostics require appropriate capability.
• Export/open review pack respects capability.
• Evidence access respects capability.

UI / Visual

• Layout uses premium target direction from Spec 325 without treating target images as truth.
• Filament light mode remains readable.
• No one-off heavy CSS unless justified.
• Right-side panel or equivalent evidence/detail area exists.
• Tables are not the only default experience.
• Page remains responsive enough for Filament admin shell.

Tests / Validation

• Repo truth map exists.
• Required Feature tests pass.
• Required Browser smoke passes.
• Relevant Spec 314-322 guards still pass.
• pint --dirty passes.
• git diff --check passes.
• No broad rebaseline.
• Full suite status is honestly reported if run/not run.

Definition Of Done

Spec 326 is done when:

1. Customer Review Workspace is productized into a decision-first surface.
2. Customer-safe review readiness is visible.
3. Review Pack state is visible.
4. Evidence freshness/path is visible.
5. Accepted risks are summarized safely.
6. Customer-safe findings/follow-ups are visible or honestly unavailable.
7. Raw diagnostics are hidden by default.
8. Primary next action is clear.
9. Workspace/Environment filter contract remains correct.
10. RBAC/capabilities are respected.
11. No false green states are introduced.
12. No invented backend claims are shown as runtime truth.
13. Browser smoke confirms clean, filtered, clear, reload, and disclosure behavior.
14. Spec 314-322 context guards remain green or known unrelated failures are documented.
15. No migrations/packages/env/queues/scheduler/storage/deployment assets are introduced unless explicitly justified.

Follow-Up Specs

• Spec 327 - Governance Inbox Decision-First Workbench Productization.
• Spec 328 - Operations Hub Decision-First Workbench Productization.
• Spec 329 - Evidence / Audit Log Disclosure Productization.
• Spec 330 - Environment Dashboard / Baseline Compare Productization.
• Spec 331 - Restore Safety Workflow Productization.

Do not start these inside Spec 326.