TenantAtlas/specs/373-diagnostic-surface-separation/tasks.md

# 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

- [x] Lane assignment is named and narrow: Feature/Livewire for page/modal rendering, Browser for first-viewport/modal hierarchy, static checks for artifact quality.
- [x] New or changed tests stay in the smallest honest family; any browser coverage is explicit and bounded to Spec 373 surfaces.
- [x] Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any browser fixture gap is documented instead of broadened silently.
- [x] Planned validation commands cover the changed behavior without pulling in unrelated lane cost.
- [x] `standard-native-filament` relief is explicit for Environment Diagnostics action safety; `shared-detail-family` coverage is explicit for support diagnostics modal.
- [x] 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.

- [x] T001 Re-read `specs/373-diagnostic-surface-separation/spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md`.
- [x] 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`
- [x] 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`
- [x] 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`
- [x] 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`
- [x] 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
- [x] 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.

- [x] 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.
- [x] 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.
- [x] T010 Create `specs/373-diagnostic-surface-separation/artifacts/affected-files.md` and populate planned file rows before runtime edits.
- [x] T011 Create `specs/373-diagnostic-surface-separation/artifacts/before-after-screenshot-index.md` with Spec 368 before screenshots and planned after/blocked screenshot slots.
- [x] T012 Create `specs/373-diagnostic-surface-separation/artifacts/diagnostic-safety-checklist.md` with one checklist row per scoped/referenced surface.
- [x] T013 Create `specs/373-diagnostic-surface-separation/artifacts/validation-report.md` with branch, HEAD, clean/dirty state before implementation, and planned commands.
- [x] 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.

- [x] T015 Add or update focused Feature/Livewire coverage for Environment Diagnostics missing-owner state.
- [x] T016 Add or update focused Feature/Livewire coverage for Environment Diagnostics duplicate-membership state.
- [x] 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.
- [x] T018 Add or update focused Feature/Livewire coverage for the no-action state: one calm diagnostic summary and no zero-card spam.
- [x] T019 Add or update assertions that `bootstrapOwner` and `mergeDuplicateMemberships` remain visible only when applicable.
- [x] T020 Add or update assertions that the existing repair actions keep confirmation, capability gating, destructive treatment, and server-side authorization behavior.
- [x] 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.

- [x] T022 Add or update tenant support diagnostics modal coverage so the summary/dominant issue, redaction note, and recommended first check appear before reference sections.
- [x] T023 Add or update OperationRun support diagnostics modal coverage so failed/blocked run context appears before lower audit/reference sections.
- [x] T024 Add or update support diagnostics authorization coverage for entitled users without support diagnostics capability.
- [x] T025 Add or update assertions that redaction markers and raw/support detail remain lower-priority, redacted, or unavailable rather than default-visible raw payloads.
- [x] T026 Add or update assertions that support diagnostics telemetry and audit behavior remain unchanged when the modal opens.
- [x] 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.

- [x] T028 Update `apps/platform/resources/views/filament/pages/environment-diagnostics.blade.php` so one diagnostic summary leads the first viewport.
- [x] T029 Ensure missing-owner copy includes failed condition, impact, and the existing next action.
- [x] T030 Ensure duplicate-membership copy includes failed condition, impact, and the existing next action.
- [x] T031 Ensure the no-action copy says one calm message such as "No diagnostic action is required" and avoids unsupported broad health claims.
- [x] 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.
- [x] T033 Preserve existing `ActionSurfaceDeclaration`, `UiEnforcement`, `Capabilities::TENANT_MANAGE`, confirmation, action handlers, and repair service ownership.
- [x] 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.

- [x] 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.
- [x] 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.
- [x] T037 Keep workspace/environment/run context visible without promoting raw record IDs as primary UI copy.
- [x] T038 Keep section references, audit history, redaction markers, and technical/support details lower-priority and redacted.
- [x] 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.

- [x] T040 Confirm Provider Connections and Required Permissions are unchanged unless a shared helper change requires a targeted regression note.
- [x] 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.
- [x] 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.
- [x] T043 Update `docs/ui-ux-enterprise-audit/route-inventory.md` only if screenshot/report references or UI-012 status changes.
- [x] T044 Update `docs/ui-ux-enterprise-audit/unresolved-pages.md` only if a scoped route/modal remains unreachable and needs durable tracking.
- [x] 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.

- [x] T046 Start the local platform stack using Sail or the repo's platform dev command.
- [x] T047 Resolve/open the Environment Diagnostics route with the existing smoke-login/browser fixture.
- [x] T048 Capture `specs/373-diagnostic-surface-separation/artifacts/screenshots/001-environment-diagnostics-after.png` if reachable.
- [x] T049 Browser-verify missing-owner or duplicate-membership state if the fixture can create it safely; otherwise document fixture limitation.
- [x] T050 Browser-verify no-action Environment Diagnostics state if reachable.
- [x] T051 Open support diagnostics modal from an existing tenant/environment or OperationRun host surface.
- [x] 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.
- [x] T053 Verify browser console has no new JavaScript/runtime errors for the scoped flow.
- [x] 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.

- [x] T055 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=EnvironmentDiagnostics`.
- [x] T056 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=SupportDiagnostics`.
- [x] T057 Run focused Spec 353 regression tests only if Provider Connections or Required Permissions were touched by shared code.
- [x] T058 Run `cd apps/platform && ./vendor/bin/sail pint --dirty` if PHP files changed.
- [x] T059 Run `git diff --check`.
- [x] T060 Complete `specs/373-diagnostic-surface-separation/artifacts/affected-files.md` with final touched files, risk, verification class, and out-of-scope side effects.
- [x] 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.
- [x] T062 Complete `specs/373-diagnostic-surface-separation/artifacts/before-after-screenshot-index.md`.
- [x] T063 Complete `specs/373-diagnostic-surface-separation/artifacts/diagnostic-safety-checklist.md`.
- [x] T064 Complete `specs/373-diagnostic-surface-separation/artifacts/implementation-notes.md`.
- [x] T065 Complete `specs/373-diagnostic-surface-separation/artifacts/validation-report.md` with tests, browser results, dirty state, runtime files changed, and recommended next spec.
- [x] 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

- [x] NT001 Do not reimplement Provider Connections or Required Permissions readiness guidance; Spec 353 owns that work.
- [x] NT002 Do not solve `/system` auth or browser fixture reachability.
- [x] NT003 Do not change ProviderGateway, provider health resolver, provider credential, or Microsoft Graph permission calculation behavior.
- [x] NT004 Do not add migrations, new models, persisted diagnostic truth, enum/status families, or provider/onboarding frameworks.
- [x] NT005 Do not add new Graph calls or provider HTTP calls during render.
- [x] NT006 Do not add support request lifecycle, external PSA handoff, AI, automation, billing, or entitlement behavior.
- [x] NT007 Do not intentionally refactor customer/auditor/operator surfaces from Specs 371/372.
- [x] 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.