@jaimevalasek/aioson 1.30.2 → 1.36.0

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/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,7 +102,8 @@ 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.
@@ -124,8 +136,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/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/orchestrator.md

@@ -1,118 +1,164 @@
-# @orchestrator — Coordene lanes paralelas em projetos MEDIUM
-
-> **Para quem é:** quem trabalha em projetos MEDIUM e precisa dividir a implementação em frentes paralelas.
-> **Tempo de leitura:** 4 min.
-> **O que você vai sair sabendo:**
-> - O que é uma "lane" e quando paralelizar faz sentido
-> - Comandos CLI do sistema de lanes
-
----
-
-## Para que serve
-
-Em projetos MEDIUM, a implementação pode ser grande o suficiente para ter partes independentes — backend de autenticação e frontend de listagem, por exemplo — que podem acontecer em paralelo sem conflito. Tentar fazer isso manualmente sem coordenação é receita para conflitos de merge e arquivos sobrescritos.
-
-`@orchestrator` divide o trabalho em **lanes** (faixas de execução): cada lane tem seu escopo, seus arquivos permitidos, e seu estado independente. Ele garante que as lanes não escrevam nos mesmos arquivos e coordena o merge no final.
-
-**Regra dura:** `@orchestrator` só ativa em projetos MEDIUM. Para MICRO e SMALL, execução sequencial é o suficiente.
-
----
-
-## Quando invocar
-
-- Projetos MEDIUM, após `@pm`, quando há implementação paralelizável.
-- Quando você tem múltiplos devs (humanos ou IAs) trabalhando na mesma feature.
-- Quando uma feature tem frentes claramente independentes (ex: API + UI + migrations).
-
----
-
-## Quando NÃO invocar
-
-- Projeto MICRO ou SMALL → ele mesmo recusa e te avisa.
-- A feature tem dependências lineares fortes → implemente sequencialmente com `@dev`.
-
----
-
-## Diálogo típico
-
-```
-Você > @orchestrator
-
-@orchestrator > Verificando classificação... MEDIUM. OK.
-                Lendo architecture.md, tasks.md, ui-spec.md...
-                
-                Dividindo em 3 lanes:
-                Lane 1 — backend
-                  Escopo: src/models/payment.js, src/services/payment-service.js, src/routes/checkout.js
-                Lane 2 — frontend
-                  Escopo: src/views/checkout/, src/components/PaymentForm/
-                Lane 3 — migrations
-                  Escopo: db/migrations/add-payment-table.sql
-                
-                Guard configurado: lanes não podem escrever fora do próprio escopo.
-                
-                $ aioson parallel:init .          ✓
-                $ aioson parallel:assign .        ✓
-                Workspace pronto em .aioson/context/parallel/
-                
-                Quando terminar cada lane, rode:
-                  aioson parallel:status .
-                  aioson parallel:merge . --apply
-```
-
----
-
-## Saídas em disco
-
-| Arquivo/Diretório | Conteúdo |
-|---|---|
-| `.aioson/context/parallel/lane-1.md` | Escopo e estado da lane 1 |
-| `.aioson/context/parallel/lane-2.md` | Escopo e estado da lane 2 |
-| `.aioson/context/parallel/lane-N.md` | ... |
-
----
-
-## Como ele lê seu projeto
-
-- `.aioson/context/project.context.md` — confirma `classification: MEDIUM`
-- `.aioson/context/discovery.md`, `architecture.md`, `prd.md`, `ui-spec.md`
-- `.aioson/context/implementation-plan-{slug}.md` — se existir
-- `.aioson/context/parallel/` — ao retomar sessão
-
----
-
-## Comandos CLI relacionados
-
-```bash
-# Inicializar workspace de lanes
-aioson parallel:init .
-
-# Distribuir escopos
-aioson parallel:assign .
-
-# Ver progresso de cada lane
-aioson parallel:status .
-
-# Validar que uma lane está autorizada a escrever num arquivo
-aioson parallel:guard . --lane=1 --paths=src/models/payment.js
-
-# Merge final (só quando todas as lanes estão prontas)
-aioson parallel:merge . --apply
-
-# Corrigir workspace quebrado
-aioson parallel:doctor . --fix
-```
-
----
-
-## Handoff típico
-
-- **Vem de:** `@pm`
-- **Vai para:** `@dev` (em cada lane)
-
----
-
-## Próximo passo
-
-- [Ficha do @dev](./dev.md) — executa dentro de cada lane
-- [Decisões iniciais: MEDIUM](../2-comecar/decisoes-iniciais.md#medium--workflow-completo)
+# @orchestrator — Maestro de spec para projetos MEDIUM
+
+> **Para quem é:** quem trabalha em projetos MEDIUM e precisa de uma autoridade única de spec que coordene a fase de descoberta e planejamento.
+> **Tempo de leitura:** 5 min.
+> **O que você vai sair sabendo:**
+> - Por que `@orchestrator` é o maestro do MEDIUM (não apenas coordenador de execução)
+> - Como funciona o fan-out para sub-agentes e a consolidação do pacote de spec
+> - Quando (e como) usar lanes paralelas pós-spec
+
+---
+
+## Para que serve
+
+Em projetos MEDIUM, a especificação envolve múltiplas dimensões — domínio, arquitetura, UX, backlog — que precisam ser coordenadas e verificadas antes que o `@dev` comece. Tentar gerenciar cada agente de spec manualmente, em sequência, é lento e sujeito a drift entre artefatos.
+
+`@orchestrator` assume o papel de **maestro de spec**: ele dispara `@analyst`, `@architect` e `@pm` (e `@ux-ui` quando a feature tem UI pesada) como **sub-agentes em fan-out**, depois **consolida, verifica e retrabaha** os artefatos deles num único pacote de spec validado — com Gates A/B/C aprovados — e só então passa o bastão para o `@dev`.
+
+**Regra dura:** `@orchestrator` só ativa em projetos MEDIUM. Para MICRO e SMALL, o `@sheldon` cobre a spec sozinho.
+
+> SMALL = `@sheldon` (vertical, solo). MEDIUM = `@orchestrator` (horizontal, fan-out). Mesma ideia — uma autoridade única de spec — formas diferentes.
+
+---
+
+## O papel duplo do `@orchestrator`
+
+### 1. Maestro de spec (papel principal no MEDIUM)
+
+Sequência padrão da lane MEDIUM:
+
+```
+@product → @orchestrator → @dev → @pentester → @qa
+```
+
+O `@orchestrator`:
+1. Lê o PRD e confirma classificação MEDIUM.
+2. (Opcional) Dispara `@sheldon` como pré-etapa para endurecer o PRD antes do fan-out.
+3. Fan-out: dispara `@analyst` + `@architect` + `@pm` como sub-agentes (+ `@ux-ui` se UI-heavy).
+4. Consolida os artefatos recebidos.
+5. Verifica consistência entre eles (detecta drift, gaps, conflitos).
+6. Retrabaha as inconsistências detectadas.
+7. Produz o pacote de spec consolidado (Gates A/B/C + plano de implementação faseado + harness-contract).
+8. Passa para `@dev`.
+
+### 2. Coordenador de lanes paralelas (papel secundário, pós-spec)
+
+Quando a implementação de uma feature MEDIUM tem frentes genuinamente independentes — backend, UI, migrations — o `@orchestrator` pode dividir o trabalho em **lanes** após o pacote de spec estar consolidado:
+
+- Cada lane tem escopo próprio, arquivos permitidos e estado independente.
+- `@dev` implementa uma lane por sessão.
+- `aioson parallel:merge` faz o merge determinístico no final.
+
+---
+
+## Quando invocar
+
+- Projetos MEDIUM, após `@product` (pacote de spec ainda não existe).
+- Quando você quer que a fase de spec rode de forma coordenada, com verificação cruzada entre sub-agentes, sem gerenciar cada um manualmente.
+
+---
+
+## Quando NÃO invocar
+
+- Projeto MICRO ou SMALL → `@sheldon` cobre sozinho; `@orchestrator` recusa e avisa.
+- Feature com pacote de spec já consolidado e você só quer dividir a implementação em lanes → use `aioson parallel:init` diretamente.
+
+---
+
+## Diálogo típico
+
+```
+Você > @orchestrator
+
+@orchestrator > Verificando classificação... MEDIUM. Confirmado.
+                Lendo prd-mvp.md...
+                
+                Iniciando fan-out de spec:
+                ├── @analyst   → mapeamento de domínio e entidades
+                ├── @architect → estrutura técnica, libs, integração
+                └── @pm        → backlog, user stories, plano de implementação
+                
+                (+ @ux-ui — feature tem UI pesada, adicionando ao fan-out)
+                
+                [sub-agentes executados]
+                
+                Consolidando artefatos...
+                Verificando consistência:
+                ✓ Entidades do @analyst alinhadas com as decisões do @architect
+                ⚠ @pm criou US-07 (notificação SMS) sem AC verificável — retrabalhando
+                ✓ @ux-ui spec alinhada com componentes declarados em architecture.md
+                
+                Gates A/B/C aprovados.
+                Pacote de spec consolidado:
+                  .aioson/context/requirements-mvp.md
+                  .aioson/context/architecture.md
+                  .aioson/context/design-doc-mvp.md
+                  .aioson/context/implementation-plan-mvp.md
+                  .aioson/context/parallel/harness-contract.json
+                
+                Próximo: @dev.
+```
+
+---
+
+## `@sheldon` como pré-etapa (opcional)
+
+Se o PRD tiver gaps ou decisões técnicas difíceis, rode `@sheldon` antes de `@orchestrator` para endurecer o PRD. Também é possível configurar `@orchestrator` para disparar `@sheldon` como um stream do fan-out.
+
+```
+@product → @sheldon (endurecimento de PRD) → @orchestrator → @dev → @pentester → @qa
+```
+
+---
+
+## Saídas em disco
+
+| Arquivo/Diretório | Conteúdo |
+|---|---|
+| `.aioson/context/requirements-{slug}.md` | Domínio consolidado (de @analyst) |
+| `.aioson/context/architecture.md` | Decisões técnicas (de @architect) |
+| `.aioson/context/design-doc-{slug}.md` | Spec de UI/UX (de @ux-ui, quando UI-heavy) |
+| `.aioson/context/implementation-plan-{slug}.md` | Plano faseado (de @pm) |
+| `.aioson/context/parallel/harness-contract.json` | Contrato de sucesso (Gates A/B/C) |
+| `.aioson/context/parallel/lane-*.md` | Lanes de execução (quando paralelização é usada) |
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/context/project.context.md` — confirma `classification: MEDIUM`
+- `.aioson/context/prd-{slug}.md` — entrada para o fan-out de spec
+- `.aioson/context/parallel/` — ao retomar sessão com lanes já criadas
+
+---
+
+## Comandos CLI relacionados
+
+```bash
+# Ver progresso de cada lane
+aioson parallel:status .
+
+# Validar que uma lane está autorizada a escrever num arquivo
+aioson parallel:guard . --lane=1 --paths=src/models/payment.js
+
+# Merge final (quando todas as lanes estão prontas)
+aioson parallel:merge . --apply
+
+# Corrigir workspace quebrado
+aioson parallel:doctor . --fix
+```
+
+---
+
+## Handoff típico
+
+- **Vem de:** `@product`
+- **Vai para:** `@dev`
+
+---
+
+## Próximo passo
+
+- [Ficha do @dev](./dev.md) — executa o plano produzido pelo orchestrator
+- [Ficha do @sheldon](./sheldon.md) — autoridade de spec para SMALL; pré-etapa opcional no MEDIUM
+- [Decisões iniciais: MEDIUM](../2-comecar/decisoes-iniciais.md#medium--maestro-lane)

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

@@ -35,10 +35,10 @@ Os dois modos produzem `security-findings-{slug}.json` com a mesma estrutura, ma
 
 ## Quando invocar
 
-- Antes de publicar uma feature para produção.
-- Quando a feature toca autenticação, pagamentos, upload de arquivos, ou dados sensíveis.
-- Quando você quer um audit point de segurança antes de uma release.
+- **MEDIUM (padrão):** `@pentester` é **inline** na lane MEDIUM — entra entre `@dev` e `@qa` como etapa padrão, não apenas opt-in.
+- **SMALL/MICRO (opt-in):** ative manualmente quando a feature toca autenticação, pagamentos, upload de arquivos, ou dados sensíveis.
 - Quando o `@tester` encontrou indícios de problemas de segurança.
+- Quando você quer um audit point de segurança antes de uma release em qualquer tamanho.
 
 ---
 
@@ -119,8 +119,8 @@ Você > checkout-stripe
 
 ## Handoff típico
 
-- **Vem de:** você diretamente, ou `@tester` (que encontrou indício)
-- **Vai para:** `@dev` (para corrigir findings HIGH/MEDIUM) → `@qa` (re-validação)
+- **Vem de:** `@dev` (na lane MEDIUM, onde é inline) — ou você diretamente / `@tester` (detour em SMALL/MICRO)
+- **Vai para:** `@dev` (para corrigir findings HIGH/MEDIUM) → `@qa` (re-validação final)
 
 ---
 

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

@@ -19,19 +19,27 @@ Sua regra interna de ouro: máximo 2 páginas. Se o output excede isso, ele est
 
 ## Dois contextos de ativação
 
-### 1. Feature workflow MEDIUM (pré-dev — v1.22.0+)
+### 1. Feature workflow MEDIUM — sub-agente do `@orchestrator` (v1.35.0)
 
-No workflow de feature MEDIUM, `@pm` aparece logo antes do `@dev` — após `@discovery-design-doc` e antes do `@scope-check` pré-dev. Aqui sua responsabilidade é produzir o `implementation-plan-{slug}.md` (Gate C) que o `@dev` precisa para começar.
+No workflow MEDIUM padrão (maestro lane), `@pm` é disparado pelo `@orchestrator` como parte do fan-out de spec. O `@orchestrator` consolida e verifica o plano produzido pelo `@pm` antes de passar para `@dev`.
 
 ```
-@analyst → @scope-check → @architect → @discovery-design-doc → @pm → STOP → /dev
+@orchestrator fan-out: @analyst + @architect + @pm + @ux-ui → consolida → @dev
 ```
 
-O Gate C só é aprovado com o plano pronto. Se o `@pm` for pulado em features MEDIUM, o `gate:check --gate=C` vai bloquear o `@dev`.
+O Gate C (plano de implementação aprovado) é verificado pelo `@orchestrator` antes do handoff.
 
-### 2. Projeto MEDIUM (modo tradicional)
+### 2. Detour opt-in (qualquer tamanho)
 
-Para o projeto completo (configuração inicial), `@pm` entra após `@ux-ui` e antes de `@orchestrator` — priorizando e sequenciando as histórias do backlog.
+Quando você quer criar o backlog e plano de implementação manualmente, sem passar pelo `@orchestrator`, pode invocar `@pm` diretamente após a fase de spec. Útil quando o `@sheldon` (SMALL) produziu o plano mas você quer expandir as user stories.
+
+### 3. Fluxo legado (escape hatch full-merged)
+
+Para quem prefere gerenciar cada sub-agente manualmente no MEDIUM:
+
+```
+@analyst → @architect → @discovery-design-doc → @pm → @orchestrator (lanes only) → @dev
+```
 
 ---
 
@@ -117,7 +125,7 @@ aioson workflow:status .
 **Feature MEDIUM (pré-dev):**
 - **Vem de:** `@discovery-design-doc`
 - **Produz:** `implementation-plan-{slug}.md` (Gate C)
-- **Vai para:** STOP — desenvolvedor faz `/compact` e ativa `/dev` quando continuar a mesma feature; usa `/clear` só para reset forte
+- **Vai para:** STOP — desenvolvedor faz `/compact` e ativa `/dev` quando continuar a mesma feature; usa `/clear` só para reset forte
 
 **Projeto MEDIUM (modo completo):**
 - **Vem de:** `@ux-ui`