@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/pt/4-agentes/tester.md

@@ -0,0 +1,105 @@
+# @tester — Engenharia de testes para apps que já existem
+
+> **Para quem é:** quem tem um app rodando sem testes adequados, ou com testes que parecem cobrir mas não cobrem o que importa.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - A diferença entre `@tester` e `@qa`
+> - O que é coverage quality tier e test smell audit
+
+---
+
+## Para que serve
+
+`@qa` valida se uma feature específica passou nos critérios de aceitação. `@tester` é diferente: ele entra quando o **app como um todo** precisa de engenharia de testes — seja porque foi construído sem testes, porque é um projeto legado, ou porque o `@qa` identificou lacunas em três ou mais módulos.
+
+Ele não implementa features. Não revisa produto. Testa o que existe.
+
+Duas capacidades recentes que o diferenciam:
+
+**Coverage quality tier:** não apenas mede "quantos % de linhas são cobertas", mas classifica a *qualidade* da cobertura. Um teste que chama a função mas não faz nenhuma assertion é cobertura sem qualidade. O tier vai de BAIXO a ALTO.
+
+**Test smell audit:** detecta padrões que fazem os testes serem enganosos — testes que sempre passam, assertions muito genéricas, dependências ocultas entre testes, testes que testam implementação em vez de comportamento.
+
+---
+
+## Quando invocar
+
+- App foi construído sem testes adequados e você quer cobri-lo agora.
+- `@qa` identificou lacunas de cobertura em 3+ módulos.
+- Você está entrando num projeto legado e quer saber o que tem e o que falta.
+- Você suspeita que os testes existentes são de baixa qualidade (smell audit).
+
+---
+
+## Quando NÃO invocar
+
+- Você está fazendo uma feature nova → use o ciclo normal com `@qa` no final.
+- Você quer revisão adversarial de segurança → use `@pentester`.
+- Os testes existentes são bons e você só quer validar a última feature → use `@qa`.
+
+---
+
+## Diálogo típico
+
+```
+Você > @tester
+
+@tester > Lendo project.context.md... Node.js, test_runner: node:test.
+          Lendo arquivos de teste existentes...
+          
+          Coverage quality tier atual: BAIXO (23% de linhas, mas 60% das assertions são genéricas)
+          
+          Test smell detectado:
+          - tests/payment.test.js linha 34: assert(result) — não verifica valor específico
+          - tests/order.test.js: 3 testes dependem de estado compartilhado (ordem importa)
+          
+          Módulos críticos sem cobertura (ordem de prioridade):
+          1. src/services/payment-service.js — lógica de cobrança, zero testes
+          2. src/middleware/auth.js — autenticação, zero testes
+          3. src/routes/checkout.js — 1 teste superficial
+          
+          Estratégia proposta: cobrir payment-service e auth primeiro.
+          Estimativa: 12 testes novos → tier MÉDIO.
+          
+          test-inventory.md criado em .aioson/context/test-inventory.md
+          Prosseguir?
+Você > Sim
+
+@tester > [implementa testes]
+          12 testes criados. 11 passaram. 1 revelou bug real em payment-service linha 87.
+          Registrado em test-inventory.md para roteamento ao @qa.
+```
+
+---
+
+## Saídas em disco
+
+| Arquivo | Conteúdo |
+|---|---|
+| `.aioson/context/test-inventory.md` | Inventário de testes: o que existe, qualidade, gaps |
+| Arquivos de teste | onde o projeto já os tem |
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/context/project.context.md` — stack, `test_runner`, `classification`
+- `.aioson/context/requirements-{slug}.md` — ACs para nomear testes (`AC-{slug}-{N}`)
+- `.aioson/context/conformance-{slug}.yaml` — contrato de conformidade (MEDIUM)
+- `.aioson/installed-skills/aioson-spec-driven/SKILL.md` — se existir
+- `.aioson/rules/` — regras com `agents: tester`
+- `security-findings-{slug}.json` — como input de risco para priorizar (não cria findings)
+
+---
+
+## Handoff típico
+
+- **Vem de:** `@qa` (que identificou gaps) ou você diretamente
+- **Vai para:** `@qa` (para validar os novos testes) ou `@pentester` (se encontrou indícios de segurança)
+
+---
+
+## Próximo passo
+
+- [Ficha do @qa](./qa.md) — complementar ao `@tester`
+- [Ficha do @pentester](./pentester.md) — se a auditoria revelar indícios de segurança

package/docs/pt/4-agentes/ux-ui.md

@@ -0,0 +1,110 @@
+# @ux-ui — Especifique a interface antes de implementá-la
+
+> **Para quem é:** quem trabalha em projetos MEDIUM com frontend e quer garantir que UI/UX foi pensada antes do código.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - Quando `@ux-ui` entra no fluxo e o que ele entrega
+> - Como ele usa o design skill do projeto
+
+---
+
+## Para que serve
+
+Quando o dev implementa a UI sem especificação, ele toma decisões de design no meio do código: escolhe um espaçamento, inventa um tom de cor, estrutura o formulário do jeito que achou certo. O resultado é inconsistente, custa refatoração e não respeita o sistema visual do produto.
+
+`@ux-ui` existe para separar "o que a interface faz" (responsabilidade dele) de "como o código implementa" (responsabilidade do `@dev`). Ele produz uma especificação de componentes, tokens e fluxos que o `@dev` segue como contrato.
+
+Ele é guiado pelo design skill do projeto — se `clean-saas-ui` estiver configurado, ele usa apenas esse sistema. Se nenhum skill estiver definido, ele para e pergunta antes de avançar.
+
+---
+
+## Quando invocar
+
+- Projetos MEDIUM com UI, após `@architect`.
+- Quando você quer redesenhar uma tela existente de forma estruturada.
+- Quando quer documentar o design system de um projeto que já tem UI mas sem spec.
+- Quando a auditoria de UI/UX é necessária (modo `audit`).
+
+---
+
+## Quando NÃO invocar
+
+- Projeto MICRO ou SMALL sem UI complexa → `@dev` pode usar o design skill direto.
+- A feature é backend puro (API, script) → não há UI para especificar.
+- Você quer clonar o design de um site existente → use `@site-forge`.
+
+---
+
+## Diálogo típico
+
+```
+Você > @ux-ui
+
+@ux-ui > Lendo project.context.md... design_skill: "clean-saas-ui".
+          Carregando .aioson/skills/design/clean-saas-ui/SKILL.md...
+          
+          Feature: checkout-stripe. Lendo prd-checkout-stripe.md e architecture.md...
+          
+          Telas necessárias:
+          1. /checkout — formulário de pagamento
+          2. /checkout/success — confirmação
+          3. /checkout/error — falha de pagamento
+          
+          Especificando tela /checkout:
+          - Input "Número do cartão": token input-default, validação em tempo real
+          - Input "Validade" + "CVV": side-by-side, tokens spacing-sm
+          - Button "Pagar R$ {total}": variant primary-lg, loading state
+          - Error state: inline, cor error-500 do token de cores
+          
+          Artefatos criados:
+          - .aioson/context/design-doc-checkout-stripe.md
+          - .aioson/context/ui-spec.md (atualizado)
+          Próximo: @pm (MEDIUM).
+```
+
+---
+
+## Saídas em disco
+
+| Arquivo | Conteúdo |
+|---|---|
+| `.aioson/context/design-doc.md` ou `design-doc-{slug}.md` | Spec de UI/UX da feature |
+| `.aioson/context/ui-spec.md` | Spec de componentes e tokens |
+| `.aioson/context/discovery.md` | Contribuição de discovery de UX |
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/context/project.context.md` — detecta `design_skill`
+- `.aioson/skills/design/{design_skill}/SKILL.md` — **único** sistema visual carregado
+- `.aioson/context/prd-{slug}.md`, `discovery.md`, `architecture.md`
+- `.aioson/context/spec-{slug}.md` (feature mode)
+- `.aioson/rules/` — regras com `agents: ux-ui`
+
+---
+
+## Comandos CLI relacionados
+
+```bash
+# Ver qual design skill está ativo
+cat .aioson/context/project.context.md | grep design_skill
+
+# Listar skills instalados
+ls .aioson/skills/design/
+```
+
+---
+
+## Handoff típico
+
+- **Vem de:** `@architect`
+- **Vai para:** `@pm` (MEDIUM)
+
+---
+
+## Próximo passo
+
+- [Ficha do @pm](./pm.md) — próximo em MEDIUM
+- [Decisões iniciais: qual design skill escolher](../2-comecar/decisoes-iniciais.md#escolhendo-o-design-system)
+- [Glossário: Design Skill](../1-entender/glossario.md#design-skill)

package/docs/pt/4-agentes/validator.md

@@ -0,0 +1,118 @@
+# @validator — Gate final: a feature está realmente pronta?
+
+> **Para quem é:** equipes que usam contratos binários de sucesso (harness-contract) e querem um veredicto imparcial antes de fechar uma feature.
+> **Tempo de leitura:** 3 min.
+> **O que você vai sair sabendo:**
+> - O que é um harness-contract e como `@validator` o verifica
+> - Por que ele nunca lê o histórico de outros agentes
+
+---
+
+## Para que serve
+
+O `@qa` valida comportamento. O `@validator` valida **se o contrato binário foi cumprido** — critérios objetivos do tipo "arquivo X existe", "teste Y passa", "API retorna Z". Ele é o gatekeeper final que decide se a feature pode ser marcada como concluída.
+
+A distinção deliberada: ele opera em **sandbox de contexto**. Não lê histórico de chat de `@dev`, `@analyst`, ou `@architect`. Lê apenas o contrato (`harness-contract.json`), o estado atual (`progress.json`), e o output de ferramentas (linters, test runners). Isso garante imparcialidade — ele não "sabe" o que foi prometido no chat, só o que o contrato exige.
+
+Seu output é sempre um JSON estruturado com `overall_score: 1` (todos passaram) ou `overall_score: 0` (algum critério falhou).
+
+---
+
+## Quando invocar
+
+- Após `@qa`, quando a feature usa um `harness-contract.json`.
+- Quando você quer um veredicto independente antes do `feature:close`.
+- Em pipelines automatizados onde precisa de um resultado parseável.
+
+---
+
+## Quando NÃO invocar
+
+- A feature não tem `harness-contract.json` → use apenas `@qa`.
+- Você quer sugestões de melhoria → `@validator` não dá sugestões, só verifica.
+- Você quer revisão de código ou arquitetura → use `@sheldon`.
+
+---
+
+## Diálogo típico
+
+```
+Você > @validator
+
+@validator > Localizando harness-contract.json para feature checkout-stripe...
+             Encontrado em .aioson/plans/checkout-stripe/harness-contract.json
+             
+             Critérios binários (5):
+             C1: src/models/payment.js existe
+             C2: db/migrations/add-payment-table.sql existe
+             C3: npm test → 0 falhas
+             C4: POST /checkout retorna 201 (smoke test)
+             C5: dev-state.md status = "implemented"
+             
+             Verificando...
+             C1: PASS — ls src/models/payment.js ✓
+             C2: PASS — ls db/migrations/add-payment-table.sql ✓
+             C3: PASS — npm test → 4 passed, 0 failed ✓
+             C4: PASS — curl POST /checkout → 201 ✓
+             C5: PASS — status: "implemented" ✓
+             
+             {
+               "overall_score": 1,
+               "ready_for_done_gate": true
+             }
+```
+
+---
+
+## Saídas em disco
+
+| Arquivo | Conteúdo |
+|---|---|
+| `.aioson/plans/{slug}/last-validator-output.json` | Veredicto JSON emitido pelo agente — consumido pelo `harness:apply-validation` |
+| `.aioson/plans/{slug}/validator-runs/{ISO}.json` | Arquivamento dos veredictos consumidos (após apply) |
+| `.aioson/plans/{slug}/progress.json` | Estado pós-aplicação: `last_error`, `ready_for_done_gate`, `circuit_state` |
+
+---
+
+## Como ele lê seu projeto
+
+Apenas e exclusivamente:
+- `.aioson/plans/{slug}/harness-contract.json` — o contrato
+- `.aioson/plans/{slug}/progress.json` — estado atual dos steps
+- Arquivos listados em `progress.json.completed_steps`
+- Output de ferramentas locais (linter, test runner, compilador)
+
+**Nunca lê:** histórico de outros agentes, PRDs, requirements, architecture, ou código de outras features.
+
+---
+
+## Handoff típico
+
+- **Vem de:** `@qa` (recomenda `@validator` no relatório quando `harness-contract.json` existe).
+- `aioson workflow:next` também roteia automaticamente para `@validator` (como detour) quando `progress.json.status === 'waiting_validation'`.
+- **Vai para:** `aioson feature:close` — bloqueado se `ready_for_done_gate !== true` (libera com `--force` em emergência).
+
+---
+
+## Como rodar (modo CLI/headless)
+
+```bash
+# 1. Gera o prompt do validator em .aioson/plans/{slug}/validator-prompt.txt
+aioson harness:validate . --slug={slug}
+
+# 2. Você roda esse prompt no LLM (Claude Code, Codex, etc.) e salva
+#    o JSON do output em .aioson/plans/{slug}/last-validator-output.json
+
+# 3. Consome o JSON, atualiza progress.json, arquiva o output:
+aioson harness:apply-validation . --slug={slug}
+# ou simplesmente re-executar harness:validate (router auto-detecta o output)
+```
+
+Em CI: pular o passo manual emitindo o prompt para um runner de LLM externo, salvando o JSON no path padrão e chamando `apply-validation`.
+
+---
+
+## Próximo passo
+
+- [Ficha do @qa](./qa.md) — antecede o validator
+- [Glossário: Harness, Done Gate](../1-entender/glossario.md)

package/docs/pt/5-referencia/README.md

@@ -0,0 +1,88 @@
+# Referência técnica — AIOSON (PT)
+
+> Esta pasta contém a documentação técnica detalhada.
+> **Para começar do zero:** vá em [`2-comecar/`](../2-comecar/primeiro-projeto.md).
+> **Para exemplos práticos prontos:** vá em [`3-receitas/`](../3-receitas/README.md).
+
+---
+
+## Novos em 2026 (sem doc PT anterior)
+
+| Documento | Descrição |
+|---|---|
+| [feature-dossier.md](./feature-dossier.md) | Dossier de feature: ponto único de verdade (spec, plano, histórico, status) |
+| [agent-chain-continuity.md](./agent-chain-continuity.md) | Sistema de continuidade entre sessões — Fases 1–8 (dev-resume, drift detection, handoff v2) |
+| [sdd-framework.md](./sdd-framework.md) | Spec-Driven Development: Constitution, project-pulse, skill aioson-spec-driven, MICRO/SMALL/MEDIUM |
+| [live-sessions.md](./live-sessions.md) | Live sessions rastreadas: tmux launcher, live:start/status/handoff/close, runtime:emit |
+| [secure-by-default.md](./secure-by-default.md) | Baseline de segurança SEC-SBD-01..08, git:guard, pentester, controles por classificação |
+| [aioson-com-store.md](./aioson-com-store.md) | AIOSON Store: auth, workspaces, system:package/publish (--invite), squad/genome/skill:publish |
+| [../living-memory/README.md](../living-memory/README.md) | Memória Viva: bootstrap auto-atualizado, autonomy contract 3 tiers, notify (ℹ/⚠/⛔), doctor checks |
+| [../active-learning-loop/README.md](../active-learning-loop/README.md) | Active Learning Loop: destilação automática no `feature:close`, busca BM25 em learnings, archive/restore com `evolution_log`, 3 checks de curadoria no doctor |
+| [../deyvin-subtask-scout/README.md](../deyvin-subtask-scout/README.md) | Deyvin Sub-Task Scout: primitiva de diagnóstico estruturado, `scout:prep/validate/commit`, caps configuráveis, archivamento por feature |
+
+---
+
+## Referência de artefatos e fluxo
+
+| Documento | Descrição |
+|---|---|
+| [fluxo-artefatos.md](./fluxo-artefatos.md) | Mapa de quem cria o quê: @product → @sheldon → @analyst → @dev → @qa |
+| [feature-archive.md](./feature-archive.md) | Arquivamento automático de features concluídas via feature:close |
+| [memoria-e-contexto.md](./memoria-e-contexto.md) | Memória persistente, context cache, context search, context monitor — guia consolidado |
+| [runtime-observability.md](./runtime-observability.md) | Telemetria SQLite, dashboard, runtime:emit, agent:done |
+| [hooks-session-guard.md](./hooks-session-guard.md) | Hooks automáticos de visibilidade no dashboard para Claude Code, Antigravity e Codex |
+
+---
+
+## CLI e configuração
+
+| Documento | Descrição |
+|---|---|
+| [comandos-cli.md](./comandos-cli.md) | Referência completa de todos os comandos do `aioson` |
+| [clientes-ai.md](./clientes-ai.md) | Como usar com Claude Code, Codex, Gemini CLI e OpenCode |
+| [sandbox.md](./sandbox.md) | Execução segura com timeout, redação de secrets e output summarizado |
+| [compress-agents.md](./compress-agents.md) | Reduzir consumo de tokens comprimindo instruções de agentes |
+| [agent-sharding.md](./agent-sharding.md) | Carregar somente as seções relevantes de um agente para uma tarefa |
+
+---
+
+## Agentes, squads e processo
+
+| Documento | Descrição |
+|---|---|
+| [sdd-planos-e-estrutura.md](./sdd-planos-e-estrutura.md) | Mapa completo de artefatos: plans/, .aioson/plans/, .aioson/context/, lanes paralelas, tasks.md |
+| [sdd-automation-scripts.md](./sdd-automation-scripts.md) | Regra dos 80%: scripts determinísticos de gate, classificação e estado |
+| [motor-hardening.md](./motor-hardening.md) | Hardening do motor: gates técnicos, auto-cura, test briefing |
+| [design-docs-governance.md](./design-docs-governance.md) | Regras hard de código que agentes aplicam automaticamente |
+| [runner-system.md](./runner-system.md) | Execução persistente em background: filas, daemon, planos por fase |
+| [automacao-squads.md](./automacao-squads.md) | Transformar processos de squad em scripts executáveis sem LLM |
+| [squad-dashboard.md](./squad-dashboard.md) | Painel web local para monitorar squads em tempo real |
+| [inteligencia-adaptativa.md](./inteligencia-adaptativa.md) | Camada de aprendizado adaptativo entre sessões |
+| [output-strategy-delivery.md](./output-strategy-delivery.md) | Webhooks, delivery automático de conteúdo, troubleshoot |
+
+---
+
+## Skills e design
+
+| Documento | Descrição |
+|---|---|
+| [skills.md](./skills.md) | Sistema de skills: tipos, instalação, mapeamento por framework |
+| [genome-4.0-spec.md](./genome-4.0-spec.md) | Especificação técnica Genome 4.0 (DISC, Enneagram, Big Five, MBTI, HEXACO-H) |
+| [genome-distribution.md](./genome-distribution.md) | Distribuição e publicação de genomes via aioson.com |
+
+---
+
+## Pipelines de dados
+
+| Documento | Descrição |
+|---|---|
+| [spec-learnings-pipeline.md](./spec-learnings-pipeline.md) | Sincronizar specs com SQLite, exportar learnings para brains |
+| [devlog-pipeline.md](./devlog-pipeline.md) | Processar devlogs manuais, sincronizar com SQLite e exportar para brains |
+
+---
+
+## Outros
+
+| Documento | Descrição |
+|---|---|
+| [web3.md](./web3.md) | Suporte a projetos dApp (Ethereum, Solana, Cardano) |

package/docs/pt/5-referencia/agent-chain-continuity.md

@@ -0,0 +1,124 @@
+# Agent-Chain Continuity
+
+> **Para quem é:** quem trabalha em features longas, com múltiplos agentes, ou retomadas frequentes.
+> **Tempo de leitura:** 8 min
+> **O que você vai sair sabendo:**
+> - Como o AIOSON garante que nenhum contexto se perde entre sessões
+> - Os 5 componentes do sistema e como eles se compõem
+
+## Para que serve
+
+Uma feature MEDIUM dura dias. Nesse tempo você troca de cliente AI, a sessão compacta, o `@dev` passa para o `@qa`, o `@qa` devolve para o `@dev`, e você dorme no meio. Toda vez que um agente novo entra, precisa responder: "onde estávamos? o que foi feito? o que mudou desde que a spec foi escrita?"
+
+Sem um sistema de continuidade, a resposta é "reler o histórico de chat" — o que não escala e some na compactação. Com agent-chain continuity, a resposta é "ler os artefatos". O histórico é descartável; os artefatos são a memória.
+
+Este sistema foi construído em 8 fases ao longo de Mar–Mai/2026 (commits `agent-chain-continuity`). Os 5 componentes são independentes mas se reforçam.
+
+## Os 5 componentes
+
+### 1. Handoff Protocol v2 (`handoff-protocol.json`)
+
+Arquivo em `.aioson/context/handoff-protocol.json`. Criado/atualizado em todo handoff entre agentes. Schema v2 inclui `artifact_uris` — lista de caminhos para todos os artefatos relevantes da feature, para o próximo agente não precisar adivinhar onde está cada coisa.
+
+```json
+{
+  "from": "@dev",
+  "to": "@qa",
+  "feature_slug": "checkout-stripe",
+  "timestamp": "2026-05-06T14:23:00Z",
+  "artifact_uris": [
+    ".aioson/context/features/checkout-stripe/spec.md",
+    ".aioson/context/dev-state.md",
+    ".aioson/context/dossier/checkout-stripe/dossier.json"
+  ],
+  "summary": "Stripe handler implementado. Webhook pendente. 3 testes falhando."
+}
+```
+
+### 2. Dev-State (`dev-state.md`)
+
+Arquivo em `.aioson/context/dev-state.md`. O `@dev` atualiza ao fim de cada sessão com: o que foi feito, o que está pendente, arquivos tocados, decisões tomadas, próxima ação sugerida. É o "onde parei" que permite retomada sem reler o histórico.
+
+### 3. Dev-Resume Helper
+
+Quando o `@dev` é invocado e detecta que há uma feature em andamento (via `dev-state.md` e dossier), ele entra automaticamente em modo de retomada: lê os artefatos, detecta drift (spec mudou depois do código?) e apresenta o estado antes de pedir qualquer instrução nova.
+
+### 4. Drift Detection (Phase 5)
+
+Se a spec foi atualizada depois que o código foi escrito, ou se o `handoff-protocol.json` não corresponde ao `dev-state.md`, o sistema detecta o drift e alerta o agente antes de prosseguir. Evita o bug clássico de "implementei com base numa spec que já mudou".
+
+```
+@dev > Detectei drift: spec.md atualizada em 2026-05-05, mas dev-state.md
+       registra implementação baseada em spec de 2026-05-03.
+       Recomendo revisar seções 2 e 3 da spec antes de continuar.
+```
+
+### 5. Sync-Agents Preflight (Phase 4)
+
+Antes de iniciar uma nova sessão de agente, o sistema verifica se os agentes instalados no workspace estão em paridade com a versão do template. Garante que `@dev` e `@qa` estão rodando o mesmo conjunto de regras — não versões diferentes de antes de um update.
+
+```bash
+aioson sync:agents .   # sincroniza agentes do template para o workspace
+```
+
+## Como o sistema se compõe
+
+```
+feature inicia (via workflow:next ou manualmente)
+        │
+        ▼
+dossier:init criado → dossier.json
+        │
+        ▼
+@product → spec.md
+        │
+        ▼
+@dev implementa → dev-state.md (atualizado a cada ponto)
+        │          handoff-protocol.json (escrito no handoff)
+        │
+        ▼
+[sessão nova / agente novo]
+        │
+        ├─ drift detection (spec mudou desde o dev-state?)
+        ├─ dev-resume (modo automático de retomada)
+        └─ next agent lê artifact_uris do handoff-protocol
+        │
+        ▼
+@qa → testa → devolve para @dev se houver falhas (ciclo autônomo, cap 2)
+        │
+        ▼
+@validator → gate final → feature:close
+        │
+        ▼
+dossier arquivado em .aioson/context/done/
+```
+
+## Gatilhos automáticos
+
+| Evento | O que acontece automaticamente |
+|---|---|
+| `aioson feature:close` | Dossier auto-init se não existir; handoff-protocol atualizado; feature movida para `done/` |
+| `aioson workflow:next` | Verifica paridade de agentes; lê dossier; emite próximo agente |
+| `@dev` entra sem instrução | Modo dev-resume: lê dev-state.md e dossier antes de qualquer ação |
+
+## Saídas em disco
+
+```
+.aioson/context/
+├── handoff-protocol.json      ← último handoff entre agentes
+├── last-handoff.json          ← alias usado por @validator
+├── dev-state.md               ← estado atual do @dev
+└── dossier/<slug>/
+    └── dossier.json           ← estado da feature (inclui artifact_uris)
+```
+
+## Quando NÃO precisa disso
+
+- Features MICRO de sessão única. O `@dev` resolve e você commita. Sem continuidade necessária.
+- Quando você usa o `runner-system` com fases automáticas — o runner gerencia tudo isso internamente.
+
+## Próximo passo
+
+- [Feature Dossier](./feature-dossier.md) — comandos detalhados do dossier
+- [Live Sessions](./live-sessions.md) — como registrar milestones de continuidade no dashboard
+- [Ficha do @deyvin](../4-agentes/deyvin.md) — o agente de retomada que consome esses artefatos