Skip to content

SOP-010 — Preserve an approved artifact (omni-intake + manifest)

Guide

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

SOP-010 — Preserve an approved artifact (omni-intake + manifest)

SOP · owner: The Archives (Archivist). Layer: SOP/Runbook (docs/canon.md). The production preservation procedure. The frozen exemplar (docs/documentation-program/exemplar/SOP-EX-preservation.md) sets the shape and quality bar; this is the real, runnable SOP. Rulebook: archive/SPECIFICATION.md (linked, not restated — one home per fact).

Interface Contract

  • Inputs: approved document ← from <authoring agent/unit> · trigger: artifact approved
  • Inputs: changed foundational/canon doc ← from <document owner/unit> · trigger: document changed
  • Inputs: new/updated history document ← from Historian · trigger: artifact approved
  • Outputs: archived record (first/latest + MANIFEST row) → to all agents · trigger: preservation complete
  • Handoff trigger (in): an authoring agent (or the Historian) hands an approved artifact for preservation, or a document owner reports a foundational doc changed
  • Handoff trigger (out): first/latest written, MANIFEST updated, and 0 drift verified
  • Definition of Done before handoff:
    • [ ] first/ written immutably (if new); latest/ refreshed verbatim
    • [ ] archive/MANIFEST.md row added/updated (path · slot · origin commit · captured · SHA-256)
    • [ ] ./scripts/archive-manifest.sh verify shows 0 drift (the gate — SOP-011)
    • [ ] Verification-log row appended in archive/MANIFEST.md
    • [ ] Learnings captured to docs/knowledge/ if the preservation surfaced one

The artifact approved in-trigger must match, verbatim, the producer’s Outputs … → to Archivist · trigger: artifact approved. The output preservation complete → to all agents is the omni-intake fan-out broadcast (matched-as-fan-out, interface-contract-spec.md §3.1) — exempt from a single named-consumer input. The manifest verified → Operations (SRE) point-to-point edge is carried by SOP-011 (the verification procedure), keeping this SOP’s contract focused on the preserve step. All trigger phrases are drawn from docs/handoff-triggers.md.

Purpose

Preserve every approved project document as a faithful, verifiable, version-tracked record (first + latest + milestones-when-named) so nothing authored is ever silently lost or altered, and integrity is provable on demand.

When to use

The standing omni-intake: whenever any agent hands off an approved artifact (including every artifact produced by the documentation program), the Historian hands a new history/ document, or the Documentarian reports a foundational doc changed. If the artifact is not approved, stop — preservation is not your trigger yet.

Flow

flowchart LR
  R["Receive approved<br/>artifact"] --> P{"New doc?"}
  P -->|yes| F["Write first<br/>(immutable)"]
  P -->|no| L["Refresh latest"]
  F --> L
  L --> M["Update MANIFEST<br/>(checksum)"]
  M --> V{"verify<br/>0 drift?"}
  V -->|yes| D["preservation complete"]
  V -->|no| Fix["Investigate & reconcile<br/>(SOP-011)"]
  Fix --> M
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  classDef d fill:#0f766e,color:#fff,stroke:#134e4a
  class R,F,L,M,D,Fix s
  class P,V d

Text fallback: receive the approved artifact → if it is new, write the first immutable version → refresh latest (verbatim) → update the MANIFEST row with a checksum → run verify; if 0 drift, emit preservation complete; if drift, investigate and reconcile (SOP-011), then re-verify.

Steps

  1. Confirm approval & exclusion. Verify the artifact is approved by its class owner (SOP-002 RACI, docs/sop/change-management.md). Confirm it is not the Principal’s personal information (PA-only; never archived — ORG.md).
  2. Locate/create the archive home under archive/ per archive/SPECIFICATION.md §5 (path mirrors the source). Never improvise a path.
  3. If new: write first/<file> immutably — extract from the origin commit (git show <commit>:<path>) or copy the working file if brand-new this change. Written once, never edited.
  4. Refresh latest/<file> — verbatim byte copy from the working tree (cp).
  5. Update archive/MANIFEST.md — add/update the first and/or latest row(s) then run ./scripts/archive-manifest.sh update to write checksums (no hand-editing).
  6. Verify — the gate (SOP-011): ./scripts/archive-manifest.sh verify → expect 0 drift. Anything else: reconcile before proceeding.
  7. Append a Verification-log row in archive/MANIFEST.md (date · action · result).
  8. Emit preservation complete (the org-wide fan-out). Capture any learning to docs/knowledge/ and ensure the Documentarian dual-indexes it.

Batched intake (wave mode). During the documentation program, preserve a wave’s approved artifacts as one pass: place all sources → one archive-manifest.sh update → one verify → one Verification-log row. This is the named mitigation for the preserve-queue bottleneck (R12).

Roles / approvers

Authored and run by the Archivist. The upstream artifact’s approval is owned by its class owner (SOP-002); no separate approval is needed to preserve an already-approved artifact. cmp/checksum confirmation is the Archivist’s own check.

Guardrails

  • Verbatim only. Byte-for-byte; cmp-confirmed. Never reformat or retype (archive/SPECIFICATION.md §7).
  • first/ is immutable. Never modified or deleted.
  • Never archive personal information (PA-only; ORG.md).
  • Do not restate archive/SPECIFICATION.md here — link to it.
  • Preservation is append-friendly: versions are superseded, never deleted.

Job aid: docs/units/archives/job-aids/JA-010-omni-intake.md. See also: archive/SPECIFICATION.md · SOP-002 (docs/sop/change-management.md) · SOP-011 (docs/sop/SOP-011-archive-integrity-verification.md) · interface-contract-spec.md §4 · exemplar docs/documentation-program/exemplar/SOP-EX-preservation.md.