synapos 2.5.0

package/.synapos/squad-templates/backend/pipelines/steps/02-design-api.md

@@ -0,0 +1,155 @@
+---
+id: 02-design-api
+name: "Design do Contrato da API"
+agent: bruno-base
+execution: subagent
+model_tier: powerful
+output_files:
+  - api-contract.md
+veto_conditions:
+  - "Endpoint sem todos os status codes documentados"
+  - "Request/Response sem schema tipado"
+  - "Decisão arquitetural sem ADR"
+---
+
+# Design do Contrato da API
+
+Você é **Bruno Base**. Leia seu `.agent.md` para aplicar sua persona e princípios completos.
+
+## Contexto disponível
+
+- Task desta sessão: `_memory/memories.md`
+- Objetivo do squad: `squad.yaml → description`
+- Memória do squad: `_memory/memories.md` — padrões e ADRs anteriores
+- **Regras críticas do projeto:** `docs/tech-context/briefing/critical-rules.md` ← leia antes de qualquer decisão
+- **ADRs existentes:** `docs/tech-context/briefing/adrs-summary.md` ← verifique conflitos com decisões anteriores
+
+## Sua missão
+
+Definir o contrato completo da API antes de qualquer implementação.
+O contrato é a lei — o dev implementa exatamente o que está aqui.
+
+## Documento a gerar
+
+### `docs/api-contract.md`
+
+```markdown
+# Contrato da API: {nome da feature/recurso}
+
+**Data:** {YYYY-MM-DD}
+**Agent:** Bruno Base
+
+## Entendimento da Task
+{o que precisa ser construído em 2-3 frases — regra de negócio incluída}
+
+## Endpoints
+
+### {MÉTODO} {/v1/recurso/:id}
+
+**Descrição:** {o que faz}
+**Autenticação:** {requerida | pública} — {tipo: JWT Bearer | API Key}
+**Rate Limit:** {X req/min por IP | por usuário} *(se aplicável)*
+
+**Request:**
+```typescript
+// Headers
+Authorization: Bearer {token}  // se autenticado
+Content-Type: application/json
+
+// Path params
+id: string  // UUID
+
+// Query params (se GET)
+page?: number  // default: 1
+limit?: number  // default: 20, max: 100
+
+// Body (se POST/PUT/PATCH)
+{
+  campo: tipo  // descrição
+}
+```
+
+**Responses:**
+```typescript
+// 200 OK / 201 Created
+{
+  data: {
+    id: string
+    // demais campos
+  },
+  meta?: { page: number, total: number }  // para listagens
+}
+
+// 400 Bad Request — input inválido
+{ error: { code: "VALIDATION_ERROR", fields: { campo: "mensagem" } } }
+
+// 401 Unauthorized — sem token ou token inválido
+{ error: { code: "UNAUTHORIZED" } }
+
+// 403 Forbidden — token válido mas sem permissão
+{ error: { code: "FORBIDDEN" } }
+
+// 404 Not Found — recurso não existe OU não pertence ao usuário
+{ error: { code: "NOT_FOUND" } }
+
+// 409 Conflict — duplicata ou estado inválido
+{ error: { code: "{CÓDIGO_ESPECÍFICO}" } }
+
+// 422 Unprocessable — regra de negócio violada
+{ error: { code: "{CÓDIGO_ESPECÍFICO}", message: "..." } }
+
+// 500 Internal Server Error — erro inesperado
+{ error: { code: "INTERNAL_ERROR" } }
+```
+
+**Exemplos:**
+```bash
+# Request
+curl -X POST /v1/users \
+  -H "Authorization: Bearer {token}" \
+  -d '{"name": "João", "email": "joao@ex.com"}'
+
+# Response 201
+{"data": {"id": "uuid", "name": "João", "email": "joao@ex.com", "createdAt": "2025-01-01T00:00:00Z"}}
+```
+
+---
+
+## Estrutura de Camadas
+
+```
+src/
+├── domain/{recurso}/
+│   ├── {Entidade}.ts           → entidade de domínio
+│   ├── {Entidade}Repository.ts → interface do repositório
+│   └── {recurso}.errors.ts     → erros de domínio tipados
+├── application/{feature}/
+│   └── {CasoDeUso}.ts          → orquestração
+├── infrastructure/
+│   └── database/
+│       └── {Entidade}PgRepository.ts  → implementação PostgreSQL
+└── presentation/{recurso}/
+    ├── {Recurso}Controller.ts   → validação de input + delegação
+    ├── {Recurso}Schema.ts       → schema Zod de validação
+    └── {Recurso}Serializer.ts   → formatação do response
+```
+
+## ADR (se houver decisão relevante)
+
+### ADR-{N}: {título}
+**Contexto:** {por que essa decisão}
+**Decisão:** {o que foi escolhido}
+**Alternativas rejeitadas:** {opção} — {motivo}
+**Consequências:** ✅ {positivo} / ⚠ {trade-off}
+
+## Pontos de Atenção para Implementação
+{alertas, edge cases, integrações, consistência com outros endpoints}
+```
+
+## Critérios de qualidade
+
+- [ ] Todos os endpoints com todos os status codes de erro documentados
+- [ ] Request e Response tipados
+- [ ] Estrutura de camadas definida
+- [ ] Erros de domínio com código semântico (não só HTTP status)
+- [ ] ADR para qualquer decisão arquitetural não óbvia

package/.synapos/squad-templates/backend/pipelines/steps/03-checkpoint-contrato.md

@@ -0,0 +1,44 @@
+---
+id: 03-checkpoint-contrato
+name: "Aprovação do Contrato"
+execution: checkpoint
+---
+
+# Checkpoint — Aprovação do Contrato da API
+
+Antes de implementar, o usuário valida o contrato definido por Bruno Base.
+
+## Apresentar resumo
+
+Leia `docs/api-contract.md` e apresente:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+CONTRATO DA API: {nome da feature}
+
+Endpoints:
+  {MÉTODO} {rota} — {descrição em 1 linha}
+  {MÉTODO} {rota} — {descrição em 1 linha}
+
+Estrutura de camadas:
+  {resumo em 2-3 linhas}
+
+{Se houver ADR}: Decisão-chave: {título}
+
+Status codes mapeados: {lista dos erros tratados}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Pergunta ao usuário
+
+```
+O contrato está alinhado?
+
+[1] Sim — implementar
+[2] Ajustar — {o que mudar no contrato?}
+[3] Simplificar — remover endpoint ou campo não necessário agora
+```
+
+**Se [2] ou [3]:** Atualize `docs/api-contract.md` e registre em `_memory/memories.md`.
+
+**Se [1]:** Prossiga para implementação.

package/.synapos/squad-templates/backend/pipelines/steps/04-implementacao.md

@@ -0,0 +1,113 @@
+---
+id: 04-implementacao
+name: "Implementação Backend"
+agent: alexandre-api
+execution: subagent
+model_tier: powerful
+veto_conditions:
+  - "Input externo sem validação de schema (Zod/Joi)"
+  - "Erro capturado silenciosamente (catch vazio ou só console.log)"
+  - "Query SQL com concatenação de string"
+  - "Operação atômica sem transação de banco"
+  - "Log sem correlationId"
+on_reject: 04-implementacao
+---
+
+# Implementação Backend
+
+Você é **Alexandre API**. Leia seu `.agent.md` para aplicar sua persona e princípios completos.
+
+## Contexto disponível
+
+- Contrato da API: `docs/api-contract.md` ← **leia antes de qualquer código**
+- Memória do squad: `_memory/memories.md`
+- **Regras críticas do projeto:** `docs/tech-context/briefing/critical-rules.md` ← aplique todas as regras durante a implementação
+
+## Sua missão
+
+Implementar exatamente o contrato definido, respeitando a estrutura de camadas.
+
+## Regras de implementação (veto se violadas)
+
+### 1. Validação de input obrigatória
+
+```typescript
+// Sempre com Zod — no controller, antes de qualquer lógica
+const schema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2).max(100),
+})
+
+const result = schema.safeParse(req.body)
+if (!result.success) {
+  return res.status(422).json({
+    error: { code: 'VALIDATION_ERROR', fields: result.error.flatten().fieldErrors }
+  })
+}
+```
+
+### 2. Tratamento explícito de erros
+
+```typescript
+// ❌ nunca
+try { ... } catch (e) {} // silencioso
+try { ... } catch (e) { console.log(e) } // não é tratamento
+
+// ✅ sempre — erros de domínio tipados
+try {
+  const result = await useCase.execute(input)
+  return res.status(201).json({ data: Serializer.toJSON(result) })
+} catch (error) {
+  if (error instanceof EmailAlreadyExistsError) {
+    return res.status(409).json({ error: { code: 'EMAIL_ALREADY_EXISTS' } })
+  }
+  logger.error('Unexpected error', { error, correlationId: req.id })
+  return res.status(500).json({ error: { code: 'INTERNAL_ERROR' } })
+}
+```
+
+### 3. Sem SQL por concatenação
+
+```typescript
+// ❌ nunca
+db.query(`SELECT * FROM users WHERE email = '${email}'`)
+
+// ✅ sempre
+db.query('SELECT * FROM users WHERE email = $1', [email])
+```
+
+### 4. Transações para operações atômicas
+
+```typescript
+await db.transaction(async (trx) => {
+  await userRepo.save(user, trx)
+  await walletRepo.create({ userId: user.id }, trx)
+  // se qualquer operação falhar, ambas são revertidas
+})
+```
+
+### 5. Log estruturado com correlationId
+
+```typescript
+logger.info('User created', {
+  correlationId: req.id,  // sempre
+  userId: user.id,
+  action: 'user.create',
+  durationMs: Date.now() - startTime,
+})
+```
+
+## Estrutura de entrega
+
+Para cada arquivo implementado:
+- **Caminho:** `src/{camada}/{recurso}/{Arquivo}.ts`
+- **O que faz:** {1 linha}
+
+Ao final, confirme:
+- [ ] Validação de input com Zod/schema
+- [ ] Todos os erros tratados explicitamente
+- [ ] Sem SQL por concatenação
+- [ ] Transações onde necessário
+- [ ] Logs com correlationId
+- [ ] Autorização verificada (não só autenticação)
+- [ ] Implementação segue a estrutura de camadas do contrato

package/.synapos/squad-templates/backend/pipelines/steps/05-seguranca.md

@@ -0,0 +1,100 @@
+---
+id: 05-seguranca
+name: "Auditoria de Segurança"
+agent: sergio-seguranca
+execution: subagent
+model_tier: powerful
+output_files:
+  - security-review.md
+veto_conditions:
+  - "IDOR identificado sem correção proposta"
+  - "Secret em código ou log"
+  - "SQL injection possível"
+  - "Endpoint sensível sem rate limiting"
+on_reject: 04-implementacao
+---
+
+# Auditoria de Segurança
+
+Você é **Sérgio Segurança**. Leia seu `.agent.md` para aplicar sua persona e princípios completos.
+
+## Contexto disponível
+
+- Contrato da API: `docs/api-contract.md`
+- Implementação do step anterior (código entregue por Alexandre API)
+- Memória do squad: `_memory/memories.md`
+
+## Execute a auditoria OWASP
+
+### A01 — Broken Access Control
+- [ ] Endpoints verificam que o recurso pertence ao usuário autenticado (IDOR)?
+- [ ] Endpoints admin exigem role adequado?
+- [ ] Não retorna 403 quando recurso existe mas não pertence ao usuário (use 404)?
+
+### A02 — Cryptographic Failures
+- [ ] Nenhum dado sensível em log (senha, token, PII)?
+- [ ] Senhas hasheadas com bcrypt/argon2?
+- [ ] Tokens JWT com algoritmo seguro (não `none`)?
+
+### A03 — Injection
+- [ ] Zero concatenação de string em queries SQL?
+- [ ] Input sanitizado antes de uso em comandos externos?
+
+### A04 — Insecure Design
+- [ ] Rate limiting em endpoints de auth (login, reset de senha)?
+- [ ] Endpoints de criação de conta protegidos contra flood?
+
+### A05 — Security Misconfiguration
+- [ ] CORS configurado de forma restritiva (não `*`)?
+- [ ] Headers de segurança presentes (via helmet)?
+- [ ] Stack trace nunca exposto no response?
+
+### A07 — Authentication Failures
+- [ ] Tokens expiram?
+- [ ] Logout invalida o token?
+
+## Documento a gerar
+
+### `docs/security-review.md`
+
+```markdown
+# Security Review
+
+**Data:** {YYYY-MM-DD}
+**Auditor:** Sérgio Segurança
+
+## Resumo
+- Críticos: {N}
+- Altos: {N}
+- Médios: {N}
+- Baixos: {N}
+- Aprovado: {Sim | Não — requer correção}
+
+## Findings
+
+### [CRÍTICO] {título} *(se encontrado)*
+**Localização:** {arquivo}:{linha aproximada}
+**Descrição:** {o que é o problema e como pode ser explorado}
+**Fix obrigatório:**
+```
+{código ou abordagem de correção}
+```
+
+### [ALTO] {título} *(se encontrado)*
+...
+
+### [MÉDIO] {título} *(se encontrado)*
+...
+
+## Itens Aprovados
+{checklist de itens que passaram na auditoria}
+
+## Decisão
+{Aprovado | Requer correção dos itens Críticos/Altos antes de prosseguir}
+```
+
+## Regra de decisão
+
+- **Critical/High encontrado** → retorna para implementação com fix detalhado
+- **Apenas Medium/Low** → aprovado, mas medium deve ir para `_memory/memories.md` como débito técnico
+- **Clean** → aprovado, prosseguir para review

package/.synapos/squad-templates/backend/pipelines/steps/06-review.md

@@ -0,0 +1,80 @@
+---
+id: 06-review
+name: "Code Review Backend"
+agent: roberto-revisao-be
+execution: inline
+model_tier: powerful
+gate: GATE-5
+output_files:
+  - review-notes.md
+veto_conditions:
+  - "Review sem categorização BLOCKER/SUGGESTION/QUESTION/PRAISE"
+  - "BLOCKER sem fix sugerido"
+on_reject: 04-implementacao
+---
+
+# Code Review Backend
+
+Você é **Roberto Revisão**. Leia seu `.agent.md` para aplicar sua persona e princípios completos.
+
+## Contexto disponível
+
+- Contrato da API: `docs/api-contract.md`
+- Implementação (código do step 04)
+- Security review: `docs/security-review.md`
+
+## Execute o review em 4 camadas
+
+### Camada 1 — Corretude
+- [ ] A implementação segue o contrato definido?
+- [ ] Todos os status codes documentados implementados?
+- [ ] Race conditions possíveis em operações concorrentes?
+- [ ] Transações onde necessário?
+
+### Camada 2 — Segurança (baseline)
+- [ ] Input validado com schema?
+- [ ] Autorização verificada (não apenas autenticação)?
+- [ ] Nenhum secret em código ou log?
+- [ ] Erros internos não expostos no response?
+
+### Camada 3 — Arquitetura
+- [ ] Lógica de negócio no domain/application (não no controller)?
+- [ ] Controller apenas valida input e delega?
+- [ ] Dependências externas abstraídas via interface?
+
+### Camada 4 — Qualidade
+- [ ] Nomes descritivos?
+- [ ] Erros tipados (não só string messages)?
+- [ ] Testes cobrem o caminho feliz e os principais erros?
+- [ ] Sem `console.log` ou código morto?
+
+## Formato de comentário (obrigatório)
+
+```
+[BLOCKER] {descrição do problema e impacto}
+Fix: {código ou abordagem}
+
+[SUGGESTION] {melhoria sem bloquear}
+
+[QUESTION] {dúvida específica}
+
+[PRAISE] {o que está bem feito}
+```
+
+## Gerar `docs/review-notes.md`
+
+```markdown
+# Review Notes — {feature}
+
+**Data:** {YYYY-MM-DD}
+**Reviewer:** Roberto Revisão
+
+## Resumo
+BLOCKERs: {N} | SUGGESTIONs: {N} | QUESTIONs: {N} | PRASEs: {N}
+
+## Comentários
+{todos os comentários categorizados}
+
+## Decisão
+{Aprovado | Requer correção: {lista de BLOCKERs}}
+```

package/.synapos/squad-templates/backend/pipelines/steps/atualizar-tarefa.md

@@ -0,0 +1,138 @@
+---
+id: atualizar-tarefa
+name: "Atualizar Tarefa"
+execution: checkpoint
+---
+
+# Atualizar Tarefa
+
+A implementação foi concluída. Registre o progresso onde as tarefas estão sendo gerenciadas.
+
+## Identificar tarefa e plataforma
+
+Leia `_memory/memories.md` da sessão atual:
+- `Task:` — descrição do que foi feito
+- `Issue:` — referência da tarefa (número, plataforma, local ou —)
+
+Apresente ao usuário:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SESSÃO CONCLUÍDA
+
+Task: {Task da sessão}
+Issue: {Issue registrada}
+
+A tarefa foi concluída?
+
+✅ Sim — marcar como concluída
+🔄 Parcial — registrar progresso e manter aberta
+⏭️  Pular — não atualizar agora
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Aguarde a seleção. Se **Pular**, encerre aqui.
+
+---
+
+## Executar por plataforma
+
+### 📁 Local — `docs/specs/*-tasks.md`
+
+Abra o arquivo de tarefas identificado no `Issue:` do memories.md.
+
+Localize o item correspondente e marque como concluído:
+- `- [ ]` → `- [x]`
+
+Se parcial, adicione nota abaixo do item:
+```markdown
+- [~] RF-{N}: {título}
+  > Parcial — {YYYY-MM-DD}: {o que foi feito}. Pendente: {o que falta}
+```
+
+---
+
+### 🐙 GitHub Issues
+
+**Se concluída:**
+```bash
+# Fechar a issue
+gh issue close {número} --comment "Implementado. Referência: {branch ou PR}"
+
+# Ou adicionar label 'done' e fechar
+gh issue edit {número} --add-label "done"
+gh issue close {número}
+```
+
+**Se parcial:**
+```bash
+gh issue comment {número} --body "Progresso — {YYYY-MM-DD}: {o que foi implementado}. Pendente: {o que falta}"
+gh issue edit {número} --add-label "in-progress"
+```
+
+---
+
+### 📐 Linear
+
+**Se concluída:**
+- Se Linear MCP disponível: atualize o status para `Done` / `Completed`
+- Caso contrário, exiba instrução:
+
+```
+Linear — Atualizar manualmente:
+Issue: {ID registrado no memories.md}
+Novo status: Done
+Comentário: Implementado em {YYYY-MM-DD}
+```
+
+**Se parcial:**
+```
+Linear — Atualizar manualmente:
+Issue: {ID}
+Novo status: In Progress
+Comentário: {progresso + pendências}
+```
+
+---
+
+### 🔲 Jira
+
+Exiba instrução:
+
+```
+Jira — Atualizar manualmente:
+Issue: {ID registrado no memories.md}
+Transição: {Done | In Progress}
+Comentário: {resumo do que foi feito}
+```
+
+---
+
+## Registrar no memories.md
+
+Adicione entrada:
+
+```markdown
+## Tarefa concluída — {YYYY-MM-DD}
+Task: {descrição}
+Issue: {referência}
+Status: {concluída | parcial}
+{SE PARCIAL:}
+Pendente: {o que falta}
+```
+
+---
+
+## Confirmação
+
+```
+✅ Progresso registrado!
+
+Task: {descrição}
+Status: {concluída | parcial}
+Plataforma: {local | GitHub #{N} | Linear | Jira | —}
+
+{SE CONCLUÍDA E TODAS AS TAREFAS DONE:}
+🎉 Todas as tarefas da feature estão concluídas.
+   Próximo passo: verificar handoff em docs/specs/{feature-slug}-handoff.md
+```

package/.synapos/squad-templates/backend/pipelines/steps/bfbe-02-diagnostico.md

@@ -0,0 +1,47 @@
+---
+id: bfbe-02-diagnostico
+name: "Diagnóstico Backend"
+agent: bruno-base
+execution: inline
+model_tier: powerful
+---
+
+# Diagnóstico de Bug Backend
+
+Você é **Bruno Base**. Pense em camadas e contratos.
+
+## Perguntar ao usuário
+
+```
+1. O que deveria acontecer?
+2. O que está acontecendo? (erro, resposta errada, lentidão)
+3. Como reproduzir? (endpoint, payload, contexto)
+4. Logs/stack trace disponíveis?
+5. Quando começou? (deploy, mudança de dados, aumento de volume)
+```
+
+## Analisar e apresentar
+
+```
+DIAGNÓSTICO
+
+Comportamento esperado: {...}
+Comportamento atual: {...}
+
+Camada provável do problema:
+  □ Validação (controller/schema)
+  □ Regra de negócio (domain/application)
+  □ Infraestrutura (banco, cache, serviço externo)
+  □ Configuração/ambiente
+
+Causa raiz hipotética:
+  {análise técnica}
+
+Arquivos suspeitos:
+  - {arquivo} — {por quê}
+
+Abordagem de fix:
+  {descrição da solução em 2-3 frases}
+```
+
+Pergunte: `[1] Correto — implementar fix  [2] Ajustar hipótese`