@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/pt/{inteligencia-adaptativa.md → 5-referencia/inteligencia-adaptativa.md}

@@ -1,324 +1,324 @@
-# Inteligência Adaptativa
-
-O AIOSON aprende com o trabalho dos agentes e evolui com o projeto. Este documento explica os três sistemas que formam a camada de inteligência adaptativa: o **Evolution Pipeline**, o **Tool Registry** e o **Ambient Intelligence Layer**.
-
----
-
-## Visão Geral
-
-Sem inteligência adaptativa, o AIOSON funciona como uma ferramenta estática: os agentes trabalham, cometem os mesmos erros, repetem os mesmos comandos — e cada sessão começa do zero.
-
-Com inteligência adaptativa:
-
-- Correções que você dá aos agentes viram **regras permanentes no contexto do projeto**
-- Ferramentas criadas por um agente ficam disponíveis em **todas as sessões futuras**
-- O framework **avisa proativamente** quando há itens que precisam de atenção
-
----
-
-## 1. Evolution Pipeline
-
-### O que é
-
-Um pipeline que transforma learnings acumulados em arquivos de configuração do projeto. Em vez de depender de você lembrar de promover learnings manualmente, o AIOSON analisa os padrões e propõe — ou aplica — as mudanças automaticamente.
-
-### Como funciona
-
-Durante as sessões, os agentes registram learnings no banco de dados com tipo, título, frequência e evidências. Quando você roda `aioson learning:evolve`, o pipeline:
-
-1. Filtra learnings com frequência ≥ 2 (ocorreram ao menos duas vezes)
-2. Agrupa por tipo (preferência, processo, domínio, qualidade)
-3. Gera deltas — mudanças propostas para arquivos de contexto e regras
-4. Roda dois gates de validação antes de aprovar cada delta
-5. Aplica os aprovados ou salva uma proposta para revisão
-
-**Gate 1 — Constitucional:** nenhum delta pode tocar arquivos em `.aioson/agents/`. Esses arquivos são imutáveis — são a identidade dos agentes, não configuração de projeto.
-
-**Gate 2 — Tamanho:** arquivos alvo não podem ultrapassar 300 linhas após o append. Evita que o contexto cresça sem controle.
-
-### Mapeamento de tipos para arquivos
-
-| Tipo de learning | Arquivo alvo |
-|---|---|
-| `preference` | `.aioson/context/project.context.md` → seção Preferências |
-| `domain` | `.aioson/context/project.context.md` → seção Conhecimento de Domínio |
-| `quality` | `.aioson/context/project.context.md` → seção Padrões de Qualidade |
-| `process` | `.aioson/rules/<squad>-process.md` (ou `project-process.md`) |
-
-### Comandos
-
-```bash
-# Ver o que seria evoluído (sem aplicar)
-aioson learning:evolve .
-aioson learning:evolve . --dry-run
-
-# Aplicar automaticamente sem perguntar
-aioson learning:evolve . --auto-apply
-
-# Filtrar por squad específico
-aioson learning:evolve . --squad=backend --dry-run
-
-# Aplicar um arquivo de proposta salvo
-aioson learning:apply . --file=.aioson/evolution/pending-2026-03-30T12-00-00.json
-```
-
-### Exemplos práticos
-
-**Cenário:** durante 3 sessões com o agente `/dev`, você corrigiu o mesmo erro — o agente tentava criar arquivos `.ts` num projeto que usa apenas `.js`.
-
-O agente registrou um learning `correction` a cada sessão. Com frequência 3:
-
-```bash
-aioson learning:evolve . --dry-run
-```
-
-Saída:
-```
-Analisando 3 learnings elegíveis...
-
-Deltas propostos: 1 aprovado, 0 rejeitados
-
-  [1] APPEND → .aioson/context/project.context.md
-      Seção: ## Preferências dos Agentes
-      Learnings: 3 (preference)
-      - Este projeto usa CommonJS (.js). Nunca criar arquivos .ts. (alta confiança)
-        > Corrigido 3 vezes em sessões de /dev
-```
-
-```bash
-aioson learning:evolve . --auto-apply
-# ✓ Aplicado: .aioson/context/project.context.md (+3 learnings)
-# 1 delta(s) aplicado(s) com sucesso.
-```
-
-Na próxima sessão, o agente lê o contexto atualizado e não comete mais o erro.
-
-**Cenário:** equipe tem padrões de processo que emergem das sessões.
-
-```bash
-aioson learning:evolve . --squad=backend
-# Gera .aioson/rules/backend-process.md com os padrões consolidados
-```
-
----
-
-## 2. Dynamic Tool Registry
-
-### O que é
-
-Um registro persistente de ferramentas criadas pelos próprios agentes durante o trabalho. Uma ferramenta registrada hoje fica disponível em todas as sessões futuras do projeto — sem que você precise configurar nada.
-
-### Como funciona
-
-As tools são armazenadas no banco SQLite do projeto (`dynamic_tools`). Cada tool tem:
-- Nome único por projeto
-- Descrição
-- Tipo: `shell` (comando bash inline) ou `script` (arquivo Node.js)
-- Squad opcional (se omitido, disponível para todos os agentes)
-
-A execução acontece via subprocess isolado com ambiente restrito — variáveis como `ANTHROPIC_API_KEY` nunca são passadas para as tools.
-
-### Comandos
-
-```bash
-# Registrar uma tool do tipo shell
-aioson tool:register . \
-  --name=run_tests \
-  --description="Roda os testes do projeto" \
-  --type=shell \
-  --cmd="npm test"
-
-# Registrar com filtro de squad
-aioson tool:register . \
-  --name=seed_db \
-  --description="Popula o banco de desenvolvimento" \
-  --type=shell \
-  --cmd="npm run db:seed" \
-  --squad=backend
-
-# Registrar um script Node.js
-aioson tool:register . \
-  --name=check_coverage \
-  --description="Verifica cobertura de testes" \
-  --type=script \
-  --path=.aioson/tools/check-coverage.js
-
-# Listar todas as tools
-aioson tool:list .
-
-# Listar tools de um squad
-aioson tool:list . --squad=backend
-
-# Chamar uma tool
-aioson tool:call . --name=run_tests --input='{}'
-
-# Chamar com input
-aioson tool:call . --name=run_tests --input='{"filter":"auth"}'
-
-# Ver detalhes de uma tool
-aioson tool:show . --name=run_tests
-
-# Remover uma tool
-aioson tool:unregister . --name=run_tests
-```
-
-### Exemplos práticos
-
-**Cenário:** agente `/qa` precisa checar se o servidor local está no ar antes de rodar testes. Em vez de escrever o curl toda vez:
-
-```bash
-aioson tool:register . \
-  --name=check_health \
-  --description="Verifica se o servidor local está respondendo" \
-  --type=shell \
-  --cmd='curl -sf http://localhost:3000/health && echo "OK" || echo "DOWN"'
-```
-
-Agora qualquer agente pode usar:
-```bash
-aioson tool:call . --name=check_health --input='{}'
-# OK
-```
-
-**Cenário:** agente `/dev` cria um script mais complexo para validar migrações:
-
-```bash
-# Agente cria o arquivo
-# .aioson/tools/validate-migrations.js
-
-# Depois registra
-aioson tool:register . \
-  --name=validate_migrations \
-  --description="Verifica se há migrações pendentes no banco" \
-  --type=script \
-  --path=.aioson/tools/validate-migrations.js \
-  --squad=backend \
-  --by=dev
-```
-
-**Segurança:** o subprocess recebe apenas `PATH`, `HOME`, `LANG`, `TERM`, `USER` e `TOOL_INPUT` (o JSON de input). Nenhuma variável de ambiente com credenciais é passada.
-
-**Listar tudo:**
-```bash
-aioson tool:list .
-# Tools registradas (3):
-#
-#   run_tests
-#     Roda os testes do projeto
-#     tipo: shell | registrada: 2026-03-30
-#
-#   check_health
-#     Verifica se o servidor local está respondendo
-#     tipo: shell | registrada: 2026-03-30
-#
-#   validate_migrations [squad:backend]
-#     Verifica se há migrações pendentes no banco
-#     tipo: script | registrada: 2026-03-30
-```
-
----
-
-## 3. Ambient Intelligence Layer
-
-### O que é
-
-Um sistema que monitora o estado do projeto e avisa proativamente quando há itens que precisam de atenção — sem que você precise lembrar de rodar comandos.
-
-### Como funciona
-
-O AIOSON injeta verificações automáticas em pontos-chave do fluxo:
-
-- **Ao iniciar uma sessão** (`live:start`): exibe um digest se há itens pendentes
-- **Ao fechar uma sessão** (`live:close`): mostra o que foi acumulado durante o trabalho
-- **Sob demanda** (`aioson health`): relatório completo do estado do projeto
-
-### Comando health
-
-```bash
-aioson health .
-```
-
-Saída de exemplo:
-```
-AIOSON Health — itens que precisam de atenção:
-
-  ● 8 learning(s) prontos para evoluir
-    → aioson learning:evolve .
-  ○ Squad "frontend" inativo há 14 dia(s)
-  ✗ 1 tool(s) com handler inválido: validate_migrations
-    → aioson tool:unregister . --name=validate_migrations
-
-```
-
-### Digest automático no live:start
-
-Ao iniciar qualquer sessão com um agente:
-
-```bash
-aioson live:start . --agent=dev --tool=claude
-# Sessão iniciada: @dev | claude | session-dev-...
-#
-# AIOSON Health — itens pendentes:
-#   ● 5 learning(s) prontos para evoluir
-#   → aioson health . para detalhes
-```
-
-### Digest automático no live:close
-
-```bash
-aioson live:close . --agent=dev --summary="Implementou feature de auth"
-# Sessão encerrada: @dev | session-dev-... | .aioson/runtime/aios.sqlite
-#
-# AIOSON Health — itens após sessão:
-#   ● 3 learning(s) prontos para evoluir
-#   → aioson health . para detalhes e ações
-```
-
-Para suprimir o digest (modo CI ou scripts):
-```bash
-aioson live:start . --agent=dev --tool=claude --no-health
-aioson live:close . --agent=dev --no-health
-```
-
-### O que o health verifica
-
-| Item | Nível | Ação sugerida |
-|---|---|---|
-| Learnings com freq ≥ 2 prontos para evoluir | info | `aioson learning:evolve .` |
-| Squads sem atividade há 14+ dias | warn | Revisar contexto do squad |
-| Tools com handler de script inexistente | error | `aioson tool:unregister . --name=<nome>` |
-| Propostas de evolução pendentes em `.aioson/evolution/` | info | `aioson learning:apply . --file=...` |
-
----
-
-## Fluxo completo integrado
-
-```
-Sessão de trabalho com /dev
-  │
-  ├─ live:start
-  │    └─ Health digest: "5 learnings prontos para evoluir"
-  │
-  ├─ Agente trabalha...
-  │    ├─ Você corrige erros → agente registra learnings
-  │    └─ Agente cria tools via tool:register
-  │
-  └─ live:close
-       ├─ Health digest: "8 learnings prontos para evoluir"
-       └─ Sugestão: aioson learning:evolve .
-            │
-            └─ learning:evolve --auto-apply
-                 ├─ Gate constitucional: ✓
-                 ├─ Gate de tamanho: ✓
-                 └─ Aplica → .aioson/context/project.context.md atualizado
-
-Próxima sessão: agente já sabe o que não fazer.
-```
-
----
-
-## Referências
-
-- [Comandos CLI](./comandos-cli.md) — referência completa de todos os comandos
-- [Memória e Contexto](./memoria-contexto.md) — como o contexto do projeto é gerenciado
-- [Squads](./automacao-squads.md) — squads e seus learnings
+# Inteligência Adaptativa
+
+O AIOSON aprende com o trabalho dos agentes e evolui com o projeto. Este documento explica os três sistemas que formam a camada de inteligência adaptativa: o **Evolution Pipeline**, o **Tool Registry** e o **Ambient Intelligence Layer**.
+
+---
+
+## Visão Geral
+
+Sem inteligência adaptativa, o AIOSON funciona como uma ferramenta estática: os agentes trabalham, cometem os mesmos erros, repetem os mesmos comandos — e cada sessão começa do zero.
+
+Com inteligência adaptativa:
+
+- Correções que você dá aos agentes viram **regras permanentes no contexto do projeto**
+- Ferramentas criadas por um agente ficam disponíveis em **todas as sessões futuras**
+- O framework **avisa proativamente** quando há itens que precisam de atenção
+
+---
+
+## 1. Evolution Pipeline
+
+### O que é
+
+Um pipeline que transforma learnings acumulados em arquivos de configuração do projeto. Em vez de depender de você lembrar de promover learnings manualmente, o AIOSON analisa os padrões e propõe — ou aplica — as mudanças automaticamente.
+
+### Como funciona
+
+Durante as sessões, os agentes registram learnings no banco de dados com tipo, título, frequência e evidências. Quando você roda `aioson learning:evolve`, o pipeline:
+
+1. Filtra learnings com frequência ≥ 2 (ocorreram ao menos duas vezes)
+2. Agrupa por tipo (preferência, processo, domínio, qualidade)
+3. Gera deltas — mudanças propostas para arquivos de contexto e regras
+4. Roda dois gates de validação antes de aprovar cada delta
+5. Aplica os aprovados ou salva uma proposta para revisão
+
+**Gate 1 — Constitucional:** nenhum delta pode tocar arquivos em `.aioson/agents/`. Esses arquivos são imutáveis — são a identidade dos agentes, não configuração de projeto.
+
+**Gate 2 — Tamanho:** arquivos alvo não podem ultrapassar 300 linhas após o append. Evita que o contexto cresça sem controle.
+
+### Mapeamento de tipos para arquivos
+
+| Tipo de learning | Arquivo alvo |
+|---|---|
+| `preference` | `.aioson/context/project.context.md` → seção Preferências |
+| `domain` | `.aioson/context/project.context.md` → seção Conhecimento de Domínio |
+| `quality` | `.aioson/context/project.context.md` → seção Padrões de Qualidade |
+| `process` | `.aioson/rules/<squad>-process.md` (ou `project-process.md`) |
+
+### Comandos
+
+```bash
+# Ver o que seria evoluído (sem aplicar)
+aioson learning:evolve .
+aioson learning:evolve . --dry-run
+
+# Aplicar automaticamente sem perguntar
+aioson learning:evolve . --auto-apply
+
+# Filtrar por squad específico
+aioson learning:evolve . --squad=backend --dry-run
+
+# Aplicar um arquivo de proposta salvo
+aioson learning:apply . --file=.aioson/evolution/pending-2026-03-30T12-00-00.json
+```
+
+### Exemplos práticos
+
+**Cenário:** durante 3 sessões com o agente `/dev`, você corrigiu o mesmo erro — o agente tentava criar arquivos `.ts` num projeto que usa apenas `.js`.
+
+O agente registrou um learning `correction` a cada sessão. Com frequência 3:
+
+```bash
+aioson learning:evolve . --dry-run
+```
+
+Saída:
+```
+Analisando 3 learnings elegíveis...
+
+Deltas propostos: 1 aprovado, 0 rejeitados
+
+  [1] APPEND → .aioson/context/project.context.md
+      Seção: ## Preferências dos Agentes
+      Learnings: 3 (preference)
+      - Este projeto usa CommonJS (.js). Nunca criar arquivos .ts. (alta confiança)
+        > Corrigido 3 vezes em sessões de /dev
+```
+
+```bash
+aioson learning:evolve . --auto-apply
+# ✓ Aplicado: .aioson/context/project.context.md (+3 learnings)
+# 1 delta(s) aplicado(s) com sucesso.
+```
+
+Na próxima sessão, o agente lê o contexto atualizado e não comete mais o erro.
+
+**Cenário:** equipe tem padrões de processo que emergem das sessões.
+
+```bash
+aioson learning:evolve . --squad=backend
+# Gera .aioson/rules/backend-process.md com os padrões consolidados
+```
+
+---
+
+## 2. Dynamic Tool Registry
+
+### O que é
+
+Um registro persistente de ferramentas criadas pelos próprios agentes durante o trabalho. Uma ferramenta registrada hoje fica disponível em todas as sessões futuras do projeto — sem que você precise configurar nada.
+
+### Como funciona
+
+As tools são armazenadas no banco SQLite do projeto (`dynamic_tools`). Cada tool tem:
+- Nome único por projeto
+- Descrição
+- Tipo: `shell` (comando bash inline) ou `script` (arquivo Node.js)
+- Squad opcional (se omitido, disponível para todos os agentes)
+
+A execução acontece via subprocess isolado com ambiente restrito — variáveis como `ANTHROPIC_API_KEY` nunca são passadas para as tools.
+
+### Comandos
+
+```bash
+# Registrar uma tool do tipo shell
+aioson tool:register . \
+  --name=run_tests \
+  --description="Roda os testes do projeto" \
+  --type=shell \
+  --cmd="npm test"
+
+# Registrar com filtro de squad
+aioson tool:register . \
+  --name=seed_db \
+  --description="Popula o banco de desenvolvimento" \
+  --type=shell \
+  --cmd="npm run db:seed" \
+  --squad=backend
+
+# Registrar um script Node.js
+aioson tool:register . \
+  --name=check_coverage \
+  --description="Verifica cobertura de testes" \
+  --type=script \
+  --path=.aioson/tools/check-coverage.js
+
+# Listar todas as tools
+aioson tool:list .
+
+# Listar tools de um squad
+aioson tool:list . --squad=backend
+
+# Chamar uma tool
+aioson tool:call . --name=run_tests --input='{}'
+
+# Chamar com input
+aioson tool:call . --name=run_tests --input='{"filter":"auth"}'
+
+# Ver detalhes de uma tool
+aioson tool:show . --name=run_tests
+
+# Remover uma tool
+aioson tool:unregister . --name=run_tests
+```
+
+### Exemplos práticos
+
+**Cenário:** agente `/qa` precisa checar se o servidor local está no ar antes de rodar testes. Em vez de escrever o curl toda vez:
+
+```bash
+aioson tool:register . \
+  --name=check_health \
+  --description="Verifica se o servidor local está respondendo" \
+  --type=shell \
+  --cmd='curl -sf http://localhost:3000/health && echo "OK" || echo "DOWN"'
+```
+
+Agora qualquer agente pode usar:
+```bash
+aioson tool:call . --name=check_health --input='{}'
+# OK
+```
+
+**Cenário:** agente `/dev` cria um script mais complexo para validar migrações:
+
+```bash
+# Agente cria o arquivo
+# .aioson/tools/validate-migrations.js
+
+# Depois registra
+aioson tool:register . \
+  --name=validate_migrations \
+  --description="Verifica se há migrações pendentes no banco" \
+  --type=script \
+  --path=.aioson/tools/validate-migrations.js \
+  --squad=backend \
+  --by=dev
+```
+
+**Segurança:** o subprocess recebe apenas `PATH`, `HOME`, `LANG`, `TERM`, `USER` e `TOOL_INPUT` (o JSON de input). Nenhuma variável de ambiente com credenciais é passada.
+
+**Listar tudo:**
+```bash
+aioson tool:list .
+# Tools registradas (3):
+#
+#   run_tests
+#     Roda os testes do projeto
+#     tipo: shell | registrada: 2026-03-30
+#
+#   check_health
+#     Verifica se o servidor local está respondendo
+#     tipo: shell | registrada: 2026-03-30
+#
+#   validate_migrations [squad:backend]
+#     Verifica se há migrações pendentes no banco
+#     tipo: script | registrada: 2026-03-30
+```
+
+---
+
+## 3. Ambient Intelligence Layer
+
+### O que é
+
+Um sistema que monitora o estado do projeto e avisa proativamente quando há itens que precisam de atenção — sem que você precise lembrar de rodar comandos.
+
+### Como funciona
+
+O AIOSON injeta verificações automáticas em pontos-chave do fluxo:
+
+- **Ao iniciar uma sessão** (`live:start`): exibe um digest se há itens pendentes
+- **Ao fechar uma sessão** (`live:close`): mostra o que foi acumulado durante o trabalho
+- **Sob demanda** (`aioson health`): relatório completo do estado do projeto
+
+### Comando health
+
+```bash
+aioson health .
+```
+
+Saída de exemplo:
+```
+AIOSON Health — itens que precisam de atenção:
+
+  ● 8 learning(s) prontos para evoluir
+    → aioson learning:evolve .
+  ○ Squad "frontend" inativo há 14 dia(s)
+  ✗ 1 tool(s) com handler inválido: validate_migrations
+    → aioson tool:unregister . --name=validate_migrations
+
+```
+
+### Digest automático no live:start
+
+Ao iniciar qualquer sessão com um agente:
+
+```bash
+aioson live:start . --agent=dev --tool=claude
+# Sessão iniciada: @dev | claude | session-dev-...
+#
+# AIOSON Health — itens pendentes:
+#   ● 5 learning(s) prontos para evoluir
+#   → aioson health . para detalhes
+```
+
+### Digest automático no live:close
+
+```bash
+aioson live:close . --agent=dev --summary="Implementou feature de auth"
+# Sessão encerrada: @dev | session-dev-... | .aioson/runtime/aios.sqlite
+#
+# AIOSON Health — itens após sessão:
+#   ● 3 learning(s) prontos para evoluir
+#   → aioson health . para detalhes e ações
+```
+
+Para suprimir o digest (modo CI ou scripts):
+```bash
+aioson live:start . --agent=dev --tool=claude --no-health
+aioson live:close . --agent=dev --no-health
+```
+
+### O que o health verifica
+
+| Item | Nível | Ação sugerida |
+|---|---|---|
+| Learnings com freq ≥ 2 prontos para evoluir | info | `aioson learning:evolve .` |
+| Squads sem atividade há 14+ dias | warn | Revisar contexto do squad |
+| Tools com handler de script inexistente | error | `aioson tool:unregister . --name=<nome>` |
+| Propostas de evolução pendentes em `.aioson/evolution/` | info | `aioson learning:apply . --file=...` |
+
+---
+
+## Fluxo completo integrado
+
+```
+Sessão de trabalho com /dev
+  │
+  ├─ live:start
+  │    └─ Health digest: "5 learnings prontos para evoluir"
+  │
+  ├─ Agente trabalha...
+  │    ├─ Você corrige erros → agente registra learnings
+  │    └─ Agente cria tools via tool:register
+  │
+  └─ live:close
+       ├─ Health digest: "8 learnings prontos para evoluir"
+       └─ Sugestão: aioson learning:evolve .
+            │
+            └─ learning:evolve --auto-apply
+                 ├─ Gate constitucional: ✓
+                 ├─ Gate de tamanho: ✓
+                 └─ Aplica → .aioson/context/project.context.md atualizado
+
+Próxima sessão: agente já sabe o que não fazer.
+```
+
+---
+
+## Referências
+
+- [Comandos CLI](./comandos-cli.md) — referência completa de todos os comandos
+- [Memória e Contexto](./memoria-e-contexto.md) — como o contexto do projeto é gerenciado
+- [Squads](./automacao-squads.md) — squads e seus learnings