ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
c125fd48fd
TenantAtlas/specs/374-diagnostic-entry-point-support-diagnostics-consolidation/tasks.md
Ahmed Darrazi c125fd48fd
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 3m58s
Details
feat(ui): implement diagnostic entry point consolidation 
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.
2026-06-13 03:06:33 +02:00

18 KiB
Raw 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.