@jaimevalasek/aioson 1.30.2 → 1.36.0

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

@@ -1,99 +1,166 @@
-# @sheldon — Análise técnica profunda e revisão de PRD
-
-> **Para quem é:** quem quer uma segunda opinião técnica de peso antes de começar a implementar.
-> **Tempo de leitura:** 4 min.
-> **O que você vai sair sabendo:**
-> - Quando o @sheldon é necessário e o que ele entrega.
-> - Como ele se encaixa entre @product e @analyst.
-
-## Para que serve
-
-O `@product` escreveu o PRD. Parece completo. Mas há gaps que só aparecem quando alguém com mentalidade técnica lê criticamente: campos de negócio não especificados, fluxos de erro ausentes, premissas implícitas que vão virar bugs.
-
-O `@sheldon` faz essa revisão crítica antes que o `@analyst`, o `@architect` e o `@dev` comecem. Ele pode ser ativado múltiplas vezes sobre o mesmo PRD — cada rodada enriquece mais. É o guardião da qualidade do PRD, não o implementador.
-
-Recentemente (commit `5b1edd6`), foi dividido em módulos on-demand, incluindo detecção de MER (missing entity relationships) — ele agora identifica relacionamentos entre entidades que o PRD não declara explicitamente.
-
-## Quando invocar
-
-- PRD parece completo mas você suspeita de gaps.
-- Feature é complexa — regras de negócio não-óbvias, múltiplos fluxos.
-- Antes de passar para `@analyst` num projeto SMALL ou MEDIUM importante.
-- Quer que alguém "tente quebrar" a spec antes do dev.
-- Há briefing aprovado (`briefing_source`) e quer garantir que os gaps do briefing foram fechados.
-
-## Quando NÃO invocar
-
-- Feature simples MICRO — é overhead desnecessário (Artigo II da Constitution).
-- PRD ainda não existe — `@product` primeiro.
-- Implementação já foi feita — `@pentester` ou `@qa` são mais adequados agora.
-
-## Diálogo típico
-
-```
-Você > @sheldon
-
-@sheldon > Lendo .aioson/context/prd-checkout-stripe.md...
-           Lendo briefing source: .aioson/briefings/marketplace-v1/briefings.md...
-
-           Análise de qualidade do PRD:
-
-           GAPS ENCONTRADOS:
-           - AC-03 não especifica o que acontece se o pagamento falhar após 3 tentativas
-             (fluxo de retry? bloqueio temporário? sem menção)
-           - Entidade "OrderItem" referenciada mas não modelada no PRD
-           - Regra de cancelamento ausente (o briefing sinalizava isso como gap aberto)
-
-           RISCOS:
-           - Webhook handler sem idempotência — pode duplicar confirmações
-           - Email de confirmação: qual provider? Sem fallback documentado
-
-           RECOMENDAÇÃO:
-           - Enriquecer o PRD in-place (gaps são fecháveis sem replanejamento)
-           - Abrir plano de execução para o webhook (risco técnico real)
-
-           Posso enriquecer o PRD agora ou prefere revisar os gaps primeiro?
-```
-
-## Saídas em disco
-
-O `@sheldon` decide entre **enriquecer in-place** ou **criar plano faseado** dependendo do tamanho do gap. Resultado:
-
-| Arquivo | Quando | O que contém |
-|---|---|---|
-| `.aioson/context/prd.md` (ou `prd-{slug}.md`) | Enriquecimento in-place | PRD com gaps fechados |
-| `.aioson/context/sheldon-enrichment.md` | Sempre | Registro das rodadas (para re-entrada) |
-| `.aioson/plans/{slug}/phase-1.md`, `phase-2.md`, ... | Quando o escopo é grande demais para uma única implementação | Plano de execução faseada lido pelos agentes seguintes (`@analyst` em diante) |
-| `.aioson/plans/{slug}/harness-contract.json` | Junto do phased plan | Contrato binário de sucesso (consumido por `@validator`) |
-| `.aioson/plans/{slug}/progress.json` | Junto do phased plan | Status corrente das fases |
-
-**Re-entrante:** se `sheldon-enrichment.md` já existir, o `@sheldon` detecta e oferece nova rodada sem refazer do zero. Você pode invocá-lo 2, 3, N vezes — cada rodada fecha mais gaps.
-
-**Campo `verification` no contrato (v1.24.0+):** ao gerar o `harness-contract.json`, o `@sheldon` agora autora um comando de shell `verification` para **todo critério `binary:true` mecanicamente verificável** (exit 0 = pass). Ele prefere o test runner do próprio projeto, mira em comandos determinísticos e cross-platform. Com isso, `aioson harness:check` consegue verificar o critério de forma determinística, fora do `self:loop`, e o `@validator` copia o exit code verbatim no veredicto. Contratos legados sem o campo continuam válidos (o `@validator` cai no julgamento por LLM para esses critérios).
-
-## Como ele lê seu projeto
-
-1. `.aioson/context/project.context.md` — stack e classificação.
-2. `.aioson/context/prd.md` ou `prd-{slug}.md` — o PRD alvo.
-3. `.aioson/context/features.md` — status das features (não revisa PRDs de features já implementadas).
-4. `.aioson/context/sheldon-enrichment.md` — histórico de enriquecimentos (re-entrada).
-5. `.aioson/briefings/{slug}/briefings.md` — se `briefing_source` está no PRD.
-6. `plans/*.md` e `prds/*.md` — fontes de pesquisa pré-produção do usuário.
-
-> **Fast path de ativação (v1.29.0):** ativar `@sheldon` "seco", sem PRD/slug, carrega **só** o `project.context.md`, a listagem de nomes dos `prd*.md` e a tabela `features.md` — apresenta a lista de PRDs para seleção e para. O conteúdo do PRD e o índice de brains entram só depois da escolha do alvo. Veja [Carregamento seletivo de contexto](../5-referencia/memoria-e-contexto.md#carregamento-seletivo-de-contexto-v1290).
-
-## Handoff típico
-
-- **Vem de:** `@product` (PRD gerado) — pode ser ativado N vezes antes de ir adiante.
-- **Vai para:** `@analyst` → `@architect` → `@dev`.
-
-## Detalhe: MER detection
-
-O @sheldon agora detecta automaticamente **relacionamentos de entidade ausentes** no PRD. Se o PRD menciona `Order` e `Customer` mas não modela a relação entre eles, ele sinaliza — o `@analyst` vai precisar modelar, melhor detectar aqui.
-
-## Próximo passo
-
-- Trilha canônica de feature completa onde o `@sheldon` é peça-chave → [Feature completa com @sheldon](../3-receitas/feature-completa-com-sheldon.md)
-- PRD ainda não existe → [@product](./product.md)
-- Estrutura de planos que o `@sheldon` cria → [SDD: planos e estrutura](../5-referencia/sdd-planos-e-estrutura.md)
-- Termos como "gap", "AC" e "PRD" → [Glossário](../1-entender/glossario.md)
+# @sheldon — Autoridade única de spec (SMALL) e endurecedor de PRD
+
+> **Para quem é:** quem trabalha em projetos SMALL (o caso mais comum) e quer a fase de spec completa numa única passada; ou quem quer análise técnica profunda e endurecimento de PRD em qualquer tamanho de projeto.
+> **Tempo de leitura:** 5 min.
+> **O que você vai sair sabendo:**
+> - Por que `@sheldon` é a autoridade única de spec no SMALL (v1.35.0)
+> - O que ele produz numa passada e quais gates ele aprova
+> - Como usá-lo no MEDIUM para endurecer o PRD antes do fan-out
+
+---
+
+## Para que serve
+
+### SMALL — autoridade única de spec (papel principal)
+
+Em projetos SMALL, toda a fase de especificação — requisitos, decisões técnicas, design doc, readiness, plano de implementação e contrato de harness — pode (e deve) ser produzida por **um único agente em uma única passada**. Isso elimina hops, evita drift entre artefatos e entrega ao `@dev` um pacote coeso e já verificado.
+
+`@sheldon` é essa autoridade. Ele executa verticalmente: lê o PRD, varre o codebase, detecta gaps, pesquisa fontes externas quando necessário, e produz o pacote de spec completo com Gates A/B/C aprovados antes de passar o bastão.
+
+**Lane SMALL (padrão em v1.35.0):**
+
+```
+@product → @sheldon → @dev → @qa
+```
+
+### Qualquer lane — endurecimento de PRD
+
+Em qualquer tamanho de projeto, `@sheldon` pode ser ativado após `@product` para fazer **gap analysis, pesquisa web, sizing técnico e endurecimento do PRD** — antes do fan-out de `@orchestrator` no MEDIUM ou antes de qualquer outra etapa.
+
+---
+
+## O que `@sheldon` produz numa passada (SMALL)
+
+| Artefato | Descrição |
+|---|---|
+| PRD enriquecido (in-place) | Gaps detectados e preenchidos diretamente no `prd-{slug}.md` |
+| `sheldon-enrichment-{slug}.md` | Registro das rodadas de enriquecimento |
+| `requirements-{slug}.md` | Entidades, regras de negócio, edge cases, MER (missing entity relationships) |
+| `architecture.md` (atualizado) | Decisões técnicas: estrutura, libs, integração |
+| `implementation-plan-{slug}.md` | Plano faseado com fases numeradas |
+| `harness-contract.json` | Contrato de sucesso com critérios RG-* para `@validator` |
+| Gates A/B/C aprovados | Pré-condições verificadas antes do `@dev` iniciar |
+
+---
+
+## Quando invocar
+
+- Projetos **SMALL** (classificação 2–3), após `@product` — é o passo padrão da lane.
+- PRD tem gaps ou decisões difíceis e você quer análise técnica antes de implementar.
+- Você quer enriquecer um PRD com pesquisa de fontes externas (Stripe docs, RFCs, posts técnicos).
+- Como pré-etapa opcional antes de `@orchestrator` no MEDIUM (endurece o PRD antes do fan-out).
+- Você quer **revisão crítica do PRD**: campos de negócio não especificados, fluxos de erro ausentes, premissas implícitas que podem virar bugs.
+
+---
+
+## Quando NÃO invocar
+
+- Projeto MICRO sem decisões técnicas novas → `@dev` lê o PRD diretamente.
+- PRD ainda não existe → `@product` primeiro.
+- Spec já está completa e Gates A/B/C aprovados → vá direto para `@dev`.
+- Implementação já foi feita → `@pentester` ou `@qa` são mais adequados agora.
+
+---
+
+## Diálogo típico (SMALL)
+
+```
+Você > @sheldon
+
+@sheldon > Lendo prd-checkout-stripe.md...
+           Varrendo codebase: models, services, routes...
+           
+           Gaps detectados no PRD:
+           1. Sem tratamento de downgrade de plano (só upgrade)
+           2. Sem política de proration na troca de plano
+           3. Webhook Stripe sem política de retry/idempotency
+           4. Nenhum AC para falha de cobrança após 3 tentativas (dunning)
+           5. Entidade "OrderItem" referenciada mas não modelada no PRD
+           
+           Fontes externas? [URL / arquivo local / "não"]
+
+Você > docs.stripe.com/billing/subscriptions/upgrade-downgrade
+
+@sheldon > [pesquisa, lê, cita]
+           
+           Enriquecendo PRD in-place (gaps 1 e 2 são decisões de produto)...
+           prd-checkout-stripe.md atualizado.
+           
+           Produzindo requirements, architecture, implementation-plan...
+           
+           Gate A (requisitos verificáveis): ✓
+           Gate B (decisões técnicas): ✓
+           Gate C (plano faseado + harness-contract com RG-*): ✓
+           
+           Pacote de spec pronto:
+             .aioson/context/requirements-checkout-stripe.md
+             .aioson/context/architecture.md
+             .aioson/context/implementation-plan-checkout-stripe.md
+             .aioson/context/sheldon-enrichment-checkout-stripe.md
+             .aioson/plans/checkout-stripe/harness-contract.json
+           
+           Próximo: @dev.
+```
+
+---
+
+## `@sheldon` no MEDIUM
+
+No MEDIUM, `@sheldon` pode atuar de duas formas:
+
+1. **Pré-etapa antes de `@orchestrator`:** endurece o PRD com análise técnica e pesquisa web antes que `@orchestrator` dispare o fan-out.
+2. **Stream do fan-out do `@orchestrator`:** `@orchestrator` o inclui como um dos sub-agentes para análise técnica profunda.
+
+```
+@product → @sheldon (endurece PRD) → @orchestrator → @dev → @pentester → @qa
+```
+
+---
+
+## Múltiplas rodadas
+
+`@sheldon` pode ser invocado N vezes no mesmo PRD. Ao detectar `sheldon-enrichment-{slug}.md` existente, ele entra em modo de **re-enrichment**: lê o que mudou desde a última rodada e oferece nova análise incremental, sem refazer do zero.
+
+---
+
+## Saídas em disco
+
+| Arquivo | Criado por | Consumido por |
+|---|---|---|
+| `prd-{slug}.md` | `@sheldon` (atualiza in-place) | `@dev`, `@qa` |
+| `sheldon-enrichment-{slug}.md` | `@sheldon` | `@sheldon` (re-entrada) |
+| `requirements-{slug}.md` | `@sheldon` | `@dev`, `@qa` |
+| `architecture.md` | `@sheldon` (atualiza) | `@dev`, `@qa` |
+| `implementation-plan-{slug}.md` | `@sheldon` | `@dev` |
+| `harness-contract.json` | `@sheldon` | `@validator` |
+
+**Campo `verification` no contrato (v1.24.0+):** ao gerar o `harness-contract.json`, o `@sheldon` autora um comando de shell `verification` para todo critério `binary:true` mecanicamente verificável. Com isso, `aioson harness:check` consegue verificar o critério de forma determinística fora do self-loop.
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/context/project.context.md` — stack, classificação
+- `.aioson/context/prd-{slug}.md` — o PRD alvo
+- `.aioson/context/sheldon-enrichment-{slug}.md` — histórico de enriquecimentos (re-entrada)
+- `.aioson/context/architecture.md` — estado atual da arquitetura
+- `.aioson/context/bootstrap/` — cache semântico do `@discover` (quando disponível)
+- `.aioson/briefings/{slug}/briefings.md` — se `briefing_source` está no PRD
+- Fontes externas — URLs e arquivos que você fornecer explicitamente
+- Código-fonte diretamente (models, schemas, services)
+
+---
+
+## Handoff típico
+
+- **Vem de:** `@product`
+- **Vai para:** `@dev` (SMALL) — ou `@orchestrator` (MEDIUM, como pré-etapa)
+
+---
+
+## Próximo passo
+
+- [Ficha do @dev](./dev.md) — implementa com base no pacote de spec produzido
+- [Ficha do @orchestrator](./orchestrator.md) — maestro de spec para MEDIUM
+- [Receita: Feature completa](../3-receitas/feature-completa-com-sheldon.md) — fluxo prático com todos os artefatos
+- [SDD: planos e estrutura](../5-referencia/sdd-planos-e-estrutura.md) — mapa de todos os artefatos

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

@@ -16,11 +16,14 @@ Quando o dev implementa a UI sem especificação, ele toma decisões de design n
 
 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.
 
+> **Posição no fluxo (v1.35.0):** no MEDIUM, `@ux-ui` é disparado como **sub-agente de fan-out** pelo `@orchestrator` quando a feature tem UI pesada — você não precisa invocá-lo manualmente. No SMALL e no MICRO, `@dev` aplica o design skill diretamente; `@ux-ui` fica como detour opt-in quando você quer especificação de UI detalhada antes da implementação.
+
 ---
 
 ## Quando invocar
 
-- Projetos MEDIUM com UI, após `@architect`.
+- **No MEDIUM com UI pesada:** `@orchestrator` o dispara como sub-agente automaticamente — você não precisa invocar manualmente.
+- **Detour explícito (qualquer tamanho):** quando você quer especificação de componentes e tokens antes do `@dev`, em vez de deixar o `@dev` inferir do design skill.
 - 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`).
@@ -29,7 +32,7 @@ Ele é guiado pelo design skill do projeto — se `clean-saas-ui` estiver config
 
 ## Quando NÃO invocar
 
-- Projeto MICRO ou SMALL sem UI complexa → `@dev` pode usar o design skill direto.
+- Projeto MICRO ou SMALL em lane padrão → `@dev` aplica o design skill direto; `@ux-ui` só se quiser spec detalhada como detour.
 - A feature é backend puro (API, script) → não há UI para especificar.
 - Você quer clonar o design de um site existente → use `@site-forge`.
 
@@ -98,8 +101,8 @@ ls .aioson/skills/design/
 
 ## Handoff típico
 
-- **Vem de:** `@architect`
-- **Vai para:** `@pm` (MEDIUM)
+- **Vem de:** `@orchestrator` (como sub-agente no MEDIUM) ou invocação explícita como detour
+- **Vai para:** resultado consolida para `@orchestrator` quando em sub-agente; ou `@dev` quando usado como detour direto
 
 ---
 

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

@@ -70,11 +70,17 @@ feature inicia (via workflow:next ou manualmente)
 dossier:init criado → dossier.json
         │
         ▼
-@product → spec.md
+@product → prd.md
         │
         ▼
-@dev implementa → dev-state.md (atualizado a cada ponto)
-        │          handoff-protocol.json (escrito no handoff)
+autoridade de spec:
+  SMALL → @sheldon (pacote de spec completo em uma passada)
+  MEDIUM → @orchestrator (fan-out: @analyst + @architect + @pm + @ux-ui → consolida)
+        │
+        ▼  Gates A/B/C aprovados
+@dev implementa por fases → dev-state.md (atualizado a cada fase)
+        │    ↕ verificação por fase (sub-agente leve, auto-continue)
+        │                       handoff-protocol.json (escrito no handoff)
         │
         ▼
 [sessão nova / agente novo]
@@ -84,10 +90,13 @@ dossier:init criado → dossier.json
         └─ next agent lê artifact_uris do handoff-protocol
         │
         ▼
-@qa → testa → devolve para @dev se houver falhas (ciclo autônomo, cap 2)
+@pentester (MEDIUM, inline) → findings → @dev corrige → @pentester re-varre
+        │
+        ▼
+@qa → runtime smoke gate + ACs → devolve para @dev se houver falhas (ciclo autônomo, cap 2)
         │
         ▼
-@validator → gate final → feature:close
+@validator → verifica contra harness-contract em contexto isolado → gate final → feature:close
         │
         ▼
 dossier arquivado em .aioson/context/done/

package/docs/pt/5-referencia/comandos-cli.md

@@ -1877,7 +1877,7 @@ aioson harness:retro . --last=5
 aioson harness:retro . --feature=checkout --json
 ```
 
-Saída em `.aioson/context/retro/checkout.md`. Fontes mineradas: QA reports, planos de correção, trilha FAIL→PASS do dossier, eventos de execução, tentativas, assinaturas de falha e devlogs. Operação de leitura — arquivos-fonte nunca são alterados.
+Saída em `.aioson/context/retro/checkout.md`. Fontes mineradas: QA reports, reports de verificação de implementação (apenas findings não confirmatórios do `Machine Report`), planos de correção, trilha FAIL→PASS do dossier, eventos de execução, tentativas, assinaturas de falha e devlogs. Raw auditor output, stderr, prompts e texto de evidence não são minerados. Operação de leitura — arquivos-fonte nunca são alterados.
 
 ```bash
 # Exibir prévia de um artefato com truncação segura

package/docs/pt/5-referencia/harness-retro.md

@@ -55,11 +55,12 @@ Usado principalmente na interface de feedback do `self:loop` quando um critério
 
 ## Fontes mineradas
 
-O `harness:retro` lê sete fontes por feature:
+O `harness:retro` lê oito fontes por feature:
 
 | Fonte | O que captura |
 |---|---|
 | Relatórios QA | Falhas e severidades de `@qa` |
+| Reports de verificação de implementação | Findings não confirmatórios do `Machine Report` (`DOES_NOT_CONFIRM`, `PARTIAL`, `NOT_VERIFIED`); não minera raw output, stderr, prompts nem texto de evidence |
 | Planos de correção | Correções aplicadas por ciclo |
 | Trilha do dossier | Ciclos FAIL→PASS do Agent Trail |
 | `execution_events` | Eventos de telemetria do loop |

package/docs/pt/5-referencia/sdd-automation-scripts.md

@@ -62,9 +62,9 @@ Detecta a classificação da feature (MICRO / SMALL / MEDIUM) automaticamente a
 | Integrações externas | nenhuma | 1 | 2+ |
 | Regras de negócio | simples | moderadas | complexas |
 
-- **0–1:** MICRO — só `@dev`, sem fases
-- **2–3:** SMALL — `@product → @analyst → @dev → @qa`
-- **4–6:** MEDIUM — adiciona `@architect`, paralelismo, conformance
+- **0–1:** MICRO — `@product → @dev → @qa`, sem fase de spec formal
+- **2–3:** SMALL (lean) — `@product → @sheldon → @dev → @qa`
+- **4–6:** MEDIUM (maestro) — `@product → @orchestrator → @dev → @pentester → @qa`
 
 **Flags:**
 
@@ -395,9 +395,9 @@ Monta e executa o plano de agentes para uma feature com base na classificação.
 
 | Tier | Passos |
 |---|---|
-| MICRO | `@dev` |
-| SMALL | `@product → @analyst → @dev → @qa` |
-| MEDIUM | `@product → @analyst → @architect → gate:check C → @dev (por fase) → @qa` |
+| MICRO | `@product → @dev → @qa` |
+| SMALL | `@product → @sheldon → @dev → @qa` |
+| MEDIUM | `@product → @orchestrator → @dev → @pentester → @qa` |
 
 **Flags:**
 

package/docs/pt/5-referencia/sdd-framework.md

@@ -54,31 +54,68 @@ Fases do SDD:
 Specify → Research → Requirements → Design → Tasks → Execute → State
 ```
 
-## Profundidade por classificação
+## As 3 lanes padrão (v1.35.0)
+
+O SDD não escala pelo número de agentes — escala pelas **lanes**: cada classificação tem uma lane com uma autoridade única de spec.
+
+| Lane | Classificação | Cadeia padrão |
+|---|---|---|
+| **MICRO** | 0–1 pts | `@product → @dev → @qa` |
+| **SMALL — lean (padrão)** | 2–3 pts | `@product → @sheldon → @dev → @qa` |
+| **MEDIUM — maestro** | 4–6 pts | `@product → @orchestrator → @dev → @pentester → @qa` |
+
+**Autoridade única de spec:**
+- **SMALL:** `@sheldon` (vertical / solo) — produz requirements + decisões técnicas + design-doc + readiness + implementation-plan + harness-contract em uma passada.
+- **MEDIUM:** `@orchestrator` (horizontal / fan-out) — dispara `@analyst` + `@architect` + `@pm` (+ `@ux-ui` quando UI-heavy) como sub-agentes, consolida e verifica os artefatos, e entrega o pacote de spec com Gates A/B/C aprovados.
 
-A beleza do SDD é que ele se contrai para projetos pequenos:
+> `@analyst`, `@architect`, `@pm`, `@discovery-design-doc`, `@scope-check` e `@ux-ui` **não são hops padrão** — são detours opt-in ou sub-agentes do fan-out do `@orchestrator`. Nenhum foi removido; apenas deixaram de ser obrigatórios no caminho padrão.
 
-| Fase | MICRO | SMALL | MEDIUM |
+## Profundidade por classificação
+
+| Fase | MICRO | SMALL (lean) | MEDIUM (maestro) |
 |---|---|---|---|
-| Specify (PRD lite) | obrigatória | obrigatória | obrigatória |
-| Research (@sheldon) | opcional | recomendada | obrigatória |
-| Requirements (@analyst) | pulada | obrigatória | obrigatória |
-| Design (@architect, @ux-ui) | pulada | seletiva | obrigatória |
-| Tasks/Plan | opcional | recomendada | obrigatória |
-| Execute (@dev) | direto | após gates | após gates |
+| Specify (PRD) | obrigatória | obrigatória | obrigatória |
+| Spec authority | — | `@sheldon` (solo) | `@orchestrator` (fan-out) |
+| Requirements | pulada | dentro do `@sheldon` | sub-agente `@analyst` via `@orchestrator` |
+| Design técnico | pulado | dentro do `@sheldon` | sub-agente `@architect` via `@orchestrator` |
+| UI/UX | pulada | detour opt-in | sub-agente `@ux-ui` via `@orchestrator` (UI-heavy) |
+| Plan/Tasks | opcional | dentro do `@sheldon` | sub-agente `@pm` via `@orchestrator` |
+| Execute (`@dev`) | direto | após Gates A/B/C | após Gates A/B/C |
+| Pentester | opt-in | opt-in | **inline** (entre `@dev` e `@qa`) |
 | QA/Validation | opcional | obrigatória | audit-blocking |
 
-Para MICRO: você vai de spec lite direto ao @dev. Nenhuma cerimônia.
-Para MEDIUM: cada fase tem gate de aprovação antes do próximo agente.
+Para MICRO: spec lite direto ao `@dev`. Nenhuma cerimônia.
+Para MEDIUM: cada dimensão de spec é coberta por um sub-agente especializado coordenado pelo `@orchestrator`.
 
 ## Gates de aprovação
 
-Em SMALL e MEDIUM, antes do handoff entre fases, um gate é verificado. Exemplo: antes do `@dev` começar, deve existir:
-- `spec-<slug>.md` com ACs verificáveis
-- `architecture.md` com decisões técnicas documentadas
-- (MEDIUM) `implementation-plan-<slug>.md` com fases de execução
+Em SMALL e MEDIUM, gates determinísticos controlam o avanço entre fases. Os 4 gates principais:
+
+| Gate | O que verifica | Quem produz / verifica |
+|---|---|---|
+| **Runtime smoke** | Build + migrations (em DB real) + boot + Core happy-path no stack real. Uma feature com backend/DB não fecha sem passar. `tsc` + testes unitários é o piso, não o "done". | `@qa` (Gate D) |
+| **Contract-integrity** | Bloqueia quando o harness-contract está ausente, sem critérios `RG-*`, ou com verificações duplicadas. Roda deterministicamente no gate de conclusão do `@dev`/`@qa`. | `aioson harness:check` |
+| **Scope-drift** | `spec:analyze` roda no gate done do `@dev`/`@qa`; bloqueia em drift real (readiness bloqueado, contrato inválido). `@scope-check` também disponível como detour explícito. | `aioson spec:analyze` / `@scope-check` |
+| **Single-spec-authority handoff** | Quando `@sheldon` (SMALL) ou `@orchestrator` (MEDIUM) passa para `@dev`, os Gates A/B/C + plano de implementação aprovado + integridade de contrato são verificados. | `@sheldon` / `@orchestrator` |
+
+Gates A/B/C = spec completa verificável (A: requisitos, B: decisões técnicas, C: plano faseado + harness-contract).
+Gate D = pré-ship: Runtime smoke + nenhum finding HIGH/CRITICAL de segurança.
 
-O gate não bloqueia automaticamente em projetos SMALL — é consultivo. Em MEDIUM, Gate D (pré-ship) bloqueia em findings High/Critical de segurança.
+## Sub-agentes de verificação (configuráveis, token-aware)
+
+`.aioson/config/verification.json` (auto-gerado, editável manualmente) declara quais verificadores (`qa` / `tester` / `pentester` / `validator`) rodam, **quando** (`per-phase` / `end-of-feature` / `sensitive-surface`), e em **qual modelo** — indexado por host harness.
+
+| Modo de dispatch | Descrição |
+|---|---|
+| **`native`** | Sub-agente in-harness num modelo do mesmo host (Claude Code → tier Claude como sonnet/opus; codex/opencode → seu modelo configurado). |
+| **`external`** | Dispara uma CLI de fornecedor diferente como auditor read-only (segunda opinião cross-vendor). Use para rodar GPT ou outro modelo como auditor externo — você não pode rodar um modelo GPT como sub-agente *nativo* do Claude Code. |
+
+Budget de tokens: verificações por fase são leves (um sub-agente barato), o smoke completo roda uma vez ao fim da feature, e verificação por fase é suprimida no MICRO.
+
+```bash
+# Resolver o plano de verificação para um slug/trigger/host
+aioson verification:plan . --slug=checkout-stripe --trigger=per-phase
+```
 
 ## The 80% Rule e SDD Automation Scripts
 

package/docs/pt/5-referencia/sdd-planos-e-estrutura.md

@@ -84,12 +84,14 @@ Veja [Plans externos para @product](../3-receitas/plans-externos-para-product.md
 |---|---|---|
 | `project.context.md` | `@setup` | todos os agentes (sempre) |
 | `project-pulse.md` | qualquer agente (ao fechar sessão) | todos os agentes (ao iniciar sessão) |
-| `prd.md` | `@product` (projeto novo) | `@sheldon`, `@analyst`, `@ux-ui`, `@pm`, `@dev` |
+| `prd.md` | `@product` (projeto novo) | `@sheldon`, `@orchestrator`, `@dev` |
 | `prd-{slug}.md` | `@product` (feature) | idem |
-| `sheldon-enrichment.md` | `@sheldon` | `@sheldon` (re-entrada), `@analyst` |
-| `architecture.md` | `@analyst` + `@architect` | `@ux-ui`, `@pm`, `@dev`, `@qa` |
-| `design-doc.md` | `@ux-ui` | `@pm`, `@dev` |
-| `tasks.md` | `@pm` | `@orchestrator`, `@dev` |
+| `sheldon-enrichment.md` | `@sheldon` | `@sheldon` (re-entrada) |
+| `requirements-{slug}.md` | `@sheldon` (SMALL) ou `@analyst` via `@orchestrator` (MEDIUM) | `@dev`, `@qa` |
+| `architecture.md` | `@sheldon` (SMALL) ou `@architect` via `@orchestrator` (MEDIUM) | `@dev`, `@qa` |
+| `implementation-plan-{slug}.md` | `@sheldon` (SMALL) ou `@pm` via `@orchestrator` (MEDIUM) | `@dev` |
+| `design-doc.md` | `@ux-ui` via `@orchestrator` (MEDIUM, UI-heavy) ou detour | `@dev` |
+| `tasks.md` | `@pm` via `@orchestrator` (MEDIUM) | `@orchestrator`, `@dev` |
 | `features.md` | qualquer agente | todos (status por slug) |
 
 ### Artefatos de execução
@@ -105,7 +107,7 @@ Veja [Plans externos para @product](../3-receitas/plans-externos-para-product.md
 
 ### `parallel/` — lanes do `@orchestrator`
 
-O `@orchestrator` cria esta subpasta quando detecta trabalho paralelizável:
+No MEDIUM, o `@orchestrator` atua como **maestro de spec**: produz o pacote de spec consolidado (via fan-out de sub-agentes) e pode criar esta subpasta quando a implementação tem frentes genuinamente paralelizáveis:
 
 ```
 .aioson/context/parallel/
@@ -292,21 +294,31 @@ O `aioson pulse:update` atualiza este arquivo via script (sem precisar de LLM).
 plans/ → prd.md → [dev implementa] → qa-report.md
 ```
 
-### SMALL
+### SMALL (lean lane — padrão v1.35.0)
 
 ```
-plans/ → prd.md → sheldon-enrichment.md → architecture.md
-       → dev-state.md → test-plan.md → qa-report.md
+plans/ → prd.md
+       → @sheldon: sheldon-enrichment.md + requirements-{slug}.md
+                   + architecture.md + implementation-plan-{slug}.md
+                   + harness-contract.json   ← pacote de spec (Gates A/B/C)
+       → @dev: dev-state.md (por fase, com verificação por fase)
+       → @qa: test-plan.md → qa-report.md
 ```
 
-### MEDIUM (completo)
+### MEDIUM (maestro lane — v1.35.0)
 
 ```
-plans/ → prd.md → sheldon-enrichment.md → .aioson/plans/{slug}/
-       → architecture.md → design-doc.md → tasks.md
-       → parallel/ → dev-state.md (por lane)
-       → test-plan.md → qa-report.md → test-inventory.md
-       → security-findings.json → last-handoff.json
+plans/ → prd.md
+       → @orchestrator fan-out:
+           @analyst  → requirements-{slug}.md
+           @architect → architecture.md
+           @pm        → implementation-plan-{slug}.md
+           @ux-ui     → design-doc-{slug}.md  (quando UI-heavy)
+         consolidação → parallel/harness-contract.json  ← Gates A/B/C
+       → @dev: dev-state.md (por fase) + parallel/lane-*.md
+       → @pentester: security-findings-{slug}.json
+       → @qa: test-plan.md → qa-report.md → test-inventory.md
+       → @validator: last-handoff.json
 ```
 
 ---

package/docs/pt/README.md

@@ -22,7 +22,7 @@ Esta é a porta de entrada da documentação em português. Não é um índice a
 ### Quero uma receita pronta para o meu caso
 
 **Trilhas canônicas — como features chegam ao dev:**
-1. **[Feature completa com @sheldon](./3-receitas/feature-completa-com-sheldon.md)** — a trilha principal: `@product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @scope-check → @dev → @qa` (com gates opcionais de `@tester` e `@pentester`)
+1. **[Feature completa com @sheldon](./3-receitas/feature-completa-com-sheldon.md)** — as duas trilhas: **SMALL lean** `@product → @sheldon → @dev → @qa` e **MEDIUM maestro** `@product → @orchestrator → @dev → @pentester → @qa` (com detours opt-in de `@tester`, `@validator`)
 2. [Da ideia ao PRD via @briefing](./3-receitas/da-ideia-ao-prd-via-briefing.md) — quando a ideia ainda é vaga
 3. [Plans externos para @product](./3-receitas/plans-externos-para-product.md) — quando você planejou em ChatGPT/Claude.io e quer trazer
 
@@ -37,7 +37,7 @@ Esta é a porta de entrada da documentação em português. Não é um índice a
 11. [Continuidade entre sessões](./3-receitas/continuidade-entre-sessoes.md) — feature dossier, dev-resume, drift detection
 
 ### Quero a referência técnica de um agente ou comando
-- **[Fichas dos 29 agentes (30 entradas com 1 alias)](./4-agentes/README.md)** — uma ficha por agente, com diálogo típico, saídas em disco e handoff
+- **[Fichas dos 29 agentes (30 entradas com 1 alias)](./4-agentes/README.md)** — uma ficha por agente, com diálogo típico, saídas em disco e handoff
 - **[Referência técnica completa](./5-referencia/README.md)** — 32 docs organizados em 5 categorias (novos 2026, artefatos, CLI/config, agentes/squads, skills/design)
 - [Guia de agentes (legado)](./agentes.md) — visão tabular alternativa
 
@@ -83,7 +83,7 @@ npx @jaimevalasek/aioson init meu-projeto
 cd meu-projeto
 
 # 3. Abra seu cliente AI (Claude Code, Codex e OpenCode) e digite:
-/aioson:agent:setup
+/aioson:agent:setup
 ```
 
 A partir daí, os agentes guiam você. Detalhes em [Primeiro projeto do zero](./2-comecar/primeiro-projeto.md).
@@ -99,7 +99,7 @@ Atualmente só PT está em reforma. EN/ES/FR continuam usando os arquivos legado
 ## Status desta documentação
 
 **Fase A (entender + começar)** — concluída · 8 docs em `1-entender/` e `2-comecar/`.
-**Fase B (receitas práticas + ficha por agente)** — concluída · 11 receitas em `3-receitas/` + 29 fichas em `4-agentes/`.
+**Fase B (receitas práticas + ficha por agente)** — concluída · 11 receitas em `3-receitas/` + 29 fichas em `4-agentes/`.
 **Fase C (referência técnica completa)** — concluída · 32 docs em `5-referencia/`, com 6 totalmente novos cobrindo features 2026 antes não documentadas em PT.
 **Fase D (trilhas de workflow)** — concluída · 3 trilhas canônicas de feature: briefing→PRD, plans externos, e trilha completa com @sheldon.