ai-execution-protocol 0.3.0 → 0.4.0

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.

package/docs/15-contexto-persistente.md

@@ -0,0 +1,204 @@
+# 15 - Contexto Persistente
+
+## Ideia central
+
+A conversa e uma interface temporaria. A memoria real do projeto deve ficar em
+artefatos pequenos, navegaveis e verificaveis.
+
+O objetivo nao e carregar mais contexto. O objetivo e encontrar o menor contexto
+correto para a tarefa atual.
+
+Meta economica: reduzir contexto desnecessario em ate 90% quando for seguro.
+Essa meta nao autoriza cortar contexto que seja necessario para entender risco,
+dependencias, imports, tipos, efeitos laterais ou validacao.
+
+## Camada segura atual
+
+Use:
+
+- `canonical-state.yaml`: estado atual resumido do projeto.
+- `context-map.yaml`: mapa pequeno de dominios, aliases e arquivos candidatos.
+- `decisions/`: decisoes importantes com status.
+- `protocol/persistent-context.yaml`: regras de recuperacao progressiva.
+- `memory/INDEX.yaml`: indice de assuntos persistentes.
+- `protocol/adaptive-memory.yaml`: promocao, conflito e seguranca da memoria.
+- `protocol/context-budget.yaml`: limite inicial e expansao justificada.
+- `protocol/capability-router.yaml`: selecao minima de skills, MCPs e
+  ferramentas quando a tarefa exigir uma capacidade externa.
+- `behavior/contract.yaml`: contrato observavel para medir se a IA seguiu o
+  framework sem exagerar tarefa simples nem subcontrolar tarefa critica.
+
+Os scripts `memory_manager.py` e `context_package.py` automatizam a manutencao
+minima e a compilacao auditavel. Eles nao transformam memoria em autoridade.
+
+## Memoria autonoma
+
+A meta de longo prazo e gerar a memoria a partir do proprio projeto:
+
+- codigo-fonte;
+- estrutura de diretorios;
+- dependencias;
+- testes;
+- configuracoes;
+- documentacao existente;
+- decisoes registradas;
+- alteracoes em Git.
+
+Isso reduz manutencao manual e evita mapas desatualizados. Porem, so deve virar
+regra obrigatoria quando houver indexador real, saida reproduzivel, deteccao de
+obsolescencia e validacao em projetos reais.
+
+## Aliases
+
+Aliases sao atalhos de navegacao.
+
+Eles ajudam a IA a encontrar dominio, documento, simbolo ou arquivo candidato,
+mas nao provam comportamento atual.
+
+Exemplo:
+
+```yaml
+aliases:
+  - auth
+  - login
+  - token
+```
+
+Esses aliases podem apontar a IA para arquivos e docs de autenticacao. Mesmo
+assim, antes de alterar codigo, a IA deve verificar o arquivo ou trecho atual.
+
+## Recuperacao progressiva
+
+Fluxo recomendado:
+
+1. Identificar objetivo.
+2. Procurar dominio ou alias em `context-map.yaml`.
+3. Ler `canonical-state.yaml` quando a verdade atual do projeto importar.
+4. Ler decisoes ativas do dominio.
+5. Abrir apenas a documentacao minima do dominio.
+6. Buscar simbolos ou arquivos candidatos.
+7. Ler trecho relevante primeiro.
+8. Abrir dependencias diretas quando necessario.
+9. Abrir arquivo inteiro quando o trecho nao for suficiente.
+
+## Validadores
+
+O Context Validator verifica se o contexto carregado basta para agir:
+
+- objetivo entendido;
+- decisoes ativas consultadas quando relevantes;
+- dependencias diretas carregadas quando necessarias;
+- risco de dominio adjacente avaliado;
+- conflito entre docs e arquivos verificados identificado.
+
+O Action Validator verifica se a intencao do usuario permite acao:
+
+- alvo identificado;
+- resultado esperado claro;
+- impacto mapeado quando o risco exigir;
+- plano de validacao existente.
+
+Regra principal:
+
+```text
+A IA pode expandir contexto.
+A IA nao pode expandir escopo.
+```
+
+Se a intencao for ambigua, a IA deve perguntar antes de editar.
+
+## Confianca
+
+Use confianca como gatilho de recuperacao:
+
+- alta: executar com contexto atual e validar;
+- media: expandir um nivel de recuperacao;
+- baixa: pedir esclarecimento.
+
+A confianca nao precisa ser um numero exato no MVP. Ela pode ser uma decisao
+operacional baseada em evidencias carregadas, lacunas conhecidas e risco.
+
+## Leitura por trecho
+
+Ler por trecho e economico quando o simbolo e claro.
+
+Mas nao e seguro editar baseado apenas em trecho isolado quando imports, tipos,
+estado compartilhado, efeitos laterais ou chamadas externas podem mudar o
+comportamento.
+
+Regra pratica:
+
+```text
+Trecho primeiro. Arquivo inteiro quando o trecho nao basta.
+```
+
+## Quando expandir contexto
+
+Expanda um nivel quando:
+
+- imports ou tipos mudam o significado do trecho;
+- estado compartilhado ou efeito lateral pode alterar o comportamento;
+- dependencia direta participa da validacao;
+- dominio adjacente pode ser afetado;
+- risco sobe para nivel 2 ou 3;
+- o alvo da alteracao ainda nao esta claro;
+- a validacao nao pode ser planejada com o contexto atual.
+
+Pare de expandir quando:
+
+- o objetivo esta claro;
+- o dominio e os arquivos candidatos estao mapeados;
+- a intencao do usuario nao esta ambigua;
+- o plano de validacao esta claro;
+- nao ha risco conhecido exigindo mais contexto.
+
+## Documentacao por assunto
+
+A recuperacao progressiva funciona melhor quando a documentacao e atomica:
+
+```text
+um arquivo = um assunto rastreavel
+```
+
+Exemplo: prefira `docs/auth-login.md` e `docs/auth-jwt.md` a um arquivo grande
+`docs/backend.md`.
+
+Depois de abrir a doc correta, use `rg` para encontrar o simbolo ou termo exato
+no codigo. A doc localiza; o codigo verificado decide.
+
+## Exemplo resumido
+
+Pedido:
+
+```text
+Altere a regra de login para bloquear usuarios inativos.
+```
+
+Aplicacao:
+
+1. Identificar intencao: regra de autenticacao.
+2. Consultar `context-map.yaml` para localizar dominio, aliases e candidatos.
+3. Ler `canonical-state.yaml` se a estrategia de auth importar.
+4. Ler decisoes ativas de autenticacao se existirem.
+5. Abrir doc minima do dominio.
+6. Buscar simbolos como `login`, `validateUser` e `AuthService`.
+7. Ler trecho primeiro.
+8. Expandir para dependencias se status de usuario vier de outro modulo.
+9. Validar caminho permitido e caminho bloqueado.
+
+Se o pedido fosse apenas "troque esse botao", o Action Validator deve pedir
+esclarecimento antes de alterar qualquer coisa.
+
+## O que fica experimental
+
+Ainda nao torne obrigatorio:
+
+- catalogo completo de simbolos;
+- grafo global de dependencias;
+- cache semantico manual;
+- detector automatico de documentacao obsoleta.
+- indexador automatico continuo;
+- previsao semantica avancada do proximo objetivo.
+
+Essas ideias sao boas, mas devem ser geradas ou verificadas por tooling para nao
+virarem mapa manual desatualizado.

package/docs/16-release-e-atualizacao.md

@@ -0,0 +1,146 @@
+# 16 - Release e Atualizacao
+
+## Objetivo
+
+Publicar uma nova versao do framework em todos os canais sem quebrar o historico
+e sem expor credenciais.
+
+Use este fluxo para qualquer nova release do framework.
+
+## Canais
+
+- GitHub: codigo, tag e release.
+- npm: pacote Node com comando `ai-protocol`.
+- PyPI: pacote Python com comando `ai-protocol`.
+
+## Antes de subir
+
+Confirme:
+
+- `package.json` esta com a nova versao.
+- `pyproject.toml` esta com a nova versao.
+- `config.yaml` e `INDEX.yaml` apontam para a versao do protocolo correta.
+- `CHANGELOG.md` tem a entrada da versao.
+- `README.md` explica a mudanca principal.
+- `docs/README.md` lista novos documentos.
+- `protocol/README.yaml` lista novos arquivos operacionais.
+- `capabilities/registry.yaml` lista capacidades do pacote minimo quando
+  aplicavel.
+- `ai_execution_protocol/protocol/` esta sincronizado com `protocol/`.
+- Instaladores e verificadores conhecem novos arquivos obrigatorios.
+
+## Validacao obrigatoria
+
+Rode:
+
+```powershell
+python scripts/build_dist.py
+python scripts/framework_tests.py
+python scripts/validate_schema.py --strict
+python scripts/health_check.py
+```
+
+Valide os pacotes sem publicar:
+
+```powershell
+npm publish --dry-run
+if (Test-Path publish-dist) { Remove-Item -LiteralPath publish-dist -Recurse -Force }
+python -m build --outdir publish-dist
+python -m twine check publish-dist\*
+```
+
+Procure sinais obvios de segredo:
+
+```powershell
+rg -n -i "api[_-]?key\s*[:=]|token\s*[:=]|secret\s*[:=]|senha\s*[:=]|password\s*[:=]|client_secret\s*[:=]|private_key\s*[:=]|-----BEGIN .*PRIVATE KEY" --glob "!results/**" --glob "!build/**" --glob "!dist/**" --glob "!publish-dist/**" --glob "!*.egg-info/**" --glob "!model-runs/generated/**" --glob "!benchmarks/generated/**" --glob "!*.tgz" .
+```
+
+Revise manualmente qualquer resultado. Termos como `token_policy` ou
+`auth_security_secret` podem ser apenas nomes de regras.
+
+## GitHub
+
+Depois de validar:
+
+```powershell
+git status -sb
+git add .
+git commit -m "Release vX.Y.Z"
+git tag -a vX.Y.Z -m "Release vX.Y.Z"
+git push origin main
+git push origin vX.Y.Z
+```
+
+Crie a release:
+
+```powershell
+C:\Projetos\.tools\gh\gh.exe release create vX.Y.Z publish-dist\ai_execution_protocol-X.Y.Z-py3-none-any.whl publish-dist\ai_execution_protocol-X.Y.Z.tar.gz --repo rodneigk2/ai-execution-protocol --title "Release vX.Y.Z" --notes-file RELEASE_NOTES.md
+```
+
+Use notas curtas com:
+
+- o que mudou;
+- impacto para usuarios;
+- validacoes executadas;
+- limites conhecidos.
+
+## npm
+
+Nunca publique a mesma versao duas vezes. Se `X.Y.Z` ja foi publicada, a
+proxima deve incrementar patch, minor ou major conforme o tamanho da mudanca.
+
+Publicar:
+
+```powershell
+npm whoami
+npm publish --access public
+```
+
+Validar:
+
+```powershell
+npm view ai-execution-protocol version --registry https://registry.npmjs.org/
+npm install -g ai-execution-protocol
+ai-protocol --help
+```
+
+Se npm exigir 2FA, use OTP ou token granular com bypass 2FA. Nao registre token
+em docs, logs ou conversa.
+
+## PyPI
+
+Nunca publique a mesma versao duas vezes. Se `X.Y.Z` ja foi publicada, a
+proxima deve incrementar patch, minor ou major conforme o tamanho da mudanca.
+
+Publicar:
+
+```powershell
+python -m twine upload publish-dist\*
+```
+
+Quando usar API token:
+
+```text
+username: __token__
+password: <token da PyPI>
+```
+
+Nao cole o token em conversa, arquivo ou log.
+
+Validar:
+
+```powershell
+python -m pip index versions ai-execution-protocol
+pip install --upgrade ai-execution-protocol
+ai-protocol --help
+```
+
+## Recuperacao
+
+Se GitHub release falhar, corrija e rode o comando de release de novo.
+
+Se npm ou PyPI falhar antes de publicar, corrija e tente novamente na mesma
+versao.
+
+Se npm ou PyPI publicar, nao tente sobrescrever a mesma versao. Incremente a
+versao e gere nova release.