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:

[
    '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)