ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests 1 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

260 lines
11 KiB
Markdown
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
- [x] Lane assignment remains explicit and narrowest sufficient (Feature + Browser).
- [x] Browser coverage stays single-file and scenario-scoped.
- [x] No new default-heavy helpers/factories/seeds are introduced; reuse existing fixture helpers.
- [x] Validation commands remain minimal and directly prove the changed contract.
- [x] 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.
- [x] T001 Re-read `spec.md`, `plan.md`, this `tasks.md`, `repo-truth-map.md`, and `evidence-review-pack-state-contract.md`.
- [x] T002 Confirm working tree intent and record baseline commit (`git status`, `git log -1`).
- [x] 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`
- [x] 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`
- [x] 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.
- [x] 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.
- [x] T007 Decide whether a small `EvidenceReviewPackPresenter` is needed or whether existing page payload builders can produce the flow model cleanly.
- [x] 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
- [x] T009 Ensure mapping uses existing models/statuses only and introduces no new enum/status/reason family.
- [x] T010 Ensure primary next action is exactly one per state and capability-aware.
- [x] 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.
- [x] T012 Add the decision question: `Is this evidence package ready for customer or auditor consumption?`
- [x] T013 Render `Status`, `Reason`, `Impact`, and `Primary next action` before raw artifact lists.
- [x] T014 Render `Evidence readiness flow` with Product Process Flow steps:
- Source data selected
- Evidence snapshot
- Stored report
- Review pack
- Customer-safe output
- Export / delivery
- [x] 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.
- [x] T016 Keep raw artifact inventory secondary and diagnostics collapsed by default.
- [x] T017 Remove or avoid duplicated readiness/verdict blocks below the decision card.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] T021 Derive review-pack available/generating/failed/expired states from `ReviewPack.status`, `expires_at`, and file metadata.
- [x] T022 Derive export/download available only from ready, non-expired packs with `file_disk`, `file_path`, and authorized signed download.
- [x] T023 Render external delivery as unavailable unless a repo-backed delivery mechanism exists.
- [x] T024 Derive customer-safe output ready only from Customer Review Workspace / Environment Review readiness that is already repo-backed.
- [x] 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.
- [x] T026 Show OperationRun proof when linked and authorized:
- status
- started/completed timestamps
- requested by / initiator
- run type
- result/outcome
- operation detail link
- [x] T027 Show failed linked OperationRuns as failed proof, not as usable evidence output.
- [x] T028 Prevent cross-workspace/environment OperationRun and artifact links.
- [x] T029 Preserve workspace/environment/review query context in all secondary links.
- [x] T030 Keep diagnostics collapsed by default and hide raw JSON, raw payloads, stack traces, and internal exceptions on first render.
- [x] T031 Respect existing capabilities for generate evidence, generate report, generate review pack, export/download, open operation proof, open diagnostics, and open Customer Review Workspace.
- [x] T032 Do not add destructive actions; preserve confirmation and authorization on existing destructive/high-impact actions.
## Phase 6: Feature Tests (Pest)
- [x] T033 Add `apps/platform/tests/Feature/Filament/Spec337EvidenceReviewPackProductFlowTest.php`.
- [x] 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
- [x] T035 Test evidence snapshot available / report missing when fixture-supported:
- evidence snapshot available
- stored report required
- no fake review pack ready claim
- [x] T036 Test review pack required when fixture-supported:
- stored report available
- review pack required
- generate review pack primary action only if authorized
- [x] T037 Test review pack available when fixture-supported:
- review pack available
- customer-safe state truthful
- export state truthful
- no false auditor-ready claim
- [x] T038 Test OperationRun proof:
- generation OperationRun visible when linked
- no cross-workspace OperationRun leak
- failed OperationRun shown as failed proof
- [x] T039 Test RBAC/context:
- unauthorized user cannot generate/export
- cross-workspace evidence not visible
- no legacy tenant alias
- [x] T040 Update existing Evidence/ReviewPack/CustomerReview tests only where assertions are strengthened.
## Phase 7: Browser Smoke + Screenshots
- [x] T041 Add `apps/platform/tests/Browser/Spec337EvidenceReviewPackProductFlowSmokeTest.php`.
- [x] 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
- [x] 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
- [x] 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`
- [x] 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
- [x] T046 Run narrow Feature tests:
```bash
cd apps/platform
./vendor/bin/sail artisan test tests/Feature/Filament/Spec337EvidenceReviewPackProductFlowTest.php --compact
```
- [x] T047 Run browser smoke:
```bash
cd apps/platform
./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec337EvidenceReviewPackProductFlowSmokeTest.php --compact
```
- [x] T048 Run overlapping guard filters. Command ran; unrelated dashboard/restore/customer-review failures reproduced individually and are documented in close-out:
```bash
cd apps/platform
./vendor/bin/sail artisan test --filter='Evidence|ReviewPack|StoredReport|CustomerReview|ProductProcessFlow' --compact
```
- [x] T049 Run formatting and whitespace checks:
```bash
cd apps/platform
./vendor/bin/sail pint --dirty
git diff --check
```
- [x] T050 Report full-suite status honestly if not run.
## Final Report Template
When implementation completes, report:
```text
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.
```
Reference in New Issue View Git Blame Copy Permalink