@jaimevalasek/aioson 1.5.1 → 1.7.0

package/docs/pt/comandos-cli.md

@@ -104,6 +104,8 @@
 | `squad:roi` | Define modelo de precificação e registra métricas de resultado | Quando quer calcular e reportar ROI da squad |
 | `squad:processes` | Lista e encerra processos ativos de uma squad | Quando quer inspecionar ou parar agentes sem usar o dashboard |
 | `squad:recovery` | Gera contexto de recovery para reinjecting após compact | Quando um agente perdeu contexto após compactação |
+| `squad:bus` | Posta, lê, monitora e resume mensagens do intra-bus de uma sessão de squad | Quando quer inspecionar a comunicação entre executores ou postar um finding/block manualmente. Veja [Squad Bus](#37-intra-bus-de-squad) |
+| `squad:autorun` | Decompõe um objetivo em tarefas, executa em grupos paralelos com reflection e registra no bus | Quando quer que uma squad execute autonomamente a partir de um goal de alto nível. Veja [Squad Autorun](#38-execuçao-autonoma-de-squad-squadautorun) |
 | `output-strategy:export` | Exporta a estratégia de output (webhooks, delivery) de uma squad | Quando quer copiar configuração para outra squad ou documentar |
 | `output-strategy:import` | Importa estratégia de output de um arquivo ou outra squad | Quando quer replicar webhooks/delivery entre squads |
 | `deliver` | Dispara delivery manual de conteúdo para webhooks configurados | Quando quer reenviar conteúdo ou testar webhooks |
@@ -128,12 +130,13 @@
 | `runtime:session:finish` | Encerra a sessao direta ativa | Quando terminou a sessao ou vai fazer handoff |
 | `runtime:session:status` | Mostra o estado da sessao direta e os ultimos eventos | Quando quer saber se a sessao ainda esta aberta ou acompanhar com `--watch` |
 | `live:start` | Abre uma sessao viva rastreada para Codex, Claude, Gemini ou OpenCode | Quando quer iniciar o cliente externo a partir do AIOSON e manter status, agente ativo e logs no dashboard |
-| `runtime:emit` | Registra eventos compactos da sessao viva atual | Quando quer marcar tarefa concluida, milestone, block ou step de plano sem abrir uma sessao paralela |
+| `runtime:emit` | Registra eventos compactos da sessão viva atual; aceita `--worker-status`, `--verdict`, `--token-count`, `--progress-pct` | Quando quer marcar tarefa concluída, milestone, block ou step de plano sem abrir uma sessão paralela |
 | `live:status` | Mostra o estado da sessao viva e do processo filho | Quando quer acompanhar `active_agent`, progresso do plano e se o cliente ainda esta vivo |
 | `live:handoff` | Transfere a mesma sessao viva para outro agente AIOSON | Quando o agente atual precisa passar a continuidade para `@product`, `@architect`, `@dev` ou outro agente |
 | `live:close` | Fecha a sessao viva e gera `summary.md` | Quando terminou a sessao externa e quer consolidar o historico compacto + verbose |
 | `runtime:backup` | Faz backup incremental do SQLite para S3 ou HTTP do cliente | Quando quer persistir dados de runtime na nuvem do cliente |
 | `runtime:restore` | Restaura dados de runtime a partir de um backup remoto | Quando quer recuperar dados em outra máquina ou após perda |
+| `agent:done` | Registra conclusão de sessão de agente; aceita `--verdict`, `--artifacts` (CSV de paths) e `--plan-step` | Ao final de cada sessão de agente — é o comando que fecha a run e popula artifacts + verdict no SQLite |
 | `runtime:prune` | Remove registros antigos do SQLite de runtime | Quando o banco está grande e quer liberar espaço |
 
 ### Skills
@@ -143,6 +146,7 @@
 | `skill:install` | Instala skill de terceiros via npm, cloud ou path local | Quando quer adicionar capacidade ao projeto. Veja [Skills](./skills.md) |
 | `skill:list` | Lista skills instaladas em `.aioson/installed-skills/` | Quando quer saber quais skills estão ativas |
 | `skill:remove` | Remove skill instalada e limpa diretórios de ferramentas | Quando uma skill não é mais necessária |
+| `design-hybrid:options` | Abre um seletor visual com setas + espaço para montar um preset temporário de variações de design | Quando quer alimentar a `design-hybrid-forge` com direções mais extravagantes, clássicas, animadas ou com CSS avançado. Usa o locale do projeto automaticamente e aceita `--locale` como override; com `--advanced` libera um 3º modificador. Veja [design-hybrid-forge](./design-hybrid-forge.md) |
 
 ### Cloud
 
@@ -153,6 +157,81 @@
 | `cloud:publish:squad` | Publica snapshot de uma squad local | Quando quer distribuir uma squad para outro projeto ou catálogo |
 | `cloud:publish:genome` | Publica snapshot de um genome local | Quando quer versionar e compartilhar um genome |
 
+### Contexto e recuperação de sessão
+
+| Comando | O que faz | Quando usar |
+|---|---|---|
+| `recovery:generate` | Gera `.aioson/context/recovery-context.md` com objetivo, agente, arquivos modificados e commits recentes | Antes de encerrar uma sessão longa ou ao detectar compactação iminente. Veja [Recuperação de Sessão](./recuperacao-de-sessao.md) |
+| `recovery:show` | Exibe o conteúdo do arquivo de recovery da sessão atual | Quando quer re-injetar o contexto no início de uma nova sessão |
+| `context:health` | Analisa `.aioson/context/`, estima tokens por arquivo, sinaliza arquivos pesados e specs de features já concluídas | Antes de iniciar qualquer sessão longa — dá visibilidade do custo de contexto |
+| `context:trim` | Detecta specs stale (feature `done`) e seções muito longas, arquiva com `--force` | Quando o contexto está crescendo ou há specs de features já entregues |
+| `context:monitor` | Exibe barras ASCII com uso de contexto por agente de uma squad; aceita `--budget` + `--tokens` para modo de budget de projeto | Quando quer acompanhar em tempo real o contexto de uma squad ou checar se está perto do limite. Veja [Monitor de Contexto](./monitor-de-contexto.md) |
+| `context:search:index` | Indexa arquivos `.md`, `.txt` e `.json` do projeto em banco FTS5 | Antes de usar `context:search` — normalmente uma vez, depois incrementalmente. Veja [Busca de Contexto](./busca-de-contexto.md) |
+| `context:search` | Busca documentos relevantes no índice por query em linguagem natural | Quando quer encontrar quais arquivos do projeto contêm contexto relevante para uma tarefa |
+| `context:cache` | Lista sessões de contexto em cache (mais recentes primeiro) | Quando quer saber quais snapshots de sessão estão disponíveis para restaurar. Veja [Cache de Contexto](./cache-de-contexto.md) |
+| `context:cache:save` | Salva um snapshot de conteúdo em `~/.aioson/temp/` | Quando quer preservar o estado de uma sessão antes de trocar de branch ou agente |
+| `context:cache:restore` | Restaura o conteúdo de uma sessão salva, com filtro opcional por query | Quando quer recuperar contexto de uma sessão anterior |
+| `context:cache:cleanup` | Remove sessões expiradas do cache (padrão: mais de 24h) | Quando quer liberar espaço ou forçar limpeza antes do prazo |
+
+### SDD Automation (Regra dos 80%)
+
+Scripts determinísticos que movem verificações de estado, validação de artefatos e gate checks para fora do contexto LLM, economizando entre 4.800–8.800 tokens por feature. Veja [SDD Automation Scripts](./sdd-automation-scripts.md).
+
+| Comando | O que faz | Quando usar |
+|---|---|---|
+| `preflight` | Coleta modo, classificação, framework, test runner, artefatos, gates e prontidão em uma chamada | No início de qualquer sessão de agente |
+| `classify` | Detecta classificação MICRO/SMALL/MEDIUM por scoring automático do PRD ou entrada interativa | Antes de decidir o fluxo de agentes |
+| `sizing` | Determina modelo de sizing: `inplace`, `phased_inplace` ou `phased_external` | Quando o `@architect` ou `@analyst` precisa decidir a estrutura de entrega |
+| `detect:test-runner` | Detecta PHPUnit, Jest, Vitest, Pytest, RSpec, Forge e node:test via arquivos de config | Quando `@dev` ou `@tester` precisa saber como rodar os testes |
+| `pulse:update` | Atualiza `project-pulse.md` com agente, feature, gate e próximo passo | Ao final de cada sessão de agente |
+| `state:save` | Salva ponto de continuação em `dev-state.md` (fase, status, spec-version, histórico) | Durante `@dev` ao fim de cada fase ou antes de encerrar |
+| `feature:close` | Fecha feature com verdict PASS/FAIL: atualiza spec, features.md e project-pulse.md | Após QA sign-off |
+| `gate:check` | Valida pré-requisitos e artefatos de um phase gate (A/B/C/D); retorna PASS ou BLOCKED | Antes de avançar para o próximo agente |
+| `artifact:validate` | Verifica a cadeia completa de artefatos de uma feature (PRD → spec → plano → conformance) | A qualquer momento para checar completude |
+| `workflow:execute` | Monta e executa o plano de agentes baseado na classificação; aceita `--dry-run` e `--start-from` | Para orquestrar features sem o dashboard |
+| `runner:queue:from-plan` | Extrai fases `## Phase N:` do plano e enfileira no runner com prioridades | Antes de iniciar execução por fase com o runner |
+| `learning:auto-promote` | Promove aprendizados de alta frequência para arquivos de regra em `.aioson/rules/` | Após várias sessões — quando quer solidificar padrões em regras |
+
+### Spec e learnings
+
+| Comando | O que faz | Quando usar |
+|---|---|---|
+| `spec:sync` | Lê todos os `spec*.md` de `.aioson/context/` e sincroniza learnings + phase gates para o SQLite | Após cada sessão de `@dev` — garante que learnings e progresso de fase aparecem no dashboard |
+| `spec:status` | Exibe tabela de features com fase atual, último agente e último checkpoint | Quando quer saber exatamente onde cada feature está sem abrir os arquivos manualmente |
+| `spec:checkpoint` | Lê `last_checkpoint` do spec e registra no SQLite como ponto de recuperação explícito | Quando uma sessão caiu sem `agent:done` e o dashboard não reflete o estado real |
+| `learning:export` | Exporta `project_learnings` do SQLite para `.aioson/brains/` como nodes Zettelkasten | Quando quer promover learnings acumulados para memória procedural do projeto |
+
+### Devlog pipeline
+
+| Comando | O que faz | Quando usar |
+|---|---|---|
+| `devlog:process` | Processa devlogs de `aioson-logs/devlog-*.md` e sincroniza artifacts, decisions, learnings e verdict com o SQLite | Quando o CLI não estava disponível durante a sessão e o agente escreveu devlog manual |
+| `devlog:watch` | Daemon que observa `aioson-logs/` e processa novos devlogs automaticamente (WSL2: polling de 5s) | Quando quer processamento zero-touch durante sessões longas |
+| `devlog:export-brains` | Exporta learnings de alta frequência dos devlogs para `.aioson/brains/` (min-frequency=2 por padrão) | Após `devlog:process` — etapa final do pipeline devlog → brains |
+
+### Execução segura
+
+| Comando | O que faz | Quando usar |
+|---|---|---|
+| `sandbox:exec` | Executa um comando shell com timeout, redação automática de secrets e summarização de output longo | Quando quer rodar scripts dentro de uma sessão de agente sem expor variáveis sensíveis do ambiente. Veja [Sandbox de Execução](./sandbox.md) |
+
+### Sharding de agente
+
+| Comando | O que faz | Quando usar |
+|---|---|---|
+| `agent:shard:index` | Divide arquivos de instrução de agente em shards por heading e indexa via FTS5 | Após adicionar ou atualizar arquivos de agente. Veja [Agent Sharding](./agent-sharding.md) |
+| `agent:load` | Carrega os shards mais relevantes de um agente para um objetivo dado, dentro de orçamento de tokens | Quando quer enviar ao LLM apenas as seções do agente necessárias para a tarefa atual |
+
+### Auditoria, briefs e verificação
+
+Três comandos de inteligência de sistema para otimizar tokens, gerar contexto autocontido e verificar entregas sem viés de conversa.
+
+| Comando | O que faz | Quando usar |
+|---|---|---|
+| `agent:audit` | Audita tamanho e tokens de todos os arquivos de agente; detecta seções candidatas a on-demand loading e calcula economia potencial por sessão | Quando quer entender o custo de contexto dos agentes e identificar o que pode ser movido para `.aioson/docs/` (carregamento sob demanda). Veja [Auditoria de Agentes](#39-auditar-agentes-agentaudit) |
+| `brief:gen` | Lê uma fase do plano de implementação + `architecture.md` + `spec.md` e gera um brief 100% autocontido para um worker | Antes de entregar uma fase a um executor de squad — garante que o worker tem tudo que precisa sem buscar contexto adicional. Veja [Geração de Brief](#40-gerar-brief-de-worker-briefgen) |
+| `verify:gate` | Verificação de olhos frescos: compara spec vs artefato entregue sem histórico de conversa; emite `PASS`, `PASS_WITH_NOTES`, `FAIL_WITH_ISSUES` ou `BLOCKED` | Após cada entrega de fase — detecta bugs que o agente gerador não consegue ver por viés de contexto. Veja [Verify Gate](#41-verificar-entrega-verifygate) |
+
 ---
 
 ## Exemplos e usos práticos
@@ -706,6 +785,841 @@ Use quando você quer:
 
 Veja [Output Strategy e Delivery](../output-strategy-delivery.md) para guia completo sobre webhooks, payloads, env vars e troubleshooting.
 
+### 28. Verificar saúde do contexto antes de uma sessão
+
+```bash
+aioson context:health .
+```
+
+Saída esperada:
+
+```
+Context Health Report — meu-projeto
+────────────────────────────────────────────────────────
+Files                        Size      Tokens (est.)
+────────────────────────────────────────────────────────
+discovery.md                 28.3KB    ~7,075  ⚠ HEAVY
+architecture.md              18.1KB    ~4,525
+spec-checkout.md             12.0KB    ~3,000
+spec-auth.md                  8.2KB    ~2,050
+project.context.md            3.9KB    ~975
+────────────────────────────────────────────────────────
+Total context load:                    ~17,625 tokens
+
+⚠  discovery.md is heavy (28.3KB). Consider:
+   → Run: aioson context:pack . --scope=checkout
+
+⚠  1 stale spec file(s) (features: done):
+   → spec-auth.md (feature: auth is done)
+   Run: aioson context:trim . to archive them
+```
+
+Use **antes de começar uma sessão longa** — se `Total context load` estiver acima de 15.000 tokens, considere arquivar specs stale ou criar um contexto escopado.
+
+### 29. Arquivar specs de features já entregues
+
+```bash
+# Ver o que seria arquivado (sem mover nada)
+aioson context:trim . --dry-run
+
+# Arquivar de verdade
+aioson context:trim . --force
+```
+
+Os arquivos são movidos para `.aioson/context/archive/` — nunca deletados. Para restaurar:
+
+```bash
+mv .aioson/context/archive/spec-auth.md .aioson/context/spec-auth.md
+```
+
+### 30. Monitorar budget de tokens durante uma sessão
+
+```bash
+# Verificar se está no safe zone (< 60%), warning (60–80%) ou critical (≥ 80%)
+aioson context:monitor . --budget=80000 --tokens=52000
+# ⚠ Context: 52,000 tokens (65%) — WARNING
+# Suggestion: /clear before next agent activation
+
+# Verificar com output JSON para integrar em scripts
+aioson context:monitor . --budget=80000 --tokens=67000 --json
+```
+
+O comando emite automaticamente um evento no SQLite quando entra em warning ou critical — visível no dashboard como `context_budget_warning`.
+
+### 31. Sincronizar spec com o banco após sessão do @dev
+
+```bash
+# Sincroniza learnings e phase_gates de todos os specs
+aioson spec:sync .
+
+# Ver o estado atual de todas as features
+aioson spec:status .
+```
+
+Saída do `spec:status`:
+
+```
+Project Status — meu-projeto
+────────────────────────────────────────────────────────────────────────────────
+Feature             Phase     Status          Last Agent      Checkpoint
+────────────────────────────────────────────────────────────────────────────────
+checkout            2/5       in_progress     dev             Criando migration...
+auth                5/5       done            qa              QA sign-off 2026-03-28
+────────────────────────────────────────────────────────────────────────────────
+Active learnings: 8  |  Promotable (freq≥3): 3
+```
+
+Execute `spec:sync` logo após cada sessão do `@dev` para manter o dashboard atualizado sem precisar do `live:start`.
+
+### 32. Registrar checkpoint manual quando a sessão caiu
+
+```bash
+# O @dev estava trabalhando em checkout mas o Claude travou sem chamar agent:done
+aioson spec:checkpoint . --feature=checkout
+
+# Para um agente diferente de dev
+aioson spec:checkpoint . --feature=checkout --agent=architect
+```
+
+Saída:
+
+```
+Reading spec-checkout.md...
+last_checkpoint: "Criando migration cart_items — step 3 of 5"
+phase_gates: {"plan":"approved","requirements":"approved","design":"pending"}
+
+Checkpoint registered:
+  run_key: dev-1711234567890
+  summary: "Criando migration cart_items — step 3 of 5"
+  status: in_progress (checkpoint only — use agent:done to close)
+
+Next: continue with /dev — start from last_checkpoint
+```
+
+### 33. Processar devlogs acumulados após sessões sem CLI
+
+```bash
+# Processar todos os devlogs de aioson-logs/ que ainda não foram processados
+aioson devlog:process .
+```
+
+Saída:
+
+```
+Devlog Processing — meu-projeto
+──────────────────────────────────────────────────
+Found 3 devlog(s):
+
+devlog-dev-1711234567.md
+  run: dev-1711234567890
+  Artifacts: 3 registered ✓
+  Decisions: 1 logged ✓
+  Learnings: 2 upserted ✓
+
+devlog-qa-1711237890.md
+  run: qa-1711237890123
+  Artifacts: 1 registered ✓
+  Learnings: 1 upserted ✓
+  Verdict: PASS ✓
+
+devlog-dev-1711241234.md — ⚠ missing frontmatter or agent field. Fix and re-run.
+──────────────────────────────────────────────────
+Processed: 2/3 devlogs
+New learnings: 3 (queued for brains export)
+Artifacts registered: 4
+```
+
+O devlog processado recebe `processed_at` no frontmatter — rodar de novo não cria duplicatas.
+
+### 34. Pipeline completo: devlog → learnings → brains
+
+```bash
+# 1. Processar devlogs acumulados
+aioson devlog:process .
+
+# 2. Exportar learnings com frequência ≥ 3 para .aioson/brains/
+aioson devlog:export-brains . --min-frequency=3
+
+# 3. Promover nodes com frequência ≥ 5 para genome (memória de longo prazo)
+aioson learning:evolve .
+```
+
+Ou, para processamento automático durante uma sessão longa:
+
+```bash
+# Rodar em background — processa novos devlogs assim que são criados
+aioson devlog:watch . &
+
+# No WSL2, usa polling de 5s automaticamente
+# Para forçar polling em qualquer ambiente:
+aioson devlog:watch . --poll &
+```
+
+### 35. Fechar sessão com verdict e artifacts
+
+```bash
+# @dev — sessão concluída com artefatos
+aioson agent:done . --agent=dev \
+  --summary="Cart implementado com migration + testes" \
+  --artifacts="src/database/migrations/003_cart_items.ts,src/actions/cart/AddToCart.ts" \
+  --plan-step=FASE-2
+
+# @qa — sessão com verdict
+aioson agent:done . --agent=qa \
+  --summary="QA checkout — PASS" \
+  --verdict=PASS \
+  --artifacts="output/qa/checkout-report.md"
+```
+
+Os artifacts aparecem na tabela `artifacts` do SQLite e ficam visíveis no dashboard. O verdict é indexado em `execution_events.verdict` para busca e filtragem rápida.
+
+### 36. Emitir evento enriquecido durante sessão live
+
+```bash
+# Checkpoint de plano com consumo de tokens e progresso
+aioson runtime:emit . --agent=dev \
+  --type=plan_checkpoint \
+  --plan-step=FASE-1 \
+  --summary="Migration de cart_items criada e testada" \
+  --token-count=3800 \
+  --progress-pct=40
+
+# Blocker com worker status
+aioson runtime:emit . --agent=dev \
+  --type=task_blocked \
+  --worker-status=blocked \
+  --summary="Aguardando schema de pagamentos do @architect"
+```
+
+### 37. Intra-bus de squad
+
+O `squad:bus` é o canal de comunicação em tempo real entre executores de uma mesma sessão de squad. Cada sessão tem um arquivo JSONL em `.aioson/squads/{slug}/sessions/{id}/bus.jsonl` com todos os eventos de status, findings, bloqueios e resultados.
+
+```bash
+# Postar uma mensagem no bus (executor → coordenador)
+aioson squad:bus . post \
+  --squad=content-team \
+  --session=abc123 \
+  --from=roteirista \
+  --to=coordenador \
+  --type=finding \
+  --content="Briefing do episódio 3 está incompleto — falta o CTA final"
+
+# Ler todas as mensagens da sessão
+aioson squad:bus . read --squad=content-team --session=abc123
+
+# Ler apenas os últimos 10 mensagens, compacto
+aioson squad:bus . read --squad=content-team --session=abc123 --last=10 --compact
+
+# Filtrar só bloqueios
+aioson squad:bus . read --squad=content-team --session=abc123 --type=block
+
+# Monitorar em tempo real (aguarda novas mensagens)
+aioson squad:bus . watch --squad=content-team --session=abc123
+
+# Resumo da sessão (totais por tipo, lista de bloqueios)
+aioson squad:bus . summary --squad=content-team --session=abc123
+
+# Listar todas as sessões da squad
+aioson squad:bus . list --squad=content-team
+
+# Limpar o bus de uma sessão encerrada
+aioson squad:bus . clear --squad=content-team --session=abc123
+```
+
+**Tipos de mensagem suportados:**
+
+| Tipo | Quando usar |
+|------|-------------|
+| `status` | Início, progresso ou conclusão de tarefa |
+| `finding` | Descoberta relevante que outros executores precisam saber |
+| `feedback` | Resultado da reflection após executar uma tarefa |
+| `question` | Dúvida que bloqueia o executor e precisa de resposta |
+| `result` | Output final de uma tarefa |
+| `block` | Bloqueio que impede continuar sem intervenção |
+
+**Exemplo: coordenador respondendo a um bloqueio**
+
+```bash
+# 1. Ver o que está bloqueado
+aioson squad:bus . read --squad=content-team --session=abc123 --type=block
+
+# Saída:
+# [10:14:32] roteirista → coordenador [block]
+#   Aguardando aprovação do outline do ep.3 antes de escrever roteiro
+
+# 2. Coordenador desbloqueia postando no bus
+aioson squad:bus . post \
+  --squad=content-team \
+  --session=abc123 \
+  --from=coordenador \
+  --to=roteirista \
+  --type=feedback \
+  --content="Outline aprovado. Pode prosseguir com o roteiro completo."
+```
+
+---
+
+### 38. Execução autônoma de squad — `squad:autorun`
+
+O `squad:autorun` recebe um objetivo de alto nível, decompõe em tarefas, organiza em grupos paralelos e executa tudo automaticamente. Pode usar reflection após cada tarefa e registrar tudo no intra-bus.
+
+#### Fluxo básico
+
+```bash
+# Executar com goal direto (decomposição heurística)
+aioson squad:autorun . \
+  --squad=content-team \
+  --goal="Criar 3 episódios de podcast para o mês de abril"
+```
+
+O comando:
+1. Detecta os executores da squad em `squad.json`
+2. Decompõe o goal em tarefas usando verbos de ação (criar, revisar, publicar, etc.)
+3. Organiza tarefas em grupos paralelos por dependência
+4. Executa cada grupo (tarefas independentes em paralelo)
+5. Grava o plano em `.aioson/squads/content-team/sessions/{id}/plan.json`
+
+#### Com reflection e bus
+
+```bash
+aioson squad:autorun . \
+  --squad=content-team \
+  --goal="Criar 3 episódios de podcast para o mês de abril" \
+  --reflect \
+  --bus
+```
+
+Com `--reflect`, após cada tarefa o sistema roda uma checklist de qualidade. Se falhar em critérios críticos, marca como `NEEDS_ITERATION` e tenta de novo (até `max_iterations` configurado em `squad.json`). Se esgotar as iterações, marca como `ESCALATE` — o coordenador precisa intervir.
+
+#### Ver o plano sem executar (dry-run)
+
+```bash
+aioson squad:autorun . \
+  --squad=content-team \
+  --goal="Criar campanha de lançamento do produto X" \
+  --dry-run
+```
+
+Saída de exemplo:
+
+```
+Plan ready: 6 tasks across 3 parallel group(s)
+
+Group 1 (2 tasks) — running in parallel
+  ○ task-1: Criar briefing da campanha [executor: estrategista]
+  ○ task-2: Mapear canais de distribuição [executor: analista]
+
+Group 2 (3 tasks) — running in parallel
+  ○ task-3: Escrever copy das redes sociais [executor: copywriter]
+  ○ task-4: Criar roteiro do vídeo de lançamento [executor: roteirista]
+  ○ task-5: Definir calendário de publicação [executor: estrategista]
+
+Group 3 (1 task)
+  ○ task-6: Revisar pacote completo da campanha [executor: coordenador]
+
+[dry-run] Plan shown above. No tasks executed.
+```
+
+#### Modo estruturado (LLM decompõe o plano)
+
+```bash
+aioson squad:autorun . \
+  --squad=content-team \
+  --goal="Criar campanha de lançamento" \
+  --mode=structured
+```
+
+No modo `structured`, o comando salva um prompt de decomposição para o agente preencher o plano manualmente e depois retoma:
+
+```bash
+# Depois que o agente preencheu o plano:
+aioson squad:autorun . --squad=content-team --plan=SESSION_ID
+```
+
+#### Retomar uma sessão existente
+
+```bash
+# Ver sessões disponíveis
+aioson squad:bus . list --squad=content-team
+
+# Retomar do ponto onde parou
+aioson squad:autorun . --squad=content-team --plan=abc-123-def-456
+```
+
+#### Flags disponíveis
+
+| Flag | Padrão | O que faz |
+|------|--------|-----------|
+| `--goal` | — | Objetivo de alto nível (obrigatório se não usar `--plan`) |
+| `--plan` | — | ID de sessão para retomar plano existente |
+| `--reflect` | false | Roda reflection após cada tarefa |
+| `--bus` | true | Ativa o intra-bus de comunicação |
+| `--mode` | heuristic | `heuristic` (regex + executores) ou `structured` (LLM) |
+| `--dry-run` | false | Mostra o plano sem executar |
+| `--sequential` | false | Força execução sequencial mesmo para tarefas paralelas |
+| `--timeout` | 120 | Timeout por tarefa em segundos |
+
+---
+
+### 39. Auditar agentes — `agent:audit`
+
+Escaneia todos os arquivos de agente, estima tokens, classifica por tipo e aponta seções que podem ser movidas para `.aioson/docs/` (on-demand loading) — economizando tokens toda vez que um agente é lido.
+
+**Por que isso importa:** cada sessão longa com um agente de 38KB custa ~9.800 tokens só de instrução. Se metade dessas seções raramente são usadas (convenções de stack, exemplos, templates), movê-las para docs reduz o custo de contexto sem perder capacidade.
+
+#### Auditoria básica
+
+```bash
+aioson agent:audit .
+```
+
+Saída de exemplo:
+
+```
+Agent Audit
+──────────────────────────────────────────────────────────────────────
+Files scanned  : 25
+Total tokens   : ~119,557 per session
+Over hard limit: 6   Over target: 11
+Potential save : ~12,565 tokens/session (on-demand split)
+
+File                                         Type          Size     Tokens      Status
+──────────────────────────────────────────────────────────────────────
+template/.aioson/agents/squad.md             orchestrator  65.0KB   ~16,641 tok ✗ hard
+template/.aioson/agents/dev.md               generalist    38.4KB   ~9,832 tok  ⚠ target
+template/.aioson/agents/ux-ui.md             generalist    33.6KB   ~8,614 tok  ⚠ target
+template/.aioson/agents/deyvin.md            generalist    14.2KB   ~3,633 tok  ✓ ok
+
+On-demand candidates (move to .aioson/docs/ to save tokens):
+  template/.aioson/agents/dev.md              save ~2,100 tok  (4 sections)
+  template/.aioson/agents/ux-ui.md            save ~1,400 tok  (3 sections)
+```
+
+#### Breakdown por seção (verbose)
+
+```bash
+aioson agent:audit . --verbose
+```
+
+Mostra as 5 maiores seções de cada arquivo e marca quais são candidatas a on-demand:
+
+```
+template/.aioson/agents/dev.md    generalist    38.4KB   ~9,832 tok  ⚠ target
+  § Stack e Convenções de Código          4.2KB [on-demand candidate]
+  § Exemplos de implementação             3.1KB [on-demand candidate]
+  § Debugging e troubleshooting           2.8KB [on-demand candidate]
+  § Regras de trabalho                    2.1KB
+  § Working memory (task list)            1.4KB
+```
+
+#### Incluir variantes de locale
+
+```bash
+aioson agent:audit . --locales
+```
+
+Inclui os arquivos de `template/.aioson/locales/*/agents/` na análise — útil para detectar qual locale está mais fora do orçamento.
+
+#### Salvar relatório completo
+
+```bash
+aioson agent:audit . --fix
+```
+
+Escreve `.aioson/docs/agent-audit.md` com tabela completa, lista de candidatos on-demand e recomendações de split. Use para revisão em equipe ou para planejar refatorações de agentes.
+
+**Limites de orçamento por tipo de agente:**
+
+| Tipo | Alvo | Limite |
+|------|------|--------|
+| Auto-loaded (`CLAUDE.md`, `AGENTS.md`) | 3.500 chars | 4.000 chars |
+| Orquestrador (`orchestrator`, `squad`) | 12.000 chars | 20.000 chars |
+| Generalista (`dev`, `architect`, `sheldon`, etc.) | 15.000 chars | 40.000 chars |
+| Focado (todos os demais) | 8.000 chars | 16.000 chars |
+
+**Seções automaticamente detectadas como candidatas a on-demand:** convenções, folder structure, stack, laravel, next.js, debugging, worktree, animação, output contract, exemplos, templates e outras seções raramente necessárias no início da sessão.
+
+---
+
+### 40. Gerar brief de worker — `brief:gen`
+
+Um brief autocontido é o que garante que um executor de squad não vai falhar por falta de contexto. O `brief:gen` lê o plano de implementação, puxa excerpts relevantes de `architecture.md` e `spec.md` e monta um documento que o worker pode executar sem olhar mais nada.
+
+**Regra de ouro dos briefs:**
+
+> O worker não tem acesso ao histórico de conversa. Tudo que ele precisa saber deve estar no brief.
+
+#### Gerar brief para a primeira fase não executada
+
+```bash
+aioson brief:gen .
+```
+
+O comando descobre automaticamente `implementation-plan.md` em `.aioson/context/` e usa a fase 1 por padrão.
+
+#### Especificar uma fase
+
+```bash
+aioson brief:gen . --phase=2
+```
+
+#### Especificar o arquivo de plano
+
+```bash
+aioson brief:gen . --plan=plans/sprint-2.md --phase=1
+```
+
+#### Gerar brief para executor de squad
+
+```bash
+aioson brief:gen . --squad=content-team --executor=roteirista --phase=3
+```
+
+O brief é salvo em `.aioson/squads/content-team/briefs/phase-3-roteirista.md`.
+
+#### Sobrescrever o caminho de saída
+
+```bash
+aioson brief:gen . --phase=2 --out=briefs/fase-2-dev.md
+```
+
+#### Estrutura gerada
+
+O brief gerado contém:
+
+```markdown
+---
+generated_at : 2026-04-02T10:00:00.000Z
+plan_file    : .aioson/context/implementation-plan.md
+phase        : 2
+---
+
+# Worker Brief — ## Phase 2 — API de autenticação
+
+> Este brief é 100% autocontido. Não busque contexto adicional.
+> Leia apenas os arquivos listados. Escreva apenas os arquivos listados.
+
+## Phase goal and tasks
+
+[conteúdo da fase 2 do plano]
+
+## Architecture reference (excerpts)
+
+[seções relevantes de architecture.md — tech stack, folder structure, conventions]
+
+## Spec reference (excerpts)
+
+[spec.md truncado em 4.000 chars]
+
+## Project context
+
+[resumo de project.context.md]
+
+## Done criteria
+
+> Preencha critérios verificáveis antes de entregar ao worker.
+> Exemplo:
+> - [ ] `src/auth/login.ts` existe e exporta `loginHandler`
+> - [ ] Todos os testes passam (`npm test`)
+
+## Hard constraints
+
+> O que o worker NÃO pode tocar ou modificar.
+
+## Out of scope
+
+> O que explicitamente fica fora desta fase.
+```
+
+**Importante:** as seções "Done criteria", "Hard constraints" e "Out of scope" são deixadas como placeholder propositalmente — o orquestrador ou coordenador deve preenchê-las antes de entregar o brief ao worker. Um brief entregue sem done criteria claros é uma das causas mais comuns de falha em squads.
+
+---
+
+### 41. Verificar entrega — `verify:gate`
+
+O `verify:gate` é uma passagem de "olhos frescos" — ele verifica se o artefato entregue atende ao spec sem carregar nenhum histórico de conversa. Isso elimina o viés de contexto que o agente gerador acumula ao longo da sessão.
+
+**Por que isso funciona:** o agente que implementou uma feature, ao revisar o próprio código, tende a "ver" o que pretendia escrever, não o que está escrito. O verify:gate parte do zero: só spec e artefato.
+
+#### Verificação básica
+
+```bash
+aioson verify:gate . \
+  --spec=.aioson/context/briefs/phase-2.md \
+  --artifact=src/auth/
+```
+
+Saída de exemplo:
+
+```
+Verify Gate
+────────────────────────────────────────────────────────────
+Spec     : .aioson/context/briefs/phase-2.md
+Artifact : src/auth/
+Files    : 7
+
+Verdict  : ✗ FAIL_WITH_ISSUES
+
+Issues:
+  ✗ Missing required file: `src/auth/login.ts`
+  ✗ Unchecked criterion: `src/auth/middleware.ts` existe e exporta `authMiddleware`
+
+Notes:
+  ⚠ Empty file: `src/auth/refresh-token.ts`
+
+Passed: 3 checks
+
+Report   : .aioson/context/verify-gate-phase-2.md
+```
+
+#### Verificar com spec completa do projeto
+
+```bash
+aioson verify:gate . \
+  --spec=.aioson/context/spec.md \
+  --artifact=src/
+```
+
+#### Modo strict (notas viram issues)
+
+```bash
+aioson verify:gate . \
+  --spec=.aioson/context/briefs/phase-2.md \
+  --artifact=src/auth/ \
+  --strict
+```
+
+No modo strict, arquivos vazios e critérios sem checkbox marcado também viram `FAIL_WITH_ISSUES`.
+
+#### Salvar relatório em path customizado
+
+```bash
+aioson verify:gate . \
+  --spec=.aioson/context/briefs/phase-2.md \
+  --artifact=src/auth/ \
+  --out=output/qa/verify-fase-2.md
+```
+
+#### Usar no CI (JSON + exit code)
+
+```bash
+aioson verify:gate . \
+  --spec=.aioson/context/briefs/phase-2.md \
+  --artifact=src/ \
+  --json
+```
+
+Saída JSON:
+
+```json
+{
+  "ok": false,
+  "verdict": "FAIL_WITH_ISSUES",
+  "spec": ".aioson/context/briefs/phase-2.md",
+  "artifact": "src/auth/",
+  "report_path": ".aioson/context/verify-gate-phase-2.md",
+  "files_scanned": 7,
+  "issues": [
+    "Missing required file: `src/auth/login.ts`",
+    "Unchecked criterion: `src/auth/middleware.ts` existe e exporta `authMiddleware`"
+  ],
+  "notes": ["Empty file: `src/auth/refresh-token.ts`"],
+  "passes": ["Required file exists: `src/auth/index.ts`"],
+  "requirements": {
+    "required_files": 3,
+    "acceptance_criteria": 5,
+    "required_patterns": 1,
+    "forbidden_patterns": 0
+  }
+}
+```
+
+#### O que o verify:gate checa
+
+| Checagem | Como funciona |
+|----------|---------------|
+| **Arquivos obrigatórios** | Extrai paths de seções "Files to write", "Output files" e "Done criteria" do spec |
+| **Critérios de aceite** | Lê checkboxes `- [ ]` e `- [x]` da seção "Done criteria" — reporta os não marcados |
+| **Padrões obrigatórios** | Busca strings de "Must contain" e "Required patterns" nos arquivos do artefato |
+| **Padrões proibidos** | Busca strings de "Hard constraints" — falha se encontrar |
+| **Arquivos vazios** | Reporta qualquer arquivo de 0 bytes como nota (issue no modo `--strict`) |
+
+**Dica para máxima cobertura:** use `brief:gen` para gerar o spec — ele já formata a seção "Done criteria" com checkboxes e "Files to write" com paths explícitos, que são exatamente o que o `verify:gate` sabe checar.
+
+#### Fluxo completo com brief:gen + verify:gate
+
+```bash
+# 1. Gerar brief para a fase 2
+aioson brief:gen . --phase=2
+# → .aioson/context/briefs/phase-2.md
+
+# 2. [Orquestrador preenche: Done criteria, Hard constraints, Out of scope]
+# 3. Worker executa a fase 2
+
+# 4. Verificar a entrega
+aioson verify:gate . \
+  --spec=.aioson/context/briefs/phase-2.md \
+  --artifact=src/
+
+# 5. Se PASS → agent:done
+aioson agent:done . --agent=dev \
+  --summary="Fase 2 concluída — auth implementado" \
+  --artifacts="src/auth/login.ts,src/auth/middleware.ts" \
+  --plan-step=FASE-2
+
+# 6. Se FAIL_WITH_ISSUES → corrigir e rodar verify:gate de novo
+```
+
+---
+
+### 42. Pré-voo antes de começar o dev
+
+```bash
+aioson preflight . --agent=dev --feature=checkout --json
+```
+
+Retorna modo, classificação, framework, test runner, gates e prontidão em uma chamada. Use antes de abrir qualquer sessão de agente.
+
+### 43. Classificar feature automaticamente
+
+```bash
+aioson classify . --feature=checkout
+# Com override manual via prompts:
+aioson classify . --feature=checkout --interactive
+```
+
+Detecta MICRO / SMALL / MEDIUM lendo PRD e requirements. Use para decidir o fluxo antes de acionar `workflow:execute`.
+
+### 44. Determinar modelo de sizing
+
+```bash
+aioson sizing . --feature=checkout
+```
+
+Decide entre `inplace`, `phased_inplace` e `phased_external` contando entidades, fases e integrações do PRD.
+
+### 45. Detectar test runner do projeto
+
+```bash
+aioson detect:test-runner . --json
+```
+
+Verifica phpunit.xml, jest.config.*, vitest.config.*, pytest.ini, .rspec e package.json. Use no início do `@dev` para saber o comando correto de testes.
+
+### 46. Verificar gate antes de avançar
+
+```bash
+# Checar se Gate C (plano) está aprovado
+aioson gate:check . --feature=checkout --gate=C
+
+# Usar nome aliases
+aioson gate:check . --feature=checkout --gate=plan --json
+```
+
+Valida pré-requisitos e artefatos. Retorna PASS ou BLOCKED com lista de evidências. Use antes de acionar `@dev` após `@analyst`.
+
+### 47. Validar cadeia de artefatos
+
+```bash
+aioson artifact:validate . --feature=checkout --json
+```
+
+Verifica toda a cadeia PRD → spec → plano → conformance e indica o próximo artefato faltante.
+
+### 48. Atualizar pulse ao final da sessão
+
+```bash
+aioson pulse:update . \
+  --agent=dev \
+  --feature=checkout \
+  --gate="Gate C: approved" \
+  --action="Phase 2 concluída" \
+  --next="Phase 3: webhook"
+```
+
+Atualiza `project-pulse.md` com estado atual. Use no `agent:done` ou antes de encerrar a sessão.
+
+### 49. Salvar ponto de continuação
+
+```bash
+aioson state:save . \
+  --feature=checkout \
+  --phase=2 \
+  --status=in_progress \
+  --next="Implement webhook idempotency" \
+  --spec-version=4
+```
+
+Cria entrada em `dev-state.md` para recuperação de sessão. Use ao fim de cada fase.
+
+### 50. Fechar feature após QA
+
+```bash
+# PASS com residual
+aioson feature:close . \
+  --feature=checkout \
+  --verdict=PASS \
+  --residual="Email delivery não testado E2E"
+
+# FAIL
+aioson feature:close . \
+  --feature=checkout \
+  --verdict=FAIL \
+  --notes="Auth edge case ausente"
+```
+
+Fecha a feature: atualiza spec (QA sign-off), features.md e project-pulse.md em uma chamada.
+
+### 51. Executar workflow completo
+
+```bash
+# Dry-run para ver o plano
+aioson workflow:execute . \
+  --feature=checkout \
+  --classification=SMALL \
+  --dry-run
+
+# Executar de verdade
+aioson workflow:execute . --feature=checkout --tool=claude
+
+# Retomar do dev (pular product e analyst)
+aioson workflow:execute . \
+  --feature=checkout \
+  --tool=claude \
+  --start-from=dev
+```
+
+### 52. Enfileirar fases do plano no runner
+
+```bash
+# Ver fases antes de enfileirar
+aioson runner:queue:from-plan . --feature=checkout --dry-run
+
+# Enfileirar para o agente dev
+aioson runner:queue:from-plan . --feature=checkout --agent=dev
+
+# Usar arquivo de plano arbitrário
+aioson runner:queue:from-plan . \
+  --plan=docs/implementation-plan.md \
+  --agent=dev
+```
+
+### 53. Promover aprendizados para regras
+
+```bash
+# Ver o que seria promovido (sem escrever)
+aioson learning:auto-promote . --threshold=3 --dry-run
+
+# Promover aprendizados frequentes
+aioson learning:auto-promote . --threshold=3
+
+# Threshold mais exigente
+aioson learning:auto-promote . --threshold=5
+```
+
+Cria arquivos em `.aioson/rules/` para aprendizados `process` e `quality` com frequência ≥ threshold. Aprendizados `domain` são anotados mas não viram regras.
+
 ---
 
 ## Atalhos úteis