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

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:

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:

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:

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.