TenantAtlas/specs/373-diagnostic-surface-separation/spec.md

Feature Specification: Spec 373 - Diagnostic Surface Separation v1

Feature Branch: 373-diagnostic-surface-separation Created: 2026-06-12 Status: Draft Input: User-provided Spec 373 draft, Spec 368 Candidate D, Spec 370 Global Surface Information Architecture Contract, and completed Spec 371/372 artifacts.

Candidate Selection Summary

• Selected candidate: Diagnostic Surface Separation v1.
• Source: User-provided Spec 373 draft and specs/368-platform-ui-signal-to-noise-browser-audit/spec-candidates.md Candidate D.
• Why selected: Spec 368 identified two remaining diagnostic/configuration gaps after later productization work: Environment Diagnostics needs stronger guidance before raw diagnostic facts, and the blocked/system diagnostic surfaces need explicit handling instead of being silently treated as productized. Spec 370 explicitly deferred Diagnostic Surface Separation as a follow-up once the global surface contract existed.
• Roadmap relationship: Supports the roadmap's Product Scalability and Self-Service Foundation lane, especially supportability, provider readiness, guided diagnostics, and customer-safe separation of diagnostic/support detail.
• Smallest viable slice: Productize the existing Environment Diagnostics page and support-diagnostics modal/bundle default hierarchy so they answer what failed, why it matters, and what to check next before technical detail. Provider Connections and Required Permissions are regression/context surfaces only because Spec 353 already implemented their readiness-guidance slice.
• Deferred close alternatives:
  • Provider Connections readiness productization: completed by Spec 353; use as regression context only.
  • Required Permissions readiness productization: completed by Spec 353; use as regression context only.
  • System panel auth/fixture reachability: deferred; do not fix /system auth or fixture coverage in this spec.
  • OperationRun detail metadata/proof separation: covered by earlier OperationRun specs; do not reopen in this slice.
  • UI Bloat Regression Guard v1: recommended follow-up after this consumer spec.
• Completed-spec guardrail result:
  • Spec 353 has implementation status, checked implementation tasks, browser-oriented coverage, and UI reports for Provider Connections and Required Permissions. It is treated as completed historical context and is not rewritten.
  • Specs 371 and 372 have implementation/browser validation artifacts and are treated as completed context only.
  • Spec 370 is the completed preparation contract consumed by this package.
  • Spec 368 is an audit/source artifact and is not modified.

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

• Problem: Diagnostic and support surfaces still risk starting with sparse technical facts, repair-action labels, raw context, or generic "all good" language instead of clear diagnostic guidance.
• Today's failure: On Environment Diagnostics, operators see a small technical page that says configuration issues exist, but it does not consistently lead with the failed condition, impact, recommended next check, and related provider/permission/operation context. Support diagnostics has good redaction and context foundations, but its default modal still needs a stronger "what to check first" hierarchy.
• User-visible improvement: Operators and support users can open diagnostic surfaces and understand the primary blocker or no-action state in the first viewport, while raw/provider/debug detail remains available only after the guided summary.
• Smallest enterprise-capable version: Update only existing diagnostic/support UI presentation over existing stored truth. Preserve current RBAC, destructive repair actions, provider/permission logic, OperationRun links, and support-diagnostics redaction. Add focused tests, browser smoke, and spec-local implementation artifacts during the later implementation step.
• Explicit non-goals: No ProviderGateway changes, no permission calculation changes, no Provider Connections or Required Permissions reimplementation, no /system auth/fixture repair, no OperationRun logic changes, no new provider connectors, no migrations, no new data models, no new provider-health engine, no new support/PSA workflow, no AI/automation feature, and no broad UI framework.
• Permanent complexity imported: Focused feature/browser tests, spec-local audit artifacts, and possibly page-local derived view data for Environment Diagnostics only if existing direct booleans are insufficient. No new persisted truth, enum/status family, provider framework, cross-domain UI taxonomy, or queue family is expected.
• Why now: Specs 370, 371, 372, and 353 have already handled the global contract, operator backup surfaces, customer/auditor surfaces, and provider-readiness destinations. The remaining diagnostic surface gap is now narrow enough to prepare without reopening completed work.
• Why not local: A copy-only change would not prove diagnostic hierarchy, repair-action safety, support/raw separation, browser reachability, and completed-spec boundaries together. A broad diagnostic framework would overbuild. The narrow correct slice is a bounded diagnostic UI separation pass.
• Approval class: Workflow Compression.
• Red flags triggered: Multiple diagnostic/support surfaces and a "surface separation" theme. Defense: scope is narrowed to existing surfaces, no new runtime framework or persistence is introduced, and completed provider/customer/operator specs are explicitly excluded from rework.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve.

Spec Scope Fields (mandatory)

• Scope: environment-bound diagnostics plus workspace/environment support-diagnostic modal context.
• Primary Routes / Surfaces:
  • /admin/workspaces/{workspace}/environments/{environment}/diagnostics
  • openSupportDiagnostics action/modal on existing environment and operation surfaces when already available
  • Provider Connections and Required Permissions only as completed Spec 353 regression/context surfaces
• Data Ownership: No data ownership change. ManagedEnvironment remains the environment context. Diagnostics continue to read existing ManagedEnvironmentDiagnosticsService, SupportDiagnosticBundleBuilder, ProviderConnection, OperationRun, Finding, StoredReport, EnvironmentReview, ReviewPack, and AuditLog truth.
• RBAC:
  • Environment Diagnostics remains workspace + environment scoped.
  • Non-members or non-entitled actors remain deny-as-not-found where route/context ownership applies.
  • Existing repair actions remain capability-gated with TENANT_MANAGE, destructive styling, confirmation, and server-side authorization through current services.
  • Support diagnostics remains capability-gated through existing support-diagnostics policies/actions.

For canonical or mixed context surfaces:

• Default filter behavior when tenant-context is active: N/A. Environment Diagnostics is route-environment scoped; support diagnostics is opened from an already authorized environment or operation context.
• Explicit entitlement checks preventing cross-tenant leakage: Existing route model binding, workspace membership, environment entitlement, and support diagnostics authorization must remain authoritative. This spec must not add query-string shortcuts or hidden remembered-environment scope.

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
• Existing modal/action presentation changed
• 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	Page archetype	Design depth	Repo-truth level	Existing pattern reused	Screenshot/page audit need	Customer/dangerous review
Environment Diagnostics (UI-012)	Support / Diagnostics, Provider / Integration	Domain Pattern Surface	repo-verified + Spec 368 browser-verified before screenshot	Spec 370 diagnostic contract, Spec 353 readiness guidance, current Filament page/action patterns	after screenshot required; update docs/ui-ux-enterprise-audit/route-inventory.md and create/update page report only if implementation changes registry status	internal/support only; existing destructive repair actions must retain confirmation, authorization, and audit ownership
Support diagnostics modal/bundle	Support / Diagnostics modal	Domain Pattern Surface	repo-verified action/modal and feature tests	SupportDiagnosticBundleBuilder, contextual help, redaction integrity, OperationRun links	browser/modal screenshot required if reachable in existing fixture; otherwise document blocked	support-only; raw/support data remains redacted and capability-gated
Provider Connections (UI-009)	Provider / Integration	Strategic Surface	completed Spec 353 context	Spec 353 readiness guidance	no new screenshot required unless shared changes regress it	preserve completed action safety
Required Permissions (UI-077)	Provider / Integration	Domain Pattern Surface	completed Spec 353 context	Spec 353 readiness guidance	no new screenshot required unless shared changes regress it	no new permission/consent behavior

Coverage files to review during implementation:

• docs/ui-ux-enterprise-audit/route-inventory.md
• docs/ui-ux-enterprise-audit/design-coverage-matrix.md only if classification/counts change
• docs/ui-ux-enterprise-audit/page-reports/ui-012-environment-diagnostics.md if absent or stale after implementation
• docs/ui-ux-enterprise-audit/unresolved-pages.md only if a scoped route/modal remains unreachable

Cross-Cutting / Shared Pattern Reuse

• Cross-cutting feature?: yes.
• Interaction class(es): diagnostics summary, support diagnostics modal, status messaging, action links, technical-details disclosure, provider/permission/operation/evidence links.
• Systems touched: EnvironmentDiagnostics, environment-diagnostics.blade.php, SupportDiagnosticBundleBuilder, support-diagnostic-bundle.blade.php, ManagedEnvironmentLinks, OperationRunLinks, ProviderReasonTranslator, ContextualHelpResolver, current support-diagnostics actions/tests, and UI audit artifacts.
• Existing pattern(s) to extend: Spec 370 diagnostic contract, Spec 353 provider-readiness hierarchy, existing support diagnostics redaction/contextual-help pattern, current Filament action confirmation/RBAC helpers.
• Shared contract / presenter / builder / renderer to reuse: SupportDiagnosticBundleBuilder, RedactionIntegrity, ContextualHelpResolver, ManagedEnvironmentLinks, OperationRunLinks, and existing action-surface declarations before adding any helper.
• Why the existing shared path is sufficient or insufficient: Existing support diagnostics and provider-readiness paths already provide most needed truth. The gap is Environment Diagnostics first-viewport hierarchy and modal ordering, not a missing data model or resolver.
• Allowed deviation and why: A page-local Environment Diagnostics view model is allowed only if it replaces duplicated Blade conditionals and stays derived from existing booleans. No generic diagnostic framework is allowed.
• Consistency impact: "what failed", "impact", "recommended next check", "related context", and "technical details" language must align across diagnostics and support modal surfaces without creating a parallel provider readiness vocabulary.
• Review focus: Confirm no completed Spec 353 surface is reopened, no raw provider payloads/secrets become default-visible, and no local action bypasses existing RBAC/audit patterns.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: No new OperationRun start/completion behavior. Existing support diagnostics may link to OperationRun proof.
• Shared OperationRun UX contract/layer reused: Existing OperationRunLinks and current OperationRun detail/navigation paths only.
• Delegated start/completion UX behaviors: N/A.
• Local surface-owned behavior that remains: Displaying a related operation link as diagnostic context when the existing bundle or page already has a repo-backed operation.
• Queued DB-notification policy: unchanged.
• Terminal notification path: unchanged.
• Exception required?: none.

Provider Boundary / Platform Core Check

• Shared provider/platform boundary touched?: yes, presentation only.
• Boundary classification: mixed. Environment Diagnostics is platform/environment owned; provider and Microsoft permission facts remain provider-owned detail.
• Seams affected: provider connection references, permission references, repair-action copy, support diagnostic dominant issue copy, technical details disclosure.
• Neutral platform terms preserved or introduced: provider connection, required permissions, operation, evidence, diagnostics, support context, managed environment.
• Provider-specific semantics retained and why: Microsoft Graph permission names, provider error reason codes, and external tenant/provider identifiers may remain in technical details or required-permission destinations because they are real provider-owned diagnostics.
• Why this does not deepen provider coupling accidentally: Primary copy uses provider-neutral "provider connection", "required access", "permission", and "operation" terms. Provider-specific values are not promoted to platform-core truth or new status families.
• Follow-up path: deeper provider-health engine or provider-specific onboarding redesign remains a follow-up spec, not part of Spec 373.

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
Environment Diagnostics first viewport	yes	Filament page + Blade content	diagnostics summary, destructive repair-action context	page/view derived state	no	Existing route only
Support diagnostics modal ordering	yes	Filament action modal + Blade content	support diagnostics, redaction, contextual help	modal/view derived state	no	Existing actions only
Provider Connections / Required Permissions	no primary change planned	Native Filament/resource/page	completed readiness guidance	regression context only	no	Spec 353 completed; do not rework

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
Environment Diagnostics	Tertiary Evidence / Diagnostics Surface	Diagnose missing owner, duplicate membership, provider/permission link, or no-action state after an environment issue is suspected	diagnostic outcome, failed condition, impact, recommended next check/action, related provider/permission/operation link if repo-backed	repair context, raw identifiers, audit/support detail, technical details	Tertiary because it supports troubleshooting after a primary operator surface points to a problem	follows contextual environment troubleshooting	removes translation from "All good" or isolated repair cards
Support diagnostics modal	Tertiary Evidence / Diagnostics Surface	Support user decides what context to inspect first before opening raw references	dominant issue, likely area when repo-backed, impact, recommended next check, redaction/completeness note	references, raw/support notes, redaction markers, audit history	Tertiary because it explains selected tenant/run context for support	follows support investigation workflow	reduces raw-section scanning before first support action

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
Environment Diagnostics	operator-MSP, support-platform	current diagnostic outcome, failed condition, impact, recommended next check	missing owner, duplicate membership, provider/permission/operation links, existing repair affordances	raw IDs and detailed repair context only if added under Technical Details	bootstrap owner, merge duplicate scopes, open required permissions, open provider connection, or no action required depending on state	no raw provider payloads/secrets; repair actions remain capability-gated	one top diagnostic summary owns state; cards below add proof/action only
Support diagnostics modal	support-platform, operator-MSP with capability	headline, dominant issue, freshness/completeness/redaction note, recommended first check	provider connection, operation context, findings, reports, review pack, audit sections	references and redaction markers in lower sections	open the most relevant existing reference when available	modal/action remains capability-gated; redaction stays default	summary states dominant issue once; sections add evidence instead of repeating it

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
Environment Diagnostics	Utility / Diagnostic	Singleton diagnostic page	resolve the visible diagnostic blocker or open related provider/permission context	same page; contextual action/link	forbidden	secondary links/details below summary	existing destructive repair actions remain header actions with confirmation/capability gating	N/A	/admin/workspaces/{workspace}/environments/{environment}/diagnostics	workspace + managed environment	Environment diagnostics	what failed, impact, next check	diagnostic singleton exemption remains valid
Support diagnostics modal	Utility / Support	Support diagnostic modal	inspect the first related context or copy support-safe summary	modal content plus existing reference links	forbidden	references inside lower sections	none added	source page/action	source page/action	workspace + environment/run context	Support diagnostics	dominant issue, freshness, redaction, first check	support modal exemption remains valid

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
Environment Diagnostics	TenantPilot operator or support user	Decide which environment diagnostic blocker to resolve or whether no action is required	Tertiary diagnostics	What failed in this environment, why does it matter, and what should I check next?	outcome, failed condition, impact, next check, safe related links	raw IDs, internal repair context, exact timestamps if later added	diagnostic readiness, membership consistency, supportability	existing TenantPilot-only membership repair actions	Bootstrap owner, Merge duplicate access scopes, or related navigation depending on state	existing repair actions only, confirmation and capability gated
Support diagnostics modal	Support user	Decide what context to inspect first in a redacted support bundle	Tertiary support diagnostics	What should support check first, and what context is available?	dominant issue, freshness, completeness, redaction, first related context	detailed references, audit history, redaction markers	availability, freshness, completeness, redaction mode	read-only support inspection	open existing related context if available	none

Proportionality Review

• New source of truth?: no.
• New persisted entity/table/artifact?: no domain persistence. Spec-local implementation artifacts are expected during implementation only.
• New abstraction?: no generic abstraction planned. A page-local derived summary helper is allowed only if it replaces duplicated view conditionals.
• New enum/state/reason family?: no.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: The current diagnostic page and support modal do not consistently lead with the troubleshooting answer before technical/support detail.
• Existing structure is insufficient because: Existing booleans and bundle arrays provide facts, but the presentation does not always compose them into one guided diagnostic case with impact and next action.
• Narrowest correct implementation: Reorder and clarify the existing Environment Diagnostics view and support diagnostics modal over existing truth, with focused tests/browser evidence.
• Ownership cost: Focused tests, browser smoke, and spec-local artifacts. No new service family, persistence, or provider engine.
• Alternative intentionally rejected: Reusing Spec 353's provider-readiness adapter as a generic diagnostic engine, or building a new diagnostic framework. Both are broader than the current release needs.
• Release truth: current-release UI productization over existing diagnostic/support truth.

Compatibility posture

This feature assumes the repo's pre-production posture. It introduces no migration, compatibility shim, legacy alias, or backfill.

Testing / Lane / Runtime Impact

• Test purpose / classification: Feature/Livewire for Environment Diagnostics and support diagnostics modal rendering; Unit/Feature only where derived summary helpers are added; Browser for first-viewport hierarchy and modal reachability.
• Validation lane(s): confidence + browser + static diff/format checks.
• Why this classification and these lanes are sufficient: The change is UI hierarchy over existing DB-backed truth. Feature/Livewire tests prove rendered state and action safety; Browser smoke proves visual hierarchy, collapsed/support detail, and no console/runtime failures.
• New or expanded test families: one bounded Spec 373 feature/browser family only if no existing diagnostic tests can be extended cleanly.
• Fixture / helper cost impact: Reuse existing workspace/environment/member/provider/support diagnostics factories and smoke-login fixture. Do not widen global browser setup.
• Heavy-family visibility / justification: Browser coverage is explicit because the source issue is browser-verified UI signal-to-noise.
• Special surface test profile: shared-detail-family for support modal; standard-native-filament for Environment Diagnostics page action safety.
• Standard-native relief or required special coverage: Environment Diagnostics uses existing Filament page/action patterns; special proof is only first-viewport hierarchy and repair-action preservation.
• Reviewer handoff: Verify completed Spec 353 boundaries, no raw/default provider payload exposure, support diagnostics redaction, destructive action confirmation/RBAC/audit, and screenshot/report artifacts.
• Budget / baseline / trend impact: none expected beyond one bounded browser smoke.
• Escalation needed: document-in-feature for contained fixture gaps; follow-up-spec for /system fixture/auth, durable bloat guard, or broad support-diagnostics workflow changes.
• Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
• Planned validation commands:
  • git diff --check
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=EnvironmentDiagnostics
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=SupportDiagnostics
  • cd apps/platform && ./vendor/bin/sail pint --dirty if PHP files change
  • bounded browser smoke for Environment Diagnostics and support diagnostics modal if UI changes are implemented

User Scenarios & Testing (mandatory)

User Story 1 - Diagnose Environment Blockers First (Priority: P1)

An operator opens Environment Diagnostics and immediately sees the current diagnostic outcome, what failed, why it matters, and what to check or repair next.

Why this priority: Environment Diagnostics is the remaining browser-verified diagnostic page from Spec 368 that still needs stronger guidance first.

Independent Test: Render the page with missing owner, duplicate memberships, both blockers, and no blocker states. Each state must show one top diagnostic summary before technical/support detail, the both-blocker state must expose one dominant next action with any second repair/context path demoted, and existing repair actions must remain preserved.

Acceptance Scenarios:

1. Given an environment has no owner, When an authorized operator opens Environment Diagnostics, Then the first viewport states the missing-owner blocker, impact, and next check/action before lower detail.
2. Given the current user has duplicate membership rows, When the page renders, Then duplicate membership is framed as a supportability/access-scope issue with the existing merge action preserved.
3. Given no known diagnostic issue exists, When the page renders, Then one calm no-action summary appears without zero-card spam or false-positive calmness.

User Story 2 - Open Support Diagnostics With Guided First Check (Priority: P2)

A support user opens support diagnostics from an existing tenant or OperationRun surface and sees the dominant issue, likely area when repo-backed, redaction state, and recommended first context before raw references.

Why this priority: Support diagnostics is repo-real and audit/redaction-sensitive; it should help support users start with the right context without leaking raw data or making raw sections the default path.

Independent Test: Mount the existing support diagnostics action/modal for tenant and OperationRun contexts. Verify the modal summary precedes reference sections, redaction note is visible, and raw/support markers remain lower-priority.

Acceptance Scenarios:

1. Given a tenant has a provider connection blocker, When support diagnostics opens, Then the modal leads with the provider/support issue and a relevant first context.
2. Given an OperationRun failed or was blocked, When support diagnostics opens, Then the modal leads with the run issue and keeps audit/references secondary.
3. Given an entitled user lacks support diagnostics capability, When the action is rendered or invoked, Then existing disabled/403 behavior remains unchanged.

User Story 3 - Preserve Completed Provider Readiness Surfaces (Priority: P3)

An implementer uses Provider Connections and Required Permissions as completed Spec 353 regression/context surfaces and does not rework them unless a shared helper change creates a confirmed regression.

Why this priority: The user draft named these surfaces, but repo truth says Spec 353 already completed their provider-readiness guidance. Reopening them would violate the completed-spec guardrail.

Independent Test: Review the final diff and browser/source audit artifacts. Provider Connections and Required Permissions should appear only as context/regression checks unless a bounded shared-change side effect is documented.

Acceptance Scenarios:

1. Given Spec 353 artifacts exist, When Spec 373 implementation starts, Then Provider Connections and Required Permissions are treated as completed context.
2. Given implementation touches a shared diagnostic/support component used by Spec 353 surfaces, When validation runs, Then targeted regression proof is recorded or the change is narrowed.

Edge Cases

• Both Environment Diagnostics blockers can be true at once; the summary must not hide either blocker, must expose one dominant next action for the first viewport, and must demote the second repair/context path instead of creating two competing primary actions.
• The support diagnostics bundle may have no provider connection, no OperationRun, or no findings; the modal must show an honest completeness/no-action statement instead of implying unavailable proof exists.
• Required Permissions and System panel may be unreachable in a given browser fixture; document blocked status and do not fix auth/routing inside this spec.
• Provider-specific reason codes may not translate; show neutral "recommended next check" language instead of unsupported likely cause.
• Technical terms may be necessary in support sections, but not as the first answer for operator diagnostics.

Requirements (mandatory)

Functional Requirements

• FR-373-001: Environment Diagnostics MUST show a single first-viewport diagnostic summary before individual blocker cards or technical detail.
• FR-373-002: The Environment Diagnostics summary MUST state the current diagnostic outcome, failed condition(s), operator impact, and recommended next check/action for each repo-backed state while exposing only one dominant next action in the first viewport.
• FR-373-003: Missing-owner and duplicate-membership states MUST remain visible and actionable; the implementation MUST NOT hide real blockers behind calm or healthy copy.
• FR-373-004: Existing Environment Diagnostics repair actions MUST retain ->action(...), ->requiresConfirmation(), destructive/action styling, capability gating, server-side authorization, and audit ownership.
• FR-373-005: The no-issue Environment Diagnostics state MUST show one calm no-action message and MUST NOT show repeated zero metrics or unsupported "healthy" claims.
• FR-373-006: Related provider, required-permission, operation, or evidence links MAY be shown only when repo-backed by existing helpers or bundle data; unavailable or non-repo-backed context MUST render as unavailable/support text rather than a fake link.
• FR-373-007: Support diagnostics modal/bundle presentation MUST lead with the support outcome, dominant issue, freshness/completeness/redaction state, and recommended first check before lower reference sections.
• FR-373-008: Support diagnostics MUST keep redaction markers, audit references, raw/provider/support details, and technical context secondary, collapsed, or lower-priority by default.
• FR-373-009: The feature MUST preserve existing support diagnostics authorization, telemetry, audit, and redaction behavior.
• FR-373-010: Provider Connections and Required Permissions MUST NOT be reimplemented by this spec; they are completed Spec 353 context unless a shared helper change creates a documented regression.
• FR-373-011: Required Permissions and System panel reachability gaps MUST be documented if observed; this spec MUST NOT fix broad auth/routing or system-panel fixture coverage.
• FR-373-012: The implementation MUST NOT change provider health resolution, permission calculation, ProviderGateway behavior, OperationRun lifecycle behavior, Graph contracts, provider credentials, or persisted diagnostic truth.
• FR-373-013: Likely cause language MUST be shown only when repo-backed by existing reason translation, provider reason, OperationRun failure summary, or stored diagnostic truth; otherwise the copy MUST use neutral recommended-next-check language without inventing a likely cause.
• FR-373-014: Spec-local implementation artifacts MUST document source audit, affected files, diagnostic contracts, screenshot index, implementation notes, browser verification, diagnostic safety checklist, and validation results.

Non-Functional Requirements

• NFR-373-001: Render paths MUST remain DB-local and MUST NOT introduce Microsoft Graph or provider HTTP calls during page render or modal render.
• NFR-373-002: No migration, new table, new persisted projection, enum/status family, provider framework, queue family, scheduler change, storage change, package, or environment variable is planned.
• NFR-373-003: Filament v5 and Livewire v4 compatibility MUST be preserved. No Livewire v3 or Filament v3/v4 APIs are allowed.
• NFR-373-004: Panel provider registration MUST remain in apps/platform/bootstrap/providers.php; this spec must not move provider registration.
• NFR-373-005: ProviderConnectionResource global search remains disabled; no globally searchable resource is added or changed unless the implementation updates the spec first.
• NFR-373-006: No new Filament asset registration is expected. If an implementation unexpectedly registers assets, deployment notes must include cd apps/platform && php artisan filament:assets.
• NFR-373-007: Browser proof must use the existing smoke-login/browser harness where available; do not invent a new auth flow.

UI Action Matrix (mandatory when Filament is changed)

Surface	Location	Header Actions	Inspect Affordance	Row Actions	Bulk Actions	Empty-State CTA(s)	View/Header Actions	Audit log?	Notes / Exemptions
Environment Diagnostics	apps/platform/app/Filament/Pages/EnvironmentDiagnostics.php and apps/platform/resources/views/filament/pages/environment-diagnostics.blade.php	Existing Bootstrap owner, Merge duplicate access scopes only when applicable	singleton page; same-route context	none	none	no list empty state; no-action summary when clean	existing repair actions only	existing service audit ownership must be preserved/verified	destructive repair actions require confirmation, TENANT_MANAGE, and server-side enforcement
Support diagnostics modal	apps/platform/resources/views/filament/modals/support-diagnostic-bundle.blade.php and existing action hosts	Existing openSupportDiagnostics action on host pages/resources only	modal references link to existing authorized targets	none	none	unavailable references render as unavailable, not fake links	no new mutation	existing support diagnostics audit/telemetry preserved	read-only support modal, capability-gated

Key Entities (include if feature involves data)

• Environment diagnostic case: derived page presentation over existing missing-owner and duplicate-membership facts.
• Support diagnostic bundle: existing redacted bundle with context, summary, sections, redaction markers, and notes.
• Related diagnostic reference: existing provider, permission, operation, evidence, review, report, or audit context link when repo-backed.

Success Criteria (mandatory)

Measurable Outcomes

• SC-373-001: Environment Diagnostics reaches a browser-reviewed target of at least 4.0 using the Spec 368 score model, or a documented blocker explains the remaining gap.
• SC-373-002: Environment Diagnostics feature/browser proof covers missing owner, duplicate memberships, both blockers, and no-action states.
• SC-373-003: Support diagnostics feature/browser proof covers tenant and OperationRun contexts where existing fixtures make them reachable.
• SC-373-004: Default-visible diagnostic/support content includes what failed, impact, and next check/action, while raw/provider/debug detail remains secondary.
• SC-373-005: Provider Connections and Required Permissions remain aligned with Spec 353 and are not reopened except for documented regression checks.
• SC-373-006: git diff --check passes; targeted tests and browser smoke pass or limitations are documented.
• SC-373-007: Final implementation artifacts include source audit, affected files, diagnostic contracts, screenshot index, implementation notes, browser report, safety checklist, and validation report.

Risks

• Hiding useful diagnostic data: Mitigate by demoting technical detail, not deleting it, and keeping support/reference sections accessible.
• Inventing likely causes: Mitigate by using likely-cause language only when backed by existing reason translation or stored failure/diagnostic truth.
• Reopening completed specs: Mitigate by treating Spec 353, 371, and 372 as context/regression only.
• Destructive repair-action drift: Mitigate by verifying confirmation, capability gating, server-side authorization, and audit ownership before changing presentation.
• Fixture gaps: Mitigate by documenting blocked pages/routes and recommending Browser Audit Fixture Coverage instead of fixing auth/routing here.

Assumptions

• Spec 353 is completed enough to exclude Provider Connections and Required Permissions from primary Spec 373 implementation.
• Existing smoke-login/browser harness can reach Environment Diagnostics and at least one support diagnostics modal; if not, the implementation documents the blocker.
• Support diagnostics remains a modal/action surface, not a new standalone page.
• No new provider or permission truth is needed to productize the first viewport.

Open Questions

None blocking preparation. During implementation, verify exact browser reachability for Environment Diagnostics and support diagnostics modal using current fixtures.

Follow-up Spec Candidates

• Spec 374 - UI Bloat Regression Guard v1.
• Browser Audit Fixture Coverage for /system, Required Permissions fallback contexts, and any support diagnostics route/modal that remains unreachable.
• Secondary-action density cleanup for Provider Connections if Spec 353 follow-up review still finds action overload.