Zettle

0013-index-maintenance

2 min read

ADR-0013: Index notes are auto-maintained from wikilinks; pre-commit hook validates

Status: Accepted Date: 2026-05-19

Context

Person and Glossary notes are index-type — their value is in being a complete directory of who/what is referenced. Manual maintenance = silent rot. Need an enforcement mechanism that makes drift impossible by construction.

Decision

  1. No new mentions: frontmatter field. Obsidian’s wikilinks already encode the mention. If an atomic body contains [[Sun-Myung-Moon]] or [[indemnity]], the link IS the mention.
  2. Every Person and Glossary file ends with an auto-generated ## Referenced by section — a list of every note in the vault that wikilinks to it.
  3. Update happens at batch finalization. When AI moves files from /staging/ to final, it scans wikilinks in all new/changed files, identifies Person/Glossary targets, and rewrites their ## Referenced by section. All index updates land in the same commit as the atomics that triggered them.
  4. Pre-commit hook validates. Hook reads every Person/Glossary ## Referenced by and verifies it matches the vault’s actual reverse-link graph. Mismatch → commit fails with a diff. AI must regenerate before retry.

Alternatives considered

  • Explicit mentions: frontmatter field: rejected — duplicates information already in wikilinks, requires sync, AI may forget to update.
  • Periodic vault audit script (run weekly): rejected — gives windows where indexes drift silently. Same-commit guarantee is stronger.
  • Trust AI to maintain without validation: rejected — silent rot is the failure mode this ADR exists to prevent.

Consequences

  • (+) Drift impossible at any commit boundary
  • (+) Person/Glossary ## Referenced by becomes useful navigation on the published site
  • (+) Wikilink scanning is cheap; no extra fields to maintain
  • (−) Pre-commit hook is real code that must be kept in sync with vault rules (~50 lines, low maintenance)
  • (−) Renaming a Person/Glossary note triggers updates across many index entries; Obsidian’s auto-rename handles the links, hook re-validates afterward

Graph View