---

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.

- [X] 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`
- [X] 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.

- [X] 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`
- [X] 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`
- [X] 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

- [X] 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

- [X] 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`
- [X] 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`
- [X] 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

- [X] 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

- [X] 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`
- [X] 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`
- [X] 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

- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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

- [X] 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`
- [X] 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.

- [X] 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`
- [X] T021 [P] Run Laravel Pint on touched PHP files through Sail before merge using `apps/platform/vendor/bin/sail`
- [X] 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`
- [X] 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.
