atlas-workflow 0.9.1 → 0.9.3

package/hosts/zcode/packages/orchestrator/README.md

@@ -0,0 +1,270 @@
+# Atlas Workflow Orchestrator
+
+Orquestra pipelines completos de desenvolvimento de features no projeto Atlas, automatizando a sequência de skills (PRD generation → planejamento → execução → review) sob demanda.
+
+## Quick Start
+
+```bash
+/workflow full backlog-item "S05"
+```
+
+Pipeline completo executado automaticamente:
+1. Gera PRD para sprint S05
+2. Valida PRD (detecta ambiguidades automaticamente)
+3. Executa entrevista se houver decisões em aberto
+4. Cria plano
+5. Executa plano
+6. (Opcional) Executa review
+
+## Sintaxe
+
+```
+/workflow <mode> <input-type> [flags]
+```
+
+### Modes
+
+- `full` — Pipeline completo (PRD → plano → executor → review opcional)
+- `direct` — Pipeline enxuto (PRD → executor → review opcional)
+- `interview-only` — Entrevista direta (brainstorm, resolução de decisões)
+
+### Input Types
+
+- `backlog-item` — Sprint ID (ex: S05) ou indicação direta
+- `idea` — Indicação/brainstorm curto
+- `prd` — Path para PRD existente
+- `brainstorm` — Texto livre (só para interview-only)
+
+### Flags
+
+- `--interview` — Força entrevista de PRD mesmo sem ambiguidades
+- `--review` — Executa slice-review ao final
+- `--help` — Mostra sintaxe completa
+
+## Exemplos
+
+### Full pipeline com sprint S05
+
+```
+/workflow full backlog-item "S05"
+```
+
+Output:
+```
+✅ Workflow: claude full backlog-item completed
+
+📄 PRD: /path/to/PRD_S05_login.md
+📋 Plan: /path/to/PLAN_S05_login.md
+🚀 Output: [summary do executor]
+
+Status:
+  ✅ PRD valid
+  ✅ Ambiguidades resolvidas (2 decisões coletadas)
+  ✅ Plano generated
+  ✅ Executor output ready (required in full/direct)
+  ⏭️  Slice review: not executed
+```
+
+### Direct pipeline com PRD existente + review
+
+```
+/workflow direct prd "/path/to/PRD_S05.md" --review
+```
+
+### Entrevista de brainstorm
+
+```
+/workflow interview-only brainstorm "Que tal dark mode?"
+```
+
+### Force entrevista mesmo sem ambiguidades
+
+```
+/workflow full idea "melhorar performance" --interview
+```
+
+## Como funciona
+
+### Full Mode
+
+```
+1. Parse input (resolve sprint/indicação)
+   ↓
+2. Generate PRD (`atlas-sprint-prd-generator`)
+   ↓
+3. Validate PRD (busca TBD, "a confirmar", gaps)
+   ↓
+4. Interview (automático se ambiguidades OU --interview)
+   └─ Atualiza PRD com decisões coletadas
+   ↓
+5. Plan (`atlas-plan-handoff`)
+   ↓
+6. Validate Plan (tem gaps?)
+   └─ Pergunta: volta? continua TBD? adia?
+   ↓
+7. Execute obrigatório em `full` (`atlas-plan-execute`, com `atlas-task-validator` sub-agent)
+   ↓
+8. Review (se --review)
+   └─ `atlas-slice-review`
+   ↓
+9. Output (resumo + próximos passos)
+```
+
+### Direct Mode
+
+```
+1. Parse/Generate PRD
+   ↓
+2. Validate PRD + Interview (condicional)
+   ↓
+3. Execute (`atlas-direct-execute`, mantendo `phase: plan_execute`)
+   ↓
+4. Review (se --review)
+   ↓
+5. Output
+```
+
+### Interview-Only Mode
+
+```
+1. Cria draft mínimo pelo `PRD_TEMPLATE.md` quando a entrada é brainstorm
+   ↓
+2. Entrevista `atlas-prd-interview` com `prd_path` válido
+   ↓
+3. Output (PRD esboço + decisões)
+```
+
+## Sequências canônicas
+
+Atlas é família única. Cliente (Claude Code, Cursor, Codex App) é apenas o host que executa as skills; não existe roteamento por família.
+
+| Mode | Sequência |
+|------|-----------|
+| `full` | `atlas-sprint-prd-generator` → `atlas-prd-interview` quando necessário → `atlas-plan-handoff` → `atlas-plan-execute` → `atlas-task-validator` → `atlas-findings-repair` (no `fail`) → `atlas-slice-review` somente com `--review` |
+| `direct` | PRD/spec existente → `atlas-direct-execute` → `atlas-task-validator` → `atlas-findings-repair` (no `fail`) → `atlas-slice-review` somente com `--review` |
+| `interview-only` | draft PRD mínimo (se brainstorm) → `atlas-prd-interview` |
+
+## Validação automática
+
+Plugin detecta ambiguidades em:
+- **Contexto e objetivo (§1):** TBD, "a confirmar", vago
+- **Escopo (§2):** incompleto, "depende de"
+- **Decisões (§3):** vazio ou muito vago
+- **Fluxos e cenários UX (§4):** gaps, "a definir"
+- **Contrato funcional e invariantes (§5):** "ainda não definido", "mock"
+
+Se encontra ambiguidades → o orquestrador conduz `atlas-prd-interview` automaticamente no fio principal.
+
+## Lógica de decisão
+
+Quando há decisões pendentes:
+
+```
+Plugin: Tenho decisões em aberto:
+  Q-XXX-01: [decisão 1]
+  Q-XXX-02: [decisão 2]
+
+Opções:
+  A) Volta pra resolver tudo (roda interview agora)
+  B) Continua com recomendações (marca TBD)
+  C) Adia essas decisões
+```
+
+Você escolhe A/B/C → pipeline continua conforme.
+
+## Integração com seu workflow
+
+### Antes de rodar workflow
+
+1. Opcional: criar backlog mestre explicitamente com `$atlas-backlog-generator`
+2. Preenchimento de `PERGUNTAS_EM_ABERTO.md` (fora do plugin)
+3. Resolver perguntas abertas fora do pipeline (se necessário)
+
+### Ao rodar workflow
+
+```
+/workflow full backlog-item "S05"
+```
+
+Plugin automatiza tudo. Você valida output.
+
+### Depois de workflow
+
+1. Validação de output do executor
+2. (Opcional) Rodada de slice-review quando `--review` foi solicitado
+3. Avança para S06
+
+## Skills envolvidas
+
+| Skill | Função |
+|-------|--------|
+| `atlas-backlog-generator` | Cria backlog mestre a partir de ideia, prompt, conversa ou briefing; uso preparatório explícito, fora da cadeia automática |
+| `atlas-sprint-prd-generator` | Gera PRD a partir de sprint/indicação |
+| `atlas-prd-interview` | Entrevista de PRD (resolve ambiguidades) |
+| `atlas-plan-handoff` | Cria plano executável |
+| `atlas-plan-execute` | Executa plano (com `atlas-task-validator` sub-agent) |
+| `atlas-slice-review` | Review fria de implementação quando `--review` está presente |
+
+## Configuração
+
+Plugin usa configuração embutida no MCP para modos, skills `atlas-*` e validadores de ambiguidade. Defaults auxiliares continuam empacotados em `packages/orchestrator/defaults/` e referências em `packages/orchestrator/references/`.
+
+## Error handling
+
+- **Sprint não encontrado:** reporta sprints disponíveis
+- **Skill falha:** para, reporta erro, oferece retry/skip/abort
+- **PRD inválido:** reporta sections faltando
+- **Ambiguidades não resolvidas:** pergunta próximos passos
+
+## Dúvidas?
+
+Veja este README, `packages/mcp-server/README.md` e os SKILL.md `atlas-*` para o contrato operacional atual.
+
+---
+
+**Plugin version:** 0.9.3
+**Author:** Paulo Borini
+**Last updated:** 2026-06-16
+
+### Novidades v0.8.4 — liveness do executor (Gate G12)
+
+- `plan_execute` agora tem liveness explícito: `atlas_lock_dispatch(start)` cria deadline de bootstrap e o executor precisa emitir checkpoints materiais.
+- `atlas-plan-execute` deve reportar `executor_started`, `skill_loaded`, `plan_loaded`, `handoff_accepted`, `task_started`, `first_write` e `state_path_created` conforme avança.
+- Se o sub-agent não retornar/progredir, o orquestrador consulta `atlas_lock_dispatch(status)`; bootstrap vencido vira `executor_bootstrap_timeout`, checkpoint antigo sem avanço vira `executor_progress_timeout`; ambos persistem `stalled`, liberam retry e não podem ser tratados como execução em andamento.
+- `atlas_lock_validator(start)` só abre o validator depois de `state_path_created` para o mesmo `state_path`; checkpoint final sem arquivo legível é bloqueado.
+
+### Novidades v0.8.2 — release/npm e procedimento de bump
+
+- Pacote npm `atlas-workflow` validado como instalador multi-host (`npm pack`, `npm exec` do tarball e `.npmignore` restritivo).
+- CI de release publica npm com provenance e GitHub Release somente por tag `vX.Y.Z`, com guard de tag = `VERSION` = `package.json.version`.
+- Procedimento de patch/bump documenta o fluxo completo para IA: classificar mudança, atualizar versões, regenerar catálogos, validar CI local, checar pacote npm, taguear e verificar publicação.
+
+### Novidades v0.8.0 — proof-of-work do validador frio (Gate G4, R20)
+
+- `atlas_lock_validator(start)` emite um `challenge` (sha256 de um arquivo do boundary do `state_path`); o validador irmão lê via `validator_recovery.challenge`, computa o hash e devolve em `challenge_response`.
+- `atlas_lock_validator(complete)` recomputa o hash do disco e bloqueia (`challenge_failed`) em divergência/ausência, sem fechar o slot — re-despacho do mesmo validador. O re-dispatch é **bounded** por attempt: esgotado o teto, o slot fecha terminal (`challenge_exhausted`, fail-closed).
+- O hash esperado nunca é persistido em estado legível (recomputado on-demand). Best-effort: boundary sem arquivo legível → sem enforcement; arquivo ausente no complete → `unverifiable`, não bloqueia.
+- Escopo honesto: atestação **mecânica** de leitura do boundary, **não** prova de isolamento não-forjável. Schema `atlas_capabilities` v5 intacto.
+
+### Novidades v0.7.1 / v0.7.2 — confiabilidade
+
+- `ping().capabilities` derivado de `toolsList()` (fonte única — fim do drift que omitia `atlas_classify_input`); CI job `cross-os` (Windows/macOS); `.gitattributes` para artefatos gerados.
+- `atlas_run_state(upsert)` faz merge top-level (não derruba `dispatch.active`); `findActiveRunConflict` só bloqueia conflito de lock real; `atlas_verify_artifact` aceita `artifact_kind`; Gate G4 endurecido (R17 falha de dispatch = `blocked`; R19 proveniência do `dispatch_token`).
+
+### Novidades v0.7.0 — topologia sibling-only
+
+- Validação fria é sempre sub-agent irmão em todos os hosts: o executor escreve `state_path` e encerra; o orquestrador despacha `atlas-task-validator`. Gate JOIN no preflight, `dispatch_token` monotônico, máximo de 2 validators por contrato. `CAPABILITIES_SCHEMA_VERSION` v3 → v5 (BREAKING de contrato, sem mudança de comportamento).
+
+### Novidades v0.6.2 — backlog mestre explícito
+
+- `atlas-backlog-generator` cria backlog mestre a partir de ideia, prompt ou conversa somente quando acionado explicitamente.
+- O backlog padrão vai para `.atlas/backlog/BACKLOG_MESTRE_<slug>.md` quando o usuário não informa path.
+- `BACKLOG_MESTRE_TEMPLATE.md` inclui MoSCoW, esforço x ganho, dependências, riscos e próxima sprint executável.
+- A cadeia automática do workflow permanece começando no PRD; backlog é preparação documental opcional.
+
+### Novidades v0.6.1 — fronteira documental no orquestrador
+
+- Fases documentais (`PRD`, entrevista, `PLAN_*.md`) são conduzidas no orquestrador; o primeiro sub-agent obrigatório do `full` nasce em `atlas-plan-execute`.
+- Os únicos sub-agents do pipeline são `atlas-plan-execute`/`atlas-direct-execute`, `atlas-task-validator`, `atlas-findings-repair` e `atlas-slice-review`.
+- A topologia é **sibling** em todos os hosts: o orquestrador coordena o validator irmão a partir do `state_path` retornado pelo executor e só reabre execução em `fail`. Host sem join síncrono é rejeitado no preflight (gate JOIN).
+- `atlas_preflight`/dispatchability distinguem skills documentais de skills executoras, evitando exigir sub-agent para entrevista/plano.

package/hosts/zcode/packages/orchestrator/commands/workflow.md

@@ -0,0 +1,37 @@
+---
+description: Orquestra pipeline de desenvolvimento de feature no Atlas (PRD → validação → entrevista → plano → execução → review)
+argument-hint: <mode> <input-type> [input] [--interview] [--review] [--help]
+---
+
+Você está executando o comando `/workflow` do plugin **atlas-workflow-orchestrator**.
+
+Argumentos recebidos: `$ARGUMENTS`
+
+## Ação
+
+1. Invoque a skill **`atlas-workflow-orchestrator`** passando os argumentos acima como input.
+2. A skill é dona de toda a lógica: parsing de `<mode> <input-type> [input] [flags]`, orquestração das sub-skills, validação de ambiguidades, resolução de decisão em aberto via entrevista (não para o pipeline) e formato de output. Siga o `SKILL.md` dela como contrato.
+3. Se `$ARGUMENTS` estiver vazio ou contiver `--help`, mostre a sintaxe completa da skill e pare.
+
+## Referência rápida de sintaxe
+
+```
+/workflow <mode> <input-type> [input] [flags]
+```
+
+- **mode**: `full` · `direct` · `execute` · `interview-only`
+- **input-type**: `backlog-item` · `idea` · `prd` · `plan` · `brainstorm`
+- **flags**: `--interview` · `--review` · `--help`
+
+Exemplos:
+
+```
+/workflow full backlog-item "S05"
+/workflow direct prd "/path/PRD_S05.md" --review
+/workflow execute plan "/path/PLAN_S05.md"
+/workflow interview-only brainstorm "que tal dark mode?"
+```
+
+Não improvise comportamento fora do `SKILL.md`. **Pipeline é fire-and-continue**: uma vez iniciado, avança fase a fase sem pedir permissão entre gates; só para em gate duro `blocked` ou blockage de ambiente real (ver "Princípio de continuação automática"). Nunca invente "Modo Discussão" ou peça "quer que eu gere/continue?". Decisão em aberto não para — dispara entrevista, propaga e segue. Em caso de erro real, siga "Error handling".
+
+**Gates duros (v0.3):** o pipeline é orientado a artefato e MCP. Antes de iniciar, rode a **Fase 0 (Pré-flight)** com `atlas_ping` e `atlas_preflight`; use ids `atlas-*`; garanta que cada sub-agent carregue o `SKILL.md` real antes de agir. Se MCP não responder, resultado exigido estiver ausente ou status for bloqueante, **aborte; nunca use fallback narrativo**. Respeite os Gates G1–G11 + TC da SKILL: `atlas_verify_artifact` antes de avançar (G1); em `full`, nenhum código antes de `PLAN_*.md` validado (G2); skills invocadas de verdade (G3); validador frio como sub-agent separado (G4); `atlas_scan_prd` determinístico e logado (G5); status verificado contra disco e MCP (G6); execução/review como sub-agents reais com `atlas_lock_dispatch`, enquanto PRD/entrevista/plano são autoria documental no pai (G7/G8); orquestrador de mãos atadas e dispatch blocking (G9); família única atlas-* via `atlas_preflight` (G10); em `full`, `atlas_assert_after_plan` exige `atlas-plan-execute` após plano (G11); `direct` usa `atlas-direct-execute`; ambos mantêm `phase: plan_execute`; PRD/PLAN exigem `atlas_verify_template_conformance` passed com `pending_count: 0` (TC). Em `interview-only brainstorm`, crie draft mínimo pelo template antes de invocar `atlas-prd-interview` com `prd_path` válido.

package/hosts/zcode/packages/orchestrator/defaults/paths.md

@@ -0,0 +1,21 @@
+# Defaults de paths
+
+Estes defaults viajam no pacote do plugin. O workflow não exige arquivo de configuração na raiz do repositório usuário.
+
+## Config
+
+1. Usar a configuração embutida no MCP do plugin.
+2. Usar `defaults/` e `references/` empacotados no plugin.
+3. Só considerar arquivos equivalentes no workspace quando o usuário apontar explicitamente.
+
+## Artefatos
+
+| Artefato | Default |
+|----------|---------|
+| PRD | path informado pelo usuário; senão diretório do backlog/template encontrado pela skill geradora |
+| PLAN | mesmo diretório do PRD, salvo se a skill de handoff resolver path mais específico |
+| Evidência de execução | relatório emitido pelo executor + diff real do workspace |
+
+## Regra
+
+Path específico de produto/repo nunca é obrigatório no orquestrador. Skills de PRD/plano podem descobrir templates/backlog no workspace, mas ausência de layout específico não autoriza implementação inline.

package/hosts/zcode/packages/orchestrator/references/host-adapters.md

@@ -0,0 +1,106 @@
+# Adapters de host
+
+Fonte canônica do conhecimento host-específico do Atlas. As skills são host-agnósticas: em runtime devem consultar a tool MCP `atlas_capabilities` e usar o descritor retornado. Este documento é a referência estática equivalente (e o que o `atlas_capabilities` materializa em código no MCP server).
+
+## Por que existe
+
+Tools nativas do cliente (`Agent()`, `TodoWrite`, `tasks`, `$skill`) vivem no host, não no MCP. O servidor não consegue chamá-las nem fazer proxy — só **descrever** qual usar. Por isso o adapter é descritivo: centraliza o "qual verbo usar por host" num único lugar (código + este doc), eliminando prosa duplicada espalhada pelas skills.
+
+## Fonte de verdade
+
+1. **Runtime:** `atlas_capabilities` (MCP) — detecta host por env e retorna o descritor. Preferir sempre.
+2. **Estático:** esta tabela — fallback de leitura/documentação quando o MCP não está disponível.
+
+Os dois devem permanecer consistentes. O descritor em código vive em `packages/mcp-server/server.js` (`HOST_ADAPTERS`). ZCode usa o mesmo formato de agentes que Claude (`.md` com frontmatter) por ser Claude Agent SDK compat.
+
+## Detecção de host
+
+| Sinal | Host |
+|-------|------|
+| arg `host` explícito na chamada | o valor passado |
+| env `ATLAS_HOST` | o valor da env |
+| env `CLAUDE_PLUGIN_ROOT` presente | `claude` |
+| env `CODEX_HOME` / `CODEX_PLUGIN_ROOT` | `codex` |
+| env `ZCODE_PLUGIN_ROOT` (injetado pelo `.zcode-plugin` do host) | `zcode` |
+| env `ATLAS_HOST=opencode` (injetado por `opencode.json`) | `opencode` |
+| env `ATLAS_HOST=pi` (injetado pela config do `pi-mcp-adapter`) | `pi` |
+| env `ATLAS_HOST=antigravity` (injetado por `mcp_config.json`) | `antigravity` |
+| nenhum | `generic` |
+
+## Matriz de adapters
+
+| Concern | `claude` (Claude Code) | `codex` (Codex App) | `opencode` | `pi` (pi cli) | `antigravity` (Gemini) | `zcode` (ZCode) | `generic` |
+|---------|------------------------|---------------------|------------|---------------|------------------------|-----------|-----------|
+| Disparo de subagente | `Agent(subagent_type: "<name>", prompt: "<state_path>")` | `spawn_agent(agent_type: "<name>", items: [{ type: "text", text: "<state_path>" }])` | `@<name>` (ou auto) com `<state_path>` | tool `subagent({ agent: "<name>", task: "<state_path>", context: "fresh" })` (pi-subagents) | `define_subagent` + `invoke_subagent` com `<state_path>` | `Agent(subagent_type: "<name>", prompt: "<state_path>")` | subagente nativo do host, passando só `<state_path>` |
+| Registro do subagente | `agents/<name>.md` na raiz do plugin | `CODEX_HOME/agents/<name>.toml` via `init codex` (`.codex/agents/` no bundle é fonte gerada; custom agent nativo; `developer_instructions` carrega o `SKILL.md`; `atlas-task-validator` pinado em `model="gpt-5.4"` + `model_reasoning_effort="high"`) | `.opencode/agents/<name>.md` (`mode: subagent`) | `.pi/agents/<name>.md` (pi-subagents; frontmatter `name`+`description`+`tools`; **`SKILL.md` canônico embutido no corpo** porque o pi não tem skill loader no sub-agente — fonte única segue `packages/skills/<name>/SKILL.md`, agente é cópia gerada por `build/gen-host-agent.mjs`) | dinâmico via `define_subagent` da skill do orquestrador | `agents/<name>.md` na raiz do plugin (.zcode-plugin) — mesmo formato claude (Claude Agent SDK) | mecanismo nativo equivalente |
+| Topologia do validador frio (G4) | **`sibling`** | **`sibling`** | **`sibling`** | **`sibling`** | **`sibling`** | **`sibling`** | **`sibling`** |
+| Join síncrono (gate JOIN) | `self_evident` (`Agent()` bloqueante) | `self_evident` (confirmado em produção) | `self_evident` (`@<name>` bloqueante) | `must_report` (depende de `pi-subagents`; hard-fail sem report) | `self_evident` (`invoke_subagent` bloqueante) | `self_evident` (`Agent()` bloqueante; Claude Agent SDK) | `must_report` (indeterminado; hard-fail sem report) |
+| Todo nativo | `TodoWrite` | `tasks` | `todowrite` | nenhum (segue sem mirror) | nenhum (segue sem mirror) | `TodoWrite` | nenhum (segue sem mirror) |
+| Config MCP | `plugin.json` `mcpServers` | `.mcp.json` | `opencode.json` `mcp.<name>` (`type:"local"`, `environment.ATLAS_HOST=opencode`) | `.mcp.json` no root (`pi-mcp-adapter`; `env.ATLAS_HOST=pi`; tools chegam proxiadas/prefixadas `atlas_workflow_<tool>`) | `mcp_config.json` (`env.ATLAS_HOST=antigravity`) | `.zcode-plugin/plugin.json` `mcpServers` (stdio; `ZCODE_PLUGIN_ROOT` injetado pelo host) | host MCP-capaz |
+| Deps externas obrigatórias | — | — | — | **`pi-mcp-adapter` + `pi-subagents`** (DEC-005) | — | — | — |
+| Estado de run | `atlas_run_state` (MCP) | `atlas_run_state` (MCP) | `atlas_run_state` (MCP) | `atlas_run_state` (MCP) | `atlas_run_state` (MCP) | `atlas_run_state` (MCP) |
+| Escrita de plano | `.atlas/plans/` | `.atlas/plans/` | `.atlas/plans/` | `.atlas/plans/` | `.atlas/plans/` | `.atlas/plans/` |
+| Leitura de plano (ordem) | `.atlas/plans/` → `.cursor/plans/` → `.codex/plans/` | idem | idem | idem | idem | idem |
+
+`.cursor/plans/` e `.codex/plans/` são lidos com deprecation warning por 1 release; escrita só em `.atlas/plans/`. **opencode** instala via `.opencode/` + `opencode.json` (`hosts/opencode/`). **pi** instala via `mcp.json` + `agents/` + `skills/` (`hosts/pi/`) e exige as 2 deps obrigatórias; sem qualquer uma o preflight aborta (gate PREREQ).
+
+## Contrato `atlas_capabilities` (schema v5)
+
+Campos retornados (DEC-007):
+
+| Campo | Tipo | Significado |
+|---|---|---|
+| `host` / `host_label` / `detected_via` | string | host detectado e como |
+| `schema_version` | int | versão do contrato (atual: **5**) |
+| `subagent_dispatch` | obj | `{mechanism, example, registration}` — verbo nativo de dispatch |
+| `validator_dispatch` | obj | `{dispatcher: 'orchestrator', required_agent_type, join: {sync, confidence, mechanism}}` — topologia é sempre sibling; `join` declara a capability de join síncrono usada pelo gate JOIN. No Codex, `required_agent_type` é `atlas-task-validator` e o registro nativo deve estar pinado em `model="gpt-5.4"` + `model_reasoning_effort="high"` |
+| `todo_tool` | string\|null | tool de todo nativa; `null` = seguir sem mirror (não-essencial) |
+| `hooks` | obj | `{supported, mechanism}` — suporte a hooks pré/pós tool |
+| `capabilities_flags` | obj | `{subagent_available, mcp_available, todo_available}` |
+| `prerequisites` | obj | `{essential:[…], non_essential:[…]}` — quais flags são hard-fail |
+| `plan_paths` / `state_backend` / `state_dir` | — | **portáveis** (iguais em todo host) |
+| `known_hosts` | string[] | hosts registrados em `HOST_ADAPTERS` |
+
+### Política de versionamento (`schema_version`)
+
+- **Aditivo** (campo novo opcional) → mantém compat; consumidores **devem ignorar campos desconhecidos**. (v1→v2 foi aditivo: `capabilities_flags`, `hooks`, `prerequisites`.)
+- **Remoção/renomeação/mudança de semântica** → bump + nota de migração + revisão das skills consumidoras.
+
+### Pré-requisitos de determinismo (DEC-004)
+
+`prerequisites.essential` (`subagent_available`, `mcp_available`) são **hard-fail**: host sem qualquer um é rejeitado no preflight, qualquer tamanho de tarefa, sem degradação/inline. `prerequisites.non_essential` (`todo_available`) apenas segue sem o recurso, registrando. O executor consome esse contrato no preflight (S09).
+
+**Gate `PREREQ` no `atlas_preflight`:** é a **primeira** verificação (precede versão/lock/modo). Mescla as flags do perfil do host com a disponibilidade real reportada em `host_capabilities` (override). Ex.: pi sem `pi-mcp-adapter`/`pi-subagents` → o adapter reporta `{"subagent_available":false}` → `status:"blocked"`, `gate:"PREREQ"`, `missing_prerequisites:[…]`, `next_action` acionável. Host qualificado passa direto para o gate G10. Nunca há fallback inline.
+
+### Transporte (S05 — spike, DEC-006)
+
+**stdio único.** Confirmado pelo survey S01: opencode usa `type:"local"` (stdio) e o `pi-mcp-adapter` suporta stdio (com fallback HTTP interno do próprio adapter, transparente ao Atlas). Nenhum host-alvo (claude/codex/cursor/opencode/pi/generic) exige HTTP/SSE no MCP do Atlas. Não há abstração de transporte (YAGNI). Ponto de extensão: se um host futuro exigir HTTP/SSE, o boot fica isolado em `startStdioLoop()` (`server.js`) — trocar/adicionar transporte é localizado, sem tocar a lógica de tools/gates.
+
+### Fronteira portável vs host-específico
+
+- **Portável (vive no MCP, igual a todo host):** `plan_paths`, `state_backend`, `state_dir`, gates G1–G11, schema de state. Nunca depende de host.
+- **Host-específico (vive em `HOST_ADAPTERS` + packaging):** `subagent_dispatch`, `todo_tool`, `hooks`, `capabilities_flags`. Variação resolvida por dado, não por ramo de código.
+
+## Como uma skill consome
+
+1. Chamar `atlas_capabilities` (sem args para autodetecção, ou `{host}` para forçar).
+2. Ler `subagent_dispatch.mechanism` / `.example`, `todo_tool`, `plan_paths`.
+3. Executar o verbo nativo correspondente. Nunca hardcodar o nome do host na prosa da skill. No Codex, `$<skill>` é ativação de skill in-context; execução/review usa custom agent nativo via `spawn_agent`. Para o validador frio no Codex, o orquestrador deve despachar explicitamente `spawn_agent(agent_type: "atlas-task-validator", items: [{ type: "text", text: "<state_path>" }])`; se esse agent type não estiver disponível, bloquear fail-closed em vez de usar `default`, `$atlas-task-validator` ou validação inline.
+4. Se `todo_tool` for `null`, seguir sem mirror de todo (não inventar tool).
+
+## Adicionar um host novo
+
+1. Adicionar entrada em `HOST_ADAPTERS` (`packages/mcp-server/server.js`).
+2. Adicionar regra de detecção em `detectHost` se houver env próprio.
+3. Adicionar linha na matriz de adapters.
+4. Registrar o subagente no formato nativo do host (ex.: `agents/<name>.md` ou equivalente). ZCode reusa o formato Claude (`agents/<name>.md`) — mesmo formato, sem geração extra.
+
+Sem tocar nas skills — elas já consomem o descritor.
+
+## Perfil `generic` (DEC-004)
+
+`generic` é o fallback para qualquer host MCP-capaz **com subagente nativo**. Não tem packaging próprio (não há bundle `generic`): o host usa seu mecanismo nativo de subagente + a config MCP do próprio host. O perfil **exige** subagente + MCP — `capabilities_flags {subagent:true, mcp:true}`. Host MCP-only **sem** subagente nativo fica **fora de escopo**: reportando `subagent_available:false` no preflight, o gate PREREQ aborta (não há degradação nem cold-review inline). Determinismo > alcance.
+
+## Status multi-host
+
+Todos os hosts-alvo do survey S01 estão implementados na matriz acima: `claude`, `codex`, `cursor` (carona no manifest claude), `opencode` (S06), `pi` (S07), `zcode` (Claude Agent SDK compat) e `generic`. Nenhum exige HTTP/SSE → stdio único (DEC-006/S05). Survey completo + fontes: `PRD_S01_host_survey.md`.

package/hosts/zcode/packages/orchestrator/references/qa_s13_matrix.md

@@ -0,0 +1,141 @@
+# S13 QA Matrix Evidence
+
+Status: NO-GO for S14
+Date: 2026-06-01
+Scope: PRD_S13_qa_matrix.md
+
+## Summary
+
+S13 executed host/plugin readiness smokes and found two blocking packaging issues before the full functional matrix could be executed:
+
+- Codex plugin install failed because `plugin.json` pointed `skills` to a non-existent contract path and inlined `mcpServers`.
+- Codex MCP startup failed because the MCP server emitted `Content-Length` framed responses while Codex RMCP expects newline-delimited JSON-RPC.
+
+Both issues were repaired in S13. After repair, Claude, Cursor and Codex host/plugin smokes passed.
+
+Continuation evidence found one more host-specific packaging issue:
+
+- Claude/Cursor plugin loaded from the packaged zip did not expose the bundled MCP server. The plugin had to be unpacked and the Claude manifest had to reference the MCP server with `${CLAUDE_PLUGIN_ROOT}/packages/mcp-server/server.js`.
+- Codex CLI usage limit later reset. The installed plugin initially did not expose Atlas MCP because the Codex `.mcp.json` launched the server from the consumer workspace. Adding `cwd: "."` to the packaged Codex MCP config made installed-plugin MCP autoexposure work.
+- A Codex full run then exposed a state-root mismatch: `cwd: "."` made state land in the plugin cache. The MCP stateful tools now accept `project_root`, preserving portable plugin startup while writing ledger and resolving relative artifacts against the consumer workspace.
+
+The full functional matrix is not green yet. Full/direct/interview-only runs and positive/negative cases per host still require real manual execution with run evidence. S14 remains blocked until that matrix is executed or a product decision explicitly accepts the remaining risk.
+
+## Environment
+
+| Host | Binary | Version/status |
+|---|---|---|
+| Claude Code | `/Users/pauloborini/.local/bin/claude` | `2.1.159 (Claude Code)` |
+| Cursor Agent | `/usr/local/bin/cursor agent` | logged in as `dev2@zavii.com.br` |
+| Codex CLI | `/Applications/Codex.app/Contents/Resources/codex` | `codex-cli 0.135.0-alpha.1` |
+
+## Complete Matrix Catalog
+
+Legend: this table is the complete required coverage catalog. Values other than `PENDING` summarize real functional evidence from `S13-F*`; the detailed run evidence remains below.
+
+| Host | Mode | Backlog item | Existing PRD | Idea | Brainstorm |
+|---|---|---:|---:|---:|---:|
+| Claude | full | PENDING | FAIL / timeout (`S13-F04`) | PENDING | PENDING |
+| Claude | direct | PENDING | PASS + expected block (`S13-F01`, `S13-F02`) | PENDING | PENDING |
+| Claude | interview-only | PENDING | PENDING | PENDING | PENDING |
+| Cursor | full | PENDING | PENDING | PENDING | PENDING |
+| Cursor | direct | PENDING | PENDING | PENDING | PENDING |
+| Cursor | interview-only | PENDING | PENDING | PENDING | PARTIAL (`S13-F03`) |
+| Codex | full | PENDING | PASS (`S13-F07`) | PENDING | PENDING |
+| Codex | direct | PENDING | PENDING | PENDING | PENDING |
+| Codex | interview-only | PENDING | PENDING | PENDING | PASS MCP gates / no implementation (`S13-F05`, `S13-F06`) |
+
+## Executed Readiness Evidence
+
+| ID | Host | Command class | Result | Evidence |
+|---|---|---|---|---|
+| S13-R01 | Claude | bare CLI | PASS | `CLAUDE_BARE_OK` |
+| S13-R02 | Claude | plugin smoke | PASS | `CLAUDE_PLUGIN_OK` |
+| S13-R03 | Cursor | bare CLI | PASS | `CURSOR_BARE_OK` |
+| S13-R04 | Cursor | plugin smoke, text output | OBSERVATION | no output after 90s; process killed |
+| S13-R05 | Cursor | plugin smoke, `stream-json` | PASS | session `c523fc93-192a-4e27-8473-48b88498ace6`, result `CURSOR_PLUGIN_STREAM_OK` |
+| S13-R06 | Codex | bare CLI | PASS | session `019e8155-39d7-79e0-88fa-d27023a2c906`, result `CODEX_BARE_OK` |
+| S13-R07 | Codex | plugin install before repair | FAIL | `missing or invalid plugin.json` |
+| S13-R08 | Codex | plugin install after repair | PASS | cache path under `.codex/plugins/cache/atlas-s13/.../0.2.0-dev` |
+| S13-R09 | Codex | plugin smoke after install | PASS | session `019e815e-e821-7b42-9805-b1b725cc2a43`, result `CODEX_PLUGIN_OK_3` |
+| S13-R10 | Claude | plugin MCP from zip | FAIL | `MCP_NOT_AVAILABLE` |
+| S13-R11 | Claude | plugin MCP from unpacked dir after path repair | PASS | `atlas_ping` returned `status: alive`, `version: 0.2.0-dev`, 9 capabilities |
+| S13-R12 | Codex | MCP via explicit `mcp_servers.*` config + approval bypass | PASS | session `019e8350-13cf-7a01-b5b6-7edac9ac8269`; `atlas_ping` returned `status: alive`, `version: 0.2.0-dev`, 9 capabilities |
+| S13-R13 | Codex | installed plugin MCP autoexposure before `cwd` repair | FAIL | session `019e8350-b437-7e33-bbe0-51f3139dc1a8`; `tool_search` found 0 Atlas tools, MCP resources/templates empty |
+| S13-R14 | Codex | installed plugin MCP autoexposure after `cwd: "."` repair | PASS | session `019e8358-5be8-7d03-abe1-0dba0773b004`; `atlas_ping` returned `status: alive`, `version: 0.2.0-dev`, 9 capabilities |
+| S13-R15 | Codex | installed plugin full run with explicit `project_root` | PASS | session `019e8365-4e3b-7042-a1d6-abbe05e45f77`; final `CODEX_FULL_POSITIVE_PROJECT_ROOT_OK`; ledger created under the consumer workspace state directory |
+
+## Repairs Applied
+
+| Finding | Severity | Repair |
+|---|---:|---|
+| Codex plugin manifest used invalid install contract | P1 | `plugin-manifests/codex/plugin.json` now points `skills` to `./skills/` and `mcpServers` to `./.mcp.json`; build creates both. |
+| Codex MCP could not parse server responses | P1 | `packages/mcp-server/server.js` now emits newline-delimited JSON-RPC responses. Input parser accepts newline-delimited requests plus `Content-Length` frames with CRLF or LF-only headers. |
+| Claude/Cursor plugin did not expose MCP from packaged path | P1 | `plugin-manifests/claude/plugin.json` now resolves the MCP server through `${CLAUDE_PLUGIN_ROOT}/packages/mcp-server/server.js`. |
+| Codex installed plugin did not expose bundled MCP from consumer workspace | P1 | `build/build-plugins.sh` now emits `.mcp.json` with `cwd: "."`, so Codex launches `packages/mcp-server/server.js` relative to the installed plugin root. |
+| Codex installed plugin wrote ledger to plugin cache after `cwd: "."` | P1 | Stateful MCP tools now accept optional `project_root`; Codex host runs can keep portable MCP startup and still write state in the consumer workspace. |
+
+## Functional Matrix Evidence
+
+| ID | Host | Mode | Input type | Result | Evidence |
+|---|---|---|---|---|---|
+| S13-F01 | Claude | direct | existing PRD | PASS | `run_id=atlas-s13-qa-20260601`; state ledger present; `qa-output.txt` contains `QA_OK`; G10/G1/G5/template_conformance passed |
+| S13-F02 | Claude | direct | ambiguous PRD | PASS expected block | `run_id=run-s13-qa-20260601-001`; state ledger present; G5 blocked with 7 ambiguity matches; template_conformance blocked with 4 pendencies; no requested implementation executed |
+| S13-F03 | Cursor | interview-only | brainstorm | PARTIAL | Legacy v0.2 evidence; family lock tool removed in v0.3; final status `interview_completed_recommendations`; user confirmation still pending |
+| S13-F04 | Claude | full | existing PRD | FAIL / timeout | no output after 4 minutes; process killed; no completed full ledger |
+| S13-F05 | Codex | interview-only | brainstorm | BLOCKED host dependency | initial Codex CLI returned usage limit: `try again at 5:39 AM`; no functional Codex run executed |
+| S13-F06 | Codex | interview-only | brainstorm | PASS MCP gates / no implementation | Legacy v0.2 evidence; family lock tool removed in v0.3; implementation_performed `false` |
+| S13-F07 | Codex | full | existing PRD | PASS | session `019e8365-4e3b-7042-a1d6-abbe05e45f77`; final `CODEX_FULL_POSITIVE_PROJECT_ROOT_OK`; `run_id=atlas-s13-codex-full-positive-project-root-20260601`; state ledger present; `qa-output.txt` is exactly 5 bytes `QA_OK`; G10/G1/G5/template_conformance/G7/G11 expected block/G8 passed |
+
+## Direct MCP Contract Probes
+
+These probes exercise the MCP contract directly. They are not substitutes for host-level functional QA.
+
+| ID | Scope | Result | Evidence |
+|---|---|---|---|
+| S13-MCP-FULL-01 | full flow gate sequence | PASS contract / not host QA | fresh workspace `/private/tmp/atlas-s13-full-probe-clean2`; `run_id=atlas-s13-full-mcp-probe-clean2-20260601`; `atlas_preflight`, PRD G1/G5/template_conformance, PLAN G1/template_conformance, `atlas_lock_dispatch` plan_handoff start/complete, `atlas_assert_after_plan` expected block for `completed_without_execute`, and plan_execute start/complete with validator `passed` all returned expected statuses |
+
+## Checks
+
+| Check | Result |
+|---|---|
+| `node --check packages/mcp-server/server.js` | PASS |
+| MCP newline initialize probe | PASS |
+| MCP `Content-Length` initialize probe with CRLF header | PASS |
+| MCP `Content-Length` initialize probe with LF-only header | PASS |
+| `build/build-plugins.sh` | PASS |
+| `unzip -t dist/atlas-workflow-codex.plugin` | PASS |
+| Claude plugin smoke | PASS |
+| Cursor plugin smoke via `stream-json` | PASS |
+| Codex plugin install + smoke | PASS |
+| Claude unpacked plugin MCP ping | PASS |
+| Claude direct positive workflow with MCP ledger | PASS |
+| Claude direct ambiguous workflow with expected MCP block | PASS |
+| Cursor interview-only workflow with MCP ledger | PARTIAL |
+| Claude full workflow | FAIL / timeout |
+| Codex functional workflow | PARTIAL / full matrix incomplete |
+| Codex explicit MCP config `atlas_ping` with approval bypass | PASS |
+| Codex installed plugin MCP autoexposure | PASS |
+| Codex installed plugin interview-only MCP gates | PASS |
+| Codex installed plugin full workflow with `project_root` ledger | PASS |
+| Direct MCP full gate sequence | PASS contract / not host QA |
+
+## Dist Evidence
+
+| Artifact | Evidence |
+|---|---|
+| `dist/atlas-workflow-claude.plugin` | `unzip -p ... .claude-plugin/plugin.json` contains `${CLAUDE_PLUGIN_ROOT}/packages/mcp-server/server.js`; `unzip -l` contains `orchestrator/references/qa_s13_matrix.md`; `unzip -t` passed |
+| `dist/atlas-workflow-codex.plugin` | `unzip -p ... .mcp.json` contains `cwd: "."`; `packages/mcp-server/server.js` accepts `project_root`; `unzip -t` passed; `unzip -l` contains `orchestrator/references/qa_s13_matrix.md` |
+
+## Go/No-Go
+
+NO-GO for S14.
+
+Reason: PRD S13 requires the critical subset to cover at least one positive and one negative path per host and to validate full/direct/interview-only behavior. This run now proves Claude direct positive/negative, Cursor interview-only partial behavior with live MCP evidence, Codex installed-plugin MCP exposure, Codex interview-only MCP gates, and Codex full positive flow, but it still does not prove one positive and one negative functional workflow per host.
+
+Required next action:
+
+1. Re-run full mode with bounded timeout and verify `PLAN_*.md`, `atlas_assert_after_plan`, execution and validator evidence.
+2. Complete Cursor interview with explicit user answer or mark it as intentionally waived by product.
+3. Execute at least one positive and one negative functional workflow run per host.
+4. Reclassify go/no-go only after the critical subset is green or explicitly waived.

package/hosts/zcode/packages/orchestrator/references/subagent_dispatch.md

@@ -0,0 +1,42 @@
+# Despacho de sub-agent
+
+Contrato host-agnóstico para Cursor, Codex e Claude Code.
+
+## Regra central
+
+Cada fase mapeada a um `skill_id` pela configuração embutida do MCP roda em sub-agent foreground, blocking, um por vez.
+
+A primeira ação do sub-agent deve ser carregar o `SKILL.md` completo do `skill_id` resolvido. Depois disso ele executa a skill.
+
+Proibido:
+
+- "aja como `<skill_id>`" sem carregar o `SKILL.md`;
+- copiar resumo da skill para substituir a leitura real;
+- executar plano/código/review no fio do orquestrador.
+
+Equivalente aceito: mecanismo nativo do host que injete a skill completa no sub-agent.
+
+## Codex
+
+No Codex, ativar `$atlas-task-validator` carrega skill no contexto atual, mas **não** cria isolamento frio. Para validação G4, o orquestrador deve chamar explicitamente o custom agent nativo:
+
+```text
+spawn_agent(agent_type: "atlas-task-validator", items: [{ type: "text", text: "<state_path>" }])
+```
+
+O registro ativo desse agent vive em `CODEX_HOME/agents/atlas-task-validator.toml` após `npx github:pauloborini/atlas-workflow init codex`; o bundle mantém `.codex/agents/` como fonte gerada. O arquivo é gerado por `build/gen-host-agent.mjs` com `model = "gpt-5.4"` e `model_reasoning_effort = "high"`. Se o host responder `unknown agent_type`, a fase bloqueia (`blocked`/fail-closed). Proibido fallback para `default`, `$atlas-task-validator`, execução inline ou validação no fio do orquestrador.
+
+## Payload mínimo
+
+- `skill_id`
+- `skill_md_path` ou indicação nativa equivalente da skill
+- `prd_path` / `plan_path` / flags da fase
+- instrução: "primeira ação: carregar a skill completa; segunda ação: executar a skill"
+
+## Descoberta de `SKILL.md`
+
+1. Mecanismo nativo de skills do host.
+2. Diretório local de skills do host.
+3. Workspace, apenas como fallback de descoberta.
+
+Se não encontrar a skill `atlas-*` exigida, abortar. Não trocar por skill nativa ou variante antiga. Não emular inline.