@jaimevalasek/aioson 1.33.1 → 1.37.0

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

@@ -1,99 +1,178 @@
-# @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.
+
+---
+
+## Autopilot: travessia automática para `@dev`
+
+Sob autopilot (`auto_handoff: true`, esquema já semeado para a feature, ou token `--auto` recebido do `@product`), `@sheldon` não para no handoff manual: uma vez com sizing/enriquecimento confirmados e o pacote lean + `dev-state.md` gravados, ele semeia o esquema agêntico (`aioson workflow:execute . --feature={slug} --seed`), completa o próprio estágio (`aioson workflow:next . --complete=sheldon`) e invoca `@dev` diretamente. Um Gate A/B/C bloqueado, ou uma decisão de sizing/escopo ainda em aberto, continua sendo parada manual normal. Veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md).
+
+---
+
+## Opção `--help`
+
+Uma ativação com `--help` (`/sheldon --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`.
+
+---
+
+## 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/tester.md

@@ -92,6 +92,12 @@ Você > Sim
 
 ---
 
+## Opção `--help`
+
+Uma ativação com `--help` (`/tester --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`.
+
+---
+
 ## Handoff típico
 
 - **Vem de:** `@qa` (que identificou gaps) ou você diretamente

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

@@ -14,13 +14,16 @@ Quando o dev implementa a UI sem especificação, ele toma decisões de design n
 
 `@ux-ui` existe para separar "o que a interface faz" (responsabilidade dele) de "como o código implementa" (responsabilidade do `@dev`). Ele produz uma especificação de componentes, tokens e fluxos que o `@dev` segue como contrato.
 
-Ele é guiado pelo design skill do projeto — se `clean-saas-ui` estiver configurado, ele usa apenas esse sistema. Se nenhum skill estiver definido, ele para e pergunta antes de avançar.
+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 oferece as **duas rotas** (espelhando o `@setup`): `interface-design` guiado pelas **suas imagens de referência** — extraídas uma única vez em `identity.md` pela skill `reference-identity-extract` — ou um **preset instalado** da lista. Nunca escolhe sozinho.
+
+> **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`.
 
@@ -78,6 +81,7 @@ Você > @ux-ui
 
 - `.aioson/context/project.context.md` — detecta `design_skill`
 - `.aioson/skills/design/{design_skill}/SKILL.md` — **único** sistema visual carregado
+- `.aioson/briefings/{slug}/identity.md` (senão `.aioson/context/identity.md`) — quando `design_skill: interface-design`: identidade visual extraída das suas imagens de referência, **input** que o motor aplica (não é um segundo skill)
 - `.aioson/context/prd-{slug}.md`, `discovery.md`, `architecture.md`
 - `.aioson/context/spec-{slug}.md` (feature mode)
 - `.aioson/rules/` — regras com `agents: ux-ui`
@@ -98,8 +102,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/README.md

@@ -12,7 +12,7 @@
 |---|---|
 | [loop-guardrails.md](./loop-guardrails.md) | Contrato verificável para o self:loop: scope guard, budget, human gates, criteria evaluation (v1.22.0) |
 | [harness-retro.md](./harness-retro.md) | Minerar o histórico de falhas de uma feature sem LLM — dossiê retrospectivo + harness:preview (v1.23.0) |
-| [autopilot-handoff.md](./autopilot-handoff.md) | Encadeamento automático de agentes pré-dev e pós-dev — opt-in via auto_handoff: true (v1.21.x–v1.22.0) |
+| [autopilot-handoff.md](./autopilot-handoff.md) | Full-feature autopilot: cadeia @product → @sheldon/@orchestrator → @dev → @qa (hub) → @tester/@pentester/@validator até `feature:close`; tokens inline `--auto`/`--step`, opção `--help` nos 13 agentes mais usados |
 | [feature-dossier.md](./feature-dossier.md) | Dossier de feature: ponto único de verdade (spec, plano, histórico, status) |
 | [agent-chain-continuity.md](./agent-chain-continuity.md) | Sistema de continuidade entre sessões — Fases 1–8 (dev-resume, drift detection, handoff v2) |
 | [sdd-framework.md](./sdd-framework.md) | Spec-Driven Development: Constitution, project-pulse, skill aioson-spec-driven, MICRO/SMALL/MEDIUM |

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 3)
         │
         ▼
-@validator → gate final → feature:close
+@validator → verifica contra harness-contract em contexto isolado → gate final → feature:close
         │
         ▼
 dossier arquivado em .aioson/context/done/