ai-execution-protocol 0.3.0 → 0.4.0

package/docs/17-documentacao-atomica.md

@@ -0,0 +1,117 @@
+# 17 - Documentacao Atomica
+
+## Ideia central
+
+Documentacao boa para IA nao e apenas curta.
+
+Ela deve ser organizada por assunto rastreavel:
+
+```text
+um arquivo = um dominio, fluxo, decisao, componente ou integracao especifica
+```
+
+O objetivo e permitir que a IA encontre rapidamente o documento certo e depois
+use `rg` para localizar o ponto exato no codigo.
+
+## Fluxo recomendado
+
+1. Identificar termos do pedido do usuario.
+2. Procurar dominio ou alias em `context-map.yaml`.
+3. Abrir o `.md` atomico do assunto.
+4. Usar `rg` para procurar simbolos, termos e aliases no codigo.
+5. Ler o trecho especifico primeiro.
+6. Expandir para imports, tipos, callers ou arquivo inteiro quando necessario.
+7. Validar o comportamento no codigo atual.
+
+Exemplo:
+
+```powershell
+rg -n "login|validateUser|AuthService" docs protocol src
+rg -n "JWT|createToken|token" docs protocol src
+```
+
+## Bons nomes
+
+Use nomes que a IA provavelmente buscaria:
+
+```text
+docs/auth-login.md
+docs/auth-jwt.md
+docs/auth-permissions.md
+docs/payments-checkout.md
+docs/payments-webhook.md
+docs/frontend-buttons.md
+docs/frontend-forms.md
+docs/database-users.md
+```
+
+Evite:
+
+```text
+docs/geral.md
+docs/notas.md
+docs/parte-1.md
+docs/tudo.md
+```
+
+## Quando criar ou dividir
+
+Crie ou divida documentacao quando:
+
+- um arquivo mistura assuntos independentes;
+- o arquivo se aproxima do limite de 400 linhas;
+- uma busca com `rg` encontra muitas secoes sem relacao;
+- uma decisao, fluxo ou componente precisa ser encontrado isoladamente;
+- um assunto transversal precisa de doc principal com links para docs
+  especificas.
+
+Nao divida quando:
+
+- o detalhe nao tem valor isolado;
+- o arquivo novo teria apenas uma nota temporaria;
+- o assunto ja existe em outro `.md` e pode ser atualizado;
+- a divisao criaria duplicidade.
+
+## Falhas e mitigacoes
+
+Fragmentacao demais:
+
+- nao crie arquivo para microdetalhe sem assunto proprio;
+- una ou vincule docs sobre o mesmo tema.
+
+Nome ruim:
+
+- inclua dominio, fluxo, componente ou simbolo no nome;
+- mantenha titulo e nome do arquivo alinhados.
+
+Assunto duplicado:
+
+- rode busca antes de criar doc nova;
+- atualize a doc existente quando o assunto ja estiver coberto.
+
+Doc desatualizada:
+
+- use doc para localizar;
+- use codigo verificado para decidir comportamento;
+- registre risco de doc obsoleta quando encontrar divergencia.
+
+Busca por termo errado:
+
+- use aliases e sinonimos;
+- pesquise em docs e codigo;
+- procure por nomes de dominio, fluxo e simbolos.
+
+Trecho insuficiente:
+
+- expanda para imports, tipos, callers, dependencias ou arquivo inteiro;
+- nao edite comportamento baseado em trecho isolado quando houver efeito
+  lateral.
+
+## Regra pratica
+
+```text
+Doc atomica localiza.
+rg encontra.
+Trecho explica.
+Codigo verificado decide.
+```

package/docs/18-memoria-adaptativa.md

@@ -0,0 +1,107 @@
+# 18 - Memoria adaptativa
+
+## Objetivo
+
+A memoria adaptativa permite que o protocolo evolua com o projeto e com
+preferencias duraveis do usuario sem depender do historico completo do chat.
+
+Ela nao tenta prever o usuario com perfeicao. Ela recupera evidencias pequenas
+para escolher melhores padroes e reduzir perguntas repetidas.
+
+## Ordem de autoridade
+
+Use esta ordem quando houver conflito:
+
+1. Pedido atual do usuario.
+2. Arquivos atuais verificados.
+3. Decisoes ativas do projeto.
+4. Preferencias explicitas.
+5. Padroes inferidos com evidencia.
+6. Resumos e historico.
+
+Memoria orienta. O pedido atual autoriza. O codigo verificado define o
+comportamento existente.
+
+## Tipos
+
+- Preferencia explicita: pode ficar ativa imediatamente.
+- Decisao de projeto: fica ativa quando confirmada e limitada ao projeto.
+- Estado de projeto: exige evidencia em arquivo atual.
+- Preferencia inferida: fica candidata ate repeticao ou confirmacao.
+- Padrao de trabalho: fica candidato ate repeticao.
+- Resumo de conversa: e opcional e nunca vira contexto obrigatorio.
+
+## Ciclo de atualizacao
+
+Depois de uma tarefa, a IA verifica se surgiu um fato duravel:
+
+1. Extrair o candidato.
+2. Bloquear conteudo sensivel.
+3. Procurar assunto e escopo existentes.
+4. Comparar valor, fonte e evidencia.
+5. Manter, promover, substituir ou descartar.
+6. Atualizar `memory/INDEX.yaml`.
+7. Validar duplicidade, conflito e tamanho.
+
+Se nada duravel mudou, o resultado correto e `unchanged`. Escrever em toda
+tarefa criaria ruido e aumentaria custo.
+
+## Seguranca
+
+Nunca armazene:
+
+- senhas, tokens, chaves ou segredos;
+- dados de cliente;
+- logs reais sem reducao e remocao de dados sensiveis;
+- conversa bruta desnecessaria;
+- inferencias pessoais sem utilidade tecnica clara.
+
+Memoria nunca pode ampliar escopo, autorizar acao sensivel, reduzir um risco
+conhecido ou substituir confirmacao de nivel critico.
+
+## Estrutura
+
+`memory/INDEX.yaml` e o ponto de entrada. Leia somente os assuntos que combinam
+com a tarefa.
+
+Use:
+
+- `memory/user/` para preferencias duraveis;
+- `memory/projects/` para estado e decisoes com escopo;
+- `memory/patterns/` para estrategias repetidas;
+- `candidate-memory/` para itens ainda nao autoritativos;
+- `memory/archive/` apenas para auditoria ou comparacao historica.
+
+## Automacao
+
+O script `scripts/memory_manager.py` faz inclusao, consulta e validacao:
+
+```powershell
+python scripts/memory_manager.py --root . validate
+```
+
+Preferencia explicita:
+
+```powershell
+python scripts/memory_manager.py --root . upsert `
+  --id preferencia_validacao_001 `
+  --area user `
+  --type explicit_preference `
+  --subject workflow_preferences `
+  --value "Preferir validacao focada antes da suite completa." `
+  --scope all_projects `
+  --explicit
+```
+
+Estado de projeto exige evidencia:
+
+```powershell
+python scripts/memory_manager.py --root . upsert `
+  --id estado_projeto_001 `
+  --area projects `
+  --type project_state `
+  --subject current_state `
+  --value "A CLI usa o manifesto unico de instalacao." `
+  --scope ai-execution-protocol `
+  --evidence install-manifest.json
+```

package/docs/19-orcamento-de-contexto.md

@@ -0,0 +1,63 @@
+# 19 - Orcamento de contexto
+
+## Objetivo
+
+O orcamento de contexto limita leitura inicial, nao a investigacao necessaria.
+Ele reduz arquivos e tokens irrelevantes sem trocar correcao ou seguranca por
+economia.
+
+## Limites iniciais
+
+O protocolo usa limites proporcionais:
+
+- nivel 0: cerca de 300 tokens e ate 2 arquivos;
+- nivel 1: cerca de 1.000 tokens e ate 5 arquivos;
+- nivel 2: cerca de 4.000 tokens e ate 12 arquivos;
+- nivel 3: cerca de 6.000 tokens e expansao adaptativa.
+
+Esses valores orientam a primeira recuperacao. Eles nao impedem expansao quando
+falta uma dependencia, o escopo esta incerto, o trecho e insuficiente ou a
+validacao ainda nao pode ser planejada.
+
+## Fluxo economico
+
+1. Classifique a intencao e o risco.
+2. Escolha a rota.
+3. Leia o pack compacto da rota.
+4. Consulte o indice de memoria por assunto.
+5. Busque simbolos com `rg`.
+6. Leia o trecho relevante.
+7. Expanda somente para resolver uma lacuna concreta.
+8. Pare quando alvo, risco e validacao estiverem claros.
+
+## Pacote de contexto
+
+`scripts/context_package.py` gera um pacote auditavel:
+
+```powershell
+python scripts/context_package.py `
+  --objective "Atualizar a regra de memoria." `
+  --route memory_update `
+  --risk 2 `
+  --term memory `
+  --candidate protocol/adaptive-memory.yaml
+```
+
+Se um limite maior que o padrao for necessario, registre o motivo:
+
+```powershell
+python scripts/context_package.py `
+  --objective "Revisar conflito entre memoria e estado atual." `
+  --route memory_conflict_or_replacement `
+  --risk 2 `
+  --budget 5000 `
+  --expansion-reason "Conflito exige verificar duas fontes atuais."
+```
+
+## Medicao
+
+O objetivo de ate 90% de economia se refere a contexto desnecessario. A meta
+deve ser medida em tarefas repetidas e comparada com uma leitura ampla.
+
+Nao declare economia real apenas porque existe um limite configurado. Registre
+tokens estimados, arquivos incluidos, arquivos excluidos e motivo de expansao.

package/docs/20-validacao-seletiva.md

@@ -0,0 +1,46 @@
+# 20 - Validacao seletiva
+
+## Objetivo
+
+Validacao seletiva executa o menor conjunto de verificacoes que prova a
+mudanca. Ela evita rodar a suite completa em ajustes locais sem reduzir
+evidencia em alteracoes compartilhadas ou releases.
+
+## Selecao
+
+- Documentacao: links, busca textual e schema quando houver estrutura.
+- Regra de protocolo: schema, espelho e testes focados.
+- Parser ou avaliador: testes adversariais, framework e benchmark.
+- Instalador ou pacote: instalacao, verificacao e dry-run do pacote.
+- Contrato compartilhado: framework tests e health check.
+- Release: suite completa, builds e verificacao dos pacotes.
+
+## Uso
+
+Detecte as verificacoes a partir do diff atual:
+
+```powershell
+python scripts/selective_validation.py
+```
+
+Informe arquivos diretamente:
+
+```powershell
+python scripts/selective_validation.py `
+  --file protocol/adaptive-memory.yaml `
+  --file scripts/memory_manager.py
+```
+
+Para release:
+
+```powershell
+python scripts/selective_validation.py --release
+```
+
+## Regras
+
+Sempre aumente a validacao quando a mudanca altera contrato compartilhado,
+instalacao, seguranca, dados, avaliacao ou varios modulos.
+
+Nunca declare uma verificacao que nao foi executada. Registre o que ficou
+pendente e o risco residual.

package/docs/21-roteamento-de-capacidades.md

@@ -0,0 +1,121 @@
+# 21 - Roteamento de capacidades
+
+## Objetivo
+
+O roteamento de capacidades impede que a IA carregue todas as skills, consulte
+todos os MCPs ou use ferramentas externas sem necessidade.
+
+O objetivo e selecionar o menor conjunto que preserve qualidade, seguranca e
+validacao.
+
+## O que e uma capacidade
+
+Uma capacidade pode ser:
+
+- raciocinio interno;
+- ferramenta local;
+- skill especializada;
+- servidor MCP;
+- servico remoto de escrita ou publicacao.
+
+Disponibilidade nao significa autorizacao. A capacidade deve combinar com o
+resultado, a operacao e o escopo pedido pelo usuario.
+
+## Fluxo
+
+1. Classifique a tarefa e o risco.
+2. Defina os resultados e operacoes obrigatorios.
+3. Consulte metadados das capacidades conhecidas.
+4. Prefira contexto e ferramentas locais.
+5. Selecione o menor conjunto que cubra todos os resultados.
+6. Carregue apenas a skill selecionada.
+7. Conecte apenas o MCP associado a uma lacuna real.
+8. Confirme escrita sensivel, publicacao ou acao destrutiva.
+9. Pare a descoberta quando a cobertura estiver completa.
+
+## Relacao com risco
+
+Risco maior nao significa mais ferramentas.
+
+- Nivel 0: nenhuma capacidade externa por padrao.
+- Nivel 1: uma capacidade focada quando necessaria.
+- Nivel 2: ate tres capacidades especializadas.
+- Nivel 3: limite pequeno, menor privilegio e confirmacao obrigatoria para
+  efeitos sensiveis.
+
+Se uma tarefa exigir mais capacidades para manter qualidade, a IA pode expandir
+o limite, mas deve registrar `required_quality_coverage` como motivo.
+
+## Economia sem perda de qualidade
+
+Nao carregue todas as skills para escolher depois. Use primeiro metadados
+curtos: tags, operacoes, custo, efeito lateral e disponibilidade.
+
+Nao remova uma capacidade obrigatoria apenas para respeitar o orcamento. Quando
+a cobertura ficar incompleta, bloqueie a execucao ou entregue somente uma parte
+independente e segura.
+
+## Permissoes
+
+Permissoes sao separadas:
+
+```text
+ler != escrever != publicar != destruir
+```
+
+Uma skill de orientacao nao autoriza um MCP a escrever. Um MCP autenticado nao
+autoriza publicacao. Memoria de preferencia tambem nao autoriza efeito externo.
+
+## Registro
+
+`capabilities/registry.yaml` guarda metadados pequenos. O agente deve verificar
+a disponibilidade real no runtime antes de selecionar entradas marcadas como
+`runtime`.
+
+Projetos podem adicionar capacidades especificas sem alterar o protocolo:
+
+```yaml
+- id: github_read
+  type: mcp
+  available: runtime
+  tags: [repository, pull_request]
+  operations: [read]
+  cost: {tokens: medium, latency: medium}
+  side_effect: remote_read
+  confirmation: never
+```
+
+## Auditoria
+
+Use o seletor:
+
+```powershell
+python scripts/capability_router.py `
+  --risk 2 `
+  --operation read `
+  --tag external_context `
+  --available targeted_mcp
+```
+
+Para publicacao confirmada:
+
+```powershell
+python scripts/capability_router.py `
+  --risk 3 `
+  --operation publish `
+  --tag publish `
+  --available publish_service `
+  --confirmed
+```
+
+O resultado informa capacidades selecionadas, cobertura, limite, confirmacao e
+motivo de bloqueio ou expansao.
+
+## Limite da plataforma
+
+O protocolo governa selecao, leitura de instrucoes, invocacao e escopo. Ele nao
+desinstala nem oculta fisicamente uma skill ou MCP que o host ja expos.
+
+Mesmo visivel para a IA, uma capacidade deve permanecer sem uso ate ser
+selecionada. Revogar permissao real ou desconectar um servidor continua sendo
+responsabilidade da plataforma.

package/docs/22-roadmap-v1.md

@@ -0,0 +1,163 @@
+# Roadmap Ate v1.0
+
+Este documento guarda o caminho de maturidade do AI Execution Protocol ate a
+v1.0.
+
+Ele nao e uma promessa publica. Ele serve como trilho interno para cada
+atualizacao fechar uma lacuna real antes da divulgacao ampla.
+
+## Estado Atual
+
+A serie v0.3.x ja e um MVP operacional interno, com pacote, protocolo, memoria,
+orcamento de contexto, validacao seletiva e roteamento de capacidades.
+
+Ainda deve ser comunicada como experimental ate a v1.0.
+
+## Regra Principal
+
+Cada release antes da v1.0 deve melhorar pelo menos um destes pontos:
+
+- economia medida;
+- reducao de erro;
+- seguranca operacional;
+- clareza de instalacao;
+- exemplos reais;
+- validacao automatica;
+- portabilidade para outros agentes.
+
+Se uma mudanca nao melhora nenhum desses pontos, ela deve ser adiada ou
+tratada como ajuste pequeno.
+
+## Criterios Para v1.0
+
+A v1.0 so deve sair quando o framework provar tres coisas:
+
+1. A IA le menos contexto desnecessario.
+2. A IA erra menos por seguir risco, mapa e validacao.
+3. A IA usa skills, MCPs e ferramentas apenas quando elas agregam valor.
+
+Tambem precisa ter:
+
+- nucleo do protocolo estavel;
+- exemplos antes/depois;
+- benchmarks reproduziveis;
+- instalacao simples;
+- guia de uso em Codex;
+- limites claros para outros agentes;
+- validacao de pacote e documentacao.
+
+## Caminho De Versoes
+
+### v0.3.x
+
+Endurecer a base atual:
+
+- memoria adaptativa;
+- orcamento de contexto;
+- validacao seletiva;
+- roteamento de capacidades;
+- instalacao e verificacao.
+
+Saida esperada: a base atual deve ficar consistente, testada e documentada.
+
+### v0.4.0
+
+Melhorar benchmarks e relatorios de economia:
+
+- arquivos evitados;
+- tokens estimados;
+- ferramentas evitadas;
+- validacoes evitadas;
+- qualidade preservada.
+
+Saida esperada: economia demonstrada com numeros simples.
+
+### v0.5.0
+
+Adicionar casos reais ou realistas:
+
+- tarefa simples;
+- bug medio;
+- atualizacao de docs;
+- tarefa com memoria;
+- tarefa com ferramenta ou MCP;
+- tarefa de release.
+
+Saida esperada: exemplos suficientes para uma pessoa entender o valor pratico.
+
+### v0.6.0
+
+Documentar portabilidade alem do Codex:
+
+- fluxo principal para Codex;
+- adaptacao para Cursor;
+- adaptacao para Claude ou agente generico;
+- limites de MCPs e skills por ambiente.
+
+Saida esperada: separar o que e regra geral do que e especifico do Codex.
+
+### v0.7.0
+
+Endurecer schemas, validadores e health checks:
+
+- cobertura de schema;
+- consistencia do manifesto de instalacao;
+- verificacao de pacote;
+- validacao de docs, protocolo e templates.
+
+Saida esperada: erros estruturais devem ser detectados antes de publicar.
+
+### v0.8.0
+
+Finalizar documentacao de adocao:
+
+- getting started;
+- instalar, atualizar e verificar;
+- adaptar em projeto existente;
+- troubleshooting;
+- contribuicao.
+
+Saida esperada: alguem novo consegue instalar e entender o fluxo sem depender
+de explicacao no chat.
+
+### v0.9.0
+
+Release candidate:
+
+- congelar contratos principais;
+- marcar partes experimentais;
+- rodar validacao completa;
+- preparar notas da v1.0.
+
+Saida esperada: nenhum bloqueio conhecido para v1.0.
+
+### v1.0.0
+
+Release publica estavel:
+
+- nucleo estavel;
+- evidencia reproduzivel;
+- documentacao clara;
+- instalacao segura;
+- posicionamento publico direto.
+
+Saida esperada: divulgar como protocolo estavel, sem prometer garantia absoluta
+de seguranca.
+
+## Como Usar Em Cada Atualizacao
+
+Antes de planejar uma nova versao:
+
+1. Leia `roadmap/v1.yaml`.
+2. Escolha a menor lacuna de maturidade ainda aberta.
+3. Atualize protocolo, docs, scripts e testes se o comportamento mudar.
+4. Registre o que foi fechado e o que ficou pendente.
+5. So publique se instalacao, validacao e pacote estiverem coerentes.
+
+Depois de publicar:
+
+1. Atualize o status do roadmap.
+2. Atualize changelog e release notes.
+3. Confirme se README, docs e comandos continuam corretos.
+4. Mantenha o projeto como experimental ate todos os criterios de v1.0 serem
+   cumpridos.