TenantAtlas/specs/337-evidence-review-pack-product-process-flow-alignment/plan.md

Implementation Plan: Spec 337 - Evidence Path / Review Pack Product Process Flow Alignment

• Branch: 337-evidence-review-pack-product-process-flow-alignment
• Date: 2026-05-30
• Spec: specs/337-evidence-review-pack-product-process-flow-alignment/spec.md
• Input: User-provided Spec 336 draft + repo inspection; reconciled to Spec 337 because repo already has Spec 336 for Baseline Compare.

Summary

Align existing Evidence / Review Pack readiness surfaces to the shared Product Process Flow contract from Spec 332.

This is runtime UX alignment only:

• no backend evidence engine rewrite
• no report/review-pack/export engine rewrite
• no new persistence
• no new OperationRun lifecycle semantics
• no new routes, packages, migrations, queues, scheduler, storage, or env vars

The implementation should make the readiness chain visible and truthful:

Source data selected -> Evidence snapshot -> Stored report -> Review pack -> Customer-safe output -> Export / delivery

Technical Context

• Language/Version: PHP 8.4.15, Laravel 12.x.
• Primary Dependencies: Filament v5 + Livewire v4, Pest v4, Tailwind v4.
• Storage: PostgreSQL; no schema change expected.
• Testing: Pest Feature/Livewire render tests + one browser smoke file.
• Validation Lanes: confidence + browser.
• Target Platform: Sail locally; Dokploy/container deployment posture unchanged.
• Project Type: Laravel monolith under apps/platform.
• Performance Goals: DB-only render; no Microsoft Graph/provider calls during page render.
• Constraints: no new backend engines, no new persisted readiness truth, no new queue/scheduler behavior, no fake customer-safe/auditor-ready/export-ready claims, no raw payload default view, no cross-workspace leaks.
• Scale/Scope: bounded to existing Evidence Overview, Review Pack, Stored Report/Evidence Snapshot proof links, Environment Review export proof, and Customer Review Workspace evidence path only where needed.

UI / Surface Guardrail Plan

• Guardrail scope: changed existing operator-facing and customer-safe evidence surfaces.
• Affected routes/pages/actions/states/navigation/panel/provider surfaces:
  • /admin/evidence/overview
  • /admin/reviews/workspace
  • /admin/workspaces/{workspace}/environments/{environment}/review-packs
  • /admin/review-packs/{reviewPack}/download
  • linked Evidence Snapshot, Stored Report, Environment Review, and OperationRun proof surfaces only as needed
• No-impact class, if applicable: N/A.
• Native vs custom classification summary: mixed but existing: Filament resources/pages plus existing Blade workbench sections and shared primitives.
• Shared-family relevance: Product Process Flow, evidence disclosure, OperationRun proof, artifact truth, customer-safe review package state.
• State layers in scope: page, detail, URL-query/environment filter, artifact links, signed download availability.
• Audience modes in scope: operator-MSP, manager, support reviewer, customer-readable review workspace.
• Decision/diagnostic/raw hierarchy plan: decision-first, proof second, diagnostics/raw third and collapsed.
• Raw/support gating plan: collapsed by default; capability-aware using existing conventions.
• One-primary-action / duplicate-truth control: compute one state-specific primary action; lower sections add proof, not alternate verdicts.
• Handling modes by drift class or surface: review-mandatory for customer-safe and auditor-facing claims; report-only for diagnostics.
• Repository-signal treatment: customer-safe/export signals must be repo-backed; unavailable/deferred is preferred over invented readiness.
• Special surface test profiles: monitoring-state-page, shared-detail-family, customer-safe consumption path.
• Required tests or manual smoke: feature state contract + browser smoke + screenshots.
• Exception path and spread control: no exception expected; follow-up spec if implementation requires new persisted lifecycle truth.
• Active feature PR close-out entry: Smoke Coverage.
• UI/Productization coverage decision: feature-local screenshots/tests required; audit docs only if route/archetype/navigation changes during implementation.
• Coverage artifacts to update: none expected in prep.
• No-impact rationale: N/A.
• Navigation / Filament provider-panel handling: no panel/provider registration change. Laravel 11+/12 provider registration remains apps/platform/bootstrap/providers.php.
• Screenshot or page-report need: screenshots required under specs/337-evidence-review-pack-product-process-flow-alignment/artifacts/screenshots/.

Shared Pattern & System Fit

• Cross-cutting feature marker: yes.
• Systems touched:
  • Spec 332 Product Process Flow system.
  • Spec 329 Evidence Overview proof-first disclosure.
  • Spec 326 Customer Review Workspace evidence path.
  • Review Pack Resource list/detail/download.
  • Evidence Snapshot Resource proof links.
  • Stored Report Resource proof links.
  • Environment Review current export/review pack proof.
  • OperationRun proof links.
• Shared abstractions reused:
  • Product Process Flow render conventions from Spec 332.
  • OperationRunLinks.
  • OperationUxPresenter where operation start/progress messaging is already delegated.
  • UiEnforcement and policy/capability gates for actions.
  • BadgeCatalog / BadgeRenderer where status-like badges are introduced or changed.
• New abstraction introduced? why?: none required in prep. A small EvidenceReviewPackPresenter or page-local view model is allowed only if it prevents scattered Blade/Page logic and remains derived-only.
• Why the existing abstraction was sufficient or insufficient: Product Process Flow is sufficient for readiness steps; a local presenter may be needed because readiness combines snapshots, reports, packs, review state, and operation proof without a single persisted lifecycle record.
• Bounded deviation / spread control: do not create a generic workflow engine or state taxonomy. Presentation-only states stay in the feature contract and tests.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes, for existing proof links and generation/export state display.
• Central contract reused: existing OperationRun lifecycle, OperationRunLinks, OperationUxPresenter, and services/jobs that already create or update runs.
• Delegated UX behaviors: queued toast, operation deep link, signed artifact link, tenant/workspace-safe URL resolution, and active-run blocked messaging remain in existing services/resources.
• Surface-owned behavior kept local: explanation copy, readiness flow placement, proof panel ordering.
• Queued DB-notification policy: no change.
• Terminal notification path: unchanged.
• Exception path: none.

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: no.
• Provider-owned seams: N/A.
• Platform-core seams: evidence/report/review artifact presentation only; no provider contract changes.
• Neutral platform terms / contracts preserved: workspace, environment, review, evidence snapshot, stored report, review pack, customer-safe output, export/download, operation proof.
• Retained provider-specific semantics and why: existing report type labels such as Entra admin roles remain only where stored reports already expose them.
• Bounded extraction or follow-up path: none.

Constitution Check

GATE: Must pass before runtime work and be rechecked after implementation design.

• Inventory-first: pass. This spec separates source data, snapshots, stored reports, review packs, customer-safe output, and export artifacts.
• Read/write separation: pass. Existing generate/export actions stay explicit, capability-gated, and OperationRun/audit-backed; no destructive action added.
• Graph contract path: pass. Page render must not call Graph/providers.
• RBAC-UX: pass. Existing policies/capabilities must continue to deny cross-workspace/environment leakage.
• Workspace isolation: pass. Canonical evidence overview keeps environment filter/context and resource routes remain workspace/environment-scoped.
• Run observability: pass. Existing long-running evidence/review-pack work remains OperationRun-backed; this spec adds proof presentation only.
• Ops-UX lifecycle: pass. No OperationRun lifecycle changes.
• Data minimization: pass. Raw payloads and diagnostics stay collapsed and capability-aware.
• Test governance: pass. Feature + browser lanes are explicit and bounded.
• Proportionality: pass. No persisted truth; only a small derived presenter if needed.
• No premature abstraction: pass. Reuse Spec 332 Product Process Flow and existing artifact/proof helpers.
• Persisted truth: pass. No new tables/entities/artifacts.
• Behavioral state: pass. Presentation states are derived and do not add lifecycle semantics.
• Shared pattern first: pass. Product Process Flow is the core reuse.
• Provider boundary: pass. No provider seam change.
• Badge semantics: pass. New/changed status-like badges must use shared badge semantics.
• Filament-native UI: pass. Use existing Filament/Blade surface conventions and shared primitives.
• Decision-first operating model: pass. Decision card and flow come before tables/raw artifacts.
• Audience-aware disclosure: pass. Customer-readable default hides raw JSON, payloads, diagnostics, fingerprints, and internal reason ownership.
• UI/Productization coverage: pass. Existing reachable surfaces changed; feature-local screenshots/tests are required.

Test Governance Check

• Test purpose / classification by changed surface: Feature tests for state contract, RBAC/context, false-claim prevention; Browser smoke for rendered flow, proof panel, collapsed diagnostics, screenshots.
• Affected validation lanes: confidence + browser.
• Why this lane mix is the narrowest sufficient proof: state composition and RBAC can be proven in Feature tests; layout/readability/collapsed diagnostics require one browser smoke.
• Narrowest proving command(s):

cd apps/platform
./vendor/bin/sail artisan test tests/Feature/Filament/Spec337EvidenceReviewPackProductFlowTest.php --compact
./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec337EvidenceReviewPackProductFlowSmokeTest.php --compact

• Fixture / helper / factory / seed / context cost risks: reuse existing workspace/environment/user/EvidenceSnapshot/StoredReport/ReviewPack/EnvironmentReview/OperationRun fixtures. Do not add heavy default seeds.
• Expensive defaults or shared helper growth introduced?: no.
• Heavy-family additions, promotions, or visibility changes: one explicit browser smoke file only.
• Surface-class relief / special coverage rule: no standard-native relief; this is a strategic/customer-safe workbench alignment.
• Closing validation and reviewer handoff: verify no raw JSON initial render, no false customer-safe/export/auditor-ready claims, no cross-workspace evidence leaks, and one primary action per state.
• Budget / baseline / trend follow-up: none expected.
• Review-stop questions: if a fixture needs new backend state, stop and mark the state unavailable/deferred instead of adding persistence.
• Escalation path: document-in-feature for unreachable states; follow-up-spec for backend readiness engine needs.
• Active feature PR close-out entry: Smoke Coverage.
• Why no dedicated follow-up spec is needed: this is a bounded Product Process Flow consumer; broader auditor artifact delivery remains a separate future spec.

Current Repo Truth Summary (Implementation-Relevant)

• EvidenceSnapshot exists with status, completeness, generated/expiry timestamps, items, workspace/environment, operation, initiator, review packs, and environment reviews.
• StoredReport exists for permission posture and Entra admin role reports; it stores JSONB payloads and fingerprints but has no direct OperationRun relationship in inspected code.
• ReviewPack exists with queued/generating/ready/failed/expired status, file metadata, evidence snapshot, environment review, OperationRun, and initiator.
• EnvironmentReview exists with evidence snapshot, OperationRun, current export review pack, sections, status, completeness, and summary.
• CustomerReviewWorkspace already derives review/package/customer-safe consumption state and signed download availability from existing review and pack truth.
• EvidenceOverview already has a proof-first workbench and collapsed diagnostics, but does not yet render the six-step Evidence readiness flow.
• Signed review-pack downloads are repo-backed via ReviewPackDownloadController, signed route, policies/capabilities, ready/non-expired/file metadata checks, and audit logging.
• Global search is disabled on relevant resources inspected (EvidenceSnapshotResource, ReviewPackResource, StoredReportResource, EnvironmentReviewResource).

Implementation Approach

Phase 0 - Repo Truth Gate (No Runtime Edits)

1. Confirm repo-truth-map.md and evidence-review-pack-state-contract.md still match runtime code.
2. Re-inspect Evidence Overview, Customer Review Workspace, ReviewPackResource, StoredReportResource, EvidenceSnapshotResource, EnvironmentReviewResource, OperationRun links, and download controller.
3. Mark unsupported states unavailable/deferred instead of implementing new backend truth.

Phase 1 - Presenter / Flow Model

1. If needed, create a small EvidenceReviewPackPresenter or page-local view model that computes:
   • decision card fields
   • six flow steps
   • proof items
   • coverage summary
   • customer-safe state
   • export/download state
   • diagnostics state
2. Keep the presenter derived-only. No static process memoization, no new source of truth, no new enum/status family.

Phase 2 - Evidence Overview UI Alignment

1. Add the decision card question and fields.
2. Add the Evidence readiness flow using the Product Process Flow pattern.
3. Productize the proof panel while preserving existing collapsed diagnostics.
4. Keep raw artifact tables secondary.
5. Avoid duplicate verdict/readiness blocks.

Phase 3 - Review Pack / Customer-Safe / Export States

1. Productize review pack state from existing ReviewPack status and file metadata.
2. Productize export/download state only where ready, non-expired, file-backed, signed download is authorized.
3. Productize customer-safe state only where Customer Review Workspace / Environment Review package readiness supports it.
4. Show external delivery as unavailable unless implementation discovers repo-backed delivery.

Phase 4 - RBAC / Context / Diagnostics

1. Preserve workspace/environment/review context in all action links.
2. Respect existing capability-first gates.
3. Keep non-member/cross-workspace artifacts hidden or not found.
4. Keep diagnostics collapsed and raw JSON hidden by default.

Phase 5 - Tests

1. Add apps/platform/tests/Feature/Filament/Spec337EvidenceReviewPackProductFlowTest.php.
2. Cover missing evidence, report missing, review pack required, review pack available, OperationRun proof, RBAC/context, no raw JSON, and no false claims.
3. Update existing tests only where assertions are strengthened for the new contract.

Phase 6 - Browser Smoke + Screenshots

1. Add apps/platform/tests/Browser/Spec337EvidenceReviewPackProductFlowSmokeTest.php.
2. Capture screenshots under specs/337-evidence-review-pack-product-process-flow-alignment/artifacts/screenshots/.
3. Document unreachable states rather than faking screenshots.

Phase 7 - Hygiene + Validation

1. Run the feature and browser commands.
2. Run overlapping filters.
3. Run Pint and git diff --check.
4. Report deployment impact: no migrations, packages, env vars, queues, scheduler, storage, or asset changes expected.

Project Structure

Documentation (this feature)

specs/337-evidence-review-pack-product-process-flow-alignment/
├── spec.md
├── plan.md
├── tasks.md
├── repo-truth-map.md
├── evidence-review-pack-state-contract.md
├── checklists/
│   └── requirements.md
└── artifacts/
    └── screenshots/

Expected Source Code Touchpoints (implementation phase only)

apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php
apps/platform/resources/views/filament/pages/monitoring/evidence-overview.blade.php
apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php
apps/platform/app/Filament/Resources/ReviewPackResource.php
apps/platform/app/Filament/Resources/ReviewPackResource/Pages/ViewReviewPack.php
apps/platform/app/Filament/Resources/EnvironmentReviewResource.php
apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php
apps/platform/app/Filament/Resources/StoredReportResource.php
apps/platform/app/Support/... (only if a small derived presenter is needed)
apps/platform/tests/Feature/Filament/Spec337EvidenceReviewPackProductFlowTest.php
apps/platform/tests/Browser/Spec337EvidenceReviewPackProductFlowSmokeTest.php

Do not create these runtime/test files during preparation-only work. They are listed for the implementation phase.