TenantAtlas/specs/075-verification-v1-5/spec.md

Feature Specification: Verification Checklist Framework V1.5 (Governance + Supportability + UI-Complete)

Feature Branch: 075-verification-v1_5
Created: 2026-02-05
Status: Draft
Input: User description: "Extend verification checklist framework with report fingerprint + previous report change indicator, per-check acknowledgements with audit/confirmation, and issues-first operator-ready verify-step UX."

Goal

V1.5 extends the V1 verification checklist framework with two enterprise-critical additions while keeping scope intentionally small:

1. Supportability / determinism: show whether results changed since the previous verification for the same identity.
2. Governance: allow explicit, auditable acknowledgement of known issues per failing check.
3. Enterprise UX completeness: make the Verify step operator-ready (issues-first, one clear primary action, technical details secondary).

Clarifications

Session 2026-02-05

• Q: How is “block” represented on checks? → A: No new status; a “Blocker” is status=fail with blocking=true.
• Q: Should severity be part of the fingerprint? → A: Yes; include severity always (normalize missing to empty) to keep hashing deterministic and to treat severity-only changes as “Changed”.
• Q: Should ack_reason be included in the audit event payload? → A: No; keep audit metadata minimal and store the reason only in the acknowledgement record.
• Q: How should provider_connection_id be treated when resolving previous_report_id? → A: Match exactly; NULL only matches NULL (no cross-connection mixing).
• Report shape (canonical, inherited from 074): Persist reports as the existing V1 JSON shape (schema_version, flow, generated_at, summary, checks[]). V1.5 adds fingerprint + previous_report_id at the top level. No sections[] array is stored.
• Idempotency (inherited): Deduplication applies only while a run is active (queued / running). Once completed / failed, starting verification creates a new run.
• Viewing (inherited): Viewing is DB-only; rendering MUST NOT perform external calls.
• Evidence (inherited): Evidence is limited to safe pointers only; no secrets (no tokens/claims/headers/raw payloads).
• Next steps (inherited): Navigation-only links (no server-side “fix it” actions from the viewer).

User Scenarios & Testing (mandatory)

User Story 1 - Operator can tell “nothing changed” (Priority: P1)

As an operator, I can immediately see whether the current verification findings are unchanged compared to the previous verification for the same identity, so I can avoid unnecessary re-diagnosis.

Why this priority: This is the fastest path to supportability: it reduces repeated analysis and makes troubleshooting deterministic.

Independent Test: Create two reports for the same identity with identical normalized check outcomes; confirm the viewer indicates “No changes since previous verification”.

Acceptance Scenarios:

1. Given a report with a previous report available, When I open the viewer, Then I see a clear indicator “Changed” or “No changes”.
2. Given the current report has the same fingerprint as the previous report, When I open the viewer, Then I see “No changes since previous verification”.

---

User Story 2 - Owner/Manager can acknowledge a known issue (Priority: P1)

As an owner/manager, I can acknowledge a failing/warning/blocking check with a short reason (and optionally an expiry) so the team can see that the risk is known, evaluated, and accepted.

Why this priority: Acknowledgements provide governance without masking risk; they improve shared context and auditability.

Independent Test: With and without the acknowledgement capability, attempt to acknowledge a failing check; assert correct authorization (403) and that an audit event is recorded for the successful path.

Acceptance Scenarios:

1. Given a check in status fail / warn (including failing blockers where blocking=true), When I acknowledge it with a reason, Then the UI shows who acknowledged it, when, and the reason.
2. Given I do not have the acknowledgement capability, When I attempt to acknowledge a check, Then the server returns 403 and the UI does not offer the acknowledgement action.

---

User Story 3 - Verify step is operator-ready (issues-first) (Priority: P1)

As a workspace member, I see issues-first results with clear next steps and exactly one primary action (start or refresh), so I can remediate quickly without hunting through technical details.

Why this priority: The Verify step is a high-frequency operator surface; clarity and deterministic states reduce time-to-resolution.

Independent Test: Seed a report with blockers and a running state; confirm the default tab and “one primary CTA” rule is enforced in both completed and running scenarios.

Acceptance Scenarios:

1. Given a report with blockers, When I open the Verify step/viewer, Then the Issues tab is the default and blockers are at the top.
2. Given a run is active, When I open the Verify step/viewer, Then the primary action is “Refresh results” and technical links are secondary.

---

Edge Cases

• No previous report exists for an identity → no “changed/no-change” indicator is shown.
• Run is active but no report is available yet → UI shows a clear “running, results will appear” explanation (no empty states without guidance).
• Partial report while running → partial results render with a “Partial results” label.
• Unknown check keys or reason codes → UI degrades gracefully, showing status and message without breaking.
• Acknowledgement attempted for non-acknowledgeable status (e.g., pass) → request is rejected and UI does not offer it.

Out of Scope

• Diff/compare UI between reports
• Server-side fixes initiated from the viewer
• Undo / unacknowledge acknowledgements (V1.5 acknowledgements are immutable per report)
• Complex staleness/TTL semantics (fresh/stale/expired)
• Global dashboards / cross-tenant reporting
• Export features (PDF/JSON) as a product feature
• Live polling (V1.5 uses manual refresh)

Requirements (mandatory)

Constitution alignment (required): This feature adds new tenant-scoped mutations (acknowledgements) and new report metadata. It MUST include explicit confirmation, audit logging for mutations, tenant isolation, and tests.

Constitution alignment (RBAC-UX): Tenant-scoped routes MUST preserve deny-as-not-found (404) for non-members, and use 403 for members missing a capability. UI visibility is not authorization; server-side enforcement is required.

Constitution alignment (BADGE-001): Status-like badges MUST use centralized mapping semantics; no ad-hoc UI mappings.

Functional Requirements

• FR-075-001 — Report fingerprint: Each verification report MUST store a deterministic fingerprint derived from normalized check outcomes.

  Normalization rule (deterministic):

  • Flatten all check results across report.checks[]
  • Sort by stable check.key
  • For each check, contribute a stable string using: key | status | blocking | reason_code | severity
    • severity MUST be included always; if the source report omits it, normalize to an empty string
  • The fingerprint MUST be a stable cryptographic hash of the joined contributions, stored as a fixed-length lowercase hex string.

• FR-075-002 — Previous report link: Each report MUST store previous_report_id (nullable) that points to the most recent earlier report for the same verification identity.

  Identity match MUST include:

  • flow
  • workspace
  • tenant
  • provider connection (provider_connection_id) matched exactly; NULL only matches NULL

• FR-075-003 — Change indicator: When a previous report exists, the viewer MUST show:

  • “No changes since previous verification” if fingerprint matches
  • “Changed since previous verification” otherwise

• FR-075-004 — Per-check acknowledgements (first-class): The system MUST allow acknowledging checks with status fail / warn.

  An acknowledgement MUST record:

  • reason (max 160 characters)
  • acknowledged timestamp
  • acknowledged-by user
  • optional expiry timestamp

  Acknowledgements MUST be unique per (report, check key). Expiry, when provided, is informational only in V1.5 and MUST NOT introduce automatic staleness/TTL behavior.

• FR-075-005 — Acknowledgement does not change outcomes: Acknowledging MUST NOT change:

  • the check status
  • the report summary status/outcome
  • the run outcome

• FR-075-006 — Acknowledgement allowed conditions: Acknowledgement MUST only be possible for checks whose status is in {fail, warn}. It MUST NOT be available for passing/green checks.

  A check is considered a Blocker when status=fail and blocking=true; blockers are acknowledgeable under the same {fail, warn} rule (no separate block status exists).

• FR-075-007 — Acknowledgement authorization (capability-first): Acknowledgement MUST require the capability tenant_verification.acknowledge as defined in the canonical capability registry.

  RBAC UX semantics:

  • non-member / not entitled to tenant scope → 404
  • member without acknowledgement capability → 403
  • members with tenant scope but without acknowledgement capability can still view reports (view remains read-only)

• FR-075-007A — Viewing authorization semantics preserved (inherited): Viewing tenant-scoped verification pages (Verify step + report viewer) MUST preserve V1 semantics:

  • non-member / not entitled to tenant scope → 404
  • member with tenant scope → can view
  • capability checks apply to mutations only (start verification, acknowledgement)

• FR-075-008 — Confirmation + audit required: Acknowledgement is a mutation and MUST require explicit user confirmation and MUST emit an audit event.

• FR-075-009 — Audit event metadata (minimal): The audit event for acknowledgement MUST include minimally:

  • workspace, tenant, run, report, flow
  • check key and reason code
  • acknowledged-by user

  It MUST NOT include ack_reason, secrets, tokens, or raw payloads.

• FR-075-010 — DB-only viewing guard (inherited): Rendering the viewer and the Verify step MUST NOT trigger external calls.

• FR-075-011 — Centralized badge semantics (BADGE-001): All check-status badges and summary-status badges used by V1.5 MUST use the centralized badge mapping registry.

• FR-075-012 — Verify step enterprise UX (normative): The Verify step/viewer MUST follow an issues-first layout and deterministic UI states:

  Structure

  • Always-visible summary card
  • Tabs: Issues (default), Passed, Technical details

  DB-only hint

  • The summary surface MUST include a clear hint that viewing is read-only and performs no external calls.

  Primary action rule (strict)

  • Exactly one primary call-to-action is shown at any time
  • “Start verification” and “Refresh results” MUST NOT both be primary simultaneously

  Issues tab ordering

  1. Blockers (not acknowledged)
  2. Failures (not acknowledged)
  3. Warnings (not acknowledged)
  4. Acknowledged issues (collapsed group)

  Next steps rendering

  • Max 2 navigation-only links per issue card
  • “Open run details” MUST appear only in Technical details (not in issue cards)

  Technical details

  • Secondary surface that can show identifiers (run/report IDs), fingerprint, and previous report link
  • No raw payloads/tokens/full error bodies

Key Entities (include if feature involves data)

• Verification Identity: The stable identifiers that define “what is being verified” (flow, workspace, tenant, and optional provider connection).
• Verification Report: A structured record of verification outcomes for a run.
• Report Fingerprint: A deterministic hash representing normalized check outcomes.
• Previous Report: The immediately preceding report for the same identity.
• Check Acknowledgement: A governance record that an issue is known/accepted (who/when/reason/optional expiry) without altering the check outcome.

Assumptions

• A verification run/report concept already exists from V1.
• The system has an audit log mechanism capable of recording acknowledgement actions.
• Manual refresh is acceptable (no polling required).

Dependencies

• Spec 074 (Verification Checklist Framework V1)

Success Criteria (mandatory)

Measurable Outcomes

• SC-075-001 (Supportability): With a previous report present, operators can determine “changed vs no changes” within 10 seconds in 95% of tested sessions.
• SC-075-002 (Governance): 100% of successful acknowledgements create an audit log record with minimal metadata and no sensitive content.
• SC-075-003 (UX determinism): The Verify step renders exactly one primary CTA in all tested UI states (not started, running with/without report, completed).
• SC-075-004 (Authorization correctness): Non-members receive 404 for tenant-scoped access routes in 100% of tests; members without acknowledgement capability receive 403 for acknowledgement attempts in 100% of tests.
• SC-075-005 (No greenwashing): Acknowledging an issue never changes check status or the report summary in any tested scenario.