ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
50cc0af961
TenantAtlas/specs/075-verification-v1-5/tasks.md

11 KiB
Raw Blame History

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).

  • 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
  • T002 [P] Confirm viewer surfaces are DB-only using existing guard helpers in tests/Support/AssertsNoOutboundHttp.php (helper availability + correct usage patterns)
  • 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.

  • 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
  • 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
  • T006 [P] Add a deterministic fingerprint helper in app/Support/Verification/VerificationReportFingerprint.php (flatten checks[]; normalize missing severity to empty string, not info)
  • T007 Add a previous-report resolver helper in app/Support/Verification/PreviousVerificationReportResolver.php
  • 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)

  • 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)
  • 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

  • T011 [US1] Compute and persist report fingerprint in app/Support/Verification/VerificationReportWriter.php (use app/Support/Verification/VerificationReportFingerprint.php)
  • 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)
  • T013 [P] [US1] Extend DB-only report viewer helper to expose v1.5 metadata in app/Filament/Support/VerificationReportViewer.php
  • 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)

  • 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

  • T016 [US2] Create migration for verification_check_acknowledgements table (includes optional expires_at; informational only) in database/migrations/*_create_verification_check_acknowledgements_table.php
  • T017 [P] [US2] Create model in app/Models/VerificationCheckAcknowledgement.php
  • T018 [P] [US2] Create factory for acknowledgements in database/factories/VerificationCheckAcknowledgementFactory.php
  • 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))
  • T020 [P] [US2] Register capability constant tenant_verification.acknowledge in app/Support/Auth/Capabilities.php
  • T021 [P] [US2] Map tenant_verification.acknowledge to tenant roles in app/Services/Auth/RoleCapabilityMap.php
  • T022 [P] [US2] Add audit action id for acknowledgement in app/Support/Audit/AuditActionId.php (e.g. verification.check_acknowledged)
  • 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)

  • T024 [P] [US3] Add Verify-step CTA and ordering tests in tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php
  • T025 [P] [US3] Add DB-only render guard test coverage for Verify surfaces in tests/Feature/Verification/VerificationReportViewerDbOnlyTest.php

Implementation for User Story 3

  • T026 [US3] Enforce “exactly one primary CTA” logic in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php (start vs refresh)
  • 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
  • T028 [US3] Add per-check acknowledgement action UI with confirmation in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php (Action::make(...)->action(...)->requiresConfirmation())
  • 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
  • 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
  • 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.

  • 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
  • T033 [P] Add redaction regression checks for new v1.5 fields (fingerprint/previous_report_id) in tests/Feature/Verification/VerificationReportRedactionTest.php
  • T034 [P] Run Pint on changed files via vendor/bin/sail bin pint --dirty
  • 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