ai-execution-protocol 0.2.0 → 0.3.0

package/dist/minimal/protocol/formatting-rules.yaml

@@ -6,6 +6,7 @@ priority:
   second: human_readability
 principles:
   - one_main_subject_per_file
+  - atomic_docs_by_trackable_subject
   - stable_keys
   - direct_names
   - short_lists
@@ -73,3 +74,29 @@ maintenance:
   if_near_limit:
     - split_by_theme
     - update_readme
+atomic_documentation:
+  principle: one_file_one_trackable_subject
+  use_for:
+    - domain
+    - flow
+    - decision
+    - component
+    - integration
+    - validation_area
+  naming:
+    do:
+      - include_search_terms_in_filename
+      - prefer_domain_flow_or_component_names
+      - keep_titles_matching_filename_subject
+    avoid:
+      - generic_names_like_general_notes_part1
+      - duplicate_files_for_same_subject
+      - oversized_docs_with_multiple_unrelated_subjects
+  split_when:
+    - file_has_multiple_independent_subjects
+    - file_nears_line_limit
+    - rg_search_would_match_unrelated_sections
+  update_when_split:
+    - docs_readme
+    - index_or_context_map_when_relevant
+    - aliases_when_subject_terms_change

package/dist/minimal/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,7 +30,9 @@ progressive_retrieval:
     - match_domain_or_alias_in_context_map
     - read_canonical_state_when_project_truth_matters
     - read_active_decisions_for_domain
-    - read_only_needed_domain_docs
+    - 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
     - read_direct_dependencies_when_needed
@@ -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,4 +107,33 @@ 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:
+  order:
+    - identify_subject_terms_from_request
+    - find_subject_doc_by_context_map_index_or_rg
+    - read_subject_doc_before_broad_doc
+    - use_rg_for_exact_code_symbol_or_term
+    - read_code_snippet_first
+    - expand_to_full_file_or_related_doc_when_needed
+  failure_mitigations:
+    fragmentation:
+      - do_not_create_doc_for_micro_detail_without_standalone_subject
+      - merge_or_link_overlapping_docs
+    bad_names:
+      - include_domain_flow_component_or_symbol_terms_in_filename
+    duplicates:
+      - search_existing_docs_before_creating_new_doc
+      - prefer_updating_existing_subject_doc
+    stale_docs:
+      - verify_current_code_before_behavior_claim
+      - report_stale_doc_risk
+    wrong_search_terms:
+      - use_aliases_and_synonyms_as_search_terms
+      - search_docs_and_code_with_rg
+    insufficient_snippet:
+      - expand_to_imports_types_callers_or_full_file

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

@@ -0,0 +1,184 @@
+id: route_packs
+type: route_summary_index
+version: 0.3
+purpose: compact_first_read_before_full_route_files
+principle: read_pack_first_expand_only_when_needed
+use:
+  - after_router_selects_route
+  - before_opening_all_route_files
+  - when_task_is_clear_enough_for_compact_rules
+expand_when:
+  - risk_or_scope_is_unclear
+  - validation_plan_is_not_clear
+  - route_pack_conflicts_with_user_request
+  - task_is_level_2_or_3_and_impact_is_not_mapped
+  - yaml_schema_or_exact_rule_text_is_needed
+packs:
+  simple_answer:
+    risk: 0
+    read_if_pack_insufficient:
+      - fast-path.yaml
+    do:
+      - answer_directly
+      - avoid_plan_or_file_reads
+      - keep_po_pm_ok_short_when_required
+  small_fix:
+    risk: 1
+    read_if_pack_insufficient:
+      - fast-path.yaml
+      - validation-checklist.yaml
+    do:
+      - identify_small_reversible_target
+      - read_focused_context
+      - change_minimum_needed
+      - validate_directly
+  user_flow_bug:
+    risk: 2
+    read_if_pack_insufficient:
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+    do:
+      - map_flow_candidate_files_and_regression_risk
+      - read_snippets_before_full_files
+      - preserve_expected_behavior
+      - validate_main_success_and_failure_paths
+  refactor:
+    risk: 2
+    read_if_pack_insufficient:
+      - context-compiler.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+      - spec-driven.yaml
+    do:
+      - define_behavior_to_preserve
+      - keep_scope_incremental
+      - avoid_new_features
+      - validate_behavior_after_change
+  feature_or_spec:
+    risk: 2
+    read_if_pack_insufficient:
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+      - spec-driven.yaml
+    do:
+      - use_light_spec_when_scope_or_risk_benefits
+      - define_objective_scope_validation
+      - implement_incrementally
+      - avoid_full_spec_for_small_clear_tasks
+  docs_update:
+    risk: 1
+    read_if_pack_insufficient:
+      - context-rules.yaml
+      - formatting-rules.yaml
+    do:
+      - update_only_affected_docs
+      - keep_docs_atomic_by_subject
+      - verify_links_or_references
+      - update_index_when_structure_changes
+  database_or_data:
+    risk: 3
+    read_if_pack_insufficient:
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+      - spec-driven.yaml
+    do:
+      - map_affected_data
+      - avoid_destructive_action_without_confirmation
+      - define_backup_or_rollback
+      - validate_before_and_after
+  auth_security_secret:
+    risk: 3
+    read_if_pack_insufficient:
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+      - spec-driven.yaml
+    do:
+      - map_security_surface
+      - avoid_exposing_secrets
+      - require_confirmation_for_sensitive_write
+      - validate_allowed_and_denied_paths
+  deploy_or_production:
+    risk: 3
+    read_if_pack_insufficient:
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - validation-checklist.yaml
+      - context-rules.yaml
+      - spec-driven.yaml
+    do:
+      - verify_local_state
+      - run_pre_deploy_validation
+      - require_confirmation_before_deploy
+      - run_post_deploy_check_if_executed
+  evaluate_response:
+    read_if_pack_insufficient:
+      - ../eval/rubric.yaml
+      - ../schema/evaluated-response.schema.json
+    do:
+      - score_risk_behavior_avoidance_delivery_clarity
+      - apply_automatic_fail_rules
+  create_or_edit_yaml:
+    read_if_pack_insufficient:
+      - formatting-rules.yaml
+      - ../schema/protocol-rule.schema.yaml
+    do:
+      - keep_yaml_compact
+      - validate_schema_when_available
+      - update_index_when_new_file_is_added
+  prompt_improvement:
+    read_if_pack_insufficient:
+      - prompt-economy.yaml
+    do:
+      - preserve_user_intent
+      - improve_only_as_much_as_needed
+      - keep_prompt_proportional_to_risk
+      - avoid_long_specs_for_simple_tasks
+  context_optimization:
+    read_if_pack_insufficient:
+      - persistent-context.yaml
+      - context-rules.yaml
+      - context-compiler.yaml
+    do:
+      - use_context_map_and_aliases_as_pointers
+      - 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,9 +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.0",
+  "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.0
+protocol_version: 0.3.0
 purpose: ai_operational_rules
 source_docs: ../docs
 constraints:
@@ -13,6 +13,8 @@ files:
     purpose: minimum_rules_to_start_any_task
   - path: router.yaml
     purpose: choose_minimum_files_to_read_by_task
+  - path: route-packs.yaml
+    purpose: compact_first_read_before_full_route_files
   - path: modes.yaml
     purpose: choose_fast_balanced_or_strict_behavior
   - path: execution-rules.yaml
@@ -23,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