ai-execution-protocol 0.6.1

Operational protocol for safer AI agents with risk routing, context budgeting, validation gates, and evidence-based delivery.

AI Execution Protocol

Operational execution protocol for safer AI agents.

AI Execution Protocol e um framework operacional para orientar agentes de IA em tarefas tecnicas com mais controle, previsibilidade e evidencia. Ele organiza risco, contexto, ferramentas, validacao e entrega para reduzir execucoes impulsivas, leituras desnecessarias e mudancas fora de escopo.

O alvo atual e Codex. O protocolo e otimizado para Codex agora, mas foi organizado para continuar portavel para outras IAs no futuro.

Objetivo

Evitar que a IA execute pedidos de forma impulsiva, perigosa ou fora de escopo.

O framework ajuda a IA a:

• entender a intencao antes de agir;
• classificar o risco da tarefa;
• localizar o dominio certo antes de abrir arquivos grandes;
• ler apenas o contexto necessario;
• mapear impacto antes de alterar arquivos;
• pedir confirmacao em acoes sensiveis;
• escolher ferramentas e nivel de inteligencia proporcionais ao risco;
• otimizar custo sem reduzir contexto, seguranca ou validacao obrigatoria;
• validar o resultado antes de entregar;
• explicar limites e risco residual.

Ideia central

Entender -> classificar risco -> mapear impacto -> executar -> validar -> entregar

O protocolo nao tenta transformar toda tarefa em um processo pesado. A regra e proporcionalidade: tarefa simples deve ser rapida; tarefa critica exige mais mapa, confirmacao e evidencia.

Desde a v0.4.0, o framework combina contrato comportamental, memoria adaptativa, orcamento de contexto, validacao seletiva e roteamento de capacidades:

pedido -> risco -> memoria relevante -> contexto limitado -> acao -> validacao

O contrato comportamental transforma regras em comportamento observavel:

tarefa -> comportamento esperado -> avaliacao -> evidencia

Memoria orienta, o pedido atual autoriza e arquivos verificados definem a realidade. Inferencias ficam candidatas ate acumularem evidencia, e conteudo sensivel e bloqueado.

Skills, MCPs e ferramentas opcionais seguem outro limite:

resultado necessario -> capacidade minima -> permissao -> validacao

Risco maior restringe permissoes. Ele nao aumenta automaticamente a quantidade de ferramentas.

A partir da v0.6.0, hosts que conseguem chamar um gate local tambem podem usar uma politica executavel:

plano -> ai-protocol-enforcement/gateway.py -> ferramenta

Sem essa chamada pelo host, o modo continua best_effort. Com ela, chamadas de ferramenta fora do plano podem ser bloqueadas fora do modelo.

A v0.4.0 tambem adicionou gate e orcamento de inteligencia:

risco -> complexidade -> capacidade planejada -> inteligencia suficiente

O framework marca como falha o uso de skill, MCP ou ferramenta fora do plano. Troca real de modelo depende do host, mas a politica de escolha fica explicita.

A v0.6.1 adiciona uma politica explicita de custo e qualidade:

risco -> barra de qualidade -> contexto minimo -> inteligencia suficiente -> validacao

Economia so e aceita quando a barra de qualidade, seguranca, escopo e validacao continuam preservados.

Status

Alpha operacional em desenvolvimento ativo.

O projeto ja inclui protocolo instalavel, roteamento por risco, memoria adaptativa, orcamento de contexto, validacao seletiva, roteamento de capacidades, gate de ferramentas e politica local de enforcement para hosts que suportam integracao.

Ainda assim, o protocolo nao e uma garantia de seguranca nem substitui revisao humana. Tarefas criticas continuam exigindo criterio tecnico, validacao real, sandbox do host e confirmacao explicita para acoes sensiveis.

Estrutura

• AGENTS.md: instrucao principal para agentes no projeto.
• INDEX.yaml: mapa estruturado para navegacao rapida.
• canonical-state.yaml: estado atual resumido e ordem de verdade.
• context-map.yaml: mapa pequeno de dominios, aliases e arquivos candidatos.
• config.yaml: configuracao do alvo atual e versao do protocolo.
• decisions/: decisoes importantes com status.
• memory/: preferencias, estado e padroes duraveis validados.
• candidate-memory/: inferencias ainda nao autoritativas.
• capabilities/: registro pequeno de skills, MCPs e ferramentas conhecidas.
• ai-protocol-enforcement/: gateway local e politica executavel instalados no projeto alvo.
• behavior/: contrato comportamental observavel introduzido na v0.4.0.
• dataset/: sementes de exemplos para fine-tuning futuro.
• docs/: explicacoes conceituais em Markdown.
• protocol/: regras operacionais curtas em YAML.
• protocol/cost-quality-policy.yaml: politica de economia sem perda da barra de qualidade.
• protocol/route-packs.yaml: resumos compactos para reduzir leitura por rota.
• cases/: casos estruturados para testar o comportamento da IA.
• examples/: exemplos humanos de uso do framework.
• schema/: contratos para manter os YAML padronizados.
• eval/: rubrica e exemplos de avaliacao.
• scripts/: automacoes de instalacao, validacao e avaliacao.
• responses/: exemplos de respostas para avaliacao.
• benchmarks/: comparacoes entre execucao com e sem protocolo.
• model-runs/: respostas reais por modelo para comparacao.
• real-runs/: templates ou registros de execucoes reais auditaveis.
• dist/minimal/: pacote minimo gerado para instalar em outros projetos.

Como usar como agente

O host carrega AGENTS.md. Depois disso:

1. Leia INDEX.yaml.
2. Confirme alvo e versao em config.yaml.
3. Leia protocol/fast-path.yaml.
4. Use protocol/router.yaml para escolher o menor contexto suficiente.
5. Consulte protocol/route-packs.yaml antes dos YAML completos.
6. Leia canonical-state.yaml e context-map.yaml somente quando estado atual ou mapeamento de dominio importarem.
7. Abra arquivos completos apenas quando o resumo compacto nao bastar.
8. Execute, valide e entregue com evidencia.
9. Atualize memoria apenas quando surgir um fato duravel e seguro.
10. Carregue apenas capacidades necessarias para resultado e validacao.

Regra de seguranca:

A IA pode expandir contexto.
A IA nao pode expandir escopo.

Aliases, mapas e decisoes ajudam a navegar. Eles nao substituem verificacao no codigo ou nos arquivos atuais antes de alterar comportamento.

Documentacao

Use docs/ para entender conceitos, limites e comportamento do framework. Use protocol/ quando quiser consultar as regras operacionais aplicadas pela IA. O indice em docs/README.md organiza os assuntos disponiveis.

Instalacao em outro projeto

Projeto novo:

ai-protocol init .

Projeto existente:

ai-protocol install .

Previa sem alterar arquivos:

ai-protocol install . --dry-run

Instalacao local via PowerShell:

.\install.ps1 C:\caminho\projeto -Force

Instalacao local via npm:

npm run install-protocol -- C:\caminho\projeto
npm run dry-run-protocol -- C:\caminho\projeto

Instalacao local via Python:

python scripts/install_protocol.py --target C:\caminho\projeto --force
python scripts/verify_install.py --target C:\caminho\projeto

O final esperado da verificacao e PASS.

No primeiro contato apos a instalacao, a IA mostra um onboarding curto. O usuario escolhe separadamente se permite reforcar regras locais do host e se participa dos testes reais. Quando autorizado, a propria IA aplica a escolha; o usuario nao precisa executar comandos adicionais. O AGENTS.md base ja faz parte da instalacao; o aceite adiciona reforcos para os demais hosts suportados. O setup precisa retornar ONBOARDING_VERIFY:PASS antes de continuar.

Depois do onboarding, a IA le apenas o estado curto. Se houver suspeita de host novo, instrucao ausente, conflito ou baixa aderencia, ela pode rodar setup.py compliance; reparo com setup.py repair --yes exige confirmacao.

Para tarefas nivel 2/3 com ferramentas, ou qualquer escrita, publicacao ou acao destrutiva, hosts integrados podem chamar ai-protocol-enforcement/gateway.py. Isso transforma a regra de ferramenta de best_effort em bloqueio local quando o host respeita o gateway.

Atualizacao pelos pacotes publicados:

npm install -g ai-execution-protocol@latest
python -m pip install --upgrade ai-execution-protocol
ai-protocol install C:\caminho\projeto
ai-protocol verify C:\caminho\projeto

Para retornar testes ao checkout local do framework:

ai-protocol install C:\caminho\projeto `
  --feedback-framework-root C:\Projetos\ai-research

Integracao opcional com arquivos de instrucao de IDE:

ai-protocol integrate C:\caminho\projeto --dry-run
ai-protocol integrate C:\caminho\projeto --yes

Esse comando adiciona um bloco marcado em CLAUDE.md, GEMINI.md, .github/copilot-instructions.md e .cursor/rules/ai-execution-protocol.mdc quando o usuario autoriza com --yes. O onboarding faz essa integracao automaticamente quando autorizado; o comando permanece como fallback.

Testes reais consentidos

A instalacao cria ai-protocol-feedback/, uma pasta visivel para consentimento e registros locais. No primeiro contato, o onboarding oferece uma escolha independente para testes reais. Depois do aceite, a IA registra os resumos e, quando houver framework local configurado, sincroniza com real-runs/received/. Nada e coletado antes da confirmacao e nao existe upload remoto.

Em estado normal, essa camada le apenas consent.json. O aviso completo e o protocolo detalhado sao condicionais, evitando custo recorrente de contexto.

Consulte docs/25-testes-reais-com-consentimento.md.

Suporte

Encontrou um bug? Abra uma issue no GitHub:

https://github.com/rodneigk2/ai-execution-protocol/issues

Tem uma feature request? Comente em uma issue existente ou crie uma nova issue com a tag [FEATURE].

Licenca

Distribuido sob a licenca MIT. Veja LICENSE.