ai-execution-protocol 0.1.0

package/protocol/router.yaml

@@ -0,0 +1,100 @@
+id: protocol_router
+type: read_router
+version: 0.1
+purpose: choose_minimum_protocol_files_by_task
+default_read:
+  - fast-path.yaml
+  - modes.yaml
+routes:
+  simple_answer:
+    risk: 0
+    read:
+      - fast-path.yaml
+  small_fix:
+    risk: 1
+    read:
+      - fast-path.yaml
+      - validation-checklist.yaml
+  user_flow_bug:
+    risk: 2
+    read:
+      - fast-path.yaml
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+  refactor:
+    risk: 2
+    read:
+      - fast-path.yaml
+      - context-compiler.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+      - spec-driven.yaml
+  feature_or_spec:
+    risk: 2
+    read:
+      - fast-path.yaml
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+      - spec-driven.yaml
+  docs_update:
+    risk: 1
+    read:
+      - fast-path.yaml
+      - context-rules.yaml
+      - formatting-rules.yaml
+  database_or_data:
+    risk: 3
+    read:
+      - fast-path.yaml
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+      - spec-driven.yaml
+  auth_security_secret:
+    risk: 3
+    read:
+      - fast-path.yaml
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+      - spec-driven.yaml
+  deploy_or_production:
+    risk: 3
+    read:
+      - fast-path.yaml
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - validation-checklist.yaml
+      - context-rules.yaml
+      - spec-driven.yaml
+  evaluate_response:
+    read:
+      - fast-path.yaml
+      - ../eval/rubric.yaml
+      - ../schema/evaluated-response.schema.json
+  create_or_edit_yaml:
+    read:
+      - fast-path.yaml
+      - formatting-rules.yaml
+      - ../schema/protocol-rule.schema.yaml
+  prompt_improvement:
+    read:
+      - fast-path.yaml
+      - prompt-economy.yaml
+  context_optimization:
+    read:
+      - fast-path.yaml
+      - context-rules.yaml
+      - context-compiler.yaml
+rules:
+  - start_with_default_read
+  - choose_one_route_if_task_type_is_clear
+  - 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/spec-driven.yaml

@@ -0,0 +1,53 @@
+id: spec_driven
+type: operational_rules
+version: 0.1
+purpose: use_spec_driven_only_when_it_improves_safety_or_clarity
+principle: protocol_is_base_spec_is_tool
+when_to_use:
+  - feature_with_multiple_steps
+  - unclear_scope_with_real_implementation
+  - level_2_change_with_cross_file_impact
+  - level_3_change_before_sensitive_action
+  - user_requests_spec_or_roadmap
+when_not_to_use:
+  - simple_answer
+  - tiny_reversible_fix
+  - clear_low_risk_change
+  - user_only_wants_quick_explanation
+spec_levels:
+  light_spec:
+    use_when:
+      - level_1_or_2
+      - small_feature_or_bug
+    max_lines: 12
+    fields:
+      - objective
+      - scope
+      - affected_area
+      - validation
+  full_spec:
+    use_when:
+      - level_2_large
+      - level_3
+      - multi_module_change
+    max_lines: 40
+    fields:
+      - objective
+      - non_goals
+      - assumptions
+      - affected_area
+      - risk
+      - implementation_steps
+      - validation
+      - rollback_or_recovery
+rules:
+  - keep_spec_shorter_than_context_it_saves
+  - do_not_create_spec_for_low_value_tasks
+  - use_spec_to_reduce_ambiguity_not_to_delay_execution
+  - after_spec_execute_with_fast_path_router_and_validation
+  - update_spec_only_when_scope_changes
+delivery:
+  include:
+    - spec_used_or_skipped
+    - reason
+    - validation_result

package/protocol/validation-checklist.yaml

@@ -0,0 +1,59 @@
+id: validation_checklist
+type: checklist
+version: 0.1
+automatic_validation:
+  - unit_tests
+  - integration_tests
+  - typecheck
+  - build
+  - lint
+  - link_check
+  - diff_check
+manual_validation:
+  fields:
+    - where_to_test
+    - steps
+    - expected_result
+    - regression_signals
+  required_when:
+    - user_visible_impact
+    - regression_risk
+    - could_break_existing_flow
+    - validation_not_fully_automated
+delivery:
+  default_style: micro_when_low_risk
+  required_fields:
+    - prompt_original
+    - prompt_melhorado_da_ia
+    - changed
+    - validated
+    - residual_risk
+    - plain_language_summary
+  conditional_fields:
+    - not_validated_when_any_expected_validation_was_not_run
+    - tests_to_run_when_break_risk_exists
+  optional_fields:
+    - next_step
+rules:
+  - id: VAL_001
+    never: claim_tested_if_not_tested
+  - id: VAL_002
+    if_validation_not_possible:
+      - record_reason
+      - indicate_expected_test
+  - id: VAL_003
+    when:
+      any:
+        - could_break_existing_flow
+        - regression_risk
+        - user_visible_impact
+    do:
+      - provide_manual_test_list
+      - include_where_to_test_steps_expected_result
+  - id: VAL_004
+    always:
+      - explain_changes_in_plain_language
+      - avoid_unexplained_jargon
+      - make_limits_and_residual_risk_understandable
+      - prefer_one_line_per_delivery_field
+      - use_micro_format_only_when_readable

package/scripts/README.md

@@ -0,0 +1,222 @@
+# Scripts
+
+Esta pasta guarda automacoes simples do framework.
+
+## eval_runner.py
+
+Avalia uma resposta YAML contra um caso YAML.
+
+Exemplo:
+
+```powershell
+python scripts/eval_runner.py --case cases/03-bug-medio.yaml --response responses/sample-response.yaml --out results/sample-run.yaml
+```
+
+O runner nao chama IA. Ele compara uma resposta estruturada com o caso e gera um
+resultado em `results/`.
+
+## response_parser.py
+
+Converte uma resposta em texto livre para `evaluated_response` YAML.
+
+Exemplo:
+
+```powershell
+python scripts/response_parser.py --case cases/03-bug-medio.yaml --text responses/natural-sample.txt --out responses/parsed-sample.yaml
+```
+
+Depois rode o avaliador:
+
+```powershell
+python scripts/eval_runner.py --case cases/03-bug-medio.yaml --response responses/parsed-sample.yaml --out results/parsed-sample-run.yaml
+```
+
+## token_report.py
+
+Estima custo de leitura das rotas em `protocol/router.yaml`.
+
+Exemplo:
+
+```powershell
+python scripts/token_report.py --out results/token-report.yaml
+```
+
+Para medir uma rota especifica:
+
+```powershell
+python scripts/token_report.py --route user_flow_bug --out results/token-user-flow-bug.yaml
+```
+
+## health_check.py
+
+Roda a validacao geral do framework.
+
+Verifica:
+
+- arquivos com no maximo 400 linhas;
+- ASCII;
+- links Markdown;
+- campos obrigatorios dos casos;
+- JSON valido nos schemas;
+- parser, runner, token report e custo de prompt.
+
+Exemplo:
+
+```powershell
+python scripts/health_check.py
+```
+
+## benchmark_runner.py
+
+Executa a suite em `benchmarks/benchmark-suite.yaml` e compara respostas sem
+protocolo contra respostas com protocolo.
+
+Exemplo:
+
+```powershell
+python scripts/benchmark_runner.py --out benchmarks/generated/report.yaml
+```
+
+## model_runs_runner.py
+
+Avalia respostas reais salvas em `model-runs/<modelo>/*.txt`.
+
+Exemplo:
+
+```powershell
+python scripts/model_runs_runner.py
+```
+
+O relatorio fica em `model-runs/generated/report.yaml`.
+
+## framework_tests.py
+
+Roda testes extras de estrutura, rotas, parser, token report, pacote minimo e
+model-runs.
+
+Exemplo:
+
+```powershell
+python scripts/framework_tests.py
+```
+
+O relatorio fica em `results/framework-test-report.yaml`.
+
+## build_dist.py
+
+Gera `dist/minimal/` a partir de `AGENTS.md` minimo e `protocol/`.
+
+Exemplo:
+
+```powershell
+python scripts/build_dist.py
+```
+
+## install_protocol.py
+
+Instala o pacote minimo em outro projeto.
+
+Exemplo:
+
+```powershell
+python scripts/install_protocol.py --target C:\caminho\projeto --force
+```
+
+Atalho:
+
+```powershell
+.\install.ps1 C:\caminho\projeto -Force
+```
+
+Atalho via npm:
+
+```powershell
+npm run init-protocol -- C:\caminho\projeto
+npm run install-protocol -- C:\caminho\projeto
+npm run dry-run-protocol -- C:\caminho\projeto
+```
+
+Quando publicado como pacote npm:
+
+```powershell
+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
+```
+
+## npm_install_protocol.js
+
+Wrapper de conveniencia para chamar `install.ps1` via `npm run`.
+
+Exemplo:
+
+```powershell
+npm run install-protocol -- C:\caminho\projeto
+npm run dry-run-protocol -- C:\caminho\projeto
+```
+
+Para conferir manualmente pelo mesmo wrapper:
+
+```powershell
+npm run verify-protocol -- C:\caminho\projeto
+```
+
+## ai_execution_protocol
+
+Pacote Python com CLI propria e arquivos YAML embutidos.
+
+Uso local:
+
+```powershell
+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 verify C:\caminho\projeto
+```
+
+Quando publicado como pacote Python:
+
+```powershell
+pip install ai-execution-protocol
+ai-protocol install C:\caminho\projeto
+```
+
+## verify_install.py
+
+Verifica se o protocolo obrigatorio esta instalado no projeto alvo.
+
+Exemplo:
+
+```powershell
+python scripts/verify_install.py --target C:\caminho\projeto
+```
+
+## validate_schema.py
+
+Valida YAML com JSON Schema quando as dependencias opcionais estao instaladas.
+
+Instalacao:
+
+```powershell
+pip install -r requirements.txt
+```
+
+Execucao:
+
+```powershell
+python scripts/validate_schema.py
+```
+
+## prompt_cost.py
+
+Mede se o prompt melhorado ficou economico para o nivel de risco.
+
+O calculo valida limite de linhas, limite de tokens estimados e proporcao de
+expansao entre prompt original e prompt melhorado.
+
+Exemplo:
+
+```powershell
+python scripts/prompt_cost.py --original prompts/original-sample.txt --improved prompts/improved-sample.txt --level 2
+```

package/scripts/build_dist.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""Build the minimal distributable package from source files."""
+
+from __future__ import annotations
+
+import shutil
+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",
+    "modes.yaml",
+    "execution-rules.yaml",
+    "risk-levels.yaml",
+    "mapping-checklists.yaml",
+    "validation-checklist.yaml",
+    "context-rules.yaml",
+    "context-compiler.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. Arquivo YAML especifico em `protocol/` conforme a rota.
+
+## Regras de execucao
+
+- Classifique o risco antes de agir.
+- Use o menor contexto suficiente.
+- Leia apenas os arquivos indicados por `protocol/router.yaml`.
+- 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 -->
+"""
+
+
+MINIMAL_README = """# Minimal AI Protocol
+
+Pacote minimo para aplicar o protocolo em outro projeto.
+
+Copie estes itens para a raiz do projeto alvo:
+
+- `AGENTS.md`
+- `.aiignore`
+- `protocol/`
+
+Use `AGENTS.md` como instrucao principal do agente.
+
+Para instalar automaticamente:
+
+```powershell
+python scripts/install_protocol.py --target C:\\caminho\\projeto --force
+```
+
+Comando unico facil de lembrar dentro deste repositorio:
+
+```powershell
+.\\install.ps1 C:\\caminho\\projeto -Force
+```
+
+Atalho via npm:
+
+```powershell
+npm run install-protocol -- C:\\caminho\\projeto
+```
+
+Como pacote npm publicado:
+
+```powershell
+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
+```
+
+Como pacote Python publicado:
+
+```powershell
+pip install ai-execution-protocol
+ai-protocol install C:\\caminho\\projeto
+ai-protocol verify C:\\caminho\\projeto
+```
+
+Se o terminal ja estiver no projeto alvo:
+
+```powershell
+C:\\caminho\\ai-research\\install.ps1 . -Force
+```
+
+No CMD:
+
+```bat
+install.bat C:\\caminho\\projeto
+```
+
+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
+"""
+
+
+def main() -> int:
+    if DIST.exists():
+        shutil.rmtree(DIST)
+    (DIST / "protocol").mkdir(parents=True, exist_ok=True)
+    if PYTHON_PACKAGE_PROTOCOL.exists():
+        shutil.rmtree(PYTHON_PACKAGE_PROTOCOL)
+    PYTHON_PACKAGE_PROTOCOL.mkdir(parents=True, exist_ok=True)
+
+    (DIST / "AGENTS.md").write_text(MINIMAL_AGENTS, encoding="utf-8")
+    (DIST / "README.md").write_text(MINIMAL_README, encoding="utf-8")
+    (DIST / ".aiignore").write_text(MINIMAL_AIIGNORE, encoding="utf-8")
+    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")
+
+    print(f"built {DIST}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/install_protocol.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+"""Install the minimal AI protocol into another project."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from ai_execution_protocol.cli import install
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--target", default=".", help="Project root to install into")
+    parser.add_argument("--force", action="store_true", help="Replace existing protocol folder")
+    parser.add_argument("--dry-run", action="store_true", help="Show planned changes without writing files")
+    args = parser.parse_args()
+
+    return install(args.target, force=args.force, dry_run=args.dry_run)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())