TenantAtlas/specs/084-verification-surfaces-unification/tasks.md

description
Task list for Spec 084 implementation

Tasks: Verification Surfaces Unification

Input: Design documents from /specs/084-verification-surfaces-unification/

Tests: REQUIRED (Pest) — this feature changes runtime behavior.

Phase 1: Setup (Shared Infrastructure)

Purpose: Establish a safe baseline and align on touched surfaces.

• T001 Capture baseline behavior by running existing verification tests in tests/Feature/Verification/VerificationStartDedupeTest.php and tests/Feature/ProviderConnections/ProviderOperationBlockedGuidanceSpec081Test.php
• T002 Identify current tenant “Verify configuration” surface implementation in app/Filament/Resources/TenantResource/Pages/ViewTenant.php and document expected deltas in specs/084-verification-surfaces-unification/quickstart.md

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Shared primitives required by ALL user stories.

⚠️ CRITICAL: No user story work should begin until this phase is complete.

• T003 Add schema-valid stub verification report for blocked provider.connection.check runs in app/Services/Providers/ProviderOperationStartGate.php (write context.verification_report after finalizeBlockedRun)
• T004 [P] Add helper to build blocked/preflight verification checks payload in app/Support/Verification/ (e.g., new BlockedVerificationReportFactory.php used by ProviderOperationStartGate)
• T005 Add a non-breaking tenant-default start helper in app/Services/Verification/StartVerification.php (keep existing explicit-connection API; delegate default-connection resolution to ProviderOperationStartGate)
• T006 Ensure blocked stub report includes next steps links from context.next_steps and normalized reason_code from context.reason_code in app/Support/Verification/BlockedVerificationReportFactory.php
• T007 Add Pest coverage for blocked stub report invariant in tests/Feature/Verification/ (new test file asserting completed blocked provider.connection.check has context.verification_report and it validates via VerificationReportSchema)
• T027 Enforce tenant entitlement for tenant-associated runs in app/Policies/OperationRunPolicy.php and app/Filament/Pages/Operations/TenantlessOperationRunViewer.php (deny-as-not-found when workspace membership or tenant entitlement is missing)

Checkpoint: A blocked provider.connection.check run always has a schema-valid stored report.

---

Phase 3: User Story 1 — Verify tenant configuration consistently (Priority: P1) 🎯 MVP

Goal: Start verification from tenant detail view and render the latest stored report DB-only.

Independent Test: Trigger the tenant verify action and confirm it creates/dedupes an OperationRun and the tenant embedded viewer renders from stored run context only.

Tests (write first)

• T008 [P] [US1] Update tests/Feature/ProviderConnections/ProviderOperationBlockedGuidanceSpec081Test.php to assert tenant verify start now creates a blocked OperationRun and includes a schema-valid verification_report stub
• T009 [P] [US1] Add tenant verify happy-path test in tests/Feature/Filament/ (new test file calling ViewTenant action and asserting ProviderConnectionHealthCheckJob dispatch + canonical view-run link)
• T010 [P] [US1] Add tenant embedded viewer DB-only test in tests/Feature/Filament/ (new test asserting the widget/view reads OperationRun.context only; no provider calls during render)
• T032 [P] [US1] Add FR-007 regression test in tests/Feature/Filament/ asserting tenant view render path never triggers synchronous verification or permission inventory persistence

Implementation

• T011 [US1] Refactor “Verify configuration” action in app/Filament/Resources/TenantResource/Pages/ViewTenant.php to start/dedupe provider.connection.check via app/Services/Verification/StartVerification.php (no synchronous Graph work)
• T012 [US1] Apply UI enforcement to the tenant verify action in app/Filament/Resources/TenantResource/Pages/ViewTenant.php using App\Support\Rbac\UiEnforcement with Capabilities::PROVIDER_RUN (visible-but-disabled; server still 403)
• T013 [US1] Ensure tenant verify notifications include a canonical tenantless “View run” link using App\Support\OperationRunLinks::tenantlessView in app/Filament/Resources/TenantResource/Pages/ViewTenant.php
• T033 [US1] Refactor tenant list “Verify configuration” action in app/Filament/Resources/TenantResource.php to the same unified provider.connection.check start path + canonical tenantless run links
• T014 [P] [US1] Create a tenant verification viewer widget class in app/Filament/Widgets/Tenant/TenantVerificationReport.php (select latest provider.connection.check run for the current tenant)
• T015 [P] [US1] Create widget view resources/views/filament/widgets/tenant/tenant-verification-report.blade.php with states: empty (Start verification CTA), in-progress, completed (render filament.components.verification-report-viewer)
• T016 [US1] Register the tenant verification viewer widget on the tenant view page by updating app/Filament/Resources/TenantResource/Pages/ViewTenant.php getHeaderWidgets() to include TenantVerificationReport
• T017 [US1] Implement the embedded viewer “Start verification” CTA to invoke the same unified start path (StartVerification) in app/Filament/Widgets/Tenant/TenantVerificationReport.php
• T018 [US1] Ensure the embedded viewer “View run” link uses OperationRunLinks::tenantlessView in app/Filament/Widgets/Tenant/TenantVerificationReport.php and resources/views/filament/widgets/tenant/tenant-verification-report.blade.php

Checkpoint: US1 works end-to-end using queued OperationRun and DB-only rendering.

---

Phase 4: User Story 2 — Onboarding verify access behaves identically (Priority: P2)

Goal: Onboarding verification uses the same run type, dedupe/busy semantics, and viewer behavior.

Independent Test: Start verification in onboarding twice and assert dedupe/busy behavior and canonical links match tenant surface.

Tests

• T019 [P] [US2] Update tests/Feature/Onboarding/OnboardingVerificationTest.php to assert busy/deduped notifications link to the canonical tenantless operations viewer route
• T020 [P] [US2] Add regression test ensuring onboarding verification uses provider.connection.check and stores verification_report in tests/Feature/Onboarding/OnboardingVerificationTest.php

Implementation

• T021 [US2] Ensure app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php startVerification() uses the same unified provider.connection.check start mechanism (ProviderOperationStartGate) and remains enqueue-only
• T022 [US2] Ensure onboarding “View run” links remain canonical via OperationRunLinks::tenantlessView (or equivalent tenantlessOperationRunUrl) in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
• T023 [US2] Confirm onboarding verification report rendering uses App\Filament\Support\VerificationReportViewer only (no external calls) in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php

---

Phase 5: User Story 3 — Use canonical run links everywhere (Priority: P3)

Goal: Every verification surface links to the same tenantless run viewer route, and tenantless viewing enforces workspace + tenant entitlement (404 when missing).

Independent Test: From both tenant and onboarding surfaces, follow “View run” and confirm it resolves to the same canonical route and is deny-as-not-found for non-entitled actors.

Tests

• T024 [P] [US3] Add canonical link assertions for tenant verify notifications in tests/Feature/Filament/ (update test from T009 to assert route name admin.operations.view)
• T025 [P] [US3] Add canonical link assertions for onboarding notifications in tests/Feature/Onboarding/OnboardingVerificationTest.php
• T026 [P] [US3] Add authorization test for tenantless run viewer requiring workspace membership + tenant entitlement (404 semantics) in tests/Feature/RunAuthorizationTenantIsolationTest.php

Implementation

• T028 [US3] Ensure all verification surfaces use OperationRunLinks::tenantlessView (or identical canonical route helper) in app/Filament/Resources/TenantResource/Pages/ViewTenant.php and app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Formatting, stability, and quickstart validation.

• T034 Fix tenant page widgets to resolve tenant from record context (Admin panel) and add regression coverage for Recent operations + Start verification disabled state
• T029 Run formatting on changed files using vendor/bin/sail bin pint --dirty (e.g., app/Filament/Resources/TenantResource/Pages/ViewTenant.php, app/Services/Providers/ProviderOperationStartGate.php, tests/Feature/Verification/*)
• T030 Run targeted Pest suite for this feature using vendor/bin/sail artisan test --compact tests/Feature/Verification/ tests/Feature/ProviderConnections/ProviderOperationBlockedGuidanceSpec081Test.php tests/Feature/Onboarding/OnboardingVerificationTest.php tests/Feature/RunAuthorizationTenantIsolationTest.php
• T031 Validate manual flows in specs/084-verification-surfaces-unification/quickstart.md and update it if any step text is now inaccurate

---

Dependencies & Execution Order

• Phase 1 (Setup) → Phase 2 (Foundational) → user stories.
• User stories after Phase 2:
  • US1 (P1) can proceed immediately after Phase 2.
  • US2 (P2) can proceed after Phase 2 (independent of US1).
  • US3 (P3) should run after US1 + US2 (to validate “every surface”).

Dependency Graph (stories)

• Foundation → US1
• Foundation → US2
• US1 + US2 → US3

---

Parallel Execution Examples

US1 parallelizable tasks

• T008, T009, T010, and T032 can be developed in parallel (separate test files).
• T014 and T015 can be developed in parallel (widget class vs Blade view).

US2 parallelizable tasks

• T019 and T020 can be developed in parallel within tests/Feature/Onboarding/.

US3 parallelizable tasks

• T024, T025, T026 can be developed in parallel (different test targets).

---

Implementation Strategy

MVP First (US1)

1. Complete Phase 1–2.
2. Implement US1 tests (T008–T010, T032) → ensure they fail.
3. Implement US1 code (T011–T018, T033) → ensure tests pass.
4. Run Phase 6 tasks to format + verify.

Incremental Delivery

• Add US2 next to remove onboarding/tenant variance.
• Finish with US3 to unify canonical links + tenantless authorization guarantees across all surfaces.