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

```bash
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.