Skip to content

SOP-020 — Roster / ORG.md update

Guide

<!-- last-reviewed: 2026-06-01 · owner: human-resources -->

SOP-020 — Roster / ORG.md update

SOP · owner: Human Resources. Layer: SOP/Runbook (docs/canon.md). The procedure for any structure-changing edit to ORG.md that is not a full hire (SOP-018) or a unit rename (SOP-021): adding/removing a roster row, moving an agent between units, correcting a reporting line, or routine roster hygiene.

Interface Contract

  • Inputs: roster change request ← from hiring Lead / Principal · trigger: “staffing request approved”
  • Outputs: updated ORG.md → to Documentarian · trigger: “document changed”
  • Outputs: approved ORG.md → to Archivist · trigger: “artifact approved”
  • Handoff trigger (in): an authorized request to change the roster/structure reaches HR
  • Handoff trigger (out): ORG.md is edited, the chart validates, and the change is approved for preservation
  • Definition of Done before handoff:
    • [ ] Change authorized (hiring Lead for members; Principal for anything touching ORG.md per program RACI §7)
    • [ ] Roster-freeze checked — if active, only routine ambiguity-removing hygiene proceeds; hires/renames follow the exception path
    • [ ] Every reference updated consistently: chart, unit section, roster row, coverage table
    • [ ] Mermaid chart validated before saving (no broken/orphaned nodes)
    • [ ] One Lead per unit preserved; no empty units invented; conflicts surfaced
    • [ ] Prior state noted once for traceability where a row is removed/moved

"document changed", "artifact approved", and "staffing request approved" are verbatim registry phrases (staffing request approved is a Wave 1 addition, Operations-approved 2026-06-01).

Purpose

Keep ORG.md the accurate single source of truth for “who owns what” as the organization changes — without drift between the chart, unit sections, roster, and the canon index.

When to use

  • Adding or removing a member within an existing unit (reports to its Lead).
  • Moving an agent between units, or correcting a stale reports to line.
  • Routine roster hygiene (e.g. confirming a legacy role’s retirement) — this is not blocked by the roster freeze (hr/policies/roster-freeze.md).
  • (For a brand-new role use SOP-018; for a unit rename use SOP-021.)

Flow

flowchart LR
  A["Authorized<br/>change"] --> B["Check freeze<br/>+ scope"]
  B --> C["Edit ORG.md<br/>(all references)"]
  C --> D{"Chart<br/>validates?"}
  D -->|yes| E["Hand off:<br/>document changed +<br/>artifact approved"]
  D -->|no| Fix["Fix nodes/edges"]
  Fix --> C
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  classDef g fill:#0f766e,color:#fff,stroke:#134e4a
  class A,B,C,E,Fix s
  class D g

Text fallback: from an authorized change → check the freeze and the scope → edit every ORG.md reference (chart, unit section, roster, coverage) → validate the Mermaid chart; if it fails, fix nodes/edges and re-edit → hand off document changed (Documentarian) and artifact approved (Archivist).

Steps

  1. Confirm authorization and freeze status. During the freeze, only routine ambiguity-removing hygiene proceeds without the exception path.
  2. Scope the change — which rows, sections, chart nodes, and the Standard business functions — coverage table are affected.
  3. Edit ORG.md consistently across all references: chart node(s), unit heading/section, roster row, coverage table. Note prior state once where a row is removed or moved.
  4. Validate the Mermaid chart before saving — no orphaned or duplicate nodes; reports to lines resolve to real roster entries.
  5. Hand off: emit "document changed" to the Documentarian (canon-index refresh) and "artifact approved" to the Archivist (preserve ORG.md first/latest + manifest).
  6. Confirm the change to the requester.

Roles / approvers

HR edits ORG.md. Authorization: the hiring Lead for member changes within a unit; the Principal for anything touching ORG.md structure (program RACI §7). Documentarian refreshes the canon index; the Archivist preserves.

Guardrails

  • Roster freeze: hires and renames are held (use SOP-018 / SOP-021 + the exception path). Routine hygiene that removes ambiguity is allowed.
  • HR edits ORG.md (and the relevant agent file) only — never archive/ or other units’ artifacts.
  • Keep one Lead per unit; never invent an empty unit to place an agent — mark it unassigned. Surface overlaps; do not resolve them silently in prose.

See also: hr/hiring-playbook.md (Renames/role changes/offboarding), docs/sop/SOP-018-hire-agent.md, docs/sop/SOP-021-rename-unit.md, docs/units/human-resources/charter.md, docs/documentation-program/interface-contract-spec.md, hr/policies/roster-freeze.md.