TenantAtlas/specs/326-customer-review-workspace-v1-productization/plan.md

# Implementation Plan: Spec 326 - Customer Review Workspace v1 Productization

**Branch**: `326-customer-review-workspace-v1-productization` | **Date**: 2026-05-18 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/326-customer-review-workspace-v1-productization/spec.md`

## Summary

Productize the existing Customer Review Workspace into a customer-safe, decision-first review consumption hub. The implementation must refactor the existing Filament page/view around readiness, evidence path, review-pack state, accepted risks, follow-ups, scope, and diagnostics disclosure while preserving existing workspace/environment contracts, policies, audit, and repo-truth boundaries.

No application implementation was performed during preparation. Runtime implementation starts from `tasks.md` in a later implementation loop.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12.52.0
**Primary Dependencies**: Filament 5.2.1, Livewire 4.1.4, Laravel Sail 1.52.0
**Storage**: PostgreSQL via Sail/Dokploy; no schema change expected
**Testing**: Pest 4.3.1, PHPUnit 12.5.4, Pest Browser for named smoke
**Validation Lanes**: confidence plus browser for Spec 326 smoke; no PostgreSQL migration lane expected unless runtime changes unexpectedly touch schema
**Target Platform**: Laravel monolith under `apps/platform`
**Project Type**: web application / Filament admin panel
**Performance Goals**: render from persisted DB state only; no Graph calls during render; avoid broad eager loading or per-row service calls beyond existing patterns
**Constraints**: customer-safe default view, no raw diagnostics, no false green, no new backend foundation, no migrations/packages/env/assets by default
**Scale/Scope**: one existing workspace-scoped page and targeted tests

## UI / Surface Guardrail Plan

- **Guardrail scope**: changed 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 review/pack/evidence/finding links only as repo-supported handoffs.
- **No-impact class, if applicable**: N/A.
- **Native vs custom classification summary**: native Filament page and components plus existing Blade composition; no CSS/JS asset bundle expected.
- **Shared-family relevance**: customer-safe review consumption, status messaging, action links, evidence/report viewer, review-pack delivery, diagnostics disclosure.
- **State layers in scope**: page payload, URL query (`environment_id`), table/session filter state, diagnostic disclosure state if implemented.
- **Audience modes in scope**: customer/read-only, MSP operator, auditor/account manager; support/operator diagnostics only where authorized.
- **Decision/diagnostic/raw hierarchy plan**: decision-first default, evidence/proof second, diagnostics/support/raw third and collapsed/gated.
- **Raw/support gating plan**: hidden by default; only explicit disclosure and existing authorization if implemented.
- **One-primary-action / duplicate-truth control**: main decision card owns status/reason/impact/primary action; panels add proof/source without restating the same blocker in multiple forms.
- **Handling modes by drift class or surface**: review-mandatory for customer-safe disclosure, environment scope, and false-green risk.
- **Repository-signal treatment**: review-mandatory; update `repo-truth-map.md` before runtime edits and document unavailable states.
- **Special surface test profiles**: `global-context-shell`, customer-safe disclosure, browser smoke.
- **Required tests or manual smoke**: Feature/Livewire tests for layout/RBAC/scope/disclosure plus Pest Browser smoke for clean/filtered/clear/reload/diagnostics.
- **Exception path and spread control**: none expected; any CSS-heavy/custom UI or new backend support must update spec/plan before implementation.
- **Active feature PR close-out entry**: Smoke Coverage.
- **UI/Productization coverage decision**: existing page materially changed; implementation must either update coverage registry or document why existing UI-006 report/Spec 325 target artifacts remain sufficient.
- **Coverage artifacts to update**: likely `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` or close-out note; exact need depends on runtime diff.
- **No-impact rationale**: N/A.
- **Navigation / Filament provider-panel handling**: no panel provider or navigation change expected; registration remains in `apps/platform/bootstrap/providers.php`.
- **Screenshot or page-report need**: screenshots required under the spec artifacts; no full new page report unless implementation changes route inventory beyond the existing page.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes.
- **Systems touched**: CustomerReviewWorkspace, review workspace Blade, WorkspaceHubEnvironmentFilter/FilterStateResetter, EnvironmentReviewRegisterService, ReviewPackService, existing policies and resources for handoff links.
- **Shared abstractions reused**: `EnvironmentReviewRegisterService`, `WorkspaceHubEnvironmentFilter`, `WorkspaceHubFilterStateResetter`, `ArtifactTruthPresenter` where already used, existing `ReviewPackStatus`, `EnvironmentReviewStatus`, `EvidenceSnapshotStatus`, `FindingException` state/validity, existing `WorkspaceAuditLogger`.
- **New abstraction introduced? why?**: none expected. Page-local helpers are permitted only to keep Blade simple.
- **Why the existing abstraction was sufficient or insufficient**: existing services/policies already own truth and access. The gap is productized layout/disclosure, not missing backend foundation.
- **Bounded deviation / spread control**: no cross-surface pattern library; any helper stays private to the page unless a later spec proves broader need.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no start/completion semantics; possible secondary proof links only.
- **Central contract reused**: existing operation route/link support if proof links are exposed.
- **Delegated UX behaviors**: N/A for start; proof links must use existing URL/auth helpers.
- **Surface-owned behavior kept local**: display proof availability/unavailability only.
- **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**: none.
- **Platform-core seams**: review/evidence/review-pack/accepted-risk display from TenantPilot artifacts.
- **Neutral platform terms / contracts preserved**: workspace, environment filter, review, evidence, review pack, accepted risk, decision trail, operation proof.
- **Retained provider-specific semantics and why**: existing review content may contain Microsoft/Intune terms where it is already customer-safe.
- **Bounded extraction or follow-up path**: none for Spec 326.

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- Inventory-first: page consumes persisted review/evidence/pack/finding data only.
- Read/write separation: default page is read-only; no destructive or remote mutation actions expected.
- Graph contract path: no Graph calls in UI render or this feature's default flow.
- Deterministic capabilities: reuse existing capability/policy checks; no raw strings in new action handlers.
- RBAC-UX: non-member workspace/environment access is 404; missing capabilities hide/disable actions according to existing policy semantics.
- Workspace isolation: workspace context remains primary; `environment_id` resolved only within current workspace and actor entitlement.
- Tenant isolation: managed-environment data remains scoped by workspace and entitlement.
- Run observability: no new OperationRun; proof links only when existing and authorized.
- Ops-UX lifecycle: unchanged.
- Test governance: Feature and browser tests are explicitly named; helper/fixture cost must remain feature-local.
- Proportionality: no new persisted truth, status families, abstractions, or cross-domain UI framework.
- No premature abstraction: page-local derived display helpers only.
- Persisted truth: no migrations, seeders, backfills, or packages expected.
- Behavioral state: display states are derived labels, not persisted domain states.
- UI semantics: do not turn badges/explanations into a new semantic layer.
- Shared pattern first: use existing Filament, status enums, `ArtifactTruthPresenter`, and action/link helpers where present.
- Provider boundary: no provider-core drift.
- Filament-native UI: use native Filament sections/cards/badges/actions and existing partials first.
- UI/Productization coverage: material page change must be reflected in active spec and implementation close-out or registry docs.
- Filament v5 / Livewire v4 compliance: required; no v3/v4 legacy APIs.
- Panel provider location: remains `apps/platform/bootstrap/providers.php`.
- Global search: related resources currently keep `protected static bool $isGloballySearchable = false`; do not enable global search in this spec.
- Destructive actions: none expected; if introduced, must be `Action::make(...)->action(...)` plus confirmation, auth, audit, tests.
- Asset strategy: no new registered assets expected; `filament:assets` only needed if implementation unexpectedly registers assets.

## Test Governance Check

- **Test purpose / classification by changed surface**: Feature/Livewire for page payload, RBAC, scope, disclosure; Browser for critical customer-safe workflow smoke.
- **Affected validation lanes**: confidence, browser.
- **Why this lane mix is the narrowest sufficient proof**: page is user-facing and shell/filter-sensitive; Feature tests prove logic, Browser smoke proves rendered shell/filter/disclosure behavior.
- **Narrowest proving command(s)**:
  - `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Reviews tests/Feature/Navigation/WorkspaceHubEnvironmentFilterContractTest.php tests/Feature/Navigation/WorkspaceHubClearFilterContractTest.php --compact`
  - `cd apps/platform && ./vendor/bin/sail artisan test tests/Browser/Spec326CustomerReviewWorkspaceProductizationSmokeTest.php --compact`
  - `cd apps/platform && ./vendor/bin/sail artisan test --filter='CustomerReviewWorkspace|WorkspaceHub|EnvironmentFilter|ClearFilter|LegacyTenant|Spec322' --compact`
  - `cd apps/platform && ./vendor/bin/sail pint --dirty`
  - `git diff --check`
- **Fixture / helper / factory / seed / context cost risks**: reuse existing review/evidence/pack helpers; no broad fixture default changes.
- **Expensive defaults or shared helper growth introduced?**: no.
- **Heavy-family additions, promotions, or visibility changes**: one explicit browser smoke family named for Spec 326.
- **Surface-class relief / special coverage rule**: no standard-native relief because customer-safe disclosure and global-context-shell behavior require explicit tests.
- **Closing validation and reviewer handoff**: verify no raw diagnostics, no false green, correct scope, RBAC action visibility, screenshots, and unchanged panel provider/global search posture.
- **Budget / baseline / trend follow-up**: none expected.
- **Review-stop questions**: Does any visible claim lack repo source? Does any URL alias set scope? Is any action unauthorized? Is diagnostics default-hidden? Are screenshots free of sensitive data?
- **Escalation path**: document-in-feature if browser fixture/setup cost grows.
- **Active feature PR close-out entry**: Smoke Coverage.
- **Why no dedicated follow-up spec is needed**: this is a single strategic surface; broader pattern library/governance inbox/operations/evidence surfaces are separate follow-up specs.

## Project Structure

### Documentation (this feature)

```text
specs/326-customer-review-workspace-v1-productization/
├── spec.md
├── plan.md
├── tasks.md
├── repo-truth-map.md
├── checklists/
│   └── requirements.md
└── artifacts/
    └── screenshots/
```

### Source Code (repository root)

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/Reviews/
apps/platform/tests/Feature/Navigation/
apps/platform/tests/Browser/Spec326CustomerReviewWorkspaceProductizationSmokeTest.php
```

Supporting surfaces to inspect but not broadly redesign:

```text
apps/platform/app/Filament/Resources/EnvironmentReviewResource.php
apps/platform/app/Filament/Resources/ReviewPackResource.php
apps/platform/app/Filament/Resources/EvidenceSnapshotResource.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/ReviewPack.php
apps/platform/app/Models/EvidenceSnapshot.php
apps/platform/app/Models/FindingException.php
apps/platform/app/Models/StoredReport.php
apps/platform/app/Models/OperationRun.php
apps/platform/app/Support/Navigation/WorkspaceHubEnvironmentFilter.php
apps/platform/app/Support/Navigation/WorkspaceHubFilterStateResetter.php
apps/platform/app/Filament/Concerns/ClearsWorkspaceHubEnvironmentFilterState.php
```

## Phase 0: Discovery Completed During Preparation

- Current route exists: `GET|HEAD admin/reviews/workspace`.
- Current page class exists: `CustomerReviewWorkspace`.
- Current Blade view exists and already uses Filament sections, badges, environment filter chip, latest released review, decision summary, accepted risks, evidence basis, and table.
- Existing tests cover Customer Review Workspace page, pack access, authorization, navigation context, hub contract, and browser smoke.
- Existing workspace hub filter support uses canonical `environment_id`, cleans legacy keys, and resolves environment within the current workspace/actor entitlement.
- Related resources (`EnvironmentReviewResource`, `ReviewPackResource`, `EvidenceSnapshotResource`, `FindingExceptionResource`, `StoredReportResource`) have global search disabled.
- Panel providers are registered in `apps/platform/bootstrap/providers.php`.
- Spec 312 and Specs 314-325 are historical dependencies; they are not modified.

## Phase 1: Repo Truth Map

Create/update `repo-truth-map.md` before runtime edits and keep it aligned during implementation. Any UI element with no repo-backed source must become unavailable/empty/deferred in the runtime surface.

## Phase 2: Page Skeleton Productization

Refactor the page around:

- Header / scope area.
- Main decision card.
- Readiness summary cards.
- Evidence path panel.
- Review pack panel.
- Accepted risk summary.
- Customer-safe findings/follow-ups.
- Collapsed diagnostics.

Use existing Filament layout primitives. Avoid new asset registration and CSS-heavy custom systems.

## Phase 3: Data Binding

Bind each section to repo-verified sources:

- `EnvironmentReview` for released review and summary.
- `ReviewPack` / `ReviewPackStatus` / `ReviewPackService` for pack state and download.
- `EvidenceSnapshot` and review summary completeness for evidence freshness/path.
- `FindingException` and review package accepted-risk summary for accepted risks.
- `Finding` / decision-summary entries for customer-safe follow-ups where supported.
- `OperationRun` relations only as secondary proof links where already present and authorized.

If data is missing, show explicit unavailable/empty state.

## Phase 4: Actions

Only include repo-real and authorized actions:

- Open review pack / download review pack.
- Open latest review.
- Open evidence snapshot if route/auth exists and is customer-safe.
- Review accepted risks / open queue if existing and authorized.
- Open operation proof if existing and authorized.
- Clear environment filter.
- Open diagnostics only if authorized and collapsed by default.

Do not introduce generation, refresh, publish, expire, revoke, restore, or other customer-impacting mutation actions on the default customer-safe view.

## Phase 5: Scope / Filter Integration

Verify clean workspace entry, filtered `environment_id` entry, visible chip, clear filter, reload safety, legacy alias rejection, and cross-workspace guard. Keep shell Workspace-owned.

## Phase 6: Browser Verification

Run targeted browser verification for clean entry, filtered entry, clear/reload, diagnostics default-hidden, evidence path/review-pack/accepted-risk visibility or explicit unavailable state, and light mode readability where supported.

Screenshots may be saved under:

```text
specs/326-customer-review-workspace-v1-productization/artifacts/screenshots/
```

## Follow-up Plan: Premium Layout Alignment

The follow-up remains inside Spec 326 and narrows to the existing Customer Review Workspace runtime surface.

- Compact the customer-safe header copy and quiet the non-certification disclosure.
- Recompose the Blade view into a main/aside workbench using a responsive `xl:grid-cols-[minmax(0,1fr)_22rem]` layout.
- Keep the main column focused on the decision card, readiness/evidence/review-pack/accepted-risk state cards, customer-safe follow-ups, and the secondary review package table.
- Move evidence path, review-pack state, accepted-risk counts/records, disclosure rules, and collapsed diagnostics into the right aside.
- Preserve existing page-local truth helpers and add only derived display payloads for the aside; no new persisted truth, services, routes, actions, or assets.
- Extend tests for premium layout copy, right-aside sections, collapsed diagnostics, hidden raw diagnostics, and absence of platform-context `tenant` copy.
- Capture `customer-review-workspace-premium-layout.png` in the existing Spec 326 screenshot artifact directory.

## Complexity Tracking

No migrations, no seeders, no packages, no env vars, no queues/scheduler/storage changes, no deployment asset changes, and no backwards compatibility layer are expected.

If implementation proves otherwise, stop, update `spec.md` and this plan, and re-run preparation review before coding the expanded scope.