TenantAtlas/specs/351-review-output-resolve-actions-v1/artifacts/review-output-resolve-actions-browser-flow-audit.md

# Spec 351 Browser Flow Audit — Review Output Resolve Actions

## Executive Summary
- Overall readiness: not ready
- Main flow result: `Create next review` is browser-verifiziert and scope-safe on `environment_id=38`, but the operator loop does not close cleanly because the workspace loses the released-review entry once a draft exists.
- Top issues:
  - P1: Workspace does not surface `Open draft review` or any successor action once a draft exists; both `environment_id=39` and the post-create state for `environment_id=38` fall back to an empty released-review state.
  - P1: `Publish review` is visible on draft review `14` while the same page still says `Publication blocked` / `Output not customer-ready` and points to `Refresh review` as the next step.
  - P2: `Refresh review` confirms cleanly but gives no browser-verifizierte success toast or obvious state delta, so the operator cannot tell whether anything changed.
- Recommendation: fix before close

## Repo State
- Branch: `351-review-output-resolve-actions-v1`
- Dirty tracked files: 26
- Untracked files: 7
- Spec 351 active/uncommitted: yes
- App code already changed: yes
- Browser flow ran against the current uncommitted working tree: yes
- Relevant Spec 351 files in the dirty tree:
  - `apps/platform/app/Support/ResolutionGuidance/ResolutionAction.php`
  - `apps/platform/app/Support/ResolutionGuidance/ResolutionCase.php`
  - `apps/platform/app/Support/ResolutionGuidance/Adapters/ReviewPackOutputResolutionAdapter.php`
  - `apps/platform/app/Support/ResolutionGuidance/ReviewOutputResolveActionMapper.php`
  - `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`
  - `apps/platform/app/Filament/Resources/EnvironmentReviewResource.php`
  - `apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/ViewEnvironmentReview.php`
  - `apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php`
  - `apps/platform/resources/views/components/resolution-guidance-card.blade.php`
  - `apps/platform/tests/Unit/ResolutionGuidance/Spec351ReviewOutputResolveActionMapperTest.php`
  - `apps/platform/tests/Feature/Filament/Spec351CustomerReviewWorkspaceResolveActionTest.php`
  - `apps/platform/tests/Feature/EnvironmentReview/Spec351EnvironmentReviewResolveActionTest.php`
  - `apps/platform/tests/Browser/Spec351ReviewOutputResolveActionsSmokeTest.php`
- Tests executed during this audit: no

## Repo-Verified Action Inventory

### Repo-backed resolve actions
- `create_next_review`
  - type: mutating / operation-backed
  - browser surface: Customer Review Workspace and Environment Review detail
  - confirmation: yes
  - capability: `Capabilities::ENVIRONMENT_REVIEW_MANAGE`
  - audit / operation backing: `AuditActionId::EnvironmentReviewSuccessorCreated`, `OperationRunType::EnvironmentReviewCompose`
- `refresh_review`
  - type: mutating / operation-backed
  - browser surface: Environment Review detail only
  - confirmation: yes
  - capability: `Capabilities::ENVIRONMENT_REVIEW_MANAGE`
  - audit / operation backing: `AuditActionId::EnvironmentReviewRefreshed`, `OperationRunType::EnvironmentReviewCompose`
- `publish_review`
  - type: mutating / domain action
  - browser surface: Environment Review detail only
  - confirmation: yes
  - capability: `Capabilities::ENVIRONMENT_REVIEW_MANAGE`
  - audit backing: `AuditActionId::EnvironmentReviewPublished`
- `open_successor_review`
  - type: navigation
  - browser surface: detail action when `superseded_by_review_id` resolves to a same-scope review
  - confirmation: no

### Fallback / navigation actions
- `resolve_review_blockers`
- `open_evidence_basis`
- `open_operation_proof`
- `open_review`
- download actions such as `download_review_pack_with_limitations`

### Actions intentionally not offered as executable in workspace
- `refresh_review`
- `publish_review`
- generic “fix automatically”
- generic “make customer-ready”

## Browser Environment
- Base URL: `http://localhost`
- User: authenticated workspace manager; resulting compose operations were initiated by `Ahmed Darrazi` (repo-verifiziert after mutation)
- Workspace: `wp` / workspace `3`
- Environments used:
  - `38` — `Spec342 Demo Evidence Incomplete`
  - `39` — `Spec342 Demo Ready`
- Reviews used:
  - `3` — published review for environment `38`, later superseded by `14`
  - `14` — draft created during this audit for environment `38`
  - `4` — superseded released review for environment `39`
  - `13` — existing draft for environment `39`
- Review / pack state:
  - environment `38` pre-action: published blocked output, review pack `4`, operation `24`
  - environment `38` post-create: draft `14`, operation `47`, previous review `3` now `superseded_by_review_id=14`
  - environment `39`: released review `4` already superseded by draft `13`

## Flow Walkthrough

### Step 0 — Existing-draft workspace state (`environment_id=39`)
- Step: reload current `Customer Review Workspace`
- URL: `http://localhost/admin/reviews/workspace?environment_id=39`
- Visible title: `Customer Review Workspace - TenantPilot`
- Primary guidance state: not present
- Primary action: not present
- Secondary actions: not present
- Clicked action: none
- Expected result: if an existing draft is the next repo-backed step, the workspace should guide to it
- Actual result:
  - browser-verifiziert: workspace shows `No released customer reviews match the active environment filter.`
  - repo-verifiziert: environment `39` has superseded review `4` plus draft `13`
  - nicht vorhanden: `Open draft review`
- Scope preserved? yes
- Console errors? no
- Network/server errors? no visible server error page
- Toast/notification: none
- State changed? no
- Operator clarity: low; the workspace gives no next step for an environment that already has a draft successor
- Issue: successor/draft flow is unreachable from the workspace once the released review is superseded
- Severity: P1
- Screenshot: `00-workspace-env39-no-released-review.png`

### Step 1 — Published blocked workspace (`environment_id=38`)
- Step: open blocked released-review workspace state
- URL: `http://localhost/admin/reviews/workspace?environment_id=38`
- Visible title: `Customer Review Workspace - TenantPilot`
- Primary guidance state: `Output not customer-ready` / `Requires review`
- Primary action: `Create next review`
- Secondary actions:
  - `Inspect review blockers`
  - `Download review pack with limitations`
  - `Open evidence basis`
  - `Open operation proof`
- Clicked action: none
- Expected result: one dominant real next step with secondary supporting actions
- Actual result:
  - browser-verifiziert: one dominant `Create next review` CTA
  - browser-verifiziert: supporting actions are visually subordinate
  - browser-verifiziert: acknowledgement copy distinguishes consumption from customer-ready status
- Scope preserved? yes
- Console errors? no
- Network/server errors? no visible server error page
- Toast/notification: none
- State changed? no
- Operator clarity: high on first screen
- Issue: none at this step
- Severity: none
- Screenshot: `01-customer-review-workspace-output-not-ready.png`

### Step 2 — Create next review confirmation
- Step: click `Create next review`
- URL: `http://localhost/admin/reviews/workspace?environment_id=38`
- Visible title: `Customer Review Workspace - TenantPilot`
- Primary guidance state: unchanged beneath modal
- Primary action: `Create next review`
- Secondary actions: unchanged beneath modal
- Clicked action: `Create next review`
- Expected result: confirmation before mutation
- Actual result:
  - browser-verifiziert: confirmation modal appears with `Create next review?`
- Scope preserved? yes
- Console errors? no
- Network/server errors? no visible server error page
- Toast/notification: modal only
- State changed? not yet
- Operator clarity: high
- Issue: none
- Severity: none
- Screenshot: `02-create-next-review-primary-action.png`

### Step 3 — Result after create-next-review confirmation
- Step: confirm `Create next review`
- URL: `http://localhost/admin/workspaces/3/environments/spec342-demo-evidence-incomplete/environment-reviews/14?source_surface=customer_review_workspace&tenant_filter_id=38`
- Visible title: `View Review - TenantPilot`
- Primary guidance state: draft review detail, initially `Internal only`, then `Publication blocked` / `Output not customer-ready` after refresh interactions
- Primary action: `Refresh review`
- Secondary actions:
  - `Inspect review blockers`
  - `Open evidence basis`
  - `Open operation proof`
- Clicked action: confirmed `Create next review`
- Expected result: new draft is created and opened in the correct environment scope
- Actual result:
  - browser-verifiziert: detail page for review `14` opens
  - repo-verifiziert: review `14` exists as draft and review `3` is now superseded by `14`
  - browser-verifiziert: `tenant_filter_id=38` and environment scope are preserved in the URL
- Scope preserved? yes
- Console errors? no
- Network/server errors? no visible server error page
- Toast/notification: none clearly visible at landing time
- State changed? yes
- Operator clarity: medium; the draft opens correctly, but the route is a normal detail route rather than a suppressed customer-workspace detail route
- Issue: no direct break, but the operator has already left the calm workspace surface
- Severity: P2
- Screenshot: `03-after-create-next-review-draft.png`

### Step 4 — Draft review guidance
- Step: inspect the newly opened draft detail
- URL: `http://localhost/admin/workspaces/3/environments/spec342-demo-evidence-incomplete/environment-reviews/14?source_surface=customer_review_workspace&tenant_filter_id=38`
- Visible title: `View Review - TenantPilot`
- Primary guidance state: `Output not customer-ready` / `Publication blocked`
- Primary action: `Refresh review`
- Secondary actions:
  - `Inspect review blockers`
  - `Open evidence basis`
  - `Open operation proof`
- Clicked action: none
- Expected result: next action should align with missing inputs / stale evidence
- Actual result:
  - browser-verifiziert: detail guidance points to `Refresh review`
  - browser-verifiziert: boundary copy remains non-customer-safe
  - browser-verifiziert + repo-verifiziert: `Publish review` is still visible in the header on this not-ready draft
- Scope preserved? yes
- Console errors? no
- Network/server errors? no visible server error page
- Toast/notification: none
- State changed? no
- Operator clarity: medium; the guidance is clear, but the visible `Publish review` header CTA competes with it
- Issue: readiness and publish availability are contradictory on the same screen
- Severity: P1
- Screenshot: `04-draft-review-guidance.png`

### Step 5 — Refresh review inputs
- Step: open and confirm `Refresh review`
- URL: `http://localhost/admin/workspaces/3/environments/spec342-demo-evidence-incomplete/environment-reviews/14?source_surface=customer_review_workspace&tenant_filter_id=38`
- Visible title: `View Review - TenantPilot`
- Primary guidance state: remains blocked / refresh-oriented
- Primary action: `Refresh review`
- Secondary actions: unchanged
- Clicked action: `Refresh review`
- Expected result: obvious success feedback or visible state transition
- Actual result:
  - browser-verifiziert: confirmation opens
  - browser-verifiziert: confirm completes without console errors
  - browser-verifiziert: no obvious success toast, no clear state delta, no new operator-facing completion cue
  - plausibel: refresh may have run, but the UI does not make that outcome legible
- Scope preserved? yes
- Console errors? no
- Network/server errors? no visible server error page
- Toast/notification: none browser-verifiziert
- State changed? not obvious
- Operator clarity: low after confirmation
- Issue: refresh feedback is too weak for an action that is supposed to move the draft forward
- Severity: P2
- Screenshot: `05-refresh-review-inputs-if-available.png`, `06-after-refresh-result.png`

### Step 6 — Evidence basis target
- Step: click `View evidence snapshot`
- URL: `http://localhost/admin/workspaces/3/environments/spec342-demo-evidence-incomplete/evidence/5`
- Visible title: `View Evidence Snapshot - TenantPilot`
- Primary guidance state: evidence page
- Primary action: none in scope for this audit
- Secondary actions: page-local
- Clicked action: `View evidence snapshot`
- Expected result: correct environment-scoped evidence detail
- Actual result:
  - browser-verifiziert: correct evidence detail opens
  - browser-verifiziert: environment scope remains `Spec342 Demo Evidence Incomplete`
- Scope preserved? yes
- Console errors? no
- Network/server errors? no visible server error page
- Toast/notification: none
- State changed? navigated
- Operator clarity: good
- Issue: none
- Severity: none
- Screenshot: `08-evidence-basis-target.png`

### Step 7 — Operation proof target
- Step: click visible `Open operation` for the current draft
- URL: `http://localhost/admin/workspaces/3/operations/47`
- Visible title: `Operation #47 - TenantPilot`
- Primary guidance state: operation detail
- Primary action: none in scope for this audit
- Secondary actions: page-local
- Clicked action: `Open operation`
- Expected result: operation proof opens for the current review/compose context
- Actual result:
  - browser-verifiziert: operation page opens
  - browser-verifiziert: operation shows compose context and succeeded outcome
- Scope preserved? yes
- Console errors? no
- Network/server errors? no visible server error page
- Toast/notification: none
- State changed? navigated
- Operator clarity: good
- Issue: none
- Severity: none
- Screenshot: `09-operation-proof-target.png`

### Step 8 — Customer-workspace detail context
- Step: open released review `3` directly in customer-workspace detail mode
- URL: `http://localhost/admin/workspaces/3/environments/spec342-demo-evidence-incomplete/environment-reviews/3?customer_workspace=1&source_surface=customer_review_workspace&tenant_filter_id=38`
- Visible title: `View Review - TenantPilot`
- Primary guidance state: released review detail with customer-workspace context note
- Primary action: suppressed
- Secondary actions: suppressed in the guidance card
- Clicked action: direct route open
- Expected result: no duplicate CTA rail and clear context note
- Actual result:
  - browser-verifiziert: context note `You are already on the review detail for this output.`
  - browser-verifiziert: no visible `Create next review`, `Publish review`, or `Refresh review` buttons in the guidance surface
  - browser-verifiziert: review status, output readiness, publication/sharing state, and limitations remain visible
- Scope preserved? yes
- Console errors? no
- Network/server errors? no visible server error page
- Toast/notification: none
- State changed? navigated
- Operator clarity: good
- Issue: none
- Severity: none
- Screenshot: `10-review-detail-customer-workspace-context.png`

### Step 9 — Final workspace state after create-next-review
- Step: return to `Customer Review Workspace` filtered to environment `38`
- URL: `http://localhost/admin/reviews/workspace?environment_id=38`
- Visible title: `Customer Review Workspace - TenantPilot`
- Primary guidance state: not present
- Primary action: not present
- Secondary actions: not present
- Clicked action: direct workspace return
- Expected result: show current draft / successor review as the next repo-backed step
- Actual result:
  - browser-verifiziert: workspace now shows `No released customer reviews match the active environment filter.`
  - repo-verifiziert: environment `38` has draft `14` and released review `3` is superseded by it
  - nicht vorhanden: `Open draft review`
- Scope preserved? yes
- Console errors? no
- Network/server errors? no visible server error page
- Toast/notification: none
- State changed? yes, but the state is not actionable from the workspace
- Operator clarity: low
- Issue: the main operator loop breaks after the successful creation of a next review
- Severity: P1
- Screenshot: `11-final-customer-review-workspace-state.png`

## Screenshot Index

| Step | Screenshot | Notes |
| --- | --- | --- |
| Extra | `00-workspace-env39-no-released-review.png` | Existing-draft environment filtered to an empty released-review state |
| 1 | `01-customer-review-workspace-output-not-ready.png` | Good first-screen blocked-output hierarchy |
| 2 | `02-create-next-review-primary-action.png` | Confirmation modal present |
| 3 | `03-after-create-next-review-draft.png` | Draft detail opened after mutation |
| 4 | `04-draft-review-guidance.png` | Draft detail shows refresh-first guidance |
| 5 | `05-refresh-review-inputs-if-available.png` | Refresh confirmation |
| 5 result | `06-after-refresh-result.png` | No clear operator-facing success cue |
| 4 / 6 | `07-publish-review-if-available.png` | `Publish review` visible on not-ready draft |
| 6 | `08-evidence-basis-target.png` | Evidence target correct |
| 7 | `09-operation-proof-target.png` | Operation target correct |
| 8 | `10-review-detail-customer-workspace-context.png` | CTA suppression works in explicit customer-workspace mode |
| 9 | `11-final-customer-review-workspace-state.png` | Final workspace loses actionable successor/draft state |

## Findings

### P0 Blockers
- none confirmed

### P1 High
- Workspace successor flow is broken once a draft exists.
  - browser-verifiziert: `environment_id=39` and post-create `environment_id=38` both end in `No released customer reviews match the active environment filter.`
  - repo-verifiziert: both environments have a draft successor (`13` for env `39`, `14` for env `38`).
  - impact: the operator cannot return to the workspace and continue with `Open draft review` or equivalent successor guidance.
- `Publish review` is visible on non-ready draft review `14`.
  - browser-verifiziert: draft detail shows `Publication blocked` / `Output not customer-ready` and still surfaces a visible `Publish review` header CTA.
  - repo-verifiziert: `publish_review` is only hidden when the review is not mutable; it is not readiness-gated in the page action.
  - impact: the UI offers a competing high-impact mutation while the guidance says the draft is not yet publishable.

### P2 Medium
- Refresh confirmation lacks clear operator feedback.
  - browser-verifiziert: confirming `Refresh review` produced no visible success toast or obvious page-state transition.
  - impact: the operator cannot tell whether the action succeeded, retried, or no-op’d.
- Create-next-review leaves the calm workspace surface immediately and opens a normal detail surface.
  - browser-verifiziert: redirect URL is a normal review detail route with `source_surface` and `tenant_filter_id`, not `customer_workspace=1`.
  - impact: the flow is technically correct, but it weakens the “resolve from workspace” productization story and makes the return path more dependent on detail behavior.

### P3 Polish
- None worth separating from the medium issues in this slice.

## Productization Assessment
- Guidance quality: good on the first blocked workspace surface; mixed once the flow moves into mutable review detail.
- Next-action clarity: good before mutation, weak after mutation because successor/draft state disappears from the workspace and `Publish review` competes with `Refresh review`.
- Scope correctness: good; workspace `3`, environment scope, `tenant_filter_id=38`, evidence target, and operation target all stayed in the right tenant/environment.
- Customer-safe boundary: good on the workspace and customer-workspace detail surfaces; no false customer-ready claim was shown while blocked.
- UI density: improved on the workspace; draft detail is denser and mixes blocked guidance with broad lifecycle controls.
- Resolve vs Diagnose: partially successful; the flow resolves into a real draft, but the loop back to the workspace does not remain actionable.

## Recommended Fix Scope

### Must be fixed before closing Spec 351
- Restore a workspace-visible successor/draft action once a released review is superseded.
- Align `Publish review` visibility with actual readiness, or clearly demote/gate it when the draft is blocked.

### Can be deferred
- Stronger success feedback for `Refresh review` if the refresh semantics are otherwise correct.

### Should not be changed
- Keep the single dominant primary CTA and subordinate supporting actions on the blocked workspace surface.
- Keep the customer-workspace detail CTA suppression behavior.
- Keep the evidence-basis and operation-proof targets as repo-backed supporting actions.

## Final Recommendation
- Close Spec 351? no
- Continue polish? no, fix the P1 workflow issues first
- Next suggested spec? none until the Spec 351 operator loop is closed end-to-end