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

# Feature Specification: Spec 349 - Customer Review Workspace Output Resolution Guidance

**Feature Branch**: `349-customer-review-workspace-output-resolution-guidance`  
**Created**: 2026-06-03  
**Status**: Draft  
**Type**: Platform productization / operator guidance / output-readiness resolution UX  
**Runtime posture**: Narrow runtime hardening over existing Review Pack output-readiness truth, Customer Review Workspace guidance, and Environment Review detail surfaces. No new persistence, no workflow engine, no portal, and no PDF/HTML renderer.  
**Input**: User-provided full Spec 349 draft + repo truth from current Customer Review Workspace, Environment Review detail, Review Pack routes, and completed Spec 347 output-readiness work.

## Dependencies And Historical Context

This spec is a bounded follow-up over already repo-real review, evidence, and customer-safe productization work:

- Spec 258 - Customer Review Workspace Productization
- Spec 308 - Decision Register Summary / Review Pack Inclusion
- Spec 311 - Workspace / Environment Surface Scope Contract
- Spec 326 - Customer Review Workspace v1 Productization
- Spec 342 - Customer Review Workspace Final Consumption Productization
- Spec 343 - Customer Review Attestation / Accepted Risk Lifecycle
- Spec 344 - Customer Review Workspace Density / Audience Polish
- Spec 347 - Review Pack Output Contract & Readiness Semantics

Repo-truth adjustments against the user draft:

- The runtime already has a bounded derived readiness layer in `App\Support\ReviewPacks\ReviewPackOutputReadiness`; Spec 349 should extend or adapt that truth rather than invent a second raw-readiness dialect.
- `CustomerReviewWorkspace` already maps readiness into a primary label, reason, impact, and primary/secondary action, but it does not yet expose a grouped resolution-guidance object with one dominant blocker and compact limitation disclosure.
- The review detail surface is Filament infolist-driven through `EnvironmentReviewResource` and `ViewEnvironmentReview.php`; there is no dedicated custom Blade detail page to redesign.
- The existing durable audit report for this surface is `docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md`; the user-draft reference to `ui-009-review-pack-output-contract.md` conflicts with repo truth because `ui-009` is already Provider Connections.
- Exact primary runtime routes are already repo-backed:
  - `/admin/reviews/workspace`
  - `/admin/workspaces/{workspace}/environments/{environment}/environment-reviews`
  - `/admin/workspaces/{workspace}/environments/{environment}/environment-reviews/{record}`
  - `/admin/workspaces/{workspace}/environments/{environment}/review-packs`
  - `/admin/workspaces/{workspace}/environments/{environment}/review-packs/{record}`
  - `/admin/review-packs/{reviewPack}/download`
  - `/admin/evidence/overview`
  - `/admin/workspaces/{workspace}/environments/{environment}/evidence/{record}`

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

- **Problem**: Spec 347 made Review Pack output truth more explicit, but the operator still has to translate readiness codes, limitation flags, and related proof surfaces into one next action.
- **Today's failure**: Customer Review Workspace and Environment Review detail can already show qualified output states such as `Published with limitations`, but the operator still has to infer which limitation matters most, where to go next, and whether the package is customer-safe, internal-only, or simply blocked.
- **User-visible improvement**: The product surfaces expose one clear output-guidance state, one dominant next action, a compact grouped limitation list, honest download wording, and collapsed technical details.
- **Smallest enterprise-capable version**: Reuse the existing output-readiness truth and current surface routes, add one bounded guidance layer over it, update Customer Review Workspace and Review Detail disclosure, and add focused tests plus browser smoke.
- **Explicit non-goals**: No new table, no persisted resolution records, no new queue family, no workflow engine, no portal, no PDF/HTML renderer, no PSA/ITSM handoff, no review-pack generator rewrite, no broad Governance Inbox redesign, no localization overhaul beyond touched output-guidance copy.
- **Permanent complexity imported**: One repo-truth map, one requirements checklist, focused plan/tasks artifacts, and likely one bounded guidance presenter/helper or an extension of the existing readiness helper. No new persisted entity, no new public state machine, and no new panel or route family.
- **Why now**: Spec 347 solved contract truth first. The next bottleneck is operator comprehension and calm decision-making on the current sellable review-consumption path.
- **Why not local**: Copy-only tweaks would leave workspace and detail surfaces free to interpret the same readiness codes differently. This needs one bounded mapping from current readiness truth to operator guidance.
- **Approval class**: Workflow Compression.
- **Red flags triggered**: Strategic customer-safe surface, status/next-action semantics, and shared interaction-family reuse. Defense: the slice is explicitly derived-only, reuses current routes and readiness truth, and forbids new persistence or a workflow engine.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12**
- **Decision**: approve.

## Candidate Source And Completed-Spec Guardrail

- **Candidate source**:
  - direct user-provided Spec 349 draft
  - roadmap lane: Customer Review Workspace v1 Completion / customer-safe review consumption
  - spec-candidate alignment: bounded follow-up under `customer-review-workspace-v1-completion`
- **Completed-spec guardrail result**:
  - no `specs/349-*` package existed before this prep
  - Specs 258, 308, 311, 326, 342, 343, 344, and 347 carry completed-task, close-out, validation, or historical implementation signals and are treated as context only
  - no completed spec is being reopened or normalized by this prep
- **Close alternatives deferred**:
  - Localization v1 customer-facing surfaces
  - Decision-Based Governance Inbox v1
  - Provider readiness / onboarding productization
  - Review Pack PDF/HTML renderer and Customer Portal boundary work
- **Smallest viable implementation slice**: existing output-readiness truth plus Customer Review Workspace and Environment Review detail guidance only: one dominant blocker, one primary action, grouped limitations, qualified download labels, collapsed technical details, and focused validation.

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace canonical-view plus environment-owned review/evidence/review-pack artifact surfaces.
- **Primary Routes**:
  - `/admin/reviews/workspace`
  - `/admin/workspaces/{workspace}/environments/{environment}/environment-reviews/{record}`
  - `/admin/workspaces/{workspace}/environments/{environment}/review-packs/{record}`
  - `/admin/review-packs/{reviewPack}/download`
  - `/admin/evidence/overview`
  - `/admin/workspaces/{workspace}/environments/{environment}/evidence/{record}`
- **Data Ownership**:
  - `EnvironmentReview` remains review publication/completeness truth
  - `EnvironmentReviewSection` remains section truth
  - `EvidenceSnapshot` remains evidence-basis truth
  - `ReviewPack` remains export artifact truth
  - `ReviewPackOutputReadiness` remains derived output-readiness truth
  - any new guidance state remains derived presentation only; no new persisted entity is introduced
- **RBAC**:
  - existing workspace membership and managed-environment entitlement remain mandatory
  - existing capabilities remain authoritative, especially `ENVIRONMENT_REVIEW_VIEW`, `REVIEW_PACK_VIEW`, and `EVIDENCE_VIEW`
  - non-members and cross-workspace or cross-environment access remain deny-as-not-found
  - no new public route family, query alias, or hidden shell-context fallback may be introduced

For canonical-view specs:

- **Default filter behavior when tenant-context is active**: keep `environment_id` as the explicit page-local filter on `/admin/reviews/workspace`; do not revive hidden shell/session environment fallback.
- **Explicit entitlement checks preventing cross-tenant leakage**: workspace, environment-review, review-pack, download, and evidence links must continue to resolve only through current scoped routes, policies, and signed-download checks.

## 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
- [ ] New modal/drawer/wizard/action added
- [x] New table/form/state added
- [x] Customer-facing surface changed
- [ ] 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")*

- **Route/page/surface**:
  - `CustomerReviewWorkspace`
  - Environment Review detail (`ViewEnvironmentReview` / `EnvironmentReviewResource` infolist)
  - Review Pack download wording as reached from those surfaces
- **Current or new page archetype**: existing strategic customer-safe review surface plus existing detail/proof surfaces; no new route archetype.
- **Design depth**: Strategic Surface for `CustomerReviewWorkspace`; Domain Pattern Surface for Environment Review detail.
- **Repo-truth level**: repo-verified existing runtime surface plus repo-verified completed Spec 347 readiness truth.
- **Existing pattern reused**: current decision card, current readiness proof panel, current detail infolist, current diagnostics/disclosure collapse pattern.
- **New pattern required**: one bounded output-resolution guidance adapter over current readiness truth; no new cross-domain UX framework.
- **Screenshot required**: yes, under `specs/349-customer-review-workspace-output-resolution-guidance/artifacts/screenshots/`.
- **Page audit required**: update `docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md`. If implementation later proves a second durable page report is needed for detail/proof coverage, it must use the next repo-real identity instead of overwriting `ui-009`.
- **Customer-safe review required**: yes. This spec directly governs customer-safe, internal-only, limited, and blocked output messaging.
- **Dangerous-action review required**: no new destructive action is added. Existing acknowledgement, publish, regenerate, and download safety remain authoritative.
- **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)*

- **Cross-cutting feature?**: yes
- **Interaction class(es)**: status messaging, next-action guidance, action links, proof surfaces, customer-safe disclosure, download wording.
- **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/routes
- **Existing pattern(s) to extend**:
  - current output-readiness derivation
  - current workspace decision card and proof panel
  - current Environment Review artifact-truth and executive-posture sections
- **Shared contract / presenter / builder / renderer to reuse**: current `ReviewPackOutputReadiness` output, existing workspace link helpers, and current detail truth presentation before adding any new formatter.
- **Why the existing shared path is sufficient or insufficient**: current readiness truth is sufficient as the raw source, but it is not yet shaped into one grouped operator-guidance object that multiple surfaces can consume without copy drift.
- **Allowed deviation and why**: one bounded `ReviewPackOutputResolutionGuidance`-style companion or equivalent page-local formatter is allowed if extending `ReviewPackOutputReadiness` directly would blur raw truth and UI guidance too far.
- **Consistency impact**: limitation code -> label/reason/impact/action mapping must stay consistent across workspace, review detail, and qualified download wording.
- **Review focus**: block any second readiness dialect, any persisted resolution entity, or any generic workflow engine disguised as guidance.

## OperationRun UX Impact *(mandatory)*

- **Touches OperationRun start/completion/link UX?**: existing proof-link and artifact handoff only
- **Shared OperationRun UX contract/layer reused**: existing operation proof links and current review-pack generation lifecycle
- **Delegated start/completion UX behaviors**: unchanged
- **Local surface-owned behavior that remains**: blocker ranking, grouped limitation disclosure, and qualified next-action wording
- **Queued DB-notification policy**: unchanged
- **Terminal notification path**: unchanged
- **Exception required?**: none

## Provider Boundary / Platform Core Check *(mandatory)*

- **Shared provider/platform boundary touched?**: no new provider seam
- **Boundary classification**: platform-core output guidance over existing review/evidence/export truth
- **Seams affected**: review/output vocabulary only
- **Neutral platform terms preserved or introduced**: review pack, evidence basis, output readiness, publication blocked, internal-only, customer-safe, limitation, next action
- **Provider-specific semantics retained and why**: only where existing review/evidence content already contains provider-backed wording
- **Why this does not deepen provider coupling accidentally**: no Graph, provider contract, identifier, or platform-core taxonomy change is introduced
- **Follow-up path**: none

## UI / Surface Guardrail Impact

| 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 and limitation summary | yes | Native Filament page plus existing Blade composition | readiness, next action, disclosure, download wording | page, URL-query, derived payload | no | Existing route only |
| Customer Review Workspace review-pack proof panel | yes | Native Filament page plus existing Blade composition | proof details, evidence basis, section completeness, PII visibility | page payload | no | Derived only |
| Environment Review detail summary and posture sections | yes | Native Filament resource/infolist | review status vs output readiness vs sharing state | detail payload | no | Existing detail route only |
| Review Pack detail/download handoff wording | no by default | existing Filament resource/detail | artifact handoff wording only if contradiction fix becomes unavoidable | none unless repo truth forces a minimal consistency patch | yes if unexpectedly touched | keep out of scope unless a direct contradiction is proven |

## Decision-First Surface Role

| 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 | Operator decides whether the current package is customer-safe, limited, internal-only, or blocked | one status, one reason, one next action, limitation count, qualified download state | detailed limitation list, evidence link, review detail, operation proof | Primary because it is the first customer-safe consumption screen | follows review handoff workflow | removes interpretation work across multiple panels and labels |
| Environment Review detail | Secondary Context | Operator verifies why the review output is blocked or limited before acting | review status, output readiness, publication/sharing state, next action | sections, evidence, review-pack proof, raw artifact truth | Secondary because it supports the first-screen decision | follows inspect-and-resolve workflow | keeps proof secondary and avoids another equal-weight warning wall |
| Review Pack detail/download | Secondary Context | Operator verifies artifact truth and authorized download path | artifact availability and qualified download meaning | file metadata, operation proof, download audit | Secondary because it is artifact proof, not the first decision surface | supports export verification | prevents detail-only semantics from leaking into the primary screen |

## Audience-Aware Disclosure

| 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, customer-safe review consumer, support where authorized | output status, primary blocker, impact, next action, limitation count, qualified download label | limitation list, section summary, evidence basis state, PII/redaction notes | raw payloads, fingerprints, lower-level proof details | one primary resolution/download action | technical details collapsed or secondary | top card states the blocker once; lower sections add evidence only |
| Environment Review detail | operator-MSP, support where authorized | review status, output readiness, publication/sharing state, next action | section counts, publish blockers, evidence basis, current export truth | raw metadata, fingerprints, support-only proof details | open the primary blocker destination | raw/support detail stays secondary and capability-scoped | detail view distinguishes status dimensions instead of restating them ambiguously |

## UI/UX Surface Classification

| 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 | Read-only strategic review hub | resolve the highest-priority blocker or download the qualified pack | explicit primary action in the decision card | forbidden | secondary links remain visually secondary | none in scope | `/admin/reviews/workspace` | existing review/evidence/pack routes only | workspace shell plus explicit `environment_id` filter | Customer Review Workspace | one output state, one blocker, one next action | none |
| Environment Review detail | Detail / Governance Artifact Detail | Read-only review detail | inspect the output blocker and open the linked proof surface | existing detail route | current repo-real behavior only | contextual detail links and secondary proof stay inside sections | existing lifecycle actions remain outside customer-workspace mode | `/admin/workspaces/{workspace}/environments/{environment}/environment-reviews` | `/admin/workspaces/{workspace}/environments/{environment}/environment-reviews/{record}` | workspace + environment route scope | Review detail | review status, output readiness, sharing state | none |

## Operator Surface Contract

| 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 | MSP/workspace operator | decide whether current output can be shared and what to resolve first | workspace review hub | Can I use or share this package, and what do I do next? | output status, blocker, impact, next action, limitation count, qualified download state | limitation details, section/evidence proof, operation proof | review publication, review completeness, output readiness, customer-safe boundary | none by default | review/open/download qualified package | none in scope |
| Environment Review detail | MSP/operator reviewer | inspect why a review is blocked or limited and open the right supporting context | read-only detail | Why is this review not customer-ready, and which proof surface explains it? | review status, output readiness, sharing/publication state, next action | sections, evidence, artifact proof, fingerprint and raw metadata | review publication, completeness, output readiness, artifact availability | existing lifecycle mutations remain unchanged and out of customer-workspace mode | open proof/evidence/review-pack links | existing publish/archive/export actions remain unchanged and already confirmation-gated where applicable |

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

- **New source of truth?**: no
- **New persisted entity/table/artifact?**: no
- **New abstraction?**: maybe one bounded presentation adapter over current readiness truth
- **New enum/state/reason family?**: no persisted family; any added `publication_blocked` or similar state must remain derived presentation only
- **New cross-domain UI framework/taxonomy?**: no
- **Current operator problem**: the runtime knows why output is limited, but the operator still has to assemble the right conclusion and next action manually.
- **Existing structure is insufficient because**: current readiness truth is optimized for contract/data correctness, not for grouped operator guidance across workspace and detail surfaces.
- **Narrowest correct implementation**: reuse the current readiness helper, derive one compact guidance object, and update only the current workspace/detail surfaces plus wording.
- **Ownership cost**: one bounded helper or formatter, focused tests, browser smoke, and one page-report update.
- **Alternative intentionally rejected**: new workflow engine, persisted resolution items, portal, or broad cross-domain guidance framework.
- **Release truth**: current-release truth.

### Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility shims, legacy route aliases, old audit-report renumbering, and compatibility-specific UI states are out of scope unless repo truth later proves they are required.

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

- **Test purpose / classification**: Feature, Browser
- **Validation lane(s)**: confidence, browser
- **Why this classification and these lanes are sufficient**: the change is a deterministic mapping and disclosure hardening over existing server-rendered surfaces. Focused Feature tests can prove grouped limitation behavior, one-primary-action rules, qualified download labels, and detail-surface separation. One bounded Browser smoke is required because this is a strategic customer-safe first-screen surface.
- **New or expanded test families**:
  - `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`
- **Relevant existing regressions to rerun**:
  - `apps/platform/tests/Feature/ReviewPack/Spec347ReviewPackOutputContractTest.php`
  - `apps/platform/tests/Feature/ReviewPack/Spec347ReviewPackReadinessSemanticsTest.php`
  - `apps/platform/tests/Feature/Filament/Spec347CustomerReviewWorkspaceOutputReadinessTest.php`
  - `apps/platform/tests/Feature/Filament/Spec342CustomerReviewWorkspaceConsumptionTest.php`
  - `apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php`
  - `apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php`
  - `apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewUiContractTest.php`
- **Fixture / helper cost impact**: reuse current review/evidence/review-pack helpers and avoid widening default browser or workspace fixtures.
- **Heavy-family visibility / justification**: one explicit browser smoke only
- **Special surface test profile**: `global-context-shell` + `shared-detail-family` + strategic customer-safe review surface
- **Standard-native relief or required special coverage**: special coverage required for no-false-share wording, one-primary-action discipline, grouped limitations, and detail-surface status separation
- **Reviewer handoff**: reviewers must confirm no new persistence, no second readiness dialect, no weakened signed-download behavior, and no equal-weight warning wall on the workspace/detail surfaces
- **Budget / baseline / trend impact**: none expected beyond one explicit browser smoke addition
- **Escalation needed**: `document-in-feature` if a minor detail-surface contradiction must be recorded; `follow-up-spec` only if repo truth reveals a broader output-guidance framework need
- **Active feature PR close-out entry**: Guardrail / Smoke Coverage
- **Planned validation commands**:

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

## Summary

Spec 347 already established the output-readiness contract. Spec 349 must not reopen that truth. The bounded job here is to productize it:

- one primary output state
- one dominant next action
- grouped limitations
- qualified download wording
- explicit internal-only / customer-safe boundary
- collapsed technical details
- distinct review status vs output readiness vs sharing/publication state on the detail surface

The implementation should extend existing readiness truth and current routes only.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - See one clear blocker on the workspace (Priority: P1)

As an MSP operator, I need the Customer Review Workspace to translate current output-readiness limitations into one dominant blocker and one next action so I can decide quickly whether the package is ready, limited, internal-only, or blocked.

**Why this priority**: This is the first customer-safe consumption surface and the main sellability gap after Spec 347.

**Independent Test**: Can be fully tested by loading the workspace with ready, limited, blocked, and internal-only fixtures and asserting one state, one primary action, and honest download wording.

**Acceptance Scenarios**:

1. **Given** the current review output has publish blockers or missing evidence, **When** the workspace loads, **Then** it shows one dominant blocker, one primary next action, and grouped supporting limitations instead of many equal-weight warnings.
2. **Given** the output is customer-safe and export-ready, **When** the workspace loads, **Then** it shows a customer-safe state with a qualified download action.

---

### User Story 2 - Inspect limitations without a warning wall (Priority: P1)

As an operator, I need limitation details and technical metadata available on demand without dominating the default screen so I can verify the proof without losing the first decision.

**Why this priority**: Spec 347 increased truth density; the next step is progressive disclosure, not more visible warnings.

**Independent Test**: Can be tested by asserting grouped limitation disclosure, collapsed technical details, and visible PII/internal-only warnings where applicable.

**Acceptance Scenarios**:

1. **Given** multiple output limitations exist, **When** the workspace or review detail renders, **Then** the limitations appear as a compact grouped list or disclosure and not as a flat wall of badges or alerts.
2. **Given** the output includes PII or internal-only context, **When** the surface renders, **Then** the operator sees that warning before any customer-safe share wording.

---

### User Story 3 - Distinguish review status from output readiness on detail (Priority: P2)

As an operator opening a released review, I need the detail page to separate review publication/completeness from output-readiness/sharing state so I do not mistake "published" for "customer-safe".

**Why this priority**: This is the main semantic trap left after Spec 347.

**Independent Test**: Can be tested by opening a published-but-limited review and asserting distinct labels/rows for review status, output readiness, and sharing/publication state.

**Acceptance Scenarios**:

1. **Given** a review is published but has output blockers, **When** the detail page renders, **Then** publication status remains visible but separate from output-readiness and sharing-state messaging.
2. **Given** the detail page is opened from Customer Review Workspace context, **When** the page renders, **Then** it preserves existing scoped access and handoff behavior while showing the clearer output-guidance separation.

## Functional Requirements

- **FR-349-001**: The product MUST derive output resolution guidance from existing review/output-readiness truth; no new persistence is allowed.
- **FR-349-002**: Customer Review Workspace MUST show one dominant output-guidance state and one primary next action.
- **FR-349-003**: Multiple limitations MUST be grouped into a compact list or disclosure instead of many equal-weight warnings.
- **FR-349-004**: The primary blocker MUST map to one plain-language reason and one supporting impact statement.
- **FR-349-005**: Qualified download wording MUST reflect whether the package is customer-safe, internal-only, limited, or not ready.
- **FR-349-006**: PII/internal-only state MUST be visible before any customer-safe/share wording is shown.
- **FR-349-007**: Technical details, section counts, evidence state, and related diagnostics MUST remain available but secondary.
- **FR-349-008**: Environment Review detail MUST distinguish review status, output readiness, and publication/sharing state.
- **FR-349-009**: Existing authorization, signed-download safety, acknowledgement behavior, and scope semantics MUST remain intact.
- **FR-349-010**: The workspace must remain workspace-scoped with visible `environment_id` filtering and no hidden topbar context behavior.

## Non-Functional Requirements

- **NFR-349-001**: The default UI must reduce attention load by showing one dominant output state and one dominant next action.
- **NFR-349-002**: Wording must remain operator-first, customer-safe, and conservative; when uncertain, the UI must prefer "requires review" over "customer-safe".
- **NFR-349-003**: The guidance layer must not add unbounded queries and should reuse already-loaded summary metadata where practical.
- **NFR-349-004**: Status, warning, and disclosure cues must remain accessible via text, keyboard-reachable controls, and non-color-only signaling.
- **NFR-349-005**: Any new display state must remain derived-only and must not become a persisted domain state or workflow state machine.

## Explicit Non-Goals

- No new table, persisted record, queue family, or workflow engine
- No Customer Portal or customer-facing route family
- No Review Pack PDF or HTML renderer
- No Review Pack generation rewrite
- No change to EvidenceSnapshot generation or OperationRun lifecycle semantics
- No broad Customer Review Workspace redesign beyond output guidance
- No Governance Inbox scope expansion
- No broad localization pass beyond touched output-guidance copy
- No billing, entitlement, PSA, or provider-onboarding work

## Success Criteria

- Customer Review Workspace shows one clear output-guidance state
- Highest-priority blocker becomes one clear next action
- Limitations are grouped and honest
- Download labels do not overpromise customer-safe sharing
- Review detail clearly separates review status from output readiness
- Technical details remain available without dominating the screen
- No new workflow engine or persisted resolution truth is introduced

## Risks

- **Guidance drift**: workspace and detail could interpret limitation codes differently if the mapping is not centralized.
- **Scope creep**: detail-surface hardening could spill into broader review resource redesign if not kept bounded.
- **False reassurance**: customer-safe wording could still overpromise if findings or accepted-risk follow-up are not folded into the effective state honestly.
- **Warning-wall regression**: a naive implementation could surface every limitation at equal weight and defeat the operator-guidance goal.

## Assumptions

- Spec 347 readiness truth remains the raw source of limitation codes and section/evidence signals.
- Existing scoped routes, signed-download behavior, and review/evidence helpers remain authoritative.
- `ui-006-customer-review-workspace.md` remains the durable page-report identity for this workspace surface unless repo truth later proves otherwise.

## Open Questions

- None blocking prep. Final label phrasing and whether the guidance adapter extends `ReviewPackOutputReadiness` directly or wraps it should be decided during implementation based on the narrowest code change.