Skip to main content

UX-REVIEW-AND-APPROVAL.md

This document defines the UX contract for submission review, approval, ratification, and evidence decisioning.

Goal:

  • keep review decisions operationally simple
  • keep decision evidence and rationale defensible
  • keep execution truth immutable while allowing clear projection/triage workflows

Capability Baseline (Validated 2026-02-25)​

Backend-live now:

  • review and approval actions:
    • POST /api/v1/submissions/\{id\}/approve
    • POST /api/v1/submissions/\{id\}/reject
    • POST /api/v1/submissions/\{id\}/review/request
    • POST /api/v1/submissions/\{id\}/review/reopen
  • submission integrity actions:
    • POST /api/v1/submissions/\{id\}/hash
    • POST /api/v1/submissions/\{id\}/ratify
    • POST /api/v1/submissions/\{id\}/void
  • evidence decisions (submission + item scopes):
    • record, amend, approve, reject, verify, void
  • derived review context:
    • koeStatus and dual-time proofReadiness on submission detail/list surfaces
    • defensibility exceptions queues with triage and rollups

Known contract nuance to treat explicitly in UX:

  • OpenAPI currently normalizes approval states with reopening semantics.
  • Review action responses currently emit changes_requested for request-changes action.
  • UX must handle both safely during contract convergence.

0. Review Doctrine (MUST)​

  1. Review changes the review plane, not execution truth.
  2. Approve/reject/request-changes/reopen are high-stakes and must be reason-aware.
  3. Four-eyes policy is enforced by backend and must be visible before action.
  4. Evidence decisions are append-only records; amendments and voids do not erase history.
  5. All reviewer decisions must remain explainable via ledger events and readiness reasons.

0.1 Review Interface Guardrails (MUST)​

  • Decision controls (approve, reject, request changes, reopen) must require deterministic reason capture where policy requires it.
  • Review and evidence panels must be keyboard-complete and screen-reader understandable.
  • Readiness and triage labels must use canonical mappings only (Needs review|Blocked, Open|Acknowledged|Resolved).
  • Triage ownership/suppression UI must be explicit and must not imply mutation of execution truth.
  • Mobile/iPad supports queue inspection and simple triage; dense evidence adjudication can be desktop-optimized with explicit handoff.
  • Conflict/forbidden outcomes must return clear action guidance (for example four-eyes or approval-policy failures).

1. Information Architecture​

Primary screens:

  1. Review Queue
  2. Submission Review Workspace
  3. Decision Drawer (approve/reject/request/reopen)
  4. Ratification Drawer
  5. Evidence Decision Panel

Supporting surfaces:

  • right drawer context links (user, evaluation, engagement, programme requirement)
  • submission hash panel
  • readiness and KOE explanation block

2. Review Queue UX​

Queue purpose:

  • prioritize which submissions need operator action now
  • keep triage state separate from execution truth

Data sources:

  • GET /api/v1/defensibility/exceptions/submissions
  • GET /api/v1/defensibility/exceptions/engagements
  • GET /api/v1/defensibility/exceptions/programme-requirements

Required table columns​

  • subject (submission/engagement/programme requirement)
  • readiness state (backend enum: needs_review or blocked)
  • reason code summary
  • triage state (backend enum: open, acknowledged, resolved)
  • owner
  • first seen / last seen
  • suppressed-until indicator

Status Label Mapping (MUST)​

Queue UI labels must map backend enums deterministically:

  • readiness: needs_review|blocked -> Needs review|Blocked
  • triage: open|acknowledged|resolved -> Open|Acknowledged|Resolved

Rules:

  • use UI labels in chips, filters, and bulk action confirmations.
  • keep backend enum values for request/query payloads only.

Required filters​

  • lens (submission, engagement, programme requirement)
  • triage state (UI labels mapped to backend enum)
  • readiness state (UI labels mapped to backend enum)
  • owner
  • include suppressed toggle (default off)

Required actions​

  • Acknowledge
  • Resolve
  • Set owner
  • Suppress until...
  • Open submission

Queue writes:

  • POST /api/v1/defensibility/exceptions/submissions/{submissionId}/triage
  • POST /api/v1/defensibility/exceptions/engagements/{engagementId}/triage
  • POST /api/v1/defensibility/exceptions/programme-requirements/{programmeRequirementId}/triage
  • POST /api/v1/defensibility/exceptions/submissions/refresh

Rule:

  • triage metadata is mutable projection state and must not be presented as execution truth.

3. Submission Review Workspace​

Primary read:

  • GET /api/v1/submissions/\{id\}

Workspace layout​

  1. Header
  • submission ID
  • execution state
  • review state
  • proofReadiness summary (defensibleAtExecution, readyNow)
  1. Candidate execution block
  • score/outcome (if available)
  • completion timestamps
  • version snapshot scope chips
  1. KOE and readiness explain block
  • K/O/E states with reason chips
  • readiness reason chips
  • computed-against references:
    • snapshot ref
    • policy ref at execution
    • policy ref now
  1. Evidence block
  • evidence decisions timeline
  • verification status indicators
  • actions (record/amend/verify/approve/reject/void)
  1. Decision rail
  • Approve
  • Reject
  • Request changes
  • Reopen review
  • Ratify
  • Void

4. Decision Actions Contract​

All mutating review actions:

  • MUST send Idempotency-Key
  • MUST include deterministic success/failure toast copy
  • SHOULD capture a rationale when risk is high or policy requires it

4.1 Approve / Reject​

Routes:

  • POST /api/v1/submissions/\{id\}/approve
  • POST /api/v1/submissions/\{id\}/reject

Rules:

  • only valid from pending-review state
  • if already decided, show conflict state and next action guidance
  • if four-eyes policy blocks actor, show explicit policy message

4.2 Request Changes / Reopen​

Routes:

  • POST /api/v1/submissions/\{id\}/review/request
  • POST /api/v1/submissions/\{id\}/review/reopen

Rules:

  • request-changes is non-terminal review state
  • reopen returns submission to pending-review decision path
  • UI must tolerate changes_requested and reopening contract variants

4.3 Ratify​

Route:

  • POST /api/v1/submissions/\{id\}/ratify

Requirements:

  • requires step-up proof payload
  • show explicit auth re-check step
  • display resulting ratification event ID

4.4 Void​

Route:

  • POST /api/v1/submissions/\{id\}/void

Rules:

  • void is destructive at the review plane and must require confirmation copy
  • once voided, approval/review actions are disabled

4.5 Hash​

Route:

  • POST /api/v1/submissions/\{id\}/hash

UX behavior:

  • show returned hash with copy action
  • preserve hash history/audit reference where available

5. Evidence Decision UX​

Submission-scope routes:

  • POST /api/v1/submissions/\{id\}/evidence/record
  • POST /api/v1/submissions/\{id\}/evidence/amend
  • POST /api/v1/submissions/\{id\}/evidence/approve
  • POST /api/v1/submissions/\{id\}/evidence/reject
  • POST /api/v1/submissions/\{id\}/evidence/verify
  • POST /api/v1/submissions/\{id\}/evidence/void

Item-scope equivalents:

  • POST /api/v1/submissions/items/\{itemId\}/evidence/...

Evidence UX rules​

  • item and submission scopes must be visually distinct to prevent wrong-scope actions
  • verify is async intent; show queued status and refresh affordance
  • amendments and voids must show lineage to prior event where provided
  • evidence decisions should update readiness/KOE context after refresh

6. Policy and Permission Behaviors​

  1. Four-eyes policy
  • backend may reject approve/reject if reviewer is same as submitter under four-eyes policy
  • UI must show clear non-retryable reason
  1. Capability gating
  • hide unavailable decision actions rather than allowing dead-end clicks
  • keep read-only review surfaces visible where permitted
  1. Idempotency conflict behavior
  • if key reused with different payload: show conflict and request a fresh action
  • if in-progress: show pending state and poll/refresh

7. Error Contract​

Status guidance:

  • 400: invalid payload/context/authority
  • 403: forbidden by policy or capability
  • 404: submission/evidence target not found (or scope-hidden)
  • 409: review/evidence state conflict or idempotency conflict
  • 500: retryable system failure

UX copy rule:

  • always include one specific next step (refresh, retry, choose different action, contact reviewer owner).

8. Definition of Done​

  1. Review queue supports triage state, owner, suppression, and lens filtering.
  2. Submission review workspace exposes KOE + dual-time readiness block with reason visibility.
  3. Approve/reject/request/reopen/ratify/void flows are explicitly mapped to API contracts.
  4. Evidence record/amend/verify/approve/reject/void actions are supported at submission and item scopes.
  5. Four-eyes/policy blocks are explicit and non-ambiguous to operators.
  6. Idempotency-safe UX is consistent across all high-stakes review mutations.