@jaimevalasek/aioson 1.33.1 → 1.37.0

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

@@ -1,9 +1,11 @@
 # Guia de Agentes AIOSON
 
-> Índice com 30 agentes e 1 alias, com situação de uso e saída esperada.
+> Índice com 31 agentes e 1 alias, com situação de uso e saída esperada.
 > Cada agente tem sua ficha — clique no nome para detalhes.
 > `@pair` é alias de `@deyvin` e não possui ficha separada.
 
+> **As colunas "Quando invocar" abaixo descrevem a capacidade de cada agente, não a ordem obrigatória do fluxo padrão.** Desde a lane lean/maestro (v1.35.0), o fluxo padrão é `@product → @sheldon → @dev → @qa` (SMALL) ou `@product → @orchestrator → @dev → @pentester → @qa` (MEDIUM) — `@analyst`, `@architect`, `@ux-ui` e `@pm` são detours opt-in ou sub-agentes do fan-out do `@orchestrator`, não hops obrigatórios. Construir a feature assim também pode rodar sozinho até a recomendação de `feature:close` — veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md).
+
 ---
 
 ## Núcleo de desenvolvimento (neste diretório)
@@ -11,14 +13,15 @@
 | Agente | Para que serve | Quando invocar | Saída principal |
 |---|---|---|---|
 | [@product](./product.md) | Define visão, PRD e escopo da feature | Início de projeto ou nova feature | `prd.md`, `spec.md` |
-| [@analyst](./analyst.md) | Descobre domínio, entidades, fluxos | Após `@product`, antes de `@architect` | `architecture.md` (domínio) |
-| [@scope-check](./scope-check.md) | Confronta intenção, plano e artefatos antes do código | Antes de `@dev` e após fixes relevantes | `scope-check.md` |
-| [@architect](./architect.md) | Decide stack, estrutura, integração técnica | Após `@analyst` | `architecture.md` (técnico) |
-| [@ux-ui](./ux-ui.md) | Design system e specs de componentes | MEDIUM, após `@architect` | `design-doc.md`, `discovery.md` |
-| [@pm](./pm.md) | Backlog, user stories, ACs detalhados | MEDIUM, após `@ux-ui` | `tasks.md` |
-| [@orchestrator](./orchestrator.md) | Coordena lanes paralelas de implementação | MEDIUM, após `@pm` | `.aioson/context/parallel/` |
-| [@dev](./dev.md) | Implementa a feature | Após planning completo | código + `dev-state.md` |
-| [@qa](./qa.md) | Testa, valida ACs, ciclo autônomo com `@dev` | Após `@dev` | `test-plan.md`, `qa-report-*.md` |
+| [@analyst](./analyst.md) | Descobre domínio, entidades, fluxos | Detour opt-in / sub-agente do `@orchestrator` (MEDIUM) | `architecture.md` (domínio) |
+| [@scope-check](./scope-check.md) | Confronta intenção, plano e artefatos antes do código | `spec:analyze` roda automático no gate `@dev`/`@qa`; detour explícito também disponível | `scope-check.md` |
+| [@architect](./architect.md) | Decide stack, estrutura, integração técnica | Detour opt-in / sub-agente do `@orchestrator` (MEDIUM) | `architecture.md` (técnico) |
+| [@ux-ui](./ux-ui.md) | Design system e specs de componentes | Detour opt-in para specs UI-heavy | `design-doc.md`, `discovery.md` |
+| [@pm](./pm.md) | Backlog, user stories, ACs detalhados | Sub-agente do `@orchestrator` (MEDIUM) ou detour opt-in | `tasks.md` |
+| [@sheldon](./sheldon.md) | **Autoridade única de spec (SMALL)** — requirements + decisões técnicas + plano faseado + harness-contract numa passada | Após `@product`, padrão do SMALL | `requirements-*.md`, `implementation-plan-*.md`, `harness-contract.json` |
+| [@orchestrator](./orchestrator.md) | **Maestro de spec (MEDIUM)** — fan-out para `@analyst`/`@architect`/`@pm` (+`@ux-ui`), consolida o pacote de spec com Gates A/B/C; secundário: coordena lanes paralelas pós-spec | Após `@product`, padrão do MEDIUM | `.aioson/context/parallel/`, pacote de spec consolidado |
+| [@dev](./dev.md) | Implementa a feature | Após o pacote de spec (`@sheldon`/`@orchestrator`) ou direto após `@product` (MICRO) | código + `dev-state.md` |
+| [@qa](./qa.md) | Testa, valida ACs, ciclo autônomo com `@dev` (cap 3), hub do autopilot pós-dev | Após `@dev` | `test-plan.md`, `qa-report-*.md` |
 | [@validator](./validator.md) | Gate final: valida contrato binário de sucesso | Após `@qa`, antes de fechar feature | veredicto em `last-handoff.json` |
 | [@forge-run](./forge-run.md) | Lane B opt-in: compila e roda o workflow de verificação executável de uma feature MEDIUM | MEDIUM com contrato `verification` + plano com Wave | `forge-run.workflow.js` |
 | [@tester](./tester.md) | Engenharia de testes para apps já existentes | Legacy/brownfield ou lacunas graves | `test-inventory.md` |
@@ -33,10 +36,9 @@
 | [@setup](./setup.md) | Onboarding: detecta stack, classifica projeto | Sempre primeiro num projeto novo | `project.context.md` |
 | [@neo](./neo.md) | Roteador: diz qual agente é o próximo | Quando você está perdido | Orientação verbal |
 | [@briefing](./briefing.md) | Transforma anotações soltas em briefing pré-PRD | Antes de `@product`, quando ideia ainda vaga | `briefing.md` |
-| [@briefing-refiner](./briefing-refiner.md) | Revisa e refina um briefing existente via superfície HTML local | Após `@briefing`, antes de `@product` | `review.html`, `refinement-report.md` |
+| [@briefing-refiner](./briefing-refiner.md) | Loop de refino de briefing: audita em achados estruturados, o CLI renderiza a revisão (`briefing:review`) e aplica o feedback confirmado (`briefing:apply-feedback`) | Após `@briefing`, antes de `@product` | `refinement-findings.json`, `review.html` (CLI), `refinement-feedback.json`, `refinement-report.md` |
 | [@deyvin](./deyvin.md) | Pair-programming e continuidade de sessão | Retomar feature interrompida | continuação do trabalho |
 | [@pair](./deyvin.md) | Alias de `@deyvin` | — | — |
-| [@sheldon](./sheldon.md) | Análise técnica profunda, revisão de arquitetura | Decisões grandes, código legado | relatório de revisão |
 | [@committer](./committer.md) | Gera mensagem de commit profissional | Após implementar, antes de commitar | mensagem de commit |
 | [@discover](./discover.md) | Constrói cache semântico do projeto | Onboarding em codebase grande | `.aioson/context/bootstrap/` |
 

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

@@ -20,18 +20,22 @@ Em projetos com `@discover` já rodado, o `@analyst` usa o cache semântico em v
 
 ## Quando invocar
 
-- Logo após `@product`, em fluxos SMALL e MEDIUM.
-- Quando uma nova feature toca entidades existentes e você quer garantir que não há conflito.
+- **No MEDIUM:** `@orchestrator` o dispara automaticamente como sub-agente no fan-out de spec — você não precisa invocar manualmente.
+- **Detour explícito:** quando uma nova feature toca entidades existentes e você quer mapeamento de domínio independente antes de qualquer implementação.
 - Quando alguém novo entra no projeto e precisa entender o domínio rapidamente.
 - Quando a spec mudou e você quer sincronizar o mapeamento de domínio.
+- Para classificação de complexidade (`aioson classify`) — `@analyst` produz o score MICRO/SMALL/MEDIUM.
+
+> **SMALL:** na lane lean padrão (`@product → @sheldon → @dev → @qa`), `@analyst` não é um hop padrão — o `@sheldon` cobre o mapeamento de domínio sozinho. Invoque `@analyst` explicitamente apenas se precisar de discovery de domínio mais aprofundado como detour.
 
 ---
 
 ## Quando NÃO invocar
 
 - Projeto MICRO sem novas entidades → o `@dev` lê o contexto direto.
+- Projeto SMALL em lane padrão → `@sheldon` já cobre o domínio; `@analyst` só se necessário como detour.
 - Você quer rever decisões técnicas (não de domínio) → invoke `@architect`.
-- A feature não toca modelo de dados e não tem fluxos novos → pule direto para `@architect`.
+- A feature não toca modelo de dados e não tem fluxos novos → pule direto para o próximo passo.
 
 ---
 
@@ -99,8 +103,8 @@ aioson workflow:status .
 
 ## Handoff típico
 
-- **Vem de:** `@product`
-- **Vai para:** `@architect`
+- **Vem de:** `@orchestrator` (como sub-agente no MEDIUM) ou invocação explícita como detour
+- **Vai para:** `@architect` (quando usado como detour); o resultado consolida para `@orchestrator` quando em sub-agente
 
 ---
 

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

@@ -20,16 +20,20 @@ Ele também contribui no `dossier` da feature, registrando os arquivos-chave no
 
 ## Quando invocar
 
-- Após `@analyst`, em fluxos SMALL e MEDIUM.
-- Quando a feature envolve decisões de integração com APIs externas ou novos módulos.
+- **No MEDIUM:** `@orchestrator` o dispara automaticamente como sub-agente no fan-out de spec — você não precisa invocar manualmente.
+- **Detour explícito:** quando a feature envolve decisões de integração com APIs externas ou novos módulos e você quer decisões técnicas separadas da análise de domínio.
 - Quando você quer garantir consistência com o padrão de pastas do projeto antes de implementar.
-- Quando há um plano Sheldon (`@sheldon` foi invocado antes) — `@architect` lê o plano por fases.
+
+> **SMALL:** na lane lean padrão (`@product → @sheldon → @dev → @qa`), `@architect` não é um hop padrão — o `@sheldon` cobre as decisões técnicas sozinho. Invoque `@architect` explicitamente apenas como detour se precisar de estrutura técnica mais detalhada.
+
+> **Modo merged:** quando `@architect` é invocado sem `@discovery-design-doc` no fluxo, ele entra em **modo merged** — além das decisões técnicas padrão, produz também o design-doc e o readiness, absorvendo o papel que seria do `@discovery-design-doc`.
 
 ---
 
 ## Quando NÃO invocar
 
 - Feature MICRO sem decisões novas → `@dev` infere do contexto existente.
+- Projeto SMALL em lane padrão → `@sheldon` já cobre as decisões técnicas; `@architect` só se necessário como detour.
 - Você só quer adicionar um campo a uma entidade existente → `@dev` lida sozinho.
 - Você quer revisar a arquitetura geral do projeto (não de uma feature) → use `@sheldon`.
 
@@ -101,8 +105,8 @@ aioson dossier:add-codemap . --slug=checkout-stripe \
 
 ## Handoff típico
 
-- **Vem de:** `@analyst`
-- **Vai para:** `@ux-ui` (MEDIUM) ou `@dev` (SMALL/MICRO)
+- **Vem de:** `@orchestrator` (como sub-agente no MEDIUM) ou `@analyst` (quando usado como detour)
+- **Vai para:** `@ux-ui` (detour MEDIUM com UI pesada) ou resultado consolida para `@orchestrator` quando em sub-agente
 
 ---
 

package/docs/pt/4-agentes/briefing-refiner.md

@@ -1,16 +1,17 @@
 # @briefing-refiner — Revisa e refina um briefing antes do PRD
 
 > **Para quem é:** quem já tem um briefing gerado pelo `@briefing` e quer revisá-lo, anotar e refinar antes de comprometer um PRD.
-> **Tempo de leitura:** 4 min.
+> **Tempo de leitura:** 5 min.
 > **O que você vai sair sabendo:**
 > - O que o `@briefing-refiner` faz e onde ele entra no fluxo.
-> - Como funciona a superfície de revisão local em HTML e por que o feedback é estruturado (JSON), não o DOM.
+> - Como funciona o loop de refinamento em rodadas (auditoria → revisão no navegador → aplicação).
+> - Como a superfície `review.html` salva de verdade (autosave local + 3 rotas de retorno do JSON).
 
 ## Para que serve
 
 Entre o briefing gerado e o PRD há uma etapa que costuma ser pulada: **revisar o briefing com olhar crítico**. Ambiguidades, redundâncias, decisões faltando, riscos vagos e gaps de impacto de implementação passam direto para o `@product` e viram dívida no PRD.
 
-O `@briefing-refiner` preenche essa etapa. Ele audita um briefing existente, gera uma **superfície de revisão local** (`review.html`) onde você edita cada seção, marca status e deixa notas, e depois aplica de volta ao briefing **apenas o feedback estruturado que você confirmar** — preservando o contrato do briefing (todas as seções obrigatórias).
+O `@briefing-refiner` preenche essa etapa em um **loop de rodadas**: ele audita o briefing e registra **achados estruturados** (findings com categoria, severidade e se bloqueiam o PRD); o CLI renderiza a superfície de revisão determinística (`aioson briefing:review`); você decide cada achado e edita cada seção no navegador; o feedback estruturado volta e é aplicado (`aioson briefing:apply-feedback`) — e o ciclo se repete até nada bloquear o PRD.
 
 É o complemento do [`@briefing`](./briefing.md): um gera, o outro refina.
 
@@ -18,7 +19,8 @@ O `@briefing-refiner` preenche essa etapa. Ele audita um briefing existente, ger
 
 - Você já tem um briefing em `.aioson/briefings/{slug}/briefings.md` e quer revisá-lo antes do PRD.
 - O briefing está `draft`, ou `approved` mas ainda **sem PRD gerado** (`prd_generated: null`).
-- Quer registrar comentários, pedir mudanças por seção ou marcar bloqueios antes de seguir para `@product`.
+- Quer registrar comentários, decidir achados, pedir mudanças por seção ou marcar bloqueios antes de seguir para `@product`.
+- Quer **ver a solução** antes do PRD (modo prototype) e, opcionalmente, definir a identidade visual a partir das suas imagens de referência.
 
 ## Quando NÃO invocar
 
@@ -26,71 +28,89 @@ O `@briefing-refiner` preenche essa etapa. Ele audita um briefing existente, ger
 - O briefing já gerou PRD (`prd_generated` preenchido) — refinar exigiria uma rota nova de PRD/enrichment, fora deste agente.
 - A ideia mudou tanto que vale regerar do zero — volte ao `@briefing`.
 
-## Dois modos de operação
+## O loop de refinamento
+
+```
+auditoria (agente) → review.html (CLI) → você decide no navegador
+       ↑                                            ↓
+regenera a revisão  ←  aplica feedback confirmado (CLI)
+(enquanto houver bloqueios ou mudanças de texto)
+```
+
+Cada rodada tem número (`round`) e arquiva o feedback consumido (`refinement-feedback.applied-round{N}.json`), então "existe `refinement-feedback.json`" = "há feedback pendente" — um sinal determinístico.
 
 ### 1. Gerar revisão
 
-Quando ainda não há feedback pendente. O agente audita o briefing e escreve a superfície de revisão:
+O agente audita o briefing e escreve os achados em `refinement-findings.json`; o CLI valida e renderiza:
 
 ```
 Você > @briefing-refiner
 
 @briefing-refiner > Briefing refinável encontrado: marketplace-v1 (draft).
 
-                    Auditando seções... ambiguidades: 3, redundâncias: 1,
-                    gaps de implementação: 2, riscos vagos: 1.
+                    Auditando... 10 achados (3 ambiguidades, 2 gaps,
+                    1 bloqueante: modelo de comissão indefinido).
 
-                    Gerei a revisão:
-                    - .aioson/briefings/marketplace-v1/review.html
-                    - .aioson/briefings/marketplace-v1/refinement-feedback.json
-                    - .aioson/briefings/marketplace-v1/refinement-report.md
+                    aioson briefing:review . --slug=marketplace-v1  ✓ (rodada 1)
 
-                    Abra o review.html, edite as seções, marque status/notas,
-                    salve/exporte o refinement-feedback.json e me reative.
+                    Abra .aioson/briefings/marketplace-v1/review.html
+                    NUM NAVEGADOR DE VERDADE (duplo clique) — previews de
+                    editor são sandboxed e bloqueiam salvar/baixar.
 ```
 
 ### 2. Aplicar feedback pendente
 
-Quando existe um `refinement-feedback.json` com mudanças não aplicadas. O agente valida, resume o que vai mudar e **pede confirmação explícita** antes de tocar o briefing:
+O CLI valida (schema, slug, hash da fonte) e faz um **dry-run** com o resumo; o agente pede confirmação explícita antes de tocar o briefing:
 
 ```
-Você > @briefing-refiner
-
-@briefing-refiner > Feedback pendente em marketplace-v1:
-                    - 4 seções com mudança aceita
-                    - 2 comentários não resolvidos
-                    - 1 item bloqueante (modelo de comissão)
+@briefing-refiner > Feedback pendente em marketplace-v1 (rodada 1):
+                    - 4 seções com mudança, 1 bloqueada
+                    - achados: 6 aceitos, 2 rejeitados, 1 adiado, 1 pendente (bloqueante)
 
-                    Aplico as 4 mudanças confirmadas? (o item bloqueante
-                    impede o handoff para @product até ser resolvido)
+                    Aplico as mudanças confirmadas? O achado bloqueante
+                    pendente mantém o bloqueio do PRD.
 Você > Sim.
 
-@briefing-refiner > Aplicado. Como o briefing estava `approved` sem PRD,
-                    voltei para `draft`. Relatório: refinement-report.md.
+@briefing-refiner > aioson briefing:apply-feedback --confirm  ✓
+                    Aplicado; briefing voltou de approved para draft.
+                    Bloqueio restante → regenerando a revisão (rodada 2)...
 ```
 
-Se você recusar, o `briefings.md` fica intacto e as mudanças puladas são registradas no relatório.
+Se você recusar, o `briefings.md` fica intacto e as mudanças puladas são registradas no relatório. Quando não sobra bloqueio: `aioson briefing:approve . --slug={slug}` → `@product`.
 
 ## A superfície de revisão (review.html)
 
-O diferencial deste agente. O `review.html` é **estático, local e self-contained**:
+Renderizada pelo CLI (`aioson briefing:review`) — estática, local, self-contained e no seu idioma:
+
+- seções editáveis em texto puro + status por seção (`unchanged`, `accepted`, `change_requested`, `remove_requested`, `blocked`) e notas;
+- **achados da auditoria por seção**, cada um com decisão própria (`pending`/`accepted`/`rejected`/`deferred`) e nota — com filtros funcionais por categoria;
+- painel com o que mudou, o que bloqueia o PRD e quantos achados seguem pendentes;
+- **autosave local**: cada edição é salva no navegador (localStorage) e restaurada ao reabrir — fechar a aba não perde nada;
+- **3 rotas para devolver o JSON**: *Salvar no arquivo* (File System Access, com fallback automático para download quando o contexto é sandboxed), *Baixar JSON* (e mover por cima do `refinement-feedback.json`), ou *Copiar JSON e colar no chat* — a rota de menor atrito.
 
-- sem servidor, sem scripts ou serviços externos;
-- seções editáveis em texto puro, com layout denso de revisão;
-- controles de status por seção: `unchanged`, `accepted`, `change_requested`, `remove_requested`, `blocked`;
-- notas/comentários por seção e um resumo do que será feito, do que é incerto e do que bloqueia o PRD;
-- filtros por ambiguidade, redundância, gap, risco, decisão pendente e sugestão de escopo;
-- **exportar/baixar/copiar o JSON sempre disponível** (a File System Access API é só um plus opcional, após ação explícita).
+> **Por que JSON e não o HTML editado?** O agente nunca trata o DOM/HTML editado como feedback canônico — só o `refinement-feedback.json` estruturado (schema v1.1, validado por hash da fonte). Isso evita aplicar mudanças inferidas e mantém o processo auditável.
 
-> **Por que JSON e não o HTML editado?** O agente nunca trata o DOM/HTML editado como feedback canônico — só o `refinement-feedback.json` estruturado. Isso evita aplicar mudanças inferidas e mantém o processo auditável.
+> **Importante:** abra o `review.html` num navegador de verdade (duplo clique). Previews embutidos de editor rodam em sandbox e bloqueiam o file picker e downloads.
+
+## Modo prototype e identidade visual (opcional)
+
+Para briefings com superfície rica (workspaces, boards, CRM/Kanban, dashboards, CRUD de uso repetido), o agente recomenda — sem bloquear — gerar um protótipo clicável antes do PRD. É nesse momento (ou já na revisão, via achado não-bloqueante) que a **identidade visual** entra:
+
+- você solta imagens de referência em `references/identity/` (marca: cor, tipografia, clima) e `references/structure/` (um board, uma tabela, uma tela);
+- a skill `reference-identity-extract` lê as imagens **uma única vez** e escreve `identity.md` (tokens + notas de estrutura por componente);
+- o motor `interface-design` **aplica** o `identity.md` em tudo que vier depois (protótipo e build) — sem imagens, ele roda intent-first.
+
+O protótipo é mock-only e nunca vira feedback canônico.
 
 ## Saídas em disco
 
 | Arquivo | O que contém |
 |---|---|
-| `.aioson/briefings/{slug}/review.html` | Superfície de revisão local e editável |
-| `.aioson/briefings/{slug}/refinement-feedback.json` | Feedback estruturado (a única fonte que o agente aplica) |
-| `.aioson/briefings/{slug}/refinement-report.md` | Relatório do que foi aplicado, pulado ou bloqueado |
+| `.aioson/briefings/{slug}/refinement-findings.json` | Achados da auditoria do agente (entrada do CLI) |
+| `.aioson/briefings/{slug}/review.html` | Superfície de revisão renderizada pelo CLI |
+| `.aioson/briefings/{slug}/refinement-feedback.json` | Feedback estruturado v1.1 (a única fonte que é aplicada) |
+| `.aioson/briefings/{slug}/refinement-report.md` | Relatório da rodada: aplicado, pulado, bloqueado, achados |
+| `.aioson/briefings/{slug}/refinement-*.{applied,declined}-round{N}.json` | Arquivo morto por rodada (feedback aplicado ou recusado, e findings consumidos) |
 | `.aioson/briefings/{slug}/briefings.md` | Atualizado **apenas** após confirmação |
 | `.aioson/briefings/config.md` | Índice/registro de briefings atualizado |
 
@@ -105,15 +125,19 @@ O diferencial deste agente. O `review.html` é **estático, local e self-contain
 
 - Nunca cria ou edita `prd*.md`.
 - Nunca aprova um briefing automaticamente.
-- Nunca roteia para `@product` enquanto houver itens bloqueantes.
+- Nunca roteia para `@product` enquanto houver itens bloqueantes (inclusive achado bloqueante pendente).
 - Nunca trata HTML/DOM editado como feedback canônico — só o JSON estruturado.
+- Nunca escreve `review.html` à mão nem aplica feedback manualmente enquanto os comandos CLI existirem — o done-gate (`verify:artifact --kind=review`) rejeita superfícies feitas à mão.
 - Nunca descarta seções obrigatórias do briefing.
-- Em V1, não há comando CLI dedicado de refinement — tudo passa pelo agente.
+
+## Opção `--help`
+
+Uma ativação com `--help` (`/briefing-refiner --help`) imprime um resumo rápido — o que faz, quando usar, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
 
 ## Handoff típico
 
 - **Vem de:** [`@briefing`](./briefing.md) (briefing gerado) ou de você, retomando uma revisão.
-- **Vai para:** depois de aplicar as mudanças e sem bloqueios → `aioson briefing:approve . --slug={slug}` → [`@product`](./product.md). Se sobrar bloqueio, você resolve no review e reativa o `@briefing-refiner`.
+- **Vai para:** depois de aplicar as mudanças e sem bloqueios → `aioson briefing:approve . --slug={slug}` → [`@product`](./product.md); para superfícies ricas, o modo prototype antes. Se sobrar bloqueio, a próxima rodada do loop resolve — nunca edição manual.
 
 ## Próximo passo
 

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

@@ -72,10 +72,14 @@ Você > Todos.
 
 > **Fast path de ativação (v1.29.0):** ativar `@briefing` "seco", sem nomear plano ou tarefa, carrega **só** o `project.context.md`, o frontmatter do registro e a *listagem de nomes* de `plans/` — apresenta o menu e para. O conteúdo dos planos e PRDs acima entra só no passo que os usa. Veja [Carregamento seletivo de contexto](../5-referencia/memoria-e-contexto.md#carregamento-seletivo-de-contexto-v1290).
 
+## Opção `--help`
+
+Uma ativação com `--help` (`/briefing --help`) imprime um resumo rápido — o que faz, quando usar, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
 ## Handoff típico
 
 - **Vem de:** você, com anotações em `plans/` ou uma ideia conversacional.
-- **Vai para:** `@product` (que usa o briefing como contexto enriquecido no PRD).
+- **Vai para:** [`@briefing-refiner`](./briefing-refiner.md) (opcional — loop de revisão e refino do briefing antes do PRD) ou, após `aioson briefing:approve`, `@product` (que usa o briefing como contexto enriquecido no PRD).
 
 ## Modo conversacional
 
@@ -93,5 +97,6 @@ Você > Sim.
 ## Próximo passo
 
 - Entender o fluxo completo → [Mapa do ecossistema](../1-entender/mapa-do-ecossistema.md)
+- Revisar e refinar o briefing antes do PRD → [@briefing-refiner](./briefing-refiner.md)
 - Após o briefing aprovado → [@product](./product.md) *(ficha em construção)*
 - Termos como "gap" e "PRD" → [Glossário](../1-entender/glossario.md)

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

@@ -10,9 +10,19 @@
 
 ## Para que serve
 
-Você passou por `@product`, `@analyst`, `@architect` e, nos fluxos SMALL/MEDIUM atuais, por `@scope-check` antes de abrir implementação. A spec existe, as decisões técnicas estão em disco. Agora é hora de escrever código — mas de forma que o próximo agente (`@qa`, `@validator`) consiga verificar o que foi feito sem perguntar "o que você implementou?".
+Você passou pela autoridade única de spec (`@sheldon` no SMALL ou `@orchestrator` no MEDIUM) — a spec existe, as decisões técnicas estão em disco, o plano de implementação está faseado e o contrato de harness está aprovado. Agora é hora de escrever código — mas de forma que o próximo agente (`@qa`, `@validator`) consiga verificar o que foi feito sem perguntar "o que você implementou?".
 
-`@dev` lê os artefatos, implementa, e grava um `dev-state.md` com o resumo do que foi feito, quais arquivos foram tocados, e qual é o próximo passo. Isso é o que permite continuar de onde parou em outra sessão, sem depender do histórico de chat.
+`@dev` lê os artefatos, implementa fase por fase, e grava um `dev-state.md` com o resumo do que foi feito, quais arquivos foram tocados, e qual é o próximo passo. Isso é o que permite continuar de onde parou em outra sessão, sem depender do histórico de chat.
+
+**Loop de fases:** `@dev` executa o plano faseado como um loop automático:
+1. Implementa a fase atual.
+2. Roda `aioson harness:check` (gate por fase).
+3. Executa **verificação por fase** (sub-agente leve, ex.: `qa` num modelo barato) — o relatório substitui o "continue?".
+4. Corrige os pontos encontrados dentro da mesma fase.
+5. **Compacta o contexto** antes de avançar.
+6. Passa para a próxima fase sem precisar de aprovação manual.
+
+O **Runtime smoke completo** (build + migrations em DB real + boot + happy-path) roda **uma vez ao fim da feature** — não por fase. Verificação por fase é suprimida no MICRO para economizar tokens.
 
 **Regra dura de contexto:** ele carrega no máximo 5 arquivos antes de escrever a primeira linha de código. Se precisar de mais, para e pergunta o que priorizar. Isso evita "contexto inchado" que leva a decisões confusas.
 
@@ -20,7 +30,8 @@ Você passou por `@product`, `@analyst`, `@architect` e, nos fluxos SMALL/MEDIUM
 
 ## Quando invocar
 
-- Após `@scope-check` (SMALL/MEDIUM) ou `@product` (MICRO).
+- Após `@sheldon` (SMALL — lane lean padrão) ou `@orchestrator` (MEDIUM — lane maestro).
+- Após `@product` (MICRO — sem fase de spec).
 - Para retomar uma feature interrompida — `@dev` lê `dev-state.md` e sabe onde parou.
 - Para correções apontadas pelo `@qa` (ciclo autônomo, até 2 iterações).
 
@@ -43,7 +54,7 @@ Você > @dev
        Lendo project.context.md... Node.js, SMALL, checkout-stripe.
        Lendo spec-checkout-stripe.md e implementation-plan-checkout-stripe.md...
        
-       Scope-check aprovado. Implementando:
+       Scope-check aprovado. Implementando:
        
        1. db/migrations/add-payment-table.sql       ← Payment schema
        2. src/models/payment.js                     ← model com validação básica
@@ -91,21 +102,40 @@ Depende do modo:
 | Modo | O que carrega (máx. 5 arquivos) |
 |---|---|
 | MICRO | `project.context.md` + `prd-{slug}.md` |
-| SMALL/MEDIUM | `project.context.md` + `spec-{slug}.md` + `implementation-plan-{slug}.md` |
+| SMALL | `project.context.md` + pacote de spec do `@sheldon` (`requirements-{slug}.md` + `implementation-plan-{slug}.md`) |
+| MEDIUM | `project.context.md` + pacote de spec do `@orchestrator` (`implementation-plan-{slug}.md` + `harness-contract.json`) |
 | Retomada | Apenas o `context_package` do `dev-state.md` |
 
 **Nunca carrega** arquivos de outros agentes (`.aioson/agents/`), specs de outras features, ou mais de 5 arquivos antes do primeiro código.
 
+**Inputs de UI (modo feature):** quando o PRD tem `## Prototype reference`, o `@dev` reproduz as telas e interações do `prototype.html`; e quando `design_skill: interface-design` e existe um `identity.md` (`.aioson/briefings/{slug}/identity.md`, senão `.aioson/context/identity.md`), ele o lê como input visual ao lado da referência de protótipo — é a identidade extraída das suas imagens de referência, e o `@dev` não entrega visual genérico enquanto ela existir.
+
 ---
 
 ## Detalhes recentes
 
-**Ciclo autônomo QA→Dev (cap 2, Mai 2026):** quando o `@qa` encontra falhas pequenas (testes falhando, AC não atendido), ele pode enviar correções diretamente ao `@dev` sem você precisar reativar manualmente. O ciclo se repete no máximo 2 vezes. Na terceira falha, ele sobe para você decidir.
+**Ciclo autônomo QA→Dev (cap 3):** quando o `@qa` encontra falhas pequenas (testes falhando, AC não atendido), ele pode enviar correções diretamente ao `@dev` sem você precisar reativar manualmente. O ciclo se repete no máximo 3 vezes (`agentic_policy.review_cycle`, configurável). Ao esgotar as tentativas, ele sobe para você decidir.
 
 **dev-resume helper:** se o `dev-state.md` existe mas está inconsistente com o código (drift detection), o `@dev` detecta a divergência e te avisa antes de continuar.
 
 ---
 
+## Modo de execução: autopilot
+
+- `/dev --auto`: arma o autopilot a partir daqui mesmo sem flag/esquema prévio — a implementação e o ciclo de revisão pós-dev (`@qa` → `@tester`/`@pentester` quando o trigger dispara → `@validator`) rodam sozinhos até a recomendação de `feature:close`.
+- `/dev --step`: desarma o autopilot **só para esta feature** — para no handoff `@dev → @qa` mesmo em projeto com `auto_handoff: true`. Uma escolha por feature sempre vence a flag do projeto.
+- Sem token: segue o esquema/flag já ativo, se houver.
+
+Veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md) para a cadeia completa e as condições de parada.
+
+---
+
+## Opção `--help`
+
+Uma ativação com `--help` (`/dev --help`) imprime um resumo rápido — o que faz, quando usar, opções, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
+---
+
 ## Comandos CLI relacionados
 
 ```bash
@@ -124,8 +154,8 @@ aioson memory:summary . --last=5
 
 ## Handoff típico
 
-- **Vem de:** `@scope-check` (SMALL/MEDIUM) ou `@product` (MICRO)
-- **Vai para:** `@qa`
+- **Vem de:** `@sheldon` (SMALL) · `@orchestrator` (MEDIUM) · `@product` (MICRO)
+- **Vai para:** `@pentester` (MEDIUM, inline) → `@qa`; ou direto `@qa` (SMALL/MICRO)
 
 ---
 

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

@@ -83,6 +83,10 @@ cat .aioson/context/dev-state.md
 npx @jaimevalasek/aioson live:start . --tool=claude --agent=deyvin --no-launch
 ```
 
+## Opção `--help`
+
+Uma ativação com `--help` (`/deyvin --help`, ou `/pair --help`) imprime um resumo rápido — o que faz, quando usar, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
 ## Handoff típico
 
 - **Vem de:** `@dev` (quando uma sessão fica incompleta) ou `@neo` (quando detecta `in_progress`).

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

@@ -99,6 +99,10 @@ ls .aioson/context/bootstrap/
 cat .aioson/context/bootstrap/entities.md
 ```
 
+## Opção `--help`
+
+Uma ativação com `--help` (`/discover --help`) imprime um resumo rápido — o que faz, quando usar, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
 ## Handoff típico
 
 - **Vem de:** `@setup` (primeira vez) ou qualquer ponto quando o cache está stale.

package/docs/pt/4-agentes/discovery-design-doc.md

@@ -43,25 +43,27 @@ Ou seja: ele pode ser um atalho antes do ciclo completo **ou** uma etapa de segu
 
 ## Onde entra no workflow
 
-Fluxo exploratório manual:
+**Fluxo exploratório manual (qualquer tamanho):**
 
 ```
 @setup -> @discovery-design-doc -> próximo agente recomendado
 ```
 
-Fluxo SMALL atual:
+**Detour opt-in no SMALL** (quando você quer consolidar artefatos de spec antes do `@dev`):
 
 ```
-@product -> @analyst -> @scope-check(pre-dev) -> @architect -> @discovery-design-doc -> @dev -> @qa
+@product -> @sheldon -> @discovery-design-doc (opt-in) -> @dev -> @qa
 ```
 
-Fluxo MEDIUM atual:
+**Sub-agente ou detour no MEDIUM** (absorvido pelo `@architect` em merged mode, ou invocável como detour entre `@orchestrator` e `@dev`):
 
 ```
-@product -> @analyst -> @architect -> @discovery-design-doc -> @ux-ui -> @pm -> @orchestrator -> @scope-check(pre-dev) -> @dev -> @qa
+@product -> @orchestrator -> @discovery-design-doc (opt-in) -> @dev -> @pentester -> @qa
 ```
 
-O papel dele no meio da feature não é substituir `@analyst` nem `@architect`. Ele transforma esses artefatos em um pacote executável para implementação.
+> **Nota (v1.35.0):** nas lanes padrão, `@discovery-design-doc` não é um hop obrigatório. No SMALL, `@sheldon` já produz design-doc e readiness. No MEDIUM, `@architect` em modo merged também os produz. `@discovery-design-doc` continua disponível como detour quando você quer consolidação explícita pré-dev ou quando o request chegou vago e precisa de normalização antes de entrar no workflow.
+
+O papel dele no meio da feature não é substituir `@sheldon` nem `@orchestrator`. Ele transforma artefatos existentes em um pacote executável para implementação, ou normaliza um request vago antes de chamar o próximo agente.
 
 ---
 
@@ -70,23 +72,23 @@ O papel dele no meio da feature não é substituir `@analyst` nem `@architect`.
 ```
 Você > @discovery-design-doc
        Quero adicionar modo offline ao app mobile para que usuários possam
-       ver conteúdos sem internet.
-
-@discovery-design-doc > Normalizando request...
-                        Problema: usuários perdem acesso ao conteúdo sem conexão
-                        Escopo: modo leitura offline (não criação)
-
-                        Ambiguidades identificadas:
-                        - Quanto conteúdo cabe offline? (sem limite definido)
-                        - Sincronização automática ou manual?
-                        - Conflitos de versão se offline e online divergirem?
-
-                        Já definido:
-                        - Stack: React Native + SQLite local disponível
-                        - Auth: token pode sobreviver offline (não expira em 24h)
-
-@discovery-design-doc > Design doc criado em: .aioson/context/design-doc.md
-                        Readiness: MÉDIO — 3 ambiguidades precisam de decisão.
+       ver conteúdos sem internet.
+
+@discovery-design-doc > Normalizando request...
+                        Problema: usuários perdem acesso ao conteúdo sem conexão
+                        Escopo: modo leitura offline (não criação)
+
+                        Ambiguidades identificadas:
+                        - Quanto conteúdo cabe offline? (sem limite definido)
+                        - Sincronização automática ou manual?
+                        - Conflitos de versão se offline e online divergirem?
+
+                        Já definido:
+                        - Stack: React Native + SQLite local disponível
+                        - Auth: token pode sobreviver offline (não expira em 24h)
+
+@discovery-design-doc > Design doc criado em: .aioson/context/design-doc.md
+                        Readiness: MÉDIO — 3 ambiguidades precisam de decisão.
                         Recomendação: @product para fechar escopo antes de @dev.
 ```
 

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

@@ -77,6 +77,10 @@ npx @jaimevalasek/aioson workflow:next .
 npx @jaimevalasek/aioson memory:summary . --last=5
 ```
 
+## Opção `--help`
+
+Uma ativação com `--help` (`/neo --help`) imprime um resumo rápido — o que faz, quando usar, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
 ## Handoff típico
 
 - **Vem de:** qualquer ponto — @neo é válido em qualquer momento.

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

@@ -94,6 +94,12 @@ Você > @orache nutrição esportiva para atletas amadores
 
 ---
 
+## Opção `--help`
+
+Uma ativação com `--help` (`/orache --help`) imprime um resumo rápido — o que faz, quando usar, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
+---
+
 ## Handoff típico
 
 - **Vem de:** `@squad` (redirect automático) ou pedido direto do usuário