ai-execution-protocol 0.1.0 → 0.2.0

package/README.md

@@ -14,6 +14,7 @@ O framework ajuda a IA a:
 
 - entender a intencao antes de agir;
 - classificar o risco da tarefa;
+- localizar o dominio certo antes de abrir arquivos grandes;
 - ler apenas o contexto necessario;
 - mapear impacto antes de alterar arquivos;
 - pedir confirmacao em acoes sensiveis;
@@ -30,6 +31,16 @@ 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.2.0, o framework adiciona uma camada leve de contexto persistente:
+
+```text
+pedido -> intencao -> dominio -> contexto minimo -> validacao -> acao
+```
+
+Essa camada usa `canonical-state.yaml`, `context-map.yaml`, `decisions/` e
+`protocol/persistent-context.yaml` para reduzir leitura desnecessaria. Ela e um
+bootstrap seguro, nao um indexador automatico completo.
+
 ## Status
 
 Projeto em fase de pesquisa e evolucao.
@@ -42,7 +53,10 @@ continuam obrigatorios em tarefas criticas.
 
 - `AGENTS.md`: instrucao principal para agentes no projeto.
 - `INDEX.yaml`: mapa estruturado para navegacao rapida.
+- `canonical-state.yaml`: estado atual resumido e ordem de verdade.
+- `context-map.yaml`: mapa pequeno de dominios, aliases e arquivos candidatos.
 - `config.yaml`: configuracao do alvo atual e versao do protocolo.
+- `decisions/`: decisoes importantes com status.
 - `docs/`: explicacoes conceituais em Markdown.
 - `protocol/`: regras operacionais curtas em YAML.
 - `cases/`: casos estruturados para testar o comportamento da IA.
@@ -59,11 +73,24 @@ continuam obrigatorios em tarefas criticas.
 ## Como usar como agente
 
 1. Leia `INDEX.yaml`.
-2. Confirme o alvo atual em `config.yaml`.
-3. Leia `protocol/fast-path.yaml`.
-4. Use `protocol/router.yaml` para escolher o menor contexto suficiente.
-5. Abra apenas os arquivos indicados pela rota.
-6. Execute, valide e entregue com evidencia.
+2. Confirme o estado atual em `canonical-state.yaml` quando a verdade do
+   projeto importar.
+3. Use `context-map.yaml` para localizar dominio e aliases provaveis.
+4. Confirme o alvo atual em `config.yaml`.
+5. Leia `protocol/fast-path.yaml`.
+6. Use `protocol/router.yaml` para escolher o menor contexto suficiente.
+7. Abra apenas os arquivos indicados pela rota ou pela recuperacao progressiva.
+8. Execute, valide e entregue com evidencia.
+
+Regra de seguranca da v0.2.0:
+
+```text
+A IA pode expandir contexto.
+A IA nao pode expandir escopo.
+```
+
+Aliases, mapas e decisoes ajudam a navegar. Eles nao substituem verificacao no
+codigo ou nos arquivos atuais antes de alterar comportamento.
 
 ## Como estudar o framework
 
@@ -73,8 +100,11 @@ Comece por:
 - `docs/01-modelo-de-execucao.md`
 - `docs/02-niveis-de-risco.md`
 - `docs/03-mapeamento-antes-de-alterar.md`
+- `docs/04-janela-de-contexto.md`
 - `docs/05-validacao-e-entrega.md`
+- `docs/15-contexto-persistente.md`
 - `docs/14-publicacao.md`
+- `docs/16-release-e-atualizacao.md`
 
 Use `docs/` para entender a metodologia. Use `protocol/` quando quiser aplicar
 as regras em uma tarefa real.
@@ -144,6 +174,7 @@ O final esperado da verificacao e `PASS`.
 ## Publicacao
 
 Antes de publicar, revise `docs/14-publicacao.md`.
+Para atualizar uma versao ja publicada, revise `docs/16-release-e-atualizacao.md`.
 
 Resumo minimo:
 

package/dist/minimal/protocol/README.yaml

@@ -1,7 +1,7 @@
 id: protocol_index
 type: index
 format: yaml
-protocol_version: 0.1.0
+protocol_version: 0.2.0
 purpose: ai_operational_rules
 source_docs: ../docs
 constraints:
@@ -27,6 +27,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/dist/minimal/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/dist/minimal/protocol/context-rules.yaml

@@ -4,6 +4,8 @@ version: 0.1
 context_policy:
   use: minimum_sufficient_context
   prefer:
+    - context_map_before_domain_docs
+    - aliases_for_search_not_truth
     - targeted_search
     - relevant_snippets
     - current_state_over_old_history
@@ -13,6 +15,7 @@ context_policy:
     - repeating_long_rules_in_chat
     - mixing_old_and_current_docs
     - treating_conversation_as_source_of_truth
+    - treating_aliases_as_verified_behavior
 file_size:
   max_lines: 400
   when_near_limit:

package/dist/minimal/protocol/persistent-context.yaml

@@ -0,0 +1,103 @@
+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_domain_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

package/dist/minimal/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/dist/minimal/protocol/router.yaml

@@ -90,6 +90,7 @@ routes:
   context_optimization:
     read:
       - fast-path.yaml
+      - persistent-context.yaml
       - context-rules.yaml
       - context-compiler.yaml
 rules:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-execution-protocol",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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.1.0
+protocol_version: 0.2.0
 purpose: ai_operational_rules
 source_docs: ../docs
 constraints:
@@ -27,6 +27,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,8 @@ version: 0.1
 context_policy:
   use: minimum_sufficient_context
   prefer:
+    - context_map_before_domain_docs
+    - aliases_for_search_not_truth
     - targeted_search
     - relevant_snippets
     - current_state_over_old_history
@@ -13,6 +15,7 @@ context_policy:
     - repeating_long_rules_in_chat
     - mixing_old_and_current_docs
     - treating_conversation_as_source_of_truth
+    - treating_aliases_as_verified_behavior
 file_size:
   max_lines: 400
   when_near_limit:

package/protocol/persistent-context.yaml

@@ -0,0 +1,103 @@
+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_domain_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

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/router.yaml

@@ -90,6 +90,7 @@ routes:
   context_optimization:
     read:
       - fast-path.yaml
+      - persistent-context.yaml
       - context-rules.yaml
       - context-compiler.yaml
 rules:

package/scripts/build_dist.py

@@ -23,6 +23,7 @@ PROTOCOL_FILES = [
     "validation-checklist.yaml",
     "context-rules.yaml",
     "context-compiler.yaml",
+    "persistent-context.yaml",
     "formatting-rules.yaml",
     "prompt-economy.yaml",
     "spec-driven.yaml",

package/scripts/npm_install_protocol.js

@@ -17,6 +17,7 @@ const protocolFiles = [
   "validation-checklist.yaml",
   "context-rules.yaml",
   "context-compiler.yaml",
+  "persistent-context.yaml",
   "formatting-rules.yaml",
   "prompt-economy.yaml",
   "spec-driven.yaml",

package/scripts/verify_install.py

@@ -20,6 +20,7 @@ REQUIRED_FILES = [
     "protocol/validation-checklist.yaml",
     "protocol/context-rules.yaml",
     "protocol/context-compiler.yaml",
+    "protocol/persistent-context.yaml",
     "protocol/formatting-rules.yaml",
     "protocol/prompt-economy.yaml",
     "protocol/spec-driven.yaml",