TenantAtlas/specs/352-environment-dashboard-operator-guidance-consolidation/spec.md

Feature Specification: Spec 352 - Environment Dashboard Operator Guidance Consolidation

Feature Branch: 352-environment-dashboard-operator-guidance-consolidation
Created: 2026-06-04
Status: Draft
Type: Platform productization / environment dashboard follow-up / operator guidance consolidation
Depends on: Specs 330, 338, 346, 350, 351
Runtime posture: Bounded follow-up over the implemented Environment Dashboard runtime. No new persistence, workflow engine, provider/governance/backup adapter rollout, or dashboard rebuild.
Input: Direct user-provided Spec 352 draft plus repo truth from the implemented Spec 330 dashboard runtime and current review-output resolution-guidance surfaces.

Dependencies And Repo-Truth Adjustments

This spec is a follow-up over already repo-real dashboard and guidance foundations:

• Spec 330 implemented the Environment Dashboard decision-first scaffold and the current readiness/recommended-action layout.
• Spec 338 hardened workspace/environment route ownership and remains the environment-scope baseline.
• Spec 346 productized the Governance Inbox operator workflow and remains the adjacent governance-owner follow-up surface when the dashboard routes into governance attention.
• Spec 350 introduced the bounded ResolutionCase / ResolutionAction contract and the review-output-first adapter path.
• Spec 351 added real review-output resolve actions and made the review surfaces more action-aware.

Repo-truth adjustments against the user draft:

• The current dashboard runtime is already productized through:
  • apps/platform/app/Filament/Pages/EnvironmentDashboard.php
  • apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php
  • apps/platform/resources/views/filament/widgets/dashboard/environment-dashboard-overview.blade.php
• EnvironmentDashboardSummaryBuilder already derives:
  • recommendedActions
  • readinessDecision
  • governanceStatus
  • readinessCards
  • readinessDimensions
  • readinessProofPanel
• The current dashboard already shows one main readiness question, but its top decision area still depends on the first entry in recommendedActions rather than on an explicit, traceable dashboard guidance contract.
• ReviewPackOutputResolutionAdapter and the Spec 350/351 resolution contract exist, but the Environment Dashboard does not currently consume them.
• Spec 330 is treated as implemented historical truth. Spec 352 must reuse its layout and payload foundations instead of reopening the dashboard productization from scratch.
• Spec 351 has checked implementation tasks and repo-real runtime follow-through, but its browser audit still records residual P2 observations. Spec 352 may consume already repo-real review-output action semantics, but it must not pretend those residual observations are resolved or reopen Spec 351 under a dashboard label.

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

• Problem: The Environment Dashboard is already the environment command surface, but its primary recommendation still comes from ad hoc ranked actions and equal-weight signals instead of one explicit operator guidance case that says what matters first and why.
• Today's failure: Operators can still see provider permissions, findings, review freshness, backup posture, evidence, and operations at once, then reconstruct for themselves which domain owns the next safe step. The current top decision area mirrors the first recommended action, but not a stable guidance contract.
• User-visible improvement: The Environment Dashboard shows one dominant operator guidance case with status, reason, impact, one primary action, and clearly subordinate secondary links, while preserving the current proof panels and secondary cards.
• Smallest enterprise-capable version: Reuse the existing Environment Dashboard route, summary builder, and decision-first layout; add one derived dashboard guidance selector/payload; optionally consume the existing review-output ResolutionCase; keep all detailed work in the linked owner surfaces.
• Explicit non-goals: No dashboard rebuild, no baseline-compare rewrite, no new provider-readiness engine, no Governance Inbox rewrite, no new backup/restore adapter, no workflow engine, no persistence, no portal, no PDF renderer, no PSA/ITSM handoff, no AI suggestions or execution.
• Permanent complexity imported: One bounded dashboard-level derived guidance payload or selector, focused Unit/Feature/Browser tests, one repo-truth map, one contract note, and one page-report update. No new table, no new persisted truth, no new cross-surface framework beyond a page-local follow-up abstraction if it is strictly necessary.
• Why now: Spec 330 made the dashboard decision-first, and Specs 350/351 made review-output guidance explicit. The remaining gap is now visible: the dashboard still ranks repo-backed actions locally instead of presenting one stable operator guidance case over the current summary data.
• Why not local: Copy-only tweaks would leave the dashboard driven by page-local action ranking and would not solve the missing contract between current dashboard signals and the newer resolution-guidance behavior.
• Approval class: Workflow Compression.
• Red flags triggered: cross-surface reuse and new support-layer naming. Defense: the slice is limited to one existing page, reuses existing summary data, forbids new persistence/framework rollout, and keeps all mutation ownership in existing source surfaces.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve with strict follow-up-only and no-dashboard-rebuild constraints.

Candidate Source And Completed-Spec Guardrail

• Candidate source:
  • direct user-provided Spec 352 draft
  • docs/ui-ux-enterprise-audit/page-reports/ui-002-environment-dashboard.md
  • current repo truth in EnvironmentDashboardSummaryBuilder, EnvironmentDashboard, and the implemented Spec 330 dashboard runtime
• Queue posture:
  • docs/product/spec-candidates.md currently says no safe automatic next-best-prep target remains in the active queue
  • Spec 352 is therefore a manual promotion, not an auto-selected candidate from the active queue
• Completed-spec guardrail result:
  • no specs/352-* package or branch existed before this preparation run
  • Spec 330 contains implemented runtime truth and checked implementation tasks; treat it as completed historical context only
  • Spec 346 remains an adjacent governance-owner workflow dependency context and is not reopened, normalized, or closed by this prep package
  • Specs 338, 350, and 351 already contain checked implementation evidence or historical implementation signals and must not be normalized or rewritten
  • Spec 351 additionally carries residual browser-audit follow-up notes; Spec 352 may depend on the repo-real action semantics but must not hide or absorb those unresolved observations
• Close alternatives deferred:
  • provider readiness / provider connections follow-up
  • finding exceptions / accepted-risk accountability follow-up
  • review register or baseline-compare follow-up
  • broader cross-domain dashboard indicator cleanup
• Smallest viable implementation slice: existing Environment Dashboard only: derive one operatorGuidance case over current summary data, optionally merge in current review-output resolution guidance, keep the current proof panels/cards as secondary context, and update the page report plus focused tests/browser smoke.

Spec Scope Fields (mandatory)

• Scope: environment-owned dashboard follow-up
• Primary Routes:
  • /admin/workspaces/{workspace}/environments/{environment}
  • existing linked source routes only: required permissions, evidence, environment review/detail, customer review workspace, operation proof/detail, findings, risk exceptions, and current environment-owned drilldowns when repo-backed
• Data Ownership:
  • ManagedEnvironment, ProviderConnection, ManagedEnvironmentPermission, EvidenceSnapshot, EnvironmentReview, ReviewPack, Finding, FindingException, OperationRun, BackupSet, RestoreRun, and current dashboard aggregate helpers remain the source truth
  • EnvironmentDashboardSummary and any new dashboard guidance payload stay derived-only and request-scoped
  • no new table, model, enum, or persisted artifact is introduced
• RBAC:
  • workspace membership plus entitled environment access remain required
  • dashboard guidance visibility remains environment-scoped
  • linked primary/secondary actions must keep their existing policy/capability rules
  • non-member or out-of-scope environment access stays 404; member-but-missing-capability stays 403 on source-owned action destinations

For canonical-view specs: N/A. The primary surface is environment-owned, not workspace-canonical.

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:
  • App\Filament\Pages\EnvironmentDashboard
  • App\Support\EnvironmentDashboard\EnvironmentDashboardSummaryBuilder
  • App\Support\EnvironmentDashboard\EnvironmentDashboardSummary
  • apps/platform/resources/views/filament/widgets/dashboard/environment-dashboard-overview.blade.php
  • current Environment Dashboard header action hierarchy where it mirrors the dominant follow-up
• Current or new page archetype: existing environment-owned Overview / Dashboard surface UI-002
• Design depth: Strategic Surface
• Repo-truth level: repo-verified existing runtime
• Existing pattern reused:
  • docs/ui-ux-enterprise-audit/page-reports/ui-002-environment-dashboard.md
  • implemented Spec 330 dashboard decision card, readiness dimensions, proof panel, and secondary signal pattern
  • current dashboard action and proof-link helpers
• New pattern required: one bounded dashboard guidance selector/payload over current summary data; no new global dashboard taxonomy
• Screenshot required: yes, under specs/352-environment-dashboard-operator-guidance-consolidation/artifacts/screenshots/
• Page audit required: yes, update docs/ui-ux-enterprise-audit/page-reports/ui-002-environment-dashboard.md
• Customer-safe review required: no new customer-facing surface, but review-output wording reused on the dashboard must stay consistent with customer-safe review semantics
• Dangerous-action review required: no new dangerous action is expected; the dashboard should remain navigation-first and must not start new high-impact mutations directly
• 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 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): dashboard signals/cards, status messaging, action links, header actions, proof links, and review-output follow-up reuse
• Systems touched:
  • App\Support\EnvironmentDashboard\EnvironmentDashboardSummaryBuilder
  • App\Support\EnvironmentDashboard\EnvironmentDashboardSummary
  • App\Filament\Pages\EnvironmentDashboard
  • current Environment Dashboard Blade view
  • App\Support\ResolutionGuidance\ResolutionCase
  • App\Support\ResolutionGuidance\ResolutionAction
  • App\Support\ResolutionGuidance\Adapters\ReviewPackOutputResolutionAdapter
  • App\Support\OperationRunLinks
  • current required-permissions, findings, risk, review, and proof-link action builders already used by the dashboard summary
• Existing pattern(s) to extend:
  • current recommendedActions() ranking in EnvironmentDashboardSummaryBuilder
  • current readinessDecision() top-card derivation
  • existing review-output resolution adapter contract from Specs 350/351
• Shared contract / presenter / builder / renderer to reuse:
  • EnvironmentDashboardSummaryBuilder
  • ReviewPackOutputResolutionAdapter
  • ResolutionCase / ResolutionAction
  • OperationRunLinks
  • existing dashboard action helper methods such as required-permissions, findings, operations, review, and backup posture links
• Why the existing shared path is sufficient or insufficient: the repo already has current dashboard ranking and a newer resolution-guidance contract, but the dashboard still lacks one explicit environment guidance envelope tying those sources together without reopening the page layout.
• Allowed deviation and why: one bounded helper such as EnvironmentDashboardOperatorGuidanceSelector or an equivalent summary-builder sub-method is allowed if it remains page-local, derived-only, and does not become a generic workflow framework.
• Consistency impact: title/reason/impact/primary-action structure, secondary-link hierarchy, scope-explicit deep links, and honest unavailable states must stay aligned with current review-output, provider, evidence, operation, and governance wording.
• Review focus: block any second dashboard framework, fake executable remediation, duplicated primary CTA rails, or regression of the Spec 330 decision-first structure.

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, link semantics only
• Shared OperationRun UX contract/layer reused: App\Support\OperationRunLinks
• Delegated start/completion UX behaviors: unchanged; the dashboard may open existing operation proof/detail routes, but it does not start or change OperationRun lifecycle behavior
• Local surface-owned behavior that remains: candidate ranking, dominant guidance selection, and one-primary-action hierarchy
• Queued DB-notification policy: unchanged
• Terminal notification path: unchanged
• Exception required?: none

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)

• Shared provider/platform boundary touched?: yes
• Boundary classification: mixed
• Seams affected: provider-readiness prioritization, required-permissions wording, and dashboard-level routing into provider-owned follow-up surfaces
• Neutral platform terms preserved or introduced: environment, provider, required permissions, evidence, operation proof, review output, operator guidance
• Provider-specific semantics retained and why: provider-owned permission or verification wording may remain only where the current required-permissions or provider connection surfaces already own that vocabulary
• Why this does not deepen provider coupling accidentally: the dashboard guidance layer stays derived and environment-owned, and it routes into existing provider-owned surfaces instead of creating new provider semantics in the dashboard core
• Follow-up path: deeper provider readiness productization remains a separate follow-up spec

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
Environment Dashboard top guidance area	yes	Native Filament page plus existing custom Blade composition	dashboard signals, action links, proof links	page, derived summary payload	no	Existing route only
Environment Dashboard header primary action mirror	yes	Native Filament action hierarchy	header actions, navigation-first follow-up	page, derived summary payload	no	Must stay subordinate to source-owned safety rules

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
Environment Dashboard	Primary Decision Surface	Operator decides which environment issue deserves the first follow-up	one guidance case, reason, impact, one primary action, compact secondary links	readiness dimensions, proof panel, recent operations, supporting signals, linked owner surfaces	Primary because it is the environment command surface and already owns the first-read posture question	Follows the environment workflow before domain drilldown	Removes cross-card reconstruction and equal-weight signal scanning

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
Environment Dashboard	operator-MSP, manager, support where already authorized	one guidance case, status, reason, impact, one primary action, compact secondary links	readiness dimensions, proof items, supporting signals, linked source detail	raw diagnostics and support tooling remain behind the existing disclosure/capability seams	yes	diagnostics stay collapsed; no new raw payload exposure is introduced	the top guidance tells the operator once what matters most; the rest of the page adds proof and route choices only

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
Environment Dashboard	Workbench / Dashboard	Environment readiness workbench	open the dominant blocker or proof owner surface	explicit primary action in the guidance card	N/A	compact links inside the same guidance block and existing secondary sections	none introduced	/admin/workspaces/{workspace}/environments/{environment}	same route plus existing linked owner routes	active workspace + route-bound environment	Environment Dashboard	one dominant issue plus next step	none

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
Environment Dashboard	MSP operator / manager	decide what to do first in this managed environment	environment command surface	What needs attention first, why does it matter, and where should I go next?	one dominant guidance case, status, reason, impact, one primary action, subordinate links	existing proof/detail/diagnostic paths only	dashboard posture, provider readiness, review freshness/output, evidence coverage, operations attention, governance state	navigation-first only in this slice	open required permissions, open draft/review output surface, open evidence, open operation proof, open findings/risk surface, or honest unavailable fallback	none introduced

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no
• New abstraction?: yes, one bounded dashboard guidance selector/payload may be introduced if the current summary-builder methods are insufficient
• New enum/state/reason family?: no
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: the current dashboard already exposes signals and ranked actions, but operators still reconstruct the top issue from page-local action ranking instead of seeing one explicit environment guidance case
• Existing structure is insufficient because: recommendedActions and readinessDecision are still separate arrays, and the dashboard does not currently consume the newer review-output resolution contract or a stable dashboard guidance envelope
• Narrowest correct implementation: add one derived guidance payload over current dashboard data and optional review-output resolution reuse, then drive the top guidance area and mirrored header action from that payload only
• Ownership cost: one local selector/presenter, focused tests, a repo-truth map, a small contract note, and one page-report update
• Alternative intentionally rejected: a broad dashboard redesign, a repo-wide guidance rollout, a provider or governance adapter expansion, or a new persisted dashboard state model
• Release truth: current-release runtime follow-up over implemented Environment Dashboard behavior

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: the core risk is deterministic guidance selection, environment-scoped link behavior, and first-screen action hierarchy; Unit tests prove ranking, Feature tests prove rendered/dashboard integration and scope, and one Browser smoke proves the visual hierarchy remains calm and honest
• New or expanded test families:
  • apps/platform/tests/Unit/EnvironmentDashboard/Spec352EnvironmentDashboardGuidanceSelectionTest.php
  • apps/platform/tests/Feature/Filament/Spec352EnvironmentDashboardGuidanceTest.php
  • apps/platform/tests/Browser/Spec352EnvironmentDashboardGuidanceSmokeTest.php
• Fixture / helper cost impact: reuse existing Environment Dashboard, review-output, provider-permissions, and operations fixtures where available; do not widen default factories or browser setup
• Heavy-family visibility / justification: one explicit browser smoke is justified because this is a strategic first-screen operator surface
• Special surface test profile: monitoring-state-page + global-context-shell
• Standard-native relief or required special coverage: special coverage required because the feature changes one-primary-action hierarchy on a strategic dashboard surface
• Reviewer handoff: confirm no fake mutation CTA is added, no cross-environment link leakage exists, provider blockers outrank lower-priority cases where repo truth supports it, and the Spec 330 structure remains intact
• Budget / baseline / trend impact: low; one new bounded Unit family and one browser smoke file
• Escalation needed: document-in-feature if a bounded dashboard selector is needed; follow-up-spec only if implementation reveals that provider/governance/review-owner surfaces need broader rewrites
• Active feature PR close-out entry: Guardrail / Smoke Coverage
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Unit/EnvironmentDashboard/Spec352EnvironmentDashboardGuidanceSelectionTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec352EnvironmentDashboardGuidanceTest.php --compact
  • cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec352EnvironmentDashboardGuidanceSmokeTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=EnvironmentDashboard
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec330
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec350
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec351
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ResolutionGuidance
  • cd apps/platform && ./vendor/bin/sail artisan pint --dirty
  • git diff --check

User Scenarios & Testing (mandatory)

User Story 1 - See one dominant next step on the Environment Dashboard (Priority: P1)

As an MSP operator, I want the Environment Dashboard to show one dominant guidance case so I know what to do first without reconstructing the answer from multiple cards.

Why this priority: This is the core product value of the spec and the main remaining gap after Spec 330 and Specs 350/351.

Independent Test: Render the dashboard with competing repo-backed signals and assert that one guidance case wins, one primary action is shown, and supporting links remain clearly secondary.

Acceptance Scenarios:

1. Given an environment has a repo-backed dominant blocker, When the dashboard renders, Then the top guidance card shows one status, one reason, one impact, and one primary action.
2. Given secondary proof or follow-up links exist, When the top guidance renders, Then they appear as subordinate links and not as competing primary CTAs.
3. Given no repo-real primary action is available, When the dashboard renders, Then the top guidance shows an honest fallback such as review details or proof review instead of a fake executable action.

---

User Story 2 - Route the operator to the right owner surface (Priority: P1)

As an MSP operator, I want dashboard guidance to route me into the correct owner surface so the dashboard stays calm and does not become a second governance inbox or troubleshooting console.

Why this priority: The dashboard is valuable only if it compresses the first decision and hands off cleanly to the owner workflow.

Independent Test: Seed provider, review-output, evidence, and operation-attention scenarios and assert that the primary/secondary links remain environment-scoped, repo-backed, and authorization-aware.

Acceptance Scenarios:

1. Given provider permissions block evidence or review freshness, When the dashboard renders, Then provider readiness outranks lower-priority review or evidence follow-up where the current repo truth supports that ordering.
2. Given the latest review output has a repo-real resolution case, When the dashboard renders, Then the dashboard may surface that case or its mapped action without inventing a new review workflow.
3. Given an action target is unauthorized or unavailable, When the dashboard renders, Then the action stays hidden, disabled by current convention, or degrades to an honest fallback without leaking protected details.

---

User Story 3 - Show a calm no-action state without losing current proof surfaces (Priority: P2)

As an MSP operator, I want the dashboard to stay useful when no urgent action exists so the page does not feel broken or empty.

Why this priority: A sellable operator dashboard needs a truthful calm state, not only action-needed states.

Independent Test: Render an environment fixture with no dominant blocker and assert that the dashboard shows a productized no-urgent-action message while keeping the current cards and proof paths available.

Acceptance Scenarios:

1. Given no dominant guidance candidate exists, When the dashboard renders, Then the top guidance shows a calm No urgent operator action state and an honest next step such as reviewing the environment.
2. Given the no-action state is shown, When the rest of the page renders, Then readiness dimensions, proof items, and supporting cards remain visible and useful.
3. Given the page is in a calm state, When the operator scans the dashboard, Then the page does not promote several equal-weight actions or warnings above the top guidance.

Functional Requirements

• FR-352-001: The Environment Dashboard MUST expose one explicit top-level operator guidance case.
• FR-352-002: The top guidance case MUST include status, reason, impact, one primary action, and optional secondary links.
• FR-352-003: The top guidance case MUST remain environment-scoped and must not depend on hidden shell context.
• FR-352-004: Guidance selection MUST derive only from repo-backed current dashboard signals and existing linked owner surfaces.
• FR-352-005: The implementation MUST reuse current EnvironmentDashboardSummaryBuilder inputs and existing proof/action helpers where possible.
• FR-352-006: The dashboard MAY consume a review-output ResolutionCase or mapped action from the current Spec 350/351 path when it is environment-scoped and repo-real.
• FR-352-007: Provider-readiness blockers SHOULD outrank lower-priority dashboard candidates when the current required-permissions/runtime truth supports that ordering.
• FR-352-008: Current dashboard recommendedActions, readiness dimensions, proof items, and supporting signals MUST remain available as secondary context unless explicitly superseded by a narrower improvement.
• FR-352-009: The top guidance area MUST keep exactly one dominant primary action.
• FR-352-010: Secondary links MUST not compete visually with the primary action.
• FR-352-011: If no primary action is safe or repo-real, the dashboard MUST render an honest fallback such as review details or proof review.
• FR-352-012: The dashboard MUST not introduce direct new mutations such as publish, refresh evidence, run verification, or restore from the top guidance area unless those actions are already source-owned, safe, and explicitly kept in-scope.
• FR-352-013: Existing high-impact or destructive actions MUST remain source-owned and continue to rely on their existing confirmation, authorization, audit, and test paths.
• FR-352-014: A productized No urgent operator action state MUST exist for environments without a dominant guidance candidate.
• FR-352-015: The implementation MUST not remove useful current dashboard proof cards, readiness dimensions, or secondary drilldowns.
• FR-352-016: Links generated by the guidance case MUST remain authorization-aware and environment-scoped.
• FR-352-017: The dashboard MUST not invent a new provider/governance/backup/review adapter family unless repo truth proves one is strictly necessary for this page-local follow-up.
• FR-352-018: Focused Unit, Feature, and Browser coverage MUST prove selection, rendering, scope, and no-action behavior.

Non-Functional Requirements

• NFR-352-001: The page must remain DB-only during render; no Graph/provider API calls are allowed.
• NFR-352-002: No migrations, seeders, packages, env vars, queue families, scheduler changes, storage changes, or deployment asset changes are expected.
• NFR-352-003: Filament v5 and Livewire v4.0+ compliance MUST be preserved.
• NFR-352-004: Panel provider registration remains apps/platform/bootstrap/providers.php; no provider registration change is expected.
• NFR-352-005: No globally searchable resource is added or changed by this spec.
• NFR-352-006: Guidance selection must be deterministic and testable from the existing summary inputs.
• NFR-352-007: The dashboard must stay calm and decision-first; diagnostics and detailed proof remain secondary.
• NFR-352-008: Browser smoke screenshots must be captured under the Spec 352 artifacts path when generated.

Success Criteria

• Operators can identify one clear first action from the Environment Dashboard without scanning multiple equal-weight cards.
• Provider, review-output, evidence, and operation-follow-up scenarios produce repo-backed dominant guidance or honest fallback behavior.
• A calm environment still shows a productized no-action state instead of an empty or noisy top area.

Repo Truth / Data Requirements

• Current dashboard truth already includes:
  • recommendedActions
  • readinessDecision
  • governanceStatus
  • readinessCards
  • readinessDimensions
  • readinessProofPanel
• The current recommendedActions() ranking in EnvironmentDashboardSummaryBuilder already includes provider permissions, findings, operations attention, risk exceptions, recovery posture, and ongoing review follow-up; Spec 352 must document and tighten, not invent, the next-step model.
• No dedicated dashboard operatorGuidance or dashboardGuidanceCase payload exists today.
• ReviewPackOutputResolutionAdapter exists today, but the dashboard does not currently consume it.
• If a visible guidance candidate lacks a safe target, authorization path, or current-release truth, it MUST become unavailable or fall back honestly rather than being invented.

Out Of Scope

• Rebuilding Environment Dashboard from scratch.
• Reopening Baseline Compare productization.
• Replacing Governance Inbox, Customer Review Workspace, Evidence Overview, or Required Permissions with dashboard-local workflow.
• New provider-readiness, backup/restore, or governance adapter families unless strict page-local proof makes one unavoidable.
• New persistence, workflow engines, customer portal, PDF/HTML renderer, PSA/ITSM handoff, or AI.
• New route architecture, navigation model, or shell/context rewrite.

Risks

• Risk 1 - Duplicate Spec 330 instead of following it up: mitigate by reusing the existing dashboard layout and touching only the dominant guidance contract and its immediate rendering.
• Risk 2 - Hide Spec 351 residual issues behind the dashboard: mitigate by consuming only repo-real action semantics and documenting that unresolved Spec 351 browser observations remain out of scope.
• Risk 3 - Turn the dashboard into a second queue or console: mitigate by keeping one dominant action and routing into owner surfaces.
• Risk 4 - Introduce fake remediation: mitigate by navigation-first behavior and source-owned action safety rules only.

Assumptions

• Spec 330 remains the canonical implemented dashboard foundation.
• The current review-output resolution contract from Specs 350/351 is stable enough to be consumed as dashboard input where the action target is already repo-real.
• Current required-permissions and operation-proof links remain the canonical owner paths for provider and operation follow-up.

Acceptance Criteria

• Environment Dashboard shows one explicit top-level operator guidance case.
• One primary action is visually dominant.
• Secondary links are clearly subordinate.
• Guidance is derived from repo-backed dashboard/runtime truth only.
• Provider-readiness blockers outrank lower-priority candidates where repo truth supports the ordering.
• Review-output guidance can surface on the dashboard when a repo-real case/action exists.
• No fake direct mutation action is introduced in the dashboard guidance area.
• No urgent operator action renders as a calm productized state when no dominant case exists.
• Existing readiness dimensions, proof items, and supporting cards remain useful.
• The page stays environment-scoped and authorization-aware.
• No new persistence, workflow engine, or broad adapter rollout is introduced.
• Focused Unit, Feature, and Browser coverage is planned and sufficient for later implementation.