ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/337-evidence-review-pack-product-process-flow-alignment/repo-truth-map.md
ahmido b7c0dfe0e3 feat: align evidence review pack product process flow (Spec 337) (#407) 
## 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
2026-05-30 13:41:19 +00:00

174 lines
16 KiB
Markdown
Raw Permalink Blame History

# 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 `ready` plus file metadata enables download/export availability, but does not automatically mean auditor-ready.
- StoredReport can be `Available` or `Missing`; 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.
Reference in New Issue View Git Blame Copy Permalink