@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/pt/living-memory/memoria-viva.md

@@ -0,0 +1,141 @@
+# O que é Memória Viva
+
+## O problema
+
+Quando você abre uma nova sessão de IA num projeto que já tem código, há duas opções ruins:
+
+1. **Esperar** o agente ler o repositório do zero — caro em tokens, lento, e o agente ainda perde nuances que só humanos sabem.
+2. **Colar contexto manual** num prompt gigante — frágil, fica obsoleto na primeira mudança, e ninguém atualiza.
+
+Ambas viraram aceitas porque parecem inevitáveis. Não são. O que falta é **um resumo semântico do projeto que se mantém vivo entre sessões** — atualizado pelos próprios agentes, do jeito certo, na hora certa, sem você precisar pedir.
+
+Isso é Memória Viva.
+
+## As 4 camadas
+
+O AIOSON guarda quatro tipos de memória, com papéis diferentes:
+
+| Camada | O que guarda | Onde mora | Atualização |
+|---|---|---|---|
+| **Bootstrap** (semântica) | Identidade, arquitetura, features, estado atual — em prosa curta | `.aioson/context/bootstrap/*.md` | Reflexão automática + `/discover` manual |
+| **Devlog** (episódica) | O que aconteceu em cada sessão de cada agente | `aioson-logs/devlog-*.md` + SQLite | Cada agente escreve no final |
+| **Brain** (procedural) | Padrões reutilizáveis que ganharam qualidade alta | `.aioson/brains/*.brain.json` | Promoção semi-automática de devlogs |
+| **Runtime** (telemetria) | Eventos minuto-a-minuto: handoffs, gates, reflexões, notifies | `.aioson/runtime/aios.sqlite` | CLI grava em todo comando relevante |
+
+Memória Viva foca em duas dessas: **bootstrap** (porque é o resumo que os agentes leem) e **runtime** (porque é onde os hooks e o doctor olham).
+
+## Anatomia de `bootstrap/`
+
+Quatro arquivos, sempre os mesmos quatro nomes:
+
+```
+.aioson/context/bootstrap/
+├── what-is.md        ← identidade do sistema, usuários, proposta de valor
+├── how-it-works.md   ← arquitetura, módulos, fluxo de dados, integrações
+├── what-it-does.md   ← features ativas, regras de negócio, workflows do usuário
+└── current-state.md  ← capabilities já entregues (append-only — diário do que ficou pronto)
+```
+
+Cada um tem YAML frontmatter no topo (`generated_at` é o campo que mais importa — bate o relógio toda vez que o arquivo é atualizado).
+
+Quando um agente abre, ele lê esses 4 arquivos primeiro. Eles cabem na janela de contexto facilmente. O agente sai sabendo o suficiente para começar a trabalhar.
+
+## Ciclo de vida de uma sessão
+
+```
+1. Você abre Claude Code / Codex / Gemini / OpenCode e ativa um agente:
+   /dev "vamos adicionar paginação em /api/posts"
+
+2. O agente lê:
+   - .aioson/config.md
+   - .aioson/context/project.context.md
+   - .aioson/context/dev-state.md  (foco atual, pacote de contexto)
+   - .aioson/context/bootstrap/how-it-works.md + current-state.md
+
+3. O agente trabalha — escreve código, roda testes, commita.
+
+4. Ao final, ele chama:
+   aioson agent:done . --agent=dev --summary="..."
+
+5. O CLI dispara o engine de reflexão:
+   - Roda heurística determinística em git diff HEAD~3..HEAD
+   - Detecta que src/routes/api/posts.js mudou → verdict=relevant
+   - Escreve .aioson/runtime/reflect-prompt.json com o manifesto
+
+6. Na próxima sessão (mesmo agente ou outro):
+   - O agente vê reflect-prompt.json existir
+   - Lê o manifesto: targets=[how-it-works.md, current-state.md], snapshot, diff
+   - Edita os 2 arquivos: adiciona a capability nova, atualiza generated_at
+   - Roda aioson memory:reflect-commit . --agent=dev --output=<json>
+
+7. O CLI valida:
+   - Frontmatter preservado? generated_at bumped? Snapshot hash bate?
+   - Se OK: escreve bootstrap/, apaga reflect-prompt.json, emite memory_reflect_committed
+   - Se FAIL: rejeita, agente tem 1 retry
+
+8. A próxima sessão começa lendo um bootstrap que já reflete a paginação.
+```
+
+A chave: nenhuma chamada LLM do CLI. A reflexão acontece **dentro da sessão paga do harness**. O CLI só decide quando dispara, monta o manifesto, e valida o resultado.
+
+## Quando a reflexão dispara
+
+A heurística é determinística e está no `src/memory-reflect-engine.js`. Verdict `relevant` se qualquer um dos critérios bate:
+
+| Sinal | Detecção |
+|---|---|
+| Rotas/handlers tocados | `routes/`, `controllers/`, `pages/api/`, `app/api/` no diff |
+| Models/migrations tocados | `models/`, `migrations/`, `prisma/schema.prisma`, `app/Models/` |
+| Contratos de domínio tocados | `prd-*.md`, `features.md`, `requirements-*.md` |
+| Adição em `current-state.md` | Diff contém adição |
+| Volume alto | ≥ 10 arquivos E ≥ 200 linhas alteradas |
+
+Caso contrário: `verdict=skip` — a sessão foi sobre CSS, typo, refactor de testes etc. e não muda nada no resumo semântico.
+
+A heurística é conservadora pelo lado dos *falsos positivos* (custa pouco — só atrasa 5s na geração do manifest), mas o doctor (Fase 4) é o backstop: se bootstrap ficar > 30 dias sem update, ele emite warning na próxima sessão sugerindo `/discover` manual.
+
+## Como verificar o estado da memória
+
+```bash
+aioson memory:status .
+# Bootstrap: 4/4
+# Memory index: present
+# Context pack: present
+# Project pulse: present
+# Devlogs: 12 (manifest present)
+# Brains: 8 indexed
+# Runtime: completed:34, running:0
+# Active learnings: 17
+```
+
+ou um resumo compacto para abrir uma sessão fria:
+
+```bash
+aioson memory:summary . --last=5
+# # AIOSON Memory Summary
+# ## Bootstrap
+# - Coverage: 4/4
+# - Identity: AIOSON — AI operating framework...
+# - Current state: ...
+# ## Project Pulse
+# ...
+# ## Recent Runtime
+# ...
+```
+
+## Onde isso encaixa no AIOSON maior
+
+Memória Viva **estende** primitivas que já existiam:
+
+- `workflow:next` e `workflow:execute` continuam sendo o motor único — Memória Viva adiciona um hook depois de `--complete`.
+- `runtime:emit` continua sendo o canal de telemetria — `notify` é wrapper visual em cima dele.
+- Os manifests em `.aioson/agents/manifests/*.manifest.json` continuam o contrato canônico — adicionamos a capability `reflect_memory`.
+- `autonomy-protocol.json` continua a fonte única de verdade — adicionamos o bloco `tiers` (schema v1.1) sem quebrar v1.0.
+
+Não há motor novo. Não há arquivo de memória novo. Não há chamada LLM nova no CLI. É a mesma máquina, com o resumo se mantendo vivo.
+
+## Continue lendo
+
+- [Reflexão In-Harness](./reflexao-in-harness.md) — a pipeline técnica com exemplos
+- [Autonomy Contract](./autonomy-contract.md) — os 3 tiers e como cada harness aplica
+- [Diagramas](./diagramas.md) — fluxo visual de uma sessão completa

package/docs/pt/living-memory/notificacoes-info.md

@@ -0,0 +1,142 @@
+# Notificações inline — `aioson notify`
+
+> `aioson notify` é o canal padrão para o framework e os agentes comunicarem **o que está acontecendo agora**, com um prefixo visual no terminal e um registro permanente em SQLite. É um wrapper sobre `runtime:emit` — não duplica nada, só dá uma UX consistente.
+
+## Sintaxe
+
+```bash
+aioson notify [path] --level=info|warn|block --topic=<topic> --message=<text> [--agent=<name>] [--json]
+```
+
+| Flag | Obrigatório | Default | Comentário |
+|---|---|---|---|
+| `--level` | sim | — | `info` / `warn` / `block` (case-insensitive; valores inválidos caem em `info`) |
+| `--topic` | recomendado | — | rótulo curto entre colchetes — ajuda na hora de filtrar no dashboard |
+| `--message` | sim | — | a mensagem em si |
+| `--agent` | não | `notify-<level>` | quem emitiu — registrado no campo `agent_name` em SQLite |
+| `--json` | não | false | suprime a saída visual (útil em scripts) |
+
+Sem mensagem o comando rejeita com `error: missing_message` e exit 1.
+
+## Os três níveis
+
+| Level | Prefixo | Exit code | Quando usar |
+|---|---|---|---|
+| `info` | `ℹ` | `0` | tier 2 disparou, transição de estado, milestone normal |
+| `warn` | `⚠` | `0` | merece atenção mas não bloqueia — bootstrap stale, drift detectado, fallback acionado |
+| `block` | `⛔` | `2` | tier 3 acionado, script wrapper deve pausar e esperar humano |
+
+Exit code 2 é o sinal canônico para wrappers entenderem "preciso de humano agora". Use em scripts:
+
+```bash
+aioson notify . --level=block --topic=git --message="Push manual necessário: git push origin main"
+if [ $? -eq 2 ]; then
+  echo "→ Pausando, aguarde decisão humana"
+  read -p "Pressione Enter quando o push estiver feito: "
+fi
+```
+
+## Exemplos canônicos
+
+### Reflexão de memória disparou
+
+```bash
+aioson notify . --level=info --topic=memory \
+  --message="Atualizando bootstrap após mudanças em src/routes/"
+```
+
+Saída:
+
+```
+ℹ [memory] Atualizando bootstrap após mudanças em src/routes/
+```
+
+Tipicamente disparado pelo hook em `workflow:next` ou `runAgentDone` quando reflect-prepare devolve `verdict=relevant`.
+
+### Bootstrap stale
+
+```bash
+aioson notify . --level=warn --topic=bootstrap \
+  --message="Bootstrap stale há 35 dias — recomendo /discover"
+```
+
+Saída:
+
+```
+⚠ [bootstrap] Bootstrap stale há 35 dias — recomendo /discover
+```
+
+Disparado pelo Step 0 dos agentes (dev, qa, deyvin) quando `aioson memory:status` reporta cobertura < 4 ou stale > 30d.
+
+### Tier 3 — push manual
+
+```bash
+aioson notify . --level=block --topic=git \
+  --message="Push manual necessário: git push origin main"
+```
+
+Saída:
+
+```
+⛔ [git] Push manual necessário: git push origin main
+```
+
+Exit code 2.
+
+## O que vai pra SQLite
+
+Cada chamada de notify grava um evento em `.aioson/runtime/aios.sqlite` (tabela `agent_events`):
+
+| Campo | Valor |
+|---|---|
+| `event_type` | `notify_info` / `notify_warn` / `notify_block` |
+| `message` | o `--message` |
+| `agent_name` | o `--agent` (ou `notify-<level>`) |
+| `payload_json` | `{ "topic": "<t>", "level": "<l>" }` |
+| `created_at` | ISO 8601 |
+
+Para consultar histórico de notify:
+
+```bash
+sqlite3 .aioson/runtime/aios.sqlite \
+  "SELECT created_at, event_type, message
+   FROM agent_events
+   WHERE event_type LIKE 'notify_%'
+   ORDER BY created_at DESC
+   LIMIT 20;"
+```
+
+## Integração com dashboard
+
+Se o AIOSON Dashboard (app separada) está rodando contra o mesmo `.aioson/runtime/aios.sqlite`:
+
+- `/logs` mostra notify junto com o resto dos eventos (filtro por `event_type`)
+- A linha do tempo de cada feature inclui notify de tier 2 e tier 3 da sessão
+
+## Quando NÃO usar notify
+
+- **Conteúdo persistente** (decisões, learnings, artefatos) — use devlog ou spec.
+- **Saída de comando** (resultado de `aioson workflow:status`) — use stdout direto, sem prefix.
+- **Erros de programação** (NaN, undefined, exception) — use `console.error` ou exit não-zero.
+- **Mensagens longas** — notify é um one-liner. Para multi-line ou markdown, use devlog.
+
+notify é sinal de **estado** — algo aconteceu, está acontecendo, ou vai precisar de humano.
+
+## Customizar prefixos
+
+Os prefixos estão hardcoded em `src/notify-renderer.js`:
+
+```js
+const LEVELS = {
+  info:  { prefix: 'ℹ',  exitCode: 0 },
+  warn:  { prefix: '⚠',  exitCode: 0 },
+  block: { prefix: '⛔', exitCode: 2 }
+};
+```
+
+Para mudar (ex: ambiente sem suporte a emoji), edite e regenere a build. Não há config dinâmica — a intenção é que os prefixos sejam reconhecíveis em telas de log compartilhadas.
+
+## Continue lendo
+
+- [Autonomy Contract](./autonomy-contract.md) — quais comandos tier 2 disparam notify automaticamente
+- [Troubleshooting](./troubleshooting.md) — como reagir a cada nível

package/docs/pt/living-memory/reflexao-in-harness.md

@@ -0,0 +1,218 @@
+# Reflexão In-Harness — pipeline técnica
+
+> Por que "in-harness"? Porque a parte cara — interpretar diff e reescrever prosa — acontece **dentro da sessão do harness** (Claude Code, Codex, Gemini, OpenCode), usando o LLM que você já está pagando. O CLI nunca abre conexão com um provider de IA. Ele decide quando disparar, monta o pacote pro agente, e valida o resultado.
+
+## Componentes
+
+```
+src/memory-reflect-engine.js          ← engine puro: evaluate, buildPrompt, validate
+src/commands/memory-reflect-prepare.js ← sub-comando que monta o manifest
+src/commands/memory-reflect-commit.js  ← sub-comando que valida e persiste
+template/.aioson/templates/reflect-prompts/
+   ├── current-state.md                ← prompt-base para reflexão de current-state
+   ├── how-it-works.md                 ← idem para how-it-works
+   └── what-it-does.md                 ← idem para what-it-does
+```
+
+O engine é **puro**: sem chamada LLM, sem rede, sem mutação de estado fora dos parâmetros que recebe. Ele só lê `git diff`, lê `bootstrap/*.md` e devolve estruturas.
+
+## A heurística — quando reflexão dispara
+
+```js
+const evaluation = await engine.evaluate(targetDir, { agent: 'dev', gitRange: 'HEAD~3..HEAD' });
+// {
+//   verdict: 'relevant' | 'skip',
+//   reasons: ['routes/controllers touched (2 files)', 'features.md changed'],
+//   signals: { routes: [...], models: [...], prd: [...], features: true, ... },
+//   shortstat: { files: 7, insertions: 142, deletions: 28 },
+//   bootstrapPresent: true,
+//   changedFiles: ['src/routes/api/posts.js', '...'],
+//   gitRange: 'HEAD~3..HEAD',
+//   agent: 'dev'
+// }
+```
+
+Critérios para `relevant` (basta um disparar):
+
+| Família | Pattern (regex) | Origem |
+|---|---|---|
+| Routes / API handlers | `(routes\|controllers)/`, `pages/api/`, `app/api/` | Express, Next.js, Laravel, Rails |
+| Models / Migrations | `models/`, `migrations/`, `prisma/schema.prisma`, `app/Models/` | ORM-agnostic |
+| Contratos de domínio | `.aioson/context/prd-*.md`, `features.md`, `requirements-*.md` | AIOSON |
+| Bootstrap mudado | `.aioson/context/bootstrap/current-state.md` | AIOSON |
+| Volume alto | ≥ 10 arquivos **E** ≥ 200 linhas | Genérico |
+
+Tudo o resto: `verdict=skip`. CSS, typos, refactor de testes, dependências dev — não mudam o resumo semântico.
+
+## O manifest — o que o agente recebe
+
+`memory:reflect-prepare` gera `.aioson/runtime/reflect-prompt.json`:
+
+```json
+{
+  "version": 1,
+  "session_id": "dev-2026-05-11T14:30:00.123Z",
+  "trigger_agent": "dev",
+  "git_range": "HEAD~3..HEAD",
+  "heuristic_verdict": "relevant",
+  "heuristic_reasons": [
+    "routes/controllers touched (2 files)",
+    "features.md changed"
+  ],
+  "targets": ["how-it-works.md", "current-state.md"],
+  "current_bootstrap_snapshot": {
+    "what-is.md": "<conteúdo atual>",
+    "how-it-works.md": "<conteúdo atual>",
+    "what-it-does.md": "<conteúdo atual>",
+    "current-state.md": "<conteúdo atual>"
+  },
+  "snapshot_hash": "237721bf02a717e89...",
+  "diff_summary": "7 files, +142/-28",
+  "changed_files": ["src/routes/api/posts.js", "..."],
+  "instructions": "Edit only: bootstrap/how-it-works.md, bootstrap/current-state.md. ...",
+  "validation_rules": {
+    "must_have_frontmatter": true,
+    "must_update_generated_at": true,
+    "must_diff_content": true,
+    "allowed_paths": [
+      ".aioson/context/bootstrap/how-it-works.md",
+      ".aioson/context/bootstrap/current-state.md"
+    ]
+  },
+  "generated_at": "2026-05-11T14:30:00.123Z"
+}
+```
+
+Os campos críticos:
+
+- `targets` — quais arquivos editar. Derivado das signals (rotas/models → `how-it-works.md + current-state.md`; PRD/features → `what-it-does.md + current-state.md`).
+- `current_bootstrap_snapshot` — conteúdo on-disk no momento da preparação. O agente pode comparar com o diff para decidir o que adicionar/remover.
+- `snapshot_hash` — SHA-256 dos 4 arquivos. Usado no commit pra detectar concorrência (alguém editou bootstrap entre prepare e commit → reject).
+- `validation_rules.allowed_paths` — limite duro. Qualquer escrita fora dessa lista é rejeitada no commit.
+
+## O agente reflete
+
+O agente lê o manifest na próxima sessão (ou na mesma, se for o caso). Cada agent.md (dev, qa, deyvin) tem uma seção "Memory reflection" com a instrução:
+
+> Se `.aioson/runtime/reflect-prompt.json` existir no início do seu turno, antes de qualquer outra ação: leia, edite os `targets` em `bootstrap/*.md` (preservando frontmatter, atualizando `generated_at`, sem escrever fora de `allowed_paths`), depois `aioson memory:reflect-commit . --agent=<você> --output=<path>` com `{ "files": { "<rel>": "<content>" } }`. Pule silenciosamente se não houver manifest.
+
+O agente é livre para usar o LLM como achar melhor para fazer a reescrita. O CLI só dita o **contrato**: o que editar, onde escrever, como apresentar o resultado.
+
+## O commit — validação determinística
+
+`memory:reflect-commit` recebe o output do agente (via `--output=<json>` ou stdin):
+
+```json
+{
+  "files": {
+    ".aioson/context/bootstrap/how-it-works.md": "---\nname: how-it-works.md\ngenerated_at: 2026-05-11T14:35:00.000Z\n---\n# How it works\n\n...\n",
+    ".aioson/context/bootstrap/current-state.md": "---\nname: current-state.md\ngenerated_at: 2026-05-11T14:35:00.000Z\n---\n# Current state\n\n## What the system already has\n\n- ...\n- Capability: paginação em /api/posts (cursor-based)\n"
+  }
+}
+```
+
+`engine.validate({ manifest, files, currentSnapshot })` aplica:
+
+1. **Path containment** — todo path em `files` precisa estar em `manifest.validation_rules.allowed_paths`. Escrita fora: reject.
+2. **Frontmatter** — todo arquivo precisa ter o bloco `---\n...\n---` no topo.
+3. **`generated_at` atualizado** — extrai o campo no antigo e no novo; precisa estar diferente.
+4. **Conteúdo mudou** — `content !== original`. Reflexão que devolve o mesmo arquivo é rejeitada.
+5. **Snapshot hash bate** — recalcula SHA-256 dos 4 arquivos on-disk agora, compara com `manifest.snapshot_hash`. Diferente: alguém mexeu entre prepare e commit, abort.
+
+Se tudo passa: escreve, apaga o manifest, emite `memory_reflect_committed` em runtime. Se falha: emite `memory_reflect_failed` com a lista de erros e o agente tem 1 retry.
+
+## Exemplo end-to-end
+
+```bash
+# 1. Sessão de dev mudou rotas
+$ git log --oneline -3
+abc1234 feat(api): paginação cursor-based em /api/posts
+def5678 test(api): cobertura para paginação
+ghi9012 feat(features): registra paginação em features.md
+
+# 2. Agente terminou — agent:done dispara prepare
+$ aioson agent:done . --agent=dev --summary="paginação"
+agent:done — @dev | task: ... | run: dev-...
+
+# 3. Manifest aparece
+$ ls .aioson/runtime/reflect-prompt.json
+.aioson/runtime/reflect-prompt.json
+
+$ cat .aioson/runtime/reflect-prompt.json | jq .heuristic_verdict
+"relevant"
+
+$ cat .aioson/runtime/reflect-prompt.json | jq .targets
+["how-it-works.md", "what-it-does.md", "current-state.md"]
+
+# 4. Próxima sessão de dev/qa/deyvin lê o manifest e edita os 3 arquivos.
+#    O agente prepara o output JSON e commita:
+
+$ cat > /tmp/reflect-output.json <<EOF
+{
+  "files": {
+    ".aioson/context/bootstrap/how-it-works.md": "...",
+    ".aioson/context/bootstrap/what-it-does.md": "...",
+    ".aioson/context/bootstrap/current-state.md": "..."
+  }
+}
+EOF
+
+$ aioson memory:reflect-commit . --agent=dev --output=/tmp/reflect-output.json
+✓ reflect committed: 3 file(s)
+  - .aioson/context/bootstrap/how-it-works.md
+  - .aioson/context/bootstrap/what-it-does.md
+  - .aioson/context/bootstrap/current-state.md
+
+# 5. Manifest foi consumido — não aparece mais
+$ ls .aioson/runtime/reflect-prompt.json
+ls: cannot access: No such file or directory
+```
+
+## O que pode dar errado e como o engine lida
+
+| Cenário | Comportamento |
+|---|---|
+| Git não disponível no projeto | Engine retorna `verdict=skip`, prepare loga `skipped` e não escreve manifest |
+| `bootstrap/` não existe | Prepare retorna `missing_bootstrap`, sugere `/discover` |
+| Diff range inválido (`HEAD~3` não existe — projeto novo) | Fallback para `git diff HEAD` (working tree). Se ainda assim vazio: skip |
+| Agente edita arquivo fora de `allowed_paths` | Commit rejeita, emite `memory_reflect_failed` com erro `outside allowed_paths` |
+| Agente esquece de atualizar `generated_at` | Reject com `generated_at not updated` |
+| Outra sessão editou bootstrap entre prepare e commit | Reject com `snapshot_hash mismatch` — concorrência detectada |
+| Agente devolve conteúdo idêntico | Reject com `content unchanged` |
+| Frontmatter quebrado | Reject com `missing YAML frontmatter` |
+
+Em todos os casos de reject, o manifest **permanece** em disco — o agente pode tentar de novo.
+
+## Forçar reflexão fora do hook
+
+Se você quer rodar manualmente (ex: depois de um rebase grande):
+
+```bash
+# Roda a heurística + escreve manifest mesmo se verdict=skip
+aioson memory:reflect-prepare . --agent=dev --force --git-range=HEAD~5..HEAD
+```
+
+`--force` ignora `verdict=skip` (mas ainda respeita `missing_bootstrap`).
+
+## Telemetria
+
+Cada estágio da pipeline emite um evento em `.aioson/runtime/aios.sqlite`:
+
+- `memory_reflect_prepared` — manifest escrito
+- `memory_reflect_skipped` — heurística disse skip
+- `memory_reflect_committed` — agente terminou com sucesso
+- `memory_reflect_failed` — validação rejeitou
+
+Você pode consultá-los via dashboard ou diretamente:
+
+```bash
+sqlite3 .aioson/runtime/aios.sqlite \
+  "SELECT created_at, event_type, message FROM agent_events
+   WHERE event_type LIKE 'memory_reflect_%' ORDER BY created_at DESC LIMIT 10;"
+```
+
+## Continue lendo
+
+- [Autonomy Contract](./autonomy-contract.md) — como reflexão se encaixa no tier 2 (auto + notify)
+- [Troubleshooting](./troubleshooting.md) — receitas para reflexões que falharam
+- [Diagramas](./diagramas.md) — fluxo visual do hook em `workflow:next`