c125fd48fd
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 3m58s
Applied diagnostic surface contract rules to Audit Log inspect modal and Support Diagnostics action context, consolidating raw diagnostic data into safe modals according to Spec 374.
288 lines
20 KiB
Markdown
288 lines
20 KiB
Markdown
# 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.
|