ai-execution-protocol 0.2.1 → 0.3.1

package/AGENTS.md

@@ -25,7 +25,11 @@ metodologia. Para executar tarefas, prefira as regras curtas em `protocol/`.
 1. `protocol/fast-path.yaml`
 2. `protocol/router.yaml`
 3. `protocol/route-packs.yaml` para ler o resumo compacto da rota.
-4. Arquivo YAML especifico em `protocol/` somente quando o pack nao bastar:
+4. `protocol/context-budget.yaml` para limitar a leitura inicial.
+5. `memory/INDEX.yaml` somente quando memoria puder ajudar.
+6. `protocol/capability-router.yaml` quando skills, MCPs ou ferramentas
+   opcionais puderem ser necessarios.
+7. Arquivo YAML especifico em `protocol/` somente quando o pack nao bastar:
    - `README.yaml`
    - `modes.yaml`
    - `execution-rules.yaml`
@@ -34,6 +38,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`
+   - `capability-router.yaml`
+   - `selective-validation.yaml`
    - `route-packs.yaml`
    - `formatting-rules.yaml`
    - `prompt-economy.yaml`
@@ -57,6 +65,13 @@ metodologia. Para executar tarefas, prefira as regras curtas em `protocol/`.
 - 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.
+- Use `protocol/capability-router.yaml` antes de carregar skills, MCPs ou
+  ferramentas opcionais.
+- 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
@@ -66,6 +81,8 @@ metodologia. Para executar tarefas, prefira as regras curtas em `protocol/`.
   prefira micro formato legivel com `PO`, `PM` e `OK`.
 - Ao criar feature, refatoracao grande ou tarefa critica, use
   `protocol/spec-driven.yaml` sem transformar tarefa simples em spec pesada.
+- Selecione apenas capacidades necessarias para cobrir resultado e validacao.
+  Risco maior restringe permissao; nao aumenta ferramentas por padrao.
 - Nao edite arquivo que nao foi identificado como candidato.
 - Se o risco subir, atualize a classificacao antes de continuar.
 - Para nivel critico, peca confirmacao antes de acao sensivel.

package/README.md

@@ -31,15 +31,25 @@ 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.1, o framework combina memoria adaptativa, orcamento de contexto,
+validacao seletiva e roteamento de capacidades:
 
 ```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.
+
+Skills, MCPs e ferramentas opcionais seguem outro limite:
+
+```text
+resultado necessario -> capacidade minima -> permissao -> validacao
+```
+
+Risco maior restringe permissoes. Ele nao aumenta automaticamente a quantidade
+de ferramentas.
 
 ## Status
 
@@ -57,6 +67,9 @@ 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.
+- `capabilities/`: registro pequeno de skills, MCPs e ferramentas conhecidas.
 - `docs/`: explicacoes conceituais em Markdown.
 - `protocol/`: regras operacionais curtas em YAML.
 - `protocol/route-packs.yaml`: resumos compactos para reduzir leitura por rota.
@@ -83,8 +96,10 @@ continuam obrigatorios em tarefas criticas.
 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.
+11. Carregue apenas capacidades necessarias para resultado e validacao.
 
-Regra de seguranca da v0.2.0:
+Regra de seguranca:
 
 ```text
 A IA pode expandir contexto.
@@ -106,6 +121,10 @@ Comece por:
 - `docs/05-validacao-e-entrega.md`
 - `docs/15-contexto-persistente.md`
 - `docs/17-documentacao-atomica.md`
+- `docs/18-memoria-adaptativa.md`
+- `docs/19-orcamento-de-contexto.md`
+- `docs/20-validacao-seletiva.md`
+- `docs/21-roteamento-de-capacidades.md`
 
 Use `docs/` para entender a metodologia. Use `protocol/` quando quiser aplicar
 as regras em uma tarefa real.
@@ -130,6 +149,14 @@ 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
+python scripts/capability_router.py --risk 1 --operation read --tag code_search
+```
+
 ## Instalacao em outro projeto
 
 Projeto novo:
@@ -172,6 +199,15 @@ python scripts/verify_install.py --target C:\caminho\projeto
 
 O final esperado da verificacao e `PASS`.
 
+Atualizacao pelos pacotes publicados:
+
+```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
 
 Distribuido sob a licenca MIT. Veja `LICENSE`.

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,63 +1,45 @@
-# 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. `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
-  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. `capabilities/registry.yaml` somente quando a tarefa exigir ferramenta
+6. 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`.
+- Use `protocol/capability-router.yaml` para carregar somente skills, MCPs e
+  ferramentas necessarias.
+- Risco maior restringe permissao; nao aumenta a quantidade por padrao.
+- 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

@@ -1,14 +1,16 @@
-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
+id: canonical_state
+type: project_state
+version: 0.3.1
+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/capabilities/registry.yaml

@@ -0,0 +1,48 @@
+id: capability_registry
+type: capability_registry
+version: 0.3.1
+purpose: project_capabilities_available_to_the_agent
+policy:
+  default_available: false
+  runtime_availability_must_be_verified: true
+capabilities:
+  - id: local_search
+    type: local_tool
+    available: true
+    tags: [code_search, file_discovery]
+    operations: [read]
+    cost: {tokens: low, latency: low}
+    side_effect: none
+    confirmation: never
+  - id: local_files
+    type: local_tool
+    available: true
+    tags: [file_read, file_write]
+    operations: [read, write]
+    cost: {tokens: low, latency: low}
+    side_effect: local_write
+    confirmation: risk_based
+  - id: focused_skill
+    type: skill
+    available: runtime
+    tags: [domain_guidance]
+    operations: [read]
+    cost: {tokens: medium, latency: low}
+    side_effect: none
+    confirmation: never
+  - id: targeted_mcp
+    type: mcp
+    available: runtime
+    tags: [external_context, remote_operation]
+    operations: [read, write]
+    cost: {tokens: medium, latency: medium}
+    side_effect: remote_write
+    confirmation: operation_based
+  - id: publish_service
+    type: remote_service
+    available: runtime
+    tags: [publish]
+    operations: [publish]
+    cost: {tokens: low, latency: medium}
+    side_effect: publish
+    confirmation: always

package/dist/minimal/context-map.yaml

@@ -1,20 +1,23 @@
-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
+id: project_context_map
+type: context_map
+version: 0.3.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
+  - memory/INDEX.yaml
+  - capabilities/registry.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

@@ -1,7 +1,4 @@
-# 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.
+# 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.1
+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.1
+protocol_version: 0.3.1
 purpose: ai_operational_rules
 source_docs: ../docs
 constraints:
@@ -25,12 +25,20 @@ 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: capability-router.yaml
+    purpose: select_minimum_skills_mcps_and_tools_by_value_cost_and_risk
   - 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