ahmido
0987527d0e
## Summary - add persisted customer review acknowledgement truth with capability gating and audit emission - extend the customer review workspace with acknowledgement state, evidence basis details, and accepted-risk lifecycle visibility - add focused feature and browser coverage plus Spec 343 screenshot artifacts and UI audit updates ## Scope - Livewire v4 / Filament v5 surface only; no panel provider changes - no new global assets; no `filament:assets` deployment change for this slice - includes a PostgreSQL migration for `environment_review_acknowledgements` ## Guardrail / Exception / Smoke Coverage - reachable UI surface changed: existing `/admin/reviews/workspace` customer-safe page - UI audit updated in `docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md` - screenshot artifacts included under `specs/343-customer-review-attestation-accepted-risk-lifecycle/artifacts/screenshots/` - spec package includes plan, tasks, repo-truth map, and state contract for the implemented slice ## Notes - target branch requested: `platform-dev` - branch pushed from commit `aaaad441fd13dbac54e971ab48765c502ced6b3f` Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #415
70 lines
5.3 KiB
Markdown
70 lines
5.3 KiB
Markdown
# Spec 343 - Repo Truth Map
|
|
|
|
Status: draft
|
|
Created: 2026-06-01
|
|
Scope: Customer review acknowledgement (attestation) + accepted risk lifecycle (Finding Exceptions)
|
|
|
|
This map is the implementation guardrail for Spec 343. Runtime work must update this file before changing code when it discovers additional truth, unsupported states, or deferred concepts.
|
|
|
|
## Classification Vocabulary
|
|
|
|
- `repo-verified`: observed in current application code, tests, specs, or routes.
|
|
- `derived from existing model`: available by deriving from existing persisted model fields or relationships.
|
|
- `foundation-real`: foundation exists, but the target behavior needs wiring/productization.
|
|
- `not available`: no repo-backed truth or action exists in the current codebase.
|
|
- `deferred`: intentionally out of scope for Spec 343.
|
|
|
|
## Core Surface Truth
|
|
|
|
| Data point | Classification | Repo evidence | Spec 343 handling |
|
|
|---|---|---|---|
|
|
| Customer Review Workspace page | repo-verified | `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php` | Extend existing page; do not add a new route. |
|
|
| Customer Review Workspace Blade view | repo-verified | `apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php` | Add acknowledgement card + tighten accepted-risk lifecycle copy. |
|
|
| Canonical route | repo-verified | `/admin/reviews/workspace` (UI-038 route inventory) | Keep route stable. |
|
|
| Environment selection | repo-verified | `environment_id` query filter semantics | Remains a page-level filter, not global context. |
|
|
| Legacy `/admin/t` context | not available | Spec 341 cleanup + current navigation contract | Must not be reintroduced. |
|
|
| Diagnostics collapse rule | repo-verified | Spec 342 + current workspace view conventions | Keep collapsed and capability-gated. |
|
|
|
|
## Review Truth
|
|
|
|
| Data point | Classification | Repo evidence | Spec 343 handling |
|
|
|---|---|---|---|
|
|
| Review record | repo-verified | `EnvironmentReview` usage in `CustomerReviewWorkspace` | Use as acknowledgement scope anchor. |
|
|
| Released/published review state | repo-verified / derived | `EnvironmentReviewStatus::*`, `published_at` (repo-backed) | Acknowledgement is only meaningful for released review packages. |
|
|
| Current export review pack | repo-verified | `EnvironmentReview.currentExportReviewPack` usage | Capture as acknowledgement basis when present. |
|
|
| Evidence snapshot basis | repo-verified | `EnvironmentReview.evidenceSnapshot` usage | Capture as acknowledgement basis when present. |
|
|
|
|
## Acknowledgement / Attestation Truth
|
|
|
|
| Data point | Classification | Repo evidence | Spec 343 handling |
|
|
|---|---|---|---|
|
|
| Review-scoped acknowledgement persisted model/table | repo-verified | `apps/platform/app/Models/EnvironmentReviewAcknowledgement.php` + `apps/platform/database/migrations/2026_06_01_000000_create_environment_review_acknowledgements_table.php` | Use `EnvironmentReviewAcknowledgement` as persisted acknowledgement truth (single-current per `environment_review_id`). |
|
|
| Acknowledgement service pattern | repo-verified | `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewAcknowledgementService.php` | Reuse approach: authorize → persist → audit. |
|
|
| Capability naming pattern for acknowledgement | repo-verified | `apps/platform/app/Support/Auth/Capabilities.php` | Use `environment_review.acknowledge` capability and enforce it on acknowledgement writes. |
|
|
| Customer-safe acknowledgement copy boundaries | repo-verified | Existing non-certification disclosure strings in review pack/evidence mapping | No legal/e-signature language; acknowledgement is “reviewed and understood”, not a compliance sign-off. |
|
|
|
|
## Accepted Risk Truth (Finding Exceptions)
|
|
|
|
| Data point | Classification | Repo evidence | Spec 343 handling |
|
|
|---|---|---|---|
|
|
| Accepted risk entity | repo-verified | `apps/platform/app/Models/FindingException.php` | Treat Finding Exceptions as accepted risks for customer-safe display. |
|
|
| Decision lifecycle | repo-verified | `apps/platform/app/Models/FindingExceptionDecision.php` (append-only) | Reuse; do not create new accepted-risk decision tables. |
|
|
| Lifecycle states | repo-verified | `FindingException::STATUS_*`, `FindingException::VALIDITY_*` | Map to customer-safe states (active/expiring/expired/pending/revoked/missing support). |
|
|
| Owner/rationale/dates | repo-verified | `owner_user_id`, `request_reason`, `expires_at`, `review_due_at` casts | Display where present; flag missing governance support. |
|
|
| Customer Review Workspace accepted-risk panel | repo-verified | `CustomerReviewWorkspace::acceptedRiskPanelForReview()` and related helpers | Tighten wording/visibility only; keep truth source unchanged. |
|
|
|
|
## Audit Truth
|
|
|
|
| Data point | Classification | Repo evidence | Spec 343 handling |
|
|
|---|---|---|---|
|
|
| Audit foundation exists | repo-verified | `apps/platform/app/Support/Audit/*` + existing audit logger usage | Reuse. |
|
|
| Review acknowledgement audit events | repo-verified | `apps/platform/app/Support/Audit/AuditActionId.php` (`environment_review.acknowledged`) | Emit a single canonical audit event on acknowledgement writes with customer-safe metadata only. |
|
|
|
|
## Unavailable Or Deferred Concepts
|
|
|
|
| Concept | Default Contract |
|
|
|---|---|
|
|
| Legal signature / compliance certification | not available; forbidden in this slice |
|
|
| External portal / federation / invitations | deferred |
|
|
| Risk scoring framework | deferred |
|