Skip to content

SOP-011 — Verify archive integrity (0 drift)

Guide

<!-- last-reviewed: 2026-06-01 · owner: The Archives (Archivist) -->

SOP-011 — Verify archive integrity (0 drift)

SOP · owner: The Archives (Archivist). Layer: SOP/Runbook (docs/canon.md). The read-only integrity gate that closes every preservation DoD and feeds the org-wide 0 drift integrity metric (docs/documentation-program/README.md §10). Rulebook: archive/SPECIFICATION.md §8 (linked, not restated).

Interface Contract

  • Inputs: archive state to verify ← from self (Archivist) · trigger: preservation complete
  • Outputs: manifest verification result → to Operations (SRE) · trigger: manifest verified
  • Handoff trigger (in): any archive change just completed, a verify is requested, or session-end
  • Handoff trigger (out): integrity computed and the result (0 drift / drift) reported to Operations (SRE)
  • Definition of Done before handoff:
    • [ ] ./scripts/archive-manifest.sh verify run; result captured (OK / drift / missing)
    • [ ] Any drift reconciled (re-update or revert) before reporting clean
    • [ ] manifest verified result handed to Operations (SRE) with the count
    • [ ] Verification-log row appended in archive/MANIFEST.md

The manifest verified output is a point-to-point edge — it must be named back as Operations (SRE)'s Inputs … ← from Archivist · trigger: manifest verified (the SRE then logs it via verification recorded). This is the non-fan-out edge from the worked example (interface-contract-spec.md §4, HR-003). All trigger phrases are drawn from docs/handoff-triggers.md.

Purpose

Prove — not assert — that the archive has not drifted: every latest/ matches its working source, no first/ was mutated, and every tracked version matches its recorded SHA-256. The single red/green check the rest of the org depends on for the 0 drift line in its DoD.

When to use

After any archive change (mandatory tail of SOP-010); whenever a verify is requested; and at session-end (the verify mode is wired there).

Flow

flowchart LR
  T["verify trigger<br/>(change / request / session-end)"] --> V["archive-manifest.sh verify"]
  V --> R{"0 drift?"}
  R -->|yes| OK["manifest verified<br/>→ Operations (SRE)"]
  R -->|drift / missing| DG["Diagnose"]
  DG --> RC["Reconcile<br/>(update or revert)"]
  RC --> V
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  classDef d fill:#0f766e,color:#fff,stroke:#134e4a
  class T,V,OK,DG,RC s
  class R d

Text fallback: a verify trigger fires → run archive-manifest.sh verify → if 0 drift, report manifest verified to Operations (SRE); if drift or missing, diagnose, reconcile (re-update or revert per authorization), then re-verify until clean.

Steps

  1. Run the gate: ./scripts/archive-manifest.sh verify. Read the summary line (verify: N OK, N drift, N missing). The script exits non-zero on any drift/missing so hooks/CI catch it.
  2. If 0 drift: record the result; hand manifest verified to Operations (SRE); append a Verification-log row in archive/MANIFEST.md. Done.
  3. If drift on a latest row (latest != <src>): the source changed without a manifest refresh. Re-run ./scripts/archive-manifest.sh update, then verify. Do not reach for refresh reflexively — it overwrites latest from the working source and can mask a real source regression (docs/knowledge/2026-06-01-archive-verify-vs-refresh.md).
  4. If FIRST MUTATED: a first/ version was edited — a spec violation (archive/SPECIFICATION.md §3). Stop; investigate; restore first/ from its origin commit before reporting clean. Never paper over it with update.
  5. If missing: a latest/ file is absent — create the archive home per archive/SPECIFICATION.md §5 and re-run SOP-010 for that doc.
  6. Reconcile only with authorization for any supersession/revert (Maintainer decides; archive/SPECIFICATION.md §10).

Roles / approvers

Run by the Archivist. Reconciliation that changes authoritative content (supersession/revert) is authorized by the Maintainer (Principal). Operations (SRE) is the consumer of the verification result, not an approver.

Guardrails

  • verify is read-only — the safe diagnostic. update/refresh mutate; never treat them as the gate.
  • Never “fix” FIRST MUTATED by re-checksumming — restore the immutable version.
  • Report honestly. A drift result is reported as drift; clean is reported only after reconciliation.

Job aid: docs/units/archives/job-aids/JA-010-omni-intake.md (step 6 Verify and If it goes wrong cover this gate). See also: archive/SPECIFICATION.md §8 · SOP-010 (docs/sop/SOP-010-preservation-omni-intake.md) · interface-contract-spec.md §4.