ai-execution-protocol 0.3.0 → 0.4.0

package/dist/minimal/protocol/capability-gate.yaml

@@ -0,0 +1,56 @@
+id: capability_gate
+type: operational_rules
+version: 0.4.0
+purpose: gate_capability_use_before_skill_mcp_or_tool_invocation
+principle: plan_before_use_audit_after_use
+guarantee_boundary:
+  framework_can:
+    - require_capability_plan_before_use
+    - mark_unplanned_use_as_protocol_failure
+    - compare_used_capabilities_with_selected_capabilities
+    - block_high_risk_workflow_when_plan_is_missing
+  host_must:
+    - hide_or_disable_tools_for_physical_enforcement
+    - enforce_runtime_permissions
+required_before_use:
+  - task_objective
+  - risk_level
+  - operation_scope
+  - requested_operations
+  - required_outcome_tags
+  - selected_capabilities
+  - confirmation_status_when_required
+allowed_states:
+  planned:
+    meaning: selected_but_not_invoked
+  used:
+    meaning: invoked_within_plan_and_scope
+  blocked:
+    meaning: needed_but_missing_or_unconfirmed
+  violation:
+    meaning: used_without_plan_or_outside_scope
+rules:
+  - no_skill_mcp_or_remote_tool_before_capability_plan
+  - local_read_can_be_implicit_only_for_level_0_or_1_basic_navigation
+  - level_2_or_3_requires_explicit_capability_plan
+  - publish_write_or_destructive_requires_confirmation_when_policy_requires
+  - used_capability_must_be_subset_of_selected_capabilities
+  - unplanned_use_is_protocol_failure
+  - missing_required_capability_blocks_high_risk_workflow
+audit:
+  compare:
+    - selected_capabilities
+    - used_capabilities
+    - operation_scope
+    - confirmation_status
+  fail_when:
+    - used_not_selected
+    - used_for_unapproved_operation
+    - used_after_blocked_status
+    - publish_without_confirmation
+delivery:
+  include_for_level_2_or_3:
+    - capability_plan_summary
+    - used_capabilities
+    - gate_status
+    - violations_if_any

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

@@ -0,0 +1,123 @@
+id: capability_router
+type: operational_rules
+version: 0.4.0
+purpose: select_only_necessary_skills_mcps_and_tools
+principle: minimum_capability_set_must_preserve_required_quality
+platform_boundary:
+  can_control:
+    - selection
+    - instruction_loading
+    - invocation
+    - operation_scope
+  cannot_guarantee:
+    - physical_unloading_of_host_exposed_tools
+    - revocation_of_platform_permissions
+  rule: exposed_capability_must_remain_unused_until_selected
+entrypoint:
+  registry: capabilities/registry.yaml
+selection_flow:
+  - classify_task_and_risk
+  - define_required_outcomes_and_operations
+  - inspect_available_capability_metadata
+  - prefer_existing_local_capability
+  - select_smallest_set_covering_required_outcomes
+  - add_dependency_only_when_selected_capability_requires_it
+  - verify_permissions_confirmation_and_validation
+  - stop_discovery_when_coverage_is_complete
+capability_types:
+  - built_in_reasoning
+  - local_tool
+  - skill
+  - mcp
+  - remote_service
+operations:
+  read:
+    effect: none_or_read_only
+  write:
+    effect: state_change
+  publish:
+    effect: external_release
+  destructive:
+    effect: irreversible_or_high_impact
+risk_policy:
+  level_0:
+    external_capability_budget: 0
+    allow:
+      - built_in_reasoning
+    expand_when:
+      - direct_answer_requires_verified_current_data
+  level_1:
+    external_capability_budget: 1
+    prefer:
+      - local_read
+      - focused_skill
+  level_2:
+    external_capability_budget: 3
+    prefer:
+      - specialized_skill
+      - targeted_mcp
+      - local_validation
+  level_3:
+    external_capability_budget: 3
+    principle: higher_risk_means_stricter_permissions_not_more_tools
+    require:
+      - least_privilege
+      - explicit_operation_scope
+      - confirmation_before_sensitive_write_publish_or_destructive
+      - validation_before_and_after
+cost_model:
+  dimensions:
+    - context_tokens
+    - latency
+    - remote_calls
+    - permission_scope
+    - side_effect_risk
+  choose_when:
+    - required_outcome_is_covered
+    - expected_quality_gain_exceeds_incremental_cost
+  never_trade:
+    - correctness
+    - security
+    - required_validation
+    - current_information_when_task_depends_on_it
+preference_order:
+  - built_in_reasoning
+  - existing_project_context
+  - local_read_tool
+  - focused_local_skill
+  - targeted_remote_read
+  - remote_write
+  - publish_or_destructive
+discovery:
+  do:
+    - use_known_available_capabilities_first
+    - search_for_tool_only_when_required_capability_is_missing
+    - load_skill_instructions_only_after_selection
+    - connect_mcp_only_for_matching_operation
+  avoid:
+    - loading_all_skills_before_selection
+    - listing_all_mcp_resources_without_need
+    - installing_adjacent_tools_not_required_by_task
+    - continuing_discovery_after_complete_coverage
+permission_policy:
+  - read_permission_does_not_imply_write_permission
+  - write_permission_does_not_imply_publish_permission
+  - memory_never_authorizes_sensitive_operation
+  - capability_availability_does_not_authorize_use
+  - current_user_request_defines_allowed_scope
+fallback:
+  when_required_coverage_is_missing:
+    - do_not_execute_incomplete_high_risk_workflow
+    - use_safe_local_partial_work_when_independently_valid
+    - report_missing_capability
+    - request_installation_or_user_action_only_when_required
+delivery:
+  include_when_capability_used:
+    - selected_capabilities
+    - selection_reason
+    - operation_scope
+    - confirmation_status_when_required
+    - validation
+  omit:
+    - full_available_capability_catalog
+    - rejected_capabilities_without_audit_need

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

@@ -70,6 +70,7 @@ existing_project_files:
     - .cursorrules
     - CLAUDE.md
     - .github/copilot-instructions.md
+    - .cursor/rules/ai-execution-protocol.mdc
     - package_docs
     - framework_configs
   behavior:
@@ -78,7 +79,7 @@ existing_project_files:
     - 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
+    - duplicate_protocol_rules_across_ide_files_only_with_marked_integration
   conflict_order:
     - current_user_request
     - AGENTS_protocol_block

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

@@ -1,11 +1,14 @@
 id: fast_path
 type: agent_entrypoint
-version: 0.3
+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
@@ -24,6 +27,10 @@ core_rules:
   - use_only_matching_memory_subjects
   - 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
+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:
@@ -182,3 +184,49 @@ packs:
       - infer_checks_from_changed_files
       - run_smallest_sufficient_validation
       - expand_when_shared_contract_changes
+  capability_selection:
+    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
+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
@@ -113,6 +122,27 @@ routes:
     read:
       - fast-path.yaml
       - selective-validation.yaml
+  capability_selection:
+    risk: adaptive
+    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
@@ -120,6 +150,10 @@ rules:
   - expand_from_route_pack_only_when_needed
   - 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.