@jaimevalasek/aioson 1.36.0 → 1.37.1

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.1",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",

package/src/agent-execution/adapters/base.js

@@ -0,0 +1,15 @@
+'use strict';
+const { spawn } = require('node:child_process');
+const { capabilities, requiredCapability } = require('../capabilities');
+const { resolveExecutable } = require('../executable-resolver');
+function redact(text) { return String(text||'').replace(/(authorization\s*[:=]\s*(?:bearer\s+)?|api[_-]?key\s*[:=]\s*|token\s*[:=]\s*|password\s*[:=]\s*)[^\s,;]+/gi,'$1[REDACTED]'); }
+function normalizeError(error) { const text=String(error?.message||error||'').toLowerCase(); if(/unexpected argument|invalid (?:argument|option)|unknown option/.test(text))return'invalid_arguments';if(/capacity|overloaded|rate limit/.test(text)) return 'capacity'; if(/model.*invalid|unknown model/.test(text)) return 'invalid_model'; if(/unauthorized|authentication failed|not authenticated|forbidden/.test(text)) return 'auth'; if(/timeout|timed out/.test(text)) return 'timeout'; return 'crash'; }
+function createAdapter(host, buildArgs) {
+  return {
+    host,
+    probe() { return capabilities(host); },
+    build(input) { const cap=this.probe(); const required=requiredCapability(input.mode); if(required && !cap[required]) return {ok:false,reason:'unsupported_capability',capability:required,host};if(input.reasoning_effort&&!cap.reasoning_effort)return{ok:false,reason:'unsupported_reasoning_effort',capability:'reasoning_effort',host};if(input.writable_roots?.length&&!cap.additional_workspaces)return{ok:false,reason:'host_capability_missing',capability:'additional_workspaces',host};const command=buildArgs(input);const args=Array.isArray(command)?command:command.args;return {ok:true,executable:cap.executable,args,stdin:Boolean(command.stdin),options:{cwd:input.cwd,shell:false,stdio:'pipe'}}; },
+    async execute(input) { const built=this.build(input); if(!built.ok) return built;let resolved;try{resolved=await resolveExecutable(built.executable,input.resolverOptions)}catch(error){return{ok:false,reason:'executable_not_found',error:redact(error.message)}}return new Promise(resolve=>{ const child=spawn(resolved.executable,[...resolved.prefixArgs,...built.args],built.options); input.onSpawn?.(child.pid,new Date().toISOString());let stderr='';let timedOut=false;let settled=false;child.stdout.on('data',d=>input.onStdout?.(d));child.stderr.on('data',d=>{input.onStderr?.(d);stderr+=d;if(stderr.length>4000)stderr=stderr.slice(-4000)});if(built.stdin)child.stdin.end(String(input.prompt_text||''));else child.stdin.end();const finish=result=>{if(settled)return;settled=true;if(timer)clearTimeout(timer);child.stdout.destroy();child.stderr.destroy();input.onExit?.(result);resolve(result)};const timer=input.timeout?setTimeout(()=>{timedOut=true;child.kill()},input.timeout):null;child.on('error',e=>finish({ok:false,reason:normalizeError(e),error:redact(e.message)}));child.on('exit',code=>finish(code===0&&!timedOut?{ok:true,code,resolver_source:resolved.source}:{ok:false,code,reason:timedOut?'timeout':normalizeError(stderr),error:redact(stderr).slice(0,1000),resolver_source:resolved.source})); }); }
+  };
+}
+module.exports={createAdapter,normalizeError,redact};

package/src/agent-execution/adapters/claude.js

@@ -0,0 +1,3 @@
+'use strict';
+const { createAdapter } = require('./base');
+module.exports=createAdapter('claude',i=>['--print',...(i.model==='configured-default'?[]:['--model',i.model]),...(i.writable_roots?.length?['--add-dir',...i.writable_roots]:[]),i.prompt_text]);

package/src/agent-execution/adapters/codex.js

@@ -0,0 +1,3 @@
+'use strict';
+const { createAdapter } = require('./base');
+module.exports=createAdapter('codex',i=>({args:['exec',...(i.model==='configured-default'?[]:['--model',i.model]),...(i.reasoning_effort?['-c',`model_reasoning_effort="${i.reasoning_effort}"`]:[]),...(i.writable_roots||[]).flatMap(root=>['--add-dir',root]),'-'],stdin:true}));

package/src/agent-execution/adapters/opencode.js

@@ -0,0 +1,3 @@
+'use strict';
+const { createAdapter } = require('./base');
+module.exports=createAdapter('opencode',i=>['run',...(i.model==='configured-default'?[]:['--model',i.model]),i.prompt_text]);

package/src/agent-execution/capabilities.js

@@ -0,0 +1,9 @@
+'use strict';
+const MATRIX = {
+  claude: { native_subagent: false, fresh_session: false, external_process: true, additional_workspaces: true, model_catalog: false, reasoning_effort: false, executable: 'claude' },
+  codex: { native_subagent: false, fresh_session: false, external_process: true, additional_workspaces: true, model_catalog: true, reasoning_effort: true, executable: 'codex' },
+  opencode: { native_subagent: false, fresh_session: false, external_process: true, additional_workspaces: false, model_catalog: false, reasoning_effort: false, executable: 'opencode' }
+};
+function capabilities(host) { return { ...(MATRIX[host] || {}), source: 'registered_adapter' }; }
+function requiredCapability(mode) { return mode === 'subagent' ? 'native_subagent' : mode === 'fresh-session' ? 'fresh_session' : mode === 'external' ? 'external_process' : null; }
+module.exports = { MATRIX, capabilities, requiredCapability };

package/src/agent-execution/dispatcher.js

@@ -0,0 +1,72 @@
+'use strict';
+const fs=require('node:fs/promises');const path=require('node:path');const crypto=require('node:crypto');
+const adapters={claude:require('./adapters/claude'),codex:require('./adapters/codex'),opencode:require('./adapters/opencode')};
+const {loadManifest,resolveAgentExecution,resolveExecutionEntry}=require('./manifest');
+const {safeReportPath,validateReport}=require('./reports');
+const {createTelemetryBridge}=require('./telemetry-bridge');
+const TERMINAL=['approved','failed','cancelled'];const LEASE_MS=30000;
+function statePath(projectDir,feature){return path.join(projectDir,'.aioson','context',`agent-execution-state-${feature}.json`)}
+function leasePath(projectDir,feature){return `${statePath(projectDir,feature)}.lock`}
+async function atomic(file,value){await fs.mkdir(path.dirname(file),{recursive:true});const tmp=`${file}.${process.pid}.${crypto.randomUUID()}.tmp`;await fs.writeFile(tmp,`${JSON.stringify(value,null,2)}\n`);await fs.rename(tmp,file)}
+async function readState(projectDir,feature){try{return JSON.parse(await fs.readFile(statePath(projectDir,feature),'utf8'))}catch(e){if(e.code==='ENOENT')return null;throw e}}
+async function acquireLease(projectDir,feature){const file=leasePath(projectDir,feature);await fs.mkdir(path.dirname(file),{recursive:true});const owner=crypto.randomUUID();for(let pass=0;pass<2;pass++){try{const h=await fs.open(file,'wx');await h.writeFile(JSON.stringify({owner,expires_at:Date.now()+LEASE_MS}));await h.close();return{file,owner}}catch(e){if(e.code!=='EEXIST')throw e;try{const current=JSON.parse(await fs.readFile(file,'utf8'));if(current.expires_at>Date.now())return null;await fs.unlink(file)}catch(readError){if(readError.code!=='ENOENT'&&readError.name!=='SyntaxError')throw readError}}}return null}
+async function releaseLease(lease){if(!lease)return;try{const current=JSON.parse(await fs.readFile(lease.file,'utf8'));if(current.owner===lease.owner)await fs.unlink(lease.file)}catch(e){if(e.code!=='ENOENT')throw e}}
+async function safePromptPath(projectDir,promptPath){const root=await fs.realpath(projectDir);const candidate=path.resolve(root,promptPath||'.aioson/context/dev-state.md');const real=await fs.realpath(candidate);if(real!==root&&!real.startsWith(root+path.sep))throw new Error('prompt_path escapes project workspace');const stat=await fs.stat(real);if(!stat.isFile())throw new Error('prompt_path must be a regular file');return real}
+async function resolveWritableRoots(projectDir,roots=[]){const resolved=[];for(const configured of roots){if(typeof configured!=='string'||!configured.trim())throw new Error('writable_root must be a non-empty path');if(configured.split(/[\\/]+/).includes('..'))throw new Error(`writable_root traversal is forbidden: ${configured}`);const candidate=path.resolve(projectDir,configured);let real;try{real=await fs.realpath(candidate)}catch{throw new Error(`writable_root does not exist: ${configured}`)}if(!(await fs.stat(real)).isDirectory())throw new Error(`writable_root is not a directory: ${configured}`);if(!resolved.includes(real))resolved.push(real)}return resolved}
+function capacitySequence(manifest,resolved){const policy=manifest.capacity_policy;if(policy.strategy!=='fallback')return[];return resolved.fallbacks.filter(item=>policy.allow_cross_host===true||item.host===resolved.host)}
+function applyCapacityPolicy(manifest,resolved,attemptCount=0){const p=manifest.capacity_policy;if(attemptCount>=p.max_attempts)return{action:'pause',reason:'capacity_limit'};if(p.strategy==='fallback'){const sequence=capacitySequence(manifest,resolved);return sequence.length?{action:'fallback',sequence}:{action:'pause',reason:'no_authorized_fallback'}}if(p.strategy==='retry'||p.strategy==='wait')return{action:p.strategy,backoff_ms:p.backoff_ms};return{action:'pause'}}
+async function executeWithCapacityPolicy({manifest,resolved,input,adapterRegistry=adapters,catalogLoader,wait=(ms)=>new Promise(resolve=>setTimeout(resolve,ms))}) {
+  const history=[];
+  const primary=resolved.ok?resolved:await resolveExecutionEntry(resolved,{catalogLoader});
+  if(!primary.ok)return{ok:false,reason:primary.reason,candidates:primary.candidates||[],history};
+  const candidates=[primary,...capacitySequence(manifest,resolved).map(item=>({...resolved,ok:false,host:item.host,model:item.model,model_requested:undefined}))];
+  let index=0;
+  for(let count=0;count<manifest.capacity_policy.max_attempts;count++){
+    let candidate=candidates[index];
+    if(!candidate.ok){
+      candidate=await resolveExecutionEntry(candidate,{catalogLoader});
+      candidates[index]=candidate;
+      if(!candidate.ok){
+        history.push({attempt:count+1,host:candidate.host,model_requested:candidate.model_requested||candidate.model,model:null,reason:candidate.reason});
+        return{ok:false,reason:candidate.reason,candidates:candidate.candidates||[],history};
+      }
+    }
+    const adapter=adapterRegistry[candidate.host];
+    if(!adapter)return{ok:false,reason:'unsupported_host',history};
+    const prompt_text=String(input.prompt_text||'')
+      .replace(/host=[^,\n]+/,`host=${candidate.host}`)
+      .replace(/model_resolved=[^,\n]+/,`model_resolved=${candidate.model}`)
+      .replace(/model_resolution_strategy=[^,\n]+/,`model_resolution_strategy=${candidate.model_resolution_strategy}`);
+    const result=await adapter.execute({...input,prompt_text,mode:candidate.mode,model:candidate.model,reasoning_effort:candidate.reasoning_effort});
+    history.push({attempt:count+1,host:candidate.host,model_requested:candidate.model_requested,model:candidate.model,model_resolution_strategy:candidate.model_resolution_strategy,reasoning_effort:candidate.reasoning_effort,reason:result.reason||null});
+    if(result.ok)return{...result,host:candidate.host,model:candidate.model,model_requested:candidate.model_requested,model_resolution_strategy:candidate.model_resolution_strategy,reasoning_effort:candidate.reasoning_effort,history};
+    if(result.reason!=='capacity')return{...result,history};
+    const decision=applyCapacityPolicy(manifest,resolved,count);
+    if(decision.action==='pause')return{ok:false,reason:decision.reason||'capacity',history};
+    if(decision.action==='fallback'){
+      if(index+1>=candidates.length)return{ok:false,reason:'fallback_exhausted',history};
+      index+=1;
+    }else if(decision.action==='wait'||decision.action==='retry'){
+      if(decision.backoff_ms)await wait(decision.backoff_ms);
+    }
+  }
+  return{ok:false,reason:'capacity_limit',history};
+}
+function buildExecutionPrompt(promptText,expected,reportPath){return `${promptText}\n\nAIOSON EXECUTION CONTRACT\nComplete the requested agent work, then write exactly one JSON report to: ${reportPath}\nThe report must include: version=1, feature=${expected.feature}, run_id=${expected.run_id}, attempt_id=${expected.attempt_id}, agent=${expected.agent}, host=${expected.host}, model_requested=${expected.model_requested}, model_resolved=${expected.model_resolved}, model_resolution_strategy=${expected.model_resolution_strategy}, reasoning_effort=${expected.reasoning_effort||'null'}, manifest_digest=${expected.manifest_digest}, writable_roots=${JSON.stringify(expected.writable_roots)}, started_at, finished_at, verdict (PASS|FAIL|BLOCKED), findings[], evidence[]. Do not report PASS unless the work and verification completed.`}
+async function readBoundReport(projectDir,relative,expected){const file=safeReportPath(projectDir,relative);let report;try{report=JSON.parse(await fs.readFile(file,'utf8'))}catch(error){return{ok:false,reason:error.code==='ENOENT'?'report_missing':'report_invalid_json',error:error.message}}const validation=validateReport(report,expected);return validation.ok?{ok:true,file,report}:{ok:false,reason:'report_binding_invalid',errors:validation.errors}}
+async function dispatch({projectDir,feature,agent='dev',runId,promptPath,adapterRegistry=adapters,catalogLoader,timeout=600000}){
+ const lease=await acquireLease(projectDir,feature);if(!lease)return{ok:false,status:'paused',reason:'lease_held',resume_command:`aioson agent:execution:resume . --feature=${feature}`};
+ try{const loaded=await loadManifest(projectDir,feature);if(!loaded.exists)return{ok:false,status:'paused',reason:'manifest_missing',resume_command:`aioson agent:execution:resume . --feature=${feature}`};if(!loaded.ok)return{ok:false,status:'paused',reason:'manifest_invalid',errors:loaded.errors};
+  let state=await readState(projectDir,feature);if(state&&state.manifest_digest!==loaded.digest&&!TERMINAL.includes(state.status))return{ok:false,status:'paused',reason:'manifest_digest_changed',expected:state.manifest_digest,actual:loaded.digest};if(state?.completed_agents?.includes(agent))return{ok:true,status:state.status,idempotent:true,state};
+  let safePrompt;try{safePrompt=await safePromptPath(projectDir,promptPath)}catch(error){return{ok:false,status:'paused',reason:'invalid_prompt_path',error:error.message}}
+  const resolved=await resolveAgentExecution(loaded.manifest,agent,{}, {catalogLoader});if(!resolved.ok)return{ok:false,status:'paused',reason:resolved.reason,candidates:resolved.candidates||[],supported:resolved.supported||[]};const adapter=adapterRegistry[resolved.host];const run_id=runId||state?.run_id||crypto.randomUUID();const attempt_id=crypto.randomUUID();if(!adapter)return{ok:false,status:'paused',reason:'unsupported_host'};let writableRoots;try{writableRoots=await resolveWritableRoots(projectDir,resolved.writable_roots)}catch(error){return{ok:false,status:'paused',reason:'invalid_writable_root',error:error.message}}const reportRelative=resolved.report.replace(/\{run_id\}/g,run_id);const reportFile=safeReportPath(projectDir,reportRelative);const expected={feature,run_id,attempt_id,agent,host:resolved.host,model_requested:resolved.model_requested,model_resolved:resolved.model,model_resolution_strategy:resolved.model_resolution_strategy,reasoning_effort:resolved.reasoning_effort,manifest_digest:loaded.digest,writable_roots:writableRoots,status:'running'};const promptText=await fs.readFile(safePrompt,'utf8');const executionInput={mode:resolved.mode,model:resolved.model,reasoning_effort:resolved.reasoning_effort,writable_roots:writableRoots,cwd:projectDir,prompt_text:buildExecutionPrompt(promptText,expected,path.relative(projectDir,reportFile)),timeout};const built=adapter.build(executionInput);
+  const correlation={feature,agent,dispatcher_run_id:run_id,attempt_id,host:resolved.host,model:resolved.model,model_requested:resolved.model_requested,model_resolved:resolved.model,reasoning_effort:resolved.reasoning_effort,model_resolution_strategy:resolved.model_resolution_strategy,catalog_source:resolved.catalog_source};const telemetry=await createTelemetryBridge(projectDir,correlation);
+  const attempt={...expected,telemetry_run_id:telemetry.run.telemetry_run_id,status:built.ok?'running':'blocked',reason:built.reason||null,report:reportRelative};state={version:1,feature,run_id,manifest_path:path.relative(projectDir,loaded.path),manifest_digest:loaded.digest,status:built.ok?'running':'paused',reason:built.reason||null,attempts:[...(state?.attempts||[]),attempt],completed_agents:state?.completed_agents||[],updated_at:new Date().toISOString()};await atomic(statePath(projectDir,feature),state);if(!built.ok){telemetry.transition('paused',built.reason);telemetry.close();return{ok:false,status:'paused',reason:built.reason,capability:built.capability,resume_command:`aioson agent:execution:resume . --feature=${feature}`,state}};
+  Object.assign(executionInput,{onSpawn:(pid,at)=>telemetry.onSpawn(pid,at),onStdout:d=>telemetry.output('stdout',d),onStderr:d=>telemetry.output('stderr',d)});
+  const execution=await executeWithCapacityPolicy({manifest:loaded.manifest,resolved,input:executionInput,adapterRegistry,catalogLoader});attempt.execution_history=execution.history||[];for(const item of attempt.execution_history){if(item.attempt>1)telemetry.event(item.host===resolved.host?'retry':'fallback',`${item.host}/${item.model}`,{attempt:item.attempt,reason:item.reason})}attempt.model_resolved=execution.model||resolved.model;attempt.model_resolution_strategy=execution.model_resolution_strategy||resolved.model_resolution_strategy;attempt.reasoning_effort=execution.reasoning_effort||resolved.reasoning_effort;attempt.host_resolved=execution.host||resolved.host;if(!execution.ok){attempt.status='blocked';attempt.reason=execution.reason;state.status='paused';state.reason=execution.reason;state.updated_at=new Date().toISOString();await atomic(statePath(projectDir,feature),state);if(execution.reason==='timeout')telemetry.event('timeout','Execution timeout');telemetry.transition('paused',execution.reason);telemetry.close();return{ok:false,status:'paused',reason:execution.reason,candidates:execution.candidates||[],execution,state,resume_command:`aioson agent:execution:resume . --feature=${feature}`}}
+  telemetry.transition('waiting_report');
+  const boundExpected={...expected,host:attempt.host_resolved,model_resolved:attempt.model_resolved,model_resolution_strategy:attempt.model_resolution_strategy,reasoning_effort:attempt.reasoning_effort,status:'running'};const reportResult=await readBoundReport(projectDir,reportRelative,boundExpected);if(!reportResult.ok){attempt.status='blocked';attempt.reason=reportResult.reason;state.status='paused';state.reason=reportResult.reason;state.updated_at=new Date().toISOString();await atomic(statePath(projectDir,feature),state);telemetry.transition('paused',reportResult.reason);telemetry.close();return{ok:false,status:'paused',reason:reportResult.reason,report:reportResult,state,resume_command:`aioson agent:execution:resume . --feature=${feature}`}}
+  const digest=crypto.createHash('sha256').update(JSON.stringify(reportResult.report)).digest('hex');telemetry.report(reportResult.report,reportRelative,digest);attempt.status='completed';attempt.verdict=reportResult.report.verdict;state.status=reportResult.report.verdict==='PASS'?'verification_planned':'correcting';telemetry.transition(reportResult.report.verdict==='PASS'?'passed':reportResult.report.verdict==='FAIL'?'failed':'correcting');telemetry.close();if(reportResult.report.verdict==='PASS'&&!state.completed_agents.includes(agent))state.completed_agents.push(agent);state.updated_at=new Date().toISOString();await atomic(statePath(projectDir,feature),state);return{ok:true,status:state.status,run_id,attempt_id,execution,report:reportResult.report,state};
+ }finally{await releaseLease(lease)}
+}
+module.exports={acquireLease,applyCapacityPolicy,buildExecutionPrompt,capacitySequence,dispatch,executeWithCapacityPolicy,leasePath,readBoundReport,readState,releaseLease,resolveWritableRoots,safePromptPath,statePath};

package/src/agent-execution/executable-resolver.js

@@ -0,0 +1,7 @@
+'use strict';
+const fs=require('node:fs/promises');const path=require('node:path');
+async function isFile(file){try{return(await fs.stat(file)).isFile()}catch{return false}}
+async function resolveNpmCmdShim(cmdPath){const text=await fs.readFile(cmdPath,'utf8');const dir=path.dirname(cmdPath);const matches=[...text.matchAll(/["'](%~dp0|%dp0%)[\\/]?([^"']+\.(?:js|exe))["']/gi)];const targets=matches.map(match=>path.resolve(dir,match[2].replace(/[\\/]+/g,path.sep))).filter(file=>!/[\\/]node\.exe$/i.test(file));for(const target of targets.reverse()){if(!(await isFile(target)))continue;const real=await fs.realpath(target);return path.extname(real).toLowerCase()==='.js'?{executable:process.execPath,prefixArgs:[real],source:'npm_cmd_js'}:{executable:real,prefixArgs:[],source:'npm_cmd_exe'}}throw new Error(`Unsupported or invalid npm command shim: ${cmdPath}`)}
+async function resolveExecutable(command,{env=process.env,platform=process.platform}={}){if(typeof command!=='string'||!command.trim())throw new Error('Executable is required');const raw=command.trim();if(path.isAbsolute(raw)){if(!(await isFile(raw)))throw new Error(`Executable not found: ${raw}`);return platform==='win32'&&path.extname(raw).toLowerCase()==='.cmd'?resolveNpmCmdShim(raw):{executable:await fs.realpath(raw),prefixArgs:[],source:'absolute'}}if(platform!=='win32')return{executable:raw,prefixArgs:[],source:'path'};const dirs=String(env.PATH||env.Path||'').split(';').filter(Boolean);for(const dir of dirs){for(const ext of ['.exe','.cmd','']){const candidate=path.join(dir,`${raw}${ext}`);if(!(await isFile(candidate)))continue;if(ext==='.cmd')return resolveNpmCmdShim(candidate);if(ext==='.exe')return{executable:await fs.realpath(candidate),prefixArgs:[],source:'windows_exe'};}}
+ throw new Error(`Executable not found on PATH: ${raw}`)}
+module.exports={resolveExecutable,resolveNpmCmdShim};