Journey 000→026

A journey lê o domínio cronologicamente, na ordem em que cada capacidade foi desenhada. Cada scenario é um par doc+spec (NNN-slug.md + NNN-slug.spec.ts) — ver convenção em AGENTS.md.

Os links abaixo apontam pros .md reais no repo. Quebram em dev preview do site, mas funcionam em qualquer file explorer / GitHub. Aceitação consciente: a doc é canônica pra navegação, o repo é canônico pro conteúdo.

Fase 1 — Núcleo financeiro (000–007)

Aqui mora o domínio puro. VOs primeiro, entities quando “atualizar” apareceu, aggregate roots quando “listar” forçou coleção em um lugar.

• 000 — Custos mensais da casa. Registrar, buscar, reajustar. Introduz Budget (aggregate root) + RecurringExpense (entity) + VOs financeiros base (Money, BillingDay, etc).
• 001 — Importar fatura do cartão. Primeira upload registra o cartão, faturas subsequentes anexam, marcar como paga. Context accounts/ (aggregate Account, entity Invoice, VO Transaction) + shared-kernel/ (Money, BillingDay, Period).
• 002 — Meta de poupança do casal. Goal multi-currency com aporte mensal necessário, contribuir com atribuição por member, ver pace/onTrack/forecast. Domain não converte moeda — UX converte por fora.
• 003 — Custo variável (expected vs actual). recordSpend(period, actual), actualFor, varianceFor. Budget ganha actualTotal(period) e varianceReport(period). Renomeação valor → expected com alias.
• 004 — Reconciliar fatura com expense. Domain Service ExpenseReconciler.applyInvoice. Expense ganha aliases + matches(description). Cross-context read-only de accounts/ por budget/.
• 005 — Renda do casal (Household). Context household/ com aggregate Household. Member promovido a Entity em shared-kernel/ com id UUID estável.
• 006 — Viabilidade da meta. Cross-context FeasibilityCheck.evaluate({goal, household, budget, today, rate?}) retorna feasible|tight|infeasible|indeterminate. Threshold tight = 80%. Introduz planning/ (capability-named, sem aggregate root).
• 007 — Persistir o orçamento. Round-trip save/load/list. Port BudgetRepository em budget/application/. Budget.id promovido. Adapter SQLite em spec colocada (ADR 003).

Fase 2 — Agente conversacional (008–013)

Aqui o agente entra. Tools como wrappers finos sobre aggregates, LLM mockado via ai/test, persistência de chat, write tools com propose→confirm.

• 008 — Chat com agente conversacional. AgentChat.ask({messages}) orquestra LLM + tools read-only. Context agent/ com BudgetTool/GoalTool/FeasibilityTool. Mock LLM via Vercel AI SDK ai/test.
• 009 — Importar fatura Nubank via chat. Upload PDF no chat, parse via unpdf + regex, registra Invoice, dispara reconciler. Estende AgentChat/ChatMessage pra multimodal.
• 010 — Persistir o resto. Pattern do 007 replicado pra Goal/Household/Account. Ids promovidos com overload externo. serializeX/rehydrate pareados.
• 011 — Cotação FX viva. Port ExchangeRateProvider em shared-kernel/application/. Adapter ExchangeRateHostProvider (exchangerate.host, cache TTL 1h, fetch+now injetáveis).
• 012 — Chat persistido + retrieval. Port AgentMemory em agent/application/. Adapter MastraAgentMemory (wraps @mastra/memory + @mastra/libsql). Working memory ON, semantic recall OFF default (ADR 004).
• 013 — Agente escreve no domínio. Write tools com pattern propose → confirm: primeira call retorna ToolReceipt com preview, segunda call com confirm:true + mesmo operationId persiste. Idempotência por operationId.

Fase 3 — Capacidade do agente (014–019)

Aqui o agente fica útil de verdade — renda variável, alerts, referral attribution, goals via conversa, onboarding zero-state, reminders proativos.

• 014 — Receita variável. recordExtraIncome, extraIncomeBy, incomeBreakdown, forecastIncome. VO IncomeEntry append-only. Variabilidade dentro do Household.
• 015 — Alerts proativos do orçamento. Domain Service BudgetAlerts.evaluate em planning/. VO Alert (kind/severity/message). Defaults warn=80%/critical=100% com override opcional. Alerts derivados, sem persistência.
• 016 — Referral attribution (sem fila). Modela attribution do share viral do landing. Sem fila, sem posição — só audit log de referrer → referee. Suporte ao K-factor 1.5 da NSM.
• 017 — Goal via conversa. Completa as write tools — criar goal via chat, contribuir via chat, ajustar target via chat.
• 018 — Onboarding zero-state. Composição multi-turn: casal entra sem nada, agente conduz através do household → primeiro income → primeiro expense.
• 019 — Reminder proativo. Cron + broadcast. Reminder de pagamento (cenário 001), check-in mensal, alert de overspend (cenário 015).

Fase 4 — Canal + UX (wa-001/2/3, landing-001/2/3, 020–023, ADRs 005–008)

Aqui o canal WhatsApp + landing PT-BR + qualidade conversacional entram em cena.

ADRs que pavimentam:

• ADR 005 — Astro landing stack. Stack do apps/landing/ (Astro + Tailwind + sitemap).
• ADR 006 — Anonymous-first identity. Casal entra sem email/password. Identidade emerge do uso.
• ADR 007 — WhatsApp channel via Baileys. Canal conversacional ÚNICO. Sem Cloud API fallback.
• ADR 008 — UX writing tone PT-BR. Tone of voice canônico do agente.

Scenarios:

• wa-001 — Onboarding via WhatsApp. Onboarding direto: primeira msg oi cria Household sem token. Prefixo ref-<token> opcional dispara attribution.
• wa-002 — Fatura via WhatsApp. Encaminhar PDF da fatura no chat. Cenário 009 + canal real.
• wa-003 — Grupo com parceiro. mel num grupo de 3 (member A + member B + agente). Mensagens compartilham contexto do Household.
• landing-001 — Hero direct-to-whats CTA. Hero “finanças do casal, sem briga” + CTA “Falar com mel” direto pra wa.me/<bot>?text=oi. Sem form, sem email.
• landing-002 — Share viral via ?ref= URL. “Convida parceiro” gera link ?ref=<token>. Attribution-only, sem fila. K-factor by design.
• landing-003 — Blog/chat teaser. Conteúdo SEO + teaser de chat com agente. CTA direto pra wa.me/<bot>.
• 020 — Gasto rápido (fast-path sem confirm). Casos óbvios (R$ 12 café) pulam o propose→confirm pra reduzir atrito. Refinement do cenário 013.
• 021 — Agente admite limite. Anti-hallucination. Agente diz “não sei” / “preciso de mais info” em vez de inventar.
• 022 — Eval harness conversacional. Suite de fixtures validando tool-call correctness por turno. Métrica conversation quality score da NSM mora aqui.
• 023 — Edge cases conversacionais. Casos chatos: typo de member, valor sem moeda, data ambígua, expense que não existe.

Estado atual

• Verde: 34 scenarios (000–026 + wa-001/2/3/4 + landing-001/2/3) — todos com spec passando.
• WIP: 0 vermelho. Backlog técnico em /cpo/030-next/ (BaileysAdapter prod, refactor pra dinero.js, vitest projects).
• ADRs: 10 aceitos (001–010).
• Próxima fase: V1.0 quality-first cutline cap 4 semanas — /cpo/010-roadmap/.

Ver snapshot live em /kpis/.