TenantAtlas/specs/342-customer-review-workspace-final-consumption-productization/spec.md

Feature Specification: Spec 342 - Customer Review Workspace v1 Final Consumption Productization

Feature Branch: 342-customer-review-workspace-final-consumption-productization
Created: 2026-06-01
Status: Draft
Type: Runtime UX productization / customer-safe review consumption / no backend rewrite
Runtime posture: Productize existing Customer Review Workspace, Environment Review, Evidence, Review Pack, Finding, Accepted Risk, Audit, and OperationRun proof foundations. Do not introduce a new portal architecture, backend review engine, or persisted readiness truth.
Input: User-provided Spec 342 draft + docs/product/spec-candidates.md P1 Customer Review Workspace v1 Completion lane.

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

• Problem: Customer Review Workspace is repo-real and has prior productization work, but final customer-safe consumption still needs one coherent first-screen answer: what was reviewed, what needs attention, which risks were accepted, what evidence/review pack exists, and what next action is expected without raw operator diagnostics.
• Today's failure: A customer, auditor, account manager, or service owner can still need to infer readiness by reading several panels, tables, generated artifacts, evidence paths, or related operations instead of seeing status, reason, impact, evidence basis, accepted-risk visibility, review-pack/export truth, and one primary next action immediately.
• User-visible improvement: The review workspace becomes a sellable v1 consumption surface: customer-safe by default, evidence-aware, accepted-risk-aware, review-pack/export-aware, and honest about unavailable/deferred states.
• Smallest enterprise-capable version: Finalize only the existing /admin/reviews/workspace surface and its current page/view/payload contract. Add or adjust a small derived presenter only if current page-local logic is too scattered, and keep it feature-local and derived-only.
• Explicit non-goals: No new external customer portal, authentication/federation, review generation engine, evidence generation engine, review-pack/PDF/ZIP generation logic, external delivery, billing/entitlement system, AI summarization, new OperationRun type, migration, package, scheduler, queue, storage, or broad shell/navigation rewrite.
• Permanent complexity imported: One spec-local repo truth map, one spec-local consumption state contract, focused Feature/Livewire tests, one Browser smoke file, and screenshot artifacts. Possible small page-local presenter if needed. No new tables, persisted source of truth, enum/status family, public framework, or cross-domain UI taxonomy.
• Why now: Specs 326, 329, 335, 336, 337, 340, and 341 have productized adjacent review/evidence/proof/process/link surfaces. The remaining P1 roadmap gap is final customer-safe review consumption, not another backend foundation or canonical-link cleanup.
• Why not local: A copy-only pass would keep readiness scattered and could create false customer-safe or evidence/export claims. A broad portal/framework would overbuild. The narrow correct slice is a repo-truth-bounded final consumption pass on the existing workspace.
• Approval class: Core Enterprise.
• Red flags triggered: Customer-facing trust language, many evidence/review/finding concepts, possible presenter/state contract. Defense: all states remain derived from repo-backed truth, raw diagnostics stay collapsed, RBAC/policies remain authoritative, no persistence or new status family is introduced, and unsupported concepts are rendered as unavailable/deferred.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve.

Candidate Source And Completed-Spec Guardrail

• Candidate source: User-provided Spec 342 draft, aligned with docs/product/spec-candidates.md → Customer Review Workspace v1 Completion and docs/product/roadmap.md → Customer Review Workspace v1 Completion as the top current productization priority.
• Completed-spec check: No specs/342-* package existed before generation. Related Specs 249, 258, 312, 326, 329, 335, 336, 337, 340, and 341 contain prepared, implemented, completed-task, validation, smoke, or close-out signals and are treated as historical context only. They must not be rewritten or normalized by this spec.
• Spec 326 boundary: Spec 342 must not repeat Spec 326’s general workspace productization. It closes the narrower final-consumption gap: customer-safe decision card, review consumption states, accepted-risk visibility, evidence/review-pack/export truth, and one next action after Specs 337 and 341.
• Close alternatives deferred:
  • localization-v1-customer-facing-surfaces: deferred until final review-consumption truth is stable.
  • decision-based-governance-inbox-v1: deferred because operator inbox maturity should build on the customer-safe review output, not replace it.
  • commercial-entitlements-billing-state-maturity: deferred until customer-facing review consumption is clearer.
  • provider-readiness-productization and PSA/support handoff: follow-up lanes only.
• Smallest viable implementation slice: Existing Customer Review Workspace only: first-screen decision state, review readiness flow, findings summary, accepted-risk summary, evidence/review-pack/export proof panel, diagnostics disclosure, route/context/RBAC safety, tests, browser smoke, and screenshots.

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.
  • Related proof/action links: EnvironmentReviewResource, EvidenceSnapshotResource, ReviewPackResource, FindingExceptionResource, StoredReportResource, OperationRunLinks, and signed review-pack download route.
• Data Ownership:
  • Workspace-scoped canonical page; rendered records are workspace- and managed-environment-owned.
  • Review truth: EnvironmentReview, status, published timestamp, summary, completeness, current export review pack.
  • Evidence truth: EvidenceSnapshot, EvidenceSnapshotItem, completeness/status, linked operation run.
  • Review pack/export truth: ReviewPack, status, file metadata, expiry, evidence snapshot, environment review, signed download eligibility.
  • Findings and accepted-risk truth: Finding, FindingException, FindingExceptionDecision, evidence references, review-derived summaries.
  • Audit/proof truth: AuditLog, existing workspace audit logger events, and linked OperationRun records.
• RBAC:
  • Workspace membership is required.
  • Managed-environment entitlement is required before showing environment-scoped review/evidence/findings/pack data.
  • Existing policies/capabilities remain authoritative for review, evidence, review-pack, accepted-risk, finding, audit, diagnostics, export/download, and operation proof visibility.
  • Non-member or cross-workspace/environment access remains deny-as-not-found.
  • Member-without-capability behavior follows existing UI hidden/disabled plus server-side policy/gate enforcement.

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, /admin/t routes, table filters, legacy query aliases, or hidden topbar scope. ?environment_id= is a page-level filter only.
• Explicit entitlement checks preventing cross-tenant leakage: Any environment_id, review, evidence snapshot, review pack, finding, accepted risk, audit, or operation proof link must resolve through current workspace and actor entitlement before rendering or navigation.

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: Existing Customer Review Workspace / Strategic Surface.
• Design depth: Strategic Surface.
• Repo-truth level: repo-verified page and foundational models; final state mapping must be maintained in repo-truth-map.md and customer-review-consumption-state-contract.md.
• Existing pattern reused: Filament Page, current Blade composition, existing workspace hub environment_id filter chip, Spec 326 customer review layout, Spec 337 evidence/review-pack product flow, existing badge/action/link helpers, existing signed review-pack download route, existing policies.
• New pattern required: none by default. A small page-local presenter is allowed only if it replaces scattered page/view logic and remains derived-only.
• Screenshot required: yes, during implementation under specs/342-customer-review-workspace-final-consumption-productization/artifacts/screenshots/.
• Page audit required: no new page audit by default because route/archetype remain the same; implementation must update UI coverage registry artifacts or document in the active close-out why existing route inventory/design coverage remains sufficient.
• Customer-safe review required: yes. The surface must hide raw JSON, provider diagnostics, internal IDs as primary labels, fingerprints, stack traces, raw operation payloads, and platform reason families by default.
• Dangerous-action review required: no new dangerous action is expected. If a generation/regeneration/export mutation is added or exposed, update this spec/plan first and require confirmation, server-side authorization, audit, notification, and action tests.
• 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 explicitly choose registry update or active-spec close-out no-registry-change rationale after the runtime diff is known.

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes.
• Interaction class(es): customer-safe review status messaging, decision card, evidence/report viewer, review-pack/export links, accepted-risk summaries, finding summaries, diagnostics disclosure, OperationRun proof links.
• Systems touched: CustomerReviewWorkspace, customer review Blade view, existing review/evidence/review-pack resources, ReviewPackDownloadController, OperationRunLinks, ArtifactTruthPresenter, BadgeCatalog / BadgeRenderer, UiEnforcement or existing capability-aware visibility helpers.
• Existing pattern(s) to extend: Spec 326 Customer Review Workspace layout/productization, Spec 337 Product Process Flow semantics, current evidence/review-pack state mapping, current workspace hub environment filter, current signed download and audit paths.
• Shared contract / presenter / builder / renderer to reuse: reuse existing artifact truth, badge, operation link, workspace filter, resource URL, and policy/capability helpers. Use CustomerReviewWorkspacePresenter only as a small derived page-local adapter if needed.
• Why the existing shared path is sufficient or insufficient: Existing repo truth sources and UI primitives are sufficient for state calculation and rendering. They may be insufficient only because the final consumption state is spread across current page methods and Blade fragments; if so, consolidate locally rather than frameworkizing.
• Allowed deviation and why: bounded page-local presenter/contract is allowed to prevent duplicate logic. No cross-domain readiness framework or new persisted state is allowed.
• Consistency impact: Status, reason, impact, next-action labels, review-pack/export state, accepted-risk terminology, and operation proof links must stay aligned with Specs 326/337 and current resources.
• Review focus: no fake customer-safe/evidence/export/auditor-ready claims, no raw diagnostics as first-screen UX, no /admin/t, no legacy query aliases, no unauthorized action leakage, no duplicated readiness summaries.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: existing link/proof display only; no new operation start, completion, dedupe, queueing, terminal notification, or lifecycle behavior.
• Shared OperationRun UX contract/layer reused: existing OperationRunLinks and existing operation/resource routes.
• Delegated start/completion UX behaviors: N/A for new starts. Existing proof/deep-link behavior must remain delegated to shared operation link helpers and policies.
• Local surface-owned behavior that remains: explanatory copy that distinguishes operation proof from evidence output and review-pack/export truth.
• 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.
• Boundary classification: platform-core consumption of existing workspace/environment governance artifacts.
• Seams affected: display and navigation over review/evidence/review-pack/finding/accepted-risk/audit/operation proof.
• Neutral platform terms preserved or introduced: workspace, environment, customer review, evidence, review pack, export, accepted risk, finding, operation proof, audit trail, diagnostics.
• Provider-specific semantics retained and why: provider-specific names may appear only inside already persisted/customer-safe evidence or review content. No Graph payloads, provider IDs, or Microsoft-specific platform-core terms should become primary UI language.
• Why this does not deepen provider coupling accidentally: no Graph calls, provider credentials, provider contract registry, connection scope, or provider taxonomy changes.
• Follow-up path: provider-readiness productization remains a separate follow-up candidate.

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

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 first screen	yes	Native Filament page plus existing Blade composition	customer-safe review consumption, status messaging	page payload, URL-query	no	Existing route only
Review decision card	yes	Filament sections/cards/badges/buttons	decision-first status/reason/impact/next action	page payload	no	Derived labels only
Review readiness flow	yes	existing Product Process Flow conventions where practical	process/status messaging	page payload	no	No new persisted lifecycle
Findings and accepted-risk summaries	yes	Filament/shared badges and cards	finding/decision/evidence summaries	page payload	no	Repo-backed fields only
Evidence / review pack / export proof panel	yes	Filament/shared proof panel	evidence/report/review-pack viewer, OperationRun proof	page payload/action links	no	Proof secondary, not diagnostics-first
Diagnostics disclosure	yes	collapsed/progressive disclosure	support/raw detail	page payload/action visibility	no	Hidden/capability-aware 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 if the review is ready to consume/share or needs follow-up	status, reason, impact, primary next action, findings, accepted risks, evidence, review-pack/export state	review detail, evidence snapshot, review pack, audit, operation proof, diagnostics	Primary because this is the customer-facing consumption hub	Review consumption, not admin mirror	Avoids reconstructing readiness across resources
Evidence / review pack / export proof panel	Secondary Context / Tertiary Evidence	Reviewer checks the proof basis after reading the decision card	evidence state, review pack state, export availability, operation/audit proof availability	linked artifacts and diagnostics when authorized	Supports primary decision without replacing it	Evidence-first review trust	Separates proof from raw payloads
Findings / accepted risks summaries	Secondary Context	Reviewer checks attention and accepted-risk accountability	open/high-impact findings, accepted risk owner/rationale/expiry where repo-backed	finding/exception detail and evidence references	Supports review follow-up and customer accountability	Findings/risk workflow	Avoids hiding risk acceptance in diagnostics

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, support where authorized	status, reason, impact, next action, findings/accepted-risk/evidence/review-pack/export summaries	collapsed and secondary	raw JSON, provider diagnostics, operation payloads, internal reason ownership, fingerprints	state-specific action: review findings, open review pack, open evidence, or complete review preparation	raw diagnostics, debug payloads, operator-only repair actions	decision card states readiness once; panels add proof
Diagnostics disclosure	operator/support only	collapsed indicator or unavailable state	operation metadata, technical details, raw/support fields if authorized	raw payloads only when explicitly revealed and permitted	close/open diagnostics	default hidden	diagnostics never restate the primary decision as a second competing summary

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 strategic hub	Consume latest review or follow one next action	Primary action in decision card; linked proof secondary	no row-click requirement for summary cards	proof panel / secondary links	none expected	/admin/reviews/workspace	existing review/evidence/pack/finding detail routes	workspace shell + optional visible environment_id filter chip	Customer review	readiness, reason, impact, evidence, pack/export, findings, accepted risks	none
Review package index	List / Table / Registry context	Secondary artifact index	Open a specific released review or review pack	dedicated open column/link only	no	row/proof links only	none expected	/admin/reviews/workspace	existing resource detail/download routes	same workspace/filter signals	Review package	package availability, latest review, evidence status, next step	existing table remains secondary

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	Decide whether a released review can be consumed/shared or needs follow-up	Strategic review workbench	Is this review ready to consume, what needs attention, and what evidence supports it?	status, reason, impact, next action, findings, accepted risks, evidence state, review pack/export state	raw operation payload, provider JSON, fingerprints, internal reason families, stack traces	review readiness, data completeness, finding attention, accepted-risk accountability, evidence state, review pack/export state	read-only consumption; existing linked actions only	state-specific open/review/download action	none expected

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no.
• New persisted entity/table/artifact?: no runtime persistence. Spec-local preparation artifacts only.
• New abstraction?: possible small page-local presenter if needed; no public interface/framework.
• New enum/state/reason family?: no. Consumption states are presentation labels derived from existing model status/relationships.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: customer-safe reviewers need a truthful first-screen answer without traversing artifacts and diagnostics.
• Existing structure is insufficient because: current truth exists, but final consumption state can be scattered across review payloads, evidence panels, accepted-risk summaries, review-pack status, and operation/audit proof.
• Narrowest correct implementation: derive state locally for the existing page, render one decision hierarchy, and test false-claim prevention.
• Ownership cost: one feature-local state contract, possible presenter, focused tests, one browser smoke, screenshot upkeep.
• Alternative intentionally rejected: portal architecture, new lifecycle table, generic readiness engine, global state taxonomy, and copy-only patch.
• Release truth: current-release truth; this is a sellability/productization slice.

Compatibility posture

This feature assumes a pre-production environment. Backward compatibility, legacy aliases, migration shims, /admin/t resurrection, and compatibility-specific tests are out of scope unless this spec is explicitly amended.

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

• Test purpose / classification: Feature/Livewire for state, RBAC, context, and false-claim prevention; Browser for rendered first-screen consumption and collapsed diagnostics.
• Validation lane(s): confidence + browser.
• Why this classification and these lanes are sufficient: state composition and authorization can be proven through focused Feature/Livewire tests; the customer-safe first screen, visual hierarchy, diagnostics disclosure, and screenshot evidence require one bounded browser smoke.
• New or expanded test families: Spec342CustomerReviewWorkspaceConsumptionTest.php and Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php.
• Fixture / helper cost impact: reuse existing workspace/environment/review/evidence/review-pack/finding/exception/audit/operation factories and fixtures; no heavy default seed or shared setup widening.
• Heavy-family visibility / justification: one explicit Browser smoke family because this is a customer-facing strategic surface.
• Special surface test profile: global-context-shell + customer-safe strategic review surface.
• Standard-native relief or required special coverage: no standard-native relief; this surface requires customer-safe disclosure and browser proof.
• Reviewer handoff: verify no false customer-safe/auditor-ready/export-ready claims, diagnostics collapsed, one next action, no /admin/t, no legacy query alias, and no cross-workspace leakage.
• Budget / baseline / trend impact: none expected beyond one bounded browser smoke.
• Escalation needed: document-in-feature for unreachable states; follow-up-spec only if implementation proves missing backend truth such as attestation or external delivery; reject-or-split if scope grows into portal/framework/backend generation.
• Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec342CustomerReviewWorkspaceConsumptionTest.php --compact
  • cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test --filter='CustomerReview|ReviewPack|Evidence|AcceptedRisk|Finding|Audit|Spec341' --compact
  • cd apps/platform && ./vendor/bin/sail pint --dirty
  • git diff --check

User Scenarios & Testing (mandatory)

User Story 1 - Understand review readiness immediately (Priority: P1)

A customer-safe reviewer opens Customer Review Workspace and sees whether the latest released review is ready to consume, why, what impact exists, and the one next action before any raw table or diagnostics.

Why this priority: This is the core sellability and trust gap.

Independent Test: Render the page with a released review in multiple repo-backed states and assert the decision card shows status, reason, impact, one next action, and no raw diagnostics.

Acceptance Scenarios:

1. Given a workspace member with review access and a released review with linked evidence and review pack, When they open /admin/reviews/workspace, Then they see a customer-safe decision card with review-ready/evidence/pack state and a primary action.
2. Given a released review without required evidence or pack output, When the reviewer opens the workspace, Then the page says what is missing and does not claim customer-safe or export-ready output.
3. Given no released review is available for the selected filter, When the reviewer opens the page, Then the empty state explains that review consumption is not ready without exposing raw diagnostics.

User Story 2 - Review findings and accepted risks safely (Priority: P1)

A reviewer sees findings needing attention and accepted risks as customer-safe summaries, including repo-backed owner, rationale, expiry/review date, proof, and action where available.

Why this priority: Accepted risks must not be hidden in diagnostics or implied as “all clear”.

Independent Test: Render fixtures with open findings and accepted-risk states; assert customer-safe summaries appear and unsupported fields are unavailable/deferred rather than faked.

Acceptance Scenarios:

1. Given findings require review, When the page renders, Then it shows findings summary and next action without raw finding payloads.
2. Given accepted risks exist, When the page renders, Then accepted-risk state is visible with repo-backed owner/rationale/expiry fields where available.
3. Given accepted-risk expiry/review date is missing, When the page renders, Then the missing review date is explicitly disclosed instead of suppressed.

User Story 3 - Consume evidence, review pack, export, audit, and operation proof truthfully (Priority: P2)

A reviewer can distinguish evidence availability, review-pack readiness, export/download state, audit trail, and OperationRun proof without treating operation proof as customer evidence.

Why this priority: Review trust depends on evidence/result truth separation.

Independent Test: Render states for evidence missing, evidence available, pack required/generating/failed/available, export unavailable/available, and linked operation proof.

Acceptance Scenarios:

1. Given evidence exists but no review pack exists, When the page renders, Then evidence is available and review pack is required.
2. Given a ready non-expired review pack has file metadata and the actor is authorized, When the page renders, Then the open/download action is visible.
3. Given linked OperationRun proof exists, When the page renders, Then operation proof appears as secondary proof and raw operation JSON remains hidden.

User Story 4 - Preserve RBAC, context, and customer-safe disclosure (Priority: P1)

Unauthorized or cross-workspace users cannot infer review, evidence, pack, finding, accepted-risk, audit, or diagnostics existence; authorized users see only capability-appropriate actions.

Why this priority: Customer-facing review consumption must not weaken tenant/workspace isolation.

Independent Test: Attempt cross-workspace environment filters and missing-capability paths; assert deny-as-not-found/hidden actions and no /admin/t or legacy query alias behavior.

Acceptance Scenarios:

1. Given a user is not entitled to the workspace/environment, When they request a filtered workspace URL, Then the page denies as not found or shows no leaked state.
2. Given a user lacks diagnostics capability, When the page renders, Then diagnostics are unavailable or hidden and raw/support detail is not visible.
3. Given legacy query aliases are present, When the page opens, Then only canonical environment_id can narrow the workspace hub.

Functional Requirements

• FR-001: The page MUST render a first-screen decision card with status, reason, impact, and one primary next action.
• FR-002: The page MUST classify customer-review consumption data using repo-verified, derived from existing model, foundation-real, not available, or deferred in repo-truth-map.md.
• FR-003: The page MUST derive visible consumption states from existing review, evidence, review-pack, finding, accepted-risk, audit, and operation truth; it MUST NOT persist new readiness truth.
• FR-004: The page MUST distinguish review readiness, evidence state, review-pack state, export/download state, findings attention, accepted-risk accountability, audit trail, and operation proof.
• FR-005: The page MUST keep diagnostics collapsed or unavailable by default and capability-gated when available.
• FR-006: The page MUST NOT expose raw provider JSON, raw OperationRun payload, stack traces, fingerprints, internal IDs as primary labels, or provider diagnostics in the default customer-safe surface.
• FR-007: Review pack/open/download actions MUST appear only when repo-backed and authorized.
• FR-008: Customer-safe, auditor-ready, export-ready, evidence-backed, healthy, compliant, or complete claims MUST appear only when repo truth supports them.
• FR-009: Accepted risks MUST be visible in the customer-safe summary when repo-backed and MUST NOT be hidden only in diagnostics.
• FR-010: Workspace/environment scope MUST remain explicit; environment_id is a page-level filter only and legacy query aliases MUST NOT resurrect context.
• FR-011: Existing authorization, policies, capabilities, and audit behavior MUST remain authoritative for all linked actions and proof surfaces.
• FR-012: New visible strings MUST follow existing localization conventions where applicable and avoid mixed-language static copy.

Non-Functional Requirements

• Page render MUST remain DB-only and MUST NOT call Microsoft Graph or external providers.
• The implementation SHOULD reuse native Filament components and shared primitives before local Blade/Tailwind styling.
• The implementation MUST preserve Filament v5 / Livewire v4.0+ compliance.
• The implementation MUST keep panel provider registration unchanged in apps/platform/bootstrap/providers.php.
• The implementation MUST avoid new frontend assets; if registered assets become necessary, update deployment notes to include php artisan filament:assets.

Out Of Scope

• External customer portal, invitations, auth/federation, customer attestation backend, PSA/helpdesk integration, email delivery, AI summarization, new evidence/review-pack/export generation, new report format, new OperationRun lifecycle, new migrations, new package, new queue/scheduler/storage/env var, new billing/entitlement system, and broad Customer Review Workspace navigation/shell redesign.

Acceptance Criteria

• AC-001: Customer Review Workspace default view starts with customer-safe status, reason, impact, and one primary next action.
• AC-002: Findings and accepted risks are summarized customer-safely when repo-backed; unsupported owner/expiry/evidence fields are unavailable/deferred rather than invented.
• AC-003: Evidence, review-pack, export/download, audit, and OperationRun proof are separated and truthfully labeled.
• AC-004: Diagnostics are collapsed or unavailable by default and raw/support details do not appear in first-screen content.
• AC-005: RBAC and workspace/environment isolation tests cover authorized, missing-capability, cross-workspace, diagnostics, and canonical-filter behavior.
• AC-006: Browser smoke captures the decision card, findings/accepted-risk/evidence/pack states, diagnostics collapsed, and no /admin/t or legacy query alias regression.

Success Criteria

• Reviewers can answer “is this review ready to consume, what needs attention, and what evidence supports it?” from the first screen in validated fixtures.
• No validated state shows a false customer-safe, auditor-ready, evidence-backed, export-ready, healthy, or compliant claim.
• Focused Feature/Livewire and Browser validation pass without broad suite or helper drift.

Risks

• Current runtime may already satisfy some Spec 342 states; implementation must avoid churn and update repo-truth-map.md before changing code.
• Some requested concepts, such as acknowledgement/attestation or external delivery, may be not repo-backed and must remain deferred.
• A local presenter can become a hidden framework if not kept page-local and derived-only.
• Browser fixture setup can expand cost; keep one bounded smoke file and document unreachable states honestly.

Assumptions

• Spec 342 is a manual user-provided promotion and may use number 342 even though automatic branch numbering would be distorted by unrelated remote branch numbers.
• Current branch platform-dev was clean before Spec Kit branch creation.
• The repo remains pre-production under the constitution’s lean doctrine.
• Existing Customer Review Workspace page and related resources remain the implementation target; no new route is required.

Open Questions

• None block safe implementation. Implementation must mark any unsupported state as not available or deferred in repo-truth-map.md instead of adding backend truth inside this spec.

Follow-up Spec Candidates

• Customer Review Attestation & Accepted Risk Lifecycle.
• Decision-Based Governance Inbox Final Operator Workflow.
• Localization v1 Product Surface Hardening.
• Provider Readiness Productization.
• External Support Desk / PSA Handoff.