ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/342-customer-review-workspace-final-consumption-productization/tasks.md
ahmido bf10645dc3 feat: finalize customer review workspace consumption (342) (#414) 
## Summary
- finalize the existing Customer Review Workspace as a customer-safe first-screen consumption surface
- lead the page with one review decision card, readiness flow, findings summary, accepted-risk summary, and secondary proof instead of diagnostics-first presentation
- keep evidence, review-pack, export, audit, and operation proof states explicit and separate so the page does not make false readiness or evidence claims
- add focused Spec 342 Feature and Browser coverage plus the spec-local truth map, state contract, and screenshot artifacts
- preserve the existing workspace-wide route with canonical `environment_id` filtering only and no new portal, backend generation flow, or navigation rewrite

## Validation
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/Spec342CustomerReviewWorkspaceConsumptionTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php`
- `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php --compact`
- `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
- `git diff --check`

## Notes
- screenshot artifacts are included under `specs/342-customer-review-workspace-final-consumption-productization/artifacts/screenshots/`
- Livewire v4 compliance unchanged
- Filament provider registration remains in `apps/platform/bootstrap/providers.php`
- no globally searchable resource behavior changed in this slice
- no new destructive action behavior was introduced
- no new Filament assets; deploy `filament:assets` posture is unchanged
- full suite was not run in this turn; validation stayed on the focused Spec 342 slices

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #414
2026-06-01 08:15:11 +00:00

14 KiB
Raw Permalink Blame History

Tasks: Spec 342 - Customer Review Workspace v1 Final Consumption Productization

Input: specs/342-customer-review-workspace-final-consumption-productization/spec.md, plan.md, repo-truth-map.md, and customer-review-consumption-state-contract.md
Prerequisites: Spec artifacts prepared; implementation must start from repo-truth verification.
Implementation status: implemented and validated with targeted Feature/Livewire and Browser smoke coverage. The broad focused regression command was run; unrelated failures outside this customer-review spec are documented in the final implementation report.

Tests: Required. This changes a strategic customer-safe Filament/Livewire page and must be validated with Feature/Livewire tests plus one bounded Browser smoke.

Test Governance Checklist

  • Lane assignment is explicit and narrow: Feature/Livewire for state/RBAC/context, Browser for rendered customer-safe first-screen proof.
  • New or changed tests stay in the smallest honest family; browser coverage is one explicit Spec 342 smoke file.
  • Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default.
  • Planned validation commands cover the change without pulling in unrelated heavy-governance cost.
  • The surface profile is global-context-shell + customer-safe strategic review surface.
  • Any unreachable state is documented in the active spec package rather than faked.

Phase 1: Preparation And Repo Truth

Purpose: Prevent duplicate Spec 326 work and false customer-safe/evidence/export claims before runtime edits.

  • T001 Re-read specs/342-customer-review-workspace-final-consumption-productization/spec.md, plan.md, repo-truth-map.md, customer-review-consumption-state-contract.md, and this tasks.md.
  • T002 Confirm branch and working tree intent; record git status --short --branch and git log -1 --oneline.
  • T003 Inspect current CustomerReviewWorkspace page/view and existing customer-review tests before editing:
    • apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
    • apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php
    • apps/platform/tests/Feature/Reviews/
    • apps/platform/tests/Browser/Spec326CustomerReviewWorkspaceProductizationSmokeTest.php
  • T004 Inspect related truth surfaces without redesigning them:
    • EnvironmentReviewResource, EvidenceSnapshotResource, ReviewPackResource, FindingExceptionResource, StoredReportResource
    • EnvironmentReview, EvidenceSnapshot, ReviewPack, Finding, FindingException, OperationRun
    • ReviewPackDownloadController, OperationRunLinks, ArtifactTruthPresenter
  • T005 Update repo-truth-map.md with any newly discovered source, capability, unsupported state, or deferred state before runtime changes.
  • T006 Confirm no migration, package, env var, queue, scheduler, storage, Graph scope, Dokploy, or Filament asset change is required; if one appears necessary, stop and update spec/plan first.
  • T007 Confirm Filament v5 / Livewire v4.0+ compliance and no Livewire v3/Filament legacy API use.
  • T008 Confirm panel provider registration remains apps/platform/bootstrap/providers.php.
  • T009 Confirm related globally searchable resources stay disabled or have safe View/Edit pages; do not enable global search in this spec.

Phase 2: Feature Tests First

Purpose: Lock the customer-safe consumption contract before UI changes.

  • T010 Create apps/platform/tests/Feature/Filament/Spec342CustomerReviewWorkspaceConsumptionTest.php.
  • T011 [P] Add tests asserting the decision card renders status, reason, impact, and exactly one primary next action for a released review.
  • T012 [P] Add tests asserting the page does not start with a raw table/log/diagnostics surface and raw diagnostics are hidden by default.
  • T013 [P] Add tests for review-not-ready, evidence-missing, evidence-available, review-pack-required, and review-pack-available states where repo fixtures support them.
  • T014 [P] Add tests asserting no customer-safe, auditor-ready, export-ready, evidence-backed, healthy, or compliant claim appears without repo-backed truth.
  • T015 [P] Add tests for findings summary visibility, open/high-impact counts where supported, customer-safe row copy, and raw finding payload absence.
  • T016 [P] Add tests for accepted-risk summary visibility, owner/rationale/expiry/review-date fields where repo-backed, and missing review-date disclosure where applicable.
  • T017 [P] Add tests for evidence/review-pack/export state separation, including review-pack download/open action visibility only when authorized and backed by ready file metadata.
  • T018 [P] Add tests for OperationRun proof and audit trail links as secondary proof, with raw OperationRun JSON hidden.
  • T019 Add RBAC/context tests for unauthorized workspace/environment access, missing diagnostics capability, cross-workspace evidence/review-pack leakage prevention, and no /admin/t.
  • T020 Add canonical filter tests proving environment_id is the only page-level filter and legacy query aliases do not resurrect hidden context after Spec 341.

Phase 3: Consumption State Contract And Presenter

Purpose: Centralize derived display state without creating new persisted truth or a generic framework.

  • T021 Verify whether existing CustomerReviewWorkspace payload helpers can implement the state contract without a new class.
  • T022 If current page/view logic is scattered, create a small page-local CustomerReviewWorkspacePresenter or equivalent derived payload builder; keep it non-persistent and non-generic.
  • T023 Compute decision-card fields from existing truth: status, reason, impact, primary action label/url/icon, and unavailable/deferred fallbacks.
  • T024 Compute review readiness flow steps from existing review/evidence/finding/accepted-risk/review-pack/export truth.
  • T025 Compute findings summary using repo-backed status/severity/owner/due fields only; unsupported fields render unavailable/deferred.
  • T026 Compute accepted-risk summary using FindingException / decision truth only; unsupported attestation/lifecycle fields render unavailable/deferred.
  • T027 Compute evidence/review-pack/export state separately; do not treat OperationRun completion as evidence availability or customer-safe output.
  • T028 Compute diagnostics state as collapsed/unavailable by default and capability-aware when shown.

Phase 4: Customer-Safe First Screen

Purpose: Make review consumption immediately understandable without raw diagnostics.

  • T029 Update apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php to expose the final consumption payload and preserve current workspace/environment filter behavior.
  • T030 Update apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php so the first viewport starts with the decision card and proof summary, not the package index table.
  • T031 Ensure the decision card asks the customer-safe question and shows status, reason, impact, and one primary next action.
  • T032 Render review readiness flow with steps: review data, evidence, findings triaged, accepted risks reviewed, review pack, customer output.
  • T033 Render findings summary and accepted-risk summary as customer-safe content above diagnostics.
  • T034 Render evidence/review-pack/export proof panel as secondary proof and keep raw/support fields collapsed.
  • T035 Keep the existing review package index/table as secondary context after the decision and proof sections.
  • T036 Ensure copy is localization-ready and does not mix German/English static labels on the same surface.

Phase 5: Actions, RBAC, And Safety

Purpose: Preserve read-only customer-safe posture and capability-aware action visibility.

  • T037 Show only repo-backed and authorized actions: review findings, open evidence, open review pack, download review pack, open audit trail, or view operation proof.
  • T038 Hide or mark unavailable any action for acknowledgement/attestation, external delivery, regeneration, approval, revoke, expire, or repair unless it is already repo-backed and authorized.
  • T039 Ensure unauthorized actions do not leak record existence or hidden diagnostics.
  • T040 Preserve existing page-open audit logging and avoid secrets/raw payloads in metadata.
  • T041 If any destructive/high-impact action is introduced unexpectedly, stop and update spec/plan before implementing Action::make(...)->action(...), ->requiresConfirmation(), authorization, audit, notification, and tests.

Phase 6: Workspace / Environment Context

Purpose: Preserve Specs 340 and 341 while productizing review consumption.

  • T042 Verify clean /admin/reviews/workspace remains workspace-wide and does not inherit remembered environment context.
  • T043 Verify /admin/reviews/workspace?environment_id={id} filters only page data, shows visible filter context, and keeps workspace shell ownership.
  • T044 Verify clear filter returns to a clean URL and reload/back/forward do not resurrect hidden scope.
  • T045 Verify legacy query aliases are ignored or rejected and never establish authority.
  • T046 Verify cross-workspace or unauthorized environment_id remains safe no-access/404.

Phase 7: Browser Smoke And Screenshots

Purpose: Prove the rendered customer-safe experience.

  • T047 Create apps/platform/tests/Browser/Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php.
  • T048 Browser state: review not ready; assert decision card, missing reason, no false ready/export/evidence claim, diagnostics collapsed.
  • T049 Browser state: review ready with evidence; assert evidence state, review-pack state, primary next action, and no raw payload.
  • T050 Browser state: review pack available; assert open/download action only when authorized and file metadata supports it.
  • T051 Browser state: findings need attention; assert findings summary and customer-safe next action.
  • T052 Browser state: accepted risks present; assert accepted-risk summary and no hidden-only risk disclosure.
  • T053 Browser state: diagnostics collapsed; assert raw diagnostics are absent before explicit/capability-gated disclosure and rendered URLs do not contain /admin/t or legacy scope query aliases.
  • T054 Capture screenshots under specs/342-customer-review-workspace-final-consumption-productization/artifacts/screenshots/:
    • spec342-customer-review-workspace-01-evidence-incomplete-not-ready.png
    • spec342-customer-review-workspace-02-ready-with-evidence.png
    • spec342-customer-review-workspace-03-review-pack-available.png
    • spec342-customer-review-workspace-04-findings-need-attention.png
    • spec342-customer-review-workspace-05-accepted-risks-present.png
    • spec342-customer-review-workspace-06-diagnostics-collapsed.png
    • spec342-customer-review-workspace-07-dark-mode.png
  • T055 If a screenshot state is unreachable, document why in the spec package rather than faking backend truth.

Phase 8: UI Coverage And Documentation Artifacts

Purpose: Satisfy UI-COV without unrelated docs churn.

  • T056 Decide after runtime diff whether docs/ui-ux-enterprise-audit/route-inventory.md or design-coverage-matrix.md needs an update.
  • T057 UI coverage docs were not changed: this spec productizes the existing /admin/reviews/workspace route without new navigation, route inventory, or archetype coverage. The active spec artifacts and browser screenshots provide the bounded UI evidence.
  • T058 Update repo-truth-map.md final classifications for implemented, unavailable, and deferred states.
  • T059 Update customer-review-consumption-state-contract.md if implementation discovers a repo-backed state that changes the contract.
  • T060 Do not create general documentation files outside required Spec Kit/UI coverage artifacts.

Phase 9: Validation

Purpose: Run narrow proof and report honestly.

  • T061 Run cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec342CustomerReviewWorkspaceConsumptionTest.php --compact.
  • T062 Run cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php --compact.
  • T063 Run cd apps/platform && ./vendor/bin/sail artisan test --filter='CustomerReview|ReviewPack|Evidence|AcceptedRisk|Finding|Audit|Spec341' --compact (executed; customer-review regressions fixed, unrelated auth/dashboard/restore/finding-exception failures remain documented in final report).
  • T064 Run cd apps/platform && ./vendor/bin/sail pint --dirty.
  • T065 Run git diff --check.
  • T066 Report full-suite status honestly if not run.
  • T067 Confirm no migrations, seeders, packages, env vars, queues, scheduler, storage, deployment assets, backwards compatibility layer, /admin/t, or legacy query alias support were added.

Explicit Non-Goals

  • NT001 Do not build an external customer portal, external authentication, invitation links, external sharing, or email/PSA delivery.
  • NT002 Do not implement a new review, evidence, report, review-pack, export, PDF, ZIP, or queue backend.
  • NT003 Do not introduce new persisted readiness truth, enum/status family, generic readiness framework, or cross-domain UI taxonomy.
  • NT004 Do not expose raw provider JSON, raw OperationRun payload, internal IDs as primary labels, stack traces, fingerprints, or diagnostics by default.
  • NT005 Do not rewrite completed Specs 249, 258, 312, 326, 329, 335, 336, 337, 340, or 341.
  • NT006 Do not change shell/sidebar/topbar/navigation scope contracts or Provider Connection authority.
  • NT007 Do not add /admin/t routes or legacy query alias support.

Required Final Report Content For Later Implementation

When implementation later completes, report:

  • Changed behavior.
  • Customer Review states and unsupported/deferred states.
  • Customer-safe consumption and diagnostics default state.
  • Evidence / Review Pack / Export truth.
  • Findings and accepted-risk visibility.
  • RBAC/context behavior.
  • Files changed.
  • Tests run and results.
  • Browser smoke and screenshots path.
  • Known gaps and follow-up specs.
  • Full suite run/not run.
  • Explicit no migrations/packages/env/queues/scheduler/storage/deployment assets/destructive actions/backcompat/legacy aliases statement.