TenantAtlas/specs/374-diagnostic-entry-point-support-diagnostics-consolidation/plan.md

# Implementation Plan: Spec 374 - Diagnostic Entry Point and Support Diagnostics Consolidation v1

**Branch**: `374-diagnostic-entry-point-support-diagnostics-consolidation` | **Date**: 2026-06-12 | **Spec**: `specs/374-diagnostic-entry-point-support-diagnostics-consolidation/spec.md`
**Input**: User-provided Spec 374 draft, completed Spec 373 artifacts, Spec 370 IA contract, and current repo routes/surfaces.

## Summary

Productize the official environment diagnostics entrypoint decision without building a diagnostic hub.

The implementation should make these product truths explicit:

- Environment Dashboard remains the primary operator starting point.
- Support Diagnostics modal is the official quick diagnostics/support context entry.
- Environment Diagnostics is a secondary repair diagnostics page/deeplink for supported membership/access repair cases.
- Provider/Permission Diagnostics, System Diagnostics, Evidence questions, and Customer Review evidence stay in their existing or future owned surfaces.

The work is presentation, discoverability, and documentation over existing routes/actions. It must not add new diagnostic backend checks, Graph calls, provider logic, migrations, navigation trees, OperationRun behavior, or customer/auditor changes.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12.52
**Primary Dependencies**: Filament v5.2.1, Livewire v4.1.4, Pest v4.3.1, Laravel Sail
**Storage**: PostgreSQL; no schema change planned
**Testing**: Pest Feature/Livewire plus bounded Browser smoke
**Validation Lanes**: confidence + browser + static diff/format checks
**Target Platform**: Laravel monolith under `apps/platform`
**Project Type**: web application
**Performance Goals**: DB-local render; no provider/Graph calls during page or modal render
**Constraints**: no new persistence, no new provider/permission/system/evidence runtime logic, no new navigation hub, no panel provider/global-search changes
**Scale/Scope**: one environment dashboard action area, one support diagnostics modal, one repair diagnostics page, and spec-local artifacts

## Current Repo Truth That Constrains The Slice

- `apps/platform/routes/web.php` defines:
  - `/admin/workspaces/{workspace}/environments/{environment:slug}` -> `EnvironmentDashboard`
  - `/admin/workspaces/{workspace}/environments/{environment:slug}/diagnostics` -> `EnvironmentDiagnostics`
- `EnvironmentDiagnostics` has `protected static bool $shouldRegisterNavigation = false`.
- `EnvironmentDiagnostics` currently has existing repair actions:
  - `bootstrapOwner`
  - `mergeDuplicateMemberships`
- The repair actions already use `Action::make(...)->action(...)`, `->requiresConfirmation()`, `UiEnforcement`, `Capabilities::TENANT_MANAGE`, and service-owned repair methods.
- `ManagedEnvironmentDiagnosticsService::tenantHasNoOwners()` currently returns `false`; missing-owner repair is an existing presentation/test seam, not repo-active detection. Spec 374 must not add missing-owner detection or owner-recovery logic.
- `environment-diagnostics.blade.php` already uses a first-viewport summary from Spec 373, but the page still reads as "Environment Diagnostics" rather than a clearly bounded repair diagnostics destination.
- `EnvironmentDashboard` already exposes `openSupportDiagnosticsAction()` from header/More actions.
- `support-diagnostic-bundle.blade.php` already presents recommended first check before lower support sections from Spec 373.
- `ManagedEnvironmentLinks::diagnosticsUrl()` exists; current preparation search found only its method definition. Implementation must re-run usage search before deciding whether to keep it as deeplink utility or adopt it for one secondary link.
- `ActionSurfaceExemptions` and `EnvironmentDiagnostics::actionSurfaceDeclaration()` currently use ManagedEnvironment diagnostics terminology; if runtime copy adopts Repair Diagnostics as the canonical page noun, those metadata paths must be audited for consistency.
- No `specs/374-*` package existed before this preparation.

## Source Inputs

Required implementation reads:

- `specs/374-diagnostic-entry-point-support-diagnostics-consolidation/spec.md`
- `specs/374-diagnostic-entry-point-support-diagnostics-consolidation/plan.md`
- `specs/374-diagnostic-entry-point-support-diagnostics-consolidation/tasks.md`
- `specs/373-diagnostic-surface-separation/spec.md`
- `specs/373-diagnostic-surface-separation/plan.md`
- `specs/373-diagnostic-surface-separation/tasks.md`
- `specs/373-diagnostic-surface-separation/artifacts/source-audit-summary.md`
- `specs/373-diagnostic-surface-separation/artifacts/diagnostic-surface-contracts.md`
- `specs/373-diagnostic-surface-separation/artifacts/browser-verification-report.md`
- `specs/373-diagnostic-surface-separation/artifacts/validation-report.md`
- `specs/370-global-surface-information-architecture-contract/artifacts/surface-contract.md`
- `specs/370-global-surface-information-architecture-contract/artifacts/surface-type-matrix.md`
- `docs/ui-ux-enterprise-audit/page-reports/ui-002-environment-dashboard.md`
- `docs/ui-ux-enterprise-audit/page-reports/ui-012-environment-diagnostics.md`
- `docs/ui-ux-enterprise-audit/route-inventory.md`

## UI / Surface Guardrail Plan

- **Guardrail scope**: changed existing environment dashboard action, support diagnostics modal purpose/copy, and repair diagnostics page framing.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**:
  - `/admin/workspaces/{workspace}/environments/{environment}`
  - `openSupportDiagnostics` action/modal
  - `/admin/workspaces/{workspace}/environments/{environment}/diagnostics`
- **No-impact class, if applicable**: N/A.
- **Native vs custom classification summary**: native Filament page/action/modal with existing Blade content; do not create a custom diagnostic UI system.
- **Shared-family relevance**: diagnostics entrypoints, support diagnostic bundle, repair diagnostics, action links, status/no-action messaging.
- **State layers in scope**: page/action/modal presentation only.
- **Audience modes in scope**: operator-MSP and support-platform.
- **Decision/diagnostic/raw hierarchy plan**: dashboard entrypoint decision first; support diagnostics first check second; repair diagnostics only when appropriate; raw/support detail lower or gated.
- **Raw/support gating plan**: support diagnostics remains capability-gated and rendered as a redacted support view while retaining the internal `default_redacted` mode; repair diagnostics does not expose raw provider data.
- **One-primary-action / duplicate-truth control**: "Open support diagnostics" remains the primary quick diagnostics path; repair diagnostics is secondary and conditional if surfaced.
- **Handling modes by drift class or surface**:
  - Environment Dashboard: implementation target.
  - Support Diagnostics modal: implementation target for purpose/first-check clarity if current copy is insufficient.
  - Environment Diagnostics: implementation target for repair-only/no-action framing.
  - Provider/Permission/System/Evidence/Customer review diagnostics: report-only or follow-up-spec.
- **Repository-signal treatment**: completed Spec 373 is context, not a rewrite target.
- **Special surface test profiles**: `standard-native-filament`, `shared-detail-family`, and `exception-coded-surface` for partial repair-state browser fixtures.
- **Required tests or manual smoke**: Feature/Livewire plus browser smoke.
- **Exception path and spread control**: fixture gaps are documented in feature artifacts; do not create auth/seed infrastructure inside this spec.
- **Active feature PR close-out entry**: Guardrail / Smoke Coverage.
- **UI/Productization coverage decision**: update coverage artifacts only for changed Environment Dashboard, support diagnostics modal, or Environment Diagnostics evidence/status. Do not churn Provider Connections/Required Permissions reports.
- **Coverage artifacts to update**:
  - `docs/ui-ux-enterprise-audit/route-inventory.md` if screenshot/report references or classification materially change.
  - `docs/ui-ux-enterprise-audit/page-reports/ui-002-environment-dashboard.md` if dashboard action evidence changes.
  - `docs/ui-ux-enterprise-audit/page-reports/ui-012-environment-diagnostics.md` if page framing/evidence changes.
  - `docs/ui-ux-enterprise-audit/unresolved-pages.md` only for scoped blocked reachability.
- **Navigation / Filament provider-panel handling**: no panel provider change; do not register `/diagnostics` as a top-level navigation item.
- **Screenshot or page-report need**: yes for dashboard action/modal and direct repair diagnostics page if reachable; document blocked repair-state screenshots honestly.

## Shared Pattern And System Fit

- **Cross-cutting feature marker**: yes.
- **Systems touched**:
  - `App\Filament\Pages\EnvironmentDashboard`
  - `App\Filament\Pages\EnvironmentDiagnostics`
  - `App\Support\Ui\ActionSurface\ActionSurfaceExemptions` only if canonical action-surface terminology changes
  - `App\Support\ManagedEnvironmentLinks`
  - `App\Support\SupportDiagnostics\SupportDiagnosticBundleBuilder` only if existing bundle copy/data is insufficient
  - `apps/platform/resources/views/filament/modals/support-diagnostic-bundle.blade.php`
  - `apps/platform/resources/views/filament/pages/environment-diagnostics.blade.php`
  - focused feature/browser tests and spec-local artifacts
- **Shared abstractions reused**:
  - `SupportDiagnosticBundleBuilder`
  - `ManagedEnvironmentLinks`
  - `ActionSurfaceDeclaration` / `ActionSurfaceExemptions` metadata where existing surface terminology is material
  - `OperationRunLinks` for existing support context only
  - `UiEnforcement`
  - `Capabilities`
  - Filament native actions, modals, sections, badges, and links
- **New abstraction introduced? why?**: none planned. A page-local derived label/helper is allowed only if it maps existing repair/no-action state and replaces duplicated view conditionals.
- **Why the existing abstraction was sufficient or insufficient**: Existing route/action/bundle truth is sufficient; only product entrypoint semantics are missing.
- **Bounded deviation / spread control**: do not reuse provider-readiness guidance as a generic diagnostic engine; keep provider-specific checks out of Environment Diagnostics.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no.
- **Central contract reused**: existing `OperationRunLinks` only if support diagnostics bundle already includes operation context.
- **Delegated UX behaviors**: N/A.
- **Surface-owned behavior kept local**: entrypoint and reference presentation only.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception path**: none.

## Provider Boundary And Portability Fit

- **Shared provider/platform boundary touched?**: yes, presentation and destination mapping only.
- **Provider-owned seams**: provider connection readiness, Microsoft/Graph permission facts, provider-specific error/reason details.
- **Platform-core seams**: managed environment dashboard, support diagnostics entrypoint, repair diagnostics route, operation/evidence references.
- **Neutral platform terms / contracts preserved**: provider connection, required permissions, managed environment, operation, evidence, support diagnostics, repair diagnostics.
- **Retained provider-specific semantics and why**: provider-specific details stay in provider-owned destinations and lower support diagnostics sections where exact troubleshooting proof is necessary.
- **Bounded extraction or follow-up path**: provider/permission diagnostics productization remains a follow-up if needed.

## Constitution Check

*GATE: Must pass before implementation. Re-check after implementation if requirements change.*

- Inventory-first / snapshots-second: N/A; no inventory/snapshot truth changes.
- Read/write separation: no new write action. Existing repair actions must retain confirmation, authorization, and service/audit ownership.
- Graph contract path: no new Graph calls. Page/modal render remains DB-local.
- Deterministic capabilities: existing capability checks remain authoritative.
- RBAC-UX: workspace/environment entitlement and support diagnostics capability remain server-side truth.
- Workspace/Tenant isolation: no query-string context shortcuts or remembered-environment overrides.
- OperationRun observability: no new OperationRun type/start/completion.
- OperationRun start UX: N/A beyond existing links.
- Data minimization: no secrets, tokens, raw provider payloads, or unrestricted logs in default-visible content.
- Test governance: confidence + browser lanes are explicit and bounded.
- Proportionality: no new persisted truth, framework, enum/status family, or diagnostic hub.
- Shared pattern first: reuse existing diagnostic/support/action/link patterns.
- Provider boundary: provider readiness stays provider-owned and is not imported into repair diagnostics.
- UI-COV-001: reachable UI impact declared; coverage artifact handling is proportional.
- DECIDE-001 / DECIDE-AUD-001: dashboard stays decision/context, support/repair diagnostics stay tertiary, raw/support depth remains lower or gated.
- Filament v5 / Livewire v4: required; no legacy APIs.
- Panel provider registration: unchanged in `apps/platform/bootstrap/providers.php`.
- Global search: no resource global-search behavior changes.
- Destructive actions: existing Environment Diagnostics repair actions stay `->action(...)` + `->requiresConfirmation()` + capability-gated + server-authorized.
- Asset strategy: no new asset registration planned; no `filament:assets` deployment change expected.

## Test Governance Check

- **Test purpose / classification by changed surface**:
  - Environment Dashboard diagnostic entry: Feature/Livewire + Browser.
  - Support Diagnostics modal: Feature/Livewire + Browser.
  - Environment Diagnostics repair/no-action framing: Feature/Livewire + Browser.
  - Matrix/artifacts: static review.
- **Affected validation lanes**: confidence and browser.
- **Why this lane mix is the narrowest sufficient proof**: entrypoint clarity must be proven both in action state/rendered DOM and actual browser discoverability.
- **Narrowest proving commands**:
  - exact Spec 374 diagnostic-entry test file/filter if created; otherwise record why no `DiagnosticEntry` filter exists and run the concrete dashboard/support/repair tests that cover it
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDiagnosticsRepairsTest.php` or the exact replacement Spec 374 repair-diagnostics test file
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=SupportDiagnostics`
  - bounded browser smoke for dashboard action/modal/direct page
  - `cd apps/platform && ./vendor/bin/sail pint --dirty` if PHP changes
  - `git diff --check`
- **Fixture / helper / factory / seed / context cost risks**: use existing fixture patterns; document unavailable repair/blocker screenshots instead of widening fixture infrastructure.
- **Expensive defaults or shared helper growth introduced?**: no.
- **Heavy-family additions, promotions, or visibility changes**: one bounded browser smoke only.
- **Surface-class relief / special coverage rule**: standard-native-filament for action state; shared-detail-family for modal; exception-coded-surface for direct repair page.
- **Closing validation and reviewer handoff**: reviewers should inspect source audit, matrix, browser report, screenshot index, validation report, and final diff for out-of-scope files.
- **Budget / baseline / trend follow-up**: none expected.
- **Review-stop questions**: Did implementation add a hub, new nav, provider/permission runtime checks, raw leakage, or weaken repair-action safety?
- **Escalation path**: document-in-feature for fixture gaps; follow-up-spec for provider/permission diagnostics, evidence/system browser reachability, or bloat guard.
- **Active feature PR close-out entry**: Guardrail / Smoke Coverage.
- **Why no dedicated follow-up spec is needed**: This is the dedicated entrypoint productization slice; broader diagnostic lanes are explicitly deferred.

## Project Structure

### Documentation (this feature)

```text
specs/374-diagnostic-entry-point-support-diagnostics-consolidation/
├── spec.md
├── plan.md
├── tasks.md
├── checklists/
│   └── requirements.md
└── artifacts/
    ├── source-audit-summary.md
    ├── diagnostic-entrypoint-matrix.md
    ├── affected-files.md
    ├── implementation-notes.md
    ├── browser-verification-report.md
    ├── before-after-screenshot-index.md
    ├── validation-report.md
    ├── follow-up-recommendations.md
    └── screenshots/
```

### Source Code (repository root)

Likely affected runtime surfaces for later implementation:

```text
apps/platform/app/Filament/Pages/EnvironmentDashboard.php
apps/platform/app/Filament/Pages/EnvironmentDiagnostics.php
apps/platform/app/Support/ManagedEnvironmentLinks.php
apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php
apps/platform/resources/views/filament/pages/environment-diagnostics.blade.php
apps/platform/resources/views/filament/modals/support-diagnostic-bundle.blade.php
apps/platform/tests/Feature/Filament/
apps/platform/tests/Feature/SupportDiagnostics/
apps/platform/tests/Browser/
docs/ui-ux-enterprise-audit/route-inventory.md
docs/ui-ux-enterprise-audit/page-reports/
```

**Structure Decision**: Single Laravel web application. Implementation should stay in existing page/view/support-diagnostics/test locations and spec-local artifacts. Do not create new base folders.

## Complexity Tracking

No constitutional violation is planned.

| Violation | Why Needed | Simpler Alternative Rejected Because |
|---|---|---|
| N/A | N/A | N/A |

## Proportionality Review

- **Current operator problem**: unclear official diagnostic entrypoint causes hidden-route confusion and future scope creep.
- **Existing structure is insufficient because**: existing surfaces show diagnostic content but do not clearly define which surface owns quick support, repair, provider/permission, system, evidence, or customer review questions.
- **Narrowest correct implementation**: label/copy/conditional entrypoint and no-action semantics over existing routes/actions, backed by a matrix and browser proof.
- **Ownership cost created**: focused tests, screenshots, and spec-local artifacts.
- **Alternative intentionally rejected**: generic Diagnostic Hub or provider-health framework.
- **Release truth**: current-release productization over existing diagnostic/support surfaces.

## Implementation Phases

### Phase 0 - Repo Truth And Source Audit

Re-read Spec 373/370 context, current dashboard/diagnostics/support code, route inventory, and tests. Re-run `ManagedEnvironmentLinks::diagnosticsUrl()` usage search. Complete source audit and matrix before runtime edits.

### Phase 1 - Tests First

Add/update focused tests for dashboard support diagnostics entry, optional secondary repair diagnostics link behavior, direct repair diagnostics no-action state, repair action safety, DB-local/no-Graph rendering for dashboard/modal/page paths, and support modal purpose/first-check fallback.

### Phase 2 - Dashboard Diagnostic Entry Productization

Refine `Open support diagnostics` label/description/placement if needed. Add a secondary repair diagnostics link only if repo-backed and low-risk. Keep the dashboard's primary decision hierarchy intact.

### Phase 3 - Repair Diagnostics Page Framing

Reframe the direct diagnostics page as repair diagnostics. Improve no-action copy and support-diagnostics handoff. Preserve repair action authorization, confirmation, and service ownership. Audit existing action-surface metadata before changing canonical nouns so the page contract does not drift from the UI governance catalog.

### Phase 4 - Support Diagnostics Purpose Check

Confirm the modal begins with recommended first check and purpose. Add calm fallback only if current bundle output can lack a recommendation. Do not add new support sections or inferred causes.

### Phase 5 - Browser Smoke And Artifacts

Use the existing browser fixture/login path. Capture dashboard entry, support diagnostics modal, direct repair diagnostics page, and no-action state screenshots where reachable. Document any repair-blocker fixture gap.

### Phase 6 - Validation And Close-Out Artifacts

Run targeted tests/static checks, complete implementation notes, browser report, screenshot index, validation report, affected files, and follow-up recommendations. Confirm no out-of-scope runtime files changed.