ahmido
b7c0dfe0e3
## Summary Productizes the Evidence Overview review-pack process flow so the operator sees a clear, gated progression: `evidence snapshot → stored report → review pack → customer-safe export` with explicit gating, state-appropriate copy, collapsed diagnostics, and dark-mode coverage. ## Changes - `EvidenceOverview` page + Blade view aligned to the review-pack state contract. - New feature test: `Spec337EvidenceReviewPackProductFlowTest`. - New browser smoke: `Spec337EvidenceReviewPackProductFlowSmokeTest`. - Spec 337 artifacts: `spec.md`, `plan.md`, `tasks.md`, state contract, repo-truth map, checklist, and screenshot evidence. ## Spec Kit Spec + code in one PR (Variante B). Gate satisfied: includes `specs/337-evidence-review-pack-product-process-flow-alignment/`. ## Notes Filament v5 / Livewire v4 compliant. No destructive actions added. Tooling scratch (`.playwright-mcp/`) intentionally excluded from the commit. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #407
16 KiB
16 KiB
Spec 337 - Repo Truth Map
Status: prepared
Created: 2026-05-30
Branch: 337-evidence-review-pack-product-process-flow-alignment
Numbering Reconciliation
The user-provided candidate called this "Spec 336". The repository already has specs/336-baseline-compare-product-process-flow-alignment/ and a matching branch for Baseline Compare Product Process Flow Alignment. To avoid overwriting a completed/in-progress spec, this Evidence / Review Pack preparation uses Spec 337.
Truth Classifications
repo-verified: confirmed in current runtime code, schema, routes, tests, or existing spec truth maps.derived from existing model: not stored as a standalone field, but safely computed from existing repo-backed data.foundation-real: foundation exists, but this spec must still productize or connect it.not available: no repo-backed source was found during preparation.deferred: intentionally out of scope for Spec 337.
Evidence Snapshot Model / Data Source
| Data Point | Classification | Repo Source | Notes |
|---|---|---|---|
| Evidence snapshot record | repo-verified | evidence_snapshots, App\Models\EvidenceSnapshot |
Scoped by workspace_id and managed_environment_id. |
| Evidence snapshot status | repo-verified | App\Enums\EvidenceSnapshotStatus |
queued, generating, active, superseded, expired, failed. |
| Evidence completeness | repo-verified | App\Enums\EvidenceCompletenessState, evidence_snapshots.completeness_state |
complete, partial, missing, stale. |
| Evidence freshness | repo-verified | evidence_snapshots.generated_at, expires_at; evidence_snapshot_items.freshness_at |
Use expiry/completeness/item freshness where available. |
| Evidence operation proof | repo-verified | evidence_snapshots.operation_run_id, EvidenceSnapshot::operationRun() |
Generation creates an OperationRun through EvidenceSnapshotService / GenerateEvidenceSnapshotJob. |
| Evidence initiator | repo-verified | evidence_snapshots.initiated_by_user_id, initiator() |
Useful for proof panel. |
| Evidence snapshot items | repo-verified | evidence_snapshot_items, EvidenceSnapshot::items() |
Dimension/state/source summaries. |
| Active/current evidence | repo-verified | model scopes active(), current() and partial unique index |
Current active snapshot is repo-backed. |
| Raw evidence payload | repo-verified | evidence_snapshot_items.summary_payload, snapshot summary |
Must remain collapsed by default. |
Stored Report Model / Data Source
| Data Point | Classification | Repo Source | Notes |
|---|---|---|---|
| Stored report record | repo-verified | stored_reports, App\Models\StoredReport |
Scoped by workspace_id, managed_environment_id, report_type. |
| Stored report payload | repo-verified | stored_reports.payload JSONB |
Must not be default-visible on customer-safe surfaces. |
| Stored report type | repo-verified | StoredReport::TYPE_PERMISSION_POSTURE, TYPE_ENTRA_ADMIN_ROLES |
Only these inspected report types are supported. |
| Stored report fingerprint | repo-verified | fingerprint, previous_fingerprint |
Artifact truth, not customer-safe readiness by itself. |
| Stored report freshness | derived from existing model | created_at, updated_at, valid_from, valid_until |
Use only where the implementation already treats report validity as meaningful. |
| Stored report generation OperationRun | not available | no direct relation found on StoredReport |
Do not show generating/failed report states unless a repo-backed run source is discovered in implementation. |
| Stored report global search | repo-verified | StoredReportResource::$isGloballySearchable = false |
Filament global search hard rule is satisfied by disabling search. |
Review Pack Model / Data Source
| Data Point | Classification | Repo Source | Notes |
|---|---|---|---|
| Review pack record | repo-verified | review_packs, App\Models\ReviewPack |
Scoped by workspace and environment. |
| Review pack status | repo-verified | App\Enums\ReviewPackStatus |
queued, generating, ready, failed, expired. |
| Review pack operation proof | repo-verified | review_packs.operation_run_id, ReviewPack::operationRun() |
Generation uses ReviewPackService / GenerateReviewPackJob. |
| Review pack initiator | repo-verified | initiated_by_user_id, initiator() |
Useful for proof panel. |
| Review pack evidence snapshot relation | repo-verified | review_packs.evidence_snapshot_id, ReviewPack::evidenceSnapshot() |
Review pack can be anchored to snapshot. |
| Review pack environment review relation | repo-verified | review_packs.environment_review_id, ReviewPack::environmentReview() |
Review-derived export packs are repo-backed. |
| Review pack file artifact | repo-verified | file_disk, file_path, file_size, sha256 |
Required for download/export readiness. |
| Review pack expiry | repo-verified | expires_at, ReviewPack::expired() |
Expired pack is not export-ready. |
| Review pack summary/options | repo-verified | JSON casts on summary, options |
Coverage values must come from these or related review/evidence records only. |
| Review pack global search | repo-verified | ReviewPackResource::$isGloballySearchable = false |
Filament global search hard rule is satisfied by disabling search. |
Tenant / Environment Review Relationship
| Data Point | Classification | Repo Source | Notes |
|---|---|---|---|
| Environment review record | repo-verified | environment_reviews, App\Models\EnvironmentReview |
Scoped by workspace and environment. |
| Review status | repo-verified | App\Enums\EnvironmentReviewStatus |
draft, ready, published, archived, superseded, failed. |
| Review completeness | repo-verified | App\Enums\EnvironmentReviewCompletenessState |
complete, partial, missing, stale. |
| Review evidence snapshot | repo-verified | environment_reviews.evidence_snapshot_id, evidenceSnapshot() |
Review is anchored to evidence snapshot. |
| Review current export pack | repo-verified | current_export_review_pack_id, currentExportReviewPack() |
This is the primary export/customer package relation. |
| Review operation proof | repo-verified | operation_run_id, operationRun() |
Review generation proof exists. |
| Review sections | repo-verified | EnvironmentReview::sections() |
Coverage/content summary may be derived only from these summaries. |
| Customer-safe package summary | derived from existing model | EnvironmentReview.summary, currentExportReviewPack, Customer Review Workspace readiness methods |
No separate persisted customer_safe flag found. |
| EnvironmentReview global search | repo-verified | EnvironmentReviewResource::$isGloballySearchable = false |
Filament global search hard rule is satisfied by disabling search. |
Customer Review Workspace Relationship
| Data Point | Classification | Repo Source | Notes |
|---|---|---|---|
| Customer Review Workspace route | repo-verified | /admin/reviews/workspace, CustomerReviewWorkspace |
Existing customer-safe consumption surface. |
| Latest review package payload | repo-verified | CustomerReviewWorkspace::latestReviewConsumptionPayload() |
Loads review, current export pack, evidence snapshot, OperationRuns. |
| Evidence path panel | repo-verified | CustomerReviewWorkspace::evidencePathForReview() and Blade view |
Already separates evidence path/proof rows. |
| Review pack panel | repo-verified | CustomerReviewWorkspace::reviewPackPanelForReview() |
Shows review pack state and export proof. |
| Customer-safe readiness | derived from existing model | reviewReadinessForTenant(), governancePackageAvailability(), workspaceReviewNeedsAttention() |
Ready/shareable state is derived from published review, evidence/package availability, accepted risk follow-up, and download URL. |
| Download URL for ready pack | repo-verified | reviewPackDownloadUrl() |
Requires ready package state, user capability, non-expired pack, file path/disk. |
| Diagnostics collapsed | repo-verified | diagnosticsDisclosureForReview() and view details block |
Keep collapsed by default. |
| Separate public delivery/email/share | not available | no delivery mechanism found | External delivery must render unavailable/deferred. |
OperationRun Relationship For Generation / Export
| Artifact / Flow | Classification | Repo Source | Notes |
|---|---|---|---|
| Evidence snapshot generation run | repo-verified | EvidenceSnapshotService::generate(), GenerateEvidenceSnapshotJob |
Creates/updates linked OperationRun. |
| Review pack generation run | repo-verified | ReviewPackService::generate(), GenerateReviewPackJob |
Creates/updates linked OperationRun. |
| Review-derived export generation run | repo-verified | ReviewPackService::generateFromReview() |
Links ReviewPack to EnvironmentReview and OperationRun. |
| Environment review generation run | repo-verified | EnvironmentReview::operationRun() and resource/service usage |
Review proof source exists. |
| Stored report generation run | not available | no direct StoredReport::operationRun() relation found |
Do not invent report generating/failed OperationRun proof unless discovered later. |
| Operation status/outcome | repo-verified | OperationRunStatus, OperationRunOutcome |
Use status/outcome/timeline/initiator/type/result in proof panel. |
| Cross-workspace OperationRun visibility | repo-verified | policies/helpers and route scoping | Must remain enforced in tests. |
Export / Download Artifact Relationship
| Data Point | Classification | Repo Source | Notes |
|---|---|---|---|
| Signed download route | repo-verified | /admin/review-packs/{reviewPack}/download, ReviewPackDownloadController, route name admin.review-packs.download |
Signed URL used by service/resource/workspace. |
| Download authorization | repo-verified | controller checks user, tenant access, Capabilities::REVIEW_PACK_VIEW |
Preserve. |
| Ready/exportable pack | repo-verified | ready status, not expired, file exists via disk/path | Required for Export available. |
| Download audit | repo-verified | ReviewPackDownloaded audit in controller |
Proof/audit exists. |
| Missing file behavior | repo-verified | controller aborts 404 when not ready/expired/missing file | Do not surface as available. |
| External delivery | not available | no email/share/portal delivery source found | Render External delivery is not configured if needed. |
Evidence Freshness Source
| Freshness Signal | Classification | Repo Source | Notes |
|---|---|---|---|
| Snapshot generated timestamp | repo-verified | EvidenceSnapshot.generated_at |
Displayable proof. |
| Snapshot expiry | repo-verified | EvidenceSnapshot.expires_at |
Use for stale/expired/unavailable. |
| Snapshot completeness | repo-verified | EvidenceSnapshot.completeness_state |
Complete/partial/missing/stale. |
| Item freshness | repo-verified | EvidenceSnapshotItem.freshness_at, measured_at |
Use only when summarized or safe to show. |
| Stored report validity | derived from existing model | valid_from, valid_until |
No automatic readiness claim unless existing UI/service treats validity as active. |
Customer-Safe State Source
| State Source | Classification | Repo Source | Notes |
|---|---|---|---|
| Explicit persisted customer-safe flag | not available | no standalone field found | Do not add or pretend one exists. |
| Customer Review Workspace readiness | derived from existing model | reviewReadinessForTenant(), governancePackageAvailability() |
Safest source for "ready to share" style presentation. |
| Review current export pack | repo-verified | EnvironmentReview.current_export_review_pack_id |
Indicates generated package linked to review. |
| Review accepted-risk follow-up | derived from existing model | Customer Review Workspace methods and review summary | Can require review before sharing. |
| Evidence Overview customer-safe state | foundation-real | Evidence Overview can link artifacts but does not by itself confirm customer-safe output | Render unavailable/needs review unless Customer Review Workspace package readiness is linked. |
RBAC / Capabilities
| Capability / Check | Classification | Repo Source | Notes |
|---|---|---|---|
| Evidence view/manage | repo-verified | EvidenceSnapshotPolicy, EvidenceSnapshotResource, capabilities |
Generate/refresh/expire evidence actions are capability-gated. |
| Review pack view/manage | repo-verified | ReviewPackPolicy, ReviewPackResource, download controller |
Generate/download/expire/regenerate are gated. |
| Environment review view/manage/export | repo-verified | EnvironmentReviewPolicy, EnvironmentReviewResource |
Export is policy/capability-backed. |
| Stored report view | repo-verified | StoredReportResource and report capability rules |
Read-only report surface. |
| OperationRun proof access | repo-verified | OperationRunLinks, resource/link visibility helpers |
Proof links must stay authorized. |
| Diagnostics access | foundation-real | existing collapsed diagnostics sections | Must follow existing capability/disclosure conventions. |
Routes / Surfaces
| Surface | Classification | Repo Source | Notes |
|---|---|---|---|
| Evidence Overview | repo-verified | apps/platform/routes/web.php, EvidenceOverview |
/admin/evidence/overview; named admin.evidence.overview. |
| Customer Review Workspace | repo-verified | route list, CustomerReviewWorkspace, panel provider registration |
/admin/reviews/workspace. |
| Review Pack list/detail | repo-verified | route list, ReviewPackResource |
Environment-owned route under workspace/environment. |
| Review Pack download | repo-verified | route list, ReviewPackDownloadController |
Signed route. |
| Evidence Snapshot resource | repo-verified | EvidenceSnapshotResource |
Global search disabled; list/view pages exist. |
| Stored Report resource | repo-verified | StoredReportResource |
Global search disabled; read-only detail. |
| Environment Review resource | repo-verified | EnvironmentReviewResource |
Global search disabled; export action exists. |
Existing Tests
| Test Area | Classification | Repo Source | Notes |
|---|---|---|---|
| Evidence Overview | repo-verified | apps/platform/tests/Feature/Evidence/EvidenceOverviewPageTest.php, EvidenceOverviewWorkspaceHubContractTest.php, Spec329EvidenceAuditDisclosureProductizationTest.php |
Existing evidence disclosure behavior. |
| Evidence Snapshot | repo-verified | apps/platform/tests/Feature/Evidence/*, apps/platform/tests/Unit/Evidence/* |
Snapshot generation/resolver/completeness coverage. |
| Stored Reports | repo-verified | apps/platform/tests/Feature/StoredReports/*, apps/platform/tests/Feature/Artifacts/* |
Stored report source/detail/entitlement tests. |
| Review Packs | repo-verified | apps/platform/tests/Feature/ReviewPack/*, ReviewPackAccessBoundaryTest.php |
Generation, download, RBAC, widget, redaction, entitlement. |
| Customer Review Workspace | repo-verified | apps/platform/tests/Feature/Reviews/*, apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php, Spec326CustomerReviewWorkspaceProductizationSmokeTest.php |
Existing customer workspace proof/package behavior. |
| Product Process Flow | repo-verified | apps/platform/tests/Feature/Filament/Spec332ProductProcessFlowSystemTest.php, browser Spec 332 tests |
Shared pattern foundation. |
| Baseline Product Flow consumer | repo-verified | apps/platform/tests/Feature/Filament/Spec336BaselineCompareProductProcessFlowAlignmentTest.php, browser Spec 336 test |
Completed/adjacent consumer pattern. |
| Spec 337 tests | deferred | planned in tasks.md |
Not created during prep-only work. |
Productization Implications
- Evidence Overview is the primary place to add the six-step flow.
- Customer Review Workspace is the safest source for customer-safe shareability; Evidence Overview must not infer it from raw evidence alone.
- Review Pack
readyplus file metadata enables download/export availability, but does not automatically mean auditor-ready. - StoredReport can be
AvailableorMissing; generating/failed report states are not repo-backed unless implementation discovers a valid OperationRun relation. - External delivery is not repo-backed and must be shown as unavailable/deferred if displayed.
- Raw payloads and diagnostics already have collapsed patterns; Spec 337 must preserve and test that behavior.