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/tasks.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

11 KiB
Raw Permalink Blame History

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

  • Input: specs/337-evidence-review-pack-product-process-flow-alignment/spec.md, specs/337-evidence-review-pack-product-process-flow-alignment/plan.md
  • Prerequisites: repo-truth-map.md, evidence-review-pack-state-contract.md
  • Preparation status: runtime implementation completed; checkboxes below reflect implementation and validation evidence.

Tests: Required. This changes strategic evidence/review surfaces and customer-safe package readiness presentation.

Test Governance Checklist

  • Lane assignment remains explicit and narrowest sufficient (Feature + Browser).
  • Browser coverage stays single-file and scenario-scoped.
  • No new default-heavy helpers/factories/seeds are introduced; reuse existing fixture helpers.
  • Validation commands remain minimal and directly prove the changed contract.
  • Any unreachable state resolves as document-in-feature instead of fake screenshots or fake data.

Phase 1: Preparation And Repo Truth

Purpose: Confirm repo truth and lock the state contract before runtime edits.

  • T001 Re-read spec.md, plan.md, this tasks.md, repo-truth-map.md, and evidence-review-pack-state-contract.md.
  • T002 Confirm working tree intent and record baseline commit (git status, git log -1).
  • T003 Re-verify related specs and guardrails:
    • specs/332-product-process-flow-system-v1/
    • specs/326-customer-review-workspace-v1-productization/
    • specs/329-evidence-audit-log-disclosure-productization/
    • specs/336-baseline-compare-product-process-flow-alignment/
    • .specify/memory/constitution.md
    • docs/ai-coding-rules.md
    • docs/filament-guidelines.md
    • docs/security-guidelines.md
    • docs/testing-guidelines.md
  • T004 Re-verify repo truth sources and step semantics:
    • apps/platform/app/Models/EvidenceSnapshot.php
    • apps/platform/app/Models/StoredReport.php
    • apps/platform/app/Models/ReviewPack.php
    • apps/platform/app/Models/EnvironmentReview.php
    • apps/platform/app/Models/OperationRun.php
    • 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/StoredReportResource.php
    • apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php
    • apps/platform/app/Filament/Resources/EnvironmentReviewResource.php
    • apps/platform/app/Services/Evidence/EvidenceSnapshotService.php
    • apps/platform/app/Services/ReviewPackService.php
    • apps/platform/app/Http/Controllers/ReviewPackDownloadController.php
  • T005 Update repo-truth-map.md and evidence-review-pack-state-contract.md if implementation-time code differs from the prepared truth. No update required; implementation stayed within the prepared derived-state contract.
  • T006 Confirm Product Process Flow rendering conventions from Spec 332 and decide reuse strategy before editing UI.

Phase 2: Presenter / Flow Model

Purpose: Centralize "what exists, what is missing, what is customer-safe, and what can be exported" without adding persisted truth.

  • T007 Decide whether a small EvidenceReviewPackPresenter is needed or whether existing page payload builders can produce the flow model cleanly.
  • T008 Implement the narrowest derived-only mapping for:
    • decision card (Status, Reason, Impact, Primary next action)
    • six readiness flow steps
    • proof items
    • coverage/contents summary
    • customer-safe state
    • export/download state
    • diagnostics default state
  • T009 Ensure mapping uses existing models/statuses only and introduces no new enum/status/reason family.
  • T010 Ensure primary next action is exactly one per state and capability-aware.
  • T011 Ensure unsupported states render as unavailable/deferred with honest copy.

Phase 3: Evidence Overview UI Alignment

Purpose: Make Evidence Overview the decision-first evidence readiness workbench.

  • T012 Add the decision question: Is this evidence package ready for customer or auditor consumption?
  • T013 Render Status, Reason, Impact, and Primary next action before raw artifact lists.
  • T014 Render Evidence readiness flow with Product Process Flow steps:
    • Source data selected
    • Evidence snapshot
    • Stored report
    • Review pack
    • Customer-safe output
    • Export / delivery
  • T015 Productize the Evidence Proof panel with rows for source data, snapshot, stored report, review pack, operation proof, export artifact, customer-safe state, and diagnostics.
  • T016 Keep raw artifact inventory secondary and diagnostics collapsed by default.
  • T017 Remove or avoid duplicated readiness/verdict blocks below the decision card.
  • T018 Ensure badges/status labels remain readable in light and dark mode.

Phase 4: Review Pack / Customer Review Workspace / Export States

Purpose: Productize only repo-backed customer-safe and export states.

  • T019 Align Review Pack Resource list/detail copy or proof placement only where needed for state truth. No runtime change required; existing resource state/download semantics already matched the repo-truth contract.
  • T020 Align Customer Review Workspace evidence path only if current copy conflicts with the Spec 337 state contract. No runtime change required; existing customer-safe workspace tests remain the source of customer-safe readiness truth.
  • T021 Derive review-pack available/generating/failed/expired states from ReviewPack.status, expires_at, and file metadata.
  • T022 Derive export/download available only from ready, non-expired packs with file_disk, file_path, and authorized signed download.
  • T023 Render external delivery as unavailable unless a repo-backed delivery mechanism exists.
  • T024 Derive customer-safe output ready only from Customer Review Workspace / Environment Review readiness that is already repo-backed.
  • T025 Show coverage/contents metrics only if they exist in review/evidence/report summary data.

Phase 5: OperationRun Proof / RBAC / Context / Diagnostics

Purpose: Preserve auditability and tenancy safety while hiding raw internals by default.

  • T026 Show OperationRun proof when linked and authorized:
    • status
    • started/completed timestamps
    • requested by / initiator
    • run type
    • result/outcome
    • operation detail link
  • T027 Show failed linked OperationRuns as failed proof, not as usable evidence output.
  • T028 Prevent cross-workspace/environment OperationRun and artifact links.
  • T029 Preserve workspace/environment/review query context in all secondary links.
  • T030 Keep diagnostics collapsed by default and hide raw JSON, raw payloads, stack traces, and internal exceptions on first render.
  • T031 Respect existing capabilities for generate evidence, generate report, generate review pack, export/download, open operation proof, open diagnostics, and open Customer Review Workspace.
  • T032 Do not add destructive actions; preserve confirmation and authorization on existing destructive/high-impact actions.

Phase 6: Feature Tests (Pest)

  • T033 Add apps/platform/tests/Feature/Filament/Spec337EvidenceReviewPackProductFlowTest.php.
  • T034 Test missing evidence:
    • decision question renders
    • Evidence snapshot required
    • flow visible
    • evidence snapshot marked missing
    • review pack unavailable
    • customer-safe output not ready
    • diagnostics collapsed
    • no raw JSON visible
  • T035 Test evidence snapshot available / report missing when fixture-supported:
    • evidence snapshot available
    • stored report required
    • no fake review pack ready claim
  • T036 Test review pack required when fixture-supported:
    • stored report available
    • review pack required
    • generate review pack primary action only if authorized
  • T037 Test review pack available when fixture-supported:
    • review pack available
    • customer-safe state truthful
    • export state truthful
    • no false auditor-ready claim
  • T038 Test OperationRun proof:
    • generation OperationRun visible when linked
    • no cross-workspace OperationRun leak
    • failed OperationRun shown as failed proof
  • T039 Test RBAC/context:
    • unauthorized user cannot generate/export
    • cross-workspace evidence not visible
    • no legacy tenant alias
  • T040 Update existing Evidence/ReviewPack/CustomerReview tests only where assertions are strengthened.

Phase 7: Browser Smoke + Screenshots

  • T041 Add apps/platform/tests/Browser/Spec337EvidenceReviewPackProductFlowSmokeTest.php.
  • T042 Cover browser states:
    • missing evidence snapshot
    • evidence generating if fixture-supported
    • stored report available / review pack missing
    • review pack available if fixture-supported
    • export unavailable
    • diagnostics collapsed
    • dark mode if practical
  • T043 Assert in browser:
    • Evidence readiness flow visible
    • decision card visible
    • proof panel visible
    • customer-safe state visible
    • raw payload hidden
    • primary next action visible
    • badges readable
  • T044 Capture screenshots into specs/337-evidence-review-pack-product-process-flow-alignment/artifacts/screenshots/:
    • 01-evidence-snapshot-required.png
    • 02-evidence-generating.png
    • 03-stored-report-required.png
    • 04-review-pack-required.png
    • 05-review-pack-available.png
    • 06-customer-safe-output-state.png
    • 07-export-unavailable.png
    • 08-diagnostics-collapsed.png
    • 09-dark-mode.png
  • T045 If a state is unreachable, document the repo-truth reason in implementation close-out. All required screenshot states were reachable with repo-backed fixtures.

Phase 8: Validation

  • T046 Run narrow Feature tests:
cd apps/platform
./vendor/bin/sail artisan test tests/Feature/Filament/Spec337EvidenceReviewPackProductFlowTest.php --compact
  • T047 Run browser smoke:
cd apps/platform
./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec337EvidenceReviewPackProductFlowSmokeTest.php --compact
  • T048 Run overlapping guard filters. Command ran; unrelated dashboard/restore/customer-review failures reproduced individually and are documented in close-out:
cd apps/platform
./vendor/bin/sail artisan test --filter='Evidence|ReviewPack|StoredReport|CustomerReview|ProductProcessFlow' --compact
  • T049 Run formatting and whitespace checks:
cd apps/platform
./vendor/bin/sail pint --dirty
git diff --check
  • T050 Report full-suite status honestly if not run.

Final Report Template

When implementation completes, report:

Spec 337 completed.

Changed behavior:
...

Evidence / Review Pack states:
- Evidence missing:
- Evidence generating:
- Stored report required:
- Review pack required:
- Review pack available:
- Customer-safe state:
- Export state:

Product Process Flow:
...

Files changed:
...

Tests:
- command:
- result:

Browser screenshots:
...

Known gaps:
...

Merge readiness:
...

No migrations were created.
No packages, env vars, queues, scheduler, storage, or deployment asset changes were made.
No destructive action behavior was changed.
No false customer-safe/evidence/export claims were introduced.