@jaimevalasek/aioson 1.5.1 → 1.7.0

package/docs/pt/inteligencia-adaptativa.md

@@ -0,0 +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

package/docs/pt/monitor-de-contexto.md

@@ -0,0 +1,158 @@
+# Monitor de Contexto
+
+> Visualiza em tempo real o uso de janela de contexto por agente, com alertas automáticos de warning e critical. Também funciona no modo de budget de projeto para sessões diretas.
+
+O `context:monitor` tem dois modos de operação:
+- **Modo squad** — lê `context-monitor.json` da squad e exibe barras de progresso por agente
+- **Modo budget** — recebe `--budget` + `--tokens` e calcula a zona de alerta da sessão atual
+
+---
+
+## Modo squad
+
+### `context:monitor --squad`
+
+```bash
+aioson context:monitor [path] [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--squad=<slug>` | Squad a monitorar (obrigatório neste modo) |
+| `--agent=<id>` | Filtrar por agente específico (opcional) |
+| `--json` | Retorna dados estruturados em JSON |
+
+**Exemplos:**
+
+```bash
+# Monitorar todos os agentes de uma squad
+aioson context:monitor . --squad=meu-squad
+
+# Monitorar apenas um agente
+aioson context:monitor . --squad=meu-squad --agent=dev
+
+# Output JSON para dashboards ou scripts
+aioson context:monitor . --squad=meu-squad --json
+```
+
+---
+
+## Modo budget de projeto
+
+Útil em sessões diretas (sem squad) para checar se você está próximo do limite da janela de contexto.
+
+### `context:monitor --budget`
+
+```bash
+aioson context:monitor [path] --budget=<tokens-totais> --tokens=<tokens-atuais>
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--budget=<n>` | Limite total em tokens (ex: `80000` para Claude Sonnet) |
+| `--tokens=<n>` | Tokens consumidos atualmente na sessão |
+| `--json` | Retorna JSON com zona, percentual e budget |
+
+**Zonas:**
+
+| Zona | Faixa | Ícone | Ação sugerida |
+|---|---|---|---|
+| safe | < 60% | ✓ | Continuar normalmente |
+| warning | 60–80% | ⚠ | Planejar `/clear` antes do próximo agente |
+| critical | ≥ 80% | ! | Rodar `context:health` e reduzir carga |
+
+**Exemplos:**
+
+```bash
+# Sessão em safe zone
+aioson context:monitor . --budget=80000 --tokens=28000
+#   ✓ Context: 28,000 tokens (35%) — SAFE
+
+# Sessão em warning zone
+aioson context:monitor . --budget=80000 --tokens=52000
+#   ⚠ Context: 52,000 tokens (65%) — WARNING
+#   Suggestion: /clear before next agent activation
+
+# Sessão em critical zone
+aioson context:monitor . --budget=80000 --tokens=67000
+#   ! Context: 67,000 tokens (84%) — CRITICAL
+#   Run: aioson context:health . for reduction options
+
+# JSON para automação
+aioson context:monitor . --budget=80000 --tokens=52000 --json
+# { "ok": true, "tokens": 52000, "budget": 80000, "pct": 65, "zone": "warning" }
+```
+
+Quando a zona é `warning` ou `critical`, um evento `context_budget_warning` ou `context_budget_critical` é automaticamente registrado no SQLite (na run ativa mais recente), ficando visível no dashboard.
+
+---
+
+## Saída
+
+```
+  Context Monitor — meu-squad
+
+   ✓ dev              [████████░░░░░░░░░░░░] 42%  42000/100000
+   ⚠ qa               [█████████████████░░░] 85%  85000/100000
+   ! analyst          [████████████████████] 97%  97000/100000
+
+  Thresholds: warning=85%  critical=95%
+  Updated: 2026-03-30T14:23:00.000Z
+```
+
+---
+
+## Níveis de alerta
+
+| Ícone | Nível | Limiar | Situação |
+|---|---|---|---|
+| ✓ | normal | < 85% | Contexto confortável |
+| ⚠ | warning | 85–94% | Prepare recovery, evite carregar novos arquivos grandes |
+| ! | critical | 95–99% | Recovery deve ser gerado agora |
+| X | overflow | ≥ 100% | Compactação iminente ou já ocorreu |
+
+---
+
+## Quando usar
+
+- Antes de iniciar uma tarefa longa em um agente que já está com contexto parcialmente cheio
+- Para saber qual agente da squad está mais próximo de compactar
+- Para integrar alertas em scripts de monitoramento via `--json`
+
+---
+
+## JSON output
+
+Com `--json`, retorna objeto com os agentes e seus níveis:
+
+```json
+{
+  "ok": true,
+  "squadSlug": "meu-squad",
+  "agents": {
+    "dev": {
+      "totalUsed": 42000,
+      "windowSize": 100000,
+      "warningLevel": "normal"
+    },
+    "qa": {
+      "totalUsed": 85000,
+      "windowSize": 100000,
+      "warningLevel": "warning"
+    }
+  },
+  "updatedAt": "2026-03-30T14:23:00.000Z"
+}
+```
+
+---
+
+## Relação com recovery automático
+
+Em squads, o monitor detecta automaticamente quando o uso de contexto de um agente cai mais de 30% entre duas medições (sinal de compactação) e injeta um arquivo de recovery. Esse comportamento é coordenado por `checkAndInjectRecovery()` dentro do Squad Dashboard.
+
+Para sessões diretas (sem squad), use [`recovery:generate`](./recuperacao-de-sessao.md).

package/docs/pt/recuperacao-de-sessao.md

@@ -0,0 +1,125 @@
+# Recuperação de Sessão
+
+> Gera e restaura contexto entre sessões do Claude Code sem perder estado após compactação.
+
+Quando o LLM compacta o contexto durante uma sessão longa, o histórico de tarefas, objetivo e arquivos modificados se perde. O `recovery:generate` cria um arquivo markdown estruturado em `.aioson/context/recovery-context.md` que pode ser re-injetado no início da próxima sessão para restaurar exatamente onde você parou.
+
+---
+
+## Comandos
+
+### `recovery:generate`
+
+Gera o arquivo de recuperação para a sessão atual.
+
+```bash
+aioson recovery:generate [path] [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--goal="..."` | Objetivo atual da sessão |
+| `--agent="..."` | Agente ativo |
+| `--json` | Retorna resultado em JSON |
+
+**Exemplos:**
+
+```bash
+# Gerar recovery simples
+aioson recovery:generate .
+
+# Gerar com contexto da sessão
+aioson recovery:generate . --goal="implementar busca FTS5" --agent="deyvin"
+
+# Retornar JSON para scripts
+aioson recovery:generate . --json
+```
+
+---
+
+### `recovery:show`
+
+Exibe o conteúdo do arquivo de recuperação existente.
+
+```bash
+aioson recovery:show [path]
+```
+
+**Exemplos:**
+
+```bash
+# Ver o recovery atual
+aioson recovery:show .
+
+# Saída em JSON
+aioson recovery:show . --json
+```
+
+---
+
+## O que o arquivo contém
+
+O `recovery-context.md` é gerado automaticamente com:
+
+- **Objetivo da sessão** — o que foi passado via `--goal`
+- **Agente ativo** — o que foi passado via `--agent`
+- **Tarefas recentes** — lista de tasks com status
+- **Notas** — observações da sessão
+- **Arquivos modificados** — `git diff --name-only HEAD`
+- **Commits recentes** — últimos 10 commits do repositório
+
+O arquivo é salvo em `.aioson/context/recovery-context.md`.
+
+**Exemplo de arquivo gerado:**
+
+```markdown
+# Recovery Context — Direct Session
+> Generated: 2026-03-30T06:00:00.000Z
+
+## Current Goal
+implementar busca FTS5 e cache de contexto
+
+## Active Agent
+deyvin
+
+## Modified Files
+- src/context-search.js
+- src/context-cache.js
+- tests/context-search.test.js
+
+## Recent Commits
+- a1b2c3d Adicionar IndexManager com FTS5
+- d4e5f6g Implementar context cache RAM
+```
+
+---
+
+## Orçamento de tokens
+
+O arquivo é mantido abaixo de **2000 tokens** automaticamente. Se o conteúdo ultrapassar esse limite, os commits e eventos mais antigos são removidos — o objetivo, agente, arquivos modificados e tarefas são sempre preservados.
+
+---
+
+## Como usar após uma compactação
+
+Quando o Claude compactar o contexto da sessão, basta re-injetar o arquivo:
+
+```
+Read .aioson/context/recovery-context.md and continue from where we left off.
+```
+
+Ou usar o `recovery:show` para copiar o conteúdo direto:
+
+```bash
+aioson recovery:show .
+```
+
+---
+
+## Relação com squads
+
+O `recovery:generate` é específico para **sessões diretas** (sem squad). Para squads, o AIOSON já gera recovery automaticamente via `squad:recovery` quando detecta queda de 30% no uso de contexto.
+
+Para saber mais sobre recovery em squads, veja a documentação do [Squad Dashboard](./squad-dashboard.md).