@jaimevalasek/aioson 1.36.0 → 1.37.0

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

@@ -14,7 +14,7 @@ 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.
 
@@ -81,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`

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

@@ -93,7 +93,7 @@ autoridade de spec:
 @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)
+@qa → runtime smoke gate + ACs → devolve para @dev se houver falhas (ciclo autônomo, cap 3)
         │
         ▼
 @validator → verifica contra harness-contract em contexto isolado → gate final → feature:close

package/docs/pt/5-referencia/autopilot-handoff.md

@@ -1,96 +1,172 @@
-# Autopilot Handoff — Encadeamento automático de agentes
+# Autopilot Handoff — o full-feature autopilot
 
-> Protocolo opt-in que elimina confirmações manuais de handoff nos segmentos determinísticos do workflow de feature.
+> Protocolo opt-in que remove as confirmações **mecânicas** de handoff em toda a cadeia de uma feature — do `@product` até a recomendação de `aioson feature:close`. Decisões humanas genuínas (escopo, sizing) continuam acontecendo dentro dos próprios agentes; o autopilot só remove o "roda o próximo passo" depois que o trabalho do agente atual já está resolvido. `feature:close`/publish **nunca** roda sozinho — é sempre gate humano.
 
-Introduzido na v1.21.x, completado na v1.22.0 (com @pm no MEDIUM). Quando ativado, os agentes do pré-dev e do ciclo pós-dev se encadeiam automaticamente — cada um termina, emite um aviso de transição e invoca o próximo. As decisões genuinamente humanas (entrada no `@dev` e `feature:close`) permanecem manuais.
+---
+
+## Dois segmentos
+
+```
+Segmento 1: @product → @sheldon (SMALL) / @orchestrator (MEDIUM) → @dev
+Segmento 2: @dev → @qa (hub) → @tester / @pentester (quando o trigger dispara) → @validator → STOP
+```
+
+1. **Cadeia spec → dev** — cada agente de spec, uma vez resolvidas as próprias decisões (sem `AskUserQuestion` aberta, gates que ele possui aprovados), semeia o esquema agêntico e invoca o próximo estágio em vez de parar. A travessia pré-dev acontece pelo pacote `dev-state.md`, não carregando o chat bruto adiante.
+2. **Ciclo de revisão pós-dev** — `@dev` e os agentes de revisão se encadeiam automaticamente até a feature estar pronta para fechar. `@qa` é o hub: possui o roteamento para os agentes especializados e o ciclo de correções.
+
+Historicamente o Segmento 1 sempre parava no humano (os agentes de spec terminavam em decisões humanas); hoje o autopilot atravessa esse segmento também — mas só mecanicamente. Uma decisão real de produto/escopo/sizing sempre pausa antes de qualquer auto-invocação.
 
 ---
 
 ## Ativação
 
-O autopilot é opt-in. Para ativar, adicione ao `project.context.md`:
+Autopilot está ativo quando as duas primeiras condições valem, com a terceira como gate:
 
-```yaml
-auto_handoff: true
-```
+1. **Sinal de autopilot armado** — `auto_handoff: true` no `project.context.md` (flag do projeto), **ou** `.aioson/context/workflow-execute.json` existe com `agentic_policy.enabled: true` **e `feature` igual ao slug atual** (esquema semeado — um esquema deixado por outra feature/já fechada **não conta**, para nenhum agente da cadeia). **O desarme por feature vence a flag:** um esquema para o slug atual com `agentic_policy.enabled: false` (escrito por `aioson workflow:execute . --feature={slug} --seed --step`) desliga o autopilot **só para essa feature**, mesmo com `auto_handoff: true` no projeto.
+2. Um workflow de feature está ativo (slug conhecido).
+3. O gate/veredito do agente atual passou **e** não há decisão humana genuína em aberto (ver condições de parada).
 
-Sem essa flag (ou com `false`), o comportamento padrão é handoff manual — cada agente para e espera você invocar o próximo. O `aioson doctor` emite um aviso `context:auto_handoff_declared` se o protocolo estiver instalado mas a flag não for declarada.
+### Token inline de modo de execução (maior precedência)
 
-**Pré-requisitos adicionais para ativação de cada handoff:**
-1. O workflow de feature deve estar ativo (slug conhecido, classificação SMALL ou MEDIUM).
-2. O gate/verdict do agente atual deve ter passado.
+Um `--auto` ou `--step` isolado nos argumentos de ativação do `@product` (kickoff) ou do `@dev` (entrada tardia/override) **é** a decisão de modo de execução — o agente remove o token do texto da tarefa e nunca pergunta:
 
----
+| Token | Onde | Efeito |
+|---|---|---|
+| `/product --auto <tarefa>` | Kickoff da feature | Pula a pergunta na tela; semeia o esquema e arma toda a cadeia a partir dali |
+| `/product --step <tarefa>` | Kickoff da feature | Pula a pergunta; grava o esquema desarmado (`agentic_policy.enabled: false`) — handoff manual |
+| `/dev --auto` | Entrada em `@dev` | Arma o autopilot a partir daqui mesmo sem flag/esquema prévio — implementação + ciclo de revisão pós-dev rodam sozinhos |
+| `/dev --step` | Entrada em `@dev` | Desarma o autopilot **só para esta feature** — para no handoff `@dev → @qa` mesmo em projeto com `auto_handoff: true` (o desarme por feature sempre vence a flag do projeto) |
 
-## Dois segmentos
+Agentes downstream (`@qa`/`@tester`/`@pentester`/`@validator`) não parseiam tokens — eles só leem a flag/esquema já decidido. Só `@product` pergunta; os demais nunca re-perguntam.
+
+### Sem token: a pergunta acontece uma única vez, no handoff do `@product`
+
+Quando não há token inline nem escolha padrão registrada, `@product` pergunta on-screen ao fechar o PRD (`AskUserQuestion`, localizado, com marcador de recomendação):
 
-### Segmento 1 — Cadeia pré-dev
+- **Autopilot — roda tudo até `feature:close`** → roda as ações de autopilot só para esta feature (não persiste default).
+- **Passo a passo — eu conduzo cada etapa** → apresenta o handoff manual e para.
+- **Sempre autopilot neste projeto** → grava `auto_handoff: true` no `project.context.md` (cria a linha se ausente) e roda as ações de autopilot.
+
+Precedência completa, da mais forte para a mais fraca:
 
 ```
-@analyst → @scope-check → @architect → @discovery-design-doc
-        [→ @pm  (apenas MEDIUM)]
-              ↓
-        STOP — human entra com /dev
+1. Token inline (--auto / --step)
+2. Esquema por feature (.aioson/context/workflow-execute.json com feature={slug}) — armado ou desarmado
+3. Flag do projeto (auto_handoff: true/false em project.context.md)
+4. Pergunta on-screen do @product (quando nada dos 3 acima está definido)
 ```
 
-A cadeia pré-dev **sempre para antes do primeiro `@dev`**. O desenvolvedor faz `/compact` quando continua a mesma feature e inicia a implementação a partir do pacote/checkpoint de contexto — `@dev` é pesado e se beneficia de um handoff operacional compacto. Use `/clear` apenas para reset forte, troca de feature, contexto poluído ou reset sensível a segurança.
+---
+
+## Semeando o esquema agêntico
 
-### Segmento 2 — Ciclo de revisão pós-dev (hub = @qa)
+O primeiro agente de spec a terminar sob autopilot semeia o contrato do run — o "esquema" que toda a cadeia segue, e o que torna uma feature construída do jeito normal (`@product → @sheldon`/`@orchestrator` → …) rodar até `feature:close` sem você precisar invocar nada:
 
-Uma vez que o `@dev` inicial termina, o autopilot retoma automaticamente:
+```bash
+aioson workflow:execute . --feature={slug} --seed --tool=<tool>
+```
+
+`--seed` grava `.aioson/context/workflow-execute.json` (com `agentic_policy.enabled: true` — caps do ciclo de revisão, `feature_close: human_gate`, condições de parada) mais `.aioson/context/workflow.state.json`. É **seed-only**: registra a política que os agentes interativos seguem, mas **não** dirige as transições de estágio sozinho (quem faz isso são os próprios agentes, via `Skill(aioson:agent:<próximo>)` + `aioson workflow:next . --complete=<agente>`). Re-semear o mesmo slug é idempotente.
+
+**Falha ao semear é condição de parada.** O agente que semeia checa o resultado do comando: uma falha `different_active_feature` significa que outra feature genuinamente ativa segura o `workflow.state.json` — expõe isso ao usuário (fechar/pausar essa feature, ou `aioson feature:sweep .`) e para com o handoff manual. Nunca continue a cadeia como se o autopilot estivesse armado quando o seed falhou.
+
+---
+
+## Roteamento — determinístico, nunca escolhido pelo modelo
+
+O próximo agente vem da máquina de estados do workflow e da evidência em disco, nunca de julgamento do LLM:
+
+- CLI disponível: rode `aioson workflow:next .` (modo inspeção) e use o estágio reportado, ou o campo `next` de `.aioson/context/workflow.state.json`.
+- CLI ausente: siga a sequência de classificação em `.aioson/config.md` e as tabelas de roteamento abaixo, exatamente.
+
+Nunca pule um estágio, reordene, ou escolha um agente que a máquina de estados/tabela não nomeou.
+
+---
+
+## Segmento 1 — cadeia spec → dev
+
+**SMALL (lane lean, padrão):** `@product` → `@sheldon` → `@dev`. Sob autopilot: `@product`, com o PRD resolvido, semeia o esquema e invoca `@sheldon`; `@sheldon`, com sizing/enriquecimento confirmados e o pacote lean + `dev-state.md` gravados, completa o próprio estágio (`aioson workflow:next . --complete=sheldon`) e invoca `@dev`. O detour opt-in full-merged do SMALL encadeia `@analyst` → `@architect` → `@dev` quando ativado (com `@scope-check`/`@discovery-design-doc` só se a sequência os inclui).
+
+**MEDIUM (lane maestro, padrão):** `@product` → `@orchestrator` → `@dev`. Sob autopilot: `@product` semeia e invoca `@orchestrator`; `@orchestrator`, com o pacote de spec com gates aprovados (Gates A/B/C, readiness pronta) + `dev-state.md` gravados, invoca `@dev`. O fan-out para `@analyst`/`@architect`/`@pm` acontece como sub-agentes, não como estágios do workflow — eles só encadeiam como estágios sob um detour opt-in full-chain.
+
+A travessia para `@dev` passa pelo pacote `dev-state.md` que o agente de spec grava — o protocolo de início de sessão do `@dev` carrega só esse pacote mínimo, então `@dev` não herda o chat pesado anterior; auto-compact transparente cuida do resto. É por isso que a travessia é segura sem um `/compact` manual. O agente de spec ainda para com o handoff manual normal se tiver uma decisão de produto/escopo/sizing em aberto, ou um gate que ele possui não aprovado. Recomende `/clear` só para reset forte, troca de feature, contexto poluído ou reset sensível a segurança.
+
+---
+
+## Segmento 2 — ciclo de revisão pós-dev (hub = `@qa`)
+
+Uma vez que um humano inicia `@dev` e ele termina, a cadeia retoma automaticamente. `@qa` é o hub; cada agente especializado volta para ele.
 
 | Agente atual | Condição | Próximo invocado |
 |---|---|---|
-| `@dev` (1ª passagem) | testes ok, sem correções abertas | `@qa` |
+| `@dev` (1ª passagem) | testes ok, gates limpos, sem ciclo de correções aberto | `@qa` |
 | `@dev` (correções) | correções aplicadas, testes ok | `@qa` (re-verificação) |
-| `@qa` | FAIL (Critical/High) | `@dev` via ciclo de correções (cap 2) |
-| `@qa` | PASS + trigger `@tester` não executado | `@tester` |
-| `@qa` | PASS + trigger `@pentester` não executado | `@pentester` |
-| `@qa` | PASS + contrato harness presente + `@validator` não PASS | `@validator` |
-| `@qa` | PASS + sem pendências | **STOP** — recomenda `aioson feature:close` |
-| `@tester` | bloqueios do dev | `@dev` |
-| `@tester` | sem bloqueios | `@qa` (re-avaliação) |
-| `@pentester` | findings abertos do dev | `@dev` |
-| `@pentester` | sem findings do dev | `@qa` (re-avaliação) |
+| `@qa` | veredito **FAIL** (Critical/High) | `@dev` via ciclo de correções (cap 3, gate de segurança) |
+| `@qa` | veredito **PASS** + trigger `@tester` dispara e ainda não rodou limpo | `@tester` |
+| `@qa` | veredito **PASS** + trigger `@pentester` dispara e ainda não rodou limpo | `@pentester` |
+| `@qa` | veredito **PASS** + contrato harness presente e `@validator` ainda não PASS | `@validator` |
+| `@qa` | veredito **PASS** + nenhum trigger/contrato pendente | **STOP** — recomenda `aioson feature:close . --feature={slug}` |
+| `@tester` | gaps bloqueantes de propriedade do dev | `@dev` |
+| `@tester` | sem gaps bloqueantes | `@qa` (reavaliação/sign-off) |
+| `@pentester` | findings abertos com `recommended_owner = dev` | `@dev` |
+| `@pentester` | sem findings abertos do dev | `@qa` (reavaliação/sign-off) |
 | `@validator` | PASS | **STOP** — recomenda `aioson feature:close` |
 | `@validator` | FAIL | `@dev` |
 
-`@tester` e `@pentester` só executam quando os seus triggers disparam (`@qa` identifica gaps de cobertura → `@tester`; superfície sensível auth/secrets/data → `@pentester`).
+**Origem do trigger para `@tester`/`@pentester`:** a lógica de trigger do `@qa` já existente (gaps de cobertura → `@tester`; superfície sensível auth/secrets/data/upload/URL externa/supply-chain → `@pentester`). Os quatro agentes estão **sempre** ligados na cadeia, mas `@tester`/`@pentester` só **executam** quando o trigger dispara — do contrário `@qa` pula direto para a próxima linha de roteamento.
+
+**Guarda de reentrada (sem loop infinito):** antes de auto-invocar um agente especializado, `@qa` checa evidência em disco de que ele já rodou limpo neste ciclo (`security-findings-{slug}.json` limpo → `@pentester` feito; artefato de cobertura do tester presente sem gap novo → `@tester` feito; `progress.json.ready_for_done_gate`/PASS do validador registrado → `@validator` feito). Um agente que já retornou limpo não é reinvocado.
 
-### Protocolo de contexto fresco do @validator
+**`@validator` roda em contexto fresco:** ao rotear para `@validator` com contrato de harness presente, não rode inline na sessão atual — o histórico de implementação enviesa o veredito. A sequência: `harness:check` (checks determinísticos) → `harness:validate` (gera `validator-prompt.txt` autocontido: critérios + resultados do check + diff vs. base) → execução em **subagente isolado** (Task tool, sem contexto de conversa) que grava o veredito em `last-validator-output.json` → `harness:validate` de novo, para consumir o veredito pelo circuit breaker. Clientes sem suporte a subagente caem para `Skill(aioson:agent:validator)` numa sessão fresca, como antes.
+
+---
 
-O `@validator` roda em contexto **fresco e isolado** (subagente/Task tool ou sessão separada), nunca inline na sessão que implementou — o histórico de implementação enviesa o veredito. Quando o autopilot roteia para `@validator`, a sequência é:
+## Condições de parada — quebram a cadeia e emitem o handoff manual normal
+
+1. **`feature:close`/publish** — SEMPRE o gate humano. Quando `@qa` (PASS, nada pendente) ou `@validator` (PASS) é o último passo limpo, STOP e recomenda `aioson feature:close . --feature={slug}`. Nunca roda `feature:close`, `feature:archive`, `npm publish`, ou qualquer ação de publish/close sozinho.
+2. **Decisão humana genuína em aberto** — um agente de spec com pergunta de produto/escopo/sizing não resolvida (uma `AskUserQuestion` aberta, ou um gate que ele possui ainda não aprovado) resolve essa decisão com o humano antes de qualquer auto-invocação, e para com o handoff manual normal. Autopilot remove paradas mecânicas, nunca decisões reais.
+3. **Cap de correções atingido** — ciclos de revisão são limitados por `agentic_policy.review_cycle` (default **3**); quando `review-cycle:advance` retorna `stop_cycle_limit`, para e escala para o humano.
+4. **Finding crítico de segurança** — o gate de segurança de correções do `@qa` (keywords auth/secret/credential/session/password/token/PII/encryption) bloqueia o auto-loop; para e exige intervenção humana.
+5. **Veredito não limpo / gate ou readiness bloqueado** — o pacote de spec maestro do `@orchestrator` sem Gates A/B/C aprovados ou com readiness `blocked`, `@validator` FAIL sem caminho seguro de correção (e, quando presentes como detours, `@architect` Gate B/readiness modo-merged `blocked`, `@pm` Gate C bloqueado, `@scope-check` não `approved`/`patched`, ou `@discovery-design-doc` readiness `blocked`): para e roteia ao dono manualmente.
+6. **Orçamento de contexto** — uso estimado ≥ `context_warning_threshold` (`.aioson/config.md`): grava o checkpoint de compactação em `.aioson/context/last-handoff.json`, para, e recomenda `/compact` para continuar a mesma feature. O workflow retoma de `.aioson/context/workflow.state.json` — a próxima sessão reentra no autopilot automaticamente. Recomende `/clear` só para reset forte, troca de feature, contexto poluído ou reset sensível a segurança.
+7. **Ambiguidade** — estado do workflow indisponível e roteamento ambíguo, ou qualquer decisão real exige input do usuário: para e pergunta, manualmente.
+
+Você pode interromper a qualquer momento com Ctrl+C; o autopilot nunca retenta uma invocação interrompida.
+
+---
+
+## Opção `--help` nos 13 agentes mais usados
+
+Uma ativação com `--help` isolado (`/<agente> --help`) faz o agente imprimir um bloco de ajuda rápido — o que faz / quando usar / opções / chamada típica / o que produz / próximo agente —, localizado no seu idioma, e parar sem fazer nenhum trabalho. Isso vale para os 13 agentes mais usados, fonte única em `.aioson/docs/agent-help.md`:
 
 ```
-harness:check                  → roda os criteria[].verification deterministicamente (exit code = veredito)
-  ↓
-harness:validate               → gera validator-prompt.txt com REVIEW PAYLOAD autocontido:
-                                   (a) resultados do harness:check
-                                   (b) lista de arquivos alterados (untracked incluídos, .aioson/** filtrado)
-                                   (c) diff unificado vs base resolvida (--base > baseline.json > merge-base > HEAD)
-  ↓
-execução isolada em subagente  → @validator julga só os critérios sem verification, em contexto limpo
-  ↓
-harness:validate (de novo)     → consome o veredito pelo circuit breaker (waiting_validation/apply-validation)
+@product · @briefing · @briefing-refiner · @dev · @deyvin · @discover ·
+@neo · @orache · @orchestrator · @tester · @pentester · @qa · @sheldon
 ```
 
-O review payload torna o prompt do validador **autocontido**: ele não precisa explorar o repositório. O diff tem teto de tamanho (`--max-diff-bytes`, default 200KB, truncamento em fronteira de linha); `--no-diff` omite o diff; fora de repo git, degrada graciosamente. A máquina de estados `waiting_validation`/`apply-validation` permanece inalterada.
+Cada agente imprime **só a própria seção**, nunca o arquivo inteiro. Fichas individuais em [`4-agentes/`](../4-agentes/README.md) linkam para essa referência quando relevante.
 
 ---
 
-## Condições de parada
+## Confiabilidade
+
+Três ajustes de confiabilidade que afetam diretamente quem usa o autopilot:
+
+- **Estado de workflow obsoleto não bloqueia mais a próxima feature.** Um `workflow.state.json` deixado por uma feature já fechada/abandonada é descartado e re-semeado automaticamente — só uma feature *genuinamente* ativa e diferente (aparece como `in_progress` em `features.md`) segue gerando o refuso `different_active_feature`. Nesse caso, a orientação é fechar/pausar a feature ativa ou rodar:
 
-O autopilot interrompe a cadeia e emite o handoff manual normal quando:
+  ```bash
+  aioson feature:sweep .
+  ```
 
-1. **`feature:close` / publish** — sempre gate humano. `@qa` PASS sem pendências ou `@validator` PASS → STOP, recomenda `aioson feature:close`.
-2. **Primeira entrada em `@dev`** — a cadeia pré-dev para aqui.
-3. **Cap de correções atingido** — ciclo `@qa` ↔ `@dev` limitado a 2 rounds.
-4. **Finding crítico de segurança** — keywords auth/secret/credential/session/password/token/PII detectados pelo gate de segurança do `@qa` → STOP, requer intervenção humana.
-5. **Verdict não passou** — `@scope-check` não aprovado, `@architect` Gate B bloqueado, `@discovery-design-doc` readiness bloqueado, `@pm` Gate C bloqueado, `@validator` FAIL sem caminho seguro → STOP, roteamento manual.
-6. **Orçamento de contexto** — uso ≥ `context_warning_threshold`: grava checkpoint em `last-handoff.json`, STOP, recomenda `/compact` para continuidade na mesma feature. A próxima sessão reentra no autopilot automaticamente. Use `/clear` apenas para reset forte, troca de feature, contexto poluído ou reset sensível a segurança.
-7. **Ambiguidade** — estado do workflow indisponível ou qualquer decisão real requer input humano → STOP.
+- **`aioson update` agora informa exatamente qual template chegou**, incluindo o build exato de uma instalação `npm link`:
 
-O usuário pode interromper a qualquer momento com Ctrl+C. O autopilot nunca retenta uma invocação interrompida.
+  ```
+  Template version applied: 1.36.0 (a1b2c3d, 2026-07-01)
+  ```
+
+  (o `(sha, data)` só aparece quando a instalação vem de um checkout git — ex.: dogfooding via `npm link`; instalações normais via npm mostram só a versão semântica.)
+
+- **A lane lean não regride mais para `@sheldon` depois da implementação.** Antes, nada resolvia o estágio `sheldon` na máquina de estados, então `aioson workflow:next --complete=dev` reativava `@sheldon` (uma ativação para trás). O estágio `sheldon` agora é reconhecido como concluído junto com o resto da cadeia — completar um estágio posterior nunca deixa `next` apontando para um estágio anterior já resolvido.
 
 ---
 
@@ -98,11 +174,10 @@ O usuário pode interromper a qualquer momento com Ctrl+C. O autopilot nunca ret
 
 Quando autopilot está ativo e nenhuma condição de parada aplica:
 
-1. O agente termina suas responsabilidades (artefatos em disco, gate, dossier, `pulse:update`, `agent:done`).
-2. Emite: `Autopilot: @<atual> done → invocando @<próximo> (Ctrl+C para interromper)`.
-3. Invoca `Skill(aioson:agent:<próximo>)` com contexto `"continue feature {slug} — autopilot handoff from @<atual>"`.
-
-O roteamento é **determinístico** — nunca escolhido pelo modelo. O próximo agente vem do state machine do workflow (`workflow.state.json` ou `aioson workflow:status .`), não de julgamento do LLM.
+1. O agente termina suas responsabilidades de fechamento primeiro (artefatos em disco, registro de gate, dossier/spec atualizados, `agent:epilogue`/`agent:done`).
+2. Se o checkpoint do runtime contém `agentic_policy.enabled=true`, deixa o gateway continuar a partir de `.aioson/context/workflow-execute.json` — não pergunta ao usuário para confirmar o próximo estágio determinístico.
+3. Sem gateway de runtime disponível, emite um aviso de transição de uma linha: `Autopilot: @<atual> done → invocando @<próximo> (Ctrl+C para interromper)`.
+4. Invoca `Skill(aioson:agent:<próximo>)` com a tarefa `"continue feature {slug} — autopilot handoff from @<atual>"`. Sem pergunta ao usuário — Ctrl+C interrompe.
 
 ---
 
@@ -112,33 +187,73 @@ O roteamento é **determinístico** — nunca escolhido pelo modelo. O próximo
 # Ver estado atual do workflow (qual agente está ativo)
 aioson workflow:status .
 
+# Semear o esquema agêntico sem avançar (agentes de spec fazem isso ao terminar)
+aioson workflow:execute . --feature=checkout --seed --tool=claude
+
+# Semear já desarmado (equivalente ao token --step)
+aioson workflow:execute . --feature=checkout --seed --step --tool=claude
+
 # Avançar manualmente (quando autopilot está desligado)
 aioson workflow:next .
 
+# Limpar workflow.state.json obsoleto de features já fechadas/abandonadas
+aioson feature:sweep .
+
 # Ver handoff preparado pelo agente anterior
 cat .aioson/context/last-handoff.json
 ```
 
 ---
 
-## Exemplo: feature MEDIUM com autopilot ativo
+## Exemplo: feature SMALL com autopilot ativo do início ao fim
 
 ```
-Você > /analyst  (start)
+Você > /product --auto build email notifications
+
+@product > PRD fechado. Modo Autopilot (token inline) — sem pergunta.
+           Semeando esquema... invocando @sheldon.
+
+@sheldon > Gates A/B/C aprovados. dev-state.md gravado.
+           Autopilot: @sheldon done → invocando @dev.
+
+@dev     > Loop de fases: 3 fases implementadas em sequência, sem parar.
+           Testes verdes. Autopilot: @dev done → invocando @qa.
+
+@qa      > PASS. Nenhum trigger de @tester/@pentester disparou. Sem harness-contract pendente.
+           STOP — "Recomendo: aioson feature:close . --feature=email-notifications"
+
+Você > aioson feature:close . --feature=email-notifications
+```
+
+---
+
+## Exemplo: feature MEDIUM, escolha feita on-screen no handoff do `@product`
+
+```
+Você > /product
+
+@product > [conduz o PRD...] PRD fechado. Classificação: MEDIUM.
+           Como você quer rodar esta feature?
+           1. Autopilot — rodar tudo até feature:close (recomendado)
+           2. Passo a passo — eu conduzo cada etapa
+           3. Sempre autopilot neste projeto
+
+Você > 3
+
+@product > Gravado auto_handoff: true em project.context.md.
+           Semeando esquema... invocando @orchestrator.
+
+@orchestrator > Fan-out @analyst + @architect + @pm (+ @ux-ui). Gates A/B/C aprovados.
+                Autopilot: @orchestrator done → invocando @dev.
 
-@analyst  → scope + domain → STOP pré-dev (autopilot para @analyst)
-@scope-check → pre-dev check → autopilot: invocando @architect
-@architect   → Gate B PASS → autopilot: invocando @discovery-design-doc
-@discovery-design-doc → readiness ok → autopilot: invocando @pm (MEDIUM)
-@pm          → Gate C PASS → STOP — "Recomendo /compact e /dev"
+@dev          > Implementado. Autopilot: @dev done → invocando @pentester (inline no MEDIUM).
 
-Você > /compact
-Você > /dev  (implementação manual — contexto limpo)
+@pentester    > Sem findings HIGH/CRITICAL. Autopilot: @pentester done → invocando @qa.
 
-@dev → testes ok → autopilot retoma: invocando @qa
-@qa  → PASS + nenhum trigger → STOP — "Execute: aioson feature:close . --feature=..."
+@qa           > PASS. Harness-contract presente, @validator ainda não PASS → invocando @validator.
 
-Você > aioson feature:close . --feature=minha-feature
+@validator    > Contexto fresco e isolado. harness:check + julgamento LLM dos critérios sem verification.
+                PASS. STOP — "Recomendo: aioson feature:close . --feature=..."
 ```
 
 ---
@@ -159,6 +274,8 @@ Veja [SDD Automation Scripts — forge:compile](./sdd-automation-scripts.md#forg
 
 ## Próximos passos
 
-- [SDD Framework](./sdd-framework.md) — sequência completa MICRO/SMALL/MEDIUM
-- [Comandos CLI](./comandos-cli.md) — `workflow:next`, `workflow:status`, `workflow:heal`
+- [SDD Framework](./sdd-framework.md) — sequência completa MICRO/SMALL/MEDIUM e as lanes lean/maestro
+- [Comandos CLI](./comandos-cli.md) — `workflow:next`, `workflow:execute`, `feature:sweep`
 - [Motor Hardening](./motor-hardening.md) — gates técnicos e auto-cura
+- [Ficha do @product](../4-agentes/product.md) — onde o modo de execução é decidido
+- [Ficha do @dev](../4-agentes/dev.md) — `--auto`/`--step` na entrada da implementação

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

@@ -226,10 +226,10 @@ Scripts determinísticos que movem verificações de estado, validação de arte
 | `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 |
-| `ac:test-audit` | Mapeia cada `AC-*` declarado em PRD/requisitos/conformance para evidência em testes ou critério executável do harness | Antes do Gate D; falha quando algum AC não tem prova de teste |
-| `sdd:benchmark` | Gera score determinístico de SDD usando cadeia de artefatos, `spec:analyze` e `ac:test-audit`; salva relatório em `.aioson/context/retro/` | Para medir a qualidade do harness sem depender de julgamento solto |
-| `spec:analyze` | Irmão de **conteúdo** do `artifact:validate`: consistência cruzada entre os artefatos (rastreabilidade REQ/AC, staleness, readiness, sanidade do contrato, vínculo AC→contrato, overlap de waves) antes do gate de execução | No preflight do `@scope-check` — errors viram blockers, warnings viram evidência de drift |
+| `artifact:validate` | Verifica a cadeia completa de artefatos de uma feature (PRD → spec → plano → conformance) | A qualquer momento para checar completude |
+| `ac:test-audit` | Mapeia cada `AC-*` declarado em PRD/requisitos/conformance para evidência em testes ou critério executável do harness | Antes do Gate D; falha quando algum AC não tem prova de teste |
+| `sdd:benchmark` | Gera score determinístico de SDD usando cadeia de artefatos, `spec:analyze` e `ac:test-audit`; salva relatório em `.aioson/context/retro/` | Para medir a qualidade do harness sem depender de julgamento solto |
+| `spec:analyze` | Irmão de **conteúdo** do `artifact:validate`: consistência cruzada entre os artefatos (rastreabilidade REQ/AC, staleness, readiness, sanidade do contrato, vínculo AC→contrato, overlap de waves) antes do gate de execução | No preflight do `@scope-check` — errors viram blockers, warnings viram evidência de drift |
 | `forge:compile` | **Lane B:** compila os artefatos de uma feature MEDIUM num `forge-run.workflow.js` auditável e versionável (parallel por Wave → convergência no `harness:check` → revisão adversarial → validador fresh-context) | Quando quer execução compilada e reproduzível via `@forge-run`; nunca roda `feature:close`/publish |
 | `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 |
 | `runner:run` | Executa uma tarefa ou worker diretamente pelo runner | Quando quer executar fora do loop principal de sessão |
@@ -375,7 +375,7 @@ aioson update .
 aioson doctor . --fix
 ```
 
-Use depois de atualizar a versão do pacote. O `update` mexe só nos arquivos gerenciados e o `doctor --fix` recoloca o que estiver faltando.
+Use depois de atualizar a versão do pacote. O `update` mexe só nos arquivos gerenciados e o `doctor --fix` recoloca o que estiver faltando. Ao terminar, `update` imprime `Template version applied: <versão>` (e `(<sha>, <data>)` quando a instalação vem de um checkout git, como um `npm link` de dogfooding) — assim dá para conferir exatamente qual template chegou.
 
 ### 4. Ver e ajustar configurações globais
 
@@ -989,7 +989,7 @@ O manifest em `.aioson/context/done/MANIFEST.md` registra todas as features arqu
 # Verificar se está no safe zone (< 60%), warning (60–80%) ou critical (≥ 80%)
 aioson context:monitor . --budget=80000 --tokens=52000
 # ⚠ Context: 52,000 tokens (65%) — WARNING
-# Suggestion: /compact before next agent activation; use /clear only for a hard reset
+# Suggestion: /compact before next agent activation; use /clear only for a hard reset
 
 # Verificar com output JSON para integrar em scripts
 aioson context:monitor . --budget=80000 --tokens=67000 --json
@@ -1742,8 +1742,17 @@ aioson workflow:execute . \
   --feature=checkout \
   --tool=claude \
   --start-from=dev
+
+# Semear o esquema agêntico do full-feature autopilot sem avançar estágio
+# (é isso que @product/@sheldon/@orchestrator rodam ao terminar sob autopilot)
+aioson workflow:execute . --feature=checkout --seed --tool=claude
+
+# Semear já desarmado — equivalente ao token inline /product --step
+aioson workflow:execute . --feature=checkout --seed --step --tool=claude
 ```
 
+Um `workflow.state.json` deixado por uma feature já fechada/abandonada é descartado e re-semeado automaticamente — só uma feature *diferente e genuinamente ativa* (`in_progress` em `features.md`) gera o refuso `different_active_feature`. Nesse caso, feche/pause a feature ativa ou rode `aioson feature:sweep .` para limpar o estado obsoleto. Veja [Autopilot Handoff](./autopilot-handoff.md) para a cadeia completa, os tokens `--auto`/`--step` e as condições de parada.
+
 ### 52. Enfileirar fases do plano no runner
 
 ```bash
@@ -1877,7 +1886,7 @@ aioson harness:retro . --last=5
 aioson harness:retro . --feature=checkout --json
 ```
 
-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.
+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/skills.md

@@ -158,6 +158,8 @@ Skills de design disponíveis:
 - `interface-design` — Design de interfaces (dashboards, apps, ferramentas)
 - `premium-command-center-ui` — UI premium para command centers
 
+A skill `interface-design` é um **motor**: antes de desenhar, ela resolve um `identity.md` — primeiro `.aioson/briefings/{slug}/identity.md`, depois `.aioson/context/identity.md` — e aplica essa identidade em tudo que produz; sem `identity.md`, roda intent-first. O `identity.md` é extraído **uma única vez** das suas imagens de referência pela skill de processo `reference-identity-extract`, e todo consumidor do motor (`@dev`, `@ux-ui`, protótipos) herda essa resolução. Ele é *input* do motor — não um segundo design skill.
+
 ## Skills de processo
 
 Skills de processo ensinam os agentes **como as fases do AIOSON se conectam** — não o que implementar, mas como sequenciar, quando aprofundar e como fazer handoff limpo entre agentes.

package/docs/pt/agentes.md

@@ -56,9 +56,11 @@ O AIOSON tem agentes oficiais de projeto e também pode criar agentes de squad.
 Quando o projeto ja existe e voce roda `scan:project`, o handoff correto agora e:
 
 ```text
-scan:project -> @analyst -> @scope-check -> @architect -> @dev
+scan:project -> @analyst -> @scope-check -> @dev (ou @architect quando o full-merged opt-in do SMALL estiver ativo)
 ```
 
+> Desde a lane lean (v1.35.0), `@analyst`/`@architect` nao sao mais hops obrigatorios do fluxo padrao apos o scan. A classificacao decide a lane: SMALL segue `@sheldon` como autoridade unica de spec (`@product -> @sheldon -> @dev`), MEDIUM segue o maestro `@orchestrator` (que dispara `@analyst`/`@architect`/`@pm` como sub-agentes do fan-out). Um `@analyst` isolado logo apos o scan continua valido como detour opt-in para mapear o dominio existente antes de abrir a primeira feature.
+
 Regras do fluxo:
 - os artefatos locais do scan (`scan-index.md`, `scan-folders.md`, `scan-<pasta>.md`, `scan-aioson.md`) servem como mapas brutos do codigo
 - `discovery.md` continua sendo a memoria comprimida que os agentes usam para entender o sistema sem reler tudo

package/package.json

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

package/src/agents.js

@@ -67,7 +67,7 @@ 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.${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. The chain stops before the first `@dev` activation (human clears context and starts implementation) and continues through the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their triggers fire → `@validator`); it NEVER auto-runs `feature:close`/publish — those require explicit human approval.' : ''}`,
+    `**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. The chain runs the whole feature: the spec authority (`@sheldon`/`@orchestrator`) seeds the agentic scheme and crosses into `@dev` via the `dev-state.md` cold-start packet once its own gates/decisions are settled, and the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their triggers fire → `@validator`) continues automatically. It stops only for a genuine human decision or a stop condition, and NEVER auto-runs `feature:close`/publish — those require explicit human approval.' : ''}`,
   ].join('\n');
 
   if (safeTool === 'claude') {

package/src/artifact-kinds.js

@@ -29,7 +29,8 @@ const AGENT_ARTIFACT_KIND = {
   'design-hybrid-forge': { kind: 'hybrid-skill', needs: 'slug' },
   copywriter: { kind: 'copy', needs: 'slug' },
   orache: { kind: 'orache-report', needs: 'file' },
-  'site-forge': { kind: 'site', needs: 'dir', opts: { noBuild: true } }
+  'site-forge': { kind: 'site', needs: 'dir', opts: { noBuild: true } },
+  'briefing-refiner': { kind: 'review', needs: 'slug' }
 };
 
 const NEEDS_FLAG = { slug: '--slug=<slug>', file: '--file=<path>', dir: '--dir=<dir>' };

package/src/autopilot-signal.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * Autopilot activation signal — the single source of truth for "is autopilot
+ * on?" outside the agent markdown files.
+ *
+ * Contract (docs/autopilot-handoff.md "Activation"), highest precedence first:
+ *   - A scheme for the CURRENT feature with `agentic_policy.enabled: false`
+ *     (the `--step` disarm) → OFF, even over `auto_handoff: true` — an explicit
+ *     per-feature choice always wins over the project default.
+ *   - `auto_handoff: true` in project.context.md frontmatter → ON (project default).
+ *   - `auto_handoff: false` → OFF, even if a seeded scheme is lying around
+ *     (step-by-step is the standing choice; a leftover scheme must not override it).
+ *   - flag absent → ON only when `.aioson/context/workflow-execute.json` exists
+ *     with `agentic_policy.enabled: true` (the per-feature "Autopilot" choice,
+ *     which deliberately does NOT persist the frontmatter flag). When a slug is
+ *     provided, the scheme counts only if it was seeded for THAT feature — a
+ *     scheme left by a different/closed feature does not.
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { validateProjectContextFile } = require('./context');
+
+const EXECUTION_STATE_RELATIVE_PATH = '.aioson/context/workflow-execute.json';
+
+async function readSeededScheme(targetDir) {
+  try {
+    const raw = await fs.readFile(path.join(targetDir, EXECUTION_STATE_RELATIVE_PATH), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function resolveAutopilotSignal(targetDir, { slug = null, projectContext = null } = {}) {
+  let flag;
+  try {
+    const context = projectContext || await validateProjectContextFile(targetDir);
+    flag = context && context.data && Object.prototype.hasOwnProperty.call(context.data, 'auto_handoff')
+      ? context.data.auto_handoff === true
+      : null;
+  } catch {
+    flag = null;
+  }
+
+  const scheme = await readSeededScheme(targetDir);
+  const slugMatches = Boolean(
+    scheme && (!slug || !scheme.feature || String(scheme.feature) === String(slug))
+  );
+
+  // Explicit per-feature disarm (--step) beats the project-wide flag.
+  if (
+    scheme && scheme.agentic_policy && scheme.agentic_policy.enabled === false &&
+    slugMatches
+  ) {
+    return { enabled: false, source: 'scheme_disarmed' };
+  }
+
+  if (flag === true) return { enabled: true, source: 'frontmatter' };
+  if (flag === false) return { enabled: false, source: 'frontmatter_off' };
+
+  const schemeEnabled = Boolean(scheme && scheme.agentic_policy && scheme.agentic_policy.enabled === true);
+  if (!schemeEnabled) return { enabled: false, source: null };
+  if (!slugMatches) return { enabled: false, source: 'scheme_other_feature' };
+  return { enabled: true, source: 'seeded_scheme' };
+}
+
+module.exports = {
+  resolveAutopilotSignal
+};

package/src/cli.js

@@ -237,7 +237,7 @@ const { runGenomePublish, runGenomeInstallStore, runGenomeInstall, runGenomeList
 const { runSkillPublish, runSkillInstallStore, runSkillListRemote } = require('./commands/store-skill');
 const { runSquadPublish, runSquadInstall, runSquadGrant, runSquadList } = require('./commands/store-squad');
 const { runSystemPackage, runSystemPublish, runSystemList, runSystemInstall } = require('./commands/store-system');
-const { runBriefingApprove, runBriefingUnapprove } = require('./commands/briefing');
+const { runBriefingApprove, runBriefingUnapprove, runBriefingReview, runBriefingApplyFeedback } = require('./commands/briefing');
 const { runCompressAgents } = require('./commands/compress-agents');
 
 const JSON_SUPPORTED_COMMANDS = new Set([
@@ -354,6 +354,10 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'audit-code',
   'verify:artifact',
   'verify-artifact',
+  'briefing:review',
+  'briefing-review',
+  'briefing:apply-feedback',
+  'briefing-apply-feedback',
   'review:feature',
   'review-feature',
   'config',
@@ -1770,6 +1774,10 @@ async function main() {
       result = await runBriefingApprove({ args, options, logger: commandLogger });
     } else if (command === 'briefing:unapprove' || command === 'briefing-unapprove') {
       result = await runBriefingUnapprove({ args, options, logger: commandLogger });
+    } else if (command === 'briefing:review' || command === 'briefing-review') {
+      result = await runBriefingReview({ args, options, logger: commandLogger });
+    } else if (command === 'briefing:apply-feedback' || command === 'briefing-apply-feedback') {
+      result = await runBriefingApplyFeedback({ args, options, logger: commandLogger });
     } else {
       const message = t('cli.unknown_command', { command });
       if (jsonMode) {