Skip to content

feat(adr): add Architecture Decision Record (ADR) system

Paolo Réant--Hamadi requested to merge feat/decisions into main

Implement a complete ADR subsystem that integrates with the wiki:

  • New agents/adr/ agent for creating ADRs with auto-linking
  • New agents/verify-adr-relevance/ sub-agent for auditing link pertinence
  • New scripts/wiki-site/lib/adr-backlinks.js for computing reverse links
  • Extend badges.js/render.js/build.js to display ADR links and backlinks in HTML
  • Add 'related_adrs' to ARRAY_CHIP_KEYS for automatic frontmatter validation
  • Update wiki-lint crossrefs.mjs automatically validates ADR references (no new code)

Architecture:

  • ADRs are a config-declared type (type: "adr"), enabling per-project opt-in
  • Pages link to ADRs via 'related_adrs' frontmatter array (slug-based, not decision_id)
  • Page→ADR: rendered as clickable chips in metadata panel (reuses ARRAY_CHIP_KEYS)
  • ADR→Pages: computed at build time, no hand-edit, shown as "Pages referencing this decision"

Integration:

  • agents/ingest Step 4.6: mandatory recheck ADR relevance when pages carrying related_adrs change
  • agents/query Step 3.5: attach ADR info to query results (if ADRs declared)
  • agents/consolidate Step 2.F: optional full audit of all ADR links (mirrors sub-agent E pattern)

Documentation:

  • New "ADR Linking Rules" section in llm-wiki-schema.md
  • Updated frontmatter examples in llm-wiki-TEMPLATE.md (status: proposed|accepted|superseded|deprecated)
  • New agents/adr/adr.md with full workflow (ask→create→link→log→report)
  • New agents/verify-adr-relevance/verify-adr-relevance.md (verdict: 🟢/🟠/🔴)
  • Adoption guide in migrations/README.md for existing projects
  • Updated README.md agents list (+2)

Testing:

  • Build & lint pass on default fixture (no ADRs declared)
  • Build & lint clean on custom fixture with type:adr, related_adrs, and backlinks
  • Chips + backlinks rendered correctly in generated HTML

Merge request reports