TenantAtlas/specs/349-customer-review-workspace-output-resolution-guidance/plan.md

# Implementation Plan: Spec 349 - Customer Review Workspace Output Resolution Guidance

**Branch**: `349-customer-review-workspace-output-resolution-guidance` | **Date**: 2026-06-03 | **Spec**: `specs/349-customer-review-workspace-output-resolution-guidance/spec.md`  
**Input**: User-provided Spec 349 draft + repo truth from current Spec 347 readiness work, current Customer Review Workspace runtime, and current Environment Review detail surface.

## Summary

Translate existing Review Pack output-readiness truth into calmer operator guidance without changing the underlying workflow model.

This slice should:

- reuse current `ReviewPackOutputReadiness` truth
- convert the highest-priority limitation into one dominant blocker and one dominant next action
- group remaining limitations into compact disclosure
- qualify download wording honestly
- surface PII/internal-only boundaries explicitly
- separate review publication/completeness from output readiness on Environment Review detail

This slice must not:

- create persistence
- create a new workflow engine or state machine
- reopen Review Pack generation semantics beyond the already-completed Spec 347 contract
- build a portal or renderer
- weaken current authorization, workspace isolation, or signed-download safety

## Technical Context

- **Language/Version**: PHP 8.4.15, Laravel 12.52.x
- **Primary Dependencies**: Filament 5.2.x, Livewire 4.1.x, Pest 4, Tailwind CSS 4
- **Storage**: PostgreSQL; no schema change expected
- **Testing**: Pest Feature/Livewire tests plus one bounded Pest Browser smoke file
- **Validation Lanes**: confidence + browser
- **Target Platform**: `apps/platform` Laravel monolith; Sail-first locally; Dokploy posture unchanged
- **Project Type**: web application with server-rendered Filament/Blade surfaces
- **Performance Goals**: no new remote calls during render, no new queue family, and no duplicate read-model layer beyond a bounded derived guidance adapter
- **Constraints**: no false customer-safe wording, no warning wall, no hidden shell-scope behavior, no new route family, no new persisted guidance state, and no detail-surface redesign outside the output-guidance slice
- **Scale/Scope**: one strategic workspace surface, one review detail surface, existing review-pack proof/download path, focused Feature coverage, and one Browser smoke

## UI / Surface Guardrail Plan

- **Guardrail scope**: material change to an existing strategic customer-safe review surface plus an existing review detail 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`
  - `apps/platform/app/Filament/Resources/EnvironmentReviewResource.php`
  - `apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/ViewEnvironmentReview.php`
  - existing review-pack download wording as reached from those surfaces
- **No-impact class, if applicable**: N/A
- **Native vs custom classification summary**: native Filament page/resource plus existing Blade/infolist composition; no new route or panel/provider
- **Shared-family relevance**: status messaging, next-action guidance, disclosure, proof links, qualified download wording
- **State layers in scope**: page payload, detail payload, URL-query filter on workspace, derived output-guidance payload only
- **Audience modes in scope**: operator-MSP, customer-safe review consumer, support where authorized
- **Decision/diagnostic/raw hierarchy plan**: one output verdict first, grouped limitations second, technical details third
- **Raw/support gating plan**: keep technical details collapsed or clearly secondary; keep support/raw detail capability-gated where already applicable
- **One-primary-action / duplicate-truth control**: preserve one dominant next action and remove repeated blocker summaries from lower panels
- **Handling modes by drift class or surface**: review-mandatory
- **Repository-signal treatment**: review-mandatory because this is a strategic trust surface
- **Special surface test profiles**: `global-context-shell` + `shared-detail-family`
- **Required tests or manual smoke**: functional-core + browser smoke
- **Exception path and spread control**: one bounded guidance adapter is allowed; no cross-domain framework
- **Active feature PR close-out entry**: Guardrail / Smoke Coverage
- **UI/Productization coverage decision**: update `docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md`; add a second report only if implementation proves the existing identity cannot absorb the detail-surface notes cleanly
- **Coverage artifacts to update**: existing workspace page report only unless repo truth later proves more is required
- **Navigation / Filament provider-panel handling**: N/A; no panel/provider change expected
- **Screenshot or page-report need**: yes, because this is a strategic customer-safe surface and one bounded browser smoke will produce proof artifacts

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes
- **Systems touched**:
  - `App\Support\ReviewPacks\ReviewPackOutputReadiness`
  - `App\Filament\Pages\Reviews\CustomerReviewWorkspace`
  - `App\Filament\Resources\EnvironmentReviewResource`
  - `App\Filament\Resources\EnvironmentReviewResource\Pages\ViewEnvironmentReview`
  - existing review-pack and evidence link helpers
- **Shared abstractions reused**:
  - current limitation codes and readiness fields from `ReviewPackOutputReadiness`
  - current workspace link/action helper paths
  - current Environment Review artifact-truth and summary presentation
- **New abstraction introduced? why?**: maybe one narrow `ReviewPackOutputResolutionGuidance`-style adapter if direct extension of `ReviewPackOutputReadiness` would blur raw output truth and UI guidance responsibilities
- **Why the existing abstraction was sufficient or insufficient**: current readiness truth is sufficient as the source, but it is not yet shaped for grouped operator guidance across multiple surfaces
- **Bounded deviation / spread control**: any new guidance adapter must remain local to review output guidance and must not become a generic workflow-resolution framework

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: existing proof-link usage only
- **Central contract reused**: existing Review Pack / Environment Review proof links
- **Delegated UX behaviors**: unchanged
- **Surface-owned behavior kept local**: one-blocker ranking, grouped limitation copy, and qualified next-action wording
- **Queued DB-notification policy**: unchanged
- **Terminal notification path**: unchanged
- **Exception path**: none

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: no new provider seam
- **Provider-owned seams**: N/A
- **Platform-core seams**: output readiness, customer-safe/internal-only/blocked guidance vocabulary
- **Neutral platform terms / contracts preserved**: review pack, evidence basis, limitation, customer-safe, internal-only, next action
- **Retained provider-specific semantics and why**: only where current review/evidence text already carries provider-backed content
- **Bounded extraction or follow-up path**: none

## Current Repo Truth Summary

- `App\Support\ReviewPacks\ReviewPackOutputReadiness` already derives:
  - `readiness_state`
  - `customer_safe_state`
  - `primary_reason`
  - `primary_action`
  - `limitations`
  - `section_summary`
- `CustomerReviewWorkspace` already folds that truth into:
  - `effectiveWorkspaceReadinessState()`
  - `workspaceReadinessLabel()`
  - `workspaceReadinessReason()`
  - `workspaceReadinessImpact()`
  - `workspaceReadinessActions()`
  - current decision card and proof-panel payloads
- Current workspace gaps:
  - no grouped limitation list tied to one dominant blocker
  - no explicit technical-details disclosure contract for output guidance
  - existing primary/secondary action mapping is still spread across multiple helper methods
- `EnvironmentReviewResource` / `ViewEnvironmentReview` already own the detail surface:
  - infolist sections for outcome summary, review, executive posture, and sections
  - customer-workspace mode that narrows header actions
  - no explicit summary block separating review publication/completeness from output-readiness/sharing state
- Route truth is already stable and workspace/environment scoped; no new route family is needed
- Existing page audit identity is `ui-006-customer-review-workspace.md`

## Implementation Approach

### Phase 0 - Repo Truth Gate

1. Re-read the prepared `spec.md`, `plan.md`, `tasks.md`, `repo-truth-map.md`, and `checklists/requirements.md` before runtime edits.
2. Re-check current runtime truth in:
   - `apps/platform/app/Support/ReviewPacks/ReviewPackOutputReadiness.php`
   - `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`
   - `apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php`
   - `apps/platform/app/Filament/Resources/EnvironmentReviewResource.php`
   - `apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/ViewEnvironmentReview.php`
3. Keep `specs/349-customer-review-workspace-output-resolution-guidance/repo-truth-map.md` current if runtime inspection reveals additional bounded truth.

### Phase 1 - Tests First

1. Add focused guidance tests before runtime refactor:
   - `apps/platform/tests/Feature/ReviewPack/Spec349ReviewPackResolutionGuidanceTest.php`
   - `apps/platform/tests/Feature/Filament/Spec349CustomerReviewWorkspaceOutputGuidanceTest.php`
   - `apps/platform/tests/Feature/EnvironmentReview/Spec349EnvironmentReviewOutputGuidanceTest.php`
   - `apps/platform/tests/Browser/Spec349OutputResolutionGuidanceSmokeTest.php`
2. Lock the following before runtime changes:
   - one primary output state
   - one primary next action
   - grouped limitation disclosure
   - qualified download wording
   - explicit PII/internal-only warning
   - collapsed technical details by default
   - review detail separation of status dimensions
3. Reuse current review/evidence/review-pack fixtures; do not widen default helper cost.

### Phase 2 - Bounded Guidance Adapter

1. Choose the narrowest implementation home:
   - extend `ReviewPackOutputReadiness` with derived presentation fields only if raw truth remains legible, or
   - add a small `ReviewPackOutputResolutionGuidance` companion under `app/Support/ReviewPacks/`
2. Keep the guidance layer derived-only:
   - display state
   - label
   - severity
   - primary reason
   - impact
   - primary action
   - grouped limitations
   - secondary actions
   - technical-details payload
3. If additional display states such as `publication_blocked` are needed, keep them presentation-only and map them from current limitation codes or publish-blocker truth.

### Phase 3 - Action Mapping And Copy

1. Map limitation codes to plain-language guidance:
   - evidence basis incomplete -> open evidence basis
   - required sections incomplete -> review section limitations
   - mapping/control limitations -> review unmapped evidence or control interpretation
   - publish blockers -> resolve review blockers
   - contains PII -> review package contents / PII state
   - export not ready -> review output limitations
2. Prefer existing route helpers and scoped resource URLs.
3. Keep button and notification vocabulary aligned to current localization patterns: `Verb + Object`, conservative sharing language, no false-ready wording.

### Phase 4 - Customer Review Workspace Update

1. Update `CustomerReviewWorkspace` payload building to consume the bounded guidance object instead of scattered reason/action logic.
2. Update the Blade view to show:
   - one output-guidance label
   - one primary reason
   - one impact statement
   - one primary action
   - compact grouped limitations
   - qualified secondary download/action wording
   - collapsed technical details
3. Preserve current acknowledgement, accepted-risk, findings, and proof sections unless a minimal copy/order change is required to support the one-blocker hierarchy.

### Phase 5 - Environment Review Detail Update

1. Update `EnvironmentReviewResource` / `ViewEnvironmentReview` so the detail surface clearly separates:
   - review status
   - output readiness
   - publication/sharing state
2. Keep fingerprint and raw proof detail secondary or hidden in customer-workspace mode.
3. Preserve customer-workspace-mode access, download safety, and current lifecycle-action behavior outside that mode.

### Phase 6 - Localization, Audit, And Browser Proof

1. Update only the required output-guidance keys in:
   - `apps/platform/lang/en/localization.php`
   - `apps/platform/lang/de/localization.php`
2. Update `docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md` with the new guidance model, one-primary-action rule, grouped limitation behavior, and repo-truth note about the missing `ui-009-review-pack-output-contract.md`.
3. Capture screenshots under `specs/349-customer-review-workspace-output-resolution-guidance/artifacts/screenshots/`.

### Phase 7 - Validation And Close-Out

1. Run focused Feature tests for the new guidance layer and the current Spec 347 regressions.
2. Run the bounded Browser smoke for representative states.
3. Run `pint --dirty` and `git diff --check`.
4. Record any unrelated failures separately without widening scope.

## Validation Plan

```bash
cd apps/platform
./vendor/bin/sail artisan test tests/Feature/ReviewPack/Spec349ReviewPackResolutionGuidanceTest.php tests/Feature/Filament/Spec349CustomerReviewWorkspaceOutputGuidanceTest.php tests/Feature/EnvironmentReview/Spec349EnvironmentReviewOutputGuidanceTest.php --compact
./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec349OutputResolutionGuidanceSmokeTest.php --compact
./vendor/bin/sail artisan test --compact --filter=Spec347
./vendor/bin/sail artisan test --compact --filter=CustomerReviewWorkspace
./vendor/bin/sail artisan test --compact --filter=ReviewPack
./vendor/bin/sail pint --dirty
git diff --check
```

## Deployment Impact

- **Env vars**: none expected
- **Migrations**: none
- **Queues / scheduler**: none
- **Storage**: none
- **Assets**: no new Filament asset registration expected; `filament:assets` is not newly required by this change