@semacode/cli 1.5.46 → 1.5.47

package/AGENTS.md

@@ -1,324 +1,324 @@
-# Sema — Regras obrigatorias para IA
-
-O Sema e o contrato semantico IA-first deste projeto.
-Toda IA deve consultar o Sema antes de qualquer acao sobre codigo ou contratos. Humanos escrevem e aprovam; agentes consomem o contrato para operar software vivo.
-
-## Boot obrigatório para qualquer IA
-
-Antes de abrir código cru, leia `SEMA_BOOT.md`. Se a IA tiver pouco contexto, pouca disciplina de tool use ou for um agente secundário, leia também `SEMA_SMALL_MODEL.md`.
-
-Capacidade operacional:
-
-- IA fraca: use `SEMA_BOOT.md`, `SEMA_SMALL_MODEL.md`, `SEMA_BRIEF.micro.txt` e falhe fechado se Sema não responder.
-- IA média: use `SEMA_BOOT.md`, `AGENT_CONTEXT_PACK.json`, `SEMA_BRIEF.curto.txt` e `SEMA_INDEX.json`.
-- IA forte: pode subir para `SEMA_BRIEF.md`, AST, IR e drift completo, mas continua obrigada a passar pelos gates Sema.
-
-Timeout operacional: timeout definido pelo agente não é falha do Sema. Se `sema resumo`, `sema_drift`, `sema_docs_impacto` ou outro gate estourar timeout local, aumente o timeout e tente de novo. Para projeto grande, prefira escopar para o contrato ou arquivo alvo; se o ambiente impedir continuar, pare bloqueado e não avance sem Sema.
-
-Idioma humano: responda no idioma falado pelo usuário. Em PT-BR, use acentos, cedilha, pontuação e símbolos normais. A DSL `.sema` pode usar palavras-chave ASCII; isso não autoriza texto humano sem acentos.
-
-## Regras
-
-1. Em IDE/local com workspace no disco, use a Sema CLI. Antes de qualquer leitura de projeto, rode `sema --version`; se o comando não existir, pare. A IA não acessa o painel Sema: peça ao humano para abrir o painel, baixar/rodar o instalador de chave e repetir `sema --version`.
-2. Depois rode `sema preflight resumo --json`; se `decisao` não for `use_cli_local`, pare bloqueado.
-3. Com CLI autorizada, rode `sema resumo`, depois `sema docs-impacto --intencao "<ação declarada>" --json`, leia as docs obrigatórias e só então avance.
-4. Em web/chat/remoto sem workspace local, use MCP remoto: `sema_chat_contexto`, depois `sema_sync` inline com contrato `.sema`, código selecionado, documentação e índice. Use o `projeto` retornado nas chamadas seguintes.
-5. É proibido usar MCP remoto, `sema_sync`, `sema_contratos_sincronizar` ou `sema mcp-client` para ler workspace local quando a CLI estiver operacional.
-6. Antes de criar qualquer módulo, rota, task ou contrato, chame `sema inspecionar` ou `sema_inspecionar` no arquivo `.sema` mais próximo.
-7. Antes de editar código existente, em IDE/local chame `sema drift` e `sema impacto`. Em web/remoto, use `sema_drift` e `sema_impacto` somente sobre o projeto remoto sincronizado.
-8. Ao criar ou editar um arquivo `.sema`, chame `sema validar` ou `sema_validar` ao final.
-9. Nunca invente contratos — use o Sema para descobrir o que já existe.
-10. Se qualquer ferramenta Sema retornar erro, corrija o problema antes de prosseguir — não avance com código enquanto houver erros Sema pendentes.
-11. Contrato vem antes de qualquer ação: crie, edite ou remova o `.sema` aplicável antes de código, deploy, docs operacionais, workflow, texto Author, game, legal, research ou ops.
-
-## MCP
-
-O servidor MCP do Sema e uma superficie privada/comercial acessada por endpoint remoto autorizado; ele nao e instalado pelo pacote npm do instalador neste repositorio.
-Use as ferramentas quando o endpoint privado estiver configurado: sema_resumo, sema_validar, sema_drift, sema_impacto, sema_renomear_semantico, sema_inspecionar, sema_ir, sema_verificar, sema_contexto_ia, sema_prompt_ia, sema_author_iniciar, sema_author_validar, sema_author_briefing, sema_author_revisar_cliches, sema_sync_ai_entrypoints, sema_exemplos, sema_instalar_exemplos, sema_docs_impacto, sema_finalizar_mudanca.
-
-Em IDE/local, a superfície principal é a Sema CLI. A IA deve provar a CLI com `sema --version`; se falhar, deve parar. A IA não acessa o painel Sema: peça ao humano para instalar pelo painel. A CLI deve ter `SEMA_CLI_AUTH_TOKEN` e deve chamar `sema preflight <comando> --json` antes de operar. Se `decisao` não for `use_cli_local`, pare. Não use MCP remoto, `sema_sync`, `sema_contratos_sincronizar` nem `sema mcp-client` para ler workspace local quando a CLI estiver operacional.
-
-Em web/chat/remoto sem workspace local, use MCP remoto: `sema_chat_contexto`, depois `sema_sync` inline com contrato, código selecionado, documentação e índice, e então use o `projeto` retornado.
-
-O MCP deve deixar claro em toda orientacao: se nao existe contrato, crie; se a intencao mudou, edite; se a capacidade saiu, remova ou aposente. Isso vale para todo tipo de Sema: Software, Author, Workflow, Ops, Game, Legal, Research e profiles futuros.
-
-## Plataformas e Interfaces
-
-### IDEs locais (Codex, Roo Code, VS Code, Cursor, Windsurf, etc.)
-Quando houver workspace local:
-1. Rode `sema --version`; se falhar, pare. A IA não acessa o painel Sema: peça ao humano para abrir o painel, baixar/rodar o instalador de chave e repetir `sema --version`.
-2. Rode `sema preflight resumo --json`; se `decisao` não for `use_cli_local`, pare.
-3. Rode `sema resumo` para entender o estado atual.
-4. **ANTES DE QUALQUER AÇÃO**: rode `sema docs-impacto --intencao "<acao>" --json`.
-5. Leia as docs obrigatórias antes de agir.
-6. Rode `sema inspecionar`, `sema drift` e `sema impacto` antes de editar.
-7. Use `sema finalizar-mudanca` para comprovar que leu as docs.
-
-### Web / Chat (ChatGPT, Lovable, etc.)
-Quando usar Sema via MCP remoto sem workspace local:
-1. Chame `sema_chat_contexto` para confirmar conexão e orientação.
-2. **ANTES DE QUALQUER AÇÃO**: declare sua intenção ao usuário.
-3. Chame `sema_sync` com contrato `.sema`, código selecionado, documentação e índice.
-4. Use obrigatoriamente o `projeto` retornado por `sema_sync`.
-5. Chame `sema_resumo`, `sema_docs_impacto`, `sema_inspecionar`, `sema_drift` e `sema_impacto` usando esse `projeto`.
-6. Leia as docs antes de agir e finalize com `sema_finalizar_mudanca`.
-
-### CLI / Terminal
-Quando usar Sema via CLI:
-1. Execute `sema preflight <comando> --json` antes de operar; se bloquear, pare.
-2. Execute `sema resumo` para entender o estado atual.
-3. Execute `sema docs-impacto` antes de qualquer ação.
-4. Leia as docs recomendadas antes de editar/criar/deletar.
-5. Execute `sema finalizar-mudanca` ao concluir.
-
-## Contratos e exemplos
-
-- Sempre salve arquivos .sema na pasta `contratos/` do projeto.
-- Crie um arquivo .sema por modulo ou contexto de negocio. Exemplo: `contratos/pedido.sema`, `contratos/pagamento.sema`, `contratos/usuario.sema`. Nunca coloque modulos de contextos diferentes no mesmo arquivo.
-- Antes de criar qualquer arquivo .sema, leia os exemplos oficiais para entender o formato correto da linguagem.
-- Em MCP remoto/cliente web, use `sema_exemplos` para listar ou ler exemplos oficiais. Nao peca para o MCP ler `C:\GitHub\Sema\exemplos` nem qualquer pasta local do usuario.
-- Em CLI/local repo, a pasta `exemplos/` pode ser lida ou materializada localmente quando necessario.
-- Nunca edite os arquivos da pasta `exemplos/`.
-
-## Quando o projeto nao tem .sema
-
-Pergunte ao usuario se deseja semantizar o projeto e sugira: sema iniciar
-
-## Exemplos de arquivos .sema (referencia de formato)
-
-### 1. Task simples com testes
-```
-module exemplos.calculadora {
-  task somar {
-    input {
-      a: Numero required
-      b: Numero required
-    }
-    output {
-      resultado: Numero
-    }
-    rules {
-      a deve_ser numero_valido
-      b deve_ser numero_valido
-    }
-    effects {
-      auditoria operacao soma
-    }
-    guarantees {
-      resultado existe
-    }
-    error {
-      entrada_invalida: "Os valores precisam ser numericos."
-    }
-    tests {
-      caso "soma basica" {
-        given { a: 2  b: 3 }
-        expect { sucesso: verdadeiro }
-      }
-    }
-  }
-}
-```
-
-### 2. Entity + CRUD com route
-```
-module exemplos.crud.simples {
-  entity Produto {
-    fields {
-      id: Id
-      nome: Texto
-      preco: Decimal
-      ativo: Booleano
-    }
-  }
-
-  task criar_produto {
-    input {
-      nome: Texto required
-      preco: Decimal required
-    }
-    output {
-      produto: Produto
-    }
-    rules {
-      nome deve_ser preenchido
-      preco deve_ser positivo
-    }
-    effects {
-      persistencia Produto
-      auditoria produto_criado
-    }
-    guarantees {
-      produto existe
-    }
-    tests {
-      caso "cria produto" {
-        given { nome: "Caneca"  preco: 39.9 }
-        expect { sucesso: verdadeiro }
-      }
-    }
-  }
-
-  route produtos {
-    metodo: POST
-    caminho: /produtos
-    task: criar_produto
-    finalidade: cadastro_produto
-    input { nome: Texto  preco: Decimal }
-    output { produto: Produto }
-  }
-}
-```
-
-### 3. Cadastro com validacoes e unicidade
-```
-module exemplos.cadastro.usuario {
-  entity Usuario {
-    fields {
-      id: Id
-      nome: Texto
-      email: Email
-      ativo: Booleano
-    }
-  }
-
-  task criar_usuario {
-    input {
-      nome: Texto required
-      email: Email required
-    }
-    output {
-      usuario: Usuario
-    }
-    rules {
-      nome deve_ser preenchido
-      email deve_ser email_valido
-      email deve_ser unico em Usuario.email
-    }
-    effects {
-      persistencia Usuario
-      evento usuario_criado
-      auditoria cadastro_usuario
-    }
-    guarantees {
-      usuario existe
-      persistencia concluida
-    }
-    error {
-      email_duplicado: "Ja existe usuario com este email."
-      entrada_invalida: "Os dados informados nao atendem as regras."
-    }
-    tests {
-      caso "cria usuario valido" {
-        given { nome: "Ana"  email: "ana@empresa.com" }
-        expect { sucesso: verdadeiro }
-      }
-    }
-  }
-}
-```
-
-### 4. Pagamento com state e flow
-```
-module exemplos.pagamento {
-  task processar_pagamento {
-    input {
-      pagamento_id: Id required
-      valor: Decimal required
-      token: Texto required
-    }
-    output {
-      pagamento: Pagamento
-      status: StatusPagamento
-    }
-    rules {
-      valor > 0
-      token deve_ser valido
-    }
-    effects {
-      consulta gateway_pagamento criticidade = alta
-      persistencia Pagamento criticidade = alta
-      evento pagamento_autorizado criticidade = media
-      auditoria pagamento criticidade = alta
-    }
-    state ciclo_pagamento {
-      transitions {
-        PENDENTE -> AUTORIZADO
-        AUTORIZADO -> PROCESSADO
-      }
-    }
-    guarantees {
-      pagamento existe
-      status em [AUTORIZADO, PROCESSADO]
-    }
-    error {
-      autorizacao_negada: "Recusado pelo gateway."
-      timeout_gateway: "Gateway nao respondeu."
-    }
-    tests {
-      caso "pagamento autorizado" {
-        given { pagamento_id: "pag_1"  valor: 199.9  token: "tok_ok" }
-        expect { sucesso: verdadeiro }
-      }
-      caso "pagamento recusado" {
-        given { pagamento_id: "pag_err"  valor: 10  token: "tok_recusado" }
-        expect { sucesso: falso }
-        error { tipo: "autorizacao_negada" }
-      }
-    }
-  }
-
-  flow orquestracao_pagamento {
-    pagamento_id: Id
-    valor: Decimal
-    token: Texto
-    etapa autorizar usa processar_pagamento com pagamento_id = pagamento_id, valor = valor, token = token em_sucesso confirmar em_erro registrar_falha
-    etapa confirmar usa confirmar_pagamento com pagamento_id = pagamento_id depende_de autorizar
-    etapa registrar_falha usa registrar_timeout_pagamento com pagamento_id = pagamento_id depende_de autorizar
-  }
-}
-```
-
-### 5. Tratamento de erro com flow ramificado
-```
-module exemplos.tratamento.erro {
-  task executar_operacao_sensivel {
-    input {
-      chave: Texto required
-    }
-    output {
-      protocolo: Id
-    }
-    rules {
-      chave deve_ser preenchida
-    }
-    effects {
-      consulta cofre
-      auditoria falha_operacao_sensivel
-    }
-    guarantees {
-      protocolo existe
-    }
-    error {
-      acesso_negado: "A chave nao tem permissao."
-      recurso_indisponivel: "Servico temporariamente indisponivel."
-    }
-    tests {
-      caso "falha por acesso negado" {
-        given { chave: "sem_permissao" }
-        expect { sucesso: falso }
-        error { tipo: "acesso_negado" }
-      }
-    }
-  }
-
-  flow resposta_segura {
-    chave: Texto
-    etapa tentar usa executar_operacao_sensivel com chave = chave em_sucesso concluir em_erro registrar_falha por_erro acesso_negado = tratar_acesso_negado, recurso_indisponivel = agendar_retentativa
-    etapa tratar_acesso_negado usa responder_acesso_negado com chave = chave depende_de tentar
-    etapa agendar_retentativa usa responder_retentativa com chave = chave depende_de tentar
-    etapa registrar_falha usa registrar_auditoria_falha com chave = chave depende_de tentar
-    etapa concluir usa registrar_sucesso com protocolo = tentar.protocolo depende_de tentar
-  }
-}
-```
+# Sema — Regras obrigatorias para IA
+
+O Sema e o contrato semantico IA-first deste projeto.
+Toda IA deve consultar o Sema antes de qualquer acao sobre codigo ou contratos. Humanos escrevem e aprovam; agentes consomem o contrato para operar software vivo.
+
+## Boot obrigatório para qualquer IA
+
+Antes de abrir código cru, leia `SEMA_BOOT.md`. Se a IA tiver pouco contexto, pouca disciplina de tool use ou for um agente secundário, leia também `SEMA_SMALL_MODEL.md`.
+
+Capacidade operacional:
+
+- IA fraca: use `SEMA_BOOT.md`, `SEMA_SMALL_MODEL.md`, `SEMA_BRIEF.micro.txt` e falhe fechado se Sema não responder.
+- IA média: use `SEMA_BOOT.md`, `AGENT_CONTEXT_PACK.json`, `SEMA_BRIEF.curto.txt` e `SEMA_INDEX.json`.
+- IA forte: pode subir para `SEMA_BRIEF.md`, AST, IR e drift completo, mas continua obrigada a passar pelos gates Sema.
+
+Timeout operacional: timeout definido pelo agente não é falha do Sema. Se `sema resumo`, `sema_drift`, `sema_docs_impacto` ou outro gate estourar timeout local, aumente o timeout e tente de novo. Para projeto grande, prefira escopar para o contrato ou arquivo alvo; se o ambiente impedir continuar, pare bloqueado e não avance sem Sema.
+
+Idioma humano: responda no idioma falado pelo usuário. Em PT-BR, use acentos, cedilha, pontuação e símbolos normais. A DSL `.sema` pode usar palavras-chave ASCII; isso não autoriza texto humano sem acentos.
+
+## Regras
+
+1. Em IDE/local com workspace no disco, use a Sema CLI. Antes de qualquer leitura de projeto, rode `sema --version`; se o comando não existir, pare. A IA não acessa o painel Sema: peça ao humano para abrir o painel, baixar/rodar o instalador de chave e repetir `sema --version`.
+2. Depois rode `sema preflight resumo --json`; se `decisao` não for `use_cli_local`, pare bloqueado.
+3. Com CLI autorizada, rode `sema resumo`, depois `sema docs-impacto --intencao "<ação declarada>" --json`, leia as docs obrigatórias e só então avance.
+4. Em web/chat/remoto sem workspace local, use MCP remoto: `sema_chat_contexto`, depois `sema_sync` inline com contrato `.sema`, código selecionado, documentação e índice. Use o `projeto` retornado nas chamadas seguintes.
+5. É proibido usar MCP remoto, `sema_sync`, `sema_contratos_sincronizar` ou `sema mcp-client` para ler workspace local quando a CLI estiver operacional.
+6. Antes de criar qualquer módulo, rota, task ou contrato, chame `sema inspecionar` ou `sema_inspecionar` no arquivo `.sema` mais próximo.
+7. Antes de editar código existente, em IDE/local chame `sema drift` e `sema impacto`. Em web/remoto, use `sema_drift` e `sema_impacto` somente sobre o projeto remoto sincronizado.
+8. Ao criar ou editar um arquivo `.sema`, chame `sema validar` ou `sema_validar` ao final.
+9. Nunca invente contratos — use o Sema para descobrir o que já existe.
+10. Se qualquer ferramenta Sema retornar erro, corrija o problema antes de prosseguir — não avance com código enquanto houver erros Sema pendentes.
+11. Contrato vem antes de qualquer ação: crie, edite ou remova o `.sema` aplicável antes de código, deploy, docs operacionais, workflow, texto Author, game, legal, research ou ops.
+
+## MCP
+
+O servidor MCP do Sema e uma superficie privada/comercial acessada por endpoint remoto autorizado; ele nao e instalado pelo pacote npm do instalador neste repositorio.
+Use as ferramentas quando o endpoint privado estiver configurado: sema_resumo, sema_validar, sema_drift, sema_impacto, sema_renomear_semantico, sema_inspecionar, sema_ir, sema_verificar, sema_contexto_ia, sema_prompt_ia, sema_author_iniciar, sema_author_validar, sema_author_briefing, sema_author_revisar_cliches, sema_sync_ai_entrypoints, sema_exemplos, sema_instalar_exemplos, sema_docs_impacto, sema_finalizar_mudanca.
+
+Em IDE/local, a superfície principal é a Sema CLI. A IA deve provar a CLI com `sema --version`; se falhar, deve parar. A IA não acessa o painel Sema: peça ao humano para instalar pelo painel. A CLI deve ter `SEMA_CLI_AUTH_TOKEN` e deve chamar `sema preflight <comando> --json` antes de operar. Se `decisao` não for `use_cli_local`, pare. Não use MCP remoto, `sema_sync`, `sema_contratos_sincronizar` nem `sema mcp-client` para ler workspace local quando a CLI estiver operacional.
+
+Em web/chat/remoto sem workspace local, use MCP remoto: `sema_chat_contexto`, depois `sema_sync` inline com contrato, código selecionado, documentação e índice, e então use o `projeto` retornado.
+
+O MCP deve deixar claro em toda orientacao: se nao existe contrato, crie; se a intencao mudou, edite; se a capacidade saiu, remova ou aposente. Isso vale para todo tipo de Sema: Software, Author, Workflow, Ops, Game, Legal, Research e profiles futuros.
+
+## Plataformas e Interfaces
+
+### IDEs locais (Codex, Roo Code, VS Code, Cursor, Windsurf, etc.)
+Quando houver workspace local:
+1. Rode `sema --version`; se falhar, pare. A IA não acessa o painel Sema: peça ao humano para abrir o painel, baixar/rodar o instalador de chave e repetir `sema --version`.
+2. Rode `sema preflight resumo --json`; se `decisao` não for `use_cli_local`, pare.
+3. Rode `sema resumo` para entender o estado atual.
+4. **ANTES DE QUALQUER AÇÃO**: rode `sema docs-impacto --intencao "<acao>" --json`.
+5. Leia as docs obrigatórias antes de agir.
+6. Rode `sema inspecionar`, `sema drift` e `sema impacto` antes de editar.
+7. Use `sema finalizar-mudanca` para comprovar que leu as docs.
+
+### Web / Chat (ChatGPT, Lovable, etc.)
+Quando usar Sema via MCP remoto sem workspace local:
+1. Chame `sema_chat_contexto` para confirmar conexão e orientação.
+2. **ANTES DE QUALQUER AÇÃO**: declare sua intenção ao usuário.
+3. Chame `sema_sync` com contrato `.sema`, código selecionado, documentação e índice.
+4. Use obrigatoriamente o `projeto` retornado por `sema_sync`.
+5. Chame `sema_resumo`, `sema_docs_impacto`, `sema_inspecionar`, `sema_drift` e `sema_impacto` usando esse `projeto`.
+6. Leia as docs antes de agir e finalize com `sema_finalizar_mudanca`.
+
+### CLI / Terminal
+Quando usar Sema via CLI:
+1. Execute `sema preflight <comando> --json` antes de operar; se bloquear, pare.
+2. Execute `sema resumo` para entender o estado atual.
+3. Execute `sema docs-impacto` antes de qualquer ação.
+4. Leia as docs recomendadas antes de editar/criar/deletar.
+5. Execute `sema finalizar-mudanca` ao concluir.
+
+## Contratos e exemplos
+
+- Sempre salve arquivos .sema na pasta `contratos/` do projeto.
+- Crie um arquivo .sema por modulo ou contexto de negocio. Exemplo: `contratos/pedido.sema`, `contratos/pagamento.sema`, `contratos/usuario.sema`. Nunca coloque modulos de contextos diferentes no mesmo arquivo.
+- Antes de criar qualquer arquivo .sema, leia os exemplos oficiais para entender o formato correto da linguagem.
+- Em MCP remoto/cliente web, use `sema_exemplos` para listar ou ler exemplos oficiais. Nao peca para o MCP ler `C:\GitHub\Sema\exemplos` nem qualquer pasta local do usuario.
+- Em CLI/local repo, a pasta `exemplos/` pode ser lida ou materializada localmente quando necessario.
+- Nunca edite os arquivos da pasta `exemplos/`.
+
+## Quando o projeto nao tem .sema
+
+Pergunte ao usuario se deseja semantizar o projeto e sugira: sema iniciar
+
+## Exemplos de arquivos .sema (referencia de formato)
+
+### 1. Task simples com testes
+```
+module exemplos.calculadora {
+  task somar {
+    input {
+      a: Numero required
+      b: Numero required
+    }
+    output {
+      resultado: Numero
+    }
+    rules {
+      a deve_ser numero_valido
+      b deve_ser numero_valido
+    }
+    effects {
+      auditoria operacao soma
+    }
+    guarantees {
+      resultado existe
+    }
+    error {
+      entrada_invalida: "Os valores precisam ser numericos."
+    }
+    tests {
+      caso "soma basica" {
+        given { a: 2  b: 3 }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+}
+```
+
+### 2. Entity + CRUD com route
+```
+module exemplos.crud.simples {
+  entity Produto {
+    fields {
+      id: Id
+      nome: Texto
+      preco: Decimal
+      ativo: Booleano
+    }
+  }
+
+  task criar_produto {
+    input {
+      nome: Texto required
+      preco: Decimal required
+    }
+    output {
+      produto: Produto
+    }
+    rules {
+      nome deve_ser preenchido
+      preco deve_ser positivo
+    }
+    effects {
+      persistencia Produto
+      auditoria produto_criado
+    }
+    guarantees {
+      produto existe
+    }
+    tests {
+      caso "cria produto" {
+        given { nome: "Caneca"  preco: 39.9 }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+
+  route produtos {
+    metodo: POST
+    caminho: /produtos
+    task: criar_produto
+    finalidade: cadastro_produto
+    input { nome: Texto  preco: Decimal }
+    output { produto: Produto }
+  }
+}
+```
+
+### 3. Cadastro com validacoes e unicidade
+```
+module exemplos.cadastro.usuario {
+  entity Usuario {
+    fields {
+      id: Id
+      nome: Texto
+      email: Email
+      ativo: Booleano
+    }
+  }
+
+  task criar_usuario {
+    input {
+      nome: Texto required
+      email: Email required
+    }
+    output {
+      usuario: Usuario
+    }
+    rules {
+      nome deve_ser preenchido
+      email deve_ser email_valido
+      email deve_ser unico em Usuario.email
+    }
+    effects {
+      persistencia Usuario
+      evento usuario_criado
+      auditoria cadastro_usuario
+    }
+    guarantees {
+      usuario existe
+      persistencia concluida
+    }
+    error {
+      email_duplicado: "Ja existe usuario com este email."
+      entrada_invalida: "Os dados informados nao atendem as regras."
+    }
+    tests {
+      caso "cria usuario valido" {
+        given { nome: "Ana"  email: "ana@empresa.com" }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+}
+```
+
+### 4. Pagamento com state e flow
+```
+module exemplos.pagamento {
+  task processar_pagamento {
+    input {
+      pagamento_id: Id required
+      valor: Decimal required
+      token: Texto required
+    }
+    output {
+      pagamento: Pagamento
+      status: StatusPagamento
+    }
+    rules {
+      valor > 0
+      token deve_ser valido
+    }
+    effects {
+      consulta gateway_pagamento criticidade = alta
+      persistencia Pagamento criticidade = alta
+      evento pagamento_autorizado criticidade = media
+      auditoria pagamento criticidade = alta
+    }
+    state ciclo_pagamento {
+      transitions {
+        PENDENTE -> AUTORIZADO
+        AUTORIZADO -> PROCESSADO
+      }
+    }
+    guarantees {
+      pagamento existe
+      status em [AUTORIZADO, PROCESSADO]
+    }
+    error {
+      autorizacao_negada: "Recusado pelo gateway."
+      timeout_gateway: "Gateway nao respondeu."
+    }
+    tests {
+      caso "pagamento autorizado" {
+        given { pagamento_id: "pag_1"  valor: 199.9  token: "tok_ok" }
+        expect { sucesso: verdadeiro }
+      }
+      caso "pagamento recusado" {
+        given { pagamento_id: "pag_err"  valor: 10  token: "tok_recusado" }
+        expect { sucesso: falso }
+        error { tipo: "autorizacao_negada" }
+      }
+    }
+  }
+
+  flow orquestracao_pagamento {
+    pagamento_id: Id
+    valor: Decimal
+    token: Texto
+    etapa autorizar usa processar_pagamento com pagamento_id = pagamento_id, valor = valor, token = token em_sucesso confirmar em_erro registrar_falha
+    etapa confirmar usa confirmar_pagamento com pagamento_id = pagamento_id depende_de autorizar
+    etapa registrar_falha usa registrar_timeout_pagamento com pagamento_id = pagamento_id depende_de autorizar
+  }
+}
+```
+
+### 5. Tratamento de erro com flow ramificado
+```
+module exemplos.tratamento.erro {
+  task executar_operacao_sensivel {
+    input {
+      chave: Texto required
+    }
+    output {
+      protocolo: Id
+    }
+    rules {
+      chave deve_ser preenchida
+    }
+    effects {
+      consulta cofre
+      auditoria falha_operacao_sensivel
+    }
+    guarantees {
+      protocolo existe
+    }
+    error {
+      acesso_negado: "A chave nao tem permissao."
+      recurso_indisponivel: "Servico temporariamente indisponivel."
+    }
+    tests {
+      caso "falha por acesso negado" {
+        given { chave: "sem_permissao" }
+        expect { sucesso: falso }
+        error { tipo: "acesso_negado" }
+      }
+    }
+  }
+
+  flow resposta_segura {
+    chave: Texto
+    etapa tentar usa executar_operacao_sensivel com chave = chave em_sucesso concluir em_erro registrar_falha por_erro acesso_negado = tratar_acesso_negado, recurso_indisponivel = agendar_retentativa
+    etapa tratar_acesso_negado usa responder_acesso_negado com chave = chave depende_de tentar
+    etapa agendar_retentativa usa responder_retentativa com chave = chave depende_de tentar
+    etapa registrar_falha usa registrar_auditoria_falha com chave = chave depende_de tentar
+    etapa concluir usa registrar_sucesso com protocolo = tentar.protocolo depende_de tentar
+  }
+}
+```