ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
241-support-diagnostic-pack-session-1777155669
TenantAtlas/specs/241-support-diagnostic-pack/tasks.md
Ahmed Darrazi 45e6142a67
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 1m0s
Details
feat(support-diagnostics): guardrail refactor and UI polish (agent)
2026-04-26 01:30:28 +02:00

15 KiB
Raw Permalink Blame History

description
Task list for feature implementation

Tasks: Support Diagnostic Pack

Input: Design documents from /specs/241-support-diagnostic-pack/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md

Tests: Required (Pest) for all runtime behavior changes. Keep proof in the targeted fast-feedback and confidence unit + feature suites listed in specs/241-support-diagnostic-pack/quickstart.md.

Scope Lock

  • This task list covers only tenant-context and OperationRun-context support diagnostic bundles on the existing admin-plane tenant dashboard and tenantless operation detail viewer.
  • Deferred by design: external ticketing, standalone support pages or resources, raw export or download flows, AI runtime behavior, heavy browser coverage, and system-panel support surfaces.

Test Governance Notes

  • Lane assignment: targeted unit + feature proof from specs/241-support-diagnostic-pack/quickstart.md is the narrowest sufficient validation for bundle composition, authorization, redaction, canonical-link reuse, and audit logging.
  • No new browser or heavy-governance family should be introduced; keep any helper or fixture growth local to SupportDiagnostics tests and cheap by default.
  • Surface profile: standard-native-filament relief applies to the tenant dashboard action, and the canonical operation detail action must preserve the monitoring-state-page contract already documented in the spec and plan.
  • If implementation leaves a bounded shared-helper or provider-boundary hotspot, record that outcome in specs/241-support-diagnostic-pack/plan.md and specs/241-support-diagnostic-pack/quickstart.md before merge instead of widening this slice.

Phase 1: Setup (Shared Infrastructure)

Purpose: Pin the first-slice scope, existing surfaces, and shared helpers before runtime edits begin.

  • T001 Review the first-slice bundle contract, scope lock, and validation commands in specs/241-support-diagnostic-pack/spec.md, specs/241-support-diagnostic-pack/plan.md, specs/241-support-diagnostic-pack/research.md, specs/241-support-diagnostic-pack/data-model.md, specs/241-support-diagnostic-pack/contracts/support-diagnostics.openapi.yaml, and specs/241-support-diagnostic-pack/quickstart.md
  • T002 [P] Verify the existing tenant dashboard, canonical tenantless operation viewer, and shared helper seams that this slice must reuse in apps/platform/app/Filament/Pages/TenantDashboard.php, apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php, apps/platform/app/Support/OperationRunLinks.php, apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php, apps/platform/app/Support/Navigation/RelatedNavigationResolver.php, apps/platform/app/Support/Providers/ProviderReasonTranslator.php, apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php, and apps/platform/app/Support/RedactionIntegrity.php

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Establish the shared derived-bundle, capability, and audit seams required by both entry contexts without adding persistence or a standalone support surface.

Critical: No user story work should start until this phase is complete.

  • T003 Create the derived support-diagnostics bundle shell with explicit forTenant(...) and forOperationRun(...) entry points and one documented runtime shape in apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php
  • T004 [P] Register support_diagnostics.view in the canonical tenant capability registry and tenant role map without adding any system-plane support variant in apps/platform/app/Support/Auth/Capabilities.php and apps/platform/app/Services/Auth/RoleCapabilityMap.php
  • T005 [P] Add the shared audit action identifier and redacted bundle-open metadata path for both contexts in apps/platform/app/Support/Audit/AuditActionId.php and apps/platform/app/Services/Audit/WorkspaceAuditLogger.php

Checkpoint: Foundation ready - both entry contexts can build on one derived bundle contract, one capability gate, and one audit path.

Phase 3: User Story 1 - Open A Tenant Support-Safe Bundle (Priority: P1) 🎯 MVP

Goal: An entitled operator can open one tenant-scoped support diagnostic bundle from the tenant dashboard and get deterministic, redacted, canonical context without manual cross-page reconstruction.

Independent Test: Seed an entitled tenant with provider, run, finding, stored-report, review, and audit truth, open support diagnostics from the tenant dashboard, and confirm the preview stays redacted, canonical, and authorization-safe.

Tests for User Story 1

  • T006 [P] [US1] Add tenant-context feature coverage for the redacted overview, provider or run or finding or report or review or audit references, freshness cues, and 404 versus 403 behavior in apps/platform/tests/Feature/SupportDiagnostics/TenantSupportDiagnosticActionTest.php

Implementation for User Story 1

  • T007 [US1] Implement tenant-context bundle collection from canonical tenant, provider connection, recent operation, findings, stored reports, tenant review or review pack, and audit truth in apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php
  • T008 [US1] Add the read-only Open support diagnostics header action and preview rendering on the tenant dashboard with capability gating after membership and entitlement are established in apps/platform/app/Filament/Pages/TenantDashboard.php
  • T009 [US1] Keep tenant-context provider excerpts and redaction notes on shared provider-owned helpers instead of page-local wording in apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php, apps/platform/app/Support/Providers/ProviderReasonTranslator.php, and apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php

Checkpoint: User Story 1 is independently functional when an entitled operator can open a tenant bundle and identify the current issue plus the next canonical records to inspect without seeing raw payload content.

Phase 4: User Story 2 - Open A Run-Centered Support-Safe Bundle (Priority: P1)

Goal: An entitled operator already inspecting one run can open the same support-safe contract from the canonical operation detail surface and keep existing run language and navigation semantics.

Independent Test: Seed a failed or degraded run with related provider, finding, report, review, and audit truth, open support diagnostics from the tenantless operation detail viewer, and confirm the preview reuses humanized run wording plus canonical links only.

Tests for User Story 2

  • T010 [P] [US2] Add operation-context feature coverage for reused humanized run summary, canonical related links, explicit redaction markers, and deny-as-not-found boundaries in apps/platform/tests/Feature/SupportDiagnostics/OperationRunSupportDiagnosticActionTest.php

Implementation for User Story 2

  • T011 [US2] Implement operation-context bundle collection by reusing the current run explanation builder and run-bound related-record truth in apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php and apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php
  • T012 [US2] Add the read-only Open support diagnostics header action to the canonical tenantless operation viewer and enforce support_diagnostics.view only after existing run access has resolved an entitled tenant scope in apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php and apps/platform/app/Policies/OperationRunPolicy.php
  • T013 [US2] Reuse canonical operation and related-record navigation instead of support-local URLs in apps/platform/app/Support/OperationRunLinks.php, apps/platform/app/Support/Navigation/RelatedNavigationResolver.php, and apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php

Checkpoint: User Story 2 is independently functional when the run detail surface can open the same support bundle contract without changing OperationRun lifecycle truth or introducing a second link vocabulary.

Phase 5: User Story 3 - Rely On Deterministic, Redacted Support Summaries (Priority: P2)

Goal: The same authorized tenant or run input always produces the same ordered, machine-readable, redacted support bundle so later tooling can reuse it safely.

Independent Test: Generate the same authorized tenant and run bundles repeatedly against unchanged truth and confirm stable section order, stable reference order, explicit missing or inaccessible placeholders, and redaction markers for sensitive provider detail.

Tests for User Story 3

  • T014 [P] [US3] Add unit coverage for stable section order, stable reference order, and graceful missing or inaccessible degradation in apps/platform/tests/Unit/Support/SupportDiagnostics/SupportDiagnosticBundleBuilderTest.php
  • T015 [P] [US3] Add unit coverage for redaction markers, translated high-level provider reasons, and excluded raw payload fields in apps/platform/tests/Unit/Support/SupportDiagnostics/SupportDiagnosticBundleRedactionTest.php
  • T016 [P] [US3] Add shared feature coverage for cross-surface authorization boundaries so non-members or non-entitled actors stay 404 and capability-denied members stay 403 in apps/platform/tests/Feature/SupportDiagnostics/SupportDiagnosticAuthorizationTest.php
  • T017 [P] [US3] Add feature coverage for bundle-open audit entries with redacted metadata for both tenant and run contexts, and assert that opening diagnostics stays DB-only, performs no outbound HTTP, dispatches no provider-backed work, creates no new OperationRun, and emits no queued OperationRun-start side effect, in apps/platform/tests/Feature/SupportDiagnostics/SupportDiagnosticAuditTest.php

Implementation for User Story 3

  • T018 [US3] Finalize deterministic ordering, freshness and completeness cues, explicit missing or inaccessible placeholders, and redaction-marker output in apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php and apps/platform/app/Support/RedactionIntegrity.php
  • T019 [US3] Wire bundle-open audit recording from both read-only actions without storing excluded payload content in apps/platform/app/Filament/Pages/TenantDashboard.php, apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php, apps/platform/app/Support/Audit/AuditActionId.php, and apps/platform/app/Services/Audit/WorkspaceAuditLogger.php

Checkpoint: User Story 3 is independently functional when bundle output is deterministic, redacted, machine-readable, and auditable across both approved contexts.

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Align the final contract docs, format touched files, and run the narrow validation set for this slice.

  • T020 [P] Update the support-diagnostics contract and manual validation notes to match the final tenant and run action behavior in specs/241-support-diagnostic-pack/contracts/support-diagnostics.openapi.yaml and specs/241-support-diagnostic-pack/quickstart.md
  • T021 [P] Run Laravel Pint on touched PHP files through Sail before merge using apps/platform/vendor/bin/sail
  • T022 Run the targeted unit and feature validation commands listed in specs/241-support-diagnostic-pack/quickstart.md after implementation completes, explicitly using those suites to prove the DB-only / no outbound HTTP / no queued OperationRun-start side-effect contract via apps/platform/tests/Unit/Support/SupportDiagnostics/SupportDiagnosticBundleBuilderTest.php, apps/platform/tests/Unit/Support/SupportDiagnostics/SupportDiagnosticBundleRedactionTest.php, apps/platform/tests/Feature/SupportDiagnostics/TenantSupportDiagnosticActionTest.php, apps/platform/tests/Feature/SupportDiagnostics/OperationRunSupportDiagnosticActionTest.php, apps/platform/tests/Feature/SupportDiagnostics/SupportDiagnosticAuthorizationTest.php, and apps/platform/tests/Feature/SupportDiagnostics/SupportDiagnosticAuditTest.php
  • T023 Record the final guardrail close-out, lane result, and any bounded document-in-feature versus follow-up-spec note for shared-helper or provider-boundary adjustments in specs/241-support-diagnostic-pack/plan.md and specs/241-support-diagnostic-pack/quickstart.md

Dependencies & Execution Order

Phase Dependencies

  • Phase 1 (Setup) starts immediately.
  • Phase 2 (Foundational) depends on Phase 1 and blocks all user stories.
  • Phase 3 (US1) depends on Phase 2 and establishes the MVP tenant-context bundle.
  • Phase 4 (US2) depends on Phase 2 and is safest after US1 in practice because both stories extend apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php and the same canonical navigation helpers.
  • Phase 5 (US3) depends on US1 and US2 because it hardens deterministic output, shared authorization proof, and audit behavior across both approved contexts.
  • Phase 6 (Polish) depends on every implemented story.

User Story Dependencies

  • US1 is the MVP and the first independently shippable increment.
  • US2 remains independently testable, but it reuses the same builder and helper seams as US1, so merge order should favor US1 first.
  • US3 depends on both P1 stories because deterministic ordering, redaction, authorization proof, and audit proof must cover the shared bundle contract across both contexts.

Within Each User Story

  • Write the listed Pest coverage first and ensure it fails before implementation.
  • Complete shared builder or helper changes before the final page-action rendering pass when both are required.
  • Re-run the narrowest affected unit or feature suite after each story checkpoint before moving to the next story.

Parallel Opportunities

Phase 1

  • T001 and T002 can run in parallel if one person confirms the feature documents while another verifies the shared code seams.

Phase 2

  • T004 and T005 can run in parallel after T003 defines the shared bundle shell.

User Story 1

  • T006 can start before runtime edits.
  • T008 and T009 can overlap once T007 establishes the tenant-context bundle payload.

User Story 2

  • T010 can start before runtime edits.
  • T012 and T013 can overlap once T011 establishes the run-context bundle payload.

User Story 3

  • T014, T015, T016, and T017 can run in parallel.
  • T018 and T019 should stay sequential because both finalize the shared builder and action audit flow.

Implementation Strategy

MVP First

  1. Complete Phase 1.
  2. Complete Phase 2.
  3. Complete Phase 3 (US1).
  4. Re-run the targeted tenant-context suite and stop for review.

Incremental Delivery

  1. Deliver US1 to compress tenant-context support work first.
  2. Add US2 to bring the same contract to the canonical run-detail surface.
  3. Add US3 to harden deterministic output, redaction, authorization, and audit proof across both contexts.

Team Strategy

  1. Finish Phase 2 together before splitting work.
  2. Parallelize test authoring inside each story.
  3. Sequence merges carefully around apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php, because all three stories extend the same shared bundle contract.