ai-execution-protocol 0.2.0 → 0.3.0

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

@@ -5,6 +5,7 @@ context_policy:
   use: minimum_sufficient_context
   prefer:
     - context_map_before_domain_docs
+    - atomic_subject_docs_before_broad_docs
     - aliases_for_search_not_truth
     - targeted_search
     - relevant_snippets
@@ -16,12 +17,24 @@ context_policy:
     - mixing_old_and_current_docs
     - treating_conversation_as_source_of_truth
     - treating_aliases_as_verified_behavior
+    - reading_broad_docs_when_atomic_subject_doc_exists
 file_size:
   max_lines: 400
   when_near_limit:
     - split_by_subject
     - keep_main_file_short
     - update_index
+subject_docs:
+  rule: docs_should_be_grouped_by_searchable_subject_not_only_by_size
+  do:
+    - create_or_update_one_doc_per_domain_flow_decision_or_component
+    - use_filename_terms_that_match_likely_user_requests_and_code_symbols
+    - use_rg_to_find_exact_code_symbols_after_reading_subject_doc
+    - verify_code_before_treating_doc_as_truth
+  avoid:
+    - fragmenting_into_micro_docs_without_standalone_subject
+    - duplicating_same_subject_across_docs
+    - keeping_cross_domain_docs_without_links_to_specific_subject_docs
 memory:
   record:
     - stable_decision

package/protocol/fast-path.yaml

@@ -1,9 +1,11 @@
 id: fast_path
 type: agent_entrypoint
-version: 0.1
+version: 0.3
 purpose: minimum_rules_to_start_any_task
 read_next:
   - router.yaml
+  - route-packs.yaml
+  - context-budget.yaml
   - modes.yaml
 core_rules:
   - classify_risk_before_action
@@ -19,6 +21,9 @@ 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
 risk_short:
   level_0: answer_only
   level_1: small_clear_reversible_isolated_change
@@ -31,3 +36,4 @@ file_policy:
 stop_reading_when:
   - enough_context_to_act_safely
   - validation_plan_is_clear
+  - context_budget_is_sufficient

package/protocol/formatting-rules.yaml

@@ -6,6 +6,7 @@ priority:
   second: human_readability
 principles:
   - one_main_subject_per_file
+  - atomic_docs_by_trackable_subject
   - stable_keys
   - direct_names
   - short_lists
@@ -73,3 +74,29 @@ maintenance:
   if_near_limit:
     - split_by_theme
     - update_readme
+atomic_documentation:
+  principle: one_file_one_trackable_subject
+  use_for:
+    - domain
+    - flow
+    - decision
+    - component
+    - integration
+    - validation_area
+  naming:
+    do:
+      - include_search_terms_in_filename
+      - prefer_domain_flow_or_component_names
+      - keep_titles_matching_filename_subject
+    avoid:
+      - generic_names_like_general_notes_part1
+      - duplicate_files_for_same_subject
+      - oversized_docs_with_multiple_unrelated_subjects
+  split_when:
+    - file_has_multiple_independent_subjects
+    - file_nears_line_limit
+    - rg_search_would_match_unrelated_sections
+  update_when_split:
+    - docs_readme
+    - index_or_context_map_when_relevant
+    - aliases_when_subject_terms_change

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,7 +30,9 @@ progressive_retrieval:
     - match_domain_or_alias_in_context_map
     - read_canonical_state_when_project_truth_matters
     - read_active_decisions_for_domain
-    - read_only_needed_domain_docs
+    - 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
     - read_direct_dependencies_when_needed
@@ -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,4 +107,33 @@ 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:
+  order:
+    - identify_subject_terms_from_request
+    - find_subject_doc_by_context_map_index_or_rg
+    - read_subject_doc_before_broad_doc
+    - use_rg_for_exact_code_symbol_or_term
+    - read_code_snippet_first
+    - expand_to_full_file_or_related_doc_when_needed
+  failure_mitigations:
+    fragmentation:
+      - do_not_create_doc_for_micro_detail_without_standalone_subject
+      - merge_or_link_overlapping_docs
+    bad_names:
+      - include_domain_flow_component_or_symbol_terms_in_filename
+    duplicates:
+      - search_existing_docs_before_creating_new_doc
+      - prefer_updating_existing_subject_doc
+    stale_docs:
+      - verify_current_code_before_behavior_claim
+      - report_stale_doc_risk
+    wrong_search_terms:
+      - use_aliases_and_synonyms_as_search_terms
+      - search_docs_and_code_with_rg
+    insufficient_snippet:
+      - expand_to_imports_types_callers_or_full_file

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

@@ -0,0 +1,184 @@
+id: route_packs
+type: route_summary_index
+version: 0.3
+purpose: compact_first_read_before_full_route_files
+principle: read_pack_first_expand_only_when_needed
+use:
+  - after_router_selects_route
+  - before_opening_all_route_files
+  - when_task_is_clear_enough_for_compact_rules
+expand_when:
+  - risk_or_scope_is_unclear
+  - validation_plan_is_not_clear
+  - route_pack_conflicts_with_user_request
+  - task_is_level_2_or_3_and_impact_is_not_mapped
+  - yaml_schema_or_exact_rule_text_is_needed
+packs:
+  simple_answer:
+    risk: 0
+    read_if_pack_insufficient:
+      - fast-path.yaml
+    do:
+      - answer_directly
+      - avoid_plan_or_file_reads
+      - keep_po_pm_ok_short_when_required
+  small_fix:
+    risk: 1
+    read_if_pack_insufficient:
+      - fast-path.yaml
+      - validation-checklist.yaml
+    do:
+      - identify_small_reversible_target
+      - read_focused_context
+      - change_minimum_needed
+      - validate_directly
+  user_flow_bug:
+    risk: 2
+    read_if_pack_insufficient:
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+    do:
+      - map_flow_candidate_files_and_regression_risk
+      - read_snippets_before_full_files
+      - preserve_expected_behavior
+      - validate_main_success_and_failure_paths
+  refactor:
+    risk: 2
+    read_if_pack_insufficient:
+      - context-compiler.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+      - spec-driven.yaml
+    do:
+      - define_behavior_to_preserve
+      - keep_scope_incremental
+      - avoid_new_features
+      - validate_behavior_after_change
+  feature_or_spec:
+    risk: 2
+    read_if_pack_insufficient:
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+      - spec-driven.yaml
+    do:
+      - use_light_spec_when_scope_or_risk_benefits
+      - define_objective_scope_validation
+      - implement_incrementally
+      - avoid_full_spec_for_small_clear_tasks
+  docs_update:
+    risk: 1
+    read_if_pack_insufficient:
+      - context-rules.yaml
+      - formatting-rules.yaml
+    do:
+      - update_only_affected_docs
+      - keep_docs_atomic_by_subject
+      - verify_links_or_references
+      - update_index_when_structure_changes
+  database_or_data:
+    risk: 3
+    read_if_pack_insufficient:
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+      - spec-driven.yaml
+    do:
+      - map_affected_data
+      - avoid_destructive_action_without_confirmation
+      - define_backup_or_rollback
+      - validate_before_and_after
+  auth_security_secret:
+    risk: 3
+    read_if_pack_insufficient:
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+      - spec-driven.yaml
+    do:
+      - map_security_surface
+      - avoid_exposing_secrets
+      - require_confirmation_for_sensitive_write
+      - validate_allowed_and_denied_paths
+  deploy_or_production:
+    risk: 3
+    read_if_pack_insufficient:
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - validation-checklist.yaml
+      - context-rules.yaml
+      - spec-driven.yaml
+    do:
+      - verify_local_state
+      - run_pre_deploy_validation
+      - require_confirmation_before_deploy
+      - run_post_deploy_check_if_executed
+  evaluate_response:
+    read_if_pack_insufficient:
+      - ../eval/rubric.yaml
+      - ../schema/evaluated-response.schema.json
+    do:
+      - score_risk_behavior_avoidance_delivery_clarity
+      - apply_automatic_fail_rules
+  create_or_edit_yaml:
+    read_if_pack_insufficient:
+      - formatting-rules.yaml
+      - ../schema/protocol-rule.schema.yaml
+    do:
+      - keep_yaml_compact
+      - validate_schema_when_available
+      - update_index_when_new_file_is_added
+  prompt_improvement:
+    read_if_pack_insufficient:
+      - prompt-economy.yaml
+    do:
+      - preserve_user_intent
+      - improve_only_as_much_as_needed
+      - keep_prompt_proportional_to_risk
+      - avoid_long_specs_for_simple_tasks
+  context_optimization:
+    read_if_pack_insufficient:
+      - persistent-context.yaml
+      - context-rules.yaml
+      - context-compiler.yaml
+    do:
+      - use_context_map_and_aliases_as_pointers
+      - 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

package/protocol/router.yaml

@@ -1,6 +1,6 @@
 id: protocol_router
 type: read_router
-version: 0.1
+version: 0.3
 purpose: choose_minimum_protocol_files_by_task
 default_read:
   - fast-path.yaml
@@ -93,9 +93,33 @@ 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
 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
   - 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

package/scripts/README.md

@@ -47,6 +47,32 @@ Para medir uma rota especifica:
 python scripts/token_report.py --route user_flow_bug --out results/token-user-flow-bug.yaml
 ```
 
+## context_package.py
+
+Gera um pacote de contexto limitado por risco, rota, memoria e candidatos.
+
+```powershell
+python scripts/context_package.py --objective "Revisar memoria" --route memory_update --risk 2 --term memory
+```
+
+## memory_manager.py
+
+Inclui, consulta e valida memoria adaptativa com deduplicacao e bloqueio de
+conteudo sensivel.
+
+```powershell
+python scripts/memory_manager.py --root . validate
+```
+
+## selective_validation.py
+
+Seleciona as verificacoes proporcionais aos arquivos alterados.
+
+```powershell
+python scripts/selective_validation.py
+python scripts/selective_validation.py --release
+```
+
 ## health_check.py
 
 Roda a validacao geral do framework.
@@ -102,6 +128,23 @@ python scripts/framework_tests.py
 
 O relatorio fica em `results/framework-test-report.yaml`.
 
+## v03_tests.py
+
+Testa memoria, orcamento de contexto, validacao seletiva e manifesto de
+instalacao.
+
+```powershell
+python scripts/v03_tests.py
+```
+
+## context_economy_benchmark.py
+
+Compara leitura ampla com rotas focadas da v0.3.0.
+
+```powershell
+python scripts/context_economy_benchmark.py
+```
+
 ## build_dist.py
 
 Gera `dist/minimal/` a partir de `AGENTS.md` minimo e `protocol/`.