ai-execution-protocol 0.1.0

package/AGENTS.md

@@ -0,0 +1,90 @@
+# AGENTS.md
+
+## Objetivo
+
+Este projeto pesquisa e organiza um protocolo de execucao segura para IA.
+
+Alvo atual: Codex. Otimize o fluxo para Codex agora, mas mantenha o protocolo
+portavel para outras IAs no futuro.
+
+## Regra principal
+
+Use `INDEX.yaml` como mapa do projeto.
+
+Use `config.yaml` para confirmar o alvo atual.
+
+Use `protocol_version` para registrar qual versao do protocolo orientou a tarefa.
+
+Use `protocol/fast-path.yaml` como entrada operacional minima.
+
+Leia arquivos em `docs/` apenas quando precisar entender, revisar ou evoluir a
+metodologia. Para executar tarefas, prefira as regras curtas em `protocol/`.
+
+## Ordem de leitura
+
+1. `protocol/fast-path.yaml`
+2. `protocol/router.yaml`
+3. Arquivo YAML especifico em `protocol/` conforme a rota:
+   - `README.yaml`
+   - `modes.yaml`
+   - `execution-rules.yaml`
+   - `risk-levels.yaml`
+   - `mapping-checklists.yaml`
+   - `validation-checklist.yaml`
+   - `context-rules.yaml`
+   - `context-compiler.yaml`
+   - `formatting-rules.yaml`
+   - `prompt-economy.yaml`
+   - `spec-driven.yaml`
+4. Arquivos em `cases/` quando precisar comparar a tarefa com um caso de teste.
+5. Arquivos em `eval/` quando precisar avaliar se uma resposta seguiu o
+   protocolo.
+6. Arquivos em `scripts/` quando precisar rodar avaliacao automatica.
+7. Arquivos em `results/` quando precisar consultar historico de avaliacoes.
+8. Arquivos em `benchmarks/` quando precisar comparar execucao com e sem
+   protocolo.
+9. Arquivos em `model-runs/` quando precisar comparar respostas reais por
+   modelo.
+10. Arquivos em `real-runs/` quando precisar auditar execucao real.
+11. Arquivos em `schema/` quando criar ou alterar YAML.
+12. Arquivos em `docs/` somente se o YAML nao for suficiente.
+
+## Regras de execucao
+
+- Classifique o risco antes de agir.
+- Use o menor contexto suficiente.
+- Leia apenas os arquivos indicados por `protocol/router.yaml`.
+- Quando houver contexto grande, historico longo ou risco de confusao, use
+  `protocol/context-compiler.yaml` antes de abrir muitos arquivos.
+- Siga `.aiignore` e `INDEX.yaml/read_policy.ignore_by_default` antes de abrir
+  relatorios gerados.
+- Ao melhorar prompt do usuario, siga `protocol/prompt-economy.yaml`.
+- Sempre entregue `Prompt original` e `Prompt melhorado da IA`; em baixo risco,
+  prefira micro formato legivel com `PO`, `PM` e `OK`.
+- Ao criar feature, refatoracao grande ou tarefa critica, use
+  `protocol/spec-driven.yaml` sem transformar tarefa simples em spec pesada.
+- Nao edite arquivo que nao foi identificado como candidato.
+- Se o risco subir, atualize a classificacao antes de continuar.
+- Para nivel critico, peca confirmacao antes de acao sensivel.
+- Quando houver risco de quebrar fluxo existente, entregue uma lista do que
+  testar.
+- Entregue com evidencia em poucas linhas: mudanca, validacao, limite e risco
+  residual.
+- Explique o resultado em linguagem clara para uma pessoa leiga entender.
+
+## Regras de organizacao
+
+- Nenhum arquivo deve passar de 400 linhas.
+- Organize primeiro para legibilidade por IA.
+- Mantenha Markdown para explicacao e YAML para operacao.
+- Ao criar arquivo novo, atualize o indice correspondente.
+- Ao criar caso novo, siga `schema/test-case.schema.yaml`.
+- Ao criar regra operacional, siga `schema/protocol-rule.schema.yaml`.
+- Ao avaliar uma resposta, use `eval/rubric.yaml`.
+- Ao rodar avaliacao automatica, use `scripts/eval_runner.py`.
+- Ao avaliar texto livre, converta antes com `scripts/response_parser.py`.
+- Ao medir custo de leitura, use `scripts/token_report.py`.
+- Ao validar o framework inteiro, use `scripts/health_check.py`.
+- Ao comparar melhoria real, registre em `benchmarks/`.
+- Ao comparar modelos reais, use `scripts/model_runs_runner.py`.
+- Evite duplicar a mesma regra em muitos lugares.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Execution Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# 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;
+- 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
+
+```text
+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.
+
+## 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.
+- `config.yaml`: configuracao do alvo atual e versao do protocolo.
+- `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 alvo atual em `config.yaml`.
+3. Leia `protocol/fast-path.yaml`.
+4. Use `protocol/router.yaml` para escolher o menor contexto suficiente.
+5. Abra apenas os arquivos indicados pela rota.
+6. Execute, valide e entregue com evidencia.
+
+## 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/05-validacao-e-entrega.md`
+- `docs/14-publicacao.md`
+
+Use `docs/` para entender a metodologia. Use `protocol/` quando quiser aplicar
+as regras em uma tarefa real.
+
+## Validacao local
+
+Execute a validacao geral:
+
+```powershell
+python scripts/health_check.py
+```
+
+Execute a bateria estrutural extra:
+
+```powershell
+python scripts/framework_tests.py
+```
+
+Meca custo aproximado de leitura por rota:
+
+```powershell
+python scripts/token_report.py
+```
+
+## Instalacao em outro projeto
+
+Projeto novo:
+
+```powershell
+ai-protocol init .
+```
+
+Projeto existente:
+
+```powershell
+ai-protocol install .
+```
+
+Previa sem alterar arquivos:
+
+```powershell
+ai-protocol install . --dry-run
+```
+
+Instalacao local via PowerShell:
+
+```powershell
+.\install.ps1 C:\caminho\projeto -Force
+```
+
+Instalacao local via npm:
+
+```powershell
+npm run install-protocol -- C:\caminho\projeto
+npm run dry-run-protocol -- C:\caminho\projeto
+```
+
+Instalacao local via Python:
+
+```powershell
+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`.
+
+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`.

package/dist/minimal/.aiignore

@@ -0,0 +1,8 @@
+# Context files ignored by default for AI reading.
+
+results/
+benchmarks/generated/
+model-runs/generated/
+dist/
+scripts/__pycache__/
+*.pyc

package/dist/minimal/AGENTS.md

@@ -0,0 +1,61 @@
+# AGENTS.md
+
+## Regra principal
+
+<!-- AI_PROTOCOL_BEGIN -->
+
+Use `protocol/fast-path.yaml` como entrada operacional minima.
+
+Siga `.aiignore` antes de abrir relatorios gerados.
+
+Este protocolo e obrigatorio para tarefas tecnicas neste projeto. Antes de
+editar, classifique risco, escolha rota e valide a entrega.
+
+## Ordem de leitura
+
+1. `protocol/fast-path.yaml`
+2. `protocol/router.yaml`
+3. Arquivo YAML especifico em `protocol/` conforme a rota.
+
+## Regras de execucao
+
+- Classifique o risco antes de agir.
+- Use o menor contexto suficiente.
+- Leia apenas os arquivos indicados por `protocol/router.yaml`.
+- Quando houver contexto grande, historico longo ou risco de confusao, use
+  `protocol/context-compiler.yaml` antes de abrir muitos arquivos.
+- Use `protocol/spec-driven.yaml` para feature, refatoracao grande ou tarefa
+  critica, sem criar spec pesada para tarefa simples.
+- Sempre entregue `Prompt original` e `Prompt melhorado da IA`; em baixo risco,
+  prefira micro formato legivel com `PO`, `PM` e `OK`.
+- Nao edite arquivo que nao foi identificado como candidato.
+- Preserve documentos, regras de IDE e configuracoes de framework existentes,
+  salvo pedido explicito do usuario.
+- Se o risco subir, atualize a classificacao antes de continuar.
+- Para nivel critico, peca confirmacao antes de acao sensivel.
+- Quando houver risco de quebrar fluxo existente, entregue uma lista do que
+  testar.
+- Entregue com evidencia em poucas linhas: mudanca, validacao, limite e risco
+  residual.
+- Explique o resultado em linguagem clara para uma pessoa leiga entender.
+
+## Convivencia com arquivos existentes
+
+Quando houver conflito, siga esta prioridade:
+
+1. pedido atual do usuario;
+2. este bloco obrigatorio em `AGENTS.md`;
+3. regras especificas da IDE ou do projeto;
+4. docs e historico somente quando a rota pedir.
+
+Nao sobrescreva `README.md`, `docs/`, `.cursorrules`, `CLAUDE.md`,
+`.github/copilot-instructions.md` ou configs de framework sem pedido claro.
+
+## Regras de organizacao
+
+- Nenhum arquivo deve passar de 400 linhas.
+- Organize primeiro para legibilidade por IA.
+- Use YAML para regras operacionais.
+- Evite duplicar a mesma regra em muitos lugares.
+
+<!-- AI_PROTOCOL_END -->

package/dist/minimal/README.md

@@ -0,0 +1,60 @@
+# Minimal AI Protocol
+
+Pacote minimo para aplicar o protocolo em outro projeto.
+
+Copie estes itens para a raiz do projeto alvo:
+
+- `AGENTS.md`
+- `.aiignore`
+- `protocol/`
+
+Use `AGENTS.md` como instrucao principal do agente.
+
+Para instalar automaticamente:
+
+```powershell
+python scripts/install_protocol.py --target C:\caminho\projeto --force
+```
+
+Comando unico facil de lembrar dentro deste repositorio:
+
+```powershell
+.\install.ps1 C:\caminho\projeto -Force
+```
+
+Atalho via npm:
+
+```powershell
+npm run install-protocol -- C:\caminho\projeto
+```
+
+Como pacote npm publicado:
+
+```powershell
+npm install -g ai-execution-protocol
+ai-protocol init C:\caminho\projeto
+ai-protocol install C:\caminho\projeto
+ai-protocol install C:\caminho\projeto --dry-run
+```
+
+Como pacote Python publicado:
+
+```powershell
+pip install ai-execution-protocol
+ai-protocol install C:\caminho\projeto
+ai-protocol verify C:\caminho\projeto
+```
+
+Se o terminal ja estiver no projeto alvo:
+
+```powershell
+C:\caminho\ai-research\install.ps1 . -Force
+```
+
+No CMD:
+
+```bat
+install.bat C:\caminho\projeto
+```
+
+O `install.ps1` tambem roda a verificacao. O resultado esperado e `PASS`.

package/dist/minimal/protocol/README.yaml

@@ -0,0 +1,35 @@
+id: protocol_index
+type: index
+format: yaml
+protocol_version: 0.1.0
+purpose: ai_operational_rules
+source_docs: ../docs
+constraints:
+  max_lines_per_file: 400
+  ai_first_readability: true
+  compact_rules: true
+files:
+  - path: fast-path.yaml
+    purpose: minimum_rules_to_start_any_task
+  - path: router.yaml
+    purpose: choose_minimum_files_to_read_by_task
+  - path: modes.yaml
+    purpose: choose_fast_balanced_or_strict_behavior
+  - path: execution-rules.yaml
+    purpose: execution_flow_and_core_behavior
+  - path: risk-levels.yaml
+    purpose: risk_classification_and_confirmation
+  - path: mapping-checklists.yaml
+    purpose: pre_change_maps_by_risk
+  - path: validation-checklist.yaml
+    purpose: validation_and_final_delivery
+  - path: context-rules.yaml
+    purpose: context_window_file_size_memory
+  - path: context-compiler.yaml
+    purpose: compile_minimum_context_package_and_canonical_state
+  - path: formatting-rules.yaml
+    purpose: ai_readable_file_format
+  - path: prompt-economy.yaml
+    purpose: improve_prompts_without_token_bloat
+  - path: spec-driven.yaml
+    purpose: use_light_or_full_specs_only_when_they_reduce_risk

package/dist/minimal/protocol/context-compiler.yaml

@@ -0,0 +1,110 @@
+id: context_compiler
+type: operational_rules
+version: 0.1
+purpose: build_minimum_context_package_before_model_reasoning
+principle: conversation_is_interface_not_source_of_truth
+canonical_state:
+  read_first:
+    - AGENTS.md
+    - INDEX.yaml
+    - config.yaml
+    - protocol/fast-path.yaml
+    - protocol/router.yaml
+  active_truth:
+    - current_user_request
+    - installed_protocol_block
+    - current_project_index
+    - current_config
+    - current_files_verified_this_turn
+  historical_only:
+    - old_chat_messages
+    - generated_reports
+    - archived_results
+    - revoked_or_replaced_decisions
+context_build:
+  input:
+    - user_request
+    - route_from_router
+    - risk_level
+    - candidate_files_or_areas
+    - recent_validated_state
+  output:
+    - objective
+    - constraints
+    - relevant_rules
+    - candidate_files
+    - validation_plan
+    - excluded_context
+selection_policy:
+  include:
+    - files_required_by_route
+    - snippets_matching_task_terms
+    - current_decisions_touching_candidate_area
+    - framework_configs_when_task_touches_framework
+  exclude:
+    - unrelated_docs
+    - old_generated_reports
+    - full_logs_without_error_focus
+    - revoked_decisions_unless_comparing_history
+    - entire_large_files_when_snippet_is_enough
+memory_layers:
+  active:
+    definition: required_to_complete_current_task
+    token_policy: keep_in_context
+  archived:
+    definition: useful_only_if_evidence_matches_task
+    token_policy: retrieve_only_on_need
+  revoked:
+    definition: no_longer_valid_decision
+    token_policy: never_treat_as_current_truth
+decision_rules:
+  - id: CTX_001
+    when: decision_has_status_revoked_or_replaced
+    do:
+      - use_only_to_explain_history
+      - prefer_replacement_decision
+    avoid:
+      - treating_as_current_instruction
+  - id: CTX_002
+    when: context_is_large
+    do:
+      - search_before_reading
+      - read_snippets_before_full_files
+      - stop_when_validation_plan_is_clear
+  - id: CTX_003
+    when: task_crosses_multiple_domains
+    do:
+      - build_context_by_domain
+      - include_only_domain_interfaces
+      - avoid_loading_all_domains
+  - id: CTX_004
+    when: context_gap_blocks_safe_execution
+    do:
+      - ask_one_short_question_or_read_next_mapped_file
+retrieval_tiers:
+  mvp:
+    use:
+      - INDEX.yaml
+      - router.yaml
+      - targeted_search
+      - file_snippets
+      - handoff_summary
+  advanced:
+    use_when:
+      - thousands_of_files
+      - repeated_cross_session_work
+      - semantic_search_needed
+    options:
+      - decision_log
+      - lightweight_knowledge_graph
+      - semantic_cache
+      - vector_search
+  avoid_initially:
+    - mandatory_vector_database_for_small_projects
+    - sending_raw_project_state_to_model
+    - building_global_graph_before_real_need
+delivery:
+  include_when_relevant:
+    - context_used
+    - context_excluded
+    - reason_for_not_reading_more

package/dist/minimal/protocol/context-rules.yaml

@@ -0,0 +1,71 @@
+id: context_rules
+type: operational_rules
+version: 0.1
+context_policy:
+  use: minimum_sufficient_context
+  prefer:
+    - targeted_search
+    - relevant_snippets
+    - current_state_over_old_history
+    - context_compiler_before_large_reads
+  avoid:
+    - reading_large_files_without_reason
+    - repeating_long_rules_in_chat
+    - mixing_old_and_current_docs
+    - treating_conversation_as_source_of_truth
+file_size:
+  max_lines: 400
+  when_near_limit:
+    - split_by_subject
+    - keep_main_file_short
+    - update_index
+memory:
+  record:
+    - stable_decision
+    - recurring_rule
+    - known_problem
+    - resume_checkpoint
+    - important_validation
+  avoid_recording:
+    - long_logs
+    - temporary_details
+    - unevidenced_conclusions
+handoff_summary:
+  use_when: new_conversation_needed
+  fields:
+    - objective
+    - last_cut
+    - relevant_files_or_areas
+    - validations_done
+    - pending_items
+    - next_step
+context_compiler:
+  source: context-compiler.yaml
+  use_when:
+    - risk_level_2_or_3
+    - large_project
+    - long_session
+    - conflicting_history
+    - task_crosses_domains
+existing_project_files:
+  preserve:
+    - README.md
+    - docs/
+    - .cursorrules
+    - CLAUDE.md
+    - .github/copilot-instructions.md
+    - package_docs
+    - framework_configs
+  behavior:
+    - do_not_overwrite_user_docs_without_request
+    - read_project_docs_only_when_route_requires_context
+    - treat_generated_or_old_docs_as_untrusted_until_verified
+    - keep_protocol_rules_in_AGENTS_and_protocol_folder
+    - use_framework_configs_as_technical_source_when_task_touches_framework
+    - do_not_duplicate_protocol_rules_across_ide_files
+  conflict_order:
+    - current_user_request
+    - AGENTS_protocol_block
+    - ide_framework_or_project_specific_rules
+    - project_specific_docs
+    - old_generated_reports

package/dist/minimal/protocol/execution-rules.yaml

@@ -0,0 +1,56 @@
+id: execution_rules
+type: operational_rules
+version: 0.1
+rules:
+  - id: EXEC_001
+    when: any_task
+    do:
+      - understand_goal
+      - classify_risk
+      - fetch_minimum_sufficient_context
+      - map_when_needed
+      - improve_prompt_proportional_to_risk_and_token_need
+      - execute_smallest_safe_change
+      - validate
+      - prepare_test_list_when_break_risk_exists
+      - deliver_with_evidence
+  - id: EXEC_002
+    when:
+      any:
+        - ambiguity
+        - risk
+        - multiple_interpretations
+        - user_requested_interpretation
+    do:
+      - show_technical_interpretation_before_action
+      - show_original_and_improved_prompt
+  - id: EXEC_003
+    when:
+      all:
+        - simple_task
+        - low_risk
+    do:
+      - solve_directly
+    avoid:
+      - heavy_plan
+      - unnecessary_confirmation
+  - id: EXEC_004
+    when:
+      any:
+        - multi_step_feature
+        - cross_file_change
+        - level_2_large
+        - level_3
+    do:
+      - create_light_or_full_spec_before_implementation
+    avoid:
+      - long_spec_for_simple_task
+      - spec_that_repeats_known_context
+  - id: EXEC_005
+    when: final_delivery
+    do:
+      - show_prompt_original
+      - show_prompt_melhorado_da_ia
+      - explain_what_was_done_in_plain_language
+      - list_validation_done_and_not_done
+      - list_manual_tests_when_break_risk_exists