@semacode/cli 1.5.46 → 1.5.48

package/AGENTS.md

@@ -1,324 +1,81 @@
-# 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:agent-entrypoint:start -->
+# Sema para agente
+
+Este workspace é governado por Sema. Antes de qualquer ação em código, contrato, documentação operacional, workflow, profile ou deploy:
+
+1. Leia `SEMA_BOOT.md`.
+2. Em IDE local, rode `sema --version`; se falhar, pare. A IA não acessa o painel Sema: peça ao humano para instalar a CLI pelo painel. Depois rode `sema preflight resumo --json`; se `decisao` não for `use_cli_local`, pare.
+3. Use CLI local: `sema resumo`, `sema docs-impacto`, `sema inspecionar`, `sema drift` e `sema impacto`.
+4. Não use rota remota, sincronização externa ou leitura por espelho para substituir a CLI local quando a CLI estiver operacional.
+5. Chame docs-impacto com a intenção declarada antes de agir.
+6. Chame inspecionar no contrato `.sema` aplicável.
+7. Antes de editar código existente, rode drift e impacto.
+8. Antes de criar ou editar `.sema`, use exemplos oficiais.
+9. Ao concluir mudança de contrato, rode validar.
+10. Antes de finalizar, use finalizar-mudanca com as docs lidas.
+
+É proibido substituir esse fluxo por leitura manual de `AGENTS.md`, `README.md`, busca local por arquivos, inferência pelo nome do projeto, bom senso ou ferramenta não citada nesta lista.
+
+Capacidade padrão deste cliente: media.
+Ordem de leitura: SEMA_BOOT.md -> agent-context-pack.json -> resumo.curto.txt -> briefing.min.json -> drift.json -> resumo.md.
+
+Políticas da plataforma:
+- O Sema governa contrato, escopo, drift, evidência e qualidade do projeto. Ele não pede, não autoriza e não contorna políticas da plataforma, termos de uso, permissões, segurança ou leis.
+- Capacidade media: Separe bloqueio da plataforma de erro do Sema. Reformule em linguagem neutra quando permitido e mantenha os gates; não tente contornar filtro.
+- Se houver alerta externo: Se um cliente, modelo ou classificador bloquear a mensagem, trate como bloqueio externo ou falso positivo possível: explique de forma neutra, preserve a intenção legítima de governança e não tente burlar filtros.
+
+Falha fechada:
+- Se não conseguir chamar Sema, pare e declare bloqueio em vez de editar código ou contrato.
+- Se não houver contrato aplicável ou vínculo semântico do arquivo, inspecione o arquivo, descubra ou crie o .sema aplicável e vincule antes do código.
+- Em IDE local, rode sema --version; se falhar, pare. A IA não acessa o painel Sema: peça ao humano para instalar a CLI pelo painel. Depois rode sema preflight <comando> --json; só continue com use_cli_local; não use rota remota, sincronização externa ou leitura por espelho para workspace local.
+- Se não houver workspace local em disco, pare bloqueado e peça o fluxo apropriado; não invente caminho nem substitua a CLI local por ferramenta paralela.
+- Se arquivos_codigo.conteudo ou conteudo inline passar de 262144 caracteres, não aumente timeout para forçar: divida por responsabilidade ou use anexo/caminho de servidor autorizado.
+- Se for criar ou corrigir .sema, use sema_exemplos antes de escrever sintaxe.
+- Se a resposta humana estiver em PT-BR, use vocabulário Sema canônico e preserve acentos mesmo que a DSL use ASCII.
+- Se um arquivo de código tiver SEMA-GOVERNED, consulte Sema e o contrato aplicável antes de editar.
+- Se codigo governado passar de 1000 linhas, planeje divisao; se passar de 2000, pare e divida antes de concluir. Documentacao Markdown nao entra nesse limite de codigo.
+- Se contrato .sema passar de 300 linhas, planeje split por dominio/capacidade; acima de 500, criacao e edicao ficam bloqueadas. Nao use parte_1/parte_2 e nao remova guarantees, tests ou vinculos so para caber.
+- Um mesmo arquivo de codigo pode ser governado por varios contratos .sema via vinculos; Sema Codigo deve preservar essa rastreabilidade.
+- Se score, achados ou decisaoAgente parecerem bons, trate como sinal de triagem e confira evidência concreta no contrato e no código.
+- Se validar artefato inline com 100/100, ainda preserve cabeçalho SEMA-GOVERNED no arquivo físico sincronizado.
+- Se `sema drift` retornar sucesso:false, `vinculos_quebrados`, `rotas_divergentes` ou impls quebradas, a mudanca nao pode ser declarada concluida; corrija contrato/codigo e rode drift de novo.
+- Se a tarefa tiver site, sistema, app, UI, painel, jogo, CLI/TUI ou terminal, nao conclua sem acabamento moderno, contextual e evidenciado; em UI mobile estreita (ex. 390px), `document.documentElement.scrollWidth <= document.documentElement.clientWidth` precisa ser verdadeiro.
+- Se texto visivel PT-BR perder acento ou cedilha em termos como descricao, lancamentos, saude ou alimentacao, trate como defeito bloqueante quando houver i18n/idioma declarado.
+- Se aparecer caminho de servidor como /srv/sema/projetos, trate como espelho governado, não como pasta local do usuário.
+- Se uma chamada Sema estourar por timeout local, aumente o timeout e tente de novo; timeout do agente não libera ação sem Sema.
+- Se a plataforma bloquear ou alertar política, trate como bloqueio externo ou falso positivo possível; explique sem tentar contornar filtro.
+- Se a tarefa tiver experiência de uso e você não conseguir garantir padrão moderno, contextual e não genérico, pare e peça revisão em vez de entregar coisa engessada.
+
+Timeout:
+- Timeout local do agente não é falha do Sema.
+- Se uma chamada Sema estourar, aumente o timeout e tente de novo antes de declarar bloqueio.
+- Para projeto inteiro, comece com 120s ou mais; se for lento, escale 120s -> 300s -> 600s.
+- Se possível, reduza escopo para `sema resumo <arquivo.sema> --micro --para mudanca`.
+
+Código governado:
+- Mantenha o marcador `SEMA-GOVERNED` em código gerado ou governado.
+- Ao encontrar esse marcador, volte ao contrato .sema aplicável e chame Sema antes de editar.
+- Comentário de código é lembrete curto; não substitui drift, docs-impacto nem finalizar-mudanca.
+- Validação inline prova o payload enviado; não dispensa o marcador no arquivo físico sincronizado.
+- Payload inline acima de 262144 caracteres não deve virar retry de timeout: modularize por responsabilidade ou use anexo/caminho de servidor autorizado.
+- Se um arquivo crescer, divida por responsabilidade real. Em web: `index.html`, `styles/*.css`, `js/state.js`, `js/calc.js`, `js/render/*.js`, `data/*.json`. Não fatie em p1/p2 sem fronteira semântica.
+
+Sinal e evidência:
+- Score composto, `achados[]` e `decisaoAgente` orientam a ação; abaixo de 80 bloqueia, alvo evolui 0.5 ponto até 100, e nada substitui evidência concreta.
+- Palavra-chave ou regex passando não prova governança se contrato, código e comportamento não batem.
+- `sema drift --json` com `sucesso:false`, `vinculos_quebrados`, `rotas_divergentes` ou impls quebradas bloqueia fechamento. Não diga "drift limpo" até rodar de novo e ficar verde.
+- Caminho de servidor ou espelho governado do Sema não é pasta local do usuário.
+
+Acabamento visual e terminal:
+- Se houver site, sistema, app, UI, painel, jogo, CLI/TUI ou terminal, acabamento moderno, contextual e não genérico é requisito governado, não enfeite.
+- Capacidade media: Defina intenção de experiência antes de codar: público, domínio, workflow real, densidade, tokens, componentes, tecnologia/biblioteca/efeitos adequados, estados, responsividade e anti-2010. O domínio manda na solução: agro, finanças, saúde, game e e-commerce não podem compartilhar a mesma casca. Rode ou peça screenshot/browser check quando houver UI e smoke check quando for terminal.
+- Evidências: registrar tokens e componentes usados, registrar bibliotecas, APIs ou efeitos escolhidos e por que combinam com o pedido, validar desktop e mobile, testar viewport estreito como 390px sem scroll horizontal, corrigir texto sobreposto, rodar smoke check de CLI/TUI quando aplicável.
+- Responsividade/ergonomia real: valide desktop/mobile e, em viewport estreito como 390px, confirme `document.documentElement.scrollWidth <= document.documentElement.clientWidth`; em terminal/CLI/TUI, rode smoke check de saída, erro e ajuda quando aplicável.
+- Proibido: interface_generica_2010, formularios_sem_hierarquia_visual, cards_cinzas_sem_identidade, layout_sem_responsividade_real, texto_estourando_ou_sobreposto.
+
+Idioma:
+- Responda no idioma do usuário.
+- Em PT-BR, use vocabulário Sema canônico, acentos, cedilha, pontuação e símbolos normais.
+- A DSL `.sema` pode ser ASCII; texto humano não precisa ser.
+- Não traduza comandos, rotas, arquivos, endpoints, variáveis, pacotes, marcas, símbolos de código nem palavras-chave da DSL.
+<!-- sema:agent-entrypoint:end -->