TenantAtlas/specs/343-customer-review-attestation-accepted-risk-lifecycle/review-attestation-risk-state-contract.md

# Spec 343 - Review Attestation & Accepted Risk State Contract

Status: draft  
Created: 2026-06-01  
Scope: Derived UI state contract for Customer Review Workspace acknowledgement + accepted-risk lifecycle

This document defines the **derived display contract** for Spec 343. It is not a new persisted truth source. The UI must not fabricate states; unsupported concepts must render as `not available` or `deferred`.

## Contract Rules

- Derived-only: all states come from repo-backed models/fields (plus “absence of record”).
- No legal/e-signature semantics.
- No compliance/certification claims.
- Diagnostics are collapsed by default and capability-gated.

## Recommended Contract Shape (illustrative)

Exact implementation may differ, but the UI should consume one coherent contract where practical:

```php
[
    'review' => [
        'id' => 123,
        'status' => 'published',
    ],
    'attestation' => [
        'state' => 'required', // not_available | required | acknowledged | re_ack_required
        'label' => 'Customer acknowledgement required',
        'reason' => 'Review pack is available, but no acknowledgement is recorded.',
        'impact' => 'The review is consumable, but not yet acknowledged.',
        'primary_next_action' => 'Acknowledge review',
        'basis' => [
            'review_pack' => 'available',   // available | not_available | preparing | expired | unknown
            'evidence' => 'available',      // available | incomplete | not_available | unknown
        ],
    ],
    'accepted_risks' => [
        'total' => 3,
        'expiring' => 1,
        'expired' => 1,
        'pending' => 0,
        'missing_support' => 0,
        'missing_required_fields' => 1,
    ],
    'diagnostics_state' => 'collapsed',
]
```

## Attestation States

### 1) Not Available

Use only when repo truth shows acknowledgement is intentionally unsupported.

| Field | Contract |
|---|---|
| Visible status | Acknowledgement not available |
| Reason | This review does not support acknowledgement yet. |
| Impact | Review consumption is available, but acknowledgement is not tracked. |
| Primary next action | Review accepted risks / findings |
| Action | None (no fake acknowledge button) |
| Diagnostics default | Collapsed |

### 2) Required

| Field | Contract |
|---|---|
| Visible status | Customer acknowledgement required |
| Reason | Review pack (and/or evidence basis) is available, but no acknowledgement is recorded. |
| Impact | The review can be consumed, but acknowledgement is not yet tracked. |
| Primary next action | Acknowledge review |
| Action | Show acknowledge action only when authorized |
| Diagnostics default | Collapsed |

### 3) Acknowledged

| Field | Contract |
|---|---|
| Visible status | Review acknowledged |
| Reason | A customer/stakeholder acknowledgement is recorded. |
| Impact | Review consumption has an audit trail. |
| Primary next action | Review accepted risks |
| Action | No “revoke” in v1 unless explicitly in scope + authorized |
| Diagnostics default | Collapsed |

### 4) Re-acknowledgement Required

Use only when repo truth can detect basis drift after acknowledgement (e.g., review pack/evidence snapshot changed).

| Field | Contract |
|---|---|
| Visible status | Re-acknowledgement required |
| Reason | Review content changed after the last acknowledgement. |
| Impact | Previous acknowledgement may no longer represent the current review package. |
| Primary next action | Re-acknowledge review |
| Diagnostics default | Collapsed |

## Accepted Risk Lifecycle Contract

Accepted risks are sourced from `FindingException` (and their decisions). Customer-safe display should map to these lifecycle signals where repo-backed:

- total accepted risks on record
- expiring soon
- expired
- pending approval
- missing governance support (`missing_support`)
- missing required fields for defensible governance (owner/rationale/review date), when repo-backed

### Copy boundaries

- “No accepted risks recorded for this review” is allowed when the count is zero.
- “No risks exist” is forbidden unless there is a separate, explicit product truth that proves it (not expected).

## Evidence / Review Pack Basis

Every attestation state should show what it is based on:

- review pack availability/status
- evidence snapshot availability/completeness
- audit linkage availability (only if repo-backed)

If evidence is missing:

- show “Evidence basis unavailable” (truthful)
- do not block acknowledgement unless the product explicitly requires evidence for acknowledgement (decision must be recorded in spec if introduced)