ai-execution-protocol 0.3.0 → 0.4.0

package/docs/05-validacao-e-entrega.md

@@ -0,0 +1,48 @@
+# 05 - Validacao e Entrega
+
+## Ideia central
+
+Uma entrega so fica confiavel quando existe evidencia do que foi validado e do
+que nao foi validado.
+
+## Validacao automatica
+
+Pode incluir testes, typecheck, build, lint, verificacao de links e checagem de
+diff.
+
+Selecione primeiro o menor conjunto capaz de provar o comportamento alterado.
+Amplie para a suite completa quando a mudanca atingir contrato compartilhado,
+instalacao, seguranca, varios modulos ou release.
+
+## Validacao manual
+
+Deve explicar onde testar, quais passos executar, resultado esperado e sinais de
+regressao.
+
+Quando houver chance de quebrar fluxo existente, impacto visual, dados,
+permissao, build, deploy ou integracao, a IA deve entregar uma lista objetiva do
+que testar manualmente.
+
+## Transparencia
+
+A IA nao deve dizer que algo foi testado se nao foi.
+
+## Entrega clara
+
+Quando houver interpretacao tecnica, uma boa resposta final separa:
+
+- prompt original;
+- prompt melhorado da IA;
+- o que mudou;
+- o que foi validado;
+- o que nao foi validado;
+- o que testar quando houver risco de quebra;
+- risco residual;
+- resumo em linguagem simples;
+- proximo passo apenas quando necessario.
+
+Por padrao, use uma linha por item. Cresca o formato somente quando risco,
+validacao ou explicacao exigirem.
+
+Uma resposta direta de nivel 0 pode omitir a comparacao de prompt quando nao
+houver interpretacao de escopo.

package/docs/06-memoria-e-continuidade.md

@@ -0,0 +1,27 @@
+# 06 - Memoria e Continuidade
+
+## Ideia central
+
+Memoria ajuda a preservar decisoes, mas deve ser curta e seletiva.
+
+## Registrar
+
+- decisao estavel;
+- regra recorrente;
+- problema conhecido;
+- checkpoint para retomada;
+- comando ou validacao importante.
+
+## Nao registrar
+
+- logs longos;
+- detalhes temporarios;
+- historico sem utilidade futura;
+- conclusoes sem evidencia;
+- informacao especifica demais.
+
+## Retomada
+
+Quando for melhor abrir nova conversa, deixar resumo com objetivo, ultimo corte,
+areas relevantes, validacoes feitas, pendencias e proximo passo.
+

package/docs/07-legibilidade-para-ia.md

@@ -0,0 +1,47 @@
+# 07 - Legibilidade Para IA
+
+## Ideia central
+
+Os arquivos devem ser organizados para a IA ler e aplicar com o minimo de
+ambiguidade.
+
+## Regras
+
+- Um assunto principal por arquivo.
+- Um arquivo deve representar um assunto rastreavel, nao apenas ser curto.
+- Titulos diretos e previsiveis.
+- Listas curtas e objetivas.
+- Regras antes de exemplos.
+- Termos consistentes.
+- Separar teoria, criterio, template e exemplo.
+- Evitar texto decorativo.
+- Evitar paragrafos longos escondendo decisao importante.
+- Evitar nomes genericos como `geral.md`, `notas.md` ou `parte-1.md`.
+
+## Documentacao atomica
+
+Use arquivos por dominio, fluxo, decisao, componente ou integracao.
+
+O nome do arquivo deve conter termos que a IA provavelmente buscaria. Depois de
+abrir a doc certa, use `rg` para encontrar simbolos e trechos no codigo.
+
+Regra curta:
+
+```text
+Doc atomica localiza.
+rg encontra.
+Codigo verificado decide.
+```
+
+## Formato preferido
+
+1. Ideia central.
+2. Quando usar.
+3. Regras.
+4. Criterios.
+5. Excecoes.
+6. Exemplos.
+7. Validacao ou entrega esperada.
+
+Nem todo arquivo precisa ter todas as secoes. O importante e manter ordem
+previsivel.

package/docs/08-posicionamento.md

@@ -0,0 +1,48 @@
+# 08 - Posicionamento
+
+## O que e
+
+Um framework para orientar IA em tarefas tecnicas com risco controlado,
+contexto minimo, validacao e entrega com evidencia.
+
+## Para quem e
+
+- Agentes de codigo.
+- Assistentes em IDE.
+- Times que usam IA para desenvolvimento.
+- Pessoas que querem reduzir erro, retrabalho e custo de contexto.
+
+## Problema que resolve
+
+IA tecnica costuma errar quando age rapido demais, le contexto demais ou trata
+tarefa critica como simples.
+
+O framework cria um processo para a IA decidir antes de agir.
+
+## O que nao tenta resolver
+
+- Nao substitui testes reais.
+- Nao substitui revisao humana em tarefa critica.
+- Nao garante que a IA sempre esteja certa.
+- Nao elimina necessidade de entender o projeto.
+
+## Promessa
+
+Reduzir erro operacional e custo de contexto ao fazer a IA:
+
+- classificar risco;
+- abrir menos arquivos;
+- mapear impacto quando necessario;
+- pedir confirmacao em tarefa critica;
+- validar antes de entregar;
+- explicar limites e risco residual.
+
+## Como medir sucesso
+
+- Menos arquivos lidos por tarefa.
+- Menos tokens por rota.
+- Mais tarefas com risco classificado corretamente.
+- Menos acoes sensiveis sem confirmacao.
+- Mais entregas com validacao clara.
+- Menos regressao por mudanca fora de escopo.
+

package/docs/09-governanca-de-mudancas.md

@@ -0,0 +1,48 @@
+# 09 - Governanca de Mudancas
+
+## Ideia central
+
+O protocolo deve evoluir sem perder clareza, economia e confiabilidade.
+
+## Quando mudar uma regra
+
+Mude uma regra quando houver:
+
+- falha repetida em caso real;
+- ambiguidade detectada por teste;
+- custo alto de contexto;
+- duplicacao clara;
+- nova categoria de risco.
+
+## Antes de mudar
+
+- Identifique o arquivo certo.
+- Verifique se a mudanca afeta `protocol/`, `cases/`, `eval/` ou `scripts/`.
+- Evite duplicar regra existente.
+- Mantenha o arquivo abaixo de 400 linhas.
+
+## Depois de mudar
+
+- Atualize indice relacionado.
+- Se criar ou dividir docs, atualize `docs/README.md`, `INDEX.yaml` ou
+  `context-map.yaml` quando relevante.
+- Verifique se a mudanca criou duplicidade entre assuntos.
+- Atualize `CHANGELOG.md`.
+- Rode `scripts/health_check.py`.
+- Se mudar `protocol/`, rode `scripts/build_dist.py`.
+- Se mudar avaliacao, rode benchmarks.
+
+## Regra de economia
+
+Toda mudanca deve reduzir ambiguidade sem aumentar contexto desnecessario.
+
+## Regra para docs novas
+
+Antes de criar uma doc nova, procure se o assunto ja existe:
+
+```powershell
+rg -n "termo-do-assunto|alias|simbolo" docs context-map.yaml INDEX.yaml
+```
+
+Se existir, atualize a doc existente. Se nao existir e o assunto tiver valor
+proprio, crie uma doc atomica com nome buscavel.

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.