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

253 lines
13 KiB
Markdown
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.
Reference in New Issue View Git Blame Copy Permalink