Architecture Decision Records

This directory contains short, dated records of meaningful design decisions. Each ADR captures one decision, the context it was made in, the alternatives considered, and the consequences accepted. The goal is auditable reasoning, not exhaustive documentation.

Format: Michael Nygard’s template, kept short.

Index

• 0001 — Just-in-time auth
• 0002 — Use Bundler’s lockfile parser
• 0003 — Prefer bug_tracker_uri over source_code_uri
• 0004 — Use OAuth Device Flow, not PATs
• 0005 — Render labels verbatim
• 0006 — Ship as a standalone gem, not a Bundler plugin — Bundler-plugin decision reversed by 0014; standalone-gem decision stands
• 0007 — Show CONTRIBUTING; don’t parse it
• 0008 — Use Rooibos for the TUI layer — superseded by 0010, substance restored by 0013
• 0009 — Top-level namespace is GemContribute
• 0010 — Use Charm-Ruby (bubbletea + lipgloss) for the TUI layer — superseded by 0013
• 0011 — HostAdapter owns host verbs; Operations compose them; CLI verbs compose Operations
• 0012 — Output-free service objects, dry-monads Result contract, three-interface architecture — packaging amended by 0014; service-layer contract stands
• 0013 — Revert TUI framework to Rooibos — supersedes 0010, restores 0008’s substance
• 0014 — Ship Bundler and RubyGems plugins as v1 interfaces — amends 0006 and 0012; shipping order amended by 0015
• 0015 — Descope v1.0 to standalone CLI; plugins to v1.x; TUI to v2.0 — amends 0014

When to add an ADR

Add one when a decision is non-obvious and would be expensive to reverse. Don’t add one for “we used Minitest.” Do add one when “we picked X over Y for non-obvious reasons and someone six months from now will wonder why.”