Runbook — Legal Hold

ADR: ADR-028Architecture: gdpr-strategy.md §4 Owner: DPO + Legal (approvers); Ops (operators)

A legal hold suspends GDPR-driven scrubbing for specific records under active investigation (regulatory request, civil litigation, criminal matter). This runbook covers opening, maintaining, and closing a hold — and triaging a scrub fault that intersects with a hold.

The backoffice.legal_holds table is the only sanctioned mechanism. Manually editing pii_redacted_at to suspend a scrub is a compliance finding.

---

Schema recap

CREATE TABLE backoffice.legal_holds (
  id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id    UUID NOT NULL,
  entity_type  TEXT NOT NULL CHECK (entity_type IN ('passenger','reseller','invoice','conversation')),
  entity_id    UUID NOT NULL,
  reason       TEXT NOT NULL,
  until        TIMESTAMPTZ,   -- NULL = open-ended
  created_by   UUID NOT NULL, -- Soft FK to auth.users(id)
  created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
  closed_at    TIMESTAMPTZ,
  closed_by    UUID           -- Soft FK to auth.users(id)
);

Scrub functions (scrub_passengers, scrub_resellers, scrub_invoices, scrub_conversations) read this table first and log SKIPPED_LEGAL_HOLD in tenant_scrub_logs for any hit.

---

Opening a hold

Approvers (required, two-person): DPO + Legal counsel (internal or engaged external).

1. Legal opens a ticket in the legal-hold Jira project. Attach: matter reference, scope (which tenants, which entity types), expected duration, legal basis.
2. DPO signs off in the ticket with a timestamp.
3. Ops runs the insert via the standard migration path (never via a live psql session):

   INSERT INTO backoffice.legal_holds
     (tenant_id, entity_type, entity_id, reason, until, created_by)
   VALUES (:tenant, :etype, :eid, :reason, :until_or_null, :ops_user);

4. Verify: the next scrub run for that entity logs SKIPPED_LEGAL_HOLD with the hold id as the skip_reason field.
5. Post a private note in #ops-privileged (not #ops): hold opened, no matter details — Jira link only.

Closing a hold

1. Legal updates the Jira ticket with "release" intent and rationale.
2. DPO signs off the release.
3. Ops updates the record:

   UPDATE backoffice.legal_holds
      SET closed_at = now(), closed_by = :ops_user
    WHERE id = :hold_id
      AND closed_at IS NULL;

4. The next scheduled scrub run will process any overdue records. Do not manually backdate pii_redacted_at or directly redact — let the scheduled pipeline handle it so the audit trail is clean.
5. Close the Jira ticket with the next successful scrub's log entry attached.

Scrub fault interaction

If a scrub job fails (alert A4 in observability-alerts.md) and the job was processing entities adjacent to an active hold, follow this sequence before retrying:

1. Snapshot tenant_scrub_logs rows for the failing run.
2. Verify no SKIPPED_LEGAL_HOLD row is mistakenly attributed to a matter that has already been closed (defensive: covers a race where closed_at was set between job read and write).
3. Retry the scrub run. If the fault persists: open a P2 incident — do not disable the scrub; a disabled scrub combined with active holds is a dual-compliance risk.

Audit

Quarterly (first Monday of Feb/May/Aug/Nov):

• Dump backoffice.legal_holds rows where until < now() AND closed_at IS NULL. Any matches = stale holds → escalate to DPO.
• Diff the list of hold ids against tenant_scrub_logs.skip_reason samples over the past 90 days to confirm every open hold is actively being honoured by the pipeline.

Notes

• entity_id is a UUID, never a natural key. If the same passenger migrates between tenants: file one hold per tenant_id — scrubs are tenant-scoped.
• The until column is advisory only. Scrubs continue to skip a hold until closed_at IS NOT NULL, regardless of until. This is deliberate so that lapsed matters do not silently auto-release.
• The hold table is append-mutate; rows are never deleted (only closed_at-stamped). This is the audit trail.