TenantAtlas/specs/337-evidence-review-pack-product-process-flow-alignment/spec.md

Feature Specification: Spec 337 - Evidence Path / Review Pack Product Process Flow Alignment

Feature Branch: 337-evidence-review-pack-product-process-flow-alignment Created: 2026-05-30 Status: Draft Type: Runtime UX alignment / Product Process Flow consumer / Evidence and Review Pack productization Runtime posture: Reuse existing Spec 332 Product Process Flow system. No backend evidence, report, review-pack, export, queue, or storage rewrite. No new persisted truth. Input: User-provided Spec 336 draft, repo-truth reconciled to Spec 337 because 336-baseline-compare-product-process-flow-alignment already exists in this repo.

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

• Problem: TenantPilot has repo-backed evidence snapshots, stored reports, review packs, customer review workspace signals, OperationRun proof, and signed downloads, but the path from technical evidence to customer- or auditor-consumable output is not expressed as one decision-first readiness flow.
• Today's failure: Operators must infer readiness from raw artifact lists, internal report names, timestamps, and generated files instead of seeing what exists, what is missing, what is stale, what is customer-safe, what can be exported, and the next action.
• User-visible improvement: Evidence and Review Pack surfaces answer in the first screen: Status, Reason, Impact, Primary next action, Evidence readiness flow, Available proof, Customer-safe output state, Export/download state, and collapsed diagnostics.
• Smallest enterprise-capable version: Reuse Spec 332's Product Process Flow pattern on existing Evidence Overview, Review Pack, Stored Report, and Customer Review Workspace evidence sections without changing generation engines or persistence.
• Explicit non-goals: New evidence backend, report engine, review-pack engine, storage backend, export format, PDF/ZIP generation logic, OperationRun model changes, migrations, packages, queue/scheduler changes, Customer Review Workspace redesign, Baseline Compare changes, Restore changes, billing/entitlement changes, generic document management.
• Permanent complexity imported: A small page/surface presenter only if needed, a feature-local state contract, focused Feature tests, one browser smoke file, and screenshot artifacts. No new tables, enums, status family, or platform workflow framework.
• Why now: Restore and Baseline Compare now consume the Product Process Flow pattern; Evidence/Review Packs are the next high-value consumer because they are the customer-safe/auditor-facing continuation of proof and review workflows.
• Why not local: Copy-only fixes would leave readiness, proof, customer-safe output, and export states scattered across evidence and review surfaces. A shared flow contract prevents another local readiness dialect.
• Approval class: Core Enterprise
• Red flags triggered: Customer-safe trust language, audit/evidence disclosure, reachable UI surface change, cross-workspace leakage risk. Defense: use repo-backed states only, collapse raw diagnostics, preserve existing RBAC/policies, and test false-claim prevention.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 1 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 10/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: canonical-view plus tenant/environment-owned artifacts.
• Primary Routes:
  • Evidence Overview: /admin/evidence/overview (admin.evidence.overview, App\Filament\Pages\Monitoring\EvidenceOverview)
  • Customer Review Workspace evidence path: /admin/reviews/workspace (App\Filament\Pages\Reviews\CustomerReviewWorkspace), only if needed for alignment
  • Review Pack list/detail: /admin/workspaces/{workspace}/environments/{environment}/review-packs
  • Review Pack signed download: /admin/review-packs/{reviewPack}/download (admin.review-packs.download)
  • Evidence Snapshot and Stored Report detail surfaces, only as linked proof surfaces
  • Environment Review detail/export state, only if needed for review-pack readiness truth
• Data Ownership:
  • Workspace-owned and environment-owned: EvidenceSnapshot, EvidenceSnapshotItem, StoredReport, ReviewPack, EnvironmentReview, EnvironmentReviewSection, OperationRun.
  • Signed download/export artifact truth is stored on ReviewPack.file_disk, file_path, file_size, sha256, generated_at, expires_at, and status.
  • Customer-safe readiness is derived from existing Customer Review Workspace review/package readiness; no separate customer_safe persisted flag is introduced.
• RBAC:
  • Workspace membership and managed environment access remain mandatory.
  • Existing capabilities gate actions and links: EVIDENCE_VIEW, EVIDENCE_MANAGE, REVIEW_PACK_VIEW, REVIEW_PACK_MANAGE, ENVIRONMENT_REVIEW_VIEW, ENVIRONMENT_REVIEW_MANAGE, report-specific capabilities, and OperationRun view capability.
  • Non-member or cross-workspace access remains not-found; member-but-missing-capability follows existing hidden/disabled/403 conventions.

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: preserve current environment filter behavior. Evidence Overview must preselect or preserve the active managed environment when provided, otherwise show authorized workspace-scoped evidence without leaking artifacts from inaccessible environments.
• Explicit entitlement checks preventing cross-tenant leakage: all artifact links and generated actions must continue to use existing policies/capability checks and route-model scoping. No /admin/t routes or legacy tenant query aliases may be introduced.

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

If any box except "No UI surface impact" is checked, complete the UI/Productization Coverage section below. "No UI surface impact" MUST NOT be checked together with another impact box; if a guarded file path changes for non-surface reasons, keep only "No UI surface impact" checked and explain the rationale below.

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: Evidence Overview (App\Filament\Pages\Monitoring\EvidenceOverview), Customer Review Workspace evidence path (App\Filament\Pages\Reviews\CustomerReviewWorkspace, only if needed), Review Pack Resource list/detail, and linked proof surfaces.
• Current or new page archetype: Existing evidence/report/review workbench and customer review workspace surfaces; archetypes unchanged.
• Design depth: Strategic Surface for Evidence Overview and Customer Review Workspace; Domain Pattern Surface for Review Pack/Stored Report/Evidence Snapshot detail proof.
• Repo-truth level: repo-verified (see repo-truth-map.md).
• Existing pattern reused: Spec 332 Product Process Flow system, Spec 329 evidence disclosure/proof-first workbench, Spec 326 Customer Review Workspace decision/readiness sections, existing OperationRun proof links.
• New pattern required: none. A small feature presenter is allowed only if it centralizes repo-backed state mapping and does not become a generic workflow engine.
• Screenshot required: yes, under specs/337-evidence-review-pack-product-process-flow-alignment/artifacts/screenshots/.
• Page audit required: no by default; route/archetype unchanged. Feature-local screenshots and tests are required proof. If implementation changes navigation/archetype, update the UI audit artifacts in the implementation PR.
• Customer-safe review required: yes. This spec touches customer/auditor consumption language and must not claim customer-safe, auditor-ready, export-ready, or complete unless repo-backed.
• Dangerous-action review required: no destructive action change. Existing generate/export/download/expire semantics remain governed by current actions, confirmations where already required, policies, and audits.
• 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
• No-impact rationale when applicable: N/A. UI impact exists; coverage artifacts may remain unchanged only if implementation preserves route family, navigation, and archetype.

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

• Cross-cutting feature?: yes
• Interaction class(es): decision cards, status messaging, Product Process Flow steps, action links, OperationRun proof links, evidence/report/review artifact viewers, collapsed diagnostics.
• Systems touched: Spec 332 Product Process Flow system; Evidence Overview proof workbench; Customer Review Workspace evidence path; Review Pack Resource; Stored Report Resource; Evidence Snapshot Resource; OperationRun link helpers.
• Existing pattern(s) to extend: Spec 332 process flow, Spec 329 proof-first evidence disclosure, Spec 326 customer review readiness, OperationRunLinks, OperationUxPresenter, UiEnforcement, BadgeCatalog / BadgeRenderer.
• Shared contract / presenter / builder / renderer to reuse: Product Process Flow render conventions from Spec 332. Use existing artifact and badge presenters where available.
• Why the existing shared path is sufficient or insufficient: sufficient for step-based readiness and proof separation; insufficient only if current components cannot express the six evidence-chain steps, in which case a bounded renderer extension is allowed.
• Allowed deviation and why: no new framework. Feature-local mapping may exist because evidence readiness combines several existing artifacts without a persisted lifecycle table.
• Consistency impact: Restore, Baseline Compare, Evidence, and Review Packs use the same Status/Reason/Impact/Next action order, honest unavailable/deferred states, and collapsed diagnostics.
• Review focus: no fake customer-safe/auditor-ready/export-ready claims, no duplicate readiness blocks, no raw JSON by default, no cross-workspace links.

OperationRun UX Impact (mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an OperationRun; otherwise write N/A - no OperationRun start or link semantics touched)

• Touches OperationRun start/completion/link UX?: yes, by presenting existing evidence/report/review-pack generation proof and operation deep links.
• Shared OperationRun UX contract/layer reused: existing OperationRunLinks, OperationUxPresenter, OperationRunService, and current service/job operation lifecycle.
• Delegated start/completion UX behaviors: existing queued toast, "View operation" links, operation status/outcome, and signed artifact links remain delegated to current services and helpers.
• Local surface-owned behavior that remains: state-specific explanation copy and artifact proof placement.
• Queued DB-notification policy: no change; no new queued DB notification.
• Terminal notification path: unchanged.
• Exception required?: none.

Provider Boundary / Platform Core Check (mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write N/A - no shared provider/platform boundary touched)

• Shared provider/platform boundary touched?: no
• Boundary classification: N/A
• Seams affected: N/A
• Neutral platform terms preserved or introduced: workspace, environment, review, evidence snapshot, stored report, review pack, customer-safe output, export/download.
• Provider-specific semantics retained and why: existing report labels such as Entra admin roles may remain only where repo-backed stored reports already expose them.
• Why this does not deepen provider coupling accidentally: the flow is artifact/process based and does not add provider contracts or provider-specific truth.
• Follow-up path: none.

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
Evidence Overview: decision card, readiness flow, proof panel, collapsed diagnostics	yes	Native Filament + shared primitives + existing Blade workbench	Product Process Flow, evidence disclosure, OperationRun proof	page, table context, URL query	no	Strategic surface, bounded alignment
Customer Review Workspace evidence path: truthful customer-safe/export state alignment, if needed	yes	Native Filament + existing workspace Blade workbench	customer-safe readiness, review pack package state	page, URL query	no	Customer-facing consumption path; only adjust if needed
Review Pack Resource list/detail: readiness/export proof copy or placement, if needed	yes	Native Filament resource	review pack artifact proof, signed download	list/detail/header actions	no	No action semantics change

Summary

Align the Evidence Path and Review Pack experience with the reusable Product Process Flow system introduced in Spec 332.

TenantPilot already has foundations for:

• evidence snapshots
• stored reports
• review packs
• tenant/environment reviews
• customer review workspace
• audit log and OperationRun proof
• report export/download

Spec 337 productizes the visible chain:

1. Source data selected
2. Evidence snapshot
3. Stored report
4. Review pack
5. Customer-safe output
6. Export / delivery

The first screen must answer: is this evidence package ready for customer or auditor consumption?

The answer must include:

• Status
• Reason
• Impact
• Primary next action
• Evidence readiness flow
• Available proof
• Customer-safe output state
• Export/download state
• Diagnostics collapsed

Repo-Truth First Requirement

Before runtime changes, the spec requires:

• specs/337-evidence-review-pack-product-process-flow-alignment/repo-truth-map.md
• specs/337-evidence-review-pack-product-process-flow-alignment/evidence-review-pack-state-contract.md

These files classify every data point as repo-verified, derived from existing model, foundation-real, not available, or deferred. No unavailable evidence, report, export, or customer-safe state may be invented.

Scope

In Scope

• Evidence Overview readiness/product-flow alignment.
• Review Pack generation/status/readiness presentation.
• Stored Report and Evidence Snapshot proof/readiness links.
• Customer Review Workspace evidence path section only if needed to preserve the same flow language.
• Review Pack export/download readiness.
• OperationRun proof for evidence/report/review-pack generation and export.
• Diagnostics collapsed by default.
• Spec 337 feature tests, browser smoke, and screenshots.
• Spec 337 state contract and repo-truth artifacts.

Out of Scope

• New evidence snapshot backend.
• New report generation engine.
• New review pack engine.
• New storage backend.
• New export format.
• New PDF/ZIP generation logic.
• New OperationRun model changes.
• New migrations unless a later implementation proves they are strictly required and receives explicit review.
• New packages.
• New queue/scheduler changes.
• Customer Review Workspace redesign.
• Baseline Compare changes.
• Restore changes.
• Billing/entitlement changes.
• Generic document management.

Product Principles

• Evidence-first.
• Customer-safe consumption.
• Decision-first.
• Auditability.
• OperationRun proof-aware.
• Workspace/environment isolation.
• Diagnostics collapsed.
• Raw artifact metadata secondary.
• No false customer-safe claim.
• No false auditor-ready claim.
• No false export-ready claim.

Avoid raw stored-report tables as the main UX, raw evidence IDs as primary labels, export file dumps, technical payload default views, generic readiness claims, customer-facing raw diagnostics, duplicated readiness blocks, and nested card-heavy layouts.

Required Product Flow

Evidence / Review Pack uses the Product Process Flow component.

Default flow steps:

1. Source data selected
2. Evidence snapshot
3. Stored report
4. Review pack
5. Customer-safe output
6. Export / delivery

If the repo only supports part of the chain for a surface, unsupported steps render as unavailable or deferred with honest copy.

Step Semantics

• Source data selected: Available, Missing, Stale, Unavailable
• Evidence snapshot: Available, Missing, Generating, Failed, Stale, Unavailable
• Stored report: Available, Missing, Generating, Failed, Unavailable
• Review pack: Available, Required, Generating, Failed, Unavailable
• Customer-safe output: Ready, Needs review, Not ready, Unavailable
• Export / delivery: Available, Required, Generated, Failed, Unavailable

Customer-safe output MUST NOT show Ready unless repo truth supports it for the selected surface. Evidence Overview alone does not create a customer-safe state.

Evidence / Review Pack Product States

At minimum, support the following state family where fixtures are repo-backed:

• Evidence snapshot required.
• Evidence generation in progress.
• Evidence generation failed.
• Stored report required.
• Review pack required.
• Review pack generation in progress.
• Customer-safe review required.
• Customer-safe output ready.
• Review pack export/download available.
• Export unavailable or external delivery not configured.

The exact copy and flow gate states are defined in evidence-review-pack-state-contract.md.

Page Layout

Use a calm main/aside layout where practical.

Default first screen:

• Main: decision card, Evidence readiness flow, readiness summary, review-pack contents/coverage, customer-safe output state.
• Aside: evidence proof, evidence snapshot, stored report, review pack, OperationRun proof, export artifact, diagnostics collapsed.

If an aside convention does not exist on the page, proof state may sit below the decision card but above raw artifact lists.

Decision Card

Required question:

Is this evidence package ready for customer or auditor consumption?

Required fields:

• Status
• Reason
• Impact
• Primary next action

One state-specific primary action is visible. Secondary proof/export links remain secondary.

Evidence Readiness Flow

Expected title: Evidence readiness flow

Expected subtitle: Customer-safe evidence requires source data, evidence snapshot, stored report, review pack, and export readiness.

Rules:

• Use horizontal variant by default if space allows.
• Use vertical variant if the page layout requires stacked flow.
• No duplicate lower readiness blocks.
• No raw artifact placeholders.
• No fake progress.
• No clipped status badges.
• Diagnostics collapsed by default.

Evidence Proof Panel

Create or productize an Evidence Proof panel with these rows:

• Source data
• Evidence snapshot
• Stored report
• Review pack
• Operation proof
• Export artifact
• Customer-safe state
• Diagnostics

Allowed presentation states: Available, Unavailable, Generating, Failed, Stale, Needs review, Ready, Not ready, Collapsed.

Do not claim Customer-safe, Auditor-ready, Export-ready, or Complete unless repo truth supports it.

Review Pack Contents / Coverage

If repo-backed, show a compact coverage summary such as:

• Controls covered
• Findings included
• Accepted risks included
• Evidence snapshots included
• Reports included
• Generated files
• Missing evidence
• Warnings

Only show metrics from repo truth. If unavailable, show: Review pack coverage details are not available for this artifact.

Customer-Safe Output

Separate internal evidence from customer-safe output.

Allowed states:

• Customer-safe output ready
• Customer-safe review required
• Customer-safe output unavailable
• Foundation exists, but customer-safe state is not linked

Customer-safe ready is only allowed when the Customer Review Workspace / Environment Review / current export pack path has a repo-backed ready package and no unresolved readiness blocker for that surface.

Export / Delivery

Show export/download state when repo-backed.

Allowed states:

• Export available
• Export required
• Export generating
• Export failed
• Export unavailable

Actions appear only if authorized:

• Download export
• Regenerate export
• View operation
• Open stored report

External delivery is not configured unless a repo-backed mechanism is discovered in implementation. Do not fake email, PSA, sharing, or portal delivery.

OperationRun Proof

Evidence/report/review-pack generation must show OperationRun proof when available:

• Operation status
• Started at
• Completed at
• Requested by
• Run type
• Result
• Link to operation detail

If unavailable, show: Operation proof unavailable. No generation operation is linked to this artifact.

Diagnostics

Diagnostics are collapsed by default.

Allowed collapsed sections:

• Raw report metadata
• Raw evidence payload
• Generation diagnostics
• Export diagnostics
• Provider diagnostics

Never default-show raw JSON, stack traces, provider secrets, raw OperationRun JSON, or internal exceptions.

Navigation / Context

Preserve workspace/environment/review context.

Allowed actions, only when route- and capability-backed:

• Generate evidence snapshot
• Open evidence snapshot
• Open stored report
• Generate review pack
• Open review pack
• Download export
• View operation proof
• Open customer review workspace
• Return to review

No hardcoded workspace IDs, /admin/t routes, legacy tenant aliases, or context-losing proof/export links.

RBAC / Capabilities

Actions only appear when authorized:

• Generate evidence
• Generate report
• Generate review pack
• Export/download
• Open operation proof
• Open diagnostics
• Open customer review workspace

Unauthorized users must either not see the action or see an unavailable state if repo conventions support that. No new destructive actions are introduced.

Required Tests

Create:

apps/platform/tests/Feature/Filament/Spec337EvidenceReviewPackProductFlowTest.php

Required assertions:

• Missing evidence renders the decision question, Evidence snapshot required, the evidence flow, missing snapshot, unavailable review pack, not-ready customer-safe output, collapsed diagnostics, and no raw JSON.
• Evidence snapshot available / report missing shows snapshot available, stored report required, and no fake review-pack ready claim when fixtures support it.
• Review pack required shows stored report available, review pack required, and the generate review pack action only when authorized.
• Review pack available shows review pack available, customer-safe state truthful, export state truthful, and no false auditor-ready claim.
• Operation proof shows linked generation OperationRun, blocks cross-workspace OperationRun leakage, and shows failed OperationRun as failed proof.
• RBAC/context tests prove unauthorized users cannot generate/export, cross-workspace evidence is not visible, and no legacy tenant alias is used.

Browser Smoke

Create:

apps/platform/tests/Browser/Spec337EvidenceReviewPackProductFlowSmokeTest.php

Browser states:

• missing evidence snapshot
• evidence generating if fixture-supported
• stored report available / review pack missing
• review pack available if fixture-supported
• export unavailable
• diagnostics collapsed
• dark mode if practical

Required screenshots:

• 01-evidence-snapshot-required.png
• 02-evidence-generating.png
• 03-stored-report-required.png
• 04-review-pack-required.png
• 05-review-pack-available.png
• 06-customer-safe-output-state.png
• 07-export-unavailable.png
• 08-diagnostics-collapsed.png
• 09-dark-mode.png

If a state is not reachable, document why; do not fake screenshots.

Acceptance Criteria

Product

• Evidence / Review Pack uses Product Process Flow.
• Decision card is visible.
• Evidence readiness state is clear.
• Review pack state is clear.
• Customer-safe output state is truthful.
• Export/download state is truthful.
• OperationRun proof is visible where available.
• Diagnostics collapsed.
• Raw payload hidden by default.

Truth / Safety

• No fake evidence claim.
• No fake customer-safe claim.
• No fake auditor-ready claim.
• No fake export-ready claim.
• No fake coverage counts.
• OperationRun proof is separated from evidence output.

Context / RBAC

• Workspace/environment/review isolation preserved.
• Capabilities respected.
• No /admin/t.
• No tenant query aliases.
• No cross-workspace evidence leakage.

Validation

• Feature tests pass.
• Browser smoke passes.
• Screenshots captured or unreached states documented.
• Pint passes.
• git diff --check passes.

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
Evidence Overview	Primary Decision Surface	Operator decides whether evidence/review pack work is ready, missing, stale, generating, failed, or exportable	Status, Reason, Impact, Primary next action, Evidence readiness flow, proof summary, customer-safe/export state	raw report metadata, raw evidence payload, operation diagnostics, artifact lists	Primary because it is the evidence proof workbench	Source data -> evidence -> report -> pack -> customer-safe -> export	Removes cross-page inference from files, IDs, and runs
Customer Review Workspace evidence path	Primary customer-safe consumption surface	Operator/customer reviewer decides whether a published review package can be shared or downloaded	Review readiness, evidence path, review pack state, customer-safe state, export availability	diagnostics, operation proof, internal artifact metadata	Primary for customer-safe consumption; only changed if needed	Review -> customer-safe package -> download	Prevents internal evidence from being mistaken for shareable output
Review Pack Resource detail	Secondary Evidence / Diagnostics	Operator inspects a generated pack and export proof	pack status, download availability, evidence snapshot link, operation proof	file metadata, summary/options diagnostics	Secondary because it is artifact detail, not the whole readiness chain	Artifact proof follows workbench decision	Keeps artifact detail from becoming the main readiness UX

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
Evidence Overview	operator-MSP, manager, support reviewer	decision card, readiness flow, proof panel, customer-safe/export state	generation diagnostics, report metadata, operation failure summary	raw evidence payload, raw report payload, stack traces, raw OperationRun JSON	state-specific action: generate evidence, generate report, generate review pack, view operation, review customer output, or download export	raw/support sections collapsed and capability-aware	one top verdict; lower sections add proof only
Customer Review Workspace evidence path	customer-readable, operator-MSP, manager	review readiness, customer-safe state, package/download state, evidence path	internal proof and diagnostics	raw JSON, fingerprints, provider diagnostics, reason ownership	review customer output or download export when repo-backed	diagnostics collapsed; raw/internal detail hidden from customer-safe default path	do not duplicate top readiness with alternate wording
Review Pack Resource detail	operator-MSP, support reviewer	pack status, export/download proof, linked snapshot/review/run	options, summary, file metadata, operation proof	raw package metadata and generation diagnostics	download export or view operation	raw diagnostics collapsed/capability-aware	artifact status does not restate customer-safe readiness unless repo-backed

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
Evidence Overview	Workbench / Monitoring	Evidence and review-pack readiness workbench	Take the next generation/review/export action	explicit action links and artifact deep links	N/A	proof panel / aside	none introduced	/admin/evidence/overview	N/A	workspace + environment filter	Evidence / Review Pack	Status, Reason, Impact, flow, proof, customer-safe/export state	N/A
Customer Review Workspace evidence path	Workbench / Review	Customer-safe review consumption surface	review or download package	workspace page sections + artifact links	N/A	evidence path/proof sections	none introduced	/admin/reviews/workspace	N/A	workspace + environment filter	Customer Review	readiness, package availability, evidence path	N/A
Review Pack Resource	List / Detail	Artifact list/detail	inspect pack or download export	resource row/detail view	existing resource behavior	row/header actions	existing expire action remains grouped/confirmed	/admin/workspaces/{workspace}/environments/{environment}/review-packs	/admin/workspaces/{workspace}/environments/{environment}/review-packs/{record}	workspace + environment route	Review Pack	status, generated/export proof, linked evidence/review/run	N/A

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
Evidence Overview	Workspace manager / governance operator	Decide whether evidence/review pack readiness requires generation, review, proof inspection, or export	Monitoring / decision-first workbench	Is this evidence package ready for customer or auditor consumption?	decision card, readiness flow, proof panel, customer-safe/export state	raw payload, generation diagnostics, failure details	data availability, evidence lifecycle, report availability, pack lifecycle, customer-safe readiness, export artifact availability, operation status/outcome	TenantPilot artifact generation/export only; no Microsoft tenant mutation introduced	generate/open evidence, open stored report, generate/open review pack, view operation, download export	none introduced
Customer Review Workspace evidence path	Customer reviewer / governance operator	Decide whether published review evidence can be shared/downloaded	Review / customer-safe consumption	Is this review package ready to share?	review readiness, evidence path, package/download state	internal diagnostics/proof	review lifecycle, evidence availability, accepted-risk follow-up, package availability	TenantPilot review/export artifacts only	review customer output, download export, open proof	none introduced
Review Pack Resource	Governance operator / support reviewer	Inspect generated pack and export proof	Artifact detail	Is this specific pack generated and downloadable?	pack status, file/download proof, linked snapshot/review/operation	options, summary, diagnostics	pack status, expiration, file availability, operation outcome	TenantPilot review-pack artifacts only	download, regenerate if authorized, view operation	existing expire action; no change

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no
• New abstraction?: yes, only a small presenter/view-model if runtime implementation needs one to avoid scattered Blade/Page state mapping.
• New enum/state/reason family?: no. Presentation states are derived from existing model statuses and the feature-local state contract.
• New cross-domain UI framework/taxonomy?: no. Reuse Spec 332 Product Process Flow.
• Current operator problem: evidence, report, review-pack, customer-safe, and export readiness are repo-real but not assembled into one decision-first flow.
• Existing structure is insufficient because: current surfaces expose proof and artifacts, but the operator still reconstructs readiness across pages, tables, file state, and operations.
• Narrowest correct implementation: derive a single flow model from existing artifacts and render it on the existing surfaces; keep backend generation, storage, OperationRun lifecycle, and route structure unchanged.
• Ownership cost: one focused presenter if needed, one feature state contract, feature/browser tests, and screenshots.
• Alternative intentionally rejected: a new persisted readiness engine, new artifact lifecycle table, new review-pack workflow service, or a generic document-management layer.
• Release truth: current-release UX alignment over existing enterprise evidence foundations.

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

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

• Test purpose / classification: Feature + Browser.
• Validation lane(s): confidence + browser.
• Why this classification and these lanes are sufficient: the risk is state composition, RBAC/context leakage, truthfulness, and visible product flow rendering, not isolated pure functions or backend engine behavior.
• New or expanded test families: Spec337EvidenceReviewPackProductFlowTest and Spec337EvidenceReviewPackProductFlowSmokeTest.
• Fixture / helper cost impact: reuse existing Evidence, ReviewPack, StoredReport, EnvironmentReview, OperationRun, workspace, and managed environment factories/helpers; no new global seeds or heavy defaults.
• Heavy-family visibility / justification: one explicit browser smoke file because this changes a strategic/customer-facing evidence path and screenshots are required.
• Special surface test profile: monitoring-state-page + shared-detail-family + customer-safe consumption path.
• Standard-native relief or required special coverage: dedicated coverage required because this is not a simple native resource list change.
• Reviewer handoff: verify lane fit, no hidden fixture growth, no raw diagnostics by default, no false customer-safe/export/auditor-ready copy, and capability-scoped actions.
• Budget / baseline / trend impact: none expected beyond one explicit browser smoke.
• Escalation needed: document-in-feature if a state is unreachable; follow-up-spec if implementation requires a new persisted readiness engine.
• Active feature PR close-out entry: Smoke Coverage.
• Planned validation commands:

cd apps/platform
./vendor/bin/sail artisan test tests/Feature/Filament/Spec337EvidenceReviewPackProductFlowTest.php --compact
./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec337EvidenceReviewPackProductFlowSmokeTest.php --compact
./vendor/bin/sail artisan test --filter='Evidence|ReviewPack|StoredReport|CustomerReview|ProductProcessFlow' --compact
./vendor/bin/sail pint --dirty
git diff --check

User Scenarios & Testing (mandatory)

User Story 1 - Understand readiness from the first screen (Priority: P1)

As a governance operator, I need Evidence / Review Pack surfaces to tell me whether a package is ready for customer or auditor consumption without inspecting raw artifacts.

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

Independent Test: Render missing-evidence and ready-package fixtures and assert the decision card, readiness flow, primary next action, proof panel, and diagnostics behavior.

Acceptance Scenarios:

1. Given no evidence snapshot exists for the selected scope, When the Evidence / Review Pack surface renders, Then it shows Evidence snapshot required, marks the evidence step missing, marks review pack unavailable, marks customer-safe output not ready, and keeps diagnostics collapsed.
2. Given a ready package with a download-backed review pack exists, When the surface renders for an authorized user, Then it shows the pack/export state truthfully and does not claim auditor-ready unless the repo-backed customer-safe conditions are satisfied.

---

User Story 2 - Follow the correct next action (Priority: P2)

As an operator, I need one primary action per state so I know whether to generate evidence, generate a report, generate a review pack, review customer output, view operation proof, or download export.

Why this priority: Evidence workflows are multi-step; competing CTAs create unsafe exports or repeated generation attempts.

Independent Test: Assert state-specific actions appear only for authorized users and that unauthorized users do not see generate/export actions.

Acceptance Scenarios:

1. Given an evidence snapshot exists but no report exists, When the page renders, Then the primary action is Generate stored report only if repo-supported and authorized.
2. Given a stored report exists but no review pack exists, When the page renders, Then the primary action is Generate review pack only for an authorized user.

---

User Story 3 - Inspect proof without exposing raw internals (Priority: P3)

As a reviewer, I need OperationRun proof and artifact links while raw diagnostics remain secondary and collapsed.

Why this priority: Auditability requires proof, but customer-safe surfaces must not default to raw provider or payload detail.

Independent Test: Render linked OperationRun fixtures, failed runs, and cross-workspace runs and assert proof visibility, failed-proof copy, cross-workspace exclusion, and raw JSON hidden by default.

Acceptance Scenarios:

1. Given a linked OperationRun exists, When the proof panel renders, Then it shows status/outcome/timeline/requester/run type and an operation detail link when authorized.
2. Given a raw payload exists, When the page loads, Then raw JSON is not visible until the diagnostics disclosure is opened and only where capability conventions allow.

Functional Requirements (mandatory)

• FR-001: Evidence / Review Pack surfaces MUST render the question Is this evidence package ready for customer or auditor consumption?.
• FR-002: The first screen MUST show Status, Reason, Impact, and Primary next action.
• FR-003: The Evidence readiness flow MUST use the Product Process Flow pattern and the six default steps.
• FR-004: The flow MUST derive step states from repo-backed artifacts only.
• FR-005: Customer-safe output MUST NOT be shown as ready unless the selected surface has repo-backed customer-safe/package/download readiness.
• FR-006: Export/download state MUST derive from ready, non-expired review packs with stored file metadata and authorized signed download access.
• FR-007: OperationRun proof MUST be shown where linked and authorized, and cross-workspace proof MUST NOT leak.
• FR-008: Diagnostics MUST be collapsed by default and raw payload/JSON MUST NOT be visible on initial render.
• FR-009: Generate/export/download/open actions MUST be capability-aware and preserve workspace/environment/review context.
• FR-010: The implementation MUST NOT introduce migrations, packages, env vars, queue/scheduler changes, new backend engines, or new persisted lifecycle truth.

Non-Functional Requirements (mandatory)

• NFR-001: Page rendering remains database-only and must not call Microsoft Graph or external providers during render.
• NFR-002: Existing Filament v5 / Livewire v4 conventions remain intact.
• NFR-003: Panel provider registration remains in apps/platform/bootstrap/providers.php; no panel provider change is planned.
• NFR-004: Globally searchable resources touched by this spec must either have Edit/View pages or keep global search disabled. EvidenceSnapshotResource, ReviewPackResource, StoredReportResource, and EnvironmentReviewResource currently disable global search.
• NFR-005: Destructive actions remain confirmed and authorized. This spec introduces no new destructive actions.
• NFR-006: No global heavy assets are introduced; no deployment filament:assets change is expected.

Key Dependencies

• Spec 332 - Product Process Flow System v1
• Spec 333 - Restore Create UX Final Productization
• Spec 335 - Restore Run Detail / Post-Execution Proof Productization
• Spec 336 - Baseline Compare Product Process Flow Alignment
• Spec 326 - Customer Review Workspace v1 Productization
• Spec 329 - Evidence / Audit Log Disclosure Productization
• Spec 325 - Screenshot-Anchored Strategic Target Images

Follow-Up Specs (out of scope)

• Provider Readiness Productization
• Restore Evidence Export / Auditor Artifact Productization
• Cross-Tenant Compare and Promotion v1
• Customer Review Workspace Decision/Attestation Polish

Implementation Close-Out Report

When implementation completes, report:

• Changed behavior.
• Evidence / Review Pack states covered.
• Product Process Flow reuse details.
• Files changed.
• Tests and results.
• Browser screenshots.
• Known gaps and unreachable states.
• Merge readiness.
• Confirmation that no migrations, packages, env vars, queues, scheduler, storage, deployment asset changes, destructive action behavior changes, or false customer-safe/evidence/export claims were introduced.