ai-execution-protocol 0.2.0 → 0.3.0

package/AGENTS.md

@@ -24,7 +24,10 @@ 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. `protocol/context-budget.yaml` para limitar a leitura inicial.
+5. `memory/INDEX.yaml` somente quando memoria puder ajudar.
+6. Arquivo YAML especifico em `protocol/` somente quando o pack nao bastar:
    - `README.yaml`
    - `modes.yaml`
    - `execution-rules.yaml`
@@ -33,6 +36,10 @@ metodologia. Para executar tarefas, prefira as regras curtas em `protocol/`.
    - `validation-checklist.yaml`
    - `context-rules.yaml`
    - `context-compiler.yaml`
+   - `context-budget.yaml`
+   - `adaptive-memory.yaml`
+   - `selective-validation.yaml`
+   - `route-packs.yaml`
    - `formatting-rules.yaml`
    - `prompt-economy.yaml`
    - `spec-driven.yaml`
@@ -54,6 +61,12 @@ 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.
+- Respeite `protocol/context-budget.yaml` e justifique expansao.
+- Leia apenas assuntos de memoria relacionados ao pedido.
+- Ao terminar, registre `updated`, `unchanged`, `candidate`, `replaced` ou
+  `blocked_sensitive`.
+- Use validacao seletiva e aumente apenas quando o impacto exigir.
 - 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

@@ -31,15 +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:
+Na v0.3.0, o framework adiciona memoria adaptativa verificada, orcamento de
+contexto e validacao seletiva:
 
 ```text
-pedido -> intencao -> dominio -> contexto minimo -> validacao -> acao
+pedido -> risco -> memoria relevante -> contexto limitado -> acao -> validacao
 ```
 
-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.
+Memoria orienta, o pedido atual autoriza e arquivos verificados definem a
+realidade. Inferencias ficam candidatas ate acumularem evidencia, e conteudo
+sensivel e bloqueado.
 
 ## Status
 
@@ -57,8 +58,11 @@ continuam obrigatorios em tarefas criticas.
 - `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.
+- `memory/`: preferencias, estado e padroes duraveis validados.
+- `candidate-memory/`: inferencias ainda nao autoritativas.
 - `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,10 +83,12 @@ 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.
+10. Atualize memoria apenas quando surgir um fato duravel e seguro.
 
-Regra de seguranca da v0.2.0:
+Regra de seguranca:
 
 ```text
 A IA pode expandir contexto.
@@ -103,8 +109,10 @@ 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`
+- `docs/18-memoria-adaptativa.md`
+- `docs/19-orcamento-de-contexto.md`
+- `docs/20-validacao-seletiva.md`
 
 Use `docs/` para entender a metodologia. Use `protocol/` quando quiser aplicar
 as regras em uma tarefa real.
@@ -129,6 +137,13 @@ Meca custo aproximado de leitura por rota:
 python scripts/token_report.py
 ```
 
+Valide a memoria e selecione apenas as verificacoes necessarias:
+
+```powershell
+python scripts/memory_manager.py --root . validate
+python scripts/selective_validation.py
+```
+
 ## Instalacao em outro projeto
 
 Projeto novo:
@@ -171,19 +186,14 @@ python scripts/verify_install.py --target C:\caminho\projeto
 
 O final esperado da verificacao e `PASS`.
 
-## Publicacao
+Atualizacao pelos pacotes publicados:
 
-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.
+```powershell
+npm install -g ai-execution-protocol@latest
+python -m pip install --upgrade ai-execution-protocol
+ai-protocol install C:\caminho\projeto
+ai-protocol verify C:\caminho\projeto
+```
 
 ## Licenca
 

package/dist/minimal/.aiignore

@@ -1,8 +1,8 @@
-# Context files ignored by default for AI reading.
-
-results/
-benchmarks/generated/
-model-runs/generated/
-dist/
-scripts/__pycache__/
-*.pyc
+results/
+benchmarks/generated/
+model-runs/generated/
+dist/
+memory/archive/
+candidate-memory/
+scripts/__pycache__/
+*.pyc

package/dist/minimal/AGENTS.md

@@ -1,61 +1,41 @@
-# AGENTS.md
-
-## Regra principal
-
-<!-- AI_PROTOCOL_BEGIN -->
-
-Use `protocol/fast-path.yaml` como entrada operacional minima.
-
-Siga `.aiignore` antes de abrir relatorios gerados.
-
-Este protocolo e obrigatorio para tarefas tecnicas neste projeto. Antes de
-editar, classifique risco, escolha rota e valide a entrega.
-
-## Ordem de leitura
-
-1. `protocol/fast-path.yaml`
-2. `protocol/router.yaml`
-3. Arquivo YAML especifico em `protocol/` conforme a rota.
-
-## Regras de execucao
-
-- Classifique o risco antes de agir.
-- Use o menor contexto suficiente.
-- Leia apenas os arquivos indicados por `protocol/router.yaml`.
-- 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
-  critica, sem criar spec pesada para tarefa simples.
-- Sempre entregue `Prompt original` e `Prompt melhorado da IA`; em baixo risco,
-  prefira micro formato legivel com `PO`, `PM` e `OK`.
-- Nao edite arquivo que nao foi identificado como candidato.
-- Preserve documentos, regras de IDE e configuracoes de framework existentes,
-  salvo pedido explicito do usuario.
-- Se o risco subir, atualize a classificacao antes de continuar.
-- Para nivel critico, peca confirmacao antes de acao sensivel.
-- Quando houver risco de quebrar fluxo existente, entregue uma lista do que
-  testar.
-- Entregue com evidencia em poucas linhas: mudanca, validacao, limite e risco
-  residual.
-- Explique o resultado em linguagem clara para uma pessoa leiga entender.
-
-## Convivencia com arquivos existentes
-
-Quando houver conflito, siga esta prioridade:
-
-1. pedido atual do usuario;
-2. este bloco obrigatorio em `AGENTS.md`;
-3. regras especificas da IDE ou do projeto;
-4. docs e historico somente quando a rota pedir.
-
-Nao sobrescreva `README.md`, `docs/`, `.cursorrules`, `CLAUDE.md`,
-`.github/copilot-instructions.md` ou configs de framework sem pedido claro.
-
-## Regras de organizacao
-
-- Nenhum arquivo deve passar de 400 linhas.
-- Organize primeiro para legibilidade por IA.
-- Use YAML para regras operacionais.
-- Evite duplicar a mesma regra em muitos lugares.
-
-<!-- AI_PROTOCOL_END -->
+# AGENTS.md
+
+## Regra principal
+
+<!-- AI_PROTOCOL_BEGIN -->
+
+Use `protocol/fast-path.yaml` como entrada operacional minima.
+
+Este protocolo e obrigatorio para tarefas tecnicas. Classifique risco, escolha
+rota, consulte o pack compacto, carregue somente memoria relevante e valide a
+entrega.
+
+## Ordem de leitura
+
+1. `protocol/fast-path.yaml`
+2. `protocol/router.yaml`
+3. `protocol/route-packs.yaml`
+4. `memory/INDEX.yaml` somente quando memoria puder ajudar
+5. YAML completo da rota somente quando o pack nao bastar
+
+## Regras de execucao
+
+- Classifique o risco antes de agir.
+- Use o menor contexto suficiente e respeite `protocol/context-budget.yaml`.
+- Memoria orienta; pedido atual autoriza; codigo verificado define realidade.
+- Nunca amplie escopo com base em previsao ou preferencia antiga.
+- Use `protocol/selective-validation.yaml` para escolher a menor prova suficiente.
+- Ao terminar, verifique memoria: updated, unchanged, candidate, replaced ou
+  blocked_sensitive.
+- Nao persista segredo, token, dado de cliente ou informacao pessoal desnecessaria.
+- Para nivel critico, peca confirmacao antes de acao sensivel.
+- Entregue mudanca, validacao, limite e risco residual em poucas linhas.
+
+## Regras de organizacao
+
+- Nenhum arquivo fonte deve passar de 400 linhas.
+- Organize por assunto rastreavel.
+- Use YAML para operacao e Markdown para explicacao.
+- Evite duplicar regras e memoria.
+
+<!-- AI_PROTOCOL_END -->

package/dist/minimal/candidate-memory/README.md

@@ -0,0 +1,4 @@
+# Candidate Memory
+
+Store inferred, non-sensitive memory candidates here until evidence or user
+confirmation is enough for promotion.

package/dist/minimal/canonical-state.yaml

@@ -0,0 +1,16 @@
+id: canonical_state
+type: project_state
+version: 0.3
+purpose: small_current_truth_summary_for_ai_navigation
+status: bootstrap_template
+truth_order:
+  - current_user_request
+  - verified_current_files
+  - active_project_decisions
+  - explicit_user_preferences
+  - inferred_patterns_with_evidence
+  - project_docs
+  - conversation_history
+notes:
+  - memory_guides_current_request_authorizes
+  - update_when_verified_project_state_changes

package/dist/minimal/context-map.yaml

@@ -0,0 +1,22 @@
+id: project_context_map
+type: context_map
+version: 0.3
+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
+  - memory/INDEX.yaml
+domains: {}
+retrieval_policy:
+  order:
+    - match_domain_by_alias
+    - read_matching_memory_subjects
+    - 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,4 @@
+# Decisions
+
+Record confirmed project decisions with status, scope, evidence and replacement
+history.

package/dist/minimal/memory/INDEX.yaml

@@ -0,0 +1,20 @@
+id: memory_index
+type: memory_index
+version: 0.3
+purpose: route_to_minimum_relevant_persistent_memory
+policy:
+  - read_only_matching_subjects
+  - do_not_load_archive_by_default
+  - current_request_overrides_memory
+  - verified_files_override_stale_memory
+entries: []
+areas:
+  user:
+    path: memory/user/
+  projects:
+    path: memory/projects/
+  patterns:
+    path: memory/patterns/
+  archive:
+    path: memory/archive/
+    read_by_default: false

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.3.0
 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
@@ -23,12 +25,18 @@ files:
     purpose: pre_change_maps_by_risk
   - path: validation-checklist.yaml
     purpose: validation_and_final_delivery
+  - path: selective-validation.yaml
+    purpose: choose_smallest_sufficient_validation
   - path: context-rules.yaml
     purpose: context_window_file_size_memory
   - path: context-compiler.yaml
     purpose: compile_minimum_context_package_and_canonical_state
+  - path: context-budget.yaml
+    purpose: enforce_context_cost_limits_by_risk
   - path: persistent-context.yaml
     purpose: progressive_context_retrieval_with_aliases
+  - path: adaptive-memory.yaml
+    purpose: maintain_verified_user_and_project_memory
   - path: formatting-rules.yaml
     purpose: ai_readable_file_format
   - path: prompt-economy.yaml

package/dist/minimal/protocol/adaptive-memory.yaml

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

package/dist/minimal/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/dist/minimal/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/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

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