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
- [x] Existing page changed
- [ ] New page/route added
- [ ] Navigation changed
- [ ] Filament panel/provider surface changed
- [x] Existing modal/action presentation changed
- [ ] New table/form/state added
- [ ] Customer-facing surface changed
- [ ] Dangerous action changed
- [x] Status/evidence/review presentation changed
- [x] Workspace/environment context presentation changed

## UI/Productization Coverage *(mandatory when UI Surface Impact is not "No UI surface impact")*

| Route/page/surface | 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.