synapos 2.5.0

package/.synapos/core/copilot-adapter.md

@@ -0,0 +1,283 @@
+---
+name: synapos-copilot-adapter
+version: 1.0.0
+description: Mapeamento de capacidades Synapos → GitHub Copilot — como executar os protocolos existentes no contexto IDE-native
+---
+
+# SYNAPOS COPILOT ADAPTER v1.0.0
+
+> Este arquivo define como cada mecanismo do Synapos é executado no GitHub Copilot.
+> O Copilot não tem controle de fluxo real, memória persistente estruturada nem execução de pipeline automática.
+> Este adapter resolve isso usando markdown como engine, comentários como comandos e arquivos como estado.
+
+---
+
+## PRINCÍPIO GERAL
+
+O Copilot lê:
+- `.github/copilot-instructions.md` — automaticamente em todo chat
+- Arquivos abertos no editor — contexto implícito
+- Arquivos referenciados com `@` no chat — contexto explícito
+
+Use isso a favor: os arquivos de session, memória e squad.yaml são a "memória" do Copilot.
+
+---
+
+## MAPEAMENTO DE CAPACIDADES
+
+### `AskUserQuestion` → Lista Numerada
+
+**Synapos padrão:**
+```
+AskUserQuestion({
+  question: "Qual modo de operação?",
+  options: [
+    { label: "⚡ Alta Performance" },
+    { label: "💰 Econômico" },
+    { label: "🧑‍💻 Solo" }
+  ]
+})
+```
+
+**Copilot Mode:**
+```
+Qual modo de operação?
+
+1) ⚡ Alta Performance — Squad completo, docs máxima
+2) 💰 Econômico — Execução rápida, menos checkpoints
+3) 🧑‍💻 Solo — Sem checkpoints, execução direta
+
+(Digite o número da opção)
+```
+
+**Regra:** Sempre aguarde uma resposta clara antes de prosseguir. Se a resposta for ambígua, peça confirmação.
+
+---
+
+### `execution: subagent` → Execução Inline
+
+**Synapos padrão:** Lança um subagente separado com persona + contexto + instruções do step.
+
+**Copilot Mode:**
+1. Declare explicitamente qual agent está "falando": `[Agent: {displayName} — {role}]`
+2. Leia o `.agent.md` correspondente para carregar a persona
+3. Injete o contexto disponível (company.md + session files + memories.md)
+4. Execute as instruções do step inline na conversa
+5. Apresente o output com o cabeçalho do agent
+
+**Exemplo de output:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎨 [Agent: Designer React — Especialista em componentes UI]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[output do agent aqui]
+```
+
+---
+
+### `execution: checkpoint` → Checklist com Confirmação
+
+**Synapos padrão:** Pausa interativa com botões clicáveis.
+
+**Copilot Mode:**
+```
+⏸ CHECKPOINT: {nome do step}
+
+{contexto ou pergunta}
+
+Checklist antes de continuar:
+  [ ] {critério 1}
+  [ ] {critério 2}
+  [ ] {critério 3}
+
+Digite "ok" para continuar, "ajustar" para modificar o contexto ou "pular" para avançar.
+```
+
+> **Modo Solo:** Checkpoints sem `gate:` são pulados automaticamente.
+> Log: `⚡ [SOLO] {nome do step} — checkpoint ignorado`
+
+---
+
+### Gates → Checklist de Validação no Output
+
+Em vez de gates que bloqueiam automaticamente o fluxo, o Copilot apresenta o gate como checklist ao final do output relevante.
+
+**Formato padrão:**
+```
+---
+## Verificação GATE-{N} — {nome do gate}
+
+✅ {item validado com sucesso}
+✅ {item validado com sucesso}
+⚠️  {item com aviso — explicação}
+🚫 {item com falha — o que fazer}
+
+[GATE-{N}]: {APROVADO | APROVADO COM AVISOS | FALHA}
+```
+
+**Se falha:** liste os itens pendentes e pergunte como proceder antes de continuar.
+
+**Gates por modo (conforme gate-system.md):**
+
+| Gate | BOOTSTRAP | STANDARD | STRICT |
+|---|---|---|---|
+| GATE-0 | ✅ (aviso) | ✅ | ✅ |
+| GATE-1 | ✅ | ✅ | ✅ |
+| GATE-DECISION | ✅ | ✅ | ✅ |
+| GATE-ADR | ❌ | ✅ | ✅ |
+| GATE-2, 3, 5 | ❌ | ✅ | ✅ |
+| GATE-4, GATE-DESIGN | ❌ | ❌ | ✅ |
+
+---
+
+### Sistema de Comandos via Comentário
+
+O usuário pode ativar comportamentos sem digitar no chat, usando comentários no código.
+
+**Sintaxe:**
+```
+// synapos:{comando} {param}:{valor} {param}:{valor}
+```
+
+**Parsing pelo Copilot:**
+1. Detecte qualquer linha com `synapos:` no início (comentário ou mensagem no chat)
+2. Extraia o comando e os parâmetros chave:valor
+3. Execute o protocolo correspondente em `.synapos/copilot.md`
+
+**Comandos suportados:**
+
+```
+// synapos:init
+```
+→ Execute o protocolo de ativação completo (`.synapos/copilot.md` PASSO 1–8)
+
+```
+// synapos:squad squad:frontend mode:bootstrap pipeline:bug-fix feature:fix-login
+```
+→ Crie e ative squad diretamente (pula para PASSO 6 do copilot.md)
+
+```
+// synapos:step step:02-design-api
+```
+→ Execute o step especificado do pipeline ativo
+
+```
+// synapos:gate gate:GATE-2
+```
+→ Execute a validação do gate especificado
+
+```
+// synapos:status
+```
+→ Exiba estado atual do squad e session
+
+```
+// synapos:decision id:1 choice:A
+```
+→ Resolva uma DECISÃO PENDENTE registrada em open-decisions.md
+
+```
+// synapos:memory
+```
+→ Exiba o conteúdo de `docs/.squads/sessions/{feature-slug}/memories.md`
+
+---
+
+### Prompt Anchors — Contexto Prioritário
+
+Para que o Copilot priorize contexto crítico do projeto, use este padrão no topo de arquivos importantes:
+
+```html
+<!-- SYNAPOS: CONTEXT START -->
+Projeto: {nome do projeto}
+Stack: {tecnologias principais}
+Regras críticas:
+- {regra 1 — ex: nunca quebrar autenticação}
+- {regra 2}
+<!-- SYNAPOS: CONTEXT END -->
+```
+
+O Copilot lê arquivos abertos no editor e usa este bloco como contexto prioritário.
+Útil para: `README.md`, `docs/_memory/company.md`, arquivos de configuração principal.
+
+---
+
+### State Management — Arquivos como Estado
+
+O Copilot não mantém estado entre sessões. Os arquivos abaixo são a fonte de verdade:
+
+| Arquivo | Propósito | Quando ler |
+|---------|-----------|------------|
+| `docs/_memory/company.md` | Perfil do projeto | Todo `synapos:init` |
+| `docs/_memory/preferences.md` | Preferências (modelo, IDE, tracker) | Início de cada sessão |
+| `.synapos/squads/{slug}/squad.yaml` | Configuração do squad ativo | Todo `synapos:step` |
+| `docs/.squads/sessions/{slug}/state.json` | Estado da feature | Verificação de progresso |
+| `docs/.squads/sessions/{slug}/memories.md` | Aprendizados acumulados | Início de cada execução |
+| `docs/.squads/sessions/{slug}/context.md` | Contexto da feature | Steps de implementação |
+
+**Instrução ao Copilot para cada step:**
+Antes de executar, leia os arquivos listados acima usando `@workspace` ou referenciando-os explicitamente no chat.
+
+---
+
+### MODEL-ADAPTER no Copilot
+
+O `model_capability` em `preferences.md` também se aplica no Copilot Mode.
+
+| `model_capability` | Comportamento |
+|---|---|
+| `high` | Execução padrão — contexto completo |
+| `standard` | Injete o CoT Prefix antes de cada step (S1 do model-adapter.md) |
+| `lite` | Ative todos os mecanismos L1–L6 do model-adapter.md |
+
+Para GPT-4o (Copilot padrão): assuma `high`.
+
+---
+
+## FLUXO TÍPICO NO COPILOT
+
+```
+1. Usuário abre projeto no VS Code / GitHub Copilot Chat
+2. Copilot carrega .github/copilot-instructions.md automaticamente
+3. Usuário digita: synapos:init
+4. Copilot executa .synapos/copilot.md — PASSO 1
+   → Verifica docs/_memory/company.md
+   → Calcula DOC_SCORE
+   → Determina EXECUTION_MODE
+5. Usuário seleciona squad ou cria novo
+6. Squad é criado em .synapos/squads/{slug}/
+7. Pipeline inicia step-by-step
+   → Cada step: lê .agent.md + contexto + instrução
+   → Executa inline
+   → Aplica gates via checklist
+   → Salva output em docs/.squads/sessions/{feature}/
+8. Ao final: atualiza memories.md + state.json
+```
+
+---
+
+## LIMITAÇÕES E COMPENSAÇÕES
+
+| Limitação do Copilot | Compensação Synapos |
+|----------------------|---------------------|
+| Sem memória persistente entre sessões | `state.json` + `memories.md` como estado externo |
+| Sem execução de pipeline automática | Step-by-step via comandos `synapos:step` |
+| Sem subagentes reais | Personas inline via `.agent.md` + prefixo de agent |
+| Sem botões interativos | Listas numeradas com input explícito |
+| Sem controle de fluxo | Markdown como engine + comentários como comandos |
+| Sem tool calls | Skills simuladas via instruções inline no step |
+
+---
+
+## REGRAS DO ADAPTER
+
+| Regra | Descrição |
+|-------|-----------|
+| **Arquivo aberto = contexto** | Incentive o usuário a abrir os arquivos relevantes no editor |
+| **@workspace para busca** | Use `@workspace` para encontrar arquivos quando necessário |
+| **Um step por vez** | Nunca execute múltiplos steps simultaneamente |
+| **Gate como checklist** | Todo gate deve ser visível ao usuário como checklist |
+| **DECISÃO PENDENTE é obrigatória** | Qualquer decisão fora do escopo = `[DECISÃO PENDENTE]` |
+| **Nunca assuma modo** | Se o modo não estiver claro, pergunte antes de executar |
+| **Instrua a abrir arquivos** | Se o contexto necessário não estiver carregado, peça ao usuário para abrir o arquivo |

package/.synapos/core/gate-system.md

@@ -0,0 +1,417 @@
+---
+name: synapos-gate-system
+version: 1.5.0
+description: Sistema de quality gates — validação em pontos críticos do pipeline
+---
+
+# SYNAPOS GATE SYSTEM v1.4.0
+
+> Gates são pontos de validação obrigatórios. Falha em um gate bloqueia o avanço.
+> Princípio: **Fail Loud, Never Silent** — nunca ignore uma falha de gate.
+
+---
+
+## GATES DISPONÍVEIS
+
+Use `gate:` nos steps do pipeline.yaml para ativar um gate antes de continuar.
+
+---
+
+### GATE-0 — Integridade do Framework e Documentação do Projeto
+
+**Quando usar:** No primeiro step de qualquer pipeline. **Obrigatório antes de qualquer execução.**
+
+**Verifica — Framework:**
+- [ ] `.synapos/core/orchestrator.md` existe
+- [ ] `.synapos/core/pipeline-runner.md` existe
+- [ ] `docs/_memory/company.md` existe
+- [ ] `docs/_memory/preferences.md` existe
+- [ ] `.synapos/squads/{slug}/squad.yaml` existe
+- [ ] `.synapos/squads/{slug}/agents/` tem pelo menos um .agent.md
+
+**Verifica — Documentação do Projeto (obrigatório):**
+- [ ] Pasta `docs/` existe na raiz do projeto
+- [ ] `docs/` contém pelo menos um arquivo `.md`
+
+**Verificação de documentação — leia `execution_mode` do squad.yaml:**
+
+| `execution_mode` | Comportamento se `docs/` ausente ou incompleta |
+|---|---|
+| `bootstrap` | Passa com aviso — gates GATE-ADR e GATE-2 desativados |
+| `standard` | Passa se `company.md` + pelo menos 1 dir de docs existir; avisa sobre gaps |
+| `strict` | Exige `company.md` + `docs/tech/` + `docs/business/` — bloqueia se faltar |
+
+---
+
+**BOOTSTRAP — docs ausentes ou incompletas:**
+```
+⚡ GATE-0 (Bootstrap Mode) — Score de documentação: {doc_score}/100
+   Executando com contexto mínimo.
+
+   Gates ativos neste modo: GATE-DECISION
+   Desativados: GATE-ADR, GATE-2, GATE-DESIGN
+
+   Para resultados melhores:
+   → /setup:build-tech       (+35 pontos de documentação)
+   → /setup:build-business   (+40 pontos de documentação)
+
+Prosseguindo...
+```
+
+**STANDARD — docs parcialmente presentes:**
+```
+🟡 GATE-0 (Standard Mode) — Score de documentação: {doc_score}/100
+   Contexto parcial. Executando com gates essenciais.
+
+   Gates ativos: GATE-0, GATE-ADR, GATE-DECISION
+   Desativados: GATE-DESIGN (requer docs/business completo)
+
+   Documentação faltante:
+   {lista de itens ausentes com pontos correspondentes}
+
+Prosseguindo...
+```
+
+**STRICT — docs completas:**
+```
+🔴 GATE-0 (Strict Mode) — Score de documentação: {doc_score}/100
+   Contexto completo. Todos os gates ativos.
+
+✅ GATE-0 aprovado
+```
+
+**STRICT sem documentação completa — bloqueia:**
+```
+🚫 GATE-0 — Documentação insuficiente para Strict Mode
+
+Score atual: {doc_score}/100 (mínimo necessário: 70)
+
+Itens faltantes:
+  ✗ {item} — {pontos} pontos
+
+Opções:
+  → Crie a documentação: /setup:build-tech e /setup:build-business
+  → Execute uma tarefa mais simples (reduz para Standard/Bootstrap automaticamente)
+```
+
+**Falha de framework (qualquer modo):** Liste os arquivos faltantes do core e pare.
+
+---
+
+### GATE-1 — Configuração do Squad
+
+**Quando usar:** Após criação do squad, antes do primeiro step real.
+
+**Verifica:**
+- [ ] squad.yaml tem `name`, `domain`, `description` preenchidos
+- [ ] squad.yaml tem `feature` e `session` preenchidos (obrigatório no modelo v2)
+- [ ] Todos os agents listados em squad.yaml têm arquivo .agent.md correspondente
+- [ ] Pipeline referenciado em squad.yaml existe
+
+**Falha:** Informe o campo ou arquivo faltante e pare.
+
+---
+
+### GATE-2 — Contexto Completo
+
+**Quando usar:** Antes de steps de implementação/execução (após discovery).
+
+**Verifica:**
+- [ ] Objetivo do squad está claro (description no squad.yaml)
+- [ ] Ao menos um documento de contexto existe em `docs/` (raiz do projeto)
+- [ ] `docs/.squads/sessions/{feature-slug}/memories.md` foi lido e considerado
+- [ ] Se `context.md` existe na session, foi carregado no contexto do agent
+
+**Falha:** Informe o que está incompleto. Sugira executar o step de investigação (pré-execução) primeiro.
+
+---
+
+### GATE-3 — Qualidade do Output
+
+**Quando usar:** Antes de steps de revisão ou handoff.
+
+**Verifica (com base nas veto_conditions do step anterior):**
+- [ ] Output não está vazio
+- [ ] Output atende os critérios mínimos do agent (Quality Criteria do .agent.md)
+- [ ] Nenhuma veto_condition foi violada
+
+**Falha:** Aponte a condição violada. Retorne ao step anterior.
+
+---
+
+### GATE-4 — Consistência de Documentação (Produto)
+
+**Quando usar:** Exclusivo para squad de Produto, antes do handoff.
+
+**Verifica (na session folder `docs/.squads/sessions/{feature-slug}/`):**
+- [ ] `context.md` existe e não está vazio
+- [ ] `architecture.md` ou `spec.md` existe com critérios de aceite
+- [ ] `plan.md` existe (se pipeline gerou)
+- [ ] `review-notes.md` existe
+- [ ] `state.json` tem entrada para este squad com todos os steps concluídos
+
+**Falha:** Liste os documentos faltantes na session. Não libere o handoff.
+
+---
+
+### GATE-DECISION — Bloqueio de Decisões Autônomas
+
+**Quando usar:** Após cada step com `execution: subagent` ou `execution: inline`. Aplicado automaticamente pelo pipeline-runner antes de aceitar qualquer output.
+
+**Princípio:** Nenhum agent pode tomar decisões além do escopo definido no step. Toda decisão deve ser sinalizada e aprovada pelo usuário.
+
+**O que é considerado uma decisão:**
+- Escolha de biblioteca, framework ou ferramenta não especificada no step
+- Definição de estrutura de dados, schema ou interface não solicitada
+- Escolha de padrão arquitetural (MVC, CQRS, Event Sourcing, etc.) não documentada em ADR
+- Escolha de biblioteca de componentes UI não especificada no step
+- Desvio de padrão documentado no design system sem justificativa
+- Escolha de padrão de interação (ex: modal vs. drawer, inline edit vs. form separado) não documentada
+- Qualquer "assumindo que..." ou "optei por..." no output
+
+**Como o agent deve sinalizar:**
+
+Quando o agent identifica que precisa tomar uma decisão além do escopo, ele **para** e inclui no output:
+
+```
+[DECISÃO PENDENTE] {id-sequencial}
+Contexto: {por que essa decisão é necessária}
+Opções:
+  A) {opção A} — {prós/contras}
+  B) {opção B} — {prós/contras}
+Recomendação do agent: {opção recomendada e por quê}
+Aguardando aprovação para prosseguir.
+```
+
+**Verifica:**
+- [ ] O output **não** contém decisões implícitas (sem `[DECISÃO PENDENTE]` quando deveria ter)
+- [ ] Cada `[DECISÃO PENDENTE]` foi aprovada pelo usuário antes de o agent prosseguir
+- [ ] O agent não escolheu unilateralmente entre as opções sem aprovação
+
+**Falha — Decisão implícita detectada:**
+```
+🚫 GATE-DECISION — FALHA: Decisão autônoma detectada
+
+O agent tomou a seguinte decisão sem aprovação:
+"{trecho do output}"
+
+O agent não pode prosseguir com esta decisão.
+Reexecutando step com instrução: sinalizar como [DECISÃO PENDENTE].
+```
+
+**Falha — Decisão pendente não resolvida:**
+```
+⏸ GATE-DECISION — AGUARDANDO: Decisão pendente
+
+[DECISÃO PENDENTE] {id}
+{conteúdo da decisão pendente}
+
+Selecione uma opção para continuar:
+- A) {opção A}
+- B) {opção B}
+- ✏️ Definir outra opção
+```
+
+Aguarde a seleção do usuário. **Nunca resolva automaticamente.**
+
+---
+
+### GATE-ADR — Conformidade com ADRs (Implementação Guiada por ADRs)
+
+**Quando usar:** Obrigatório antes de qualquer step de implementação (`execution: subagent` ou `execution: inline`) quando o projeto tem ADRs em `docs/`.
+
+**Verifica:**
+- [ ] O agent leu todas as ADRs disponíveis em `docs/` (arquivos com `ADR`, `adr`, `decisions`, `architecture-decision` no nome ou caminho)
+- [ ] O output do step lista explicitamente quais ADRs foram consultadas
+- [ ] Nenhuma decisão técnica no output contradiz uma ADR com status `Aceito` ou `Ativo`
+- [ ] Se o step CRIA uma nova ADR, ela segue o template padrão (Contexto / Decisão / Alternativas / Consequências)
+
+**Resultado esperado:** Código e documentação conformes com ADRs desde o início — não como revisão posterior.
+
+**Falha — Conflito detectado:**
+```
+🚫 GATE-ADR — FALHA: Conflito com ADR existente
+
+ADR violada: {adr-id} — {título}
+Decisão conflitante no output: {trecho}
+Status da ADR: Aceito
+
+O agent não pode prosseguir com decisões que contradizem ADRs aprovadas.
+Opções:
+  - Revise o output para seguir a ADR
+  - Proponha uma nova ADR para substituir a existente (requer aprovação do usuário)
+```
+
+**Falha — ADRs não consultadas:**
+```
+⚠️  GATE-ADR — AVISO: ADRs não referenciadas no output
+
+ADRs disponíveis não foram listadas pelo agent.
+Reexecutando step com instrução explícita de consulta às ADRs.
+```
+
+**Falha — Decisão sem ADR correspondente:**
+```
+⚠️  GATE-ADR — AUSÊNCIA: Decisão arquitetural sem ADR
+
+O output contém decisão de alto impacto sem ADR correspondente:
+"{trecho da decisão}"
+
+Opções:
+  - Crie uma nova ADR para documentar esta decisão antes de prosseguir
+  - Use [DECISÃO PENDENTE] para aguardar aprovação do usuário
+
+Decisões que requerem ADR: escolha de framework, banco de dados, padrão arquitetural,
+estratégia de cache, política de autenticação, estrutura de dados principal.
+```
+
+---
+
+### GATE-DESIGN — Conformidade com Design System e Acessibilidade
+
+**Quando usar:** Em steps de frontend/produto que geram especificações de componente, fluxos de UI ou documentação visual. Aplicado automaticamente em steps onde o agent tem `tasks` contendo `design-system`, `component-spec` ou `ux-review`.
+
+**Verifica:**
+- [ ] Todos os estados de componente especificados: default, hover, focus, disabled, loading, error
+- [ ] Contraste de texto ≥ 4.5:1 (WCAG 2.1 AA) — valor numérico declarado no output
+- [ ] Estado vazio (`empty state`) documentado para listas e views de dados
+- [ ] Estado de erro com mensagem clara e ação de recuperação
+- [ ] Componentes novos justificados — existência verificada no design system antes de propor novo
+- [ ] Responsividade: breakpoints mobile e desktop definidos (se aplicável ao componente)
+- [ ] Tokens de design usados (sem valores hardcoded de cor, espaçamento ou tipografia)
+
+**Output esperado:** Seção `## Verificação GATE-DESIGN` no arquivo de spec com cada item marcado como `✅` ou `⚠️ Justificativa`.
+
+**Falha — estados faltando:**
+```
+🚫 GATE-DESIGN — FALHA: Estados de componente incompletos
+
+Componente(s) com estados faltando:
+  ✗ {componente}: falta {estados ausentes}
+
+Todo componente interativo deve ter todos os 6 estados especificados.
+Adicione os estados antes de prosseguir.
+```
+
+**Falha — contraste:**
+```
+🚫 GATE-DESIGN — FALHA: Contraste insuficiente ou não verificado
+
+Requisito: ≥ 4.5:1 para texto normal, ≥ 3:1 para texto grande (WCAG 2.1 AA)
+Pendente: {lista de elementos sem contraste declarado}
+
+Declare o ratio de contraste ou ajuste as cores.
+```
+
+**Falha — componente não justificado:**
+```
+⚠️  GATE-DESIGN — AVISO: Componente novo sem verificação de design system
+
+Componente(s) propostos sem verificação se existem no design system:
+  ? {nome do componente}
+
+Verifique se já existe antes de propor. Se não existe, documente a justificativa.
+```
+
+**Gate passando:**
+```
+✅ GATE-DESIGN — Design System e Acessibilidade: aprovado
+```
+
+---
+
+### GATE-5 — Entrega / Handoff
+
+**Quando usar:** Último step de qualquer pipeline antes de marcar como completed.
+
+**Verifica:**
+- [ ] Todos os `output_file` definidos no pipeline foram gerados em `docs/.squads/sessions/{feature-slug}/`
+- [ ] `state.json` marca `state.squads["{squad-slug}"].completed_steps` com todos os steps do pipeline
+- [ ] Não há veto_conditions pendentes
+- [ ] Não há `[DECISÃO PENDENTE]` não resolvida nos arquivos da session
+
+**Falha:** Liste o que está faltando. Não marque o squad como completed.
+
+---
+
+## GATES POR EXECUTION MODE
+
+O pipeline-runner lê `execution_mode` do squad.yaml e ativa apenas os gates correspondentes:
+
+| Gate | BOOTSTRAP | STANDARD | STRICT |
+|---|---|---|---|
+| GATE-0 | ✅ (passa com aviso) | ✅ | ✅ |
+| GATE-1 | ✅ | ✅ | ✅ |
+| GATE-2 | ❌ desativado | ✅ | ✅ |
+| GATE-3 | ❌ desativado | ✅ | ✅ |
+| GATE-4 | ❌ desativado | ❌ desativado | ✅ |
+| GATE-5 | ❌ desativado | ✅ | ✅ |
+| GATE-ADR | ❌ desativado | ✅ | ✅ |
+| GATE-DECISION | ✅ | ✅ | ✅ |
+| GATE-DESIGN | ❌ desativado | ❌ desativado | ✅ |
+
+> **GATE-1 e GATE-DECISION são universais** — ativos em todos os modos, sempre.
+> **GATE-DECISION nunca é desativado** — evitar decisões autônomas é princípio inegociável.
+
+---
+
+## COMO USAR NOS PIPELINES
+
+No `pipeline.yaml`, adicione `gate:` em um step:
+
+```yaml
+steps:
+  - id: gate-contexto
+    name: "Validar Contexto"
+    execution: checkpoint
+    gate: GATE-2
+    # Não tem agent — é validação automática
+
+  - id: implementacao
+    name: "Implementar Feature"
+    agent: rodrigo-react
+    depends_on: [gate-contexto]
+    ...
+```
+
+Ou como validação inline antes de continuar um step:
+
+```yaml
+  - id: spec-final
+    name: "Spec Final"
+    agent: priscila-produto
+    gate: GATE-4    # Gate executado ANTES de aceitar o output
+    ...
+```
+
+---
+
+## VETO CONDITIONS vs GATES
+
+| | Veto Conditions | Gates |
+|--|----------------|-------|
+| **Escopo** | Output de um step específico | Marco estrutural do pipeline |
+| **Foco** | Qualidade do conteúdo gerado | Existência e consistência de artefatos |
+| **Retentativa** | Automática (até 2x) | Bloqueia até usuário resolver |
+| **Exemplo** | "Output sem critérios de aceite" | "Todos os docs de handoff existem" |
+
+---
+
+## MENSAGENS DE GATE
+
+**Gate passando:**
+```
+✅ GATE-{N} — {nome}: aprovado
+```
+
+**Gate falhando:**
+```
+🚫 GATE-{N} — {nome}: FALHA
+
+Motivo: {descrição específica}
+Itens faltantes:
+  ✗ {item 1}
+  ✗ {item 2}
+
+Resolva e execute novamente.
+```