@jaimevalasek/aioson 1.21.7 → 1.22.0

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

@@ -1,44 +1,75 @@
-# @discovery-design-doc — Discovery e design doc em uma sessão combinada
-
-> **Para quem é:** quem tem uma ideia ou request e quer clareza completa — problema, ambiguidades, próximos passos — antes de qualquer implementação.
-> **Tempo de leitura:** 3 min.
-> **O que você vai sair sabendo:**
-> - Quando usar este agente vs usar `@analyst` e `@architect` separados
-> - O que o design doc entrega e como ele guia os próximos agentes
-
----
-
-## Para que serve
-
-Às vezes um request chega vago: um ticket, uma ideia de feature, uma anotação de reunião. Antes de abrir `@product` e percorrer o ciclo completo, você quer **normalizar o problema, identificar o que já está definido, e saber o que ainda está aberto** — tudo em uma sessão.
-
-O `@discovery-design-doc` faz exatamente isso: transforma um request bruto num design doc enxuto e num documento de readiness que diz ao próximo agente "aqui está o que você precisa, e aqui está o que ainda falta".
-
-É um atalho para quando o ciclo completo seria pesado demais — ou para quando você quer um checkpoint antes de decidir qual agente acionar.
-
----
-
-## Quando invocar
-
-- Você tem um ticket, briefing ou ideia e quer transformar em documento estruturado rapidamente
-- Você quer saber o que está bem definido vs o que ainda é ambíguo antes de acionar `@product` ou `@dev`
-- Você está em modo exploratório e quer um checkpoint de clareza sem comprometer o workflow completo
-
----
-
-## Quando NÃO invocar
-
-- A feature já tem spec e PRD definidos — acione diretamente `@dev` ou `@qa`
-- Você precisa de discovery profundo com mapeamento de domínio — use `@analyst` dentro do workflow SMALL/MEDIUM
-- Você quer um briefing pré-PRD com frameworks de framing — use `@briefing`
-
----
-
-## Diálogo típico
-
-```
-Você > @discovery-design-doc
-       Quero adicionar modo offline ao app mobile para que usuários possam
+# @discovery-design-doc — Discovery, readiness e design doc
+
+> **Para quem é:** quem precisa transformar uma ideia vaga em clareza inicial ou consolidar PRD, requisitos e arquitetura num contrato técnico antes do `@dev`.
+> **Tempo de leitura:** 3 min.
+> **O que você vai sair sabendo:**
+> - Os dois modos corretos de uso: exploratório e pré-dev
+> - Por que ele pode aparecer depois de `@analyst` e `@architect` no workflow
+> - O que o design doc e o readiness entregam para os próximos agentes
+
+---
+
+## Para que serve
+
+O `@discovery-design-doc` tem dois usos válidos:
+
+- **Modo exploratório:** quando um request chega vago, como ticket, ideia de feature ou anotação de reunião. Ele normaliza o problema, identifica ambiguidades e recomenda o próximo agente.
+- **Modo pré-dev no workflow:** quando o projeto SMALL/MEDIUM já passou por `@analyst` e `@architect`. Nesse caso, ele consolida PRD, requisitos, spec e arquitetura num `design-doc` vivo e num `readiness` com plano técnico concreto para o `@dev`.
+
+Ou seja: ele pode ser um atalho antes do ciclo completo **ou** uma etapa de segurança entre arquitetura e implementação. No workflow atual, esse segundo uso é esperado para SMALL/MEDIUM.
+
+---
+
+## Quando invocar
+
+- Você tem um ticket, briefing ou ideia e quer transformar em documento estruturado rapidamente
+- Você quer saber o que está bem definido vs o que ainda é ambíguo antes de acionar `@product` ou `@dev`
+- Você está em modo exploratório e quer um checkpoint de clareza sem comprometer o workflow completo
+- Você está no workflow SMALL/MEDIUM após `@architect` e precisa gerar o contrato técnico pré-dev
+- O `@dev` precisa de caminhos, módulos, decisões de reuso e riscos de tamanho de arquivo antes de editar código
+
+---
+
+## Quando NÃO invocar
+
+- Para refazer discovery amplo quando PRD, requirements, spec e architecture já estão claros
+- Você precisa de discovery profundo com mapeamento de domínio — use `@analyst` dentro do workflow SMALL/MEDIUM
+- Você quer um briefing pré-PRD com frameworks de framing — use `@briefing`
+- A tarefa é MICRO e já possui um plano simples suficiente para `@dev`
+
+> Ter PRD/spec definidos **não impede** o uso deste agente. No workflow SMALL/MEDIUM, eles são justamente entradas para o `design-doc` e o `readiness` pré-dev.
+
+---
+
+## Onde entra no workflow
+
+Fluxo exploratório manual:
+
+```
+@setup -> @discovery-design-doc -> próximo agente recomendado
+```
+
+Fluxo SMALL atual:
+
+```
+@product -> @analyst -> @scope-check(pre-dev) -> @architect -> @discovery-design-doc -> @dev -> @qa
+```
+
+Fluxo MEDIUM atual:
+
+```
+@product -> @analyst -> @architect -> @discovery-design-doc -> @ux-ui -> @pm -> @orchestrator -> @scope-check(pre-dev) -> @dev -> @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.
+
+---
+
+## Diálogo típico — modo exploratório
+
+```
+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...
@@ -56,36 +87,64 @@ Você > @discovery-design-doc
 
 @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.
-```
-
----
-
-## Saídas em disco
-
-```
-.aioson/context/design-doc.md      ← design doc enxuto (vivo, atualizado por agentes futuros)
-.aioson/context/readiness.md       ← status de clareza + ambiguidades abertas
-```
-
----
-
-## Como ele lê seu projeto
-
-- `.aioson/context/project.context.md`
-- Artefatos existentes: `discovery.md`, `architecture.md`, `prd.md`, `spec.md` (quando relevantes)
-- Input direto: briefing, ticket, screenshots, arquivos que você fornecer
-
----
-
-## Handoff típico
-
-- **Vem de:** pedido direto com um request vago ou ticket
-- **Vai para:** o agente recomendado no `readiness.md` — tipicamente `@product` (para fechar escopo) ou `@dev` (quando readiness é ALTO)
-
----
-
-## Próximo passo
-
-- Para framing pré-PRD com discovery frameworks: ficha `briefing.md` (em construção)
-- Para ciclo completo: [Primeiro projeto do zero](../2-comecar/primeiro-projeto.md)
+                        Recomendação: @product para fechar escopo antes de @dev.
+```
+
+---
+
+## Diálogo típico — modo pré-dev
+
+```
+Você > @discovery-design-doc
+       Consolidar a feature checkout depois da arquitetura.
+
+@discovery-design-doc > Lendo PRD, requirements, spec e architecture...
+                        Escopo: checkout com pagamento único
+                        Readiness: ready_with_warnings
+
+                        Plano técnico:
+                        - Reusar módulo de pedidos existente
+                        - Criar service de pagamento em src/lib/payments/
+                        - Evitar alterar fluxo de carrinho fora do checkout
+                        - Risco: controller pode passar de 500 linhas; dividir em service + validator
+
+@discovery-design-doc > Design doc criado em: .aioson/context/design-doc-checkout.md
+                        Readiness criado em: .aioson/context/readiness-checkout.md
+                        Recomendação: seguir para @dev quando Gate B estiver aprovado.
+```
+
+---
+
+## Saídas em disco
+
+```
+.aioson/context/design-doc.md              ← design doc do projeto
+.aioson/context/readiness.md               ← readiness do projeto
+.aioson/context/design-doc-{slug}.md       ← design doc da feature
+.aioson/context/readiness-{slug}.md        ← readiness da feature
+```
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/context/project.context.md`
+- Artefatos existentes: `prd.md`, `prd-{slug}.md`, `requirements-{slug}.md`, `spec.md`, `spec-{slug}.md`, `discovery.md`, `architecture.md` (quando relevantes)
+- Design docs existentes: `design-doc.md`, `design-doc-{slug}.md`, `readiness.md`, `readiness-{slug}.md`
+- `.aioson/context/project-map.md` quando existir, para resolver caminhos canônicos
+- Input direto: briefing, ticket, screenshots, arquivos que você fornecer
+
+---
+
+## Handoff típico
+
+- **Vem de:** pedido direto com um request vago ou ticket
+- **Também vem de:** `@architect` no workflow SMALL/MEDIUM, como consolidação pré-dev
+- **Vai para:** o agente recomendado no `readiness.md` — tipicamente `@product` quando o escopo ainda está aberto, ou `@dev` quando o readiness está pronto
+
+---
+
+## Próximo passo
+
+- Para framing pré-PRD com discovery frameworks: ficha `briefing.md` (em construção)
+- Para ciclo completo: [Primeiro projeto do zero](../2-comecar/primeiro-projeto.md)

package/docs/pt/4-agentes/scope-check.md

@@ -0,0 +1,65 @@
+# @scope-check
+
+## Para que serve
+
+O `@scope-check` valida se intenção, plano e artefatos estão alinhados antes de continuar para a implementação.  
+Ele evita drift de escopo: antes de codar, confere se tudo que foi decidido está presente no PRD/especificações e no plano aprovado; após mudanças relevantes, confirma se as correções alteraram contrato, comportamento ou escopo.
+
+## Quando usar
+
+- Antes de `@dev` em fluxos **SMALL** e **MEDIUM** (pré-dev).  
+- Após `@dev` e/ou correções de `@qa`/`@tester`/`@pentester`, quando houve mudança material de código ou comportamento.
+- Em reaberturas de feature com risco de quebra de contrato entre o que foi planejado e o que está sendo entregue.
+
+## Modos
+
+- `pre-dev` (padrão): valida intenção e plano antes da primeira implementação.
+- `post-dev` (opcional): valida se o diff entregue bate com o plano aprovado.
+- `post-fix` (opcional): valida se correções mantiveram o escopo e contrato.
+- `final` (opcional): reconcilia intenção, plano e resultado de fechamento.
+
+## Arquivos de entrada
+
+- `project.context.md`
+- `prd.md` ou `prd-{slug}.md`
+- `requirements-{slug}.md`
+- `spec-{slug}.md`
+- `architecture.md`
+- `design-doc.md`, `implementation-plan-{slug}.md`, `dev-state.md` (quando existirem)
+- `security-findings-{slug}.json` e outros artefatos de revisão (quando aplicável)
+
+## Saída esperada
+
+Cria/atualiza:
+
+- `.aioson/context/scope-check.md` (modo projeto)
+- `.aioson/context/scope-check-{slug}.md` (modo feature)
+
+O relatório deve indicar:
+
+- `status`: `approved | patched | needs-product | needs-analyst-redo | needs-architecture | needs-dev-fix | needs-qa-recheck | blocked`
+- `next_agent`
+- principais divergências encontradas e impacto
+- decisão objetiva de continuação ou bloqueio
+
+## Regras duras
+
+- Não aprova entrega quando o que foi implementado diverge de requisito, AC ou decisão já aprovada.
+- Não inventa arquivos ou comportamentos não rastreados por artefatos.
+- Não aprova por “o código funciona” se houver divergência funcional relevante.
+- Em MICRO, mantém o relatório mais leve; em SMALL/MEDIUM pode ser mais detalhado.
+
+## Handoff padrão
+
+- `approved` ou `patched`: segue para o próximo agente do fluxo.
+- `needs-*`: interrompe o fluxo e encaminha com pedido explícito de correção no dono do estágio anterior.
+- `blocked`: pede uma pergunta objetiva de decisão ao usuário/owner.
+
+## Comando de ativação
+
+```
+/aioson:agent:scope-check
+```
+
+No modo CLI, use também o contexto/artefatos corretos para fechar o contrato antes de avançar para `@dev`/`@qa`.
+

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

@@ -28,6 +28,7 @@
 |---|---|
 | [fluxo-artefatos.md](./fluxo-artefatos.md) | Mapa de quem cria o quê: @product → @sheldon → @analyst → @dev → @qa |
 | [feature-archive.md](./feature-archive.md) | Arquivamento automático de features concluídas via feature:close |
+| [feature-export.md](./feature-export.md) | Exportar (copiar) todos os artefatos de uma feature para um local limpo — entregável portátil |
 | [memoria-e-contexto.md](./memoria-e-contexto.md) | Memória persistente, context cache, context search, context monitor — guia consolidado |
 | [runtime-observability.md](./runtime-observability.md) | Telemetria SQLite, dashboard, runtime:emit, agent:done |
 | [hooks-session-guard.md](./hooks-session-guard.md) | Hooks automáticos de visibilidade no dashboard para Claude Code, Antigravity e Codex |

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

@@ -222,6 +222,7 @@ Scripts determinísticos que movem verificações de estado, validação de arte
 | `state:save` | Salva ponto de continuação em `dev-state.md` (fase, status, spec-version, histórico) | Durante `@dev` ao fim de cada fase ou antes de encerrar |
 | `feature:close` | Fecha feature com verdict PASS/FAIL: atualiza spec, features.md, project-pulse.md e dispara archivamento automático | Após QA sign-off — chamado pelo `@qa` automaticamente |
 | `feature:archive` | Move artefatos de uma feature `done` para `.aioson/context/done/{slug}/` e atualiza o manifest | Chamado pelo `feature:close` automaticamente; também disponível para retroativo com `--dry-run` e `--restore` |
+| `feature:export` | **Copia** todos os artefatos de uma feature para um `--out` limpo, sem mexer na origem; gera `INDEX.md` | Exportar specs para analisar fora, entregar a cliente, ou usar o AIOSON só como gerador de specs. Veja [feature-export.md](./feature-export.md) |
 | `gate:check` | Valida pré-requisitos e artefatos de um phase gate (A/B/C/D); retorna PASS ou BLOCKED | Antes de avançar para o próximo agente |
 | `artifact:validate` | Verifica a cadeia completa de artefatos de uma feature (PRD → spec → plano → conformance) | A qualquer momento para checar completude |
 | `workflow:execute` | Monta e executa o plano de agentes baseado na classificação; aceita `--dry-run` e `--start-from` | Para orquestrar features sem o dashboard |
@@ -521,8 +522,8 @@ Importante:
 - `scan:project` sozinho nao gera `discovery.md`
 - `scan:project` nunca gera `architecture.md`
 - se `discovery.md` e `skeleton-system.md` ja existirem e voce rodar com `--with-llm`, o scanner agora entra em modo de atualizacao por padrao: usa os arquivos atuais como memoria base, gera a nova versao consolidada e cria backup automatico em `.aioson/backups/` antes de sobrescrever
-- em projetos SMALL brownfield, o fluxo tipico depois do scan completo e `@analyst` -> `@scope-check` -> `@architect` -> `@dev`
-- sem API LLM configurada, o fluxo local tambem e valido: `scan:project --folder=...` -> `@analyst` no seu Codex/Claude -> `@scope-check` -> `@architect` -> `@dev`
+- em projetos SMALL brownfield, o fluxo tipico depois do scan completo e `@analyst` -> `@scope-check` -> `@architect` -> `@dev`
+- sem API LLM configurada, o fluxo local tambem e valido: `scan:project --folder=...` -> `@analyst` no seu Codex/Claude -> `@scope-check` -> `@architect` -> `@dev`
 
 O parâmetro `--folder` agora é obrigatório. Ele define quais pastas do projeto devem ganhar um mapa completo com pastas e arquivos. Você pode informar uma pasta ou várias separadas por vírgula.
 
@@ -574,8 +575,8 @@ Quando usar cada modo:
 
 Fluxos recomendados:
 
-- **Com API no aioson:** `scan:project --folder=src --with-llm --provider=...` -> `@analyst` -> `@scope-check` -> `@architect` -> `@dev`
-- **Sem API no aioson:** `scan:project --folder=src` -> abrir seu AI CLI -> `@analyst` -> `@scope-check` -> `@architect` -> `@dev`
+- **Com API no aioson:** `scan:project --folder=src --with-llm --provider=...` -> `@analyst` -> `@scope-check` -> `@architect` -> `@dev`
+- **Sem API no aioson:** `scan:project --folder=src` -> abrir seu AI CLI -> `@analyst` -> `@scope-check` -> `@architect` -> `@dev`
 - **Com contexto mínimo para tarefa específica:** `scan:project --folder=src` -> `context:pack --agent=dev --goal="..." --module=src`
 - Se o seu cliente nao entender `@analyst`, gere um prompt pronto com `aioson agent:prompt analyst --tool=codex` ou troque `--tool` para o cliente correto
 

package/docs/pt/5-referencia/feature-archive.md

@@ -194,6 +194,7 @@ aioson feature:archive . --feature=checkout --json
 
 ## Veja também
 
+- [Feature Export](./feature-export.md) — **copiar** (não mover) os artefatos para um local limpo, sem mexer na origem
 - [Feature Dossier](./feature-dossier.md) — o que o dossier carrega *antes* de arquivar a feature
 - [Continuidade entre sessões](../3-receitas/continuidade-entre-sessoes.md) — retomar feature interrompida com dossier + dev-resume
 - [Fluxo de artefatos](./fluxo-artefatos.md) — mapa de quem cria o quê e quem consome

package/docs/pt/5-referencia/feature-export.md

@@ -0,0 +1,155 @@
+# Feature Export — Exportar artefatos para um local limpo
+
+O `feature:export` **copia** todos os artefatos de uma feature para um diretório de saída que você escolhe, deixando a árvore original intacta.
+
+É o irmão não-destrutivo do [`feature:archive`](./feature-archive.md): em vez de **mover** os arquivos para `.aioson/context/done/{slug}/`, ele **copia** para um `--out` arbitrário. O objetivo é transformar a saída em markdown do AIOSON num entregável portátil — para analisar as specs fora do projeto, entregar a um cliente, ou usar o AIOSON apenas como gerador de specs.
+
+---
+
+## Como funciona
+
+O comando reutiliza exatamente a mesma enumeração de artefatos do `feature:archive` (incluindo o guard contra colisão de slugs parecidos), mas:
+
+- **Copia** em vez de mover — a árvore de origem nunca é alterada.
+- Escreve no `--out` que você indicar (ou em `<projeto>/{slug}-export` por padrão).
+- Funciona tanto para features **ativas** (artefatos no root + diretórios por slug) quanto para features **já arquivadas** (`context/done/{slug}/`).
+- Gera um `INDEX.md` listando tudo que foi exportado e a origem de cada arquivo.
+
+```bash
+# Exporta a feature checkout para ./checkout-export/ (mirrored + INDEX.md)
+aioson feature:export . --feature=checkout
+
+# Destino customizado
+aioson feature:export . --feature=checkout --out=../checkout-specs
+
+# Tudo num diretório só (sem subpastas), nomes prefixados por label
+aioson feature:export . --feature=checkout --flatten
+
+# Sem o INDEX.md
+aioson feature:export . --feature=checkout --no-index
+
+# Ver o que seria copiado sem escrever nada
+aioson feature:export . --feature=checkout --dry-run
+```
+
+---
+
+## O que é copiado
+
+A mesma superfície que o `feature:archive` identifica:
+
+- Arquivos no **root** de `.aioson/context/` no padrão `*-{slug}.{md,yaml,yml,json}` (ex.: `prd-checkout.md`, `spec-checkout.md`, `requirements-checkout.md`, `conformance-checkout.yaml`, `security-findings-checkout.json`).
+- Diretórios por slug: `context/features/{slug}/` (dossier), `.aioson/plans/{slug}/`, `.aioson/briefings/{slug}/`.
+- `context/done/{slug}/` quando a feature já foi arquivada (sempre incluído).
+
+**O que nunca é copiado:** arquivos globais (`project.context.md`, `project-pulse.md`, `features.md`, etc.) e arquivos de outra feature — o guard contra colisão garante que `checkout-v2` nunca vaze numa exportação de `checkout`.
+
+---
+
+## Estrutura de saída
+
+### Mirrored (padrão)
+
+```
+checkout-export/
+├── INDEX.md                    ← manifesto gerado
+├── prd-checkout.md             ← arquivos do root
+├── spec-checkout.md
+├── requirements-checkout.md
+├── dossier/
+│   └── dossier.md
+├── plans/
+│   ├── manifest.md
+│   └── plan-phase-1.md
+├── briefings/
+│   └── briefing.md
+└── done/                       ← presente se a feature já foi arquivada
+    └── ...
+```
+
+### Flatten (`--flatten`)
+
+Tudo num nível só. Arquivos do root mantêm o nome; arquivos aninhados viram `label-...-arquivo.ext` (livre de colisão por construção):
+
+```
+checkout-export/
+├── INDEX.md
+├── prd-checkout.md
+├── spec-checkout.md
+├── dossier-dossier.md
+├── plans-manifest.md
+├── plans-plan-phase-1.md
+└── briefings-briefing.md
+```
+
+---
+
+## O INDEX.md
+
+Gerado por padrão (desabilite com `--no-index`). Lista cada arquivo exportado, o grupo de origem e o caminho fonte:
+
+```markdown
+# Feature Export — checkout
+
+> 7 file(s) copied from AIOSON on 2026-06-08.
+> Non-destructive snapshot — the original artefacts were left untouched.
+
+| group | file | source |
+|-------|------|--------|
+| context | prd-checkout.md | .aioson/context/prd-checkout.md |
+| dossier | dossier/dossier.md | .aioson/context/features/checkout/dossier.md |
+| plans | plans/manifest.md | .aioson/plans/checkout/manifest.md |
+```
+
+---
+
+## Opções
+
+| Opção | Padrão | Descrição |
+|-------|--------|-----------|
+| `--feature=<slug>` | — | Identificador da feature (obrigatório). |
+| `--out=<dir>` | `<projeto>/{slug}-export` | Diretório de destino. |
+| `--flatten` | mirrored | Achata a estrutura num nível só. |
+| `--no-index` | gera INDEX | Não escreve o `INDEX.md`. |
+| `--dry-run` | — | Mostra o que seria copiado sem escrever nada. |
+| `--json` | — | Saída JSON estruturada (`outDir`, `count`, `copied`, `index`). |
+
+---
+
+## Saída JSON
+
+```bash
+aioson feature:export . --feature=checkout --json
+```
+
+```json
+{
+  "ok": true,
+  "slug": "checkout",
+  "outDir": "checkout-export",
+  "flatten": false,
+  "count": 7,
+  "copied": ["prd-checkout.md", "spec-checkout.md", "dossier/dossier.md"],
+  "index": true
+}
+```
+
+---
+
+## Diferenças em relação ao feature:archive
+
+| | `feature:archive` | `feature:export` |
+|---|---|---|
+| Operação | **move** (`fs.rename`) | **copia** (não-destrutivo) |
+| Destino | `.aioson/context/done/{slug}/` (dentro do projeto) | `--out` arbitrário |
+| Quem aciona | agentes (via `feature:close`) | o usuário |
+| Guard de status | exige `done` (ou `--force`) | nenhum — exporta feature em progresso também |
+| Efeito na origem | remove do root | intacta |
+
+---
+
+## Veja também
+
+- [Feature Archive](./feature-archive.md) — limpeza automática do contexto (move, não copia)
+- [Feature Dossier](./feature-dossier.md) — o que o dossier consolida antes de exportar/arquivar
+- [Fluxo de artefatos](./fluxo-artefatos.md) — mapa de quem cria o quê

package/docs/pt/README.md

@@ -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](./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
 
@@ -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/` + 28 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.
 

package/docs/pt/agentes.md

@@ -1,6 +1,8 @@
 # Guia de Agentes
 
-> **Versão tabular alternativa (legado).** Para fichas individuais detalhadas com diálogos, saídas em disco e handoff, veja [`4-agentes/README.md`](./4-agentes/README.md).
+> **Versão tabular alternativa (legado).** Para fichas individuais detalhadas com diálogos, saídas em disco e handoff, veja [`4-agentes/README.md`](./4-agentes/README.md).
+
+> `@pair` é alias de `@deyvin` e não possui ficha separada.
 
 > Quando usar cada agente, o que ele entrega e como ativá-lo.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.21.7",
+  "version": "1.22.0",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",

package/src/agent-manifests.js

@@ -7,11 +7,16 @@ const { isCanonicalAgent } = require('./dossier/schema');
 
 const MANIFESTS_RELATIVE_DIR = '.aioson/agents/manifests';
 const ALLOWED_AUTONOMY_MODES = new Set(['guarded', 'trusted', 'headless']);
+// Canonical scope-check modes. Kept in sync with SCOPE_CHECK_MODES in
+// src/commands/workflow-next.js and src/commands/agents.js — this is the read
+// path that validates the manifest's declared check_modes so the field cannot
+// silently drift to a mode the router does not understand.
+const ALLOWED_CHECK_MODES = new Set(['pre-dev', 'post-dev', 'post-fix', 'final']);
 
 // SF-project-16: every field that influences autonomy is validated on read.
-// Unknown fields are passed through (forward-compat), but autonomy_modes is
-// filtered to ALLOWED_AUTONOMY_MODES. Non-canonical agent ids are refused
-// before the file is even opened.
+// Unknown fields are passed through (forward-compat), but autonomy_modes and
+// check_modes are filtered to their allowed sets. Non-canonical agent ids are
+// refused before the file is even opened.
 function sanitizeManifest(raw) {
   if (!raw || typeof raw !== 'object') return null;
   const out = { ...raw };
@@ -20,6 +25,10 @@ function sanitizeManifest(raw) {
       .filter((mode) => typeof mode === 'string' && ALLOWED_AUTONOMY_MODES.has(mode));
     out.autonomy_modes = filtered;
   }
+  if (Array.isArray(raw.check_modes)) {
+    out.check_modes = raw.check_modes
+      .filter((mode) => typeof mode === 'string' && ALLOWED_CHECK_MODES.has(mode));
+  }
   return out;
 }
 
@@ -78,6 +87,8 @@ function buildAgentCapabilitySummary(manifest, tool) {
 
 module.exports = {
   MANIFESTS_RELATIVE_DIR,
+  ALLOWED_AUTONOMY_MODES,
+  ALLOWED_CHECK_MODES,
   readAgentManifest,
   resolveAgentCapabilities,
   supportsTool,

package/src/agents.js

@@ -29,15 +29,16 @@ function buildAgentPrompt(agent, tool, options = {}) {
   const safeTool = String(tool || 'codex').toLowerCase();
   const instructionPath = options.instructionPath || agent.path;
   const targetDir = options.targetDir ? String(options.targetDir) : '.';
-  const interactionLanguage = String(options.interactionLanguage || 'en');
-  const autonomyMode = String(options.autonomyMode || '').trim();
-  const capabilitySummary = String(options.capabilitySummary || '').trim();
-  const activationContext = String(options.activationContext || '').trim();
-  const dependsOn = Array.isArray(options.dependsOn) ? options.dependsOn : agent.dependsOn;
-  const dependencyText =
-    dependsOn.length > 0
-      ? `Check required context files first: ${dependsOn.join(', ')}.`
-      : 'No prerequisite context files are required.';
+  const interactionLanguage = String(options.interactionLanguage || 'en');
+  const autonomyMode = String(options.autonomyMode || '').trim();
+  const autoHandoff = options.autoHandoff === true;
+  const capabilitySummary = String(options.capabilitySummary || '').trim();
+  const activationContext = String(options.activationContext || '').trim();
+  const dependsOn = Array.isArray(options.dependsOn) ? options.dependsOn : agent.dependsOn;
+  const dependencyText =
+    dependsOn.length > 0
+      ? `Check required context files first: ${dependsOn.join(', ')}.`
+      : 'No prerequisite context files are required.';
   const activationBlock = activationContext
     ? [
       '',
@@ -66,19 +67,19 @@ function buildAgentPrompt(agent, tool, options = {}) {
     '',
     `**Language boundary:** Agent instructions are canonical in English. All user-facing communication must be in ${interactionLanguage}.`,
     '',
-    `**Scope boundary:** You operate exclusively as ${agent.command}. Do not perform work that belongs to another agent. When your work is complete, output only the handoff — which agent is next and why. Do not continue into that agent\'s territory.`,
+    `**Scope boundary:** You operate exclusively as ${agent.command}. Do not perform work that belongs to another agent. When your work is complete, output only the handoff — which agent is next and why. Do not continue into that agent\'s territory.${autoHandoff ? ' Exception: autopilot handoff is active for this stage — follow `.aioson/docs/autopilot-handoff.md` and auto-invoke the next agent\'s skill when no stop condition applies, never past the `@dev` handoff.' : ''}`,
   ].join('\n');
 
-  if (safeTool === 'claude') {
-    return `Read ${instructionPath} and execute ${agent.command}. ${dependencyText}${activationBlock}\n\nWrite output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
-  }
-
-  if (safeTool === 'opencode') {
-    return `Use agent "${agent.id}" from ${instructionPath}. ${dependencyText}${activationBlock}\n\nSave output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
-  }
-
-  return `Read AGENTS.md and execute ${agent.command} using ${instructionPath}. ${dependencyText}${activationBlock}\n\nSave output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
-}
+  if (safeTool === 'claude') {
+    return `Read ${instructionPath} and execute ${agent.command}. ${dependencyText}${activationBlock}\n\nWrite output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
+  }
+
+  if (safeTool === 'opencode') {
+    return `Use agent "${agent.id}" from ${instructionPath}. ${dependencyText}${activationBlock}\n\nSave output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
+  }
+
+  return `Read AGENTS.md and execute ${agent.command} using ${instructionPath}. ${dependencyText}${activationBlock}\n\nSave output to ${agent.output}.${autonomyBlock}${lifecycleBlock}`;
+}
 
 module.exports = {
   normalizeAgentName,