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

Feature Specification: Spec 343 - Customer Review Attestation & Accepted Risk Lifecycle

Feature Branch: 343-customer-review-attestation-accepted-risk-lifecycle
Created: 2026-06-01
Status: Implemented
Type: Runtime productization / customer-safe acknowledgement / accepted-risk lifecycle
Runtime posture: Add a small repo-backed customer review acknowledgement (attestation) and tighten customer-safe visibility of accepted risks (Finding Exceptions) on the existing Customer Review Workspace. No generic GRC rebuild and no legal/e-signature semantics.
Input: User-provided Spec 343 draft (Codex attachment pasted-text.txt) + repo truth from Specs 326, 329, 337, 342 and the current CustomerReviewWorkspace implementation.

Spec Candidate Check (mandatory — SPEC-GATE-001)

• Problem: Customer Review Workspace is now consumable (Spec 342), but it still lacks an explicit, customer-safe acknowledgement trail and a clear accepted-risk lifecycle view that answers: what was acknowledged, which risks are accepted, who owns them, and what needs re-review.
• Today's failure: Stakeholders can consume a review pack, but acknowledgement and accepted-risk accountability can remain implicit (notes, exports, operator memory) rather than explicit, customer-safe, and auditable.
• User-visible improvement: The first screen answers: “Has this review been acknowledged, what risks are accepted, what needs re-review, and what’s the next action?” with truthful evidence/review-pack basis and audit trail.
• Smallest enterprise-capable version: Extend only the existing /admin/reviews/workspace surface with one acknowledgement card and a tightened accepted-risk lifecycle section. Reuse existing accepted-risk truth (FindingException) and introduce a minimal persisted acknowledgement record only if repo truth shows it is not already present.
• Explicit non-goals: No legal signature, no compliance certification claims, no generic GRC framework, no external customer portal, no external identity federation, no risk scoring engine, no new review-pack format, no bulk approval automation.
• Permanent complexity imported: One small persisted acknowledgement model + migration (only if not already present), one acknowledgement service/action, one audit action family, minimal derived state/presenter, focused Feature/Livewire tests, one Browser smoke file, and screenshot artifacts.
• Why now: After Spec 342 made consumption customer-safe, the next sellability gap is a lightweight acknowledgement and accepted-risk accountability loop (acknowledge → accepted risks on record → re-review due) without turning TenantPilot into a GRC product.
• Why not local: A copy-only update cannot produce durable acknowledgement truth or auditable risk lifecycle. A “full attestation workflow” would violate roadmap/constitution proportionality. The narrow correct slice is one acknowledgement record tied to an existing review pack/evidence basis and an honest lifecycle display.
• Approval class: Core Enterprise.
• Red flags triggered: New persisted truth (acknowledgement record), customer-facing trust language, and lifecycle claims. Defense: minimal persistence justified by audit truth (PERSIST-001), all states are evidence-backed, and the UX forbids false legal/compliance claims.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve.

Candidate Source And Completed-Spec Guardrail

• Candidate source: Directly user-provided as “Spec 343 — Customer Review Attestation & Accepted Risk Lifecycle” as the next step after Spec 342.
• Completed-spec check: No specs/343-* package existed before Spec Kit creation. Related Specs 326, 329, 337, and 342 contain completed-task, close-out, or review-outcome signals and are treated as historical context only. They must not be rewritten or normalized by this spec.
• Roadmap alignment: This is a bounded acknowledgement + accepted-risk lifecycle slice on top of an existing strategic surface. It explicitly avoids becoming a “full attestation workflow block” or generic GRC system by keeping semantics lightweight and customer-safe.
• Close alternatives deferred:
  • Decision-Based Governance Inbox Final Operator Workflow (draft follow-up 344).
  • Localization v1 Product Surface Hardening (draft follow-up 345).
  • Provider Readiness Productization (draft follow-up 346).
  • External Support Desk / PSA Handoff (draft follow-up 347).

Spec Scope Fields (mandatory)

• Scope: workspace hub (existing strategic surface) with page-level environment_id filter.
• Primary Routes:
  • /admin/reviews/workspace (Customer Review Workspace)
  • linked drill-down surfaces for exceptions/accepted risks (FindingExceptionResource), evidence, review packs, audit trail (only where already repo-backed)
• Data Ownership:
  • Accepted risks: tenant/workspace-scoped FindingException + append-only FindingExceptionDecision.
  • New acknowledgement truth (if missing): a workspace + managed-environment + review-scoped persisted record.
• RBAC:
  • Viewing remains governed by existing workspace membership rules + existing capability gates for linked resources.
  • Recording acknowledgement requires a dedicated capability (new, repo-aligned name to be chosen during repo-truth phase; do not overload environment_review.manage unless evidence shows it is the correct least-privilege boundary).
  • Diagnostics remain capability-gated (support_diagnostics.view).

UI Surface Impact (mandatory — UI-COV-001)

• No UI surface impact
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

UI/Productization Coverage (mandatory)

• Route/page/surface: /admin/reviews/workspace (apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php + apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php)
• Current page archetype: docs/ui-ux-enterprise-audit/route-inventory.md → UI-038 (Strategic Surface, repo-verified)
• Design depth: Strategic Surface (customer-safe)
• Repo-truth level: repo-verified surface; new acknowledgement truth may require a small persisted model
• Existing pattern reused: Spec 342 decision-card hierarchy + FindingException lifecycle truth + existing localized copy patterns
• New pattern required: none; only one new card/state block and one action modal on an existing strategic page
• Screenshot required: yes (specs/343-customer-review-attestation-accepted-risk-lifecycle/artifacts/screenshots/)
• Customer-safe review required: yes (copy + disclosure + false-claim prevention)
• Dangerous-action review required: conditional (only if the surface includes revoke/update risk actions; otherwise N/A)
• Coverage artifacts: decide post-diff whether docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md requires an update; route inventory entry should remain stable.

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes.
• Interaction classes: status messaging, action links, evidence/proof disclosure, audit trail disclosure, accepted-risk lifecycle.
• Shared paths reused:
  • Existing customer-safe disclosure language (“not a certification / legal attestation / compliance guarantee”) where applicable.
  • Existing Finding Exception lifecycle truth (FindingException, FindingExceptionDecision), not a new accepted-risk engine.
  • Existing audit foundation (AuditActionId + workspace audit logging patterns), extended with a new action family only for acknowledgement.
• Deviations: none intended. If implementation introduces a new presenter/state contract, it must remain feature-local and derived-only.

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: yes — only for acknowledgement/attestation (a stakeholder acknowledgement must persist independently of the page render).
• New persisted entity/table/artifact?: conditional. If repo truth confirms no existing review acknowledgement table/model, add one minimal persisted entity.
• Why persistence is justified (PERSIST-001): acknowledgement is an auditable governance-of-record event that must outlive the session and be queryable (“who acknowledged what, when, based on which review pack/evidence basis”).
• New abstraction?: no framework. At most one feature-local derived state builder (contract) to keep UI truthful and consistent.
• New enum/state family?: no new global status family. Attestation states are derived from acknowledgement record presence + basis comparison.
• Narrowest correct implementation:
  • Persist acknowledgement as one append-only record per review basis (or per review with basis snapshot fields).
  • Render derived states on the existing page; keep diagnostics collapsed.
  • Add audit emission + focused tests.
• Alternative intentionally rejected: generic attestation workflow engine, legal signature semantics, and GRC-style policy/exception board.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Feature/Livewire for state, RBAC, isolation, audit emission; Browser for customer-safe rendered hierarchy and disclosure defaults.
• Validation lane(s): confidence + browser.
• Why sufficient: the behavioral core is authorization + persisted acknowledgement + derived state; one bounded browser smoke is required for strategic customer-safe UX and diagnostics collapse.
• Planned validation commands (later implementation):
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec343CustomerReviewAttestationAcceptedRiskTest.php --compact
  • cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec343CustomerReviewAttestationAcceptedRiskSmokeTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test --filter='CustomerReview|EnvironmentReview|ReviewPack|Evidence|FindingException|Audit' --compact
  • cd apps/platform && ./vendor/bin/sail pint --dirty
  • git diff --check

User Scenarios (must map to tasks)

User Story 1 — Customer/stakeholder acknowledgement is explicit (P1)

Given a released review exists and the review pack/evidence basis is available, when a stakeholder opens Customer Review Workspace, then the page shows whether acknowledgement is required, acknowledged, or re-acknowledgement is required (only when repo truth can detect basis change).

User Story 2 — Accepted risks are visible and reviewable (P1)

Given accepted risks exist (Finding Exceptions), when a stakeholder opens Customer Review Workspace, then the page shows customer-safe counts and lifecycle signals (active, expiring, expired, pending) and highlights missing owner/rationale/review dates where repo-backed.

User Story 3 — No false legal/compliance claims (P0)

Given any state (no review pack, incomplete evidence, missing audit linkage), when the page renders, then it never implies legal signature, compliance certification, or “no risk exists” when only “no accepted risks recorded” is true.

Requirements

Functional Requirements

• FR-001 (Attestation card): Customer Review Workspace MUST render a “Review acknowledgement” card with: status, reason, impact, evidence/review-pack basis, and one primary next action.
• FR-002 (Attestation states): The surface MUST support these derived acknowledgement states:
  • not_available (only if repo truth decides acknowledgement is intentionally not supported)
  • required (review is consumable but no acknowledgement record exists)
  • acknowledged (acknowledgement record exists)
  • re_ack_required (only if repo truth can detect a changed basis after acknowledgement)
• FR-003 (Acknowledge action): If acknowledgement is supported, the surface MUST provide an action that records acknowledgement with:
  • actor + timestamp (repo truth: authenticated user)
  • optional comment
  • captured basis (at minimum: review id + current review-pack id and/or evidence snapshot id when present)
  • audit log emission
• FR-004 (Accepted risk visibility): The surface MUST show accepted risks (Finding Exceptions) summary and lifecycle signals using repo-backed truth (counts and validity/status).
• FR-005 (Accepted risk lifecycle fields): Where repo-backed, the surface MUST show owner, rationale (request reason), and expiry/review due dates, and must flag missing governance support.
• FR-006 (Evidence and audit basis): Attestation and accepted-risk sections MUST show a truthful basis (review pack/evidence snapshot availability and audit linkage state) and must never fabricate proof.
• FR-007 (Diagnostics default): Diagnostics MUST remain collapsed by default and MUST remain capability-gated.

Non-Functional Requirements

• NFR-001 (Isolation): No cross-workspace leakage for acknowledgement records or accepted risks.
• NFR-002 (Authorization): UI visibility is not authorization; policies/gates must enforce capabilities for acknowledgement write and any linked action.
• NFR-003 (Performance): No Graph/provider calls during page render; derived state uses DB-only query paths with eager-loading where relationship-backed details are rendered.

Out Of Scope

• Legal signatures, legal attestations, regulatory sign-off, compliance certification claims.
• External customer portal architecture, external federation/invitation links.
• New GRC framework, risk scoring engine, or cross-domain policy exception board.
• New review pack formats or evidence generation backend.
• Bulk approval automation for accepted risks.

Acceptance Criteria

Product

• Customer Review Workspace shows an acknowledgement card with status/reason/impact/next action.
• Acknowledgement supports required and acknowledged states using repo-backed truth.
• “Re-ack required” is shown only when basis drift detection is repo-backed; otherwise it is not shown.
• Accepted risks (Finding Exceptions) are visible with lifecycle signals (active/expiring/expired/pending) using repo-backed truth.
• Owner/rationale/expiry or review-due dates are displayed where repo-backed and missing governance support is highlighted.
• Evidence / review-pack basis is visible and truthful for acknowledgement and accepted-risk sections.
• Diagnostics remain secondary: collapsed by default and capability-gated.

Truth / Safety

• No legal signature / compliance certification claims appear in UI copy, notifications, or audit summaries.
• No fake “no risks exist” claim (only “no accepted risks recorded” where applicable).
• No fabricated evidence or audit trail claims; unsupported concepts render as “not available”/“deferred”.

RBAC / Isolation

• Acknowledgement write is capability-gated and auditable.
• Cross-workspace review/acknowledgement/exception access is denied-as-not-found.

Validation

• Feature/Livewire tests pass.
• Browser smoke passes and screenshots are captured (or unreachable states are documented honestly).

Assumptions

• Acknowledgement is recorded by an authenticated user (customer stakeholder or internal role), not an external identity/federation flow.
• Accepted risks are represented by FindingException + decisions; Spec 343 does not introduce a second accepted-risk model.
• Review pack and/or evidence snapshot identifiers are available to capture an acknowledgement basis for “re-ack required” decisions (if the feature supports that state).

Risks

• Scope creep into “full attestation workflow” or generic GRC mechanics; mitigate by enforcing non-goals and proportionality checks before implementation expands.
• Wrong capability boundary for acknowledgement write; mitigate by repo-truth-first and least-privilege review before naming/adding the capability.
• False-claim risk (legal/compliance, evidence, “no risk”); mitigate via explicit acceptance criteria + browser screenshots + negative tests.

Spec Artifacts (required for this package)

• specs/343-customer-review-attestation-accepted-risk-lifecycle/spec.md
• specs/343-customer-review-attestation-accepted-risk-lifecycle/plan.md
• specs/343-customer-review-attestation-accepted-risk-lifecycle/tasks.md
• specs/343-customer-review-attestation-accepted-risk-lifecycle/repo-truth-map.md
• specs/343-customer-review-attestation-accepted-risk-lifecycle/review-attestation-risk-state-contract.md
• specs/343-customer-review-attestation-accepted-risk-lifecycle/checklists/requirements.md
• specs/343-customer-review-attestation-accepted-risk-lifecycle/artifacts/screenshots/

Open Questions

• None block safe implementation.
• OQ-001 (resolved): Acknowledgement is available to authenticated actors with the dedicated capability environment_review.acknowledge (no external portal/federation semantics in v1).
• OQ-002 (resolved): Basis capture for drift detection uses environment_reviews.current_export_review_pack_id and environment_reviews.evidence_snapshot_id.
• OQ-003 (resolved): v1 uses single-current acknowledgement per environment_review_id (overwrite-on-ack) while preserving an audit trail (environment_review.acknowledged) for each acknowledgement action.
• OQ-004 (deferred): A separate acknowledgement Resource/detail page is deferred; the acknowledgement card + audit trail are sufficient for v1.

Follow-Up Spec Candidates

• Spec 344 — Decision-Based Governance Inbox Final Operator Workflow
• Spec 345 — Localization v1 Product Surface Hardening
• Spec 346 — Provider Readiness Productization
• Spec 347 — External Support Desk / PSA Handoff