# Research: Verification Checklist Framework (074)

**Date**: 2026-02-03  
**Phase**: Phase 0 (Foundational Research)  
**Status**: Complete

---

## Decisions

### D-001 — Canonical storage location for verification reports

**Decision**: Store the verification report in `operation_runs.context.verification_report` (JSONB).

**Rationale**:
- Monitoring pages must be DB-only at render time (constitution: Operations / Run Observability Standard).
- `OperationRun` is the canonical operational record; keeping the report attached avoids new tables/indexing for v1.
- The existing UI already renders `OperationRun.context` safely as JSON, so we can progressively enhance into a structured viewer.

**Alternatives considered**:
- Dedicated `verification_reports` table: rejected for v1 to keep adoption lightweight; can be introduced later if querying/indexing becomes necessary.

---

### D-002 — Idempotency / dedupe mechanism

**Decision**: Use the existing `OperationRunService::ensureRunWithIdentity()` mechanism and the DB partial unique index on `(tenant_id, run_identity_hash)` for active statuses (`queued`, `running`).

**Rationale**:
- This repo already enforces active-run dedupe at the DB level via `operation_runs_active_unique`.
- Matches the clarified spec policy: dedupe only while a run is active; completed runs allow a new run.

**Alternatives considered**:
- Application-only locks/dedupe: rejected as non-race-safe.

---

### D-003 — Flow identifier and identity scope

**Decision**: Treat `OperationRun.type` as the primary flow identifier for the verification run, and keep additional flow details (wizard step, etc.) in `context`.

**Rationale**:
- Existing operations already key UX semantics (labels, polling, related links) off `OperationRun.type`.
- Dedupe identity hashing already includes `type`, making flow part of the dedupe boundary.

**Alternatives considered**:
- Separate `flow_id` column: rejected for v1 (schema change not required).

---

### D-004 — Reason code taxonomy and extensions

**Decision**: Maintain a small baseline set of cross-cutting reason codes, and reserve `ext.*` for flow/check-specific extensions.

**Rationale**:
- Prevents brittle UI parsing and enables future automation.
- Keeps room for flow-specific details without polluting the baseline vocabulary.

**Alternatives considered**:
- Free-form codes everywhere: rejected due to support/automation cost.

---

### D-005 — Evidence policy (strict safe pointers)

**Decision**: Evidence fields in check results are *strictly* structured safe pointers only (IDs, masked strings, hashes). No payloads, tokens, claims, headers, or full error bodies.

**Rationale**:
- Aligns with constitution data-minimization and safe logging rules.
- Avoids accidentally persisting secrets inside run context.

**Alternatives considered**:
- Storing raw error payloads: rejected for security and compliance risk.

---

### D-006 — UI semantics for statuses and badges

**Decision**: Render status-like values (check status, severity) via centralized badge semantics (BADGE-001), not ad-hoc mappings in feature pages.

**Rationale**:
- Prevents drift in meaning/colors across the suite.
- Enables straightforward regression tests for new/changed status values.

**Alternatives considered**:
- Inline color mapping inside a Blade view: rejected (violates BADGE-001).