ai-execution-protocol 0.2.1__tar.gz → 0.3.0__tar.gz

{ai_execution_protocol-0.2.1 → ai_execution_protocol-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-execution-protocol
-Version: 0.2.1
+Version: 0.3.0
 Summary: Experimental AI execution protocol for safer agent workflows, minimal context, risk classification, validation, and evidence-based delivery.
 Author: AI Execution Protocol
 License-Expression: MIT
@@ -52,15 +52,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
 
@@ -78,6 +79,8 @@ 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.
@@ -104,8 +107,9 @@ 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.
 
-Regra de seguranca da v0.2.0:
+Regra de seguranca:
 
 ```text
 A IA pode expandir contexto.
@@ -127,6 +131,9 @@ 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`
 
 Use `docs/` para entender a metodologia. Use `protocol/` quando quiser aplicar
 as regras em uma tarefa real.
@@ -151,6 +158,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:
@@ -193,6 +207,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`.

{ai_execution_protocol-0.2.1 → ai_execution_protocol-0.3.0}/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,6 +58,8 @@ 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.
@@ -83,8 +86,9 @@ 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.
 
-Regra de seguranca da v0.2.0:
+Regra de seguranca:
 
 ```text
 A IA pode expandir contexto.
@@ -106,6 +110,9 @@ 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`
 
 Use `docs/` para entender a metodologia. Use `protocol/` quando quiser aplicar
 as regras em uma tarefa real.
@@ -130,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:
@@ -172,6 +186,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`.

{ai_execution_protocol-0.2.1 → ai_execution_protocol-0.3.0}/ai_execution_protocol/cli.py

@@ -9,126 +9,17 @@ from datetime import datetime
 from importlib import resources
 from pathlib import Path
 
+from .install_support import manifest, template
 
 MARKER_START = "<!-- AI_PROTOCOL_BEGIN -->"
 MARKER_END = "<!-- AI_PROTOCOL_END -->"
-AIIGNORE_LINES = [
-    "results/",
-    "benchmarks/generated/",
-    "model-runs/generated/",
-    "dist/",
-    "scripts/__pycache__/",
-    "*.pyc",
+MANIFEST = manifest()
+AIIGNORE_LINES = MANIFEST["aiignore_lines"]
+REQUIRED_PROTOCOL_FILES = MANIFEST["protocol_files"]
+REQUIRED_FILES = MANIFEST["required_files"] + [
+    f"protocol/{name}" for name in REQUIRED_PROTOCOL_FILES
 ]
-
-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.
-"""
-REQUIRED_PROTOCOL_FILES = [
-    "README.yaml",
-    "fast-path.yaml",
-    "router.yaml",
-    "route-packs.yaml",
-    "modes.yaml",
-    "execution-rules.yaml",
-    "risk-levels.yaml",
-    "mapping-checklists.yaml",
-    "validation-checklist.yaml",
-    "context-rules.yaml",
-    "context-compiler.yaml",
-    "persistent-context.yaml",
-    "formatting-rules.yaml",
-    "prompt-economy.yaml",
-    "spec-driven.yaml",
-]
-REQUIRED_FILES = [
-    "AGENTS.md",
-    ".aiignore",
-    "canonical-state.yaml",
-    "context-map.yaml",
-    "decisions/README.md",
-    *[f"protocol/{name}" for name in REQUIRED_PROTOCOL_FILES],
-]
-REQUIRED_TEXT = {
-    "AGENTS.md": [
-        "AI_PROTOCOL_BEGIN",
-        "protocol/fast-path.yaml",
-        "protocol/router.yaml",
-        "protocol/route-packs.yaml",
-        "Classifique o risco antes de agir",
-        "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",
-    ],
-}
+REQUIRED_TEXT = MANIFEST["required_text"]
 
 
 def protocol_source() -> resources.abc.Traversable:
@@ -136,70 +27,7 @@ def protocol_source() -> resources.abc.Traversable:
 
 
 def minimal_agents() -> str:
-    return """# 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 -->
-"""
+    return template("AGENTS.md")
 
 
 def protocol_block() -> str:
@@ -265,9 +93,10 @@ def write_if_missing(path: Path, text: str) -> None:
 
 
 def install_context_templates(target_root: Path) -> None:
-    write_if_missing(target_root / "canonical-state.yaml", MINIMAL_CANONICAL_STATE)
-    write_if_missing(target_root / "context-map.yaml", MINIMAL_CONTEXT_MAP)
-    write_if_missing(target_root / "decisions" / "README.md", MINIMAL_DECISIONS_README)
+    for item in MANIFEST["required_files"]:
+        if item in {"AGENTS.md", ".aiignore"}:
+            continue
+        write_if_missing(target_root / item, template(item))
 
 
 def print_dry_run(target_root: Path, force: bool) -> None:

ai_execution_protocol-0.3.0/ai_execution_protocol/install-manifest.json

@@ -0,0 +1,64 @@
+{
+  "protocol_files": [
+    "README.yaml",
+    "fast-path.yaml",
+    "router.yaml",
+    "route-packs.yaml",
+    "modes.yaml",
+    "execution-rules.yaml",
+    "risk-levels.yaml",
+    "mapping-checklists.yaml",
+    "validation-checklist.yaml",
+    "selective-validation.yaml",
+    "context-rules.yaml",
+    "context-compiler.yaml",
+    "context-budget.yaml",
+    "persistent-context.yaml",
+    "adaptive-memory.yaml",
+    "formatting-rules.yaml",
+    "prompt-economy.yaml",
+    "spec-driven.yaml"
+  ],
+  "required_files": [
+    "AGENTS.md",
+    ".aiignore",
+    "canonical-state.yaml",
+    "context-map.yaml",
+    "decisions/README.md",
+    "memory/INDEX.yaml",
+    "candidate-memory/README.md"
+  ],
+  "aiignore_lines": [
+    "results/",
+    "benchmarks/generated/",
+    "model-runs/generated/",
+    "dist/",
+    "scripts/__pycache__/",
+    "*.pyc"
+  ],
+  "required_text": {
+    "AGENTS.md": [
+      "AI_PROTOCOL_BEGIN",
+      "protocol/fast-path.yaml",
+      "protocol/router.yaml",
+      "protocol/route-packs.yaml",
+      "Classifique o risco antes de agir"
+    ],
+    "memory/INDEX.yaml": [
+      "memory_index",
+      "read_only_matching_subjects"
+    ],
+    "protocol/adaptive-memory.yaml": [
+      "memory_guides_current_request_authorizes",
+      "blocked_sensitive"
+    ],
+    "protocol/context-budget.yaml": [
+      "budget_guides_reading",
+      "stop_when"
+    ],
+    "protocol/selective-validation.yaml": [
+      "smallest_validation_set",
+      "release"
+    ]
+  }
+}

ai_execution_protocol-0.3.0/ai_execution_protocol/install_support.py

@@ -0,0 +1,17 @@
+"""Shared installation data loaded from packaged manifest and templates."""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+
+
+PACKAGE = resources.files("ai_execution_protocol")
+
+
+def manifest() -> dict:
+    return json.loads(PACKAGE.joinpath("install-manifest.json").read_text(encoding="utf-8"))
+
+
+def template(path: str) -> str:
+    return PACKAGE.joinpath("templates", "minimal", *path.split("/")).read_text(encoding="utf-8")

{ai_execution_protocol-0.2.1 → ai_execution_protocol-0.3.0}/ai_execution_protocol/protocol/README.yaml

@@ -1,7 +1,7 @@
 id: protocol_index
 type: index
 format: yaml
-protocol_version: 0.2.1
+protocol_version: 0.3.0
 purpose: ai_operational_rules
 source_docs: ../docs
 constraints:
@@ -25,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

ai_execution_protocol-0.3.0/ai_execution_protocol/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

ai_execution_protocol-0.3.0/ai_execution_protocol/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