@jaimevalasek/aioson 1.8.0 → 1.9.0

package/docs/pt/5-referencia/live-sessions.md

@@ -0,0 +1,144 @@
+# Live Sessions — Sessões Rastreadas
+
+> **Para quem é:** quem quer ver o progresso das sessões no dashboard do AIOSON, ou quer telemetria de milestones.
+> **Tempo de leitura:** 6 min
+> **O que você vai sair sabendo:**
+> - A diferença entre sessão direta e sessão rastreada
+> - Como abrir, monitorar, transferir e fechar uma live session
+
+## Para que serve
+
+Quando você digita `@dev` no Claude Code e o agente começa a trabalhar, isso é uma sessão direta: o trabalho acontece, artefatos são criados, mas o dashboard não sabe o que está acontecendo em tempo real.
+
+Uma live session é um *envelope rastreado*: ela registra quem está trabalhando, quando começou, quais milestones passou e quando fechou — tudo em SQLite local (`.aioson/runtime/aios.sqlite`) que o dashboard lê.
+
+Você usa live sessions quando quer:
+- Acompanhar progresso no dashboard em tempo real
+- Registrar milestones de execução como eventos
+- Fazer handoff formal entre agentes numa mesma sessão rastreada
+- Ter histórico auditável de sessões por agente
+
+## Quando usar
+
+- Projetos MEDIUM com múltiplos agentes em sequência — cada handoff fica registrado.
+- Times que acompanham progresso via dashboard.
+- Sessões longas (horas) onde você quer checkpoints.
+- Antes de começar um `@dev` de feature crítica — você abre a session, o agente trabalha dentro dela, você fecha ao fim.
+
+## Quando NÃO usar
+
+- Projetos MICRO de sessão única. Overhead de setup não compensa.
+- Quando você usa `aioson workflow:next` — ele já cria a telemetria automaticamente.
+- Exploração rápida sem intenção de registrar.
+
+## Comandos
+
+```bash
+# Abrir uma sessão rastreada
+aioson live:start . --agent=dev --tool=claude
+
+# Com tmux (lança o cliente AI numa pane separada automaticamente)
+aioson live:start . --agent=dev --tool=claude --tmux
+
+# Sem lançar o cliente AI (apenas cria o envelope de sessão)
+aioson live:start . --agent=deyvin --tool=claude --no-launch
+
+# Retomar uma sessão existente
+aioson live:start . --agent=dev --tool=claude --resume
+
+# Ver status da sessão ativa (atualiza a cada 2s)
+aioson live:status . --agent=dev --watch=2
+
+# Ver status uma única vez
+aioson live:status . --agent=dev
+
+# Emitir milestone dentro da sessão
+aioson runtime:emit . --agent=dev --type=checkpoint --summary="Stripe handler concluído"
+
+# Emitir milestone de plano (quando existe um plano em andamento)
+aioson runtime:emit . --agent=dev --type=plan_checkpoint --plan-step=2
+
+# Transferir sessão para outro agente (mantém o envelope rastreado)
+aioson live:handoff . --agent=dev --to=qa --reason="Implementação concluída, 4 testes passando"
+
+# Fechar sessão
+aioson live:close . --agent=qa --summary="QA passou 12/12 ACs. Feature pronta."
+
+# Listar sessões ativas
+aioson live:list .
+```
+
+## Exemplo prático
+
+```
+# Você abre o terminal e inicia a sessão
+$ aioson live:start . --agent=dev --tool=claude --no-launch
+> Live session aberta: session-key=dev-1715103120-a3b4
+> Registrado em: .aioson/runtime/aios.sqlite
+> Abra seu cliente AI e comece com @dev.
+
+# Dentro do Claude Code
+Você > @dev
+@dev > Lendo project-pulse e dossier checkout-stripe...
+       Implementando: stripe-handler, webhook route, checkout form.
+
+# Você acompanha no terminal (outra janela)
+$ aioson live:status . --agent=dev --watch=2
+> Session: dev-1715103120-a3b4 | Status: active | Duração: 00:23:14
+> Último evento: "webhook route implementada" (há 2 min)
+
+# Agente emite milestone
+$ aioson runtime:emit . --agent=dev --type=checkpoint --summary="Stripe handler OK"
+
+# Handoff para @qa
+$ aioson live:handoff . --agent=dev --to=qa --reason="Implementação concluída"
+> Session transferida para @qa. Histórico preservado.
+
+# Dentro do Claude Code
+Você > @qa
+@qa > Retomando sessão rastreada. Lendo handoff-protocol...
+      Testando: 4 ACs identificados.
+
+# Fechar ao fim
+$ aioson live:close . --agent=qa --summary="12/12 ACs passando. Feature pronta."
+> Session fechada. Duração total: 01:45:30. Registrado no dashboard.
+```
+
+## O tmux launcher
+
+Com `--tmux`, o AIOSON lança o cliente AI numa pane separada do tmux e exibe uma status bar compacta com: agente atual, duração, último evento. Util para trabalho longo sem precisar alternar entre terminais.
+
+Requer `tmux` instalado (`apt install tmux` ou `brew install tmux`).
+
+```bash
+aioson live:start . --agent=dev --tool=claude --tmux
+# Abre: pane esquerda (status bar) + pane direita (claude)
+```
+
+## Saídas em disco
+
+```
+.aioson/runtime/
+├── aios.sqlite                    ← banco principal (dashboard lê daqui)
+└── live/<session-key>/
+    ├── state.json                 ← estado da sessão
+    ├── events.ndjson              ← stream de eventos (até 10 por sessão)
+    └── summary.md                 ← resumo ao fechar
+```
+
+## Diferença: live session vs workflow:next
+
+| | `live:start` | `workflow:next` |
+|---|---|---|
+| Quem controla routing | Você | O CLI |
+| Registra telemetria | Sim | Sim |
+| Lança cliente AI | Opcional | Sim |
+| Flexibilidade | Total | Workflow-driven |
+
+Use `workflow:next` para seguir o fluxo automático do SDD. Use `live:start` quando quer controle manual sobre qual agente está ativo.
+
+## Próximo passo
+
+- [Agent-chain continuity](./agent-chain-continuity.md) — como milestones e handoffs se conectam com dossier
+- [Runtime observability](./runtime-observability.md) — visualizar telemetria no dashboard
+- [Hooks & Session Guard](./hooks-session-guard.md) — visibilidade automática sem live session

package/docs/pt/5-referencia/memoria-e-contexto.md

@@ -0,0 +1,340 @@
+# Memória e Contexto
+
+> **Para quem é:** qualquer pessoa usando AIOSON que queira entender como a "memória" entre sessões funciona, ou que precise depurar por que um agente "esqueceu" algo.
+> **Tempo de leitura:** ~10 min (doc consolidado).
+> **O que você vai sair sabendo:**
+> - As 3 camadas de memória do AIOSON e o papel de cada uma
+> - Como usar os 4 comandos de contexto (pack, cache, busca, monitor)
+> - Onde cada artefato de memória vive no disco
+
+---
+
+## Por que existe (o problema)
+
+Todo cliente AI tem janela de contexto limitada. Numa sessão longa, você acumula histórico, código, specs, decisões — e quando a janela enche, o cliente compacta ou descarta. A próxima sessão começa do zero. Para um projeto de 3 dias, isso significa repassar para a IA o que você estava fazendo, qual era o estado do código, que decisões já foram tomadas — pura repetição.
+
+O segundo problema é de escala: um monorepo com 2.000 arquivos não cabe numa janela de contexto. Qualquer agente que tentar ler "o projeto inteiro" desperdiça tokens em arquivos irrelevantes para a task em questão.
+
+AIOSON resolve com **memória externa**: decisões importantes viram arquivos em disco, não ficam só no histórico de conversa. A próxima sessão lê esses arquivos antes de qualquer coisa. E um conjunto de ferramentas garante que apenas os arquivos *relevantes para a tarefa atual* sejam carregados.
+
+---
+
+## As 3 camadas de memória
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  CAMADA 1 — Arquivos de contexto                           │
+│  .aioson/context/*.md                                      │
+│  project.context.md · architecture.md · spec.md ·          │
+│  dev-state.md · prd.md · dossier/ · features/ ...          │
+│                                                            │
+│  Escrita por agentes, lida por agentes.                    │
+│  Persistente no Git (pode commitar).                       │
+└────────────────────────────────────────────────────────────┘
+           │ alimenta
+           ▼
+┌────────────────────────────────────────────────────────────┐
+│  CAMADA 2 — Brains procedurais (Zettelkasten)              │
+│  .aioson/brains/<agente>/                                  │
+│                                                            │
+│  Nós de conhecimento cross-referenciáveis.                 │
+│  Cada agente carrega apenas os nós relevantes.             │
+│  Gerado por @discover e outros agentes especializados.     │
+└────────────────────────────────────────────────────────────┘
+           │ indexado por
+           ▼
+┌────────────────────────────────────────────────────────────┐
+│  CAMADA 3 — Active retrieval (2026)                        │
+│  ~/.aioson/search/context-search.sqlite                    │
+│                                                            │
+│  FTS5 index. Agentes BUSCAM o que precisam em vez de       │
+│  carregar tudo. Bônus de recência, ranking BM25.           │
+└────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Camada 1 — Arquivos de contexto
+
+São os artefatos que os agentes criam ao longo do workflow. São a "memória oficial" de um projeto.
+
+| Arquivo | Criado por | O que guarda |
+|---|---|---|
+| `project.context.md` | `@setup` | Stack, classificação, idioma, framework |
+| `project-pulse.md` | todos (atualizado a cada sessão) | Estado global vivo do projeto |
+| `architecture.md` | `@analyst`, `@architect` | Entidades de domínio + decisões técnicas |
+| `prd.md` / `spec.md` | `@product` | Escopo, ACs, fora-de-escopo |
+| `design-doc.md` | `@ux-ui` | Specs de componentes, design tokens |
+| `tasks.md` | `@pm` | Backlog, user stories |
+| `dev-state.md` | `@dev` | O que foi implementado, status |
+| `test-plan.md` | `@qa` | Plano de teste, cobertura |
+| `handoff-protocol.json` | todos | Último handoff entre agentes |
+| `features/<slug>/` | `@product` | Specs por feature |
+| `dossier/<slug>/` | agent-chain | Tudo sobre uma feature em curso |
+
+### Context Pack — carregamento mínimo por task
+
+Em vez de ler todos os arquivos acima, use `context:pack` para montar um pacote curado para a task atual:
+
+```bash
+aioson context:pack . --agent=dev --goal="ajustar validação do formulário de cadastro" --module=src
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--agent=<nome>` | Agente que vai usar o contexto |
+| `--goal="..."` | O que você quer fazer (orienta a seleção) |
+| `--module=<pasta>` | Restringir ao módulo relevante |
+| `--max-files=N` | Limitar número de arquivos no pacote |
+
+Gera `.aioson/context/context-pack.md` com:
+- Ordem de leitura recomendada
+- Lista dos arquivos selecionados
+- Trechos embutidos dos mais relevantes
+
+**Quando usar:** antes de começar uma task num projeto grande — coloca na janela de contexto apenas o que importa.
+
+---
+
+## Camada 2 — Brains procedurais
+
+O agente `@discover` (e outros especializados, como `@site-forge`) constroem uma base de conhecimento estruturada em nós Zettelkasten — cada nó tem título, conteúdo e referências cruzadas para outros nós.
+
+```
+.aioson/brains/
+├── discover/
+│   ├── entidades-principais.md
+│   ├── fluxo-autenticacao.md
+│   └── ...
+└── site-forge/
+    ├── squarespace-layout-patterns.md
+    └── ...
+```
+
+Agentes carregam apenas os nós relevantes para a task, usando o índice `bootstrap/` para localizar o que precisam sem ler tudo.
+
+**Quando é útil:** codebases grandes (>500 arquivos) onde um agent que tenta ler tudo vai estourar a janela antes de chegar na task.
+
+---
+
+## Camada 3 — Active retrieval
+
+A camada mais recente (adicionada em 2026, commit `5cc7074`). Antes, agentes tinham que carregar blocos fixos de contexto. Com active retrieval, eles podem **buscar** o que precisam usando termos naturais.
+
+O índice é um SQLite com FTS5, salvo em `~/.aioson/search/context-search.sqlite`.
+
+---
+
+## Operações
+
+### Busca FTS5 — `context:search`
+
+**Primeiro, indexe o projeto:**
+
+```bash
+aioson context:search:index .
+
+# Forçar reindexação após mudanças significativas
+aioson context:search:index . --force
+```
+
+**Depois, busque:**
+
+```bash
+aioson context:search "autenticação JWT"
+aioson context:search "endpoint de pagamento" --limit=5
+aioson context:search "configuração banco de dados" --json
+```
+
+**Saída:**
+
+```
+  Search results for: "autenticação JWT"
+
+  1. Arquitetura de Segurança
+     .aioson/context/architecture.md
+     ...sistema usa [JWT] com expiração de 24h, [autenticação] via Bearer token...
+
+  2. Especificação de API
+     .aioson/context/spec.md
+     ...endpoints protegidos exigem header [Authorization: Bearer <token>]...
+```
+
+**Como o ranking funciona:**
+- BM25 built-in do FTS5 (penaliza termos raros e de spam, recompensa precisão)
+- Bônus de recência: arquivos modificados recentemente têm score ligeiramente maior
+- Decay de 30 dias: após um mês, o bônus de recência se dissipa
+- Entradas com mais de 24h na indexação são reconsideradas na próxima passagem; use `--force` para atualizar antes disso
+
+---
+
+### Cache de snapshot — `context:cache`
+
+Salva o estado de uma sessão para restaurar depois — útil antes de trocar de branch, de agente, ou de máquina.
+
+**Listar sessões salvas:**
+
+```bash
+aioson context:cache
+```
+
+```
+  Cached Context Sessions
+
+  a3f8c2d1  2026-05-06T14:00  6KB — implementar checkout Stripe
+  b9e1f4a2  2026-05-05T10:30  8KB — refatorar módulo de pedidos
+```
+
+**Salvar snapshot:**
+
+```bash
+aioson context:cache:save . \
+  --content="$(cat .aioson/context/dev-state.md)" \
+  --goal="checkout Stripe — mid-implementation" \
+  --agent="dev"
+```
+
+**Restaurar:**
+
+```bash
+# Restaurar completo
+aioson context:cache:restore --session=a3f8c2d1
+
+# Restaurar apenas linhas relacionadas a JWT
+aioson context:cache:restore --session=a3f8c2d1 --query="JWT"
+```
+
+**Limpar sessões expiradas:**
+
+```bash
+aioson context:cache:cleanup          # remove > 24h (padrão)
+aioson context:cache:cleanup --max-age=6  # remove > 6h
+```
+
+As sessões ficam em `~/.aioson/temp/` — fora do repositório, nunca commitadas.
+
+---
+
+### Monitor de uso — `context:monitor`
+
+Dois modos de operação:
+
+**Modo budget de projeto** — útil em sessões diretas no Claude Code/Codex/etc.:
+
+```bash
+aioson context:monitor . --budget=80000 --tokens=52000
+```
+
+```
+  ⚠ Context: 52,000 tokens (65%) — WARNING
+  Suggestion: /clear before next agent activation
+```
+
+| Zona | Faixa | Ação |
+|---|---|---|
+| safe | < 60% | Continuar normalmente |
+| warning | 60–80% | Planejar `/clear` antes do próximo agente |
+| critical | ≥ 80% | Rodar `context:health` e reduzir carga |
+
+**Thresholds por classificação** (para automonitoramento dos agentes, configurado em `.aioson/config.md`):
+
+| Classificação | Threshold de alerta |
+|---|---|
+| MICRO | 75% |
+| SMALL | 65% (padrão) |
+| MEDIUM | 55% |
+
+Quando o agente detecta que está próximo do threshold: ele grava artefatos em progresso, emite aviso de contexto, e registra no `last_checkpoint` o estado atual.
+
+**Modo squad** — para projetos com múltiplos agentes em paralelo:
+
+```bash
+aioson context:monitor . --squad=meu-squad
+aioson context:monitor . --squad=meu-squad --agent=dev
+aioson context:monitor . --squad=meu-squad --json
+```
+
+Quando a zona é `warning` ou `critical`, um evento é automaticamente registrado no SQLite local, ficando visível no dashboard.
+
+---
+
+## Onde tudo vive
+
+```
+seu-projeto/
+└── .aioson/
+    ├── context/             ← Camada 1: artefatos dos agentes (commitável)
+    │   ├── project.context.md
+    │   ├── project-pulse.md
+    │   ├── architecture.md
+    │   ├── spec.md
+    │   ├── dev-state.md
+    │   ├── context-pack.md  ← gerado por context:pack
+    │   ├── features/
+    │   └── dossier/
+    ├── brains/              ← Camada 2: nós Zettelkasten (commitável)
+    │   └── discover/
+    └── runtime/
+        └── aios.sqlite      ← telemetria local (não commitar)
+
+~/.aioson/
+    ├── temp/                ← cache de snapshot (context:cache:save)
+    │   └── <sessionId>/
+    │       └── context.md
+    └── search/
+        └── context-search.sqlite  ← índice FTS5 (context:search:index)
+```
+
+**O que commitar:**
+- Pode commitar `.aioson/context/` — é memória do projeto.
+- Pode commitar `.aioson/brains/` quando for parte real do trabalho.
+- **Não commitar:** `.aioson/runtime/`, `~/.aioson/temp/`, `~/.aioson/search/`.
+- **Não commitar** (gerenciados pelo framework): `.aioson/agents/`, `.aioson/locales/`, `.aioson/skills/`, `.aioson/schemas/`, `.aioson/tasks/`, `.aioson/templates/`.
+
+---
+
+## Quando NÃO usar (anti-padrões)
+
+- **Não use `context:pack` para projetos MICRO de 3 arquivos.** O overhead de montar o pacote supera o benefício.
+- **Não use `context:search` sem indexar primeiro.** O comando busca só o índice; sem `context:search:index`, retorna vazio.
+- **Não comite `~/.aioson/temp/`.** Está fora do projeto por design — é cache pessoal de máquina.
+- **Não regenere brains toda sessão.** `@discover` é pesado; rode quando o codebase mudar significativamente.
+- **Não confunda `context:cache` com feature dossier.** Cache é snapshot temporário de sessão (expira em 24h). O dossier é memória permanente de feature — veja [`feature-dossier.md`](./feature-dossier.md).
+
+---
+
+## Fluxo prático — codebase grande, sessão nova
+
+```
+Você > Quero retomar a feature "checkout-stripe"
+       (sessão anterior caiu ontem)
+
+# 1. Busca o que é relevante
+$ aioson context:search "checkout stripe"
+
+  1. Feature Dossier: checkout-stripe
+     .aioson/context/dossier/checkout-stripe/spec.md
+  2. Estado de implementação
+     .aioson/context/dev-state.md
+
+# 2. Monta pacote mínimo
+$ aioson context:pack . --agent=dev --goal="retomar checkout-stripe" --module=src/checkout
+
+# 3. Abre cliente AI com o pacote já montado
+$ claude .
+
+Você > @deyvin
+@deyvin > [lê context-pack.md e dev-state.md]
+  Encontrei onde paramos: src/checkout/payment.js — a integração
+  com o webhook do Stripe estava 80% feita. Continuando...
+```
+
+---
+
+## Próximo passo
+
+- Quer entender como o dossier de feature funciona? → [`feature-dossier.md`](./feature-dossier.md)
+- Quer ver como sessões completas são retomadas? → [`3-receitas/continuidade-entre-sessoes.md`](../3-receitas/continuidade-entre-sessoes.md)
+- Glossário de termos: Brains, Context Pack, Active Retrieval → [`1-entender/glossario.md`](../1-entender/glossario.md)