ai-execution-protocol 0.4.0

Behavioral execution framework for safer AI agents, minimal context, risk control, validation, and evidence-based delivery.

AI Execution Protocol

Behavioral execution framework for safer AI agents.

Framework experimental para orientar agentes de IA em tarefas tecnicas com mais seguranca, contexto minimo, validacao e controle de risco.

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;
• 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.

Na 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 v0.4.0 tambem adiciona 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.

Status

Projeto em fase de pesquisa e evolucao.

Este repositorio contem uma proposta tecnica, nao uma garantia de seguranca nem uma fonte normativa definitiva. Testes reais, revisao humana e criterio tecnico continuam obrigatorios em tarefas criticas.

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.
• behavior/: contrato comportamental observavel da v0.4.0.
• dataset/: sementes de exemplos para fine-tuning futuro.
• roadmap/: trilho de maturidade para evoluir das versoes 0.x ate a v1.0.
• docs/: explicacoes conceituais em Markdown.
• protocol/: regras operacionais curtas em YAML.
• 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

1. Leia INDEX.yaml.
2. Confirme o estado atual em canonical-state.yaml quando a verdade do projeto importar.
3. Use context-map.yaml para localizar dominio e aliases provaveis.
4. Confirme o alvo atual em config.yaml.
5. Leia protocol/fast-path.yaml.
6. Use protocol/router.yaml para escolher o menor contexto suficiente.
7. Consulte protocol/route-packs.yaml antes de abrir todos os YAML da rota.
8. Abra arquivos completos apenas quando o resumo compacto nao bastar.
9. Execute, valide e entregue com evidencia.
10. Atualize memoria apenas quando surgir um fato duravel e seguro.
11. 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.

Como estudar o framework

Comece por:

• docs/00-visao-geral.md
• docs/01-modelo-de-execucao.md
• docs/02-niveis-de-risco.md
• docs/03-mapeamento-antes-de-alterar.md
• docs/04-janela-de-contexto.md
• docs/05-validacao-e-entrega.md
• docs/15-contexto-persistente.md
• docs/17-documentacao-atomica.md
• docs/18-memoria-adaptativa.md
• docs/19-orcamento-de-contexto.md
• docs/20-validacao-seletiva.md
• docs/21-roteamento-de-capacidades.md
• docs/22-roadmap-v1.md
• docs/23-contrato-comportamental.md
• docs/24-gate-de-capacidades-e-inteligencia.md

Use docs/ para entender a metodologia. Use protocol/ quando quiser aplicar as regras em uma tarefa real.

Para evoluir o projeto ate a v1.0, use roadmap/v1.yaml como trilho operacional e docs/22-roadmap-v1.md como explicacao.

Validacao local

Execute a validacao geral:

python scripts/health_check.py

Execute a bateria estrutural extra:

python scripts/framework_tests.py

Meca custo aproximado de leitura por rota:

python scripts/token_report.py

Valide a memoria e selecione apenas as verificacoes necessarias:

python scripts/memory_manager.py --root . validate
python scripts/selective_validation.py
python scripts/capability_router.py --risk 1 --operation read --tag code_search
python scripts/behavior_contract_check.py

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.

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

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, .cursorrules, .github/copilot-instructions.md e .cursor/rules/ai-execution-protocol.mdc quando o usuario autoriza com --yes. O objetivo e aumentar aderencia em hosts que nao leem AGENTS.md diretamente, sem sobrescrever regras existentes.

Licenca

Distribuido sob a licenca MIT. Veja LICENSE.