ai-execution-protocol 0.3.0 → 0.3.1

package/AGENTS.md

@@ -27,7 +27,9 @@ metodologia. Para executar tarefas, prefira as regras curtas em `protocol/`.
 3. `protocol/route-packs.yaml` para ler o resumo compacto da rota.
 4. `protocol/context-budget.yaml` para limitar a leitura inicial.
 5. `memory/INDEX.yaml` somente quando memoria puder ajudar.
-6. Arquivo YAML especifico em `protocol/` somente quando o pack nao bastar:
+6. `protocol/capability-router.yaml` quando skills, MCPs ou ferramentas
+   opcionais puderem ser necessarios.
+7. Arquivo YAML especifico em `protocol/` somente quando o pack nao bastar:
    - `README.yaml`
    - `modes.yaml`
    - `execution-rules.yaml`
@@ -38,6 +40,7 @@ metodologia. Para executar tarefas, prefira as regras curtas em `protocol/`.
    - `context-compiler.yaml`
    - `context-budget.yaml`
    - `adaptive-memory.yaml`
+   - `capability-router.yaml`
    - `selective-validation.yaml`
    - `route-packs.yaml`
    - `formatting-rules.yaml`
@@ -63,6 +66,8 @@ metodologia. Para executar tarefas, prefira as regras curtas em `protocol/`.
 - Leia apenas os arquivos indicados por `protocol/router.yaml`.
 - Use `protocol/route-packs.yaml` antes de abrir todos os arquivos da rota.
 - Respeite `protocol/context-budget.yaml` e justifique expansao.
+- Use `protocol/capability-router.yaml` antes de carregar skills, MCPs ou
+  ferramentas opcionais.
 - Leia apenas assuntos de memoria relacionados ao pedido.
 - Ao terminar, registre `updated`, `unchanged`, `candidate`, `replaced` ou
   `blocked_sensitive`.
@@ -76,6 +81,8 @@ metodologia. Para executar tarefas, prefira as regras curtas em `protocol/`.
   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.
+- Selecione apenas capacidades necessarias para cobrir resultado e validacao.
+  Risco maior restringe permissao; nao aumenta ferramentas por padrao.
 - 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.

package/README.md

@@ -31,8 +31,8 @@ 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.3.0, o framework adiciona memoria adaptativa verificada, orcamento de
-contexto e validacao seletiva:
+Na v0.3.1, o framework combina memoria adaptativa, orcamento de contexto,
+validacao seletiva e roteamento de capacidades:
 
 ```text
 pedido -> risco -> memoria relevante -> contexto limitado -> acao -> validacao
@@ -42,6 +42,15 @@ 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:
+
+```text
+resultado necessario -> capacidade minima -> permissao -> validacao
+```
+
+Risco maior restringe permissoes. Ele nao aumenta automaticamente a quantidade
+de ferramentas.
+
 ## Status
 
 Projeto em fase de pesquisa e evolucao.
@@ -60,6 +69,7 @@ continuam obrigatorios em tarefas criticas.
 - `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.
 - `docs/`: explicacoes conceituais em Markdown.
 - `protocol/`: regras operacionais curtas em YAML.
 - `protocol/route-packs.yaml`: resumos compactos para reduzir leitura por rota.
@@ -87,6 +97,7 @@ continuam obrigatorios em tarefas criticas.
 8. Abra arquivos completos apenas quando o resumo compacto nao bastar.
 9. Execute, valide e entregue com evidencia.
 10. Atualize memoria apenas quando surgir um fato duravel e seguro.
+11. Carregue apenas capacidades necessarias para resultado e validacao.
 
 Regra de seguranca:
 
@@ -113,6 +124,7 @@ Comece por:
 - `docs/18-memoria-adaptativa.md`
 - `docs/19-orcamento-de-contexto.md`
 - `docs/20-validacao-seletiva.md`
+- `docs/21-roteamento-de-capacidades.md`
 
 Use `docs/` para entender a metodologia. Use `protocol/` quando quiser aplicar
 as regras em uma tarefa real.
@@ -142,6 +154,7 @@ Valide a memoria e selecione apenas as verificacoes necessarias:
 ```powershell
 python scripts/memory_manager.py --root . validate
 python scripts/selective_validation.py
+python scripts/capability_router.py --risk 1 --operation read --tag code_search
 ```
 
 ## Instalacao em outro projeto

package/dist/minimal/AGENTS.md

@@ -16,12 +16,16 @@ entrega.
 2. `protocol/router.yaml`
 3. `protocol/route-packs.yaml`
 4. `memory/INDEX.yaml` somente quando memoria puder ajudar
-5. YAML completo da rota somente quando o pack nao bastar
+5. `capabilities/registry.yaml` somente quando a tarefa exigir ferramenta
+6. YAML completo da rota somente quando o pack nao bastar
 
 ## Regras de execucao
 
 - Classifique o risco antes de agir.
 - Use o menor contexto suficiente e respeite `protocol/context-budget.yaml`.
+- Use `protocol/capability-router.yaml` para carregar somente skills, MCPs e
+  ferramentas necessarias.
+- Risco maior restringe permissao; nao aumenta a quantidade por padrao.
 - Memoria orienta; pedido atual autoriza; codigo verificado define realidade.
 - Nunca amplie escopo com base em previsao ou preferencia antiga.
 - Use `protocol/selective-validation.yaml` para escolher a menor prova suficiente.

package/dist/minimal/canonical-state.yaml

@@ -1,6 +1,6 @@
 id: canonical_state
 type: project_state
-version: 0.3
+version: 0.3.1
 purpose: small_current_truth_summary_for_ai_navigation
 status: bootstrap_template
 truth_order:

package/dist/minimal/capabilities/registry.yaml

@@ -0,0 +1,48 @@
+id: capability_registry
+type: capability_registry
+version: 0.3.1
+purpose: project_capabilities_available_to_the_agent
+policy:
+  default_available: false
+  runtime_availability_must_be_verified: true
+capabilities:
+  - id: local_search
+    type: local_tool
+    available: true
+    tags: [code_search, file_discovery]
+    operations: [read]
+    cost: {tokens: low, latency: low}
+    side_effect: none
+    confirmation: never
+  - id: local_files
+    type: local_tool
+    available: true
+    tags: [file_read, file_write]
+    operations: [read, write]
+    cost: {tokens: low, latency: low}
+    side_effect: local_write
+    confirmation: risk_based
+  - id: focused_skill
+    type: skill
+    available: runtime
+    tags: [domain_guidance]
+    operations: [read]
+    cost: {tokens: medium, latency: low}
+    side_effect: none
+    confirmation: never
+  - id: targeted_mcp
+    type: mcp
+    available: runtime
+    tags: [external_context, remote_operation]
+    operations: [read, write]
+    cost: {tokens: medium, latency: medium}
+    side_effect: remote_write
+    confirmation: operation_based
+  - id: publish_service
+    type: remote_service
+    available: runtime
+    tags: [publish]
+    operations: [publish]
+    cost: {tokens: low, latency: medium}
+    side_effect: publish
+    confirmation: always

package/dist/minimal/context-map.yaml

@@ -1,6 +1,6 @@
 id: project_context_map
 type: context_map
-version: 0.3
+version: 0.3.1
 purpose: small_index_for_progressive_context_retrieval
 maintenance:
   current_mode: manual_bootstrap
@@ -11,6 +11,7 @@ read_first:
   - protocol/router.yaml
   - protocol/route-packs.yaml
   - memory/INDEX.yaml
+  - capabilities/registry.yaml
 domains: {}
 retrieval_policy:
   order:

package/dist/minimal/memory/INDEX.yaml

@@ -1,6 +1,6 @@
 id: memory_index
 type: memory_index
-version: 0.3
+version: 0.3.1
 purpose: route_to_minimum_relevant_persistent_memory
 policy:
   - read_only_matching_subjects

package/dist/minimal/protocol/README.yaml

@@ -1,7 +1,7 @@
 id: protocol_index
 type: index
 format: yaml
-protocol_version: 0.3.0
+protocol_version: 0.3.1
 purpose: ai_operational_rules
 source_docs: ../docs
 constraints:
@@ -37,6 +37,8 @@ files:
     purpose: progressive_context_retrieval_with_aliases
   - path: adaptive-memory.yaml
     purpose: maintain_verified_user_and_project_memory
+  - path: capability-router.yaml
+    purpose: select_minimum_skills_mcps_and_tools_by_value_cost_and_risk
   - path: formatting-rules.yaml
     purpose: ai_readable_file_format
   - path: prompt-economy.yaml

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

@@ -0,0 +1,123 @@
+id: capability_router
+type: operational_rules
+version: 0.3.1
+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/fast-path.yaml

@@ -1,11 +1,12 @@
 id: fast_path
 type: agent_entrypoint
-version: 0.3
+version: 0.3.1
 purpose: minimum_rules_to_start_any_task
 read_next:
   - router.yaml
   - route-packs.yaml
   - context-budget.yaml
+  - capability-router.yaml
   - modes.yaml
 core_rules:
   - classify_risk_before_action
@@ -24,6 +25,7 @@ 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
 risk_short:
   level_0: answer_only
   level_1: small_clear_reversible_isolated_change

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

@@ -1,6 +1,6 @@
 id: route_packs
 type: route_summary_index
-version: 0.3
+version: 0.3.1
 purpose: compact_first_read_before_full_route_files
 principle: read_pack_first_expand_only_when_needed
 use:
@@ -182,3 +182,14 @@ 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
+      - 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
+      - stop_discovery_when_quality_coverage_is_complete

package/dist/minimal/protocol/router.yaml

@@ -1,6 +1,6 @@
 id: protocol_router
 type: read_router
-version: 0.3
+version: 0.3.1
 purpose: choose_minimum_protocol_files_by_task
 default_read:
   - fast-path.yaml
@@ -113,6 +113,12 @@ routes:
     read:
       - fast-path.yaml
       - selective-validation.yaml
+  capability_selection:
+    risk: adaptive
+    read:
+      - fast-path.yaml
+      - capability-router.yaml
+      - context-budget.yaml
 rules:
   - start_with_default_read
   - choose_one_route_if_task_type_is_clear
@@ -120,6 +126,7 @@ 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
   - 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/install-manifest.json

@@ -15,6 +15,7 @@
     "context-budget.yaml",
     "persistent-context.yaml",
     "adaptive-memory.yaml",
+    "capability-router.yaml",
     "formatting-rules.yaml",
     "prompt-economy.yaml",
     "spec-driven.yaml"
@@ -26,7 +27,8 @@
     "context-map.yaml",
     "decisions/README.md",
     "memory/INDEX.yaml",
-    "candidate-memory/README.md"
+    "candidate-memory/README.md",
+    "capabilities/registry.yaml"
   ],
   "aiignore_lines": [
     "results/",
@@ -42,7 +44,8 @@
       "protocol/fast-path.yaml",
       "protocol/router.yaml",
       "protocol/route-packs.yaml",
-      "Classifique o risco antes de agir"
+      "Classifique o risco antes de agir",
+      "protocol/capability-router.yaml"
     ],
     "memory/INDEX.yaml": [
       "memory_index",
@@ -59,6 +62,14 @@
     "protocol/selective-validation.yaml": [
       "smallest_validation_set",
       "release"
+    ],
+    "protocol/capability-router.yaml": [
+      "minimum_capability_set",
+      "higher_risk_means_stricter_permissions_not_more_tools"
+    ],
+    "capabilities/registry.yaml": [
+      "capability_registry",
+      "runtime_availability_must_be_verified"
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-execution-protocol",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "private": false,
   "description": "Experimental AI execution protocol for safer agent workflows, minimal context, risk classification, validation, and evidence-based delivery.",
   "license": "MIT",

package/protocol/README.yaml

@@ -1,7 +1,7 @@
 id: protocol_index
 type: index
 format: yaml
-protocol_version: 0.3.0
+protocol_version: 0.3.1
 purpose: ai_operational_rules
 source_docs: ../docs
 constraints:
@@ -37,6 +37,8 @@ files:
     purpose: progressive_context_retrieval_with_aliases
   - path: adaptive-memory.yaml
     purpose: maintain_verified_user_and_project_memory
+  - path: capability-router.yaml
+    purpose: select_minimum_skills_mcps_and_tools_by_value_cost_and_risk
   - path: formatting-rules.yaml
     purpose: ai_readable_file_format
   - path: prompt-economy.yaml

package/protocol/capability-router.yaml

@@ -0,0 +1,123 @@
+id: capability_router
+type: operational_rules
+version: 0.3.1
+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/protocol/fast-path.yaml

@@ -1,11 +1,12 @@
 id: fast_path
 type: agent_entrypoint
-version: 0.3
+version: 0.3.1
 purpose: minimum_rules_to_start_any_task
 read_next:
   - router.yaml
   - route-packs.yaml
   - context-budget.yaml
+  - capability-router.yaml
   - modes.yaml
 core_rules:
   - classify_risk_before_action
@@ -24,6 +25,7 @@ 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
 risk_short:
   level_0: answer_only
   level_1: small_clear_reversible_isolated_change

package/protocol/route-packs.yaml

@@ -1,6 +1,6 @@
 id: route_packs
 type: route_summary_index
-version: 0.3
+version: 0.3.1
 purpose: compact_first_read_before_full_route_files
 principle: read_pack_first_expand_only_when_needed
 use:
@@ -182,3 +182,14 @@ 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
+      - 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
+      - stop_discovery_when_quality_coverage_is_complete

package/protocol/router.yaml

@@ -1,6 +1,6 @@
 id: protocol_router
 type: read_router
-version: 0.3
+version: 0.3.1
 purpose: choose_minimum_protocol_files_by_task
 default_read:
   - fast-path.yaml
@@ -113,6 +113,12 @@ routes:
     read:
       - fast-path.yaml
       - selective-validation.yaml
+  capability_selection:
+    risk: adaptive
+    read:
+      - fast-path.yaml
+      - capability-router.yaml
+      - context-budget.yaml
 rules:
   - start_with_default_read
   - choose_one_route_if_task_type_is_clear
@@ -120,6 +126,7 @@ 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
   - 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/scripts/README.md

@@ -73,6 +73,20 @@ python scripts/selective_validation.py
 python scripts/selective_validation.py --release
 ```
 
+## capability_router.py
+
+Seleciona o menor conjunto de skills, MCPs e ferramentas que cobre a tarefa.
+
+```powershell
+python scripts/capability_router.py --risk 1 --operation read --tag code_search
+```
+
+Capacidades marcadas como `runtime` precisam ser informadas:
+
+```powershell
+python scripts/capability_router.py --risk 2 --operation read --tag external_context --available targeted_mcp
+```
+
 ## health_check.py
 
 Roda a validacao geral do framework.
@@ -137,14 +151,32 @@ instalacao.
 python scripts/v03_tests.py
 ```
 
+## v031_tests.py
+
+Testa cobertura, custo, disponibilidade e confirmacao do roteador de
+capacidades.
+
+```powershell
+python scripts/v031_tests.py
+```
+
 ## context_economy_benchmark.py
 
-Compara leitura ampla com rotas focadas da v0.3.0.
+Compara leitura ampla com rotas focadas do protocolo atual.
 
 ```powershell
 python scripts/context_economy_benchmark.py
 ```
 
+## capability_economy_benchmark.py
+
+Compara carregar o catalogo inteiro com selecionar apenas capacidades
+necessarias.
+
+```powershell
+python scripts/capability_economy_benchmark.py
+```
+
 ## build_dist.py
 
 Gera `dist/minimal/` a partir de `AGENTS.md` minimo e `protocol/`.

package/templates/minimal/AGENTS.md

@@ -16,12 +16,16 @@ entrega.
 2. `protocol/router.yaml`
 3. `protocol/route-packs.yaml`
 4. `memory/INDEX.yaml` somente quando memoria puder ajudar
-5. YAML completo da rota somente quando o pack nao bastar
+5. `capabilities/registry.yaml` somente quando a tarefa exigir ferramenta
+6. YAML completo da rota somente quando o pack nao bastar
 
 ## Regras de execucao
 
 - Classifique o risco antes de agir.
 - Use o menor contexto suficiente e respeite `protocol/context-budget.yaml`.
+- Use `protocol/capability-router.yaml` para carregar somente skills, MCPs e
+  ferramentas necessarias.
+- Risco maior restringe permissao; nao aumenta a quantidade por padrao.
 - Memoria orienta; pedido atual autoriza; codigo verificado define realidade.
 - Nunca amplie escopo com base em previsao ou preferencia antiga.
 - Use `protocol/selective-validation.yaml` para escolher a menor prova suficiente.

package/templates/minimal/canonical-state.yaml

@@ -1,6 +1,6 @@
 id: canonical_state
 type: project_state
-version: 0.3
+version: 0.3.1
 purpose: small_current_truth_summary_for_ai_navigation
 status: bootstrap_template
 truth_order:

package/templates/minimal/capabilities/registry.yaml

@@ -0,0 +1,48 @@
+id: capability_registry
+type: capability_registry
+version: 0.3.1
+purpose: project_capabilities_available_to_the_agent
+policy:
+  default_available: false
+  runtime_availability_must_be_verified: true
+capabilities:
+  - id: local_search
+    type: local_tool
+    available: true
+    tags: [code_search, file_discovery]
+    operations: [read]
+    cost: {tokens: low, latency: low}
+    side_effect: none
+    confirmation: never
+  - id: local_files
+    type: local_tool
+    available: true
+    tags: [file_read, file_write]
+    operations: [read, write]
+    cost: {tokens: low, latency: low}
+    side_effect: local_write
+    confirmation: risk_based
+  - id: focused_skill
+    type: skill
+    available: runtime
+    tags: [domain_guidance]
+    operations: [read]
+    cost: {tokens: medium, latency: low}
+    side_effect: none
+    confirmation: never
+  - id: targeted_mcp
+    type: mcp
+    available: runtime
+    tags: [external_context, remote_operation]
+    operations: [read, write]
+    cost: {tokens: medium, latency: medium}
+    side_effect: remote_write
+    confirmation: operation_based
+  - id: publish_service
+    type: remote_service
+    available: runtime
+    tags: [publish]
+    operations: [publish]
+    cost: {tokens: low, latency: medium}
+    side_effect: publish
+    confirmation: always

package/templates/minimal/context-map.yaml

@@ -1,6 +1,6 @@
 id: project_context_map
 type: context_map
-version: 0.3
+version: 0.3.1
 purpose: small_index_for_progressive_context_retrieval
 maintenance:
   current_mode: manual_bootstrap
@@ -11,6 +11,7 @@ read_first:
   - protocol/router.yaml
   - protocol/route-packs.yaml
   - memory/INDEX.yaml
+  - capabilities/registry.yaml
 domains: {}
 retrieval_policy:
   order:

package/templates/minimal/memory/INDEX.yaml

@@ -1,6 +1,6 @@
 id: memory_index
 type: memory_index
-version: 0.3
+version: 0.3.1
 purpose: route_to_minimum_relevant_persistent_memory
 policy:
   - read_only_matching_subjects