From b0d722d1a985326fb38e4e7fea237b9c4a2adcfd Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Thu, 30 Apr 2026 07:55:28 -0500
Subject: docs: record four ADRs for gloss design decisions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The four decisions called out in the brainstorm now have their own
files under docs/decisions/, each with Context / Decision /
Consequences / Alternatives Considered.

- 0001 — storage path default: respects org-directory if set, falls
  back to user-emacs-directory.
- 0002 — auto-fetch on local miss: silent fall-through, network
  failures surface via the regular error rollup. No y/n prompt for
  v1.
- 0003 — drill direction: every entry exports as twosided. One card
  per entry, both directions over time, no per-entry override.
- 0004 — HTML strip strategy: libxml-parse-html-region. Plain text
  only, no italic/bold preservation. Online fetch disabled package-wide
  for the session if libxml is missing.

The "Open Questions" section in the design doc is now "Decisions
Recorded" with links into the ADRs.
---
 docs/design/gloss.org | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

(limited to 'docs/design')

diff --git a/docs/design/gloss.org b/docs/design/gloss.org
index 649eb24..c4b2e1a 100644
--- a/docs/design/gloss.org
+++ b/docs/design/gloss.org
@@ -294,14 +294,14 @@ Per-source statuses from Error Handling land here verbatim. No personal data bey
 
 No metrics export, no telemetry, no profiling hooks — v3 territory if the package ever needs them.
 
-* Open Questions (will become ADRs)
+* Decisions Recorded
 
-Each was decided during the brainstorm. Listed for traceability; each becomes an ADR in the gloss repo's =docs/decisions/=.
+The four design decisions called out during the brainstorm are now ADRs under [[file:../decisions/][docs/decisions/]]:
 
-- [ ] *ADR-1: storage path default* → =(expand-file-name "gloss.org" (or org-directory user-emacs-directory))=. Rationale: respects the user's existing =org-directory= convention; falls back gracefully.
-- [ ] *ADR-2: auto-fetch on local miss* → silent fall-through with graceful network-failure path. Rationale: y/n prompt is yes 99% of the time and an annoyance the other 1%; the offline case is better handled by detecting the failure than by pre-asking permission.
-- [ ] *ADR-3: drill direction* → =:DRILL_CARD_TYPE: twosided=. Rationale: tests both recognition and recall over time without doubling the deck.
-- [ ] *ADR-4: HTML strip strategy* → =libxml-parse-html-region= (plain text only, no italic/bold preservation). Rationale: more robust than regex on edge cases; libxml2 is standard on Linux/Mac; ~30 lines.
+- [[file:../decisions/0001-storage-path-default.org][ADR-1: Storage path default]] → =(expand-file-name "gloss.org" (or org-directory user-emacs-directory))=.
+- [[file:../decisions/0002-auto-fetch-on-local-miss.org][ADR-2: Auto-fetch on local miss]] → silent fall-through with graceful network-failure path.
+- [[file:../decisions/0003-drill-direction.org][ADR-3: Drill direction]] → =:DRILL_CARD_TYPE: twosided=.
+- [[file:../decisions/0004-html-strip-strategy.org][ADR-4: HTML strip strategy]] → =libxml-parse-html-region= (plain text only, no italic/bold preservation).
 
 * Next Steps
 
-- 
cgit v1.2.3