@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/pt/active-learning-loop/README.md

@@ -0,0 +1,117 @@
+# Active Learning Loop — guia em português
+
+> **Active Learning Loop** é o ciclo que fecha o arco entre as primitivas de aprendizado já existentes no AIOSON e o ciclo de vida de uma feature. Quando uma feature é fechada com `feature:close --verdict=PASS`, o framework dispara automaticamente a destilação: learnings são promovidos a regras, o `doctor` monitora lacunas de curadoria, e um fluxo de arquivo aprovado por humano mantém a memória do projeto organizada.
+
+Esta pasta documenta a feature completa — 6 fases, 4 novos verbos CLI, 3 novos checks do doctor.
+
+---
+
+## Para que serve
+
+- **Fechar o loop de aprendizado** — sem Active Learning Loop, learnings acumulam em `project_learnings` mas nunca chegam a regras usáveis. A feature liga os dois pontos: `feature:close` → destilação automática → regras prontas para o próximo agente.
+- **Medir uso real de regras** — agentes declaram "carreguei esta regra" via `aioson context:load`. O doctor usa esse sinal para identificar regras que ninguém mais consulta.
+- **Pesquisar memória rapidamente** — `aioson memory:search` oferece busca BM25 sobre learnings, direto do terminal.
+- **Arquivar com rastreabilidade** — `aioson memory:archive` move regras/brains obsoletos para `_archived/` com log de evolução append-only; `memory:restore` desfaz se necessário.
+- **Alertar sobre lacunas** — três checks novos no `doctor` (staleness de regras, learnings órfãos, lag de destilação) geram hints acionáveis com comandos prontos para copiar.
+
+---
+
+## Pré-requisitos
+
+- AIOSON instalado (versão que incluiu esta feature)
+- `.aioson/config/learning-loop.json` presente no projeto (copiado automaticamente pelo installer; veja [Configuração](#configuração))
+- Projeto classificado como SMALL ou MEDIUM — projetos MICRO optam para fora automaticamente (sem destilação, sem checks do doctor)
+
+---
+
+## Roteiro de leitura
+
+### Quero entender o que mudou no meu fluxo (10 min)
+1. [O que é o Active Learning Loop](./ativo-learning-loop.md) — o problema, as 6 fases, o fluxo completo
+2. [Diagramas](./diagramas.md) — fluxo ASCII do `feature:close` → destilação → `evolution_log` → `doctor`
+
+### Quero usar na prática agora
+3. [Como usar](./como-usar.md) — pesquisar um learning, arquivar uma regra obsoleta, o que `feature:close` faz agora
+4. [Referência CLI](./comandos-cli.md) — todos os flags dos 4 novos verbos
+
+### Algo aconteceu / quero entender o que o doctor está dizendo
+5. [Doctor checks](./doctor-checks.md) — o que cada um dos 3 novos checks significa e como agir
+6. [Troubleshooting](./troubleshooting.md) — lock preso, opt-out MICRO, `pattern:detect` adiado, `aioson update` sobrescreve config
+
+---
+
+## Comandos canônicos
+
+| Comando | O que faz | Tier | Doc |
+|---|---|---|---|
+| `aioson context:load --target=rule:<slug> --agent=<nome>` | Registra que um agente carregou uma regra/brain | tier-1 silencioso | [Referência CLI](./comandos-cli.md) |
+| `aioson memory:search "<query>"` | Busca BM25 em learnings por palavras-chave | tier-1 silencioso | [Referência CLI](./comandos-cli.md) |
+| `aioson memory:archive --id=rule:<slug> --reason="<texto>"` | Arquiva regra/learning/brain com log de evolução | tier-2 notificado | [Referência CLI](./comandos-cli.md) |
+| `aioson memory:restore --id=rule:<slug>` | Restaura item arquivado | tier-2 notificado | [Referência CLI](./comandos-cli.md) |
+| `aioson feature:close --slug=X --verdict=PASS` | Fecha feature + dispara destilação automática (novo) | tier-2 notificado | [Como usar](./como-usar.md) |
+| `aioson doctor .` | Diagnóstico, incluindo 3 novos checks de curadoria | tier-1 silencioso | [Doctor checks](./doctor-checks.md) |
+
+---
+
+## Onde os artefatos vivem
+
+| Caminho | Papel |
+|---|---|
+| `.aioson/config/learning-loop.json` | Configuração do loop por projeto (thresholds, opt-out, timeout) |
+| `.aioson/rules/_archived/YYYY-MM-DD/<slug>.md` | Regras arquivadas com data de arquivamento |
+| `.aioson/brains/_archived/YYYY-MM-DD/<id>.brain.json` | Brains arquivados |
+| `.aioson/context/_archived/YYYY-MM-DD/<slug>.json` | Learnings arquivados |
+| `.aioson/runtime/aios.sqlite` → tabela `evolution_log` | Log append-only de toda mutação de memória |
+| `.aioson/runtime/aios.sqlite` → tabela `execution_events` | Eventos `rule_loaded` / `brain_loaded` emitidos por `context:load` |
+| `.aioson/runtime/aios.sqlite` → virtual table `project_learnings_fts` | Índice FTS5 sobre `project_learnings` (título + evidência) |
+
+---
+
+## Configuração
+
+`.aioson/config/learning-loop.json` é copiado do template no primeiro install:
+
+```json
+{
+  "$schema": "https://aioson.dev/schemas/learning-loop.v1.json",
+  "enabled": true,
+  "skip_on_classification": ["MICRO"],
+  "execution_mode": "foreground",
+  "lock_strategy": "sqlite-row",
+  "auto_promote_threshold": 3,
+  "staleness_window_features_min": 5,
+  "timeout_ms": 5000
+}
+```
+
+| Campo | O que controla |
+|---|---|
+| `enabled` | Liga/desliga o loop inteiro no projeto |
+| `skip_on_classification` | Classificações que opt-out automaticamente (default: `["MICRO"]`) |
+| `auto_promote_threshold` | Quantas evidências um learning precisa para ser promovido automaticamente |
+| `staleness_window_features_min` | Mínimo de features fechadas para calcular janela de staleness |
+| `timeout_ms` | Timeout da destilação em foreground (default: 5000ms) |
+
+> **Aviso:** `aioson update` atualmente **sobrescreve** este arquivo (política do installer). Faça backup de customizações antes de rodar `aioson update`. Veja [Troubleshooting](./troubleshooting.md#aioson-update-sobrescreve-learning-loopjson).
+
+---
+
+## Status
+
+A feature `active-learning-loop` foi entregue em 6 fases:
+
+| Fase | Slug | Entrega | Status |
+|---|---|---|---|
+| 1 | `telemetry-foundation` | CLI `context:load` + eventos `rule_loaded`/`brain_loaded` | PASS |
+| 2 | `memory-search-fts5` | CLI `memory:search` + índice FTS5 BM25 | PASS |
+| 3 | `memory-archive-with-evolution-log` | CLI `memory:archive` + `memory:restore` + `evolution_log` | PASS |
+| 4 | `doctor-curation-checks` | 3 novos checks: staleness, orphans, distillation lag | PASS |
+| 5 | `feature-close-distillation-hook` | Hook em `feature:close` + destilação foreground | PASS |
+| 6 | `inception-mirror-parity` | Validação de paridade `src/` ↔ `template/src/` | PASS |
+
+112/112 testes determinísticos passando. QA aprovado.
+
+Artefatos de especificação (arquivados):
+- [PRD](../../.aioson/context/done/active-learning-loop/prd-active-learning-loop.md)
+- [Spec](../../.aioson/context/done/active-learning-loop/spec-active-learning-loop.md)
+- [Arquitetura](../../.aioson/context/done/active-learning-loop/architecture-active-learning-loop.md)

package/docs/pt/active-learning-loop/ativo-learning-loop.md

@@ -0,0 +1,117 @@
+# O que é o Active Learning Loop
+
+## O problema
+
+O AIOSON já sabia aprender. Depois de cada sessão, `project_learnings` acumula observações: padrões detectados, erros corrigidos, decisões tomadas. Mas havia uma lacuna: esses learnings raramente viravam regras ativas. A destilação existia como comando manual que poucos rodavam. As regras existentes acumulavam sem que ninguém soubesse quais ainda eram consultadas.
+
+O resultado prático: depois de N features, a memória do projeto estava cheia de aprendizados que nunca fecharam o ciclo — nem viraram regras usáveis, nem foram arquivados. O `doctor` não tinha visibilidade do problema. Os agentes continuavam lendo regras que ninguém validava há meses.
+
+Active Learning Loop fecha esse arco.
+
+## O que a feature faz
+
+Quatro superfícies novas, interligadas:
+
+**1. Telemetria de carregamento** — agentes declaram explicitamente "carreguei esta regra/brain" via `aioson context:load`. O CLI grava um evento `rule_loaded` ou `brain_loaded` em `execution_events`. Silencioso, tier-1. O doctor usa esse sinal depois.
+
+**2. Busca em memória** — `aioson memory:search "autenticação JWT"` faz busca BM25 sobre o título e a evidência de todos os learnings ativos. Sem configuração, sem embeddings, sem chamada LLM — SQLite FTS5 nativo.
+
+**3. Arquivo com rastreabilidade** — `aioson memory:archive --id=rule:minha-regra --reason="substituída por X"` move o arquivo físico para `.aioson/rules/_archived/YYYY-MM-DD/` e grava um par de linhas em `evolution_log`: o entry anterior recebe `end_at`, um novo entry documenta o motivo. Append-only — o histórico nunca muda. `memory:restore` desfaz o processo se necessário.
+
+**4. Destilação automática no `feature:close`** — quando você fecha uma feature com `--verdict=PASS`, o CLI roda `runDistillation()` em foreground (timeout 5s), promove learnings que cruzaram o threshold, emite uma notificação com o resumo e grava o resultado em `evolution_log`. Se falhar por qualquer motivo, o código de saída do `feature:close` ainda é 0 — a destilação é best-effort.
+
+## As 6 fases
+
+### Fase 1 — telemetry-foundation
+
+Novo verbo CLI: `aioson context:load`. Os agentes chamam esse comando quando carregam uma regra ou brain no início da sessão. O evento vai para `execution_events` como `rule_loaded` ou `brain_loaded`, com payload: slug, agente, feature associada (opcional).
+
+O verbo suporta `--batch="regra-a,regra-b,regra-c"` para minimizar chamadas quando um agente carrega várias regras de uma vez.
+
+Nenhuma mudança visível no comportamento dos agentes — é telemetria silenciosa. O valor aparece nas fases 4 e 5.
+
+### Fase 2 — memory-search-fts5
+
+Novo verbo: `aioson memory:search "<query>"`. Cria uma virtual table FTS5 (`project_learnings_fts`) sobre `project_learnings`, sincronizada via triggers SQL (INSERT/UPDATE/DELETE). Ranking BM25 por default.
+
+Sanitização de query: cada token (separado por espaço) vira uma frase entre aspas ANDada com os outros. Caracteres de operador FTS5 (`*()^:+-"`) são removidos. Queries que resultam em string vazia retornam `{ ok: false, reason: 'query_unparseable' }` sem erro. Limite de 500 caracteres.
+
+Entradas arquivadas são excluídas por default; `--include-archived` as inclui.
+
+### Fase 3 — memory-archive-with-evolution-log
+
+Dois novos verbos: `memory:archive` e `memory:restore`.
+
+`memory:archive` é tier-2 (notified): emite `aioson notify --level=warn` antes da mutação, move o arquivo físico para `_archived/YYYY-MM-DD/`, e grava duas linhas em `evolution_log` — `end_at` no entry ativo anterior, novo entry com o motivo. A operação é atômica: se a escrita no DB falhar após o move físico, o arquivo é restaurado (rollback de FS).
+
+`--dry-run` simula a operação inteira sem efeito colateral.
+
+`memory:restore` inverte: move o arquivo de volta, grava `event_type='restored'` em `evolution_log`.
+
+**Tier-2 humano-only**: tanto `memory:archive` quanto `memory:restore` recusam execução quando `AIOSON_RUNTIME_HOOK=1` está setado (ambiente de hook automatizado). Essas operações são intencionalmente restritas ao humano.
+
+### Fase 4 — doctor-curation-checks
+
+Três novos checks em `aioson doctor`, com `severity='warning'` (não bloqueiam `ok=true`, mas aparecem em `failedCount`):
+
+1. **`living-memory:rule_staleness`** — regras que não tiveram nenhum evento `rule_loaded` nas últimas N features fechadas. N = max(5, ceil(média de dias entre as últimas 5 features ÷ 7)).
+2. **`living-memory:learning_orphans`** — learnings com `status=promoted` cujo target rule não teve nenhum `rule_loaded` após a promoção. Indica que a regra gerada nunca foi usada.
+3. **`living-memory:distillation_lag`** — 5+ features fechadas, mas menos eventos `auto_distillation` do que features fechadas. O loop não está rodando como esperado.
+
+Projetos com classificação MICRO optam para fora de todos os três checks.
+
+O hint de cada check inclui o comando pronto para copiar: `aioson memory:archive --id=rule:<slug> --reason="..."`.
+
+### Fase 5 — feature-close-distillation-hook
+
+`aioson feature:close --slug=X --verdict=PASS` agora chama `runDistillation(X)` depois do passo de finalização do dossier, antes de retornar.
+
+O fluxo:
+1. Lê a classificação do PRD da feature — se MICRO, emite notify e pula.
+2. Verifica status da feature em `features.md` — se `abandoned`, pula.
+3. Tenta adquirir o lock via INSERT em `evolution_log` (row com `end_at=NULL`). Se já existe uma row ativa para a feature, emite notify "already in progress" e sai com 0.
+4. Roda `learning:auto-promote --feature=X` com timeout de 5s.
+5. Ao final: UPDATE da row de lock com `end_at=now()` e `payload.state='complete'`.
+6. Emite `aioson notify --level=info --topic=learning-loop --message="distillation: N promoted, M for review, K merge candidates"`.
+
+Se `runDistillation` lança exceção, o catch grava `event_type='distillation_failed'` em `evolution_log` e engole o erro. O `feature:close` retorna 0 independentemente.
+
+`--no-distill` desativa o hook para a chamada corrente.
+
+### Fase 6 — inception-mirror-parity
+
+Validação de infraestrutura — sem superfície nova para o usuário. Garante que um projeto criado com `aioson setup` herda o mesmo loop que o repositório AIOSON usa. `npm run sync:agents:preflight` foi estendido para detectar drift nos 10 novos arquivos, nas entradas do autonomy-protocol, e nos placeholders `_archived/`.
+
+## Como as peças se conectam
+
+```
+Agente carrega regra
+  └─ aioson context:load --target=rule:authn --agent=dev
+        └─ grava execution_events (rule_loaded)
+
+Agente trabalha, feature fecha
+  └─ aioson feature:close --slug=authn-flow --verdict=PASS
+        └─ runDistillation()
+              ├─ learning:auto-promote → promove learnings maduros
+              ├─ UPDATE evolution_log (distillation complete)
+              └─ notify "N promoted, M for review"
+
+Doctor verifica periodicamente
+  └─ aioson doctor .
+        ├─ rule_staleness: regra 'authn' sem rule_loaded em 8 features
+        ├─ learning_orphans: learning 'jwt-expiry-pattern' promovido mas regra nunca carregada
+        └─ distillation_lag: 7 features fechadas, 4 distillations registradas
+
+Humano age nas hints
+  └─ aioson memory:archive --id=rule:authn --reason="obsoleta após migração OAuth"
+        ├─ notify --level=warn (antes da mutação)
+        ├─ move físico: .aioson/rules/authn.md → .aioson/rules/_archived/2026-05-14/authn.md
+        └─ evolution_log: end_at no entry anterior, novo entry com motivo
+```
+
+## Continue lendo
+
+- [Diagramas](./diagramas.md) — fluxo ASCII detalhado
+- [Como usar](./como-usar.md) — exemplos concretos
+- [Referência CLI](./comandos-cli.md) — todos os flags
+- [Doctor checks](./doctor-checks.md) — o que cada check significa

package/docs/pt/active-learning-loop/comandos-cli.md

@@ -0,0 +1,320 @@
+# Referência CLI — Active Learning Loop
+
+> Quatro novos verbos. Cada seção cobre o contrato completo: flags, comportamento, exit codes, exemplos de saída.
+
+---
+
+## `aioson context:load`
+
+Registra que um agente carregou uma regra ou brain. Grava um evento `rule_loaded` ou `brain_loaded` em `execution_events`.
+
+**Tier:** 1 (silencioso — sem output por default)
+
+```
+aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nome> [opções]
+```
+
+### Flags
+
+| Flag | Obrigatório | Descrição |
+|---|---|---|
+| `--target=<tipo>:<slug>` | sim | Tipo (`rule` ou `brain`) e identificador do target. Ex: `rule:authn-rules`, `brain:sheldon-005` |
+| `--agent=<nome>` | sim | Nome do agente que está carregando. Ex: `dev`, `qa`, `sheldon` |
+| `--batch="a,b,c"` | não | Slugs adicionais para registrar em lote (mesmo tipo e agente). Separados por vírgula |
+| `--feature=<slug>` | não | Feature associada ao carregamento (para rastreabilidade em `execution_events`) |
+| `--verbose` | não | Imprime confirmação de cada evento registrado |
+| `--json` | não | Output em JSON (`{ ok, event, target, agent }`) |
+
+### Comportamento
+
+- Cria um row em `execution_events` com `event_type='rule_loaded'` ou `event_type='brain_loaded'`, `payload_json` contendo `target_slug`, `agent`, `feature_slug` (se passado).
+- `--batch="b,c"` registra eventos adicionais para os slugs `b` e `c` com o mesmo tipo do `--target` principal.
+- Payload cap: 4KB por evento.
+- Path normalization cross-platform: slugs são normalizados antes de gravar.
+- Não valida se o arquivo da regra/brain existe — é telemetria pura.
+
+### Exit codes
+
+| Código | Quando |
+|---|---|
+| 0 | Evento(s) registrado(s) com sucesso |
+| 1 | Erro de argumento (target mal formado, agent ausente) |
+
+### Exemplos
+
+```bash
+# Básico
+aioson context:load --target=rule:authn-rules --agent=dev
+
+# Lote de 3 regras + verbose
+aioson context:load --target=rule:authn-rules --agent=dev \
+  --batch="jwt-patterns,session-management" --verbose
+
+# Associado a feature + JSON
+aioson context:load --target=brain:sheldon-006 --agent=sheldon \
+  --feature=authn-flow --json
+```
+
+---
+
+## `aioson memory:search`
+
+Busca BM25 sobre `project_learnings` (título + evidência) via SQLite FTS5.
+
+**Tier:** 1 (silencioso — não emite notify)
+
+```
+aioson memory:search "<query>" [path] [opções]
+```
+
+### Flags
+
+| Flag | Default | Descrição |
+|---|---|---|
+| `"<query>"` | — (obrigatório) | Texto de busca. Máximo 500 caracteres |
+| `path` | `.` | Diretório raiz do projeto |
+| `--limit=N` | 5 | Número máximo de resultados |
+| `--surface=<valor>` | `learnings` | Onde buscar: `rules`, `learnings`, ou `all` |
+| `--include-archived` | false | Inclui entradas com status `archived` |
+| `--json` | false | Output em JSON |
+
+### Comportamento e sanitização de query
+
+Cada token (separado por espaço) é convertido para uma frase entre aspas e ANDado com os outros:
+
+```
+"autenticação JWT"  →  '"autenticação" "JWT"'
+```
+
+Caracteres de operador FTS5 (`* ( ) ^ : + - "`) são removidos antes da conversão. Se após a sanitização a query resultar em string vazia, o comando retorna `{ ok: false, reason: 'query_unparseable' }` com exit code 0 (não é erro — é comportamento esperado).
+
+Entradas arquivadas são excluídas por default; `--include-archived` as inclui.
+
+Ranking: BM25 (menor score = mais relevante).
+
+### Exit codes
+
+| Código | Quando |
+|---|---|
+| 0 | Busca executada (mesmo que sem resultados) |
+| 1 | Erro de argumento ou falha de DB |
+
+### Exemplos de output
+
+```bash
+aioson memory:search "autenticação JWT"
+```
+
+```
+2 results for "autenticação JWT"
+
+[1] authn-refresh-token-ttl  (promoted)
+    Tokens de refresh devem ter TTL de 7 dias máximo.
+    Evidence: 4 sessions
+
+[2] jwt-audience-check  (for_review)
+    Validar claim 'aud' em todos os endpoints.
+    Evidence: 2 sessions
+```
+
+Sem resultados:
+
+```
+0 results for "xyzzy"
+```
+
+Query não parseável:
+
+```json
+{ "ok": false, "reason": "query_unparseable" }
+```
+
+Output JSON completo:
+
+```json
+{
+  "ok": true,
+  "query": "autenticação JWT",
+  "sanitized_query": "\"autenticação\" \"JWT\"",
+  "results": [
+    {
+      "id": "authn-refresh-token-ttl",
+      "title": "authn-refresh-token-ttl",
+      "status": "promoted",
+      "score": -2.14,
+      "snippet": "Tokens de refresh devem ter TTL de 7 dias máximo."
+    }
+  ],
+  "total": 2
+}
+```
+
+---
+
+## `aioson memory:archive`
+
+Arquiva uma regra, learning ou brain: move o arquivo físico para `_archived/YYYY-MM-DD/` e grava o histórico em `evolution_log`.
+
+**Tier:** 2 (notificado — emite `notify --level=warn` antes da mutação)
+
+**Humano-only:** recusa quando `AIOSON_RUNTIME_HOOK=1` está setado.
+
+```
+aioson memory:archive [path] --id=<rule|learning|brain>:<slug> --reason="<texto>" [opções]
+```
+
+### Flags
+
+| Flag | Obrigatório | Descrição |
+|---|---|---|
+| `--id=<tipo>:<slug>` | sim | Tipo e slug do target. Tipos: `rule`, `learning`, `brain` |
+| `--reason="<texto>"` | sim | Motivo do arquivamento (gravado em `evolution_log`) |
+| `--feature=<slug>` | não | Feature associada ao arquivamento (para rastreabilidade) |
+| `--dry-run` | não | Simula sem efeito colateral — imprime o que aconteceria |
+| `--json` | não | Output em JSON |
+
+### Caminhos por tipo
+
+| Tipo | Origem | Destino |
+|---|---|---|
+| `rule` | `.aioson/rules/<slug>.md` | `.aioson/rules/_archived/YYYY-MM-DD/<slug>.md` |
+| `brain` | `.aioson/brains/<slug>.brain.json` | `.aioson/brains/_archived/YYYY-MM-DD/<slug>.brain.json` |
+| `learning` | `.aioson/context/<slug>.json` | `.aioson/context/_archived/YYYY-MM-DD/<slug>.json` |
+
+Colisão de nomes no destino: sufixo `-{seq}` é adicionado automaticamente (`-1`, `-2`, etc.).
+
+### Comportamento
+
+1. Verifica `AIOSON_RUNTIME_HOOK=1` — recusa se setado.
+2. Resolve path do arquivo. Erro se não encontrado.
+3. Noop idempotente se já arquivado.
+4. Emite `notify --level=warn` antes de qualquer mutação.
+5. Operação atômica: BEGIN TRANSACTION, move físico, INSERT/UPDATE em `evolution_log`, COMMIT. Se o COMMIT falhar, tenta reverter o move físico.
+6. Registra `event_type='archived'` em `evolution_log` (entry ativo anterior recebe `end_at`).
+
+### Exit codes
+
+| Código | Quando |
+|---|---|
+| 0 | Arquivado com sucesso (ou noop se já arquivado) |
+| 0 | `--dry-run` executado |
+| 1 | Target não encontrado, AIOSON_RUNTIME_HOOK=1, falha de DB ou FS |
+
+### Exemplos
+
+```bash
+# Dry-run primeiro
+aioson memory:archive --id=rule:legacy-session-cookies \
+  --reason="substituída por JWT auth (authn-flow)" --dry-run
+
+# Execução real
+aioson memory:archive --id=rule:legacy-session-cookies \
+  --reason="substituída por JWT auth (authn-flow)"
+
+# Com feature associada
+aioson memory:archive --id=rule:legacy-session-cookies \
+  --reason="substituída por JWT auth (authn-flow)" --feature=authn-flow
+
+# JSON
+aioson memory:archive --id=rule:legacy-session-cookies \
+  --reason="obsoleta" --json
+```
+
+Output JSON:
+
+```json
+{
+  "ok": true,
+  "action": "archived",
+  "type": "rule",
+  "slug": "legacy-session-cookies",
+  "source": ".aioson/rules/legacy-session-cookies.md",
+  "dest": ".aioson/rules/_archived/2026-05-14/legacy-session-cookies.md",
+  "evolution_log_rowid": 42
+}
+```
+
+---
+
+## `aioson memory:restore`
+
+Restaura um item arquivado: move de volta para o path original e grava `event_type='restored'` em `evolution_log`.
+
+**Tier:** 2 (notificado — emite `notify --level=warn` antes da mutação)
+
+**Humano-only:** recusa quando `AIOSON_RUNTIME_HOOK=1` está setado.
+
+```
+aioson memory:restore [path] --id=<rule|learning|brain>:<slug> [opções]
+```
+
+### Flags
+
+| Flag | Obrigatório | Descrição |
+|---|---|---|
+| `--id=<tipo>:<slug>` | sim | Tipo e slug do item a restaurar |
+| `--reason="<texto>"` | não | Motivo da restauração (gravado em `evolution_log`) |
+| `--feature=<slug>` | não | Feature associada (para rastreabilidade) |
+| `--dry-run` | não | Simula sem efeito colateral |
+| `--json` | não | Output em JSON |
+
+### Comportamento
+
+1. Localiza o arquivo mais recente em `_archived/*/` que corresponde ao slug.
+2. Verifica se o path de destino original está disponível — erro se já existe um arquivo ativo com o mesmo nome.
+3. Emite `notify --level=warn` antes de qualquer mutação.
+4. Operação atômica: move físico + INSERT `event_type='restored'` + UPDATE `end_at` do entry `archived` ativo.
+
+### Exit codes
+
+| Código | Quando |
+|---|---|
+| 0 | Restaurado com sucesso |
+| 0 | `--dry-run` executado |
+| 1 | Item não encontrado em `_archived/`, path original já ocupado, AIOSON_RUNTIME_HOOK=1 |
+
+### Exemplos
+
+```bash
+# Dry-run
+aioson memory:restore --id=rule:rate-limiting-rules --dry-run
+
+# Execução real com motivo
+aioson memory:restore --id=rule:rate-limiting-rules \
+  --reason="regra ainda necessária — remoção foi prematura"
+
+# JSON
+aioson memory:restore --id=rule:rate-limiting-rules --json
+```
+
+---
+
+## `aioson feature:close` (modificado)
+
+O comando existente `feature:close` ganhou um hook de destilação ao final. A sintaxe não mudou — apenas `--no-distill` foi adicionado.
+
+```
+aioson feature:close --slug=<slug> --verdict=<PASS|FAIL|ABANDONED> [--no-distill]
+```
+
+### Flag adicionada
+
+| Flag | Descrição |
+|---|---|
+| `--no-distill` | Pula o hook de destilação para esta chamada (sem alterar o config permanente) |
+
+### Comportamento do hook
+
+- Só roda quando `--verdict=PASS` e classificação não é MICRO.
+- Foreground com timeout de 5s (configurável em `learning-loop.json`).
+- Exit code sempre 0, mesmo que a destilação falhe.
+- Emite exatamente 1 notify `--level=info --topic=learning-loop` com o resumo.
+- Grava resultado em `evolution_log` (`auto_distillation` ou `distillation_failed`).
+
+---
+
+## Continue lendo
+
+- [Como usar](./como-usar.md) — exemplos end-to-end
+- [Doctor checks](./doctor-checks.md) — o que os checks do doctor significam
+- [Troubleshooting](./troubleshooting.md) — problemas conhecidos