Skip to content

SOP-078 — Run the Handoff Register reconciliation

Guide

SOP-078 — Run the Handoff Register reconciliation

SOP · owner: Operations (Process Engineer). Layer: SOP/Runbook (docs/canon.md). The procedure for running the reconciliation gate — the single highest-leverage build in the documentation program (master plan §5.3). Operations owns the mechanism + reconciliation; Quality & Risk provides independent assurance the register stays green; the Archivist preserves it.

Interface Contract

  • Inputs: Interface Contract blocks ← from <authoring agent/unit> · trigger: artifact approved
  • Outputs: Handoff Register handed for assurance → to Quality & Risk · trigger: review requested
  • Inputs: assurance cleared (register stays green) ← from <Quality & Risk> · trigger: review passed
  • Handoff trigger (in): a wave’s SOPs are authored and ready to reconcile
  • Handoff trigger (out): the register reconciles GREEN and is handed to Q&R for assurance
  • Definition of Done before handoff:
    • [ ] node scripts/handoff-reconcile.mjs reads GREEN (exit 0)
    • [ ] register regenerated (--register docs/handoff-register.md)
    • [ ] every defect routed to its owner (gap) or canon RACI (overlap)
    • [ ] result recorded at the wave checkpoint (AR-003 manual run)
    • [ ] learnings captured to docs/knowledge/ if any

Purpose

Turn “seamless handoffs” into a red/green number: parse every Interface Contract block, build the edge list, reconcile per interface-contract-spec.md §3.1, and route defects to their owners — until the gate reads GREEN.

When to use

At every wave checkpoint, before any Phase-2 “done” claim, and whenever an SOP’s Interface Contract is added or changed. Until AR-003 wires a cadence, run it manually at each checkpoint (CI also runs it per-push).

Flow

flowchart LR
  Run["Run reconciler"] --> V{"GREEN?"}
  V -->|green| Reg["Regenerate register<br/>→ hand to Q&R"]
  V -->|GAP| G["Route to owning agent"]
  V -->|OVERLAP| O["Route to canon RACI"]
  V -->|UNREGISTERED| U["Add/reuse trigger<br/>(registry)"]
  G --> Run
  O --> Run
  U --> Run
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  classDef d fill:#0f766e,color:#fff,stroke:#134e4a
  class Run,Reg,G,O,U s
  class V d

Text fallback: Run node scripts/handoff-reconcile.mjs → if GREEN, regenerate the register and hand it to Q&R for assurance; a GAP routes back to the owning agent, an OVERLAP routes to canon RACI / the C-suite head (never peer-negotiated), and an UNREGISTERED TRIGGER is fixed by adding the phrase (or reusing one) in the registry. Re-run until GREEN.

Steps

  1. Run node scripts/handoff-reconcile.mjs. Read the per-edge verdict lines and the trailing GREEN/RED line (exit 0 / exit 1).
  2. Read the verdict against interface-contract-spec.md §3.1 / §3.1.1:
    • matched, matched (fan-out), matched (fan-in), matched (self), exempt (Principal), pending (counterparty not yet authored) — all clean.
    • GAP — dropped handoff / dangling dependency / trigger mismatch — a real gap.
    • OVERLAP — two authored production producers claim one artifact.
    • UNREGISTERED TRIGGER — a phrase not in docs/handoff-triggers.md.
  3. Route each defect:
    • GAP → the owning agent fixes their Interface Contract (add the mirroring edge, or reconcile the trigger phrase to match verbatim).
    • OVERLAP → escalate to canon RACI / the cluster C-suite head; do not peer-negotiate (R8).
    • UNREGISTERED TRIGGER → add the phrase to the registry (reuse-beats-add) or reuse an existing canonical one; report the addition for the single-writer pass.
  4. Re-run until GREEN (exit 0).
  5. Regenerate the register: node scripts/handoff-reconcile.mjs --register docs/handoff-register.md (generated artifact — never hand-edit).
  6. Hand to Q&R for independent assurance (review requested); record the result at the wave checkpoint (AR-003 manual run).

Adding a trigger (do not invent inline)

  1. The authoring agent sends Operations the phrase, its meaning, and the producer→consumer edge.
  2. Operations checks it is not a synonym (reuse beats add).
  3. If genuinely new, Operations appends a row to docs/handoff-triggers.md — but during a wave, report it so the single-writer integration pass consolidates additions.

Roles / approvers

  • Run + route: Operations (Process Engineer).
  • Overlap resolution: canon RACI / cluster C-suite head / Principal.
  • Independent assurance: Quality & Risk (the register stays green is their sign-off, not self-attestation — R11).

Guardrails

  • The script is the gate, not an eyeball (GR-2); a checkbox cannot clear it.
  • The register is generated — never hand-edit docs/handoff-register.md.
  • Known blind spot (OR-1): a declared fan-in sink reconciles GREEN even with zero producers (scripts/handoff-reconcile.mjs:318-323 asserts no producer minimum). GREEN is necessary, not sufficient — a sink can be green and orphaned. See docs/knowledge/2026-06-01-reconciler-fan-in-blind-spot.md and the proposed CI complement (do not rebuild the reconciler to fix this now).

See also: interface-contract-spec.md · docs/handoff-triggers.md · scripts/handoff-reconcile.mjs · docs/sop/registry.md · docs/knowledge/2026-06-01-reconciler-fan-in-blind-spot.md.