ai-execution-protocol 0.3.0 → 0.4.0

package/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/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/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/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/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/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/roadmap/v1.yaml

@@ -0,0 +1,139 @@
+id: roadmap_v1
+type: release_roadmap
+version: 0.1
+target_release: 1.0.0
+purpose: guide_each_update_until_public_v1
+status: active
+principle:
+  - do_not_market_as_stable_before_v1
+  - each_release_must_close_one_maturity_gap
+  - prove_context_economy_quality_and_safety_with_examples
+  - keep_protocol_core_stable_before_broad_public_launch
+current_position:
+  current_series: 0.4.x
+  maturity: behavioral_execution_layer
+  public_positioning: experimental_until_v1
+  publish_strategy: publish_packages_for_testing_not_broad_marketing
+v1_success_criteria:
+  protocol_stability:
+    - risk_levels_stable
+    - context_budget_stable
+    - adaptive_memory_stable
+    - capability_routing_stable
+    - selective_validation_stable
+  evidence:
+    - real_cases_documented
+    - before_after_examples_available
+    - benchmark_report_current
+    - install_and_update_flow_verified
+  adoption:
+    - codex_guide_clear
+    - other_agent_portability_documented
+    - troubleshooting_documented
+    - contribution_rules_clear
+  safety:
+    - secret_handling_documented
+    - sensitive_actions_require_confirmation
+    - memory_deduplication_and_replacement_validated
+    - capability_permissions_follow_least_privilege
+release_path:
+  - version: 0.3.x
+    goal: harden_current_capability_context_memory_stack
+    status: completed
+    exit_criteria:
+      - capability_routing_documented_and_tested
+      - docs_commands_and_install_flow_stay_synced
+      - no_known_packaging_gap_blocks_testing
+  - version: 0.4.0
+    goal: add_behavioral_execution_contract_and_economy_reports
+    status: current
+    focus:
+      - behavioral_contract
+      - trainable_behavior_units
+      - token_and_file_read_savings
+      - tools_avoided
+      - validation_cost_by_risk
+      - quality_preserved_examples
+    exit_criteria:
+      - behavior_contract_is_installed_and_validated
+      - benchmark_report_has_clear_before_after_numbers
+      - benchmark_can_be_reproduced_locally
+  - version: 0.5.0
+    goal: add_real_world_cases
+    focus:
+      - simple_task
+      - medium_risk_bug
+      - docs_update
+      - capability_or_mcp_task
+      - memory_update_task
+      - release_task
+    exit_criteria:
+      - at_least_6_real_or_realistic_cases
+      - each_case_has_context_used_validation_and_outcome
+  - version: 0.6.0
+    goal: document_portability_beyond_codex
+    focus:
+      - codex_primary_flow
+      - cursor_adaptation
+      - claude_or_generic_agent_adaptation
+      - mcp_capability_boundaries
+    exit_criteria:
+      - portability_limits_are_explicit
+      - codex_specific_rules_are_separated_from_generic_rules
+  - version: 0.7.0
+    goal: harden_schemas_validation_and_health_checks
+    focus:
+      - schema_coverage
+      - health_check_coverage
+      - install_manifest_consistency
+      - package_content_checks
+    exit_criteria:
+      - health_check_catches_missing_core_files
+      - release_checks_cover_docs_protocol_templates_and_packages
+  - version: 0.8.0
+    goal: finish_adoption_documentation
+    focus:
+      - getting_started
+      - install_update_verify
+      - project_adaptation
+      - troubleshooting
+      - contribution_guidelines
+    exit_criteria:
+      - new_user_can_install_verify_and_understand_core_flow
+      - docs_are_atomic_and_indexed
+  - version: 0.9.0
+    goal: release_candidate
+    focus:
+      - freeze_core_contracts
+      - remove_or_mark_unstable_experimental_parts
+      - run_full_validation
+      - prepare_v1_release_notes
+    exit_criteria:
+      - no_known_blocker_for_v1
+      - docs_and_protocol_are_consistent
+      - packages_install_cleanly
+  - version: 1.0.0
+    goal: stable_public_release
+    focus:
+      - stable_protocol_core
+      - clear_public_positioning
+      - reproducible_evidence
+      - safe_installation
+    exit_criteria:
+      - v1_success_criteria_met
+update_rule:
+  before_each_release:
+    - read_this_roadmap
+    - choose_next_smallest_maturity_gap
+    - update_docs_protocol_tests_when_behavior_changes
+    - record_completed_and_remaining_exit_criteria
+  after_each_release:
+    - update_current_position
+    - mark_exit_criteria_done_or_pending
+    - update_docs_22_roadmap_v1
+    - keep_changelog_release_notes_synced
+avoid:
+  - broad_marketing_before_v1
+  - claiming_security_guarantees
+  - changing_core_terms_without_migration_note
+  - adding_new_surfaces_without_tests_or_docs

package/schema/README.md

@@ -0,0 +1,26 @@
+# Schemas
+
+Esta pasta descreve o formato esperado dos arquivos YAML.
+
+Os schemas sao leves e servem como contrato de organizacao. Eles ajudam a IA a
+manter arquivos parecidos entre si.
+
+## Arquivos
+
+- [protocol-rule.schema.yaml](./protocol-rule.schema.yaml): formato de regra
+  operacional.
+- [test-case.schema.yaml](./test-case.schema.yaml): formato de caso de teste.
+- [protocol-rule.schema.json](./protocol-rule.schema.json): JSON Schema
+  validavel para regras operacionais.
+- [test-case.schema.json](./test-case.schema.json): JSON Schema validavel para
+  casos.
+- [evaluated-response.schema.json](./evaluated-response.schema.json): JSON
+  Schema validavel para respostas avaliaveis.
+- [evaluation-result.schema.json](./evaluation-result.schema.json): JSON Schema
+  validavel para resultados.
+- [memory-entry.schema.json](./memory-entry.schema.json): contrato de uma
+  entrada de memoria adaptativa.
+- [capability-registry.schema.json](./capability-registry.schema.json):
+  contrato do registro de skills, MCPs e ferramentas.
+- [behavior-contract.schema.json](./behavior-contract.schema.json): contrato
+  da camada comportamental observavel.

package/schema/behavior-contract.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-research.local/schema/behavior-contract.schema.json",
+  "title": "Behavior contract",
+  "type": "object",
+  "required": [
+    "id",
+    "type",
+    "version",
+    "purpose",
+    "principle",
+    "automatic_fail_when"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "type": { "const": "behavior_contract" },
+    "version": { "type": ["string", "number"] },
+    "purpose": { "type": "string" },
+    "subtitle": { "type": "string" },
+    "status": { "type": "string" },
+    "principle": { "type": "array", "items": { "type": "string" } },
+    "scope": { "type": "object" },
+    "behavior_sets": { "type": "array" },
+    "core_behaviors": { "type": "array", "items": { "type": "string" } },
+    "trainable_units": { "type": "array" },
+    "evaluation_dimensions": { "type": "array" },
+    "automatic_fail_when": { "type": "array", "items": { "type": "string" } },
+    "dataset_policy": { "type": "object" }
+  },
+  "additionalProperties": false
+}

package/schema/capability-registry.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-research.local/schema/capability-registry.schema.json",
+  "title": "Capability registry",
+  "type": "object",
+  "required": ["id", "type", "version", "capabilities"],
+  "properties": {
+    "id": { "type": "string" },
+    "type": { "const": "capability_registry" },
+    "version": { "type": ["string", "number"] },
+    "purpose": { "type": "string" },
+    "policy": { "type": "object" },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "type",
+          "available",
+          "tags",
+          "operations",
+          "cost",
+          "side_effect",
+          "confirmation"
+        ],
+        "properties": {
+          "id": { "type": "string" },
+          "type": {
+            "enum": [
+              "built_in_reasoning",
+              "local_tool",
+              "skill",
+              "mcp",
+              "remote_service"
+            ]
+          },
+          "available": { "type": ["boolean", "string"] },
+          "tags": { "type": "array", "items": { "type": "string" } },
+          "operations": { "type": "array", "items": { "type": "string" } },
+          "cost": { "type": "object" },
+          "side_effect": { "type": "string" },
+          "confirmation": { "type": "string" },
+          "depends_on": { "type": "array", "items": { "type": "string" } }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schema/evaluated-response.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-research.local/schema/evaluated-response.schema.json",
+  "title": "Evaluated AI response",
+  "type": "object",
+  "required": [
+    "id",
+    "type",
+    "case_id",
+    "selected_level",
+    "behaviors",
+    "avoided",
+    "delivery"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "type": { "const": "evaluated_response" },
+    "case_id": { "type": "string" },
+    "selected_level": { "type": ["integer", "null"], "enum": [0, 1, 2, 3, null] },
+    "behaviors": { "type": "array", "items": { "type": "string" } },
+    "behavior_contract_alignment": { "type": "array", "items": { "type": "string" } },
+    "avoided": { "type": "array", "items": { "type": "string" } },
+    "delivery": { "type": "array", "items": { "type": "string" } },
+    "structured": { "type": "boolean" },
+    "automatic_fail": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schema/evaluation-result.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-research.local/schema/evaluation-result.schema.json",
+  "title": "Evaluation result",
+  "type": "object",
+  "required": [
+    "id",
+    "type",
+    "case_id",
+    "expected_level",
+    "selected_level",
+    "score",
+    "status"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "type": { "const": "evaluation_result" },
+    "case_id": { "type": "string" },
+    "expected_level": { "type": "integer", "enum": [0, 1, 2, 3] },
+    "selected_level": { "type": ["integer", "null"], "enum": [0, 1, 2, 3, null] },
+    "score": {
+      "type": "object",
+      "required": ["total", "max"],
+      "properties": {
+        "total": { "type": "integer" },
+        "max": { "type": "integer" },
+        "by_criteria": { "type": "object" }
+      }
+    },
+    "status": { "type": "string", "enum": ["pass", "partial", "fail"] }
+  }
+}