ai-execution-protocol 0.6.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.

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.

Status

Projeto experimental em fase de pesquisa.

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

Licenca

Distribuido sob a licenca MIT. Veja LICENSE.