ai-execution-protocol 0.3.1 → 0.4.0

package/dist/minimal/protocol/fast-path.yaml

@@ -1,12 +1,14 @@
 id: fast_path
 type: agent_entrypoint
-version: 0.3.1
+version: 0.4.0
 purpose: minimum_rules_to_start_any_task
 read_next:
   - router.yaml
   - route-packs.yaml
   - context-budget.yaml
   - capability-router.yaml
+  - capability-gate.yaml
+  - intelligence-router.yaml
   - modes.yaml
 core_rules:
   - classify_risk_before_action
@@ -26,6 +28,9 @@ core_rules:
   - check_memory_update_result_after_task
   - use_selective_validation_by_blast_radius
   - select_minimum_capability_set_before_loading_skills_or_mcps
+  - require_capability_plan_before_skill_mcp_or_remote_tool_use
+  - choose_intelligence_level_proportional_to_risk_and_complexity
+  - follow_behavioral_execution_contract
 risk_short:
   level_0: answer_only
   level_1: small_clear_reversible_isolated_change

package/dist/minimal/protocol/intelligence-router.yaml

@@ -0,0 +1,63 @@
+id: intelligence_router
+type: operational_rules
+version: 0.4.0
+purpose: choose_model_reasoning_and_effort_proportional_to_task_need
+principle: use_the_cheapest_sufficient_intelligence_without_trading_correctness
+levels:
+  minimal:
+    use_when:
+      - level_0_direct_answer
+      - no_current_external_data_needed
+      - no_file_change
+    model_need: low_cost_fast
+    reasoning_depth: low
+    tools: none
+  standard:
+    use_when:
+      - level_1_small_change
+      - focused_file_read
+      - simple_validation
+    model_need: default
+    reasoning_depth: medium
+    tools: local_only
+  deep:
+    use_when:
+      - level_2_flow_bug
+      - refactor
+      - ambiguous_impact
+      - failed_first_validation
+    model_need: stronger_or_more_reasoning
+    reasoning_depth: high
+    tools: selected_local_or_targeted_remote
+  critical:
+    use_when:
+      - level_3_data_auth_security_deploy_publish_destructive
+      - high_blast_radius
+      - irreversible_or_external_side_effect
+    model_need: strongest_available_for_task
+    reasoning_depth: high_with_audit
+    tools: least_privilege_confirmed
+escalate_when:
+  - risk_level_increases
+  - ambiguity_blocks_safe_action
+  - validation_fails
+  - context_conflict_detected
+  - external_current_data_is_required
+  - specialized_modality_is_required
+deescalate_when:
+  - task_is_direct_answer
+  - no_code_or_external_state_needed
+  - validation_plan_is_trivial
+  - previous_high_risk_assumption_is_not_supported_by_evidence
+never_trade:
+  - security
+  - correctness
+  - required_validation
+  - explicit_user_scope
+delivery:
+  include_when_level_2_or_3:
+    - intelligence_level
+    - escalation_reason_if_any
+    - why_lower_level_was_not_enough
+  omit_for_level_0:
+    - model_discussion_unless_user_asks

package/dist/minimal/protocol/route-packs.yaml

@@ -1,6 +1,6 @@
 id: route_packs
 type: route_summary_index
-version: 0.3.1
+version: 0.4.0
 purpose: compact_first_read_before_full_route_files
 principle: read_pack_first_expand_only_when_needed
 use:
@@ -120,10 +120,12 @@ packs:
       - run_post_deploy_check_if_executed
   evaluate_response:
     read_if_pack_insufficient:
+      - ../behavior/contract.yaml
       - ../eval/rubric.yaml
       - ../schema/evaluated-response.schema.json
     do:
       - score_risk_behavior_avoidance_delivery_clarity
+      - check_behavior_contract_alignment
       - apply_automatic_fail_rules
   create_or_edit_yaml:
     read_if_pack_insufficient:
@@ -186,10 +188,45 @@ packs:
     risk: adaptive
     read_if_pack_insufficient:
       - capability-router.yaml
+      - capability-gate.yaml
       - context-budget.yaml
     do:
       - define_required_outcomes_and_operations
       - select_smallest_available_capability_set
       - load_only_selected_skill_or_mcp
       - require_confirmation_for_sensitive_remote_effect
+      - audit_used_capabilities_against_selected_plan
       - stop_discovery_when_quality_coverage_is_complete
+  intelligence_selection:
+    risk: adaptive
+    read_if_pack_insufficient:
+      - intelligence-router.yaml
+      - context-budget.yaml
+    do:
+      - choose_cheapest_sufficient_intelligence_level
+      - escalate_for_risk_ambiguity_validation_failure_or_large_context
+      - deescalate_when_task_is_direct_and_low_risk
+      - do_not_trade_security_correctness_or_validation_for_cost
+  behavior_evaluation:
+    risk: 1
+    read_if_pack_insufficient:
+      - ../behavior/contract.yaml
+      - ../behavior/audit-checklist.yaml
+      - ../eval/rubric.yaml
+    do:
+      - compare_response_to_observable_behaviors
+      - verify_simple_tasks_are_not_overprocessed
+      - verify_critical_tasks_are_not_undercontrolled
+      - apply_behavior_automatic_fail_rules
+  dataset_preparation:
+    risk: 1
+    read_if_pack_insufficient:
+      - ../behavior/contract.yaml
+      - ../behavior/audit-checklist.yaml
+      - prompt-economy.yaml
+      - ../dataset/README.md
+    do:
+      - create_examples_from_observable_behavior
+      - include_good_bad_and_reason
+      - keep_training_examples_consistent
+      - avoid_rewarding_bureaucracy

package/dist/minimal/protocol/router.yaml

@@ -1,6 +1,6 @@
 id: protocol_router
 type: read_router
-version: 0.3.1
+version: 0.4.0
 purpose: choose_minimum_protocol_files_by_task
 default_read:
   - fast-path.yaml
@@ -76,8 +76,17 @@ routes:
   evaluate_response:
     read:
       - fast-path.yaml
+      - ../behavior/contract.yaml
       - ../eval/rubric.yaml
       - ../schema/evaluated-response.schema.json
+  behavior_evaluation:
+    risk: 1
+    read:
+      - fast-path.yaml
+      - ../behavior/contract.yaml
+      - ../behavior/audit-checklist.yaml
+      - ../eval/rubric.yaml
+      - ../dataset/README.md
   create_or_edit_yaml:
     read:
       - fast-path.yaml
@@ -118,7 +127,22 @@ routes:
     read:
       - fast-path.yaml
       - capability-router.yaml
+      - capability-gate.yaml
+      - context-budget.yaml
+  intelligence_selection:
+    risk: adaptive
+    read:
+      - fast-path.yaml
+      - intelligence-router.yaml
       - context-budget.yaml
+  dataset_preparation:
+    risk: 1
+    read:
+      - fast-path.yaml
+      - ../behavior/contract.yaml
+      - ../behavior/audit-checklist.yaml
+      - prompt-economy.yaml
+      - ../dataset/README.md
 rules:
   - start_with_default_read
   - choose_one_route_if_task_type_is_clear
@@ -127,6 +151,9 @@ rules:
   - apply_context_budget_to_selected_route
   - retrieve_only_matching_memory_subjects
   - select_capabilities_before_loading_skill_or_connecting_mcp
+  - require_capability_gate_before_invocation
+  - route_model_or_reasoning_effort_by_risk_and_complexity
+  - use_behavior_contract_when_task_is_about_adherence_dataset_or_training
   - if_route_unclear_read_risk_levels_then_choose_route
   - do_not_read_docs_unless_protocol_is_insufficient
   - do_not_read_cases_unless_testing_or_comparing_behavior

package/docs/00-visao-geral.md

@@ -0,0 +1,41 @@
+# 00 - Visao Geral
+
+## Ideia central
+
+Uma IA que trabalha em codigo, projetos ou tarefas tecnicas nao deve apenas
+obedecer ao prompt literal. Ela deve entender a intencao real, classificar o
+risco, buscar o contexto minimo, executar com escopo controlado e entregar com
+evidencia.
+
+O objetivo nao e criar um prompt maior. O objetivo e criar um metodo de
+decisao.
+
+## Nome de trabalho
+
+Protocolo de Execucao Segura para IA.
+
+## Problema que resolve
+
+Pedidos humanos costumam ser curtos, informais ou incompletos. Sem metodo, a IA
+pode alterar arquivos antes de entender impacto, ler contexto demais, tratar
+tarefa critica como simples ou entregar sem provar o que validou.
+
+## Camadas
+
+1. Filosofia: interpretar, reduzir risco e executar com evidencia.
+2. Processo: entender, classificar risco, buscar contexto, mapear, alterar,
+   validar e entregar.
+3. Operacao: usar templates e regras YAML curtas para guiar agentes.
+4. Contexto: compilar apenas o pacote minimo necessario antes de raciocinar.
+
+## Principio principal
+
+O processo deve ser proporcional ao risco.
+
+Tarefa simples deve ser rapida. Tarefa com banco, autenticacao, seguranca,
+deploy, dados reais ou comandos destrutivos exige mapa critico, confirmacao e
+validacao forte.
+
+A conversa nao deve ser fonte da verdade. A fonte da verdade deve ser o estado
+atual verificado por `INDEX.yaml`, `config.yaml`, protocolo instalado e arquivos
+lidos na tarefa atual.

package/docs/01-modelo-de-execucao.md

@@ -0,0 +1,25 @@
+# 01 - Modelo de Execucao
+
+## Ideia central
+
+A IA deve transformar um pedido humano em uma tarefa tecnica clara e escolher o
+menor caminho seguro.
+
+## Fluxo
+
+1. Entender o objetivo.
+2. Identificar a area provavel.
+3. Avaliar risco.
+4. Buscar contexto minimo suficiente.
+5. Planejar a menor alteracao segura.
+6. Executar.
+7. Validar.
+8. Explicar resultado, limites e pendencias.
+
+## Quando mostrar interpretacao
+
+Mostre a interpretacao tecnica quando houver ambiguidade, risco, multiplas
+interpretacoes ou pedido explicito.
+
+Para tarefas simples, resolver direto costuma ser melhor.
+

package/docs/02-niveis-de-risco.md

@@ -0,0 +1,62 @@
+# 02 - Niveis de Risco
+
+## Ideia central
+
+O volume de contexto e planejamento deve acompanhar o risco.
+
+## Nivel 0
+
+Resposta simples. Nao altera arquivo e nao executa acao sensivel.
+
+## Nivel 1
+
+Caminho rapido. A tarefa e clara, pequena, reversivel e isolada.
+
+## Nivel 2
+
+Mapa de impacto. Use quando ha comportamento relevante, mais de um arquivo,
+ambiguidade ou impacto para usuario.
+
+## Nivel 3
+
+Mapa critico. Use quando envolve dados reais, seguranca, autenticacao,
+permissoes, banco, deploy, integracoes criticas ou comandos destrutivos.
+
+## Regra de subida
+
+Comece pequeno. Suba o nivel quando aparecer evidencia de risco. Nunca reduza o
+nivel ignorando risco ja descoberto.
+
+## Classificacao proporcional
+
+Nao trate toda tarefa com varios passos como nivel 3.
+
+Comece pelo menor nivel seguro para o escopo conhecido. Suba apenas quando
+aparecer evidencia concreta: dados reais, autenticacao, permissoes, banco,
+deploy, segredo, comando destrutivo ou impacto incerto em fluxo existente.
+
+Se a tarefa puder ser dividida, classifique cada subtarefa pelo proprio escopo.
+Uma parte critica pode continuar bloqueada em nivel 3 enquanto uma parte segura
+segue como nivel 1 ou 2.
+
+Isso tambem economiza contexto: a IA nao precisa carregar contexto critico para
+uma subtarefa segura, mas deve manter o risco critico registrado quando ele
+continua no pedido original.
+
+## Acao critica bloqueada
+
+Se uma tarefa foi classificada como nivel 3 e a parte critica nao pode ser
+executada, nao reduza o risco da tarefa original apenas para economizar
+contexto.
+
+Marque a parte critica como bloqueada ou pendente. Depois, se houver partes
+seguras e uteis, separe essas partes como subtarefas menores e classifique cada
+uma pelo proprio escopo.
+
+Exemplo: se o pedido e publicar em producao, mas nao existe acesso ao deploy, o
+deploy continua nivel 3 bloqueado. Preparar README, revisar `.gitignore` ou
+montar comandos de publicacao pode ser tratado como subtarefa segura, com
+contexto menor.
+
+So reduza o escopo quando a acao critica for removida explicitamente do pedido
+ou quando nova evidencia provar que o risco critico nao se aplica.

package/docs/03-mapeamento-antes-de-alterar.md

@@ -0,0 +1,48 @@
+# 03 - Mapeamento Antes de Alterar
+
+## Ideia central
+
+Antes de modificar, a IA deve saber o que esta alterando, por que esta
+alterando e como provar que funcionou.
+
+## Mapa minimo
+
+Use em tarefas simples:
+
+- objetivo;
+- area afetada;
+- arquivos candidatos;
+- risco;
+- plano;
+- validacao.
+
+## Mapa de impacto
+
+Use em tarefas medias:
+
+- objetivo real;
+- fluxo tecnico;
+- arquivos candidatos;
+- riscos e efeitos colaterais;
+- fora do escopo;
+- plano de alteracao;
+- rollback mental;
+- validacao esperada.
+
+## Mapa critico
+
+Use em tarefas sensiveis:
+
+- dados afetados;
+- permissoes;
+- superficie de seguranca;
+- riscos criticos;
+- plano seguro;
+- confirmacao necessaria;
+- rollback.
+
+## Regra pratica
+
+Nao editar arquivo que nao foi identificado como candidato. Se um novo arquivo
+se tornar necessario, atualizar o mapa antes de editar.
+

package/docs/04-janela-de-contexto.md

@@ -0,0 +1,56 @@
+# 04 - Janela de Contexto
+
+## Ideia central
+
+Janela de contexto e o limite de informacao que a IA consegue considerar em uma
+conversa ou execucao.
+
+Ela inclui mensagens, instrucoes, arquivos lidos, outputs, logs, diffs e
+resumos.
+
+## Risco
+
+Contexto demais aumenta custo e pode fazer a IA misturar decisoes antigas com
+informacoes novas.
+
+## Boas praticas
+
+- Manter cada arquivo com no maximo 400 linhas.
+- Ler trechos em vez de arquivos inteiros quando possivel.
+- Usar busca textual para localizar a parte relevante.
+- Evitar repetir regras longas no chat.
+- Separar historico de estado atual.
+- Tratar a conversa como interface, nao como fonte da verdade.
+- Usar `protocol/context-compiler.yaml` para montar um pacote minimo de contexto
+  antes de tarefas grandes ou com historico confuso.
+- Abrir nova conversa quando a continuidade ficar arriscada.
+
+## MVP recomendado
+
+Antes de bancos vetoriais ou grafo completo, use:
+
+- `canonical-state.yaml` como estado atual resumido;
+- `context-map.yaml` como mapa de dominios e aliases;
+- `decisions/` para decisoes ativas;
+- `INDEX.yaml` como mapa;
+- `config.yaml` como estado atual;
+- `protocol/router.yaml` como seletor de regras;
+- busca textual para localizar arquivos candidatos;
+- trechos relevantes em vez de arquivos inteiros;
+- resumo de handoff quando a conversa ficar longa.
+
+Meta economica: reduzir contexto desnecessario em ate 90% quando isso nao
+prejudicar seguranca, classificacao de risco, precisao ou validacao.
+
+Essa meta mede contexto irrelevante evitado. Ela nao autoriza ignorar arquivo,
+dependencia ou validacao necessaria.
+
+Use RAG, grafo de conhecimento ou cache semantico apenas quando o projeto tiver
+volume real suficiente para justificar o custo.
+
+## Limite de arquivo
+
+Nenhum arquivo deve passar de 400 linhas.
+
+Quando um arquivo se aproximar desse limite, dividir por assunto e manter um
+indice curto.

package/docs/05-validacao-e-entrega.md

@@ -0,0 +1,48 @@
+# 05 - Validacao e Entrega
+
+## Ideia central
+
+Uma entrega so fica confiavel quando existe evidencia do que foi validado e do
+que nao foi validado.
+
+## Validacao automatica
+
+Pode incluir testes, typecheck, build, lint, verificacao de links e checagem de
+diff.
+
+Selecione primeiro o menor conjunto capaz de provar o comportamento alterado.
+Amplie para a suite completa quando a mudanca atingir contrato compartilhado,
+instalacao, seguranca, varios modulos ou release.
+
+## Validacao manual
+
+Deve explicar onde testar, quais passos executar, resultado esperado e sinais de
+regressao.
+
+Quando houver chance de quebrar fluxo existente, impacto visual, dados,
+permissao, build, deploy ou integracao, a IA deve entregar uma lista objetiva do
+que testar manualmente.
+
+## Transparencia
+
+A IA nao deve dizer que algo foi testado se nao foi.
+
+## Entrega clara
+
+Quando houver interpretacao tecnica, uma boa resposta final separa:
+
+- prompt original;
+- prompt melhorado da IA;
+- o que mudou;
+- o que foi validado;
+- o que nao foi validado;
+- o que testar quando houver risco de quebra;
+- risco residual;
+- resumo em linguagem simples;
+- proximo passo apenas quando necessario.
+
+Por padrao, use uma linha por item. Cresca o formato somente quando risco,
+validacao ou explicacao exigirem.
+
+Uma resposta direta de nivel 0 pode omitir a comparacao de prompt quando nao
+houver interpretacao de escopo.

package/docs/06-memoria-e-continuidade.md

@@ -0,0 +1,27 @@
+# 06 - Memoria e Continuidade
+
+## Ideia central
+
+Memoria ajuda a preservar decisoes, mas deve ser curta e seletiva.
+
+## Registrar
+
+- decisao estavel;
+- regra recorrente;
+- problema conhecido;
+- checkpoint para retomada;
+- comando ou validacao importante.
+
+## Nao registrar
+
+- logs longos;
+- detalhes temporarios;
+- historico sem utilidade futura;
+- conclusoes sem evidencia;
+- informacao especifica demais.
+
+## Retomada
+
+Quando for melhor abrir nova conversa, deixar resumo com objetivo, ultimo corte,
+areas relevantes, validacoes feitas, pendencias e proximo passo.
+

package/docs/07-legibilidade-para-ia.md

@@ -0,0 +1,47 @@
+# 07 - Legibilidade Para IA
+
+## Ideia central
+
+Os arquivos devem ser organizados para a IA ler e aplicar com o minimo de
+ambiguidade.
+
+## Regras
+
+- Um assunto principal por arquivo.
+- Um arquivo deve representar um assunto rastreavel, nao apenas ser curto.
+- Titulos diretos e previsiveis.
+- Listas curtas e objetivas.
+- Regras antes de exemplos.
+- Termos consistentes.
+- Separar teoria, criterio, template e exemplo.
+- Evitar texto decorativo.
+- Evitar paragrafos longos escondendo decisao importante.
+- Evitar nomes genericos como `geral.md`, `notas.md` ou `parte-1.md`.
+
+## Documentacao atomica
+
+Use arquivos por dominio, fluxo, decisao, componente ou integracao.
+
+O nome do arquivo deve conter termos que a IA provavelmente buscaria. Depois de
+abrir a doc certa, use `rg` para encontrar simbolos e trechos no codigo.
+
+Regra curta:
+
+```text
+Doc atomica localiza.
+rg encontra.
+Codigo verificado decide.
+```
+
+## Formato preferido
+
+1. Ideia central.
+2. Quando usar.
+3. Regras.
+4. Criterios.
+5. Excecoes.
+6. Exemplos.
+7. Validacao ou entrega esperada.
+
+Nem todo arquivo precisa ter todas as secoes. O importante e manter ordem
+previsivel.

package/docs/08-posicionamento.md

@@ -0,0 +1,48 @@
+# 08 - Posicionamento
+
+## O que e
+
+Um framework para orientar IA em tarefas tecnicas com risco controlado,
+contexto minimo, validacao e entrega com evidencia.
+
+## Para quem e
+
+- Agentes de codigo.
+- Assistentes em IDE.
+- Times que usam IA para desenvolvimento.
+- Pessoas que querem reduzir erro, retrabalho e custo de contexto.
+
+## Problema que resolve
+
+IA tecnica costuma errar quando age rapido demais, le contexto demais ou trata
+tarefa critica como simples.
+
+O framework cria um processo para a IA decidir antes de agir.
+
+## O que nao tenta resolver
+
+- Nao substitui testes reais.
+- Nao substitui revisao humana em tarefa critica.
+- Nao garante que a IA sempre esteja certa.
+- Nao elimina necessidade de entender o projeto.
+
+## Promessa
+
+Reduzir erro operacional e custo de contexto ao fazer a IA:
+
+- classificar risco;
+- abrir menos arquivos;
+- mapear impacto quando necessario;
+- pedir confirmacao em tarefa critica;
+- validar antes de entregar;
+- explicar limites e risco residual.
+
+## Como medir sucesso
+
+- Menos arquivos lidos por tarefa.
+- Menos tokens por rota.
+- Mais tarefas com risco classificado corretamente.
+- Menos acoes sensiveis sem confirmacao.
+- Mais entregas com validacao clara.
+- Menos regressao por mudanca fora de escopo.
+

package/docs/09-governanca-de-mudancas.md

@@ -0,0 +1,48 @@
+# 09 - Governanca de Mudancas
+
+## Ideia central
+
+O protocolo deve evoluir sem perder clareza, economia e confiabilidade.
+
+## Quando mudar uma regra
+
+Mude uma regra quando houver:
+
+- falha repetida em caso real;
+- ambiguidade detectada por teste;
+- custo alto de contexto;
+- duplicacao clara;
+- nova categoria de risco.
+
+## Antes de mudar
+
+- Identifique o arquivo certo.
+- Verifique se a mudanca afeta `protocol/`, `cases/`, `eval/` ou `scripts/`.
+- Evite duplicar regra existente.
+- Mantenha o arquivo abaixo de 400 linhas.
+
+## Depois de mudar
+
+- Atualize indice relacionado.
+- Se criar ou dividir docs, atualize `docs/README.md`, `INDEX.yaml` ou
+  `context-map.yaml` quando relevante.
+- Verifique se a mudanca criou duplicidade entre assuntos.
+- Atualize `CHANGELOG.md`.
+- Rode `scripts/health_check.py`.
+- Se mudar `protocol/`, rode `scripts/build_dist.py`.
+- Se mudar avaliacao, rode benchmarks.
+
+## Regra de economia
+
+Toda mudanca deve reduzir ambiguidade sem aumentar contexto desnecessario.
+
+## Regra para docs novas
+
+Antes de criar uma doc nova, procure se o assunto ja existe:
+
+```powershell
+rg -n "termo-do-assunto|alias|simbolo" docs context-map.yaml INDEX.yaml
+```
+
+Se existir, atualize a doc existente. Se nao existir e o assunto tiver valor
+proprio, crie uma doc atomica com nome buscavel.