ai-execution-protocol 0.2.0

Experimental AI execution protocol for safer agent workflows, minimal context, risk classification, validation, and evidence-based delivery.

AI Execution Protocol

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.2.0, o framework adiciona uma camada leve de contexto persistente:

pedido -> intencao -> dominio -> contexto minimo -> validacao -> acao

Essa camada usa canonical-state.yaml, context-map.yaml, decisions/ e protocol/persistent-context.yaml para reduzir leitura desnecessaria. Ela e um bootstrap seguro, nao um indexador automatico completo.

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.
• docs/: explicacoes conceituais em Markdown.
• protocol/: regras operacionais curtas em YAML.
• 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. Abra apenas os arquivos indicados pela rota ou pela recuperacao progressiva.
8. Execute, valide e entregue com evidencia.

Regra de seguranca da v0.2.0:

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/14-publicacao.md
• docs/16-release-e-atualizacao.md

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

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

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.

Publicacao

Antes de publicar, revise docs/14-publicacao.md. Para atualizar uma versao ja publicada, revise docs/16-release-e-atualizacao.md.

Resumo minimo:

• nao publique .env, chaves, tokens, senhas, logs reais ou dados de cliente;
• mantenha artefatos gerados fora do Git quando nao forem necessarios;
• use .gitignore;
• publique com README.md, LICENSE, docs/, protocol/, cases/, examples/, schema/, eval/ e scripts/ quando fizer sentido;
• preserve o posicionamento como pesquisa experimental e framework em evolucao.

Licenca

Distribuido sob a licenca MIT. Veja LICENSE.