ai-execution-protocol 0.2.0 → 0.2.1

package/AGENTS.md

@@ -24,7 +24,8 @@ metodologia. Para executar tarefas, prefira as regras curtas em `protocol/`.
 
 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:
    - `README.yaml`
    - `modes.yaml`
    - `execution-rules.yaml`
@@ -33,6 +34,7 @@ metodologia. Para executar tarefas, prefira as regras curtas em `protocol/`.
    - `validation-checklist.yaml`
    - `context-rules.yaml`
    - `context-compiler.yaml`
+   - `route-packs.yaml`
    - `formatting-rules.yaml`
    - `prompt-economy.yaml`
    - `spec-driven.yaml`
@@ -54,6 +56,7 @@ metodologia. Para executar tarefas, prefira as regras curtas em `protocol/`.
 - 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.
 - Siga `.aiignore` e `INDEX.yaml/read_policy.ignore_by_default` antes de abrir

package/README.md

@@ -59,6 +59,7 @@ continuam obrigatorios em tarefas criticas.
 - `decisions/`: decisoes importantes com status.
 - `docs/`: explicacoes conceituais em Markdown.
 - `protocol/`: regras operacionais curtas em YAML.
+- `protocol/route-packs.yaml`: resumos compactos para reduzir leitura por rota.
 - `cases/`: casos estruturados para testar o comportamento da IA.
 - `examples/`: exemplos humanos de uso do framework.
 - `schema/`: contratos para manter os YAML padronizados.
@@ -79,8 +80,9 @@ continuam obrigatorios em tarefas criticas.
 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.
+7. Consulte `protocol/route-packs.yaml` antes de abrir todos os YAML da rota.
+8. Abra arquivos completos apenas quando o resumo compacto nao bastar.
+9. Execute, valide e entregue com evidencia.
 
 Regra de seguranca da v0.2.0:
 
@@ -103,8 +105,7 @@ Comece por:
 - `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`
+- `docs/17-documentacao-atomica.md`
 
 Use `docs/` para entender a metodologia. Use `protocol/` quando quiser aplicar
 as regras em uma tarefa real.
@@ -171,20 +172,6 @@ python scripts/verify_install.py --target C:\caminho\projeto
 
 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:
-
-- nao publique `.env`, chaves, tokens, senhas, logs reais ou dados de cliente;
-- mantenha artefatos gerados fora do Git quando nao forem necessarios;
-- use `.gitignore`;
-- publique com `README.md`, `LICENSE`, `docs/`, `protocol/`, `cases/`,
-  `examples/`, `schema/`, `eval/` e `scripts/` quando fizer sentido;
-- preserve o posicionamento como pesquisa experimental e framework em evolucao.
-
 ## Licenca
 
 Distribuido sob a licenca MIT. Veja `LICENSE`.

package/dist/minimal/AGENTS.md

@@ -15,13 +15,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

package/dist/minimal/canonical-state.yaml

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

package/dist/minimal/context-map.yaml

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

package/dist/minimal/decisions/README.md

@@ -0,0 +1,7 @@
+# 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.

package/dist/minimal/protocol/README.yaml

@@ -1,7 +1,7 @@
 id: protocol_index
 type: index
 format: yaml
-protocol_version: 0.2.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

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

@@ -29,7 +29,7 @@ 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
+    - read_only_needed_atomic_subject_docs
     - search_candidate_symbols_or_files
     - read_relevant_snippet_first
     - read_direct_dependencies_when_needed
@@ -101,3 +101,29 @@ validation:
     - 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/dist/minimal/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/dist/minimal/protocol/router.yaml

@@ -96,6 +96,8 @@ routes:
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-execution-protocol",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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.2.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

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

@@ -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

@@ -29,7 +29,7 @@ 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
+    - read_only_needed_atomic_subject_docs
     - search_candidate_symbols_or_files
     - read_relevant_snippet_first
     - read_direct_dependencies_when_needed
@@ -101,3 +101,29 @@ validation:
     - 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/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

@@ -96,6 +96,8 @@ routes:
 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",
@@ -47,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
@@ -168,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)
@@ -179,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)

package/scripts/npm_install_protocol.js

@@ -10,6 +10,7 @@ const protocolFiles = [
   "README.yaml",
   "fast-path.yaml",
   "router.yaml",
+  "route-packs.yaml",
   "modes.yaml",
   "execution-rules.yaml",
   "risk-levels.yaml",
@@ -30,6 +31,50 @@ const aiignoreLines = [
   "scripts/__pycache__/",
   "*.pyc",
 ];
+const minimalCanonicalState = `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
+`;
+const minimalContextMap = `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
+`;
+const minimalDecisionsReadme = `# 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.
+`;
 const requiredText = {
   "AGENTS.md": [
     "AI_PROTOCOL_BEGIN",
@@ -39,7 +84,14 @@ const requiredText = {
     "Nenhum arquivo deve passar de 400 linhas.",
   ],
   ".aiignore": ["results/", "dist/", "*.pyc"],
+  "canonical-state.yaml": ["canonical_state", "truth_order"],
+  "context-map.yaml": ["project_context_map", "aliases_are_pointers_not_truth"],
   "protocol/router.yaml": ["feature_or_spec", "spec-driven.yaml", "prompt_improvement"],
+  "protocol/route-packs.yaml": [
+    "read_pack_first_expand_only_when_needed",
+    "simple_answer",
+    "context_optimization",
+  ],
   "protocol/spec-driven.yaml": ["protocol_is_base_spec_is_tool", "do_not_create_spec_for_low_value_tasks"],
 };
 
@@ -78,13 +130,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
@@ -194,6 +248,17 @@ function installAiignore(target) {
   writeText(target, existing.join("\n").trim() + "\n");
 }
 
+function writeIfMissing(file, text) {
+  if (fs.existsSync(file)) return;
+  writeText(file, text);
+}
+
+function installContextTemplates(targetRoot) {
+  writeIfMissing(path.join(targetRoot, "canonical-state.yaml"), minimalCanonicalState);
+  writeIfMissing(path.join(targetRoot, "context-map.yaml"), minimalContextMap);
+  writeIfMissing(path.join(targetRoot, "decisions", "README.md"), minimalDecisionsReadme);
+}
+
 function copyProtocol(target, force, backupRoot) {
   if (fs.existsSync(target) && !force) return;
   if (fs.existsSync(target)) {
@@ -219,6 +284,7 @@ function install(target, force, dryRun) {
   backup(path.join(targetRoot, ".aiignore"), backupRoot);
   installAgents(path.join(targetRoot, "AGENTS.md"));
   installAiignore(path.join(targetRoot, ".aiignore"));
+  installContextTemplates(targetRoot);
   copyProtocol(path.join(targetRoot, "protocol"), force, backupRoot);
   console.log(`installed protocol -> ${targetRoot}`);
   return verify(targetRoot);
@@ -227,7 +293,14 @@ function install(target, force, dryRun) {
 function verify(target) {
   const targetRoot = path.resolve(target);
   const errors = [];
-  const requiredFiles = ["AGENTS.md", ".aiignore", ...protocolFiles.map((file) => `protocol/${file}`)];
+  const requiredFiles = [
+    "AGENTS.md",
+    ".aiignore",
+    "canonical-state.yaml",
+    "context-map.yaml",
+    "decisions/README.md",
+    ...protocolFiles.map((file) => `protocol/${file}`),
+  ];
   for (const item of requiredFiles) {
     const file = path.join(targetRoot, item);
     if (!fs.existsSync(file)) {

package/scripts/verify_install.py

@@ -10,9 +10,13 @@ from pathlib import Path
 REQUIRED_FILES = [
     "AGENTS.md",
     ".aiignore",
+    "canonical-state.yaml",
+    "context-map.yaml",
+    "decisions/README.md",
     "protocol/README.yaml",
     "protocol/fast-path.yaml",
     "protocol/router.yaml",
+    "protocol/route-packs.yaml",
     "protocol/modes.yaml",
     "protocol/execution-rules.yaml",
     "protocol/risk-levels.yaml",
@@ -42,11 +46,24 @@ REQUIRED_TEXT = {
         "dist/",
         "*.pyc",
     ],
+    "canonical-state.yaml": [
+        "canonical_state",
+        "truth_order",
+    ],
+    "context-map.yaml": [
+        "project_context_map",
+        "aliases_are_pointers_not_truth",
+    ],
     "protocol/router.yaml": [
         "feature_or_spec",
         "spec-driven.yaml",
         "prompt_improvement",
     ],
+    "protocol/route-packs.yaml": [
+        "read_pack_first_expand_only_when_needed",
+        "simple_answer",
+        "context_optimization",
+    ],
     "protocol/spec-driven.yaml": [
         "protocol_is_base_spec_is_tool",
         "do_not_create_spec_for_low_value_tasks",