ai-execution-protocol 0.1.0 → 0.2.1

package/protocol/README.yaml

@@ -1,7 +1,7 @@
 id: protocol_index
 type: index
 format: yaml
-protocol_version: 0.1.0
+protocol_version: 0.2.1
 purpose: ai_operational_rules
 source_docs: ../docs
 constraints:
@@ -13,6 +13,8 @@ files:
     purpose: minimum_rules_to_start_any_task
   - path: router.yaml
     purpose: choose_minimum_files_to_read_by_task
+  - path: route-packs.yaml
+    purpose: compact_first_read_before_full_route_files
   - path: modes.yaml
     purpose: choose_fast_balanced_or_strict_behavior
   - path: execution-rules.yaml
@@ -27,6 +29,8 @@ files:
     purpose: context_window_file_size_memory
   - path: context-compiler.yaml
     purpose: compile_minimum_context_package_and_canonical_state
+  - path: persistent-context.yaml
+    purpose: progressive_context_retrieval_with_aliases
   - path: formatting-rules.yaml
     purpose: ai_readable_file_format
   - path: prompt-economy.yaml

package/protocol/context-compiler.yaml

@@ -6,6 +6,8 @@ principle: conversation_is_interface_not_source_of_truth
 canonical_state:
   read_first:
     - AGENTS.md
+    - canonical-state.yaml
+    - context-map.yaml
     - INDEX.yaml
     - config.yaml
     - protocol/fast-path.yaml
@@ -37,6 +39,8 @@ context_build:
     - excluded_context
 selection_policy:
   include:
+    - context_map_domain_when_available
+    - active_decisions_for_matched_domain
     - files_required_by_route
     - snippets_matching_task_terms
     - current_decisions_touching_candidate_area
@@ -81,9 +85,19 @@ decision_rules:
     when: context_gap_blocks_safe_execution
     do:
       - ask_one_short_question_or_read_next_mapped_file
+  - id: CTX_005
+    when: alias_or_snippet_seems_sufficient
+    do:
+      - verify_against_current_file_state_before_editing
+      - escalate_to_full_file_when_imports_types_or_side_effects_matter
+    avoid:
+      - treating_alias_as_source_of_truth
+      - editing_from_snippet_when_behavior_depends_on_unread_context
 retrieval_tiers:
   mvp:
     use:
+      - canonical-state.yaml
+      - context-map.yaml
       - INDEX.yaml
       - router.yaml
       - targeted_search
@@ -108,3 +122,10 @@ delivery:
     - context_used
     - context_excluded
     - reason_for_not_reading_more
+economy_goal:
+  target: reduce_unneeded_context_up_to_90_percent_when_safe
+  never_trade_off:
+    - correctness
+    - security
+    - validation
+    - risk_classification

package/protocol/context-rules.yaml

@@ -4,6 +4,9 @@ version: 0.1
 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
     - current_state_over_old_history
@@ -13,12 +16,25 @@ context_policy:
     - repeating_long_rules_in_chat
     - 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

@@ -4,6 +4,7 @@ version: 0.1
 purpose: minimum_rules_to_start_any_task
 read_next:
   - router.yaml
+  - route-packs.yaml
   - modes.yaml
 core_rules:
   - classify_risk_before_action

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

@@ -0,0 +1,129 @@
+id: persistent_context
+type: operational_rules
+version: 0.2
+purpose: navigate_project_memory_without_loading_unneeded_context
+principle: aliases_are_pointers_not_truth
+autonomous_memory:
+  target: generate_memory_from_project_state_without_manual_maintenance
+  current_safe_stage: bootstrap_with_small_verified_artifacts
+  promote_to_required_only_when:
+    - indexer_exists
+    - generated_output_is_reproducible
+    - stale_output_can_be_detected
+    - validation_passes_in_real_projects
+economy_goal:
+  target: reduce_unneeded_context_up_to_90_percent_when_safe
+  meaning: reduce_irrelevant_context_not_required_context
+  stop_condition:
+    - objective_is_clear
+    - candidate_area_is_mapped
+    - validation_plan_is_clear
+    - no_unresolved_risk_requires_more_context
+entrypoints:
+  - canonical-state.yaml
+  - context-map.yaml
+  - decisions/
+progressive_retrieval:
+  order:
+    - identify_objective
+    - match_domain_or_alias_in_context_map
+    - read_canonical_state_when_project_truth_matters
+    - read_active_decisions_for_domain
+    - read_only_needed_atomic_subject_docs
+    - search_candidate_symbols_or_files
+    - read_relevant_snippet_first
+    - read_direct_dependencies_when_needed
+    - read_full_file_when_snippet_is_not_enough
+confidence_policy:
+  high:
+    threshold: enough_context_to_act_and_validate
+    do:
+      - execute_with_current_context
+  medium:
+    threshold: likely_context_gap_or_adjacent_dependency
+    do:
+      - expand_one_retrieval_level
+  low:
+    threshold: ambiguous_intent_or_missing_target
+    do:
+      - ask_clarifying_question
+context_validator:
+  check:
+    - enough_context_for_objective
+    - active_decisions_loaded_when_relevant
+    - direct_dependencies_loaded_when_needed
+    - adjacent_domain_risk_checked
+    - docs_do_not_conflict_with_verified_files
+  if_gap_found:
+    - expand_context_not_scope
+action_validator:
+  require:
+    - target_is_identified
+    - expected_result_is_clear
+    - impact_is_mapped_for_level_2_or_3
+    - validation_plan_exists
+  if_intent_is_ambiguous:
+    - ask_user_before_editing
+  rule: context_can_expand_scope_cannot_expand
+alias_policy:
+  use_aliases_for:
+    - domain_routing
+    - symbol_search_terms
+    - dependency_search_terms
+    - recent_context_labels
+  never_use_aliases_as:
+    - proof_of_current_behavior
+    - replacement_for_code_or_verified_files
+    - permission_to_edit_without_mapping
+snippet_policy:
+  prefer:
+    - targeted_search
+    - symbol_or_function_snippet
+    - nearby_imports_types_and_callers_when_needed
+  read_full_file_when:
+    - imports_or_types_change_meaning
+    - side_effects_or_shared_state_matter
+    - snippet_boundaries_are_unclear
+    - edit_risk_is_level_2_or_3_and_file_is_candidate
+conflict_policy:
+  order:
+    - current_user_request
+    - canonical_state
+    - active_decisions
+    - verified_code_or_files_this_turn
+    - domain_docs
+    - current_conversation
+  if_docs_conflict_with_code:
+    - trust_verified_code_for_behavior
+    - report_stale_doc_risk
+validation:
+  require:
+    - state_context_used_when_relevant
+    - state_context_not_loaded_when_excluded_for_economy
+    - 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/risk-levels.yaml

@@ -65,6 +65,24 @@ levels:
 escalation:
   rule: raise_level_when_new_risk_evidence_appears
   never: lower_level_by_ignoring_known_risk
+proportional_classification:
+  principle: start_with_lowest_safe_level_and_escalate_only_with_evidence
+  do:
+    - classify_the_user_request_before_reading_large_context
+    - keep_scope_small_when_task_is_clear_and_reversible
+    - escalate_when_new_risk_evidence_appears
+    - classify_split_subtasks_by_their_own_executable_scope
+  avoid:
+    - treating_every_multi_step_task_as_level_3
+    - loading_critical_context_before_critical_risk_is_evident
+    - downgrading_known_risk_to_save_tokens
+  escalation_triggers:
+    - real_data_or_customer_data
+    - auth_or_permission_change
+    - database_or_destructive_command
+    - deploy_or_production_change
+    - secrets_or_tokens
+    - unclear_impact_on_existing_flow
 blocked_critical_scope:
   principle: do_not_lower_original_risk_because_sensitive_action_is_blocked
   when:

package/protocol/route-packs.yaml

@@ -0,0 +1,153 @@
+id: route_packs
+type: route_summary_index
+version: 0.1
+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

package/protocol/router.yaml

@@ -90,11 +90,14 @@ routes:
   context_optimization:
     read:
       - fast-path.yaml
+      - persistent-context.yaml
       - context-rules.yaml
       - context-compiler.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
   - 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/build_dist.py

@@ -16,6 +16,7 @@ PROTOCOL_FILES = [
     "README.yaml",
     "fast-path.yaml",
     "router.yaml",
+    "route-packs.yaml",
     "modes.yaml",
     "execution-rules.yaml",
     "risk-levels.yaml",
@@ -23,6 +24,7 @@ PROTOCOL_FILES = [
     "validation-checklist.yaml",
     "context-rules.yaml",
     "context-compiler.yaml",
+    "persistent-context.yaml",
     "formatting-rules.yaml",
     "prompt-economy.yaml",
     "spec-driven.yaml",
@@ -46,13 +48,15 @@ editar, classifique risco, escolha rota e valide a entrega.
 
 1. `protocol/fast-path.yaml`
 2. `protocol/router.yaml`
-3. Arquivo YAML especifico em `protocol/` conforme a rota.
+3. `protocol/route-packs.yaml` para ler o resumo compacto da rota.
+4. Arquivo YAML especifico em `protocol/` somente quando o pack nao bastar.
 
 ## Regras de execucao
 
 - Classifique o risco antes de agir.
 - Use o menor contexto suficiente.
 - Leia apenas os arquivos indicados por `protocol/router.yaml`.
+- Use `protocol/route-packs.yaml` antes de abrir todos os arquivos da rota.
 - Quando houver contexto grande, historico longo ou risco de confusao, use
   `protocol/context-compiler.yaml` antes de abrir muitos arquivos.
 - Use `protocol/spec-driven.yaml` para feature, refatoracao grande ou tarefa
@@ -167,6 +171,56 @@ scripts/__pycache__/
 """
 
 
+MINIMAL_CANONICAL_STATE = """id: canonical_state
+type: project_state
+version: 0.1
+purpose: small_current_truth_summary_for_ai_navigation
+status: bootstrap_template
+truth_order:
+  - current_user_request
+  - verified_current_files
+  - protocol_rules
+  - project_docs
+  - conversation_history
+notes:
+  - update_this_file_when_project_state_or_decisions_change
+  - do_not_treat_this_file_as_truth_without_current_file_verification
+"""
+
+
+MINIMAL_CONTEXT_MAP = """id: project_context_map
+type: context_map
+version: 0.1
+purpose: small_index_for_progressive_context_retrieval
+maintenance:
+  current_mode: manual_bootstrap
+  rule: aliases_are_pointers_not_truth
+read_first:
+  - canonical-state.yaml
+  - protocol/fast-path.yaml
+  - protocol/router.yaml
+  - protocol/route-packs.yaml
+domains: {}
+retrieval_policy:
+  order:
+    - match_domain_by_alias
+    - read_domain_docs_only_when_needed
+    - search_candidate_files_or_symbols
+    - read_relevant_snippet_first
+    - read_full_file_when_snippet_is_not_enough
+"""
+
+
+MINIMAL_DECISIONS_README = """# Decisions
+
+Use esta pasta para registrar decisoes estaveis que a IA deve considerar ao
+mapear contexto.
+
+Cada decisao deve indicar status, escopo, impacto e arquivo relacionado quando
+existir.
+"""
+
+
 def main() -> int:
     if DIST.exists():
         shutil.rmtree(DIST)
@@ -178,6 +232,10 @@ def main() -> int:
     (DIST / "AGENTS.md").write_text(MINIMAL_AGENTS, encoding="utf-8")
     (DIST / "README.md").write_text(MINIMAL_README, encoding="utf-8")
     (DIST / ".aiignore").write_text(MINIMAL_AIIGNORE, encoding="utf-8")
+    (DIST / "canonical-state.yaml").write_text(MINIMAL_CANONICAL_STATE, encoding="utf-8")
+    (DIST / "context-map.yaml").write_text(MINIMAL_CONTEXT_MAP, encoding="utf-8")
+    (DIST / "decisions").mkdir(parents=True, exist_ok=True)
+    (DIST / "decisions" / "README.md").write_text(MINIMAL_DECISIONS_README, encoding="utf-8")
     for name in PROTOCOL_FILES:
         shutil.copy2(ROOT / "protocol" / name, DIST / "protocol" / name)
         shutil.copy2(ROOT / "protocol" / name, PYTHON_PACKAGE_PROTOCOL / name)