ahmido
53dc89e6ef
Implements Spec 075 (V1.5) on top of Spec 074. Highlights - Deterministic report fingerprint (sha256) + previous_report_id linkage - Viewer change indicator: "No changes" vs "Changed" when previous exists - Check acknowledgements (fail|warn|block) with capability-first auth, confirmation, and audit event - Verify-step UX polish (issues-first, primary CTA) Testing - Focused Pest coverage for fingerprint, previous resolver, change indicator, acknowledgements, badge semantics, DB-only viewer guard. Notes - Viewing remains DB-only (no external calls while rendering). Co-authored-by: Ahmed Darrazi <ahmeddarrazi@MacBookPro.fritz.box> Reviewed-on: #93
173 lines
11 KiB
Markdown
173 lines
11 KiB
Markdown
---
|
||
|
||
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`
|