--- description: "Task breakdown for Spec 075 (Verification Checklist Framework V1.5)" --- # Tasks: Verification Checklist Framework V1.5 (075) **Input**: Design documents from `/specs/075-verification-v1-5/` **Tests**: REQUIRED (Pest) ## Phase 1: Setup (Shared Infrastructure) **Purpose**: Align feature artifacts with the existing 074 verification implementation (report shape, DB-only viewing constraints). - [X] T001 Reconcile v1.5 report contract to match the V1 report shape (`schema_version`, `flow`, `generated_at`, `summary`, `checks[]`) + v1.5 fields (`fingerprint`, `previous_report_id`) and allow empty-string `severity` (missing → empty) in specs/075-verification-v1-5/contracts/verification-report.v1_5.schema.json - [X] T002 [P] Confirm viewer surfaces are DB-only using existing guard helpers in tests/Support/AssertsNoOutboundHttp.php (helper availability + correct usage patterns) - [X] T003 [P] Identify all report viewer templates to update: resources/views/filament/components/verification-report-viewer.blade.php and resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Shared primitives required by all user stories (schema/sanitization, stable fingerprint, previous report resolution). **⚠️ CRITICAL**: Complete this phase before implementing US1/US2/US3. - [X] T004 Update report schema to allow v1.5 metadata fields (`fingerprint`, `previous_report_id`) and allow empty-string `severity` (missing → empty) in app/Support/Verification/VerificationReportSchema.php - [X] T005 Update report sanitizer to preserve v1.5 metadata fields (`fingerprint`, `previous_report_id`) and preserve empty-string `severity` (missing → empty) in app/Support/Verification/VerificationReportSanitizer.php - [X] T006 [P] Add a deterministic fingerprint helper in app/Support/Verification/VerificationReportFingerprint.php (flatten `checks[]`; normalize missing `severity` to empty string, not `info`) - [X] T007 Add a previous-report resolver helper in app/Support/Verification/PreviousVerificationReportResolver.php - [X] T008 [P] Add or update verification badge mapping tests in tests/Feature/Badges/ to cover all v1.5-used status-like values (BADGE-001) **Checkpoint**: Schema + sanitizer accept v1.5 fields; fingerprint + previous-report resolver are available for use. --- ## Phase 3: User Story 1 — Operator can tell “nothing changed” (Priority: P1) 🎯 MVP **Goal**: Persist a deterministic `fingerprint` + `previous_report_id` on each report, and show “Changed / No changes” when a previous report exists. **Independent Test**: Create two completed verification runs for the same identity with identical normalized outcomes; confirm viewer indicates “No changes since previous verification”. ### Tests for User Story 1 (write first) - [X] T009 [P] [US1] Add fingerprint determinism unit tests in tests/Feature/Verification/VerificationReportFingerprintTest.php (including missing severity → empty string, and severity-only changes → different hash) - [X] T010 [P] [US1] Add previous report identity matching tests (provider_connection_id exact match; NULL matches NULL) and a regression proving cross-connection runs don’t match when run_identity_hash includes provider_connection_id in tests/Feature/Verification/PreviousVerificationReportResolverTest.php ### Implementation for User Story 1 - [X] T011 [US1] Compute and persist report fingerprint in app/Support/Verification/VerificationReportWriter.php (use app/Support/Verification/VerificationReportFingerprint.php) - [X] T012 [US1] Resolve and persist previous_report_id during write in app/Support/Verification/VerificationReportWriter.php (use app/Support/Verification/PreviousVerificationReportResolver.php + run_identity_hash; verify all verification run start paths include provider_connection_id in identityInputs) - [X] T013 [P] [US1] Extend DB-only report viewer helper to expose v1.5 metadata in app/Filament/Support/VerificationReportViewer.php - [X] T014 [US1] Add change-indicator computation for viewer surfaces in app/Filament/Support/VerificationReportChangeIndicator.php **Checkpoint**: Report JSON includes `fingerprint` + `previous_report_id`; viewer can derive Changed/No changes. --- ## Phase 4: User Story 2 — Owner/Manager can acknowledge a known issue (Priority: P1) **Goal**: Acknowledge `fail` / `warn` checks per report with confirmation + audit, without changing check outcomes. **Independent Test**: Attempt to acknowledge a failing check (a) as non-member → 404, (b) as member without capability → 403, (c) with capability → record created + audit logged. ### Tests for User Story 2 (write first) - [X] T015 [P] [US2] Add acknowledgement authorization + audit tests in tests/Feature/Verification/VerificationCheckAcknowledgementTest.php (404 non-member, 403 missing capability, persists optional expires_at; audit metadata includes check_key + reason_code and excludes ack_reason) ### Implementation for User Story 2 - [X] T016 [US2] Create migration for verification_check_acknowledgements table (includes optional expires_at; informational only) in database/migrations/*_create_verification_check_acknowledgements_table.php - [X] T017 [P] [US2] Create model in app/Models/VerificationCheckAcknowledgement.php - [X] T018 [P] [US2] Create factory for acknowledgements in database/factories/VerificationCheckAcknowledgementFactory.php - [X] T019 [US2] Implement acknowledgement creation service in app/Services/Verification/VerificationCheckAcknowledgementService.php (server-side authorization via Gate/policy; validate status ∈ {fail,warn}; validate optional expires_at; enforce unique per (operation_run_id, check_key)) - [X] T020 [P] [US2] Register capability constant tenant_verification.acknowledge in app/Support/Auth/Capabilities.php - [X] T021 [P] [US2] Map tenant_verification.acknowledge to tenant roles in app/Services/Auth/RoleCapabilityMap.php - [X] T022 [P] [US2] Add audit action id for acknowledgement in app/Support/Audit/AuditActionId.php (e.g. verification.check_acknowledged) - [X] T023 [US2] Emit audit event with minimal metadata via app/Services/Audit/WorkspaceAuditLogger.php from the acknowledgement path (MUST include: tenant_id, operation_run_id/report_id, flow, check_key, reason_code; MUST NOT include ack_reason) **Checkpoint**: Acknowledgements are persisted, authorized, confirmed in UI (next story), and audited with minimized metadata. --- ## Phase 5: User Story 3 — Verify step is operator-ready (issues-first) (Priority: P1) **Goal**: Issues-first view, centralized badge semantics (BADGE-001), DB-only hint, and exactly one primary CTA depending on state. **Independent Test**: Seed a run with blockers while completed and while running; confirm Issues is default, ordering rules hold, and one-primary-CTA rule holds. ### Tests for User Story 3 (write first) - [X] T024 [P] [US3] Add Verify-step CTA and ordering tests in tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php - [X] T025 [P] [US3] Add DB-only render guard test coverage for Verify surfaces in tests/Feature/Verification/VerificationReportViewerDbOnlyTest.php ### Implementation for User Story 3 - [X] T026 [US3] Enforce “exactly one primary CTA” logic in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php (start vs refresh) - [X] T027 [US3] Refactor Verify-step report view to issues-first tabs + ordering + DB-only hint in resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php - [X] T028 [US3] Add per-check acknowledgement action UI with confirmation in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php (Action::make(...)->action(...)->requiresConfirmation()) - [X] T029 [US3] Wire acknowledgement UI to service + RBAC semantics (404 non-member, 403 missing capability; server-side enforcement required) in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php - [X] T030 [US3] Update the Monitoring viewer to match v1.5 UX rules (issues-first tabs: Issues default, Passed, Technical details; ordering; next-steps max 2) in resources/views/filament/components/verification-report-viewer.blade.php - [X] T031 [P] [US3] Show change indicator + previous report link in technical details (no raw payloads) in resources/views/filament/components/verification-report-viewer.blade.php **Checkpoint**: Verify UX is deterministic, issues-first, and operator-ready across onboarding and monitoring surfaces. --- ## Phase 6: Polish & Cross-Cutting Concerns **Purpose**: Hardening, formatting, and regression coverage. - [X] T032 [P] Ensure acknowledgement does not mutate check status/summary in app/Support/Verification/VerificationReportWriter.php and cover with assertions in tests/Feature/Verification/VerificationCheckAcknowledgementTest.php - [X] T033 [P] Add redaction regression checks for new v1.5 fields (fingerprint/previous_report_id) in tests/Feature/Verification/VerificationReportRedactionTest.php - [X] T034 [P] Run Pint on changed files via vendor/bin/sail bin pint --dirty - [X] T035 Run focused test suite via vendor/bin/sail artisan test --compact --filter=Verification --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: start immediately - **Foundational (Phase 2)**: blocks all user stories - **User Stories (Phase 3–5)**: - US1 depends on Phase 2 - US2 depends on Phase 2 - US3 depends on Phase 2 and benefits from US1 + US2 completion - **Polish (Phase 6)**: after US1–US3 ### User Story Dependencies (Graph) - **US1 (Fingerprint + previous report + changed indicator)** → enables technical details and “Changed/No changes” banner in US3 - **US2 (Acknowledgements)** → enables “Acknowledged issues” grouping and action UX in US3 - **US3 (Verify UX)** → integrates outputs of US1 + US2 into operator surface --- ## Parallel Execution Examples ### US1 - Run in parallel: - T009 (fingerprint determinism tests) + T010 (previous resolver tests) - T013 (viewer helper exposure) can proceed while T011/T012 land ### US2 - Run in parallel: - T017 (model) + T018 (factory) + T020 (capability constant) + T021 (role mapping) + T022 (audit action id) ### US3 - Run in parallel: - T024 (UX tests) + T025 (DB-only tests) - T027 (onboarding blade refactor) + T030 (monitoring viewer refactor) --- ## Implementation Strategy ### MVP First (US1) 1. Phase 1 → Phase 2 2. Implement US1 (Phase 3) 3. Validate: run T035 and confirm “No changes since previous verification” path ### Incremental Delivery 1. US1 (supportability) → US2 (governance) → US3 (operator UX) 2. After each story, run story-specific tests plus `vendor/bin/sail artisan test --compact --filter=Verification`