ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/373-diagnostic-surface-separation/tasks.md
ahmido 94877c9a66 feat(ui): implement diagnostic surface separation (#444) 
Applied the decision-first diagnostic surface IA contract to EnvironmentDiagnostics and SupportDiagnostics bundles. Added recommended_first_check and separated technical metadata as per Spec 373.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #444
2026-06-12 20:31:17 +00:00

17 KiB
Raw Permalink Blame History

Tasks: Spec 373 - Diagnostic Surface Separation v1

Input: specs/373-diagnostic-surface-separation/spec.md, plan.md, checklists/requirements.md, Spec 368 audit artifacts, Spec 370 contract artifacts, and completed Spec 353/371/372 context.

Tests: Required for later implementation. This spec changes existing operator/support-facing diagnostic UI hierarchy.

Test Governance Checklist

  • Lane assignment is named and narrow: Feature/Livewire for page/modal rendering, Browser for first-viewport/modal hierarchy, static checks for artifact quality.
  • New or changed tests stay in the smallest honest family; any browser coverage is explicit and bounded to Spec 373 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 relief is explicit for Environment Diagnostics action safety; shared-detail-family coverage is explicit for support diagnostics modal.
  • Any material fixture, browser, or follow-up note is recorded in the active spec artifacts.

Phase 1: Preparation And Repo Truth

Purpose: Confirm the implementation target is the remaining diagnostics gap and not completed provider/customer/operator productization work.

  • T001 Re-read specs/373-diagnostic-surface-separation/spec.md, plan.md, tasks.md, and checklists/requirements.md.
  • T002 Re-read Spec 368 diagnostic/configuration source inputs:
    • specs/368-platform-ui-signal-to-noise-browser-audit/audit.md
    • specs/368-platform-ui-signal-to-noise-browser-audit/findings.md
    • specs/368-platform-ui-signal-to-noise-browser-audit/page-scorecard.csv
    • specs/368-platform-ui-signal-to-noise-browser-audit/spec-candidates.md
    • specs/368-platform-ui-signal-to-noise-browser-audit/artifacts/raw/browser-notes.md
    • specs/368-platform-ui-signal-to-noise-browser-audit/artifacts/screenshots/admin/015-diagnostic-surface-diagnostics-environment-diagnostics.png
    • specs/368-platform-ui-signal-to-noise-browser-audit/artifacts/screenshots/blocked-or-error/016-configuration-surface-settings-required-permissions-error.png
    • specs/368-platform-ui-signal-to-noise-browser-audit/artifacts/screenshots/blocked-or-error/031-system-surface-dashboard-system-dashboard-error.png
  • T003 Re-read Spec 370 contract artifacts:
    • 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/page-assessment-checklist.md
    • specs/370-global-surface-information-architecture-contract/artifacts/copy-and-terminology-rules.md
    • specs/370-global-surface-information-architecture-contract/artifacts/follow-up-spec-map.md
  • T004 Re-read completed Spec 353 boundaries and artifacts:
    • specs/353-provider-connections-resolution-guidance-v1/spec.md
    • specs/353-provider-connections-resolution-guidance-v1/tasks.md
    • docs/ui-ux-enterprise-audit/page-reports/ui-009-provider-connections.md
    • docs/ui-ux-enterprise-audit/page-reports/ui-077-required-permissions.md
  • T005 Re-read completed Spec 371 and Spec 372 artifact summaries for patterns and guardrails:
    • specs/371-core-operator-view-surfaces-productization/artifacts/source-audit-summary.md
    • specs/371-core-operator-view-surfaces-productization/artifacts/browser-verification-report.md
    • specs/371-core-operator-view-surfaces-productization/artifacts/validation-report.md
    • specs/372-customer-auditor-surface-safety-pass/artifacts/source-audit-summary.md
    • specs/372-customer-auditor-surface-safety-pass/artifacts/browser-verification-report.md
    • specs/372-customer-auditor-surface-safety-pass/artifacts/validation-report.md
  • T006 Re-verify current runtime truth in:
    • apps/platform/app/Filament/Pages/EnvironmentDiagnostics.php
    • apps/platform/resources/views/filament/pages/environment-diagnostics.blade.php
    • apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php
    • apps/platform/resources/views/filament/modals/support-diagnostic-bundle.blade.php
    • existing support diagnostics action host pages/resources
  • T007 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: Make the later implementation auditable and prevent accidental scope growth.

  • T008 Create specs/373-diagnostic-surface-separation/artifacts/source-audit-summary.md with Spec 368 findings, Spec 370 inputs, Spec 371/372/353 completed-context notes, and reachability expectations.
  • T009 Create specs/373-diagnostic-surface-separation/artifacts/diagnostic-surface-contracts.md covering Environment Diagnostics, support diagnostics modal, Provider Connections context, Required Permissions context, and /system deferred status.
  • T010 Create specs/373-diagnostic-surface-separation/artifacts/affected-files.md and populate planned file rows before runtime edits.
  • T011 Create specs/373-diagnostic-surface-separation/artifacts/before-after-screenshot-index.md with Spec 368 before screenshots and planned after/blocked screenshot slots.
  • T012 Create specs/373-diagnostic-surface-separation/artifacts/diagnostic-safety-checklist.md with one checklist row per scoped/referenced surface.
  • T013 Create specs/373-diagnostic-surface-separation/artifacts/validation-report.md with branch, HEAD, clean/dirty state before implementation, and planned commands.
  • T014 Create specs/373-diagnostic-surface-separation/artifacts/implementation-notes.md and specs/373-diagnostic-surface-separation/artifacts/browser-verification-report.md, then record the completed-spec guardrail decision and planned browser checks before runtime edits.

Phase 3: Tests First - Environment Diagnostics

Purpose: Lock diagnostic hierarchy and existing repair-action safety before changing page output.

  • T015 Add or update focused Feature/Livewire coverage for Environment Diagnostics missing-owner state.
  • T016 Add or update focused Feature/Livewire coverage for Environment Diagnostics duplicate-membership state.
  • T017 Add or update focused Feature/Livewire coverage for both blockers shown together with one top summary, one dominant next action, and any second repair/context path demoted instead of competing summaries or primary actions.
  • T018 Add or update focused Feature/Livewire coverage for the no-action state: one calm diagnostic summary and no zero-card spam.
  • T019 Add or update assertions that bootstrapOwner and mergeDuplicateMemberships remain visible only when applicable.
  • T020 Add or update assertions that the existing repair actions keep confirmation, capability gating, destructive treatment, and server-side authorization behavior.
  • T021 Add or update assertions that Environment Diagnostics render paths do not call Graph/provider HTTP and use existing DB-local truth only.

Phase 4: Tests First - Support Diagnostics Modal

Purpose: Preserve authorization, redaction, telemetry, audit, and modal support value while improving hierarchy.

  • T022 Add or update tenant support diagnostics modal coverage so the summary/dominant issue, redaction note, and recommended first check appear before reference sections.
  • T023 Add or update OperationRun support diagnostics modal coverage so failed/blocked run context appears before lower audit/reference sections.
  • T024 Add or update support diagnostics authorization coverage for entitled users without support diagnostics capability.
  • T025 Add or update assertions that redaction markers and raw/support detail remain lower-priority, redacted, or unavailable rather than default-visible raw payloads.
  • T026 Add or update assertions that support diagnostics telemetry and audit behavior remain unchanged when the modal opens.
  • T027 Add or update tests for missing provider connection / missing OperationRun / untranslated provider reason / no dominant issue fallback copy, including assertions that unavailable context is not rendered as a fake link and likely-cause copy falls back to neutral recommended-next-check language.

Phase 5: Environment Diagnostics Implementation

Purpose: Productize the existing diagnostic page without backend or provider behavior changes.

  • T028 Update apps/platform/resources/views/filament/pages/environment-diagnostics.blade.php so one diagnostic summary leads the first viewport.
  • T029 Ensure missing-owner copy includes failed condition, impact, and the existing next action.
  • T030 Ensure duplicate-membership copy includes failed condition, impact, and the existing next action.
  • T031 Ensure the no-action copy says one calm message such as "No diagnostic action is required" and avoids unsupported broad health claims.
  • T032 If needed, update apps/platform/app/Filament/Pages/EnvironmentDiagnostics.php with the smallest page-local derived summary data; do not create a generic diagnostic framework.
  • T033 Preserve existing ActionSurfaceDeclaration, UiEnforcement, Capabilities::TENANT_MANAGE, confirmation, action handlers, and repair service ownership.
  • T034 Keep technical/provider/ID detail out of the first viewport unless it directly explains the current diagnostic blocker.

Phase 6: Support Diagnostics Modal Implementation

Purpose: Make support diagnostics guide the first support check while preserving full redacted depth.

  • T035 Update apps/platform/resources/views/filament/modals/support-diagnostic-bundle.blade.php so headline, dominant issue, freshness/completeness, redaction note, and recommended first check precede lower sections.
  • T036 If existing bundle data is insufficient for "recommended first check", update apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php narrowly using existing provider reason, OperationRun, contextual help, and reference truth; do not infer links or likely causes when no repo-backed proof exists.
  • T037 Keep workspace/environment/run context visible without promoting raw record IDs as primary UI copy.
  • T038 Keep section references, audit history, redaction markers, and technical/support details lower-priority and redacted.
  • T039 Do not add new support request, PSA, AI, export, provider, permission, or OperationRun behavior.

Phase 7: Completed-Spec Regression And UI Audit Handling

Purpose: Protect completed Spec 353/371/372 surfaces while keeping coverage artifacts proportional.

  • T040 Confirm Provider Connections and Required Permissions are unchanged unless a shared helper change requires a targeted regression note.
  • T041 If Provider Connections or Required Permissions are touched by shared code, run focused Spec 353 regression tests and document why the touch was unavoidable.
  • T042 Update or create docs/ui-ux-enterprise-audit/page-reports/ui-012-environment-diagnostics.md only if implementation materially changes UI-012 evidence/status.
  • T043 Update docs/ui-ux-enterprise-audit/route-inventory.md only if screenshot/report references or UI-012 status changes.
  • T044 Update docs/ui-ux-enterprise-audit/unresolved-pages.md only if a scoped route/modal remains unreachable and needs durable tracking.
  • T045 Leave docs/ui-ux-enterprise-audit/page-reports/ui-009-provider-connections.md and docs/ui-ux-enterprise-audit/page-reports/ui-077-required-permissions.md untouched unless a documented regression requires it.

Phase 8: Browser Smoke And Screenshots

Purpose: Prove the source browser finding has been addressed or document fixture limitations honestly.

  • T046 Start the local platform stack using Sail or the repo's platform dev command.
  • T047 Resolve/open the Environment Diagnostics route with the existing smoke-login/browser fixture.
  • T048 Capture specs/373-diagnostic-surface-separation/artifacts/screenshots/001-environment-diagnostics-after.png if reachable.
  • T049 Browser-verify missing-owner or duplicate-membership state if the fixture can create it safely; otherwise document fixture limitation.
  • T050 Browser-verify no-action Environment Diagnostics state if reachable.
  • T051 Open support diagnostics modal from an existing tenant/environment or OperationRun host surface.
  • T052 Capture specs/373-diagnostic-surface-separation/artifacts/screenshots/002-support-diagnostics-after-or-blocked.png if reachable, or a blocked screenshot/reason if not.
  • T053 Verify browser console has no new JavaScript/runtime errors for the scoped flow.
  • T054 Verify Provider Connections and Required Permissions are not recaptured unless shared changes require targeted regression proof.

Phase 9: Validation And Close-Out Artifacts

Purpose: Finish the implementation with focused proof and complete spec-local evidence.

Execution notes:

  • T055 exact filter result: --filter=EnvironmentDiagnostics returned No tests found; effective Environment Diagnostics validation used tests/Feature/Filament/TenantDiagnosticsRepairsTest.php and passed.

  • T057 was not applicable because no Provider Connections or Required Permissions runtime files were touched; Spec 353 reports remained unchanged.

  • T055 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=EnvironmentDiagnostics.

  • T056 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=SupportDiagnostics.

  • T057 Run focused Spec 353 regression tests only if Provider Connections or Required Permissions were touched by shared code.

  • T058 Run cd apps/platform && ./vendor/bin/sail pint --dirty if PHP files changed.

  • T059 Run git diff --check.

  • T060 Complete specs/373-diagnostic-surface-separation/artifacts/affected-files.md with final touched files, risk, verification class, and out-of-scope side effects.

  • T061 Complete specs/373-diagnostic-surface-separation/artifacts/browser-verification-report.md with URLs, fixture, screenshots, reachability, before/after scores, blocked pages, and remaining issues.

  • T062 Complete specs/373-diagnostic-surface-separation/artifacts/before-after-screenshot-index.md.

  • T063 Complete specs/373-diagnostic-surface-separation/artifacts/diagnostic-safety-checklist.md.

  • T064 Complete specs/373-diagnostic-surface-separation/artifacts/implementation-notes.md.

  • T065 Complete specs/373-diagnostic-surface-separation/artifacts/validation-report.md with tests, browser results, dirty state, runtime files changed, and recommended next spec.

  • T066 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 reimplement Provider Connections or Required Permissions readiness guidance; Spec 353 owns that work.
  • NT002 Do not solve /system auth or browser fixture reachability.
  • NT003 Do not change ProviderGateway, provider health resolver, provider credential, or Microsoft Graph permission calculation behavior.
  • NT004 Do not add migrations, new models, persisted diagnostic truth, enum/status families, or provider/onboarding frameworks.
  • NT005 Do not add new Graph calls or provider HTTP calls during render.
  • NT006 Do not add support request lifecycle, external PSA handoff, AI, automation, billing, or entitlement behavior.
  • NT007 Do not intentionally refactor customer/auditor/operator surfaces from Specs 371/372.
  • NT008 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 created before tests and implementation so scope drift is visible.
  • Phases 3 and 4 test work should precede Phases 5 and 6 implementation.
  • Phase 7 runs after any shared-code touch and before browser close-out.
  • Phase 8 browser smoke runs after targeted tests are green enough to make rendered proof meaningful.
  • Phase 9 closes the implementation package.

Recommended Implementation Strategy

Deliver User Story 1 first: Environment Diagnostics guidance. It is the browser-verified Spec 368 gap and can be tested independently. Add support diagnostics modal hierarchy next if reachable with existing fixtures. Treat Provider Connections and Required Permissions as regression context only.