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.