ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
9e435ea91f
TenantAtlas/specs/337-evidence-review-pack-product-process-flow-alignment/evidence-review-pack-state-contract.md
ahmido b7c0dfe0e3 feat: align evidence review pack product process flow (Spec 337) (#407) 
## Summary

Productizes the Evidence Overview review-pack process flow so the operator sees a clear, gated progression:

`evidence snapshot → stored report → review pack → customer-safe export`

with explicit gating, state-appropriate copy, collapsed diagnostics, and dark-mode coverage.

## Changes

- `EvidenceOverview` page + Blade view aligned to the review-pack state contract.
- New feature test: `Spec337EvidenceReviewPackProductFlowTest`.
- New browser smoke: `Spec337EvidenceReviewPackProductFlowSmokeTest`.
- Spec 337 artifacts: `spec.md`, `plan.md`, `tasks.md`, state contract, repo-truth map, checklist, and screenshot evidence.

## Spec Kit

Spec + code in one PR (Variante B). Gate satisfied: includes `specs/337-evidence-review-pack-product-process-flow-alignment/`.

## Notes

Filament v5 / Livewire v4 compliant. No destructive actions added. Tooling scratch (`.playwright-mcp/`) intentionally excluded from the commit.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #407
2026-05-30 13:41:19 +00:00

13 KiB
Raw Blame History

Spec 337 - Evidence / Review Pack State Contract

Status: prepared Created: 2026-05-30 Scope: Evidence / Review Pack readiness surfaces

This contract defines what the first screen must show per repo-backed state, without inventing evidence, customer-safe, auditor-ready, or export truth.

Flow Steps

The Evidence readiness flow uses these fixed steps:

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

Presentation Vocabulary

Presentation states are not a new enum family. They are labels derived from existing model state.

  • Available
  • Missing
  • Required
  • Generating
  • Failed
  • Stale
  • Needs review
  • Ready
  • Not ready
  • Generated
  • Unavailable
  • Collapsed

Universal Defaults

  • Diagnostics default: Collapsed.
  • Raw JSON / raw payload default: hidden.
  • Primary next action: exactly one per state.
  • Customer-safe output: Ready only when Customer Review Workspace / Environment Review package readiness is repo-backed.
  • Export/download: Available only when a ready, non-expired review pack has file metadata and the user can access the signed download.
  • Operation proof: proof of generation/export is not the same as evidence output or customer-safe readiness.
  • External delivery: unavailable unless a repo-backed mechanism is discovered.

State Contracts

1. No Evidence Snapshot

Field Contract
State No evidence snapshot
Visible status Evidence snapshot required
Reason No evidence snapshot is available for the selected review scope.
Impact Review pack output cannot be trusted or exported yet.
Primary next action Generate evidence snapshot, only when repo-supported and authorized. Otherwise show unavailable state.
Flow gate states Source data selected: Available or Unavailable (repo-backed); Evidence snapshot: Missing; Stored report: Unavailable; Review pack: Unavailable; Customer-safe output: Not ready; Export / delivery: Unavailable
Evidence proof Snapshot unavailable; source data proof only if repo-backed.
Customer-safe state Not ready.
Export state Unavailable.
Diagnostics default Collapsed; no raw JSON visible.

2. Evidence Snapshot Generating

Field Contract
State Evidence snapshot generating
Visible status Evidence generation in progress
Reason Evidence snapshot generation is currently running.
Impact Review pack output is not final yet.
Primary next action View operation progress.
Flow gate states Source data selected: Available or Unavailable; Evidence snapshot: Generating; Stored report: Unavailable; Review pack: Unavailable; Customer-safe output: Not ready; Export / delivery: Unavailable
Evidence proof Linked OperationRun visible when authorized.
Customer-safe state Not ready.
Export state Unavailable.
Diagnostics default Collapsed.

3. Evidence Snapshot Failed

Field Contract
State Evidence snapshot failed
Visible status Evidence generation failed
Reason Evidence snapshot generation ended with errors.
Impact Review pack output cannot be generated from this evidence yet.
Primary next action Review evidence operation.
Flow gate states Source data selected: Available or Unavailable; Evidence snapshot: Failed; Stored report: Unavailable; Review pack: Unavailable; Customer-safe output: Not ready; Export / delivery: Unavailable
Evidence proof Failed OperationRun proof visible when authorized.
Customer-safe state Not ready.
Export state Unavailable.
Diagnostics default Collapsed; failure summarized before diagnostics.

4. Evidence Snapshot Stale

Field Contract
State Evidence snapshot stale or expired
Visible status Evidence refresh required
Reason Evidence exists, but its freshness is outside the acceptable window or the snapshot is expired/stale.
Impact Review pack output should not be treated as current until evidence is refreshed.
Primary next action Refresh evidence snapshot, only when repo-supported and authorized.
Flow gate states Source data selected: Available or Unavailable; Evidence snapshot: Stale; Stored report: Unavailable or Available (repo-backed); Review pack: Unavailable or Needs review; Customer-safe output: Not ready; Export / delivery: Unavailable
Evidence proof Existing snapshot proof may be shown with stale/expired state.
Customer-safe state Not ready or Needs review; never Ready from stale evidence alone.
Export state Unavailable unless implementation proves a still-valid review-derived pack is independent and repo-backed; default unavailable.
Diagnostics default Collapsed.

5. Evidence Snapshot Available, Stored Report Missing

Field Contract
State Evidence snapshot available / stored report missing
Visible status Stored report required
Reason Evidence snapshot exists, but no stored report is available for this review output.
Impact Evidence is present but not yet packaged for consumption.
Primary next action Generate stored report, only if repo-supported and authorized; otherwise Open evidence snapshot or show report unavailable.
Flow gate states Source data selected: Available; Evidence snapshot: Available; Stored report: Missing; Review pack: Unavailable; Customer-safe output: Not ready; Export / delivery: Unavailable
Evidence proof Evidence snapshot proof available. Stored report proof unavailable.
Customer-safe state Not ready.
Export state Unavailable.
Diagnostics default Collapsed.

6. Stored Report Available, Review Pack Required

Field Contract
State Stored report available / review pack required
Visible status Review pack required
Reason Stored report exists, but a review pack has not been generated.
Impact Customer-safe delivery is not ready yet.
Primary next action Generate review pack, only when authorized and entitlement/evidence requirements allow it.
Flow gate states Source data selected: Available; Evidence snapshot: Available; Stored report: Available; Review pack: Required; Customer-safe output: Not ready; Export / delivery: Unavailable
Evidence proof Evidence snapshot and stored report proof available.
Customer-safe state Not ready.
Export state Unavailable.
Diagnostics default Collapsed.

7. Review Pack Generating

Field Contract
State Review pack generating
Visible status Review pack generation in progress
Reason Review pack generation is currently running.
Impact Customer output is not final yet.
Primary next action View operation progress.
Flow gate states Source data selected: Available; Evidence snapshot: Available; Stored report: Available or Unavailable (repo-backed); Review pack: Generating; Customer-safe output: Not ready; Export / delivery: Unavailable
Evidence proof ReviewPack OperationRun proof visible when authorized.
Customer-safe state Not ready.
Export state Unavailable.
Diagnostics default Collapsed.

8. Review Pack Failed

Field Contract
State Review pack failed
Visible status Review pack generation failed
Reason Review pack generation ended with errors.
Impact Customer-safe output cannot be generated from this pack yet.
Primary next action Review review-pack operation.
Flow gate states Source data selected: Available; Evidence snapshot: Available; Stored report: Available or Unavailable (repo-backed); Review pack: Failed; Customer-safe output: Not ready; Export / delivery: Failed or Unavailable
Evidence proof Failed OperationRun proof visible when authorized.
Customer-safe state Not ready.
Export state Failed or Unavailable, based on repo-backed artifact state.
Diagnostics default Collapsed; failure summarized before diagnostics.

9. Review Pack Available, Customer-Safe Output Needs Review

Field Contract
State Review pack available / customer-safe review required
Visible status Customer-safe review required
Reason A review pack exists, but customer-safe output has not been confirmed by repo-backed review/package readiness.
Impact Do not share the pack externally until it has been reviewed.
Primary next action Review customer output.
Flow gate states Source data selected: Available; Evidence snapshot: Available; Stored report: Available or Unavailable (repo-backed); Review pack: Available; Customer-safe output: Needs review; Export / delivery: Required, Available, or Unavailable based on pack file truth
Evidence proof Review pack proof available; OperationRun proof available when linked.
Customer-safe state Needs review.
Export state Do not show export/share as final customer-ready unless download/package readiness is repo-backed.
Diagnostics default Collapsed.

10. Customer-Safe Output Ready

Field Contract
State Customer-safe output ready
Visible status Customer-safe output ready
Reason Review pack output is available for customer/auditor consumption through a repo-backed review/package readiness path.
Impact The pack can be shared or exported according to workspace policy.
Primary next action Export review pack or Download export, only when authorized.
Flow gate states Source data selected: Available; Evidence snapshot: Available; Stored report: Available or Unavailable (repo-backed); Review pack: Available; Customer-safe output: Ready; Export / delivery: Available, Generated, or Required based on repo-backed artifact state
Evidence proof Linked snapshot/review/pack/operation proof visible when authorized.
Customer-safe state Ready.
Export state Available or Required from review-pack file truth.
Diagnostics default Collapsed.

11. Export Available

Field Contract
State Export available
Visible status Review pack export available
Reason A generated export artifact is available.
Impact Evidence package can be downloaded or shared according to capability rules.
Primary next action Download export.
Flow gate states Source data selected: Available; Evidence snapshot: Available; Stored report: Available or Unavailable (repo-backed); Review pack: Available; Customer-safe output: Ready or Needs review based on repo-backed customer-safe state; Export / delivery: Available
Evidence proof Review pack file metadata and OperationRun proof available when authorized.
Customer-safe state Ready only if repo-backed; otherwise Needs review even when download exists.
Export state Available.
Diagnostics default Collapsed.

12. Export Unavailable / External Delivery Not Configured

Field Contract
State Export unavailable
Visible status Export unavailable
Reason No generated export artifact is available, the pack is not ready, the file is missing/expired, or external delivery is not configured.
Impact Evidence package cannot be downloaded or delivered from this surface yet.
Primary next action Generate review pack, regenerate export, review operation, or no action, based on repo-backed state and authorization.
Flow gate states Source data selected: repo-backed; Evidence snapshot: repo-backed; Stored report: repo-backed; Review pack: repo-backed; Customer-safe output: repo-backed; Export / delivery: Unavailable
Evidence proof Show available proof rows only.
Customer-safe state Ready, Needs review, Not ready, or Unavailable based on repo truth; never inferred from missing export.
Export state Unavailable.
Diagnostics default Collapsed.

Surface-Specific Notes

Evidence Overview

  • Evidence Overview can show internal evidence and artifact proof.
  • Evidence Overview must not infer Customer-safe output ready unless it links to a repo-backed Customer Review Workspace / Environment Review current export state.
  • Raw artifact inventory remains secondary.

Customer Review Workspace

  • This is the safest source for customer-safe package readiness.
  • It can show customer-safe output ready only when existing review/package/download readiness methods support that claim.
  • Diagnostics remain collapsed and customer-facing default content must hide raw internals.

Review Pack Resource

  • A ready review pack with file metadata supports export/download availability.
  • It does not automatically support auditor-ready copy.
  • The existing expire action remains destructive/confirmed and is not changed by this spec.

Stored Report

  • Stored report Available / Missing is repo-backed.
  • Stored report Generating / Failed is not repo-backed unless implementation discovers a direct OperationRun relation or existing job/run source.