ai-execution-protocol 0.3.1 → 0.4.0

package/docs/10-economia-de-prompt.md

@@ -0,0 +1,79 @@
+# 10 - Economia de Prompt
+
+## Ideia central
+
+A IA deve melhorar o prompt do usuario, mas nao deve transformar um pedido
+curto em uma especificacao gigante sem necessidade.
+
+Prompt melhorado deve ser proporcional ao risco.
+
+## Regra pratica
+
+- Nivel 0: reescreva em uma linha curta ou repita o objetivo com mais clareza.
+- Nivel 1: no maximo uma frase de interpretacao.
+- Nivel 2: objetivo, escopo e validacao em poucas linhas.
+- Nivel 3: objetivo, risco critico, confirmacao e validacao.
+
+## O que evitar
+
+- Repetir contexto inteiro.
+- Copiar regras do protocolo no prompt.
+- Adicionar features nao solicitadas.
+- Criar checklist grande para tarefa simples.
+
+## Economia por rota
+
+Use `protocol/route-packs.yaml` depois de escolher a rota em
+`protocol/router.yaml`.
+
+O pack resume a acao minima de cada rota. Abra os YAML completos somente quando:
+
+- o risco ou escopo nao estiver claro;
+- o plano de validacao ainda nao estiver claro;
+- a tarefa for nivel 2 ou 3 e o impacto ainda nao estiver mapeado;
+- for preciso texto exato de regra ou schema.
+
+## Formato economico
+
+Mostre o prompt original e o prompt melhorado quando houver acao tecnica,
+interpretacao de escopo, risco nivel 1 ou maior, ou quando a melhoria alterar a
+execucao.
+
+Em uma resposta direta de nivel 0, sem interpretacao relevante, omita a
+comparacao quando ela custar mais do que esclarecer.
+
+Para nivel 1, use micro formato organizado:
+
+```text
+PO: [pedido do usuario em uma linha]
+PM: [pedido refinado em uma linha]
+OK:
+  Feito: [resposta ou mudanca]
+  Validado: [evidencia ou nao rodei]
+  Risco: [nenhum/baixo/restante]
+```
+
+Para nivel 2-3, use formato compacto:
+
+```text
+PO: [pedido do usuario em uma linha]
+PM: [pedido refinado em uma linha]
+Feito: [resposta ou mudanca]
+Validado: [evidencia ou nao rodei]
+Risco: [nenhum/baixo/restante]
+```
+
+Use `Testar:` somente quando houver risco de quebrar algo. Use `Confirmar:`
+somente em nivel 3 ou acao sensivel.
+
+## Economia com risco critico bloqueado
+
+Economia de prompt nao pode esconder risco.
+
+Quando um pedido tem parte nivel 3 que nao pode ser executada, mantenha essa
+parte como nivel 3 bloqueado e execute apenas subtarefas seguras com contexto
+proporcional.
+
+Isso reduz custo porque a IA nao precisa abrir contexto critico para uma acao
+que nao conseguira executar. Ao mesmo tempo, a entrega continua honesta: a parte
+sensivel fica registrada como pendente, nao como concluida.

package/docs/11-retencao-de-resultados.md

@@ -0,0 +1,26 @@
+# 11 - Retencao de Resultados
+
+## Ideia central
+
+Resultados gerados ajudam auditoria, mas podem virar custo de contexto se forem
+lidos sem necessidade.
+
+## Regras
+
+- Seguir `.aiignore` e `INDEX.yaml/read_policy.ignore_by_default`.
+- Nao ler `generated/` por padrao.
+- Ler `results/` apenas quando a tarefa envolver avaliacao ou historico.
+- Manter relatorios recentes pequenos.
+- Arquivar ou remover resultados antigos quando deixarem de ser uteis.
+- Nunca usar resultado antigo como estado atual sem verificar.
+
+## Pastas geradas
+
+- `benchmarks/generated/`
+- `model-runs/generated/`
+- `results/`
+
+## Uso esperado
+
+Use resultados para comparar, auditar e medir evolucao. Nao use como regra
+operacional principal.

package/docs/12-instalacao-em-outro-projeto.md

@@ -0,0 +1,254 @@
+# 12 - Instalacao em Outro Projeto
+
+## Ideia central
+
+Use `dist/minimal/` para aplicar o protocolo em outro projeto.
+
+## Como gerar
+
+Na raiz deste projeto:
+
+```powershell
+python scripts/build_dist.py
+```
+
+## O que copiar
+
+O instalador copia de `dist/minimal/` para a raiz do projeto alvo:
+
+- `AGENTS.md`
+- `.aiignore`
+- `canonical-state.yaml`
+- `context-map.yaml`
+- `decisions/README.md`
+- `memory/INDEX.yaml`
+- `candidate-memory/README.md`
+- `capabilities/registry.yaml`
+- `protocol/`
+
+Ele tambem inclui template interno para integracao opcional com arquivos de IDE.
+Esse template nao e aplicado sem comando explicito.
+
+## Instalacao automatica
+
+### CLI instalada
+
+Projeto novo:
+
+```powershell
+ai-protocol init C:\caminho\projeto
+```
+
+Projeto existente:
+
+```powershell
+ai-protocol install C:\caminho\projeto
+```
+
+Previa sem alterar arquivos:
+
+```powershell
+ai-protocol install C:\caminho\projeto --dry-run
+```
+
+Integracao opcional com arquivos de instrucao de IDE:
+
+```powershell
+ai-protocol integrate C:\caminho\projeto --dry-run
+ai-protocol integrate C:\caminho\projeto --yes
+```
+
+### PowerShell
+
+```powershell
+.\install.ps1 C:\caminho\projeto -Force
+```
+
+Esse comando gera `dist/minimal/`, instala o protocolo e roda a verificacao.
+O resultado esperado no final e `PASS`.
+
+### NPM
+
+Uso local, dentro deste repositorio:
+
+```powershell
+npm run install-protocol -- C:\caminho\projeto
+npm run dry-run-protocol -- C:\caminho\projeto
+```
+
+O script npm instala direto via Node. Ele existe para IDEs e projetos onde
+`npm run` e mais facil de lembrar.
+
+Uso como pacote publicado:
+
+```powershell
+npm install -g ai-execution-protocol
+ai-protocol install C:\caminho\projeto
+ai-protocol integrate C:\caminho\projeto --yes
+```
+
+Atualizar uma instalacao existente:
+
+```powershell
+npm install -g ai-execution-protocol@latest
+ai-protocol install C:\caminho\projeto
+ai-protocol integrate C:\caminho\projeto --yes
+ai-protocol verify C:\caminho\projeto
+```
+
+Para verificar manualmente via npm:
+
+```powershell
+npm run verify-protocol -- C:\caminho\projeto
+```
+
+Ou com a CLI instalada:
+
+```powershell
+ai-protocol verify C:\caminho\projeto
+```
+
+Se o terminal da IDE ja estiver aberto no projeto alvo, use o caminho completo
+do framework e `.` como alvo:
+
+```powershell
+C:\caminho\ai-research\install.ps1 . -Force
+```
+
+Ou via npm, a partir da raiz deste framework:
+
+```powershell
+npm run install-protocol -- .
+```
+
+### Python
+
+Forma equivalente via Python:
+
+```powershell
+python scripts/install_protocol.py --target C:\caminho\projeto --force
+python scripts/install_protocol.py --target C:\caminho\projeto --dry-run
+python scripts/verify_install.py --target C:\caminho\projeto
+```
+
+Uso como pacote publicado:
+
+```powershell
+pip install ai-execution-protocol
+ai-protocol install C:\caminho\projeto
+ai-protocol integrate C:\caminho\projeto --yes
+```
+
+Atualizar uma instalacao existente:
+
+```powershell
+python -m pip install --upgrade ai-execution-protocol
+ai-protocol install C:\caminho\projeto
+ai-protocol integrate C:\caminho\projeto --yes
+ai-protocol verify C:\caminho\projeto
+```
+
+Tambem funciona como modulo:
+
+```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 integrate C:\caminho\projeto --yes
+```
+
+Ou no CMD:
+
+```bat
+install.bat C:\caminho\projeto
+```
+
+## Verificacao obrigatoria
+
+```powershell
+python scripts/verify_install.py --target C:\caminho\projeto
+```
+
+O verificador deve retornar `PASS`. Se retornar `FAIL`, a IA nao deve tratar o
+protocolo como instalado corretamente.
+
+Use esta regra facil de lembrar:
+
+```text
+PowerShell = install.ps1 <projeto> -Force
+NPM local = npm run install-protocol -- <projeto>
+NPM pacote = npm install -g ai-execution-protocol; ai-protocol install <projeto>
+NPM atualizar = npm install -g ai-execution-protocol@latest; ai-protocol install <projeto>
+Python local = install_protocol.py + verify_install.py
+Python pacote = pip install ai-execution-protocol; ai-protocol install <projeto>
+Python atualizar = python -m pip install --upgrade ai-execution-protocol; ai-protocol install <projeto>
+previa = ai-protocol install <projeto> --dry-run
+integracao IDE = ai-protocol integrate <projeto> --yes
+alvo atual = use . como <projeto>
+sucesso = PASS
+```
+
+## Como usar
+
+No projeto alvo, a IA deve ler:
+
+1. `AGENTS.md`
+2. `protocol/fast-path.yaml`
+3. `protocol/router.yaml`
+
+Depois deve abrir apenas os arquivos indicados pela rota.
+
+Para tornar o protocolo obrigatorio, mantenha `AGENTS.md` na raiz do projeto
+alvo. No Codex, esse arquivo vira a instrucao principal do agente naquele
+workspace.
+
+## Convivencia com arquivos existentes
+
+O instalador preserva arquivos existentes do projeto:
+
+- se ja existir `AGENTS.md`, injeta um bloco `AI_PROTOCOL_BEGIN` no topo e
+  mantem as instrucoes antigas abaixo;
+- se ja existir `.aiignore`, adiciona apenas as entradas faltantes;
+- se `--force` substituir `protocol/`, cria backup em `.ai-protocol-backup/`;
+- nao altera `README.md`, `docs/`, `.cursorrules`, `CLAUDE.md`,
+  `.github/copilot-instructions.md` ou configuracoes de frameworks.
+
+O comando separado `ai-protocol integrate <projeto> --yes` pode alterar:
+
+- `CLAUDE.md`;
+- `.cursorrules`;
+- `.github/copilot-instructions.md`;
+- `.cursor/rules/ai-execution-protocol.mdc`.
+
+Ele usa marcadores `AI_PROTOCOL_IDE_BEGIN` e `AI_PROTOCOL_IDE_END`, cria backup
+e atualiza o mesmo bloco quando executado novamente. Sem `--yes`, apenas mostra
+o plano.
+
+Na pratica, documentos e regras do usuario continuam existindo. O protocolo nao
+vira dono desses arquivos; ele orienta a IA a le-los somente quando a rota pedir
+contexto e a nao sobrescreve-los sem pedido explicito.
+
+Quando houver conflito, a IA deve seguir esta ordem:
+
+1. pedido atual do usuario;
+2. bloco obrigatorio do protocolo em `AGENTS.md`;
+3. regras especificas da IDE, do framework ou do projeto;
+4. relatorios antigos ou arquivos gerados somente depois de verificar.
+
+Exemplos preservados: `README.md`, `docs/`, `.cursorrules`, `CLAUDE.md`,
+`.github/copilot-instructions.md`, `next.config.*`, `vite.config.*`,
+`angular.json`, `package.json`, `pyproject.toml`, `composer.json`,
+`Gemfile`, `Cargo.toml` e arquivos equivalentes de framework.
+
+## O que nao copiar
+
+Nao copie por padrao:
+
+- `docs/`
+- `cases/`
+- `eval/`
+- `results/`
+- `benchmarks/`
+- `model-runs/`
+
+Essas pastas servem para evoluir e testar o framework, nao para uso minimo.

package/docs/13-uso-em-ides.md

@@ -0,0 +1,137 @@
+# 13 - Uso em IDEs
+
+## Ideia central
+
+O protocolo deve ser facil de instalar e seguro para conviver com regras ja
+existentes da IDE ou do projeto.
+
+## Comando facil
+
+Na raiz deste framework, use sempre a mesma memoria:
+
+```powershell
+.\install.ps1 C:\caminho\projeto -Force
+```
+
+Se a IDE usa bem npm:
+
+```powershell
+npm run install-protocol -- C:\caminho\projeto
+npm run dry-run-protocol -- C:\caminho\projeto
+```
+
+Depois de publicar como pacote:
+
+```powershell
+npm install -g ai-execution-protocol
+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
+```
+
+Via Python instalado:
+
+```powershell
+pip install ai-execution-protocol
+ai-protocol install C:\caminho\projeto
+ai-protocol verify C:\caminho\projeto
+```
+
+Se o terminal da IDE ja estiver no projeto alvo:
+
+```powershell
+C:\caminho\ai-research\install.ps1 . -Force
+```
+
+No CMD:
+
+```bat
+install.bat C:\caminho\projeto
+```
+
+O `install.ps1` ja gera o pacote minimo, instala e verifica. O final esperado e
+`PASS`.
+
+O npm instala direto via Node. Ele nao muda o comportamento do protocolo e nao
+depende de PowerShell.
+
+No uso por pacote, `npm install` e `pip install` instalam a CLI. A alteracao no
+projeto so acontece quando o usuario roda `ai-protocol install <projeto>`.
+
+`ai-protocol integrate <projeto> --yes` e opcional. Ele escreve apenas blocos
+marcados em arquivos de instrucao de IDE e cria backup antes de alterar arquivo
+existente.
+
+## Comportamento por IDE
+
+- Codex: usa `AGENTS.md` como instrucao raiz do workspace.
+- Cursor: pode receber bloco marcado em `.cursorrules` e `.cursor/rules/`.
+- Claude Code: pode receber bloco marcado em `CLAUDE.md`.
+- GitHub Copilot: pode receber bloco marcado em `.github/copilot-instructions.md`.
+- Outras IDEs: o protocolo continua disponivel em `AGENTS.md` e `protocol/`.
+
+## Convivencia com arquivos do usuario
+
+O instalador nao apaga documentos do projeto por padrao.
+
+Ele faz:
+
+- injeta bloco `AI_PROTOCOL_BEGIN` em `AGENTS.md`;
+- mantem instrucoes antigas abaixo do bloco;
+- adiciona entradas faltantes em `.aiignore`;
+- copia `protocol/`;
+- cria backup antes de substituir `protocol/` com `-Force`.
+
+O comando `install` nao altera:
+
+- `README.md`;
+- `docs/`;
+- `.cursorrules`;
+- `CLAUDE.md`;
+- `.github/copilot-instructions.md`;
+- configs de Next, Vite, Django, Laravel, Rails ou outros frameworks.
+
+O comando `integrate --yes` pode alterar somente:
+
+- `CLAUDE.md`;
+- `.cursorrules`;
+- `.github/copilot-instructions.md`;
+- `.cursor/rules/ai-execution-protocol.mdc`.
+
+Cada alteracao usa marcadores `AI_PROTOCOL_IDE_BEGIN` e
+`AI_PROTOCOL_IDE_END`, entao uma nova execucao atualiza o mesmo bloco em vez de
+duplicar texto.
+
+Com documentos e frameworks do usuario, o comportamento esperado e:
+
+- preservar os arquivos existentes;
+- ler docs do projeto somente quando a rota exigir contexto;
+- tratar docs antigos, gerados ou historicos como nao confiaveis ate verificar;
+- usar configs de framework como fonte tecnica quando a tarefa tocar aquele
+  framework;
+- nao copiar regras do protocolo para varios arquivos da IDE.
+
+## Ordem de prioridade
+
+Quando houver conflito, a IA deve seguir:
+
+1. pedido atual do usuario;
+2. bloco obrigatorio em `AGENTS.md`;
+3. regras especificas da IDE ou do projeto;
+4. docs e historico somente quando a rota pedir.
+
+## Regra pratica
+
+Use um comando e confira o `PASS`.
+
+```text
+install.ps1 <projeto> -Force
+npm run install-protocol -- <projeto>
+ai-protocol install <projeto>
+ai-protocol install <projeto> --dry-run
+ai-protocol integrate <projeto> --yes
+```
+
+Se `PASS` aparecer, a IA pode tratar o protocolo como ativo naquele projeto.
+Se a IDE nao ler `AGENTS.md`, rode tambem `integrate --yes`.

package/docs/14-publicacao.md

@@ -0,0 +1,128 @@
+# 14 - Publicacao
+
+## Objetivo
+
+Preparar este framework para publicacao sem expor informacao privada e sem
+vender a ideia como pronta demais.
+
+## Posicionamento publico
+
+Use termos como:
+
+- framework experimental;
+- pesquisa em evolucao;
+- proposta tecnica;
+- protocolo conceitual;
+- metodologia para agentes de IA.
+
+Evite prometer que o protocolo elimina risco, substitui revisao humana ou
+garante seguranca. A mensagem correta e: o framework reduz risco operacional ao
+forcar contexto minimo, classificacao de risco, validacao e entrega com
+evidencia.
+
+## Arquivos recomendados para publicar
+
+Publicacao base:
+
+- `README.md`
+- `LICENSE`
+- `.gitignore`
+- `AGENTS.md`
+- `INDEX.yaml`
+- `config.yaml`
+- `docs/`
+- `protocol/`
+- `cases/`
+- `examples/`
+- `schema/`
+- `eval/`
+- `scripts/`
+- `responses/`
+- `prompts/`
+- `package.json`
+- `pyproject.toml`
+- `requirements.txt`
+- `install.ps1`
+- `install.bat`
+
+Arquivos gerados ou historicos devem ficar fora do Git quando nao forem
+necessarios para explicar o framework:
+
+- `build/`
+- `dist/`
+- `results/`
+- `benchmarks/generated/`
+- `model-runs/generated/`
+- `*.tgz`
+- `*.whl`
+- `*.tar.gz`
+- `__pycache__/`
+- `*.egg-info/`
+
+## Checklist de privacidade
+
+Antes de publicar, confira se nao existe:
+
+- `.env` ou arquivo local de configuracao;
+- senha;
+- token;
+- chave de API;
+- certificado privado;
+- dado de cliente;
+- log real;
+- print com informacao sensivel;
+- nome de projeto privado que voce nao quer expor;
+- caminho local sensivel em exemplo publico.
+
+Se algo sensivel ja entrou no historico do Git, apagar o arquivo depois pode
+nao ser suficiente. Nesse caso, trate como remocao de dado sensivel do
+historico antes de publicar.
+
+## Checklist tecnico
+
+1. Confirme que `.gitignore` cobre dependencias, builds, logs e segredos.
+2. Confirme que `README.md` explica objetivo, status, estrutura e validacao.
+3. Confirme que `LICENSE` existe.
+4. Rode a validacao geral:
+
+```powershell
+python scripts/health_check.py
+```
+
+5. Rode a bateria estrutural:
+
+```powershell
+python scripts/framework_tests.py
+```
+
+6. Procure sinais obvios de segredo antes do primeiro commit:
+
+```powershell
+rg -n -i "api[_-]?key|token|secret|senha|password|client_secret|private_key" .
+```
+
+Revise manualmente qualquer resultado. Nem todo resultado e vazamento; alguns
+podem ser apenas regras de seguranca ou exemplos.
+
+## Primeiro commit
+
+Depois de criar o repositorio no GitHub:
+
+```powershell
+git init
+git add .
+git commit -m "Initial AI execution protocol framework"
+git branch -M main
+git remote add origin https://github.com/SEU_USUARIO/NOME_DO_REPOSITORIO.git
+git push -u origin main
+```
+
+## Criterio de pronto para publicar
+
+O projeto esta pronto para publicacao inicial quando:
+
+- a proposta aparece como experimental;
+- a estrutura separa estudo (`docs/`) de operacao (`protocol/`);
+- arquivos privados e gerados estao ignorados;
+- README, licenca e indice estao consistentes;
+- validacoes locais passaram ou os limites estao documentados.