ai-execution-protocol 0.2.1 → 0.3.0

package/protocol/route-packs.yaml

@@ -1,6 +1,6 @@
 id: route_packs
 type: route_summary_index
-version: 0.1
+version: 0.3
 purpose: compact_first_read_before_full_route_files
 principle: read_pack_first_expand_only_when_needed
 use:
@@ -151,3 +151,34 @@ packs:
       - read_atomic_subject_doc_before_broad_doc
       - search_with_rg_before_full_file_reads
       - expand_context_without_expanding_scope
+  memory_update:
+    risk: 1
+    read_if_pack_insufficient:
+      - adaptive-memory.yaml
+      - context-budget.yaml
+      - validation-checklist.yaml
+    do:
+      - extract_only_stable_non_sensitive_knowledge
+      - search_before_create
+      - merge_replace_or_keep_unchanged
+      - update_memory_index
+      - report_memory_update_result
+  memory_conflict_or_replacement:
+    risk: 2
+    read_if_pack_insufficient:
+      - adaptive-memory.yaml
+      - context-compiler.yaml
+      - validation-checklist.yaml
+    do:
+      - preserve_provenance
+      - mark_old_entry_replaced
+      - keep_current_request_authoritative
+      - validate_no_duplicate_active_entry
+  selective_validation:
+    risk: 1
+    read_if_pack_insufficient:
+      - selective-validation.yaml
+    do:
+      - infer_checks_from_changed_files
+      - run_smallest_sufficient_validation
+      - expand_when_shared_contract_changes

package/protocol/router.yaml

@@ -1,6 +1,6 @@
 id: protocol_router
 type: read_router
-version: 0.1
+version: 0.3
 purpose: choose_minimum_protocol_files_by_task
 default_read:
   - fast-path.yaml
@@ -93,11 +93,33 @@ routes:
       - persistent-context.yaml
       - context-rules.yaml
       - context-compiler.yaml
+      - context-budget.yaml
+  memory_update:
+    risk: 1
+    read:
+      - fast-path.yaml
+      - adaptive-memory.yaml
+      - context-budget.yaml
+      - validation-checklist.yaml
+  memory_conflict_or_replacement:
+    risk: 2
+    read:
+      - fast-path.yaml
+      - adaptive-memory.yaml
+      - context-compiler.yaml
+      - validation-checklist.yaml
+  selective_validation:
+    risk: 1
+    read:
+      - fast-path.yaml
+      - selective-validation.yaml
 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
+  - apply_context_budget_to_selected_route
+  - retrieve_only_matching_memory_subjects
   - 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/protocol/selective-validation.yaml

@@ -0,0 +1,44 @@
+id: selective_validation
+type: operational_rules
+version: 0.3
+purpose: run_smallest_validation_set_that_proves_the_change
+principle: validation_scales_with_behavior_and_blast_radius
+selection:
+  docs_only:
+    run:
+      - link_check
+      - text_search
+      - schema_if_structured
+  protocol_rule:
+    run:
+      - schema_validation
+      - mirror_sync
+      - framework_targeted_tests
+  parser_or_evaluator:
+    run:
+      - parser_adversarial_tests
+      - framework_tests
+      - benchmark_runner
+  installer_or_package:
+    run:
+      - install_test
+      - verify_install
+      - package_dry_run
+  shared_or_cross_module:
+    run:
+      - framework_tests
+      - health_check
+  release:
+    run:
+      - framework_tests
+      - schema_strict
+      - health_check
+      - npm_dry_run
+      - python_build
+      - twine_check
+rules:
+  - infer_validation_from_changed_files_and_behavior
+  - expand_validation_when_shared_contract_changes
+  - never_claim_unrun_validation
+  - full_health_check_is_not_required_for_every_small_change
+  - user_visible_or_critical_change_requires_manual_test_guidance

package/protocol/validation-checklist.yaml

@@ -1,6 +1,7 @@
 id: validation_checklist
 type: checklist
-version: 0.1
+version: 0.3
+selection_source: protocol/selective-validation.yaml
 automatic_validation:
   - unit_tests
   - integration_tests
@@ -57,3 +58,11 @@ rules:
       - make_limits_and_residual_risk_understandable
       - prefer_one_line_per_delivery_field
       - use_micro_format_only_when_readable
+  - id: VAL_005
+    always:
+      - select_smallest_validation_set_that_proves_behavior
+      - expand_when_shared_contract_or_blast_radius_requires
+      - record_every_expected_validation_not_run
+    avoid:
+      - full_health_check_for_trivial_local_change
+      - unrelated_expensive_validation

package/scripts/README.md

@@ -47,6 +47,32 @@ Para medir uma rota especifica:
 python scripts/token_report.py --route user_flow_bug --out results/token-user-flow-bug.yaml
 ```
 
+## context_package.py
+
+Gera um pacote de contexto limitado por risco, rota, memoria e candidatos.
+
+```powershell
+python scripts/context_package.py --objective "Revisar memoria" --route memory_update --risk 2 --term memory
+```
+
+## memory_manager.py
+
+Inclui, consulta e valida memoria adaptativa com deduplicacao e bloqueio de
+conteudo sensivel.
+
+```powershell
+python scripts/memory_manager.py --root . validate
+```
+
+## selective_validation.py
+
+Seleciona as verificacoes proporcionais aos arquivos alterados.
+
+```powershell
+python scripts/selective_validation.py
+python scripts/selective_validation.py --release
+```
+
 ## health_check.py
 
 Roda a validacao geral do framework.
@@ -102,6 +128,23 @@ python scripts/framework_tests.py
 
 O relatorio fica em `results/framework-test-report.yaml`.
 
+## v03_tests.py
+
+Testa memoria, orcamento de contexto, validacao seletiva e manifesto de
+instalacao.
+
+```powershell
+python scripts/v03_tests.py
+```
+
+## context_economy_benchmark.py
+
+Compara leitura ampla com rotas focadas da v0.3.0.
+
+```powershell
+python scripts/context_economy_benchmark.py
+```
+
 ## build_dist.py
 
 Gera `dist/minimal/` a partir de `AGENTS.md` minimo e `protocol/`.

package/scripts/build_dist.py

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import json
 import shutil
 from pathlib import Path
 
@@ -10,91 +11,7 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parents[1]
 DIST = ROOT / "dist" / "minimal"
 PYTHON_PACKAGE_PROTOCOL = ROOT / "ai_execution_protocol" / "protocol"
-
-
-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",
-]
-
-
-MINIMAL_AGENTS = """# 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 -->
-"""
+PYTHON_PACKAGE_TEMPLATES = ROOT / "ai_execution_protocol" / "templates" / "minimal"
 
 
 MINIMAL_README = """# Minimal AI Protocol
@@ -160,68 +77,15 @@ O `install.ps1` tambem roda a verificacao. O resultado esperado e `PASS`.
 """
 
 
-MINIMAL_AIIGNORE = """# Context files ignored by default for AI reading.
-
-results/
-benchmarks/generated/
-model-runs/generated/
-dist/
-scripts/__pycache__/
-*.pyc
-"""
-
-
-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 copy_tree(source: Path, target: Path) -> None:
+    if target.exists():
+        shutil.rmtree(target)
+    shutil.copytree(source, target)
 
 
 def main() -> int:
+    manifest = json.loads((ROOT / "install-manifest.json").read_text(encoding="utf-8"))
+    protocol_files = manifest["protocol_files"]
     if DIST.exists():
         shutil.rmtree(DIST)
     (DIST / "protocol").mkdir(parents=True, exist_ok=True)
@@ -229,17 +93,14 @@ def main() -> int:
         shutil.rmtree(PYTHON_PACKAGE_PROTOCOL)
     PYTHON_PACKAGE_PROTOCOL.mkdir(parents=True, exist_ok=True)
 
-    (DIST / "AGENTS.md").write_text(MINIMAL_AGENTS, encoding="utf-8")
+    shutil.copytree(ROOT / "templates" / "minimal", DIST, dirs_exist_ok=True)
     (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:
+    for name in protocol_files:
         shutil.copy2(ROOT / "protocol" / name, DIST / "protocol" / name)
         shutil.copy2(ROOT / "protocol" / name, PYTHON_PACKAGE_PROTOCOL / name)
     (PYTHON_PACKAGE_PROTOCOL / "__init__.py").write_text("", encoding="utf-8")
+    shutil.copy2(ROOT / "install-manifest.json", ROOT / "ai_execution_protocol" / "install-manifest.json")
+    copy_tree(ROOT / "templates" / "minimal", PYTHON_PACKAGE_TEMPLATES)
 
     print(f"built {DIST}")
     return 0

package/scripts/npm_install_protocol.js

@@ -6,94 +6,10 @@ const path = require("path");
 const root = path.resolve(__dirname, "..");
 const markerStart = "<!-- AI_PROTOCOL_BEGIN -->";
 const markerEnd = "<!-- AI_PROTOCOL_END -->";
-const protocolFiles = [
-  "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",
-];
-const aiignoreLines = [
-  "results/",
-  "benchmarks/generated/",
-  "model-runs/generated/",
-  "dist/",
-  "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",
-    "protocol/fast-path.yaml",
-    "protocol/router.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"],
-};
+const manifest = JSON.parse(fs.readFileSync(path.join(root, "install-manifest.json"), "utf8"));
+const protocolFiles = manifest.protocol_files;
+const aiignoreLines = manifest.aiignore_lines;
+const requiredText = manifest.required_text;
 
 function readText(file) {
   return fs.readFileSync(file, "utf8");
@@ -112,71 +28,7 @@ function sourceProtocolDir() {
 
 function minimalAgents() {
   const file = path.join(root, "dist", "minimal", "AGENTS.md");
-  if (fs.existsSync(file)) return readText(file);
-  return `# AGENTS.md
-
-## Regra principal
-
-${markerStart}
-
-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.
-
-${markerEnd}
-`;
+  return readText(file);
 }
 
 function protocolBlock() {
@@ -254,9 +106,10 @@ function writeIfMissing(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);
+  for (const item of manifest.required_files) {
+    if (item === "AGENTS.md" || item === ".aiignore") continue;
+    writeIfMissing(path.join(targetRoot, item), readText(path.join(root, "dist", "minimal", item)));
+  }
 }
 
 function copyProtocol(target, force, backupRoot) {
@@ -294,11 +147,7 @@ function verify(target) {
   const targetRoot = path.resolve(target);
   const errors = [];
   const requiredFiles = [
-    "AGENTS.md",
-    ".aiignore",
-    "canonical-state.yaml",
-    "context-map.yaml",
-    "decisions/README.md",
+    ...manifest.required_files,
     ...protocolFiles.map((file) => `protocol/${file}`),
   ];
   for (const item of requiredFiles) {