TenantAtlas/specs/387-review-publication-resolution-decision-ux-v1/plan.md

# Implementation Plan: Spec 387 - Review Publication Resolution Decision UX v1

**Branch**: `387-review-publication-resolution-decision-ux-v1` | **Date**: 2026-06-18 | **Spec**: `specs/387-review-publication-resolution-decision-ux-v1/spec.md`
**Input**: Feature specification from `/specs/387-review-publication-resolution-decision-ux-v1/spec.md`

## Summary

Harden the existing Spec 386 Review Publication Resolution page so its remaining visible labels, confirmation modals, readonly states, proof disclosure, and state-specific messages consistently read as decision-first publication preparation. Keep all workflow mechanics, persistence, policies, OperationRun behavior, audit behavior, routes, and navigation from Spec 386 unchanged.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12.52.0
**Primary Dependencies**: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1
**Storage**: PostgreSQL via Sail; no schema changes in this spec
**Testing**: Pest 4, Filament/Livewire component tests, focused browser smoke
**Validation Lanes**: confidence + browser; focused fast-feedback feature tests
**Target Platform**: Laravel monolith under `apps/platform`
**Project Type**: web application / Filament admin panel
**Performance Goals**: no new render-time Graph calls; no new remote work; no added polling
**Constraints**: no new workflow engine, no new persistence, no top-level navigation, no global search, no auto-publish
**Scale/Scope**: one existing subject-owned Review Publication Resolution workflow page and related blocked Review Detail CTA

## UI / Surface Guardrail Plan

- **Guardrail scope**: changed surfaces.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**:
  - `App\Filament\Resources\EnvironmentReviewResource\Pages\ResolveReviewPublication`
  - `apps/platform/resources/views/filament/resources/environment-review-resource/pages/resolve-review-publication.blade.php`
  - `ViewEnvironmentReview` / Environment Review blocked CTA state if current copy needs adjustment
  - Customer Review Workspace leakage tests only
- **No-impact class, if applicable**: N/A.
- **Native vs custom classification summary**: mixed existing Filament page + native Filament components + existing Blade composition.
- **Shared-family relevance**: action labels, confirmation modals, proof disclosure, OperationRun links, customer-safe review boundary.
- **State layers in scope**: page, action modal, proof disclosure, existing detail entry point.
- **Audience modes in scope**: operator-MSP, manager, readonly inspector, support-platform; customer/read-only only for negative leakage.
- **Decision/diagnostic/raw hierarchy plan**: decision-first, diagnostics-second, raw/support absent by default.
- **Raw/support gating plan**: technical proof collapsed; raw provider/report/evidence payloads not rendered.
- **One-primary-action / duplicate-truth control**: keep one current-step primary action when executable; demote operation/proof links and navigation.
- **Handling modes by drift class or surface**: report-only for UI audit files unless rendered structure materially changes; review-mandatory for confirmation/action labels and customer non-leakage.
- **Repository-signal treatment**: existing UI-101 report and Spec 386 tests are context; update only when rendered UI changes.
- **Special surface test profiles**: workflow-detail surface, standard-native-filament, browser smoke.
- **Required tests or manual smoke**: Filament/Livewire action tests and browser smoke for first-screen hierarchy, modal copy, collapsed proof, readonly state, mobile, and customer non-leakage.
- **Exception path and spread control**: none approved.
- **Active feature PR close-out entry**: Smoke Coverage / UX Hardening / No New Workflow Mechanics.
- **UI/Productization coverage decision**: coverage artifacts update only if material rendered copy/structure changes; otherwise implementation close-out records no new route/archetype.
- **Coverage artifacts to update**: likely `docs/ui-ux-enterprise-audit/page-reports/ui-101-review-publication-resolution.md`; route inventory/design matrix should need no route/archetype change.
- **No-impact rationale**: N/A.
- **Navigation / Filament provider-panel handling**: no provider registration or panel path change; Laravel 12 panel providers remain in `apps/platform/bootstrap/providers.php`.
- **Screenshot or page-report need**: yes for changed user-facing states; proportional fallback notes are acceptable when a state cannot be produced with current fixtures.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes, but bounded to one workflow page.
- **Systems touched**:
  - `ResolveReviewPublication`
  - `ReviewPublicationResolutionStepAuthorizer`
  - existing OperationRun UX/link helpers
  - existing customer workspace negative leakage checks
- **Shared abstractions reused**:
  - native Filament `Actions\Action`
  - `UiEnforcement`
  - `OperationUxPresenter`
  - `OperationRunLinks`
  - existing scoped URL helpers
- **New abstraction introduced? why?**: none by default. Page-local extraction is allowed only if it replaces duplication and remains review-publication-specific.
- **Why the existing abstraction was sufficient or insufficient**: existing Spec 386 services and page architecture are sufficient; only labels/messages need hardening.
- **Bounded deviation / spread control**: do not introduce a shared decision presenter or generic resolution framework.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: yes for visible link/copy only.
- **Central contract reused**: existing OperationRun UX/link behavior from Spec 386.
- **Delegated UX behaviors**: queued toast, run link, artifact link, browser event, dedupe messaging, safe URL resolution, and terminal notifications remain delegated to existing services/helpers.
- **Surface-owned behavior kept local**: action label, modal copy, no-auto-publish copy, and proof disclosure ordering.
- **Queued DB-notification policy**: unchanged.
- **Terminal notification path**: unchanged.
- **Exception path**: none.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: no new provider/platform seam.
- **Provider-owned seams**: required report generation, evidence generation, review refresh, and review-pack generation remain source-owned by existing Spec 386 services.
- **Platform-core seams**: publication preparation copy, workflow page hierarchy, customer-safe boundary, action naming.
- **Neutral platform terms / contracts preserved**: publication preparation, required reports, evidence, review, export, operation, technical proof.
- **Retained provider-specific semantics and why**: "Permission posture" and "Entra admin roles" remain report labels because they are operator-relevant required reports.
- **Bounded extraction or follow-up path**: follow-up spec only if proof/currentness, inbox intake, or restore adapters need new runtime semantics.

## Constitution Check

- Inventory-first: no inventory or snapshot source-of-truth changes.
- Read/write separation: existing mutating/high-impact step actions keep confirmation, authorization, audit, and tests.
- Graph contract path: no new Graph calls; existing source-owned actions remain authoritative.
- Deterministic capabilities: no capability resolver changes.
- RBAC-UX: existing workspace/environment policies and `ReviewPublicationResolutionStepAuthorizer` remain authoritative; readonly inspection must be explicit and non-executable.
- Workspace isolation: existing scoped review/case resolution remains mandatory.
- Tenant isolation: no cross-tenant data path is added.
- Run observability: no new OperationRun types or transitions; existing links and start UX reused.
- OperationRun start UX: no local queued toast/link/event composition beyond existing helpers.
- Ops-UX lifecycle: no direct `OperationRun.status` or `OperationRun.outcome` changes.
- Data minimization: no raw provider payloads, raw report contents, evidence JSON, secrets, or exception messages in default UI.
- Test governance: focused Feature/Filament/Browser proof; no hidden heavy-governance expansion.
- Proportionality: no new persistence, status family, generic presenter, or framework by default.
- No premature abstraction: page-local mapping preferred over a new presenter.
- Persisted truth: none added.
- Behavioral state: no new state/status values.
- UI semantics: direct mapping from existing step keys/statuses to operator copy; no new taxonomy.
- Shared pattern first: existing Filament and OperationRun helpers reused.
- Provider boundary: no provider-specific semantics spread into platform-core truth.
- V1 explicitness / few layers: direct local implementation.
- Badge semantics: existing Filament badges/shared badge semantics only; no ad-hoc status color language.
- Filament-native UI: native Filament components and existing Blade composition retained; no new independent button/card/status system.
- UI/Productization coverage: UI-101 coverage reused/updated proportionally.
- Filament v5 / Livewire v4: implementation must remain Livewire 4.1.4 compatible and avoid Livewire v3 APIs.
- Panel provider registration: no panel provider changes; Laravel 12 providers remain in `apps/platform/bootstrap/providers.php`.
- Global search: no Resource is added; no global-search surface is introduced.
- Destructive/high-impact actions: step execution and cancel remain `->action(...)` actions with `->requiresConfirmation()`, authorization, audit, and tests.
- Asset strategy: no registered Filament assets expected; no `filament:assets` deploy change unless implementation unexpectedly registers assets and updates this plan first.

## Test Governance Check

- **Test purpose / classification by changed surface**: Feature for copy/RBAC/leakage, Filament/Livewire for page actions/modals, Browser for visual hierarchy/disclosure/mobile.
- **Affected validation lanes**: confidence + browser; focused fast-feedback for feature tests.
- **Why this lane mix is the narrowest sufficient proof**: this is visible Filament UI behavior over existing services, not schema/provider/runtime behavior.
- **Narrowest proving command(s)**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/EnvironmentReview/Spec387ReviewPublicationResolutionDecisionUxTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/EnvironmentReview/Spec386ReviewPublicationResolutionWorkflowTest.php`
  - `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec387ReviewPublicationResolutionDecisionUxTest.php`
  - `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
  - `git diff --check`
- **Fixture / helper / factory / seed / context cost risks**: reuse Spec 386 fixtures/helpers; avoid new global defaults.
- **Expensive defaults or shared helper growth introduced?**: no.
- **Heavy-family additions, promotions, or visibility changes**: one explicit browser family/file if not extending existing Spec 386 browser smoke.
- **Surface-class relief / special coverage rule**: workflow-detail surface requires browser smoke; otherwise standard-native-filament relief applies.
- **Closing validation and reviewer handoff**: verify no new app mechanics, no new route/resource/global search, confirmation copy, readonly non-execution, no customer leakage, and screenshot/index evidence.
- **Budget / baseline / trend follow-up**: none unless browser runtime grows materially.
- **Review-stop questions**: did scope stay copy/UI-only; did disabled/denied states stay server-enforced; did proof stay secondary; did no-publish remain explicit.
- **Escalation path**: document-in-feature if some browser states cannot be captured; follow-up-spec for proof/currentness or new adapter mechanics.
- **Active feature PR close-out entry**: Smoke Coverage / UX Hardening / No New Workflow Mechanics.
- **Why no dedicated follow-up spec is needed**: this is the dedicated residual UX hardening slice; broader proof/currentness/inbox/restore concerns are separate candidates.

## Project Structure

### Documentation (this feature)

```text
specs/387-review-publication-resolution-decision-ux-v1/
+-- checklists/
|   +-- requirements.md
+-- plan.md
+-- spec.md
+-- tasks.md
```

### Source Code (repository root)

```text
apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/
+-- ResolveReviewPublication.php

apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/
+-- ViewEnvironmentReview.php

apps/platform/resources/views/filament/resources/environment-review-resource/pages/
+-- resolve-review-publication.blade.php

apps/platform/tests/Feature/EnvironmentReview/
+-- Spec386ReviewPublicationResolutionWorkflowTest.php
+-- Spec387ReviewPublicationResolutionDecisionUxTest.php

apps/platform/tests/Browser/
+-- Spec387ReviewPublicationResolutionDecisionUxTest.php

docs/ui-ux-enterprise-audit/page-reports/
+-- ui-101-review-publication-resolution.md
```

**Structure Decision**: Use existing Laravel/Filament app structure and existing Spec 386 test families. Do not create new base folders or runtime packages.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| N/A | No constitution violation is approved. | N/A |

## Proportionality Review

- **Current operator problem**: remaining implementation-first labels and generic confirmation affordances weaken a recently introduced decision workflow.
- **Existing structure is insufficient because**: the existing structure is good but needs copy/state hardening; no new structure is required by default.
- **Narrowest correct implementation**: update current page mappings, localization-backed Blade/page copy, action modal labels, tests, screenshots, and UI coverage notes.
- **Ownership cost created**: focused tests and screenshots only.
- **Alternative intentionally rejected**: a new generic presenter/framework or new workflow mechanics.
- **Release truth**: current-release UX hardening.

## Implementation Phases

1. Confirm repo truth and current visible strings against Spec 386 implementation.
2. Add focused tests for residual copy, modal, readonly, disclosure, and leakage behavior.
3. Adjust existing page/action/view copy through existing localization-backed local mappings only.
4. Capture browser screenshots and update UI-101 coverage notes if material.
5. Run focused validation and record no implementation scope expansion.