SOP-023 — Update the canon index & map

SOP · owner: Documentation (Documentarian). Layer: SOP/Runbook (docs/canon.md). Procedure for keeping docs/canon.md (the documentation map) accurate when a doc is added, moved, renamed, or retired. Canon links, never restates (CONTRIBUTING.md).

Interface Contract

Inputs: doc added/moved/renamed/retired ← from <document owner / self> · trigger: “document changed”
Outputs: updated canon index (docs/canon.md) → to Archivist · trigger: “artifact approved”
Inputs: preserved record (fan-out) ← from Archivist · trigger: “preservation complete”
Handoff trigger (in): a doc’s existence, path, name, or status changed and the canon map no longer matches reality
Handoff trigger (out): the canon Index, hierarchy, ownership, and cross-links reflect the change, with no broken links
Definition of Done before handoff:
- [ ] The doc’s row in the docs/canon.md Index is added/updated/removed with correct Layer + Owner
- [ ] No link in canon points to a moved/retired path; references use IDs where one exists
- [ ] Glossary checked for any new load-bearing term the doc introduced
- [ ] Change handed to the Archivist for preservation

Purpose

Keep the canon map (docs/canon.md) — the index every employee reviews each morning — a true, link-resolving picture of the corpus, so a cold-starting instance can find any doc and never follows a dead link.

When to use

A doc is added, moved, renamed, or retired; a doc introduces a new term; or a periodic coherence pass finds the Index out of step with docs/.

Flow

flowchart LR
  T["doc added / moved /<br/>renamed / retired"] --> R["Locate its row(s)<br/>in canon Index"]
  R --> U["Add / update / remove<br/>row (Layer · Owner)"]
  U --> X["Re-check cross-links<br/>resolve (by ID)"]
  X --> G["Glossary check<br/>(new terms?)"]
  G --> A["Hand to Archivist<br/>'artifact approved'"]
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  class T,R,U,X,G,A s

Text fallback: a doc changed → locate its row(s) in the canon Index → add, update, or remove the row with the correct Layer and Owner → re-check that cross-links still resolve (prefer ID references) → glossary check for any new load-bearing term → hand to the Archivist (artifact approved).

Steps

Identify what changed: added / moved / renamed / retired, and the doc’s Layer (Macro → Foundational → Policy/Process → SOP/Runbook → Job aid) and Owner.
Edit the docs/canon.md Index table: add the row (new), update path/owner (moved/renamed), or remove it (retired). Keep the layer ordering intact.
Scan canon for stale links to the old path; fix to the new path or an ID. Note: for docs/units/* (unit charters/SOPs/job aids), ensure the Index has a row for that class (Phase-0 R2) before adding the doc under it.
Glossary check (docs/glossary.md): if the doc introduced a load-bearing term, add a one-line entry that links to the owning doc (does not restate).
Hand to the Archivist (artifact approved).

Roles / approvers

Documentarian authors. The canon map is Foundational (Principal-approved on substantive structural change; routine index upkeep is owner-maintained per the RACI-lite). Preservation: Archivist.

Guardrails

Canon links, never restates — no content owned elsewhere is duplicated here.
Reference by ID so links survive renames (GR-#, SOP-###, JA-###, ADR-####, MS-##; CONTRIBUTING.md).
Do not edit other owners’ rows’ content — adjust index/ownership only; route ownership disputes to canon RACI / the COO (master plan §11 R8).

See also: docs/canon.md · SOP-022 · CONTRIBUTING.md (ID scheme, one-home rule) · charter (docs/units/documentation/charter.md).