TenantAtlas/specs/342-customer-review-workspace-final-consumption-productization/plan.md

Implementation Plan: Spec 342 - Customer Review Workspace v1 Final Consumption Productization

Branch: 342-customer-review-workspace-final-consumption-productization | Date: 2026-06-01 | Spec: specs/342-customer-review-workspace-final-consumption-productization/spec.md
Input: User-provided Spec 342 draft + roadmap candidate customer-review-workspace-v1-completion.

Summary

Finalize the existing Customer Review Workspace as a customer-safe consumption surface.

This is a runtime UX productization slice only:

• no new customer portal
• no backend review/evidence/review-pack generation rewrite
• no new persistence or lifecycle/status family
• no new Graph/provider calls
• no new routes unless implementation proves a narrow existing route/action link gap
• no shell/sidebar/topbar or canonical-link cleanup work

The implementation should make the first screen answer:

Is this review ready to consume, what requires attention, and what evidence/review-pack/export truth supports it?

Technical Context

• Language/Version: PHP 8.4.15, Laravel 12.52.x.
• Primary Dependencies: Filament v5.2.x, Livewire v4.1.x, Pest v4, Tailwind CSS v4.
• Storage: PostgreSQL; no schema change expected.
• Testing: Pest Feature/Livewire tests + one Pest Browser smoke file.
• Validation Lanes: confidence + browser.
• Target Platform: apps/platform Laravel monolith; Sail locally; Dokploy/container deployment posture unchanged.
• Project Type: Web application.
• Performance Goals: DB-only page render; no Microsoft Graph/provider calls during render; reuse eager-loaded relationships where summary state depends on related review/evidence/pack/finding records.
• Constraints: no false customer-safe/auditor-ready/export-ready/evidence-backed/compliant claims; no raw diagnostics by default; no cross-workspace/environment leakage; no /admin/t or legacy query alias resurrection.
• Scale/Scope: one existing strategic page, related proof/detail links, focused tests, one browser smoke, and spec-local artifacts.

UI / Surface Guardrail Plan

• Guardrail scope: material change to an existing strategic customer-safe review surface.
• Affected routes/pages/actions/states/navigation/panel/provider surfaces:
  • /admin/reviews/workspace
  • apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
  • apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php
  • existing linked proof/action surfaces for environment reviews, evidence snapshots, review packs, findings/accepted risks, audit, and operation proof.
• No-impact class, if applicable: N/A.
• Native vs custom classification summary: mixed, but existing route uses a native Filament page with Blade composition. New/changed UI should use Filament/shared primitives first.
• Shared-family relevance: customer-safe review consumption, evidence/report viewer, review pack/export links, status messaging, OperationRun proof links.
• State layers in scope: page payload, URL-query filter, proof/detail links, diagnostics disclosure.
• Audience modes in scope: customer/read-only, MSP operator, auditor/account manager, support where authorized.
• Navigation / Filament provider-panel handling: no navigation or panel provider change expected. Panel providers remain registered in apps/platform/bootstrap/providers.php.
• Screenshot or page-report need: screenshots required under this spec package during browser smoke. UI audit registry update is required only if implementation changes route/archetype/navigation; otherwise record active close-out no-registry-change rationale.

Shared Pattern & System Fit

• Cross-cutting feature marker: yes.
• Systems touched:
  • Customer Review Workspace page/view/payload helpers.
  • Spec 337-style evidence/review-pack process-flow semantics.
  • Existing ArtifactTruthPresenter and badge helpers where available.
  • Existing OperationRunLinks for operation proof links.
  • Existing signed review-pack download route/controller.
  • Existing policy/capability/UI enforcement paths.
• Shared abstractions reused: existing review/evidence/review-pack status enums, resource URLs, workspace hub environment filter, OperationRunLinks, ArtifactTruthPresenter, BadgeCatalog / BadgeRenderer, UiEnforcement where applicable.
• New abstraction introduced? why?: none by default. A small derived CustomerReviewWorkspacePresenter may be introduced only if it consolidates scattered page/view state and remains page-local.
• Why the existing abstraction was sufficient or insufficient: current models and services provide truth; current page may not centralize final consumption state. A local presenter can reduce duplicate Blade/Page logic without becoming a framework.
• Bounded deviation / spread control: do not create a generic readiness engine, global state taxonomy, new interface, registry, or persisted truth.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: existing proof links only.
• Central contract reused: existing OperationRun link/resource helpers and authorization.
• Delegated UX behaviors: operation deep-link URL resolution stays in shared helpers/resources; no new operation start/toast/notification lifecycle.
• Surface-owned behavior kept local: explanatory distinction between operation proof and customer evidence/review-pack/export truth.
• Queued DB-notification policy: N/A.
• Terminal notification path: unchanged.
• Exception path: none.

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: no new provider boundary.
• Provider-owned seams: N/A.
• Platform-core seams: review/evidence/review-pack/finding/audit/operation proof presentation over existing workspace/environment artifacts.
• Neutral platform terms / contracts preserved: workspace, environment, customer review, evidence, review pack, export, accepted risk, finding, operation proof, audit trail, diagnostics.
• Retained provider-specific semantics and why: only inside existing customer-safe review/evidence content where repo-backed.
• Bounded extraction or follow-up path: provider readiness remains a follow-up spec, not part of Spec 342.

Current Repo Truth Summary

• CustomerReviewWorkspace already exists as a Filament page with slug reviews/workspace, workspace-wide navigation, canonical environment_id filtering, header clear-filter action, table context, and existing page-open audit logging.
• The current Blade view already renders decision-card, readiness-dimension, follow-up, review-package-index, evidence-aside, review-pack-state, accepted-risk-summary, and diagnostics areas.
• EnvironmentReview owns review status, completeness, summary, publication timestamps, evidence snapshot, operation run, sections, review packs, and current export review pack.
• EvidenceSnapshot owns evidence status/completeness, generated/expiry timestamps, items, linked review packs, linked reviews, and operation proof.
• ReviewPack owns queued/generating/ready/failed/expired state, file metadata, expiry, linked evidence snapshot, environment review, operation run, and signed-download eligibility.
• Finding and FindingException provide finding severity/status, owner/assignee/due fields, accepted-risk/exception status, current validity, owner/rationale/review dates, decision history, and evidence references where loaded.
• ReviewPackDownloadController, ReviewPackService, and review-pack tests already prove signed download and authorization paths.
• Existing relevant tests include tests/Feature/Reviews/*, tests/Feature/ReviewPack/*, tests/Feature/Evidence/*, tests/Feature/Filament/Spec337EvidenceReviewPackProductFlowTest.php, tests/Browser/Spec326CustomerReviewWorkspaceProductizationSmokeTest.php, and tests/Browser/Spec337EvidenceReviewPackProductFlowSmokeTest.php.
• Related resources inspected for global-search posture should remain disabled or safe; this spec must not enable global search.

Implementation Approach

Phase 0 — Repo Truth Gate

1. Re-read this spec, plan, tasks, repo-truth-map.md, and customer-review-consumption-state-contract.md.
2. Re-inspect current Customer Review Workspace page/view and related tests before editing.
3. Update repo-truth-map.md with any runtime discoveries before code changes.
4. Mark unsupported concepts such as acknowledgement/attestation or external delivery as unavailable/deferred.

Phase 1 — Tests First

1. Add Feature/Livewire tests for decision-card status/reason/impact/next-action and hidden raw diagnostics.
2. Add tests for findings/accepted-risk summaries and unsupported fields.
3. Add tests for evidence/review-pack/export/operation proof separation.
4. Add RBAC/context tests for cross-workspace environment filter, diagnostics capability, authorized review-pack download/open actions, and no legacy query alias resurrection.

Phase 2 — Consumption State Contract

1. Use the spec-local contract as the mapping source for visible states.
2. If needed, create a small CustomerReviewWorkspacePresenter or page-local payload builder that computes:
   • status, reason, impact, primary next action
   • review readiness flow
   • findings summary
   • accepted-risk summary
   • evidence state
   • review-pack state
   • export state
   • proof items
   • diagnostics state
3. Keep states derived from existing models only.

Phase 3 — First-Screen Productization

1. Ensure the first viewport leads with the decision card.
2. Ensure findings and accepted risks are visible customer-safe summaries.
3. Ensure evidence, review-pack, export, audit, and operation proof are visible as secondary proof, not raw diagnostics.
4. Keep the review package index/table as secondary context.
5. Keep diagnostics collapsed or unavailable by default.

Phase 4 — Actions, RBAC, And Safety

1. Show only repo-backed, authorized primary/secondary actions.
2. Keep mutation/generation/repair actions out of the customer-safe default surface unless explicitly authorized and already repo-supported.
3. If a high-impact action becomes necessary, stop and update spec/plan before implementation.
4. Preserve existing audit logging and avoid secrets/raw payloads.

Phase 5 — Browser Smoke And Screenshots

1. Add one bounded Browser smoke file for representative states.
2. Capture screenshots under this spec package.
3. Document unreachable states rather than faking fixtures.

Phase 6 — Validation And Close-Out

1. Run focused Feature/Livewire validation.
2. Run the bounded Browser smoke.
3. Run overlapping filter tests, pint --dirty, and git diff --check.
4. Record UI coverage close-out decision and known gaps.

Test Governance Check

• Test purpose / classification by changed surface: Feature/Livewire for state/RBAC/context/false claims; Browser for rendered first-screen hierarchy, diagnostics collapsed, and screenshots.
• Affected validation lanes: confidence + browser.
• Why this lane mix is the narrowest sufficient proof: page state and authorization are cheaper and deterministic in Feature tests; rendered hierarchy and diagnostics disclosure are the product value and need browser proof.
• Narrowest proving command(s):

cd apps/platform
./vendor/bin/sail artisan test tests/Feature/Filament/Spec342CustomerReviewWorkspaceConsumptionTest.php --compact
./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php --compact
./vendor/bin/sail artisan test --filter='CustomerReview|ReviewPack|Evidence|AcceptedRisk|Finding|Audit|Spec341' --compact
./vendor/bin/sail pint --dirty
git diff --check

• Fixture / helper / factory / seed / context cost risks: reuse existing review/evidence/review-pack/finding/exception/audit/operation fixtures; no broad seeding.
• Expensive defaults or shared helper growth introduced?: no.
• Heavy-family additions, promotions, or visibility changes: one explicit browser smoke only.
• Surface-class relief / special coverage rule: no relief; strategic customer-safe surface.
• Closing validation and reviewer handoff: confirm state truth, hidden diagnostics, RBAC/context safety, one next action, screenshots, and no false readiness claims.
• Budget / baseline / trend follow-up: none expected.
• Review-stop questions: Are any claims not repo-backed? Does any state require backend truth? Did a presenter become a framework? Did browser coverage widen? Did a route/shell/query alias regress?
• Escalation path: document-in-feature for unreachable fixture states; follow-up-spec for missing backend capabilities; reject-or-split for portal/framework/backend generation.
• Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
• Why no dedicated follow-up spec is needed: final consumption belongs in this active feature; attestation, localization, governance inbox, provider readiness, and PSA handoff remain separate follow-up specs.

Project Structure

Documentation (this feature)

specs/342-customer-review-workspace-final-consumption-productization/
├── spec.md
├── plan.md
├── tasks.md
├── repo-truth-map.md
├── customer-review-consumption-state-contract.md
├── checklists/
│   └── requirements.md
└── artifacts/
    └── screenshots/

Expected implementation touch points

apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php
apps/platform/tests/Feature/Filament/Spec342CustomerReviewWorkspaceConsumptionTest.php
apps/platform/tests/Browser/Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php

Supporting surfaces to inspect, not broadly redesign

apps/platform/app/Filament/Resources/EnvironmentReviewResource.php
apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php
apps/platform/app/Filament/Resources/ReviewPackResource.php
apps/platform/app/Filament/Resources/FindingExceptionResource.php
apps/platform/app/Filament/Resources/StoredReportResource.php
apps/platform/app/Models/EnvironmentReview.php
apps/platform/app/Models/EvidenceSnapshot.php
apps/platform/app/Models/ReviewPack.php
apps/platform/app/Models/Finding.php
apps/platform/app/Models/FindingException.php
apps/platform/app/Models/OperationRun.php
apps/platform/app/Support/Navigation/WorkspaceHubEnvironmentFilter.php
apps/platform/app/Support/OperationRunLinks.php
apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
Possible page-local presenter	May be needed to centralize derived state and avoid duplicate page/view logic	Blade-only mapping risks scattered false claims and hard-to-test conditions

Proportionality Review

• New persisted truth: none.
• New abstraction: none by default; possible page-local presenter only.
• New state/status family: no; presentation states derive from existing model truth.
• Ownership cost: state contract, feature tests, browser smoke, screenshots.
• Rejected alternatives: copy-only patch, portal architecture, persisted readiness table, global readiness engine.

Constitution Check

• Inventory-first: pass; all display states derive from last-observed review/evidence/artifact truth.
• Read/write separation: pass; default surface is read-only consumption. Any existing generation/download action remains policy/audit-backed.
• Graph contract path: pass; no Graph call during page render.
• Deterministic capabilities: pass; existing policies/capabilities remain authoritative.
• RBAC-UX: pass; /admin only, workspace/environment entitlement required, non-member access is deny-as-not-found.
• Workspace/tenant isolation: pass; environment_id is filter only and must be entitlement-checked.
• Run observability: pass; no new OperationRun lifecycle. Existing runs are proof only.
• Data minimization: pass; no secrets/raw payloads/default diagnostics.
• Test governance: pass; confidence + one browser smoke are explicit.
• Proportionality / no premature abstraction: pass with bounded presenter guard.
• Persisted truth / behavioral state: pass; no new persistence or lifecycle state.
• Shared pattern first: pass; reuse Spec 337/Product Process Flow semantics and existing artifact/operation/badge helpers.
• Provider boundary: pass; no provider seam change.
• UI/Productization coverage: pass; existing strategic surface changed, screenshot/close-out coverage required.
• Filament v5 / Livewire v4 compliance: required; no Livewire v3 or Filament legacy APIs.
• Provider registration: unchanged in apps/platform/bootstrap/providers.php.
• Global search: do not enable global search for related resources in this spec.
• Destructive actions: none expected; any introduced high-impact/destructive action must use Action::make(...)->action(...), ->requiresConfirmation(), authorization, audit, notification, and tests after spec/plan update.
• Asset strategy: no registered assets expected; if assets are introduced, update deployment to run cd apps/platform && php artisan filament:assets.

Deployment / Ops Impact

No migrations, env vars, packages, queues, scheduler, storage, Graph scopes, Dokploy config, or Filament assets are expected. Runtime impact is UI/page rendering plus tests. If implementation proves otherwise, update spec/plan before coding further.