ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/374-diagnostic-entry-point-support-diagnostics-consolidation/tasks.md
ahmido 0a1ecf99c9 feat(ui): implement diagnostic entry point consolidation (#445) 
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.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #445
2026-06-13 01:16:00 +00:00

18 KiB
Raw Permalink Blame History

Tasks: Spec 374 - Diagnostic Entry Point and Support Diagnostics Consolidation v1

Input: specs/374-diagnostic-entry-point-support-diagnostics-consolidation/spec.md, plan.md, checklists/requirements.md, Spec 373 completed artifacts, Spec 370 IA contract, and current dashboard/diagnostics/support code.

Tests: Required for later implementation. This spec changes existing operator/support-facing diagnostic entrypoint semantics and repair diagnostics framing.

Implementation Notes For Task Completion

  • T017/T032/T033 were satisfied by proving no dashboard repair diagnostics link is needed in the current no-action state; ManagedEnvironmentLinks::diagnosticsUrl() remains a retained canonical deeplink utility, while Repair Diagnostics now exposes one secondary read-only Open support diagnostics modal action.
  • T031 was satisfied by preserving the existing dashboard Open support diagnostics action label/grouping and updating only the modal description copy in localization.
  • T041 was not needed because existing SupportDiagnosticBundleBuilder recommended-first-check data was sufficient.
  • T045/T063 were not applicable because Provider Connections and Required Permissions runtime files were not touched.
  • T058 was documented as fixture-limited: the browser smoke did not create a repair/blocker state, while missing-owner and duplicate-membership states remain covered by Feature/Livewire tests.
  • The implementation commands were run with local php artisan test / php vendor/bin/pint instead of Sail because the local non-Docker test harness was available and passed.

Test Governance Checklist

  • Lane assignment is named and narrow: Feature/Livewire for action/page/modal rendering, Browser for entrypoint discoverability, static checks for artifact quality.
  • New or changed tests stay in the smallest honest family; browser coverage is explicit and bounded to Spec 374 surfaces.
  • Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any browser fixture gap is documented instead of broadened silently.
  • Planned validation commands cover the changed behavior without pulling in unrelated lane cost.
  • standard-native-filament, shared-detail-family, and exception-coded-surface profiles are applied only where they match the proof need.
  • Any material fixture, browser, or follow-up note is recorded in the active spec artifacts.

Phase 1: Preparation And Repo Truth

Purpose: Confirm Spec 374 is an entrypoint/productization follow-up, not a rewrite of completed Spec 373.

  • T001 Re-read specs/374-diagnostic-entry-point-support-diagnostics-consolidation/spec.md, plan.md, tasks.md, and checklists/requirements.md.
  • T002 Re-read completed Spec 373 governing artifacts:
    • 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
  • T003 Re-read Spec 370 IA inputs:
    • specs/370-global-surface-information-architecture-contract/artifacts/surface-contract.md
    • specs/370-global-surface-information-architecture-contract/artifacts/surface-type-matrix.md
    • specs/370-global-surface-information-architecture-contract/artifacts/copy-and-terminology-rules.md
  • T004 Re-read current runtime truth in:
    • apps/platform/routes/web.php
    • 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
  • T005 Search and document all current ManagedEnvironmentLinks::diagnosticsUrl() callers.
  • T006 Confirm no migration, package, env var, queue family, scheduler, storage, panel/provider, global-search, provider gateway, permission engine, or OperationRun lifecycle change is required.

Phase 2: Spec-Local Artifacts Before Runtime Edits

Purpose: Prevent the implementation from growing into a diagnostic hub.

  • T007 Update specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/source-audit-summary.md with final pre-edit route/action/helper/code findings.
  • T008 Update specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/diagnostic-entrypoint-matrix.md with all required diagnostic need rows and final in-scope/deferred decisions.
  • T009 Create specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/implementation-notes.md with planned product decision sections before runtime edits.
  • T010 Create specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/browser-verification-report.md with planned URLs, fixture assumptions, and screenshot slots before browser work.
  • T011 Create specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/before-after-screenshot-index.md with Spec 373/route-inventory before evidence and planned after slots.
  • T012 Create specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/follow-up-recommendations.md with deferred Provider/Permission, Evidence/System, UI Bloat Guard, and long-term repair-diagnostics discoverability sections.
  • T013 Update specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/affected-files.md with planned runtime/docs/test/artifact rows before code changes.
  • T014 Update specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/validation-report.md with branch, HEAD, dirty state before implementation, and planned commands.

Phase 3: Tests First - Dashboard Entry And Repair Link Semantics

Purpose: Lock the official diagnostic entrypoint and avoid button overload before changing UI copy.

  • T015 Add or update Feature/Livewire coverage proving Environment Dashboard exposes Open support diagnostics as the clear quick diagnostic entry.
  • T016 Add or update coverage proving no repair diagnostics action is promoted as a primary dashboard action when no repairable diagnostics are active.
  • T017 If a repair diagnostics link is implemented, add coverage proving it is secondary, clearly labeled, and shown only when existing repair truth indicates value or the matrix/source audit documents one secondary deeplink utility rationale.
  • T018 Add assertions that dashboard diagnostic entry changes do not add new top-level navigation, alter panel provider registration, or call Graph/provider HTTP during render.

Phase 4: Tests First - Repair Diagnostics Page

Purpose: Make the direct page honest about being repair diagnostics, not all environment health.

  • T019 Add or update Feature/Livewire coverage for the no-action Environment Diagnostics state: repair-only language, broader support context handoff, and no broad health claim.
  • T020 Add or update coverage for the existing missing-owner presentation path only if it can be exercised without adding runtime missing-owner detection or owner-recovery logic.
  • T021 Add or update coverage for duplicate-membership repair state.
  • T022 Add or update coverage for both repair blockers, ensuring one dominant repair path and secondary repair path demotion.
  • T023 Add or update assertions that existing bootstrapOwner and mergeDuplicateMemberships actions remain visible only when applicable.
  • T024 Add or update assertions that existing repair actions keep confirmation, capability gating, destructive treatment, and server-side authorization behavior.
  • T025 Add or update assertions that repair diagnostics render paths do not call Graph/provider HTTP, use existing DB-local truth only, and keep action-surface metadata consistent if the canonical noun changes to Repair Diagnostics.

Phase 5: Tests First - Support Diagnostics Modal

Purpose: Preserve the official quick support entry while avoiding invented likely causes.

  • T026 Add or update support diagnostics modal coverage proving the modal explains its quick support purpose before lower technical sections.
  • T027 Add or update coverage proving recommended first check appears when repo-backed data exists.
  • T028 Add or update coverage for calm fallback copy when no specific recommended first check exists.
  • T029 Add or update assertions that redaction markers and raw/support detail remain lower-priority, redacted, unavailable, or capability-gated.
  • T030 Add or update assertions that support diagnostics telemetry, audit, authorization behavior, and DB-local/no-Graph rendering remain unchanged when the modal opens.

Phase 6: Dashboard Diagnostic Entry Implementation

Purpose: Productize the visible entrypoint without making diagnostics compete with dashboard decisions.

  • T031 Update apps/platform/app/Filament/Pages/EnvironmentDashboard.php only if needed to clarify Open support diagnostics label, description, grouping, or tooltip.
  • T032 If adding a repair diagnostics link, use ManagedEnvironmentLinks::diagnosticsUrl() or an existing route helper in exactly one secondary placement, and record whether the trigger is existing repair truth or a documented secondary deeplink utility.
  • T033 Ensure any repair diagnostics link is clearly labeled as repair diagnostics and does not displace the dashboard's primary decisions.
  • T034 Do not add a top-level navigation item, a dashboard diagnostic hub card, or multiple competing diagnostic buttons.

Phase 7: Repair Diagnostics Page Implementation

Purpose: Make the direct route repair-only and honest in no-action states.

  • T035 Update apps/platform/app/Filament/Pages/EnvironmentDiagnostics.php only if needed for page-local derived labels or secondary handoff text.
  • T036 Update apps/platform/resources/views/filament/pages/environment-diagnostics.blade.php so the page title/body/state copy says repair diagnostics and no supported repair diagnostics when no issue exists.
  • T037 Add or preserve clear copy that broader support context starts from Open support diagnostics, with Environment Dashboard remaining the official quick entrypoint and Repair Diagnostics providing a secondary handoff.
  • T038 Preserve existing ActionSurfaceDeclaration, ActionSurfaceExemptions, UiEnforcement, Capabilities::TENANT_MANAGE, confirmation, action handlers, and repair service ownership; update or explicitly retain existing ManagedEnvironment diagnostics terminology if rendered copy moves to Repair Diagnostics.
  • T039 Keep provider/permission/evidence/system checks out of the repair page unless already repo-backed as lower related context and explicitly documented.

Phase 8: Support Diagnostics Modal Implementation

Purpose: Confirm the modal is the official quick diagnostics/support context path.

  • T040 Update apps/platform/resources/views/filament/modals/support-diagnostic-bundle.blade.php only if current copy does not clearly state the quick support diagnostics purpose.
  • T041 If existing bundle data is insufficient for fallback first-check copy, update apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php narrowly using existing truth only.
  • T042 Keep support modal read-only, redacted, capability-gated, and lower sections secondary.
  • T043 Document native Filament/shared primitive reuse for any changed Blade/Tailwind composition, including why no ad-hoc status/button/card language was introduced, and do not add support request lifecycle, PSA, AI, export, provider, permission, or OperationRun behavior.

Phase 9: Deferred Surface And UI Audit Handling

Purpose: Keep follow-up diagnostics out of Spec 374 while recording durable decisions.

  • T044 Confirm Provider Connections and Required Permissions runtime files are unchanged unless a shared helper change requires a targeted regression note.
  • T045 If Provider Connections or Required Permissions are touched by shared code, run focused Spec 353-style regression tests and document why the touch was unavoidable.
  • T046 Update docs/ui-ux-enterprise-audit/page-reports/ui-002-environment-dashboard.md only if dashboard diagnostic action evidence/status changes materially.
  • T047 Update docs/ui-ux-enterprise-audit/page-reports/ui-012-environment-diagnostics.md if repair diagnostics evidence/status changes materially.
  • T048 Update docs/ui-ux-enterprise-audit/route-inventory.md only if screenshot/report references or classifications materially change.
  • T049 Update docs/ui-ux-enterprise-audit/unresolved-pages.md only if a scoped modal/page remains unreachable and needs durable tracking.

Phase 10: Browser Smoke And Screenshots

Purpose: Prove entrypoint discoverability and honest page semantics in the browser.

  • T050 Start the local platform stack using Sail or the repo's platform dev command.
  • T051 Resolve/open the Environment Dashboard with the existing smoke-login/browser fixture.
  • T052 Capture specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/screenshots/001-environment-dashboard-diagnostic-entry-after.png if reachable.
  • T053 Open Support Diagnostics from the dashboard action/modal.
  • T054 Capture specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/screenshots/002-support-diagnostics-modal-after.png if reachable.
  • T055 Open the direct Environment Diagnostics / Repair Diagnostics page.
  • T056 Capture specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/screenshots/003-environment-repair-diagnostics-after.png if reachable.
  • T057 Verify no-action state and capture the secondary support handoff as specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/screenshots/004-environment-repair-diagnostics-support-modal-after.png if reachable.
  • T058 Verify repair/blocker state if the fixture can create it safely; otherwise document not available and do not fake the state.
  • T059 Verify browser console has no new JavaScript/runtime errors for the scoped flow.

Phase 11: Validation And Close-Out Artifacts

Purpose: Finish with bounded proof and no application-scope creep.

  • T060 Run the exact Spec 374 diagnostic-entry test file/filter if created; otherwise record why no DiagnosticEntry filter exists and run the concrete dashboard/support/repair test files that cover it.
  • T061 Run cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDiagnosticsRepairsTest.php or the exact replacement Spec 374 repair-diagnostics test file.
  • T062 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=SupportDiagnostics.
  • T063 Run focused Spec 353 regression tests only if Provider Connections or Required Permissions were touched by shared code.
  • T064 Run cd apps/platform && ./vendor/bin/sail pint --dirty if PHP files changed.
  • T065 Run git diff --check.
  • T066 Complete specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/affected-files.md with final touched files, risk, verification class, and out-of-scope side effects.
  • T067 Complete specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/browser-verification-report.md with URLs, fixture, screenshots, reachability, blocked pages, and remaining issues.
  • T068 Complete specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/before-after-screenshot-index.md.
  • T069 Complete specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/implementation-notes.md.
  • T070 Complete specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/follow-up-recommendations.md.
  • T071 Complete specs/374-diagnostic-entry-point-support-diagnostics-consolidation/artifacts/validation-report.md with tests, browser results, dirty state, runtime files changed, and recommended next spec.
  • T072 Confirm final implementation report includes Livewire v4 compliance, provider registration location, global search status, destructive action safety, asset strategy, tests, and deployment impact.

Non-Goals Checklist

  • NT001 Do not build a diagnostic hub.
  • NT002 Do not register Environment Diagnostics as top-level navigation.
  • NT003 Do not reimplement Provider Connections or Required Permissions readiness guidance.
  • NT004 Do not solve /system auth or browser fixture reachability.
  • NT005 Do not solve Evidence Snapshot reachability or customer review evidence productization.
  • NT006 Do not change ProviderGateway, provider health resolver, provider credential, Microsoft Graph permission calculation, or Graph contracts.
  • NT007 Do not add migrations, new models, persisted diagnostic truth, enum/status families, or provider/onboarding frameworks.
  • NT008 Do not add new Graph calls or provider HTTP calls during render.
  • NT009 Do not add support request lifecycle, external PSA handoff, AI, automation, billing, or entitlement behavior.
  • NT010 Do not intentionally refactor customer/auditor surfaces or core operator surfaces from Specs 371/372.
  • NT011 Do not rewrite completed historical specs or remove implementation close-out/validation evidence.

Dependencies And Execution Order

  • Phase 1 must complete before runtime edits.
  • Phase 2 artifacts should be updated before tests and implementation so scope drift is visible.
  • Phases 3, 4, and 5 test work should precede Phases 6, 7, and 8 implementation.
  • Phase 9 runs after any shared-code touch and before browser close-out.
  • Phase 10 browser smoke runs after targeted tests are green enough to make rendered proof meaningful.
  • Phase 11 closes the implementation package.

Recommended Implementation Strategy

Deliver User Story 1 first: the dashboard entrypoint and support diagnostics modal. Then refine direct repair diagnostics no-action semantics. Treat provider/permission/system/evidence/customer review diagnostics as matrix/follow-up decisions unless a shared change creates a bounded regression.