ai-execution-protocol 0.3.0 → 0.4.0

package/schema/memory-entry.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-research.local/schema/memory-entry.schema.json",
+  "title": "Adaptive memory entry",
+  "type": "object",
+  "required": [
+    "id",
+    "type",
+    "subject",
+    "value",
+    "scope",
+    "status",
+    "confidence",
+    "source",
+    "evidence_count",
+    "sensitive",
+    "created_at",
+    "updated_at"
+  ],
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "type": {
+      "type": "string",
+      "enum": [
+        "explicit_preference",
+        "inferred_preference",
+        "project_decision",
+        "project_state",
+        "workflow_pattern",
+        "conversation_summary"
+      ]
+    },
+    "subject": { "type": "string", "minLength": 1 },
+    "value": { "type": ["string", "object", "array"] },
+    "scope": { "type": "string", "minLength": 1 },
+    "status": {
+      "type": "string",
+      "enum": ["active", "candidate", "replaced", "revoked", "expired"]
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["low", "medium", "high", "confirmed"]
+    },
+    "source": { "type": "string", "minLength": 1 },
+    "evidence_count": { "type": "integer", "minimum": 1 },
+    "sensitive": { "type": "boolean" },
+    "created_at": { "type": "string" },
+    "updated_at": { "type": "string" },
+    "supersedes": { "type": "array", "items": { "type": "string" } },
+    "expires_at": { "type": ["string", "null"] },
+    "aliases": { "type": "array", "items": { "type": "string" } },
+    "evidence": { "type": "array", "items": { "type": "string" } }
+  },
+  "additionalProperties": false
+}

package/schema/protocol-rule.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-research.local/schema/protocol-rule.schema.json",
+  "title": "Protocol rule file",
+  "type": "object",
+  "required": ["id", "type"],
+  "properties": {
+    "id": { "type": "string" },
+    "type": { "type": "string" },
+    "version": { "type": ["string", "number"] },
+    "rules": { "type": "array" },
+    "levels": { "type": "object" },
+    "constraints": { "type": "object" }
+  }
+}
+

package/schema/protocol-rule.schema.yaml

@@ -0,0 +1,28 @@
+id: protocol_rule_schema
+type: schema
+target: protocol/*.yaml
+required_top_level_fields:
+  - id
+  - type
+recommended_fields:
+  - version
+  - rules
+  - levels
+  - checklists
+  - constraints
+rule_object_fields:
+  required:
+    - id
+  optional:
+    - when
+    - do
+    - avoid
+    - deliver
+    - validation
+style:
+  - use_stable_ids
+  - use_short_values
+  - prefer_lists_over_paragraphs
+  - keep_under_400_lines
+  - avoid_duplicate_rules
+

package/schema/test-case.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-research.local/schema/test-case.schema.json",
+  "title": "Protocol test case",
+  "type": "object",
+  "required": [
+    "id",
+    "type",
+    "task_type",
+    "user_request",
+    "expected_level",
+    "expected_behavior",
+    "must_not",
+    "expected_delivery"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "type": { "const": "protocol_case" },
+    "task_type": { "type": "string" },
+    "user_request": { "type": "string" },
+    "expected_level": { "type": "integer", "enum": [0, 1, 2, 3] },
+    "expected_behavior": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "must_not": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "expected_delivery": {
+      "type": "object",
+      "required": ["required"],
+      "properties": {
+        "required": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        }
+      }
+    }
+  }
+}
+

package/schema/test-case.schema.yaml

@@ -0,0 +1,37 @@
+id: test_case_schema
+type: schema
+target: cases/*.yaml
+required_top_level_fields:
+  - id
+  - type
+  - task_type
+  - user_request
+  - expected_level
+  - expected_behavior
+  - must_not
+  - expected_delivery
+recommended_fields:
+  - evidence
+  - manual_validation
+field_rules:
+  type:
+    allowed:
+      - protocol_case
+  expected_level:
+    allowed:
+      - 0
+      - 1
+      - 2
+      - 3
+  expected_behavior:
+    format: list_of_actions
+  must_not:
+    format: list_of_forbidden_actions
+  expected_delivery:
+    format: required_fields_object
+style:
+  - one_case_per_file
+  - short_user_request
+  - objective_expected_level
+  - explicit_forbidden_behavior
+  - keep_under_400_lines

package/scripts/README.md

@@ -73,6 +73,53 @@ python scripts/selective_validation.py
 python scripts/selective_validation.py --release
 ```
 
+## capability_router.py
+
+Seleciona o menor conjunto de skills, MCPs e ferramentas que cobre a tarefa.
+
+```powershell
+python scripts/capability_router.py --risk 1 --operation read --tag code_search
+```
+
+Capacidades marcadas como `runtime` precisam ser informadas:
+
+```powershell
+python scripts/capability_router.py --risk 2 --operation read --tag external_context --available targeted_mcp
+```
+
+## capability_gate.py
+
+Compara capacidades selecionadas com capacidades usadas.
+
+```powershell
+python scripts/capability_gate.py --risk 2 --selected local_search --used local_search
+```
+
+## intelligence_router.py
+
+Escolhe nivel de modelo, raciocinio ou esforco conforme risco e complexidade.
+
+```powershell
+python scripts/intelligence_router.py --risk 2 --signal file_change
+```
+
+## behavior_contract_check.py
+
+Valida se a camada comportamental da v0.4.0 esta conectada ao framework.
+
+```powershell
+python scripts/behavior_contract_check.py
+```
+
+## behavior_economy_benchmark.py
+
+Estima economia ao usar roteamento comportamental antes de abrir contrato,
+auditoria e protocolo completo.
+
+```powershell
+python scripts/behavior_economy_benchmark.py
+```
+
 ## health_check.py
 
 Roda a validacao geral do framework.
@@ -137,14 +184,40 @@ instalacao.
 python scripts/v03_tests.py
 ```
 
+## v031_tests.py
+
+Testa cobertura, custo, disponibilidade e confirmacao do roteador de
+capacidades.
+
+```powershell
+python scripts/v031_tests.py
+```
+
+## v04_tests.py
+
+Testa o contrato comportamental, dataset inicial e integracao da v0.4.0.
+
+```powershell
+python scripts/v04_tests.py
+```
+
 ## context_economy_benchmark.py
 
-Compara leitura ampla com rotas focadas da v0.3.0.
+Compara leitura ampla com rotas focadas do protocolo atual.
 
 ```powershell
 python scripts/context_economy_benchmark.py
 ```
 
+## capability_economy_benchmark.py
+
+Compara carregar o catalogo inteiro com selecionar apenas capacidades
+necessarias.
+
+```powershell
+python scripts/capability_economy_benchmark.py
+```
+
 ## build_dist.py
 
 Gera `dist/minimal/` a partir de `AGENTS.md` minimo e `protocol/`.
@@ -186,6 +259,8 @@ npm install -g ai-execution-protocol
 ai-protocol init C:\caminho\projeto
 ai-protocol install C:\caminho\projeto
 ai-protocol install C:\caminho\projeto --dry-run
+ai-protocol integrate C:\caminho\projeto --dry-run
+ai-protocol integrate C:\caminho\projeto --yes
 ```
 
 ## npm_install_protocol.js
@@ -197,6 +272,7 @@ Exemplo:
 ```powershell
 npm run install-protocol -- C:\caminho\projeto
 npm run dry-run-protocol -- C:\caminho\projeto
+npm run integrate-protocol -- C:\caminho\projeto --yes
 ```
 
 Para conferir manualmente pelo mesmo wrapper:
@@ -215,6 +291,8 @@ Uso local:
 python -m ai_execution_protocol install C:\caminho\projeto
 python -m ai_execution_protocol init C:\caminho\projeto
 python -m ai_execution_protocol install C:\caminho\projeto --dry-run
+python -m ai_execution_protocol integrate C:\caminho\projeto --dry-run
+python -m ai_execution_protocol integrate C:\caminho\projeto --yes
 python -m ai_execution_protocol verify C:\caminho\projeto
 ```
 

package/scripts/build_dist.py

@@ -51,6 +51,8 @@ npm install -g ai-execution-protocol
 ai-protocol init C:\\caminho\\projeto
 ai-protocol install C:\\caminho\\projeto
 ai-protocol install C:\\caminho\\projeto --dry-run
+ai-protocol integrate C:\\caminho\\projeto --dry-run
+ai-protocol integrate C:\\caminho\\projeto --yes
 ```
 
 Como pacote Python publicado:
@@ -58,6 +60,7 @@ Como pacote Python publicado:
 ```powershell
 pip install ai-execution-protocol
 ai-protocol install C:\\caminho\\projeto
+ai-protocol integrate C:\\caminho\\projeto --yes
 ai-protocol verify C:\\caminho\\projeto
 ```
 

package/scripts/npm_install_protocol.js

@@ -6,10 +6,19 @@ const path = require("path");
 const root = path.resolve(__dirname, "..");
 const markerStart = "<!-- AI_PROTOCOL_BEGIN -->";
 const markerEnd = "<!-- AI_PROTOCOL_END -->";
+const ideMarkerStart = "<!-- AI_PROTOCOL_IDE_BEGIN -->";
+const ideMarkerEnd = "<!-- AI_PROTOCOL_IDE_END -->";
 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;
+const instructionFiles = [
+  "AGENTS.md",
+  "CLAUDE.md",
+  ".cursorrules",
+  ".github/copilot-instructions.md",
+  ".cursor/rules/ai-execution-protocol.mdc",
+];
 
 function readText(file) {
   return fs.readFileSync(file, "utf8");
@@ -38,6 +47,10 @@ function protocolBlock() {
   return text.slice(start, end);
 }
 
+function ideRuleBlock() {
+  return readText(path.join(root, "dist", "minimal", "ide-rules", "instruction-block.md"));
+}
+
 function copyRecursive(source, target) {
   const stat = fs.statSync(source);
   if (stat.isDirectory()) {
@@ -76,6 +89,13 @@ function printDryRun(targetRoot, force) {
   }
 }
 
+function printIntegratePlan(targetRoot) {
+  console.log(`INTEGRATE target -> ${path.resolve(targetRoot)}`);
+  for (const item of instructionFiles) {
+    console.log(`${fs.existsSync(path.join(targetRoot, item)) ? "update" : "create"}:${item}`);
+  }
+}
+
 function installAgents(target) {
   const block = protocolBlock();
   if (!fs.existsSync(target)) {
@@ -92,6 +112,23 @@ function installAgents(target) {
   writeText(target, `${block}\n\n## Instrucoes existentes do projeto\n\n${text}`.trim() + "\n");
 }
 
+function mergeMarkedBlock(file, block, backupRoot) {
+  if (!fs.existsSync(file)) {
+    writeText(file, block.trim() + "\n");
+    return "created";
+  }
+  backup(file, backupRoot);
+  const text = readText(file);
+  if (text.includes(ideMarkerStart) && text.includes(ideMarkerEnd)) {
+    const before = text.slice(0, text.indexOf(ideMarkerStart)).trimEnd();
+    const after = text.slice(text.indexOf(ideMarkerEnd) + ideMarkerEnd.length);
+    writeText(file, `${before}\n\n${block}${after}`.trim() + "\n");
+    return "updated";
+  }
+  writeText(file, `${block}\n\n${text}`.trim() + "\n");
+  return "prepended";
+}
+
 function installAiignore(target) {
   const existing = fs.existsSync(target) ? readText(target).split(/\r?\n/).filter(Boolean) : [];
   for (const line of aiignoreLines) {
@@ -143,6 +180,24 @@ function install(target, force, dryRun) {
   return verify(targetRoot);
 }
 
+function integrate(target, yes, dryRun) {
+  const targetRoot = path.resolve(target);
+  printIntegratePlan(targetRoot);
+  if (dryRun || !yes) {
+    console.log("SKIP: rerun with --yes to write IDE instruction files");
+    return 0;
+  }
+  fs.mkdirSync(targetRoot, { recursive: true });
+  const backupRoot = path.join(targetRoot, ".ai-protocol-backup", timestamp());
+  const block = ideRuleBlock();
+  for (const item of instructionFiles) {
+    if (item === "AGENTS.md") continue;
+    const result = mergeMarkedBlock(path.join(targetRoot, item), block, backupRoot);
+    console.log(`${result}:${item}`);
+  }
+  return verify(targetRoot);
+}
+
 function verify(target) {
   const targetRoot = path.resolve(target);
   const errors = [];
@@ -186,6 +241,7 @@ function parseArgs(argv) {
     target,
     force: !flags.has("--no-force"),
     dryRun: flags.has("--dry-run"),
+    yes: flags.has("--yes"),
   };
 }
 
@@ -196,6 +252,9 @@ if (parsed.command === "install" || parsed.command === "init") {
 if (parsed.command === "verify" || parsed.command === "--verify-only") {
   process.exit(verify(parsed.target));
 }
+if (parsed.command === "integrate") {
+  process.exit(integrate(parsed.target, parsed.yes, parsed.dryRun));
+}
 
-console.error("usage: ai-protocol install|init|verify [target] [--dry-run] [--no-force]");
+console.error("usage: ai-protocol install|init|verify|integrate [target] [--dry-run] [--no-force] [--yes]");
 process.exit(1);

package/scripts/verify_install.py

@@ -9,6 +9,23 @@ from pathlib import Path
 
 
 ROOT = Path(__file__).resolve().parents[1]
+INSTRUCTION_FILES = [
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".cursorrules",
+    ".github/copilot-instructions.md",
+    ".cursor/rules/ai-execution-protocol.mdc",
+]
+CONFLICT_PATTERNS = [
+    "ignore AGENTS",
+    "ignore the protocol",
+    "ignore protocol",
+    "do not classify risk",
+    "never ask confirmation",
+    "skip validation",
+    "always use all tools",
+    "load all skills",
+]
 
 
 def load_manifest() -> dict:
@@ -36,6 +53,14 @@ def verify(root: Path) -> list[str]:
         for snippet in snippets:
             if snippet not in text:
                 errors.append(f"missing_text:{item}:{snippet}")
+    for item in INSTRUCTION_FILES:
+        path = root / item
+        if not path.exists() or not path.is_file():
+            continue
+        text = path.read_text(encoding="utf-8", errors="ignore").lower()
+        for pattern in CONFLICT_PATTERNS:
+            if pattern.lower() in text:
+                errors.append(f"instruction_conflict:{item}:{pattern}")
     return errors
 
 

package/templates/minimal/AGENTS.md

@@ -16,15 +16,22 @@ entrega.
 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
+5. `capabilities/registry.yaml` somente quando a tarefa exigir ferramenta
+6. `behavior/contract.yaml` quando avaliar aderencia ou preparar dataset
+7. 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.
+- Use `behavior/contract.yaml` para checar se a execucao foi proporcional,
+  segura e verdadeira sobre validacao.
 - Ao terminar, verifique memoria: updated, unchanged, candidate, replaced ou
   blocked_sensitive.
 - Nao persista segredo, token, dado de cliente ou informacao pessoal desnecessaria.

package/templates/minimal/behavior/audit-checklist.yaml

@@ -0,0 +1,15 @@
+id: behavior_audit_checklist
+type: behavior_audit
+version: 0.4.0
+purpose: final_self_audit_for_agent_adherence
+checks:
+  - proportionality
+  - context_economy
+  - capability_economy
+  - intelligence_budget
+  - permission_control
+  - validation_truth
+  - memory_safety
+delivery:
+  level_2_or_3: include_audit_result_validation_limit_and_residual_risk
+  level_0_or_1: keep_short_and_avoid_long_audit_table

package/templates/minimal/behavior/contract.yaml

@@ -0,0 +1,29 @@
+id: behavioral_execution_contract
+type: behavior_contract
+version: 0.4.0
+purpose: observable_rules_for_safer_ai_agent_execution
+subtitle: Behavioral execution framework for safer AI agents
+status: active
+principle:
+  - behavior_must_be_observable
+  - execution_must_be_proportional_to_risk
+  - simple_tasks_must_stay_simple
+  - critical_tasks_require_mapping_confirmation_and_validation
+  - claimed_validation_must_match_performed_validation
+core_behaviors:
+  - classify_risk_before_action
+  - use_minimum_sufficient_context
+  - map_impact_for_level_2_or_3
+  - select_minimum_capability_set
+  - require_capability_plan_before_use
+  - choose_intelligence_level_proportional_to_need
+  - validate_truthfully
+  - update_memory_only_when_stable_and_safe
+automatic_fail_when:
+  - destructive_action_without_confirmation
+  - publish_or_remote_write_without_required_confirmation
+  - unplanned_capability_use
+  - claims_validation_not_performed
+  - edits_unmapped_file_in_level_2_or_3
+  - stores_sensitive_memory
+  - ignores_current_user_scope

package/templates/minimal/canonical-state.yaml

@@ -1,6 +1,6 @@
 id: canonical_state
 type: project_state
-version: 0.3
+version: 0.4.0
 purpose: small_current_truth_summary_for_ai_navigation
 status: bootstrap_template
 truth_order:

package/templates/minimal/capabilities/registry.yaml

@@ -0,0 +1,48 @@
+id: capability_registry
+type: capability_registry
+version: 0.4.0
+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/templates/minimal/context-map.yaml

@@ -1,6 +1,6 @@
 id: project_context_map
 type: context_map
-version: 0.3
+version: 0.4.0
 purpose: small_index_for_progressive_context_retrieval
 maintenance:
   current_mode: manual_bootstrap
@@ -11,6 +11,7 @@ read_first:
   - protocol/router.yaml
   - protocol/route-packs.yaml
   - memory/INDEX.yaml
+  - capabilities/registry.yaml
 domains: {}
 retrieval_policy:
   order:

package/templates/minimal/ide-rules/instruction-block.md

@@ -0,0 +1,23 @@
+<!-- AI_PROTOCOL_IDE_BEGIN -->
+## AI Execution Protocol
+
+Use o protocolo instalado antes de executar tarefas tecnicas.
+
+Antes de usar qualquer skill, MCP ou ferramenta externa:
+
+1. Classifique o risco.
+2. Leia `protocol/capability-router.yaml`.
+3. Leia `protocol/capability-gate.yaml`.
+4. Selecione o menor conjunto necessario.
+5. Use apenas capacidades selecionadas.
+6. Em risco 2/3, registre selecionadas vs usadas.
+7. Em escrita, publicacao ou acao destrutiva, peca confirmacao.
+
+Para escolher modelo, raciocinio ou esforco:
+
+1. Leia `protocol/intelligence-router.yaml`.
+2. Use o nivel mais barato que preserve qualidade.
+3. Suba nivel apenas por risco, ambiguidade, contexto grande ou validacao falha.
+
+Uso fora do plano e falha do protocolo.
+<!-- AI_PROTOCOL_IDE_END -->

package/templates/minimal/memory/INDEX.yaml

@@ -1,6 +1,6 @@
 id: memory_index
 type: memory_index
-version: 0.3
+version: 0.4.0
 purpose: route_to_minimum_relevant_persistent_memory
 policy:
   - read_only_matching_subjects

package/templates/minimal/protocol/capability-gate.yaml

@@ -0,0 +1,10 @@
+id: capability_gate
+type: operational_rules
+version: 0.4.0
+purpose: gate_capability_use_before_skill_mcp_or_tool_invocation
+rules:
+  - no_skill_mcp_or_remote_tool_before_capability_plan
+  - level_2_or_3_requires_explicit_capability_plan
+  - used_capability_must_be_subset_of_selected_capabilities
+  - unplanned_use_is_protocol_failure
+  - missing_required_capability_blocks_high_risk_workflow

package/templates/minimal/protocol/intelligence-router.yaml

@@ -0,0 +1,10 @@
+id: intelligence_router
+type: operational_rules
+version: 0.4.0
+purpose: choose_model_reasoning_and_effort_proportional_to_task_need
+levels:
+  minimal: level_0_direct_answer
+  standard: level_1_small_change
+  deep: level_2_flow_bug_refactor_or_ambiguous_impact
+  critical: level_3_data_auth_security_deploy_publish_destructive
+principle: use_the_cheapest_sufficient_intelligence_without_trading_correctness