@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/pt/active-learning-loop/como-usar.md

@@ -0,0 +1,313 @@
+# Como usar o Active Learning Loop
+
+> Exemplos concretos. Cada seção resolve uma necessidade real do dia a dia.
+
+---
+
+## 1. Pesquisar um learning existente
+
+Você quer saber se o projeto já tem algum learning sobre autenticação antes de criar uma regra nova:
+
+```bash
+aioson memory:search "autenticação"
+```
+
+Saída típica:
+
+```
+3 results for "autenticação" (BM25)
+
+[1] authn-refresh-token-ttl  (promoted)
+    Tokens de refresh devem ter TTL de 7 dias máximo conforme decisão em auth-flow feature.
+    Evidence: 4 sessions
+
+[2] jwt-audience-check  (for_review)
+    Validar claim 'aud' em todos os endpoints. Encontrado em 2 sessões de security-audit.
+    Evidence: 2 sessions
+
+[3] oauth-state-param  (active)
+    State parameter obrigatório em fluxo OAuth para prevenir CSRF.
+    Evidence: 3 sessions
+```
+
+Filtrar só learnings promovidos:
+
+```bash
+aioson memory:search "autenticação" --surface=learnings --limit=10
+```
+
+Buscar em regras também:
+
+```bash
+aioson memory:search "autenticação" --surface=all
+```
+
+Incluir entradas já arquivadas (para auditoria histórica):
+
+```bash
+aioson memory:search "autenticação" --include-archived
+```
+
+Saída em JSON (para scripts):
+
+```bash
+aioson memory:search "autenticação" --json
+```
+
+```json
+{
+  "ok": true,
+  "query": "autenticação",
+  "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..."
+    }
+  ],
+  "total": 3
+}
+```
+
+**Nota sobre busca:** a query usa token-AND — cada palavra separada por espaço deve aparecer no documento. `"autenticação JWT"` encontra documentos que contêm ambas as palavras, não necessariamente a frase exata. Operadores como AND/OR/NOT são removidos — é busca por palavras-chave, não linguagem de query.
+
+---
+
+## 2. Declarar que um agente carregou uma regra
+
+Quando você (ou um agente que você está escrevendo) carrega uma regra no início da sessão, declare isso para o sistema de telemetria:
+
+```bash
+aioson context:load --target=rule:authn-rules --agent=dev
+```
+
+Para carregar vários de uma vez (recomendado — minimiza overhead):
+
+```bash
+aioson context:load --target=rule:authn-rules --agent=dev --batch="jwt-patterns,oauth-state,session-management"
+```
+
+Associar ao carregamento de uma feature em andamento:
+
+```bash
+aioson context:load --target=brain:sheldon-005 --agent=sheldon --feature=authn-flow
+```
+
+O comando é tier-1 silencioso — não imprime nada por default. Use `--verbose` se quiser confirmar:
+
+```bash
+aioson context:load --target=rule:authn-rules --agent=dev --verbose
+# rule_loaded: authn-rules (agent: dev)
+```
+
+Use `--json` para integrar em scripts:
+
+```bash
+aioson context:load --target=rule:authn-rules --agent=dev --json
+# {"ok":true,"event":"rule_loaded","target":"authn-rules","agent":"dev"}
+```
+
+---
+
+## 3. O que `feature:close` faz agora
+
+O fluxo existente continua igual — a destilação é adicionada ao final:
+
+```bash
+aioson feature:close --slug=authn-flow --verdict=PASS
+```
+
+Saída esperada (além da saída normal do feature:close):
+
+```
+[existente] Gate validation: OK
+[existente] Dossier finalized: .aioson/context/features/authn-flow/
+[existente] features.md updated: authn-flow → PASS
+
+ℹ [learning-loop] distillation: 2 promoted, 1 for review, 0 merge candidates
+```
+
+O que aconteceu nos bastidores:
+1. Leu a classificação do PRD — SMALL, então prosseguiu.
+2. Adquiriu o lock de distilação em `evolution_log`.
+3. Rodou `learning:auto-promote --feature=authn-flow` — 2 learnings cruzaram o threshold e viraram regras.
+4. 1 learning ficou em `for_review` — ainda não tem evidências suficientes.
+5. Gravou o resultado em `evolution_log` e emitiu o notify.
+
+**Desativar por chamada:**
+
+```bash
+aioson feature:close --slug=authn-flow --verdict=PASS --no-distill
+```
+
+**Projeto MICRO** — a destilação é pulada automaticamente, sem necessidade de `--no-distill`:
+
+```
+[existente] Gate validation: OK
+...
+ℹ [learning-loop] skipped: MICRO classification
+```
+
+---
+
+## 4. Arquivar uma regra obsoleta
+
+O `doctor` reportou staleness na regra `legacy-session-cookies`. Você quer arquivá-la:
+
+```bash
+# Simule primeiro para ver o que vai acontecer
+aioson memory:archive --id=rule:legacy-session-cookies --reason="substituída por JWT-based auth (feature authn-flow)" --dry-run
+```
+
+Saída do dry-run:
+
+```
+[dry-run] would archive:
+  source:  .aioson/rules/legacy-session-cookies.md
+  dest:    .aioson/rules/_archived/2026-05-14/legacy-session-cookies.md
+  reason:  substituída por JWT-based auth (feature authn-flow)
+  evolution_log: 1 entry to close, 1 entry to insert
+```
+
+Se o dry-run está correto, execute:
+
+```bash
+aioson memory:archive --id=rule:legacy-session-cookies --reason="substituída por JWT-based auth (feature authn-flow)"
+```
+
+Saída:
+
+```
+⚠ [memory-archive] archiving rule:legacy-session-cookies — legacy-session-cookies.md
+archived: .aioson/rules/_archived/2026-05-14/legacy-session-cookies.md
+```
+
+Associar ao fechamento de uma feature (opcional, mas recomendado para rastreabilidade):
+
+```bash
+aioson memory:archive --id=rule:legacy-session-cookies --reason="..." --feature=authn-flow
+```
+
+---
+
+## 5. Arquivar um learning ou brain
+
+O mesmo comando funciona para os três tipos — `rule`, `learning`, e `brain`:
+
+```bash
+# Arquivar um learning
+aioson memory:archive --id=learning:jwt-draft-1 --reason="superado pela versão promovida em authn-flow"
+
+# Arquivar um brain
+aioson memory:archive --id=brain:sheldon-003 --reason="versão 003 foi substituída por sheldon-006"
+```
+
+---
+
+## 6. Restaurar um item arquivado
+
+Você arquivou a regra `rate-limiting-rules` mas percebeu que ainda é usada:
+
+```bash
+aioson memory:restore --id=rule:rate-limiting-rules
+```
+
+Saída:
+
+```
+⚠ [memory-restore] restoring rule:rate-limiting-rules
+restored: .aioson/rules/rate-limiting-rules.md
+```
+
+Com motivo (recomendado para rastreabilidade):
+
+```bash
+aioson memory:restore --id=rule:rate-limiting-rules --reason="regra ainda necessária — removal foi precipitado"
+```
+
+Dry-run disponível também:
+
+```bash
+aioson memory:restore --id=rule:rate-limiting-rules --dry-run
+```
+
+---
+
+## 7. Verificar o estado do loop via doctor
+
+```bash
+aioson doctor .
+```
+
+Se o loop está saudável:
+
+```
+[OK] living-memory:rule_staleness
+[OK] living-memory:learning_orphans
+[OK] living-memory:distillation_lag
+```
+
+Se há problemas:
+
+```
+[WARN] living-memory:rule_staleness (2 stale rules)
+  Rule 'legacy-session-cookies' has 0 rule_loaded events in last 7 features.
+  Rule 'old-rate-limit-policy' has 0 rule_loaded events in last 7 features.
+  Hint: consider archiving:
+    aioson memory:archive --id=rule:legacy-session-cookies --reason="..."
+    aioson memory:archive --id=rule:old-rate-limit-policy --reason="..."
+
+[WARN] living-memory:learning_orphans (1 orphan)
+  Learning 'jwt-expiry-pattern' was promoted but its target rule had no rule_loaded after promotion.
+  Hint: aioson memory:archive --id=learning:jwt-expiry-pattern --reason="..."
+
+[WARN] living-memory:distillation_lag
+  8 features closed, 5 auto_distillation events recorded.
+  Hint: Run `aioson feature:close --slug=<slug> --verdict=PASS` on pending features,
+        or check if distillation is failing silently (see evolution_log).
+```
+
+Veja [Doctor checks](./doctor-checks.md) para o que cada check significa e como agir.
+
+---
+
+## 8. Inspecionar o `evolution_log` diretamente
+
+Para auditoria ou troubleshooting, consulte o SQLite diretamente:
+
+```bash
+sqlite3 .aioson/runtime/aios.sqlite \
+  "SELECT target_type, target_id, event_type, start_at, end_at, reason
+   FROM evolution_log
+   ORDER BY start_at DESC
+   LIMIT 10;"
+```
+
+Verificar o lock de distilação ativo:
+
+```bash
+sqlite3 .aioson/runtime/aios.sqlite \
+  "SELECT feature_slug, start_at, payload_json
+   FROM evolution_log
+   WHERE event_type='auto_distillation' AND end_at IS NULL;"
+```
+
+Histórico de uma regra específica:
+
+```bash
+sqlite3 .aioson/runtime/aios.sqlite \
+  "SELECT event_type, start_at, end_at, reason, actor
+   FROM evolution_log
+   WHERE target_type='rule' AND target_id='authn-rules'
+   ORDER BY start_at;"
+```
+
+---
+
+## Continue lendo
+
+- [Referência CLI](./comandos-cli.md) — todos os flags documentados
+- [Doctor checks](./doctor-checks.md) — o que os checks significam e como agir
+- [Troubleshooting](./troubleshooting.md) — problemas conhecidos

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

@@ -0,0 +1,225 @@
+# Diagramas — Active Learning Loop em ASCII
+
+> Fluxos canônicos da feature. ASCII porque renderiza em qualquer terminal, qualquer Markdown viewer, e qualquer diff.
+
+---
+
+## 1. `feature:close` → destilação → `evolution_log` → `doctor`
+
+```
+aioson feature:close --slug=minha-feature --verdict=PASS
+  │
+  ├── [existente] gate validation
+  ├── [existente] dossier finalize
+  ├── [existente] features.md update
+  │
+  └── [NOVO] runHookOnFeatureClose()
+        │
+        ├── Lê PRD frontmatter classification
+        │   └── MICRO? → notify "skipped: MICRO classification" → exit 0
+        │
+        ├── Lê features.md status
+        │   └── abandoned? → skip silencioso → exit 0
+        │
+        ├── --no-distill passado? → skip → exit 0
+        │
+        ├── Tenta adquirir lock:
+        │   INSERT INTO evolution_log
+        │     (feature_slug='minha-feature', event_type='auto_distillation',
+        │      start_at=now(), end_at=NULL, actor='auto', payload='{"state":"start"}')
+        │   └── row ativa já existe? → notify "already in progress" → exit 0
+        │
+        ├── setTimeout(5000ms) → AbortController.abort()
+        │
+        ├── try {
+        │     learning:auto-promote --feature=minha-feature
+        │       └── retorna { promoted: N, for_review: M }
+        │   }
+        │   catch (err) {
+        │     UPDATE evolution_log SET event_type='distillation_failed',
+        │       end_at=now(), payload='{"error":"...", "phase":"auto-promote"}'
+        │     // engole exceção — não relança
+        │   }
+        │
+        ├── UPDATE evolution_log SET end_at=now(),
+        │     payload='{"state":"complete","promoted":N,"review":M,"merge":0,"duration_ms":D}'
+        │
+        ├── aioson notify --level=info --topic=learning-loop
+        │     --message="distillation: N promoted, M for review, 0 merge candidates"
+        │
+        └── exit 0  ← sempre 0, independente de falha na destilação
+```
+
+---
+
+## 2. Padrão de lock (DD-3 — dois terminais simultâneos)
+
+```
+Terminal A                              Terminal B
+──────────────────────────────────      ──────────────────────────────────
+feature:close --slug=X                  feature:close --slug=X (simultâneo)
+
+SELECT 1 FROM evolution_log
+  WHERE feature_slug='X'
+    AND event_type='auto_distillation'
+    AND end_at IS NULL
+  → 0 rows
+
+INSERT row (end_at=NULL) → rowid=42
+                                        SELECT 1 ... → 1 row (rowid=42)
+                                        notify "already in progress" → exit 0
+
+(distillação roda ~2-3s)
+
+UPDATE rowid=42 SET end_at=now()
+notify "N promoted, M for review"
+exit 0
+```
+
+---
+
+## 3. `memory:archive` — operação atômica com rollback
+
+```
+aioson memory:archive --id=rule:authn --reason="obsoleta após OAuth"
+  │
+  ├── Verifica AIOSON_RUNTIME_HOOK=1 → recusa (tier-2 humano-only)
+  │
+  ├── Resolve path: .aioson/rules/authn.md
+  │   └── não existe? → erro: "target not found"
+  │
+  ├── Já arquivada? → noop (idempotente)
+  │
+  ├── aioson notify --level=warn --topic=memory-archive
+  │     --message="archiving rule:authn — authn.md"
+  │
+  ├── BEGIN TRANSACTION (SQLite)
+  │
+  ├── move físico:
+  │   .aioson/rules/authn.md
+  │     → .aioson/rules/_archived/2026-05-14/authn.md
+  │   └── erro no move → ROLLBACK → exit 1
+  │
+  ├── INSERT evolution_log (event_type='archived', start_at=now(), end_at=NULL,
+  │     target_type='rule', target_id='authn', reason='obsoleta após OAuth',
+  │     actor='human', feature_slug=<--feature se passado>)
+  │
+  ├── UPDATE evolution_log SET end_at=now()
+  │     WHERE target_id='authn' AND end_at IS NULL AND event_type != 'archived'
+  │   (fecha entry ativo anterior)
+  │
+  ├── COMMIT
+  │   └── erro no COMMIT → tenta reverter move físico → exit 1
+  │
+  └── { ok: true, path: "_archived/2026-05-14/authn.md" }
+```
+
+---
+
+## 4. Ciclo do `doctor` com os novos checks
+
+```
+$ aioson doctor .
+        │
+        ▼
+┌──────────────────────────────────────────────────────────────────┐
+│ runDoctor(targetDir)                                             │
+│  └─ checks[]                                                     │
+│      ├─ ... [checks existentes severity='error'] ...             │
+│      ├─ living-memory:bootstrap_coverage   [severity: warning]   │
+│      ├─ living-memory:features_dir         [severity: warning]   │
+│      ├─ living-memory:claude_commands      [severity: warning]   │
+│      ├─ living-memory:version_drift        [severity: warning]   │
+│      ├─ living-memory:permissions_in_sync  [severity: warning]   │
+│      │                                                           │
+│      ├─ [NOVO] living-memory:rule_staleness   [severity: warning]│
+│      │    └─ query: execution_events WHERE event_type='rule_loaded'
+│      │           AND context LIKE 'feature=%' GROUP BY slug
+│      │           → stale se nenhum hit nas últimas N features     │
+│      │                                                           │
+│      ├─ [NOVO] living-memory:learning_orphans [severity: warning]│
+│      │    └─ query: project_learnings WHERE status='promoted'    │
+│      │           LEFT JOIN execution_events (rule_loaded, after  │
+│      │           promoted_at) → orphan se join retorna NULL      │
+│      │                                                           │
+│      └─ [NOVO] living-memory:distillation_lag [severity: warning]│
+│           └─ count(features fechadas) vs count(auto_distillation │
+│              em evolution_log) → lag se fechadas > distillations │
+│                                                                  │
+│  report.ok = errorCount === 0                                    │
+│  (warnings somam em failedCount mas não afetam ok)              │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 5. Validity-window no `evolution_log`
+
+```
+Estado inicial (regra ativa):
+─────────────────────────────────────────────────────────────────
+ rowid | target_type | target_id | event_type | start_at   | end_at
+   1   |   'rule'    |  'authn'  |  'created' | 2026-01-10 | NULL   ← ativo
+
+memory:archive roda:
+─────────────────────────────────────────────────────────────────
+ rowid | target_type | target_id | event_type | start_at   | end_at
+   1   |   'rule'    |  'authn'  |  'created' | 2026-01-10 | 2026-05-14  ← fechado
+   2   |   'rule'    |  'authn'  |  'archived'| 2026-05-14 | NULL        ← ativo
+
+memory:restore roda:
+─────────────────────────────────────────────────────────────────
+ rowid | target_type | target_id | event_type | start_at   | end_at
+   1   |   'rule'    |  'authn'  |  'created' | 2026-01-10 | 2026-05-14
+   2   |   'rule'    |  'authn'  |  'archived'| 2026-05-14 | 2026-05-14  ← fechado
+   3   |   'rule'    |  'authn'  |  'restored'| 2026-05-14 | NULL        ← ativo
+
+Invariante: start_at e reason nunca mudam após INSERT.
+           Apenas end_at é atualizado, e só uma vez.
+```
+
+---
+
+## 6. FTS5 — fluxo de sincronização e busca
+
+```
+project_learnings (tabela normal)
+        │
+        │ triggers SQL (INSERT, UPDATE, DELETE)
+        ▼
+project_learnings_fts (virtual table FTS5)
+   colunas indexadas: title, evidence
+   ranking: BM25 (default)
+        │
+        │ aioson memory:search "autenticação JWT"
+        ▼
+  Sanitização da query:
+    input:  "autenticação JWT"
+    tokens: ["autenticação", "JWT"]
+    FTS5:   '"autenticação" "JWT"'  ← token-AND, cada token é frase literal
+        │
+        ▼
+  SELECT l.*, fts.rank
+  FROM project_learnings_fts fts
+  JOIN project_learnings l ON l.rowid = fts.rowid
+  WHERE fts MATCH '"autenticação" "JWT"'
+    AND l.status != 'archived'   ← excluídas por default
+  ORDER BY fts.rank              ← BM25 (menor = mais relevante)
+  LIMIT 5
+        │
+        ▼
+  Resultado:
+  [1] autenticação-jwt-refresh (score: -2.14)
+      "Tokens JWT de refresh devem ter TTL de 7 dias..."
+  [2] jwt-audience-validation (score: -1.87)
+      ...
+```
+
+---
+
+## Continue lendo
+
+- [O que é o Active Learning Loop](./ativo-learning-loop.md) — conceito e fases
+- [Como usar](./como-usar.md) — exemplos concretos
+- [Doctor checks](./doctor-checks.md) — o que os checks significam
+- [Troubleshooting](./troubleshooting.md) — problemas conhecidos

package/docs/pt/active-learning-loop/doctor-checks.md

@@ -0,0 +1,151 @@
+# Doctor checks — curadoria de memória
+
+> Os três novos checks aparecem em `aioson doctor .` com `severity='warning'`. Warnings não afetam `ok=true` — o projeto continua funcionando. Mas cada um representa uma lacuna de curadoria que, se ignorada, torna a memória do projeto menos útil ao longo do tempo.
+
+---
+
+## Como os checks aparecem
+
+```bash
+aioson doctor .
+```
+
+Quando tudo está saudável:
+
+```
+[OK] living-memory:rule_staleness
+[OK] living-memory:learning_orphans
+[OK] living-memory:distillation_lag
+```
+
+Quando há lacunas:
+
+```
+[WARN] living-memory:rule_staleness (2 stale rules)
+  ...
+[WARN] living-memory:learning_orphans (1 orphan)
+  ...
+[WARN] living-memory:distillation_lag
+  ...
+```
+
+Os três checks só rodam em projetos com classificação **SMALL** ou **MEDIUM**. Projetos MICRO optam para fora automaticamente — nenhum dos três será exibido.
+
+---
+
+## `living-memory:rule_staleness`
+
+**O que detecta:** regras (arquivos em `.aioson/rules/`) que não tiveram nenhum evento `rule_loaded` nas últimas N features fechadas.
+
+**Por que importa:** se nenhum agente carregou uma regra nas últimas N features, ela provavelmente perdeu relevância — o contexto do projeto mudou, a regra foi superada, ou simplesmente nunca foi usada. Regras obsoletas ocupam espaço no contexto dos agentes sem agregar valor.
+
+**Como N é calculado:**
+
+```
+N = max(5, ceil(média de dias entre as últimas 5 features / 7))
+```
+
+Projetos com features frequentes (1 por semana) têm N = 5. Projetos com ritmo mais lento (1 por mês) têm N maior — a janela se expande para cobrir o mesmo período de tempo real.
+
+`staleness_window_features_min: 5` em `learning-loop.json` define o piso.
+
+**Saída típica:**
+
+```
+[WARN] living-memory:rule_staleness (2 stale rules)
+  Rule 'legacy-session-cookies' has 0 rule_loaded events in last 7 features.
+  Rule 'old-rate-limit-policy' has 0 rule_loaded events in last 7 features.
+  Hint:
+    aioson memory:archive --id=rule:legacy-session-cookies --reason="<motivo>"
+    aioson memory:archive --id=rule:old-rate-limit-policy --reason="<motivo>"
+```
+
+**Como agir:**
+
+1. Verifique se a regra ainda é relevante para o projeto atual.
+2. Se não for: use o hint do doctor para arquivar.
+3. Se ainda for relevante mas não está sendo carregada: adicione `context:load` aos agentes que deveriam usá-la.
+4. Se você não tem certeza: arquive com `--dry-run` para ver o impacto antes de executar.
+
+**Falso positivo:** o check só funciona quando os agentes estão usando `aioson context:load` para declarar carregamentos. Se seus agentes customizados não fazem isso, o check vai reportar tudo como stale. Solução: adicionar `aioson context:load` ao início das sessões.
+
+---
+
+## `living-memory:learning_orphans`
+
+**O que detecta:** learnings com `status='promoted'` cujo target rule não teve nenhum evento `rule_loaded` após a data de promoção.
+
+**Por que importa:** quando um learning é promovido, ele gerou (ou deveria ter gerado) uma regra. Se essa regra nunca foi carregada por nenhum agente desde a promoção, significa uma de duas coisas: ou a regra nunca chegou a ser criada (falha no fluxo de promoção), ou foi criada mas os agentes não a estão consultando. De qualquer forma, é uma lacuna.
+
+**Saída típica:**
+
+```
+[WARN] living-memory:learning_orphans (1 orphan)
+  Learning 'jwt-expiry-pattern' (promoted 2026-04-10) — target rule had no
+  rule_loaded events after promotion date.
+  Hint:
+    aioson memory:archive --id=learning:jwt-expiry-pattern --reason="<motivo>"
+```
+
+**Como agir:**
+
+1. Verifique se a regra correspondente existe em `.aioson/rules/`.
+2. Se a regra não existe: o learning foi promovido mas nunca materializou uma regra — crie a regra manualmente ou arquive o learning.
+3. Se a regra existe mas nunca foi carregada: adicione `context:load` onde apropriado, ou arquive a regra se ela não é mais relevante.
+4. Se o learning foi promovido erroneamente: arquive-o.
+
+---
+
+## `living-memory:distillation_lag`
+
+**O que detecta:** projetos onde o número de features fechadas é significativamente maior que o número de eventos `auto_distillation` registrados em `evolution_log`. Threshold: 5+ features fechadas com menos destilações do que fechamentos.
+
+**Por que importa:** se `feature:close` está sendo chamado mas a destilação não está rodando, o loop está silenciosamente quebrado. Os learnings estão acumulando sem destilação. Pode ser que `--no-distill` esteja sendo usado consistentemente, que o hook esteja falhando silenciosamente, ou que o projeto tenha migrado para o framework depois de fechar várias features.
+
+**Saída típica:**
+
+```
+[WARN] living-memory:distillation_lag
+  8 features closed, 5 auto_distillation events recorded.
+  Hint: check if distillation is failing silently:
+    sqlite3 .aioson/runtime/aios.sqlite \
+      "SELECT feature_slug, payload_json FROM evolution_log \
+       WHERE event_type='distillation_failed' ORDER BY start_at DESC LIMIT 5;"
+  Or run distillation manually on recent features.
+```
+
+**Como agir:**
+
+1. Execute o comando SQLite do hint para ver se há falhas silenciosas registradas.
+2. Se há `distillation_failed`: veja o `payload_json.error_phase` para entender onde está falhando e consulte [Troubleshooting](./troubleshooting.md).
+3. Se não há falhas mas há lag: provavelmente as features foram fechadas com `--no-distill` ou antes de o hook existir. O lag vai diminuir naturalmente à medida que novas features forem fechadas.
+4. Se o projeto é novo no framework mas tinha features antigas: o lag é esperado e vai se resolver.
+
+---
+
+## Resumo rápido
+
+| Check | Sinal problemático | Ação imediata |
+|---|---|---|
+| `rule_staleness` | Regra sem `rule_loaded` em N features | Verificar relevância → arquivar ou adicionar `context:load` |
+| `learning_orphans` | Learning promovido, regra nunca carregada | Verificar se regra existe → criar, arquivar learning, ou adicionar `context:load` |
+| `distillation_lag` | Mais features fechadas do que destilações | Inspecionar `distillation_failed` em `evolution_log` |
+
+---
+
+## Sobre a severidade `warning`
+
+Os três checks são `severity='warning'`, não `severity='error'`. Isso significa:
+
+- `report.ok` continua `true` mesmo com warnings.
+- `report.failedCount` inclui warnings.
+- Não há `doctor --fix` automático para esses checks — as ações são semânticas e requerem julgamento humano.
+- O hint de cada check inclui o comando exato para executar quando você decidir agir.
+
+---
+
+## Continue lendo
+
+- [Como usar](./como-usar.md) — exemplos de archive e restore
+- [Referência CLI](./comandos-cli.md) — flags de `memory:archive` e `memory:restore`
+- [Troubleshooting](./troubleshooting.md) — lock preso, falhas de destilação