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

# Implementation Plan: Spec 343 - Customer Review Attestation & Accepted Risk Lifecycle

**Branch**: `343-customer-review-attestation-accepted-risk-lifecycle` | **Date**: 2026-06-01 | **Spec**: `specs/343-customer-review-attestation-accepted-risk-lifecycle/spec.md`  
**Input**: User-provided Spec 343 draft (Codex attachment) + current repo truth from `CustomerReviewWorkspace` + accepted-risk lifecycle foundations (`FindingException`).

## Summary

Add the next bounded step after customer-safe review consumption (Spec 342):

1) Make customer/stakeholder acknowledgement explicit and auditable.  
2) Tighten the customer-safe accepted-risk lifecycle visibility (owner/rationale/expiry/re-review due) using existing `FindingException` truth.  

This is a runtime productization slice, not a GRC rebuild:

- no legal/e-signature semantics
- no compliance certification claims
- no external customer portal architecture
- no Graph/provider calls during render
- no new global framework for attestations

## Technical Context

- **Language/Version**: PHP 8.4.15, Laravel 12.x.
- **UI**: Filament v5 + Livewire v4 (no Livewire v3 APIs).
- **Panel providers**: remain registered in `apps/platform/bootstrap/providers.php` (no changes expected).
- **Storage**: PostgreSQL; a new migration is possible if acknowledgement persistence is missing.
- **Testing**: Pest Feature/Livewire tests + one Pest Browser smoke file (strategic customer-safe surface).
- **Assets**: no new global assets expected; `filament:assets` not expected for this spec.

## UI / Surface Guardrail Plan

- **Guardrail scope**: material change to an existing strategic customer-safe review surface (UI-038).
- **Primary surface**:
  - `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`
  - `apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php`
- **New surface elements**:
  - “Review acknowledgement” card
  - “Acknowledge review” action modal (write path)
  - tightened accepted-risk lifecycle presentation (read-first)
- **Disclosure defaults**: diagnostics remain collapsed and capability-gated.
- **UI audit registry**: decide post-diff whether `docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md` requires an update; route inventory should remain stable.

## Repo-Truth-First Execution Rule

Before any runtime change:

1) Update `specs/343-customer-review-attestation-accepted-risk-lifecycle/repo-truth-map.md` with confirmed truth for:
   - Customer Review Workspace payload/state shape
   - `FindingException`/decision lifecycle fields used for customer-safe display
   - any existing acknowledgement-like concepts (none expected beyond verification acknowledgements)
   - audit log seams and existing action IDs
2) Update `specs/343-customer-review-attestation-accepted-risk-lifecycle/review-attestation-risk-state-contract.md` to match the confirmed truth (no invented states).

## Data Model Plan (Acknowledgement Truth)

### Goal

Persist a customer/stakeholder acknowledgement event so it is queryable, auditable, and basis-aware.

### Expected current repo truth

- Accepted risks already exist as `FindingException` (+ append-only decisions).
- No existing review acknowledgement model/table exists (to be confirmed in Phase 1).

### Proposed minimal persisted entity (conditional)

If repo truth confirms there is no review acknowledgement entity:

- Add `EnvironmentReviewAcknowledgement` (final name to be validated against existing naming conventions).
- Table should be workspace- and environment-scoped and reference the acknowledged review:
  - `workspace_id`
  - `managed_environment_id`
  - `environment_review_id`
  - actor + timestamp fields
  - optional comment
  - basis capture (at minimum: `review_pack_id` and/or `evidence_snapshot_id` when present)

### Basis-change detection (for `re_ack_required`)

Derive `re_ack_required` only if repo truth can safely detect basis drift:

- compare stored basis fields to current review pack / evidence snapshot identifiers
- if basis fields are missing, prefer “acknowledged” without re-ack semantics (no guesswork)

### Constitution alignment

- **PERSIST-001**: acknowledgement is product truth with independent audit needs; persistence is justified.
- **STATE-001**: any new displayed state must change behavior (action availability, warnings, or next action), not just wording.

## Authorization Plan

- Introduce (or reuse if already present) one dedicated capability for recording acknowledgement.
- Enforce:
  - workspace membership + environment access boundaries
  - capability checks for write
  - deny-as-not-found for cross-workspace review access
- Keep diagnostics behind `support_diagnostics.view`.

## Auditability Plan

- Add audit events for:
  - review acknowledgement recorded
  - acknowledgement superseded/replaced (if append-only)
  - (optional) acknowledgement revoked (only if a revoke capability exists; otherwise out of scope)
- Audit payload must be customer-safe (no secrets, no raw provider payloads).

## Accepted Risk Lifecycle Plan (Finding Exceptions)

The Customer Review Workspace already surfaces accepted-risk counts and lifecycle signals.

This spec tightens customer-safe lifecycle truth:

- ensure owner/rationale/expiry/review_due signals are visible where repo-backed
- highlight missing governance support states (`missing_support`, missing owner/reason/dates) without fabricating “no risk”
- ensure accepted-risk and findings presentation never slips into diagnostics-only disclosure

Any accepted-risk mutation actions on the customer-safe surface are optional and must be capability-gated, confirmed where destructive, and audited.

## Implementation Phases

### Phase 0 — Preflight

- Confirm working tree is clean and branch is correct.
- Re-read Spec 342 state contract and repo-truth map boundaries so Spec 343 does not duplicate or regress consumption semantics.

### Phase 1 — Repo Truth Mapping

- Validate acknowledgement absence/presence in codebase and database schema.
- Confirm `FindingException` lifecycle fields used in Customer Review Workspace.
- Record everything in `repo-truth-map.md` with classifications.

### Phase 2 — Acknowledgement Persistence (conditional)

- Implement the minimal model + migration only if missing.
- Add a service/action class to record acknowledgement with authorization + audit.

### Phase 3 — UI Wiring (Customer Review Workspace)

- Implement derived state builder and card rendering.
- Add the “Acknowledge review” action modal (requires confirmation).
- Keep copy customer-safe and localization-ready (reuse existing localization patterns).

### Phase 4 — Accepted Risk Lifecycle Tightening

- Keep accepted-risk truth sourced from `FindingException`.
- Add/adjust lifecycle highlighting only if repo truth proves gaps.

### Phase 5 — Tests + Browser Smoke + Screenshots

- Add focused Feature/Livewire tests for attestation states, RBAC boundaries, and audit emission.
- Add one Browser smoke for the strategic surface and capture screenshots.

### Phase 6 — Validation + Close-Out

- Run the planned validation commands.
- Update spec package artifacts (`repo-truth-map.md`, state contract, checklist) based on what was discovered/implemented.
- Record any unreachable states as “not available”/“deferred”, not as TODO guesswork.

## Deployment / Ops Impact

- **Migrations**: possible (only if acknowledgement persistence is missing).
- **Env vars**: none expected.
- **Queues/scheduler**: none expected.
- **Storage**: none expected.
- **Filament assets**: none expected.