ai-execution-protocol 0.2.1 → 0.3.1

package/protocol/adaptive-memory.yaml

@@ -0,0 +1,97 @@
+id: adaptive_memory
+type: operational_rules
+version: 0.3
+purpose: evolve_with_user_and_project_through_verified_external_memory
+principle: memory_guides_current_request_authorizes_verified_files_define_reality
+entrypoints:
+  - memory/INDEX.yaml
+  - memory/user/
+  - memory/projects/
+  - memory/patterns/
+  - candidate-memory/
+authority_order:
+  - current_user_request
+  - verified_current_files
+  - active_project_decisions
+  - explicit_user_preferences
+  - inferred_patterns_with_evidence
+  - conversation_summary
+  - old_history
+memory_types:
+  explicit_preference:
+    promotion: automatic_when_non_sensitive_and_explicit
+  project_decision:
+    promotion: automatic_when_confirmed_and_scoped
+  project_state:
+    promotion: require_current_file_evidence
+  inferred_preference:
+    promotion: candidate_until_repeated_or_confirmed
+  workflow_pattern:
+    promotion: candidate_until_repeated
+  conversation_summary:
+    promotion: optional_and_never_mandatory_context
+required_fields:
+  - id
+  - type
+  - subject
+  - value
+  - scope
+  - status
+  - confidence
+  - source
+  - evidence_count
+  - sensitive
+  - created_at
+  - updated_at
+status:
+  active:
+    use: current_memory
+  candidate:
+    use: not_authoritative
+  replaced:
+    use: history_only
+  revoked:
+    use: never_as_current_truth
+  expired:
+    use: revalidate_before_use
+maintenance:
+  always_check_after_task: true
+  allowed_results:
+    - updated
+    - unchanged
+    - candidate
+    - replaced
+    - blocked_sensitive
+  flow:
+    - extract_candidate
+    - classify_sensitivity
+    - search_existing_subject_and_aliases
+    - compare_value_scope_and_source
+    - merge_replace_or_discard
+    - update_index
+    - validate_duplicates_conflicts_and_size
+safety:
+  never_store:
+    - passwords
+    - api_tokens
+    - private_keys
+    - customer_data
+    - unnecessary_personal_data
+    - raw_logs
+    - unredacted_sensitive_conversation
+  prediction:
+    allow:
+      - suggest_likely_preference
+      - choose_low_risk_defaults
+    never:
+      - expand_scope
+      - authorize_sensitive_action
+      - override_current_request
+      - claim_perfect_prediction
+economy:
+  - read_index_before_memory_files
+  - retrieve_only_matching_subjects
+  - do_not_load_archive_by_default
+  - do_not_write_when_result_is_unchanged
+  - keep_one_trackable_subject_per_file
+  - enforce_context_budget

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/context-budget.yaml

@@ -0,0 +1,44 @@
+id: context_budget
+type: operational_rules
+version: 0.3
+purpose: limit_context_cost_without_trading_correctness_or_safety
+principle: budget_guides_reading_risk_can_justify_expansion
+levels:
+  level_0:
+    initial_tokens_est: 300
+    max_files_before_justification: 2
+  level_1:
+    initial_tokens_est: 1000
+    max_files_before_justification: 5
+  level_2:
+    initial_tokens_est: 4000
+    max_files_before_justification: 12
+  level_3:
+    initial_tokens_est: 6000
+    mode: adaptive
+    max_files_before_justification: 20
+count:
+  - protocol_rules
+  - memory_entries
+  - project_docs
+  - code_snippets
+exclude:
+  - generated_reports_not_read
+  - files_only_listed_not_opened
+expansion_requires:
+  - unresolved_risk
+  - missing_dependency
+  - unclear_scope
+  - insufficient_snippet
+  - validation_gap
+stop_when:
+  - objective_is_clear
+  - target_is_identified
+  - risk_is_classified
+  - validation_plan_is_clear
+  - no_unresolved_gap_requires_more_context
+delivery:
+  report_when_exceeded:
+    - initial_budget
+    - estimated_context_used
+    - expansion_reason

package/protocol/context-compiler.yaml

@@ -1,6 +1,6 @@
 id: context_compiler
 type: operational_rules
-version: 0.1
+version: 0.3
 purpose: build_minimum_context_package_before_model_reasoning
 principle: conversation_is_interface_not_source_of_truth
 canonical_state:
@@ -28,19 +28,25 @@ context_build:
     - user_request
     - route_from_router
     - risk_level
+    - context_budget
     - candidate_files_or_areas
+    - matching_memory_subjects
     - recent_validated_state
   output:
     - objective
     - constraints
     - relevant_rules
+    - matching_memory
     - candidate_files
+    - estimated_tokens
+    - budget_status
     - validation_plan
     - excluded_context
 selection_policy:
   include:
     - context_map_domain_when_available
     - active_decisions_for_matched_domain
+    - active_memory_matching_subject_and_scope
     - files_required_by_route
     - snippets_matching_task_terms
     - current_decisions_touching_candidate_area
@@ -51,6 +57,7 @@ selection_policy:
     - full_logs_without_error_focus
     - revoked_decisions_unless_comparing_history
     - entire_large_files_when_snippet_is_enough
+    - candidate_or_archived_memory_without_task_match
 memory_layers:
   active:
     definition: required_to_complete_current_task
@@ -93,6 +100,21 @@ decision_rules:
     avoid:
       - treating_alias_as_source_of_truth
       - editing_from_snippet_when_behavior_depends_on_unread_context
+  - id: CTX_006
+    when: persistent_memory_may_be_relevant
+    do:
+      - read_memory_index_first
+      - retrieve_only_matching_active_entries
+      - verify_project_state_against_current_files
+    avoid:
+      - loading_all_memory
+      - treating_candidate_memory_as_authoritative
+  - id: CTX_007
+    when: initial_context_budget_is_reached
+    do:
+      - stop_if_objective_target_and_validation_are_clear
+      - expand_only_for_unresolved_risk_dependency_scope_or_validation_gap
+      - record_expansion_reason
 retrieval_tiers:
   mvp:
     use:
@@ -121,6 +143,7 @@ delivery:
   include_when_relevant:
     - context_used
     - context_excluded
+    - context_budget_status
     - reason_for_not_reading_more
 economy_goal:
   target: reduce_unneeded_context_up_to_90_percent_when_safe

package/protocol/fast-path.yaml

@@ -1,10 +1,12 @@
 id: fast_path
 type: agent_entrypoint
-version: 0.1
+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
@@ -20,6 +22,10 @@ core_rules:
   - include_test_list_when_break_risk_exists
   - explain_in_plain_language_for_non_experts
   - use_context_compiler_when_context_or_history_is_large
+  - 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
@@ -32,3 +38,4 @@ file_policy:
 stop_reading_when:
   - enough_context_to_act_safely
   - validation_plan_is_clear
+  - context_budget_is_sufficient

package/protocol/persistent-context.yaml

@@ -1,6 +1,6 @@
 id: persistent_context
 type: operational_rules
-version: 0.2
+version: 0.3
 purpose: navigate_project_memory_without_loading_unneeded_context
 principle: aliases_are_pointers_not_truth
 autonomous_memory:
@@ -22,6 +22,7 @@ economy_goal:
 entrypoints:
   - canonical-state.yaml
   - context-map.yaml
+  - memory/INDEX.yaml
   - decisions/
 progressive_retrieval:
   order:
@@ -29,6 +30,8 @@ progressive_retrieval:
     - match_domain_or_alias_in_context_map
     - read_canonical_state_when_project_truth_matters
     - read_active_decisions_for_domain
+    - query_memory_index_for_matching_subjects
+    - read_only_matching_active_memory
     - read_only_needed_atomic_subject_docs
     - search_candidate_symbols_or_files
     - read_relevant_snippet_first
@@ -51,6 +54,8 @@ context_validator:
   check:
     - enough_context_for_objective
     - active_decisions_loaded_when_relevant
+    - matching_memory_loaded_only_when_relevant
+    - context_budget_respected_or_expansion_justified
     - direct_dependencies_loaded_when_needed
     - adjacent_domain_risk_checked
     - docs_do_not_conflict_with_verified_files
@@ -88,9 +93,11 @@ snippet_policy:
 conflict_policy:
   order:
     - current_user_request
-    - canonical_state
-    - active_decisions
     - verified_code_or_files_this_turn
+    - active_decisions
+    - canonical_state
+    - explicit_user_preferences
+    - inferred_patterns_with_evidence
     - domain_docs
     - current_conversation
   if_docs_conflict_with_code:
@@ -100,6 +107,9 @@ validation:
   require:
     - state_context_used_when_relevant
     - state_context_not_loaded_when_excluded_for_economy
+    - memory_index_used_before_memory_files
+    - memory_update_result_recorded_when_new_durable_fact_exists
+    - sensitive_or_unverified_content_not_promoted
     - escalate_context_if_snippet_is_insufficient
     - update_subject_index_when_docs_are_split
 atomic_subject_flow:

package/protocol/prompt-economy.yaml

@@ -1,6 +1,6 @@
 id: prompt_economy
 type: operational_rules
-version: 0.1
+version: 0.3
 purpose: improve_user_prompt_without_token_bloat
 principle: always_improve_prompt_only_as_much_as_needed_for_safe_execution
 rules:
@@ -34,15 +34,20 @@ rules:
       - validation
       - confirmation_if_needed
   - id: PROMPT_005
-    name: always_show_prompt_comparison
+    name: show_prompt_comparison_when_interpretation_matters
     do:
-      - include_user_original_prompt
-      - include_ai_improved_prompt
+      - include_user_original_prompt_for_technical_or_interpreted_tasks
+      - include_ai_improved_prompt_for_technical_or_interpreted_tasks
       - keep_comparison_to_minimum_viable_words
       - preserve_user_language_when_possible
     avoid:
       - hiding_interpretation_from_user
       - expanding_simple_requests_into_large_specs
+    may_omit_when:
+      - level_0
+      - no_technical_action
+      - no_scope_or_intent_interpretation
+      - direct_answer_is_clearer
 limits:
   level_0:
     max_lines: 5
@@ -75,16 +80,19 @@ delivery_rule:
     - "Feito: <what changed or answer>"
     - "Validado: <evidence or not run>"
     - "Risco: <residual risk or none>"
-  always_show:
-    - prompt_original
-    - prompt_melhorado_da_ia
+  show_when:
+    - technical_action
+    - scope_interpretation
+    - risk_level_1_or_higher
+    - prompt_improvement_changes_execution
   comparison:
     - original_prompt_must_keep_user_words_when_reasonable
     - improved_prompt_must_state_objective_scope_risk_validation
     - improved_prompt_must_fit_risk_level_limits
   token_policy:
     - use_abbreviated_labels_po_pm_when_user_did_not_request_full_form
-    - level_0_and_1_use_micro_template
+    - level_0_may_use_direct_answer_when_comparison_adds_no_value
+    - level_1_use_micro_template
     - level_2_use_compact_objective_scope_validation
     - level_3_include_risk_confirmation_without_long_spec
     - omit_tests_line_when_no_break_risk_exists

package/protocol/route-packs.yaml

@@ -1,6 +1,6 @@
 id: route_packs
 type: route_summary_index
-version: 0.1
+version: 0.3.1
 purpose: compact_first_read_before_full_route_files
 principle: read_pack_first_expand_only_when_needed
 use:
@@ -151,3 +151,45 @@ packs:
       - read_atomic_subject_doc_before_broad_doc
       - search_with_rg_before_full_file_reads
       - expand_context_without_expanding_scope
+  memory_update:
+    risk: 1
+    read_if_pack_insufficient:
+      - adaptive-memory.yaml
+      - context-budget.yaml
+      - validation-checklist.yaml
+    do:
+      - extract_only_stable_non_sensitive_knowledge
+      - search_before_create
+      - merge_replace_or_keep_unchanged
+      - update_memory_index
+      - report_memory_update_result
+  memory_conflict_or_replacement:
+    risk: 2
+    read_if_pack_insufficient:
+      - adaptive-memory.yaml
+      - context-compiler.yaml
+      - validation-checklist.yaml
+    do:
+      - preserve_provenance
+      - mark_old_entry_replaced
+      - keep_current_request_authoritative
+      - validate_no_duplicate_active_entry
+  selective_validation:
+    risk: 1
+    read_if_pack_insufficient:
+      - selective-validation.yaml
+    do:
+      - 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.1
+version: 0.3.1
 purpose: choose_minimum_protocol_files_by_task
 default_read:
   - fast-path.yaml
@@ -93,11 +93,40 @@ routes:
       - persistent-context.yaml
       - context-rules.yaml
       - context-compiler.yaml
+      - context-budget.yaml
+  memory_update:
+    risk: 1
+    read:
+      - fast-path.yaml
+      - adaptive-memory.yaml
+      - context-budget.yaml
+      - validation-checklist.yaml
+  memory_conflict_or_replacement:
+    risk: 2
+    read:
+      - fast-path.yaml
+      - adaptive-memory.yaml
+      - context-compiler.yaml
+      - validation-checklist.yaml
+  selective_validation:
+    risk: 1
+    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
   - read_route_pack_before_full_route_files_when_available
   - 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/protocol/selective-validation.yaml

@@ -0,0 +1,44 @@
+id: selective_validation
+type: operational_rules
+version: 0.3
+purpose: run_smallest_validation_set_that_proves_the_change
+principle: validation_scales_with_behavior_and_blast_radius
+selection:
+  docs_only:
+    run:
+      - link_check
+      - text_search
+      - schema_if_structured
+  protocol_rule:
+    run:
+      - schema_validation
+      - mirror_sync
+      - framework_targeted_tests
+  parser_or_evaluator:
+    run:
+      - parser_adversarial_tests
+      - framework_tests
+      - benchmark_runner
+  installer_or_package:
+    run:
+      - install_test
+      - verify_install
+      - package_dry_run
+  shared_or_cross_module:
+    run:
+      - framework_tests
+      - health_check
+  release:
+    run:
+      - framework_tests
+      - schema_strict
+      - health_check
+      - npm_dry_run
+      - python_build
+      - twine_check
+rules:
+  - infer_validation_from_changed_files_and_behavior
+  - expand_validation_when_shared_contract_changes
+  - never_claim_unrun_validation
+  - full_health_check_is_not_required_for_every_small_change
+  - user_visible_or_critical_change_requires_manual_test_guidance

package/protocol/validation-checklist.yaml

@@ -1,6 +1,7 @@
 id: validation_checklist
 type: checklist
-version: 0.1
+version: 0.3
+selection_source: protocol/selective-validation.yaml
 automatic_validation:
   - unit_tests
   - integration_tests
@@ -57,3 +58,11 @@ rules:
       - make_limits_and_residual_risk_understandable
       - prefer_one_line_per_delivery_field
       - use_micro_format_only_when_readable
+  - id: VAL_005
+    always:
+      - select_smallest_validation_set_that_proves_behavior
+      - expand_when_shared_contract_or_blast_radius_requires
+      - record_every_expected_validation_not_run
+    avoid:
+      - full_health_check_for_trivial_local_change
+      - unrelated_expensive_validation