ai-execution-protocol 0.3.1 → 0.4.0

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.

package/docs/17-documentacao-atomica.md

@@ -0,0 +1,117 @@
+# 17 - Documentacao Atomica
+
+## Ideia central
+
+Documentacao boa para IA nao e apenas curta.
+
+Ela deve ser organizada por assunto rastreavel:
+
+```text
+um arquivo = um dominio, fluxo, decisao, componente ou integracao especifica
+```
+
+O objetivo e permitir que a IA encontre rapidamente o documento certo e depois
+use `rg` para localizar o ponto exato no codigo.
+
+## Fluxo recomendado
+
+1. Identificar termos do pedido do usuario.
+2. Procurar dominio ou alias em `context-map.yaml`.
+3. Abrir o `.md` atomico do assunto.
+4. Usar `rg` para procurar simbolos, termos e aliases no codigo.
+5. Ler o trecho especifico primeiro.
+6. Expandir para imports, tipos, callers ou arquivo inteiro quando necessario.
+7. Validar o comportamento no codigo atual.
+
+Exemplo:
+
+```powershell
+rg -n "login|validateUser|AuthService" docs protocol src
+rg -n "JWT|createToken|token" docs protocol src
+```
+
+## Bons nomes
+
+Use nomes que a IA provavelmente buscaria:
+
+```text
+docs/auth-login.md
+docs/auth-jwt.md
+docs/auth-permissions.md
+docs/payments-checkout.md
+docs/payments-webhook.md
+docs/frontend-buttons.md
+docs/frontend-forms.md
+docs/database-users.md
+```
+
+Evite:
+
+```text
+docs/geral.md
+docs/notas.md
+docs/parte-1.md
+docs/tudo.md
+```
+
+## Quando criar ou dividir
+
+Crie ou divida documentacao quando:
+
+- um arquivo mistura assuntos independentes;
+- o arquivo se aproxima do limite de 400 linhas;
+- uma busca com `rg` encontra muitas secoes sem relacao;
+- uma decisao, fluxo ou componente precisa ser encontrado isoladamente;
+- um assunto transversal precisa de doc principal com links para docs
+  especificas.
+
+Nao divida quando:
+
+- o detalhe nao tem valor isolado;
+- o arquivo novo teria apenas uma nota temporaria;
+- o assunto ja existe em outro `.md` e pode ser atualizado;
+- a divisao criaria duplicidade.
+
+## Falhas e mitigacoes
+
+Fragmentacao demais:
+
+- nao crie arquivo para microdetalhe sem assunto proprio;
+- una ou vincule docs sobre o mesmo tema.
+
+Nome ruim:
+
+- inclua dominio, fluxo, componente ou simbolo no nome;
+- mantenha titulo e nome do arquivo alinhados.
+
+Assunto duplicado:
+
+- rode busca antes de criar doc nova;
+- atualize a doc existente quando o assunto ja estiver coberto.
+
+Doc desatualizada:
+
+- use doc para localizar;
+- use codigo verificado para decidir comportamento;
+- registre risco de doc obsoleta quando encontrar divergencia.
+
+Busca por termo errado:
+
+- use aliases e sinonimos;
+- pesquise em docs e codigo;
+- procure por nomes de dominio, fluxo e simbolos.
+
+Trecho insuficiente:
+
+- expanda para imports, tipos, callers, dependencias ou arquivo inteiro;
+- nao edite comportamento baseado em trecho isolado quando houver efeito
+  lateral.
+
+## Regra pratica
+
+```text
+Doc atomica localiza.
+rg encontra.
+Trecho explica.
+Codigo verificado decide.
+```

package/docs/18-memoria-adaptativa.md

@@ -0,0 +1,107 @@
+# 18 - Memoria adaptativa
+
+## Objetivo
+
+A memoria adaptativa permite que o protocolo evolua com o projeto e com
+preferencias duraveis do usuario sem depender do historico completo do chat.
+
+Ela nao tenta prever o usuario com perfeicao. Ela recupera evidencias pequenas
+para escolher melhores padroes e reduzir perguntas repetidas.
+
+## Ordem de autoridade
+
+Use esta ordem quando houver conflito:
+
+1. Pedido atual do usuario.
+2. Arquivos atuais verificados.
+3. Decisoes ativas do projeto.
+4. Preferencias explicitas.
+5. Padroes inferidos com evidencia.
+6. Resumos e historico.
+
+Memoria orienta. O pedido atual autoriza. O codigo verificado define o
+comportamento existente.
+
+## Tipos
+
+- Preferencia explicita: pode ficar ativa imediatamente.
+- Decisao de projeto: fica ativa quando confirmada e limitada ao projeto.
+- Estado de projeto: exige evidencia em arquivo atual.
+- Preferencia inferida: fica candidata ate repeticao ou confirmacao.
+- Padrao de trabalho: fica candidato ate repeticao.
+- Resumo de conversa: e opcional e nunca vira contexto obrigatorio.
+
+## Ciclo de atualizacao
+
+Depois de uma tarefa, a IA verifica se surgiu um fato duravel:
+
+1. Extrair o candidato.
+2. Bloquear conteudo sensivel.
+3. Procurar assunto e escopo existentes.
+4. Comparar valor, fonte e evidencia.
+5. Manter, promover, substituir ou descartar.
+6. Atualizar `memory/INDEX.yaml`.
+7. Validar duplicidade, conflito e tamanho.
+
+Se nada duravel mudou, o resultado correto e `unchanged`. Escrever em toda
+tarefa criaria ruido e aumentaria custo.
+
+## Seguranca
+
+Nunca armazene:
+
+- senhas, tokens, chaves ou segredos;
+- dados de cliente;
+- logs reais sem reducao e remocao de dados sensiveis;
+- conversa bruta desnecessaria;
+- inferencias pessoais sem utilidade tecnica clara.
+
+Memoria nunca pode ampliar escopo, autorizar acao sensivel, reduzir um risco
+conhecido ou substituir confirmacao de nivel critico.
+
+## Estrutura
+
+`memory/INDEX.yaml` e o ponto de entrada. Leia somente os assuntos que combinam
+com a tarefa.
+
+Use:
+
+- `memory/user/` para preferencias duraveis;
+- `memory/projects/` para estado e decisoes com escopo;
+- `memory/patterns/` para estrategias repetidas;
+- `candidate-memory/` para itens ainda nao autoritativos;
+- `memory/archive/` apenas para auditoria ou comparacao historica.
+
+## Automacao
+
+O script `scripts/memory_manager.py` faz inclusao, consulta e validacao:
+
+```powershell
+python scripts/memory_manager.py --root . validate
+```
+
+Preferencia explicita:
+
+```powershell
+python scripts/memory_manager.py --root . upsert `
+  --id preferencia_validacao_001 `
+  --area user `
+  --type explicit_preference `
+  --subject workflow_preferences `
+  --value "Preferir validacao focada antes da suite completa." `
+  --scope all_projects `
+  --explicit
+```
+
+Estado de projeto exige evidencia:
+
+```powershell
+python scripts/memory_manager.py --root . upsert `
+  --id estado_projeto_001 `
+  --area projects `
+  --type project_state `
+  --subject current_state `
+  --value "A CLI usa o manifesto unico de instalacao." `
+  --scope ai-execution-protocol `
+  --evidence install-manifest.json
+```

package/docs/19-orcamento-de-contexto.md

@@ -0,0 +1,63 @@
+# 19 - Orcamento de contexto
+
+## Objetivo
+
+O orcamento de contexto limita leitura inicial, nao a investigacao necessaria.
+Ele reduz arquivos e tokens irrelevantes sem trocar correcao ou seguranca por
+economia.
+
+## Limites iniciais
+
+O protocolo usa limites proporcionais:
+
+- nivel 0: cerca de 300 tokens e ate 2 arquivos;
+- nivel 1: cerca de 1.000 tokens e ate 5 arquivos;
+- nivel 2: cerca de 4.000 tokens e ate 12 arquivos;
+- nivel 3: cerca de 6.000 tokens e expansao adaptativa.
+
+Esses valores orientam a primeira recuperacao. Eles nao impedem expansao quando
+falta uma dependencia, o escopo esta incerto, o trecho e insuficiente ou a
+validacao ainda nao pode ser planejada.
+
+## Fluxo economico
+
+1. Classifique a intencao e o risco.
+2. Escolha a rota.
+3. Leia o pack compacto da rota.
+4. Consulte o indice de memoria por assunto.
+5. Busque simbolos com `rg`.
+6. Leia o trecho relevante.
+7. Expanda somente para resolver uma lacuna concreta.
+8. Pare quando alvo, risco e validacao estiverem claros.
+
+## Pacote de contexto
+
+`scripts/context_package.py` gera um pacote auditavel:
+
+```powershell
+python scripts/context_package.py `
+  --objective "Atualizar a regra de memoria." `
+  --route memory_update `
+  --risk 2 `
+  --term memory `
+  --candidate protocol/adaptive-memory.yaml
+```
+
+Se um limite maior que o padrao for necessario, registre o motivo:
+
+```powershell
+python scripts/context_package.py `
+  --objective "Revisar conflito entre memoria e estado atual." `
+  --route memory_conflict_or_replacement `
+  --risk 2 `
+  --budget 5000 `
+  --expansion-reason "Conflito exige verificar duas fontes atuais."
+```
+
+## Medicao
+
+O objetivo de ate 90% de economia se refere a contexto desnecessario. A meta
+deve ser medida em tarefas repetidas e comparada com uma leitura ampla.
+
+Nao declare economia real apenas porque existe um limite configurado. Registre
+tokens estimados, arquivos incluidos, arquivos excluidos e motivo de expansao.

package/docs/20-validacao-seletiva.md

@@ -0,0 +1,46 @@
+# 20 - Validacao seletiva
+
+## Objetivo
+
+Validacao seletiva executa o menor conjunto de verificacoes que prova a
+mudanca. Ela evita rodar a suite completa em ajustes locais sem reduzir
+evidencia em alteracoes compartilhadas ou releases.
+
+## Selecao
+
+- Documentacao: links, busca textual e schema quando houver estrutura.
+- Regra de protocolo: schema, espelho e testes focados.
+- Parser ou avaliador: testes adversariais, framework e benchmark.
+- Instalador ou pacote: instalacao, verificacao e dry-run do pacote.
+- Contrato compartilhado: framework tests e health check.
+- Release: suite completa, builds e verificacao dos pacotes.
+
+## Uso
+
+Detecte as verificacoes a partir do diff atual:
+
+```powershell
+python scripts/selective_validation.py
+```
+
+Informe arquivos diretamente:
+
+```powershell
+python scripts/selective_validation.py `
+  --file protocol/adaptive-memory.yaml `
+  --file scripts/memory_manager.py
+```
+
+Para release:
+
+```powershell
+python scripts/selective_validation.py --release
+```
+
+## Regras
+
+Sempre aumente a validacao quando a mudanca altera contrato compartilhado,
+instalacao, seguranca, dados, avaliacao ou varios modulos.
+
+Nunca declare uma verificacao que nao foi executada. Registre o que ficou
+pendente e o risco residual.