Decisions (ADRs)

ADRs curtos pra decisões técnicas atemporais. Sem spec sibling. Formato fixo: Contexto / Decisão / Consequências / Alternativas / Referências (ADR 003).

Catálogo (8 aceitas)

• 001 — Stack de infraestrutura — dinero.js v2, drizzle + better-sqlite3, temporal-polyfill, Gemini 2.5 Flash via OpenRouter (não 3.x), unpdf + banksheet, clone vercel/chatbot starter. Skip: currency.js, prisma, pdf-parse, belvo.
• 002 — Estratégia de testes em tiers — três tiers (domain/infra/e2e), Vitest projects, Playwright. MockLanguageModelV1 mock-first; cassette só quando bug aparecer. Sem CI até ter remote.
• 003 — Estratégia de documentação — híbrido: scenarios/ behavioral UX-facing, decisions/ ADRs técnicos, src/contexts/*/infrastructure/*.spec.ts adapter specs colocated sem Gherkin. Roteamento por verbo do conteúdo.
• 004 — Memory architecture — @mastra/memory + @mastra/libsql ponteado via withMastra(). AgentChat segue stateless: recebe resourceId/threadId, memória via DI. Quatro tiers: conversation history, working memory, observational compression, semantic recall opt-in.
• 005 — Landing stack — Astro 6 separado do app principal. Cloudflare Pages free tier + Workers + D1 pra referral attribution. SEO long-tail PT-BR como canal primário.
• 006 — Anonymous-first identity — chat É onboarding, sem signup tradicional. resourceId = UUID anônimo (cookie/localStorage). Convidar parceiro = link assinado (HMAC + TTL 7d).
• 007 — WhatsApp via Baileys (no Cloud API fallback) — canal único conversacional. Sem Cloud API, sem Telegram. TOS-risk aceito conscientemente. Web vira só landing/blog/dashboard read-only.
• 008 — UX writing tone PT-BR — voz oficial do agente “mel” (minúsculo). Frases ≤ 15 palavras, 1 pergunta/turn, emoji funcional só, sem juridiquês. MEL_VOICE_GUIDE constante.

Convenção dos ADRs

Cada ADR tem frontmatter YAML com cross-ref:

• id, slug, title, status: Aceita, date.
• supersedes/superseded_by (~ por default).
• affects.{files, scenarios}.
• related.{decisions, scenarios}.

Body segue formato fixo: **Status** line, depois Contexto → Decisão → Consequências → Alternativas → Referências.

Quando criar ADR novo

• Decisão técnica que afeta múltiplos cenários ou contexts.
• Trade-off conscientemente assumido (ex: TOS-risk Baileys).
• Stack pick que vai durar (libs, providers, frameworks).
• Convenção codificável (tom UX, layering, naming).

Não criar ADR pra:

• Gotcha pontual — vai pra AGENTS.md ## Gotchas.
• Mecânica de adapter — vai pra spec colocada src/.../infrastructure/*.spec.ts (ADR 003).
• História do casal — vai pra scenarios/NNN-slug.{md,spec.ts}.