ai-execution-protocol 0.3.1 → 0.4.0

package/install-manifest.json

@@ -16,6 +16,8 @@
     "persistent-context.yaml",
     "adaptive-memory.yaml",
     "capability-router.yaml",
+    "capability-gate.yaml",
+    "intelligence-router.yaml",
     "formatting-rules.yaml",
     "prompt-economy.yaml",
     "spec-driven.yaml"
@@ -28,7 +30,9 @@
     "decisions/README.md",
     "memory/INDEX.yaml",
     "candidate-memory/README.md",
-    "capabilities/registry.yaml"
+    "capabilities/registry.yaml",
+    "behavior/contract.yaml",
+    "behavior/audit-checklist.yaml"
   ],
   "aiignore_lines": [
     "results/",
@@ -45,7 +49,8 @@
       "protocol/router.yaml",
       "protocol/route-packs.yaml",
       "Classifique o risco antes de agir",
-      "protocol/capability-router.yaml"
+      "protocol/capability-router.yaml",
+      "behavior/contract.yaml"
     ],
     "memory/INDEX.yaml": [
       "memory_index",
@@ -67,9 +72,29 @@
       "minimum_capability_set",
       "higher_risk_means_stricter_permissions_not_more_tools"
     ],
+    "protocol/capability-gate.yaml": [
+      "capability_gate",
+      "plan_before_use_audit_after_use",
+      "unplanned_use_is_protocol_failure"
+    ],
+    "protocol/intelligence-router.yaml": [
+      "intelligence_router",
+      "cheapest_sufficient_intelligence",
+      "critical"
+    ],
     "capabilities/registry.yaml": [
       "capability_registry",
       "runtime_availability_must_be_verified"
+    ],
+    "behavior/contract.yaml": [
+      "behavior_contract",
+      "Behavioral execution framework for safer AI agents",
+      "claimed_validation_must_match_performed_validation"
+    ],
+    "behavior/audit-checklist.yaml": [
+      "behavior_audit_checklist",
+      "validation_truth",
+      "capability_economy"
     ]
   }
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "ai-execution-protocol",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "private": false,
-  "description": "Experimental AI execution protocol for safer agent workflows, minimal context, risk classification, validation, and evidence-based delivery.",
+  "description": "Behavioral execution framework for safer AI agents, minimal context, risk control, validation, and evidence-based delivery.",
   "license": "MIT",
   "author": "AI Execution Protocol",
   "homepage": "https://github.com/rodneigk2/ai-execution-protocol#readme",
@@ -35,6 +35,12 @@
     "scripts/verify_install.py",
     "install-manifest.json",
     "protocol/",
+    "behavior/",
+    "dataset/",
+    "docs/",
+    "eval/",
+    "schema/",
+    "roadmap/",
     "templates/minimal/",
     "dist/minimal/"
   ],
@@ -43,6 +49,7 @@
     "init-protocol": "node scripts/npm_install_protocol.js init",
     "install-protocol": "node scripts/npm_install_protocol.js install",
     "dry-run-protocol": "node scripts/npm_install_protocol.js install --dry-run",
+    "integrate-protocol": "node scripts/npm_install_protocol.js integrate",
     "verify-protocol": "node scripts/npm_install_protocol.js verify"
   }
 }

package/protocol/README.yaml

@@ -1,7 +1,7 @@
 id: protocol_index
 type: index
 format: yaml
-protocol_version: 0.3.1
+protocol_version: 0.4.0
 purpose: ai_operational_rules
 source_docs: ../docs
 constraints:
@@ -39,6 +39,14 @@ files:
     purpose: maintain_verified_user_and_project_memory
   - path: capability-router.yaml
     purpose: select_minimum_skills_mcps_and_tools_by_value_cost_and_risk
+  - path: capability-gate.yaml
+    purpose: require_plan_before_capability_use_and_audit_after_use
+  - path: intelligence-router.yaml
+    purpose: choose_model_reasoning_effort_by_risk_and_complexity
+  - path: ../behavior/contract.yaml
+    purpose: define_observable_behavior_for_agent_adherence
+  - path: ../behavior/audit-checklist.yaml
+    purpose: final_self_audit_for_agent_adherence
   - path: formatting-rules.yaml
     purpose: ai_readable_file_format
   - path: prompt-economy.yaml

package/protocol/capability-gate.yaml

@@ -0,0 +1,56 @@
+id: capability_gate
+type: operational_rules
+version: 0.4.0
+purpose: gate_capability_use_before_skill_mcp_or_tool_invocation
+principle: plan_before_use_audit_after_use
+guarantee_boundary:
+  framework_can:
+    - require_capability_plan_before_use
+    - mark_unplanned_use_as_protocol_failure
+    - compare_used_capabilities_with_selected_capabilities
+    - block_high_risk_workflow_when_plan_is_missing
+  host_must:
+    - hide_or_disable_tools_for_physical_enforcement
+    - enforce_runtime_permissions
+required_before_use:
+  - task_objective
+  - risk_level
+  - operation_scope
+  - requested_operations
+  - required_outcome_tags
+  - selected_capabilities
+  - confirmation_status_when_required
+allowed_states:
+  planned:
+    meaning: selected_but_not_invoked
+  used:
+    meaning: invoked_within_plan_and_scope
+  blocked:
+    meaning: needed_but_missing_or_unconfirmed
+  violation:
+    meaning: used_without_plan_or_outside_scope
+rules:
+  - no_skill_mcp_or_remote_tool_before_capability_plan
+  - local_read_can_be_implicit_only_for_level_0_or_1_basic_navigation
+  - level_2_or_3_requires_explicit_capability_plan
+  - publish_write_or_destructive_requires_confirmation_when_policy_requires
+  - used_capability_must_be_subset_of_selected_capabilities
+  - unplanned_use_is_protocol_failure
+  - missing_required_capability_blocks_high_risk_workflow
+audit:
+  compare:
+    - selected_capabilities
+    - used_capabilities
+    - operation_scope
+    - confirmation_status
+  fail_when:
+    - used_not_selected
+    - used_for_unapproved_operation
+    - used_after_blocked_status
+    - publish_without_confirmation
+delivery:
+  include_for_level_2_or_3:
+    - capability_plan_summary
+    - used_capabilities
+    - gate_status
+    - violations_if_any

package/protocol/capability-router.yaml

@@ -1,6 +1,6 @@
 id: capability_router
 type: operational_rules
-version: 0.3.1
+version: 0.4.0
 purpose: select_only_necessary_skills_mcps_and_tools
 principle: minimum_capability_set_must_preserve_required_quality
 platform_boundary:

package/protocol/context-rules.yaml

@@ -70,6 +70,7 @@ existing_project_files:
     - .cursorrules
     - CLAUDE.md
     - .github/copilot-instructions.md
+    - .cursor/rules/ai-execution-protocol.mdc
     - package_docs
     - framework_configs
   behavior:
@@ -78,7 +79,7 @@ existing_project_files:
     - treat_generated_or_old_docs_as_untrusted_until_verified
     - keep_protocol_rules_in_AGENTS_and_protocol_folder
     - use_framework_configs_as_technical_source_when_task_touches_framework
-    - do_not_duplicate_protocol_rules_across_ide_files
+    - duplicate_protocol_rules_across_ide_files_only_with_marked_integration
   conflict_order:
     - current_user_request
     - AGENTS_protocol_block

package/protocol/fast-path.yaml

@@ -1,12 +1,14 @@
 id: fast_path
 type: agent_entrypoint
-version: 0.3.1
+version: 0.4.0
 purpose: minimum_rules_to_start_any_task
 read_next:
   - router.yaml
   - route-packs.yaml
   - context-budget.yaml
   - capability-router.yaml
+  - capability-gate.yaml
+  - intelligence-router.yaml
   - modes.yaml
 core_rules:
   - classify_risk_before_action
@@ -26,6 +28,9 @@ core_rules:
   - check_memory_update_result_after_task
   - use_selective_validation_by_blast_radius
   - select_minimum_capability_set_before_loading_skills_or_mcps
+  - require_capability_plan_before_skill_mcp_or_remote_tool_use
+  - choose_intelligence_level_proportional_to_risk_and_complexity
+  - follow_behavioral_execution_contract
 risk_short:
   level_0: answer_only
   level_1: small_clear_reversible_isolated_change

package/protocol/intelligence-router.yaml

@@ -0,0 +1,63 @@
+id: intelligence_router
+type: operational_rules
+version: 0.4.0
+purpose: choose_model_reasoning_and_effort_proportional_to_task_need
+principle: use_the_cheapest_sufficient_intelligence_without_trading_correctness
+levels:
+  minimal:
+    use_when:
+      - level_0_direct_answer
+      - no_current_external_data_needed
+      - no_file_change
+    model_need: low_cost_fast
+    reasoning_depth: low
+    tools: none
+  standard:
+    use_when:
+      - level_1_small_change
+      - focused_file_read
+      - simple_validation
+    model_need: default
+    reasoning_depth: medium
+    tools: local_only
+  deep:
+    use_when:
+      - level_2_flow_bug
+      - refactor
+      - ambiguous_impact
+      - failed_first_validation
+    model_need: stronger_or_more_reasoning
+    reasoning_depth: high
+    tools: selected_local_or_targeted_remote
+  critical:
+    use_when:
+      - level_3_data_auth_security_deploy_publish_destructive
+      - high_blast_radius
+      - irreversible_or_external_side_effect
+    model_need: strongest_available_for_task
+    reasoning_depth: high_with_audit
+    tools: least_privilege_confirmed
+escalate_when:
+  - risk_level_increases
+  - ambiguity_blocks_safe_action
+  - validation_fails
+  - context_conflict_detected
+  - external_current_data_is_required
+  - specialized_modality_is_required
+deescalate_when:
+  - task_is_direct_answer
+  - no_code_or_external_state_needed
+  - validation_plan_is_trivial
+  - previous_high_risk_assumption_is_not_supported_by_evidence
+never_trade:
+  - security
+  - correctness
+  - required_validation
+  - explicit_user_scope
+delivery:
+  include_when_level_2_or_3:
+    - intelligence_level
+    - escalation_reason_if_any
+    - why_lower_level_was_not_enough
+  omit_for_level_0:
+    - model_discussion_unless_user_asks

package/protocol/route-packs.yaml

@@ -1,6 +1,6 @@
 id: route_packs
 type: route_summary_index
-version: 0.3.1
+version: 0.4.0
 purpose: compact_first_read_before_full_route_files
 principle: read_pack_first_expand_only_when_needed
 use:
@@ -120,10 +120,12 @@ packs:
       - run_post_deploy_check_if_executed
   evaluate_response:
     read_if_pack_insufficient:
+      - ../behavior/contract.yaml
       - ../eval/rubric.yaml
       - ../schema/evaluated-response.schema.json
     do:
       - score_risk_behavior_avoidance_delivery_clarity
+      - check_behavior_contract_alignment
       - apply_automatic_fail_rules
   create_or_edit_yaml:
     read_if_pack_insufficient:
@@ -186,10 +188,45 @@ packs:
     risk: adaptive
     read_if_pack_insufficient:
       - capability-router.yaml
+      - capability-gate.yaml
       - context-budget.yaml
     do:
       - define_required_outcomes_and_operations
       - select_smallest_available_capability_set
       - load_only_selected_skill_or_mcp
       - require_confirmation_for_sensitive_remote_effect
+      - audit_used_capabilities_against_selected_plan
       - stop_discovery_when_quality_coverage_is_complete
+  intelligence_selection:
+    risk: adaptive
+    read_if_pack_insufficient:
+      - intelligence-router.yaml
+      - context-budget.yaml
+    do:
+      - choose_cheapest_sufficient_intelligence_level
+      - escalate_for_risk_ambiguity_validation_failure_or_large_context
+      - deescalate_when_task_is_direct_and_low_risk
+      - do_not_trade_security_correctness_or_validation_for_cost
+  behavior_evaluation:
+    risk: 1
+    read_if_pack_insufficient:
+      - ../behavior/contract.yaml
+      - ../behavior/audit-checklist.yaml
+      - ../eval/rubric.yaml
+    do:
+      - compare_response_to_observable_behaviors
+      - verify_simple_tasks_are_not_overprocessed
+      - verify_critical_tasks_are_not_undercontrolled
+      - apply_behavior_automatic_fail_rules
+  dataset_preparation:
+    risk: 1
+    read_if_pack_insufficient:
+      - ../behavior/contract.yaml
+      - ../behavior/audit-checklist.yaml
+      - prompt-economy.yaml
+      - ../dataset/README.md
+    do:
+      - create_examples_from_observable_behavior
+      - include_good_bad_and_reason
+      - keep_training_examples_consistent
+      - avoid_rewarding_bureaucracy

package/protocol/router.yaml

@@ -1,6 +1,6 @@
 id: protocol_router
 type: read_router
-version: 0.3.1
+version: 0.4.0
 purpose: choose_minimum_protocol_files_by_task
 default_read:
   - fast-path.yaml
@@ -76,8 +76,17 @@ routes:
   evaluate_response:
     read:
       - fast-path.yaml
+      - ../behavior/contract.yaml
       - ../eval/rubric.yaml
       - ../schema/evaluated-response.schema.json
+  behavior_evaluation:
+    risk: 1
+    read:
+      - fast-path.yaml
+      - ../behavior/contract.yaml
+      - ../behavior/audit-checklist.yaml
+      - ../eval/rubric.yaml
+      - ../dataset/README.md
   create_or_edit_yaml:
     read:
       - fast-path.yaml
@@ -118,7 +127,22 @@ routes:
     read:
       - fast-path.yaml
       - capability-router.yaml
+      - capability-gate.yaml
+      - context-budget.yaml
+  intelligence_selection:
+    risk: adaptive
+    read:
+      - fast-path.yaml
+      - intelligence-router.yaml
       - context-budget.yaml
+  dataset_preparation:
+    risk: 1
+    read:
+      - fast-path.yaml
+      - ../behavior/contract.yaml
+      - ../behavior/audit-checklist.yaml
+      - prompt-economy.yaml
+      - ../dataset/README.md
 rules:
   - start_with_default_read
   - choose_one_route_if_task_type_is_clear
@@ -127,6 +151,9 @@ rules:
   - apply_context_budget_to_selected_route
   - retrieve_only_matching_memory_subjects
   - select_capabilities_before_loading_skill_or_connecting_mcp
+  - require_capability_gate_before_invocation
+  - route_model_or_reasoning_effort_by_risk_and_complexity
+  - use_behavior_contract_when_task_is_about_adherence_dataset_or_training
   - 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/roadmap/v1.yaml

@@ -0,0 +1,139 @@
+id: roadmap_v1
+type: release_roadmap
+version: 0.1
+target_release: 1.0.0
+purpose: guide_each_update_until_public_v1
+status: active
+principle:
+  - do_not_market_as_stable_before_v1
+  - each_release_must_close_one_maturity_gap
+  - prove_context_economy_quality_and_safety_with_examples
+  - keep_protocol_core_stable_before_broad_public_launch
+current_position:
+  current_series: 0.4.x
+  maturity: behavioral_execution_layer
+  public_positioning: experimental_until_v1
+  publish_strategy: publish_packages_for_testing_not_broad_marketing
+v1_success_criteria:
+  protocol_stability:
+    - risk_levels_stable
+    - context_budget_stable
+    - adaptive_memory_stable
+    - capability_routing_stable
+    - selective_validation_stable
+  evidence:
+    - real_cases_documented
+    - before_after_examples_available
+    - benchmark_report_current
+    - install_and_update_flow_verified
+  adoption:
+    - codex_guide_clear
+    - other_agent_portability_documented
+    - troubleshooting_documented
+    - contribution_rules_clear
+  safety:
+    - secret_handling_documented
+    - sensitive_actions_require_confirmation
+    - memory_deduplication_and_replacement_validated
+    - capability_permissions_follow_least_privilege
+release_path:
+  - version: 0.3.x
+    goal: harden_current_capability_context_memory_stack
+    status: completed
+    exit_criteria:
+      - capability_routing_documented_and_tested
+      - docs_commands_and_install_flow_stay_synced
+      - no_known_packaging_gap_blocks_testing
+  - version: 0.4.0
+    goal: add_behavioral_execution_contract_and_economy_reports
+    status: current
+    focus:
+      - behavioral_contract
+      - trainable_behavior_units
+      - token_and_file_read_savings
+      - tools_avoided
+      - validation_cost_by_risk
+      - quality_preserved_examples
+    exit_criteria:
+      - behavior_contract_is_installed_and_validated
+      - benchmark_report_has_clear_before_after_numbers
+      - benchmark_can_be_reproduced_locally
+  - version: 0.5.0
+    goal: add_real_world_cases
+    focus:
+      - simple_task
+      - medium_risk_bug
+      - docs_update
+      - capability_or_mcp_task
+      - memory_update_task
+      - release_task
+    exit_criteria:
+      - at_least_6_real_or_realistic_cases
+      - each_case_has_context_used_validation_and_outcome
+  - version: 0.6.0
+    goal: document_portability_beyond_codex
+    focus:
+      - codex_primary_flow
+      - cursor_adaptation
+      - claude_or_generic_agent_adaptation
+      - mcp_capability_boundaries
+    exit_criteria:
+      - portability_limits_are_explicit
+      - codex_specific_rules_are_separated_from_generic_rules
+  - version: 0.7.0
+    goal: harden_schemas_validation_and_health_checks
+    focus:
+      - schema_coverage
+      - health_check_coverage
+      - install_manifest_consistency
+      - package_content_checks
+    exit_criteria:
+      - health_check_catches_missing_core_files
+      - release_checks_cover_docs_protocol_templates_and_packages
+  - version: 0.8.0
+    goal: finish_adoption_documentation
+    focus:
+      - getting_started
+      - install_update_verify
+      - project_adaptation
+      - troubleshooting
+      - contribution_guidelines
+    exit_criteria:
+      - new_user_can_install_verify_and_understand_core_flow
+      - docs_are_atomic_and_indexed
+  - version: 0.9.0
+    goal: release_candidate
+    focus:
+      - freeze_core_contracts
+      - remove_or_mark_unstable_experimental_parts
+      - run_full_validation
+      - prepare_v1_release_notes
+    exit_criteria:
+      - no_known_blocker_for_v1
+      - docs_and_protocol_are_consistent
+      - packages_install_cleanly
+  - version: 1.0.0
+    goal: stable_public_release
+    focus:
+      - stable_protocol_core
+      - clear_public_positioning
+      - reproducible_evidence
+      - safe_installation
+    exit_criteria:
+      - v1_success_criteria_met
+update_rule:
+  before_each_release:
+    - read_this_roadmap
+    - choose_next_smallest_maturity_gap
+    - update_docs_protocol_tests_when_behavior_changes
+    - record_completed_and_remaining_exit_criteria
+  after_each_release:
+    - update_current_position
+    - mark_exit_criteria_done_or_pending
+    - update_docs_22_roadmap_v1
+    - keep_changelog_release_notes_synced
+avoid:
+  - broad_marketing_before_v1
+  - claiming_security_guarantees
+  - changing_core_terms_without_migration_note
+  - adding_new_surfaces_without_tests_or_docs

package/schema/README.md

@@ -0,0 +1,26 @@
+# Schemas
+
+Esta pasta descreve o formato esperado dos arquivos YAML.
+
+Os schemas sao leves e servem como contrato de organizacao. Eles ajudam a IA a
+manter arquivos parecidos entre si.
+
+## Arquivos
+
+- [protocol-rule.schema.yaml](./protocol-rule.schema.yaml): formato de regra
+  operacional.
+- [test-case.schema.yaml](./test-case.schema.yaml): formato de caso de teste.
+- [protocol-rule.schema.json](./protocol-rule.schema.json): JSON Schema
+  validavel para regras operacionais.
+- [test-case.schema.json](./test-case.schema.json): JSON Schema validavel para
+  casos.
+- [evaluated-response.schema.json](./evaluated-response.schema.json): JSON
+  Schema validavel para respostas avaliaveis.
+- [evaluation-result.schema.json](./evaluation-result.schema.json): JSON Schema
+  validavel para resultados.
+- [memory-entry.schema.json](./memory-entry.schema.json): contrato de uma
+  entrada de memoria adaptativa.
+- [capability-registry.schema.json](./capability-registry.schema.json):
+  contrato do registro de skills, MCPs e ferramentas.
+- [behavior-contract.schema.json](./behavior-contract.schema.json): contrato
+  da camada comportamental observavel.

package/schema/behavior-contract.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-research.local/schema/behavior-contract.schema.json",
+  "title": "Behavior contract",
+  "type": "object",
+  "required": [
+    "id",
+    "type",
+    "version",
+    "purpose",
+    "principle",
+    "automatic_fail_when"
+  ],
+  "properties": {
+    "id": { "type": "string" },
+    "type": { "const": "behavior_contract" },
+    "version": { "type": ["string", "number"] },
+    "purpose": { "type": "string" },
+    "subtitle": { "type": "string" },
+    "status": { "type": "string" },
+    "principle": { "type": "array", "items": { "type": "string" } },
+    "scope": { "type": "object" },
+    "behavior_sets": { "type": "array" },
+    "core_behaviors": { "type": "array", "items": { "type": "string" } },
+    "trainable_units": { "type": "array" },
+    "evaluation_dimensions": { "type": "array" },
+    "automatic_fail_when": { "type": "array", "items": { "type": "string" } },
+    "dataset_policy": { "type": "object" }
+  },
+  "additionalProperties": false
+}

package/schema/capability-registry.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-research.local/schema/capability-registry.schema.json",
+  "title": "Capability registry",
+  "type": "object",
+  "required": ["id", "type", "version", "capabilities"],
+  "properties": {
+    "id": { "type": "string" },
+    "type": { "const": "capability_registry" },
+    "version": { "type": ["string", "number"] },
+    "purpose": { "type": "string" },
+    "policy": { "type": "object" },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "type",
+          "available",
+          "tags",
+          "operations",
+          "cost",
+          "side_effect",
+          "confirmation"
+        ],
+        "properties": {
+          "id": { "type": "string" },
+          "type": {
+            "enum": [
+              "built_in_reasoning",
+              "local_tool",
+              "skill",
+              "mcp",
+              "remote_service"
+            ]
+          },
+          "available": { "type": ["boolean", "string"] },
+          "tags": { "type": "array", "items": { "type": "string" } },
+          "operations": { "type": "array", "items": { "type": "string" } },
+          "cost": { "type": "object" },
+          "side_effect": { "type": "string" },
+          "confirmation": { "type": "string" },
+          "depends_on": { "type": "array", "items": { "type": "string" } }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}