@daniellins/power-claude 0.16.3

package/template/pods/automation/knowledge/langgraph-patterns.md

@@ -0,0 +1,126 @@
+# Langgraph — Padrões de produção (Python)
+
+Referência de trabalho do pod `automation`. Carregado sob demanda pelos comandos do `langgraph-architect`.
+
+## 1. StateGraph básico com TypedDict
+
+```python
+from typing import Annotated, TypedDict
+from langgraph.graph import StateGraph, START, END
+from langgraph.graph.message import add_messages
+
+class AgentState(TypedDict):
+    messages: Annotated[list, add_messages]  # reducer: acumula
+    iteracoes: int                            # sobrescreve (default)
+    resultado: str | None
+
+def analisar(state: AgentState) -> dict:
+    """Node retorna APENAS os campos que atualiza — nunca o estado inteiro mutado."""
+    return {"iteracoes": state["iteracoes"] + 1}
+
+builder = StateGraph(AgentState)
+builder.add_node("analisar", analisar)
+builder.add_edge(START, "analisar")
+builder.add_edge("analisar", END)
+graph = builder.compile()
+```
+
+- Estado é **TypedDict ou Pydantic BaseModel** — nunca dict solto. Pydantic quando precisa validação em runtime.
+- Campos acumulativos (mensagens, logs) usam reducer via `Annotated[list, add_messages]` ou `operator.add`; sem reducer, cada node sobrescreve.
+
+## 2. Conditional edges
+
+```python
+def rotear(state: AgentState) -> str:
+    if state["iteracoes"] >= 5:
+        return "encerrar"            # condição de parada SEMPRE primeiro
+    if state.get("resultado"):
+        return "revisar"
+    return "analisar"
+
+builder.add_conditional_edges("analisar", rotear,
+    {"analisar": "analisar", "revisar": "revisar", "encerrar": END})
+```
+
+- A função de roteamento cobre **todos** os valores possíveis; o mapa lista todas as rotas. Valor fora do mapa = crash em produção.
+- Condição de parada checada **antes** das rotas de continuação — nunca depender só do `recursion_limit`.
+
+## 3. Checkpointer (memória/persistência)
+
+```python
+from langgraph.checkpoint.memory import MemorySaver          # dev/teste
+from langgraph.checkpoint.sqlite import SqliteSaver          # single-node
+from langgraph.checkpoint.postgres import PostgresSaver      # produção
+
+graph = builder.compile(checkpointer=PostgresSaver.from_conn_string(DB_URL))
+config = {"configurable": {"thread_id": "cliente-123"}}      # 1 thread = 1 conversa/execução
+graph.invoke({"messages": [...], "iteracoes": 0}, config)
+```
+
+- `thread_id` é a chave de retomada: mesma thread = continua do checkpoint; thread nova = do zero.
+- Checkpointer é pré-requisito de interrupt/HITL e de retomada após crash. `MemorySaver` nunca em produção.
+
+## 4. Interrupt / Human-in-the-loop
+
+```python
+from langgraph.types import interrupt, Command
+
+def aprovar_envio(state: AgentState) -> dict:
+    """Pausa antes de ação irreversível; humano aprova, edita ou rejeita."""
+    decisao = interrupt({"proposta": state["resultado"], "acao": "enviar e-mail ao cliente"})
+    if decisao["aprovado"]:
+        return {"resultado": decisao.get("texto_editado", state["resultado"])}
+    return {"resultado": None}
+
+# Retomada (ex.: handler de API depois da resposta humana):
+graph.invoke(Command(resume={"aprovado": True}), config)
+```
+
+- `interrupt()` exige checkpointer. O grafo congela; a retomada re-executa o node do início — código antes do `interrupt` deve ser idempotente.
+- Padrão de payload: mostrar ao humano exatamente o que será feito + dados para decidir; nunca "aprovar? s/n" sem contexto.
+
+## 5. Subgrafos
+
+```python
+sub = sub_builder.compile()
+builder.add_node("pesquisa", sub)   # subgrafo entra como node
+```
+
+- Usar quando um bloco tem estado próprio ou é reutilizado entre grafos. Estados diferentes: envolver com função que traduz estado pai ↔ filho.
+- Cada subgrafo testável isoladamente — mesmo racional de quebrar workflow monolítico.
+
+## 6. Streaming
+
+```python
+for chunk in graph.stream(inputs, config, stream_mode="updates"):
+    ...   # "updates": deltas por node | "values": estado completo | "messages": tokens de LLM
+```
+
+- `stream_mode="updates"` para observabilidade de execução (qual node rodou, o que mudou); `"messages"` para UI de chat token a token.
+
+## 7. Limites de recursão
+
+```python
+graph.invoke(inputs, {"recursion_limit": 25, "configurable": {"thread_id": "t1"}})
+```
+
+- `recursion_limit` (default 25) conta **supersteps**, não iterações lógicas. É o airbag — a condição de parada no estado (`iteracoes >= N`) é o freio. Ambos obrigatórios.
+- Estourar o limite levanta `GraphRecursionError`: capturar e degradar com graça (salvar estado parcial, notificar), não deixar subir cru.
+
+## 8. Erro e retry
+
+```python
+from langgraph.pregel import RetryPolicy
+builder.add_node("chamar_api", chamar_api,
+    retry=RetryPolicy(max_attempts=3, backoff_factor=2.0, retry_on=(TimeoutError,)))
+```
+
+- `RetryPolicy` por node para falha transitória (rede, 429). Erro de lógica não se retenta — se trata: node de fallback via conditional edge com rota de erro no estado (`state["erro"]`).
+- Ação irreversível + retry = duplicação. Nodes com efeito externo precisam de idempotência (chave externa) ou interrupt antes.
+
+## 9. Teste de grafos
+
+- **Nodes puros primeiro:** cada node é função `state -> dict` — teste unitário direto, sem grafo, com estado sintético (incluindo estados de erro).
+- **Roteamento:** testar a função de conditional edge para cada valor possível do estado — é onde bugs de produção moram.
+- **Grafo compilado:** `graph.invoke` com `MemorySaver` e LLM mockado (fake model ou `with_structured_output` stub); assert no estado final e na sequência de nodes via `stream(stream_mode="updates")`.
+- **Custo:** registrar tokens por caminho no teste de integração (callback de contagem); comparar com o custo estimado no `*design` — divergência grande = desenho desatualizado.

package/template/pods/automation/knowledge/n8n-patterns.md

@@ -0,0 +1,131 @@
+# N8N — Padrões de produção
+
+Referência de trabalho do pod `automation`. Padrões validados em automações reais de PME. Carregado sob demanda pelos comandos do `n8n-architect`.
+
+## 1. Estrutura do workflow JSON
+
+Um workflow exportado tem quatro chaves principais:
+
+```json
+{
+  "name": "Nome do Workflow",
+  "nodes": [
+    {
+      "parameters": { "...": "config específica do node" },
+      "id": "uuid-estável",
+      "name": "Nome único no workflow",
+      "type": "n8n-nodes-base.httpRequest",
+      "typeVersion": 4.2,
+      "position": [240, 0],
+      "onError": "continueRegularOutput"
+    }
+  ],
+  "connections": {
+    "Nome Do Node Origem": {
+      "main": [[ { "node": "Nome Do Node Destino", "type": "main", "index": 0 } ]]
+    }
+  },
+  "settings": { "executionOrder": "v1", "timezone": "UTC", "errorWorkflow": "<id>" }
+}
+```
+
+Regras práticas:
+- `settings.timezone` é **dado da instância, não default do framework**: `UTC` é o valor neutro
+  (válido em qualquer lugar, sem horário de verão), e é aqui só para o JSON ser importável.
+  **Ajuste para o fuso de quem opera** (`America/Sao_Paulo`, `Europe/Lisbon`, …) — um cron herdado
+  com o fuso de outra pessoa dispara na hora errada **e não falha de forma visível**.
+- `connections` referencia nodes pelo **name**, não pelo id — renomear node exige atualizar conexões.
+- `main` é array de arrays: o array externo é o índice de **saída** (IF tem saída 0=true, 1=false); `index` no destino é a **entrada** (Merge com 3 entradas usa 0, 1, 2).
+- `typeVersion` importa: parâmetros mudam entre versões (IF v1 vs v2.2, Google Sheets v4+). Exportar de instância atual, não de memória.
+
+## 2. Error handling
+
+**Error workflow (padrão preferido):** workflow separado começando com node `Error Trigger` (`n8n-nodes-base.errorTrigger`); registrar em `settings.errorWorkflow` de cada workflow de produção. O payload recebido:
+
+```json
+{
+  "workflow": { "id": "...", "name": "Workflow que falhou" },
+  "execution": {
+    "id": "...", "url": "https://n8n.../executions/...",
+    "error": { "message": "...", "stack": "..." },
+    "lastNodeExecuted": "Nome Do Node"
+  }
+}
+```
+
+Um único error workflow atende todos os workflows de produção: formata o payload acima e notifica o canal de operação (e-mail/WhatsApp) com nome do workflow, node que falhou e link da execução.
+
+**Tratamento inline (complementar):** `onError: "continueRegularOutput"` no node que pode falhar → item de erro segue com campo `error` → node IF separa branch de erro (condição: `$json.error` existe) → branch falso alerta/loga. Usar quando a falha parcial não deve derrubar a execução (ex.: 1 de 3 feeds fora do ar).
+
+```text
+[HTTP Request (onError: continue)] → [IF $json.error notExists?]
+        true  → segue o fluxo normal
+        false → [Alerta operador] (+ opcional: grava em log de falhas)
+```
+
+Nunca: engolir erro sem branch de tratamento (`continueRegularOutput` sem IF a jusante é falha silenciosa).
+
+## 3. Retry com backoff
+
+- Node-level: em nodes HTTP Request e afins, `retryOnFail: true`, `maxTries` (2–5), `waitBetweenTries` (ms). Cobre falha transitória de rede.
+
+```json
+{ "retryOnFail": true, "maxTries": 3, "waitBetweenTries": 5000 }
+```
+
+- Backoff real (429/rate limit): loop explícito com `Wait` node e contador no item:
+
+```text
+[Set tentativa=1] → [HTTP Request (onError: continue)] → [IF sucesso?]
+   true  → segue
+   false → [IF tentativa < 4?]
+              true  → [Wait {{ $json.tentativa * 30 }}s] → [Set tentativa+1] → volta ao Request
+              false → [Alerta: desistiu após 4 tentativas]
+```
+
+  Teto de tentativas é obrigatório — sem ele o loop de retry é loop infinito.
+- Timeout sempre configurado em chamadas externas (`options.timeout`, ex.: 30000 ms); default infinito é anti-pattern.
+- Retry só para falha transitória (timeout, 429, 5xx). Erro 4xx de payload não se retenta — se corrige.
+
+## 4. Dedupe / idempotência com chave externa
+
+- Node `Remove Duplicates` (`n8n-nodes-base.removeDuplicates`), operação `removeItemsSeenInPreviousExecutions`: dedupe **entre execuções** por chave (`dedupeValue`, ex.: `={{ $json.link }}` ou id externo). É o padrão para "processar cada item uma vez na vida".
+- Alternativa com auditoria: consultar storage (Sheets/Postgres/Redis) pela chave antes de agir; gravar chave após efeito confirmado.
+- Efeitos externos (criar cobrança, enviar mensagem): usar chave de idempotência da API destino quando existir (ex.: `Idempotency-Key` no Stripe). Reexecução manual do workflow NÃO pode duplicar efeito — teste isso antes de entregar.
+
+## 5. Webhook seguro
+
+- Autenticação sempre: Header Auth (token em credential store) no mínimo; HMAC (validar assinatura no primeiro node) para provedores que suportam (Meta, Stripe). Validação HMAC num Code node logo após o Webhook:
+
+```javascript
+const crypto = require('crypto');
+const assinaturaRecebida = $json.headers['x-hub-signature-256'] || '';
+const esperada = 'sha256=' + crypto
+  .createHmac('sha256', $env.WEBHOOK_APP_SECRET)   // segredo via env/credential, nunca inline
+  .update(JSON.stringify($json.body))
+  .digest('hex');
+if (!crypto.timingSafeEqual(Buffer.from(assinaturaRecebida), Buffer.from(esperada))) {
+  throw new Error('Assinatura HMAC inválida — payload rejeitado');
+}
+return $input.all();
+```
+
+- Validar payload antes de agir: IF checando campos obrigatórios; payload inválido → resposta 400 + log, nunca segue o fluxo.
+- `Respond to Webhook` cedo (202) e processar depois, quando o provedor tem timeout curto (WhatsApp: 10s).
+- Path do webhook não é segredo — tratar como público mesmo com UUID.
+
+## 6. Integrações comuns (PMEs)
+
+- **WhatsApp (API oficial / Cloud API):** webhook de entrada com verificação de token GET + HMAC; envio via HTTP Request para `graph.facebook.com/v*/{phone-id}/messages` com credential Header Auth. Janela de 24h: fora dela, só template aprovado.
+- **Google Sheets** (`n8n-nodes-base.googleSheets` v4+): operação `append` para log/registro, `appendOrUpdate` com coluna-chave para upsert idempotente. Sheets é UI de operação barata para PME — não é banco; acima de ~10k linhas, migrar.
+- **HTTP Request** (`n8n-nodes-base.httpRequest` v4+): o canivete para API sem node nativo. Sempre: credential store (Header/OAuth2), `timeout`, `retryOnFail`, paginação explícita quando a API pagina.
+- **Agendamento** (`n8n-nodes-base.scheduleTrigger`): cron expression explícita (`0 7 * * *`) + `settings.timezone` declarado — sem timezone, o cron roda no fuso do servidor e "7h" vira surpresa.
+
+## 7. Anti-patterns (veto em review)
+
+- **Polling agressivo:** trigger a cada minuto contra API sem necessidade — usar webhook quando existir; senão, o maior intervalo que o negócio tolera.
+- **Credencial em texto:** token/senha em parâmetro, expressão, Code node ou committed no JSON exportado. Só credential store.
+- **Workflow monolítico:** 40+ nodes, múltiplos jobs num workflow só — quebrar por responsabilidade e ligar via `Execute Workflow`; cada sub-workflow testável isoladamente.
+- **Falha silenciosa:** `onError: continueRegularOutput` sem branch de erro a jusante; execução "verde" com metade dos itens perdidos.
+- **Code node como muleta universal:** reimplementar em JS o que node nativo faz (dedupe, merge, filtro) — mais superfície de bug, menos legibilidade para quem opera.
+- **Sem dono nem runbook:** workflow em produção que só o criador entende. Entrega inclui `*docs`.

package/template/pods/automation/memory/README.md

@@ -0,0 +1,16 @@
+# Memória do pod `automation` — OPERANTE (SF2.3)
+
+> Instalada por forge-generate.cjs via o motor `scripts/pod-memory.cjs` (SF2.1).
+> Tier: STANDARD/COMPLEX. Esta memória NÃO é scaffold morto: nasce cabeada ao lifecycle.
+
+## Cabeamento (nenhuma ação manual necessária)
+
+- `learnings.jsonl` — log cru append-only. O runner (`pc-run-pod`, SF2.2) faz `append()`
+  ao fim de cada etapa/run. O AGENTE NUNCA lê este arquivo (auditoria apenas).
+- `learnings.consolidated.md` — top-N curado (`consolidate()`), no path canônico que
+  `getConsolidatedForBrief()` entrega ao brief da run. É o ÚNICO que o agente lê.
+- Auditoria de aderência por run: `config/heuristic-watcher-rubric.yaml` +
+  `scripts/watcher-audit.cjs` (executado pelo `pod-critic`).
+
+Assim que este pod rodar via `pc-run-pod`, injeção do consolidado no brief e append de
+learnings funcionam sem qualquer passo manual — a operância é o cabeamento ao motor pronto.

package/template/pods/automation/memory/learnings.consolidated.md

@@ -0,0 +1,8 @@
+# Memória consolidada — automation
+
+> Curado por pod-memory.cjs (SF2.1). Único artefato de memória lido pelo agente.
+> Log cru (learnings.jsonl) NÃO é lido pelo agente — auditoria apenas.
+
+## Heurísticas (top-N)
+
+_Nenhuma heurística consolidada ainda._

package/template/pods/automation/pod-spec.json

@@ -0,0 +1,109 @@
+{
+  "pod": "automation",
+  "workflowId": "n8n-build",
+  "_adr": "ADR-005 Decisão B: a ordem do DAG é DADO DECLARADO (agents[] ordenado = ordem topológica das 5 fases do 'Fluxo típico'), nunca readdir/alfabético. ADR-002: os 3 itens da 'Regra do pod (inegociável)' que exigem julgamento (error handling explícito, idempotência onde aplicável, qualidade do runbook) viram checkpoint.blocking; a fatia machine-redutível de 'documentação de operação' (o entregável existe em disco) vira veto file_referenced_exists. ADR-004: critical:true — automação em produção (README §'Regra do pod'). Retrofit SF6.3: formaliza o 'Fluxo típico' (README:14-20) do pod em wf-*.yaml seguível por pc-run-pod.",
+  "_sources": {
+    "fluxo_tipico": "README.md:14-20 'Fluxo típico' — 5 fases numeradas: 1. Descoberta (*discover n8n / entrevista equivalente), 2. Desenho (*design; 'Aprovação do desenho ANTES de gerar código' :17), 3. Geração (*build; 'JSON importável (N8N) ou código Python tipado (Langgraph)' :18), 4. Teste (execução + red-team via *review :19), 5. Handoff de deploy (runbook *docs :20). DAG linear descoberta→desenho→geração→teste→handoff.",
+    "regra_do_pod": "README.md:22-28 'Regra do pod (inegociável)': error handling explícito (:26), idempotência onde aplicável (:27), documentação de operação/runbook (:28). Condições de JULGAMENTO ('error handling está de fato explícito?', 'onde aplicável') → checkpoint.blocking nas etapas de Teste (error handling+idempotência) e Handoff (qualidade do runbook), fronteira ADR-002. A fatia objetiva ('o entregável de automação existe em disco') → veto file_referenced_exists em n8n-handoff.",
+    "criterio_de_track": "README.md:9-12 — critério de escolha N8N vs Langgraph é decisão da Fase 1 (Descoberta): 'mover e transformar dados entre sistemas' → N8N; 'um agente decide, com estado e supervisão humana' → Langgraph. Decidido POR PROCESSO, antes do Desenho.",
+    "decisao_2_workflows": "AC1 — DECISÃO POR EVIDÊNCIA: DOIS wf-*.yaml (wf-n8n-build.yaml + wf-langgraph-build.yaml, este em specs/wf-langgraph-build.spec.json), NÃO um único parametrizado. Racional decisivo (mecanismo): validate-pod-workflow.cjs:291 e pc-run-pod.cjs exigem `agent` LITERAL FIXO por etapa — não há parametrização de agente. Um único wf forçaria UM agente (n8n-architect OU langgraph-architect) sobre AMBOS os tracks, o que é falso: os dois agentes têm golden rules distintas (n8n-architect: error workflow/credential store/webhook autenticado, agents/n8n-architect.md:27-30; langgraph-architect: recursion_limit+condição de parada/estado tipado/interrupt antes de ação irreversível, agents/langgraph-architect.md:26-30) e ENTREGÁVEIS distintos (JSON importável vs código Python tipado, README:18). 'Agente-executor como parâmetro decidido na Fase 1' NÃO é construível sem inventar orquestração (No Invention / Escopo OUT 'sem duplicar orquestração'). NÃO é '90% duplicado': todo step diverge no agent, no template (guidance n8n nodes/connections vs langgraph state/edges) e o build diverge no tipo de entregável. A FORMA compartilhada (5 fases lineares) é a metodologia do pod, não duplicação de orquestração — pc-run-pod roda um wf por run, sem orquestração compartilhada entre eles.",
+    "json_schema_valid_linha_do_tempo": "LINHA DO TEMPO da decisão (preservada por inteiro — Risco 3 da SF7.8). [2026-07-25, REJEITADO no retrofit SF6.3] AC3/fronteira ADR-002 explicitada no brief ('validação de JSON importável pode ser json_schema_valid?'): AVALIADO para n8n-build e REJEITADO por evidência de mecanismo — à época, evalVeto json_schema_valid fazia JSON.parse do ARTEFATO INTEIRO (exigia artefato JSON puro), o que colidia com checkTemplateConformance (todo artefato de etapa deve conter as seções ##+ do template) e com stepTemplate (todo template gerado carrega headings ## + o campo-âncora `confianca`). A validação estrutural ficou como CHECKPOINT de red-team (n8n-test) — resposta honesta, não veto fabricado — e o débito registrado como CONCERNS-1 do gate SF6.3. [2026-07-29, ADOTADO na SF7.8] ADR-011 Decisão 1 (SF7.2) resolveu a colisão NO NÍVEL DA FORMA: `json_schema_valid` ganhou `extract:{section,fence}` — valida o bloco ```json da seção declarada, não o artefato inteiro; headings/`confianca` do template ficam intactos. A etapa n8n-build agora carrega o veto de importabilidade por máquina (nodes/connections, n8n-patterns.md:7) ALÉM do checkpoint de red-team, fechando o CONCERNS-1 de ponta a ponta (capacidade SF7.2 + adoção SF7.8).",
+    "agentes": "agents/n8n-architect.md (30 linhas, comandos *discover/*design/*build/*review/*docs — cobre as 5 fases) + agents/langgraph-architect.md (30 linhas, *design/*build/*hitl/*review/*memory)."
+  },
+  "handoffs": 4,
+  "critical": true,
+  "agents": [
+    {
+      "name": "n8n-architect",
+      "step": "n8n-discover",
+      "output": "process-map-n8n",
+      "sections": [
+        "## Trigger",
+        "## Passos e Sistemas",
+        "## Volumes e Modos de Falha",
+        "## Quem Opera"
+      ],
+      "veto": [
+        { "type": "field_matches", "field": "confianca", "pattern": "^(alta|media|baixa)$", "_sources": "âncora de conformidade do pod (ADR-005 Decisão A) — campo de máquina ortogonal fora dos headings; derivável pelo sweep (valor presente fora do pattern)" }
+      ],
+      "_sources": "README.md:16 Fase 1 Descoberta + agents/n8n-architect.md:18 *discover ('trigger, passos e decisões, sistemas envolvidos e suas APIs, volumes, modos de falha conhecidos, quem opera hoje')."
+    },
+    {
+      "name": "n8n-architect",
+      "step": "n8n-design",
+      "output": "design-n8n",
+      "sections": [
+        "## Nodes",
+        "## Conexoes e Branch de Erro",
+        "## Retry e Timeout",
+        "## Pontos de Dedupe",
+        "## Tabela de Riscos"
+      ],
+      "veto": [
+        { "type": "field_matches", "field": "confianca", "pattern": "^(alta|media|baixa)$", "_sources": "âncora de conformidade do pod (ADR-005 Decisão A)" }
+      ],
+      "checkpoint": {
+        "blocking": true,
+        "criteria": "Desenho aprovado ANTES de gerar código (README:17): lista de nodes validados contra o catálogo, branch/workflow de erro, política de retry+timeout por node externo, pontos de dedupe, tabela de riscos — APROVAÇÃO HUMANA por escrito, JULGAMENTO (fronteira ADR-002), NUNCA veto de máquina.",
+        "_sources": "README.md:17 'Aprovação do desenho ANTES de gerar código' + agents/n8n-architect.md:19 *design (nodes, conexões, branch de erro, retry/timeout, dedupe, tabela de riscos, para aprovação)."
+      },
+      "_sources": "README.md:17 Fase 2 Desenho + agents/n8n-architect.md:19 *design."
+    },
+    {
+      "name": "n8n-architect",
+      "step": "n8n-build",
+      "output": "workflow-json",
+      "sections": [
+        "## Workflow JSON Importavel",
+        "## Validacao de Parseabilidade"
+      ],
+      "veto": [
+        { "type": "field_matches", "field": "confianca", "pattern": "^(alta|media|baixa)$", "_sources": "âncora de conformidade do pod (ADR-005 Decisão A) — mantida junto do veto de domínio, mesmo padrão das demais etapas." },
+        { "type": "json_schema_valid", "schema": { "required": ["connections", "nodes"] }, "extract": { "section": "## Workflow JSON Importavel", "fence": "json" }, "_sources": "SF7.8/ADR-011 Decisão 1: prova de importabilidade por máquina — bloco ```json da seção real do template (n8n-build-tmpl.md:7), shape mínimo N8N (nodes/connections, n8n-patterns.md:7). required ordena connections primeiro (o sweep remove required[0] — o defeito exato do CONCERNS-1). Ver _sources.json_schema_valid_linha_do_tempo." }
+      ],
+      "_sources": "README.md:18 Fase 3 Geração ('JSON importável (N8N)') + agents/n8n-architect.md:20 *build ('nodes + connections + settings, valida parseabilidade antes de entregar') + knowledge/n8n-patterns.md:7-30 (estrutura do workflow JSON)."
+    },
+    {
+      "name": "n8n-architect",
+      "step": "n8n-test",
+      "output": "review-n8n",
+      "sections": [
+        "## Achados por Severidade",
+        "## Error Handling",
+        "## Idempotencia",
+        "## Custo por Execucao"
+      ],
+      "veto": [
+        { "type": "field_matches", "field": "confianca", "pattern": "^(alta|media|baixa)$", "_sources": "âncora de conformidade do pod (ADR-005 Decisão A)" }
+      ],
+      "checkpoint": {
+        "blocking": true,
+        "criteria": "Regra do pod (inegociável), itens 1-2 (README:26-27): error handling EXPLÍCITO (error workflow ou onError + branch de tratamento — falha silenciosa é bug de entrega) E idempotência ONDE APLICÁVEL (dedupe por chave externa, reexecução não duplica efeito) confirmados no red-team (*review), sem achado crítico aberto. JULGAMENTO humano ('está de fato explícito?', 'onde aplicável'), fronteira ADR-002, NUNCA veto de máquina.",
+        "_sources": "README.md:19 Fase 4 Teste (red-team via *review) + :26-27 Regra do pod (error handling, idempotência) + agents/n8n-architect.md:21 *review (SPOF, credenciais, loops, custo, ausência de error handling/dedupe) + knowledge/n8n-patterns.md:37-90 (error handling, retry, dedupe)."
+      },
+      "_sources": "README.md:19 Fase 4 Teste + :26-27 Regra do pod itens 1-2 + agents/n8n-architect.md:21 *review."
+    },
+    {
+      "name": "n8n-architect",
+      "step": "n8n-handoff",
+      "output": "runbook-n8n",
+      "sections": [
+        "## O Que Faz",
+        "## Como Saber Que Quebrou",
+        "## Como Reexecutar com Seguranca",
+        "## Credenciais e Dono"
+      ],
+      "veto": [
+        { "type": "file_referenced_exists", "field": "entregavel", "_sources": "Regra do pod item 3 (README:28 'documentação de operação'), FATIA machine-checkável: o runbook referencia o entregável de automação (campo `entregavel`) e file_referenced_exists prova que ele EXISTE em disco (o artefato de n8n-build). Ortogonal (campo fora dos headings), derivável pelo sweep (path inexistente → bloqueia). Espelha squad-forge/pod-spec.json step register (file_referenced_exists entry_point)." },
+        { "type": "field_matches", "field": "confianca", "pattern": "^(alta|media|baixa)$", "_sources": "âncora de conformidade do pod" }
+      ],
+      "checkpoint": {
+        "blocking": true,
+        "criteria": "Regra do pod (inegociável), item 3 (README:28): runbook OPERÁVEL — o que a automação faz, como saber que quebrou (onde olhar), como reexecutar com segurança, credenciais necessárias, quem é o dono. COMPLETUDE/qualidade QUALITATIVA (julgamento humano), fronteira ADR-002, NUNCA veto — a fatia objetiva ('o entregável existe') é o veto file_referenced_exists acima.",
+        "_sources": "README.md:20 Fase 5 Handoff de deploy (runbook *docs) + :28 Regra do pod item 3 + agents/n8n-architect.md:22 *docs (o que faz, como saber que quebrou, como reexecutar, credenciais, dono)."
+      },
+      "_sources": "README.md:20 Fase 5 Handoff + :28 Regra do pod item 3 + agents/n8n-architect.md:22 *docs."
+    }
+  ],
+  "smoke_scenario": "workflows/wf-n8n-build.smoke.json"
+}

package/template/pods/automation/specs/wf-langgraph-build.spec.json

@@ -0,0 +1,107 @@
+{
+  "pod": "automation",
+  "workflowId": "langgraph-build",
+  "_adr": "ADR-005 Decisão B: agents[] ordenado = ordem topológica das 5 fases (Descoberta→Desenho→Geração→Teste→Handoff). Segundo workflow do pod `automation` (track Langgraph), irmão de wf-n8n-build.yaml — ver pod-spec._sources.decisao_2_workflows para o racional de 2 wf-*.yaml. Gerado por forge-generate.cjs --additive (MERGE em squad-io.yaml, padrão multi-workflow do hormozi-method/specs/). Namespace pod-wide (M3): step-ids lg-* e outputs *-lg/graph-code NÃO colidem com os n8n-* de wf-n8n-build.",
+  "_sources": {
+    "fluxo_tipico": "README.md:14-20 'Fluxo típico' — MESMAS 5 fases do track N8N; divergem só no agente-executor (langgraph-architect) e no entregável da Geração (código Python tipado, README:18).",
+    "track_langgraph": "README.md:10-12 — 'um agente decide, com estado e supervisão humana' → Langgraph; agents/langgraph-architect.md (grafos Langgraph em Python, agentes com estado em produção).",
+    "descoberta_langgraph": "README.md:16 'Descoberta do processo — *discover (n8n) OU entrevista equivalente'. langgraph-architect não tem comando *discover próprio; a descoberta do track Langgraph é a 'entrevista equivalente', conduzida pelo próprio langgraph-architect (executor do track, cujo *design pressupõe o processo entendido — agents/langgraph-architect.md:18). Nenhum agente de descoberta separado é inventado (No Invention).",
+    "regra_do_pod": "README.md:22-28 — mesma Regra inegociável, sabor Langgraph: error handling = estados de erro e retry (RetryPolicy/rota de erro no estado, langgraph-patterns.md:112-119); idempotência = ação irreversível exige interrupt ou chave de idempotência (langgraph-patterns.md:119); documentação de operação = runbook + config de checkpointer/persistência (*memory, agents/langgraph-architect.md:22). Julgamento → checkpoint (lg-test, lg-handoff); fatia objetiva (entregável existe) → veto file_referenced_exists (lg-handoff)."
+  },
+  "handoffs": 4,
+  "critical": true,
+  "agents": [
+    {
+      "name": "langgraph-architect",
+      "step": "lg-discover",
+      "output": "process-map-lg",
+      "sections": [
+        "## Processo e Decisao",
+        "## Estado Necessario",
+        "## Pontos de Supervisao Humana",
+        "## Quem Opera"
+      ],
+      "veto": [
+        { "type": "field_matches", "field": "confianca", "pattern": "^(alta|media|baixa)$", "_sources": "âncora de conformidade do pod (ADR-005 Decisão A) — campo de máquina ortogonal fora dos headings" }
+      ],
+      "_sources": "README.md:16 Fase 1 Descoberta ('entrevista equivalente' para o track Langgraph) — processo, decisão de LLM, estado necessário, pontos de supervisão humana, quem opera. Ver _sources.descoberta_langgraph."
+    },
+    {
+      "name": "langgraph-architect",
+      "step": "lg-design",
+      "output": "design-lg",
+      "sections": [
+        "## Schema de Estado",
+        "## Nodes e Responsabilidade",
+        "## Edges Condicionais",
+        "## Condicao de Parada e Limite",
+        "## Checkpoints"
+      ],
+      "veto": [
+        { "type": "field_matches", "field": "confianca", "pattern": "^(alta|media|baixa)$", "_sources": "âncora de conformidade do pod (ADR-005 Decisão A)" }
+      ],
+      "checkpoint": {
+        "blocking": true,
+        "criteria": "Desenho aprovado ANTES de gerar código (README:17): schema de estado (campos, tipos, reducers), nodes com responsabilidade única, edges condicionais com TODAS as rotas mapeadas (rota default de erro incluída), condição de parada explícita E limite de iterações, checkpoints — APROVAÇÃO HUMANA por escrito, JULGAMENTO (ADR-002), NUNCA veto.",
+        "_sources": "README.md:17 'Aprovação do desenho ANTES de gerar código' + agents/langgraph-architect.md:18 *design + :30 (toda edge condicional cobre todos os valores) + knowledge/langgraph-patterns.md:32-46 (conditional edges, condição de parada primeiro)."
+      },
+      "_sources": "README.md:17 Fase 2 Desenho + agents/langgraph-architect.md:18 *design."
+    },
+    {
+      "name": "langgraph-architect",
+      "step": "lg-build",
+      "output": "graph-code",
+      "sections": [
+        "## Codigo do Grafo",
+        "## Estado Tipado",
+        "## Recursion Limit"
+      ],
+      "veto": [
+        { "type": "field_matches", "field": "confianca", "pattern": "^(alta|media|baixa)$", "_sources": "âncora de conformidade do pod. Entregável = código Python tipado (README:18), NÃO JSON — json_schema_valid é inaplicável a este track (ver pod-spec._sources.json_schema_valid_avaliado_e_rejeitado); a validação (recursion_limit + estado tipado) fica no red-team lg-test." }
+      ],
+      "_sources": "README.md:18 Fase 3 Geração ('código Python tipado (Langgraph)') + agents/langgraph-architect.md:19 *build (StateGraph com TypedDict/Pydantic, type hints, docstrings, recursion_limit configurado) + knowledge/langgraph-patterns.md:5-25,102-108."
+    },
+    {
+      "name": "langgraph-architect",
+      "step": "lg-test",
+      "output": "review-lg",
+      "sections": [
+        "## Achados por Severidade",
+        "## Rotas Nao Tratadas",
+        "## Custo de Tokens por Caminho",
+        "## Acoes Irreversiveis"
+      ],
+      "veto": [
+        { "type": "field_matches", "field": "confianca", "pattern": "^(alta|media|baixa)$", "_sources": "âncora de conformidade do pod (ADR-005 Decisão A)" }
+      ],
+      "checkpoint": {
+        "blocking": true,
+        "criteria": "Regra do pod (inegociável), itens 1-2 sabor Langgraph (README:26-27): error handling EXPLÍCITO (estados de erro e retry — RetryPolicy/rota de erro no estado, checkpointer presente) E idempotência ONDE APLICÁVEL (ação irreversível protegida por interrupt ou chave de idempotência; código antes do interrupt idempotente) confirmados no red-team (*review), sem ciclo sem saída nem rota não tratada. JULGAMENTO humano, fronteira ADR-002, NUNCA veto.",
+        "_sources": "README.md:19 Fase 4 Teste + :26-27 Regra do pod + agents/langgraph-architect.md:21 *review (ciclos sem saída, rotas não tratadas, custo de tokens, ações irreversíveis sem interrupt, checkpointer ausente) + :26-28 golden rules + knowledge/langgraph-patterns.md:79,119."
+      },
+      "_sources": "README.md:19 Fase 4 Teste + :26-27 Regra do pod itens 1-2 + agents/langgraph-architect.md:21 *review."
+    },
+    {
+      "name": "langgraph-architect",
+      "step": "lg-handoff",
+      "output": "runbook-lg",
+      "sections": [
+        "## O Que Faz",
+        "## Como Saber Que Quebrou",
+        "## Como Reexecutar com Seguranca",
+        "## Checkpointer e Dono"
+      ],
+      "veto": [
+        { "type": "file_referenced_exists", "field": "entregavel", "_sources": "Regra do pod item 3 (README:28), FATIA machine-checkável: o runbook referencia o entregável (campo `entregavel` = artefato de lg-build) e file_referenced_exists prova que existe em disco. Ortogonal, derivável pelo sweep (path inexistente → bloqueia)." },
+        { "type": "field_matches", "field": "confianca", "pattern": "^(alta|media|baixa)$", "_sources": "âncora de conformidade do pod" }
+      ],
+      "checkpoint": {
+        "blocking": true,
+        "criteria": "Regra do pod (inegociável), item 3 (README:28): runbook OPERÁVEL — o que faz, como saber que quebrou, como reexecutar com segurança, config de checkpointer/persistência (retomada após falha) e quem é o dono. COMPLETUDE QUALITATIVA (julgamento), fronteira ADR-002, NUNCA veto — a fatia objetiva ('entregável existe') é o veto file_referenced_exists acima.",
+        "_sources": "README.md:20 Fase 5 Handoff + :28 Regra do pod item 3 + agents/langgraph-architect.md:22 *memory (checkpointing/persistência, retomada após falha)."
+      },
+      "_sources": "README.md:20 Fase 5 Handoff + :28 Regra do pod item 3 + agents/langgraph-architect.md:22 *memory."
+    }
+  ],
+  "smoke_scenario": "workflows/wf-langgraph-build.smoke.json"
+}

package/template/pods/automation/squad-io.yaml

@@ -0,0 +1,28 @@
+# squad-io.yaml — contrato de handoff do pod `automation` (SF1.4).
+# Cada handoff liga o output de uma etapa ao input da etapa a jusante.
+pod: automation
+handoffs:
+  - from: n8n-discover
+    to: n8n-design
+    artifact: process-map-n8n
+  - from: n8n-design
+    to: n8n-build
+    artifact: design-n8n
+  - from: n8n-build
+    to: n8n-test
+    artifact: workflow-json
+  - from: n8n-test
+    to: n8n-handoff
+    artifact: review-n8n
+  - from: lg-discover
+    to: lg-design
+    artifact: process-map-lg
+  - from: lg-design
+    to: lg-build
+    artifact: design-lg
+  - from: lg-build
+    to: lg-test
+    artifact: graph-code
+  - from: lg-test
+    to: lg-handoff
+    artifact: review-lg

package/template/pods/automation/templates/lg-build-tmpl.md

@@ -0,0 +1,17 @@
+# Template de saída — etapa `lg-build` (agente `langgraph-architect`, artefato `graph-code`)
+
+> Gerado por forge-generate.cjs (SF1.4 + ADR-005). Preencher com o artefato real da etapa.
+> FORMA (seções `##`) verificada por checkTemplateConformance; VETO ORTOGONAL via o
+> campo de máquina `confianca` abaixo (fora dos headings — ADR-005 Decisão A).
+
+## Codigo do Grafo
+<!-- preencher: conteúdo de "Codigo do Grafo" -->
+
+## Estado Tipado
+<!-- preencher: conteúdo de "Estado Tipado" -->
+
+## Recursion Limit
+<!-- preencher: conteúdo de "Recursion Limit" -->
+
+<!-- Campo de máquina do veto default (ADR-005) — NÃO é heading. Troque o placeholder por alta|media|baixa. -->
+confianca: <alta|media|baixa>

package/template/pods/automation/templates/lg-design-tmpl.md

@@ -0,0 +1,23 @@
+# Template de saída — etapa `lg-design` (agente `langgraph-architect`, artefato `design-lg`)
+
+> Gerado por forge-generate.cjs (SF1.4 + ADR-005). Preencher com o artefato real da etapa.
+> FORMA (seções `##`) verificada por checkTemplateConformance; VETO ORTOGONAL via o
+> campo de máquina `confianca` abaixo (fora dos headings — ADR-005 Decisão A).
+
+## Schema de Estado
+<!-- preencher: conteúdo de "Schema de Estado" -->
+
+## Nodes e Responsabilidade
+<!-- preencher: conteúdo de "Nodes e Responsabilidade" -->
+
+## Edges Condicionais
+<!-- preencher: conteúdo de "Edges Condicionais" -->
+
+## Condicao de Parada e Limite
+<!-- preencher: conteúdo de "Condicao de Parada e Limite" -->
+
+## Checkpoints
+<!-- preencher: conteúdo de "Checkpoints" -->
+
+<!-- Campo de máquina do veto default (ADR-005) — NÃO é heading. Troque o placeholder por alta|media|baixa. -->
+confianca: <alta|media|baixa>

package/template/pods/automation/templates/lg-discover-tmpl.md

@@ -0,0 +1,20 @@
+# Template de saída — etapa `lg-discover` (agente `langgraph-architect`, artefato `process-map-lg`)
+
+> Gerado por forge-generate.cjs (SF1.4 + ADR-005). Preencher com o artefato real da etapa.
+> FORMA (seções `##`) verificada por checkTemplateConformance; VETO ORTOGONAL via o
+> campo de máquina `confianca` abaixo (fora dos headings — ADR-005 Decisão A).
+
+## Processo e Decisao
+<!-- preencher: conteúdo de "Processo e Decisao" -->
+
+## Estado Necessario
+<!-- preencher: conteúdo de "Estado Necessario" -->
+
+## Pontos de Supervisao Humana
+<!-- preencher: conteúdo de "Pontos de Supervisao Humana" -->
+
+## Quem Opera
+<!-- preencher: conteúdo de "Quem Opera" -->
+
+<!-- Campo de máquina do veto default (ADR-005) — NÃO é heading. Troque o placeholder por alta|media|baixa. -->
+confianca: <alta|media|baixa>

package/template/pods/automation/templates/lg-handoff-tmpl.md

@@ -0,0 +1,20 @@
+# Template de saída — etapa `lg-handoff` (agente `langgraph-architect`, artefato `runbook-lg`)
+
+> Gerado por forge-generate.cjs (SF1.4 + ADR-005). Preencher com o artefato real da etapa.
+> FORMA (seções `##`) verificada por checkTemplateConformance; VETO ORTOGONAL via o
+> campo de máquina `confianca` abaixo (fora dos headings — ADR-005 Decisão A).
+
+## O Que Faz
+<!-- preencher: conteúdo de "O Que Faz" -->
+
+## Como Saber Que Quebrou
+<!-- preencher: conteúdo de "Como Saber Que Quebrou" -->
+
+## Como Reexecutar com Seguranca
+<!-- preencher: conteúdo de "Como Reexecutar com Seguranca" -->
+
+## Checkpointer e Dono
+<!-- preencher: conteúdo de "Checkpointer e Dono" -->
+
+<!-- Campo de máquina do veto default (ADR-005) — NÃO é heading. Troque o placeholder por alta|media|baixa. -->
+confianca: <alta|media|baixa>