TenantAtlas/specs/351-review-output-resolve-actions-v1/spec.md

# Feature Specification: Spec 351 - Review Output Resolve Actions v1

**Feature Branch**: `351-review-output-resolve-actions-v1`  
**Created**: 2026-06-03  
**Status**: Draft  
**Type**: Platform productization / operator workflow / review-output resolution actions  
**Depends on**: Specs 347, 349, 350  
**Runtime posture**: Bounded action enablement. Reuse existing review, evidence, and pack actions only. No new workflow engine, fake remediation, customer portal, or provider/dashboard expansion.  
**Input**: Direct user-provided Spec 351 draft plus repo truth from current review-output guidance and existing environment-review lifecycle actions.

## Spec Candidate Check *(mandatory — SPEC-GATE-001)*

- **Problem**: TenantPilot can now explain why a review output is blocked or limited, but it still often stops at diagnosis instead of telling the operator what real next step the repo already supports.
- **Today's failure**: Operators land on "Inspect review blockers" or similar disclosure-first guidance, then still have to infer whether they should create the next review, refresh the draft, publish, open evidence, or only review limitations.
- **User-visible improvement**: Customer Review Workspace and Environment Review detail show one real next step first when a safe repo-backed action exists, keep every other action visibly secondary, separate package existence from internal export and customer sharing, and keep unsupported states honest through disclosure/navigation fallbacks.
- **Smallest enterprise-capable version**: Review-output-only action mapping across `CustomerReviewWorkspace` and Environment Review detail, reusing existing review/evidence actions and current scoped routes.
- **Explicit non-goals**: No workflow engine, no new persistence, no provider-readiness rollout, no governance-inbox rollout, no dashboard rollout, no customer portal, no PDF/HTML renderer, no AI suggestion system.
- **Permanent complexity imported**: One deterministic mapper, one review-output action-capability map, focused Unit/Feature/Browser tests, and possibly a small derived extension to the existing `ResolutionAction` contract for source-owned action execution metadata.
- **Why now**: Spec 350 already established the shared review-output-first contract. The next gap is productization: operators still lack a clear "do this now" step on the same surfaces.
- **Why not local**: The gap spans two existing consumers of the same review-output truth, and the current adapter/view flow can only express URL-based actions. A local copy change would not safely bridge to real review lifecycle actions.
- **Approval class**: Workflow Compression.
- **Red flags triggered**: New meta-infrastructure is limited to one mapper over an existing contract; the main defense is that it reuses already-real actions and stays review-output-only.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12**
- **Decision**: approve with repo-truth-first and no-fake-action constraints.

## Candidate Source And Completed-Spec Guardrail

- **Candidate source**:
  - direct user-provided Spec 351 draft
  - roadmap relationship: customer review completion and review-output-first operator workflow productization
- **Why selected now**:
  - the user explicitly requested a non-framework follow-up after Spec 350
  - the repo already has real review lifecycle actions (`refresh_review`, `publish_review`, `create_next_review`) that are not yet first-class resolve actions on the main review-output guidance surfaces
- **Close alternatives deferred**:
  - provider-readiness and required-permissions productization
  - governance-inbox reuse of the same contract
  - environment/dashboard reuse of the same contract
  - portal, PDF/HTML, PSA, and AI follow-up lanes
- **Completed-spec guardrail result**:
  - `specs/347-review-pack-output-contract-readiness-semantics`, `specs/349-customer-review-workspace-output-resolution-guidance`, and `specs/350-operator-resolution-guidance-framework-v1` already contain checked preparation/implementation evidence and are context only
  - they must not be normalized, reopened, or rewritten during this preparation step
- **Direct repo-truth corrections to the user draft**:
  - the repo already exposes `Create next review`, `Refresh review`, and `Publish review` as real actions on `ViewEnvironmentReview`
  - the repo does **not** currently expose a generic workspace-level "Open existing draft review" resolver; successor/draft navigation is only available when a concrete review target is known
  - current review-output guidance cards render URL buttons only, so executable resolve actions require an explicit reuse of Filament page/record actions instead of a pure copy change

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace review-consumption surface plus environment-review detail.
- **Primary Routes**:
  - `/admin/reviews/workspace`
  - existing environment-scoped Environment Review detail route(s)
  - existing Evidence Snapshot detail and OperationRun detail routes only as linked follow-up or fallback destinations
- **Data Ownership**:
  - `EnvironmentReview`, `ReviewPack`, `EvidenceSnapshot`, and `OperationRun` remain authoritative
  - `ResolutionCase`, `ResolutionAction`, and the new mapper stay derived-only and request-scoped
- **RBAC**:
  - workspace membership plus entitled environment access remain required for visibility
  - mutating review actions require `Capabilities::ENVIRONMENT_REVIEW_MANAGE`
  - evidence refresh remains `Capabilities::EVIDENCE_MANAGE` on evidence-owned surfaces
  - non-member or non-entitled access stays 404; member-but-missing-capability stays 403

## UI Surface Impact *(mandatory — UI-COV-001)*

Does this spec add, remove, rename, or materially change any reachable UI surface?

- [ ] No UI surface impact
- [x] Existing page changed
- [ ] New page/route added
- [ ] Navigation changed
- [ ] Filament panel/provider surface changed
- [x] New modal/drawer/wizard/action added
- [x] New table/form/state added
- [x] Customer-facing surface changed
- [x] Dangerous action changed
- [x] Status/evidence/review presentation changed
- [x] Workspace/environment context presentation changed

## UI/Productization Coverage *(mandatory when UI Surface Impact is not "No UI surface impact"; otherwise write `N/A - no reachable UI surface impact` plus rationale)*

- **Route/page/surface**:
  - `App\Filament\Pages\Reviews\CustomerReviewWorkspace`
  - `App\Filament\Resources\EnvironmentReviewResource`
  - `App\Filament\Resources\EnvironmentReviewResource\Pages\ViewEnvironmentReview`
  - existing review-output guidance card and decision card CTA zones
- **Current or new page archetype**: existing strategic workspace review surface (`UI-006`) plus existing environment review detail (`UI-040`)
- **Design depth**: Strategic Surface for the workspace, Domain Pattern Surface for review detail
- **Repo-truth level**: repo-verified
- **Existing pattern reused**:
  - `docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md`
  - `docs/ui-ux-enterprise-audit/page-reports/ui-040-environment-review-detail.md`
  - current Filament page-action mounting pattern already used on `CustomerReviewWorkspace`
- **New pattern required**: one bounded review-output resolve-action mapper and one bounded reuse path from guidance cards into existing source-owned Filament actions
- **Screenshot required**: yes, under `specs/351-review-output-resolve-actions-v1/artifacts/screenshots/`
- **Page audit required**: yes, update `ui-006` and `ui-040`
- **Customer-safe review required**: yes, because the workspace is an operator-facing customer-safe handoff surface
- **Dangerous-action review required**: yes; `create_next_review`, `refresh_review`, and `publish_review` become more prominent when used as recommended resolve actions
- **Coverage files updated or explicitly not needed**:
  - [ ] `docs/ui-ux-enterprise-audit/route-inventory.md`
  - [ ] `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`
  - [x] `docs/ui-ux-enterprise-audit/page-reports/...`
  - [ ] `docs/ui-ux-enterprise-audit/strategic-surfaces.md`
  - [ ] `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md`
  - [ ] `docs/ui-ux-enterprise-audit/unresolved-pages.md`
  - [ ] `N/A - no reachable UI surface impact`
- **No-impact rationale when applicable**: N/A

## Cross-Cutting / Shared Pattern Reuse *(mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write `N/A - no shared interaction family touched`)*

- **Cross-cutting feature?**: yes
- **Interaction class(es)**: next-action guidance, lifecycle actions, status messaging, evidence/report viewers, proof links
- **Systems touched**:
  - `App\Support\ReviewPacks\ReviewPackOutputResolutionGuidance`
  - `App\Support\ResolutionGuidance\ResolutionAction`
  - `App\Support\ResolutionGuidance\ResolutionCase`
  - `App\Support\ResolutionGuidance\Adapters\ReviewPackOutputResolutionAdapter`
  - `App\Filament\Pages\Reviews\CustomerReviewWorkspace`
  - `App\Filament\Resources\EnvironmentReviewResource`
  - `App\Filament\Resources\EnvironmentReviewResource\Pages\ViewEnvironmentReview`
  - `App\Support\Ui\GovernanceActions\GovernanceActionCatalog`
- **Existing pattern(s) to extend**: current review-output guidance plus current source-owned Filament lifecycle actions
- **Shared contract / presenter / builder / renderer to reuse**:
  - `ResolutionAction` / `ResolutionCase`
  - `ReviewPackOutputResolutionAdapter`
  - existing Filament page actions on `CustomerReviewWorkspace`
  - existing Filament record actions on `ViewEnvironmentReview`
  - `UiEnforcement`, `GovernanceActionCatalog`, and scoped route helpers
- **Why the existing shared path is sufficient or insufficient**: the contract already standardizes title/reason/impact/action shape, but it does not yet choose real resolve actions deterministically or bridge those actions into executable workspace/detail UI without falling back to URL-only guidance.
- **Allowed deviation and why**: one mapper plus a small derived execution-metadata extension on `ResolutionAction` is allowed if it is the narrowest way to reuse source-owned actions without creating a parallel workflow/action framework.
- **Consistency impact**: the same review-output blocker must produce the same dominant next action vocabulary across workspace and detail, while follow-up overrides and capability limits remain explicit.
- **Review focus**: prevent direct service calls from Blade, prevent fake enabled buttons, prevent duplicate primary CTAs, and prevent the contract from broadening into a general remediation engine.

## OperationRun UX Impact *(mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an `OperationRun`; otherwise write `N/A - no OperationRun start or link semantics touched`)*

- **Touches OperationRun start/completion/link UX?**: yes, indirectly
- **Shared OperationRun UX contract/layer reused**:
  - `EnvironmentReviewService::refresh()`
  - `EnvironmentReviewLifecycleService::createNextReview()`
  - existing `OperationRunLinks`
- **Delegated start/completion UX behaviors**: review refresh and next-review creation must keep their current service-owned queue/run behavior; the resolve-action layer only selects or mounts those actions
- **Local surface-owned behavior that remains**: action ranking, explanation text, and capability-aware fallback selection
- **Queued DB-notification policy**: unchanged
- **Terminal notification path**: unchanged
- **Exception required?**: none; resolve-action guidance must not start jobs directly

## Provider Boundary / Platform Core Check *(mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write `N/A - no shared provider/platform boundary touched`)*

N/A - no shared provider/platform boundary touched beyond already-neutral review, evidence, operation, and output terminology.

## UI / Surface Guardrail Impact *(mandatory when operator-facing surfaces are changed; otherwise write `N/A`)*

| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Customer Review Workspace decision card resolve action | yes | Native Filament page + existing Blade composition | review-output guidance + lifecycle actions | page, URL-query, derived action state | yes | executable CTA reuse must stay source-owned |
| Environment Review detail output-guidance semantics | yes | Native Filament resource + infolist Blade | review-output guidance + lifecycle actions | detail, URL-query, derived action state | no | do not duplicate header and card CTA rails |

## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)*

| Surface | Decision Role | Human-in-the-loop Moment | Immediately Visible for First Decision | On-Demand Detail / Evidence | Why This Is Primary or Why Not | Workflow Alignment | Attention-load Reduction |
|---|---|---|---|---|---|---|---|
| Customer Review Workspace | Primary Decision Surface | Decide what real next step gets the current output closer to customer-safe or publishable | issue, reason, impact, one dominant next action | evidence basis, technical details, operation proof, limitations list | primary because it is the first workspace-wide handoff surface | review handoff and follow-up workflow | removes "inspect blockers then infer the action" |
| Environment Review detail | Secondary Context | Understand or execute the review lifecycle step for the current review | aligned next-step label and context note | sections, artifact truth, evidence, header actions, proof links | secondary because it deepens the chosen review rather than ranking workspace work | detail follow-through | avoids competing status and CTA dialects |

## Audience-Aware Disclosure *(mandatory when operator-facing surfaces are changed)*

| Surface | Audience Modes In Scope | Decision-First Default-Visible Content | Operator Diagnostics | Support / Raw Evidence | One Dominant Next Action | Hidden / Gated By Default | Duplicate-Truth Prevention |
|---|---|---|---|---|---|---|---|
| Customer Review Workspace | operator-MSP, manager, readonly reviewer | output state, reason, impact, one action | evidence basis, limitations, technical detail | raw/support detail remains elsewhere | yes | mutating actions hidden, disabled, or downgraded when capability/surface is not safe | findings/accepted-risk overrides remain the only higher-priority exception |
| Environment Review detail | operator-MSP, support, customer-workspace detail context | review/output/publication state and aligned next step | lifecycle detail, sections, evidence, pack truth | support/raw detail stays in existing deeper surfaces | yes | customer-workspace detail mode suppresses duplicate CTA rails | normal detail keeps one dominant lifecycle action, not two |

## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*

| Surface | Action Surface Class | Surface Type | Likely Next Operator Action | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type / Justification |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Customer Review Workspace | Utility / Workspace Decision | Customer-safe workspace hub | create next review, refresh review, publish review, or open evidence depending on state | explicit CTA in decision card | N/A | grouped supporting links in the same card | none directly in-card unless source-owned action reuse stays bounded | `/admin/reviews/workspace` | existing environment review detail | workspace + visible environment filter | Review output | dominant blocker plus next step | action execution bridge only, no new route |
| Environment Review detail | Detail / Artifact + Review Context | Existing review detail | inspect current review or execute the dominant lifecycle action | existing detail page | current repo-real behavior only | header `More`, evidence/proof links, limitations | existing archive/danger group remains separate | existing review register route | existing environment review detail route | workspace/environment + customer_workspace query | Environment review | review/output/publication dimensions and next step | preserve single dominant lifecycle action |

## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*

| Surface | Primary Persona | Decision / Operator Action Supported | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|---|
| Customer Review Workspace resolve-action card | MSP operator / manager | Decide what real next step to take for the latest released review output | workspace review handoff | What do I do now to move this output forward safely? | issue, reason, impact, one dominant action, latest released review context | limitations, technical detail, evidence/proof links | review status, output readiness, publication/sharing boundary | existing review/evidence actions only | open successor review if known, create next review, refresh review, publish review, open evidence | publish and next-cycle creation remain high-impact and must retain confirmation/audit/policy behavior |
| Environment Review detail guidance | MSP operator / support | Understand or execute the next review lifecycle step without duplicate CTA rails | detail context | Is this review blocked, ready, or historical, and where is the real action surface? | review status, output readiness, publication boundary, aligned next step | sections, evidence, proof links, technical detail | lifecycle, output readiness, publication/sharing state | existing detail lifecycle action set | existing dominant header action or one aligned CTA | archive stays in danger group; customer_workspace mode suppresses duplicated CTAs |

## Workspace Hierarchy Notes

- The workspace decision card keeps exactly one dominant primary CTA. All other mapped actions remain secondary links or a subdued button group beneath the primary action.
- The right-side review-pack state card must separate three semantics: package exists, internal export, and customer sharing.
- Review acknowledgement copy must stay explicit that acknowledgement records review consumption and does not make the output customer-ready.
- The review consumption flow remains available as supporting reference only and must not read like a second decision surface beside the main decision card.

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: no
- **New persisted entity/table/artifact?**: no
- **New abstraction?**: yes
- **New enum/state/reason family?**: no
- **New cross-domain UI framework/taxonomy?**: no
- **Current operator problem**: review-output guidance explains blockers but does not always expose the next real repo-backed action first.
- **Existing structure is insufficient because**: `ReviewPackOutputResolutionGuidance` should remain the source for readiness, limitations, and explanatory copy, but it only derives URL/disclosure actions while the repo-real lifecycle actions live separately on detail headers and are not yet selected or mounted from one canonical resolve-action path.
- **Narrowest correct implementation**: one review-output-only mapper that becomes the canonical selector of `resolution_case.primary_action` and `secondary_actions` for the two in-scope surfaces, plus, if strictly necessary, a small `ResolutionAction` extension for missing execution-routing metadata such as `action_name` and `execution_surface` while reusing existing `disabled_reason`, capability, confirmation, audit, and `OperationRun` metadata.
- **Ownership cost**: one mapper, targeted tests, possible action metadata extension, and review of one current confirmation gap (`create_next_review`).
- **Alternative intentionally rejected**: a generic remediation/resolution framework or a dashboard/provider/governance roll-out in the same slice.
- **Release truth**: current-release truth over existing review/evidence/output surfaces.

### Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*

- **Test purpose / classification**: Unit + Feature + Browser
- **Validation lane(s)**: fast-feedback + confidence + browser
- **Why this classification and these lanes are sufficient**: deterministic action selection belongs in Unit tests, workspace/detail behavior belongs in Feature tests, and one browser smoke proves the dominant CTA is visible and honest on the real surfaces.
- **New or expanded test families**: one bounded `ResolutionGuidance` mapper family only
- **Fixture / helper cost impact**: reuse existing review/evidence factories and helpers; no new expensive global defaults
- **Heavy-family visibility / justification**: one browser smoke is explicit because the change affects first-screen CTA trust on strategic review surfaces
- **Special surface test profile**: `global-context-shell` + `shared-detail-family`
- **Standard-native relief or required special coverage**: required special coverage for workspace decision card and detail suppression behavior
- **Reviewer handoff**: verify lane fit, check that executable actions are only source-owned, confirm no fake enabled buttons remain, and rely on the exact commands below
- **Budget / baseline / trend impact**: none expected beyond one new bounded browser smoke
- **Escalation needed**: document-in-feature only if `create_next_review` confirmation cannot be safely aligned in-scope
- **Active feature PR close-out entry**: Guardrail / Confirmation / Smoke Coverage
- **Planned validation commands**:
  - `cd apps/platform && ./vendor/bin/sail artisan test tests/Unit/ResolutionGuidance/Spec351ReviewOutputResolveActionMapperTest.php --compact`
  - `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec351CustomerReviewWorkspaceResolveActionTest.php tests/Feature/EnvironmentReview/Spec351EnvironmentReviewResolveActionTest.php --compact`
  - `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec351ReviewOutputResolveActionsSmokeTest.php --compact`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec347`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec349`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec350`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=CustomerReviewWorkspace`
  - `cd apps/platform && ./vendor/bin/sail pint --dirty`
  - `git diff --check`

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Move a blocked published output into the next safe review cycle (Priority: P1)

As an MSP operator, I need the workspace to show the real next review-cycle action for a blocked or limited published output so I can stop diagnosing and start moving the output forward safely.

**Why this priority**: This is the core productization gap after Spec 350.

**Independent Test**: Can be fully tested by seeding a published review with blocked output and asserting that the workspace selects a repo-backed successor/create/fallback action deterministically.

**Acceptance Scenarios**:

1. **Given** a published review with output blockers and a deterministic successor review target, **When** the workspace is opened, **Then** the dominant action opens that successor review instead of showing a fake fix.
2. **Given** a published review with output blockers and no known successor review, **When** the workspace is opened by a manage-capable actor, **Then** the dominant action offers the existing next-cycle creation path or an honest fallback.

---

### User Story 2 - Resolve a mutable review from stale or incomplete inputs (Priority: P1)

As an operator on a mutable review, I need the guidance to point to the real input-refresh or evidence path that unblocks publication.

**Why this priority**: Draft/ready reviews already have lifecycle actions, but the guidance surfaces do not yet map to them directly.

**Independent Test**: Can be tested by seeding mutable reviews with missing/stale evidence and asserting refresh/evidence fallback behavior on workspace or detail.

**Acceptance Scenarios**:

1. **Given** a mutable review with stale or incomplete evidence, **When** the mapper runs, **Then** it chooses `refresh_review` only when that action is safe and available on the current surface.
2. **Given** a mutable review without a safe execution surface for refresh, **When** the mapper runs, **Then** it falls back to `Open evidence basis` or another truthful disclosure action.

---

### User Story 3 - Publish a ready draft without CTA duplication (Priority: P2)

As an operator on a publishable draft, I need the guidance to align with the publish action without creating two competing primary CTAs on the detail surface.

**Why this priority**: The detail page already has lifecycle header actions, so Spec 351 must improve clarity without creating visual competition.

**Independent Test**: Can be tested by seeding a ready review or running the local/testing browser fixture command and asserting that the dominant next step matches the publish path while customer-workspace detail mode stays suppressed.

**Acceptance Scenarios**:

1. **Given** a ready mutable review, **When** the detail surface is opened normally, **Then** the next-step semantics align with `Publish review` and do not create duplicate primary action rails.
2. **Given** the same review is opened in `customer_workspace` detail mode, **When** the guidance card renders, **Then** the CTA remains suppressed and the context note stays visible.

## Requirements

- **FR-351-001**: Add a deterministic `ReviewOutputResolveActionMapper` that is the canonical selector of one dominant next action plus optional secondary actions for `resolution_case` on the two in-scope surfaces.
- **FR-351-002**: Published blocked or limited reviews MUST prefer a known successor-review-open path only when the target review is actually known; otherwise they MUST prefer `create_next_review` or an honest fallback.
- **FR-351-003**: Mutable blocked reviews MUST prefer `refresh_review` only when the current surface and actor can safely execute it; otherwise they MUST fall back to evidence/detail navigation.
- **FR-351-004**: Ready mutable reviews MUST align to the existing `publish_review` action when it is safe and permitted.
- **FR-351-005**: Unsupported, unsafe, or unauthorized executable actions MUST degrade to truthful navigation, disclosure, or `none`; no fake enabled fix buttons are allowed.
- **FR-351-006**: `CustomerReviewWorkspace` MUST use the mapper for the dominant review-output CTA while preserving existing findings and accepted-risk follow-up overrides.
- **FR-351-007**: `EnvironmentReviewResource` detail MUST use the same action semantics by aligning the guidance next-step semantics to the existing dominant header lifecycle action in normal detail mode, without reintroducing duplicate primary CTA rails, and while preserving `customer_workspace` detail-mode suppression.
- **FR-351-008**: If `create_next_review` is surfaced as a dominant executable resolve action, the source-owned action MUST require confirmation before it can be executed from workspace or detail; otherwise the mapper MUST degrade to truthful navigation, disclosure, or `none`.
- **FR-351-009**: Any workspace-side executable CTA MUST reuse Filament page actions and existing services, not direct Blade-to-service calls.
- **FR-351-010**: No new persistence, lifecycle states, provider/dashboard consumers, or workflow engine abstractions may be introduced in this slice.
- **FR-351-011**: `CustomerReviewWorkspace` MUST keep exactly one dominant primary CTA in the decision card and MUST render every other mapped action as secondary navigation or subdued supporting actions, not as peer primary CTAs.
- **FR-351-012**: `CustomerReviewWorkspace` MUST split review-pack truth into distinct package-exists, internal-export, and customer-sharing semantics instead of flattening them into one undifferentiated state list.
- **FR-351-013**: Review acknowledgement copy MUST explicitly state that acknowledgement records review consumption and does not determine whether the output is customer-ready.
- **FR-351-014**: The workspace review-consumption flow MUST remain a supporting reference below the primary decision surfaces and MUST not present itself as a second decision surface.

## Non-Goals

- Provider readiness, required permissions, and verification productization
- Governance Inbox or Environment Dashboard adoption of the same contract
- Customer portal, PDF/HTML rendering, PSA/ITSM, or AI suggestions
- New tables, new enums, or new workflow/lifecycle engines
- Broad review register or review detail redesign outside the resolve-action slice

## Acceptance Criteria

- **AC1**: The prep package documents which candidate resolve actions are repo-backed, partially repo-backed, fallback-only, or deferred.
- **AC2**: Action selection is deterministic and covered by Unit tests for published blocked, mutable blocked, ready draft, internal-only, and no-action fallback states.
- **AC3**: Workspace guidance no longer defaults to disclosure-first copy when a stronger real review-output action exists and can be executed or linked honestly.
- **AC4**: Published reviews are never presented as directly editable; next-cycle or disclosure semantics stay explicit.
- **AC5**: Mutable drafts can resolve to refresh or publish actions when repo-backed and permitted.
- **AC6**: No fake successor-review-open action appears unless a real target review is known.
- **AC7**: Environment Review detail stays non-duplicative and preserves `customer_workspace` CTA suppression.
- **AC8**: Capability, confirmation, audit, and `OperationRun` behavior are reused from the source-owned actions.
- **AC9**: Spec 347, 349, 350, and `CustomerReviewWorkspace` regressions are part of the implementation validation plan.
- **AC10**: Browser smoke proves one real next step or one honest fallback on at least one blocked and one ready-state path.
- **AC11**: In workspace browser proof, `Create next review` or the mapped dominant action is the only visually primary CTA; other actions render as secondary supporting actions.
- **AC12**: The workspace sidebar separates package existence, internal export, and customer sharing, and the acknowledgement card states that acknowledgement does not make the output customer-ready.
- **AC13**: Local/testing manual verification may use a bounded browser fixture command that seeds a published predecessor plus a linked ready successor review without adding new production persistence families or workflow abstractions.

## Risks

- **Risk 1**: The current guidance contract can select executable intent, but the current blades only understand URL buttons.
  - **Mitigation**: reuse existing Filament page actions on `CustomerReviewWorkspace` and avoid inline execution on detail unless it replaces, not duplicates, the header action.
- **Risk 2**: `create_next_review` is currently repo-real but not confirmation-gated.
  - **Mitigation**: treat confirmation alignment as an explicit implementation decision for this spec before the action becomes the dominant CTA.
- **Risk 3**: "Open successor review" may be overclaimed if no deterministic successor target exists.
  - **Mitigation**: require a known `superseded_by_review_id` or another repo-verified target before showing that action.
- **Risk 4**: Readonly workspace viewers may see unsafe or misleading action affordances.
  - **Mitigation**: capability-aware fallback selection and no fake enabled buttons.

## Assumptions

- `CustomerReviewWorkspace` can safely mount additional Filament page actions because it already uses `mountAction()` plus `<x-filament-actions::modals />`.
- Environment Review detail can satisfy the resolve-action contract by aligning with existing lifecycle header actions instead of always adding a second button inside the guidance card.
- Review-output action mapping remains review-output-only in this slice; provider/dashboard/inbox reuse stays deferred.

## Open Questions

- No blocking product questions remain for preparation. Implementation may decide whether to retain current repo-real labels (`Create next review`, `Refresh review`) or adopt clearer copy (`Create next review draft`, `Refresh review inputs`) as long as the source-owned behavior and audit/capability semantics stay consistent.

## Follow-up Spec Candidates

- `352-platform-sellable-smoke-matrix`
- `353-provider-readiness-productization`
- `354-review-pack-pdf-html-renderer-v1`
- `355-customer-portal-boundary-contract`
- `356-private-ai-resolution-suggestion-foundation`