TenantAtlas/specs/372-customer-auditor-surface-safety-pass/spec.md

Feature Specification: Spec 372 - Customer/Auditor Surface Safety Pass v1

Feature Branch: 372-customer-auditor-surface-safety-pass
Created: 2026-06-11
Status: Approved
Type: Customer/auditor UI safety productization pass over existing review, report, pack, and evidence surfaces
Runtime posture: UI/productization only for existing reachable surfaces. No new review logic, evidence logic, migrations, routes, customer portal, report renderer changes, disclosure-policy changes, OperationRun model changes, backend export changes, shell/navigation rewrite, billing, support handoff, or broad diagnostic refactor.
Input: User-provided Spec 372 draft plus Spec 368 Candidate C, Spec 370 follow-up map, and completed Spec 371 productization artifacts.

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

• Problem: Customer- and auditor-facing review/report/evidence surfaces are repo-real, but the customer-safe experience is uneven across the full handoff path. Some pages are strong, some are dense, and Evidence Snapshot detail was blocked in the Spec 368 browser pass.
• Today's failure: A customer, auditor, or operator-as-facilitator can still encounter repeated readiness/status phrases, broad operator chrome, technical metadata, OperationRun-adjacent language, or unclear evidence limitations before understanding the outcome, evidence basis, and next safe action.
• User-visible improvement: The scoped surfaces answer the customer/auditor questions first: outcome, readiness, findings/risks needing decision, evidence availability, limitations, and the one safe next action. Diagnostics and internal mechanics remain available only as secondary, collapsed, or capability-gated content.
• Smallest enterprise-capable version: Existing Customer Review Workspace, Environment Review View, Review Pack View, Stored Report View, and Evidence Snapshot View only if reachable with current fixtures. Keep changes page-local or narrowly shared among these surfaces; document blocked Evidence Snapshot reachability instead of fixing auth/routing broadly.
• Explicit non-goals: No operator-surface refactor from Spec 371, Environment Dashboard, Operations Hub, OperationRun View, Backup Set View, Restore Run View, Baseline Profile View, Provider Connections, Environment Diagnostics, Required Permissions, System Panel, new customer portal, new persisted truth, new readiness engine, new disclosure policy, new report renderer, new Graph calls, or new routes.
• Permanent complexity imported: Spec-local source audit, affected-file map, customer surface contracts, screenshot index, customer safety checklist, validation report, focused Feature/Livewire tests, bounded Browser smoke, and screenshots. No new persisted entity, enum/status family, public framework, or cross-domain UI taxonomy is expected.
• Why now: Spec 370 created the global surface information architecture contract and explicitly deferred a Customer/Auditor Surface Safety Pass. Spec 371 has now proven the summary-first, metadata-demotion, technical-details-collapse, single-primary-action, screenshot-backed productization pattern on core operator surfaces.
• Why not local: A single-page patch would repeat the earlier Customer Review Workspace slices and miss the full customer/auditor handoff path. A broad portal/report rewrite would overbuild. The correct v1 is a bounded safety pass across existing output/evidence surfaces.
• Approval class: Core Enterprise.
• Red flags triggered: Multiple surfaces and customer-safe trust language. Defense: every surface is existing/repo-real, Evidence Snapshot is conditional, no new persistence/framework is introduced, and the scope applies an already accepted contract rather than inventing a new one.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve.

Candidate Source And Completed-Spec Guardrail

• Selected candidate: Spec 372 - Customer/Auditor Surface Safety Pass v1.
• Source locations:
  • User-provided draft: /Users/ahmeddarrazi/.codex/attachments/398c764b-3ff8-45f7-ae91-540699f3781f/pasted-text.txt
  • Spec 368 Candidate C: specs/368-platform-ui-signal-to-noise-browser-audit/spec-candidates.md
  • Spec 370 explicit deferred follow-up: specs/370-global-surface-information-architecture-contract/artifacts/follow-up-spec-map.md
  • Roadmap/candidate relationship: docs/product/spec-candidates.md customer-review and evidence/report productization follow-ups.
• Completed-spec check:
  • No specs/372-* package existed before this prep.
  • Specs 342, 344, and 347 contain completed-task, validation, smoke, or implementation-history signals and are treated as completed historical context only.
  • Specs 370 and 371 contain completed-task, validation, and close-out signals and are read-only inputs.
  • Spec 368 is an audit source package and remains read-only.
• Boundary against related completed specs:
  • Spec 342/344: Customer Review Workspace single-surface consumption and density work. Spec 372 may inspect and preserve those outcomes but must not reopen them as the whole scope.
  • Spec 347: Review Pack output contract/readiness semantics. Spec 372 may reuse its output-readiness language but must not change generator, ZIP contract, or disclosure policy truth.
  • Spec 371: Backup Set operator productization pattern. Spec 372 reuses the pattern direction, not the operator wording or backup/restore surfaces.
• Close alternatives deferred:
  • Diagnostic Surface Separation v1: deferred because Required Permissions, System Panel, Provider Connections, and Environment Diagnostics are diagnostic/operator/support surfaces outside this customer/auditor pass.
  • UI Bloat Regression Guard v1: deferred until another runtime consumer proves the contract pattern and exceptions.
  • Localization v1 Customer-facing Surfaces: deferred until the customer/auditor safety hierarchy is stable.
• Smallest viable implementation slice: existing scoped surfaces only, with source audit, page contracts, customer-safety checklist, tests, and browser screenshots. Evidence Snapshot is included only if reachable with existing fixtures.

Spec Scope Fields (mandatory)

• Scope: workspace canonical view plus environment-owned review/report/evidence artifact detail surfaces.
• Primary Routes / Surfaces:
  • Customer Review Workspace: /admin/reviews/workspace, App\Filament\Pages\Reviews\CustomerReviewWorkspace, apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php
  • Environment Review View: /admin/workspaces/{workspace}/environments/{environment}/environment-reviews/{record}, App\Filament\Resources\EnvironmentReviewResource
  • Review Pack View: /admin/workspaces/{workspace}/environments/{environment}/review-packs/{record}, App\Filament\Resources\ReviewPackResource
  • Stored Report View: /admin/workspaces/{workspace}/environments/{environment}/stored-reports/{record}, App\Filament\Resources\StoredReportResource
  • Evidence Snapshot View, conditional: /admin/workspaces/{workspace}/environments/{environment}/evidence/{record}, App\Filament\Resources\EvidenceSnapshotResource
• Data Ownership:
  • Workspace-owned shell/context remains workspace-scoped.
  • Environment-owned records remain workspace + managed-environment scoped.
  • Review truth remains in EnvironmentReview and related review sections/summaries.
  • Evidence truth remains in EvidenceSnapshot and evidence snapshot items.
  • Report/export truth remains in ReviewPack and StoredReport.
  • OperationRun remains proof/diagnostic linkage only, not customer-facing evidence truth.
• RBAC:
  • Workspace membership and managed-environment entitlement are mandatory before rendering any environment-owned record.
  • Existing resource policies/capability checks remain authoritative.
  • Non-member or cross-workspace/environment access remains deny-as-not-found.
  • Missing capability after entitlement remains 403 or disabled/hidden per existing UI enforcement.
  • Operator/support diagnostics may be visible only through existing capabilities and must stay collapsed or secondary by default.

For canonical-view specs:

• Default filter behavior when tenant-context is active: Customer Review Workspace remains workspace-wide with explicit environment_id page filter only. Hidden environment context, legacy /admin/t, legacy query aliases, and remembered switcher state must not create authority.
• Explicit entitlement checks preventing cross-tenant leakage: all scoped record URLs and detail panels must resolve through current workspace/environment ownership and existing policies before content or actions are shown.

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")

Route/page/surface	Archetype	Design depth	Repo-truth level	Existing pattern reused	Screenshot / audit need	Customer-safe review	Dangerous-action review
Customer Review Workspace	Customer surface / Strategic Surface	Strategic Surface	repo-verified + browser-verified	Specs 342/344/347 customer-safe hierarchy, Spec 370 contract, existing workspace filter	after screenshots required; existing UI-006 page report may need update	yes	existing acknowledgement/create-next-review actions remain in scope for preservation only: keep confirmation, authorization, audit, and capability-aware UI behavior; no new high-impact action
Environment Review View	Customer/auditor review detail	Domain Pattern Surface	repo-verified + browser-verified in Spec 368	Spec 347 review output readiness, existing EnvironmentReviewResource detail	after screenshot required; UI-040 report may need update	yes	existing refresh/publish/create-next/archive/export actions remain in scope for preservation only; keep confirmation, authorization, audit, OperationRun UX, and capability behavior; no new action
Review Pack View	Auditor/output artifact detail	Domain Pattern Surface	repo-verified + browser-verified in Spec 368	Spec 347 Review Pack output/readiness semantics	after screenshot required; UI-042 report may need update	yes	existing download/rendered-report/regenerate/expire behavior remains in scope for preservation only; keep signed download, confirmation, authorization, audit, and OperationRun UX unchanged
Stored Report View	Auditor/report artifact detail	Domain Pattern Surface	repo-verified + browser-verified in Spec 368	existing StoredReportResource detail presentation tests and evidence/report language	after screenshot required if touched; unresolved/UI-048 notes may need update	yes	no destructive action expected; preserve read-only current-report navigation and report capability checks
Evidence Snapshot View	Evidence surface	Manual Review Required until reachable	repo-verified route, browser-blocked in Spec 368	existing EvidenceSnapshotResource and evidence badge/status helpers	after or blocked screenshot required	yes if reachable	existing refresh/expire/create-snapshot behavior remains in scope for preservation only; keep confirmation, authorization, audit, OperationRun UX, and customer-flow hiding/gating unchanged

• Coverage files updated or explicitly not needed:
  • docs/ui-ux-enterprise-audit/route-inventory.md
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md (not needed: no archetype/count model changed)
  • docs/ui-ux-enterprise-audit/page-reports/...
  • docs/ui-ux-enterprise-audit/strategic-surfaces.md (not needed: no new strategic-surface category)
  • docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md (not needed: no follow-up grouping change)
  • docs/ui-ux-enterprise-audit/unresolved-pages.md
  • N/A - no reachable UI surface impact (not applicable: reachable UI surfaces changed)
• Coverage decision for implementation: implementation must update the relevant docs/ui-ux-enterprise-audit/page-reports/... artifact for every materially changed reachable scoped page. no-count-change may only be recorded for route inventory, archetype counts, or design matrix rows when those registries remain unchanged; it is not a substitute for page-report coverage when runtime UI changes.

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes.
• Interaction class(es): status messaging, evidence/report viewers, review-pack/download affordances, limitation copy, diagnostics disclosure, action hierarchy, customer/auditor-safe output language.
• Systems touched: scoped Filament pages/resources/views, existing badge/status helpers, existing evidence/review/report links, existing Review Pack download/report links, existing OperationRun proof links.
• Existing pattern(s) to extend: Spec 370 surface contract, Spec 371 productization pattern direction, Specs 342/344 Customer Review Workspace hierarchy, Spec 347 review-pack output readiness semantics, existing BadgeCatalog/BadgeRenderer, existing policy and UI enforcement helpers.
• Shared contract / presenter / builder / renderer to reuse: existing artifact truth, badge, review-output, evidence, resource URL, OperationRun link, and policy/capability helpers. Any new helper must be page-local or scoped to the selected surfaces.
• Why existing paths are sufficient or insufficient: existing truth sources are sufficient for the v1 safety pass. The likely gap is presentation hierarchy and copy, not domain truth.
• Allowed deviation and why: a small scoped view model/helper is allowed only if it replaces duplicated page/view logic across the selected review/report/evidence surfaces. It must stay derived-only and must not become a generic UI framework.
• Consistency impact: readiness labels, limitations, evidence basis, report/download labels, diagnostics labels, and primary next actions must use one customer/auditor-safe vocabulary across scoped surfaces.
• Review focus: no raw IDs, provider payloads, OperationRun internals, internal reason families, write-gate/hard-blocker terms, or debug/troubleshooting language in default customer/auditor views.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: existing proof/deep-link display only; no new operation start, completion, dedupe, queueing, terminal notification, or lifecycle behavior.
• Shared OperationRun UX contract/layer reused: existing OperationRun links and related resource routes.
• Delegated start/completion UX behaviors: N/A for new starts.
• Local surface-owned behavior that remains: customer-safe explanation that operation proof is secondary diagnostics/provenance, not the primary evidence claim.
• 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/platform seam.
• Boundary classification: platform-core presentation over existing review, evidence, report, and artifact truth.
• Seams affected: customer/auditor labels and visibility only; no Graph contracts, provider credentials, provider dispatch, or provider scope semantics.
• Neutral platform terms preserved or introduced: workspace, environment, review, evidence, review pack, stored report, limitations, findings, accepted risk, diagnostics.
• Provider-specific semantics retained and why: only where existing customer-safe evidence/report content already contains provider-specific facts. Provider IDs/payloads stay out of default views.
• Why this does not deepen provider coupling accidentally: no new Graph call, provider schema, provider vocabulary, provider model, or provider capability path is introduced.
• Follow-up path: Diagnostic Surface Separation or Provider Connection readiness productization remains separate if provider/debug language still appears in non-scoped pages.

UI / Surface Guardrail Impact

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 viewport	yes	Native Filament page plus existing Blade composition	customer-safe review consumption, evidence/report links	page payload, URL-query	no	Existing route only
Environment Review detail first viewport	yes	Filament Resource View/Infolist or existing detail composition	review status/evidence/limitations	detail payload	no	Existing route only
Review Pack detail first viewport	yes	Filament Resource View/Infolist or existing detail composition	output readiness, disclosure, download	detail payload/actions	no	Generator/disclosure policy unchanged
Stored Report detail first viewport	yes	Filament Resource View/Infolist or existing detail composition	report readiness, evidence, limitations	detail payload/actions	no	Storage/report generation unchanged
Evidence Snapshot detail, conditional	yes if reachable	Filament Resource View/Infolist	evidence proof vs diagnostics	detail payload/actions	no	If blocked, document and defer

Decision-First Surface Role

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	Customer/auditor/operator decides what needs review, download, or acknowledgement	outcome, readiness, decision-needed findings, accepted risks, evidence/report pack, limitations, primary action	detailed review, evidence, report pack, diagnostics	Primary workspace handoff surface	customer review consumption	removes cross-page reconstruction
Environment Review View	Primary/Secondary hybrid	Reader decides whether the review outcome is trustworthy and what remains limited	review outcome, scope/period, decision-needed items, evidence basis, limitations	sections, source refs, technical metadata, operation proof	Primary for one released review	released-review detail	makes review record read as output
Review Pack View	Auditor Surface	Reader verifies whether the pack is ready/shareable and what it contains	pack readiness, included sections, evidence basis, disclosure/limitations, download state	metadata, operation proof, renderer/storage details	Secondary artifact proof	review-pack output	keeps artifact truth clear
Stored Report View	Auditor Surface	Reader verifies report identity, readiness, scope, evidence, and limitations	report type/title, subject/scope, readiness, evidence basis, primary download/view	storage metadata, audit refs, technical report metadata	Secondary artifact proof	stored-report consumption	avoids storage-object framing
Evidence Snapshot View	Evidence Surface	Reader verifies what evidence was captured and what it supports	subject, evidence type, captured at, readiness, limitations, related review/report	raw provider object, operation context, diagnostics	Primary evidence detail if reachable	evidence proof	separates proof from diagnostics

Audience-Aware Disclosure

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, auditor, operator-as-facilitator, support where authorized	outcome, decision-needed items, accepted risks, evidence/report availability, limitations	collapsed secondary	raw JSON, provider payloads, internal IDs, OperationRun context	review decisions / download review pack / view evidence depending state	raw/support detail and operator-only repair actions	readiness appears once; lower sections add proof
Environment Review View	customer, auditor, operator-as-facilitator	review outcome, period/scope, evidence basis, limitations, primary action	sidebar/details	raw refs, source payloads, OperationRun internals	open evidence / open pack / review limitations	technical metadata and diagnostics	lifecycle truth appears once
Review Pack View	customer, auditor, operator	pack readiness, contents, evidence basis, limitations, download state	secondary details	renderer/storage internals and operation proof	download/view pack when ready; review limitations when not	regenerate/expire/support actions if not primary	output readiness not repeated as peer cards
Stored Report View	customer, auditor, operator	report identity, disclosure/readiness, subject/scope, evidence basis, limitations	secondary details	storage metadata and raw report internals	download/view report	technical report metadata and raw IDs	report readiness owns first viewport
Evidence Snapshot View	auditor, customer, operator	subject, evidence type, capture date, readiness, limitations, related review/report	secondary/collapsed	raw provider object, internal IDs, operation context	view/download evidence if allowed	raw payload and diagnostics	evidence state distinct from diagnostics

UI/UX Surface Classification

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 review, review decisions, or download pack	primary action in decision zone	N/A	proof/detail links below first decision	existing acknowledgement/create-next-review actions preserved, not expanded	/admin/reviews/workspace	existing review/evidence/pack/report routes	workspace shell + visible environment filter	Customer review	outcome, readiness, decisions, accepted risks, evidence, limitations	none
Environment Review View	Detail / Report	Customer/auditor review detail	inspect review outcome and evidence basis	detail page primary action	N/A	section/evidence links in supporting details	existing refresh/publish/create-next/archive/export actions preserved, not expanded	existing EnvironmentReviewResource index	existing EnvironmentReviewResource view	workspace/environment route	Review	outcome, scope, evidence, limitations	none
Review Pack View	Detail / Artifact	Auditor output artifact	download or verify pack readiness	detail header or first decision card	N/A	metadata/proof below readiness	existing high-impact actions remain out of first viewport	existing ReviewPackResource index	existing ReviewPackResource view	workspace/environment route	Review pack	readiness, contents, evidence, limitations	none
Stored Report View	Detail / Artifact	Auditor report artifact	download or view report	detail header or first decision card	N/A	storage/audit metadata below readiness	no destructive action expected; read-only navigation preserved	existing StoredReportResource index	existing StoredReportResource view	workspace/environment route	Stored report	report type, scope, readiness, evidence	none
Evidence Snapshot View	Detail / Evidence	Evidence proof	inspect evidence or document blocked reachability	detail page primary action	N/A	raw/support evidence in technical details	existing refresh/expire/create-snapshot actions preserved, not expanded	existing EvidenceSnapshotResource index	existing EvidenceSnapshotResource view	workspace/environment route	Evidence snapshot	subject, type, captured at, limitations	conditional reachability

Operator Surface Contract

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 what can be reviewed/shared or what needs decision	customer-safe review hub	What is ready and what needs customer decision?	outcome, readiness, decision-needed findings, accepted risks, evidence/report pack, limitations	raw payloads, OperationRun internals, provider/debug detail	review readiness, evidence state, pack/report availability, accepted-risk accountability	read-mostly consumption; existing acknowledgement/create-next-review actions preserved only	review decisions / view evidence / download pack	existing confirmed/audited acknowledgement and create-next-review paths preserved
Environment Review View	Customer/auditor, MSP operator	inspect a released review and limitations	review detail	What does this review conclude and what proof supports it?	outcome, period/scope, evidence basis, limitations, decision-needed items	source refs, raw context, operation metadata	lifecycle, readiness, evidence completeness, output availability	read-mostly detail; existing lifecycle/export actions preserved only	open evidence / open pack / review limitations	existing confirmed/audited refresh, publish, create-next, archive, and export paths preserved
Review Pack View	Auditor/customer, MSP operator	verify and download a review output artifact	artifact detail	Is this pack ready and what does it include?	pack status, included sections, evidence basis, limitations, download state	renderer/storage metadata, operation proof	artifact status, disclosure, evidence basis, expiry	existing export/download only	download/view pack	existing regenerate/expire if present must stay confirmed/authorized/audited
Stored Report View	Auditor/customer, MSP operator	verify and download a report artifact	artifact detail	What report is this and what evidence/limitations apply?	report title/type, subject/scope, readiness, evidence basis, limitations	storage metadata, raw/internal report details	report status, disclosure/readiness, evidence basis	existing read-only open-current-report navigation only	download/view report	no destructive action in current repo; preserve report capability checks
Evidence Snapshot View	Auditor/customer, MSP operator	verify what evidence was captured and what it supports	evidence detail	What does this evidence prove and what are its limits?	subject, type, captured at, readiness, limitations, related review/report	raw provider object, operation context, internal IDs	evidence status, capture freshness, customer-safe boundary	read-mostly evidence; existing refresh/expire/create-snapshot actions preserved only	view/download evidence if allowed	existing confirmed/audited refresh, expire, and create-snapshot paths preserved

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no.
• New persisted entity/table/artifact?: no runtime persistence. Spec-local artifacts only.
• New abstraction?: no framework. Optional narrow, derived, scoped presentation helper only if implementation proves duplicated page logic would otherwise drift.
• New enum/state/reason family?: no. Labels derive from existing review/evidence/pack/report truth.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: customer/auditor readers need a trustworthy handoff path that does not require operator/debug knowledge.
• Existing structure is insufficient because: the truth exists across separate review, pack, report, evidence, and proof pages, but customer-safe hierarchy and diagnostics separation are not uniformly applied.
• Narrowest correct implementation: page-local productization over the selected existing surfaces plus screenshots/checklists.
• Ownership cost: focused tests, bounded browser smoke, screenshots, and spec-local validation artifacts.
• Alternative intentionally rejected: customer portal shell, output engine rewrite, generic evidence framework, new readiness table/status family, and broad diagnostic refactor.
• Release truth: current-release sellability and trust hardening.

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 server-rendered state, RBAC/context, false-claim prevention, and action visibility; Browser for first-viewport hierarchy, customer-safe copy, diagnostics collapse, and screenshots.
• Validation lane(s): confidence + browser + git diff --check; Pint dirty if PHP changes.
• Why this classification and these lanes are sufficient: the work is UI/productization over existing persisted truth. Focused Feature/Livewire tests prove data/action safety, while Browser smoke proves rendered hierarchy and absence of default diagnostics/internal language.
• New or expanded test families: implemented Spec372CustomerAuditorSurfaceSafetyTest.php and Spec372CustomerAuditorSurfaceSafetySmokeTest.php.
• Fixture / helper cost impact: reuse existing review-output browser fixture and existing factories/helpers. No broad seed, full workspace default, provider setup, or shared helper widening unless explicit and documented.
• Heavy-family visibility / justification: one bounded Browser smoke family is expected because the scoped surfaces are customer/auditor strategic output surfaces.
• Special surface test profile: customer-safe strategic review surface + artifact/evidence detail surfaces.
• Standard-native relief or required special coverage: special coverage required for no raw IDs/default OperationRun internals/provider payloads/debug terms, visible limitations, one primary action, and diagnostics collapse.
• Reviewer handoff: verify no customer-ready/auditor-ready/export-ready claims without repo-backed truth, no out-of-scope operator page refactors, and no broad auth/routing fix for Evidence Snapshot.
• Budget / baseline / trend impact: none expected beyond a bounded browser smoke.
• Escalation needed: document-in-feature for contained reachability or copy tradeoffs; follow-up-spec for structural diagnostic fixture gaps; reject-or-split if scope expands into backend/report/portal/workflow changes.
• Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec372
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=CustomerReview
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=EnvironmentReview
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ReviewPack
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=StoredReport
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=EvidenceSnapshot
  • cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec372CustomerAuditorSurfaceSafetySmokeTest.php --compact
  • cd apps/platform && ./vendor/bin/sail pint --dirty
  • git diff --check

User Scenarios & Testing (mandatory)

User Story 1 - Customer sees the outcome and next action first (Priority: P1)

A customer or operator-as-facilitator opens Customer Review Workspace and sees the review outcome/readiness, decision-needed findings, accepted risks, evidence/report availability, visible limitations, and exactly one dominant customer-safe next action before diagnostics or internal metadata.

Why this priority: This is the clearest customer sellability and false-calmness risk.

Independent Test: Render the workspace with released review, limitation, evidence, pack, finding, and accepted-risk states; assert the first viewport is outcome-first and no raw/internal language appears by default.

Acceptance Scenarios:

1. Given a released review with evidence and a ready review pack, When the user opens Customer Review Workspace, Then the first viewport shows readiness, evidence/report availability, limitations if any, and one primary action.
2. Given findings or accepted risks require customer attention, When the page renders, Then they are visible as customer-safe decision items and not hidden in diagnostics.
3. Given technical detail exists, When the default view renders, Then raw/internal detail is collapsed, demoted, or capability-gated.

User Story 2 - Auditor reads review detail as an output, not an internal record (Priority: P1)

A customer or auditor opens an Environment Review detail and can understand outcome, scope, evidence basis, limitations, decision-needed items, and the safe next action without parsing lifecycle repetition or operation internals.

Why this priority: Environment Review View is the source review detail behind customer handoff and must not read like an internal admin record.

Independent Test: Render an existing EnvironmentReviewResource view and assert outcome/evidence/limitations precede technical metadata, repeated lifecycle/status copy is reduced, and diagnostics are secondary.

Acceptance Scenarios:

1. Given a released review, When the detail page opens, Then outcome/readiness and scope are first, followed by evidence basis and limitations.
2. Given review lifecycle and source metadata exist, When the default view renders, Then they are sidebar/detail content rather than primary decision content.
3. Given operation proof exists, When the page renders, Then it is secondary proof and not required for customer understanding.

User Story 3 - Auditor verifies pack and report readiness without storage/debug framing (Priority: P1)

A customer or auditor opens Review Pack and Stored Report details and sees artifact readiness, included scope, evidence basis, limitations, and download/view availability before storage metadata, renderer internals, or support diagnostics.

Why this priority: Review Pack and Stored Report are the shareable proof surfaces; misleading or overly technical framing undermines auditor trust.

Independent Test: Render ready and not-ready pack/report states; assert readiness/download labels are state-aware and limitations are visible without changing generation or renderer logic.

Acceptance Scenarios:

1. Given a ready Review Pack, When the detail page opens, Then pack readiness, included sections, evidence basis, limitations, and the download/view action are visible first.
2. Given a non-ready or limitations-bearing pack/report, When the detail page opens, Then the page does not imply customer-ready sharing and explains the limitation.
3. Given report storage metadata exists, When the default Stored Report view renders, Then it is secondary and the report subject/scope/readiness own the first viewport.

User Story 4 - Evidence Snapshot is productized if reachable, or blocked honestly if not (Priority: P2)

An auditor can either reach Evidence Snapshot detail and see evidence subject/type/readiness/limitations with diagnostics separated, or the package documents that current fixtures do not reach it and defers fixture coverage.

Why this priority: Evidence is central to auditor trust, but fixing auth/routing broadly would exceed this safety pass.

Independent Test: Use existing smoke-login/browser fixture. If reachable, render and test the evidence page. If blocked, capture/document the blocked state and add follow-up recommendation.

Acceptance Scenarios:

1. Given Evidence Snapshot detail is reachable with existing fixtures, When it opens, Then subject, type, captured-at, readiness, related review/report, and limitations appear before raw payloads.
2. Given Evidence Snapshot detail redirects or is forbidden with existing fixtures, When browser verification runs, Then the blocked route, final URL, and follow-up are documented without broad auth/routing changes.

User Story 5 - Existing RBAC, action safety, and completed surfaces remain intact (Priority: P1)

An authorized user sees capability-appropriate customer/auditor actions, while unauthorized or cross-scope users cannot infer records; completed operator surfaces from Spec 371 and other out-of-scope pages are not refactored.

Why this priority: Customer-safe polish must not weaken workspace/tenant isolation, destructive-action safety, or completed operator workflows.

Independent Test: Run targeted authorization/action tests and inspect git diff to confirm out-of-scope app surfaces are untouched unless an unavoidable shared partial impact is documented.

Acceptance Scenarios:

1. Given a non-member or wrong-environment actor, When they try to access scoped detail pages, Then existing deny-as-not-found behavior remains.
2. Given a member lacks a capability, When a download/diagnostic action is rendered or executed, Then existing capability behavior remains enforced.
3. Given no new destructive action is in scope, When implementation completes, Then no new destructive/high-impact action was added without a spec/plan update.

Edge Cases

• Evidence Snapshot remains unreachable in current smoke fixture.
• A shared partial is used by both scoped customer/auditor pages and out-of-scope operator pages.
• A page has no current review, report, pack, or evidence artifact.
• A report/pack exists but is expired, incomplete, not customer-ready, or limitations-bearing.
• Raw/provider/operation data is needed by support but unsafe for customer/auditor default view.
• Existing tests assert old copy that is replaced by safer customer/auditor wording.

Functional Requirements

• FR-001: Each reachable scoped page MUST lead with outcome/readiness, evidence availability, limitations, and one customer/auditor-safe next action.
• FR-002: Default customer/auditor views MUST NOT expose raw IDs, internal IDs, provider payloads, raw JSON, operation context payloads, internal reason families, stack traces, debug wording, or OperationRun internals.
• FR-003: Technical detail MUST be collapsed, demoted to aside/details, or capability-gated outside the first viewport.
• FR-004: Evidence and diagnostics MUST be visually and verbally separated. Evidence is proof for a review/report claim; diagnostics are technical troubleshooting.
• FR-005: Limitations MUST remain visible and written in calm customer/auditor language.
• FR-006: Each scoped page MUST have one dominant customer/auditor-safe primary action and at most two secondary actions in the first viewport.
• FR-007: Repeated readiness/status phrases MUST be reduced so one first-viewport block owns the current decision and later sections add proof instead of restating the same truth.
• FR-008: Zero/no-attention card spam MUST be suppressed unless zero is itself required proof for the page decision.
• FR-009: Customer Review Workspace MUST preserve visibility for decision-needed findings, accepted risks, evidence/report pack availability, and limitations.
• FR-010: Environment Review View MUST present review outcome, scope/period, evidence basis, decision-needed items, accepted risks where relevant, and limitations before technical metadata.
• FR-011: Review Pack View MUST preserve disclosure policy and output-readiness truth, keep evidence basis and limitations visible, and avoid customer-ready claims when the pack is not ready.
• FR-012: Stored Report View MUST present report title/type, subject/scope, readiness/disclosure state, evidence basis, limitations, and download/view state before storage metadata.
• FR-013: Evidence Snapshot View MUST be productized only if reachable with existing fixtures; if not reachable, the implementation MUST document the blocked state and recommend Evidence Surface Browser Fixture Coverage v1.
• FR-014: Existing RBAC, policy, capability, signed download, audit, and destructive/high-impact action behavior MUST remain intact.
• FR-015: The implementation MUST document source audit, affected files, customer surface contracts, screenshot index, implementation notes, browser verification, customer safety checklist, and validation results in the spec package.

Non-Functional Requirements

• NFR-001: No Graph/provider calls during page render.
• NFR-002: No migrations, new tables, new persisted readiness state, new enum/status family, new OperationRun type, new queue family, new scheduler, or storage topology change.
• NFR-003: Filament v5 and Livewire v4.0+ APIs only.
• NFR-004: Panel provider registration remains unchanged in apps/platform/bootstrap/providers.php.
• NFR-005: No new Filament asset registration is expected; if assets are introduced unexpectedly, update spec/plan first and document php artisan filament:assets.
• NFR-006: Browser proof must use the existing smoke-login/browser fixture path where available; do not invent a new auth flow.
• NFR-007: Customer/auditor copy must avoid unsupported certification, compliance, or customer-ready claims.

Out Of Scope

• Operator View Surfaces from Spec 371.
• Environment Dashboard, Operations Hub, OperationRun View, Backup Set View, Restore Run View, Baseline Profile View.
• Provider Connections, Environment Diagnostics, Required Permissions, System Panel.
• Review generation, evidence generation, Review Pack generator, Stored Report storage, disclosure policy logic, Report Renderer, migrations, backfills, legacy compatibility, external support/PSA handoff, billing/entitlements, private AI governance, new top-level navigation, and new customer portal shell.

Required Preparation And Implementation Artifacts

• artifacts/source-audit-summary.md
• artifacts/affected-files.md
• artifacts/customer-surface-contracts.md
• artifacts/before-after-screenshot-index.md
• artifacts/implementation-notes.md
• artifacts/browser-verification-report.md
• artifacts/customer-safety-checklist.md
• artifacts/validation-report.md
• artifacts/screenshots/

Acceptance Criteria

• AC-001: Spec 370 customer/auditor contract is applied to each reachable scoped page.
• AC-002: Spec 371 implementation patterns are reviewed and summarized, with customer/auditor-specific adaptations documented.
• AC-003: Customer Review Workspace is calmer, outcome-first, and still shows customer decisions, accepted risks, evidence/report access, limitations, and one primary action.
• AC-004: Environment Review View reads like a customer/auditor review output, not an internal record.
• AC-005: Review Pack View preserves output readiness/disclosure truth and keeps evidence/limitations/action hierarchy clear.
• AC-006: Stored Report View is auditor-ready with report scope/readiness/evidence/limitations first.
• AC-007: Evidence Snapshot is either productized if reachable or documented as blocked with a follow-up recommendation.
• AC-008: Customer safety checklist exists and covers every scoped page.
• AC-009: No intentional out-of-scope operator/diagnostic/system surface refactor occurs.
• AC-010: After screenshots or blocked screenshots/reasons exist for every scoped page.
• AC-011: Targeted tests and git diff --check pass, or limitations are explicitly documented.

Success Criteria

• Customer/auditor readers can answer “What is the outcome, what evidence supports it, what limitations exist, and what should I do next?” within the first viewport on every reachable scoped surface.
• No default scoped surface requires understanding OperationRuns, provider payloads, raw JSON, or internal IDs.
• Review Pack and Stored Report outputs remain truthful and do not overclaim customer/auditor readiness.
• Evidence Snapshot reachability is no longer silently unknown: it is either verified/productized or blocked with a named follow-up.
• Scope remains bounded to the existing surfaces and no backend truth is invented.

Risks

• Hiding necessary limitations: mitigated by requiring limitations visible by default.
• Breaking trust through over-simplification: mitigated by preserving evidence basis and disclosure/readiness truth.
• Shared components affect out-of-scope pages: mitigated by inspecting usage and preferring page-local changes.
• Evidence Snapshot remains blocked: mitigated by documenting blocked state and deferring fixture coverage.
• Old tests assert replaced copy: mitigated by updating only stale copy assertions while preserving authorization/state assertions.
• 371 pattern copied too literally: mitigated by reusing structure, not operator wording.

Assumptions

• The current branch base already includes completed Spec 371 runtime work and artifacts.
• Existing smoke-login/review-output browser fixture remains the preferred browser auth/data path.
• Customer/auditor output safety can be improved through presentation hierarchy and copy without changing review/evidence/report domain truth.
• Evidence Snapshot reachability is allowed to remain blocked if current fixtures still redirect or forbid access.

Open Questions

• None blocking. Evidence Snapshot reachability is intentionally conditional and decided by repo/browser verification during implementation.

Follow-Up Spec Candidates

• Spec 373 - Diagnostic Surface Separation v1.
• Evidence Surface Browser Fixture Coverage v1, if Evidence Snapshot remains blocked.
• UI Bloat Regression Guard v1, after this second consumer validates stable guard patterns.
• Localization v1 Customer-facing Surfaces, after customer/auditor safety hierarchy stabilizes.