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)

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:

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.