Skip to content

SOP-079 — Automation & CI (add or modify a check)

Guide

SOP-079 — Automation & CI (add or modify a check)

SOP · owner: Operations (Process Engineer). Layer: SOP/Runbook (docs/canon.md). The procedure for changing the automation/CI pipeline Operations owns — .github/workflows/, .claude/hooks/, and the repo-root scripts/. Right-size everything (GR-4): automate real toil, never add ceremony.

Interface Contract

  • Inputs: proposed CI/pipeline change ← from <authoring agent/unit> · trigger: document changed
  • Inputs: harness / check handed for CI integration ← from <authoring agent/unit> · trigger: review requested
  • Outputs: approved CI/automation change → to Archivist · trigger: artifact approved
  • Handoff trigger (in): a real toil/risk justifies a new or changed check (GR-4 need analysis)
  • Handoff trigger (out): the change is green in CI and approved for preservation
  • Definition of Done before handoff:
    • [ ] GR-4 need analysis: what capability, for what, under what constraint
    • [ ] the check runs locally and in CI (.github/workflows/ci.yml) and is green
    • [ ] no secrets or personal information enter the repo (security.md)
    • [ ] node scripts/handoff-reconcile.mjs still GREEN
    • [ ] Archived (0 drift); learnings captured to docs/knowledge/ if any

Purpose

A controlled path for adding or changing pipeline automation, so a new check removes real toil, runs in CI, and never introduces a secret, an external call, or ceremony.

When to use

Adding/modifying a CI step (.github/workflows/), a hook (.claude/hooks/), or a script (scripts/) — e.g. the proposed fan-in CI complement (OR-1), a new integrity gate, or a build-skip allowlist change. Use SOP-077 for the SOP doc that describes it.

Flow

flowchart LR
  N["Need analysis<br/>(GR-4)"] --> B["Build the check<br/>local-first"]
  B --> T{"Green<br/>local + CI?"}
  T -->|no| B
  T -->|yes| W["Wire into CI / hook"]
  W --> A["Approve + archive"]
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  classDef d fill:#0f766e,color:#fff,stroke:#134e4a
  class N,B,W,A s
  class T d

Text fallback: a need analysis (GR-4 — what capability, for what, under what constraint) justifies the change → build the check, test it locally first → confirm it is green locally and in CI → wire it into .github/workflows/ci.yml or a hook → approve + archive. No secrets, no external calls; CI is a quality gate, not a deploy.

Steps

  1. Need analysis (GR-4). State the capability, the toil/risk it removes, and the constraint. No need, no build — ceremony is a defect.
  2. Build local-first. Write the script/check (prefer a small Node .mjs matching scripts/ conventions — silent fallback, single prefixed summary line). Run it locally.
  3. Verify green locally and confirm it fits the CI contract: no secrets, no external calls, fast (CI timeout-minutes: 15).
  4. Wire it into .github/workflows/ci.yml (a named step) or .claude/hooks/. During this wave, .github/ is frozen — propose the wiring, do not edit it; land the script and the SOP, and report the CI step for the integration pass.
  5. Confirm the reconciler still reads GREEN (a new check must not break the gate).
  6. Approve (SOP-077/SOP-002) and archive (0 drift).

The existing pipeline (reference)

Surface What runs Where
CI gate (per push/PR) archive verify · schema-drift · handoff reconcile · KM index · build · npm audit .github/workflows/ci.yml
SessionEnd hook archive-manifest.sh verify .claude/hooks/session-end.sh
SessionStart hook canon/integrity review prompt .claude/hooks/session-start.sh
Scripts archive-manifest.sh, handoff-reconcile.mjs, km-index-check.mjs, check-schema-drift.mjs scripts/

AR-003 (no-op cadence) — known gap. Nothing runs the reconciler / KM check on a cadence; CI runs them per-push only. Until AR-003 is wired, run them manually at each wave checkpoint (flag to the Principal — OR-2).

Roles / approvers

  • Build + wire: Operations (Process Engineer).
  • Approve: Operations (SOP-077/SOP-002); secrets-touching changes route through Security (SOP-004).
  • Archive: Archivist.

Guardrails

  • No secrets, no external calls in CI (security.md); CI is a quality gate.
  • GR-7: never push mid-task; batch to a checkpoint (each main push is a Vercel deploy, ADR-0009).
  • Right-size (GR-4): a check that does not remove real toil is ceremony — reject it.
  • .github/ frozen this wave — propose CI-step wiring, do not self-edit.

See also: .github/workflows/ci.yml · .claude/hooks/ · docs/operations.md · docs/sop/SOP-004-secrets-management.md · docs/sop/SOP-077-sop-system-change-management.md · docs/knowledge/2026-06-01-reconciler-fan-in-blind-spot.md.