SOP-025 — Two-index discipline (knowledge index reconciliation)

SOP · owner: Documentation (Documentarian). Layer: SOP/Runbook (docs/canon.md). The Index step of the KM lifecycle (SOP-024 step 6) — keep the knowledge index reconciled so no learning is orphaned (K2/K7). Enforced by scripts/km-index-check.mjs. Links to the KM design, does not restate it.

Interface Contract

Inputs: preserved knowledge entry ← from Archivist · trigger: “preservation complete”
Outputs: reconciled knowledge index (docs/knowledge/README.md, GREEN) → to Archivist · trigger: “artifact approved”
Handoff trigger (in): a knowledge entry has been curated (SOP-024) and preserved, and is not yet in the README index
Handoff trigger (out): every docs/knowledge/*.md is listed in docs/knowledge/README.md and km-index-check.mjs returns GREEN
Definition of Done before handoff:
- [ ] A row for the entry exists in the docs/knowledge/README.md Index table (filename + topic)
- [ ] node scripts/km-index-check.mjs exits 0 / prints GREEN
- [ ] The reconciled index is handed to the Archivist for preservation

Purpose

Guarantee that every dated knowledge entry on disk is findable from the index, so a cold-starting instance retrieving from docs/knowledge/README.md never misses a learning. The scripted check makes this a red/green gate, not a hope (master plan §10 KM index integrity = 0).

When to use

After a knowledge entry is curated (SOP-024) and preserved; whenever km-index-check.mjs is RED; as part of the weekly curation sweep.

The two indices (what reconciles against what)

docs/knowledge/README.md — the enumerated index (one row per entry). This is what km-index-check.mjs enforces.
docs/canon.md Knowledge row — references the corpus by glob (docs/knowledge/*), so it covers every entry by construction; there is no per-entry list there to drift. The script’s header documents this — it checks the README only. If canon ever moves to an enumerated list, extend the check (Phase-0 recommendation R5; this SOP).

Flow

flowchart LR
  P["Entry curated +<br/>preserved"] --> Add["Add row to<br/>README index"]
  Add --> Run["node scripts/<br/>km-index-check.mjs"]
  Run --> Q{"GREEN?"}
  Q -->|no| Add
  Q -->|yes| A["Hand to Archivist<br/>'artifact approved'"]
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  classDef g fill:#0f766e,color:#fff,stroke:#134e4a
  class P,Add,Run,A s
  class Q g

Text fallback: an entry is curated and preserved → add its row to the docs/knowledge/README.md Index → run node scripts/km-index-check.mjs → if RED (an entry is missing), add the missing row(s) and re-run → at GREEN, hand the reconciled index to the Archivist (artifact approved).

Steps

Add a row to the Index table in docs/knowledge/README.md: | <filename> | <one-line topic> |.
Run the check:
```
node scripts/km-index-check.mjs
```
Expect GREEN — all N knowledge entries are listed. If RED, it names each missing file — add a row for each and re-run.
Sanity-check the canon Knowledge row glob still covers docs/knowledge/* (it does by construction; only act if canon switched to an enumerated list).
Hand the reconciled index to the Archivist (artifact approved).

Roles / approvers

Documentarian is the single writer of docs/knowledge/README.md. Archivist preserves. Contributors never edit the index directly (write-race avoidance) — they file the entry and report it for indexing.

Guardrails

Single-writer. Exactly one curator writes the README index per pass — concurrent edits by multiple agents corrupt the table (the write race this SOP exists to prevent; see docs/knowledge/2026-06-01-km-two-index-discipline-and-write-race.md).
GREEN is the gate. Do not hand off while km-index-check.mjs is RED.
Do not add expiry to entries — the index lists dated records governed by supersession (knowledge-management.md §5).

See also: SOP-024 (curation lifecycle) · scripts/km-index-check.mjs · docs/knowledge/README.md · knowledge-management.md §3/§7 · charter (docs/units/documentation/charter.md).