KM two-index check is README-only, and the index needs a single writer

Date: 2026-06-01 · By: Documentation (Documentarian)
Topic: km-two-index-discipline-and-write-race
Status: active

Append-only, dated, one topic per entry. Captured first; promoted into SOP-024/025 and JA-022 (see Promotion).

What we learned

Two concrete, testable facts surfaced while authoring the Documentation unit’s KM SOPs in Wave 1:

The “two-index” check is, in practice, a one-index check. Despite the program’s “both indices update together” framing (knowledge-management.md §3 step 4), scripts/km-index-check.mjs enforces only docs/knowledge/README.md. Its header (lines 9–13) explains why: the canon Knowledge row (docs/canon.md) references the corpus by glob (docs/knowledge/*), so it covers every entry by construction — there is no per-entry list there to drift. The check is a substring match: an entry is “indexed” iff its filename appears anywhere in the README (km-index-check.mjs:39). Implication: you only ever hand-edit the README; you do not add a per-entry canon row (none exists). The script will only need extending if canon ever switches to an enumerated list.
Ground truth differs from the program’s stated KM-readiness. The program docs say “2 dated entries, 1 unindexed” (knowledge-management.md §1, §7.4) — stale. As the Wave 1 corpus landed the base grew to 5 dated entries (the three pre-existing ones plus 2026-06-01-archive-verify-vs-refresh.md and this entry), all indexed; node scripts/km-index-check.mjs returns GREEN — all 5 ... listed (exit 0). The count moves as entries are filed — the durable fact is that the index reconciles GREEN, not any one number. The K7/§7.4 omission the program planned to fix is closed.
The dead end that the single-writer rule avoids. The KM lifecycle says “every agent captures.” If every contributing agent also edited the shared docs/knowledge/README.md index table, concurrent Wave-1 authors would race on the same Markdown table and corrupt rows. The fix adopted here: contributors file the entry and report the filename; only the curator (Documentarian) writes the README index. This is why this very task was instructed not to edit docs/knowledge/README.md — to avoid exactly that write race — and to report the new entry for indexing instead.

Why it matters

It saves every future curator two wrong moves: (1) hunting for a non-existent “second index” / per-entry canon row to update, and (2) assuming any agent can edit the knowledge index safely. It also corrects a stale program claim so the Wave 0 DoD line “fix the current index omission” is recorded as done, not pending.

Next time

Treat the knowledge index as README-only and single-writer — file + report, do not co-edit the table.
Run node scripts/km-index-check.mjs as the green gate before any KM handoff; do not hand off on RED.
If canon ever enumerates knowledge entries, extend km-index-check.mjs to check it too (today it intentionally does not).

Promotion

Promoted to: docs/sop/SOP-024-km-curation.md and docs/sop/SOP-025-two-index-discipline.md (the index step + single-writer guardrail) and docs/units/documentation/job-aids/JA-022-add-knowledge-entry.md (the stranger-executable steps). Also feeds Phase-0 recommendation R5.
Supersedes / superseded by: none.