@semacode/cli 1.3.2 → 1.3.6

package/docs/integracao-com-ia.md

@@ -1,228 +0,0 @@
-# Integracao com IA
-
-A Sema foi desenhada para IA editar backend vivo com menos chute. O ponto nao e "a IA gera tudo"; o ponto e deixar contrato, vinculo e contexto operacional estruturados o bastante para a IA nao trabalhar igual um bicho tonto. Leitura humana continua possivel, mas nao e o centro do desenho.
-
-## Moldura correta
-
-Se uma IA tratar a Sema como enfeite declarativo, ela vai usar mal. A moldura certa e esta:
-
-- `impl` liga intencao a simbolo executavel
-- `vinculos` ligam contrato a arquivo, simbolo, recurso e superficie real
-- `execucao` explicita timeout, retry, compensacao e criticidade
-- `drift` mede verdade contra codigo vivo
-- `contexto-ia` empacota briefing operacional antes da edicao
-
-Em resumo: a Sema nao serve para a IA adivinhar melhor. Ela serve para a IA precisar adivinhar menos.
-
-## Fluxo recomendado
-
-Quando o trabalho cair em projeto vivo, o fluxo canonico agora e:
-
-```bash
-sema inspecionar . --json
-sema resumo contratos/modulo.sema --micro --para mudanca
-sema drift contratos/modulo.sema --json
-sema contexto-ia contratos/modulo.sema --saida ./.tmp/contexto --json
-```
-
-Leitura rapida:
-
-1. `inspecionar` descobre base do projeto, diretorios de codigo, fontes legado e modulos relevantes.
-2. `resumo` entrega o menor cartao semantico util para a IA atual.
-3. `drift` mede impls, vinculos, rotas, recursos, score semantico e confianca.
-4. `contexto-ia` gera o pacote que a IA deveria ler antes de editar.
-
-## Capacidade da IA
-
-A Sema agora assume explicitamente que nem toda IA aguenta o pacote completo.
-
-- IA pequena ou gratuita: comece em `resumo.micro.txt`, `briefing.min.json` e `prompt-curto.txt`
-- IA media: suba para `resumo.curto.txt`, `briefing.min.json` e `drift.json`
-- IA grande ou com tool use: leia `README.md`, `resumo.md`, `briefing.json`, `drift.json`, `ir.json` e `ast.json`
-
-Se voce joga `ast.json` inteiro em modelo pequeno e depois reclama da resposta, foi voce que fez cagada operacional.
-
-## O que a IA deve consumir
-
-No minimo, para IA pequena:
-
-- `resumo.micro.txt`
-- `briefing.min.json`
-
-No minimo, para IA media:
-
-- `resumo.curto.txt`
-- `briefing.min.json`
-- `drift.json`
-
-No minimo, para IA grande:
-
-- `ir.json`
-- `drift.json`
-- `briefing.json`
-- o proprio contrato `.sema`
-
-O `briefing.json` agora e a peca mais operacional do pacote. Ele responde perguntas que agente serio precisa responder antes de mexer em codigo:
-
-- o que tocar
-- o que validar
-- o que esta frouxo
-- o que foi inferido
-- quais simbolos estao relacionados
-- quais superficies publicas podem ser afetadas
-- quais testes minimos rodar
-
-## Saida relevante do pacote `contexto-ia`
-
-Hoje o pacote pode incluir:
-
-- `resumo.micro.txt`
-- `resumo.curto.txt`
-- `resumo.md`
-- `briefing.min.json`
-- `prompt-curto.txt`
-- `ast.json`
-- `ir.json`
-- `diagnosticos.json`
-- `drift.json`
-- `briefing.json`
-- `README.md`
-- `impl.<origem>.txt` quando existir implementacao vinculada
-
-## Score, confianca e risco
-
-`drift`, `inspecionar` e `contexto-ia` passam a expor sinais que ajudam a IA a nao tratar rascunho como verdade absoluta:
-
-- `scoreSemantico`
-- `confiancaVinculo`
-- `riscoOperacional`
-- `lacunas`
-- `vinculos_validos`
-- `vinculos_quebrados`
-
-Leitura pratica:
-
-- score alto + confianca alta: a IA pode editar com trilha boa
-- score medio: ainda precisa ler contrato e conferir codigo vivo
-- vinculo quebrado: a IA deve reduzir ousadia e consertar rastreabilidade antes de refatorar igual doida
-
-## Superficies que a IA pode esperar
-
-A linguagem agora trata estas bordas como primeira classe:
-
-- `route`
-- `worker`
-- `evento`
-- `fila`
-- `cron`
-- `webhook`
-- `cache`
-- `storage`
-- `policy`
-
-Isso importa porque backend real nao vive so de HTTP. Se a IA vai editar stack viva, ela precisa enxergar job, evento, webhook e recurso assincrono como parte do contrato, nao como sobra esquecida no runtime.
-
-## Contrato operacional
-
-Dentro de `task` e superficies, a IA deve prestar atencao em:
-
-- `input`
-- `output`
-- `effects`
-- `impl`
-- `vinculos`
-- `execucao`
-- `guarantees`
-- `error`
-
-Exemplo minimo:
-
-```sema
-task medir_drift {
-  input {
-    contrato: Texto required
-  }
-  output {
-    score: Decimal
-  }
-  impl {
-    ts: cli.src.drift.analisarDriftLegado
-  }
-  vinculos {
-    arquivo: "pacotes/cli/src/drift.ts"
-    simbolo: cli.src.drift.analisarDriftLegado
-  }
-  execucao {
-    timeout: "30s"
-    retry: "3x exponencial"
-    criticidade_operacional: alta
-  }
-  guarantees {
-    score existe
-  }
-}
-```
-
-## Comandos que agente serio nao deveria ignorar
-
-- `sema ast arquivo.sema --json`
-- `sema ir arquivo.sema --json`
-- `sema validar arquivo.sema --json`
-- `sema diagnosticos arquivo.sema --json`
-- `sema formatar arquivo.sema`
-- `sema inspecionar [arquivo-ou-pasta] --json`
-- `sema drift [arquivo-ou-pasta] --json`
-- `sema contexto-ia arquivo.sema [--saida <diretorio>] --json`
-- `sema verificar [arquivo-ou-pasta] --json`
-
-## Fluxos comuns
-
-Quando a tarefa for so modelagem:
-
-```bash
-sema ast contratos/pedidos.sema --json
-sema ir contratos/pedidos.sema --json
-sema formatar contratos/pedidos.sema
-sema validar contratos/pedidos.sema --json
-```
-
-Quando a tarefa envolver codigo derivado:
-
-```bash
-sema inspecionar . --json
-sema drift contratos/pedidos.sema --json
-sema contexto-ia contratos/pedidos.sema --saida ./.tmp/contexto-pedidos --json
-sema compilar contratos/pedidos.sema --alvo typescript --framework nestjs --estrutura backend --saida ./generated/nestjs
-```
-
-Quando a tarefa nasce num legado:
-
-```bash
-sema importar flask ./backend-flask --saida ./sema/importado --json
-sema formatar ./sema/importado
-sema validar ./sema/importado --json
-sema drift ./sema/importado --json
-```
-
-## Showcase oficial do repo
-
-Se voce estiver no monorepo da Sema, o showcase [showcases/ranking-showroom](../showcases/ranking-showroom/) continua sendo a melhor vitrine do fluxo completo:
-
-```bash
-cd showcases/ranking-showroom
-sema inspecionar . --json
-sema drift contratos/ranking_showroom.sema --json
-sema contexto-ia contratos/ranking_showroom.sema --saida ./.tmp/contexto-ranking --json
-```
-
-O valor aqui nao e so "validou". O valor e sair com score, confianca, drift e briefing suficientes para editar o backend Flask real sem sair cavando arquivo a esmo.
-
-## Fechamento operacional
-
-Quando a IA terminar a mudanca fora do monorepo:
-
-```bash
-sema formatar contratos/modulo.sema
-sema validar contratos/modulo.sema --json
-sema verificar contratos --json --saida ./.tmp/verificacao-final
-```

package/docs/pagamento-ponta-a-ponta.md

@@ -1,155 +0,0 @@
-# Pagamento Ponta a Ponta na Sema
-
-Este documento descreve o vertical oficial de pagamento da Sema no fluxo publico atual.
-
-O objetivo nao e mostrar um exemplo fofo. O objetivo e demonstrar que a linguagem ja consegue modelar um fluxo de negocio real com:
-
-- contrato publico
-- regras
-- efeitos operacionais
-- transicoes de estado
-- orquestracao
-- erros publicos
-- testes executaveis
-
-## Arquivos de referencia
-
-- `exemplos/pagamento_dominio.sema`
-- `exemplos/pagamento.sema`
-
-## Como o vertical foi dividido
-
-### `exemplos.pagamento.dominio`
-
-Centraliza os contratos compartilhados:
-
-- `entity Pagamento`
-- `enum StatusPagamento`
-- `state ciclo_pagamento`
-
-### `exemplos.pagamento`
-
-Centraliza a operacao do vertical:
-
-- `task processar_pagamento`
-- `task confirmar_pagamento`
-- `task notificar_falha_pagamento`
-- `task registrar_timeout_pagamento`
-- `flow orquestracao_pagamento`
-- `route processar_pagamento_publico`
-
-## Narrativa do caso
-
-### Entrada publica
-
-A operacao entra por:
-
-- `route processar_pagamento_publico`
-
-Esse contrato publica:
-
-- `pagamento_id`
-- `valor`
-- `token`
-
-E expoe:
-
-- `pagamento`
-- `status`
-- erros publicos coerentes com a `task`
-
-### Task interna
-
-A `task processar_pagamento` faz o trabalho central:
-
-- valida entrada
-- consulta o gateway
-- persiste o pagamento
-- emite evento
-- notifica comprovante
-- registra auditoria
-- garante consistencia da saida
-
-### Estado e transicoes
-
-O `state ciclo_pagamento` ancora o contrato de transicao:
-
-- `PENDENTE -> AUTORIZADO`
-- `AUTORIZADO -> PROCESSADO`
-- `PENDENTE -> RECUSADO`
-
-A `task` explicita quais transicoes ela realmente usa.
-
-### Flow de orquestracao
-
-O `flow orquestracao_pagamento` demonstra:
-
-- passagem de contexto
-- confirmacao em caso de sucesso
-- notificacao em caso de recusa
-- registro de timeout em caso de indisponibilidade
-- ramificacao por erro tipado
-
-### Efeitos operacionais
-
-O vertical usa as 5 categorias oficiais da Sema:
-
-- `persistencia`
-- `consulta`
-- `evento`
-- `notificacao`
-- `auditoria`
-
-Tambem usa `criticidade` para deixar claro o peso operacional do efeito.
-
-### Falhas reais
-
-O vertical cobre explicitamente:
-
-- autorizacao negada
-- saldo insuficiente
-- timeout de gateway
-
-## Fluxo de trabalho recomendado
-
-### 1. Escrever ou ajustar os arquivos `.sema`
-
-Use o dominio compartilhado em um modulo e a operacao em outro modulo.
-
-### 2. Aplicar o formato canonico
-
-```bash
-sema formatar exemplos
-```
-
-### 3. Validar semanticamente
-
-```bash
-sema validar exemplos/pagamento.sema
-```
-
-### 4. Gerar codigo
-
-```bash
-sema compilar exemplos/pagamento.sema --alvo typescript --saida ./.tmp/pagamento-ts
-sema compilar exemplos/pagamento.sema --alvo python --saida ./.tmp/pagamento-py
-```
-
-### 5. Verificar o vertical completo
-
-```bash
-sema verificar exemplos/pagamento.sema --json --saida ./.tmp/verificacao-pagamento
-```
-
-## O que esse vertical prova
-
-Se esse vertical passa, a Sema ja consegue demonstrar que:
-
-- modela contrato publico
-- modela efeitos operacionais
-- modela falhas reais
-- modulariza dominio com `use`
-- gera artefatos coerentes para TypeScript e Python
-- executa testes gerados sem gambiarra conceitual
-
-Esse e o criterio pratico que sustenta o uso publico do vertical de pagamento como referencia para IA e geracao.

package/docs/prompt-base-ia-sema.md

@@ -1,104 +0,0 @@
-# Prompt-Base Oficial para IA Trabalhar com Sema
-
-Este arquivo serve como prompt-base oficial para qualquer IA que precise ler, escrever, revisar ou transformar arquivos `.sema`.
-
-O objetivo nao e fazer a IA "improvisar bonito". O objetivo e fazer a IA operar a linguagem com previsibilidade. A Sema nao foi desenhada para ergonomia humana como prioridade; ela foi desenhada para IA.
-
-## Prompt-base
-
-Use o texto abaixo como base:
-
-```text
-Voce esta trabalhando com Sema, um Protocolo de Governanca de Intencao para IA e backend vivo.
-
-Tecnicamente, a Sema funciona como linguagem de intencao orientada a contrato. Operacionalmente, ela existe para governar semantica acima da stack e reduzir ambiguidade para IA, nao para substituir arquitetura, design ou curadoria humana.
-
-Trate a Sema como linguagem de especificacao executavel e protocolo de governanca semantica. Nao invente sintaxe, palavras-chave ou blocos fora da gramatica e dos exemplos oficiais.
-
-Fontes de verdade, em ordem:
-1. se o projeto expuser `SEMA_CONTEXT.md`, comece por ele
-2. `SEMA_BRIEF.md`
-3. `SEMA_INDEX.json`
-4. README do projeto
-5. gramatica e documentacao de sintaxe da Sema
-6. especificacao semantica da linguagem
-7. exemplos oficiais, com prioridade para o vertical de pagamento
-8. `sema resumo` e `briefing.min.json` quando a IA for pequena
-9. AST, IR e diagnosticos exportados pela CLI em JSON quando a capacidade aguentar
-
-Regras de operacao:
-- preserve o significado semantico
-- use o formatador oficial da Sema como fonte unica de estilo
-- use diagnosticos estruturados como contrato de correcao
-- use a IR como fonte de verdade semantica quando houver duvida
-- nao conclua uma alteracao sem validar e verificar o modulo
-- trate `importar` como bootstrap revisavel, nao como contrato final automatico
-- trate `drift` como medicao de verdade contra codigo vivo
-- trate `impl` como ponte entre task e simbolo real
-- nao invente regra de negocio que o contrato e o codigo nao sustentem
-
-Antes de editar `.sema`, entenda:
-- o module alvo
-- os contratos de task, route, error, effects, guarantees, state e flow
-- os exemplos oficiais relacionados
-
-Depois de editar `.sema`, execute este fluxo:
-1. formatar
-2. validar
-3. diagnosticar, se houver falha
-4. verificar
-
-Se houver conflito entre texto livre e IR/diagnosticos, priorize a IR e os diagnosticos da CLI.
-
-Se algo nao estiver claro, siga a forma ja usada nos exemplos oficiais. Nao improvise sem base.
-```
-
-## Variacao curta
-
-Se voce quiser um prompt menor para uso frequente:
-
-```text
-Trabalhe com Sema como DSL semantica orientada a contrato. Nao invente sintaxe. Use os exemplos oficiais e a gramatica como referencia de escrita. Use `ir --json` como fonte de verdade semantica, `diagnosticos --json` como fonte de correcao e `sema formatar` como fonte unica de estilo. Antes de encerrar, rode validacao e verificacao.
-```
-
-Se voce quiser um prompt ainda mais curto e pronto para colar, use:
-
-```bash
-sema prompt-curto caminho/arquivo.sema --curto --para mudanca
-```
-
-## Variacao para revisao
-
-Use esta versao quando a IA for revisar `.sema` em vez de criar:
-
-```text
-Revise este modulo Sema como contrato semantico executavel. Procure incoerencias entre input, output, rules, effects, guarantees, state, flow, route e error. Considere a IR e os diagnosticos da CLI como fonte de verdade. Nao critique estilo fora do que o formatador oficial resolveria automaticamente.
-```
-
-## Variacao para geracao
-
-Use esta versao quando a IA for escrever modulo novo:
-
-```text
-Gere um modulo Sema seguindo a gramatica oficial, os exemplos do projeto e o estilo do formatador canonico. Estruture o modulo como contrato semantico executavel, com blocos explicitos para entrada, saida, regras, efeitos, garantias, erros, estado, fluxo e testes quando fizer sentido. Nao use sintaxe fora do repertorio ja suportado pela linguagem.
-```
-
-## Variacao para correcao guiada por diagnostico
-
-Use esta versao quando a IA ja tiver erro concreto para corrigir:
-
-```text
-Corrija este modulo Sema a partir dos diagnosticos estruturados da CLI. Preserve a intencao do contrato e altere apenas o necessario para eliminar as falhas. Depois da correcao, aplique o formatador oficial e revalide.
-```
-
-## O que sempre anexar junto do prompt
-
-Idealmente, acompanhe o prompt com:
-
-- o arquivo `.sema` alvo
-- o resultado de `sema ast --json`
-- o resultado de `sema ir --json`
-- o resultado de `sema diagnosticos --json`, se houver erro
-- um exemplo oficial parecido
-
-Sem isso, a IA pode ate acertar. Com isso, ela trabalha direito.