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
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• 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
  • 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:

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.