product-runner 0.5.0

package/common/agents/protocolo-de-gates.md

@@ -0,0 +1,51 @@
+# Protocolo de Gates
+
+> Regras de gate e de calibragem por stakes, **comuns a todos os agentes do pipeline**. Cada agente referencia este arquivo em vez de redefinir as regras localmente — fonte de verdade única, sem drift entre agentes. Mantenha este arquivo na mesma pasta dos agentes.
+
+---
+
+## Por que este arquivo existe
+
+Os agentes erravam o mesmo ponto: **declaravam rigor de gate e depois cediam a um "ok" genérico em ponto de alto risco.** Regra em prosa que o agente "lembra" é insuficiente — é o mesmo aprendizado dos critérios meta do `spec-guide` (checklist binário vence atenção textual). Este protocolo troca autocontrole por procedimento.
+
+---
+
+## 1. Stakes calibram tudo
+
+Antes de cada decisão, classifique: errar aqui é **caro/irreversível (alto risco)** ou **barato/reversível (baixo risco)**? A classificação calibra três coisas: profundidade de investigação, rigor de gate, e exigência de confirmação.
+
+A **classificação** é discricionária — é o julgamento do agente. A **execução** depois dela não é (ver §2). Investigação que não reduz risco e só cansa o humano é falha, não virtude.
+
+---
+
+## 2. Procedimento de gate
+
+- **Baixo risco:** declare a interpretação/suposição e **siga**. Sem turno de confirmação dedicado. Mantém o fluxo leve.
+- **Alto risco:** emita uma **lista numerada** dos itens que precisam de confirmação. O gate **só fecha** quando cada item recebe confirmação que o referencia.
+  - Resposta genérica ("ok", "está ok", "sim", "pode seguir") a um gate de alto risco **não fecha o gate**. Você **não tem discrição** para aceitá-la: a classificação de risco já foi feita; genérico é, por definição, gate aberto.
+  - Ao receber genérico, **re-apresente os itens numerados e peça confirmação por item** (uma vez, sem repetir indefinidamente).
+  - Silêncio nunca é aprovação.
+
+---
+
+## 3. Validação diferencial (valores verificáveis)
+
+Se um artefato contém **valores verificáveis** — contas, números, critérios de aceite binários — esses valores são **automaticamente itens de alto risco** (§2), porque serão consumidos a jusante como referência de comportamento.
+
+- Mostre a conta/derivação explicitamente.
+- No gate, conduza o humano a confirmar **os valores**, não só "o documento parece bom". Peça confirmação do resultado, não da aparência.
+
+---
+
+## Anti-padrões
+
+- Declarar rigor ("ok genérico não fecha aqui") e depois fechar com ok genérico.
+- Aceitar "está ok" sobre artefato com contas sem que os números tenham sido confirmados.
+- Usar a classificação de risco como desculpa para pular a checklist no que já foi classificado como alto.
+- Aplicar a checklist pesada a **tudo**, inclusive baixo risco — isso reintroduz o "massivo" e treina o humano a carimbar.
+
+---
+
+## Limite honesto
+
+Este protocolo é **mais forte que regra em prosa, não à prova de falha**. Um LLM ainda pode violar regra explícita. A única validação real é rodar e observar — trate como hipótese até ter evidência de runs.

package/common/claude-md.template.md

@@ -0,0 +1,210 @@
+# {PROJECT_NAME}
+
+{Descrição curta do projeto — 1-2 frases.}
+
+> **Este é um template.** Ao usar, mescle com `profile-{cli|ssr}/claude-md.extension.md`
+> da pasta de templates. Substitua valores entre `{}` pelos do projeto.
+
+## Stack
+
+- **Runtime:** {ex: Node.js + TypeScript}
+- **Validação:** Zod (schemas como fonte de verdade única)
+- **Testes:** Vitest
+- **Formatter:** Prettier + lint-staged + husky (desde dia zero)
+- {Outras deps específicas do projeto}
+
+## Arquitetura
+
+### Princípio central
+
+{Descrever em 2-3 linhas o princípio arquitetural do projeto.
+Exemplos:
+- "Lógica de domínio desacoplada do framework. Services são
+  TypeScript puro. Camada de orquestração é casca fina que delega."
+- "Loop infinito em casca fina. Lógica de trade vive em services
+  testáveis com mock de broker."}
+
+### Estrutura de pastas
+
+{Definir conforme perfil do projeto. Ver `profile-{cli|ssr}/code-patterns.md`
+pra estrutura recomendada.}
+
+## Docs de referência
+
+Antes de implementar uma spec, consultar o doc relevante:
+
+- [design-principles](./docs/design-principles.md) — princípios técnicos, princípios LLM-first, valores
+- [code-patterns](./docs/code-patterns.md) — schemas Zod, services, padrões de código
+- [spec-guide](./docs/spec-guide.md) — como ler, escrever e implementar specs
+  (inclui critérios meta M1, M2, M3 — e M4 em specs de UI)
+- [pipeline](./docs/pipeline.md) — como uma ideia vira spec **e código**: discovery → conceituação →
+  doc-funcional → geração de spec → implementação → **review** (Review.Code →
+  User Review → Review.Product → Review.LLM). Agentes em
+  [agents/](./docs/agents/README.md); gates em [protocolo-de-gates](./docs/agents/protocolo-de-gates.md).
+  Para descobrir em que etapa o projeto está, ver "Em que etapa o projeto está" abaixo
+- {Outros docs do perfil — [api-patterns](./docs/api-patterns.md) / [ui-patterns](./docs/ui-patterns.md) no SSR}
+
+## Padrão de dados
+
+Zod entity como raiz. Tipos derivam via `z.infer`. Validação na
+fronteira (boot, resposta de I/O externo, leitura de arquivo).
+Dentro dos services, dados são tipados e confiáveis.
+
+Detalhes em [code-patterns](./docs/code-patterns.md).
+
+## Convenções de código
+
+### Geral
+
+- TypeScript strict mode: começar `false`, migrar gradualmente.
+- Arquivos novos em `kebab-case.ts`. Arquivos legados ficam até
+  serem refatorados.
+- Exportar funções nomeadas, não default exports.
+- Sem `any` em código novo. Em código legado, manter até refactor
+  da spec correspondente.
+
+### Services e lógica
+
+- Funções puras quando possível (input → output, sem side-effects).
+- Services nunca importam módulos de I/O ou framework
+  (`fs`, `dotenv`, `process`, libs externas com side-effects).
+- Services nunca chamam `console.log` direto. Logs estruturados
+  via logger dedicado quando aplicável.
+- Side-effects (IO, integração externa, log) ficam em camada
+  dedicada (persistence/, integrations/, ou orquestrador).
+
+### Erros
+
+- Lançar classe específica do domínio (ex: `DomainError` ou
+  subclasses), nunca `Error` puro em código de domínio.
+- Preservar stack trace: `throw error` ou `throw new XxxError(msg, { cause: error })`,
+  nunca `throw error.message`.
+
+### Validação
+
+- Toda leitura de I/O externa passa por `Schema.safeParse()`.
+- Resposta de lib externa passa por schema parse antes de chegar
+  na lógica.
+- Dentro de services: zero revalidação. Os dados já estão tipados.
+
+## Workflow de desenvolvimento
+
+Spec-first: cada mudança não-trivial passa por uma spec antes
+da implementação.
+
+### Onde mora cada coisa
+
+| Etapa                                     | Ferramenta                                       |
+| ----------------------------------------- | ------------------------------------------------ |
+| Análise, decisão, escrita de spec, review | Cowork (Claude.ai com acesso aos arquivos)       |
+| Implementação                             | Claude Code (sessão dedicada apontando pro repo) |
+
+### Ciclo
+
+1. Cowork analisa, escreve spec, grava em `specs/`.
+2. Claude Code implementa e preenche "Decisões de implementação" na própria
+   spec (critério M1).
+3. **Review** (sub-cadeia, por incremento): Review.Code cruza cada critério
+   com o código real → User Review (usabilidade) → Review.Product (roteia
+   feedback) → Review.LLM (corrige o pipeline). Detalhe em
+   [pipeline](./docs/pipeline.md) §5.
+4. Próxima spec.
+
+> Nota: preencher "Decisões de implementação" é rastro do passo 2
+> (implementação), **não** do passo 3 (review). O review deixa rastro
+> próprio (veredito do Review.Code). Ver "Em que etapa o projeto está".
+
+### Ao implementar uma spec (Claude Code)
+
+1. Ler a spec inteira antes de começar.
+2. Verificar "Depende de" — se a dependência não está implementada, parar.
+3. Consultar `docs/` referenciados.
+4. Implementar mudanças.
+5. Rodar critérios de aceite — confirmar cada um.
+6. Reportar: critérios ✅/❌/⚠️ + decisões de implementação + notas.
+
+### Regras operacionais
+
+- **3 strikes.** Se uma abordagem falhou 3 vezes, parar e relatar.
+  Não entrar em loop tentando variações.
+- **Spec vs realidade.** Se a spec tem um tradeoff técnico significativo
+  na implementação, PARAR e apresentar o caso. Spec é guia, não lei.
+- **Menor superfície.** Preferir solução que altera menos arquivos.
+- **Não adivinhar.** Se a spec não cobre, perguntar.
+- **Mudanças adjacentes vão pra outra spec.** Bug ou refactor tentador
+  observado durante implementação não entra na spec atual. Anotar
+  em "Decisões de implementação", abrir spec separada se relevante.
+  Detalhe em [spec-guide](./docs/spec-guide.md).
+- **Leitura consolidada de arquivos grandes.** Antes de fazer
+  múltiplos `Read` do mesmo arquivo com offsets diferentes, considerar
+  1 leitura com `limit` alto (ex: `limit: 2000` cobre arquivos até
+  ~2000 linhas). Custo de tokens da leitura única é menor que custo
+  de round-trips fragmentados.
+- **Decisões de implementação são obrigatórias.** Toda spec implementada
+  termina com essa seção preenchida — escolhas, divergências, tentações
+  não feitas. Sem isso, spec está incompleta. Reforçado pelo critério
+  meta **M1** (ver [spec-guide](./docs/spec-guide.md)).
+
+### Fixes diretos (sem spec)
+
+Se altera contrato (schema, função pública, comportamento observável
+de fora), spec. Se é correção do que já deveria funcionar (typo,
+parêntese, condição invertida, ajuste de mensagem), fix direto.
+
+## Comandos úteis
+
+{Definir conforme perfil do projeto.}
+
+## Configuração
+
+{Tabela de arquivos de config + se vão pra git ou não.}
+
+| Arquivo        | Conteúdo                          | Comitado? |
+| -------------- | --------------------------------- | --------- |
+| `.env`         | Segredos                          | ❌ NUNCA  |
+| `.env.example` | Mesmas chaves sem valor           | ✅        |
+| {outros}       | ...                               | ...       |
+
+## Estado do refactor / desenvolvimento
+
+> **Índice derivado, não fonte.** Esta tabela e o [_overview](./specs/_overview.md) são
+> conveniência e **drift-am**. O estado real de cada spec mora **no conteúdo
+> da spec** (critérios marcados, veredito de review), não aqui. Mesmo
+> princípio LDoc→HDoc. Se a tabela diverge da spec, a **spec ganha**.
+
+Roadmap completo em [_overview](./specs/_overview.md).
+
+| #   | Spec                        | Status                     |
+| --- | --------------------------- | -------------------------- |
+| 00  | {Primeira spec}             | {⏳ pendente / ✅ feito}   |
+| ... | ...                         | ...                        |
+
+### Em que etapa o projeto está
+
+Antes de dizer "qual a próxima etapa" ou "X está pronto?": **descubra pelo
+rastro no conteúdo das specs**, não pela tabela acima.
+
+- Cada estágio do pipeline deixa rastro detectável na spec/artefato; o
+  **primeiro estágio sem rastro é o próximo passo**. Tabela de rastros em
+  [pipeline](./docs/pipeline.md) ("Em que estágio estou?").
+- **Cuidado:** "Decisões de implementação" preenchidas são rastro da
+  **implementação** (estágio 4, critério M1), **não** do review. O review
+  deixa rastro próprio (veredito do Review.Code). Não confunda — se não há
+  veredito de review, o próximo passo é **rodar os fluxos de review**.
+- A spec é a fonte; `_overview` e a tabela acima são índice derivado que
+  drift-a. Nunca responda status a partir de leitura truncada (`head -N`).
+
+## Manutenção dos protocolos de doc
+
+Estes docs e este `CLAUDE.md` vieram de `product-runner` (manifesto em
+`docs/.product-runner.json`). O protocolo completo de manutenção
+— diagnóstico do projeto, verificação de versão, `update`, migrations e handoffs —
+vive no agente [agente-prod-runner](./docs/agents/agente-prod-runner.md).
+
+**No início de uma sessão de trabalho, ≤ 1×/dia:** siga a *Verificação de
+atualização* do [agente-prod-runner](./docs/agents/agente-prod-runner.md) — ele compara a versão
+publicada com a do manifesto e, havendo novidade, conduz o `update` com você.
+Nunca aplica nada (nem `--force`) sem sua aprovação.
+
+> **Gitignore:** mantenha `docs/.prod-runner-update/` no `.gitignore` — é área de
+> trabalho efêmera do `update`, não versionada.

package/common/design-principles.md

@@ -0,0 +1,229 @@
+# Design principles
+
+Princípios que guiam decisões neste projeto, organizados por
+o que ajudam: estrutura técnica do código, ou trabalho da LLM.
+
+Princípios não são "boas práticas genéricas" — são regras
+acionáveis com critério claro de violação.
+
+---
+
+## Princípios técnicos
+
+### 1. Fonte de verdade única
+
+Uma definição. Tudo deriva dela. Se um campo muda na fonte,
+o que depende dele quebra em compile-time.
+
+**Na prática:**
+
+- `ConfigValuesSchema` (Zod) é a raiz. `type ConfigValues = z.infer<typeof ConfigValuesSchema>`.
+- Inputs derivam por `pick`/`extend`. Outputs derivam por `omit`/`extend`.
+- Zero `interface` ou `type` escritos à mão que duplique algo do schema.
+
+**Anti-pattern:**
+
+```ts
+// ❌ tipo paralelo ao schema, vai sair de sincronia
+const ConfigValuesSchema = z.object({ id: z.string(), ... });
+interface ConfigValues { id: string; ... }
+```
+
+**Por que importa pra LLM:** ela lê 1 schema e sabe todos os tipos.
+Não precisa cruzar definições espalhadas.
+
+### 2. Lógica de domínio isolada do framework e libs externas
+
+Funções de cálculo, decisão e regras nunca importam
+`@binance/connector`, `dotenv`, `fs`, `process`. Recebem
+inputs tipados, retornam outputs tipados.
+
+**Na prática:**
+
+- `recalculateLimits(state, prices, config)` — função pura.
+- Acesso à Binance via `BrokerClient` (interface), implementado por `BinanceBroker`.
+- Persistência via funções dedicadas (`load`, `save`), nunca dentro da lógica de trade.
+
+**Anti-pattern:**
+
+```ts
+// ❌ lógica chamando broker direto
+function recalculateLimits(...) {
+    const price = await client.tickerPrice(...);
+    ...
+}
+```
+
+**Por que importa pra LLM:** função pura é caixa fechada com
+contexto reduzido. LLM consegue raciocinar/testar/refatorar
+sem carregar contexto da Binance.
+
+### 3. Fronteira é onde valida
+
+Valida UMA vez, na entrada do sistema. Dentro da lógica,
+dados são tipados e confiáveis.
+
+**Na prática:**
+
+- Boot: `ConfigValuesSchema.safeParse(JSON.parse(arquivo))`. Se inválido, fail-fast com mensagem clara.
+- Resposta da Binance: `BinanceTickerResponseSchema.parse(response.data)` antes de chegar na lógica.
+- Reload de estado: `BotStateSchema.parse(json)` em vez de `Object.setPrototypeOf` cego.
+- Dentro de services: zero revalidação. Os dados já estão tipados.
+
+**Anti-pattern:**
+
+```ts
+// ❌ confiar em forma sem validar
+const price = Number(response.data.price); // se .data ou .price mudar, quebra silencioso
+```
+
+```ts
+// ❌ revalidar dentro de service
+function buyAndSell(state) {
+    if (!state.config.tradeSymbol) throw ...; // já validado na entrada
+}
+```
+
+### 4. Casca fina na borda
+
+A camada de orquestração (loop principal, entrypoint) não pensa.
+Recebe, delega, responde.
+
+**Na prática:**
+
+- `index.ts` ≤ 100 linhas. Carrega config, instancia broker, dispara `tradingLoop`.
+- Loop em `services/trading/loop.ts`. Decisões em `services/trading/decisions.ts`. Etc.
+- Aninhamento máximo no entrypoint: 2 níveis.
+
+**Anti-pattern:**
+
+- `index.ts` com 800 linhas misturando loop, lógica, ordens e persistência. (estado atual — refactor planejado em refactor/06)
+
+---
+
+## Princípios LLM-first
+
+Regras que existem porque LLM como executor tem limitações
+específicas: tende a fazer mais que pedido, entra em loops,
+"esquece" decisões anteriores.
+
+### 1. Critérios de aceite binários
+
+Toda spec termina com checklist. Cada item passa ou não passa.
+Verificável por comando ou observação direta.
+
+**Na prática:**
+
+- `git grep -E '(eNls3mjIoTZ|vIE3NutkqUq6)'` retorna vazio. ✅/❌
+- Rodar `npm run start` sem `.env` termina com exit code != 0. ✅/❌
+
+**Anti-pattern:**
+
+- "Implementar de forma robusta" — não verificável.
+- "O bot funciona corretamente" — não verificável sem critério.
+
+**Por que importa:** elimina "parcialmente implementado". LLM tem
+sinal claro pra parar.
+
+### 2. Escopo travado por não-objetivos explícitos
+
+Toda spec lista "Não-objetivos" antes do checklist.
+Sem isso, LLM tende a fazer mais que pedido.
+
+**Na prática:**
+
+```markdown
+## Não-objetivos
+
+Esta spec NÃO faz:
+
+- tsconfig.json (vem em setup/01)
+- Vitest, testes (setup/01)
+- Fix do bug aritmético em makeTradingTurnLog (refactor/03)
+
+Se aparecer tentação, não fazer. Anotar em "Decisões de implementação".
+```
+
+**Por que importa:** lista de "não fazer" é mais eficaz que aviso
+genérico. Ancoragem específica trava escopo.
+
+### 3. Reportar decisões na própria spec
+
+Após implementação, preencher seção "Decisões de implementação"
+da spec. Documentar:
+
+- Divergências do plano original.
+- Escolhas entre alternativas (qual e por quê).
+- Tentações de escopo que apareceram (não feitas, anotadas).
+
+**Na prática:** ver final de `specs/setup/00-hardening.md`.
+
+**Por que importa:** próxima sessão (humana ou LLM) lê a spec e
+sabe o estado real, não o estado planejado. Sem isso, divergência
+silenciosa acumula.
+
+### 4. Guardrail dos 3 strikes
+
+Se uma abordagem falhou, tentou variação, falhou de novo,
+tentou outra: PARA na 3ª tentativa. Reporta o que tentou
+e pede orientação.
+
+**Na prática:** em problemas técnicos novos (erro estranho,
+config que não funciona, comportamento inesperado), LLM
+não fica iterando indefinidamente.
+
+**Por que importa:** sem isso, sessão entra em loop e acumula
+confusão. Vide o caso `searchVector/Prisma` no DocManager.
+
+### 5. Documentar o porquê, não só o quê
+
+Toda decisão arquitetural tem nota explicando o motivo.
+CLAUDE.md, docs e specs sempre têm "porquê".
+
+**Na prática:**
+
+- "Usamos `Object.setPrototypeOf` em vez de factory `fromPlain` PORQUE é a substituição mais direta da reanexação manual sem expandir escopo desta spec."
+- "Loop sequencial em vez de paralelo PORQUE rate-limit da Binance e simplifica raciocínio sobre estado."
+
+**Anti-pattern:** comentário que descreve o óbvio (`// incrementa contador`)
+em vez de explicar a decisão.
+
+**Por que importa:** sem o porquê, decisões são revisitadas a cada
+sessão. LLM "redebate" coisas já decididas.
+
+---
+
+## Valores não-acionáveis
+
+Estes não são princípios — são valores culturais. Influenciam
+mentalidade mas não dão critério binário.
+
+### Evolução aditiva
+
+**Como cultura:** preferir mudanças que estendem em vez de quebrar.
+Campos novos nullable, schemas antigos continuam parseando.
+
+**Como regra acionável:** "Adicionar campo: nullable. Renomear:
+criar novo + deprecar. Remover: marcar deprecated em comentário,
+remover só após 1 ciclo de uso."
+
+Quando esta segunda forma estiver consolidada, vira princípio
+técnico. Por enquanto, é nota.
+
+### Pragmatismo sobre purismo
+
+**Como cultura:** se ferramenta não suporta algo nativamente,
+contornar com escape hatch mais simples e documentar.
+
+**Aviso de dívida:** LLM aceita escape hatches com facilidade.
+O risco é normalizar `as any`, `// @ts-ignore`, dado mockado em
+produção, "deixa pra depois".
+
+**Regra de uso:** qualquer escape hatch (cast, ignore, hack)
+DEVE ser documentado em "Decisões de implementação" da spec
+com motivo. Sem isso, vira dívida invisível.
+
+---
+
+_Este documento é vivo. Princípios entram por observação prática
+de problema, não por importação de "boas práticas"._