discord_bot/DECISIONS.md

# DECISIONS.md — ADR log

Decisions inside the set architecture. D-NNN, never renumbered.

- **D-001** — SDD+BDD+TDD adopted (2026-07-13). SPEC-system port:
  numbered requirements in `specs/`, coverage classes
  feature/test/manual, `tools/trace.py` enforcement in `make check`.
  Process is binding — see SPEC-000.
- **D-002** — BDD runs at the responder seam, not against live
  services. `FakeModelResponder` scripts model output; Discord-event
  behavior is unit-tested with mocked discord.py objects. Rationale:
  Discord ToS forbids test-account automation and LLM output is
  nondeterministic — a live-BDD lane would be flaky by construction.
- **D-003** — Packaging = uv + pyproject only (2026-07-13). setup.py,
  requirements.txt and pytest.ini removed; single source of truth,
  locked via uv.lock. Python `>=3.11` floor keeps the kitchen host
  (py3.11) deployable until FDB-016 lands.
- **D-004** — openai SDK pinned `<2` (1.109.x). The v2 SDK migration
  happens together with the FDB-005 envelope rewrite (structured
  outputs / Responses API) — one breaking change, one test cycle,
  instead of two.
- **D-005** — `--strict-markers` stays on; requirement tags from
  `.feature` files are registered as pytest markers dynamically in
  `tests/conftest.py`.
- **D-006** — FDB-005 stays on chat.completions + structured outputs;
  the Responses API migration is deferred to FDB-007, where history
  handling gets redesigned anyway — one conversation-state reshape
  instead of two.
- **D-007** — openai SDK bumped to 2.x together with the envelope
  rewrite (supersedes the D-004 pin). `multiline` dependency dropped —
  strict schema output made relaxed-JSON parsing dead code.
- **D-008** — Operator runtime flags (pause/images/tasks/quiet) are
  in-memory only; a restart resets to config defaults. Persistence
  arrives with the FDB-011 task store if staff practice demands it.
- **D-009** — `translate()` still keys off `fix-model` although the
  repair path is gone; the whole translate-before-draw step dies in
  FDB-009 (gpt-image-2 is multilingual). Not worth a config rename
  for one phase. *(Closed 2026-07-13: FDB-009 deleted translate();
  the fix-model config key is now fully dead and can be dropped from
  live configs.)*
- **D-010** — Persistence uses stdlib `sqlite3` via
  `asyncio.to_thread`, not aiosqlite: no new dependency, and a
  connection-per-operation with WAL is plenty at this message volume.
- **D-011** — `save_history` replaces the channel's rows wholesale
  per message instead of appending: histories are capped at
  `history-limit` (~200-350 rows) and trims must be reflected;
  correctness over micro-optimization.
- **D-012** — Budget spend is *estimated* from configured per-token/
  per-image prices, not fetched from the billing API: deterministic,
  testable, no extra scopes. Dashboard hard limits (FDB-001) stay the
  outer safety net; this ledger is the inner, immediate one. User
  image quota counts at grant time (reservation), global image spend
  at generation time.
- **D-013** — `!forgetme` v1 purges history rows only; the
  single-string channel memory cannot be selectively cleaned. Full
  fact-level erasure ships with FDB-007 structured memory — stated in
  the user-facing confirmation, not hidden. (Superseded by D-014:
  erasure now covers facts, observations and episode traces.)
- **D-016** — The reply/ignore classifier fails open (BEH-03): a
  broken classifier must never mute the bot; the budget gate already
  bounds spend. Its verdict gates BEFORE the main call, the
  envelope's answer_needed still gates after — two independent nets.
- **D-021** — Health monitoring (FDB-012, SPEC-012 OPS-18/19): a
  separate `monitor_loop` (own cadence, default 300 s) rather than
  folding checks into the 60 s task loop — monitoring is coarse and
  should not run every minute. Checks are edge-triggered (alert on the
  rising edge, re-arm on recovery) so a standing condition never spams;
  they reuse the existing rate-limited staff-alert path. Metrics are
  the cheap, high-signal ones (spend vs budget, free disk, task-queue
  depth); each is independently skippable when it has no data, so a
  deployment without a budget or store still runs the others. Opt-in
  (`enable-monitoring`) like every other operational rollout.
- **D-021** — Responses API behind `use-responses-api` (FDB-028,
  ENV-22..24, resolves D-006): the responder path can use
  `/v1/responses`, which allows tools + `reasoning_effort` (the
  chat/completions 400 from ENV-21) and keeps one chain of thought
  across tool rounds. Stateless by choice: `store=false` +
  encrypted reasoning items passed back — GDPR posture unchanged, no
  server-side conversation retention. Flag defaults off; rollback is
  a config toggle (hot-reload), not a deploy. Classifier /
  consolidation / task-gen stay on chat/completions (no tools, no
  reasoning need — not worth the churn).
- **D-020** — Web search via Exa (FDB-022, SPEC-015): a `web_search`
  tool alongside fetch_url/IGDB/codex/get_news, filling the "look it up
  on the open web" gap. Exa (not a raw search-engine scrape) because it
  returns clean title+url+text in one call — no SSRF surface of our own
  (we call one fixed API endpoint, not arbitrary hosts), and it pairs
  with fetch_url for the full article. Key is a host secret
  (`exa-api-key`, env `EXA_API_KEY` fallback), never repo-side; results
  sanitized like every other external-text tool; off by default
  (`enable-web-search`), metered per user.
- **D-019** — News memory + on-demand tool (SPEC-013 NEWS-07..12):
  the news pipeline now carries item summaries (feed descriptions,
  HTML-stripped) and persists every fetched item into a deduped `news`
  table (schema v6), pruned to a rolling window (`news-keep`). Both the
  kroa digest run and the ggg posting run write to it, so the store is
  a single searchable source across both models. A `get_news` tool
  reads that store (topic/source-filtered, metered, sanitized) rather
  than re-fetching feeds live: the ambient `{news}` digest stays a
  small always-on snapshot, while the tool gives unbounded on-demand
  reach without a fresh network round-trip per call. The store is the
  same `bot.db` (WAL) the bot uses; the cron process opens it
  independently — concurrent reader/writer is what WAL is for.
- **D-018** — Codex Mechanicus search (FDB-019, SPEC-014): Luma's
  lore is grounded in the priest's real archive at binaric.tech via a
  `codex_search` tool over the site's public `search-index.json`, not
  a bot-side copy — the index stays a single source of truth, refreshed
  by the site's own publish rite, and the bot caches it in memory
  (TTL). It reuses SPEC-011's `guard_url` + `read_capped` (fetch is
  SSRF-guarded and byte-bounded) and sanitizes every returned field:
  one's own web content is still untrusted by the time it reaches a
  prompt. Luma-only (`enable-codex`, off elsewhere) — the Adeptus
  Mechanicus archive has no place in Fjærkroa's café persona.
- **D-017** — All human-behavior knobs default to off/v3.0.0
  semantics; behavior changes are config rollouts per deployment, not
  code flips. The classifier's `factual` flag is the only coupling
  (delay bypass) and defaults to false without a classifier.
- **D-015** — Deploys are push-based from the dev machine
  (`git archive <tag> | ssh`), not pull-based: no deploy keys or git
  state on the hosts, the artifact is exactly the tag tree, untracked
  live config survives in-place extraction. Trade-off: deploys need
  the dev machine; acceptable for a one-operator project.
- **D-014** — Structured memory (FDB-007): observations are the only
  consolidation feed (independent of history trimming); consolidation
  returns NEW facts only (no wholesale rewrite — the lossiness of the
  old memoize path is exactly what we're removing); self-authorship
  is enforced in code (fact subject must be an observation author),
  not just in the prompt; memory reads run on the loop (small indexed
  SQLite queries), writes off-loop. Legacy memory strings survive as
  episodes; the memory table stays as a read-only legacy fallback for
  deployments without memory-model.