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)**:

```bash
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)

```text
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

```text
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

```text
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.