TenantAtlas/specs/074-verification-checklist/plan.md

Implementation Plan: Verification Checklist Framework (Enterprise-Ready)

Branch: 074-verification-checklist | Date: 2026-02-03 | Spec: spec.md Input: Feature specification from /specs/074-verification-checklist/spec.md

Note: This file is generated from the plan template and then filled in by /speckit.plan workflow steps.

Summary

• Introduce a versioned “verification report” contract that can be attached to an existing OperationRun and rendered consistently across multiple flows.
• Provide a reusable, DB-only report viewer (no outbound calls during render/hydration/poll) that presents summary + per-check statuses + safe evidence pointers + navigation-only next steps.
• Enforce enterprise semantics: stable reason codes, strict evidence redaction, deterministic active-run dedupe, and capability-first authorization aligned with RBAC-UX (non-members 404; members missing start capability 403).
• Emit audit events for verification start + completion using stable action identifiers with redacted metadata.

Technical Context

Language/Version: PHP 8.4 (Laravel 12) Primary Dependencies: Laravel 12 + Filament v5 + Livewire v4 Storage: PostgreSQL (Sail) with JSONB (operation_runs.context) Testing: Pest (PHPUnit) Target Platform: Web application (Sail/Docker locally; container deploy via Dokploy) Project Type: web Performance Goals: Verification viewer renders fast from DB-only JSON (typical report ≤ 50 checks) Constraints: Viewer is read-only and must not trigger any outbound HTTP or job dispatch; evidence must not contain secrets/tokens/payloads; new status-like badges must use centralized BADGE-001 mapping. Scale/Scope: Multiple tenants/workspaces; many runs over time; verification used in onboarding + provider ops + future readiness flows

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• Inventory-first, snapshots-second: PASS (this feature is run/report UX; no inventory semantics changed).
• Read/write separation: PASS (viewer is read-only; start surfaces enqueue-only and already follow OperationRun patterns).
• Graph contract path: PASS (viewer performs no Graph calls; verification execution remains in queued jobs that already follow provider gateway patterns).
• Deterministic capabilities: PASS (start/view gates reference the existing capability registry; no role-string checks).
• RBAC-UX: PASS (non-member tenant access is 404; member-but-missing-capability is 403; server-side gates enforce mutations/starts).
• Run observability: PASS (verification is represented as OperationRun; active-run dedupe enforced by the existing partial unique index on (tenant_id, run_identity_hash) for active statuses).
• Data minimization: PASS (report evidence constrained to safe pointers; audit metadata redacted; no secrets in stored report).
• Badge semantics (BADGE-001): PASS (plan includes adding a centralized badge domain for check statuses/severity; no ad-hoc UI mappings).

Project Structure

Documentation (this feature)

specs/074-verification-checklist/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output
└── tasks.md             # Phase 2 output (/speckit.tasks)

Source Code (repository root)

app/
├── Filament/
├── Jobs/
├── Models/
├── Policies/
├── Services/
└── Support/

config/
database/
resources/
routes/
tests/

Structure Decision: Single Laravel web application with Filament admin panel. The framework is implemented as:

• contract + helpers under app/Support/**
• report writer invoked from queued jobs under app/Jobs/** / app/Services/**
• viewer UI as Filament schema components and Blade views under app/Filament/** and resources/views/filament/**
• authorization via existing capabilities/gates/policies

Complexity Tracking

No constitution violations required for this feature.

Phase 0 — Research (output: research.md)

See: research.md

Goals:

• Confirm the canonical storage location for the report (DB-only render) using existing operation_runs.context JSONB.
• Confirm active-run dedupe behavior and ensure it matches the spec’s “dedupe while active only” requirement.
• Confirm the correct approach for status-like UI badges in Filament (BADGE-001), so the viewer doesn’t introduce ad-hoc mappings.
• Confirm the existing audit logger + redaction utilities and define stable action IDs for verification completion.

Phase 1 — Design & Contracts (outputs: data-model.md, contracts/, quickstart.md)

See:

• data-model.md
• contracts/
• quickstart.md

Design focus:

• Report schema: versioned JSON document (checks + counts + timestamps + next steps) stored in operation_runs.context.verification_report.
• Reason codes: baseline set + reserved ext.* namespace.
• Evidence redaction: strict sanitizer so reports never store or render secrets/tokens/payloads.
• Viewer: reusable Filament view entry / component that renders summary + per-check details without any outbound calls.
• Authorization: view allowed for tenant-scoped members; start requires capability; non-member access is deny-as-not-found.
• Auditing: start + completion events logged with minimal redacted metadata.

Phase 2 — Implementation Outline (tasks created in /speckit.tasks)

• Contract: create a canonical report schema (JSON Schema + example) and a small baseline reason-code list.
• Writer: add a VerificationReportWriter (or equivalent) that normalizes check results, enforces redaction rules, and writes the report into OperationRun->context.
• Viewer: add a reusable Filament UI renderer (Blade view + helper) that displays summary, counts, statuses, and next steps (links-only).
• Integration points:
  • Show the verification report section in Monitoring → Operations run detail when present.
  • Embed the same viewer in onboarding and provider connection verification flows.
• RBAC & UX:
  • Enforce “view vs start” split (view allowed for tenant members; start capability required).
  • Preserve RBAC-UX semantics (non-members 404; members missing capability 403).
• Audit:
  • Keep existing start audit event; add a completion audit event emitted when the verification run finalizes.
• Tests (Pest):
  • Viewer is DB-only (Http::fake + render assertion).
  • Evidence redaction rules (report contains no forbidden keys/values).
  • Dedupe semantics reuse active run (leveraging the existing partial unique index behavior).

Constitution Check (Post-Design)

Re-check result: PASS. Design artifacts keep verification viewing DB-only, align with run observability + dedupe, enforce RBAC-UX semantics, and centralize status badge mappings.