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](./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)

```text
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)

```text
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](./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](./data-model.md)
- [contracts/](./contracts/)
- [quickstart.md](./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.