ai-execution-protocol 0.2.1 → 0.3.0

package/dist/minimal/protocol/prompt-economy.yaml

@@ -1,6 +1,6 @@
 id: prompt_economy
 type: operational_rules
-version: 0.1
+version: 0.3
 purpose: improve_user_prompt_without_token_bloat
 principle: always_improve_prompt_only_as_much_as_needed_for_safe_execution
 rules:
@@ -34,15 +34,20 @@ rules:
       - validation
       - confirmation_if_needed
   - id: PROMPT_005
-    name: always_show_prompt_comparison
+    name: show_prompt_comparison_when_interpretation_matters
     do:
-      - include_user_original_prompt
-      - include_ai_improved_prompt
+      - include_user_original_prompt_for_technical_or_interpreted_tasks
+      - include_ai_improved_prompt_for_technical_or_interpreted_tasks
       - keep_comparison_to_minimum_viable_words
       - preserve_user_language_when_possible
     avoid:
       - hiding_interpretation_from_user
       - expanding_simple_requests_into_large_specs
+    may_omit_when:
+      - level_0
+      - no_technical_action
+      - no_scope_or_intent_interpretation
+      - direct_answer_is_clearer
 limits:
   level_0:
     max_lines: 5
@@ -75,16 +80,19 @@ delivery_rule:
     - "Feito: <what changed or answer>"
     - "Validado: <evidence or not run>"
     - "Risco: <residual risk or none>"
-  always_show:
-    - prompt_original
-    - prompt_melhorado_da_ia
+  show_when:
+    - technical_action
+    - scope_interpretation
+    - risk_level_1_or_higher
+    - prompt_improvement_changes_execution
   comparison:
     - original_prompt_must_keep_user_words_when_reasonable
     - improved_prompt_must_state_objective_scope_risk_validation
     - improved_prompt_must_fit_risk_level_limits
   token_policy:
     - use_abbreviated_labels_po_pm_when_user_did_not_request_full_form
-    - level_0_and_1_use_micro_template
+    - level_0_may_use_direct_answer_when_comparison_adds_no_value
+    - level_1_use_micro_template
     - level_2_use_compact_objective_scope_validation
     - level_3_include_risk_confirmation_without_long_spec
     - omit_tests_line_when_no_break_risk_exists

package/dist/minimal/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/dist/minimal/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/dist/minimal/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/dist/minimal/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/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"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-execution-protocol",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "private": false,
   "description": "Experimental AI execution protocol for safer agent workflows, minimal context, risk classification, validation, and evidence-based delivery.",
   "license": "MIT",
@@ -33,7 +33,9 @@
     "scripts/install_protocol.py",
     "scripts/npm_install_protocol.js",
     "scripts/verify_install.py",
+    "install-manifest.json",
     "protocol/",
+    "templates/minimal/",
     "dist/minimal/"
   ],
   "scripts": {

package/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

package/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

package/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

package/protocol/context-compiler.yaml

@@ -1,6 +1,6 @@
 id: context_compiler
 type: operational_rules
-version: 0.1
+version: 0.3
 purpose: build_minimum_context_package_before_model_reasoning
 principle: conversation_is_interface_not_source_of_truth
 canonical_state:
@@ -28,19 +28,25 @@ context_build:
     - user_request
     - route_from_router
     - risk_level
+    - context_budget
     - candidate_files_or_areas
+    - matching_memory_subjects
     - recent_validated_state
   output:
     - objective
     - constraints
     - relevant_rules
+    - matching_memory
     - candidate_files
+    - estimated_tokens
+    - budget_status
     - validation_plan
     - excluded_context
 selection_policy:
   include:
     - context_map_domain_when_available
     - active_decisions_for_matched_domain
+    - active_memory_matching_subject_and_scope
     - files_required_by_route
     - snippets_matching_task_terms
     - current_decisions_touching_candidate_area
@@ -51,6 +57,7 @@ selection_policy:
     - full_logs_without_error_focus
     - revoked_decisions_unless_comparing_history
     - entire_large_files_when_snippet_is_enough
+    - candidate_or_archived_memory_without_task_match
 memory_layers:
   active:
     definition: required_to_complete_current_task
@@ -93,6 +100,21 @@ decision_rules:
     avoid:
       - treating_alias_as_source_of_truth
       - editing_from_snippet_when_behavior_depends_on_unread_context
+  - id: CTX_006
+    when: persistent_memory_may_be_relevant
+    do:
+      - read_memory_index_first
+      - retrieve_only_matching_active_entries
+      - verify_project_state_against_current_files
+    avoid:
+      - loading_all_memory
+      - treating_candidate_memory_as_authoritative
+  - id: CTX_007
+    when: initial_context_budget_is_reached
+    do:
+      - stop_if_objective_target_and_validation_are_clear
+      - expand_only_for_unresolved_risk_dependency_scope_or_validation_gap
+      - record_expansion_reason
 retrieval_tiers:
   mvp:
     use:
@@ -121,6 +143,7 @@ delivery:
   include_when_relevant:
     - context_used
     - context_excluded
+    - context_budget_status
     - reason_for_not_reading_more
 economy_goal:
   target: reduce_unneeded_context_up_to_90_percent_when_safe

package/protocol/fast-path.yaml

@@ -1,10 +1,11 @@
 id: fast_path
 type: agent_entrypoint
-version: 0.1
+version: 0.3
 purpose: minimum_rules_to_start_any_task
 read_next:
   - router.yaml
   - route-packs.yaml
+  - context-budget.yaml
   - modes.yaml
 core_rules:
   - classify_risk_before_action
@@ -20,6 +21,9 @@ core_rules:
   - include_test_list_when_break_risk_exists
   - explain_in_plain_language_for_non_experts
   - use_context_compiler_when_context_or_history_is_large
+  - use_only_matching_memory_subjects
+  - check_memory_update_result_after_task
+  - use_selective_validation_by_blast_radius
 risk_short:
   level_0: answer_only
   level_1: small_clear_reversible_isolated_change
@@ -32,3 +36,4 @@ file_policy:
 stop_reading_when:
   - enough_context_to_act_safely
   - validation_plan_is_clear
+  - context_budget_is_sufficient

package/protocol/persistent-context.yaml

@@ -1,6 +1,6 @@
 id: persistent_context
 type: operational_rules
-version: 0.2
+version: 0.3
 purpose: navigate_project_memory_without_loading_unneeded_context
 principle: aliases_are_pointers_not_truth
 autonomous_memory:
@@ -22,6 +22,7 @@ economy_goal:
 entrypoints:
   - canonical-state.yaml
   - context-map.yaml
+  - memory/INDEX.yaml
   - decisions/
 progressive_retrieval:
   order:
@@ -29,6 +30,8 @@ progressive_retrieval:
     - match_domain_or_alias_in_context_map
     - read_canonical_state_when_project_truth_matters
     - read_active_decisions_for_domain
+    - query_memory_index_for_matching_subjects
+    - read_only_matching_active_memory
     - read_only_needed_atomic_subject_docs
     - search_candidate_symbols_or_files
     - read_relevant_snippet_first
@@ -51,6 +54,8 @@ context_validator:
   check:
     - enough_context_for_objective
     - active_decisions_loaded_when_relevant
+    - matching_memory_loaded_only_when_relevant
+    - context_budget_respected_or_expansion_justified
     - direct_dependencies_loaded_when_needed
     - adjacent_domain_risk_checked
     - docs_do_not_conflict_with_verified_files
@@ -88,9 +93,11 @@ snippet_policy:
 conflict_policy:
   order:
     - current_user_request
-    - canonical_state
-    - active_decisions
     - verified_code_or_files_this_turn
+    - active_decisions
+    - canonical_state
+    - explicit_user_preferences
+    - inferred_patterns_with_evidence
     - domain_docs
     - current_conversation
   if_docs_conflict_with_code:
@@ -100,6 +107,9 @@ validation:
   require:
     - state_context_used_when_relevant
     - state_context_not_loaded_when_excluded_for_economy
+    - memory_index_used_before_memory_files
+    - memory_update_result_recorded_when_new_durable_fact_exists
+    - sensitive_or_unverified_content_not_promoted
     - escalate_context_if_snippet_is_insufficient
     - update_subject_index_when_docs_are_split
 atomic_subject_flow:

package/protocol/prompt-economy.yaml

@@ -1,6 +1,6 @@
 id: prompt_economy
 type: operational_rules
-version: 0.1
+version: 0.3
 purpose: improve_user_prompt_without_token_bloat
 principle: always_improve_prompt_only_as_much_as_needed_for_safe_execution
 rules:
@@ -34,15 +34,20 @@ rules:
       - validation
       - confirmation_if_needed
   - id: PROMPT_005
-    name: always_show_prompt_comparison
+    name: show_prompt_comparison_when_interpretation_matters
     do:
-      - include_user_original_prompt
-      - include_ai_improved_prompt
+      - include_user_original_prompt_for_technical_or_interpreted_tasks
+      - include_ai_improved_prompt_for_technical_or_interpreted_tasks
       - keep_comparison_to_minimum_viable_words
       - preserve_user_language_when_possible
     avoid:
       - hiding_interpretation_from_user
       - expanding_simple_requests_into_large_specs
+    may_omit_when:
+      - level_0
+      - no_technical_action
+      - no_scope_or_intent_interpretation
+      - direct_answer_is_clearer
 limits:
   level_0:
     max_lines: 5
@@ -75,16 +80,19 @@ delivery_rule:
     - "Feito: <what changed or answer>"
     - "Validado: <evidence or not run>"
     - "Risco: <residual risk or none>"
-  always_show:
-    - prompt_original
-    - prompt_melhorado_da_ia
+  show_when:
+    - technical_action
+    - scope_interpretation
+    - risk_level_1_or_higher
+    - prompt_improvement_changes_execution
   comparison:
     - original_prompt_must_keep_user_words_when_reasonable
     - improved_prompt_must_state_objective_scope_risk_validation
     - improved_prompt_must_fit_risk_level_limits
   token_policy:
     - use_abbreviated_labels_po_pm_when_user_did_not_request_full_form
-    - level_0_and_1_use_micro_template
+    - level_0_may_use_direct_answer_when_comparison_adds_no_value
+    - level_1_use_micro_template
     - level_2_use_compact_objective_scope_validation
     - level_3_include_risk_confirmation_without_long_spec
     - omit_tests_line_when_no_break_risk_exists